diff --git a/library/alloc/Cargo.toml b/library/alloc/Cargo.toml deleted file mode 100644 index 3960f71681264..0000000000000 --- a/library/alloc/Cargo.toml +++ /dev/null @@ -1,54 +0,0 @@ -[package] -name = "alloc" -version = "0.0.0" -license = "MIT OR Apache-2.0" -repository = "https://github.com/rust-lang/rust.git" -description = "The Rust core allocation and collections library" -autotests = false -autobenches = false -edition = "2021" - -[dependencies] -core = { path = "../core" } -compiler_builtins = { version = "0.1.40", features = ['rustc-dep-of-std'] } - -[dev-dependencies] -rand = { version = "0.8.5", default-features = false, features = ["alloc"] } -rand_xorshift = "0.3.0" - -[[test]] -name = "alloctests" -path = "tests/lib.rs" - -[[bench]] -name = "allocbenches" -path = "benches/lib.rs" -test = true - -[[bench]] -name = "vec_deque_append_bench" -path = "benches/vec_deque_append.rs" -harness = false - -[features] -compiler-builtins-mem = ['compiler_builtins/mem'] -compiler-builtins-c = ["compiler_builtins/c"] -compiler-builtins-no-asm = ["compiler_builtins/no-asm"] -compiler-builtins-mangled-names = ["compiler_builtins/mangled-names"] -compiler-builtins-weak-intrinsics = ["compiler_builtins/weak-intrinsics"] -# Make panics and failed asserts immediately abort without formatting any message -panic_immediate_abort = ["core/panic_immediate_abort"] -# Choose algorithms that are optimized for binary size instead of runtime performance -optimize_for_size = ["core/optimize_for_size"] - -[lints.rust.unexpected_cfgs] -level = "warn" -# x.py uses beta cargo, so `check-cfg` entries do not yet take effect -# for rust-lang/rust. But for users of `-Zbuild-std` it does. -# The unused warning is waiting for rust-lang/cargo#13925 to reach beta. -check-cfg = [ - 'cfg(bootstrap)', - 'cfg(no_global_oom_handling)', - 'cfg(no_rc)', - 'cfg(no_sync)', -] diff --git a/library/alloc/benches/binary_heap.rs b/library/alloc/benches/binary_heap.rs deleted file mode 100644 index 917e71f250ee8..0000000000000 --- a/library/alloc/benches/binary_heap.rs +++ /dev/null @@ -1,91 +0,0 @@ -use std::collections::BinaryHeap; - -use rand::seq::SliceRandom; -use test::{black_box, Bencher}; - -#[bench] -fn bench_find_smallest_1000(b: &mut Bencher) { - let mut rng = crate::bench_rng(); - let mut vec: Vec = (0..100_000).collect(); - vec.shuffle(&mut rng); - - b.iter(|| { - let mut iter = vec.iter().copied(); - let mut heap: BinaryHeap<_> = iter.by_ref().take(1000).collect(); - - for x in iter { - let mut max = heap.peek_mut().unwrap(); - // This comparison should be true only 1% of the time. - // Unnecessary `sift_down`s will degrade performance - if x < *max { - *max = x; - } - } - - heap - }) -} - -#[bench] -fn bench_peek_mut_deref_mut(b: &mut Bencher) { - let mut bheap = BinaryHeap::from(vec![42]); - let vec: Vec = (0..1_000_000).collect(); - - b.iter(|| { - let vec = black_box(&vec); - let mut peek_mut = bheap.peek_mut().unwrap(); - // The compiler shouldn't be able to optimize away the `sift_down` - // assignment in `PeekMut`'s `DerefMut` implementation since - // the loop might not run. - for &i in vec.iter() { - *peek_mut = i; - } - // Remove the already minimal overhead of the sift_down - std::mem::forget(peek_mut); - }) -} - -#[bench] -fn bench_from_vec(b: &mut Bencher) { - let mut rng = crate::bench_rng(); - let mut vec: Vec = (0..100_000).collect(); - vec.shuffle(&mut rng); - - b.iter(|| BinaryHeap::from(vec.clone())) -} - -#[bench] -fn bench_into_sorted_vec(b: &mut Bencher) { - let bheap: BinaryHeap = (0..10_000).collect(); - - b.iter(|| bheap.clone().into_sorted_vec()) -} - -#[bench] -fn bench_push(b: &mut Bencher) { - let mut bheap = BinaryHeap::with_capacity(50_000); - let mut rng = crate::bench_rng(); - let mut vec: Vec = (0..50_000).collect(); - vec.shuffle(&mut rng); - - b.iter(|| { - for &i in vec.iter() { - bheap.push(i); - } - black_box(&mut bheap); - bheap.clear(); - }) -} - -#[bench] -fn bench_pop(b: &mut Bencher) { - let mut bheap = BinaryHeap::with_capacity(10_000); - - b.iter(|| { - bheap.extend((0..10_000).rev()); - black_box(&mut bheap); - while let Some(elem) = bheap.pop() { - black_box(elem); - } - }) -} diff --git a/library/alloc/benches/btree/map.rs b/library/alloc/benches/btree/map.rs deleted file mode 100644 index 4fe07eb02139f..0000000000000 --- a/library/alloc/benches/btree/map.rs +++ /dev/null @@ -1,583 +0,0 @@ -use std::collections::BTreeMap; -use std::ops::RangeBounds; - -use rand::{seq::SliceRandom, Rng}; -use test::{black_box, Bencher}; - -macro_rules! map_insert_rand_bench { - ($name: ident, $n: expr, $map: ident) => { - #[bench] - pub fn $name(b: &mut Bencher) { - let n: usize = $n; - let mut map = $map::new(); - // setup - let mut rng = crate::bench_rng(); - - for _ in 0..n { - let i = rng.gen::() % n; - map.insert(i, i); - } - - // measure - b.iter(|| { - let k = rng.gen::() % n; - map.insert(k, k); - map.remove(&k); - }); - black_box(map); - } - }; -} - -macro_rules! map_insert_seq_bench { - ($name: ident, $n: expr, $map: ident) => { - #[bench] - pub fn $name(b: &mut Bencher) { - let mut map = $map::new(); - let n: usize = $n; - // setup - for i in 0..n { - map.insert(i * 2, i * 2); - } - - // measure - let mut i = 1; - b.iter(|| { - map.insert(i, i); - map.remove(&i); - i = (i + 2) % n; - }); - black_box(map); - } - }; -} - -macro_rules! map_from_iter_rand_bench { - ($name: ident, $n: expr, $map: ident) => { - #[bench] - pub fn $name(b: &mut Bencher) { - let n: usize = $n; - // setup - let mut rng = crate::bench_rng(); - let mut vec = Vec::with_capacity(n); - - for _ in 0..n { - let i = rng.gen::() % n; - vec.push((i, i)); - } - - // measure - b.iter(|| { - let map: $map<_, _> = vec.iter().copied().collect(); - black_box(map); - }); - } - }; -} - -macro_rules! map_from_iter_seq_bench { - ($name: ident, $n: expr, $map: ident) => { - #[bench] - pub fn $name(b: &mut Bencher) { - let n: usize = $n; - // setup - let mut vec = Vec::with_capacity(n); - - for i in 0..n { - vec.push((i, i)); - } - - // measure - b.iter(|| { - let map: $map<_, _> = vec.iter().copied().collect(); - black_box(map); - }); - } - }; -} - -macro_rules! map_find_rand_bench { - ($name: ident, $n: expr, $map: ident) => { - #[bench] - pub fn $name(b: &mut Bencher) { - let mut map = $map::new(); - let n: usize = $n; - - // setup - let mut rng = crate::bench_rng(); - let mut keys: Vec<_> = (0..n).map(|_| rng.gen::() % n).collect(); - - for &k in &keys { - map.insert(k, k); - } - - keys.shuffle(&mut rng); - - // measure - let mut i = 0; - b.iter(|| { - let t = map.get(&keys[i]); - i = (i + 1) % n; - black_box(t); - }) - } - }; -} - -macro_rules! map_find_seq_bench { - ($name: ident, $n: expr, $map: ident) => { - #[bench] - pub fn $name(b: &mut Bencher) { - let mut map = $map::new(); - let n: usize = $n; - - // setup - for i in 0..n { - map.insert(i, i); - } - - // measure - let mut i = 0; - b.iter(|| { - let x = map.get(&i); - i = (i + 1) % n; - black_box(x); - }) - } - }; -} - -map_insert_rand_bench! {insert_rand_100, 100, BTreeMap} -map_insert_rand_bench! {insert_rand_10_000, 10_000, BTreeMap} - -map_insert_seq_bench! {insert_seq_100, 100, BTreeMap} -map_insert_seq_bench! {insert_seq_10_000, 10_000, BTreeMap} - -map_from_iter_rand_bench! {from_iter_rand_100, 100, BTreeMap} -map_from_iter_rand_bench! {from_iter_rand_10_000, 10_000, BTreeMap} - -map_from_iter_seq_bench! {from_iter_seq_100, 100, BTreeMap} -map_from_iter_seq_bench! {from_iter_seq_10_000, 10_000, BTreeMap} - -map_find_rand_bench! {find_rand_100, 100, BTreeMap} -map_find_rand_bench! {find_rand_10_000, 10_000, BTreeMap} - -map_find_seq_bench! {find_seq_100, 100, BTreeMap} -map_find_seq_bench! {find_seq_10_000, 10_000, BTreeMap} - -fn bench_iteration(b: &mut Bencher, size: i32) { - let mut map = BTreeMap::::new(); - let mut rng = crate::bench_rng(); - - for _ in 0..size { - map.insert(rng.gen(), rng.gen()); - } - - b.iter(|| { - for entry in &map { - black_box(entry); - } - }); -} - -#[bench] -pub fn iteration_20(b: &mut Bencher) { - bench_iteration(b, 20); -} - -#[bench] -pub fn iteration_1000(b: &mut Bencher) { - bench_iteration(b, 1000); -} - -#[bench] -pub fn iteration_100000(b: &mut Bencher) { - bench_iteration(b, 100000); -} - -fn bench_iteration_mut(b: &mut Bencher, size: i32) { - let mut map = BTreeMap::::new(); - let mut rng = crate::bench_rng(); - - for _ in 0..size { - map.insert(rng.gen(), rng.gen()); - } - - b.iter(|| { - for kv in map.iter_mut() { - black_box(kv); - } - }); -} - -#[bench] -pub fn iteration_mut_20(b: &mut Bencher) { - bench_iteration_mut(b, 20); -} - -#[bench] -pub fn iteration_mut_1000(b: &mut Bencher) { - bench_iteration_mut(b, 1000); -} - -#[bench] -pub fn iteration_mut_100000(b: &mut Bencher) { - bench_iteration_mut(b, 100000); -} - -fn bench_first_and_last_nightly(b: &mut Bencher, size: i32) { - let map: BTreeMap<_, _> = (0..size).map(|i| (i, i)).collect(); - b.iter(|| { - for _ in 0..10 { - black_box(map.first_key_value()); - black_box(map.last_key_value()); - } - }); -} - -fn bench_first_and_last_stable(b: &mut Bencher, size: i32) { - let map: BTreeMap<_, _> = (0..size).map(|i| (i, i)).collect(); - b.iter(|| { - for _ in 0..10 { - black_box(map.iter().next()); - black_box(map.iter().next_back()); - } - }); -} - -#[bench] -pub fn first_and_last_0_nightly(b: &mut Bencher) { - bench_first_and_last_nightly(b, 0); -} - -#[bench] -pub fn first_and_last_0_stable(b: &mut Bencher) { - bench_first_and_last_stable(b, 0); -} - -#[bench] -pub fn first_and_last_100_nightly(b: &mut Bencher) { - bench_first_and_last_nightly(b, 100); -} - -#[bench] -pub fn first_and_last_100_stable(b: &mut Bencher) { - bench_first_and_last_stable(b, 100); -} - -#[bench] -pub fn first_and_last_10k_nightly(b: &mut Bencher) { - bench_first_and_last_nightly(b, 10_000); -} - -#[bench] -pub fn first_and_last_10k_stable(b: &mut Bencher) { - bench_first_and_last_stable(b, 10_000); -} - -const BENCH_RANGE_SIZE: i32 = 145; -const BENCH_RANGE_COUNT: i32 = BENCH_RANGE_SIZE * (BENCH_RANGE_SIZE - 1) / 2; - -fn bench_range(b: &mut Bencher, f: F) -where - F: Fn(i32, i32) -> R, - R: RangeBounds, -{ - let map: BTreeMap<_, _> = (0..BENCH_RANGE_SIZE).map(|i| (i, i)).collect(); - b.iter(|| { - let mut c = 0; - for i in 0..BENCH_RANGE_SIZE { - for j in i + 1..BENCH_RANGE_SIZE { - let _ = black_box(map.range(f(i, j))); - c += 1; - } - } - debug_assert_eq!(c, BENCH_RANGE_COUNT); - }); -} - -#[bench] -pub fn range_included_excluded(b: &mut Bencher) { - bench_range(b, |i, j| i..j); -} - -#[bench] -pub fn range_included_included(b: &mut Bencher) { - bench_range(b, |i, j| i..=j); -} - -#[bench] -pub fn range_included_unbounded(b: &mut Bencher) { - bench_range(b, |i, _| i..); -} - -#[bench] -pub fn range_unbounded_unbounded(b: &mut Bencher) { - bench_range(b, |_, _| ..); -} - -fn bench_iter(b: &mut Bencher, repeats: i32, size: i32) { - let map: BTreeMap<_, _> = (0..size).map(|i| (i, i)).collect(); - b.iter(|| { - for _ in 0..repeats { - let _ = black_box(map.iter()); - } - }); -} - -/// Contrast range_unbounded_unbounded with `iter()`. -#[bench] -pub fn range_unbounded_vs_iter(b: &mut Bencher) { - bench_iter(b, BENCH_RANGE_COUNT, BENCH_RANGE_SIZE); -} - -#[bench] -pub fn iter_0(b: &mut Bencher) { - bench_iter(b, 1_000, 0); -} - -#[bench] -pub fn iter_1(b: &mut Bencher) { - bench_iter(b, 1_000, 1); -} - -#[bench] -pub fn iter_100(b: &mut Bencher) { - bench_iter(b, 1_000, 100); -} - -#[bench] -pub fn iter_10k(b: &mut Bencher) { - bench_iter(b, 1_000, 10_000); -} - -#[bench] -pub fn iter_1m(b: &mut Bencher) { - bench_iter(b, 1_000, 1_000_000); -} - -const FAT: usize = 256; - -// The returned map has small keys and values. -// Benchmarks on it have a counterpart in set.rs with the same keys and no values at all. -fn slim_map(n: usize) -> BTreeMap { - (0..n).map(|i| (i, i)).collect::>() -} - -// The returned map has small keys and large values. -fn fat_val_map(n: usize) -> BTreeMap { - (0..n).map(|i| (i, [i; FAT])).collect::>() -} - -#[bench] -pub fn clone_slim_100(b: &mut Bencher) { - let src = slim_map(100); - b.iter(|| src.clone()) -} - -#[bench] -pub fn clone_slim_100_and_clear(b: &mut Bencher) { - let src = slim_map(100); - b.iter(|| src.clone().clear()) -} - -#[bench] -pub fn clone_slim_100_and_drain_all(b: &mut Bencher) { - let src = slim_map(100); - b.iter(|| src.clone().extract_if(|_, _| true).count()) -} - -#[bench] -pub fn clone_slim_100_and_drain_half(b: &mut Bencher) { - let src = slim_map(100); - b.iter(|| { - let mut map = src.clone(); - assert_eq!(map.extract_if(|i, _| i % 2 == 0).count(), 100 / 2); - assert_eq!(map.len(), 100 / 2); - }) -} - -#[bench] -pub fn clone_slim_100_and_into_iter(b: &mut Bencher) { - let src = slim_map(100); - b.iter(|| src.clone().into_iter().count()) -} - -#[bench] -pub fn clone_slim_100_and_pop_all(b: &mut Bencher) { - let src = slim_map(100); - b.iter(|| { - let mut map = src.clone(); - while map.pop_first().is_some() {} - map - }); -} - -#[bench] -pub fn clone_slim_100_and_remove_all(b: &mut Bencher) { - let src = slim_map(100); - b.iter(|| { - let mut map = src.clone(); - while let Some(elt) = map.iter().map(|(&i, _)| i).next() { - let v = map.remove(&elt); - debug_assert!(v.is_some()); - } - map - }); -} - -#[bench] -pub fn clone_slim_100_and_remove_half(b: &mut Bencher) { - let src = slim_map(100); - b.iter(|| { - let mut map = src.clone(); - for i in (0..100).step_by(2) { - let v = map.remove(&i); - debug_assert!(v.is_some()); - } - assert_eq!(map.len(), 100 / 2); - map - }) -} - -#[bench] -pub fn clone_slim_10k(b: &mut Bencher) { - let src = slim_map(10_000); - b.iter(|| src.clone()) -} - -#[bench] -pub fn clone_slim_10k_and_clear(b: &mut Bencher) { - let src = slim_map(10_000); - b.iter(|| src.clone().clear()) -} - -#[bench] -pub fn clone_slim_10k_and_drain_all(b: &mut Bencher) { - let src = slim_map(10_000); - b.iter(|| src.clone().extract_if(|_, _| true).count()) -} - -#[bench] -pub fn clone_slim_10k_and_drain_half(b: &mut Bencher) { - let src = slim_map(10_000); - b.iter(|| { - let mut map = src.clone(); - assert_eq!(map.extract_if(|i, _| i % 2 == 0).count(), 10_000 / 2); - assert_eq!(map.len(), 10_000 / 2); - }) -} - -#[bench] -pub fn clone_slim_10k_and_into_iter(b: &mut Bencher) { - let src = slim_map(10_000); - b.iter(|| src.clone().into_iter().count()) -} - -#[bench] -pub fn clone_slim_10k_and_pop_all(b: &mut Bencher) { - let src = slim_map(10_000); - b.iter(|| { - let mut map = src.clone(); - while map.pop_first().is_some() {} - map - }); -} - -#[bench] -pub fn clone_slim_10k_and_remove_all(b: &mut Bencher) { - let src = slim_map(10_000); - b.iter(|| { - let mut map = src.clone(); - while let Some(elt) = map.iter().map(|(&i, _)| i).next() { - let v = map.remove(&elt); - debug_assert!(v.is_some()); - } - map - }); -} - -#[bench] -pub fn clone_slim_10k_and_remove_half(b: &mut Bencher) { - let src = slim_map(10_000); - b.iter(|| { - let mut map = src.clone(); - for i in (0..10_000).step_by(2) { - let v = map.remove(&i); - debug_assert!(v.is_some()); - } - assert_eq!(map.len(), 10_000 / 2); - map - }) -} - -#[bench] -pub fn clone_fat_val_100(b: &mut Bencher) { - let src = fat_val_map(100); - b.iter(|| src.clone()) -} - -#[bench] -pub fn clone_fat_val_100_and_clear(b: &mut Bencher) { - let src = fat_val_map(100); - b.iter(|| src.clone().clear()) -} - -#[bench] -pub fn clone_fat_val_100_and_drain_all(b: &mut Bencher) { - let src = fat_val_map(100); - b.iter(|| src.clone().extract_if(|_, _| true).count()) -} - -#[bench] -pub fn clone_fat_val_100_and_drain_half(b: &mut Bencher) { - let src = fat_val_map(100); - b.iter(|| { - let mut map = src.clone(); - assert_eq!(map.extract_if(|i, _| i % 2 == 0).count(), 100 / 2); - assert_eq!(map.len(), 100 / 2); - }) -} - -#[bench] -pub fn clone_fat_val_100_and_into_iter(b: &mut Bencher) { - let src = fat_val_map(100); - b.iter(|| src.clone().into_iter().count()) -} - -#[bench] -pub fn clone_fat_val_100_and_pop_all(b: &mut Bencher) { - let src = fat_val_map(100); - b.iter(|| { - let mut map = src.clone(); - while map.pop_first().is_some() {} - map - }); -} - -#[bench] -pub fn clone_fat_val_100_and_remove_all(b: &mut Bencher) { - let src = fat_val_map(100); - b.iter(|| { - let mut map = src.clone(); - while let Some(elt) = map.iter().map(|(&i, _)| i).next() { - let v = map.remove(&elt); - debug_assert!(v.is_some()); - } - map - }); -} - -#[bench] -pub fn clone_fat_val_100_and_remove_half(b: &mut Bencher) { - let src = fat_val_map(100); - b.iter(|| { - let mut map = src.clone(); - for i in (0..100).step_by(2) { - let v = map.remove(&i); - debug_assert!(v.is_some()); - } - assert_eq!(map.len(), 100 / 2); - map - }) -} diff --git a/library/alloc/benches/btree/mod.rs b/library/alloc/benches/btree/mod.rs deleted file mode 100644 index 095ca5dd2e21b..0000000000000 --- a/library/alloc/benches/btree/mod.rs +++ /dev/null @@ -1,2 +0,0 @@ -mod map; -mod set; diff --git a/library/alloc/benches/btree/set.rs b/library/alloc/benches/btree/set.rs deleted file mode 100644 index 09d72c7206469..0000000000000 --- a/library/alloc/benches/btree/set.rs +++ /dev/null @@ -1,224 +0,0 @@ -use std::collections::BTreeSet; - -use rand::Rng; -use test::Bencher; - -fn random(n: usize) -> BTreeSet { - let mut rng = crate::bench_rng(); - let mut set = BTreeSet::new(); - while set.len() < n { - set.insert(rng.gen()); - } - assert_eq!(set.len(), n); - set -} - -fn neg(n: usize) -> BTreeSet { - let set: BTreeSet = (-(n as i32)..=-1).collect(); - assert_eq!(set.len(), n); - set -} - -fn pos(n: usize) -> BTreeSet { - let set: BTreeSet = (1..=(n as i32)).collect(); - assert_eq!(set.len(), n); - set -} - -fn stagger(n1: usize, factor: usize) -> [BTreeSet; 2] { - let n2 = n1 * factor; - let mut sets = [BTreeSet::new(), BTreeSet::new()]; - for i in 0..(n1 + n2) { - let b = i % (factor + 1) != 0; - sets[b as usize].insert(i as u32); - } - assert_eq!(sets[0].len(), n1); - assert_eq!(sets[1].len(), n2); - sets -} - -macro_rules! set_bench { - ($name: ident, $set_func: ident, $result_func: ident, $sets: expr) => { - #[bench] - pub fn $name(b: &mut Bencher) { - // setup - let sets = $sets; - - // measure - b.iter(|| sets[0].$set_func(&sets[1]).$result_func()) - } - }; -} - -fn slim_set(n: usize) -> BTreeSet { - (0..n).collect::>() -} - -#[bench] -pub fn clone_100(b: &mut Bencher) { - let src = slim_set(100); - b.iter(|| src.clone()) -} - -#[bench] -pub fn clone_100_and_clear(b: &mut Bencher) { - let src = slim_set(100); - b.iter(|| src.clone().clear()) -} - -#[bench] -pub fn clone_100_and_drain_all(b: &mut Bencher) { - let src = slim_set(100); - b.iter(|| src.clone().extract_if(|_| true).count()) -} - -#[bench] -pub fn clone_100_and_drain_half(b: &mut Bencher) { - let src = slim_set(100); - b.iter(|| { - let mut set = src.clone(); - assert_eq!(set.extract_if(|i| i % 2 == 0).count(), 100 / 2); - assert_eq!(set.len(), 100 / 2); - }) -} - -#[bench] -pub fn clone_100_and_into_iter(b: &mut Bencher) { - let src = slim_set(100); - b.iter(|| src.clone().into_iter().count()) -} - -#[bench] -pub fn clone_100_and_pop_all(b: &mut Bencher) { - let src = slim_set(100); - b.iter(|| { - let mut set = src.clone(); - while set.pop_first().is_some() {} - set - }); -} - -#[bench] -pub fn clone_100_and_remove_all(b: &mut Bencher) { - let src = slim_set(100); - b.iter(|| { - let mut set = src.clone(); - while let Some(elt) = set.iter().copied().next() { - let ok = set.remove(&elt); - debug_assert!(ok); - } - set - }); -} - -#[bench] -pub fn clone_100_and_remove_half(b: &mut Bencher) { - let src = slim_set(100); - b.iter(|| { - let mut set = src.clone(); - for i in (0..100).step_by(2) { - let ok = set.remove(&i); - debug_assert!(ok); - } - assert_eq!(set.len(), 100 / 2); - set - }) -} - -#[bench] -pub fn clone_10k(b: &mut Bencher) { - let src = slim_set(10_000); - b.iter(|| src.clone()) -} - -#[bench] -pub fn clone_10k_and_clear(b: &mut Bencher) { - let src = slim_set(10_000); - b.iter(|| src.clone().clear()) -} - -#[bench] -pub fn clone_10k_and_drain_all(b: &mut Bencher) { - let src = slim_set(10_000); - b.iter(|| src.clone().extract_if(|_| true).count()) -} - -#[bench] -pub fn clone_10k_and_drain_half(b: &mut Bencher) { - let src = slim_set(10_000); - b.iter(|| { - let mut set = src.clone(); - assert_eq!(set.extract_if(|i| i % 2 == 0).count(), 10_000 / 2); - assert_eq!(set.len(), 10_000 / 2); - }) -} - -#[bench] -pub fn clone_10k_and_into_iter(b: &mut Bencher) { - let src = slim_set(10_000); - b.iter(|| src.clone().into_iter().count()) -} - -#[bench] -pub fn clone_10k_and_pop_all(b: &mut Bencher) { - let src = slim_set(10_000); - b.iter(|| { - let mut set = src.clone(); - while set.pop_first().is_some() {} - set - }); -} - -#[bench] -pub fn clone_10k_and_remove_all(b: &mut Bencher) { - let src = slim_set(10_000); - b.iter(|| { - let mut set = src.clone(); - while let Some(elt) = set.iter().copied().next() { - let ok = set.remove(&elt); - debug_assert!(ok); - } - set - }); -} - -#[bench] -pub fn clone_10k_and_remove_half(b: &mut Bencher) { - let src = slim_set(10_000); - b.iter(|| { - let mut set = src.clone(); - for i in (0..10_000).step_by(2) { - let ok = set.remove(&i); - debug_assert!(ok); - } - assert_eq!(set.len(), 10_000 / 2); - set - }) -} - -set_bench! {intersection_100_neg_vs_100_pos, intersection, count, [neg(100), pos(100)]} -set_bench! {intersection_100_neg_vs_10k_pos, intersection, count, [neg(100), pos(10_000)]} -set_bench! {intersection_100_pos_vs_100_neg, intersection, count, [pos(100), neg(100)]} -set_bench! {intersection_100_pos_vs_10k_neg, intersection, count, [pos(100), neg(10_000)]} -set_bench! {intersection_10k_neg_vs_100_pos, intersection, count, [neg(10_000), pos(100)]} -set_bench! {intersection_10k_neg_vs_10k_pos, intersection, count, [neg(10_000), pos(10_000)]} -set_bench! {intersection_10k_pos_vs_100_neg, intersection, count, [pos(10_000), neg(100)]} -set_bench! {intersection_10k_pos_vs_10k_neg, intersection, count, [pos(10_000), neg(10_000)]} -set_bench! {intersection_random_100_vs_100, intersection, count, [random(100), random(100)]} -set_bench! {intersection_random_100_vs_10k, intersection, count, [random(100), random(10_000)]} -set_bench! {intersection_random_10k_vs_100, intersection, count, [random(10_000), random(100)]} -set_bench! {intersection_random_10k_vs_10k, intersection, count, [random(10_000), random(10_000)]} -set_bench! {intersection_staggered_100_vs_100, intersection, count, stagger(100, 1)} -set_bench! {intersection_staggered_10k_vs_10k, intersection, count, stagger(10_000, 1)} -set_bench! {intersection_staggered_100_vs_10k, intersection, count, stagger(100, 100)} -set_bench! {difference_random_100_vs_100, difference, count, [random(100), random(100)]} -set_bench! {difference_random_100_vs_10k, difference, count, [random(100), random(10_000)]} -set_bench! {difference_random_10k_vs_100, difference, count, [random(10_000), random(100)]} -set_bench! {difference_random_10k_vs_10k, difference, count, [random(10_000), random(10_000)]} -set_bench! {difference_staggered_100_vs_100, difference, count, stagger(100, 1)} -set_bench! {difference_staggered_10k_vs_10k, difference, count, stagger(10_000, 1)} -set_bench! {difference_staggered_100_vs_10k, difference, count, stagger(100, 100)} -set_bench! {is_subset_100_vs_100, is_subset, clone, [pos(100), pos(100)]} -set_bench! {is_subset_100_vs_10k, is_subset, clone, [pos(100), pos(10_000)]} -set_bench! {is_subset_10k_vs_100, is_subset, clone, [pos(10_000), pos(100)]} -set_bench! {is_subset_10k_vs_10k, is_subset, clone, [pos(10_000), pos(10_000)]} diff --git a/library/alloc/benches/lib.rs b/library/alloc/benches/lib.rs deleted file mode 100644 index 0561f49c967e5..0000000000000 --- a/library/alloc/benches/lib.rs +++ /dev/null @@ -1,31 +0,0 @@ -// Disabling on android for the time being -// See https://github.com/rust-lang/rust/issues/73535#event-3477699747 -#![cfg(not(target_os = "android"))] -// Disabling in Miri as these would take too long. -#![cfg(not(miri))] -#![feature(btree_extract_if)] -#![feature(iter_next_chunk)] -#![feature(repr_simd)] -#![feature(slice_partition_dedup)] -#![feature(strict_provenance)] -#![feature(test)] -#![deny(fuzzy_provenance_casts)] - -extern crate test; - -mod binary_heap; -mod btree; -mod linked_list; -mod slice; -mod str; -mod string; -mod vec; -mod vec_deque; - -/// Returns a `rand::Rng` seeded with a consistent seed. -/// -/// This is done to avoid introducing nondeterminism in benchmark results. -fn bench_rng() -> rand_xorshift::XorShiftRng { - const SEED: [u8; 16] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]; - rand::SeedableRng::from_seed(SEED) -} diff --git a/library/alloc/benches/linked_list.rs b/library/alloc/benches/linked_list.rs deleted file mode 100644 index 29c5ad2bc6eb2..0000000000000 --- a/library/alloc/benches/linked_list.rs +++ /dev/null @@ -1,77 +0,0 @@ -use std::collections::LinkedList; -use test::Bencher; - -#[bench] -fn bench_collect_into(b: &mut Bencher) { - let v = &[0; 64]; - b.iter(|| { - let _: LinkedList<_> = v.iter().cloned().collect(); - }) -} - -#[bench] -fn bench_push_front(b: &mut Bencher) { - let mut m: LinkedList<_> = LinkedList::new(); - b.iter(|| { - m.push_front(0); - }) -} - -#[bench] -fn bench_push_back(b: &mut Bencher) { - let mut m: LinkedList<_> = LinkedList::new(); - b.iter(|| { - m.push_back(0); - }) -} - -#[bench] -fn bench_push_back_pop_back(b: &mut Bencher) { - let mut m: LinkedList<_> = LinkedList::new(); - b.iter(|| { - m.push_back(0); - m.pop_back(); - }) -} - -#[bench] -fn bench_push_front_pop_front(b: &mut Bencher) { - let mut m: LinkedList<_> = LinkedList::new(); - b.iter(|| { - m.push_front(0); - m.pop_front(); - }) -} - -#[bench] -fn bench_iter(b: &mut Bencher) { - let v = &[0; 128]; - let m: LinkedList<_> = v.iter().cloned().collect(); - b.iter(|| { - assert!(m.iter().count() == 128); - }) -} -#[bench] -fn bench_iter_mut(b: &mut Bencher) { - let v = &[0; 128]; - let mut m: LinkedList<_> = v.iter().cloned().collect(); - b.iter(|| { - assert!(m.iter_mut().count() == 128); - }) -} -#[bench] -fn bench_iter_rev(b: &mut Bencher) { - let v = &[0; 128]; - let m: LinkedList<_> = v.iter().cloned().collect(); - b.iter(|| { - assert!(m.iter().rev().count() == 128); - }) -} -#[bench] -fn bench_iter_mut_rev(b: &mut Bencher) { - let v = &[0; 128]; - let mut m: LinkedList<_> = v.iter().cloned().collect(); - b.iter(|| { - assert!(m.iter_mut().rev().count() == 128); - }) -} diff --git a/library/alloc/benches/slice.rs b/library/alloc/benches/slice.rs deleted file mode 100644 index b62be9d39a1cd..0000000000000 --- a/library/alloc/benches/slice.rs +++ /dev/null @@ -1,379 +0,0 @@ -use std::{mem, ptr}; - -use rand::distributions::{Alphanumeric, DistString, Standard}; -use rand::Rng; -use test::{black_box, Bencher}; - -#[bench] -fn iterator(b: &mut Bencher) { - // peculiar numbers to stop LLVM from optimising the summation - // out. - let v: Vec<_> = (0..100).map(|i| i ^ (i << 1) ^ (i >> 1)).collect(); - - b.iter(|| { - let mut sum = 0; - for x in &v { - sum += *x; - } - // sum == 11806, to stop dead code elimination. - if sum == 0 { - panic!() - } - }) -} - -#[bench] -fn mut_iterator(b: &mut Bencher) { - let mut v = vec![0; 100]; - - b.iter(|| { - let mut i = 0; - for x in &mut v { - *x = i; - i += 1; - } - }) -} - -#[bench] -fn concat(b: &mut Bencher) { - let xss: Vec> = (0..100).map(|i| (0..i).collect()).collect(); - b.iter(|| { - xss.concat(); - }); -} - -#[bench] -fn join(b: &mut Bencher) { - let xss: Vec> = (0..100).map(|i| (0..i).collect()).collect(); - b.iter(|| xss.join(&0)); -} - -#[bench] -fn push(b: &mut Bencher) { - let mut vec = Vec::::new(); - b.iter(|| { - vec.push(0); - black_box(&vec); - }); -} - -#[bench] -fn starts_with_same_vector(b: &mut Bencher) { - let vec: Vec<_> = (0..100).collect(); - b.iter(|| vec.starts_with(&vec)) -} - -#[bench] -fn starts_with_single_element(b: &mut Bencher) { - let vec: Vec<_> = vec![0]; - b.iter(|| vec.starts_with(&vec)) -} - -#[bench] -fn starts_with_diff_one_element_at_end(b: &mut Bencher) { - let vec: Vec<_> = (0..100).collect(); - let mut match_vec: Vec<_> = (0..99).collect(); - match_vec.push(0); - b.iter(|| vec.starts_with(&match_vec)) -} - -#[bench] -fn ends_with_same_vector(b: &mut Bencher) { - let vec: Vec<_> = (0..100).collect(); - b.iter(|| vec.ends_with(&vec)) -} - -#[bench] -fn ends_with_single_element(b: &mut Bencher) { - let vec: Vec<_> = vec![0]; - b.iter(|| vec.ends_with(&vec)) -} - -#[bench] -fn ends_with_diff_one_element_at_beginning(b: &mut Bencher) { - let vec: Vec<_> = (0..100).collect(); - let mut match_vec: Vec<_> = (0..100).collect(); - match_vec[0] = 200; - b.iter(|| vec.starts_with(&match_vec)) -} - -#[bench] -fn contains_last_element(b: &mut Bencher) { - let vec: Vec<_> = (0..100).collect(); - b.iter(|| vec.contains(&99)) -} - -#[bench] -fn zero_1kb_from_elem(b: &mut Bencher) { - b.iter(|| vec![0u8; 1024]); -} - -#[bench] -fn zero_1kb_set_memory(b: &mut Bencher) { - b.iter(|| { - let mut v = Vec::::with_capacity(1024); - unsafe { - let vp = v.as_mut_ptr(); - ptr::write_bytes(vp, 0, 1024); - v.set_len(1024); - } - v - }); -} - -#[bench] -fn zero_1kb_loop_set(b: &mut Bencher) { - b.iter(|| { - let mut v = Vec::::with_capacity(1024); - unsafe { - v.set_len(1024); - } - for i in 0..1024 { - v[i] = 0; - } - }); -} - -#[bench] -fn zero_1kb_mut_iter(b: &mut Bencher) { - b.iter(|| { - let mut v = Vec::::with_capacity(1024); - unsafe { - v.set_len(1024); - } - for x in &mut v { - *x = 0; - } - v - }); -} - -#[bench] -fn random_inserts(b: &mut Bencher) { - let mut rng = crate::bench_rng(); - b.iter(|| { - let mut v = vec![(0, 0); 30]; - for _ in 0..100 { - let l = v.len(); - v.insert(rng.gen::() % (l + 1), (1, 1)); - } - }) -} - -#[bench] -fn random_removes(b: &mut Bencher) { - let mut rng = crate::bench_rng(); - b.iter(|| { - let mut v = vec![(0, 0); 130]; - for _ in 0..100 { - let l = v.len(); - v.remove(rng.gen::() % l); - } - }) -} - -fn gen_ascending(len: usize) -> Vec { - (0..len as u64).collect() -} - -fn gen_descending(len: usize) -> Vec { - (0..len as u64).rev().collect() -} - -fn gen_random(len: usize) -> Vec { - let mut rng = crate::bench_rng(); - (&mut rng).sample_iter(&Standard).take(len).collect() -} - -fn gen_random_bytes(len: usize) -> Vec { - let mut rng = crate::bench_rng(); - (&mut rng).sample_iter(&Standard).take(len).collect() -} - -fn gen_mostly_ascending(len: usize) -> Vec { - let mut rng = crate::bench_rng(); - let mut v = gen_ascending(len); - for _ in (0usize..).take_while(|x| x * x <= len) { - let x = rng.gen::() % len; - let y = rng.gen::() % len; - v.swap(x, y); - } - v -} - -fn gen_mostly_descending(len: usize) -> Vec { - let mut rng = crate::bench_rng(); - let mut v = gen_descending(len); - for _ in (0usize..).take_while(|x| x * x <= len) { - let x = rng.gen::() % len; - let y = rng.gen::() % len; - v.swap(x, y); - } - v -} - -fn gen_strings(len: usize) -> Vec { - let mut rng = crate::bench_rng(); - let mut v = vec![]; - for _ in 0..len { - let n = rng.gen::() % 20 + 1; - v.push(Alphanumeric.sample_string(&mut rng, n)); - } - v -} - -fn gen_big_random(len: usize) -> Vec<[u64; 16]> { - let mut rng = crate::bench_rng(); - (&mut rng).sample_iter(&Standard).map(|x| [x; 16]).take(len).collect() -} - -macro_rules! sort { - ($f:ident, $name:ident, $gen:expr, $len:expr) => { - #[bench] - fn $name(b: &mut Bencher) { - let v = $gen($len); - b.iter(|| v.clone().$f()); - b.bytes = $len * mem::size_of_val(&$gen(1)[0]) as u64; - } - }; -} - -macro_rules! sort_strings { - ($f:ident, $name:ident, $gen:expr, $len:expr) => { - #[bench] - fn $name(b: &mut Bencher) { - let v = $gen($len); - let v = v.iter().map(|s| &**s).collect::>(); - b.iter(|| v.clone().$f()); - b.bytes = $len * mem::size_of::<&str>() as u64; - } - }; -} - -macro_rules! sort_expensive { - ($f:ident, $name:ident, $gen:expr, $len:expr) => { - #[bench] - fn $name(b: &mut Bencher) { - let v = $gen($len); - b.iter(|| { - let mut v = v.clone(); - let mut count = 0; - v.$f(|a: &u64, b: &u64| { - count += 1; - if count % 1_000_000_000 == 0 { - panic!("should not happen"); - } - (*a as f64).cos().partial_cmp(&(*b as f64).cos()).unwrap() - }); - black_box(count); - }); - b.bytes = $len * mem::size_of_val(&$gen(1)[0]) as u64; - } - }; -} - -macro_rules! sort_lexicographic { - ($f:ident, $name:ident, $gen:expr, $len:expr) => { - #[bench] - fn $name(b: &mut Bencher) { - let v = $gen($len); - b.iter(|| v.clone().$f(|x| x.to_string())); - b.bytes = $len * mem::size_of_val(&$gen(1)[0]) as u64; - } - }; -} - -sort!(sort, sort_small_ascending, gen_ascending, 10); -sort!(sort, sort_small_descending, gen_descending, 10); -sort!(sort, sort_small_random, gen_random, 10); -sort!(sort, sort_small_big, gen_big_random, 10); -sort!(sort, sort_medium_random, gen_random, 100); -sort!(sort, sort_large_ascending, gen_ascending, 10000); -sort!(sort, sort_large_descending, gen_descending, 10000); -sort!(sort, sort_large_mostly_ascending, gen_mostly_ascending, 10000); -sort!(sort, sort_large_mostly_descending, gen_mostly_descending, 10000); -sort!(sort, sort_large_random, gen_random, 10000); -sort!(sort, sort_large_big, gen_big_random, 10000); -sort_strings!(sort, sort_large_strings, gen_strings, 10000); -sort_expensive!(sort_by, sort_large_expensive, gen_random, 10000); - -sort!(sort_unstable, sort_unstable_small_ascending, gen_ascending, 10); -sort!(sort_unstable, sort_unstable_small_descending, gen_descending, 10); -sort!(sort_unstable, sort_unstable_small_random, gen_random, 10); -sort!(sort_unstable, sort_unstable_small_big, gen_big_random, 10); -sort!(sort_unstable, sort_unstable_medium_random, gen_random, 100); -sort!(sort_unstable, sort_unstable_large_ascending, gen_ascending, 10000); -sort!(sort_unstable, sort_unstable_large_descending, gen_descending, 10000); -sort!(sort_unstable, sort_unstable_large_mostly_ascending, gen_mostly_ascending, 10000); -sort!(sort_unstable, sort_unstable_large_mostly_descending, gen_mostly_descending, 10000); -sort!(sort_unstable, sort_unstable_large_random, gen_random, 10000); -sort!(sort_unstable, sort_unstable_large_big, gen_big_random, 10000); -sort_strings!(sort_unstable, sort_unstable_large_strings, gen_strings, 10000); -sort_expensive!(sort_unstable_by, sort_unstable_large_expensive, gen_random, 10000); - -sort_lexicographic!(sort_by_key, sort_by_key_lexicographic, gen_random, 10000); -sort_lexicographic!(sort_unstable_by_key, sort_unstable_by_key_lexicographic, gen_random, 10000); -sort_lexicographic!(sort_by_cached_key, sort_by_cached_key_lexicographic, gen_random, 10000); - -macro_rules! reverse { - ($name:ident, $ty:ty, $f:expr) => { - #[bench] - fn $name(b: &mut Bencher) { - // odd length and offset by 1 to be as unaligned as possible - let n = 0xFFFFF; - let mut v: Vec<_> = (0..1 + (n / mem::size_of::<$ty>() as u64)).map($f).collect(); - b.iter(|| black_box(&mut v[1..]).reverse()); - b.bytes = n; - } - }; -} - -reverse!(reverse_u8, u8, |x| x as u8); -reverse!(reverse_u16, u16, |x| x as u16); -reverse!(reverse_u8x3, [u8; 3], |x| [x as u8, (x >> 8) as u8, (x >> 16) as u8]); -reverse!(reverse_u32, u32, |x| x as u32); -reverse!(reverse_u64, u64, |x| x as u64); -reverse!(reverse_u128, u128, |x| x as u128); -#[repr(simd)] -struct F64x4(f64, f64, f64, f64); -reverse!(reverse_simd_f64x4, F64x4, |x| { - let x = x as f64; - F64x4(x, x, x, x) -}); - -macro_rules! rotate { - ($name:ident, $gen:expr, $len:expr, $mid:expr) => { - #[bench] - fn $name(b: &mut Bencher) { - let size = mem::size_of_val(&$gen(1)[0]); - let mut v = $gen($len * 8 / size); - b.iter(|| black_box(&mut v).rotate_left(($mid * 8 + size - 1) / size)); - b.bytes = (v.len() * size) as u64; - } - }; -} - -rotate!(rotate_tiny_by1, gen_random, 16, 1); -rotate!(rotate_tiny_half, gen_random, 16, 16 / 2); -rotate!(rotate_tiny_half_plus_one, gen_random, 16, 16 / 2 + 1); - -rotate!(rotate_medium_by1, gen_random, 9158, 1); -rotate!(rotate_medium_by727_u64, gen_random, 9158, 727); -rotate!(rotate_medium_by727_bytes, gen_random_bytes, 9158, 727); -rotate!(rotate_medium_by727_strings, gen_strings, 9158, 727); -rotate!(rotate_medium_half, gen_random, 9158, 9158 / 2); -rotate!(rotate_medium_half_plus_one, gen_random, 9158, 9158 / 2 + 1); - -// Intended to use more RAM than the machine has cache -rotate!(rotate_huge_by1, gen_random, 5 * 1024 * 1024, 1); -rotate!(rotate_huge_by9199_u64, gen_random, 5 * 1024 * 1024, 9199); -rotate!(rotate_huge_by9199_bytes, gen_random_bytes, 5 * 1024 * 1024, 9199); -rotate!(rotate_huge_by9199_strings, gen_strings, 5 * 1024 * 1024, 9199); -rotate!(rotate_huge_by9199_big, gen_big_random, 5 * 1024 * 1024, 9199); -rotate!(rotate_huge_by1234577_u64, gen_random, 5 * 1024 * 1024, 1234577); -rotate!(rotate_huge_by1234577_bytes, gen_random_bytes, 5 * 1024 * 1024, 1234577); -rotate!(rotate_huge_by1234577_strings, gen_strings, 5 * 1024 * 1024, 1234577); -rotate!(rotate_huge_by1234577_big, gen_big_random, 5 * 1024 * 1024, 1234577); -rotate!(rotate_huge_half, gen_random, 5 * 1024 * 1024, 5 * 1024 * 1024 / 2); -rotate!(rotate_huge_half_plus_one, gen_random, 5 * 1024 * 1024, 5 * 1024 * 1024 / 2 + 1); diff --git a/library/alloc/benches/str.rs b/library/alloc/benches/str.rs deleted file mode 100644 index c148ab6b220a5..0000000000000 --- a/library/alloc/benches/str.rs +++ /dev/null @@ -1,349 +0,0 @@ -use test::{black_box, Bencher}; - -#[bench] -fn char_iterator(b: &mut Bencher) { - let s = "ศไทย中华Việt Nam; Mary had a little lamb, Little lamb"; - - b.iter(|| s.chars().count()); -} - -#[bench] -fn char_iterator_for(b: &mut Bencher) { - let s = "ศไทย中华Việt Nam; Mary had a little lamb, Little lamb"; - - b.iter(|| { - for ch in s.chars() { - black_box(ch); - } - }); -} - -#[bench] -fn char_iterator_ascii(b: &mut Bencher) { - let s = "Mary had a little lamb, Little lamb - Mary had a little lamb, Little lamb - Mary had a little lamb, Little lamb - Mary had a little lamb, Little lamb - Mary had a little lamb, Little lamb - Mary had a little lamb, Little lamb"; - - b.iter(|| s.chars().count()); -} - -#[bench] -fn char_iterator_rev(b: &mut Bencher) { - let s = "ศไทย中华Việt Nam; Mary had a little lamb, Little lamb"; - - b.iter(|| s.chars().rev().count()); -} - -#[bench] -fn char_iterator_rev_for(b: &mut Bencher) { - let s = "ศไทย中华Việt Nam; Mary had a little lamb, Little lamb"; - - b.iter(|| { - for ch in s.chars().rev() { - black_box(ch); - } - }); -} - -#[bench] -fn char_indicesator(b: &mut Bencher) { - let s = "ศไทย中华Việt Nam; Mary had a little lamb, Little lamb"; - let len = s.chars().count(); - - b.iter(|| assert_eq!(s.char_indices().count(), len)); -} - -#[bench] -fn char_indicesator_rev(b: &mut Bencher) { - let s = "ศไทย中华Việt Nam; Mary had a little lamb, Little lamb"; - let len = s.chars().count(); - - b.iter(|| assert_eq!(s.char_indices().rev().count(), len)); -} - -#[bench] -fn split_unicode_ascii(b: &mut Bencher) { - let s = "ประเทศไทย中华Việt Namประเทศไทย中华Việt Nam"; - - b.iter(|| assert_eq!(s.split('V').count(), 3)); -} - -#[bench] -fn split_ascii(b: &mut Bencher) { - let s = "Mary had a little lamb, Little lamb, little-lamb."; - let len = s.split(' ').count(); - - b.iter(|| assert_eq!(s.split(' ').count(), len)); -} - -#[bench] -fn split_extern_fn(b: &mut Bencher) { - let s = "Mary had a little lamb, Little lamb, little-lamb."; - let len = s.split(' ').count(); - fn pred(c: char) -> bool { - c == ' ' - } - - b.iter(|| assert_eq!(s.split(pred).count(), len)); -} - -#[bench] -fn split_closure(b: &mut Bencher) { - let s = "Mary had a little lamb, Little lamb, little-lamb."; - let len = s.split(' ').count(); - - b.iter(|| assert_eq!(s.split(|c: char| c == ' ').count(), len)); -} - -#[bench] -fn split_slice(b: &mut Bencher) { - let s = "Mary had a little lamb, Little lamb, little-lamb."; - let len = s.split(' ').count(); - - let c: &[char] = &[' ']; - b.iter(|| assert_eq!(s.split(c).count(), len)); -} - -#[bench] -fn bench_join(b: &mut Bencher) { - let s = "ศไทย中华Việt Nam; Mary had a little lamb, Little lamb"; - let sep = "→"; - let v = vec![s, s, s, s, s, s, s, s, s, s]; - b.iter(|| { - assert_eq!(v.join(sep).len(), s.len() * 10 + sep.len() * 9); - }) -} - -#[bench] -fn bench_contains_short_short(b: &mut Bencher) { - let haystack = "Lorem ipsum dolor sit amet, consectetur adipiscing elit."; - let needle = "sit"; - - b.bytes = haystack.len() as u64; - b.iter(|| { - assert!(black_box(haystack).contains(black_box(needle))); - }) -} - -static LONG_HAYSTACK: &str = "\ -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse quis lorem sit amet dolor \ -ultricies condimentum. Praesent iaculis purus elit, ac malesuada quam malesuada in. Duis sed orci \ -eros. Suspendisse sit amet magna mollis, mollis nunc luctus, imperdiet mi. Integer fringilla non \ -sem ut lacinia. Fusce varius tortor a risus porttitor hendrerit. Morbi mauris dui, ultricies nec \ -tempus vel, gravida nec quam. - -In est dui, tincidunt sed tempus interdum, adipiscing laoreet ante. Etiam tempor, tellus quis \ -sagittis interdum, nulla purus mattis sem, quis auctor erat odio ac tellus. In nec nunc sit amet \ -diam volutpat molestie at sed ipsum. Vestibulum laoreet consequat vulputate. Integer accumsan \ -lorem ac dignissim placerat. Suspendisse convallis faucibus lorem. Aliquam erat volutpat. In vel \ -eleifend felis. Sed suscipit nulla lorem, sed mollis est sollicitudin et. Nam fermentum egestas \ -interdum. Curabitur ut nisi justo. - -Sed sollicitudin ipsum tellus, ut condimentum leo eleifend nec. Cras ut velit ante. Phasellus nec \ -mollis odio. Mauris molestie erat in arcu mattis, at aliquet dolor vehicula. Quisque malesuada \ -lectus sit amet nisi pretium, a condimentum ipsum porta. Morbi at dapibus diam. Praesent egestas \ -est sed risus elementum, eu rutrum metus ultrices. Etiam fermentum consectetur magna, id rutrum \ -felis accumsan a. Aliquam ut pellentesque libero. Sed mi nulla, lobortis eu tortor id, suscipit \ -ultricies neque. Morbi iaculis sit amet risus at iaculis. Praesent eget ligula quis turpis \ -feugiat suscipit vel non arcu. Interdum et malesuada fames ac ante ipsum primis in faucibus. \ -Aliquam sit amet placerat lorem. - -Cras a lacus vel ante posuere elementum. Nunc est leo, bibendum ut facilisis vel, bibendum at \ -mauris. Nullam adipiscing diam vel odio ornare, luctus adipiscing mi luctus. Nulla facilisi. \ -Mauris adipiscing bibendum neque, quis adipiscing lectus tempus et. Sed feugiat erat et nisl \ -lobortis pharetra. Donec vitae erat enim. Nullam sit amet felis et quam lacinia tincidunt. Aliquam \ -suscipit dapibus urna. Sed volutpat urna in magna pulvinar volutpat. Phasellus nec tellus ac diam \ -cursus accumsan. - -Nam lectus enim, dapibus non nisi tempor, consectetur convallis massa. Maecenas eleifend dictum \ -feugiat. Etiam quis mauris vel risus luctus mattis a a nunc. Nullam orci quam, imperdiet id \ -vehicula in, porttitor ut nibh. Duis sagittis adipiscing nisl vitae congue. Donec mollis risus eu \ -leo suscipit, varius porttitor nulla porta. Pellentesque ut sem nec nisi euismod vehicula. Nulla \ -malesuada sollicitudin quam eu fermentum."; - -#[bench] -fn bench_contains_2b_repeated_long(b: &mut Bencher) { - let haystack = LONG_HAYSTACK; - let needle = "::"; - - b.bytes = haystack.len() as u64; - b.iter(|| { - assert!(!black_box(haystack).contains(black_box(needle))); - }) -} - -#[bench] -fn bench_contains_short_long(b: &mut Bencher) { - let haystack = LONG_HAYSTACK; - let needle = "english"; - - b.bytes = haystack.len() as u64; - b.iter(|| { - assert!(!black_box(haystack).contains(black_box(needle))); - }) -} - -#[bench] -fn bench_contains_16b_in_long(b: &mut Bencher) { - let haystack = LONG_HAYSTACK; - let needle = "english language"; - - b.bytes = haystack.len() as u64; - b.iter(|| { - assert!(!black_box(haystack).contains(black_box(needle))); - }) -} - -#[bench] -fn bench_contains_32b_in_long(b: &mut Bencher) { - let haystack = LONG_HAYSTACK; - let needle = "the english language sample text"; - - b.bytes = haystack.len() as u64; - b.iter(|| { - assert!(!black_box(haystack).contains(black_box(needle))); - }) -} - -#[bench] -fn bench_contains_bad_naive(b: &mut Bencher) { - let haystack = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"; - let needle = "aaaaaaaab"; - - b.bytes = haystack.len() as u64; - b.iter(|| { - assert!(!black_box(haystack).contains(black_box(needle))); - }) -} - -#[bench] -fn bench_contains_bad_simd(b: &mut Bencher) { - let haystack = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"; - let needle = "aaabaaaa"; - - b.bytes = haystack.len() as u64; - b.iter(|| { - assert!(!black_box(haystack).contains(black_box(needle))); - }) -} - -#[bench] -fn bench_contains_equal(b: &mut Bencher) { - let haystack = "Lorem ipsum dolor sit amet, consectetur adipiscing elit."; - let needle = "Lorem ipsum dolor sit amet, consectetur adipiscing elit."; - - b.bytes = haystack.len() as u64; - b.iter(|| { - assert!(black_box(haystack).contains(black_box(needle))); - }) -} - -macro_rules! make_test_inner { - ($s:ident, $code:expr, $name:ident, $str:expr, $iters:expr) => { - #[bench] - fn $name(bencher: &mut Bencher) { - let mut $s = $str; - black_box(&mut $s); - bencher.iter(|| { - for _ in 0..$iters { - black_box($code); - } - }); - } - }; -} - -macro_rules! make_test { - ($name:ident, $s:ident, $code:expr) => { - make_test!($name, $s, $code, 1); - }; - ($name:ident, $s:ident, $code:expr, $iters:expr) => { - mod $name { - use test::Bencher; - use test::black_box; - - // Short strings: 65 bytes each - make_test_inner!($s, $code, short_ascii, - "Mary had a little lamb, Little lamb Mary had a littl lamb, lamb!", $iters); - make_test_inner!($s, $code, short_mixed, - "ศไทย中华Việt Nam; Mary had a little lamb, Little lam!", $iters); - make_test_inner!($s, $code, short_pile_of_poo, - "💩💩💩💩💩💩💩💩💩💩💩💩💩💩💩💩!", $iters); - make_test_inner!($s, $code, long_lorem_ipsum,"\ -Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse quis lorem sit amet dolor \ -ultricies condimentum. Praesent iaculis purus elit, ac malesuada quam malesuada in. Duis sed orci \ -eros. Suspendisse sit amet magna mollis, mollis nunc luctus, imperdiet mi. Integer fringilla non \ -sem ut lacinia. Fusce varius tortor a risus porttitor hendrerit. Morbi mauris dui, ultricies nec \ -tempus vel, gravida nec quam. - -In est dui, tincidunt sed tempus interdum, adipiscing laoreet ante. Etiam tempor, tellus quis \ -sagittis interdum, nulla purus mattis sem, quis auctor erat odio ac tellus. In nec nunc sit amet \ -diam volutpat molestie at sed ipsum. Vestibulum laoreet consequat vulputate. Integer accumsan \ -lorem ac dignissim placerat. Suspendisse convallis faucibus lorem. Aliquam erat volutpat. In vel \ -eleifend felis. Sed suscipit nulla lorem, sed mollis est sollicitudin et. Nam fermentum egestas \ -interdum. Curabitur ut nisi justo. - -Sed sollicitudin ipsum tellus, ut condimentum leo eleifend nec. Cras ut velit ante. Phasellus nec \ -mollis odio. Mauris molestie erat in arcu mattis, at aliquet dolor vehicula. Quisque malesuada \ -lectus sit amet nisi pretium, a condimentum ipsum porta. Morbi at dapibus diam. Praesent egestas \ -est sed risus elementum, eu rutrum metus ultrices. Etiam fermentum consectetur magna, id rutrum \ -felis accumsan a. Aliquam ut pellentesque libero. Sed mi nulla, lobortis eu tortor id, suscipit \ -ultricies neque. Morbi iaculis sit amet risus at iaculis. Praesent eget ligula quis turpis \ -feugiat suscipit vel non arcu. Interdum et malesuada fames ac ante ipsum primis in faucibus. \ -Aliquam sit amet placerat lorem. - -Cras a lacus vel ante posuere elementum. Nunc est leo, bibendum ut facilisis vel, bibendum at \ -mauris. Nullam adipiscing diam vel odio ornare, luctus adipiscing mi luctus. Nulla facilisi. \ -Mauris adipiscing bibendum neque, quis adipiscing lectus tempus et. Sed feugiat erat et nisl \ -lobortis pharetra. Donec vitae erat enim. Nullam sit amet felis et quam lacinia tincidunt. Aliquam \ -suscipit dapibus urna. Sed volutpat urna in magna pulvinar volutpat. Phasellus nec tellus ac diam \ -cursus accumsan. - -Nam lectus enim, dapibus non nisi tempor, consectetur convallis massa. Maecenas eleifend dictum \ -feugiat. Etiam quis mauris vel risus luctus mattis a a nunc. Nullam orci quam, imperdiet id \ -vehicula in, porttitor ut nibh. Duis sagittis adipiscing nisl vitae congue. Donec mollis risus eu \ -leo suscipit, varius porttitor nulla porta. Pellentesque ut sem nec nisi euismod vehicula. Nulla \ -malesuada sollicitudin quam eu fermentum!", $iters); - } - } -} - -make_test!(chars_count, s, s.chars().count()); - -make_test!(contains_bang_str, s, s.contains("!")); -make_test!(contains_bang_char, s, s.contains('!')); - -make_test!(match_indices_a_str, s, s.match_indices("a").count()); - -make_test!(split_a_str, s, s.split("a").count()); - -make_test!(trim_ascii_char, s, { s.trim_matches(|c: char| c.is_ascii()) }); -make_test!(trim_start_ascii_char, s, { s.trim_start_matches(|c: char| c.is_ascii()) }); -make_test!(trim_end_ascii_char, s, { s.trim_end_matches(|c: char| c.is_ascii()) }); - -make_test!(find_underscore_char, s, s.find('_')); -make_test!(rfind_underscore_char, s, s.rfind('_')); -make_test!(find_underscore_str, s, s.find("_")); - -make_test!(find_zzz_char, s, s.find('\u{1F4A4}')); -make_test!(rfind_zzz_char, s, s.rfind('\u{1F4A4}')); -make_test!(find_zzz_str, s, s.find("\u{1F4A4}")); - -make_test!(starts_with_ascii_char, s, s.starts_with('/'), 1024); -make_test!(ends_with_ascii_char, s, s.ends_with('/'), 1024); -make_test!(starts_with_unichar, s, s.starts_with('\u{1F4A4}'), 1024); -make_test!(ends_with_unichar, s, s.ends_with('\u{1F4A4}'), 1024); -make_test!(starts_with_str, s, s.starts_with("💩💩💩💩💩💩💩💩💩💩💩💩💩💩💩💩"), 1024); -make_test!(ends_with_str, s, s.ends_with("💩💩💩💩💩💩💩💩💩💩💩💩💩💩💩💩"), 1024); - -make_test!(split_space_char, s, s.split(' ').count()); -make_test!(split_terminator_space_char, s, s.split_terminator(' ').count()); - -make_test!(splitn_space_char, s, s.splitn(10, ' ').count()); -make_test!(rsplitn_space_char, s, s.rsplitn(10, ' ').count()); - -make_test!(split_space_str, s, s.split(" ").count()); -make_test!(split_ad_str, s, s.split("ad").count()); diff --git a/library/alloc/benches/string.rs b/library/alloc/benches/string.rs deleted file mode 100644 index 5c95160ba2d14..0000000000000 --- a/library/alloc/benches/string.rs +++ /dev/null @@ -1,164 +0,0 @@ -use std::iter::repeat; -use test::{black_box, Bencher}; - -#[bench] -fn bench_with_capacity(b: &mut Bencher) { - b.iter(|| String::with_capacity(100)); -} - -#[bench] -fn bench_push_str(b: &mut Bencher) { - let s = "ศไทย中华Việt Nam; Mary had a little lamb, Little lamb"; - b.iter(|| { - let mut r = String::new(); - r.push_str(s); - }); -} - -const REPETITIONS: u64 = 10_000; - -#[bench] -fn bench_push_str_one_byte(b: &mut Bencher) { - b.bytes = REPETITIONS; - b.iter(|| { - let mut r = String::new(); - for _ in 0..REPETITIONS { - r.push_str("a") - } - }); -} - -#[bench] -fn bench_push_char_one_byte(b: &mut Bencher) { - b.bytes = REPETITIONS; - b.iter(|| { - let mut r = String::new(); - for _ in 0..REPETITIONS { - r.push('a') - } - }); -} - -#[bench] -fn bench_push_char_two_bytes(b: &mut Bencher) { - b.bytes = REPETITIONS * 2; - b.iter(|| { - let mut r = String::new(); - for _ in 0..REPETITIONS { - r.push('â') - } - }); -} - -#[bench] -fn from_utf8_lossy_100_ascii(b: &mut Bencher) { - let s = b"Hello there, the quick brown fox jumped over the lazy dog! \ - Lorem ipsum dolor sit amet, consectetur. "; - - assert_eq!(100, s.len()); - b.iter(|| { - let _ = String::from_utf8_lossy(s); - }); -} - -#[bench] -fn from_utf8_lossy_100_multibyte(b: &mut Bencher) { - let s = "𐌀𐌖𐌋𐌄𐌑𐌉ปรدولة الكويتทศไทย中华𐍅𐌿𐌻𐍆𐌹𐌻𐌰".as_bytes(); - assert_eq!(100, s.len()); - b.iter(|| { - let _ = String::from_utf8_lossy(s); - }); -} - -#[bench] -fn from_utf8_lossy_invalid(b: &mut Bencher) { - let s = b"Hello\xC0\x80 There\xE6\x83 Goodbye"; - b.iter(|| { - let _ = String::from_utf8_lossy(s); - }); -} - -#[bench] -fn from_utf8_lossy_100_invalid(b: &mut Bencher) { - let s = repeat(0xf5).take(100).collect::>(); - b.iter(|| { - let _ = String::from_utf8_lossy(&s); - }); -} - -#[bench] -fn bench_exact_size_shrink_to_fit(b: &mut Bencher) { - let s = "Hello there, the quick brown fox jumped over the lazy dog! \ - Lorem ipsum dolor sit amet, consectetur. "; - // ensure our operation produces an exact-size string before we benchmark it - let mut r = String::with_capacity(s.len()); - r.push_str(s); - assert_eq!(r.len(), r.capacity()); - b.iter(|| { - let mut r = String::with_capacity(s.len()); - r.push_str(s); - r.shrink_to_fit(); - r - }); -} - -#[bench] -fn bench_from_str(b: &mut Bencher) { - let s = "Hello there, the quick brown fox jumped over the lazy dog! \ - Lorem ipsum dolor sit amet, consectetur. "; - b.iter(|| String::from(s)) -} - -#[bench] -fn bench_from(b: &mut Bencher) { - let s = "Hello there, the quick brown fox jumped over the lazy dog! \ - Lorem ipsum dolor sit amet, consectetur. "; - b.iter(|| String::from(s)) -} - -#[bench] -fn bench_to_string(b: &mut Bencher) { - let s = "Hello there, the quick brown fox jumped over the lazy dog! \ - Lorem ipsum dolor sit amet, consectetur. "; - b.iter(|| s.to_string()) -} - -#[bench] -fn bench_insert_char_short(b: &mut Bencher) { - let s = "Hello, World!"; - b.iter(|| { - let mut x = String::from(s); - black_box(&mut x).insert(6, black_box(' ')); - x - }) -} - -#[bench] -fn bench_insert_char_long(b: &mut Bencher) { - let s = "Hello, World!"; - b.iter(|| { - let mut x = String::from(s); - black_box(&mut x).insert(6, black_box('❤')); - x - }) -} - -#[bench] -fn bench_insert_str_short(b: &mut Bencher) { - let s = "Hello, World!"; - b.iter(|| { - let mut x = String::from(s); - black_box(&mut x).insert_str(6, black_box(" ")); - x - }) -} - -#[bench] -fn bench_insert_str_long(b: &mut Bencher) { - let s = "Hello, World!"; - b.iter(|| { - let mut x = String::from(s); - black_box(&mut x).insert_str(6, black_box(" rustic ")); - x - }) -} diff --git a/library/alloc/benches/vec.rs b/library/alloc/benches/vec.rs deleted file mode 100644 index 8ebfe313dc5d5..0000000000000 --- a/library/alloc/benches/vec.rs +++ /dev/null @@ -1,872 +0,0 @@ -use rand::RngCore; -use std::iter::repeat; -use test::{black_box, Bencher}; - -#[bench] -fn bench_new(b: &mut Bencher) { - b.iter(|| Vec::::new()) -} - -fn do_bench_with_capacity(b: &mut Bencher, src_len: usize) { - b.bytes = src_len as u64; - - b.iter(|| Vec::::with_capacity(src_len)) -} - -#[bench] -fn bench_with_capacity_0000(b: &mut Bencher) { - do_bench_with_capacity(b, 0) -} - -#[bench] -fn bench_with_capacity_0010(b: &mut Bencher) { - do_bench_with_capacity(b, 10) -} - -#[bench] -fn bench_with_capacity_0100(b: &mut Bencher) { - do_bench_with_capacity(b, 100) -} - -#[bench] -fn bench_with_capacity_1000(b: &mut Bencher) { - do_bench_with_capacity(b, 1000) -} - -fn do_bench_from_fn(b: &mut Bencher, src_len: usize) { - b.bytes = src_len as u64; - - b.iter(|| (0..src_len).collect::>()) -} - -#[bench] -fn bench_from_fn_0000(b: &mut Bencher) { - do_bench_from_fn(b, 0) -} - -#[bench] -fn bench_from_fn_0010(b: &mut Bencher) { - do_bench_from_fn(b, 10) -} - -#[bench] -fn bench_from_fn_0100(b: &mut Bencher) { - do_bench_from_fn(b, 100) -} - -#[bench] -fn bench_from_fn_1000(b: &mut Bencher) { - do_bench_from_fn(b, 1000) -} - -fn do_bench_from_elem(b: &mut Bencher, src_len: usize) { - b.bytes = src_len as u64; - - b.iter(|| repeat(5).take(src_len).collect::>()) -} - -#[bench] -fn bench_from_elem_0000(b: &mut Bencher) { - do_bench_from_elem(b, 0) -} - -#[bench] -fn bench_from_elem_0010(b: &mut Bencher) { - do_bench_from_elem(b, 10) -} - -#[bench] -fn bench_from_elem_0100(b: &mut Bencher) { - do_bench_from_elem(b, 100) -} - -#[bench] -fn bench_from_elem_1000(b: &mut Bencher) { - do_bench_from_elem(b, 1000) -} - -fn do_bench_from_slice(b: &mut Bencher, src_len: usize) { - let src: Vec<_> = FromIterator::from_iter(0..src_len); - - b.bytes = src_len as u64; - - b.iter(|| src.as_slice().to_vec()); -} - -#[bench] -fn bench_from_slice_0000(b: &mut Bencher) { - do_bench_from_slice(b, 0) -} - -#[bench] -fn bench_from_slice_0010(b: &mut Bencher) { - do_bench_from_slice(b, 10) -} - -#[bench] -fn bench_from_slice_0100(b: &mut Bencher) { - do_bench_from_slice(b, 100) -} - -#[bench] -fn bench_from_slice_1000(b: &mut Bencher) { - do_bench_from_slice(b, 1000) -} - -fn do_bench_from_iter(b: &mut Bencher, src_len: usize) { - let src: Vec<_> = FromIterator::from_iter(0..src_len); - - b.bytes = src_len as u64; - - b.iter(|| { - let dst: Vec<_> = FromIterator::from_iter(src.iter().cloned()); - dst - }); -} - -#[bench] -fn bench_from_iter_0000(b: &mut Bencher) { - do_bench_from_iter(b, 0) -} - -#[bench] -fn bench_from_iter_0010(b: &mut Bencher) { - do_bench_from_iter(b, 10) -} - -#[bench] -fn bench_from_iter_0100(b: &mut Bencher) { - do_bench_from_iter(b, 100) -} - -#[bench] -fn bench_from_iter_1000(b: &mut Bencher) { - do_bench_from_iter(b, 1000) -} - -fn do_bench_extend(b: &mut Bencher, dst_len: usize, src_len: usize) { - let dst: Vec<_> = FromIterator::from_iter(0..dst_len); - let src: Vec<_> = FromIterator::from_iter(dst_len..dst_len + src_len); - - b.bytes = src_len as u64; - - b.iter(|| { - let mut dst = dst.clone(); - dst.extend(src.clone()); - dst - }); -} - -#[bench] -fn bench_extend_0000_0000(b: &mut Bencher) { - do_bench_extend(b, 0, 0) -} - -#[bench] -fn bench_extend_0000_0010(b: &mut Bencher) { - do_bench_extend(b, 0, 10) -} - -#[bench] -fn bench_extend_0000_0100(b: &mut Bencher) { - do_bench_extend(b, 0, 100) -} - -#[bench] -fn bench_extend_0000_1000(b: &mut Bencher) { - do_bench_extend(b, 0, 1000) -} - -#[bench] -fn bench_extend_0010_0010(b: &mut Bencher) { - do_bench_extend(b, 10, 10) -} - -#[bench] -fn bench_extend_0100_0100(b: &mut Bencher) { - do_bench_extend(b, 100, 100) -} - -#[bench] -fn bench_extend_1000_1000(b: &mut Bencher) { - do_bench_extend(b, 1000, 1000) -} - -fn do_bench_extend_from_slice(b: &mut Bencher, dst_len: usize, src_len: usize) { - let dst: Vec<_> = FromIterator::from_iter(0..dst_len); - let src: Vec<_> = FromIterator::from_iter(dst_len..dst_len + src_len); - - b.bytes = src_len as u64; - - b.iter(|| { - let mut dst = dst.clone(); - dst.extend_from_slice(&src); - dst - }); -} - -#[bench] -fn bench_extend_recycle(b: &mut Bencher) { - let mut data = vec![0; 1000]; - - b.iter(|| { - let tmp = std::mem::take(&mut data); - let mut to_extend = black_box(Vec::new()); - to_extend.extend(tmp.into_iter()); - data = black_box(to_extend); - }); - - black_box(data); -} - -#[bench] -fn bench_extend_from_slice_0000_0000(b: &mut Bencher) { - do_bench_extend_from_slice(b, 0, 0) -} - -#[bench] -fn bench_extend_from_slice_0000_0010(b: &mut Bencher) { - do_bench_extend_from_slice(b, 0, 10) -} - -#[bench] -fn bench_extend_from_slice_0000_0100(b: &mut Bencher) { - do_bench_extend_from_slice(b, 0, 100) -} - -#[bench] -fn bench_extend_from_slice_0000_1000(b: &mut Bencher) { - do_bench_extend_from_slice(b, 0, 1000) -} - -#[bench] -fn bench_extend_from_slice_0010_0010(b: &mut Bencher) { - do_bench_extend_from_slice(b, 10, 10) -} - -#[bench] -fn bench_extend_from_slice_0100_0100(b: &mut Bencher) { - do_bench_extend_from_slice(b, 100, 100) -} - -#[bench] -fn bench_extend_from_slice_1000_1000(b: &mut Bencher) { - do_bench_extend_from_slice(b, 1000, 1000) -} - -fn do_bench_clone(b: &mut Bencher, src_len: usize) { - let src: Vec = FromIterator::from_iter(0..src_len); - - b.bytes = src_len as u64; - - b.iter(|| src.clone()); -} - -#[bench] -fn bench_clone_0000(b: &mut Bencher) { - do_bench_clone(b, 0) -} - -#[bench] -fn bench_clone_0010(b: &mut Bencher) { - do_bench_clone(b, 10) -} - -#[bench] -fn bench_clone_0100(b: &mut Bencher) { - do_bench_clone(b, 100) -} - -#[bench] -fn bench_clone_1000(b: &mut Bencher) { - do_bench_clone(b, 1000) -} - -fn do_bench_clone_from(b: &mut Bencher, times: usize, dst_len: usize, src_len: usize) { - let dst: Vec<_> = FromIterator::from_iter(0..src_len); - let src: Vec<_> = FromIterator::from_iter(dst_len..dst_len + src_len); - - b.bytes = (times * src_len) as u64; - - b.iter(|| { - let mut dst = dst.clone(); - - for _ in 0..times { - dst.clone_from(&src); - dst = black_box(dst); - } - dst - }); -} - -#[bench] -fn bench_clone_from_01_0000_0000(b: &mut Bencher) { - do_bench_clone_from(b, 1, 0, 0) -} - -#[bench] -fn bench_clone_from_01_0000_0010(b: &mut Bencher) { - do_bench_clone_from(b, 1, 0, 10) -} - -#[bench] -fn bench_clone_from_01_0000_0100(b: &mut Bencher) { - do_bench_clone_from(b, 1, 0, 100) -} - -#[bench] -fn bench_clone_from_01_0000_1000(b: &mut Bencher) { - do_bench_clone_from(b, 1, 0, 1000) -} - -#[bench] -fn bench_clone_from_01_0010_0010(b: &mut Bencher) { - do_bench_clone_from(b, 1, 10, 10) -} - -#[bench] -fn bench_clone_from_01_0100_0100(b: &mut Bencher) { - do_bench_clone_from(b, 1, 100, 100) -} - -#[bench] -fn bench_clone_from_01_1000_1000(b: &mut Bencher) { - do_bench_clone_from(b, 1, 1000, 1000) -} - -#[bench] -fn bench_clone_from_01_0010_0100(b: &mut Bencher) { - do_bench_clone_from(b, 1, 10, 100) -} - -#[bench] -fn bench_clone_from_01_0100_1000(b: &mut Bencher) { - do_bench_clone_from(b, 1, 100, 1000) -} - -#[bench] -fn bench_clone_from_01_0010_0000(b: &mut Bencher) { - do_bench_clone_from(b, 1, 10, 0) -} - -#[bench] -fn bench_clone_from_01_0100_0010(b: &mut Bencher) { - do_bench_clone_from(b, 1, 100, 10) -} - -#[bench] -fn bench_clone_from_01_1000_0100(b: &mut Bencher) { - do_bench_clone_from(b, 1, 1000, 100) -} - -#[bench] -fn bench_clone_from_10_0000_0000(b: &mut Bencher) { - do_bench_clone_from(b, 10, 0, 0) -} - -#[bench] -fn bench_clone_from_10_0000_0010(b: &mut Bencher) { - do_bench_clone_from(b, 10, 0, 10) -} - -#[bench] -fn bench_clone_from_10_0000_0100(b: &mut Bencher) { - do_bench_clone_from(b, 10, 0, 100) -} - -#[bench] -fn bench_clone_from_10_0000_1000(b: &mut Bencher) { - do_bench_clone_from(b, 10, 0, 1000) -} - -#[bench] -fn bench_clone_from_10_0010_0010(b: &mut Bencher) { - do_bench_clone_from(b, 10, 10, 10) -} - -#[bench] -fn bench_clone_from_10_0100_0100(b: &mut Bencher) { - do_bench_clone_from(b, 10, 100, 100) -} - -#[bench] -fn bench_clone_from_10_1000_1000(b: &mut Bencher) { - do_bench_clone_from(b, 10, 1000, 1000) -} - -#[bench] -fn bench_clone_from_10_0010_0100(b: &mut Bencher) { - do_bench_clone_from(b, 10, 10, 100) -} - -#[bench] -fn bench_clone_from_10_0100_1000(b: &mut Bencher) { - do_bench_clone_from(b, 10, 100, 1000) -} - -#[bench] -fn bench_clone_from_10_0010_0000(b: &mut Bencher) { - do_bench_clone_from(b, 10, 10, 0) -} - -#[bench] -fn bench_clone_from_10_0100_0010(b: &mut Bencher) { - do_bench_clone_from(b, 10, 100, 10) -} - -#[bench] -fn bench_clone_from_10_1000_0100(b: &mut Bencher) { - do_bench_clone_from(b, 10, 1000, 100) -} - -macro_rules! bench_in_place { - ($($fname:ident, $type:ty, $count:expr, $init:expr);*) => { - $( - #[bench] - fn $fname(b: &mut Bencher) { - b.iter(|| { - let src: Vec<$type> = black_box(vec![$init; $count]); - src.into_iter() - .enumerate() - .map(|(idx, e)| idx as $type ^ e) - .collect::>() - }); - } - )+ - }; -} - -bench_in_place![ - bench_in_place_xxu8_0010_i0, u8, 10, 0; - bench_in_place_xxu8_0100_i0, u8, 100, 0; - bench_in_place_xxu8_1000_i0, u8, 1000, 0; - bench_in_place_xxu8_0010_i1, u8, 10, 1; - bench_in_place_xxu8_0100_i1, u8, 100, 1; - bench_in_place_xxu8_1000_i1, u8, 1000, 1; - bench_in_place_xu32_0010_i0, u32, 10, 0; - bench_in_place_xu32_0100_i0, u32, 100, 0; - bench_in_place_xu32_1000_i0, u32, 1000, 0; - bench_in_place_xu32_0010_i1, u32, 10, 1; - bench_in_place_xu32_0100_i1, u32, 100, 1; - bench_in_place_xu32_1000_i1, u32, 1000, 1; - bench_in_place_u128_0010_i0, u128, 10, 0; - bench_in_place_u128_0100_i0, u128, 100, 0; - bench_in_place_u128_1000_i0, u128, 1000, 0; - bench_in_place_u128_0010_i1, u128, 10, 1; - bench_in_place_u128_0100_i1, u128, 100, 1; - bench_in_place_u128_1000_i1, u128, 1000, 1 -]; - -#[bench] -fn bench_in_place_recycle(b: &mut Bencher) { - let mut data = vec![0; 1000]; - - b.iter(|| { - let tmp = std::mem::take(&mut data); - data = black_box( - tmp.into_iter() - .enumerate() - .map(|(idx, e)| idx.wrapping_add(e)) - .fuse() - .collect::>(), - ); - }); -} - -#[bench] -fn bench_in_place_zip_recycle(b: &mut Bencher) { - let mut data = vec![0u8; 1000]; - let mut rng = crate::bench_rng(); - let mut subst = vec![0u8; 1000]; - rng.fill_bytes(&mut subst[..]); - - b.iter(|| { - let tmp = std::mem::take(&mut data); - let mangled = tmp - .into_iter() - .zip(subst.iter().copied()) - .enumerate() - .map(|(i, (d, s))| d.wrapping_add(i as u8) ^ s) - .collect::>(); - data = black_box(mangled); - }); -} - -#[bench] -fn bench_in_place_zip_iter_mut(b: &mut Bencher) { - let mut data = vec![0u8; 256]; - let mut rng = crate::bench_rng(); - let mut subst = vec![0u8; 1000]; - rng.fill_bytes(&mut subst[..]); - - b.iter(|| { - data.iter_mut().enumerate().for_each(|(i, d)| { - *d = d.wrapping_add(i as u8) ^ subst[i]; - }); - }); - - black_box(data); -} - -pub fn vec_cast(input: Vec) -> Vec { - input.into_iter().map(|e| unsafe { std::mem::transmute_copy(&e) }).collect() -} - -#[bench] -fn bench_transmute(b: &mut Bencher) { - let mut vec = vec![10u32; 100]; - b.bytes = 800; // 2 casts x 4 bytes x 100 - b.iter(|| { - let v = std::mem::take(&mut vec); - let v = black_box(vec_cast::(v)); - let v = black_box(vec_cast::(v)); - vec = v; - }); -} - -#[derive(Clone)] -struct Droppable(usize); - -impl Drop for Droppable { - fn drop(&mut self) { - black_box(self); - } -} - -#[bench] -fn bench_in_place_collect_droppable(b: &mut Bencher) { - let v: Vec = std::iter::repeat_with(|| Droppable(0)).take(1000).collect(); - b.iter(|| { - v.clone() - .into_iter() - .skip(100) - .enumerate() - .map(|(i, e)| Droppable(i ^ e.0)) - .collect::>() - }) -} - -const LEN: usize = 16384; - -#[bench] -fn bench_chain_collect(b: &mut Bencher) { - let data = black_box([0; LEN]); - b.iter(|| data.iter().cloned().chain([1]).collect::>()); -} - -#[bench] -fn bench_chain_chain_collect(b: &mut Bencher) { - let data = black_box([0; LEN]); - b.iter(|| data.iter().cloned().chain([1]).chain([2]).collect::>()); -} - -#[bench] -fn bench_nest_chain_chain_collect(b: &mut Bencher) { - let data = black_box([0; LEN]); - b.iter(|| { - data.iter().cloned().chain([1].iter().chain([2].iter()).cloned()).collect::>() - }); -} - -#[bench] -fn bench_range_map_collect(b: &mut Bencher) { - b.iter(|| (0..LEN).map(|_| u32::default()).collect::>()); -} - -#[bench] -fn bench_chain_extend_ref(b: &mut Bencher) { - let data = black_box([0; LEN]); - b.iter(|| { - let mut v = Vec::::with_capacity(data.len() + 1); - v.extend(data.iter().chain([1].iter())); - v - }); -} - -#[bench] -fn bench_chain_extend_value(b: &mut Bencher) { - let data = black_box([0; LEN]); - b.iter(|| { - let mut v = Vec::::with_capacity(data.len() + 1); - v.extend(data.iter().cloned().chain(Some(1))); - v - }); -} - -#[bench] -fn bench_rev_1(b: &mut Bencher) { - let data = black_box([0; LEN]); - b.iter(|| { - let mut v = Vec::::new(); - v.extend(data.iter().rev()); - v - }); -} - -#[bench] -fn bench_rev_2(b: &mut Bencher) { - let data = black_box([0; LEN]); - b.iter(|| { - let mut v = Vec::::with_capacity(data.len()); - v.extend(data.iter().rev()); - v - }); -} - -#[bench] -fn bench_map_regular(b: &mut Bencher) { - let data = black_box([(0, 0); LEN]); - b.iter(|| { - let mut v = Vec::::new(); - v.extend(data.iter().map(|t| t.1)); - v - }); -} - -#[bench] -fn bench_map_fast(b: &mut Bencher) { - let data = black_box([(0, 0); LEN]); - b.iter(|| { - let mut result: Vec = Vec::with_capacity(data.len()); - for i in 0..data.len() { - unsafe { - *result.as_mut_ptr().add(i) = data[i].0; - result.set_len(i); - } - } - result - }); -} - -fn random_sorted_fill(mut seed: u32, buf: &mut [u32]) { - let mask = if buf.len() < 8192 { - 0xFF - } else if buf.len() < 200_000 { - 0xFFFF - } else { - 0xFFFF_FFFF - }; - - for item in buf.iter_mut() { - seed ^= seed << 13; - seed ^= seed >> 17; - seed ^= seed << 5; - - *item = seed & mask; - } - - buf.sort(); -} - -// Measures performance of slice dedup impl. -// This was used to justify separate implementation of dedup for Vec. -// This algorithm was used for Vecs prior to Rust 1.52. -fn bench_dedup_slice_truncate(b: &mut Bencher, sz: usize) { - let mut template = vec![0u32; sz]; - b.bytes = std::mem::size_of_val(template.as_slice()) as u64; - random_sorted_fill(0x43, &mut template); - - let mut vec = template.clone(); - b.iter(|| { - let vec = black_box(&mut vec); - let len = { - let (dedup, _) = vec.partition_dedup(); - dedup.len() - }; - vec.truncate(len); - - black_box(vec.first()); - let vec = black_box(vec); - vec.clear(); - vec.extend_from_slice(&template); - }); -} - -// Measures performance of Vec::dedup on random data. -fn bench_vec_dedup_random(b: &mut Bencher, sz: usize) { - let mut template = vec![0u32; sz]; - b.bytes = std::mem::size_of_val(template.as_slice()) as u64; - random_sorted_fill(0x43, &mut template); - - let mut vec = template.clone(); - b.iter(|| { - let vec = black_box(&mut vec); - vec.dedup(); - black_box(vec.first()); - let vec = black_box(vec); - vec.clear(); - vec.extend_from_slice(&template); - }); -} - -// Measures performance of Vec::dedup when there is no items removed -fn bench_vec_dedup_none(b: &mut Bencher, sz: usize) { - let mut template = vec![0u32; sz]; - b.bytes = std::mem::size_of_val(template.as_slice()) as u64; - template.chunks_exact_mut(2).for_each(|w| { - w[0] = black_box(0); - w[1] = black_box(5); - }); - - let mut vec = template.clone(); - b.iter(|| { - let vec = black_box(&mut vec); - vec.dedup(); - black_box(vec.first()); - // Unlike other benches of `dedup` - // this doesn't reinitialize vec - // because we measure how efficient dedup is - // when no memory written - }); -} - -// Measures performance of Vec::dedup when there is all items removed -fn bench_vec_dedup_all(b: &mut Bencher, sz: usize) { - let mut template = vec![0u32; sz]; - b.bytes = std::mem::size_of_val(template.as_slice()) as u64; - template.iter_mut().for_each(|w| { - *w = black_box(0); - }); - - let mut vec = template.clone(); - b.iter(|| { - let vec = black_box(&mut vec); - vec.dedup(); - black_box(vec.first()); - let vec = black_box(vec); - vec.clear(); - vec.extend_from_slice(&template); - }); -} - -#[bench] -fn bench_dedup_slice_truncate_100(b: &mut Bencher) { - bench_dedup_slice_truncate(b, 100); -} -#[bench] -fn bench_dedup_random_100(b: &mut Bencher) { - bench_vec_dedup_random(b, 100); -} - -#[bench] -fn bench_dedup_none_100(b: &mut Bencher) { - bench_vec_dedup_none(b, 100); -} - -#[bench] -fn bench_dedup_all_100(b: &mut Bencher) { - bench_vec_dedup_all(b, 100); -} - -#[bench] -fn bench_dedup_slice_truncate_1000(b: &mut Bencher) { - bench_dedup_slice_truncate(b, 1000); -} -#[bench] -fn bench_dedup_random_1000(b: &mut Bencher) { - bench_vec_dedup_random(b, 1000); -} - -#[bench] -fn bench_dedup_none_1000(b: &mut Bencher) { - bench_vec_dedup_none(b, 1000); -} - -#[bench] -fn bench_dedup_all_1000(b: &mut Bencher) { - bench_vec_dedup_all(b, 1000); -} - -#[bench] -fn bench_dedup_slice_truncate_10000(b: &mut Bencher) { - bench_dedup_slice_truncate(b, 10000); -} -#[bench] -fn bench_dedup_random_10000(b: &mut Bencher) { - bench_vec_dedup_random(b, 10000); -} - -#[bench] -fn bench_dedup_none_10000(b: &mut Bencher) { - bench_vec_dedup_none(b, 10000); -} - -#[bench] -fn bench_dedup_all_10000(b: &mut Bencher) { - bench_vec_dedup_all(b, 10000); -} - -#[bench] -fn bench_dedup_slice_truncate_100000(b: &mut Bencher) { - bench_dedup_slice_truncate(b, 100000); -} -#[bench] -fn bench_dedup_random_100000(b: &mut Bencher) { - bench_vec_dedup_random(b, 100000); -} - -#[bench] -fn bench_dedup_none_100000(b: &mut Bencher) { - bench_vec_dedup_none(b, 100000); -} - -#[bench] -fn bench_dedup_all_100000(b: &mut Bencher) { - bench_vec_dedup_all(b, 100000); -} - -#[bench] -fn bench_flat_map_collect(b: &mut Bencher) { - let v = vec![777u32; 500000]; - b.iter(|| v.iter().flat_map(|color| color.rotate_left(8).to_be_bytes()).collect::>()); -} - -/// Reference benchmark that `retain` has to compete with. -#[bench] -fn bench_retain_iter_100000(b: &mut Bencher) { - let mut v = Vec::with_capacity(100000); - - b.iter(|| { - let mut tmp = std::mem::take(&mut v); - tmp.clear(); - tmp.extend(black_box(1..=100000)); - v = tmp.into_iter().filter(|x| x & 1 == 0).collect(); - }); -} - -#[bench] -fn bench_retain_100000(b: &mut Bencher) { - let mut v = Vec::with_capacity(100000); - - b.iter(|| { - v.clear(); - v.extend(black_box(1..=100000)); - v.retain(|x| x & 1 == 0) - }); -} - -#[bench] -fn bench_retain_whole_100000(b: &mut Bencher) { - let mut v = black_box(vec![826u32; 100000]); - b.iter(|| v.retain(|x| *x == 826u32)); -} - -#[bench] -fn bench_next_chunk(b: &mut Bencher) { - let v = vec![13u8; 2048]; - - b.iter(|| { - const CHUNK: usize = 8; - - let mut sum = [0u32; CHUNK]; - let mut iter = black_box(v.clone()).into_iter(); - - while let Ok(chunk) = iter.next_chunk::() { - for i in 0..CHUNK { - sum[i] += chunk[i] as u32; - } - } - - sum - }) -} diff --git a/library/alloc/benches/vec_deque.rs b/library/alloc/benches/vec_deque.rs deleted file mode 100644 index 35939f489b45d..0000000000000 --- a/library/alloc/benches/vec_deque.rs +++ /dev/null @@ -1,268 +0,0 @@ -use std::{ - collections::{vec_deque, VecDeque}, - mem, -}; -use test::{black_box, Bencher}; - -#[bench] -fn bench_new(b: &mut Bencher) { - b.iter(|| { - let ring: VecDeque = VecDeque::new(); - black_box(ring); - }) -} - -#[bench] -fn bench_grow_1025(b: &mut Bencher) { - b.iter(|| { - let mut deq = VecDeque::new(); - for i in 0..1025 { - deq.push_front(i); - } - black_box(deq); - }) -} - -#[bench] -fn bench_iter_1000(b: &mut Bencher) { - let ring: VecDeque<_> = (0..1000).collect(); - - b.iter(|| { - let mut sum = 0; - for &i in &ring { - sum += i; - } - black_box(sum); - }) -} - -#[bench] -fn bench_mut_iter_1000(b: &mut Bencher) { - let mut ring: VecDeque<_> = (0..1000).collect(); - - b.iter(|| { - let mut sum = 0; - for i in &mut ring { - sum += *i; - } - black_box(sum); - }) -} - -#[bench] -fn bench_try_fold(b: &mut Bencher) { - let ring: VecDeque<_> = (0..1000).collect(); - - b.iter(|| black_box(ring.iter().try_fold(0, |a, b| Some(a + b)))) -} - -/// does the memory bookkeeping to reuse the buffer of the Vec between iterations. -/// `setup` must not modify its argument's length or capacity. `g` must not move out of its argument. -fn into_iter_helper< - T: Copy, - F: FnOnce(&mut VecDeque), - G: FnOnce(&mut vec_deque::IntoIter), ->( - v: &mut Vec, - setup: F, - g: G, -) { - let ptr = v.as_mut_ptr(); - let len = v.len(); - // ensure that the vec is full, to make sure that any wrapping from the deque doesn't - // access uninitialized memory. - assert_eq!(v.len(), v.capacity()); - - let mut deque = VecDeque::from(mem::take(v)); - setup(&mut deque); - - let mut it = deque.into_iter(); - g(&mut it); - - mem::forget(it); - - // SAFETY: the provided functions are not allowed to modify the allocation, so the buffer is still alive. - // len and capacity are accurate due to the above assertion. - // All the elements in the buffer are still valid, because of `T: Copy` which implies `T: !Drop`. - mem::forget(mem::replace(v, unsafe { Vec::from_raw_parts(ptr, len, len) })); -} - -#[bench] -fn bench_into_iter(b: &mut Bencher) { - let len = 1024; - // we reuse this allocation for every run - let mut vec: Vec = (0..len).collect(); - vec.shrink_to_fit(); - - b.iter(|| { - let mut sum = 0; - into_iter_helper( - &mut vec, - |_| {}, - |it| { - for i in it { - sum += i; - } - }, - ); - black_box(sum); - - let mut sum = 0; - // rotating a full deque doesn't move any memory. - into_iter_helper( - &mut vec, - |d| d.rotate_left(len / 2), - |it| { - for i in it { - sum += i; - } - }, - ); - black_box(sum); - }); -} - -#[bench] -fn bench_into_iter_fold(b: &mut Bencher) { - let len = 1024; - - // because `fold` takes ownership of the iterator, - // we can't prevent it from dropping the memory, - // so we have to bite the bullet and reallocate - // for every iteration. - b.iter(|| { - let deque: VecDeque = (0..len).collect(); - assert_eq!(deque.len(), deque.capacity()); - let sum = deque.into_iter().fold(0, |a, b| a + b); - black_box(sum); - - // rotating a full deque doesn't move any memory. - let mut deque: VecDeque = (0..len).collect(); - assert_eq!(deque.len(), deque.capacity()); - deque.rotate_left(len / 2); - let sum = deque.into_iter().fold(0, |a, b| a + b); - black_box(sum); - }); -} - -#[bench] -fn bench_into_iter_try_fold(b: &mut Bencher) { - let len = 1024; - // we reuse this allocation for every run - let mut vec: Vec = (0..len).collect(); - vec.shrink_to_fit(); - - // Iterator::any uses Iterator::try_fold under the hood - b.iter(|| { - let mut b = false; - into_iter_helper(&mut vec, |_| {}, |it| b = it.any(|i| i == len - 1)); - black_box(b); - - into_iter_helper(&mut vec, |d| d.rotate_left(len / 2), |it| b = it.any(|i| i == len - 1)); - black_box(b); - }); -} - -#[bench] -fn bench_into_iter_next_chunk(b: &mut Bencher) { - let len = 1024; - // we reuse this allocation for every run - let mut vec: Vec = (0..len).collect(); - vec.shrink_to_fit(); - - b.iter(|| { - let mut buf = [0; 64]; - into_iter_helper( - &mut vec, - |_| {}, - |it| { - while let Ok(a) = it.next_chunk() { - buf = a; - } - }, - ); - black_box(buf); - - into_iter_helper( - &mut vec, - |d| d.rotate_left(len / 2), - |it| { - while let Ok(a) = it.next_chunk() { - buf = a; - } - }, - ); - black_box(buf); - }); -} - -#[bench] -fn bench_from_array_1000(b: &mut Bencher) { - const N: usize = 1000; - let mut array: [usize; N] = [0; N]; - - for i in 0..N { - array[i] = i; - } - - b.iter(|| { - let deq: VecDeque<_> = array.into(); - black_box(deq); - }) -} - -#[bench] -fn bench_extend_bytes(b: &mut Bencher) { - let mut ring: VecDeque = VecDeque::with_capacity(1000); - let input: &[u8] = &[128; 512]; - - b.iter(|| { - ring.clear(); - ring.extend(black_box(input)); - }); -} - -#[bench] -fn bench_extend_vec(b: &mut Bencher) { - let mut ring: VecDeque = VecDeque::with_capacity(1000); - let input = vec![128; 512]; - - b.iter(|| { - ring.clear(); - - let input = input.clone(); - ring.extend(black_box(input)); - }); -} - -#[bench] -fn bench_extend_trustedlen(b: &mut Bencher) { - let mut ring: VecDeque = VecDeque::with_capacity(1000); - - b.iter(|| { - ring.clear(); - ring.extend(black_box(0..512)); - }); -} - -#[bench] -fn bench_extend_chained_trustedlen(b: &mut Bencher) { - let mut ring: VecDeque = VecDeque::with_capacity(1000); - - b.iter(|| { - ring.clear(); - ring.extend(black_box((0..256).chain(768..1024))); - }); -} - -#[bench] -fn bench_extend_chained_bytes(b: &mut Bencher) { - let mut ring: VecDeque = VecDeque::with_capacity(1000); - let input1: &[u16] = &[128; 256]; - let input2: &[u16] = &[255; 256]; - - b.iter(|| { - ring.clear(); - ring.extend(black_box(input1.iter().chain(input2.iter()))); - }); -} diff --git a/library/alloc/benches/vec_deque_append.rs b/library/alloc/benches/vec_deque_append.rs deleted file mode 100644 index 30b6e600e5adc..0000000000000 --- a/library/alloc/benches/vec_deque_append.rs +++ /dev/null @@ -1,39 +0,0 @@ -use std::{collections::VecDeque, time::Instant}; - -const VECDEQUE_LEN: i32 = 100000; -const WARMUP_N: usize = 100; -const BENCH_N: usize = 1000; - -fn main() { - if cfg!(miri) { - // Don't benchmark Miri... - // (Due to bootstrap quirks, this gets picked up by `x.py miri library/alloc --no-doc`.) - return; - } - let a: VecDeque = (0..VECDEQUE_LEN).collect(); - let b: VecDeque = (0..VECDEQUE_LEN).collect(); - - for _ in 0..WARMUP_N { - let mut c = a.clone(); - let mut d = b.clone(); - c.append(&mut d); - } - - let mut durations = Vec::with_capacity(BENCH_N); - - for _ in 0..BENCH_N { - let mut c = a.clone(); - let mut d = b.clone(); - let before = Instant::now(); - c.append(&mut d); - let after = Instant::now(); - durations.push(after.duration_since(before)); - } - - let l = durations.len(); - durations.sort(); - - assert!(BENCH_N % 2 == 0); - let median = (durations[(l / 2) - 1] + durations[l / 2]) / 2; - println!("\ncustom-bench vec_deque_append {:?} ns/iter\n", median.as_nanos()); -} diff --git a/library/alloc/src/alloc.rs b/library/alloc/src/alloc.rs deleted file mode 100644 index 6677534eafc6e..0000000000000 --- a/library/alloc/src/alloc.rs +++ /dev/null @@ -1,452 +0,0 @@ -//! Memory allocation APIs - -#![stable(feature = "alloc_module", since = "1.28.0")] - -#[cfg(not(test))] -use core::hint; - -#[cfg(not(test))] -use core::ptr::{self, NonNull}; - -#[stable(feature = "alloc_module", since = "1.28.0")] -#[doc(inline)] -pub use core::alloc::*; - -#[cfg(test)] -mod tests; - -extern "Rust" { - // These are the magic symbols to call the global allocator. rustc generates - // them to call `__rg_alloc` etc. if there is a `#[global_allocator]` attribute - // (the code expanding that attribute macro generates those functions), or to call - // the default implementations in std (`__rdl_alloc` etc. in `library/std/src/alloc.rs`) - // otherwise. - // The rustc fork of LLVM 14 and earlier also special-cases these function names to be able to optimize them - // like `malloc`, `realloc`, and `free`, respectively. - #[rustc_allocator] - #[rustc_nounwind] - fn __rust_alloc(size: usize, align: usize) -> *mut u8; - #[rustc_deallocator] - #[rustc_nounwind] - fn __rust_dealloc(ptr: *mut u8, size: usize, align: usize); - #[rustc_reallocator] - #[rustc_nounwind] - fn __rust_realloc(ptr: *mut u8, old_size: usize, align: usize, new_size: usize) -> *mut u8; - #[rustc_allocator_zeroed] - #[rustc_nounwind] - fn __rust_alloc_zeroed(size: usize, align: usize) -> *mut u8; - - static __rust_no_alloc_shim_is_unstable: u8; -} - -/// The global memory allocator. -/// -/// This type implements the [`Allocator`] trait by forwarding calls -/// to the allocator registered with the `#[global_allocator]` attribute -/// if there is one, or the `std` crate’s default. -/// -/// Note: while this type is unstable, the functionality it provides can be -/// accessed through the [free functions in `alloc`](self#functions). -#[unstable(feature = "allocator_api", issue = "32838")] -#[derive(Copy, Clone, Default, Debug)] -#[cfg(not(test))] -// the compiler needs to know when a Box uses the global allocator vs a custom one -#[lang = "global_alloc_ty"] -pub struct Global; - -#[cfg(test)] -pub use std::alloc::Global; - -/// Allocate memory with the global allocator. -/// -/// This function forwards calls to the [`GlobalAlloc::alloc`] method -/// of the allocator registered with the `#[global_allocator]` attribute -/// if there is one, or the `std` crate’s default. -/// -/// This function is expected to be deprecated in favor of the `alloc` method -/// of the [`Global`] type when it and the [`Allocator`] trait become stable. -/// -/// # Safety -/// -/// See [`GlobalAlloc::alloc`]. -/// -/// # Examples -/// -/// ``` -/// use std::alloc::{alloc, dealloc, handle_alloc_error, Layout}; -/// -/// unsafe { -/// let layout = Layout::new::(); -/// let ptr = alloc(layout); -/// if ptr.is_null() { -/// handle_alloc_error(layout); -/// } -/// -/// *(ptr as *mut u16) = 42; -/// assert_eq!(*(ptr as *mut u16), 42); -/// -/// dealloc(ptr, layout); -/// } -/// ``` -#[stable(feature = "global_alloc", since = "1.28.0")] -#[must_use = "losing the pointer will leak memory"] -#[inline] -pub unsafe fn alloc(layout: Layout) -> *mut u8 { - unsafe { - // Make sure we don't accidentally allow omitting the allocator shim in - // stable code until it is actually stabilized. - core::ptr::read_volatile(&__rust_no_alloc_shim_is_unstable); - - __rust_alloc(layout.size(), layout.align()) - } -} - -/// Deallocate memory with the global allocator. -/// -/// This function forwards calls to the [`GlobalAlloc::dealloc`] method -/// of the allocator registered with the `#[global_allocator]` attribute -/// if there is one, or the `std` crate’s default. -/// -/// This function is expected to be deprecated in favor of the `dealloc` method -/// of the [`Global`] type when it and the [`Allocator`] trait become stable. -/// -/// # Safety -/// -/// See [`GlobalAlloc::dealloc`]. -#[stable(feature = "global_alloc", since = "1.28.0")] -#[inline] -pub unsafe fn dealloc(ptr: *mut u8, layout: Layout) { - unsafe { __rust_dealloc(ptr, layout.size(), layout.align()) } -} - -/// Reallocate memory with the global allocator. -/// -/// This function forwards calls to the [`GlobalAlloc::realloc`] method -/// of the allocator registered with the `#[global_allocator]` attribute -/// if there is one, or the `std` crate’s default. -/// -/// This function is expected to be deprecated in favor of the `realloc` method -/// of the [`Global`] type when it and the [`Allocator`] trait become stable. -/// -/// # Safety -/// -/// See [`GlobalAlloc::realloc`]. -#[stable(feature = "global_alloc", since = "1.28.0")] -#[must_use = "losing the pointer will leak memory"] -#[inline] -pub unsafe fn realloc(ptr: *mut u8, layout: Layout, new_size: usize) -> *mut u8 { - unsafe { __rust_realloc(ptr, layout.size(), layout.align(), new_size) } -} - -/// Allocate zero-initialized memory with the global allocator. -/// -/// This function forwards calls to the [`GlobalAlloc::alloc_zeroed`] method -/// of the allocator registered with the `#[global_allocator]` attribute -/// if there is one, or the `std` crate’s default. -/// -/// This function is expected to be deprecated in favor of the `alloc_zeroed` method -/// of the [`Global`] type when it and the [`Allocator`] trait become stable. -/// -/// # Safety -/// -/// See [`GlobalAlloc::alloc_zeroed`]. -/// -/// # Examples -/// -/// ``` -/// use std::alloc::{alloc_zeroed, dealloc, Layout}; -/// -/// unsafe { -/// let layout = Layout::new::(); -/// let ptr = alloc_zeroed(layout); -/// -/// assert_eq!(*(ptr as *mut u16), 0); -/// -/// dealloc(ptr, layout); -/// } -/// ``` -#[stable(feature = "global_alloc", since = "1.28.0")] -#[must_use = "losing the pointer will leak memory"] -#[inline] -pub unsafe fn alloc_zeroed(layout: Layout) -> *mut u8 { - unsafe { __rust_alloc_zeroed(layout.size(), layout.align()) } -} - -#[cfg(not(test))] -impl Global { - #[inline] - fn alloc_impl(&self, layout: Layout, zeroed: bool) -> Result, AllocError> { - match layout.size() { - 0 => Ok(NonNull::slice_from_raw_parts(layout.dangling(), 0)), - // SAFETY: `layout` is non-zero in size, - size => unsafe { - let raw_ptr = if zeroed { alloc_zeroed(layout) } else { alloc(layout) }; - let ptr = NonNull::new(raw_ptr).ok_or(AllocError)?; - Ok(NonNull::slice_from_raw_parts(ptr, size)) - }, - } - } - - // SAFETY: Same as `Allocator::grow` - #[inline] - unsafe fn grow_impl( - &self, - ptr: NonNull, - old_layout: Layout, - new_layout: Layout, - zeroed: bool, - ) -> Result, AllocError> { - debug_assert!( - new_layout.size() >= old_layout.size(), - "`new_layout.size()` must be greater than or equal to `old_layout.size()`" - ); - - match old_layout.size() { - 0 => self.alloc_impl(new_layout, zeroed), - - // SAFETY: `new_size` is non-zero as `old_size` is greater than or equal to `new_size` - // as required by safety conditions. Other conditions must be upheld by the caller - old_size if old_layout.align() == new_layout.align() => unsafe { - let new_size = new_layout.size(); - - // `realloc` probably checks for `new_size >= old_layout.size()` or something similar. - hint::assert_unchecked(new_size >= old_layout.size()); - - let raw_ptr = realloc(ptr.as_ptr(), old_layout, new_size); - let ptr = NonNull::new(raw_ptr).ok_or(AllocError)?; - if zeroed { - raw_ptr.add(old_size).write_bytes(0, new_size - old_size); - } - Ok(NonNull::slice_from_raw_parts(ptr, new_size)) - }, - - // SAFETY: because `new_layout.size()` must be greater than or equal to `old_size`, - // both the old and new memory allocation are valid for reads and writes for `old_size` - // bytes. Also, because the old allocation wasn't yet deallocated, it cannot overlap - // `new_ptr`. Thus, the call to `copy_nonoverlapping` is safe. The safety contract - // for `dealloc` must be upheld by the caller. - old_size => unsafe { - let new_ptr = self.alloc_impl(new_layout, zeroed)?; - ptr::copy_nonoverlapping(ptr.as_ptr(), new_ptr.as_mut_ptr(), old_size); - self.deallocate(ptr, old_layout); - Ok(new_ptr) - }, - } - } -} - -#[unstable(feature = "allocator_api", issue = "32838")] -#[cfg(not(test))] -unsafe impl Allocator for Global { - #[inline] - fn allocate(&self, layout: Layout) -> Result, AllocError> { - self.alloc_impl(layout, false) - } - - #[inline] - fn allocate_zeroed(&self, layout: Layout) -> Result, AllocError> { - self.alloc_impl(layout, true) - } - - #[inline] - unsafe fn deallocate(&self, ptr: NonNull, layout: Layout) { - if layout.size() != 0 { - // SAFETY: `layout` is non-zero in size, - // other conditions must be upheld by the caller - unsafe { dealloc(ptr.as_ptr(), layout) } - } - } - - #[inline] - unsafe fn grow( - &self, - ptr: NonNull, - old_layout: Layout, - new_layout: Layout, - ) -> Result, AllocError> { - // SAFETY: all conditions must be upheld by the caller - unsafe { self.grow_impl(ptr, old_layout, new_layout, false) } - } - - #[inline] - unsafe fn grow_zeroed( - &self, - ptr: NonNull, - old_layout: Layout, - new_layout: Layout, - ) -> Result, AllocError> { - // SAFETY: all conditions must be upheld by the caller - unsafe { self.grow_impl(ptr, old_layout, new_layout, true) } - } - - #[inline] - unsafe fn shrink( - &self, - ptr: NonNull, - old_layout: Layout, - new_layout: Layout, - ) -> Result, AllocError> { - debug_assert!( - new_layout.size() <= old_layout.size(), - "`new_layout.size()` must be smaller than or equal to `old_layout.size()`" - ); - - match new_layout.size() { - // SAFETY: conditions must be upheld by the caller - 0 => unsafe { - self.deallocate(ptr, old_layout); - Ok(NonNull::slice_from_raw_parts(new_layout.dangling(), 0)) - }, - - // SAFETY: `new_size` is non-zero. Other conditions must be upheld by the caller - new_size if old_layout.align() == new_layout.align() => unsafe { - // `realloc` probably checks for `new_size <= old_layout.size()` or something similar. - hint::assert_unchecked(new_size <= old_layout.size()); - - let raw_ptr = realloc(ptr.as_ptr(), old_layout, new_size); - let ptr = NonNull::new(raw_ptr).ok_or(AllocError)?; - Ok(NonNull::slice_from_raw_parts(ptr, new_size)) - }, - - // SAFETY: because `new_size` must be smaller than or equal to `old_layout.size()`, - // both the old and new memory allocation are valid for reads and writes for `new_size` - // bytes. Also, because the old allocation wasn't yet deallocated, it cannot overlap - // `new_ptr`. Thus, the call to `copy_nonoverlapping` is safe. The safety contract - // for `dealloc` must be upheld by the caller. - new_size => unsafe { - let new_ptr = self.allocate(new_layout)?; - ptr::copy_nonoverlapping(ptr.as_ptr(), new_ptr.as_mut_ptr(), new_size); - self.deallocate(ptr, old_layout); - Ok(new_ptr) - }, - } - } -} - -/// The allocator for unique pointers. -#[cfg(all(not(no_global_oom_handling), not(test)))] -#[lang = "exchange_malloc"] -#[inline] -unsafe fn exchange_malloc(size: usize, align: usize) -> *mut u8 { - let layout = unsafe { Layout::from_size_align_unchecked(size, align) }; - match Global.allocate(layout) { - Ok(ptr) => ptr.as_mut_ptr(), - Err(_) => handle_alloc_error(layout), - } -} - -// # Allocation error handler - -#[cfg(not(no_global_oom_handling))] -extern "Rust" { - // This is the magic symbol to call the global alloc error handler. rustc generates - // it to call `__rg_oom` if there is a `#[alloc_error_handler]`, or to call the - // default implementations below (`__rdl_oom`) otherwise. - fn __rust_alloc_error_handler(size: usize, align: usize) -> !; -} - -/// Signal a memory allocation error. -/// -/// Callers of memory allocation APIs wishing to cease execution -/// in response to an allocation error are encouraged to call this function, -/// rather than directly invoking [`panic!`] or similar. -/// -/// This function is guaranteed to diverge (not return normally with a value), but depending on -/// global configuration, it may either panic (resulting in unwinding or aborting as per -/// configuration for all panics), or abort the process (with no unwinding). -/// -/// The default behavior is: -/// -/// * If the binary links against `std` (typically the case), then -/// print a message to standard error and abort the process. -/// This behavior can be replaced with [`set_alloc_error_hook`] and [`take_alloc_error_hook`]. -/// Future versions of Rust may panic by default instead. -/// -/// * If the binary does not link against `std` (all of its crates are marked -/// [`#![no_std]`][no_std]), then call [`panic!`] with a message. -/// [The panic handler] applies as to any panic. -/// -/// [`set_alloc_error_hook`]: ../../std/alloc/fn.set_alloc_error_hook.html -/// [`take_alloc_error_hook`]: ../../std/alloc/fn.take_alloc_error_hook.html -/// [The panic handler]: https://doc.rust-lang.org/reference/runtime.html#the-panic_handler-attribute -/// [no_std]: https://doc.rust-lang.org/reference/names/preludes.html#the-no_std-attribute -#[stable(feature = "global_alloc", since = "1.28.0")] -#[rustc_const_unstable(feature = "const_alloc_error", issue = "92523")] -#[cfg(all(not(no_global_oom_handling), not(test)))] -#[cold] -pub const fn handle_alloc_error(layout: Layout) -> ! { - const fn ct_error(_: Layout) -> ! { - panic!("allocation failed"); - } - - #[inline] - fn rt_error(layout: Layout) -> ! { - unsafe { - __rust_alloc_error_handler(layout.size(), layout.align()); - } - } - - #[cfg(not(feature = "panic_immediate_abort"))] - { - core::intrinsics::const_eval_select((layout,), ct_error, rt_error) - } - - #[cfg(feature = "panic_immediate_abort")] - ct_error(layout) -} - -// For alloc test `std::alloc::handle_alloc_error` can be used directly. -#[cfg(all(not(no_global_oom_handling), test))] -pub use std::alloc::handle_alloc_error; - -#[cfg(all(not(no_global_oom_handling), not(test)))] -#[doc(hidden)] -#[allow(unused_attributes)] -#[unstable(feature = "alloc_internals", issue = "none")] -pub mod __alloc_error_handler { - // called via generated `__rust_alloc_error_handler` if there is no - // `#[alloc_error_handler]`. - #[rustc_std_internal_symbol] - pub unsafe fn __rdl_oom(size: usize, _align: usize) -> ! { - extern "Rust" { - // This symbol is emitted by rustc next to __rust_alloc_error_handler. - // Its value depends on the -Zoom={panic,abort} compiler option. - static __rust_alloc_error_handler_should_panic: u8; - } - - if unsafe { __rust_alloc_error_handler_should_panic != 0 } { - panic!("memory allocation of {size} bytes failed") - } else { - core::panicking::panic_nounwind_fmt( - format_args!("memory allocation of {size} bytes failed"), - /* force_no_backtrace */ false, - ) - } - } -} - -#[cfg(not(no_global_oom_handling))] -/// Specialize clones into pre-allocated, uninitialized memory. -/// Used by `Box::clone` and `Rc`/`Arc::make_mut`. -pub(crate) trait WriteCloneIntoRaw: Sized { - unsafe fn write_clone_into_raw(&self, target: *mut Self); -} - -#[cfg(not(no_global_oom_handling))] -impl WriteCloneIntoRaw for T { - #[inline] - default unsafe fn write_clone_into_raw(&self, target: *mut Self) { - // Having allocated *first* may allow the optimizer to create - // the cloned value in-place, skipping the local and move. - unsafe { target.write(self.clone()) }; - } -} - -#[cfg(not(no_global_oom_handling))] -impl WriteCloneIntoRaw for T { - #[inline] - unsafe fn write_clone_into_raw(&self, target: *mut Self) { - // We can always copy in-place, without ever involving a local value. - unsafe { target.copy_from_nonoverlapping(self, 1) }; - } -} diff --git a/library/alloc/src/alloc/tests.rs b/library/alloc/src/alloc/tests.rs deleted file mode 100644 index 1a5938fd34cf1..0000000000000 --- a/library/alloc/src/alloc/tests.rs +++ /dev/null @@ -1,29 +0,0 @@ -use super::*; - -extern crate test; -use crate::boxed::Box; -use test::Bencher; - -#[test] -fn allocate_zeroed() { - unsafe { - let layout = Layout::from_size_align(1024, 1).unwrap(); - let ptr = - Global.allocate_zeroed(layout.clone()).unwrap_or_else(|_| handle_alloc_error(layout)); - - let mut i = ptr.as_non_null_ptr().as_ptr(); - let end = i.add(layout.size()); - while i < end { - assert_eq!(*i, 0); - i = i.add(1); - } - Global.deallocate(ptr.as_non_null_ptr(), layout); - } -} - -#[bench] -fn alloc_owned_small(b: &mut Bencher) { - b.iter(|| { - let _: Box<_> = Box::new(10); - }) -} diff --git a/library/alloc/src/borrow.rs b/library/alloc/src/borrow.rs deleted file mode 100644 index 42f8a08a9e4ee..0000000000000 --- a/library/alloc/src/borrow.rs +++ /dev/null @@ -1,497 +0,0 @@ -//! A module for working with borrowed data. - -#![stable(feature = "rust1", since = "1.0.0")] - -use core::cmp::Ordering; -use core::hash::{Hash, Hasher}; -#[cfg(not(no_global_oom_handling))] -use core::ops::{Add, AddAssign}; -use core::ops::{Deref, DerefPure}; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::borrow::{Borrow, BorrowMut}; - -use crate::fmt; -#[cfg(not(no_global_oom_handling))] -use crate::string::String; - -use Cow::*; - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, B: ?Sized> Borrow for Cow<'a, B> -where - B: ToOwned, -{ - fn borrow(&self) -> &B { - &**self - } -} - -/// A generalization of `Clone` to borrowed data. -/// -/// Some types make it possible to go from borrowed to owned, usually by -/// implementing the `Clone` trait. But `Clone` works only for going from `&T` -/// to `T`. The `ToOwned` trait generalizes `Clone` to construct owned data -/// from any borrow of a given type. -#[cfg_attr(not(test), rustc_diagnostic_item = "ToOwned")] -#[stable(feature = "rust1", since = "1.0.0")] -pub trait ToOwned { - /// The resulting type after obtaining ownership. - #[stable(feature = "rust1", since = "1.0.0")] - type Owned: Borrow; - - /// Creates owned data from borrowed data, usually by cloning. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let s: &str = "a"; - /// let ss: String = s.to_owned(); - /// - /// let v: &[i32] = &[1, 2]; - /// let vv: Vec = v.to_owned(); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use = "cloning is often expensive and is not expected to have side effects"] - #[cfg_attr(not(test), rustc_diagnostic_item = "to_owned_method")] - fn to_owned(&self) -> Self::Owned; - - /// Uses borrowed data to replace owned data, usually by cloning. - /// - /// This is borrow-generalized version of [`Clone::clone_from`]. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let mut s: String = String::new(); - /// "hello".clone_into(&mut s); - /// - /// let mut v: Vec = Vec::new(); - /// [1, 2][..].clone_into(&mut v); - /// ``` - #[stable(feature = "toowned_clone_into", since = "1.63.0")] - fn clone_into(&self, target: &mut Self::Owned) { - *target = self.to_owned(); - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ToOwned for T -where - T: Clone, -{ - type Owned = T; - fn to_owned(&self) -> T { - self.clone() - } - - fn clone_into(&self, target: &mut T) { - target.clone_from(self); - } -} - -/// A clone-on-write smart pointer. -/// -/// The type `Cow` is a smart pointer providing clone-on-write functionality: it -/// can enclose and provide immutable access to borrowed data, and clone the -/// data lazily when mutation or ownership is required. The type is designed to -/// work with general borrowed data via the `Borrow` trait. -/// -/// `Cow` implements `Deref`, which means that you can call -/// non-mutating methods directly on the data it encloses. If mutation -/// is desired, `to_mut` will obtain a mutable reference to an owned -/// value, cloning if necessary. -/// -/// If you need reference-counting pointers, note that -/// [`Rc::make_mut`][crate::rc::Rc::make_mut] and -/// [`Arc::make_mut`][crate::sync::Arc::make_mut] can provide clone-on-write -/// functionality as well. -/// -/// # Examples -/// -/// ``` -/// use std::borrow::Cow; -/// -/// fn abs_all(input: &mut Cow<'_, [i32]>) { -/// for i in 0..input.len() { -/// let v = input[i]; -/// if v < 0 { -/// // Clones into a vector if not already owned. -/// input.to_mut()[i] = -v; -/// } -/// } -/// } -/// -/// // No clone occurs because `input` doesn't need to be mutated. -/// let slice = [0, 1, 2]; -/// let mut input = Cow::from(&slice[..]); -/// abs_all(&mut input); -/// -/// // Clone occurs because `input` needs to be mutated. -/// let slice = [-1, 0, 1]; -/// let mut input = Cow::from(&slice[..]); -/// abs_all(&mut input); -/// -/// // No clone occurs because `input` is already owned. -/// let mut input = Cow::from(vec![-1, 0, 1]); -/// abs_all(&mut input); -/// ``` -/// -/// Another example showing how to keep `Cow` in a struct: -/// -/// ``` -/// use std::borrow::Cow; -/// -/// struct Items<'a, X> where [X]: ToOwned> { -/// values: Cow<'a, [X]>, -/// } -/// -/// impl<'a, X: Clone + 'a> Items<'a, X> where [X]: ToOwned> { -/// fn new(v: Cow<'a, [X]>) -> Self { -/// Items { values: v } -/// } -/// } -/// -/// // Creates a container from borrowed values of a slice -/// let readonly = [1, 2]; -/// let borrowed = Items::new((&readonly[..]).into()); -/// match borrowed { -/// Items { values: Cow::Borrowed(b) } => println!("borrowed {b:?}"), -/// _ => panic!("expect borrowed value"), -/// } -/// -/// let mut clone_on_write = borrowed; -/// // Mutates the data from slice into owned vec and pushes a new value on top -/// clone_on_write.values.to_mut().push(3); -/// println!("clone_on_write = {:?}", clone_on_write.values); -/// -/// // The data was mutated. Let's check it out. -/// match clone_on_write { -/// Items { values: Cow::Owned(_) } => println!("clone_on_write contains owned data"), -/// _ => panic!("expect owned data"), -/// } -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "Cow")] -pub enum Cow<'a, B: ?Sized + 'a> -where - B: ToOwned, -{ - /// Borrowed data. - #[stable(feature = "rust1", since = "1.0.0")] - Borrowed(#[stable(feature = "rust1", since = "1.0.0")] &'a B), - - /// Owned data. - #[stable(feature = "rust1", since = "1.0.0")] - Owned(#[stable(feature = "rust1", since = "1.0.0")] ::Owned), -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Cow<'_, B> { - fn clone(&self) -> Self { - match *self { - Borrowed(b) => Borrowed(b), - Owned(ref o) => { - let b: &B = o.borrow(); - Owned(b.to_owned()) - } - } - } - - fn clone_from(&mut self, source: &Self) { - match (self, source) { - (&mut Owned(ref mut dest), &Owned(ref o)) => o.borrow().clone_into(dest), - (t, s) => *t = s.clone(), - } - } -} - -impl Cow<'_, B> { - /// Returns true if the data is borrowed, i.e. if `to_mut` would require additional work. - /// - /// # Examples - /// - /// ``` - /// #![feature(cow_is_borrowed)] - /// use std::borrow::Cow; - /// - /// let cow = Cow::Borrowed("moo"); - /// assert!(cow.is_borrowed()); - /// - /// let bull: Cow<'_, str> = Cow::Owned("...moo?".to_string()); - /// assert!(!bull.is_borrowed()); - /// ``` - #[unstable(feature = "cow_is_borrowed", issue = "65143")] - #[rustc_const_unstable(feature = "const_cow_is_borrowed", issue = "65143")] - pub const fn is_borrowed(&self) -> bool { - match *self { - Borrowed(_) => true, - Owned(_) => false, - } - } - - /// Returns true if the data is owned, i.e. if `to_mut` would be a no-op. - /// - /// # Examples - /// - /// ``` - /// #![feature(cow_is_borrowed)] - /// use std::borrow::Cow; - /// - /// let cow: Cow<'_, str> = Cow::Owned("moo".to_string()); - /// assert!(cow.is_owned()); - /// - /// let bull = Cow::Borrowed("...moo?"); - /// assert!(!bull.is_owned()); - /// ``` - #[unstable(feature = "cow_is_borrowed", issue = "65143")] - #[rustc_const_unstable(feature = "const_cow_is_borrowed", issue = "65143")] - pub const fn is_owned(&self) -> bool { - !self.is_borrowed() - } - - /// Acquires a mutable reference to the owned form of the data. - /// - /// Clones the data if it is not already owned. - /// - /// # Examples - /// - /// ``` - /// use std::borrow::Cow; - /// - /// let mut cow = Cow::Borrowed("foo"); - /// cow.to_mut().make_ascii_uppercase(); - /// - /// assert_eq!( - /// cow, - /// Cow::Owned(String::from("FOO")) as Cow<'_, str> - /// ); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn to_mut(&mut self) -> &mut ::Owned { - match *self { - Borrowed(borrowed) => { - *self = Owned(borrowed.to_owned()); - match *self { - Borrowed(..) => unreachable!(), - Owned(ref mut owned) => owned, - } - } - Owned(ref mut owned) => owned, - } - } - - /// Extracts the owned data. - /// - /// Clones the data if it is not already owned. - /// - /// # Examples - /// - /// Calling `into_owned` on a `Cow::Borrowed` returns a clone of the borrowed data: - /// - /// ``` - /// use std::borrow::Cow; - /// - /// let s = "Hello world!"; - /// let cow = Cow::Borrowed(s); - /// - /// assert_eq!( - /// cow.into_owned(), - /// String::from(s) - /// ); - /// ``` - /// - /// Calling `into_owned` on a `Cow::Owned` returns the owned data. The data is moved out of the - /// `Cow` without being cloned. - /// - /// ``` - /// use std::borrow::Cow; - /// - /// let s = "Hello world!"; - /// let cow: Cow<'_, str> = Cow::Owned(String::from(s)); - /// - /// assert_eq!( - /// cow.into_owned(), - /// String::from(s) - /// ); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn into_owned(self) -> ::Owned { - match self { - Borrowed(borrowed) => borrowed.to_owned(), - Owned(owned) => owned, - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Deref for Cow<'_, B> -where - B::Owned: Borrow, -{ - type Target = B; - - fn deref(&self) -> &B { - match *self { - Borrowed(borrowed) => borrowed, - Owned(ref owned) => owned.borrow(), - } - } -} - -#[unstable(feature = "deref_pure_trait", issue = "87121")] -unsafe impl DerefPure for Cow<'_, B> where B::Owned: Borrow {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Eq for Cow<'_, B> where B: Eq + ToOwned {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for Cow<'_, B> -where - B: Ord + ToOwned, -{ - #[inline] - fn cmp(&self, other: &Self) -> Ordering { - Ord::cmp(&**self, &**other) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, 'b, B: ?Sized, C: ?Sized> PartialEq> for Cow<'a, B> -where - B: PartialEq + ToOwned, - C: ToOwned, -{ - #[inline] - fn eq(&self, other: &Cow<'b, C>) -> bool { - PartialEq::eq(&**self, &**other) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, B: ?Sized> PartialOrd for Cow<'a, B> -where - B: PartialOrd + ToOwned, -{ - #[inline] - fn partial_cmp(&self, other: &Cow<'a, B>) -> Option { - PartialOrd::partial_cmp(&**self, &**other) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for Cow<'_, B> -where - B: fmt::Debug + ToOwned, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - match *self { - Borrowed(ref b) => fmt::Debug::fmt(b, f), - Owned(ref o) => fmt::Debug::fmt(o, f), - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for Cow<'_, B> -where - B: fmt::Display + ToOwned, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - match *self { - Borrowed(ref b) => fmt::Display::fmt(b, f), - Owned(ref o) => fmt::Display::fmt(o, f), - } - } -} - -#[stable(feature = "default", since = "1.11.0")] -impl Default for Cow<'_, B> -where - B: ToOwned, -{ - /// Creates an owned Cow<'a, B> with the default value for the contained owned value. - fn default() -> Self { - Owned(::Owned::default()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Hash for Cow<'_, B> -where - B: Hash + ToOwned, -{ - #[inline] - fn hash(&self, state: &mut H) { - Hash::hash(&**self, state) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef for Cow<'_, T> { - fn as_ref(&self) -> &T { - self - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "cow_add", since = "1.14.0")] -impl<'a> Add<&'a str> for Cow<'a, str> { - type Output = Cow<'a, str>; - - #[inline] - fn add(mut self, rhs: &'a str) -> Self::Output { - self += rhs; - self - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "cow_add", since = "1.14.0")] -impl<'a> Add> for Cow<'a, str> { - type Output = Cow<'a, str>; - - #[inline] - fn add(mut self, rhs: Cow<'a, str>) -> Self::Output { - self += rhs; - self - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "cow_add", since = "1.14.0")] -impl<'a> AddAssign<&'a str> for Cow<'a, str> { - fn add_assign(&mut self, rhs: &'a str) { - if self.is_empty() { - *self = Cow::Borrowed(rhs) - } else if !rhs.is_empty() { - if let Cow::Borrowed(lhs) = *self { - let mut s = String::with_capacity(lhs.len() + rhs.len()); - s.push_str(lhs); - *self = Cow::Owned(s); - } - self.to_mut().push_str(rhs); - } - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "cow_add", since = "1.14.0")] -impl<'a> AddAssign> for Cow<'a, str> { - fn add_assign(&mut self, rhs: Cow<'a, str>) { - if self.is_empty() { - *self = rhs - } else if !rhs.is_empty() { - if let Cow::Borrowed(lhs) = *self { - let mut s = String::with_capacity(lhs.len() + rhs.len()); - s.push_str(lhs); - *self = Cow::Owned(s); - } - self.to_mut().push_str(&rhs); - } - } -} diff --git a/library/alloc/src/boxed.rs b/library/alloc/src/boxed.rs deleted file mode 100644 index 21d0050300170..0000000000000 --- a/library/alloc/src/boxed.rs +++ /dev/null @@ -1,2641 +0,0 @@ -//! The `Box` type for heap allocation. -//! -//! [`Box`], casually referred to as a 'box', provides the simplest form of -//! heap allocation in Rust. Boxes provide ownership for this allocation, and -//! drop their contents when they go out of scope. Boxes also ensure that they -//! never allocate more than `isize::MAX` bytes. -//! -//! # Examples -//! -//! Move a value from the stack to the heap by creating a [`Box`]: -//! -//! ``` -//! let val: u8 = 5; -//! let boxed: Box = Box::new(val); -//! ``` -//! -//! Move a value from a [`Box`] back to the stack by [dereferencing]: -//! -//! ``` -//! let boxed: Box = Box::new(5); -//! let val: u8 = *boxed; -//! ``` -//! -//! Creating a recursive data structure: -//! -//! ``` -//! ##[allow(dead_code)] -//! #[derive(Debug)] -//! enum List { -//! Cons(T, Box>), -//! Nil, -//! } -//! -//! let list: List = List::Cons(1, Box::new(List::Cons(2, Box::new(List::Nil)))); -//! println!("{list:?}"); -//! ``` -//! -//! This will print `Cons(1, Cons(2, Nil))`. -//! -//! Recursive structures must be boxed, because if the definition of `Cons` -//! looked like this: -//! -//! ```compile_fail,E0072 -//! # enum List { -//! Cons(T, List), -//! # } -//! ``` -//! -//! It wouldn't work. This is because the size of a `List` depends on how many -//! elements are in the list, and so we don't know how much memory to allocate -//! for a `Cons`. By introducing a [`Box`], which has a defined size, we know how -//! big `Cons` needs to be. -//! -//! # Memory layout -//! -//! For non-zero-sized values, a [`Box`] will use the [`Global`] allocator for -//! its allocation. It is valid to convert both ways between a [`Box`] and a -//! raw pointer allocated with the [`Global`] allocator, given that the -//! [`Layout`] used with the allocator is correct for the type. More precisely, -//! a `value: *mut T` that has been allocated with the [`Global`] allocator -//! with `Layout::for_value(&*value)` may be converted into a box using -//! [`Box::::from_raw(value)`]. Conversely, the memory backing a `value: *mut -//! T` obtained from [`Box::::into_raw`] may be deallocated using the -//! [`Global`] allocator with [`Layout::for_value(&*value)`]. -//! -//! For zero-sized values, the `Box` pointer still has to be [valid] for reads -//! and writes and sufficiently aligned. In particular, casting any aligned -//! non-zero integer literal to a raw pointer produces a valid pointer, but a -//! pointer pointing into previously allocated memory that since got freed is -//! not valid. The recommended way to build a Box to a ZST if `Box::new` cannot -//! be used is to use [`ptr::NonNull::dangling`]. -//! -//! So long as `T: Sized`, a `Box` is guaranteed to be represented -//! as a single pointer and is also ABI-compatible with C pointers -//! (i.e. the C type `T*`). This means that if you have extern "C" -//! Rust functions that will be called from C, you can define those -//! Rust functions using `Box` types, and use `T*` as corresponding -//! type on the C side. As an example, consider this C header which -//! declares functions that create and destroy some kind of `Foo` -//! value: -//! -//! ```c -//! /* C header */ -//! -//! /* Returns ownership to the caller */ -//! struct Foo* foo_new(void); -//! -//! /* Takes ownership from the caller; no-op when invoked with null */ -//! void foo_delete(struct Foo*); -//! ``` -//! -//! These two functions might be implemented in Rust as follows. Here, the -//! `struct Foo*` type from C is translated to `Box`, which captures -//! the ownership constraints. Note also that the nullable argument to -//! `foo_delete` is represented in Rust as `Option>`, since `Box` -//! cannot be null. -//! -//! ``` -//! #[repr(C)] -//! pub struct Foo; -//! -//! #[no_mangle] -//! pub extern "C" fn foo_new() -> Box { -//! Box::new(Foo) -//! } -//! -//! #[no_mangle] -//! pub extern "C" fn foo_delete(_: Option>) {} -//! ``` -//! -//! Even though `Box` has the same representation and C ABI as a C pointer, -//! this does not mean that you can convert an arbitrary `T*` into a `Box` -//! and expect things to work. `Box` values will always be fully aligned, -//! non-null pointers. Moreover, the destructor for `Box` will attempt to -//! free the value with the global allocator. In general, the best practice -//! is to only use `Box` for pointers that originated from the global -//! allocator. -//! -//! **Important.** At least at present, you should avoid using -//! `Box` types for functions that are defined in C but invoked -//! from Rust. In those cases, you should directly mirror the C types -//! as closely as possible. Using types like `Box` where the C -//! definition is just using `T*` can lead to undefined behavior, as -//! described in [rust-lang/unsafe-code-guidelines#198][ucg#198]. -//! -//! # Considerations for unsafe code -//! -//! **Warning: This section is not normative and is subject to change, possibly -//! being relaxed in the future! It is a simplified summary of the rules -//! currently implemented in the compiler.** -//! -//! The aliasing rules for `Box` are the same as for `&mut T`. `Box` -//! asserts uniqueness over its content. Using raw pointers derived from a box -//! after that box has been mutated through, moved or borrowed as `&mut T` -//! is not allowed. For more guidance on working with box from unsafe code, see -//! [rust-lang/unsafe-code-guidelines#326][ucg#326]. -//! -//! # Editions -//! -//! A special case exists for the implementation of `IntoIterator` for arrays on the Rust 2021 -//! edition, as documented [here][array]. Unfortunately, it was later found that a similar -//! workaround should be added for boxed slices, and this was applied in the 2024 edition. -//! -//! Specifically, `IntoIterator` is implemented for `Box<[T]>` on all editions, but specific calls -//! to `into_iter()` for boxed slices will defer to the slice implementation on editions before -//! 2024: -//! -#![cfg_attr(bootstrap, doc = "```rust,edition2021,ignore")] -#![cfg_attr(not(bootstrap), doc = "```rust,edition2021")] -//! // Rust 2015, 2018, and 2021: -//! -//! # #![allow(boxed_slice_into_iter)] // override our `deny(warnings)` -//! let boxed_slice: Box<[i32]> = vec![0; 3].into_boxed_slice(); -//! -//! // This creates a slice iterator, producing references to each value. -//! for item in boxed_slice.into_iter().enumerate() { -//! let (i, x): (usize, &i32) = item; -//! println!("boxed_slice[{i}] = {x}"); -//! } -//! -//! // The `boxed_slice_into_iter` lint suggests this change for future compatibility: -//! for item in boxed_slice.iter().enumerate() { -//! let (i, x): (usize, &i32) = item; -//! println!("boxed_slice[{i}] = {x}"); -//! } -//! -//! // You can explicitly iterate a boxed slice by value using `IntoIterator::into_iter` -//! for item in IntoIterator::into_iter(boxed_slice).enumerate() { -//! let (i, x): (usize, i32) = item; -//! println!("boxed_slice[{i}] = {x}"); -//! } -//! ``` -//! -//! Similar to the array implementation, this may be modified in the future to remove this override, -//! and it's best to avoid relying on this edition-dependent behavior if you wish to preserve -//! compatibility with future versions of the compiler. -//! -//! [ucg#198]: https://github.com/rust-lang/unsafe-code-guidelines/issues/198 -//! [ucg#326]: https://github.com/rust-lang/unsafe-code-guidelines/issues/326 -//! [dereferencing]: core::ops::Deref -//! [`Box::::from_raw(value)`]: Box::from_raw -//! [`Global`]: crate::alloc::Global -//! [`Layout`]: crate::alloc::Layout -//! [`Layout::for_value(&*value)`]: crate::alloc::Layout::for_value -//! [valid]: ptr#safety - -#![stable(feature = "rust1", since = "1.0.0")] - -use core::any::Any; -use core::async_iter::AsyncIterator; -use core::borrow; -use core::cmp::Ordering; -use core::error::Error; -use core::fmt; -use core::future::Future; -use core::hash::{Hash, Hasher}; -use core::iter::FusedIterator; -use core::marker::Tuple; -use core::marker::Unsize; -use core::mem::{self, SizedTypeProperties}; -use core::ops::{AsyncFn, AsyncFnMut, AsyncFnOnce}; -use core::ops::{ - CoerceUnsized, Coroutine, CoroutineState, Deref, DerefMut, DerefPure, DispatchFromDyn, Receiver, -}; -use core::pin::Pin; -use core::ptr::{self, addr_of_mut, NonNull, Unique}; -use core::slice; -use core::task::{Context, Poll}; - -#[cfg(not(no_global_oom_handling))] -use crate::alloc::{handle_alloc_error, WriteCloneIntoRaw}; -use crate::alloc::{AllocError, Allocator, Global, Layout}; -#[cfg(not(no_global_oom_handling))] -use crate::borrow::Cow; -use crate::raw_vec::RawVec; -#[cfg(not(no_global_oom_handling))] -use crate::str::from_boxed_utf8_unchecked; -#[cfg(not(no_global_oom_handling))] -use crate::string::String; -use crate::vec; -#[cfg(not(no_global_oom_handling))] -use crate::vec::Vec; - -#[unstable(feature = "thin_box", issue = "92791")] -pub use thin::ThinBox; - -mod thin; - -/// A pointer type that uniquely owns a heap allocation of type `T`. -/// -/// See the [module-level documentation](../../std/boxed/index.html) for more. -#[lang = "owned_box"] -#[fundamental] -#[stable(feature = "rust1", since = "1.0.0")] -// The declaration of the `Box` struct must be kept in sync with the -// compiler or ICEs will happen. -pub struct Box< - T: ?Sized, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, ->(Unique, A); - -impl Box { - /// Allocates memory on the heap and then places `x` into it. - /// - /// This doesn't actually allocate if `T` is zero-sized. - /// - /// # Examples - /// - /// ``` - /// let five = Box::new(5); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[inline(always)] - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - #[rustc_diagnostic_item = "box_new"] - pub fn new(x: T) -> Self { - #[rustc_box] - Box::new(x) - } - - /// Constructs a new box with uninitialized contents. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// - /// let mut five = Box::::new_uninit(); - /// - /// let five = unsafe { - /// // Deferred initialization: - /// five.as_mut_ptr().write(5); - /// - /// five.assume_init() - /// }; - /// - /// assert_eq!(*five, 5) - /// ``` - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "new_uninit", issue = "63291")] - #[must_use] - #[inline] - pub fn new_uninit() -> Box> { - Self::new_uninit_in(Global) - } - - /// Constructs a new `Box` with uninitialized contents, with the memory - /// being filled with `0` bytes. - /// - /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and incorrect usage - /// of this method. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// - /// let zero = Box::::new_zeroed(); - /// let zero = unsafe { zero.assume_init() }; - /// - /// assert_eq!(*zero, 0) - /// ``` - /// - /// [zeroed]: mem::MaybeUninit::zeroed - #[cfg(not(no_global_oom_handling))] - #[inline] - #[unstable(feature = "new_uninit", issue = "63291")] - #[must_use] - pub fn new_zeroed() -> Box> { - Self::new_zeroed_in(Global) - } - - /// Constructs a new `Pin>`. If `T` does not implement [`Unpin`], then - /// `x` will be pinned in memory and unable to be moved. - /// - /// Constructing and pinning of the `Box` can also be done in two steps: `Box::pin(x)` - /// does the same as [Box::into_pin]\([Box::new]\(x)). Consider using - /// [`into_pin`](Box::into_pin) if you already have a `Box`, or if you want to - /// construct a (pinned) `Box` in a different way than with [`Box::new`]. - #[cfg(not(no_global_oom_handling))] - #[stable(feature = "pin", since = "1.33.0")] - #[must_use] - #[inline(always)] - pub fn pin(x: T) -> Pin> { - Box::new(x).into() - } - - /// Allocates memory on the heap then places `x` into it, - /// returning an error if the allocation fails - /// - /// This doesn't actually allocate if `T` is zero-sized. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// - /// let five = Box::try_new(5)?; - /// # Ok::<(), std::alloc::AllocError>(()) - /// ``` - #[unstable(feature = "allocator_api", issue = "32838")] - #[inline] - pub fn try_new(x: T) -> Result { - Self::try_new_in(x, Global) - } - - /// Constructs a new box with uninitialized contents on the heap, - /// returning an error if the allocation fails - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api, new_uninit)] - /// - /// let mut five = Box::::try_new_uninit()?; - /// - /// let five = unsafe { - /// // Deferred initialization: - /// five.as_mut_ptr().write(5); - /// - /// five.assume_init() - /// }; - /// - /// assert_eq!(*five, 5); - /// # Ok::<(), std::alloc::AllocError>(()) - /// ``` - #[unstable(feature = "allocator_api", issue = "32838")] - // #[unstable(feature = "new_uninit", issue = "63291")] - #[inline] - pub fn try_new_uninit() -> Result>, AllocError> { - Box::try_new_uninit_in(Global) - } - - /// Constructs a new `Box` with uninitialized contents, with the memory - /// being filled with `0` bytes on the heap - /// - /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and incorrect usage - /// of this method. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api, new_uninit)] - /// - /// let zero = Box::::try_new_zeroed()?; - /// let zero = unsafe { zero.assume_init() }; - /// - /// assert_eq!(*zero, 0); - /// # Ok::<(), std::alloc::AllocError>(()) - /// ``` - /// - /// [zeroed]: mem::MaybeUninit::zeroed - #[unstable(feature = "allocator_api", issue = "32838")] - // #[unstable(feature = "new_uninit", issue = "63291")] - #[inline] - pub fn try_new_zeroed() -> Result>, AllocError> { - Box::try_new_zeroed_in(Global) - } -} - -impl Box { - /// Allocates memory in the given allocator then places `x` into it. - /// - /// This doesn't actually allocate if `T` is zero-sized. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// - /// use std::alloc::System; - /// - /// let five = Box::new_in(5, System); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "allocator_api", issue = "32838")] - #[must_use] - #[inline] - pub fn new_in(x: T, alloc: A) -> Self - where - A: Allocator, - { - let mut boxed = Self::new_uninit_in(alloc); - unsafe { - boxed.as_mut_ptr().write(x); - boxed.assume_init() - } - } - - /// Allocates memory in the given allocator then places `x` into it, - /// returning an error if the allocation fails - /// - /// This doesn't actually allocate if `T` is zero-sized. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// - /// use std::alloc::System; - /// - /// let five = Box::try_new_in(5, System)?; - /// # Ok::<(), std::alloc::AllocError>(()) - /// ``` - #[unstable(feature = "allocator_api", issue = "32838")] - #[inline] - pub fn try_new_in(x: T, alloc: A) -> Result - where - A: Allocator, - { - let mut boxed = Self::try_new_uninit_in(alloc)?; - unsafe { - boxed.as_mut_ptr().write(x); - Ok(boxed.assume_init()) - } - } - - /// Constructs a new box with uninitialized contents in the provided allocator. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api, new_uninit)] - /// - /// use std::alloc::System; - /// - /// let mut five = Box::::new_uninit_in(System); - /// - /// let five = unsafe { - /// // Deferred initialization: - /// five.as_mut_ptr().write(5); - /// - /// five.assume_init() - /// }; - /// - /// assert_eq!(*five, 5) - /// ``` - #[unstable(feature = "allocator_api", issue = "32838")] - #[cfg(not(no_global_oom_handling))] - #[must_use] - // #[unstable(feature = "new_uninit", issue = "63291")] - pub fn new_uninit_in(alloc: A) -> Box, A> - where - A: Allocator, - { - let layout = Layout::new::>(); - // NOTE: Prefer match over unwrap_or_else since closure sometimes not inlineable. - // That would make code size bigger. - match Box::try_new_uninit_in(alloc) { - Ok(m) => m, - Err(_) => handle_alloc_error(layout), - } - } - - /// Constructs a new box with uninitialized contents in the provided allocator, - /// returning an error if the allocation fails - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api, new_uninit)] - /// - /// use std::alloc::System; - /// - /// let mut five = Box::::try_new_uninit_in(System)?; - /// - /// let five = unsafe { - /// // Deferred initialization: - /// five.as_mut_ptr().write(5); - /// - /// five.assume_init() - /// }; - /// - /// assert_eq!(*five, 5); - /// # Ok::<(), std::alloc::AllocError>(()) - /// ``` - #[unstable(feature = "allocator_api", issue = "32838")] - // #[unstable(feature = "new_uninit", issue = "63291")] - pub fn try_new_uninit_in(alloc: A) -> Result, A>, AllocError> - where - A: Allocator, - { - let ptr = if T::IS_ZST { - NonNull::dangling() - } else { - let layout = Layout::new::>(); - alloc.allocate(layout)?.cast() - }; - unsafe { Ok(Box::from_raw_in(ptr.as_ptr(), alloc)) } - } - - /// Constructs a new `Box` with uninitialized contents, with the memory - /// being filled with `0` bytes in the provided allocator. - /// - /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and incorrect usage - /// of this method. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api, new_uninit)] - /// - /// use std::alloc::System; - /// - /// let zero = Box::::new_zeroed_in(System); - /// let zero = unsafe { zero.assume_init() }; - /// - /// assert_eq!(*zero, 0) - /// ``` - /// - /// [zeroed]: mem::MaybeUninit::zeroed - #[unstable(feature = "allocator_api", issue = "32838")] - #[cfg(not(no_global_oom_handling))] - // #[unstable(feature = "new_uninit", issue = "63291")] - #[must_use] - pub fn new_zeroed_in(alloc: A) -> Box, A> - where - A: Allocator, - { - let layout = Layout::new::>(); - // NOTE: Prefer match over unwrap_or_else since closure sometimes not inlineable. - // That would make code size bigger. - match Box::try_new_zeroed_in(alloc) { - Ok(m) => m, - Err(_) => handle_alloc_error(layout), - } - } - - /// Constructs a new `Box` with uninitialized contents, with the memory - /// being filled with `0` bytes in the provided allocator, - /// returning an error if the allocation fails, - /// - /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and incorrect usage - /// of this method. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api, new_uninit)] - /// - /// use std::alloc::System; - /// - /// let zero = Box::::try_new_zeroed_in(System)?; - /// let zero = unsafe { zero.assume_init() }; - /// - /// assert_eq!(*zero, 0); - /// # Ok::<(), std::alloc::AllocError>(()) - /// ``` - /// - /// [zeroed]: mem::MaybeUninit::zeroed - #[unstable(feature = "allocator_api", issue = "32838")] - // #[unstable(feature = "new_uninit", issue = "63291")] - pub fn try_new_zeroed_in(alloc: A) -> Result, A>, AllocError> - where - A: Allocator, - { - let ptr = if T::IS_ZST { - NonNull::dangling() - } else { - let layout = Layout::new::>(); - alloc.allocate_zeroed(layout)?.cast() - }; - unsafe { Ok(Box::from_raw_in(ptr.as_ptr(), alloc)) } - } - - /// Constructs a new `Pin>`. If `T` does not implement [`Unpin`], then - /// `x` will be pinned in memory and unable to be moved. - /// - /// Constructing and pinning of the `Box` can also be done in two steps: `Box::pin_in(x, alloc)` - /// does the same as [Box::into_pin]\([Box::new_in]\(x, alloc)). Consider using - /// [`into_pin`](Box::into_pin) if you already have a `Box`, or if you want to - /// construct a (pinned) `Box` in a different way than with [`Box::new_in`]. - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "allocator_api", issue = "32838")] - #[must_use] - #[inline(always)] - pub fn pin_in(x: T, alloc: A) -> Pin - where - A: 'static + Allocator, - { - Self::into_pin(Self::new_in(x, alloc)) - } - - /// Converts a `Box` into a `Box<[T]>` - /// - /// This conversion does not allocate on the heap and happens in place. - #[unstable(feature = "box_into_boxed_slice", issue = "71582")] - pub fn into_boxed_slice(boxed: Self) -> Box<[T], A> { - let (raw, alloc) = Box::into_raw_with_allocator(boxed); - unsafe { Box::from_raw_in(raw as *mut [T; 1], alloc) } - } - - /// Consumes the `Box`, returning the wrapped value. - /// - /// # Examples - /// - /// ``` - /// #![feature(box_into_inner)] - /// - /// let c = Box::new(5); - /// - /// assert_eq!(Box::into_inner(c), 5); - /// ``` - #[unstable(feature = "box_into_inner", issue = "80437")] - #[inline] - pub fn into_inner(boxed: Self) -> T { - *boxed - } -} - -impl Box<[T]> { - /// Constructs a new boxed slice with uninitialized contents. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// - /// let mut values = Box::<[u32]>::new_uninit_slice(3); - /// - /// let values = unsafe { - /// // Deferred initialization: - /// values[0].as_mut_ptr().write(1); - /// values[1].as_mut_ptr().write(2); - /// values[2].as_mut_ptr().write(3); - /// - /// values.assume_init() - /// }; - /// - /// assert_eq!(*values, [1, 2, 3]) - /// ``` - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "new_uninit", issue = "63291")] - #[must_use] - pub fn new_uninit_slice(len: usize) -> Box<[mem::MaybeUninit]> { - unsafe { RawVec::with_capacity(len).into_box(len) } - } - - /// Constructs a new boxed slice with uninitialized contents, with the memory - /// being filled with `0` bytes. - /// - /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and incorrect usage - /// of this method. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// - /// let values = Box::<[u32]>::new_zeroed_slice(3); - /// let values = unsafe { values.assume_init() }; - /// - /// assert_eq!(*values, [0, 0, 0]) - /// ``` - /// - /// [zeroed]: mem::MaybeUninit::zeroed - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "new_uninit", issue = "63291")] - #[must_use] - pub fn new_zeroed_slice(len: usize) -> Box<[mem::MaybeUninit]> { - unsafe { RawVec::with_capacity_zeroed(len).into_box(len) } - } - - /// Constructs a new boxed slice with uninitialized contents. Returns an error if - /// the allocation fails - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api, new_uninit)] - /// - /// let mut values = Box::<[u32]>::try_new_uninit_slice(3)?; - /// let values = unsafe { - /// // Deferred initialization: - /// values[0].as_mut_ptr().write(1); - /// values[1].as_mut_ptr().write(2); - /// values[2].as_mut_ptr().write(3); - /// values.assume_init() - /// }; - /// - /// assert_eq!(*values, [1, 2, 3]); - /// # Ok::<(), std::alloc::AllocError>(()) - /// ``` - #[unstable(feature = "allocator_api", issue = "32838")] - #[inline] - pub fn try_new_uninit_slice(len: usize) -> Result]>, AllocError> { - let ptr = if T::IS_ZST || len == 0 { - NonNull::dangling() - } else { - let layout = match Layout::array::>(len) { - Ok(l) => l, - Err(_) => return Err(AllocError), - }; - Global.allocate(layout)?.cast() - }; - unsafe { Ok(RawVec::from_raw_parts_in(ptr.as_ptr(), len, Global).into_box(len)) } - } - - /// Constructs a new boxed slice with uninitialized contents, with the memory - /// being filled with `0` bytes. Returns an error if the allocation fails - /// - /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and incorrect usage - /// of this method. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api, new_uninit)] - /// - /// let values = Box::<[u32]>::try_new_zeroed_slice(3)?; - /// let values = unsafe { values.assume_init() }; - /// - /// assert_eq!(*values, [0, 0, 0]); - /// # Ok::<(), std::alloc::AllocError>(()) - /// ``` - /// - /// [zeroed]: mem::MaybeUninit::zeroed - #[unstable(feature = "allocator_api", issue = "32838")] - #[inline] - pub fn try_new_zeroed_slice(len: usize) -> Result]>, AllocError> { - let ptr = if T::IS_ZST || len == 0 { - NonNull::dangling() - } else { - let layout = match Layout::array::>(len) { - Ok(l) => l, - Err(_) => return Err(AllocError), - }; - Global.allocate_zeroed(layout)?.cast() - }; - unsafe { Ok(RawVec::from_raw_parts_in(ptr.as_ptr(), len, Global).into_box(len)) } - } -} - -impl Box<[T], A> { - /// Constructs a new boxed slice with uninitialized contents in the provided allocator. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api, new_uninit)] - /// - /// use std::alloc::System; - /// - /// let mut values = Box::<[u32], _>::new_uninit_slice_in(3, System); - /// - /// let values = unsafe { - /// // Deferred initialization: - /// values[0].as_mut_ptr().write(1); - /// values[1].as_mut_ptr().write(2); - /// values[2].as_mut_ptr().write(3); - /// - /// values.assume_init() - /// }; - /// - /// assert_eq!(*values, [1, 2, 3]) - /// ``` - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "allocator_api", issue = "32838")] - // #[unstable(feature = "new_uninit", issue = "63291")] - #[must_use] - pub fn new_uninit_slice_in(len: usize, alloc: A) -> Box<[mem::MaybeUninit], A> { - unsafe { RawVec::with_capacity_in(len, alloc).into_box(len) } - } - - /// Constructs a new boxed slice with uninitialized contents in the provided allocator, - /// with the memory being filled with `0` bytes. - /// - /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and incorrect usage - /// of this method. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api, new_uninit)] - /// - /// use std::alloc::System; - /// - /// let values = Box::<[u32], _>::new_zeroed_slice_in(3, System); - /// let values = unsafe { values.assume_init() }; - /// - /// assert_eq!(*values, [0, 0, 0]) - /// ``` - /// - /// [zeroed]: mem::MaybeUninit::zeroed - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "allocator_api", issue = "32838")] - // #[unstable(feature = "new_uninit", issue = "63291")] - #[must_use] - pub fn new_zeroed_slice_in(len: usize, alloc: A) -> Box<[mem::MaybeUninit], A> { - unsafe { RawVec::with_capacity_zeroed_in(len, alloc).into_box(len) } - } -} - -impl Box, A> { - /// Converts to `Box`. - /// - /// # Safety - /// - /// As with [`MaybeUninit::assume_init`], - /// it is up to the caller to guarantee that the value - /// really is in an initialized state. - /// Calling this when the content is not yet fully initialized - /// causes immediate undefined behavior. - /// - /// [`MaybeUninit::assume_init`]: mem::MaybeUninit::assume_init - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// - /// let mut five = Box::::new_uninit(); - /// - /// let five: Box = unsafe { - /// // Deferred initialization: - /// five.as_mut_ptr().write(5); - /// - /// five.assume_init() - /// }; - /// - /// assert_eq!(*five, 5) - /// ``` - #[unstable(feature = "new_uninit", issue = "63291")] - #[inline] - pub unsafe fn assume_init(self) -> Box { - let (raw, alloc) = Box::into_raw_with_allocator(self); - unsafe { Box::from_raw_in(raw as *mut T, alloc) } - } - - /// Writes the value and converts to `Box`. - /// - /// This method converts the box similarly to [`Box::assume_init`] but - /// writes `value` into it before conversion thus guaranteeing safety. - /// In some scenarios use of this method may improve performance because - /// the compiler may be able to optimize copying from stack. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// - /// let big_box = Box::<[usize; 1024]>::new_uninit(); - /// - /// let mut array = [0; 1024]; - /// for (i, place) in array.iter_mut().enumerate() { - /// *place = i; - /// } - /// - /// // The optimizer may be able to elide this copy, so previous code writes - /// // to heap directly. - /// let big_box = Box::write(big_box, array); - /// - /// for (i, x) in big_box.iter().enumerate() { - /// assert_eq!(*x, i); - /// } - /// ``` - #[unstable(feature = "new_uninit", issue = "63291")] - #[inline] - pub fn write(mut boxed: Self, value: T) -> Box { - unsafe { - (*boxed).write(value); - boxed.assume_init() - } - } -} - -impl Box<[mem::MaybeUninit], A> { - /// Converts to `Box<[T], A>`. - /// - /// # Safety - /// - /// As with [`MaybeUninit::assume_init`], - /// it is up to the caller to guarantee that the values - /// really are in an initialized state. - /// Calling this when the content is not yet fully initialized - /// causes immediate undefined behavior. - /// - /// [`MaybeUninit::assume_init`]: mem::MaybeUninit::assume_init - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// - /// let mut values = Box::<[u32]>::new_uninit_slice(3); - /// - /// let values = unsafe { - /// // Deferred initialization: - /// values[0].as_mut_ptr().write(1); - /// values[1].as_mut_ptr().write(2); - /// values[2].as_mut_ptr().write(3); - /// - /// values.assume_init() - /// }; - /// - /// assert_eq!(*values, [1, 2, 3]) - /// ``` - #[unstable(feature = "new_uninit", issue = "63291")] - #[inline] - pub unsafe fn assume_init(self) -> Box<[T], A> { - let (raw, alloc) = Box::into_raw_with_allocator(self); - unsafe { Box::from_raw_in(raw as *mut [T], alloc) } - } -} - -impl Box { - /// Constructs a box from a raw pointer. - /// - /// After calling this function, the raw pointer is owned by the - /// resulting `Box`. Specifically, the `Box` destructor will call - /// the destructor of `T` and free the allocated memory. For this - /// to be safe, the memory must have been allocated in accordance - /// with the [memory layout] used by `Box` . - /// - /// # Safety - /// - /// This function is unsafe because improper use may lead to - /// memory problems. For example, a double-free may occur if the - /// function is called twice on the same raw pointer. - /// - /// The safety conditions are described in the [memory layout] section. - /// - /// # Examples - /// - /// Recreate a `Box` which was previously converted to a raw pointer - /// using [`Box::into_raw`]: - /// ``` - /// let x = Box::new(5); - /// let ptr = Box::into_raw(x); - /// let x = unsafe { Box::from_raw(ptr) }; - /// ``` - /// Manually create a `Box` from scratch by using the global allocator: - /// ``` - /// use std::alloc::{alloc, Layout}; - /// - /// unsafe { - /// let ptr = alloc(Layout::new::()) as *mut i32; - /// // In general .write is required to avoid attempting to destruct - /// // the (uninitialized) previous contents of `ptr`, though for this - /// // simple example `*ptr = 5` would have worked as well. - /// ptr.write(5); - /// let x = Box::from_raw(ptr); - /// } - /// ``` - /// - /// [memory layout]: self#memory-layout - /// [`Layout`]: crate::Layout - #[stable(feature = "box_raw", since = "1.4.0")] - #[inline] - #[must_use = "call `drop(Box::from_raw(ptr))` if you intend to drop the `Box`"] - pub unsafe fn from_raw(raw: *mut T) -> Self { - unsafe { Self::from_raw_in(raw, Global) } - } -} - -impl Box { - /// Constructs a box from a raw pointer in the given allocator. - /// - /// After calling this function, the raw pointer is owned by the - /// resulting `Box`. Specifically, the `Box` destructor will call - /// the destructor of `T` and free the allocated memory. For this - /// to be safe, the memory must have been allocated in accordance - /// with the [memory layout] used by `Box` . - /// - /// # Safety - /// - /// This function is unsafe because improper use may lead to - /// memory problems. For example, a double-free may occur if the - /// function is called twice on the same raw pointer. - /// - /// - /// # Examples - /// - /// Recreate a `Box` which was previously converted to a raw pointer - /// using [`Box::into_raw_with_allocator`]: - /// ``` - /// #![feature(allocator_api)] - /// - /// use std::alloc::System; - /// - /// let x = Box::new_in(5, System); - /// let (ptr, alloc) = Box::into_raw_with_allocator(x); - /// let x = unsafe { Box::from_raw_in(ptr, alloc) }; - /// ``` - /// Manually create a `Box` from scratch by using the system allocator: - /// ``` - /// #![feature(allocator_api, slice_ptr_get)] - /// - /// use std::alloc::{Allocator, Layout, System}; - /// - /// unsafe { - /// let ptr = System.allocate(Layout::new::())?.as_mut_ptr() as *mut i32; - /// // In general .write is required to avoid attempting to destruct - /// // the (uninitialized) previous contents of `ptr`, though for this - /// // simple example `*ptr = 5` would have worked as well. - /// ptr.write(5); - /// let x = Box::from_raw_in(ptr, System); - /// } - /// # Ok::<(), std::alloc::AllocError>(()) - /// ``` - /// - /// [memory layout]: self#memory-layout - /// [`Layout`]: crate::Layout - #[unstable(feature = "allocator_api", issue = "32838")] - #[rustc_const_unstable(feature = "const_box", issue = "92521")] - #[inline] - pub const unsafe fn from_raw_in(raw: *mut T, alloc: A) -> Self { - Box(unsafe { Unique::new_unchecked(raw) }, alloc) - } - - /// Consumes the `Box`, returning a wrapped raw pointer. - /// - /// The pointer will be properly aligned and non-null. - /// - /// After calling this function, the caller is responsible for the - /// memory previously managed by the `Box`. In particular, the - /// caller should properly destroy `T` and release the memory, taking - /// into account the [memory layout] used by `Box`. The easiest way to - /// do this is to convert the raw pointer back into a `Box` with the - /// [`Box::from_raw`] function, allowing the `Box` destructor to perform - /// the cleanup. - /// - /// Note: this is an associated function, which means that you have - /// to call it as `Box::into_raw(b)` instead of `b.into_raw()`. This - /// is so that there is no conflict with a method on the inner type. - /// - /// # Examples - /// Converting the raw pointer back into a `Box` with [`Box::from_raw`] - /// for automatic cleanup: - /// ``` - /// let x = Box::new(String::from("Hello")); - /// let ptr = Box::into_raw(x); - /// let x = unsafe { Box::from_raw(ptr) }; - /// ``` - /// Manual cleanup by explicitly running the destructor and deallocating - /// the memory: - /// ``` - /// use std::alloc::{dealloc, Layout}; - /// use std::ptr; - /// - /// let x = Box::new(String::from("Hello")); - /// let ptr = Box::into_raw(x); - /// unsafe { - /// ptr::drop_in_place(ptr); - /// dealloc(ptr as *mut u8, Layout::new::()); - /// } - /// ``` - /// Note: This is equivalent to the following: - /// ``` - /// let x = Box::new(String::from("Hello")); - /// let ptr = Box::into_raw(x); - /// unsafe { - /// drop(Box::from_raw(ptr)); - /// } - /// ``` - /// - /// [memory layout]: self#memory-layout - #[stable(feature = "box_raw", since = "1.4.0")] - #[inline] - pub fn into_raw(b: Self) -> *mut T { - // Make sure Miri realizes that we transition from a noalias pointer to a raw pointer here. - unsafe { addr_of_mut!(*&mut *Self::into_raw_with_allocator(b).0) } - } - - /// Consumes the `Box`, returning a wrapped raw pointer and the allocator. - /// - /// The pointer will be properly aligned and non-null. - /// - /// After calling this function, the caller is responsible for the - /// memory previously managed by the `Box`. In particular, the - /// caller should properly destroy `T` and release the memory, taking - /// into account the [memory layout] used by `Box`. The easiest way to - /// do this is to convert the raw pointer back into a `Box` with the - /// [`Box::from_raw_in`] function, allowing the `Box` destructor to perform - /// the cleanup. - /// - /// Note: this is an associated function, which means that you have - /// to call it as `Box::into_raw_with_allocator(b)` instead of `b.into_raw_with_allocator()`. This - /// is so that there is no conflict with a method on the inner type. - /// - /// # Examples - /// Converting the raw pointer back into a `Box` with [`Box::from_raw_in`] - /// for automatic cleanup: - /// ``` - /// #![feature(allocator_api)] - /// - /// use std::alloc::System; - /// - /// let x = Box::new_in(String::from("Hello"), System); - /// let (ptr, alloc) = Box::into_raw_with_allocator(x); - /// let x = unsafe { Box::from_raw_in(ptr, alloc) }; - /// ``` - /// Manual cleanup by explicitly running the destructor and deallocating - /// the memory: - /// ``` - /// #![feature(allocator_api)] - /// - /// use std::alloc::{Allocator, Layout, System}; - /// use std::ptr::{self, NonNull}; - /// - /// let x = Box::new_in(String::from("Hello"), System); - /// let (ptr, alloc) = Box::into_raw_with_allocator(x); - /// unsafe { - /// ptr::drop_in_place(ptr); - /// let non_null = NonNull::new_unchecked(ptr); - /// alloc.deallocate(non_null.cast(), Layout::new::()); - /// } - /// ``` - /// - /// [memory layout]: self#memory-layout - #[unstable(feature = "allocator_api", issue = "32838")] - #[inline] - pub fn into_raw_with_allocator(b: Self) -> (*mut T, A) { - let mut b = mem::ManuallyDrop::new(b); - // We carefully get the raw pointer out in a way that Miri's aliasing model understands what - // is happening: using the primitive "deref" of `Box`. In case `A` is *not* `Global`, we - // want *no* aliasing requirements here! - // In case `A` *is* `Global`, this does not quite have the right behavior; `into_raw` - // works around that. - let ptr = addr_of_mut!(**b); - let alloc = unsafe { ptr::read(&b.1) }; - (ptr, alloc) - } - - #[unstable( - feature = "ptr_internals", - issue = "none", - reason = "use `Box::leak(b).into()` or `Unique::from(Box::leak(b))` instead" - )] - #[inline] - #[doc(hidden)] - pub fn into_unique(b: Self) -> (Unique, A) { - let (ptr, alloc) = Box::into_raw_with_allocator(b); - unsafe { (Unique::from(&mut *ptr), alloc) } - } - - /// Returns a reference to the underlying allocator. - /// - /// Note: this is an associated function, which means that you have - /// to call it as `Box::allocator(&b)` instead of `b.allocator()`. This - /// is so that there is no conflict with a method on the inner type. - #[unstable(feature = "allocator_api", issue = "32838")] - #[rustc_const_unstable(feature = "const_box", issue = "92521")] - #[inline] - pub const fn allocator(b: &Self) -> &A { - &b.1 - } - - /// Consumes and leaks the `Box`, returning a mutable reference, - /// `&'a mut T`. Note that the type `T` must outlive the chosen lifetime - /// `'a`. If the type has only static references, or none at all, then this - /// may be chosen to be `'static`. - /// - /// This function is mainly useful for data that lives for the remainder of - /// the program's life. Dropping the returned reference will cause a memory - /// leak. If this is not acceptable, the reference should first be wrapped - /// with the [`Box::from_raw`] function producing a `Box`. This `Box` can - /// then be dropped which will properly destroy `T` and release the - /// allocated memory. - /// - /// Note: this is an associated function, which means that you have - /// to call it as `Box::leak(b)` instead of `b.leak()`. This - /// is so that there is no conflict with a method on the inner type. - /// - /// # Examples - /// - /// Simple usage: - /// - /// ``` - /// let x = Box::new(41); - /// let static_ref: &'static mut usize = Box::leak(x); - /// *static_ref += 1; - /// assert_eq!(*static_ref, 42); - /// ``` - /// - /// Unsized data: - /// - /// ``` - /// let x = vec![1, 2, 3].into_boxed_slice(); - /// let static_ref = Box::leak(x); - /// static_ref[0] = 4; - /// assert_eq!(*static_ref, [4, 2, 3]); - /// ``` - #[stable(feature = "box_leak", since = "1.26.0")] - #[inline] - pub fn leak<'a>(b: Self) -> &'a mut T - where - A: 'a, - { - unsafe { &mut *Box::into_raw(b) } - } - - /// Converts a `Box` into a `Pin>`. If `T` does not implement [`Unpin`], then - /// `*boxed` will be pinned in memory and unable to be moved. - /// - /// This conversion does not allocate on the heap and happens in place. - /// - /// This is also available via [`From`]. - /// - /// Constructing and pinning a `Box` with Box::into_pin([Box::new]\(x)) - /// can also be written more concisely using [Box::pin]\(x). - /// This `into_pin` method is useful if you already have a `Box`, or you are - /// constructing a (pinned) `Box` in a different way than with [`Box::new`]. - /// - /// # Notes - /// - /// It's not recommended that crates add an impl like `From> for Pin`, - /// as it'll introduce an ambiguity when calling `Pin::from`. - /// A demonstration of such a poor impl is shown below. - /// - /// ```compile_fail - /// # use std::pin::Pin; - /// struct Foo; // A type defined in this crate. - /// impl From> for Pin { - /// fn from(_: Box<()>) -> Pin { - /// Pin::new(Foo) - /// } - /// } - /// - /// let foo = Box::new(()); - /// let bar = Pin::from(foo); - /// ``` - #[stable(feature = "box_into_pin", since = "1.63.0")] - #[rustc_const_unstable(feature = "const_box", issue = "92521")] - pub const fn into_pin(boxed: Self) -> Pin - where - A: 'static, - { - // It's not possible to move or replace the insides of a `Pin>` - // when `T: !Unpin`, so it's safe to pin it directly without any - // additional requirements. - unsafe { Pin::new_unchecked(boxed) } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl<#[may_dangle] T: ?Sized, A: Allocator> Drop for Box { - #[inline] - fn drop(&mut self) { - // the T in the Box is dropped by the compiler before the destructor is run - - let ptr = self.0; - - unsafe { - let layout = Layout::for_value_raw(ptr.as_ptr()); - if layout.size() != 0 { - self.1.deallocate(From::from(ptr.cast()), layout); - } - } - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl Default for Box { - /// Creates a `Box`, with the `Default` value for T. - #[inline] - fn default() -> Self { - Box::new(T::default()) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl Default for Box<[T]> { - #[inline] - fn default() -> Self { - let ptr: Unique<[T]> = Unique::<[T; 0]>::dangling(); - Box(ptr, Global) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "default_box_extra", since = "1.17.0")] -impl Default for Box { - #[inline] - fn default() -> Self { - // SAFETY: This is the same as `Unique::cast` but with an unsized `U = str`. - let ptr: Unique = unsafe { - let bytes: Unique<[u8]> = Unique::<[u8; 0]>::dangling(); - Unique::new_unchecked(bytes.as_ptr() as *mut str) - }; - Box(ptr, Global) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Box { - /// Returns a new box with a `clone()` of this box's contents. - /// - /// # Examples - /// - /// ``` - /// let x = Box::new(5); - /// let y = x.clone(); - /// - /// // The value is the same - /// assert_eq!(x, y); - /// - /// // But they are unique objects - /// assert_ne!(&*x as *const i32, &*y as *const i32); - /// ``` - #[inline] - fn clone(&self) -> Self { - // Pre-allocate memory to allow writing the cloned value directly. - let mut boxed = Self::new_uninit_in(self.1.clone()); - unsafe { - (**self).write_clone_into_raw(boxed.as_mut_ptr()); - boxed.assume_init() - } - } - - /// Copies `source`'s contents into `self` without creating a new allocation. - /// - /// # Examples - /// - /// ``` - /// let x = Box::new(5); - /// let mut y = Box::new(10); - /// let yp: *const i32 = &*y; - /// - /// y.clone_from(&x); - /// - /// // The value is the same - /// assert_eq!(x, y); - /// - /// // And no allocation occurred - /// assert_eq!(yp, &*y); - /// ``` - #[inline] - fn clone_from(&mut self, source: &Self) { - (**self).clone_from(&(**source)); - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "box_slice_clone", since = "1.3.0")] -impl Clone for Box { - fn clone(&self) -> Self { - // this makes a copy of the data - let buf: Box<[u8]> = self.as_bytes().into(); - unsafe { from_boxed_utf8_unchecked(buf) } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for Box { - #[inline] - fn eq(&self, other: &Self) -> bool { - PartialEq::eq(&**self, &**other) - } - #[inline] - fn ne(&self, other: &Self) -> bool { - PartialEq::ne(&**self, &**other) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialOrd for Box { - #[inline] - fn partial_cmp(&self, other: &Self) -> Option { - PartialOrd::partial_cmp(&**self, &**other) - } - #[inline] - fn lt(&self, other: &Self) -> bool { - PartialOrd::lt(&**self, &**other) - } - #[inline] - fn le(&self, other: &Self) -> bool { - PartialOrd::le(&**self, &**other) - } - #[inline] - fn ge(&self, other: &Self) -> bool { - PartialOrd::ge(&**self, &**other) - } - #[inline] - fn gt(&self, other: &Self) -> bool { - PartialOrd::gt(&**self, &**other) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for Box { - #[inline] - fn cmp(&self, other: &Self) -> Ordering { - Ord::cmp(&**self, &**other) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl Eq for Box {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Hash for Box { - fn hash(&self, state: &mut H) { - (**self).hash(state); - } -} - -#[stable(feature = "indirect_hasher_impl", since = "1.22.0")] -impl Hasher for Box { - fn finish(&self) -> u64 { - (**self).finish() - } - fn write(&mut self, bytes: &[u8]) { - (**self).write(bytes) - } - fn write_u8(&mut self, i: u8) { - (**self).write_u8(i) - } - fn write_u16(&mut self, i: u16) { - (**self).write_u16(i) - } - fn write_u32(&mut self, i: u32) { - (**self).write_u32(i) - } - fn write_u64(&mut self, i: u64) { - (**self).write_u64(i) - } - fn write_u128(&mut self, i: u128) { - (**self).write_u128(i) - } - fn write_usize(&mut self, i: usize) { - (**self).write_usize(i) - } - fn write_i8(&mut self, i: i8) { - (**self).write_i8(i) - } - fn write_i16(&mut self, i: i16) { - (**self).write_i16(i) - } - fn write_i32(&mut self, i: i32) { - (**self).write_i32(i) - } - fn write_i64(&mut self, i: i64) { - (**self).write_i64(i) - } - fn write_i128(&mut self, i: i128) { - (**self).write_i128(i) - } - fn write_isize(&mut self, i: isize) { - (**self).write_isize(i) - } - fn write_length_prefix(&mut self, len: usize) { - (**self).write_length_prefix(len) - } - fn write_str(&mut self, s: &str) { - (**self).write_str(s) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "from_for_ptrs", since = "1.6.0")] -impl From for Box { - /// Converts a `T` into a `Box` - /// - /// The conversion allocates on the heap and moves `t` - /// from the stack into it. - /// - /// # Examples - /// - /// ```rust - /// let x = 5; - /// let boxed = Box::new(5); - /// - /// assert_eq!(Box::from(x), boxed); - /// ``` - fn from(t: T) -> Self { - Box::new(t) - } -} - -#[stable(feature = "pin", since = "1.33.0")] -impl From> for Pin> -where - A: 'static, -{ - /// Converts a `Box` into a `Pin>`. If `T` does not implement [`Unpin`], then - /// `*boxed` will be pinned in memory and unable to be moved. - /// - /// This conversion does not allocate on the heap and happens in place. - /// - /// This is also available via [`Box::into_pin`]. - /// - /// Constructing and pinning a `Box` with >>::from([Box::new]\(x)) - /// can also be written more concisely using [Box::pin]\(x). - /// This `From` implementation is useful if you already have a `Box`, or you are - /// constructing a (pinned) `Box` in a different way than with [`Box::new`]. - fn from(boxed: Box) -> Self { - Box::into_pin(boxed) - } -} - -/// Specialization trait used for `From<&[T]>`. -#[cfg(not(no_global_oom_handling))] -trait BoxFromSlice { - fn from_slice(slice: &[T]) -> Self; -} - -#[cfg(not(no_global_oom_handling))] -impl BoxFromSlice for Box<[T]> { - #[inline] - default fn from_slice(slice: &[T]) -> Self { - slice.to_vec().into_boxed_slice() - } -} - -#[cfg(not(no_global_oom_handling))] -impl BoxFromSlice for Box<[T]> { - #[inline] - fn from_slice(slice: &[T]) -> Self { - let len = slice.len(); - let buf = RawVec::with_capacity(len); - unsafe { - ptr::copy_nonoverlapping(slice.as_ptr(), buf.ptr(), len); - buf.into_box(slice.len()).assume_init() - } - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "box_from_slice", since = "1.17.0")] -impl From<&[T]> for Box<[T]> { - /// Converts a `&[T]` into a `Box<[T]>` - /// - /// This conversion allocates on the heap - /// and performs a copy of `slice` and its contents. - /// - /// # Examples - /// ```rust - /// // create a &[u8] which will be used to create a Box<[u8]> - /// let slice: &[u8] = &[104, 101, 108, 108, 111]; - /// let boxed_slice: Box<[u8]> = Box::from(slice); - /// - /// println!("{boxed_slice:?}"); - /// ``` - #[inline] - fn from(slice: &[T]) -> Box<[T]> { - >::from_slice(slice) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "box_from_cow", since = "1.45.0")] -impl From> for Box<[T]> { - /// Converts a `Cow<'_, [T]>` into a `Box<[T]>` - /// - /// When `cow` is the `Cow::Borrowed` variant, this - /// conversion allocates on the heap and copies the - /// underlying slice. Otherwise, it will try to reuse the owned - /// `Vec`'s allocation. - #[inline] - fn from(cow: Cow<'_, [T]>) -> Box<[T]> { - match cow { - Cow::Borrowed(slice) => Box::from(slice), - Cow::Owned(slice) => Box::from(slice), - } - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "box_from_slice", since = "1.17.0")] -impl From<&str> for Box { - /// Converts a `&str` into a `Box` - /// - /// This conversion allocates on the heap - /// and performs a copy of `s`. - /// - /// # Examples - /// - /// ```rust - /// let boxed: Box = Box::from("hello"); - /// println!("{boxed}"); - /// ``` - #[inline] - fn from(s: &str) -> Box { - unsafe { from_boxed_utf8_unchecked(Box::from(s.as_bytes())) } - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "box_from_cow", since = "1.45.0")] -impl From> for Box { - /// Converts a `Cow<'_, str>` into a `Box` - /// - /// When `cow` is the `Cow::Borrowed` variant, this - /// conversion allocates on the heap and copies the - /// underlying `str`. Otherwise, it will try to reuse the owned - /// `String`'s allocation. - /// - /// # Examples - /// - /// ```rust - /// use std::borrow::Cow; - /// - /// let unboxed = Cow::Borrowed("hello"); - /// let boxed: Box = Box::from(unboxed); - /// println!("{boxed}"); - /// ``` - /// - /// ```rust - /// # use std::borrow::Cow; - /// let unboxed = Cow::Owned("hello".to_string()); - /// let boxed: Box = Box::from(unboxed); - /// println!("{boxed}"); - /// ``` - #[inline] - fn from(cow: Cow<'_, str>) -> Box { - match cow { - Cow::Borrowed(s) => Box::from(s), - Cow::Owned(s) => Box::from(s), - } - } -} - -#[stable(feature = "boxed_str_conv", since = "1.19.0")] -impl From> for Box<[u8], A> { - /// Converts a `Box` into a `Box<[u8]>` - /// - /// This conversion does not allocate on the heap and happens in place. - /// - /// # Examples - /// ```rust - /// // create a Box which will be used to create a Box<[u8]> - /// let boxed: Box = Box::from("hello"); - /// let boxed_str: Box<[u8]> = Box::from(boxed); - /// - /// // create a &[u8] which will be used to create a Box<[u8]> - /// let slice: &[u8] = &[104, 101, 108, 108, 111]; - /// let boxed_slice = Box::from(slice); - /// - /// assert_eq!(boxed_slice, boxed_str); - /// ``` - #[inline] - fn from(s: Box) -> Self { - let (raw, alloc) = Box::into_raw_with_allocator(s); - unsafe { Box::from_raw_in(raw as *mut [u8], alloc) } - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "box_from_array", since = "1.45.0")] -impl From<[T; N]> for Box<[T]> { - /// Converts a `[T; N]` into a `Box<[T]>` - /// - /// This conversion moves the array to newly heap-allocated memory. - /// - /// # Examples - /// - /// ```rust - /// let boxed: Box<[u8]> = Box::from([4, 2]); - /// println!("{boxed:?}"); - /// ``` - fn from(array: [T; N]) -> Box<[T]> { - Box::new(array) - } -} - -/// Casts a boxed slice to a boxed array. -/// -/// # Safety -/// -/// `boxed_slice.len()` must be exactly `N`. -unsafe fn boxed_slice_as_array_unchecked( - boxed_slice: Box<[T], A>, -) -> Box<[T; N], A> { - debug_assert_eq!(boxed_slice.len(), N); - - let (ptr, alloc) = Box::into_raw_with_allocator(boxed_slice); - // SAFETY: Pointer and allocator came from an existing box, - // and our safety condition requires that the length is exactly `N` - unsafe { Box::from_raw_in(ptr as *mut [T; N], alloc) } -} - -#[stable(feature = "boxed_slice_try_from", since = "1.43.0")] -impl TryFrom> for Box<[T; N]> { - type Error = Box<[T]>; - - /// Attempts to convert a `Box<[T]>` into a `Box<[T; N]>`. - /// - /// The conversion occurs in-place and does not require a - /// new memory allocation. - /// - /// # Errors - /// - /// Returns the old `Box<[T]>` in the `Err` variant if - /// `boxed_slice.len()` does not equal `N`. - fn try_from(boxed_slice: Box<[T]>) -> Result { - if boxed_slice.len() == N { - Ok(unsafe { boxed_slice_as_array_unchecked(boxed_slice) }) - } else { - Err(boxed_slice) - } - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "boxed_array_try_from_vec", since = "1.66.0")] -impl TryFrom> for Box<[T; N]> { - type Error = Vec; - - /// Attempts to convert a `Vec` into a `Box<[T; N]>`. - /// - /// Like [`Vec::into_boxed_slice`], this is in-place if `vec.capacity() == N`, - /// but will require a reallocation otherwise. - /// - /// # Errors - /// - /// Returns the original `Vec` in the `Err` variant if - /// `boxed_slice.len()` does not equal `N`. - /// - /// # Examples - /// - /// This can be used with [`vec!`] to create an array on the heap: - /// - /// ``` - /// let state: Box<[f32; 100]> = vec![1.0; 100].try_into().unwrap(); - /// assert_eq!(state.len(), 100); - /// ``` - fn try_from(vec: Vec) -> Result { - if vec.len() == N { - let boxed_slice = vec.into_boxed_slice(); - Ok(unsafe { boxed_slice_as_array_unchecked(boxed_slice) }) - } else { - Err(vec) - } - } -} - -impl Box { - /// Attempt to downcast the box to a concrete type. - /// - /// # Examples - /// - /// ``` - /// use std::any::Any; - /// - /// fn print_if_string(value: Box) { - /// if let Ok(string) = value.downcast::() { - /// println!("String ({}): {}", string.len(), string); - /// } - /// } - /// - /// let my_string = "Hello World".to_string(); - /// print_if_string(Box::new(my_string)); - /// print_if_string(Box::new(0i8)); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn downcast(self) -> Result, Self> { - if self.is::() { unsafe { Ok(self.downcast_unchecked::()) } } else { Err(self) } - } - - /// Downcasts the box to a concrete type. - /// - /// For a safe alternative see [`downcast`]. - /// - /// # Examples - /// - /// ``` - /// #![feature(downcast_unchecked)] - /// - /// use std::any::Any; - /// - /// let x: Box = Box::new(1_usize); - /// - /// unsafe { - /// assert_eq!(*x.downcast_unchecked::(), 1); - /// } - /// ``` - /// - /// # Safety - /// - /// The contained value must be of type `T`. Calling this method - /// with the incorrect type is *undefined behavior*. - /// - /// [`downcast`]: Self::downcast - #[inline] - #[unstable(feature = "downcast_unchecked", issue = "90850")] - pub unsafe fn downcast_unchecked(self) -> Box { - debug_assert!(self.is::()); - unsafe { - let (raw, alloc): (*mut dyn Any, _) = Box::into_raw_with_allocator(self); - Box::from_raw_in(raw as *mut T, alloc) - } - } -} - -impl Box { - /// Attempt to downcast the box to a concrete type. - /// - /// # Examples - /// - /// ``` - /// use std::any::Any; - /// - /// fn print_if_string(value: Box) { - /// if let Ok(string) = value.downcast::() { - /// println!("String ({}): {}", string.len(), string); - /// } - /// } - /// - /// let my_string = "Hello World".to_string(); - /// print_if_string(Box::new(my_string)); - /// print_if_string(Box::new(0i8)); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn downcast(self) -> Result, Self> { - if self.is::() { unsafe { Ok(self.downcast_unchecked::()) } } else { Err(self) } - } - - /// Downcasts the box to a concrete type. - /// - /// For a safe alternative see [`downcast`]. - /// - /// # Examples - /// - /// ``` - /// #![feature(downcast_unchecked)] - /// - /// use std::any::Any; - /// - /// let x: Box = Box::new(1_usize); - /// - /// unsafe { - /// assert_eq!(*x.downcast_unchecked::(), 1); - /// } - /// ``` - /// - /// # Safety - /// - /// The contained value must be of type `T`. Calling this method - /// with the incorrect type is *undefined behavior*. - /// - /// [`downcast`]: Self::downcast - #[inline] - #[unstable(feature = "downcast_unchecked", issue = "90850")] - pub unsafe fn downcast_unchecked(self) -> Box { - debug_assert!(self.is::()); - unsafe { - let (raw, alloc): (*mut (dyn Any + Send), _) = Box::into_raw_with_allocator(self); - Box::from_raw_in(raw as *mut T, alloc) - } - } -} - -impl Box { - /// Attempt to downcast the box to a concrete type. - /// - /// # Examples - /// - /// ``` - /// use std::any::Any; - /// - /// fn print_if_string(value: Box) { - /// if let Ok(string) = value.downcast::() { - /// println!("String ({}): {}", string.len(), string); - /// } - /// } - /// - /// let my_string = "Hello World".to_string(); - /// print_if_string(Box::new(my_string)); - /// print_if_string(Box::new(0i8)); - /// ``` - #[inline] - #[stable(feature = "box_send_sync_any_downcast", since = "1.51.0")] - pub fn downcast(self) -> Result, Self> { - if self.is::() { unsafe { Ok(self.downcast_unchecked::()) } } else { Err(self) } - } - - /// Downcasts the box to a concrete type. - /// - /// For a safe alternative see [`downcast`]. - /// - /// # Examples - /// - /// ``` - /// #![feature(downcast_unchecked)] - /// - /// use std::any::Any; - /// - /// let x: Box = Box::new(1_usize); - /// - /// unsafe { - /// assert_eq!(*x.downcast_unchecked::(), 1); - /// } - /// ``` - /// - /// # Safety - /// - /// The contained value must be of type `T`. Calling this method - /// with the incorrect type is *undefined behavior*. - /// - /// [`downcast`]: Self::downcast - #[inline] - #[unstable(feature = "downcast_unchecked", issue = "90850")] - pub unsafe fn downcast_unchecked(self) -> Box { - debug_assert!(self.is::()); - unsafe { - let (raw, alloc): (*mut (dyn Any + Send + Sync), _) = - Box::into_raw_with_allocator(self); - Box::from_raw_in(raw as *mut T, alloc) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for Box { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt(&**self, f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for Box { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&**self, f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Pointer for Box { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - // It's not possible to extract the inner Uniq directly from the Box, - // instead we cast it to a *const which aliases the Unique - let ptr: *const T = &**self; - fmt::Pointer::fmt(&ptr, f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Deref for Box { - type Target = T; - - fn deref(&self) -> &T { - &**self - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DerefMut for Box { - fn deref_mut(&mut self) -> &mut T { - &mut **self - } -} - -#[unstable(feature = "deref_pure_trait", issue = "87121")] -unsafe impl DerefPure for Box {} - -#[unstable(feature = "receiver_trait", issue = "none")] -impl Receiver for Box {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for Box { - type Item = I::Item; - fn next(&mut self) -> Option { - (**self).next() - } - fn size_hint(&self) -> (usize, Option) { - (**self).size_hint() - } - fn nth(&mut self, n: usize) -> Option { - (**self).nth(n) - } - fn last(self) -> Option { - BoxIter::last(self) - } -} - -trait BoxIter { - type Item; - fn last(self) -> Option; -} - -impl BoxIter for Box { - type Item = I::Item; - default fn last(self) -> Option { - #[inline] - fn some(_: Option, x: T) -> Option { - Some(x) - } - - self.fold(None, some) - } -} - -/// Specialization for sized `I`s that uses `I`s implementation of `last()` -/// instead of the default. -#[stable(feature = "rust1", since = "1.0.0")] -impl BoxIter for Box { - fn last(self) -> Option { - (*self).last() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DoubleEndedIterator for Box { - fn next_back(&mut self) -> Option { - (**self).next_back() - } - fn nth_back(&mut self, n: usize) -> Option { - (**self).nth_back(n) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Box { - fn len(&self) -> usize { - (**self).len() - } - fn is_empty(&self) -> bool { - (**self).is_empty() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Box {} - -#[stable(feature = "boxed_closure_impls", since = "1.35.0")] -impl + ?Sized, A: Allocator> FnOnce for Box { - type Output = >::Output; - - extern "rust-call" fn call_once(self, args: Args) -> Self::Output { - >::call_once(*self, args) - } -} - -#[stable(feature = "boxed_closure_impls", since = "1.35.0")] -impl + ?Sized, A: Allocator> FnMut for Box { - extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output { - >::call_mut(self, args) - } -} - -#[stable(feature = "boxed_closure_impls", since = "1.35.0")] -impl + ?Sized, A: Allocator> Fn for Box { - extern "rust-call" fn call(&self, args: Args) -> Self::Output { - >::call(self, args) - } -} - -#[unstable(feature = "async_fn_traits", issue = "none")] -impl + ?Sized, A: Allocator> AsyncFnOnce for Box { - type Output = F::Output; - type CallOnceFuture = F::CallOnceFuture; - - extern "rust-call" fn async_call_once(self, args: Args) -> Self::CallOnceFuture { - F::async_call_once(*self, args) - } -} - -#[unstable(feature = "async_fn_traits", issue = "none")] -impl + ?Sized, A: Allocator> AsyncFnMut for Box { - type CallRefFuture<'a> = F::CallRefFuture<'a> where Self: 'a; - - extern "rust-call" fn async_call_mut(&mut self, args: Args) -> Self::CallRefFuture<'_> { - F::async_call_mut(self, args) - } -} - -#[unstable(feature = "async_fn_traits", issue = "none")] -impl + ?Sized, A: Allocator> AsyncFn for Box { - extern "rust-call" fn async_call(&self, args: Args) -> Self::CallRefFuture<'_> { - F::async_call(self, args) - } -} - -#[unstable(feature = "coerce_unsized", issue = "18598")] -impl, U: ?Sized, A: Allocator> CoerceUnsized> for Box {} - -// It is quite crucial that we only allow the `Global` allocator here. -// Handling arbitrary custom allocators (which can affect the `Box` layout heavily!) -// would need a lot of codegen and interpreter adjustments. -#[unstable(feature = "dispatch_from_dyn", issue = "none")] -impl, U: ?Sized> DispatchFromDyn> for Box {} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "boxed_slice_from_iter", since = "1.32.0")] -impl FromIterator for Box<[I]> { - fn from_iter>(iter: T) -> Self { - iter.into_iter().collect::>().into_boxed_slice() - } -} - -/// This implementation is required to make sure that the `Box<[I]>: IntoIterator` -/// implementation doesn't overlap with `IntoIterator for T where T: Iterator` blanket. -#[stable(feature = "boxed_slice_into_iter", since = "CURRENT_RUSTC_VERSION")] -impl !Iterator for Box<[I], A> {} - -/// This implementation is required to make sure that the `&Box<[I]>: IntoIterator` -/// implementation doesn't overlap with `IntoIterator for T where T: Iterator` blanket. -#[stable(feature = "boxed_slice_into_iter", since = "CURRENT_RUSTC_VERSION")] -impl<'a, I, A: Allocator> !Iterator for &'a Box<[I], A> {} - -/// This implementation is required to make sure that the `&mut Box<[I]>: IntoIterator` -/// implementation doesn't overlap with `IntoIterator for T where T: Iterator` blanket. -#[stable(feature = "boxed_slice_into_iter", since = "CURRENT_RUSTC_VERSION")] -impl<'a, I, A: Allocator> !Iterator for &'a mut Box<[I], A> {} - -// Note: the `#[rustc_skip_during_method_dispatch(boxed_slice)]` on `trait IntoIterator` -// hides this implementation from explicit `.into_iter()` calls on editions < 2024, -// so those calls will still resolve to the slice implementation, by reference. -#[stable(feature = "boxed_slice_into_iter", since = "CURRENT_RUSTC_VERSION")] -impl IntoIterator for Box<[I], A> { - type IntoIter = vec::IntoIter; - type Item = I; - fn into_iter(self) -> vec::IntoIter { - self.into_vec().into_iter() - } -} - -#[stable(feature = "boxed_slice_into_iter", since = "CURRENT_RUSTC_VERSION")] -impl<'a, I, A: Allocator> IntoIterator for &'a Box<[I], A> { - type IntoIter = slice::Iter<'a, I>; - type Item = &'a I; - fn into_iter(self) -> slice::Iter<'a, I> { - self.iter() - } -} - -#[stable(feature = "boxed_slice_into_iter", since = "CURRENT_RUSTC_VERSION")] -impl<'a, I, A: Allocator> IntoIterator for &'a mut Box<[I], A> { - type IntoIter = slice::IterMut<'a, I>; - type Item = &'a mut I; - fn into_iter(self) -> slice::IterMut<'a, I> { - self.iter_mut() - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "boxed_str_from_iter", since = "CURRENT_RUSTC_VERSION")] -impl FromIterator for Box { - fn from_iter>(iter: T) -> Self { - String::from_iter(iter).into_boxed_str() - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "boxed_str_from_iter", since = "CURRENT_RUSTC_VERSION")] -impl<'a> FromIterator<&'a char> for Box { - fn from_iter>(iter: T) -> Self { - String::from_iter(iter).into_boxed_str() - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "boxed_str_from_iter", since = "CURRENT_RUSTC_VERSION")] -impl<'a> FromIterator<&'a str> for Box { - fn from_iter>(iter: T) -> Self { - String::from_iter(iter).into_boxed_str() - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "boxed_str_from_iter", since = "CURRENT_RUSTC_VERSION")] -impl FromIterator for Box { - fn from_iter>(iter: T) -> Self { - String::from_iter(iter).into_boxed_str() - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "boxed_str_from_iter", since = "CURRENT_RUSTC_VERSION")] -impl FromIterator> for Box { - fn from_iter>>(iter: T) -> Self { - String::from_iter(iter).into_boxed_str() - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "boxed_str_from_iter", since = "CURRENT_RUSTC_VERSION")] -impl<'a> FromIterator> for Box { - fn from_iter>>(iter: T) -> Self { - String::from_iter(iter).into_boxed_str() - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "box_slice_clone", since = "1.3.0")] -impl Clone for Box<[T], A> { - fn clone(&self) -> Self { - let alloc = Box::allocator(self).clone(); - self.to_vec_in(alloc).into_boxed_slice() - } - - /// Copies `source`'s contents into `self` without creating a new allocation, - /// so long as the two are of the same length. - /// - /// # Examples - /// - /// ``` - /// let x = Box::new([5, 6, 7]); - /// let mut y = Box::new([8, 9, 10]); - /// let yp: *const [i32] = &*y; - /// - /// y.clone_from(&x); - /// - /// // The value is the same - /// assert_eq!(x, y); - /// - /// // And no allocation occurred - /// assert_eq!(yp, &*y); - /// ``` - fn clone_from(&mut self, source: &Self) { - if self.len() == source.len() { - self.clone_from_slice(&source); - } else { - *self = source.clone(); - } - } -} - -#[stable(feature = "box_borrow", since = "1.1.0")] -impl borrow::Borrow for Box { - fn borrow(&self) -> &T { - &**self - } -} - -#[stable(feature = "box_borrow", since = "1.1.0")] -impl borrow::BorrowMut for Box { - fn borrow_mut(&mut self) -> &mut T { - &mut **self - } -} - -#[stable(since = "1.5.0", feature = "smart_ptr_as_ref")] -impl AsRef for Box { - fn as_ref(&self) -> &T { - &**self - } -} - -#[stable(since = "1.5.0", feature = "smart_ptr_as_ref")] -impl AsMut for Box { - fn as_mut(&mut self) -> &mut T { - &mut **self - } -} - -/* Nota bene - * - * We could have chosen not to add this impl, and instead have written a - * function of Pin> to Pin. Such a function would not be sound, - * because Box implements Unpin even when T does not, as a result of - * this impl. - * - * We chose this API instead of the alternative for a few reasons: - * - Logically, it is helpful to understand pinning in regard to the - * memory region being pointed to. For this reason none of the - * standard library pointer types support projecting through a pin - * (Box is the only pointer type in std for which this would be - * safe.) - * - It is in practice very useful to have Box be unconditionally - * Unpin because of trait objects, for which the structural auto - * trait functionality does not apply (e.g., Box would - * otherwise not be Unpin). - * - * Another type with the same semantics as Box but only a conditional - * implementation of `Unpin` (where `T: Unpin`) would be valid/safe, and - * could have a method to project a Pin from it. - */ -#[stable(feature = "pin", since = "1.33.0")] -impl Unpin for Box {} - -#[unstable(feature = "coroutine_trait", issue = "43122")] -impl + Unpin, R, A: Allocator> Coroutine for Box { - type Yield = G::Yield; - type Return = G::Return; - - fn resume(mut self: Pin<&mut Self>, arg: R) -> CoroutineState { - G::resume(Pin::new(&mut *self), arg) - } -} - -#[unstable(feature = "coroutine_trait", issue = "43122")] -impl, R, A: Allocator> Coroutine for Pin> -where - A: 'static, -{ - type Yield = G::Yield; - type Return = G::Return; - - fn resume(mut self: Pin<&mut Self>, arg: R) -> CoroutineState { - G::resume((*self).as_mut(), arg) - } -} - -#[stable(feature = "futures_api", since = "1.36.0")] -impl Future for Box { - type Output = F::Output; - - fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll { - F::poll(Pin::new(&mut *self), cx) - } -} - -#[unstable(feature = "async_iterator", issue = "79024")] -impl AsyncIterator for Box { - type Item = S::Item; - - fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll> { - Pin::new(&mut **self).poll_next(cx) - } - - fn size_hint(&self) -> (usize, Option) { - (**self).size_hint() - } -} - -impl dyn Error { - #[inline] - #[stable(feature = "error_downcast", since = "1.3.0")] - #[rustc_allow_incoherent_impl] - /// Attempts to downcast the box to a concrete type. - pub fn downcast(self: Box) -> Result, Box> { - if self.is::() { - unsafe { - let raw: *mut dyn Error = Box::into_raw(self); - Ok(Box::from_raw(raw as *mut T)) - } - } else { - Err(self) - } - } -} - -impl dyn Error + Send { - #[inline] - #[stable(feature = "error_downcast", since = "1.3.0")] - #[rustc_allow_incoherent_impl] - /// Attempts to downcast the box to a concrete type. - pub fn downcast(self: Box) -> Result, Box> { - let err: Box = self; - ::downcast(err).map_err(|s| unsafe { - // Reapply the `Send` marker. - Box::from_raw(Box::into_raw(s) as *mut (dyn Error + Send)) - }) - } -} - -impl dyn Error + Send + Sync { - #[inline] - #[stable(feature = "error_downcast", since = "1.3.0")] - #[rustc_allow_incoherent_impl] - /// Attempts to downcast the box to a concrete type. - pub fn downcast(self: Box) -> Result, Box> { - let err: Box = self; - ::downcast(err).map_err(|s| unsafe { - // Reapply the `Send + Sync` marker. - Box::from_raw(Box::into_raw(s) as *mut (dyn Error + Send + Sync)) - }) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, E: Error + 'a> From for Box { - /// Converts a type of [`Error`] into a box of dyn [`Error`]. - /// - /// # Examples - /// - /// ``` - /// use std::error::Error; - /// use std::fmt; - /// use std::mem; - /// - /// #[derive(Debug)] - /// struct AnError; - /// - /// impl fmt::Display for AnError { - /// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - /// write!(f, "An error") - /// } - /// } - /// - /// impl Error for AnError {} - /// - /// let an_error = AnError; - /// assert!(0 == mem::size_of_val(&an_error)); - /// let a_boxed_error = Box::::from(an_error); - /// assert!(mem::size_of::>() == mem::size_of_val(&a_boxed_error)) - /// ``` - fn from(err: E) -> Box { - Box::new(err) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, E: Error + Send + Sync + 'a> From for Box { - /// Converts a type of [`Error`] + [`Send`] + [`Sync`] into a box of - /// dyn [`Error`] + [`Send`] + [`Sync`]. - /// - /// # Examples - /// - /// ``` - /// use std::error::Error; - /// use std::fmt; - /// use std::mem; - /// - /// #[derive(Debug)] - /// struct AnError; - /// - /// impl fmt::Display for AnError { - /// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - /// write!(f, "An error") - /// } - /// } - /// - /// impl Error for AnError {} - /// - /// unsafe impl Send for AnError {} - /// - /// unsafe impl Sync for AnError {} - /// - /// let an_error = AnError; - /// assert!(0 == mem::size_of_val(&an_error)); - /// let a_boxed_error = Box::::from(an_error); - /// assert!( - /// mem::size_of::>() == mem::size_of_val(&a_boxed_error)) - /// ``` - fn from(err: E) -> Box { - Box::new(err) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a> From for Box { - /// Converts a [`String`] into a box of dyn [`Error`] + [`Send`] + [`Sync`]. - /// - /// # Examples - /// - /// ``` - /// use std::error::Error; - /// use std::mem; - /// - /// let a_string_error = "a string error".to_string(); - /// let a_boxed_error = Box::::from(a_string_error); - /// assert!( - /// mem::size_of::>() == mem::size_of_val(&a_boxed_error)) - /// ``` - #[inline] - fn from(err: String) -> Box { - struct StringError(String); - - impl Error for StringError { - #[allow(deprecated)] - fn description(&self) -> &str { - &self.0 - } - } - - impl fmt::Display for StringError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt(&self.0, f) - } - } - - // Purposefully skip printing "StringError(..)" - impl fmt::Debug for StringError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&self.0, f) - } - } - - Box::new(StringError(err)) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "string_box_error", since = "1.6.0")] -impl<'a> From for Box { - /// Converts a [`String`] into a box of dyn [`Error`]. - /// - /// # Examples - /// - /// ``` - /// use std::error::Error; - /// use std::mem; - /// - /// let a_string_error = "a string error".to_string(); - /// let a_boxed_error = Box::::from(a_string_error); - /// assert!(mem::size_of::>() == mem::size_of_val(&a_boxed_error)) - /// ``` - fn from(str_err: String) -> Box { - let err1: Box = From::from(str_err); - let err2: Box = err1; - err2 - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a> From<&str> for Box { - /// Converts a [`str`] into a box of dyn [`Error`] + [`Send`] + [`Sync`]. - /// - /// [`str`]: prim@str - /// - /// # Examples - /// - /// ``` - /// use std::error::Error; - /// use std::mem; - /// - /// let a_str_error = "a str error"; - /// let a_boxed_error = Box::::from(a_str_error); - /// assert!( - /// mem::size_of::>() == mem::size_of_val(&a_boxed_error)) - /// ``` - #[inline] - fn from(err: &str) -> Box { - From::from(String::from(err)) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "string_box_error", since = "1.6.0")] -impl<'a> From<&str> for Box { - /// Converts a [`str`] into a box of dyn [`Error`]. - /// - /// [`str`]: prim@str - /// - /// # Examples - /// - /// ``` - /// use std::error::Error; - /// use std::mem; - /// - /// let a_str_error = "a str error"; - /// let a_boxed_error = Box::::from(a_str_error); - /// assert!(mem::size_of::>() == mem::size_of_val(&a_boxed_error)) - /// ``` - fn from(err: &str) -> Box { - From::from(String::from(err)) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "cow_box_error", since = "1.22.0")] -impl<'a, 'b> From> for Box { - /// Converts a [`Cow`] into a box of dyn [`Error`] + [`Send`] + [`Sync`]. - /// - /// # Examples - /// - /// ``` - /// use std::error::Error; - /// use std::mem; - /// use std::borrow::Cow; - /// - /// let a_cow_str_error = Cow::from("a str error"); - /// let a_boxed_error = Box::::from(a_cow_str_error); - /// assert!( - /// mem::size_of::>() == mem::size_of_val(&a_boxed_error)) - /// ``` - fn from(err: Cow<'b, str>) -> Box { - From::from(String::from(err)) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "cow_box_error", since = "1.22.0")] -impl<'a, 'b> From> for Box { - /// Converts a [`Cow`] into a box of dyn [`Error`]. - /// - /// # Examples - /// - /// ``` - /// use std::error::Error; - /// use std::mem; - /// use std::borrow::Cow; - /// - /// let a_cow_str_error = Cow::from("a str error"); - /// let a_boxed_error = Box::::from(a_cow_str_error); - /// assert!(mem::size_of::>() == mem::size_of_val(&a_boxed_error)) - /// ``` - fn from(err: Cow<'b, str>) -> Box { - From::from(String::from(err)) - } -} - -#[stable(feature = "box_error", since = "1.8.0")] -impl core::error::Error for Box { - #[allow(deprecated, deprecated_in_future)] - fn description(&self) -> &str { - core::error::Error::description(&**self) - } - - #[allow(deprecated)] - fn cause(&self) -> Option<&dyn core::error::Error> { - core::error::Error::cause(&**self) - } - - fn source(&self) -> Option<&(dyn core::error::Error + 'static)> { - core::error::Error::source(&**self) - } - - fn provide<'b>(&'b self, request: &mut core::error::Request<'b>) { - core::error::Error::provide(&**self, request); - } -} diff --git a/library/alloc/src/boxed/thin.rs b/library/alloc/src/boxed/thin.rs deleted file mode 100644 index 8b145b67bf186..0000000000000 --- a/library/alloc/src/boxed/thin.rs +++ /dev/null @@ -1,436 +0,0 @@ -// Based on -// https://github.com/matthieu-m/rfc2580/blob/b58d1d3cba0d4b5e859d3617ea2d0943aaa31329/examples/thin.rs -// by matthieu-m -use crate::alloc::{self, Layout, LayoutError}; -use core::error::Error; -use core::fmt::{self, Debug, Display, Formatter}; -#[cfg(not(no_global_oom_handling))] -use core::intrinsics::const_allocate; -use core::marker::PhantomData; -#[cfg(not(no_global_oom_handling))] -use core::marker::Unsize; -use core::mem; -#[cfg(not(no_global_oom_handling))] -use core::mem::SizedTypeProperties; -use core::ops::{Deref, DerefMut}; -use core::ptr::Pointee; -use core::ptr::{self, NonNull}; - -/// ThinBox. -/// -/// A thin pointer for heap allocation, regardless of T. -/// -/// # Examples -/// -/// ``` -/// #![feature(thin_box)] -/// use std::boxed::ThinBox; -/// -/// let five = ThinBox::new(5); -/// let thin_slice = ThinBox::<[i32]>::new_unsize([1, 2, 3, 4]); -/// -/// use std::mem::{size_of, size_of_val}; -/// let size_of_ptr = size_of::<*const ()>(); -/// assert_eq!(size_of_ptr, size_of_val(&five)); -/// assert_eq!(size_of_ptr, size_of_val(&thin_slice)); -/// ``` -#[unstable(feature = "thin_box", issue = "92791")] -pub struct ThinBox { - // This is essentially `WithHeader<::Metadata>`, - // but that would be invariant in `T`, and we want covariance. - ptr: WithOpaqueHeader, - _marker: PhantomData, -} - -/// `ThinBox` is `Send` if `T` is `Send` because the data is owned. -#[unstable(feature = "thin_box", issue = "92791")] -unsafe impl Send for ThinBox {} - -/// `ThinBox` is `Sync` if `T` is `Sync` because the data is owned. -#[unstable(feature = "thin_box", issue = "92791")] -unsafe impl Sync for ThinBox {} - -#[unstable(feature = "thin_box", issue = "92791")] -impl ThinBox { - /// Moves a type to the heap with its [`Metadata`] stored in the heap allocation instead of on - /// the stack. - /// - /// # Examples - /// - /// ``` - /// #![feature(thin_box)] - /// use std::boxed::ThinBox; - /// - /// let five = ThinBox::new(5); - /// ``` - /// - /// [`Metadata`]: core::ptr::Pointee::Metadata - #[cfg(not(no_global_oom_handling))] - pub fn new(value: T) -> Self { - let meta = ptr::metadata(&value); - let ptr = WithOpaqueHeader::new(meta, value); - ThinBox { ptr, _marker: PhantomData } - } - - /// Moves a type to the heap with its [`Metadata`] stored in the heap allocation instead of on - /// the stack. Returns an error if allocation fails, instead of aborting. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// #![feature(thin_box)] - /// use std::boxed::ThinBox; - /// - /// let five = ThinBox::try_new(5)?; - /// # Ok::<(), std::alloc::AllocError>(()) - /// ``` - /// - /// [`Metadata`]: core::ptr::Pointee::Metadata - pub fn try_new(value: T) -> Result { - let meta = ptr::metadata(&value); - WithOpaqueHeader::try_new(meta, value).map(|ptr| ThinBox { ptr, _marker: PhantomData }) - } -} - -#[unstable(feature = "thin_box", issue = "92791")] -impl ThinBox { - /// Moves a type to the heap with its [`Metadata`] stored in the heap allocation instead of on - /// the stack. - /// - /// # Examples - /// - /// ``` - /// #![feature(thin_box)] - /// use std::boxed::ThinBox; - /// - /// let thin_slice = ThinBox::<[i32]>::new_unsize([1, 2, 3, 4]); - /// ``` - /// - /// [`Metadata`]: core::ptr::Pointee::Metadata - #[cfg(not(no_global_oom_handling))] - pub fn new_unsize(value: T) -> Self - where - T: Unsize, - { - if mem::size_of::() == 0 { - let ptr = WithOpaqueHeader::new_unsize_zst::(value); - ThinBox { ptr, _marker: PhantomData } - } else { - let meta = ptr::metadata(&value as &Dyn); - let ptr = WithOpaqueHeader::new(meta, value); - ThinBox { ptr, _marker: PhantomData } - } - } -} - -#[unstable(feature = "thin_box", issue = "92791")] -impl Debug for ThinBox { - fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { - Debug::fmt(self.deref(), f) - } -} - -#[unstable(feature = "thin_box", issue = "92791")] -impl Display for ThinBox { - fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { - Display::fmt(self.deref(), f) - } -} - -#[unstable(feature = "thin_box", issue = "92791")] -impl Deref for ThinBox { - type Target = T; - - fn deref(&self) -> &T { - let value = self.data(); - let metadata = self.meta(); - let pointer = ptr::from_raw_parts(value as *const (), metadata); - unsafe { &*pointer } - } -} - -#[unstable(feature = "thin_box", issue = "92791")] -impl DerefMut for ThinBox { - fn deref_mut(&mut self) -> &mut T { - let value = self.data(); - let metadata = self.meta(); - let pointer = ptr::from_raw_parts_mut::(value as *mut (), metadata); - unsafe { &mut *pointer } - } -} - -#[unstable(feature = "thin_box", issue = "92791")] -impl Drop for ThinBox { - fn drop(&mut self) { - unsafe { - let value = self.deref_mut(); - let value = value as *mut T; - self.with_header().drop::(value); - } - } -} - -#[unstable(feature = "thin_box", issue = "92791")] -impl ThinBox { - fn meta(&self) -> ::Metadata { - // Safety: - // - NonNull and valid. - unsafe { *self.with_header().header() } - } - - fn data(&self) -> *mut u8 { - self.with_header().value() - } - - fn with_header(&self) -> &WithHeader<::Metadata> { - // SAFETY: both types are transparent to `NonNull` - unsafe { &*(core::ptr::addr_of!(self.ptr) as *const WithHeader<_>) } - } -} - -/// A pointer to type-erased data, guaranteed to either be: -/// 1. `NonNull::dangling()`, in the case where both the pointee (`T`) and -/// metadata (`H`) are ZSTs. -/// 2. A pointer to a valid `T` that has a header `H` directly before the -/// pointed-to location. -#[repr(transparent)] -struct WithHeader(NonNull, PhantomData); - -/// An opaque representation of `WithHeader` to avoid the -/// projection invariance of `::Metadata`. -#[repr(transparent)] -struct WithOpaqueHeader(NonNull); - -impl WithOpaqueHeader { - #[cfg(not(no_global_oom_handling))] - fn new(header: H, value: T) -> Self { - let ptr = WithHeader::new(header, value); - Self(ptr.0) - } - - #[cfg(not(no_global_oom_handling))] - fn new_unsize_zst(value: T) -> Self - where - Dyn: ?Sized, - T: Unsize, - { - let ptr = WithHeader::<::Metadata>::new_unsize_zst::(value); - Self(ptr.0) - } - - fn try_new(header: H, value: T) -> Result { - WithHeader::try_new(header, value).map(|ptr| Self(ptr.0)) - } -} - -impl WithHeader { - #[cfg(not(no_global_oom_handling))] - fn new(header: H, value: T) -> WithHeader { - let value_layout = Layout::new::(); - let Ok((layout, value_offset)) = Self::alloc_layout(value_layout) else { - // We pass an empty layout here because we do not know which layout caused the - // arithmetic overflow in `Layout::extend` and `handle_alloc_error` takes `Layout` as - // its argument rather than `Result`, also this function has been - // stable since 1.28 ._. - // - // On the other hand, look at this gorgeous turbofish! - alloc::handle_alloc_error(Layout::new::<()>()); - }; - - unsafe { - // Note: It's UB to pass a layout with a zero size to `alloc::alloc`, so - // we use `layout.dangling()` for this case, which should have a valid - // alignment for both `T` and `H`. - let ptr = if layout.size() == 0 { - // Some paranoia checking, mostly so that the ThinBox tests are - // more able to catch issues. - debug_assert!(value_offset == 0 && T::IS_ZST && H::IS_ZST); - layout.dangling() - } else { - let ptr = alloc::alloc(layout); - if ptr.is_null() { - alloc::handle_alloc_error(layout); - } - // Safety: - // - The size is at least `aligned_header_size`. - let ptr = ptr.add(value_offset) as *mut _; - - NonNull::new_unchecked(ptr) - }; - - let result = WithHeader(ptr, PhantomData); - ptr::write(result.header(), header); - ptr::write(result.value().cast(), value); - - result - } - } - - /// Non-panicking version of `new`. - /// Any error is returned as `Err(core::alloc::AllocError)`. - fn try_new(header: H, value: T) -> Result, core::alloc::AllocError> { - let value_layout = Layout::new::(); - let Ok((layout, value_offset)) = Self::alloc_layout(value_layout) else { - return Err(core::alloc::AllocError); - }; - - unsafe { - // Note: It's UB to pass a layout with a zero size to `alloc::alloc`, so - // we use `layout.dangling()` for this case, which should have a valid - // alignment for both `T` and `H`. - let ptr = if layout.size() == 0 { - // Some paranoia checking, mostly so that the ThinBox tests are - // more able to catch issues. - debug_assert!( - value_offset == 0 && mem::size_of::() == 0 && mem::size_of::() == 0 - ); - layout.dangling() - } else { - let ptr = alloc::alloc(layout); - if ptr.is_null() { - return Err(core::alloc::AllocError); - } - - // Safety: - // - The size is at least `aligned_header_size`. - let ptr = ptr.add(value_offset) as *mut _; - - NonNull::new_unchecked(ptr) - }; - - let result = WithHeader(ptr, PhantomData); - ptr::write(result.header(), header); - ptr::write(result.value().cast(), value); - - Ok(result) - } - } - - // `Dyn` is `?Sized` type like `[u32]`, and `T` is ZST type like `[u32; 0]`. - #[cfg(not(no_global_oom_handling))] - fn new_unsize_zst(value: T) -> WithHeader - where - Dyn: Pointee + ?Sized, - T: Unsize, - { - assert!(mem::size_of::() == 0); - - const fn max(a: usize, b: usize) -> usize { - if a > b { a } else { b } - } - - // Compute a pointer to the right metadata. This will point to the beginning - // of the header, past the padding, so the assigned type makes sense. - // It also ensures that the address at the end of the header is sufficiently - // aligned for T. - let alloc: &::Metadata = const { - // FIXME: just call `WithHeader::alloc_layout` with size reset to 0. - // Currently that's blocked on `Layout::extend` not being `const fn`. - - let alloc_align = - max(mem::align_of::(), mem::align_of::<::Metadata>()); - - let alloc_size = - max(mem::align_of::(), mem::size_of::<::Metadata>()); - - unsafe { - // SAFETY: align is power of two because it is the maximum of two alignments. - let alloc: *mut u8 = const_allocate(alloc_size, alloc_align); - - let metadata_offset = - alloc_size.checked_sub(mem::size_of::<::Metadata>()).unwrap(); - // SAFETY: adding offset within the allocation. - let metadata_ptr: *mut ::Metadata = - alloc.add(metadata_offset).cast(); - // SAFETY: `*metadata_ptr` is within the allocation. - metadata_ptr.write(ptr::metadata::(ptr::dangling::() as *const Dyn)); - - // SAFETY: we have just written the metadata. - &*(metadata_ptr) - } - }; - - // SAFETY: `alloc` points to `::Metadata`, so addition stays in-bounds. - let value_ptr = - unsafe { (alloc as *const ::Metadata).add(1) }.cast::().cast_mut(); - debug_assert!(value_ptr.is_aligned()); - mem::forget(value); - WithHeader(NonNull::new(value_ptr.cast()).unwrap(), PhantomData) - } - - // Safety: - // - Assumes that either `value` can be dereferenced, or is the - // `NonNull::dangling()` we use when both `T` and `H` are ZSTs. - unsafe fn drop(&self, value: *mut T) { - struct DropGuard { - ptr: NonNull, - value_layout: Layout, - _marker: PhantomData, - } - - impl Drop for DropGuard { - fn drop(&mut self) { - // All ZST are allocated statically. - if self.value_layout.size() == 0 { - return; - } - - unsafe { - // SAFETY: Layout must have been computable if we're in drop - let (layout, value_offset) = - WithHeader::::alloc_layout(self.value_layout).unwrap_unchecked(); - - // Since we only allocate for non-ZSTs, the layout size cannot be zero. - debug_assert!(layout.size() != 0); - alloc::dealloc(self.ptr.as_ptr().sub(value_offset), layout); - } - } - } - - unsafe { - // `_guard` will deallocate the memory when dropped, even if `drop_in_place` unwinds. - let _guard = DropGuard { - ptr: self.0, - value_layout: Layout::for_value_raw(value), - _marker: PhantomData::, - }; - - // We only drop the value because the Pointee trait requires that the metadata is copy - // aka trivially droppable. - ptr::drop_in_place::(value); - } - } - - fn header(&self) -> *mut H { - // Safety: - // - At least `size_of::()` bytes are allocated ahead of the pointer. - // - We know that H will be aligned because the middle pointer is aligned to the greater - // of the alignment of the header and the data and the header size includes the padding - // needed to align the header. Subtracting the header size from the aligned data pointer - // will always result in an aligned header pointer, it just may not point to the - // beginning of the allocation. - let hp = unsafe { self.0.as_ptr().sub(Self::header_size()) as *mut H }; - debug_assert!(hp.is_aligned()); - hp - } - - fn value(&self) -> *mut u8 { - self.0.as_ptr() - } - - const fn header_size() -> usize { - mem::size_of::() - } - - fn alloc_layout(value_layout: Layout) -> Result<(Layout, usize), LayoutError> { - Layout::new::().extend(value_layout) - } -} - -#[unstable(feature = "thin_box", issue = "92791")] -impl Error for ThinBox { - fn source(&self) -> Option<&(dyn Error + 'static)> { - self.deref().source() - } -} diff --git a/library/alloc/src/collections/binary_heap/mod.rs b/library/alloc/src/collections/binary_heap/mod.rs deleted file mode 100644 index 846b9a1404d27..0000000000000 --- a/library/alloc/src/collections/binary_heap/mod.rs +++ /dev/null @@ -1,1886 +0,0 @@ -//! A priority queue implemented with a binary heap. -//! -//! Insertion and popping the largest element have *O*(log(*n*)) time complexity. -//! Checking the largest element is *O*(1). Converting a vector to a binary heap -//! can be done in-place, and has *O*(*n*) complexity. A binary heap can also be -//! converted to a sorted vector in-place, allowing it to be used for an *O*(*n* * log(*n*)) -//! in-place heapsort. -//! -//! # Examples -//! -//! This is a larger example that implements [Dijkstra's algorithm][dijkstra] -//! to solve the [shortest path problem][sssp] on a [directed graph][dir_graph]. -//! It shows how to use [`BinaryHeap`] with custom types. -//! -//! [dijkstra]: https://en.wikipedia.org/wiki/Dijkstra%27s_algorithm -//! [sssp]: https://en.wikipedia.org/wiki/Shortest_path_problem -//! [dir_graph]: https://en.wikipedia.org/wiki/Directed_graph -//! -//! ``` -//! use std::cmp::Ordering; -//! use std::collections::BinaryHeap; -//! -//! #[derive(Copy, Clone, Eq, PartialEq)] -//! struct State { -//! cost: usize, -//! position: usize, -//! } -//! -//! // The priority queue depends on `Ord`. -//! // Explicitly implement the trait so the queue becomes a min-heap -//! // instead of a max-heap. -//! impl Ord for State { -//! fn cmp(&self, other: &Self) -> Ordering { -//! // Notice that we flip the ordering on costs. -//! // In case of a tie we compare positions - this step is necessary -//! // to make implementations of `PartialEq` and `Ord` consistent. -//! other.cost.cmp(&self.cost) -//! .then_with(|| self.position.cmp(&other.position)) -//! } -//! } -//! -//! // `PartialOrd` needs to be implemented as well. -//! impl PartialOrd for State { -//! fn partial_cmp(&self, other: &Self) -> Option { -//! Some(self.cmp(other)) -//! } -//! } -//! -//! // Each node is represented as a `usize`, for a shorter implementation. -//! struct Edge { -//! node: usize, -//! cost: usize, -//! } -//! -//! // Dijkstra's shortest path algorithm. -//! -//! // Start at `start` and use `dist` to track the current shortest distance -//! // to each node. This implementation isn't memory-efficient as it may leave duplicate -//! // nodes in the queue. It also uses `usize::MAX` as a sentinel value, -//! // for a simpler implementation. -//! fn shortest_path(adj_list: &Vec>, start: usize, goal: usize) -> Option { -//! // dist[node] = current shortest distance from `start` to `node` -//! let mut dist: Vec<_> = (0..adj_list.len()).map(|_| usize::MAX).collect(); -//! -//! let mut heap = BinaryHeap::new(); -//! -//! // We're at `start`, with a zero cost -//! dist[start] = 0; -//! heap.push(State { cost: 0, position: start }); -//! -//! // Examine the frontier with lower cost nodes first (min-heap) -//! while let Some(State { cost, position }) = heap.pop() { -//! // Alternatively we could have continued to find all shortest paths -//! if position == goal { return Some(cost); } -//! -//! // Important as we may have already found a better way -//! if cost > dist[position] { continue; } -//! -//! // For each node we can reach, see if we can find a way with -//! // a lower cost going through this node -//! for edge in &adj_list[position] { -//! let next = State { cost: cost + edge.cost, position: edge.node }; -//! -//! // If so, add it to the frontier and continue -//! if next.cost < dist[next.position] { -//! heap.push(next); -//! // Relaxation, we have now found a better way -//! dist[next.position] = next.cost; -//! } -//! } -//! } -//! -//! // Goal not reachable -//! None -//! } -//! -//! fn main() { -//! // This is the directed graph we're going to use. -//! // The node numbers correspond to the different states, -//! // and the edge weights symbolize the cost of moving -//! // from one node to another. -//! // Note that the edges are one-way. -//! // -//! // 7 -//! // +-----------------+ -//! // | | -//! // v 1 2 | 2 -//! // 0 -----> 1 -----> 3 ---> 4 -//! // | ^ ^ ^ -//! // | | 1 | | -//! // | | | 3 | 1 -//! // +------> 2 -------+ | -//! // 10 | | -//! // +---------------+ -//! // -//! // The graph is represented as an adjacency list where each index, -//! // corresponding to a node value, has a list of outgoing edges. -//! // Chosen for its efficiency. -//! let graph = vec![ -//! // Node 0 -//! vec![Edge { node: 2, cost: 10 }, -//! Edge { node: 1, cost: 1 }], -//! // Node 1 -//! vec![Edge { node: 3, cost: 2 }], -//! // Node 2 -//! vec![Edge { node: 1, cost: 1 }, -//! Edge { node: 3, cost: 3 }, -//! Edge { node: 4, cost: 1 }], -//! // Node 3 -//! vec![Edge { node: 0, cost: 7 }, -//! Edge { node: 4, cost: 2 }], -//! // Node 4 -//! vec![]]; -//! -//! assert_eq!(shortest_path(&graph, 0, 1), Some(1)); -//! assert_eq!(shortest_path(&graph, 0, 3), Some(3)); -//! assert_eq!(shortest_path(&graph, 3, 0), Some(7)); -//! assert_eq!(shortest_path(&graph, 0, 4), Some(5)); -//! assert_eq!(shortest_path(&graph, 4, 0), None); -//! } -//! ``` - -#![allow(missing_docs)] -#![stable(feature = "rust1", since = "1.0.0")] - -use core::alloc::Allocator; -use core::fmt; -use core::iter::{FusedIterator, InPlaceIterable, SourceIter, TrustedFused, TrustedLen}; -use core::mem::{self, swap, ManuallyDrop}; -use core::num::NonZero; -use core::ops::{Deref, DerefMut}; -use core::ptr; - -use crate::alloc::Global; -use crate::collections::TryReserveError; -use crate::slice; -use crate::vec::{self, AsVecIntoIter, Vec}; - -#[cfg(test)] -mod tests; - -/// A priority queue implemented with a binary heap. -/// -/// This will be a max-heap. -/// -/// It is a logic error for an item to be modified in such a way that the -/// item's ordering relative to any other item, as determined by the [`Ord`] -/// trait, changes while it is in the heap. This is normally only possible -/// through interior mutability, global state, I/O, or unsafe code. The -/// behavior resulting from such a logic error is not specified, but will -/// be encapsulated to the `BinaryHeap` that observed the logic error and not -/// result in undefined behavior. This could include panics, incorrect results, -/// aborts, memory leaks, and non-termination. -/// -/// As long as no elements change their relative order while being in the heap -/// as described above, the API of `BinaryHeap` guarantees that the heap -/// invariant remains intact i.e. its methods all behave as documented. For -/// example if a method is documented as iterating in sorted order, that's -/// guaranteed to work as long as elements in the heap have not changed order, -/// even in the presence of closures getting unwinded out of, iterators getting -/// leaked, and similar foolishness. -/// -/// # Examples -/// -/// ``` -/// use std::collections::BinaryHeap; -/// -/// // Type inference lets us omit an explicit type signature (which -/// // would be `BinaryHeap` in this example). -/// let mut heap = BinaryHeap::new(); -/// -/// // We can use peek to look at the next item in the heap. In this case, -/// // there's no items in there yet so we get None. -/// assert_eq!(heap.peek(), None); -/// -/// // Let's add some scores... -/// heap.push(1); -/// heap.push(5); -/// heap.push(2); -/// -/// // Now peek shows the most important item in the heap. -/// assert_eq!(heap.peek(), Some(&5)); -/// -/// // We can check the length of a heap. -/// assert_eq!(heap.len(), 3); -/// -/// // We can iterate over the items in the heap, although they are returned in -/// // a random order. -/// for x in &heap { -/// println!("{x}"); -/// } -/// -/// // If we instead pop these scores, they should come back in order. -/// assert_eq!(heap.pop(), Some(5)); -/// assert_eq!(heap.pop(), Some(2)); -/// assert_eq!(heap.pop(), Some(1)); -/// assert_eq!(heap.pop(), None); -/// -/// // We can clear the heap of any remaining items. -/// heap.clear(); -/// -/// // The heap should now be empty. -/// assert!(heap.is_empty()) -/// ``` -/// -/// A `BinaryHeap` with a known list of items can be initialized from an array: -/// -/// ``` -/// use std::collections::BinaryHeap; -/// -/// let heap = BinaryHeap::from([1, 5, 2]); -/// ``` -/// -/// ## Min-heap -/// -/// Either [`core::cmp::Reverse`] or a custom [`Ord`] implementation can be used to -/// make `BinaryHeap` a min-heap. This makes `heap.pop()` return the smallest -/// value instead of the greatest one. -/// -/// ``` -/// use std::collections::BinaryHeap; -/// use std::cmp::Reverse; -/// -/// let mut heap = BinaryHeap::new(); -/// -/// // Wrap values in `Reverse` -/// heap.push(Reverse(1)); -/// heap.push(Reverse(5)); -/// heap.push(Reverse(2)); -/// -/// // If we pop these scores now, they should come back in the reverse order. -/// assert_eq!(heap.pop(), Some(Reverse(1))); -/// assert_eq!(heap.pop(), Some(Reverse(2))); -/// assert_eq!(heap.pop(), Some(Reverse(5))); -/// assert_eq!(heap.pop(), None); -/// ``` -/// -/// # Time complexity -/// -/// | [push] | [pop] | [peek]/[peek\_mut] | -/// |---------|---------------|--------------------| -/// | *O*(1)~ | *O*(log(*n*)) | *O*(1) | -/// -/// The value for `push` is an expected cost; the method documentation gives a -/// more detailed analysis. -/// -/// [`core::cmp::Reverse`]: core::cmp::Reverse -/// [`Cell`]: core::cell::Cell -/// [`RefCell`]: core::cell::RefCell -/// [push]: BinaryHeap::push -/// [pop]: BinaryHeap::pop -/// [peek]: BinaryHeap::peek -/// [peek\_mut]: BinaryHeap::peek_mut -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "BinaryHeap")] -pub struct BinaryHeap< - T, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, -> { - data: Vec, -} - -/// Structure wrapping a mutable reference to the greatest item on a -/// `BinaryHeap`. -/// -/// This `struct` is created by the [`peek_mut`] method on [`BinaryHeap`]. See -/// its documentation for more. -/// -/// [`peek_mut`]: BinaryHeap::peek_mut -#[stable(feature = "binary_heap_peek_mut", since = "1.12.0")] -pub struct PeekMut< - 'a, - T: 'a + Ord, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, -> { - heap: &'a mut BinaryHeap, - // If a set_len + sift_down are required, this is Some. If a &mut T has not - // yet been exposed to peek_mut()'s caller, it's None. - original_len: Option>, -} - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl fmt::Debug for PeekMut<'_, T, A> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("PeekMut").field(&self.heap.data[0]).finish() - } -} - -#[stable(feature = "binary_heap_peek_mut", since = "1.12.0")] -impl Drop for PeekMut<'_, T, A> { - fn drop(&mut self) { - if let Some(original_len) = self.original_len { - // SAFETY: That's how many elements were in the Vec at the time of - // the PeekMut::deref_mut call, and therefore also at the time of - // the BinaryHeap::peek_mut call. Since the PeekMut did not end up - // getting leaked, we are now undoing the leak amplification that - // the DerefMut prepared for. - unsafe { self.heap.data.set_len(original_len.get()) }; - - // SAFETY: PeekMut is only instantiated for non-empty heaps. - unsafe { self.heap.sift_down(0) }; - } - } -} - -#[stable(feature = "binary_heap_peek_mut", since = "1.12.0")] -impl Deref for PeekMut<'_, T, A> { - type Target = T; - fn deref(&self) -> &T { - debug_assert!(!self.heap.is_empty()); - // SAFE: PeekMut is only instantiated for non-empty heaps - unsafe { self.heap.data.get_unchecked(0) } - } -} - -#[stable(feature = "binary_heap_peek_mut", since = "1.12.0")] -impl DerefMut for PeekMut<'_, T, A> { - fn deref_mut(&mut self) -> &mut T { - debug_assert!(!self.heap.is_empty()); - - let len = self.heap.len(); - if len > 1 { - // Here we preemptively leak all the rest of the underlying vector - // after the currently max element. If the caller mutates the &mut T - // we're about to give them, and then leaks the PeekMut, all these - // elements will remain leaked. If they don't leak the PeekMut, then - // either Drop or PeekMut::pop will un-leak the vector elements. - // - // This is technique is described throughout several other places in - // the standard library as "leak amplification". - unsafe { - // SAFETY: len > 1 so len != 0. - self.original_len = Some(NonZero::new_unchecked(len)); - // SAFETY: len > 1 so all this does for now is leak elements, - // which is safe. - self.heap.data.set_len(1); - } - } - - // SAFE: PeekMut is only instantiated for non-empty heaps - unsafe { self.heap.data.get_unchecked_mut(0) } - } -} - -impl<'a, T: Ord, A: Allocator> PeekMut<'a, T, A> { - /// Removes the peeked value from the heap and returns it. - #[stable(feature = "binary_heap_peek_mut_pop", since = "1.18.0")] - pub fn pop(mut this: PeekMut<'a, T, A>) -> T { - if let Some(original_len) = this.original_len.take() { - // SAFETY: This is how many elements were in the Vec at the time of - // the BinaryHeap::peek_mut call. - unsafe { this.heap.data.set_len(original_len.get()) }; - - // Unlike in Drop, here we don't also need to do a sift_down even if - // the caller could've mutated the element. It is removed from the - // heap on the next line and pop() is not sensitive to its value. - } - this.heap.pop().unwrap() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for BinaryHeap { - fn clone(&self) -> Self { - BinaryHeap { data: self.data.clone() } - } - - /// Overwrites the contents of `self` with a clone of the contents of `source`. - /// - /// This method is preferred over simply assigning `source.clone()` to `self`, - /// as it avoids reallocation if possible. - /// - /// See [`Vec::clone_from()`] for more details. - fn clone_from(&mut self, source: &Self) { - self.data.clone_from(&source.data); - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Default for BinaryHeap { - /// Creates an empty `BinaryHeap`. - #[inline] - fn default() -> BinaryHeap { - BinaryHeap::new() - } -} - -#[stable(feature = "binaryheap_debug", since = "1.4.0")] -impl fmt::Debug for BinaryHeap { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.iter()).finish() - } -} - -struct RebuildOnDrop< - 'a, - T: Ord, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, -> { - heap: &'a mut BinaryHeap, - rebuild_from: usize, -} - -impl Drop for RebuildOnDrop<'_, T, A> { - fn drop(&mut self) { - self.heap.rebuild_tail(self.rebuild_from); - } -} - -impl BinaryHeap { - /// Creates an empty `BinaryHeap` as a max-heap. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::collections::BinaryHeap; - /// let mut heap = BinaryHeap::new(); - /// heap.push(4); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_binary_heap_constructor", issue = "112353")] - #[must_use] - pub const fn new() -> BinaryHeap { - BinaryHeap { data: vec![] } - } - - /// Creates an empty `BinaryHeap` with at least the specified capacity. - /// - /// The binary heap will be able to hold at least `capacity` elements without - /// reallocating. This method is allowed to allocate for more elements than - /// `capacity`. If `capacity` is 0, the binary heap will not allocate. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::collections::BinaryHeap; - /// let mut heap = BinaryHeap::with_capacity(10); - /// heap.push(4); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - pub fn with_capacity(capacity: usize) -> BinaryHeap { - BinaryHeap { data: Vec::with_capacity(capacity) } - } -} - -impl BinaryHeap { - /// Creates an empty `BinaryHeap` as a max-heap, using `A` as allocator. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(allocator_api)] - /// - /// use std::alloc::System; - /// use std::collections::BinaryHeap; - /// let mut heap = BinaryHeap::new_in(System); - /// heap.push(4); - /// ``` - #[unstable(feature = "allocator_api", issue = "32838")] - #[rustc_const_unstable(feature = "const_binary_heap_constructor", issue = "112353")] - #[must_use] - pub const fn new_in(alloc: A) -> BinaryHeap { - BinaryHeap { data: Vec::new_in(alloc) } - } - - /// Creates an empty `BinaryHeap` with at least the specified capacity, using `A` as allocator. - /// - /// The binary heap will be able to hold at least `capacity` elements without - /// reallocating. This method is allowed to allocate for more elements than - /// `capacity`. If `capacity` is 0, the binary heap will not allocate. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(allocator_api)] - /// - /// use std::alloc::System; - /// use std::collections::BinaryHeap; - /// let mut heap = BinaryHeap::with_capacity_in(10, System); - /// heap.push(4); - /// ``` - #[unstable(feature = "allocator_api", issue = "32838")] - #[must_use] - pub fn with_capacity_in(capacity: usize, alloc: A) -> BinaryHeap { - BinaryHeap { data: Vec::with_capacity_in(capacity, alloc) } - } - - /// Returns a mutable reference to the greatest item in the binary heap, or - /// `None` if it is empty. - /// - /// Note: If the `PeekMut` value is leaked, some heap elements might get - /// leaked along with it, but the remaining elements will remain a valid - /// heap. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::collections::BinaryHeap; - /// let mut heap = BinaryHeap::new(); - /// assert!(heap.peek_mut().is_none()); - /// - /// heap.push(1); - /// heap.push(5); - /// heap.push(2); - /// { - /// let mut val = heap.peek_mut().unwrap(); - /// *val = 0; - /// } - /// assert_eq!(heap.peek(), Some(&2)); - /// ``` - /// - /// # Time complexity - /// - /// If the item is modified then the worst case time complexity is *O*(log(*n*)), - /// otherwise it's *O*(1). - #[stable(feature = "binary_heap_peek_mut", since = "1.12.0")] - pub fn peek_mut(&mut self) -> Option> { - if self.is_empty() { None } else { Some(PeekMut { heap: self, original_len: None }) } - } - - /// Removes the greatest item from the binary heap and returns it, or `None` if it - /// is empty. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::collections::BinaryHeap; - /// let mut heap = BinaryHeap::from([1, 3]); - /// - /// assert_eq!(heap.pop(), Some(3)); - /// assert_eq!(heap.pop(), Some(1)); - /// assert_eq!(heap.pop(), None); - /// ``` - /// - /// # Time complexity - /// - /// The worst case cost of `pop` on a heap containing *n* elements is *O*(log(*n*)). - #[stable(feature = "rust1", since = "1.0.0")] - pub fn pop(&mut self) -> Option { - self.data.pop().map(|mut item| { - if !self.is_empty() { - swap(&mut item, &mut self.data[0]); - // SAFETY: !self.is_empty() means that self.len() > 0 - unsafe { self.sift_down_to_bottom(0) }; - } - item - }) - } - - /// Pushes an item onto the binary heap. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::collections::BinaryHeap; - /// let mut heap = BinaryHeap::new(); - /// heap.push(3); - /// heap.push(5); - /// heap.push(1); - /// - /// assert_eq!(heap.len(), 3); - /// assert_eq!(heap.peek(), Some(&5)); - /// ``` - /// - /// # Time complexity - /// - /// The expected cost of `push`, averaged over every possible ordering of - /// the elements being pushed, and over a sufficiently large number of - /// pushes, is *O*(1). This is the most meaningful cost metric when pushing - /// elements that are *not* already in any sorted pattern. - /// - /// The time complexity degrades if elements are pushed in predominantly - /// ascending order. In the worst case, elements are pushed in ascending - /// sorted order and the amortized cost per push is *O*(log(*n*)) against a heap - /// containing *n* elements. - /// - /// The worst case cost of a *single* call to `push` is *O*(*n*). The worst case - /// occurs when capacity is exhausted and needs a resize. The resize cost - /// has been amortized in the previous figures. - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("append", "put")] - pub fn push(&mut self, item: T) { - let old_len = self.len(); - self.data.push(item); - // SAFETY: Since we pushed a new item it means that - // old_len = self.len() - 1 < self.len() - unsafe { self.sift_up(0, old_len) }; - } - - /// Consumes the `BinaryHeap` and returns a vector in sorted - /// (ascending) order. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::collections::BinaryHeap; - /// - /// let mut heap = BinaryHeap::from([1, 2, 4, 5, 7]); - /// heap.push(6); - /// heap.push(3); - /// - /// let vec = heap.into_sorted_vec(); - /// assert_eq!(vec, [1, 2, 3, 4, 5, 6, 7]); - /// ``` - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "binary_heap_extras_15", since = "1.5.0")] - pub fn into_sorted_vec(mut self) -> Vec { - let mut end = self.len(); - while end > 1 { - end -= 1; - // SAFETY: `end` goes from `self.len() - 1` to 1 (both included), - // so it's always a valid index to access. - // It is safe to access index 0 (i.e. `ptr`), because - // 1 <= end < self.len(), which means self.len() >= 2. - unsafe { - let ptr = self.data.as_mut_ptr(); - ptr::swap(ptr, ptr.add(end)); - } - // SAFETY: `end` goes from `self.len() - 1` to 1 (both included) so: - // 0 < 1 <= end <= self.len() - 1 < self.len() - // Which means 0 < end and end < self.len(). - unsafe { self.sift_down_range(0, end) }; - } - self.into_vec() - } - - // The implementations of sift_up and sift_down use unsafe blocks in - // order to move an element out of the vector (leaving behind a - // hole), shift along the others and move the removed element back into the - // vector at the final location of the hole. - // The `Hole` type is used to represent this, and make sure - // the hole is filled back at the end of its scope, even on panic. - // Using a hole reduces the constant factor compared to using swaps, - // which involves twice as many moves. - - /// # Safety - /// - /// The caller must guarantee that `pos < self.len()`. - unsafe fn sift_up(&mut self, start: usize, pos: usize) -> usize { - // Take out the value at `pos` and create a hole. - // SAFETY: The caller guarantees that pos < self.len() - let mut hole = unsafe { Hole::new(&mut self.data, pos) }; - - while hole.pos() > start { - let parent = (hole.pos() - 1) / 2; - - // SAFETY: hole.pos() > start >= 0, which means hole.pos() > 0 - // and so hole.pos() - 1 can't underflow. - // This guarantees that parent < hole.pos() so - // it's a valid index and also != hole.pos(). - if hole.element() <= unsafe { hole.get(parent) } { - break; - } - - // SAFETY: Same as above - unsafe { hole.move_to(parent) }; - } - - hole.pos() - } - - /// Take an element at `pos` and move it down the heap, - /// while its children are larger. - /// - /// # Safety - /// - /// The caller must guarantee that `pos < end <= self.len()`. - unsafe fn sift_down_range(&mut self, pos: usize, end: usize) { - // SAFETY: The caller guarantees that pos < end <= self.len(). - let mut hole = unsafe { Hole::new(&mut self.data, pos) }; - let mut child = 2 * hole.pos() + 1; - - // Loop invariant: child == 2 * hole.pos() + 1. - while child <= end.saturating_sub(2) { - // compare with the greater of the two children - // SAFETY: child < end - 1 < self.len() and - // child + 1 < end <= self.len(), so they're valid indexes. - // child == 2 * hole.pos() + 1 != hole.pos() and - // child + 1 == 2 * hole.pos() + 2 != hole.pos(). - // FIXME: 2 * hole.pos() + 1 or 2 * hole.pos() + 2 could overflow - // if T is a ZST - child += unsafe { hole.get(child) <= hole.get(child + 1) } as usize; - - // if we are already in order, stop. - // SAFETY: child is now either the old child or the old child+1 - // We already proven that both are < self.len() and != hole.pos() - if hole.element() >= unsafe { hole.get(child) } { - return; - } - - // SAFETY: same as above. - unsafe { hole.move_to(child) }; - child = 2 * hole.pos() + 1; - } - - // SAFETY: && short circuit, which means that in the - // second condition it's already true that child == end - 1 < self.len(). - if child == end - 1 && hole.element() < unsafe { hole.get(child) } { - // SAFETY: child is already proven to be a valid index and - // child == 2 * hole.pos() + 1 != hole.pos(). - unsafe { hole.move_to(child) }; - } - } - - /// # Safety - /// - /// The caller must guarantee that `pos < self.len()`. - unsafe fn sift_down(&mut self, pos: usize) { - let len = self.len(); - // SAFETY: pos < len is guaranteed by the caller and - // obviously len = self.len() <= self.len(). - unsafe { self.sift_down_range(pos, len) }; - } - - /// Take an element at `pos` and move it all the way down the heap, - /// then sift it up to its position. - /// - /// Note: This is faster when the element is known to be large / should - /// be closer to the bottom. - /// - /// # Safety - /// - /// The caller must guarantee that `pos < self.len()`. - unsafe fn sift_down_to_bottom(&mut self, mut pos: usize) { - let end = self.len(); - let start = pos; - - // SAFETY: The caller guarantees that pos < self.len(). - let mut hole = unsafe { Hole::new(&mut self.data, pos) }; - let mut child = 2 * hole.pos() + 1; - - // Loop invariant: child == 2 * hole.pos() + 1. - while child <= end.saturating_sub(2) { - // SAFETY: child < end - 1 < self.len() and - // child + 1 < end <= self.len(), so they're valid indexes. - // child == 2 * hole.pos() + 1 != hole.pos() and - // child + 1 == 2 * hole.pos() + 2 != hole.pos(). - // FIXME: 2 * hole.pos() + 1 or 2 * hole.pos() + 2 could overflow - // if T is a ZST - child += unsafe { hole.get(child) <= hole.get(child + 1) } as usize; - - // SAFETY: Same as above - unsafe { hole.move_to(child) }; - child = 2 * hole.pos() + 1; - } - - if child == end - 1 { - // SAFETY: child == end - 1 < self.len(), so it's a valid index - // and child == 2 * hole.pos() + 1 != hole.pos(). - unsafe { hole.move_to(child) }; - } - pos = hole.pos(); - drop(hole); - - // SAFETY: pos is the position in the hole and was already proven - // to be a valid index. - unsafe { self.sift_up(start, pos) }; - } - - /// Rebuild assuming data[0..start] is still a proper heap. - fn rebuild_tail(&mut self, start: usize) { - if start == self.len() { - return; - } - - let tail_len = self.len() - start; - - #[inline(always)] - fn log2_fast(x: usize) -> usize { - (usize::BITS - x.leading_zeros() - 1) as usize - } - - // `rebuild` takes O(self.len()) operations - // and about 2 * self.len() comparisons in the worst case - // while repeating `sift_up` takes O(tail_len * log(start)) operations - // and about 1 * tail_len * log_2(start) comparisons in the worst case, - // assuming start >= tail_len. For larger heaps, the crossover point - // no longer follows this reasoning and was determined empirically. - let better_to_rebuild = if start < tail_len { - true - } else if self.len() <= 2048 { - 2 * self.len() < tail_len * log2_fast(start) - } else { - 2 * self.len() < tail_len * 11 - }; - - if better_to_rebuild { - self.rebuild(); - } else { - for i in start..self.len() { - // SAFETY: The index `i` is always less than self.len(). - unsafe { self.sift_up(0, i) }; - } - } - } - - fn rebuild(&mut self) { - let mut n = self.len() / 2; - while n > 0 { - n -= 1; - // SAFETY: n starts from self.len() / 2 and goes down to 0. - // The only case when !(n < self.len()) is if - // self.len() == 0, but it's ruled out by the loop condition. - unsafe { self.sift_down(n) }; - } - } - - /// Moves all the elements of `other` into `self`, leaving `other` empty. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::collections::BinaryHeap; - /// - /// let mut a = BinaryHeap::from([-10, 1, 2, 3, 3]); - /// let mut b = BinaryHeap::from([-20, 5, 43]); - /// - /// a.append(&mut b); - /// - /// assert_eq!(a.into_sorted_vec(), [-20, -10, 1, 2, 3, 3, 5, 43]); - /// assert!(b.is_empty()); - /// ``` - #[stable(feature = "binary_heap_append", since = "1.11.0")] - pub fn append(&mut self, other: &mut Self) { - if self.len() < other.len() { - swap(self, other); - } - - let start = self.data.len(); - - self.data.append(&mut other.data); - - self.rebuild_tail(start); - } - - /// Clears the binary heap, returning an iterator over the removed elements - /// in heap order. If the iterator is dropped before being fully consumed, - /// it drops the remaining elements in heap order. - /// - /// The returned iterator keeps a mutable borrow on the heap to optimize - /// its implementation. - /// - /// Note: - /// * `.drain_sorted()` is *O*(*n* \* log(*n*)); much slower than `.drain()`. - /// You should use the latter for most cases. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(binary_heap_drain_sorted)] - /// use std::collections::BinaryHeap; - /// - /// let mut heap = BinaryHeap::from([1, 2, 3, 4, 5]); - /// assert_eq!(heap.len(), 5); - /// - /// drop(heap.drain_sorted()); // removes all elements in heap order - /// assert_eq!(heap.len(), 0); - /// ``` - #[inline] - #[unstable(feature = "binary_heap_drain_sorted", issue = "59278")] - pub fn drain_sorted(&mut self) -> DrainSorted<'_, T, A> { - DrainSorted { inner: self } - } - - /// Retains only the elements specified by the predicate. - /// - /// In other words, remove all elements `e` for which `f(&e)` returns - /// `false`. The elements are visited in unsorted (and unspecified) order. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::collections::BinaryHeap; - /// - /// let mut heap = BinaryHeap::from([-10, -5, 1, 2, 4, 13]); - /// - /// heap.retain(|x| x % 2 == 0); // only keep even numbers - /// - /// assert_eq!(heap.into_sorted_vec(), [-10, 2, 4]) - /// ``` - #[stable(feature = "binary_heap_retain", since = "1.70.0")] - pub fn retain(&mut self, mut f: F) - where - F: FnMut(&T) -> bool, - { - // rebuild_start will be updated to the first touched element below, and the rebuild will - // only be done for the tail. - let mut guard = RebuildOnDrop { rebuild_from: self.len(), heap: self }; - let mut i = 0; - - guard.heap.data.retain(|e| { - let keep = f(e); - if !keep && i < guard.rebuild_from { - guard.rebuild_from = i; - } - i += 1; - keep - }); - } -} - -impl BinaryHeap { - /// Returns an iterator visiting all values in the underlying vector, in - /// arbitrary order. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::collections::BinaryHeap; - /// let heap = BinaryHeap::from([1, 2, 3, 4]); - /// - /// // Print 1, 2, 3, 4 in arbitrary order - /// for x in heap.iter() { - /// println!("{x}"); - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn iter(&self) -> Iter<'_, T> { - Iter { iter: self.data.iter() } - } - - /// Returns an iterator which retrieves elements in heap order. - /// This method consumes the original heap. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(binary_heap_into_iter_sorted)] - /// use std::collections::BinaryHeap; - /// let heap = BinaryHeap::from([1, 2, 3, 4, 5]); - /// - /// assert_eq!(heap.into_iter_sorted().take(2).collect::>(), [5, 4]); - /// ``` - #[unstable(feature = "binary_heap_into_iter_sorted", issue = "59278")] - pub fn into_iter_sorted(self) -> IntoIterSorted { - IntoIterSorted { inner: self } - } - - /// Returns the greatest item in the binary heap, or `None` if it is empty. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::collections::BinaryHeap; - /// let mut heap = BinaryHeap::new(); - /// assert_eq!(heap.peek(), None); - /// - /// heap.push(1); - /// heap.push(5); - /// heap.push(2); - /// assert_eq!(heap.peek(), Some(&5)); - /// - /// ``` - /// - /// # Time complexity - /// - /// Cost is *O*(1) in the worst case. - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn peek(&self) -> Option<&T> { - self.data.get(0) - } - - /// Returns the number of elements the binary heap can hold without reallocating. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::collections::BinaryHeap; - /// let mut heap = BinaryHeap::with_capacity(100); - /// assert!(heap.capacity() >= 100); - /// heap.push(4); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn capacity(&self) -> usize { - self.data.capacity() - } - - /// Reserves the minimum capacity for at least `additional` elements more than - /// the current length. Unlike [`reserve`], this will not - /// deliberately over-allocate to speculatively avoid frequent allocations. - /// After calling `reserve_exact`, capacity will be greater than or equal to - /// `self.len() + additional`. Does nothing if the capacity is already - /// sufficient. - /// - /// [`reserve`]: BinaryHeap::reserve - /// - /// # Panics - /// - /// Panics if the new capacity overflows [`usize`]. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::collections::BinaryHeap; - /// let mut heap = BinaryHeap::new(); - /// heap.reserve_exact(100); - /// assert!(heap.capacity() >= 100); - /// heap.push(4); - /// ``` - /// - /// [`reserve`]: BinaryHeap::reserve - #[stable(feature = "rust1", since = "1.0.0")] - pub fn reserve_exact(&mut self, additional: usize) { - self.data.reserve_exact(additional); - } - - /// Reserves capacity for at least `additional` elements more than the - /// current length. The allocator may reserve more space to speculatively - /// avoid frequent allocations. After calling `reserve`, - /// capacity will be greater than or equal to `self.len() + additional`. - /// Does nothing if capacity is already sufficient. - /// - /// # Panics - /// - /// Panics if the new capacity overflows [`usize`]. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::collections::BinaryHeap; - /// let mut heap = BinaryHeap::new(); - /// heap.reserve(100); - /// assert!(heap.capacity() >= 100); - /// heap.push(4); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn reserve(&mut self, additional: usize) { - self.data.reserve(additional); - } - - /// Tries to reserve the minimum capacity for at least `additional` elements - /// more than the current length. Unlike [`try_reserve`], this will not - /// deliberately over-allocate to speculatively avoid frequent allocations. - /// After calling `try_reserve_exact`, capacity will be greater than or - /// equal to `self.len() + additional` if it returns `Ok(())`. - /// Does nothing if the capacity is already sufficient. - /// - /// Note that the allocator may give the collection more space than it - /// requests. Therefore, capacity can not be relied upon to be precisely - /// minimal. Prefer [`try_reserve`] if future insertions are expected. - /// - /// [`try_reserve`]: BinaryHeap::try_reserve - /// - /// # Errors - /// - /// If the capacity overflows, or the allocator reports a failure, then an error - /// is returned. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BinaryHeap; - /// use std::collections::TryReserveError; - /// - /// fn find_max_slow(data: &[u32]) -> Result, TryReserveError> { - /// let mut heap = BinaryHeap::new(); - /// - /// // Pre-reserve the memory, exiting if we can't - /// heap.try_reserve_exact(data.len())?; - /// - /// // Now we know this can't OOM in the middle of our complex work - /// heap.extend(data.iter()); - /// - /// Ok(heap.pop()) - /// } - /// # find_max_slow(&[1, 2, 3]).expect("why is the test harness OOMing on 12 bytes?"); - /// ``` - #[stable(feature = "try_reserve_2", since = "1.63.0")] - pub fn try_reserve_exact(&mut self, additional: usize) -> Result<(), TryReserveError> { - self.data.try_reserve_exact(additional) - } - - /// Tries to reserve capacity for at least `additional` elements more than the - /// current length. The allocator may reserve more space to speculatively - /// avoid frequent allocations. After calling `try_reserve`, capacity will be - /// greater than or equal to `self.len() + additional` if it returns - /// `Ok(())`. Does nothing if capacity is already sufficient. This method - /// preserves the contents even if an error occurs. - /// - /// # Errors - /// - /// If the capacity overflows, or the allocator reports a failure, then an error - /// is returned. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BinaryHeap; - /// use std::collections::TryReserveError; - /// - /// fn find_max_slow(data: &[u32]) -> Result, TryReserveError> { - /// let mut heap = BinaryHeap::new(); - /// - /// // Pre-reserve the memory, exiting if we can't - /// heap.try_reserve(data.len())?; - /// - /// // Now we know this can't OOM in the middle of our complex work - /// heap.extend(data.iter()); - /// - /// Ok(heap.pop()) - /// } - /// # find_max_slow(&[1, 2, 3]).expect("why is the test harness OOMing on 12 bytes?"); - /// ``` - #[stable(feature = "try_reserve_2", since = "1.63.0")] - pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> { - self.data.try_reserve(additional) - } - - /// Discards as much additional capacity as possible. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::collections::BinaryHeap; - /// let mut heap: BinaryHeap = BinaryHeap::with_capacity(100); - /// - /// assert!(heap.capacity() >= 100); - /// heap.shrink_to_fit(); - /// assert!(heap.capacity() == 0); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn shrink_to_fit(&mut self) { - self.data.shrink_to_fit(); - } - - /// Discards capacity with a lower bound. - /// - /// The capacity will remain at least as large as both the length - /// and the supplied value. - /// - /// If the current capacity is less than the lower limit, this is a no-op. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BinaryHeap; - /// let mut heap: BinaryHeap = BinaryHeap::with_capacity(100); - /// - /// assert!(heap.capacity() >= 100); - /// heap.shrink_to(10); - /// assert!(heap.capacity() >= 10); - /// ``` - #[inline] - #[stable(feature = "shrink_to", since = "1.56.0")] - pub fn shrink_to(&mut self, min_capacity: usize) { - self.data.shrink_to(min_capacity) - } - - /// Returns a slice of all values in the underlying vector, in arbitrary - /// order. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(binary_heap_as_slice)] - /// use std::collections::BinaryHeap; - /// use std::io::{self, Write}; - /// - /// let heap = BinaryHeap::from([1, 2, 3, 4, 5, 6, 7]); - /// - /// io::sink().write(heap.as_slice()).unwrap(); - /// ``` - #[must_use] - #[unstable(feature = "binary_heap_as_slice", issue = "83659")] - pub fn as_slice(&self) -> &[T] { - self.data.as_slice() - } - - /// Consumes the `BinaryHeap` and returns the underlying vector - /// in arbitrary order. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::collections::BinaryHeap; - /// let heap = BinaryHeap::from([1, 2, 3, 4, 5, 6, 7]); - /// let vec = heap.into_vec(); - /// - /// // Will print in some order - /// for x in vec { - /// println!("{x}"); - /// } - /// ``` - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "binary_heap_extras_15", since = "1.5.0")] - pub fn into_vec(self) -> Vec { - self.into() - } - - /// Returns a reference to the underlying allocator. - #[unstable(feature = "allocator_api", issue = "32838")] - #[inline] - pub fn allocator(&self) -> &A { - self.data.allocator() - } - - /// Returns the length of the binary heap. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::collections::BinaryHeap; - /// let heap = BinaryHeap::from([1, 3]); - /// - /// assert_eq!(heap.len(), 2); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("length", "size")] - pub fn len(&self) -> usize { - self.data.len() - } - - /// Checks if the binary heap is empty. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::collections::BinaryHeap; - /// let mut heap = BinaryHeap::new(); - /// - /// assert!(heap.is_empty()); - /// - /// heap.push(3); - /// heap.push(5); - /// heap.push(1); - /// - /// assert!(!heap.is_empty()); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn is_empty(&self) -> bool { - self.len() == 0 - } - - /// Clears the binary heap, returning an iterator over the removed elements - /// in arbitrary order. If the iterator is dropped before being fully - /// consumed, it drops the remaining elements in arbitrary order. - /// - /// The returned iterator keeps a mutable borrow on the heap to optimize - /// its implementation. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::collections::BinaryHeap; - /// let mut heap = BinaryHeap::from([1, 3]); - /// - /// assert!(!heap.is_empty()); - /// - /// for x in heap.drain() { - /// println!("{x}"); - /// } - /// - /// assert!(heap.is_empty()); - /// ``` - #[inline] - #[stable(feature = "drain", since = "1.6.0")] - pub fn drain(&mut self) -> Drain<'_, T, A> { - Drain { iter: self.data.drain(..) } - } - - /// Drops all items from the binary heap. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::collections::BinaryHeap; - /// let mut heap = BinaryHeap::from([1, 3]); - /// - /// assert!(!heap.is_empty()); - /// - /// heap.clear(); - /// - /// assert!(heap.is_empty()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn clear(&mut self) { - self.drain(); - } -} - -/// Hole represents a hole in a slice i.e., an index without valid value -/// (because it was moved from or duplicated). -/// In drop, `Hole` will restore the slice by filling the hole -/// position with the value that was originally removed. -struct Hole<'a, T: 'a> { - data: &'a mut [T], - elt: ManuallyDrop, - pos: usize, -} - -impl<'a, T> Hole<'a, T> { - /// Create a new `Hole` at index `pos`. - /// - /// Unsafe because pos must be within the data slice. - #[inline] - unsafe fn new(data: &'a mut [T], pos: usize) -> Self { - debug_assert!(pos < data.len()); - // SAFE: pos should be inside the slice - let elt = unsafe { ptr::read(data.get_unchecked(pos)) }; - Hole { data, elt: ManuallyDrop::new(elt), pos } - } - - #[inline] - fn pos(&self) -> usize { - self.pos - } - - /// Returns a reference to the element removed. - #[inline] - fn element(&self) -> &T { - &self.elt - } - - /// Returns a reference to the element at `index`. - /// - /// Unsafe because index must be within the data slice and not equal to pos. - #[inline] - unsafe fn get(&self, index: usize) -> &T { - debug_assert!(index != self.pos); - debug_assert!(index < self.data.len()); - unsafe { self.data.get_unchecked(index) } - } - - /// Move hole to new location - /// - /// Unsafe because index must be within the data slice and not equal to pos. - #[inline] - unsafe fn move_to(&mut self, index: usize) { - debug_assert!(index != self.pos); - debug_assert!(index < self.data.len()); - unsafe { - let ptr = self.data.as_mut_ptr(); - let index_ptr: *const _ = ptr.add(index); - let hole_ptr = ptr.add(self.pos); - ptr::copy_nonoverlapping(index_ptr, hole_ptr, 1); - } - self.pos = index; - } -} - -impl Drop for Hole<'_, T> { - #[inline] - fn drop(&mut self) { - // fill the hole again - unsafe { - let pos = self.pos; - ptr::copy_nonoverlapping(&*self.elt, self.data.get_unchecked_mut(pos), 1); - } - } -} - -/// An iterator over the elements of a `BinaryHeap`. -/// -/// This `struct` is created by [`BinaryHeap::iter()`]. See its -/// documentation for more. -/// -/// [`iter`]: BinaryHeap::iter -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Iter<'a, T: 'a> { - iter: slice::Iter<'a, T>, -} - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl fmt::Debug for Iter<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("Iter").field(&self.iter.as_slice()).finish() - } -} - -// FIXME(#26925) Remove in favor of `#[derive(Clone)]` -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Iter<'_, T> { - fn clone(&self) -> Self { - Iter { iter: self.iter.clone() } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> Iterator for Iter<'a, T> { - type Item = &'a T; - - #[inline] - fn next(&mut self) -> Option<&'a T> { - self.iter.next() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } - - #[inline] - fn last(self) -> Option<&'a T> { - self.iter.last() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> DoubleEndedIterator for Iter<'a, T> { - #[inline] - fn next_back(&mut self) -> Option<&'a T> { - self.iter.next_back() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Iter<'_, T> { - fn is_empty(&self) -> bool { - self.iter.is_empty() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Iter<'_, T> {} - -/// An owning iterator over the elements of a `BinaryHeap`. -/// -/// This `struct` is created by [`BinaryHeap::into_iter()`] -/// (provided by the [`IntoIterator`] trait). See its documentation for more. -/// -/// [`into_iter`]: BinaryHeap::into_iter -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Clone)] -pub struct IntoIter< - T, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, -> { - iter: vec::IntoIter, -} - -impl IntoIter { - /// Returns a reference to the underlying allocator. - #[unstable(feature = "allocator_api", issue = "32838")] - pub fn allocator(&self) -> &A { - self.iter.allocator() - } -} - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl fmt::Debug for IntoIter { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("IntoIter").field(&self.iter.as_slice()).finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for IntoIter { - type Item = T; - - #[inline] - fn next(&mut self) -> Option { - self.iter.next() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DoubleEndedIterator for IntoIter { - #[inline] - fn next_back(&mut self) -> Option { - self.iter.next_back() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for IntoIter { - fn is_empty(&self) -> bool { - self.iter.is_empty() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for IntoIter {} - -#[doc(hidden)] -#[unstable(issue = "none", feature = "trusted_fused")] -unsafe impl TrustedFused for IntoIter {} - -#[stable(feature = "default_iters", since = "1.70.0")] -impl Default for IntoIter { - /// Creates an empty `binary_heap::IntoIter`. - /// - /// ``` - /// # use std::collections::binary_heap; - /// let iter: binary_heap::IntoIter = Default::default(); - /// assert_eq!(iter.len(), 0); - /// ``` - fn default() -> Self { - IntoIter { iter: Default::default() } - } -} - -// In addition to the SAFETY invariants of the following three unsafe traits -// also refer to the vec::in_place_collect module documentation to get an overview -#[unstable(issue = "none", feature = "inplace_iteration")] -#[doc(hidden)] -unsafe impl SourceIter for IntoIter { - type Source = IntoIter; - - #[inline] - unsafe fn as_inner(&mut self) -> &mut Self::Source { - self - } -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -#[doc(hidden)] -unsafe impl InPlaceIterable for IntoIter { - const EXPAND_BY: Option> = NonZero::new(1); - const MERGE_BY: Option> = NonZero::new(1); -} - -unsafe impl AsVecIntoIter for IntoIter { - type Item = I; - - fn as_into_iter(&mut self) -> &mut vec::IntoIter { - &mut self.iter - } -} - -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[unstable(feature = "binary_heap_into_iter_sorted", issue = "59278")] -#[derive(Clone, Debug)] -pub struct IntoIterSorted< - T, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, -> { - inner: BinaryHeap, -} - -impl IntoIterSorted { - /// Returns a reference to the underlying allocator. - #[unstable(feature = "allocator_api", issue = "32838")] - pub fn allocator(&self) -> &A { - self.inner.allocator() - } -} - -#[unstable(feature = "binary_heap_into_iter_sorted", issue = "59278")] -impl Iterator for IntoIterSorted { - type Item = T; - - #[inline] - fn next(&mut self) -> Option { - self.inner.pop() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let exact = self.inner.len(); - (exact, Some(exact)) - } -} - -#[unstable(feature = "binary_heap_into_iter_sorted", issue = "59278")] -impl ExactSizeIterator for IntoIterSorted {} - -#[unstable(feature = "binary_heap_into_iter_sorted", issue = "59278")] -impl FusedIterator for IntoIterSorted {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for IntoIterSorted {} - -/// A draining iterator over the elements of a `BinaryHeap`. -/// -/// This `struct` is created by [`BinaryHeap::drain()`]. See its -/// documentation for more. -/// -/// [`drain`]: BinaryHeap::drain -#[stable(feature = "drain", since = "1.6.0")] -#[derive(Debug)] -pub struct Drain< - 'a, - T: 'a, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, -> { - iter: vec::Drain<'a, T, A>, -} - -impl Drain<'_, T, A> { - /// Returns a reference to the underlying allocator. - #[unstable(feature = "allocator_api", issue = "32838")] - pub fn allocator(&self) -> &A { - self.iter.allocator() - } -} - -#[stable(feature = "drain", since = "1.6.0")] -impl Iterator for Drain<'_, T, A> { - type Item = T; - - #[inline] - fn next(&mut self) -> Option { - self.iter.next() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } -} - -#[stable(feature = "drain", since = "1.6.0")] -impl DoubleEndedIterator for Drain<'_, T, A> { - #[inline] - fn next_back(&mut self) -> Option { - self.iter.next_back() - } -} - -#[stable(feature = "drain", since = "1.6.0")] -impl ExactSizeIterator for Drain<'_, T, A> { - fn is_empty(&self) -> bool { - self.iter.is_empty() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Drain<'_, T, A> {} - -/// A draining iterator over the elements of a `BinaryHeap`. -/// -/// This `struct` is created by [`BinaryHeap::drain_sorted()`]. See its -/// documentation for more. -/// -/// [`drain_sorted`]: BinaryHeap::drain_sorted -#[unstable(feature = "binary_heap_drain_sorted", issue = "59278")] -#[derive(Debug)] -pub struct DrainSorted< - 'a, - T: Ord, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, -> { - inner: &'a mut BinaryHeap, -} - -impl<'a, T: Ord, A: Allocator> DrainSorted<'a, T, A> { - /// Returns a reference to the underlying allocator. - #[unstable(feature = "allocator_api", issue = "32838")] - pub fn allocator(&self) -> &A { - self.inner.allocator() - } -} - -#[unstable(feature = "binary_heap_drain_sorted", issue = "59278")] -impl<'a, T: Ord, A: Allocator> Drop for DrainSorted<'a, T, A> { - /// Removes heap elements in heap order. - fn drop(&mut self) { - struct DropGuard<'r, 'a, T: Ord, A: Allocator>(&'r mut DrainSorted<'a, T, A>); - - impl<'r, 'a, T: Ord, A: Allocator> Drop for DropGuard<'r, 'a, T, A> { - fn drop(&mut self) { - while self.0.inner.pop().is_some() {} - } - } - - while let Some(item) = self.inner.pop() { - let guard = DropGuard(self); - drop(item); - mem::forget(guard); - } - } -} - -#[unstable(feature = "binary_heap_drain_sorted", issue = "59278")] -impl Iterator for DrainSorted<'_, T, A> { - type Item = T; - - #[inline] - fn next(&mut self) -> Option { - self.inner.pop() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let exact = self.inner.len(); - (exact, Some(exact)) - } -} - -#[unstable(feature = "binary_heap_drain_sorted", issue = "59278")] -impl ExactSizeIterator for DrainSorted<'_, T, A> {} - -#[unstable(feature = "binary_heap_drain_sorted", issue = "59278")] -impl FusedIterator for DrainSorted<'_, T, A> {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for DrainSorted<'_, T, A> {} - -#[stable(feature = "binary_heap_extras_15", since = "1.5.0")] -impl From> for BinaryHeap { - /// Converts a `Vec` into a `BinaryHeap`. - /// - /// This conversion happens in-place, and has *O*(*n*) time complexity. - fn from(vec: Vec) -> BinaryHeap { - let mut heap = BinaryHeap { data: vec }; - heap.rebuild(); - heap - } -} - -#[stable(feature = "std_collections_from_array", since = "1.56.0")] -impl From<[T; N]> for BinaryHeap { - /// ``` - /// use std::collections::BinaryHeap; - /// - /// let mut h1 = BinaryHeap::from([1, 4, 2, 3]); - /// let mut h2: BinaryHeap<_> = [1, 4, 2, 3].into(); - /// while let Some((a, b)) = h1.pop().zip(h2.pop()) { - /// assert_eq!(a, b); - /// } - /// ``` - fn from(arr: [T; N]) -> Self { - Self::from_iter(arr) - } -} - -#[stable(feature = "binary_heap_extras_15", since = "1.5.0")] -impl From> for Vec { - /// Converts a `BinaryHeap` into a `Vec`. - /// - /// This conversion requires no data movement or allocation, and has - /// constant time complexity. - fn from(heap: BinaryHeap) -> Vec { - heap.data - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl FromIterator for BinaryHeap { - fn from_iter>(iter: I) -> BinaryHeap { - BinaryHeap::from(iter.into_iter().collect::>()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl IntoIterator for BinaryHeap { - type Item = T; - type IntoIter = IntoIter; - - /// Creates a consuming iterator, that is, one that moves each value out of - /// the binary heap in arbitrary order. The binary heap cannot be used - /// after calling this. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::collections::BinaryHeap; - /// let heap = BinaryHeap::from([1, 2, 3, 4]); - /// - /// // Print 1, 2, 3, 4 in arbitrary order - /// for x in heap.into_iter() { - /// // x has type i32, not &i32 - /// println!("{x}"); - /// } - /// ``` - fn into_iter(self) -> IntoIter { - IntoIter { iter: self.data.into_iter() } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T, A: Allocator> IntoIterator for &'a BinaryHeap { - type Item = &'a T; - type IntoIter = Iter<'a, T>; - - fn into_iter(self) -> Iter<'a, T> { - self.iter() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Extend for BinaryHeap { - #[inline] - fn extend>(&mut self, iter: I) { - let guard = RebuildOnDrop { rebuild_from: self.len(), heap: self }; - guard.heap.data.extend(iter); - } - - #[inline] - fn extend_one(&mut self, item: T) { - self.push(item); - } - - #[inline] - fn extend_reserve(&mut self, additional: usize) { - self.reserve(additional); - } -} - -#[stable(feature = "extend_ref", since = "1.2.0")] -impl<'a, T: 'a + Ord + Copy, A: Allocator> Extend<&'a T> for BinaryHeap { - fn extend>(&mut self, iter: I) { - self.extend(iter.into_iter().cloned()); - } - - #[inline] - fn extend_one(&mut self, &item: &'a T) { - self.push(item); - } - - #[inline] - fn extend_reserve(&mut self, additional: usize) { - self.reserve(additional); - } -} diff --git a/library/alloc/src/collections/binary_heap/tests.rs b/library/alloc/src/collections/binary_heap/tests.rs deleted file mode 100644 index d4bc6226a14a8..0000000000000 --- a/library/alloc/src/collections/binary_heap/tests.rs +++ /dev/null @@ -1,578 +0,0 @@ -use super::*; -use crate::boxed::Box; -use crate::testing::crash_test::{CrashTestDummy, Panic}; -use std::panic::{catch_unwind, AssertUnwindSafe}; - -#[test] -fn test_iterator() { - let data = vec![5, 9, 3]; - let iterout = [9, 5, 3]; - let heap = BinaryHeap::from(data); - let mut i = 0; - for el in &heap { - assert_eq!(*el, iterout[i]); - i += 1; - } -} - -#[test] -fn test_iter_rev_cloned_collect() { - let data = vec![5, 9, 3]; - let iterout = vec![3, 5, 9]; - let pq = BinaryHeap::from(data); - - let v: Vec<_> = pq.iter().rev().cloned().collect(); - assert_eq!(v, iterout); -} - -#[test] -fn test_into_iter_collect() { - let data = vec![5, 9, 3]; - let iterout = vec![9, 5, 3]; - let pq = BinaryHeap::from(data); - - let v: Vec<_> = pq.into_iter().collect(); - assert_eq!(v, iterout); -} - -#[test] -fn test_into_iter_size_hint() { - let data = vec![5, 9]; - let pq = BinaryHeap::from(data); - - let mut it = pq.into_iter(); - - assert_eq!(it.size_hint(), (2, Some(2))); - assert_eq!(it.next(), Some(9)); - - assert_eq!(it.size_hint(), (1, Some(1))); - assert_eq!(it.next(), Some(5)); - - assert_eq!(it.size_hint(), (0, Some(0))); - assert_eq!(it.next(), None); -} - -#[test] -fn test_into_iter_rev_collect() { - let data = vec![5, 9, 3]; - let iterout = vec![3, 5, 9]; - let pq = BinaryHeap::from(data); - - let v: Vec<_> = pq.into_iter().rev().collect(); - assert_eq!(v, iterout); -} - -#[test] -fn test_into_iter_sorted_collect() { - let heap = BinaryHeap::from(vec![2, 4, 6, 2, 1, 8, 10, 3, 5, 7, 0, 9, 1]); - let it = heap.into_iter_sorted(); - let sorted = it.collect::>(); - assert_eq!(sorted, vec![10, 9, 8, 7, 6, 5, 4, 3, 2, 2, 1, 1, 0]); -} - -#[test] -fn test_drain_sorted_collect() { - let mut heap = BinaryHeap::from(vec![2, 4, 6, 2, 1, 8, 10, 3, 5, 7, 0, 9, 1]); - let it = heap.drain_sorted(); - let sorted = it.collect::>(); - assert_eq!(sorted, vec![10, 9, 8, 7, 6, 5, 4, 3, 2, 2, 1, 1, 0]); -} - -fn check_exact_size_iterator(len: usize, it: I) { - let mut it = it; - - for i in 0..it.len() { - let (lower, upper) = it.size_hint(); - assert_eq!(Some(lower), upper); - assert_eq!(lower, len - i); - assert_eq!(it.len(), len - i); - it.next(); - } - assert_eq!(it.len(), 0); - assert!(it.is_empty()); -} - -#[test] -fn test_exact_size_iterator() { - let heap = BinaryHeap::from(vec![2, 4, 6, 2, 1, 8, 10, 3, 5, 7, 0, 9, 1]); - check_exact_size_iterator(heap.len(), heap.iter()); - check_exact_size_iterator(heap.len(), heap.clone().into_iter()); - check_exact_size_iterator(heap.len(), heap.clone().into_iter_sorted()); - check_exact_size_iterator(heap.len(), heap.clone().drain()); - check_exact_size_iterator(heap.len(), heap.clone().drain_sorted()); -} - -fn check_trusted_len(len: usize, it: I) { - let mut it = it; - for i in 0..len { - let (lower, upper) = it.size_hint(); - if upper.is_some() { - assert_eq!(Some(lower), upper); - assert_eq!(lower, len - i); - } - it.next(); - } -} - -#[test] -fn test_trusted_len() { - let heap = BinaryHeap::from(vec![2, 4, 6, 2, 1, 8, 10, 3, 5, 7, 0, 9, 1]); - check_trusted_len(heap.len(), heap.clone().into_iter_sorted()); - check_trusted_len(heap.len(), heap.clone().drain_sorted()); -} - -#[test] -fn test_peek_and_pop() { - let data = vec![2, 4, 6, 2, 1, 8, 10, 3, 5, 7, 0, 9, 1]; - let mut sorted = data.clone(); - sorted.sort(); - let mut heap = BinaryHeap::from(data); - while !heap.is_empty() { - assert_eq!(heap.peek().unwrap(), sorted.last().unwrap()); - assert_eq!(heap.pop().unwrap(), sorted.pop().unwrap()); - } -} - -#[test] -fn test_peek_mut() { - let data = vec![2, 4, 6, 2, 1, 8, 10, 3, 5, 7, 0, 9, 1]; - let mut heap = BinaryHeap::from(data); - assert_eq!(heap.peek(), Some(&10)); - { - let mut top = heap.peek_mut().unwrap(); - *top -= 2; - } - assert_eq!(heap.peek(), Some(&9)); -} - -#[test] -fn test_peek_mut_leek() { - let data = vec![4, 2, 7]; - let mut heap = BinaryHeap::from(data); - let mut max = heap.peek_mut().unwrap(); - *max = -1; - - // The PeekMut object's Drop impl would have been responsible for moving the - // -1 out of the max position of the BinaryHeap, but we don't run it. - mem::forget(max); - - // Absent some mitigation like leak amplification, the -1 would incorrectly - // end up in the last position of the returned Vec, with the rest of the - // heap's original contents in front of it in sorted order. - let sorted_vec = heap.into_sorted_vec(); - assert!(sorted_vec.is_sorted(), "{:?}", sorted_vec); -} - -#[test] -fn test_peek_mut_pop() { - let data = vec![2, 4, 6, 2, 1, 8, 10, 3, 5, 7, 0, 9, 1]; - let mut heap = BinaryHeap::from(data); - assert_eq!(heap.peek(), Some(&10)); - { - let mut top = heap.peek_mut().unwrap(); - *top -= 2; - assert_eq!(PeekMut::pop(top), 8); - } - assert_eq!(heap.peek(), Some(&9)); -} - -#[test] -fn test_push() { - let mut heap = BinaryHeap::from(vec![2, 4, 9]); - assert_eq!(heap.len(), 3); - assert!(*heap.peek().unwrap() == 9); - heap.push(11); - assert_eq!(heap.len(), 4); - assert!(*heap.peek().unwrap() == 11); - heap.push(5); - assert_eq!(heap.len(), 5); - assert!(*heap.peek().unwrap() == 11); - heap.push(27); - assert_eq!(heap.len(), 6); - assert!(*heap.peek().unwrap() == 27); - heap.push(3); - assert_eq!(heap.len(), 7); - assert!(*heap.peek().unwrap() == 27); - heap.push(103); - assert_eq!(heap.len(), 8); - assert!(*heap.peek().unwrap() == 103); -} - -#[test] -fn test_push_unique() { - let mut heap = BinaryHeap::>::from(vec![Box::new(2), Box::new(4), Box::new(9)]); - assert_eq!(heap.len(), 3); - assert!(**heap.peek().unwrap() == 9); - heap.push(Box::new(11)); - assert_eq!(heap.len(), 4); - assert!(**heap.peek().unwrap() == 11); - heap.push(Box::new(5)); - assert_eq!(heap.len(), 5); - assert!(**heap.peek().unwrap() == 11); - heap.push(Box::new(27)); - assert_eq!(heap.len(), 6); - assert!(**heap.peek().unwrap() == 27); - heap.push(Box::new(3)); - assert_eq!(heap.len(), 7); - assert!(**heap.peek().unwrap() == 27); - heap.push(Box::new(103)); - assert_eq!(heap.len(), 8); - assert!(**heap.peek().unwrap() == 103); -} - -fn check_to_vec(mut data: Vec) { - let heap = BinaryHeap::from(data.clone()); - let mut v = heap.clone().into_vec(); - v.sort(); - data.sort(); - - assert_eq!(v, data); - assert_eq!(heap.into_sorted_vec(), data); -} - -#[test] -fn test_to_vec() { - check_to_vec(vec![]); - check_to_vec(vec![5]); - check_to_vec(vec![3, 2]); - check_to_vec(vec![2, 3]); - check_to_vec(vec![5, 1, 2]); - check_to_vec(vec![1, 100, 2, 3]); - check_to_vec(vec![1, 3, 5, 7, 9, 2, 4, 6, 8, 0]); - check_to_vec(vec![2, 4, 6, 2, 1, 8, 10, 3, 5, 7, 0, 9, 1]); - check_to_vec(vec![9, 11, 9, 9, 9, 9, 11, 2, 3, 4, 11, 9, 0, 0, 0, 0]); - check_to_vec(vec![0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); - check_to_vec(vec![10, 9, 8, 7, 6, 5, 4, 3, 2, 1, 0]); - check_to_vec(vec![0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, 0, 0, 1, 2]); - check_to_vec(vec![5, 4, 3, 2, 1, 5, 4, 3, 2, 1, 5, 4, 3, 2, 1]); -} - -#[test] -fn test_in_place_iterator_specialization() { - let src: Vec = vec![1, 2, 3]; - let src_ptr = src.as_ptr(); - let heap: BinaryHeap<_> = src.into_iter().map(std::convert::identity).collect(); - let heap_ptr = heap.iter().next().unwrap() as *const usize; - assert_eq!(src_ptr, heap_ptr); - let sink: Vec<_> = heap.into_iter().map(std::convert::identity).collect(); - let sink_ptr = sink.as_ptr(); - assert_eq!(heap_ptr, sink_ptr); -} - -#[test] -fn test_empty_pop() { - let mut heap = BinaryHeap::::new(); - assert!(heap.pop().is_none()); -} - -#[test] -fn test_empty_peek() { - let empty = BinaryHeap::::new(); - assert!(empty.peek().is_none()); -} - -#[test] -fn test_empty_peek_mut() { - let mut empty = BinaryHeap::::new(); - assert!(empty.peek_mut().is_none()); -} - -#[test] -fn test_from_iter() { - let xs = vec![9, 8, 7, 6, 5, 4, 3, 2, 1]; - - let mut q: BinaryHeap<_> = xs.iter().rev().cloned().collect(); - - for &x in &xs { - assert_eq!(q.pop().unwrap(), x); - } -} - -#[test] -fn test_drain() { - let mut q: BinaryHeap<_> = [9, 8, 7, 6, 5, 4, 3, 2, 1].iter().cloned().collect(); - - assert_eq!(q.drain().take(5).count(), 5); - - assert!(q.is_empty()); -} - -#[test] -fn test_drain_sorted() { - let mut q: BinaryHeap<_> = [9, 8, 7, 6, 5, 4, 3, 2, 1].iter().cloned().collect(); - - assert_eq!(q.drain_sorted().take(5).collect::>(), vec![9, 8, 7, 6, 5]); - - assert!(q.is_empty()); -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_drain_sorted_leak() { - let d0 = CrashTestDummy::new(0); - let d1 = CrashTestDummy::new(1); - let d2 = CrashTestDummy::new(2); - let d3 = CrashTestDummy::new(3); - let d4 = CrashTestDummy::new(4); - let d5 = CrashTestDummy::new(5); - let mut q = BinaryHeap::from(vec![ - d0.spawn(Panic::Never), - d1.spawn(Panic::Never), - d2.spawn(Panic::Never), - d3.spawn(Panic::InDrop), - d4.spawn(Panic::Never), - d5.spawn(Panic::Never), - ]); - - catch_unwind(AssertUnwindSafe(|| drop(q.drain_sorted()))).unwrap_err(); - - assert_eq!(d0.dropped(), 1); - assert_eq!(d1.dropped(), 1); - assert_eq!(d2.dropped(), 1); - assert_eq!(d3.dropped(), 1); - assert_eq!(d4.dropped(), 1); - assert_eq!(d5.dropped(), 1); - assert!(q.is_empty()); -} - -#[test] -fn test_drain_forget() { - let a = CrashTestDummy::new(0); - let b = CrashTestDummy::new(1); - let c = CrashTestDummy::new(2); - let mut q = - BinaryHeap::from(vec![a.spawn(Panic::Never), b.spawn(Panic::Never), c.spawn(Panic::Never)]); - - catch_unwind(AssertUnwindSafe(|| { - let mut it = q.drain(); - it.next(); - mem::forget(it); - })) - .unwrap(); - // Behaviour after leaking is explicitly unspecified and order is arbitrary, - // so it's fine if these start failing, but probably worth knowing. - assert!(q.is_empty()); - assert_eq!(a.dropped() + b.dropped() + c.dropped(), 1); - assert_eq!(a.dropped(), 0); - assert_eq!(b.dropped(), 0); - assert_eq!(c.dropped(), 1); - drop(q); - assert_eq!(a.dropped(), 0); - assert_eq!(b.dropped(), 0); - assert_eq!(c.dropped(), 1); -} - -#[test] -fn test_drain_sorted_forget() { - let a = CrashTestDummy::new(0); - let b = CrashTestDummy::new(1); - let c = CrashTestDummy::new(2); - let mut q = - BinaryHeap::from(vec![a.spawn(Panic::Never), b.spawn(Panic::Never), c.spawn(Panic::Never)]); - - catch_unwind(AssertUnwindSafe(|| { - let mut it = q.drain_sorted(); - it.next(); - mem::forget(it); - })) - .unwrap(); - // Behaviour after leaking is explicitly unspecified, - // so it's fine if these start failing, but probably worth knowing. - assert_eq!(q.len(), 2); - assert_eq!(a.dropped(), 0); - assert_eq!(b.dropped(), 0); - assert_eq!(c.dropped(), 1); - drop(q); - assert_eq!(a.dropped(), 1); - assert_eq!(b.dropped(), 1); - assert_eq!(c.dropped(), 1); -} - -#[test] -fn test_extend_ref() { - let mut a = BinaryHeap::new(); - a.push(1); - a.push(2); - - a.extend(&[3, 4, 5]); - - assert_eq!(a.len(), 5); - assert_eq!(a.into_sorted_vec(), [1, 2, 3, 4, 5]); - - let mut a = BinaryHeap::new(); - a.push(1); - a.push(2); - let mut b = BinaryHeap::new(); - b.push(3); - b.push(4); - b.push(5); - - a.extend(&b); - - assert_eq!(a.len(), 5); - assert_eq!(a.into_sorted_vec(), [1, 2, 3, 4, 5]); -} - -#[test] -fn test_append() { - let mut a = BinaryHeap::from(vec![-10, 1, 2, 3, 3]); - let mut b = BinaryHeap::from(vec![-20, 5, 43]); - - a.append(&mut b); - - assert_eq!(a.into_sorted_vec(), [-20, -10, 1, 2, 3, 3, 5, 43]); - assert!(b.is_empty()); -} - -#[test] -fn test_append_to_empty() { - let mut a = BinaryHeap::new(); - let mut b = BinaryHeap::from(vec![-20, 5, 43]); - - a.append(&mut b); - - assert_eq!(a.into_sorted_vec(), [-20, 5, 43]); - assert!(b.is_empty()); -} - -#[test] -fn test_extend_specialization() { - let mut a = BinaryHeap::from(vec![-10, 1, 2, 3, 3]); - let b = BinaryHeap::from(vec![-20, 5, 43]); - - a.extend(b); - - assert_eq!(a.into_sorted_vec(), [-20, -10, 1, 2, 3, 3, 5, 43]); -} - -#[allow(dead_code)] -fn assert_covariance() { - fn drain<'new>(d: Drain<'static, &'static str>) -> Drain<'new, &'new str> { - d - } -} - -#[test] -fn test_retain() { - let mut a = BinaryHeap::from(vec![100, 10, 50, 1, 2, 20, 30]); - a.retain(|&x| x != 2); - - // Check that 20 moved into 10's place. - assert_eq!(a.clone().into_vec(), [100, 20, 50, 1, 10, 30]); - - a.retain(|_| true); - - assert_eq!(a.clone().into_vec(), [100, 20, 50, 1, 10, 30]); - - a.retain(|&x| x < 50); - - assert_eq!(a.clone().into_vec(), [30, 20, 10, 1]); - - a.retain(|_| false); - - assert!(a.is_empty()); -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_retain_catch_unwind() { - let mut heap = BinaryHeap::from(vec![3, 1, 2]); - - // Removes the 3, then unwinds out of retain. - let _ = catch_unwind(AssertUnwindSafe(|| { - heap.retain(|e| { - if *e == 1 { - panic!(); - } - false - }); - })); - - // Naively this would be [1, 2] (an invalid heap) if BinaryHeap delegates to - // Vec's retain impl and then does not rebuild the heap after that unwinds. - assert_eq!(heap.into_vec(), [2, 1]); -} - -// old binaryheap failed this test -// -// Integrity means that all elements are present after a comparison panics, -// even if the order might not be correct. -// -// Destructors must be called exactly once per element. -// FIXME: re-enable emscripten once it can unwind again -#[test] -#[cfg(not(target_os = "emscripten"))] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn panic_safe() { - use rand::seq::SliceRandom; - use std::cmp; - use std::panic::{self, AssertUnwindSafe}; - use std::sync::atomic::{AtomicUsize, Ordering}; - - static DROP_COUNTER: AtomicUsize = AtomicUsize::new(0); - - #[derive(Eq, PartialEq, Ord, Clone, Debug)] - struct PanicOrd(T, bool); - - impl Drop for PanicOrd { - fn drop(&mut self) { - // update global drop count - DROP_COUNTER.fetch_add(1, Ordering::SeqCst); - } - } - - impl PartialOrd for PanicOrd { - fn partial_cmp(&self, other: &Self) -> Option { - if self.1 || other.1 { - panic!("Panicking comparison"); - } - self.0.partial_cmp(&other.0) - } - } - let mut rng = crate::test_helpers::test_rng(); - const DATASZ: usize = 32; - // Miri is too slow - let ntest = if cfg!(miri) { 1 } else { 10 }; - - // don't use 0 in the data -- we want to catch the zeroed-out case. - let data = (1..=DATASZ).collect::>(); - - // since it's a fuzzy test, run several tries. - for _ in 0..ntest { - for i in 1..=DATASZ { - DROP_COUNTER.store(0, Ordering::SeqCst); - - let mut panic_ords: Vec<_> = - data.iter().filter(|&&x| x != i).map(|&x| PanicOrd(x, false)).collect(); - let panic_item = PanicOrd(i, true); - - // heapify the sane items - panic_ords.shuffle(&mut rng); - let mut heap = BinaryHeap::from(panic_ords); - let inner_data; - - { - // push the panicking item to the heap and catch the panic - let thread_result = { - let mut heap_ref = AssertUnwindSafe(&mut heap); - panic::catch_unwind(move || { - heap_ref.push(panic_item); - }) - }; - assert!(thread_result.is_err()); - - // Assert no elements were dropped - let drops = DROP_COUNTER.load(Ordering::SeqCst); - assert!(drops == 0, "Must not drop items. drops={}", drops); - inner_data = heap.clone().into_vec(); - drop(heap); - } - let drops = DROP_COUNTER.load(Ordering::SeqCst); - assert_eq!(drops, DATASZ); - - let mut data_sorted = inner_data.into_iter().map(|p| p.0).collect::>(); - data_sorted.sort(); - assert_eq!(data_sorted, data); - } - } -} diff --git a/library/alloc/src/collections/btree/append.rs b/library/alloc/src/collections/btree/append.rs deleted file mode 100644 index b6989afb6255d..0000000000000 --- a/library/alloc/src/collections/btree/append.rs +++ /dev/null @@ -1,107 +0,0 @@ -use super::merge_iter::MergeIterInner; -use super::node::{self, Root}; -use core::alloc::Allocator; -use core::iter::FusedIterator; - -impl Root { - /// Appends all key-value pairs from the union of two ascending iterators, - /// incrementing a `length` variable along the way. The latter makes it - /// easier for the caller to avoid a leak when a drop handler panicks. - /// - /// If both iterators produce the same key, this method drops the pair from - /// the left iterator and appends the pair from the right iterator. - /// - /// If you want the tree to end up in a strictly ascending order, like for - /// a `BTreeMap`, both iterators should produce keys in strictly ascending - /// order, each greater than all keys in the tree, including any keys - /// already in the tree upon entry. - pub fn append_from_sorted_iters( - &mut self, - left: I, - right: I, - length: &mut usize, - alloc: A, - ) where - K: Ord, - I: Iterator + FusedIterator, - { - // We prepare to merge `left` and `right` into a sorted sequence in linear time. - let iter = MergeIter(MergeIterInner::new(left, right)); - - // Meanwhile, we build a tree from the sorted sequence in linear time. - self.bulk_push(iter, length, alloc) - } - - /// Pushes all key-value pairs to the end of the tree, incrementing a - /// `length` variable along the way. The latter makes it easier for the - /// caller to avoid a leak when the iterator panicks. - pub fn bulk_push(&mut self, iter: I, length: &mut usize, alloc: A) - where - I: Iterator, - { - let mut cur_node = self.borrow_mut().last_leaf_edge().into_node(); - // Iterate through all key-value pairs, pushing them into nodes at the right level. - for (key, value) in iter { - // Try to push key-value pair into the current leaf node. - if cur_node.len() < node::CAPACITY { - cur_node.push(key, value); - } else { - // No space left, go up and push there. - let mut open_node; - let mut test_node = cur_node.forget_type(); - loop { - match test_node.ascend() { - Ok(parent) => { - let parent = parent.into_node(); - if parent.len() < node::CAPACITY { - // Found a node with space left, push here. - open_node = parent; - break; - } else { - // Go up again. - test_node = parent.forget_type(); - } - } - Err(_) => { - // We are at the top, create a new root node and push there. - open_node = self.push_internal_level(alloc.clone()); - break; - } - } - } - - // Push key-value pair and new right subtree. - let tree_height = open_node.height() - 1; - let mut right_tree = Root::new(alloc.clone()); - for _ in 0..tree_height { - right_tree.push_internal_level(alloc.clone()); - } - open_node.push(key, value, right_tree); - - // Go down to the right-most leaf again. - cur_node = open_node.forget_type().last_leaf_edge().into_node(); - } - - // Increment length every iteration, to make sure the map drops - // the appended elements even if advancing the iterator panicks. - *length += 1; - } - self.fix_right_border_of_plentiful(); - } -} - -// An iterator for merging two sorted sequences into one -struct MergeIter>(MergeIterInner); - -impl Iterator for MergeIter -where - I: Iterator + FusedIterator, -{ - type Item = (K, V); - - /// If two keys are equal, returns the key-value pair from the right source. - fn next(&mut self) -> Option<(K, V)> { - let (a_next, b_next) = self.0.nexts(|a: &(K, V), b: &(K, V)| K::cmp(&a.0, &b.0)); - b_next.or(a_next) - } -} diff --git a/library/alloc/src/collections/btree/borrow.rs b/library/alloc/src/collections/btree/borrow.rs deleted file mode 100644 index 000b9bd0fab42..0000000000000 --- a/library/alloc/src/collections/btree/borrow.rs +++ /dev/null @@ -1,69 +0,0 @@ -use core::marker::PhantomData; -use core::ptr::NonNull; - -/// Models a reborrow of some unique reference, when you know that the reborrow -/// and all its descendants (i.e., all pointers and references derived from it) -/// will not be used any more at some point, after which you want to use the -/// original unique reference again. -/// -/// The borrow checker usually handles this stacking of borrows for you, but -/// some control flows that accomplish this stacking are too complicated for -/// the compiler to follow. A `DormantMutRef` allows you to check borrowing -/// yourself, while still expressing its stacked nature, and encapsulating -/// the raw pointer code needed to do this without undefined behavior. -pub struct DormantMutRef<'a, T> { - ptr: NonNull, - _marker: PhantomData<&'a mut T>, -} - -unsafe impl<'a, T> Sync for DormantMutRef<'a, T> where &'a mut T: Sync {} -unsafe impl<'a, T> Send for DormantMutRef<'a, T> where &'a mut T: Send {} - -impl<'a, T> DormantMutRef<'a, T> { - /// Capture a unique borrow, and immediately reborrow it. For the compiler, - /// the lifetime of the new reference is the same as the lifetime of the - /// original reference, but you promise to use it for a shorter period. - pub fn new(t: &'a mut T) -> (&'a mut T, Self) { - let ptr = NonNull::from(t); - // SAFETY: we hold the borrow throughout 'a via `_marker`, and we expose - // only this reference, so it is unique. - let new_ref = unsafe { &mut *ptr.as_ptr() }; - (new_ref, Self { ptr, _marker: PhantomData }) - } - - /// Revert to the unique borrow initially captured. - /// - /// # Safety - /// - /// The reborrow must have ended, i.e., the reference returned by `new` and - /// all pointers and references derived from it, must not be used anymore. - pub unsafe fn awaken(self) -> &'a mut T { - // SAFETY: our own safety conditions imply this reference is again unique. - unsafe { &mut *self.ptr.as_ptr() } - } - - /// Borrows a new mutable reference from the unique borrow initially captured. - /// - /// # Safety - /// - /// The reborrow must have ended, i.e., the reference returned by `new` and - /// all pointers and references derived from it, must not be used anymore. - pub unsafe fn reborrow(&mut self) -> &'a mut T { - // SAFETY: our own safety conditions imply this reference is again unique. - unsafe { &mut *self.ptr.as_ptr() } - } - - /// Borrows a new shared reference from the unique borrow initially captured. - /// - /// # Safety - /// - /// The reborrow must have ended, i.e., the reference returned by `new` and - /// all pointers and references derived from it, must not be used anymore. - pub unsafe fn reborrow_shared(&self) -> &'a T { - // SAFETY: our own safety conditions imply this reference is again unique. - unsafe { &*self.ptr.as_ptr() } - } -} - -#[cfg(test)] -mod tests; diff --git a/library/alloc/src/collections/btree/borrow/tests.rs b/library/alloc/src/collections/btree/borrow/tests.rs deleted file mode 100644 index 56a8434fc71e6..0000000000000 --- a/library/alloc/src/collections/btree/borrow/tests.rs +++ /dev/null @@ -1,19 +0,0 @@ -use super::DormantMutRef; - -#[test] -fn test_borrow() { - let mut data = 1; - let mut stack = vec![]; - let mut rr = &mut data; - for factor in [2, 3, 7].iter() { - let (r, dormant_r) = DormantMutRef::new(rr); - rr = r; - assert_eq!(*rr, 1); - stack.push((factor, dormant_r)); - } - while let Some((factor, dormant_r)) = stack.pop() { - let r = unsafe { dormant_r.awaken() }; - *r *= factor; - } - assert_eq!(data, 42); -} diff --git a/library/alloc/src/collections/btree/dedup_sorted_iter.rs b/library/alloc/src/collections/btree/dedup_sorted_iter.rs deleted file mode 100644 index cd6a88f329125..0000000000000 --- a/library/alloc/src/collections/btree/dedup_sorted_iter.rs +++ /dev/null @@ -1,49 +0,0 @@ -use core::iter::Peekable; - -/// An iterator for deduping the key of a sorted iterator. -/// When encountering the duplicated key, only the last key-value pair is yielded. -/// -/// Used by [`BTreeMap::bulk_build_from_sorted_iter`][1]. -/// -/// [1]: crate::collections::BTreeMap::bulk_build_from_sorted_iter -pub struct DedupSortedIter -where - I: Iterator, -{ - iter: Peekable, -} - -impl DedupSortedIter -where - I: Iterator, -{ - pub fn new(iter: I) -> Self { - Self { iter: iter.peekable() } - } -} - -impl Iterator for DedupSortedIter -where - K: Eq, - I: Iterator, -{ - type Item = (K, V); - - fn next(&mut self) -> Option<(K, V)> { - loop { - let next = match self.iter.next() { - Some(next) => next, - None => return None, - }; - - let peeked = match self.iter.peek() { - Some(peeked) => peeked, - None => return Some(next), - }; - - if next.0 != peeked.0 { - return Some(next); - } - } - } -} diff --git a/library/alloc/src/collections/btree/fix.rs b/library/alloc/src/collections/btree/fix.rs deleted file mode 100644 index 91b61218005a6..0000000000000 --- a/library/alloc/src/collections/btree/fix.rs +++ /dev/null @@ -1,179 +0,0 @@ -use super::map::MIN_LEN; -use super::node::{marker, ForceResult::*, Handle, LeftOrRight::*, NodeRef, Root}; -use core::alloc::Allocator; - -impl<'a, K: 'a, V: 'a> NodeRef, K, V, marker::LeafOrInternal> { - /// Stocks up a possibly underfull node by merging with or stealing from a - /// sibling. If successful but at the cost of shrinking the parent node, - /// returns that shrunk parent node. Returns an `Err` if the node is - /// an empty root. - fn fix_node_through_parent( - self, - alloc: A, - ) -> Result, K, V, marker::Internal>>, Self> { - let len = self.len(); - if len >= MIN_LEN { - Ok(None) - } else { - match self.choose_parent_kv() { - Ok(Left(mut left_parent_kv)) => { - if left_parent_kv.can_merge() { - let parent = left_parent_kv.merge_tracking_parent(alloc); - Ok(Some(parent)) - } else { - left_parent_kv.bulk_steal_left(MIN_LEN - len); - Ok(None) - } - } - Ok(Right(mut right_parent_kv)) => { - if right_parent_kv.can_merge() { - let parent = right_parent_kv.merge_tracking_parent(alloc); - Ok(Some(parent)) - } else { - right_parent_kv.bulk_steal_right(MIN_LEN - len); - Ok(None) - } - } - Err(root) => { - if len > 0 { - Ok(None) - } else { - Err(root) - } - } - } - } - } -} - -impl<'a, K: 'a, V: 'a> NodeRef, K, V, marker::LeafOrInternal> { - /// Stocks up a possibly underfull node, and if that causes its parent node - /// to shrink, stocks up the parent, recursively. - /// Returns `true` if it fixed the tree, `false` if it couldn't because the - /// root node became empty. - /// - /// This method does not expect ancestors to already be underfull upon entry - /// and panics if it encounters an empty ancestor. - pub fn fix_node_and_affected_ancestors(mut self, alloc: A) -> bool { - loop { - match self.fix_node_through_parent(alloc.clone()) { - Ok(Some(parent)) => self = parent.forget_type(), - Ok(None) => return true, - Err(_) => return false, - } - } - } -} - -impl Root { - /// Removes empty levels on the top, but keeps an empty leaf if the entire tree is empty. - pub fn fix_top(&mut self, alloc: A) { - while self.height() > 0 && self.len() == 0 { - self.pop_internal_level(alloc.clone()); - } - } - - /// Stocks up or merge away any underfull nodes on the right border of the - /// tree. The other nodes, those that are not the root nor a rightmost edge, - /// must already have at least MIN_LEN elements. - pub fn fix_right_border(&mut self, alloc: A) { - self.fix_top(alloc.clone()); - if self.len() > 0 { - self.borrow_mut().last_kv().fix_right_border_of_right_edge(alloc.clone()); - self.fix_top(alloc); - } - } - - /// The symmetric clone of `fix_right_border`. - pub fn fix_left_border(&mut self, alloc: A) { - self.fix_top(alloc.clone()); - if self.len() > 0 { - self.borrow_mut().first_kv().fix_left_border_of_left_edge(alloc.clone()); - self.fix_top(alloc); - } - } - - /// Stocks up any underfull nodes on the right border of the tree. - /// The other nodes, those that are neither the root nor a rightmost edge, - /// must be prepared to have up to MIN_LEN elements stolen. - pub fn fix_right_border_of_plentiful(&mut self) { - let mut cur_node = self.borrow_mut(); - while let Internal(internal) = cur_node.force() { - // Check if right-most child is underfull. - let mut last_kv = internal.last_kv().consider_for_balancing(); - debug_assert!(last_kv.left_child_len() >= MIN_LEN * 2); - let right_child_len = last_kv.right_child_len(); - if right_child_len < MIN_LEN { - // We need to steal. - last_kv.bulk_steal_left(MIN_LEN - right_child_len); - } - - // Go further down. - cur_node = last_kv.into_right_child(); - } - } -} - -impl<'a, K: 'a, V: 'a> Handle, K, V, marker::LeafOrInternal>, marker::KV> { - fn fix_left_border_of_left_edge(mut self, alloc: A) { - while let Internal(internal_kv) = self.force() { - self = internal_kv.fix_left_child(alloc.clone()).first_kv(); - debug_assert!(self.reborrow().into_node().len() > MIN_LEN); - } - } - - fn fix_right_border_of_right_edge(mut self, alloc: A) { - while let Internal(internal_kv) = self.force() { - self = internal_kv.fix_right_child(alloc.clone()).last_kv(); - debug_assert!(self.reborrow().into_node().len() > MIN_LEN); - } - } -} - -impl<'a, K: 'a, V: 'a> Handle, K, V, marker::Internal>, marker::KV> { - /// Stocks up the left child, assuming the right child isn't underfull, and - /// provisions an extra element to allow merging its children in turn - /// without becoming underfull. - /// Returns the left child. - fn fix_left_child( - self, - alloc: A, - ) -> NodeRef, K, V, marker::LeafOrInternal> { - let mut internal_kv = self.consider_for_balancing(); - let left_len = internal_kv.left_child_len(); - debug_assert!(internal_kv.right_child_len() >= MIN_LEN); - if internal_kv.can_merge() { - internal_kv.merge_tracking_child(alloc) - } else { - // `MIN_LEN + 1` to avoid readjust if merge happens on the next level. - let count = (MIN_LEN + 1).saturating_sub(left_len); - if count > 0 { - internal_kv.bulk_steal_right(count); - } - internal_kv.into_left_child() - } - } - - /// Stocks up the right child, assuming the left child isn't underfull, and - /// provisions an extra element to allow merging its children in turn - /// without becoming underfull. - /// Returns wherever the right child ended up. - fn fix_right_child( - self, - alloc: A, - ) -> NodeRef, K, V, marker::LeafOrInternal> { - let mut internal_kv = self.consider_for_balancing(); - let right_len = internal_kv.right_child_len(); - debug_assert!(internal_kv.left_child_len() >= MIN_LEN); - if internal_kv.can_merge() { - internal_kv.merge_tracking_child(alloc) - } else { - // `MIN_LEN + 1` to avoid readjust if merge happens on the next level. - let count = (MIN_LEN + 1).saturating_sub(right_len); - if count > 0 { - internal_kv.bulk_steal_left(count); - } - internal_kv.into_right_child() - } - } -} diff --git a/library/alloc/src/collections/btree/map.rs b/library/alloc/src/collections/btree/map.rs deleted file mode 100644 index 3875f61efafdf..0000000000000 --- a/library/alloc/src/collections/btree/map.rs +++ /dev/null @@ -1,3411 +0,0 @@ -use crate::vec::Vec; -use core::borrow::Borrow; -use core::cmp::Ordering; -use core::error::Error; -use core::fmt::{self, Debug}; -use core::hash::{Hash, Hasher}; -use core::iter::FusedIterator; -use core::marker::PhantomData; -use core::mem::{self, ManuallyDrop}; -use core::ops::{Bound, Index, RangeBounds}; -use core::ptr; - -use crate::alloc::{Allocator, Global}; - -use super::borrow::DormantMutRef; -use super::dedup_sorted_iter::DedupSortedIter; -use super::navigate::{LazyLeafRange, LeafRange}; -use super::node::{self, marker, ForceResult::*, Handle, NodeRef, Root}; -use super::search::{SearchBound, SearchResult::*}; -use super::set_val::SetValZST; - -mod entry; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use entry::{Entry, OccupiedEntry, OccupiedError, VacantEntry}; - -use Entry::*; - -/// Minimum number of elements in a node that is not a root. -/// We might temporarily have fewer elements during methods. -pub(super) const MIN_LEN: usize = node::MIN_LEN_AFTER_SPLIT; - -// A tree in a `BTreeMap` is a tree in the `node` module with additional invariants: -// - Keys must appear in ascending order (according to the key's type). -// - Every non-leaf node contains at least 1 element (has at least 2 children). -// - Every non-root node contains at least MIN_LEN elements. -// -// An empty map is represented either by the absence of a root node or by a -// root node that is an empty leaf. - -/// An ordered map based on a [B-Tree]. -/// -/// B-Trees represent a fundamental compromise between cache-efficiency and actually minimizing -/// the amount of work performed in a search. In theory, a binary search tree (BST) is the optimal -/// choice for a sorted map, as a perfectly balanced BST performs the theoretical minimum amount of -/// comparisons necessary to find an element (log2n). However, in practice the way this -/// is done is *very* inefficient for modern computer architectures. In particular, every element -/// is stored in its own individually heap-allocated node. This means that every single insertion -/// triggers a heap-allocation, and every single comparison should be a cache-miss. Since these -/// are both notably expensive things to do in practice, we are forced to, at the very least, -/// reconsider the BST strategy. -/// -/// A B-Tree instead makes each node contain B-1 to 2B-1 elements in a contiguous array. By doing -/// this, we reduce the number of allocations by a factor of B, and improve cache efficiency in -/// searches. However, this does mean that searches will have to do *more* comparisons on average. -/// The precise number of comparisons depends on the node search strategy used. For optimal cache -/// efficiency, one could search the nodes linearly. For optimal comparisons, one could search -/// the node using binary search. As a compromise, one could also perform a linear search -/// that initially only checks every ith element for some choice of i. -/// -/// Currently, our implementation simply performs naive linear search. This provides excellent -/// performance on *small* nodes of elements which are cheap to compare. However in the future we -/// would like to further explore choosing the optimal search strategy based on the choice of B, -/// and possibly other factors. Using linear search, searching for a random element is expected -/// to take B * log(n) comparisons, which is generally worse than a BST. In practice, -/// however, performance is excellent. -/// -/// It is a logic error for a key to be modified in such a way that the key's ordering relative to -/// any other key, as determined by the [`Ord`] trait, changes while it is in the map. This is -/// normally only possible through [`Cell`], [`RefCell`], global state, I/O, or unsafe code. -/// The behavior resulting from such a logic error is not specified, but will be encapsulated to the -/// `BTreeMap` that observed the logic error and not result in undefined behavior. This could -/// include panics, incorrect results, aborts, memory leaks, and non-termination. -/// -/// Iterators obtained from functions such as [`BTreeMap::iter`], [`BTreeMap::into_iter`], [`BTreeMap::values`], or -/// [`BTreeMap::keys`] produce their items in order by key, and take worst-case logarithmic and -/// amortized constant time per item returned. -/// -/// [B-Tree]: https://en.wikipedia.org/wiki/B-tree -/// [`Cell`]: core::cell::Cell -/// [`RefCell`]: core::cell::RefCell -/// -/// # Examples -/// -/// ``` -/// use std::collections::BTreeMap; -/// -/// // type inference lets us omit an explicit type signature (which -/// // would be `BTreeMap<&str, &str>` in this example). -/// let mut movie_reviews = BTreeMap::new(); -/// -/// // review some movies. -/// movie_reviews.insert("Office Space", "Deals with real issues in the workplace."); -/// movie_reviews.insert("Pulp Fiction", "Masterpiece."); -/// movie_reviews.insert("The Godfather", "Very enjoyable."); -/// movie_reviews.insert("The Blues Brothers", "Eye lyked it a lot."); -/// -/// // check for a specific one. -/// if !movie_reviews.contains_key("Les Misérables") { -/// println!("We've got {} reviews, but Les Misérables ain't one.", -/// movie_reviews.len()); -/// } -/// -/// // oops, this review has a lot of spelling mistakes, let's delete it. -/// movie_reviews.remove("The Blues Brothers"); -/// -/// // look up the values associated with some keys. -/// let to_find = ["Up!", "Office Space"]; -/// for movie in &to_find { -/// match movie_reviews.get(movie) { -/// Some(review) => println!("{movie}: {review}"), -/// None => println!("{movie} is unreviewed.") -/// } -/// } -/// -/// // Look up the value for a key (will panic if the key is not found). -/// println!("Movie review: {}", movie_reviews["Office Space"]); -/// -/// // iterate over everything. -/// for (movie, review) in &movie_reviews { -/// println!("{movie}: \"{review}\""); -/// } -/// ``` -/// -/// A `BTreeMap` with a known list of items can be initialized from an array: -/// -/// ``` -/// use std::collections::BTreeMap; -/// -/// let solar_distance = BTreeMap::from([ -/// ("Mercury", 0.4), -/// ("Venus", 0.7), -/// ("Earth", 1.0), -/// ("Mars", 1.5), -/// ]); -/// ``` -/// -/// `BTreeMap` implements an [`Entry API`], which allows for complex -/// methods of getting, setting, updating and removing keys and their values: -/// -/// [`Entry API`]: BTreeMap::entry -/// -/// ``` -/// use std::collections::BTreeMap; -/// -/// // type inference lets us omit an explicit type signature (which -/// // would be `BTreeMap<&str, u8>` in this example). -/// let mut player_stats = BTreeMap::new(); -/// -/// fn random_stat_buff() -> u8 { -/// // could actually return some random value here - let's just return -/// // some fixed value for now -/// 42 -/// } -/// -/// // insert a key only if it doesn't already exist -/// player_stats.entry("health").or_insert(100); -/// -/// // insert a key using a function that provides a new value only if it -/// // doesn't already exist -/// player_stats.entry("defence").or_insert_with(random_stat_buff); -/// -/// // update a key, guarding against the key possibly not being set -/// let stat = player_stats.entry("attack").or_insert(100); -/// *stat += random_stat_buff(); -/// -/// // modify an entry before an insert with in-place mutation -/// player_stats.entry("mana").and_modify(|mana| *mana += 200).or_insert(100); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "BTreeMap")] -#[rustc_insignificant_dtor] -pub struct BTreeMap< - K, - V, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator + Clone = Global, -> { - root: Option>, - length: usize, - /// `ManuallyDrop` to control drop order (needs to be dropped after all the nodes). - pub(super) alloc: ManuallyDrop, - // For dropck; the `Box` avoids making the `Unpin` impl more strict than before - _marker: PhantomData>, -} - -#[stable(feature = "btree_drop", since = "1.7.0")] -unsafe impl<#[may_dangle] K, #[may_dangle] V, A: Allocator + Clone> Drop for BTreeMap { - fn drop(&mut self) { - drop(unsafe { ptr::read(self) }.into_iter()) - } -} - -// FIXME: This implementation is "wrong", but changing it would be a breaking change. -// (The bounds of the automatic `UnwindSafe` implementation have been like this since Rust 1.50.) -// Maybe we can fix it nonetheless with a crater run, or if the `UnwindSafe` -// traits are deprecated, or disarmed (no longer causing hard errors) in the future. -#[stable(feature = "btree_unwindsafe", since = "1.64.0")] -impl core::panic::UnwindSafe for BTreeMap -where - A: core::panic::UnwindSafe, - K: core::panic::RefUnwindSafe, - V: core::panic::RefUnwindSafe, -{ -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for BTreeMap { - fn clone(&self) -> BTreeMap { - fn clone_subtree<'a, K: Clone, V: Clone, A: Allocator + Clone>( - node: NodeRef, K, V, marker::LeafOrInternal>, - alloc: A, - ) -> BTreeMap - where - K: 'a, - V: 'a, - { - match node.force() { - Leaf(leaf) => { - let mut out_tree = BTreeMap { - root: Some(Root::new(alloc.clone())), - length: 0, - alloc: ManuallyDrop::new(alloc), - _marker: PhantomData, - }; - - { - let root = out_tree.root.as_mut().unwrap(); // unwrap succeeds because we just wrapped - let mut out_node = match root.borrow_mut().force() { - Leaf(leaf) => leaf, - Internal(_) => unreachable!(), - }; - - let mut in_edge = leaf.first_edge(); - while let Ok(kv) = in_edge.right_kv() { - let (k, v) = kv.into_kv(); - in_edge = kv.right_edge(); - - out_node.push(k.clone(), v.clone()); - out_tree.length += 1; - } - } - - out_tree - } - Internal(internal) => { - let mut out_tree = - clone_subtree(internal.first_edge().descend(), alloc.clone()); - - { - let out_root = out_tree.root.as_mut().unwrap(); - let mut out_node = out_root.push_internal_level(alloc.clone()); - let mut in_edge = internal.first_edge(); - while let Ok(kv) = in_edge.right_kv() { - let (k, v) = kv.into_kv(); - in_edge = kv.right_edge(); - - let k = (*k).clone(); - let v = (*v).clone(); - let subtree = clone_subtree(in_edge.descend(), alloc.clone()); - - // We can't destructure subtree directly - // because BTreeMap implements Drop - let (subroot, sublength) = unsafe { - let subtree = ManuallyDrop::new(subtree); - let root = ptr::read(&subtree.root); - let length = subtree.length; - (root, length) - }; - - out_node.push( - k, - v, - subroot.unwrap_or_else(|| Root::new(alloc.clone())), - ); - out_tree.length += 1 + sublength; - } - } - - out_tree - } - } - } - - if self.is_empty() { - BTreeMap::new_in((*self.alloc).clone()) - } else { - clone_subtree(self.root.as_ref().unwrap().reborrow(), (*self.alloc).clone()) // unwrap succeeds because not empty - } - } -} - -impl super::Recover for BTreeMap -where - K: Borrow + Ord, - Q: Ord, -{ - type Key = K; - - fn get(&self, key: &Q) -> Option<&K> { - let root_node = self.root.as_ref()?.reborrow(); - match root_node.search_tree(key) { - Found(handle) => Some(handle.into_kv().0), - GoDown(_) => None, - } - } - - fn take(&mut self, key: &Q) -> Option { - let (map, dormant_map) = DormantMutRef::new(self); - let root_node = map.root.as_mut()?.borrow_mut(); - match root_node.search_tree(key) { - Found(handle) => Some( - OccupiedEntry { - handle, - dormant_map, - alloc: (*map.alloc).clone(), - _marker: PhantomData, - } - .remove_kv() - .0, - ), - GoDown(_) => None, - } - } - - fn replace(&mut self, key: K) -> Option { - let (map, dormant_map) = DormantMutRef::new(self); - let root_node = - map.root.get_or_insert_with(|| Root::new((*map.alloc).clone())).borrow_mut(); - match root_node.search_tree::(&key) { - Found(mut kv) => Some(mem::replace(kv.key_mut(), key)), - GoDown(handle) => { - VacantEntry { - key, - handle: Some(handle), - dormant_map, - alloc: (*map.alloc).clone(), - _marker: PhantomData, - } - .insert(SetValZST::default()); - None - } - } - } -} - -/// An iterator over the entries of a `BTreeMap`. -/// -/// This `struct` is created by the [`iter`] method on [`BTreeMap`]. See its -/// documentation for more. -/// -/// [`iter`]: BTreeMap::iter -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Iter<'a, K: 'a, V: 'a> { - range: LazyLeafRange, K, V>, - length: usize, -} - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl fmt::Debug for Iter<'_, K, V> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.clone()).finish() - } -} - -#[stable(feature = "default_iters", since = "1.70.0")] -impl<'a, K: 'a, V: 'a> Default for Iter<'a, K, V> { - /// Creates an empty `btree_map::Iter`. - /// - /// ``` - /// # use std::collections::btree_map; - /// let iter: btree_map::Iter<'_, u8, u8> = Default::default(); - /// assert_eq!(iter.len(), 0); - /// ``` - fn default() -> Self { - Iter { range: Default::default(), length: 0 } - } -} - -/// A mutable iterator over the entries of a `BTreeMap`. -/// -/// This `struct` is created by the [`iter_mut`] method on [`BTreeMap`]. See its -/// documentation for more. -/// -/// [`iter_mut`]: BTreeMap::iter_mut -#[stable(feature = "rust1", since = "1.0.0")] -pub struct IterMut<'a, K: 'a, V: 'a> { - range: LazyLeafRange, K, V>, - length: usize, - - // Be invariant in `K` and `V` - _marker: PhantomData<&'a mut (K, V)>, -} - -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "collection_debug", since = "1.17.0")] -impl fmt::Debug for IterMut<'_, K, V> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let range = Iter { range: self.range.reborrow(), length: self.length }; - f.debug_list().entries(range).finish() - } -} - -#[stable(feature = "default_iters", since = "1.70.0")] -impl<'a, K: 'a, V: 'a> Default for IterMut<'a, K, V> { - /// Creates an empty `btree_map::IterMut`. - /// - /// ``` - /// # use std::collections::btree_map; - /// let iter: btree_map::IterMut<'_, u8, u8> = Default::default(); - /// assert_eq!(iter.len(), 0); - /// ``` - fn default() -> Self { - IterMut { range: Default::default(), length: 0, _marker: PhantomData {} } - } -} - -/// An owning iterator over the entries of a `BTreeMap`, sorted by key. -/// -/// This `struct` is created by the [`into_iter`] method on [`BTreeMap`] -/// (provided by the [`IntoIterator`] trait). See its documentation for more. -/// -/// [`into_iter`]: IntoIterator::into_iter -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_insignificant_dtor] -pub struct IntoIter< - K, - V, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator + Clone = Global, -> { - range: LazyLeafRange, - length: usize, - /// The BTreeMap will outlive this IntoIter so we don't care about drop order for `alloc`. - alloc: A, -} - -impl IntoIter { - /// Returns an iterator of references over the remaining items. - #[inline] - pub(super) fn iter(&self) -> Iter<'_, K, V> { - Iter { range: self.range.reborrow(), length: self.length } - } -} - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl Debug for IntoIter { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.iter()).finish() - } -} - -#[stable(feature = "default_iters", since = "1.70.0")] -impl Default for IntoIter -where - A: Allocator + Default + Clone, -{ - /// Creates an empty `btree_map::IntoIter`. - /// - /// ``` - /// # use std::collections::btree_map; - /// let iter: btree_map::IntoIter = Default::default(); - /// assert_eq!(iter.len(), 0); - /// ``` - fn default() -> Self { - IntoIter { range: Default::default(), length: 0, alloc: Default::default() } - } -} - -/// An iterator over the keys of a `BTreeMap`. -/// -/// This `struct` is created by the [`keys`] method on [`BTreeMap`]. See its -/// documentation for more. -/// -/// [`keys`]: BTreeMap::keys -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Keys<'a, K, V> { - inner: Iter<'a, K, V>, -} - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl fmt::Debug for Keys<'_, K, V> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.clone()).finish() - } -} - -/// An iterator over the values of a `BTreeMap`. -/// -/// This `struct` is created by the [`values`] method on [`BTreeMap`]. See its -/// documentation for more. -/// -/// [`values`]: BTreeMap::values -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Values<'a, K, V> { - inner: Iter<'a, K, V>, -} - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl fmt::Debug for Values<'_, K, V> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.clone()).finish() - } -} - -/// A mutable iterator over the values of a `BTreeMap`. -/// -/// This `struct` is created by the [`values_mut`] method on [`BTreeMap`]. See its -/// documentation for more. -/// -/// [`values_mut`]: BTreeMap::values_mut -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "map_values_mut", since = "1.10.0")] -pub struct ValuesMut<'a, K, V> { - inner: IterMut<'a, K, V>, -} - -#[stable(feature = "map_values_mut", since = "1.10.0")] -impl fmt::Debug for ValuesMut<'_, K, V> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.inner.iter().map(|(_, val)| val)).finish() - } -} - -/// An owning iterator over the keys of a `BTreeMap`. -/// -/// This `struct` is created by the [`into_keys`] method on [`BTreeMap`]. -/// See its documentation for more. -/// -/// [`into_keys`]: BTreeMap::into_keys -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "map_into_keys_values", since = "1.54.0")] -pub struct IntoKeys { - inner: IntoIter, -} - -#[stable(feature = "map_into_keys_values", since = "1.54.0")] -impl fmt::Debug for IntoKeys { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.inner.iter().map(|(key, _)| key)).finish() - } -} - -/// An owning iterator over the values of a `BTreeMap`. -/// -/// This `struct` is created by the [`into_values`] method on [`BTreeMap`]. -/// See its documentation for more. -/// -/// [`into_values`]: BTreeMap::into_values -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "map_into_keys_values", since = "1.54.0")] -pub struct IntoValues< - K, - V, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator + Clone = Global, -> { - inner: IntoIter, -} - -#[stable(feature = "map_into_keys_values", since = "1.54.0")] -impl fmt::Debug for IntoValues { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.inner.iter().map(|(_, val)| val)).finish() - } -} - -/// An iterator over a sub-range of entries in a `BTreeMap`. -/// -/// This `struct` is created by the [`range`] method on [`BTreeMap`]. See its -/// documentation for more. -/// -/// [`range`]: BTreeMap::range -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "btree_range", since = "1.17.0")] -pub struct Range<'a, K: 'a, V: 'a> { - inner: LeafRange, K, V>, -} - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl fmt::Debug for Range<'_, K, V> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.clone()).finish() - } -} - -/// A mutable iterator over a sub-range of entries in a `BTreeMap`. -/// -/// This `struct` is created by the [`range_mut`] method on [`BTreeMap`]. See its -/// documentation for more. -/// -/// [`range_mut`]: BTreeMap::range_mut -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "btree_range", since = "1.17.0")] -pub struct RangeMut<'a, K: 'a, V: 'a> { - inner: LeafRange, K, V>, - - // Be invariant in `K` and `V` - _marker: PhantomData<&'a mut (K, V)>, -} - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl fmt::Debug for RangeMut<'_, K, V> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let range = Range { inner: self.inner.reborrow() }; - f.debug_list().entries(range).finish() - } -} - -impl BTreeMap { - /// Makes a new, empty `BTreeMap`. - /// - /// Does not allocate anything on its own. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map = BTreeMap::new(); - /// - /// // entries can now be inserted into the empty map - /// map.insert(1, "a"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_btree_new", since = "1.66.0")] - #[inline] - #[must_use] - pub const fn new() -> BTreeMap { - BTreeMap { root: None, length: 0, alloc: ManuallyDrop::new(Global), _marker: PhantomData } - } -} - -impl BTreeMap { - /// Clears the map, removing all elements. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut a = BTreeMap::new(); - /// a.insert(1, "a"); - /// a.clear(); - /// assert!(a.is_empty()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn clear(&mut self) { - // avoid moving the allocator - drop(BTreeMap { - root: mem::replace(&mut self.root, None), - length: mem::replace(&mut self.length, 0), - alloc: self.alloc.clone(), - _marker: PhantomData, - }); - } - - /// Makes a new empty BTreeMap with a reasonable choice for B. - /// - /// # Examples - /// - /// ``` - /// # #![feature(allocator_api)] - /// # #![feature(btreemap_alloc)] - /// use std::collections::BTreeMap; - /// use std::alloc::Global; - /// - /// let mut map = BTreeMap::new_in(Global); - /// - /// // entries can now be inserted into the empty map - /// map.insert(1, "a"); - /// ``` - #[unstable(feature = "btreemap_alloc", issue = "32838")] - pub const fn new_in(alloc: A) -> BTreeMap { - BTreeMap { root: None, length: 0, alloc: ManuallyDrop::new(alloc), _marker: PhantomData } - } -} - -impl BTreeMap { - /// Returns a reference to the value corresponding to the key. - /// - /// The key may be any borrowed form of the map's key type, but the ordering - /// on the borrowed form *must* match the ordering on the key type. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map = BTreeMap::new(); - /// map.insert(1, "a"); - /// assert_eq!(map.get(&1), Some(&"a")); - /// assert_eq!(map.get(&2), None); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn get(&self, key: &Q) -> Option<&V> - where - K: Borrow + Ord, - Q: Ord, - { - let root_node = self.root.as_ref()?.reborrow(); - match root_node.search_tree(key) { - Found(handle) => Some(handle.into_kv().1), - GoDown(_) => None, - } - } - - /// Returns the key-value pair corresponding to the supplied key. - /// - /// The supplied key may be any borrowed form of the map's key type, but the ordering - /// on the borrowed form *must* match the ordering on the key type. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map = BTreeMap::new(); - /// map.insert(1, "a"); - /// assert_eq!(map.get_key_value(&1), Some((&1, &"a"))); - /// assert_eq!(map.get_key_value(&2), None); - /// ``` - #[stable(feature = "map_get_key_value", since = "1.40.0")] - pub fn get_key_value(&self, k: &Q) -> Option<(&K, &V)> - where - K: Borrow + Ord, - Q: Ord, - { - let root_node = self.root.as_ref()?.reborrow(); - match root_node.search_tree(k) { - Found(handle) => Some(handle.into_kv()), - GoDown(_) => None, - } - } - - /// Returns the first key-value pair in the map. - /// The key in this pair is the minimum key in the map. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map = BTreeMap::new(); - /// assert_eq!(map.first_key_value(), None); - /// map.insert(1, "b"); - /// map.insert(2, "a"); - /// assert_eq!(map.first_key_value(), Some((&1, &"b"))); - /// ``` - #[stable(feature = "map_first_last", since = "1.66.0")] - pub fn first_key_value(&self) -> Option<(&K, &V)> - where - K: Ord, - { - let root_node = self.root.as_ref()?.reborrow(); - root_node.first_leaf_edge().right_kv().ok().map(Handle::into_kv) - } - - /// Returns the first entry in the map for in-place manipulation. - /// The key of this entry is the minimum key in the map. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map = BTreeMap::new(); - /// map.insert(1, "a"); - /// map.insert(2, "b"); - /// if let Some(mut entry) = map.first_entry() { - /// if *entry.key() > 0 { - /// entry.insert("first"); - /// } - /// } - /// assert_eq!(*map.get(&1).unwrap(), "first"); - /// assert_eq!(*map.get(&2).unwrap(), "b"); - /// ``` - #[stable(feature = "map_first_last", since = "1.66.0")] - pub fn first_entry(&mut self) -> Option> - where - K: Ord, - { - let (map, dormant_map) = DormantMutRef::new(self); - let root_node = map.root.as_mut()?.borrow_mut(); - let kv = root_node.first_leaf_edge().right_kv().ok()?; - Some(OccupiedEntry { - handle: kv.forget_node_type(), - dormant_map, - alloc: (*map.alloc).clone(), - _marker: PhantomData, - }) - } - - /// Removes and returns the first element in the map. - /// The key of this element is the minimum key that was in the map. - /// - /// # Examples - /// - /// Draining elements in ascending order, while keeping a usable map each iteration. - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map = BTreeMap::new(); - /// map.insert(1, "a"); - /// map.insert(2, "b"); - /// while let Some((key, _val)) = map.pop_first() { - /// assert!(map.iter().all(|(k, _v)| *k > key)); - /// } - /// assert!(map.is_empty()); - /// ``` - #[stable(feature = "map_first_last", since = "1.66.0")] - pub fn pop_first(&mut self) -> Option<(K, V)> - where - K: Ord, - { - self.first_entry().map(|entry| entry.remove_entry()) - } - - /// Returns the last key-value pair in the map. - /// The key in this pair is the maximum key in the map. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map = BTreeMap::new(); - /// map.insert(1, "b"); - /// map.insert(2, "a"); - /// assert_eq!(map.last_key_value(), Some((&2, &"a"))); - /// ``` - #[stable(feature = "map_first_last", since = "1.66.0")] - pub fn last_key_value(&self) -> Option<(&K, &V)> - where - K: Ord, - { - let root_node = self.root.as_ref()?.reborrow(); - root_node.last_leaf_edge().left_kv().ok().map(Handle::into_kv) - } - - /// Returns the last entry in the map for in-place manipulation. - /// The key of this entry is the maximum key in the map. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map = BTreeMap::new(); - /// map.insert(1, "a"); - /// map.insert(2, "b"); - /// if let Some(mut entry) = map.last_entry() { - /// if *entry.key() > 0 { - /// entry.insert("last"); - /// } - /// } - /// assert_eq!(*map.get(&1).unwrap(), "a"); - /// assert_eq!(*map.get(&2).unwrap(), "last"); - /// ``` - #[stable(feature = "map_first_last", since = "1.66.0")] - pub fn last_entry(&mut self) -> Option> - where - K: Ord, - { - let (map, dormant_map) = DormantMutRef::new(self); - let root_node = map.root.as_mut()?.borrow_mut(); - let kv = root_node.last_leaf_edge().left_kv().ok()?; - Some(OccupiedEntry { - handle: kv.forget_node_type(), - dormant_map, - alloc: (*map.alloc).clone(), - _marker: PhantomData, - }) - } - - /// Removes and returns the last element in the map. - /// The key of this element is the maximum key that was in the map. - /// - /// # Examples - /// - /// Draining elements in descending order, while keeping a usable map each iteration. - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map = BTreeMap::new(); - /// map.insert(1, "a"); - /// map.insert(2, "b"); - /// while let Some((key, _val)) = map.pop_last() { - /// assert!(map.iter().all(|(k, _v)| *k < key)); - /// } - /// assert!(map.is_empty()); - /// ``` - #[stable(feature = "map_first_last", since = "1.66.0")] - pub fn pop_last(&mut self) -> Option<(K, V)> - where - K: Ord, - { - self.last_entry().map(|entry| entry.remove_entry()) - } - - /// Returns `true` if the map contains a value for the specified key. - /// - /// The key may be any borrowed form of the map's key type, but the ordering - /// on the borrowed form *must* match the ordering on the key type. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map = BTreeMap::new(); - /// map.insert(1, "a"); - /// assert_eq!(map.contains_key(&1), true); - /// assert_eq!(map.contains_key(&2), false); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn contains_key(&self, key: &Q) -> bool - where - K: Borrow + Ord, - Q: Ord, - { - self.get(key).is_some() - } - - /// Returns a mutable reference to the value corresponding to the key. - /// - /// The key may be any borrowed form of the map's key type, but the ordering - /// on the borrowed form *must* match the ordering on the key type. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map = BTreeMap::new(); - /// map.insert(1, "a"); - /// if let Some(x) = map.get_mut(&1) { - /// *x = "b"; - /// } - /// assert_eq!(map[&1], "b"); - /// ``` - // See `get` for implementation notes, this is basically a copy-paste with mut's added - #[stable(feature = "rust1", since = "1.0.0")] - pub fn get_mut(&mut self, key: &Q) -> Option<&mut V> - where - K: Borrow + Ord, - Q: Ord, - { - let root_node = self.root.as_mut()?.borrow_mut(); - match root_node.search_tree(key) { - Found(handle) => Some(handle.into_val_mut()), - GoDown(_) => None, - } - } - - /// Inserts a key-value pair into the map. - /// - /// If the map did not have this key present, `None` is returned. - /// - /// If the map did have this key present, the value is updated, and the old - /// value is returned. The key is not updated, though; this matters for - /// types that can be `==` without being identical. See the [module-level - /// documentation] for more. - /// - /// [module-level documentation]: index.html#insert-and-complex-keys - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map = BTreeMap::new(); - /// assert_eq!(map.insert(37, "a"), None); - /// assert_eq!(map.is_empty(), false); - /// - /// map.insert(37, "b"); - /// assert_eq!(map.insert(37, "c"), Some("b")); - /// assert_eq!(map[&37], "c"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("push", "put", "set")] - pub fn insert(&mut self, key: K, value: V) -> Option - where - K: Ord, - { - match self.entry(key) { - Occupied(mut entry) => Some(entry.insert(value)), - Vacant(entry) => { - entry.insert(value); - None - } - } - } - - /// Tries to insert a key-value pair into the map, and returns - /// a mutable reference to the value in the entry. - /// - /// If the map already had this key present, nothing is updated, and - /// an error containing the occupied entry and the value is returned. - /// - /// # Examples - /// - /// ``` - /// #![feature(map_try_insert)] - /// - /// use std::collections::BTreeMap; - /// - /// let mut map = BTreeMap::new(); - /// assert_eq!(map.try_insert(37, "a").unwrap(), &"a"); - /// - /// let err = map.try_insert(37, "b").unwrap_err(); - /// assert_eq!(err.entry.key(), &37); - /// assert_eq!(err.entry.get(), &"a"); - /// assert_eq!(err.value, "b"); - /// ``` - #[unstable(feature = "map_try_insert", issue = "82766")] - pub fn try_insert(&mut self, key: K, value: V) -> Result<&mut V, OccupiedError<'_, K, V, A>> - where - K: Ord, - { - match self.entry(key) { - Occupied(entry) => Err(OccupiedError { entry, value }), - Vacant(entry) => Ok(entry.insert(value)), - } - } - - /// Removes a key from the map, returning the value at the key if the key - /// was previously in the map. - /// - /// The key may be any borrowed form of the map's key type, but the ordering - /// on the borrowed form *must* match the ordering on the key type. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map = BTreeMap::new(); - /// map.insert(1, "a"); - /// assert_eq!(map.remove(&1), Some("a")); - /// assert_eq!(map.remove(&1), None); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("delete", "take")] - pub fn remove(&mut self, key: &Q) -> Option - where - K: Borrow + Ord, - Q: Ord, - { - self.remove_entry(key).map(|(_, v)| v) - } - - /// Removes a key from the map, returning the stored key and value if the key - /// was previously in the map. - /// - /// The key may be any borrowed form of the map's key type, but the ordering - /// on the borrowed form *must* match the ordering on the key type. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map = BTreeMap::new(); - /// map.insert(1, "a"); - /// assert_eq!(map.remove_entry(&1), Some((1, "a"))); - /// assert_eq!(map.remove_entry(&1), None); - /// ``` - #[stable(feature = "btreemap_remove_entry", since = "1.45.0")] - pub fn remove_entry(&mut self, key: &Q) -> Option<(K, V)> - where - K: Borrow + Ord, - Q: Ord, - { - let (map, dormant_map) = DormantMutRef::new(self); - let root_node = map.root.as_mut()?.borrow_mut(); - match root_node.search_tree(key) { - Found(handle) => Some( - OccupiedEntry { - handle, - dormant_map, - alloc: (*map.alloc).clone(), - _marker: PhantomData, - } - .remove_entry(), - ), - GoDown(_) => None, - } - } - - /// Retains only the elements specified by the predicate. - /// - /// In other words, remove all pairs `(k, v)` for which `f(&k, &mut v)` returns `false`. - /// The elements are visited in ascending key order. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map: BTreeMap = (0..8).map(|x| (x, x*10)).collect(); - /// // Keep only the elements with even-numbered keys. - /// map.retain(|&k, _| k % 2 == 0); - /// assert!(map.into_iter().eq(vec![(0, 0), (2, 20), (4, 40), (6, 60)])); - /// ``` - #[inline] - #[stable(feature = "btree_retain", since = "1.53.0")] - pub fn retain(&mut self, mut f: F) - where - K: Ord, - F: FnMut(&K, &mut V) -> bool, - { - self.extract_if(|k, v| !f(k, v)).for_each(drop); - } - - /// Moves all elements from `other` into `self`, leaving `other` empty. - /// - /// If a key from `other` is already present in `self`, the respective - /// value from `self` will be overwritten with the respective value from `other`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut a = BTreeMap::new(); - /// a.insert(1, "a"); - /// a.insert(2, "b"); - /// a.insert(3, "c"); // Note: Key (3) also present in b. - /// - /// let mut b = BTreeMap::new(); - /// b.insert(3, "d"); // Note: Key (3) also present in a. - /// b.insert(4, "e"); - /// b.insert(5, "f"); - /// - /// a.append(&mut b); - /// - /// assert_eq!(a.len(), 5); - /// assert_eq!(b.len(), 0); - /// - /// assert_eq!(a[&1], "a"); - /// assert_eq!(a[&2], "b"); - /// assert_eq!(a[&3], "d"); // Note: "c" has been overwritten. - /// assert_eq!(a[&4], "e"); - /// assert_eq!(a[&5], "f"); - /// ``` - #[stable(feature = "btree_append", since = "1.11.0")] - pub fn append(&mut self, other: &mut Self) - where - K: Ord, - A: Clone, - { - // Do we have to append anything at all? - if other.is_empty() { - return; - } - - // We can just swap `self` and `other` if `self` is empty. - if self.is_empty() { - mem::swap(self, other); - return; - } - - let self_iter = mem::replace(self, Self::new_in((*self.alloc).clone())).into_iter(); - let other_iter = mem::replace(other, Self::new_in((*self.alloc).clone())).into_iter(); - let root = self.root.get_or_insert_with(|| Root::new((*self.alloc).clone())); - root.append_from_sorted_iters( - self_iter, - other_iter, - &mut self.length, - (*self.alloc).clone(), - ) - } - - /// Constructs a double-ended iterator over a sub-range of elements in the map. - /// The simplest way is to use the range syntax `min..max`, thus `range(min..max)` will - /// yield elements from min (inclusive) to max (exclusive). - /// The range may also be entered as `(Bound, Bound)`, so for example - /// `range((Excluded(4), Included(10)))` will yield a left-exclusive, right-inclusive - /// range from 4 to 10. - /// - /// # Panics - /// - /// Panics if range `start > end`. - /// Panics if range `start == end` and both bounds are `Excluded`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// use std::ops::Bound::Included; - /// - /// let mut map = BTreeMap::new(); - /// map.insert(3, "a"); - /// map.insert(5, "b"); - /// map.insert(8, "c"); - /// for (&key, &value) in map.range((Included(&4), Included(&8))) { - /// println!("{key}: {value}"); - /// } - /// assert_eq!(Some((&5, &"b")), map.range(4..).next()); - /// ``` - #[stable(feature = "btree_range", since = "1.17.0")] - pub fn range(&self, range: R) -> Range<'_, K, V> - where - T: Ord, - K: Borrow + Ord, - R: RangeBounds, - { - if let Some(root) = &self.root { - Range { inner: root.reborrow().range_search(range) } - } else { - Range { inner: LeafRange::none() } - } - } - - /// Constructs a mutable double-ended iterator over a sub-range of elements in the map. - /// The simplest way is to use the range syntax `min..max`, thus `range(min..max)` will - /// yield elements from min (inclusive) to max (exclusive). - /// The range may also be entered as `(Bound, Bound)`, so for example - /// `range((Excluded(4), Included(10)))` will yield a left-exclusive, right-inclusive - /// range from 4 to 10. - /// - /// # Panics - /// - /// Panics if range `start > end`. - /// Panics if range `start == end` and both bounds are `Excluded`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map: BTreeMap<&str, i32> = - /// [("Alice", 0), ("Bob", 0), ("Carol", 0), ("Cheryl", 0)].into(); - /// for (_, balance) in map.range_mut("B".."Cheryl") { - /// *balance += 100; - /// } - /// for (name, balance) in &map { - /// println!("{name} => {balance}"); - /// } - /// ``` - #[stable(feature = "btree_range", since = "1.17.0")] - pub fn range_mut(&mut self, range: R) -> RangeMut<'_, K, V> - where - T: Ord, - K: Borrow + Ord, - R: RangeBounds, - { - if let Some(root) = &mut self.root { - RangeMut { inner: root.borrow_valmut().range_search(range), _marker: PhantomData } - } else { - RangeMut { inner: LeafRange::none(), _marker: PhantomData } - } - } - - /// Gets the given key's corresponding entry in the map for in-place manipulation. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut count: BTreeMap<&str, usize> = BTreeMap::new(); - /// - /// // count the number of occurrences of letters in the vec - /// for x in ["a", "b", "a", "c", "a", "b"] { - /// count.entry(x).and_modify(|curr| *curr += 1).or_insert(1); - /// } - /// - /// assert_eq!(count["a"], 3); - /// assert_eq!(count["b"], 2); - /// assert_eq!(count["c"], 1); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn entry(&mut self, key: K) -> Entry<'_, K, V, A> - where - K: Ord, - { - let (map, dormant_map) = DormantMutRef::new(self); - match map.root { - None => Vacant(VacantEntry { - key, - handle: None, - dormant_map, - alloc: (*map.alloc).clone(), - _marker: PhantomData, - }), - Some(ref mut root) => match root.borrow_mut().search_tree(&key) { - Found(handle) => Occupied(OccupiedEntry { - handle, - dormant_map, - alloc: (*map.alloc).clone(), - _marker: PhantomData, - }), - GoDown(handle) => Vacant(VacantEntry { - key, - handle: Some(handle), - dormant_map, - alloc: (*map.alloc).clone(), - _marker: PhantomData, - }), - }, - } - } - - /// Splits the collection into two at the given key. Returns everything after the given key, - /// including the key. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut a = BTreeMap::new(); - /// a.insert(1, "a"); - /// a.insert(2, "b"); - /// a.insert(3, "c"); - /// a.insert(17, "d"); - /// a.insert(41, "e"); - /// - /// let b = a.split_off(&3); - /// - /// assert_eq!(a.len(), 2); - /// assert_eq!(b.len(), 3); - /// - /// assert_eq!(a[&1], "a"); - /// assert_eq!(a[&2], "b"); - /// - /// assert_eq!(b[&3], "c"); - /// assert_eq!(b[&17], "d"); - /// assert_eq!(b[&41], "e"); - /// ``` - #[stable(feature = "btree_split_off", since = "1.11.0")] - pub fn split_off(&mut self, key: &Q) -> Self - where - K: Borrow + Ord, - A: Clone, - { - if self.is_empty() { - return Self::new_in((*self.alloc).clone()); - } - - let total_num = self.len(); - let left_root = self.root.as_mut().unwrap(); // unwrap succeeds because not empty - - let right_root = left_root.split_off(key, (*self.alloc).clone()); - - let (new_left_len, right_len) = Root::calc_split_length(total_num, &left_root, &right_root); - self.length = new_left_len; - - BTreeMap { - root: Some(right_root), - length: right_len, - alloc: self.alloc.clone(), - _marker: PhantomData, - } - } - - /// Creates an iterator that visits all elements (key-value pairs) in - /// ascending key order and uses a closure to determine if an element should - /// be removed. If the closure returns `true`, the element is removed from - /// the map and yielded. If the closure returns `false`, or panics, the - /// element remains in the map and will not be yielded. - /// - /// The iterator also lets you mutate the value of each element in the - /// closure, regardless of whether you choose to keep or remove it. - /// - /// If the returned `ExtractIf` is not exhausted, e.g. because it is dropped without iterating - /// or the iteration short-circuits, then the remaining elements will be retained. - /// Use [`retain`] with a negated predicate if you do not need the returned iterator. - /// - /// [`retain`]: BTreeMap::retain - /// - /// # Examples - /// - /// Splitting a map into even and odd keys, reusing the original map: - /// - /// ``` - /// #![feature(btree_extract_if)] - /// use std::collections::BTreeMap; - /// - /// let mut map: BTreeMap = (0..8).map(|x| (x, x)).collect(); - /// let evens: BTreeMap<_, _> = map.extract_if(|k, _v| k % 2 == 0).collect(); - /// let odds = map; - /// assert_eq!(evens.keys().copied().collect::>(), [0, 2, 4, 6]); - /// assert_eq!(odds.keys().copied().collect::>(), [1, 3, 5, 7]); - /// ``` - #[unstable(feature = "btree_extract_if", issue = "70530")] - pub fn extract_if(&mut self, pred: F) -> ExtractIf<'_, K, V, F, A> - where - K: Ord, - F: FnMut(&K, &mut V) -> bool, - { - let (inner, alloc) = self.extract_if_inner(); - ExtractIf { pred, inner, alloc } - } - - pub(super) fn extract_if_inner(&mut self) -> (ExtractIfInner<'_, K, V>, A) - where - K: Ord, - { - if let Some(root) = self.root.as_mut() { - let (root, dormant_root) = DormantMutRef::new(root); - let front = root.borrow_mut().first_leaf_edge(); - ( - ExtractIfInner { - length: &mut self.length, - dormant_root: Some(dormant_root), - cur_leaf_edge: Some(front), - }, - (*self.alloc).clone(), - ) - } else { - ( - ExtractIfInner { - length: &mut self.length, - dormant_root: None, - cur_leaf_edge: None, - }, - (*self.alloc).clone(), - ) - } - } - - /// Creates a consuming iterator visiting all the keys, in sorted order. - /// The map cannot be used after calling this. - /// The iterator element type is `K`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut a = BTreeMap::new(); - /// a.insert(2, "b"); - /// a.insert(1, "a"); - /// - /// let keys: Vec = a.into_keys().collect(); - /// assert_eq!(keys, [1, 2]); - /// ``` - #[inline] - #[stable(feature = "map_into_keys_values", since = "1.54.0")] - pub fn into_keys(self) -> IntoKeys { - IntoKeys { inner: self.into_iter() } - } - - /// Creates a consuming iterator visiting all the values, in order by key. - /// The map cannot be used after calling this. - /// The iterator element type is `V`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut a = BTreeMap::new(); - /// a.insert(1, "hello"); - /// a.insert(2, "goodbye"); - /// - /// let values: Vec<&str> = a.into_values().collect(); - /// assert_eq!(values, ["hello", "goodbye"]); - /// ``` - #[inline] - #[stable(feature = "map_into_keys_values", since = "1.54.0")] - pub fn into_values(self) -> IntoValues { - IntoValues { inner: self.into_iter() } - } - - /// Makes a `BTreeMap` from a sorted iterator. - pub(crate) fn bulk_build_from_sorted_iter(iter: I, alloc: A) -> Self - where - K: Ord, - I: IntoIterator, - { - let mut root = Root::new(alloc.clone()); - let mut length = 0; - root.bulk_push(DedupSortedIter::new(iter.into_iter()), &mut length, alloc.clone()); - BTreeMap { root: Some(root), length, alloc: ManuallyDrop::new(alloc), _marker: PhantomData } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, K, V, A: Allocator + Clone> IntoIterator for &'a BTreeMap { - type Item = (&'a K, &'a V); - type IntoIter = Iter<'a, K, V>; - - fn into_iter(self) -> Iter<'a, K, V> { - self.iter() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, K: 'a, V: 'a> Iterator for Iter<'a, K, V> { - type Item = (&'a K, &'a V); - - fn next(&mut self) -> Option<(&'a K, &'a V)> { - if self.length == 0 { - None - } else { - self.length -= 1; - Some(unsafe { self.range.next_unchecked() }) - } - } - - fn size_hint(&self) -> (usize, Option) { - (self.length, Some(self.length)) - } - - fn last(mut self) -> Option<(&'a K, &'a V)> { - self.next_back() - } - - fn min(mut self) -> Option<(&'a K, &'a V)> - where - (&'a K, &'a V): Ord, - { - self.next() - } - - fn max(mut self) -> Option<(&'a K, &'a V)> - where - (&'a K, &'a V): Ord, - { - self.next_back() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Iter<'_, K, V> {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, K: 'a, V: 'a> DoubleEndedIterator for Iter<'a, K, V> { - fn next_back(&mut self) -> Option<(&'a K, &'a V)> { - if self.length == 0 { - None - } else { - self.length -= 1; - Some(unsafe { self.range.next_back_unchecked() }) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Iter<'_, K, V> { - fn len(&self) -> usize { - self.length - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Iter<'_, K, V> { - fn clone(&self) -> Self { - Iter { range: self.range.clone(), length: self.length } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, K, V, A: Allocator + Clone> IntoIterator for &'a mut BTreeMap { - type Item = (&'a K, &'a mut V); - type IntoIter = IterMut<'a, K, V>; - - fn into_iter(self) -> IterMut<'a, K, V> { - self.iter_mut() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, K, V> Iterator for IterMut<'a, K, V> { - type Item = (&'a K, &'a mut V); - - fn next(&mut self) -> Option<(&'a K, &'a mut V)> { - if self.length == 0 { - None - } else { - self.length -= 1; - Some(unsafe { self.range.next_unchecked() }) - } - } - - fn size_hint(&self) -> (usize, Option) { - (self.length, Some(self.length)) - } - - fn last(mut self) -> Option<(&'a K, &'a mut V)> { - self.next_back() - } - - fn min(mut self) -> Option<(&'a K, &'a mut V)> - where - (&'a K, &'a mut V): Ord, - { - self.next() - } - - fn max(mut self) -> Option<(&'a K, &'a mut V)> - where - (&'a K, &'a mut V): Ord, - { - self.next_back() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, K, V> DoubleEndedIterator for IterMut<'a, K, V> { - fn next_back(&mut self) -> Option<(&'a K, &'a mut V)> { - if self.length == 0 { - None - } else { - self.length -= 1; - Some(unsafe { self.range.next_back_unchecked() }) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for IterMut<'_, K, V> { - fn len(&self) -> usize { - self.length - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for IterMut<'_, K, V> {} - -impl<'a, K, V> IterMut<'a, K, V> { - /// Returns an iterator of references over the remaining items. - #[inline] - pub(super) fn iter(&self) -> Iter<'_, K, V> { - Iter { range: self.range.reborrow(), length: self.length } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl IntoIterator for BTreeMap { - type Item = (K, V); - type IntoIter = IntoIter; - - /// Gets an owning iterator over the entries of the map, sorted by key. - fn into_iter(self) -> IntoIter { - let mut me = ManuallyDrop::new(self); - if let Some(root) = me.root.take() { - let full_range = root.into_dying().full_range(); - - IntoIter { - range: full_range, - length: me.length, - alloc: unsafe { ManuallyDrop::take(&mut me.alloc) }, - } - } else { - IntoIter { - range: LazyLeafRange::none(), - length: 0, - alloc: unsafe { ManuallyDrop::take(&mut me.alloc) }, - } - } - } -} - -#[stable(feature = "btree_drop", since = "1.7.0")] -impl Drop for IntoIter { - fn drop(&mut self) { - struct DropGuard<'a, K, V, A: Allocator + Clone>(&'a mut IntoIter); - - impl<'a, K, V, A: Allocator + Clone> Drop for DropGuard<'a, K, V, A> { - fn drop(&mut self) { - // Continue the same loop we perform below. This only runs when unwinding, so we - // don't have to care about panics this time (they'll abort). - while let Some(kv) = self.0.dying_next() { - // SAFETY: we consume the dying handle immediately. - unsafe { kv.drop_key_val() }; - } - } - } - - while let Some(kv) = self.dying_next() { - let guard = DropGuard(self); - // SAFETY: we don't touch the tree before consuming the dying handle. - unsafe { kv.drop_key_val() }; - mem::forget(guard); - } - } -} - -impl IntoIter { - /// Core of a `next` method returning a dying KV handle, - /// invalidated by further calls to this function and some others. - fn dying_next( - &mut self, - ) -> Option, marker::KV>> { - if self.length == 0 { - self.range.deallocating_end(self.alloc.clone()); - None - } else { - self.length -= 1; - Some(unsafe { self.range.deallocating_next_unchecked(self.alloc.clone()) }) - } - } - - /// Core of a `next_back` method returning a dying KV handle, - /// invalidated by further calls to this function and some others. - fn dying_next_back( - &mut self, - ) -> Option, marker::KV>> { - if self.length == 0 { - self.range.deallocating_end(self.alloc.clone()); - None - } else { - self.length -= 1; - Some(unsafe { self.range.deallocating_next_back_unchecked(self.alloc.clone()) }) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for IntoIter { - type Item = (K, V); - - fn next(&mut self) -> Option<(K, V)> { - // SAFETY: we consume the dying handle immediately. - self.dying_next().map(unsafe { |kv| kv.into_key_val() }) - } - - fn size_hint(&self) -> (usize, Option) { - (self.length, Some(self.length)) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DoubleEndedIterator for IntoIter { - fn next_back(&mut self) -> Option<(K, V)> { - // SAFETY: we consume the dying handle immediately. - self.dying_next_back().map(unsafe { |kv| kv.into_key_val() }) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for IntoIter { - fn len(&self) -> usize { - self.length - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for IntoIter {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, K, V> Iterator for Keys<'a, K, V> { - type Item = &'a K; - - fn next(&mut self) -> Option<&'a K> { - self.inner.next().map(|(k, _)| k) - } - - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } - - fn last(mut self) -> Option<&'a K> { - self.next_back() - } - - fn min(mut self) -> Option<&'a K> - where - &'a K: Ord, - { - self.next() - } - - fn max(mut self) -> Option<&'a K> - where - &'a K: Ord, - { - self.next_back() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, K, V> DoubleEndedIterator for Keys<'a, K, V> { - fn next_back(&mut self) -> Option<&'a K> { - self.inner.next_back().map(|(k, _)| k) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Keys<'_, K, V> { - fn len(&self) -> usize { - self.inner.len() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Keys<'_, K, V> {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Keys<'_, K, V> { - fn clone(&self) -> Self { - Keys { inner: self.inner.clone() } - } -} - -#[stable(feature = "default_iters", since = "1.70.0")] -impl Default for Keys<'_, K, V> { - /// Creates an empty `btree_map::Keys`. - /// - /// ``` - /// # use std::collections::btree_map; - /// let iter: btree_map::Keys<'_, u8, u8> = Default::default(); - /// assert_eq!(iter.len(), 0); - /// ``` - fn default() -> Self { - Keys { inner: Default::default() } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, K, V> Iterator for Values<'a, K, V> { - type Item = &'a V; - - fn next(&mut self) -> Option<&'a V> { - self.inner.next().map(|(_, v)| v) - } - - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } - - fn last(mut self) -> Option<&'a V> { - self.next_back() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, K, V> DoubleEndedIterator for Values<'a, K, V> { - fn next_back(&mut self) -> Option<&'a V> { - self.inner.next_back().map(|(_, v)| v) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Values<'_, K, V> { - fn len(&self) -> usize { - self.inner.len() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Values<'_, K, V> {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Values<'_, K, V> { - fn clone(&self) -> Self { - Values { inner: self.inner.clone() } - } -} - -#[stable(feature = "default_iters", since = "1.70.0")] -impl Default for Values<'_, K, V> { - /// Creates an empty `btree_map::Values`. - /// - /// ``` - /// # use std::collections::btree_map; - /// let iter: btree_map::Values<'_, u8, u8> = Default::default(); - /// assert_eq!(iter.len(), 0); - /// ``` - fn default() -> Self { - Values { inner: Default::default() } - } -} - -/// An iterator produced by calling `extract_if` on BTreeMap. -#[unstable(feature = "btree_extract_if", issue = "70530")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct ExtractIf< - 'a, - K, - V, - F, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator + Clone = Global, -> where - F: 'a + FnMut(&K, &mut V) -> bool, -{ - pred: F, - inner: ExtractIfInner<'a, K, V>, - /// The BTreeMap will outlive this IntoIter so we don't care about drop order for `alloc`. - alloc: A, -} -/// Most of the implementation of ExtractIf are generic over the type -/// of the predicate, thus also serving for BTreeSet::ExtractIf. -pub(super) struct ExtractIfInner<'a, K, V> { - /// Reference to the length field in the borrowed map, updated live. - length: &'a mut usize, - /// Buried reference to the root field in the borrowed map. - /// Wrapped in `Option` to allow drop handler to `take` it. - dormant_root: Option>>, - /// Contains a leaf edge preceding the next element to be returned, or the last leaf edge. - /// Empty if the map has no root, if iteration went beyond the last leaf edge, - /// or if a panic occurred in the predicate. - cur_leaf_edge: Option, K, V, marker::Leaf>, marker::Edge>>, -} - -#[unstable(feature = "btree_extract_if", issue = "70530")] -impl fmt::Debug for ExtractIf<'_, K, V, F> -where - K: fmt::Debug, - V: fmt::Debug, - F: FnMut(&K, &mut V) -> bool, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("ExtractIf").field(&self.inner.peek()).finish() - } -} - -#[unstable(feature = "btree_extract_if", issue = "70530")] -impl Iterator for ExtractIf<'_, K, V, F, A> -where - F: FnMut(&K, &mut V) -> bool, -{ - type Item = (K, V); - - fn next(&mut self) -> Option<(K, V)> { - self.inner.next(&mut self.pred, self.alloc.clone()) - } - - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } -} - -impl<'a, K, V> ExtractIfInner<'a, K, V> { - /// Allow Debug implementations to predict the next element. - pub(super) fn peek(&self) -> Option<(&K, &V)> { - let edge = self.cur_leaf_edge.as_ref()?; - edge.reborrow().next_kv().ok().map(Handle::into_kv) - } - - /// Implementation of a typical `ExtractIf::next` method, given the predicate. - pub(super) fn next(&mut self, pred: &mut F, alloc: A) -> Option<(K, V)> - where - F: FnMut(&K, &mut V) -> bool, - { - while let Ok(mut kv) = self.cur_leaf_edge.take()?.next_kv() { - let (k, v) = kv.kv_mut(); - if pred(k, v) { - *self.length -= 1; - let (kv, pos) = kv.remove_kv_tracking( - || { - // SAFETY: we will touch the root in a way that will not - // invalidate the position returned. - let root = unsafe { self.dormant_root.take().unwrap().awaken() }; - root.pop_internal_level(alloc.clone()); - self.dormant_root = Some(DormantMutRef::new(root).1); - }, - alloc.clone(), - ); - self.cur_leaf_edge = Some(pos); - return Some(kv); - } - self.cur_leaf_edge = Some(kv.next_leaf_edge()); - } - None - } - - /// Implementation of a typical `ExtractIf::size_hint` method. - pub(super) fn size_hint(&self) -> (usize, Option) { - // In most of the btree iterators, `self.length` is the number of elements - // yet to be visited. Here, it includes elements that were visited and that - // the predicate decided not to drain. Making this upper bound more tight - // during iteration would require an extra field. - (0, Some(*self.length)) - } -} - -#[unstable(feature = "btree_extract_if", issue = "70530")] -impl FusedIterator for ExtractIf<'_, K, V, F> where F: FnMut(&K, &mut V) -> bool {} - -#[stable(feature = "btree_range", since = "1.17.0")] -impl<'a, K, V> Iterator for Range<'a, K, V> { - type Item = (&'a K, &'a V); - - fn next(&mut self) -> Option<(&'a K, &'a V)> { - self.inner.next_checked() - } - - fn last(mut self) -> Option<(&'a K, &'a V)> { - self.next_back() - } - - fn min(mut self) -> Option<(&'a K, &'a V)> - where - (&'a K, &'a V): Ord, - { - self.next() - } - - fn max(mut self) -> Option<(&'a K, &'a V)> - where - (&'a K, &'a V): Ord, - { - self.next_back() - } -} - -#[stable(feature = "default_iters", since = "1.70.0")] -impl Default for Range<'_, K, V> { - /// Creates an empty `btree_map::Range`. - /// - /// ``` - /// # use std::collections::btree_map; - /// let iter: btree_map::Range<'_, u8, u8> = Default::default(); - /// assert_eq!(iter.count(), 0); - /// ``` - fn default() -> Self { - Range { inner: Default::default() } - } -} - -#[stable(feature = "map_values_mut", since = "1.10.0")] -impl<'a, K, V> Iterator for ValuesMut<'a, K, V> { - type Item = &'a mut V; - - fn next(&mut self) -> Option<&'a mut V> { - self.inner.next().map(|(_, v)| v) - } - - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } - - fn last(mut self) -> Option<&'a mut V> { - self.next_back() - } -} - -#[stable(feature = "map_values_mut", since = "1.10.0")] -impl<'a, K, V> DoubleEndedIterator for ValuesMut<'a, K, V> { - fn next_back(&mut self) -> Option<&'a mut V> { - self.inner.next_back().map(|(_, v)| v) - } -} - -#[stable(feature = "map_values_mut", since = "1.10.0")] -impl ExactSizeIterator for ValuesMut<'_, K, V> { - fn len(&self) -> usize { - self.inner.len() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for ValuesMut<'_, K, V> {} - -#[stable(feature = "map_into_keys_values", since = "1.54.0")] -impl Iterator for IntoKeys { - type Item = K; - - fn next(&mut self) -> Option { - self.inner.next().map(|(k, _)| k) - } - - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } - - fn last(mut self) -> Option { - self.next_back() - } - - fn min(mut self) -> Option - where - K: Ord, - { - self.next() - } - - fn max(mut self) -> Option - where - K: Ord, - { - self.next_back() - } -} - -#[stable(feature = "map_into_keys_values", since = "1.54.0")] -impl DoubleEndedIterator for IntoKeys { - fn next_back(&mut self) -> Option { - self.inner.next_back().map(|(k, _)| k) - } -} - -#[stable(feature = "map_into_keys_values", since = "1.54.0")] -impl ExactSizeIterator for IntoKeys { - fn len(&self) -> usize { - self.inner.len() - } -} - -#[stable(feature = "map_into_keys_values", since = "1.54.0")] -impl FusedIterator for IntoKeys {} - -#[stable(feature = "default_iters", since = "1.70.0")] -impl Default for IntoKeys -where - A: Allocator + Default + Clone, -{ - /// Creates an empty `btree_map::IntoKeys`. - /// - /// ``` - /// # use std::collections::btree_map; - /// let iter: btree_map::IntoKeys = Default::default(); - /// assert_eq!(iter.len(), 0); - /// ``` - fn default() -> Self { - IntoKeys { inner: Default::default() } - } -} - -#[stable(feature = "map_into_keys_values", since = "1.54.0")] -impl Iterator for IntoValues { - type Item = V; - - fn next(&mut self) -> Option { - self.inner.next().map(|(_, v)| v) - } - - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } - - fn last(mut self) -> Option { - self.next_back() - } -} - -#[stable(feature = "map_into_keys_values", since = "1.54.0")] -impl DoubleEndedIterator for IntoValues { - fn next_back(&mut self) -> Option { - self.inner.next_back().map(|(_, v)| v) - } -} - -#[stable(feature = "map_into_keys_values", since = "1.54.0")] -impl ExactSizeIterator for IntoValues { - fn len(&self) -> usize { - self.inner.len() - } -} - -#[stable(feature = "map_into_keys_values", since = "1.54.0")] -impl FusedIterator for IntoValues {} - -#[stable(feature = "default_iters", since = "1.70.0")] -impl Default for IntoValues -where - A: Allocator + Default + Clone, -{ - /// Creates an empty `btree_map::IntoValues`. - /// - /// ``` - /// # use std::collections::btree_map; - /// let iter: btree_map::IntoValues = Default::default(); - /// assert_eq!(iter.len(), 0); - /// ``` - fn default() -> Self { - IntoValues { inner: Default::default() } - } -} - -#[stable(feature = "btree_range", since = "1.17.0")] -impl<'a, K, V> DoubleEndedIterator for Range<'a, K, V> { - fn next_back(&mut self) -> Option<(&'a K, &'a V)> { - self.inner.next_back_checked() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Range<'_, K, V> {} - -#[stable(feature = "btree_range", since = "1.17.0")] -impl Clone for Range<'_, K, V> { - fn clone(&self) -> Self { - Range { inner: self.inner.clone() } - } -} - -#[stable(feature = "btree_range", since = "1.17.0")] -impl<'a, K, V> Iterator for RangeMut<'a, K, V> { - type Item = (&'a K, &'a mut V); - - fn next(&mut self) -> Option<(&'a K, &'a mut V)> { - self.inner.next_checked() - } - - fn last(mut self) -> Option<(&'a K, &'a mut V)> { - self.next_back() - } - - fn min(mut self) -> Option<(&'a K, &'a mut V)> - where - (&'a K, &'a mut V): Ord, - { - self.next() - } - - fn max(mut self) -> Option<(&'a K, &'a mut V)> - where - (&'a K, &'a mut V): Ord, - { - self.next_back() - } -} - -#[stable(feature = "btree_range", since = "1.17.0")] -impl<'a, K, V> DoubleEndedIterator for RangeMut<'a, K, V> { - fn next_back(&mut self) -> Option<(&'a K, &'a mut V)> { - self.inner.next_back_checked() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for RangeMut<'_, K, V> {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl FromIterator<(K, V)> for BTreeMap { - fn from_iter>(iter: T) -> BTreeMap { - let mut inputs: Vec<_> = iter.into_iter().collect(); - - if inputs.is_empty() { - return BTreeMap::new(); - } - - // use stable sort to preserve the insertion order. - inputs.sort_by(|a, b| a.0.cmp(&b.0)); - BTreeMap::bulk_build_from_sorted_iter(inputs, Global) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Extend<(K, V)> for BTreeMap { - #[inline] - fn extend>(&mut self, iter: T) { - iter.into_iter().for_each(move |(k, v)| { - self.insert(k, v); - }); - } - - #[inline] - fn extend_one(&mut self, (k, v): (K, V)) { - self.insert(k, v); - } -} - -#[stable(feature = "extend_ref", since = "1.2.0")] -impl<'a, K: Ord + Copy, V: Copy, A: Allocator + Clone> Extend<(&'a K, &'a V)> - for BTreeMap -{ - fn extend>(&mut self, iter: I) { - self.extend(iter.into_iter().map(|(&key, &value)| (key, value))); - } - - #[inline] - fn extend_one(&mut self, (&k, &v): (&'a K, &'a V)) { - self.insert(k, v); - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Hash for BTreeMap { - fn hash(&self, state: &mut H) { - state.write_length_prefix(self.len()); - for elt in self { - elt.hash(state); - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Default for BTreeMap { - /// Creates an empty `BTreeMap`. - fn default() -> BTreeMap { - BTreeMap::new() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for BTreeMap { - fn eq(&self, other: &BTreeMap) -> bool { - self.len() == other.len() && self.iter().zip(other).all(|(a, b)| a == b) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Eq for BTreeMap {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialOrd for BTreeMap { - #[inline] - fn partial_cmp(&self, other: &BTreeMap) -> Option { - self.iter().partial_cmp(other.iter()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for BTreeMap { - #[inline] - fn cmp(&self, other: &BTreeMap) -> Ordering { - self.iter().cmp(other.iter()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Debug for BTreeMap { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_map().entries(self.iter()).finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Index<&Q> for BTreeMap -where - K: Borrow + Ord, - Q: Ord, -{ - type Output = V; - - /// Returns a reference to the value corresponding to the supplied key. - /// - /// # Panics - /// - /// Panics if the key is not present in the `BTreeMap`. - #[inline] - fn index(&self, key: &Q) -> &V { - self.get(key).expect("no entry found for key") - } -} - -#[stable(feature = "std_collections_from_array", since = "1.56.0")] -impl From<[(K, V); N]> for BTreeMap { - /// Converts a `[(K, V); N]` into a `BTreeMap<(K, V)>`. - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let map1 = BTreeMap::from([(1, 2), (3, 4)]); - /// let map2: BTreeMap<_, _> = [(1, 2), (3, 4)].into(); - /// assert_eq!(map1, map2); - /// ``` - fn from(mut arr: [(K, V); N]) -> Self { - if N == 0 { - return BTreeMap::new(); - } - - // use stable sort to preserve the insertion order. - arr.sort_by(|a, b| a.0.cmp(&b.0)); - BTreeMap::bulk_build_from_sorted_iter(arr, Global) - } -} - -impl BTreeMap { - /// Gets an iterator over the entries of the map, sorted by key. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map = BTreeMap::new(); - /// map.insert(3, "c"); - /// map.insert(2, "b"); - /// map.insert(1, "a"); - /// - /// for (key, value) in map.iter() { - /// println!("{key}: {value}"); - /// } - /// - /// let (first_key, first_value) = map.iter().next().unwrap(); - /// assert_eq!((*first_key, *first_value), (1, "a")); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn iter(&self) -> Iter<'_, K, V> { - if let Some(root) = &self.root { - let full_range = root.reborrow().full_range(); - - Iter { range: full_range, length: self.length } - } else { - Iter { range: LazyLeafRange::none(), length: 0 } - } - } - - /// Gets a mutable iterator over the entries of the map, sorted by key. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map = BTreeMap::from([ - /// ("a", 1), - /// ("b", 2), - /// ("c", 3), - /// ]); - /// - /// // add 10 to the value if the key isn't "a" - /// for (key, value) in map.iter_mut() { - /// if key != &"a" { - /// *value += 10; - /// } - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn iter_mut(&mut self) -> IterMut<'_, K, V> { - if let Some(root) = &mut self.root { - let full_range = root.borrow_valmut().full_range(); - - IterMut { range: full_range, length: self.length, _marker: PhantomData } - } else { - IterMut { range: LazyLeafRange::none(), length: 0, _marker: PhantomData } - } - } - - /// Gets an iterator over the keys of the map, in sorted order. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut a = BTreeMap::new(); - /// a.insert(2, "b"); - /// a.insert(1, "a"); - /// - /// let keys: Vec<_> = a.keys().cloned().collect(); - /// assert_eq!(keys, [1, 2]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn keys(&self) -> Keys<'_, K, V> { - Keys { inner: self.iter() } - } - - /// Gets an iterator over the values of the map, in order by key. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut a = BTreeMap::new(); - /// a.insert(1, "hello"); - /// a.insert(2, "goodbye"); - /// - /// let values: Vec<&str> = a.values().cloned().collect(); - /// assert_eq!(values, ["hello", "goodbye"]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn values(&self) -> Values<'_, K, V> { - Values { inner: self.iter() } - } - - /// Gets a mutable iterator over the values of the map, in order by key. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut a = BTreeMap::new(); - /// a.insert(1, String::from("hello")); - /// a.insert(2, String::from("goodbye")); - /// - /// for value in a.values_mut() { - /// value.push_str("!"); - /// } - /// - /// let values: Vec = a.values().cloned().collect(); - /// assert_eq!(values, [String::from("hello!"), - /// String::from("goodbye!")]); - /// ``` - #[stable(feature = "map_values_mut", since = "1.10.0")] - pub fn values_mut(&mut self) -> ValuesMut<'_, K, V> { - ValuesMut { inner: self.iter_mut() } - } - - /// Returns the number of elements in the map. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut a = BTreeMap::new(); - /// assert_eq!(a.len(), 0); - /// a.insert(1, "a"); - /// assert_eq!(a.len(), 1); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable( - feature = "const_btree_len", - issue = "71835", - implied_by = "const_btree_new" - )] - #[rustc_confusables("length", "size")] - pub const fn len(&self) -> usize { - self.length - } - - /// Returns `true` if the map contains no elements. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut a = BTreeMap::new(); - /// assert!(a.is_empty()); - /// a.insert(1, "a"); - /// assert!(!a.is_empty()); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable( - feature = "const_btree_len", - issue = "71835", - implied_by = "const_btree_new" - )] - pub const fn is_empty(&self) -> bool { - self.len() == 0 - } - - /// Returns a [`Cursor`] pointing at the gap before the smallest key - /// greater than the given bound. - /// - /// Passing `Bound::Included(x)` will return a cursor pointing to the - /// gap before the smallest key greater than or equal to `x`. - /// - /// Passing `Bound::Excluded(x)` will return a cursor pointing to the - /// gap before the smallest key greater than `x`. - /// - /// Passing `Bound::Unbounded` will return a cursor pointing to the - /// gap before the smallest key in the map. - /// - /// # Examples - /// - /// ``` - /// #![feature(btree_cursors)] - /// - /// use std::collections::BTreeMap; - /// use std::ops::Bound; - /// - /// let map = BTreeMap::from([ - /// (1, "a"), - /// (2, "b"), - /// (3, "c"), - /// (4, "d"), - /// ]); - /// - /// let cursor = map.lower_bound(Bound::Included(&2)); - /// assert_eq!(cursor.peek_prev(), Some((&1, &"a"))); - /// assert_eq!(cursor.peek_next(), Some((&2, &"b"))); - /// - /// let cursor = map.lower_bound(Bound::Excluded(&2)); - /// assert_eq!(cursor.peek_prev(), Some((&2, &"b"))); - /// assert_eq!(cursor.peek_next(), Some((&3, &"c"))); - /// - /// let cursor = map.lower_bound(Bound::Unbounded); - /// assert_eq!(cursor.peek_prev(), None); - /// assert_eq!(cursor.peek_next(), Some((&1, &"a"))); - /// ``` - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn lower_bound(&self, bound: Bound<&Q>) -> Cursor<'_, K, V> - where - K: Borrow + Ord, - Q: Ord, - { - let root_node = match self.root.as_ref() { - None => return Cursor { current: None, root: None }, - Some(root) => root.reborrow(), - }; - let edge = root_node.lower_bound(SearchBound::from_range(bound)); - Cursor { current: Some(edge), root: self.root.as_ref() } - } - - /// Returns a [`CursorMut`] pointing at the gap before the smallest key - /// greater than the given bound. - /// - /// Passing `Bound::Included(x)` will return a cursor pointing to the - /// gap before the smallest key greater than or equal to `x`. - /// - /// Passing `Bound::Excluded(x)` will return a cursor pointing to the - /// gap before the smallest key greater than `x`. - /// - /// Passing `Bound::Unbounded` will return a cursor pointing to the - /// gap before the smallest key in the map. - /// - /// # Examples - /// - /// ``` - /// #![feature(btree_cursors)] - /// - /// use std::collections::BTreeMap; - /// use std::ops::Bound; - /// - /// let mut map = BTreeMap::from([ - /// (1, "a"), - /// (2, "b"), - /// (3, "c"), - /// (4, "d"), - /// ]); - /// - /// let mut cursor = map.lower_bound_mut(Bound::Included(&2)); - /// assert_eq!(cursor.peek_prev(), Some((&1, &mut "a"))); - /// assert_eq!(cursor.peek_next(), Some((&2, &mut "b"))); - /// - /// let mut cursor = map.lower_bound_mut(Bound::Excluded(&2)); - /// assert_eq!(cursor.peek_prev(), Some((&2, &mut "b"))); - /// assert_eq!(cursor.peek_next(), Some((&3, &mut "c"))); - /// - /// let mut cursor = map.lower_bound_mut(Bound::Unbounded); - /// assert_eq!(cursor.peek_prev(), None); - /// assert_eq!(cursor.peek_next(), Some((&1, &mut "a"))); - /// ``` - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn lower_bound_mut(&mut self, bound: Bound<&Q>) -> CursorMut<'_, K, V, A> - where - K: Borrow + Ord, - Q: Ord, - { - let (root, dormant_root) = DormantMutRef::new(&mut self.root); - let root_node = match root.as_mut() { - None => { - return CursorMut { - inner: CursorMutKey { - current: None, - root: dormant_root, - length: &mut self.length, - alloc: &mut *self.alloc, - }, - }; - } - Some(root) => root.borrow_mut(), - }; - let edge = root_node.lower_bound(SearchBound::from_range(bound)); - CursorMut { - inner: CursorMutKey { - current: Some(edge), - root: dormant_root, - length: &mut self.length, - alloc: &mut *self.alloc, - }, - } - } - - /// Returns a [`Cursor`] pointing at the gap after the greatest key - /// smaller than the given bound. - /// - /// Passing `Bound::Included(x)` will return a cursor pointing to the - /// gap after the greatest key smaller than or equal to `x`. - /// - /// Passing `Bound::Excluded(x)` will return a cursor pointing to the - /// gap after the greatest key smaller than `x`. - /// - /// Passing `Bound::Unbounded` will return a cursor pointing to the - /// gap after the greatest key in the map. - /// - /// # Examples - /// - /// ``` - /// #![feature(btree_cursors)] - /// - /// use std::collections::BTreeMap; - /// use std::ops::Bound; - /// - /// let map = BTreeMap::from([ - /// (1, "a"), - /// (2, "b"), - /// (3, "c"), - /// (4, "d"), - /// ]); - /// - /// let cursor = map.upper_bound(Bound::Included(&3)); - /// assert_eq!(cursor.peek_prev(), Some((&3, &"c"))); - /// assert_eq!(cursor.peek_next(), Some((&4, &"d"))); - /// - /// let cursor = map.upper_bound(Bound::Excluded(&3)); - /// assert_eq!(cursor.peek_prev(), Some((&2, &"b"))); - /// assert_eq!(cursor.peek_next(), Some((&3, &"c"))); - /// - /// let cursor = map.upper_bound(Bound::Unbounded); - /// assert_eq!(cursor.peek_prev(), Some((&4, &"d"))); - /// assert_eq!(cursor.peek_next(), None); - /// ``` - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn upper_bound(&self, bound: Bound<&Q>) -> Cursor<'_, K, V> - where - K: Borrow + Ord, - Q: Ord, - { - let root_node = match self.root.as_ref() { - None => return Cursor { current: None, root: None }, - Some(root) => root.reborrow(), - }; - let edge = root_node.upper_bound(SearchBound::from_range(bound)); - Cursor { current: Some(edge), root: self.root.as_ref() } - } - - /// Returns a [`CursorMut`] pointing at the gap after the greatest key - /// smaller than the given bound. - /// - /// Passing `Bound::Included(x)` will return a cursor pointing to the - /// gap after the greatest key smaller than or equal to `x`. - /// - /// Passing `Bound::Excluded(x)` will return a cursor pointing to the - /// gap after the greatest key smaller than `x`. - /// - /// Passing `Bound::Unbounded` will return a cursor pointing to the - /// gap after the greatest key in the map. - /// - /// # Examples - /// - /// ``` - /// #![feature(btree_cursors)] - /// - /// use std::collections::BTreeMap; - /// use std::ops::Bound; - /// - /// let mut map = BTreeMap::from([ - /// (1, "a"), - /// (2, "b"), - /// (3, "c"), - /// (4, "d"), - /// ]); - /// - /// let mut cursor = map.upper_bound_mut(Bound::Included(&3)); - /// assert_eq!(cursor.peek_prev(), Some((&3, &mut "c"))); - /// assert_eq!(cursor.peek_next(), Some((&4, &mut "d"))); - /// - /// let mut cursor = map.upper_bound_mut(Bound::Excluded(&3)); - /// assert_eq!(cursor.peek_prev(), Some((&2, &mut "b"))); - /// assert_eq!(cursor.peek_next(), Some((&3, &mut "c"))); - /// - /// let mut cursor = map.upper_bound_mut(Bound::Unbounded); - /// assert_eq!(cursor.peek_prev(), Some((&4, &mut "d"))); - /// assert_eq!(cursor.peek_next(), None); - /// ``` - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn upper_bound_mut(&mut self, bound: Bound<&Q>) -> CursorMut<'_, K, V, A> - where - K: Borrow + Ord, - Q: Ord, - { - let (root, dormant_root) = DormantMutRef::new(&mut self.root); - let root_node = match root.as_mut() { - None => { - return CursorMut { - inner: CursorMutKey { - current: None, - root: dormant_root, - length: &mut self.length, - alloc: &mut *self.alloc, - }, - }; - } - Some(root) => root.borrow_mut(), - }; - let edge = root_node.upper_bound(SearchBound::from_range(bound)); - CursorMut { - inner: CursorMutKey { - current: Some(edge), - root: dormant_root, - length: &mut self.length, - alloc: &mut *self.alloc, - }, - } - } -} - -/// A cursor over a `BTreeMap`. -/// -/// A `Cursor` is like an iterator, except that it can freely seek back-and-forth. -/// -/// Cursors always point to a gap between two elements in the map, and can -/// operate on the two immediately adjacent elements. -/// -/// A `Cursor` is created with the [`BTreeMap::lower_bound`] and [`BTreeMap::upper_bound`] methods. -#[unstable(feature = "btree_cursors", issue = "107540")] -pub struct Cursor<'a, K: 'a, V: 'a> { - // If current is None then it means the tree has not been allocated yet. - current: Option, K, V, marker::Leaf>, marker::Edge>>, - root: Option<&'a node::Root>, -} - -#[unstable(feature = "btree_cursors", issue = "107540")] -impl Clone for Cursor<'_, K, V> { - fn clone(&self) -> Self { - let Cursor { current, root } = *self; - Cursor { current, root } - } -} - -#[unstable(feature = "btree_cursors", issue = "107540")] -impl Debug for Cursor<'_, K, V> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str("Cursor") - } -} - -/// A cursor over a `BTreeMap` with editing operations. -/// -/// A `Cursor` is like an iterator, except that it can freely seek back-and-forth, and can -/// safely mutate the map during iteration. This is because the lifetime of its yielded -/// references is tied to its own lifetime, instead of just the underlying map. This means -/// cursors cannot yield multiple elements at once. -/// -/// Cursors always point to a gap between two elements in the map, and can -/// operate on the two immediately adjacent elements. -/// -/// A `CursorMut` is created with the [`BTreeMap::lower_bound_mut`] and [`BTreeMap::upper_bound_mut`] -/// methods. -#[unstable(feature = "btree_cursors", issue = "107540")] -pub struct CursorMut< - 'a, - K: 'a, - V: 'a, - #[unstable(feature = "allocator_api", issue = "32838")] A = Global, -> { - inner: CursorMutKey<'a, K, V, A>, -} - -#[unstable(feature = "btree_cursors", issue = "107540")] -impl Debug for CursorMut<'_, K, V, A> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str("CursorMut") - } -} - -/// A cursor over a `BTreeMap` with editing operations, and which allows -/// mutating the key of elements. -/// -/// A `Cursor` is like an iterator, except that it can freely seek back-and-forth, and can -/// safely mutate the map during iteration. This is because the lifetime of its yielded -/// references is tied to its own lifetime, instead of just the underlying map. This means -/// cursors cannot yield multiple elements at once. -/// -/// Cursors always point to a gap between two elements in the map, and can -/// operate on the two immediately adjacent elements. -/// -/// A `CursorMutKey` is created from a [`CursorMut`] with the -/// [`CursorMut::with_mutable_key`] method. -/// -/// # Safety -/// -/// Since this cursor allows mutating keys, you must ensure that the `BTreeMap` -/// invariants are maintained. Specifically: -/// -/// * The key of the newly inserted element must be unique in the tree. -/// * All keys in the tree must remain in sorted order. -#[unstable(feature = "btree_cursors", issue = "107540")] -pub struct CursorMutKey< - 'a, - K: 'a, - V: 'a, - #[unstable(feature = "allocator_api", issue = "32838")] A = Global, -> { - // If current is None then it means the tree has not been allocated yet. - current: Option, K, V, marker::Leaf>, marker::Edge>>, - root: DormantMutRef<'a, Option>>, - length: &'a mut usize, - alloc: &'a mut A, -} - -#[unstable(feature = "btree_cursors", issue = "107540")] -impl Debug for CursorMutKey<'_, K, V, A> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str("CursorMutKey") - } -} - -impl<'a, K, V> Cursor<'a, K, V> { - /// Advances the cursor to the next gap, returning the key and value of the - /// element that it moved over. - /// - /// If the cursor is already at the end of the map then `None` is returned - /// and the cursor is not moved. - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn next(&mut self) -> Option<(&'a K, &'a V)> { - let current = self.current.take()?; - match current.next_kv() { - Ok(kv) => { - let result = kv.into_kv(); - self.current = Some(kv.next_leaf_edge()); - Some(result) - } - Err(root) => { - self.current = Some(root.last_leaf_edge()); - None - } - } - } - - /// Advances the cursor to the previous gap, returning the key and value of - /// the element that it moved over. - /// - /// If the cursor is already at the start of the map then `None` is returned - /// and the cursor is not moved. - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn prev(&mut self) -> Option<(&'a K, &'a V)> { - let current = self.current.take()?; - match current.next_back_kv() { - Ok(kv) => { - let result = kv.into_kv(); - self.current = Some(kv.next_back_leaf_edge()); - Some(result) - } - Err(root) => { - self.current = Some(root.first_leaf_edge()); - None - } - } - } - - /// Returns a reference to the key and value of the next element without - /// moving the cursor. - /// - /// If the cursor is at the end of the map then `None` is returned - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn peek_next(&self) -> Option<(&'a K, &'a V)> { - self.clone().next() - } - - /// Returns a reference to the key and value of the previous element - /// without moving the cursor. - /// - /// If the cursor is at the start of the map then `None` is returned. - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn peek_prev(&self) -> Option<(&'a K, &'a V)> { - self.clone().prev() - } -} - -impl<'a, K, V, A> CursorMut<'a, K, V, A> { - /// Advances the cursor to the next gap, returning the key and value of the - /// element that it moved over. - /// - /// If the cursor is already at the end of the map then `None` is returned - /// and the cursor is not moved. - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn next(&mut self) -> Option<(&K, &mut V)> { - let (k, v) = self.inner.next()?; - Some((&*k, v)) - } - - /// Advances the cursor to the previous gap, returning the key and value of - /// the element that it moved over. - /// - /// If the cursor is already at the start of the map then `None` is returned - /// and the cursor is not moved. - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn prev(&mut self) -> Option<(&K, &mut V)> { - let (k, v) = self.inner.prev()?; - Some((&*k, v)) - } - - /// Returns a reference to the key and value of the next element without - /// moving the cursor. - /// - /// If the cursor is at the end of the map then `None` is returned - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn peek_next(&mut self) -> Option<(&K, &mut V)> { - let (k, v) = self.inner.peek_next()?; - Some((&*k, v)) - } - - /// Returns a reference to the key and value of the previous element - /// without moving the cursor. - /// - /// If the cursor is at the start of the map then `None` is returned. - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn peek_prev(&mut self) -> Option<(&K, &mut V)> { - let (k, v) = self.inner.peek_prev()?; - Some((&*k, v)) - } - - /// Returns a read-only cursor pointing to the same location as the - /// `CursorMut`. - /// - /// The lifetime of the returned `Cursor` is bound to that of the - /// `CursorMut`, which means it cannot outlive the `CursorMut` and that the - /// `CursorMut` is frozen for the lifetime of the `Cursor`. - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn as_cursor(&self) -> Cursor<'_, K, V> { - self.inner.as_cursor() - } - - /// Converts the cursor into a [`CursorMutKey`], which allows mutating - /// the key of elements in the tree. - /// - /// # Safety - /// - /// Since this cursor allows mutating keys, you must ensure that the `BTreeMap` - /// invariants are maintained. Specifically: - /// - /// * The key of the newly inserted element must be unique in the tree. - /// * All keys in the tree must remain in sorted order. - #[unstable(feature = "btree_cursors", issue = "107540")] - pub unsafe fn with_mutable_key(self) -> CursorMutKey<'a, K, V, A> { - self.inner - } -} - -impl<'a, K, V, A> CursorMutKey<'a, K, V, A> { - /// Advances the cursor to the next gap, returning the key and value of the - /// element that it moved over. - /// - /// If the cursor is already at the end of the map then `None` is returned - /// and the cursor is not moved. - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn next(&mut self) -> Option<(&mut K, &mut V)> { - let current = self.current.take()?; - match current.next_kv() { - Ok(mut kv) => { - // SAFETY: The key/value pointers remain valid even after the - // cursor is moved forward. The lifetimes then prevent any - // further access to the cursor. - let (k, v) = unsafe { kv.reborrow_mut().into_kv_mut() }; - let (k, v) = (k as *mut _, v as *mut _); - self.current = Some(kv.next_leaf_edge()); - Some(unsafe { (&mut *k, &mut *v) }) - } - Err(root) => { - self.current = Some(root.last_leaf_edge()); - None - } - } - } - - /// Advances the cursor to the previous gap, returning the key and value of - /// the element that it moved over. - /// - /// If the cursor is already at the start of the map then `None` is returned - /// and the cursor is not moved. - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn prev(&mut self) -> Option<(&mut K, &mut V)> { - let current = self.current.take()?; - match current.next_back_kv() { - Ok(mut kv) => { - // SAFETY: The key/value pointers remain valid even after the - // cursor is moved forward. The lifetimes then prevent any - // further access to the cursor. - let (k, v) = unsafe { kv.reborrow_mut().into_kv_mut() }; - let (k, v) = (k as *mut _, v as *mut _); - self.current = Some(kv.next_back_leaf_edge()); - Some(unsafe { (&mut *k, &mut *v) }) - } - Err(root) => { - self.current = Some(root.first_leaf_edge()); - None - } - } - } - - /// Returns a reference to the key and value of the next element without - /// moving the cursor. - /// - /// If the cursor is at the end of the map then `None` is returned - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn peek_next(&mut self) -> Option<(&mut K, &mut V)> { - let current = self.current.as_mut()?; - // SAFETY: We're not using this to mutate the tree. - let kv = unsafe { current.reborrow_mut() }.next_kv().ok()?.into_kv_mut(); - Some(kv) - } - - /// Returns a reference to the key and value of the previous element - /// without moving the cursor. - /// - /// If the cursor is at the start of the map then `None` is returned. - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn peek_prev(&mut self) -> Option<(&mut K, &mut V)> { - let current = self.current.as_mut()?; - // SAFETY: We're not using this to mutate the tree. - let kv = unsafe { current.reborrow_mut() }.next_back_kv().ok()?.into_kv_mut(); - Some(kv) - } - - /// Returns a read-only cursor pointing to the same location as the - /// `CursorMutKey`. - /// - /// The lifetime of the returned `Cursor` is bound to that of the - /// `CursorMutKey`, which means it cannot outlive the `CursorMutKey` and that the - /// `CursorMutKey` is frozen for the lifetime of the `Cursor`. - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn as_cursor(&self) -> Cursor<'_, K, V> { - Cursor { - // SAFETY: The tree is immutable while the cursor exists. - root: unsafe { self.root.reborrow_shared().as_ref() }, - current: self.current.as_ref().map(|current| current.reborrow()), - } - } -} - -// Now the tree editing operations -impl<'a, K: Ord, V, A: Allocator + Clone> CursorMutKey<'a, K, V, A> { - /// Inserts a new key-value pair into the map in the gap that the - /// cursor is currently pointing to. - /// - /// After the insertion the cursor will be pointing at the gap before the - /// newly inserted element. - /// - /// # Safety - /// - /// You must ensure that the `BTreeMap` invariants are maintained. - /// Specifically: - /// - /// * The key of the newly inserted element must be unique in the tree. - /// * All keys in the tree must remain in sorted order. - #[unstable(feature = "btree_cursors", issue = "107540")] - pub unsafe fn insert_after_unchecked(&mut self, key: K, value: V) { - let edge = match self.current.take() { - None => { - // Tree is empty, allocate a new root. - // SAFETY: We have no other reference to the tree. - let root = unsafe { self.root.reborrow() }; - debug_assert!(root.is_none()); - let mut node = NodeRef::new_leaf(self.alloc.clone()); - // SAFETY: We don't touch the root while the handle is alive. - let handle = unsafe { node.borrow_mut().push_with_handle(key, value) }; - *root = Some(node.forget_type()); - *self.length += 1; - self.current = Some(handle.left_edge()); - return; - } - Some(current) => current, - }; - - let handle = edge.insert_recursing(key, value, self.alloc.clone(), |ins| { - drop(ins.left); - // SAFETY: The handle to the newly inserted value is always on a - // leaf node, so adding a new root node doesn't invalidate it. - let root = unsafe { self.root.reborrow().as_mut().unwrap() }; - root.push_internal_level(self.alloc.clone()).push(ins.kv.0, ins.kv.1, ins.right) - }); - self.current = Some(handle.left_edge()); - *self.length += 1; - } - - /// Inserts a new key-value pair into the map in the gap that the - /// cursor is currently pointing to. - /// - /// After the insertion the cursor will be pointing at the gap after the - /// newly inserted element. - /// - /// # Safety - /// - /// You must ensure that the `BTreeMap` invariants are maintained. - /// Specifically: - /// - /// * The key of the newly inserted element must be unique in the tree. - /// * All keys in the tree must remain in sorted order. - #[unstable(feature = "btree_cursors", issue = "107540")] - pub unsafe fn insert_before_unchecked(&mut self, key: K, value: V) { - let edge = match self.current.take() { - None => { - // SAFETY: We have no other reference to the tree. - match unsafe { self.root.reborrow() } { - root @ None => { - // Tree is empty, allocate a new root. - let mut node = NodeRef::new_leaf(self.alloc.clone()); - // SAFETY: We don't touch the root while the handle is alive. - let handle = unsafe { node.borrow_mut().push_with_handle(key, value) }; - *root = Some(node.forget_type()); - *self.length += 1; - self.current = Some(handle.right_edge()); - return; - } - Some(root) => root.borrow_mut().last_leaf_edge(), - } - } - Some(current) => current, - }; - - let handle = edge.insert_recursing(key, value, self.alloc.clone(), |ins| { - drop(ins.left); - // SAFETY: The handle to the newly inserted value is always on a - // leaf node, so adding a new root node doesn't invalidate it. - let root = unsafe { self.root.reborrow().as_mut().unwrap() }; - root.push_internal_level(self.alloc.clone()).push(ins.kv.0, ins.kv.1, ins.right) - }); - self.current = Some(handle.right_edge()); - *self.length += 1; - } - - /// Inserts a new key-value pair into the map in the gap that the - /// cursor is currently pointing to. - /// - /// After the insertion the cursor will be pointing at the gap before the - /// newly inserted element. - /// - /// If the inserted key is not greater than the key before the cursor - /// (if any), or if it not less than the key after the cursor (if any), - /// then an [`UnorderedKeyError`] is returned since this would - /// invalidate the [`Ord`] invariant between the keys of the map. - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn insert_after(&mut self, key: K, value: V) -> Result<(), UnorderedKeyError> { - if let Some((prev, _)) = self.peek_prev() { - if &key <= prev { - return Err(UnorderedKeyError {}); - } - } - if let Some((next, _)) = self.peek_next() { - if &key >= next { - return Err(UnorderedKeyError {}); - } - } - unsafe { - self.insert_after_unchecked(key, value); - } - Ok(()) - } - - /// Inserts a new key-value pair into the map in the gap that the - /// cursor is currently pointing to. - /// - /// After the insertion the cursor will be pointing at the gap after the - /// newly inserted element. - /// - /// If the inserted key is not greater than the key before the cursor - /// (if any), or if it not less than the key after the cursor (if any), - /// then an [`UnorderedKeyError`] is returned since this would - /// invalidate the [`Ord`] invariant between the keys of the map. - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn insert_before(&mut self, key: K, value: V) -> Result<(), UnorderedKeyError> { - if let Some((prev, _)) = self.peek_prev() { - if &key <= prev { - return Err(UnorderedKeyError {}); - } - } - if let Some((next, _)) = self.peek_next() { - if &key >= next { - return Err(UnorderedKeyError {}); - } - } - unsafe { - self.insert_before_unchecked(key, value); - } - Ok(()) - } - - /// Removes the next element from the `BTreeMap`. - /// - /// The element that was removed is returned. The cursor position is - /// unchanged (before the removed element). - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn remove_next(&mut self) -> Option<(K, V)> { - let current = self.current.take()?; - if current.reborrow().next_kv().is_err() { - self.current = Some(current); - return None; - } - let mut emptied_internal_root = false; - let (kv, pos) = current - .next_kv() - // This should be unwrap(), but that doesn't work because NodeRef - // doesn't implement Debug. The condition is checked above. - .ok()? - .remove_kv_tracking(|| emptied_internal_root = true, self.alloc.clone()); - self.current = Some(pos); - *self.length -= 1; - if emptied_internal_root { - // SAFETY: This is safe since current does not point within the now - // empty root node. - let root = unsafe { self.root.reborrow().as_mut().unwrap() }; - root.pop_internal_level(self.alloc.clone()); - } - Some(kv) - } - - /// Removes the precending element from the `BTreeMap`. - /// - /// The element that was removed is returned. The cursor position is - /// unchanged (after the removed element). - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn remove_prev(&mut self) -> Option<(K, V)> { - let current = self.current.take()?; - if current.reborrow().next_back_kv().is_err() { - self.current = Some(current); - return None; - } - let mut emptied_internal_root = false; - let (kv, pos) = current - .next_back_kv() - // This should be unwrap(), but that doesn't work because NodeRef - // doesn't implement Debug. The condition is checked above. - .ok()? - .remove_kv_tracking(|| emptied_internal_root = true, self.alloc.clone()); - self.current = Some(pos); - *self.length -= 1; - if emptied_internal_root { - // SAFETY: This is safe since current does not point within the now - // empty root node. - let root = unsafe { self.root.reborrow().as_mut().unwrap() }; - root.pop_internal_level(self.alloc.clone()); - } - Some(kv) - } -} - -impl<'a, K: Ord, V, A: Allocator + Clone> CursorMut<'a, K, V, A> { - /// Inserts a new key-value pair into the map in the gap that the - /// cursor is currently pointing to. - /// - /// After the insertion the cursor will be pointing at the gap after the - /// newly inserted element. - /// - /// # Safety - /// - /// You must ensure that the `BTreeMap` invariants are maintained. - /// Specifically: - /// - /// * The key of the newly inserted element must be unique in the tree. - /// * All keys in the tree must remain in sorted order. - #[unstable(feature = "btree_cursors", issue = "107540")] - pub unsafe fn insert_after_unchecked(&mut self, key: K, value: V) { - unsafe { self.inner.insert_after_unchecked(key, value) } - } - - /// Inserts a new key-value pair into the map in the gap that the - /// cursor is currently pointing to. - /// - /// After the insertion the cursor will be pointing at the gap after the - /// newly inserted element. - /// - /// # Safety - /// - /// You must ensure that the `BTreeMap` invariants are maintained. - /// Specifically: - /// - /// * The key of the newly inserted element must be unique in the tree. - /// * All keys in the tree must remain in sorted order. - #[unstable(feature = "btree_cursors", issue = "107540")] - pub unsafe fn insert_before_unchecked(&mut self, key: K, value: V) { - unsafe { self.inner.insert_before_unchecked(key, value) } - } - - /// Inserts a new key-value pair into the map in the gap that the - /// cursor is currently pointing to. - /// - /// After the insertion the cursor will be pointing at the gap before the - /// newly inserted element. - /// - /// If the inserted key is not greater than the key before the cursor - /// (if any), or if it not less than the key after the cursor (if any), - /// then an [`UnorderedKeyError`] is returned since this would - /// invalidate the [`Ord`] invariant between the keys of the map. - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn insert_after(&mut self, key: K, value: V) -> Result<(), UnorderedKeyError> { - self.inner.insert_after(key, value) - } - - /// Inserts a new key-value pair into the map in the gap that the - /// cursor is currently pointing to. - /// - /// After the insertion the cursor will be pointing at the gap after the - /// newly inserted element. - /// - /// If the inserted key is not greater than the key before the cursor - /// (if any), or if it not less than the key after the cursor (if any), - /// then an [`UnorderedKeyError`] is returned since this would - /// invalidate the [`Ord`] invariant between the keys of the map. - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn insert_before(&mut self, key: K, value: V) -> Result<(), UnorderedKeyError> { - self.inner.insert_before(key, value) - } - - /// Removes the next element from the `BTreeMap`. - /// - /// The element that was removed is returned. The cursor position is - /// unchanged (before the removed element). - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn remove_next(&mut self) -> Option<(K, V)> { - self.inner.remove_next() - } - - /// Removes the precending element from the `BTreeMap`. - /// - /// The element that was removed is returned. The cursor position is - /// unchanged (after the removed element). - #[unstable(feature = "btree_cursors", issue = "107540")] - pub fn remove_prev(&mut self) -> Option<(K, V)> { - self.inner.remove_prev() - } -} - -/// Error type returned by [`CursorMut::insert_before`] and -/// [`CursorMut::insert_after`] if the key being inserted is not properly -/// ordered with regards to adjacent keys. -#[derive(Clone, PartialEq, Eq, Debug)] -#[unstable(feature = "btree_cursors", issue = "107540")] -pub struct UnorderedKeyError {} - -#[unstable(feature = "btree_cursors", issue = "107540")] -impl fmt::Display for UnorderedKeyError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "key is not properly ordered relative to neighbors") - } -} - -#[unstable(feature = "btree_cursors", issue = "107540")] -impl Error for UnorderedKeyError {} - -#[cfg(test)] -mod tests; diff --git a/library/alloc/src/collections/btree/map/entry.rs b/library/alloc/src/collections/btree/map/entry.rs deleted file mode 100644 index 66eb991c6d4b8..0000000000000 --- a/library/alloc/src/collections/btree/map/entry.rs +++ /dev/null @@ -1,570 +0,0 @@ -use core::fmt::{self, Debug}; -use core::marker::PhantomData; -use core::mem; - -use crate::alloc::{Allocator, Global}; - -use super::super::borrow::DormantMutRef; -use super::super::node::{marker, Handle, NodeRef}; -use super::BTreeMap; - -use Entry::*; - -/// A view into a single entry in a map, which may either be vacant or occupied. -/// -/// This `enum` is constructed from the [`entry`] method on [`BTreeMap`]. -/// -/// [`entry`]: BTreeMap::entry -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "BTreeEntry")] -pub enum Entry< - 'a, - K: 'a, - V: 'a, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator + Clone = Global, -> { - /// A vacant entry. - #[stable(feature = "rust1", since = "1.0.0")] - Vacant(#[stable(feature = "rust1", since = "1.0.0")] VacantEntry<'a, K, V, A>), - - /// An occupied entry. - #[stable(feature = "rust1", since = "1.0.0")] - Occupied(#[stable(feature = "rust1", since = "1.0.0")] OccupiedEntry<'a, K, V, A>), -} - -#[stable(feature = "debug_btree_map", since = "1.12.0")] -impl Debug for Entry<'_, K, V, A> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - match *self { - Vacant(ref v) => f.debug_tuple("Entry").field(v).finish(), - Occupied(ref o) => f.debug_tuple("Entry").field(o).finish(), - } - } -} - -/// A view into a vacant entry in a `BTreeMap`. -/// It is part of the [`Entry`] enum. -#[stable(feature = "rust1", since = "1.0.0")] -pub struct VacantEntry< - 'a, - K, - V, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator + Clone = Global, -> { - pub(super) key: K, - /// `None` for a (empty) map without root - pub(super) handle: Option, K, V, marker::Leaf>, marker::Edge>>, - pub(super) dormant_map: DormantMutRef<'a, BTreeMap>, - - /// The BTreeMap will outlive this IntoIter so we don't care about drop order for `alloc`. - pub(super) alloc: A, - - // Be invariant in `K` and `V` - pub(super) _marker: PhantomData<&'a mut (K, V)>, -} - -#[stable(feature = "debug_btree_map", since = "1.12.0")] -impl Debug for VacantEntry<'_, K, V, A> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("VacantEntry").field(self.key()).finish() - } -} - -/// A view into an occupied entry in a `BTreeMap`. -/// It is part of the [`Entry`] enum. -#[stable(feature = "rust1", since = "1.0.0")] -pub struct OccupiedEntry< - 'a, - K, - V, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator + Clone = Global, -> { - pub(super) handle: Handle, K, V, marker::LeafOrInternal>, marker::KV>, - pub(super) dormant_map: DormantMutRef<'a, BTreeMap>, - - /// The BTreeMap will outlive this IntoIter so we don't care about drop order for `alloc`. - pub(super) alloc: A, - - // Be invariant in `K` and `V` - pub(super) _marker: PhantomData<&'a mut (K, V)>, -} - -#[stable(feature = "debug_btree_map", since = "1.12.0")] -impl Debug for OccupiedEntry<'_, K, V, A> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("OccupiedEntry").field("key", self.key()).field("value", self.get()).finish() - } -} - -/// The error returned by [`try_insert`](BTreeMap::try_insert) when the key already exists. -/// -/// Contains the occupied entry, and the value that was not inserted. -#[unstable(feature = "map_try_insert", issue = "82766")] -pub struct OccupiedError<'a, K: 'a, V: 'a, A: Allocator + Clone = Global> { - /// The entry in the map that was already occupied. - pub entry: OccupiedEntry<'a, K, V, A>, - /// The value which was not inserted, because the entry was already occupied. - pub value: V, -} - -#[unstable(feature = "map_try_insert", issue = "82766")] -impl Debug for OccupiedError<'_, K, V, A> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("OccupiedError") - .field("key", self.entry.key()) - .field("old_value", self.entry.get()) - .field("new_value", &self.value) - .finish() - } -} - -#[unstable(feature = "map_try_insert", issue = "82766")] -impl<'a, K: Debug + Ord, V: Debug, A: Allocator + Clone> fmt::Display - for OccupiedError<'a, K, V, A> -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!( - f, - "failed to insert {:?}, key {:?} already exists with value {:?}", - self.value, - self.entry.key(), - self.entry.get(), - ) - } -} - -#[unstable(feature = "map_try_insert", issue = "82766")] -impl<'a, K: core::fmt::Debug + Ord, V: core::fmt::Debug> core::error::Error - for crate::collections::btree_map::OccupiedError<'a, K, V> -{ - #[allow(deprecated)] - fn description(&self) -> &str { - "key already exists" - } -} - -impl<'a, K: Ord, V, A: Allocator + Clone> Entry<'a, K, V, A> { - /// Ensures a value is in the entry by inserting the default if empty, and returns - /// a mutable reference to the value in the entry. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); - /// map.entry("poneyland").or_insert(12); - /// - /// assert_eq!(map["poneyland"], 12); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn or_insert(self, default: V) -> &'a mut V { - match self { - Occupied(entry) => entry.into_mut(), - Vacant(entry) => entry.insert(default), - } - } - - /// Ensures a value is in the entry by inserting the result of the default function if empty, - /// and returns a mutable reference to the value in the entry. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map: BTreeMap<&str, String> = BTreeMap::new(); - /// let s = "hoho".to_string(); - /// - /// map.entry("poneyland").or_insert_with(|| s); - /// - /// assert_eq!(map["poneyland"], "hoho".to_string()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn or_insert_with V>(self, default: F) -> &'a mut V { - match self { - Occupied(entry) => entry.into_mut(), - Vacant(entry) => entry.insert(default()), - } - } - - /// Ensures a value is in the entry by inserting, if empty, the result of the default function. - /// This method allows for generating key-derived values for insertion by providing the default - /// function a reference to the key that was moved during the `.entry(key)` method call. - /// - /// The reference to the moved key is provided so that cloning or copying the key is - /// unnecessary, unlike with `.or_insert_with(|| ... )`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); - /// - /// map.entry("poneyland").or_insert_with_key(|key| key.chars().count()); - /// - /// assert_eq!(map["poneyland"], 9); - /// ``` - #[inline] - #[stable(feature = "or_insert_with_key", since = "1.50.0")] - pub fn or_insert_with_key V>(self, default: F) -> &'a mut V { - match self { - Occupied(entry) => entry.into_mut(), - Vacant(entry) => { - let value = default(entry.key()); - entry.insert(value) - } - } - } - - /// Returns a reference to this entry's key. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); - /// assert_eq!(map.entry("poneyland").key(), &"poneyland"); - /// ``` - #[stable(feature = "map_entry_keys", since = "1.10.0")] - pub fn key(&self) -> &K { - match *self { - Occupied(ref entry) => entry.key(), - Vacant(ref entry) => entry.key(), - } - } - - /// Provides in-place mutable access to an occupied entry before any - /// potential inserts into the map. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); - /// - /// map.entry("poneyland") - /// .and_modify(|e| { *e += 1 }) - /// .or_insert(42); - /// assert_eq!(map["poneyland"], 42); - /// - /// map.entry("poneyland") - /// .and_modify(|e| { *e += 1 }) - /// .or_insert(42); - /// assert_eq!(map["poneyland"], 43); - /// ``` - #[stable(feature = "entry_and_modify", since = "1.26.0")] - pub fn and_modify(self, f: F) -> Self - where - F: FnOnce(&mut V), - { - match self { - Occupied(mut entry) => { - f(entry.get_mut()); - Occupied(entry) - } - Vacant(entry) => Vacant(entry), - } - } -} - -impl<'a, K: Ord, V: Default, A: Allocator + Clone> Entry<'a, K, V, A> { - #[stable(feature = "entry_or_default", since = "1.28.0")] - /// Ensures a value is in the entry by inserting the default value if empty, - /// and returns a mutable reference to the value in the entry. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map: BTreeMap<&str, Option> = BTreeMap::new(); - /// map.entry("poneyland").or_default(); - /// - /// assert_eq!(map["poneyland"], None); - /// ``` - pub fn or_default(self) -> &'a mut V { - match self { - Occupied(entry) => entry.into_mut(), - Vacant(entry) => entry.insert(Default::default()), - } - } -} - -impl<'a, K: Ord, V, A: Allocator + Clone> VacantEntry<'a, K, V, A> { - /// Gets a reference to the key that would be used when inserting a value - /// through the VacantEntry. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); - /// assert_eq!(map.entry("poneyland").key(), &"poneyland"); - /// ``` - #[stable(feature = "map_entry_keys", since = "1.10.0")] - pub fn key(&self) -> &K { - &self.key - } - - /// Take ownership of the key. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// use std::collections::btree_map::Entry; - /// - /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); - /// - /// if let Entry::Vacant(v) = map.entry("poneyland") { - /// v.into_key(); - /// } - /// ``` - #[stable(feature = "map_entry_recover_keys2", since = "1.12.0")] - pub fn into_key(self) -> K { - self.key - } - - /// Sets the value of the entry with the `VacantEntry`'s key, - /// and returns a mutable reference to it. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// use std::collections::btree_map::Entry; - /// - /// let mut map: BTreeMap<&str, u32> = BTreeMap::new(); - /// - /// if let Entry::Vacant(o) = map.entry("poneyland") { - /// o.insert(37); - /// } - /// assert_eq!(map["poneyland"], 37); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("push", "put")] - pub fn insert(mut self, value: V) -> &'a mut V { - let out_ptr = match self.handle { - None => { - // SAFETY: There is no tree yet so no reference to it exists. - let map = unsafe { self.dormant_map.awaken() }; - let mut root = NodeRef::new_leaf(self.alloc.clone()); - let val_ptr = root.borrow_mut().push(self.key, value); - map.root = Some(root.forget_type()); - map.length = 1; - val_ptr - } - Some(handle) => { - let new_handle = - handle.insert_recursing(self.key, value, self.alloc.clone(), |ins| { - drop(ins.left); - // SAFETY: Pushing a new root node doesn't invalidate - // handles to existing nodes. - let map = unsafe { self.dormant_map.reborrow() }; - let root = map.root.as_mut().unwrap(); // same as ins.left - root.push_internal_level(self.alloc).push(ins.kv.0, ins.kv.1, ins.right) - }); - - // Get the pointer to the value - let val_ptr = new_handle.into_val_mut(); - - // SAFETY: We have consumed self.handle. - let map = unsafe { self.dormant_map.awaken() }; - map.length += 1; - val_ptr - } - }; - - // Now that we have finished growing the tree using borrowed references, - // dereference the pointer to a part of it, that we picked up along the way. - unsafe { &mut *out_ptr } - } -} - -impl<'a, K: Ord, V, A: Allocator + Clone> OccupiedEntry<'a, K, V, A> { - /// Gets a reference to the key in the entry. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// - /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); - /// map.entry("poneyland").or_insert(12); - /// assert_eq!(map.entry("poneyland").key(), &"poneyland"); - /// ``` - #[must_use] - #[stable(feature = "map_entry_keys", since = "1.10.0")] - pub fn key(&self) -> &K { - self.handle.reborrow().into_kv().0 - } - - /// Take ownership of the key and value from the map. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// use std::collections::btree_map::Entry; - /// - /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); - /// map.entry("poneyland").or_insert(12); - /// - /// if let Entry::Occupied(o) = map.entry("poneyland") { - /// // We delete the entry from the map. - /// o.remove_entry(); - /// } - /// - /// // If now try to get the value, it will panic: - /// // println!("{}", map["poneyland"]); - /// ``` - #[stable(feature = "map_entry_recover_keys2", since = "1.12.0")] - pub fn remove_entry(self) -> (K, V) { - self.remove_kv() - } - - /// Gets a reference to the value in the entry. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// use std::collections::btree_map::Entry; - /// - /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); - /// map.entry("poneyland").or_insert(12); - /// - /// if let Entry::Occupied(o) = map.entry("poneyland") { - /// assert_eq!(o.get(), &12); - /// } - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn get(&self) -> &V { - self.handle.reborrow().into_kv().1 - } - - /// Gets a mutable reference to the value in the entry. - /// - /// If you need a reference to the `OccupiedEntry` that may outlive the - /// destruction of the `Entry` value, see [`into_mut`]. - /// - /// [`into_mut`]: OccupiedEntry::into_mut - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// use std::collections::btree_map::Entry; - /// - /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); - /// map.entry("poneyland").or_insert(12); - /// - /// assert_eq!(map["poneyland"], 12); - /// if let Entry::Occupied(mut o) = map.entry("poneyland") { - /// *o.get_mut() += 10; - /// assert_eq!(*o.get(), 22); - /// - /// // We can use the same Entry multiple times. - /// *o.get_mut() += 2; - /// } - /// assert_eq!(map["poneyland"], 24); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn get_mut(&mut self) -> &mut V { - self.handle.kv_mut().1 - } - - /// Converts the entry into a mutable reference to its value. - /// - /// If you need multiple references to the `OccupiedEntry`, see [`get_mut`]. - /// - /// [`get_mut`]: OccupiedEntry::get_mut - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// use std::collections::btree_map::Entry; - /// - /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); - /// map.entry("poneyland").or_insert(12); - /// - /// assert_eq!(map["poneyland"], 12); - /// if let Entry::Occupied(o) = map.entry("poneyland") { - /// *o.into_mut() += 10; - /// } - /// assert_eq!(map["poneyland"], 22); - /// ``` - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn into_mut(self) -> &'a mut V { - self.handle.into_val_mut() - } - - /// Sets the value of the entry with the `OccupiedEntry`'s key, - /// and returns the entry's old value. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// use std::collections::btree_map::Entry; - /// - /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); - /// map.entry("poneyland").or_insert(12); - /// - /// if let Entry::Occupied(mut o) = map.entry("poneyland") { - /// assert_eq!(o.insert(15), 12); - /// } - /// assert_eq!(map["poneyland"], 15); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("push", "put")] - pub fn insert(&mut self, value: V) -> V { - mem::replace(self.get_mut(), value) - } - - /// Takes the value of the entry out of the map, and returns it. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeMap; - /// use std::collections::btree_map::Entry; - /// - /// let mut map: BTreeMap<&str, usize> = BTreeMap::new(); - /// map.entry("poneyland").or_insert(12); - /// - /// if let Entry::Occupied(o) = map.entry("poneyland") { - /// assert_eq!(o.remove(), 12); - /// } - /// // If we try to get "poneyland"'s value, it'll panic: - /// // println!("{}", map["poneyland"]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("delete", "take")] - pub fn remove(self) -> V { - self.remove_kv().1 - } - - // Body of `remove_entry`, probably separate because the name reflects the returned pair. - pub(super) fn remove_kv(self) -> (K, V) { - let mut emptied_internal_root = false; - let (old_kv, _) = - self.handle.remove_kv_tracking(|| emptied_internal_root = true, self.alloc.clone()); - // SAFETY: we consumed the intermediate root borrow, `self.handle`. - let map = unsafe { self.dormant_map.awaken() }; - map.length -= 1; - if emptied_internal_root { - let root = map.root.as_mut().unwrap(); - root.pop_internal_level(self.alloc); - } - old_kv - } -} diff --git a/library/alloc/src/collections/btree/map/tests.rs b/library/alloc/src/collections/btree/map/tests.rs deleted file mode 100644 index 56620cf890db7..0000000000000 --- a/library/alloc/src/collections/btree/map/tests.rs +++ /dev/null @@ -1,2515 +0,0 @@ -use super::*; -use crate::boxed::Box; -use crate::fmt::Debug; -use crate::rc::Rc; -use crate::string::{String, ToString}; -use crate::testing::crash_test::{CrashTestDummy, Panic}; -use crate::testing::ord_chaos::{Cyclic3, Governed, Governor}; -use crate::testing::rng::DeterministicRng; -use core::assert_matches::assert_matches; -use std::iter; -use std::ops::Bound::{Excluded, Included, Unbounded}; -use std::panic::{catch_unwind, AssertUnwindSafe}; -use std::sync::atomic::{AtomicUsize, Ordering::SeqCst}; - -// Minimum number of elements to insert, to guarantee a tree with 2 levels, -// i.e., a tree who's root is an internal node at height 1, with edges to leaf nodes. -// It's not the minimum size: removing an element from such a tree does not always reduce height. -const MIN_INSERTS_HEIGHT_1: usize = node::CAPACITY + 1; - -// Minimum number of elements to insert in ascending order, to guarantee a tree with 3 levels, -// i.e., a tree who's root is an internal node at height 2, with edges to more internal nodes. -// It's not the minimum size: removing an element from such a tree does not always reduce height. -const MIN_INSERTS_HEIGHT_2: usize = 89; - -// Gathers all references from a mutable iterator and makes sure Miri notices if -// using them is dangerous. -fn test_all_refs<'a, T: 'a>(dummy: &mut T, iter: impl Iterator) { - // Gather all those references. - let mut refs: Vec<&mut T> = iter.collect(); - // Use them all. Twice, to be sure we got all interleavings. - for r in refs.iter_mut() { - mem::swap(dummy, r); - } - for r in refs { - mem::swap(dummy, r); - } -} - -impl BTreeMap { - // Panics if the map (or the code navigating it) is corrupted. - fn check_invariants(&self) { - if let Some(root) = &self.root { - let root_node = root.reborrow(); - - // Check the back pointers top-down, before we attempt to rely on - // more serious navigation code. - assert!(root_node.ascend().is_err()); - root_node.assert_back_pointers(); - - // Check consistency of `length` with what navigation code encounters. - assert_eq!(self.length, root_node.calc_length()); - - // Lastly, check the invariant causing the least harm. - root_node.assert_min_len(if root_node.height() > 0 { 1 } else { 0 }); - } else { - assert_eq!(self.length, 0); - } - - // Check that `assert_strictly_ascending` will encounter all keys. - assert_eq!(self.length, self.keys().count()); - } - - // Panics if the map is corrupted or if the keys are not in strictly - // ascending order, in the current opinion of the `Ord` implementation. - // If the `Ord` implementation violates transitivity, this method does not - // guarantee that all keys are unique, just that adjacent keys are unique. - fn check(&self) - where - K: Debug + Ord, - { - self.check_invariants(); - self.assert_strictly_ascending(); - } - - // Returns the height of the root, if any. - fn height(&self) -> Option { - self.root.as_ref().map(node::Root::height) - } - - fn dump_keys(&self) -> String - where - K: Debug, - { - if let Some(root) = self.root.as_ref() { - root.reborrow().dump_keys() - } else { - String::from("not yet allocated") - } - } - - // Panics if the keys are not in strictly ascending order. - fn assert_strictly_ascending(&self) - where - K: Debug + Ord, - { - let mut keys = self.keys(); - if let Some(mut previous) = keys.next() { - for next in keys { - assert!(previous < next, "{:?} >= {:?}", previous, next); - previous = next; - } - } - } - - // Transform the tree to minimize wasted space, obtaining fewer nodes that - // are mostly filled up to their capacity. The same compact tree could have - // been obtained by inserting keys in a shrewd order. - fn compact(&mut self) - where - K: Ord, - { - let iter = mem::take(self).into_iter(); - if !iter.is_empty() { - self.root.insert(Root::new(*self.alloc)).bulk_push(iter, &mut self.length, *self.alloc); - } - } -} - -impl<'a, K: 'a, V: 'a> NodeRef, K, V, marker::LeafOrInternal> { - fn assert_min_len(self, min_len: usize) { - assert!(self.len() >= min_len, "node len {} < {}", self.len(), min_len); - if let node::ForceResult::Internal(node) = self.force() { - for idx in 0..=node.len() { - let edge = unsafe { Handle::new_edge(node, idx) }; - edge.descend().assert_min_len(MIN_LEN); - } - } - } -} - -// Tests our value of MIN_INSERTS_HEIGHT_2. Failure may mean you just need to -// adapt that value to match a change in node::CAPACITY or the choices made -// during insertion, otherwise other test cases may fail or be less useful. -#[test] -fn test_levels() { - let mut map = BTreeMap::new(); - map.check(); - assert_eq!(map.height(), None); - assert_eq!(map.len(), 0); - - map.insert(0, ()); - while map.height() == Some(0) { - let last_key = *map.last_key_value().unwrap().0; - map.insert(last_key + 1, ()); - } - map.check(); - // Structure: - // - 1 element in internal root node with 2 children - // - 6 elements in left leaf child - // - 5 elements in right leaf child - assert_eq!(map.height(), Some(1)); - assert_eq!(map.len(), MIN_INSERTS_HEIGHT_1, "{}", map.dump_keys()); - - while map.height() == Some(1) { - let last_key = *map.last_key_value().unwrap().0; - map.insert(last_key + 1, ()); - } - map.check(); - // Structure: - // - 1 element in internal root node with 2 children - // - 6 elements in left internal child with 7 grandchildren - // - 42 elements in left child's 7 grandchildren with 6 elements each - // - 5 elements in right internal child with 6 grandchildren - // - 30 elements in right child's 5 first grandchildren with 6 elements each - // - 5 elements in right child's last grandchild - assert_eq!(map.height(), Some(2)); - assert_eq!(map.len(), MIN_INSERTS_HEIGHT_2, "{}", map.dump_keys()); -} - -// Ensures the testing infrastructure usually notices order violations. -#[test] -#[should_panic] -fn test_check_ord_chaos() { - let gov = Governor::new(); - let map = BTreeMap::from([(Governed(1, &gov), ()), (Governed(2, &gov), ())]); - gov.flip(); - map.check(); -} - -// Ensures the testing infrastructure doesn't always mind order violations. -#[test] -fn test_check_invariants_ord_chaos() { - let gov = Governor::new(); - let map = BTreeMap::from([(Governed(1, &gov), ()), (Governed(2, &gov), ())]); - gov.flip(); - map.check_invariants(); -} - -#[test] -fn test_basic_large() { - let mut map = BTreeMap::new(); - // Miri is too slow - let size = if cfg!(miri) { MIN_INSERTS_HEIGHT_2 } else { 10000 }; - let size = size + (size % 2); // round up to even number - assert_eq!(map.len(), 0); - - for i in 0..size { - assert_eq!(map.insert(i, 10 * i), None); - assert_eq!(map.len(), i + 1); - } - - assert_eq!(map.first_key_value(), Some((&0, &0))); - assert_eq!(map.last_key_value(), Some((&(size - 1), &(10 * (size - 1))))); - assert_eq!(map.first_entry().unwrap().key(), &0); - assert_eq!(map.last_entry().unwrap().key(), &(size - 1)); - - for i in 0..size { - assert_eq!(map.get(&i).unwrap(), &(i * 10)); - } - - for i in size..size * 2 { - assert_eq!(map.get(&i), None); - } - - for i in 0..size { - assert_eq!(map.insert(i, 100 * i), Some(10 * i)); - assert_eq!(map.len(), size); - } - - for i in 0..size { - assert_eq!(map.get(&i).unwrap(), &(i * 100)); - } - - for i in 0..size / 2 { - assert_eq!(map.remove(&(i * 2)), Some(i * 200)); - assert_eq!(map.len(), size - i - 1); - } - - for i in 0..size / 2 { - assert_eq!(map.get(&(2 * i)), None); - assert_eq!(map.get(&(2 * i + 1)).unwrap(), &(i * 200 + 100)); - } - - for i in 0..size / 2 { - assert_eq!(map.remove(&(2 * i)), None); - assert_eq!(map.remove(&(2 * i + 1)), Some(i * 200 + 100)); - assert_eq!(map.len(), size / 2 - i - 1); - } - map.check(); -} - -#[test] -fn test_basic_small() { - let mut map = BTreeMap::new(); - // Empty, root is absent (None): - assert_eq!(map.remove(&1), None); - assert_eq!(map.len(), 0); - assert_eq!(map.get(&1), None); - assert_eq!(map.get_mut(&1), None); - assert_eq!(map.first_key_value(), None); - assert_eq!(map.last_key_value(), None); - assert_eq!(map.keys().count(), 0); - assert_eq!(map.values().count(), 0); - assert_eq!(map.range(..).next(), None); - assert_eq!(map.range(..1).next(), None); - assert_eq!(map.range(1..).next(), None); - assert_eq!(map.range(1..=1).next(), None); - assert_eq!(map.range(1..2).next(), None); - assert_eq!(map.height(), None); - assert_eq!(map.insert(1, 1), None); - assert_eq!(map.height(), Some(0)); - map.check(); - - // 1 key-value pair: - assert_eq!(map.len(), 1); - assert_eq!(map.get(&1), Some(&1)); - assert_eq!(map.get_mut(&1), Some(&mut 1)); - assert_eq!(map.first_key_value(), Some((&1, &1))); - assert_eq!(map.last_key_value(), Some((&1, &1))); - assert_eq!(map.keys().collect::>(), vec![&1]); - assert_eq!(map.values().collect::>(), vec![&1]); - assert_eq!(map.insert(1, 2), Some(1)); - assert_eq!(map.len(), 1); - assert_eq!(map.get(&1), Some(&2)); - assert_eq!(map.get_mut(&1), Some(&mut 2)); - assert_eq!(map.first_key_value(), Some((&1, &2))); - assert_eq!(map.last_key_value(), Some((&1, &2))); - assert_eq!(map.keys().collect::>(), vec![&1]); - assert_eq!(map.values().collect::>(), vec![&2]); - assert_eq!(map.insert(2, 4), None); - assert_eq!(map.height(), Some(0)); - map.check(); - - // 2 key-value pairs: - assert_eq!(map.len(), 2); - assert_eq!(map.get(&2), Some(&4)); - assert_eq!(map.get_mut(&2), Some(&mut 4)); - assert_eq!(map.first_key_value(), Some((&1, &2))); - assert_eq!(map.last_key_value(), Some((&2, &4))); - assert_eq!(map.keys().collect::>(), vec![&1, &2]); - assert_eq!(map.values().collect::>(), vec![&2, &4]); - assert_eq!(map.remove(&1), Some(2)); - assert_eq!(map.height(), Some(0)); - map.check(); - - // 1 key-value pair: - assert_eq!(map.len(), 1); - assert_eq!(map.get(&1), None); - assert_eq!(map.get_mut(&1), None); - assert_eq!(map.get(&2), Some(&4)); - assert_eq!(map.get_mut(&2), Some(&mut 4)); - assert_eq!(map.first_key_value(), Some((&2, &4))); - assert_eq!(map.last_key_value(), Some((&2, &4))); - assert_eq!(map.keys().collect::>(), vec![&2]); - assert_eq!(map.values().collect::>(), vec![&4]); - assert_eq!(map.remove(&2), Some(4)); - assert_eq!(map.height(), Some(0)); - map.check(); - - // Empty but root is owned (Some(...)): - assert_eq!(map.len(), 0); - assert_eq!(map.get(&1), None); - assert_eq!(map.get_mut(&1), None); - assert_eq!(map.first_key_value(), None); - assert_eq!(map.last_key_value(), None); - assert_eq!(map.keys().count(), 0); - assert_eq!(map.values().count(), 0); - assert_eq!(map.range(..).next(), None); - assert_eq!(map.range(..1).next(), None); - assert_eq!(map.range(1..).next(), None); - assert_eq!(map.range(1..=1).next(), None); - assert_eq!(map.range(1..2).next(), None); - assert_eq!(map.remove(&1), None); - assert_eq!(map.height(), Some(0)); - map.check(); -} - -#[test] -fn test_iter() { - // Miri is too slow - let size = if cfg!(miri) { 200 } else { 10000 }; - let mut map = BTreeMap::from_iter((0..size).map(|i| (i, i))); - - fn test(size: usize, mut iter: T) - where - T: Iterator, - { - for i in 0..size { - assert_eq!(iter.size_hint(), (size - i, Some(size - i))); - assert_eq!(iter.next().unwrap(), (i, i)); - } - assert_eq!(iter.size_hint(), (0, Some(0))); - assert_eq!(iter.next(), None); - } - test(size, map.iter().map(|(&k, &v)| (k, v))); - test(size, map.iter_mut().map(|(&k, &mut v)| (k, v))); - test(size, map.into_iter()); -} - -#[test] -fn test_iter_rev() { - // Miri is too slow - let size = if cfg!(miri) { 200 } else { 10000 }; - let mut map = BTreeMap::from_iter((0..size).map(|i| (i, i))); - - fn test(size: usize, mut iter: T) - where - T: Iterator, - { - for i in 0..size { - assert_eq!(iter.size_hint(), (size - i, Some(size - i))); - assert_eq!(iter.next().unwrap(), (size - i - 1, size - i - 1)); - } - assert_eq!(iter.size_hint(), (0, Some(0))); - assert_eq!(iter.next(), None); - } - test(size, map.iter().rev().map(|(&k, &v)| (k, v))); - test(size, map.iter_mut().rev().map(|(&k, &mut v)| (k, v))); - test(size, map.into_iter().rev()); -} - -// Specifically tests iter_mut's ability to mutate the value of pairs in-line. -fn do_test_iter_mut_mutation(size: usize) -where - T: Copy + Debug + Ord + TryFrom, - >::Error: Debug, -{ - let zero = T::try_from(0).unwrap(); - let mut map = BTreeMap::from_iter((0..size).map(|i| (T::try_from(i).unwrap(), zero))); - - // Forward and backward iteration sees enough pairs (also tested elsewhere) - assert_eq!(map.iter_mut().count(), size); - assert_eq!(map.iter_mut().rev().count(), size); - - // Iterate forwards, trying to mutate to unique values - for (i, (k, v)) in map.iter_mut().enumerate() { - assert_eq!(*k, T::try_from(i).unwrap()); - assert_eq!(*v, zero); - *v = T::try_from(i + 1).unwrap(); - } - - // Iterate backwards, checking that mutations succeeded and trying to mutate again - for (i, (k, v)) in map.iter_mut().rev().enumerate() { - assert_eq!(*k, T::try_from(size - i - 1).unwrap()); - assert_eq!(*v, T::try_from(size - i).unwrap()); - *v = T::try_from(2 * size - i).unwrap(); - } - - // Check that backward mutations succeeded - for (i, (k, v)) in map.iter_mut().enumerate() { - assert_eq!(*k, T::try_from(i).unwrap()); - assert_eq!(*v, T::try_from(size + i + 1).unwrap()); - } - map.check(); -} - -#[derive(Clone, Copy, Debug, Eq, PartialEq, PartialOrd, Ord)] -#[repr(align(32))] -struct Align32(usize); - -impl TryFrom for Align32 { - type Error = (); - - fn try_from(s: usize) -> Result { - Ok(Align32(s)) - } -} - -#[test] -fn test_iter_mut_mutation() { - // Check many alignments and trees with roots at various heights. - do_test_iter_mut_mutation::(0); - do_test_iter_mut_mutation::(1); - do_test_iter_mut_mutation::(MIN_INSERTS_HEIGHT_1); - do_test_iter_mut_mutation::(MIN_INSERTS_HEIGHT_2); - do_test_iter_mut_mutation::(1); - do_test_iter_mut_mutation::(MIN_INSERTS_HEIGHT_1); - do_test_iter_mut_mutation::(MIN_INSERTS_HEIGHT_2); - do_test_iter_mut_mutation::(1); - do_test_iter_mut_mutation::(MIN_INSERTS_HEIGHT_1); - do_test_iter_mut_mutation::(MIN_INSERTS_HEIGHT_2); - do_test_iter_mut_mutation::(1); - do_test_iter_mut_mutation::(MIN_INSERTS_HEIGHT_1); - do_test_iter_mut_mutation::(MIN_INSERTS_HEIGHT_2); - do_test_iter_mut_mutation::(1); - do_test_iter_mut_mutation::(MIN_INSERTS_HEIGHT_1); - do_test_iter_mut_mutation::(MIN_INSERTS_HEIGHT_2); - do_test_iter_mut_mutation::(1); - do_test_iter_mut_mutation::(MIN_INSERTS_HEIGHT_1); - do_test_iter_mut_mutation::(MIN_INSERTS_HEIGHT_2); -} - -#[test] -fn test_values_mut() { - let mut a = BTreeMap::from_iter((0..MIN_INSERTS_HEIGHT_2).map(|i| (i, i))); - test_all_refs(&mut 13, a.values_mut()); - a.check(); -} - -#[test] -fn test_values_mut_mutation() { - let mut a = BTreeMap::new(); - a.insert(1, String::from("hello")); - a.insert(2, String::from("goodbye")); - - for value in a.values_mut() { - value.push_str("!"); - } - - let values = Vec::from_iter(a.values().cloned()); - assert_eq!(values, [String::from("hello!"), String::from("goodbye!")]); - a.check(); -} - -#[test] -fn test_iter_entering_root_twice() { - let mut map = BTreeMap::from([(0, 0), (1, 1)]); - let mut it = map.iter_mut(); - let front = it.next().unwrap(); - let back = it.next_back().unwrap(); - assert_eq!(front, (&0, &mut 0)); - assert_eq!(back, (&1, &mut 1)); - *front.1 = 24; - *back.1 = 42; - assert_eq!(front, (&0, &mut 24)); - assert_eq!(back, (&1, &mut 42)); - assert_eq!(it.next(), None); - assert_eq!(it.next_back(), None); - map.check(); -} - -#[test] -fn test_iter_descending_to_same_node_twice() { - let mut map = BTreeMap::from_iter((0..MIN_INSERTS_HEIGHT_1).map(|i| (i, i))); - let mut it = map.iter_mut(); - // Descend into first child. - let front = it.next().unwrap(); - // Descend into first child again, after running through second child. - while it.next_back().is_some() {} - // Check immutable access. - assert_eq!(front, (&0, &mut 0)); - // Perform mutable access. - *front.1 = 42; - map.check(); -} - -#[test] -fn test_iter_mixed() { - // Miri is too slow - let size = if cfg!(miri) { 200 } else { 10000 }; - - let mut map = BTreeMap::from_iter((0..size).map(|i| (i, i))); - - fn test(size: usize, mut iter: T) - where - T: Iterator + DoubleEndedIterator, - { - for i in 0..size / 4 { - assert_eq!(iter.size_hint(), (size - i * 2, Some(size - i * 2))); - assert_eq!(iter.next().unwrap(), (i, i)); - assert_eq!(iter.next_back().unwrap(), (size - i - 1, size - i - 1)); - } - for i in size / 4..size * 3 / 4 { - assert_eq!(iter.size_hint(), (size * 3 / 4 - i, Some(size * 3 / 4 - i))); - assert_eq!(iter.next().unwrap(), (i, i)); - } - assert_eq!(iter.size_hint(), (0, Some(0))); - assert_eq!(iter.next(), None); - } - test(size, map.iter().map(|(&k, &v)| (k, v))); - test(size, map.iter_mut().map(|(&k, &mut v)| (k, v))); - test(size, map.into_iter()); -} - -#[test] -fn test_iter_min_max() { - let mut a = BTreeMap::new(); - assert_eq!(a.iter().min(), None); - assert_eq!(a.iter().max(), None); - assert_eq!(a.iter_mut().min(), None); - assert_eq!(a.iter_mut().max(), None); - assert_eq!(a.range(..).min(), None); - assert_eq!(a.range(..).max(), None); - assert_eq!(a.range_mut(..).min(), None); - assert_eq!(a.range_mut(..).max(), None); - assert_eq!(a.keys().min(), None); - assert_eq!(a.keys().max(), None); - assert_eq!(a.values().min(), None); - assert_eq!(a.values().max(), None); - assert_eq!(a.values_mut().min(), None); - assert_eq!(a.values_mut().max(), None); - a.insert(1, 42); - a.insert(2, 24); - assert_eq!(a.iter().min(), Some((&1, &42))); - assert_eq!(a.iter().max(), Some((&2, &24))); - assert_eq!(a.iter_mut().min(), Some((&1, &mut 42))); - assert_eq!(a.iter_mut().max(), Some((&2, &mut 24))); - assert_eq!(a.range(..).min(), Some((&1, &42))); - assert_eq!(a.range(..).max(), Some((&2, &24))); - assert_eq!(a.range_mut(..).min(), Some((&1, &mut 42))); - assert_eq!(a.range_mut(..).max(), Some((&2, &mut 24))); - assert_eq!(a.keys().min(), Some(&1)); - assert_eq!(a.keys().max(), Some(&2)); - assert_eq!(a.values().min(), Some(&24)); - assert_eq!(a.values().max(), Some(&42)); - assert_eq!(a.values_mut().min(), Some(&mut 24)); - assert_eq!(a.values_mut().max(), Some(&mut 42)); - a.check(); -} - -fn range_keys(map: &BTreeMap, range: impl RangeBounds) -> Vec { - Vec::from_iter(map.range(range).map(|(&k, &v)| { - assert_eq!(k, v); - k - })) -} - -#[test] -fn test_range_small() { - let size = 4; - - let all = Vec::from_iter(1..=size); - let (first, last) = (vec![all[0]], vec![all[size as usize - 1]]); - let map = BTreeMap::from_iter(all.iter().copied().map(|i| (i, i))); - - assert_eq!(range_keys(&map, (Excluded(0), Excluded(size + 1))), all); - assert_eq!(range_keys(&map, (Excluded(0), Included(size + 1))), all); - assert_eq!(range_keys(&map, (Excluded(0), Included(size))), all); - assert_eq!(range_keys(&map, (Excluded(0), Unbounded)), all); - assert_eq!(range_keys(&map, (Included(0), Excluded(size + 1))), all); - assert_eq!(range_keys(&map, (Included(0), Included(size + 1))), all); - assert_eq!(range_keys(&map, (Included(0), Included(size))), all); - assert_eq!(range_keys(&map, (Included(0), Unbounded)), all); - assert_eq!(range_keys(&map, (Included(1), Excluded(size + 1))), all); - assert_eq!(range_keys(&map, (Included(1), Included(size + 1))), all); - assert_eq!(range_keys(&map, (Included(1), Included(size))), all); - assert_eq!(range_keys(&map, (Included(1), Unbounded)), all); - assert_eq!(range_keys(&map, (Unbounded, Excluded(size + 1))), all); - assert_eq!(range_keys(&map, (Unbounded, Included(size + 1))), all); - assert_eq!(range_keys(&map, (Unbounded, Included(size))), all); - assert_eq!(range_keys(&map, ..), all); - - assert_eq!(range_keys(&map, (Excluded(0), Excluded(1))), vec![]); - assert_eq!(range_keys(&map, (Excluded(0), Included(0))), vec![]); - assert_eq!(range_keys(&map, (Included(0), Included(0))), vec![]); - assert_eq!(range_keys(&map, (Included(0), Excluded(1))), vec![]); - assert_eq!(range_keys(&map, (Unbounded, Excluded(1))), vec![]); - assert_eq!(range_keys(&map, (Unbounded, Included(0))), vec![]); - assert_eq!(range_keys(&map, (Excluded(0), Excluded(2))), first); - assert_eq!(range_keys(&map, (Excluded(0), Included(1))), first); - assert_eq!(range_keys(&map, (Included(0), Excluded(2))), first); - assert_eq!(range_keys(&map, (Included(0), Included(1))), first); - assert_eq!(range_keys(&map, (Included(1), Excluded(2))), first); - assert_eq!(range_keys(&map, (Included(1), Included(1))), first); - assert_eq!(range_keys(&map, (Unbounded, Excluded(2))), first); - assert_eq!(range_keys(&map, (Unbounded, Included(1))), first); - assert_eq!(range_keys(&map, (Excluded(size - 1), Excluded(size + 1))), last); - assert_eq!(range_keys(&map, (Excluded(size - 1), Included(size + 1))), last); - assert_eq!(range_keys(&map, (Excluded(size - 1), Included(size))), last); - assert_eq!(range_keys(&map, (Excluded(size - 1), Unbounded)), last); - assert_eq!(range_keys(&map, (Included(size), Excluded(size + 1))), last); - assert_eq!(range_keys(&map, (Included(size), Included(size + 1))), last); - assert_eq!(range_keys(&map, (Included(size), Included(size))), last); - assert_eq!(range_keys(&map, (Included(size), Unbounded)), last); - assert_eq!(range_keys(&map, (Excluded(size), Excluded(size + 1))), vec![]); - assert_eq!(range_keys(&map, (Excluded(size), Included(size))), vec![]); - assert_eq!(range_keys(&map, (Excluded(size), Unbounded)), vec![]); - assert_eq!(range_keys(&map, (Included(size + 1), Excluded(size + 1))), vec![]); - assert_eq!(range_keys(&map, (Included(size + 1), Included(size + 1))), vec![]); - assert_eq!(range_keys(&map, (Included(size + 1), Unbounded)), vec![]); - - assert_eq!(range_keys(&map, ..3), vec![1, 2]); - assert_eq!(range_keys(&map, 3..), vec![3, 4]); - assert_eq!(range_keys(&map, 2..=3), vec![2, 3]); -} - -#[test] -fn test_range_height_1() { - // Tests tree with a root and 2 leaves. We test around the middle of the - // keys because one of those is the single key in the root node. - let map = BTreeMap::from_iter((0..MIN_INSERTS_HEIGHT_1 as i32).map(|i| (i, i))); - let middle = MIN_INSERTS_HEIGHT_1 as i32 / 2; - for root in middle - 2..=middle + 2 { - assert_eq!(range_keys(&map, (Excluded(root), Excluded(root + 1))), vec![]); - assert_eq!(range_keys(&map, (Excluded(root), Included(root + 1))), vec![root + 1]); - assert_eq!(range_keys(&map, (Included(root), Excluded(root + 1))), vec![root]); - assert_eq!(range_keys(&map, (Included(root), Included(root + 1))), vec![root, root + 1]); - - assert_eq!(range_keys(&map, (Excluded(root - 1), Excluded(root))), vec![]); - assert_eq!(range_keys(&map, (Included(root - 1), Excluded(root))), vec![root - 1]); - assert_eq!(range_keys(&map, (Excluded(root - 1), Included(root))), vec![root]); - assert_eq!(range_keys(&map, (Included(root - 1), Included(root))), vec![root - 1, root]); - } -} - -#[test] -fn test_range_large() { - let size = 200; - - let all = Vec::from_iter(1..=size); - let (first, last) = (vec![all[0]], vec![all[size as usize - 1]]); - let map = BTreeMap::from_iter(all.iter().copied().map(|i| (i, i))); - - assert_eq!(range_keys(&map, (Excluded(0), Excluded(size + 1))), all); - assert_eq!(range_keys(&map, (Excluded(0), Included(size + 1))), all); - assert_eq!(range_keys(&map, (Excluded(0), Included(size))), all); - assert_eq!(range_keys(&map, (Excluded(0), Unbounded)), all); - assert_eq!(range_keys(&map, (Included(0), Excluded(size + 1))), all); - assert_eq!(range_keys(&map, (Included(0), Included(size + 1))), all); - assert_eq!(range_keys(&map, (Included(0), Included(size))), all); - assert_eq!(range_keys(&map, (Included(0), Unbounded)), all); - assert_eq!(range_keys(&map, (Included(1), Excluded(size + 1))), all); - assert_eq!(range_keys(&map, (Included(1), Included(size + 1))), all); - assert_eq!(range_keys(&map, (Included(1), Included(size))), all); - assert_eq!(range_keys(&map, (Included(1), Unbounded)), all); - assert_eq!(range_keys(&map, (Unbounded, Excluded(size + 1))), all); - assert_eq!(range_keys(&map, (Unbounded, Included(size + 1))), all); - assert_eq!(range_keys(&map, (Unbounded, Included(size))), all); - assert_eq!(range_keys(&map, ..), all); - - assert_eq!(range_keys(&map, (Excluded(0), Excluded(1))), vec![]); - assert_eq!(range_keys(&map, (Excluded(0), Included(0))), vec![]); - assert_eq!(range_keys(&map, (Included(0), Included(0))), vec![]); - assert_eq!(range_keys(&map, (Included(0), Excluded(1))), vec![]); - assert_eq!(range_keys(&map, (Unbounded, Excluded(1))), vec![]); - assert_eq!(range_keys(&map, (Unbounded, Included(0))), vec![]); - assert_eq!(range_keys(&map, (Excluded(0), Excluded(2))), first); - assert_eq!(range_keys(&map, (Excluded(0), Included(1))), first); - assert_eq!(range_keys(&map, (Included(0), Excluded(2))), first); - assert_eq!(range_keys(&map, (Included(0), Included(1))), first); - assert_eq!(range_keys(&map, (Included(1), Excluded(2))), first); - assert_eq!(range_keys(&map, (Included(1), Included(1))), first); - assert_eq!(range_keys(&map, (Unbounded, Excluded(2))), first); - assert_eq!(range_keys(&map, (Unbounded, Included(1))), first); - assert_eq!(range_keys(&map, (Excluded(size - 1), Excluded(size + 1))), last); - assert_eq!(range_keys(&map, (Excluded(size - 1), Included(size + 1))), last); - assert_eq!(range_keys(&map, (Excluded(size - 1), Included(size))), last); - assert_eq!(range_keys(&map, (Excluded(size - 1), Unbounded)), last); - assert_eq!(range_keys(&map, (Included(size), Excluded(size + 1))), last); - assert_eq!(range_keys(&map, (Included(size), Included(size + 1))), last); - assert_eq!(range_keys(&map, (Included(size), Included(size))), last); - assert_eq!(range_keys(&map, (Included(size), Unbounded)), last); - assert_eq!(range_keys(&map, (Excluded(size), Excluded(size + 1))), vec![]); - assert_eq!(range_keys(&map, (Excluded(size), Included(size))), vec![]); - assert_eq!(range_keys(&map, (Excluded(size), Unbounded)), vec![]); - assert_eq!(range_keys(&map, (Included(size + 1), Excluded(size + 1))), vec![]); - assert_eq!(range_keys(&map, (Included(size + 1), Included(size + 1))), vec![]); - assert_eq!(range_keys(&map, (Included(size + 1), Unbounded)), vec![]); - - fn check<'a, L, R>(lhs: L, rhs: R) - where - L: IntoIterator, - R: IntoIterator, - { - assert_eq!(Vec::from_iter(lhs), Vec::from_iter(rhs)); - } - - check(map.range(..=100), map.range(..101)); - check(map.range(5..=8), vec![(&5, &5), (&6, &6), (&7, &7), (&8, &8)]); - check(map.range(-1..=2), vec![(&1, &1), (&2, &2)]); -} - -#[test] -fn test_range_inclusive_max_value() { - let max = usize::MAX; - let map = BTreeMap::from([(max, 0)]); - assert_eq!(Vec::from_iter(map.range(max..=max)), &[(&max, &0)]); -} - -#[test] -fn test_range_equal_empty_cases() { - let map = BTreeMap::from_iter((0..5).map(|i| (i, i))); - assert_eq!(map.range((Included(2), Excluded(2))).next(), None); - assert_eq!(map.range((Excluded(2), Included(2))).next(), None); -} - -#[test] -#[should_panic] -fn test_range_equal_excluded() { - let map = BTreeMap::from_iter((0..5).map(|i| (i, i))); - let _ = map.range((Excluded(2), Excluded(2))); -} - -#[test] -#[should_panic] -fn test_range_backwards_1() { - let map = BTreeMap::from_iter((0..5).map(|i| (i, i))); - let _ = map.range((Included(3), Included(2))); -} - -#[test] -#[should_panic] -fn test_range_backwards_2() { - let map = BTreeMap::from_iter((0..5).map(|i| (i, i))); - let _ = map.range((Included(3), Excluded(2))); -} - -#[test] -#[should_panic] -fn test_range_backwards_3() { - let map = BTreeMap::from_iter((0..5).map(|i| (i, i))); - let _ = map.range((Excluded(3), Included(2))); -} - -#[test] -#[should_panic] -fn test_range_backwards_4() { - let map = BTreeMap::from_iter((0..5).map(|i| (i, i))); - let _ = map.range((Excluded(3), Excluded(2))); -} - -#[test] -fn test_range_finding_ill_order_in_map() { - let mut map = BTreeMap::new(); - map.insert(Cyclic3::B, ()); - // Lacking static_assert, call `range` conditionally, to emphasise that - // we cause a different panic than `test_range_backwards_1` does. - // A more refined `should_panic` would be welcome. - if Cyclic3::C < Cyclic3::A { - let _ = map.range(Cyclic3::C..=Cyclic3::A); - } -} - -#[test] -fn test_range_finding_ill_order_in_range_ord() { - // Has proper order the first time asked, then flips around. - struct EvilTwin(i32); - - impl PartialOrd for EvilTwin { - fn partial_cmp(&self, other: &Self) -> Option { - Some(self.cmp(other)) - } - } - - static COMPARES: AtomicUsize = AtomicUsize::new(0); - impl Ord for EvilTwin { - fn cmp(&self, other: &Self) -> Ordering { - let ord = self.0.cmp(&other.0); - if COMPARES.fetch_add(1, SeqCst) > 0 { ord.reverse() } else { ord } - } - } - - impl PartialEq for EvilTwin { - fn eq(&self, other: &Self) -> bool { - self.0.eq(&other.0) - } - } - - impl Eq for EvilTwin {} - - #[derive(PartialEq, Eq, PartialOrd, Ord)] - struct CompositeKey(i32, EvilTwin); - - impl Borrow for CompositeKey { - fn borrow(&self) -> &EvilTwin { - &self.1 - } - } - - let map = BTreeMap::from_iter((0..12).map(|i| (CompositeKey(i, EvilTwin(i)), ()))); - let _ = map.range(EvilTwin(5)..=EvilTwin(7)); -} - -#[test] -fn test_range_1000() { - // Miri is too slow - let size = if cfg!(miri) { MIN_INSERTS_HEIGHT_2 as u32 } else { 1000 }; - let map = BTreeMap::from_iter((0..size).map(|i| (i, i))); - - fn test(map: &BTreeMap, size: u32, min: Bound<&u32>, max: Bound<&u32>) { - let mut kvs = map.range((min, max)).map(|(&k, &v)| (k, v)); - let mut pairs = (0..size).map(|i| (i, i)); - - for (kv, pair) in kvs.by_ref().zip(pairs.by_ref()) { - assert_eq!(kv, pair); - } - assert_eq!(kvs.next(), None); - assert_eq!(pairs.next(), None); - } - test(&map, size, Included(&0), Excluded(&size)); - test(&map, size, Unbounded, Excluded(&size)); - test(&map, size, Included(&0), Included(&(size - 1))); - test(&map, size, Unbounded, Included(&(size - 1))); - test(&map, size, Included(&0), Unbounded); - test(&map, size, Unbounded, Unbounded); -} - -#[test] -fn test_range_borrowed_key() { - let mut map = BTreeMap::new(); - map.insert("aardvark".to_string(), 1); - map.insert("baboon".to_string(), 2); - map.insert("coyote".to_string(), 3); - map.insert("dingo".to_string(), 4); - // NOTE: would like to use simply "b".."d" here... - let mut iter = map.range::((Included("b"), Excluded("d"))); - assert_eq!(iter.next(), Some((&"baboon".to_string(), &2))); - assert_eq!(iter.next(), Some((&"coyote".to_string(), &3))); - assert_eq!(iter.next(), None); -} - -#[test] -fn test_range() { - let size = 200; - // Miri is too slow - let step = if cfg!(miri) { 66 } else { 1 }; - let map = BTreeMap::from_iter((0..size).map(|i| (i, i))); - - for i in (0..size).step_by(step) { - for j in (i..size).step_by(step) { - let mut kvs = map.range((Included(&i), Included(&j))).map(|(&k, &v)| (k, v)); - let mut pairs = (i..=j).map(|i| (i, i)); - - for (kv, pair) in kvs.by_ref().zip(pairs.by_ref()) { - assert_eq!(kv, pair); - } - assert_eq!(kvs.next(), None); - assert_eq!(pairs.next(), None); - } - } -} - -#[test] -fn test_range_mut() { - let size = 200; - // Miri is too slow - let step = if cfg!(miri) { 66 } else { 1 }; - let mut map = BTreeMap::from_iter((0..size).map(|i| (i, i))); - - for i in (0..size).step_by(step) { - for j in (i..size).step_by(step) { - let mut kvs = map.range_mut((Included(&i), Included(&j))).map(|(&k, &mut v)| (k, v)); - let mut pairs = (i..=j).map(|i| (i, i)); - - for (kv, pair) in kvs.by_ref().zip(pairs.by_ref()) { - assert_eq!(kv, pair); - } - assert_eq!(kvs.next(), None); - assert_eq!(pairs.next(), None); - } - } - map.check(); -} - -#[should_panic(expected = "range start is greater than range end in BTreeMap")] -#[test] -fn test_range_panic_1() { - let mut map = BTreeMap::new(); - map.insert(3, "a"); - map.insert(5, "b"); - map.insert(8, "c"); - - let _invalid_range = map.range((Included(&8), Included(&3))); -} - -#[should_panic(expected = "range start and end are equal and excluded in BTreeMap")] -#[test] -fn test_range_panic_2() { - let mut map = BTreeMap::new(); - map.insert(3, "a"); - map.insert(5, "b"); - map.insert(8, "c"); - - let _invalid_range = map.range((Excluded(&5), Excluded(&5))); -} - -#[should_panic(expected = "range start and end are equal and excluded in BTreeMap")] -#[test] -fn test_range_panic_3() { - let mut map: BTreeMap = BTreeMap::new(); - map.insert(3, ()); - map.insert(5, ()); - map.insert(8, ()); - - let _invalid_range = map.range((Excluded(&5), Excluded(&5))); -} - -#[test] -fn test_retain() { - let mut map = BTreeMap::from_iter((0..100).map(|x| (x, x * 10))); - - map.retain(|&k, _| k % 2 == 0); - assert_eq!(map.len(), 50); - assert_eq!(map[&2], 20); - assert_eq!(map[&4], 40); - assert_eq!(map[&6], 60); -} - -mod test_extract_if { - use super::*; - - #[test] - fn empty() { - let mut map: BTreeMap = BTreeMap::new(); - map.extract_if(|_, _| unreachable!("there's nothing to decide on")).for_each(drop); - assert_eq!(map.height(), None); - map.check(); - } - - // Explicitly consumes the iterator, where most test cases drop it instantly. - #[test] - fn consumed_keeping_all() { - let pairs = (0..3).map(|i| (i, i)); - let mut map = BTreeMap::from_iter(pairs); - assert!(map.extract_if(|_, _| false).eq(iter::empty())); - map.check(); - } - - // Explicitly consumes the iterator, where most test cases drop it instantly. - #[test] - fn consumed_removing_all() { - let pairs = (0..3).map(|i| (i, i)); - let mut map = BTreeMap::from_iter(pairs.clone()); - assert!(map.extract_if(|_, _| true).eq(pairs)); - assert!(map.is_empty()); - map.check(); - } - - // Explicitly consumes the iterator and modifies values through it. - #[test] - fn mutating_and_keeping() { - let pairs = (0..3).map(|i| (i, i)); - let mut map = BTreeMap::from_iter(pairs); - assert!( - map.extract_if(|_, v| { - *v += 6; - false - }) - .eq(iter::empty()) - ); - assert!(map.keys().copied().eq(0..3)); - assert!(map.values().copied().eq(6..9)); - map.check(); - } - - // Explicitly consumes the iterator and modifies values through it. - #[test] - fn mutating_and_removing() { - let pairs = (0..3).map(|i| (i, i)); - let mut map = BTreeMap::from_iter(pairs); - assert!( - map.extract_if(|_, v| { - *v += 6; - true - }) - .eq((0..3).map(|i| (i, i + 6))) - ); - assert!(map.is_empty()); - map.check(); - } - - #[test] - fn underfull_keeping_all() { - let pairs = (0..3).map(|i| (i, i)); - let mut map = BTreeMap::from_iter(pairs); - map.extract_if(|_, _| false).for_each(drop); - assert!(map.keys().copied().eq(0..3)); - map.check(); - } - - #[test] - fn underfull_removing_one() { - let pairs = (0..3).map(|i| (i, i)); - for doomed in 0..3 { - let mut map = BTreeMap::from_iter(pairs.clone()); - map.extract_if(|i, _| *i == doomed).for_each(drop); - assert_eq!(map.len(), 2); - map.check(); - } - } - - #[test] - fn underfull_keeping_one() { - let pairs = (0..3).map(|i| (i, i)); - for sacred in 0..3 { - let mut map = BTreeMap::from_iter(pairs.clone()); - map.extract_if(|i, _| *i != sacred).for_each(drop); - assert!(map.keys().copied().eq(sacred..=sacred)); - map.check(); - } - } - - #[test] - fn underfull_removing_all() { - let pairs = (0..3).map(|i| (i, i)); - let mut map = BTreeMap::from_iter(pairs); - map.extract_if(|_, _| true).for_each(drop); - assert!(map.is_empty()); - map.check(); - } - - #[test] - fn height_0_keeping_all() { - let pairs = (0..node::CAPACITY).map(|i| (i, i)); - let mut map = BTreeMap::from_iter(pairs); - map.extract_if(|_, _| false).for_each(drop); - assert!(map.keys().copied().eq(0..node::CAPACITY)); - map.check(); - } - - #[test] - fn height_0_removing_one() { - let pairs = (0..node::CAPACITY).map(|i| (i, i)); - for doomed in 0..node::CAPACITY { - let mut map = BTreeMap::from_iter(pairs.clone()); - map.extract_if(|i, _| *i == doomed).for_each(drop); - assert_eq!(map.len(), node::CAPACITY - 1); - map.check(); - } - } - - #[test] - fn height_0_keeping_one() { - let pairs = (0..node::CAPACITY).map(|i| (i, i)); - for sacred in 0..node::CAPACITY { - let mut map = BTreeMap::from_iter(pairs.clone()); - map.extract_if(|i, _| *i != sacred).for_each(drop); - assert!(map.keys().copied().eq(sacred..=sacred)); - map.check(); - } - } - - #[test] - fn height_0_removing_all() { - let pairs = (0..node::CAPACITY).map(|i| (i, i)); - let mut map = BTreeMap::from_iter(pairs); - map.extract_if(|_, _| true).for_each(drop); - assert!(map.is_empty()); - map.check(); - } - - #[test] - fn height_0_keeping_half() { - let mut map = BTreeMap::from_iter((0..16).map(|i| (i, i))); - assert_eq!(map.extract_if(|i, _| *i % 2 == 0).count(), 8); - assert_eq!(map.len(), 8); - map.check(); - } - - #[test] - fn height_1_removing_all() { - let pairs = (0..MIN_INSERTS_HEIGHT_1).map(|i| (i, i)); - let mut map = BTreeMap::from_iter(pairs); - map.extract_if(|_, _| true).for_each(drop); - assert!(map.is_empty()); - map.check(); - } - - #[test] - fn height_1_removing_one() { - let pairs = (0..MIN_INSERTS_HEIGHT_1).map(|i| (i, i)); - for doomed in 0..MIN_INSERTS_HEIGHT_1 { - let mut map = BTreeMap::from_iter(pairs.clone()); - map.extract_if(|i, _| *i == doomed).for_each(drop); - assert_eq!(map.len(), MIN_INSERTS_HEIGHT_1 - 1); - map.check(); - } - } - - #[test] - fn height_1_keeping_one() { - let pairs = (0..MIN_INSERTS_HEIGHT_1).map(|i| (i, i)); - for sacred in 0..MIN_INSERTS_HEIGHT_1 { - let mut map = BTreeMap::from_iter(pairs.clone()); - map.extract_if(|i, _| *i != sacred).for_each(drop); - assert!(map.keys().copied().eq(sacred..=sacred)); - map.check(); - } - } - - #[test] - fn height_2_removing_one() { - let pairs = (0..MIN_INSERTS_HEIGHT_2).map(|i| (i, i)); - for doomed in (0..MIN_INSERTS_HEIGHT_2).step_by(12) { - let mut map = BTreeMap::from_iter(pairs.clone()); - map.extract_if(|i, _| *i == doomed).for_each(drop); - assert_eq!(map.len(), MIN_INSERTS_HEIGHT_2 - 1); - map.check(); - } - } - - #[test] - fn height_2_keeping_one() { - let pairs = (0..MIN_INSERTS_HEIGHT_2).map(|i| (i, i)); - for sacred in (0..MIN_INSERTS_HEIGHT_2).step_by(12) { - let mut map = BTreeMap::from_iter(pairs.clone()); - map.extract_if(|i, _| *i != sacred).for_each(drop); - assert!(map.keys().copied().eq(sacred..=sacred)); - map.check(); - } - } - - #[test] - fn height_2_removing_all() { - let pairs = (0..MIN_INSERTS_HEIGHT_2).map(|i| (i, i)); - let mut map = BTreeMap::from_iter(pairs); - map.extract_if(|_, _| true).for_each(drop); - assert!(map.is_empty()); - map.check(); - } - - #[test] - #[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] - fn drop_panic_leak() { - let a = CrashTestDummy::new(0); - let b = CrashTestDummy::new(1); - let c = CrashTestDummy::new(2); - let mut map = BTreeMap::new(); - map.insert(a.spawn(Panic::Never), ()); - map.insert(b.spawn(Panic::InDrop), ()); - map.insert(c.spawn(Panic::Never), ()); - - catch_unwind(move || map.extract_if(|dummy, _| dummy.query(true)).for_each(drop)) - .unwrap_err(); - - assert_eq!(a.queried(), 1); - assert_eq!(b.queried(), 1); - assert_eq!(c.queried(), 0); - assert_eq!(a.dropped(), 1); - assert_eq!(b.dropped(), 1); - assert_eq!(c.dropped(), 1); - } - - #[test] - #[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] - fn pred_panic_leak() { - let a = CrashTestDummy::new(0); - let b = CrashTestDummy::new(1); - let c = CrashTestDummy::new(2); - let mut map = BTreeMap::new(); - map.insert(a.spawn(Panic::Never), ()); - map.insert(b.spawn(Panic::InQuery), ()); - map.insert(c.spawn(Panic::InQuery), ()); - - catch_unwind(AssertUnwindSafe(|| { - map.extract_if(|dummy, _| dummy.query(true)).for_each(drop) - })) - .unwrap_err(); - - assert_eq!(a.queried(), 1); - assert_eq!(b.queried(), 1); - assert_eq!(c.queried(), 0); - assert_eq!(a.dropped(), 1); - assert_eq!(b.dropped(), 0); - assert_eq!(c.dropped(), 0); - assert_eq!(map.len(), 2); - assert_eq!(map.first_entry().unwrap().key().id(), 1); - assert_eq!(map.last_entry().unwrap().key().id(), 2); - map.check(); - } - - // Same as above, but attempt to use the iterator again after the panic in the predicate - #[test] - #[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] - fn pred_panic_reuse() { - let a = CrashTestDummy::new(0); - let b = CrashTestDummy::new(1); - let c = CrashTestDummy::new(2); - let mut map = BTreeMap::new(); - map.insert(a.spawn(Panic::Never), ()); - map.insert(b.spawn(Panic::InQuery), ()); - map.insert(c.spawn(Panic::InQuery), ()); - - { - let mut it = map.extract_if(|dummy, _| dummy.query(true)); - catch_unwind(AssertUnwindSafe(|| while it.next().is_some() {})).unwrap_err(); - // Iterator behaviour after a panic is explicitly unspecified, - // so this is just the current implementation: - let result = catch_unwind(AssertUnwindSafe(|| it.next())); - assert!(matches!(result, Ok(None))); - } - - assert_eq!(a.queried(), 1); - assert_eq!(b.queried(), 1); - assert_eq!(c.queried(), 0); - assert_eq!(a.dropped(), 1); - assert_eq!(b.dropped(), 0); - assert_eq!(c.dropped(), 0); - assert_eq!(map.len(), 2); - assert_eq!(map.first_entry().unwrap().key().id(), 1); - assert_eq!(map.last_entry().unwrap().key().id(), 2); - map.check(); - } -} - -#[test] -fn test_borrow() { - // make sure these compile -- using the Borrow trait - { - let mut map = BTreeMap::new(); - map.insert("0".to_string(), 1); - assert_eq!(map["0"], 1); - } - - { - let mut map = BTreeMap::new(); - map.insert(Box::new(0), 1); - assert_eq!(map[&0], 1); - } - - { - let mut map = BTreeMap::new(); - map.insert(Box::new([0, 1]) as Box<[i32]>, 1); - assert_eq!(map[&[0, 1][..]], 1); - } - - { - let mut map = BTreeMap::new(); - map.insert(Rc::new(0), 1); - assert_eq!(map[&0], 1); - } - - #[allow(dead_code)] - fn get(v: &BTreeMap, ()>, t: &T) { - let _ = v.get(t); - } - - #[allow(dead_code)] - fn get_mut(v: &mut BTreeMap, ()>, t: &T) { - let _ = v.get_mut(t); - } - - #[allow(dead_code)] - fn get_key_value(v: &BTreeMap, ()>, t: &T) { - let _ = v.get_key_value(t); - } - - #[allow(dead_code)] - fn contains_key(v: &BTreeMap, ()>, t: &T) { - let _ = v.contains_key(t); - } - - #[allow(dead_code)] - fn range(v: &BTreeMap, ()>, t: T) { - let _ = v.range(t..); - } - - #[allow(dead_code)] - fn range_mut(v: &mut BTreeMap, ()>, t: T) { - let _ = v.range_mut(t..); - } - - #[allow(dead_code)] - fn remove(v: &mut BTreeMap, ()>, t: &T) { - v.remove(t); - } - - #[allow(dead_code)] - fn remove_entry(v: &mut BTreeMap, ()>, t: &T) { - v.remove_entry(t); - } - - #[allow(dead_code)] - fn split_off(v: &mut BTreeMap, ()>, t: &T) { - v.split_off(t); - } -} - -#[test] -fn test_entry() { - let xs = [(1, 10), (2, 20), (3, 30), (4, 40), (5, 50), (6, 60)]; - - let mut map = BTreeMap::from(xs); - - // Existing key (insert) - match map.entry(1) { - Vacant(_) => unreachable!(), - Occupied(mut view) => { - assert_eq!(view.get(), &10); - assert_eq!(view.insert(100), 10); - } - } - assert_eq!(map.get(&1).unwrap(), &100); - assert_eq!(map.len(), 6); - - // Existing key (update) - match map.entry(2) { - Vacant(_) => unreachable!(), - Occupied(mut view) => { - let v = view.get_mut(); - *v *= 10; - } - } - assert_eq!(map.get(&2).unwrap(), &200); - assert_eq!(map.len(), 6); - map.check(); - - // Existing key (take) - match map.entry(3) { - Vacant(_) => unreachable!(), - Occupied(view) => { - assert_eq!(view.remove(), 30); - } - } - assert_eq!(map.get(&3), None); - assert_eq!(map.len(), 5); - map.check(); - - // Inexistent key (insert) - match map.entry(10) { - Occupied(_) => unreachable!(), - Vacant(view) => { - assert_eq!(*view.insert(1000), 1000); - } - } - assert_eq!(map.get(&10).unwrap(), &1000); - assert_eq!(map.len(), 6); - map.check(); -} - -#[test] -fn test_extend_ref() { - let mut a = BTreeMap::new(); - a.insert(1, "one"); - let mut b = BTreeMap::new(); - b.insert(2, "two"); - b.insert(3, "three"); - - a.extend(&b); - - assert_eq!(a.len(), 3); - assert_eq!(a[&1], "one"); - assert_eq!(a[&2], "two"); - assert_eq!(a[&3], "three"); - a.check(); -} - -#[test] -fn test_zst() { - let mut m = BTreeMap::new(); - assert_eq!(m.len(), 0); - - assert_eq!(m.insert((), ()), None); - assert_eq!(m.len(), 1); - - assert_eq!(m.insert((), ()), Some(())); - assert_eq!(m.len(), 1); - assert_eq!(m.iter().count(), 1); - - m.clear(); - assert_eq!(m.len(), 0); - - for _ in 0..100 { - m.insert((), ()); - } - - assert_eq!(m.len(), 1); - assert_eq!(m.iter().count(), 1); - m.check(); -} - -// This test's only purpose is to ensure that zero-sized keys with nonsensical orderings -// do not cause segfaults when used with zero-sized values. All other map behavior is -// undefined. -#[test] -fn test_bad_zst() { - #[derive(Clone, Copy, Debug)] - struct Bad; - - impl PartialEq for Bad { - fn eq(&self, _: &Self) -> bool { - false - } - } - - impl Eq for Bad {} - - impl PartialOrd for Bad { - fn partial_cmp(&self, _: &Self) -> Option { - Some(Ordering::Less) - } - } - - impl Ord for Bad { - fn cmp(&self, _: &Self) -> Ordering { - Ordering::Less - } - } - - let mut m = BTreeMap::new(); - - for _ in 0..100 { - m.insert(Bad, Bad); - } - m.check(); -} - -#[test] -fn test_clear() { - let mut map = BTreeMap::new(); - for &len in &[MIN_INSERTS_HEIGHT_1, MIN_INSERTS_HEIGHT_2, 0, node::CAPACITY] { - for i in 0..len { - map.insert(i, ()); - } - assert_eq!(map.len(), len); - map.clear(); - map.check(); - assert_eq!(map.height(), None); - } -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_clear_drop_panic_leak() { - let a = CrashTestDummy::new(0); - let b = CrashTestDummy::new(1); - let c = CrashTestDummy::new(2); - - let mut map = BTreeMap::new(); - map.insert(a.spawn(Panic::Never), ()); - map.insert(b.spawn(Panic::InDrop), ()); - map.insert(c.spawn(Panic::Never), ()); - - catch_unwind(AssertUnwindSafe(|| map.clear())).unwrap_err(); - assert_eq!(a.dropped(), 1); - assert_eq!(b.dropped(), 1); - assert_eq!(c.dropped(), 1); - assert_eq!(map.len(), 0); - - drop(map); - assert_eq!(a.dropped(), 1); - assert_eq!(b.dropped(), 1); - assert_eq!(c.dropped(), 1); -} - -#[test] -fn test_clone() { - let mut map = BTreeMap::new(); - let size = MIN_INSERTS_HEIGHT_1; - assert_eq!(map.len(), 0); - - for i in 0..size { - assert_eq!(map.insert(i, 10 * i), None); - assert_eq!(map.len(), i + 1); - map.check(); - assert_eq!(map, map.clone()); - } - - for i in 0..size { - assert_eq!(map.insert(i, 100 * i), Some(10 * i)); - assert_eq!(map.len(), size); - map.check(); - assert_eq!(map, map.clone()); - } - - for i in 0..size / 2 { - assert_eq!(map.remove(&(i * 2)), Some(i * 200)); - assert_eq!(map.len(), size - i - 1); - map.check(); - assert_eq!(map, map.clone()); - } - - for i in 0..size / 2 { - assert_eq!(map.remove(&(2 * i)), None); - assert_eq!(map.remove(&(2 * i + 1)), Some(i * 200 + 100)); - assert_eq!(map.len(), size / 2 - i - 1); - map.check(); - assert_eq!(map, map.clone()); - } - - // Test a tree with 2 semi-full levels and a tree with 3 levels. - map = BTreeMap::from_iter((1..MIN_INSERTS_HEIGHT_2).map(|i| (i, i))); - assert_eq!(map.len(), MIN_INSERTS_HEIGHT_2 - 1); - assert_eq!(map, map.clone()); - map.insert(0, 0); - assert_eq!(map.len(), MIN_INSERTS_HEIGHT_2); - assert_eq!(map, map.clone()); - map.check(); -} - -fn test_clone_panic_leak(size: usize) { - for i in 0..size { - let dummies = Vec::from_iter((0..size).map(|id| CrashTestDummy::new(id))); - let map = BTreeMap::from_iter(dummies.iter().map(|dummy| { - let panic = if dummy.id == i { Panic::InClone } else { Panic::Never }; - (dummy.spawn(panic), ()) - })); - - catch_unwind(|| map.clone()).unwrap_err(); - for d in &dummies { - assert_eq!(d.cloned(), if d.id <= i { 1 } else { 0 }, "id={}/{}", d.id, i); - assert_eq!(d.dropped(), if d.id < i { 1 } else { 0 }, "id={}/{}", d.id, i); - } - assert_eq!(map.len(), size); - - drop(map); - for d in &dummies { - assert_eq!(d.cloned(), if d.id <= i { 1 } else { 0 }, "id={}/{}", d.id, i); - assert_eq!(d.dropped(), if d.id < i { 2 } else { 1 }, "id={}/{}", d.id, i); - } - } -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_clone_panic_leak_height_0() { - test_clone_panic_leak(3) -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_clone_panic_leak_height_1() { - test_clone_panic_leak(MIN_INSERTS_HEIGHT_1) -} - -#[test] -fn test_clone_from() { - let mut map1 = BTreeMap::new(); - let max_size = MIN_INSERTS_HEIGHT_1; - - // Range to max_size inclusive, because i is the size of map1 being tested. - for i in 0..=max_size { - let mut map2 = BTreeMap::new(); - for j in 0..i { - let mut map1_copy = map2.clone(); - map1_copy.clone_from(&map1); // small cloned from large - assert_eq!(map1_copy, map1); - let mut map2_copy = map1.clone(); - map2_copy.clone_from(&map2); // large cloned from small - assert_eq!(map2_copy, map2); - map2.insert(100 * j + 1, 2 * j + 1); - } - map2.clone_from(&map1); // same length - map2.check(); - assert_eq!(map2, map1); - map1.insert(i, 10 * i); - map1.check(); - } -} - -#[allow(dead_code)] -fn assert_covariance() { - fn map_key<'new>(v: BTreeMap<&'static str, ()>) -> BTreeMap<&'new str, ()> { - v - } - fn map_val<'new>(v: BTreeMap<(), &'static str>) -> BTreeMap<(), &'new str> { - v - } - - fn iter_key<'a, 'new>(v: Iter<'a, &'static str, ()>) -> Iter<'a, &'new str, ()> { - v - } - fn iter_val<'a, 'new>(v: Iter<'a, (), &'static str>) -> Iter<'a, (), &'new str> { - v - } - - fn into_iter_key<'new>(v: IntoIter<&'static str, ()>) -> IntoIter<&'new str, ()> { - v - } - fn into_iter_val<'new>(v: IntoIter<(), &'static str>) -> IntoIter<(), &'new str> { - v - } - - fn into_keys_key<'new>(v: IntoKeys<&'static str, ()>) -> IntoKeys<&'new str, ()> { - v - } - fn into_keys_val<'new>(v: IntoKeys<(), &'static str>) -> IntoKeys<(), &'new str> { - v - } - - fn into_values_key<'new>(v: IntoValues<&'static str, ()>) -> IntoValues<&'new str, ()> { - v - } - fn into_values_val<'new>(v: IntoValues<(), &'static str>) -> IntoValues<(), &'new str> { - v - } - - fn range_key<'a, 'new>(v: Range<'a, &'static str, ()>) -> Range<'a, &'new str, ()> { - v - } - fn range_val<'a, 'new>(v: Range<'a, (), &'static str>) -> Range<'a, (), &'new str> { - v - } - - fn keys_key<'a, 'new>(v: Keys<'a, &'static str, ()>) -> Keys<'a, &'new str, ()> { - v - } - fn keys_val<'a, 'new>(v: Keys<'a, (), &'static str>) -> Keys<'a, (), &'new str> { - v - } - - fn values_key<'a, 'new>(v: Values<'a, &'static str, ()>) -> Values<'a, &'new str, ()> { - v - } - fn values_val<'a, 'new>(v: Values<'a, (), &'static str>) -> Values<'a, (), &'new str> { - v - } -} - -#[allow(dead_code)] -fn assert_sync() { - fn map(v: &BTreeMap) -> impl Sync + '_ { - v - } - - fn into_iter(v: BTreeMap) -> impl Sync { - v.into_iter() - } - - fn into_keys(v: BTreeMap) -> impl Sync { - v.into_keys() - } - - fn into_values(v: BTreeMap) -> impl Sync { - v.into_values() - } - - fn extract_if(v: &mut BTreeMap) -> impl Sync + '_ { - v.extract_if(|_, _| false) - } - - fn iter(v: &BTreeMap) -> impl Sync + '_ { - v.iter() - } - - fn iter_mut(v: &mut BTreeMap) -> impl Sync + '_ { - v.iter_mut() - } - - fn keys(v: &BTreeMap) -> impl Sync + '_ { - v.keys() - } - - fn values(v: &BTreeMap) -> impl Sync + '_ { - v.values() - } - - fn values_mut(v: &mut BTreeMap) -> impl Sync + '_ { - v.values_mut() - } - - fn range(v: &BTreeMap) -> impl Sync + '_ { - v.range(..) - } - - fn range_mut(v: &mut BTreeMap) -> impl Sync + '_ { - v.range_mut(..) - } - - fn entry(v: &mut BTreeMap) -> impl Sync + '_ { - v.entry(Default::default()) - } - - fn occupied_entry(v: &mut BTreeMap) -> impl Sync + '_ { - match v.entry(Default::default()) { - Occupied(entry) => entry, - _ => unreachable!(), - } - } - - fn vacant_entry(v: &mut BTreeMap) -> impl Sync + '_ { - match v.entry(Default::default()) { - Vacant(entry) => entry, - _ => unreachable!(), - } - } -} - -#[allow(dead_code)] -fn assert_send() { - fn map(v: BTreeMap) -> impl Send { - v - } - - fn into_iter(v: BTreeMap) -> impl Send { - v.into_iter() - } - - fn into_keys(v: BTreeMap) -> impl Send { - v.into_keys() - } - - fn into_values(v: BTreeMap) -> impl Send { - v.into_values() - } - - fn extract_if(v: &mut BTreeMap) -> impl Send + '_ { - v.extract_if(|_, _| false) - } - - fn iter(v: &BTreeMap) -> impl Send + '_ { - v.iter() - } - - fn iter_mut(v: &mut BTreeMap) -> impl Send + '_ { - v.iter_mut() - } - - fn keys(v: &BTreeMap) -> impl Send + '_ { - v.keys() - } - - fn values(v: &BTreeMap) -> impl Send + '_ { - v.values() - } - - fn values_mut(v: &mut BTreeMap) -> impl Send + '_ { - v.values_mut() - } - - fn range(v: &BTreeMap) -> impl Send + '_ { - v.range(..) - } - - fn range_mut(v: &mut BTreeMap) -> impl Send + '_ { - v.range_mut(..) - } - - fn entry(v: &mut BTreeMap) -> impl Send + '_ { - v.entry(Default::default()) - } - - fn occupied_entry(v: &mut BTreeMap) -> impl Send + '_ { - match v.entry(Default::default()) { - Occupied(entry) => entry, - _ => unreachable!(), - } - } - - fn vacant_entry(v: &mut BTreeMap) -> impl Send + '_ { - match v.entry(Default::default()) { - Vacant(entry) => entry, - _ => unreachable!(), - } - } -} - -#[test] -fn test_ord_absence() { - fn map(mut map: BTreeMap) { - let _ = map.is_empty(); - let _ = map.len(); - map.clear(); - let _ = map.iter(); - let _ = map.iter_mut(); - let _ = map.keys(); - let _ = map.values(); - let _ = map.values_mut(); - if true { - let _ = map.into_values(); - } else if true { - let _ = map.into_iter(); - } else { - let _ = map.into_keys(); - } - } - - fn map_debug(mut map: BTreeMap) { - format!("{map:?}"); - format!("{:?}", map.iter()); - format!("{:?}", map.iter_mut()); - format!("{:?}", map.keys()); - format!("{:?}", map.values()); - format!("{:?}", map.values_mut()); - if true { - format!("{:?}", map.into_iter()); - } else if true { - format!("{:?}", map.into_keys()); - } else { - format!("{:?}", map.into_values()); - } - } - - fn map_clone(mut map: BTreeMap) { - map.clone_from(&map.clone()); - } - - #[derive(Debug, Clone)] - struct NonOrd; - map(BTreeMap::::new()); - map_debug(BTreeMap::::new()); - map_clone(BTreeMap::::default()); -} - -#[test] -fn test_occupied_entry_key() { - let mut a = BTreeMap::new(); - let key = "hello there"; - let value = "value goes here"; - assert_eq!(a.height(), None); - a.insert(key, value); - assert_eq!(a.len(), 1); - assert_eq!(a[key], value); - - match a.entry(key) { - Vacant(_) => panic!(), - Occupied(e) => assert_eq!(key, *e.key()), - } - assert_eq!(a.len(), 1); - assert_eq!(a[key], value); - a.check(); -} - -#[test] -fn test_vacant_entry_key() { - let mut a = BTreeMap::new(); - let key = "hello there"; - let value = "value goes here"; - - assert_eq!(a.height(), None); - match a.entry(key) { - Occupied(_) => unreachable!(), - Vacant(e) => { - assert_eq!(key, *e.key()); - e.insert(value); - } - } - assert_eq!(a.len(), 1); - assert_eq!(a[key], value); - a.check(); -} - -#[test] -fn test_vacant_entry_no_insert() { - let mut a = BTreeMap::<&str, ()>::new(); - let key = "hello there"; - - // Non-allocated - assert_eq!(a.height(), None); - match a.entry(key) { - Occupied(_) => unreachable!(), - Vacant(e) => assert_eq!(key, *e.key()), - } - // Ensures the tree has no root. - assert_eq!(a.height(), None); - a.check(); - - // Allocated but still empty - a.insert(key, ()); - a.remove(&key); - assert_eq!(a.height(), Some(0)); - assert!(a.is_empty()); - match a.entry(key) { - Occupied(_) => unreachable!(), - Vacant(e) => assert_eq!(key, *e.key()), - } - // Ensures the allocated root is not changed. - assert_eq!(a.height(), Some(0)); - assert!(a.is_empty()); - a.check(); -} - -#[test] -fn test_first_last_entry() { - let mut a = BTreeMap::new(); - assert!(a.first_entry().is_none()); - assert!(a.last_entry().is_none()); - a.insert(1, 42); - assert_eq!(a.first_entry().unwrap().key(), &1); - assert_eq!(a.last_entry().unwrap().key(), &1); - a.insert(2, 24); - assert_eq!(a.first_entry().unwrap().key(), &1); - assert_eq!(a.last_entry().unwrap().key(), &2); - a.insert(0, 6); - assert_eq!(a.first_entry().unwrap().key(), &0); - assert_eq!(a.last_entry().unwrap().key(), &2); - let (k1, v1) = a.first_entry().unwrap().remove_entry(); - assert_eq!(k1, 0); - assert_eq!(v1, 6); - let (k2, v2) = a.last_entry().unwrap().remove_entry(); - assert_eq!(k2, 2); - assert_eq!(v2, 24); - assert_eq!(a.first_entry().unwrap().key(), &1); - assert_eq!(a.last_entry().unwrap().key(), &1); - a.check(); -} - -#[test] -fn test_pop_first_last() { - let mut map = BTreeMap::new(); - assert_eq!(map.pop_first(), None); - assert_eq!(map.pop_last(), None); - - map.insert(1, 10); - map.insert(2, 20); - map.insert(3, 30); - map.insert(4, 40); - - assert_eq!(map.len(), 4); - - let (key, val) = map.pop_first().unwrap(); - assert_eq!(key, 1); - assert_eq!(val, 10); - assert_eq!(map.len(), 3); - - let (key, val) = map.pop_first().unwrap(); - assert_eq!(key, 2); - assert_eq!(val, 20); - assert_eq!(map.len(), 2); - let (key, val) = map.pop_last().unwrap(); - assert_eq!(key, 4); - assert_eq!(val, 40); - assert_eq!(map.len(), 1); - - map.insert(5, 50); - map.insert(6, 60); - assert_eq!(map.len(), 3); - - let (key, val) = map.pop_first().unwrap(); - assert_eq!(key, 3); - assert_eq!(val, 30); - assert_eq!(map.len(), 2); - - let (key, val) = map.pop_last().unwrap(); - assert_eq!(key, 6); - assert_eq!(val, 60); - assert_eq!(map.len(), 1); - - let (key, val) = map.pop_last().unwrap(); - assert_eq!(key, 5); - assert_eq!(val, 50); - assert_eq!(map.len(), 0); - - assert_eq!(map.pop_first(), None); - assert_eq!(map.pop_last(), None); - - map.insert(7, 70); - map.insert(8, 80); - - let (key, val) = map.pop_last().unwrap(); - assert_eq!(key, 8); - assert_eq!(val, 80); - assert_eq!(map.len(), 1); - - let (key, val) = map.pop_last().unwrap(); - assert_eq!(key, 7); - assert_eq!(val, 70); - assert_eq!(map.len(), 0); - - assert_eq!(map.pop_first(), None); - assert_eq!(map.pop_last(), None); -} - -#[test] -fn test_get_key_value() { - let mut map = BTreeMap::new(); - - assert!(map.is_empty()); - assert_eq!(map.get_key_value(&1), None); - assert_eq!(map.get_key_value(&2), None); - - map.insert(1, 10); - map.insert(2, 20); - map.insert(3, 30); - - assert_eq!(map.len(), 3); - assert_eq!(map.get_key_value(&1), Some((&1, &10))); - assert_eq!(map.get_key_value(&3), Some((&3, &30))); - assert_eq!(map.get_key_value(&4), None); - - map.remove(&3); - - assert_eq!(map.len(), 2); - assert_eq!(map.get_key_value(&3), None); - assert_eq!(map.get_key_value(&2), Some((&2, &20))); -} - -#[test] -fn test_insert_into_full_height_0() { - let size = node::CAPACITY; - for pos in 0..=size { - let mut map = BTreeMap::from_iter((0..size).map(|i| (i * 2 + 1, ()))); - assert!(map.insert(pos * 2, ()).is_none()); - map.check(); - } -} - -#[test] -fn test_insert_into_full_height_1() { - let size = node::CAPACITY + 1 + node::CAPACITY; - for pos in 0..=size { - let mut map = BTreeMap::from_iter((0..size).map(|i| (i * 2 + 1, ()))); - map.compact(); - let root_node = map.root.as_ref().unwrap().reborrow(); - assert_eq!(root_node.len(), 1); - assert_eq!(root_node.first_leaf_edge().into_node().len(), node::CAPACITY); - assert_eq!(root_node.last_leaf_edge().into_node().len(), node::CAPACITY); - - assert!(map.insert(pos * 2, ()).is_none()); - map.check(); - } -} - -#[test] -fn test_try_insert() { - let mut map = BTreeMap::new(); - - assert!(map.is_empty()); - - assert_eq!(map.try_insert(1, 10).unwrap(), &10); - assert_eq!(map.try_insert(2, 20).unwrap(), &20); - - let err = map.try_insert(2, 200).unwrap_err(); - assert_eq!(err.entry.key(), &2); - assert_eq!(err.entry.get(), &20); - assert_eq!(err.value, 200); -} - -macro_rules! create_append_test { - ($name:ident, $len:expr) => { - #[test] - fn $name() { - let mut a = BTreeMap::new(); - for i in 0..8 { - a.insert(i, i); - } - - let mut b = BTreeMap::new(); - for i in 5..$len { - b.insert(i, 2 * i); - } - - a.append(&mut b); - - assert_eq!(a.len(), $len); - assert_eq!(b.len(), 0); - - for i in 0..$len { - if i < 5 { - assert_eq!(a[&i], i); - } else { - assert_eq!(a[&i], 2 * i); - } - } - - a.check(); - assert_eq!(a.remove(&($len - 1)), Some(2 * ($len - 1))); - assert_eq!(a.insert($len - 1, 20), None); - a.check(); - } - }; -} - -// These are mostly for testing the algorithm that "fixes" the right edge after insertion. -// Single node. -create_append_test!(test_append_9, 9); -// Two leafs that don't need fixing. -create_append_test!(test_append_17, 17); -// Two leafs where the second one ends up underfull and needs stealing at the end. -create_append_test!(test_append_14, 14); -// Two leafs where the second one ends up empty because the insertion finished at the root. -create_append_test!(test_append_12, 12); -// Three levels; insertion finished at the root. -create_append_test!(test_append_144, 144); -// Three levels; insertion finished at leaf while there is an empty node on the second level. -create_append_test!(test_append_145, 145); -// Tests for several randomly chosen sizes. -create_append_test!(test_append_170, 170); -create_append_test!(test_append_181, 181); -#[cfg(not(miri))] // Miri is too slow -create_append_test!(test_append_239, 239); -#[cfg(not(miri))] // Miri is too slow -create_append_test!(test_append_1700, 1700); - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_append_drop_leak() { - let a = CrashTestDummy::new(0); - let b = CrashTestDummy::new(1); - let c = CrashTestDummy::new(2); - let mut left = BTreeMap::new(); - let mut right = BTreeMap::new(); - left.insert(a.spawn(Panic::Never), ()); - left.insert(b.spawn(Panic::InDrop), ()); // first duplicate key, dropped during append - left.insert(c.spawn(Panic::Never), ()); - right.insert(b.spawn(Panic::Never), ()); - right.insert(c.spawn(Panic::Never), ()); - - catch_unwind(move || left.append(&mut right)).unwrap_err(); - assert_eq!(a.dropped(), 1); - assert_eq!(b.dropped(), 1); // should be 2 were it not for Rust issue #47949 - assert_eq!(c.dropped(), 2); -} - -#[test] -fn test_append_ord_chaos() { - let mut map1 = BTreeMap::new(); - map1.insert(Cyclic3::A, ()); - map1.insert(Cyclic3::B, ()); - let mut map2 = BTreeMap::new(); - map2.insert(Cyclic3::A, ()); - map2.insert(Cyclic3::B, ()); - map2.insert(Cyclic3::C, ()); // lands first, before A - map2.insert(Cyclic3::B, ()); // lands first, before C - map1.check(); - map2.check(); // keys are not unique but still strictly ascending - assert_eq!(map1.len(), 2); - assert_eq!(map2.len(), 4); - map1.append(&mut map2); - assert_eq!(map1.len(), 5); - assert_eq!(map2.len(), 0); - map1.check(); - map2.check(); -} - -fn rand_data(len: usize) -> Vec<(u32, u32)> { - let mut rng = DeterministicRng::new(); - Vec::from_iter((0..len).map(|_| (rng.next(), rng.next()))) -} - -#[test] -fn test_split_off_empty_right() { - let mut data = rand_data(173); - - let mut map = BTreeMap::from_iter(data.clone()); - let right = map.split_off(&(data.iter().max().unwrap().0 + 1)); - map.check(); - right.check(); - - data.sort(); - assert!(map.into_iter().eq(data)); - assert!(right.into_iter().eq(None)); -} - -#[test] -fn test_split_off_empty_left() { - let mut data = rand_data(314); - - let mut map = BTreeMap::from_iter(data.clone()); - let right = map.split_off(&data.iter().min().unwrap().0); - map.check(); - right.check(); - - data.sort(); - assert!(map.into_iter().eq(None)); - assert!(right.into_iter().eq(data)); -} - -// In a tree with 3 levels, if all but a part of the first leaf node is split off, -// make sure fix_top eliminates both top levels. -#[test] -fn test_split_off_tiny_left_height_2() { - let pairs = (0..MIN_INSERTS_HEIGHT_2).map(|i| (i, i)); - let mut left = BTreeMap::from_iter(pairs.clone()); - let right = left.split_off(&1); - left.check(); - right.check(); - assert_eq!(left.len(), 1); - assert_eq!(right.len(), MIN_INSERTS_HEIGHT_2 - 1); - assert_eq!(*left.first_key_value().unwrap().0, 0); - assert_eq!(*right.first_key_value().unwrap().0, 1); -} - -// In a tree with 3 levels, if only part of the last leaf node is split off, -// make sure fix_top eliminates both top levels. -#[test] -fn test_split_off_tiny_right_height_2() { - let pairs = (0..MIN_INSERTS_HEIGHT_2).map(|i| (i, i)); - let last = MIN_INSERTS_HEIGHT_2 - 1; - let mut left = BTreeMap::from_iter(pairs.clone()); - assert_eq!(*left.last_key_value().unwrap().0, last); - let right = left.split_off(&last); - left.check(); - right.check(); - assert_eq!(left.len(), MIN_INSERTS_HEIGHT_2 - 1); - assert_eq!(right.len(), 1); - assert_eq!(*left.last_key_value().unwrap().0, last - 1); - assert_eq!(*right.last_key_value().unwrap().0, last); -} - -#[test] -fn test_split_off_halfway() { - let mut rng = DeterministicRng::new(); - for &len in &[node::CAPACITY, 25, 50, 75, 100] { - let mut data = Vec::from_iter((0..len).map(|_| (rng.next(), ()))); - // Insertion in non-ascending order creates some variation in node length. - let mut map = BTreeMap::from_iter(data.iter().copied()); - data.sort(); - let small_keys = data.iter().take(len / 2).map(|kv| kv.0); - let large_keys = data.iter().skip(len / 2).map(|kv| kv.0); - let split_key = large_keys.clone().next().unwrap(); - let right = map.split_off(&split_key); - map.check(); - right.check(); - assert!(map.keys().copied().eq(small_keys)); - assert!(right.keys().copied().eq(large_keys)); - } -} - -#[test] -fn test_split_off_large_random_sorted() { - // Miri is too slow - let mut data = if cfg!(miri) { rand_data(529) } else { rand_data(1529) }; - // special case with maximum height. - data.sort(); - - let mut map = BTreeMap::from_iter(data.clone()); - let key = data[data.len() / 2].0; - let right = map.split_off(&key); - map.check(); - right.check(); - - assert!(map.into_iter().eq(data.clone().into_iter().filter(|x| x.0 < key))); - assert!(right.into_iter().eq(data.into_iter().filter(|x| x.0 >= key))); -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_into_iter_drop_leak_height_0() { - let a = CrashTestDummy::new(0); - let b = CrashTestDummy::new(1); - let c = CrashTestDummy::new(2); - let d = CrashTestDummy::new(3); - let e = CrashTestDummy::new(4); - let mut map = BTreeMap::new(); - map.insert("a", a.spawn(Panic::Never)); - map.insert("b", b.spawn(Panic::Never)); - map.insert("c", c.spawn(Panic::Never)); - map.insert("d", d.spawn(Panic::InDrop)); - map.insert("e", e.spawn(Panic::Never)); - - catch_unwind(move || drop(map.into_iter())).unwrap_err(); - - assert_eq!(a.dropped(), 1); - assert_eq!(b.dropped(), 1); - assert_eq!(c.dropped(), 1); - assert_eq!(d.dropped(), 1); - assert_eq!(e.dropped(), 1); -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_into_iter_drop_leak_height_1() { - let size = MIN_INSERTS_HEIGHT_1; - for panic_point in vec![0, 1, size - 2, size - 1] { - let dummies = Vec::from_iter((0..size).map(|i| CrashTestDummy::new(i))); - let map = BTreeMap::from_iter((0..size).map(|i| { - let panic = if i == panic_point { Panic::InDrop } else { Panic::Never }; - (dummies[i].spawn(Panic::Never), dummies[i].spawn(panic)) - })); - catch_unwind(move || drop(map.into_iter())).unwrap_err(); - for i in 0..size { - assert_eq!(dummies[i].dropped(), 2); - } - } -} - -#[test] -fn test_into_keys() { - let map = BTreeMap::from([(1, 'a'), (2, 'b'), (3, 'c')]); - let keys = Vec::from_iter(map.into_keys()); - - assert_eq!(keys.len(), 3); - assert!(keys.contains(&1)); - assert!(keys.contains(&2)); - assert!(keys.contains(&3)); -} - -#[test] -fn test_into_values() { - let map = BTreeMap::from([(1, 'a'), (2, 'b'), (3, 'c')]); - let values = Vec::from_iter(map.into_values()); - - assert_eq!(values.len(), 3); - assert!(values.contains(&'a')); - assert!(values.contains(&'b')); - assert!(values.contains(&'c')); -} - -#[test] -fn test_insert_remove_intertwined() { - let loops = if cfg!(miri) { 100 } else { 1_000_000 }; - let mut map = BTreeMap::new(); - let mut i = 1; - let offset = 165; // somewhat arbitrarily chosen to cover some code paths - for _ in 0..loops { - i = (i + offset) & 0xFF; - map.insert(i, i); - map.remove(&(0xFF - i)); - } - map.check(); -} - -#[test] -fn test_insert_remove_intertwined_ord_chaos() { - let loops = if cfg!(miri) { 100 } else { 1_000_000 }; - let gov = Governor::new(); - let mut map = BTreeMap::new(); - let mut i = 1; - let offset = 165; // more arbitrarily copied from above - for _ in 0..loops { - i = (i + offset) & 0xFF; - map.insert(Governed(i, &gov), ()); - map.remove(&Governed(0xFF - i, &gov)); - gov.flip(); - } - map.check_invariants(); -} - -#[test] -fn from_array() { - let map = BTreeMap::from([(1, 2), (3, 4)]); - let unordered_duplicates = BTreeMap::from([(3, 4), (1, 2), (1, 2)]); - assert_eq!(map, unordered_duplicates); -} - -#[test] -fn test_cursor() { - let map = BTreeMap::from([(1, 'a'), (2, 'b'), (3, 'c')]); - - let mut cur = map.lower_bound(Bound::Unbounded); - assert_eq!(cur.peek_next(), Some((&1, &'a'))); - assert_eq!(cur.peek_prev(), None); - assert_eq!(cur.prev(), None); - assert_eq!(cur.next(), Some((&1, &'a'))); - - assert_eq!(cur.next(), Some((&2, &'b'))); - - assert_eq!(cur.peek_next(), Some((&3, &'c'))); - assert_eq!(cur.prev(), Some((&2, &'b'))); - assert_eq!(cur.peek_prev(), Some((&1, &'a'))); - - let mut cur = map.upper_bound(Bound::Excluded(&1)); - assert_eq!(cur.peek_prev(), None); - assert_eq!(cur.next(), Some((&1, &'a'))); - assert_eq!(cur.prev(), Some((&1, &'a'))); -} - -#[test] -fn test_cursor_mut() { - let mut map = BTreeMap::from([(1, 'a'), (3, 'c'), (5, 'e')]); - let mut cur = map.lower_bound_mut(Bound::Excluded(&3)); - assert_eq!(cur.peek_next(), Some((&5, &mut 'e'))); - assert_eq!(cur.peek_prev(), Some((&3, &mut 'c'))); - - cur.insert_before(4, 'd').unwrap(); - assert_eq!(cur.peek_next(), Some((&5, &mut 'e'))); - assert_eq!(cur.peek_prev(), Some((&4, &mut 'd'))); - - assert_eq!(cur.next(), Some((&5, &mut 'e'))); - assert_eq!(cur.peek_next(), None); - assert_eq!(cur.peek_prev(), Some((&5, &mut 'e'))); - cur.insert_before(6, 'f').unwrap(); - assert_eq!(cur.peek_next(), None); - assert_eq!(cur.peek_prev(), Some((&6, &mut 'f'))); - assert_eq!(cur.remove_prev(), Some((6, 'f'))); - assert_eq!(cur.remove_prev(), Some((5, 'e'))); - assert_eq!(cur.remove_next(), None); - assert_eq!(map, BTreeMap::from([(1, 'a'), (3, 'c'), (4, 'd')])); - - let mut cur = map.upper_bound_mut(Bound::Included(&5)); - assert_eq!(cur.peek_next(), None); - assert_eq!(cur.prev(), Some((&4, &mut 'd'))); - assert_eq!(cur.peek_next(), Some((&4, &mut 'd'))); - assert_eq!(cur.peek_prev(), Some((&3, &mut 'c'))); - assert_eq!(cur.remove_next(), Some((4, 'd'))); - assert_eq!(map, BTreeMap::from([(1, 'a'), (3, 'c')])); -} - -#[test] -fn test_cursor_mut_key() { - let mut map = BTreeMap::from([(1, 'a'), (3, 'c'), (5, 'e')]); - let mut cur = unsafe { map.lower_bound_mut(Bound::Excluded(&3)).with_mutable_key() }; - assert_eq!(cur.peek_next(), Some((&mut 5, &mut 'e'))); - assert_eq!(cur.peek_prev(), Some((&mut 3, &mut 'c'))); - - cur.insert_before(4, 'd').unwrap(); - assert_eq!(cur.peek_next(), Some((&mut 5, &mut 'e'))); - assert_eq!(cur.peek_prev(), Some((&mut 4, &mut 'd'))); - - assert_eq!(cur.next(), Some((&mut 5, &mut 'e'))); - assert_eq!(cur.peek_next(), None); - assert_eq!(cur.peek_prev(), Some((&mut 5, &mut 'e'))); - cur.insert_before(6, 'f').unwrap(); - assert_eq!(cur.peek_next(), None); - assert_eq!(cur.peek_prev(), Some((&mut 6, &mut 'f'))); - assert_eq!(cur.remove_prev(), Some((6, 'f'))); - assert_eq!(cur.remove_prev(), Some((5, 'e'))); - assert_eq!(cur.remove_next(), None); - assert_eq!(map, BTreeMap::from([(1, 'a'), (3, 'c'), (4, 'd')])); - - let mut cur = unsafe { map.upper_bound_mut(Bound::Included(&5)).with_mutable_key() }; - assert_eq!(cur.peek_next(), None); - assert_eq!(cur.prev(), Some((&mut 4, &mut 'd'))); - assert_eq!(cur.peek_next(), Some((&mut 4, &mut 'd'))); - assert_eq!(cur.peek_prev(), Some((&mut 3, &mut 'c'))); - assert_eq!(cur.remove_next(), Some((4, 'd'))); - assert_eq!(map, BTreeMap::from([(1, 'a'), (3, 'c')])); -} - -#[test] -fn test_cursor_empty() { - let mut map = BTreeMap::new(); - let mut cur = map.lower_bound_mut(Bound::Excluded(&3)); - assert_eq!(cur.peek_next(), None); - assert_eq!(cur.peek_prev(), None); - cur.insert_after(0, 0).unwrap(); - assert_eq!(cur.peek_next(), Some((&0, &mut 0))); - assert_eq!(cur.peek_prev(), None); - assert_eq!(map, BTreeMap::from([(0, 0)])); -} - -#[test] -fn test_cursor_mut_insert_before_1() { - let mut map = BTreeMap::from([(1, 'a'), (2, 'b'), (3, 'c')]); - let mut cur = map.upper_bound_mut(Bound::Included(&2)); - cur.insert_before(0, 'd').unwrap_err(); -} - -#[test] -fn test_cursor_mut_insert_before_2() { - let mut map = BTreeMap::from([(1, 'a'), (2, 'b'), (3, 'c')]); - let mut cur = map.upper_bound_mut(Bound::Included(&2)); - cur.insert_before(1, 'd').unwrap_err(); -} - -#[test] -fn test_cursor_mut_insert_before_3() { - let mut map = BTreeMap::from([(1, 'a'), (2, 'b'), (3, 'c')]); - let mut cur = map.upper_bound_mut(Bound::Included(&2)); - cur.insert_before(2, 'd').unwrap_err(); -} - -#[test] -fn test_cursor_mut_insert_before_4() { - let mut map = BTreeMap::from([(1, 'a'), (2, 'b'), (3, 'c')]); - let mut cur = map.upper_bound_mut(Bound::Included(&2)); - cur.insert_before(3, 'd').unwrap_err(); -} - -#[test] -fn test_cursor_mut_insert_after_1() { - let mut map = BTreeMap::from([(1, 'a'), (2, 'b'), (3, 'c')]); - let mut cur = map.upper_bound_mut(Bound::Included(&2)); - cur.insert_after(1, 'd').unwrap_err(); -} - -#[test] -fn test_cursor_mut_insert_after_2() { - let mut map = BTreeMap::from([(1, 'a'), (2, 'b'), (3, 'c')]); - let mut cur = map.upper_bound_mut(Bound::Included(&2)); - cur.insert_after(2, 'd').unwrap_err(); -} - -#[test] -fn test_cursor_mut_insert_after_3() { - let mut map = BTreeMap::from([(1, 'a'), (2, 'b'), (3, 'c')]); - let mut cur = map.upper_bound_mut(Bound::Included(&2)); - cur.insert_after(3, 'd').unwrap_err(); -} - -#[test] -fn test_cursor_mut_insert_after_4() { - let mut map = BTreeMap::from([(1, 'a'), (2, 'b'), (3, 'c')]); - let mut cur = map.upper_bound_mut(Bound::Included(&2)); - cur.insert_after(4, 'd').unwrap_err(); -} - -#[test] -fn cursor_peek_prev_agrees_with_cursor_mut() { - let mut map = BTreeMap::from([(1, 1), (2, 2), (3, 3)]); - - let cursor = map.lower_bound(Bound::Excluded(&3)); - assert!(cursor.peek_next().is_none()); - - let prev = cursor.peek_prev(); - assert_matches!(prev, Some((&3, _))); - - // Shadow names so the two parts of this test match. - let mut cursor = map.lower_bound_mut(Bound::Excluded(&3)); - assert!(cursor.peek_next().is_none()); - - let prev = cursor.peek_prev(); - assert_matches!(prev, Some((&3, _))); -} diff --git a/library/alloc/src/collections/btree/mem.rs b/library/alloc/src/collections/btree/mem.rs deleted file mode 100644 index e1363d1ae1f6b..0000000000000 --- a/library/alloc/src/collections/btree/mem.rs +++ /dev/null @@ -1,35 +0,0 @@ -use core::intrinsics; -use core::mem; -use core::ptr; - -/// This replaces the value behind the `v` unique reference by calling the -/// relevant function. -/// -/// If a panic occurs in the `change` closure, the entire process will be aborted. -#[allow(dead_code)] // keep as illustration and for future use -#[inline] -pub fn take_mut(v: &mut T, change: impl FnOnce(T) -> T) { - replace(v, |value| (change(value), ())) -} - -/// This replaces the value behind the `v` unique reference by calling the -/// relevant function, and returns a result obtained along the way. -/// -/// If a panic occurs in the `change` closure, the entire process will be aborted. -#[inline] -pub fn replace(v: &mut T, change: impl FnOnce(T) -> (T, R)) -> R { - struct PanicGuard; - impl Drop for PanicGuard { - fn drop(&mut self) { - intrinsics::abort() - } - } - let guard = PanicGuard; - let value = unsafe { ptr::read(v) }; - let (new_value, ret) = change(value); - unsafe { - ptr::write(v, new_value); - } - mem::forget(guard); - ret -} diff --git a/library/alloc/src/collections/btree/merge_iter.rs b/library/alloc/src/collections/btree/merge_iter.rs deleted file mode 100644 index 7f23d93b990f5..0000000000000 --- a/library/alloc/src/collections/btree/merge_iter.rs +++ /dev/null @@ -1,98 +0,0 @@ -use core::cmp::Ordering; -use core::fmt::{self, Debug}; -use core::iter::FusedIterator; - -/// Core of an iterator that merges the output of two strictly ascending iterators, -/// for instance a union or a symmetric difference. -pub struct MergeIterInner { - a: I, - b: I, - peeked: Option>, -} - -/// Benchmarks faster than wrapping both iterators in a Peekable, -/// probably because we can afford to impose a FusedIterator bound. -#[derive(Clone, Debug)] -enum Peeked { - A(I::Item), - B(I::Item), -} - -impl Clone for MergeIterInner -where - I: Clone, - I::Item: Clone, -{ - fn clone(&self) -> Self { - Self { a: self.a.clone(), b: self.b.clone(), peeked: self.peeked.clone() } - } -} - -impl Debug for MergeIterInner -where - I: Debug, - I::Item: Debug, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("MergeIterInner").field(&self.a).field(&self.b).field(&self.peeked).finish() - } -} - -impl MergeIterInner { - /// Creates a new core for an iterator merging a pair of sources. - pub fn new(a: I, b: I) -> Self { - MergeIterInner { a, b, peeked: None } - } - - /// Returns the next pair of items stemming from the pair of sources - /// being merged. If both returned options contain a value, that value - /// is equal and occurs in both sources. If one of the returned options - /// contains a value, that value doesn't occur in the other source (or - /// the sources are not strictly ascending). If neither returned option - /// contains a value, iteration has finished and subsequent calls will - /// return the same empty pair. - pub fn nexts Ordering>( - &mut self, - cmp: Cmp, - ) -> (Option, Option) - where - I: FusedIterator, - { - let mut a_next; - let mut b_next; - match self.peeked.take() { - Some(Peeked::A(next)) => { - a_next = Some(next); - b_next = self.b.next(); - } - Some(Peeked::B(next)) => { - b_next = Some(next); - a_next = self.a.next(); - } - None => { - a_next = self.a.next(); - b_next = self.b.next(); - } - } - if let (Some(ref a1), Some(ref b1)) = (&a_next, &b_next) { - match cmp(a1, b1) { - Ordering::Less => self.peeked = b_next.take().map(Peeked::B), - Ordering::Greater => self.peeked = a_next.take().map(Peeked::A), - Ordering::Equal => (), - } - } - (a_next, b_next) - } - - /// Returns a pair of upper bounds for the `size_hint` of the final iterator. - pub fn lens(&self) -> (usize, usize) - where - I: ExactSizeIterator, - { - match self.peeked { - Some(Peeked::A(_)) => (1 + self.a.len(), self.b.len()), - Some(Peeked::B(_)) => (self.a.len(), 1 + self.b.len()), - _ => (self.a.len(), self.b.len()), - } - } -} diff --git a/library/alloc/src/collections/btree/mod.rs b/library/alloc/src/collections/btree/mod.rs deleted file mode 100644 index c7d0144de30cb..0000000000000 --- a/library/alloc/src/collections/btree/mod.rs +++ /dev/null @@ -1,22 +0,0 @@ -mod append; -mod borrow; -mod dedup_sorted_iter; -mod fix; -pub mod map; -mod mem; -mod merge_iter; -mod navigate; -mod node; -mod remove; -mod search; -pub mod set; -mod set_val; -mod split; - -trait Recover { - type Key; - - fn get(&self, key: &Q) -> Option<&Self::Key>; - fn take(&mut self, key: &Q) -> Option; - fn replace(&mut self, key: Self::Key) -> Option; -} diff --git a/library/alloc/src/collections/btree/navigate.rs b/library/alloc/src/collections/btree/navigate.rs deleted file mode 100644 index 5e6a26f65c41e..0000000000000 --- a/library/alloc/src/collections/btree/navigate.rs +++ /dev/null @@ -1,782 +0,0 @@ -use core::borrow::Borrow; -use core::hint; -use core::ops::RangeBounds; -use core::ptr; - -use super::node::{marker, ForceResult::*, Handle, NodeRef}; -use super::search::SearchBound; - -use crate::alloc::Allocator; -// `front` and `back` are always both `None` or both `Some`. -pub struct LeafRange { - front: Option, marker::Edge>>, - back: Option, marker::Edge>>, -} - -impl<'a, K: 'a, V: 'a> Clone for LeafRange, K, V> { - fn clone(&self) -> Self { - LeafRange { front: self.front.clone(), back: self.back.clone() } - } -} - -impl Default for LeafRange { - fn default() -> Self { - LeafRange { front: None, back: None } - } -} - -impl LeafRange { - pub fn none() -> Self { - LeafRange { front: None, back: None } - } - - fn is_empty(&self) -> bool { - self.front == self.back - } - - /// Temporarily takes out another, immutable equivalent of the same range. - pub fn reborrow(&self) -> LeafRange, K, V> { - LeafRange { - front: self.front.as_ref().map(|f| f.reborrow()), - back: self.back.as_ref().map(|b| b.reborrow()), - } - } -} - -impl<'a, K, V> LeafRange, K, V> { - #[inline] - pub fn next_checked(&mut self) -> Option<(&'a K, &'a V)> { - self.perform_next_checked(|kv| kv.into_kv()) - } - - #[inline] - pub fn next_back_checked(&mut self) -> Option<(&'a K, &'a V)> { - self.perform_next_back_checked(|kv| kv.into_kv()) - } -} - -impl<'a, K, V> LeafRange, K, V> { - #[inline] - pub fn next_checked(&mut self) -> Option<(&'a K, &'a mut V)> { - self.perform_next_checked(|kv| unsafe { ptr::read(kv) }.into_kv_valmut()) - } - - #[inline] - pub fn next_back_checked(&mut self) -> Option<(&'a K, &'a mut V)> { - self.perform_next_back_checked(|kv| unsafe { ptr::read(kv) }.into_kv_valmut()) - } -} - -impl LeafRange { - /// If possible, extract some result from the following KV and move to the edge beyond it. - fn perform_next_checked(&mut self, f: F) -> Option - where - F: Fn(&Handle, marker::KV>) -> R, - { - if self.is_empty() { - None - } else { - super::mem::replace(self.front.as_mut().unwrap(), |front| { - let kv = front.next_kv().ok().unwrap(); - let result = f(&kv); - (kv.next_leaf_edge(), Some(result)) - }) - } - } - - /// If possible, extract some result from the preceding KV and move to the edge beyond it. - fn perform_next_back_checked(&mut self, f: F) -> Option - where - F: Fn(&Handle, marker::KV>) -> R, - { - if self.is_empty() { - None - } else { - super::mem::replace(self.back.as_mut().unwrap(), |back| { - let kv = back.next_back_kv().ok().unwrap(); - let result = f(&kv); - (kv.next_back_leaf_edge(), Some(result)) - }) - } - } -} - -enum LazyLeafHandle { - Root(NodeRef), // not yet descended - Edge(Handle, marker::Edge>), -} - -impl<'a, K: 'a, V: 'a> Clone for LazyLeafHandle, K, V> { - fn clone(&self) -> Self { - match self { - LazyLeafHandle::Root(root) => LazyLeafHandle::Root(*root), - LazyLeafHandle::Edge(edge) => LazyLeafHandle::Edge(*edge), - } - } -} - -impl LazyLeafHandle { - fn reborrow(&self) -> LazyLeafHandle, K, V> { - match self { - LazyLeafHandle::Root(root) => LazyLeafHandle::Root(root.reborrow()), - LazyLeafHandle::Edge(edge) => LazyLeafHandle::Edge(edge.reborrow()), - } - } -} - -// `front` and `back` are always both `None` or both `Some`. -pub struct LazyLeafRange { - front: Option>, - back: Option>, -} - -impl Default for LazyLeafRange { - fn default() -> Self { - LazyLeafRange { front: None, back: None } - } -} - -impl<'a, K: 'a, V: 'a> Clone for LazyLeafRange, K, V> { - fn clone(&self) -> Self { - LazyLeafRange { front: self.front.clone(), back: self.back.clone() } - } -} - -impl LazyLeafRange { - pub fn none() -> Self { - LazyLeafRange { front: None, back: None } - } - - /// Temporarily takes out another, immutable equivalent of the same range. - pub fn reborrow(&self) -> LazyLeafRange, K, V> { - LazyLeafRange { - front: self.front.as_ref().map(|f| f.reborrow()), - back: self.back.as_ref().map(|b| b.reborrow()), - } - } -} - -impl<'a, K, V> LazyLeafRange, K, V> { - #[inline] - pub unsafe fn next_unchecked(&mut self) -> (&'a K, &'a V) { - unsafe { self.init_front().unwrap().next_unchecked() } - } - - #[inline] - pub unsafe fn next_back_unchecked(&mut self) -> (&'a K, &'a V) { - unsafe { self.init_back().unwrap().next_back_unchecked() } - } -} - -impl<'a, K, V> LazyLeafRange, K, V> { - #[inline] - pub unsafe fn next_unchecked(&mut self) -> (&'a K, &'a mut V) { - unsafe { self.init_front().unwrap().next_unchecked() } - } - - #[inline] - pub unsafe fn next_back_unchecked(&mut self) -> (&'a K, &'a mut V) { - unsafe { self.init_back().unwrap().next_back_unchecked() } - } -} - -impl LazyLeafRange { - fn take_front( - &mut self, - ) -> Option, marker::Edge>> { - match self.front.take()? { - LazyLeafHandle::Root(root) => Some(root.first_leaf_edge()), - LazyLeafHandle::Edge(edge) => Some(edge), - } - } - - #[inline] - pub unsafe fn deallocating_next_unchecked( - &mut self, - alloc: A, - ) -> Handle, marker::KV> { - debug_assert!(self.front.is_some()); - let front = self.init_front().unwrap(); - unsafe { front.deallocating_next_unchecked(alloc) } - } - - #[inline] - pub unsafe fn deallocating_next_back_unchecked( - &mut self, - alloc: A, - ) -> Handle, marker::KV> { - debug_assert!(self.back.is_some()); - let back = self.init_back().unwrap(); - unsafe { back.deallocating_next_back_unchecked(alloc) } - } - - #[inline] - pub fn deallocating_end(&mut self, alloc: A) { - if let Some(front) = self.take_front() { - front.deallocating_end(alloc) - } - } -} - -impl LazyLeafRange { - fn init_front( - &mut self, - ) -> Option<&mut Handle, marker::Edge>> { - if let Some(LazyLeafHandle::Root(root)) = &self.front { - self.front = Some(LazyLeafHandle::Edge(unsafe { ptr::read(root) }.first_leaf_edge())); - } - match &mut self.front { - None => None, - Some(LazyLeafHandle::Edge(edge)) => Some(edge), - // SAFETY: the code above would have replaced it. - Some(LazyLeafHandle::Root(_)) => unsafe { hint::unreachable_unchecked() }, - } - } - - fn init_back( - &mut self, - ) -> Option<&mut Handle, marker::Edge>> { - if let Some(LazyLeafHandle::Root(root)) = &self.back { - self.back = Some(LazyLeafHandle::Edge(unsafe { ptr::read(root) }.last_leaf_edge())); - } - match &mut self.back { - None => None, - Some(LazyLeafHandle::Edge(edge)) => Some(edge), - // SAFETY: the code above would have replaced it. - Some(LazyLeafHandle::Root(_)) => unsafe { hint::unreachable_unchecked() }, - } - } -} - -impl NodeRef { - /// Finds the distinct leaf edges delimiting a specified range in a tree. - /// - /// If such distinct edges exist, returns them in ascending order, meaning - /// that a non-zero number of calls to `next_unchecked` on the `front` of - /// the result and/or calls to `next_back_unchecked` on the `back` of the - /// result will eventually reach the same edge. - /// - /// If there are no such edges, i.e., if the tree contains no key within - /// the range, returns an empty `front` and `back`. - /// - /// # Safety - /// Unless `BorrowType` is `Immut`, do not use the handles to visit the same - /// KV twice. - unsafe fn find_leaf_edges_spanning_range( - self, - range: R, - ) -> LeafRange - where - Q: Ord, - K: Borrow, - R: RangeBounds, - { - match self.search_tree_for_bifurcation(&range) { - Err(_) => LeafRange::none(), - Ok(( - node, - lower_edge_idx, - upper_edge_idx, - mut lower_child_bound, - mut upper_child_bound, - )) => { - let mut lower_edge = unsafe { Handle::new_edge(ptr::read(&node), lower_edge_idx) }; - let mut upper_edge = unsafe { Handle::new_edge(node, upper_edge_idx) }; - loop { - match (lower_edge.force(), upper_edge.force()) { - (Leaf(f), Leaf(b)) => return LeafRange { front: Some(f), back: Some(b) }, - (Internal(f), Internal(b)) => { - (lower_edge, lower_child_bound) = - f.descend().find_lower_bound_edge(lower_child_bound); - (upper_edge, upper_child_bound) = - b.descend().find_upper_bound_edge(upper_child_bound); - } - _ => unreachable!("BTreeMap has different depths"), - } - } - } - } - } -} - -fn full_range( - root1: NodeRef, - root2: NodeRef, -) -> LazyLeafRange { - LazyLeafRange { - front: Some(LazyLeafHandle::Root(root1)), - back: Some(LazyLeafHandle::Root(root2)), - } -} - -impl<'a, K: 'a, V: 'a> NodeRef, K, V, marker::LeafOrInternal> { - /// Finds the pair of leaf edges delimiting a specific range in a tree. - /// - /// The result is meaningful only if the tree is ordered by key, like the tree - /// in a `BTreeMap` is. - pub fn range_search(self, range: R) -> LeafRange, K, V> - where - Q: ?Sized + Ord, - K: Borrow, - R: RangeBounds, - { - // SAFETY: our borrow type is immutable. - unsafe { self.find_leaf_edges_spanning_range(range) } - } - - /// Finds the pair of leaf edges delimiting an entire tree. - pub fn full_range(self) -> LazyLeafRange, K, V> { - full_range(self, self) - } -} - -impl<'a, K: 'a, V: 'a> NodeRef, K, V, marker::LeafOrInternal> { - /// Splits a unique reference into a pair of leaf edges delimiting a specified range. - /// The result are non-unique references allowing (some) mutation, which must be used - /// carefully. - /// - /// The result is meaningful only if the tree is ordered by key, like the tree - /// in a `BTreeMap` is. - /// - /// # Safety - /// Do not use the duplicate handles to visit the same KV twice. - pub fn range_search(self, range: R) -> LeafRange, K, V> - where - Q: ?Sized + Ord, - K: Borrow, - R: RangeBounds, - { - unsafe { self.find_leaf_edges_spanning_range(range) } - } - - /// Splits a unique reference into a pair of leaf edges delimiting the full range of the tree. - /// The results are non-unique references allowing mutation (of values only), so must be used - /// with care. - pub fn full_range(self) -> LazyLeafRange, K, V> { - // We duplicate the root NodeRef here -- we will never visit the same KV - // twice, and never end up with overlapping value references. - let self2 = unsafe { ptr::read(&self) }; - full_range(self, self2) - } -} - -impl NodeRef { - /// Splits a unique reference into a pair of leaf edges delimiting the full range of the tree. - /// The results are non-unique references allowing massively destructive mutation, so must be - /// used with the utmost care. - pub fn full_range(self) -> LazyLeafRange { - // We duplicate the root NodeRef here -- we will never access it in a way - // that overlaps references obtained from the root. - let self2 = unsafe { ptr::read(&self) }; - full_range(self, self2) - } -} - -impl - Handle, marker::Edge> -{ - /// Given a leaf edge handle, returns [`Result::Ok`] with a handle to the neighboring KV - /// on the right side, which is either in the same leaf node or in an ancestor node. - /// If the leaf edge is the last one in the tree, returns [`Result::Err`] with the root node. - pub fn next_kv( - self, - ) -> Result< - Handle, marker::KV>, - NodeRef, - > { - let mut edge = self.forget_node_type(); - loop { - edge = match edge.right_kv() { - Ok(kv) => return Ok(kv), - Err(last_edge) => match last_edge.into_node().ascend() { - Ok(parent_edge) => parent_edge.forget_node_type(), - Err(root) => return Err(root), - }, - } - } - } - - /// Given a leaf edge handle, returns [`Result::Ok`] with a handle to the neighboring KV - /// on the left side, which is either in the same leaf node or in an ancestor node. - /// If the leaf edge is the first one in the tree, returns [`Result::Err`] with the root node. - pub fn next_back_kv( - self, - ) -> Result< - Handle, marker::KV>, - NodeRef, - > { - let mut edge = self.forget_node_type(); - loop { - edge = match edge.left_kv() { - Ok(kv) => return Ok(kv), - Err(last_edge) => match last_edge.into_node().ascend() { - Ok(parent_edge) => parent_edge.forget_node_type(), - Err(root) => return Err(root), - }, - } - } - } -} - -impl - Handle, marker::Edge> -{ - /// Given an internal edge handle, returns [`Result::Ok`] with a handle to the neighboring KV - /// on the right side, which is either in the same internal node or in an ancestor node. - /// If the internal edge is the last one in the tree, returns [`Result::Err`] with the root node. - fn next_kv( - self, - ) -> Result< - Handle, marker::KV>, - NodeRef, - > { - let mut edge = self; - loop { - edge = match edge.right_kv() { - Ok(internal_kv) => return Ok(internal_kv), - Err(last_edge) => match last_edge.into_node().ascend() { - Ok(parent_edge) => parent_edge, - Err(root) => return Err(root), - }, - } - } - } -} - -impl Handle, marker::Edge> { - /// Given a leaf edge handle into a dying tree, returns the next leaf edge - /// on the right side, and the key-value pair in between, if they exist. - /// - /// If the given edge is the last one in a leaf, this method deallocates - /// the leaf, as well as any ancestor nodes whose last edge was reached. - /// This implies that if no more key-value pair follows, the entire tree - /// will have been deallocated and there is nothing left to return. - /// - /// # Safety - /// - The given edge must not have been previously returned by counterpart - /// `deallocating_next_back`. - /// - The returned KV handle is only valid to access the key and value, - /// and only valid until the next call to a `deallocating_` method. - unsafe fn deallocating_next( - self, - alloc: A, - ) -> Option<(Self, Handle, marker::KV>)> - { - let mut edge = self.forget_node_type(); - loop { - edge = match edge.right_kv() { - Ok(kv) => return Some((unsafe { ptr::read(&kv) }.next_leaf_edge(), kv)), - Err(last_edge) => { - match unsafe { last_edge.into_node().deallocate_and_ascend(alloc.clone()) } { - Some(parent_edge) => parent_edge.forget_node_type(), - None => return None, - } - } - } - } - } - - /// Given a leaf edge handle into a dying tree, returns the next leaf edge - /// on the left side, and the key-value pair in between, if they exist. - /// - /// If the given edge is the first one in a leaf, this method deallocates - /// the leaf, as well as any ancestor nodes whose first edge was reached. - /// This implies that if no more key-value pair follows, the entire tree - /// will have been deallocated and there is nothing left to return. - /// - /// # Safety - /// - The given edge must not have been previously returned by counterpart - /// `deallocating_next`. - /// - The returned KV handle is only valid to access the key and value, - /// and only valid until the next call to a `deallocating_` method. - unsafe fn deallocating_next_back( - self, - alloc: A, - ) -> Option<(Self, Handle, marker::KV>)> - { - let mut edge = self.forget_node_type(); - loop { - edge = match edge.left_kv() { - Ok(kv) => return Some((unsafe { ptr::read(&kv) }.next_back_leaf_edge(), kv)), - Err(last_edge) => { - match unsafe { last_edge.into_node().deallocate_and_ascend(alloc.clone()) } { - Some(parent_edge) => parent_edge.forget_node_type(), - None => return None, - } - } - } - } - } - - /// Deallocates a pile of nodes from the leaf up to the root. - /// This is the only way to deallocate the remainder of a tree after - /// `deallocating_next` and `deallocating_next_back` have been nibbling at - /// both sides of the tree, and have hit the same edge. As it is intended - /// only to be called when all keys and values have been returned, - /// no cleanup is done on any of the keys or values. - fn deallocating_end(self, alloc: A) { - let mut edge = self.forget_node_type(); - while let Some(parent_edge) = - unsafe { edge.into_node().deallocate_and_ascend(alloc.clone()) } - { - edge = parent_edge.forget_node_type(); - } - } -} - -impl<'a, K, V> Handle, K, V, marker::Leaf>, marker::Edge> { - /// Moves the leaf edge handle to the next leaf edge and returns references to the - /// key and value in between. - /// - /// # Safety - /// There must be another KV in the direction travelled. - unsafe fn next_unchecked(&mut self) -> (&'a K, &'a V) { - super::mem::replace(self, |leaf_edge| { - let kv = leaf_edge.next_kv().ok().unwrap(); - (kv.next_leaf_edge(), kv.into_kv()) - }) - } - - /// Moves the leaf edge handle to the previous leaf edge and returns references to the - /// key and value in between. - /// - /// # Safety - /// There must be another KV in the direction travelled. - unsafe fn next_back_unchecked(&mut self) -> (&'a K, &'a V) { - super::mem::replace(self, |leaf_edge| { - let kv = leaf_edge.next_back_kv().ok().unwrap(); - (kv.next_back_leaf_edge(), kv.into_kv()) - }) - } -} - -impl<'a, K, V> Handle, K, V, marker::Leaf>, marker::Edge> { - /// Moves the leaf edge handle to the next leaf edge and returns references to the - /// key and value in between. - /// - /// # Safety - /// There must be another KV in the direction travelled. - unsafe fn next_unchecked(&mut self) -> (&'a K, &'a mut V) { - let kv = super::mem::replace(self, |leaf_edge| { - let kv = leaf_edge.next_kv().ok().unwrap(); - (unsafe { ptr::read(&kv) }.next_leaf_edge(), kv) - }); - // Doing this last is faster, according to benchmarks. - kv.into_kv_valmut() - } - - /// Moves the leaf edge handle to the previous leaf and returns references to the - /// key and value in between. - /// - /// # Safety - /// There must be another KV in the direction travelled. - unsafe fn next_back_unchecked(&mut self) -> (&'a K, &'a mut V) { - let kv = super::mem::replace(self, |leaf_edge| { - let kv = leaf_edge.next_back_kv().ok().unwrap(); - (unsafe { ptr::read(&kv) }.next_back_leaf_edge(), kv) - }); - // Doing this last is faster, according to benchmarks. - kv.into_kv_valmut() - } -} - -impl Handle, marker::Edge> { - /// Moves the leaf edge handle to the next leaf edge and returns the key and value - /// in between, deallocating any node left behind while leaving the corresponding - /// edge in its parent node dangling. - /// - /// # Safety - /// - There must be another KV in the direction travelled. - /// - That KV was not previously returned by counterpart - /// `deallocating_next_back_unchecked` on any copy of the handles - /// being used to traverse the tree. - /// - /// The only safe way to proceed with the updated handle is to compare it, drop it, - /// or call this method or counterpart `deallocating_next_back_unchecked` again. - unsafe fn deallocating_next_unchecked( - &mut self, - alloc: A, - ) -> Handle, marker::KV> { - super::mem::replace(self, |leaf_edge| unsafe { - leaf_edge.deallocating_next(alloc).unwrap() - }) - } - - /// Moves the leaf edge handle to the previous leaf edge and returns the key and value - /// in between, deallocating any node left behind while leaving the corresponding - /// edge in its parent node dangling. - /// - /// # Safety - /// - There must be another KV in the direction travelled. - /// - That leaf edge was not previously returned by counterpart - /// `deallocating_next_unchecked` on any copy of the handles - /// being used to traverse the tree. - /// - /// The only safe way to proceed with the updated handle is to compare it, drop it, - /// or call this method or counterpart `deallocating_next_unchecked` again. - unsafe fn deallocating_next_back_unchecked( - &mut self, - alloc: A, - ) -> Handle, marker::KV> { - super::mem::replace(self, |leaf_edge| unsafe { - leaf_edge.deallocating_next_back(alloc).unwrap() - }) - } -} - -impl NodeRef { - /// Returns the leftmost leaf edge in or underneath a node - in other words, the edge - /// you need first when navigating forward (or last when navigating backward). - #[inline] - pub fn first_leaf_edge(self) -> Handle, marker::Edge> { - let mut node = self; - loop { - match node.force() { - Leaf(leaf) => return leaf.first_edge(), - Internal(internal) => node = internal.first_edge().descend(), - } - } - } - - /// Returns the rightmost leaf edge in or underneath a node - in other words, the edge - /// you need last when navigating forward (or first when navigating backward). - #[inline] - pub fn last_leaf_edge(self) -> Handle, marker::Edge> { - let mut node = self; - loop { - match node.force() { - Leaf(leaf) => return leaf.last_edge(), - Internal(internal) => node = internal.last_edge().descend(), - } - } - } -} - -pub enum Position { - Leaf(NodeRef), - Internal(NodeRef), - InternalKV, -} - -impl<'a, K: 'a, V: 'a> NodeRef, K, V, marker::LeafOrInternal> { - /// Visits leaf nodes and internal KVs in order of ascending keys, and also - /// visits internal nodes as a whole in a depth first order, meaning that - /// internal nodes precede their individual KVs and their child nodes. - pub fn visit_nodes_in_order(self, mut visit: F) - where - F: FnMut(Position, K, V>), - { - match self.force() { - Leaf(leaf) => visit(Position::Leaf(leaf)), - Internal(internal) => { - visit(Position::Internal(internal)); - let mut edge = internal.first_edge(); - loop { - edge = match edge.descend().force() { - Leaf(leaf) => { - visit(Position::Leaf(leaf)); - match edge.next_kv() { - Ok(kv) => { - visit(Position::InternalKV); - kv.right_edge() - } - Err(_) => return, - } - } - Internal(internal) => { - visit(Position::Internal(internal)); - internal.first_edge() - } - } - } - } - } - } - - /// Calculates the number of elements in a (sub)tree. - pub fn calc_length(self) -> usize { - let mut result = 0; - self.visit_nodes_in_order(|pos| match pos { - Position::Leaf(node) => result += node.len(), - Position::Internal(node) => result += node.len(), - Position::InternalKV => (), - }); - result - } -} - -impl - Handle, marker::KV> -{ - /// Returns the leaf edge closest to a KV for forward navigation. - pub fn next_leaf_edge(self) -> Handle, marker::Edge> { - match self.force() { - Leaf(leaf_kv) => leaf_kv.right_edge(), - Internal(internal_kv) => { - let next_internal_edge = internal_kv.right_edge(); - next_internal_edge.descend().first_leaf_edge() - } - } - } - - /// Returns the leaf edge closest to a KV for backward navigation. - pub fn next_back_leaf_edge( - self, - ) -> Handle, marker::Edge> { - match self.force() { - Leaf(leaf_kv) => leaf_kv.left_edge(), - Internal(internal_kv) => { - let next_internal_edge = internal_kv.left_edge(); - next_internal_edge.descend().last_leaf_edge() - } - } - } -} - -impl NodeRef { - /// Returns the leaf edge corresponding to the first point at which the - /// given bound is true. - pub fn lower_bound( - self, - mut bound: SearchBound<&Q>, - ) -> Handle, marker::Edge> - where - Q: Ord, - K: Borrow, - { - let mut node = self; - loop { - let (edge, new_bound) = node.find_lower_bound_edge(bound); - match edge.force() { - Leaf(edge) => return edge, - Internal(edge) => { - node = edge.descend(); - bound = new_bound; - } - } - } - } - - /// Returns the leaf edge corresponding to the last point at which the - /// given bound is true. - pub fn upper_bound( - self, - mut bound: SearchBound<&Q>, - ) -> Handle, marker::Edge> - where - Q: Ord, - K: Borrow, - { - let mut node = self; - loop { - let (edge, new_bound) = node.find_upper_bound_edge(bound); - match edge.force() { - Leaf(edge) => return edge, - Internal(edge) => { - node = edge.descend(); - bound = new_bound; - } - } - } - } -} diff --git a/library/alloc/src/collections/btree/node.rs b/library/alloc/src/collections/btree/node.rs deleted file mode 100644 index 78ccb3af66dbb..0000000000000 --- a/library/alloc/src/collections/btree/node.rs +++ /dev/null @@ -1,1846 +0,0 @@ -// This is an attempt at an implementation following the ideal -// -// ``` -// struct BTreeMap { -// height: usize, -// root: Option>> -// } -// -// struct Node { -// keys: [K; 2 * B - 1], -// vals: [V; 2 * B - 1], -// edges: [if height > 0 { Box> } else { () }; 2 * B], -// parent: Option<(NonNull>, u16)>, -// len: u16, -// } -// ``` -// -// Since Rust doesn't actually have dependent types and polymorphic recursion, -// we make do with lots of unsafety. - -// A major goal of this module is to avoid complexity by treating the tree as a generic (if -// weirdly shaped) container and avoiding dealing with most of the B-Tree invariants. As such, -// this module doesn't care whether the entries are sorted, which nodes can be underfull, or -// even what underfull means. However, we do rely on a few invariants: -// -// - Trees must have uniform depth/height. This means that every path down to a leaf from a -// given node has exactly the same length. -// - A node of length `n` has `n` keys, `n` values, and `n + 1` edges. -// This implies that even an empty node has at least one edge. -// For a leaf node, "having an edge" only means we can identify a position in the node, -// since leaf edges are empty and need no data representation. In an internal node, -// an edge both identifies a position and contains a pointer to a child node. - -use core::marker::PhantomData; -use core::mem::{self, MaybeUninit}; -use core::ptr::{self, NonNull}; -use core::slice::SliceIndex; - -use crate::alloc::{Allocator, Layout}; -use crate::boxed::Box; - -const B: usize = 6; -pub const CAPACITY: usize = 2 * B - 1; -pub const MIN_LEN_AFTER_SPLIT: usize = B - 1; -const KV_IDX_CENTER: usize = B - 1; -const EDGE_IDX_LEFT_OF_CENTER: usize = B - 1; -const EDGE_IDX_RIGHT_OF_CENTER: usize = B; - -/// The underlying representation of leaf nodes and part of the representation of internal nodes. -struct LeafNode { - /// We want to be covariant in `K` and `V`. - parent: Option>>, - - /// This node's index into the parent node's `edges` array. - /// `*node.parent.edges[node.parent_idx]` should be the same thing as `node`. - /// This is only guaranteed to be initialized when `parent` is non-null. - parent_idx: MaybeUninit, - - /// The number of keys and values this node stores. - len: u16, - - /// The arrays storing the actual data of the node. Only the first `len` elements of each - /// array are initialized and valid. - keys: [MaybeUninit; CAPACITY], - vals: [MaybeUninit; CAPACITY], -} - -impl LeafNode { - /// Initializes a new `LeafNode` in-place. - unsafe fn init(this: *mut Self) { - // As a general policy, we leave fields uninitialized if they can be, as this should - // be both slightly faster and easier to track in Valgrind. - unsafe { - // parent_idx, keys, and vals are all MaybeUninit - ptr::addr_of_mut!((*this).parent).write(None); - ptr::addr_of_mut!((*this).len).write(0); - } - } - - /// Creates a new boxed `LeafNode`. - fn new(alloc: A) -> Box { - unsafe { - let mut leaf = Box::new_uninit_in(alloc); - LeafNode::init(leaf.as_mut_ptr()); - leaf.assume_init() - } - } -} - -/// The underlying representation of internal nodes. As with `LeafNode`s, these should be hidden -/// behind `BoxedNode`s to prevent dropping uninitialized keys and values. Any pointer to an -/// `InternalNode` can be directly cast to a pointer to the underlying `LeafNode` portion of the -/// node, allowing code to act on leaf and internal nodes generically without having to even check -/// which of the two a pointer is pointing at. This property is enabled by the use of `repr(C)`. -#[repr(C)] -// gdb_providers.py uses this type name for introspection. -struct InternalNode { - data: LeafNode, - - /// The pointers to the children of this node. `len + 1` of these are considered - /// initialized and valid, except that near the end, while the tree is held - /// through borrow type `Dying`, some of these pointers are dangling. - edges: [MaybeUninit>; 2 * B], -} - -impl InternalNode { - /// Creates a new boxed `InternalNode`. - /// - /// # Safety - /// An invariant of internal nodes is that they have at least one - /// initialized and valid edge. This function does not set up - /// such an edge. - unsafe fn new(alloc: A) -> Box { - unsafe { - let mut node = Box::::new_uninit_in(alloc); - // We only need to initialize the data; the edges are MaybeUninit. - LeafNode::init(ptr::addr_of_mut!((*node.as_mut_ptr()).data)); - node.assume_init() - } - } -} - -/// A managed, non-null pointer to a node. This is either an owned pointer to -/// `LeafNode` or an owned pointer to `InternalNode`. -/// -/// However, `BoxedNode` contains no information as to which of the two types -/// of nodes it actually contains, and, partially due to this lack of information, -/// is not a separate type and has no destructor. -type BoxedNode = NonNull>; - -// N.B. `NodeRef` is always covariant in `K` and `V`, even when the `BorrowType` -// is `Mut`. This is technically wrong, but cannot result in any unsafety due to -// internal use of `NodeRef` because we stay completely generic over `K` and `V`. -// However, whenever a public type wraps `NodeRef`, make sure that it has the -// correct variance. -/// -/// A reference to a node. -/// -/// This type has a number of parameters that controls how it acts: -/// - `BorrowType`: A dummy type that describes the kind of borrow and carries a lifetime. -/// - When this is `Immut<'a>`, the `NodeRef` acts roughly like `&'a Node`. -/// - When this is `ValMut<'a>`, the `NodeRef` acts roughly like `&'a Node` -/// with respect to keys and tree structure, but also allows many -/// mutable references to values throughout the tree to coexist. -/// - When this is `Mut<'a>`, the `NodeRef` acts roughly like `&'a mut Node`, -/// although insert methods allow a mutable pointer to a value to coexist. -/// - When this is `Owned`, the `NodeRef` acts roughly like `Box`, -/// but does not have a destructor, and must be cleaned up manually. -/// - When this is `Dying`, the `NodeRef` still acts roughly like `Box`, -/// but has methods to destroy the tree bit by bit, and ordinary methods, -/// while not marked as unsafe to call, can invoke UB if called incorrectly. -/// Since any `NodeRef` allows navigating through the tree, `BorrowType` -/// effectively applies to the entire tree, not just to the node itself. -/// - `K` and `V`: These are the types of keys and values stored in the nodes. -/// - `Type`: This can be `Leaf`, `Internal`, or `LeafOrInternal`. When this is -/// `Leaf`, the `NodeRef` points to a leaf node, when this is `Internal` the -/// `NodeRef` points to an internal node, and when this is `LeafOrInternal` the -/// `NodeRef` could be pointing to either type of node. -/// `Type` is named `NodeType` when used outside `NodeRef`. -/// -/// Both `BorrowType` and `NodeType` restrict what methods we implement, to -/// exploit static type safety. There are limitations in the way we can apply -/// such restrictions: -/// - For each type parameter, we can only define a method either generically -/// or for one particular type. For example, we cannot define a method like -/// `into_kv` generically for all `BorrowType`, or once for all types that -/// carry a lifetime, because we want it to return `&'a` references. -/// Therefore, we define it only for the least powerful type `Immut<'a>`. -/// - We cannot get implicit coercion from say `Mut<'a>` to `Immut<'a>`. -/// Therefore, we have to explicitly call `reborrow` on a more powerful -/// `NodeRef` in order to reach a method like `into_kv`. -/// -/// All methods on `NodeRef` that return some kind of reference, either: -/// - Take `self` by value, and return the lifetime carried by `BorrowType`. -/// Sometimes, to invoke such a method, we need to call `reborrow_mut`. -/// - Take `self` by reference, and (implicitly) return that reference's -/// lifetime, instead of the lifetime carried by `BorrowType`. That way, -/// the borrow checker guarantees that the `NodeRef` remains borrowed as long -/// as the returned reference is used. -/// The methods supporting insert bend this rule by returning a raw pointer, -/// i.e., a reference without any lifetime. -pub struct NodeRef { - /// The number of levels that the node and the level of leaves are apart, a - /// constant of the node that cannot be entirely described by `Type`, and that - /// the node itself does not store. We only need to store the height of the root - /// node, and derive every other node's height from it. - /// Must be zero if `Type` is `Leaf` and non-zero if `Type` is `Internal`. - height: usize, - /// The pointer to the leaf or internal node. The definition of `InternalNode` - /// ensures that the pointer is valid either way. - node: NonNull>, - _marker: PhantomData<(BorrowType, Type)>, -} - -/// The root node of an owned tree. -/// -/// Note that this does not have a destructor, and must be cleaned up manually. -pub type Root = NodeRef; - -impl<'a, K: 'a, V: 'a, Type> Copy for NodeRef, K, V, Type> {} -impl<'a, K: 'a, V: 'a, Type> Clone for NodeRef, K, V, Type> { - fn clone(&self) -> Self { - *self - } -} - -unsafe impl Sync for NodeRef {} - -unsafe impl Send for NodeRef, K, V, Type> {} -unsafe impl Send for NodeRef, K, V, Type> {} -unsafe impl Send for NodeRef, K, V, Type> {} -unsafe impl Send for NodeRef {} -unsafe impl Send for NodeRef {} - -impl NodeRef { - pub fn new_leaf(alloc: A) -> Self { - Self::from_new_leaf(LeafNode::new(alloc)) - } - - fn from_new_leaf(leaf: Box, A>) -> Self { - NodeRef { height: 0, node: NonNull::from(Box::leak(leaf)), _marker: PhantomData } - } -} - -impl NodeRef { - fn new_internal(child: Root, alloc: A) -> Self { - let mut new_node = unsafe { InternalNode::new(alloc) }; - new_node.edges[0].write(child.node); - unsafe { NodeRef::from_new_internal(new_node, child.height + 1) } - } - - /// # Safety - /// `height` must not be zero. - unsafe fn from_new_internal( - internal: Box, A>, - height: usize, - ) -> Self { - debug_assert!(height > 0); - let node = NonNull::from(Box::leak(internal)).cast(); - let mut this = NodeRef { height, node, _marker: PhantomData }; - this.borrow_mut().correct_all_childrens_parent_links(); - this - } -} - -impl NodeRef { - /// Unpack a node reference that was packed as `NodeRef::parent`. - fn from_internal(node: NonNull>, height: usize) -> Self { - debug_assert!(height > 0); - NodeRef { height, node: node.cast(), _marker: PhantomData } - } -} - -impl NodeRef { - /// Exposes the data of an internal node. - /// - /// Returns a raw ptr to avoid invalidating other references to this node. - fn as_internal_ptr(this: &Self) -> *mut InternalNode { - // SAFETY: the static node type is `Internal`. - this.node.as_ptr() as *mut InternalNode - } -} - -impl<'a, K, V> NodeRef, K, V, marker::Internal> { - /// Borrows exclusive access to the data of an internal node. - fn as_internal_mut(&mut self) -> &mut InternalNode { - let ptr = Self::as_internal_ptr(self); - unsafe { &mut *ptr } - } -} - -impl NodeRef { - /// Finds the length of the node. This is the number of keys or values. - /// The number of edges is `len() + 1`. - /// Note that, despite being safe, calling this function can have the side effect - /// of invalidating mutable references that unsafe code has created. - pub fn len(&self) -> usize { - // Crucially, we only access the `len` field here. If BorrowType is marker::ValMut, - // there might be outstanding mutable references to values that we must not invalidate. - unsafe { usize::from((*Self::as_leaf_ptr(self)).len) } - } - - /// Returns the number of levels that the node and leaves are apart. Zero - /// height means the node is a leaf itself. If you picture trees with the - /// root on top, the number says at which elevation the node appears. - /// If you picture trees with leaves on top, the number says how high - /// the tree extends above the node. - pub fn height(&self) -> usize { - self.height - } - - /// Temporarily takes out another, immutable reference to the same node. - pub fn reborrow(&self) -> NodeRef, K, V, Type> { - NodeRef { height: self.height, node: self.node, _marker: PhantomData } - } - - /// Exposes the leaf portion of any leaf or internal node. - /// - /// Returns a raw ptr to avoid invalidating other references to this node. - fn as_leaf_ptr(this: &Self) -> *mut LeafNode { - // The node must be valid for at least the LeafNode portion. - // This is not a reference in the NodeRef type because we don't know if - // it should be unique or shared. - this.node.as_ptr() - } -} - -impl NodeRef { - /// Finds the parent of the current node. Returns `Ok(handle)` if the current - /// node actually has a parent, where `handle` points to the edge of the parent - /// that points to the current node. Returns `Err(self)` if the current node has - /// no parent, giving back the original `NodeRef`. - /// - /// The method name assumes you picture trees with the root node on top. - /// - /// `edge.descend().ascend().unwrap()` and `node.ascend().unwrap().descend()` should - /// both, upon success, do nothing. - pub fn ascend( - self, - ) -> Result, marker::Edge>, Self> { - const { - assert!(BorrowType::TRAVERSAL_PERMIT); - } - - // We need to use raw pointers to nodes because, if BorrowType is marker::ValMut, - // there might be outstanding mutable references to values that we must not invalidate. - let leaf_ptr: *const _ = Self::as_leaf_ptr(&self); - unsafe { (*leaf_ptr).parent } - .as_ref() - .map(|parent| Handle { - node: NodeRef::from_internal(*parent, self.height + 1), - idx: unsafe { usize::from((*leaf_ptr).parent_idx.assume_init()) }, - _marker: PhantomData, - }) - .ok_or(self) - } - - pub fn first_edge(self) -> Handle { - unsafe { Handle::new_edge(self, 0) } - } - - pub fn last_edge(self) -> Handle { - let len = self.len(); - unsafe { Handle::new_edge(self, len) } - } - - /// Note that `self` must be nonempty. - pub fn first_kv(self) -> Handle { - let len = self.len(); - assert!(len > 0); - unsafe { Handle::new_kv(self, 0) } - } - - /// Note that `self` must be nonempty. - pub fn last_kv(self) -> Handle { - let len = self.len(); - assert!(len > 0); - unsafe { Handle::new_kv(self, len - 1) } - } -} - -impl NodeRef { - /// Could be a public implementation of PartialEq, but only used in this module. - fn eq(&self, other: &Self) -> bool { - let Self { node, height, _marker } = self; - if node.eq(&other.node) { - debug_assert_eq!(*height, other.height); - true - } else { - false - } - } -} - -impl<'a, K: 'a, V: 'a, Type> NodeRef, K, V, Type> { - /// Exposes the leaf portion of any leaf or internal node in an immutable tree. - fn into_leaf(self) -> &'a LeafNode { - let ptr = Self::as_leaf_ptr(&self); - // SAFETY: there can be no mutable references into this tree borrowed as `Immut`. - unsafe { &*ptr } - } - - /// Borrows a view into the keys stored in the node. - pub fn keys(&self) -> &[K] { - let leaf = self.into_leaf(); - unsafe { - MaybeUninit::slice_assume_init_ref(leaf.keys.get_unchecked(..usize::from(leaf.len))) - } - } -} - -impl NodeRef { - /// Similar to `ascend`, gets a reference to a node's parent node, but also - /// deallocates the current node in the process. This is unsafe because the - /// current node will still be accessible despite being deallocated. - pub unsafe fn deallocate_and_ascend( - self, - alloc: A, - ) -> Option, marker::Edge>> { - let height = self.height; - let node = self.node; - let ret = self.ascend().ok(); - unsafe { - alloc.deallocate( - node.cast(), - if height > 0 { - Layout::new::>() - } else { - Layout::new::>() - }, - ); - } - ret - } -} - -impl<'a, K, V, Type> NodeRef, K, V, Type> { - /// Temporarily takes out another mutable reference to the same node. Beware, as - /// this method is very dangerous, doubly so since it might not immediately appear - /// dangerous. - /// - /// Because mutable pointers can roam anywhere around the tree, the returned - /// pointer can easily be used to make the original pointer dangling, out of - /// bounds, or invalid under stacked borrow rules. - // FIXME(@gereeter) consider adding yet another type parameter to `NodeRef` - // that restricts the use of navigation methods on reborrowed pointers, - // preventing this unsafety. - unsafe fn reborrow_mut(&mut self) -> NodeRef, K, V, Type> { - NodeRef { height: self.height, node: self.node, _marker: PhantomData } - } - - /// Borrows exclusive access to the leaf portion of a leaf or internal node. - fn as_leaf_mut(&mut self) -> &mut LeafNode { - let ptr = Self::as_leaf_ptr(self); - // SAFETY: we have exclusive access to the entire node. - unsafe { &mut *ptr } - } - - /// Offers exclusive access to the leaf portion of a leaf or internal node. - fn into_leaf_mut(mut self) -> &'a mut LeafNode { - let ptr = Self::as_leaf_ptr(&mut self); - // SAFETY: we have exclusive access to the entire node. - unsafe { &mut *ptr } - } - - /// Returns a dormant copy of this node with its lifetime erased which can - /// be reawakened later. - pub fn dormant(&self) -> NodeRef { - NodeRef { height: self.height, node: self.node, _marker: PhantomData } - } -} - -impl NodeRef { - /// Revert to the unique borrow initially captured. - /// - /// # Safety - /// - /// The reborrow must have ended, i.e., the reference returned by `new` and - /// all pointers and references derived from it, must not be used anymore. - pub unsafe fn awaken<'a>(self) -> NodeRef, K, V, Type> { - NodeRef { height: self.height, node: self.node, _marker: PhantomData } - } -} - -impl NodeRef { - /// Borrows exclusive access to the leaf portion of a dying leaf or internal node. - fn as_leaf_dying(&mut self) -> &mut LeafNode { - let ptr = Self::as_leaf_ptr(self); - // SAFETY: we have exclusive access to the entire node. - unsafe { &mut *ptr } - } -} - -impl<'a, K: 'a, V: 'a, Type> NodeRef, K, V, Type> { - /// Borrows exclusive access to an element of the key storage area. - /// - /// # Safety - /// `index` is in bounds of 0..CAPACITY - unsafe fn key_area_mut(&mut self, index: I) -> &mut Output - where - I: SliceIndex<[MaybeUninit], Output = Output>, - { - // SAFETY: the caller will not be able to call further methods on self - // until the key slice reference is dropped, as we have unique access - // for the lifetime of the borrow. - unsafe { self.as_leaf_mut().keys.as_mut_slice().get_unchecked_mut(index) } - } - - /// Borrows exclusive access to an element or slice of the node's value storage area. - /// - /// # Safety - /// `index` is in bounds of 0..CAPACITY - unsafe fn val_area_mut(&mut self, index: I) -> &mut Output - where - I: SliceIndex<[MaybeUninit], Output = Output>, - { - // SAFETY: the caller will not be able to call further methods on self - // until the value slice reference is dropped, as we have unique access - // for the lifetime of the borrow. - unsafe { self.as_leaf_mut().vals.as_mut_slice().get_unchecked_mut(index) } - } -} - -impl<'a, K: 'a, V: 'a> NodeRef, K, V, marker::Internal> { - /// Borrows exclusive access to an element or slice of the node's storage area for edge contents. - /// - /// # Safety - /// `index` is in bounds of 0..CAPACITY + 1 - unsafe fn edge_area_mut(&mut self, index: I) -> &mut Output - where - I: SliceIndex<[MaybeUninit>], Output = Output>, - { - // SAFETY: the caller will not be able to call further methods on self - // until the edge slice reference is dropped, as we have unique access - // for the lifetime of the borrow. - unsafe { self.as_internal_mut().edges.as_mut_slice().get_unchecked_mut(index) } - } -} - -impl<'a, K, V, Type> NodeRef, K, V, Type> { - /// # Safety - /// - The node has more than `idx` initialized elements. - unsafe fn into_key_val_mut_at(mut self, idx: usize) -> (&'a K, &'a mut V) { - // We only create a reference to the one element we are interested in, - // to avoid aliasing with outstanding references to other elements, - // in particular, those returned to the caller in earlier iterations. - let leaf = Self::as_leaf_ptr(&mut self); - let keys = unsafe { ptr::addr_of!((*leaf).keys) }; - let vals = unsafe { ptr::addr_of_mut!((*leaf).vals) }; - // We must coerce to unsized array pointers because of Rust issue #74679. - let keys: *const [_] = keys; - let vals: *mut [_] = vals; - let key = unsafe { (&*keys.get_unchecked(idx)).assume_init_ref() }; - let val = unsafe { (&mut *vals.get_unchecked_mut(idx)).assume_init_mut() }; - (key, val) - } -} - -impl<'a, K: 'a, V: 'a, Type> NodeRef, K, V, Type> { - /// Borrows exclusive access to the length of the node. - pub fn len_mut(&mut self) -> &mut u16 { - &mut self.as_leaf_mut().len - } -} - -impl<'a, K, V> NodeRef, K, V, marker::Internal> { - /// # Safety - /// Every item returned by `range` is a valid edge index for the node. - unsafe fn correct_childrens_parent_links>(&mut self, range: R) { - for i in range { - debug_assert!(i <= self.len()); - unsafe { Handle::new_edge(self.reborrow_mut(), i) }.correct_parent_link(); - } - } - - fn correct_all_childrens_parent_links(&mut self) { - let len = self.len(); - unsafe { self.correct_childrens_parent_links(0..=len) }; - } -} - -impl<'a, K: 'a, V: 'a> NodeRef, K, V, marker::LeafOrInternal> { - /// Sets the node's link to its parent edge, - /// without invalidating other references to the node. - fn set_parent_link(&mut self, parent: NonNull>, parent_idx: usize) { - let leaf = Self::as_leaf_ptr(self); - unsafe { (*leaf).parent = Some(parent) }; - unsafe { (*leaf).parent_idx.write(parent_idx as u16) }; - } -} - -impl NodeRef { - /// Clears the root's link to its parent edge. - fn clear_parent_link(&mut self) { - let mut root_node = self.borrow_mut(); - let leaf = root_node.as_leaf_mut(); - leaf.parent = None; - } -} - -impl NodeRef { - /// Returns a new owned tree, with its own root node that is initially empty. - pub fn new(alloc: A) -> Self { - NodeRef::new_leaf(alloc).forget_type() - } - - /// Adds a new internal node with a single edge pointing to the previous root node, - /// make that new node the root node, and return it. This increases the height by 1 - /// and is the opposite of `pop_internal_level`. - pub fn push_internal_level( - &mut self, - alloc: A, - ) -> NodeRef, K, V, marker::Internal> { - super::mem::take_mut(self, |old_root| NodeRef::new_internal(old_root, alloc).forget_type()); - - // `self.borrow_mut()`, except that we just forgot we're internal now: - NodeRef { height: self.height, node: self.node, _marker: PhantomData } - } - - /// Removes the internal root node, using its first child as the new root node. - /// As it is intended only to be called when the root node has only one child, - /// no cleanup is done on any of the keys, values and other children. - /// This decreases the height by 1 and is the opposite of `push_internal_level`. - /// - /// Requires exclusive access to the `NodeRef` object but not to the root node; - /// it will not invalidate other handles or references to the root node. - /// - /// Panics if there is no internal level, i.e., if the root node is a leaf. - pub fn pop_internal_level(&mut self, alloc: A) { - assert!(self.height > 0); - - let top = self.node; - - // SAFETY: we asserted to be internal. - let internal_self = unsafe { self.borrow_mut().cast_to_internal_unchecked() }; - // SAFETY: we borrowed `self` exclusively and its borrow type is exclusive. - let internal_node = unsafe { &mut *NodeRef::as_internal_ptr(&internal_self) }; - // SAFETY: the first edge is always initialized. - self.node = unsafe { internal_node.edges[0].assume_init_read() }; - self.height -= 1; - self.clear_parent_link(); - - unsafe { - alloc.deallocate(top.cast(), Layout::new::>()); - } - } -} - -impl NodeRef { - /// Mutably borrows the owned root node. Unlike `reborrow_mut`, this is safe - /// because the return value cannot be used to destroy the root, and there - /// cannot be other references to the tree. - pub fn borrow_mut(&mut self) -> NodeRef, K, V, Type> { - NodeRef { height: self.height, node: self.node, _marker: PhantomData } - } - - /// Slightly mutably borrows the owned root node. - pub fn borrow_valmut(&mut self) -> NodeRef, K, V, Type> { - NodeRef { height: self.height, node: self.node, _marker: PhantomData } - } - - /// Irreversibly transitions to a reference that permits traversal and offers - /// destructive methods and little else. - pub fn into_dying(self) -> NodeRef { - NodeRef { height: self.height, node: self.node, _marker: PhantomData } - } -} - -impl<'a, K: 'a, V: 'a> NodeRef, K, V, marker::Leaf> { - /// Adds a key-value pair to the end of the node, and returns - /// a handle to the inserted value. - /// - /// # Safety - /// - /// The returned handle has an unbound lifetime. - pub unsafe fn push_with_handle<'b>( - &mut self, - key: K, - val: V, - ) -> Handle, K, V, marker::Leaf>, marker::KV> { - let len = self.len_mut(); - let idx = usize::from(*len); - assert!(idx < CAPACITY); - *len += 1; - unsafe { - self.key_area_mut(idx).write(key); - self.val_area_mut(idx).write(val); - Handle::new_kv( - NodeRef { height: self.height, node: self.node, _marker: PhantomData }, - idx, - ) - } - } - - /// Adds a key-value pair to the end of the node, and returns - /// the mutable reference of the inserted value. - pub fn push(&mut self, key: K, val: V) -> *mut V { - // SAFETY: The unbound handle is no longer accessible. - unsafe { self.push_with_handle(key, val).into_val_mut() } - } -} - -impl<'a, K: 'a, V: 'a> NodeRef, K, V, marker::Internal> { - /// Adds a key-value pair, and an edge to go to the right of that pair, - /// to the end of the node. - pub fn push(&mut self, key: K, val: V, edge: Root) { - assert!(edge.height == self.height - 1); - - let len = self.len_mut(); - let idx = usize::from(*len); - assert!(idx < CAPACITY); - *len += 1; - unsafe { - self.key_area_mut(idx).write(key); - self.val_area_mut(idx).write(val); - self.edge_area_mut(idx + 1).write(edge.node); - Handle::new_edge(self.reborrow_mut(), idx + 1).correct_parent_link(); - } - } -} - -impl NodeRef { - /// Removes any static information asserting that this node is a `Leaf` node. - pub fn forget_type(self) -> NodeRef { - NodeRef { height: self.height, node: self.node, _marker: PhantomData } - } -} - -impl NodeRef { - /// Removes any static information asserting that this node is an `Internal` node. - pub fn forget_type(self) -> NodeRef { - NodeRef { height: self.height, node: self.node, _marker: PhantomData } - } -} - -impl NodeRef { - /// Checks whether a node is an `Internal` node or a `Leaf` node. - pub fn force( - self, - ) -> ForceResult< - NodeRef, - NodeRef, - > { - if self.height == 0 { - ForceResult::Leaf(NodeRef { - height: self.height, - node: self.node, - _marker: PhantomData, - }) - } else { - ForceResult::Internal(NodeRef { - height: self.height, - node: self.node, - _marker: PhantomData, - }) - } - } -} - -impl<'a, K, V> NodeRef, K, V, marker::LeafOrInternal> { - /// Unsafely asserts to the compiler the static information that this node is a `Leaf`. - unsafe fn cast_to_leaf_unchecked(self) -> NodeRef, K, V, marker::Leaf> { - debug_assert!(self.height == 0); - NodeRef { height: self.height, node: self.node, _marker: PhantomData } - } - - /// Unsafely asserts to the compiler the static information that this node is an `Internal`. - unsafe fn cast_to_internal_unchecked(self) -> NodeRef, K, V, marker::Internal> { - debug_assert!(self.height > 0); - NodeRef { height: self.height, node: self.node, _marker: PhantomData } - } -} - -/// A reference to a specific key-value pair or edge within a node. The `Node` parameter -/// must be a `NodeRef`, while the `Type` can either be `KV` (signifying a handle on a key-value -/// pair) or `Edge` (signifying a handle on an edge). -/// -/// Note that even `Leaf` nodes can have `Edge` handles. Instead of representing a pointer to -/// a child node, these represent the spaces where child pointers would go between the key-value -/// pairs. For example, in a node with length 2, there would be 3 possible edge locations - one -/// to the left of the node, one between the two pairs, and one at the right of the node. -pub struct Handle { - node: Node, - idx: usize, - _marker: PhantomData, -} - -impl Copy for Handle {} -// We don't need the full generality of `#[derive(Clone)]`, as the only time `Node` will be -// `Clone`able is when it is an immutable reference and therefore `Copy`. -impl Clone for Handle { - fn clone(&self) -> Self { - *self - } -} - -impl Handle { - /// Retrieves the node that contains the edge or key-value pair this handle points to. - pub fn into_node(self) -> Node { - self.node - } - - /// Returns the position of this handle in the node. - pub fn idx(&self) -> usize { - self.idx - } -} - -impl Handle, marker::KV> { - /// Creates a new handle to a key-value pair in `node`. - /// Unsafe because the caller must ensure that `idx < node.len()`. - pub unsafe fn new_kv(node: NodeRef, idx: usize) -> Self { - debug_assert!(idx < node.len()); - - Handle { node, idx, _marker: PhantomData } - } - - pub fn left_edge(self) -> Handle, marker::Edge> { - unsafe { Handle::new_edge(self.node, self.idx) } - } - - pub fn right_edge(self) -> Handle, marker::Edge> { - unsafe { Handle::new_edge(self.node, self.idx + 1) } - } -} - -impl PartialEq - for Handle, HandleType> -{ - fn eq(&self, other: &Self) -> bool { - let Self { node, idx, _marker } = self; - node.eq(&other.node) && *idx == other.idx - } -} - -impl - Handle, HandleType> -{ - /// Temporarily takes out another immutable handle on the same location. - pub fn reborrow(&self) -> Handle, K, V, NodeType>, HandleType> { - // We can't use Handle::new_kv or Handle::new_edge because we don't know our type - Handle { node: self.node.reborrow(), idx: self.idx, _marker: PhantomData } - } -} - -impl<'a, K, V, NodeType, HandleType> Handle, K, V, NodeType>, HandleType> { - /// Temporarily takes out another mutable handle on the same location. Beware, as - /// this method is very dangerous, doubly so since it might not immediately appear - /// dangerous. - /// - /// For details, see `NodeRef::reborrow_mut`. - pub unsafe fn reborrow_mut( - &mut self, - ) -> Handle, K, V, NodeType>, HandleType> { - // We can't use Handle::new_kv or Handle::new_edge because we don't know our type - Handle { node: unsafe { self.node.reborrow_mut() }, idx: self.idx, _marker: PhantomData } - } - - /// Returns a dormant copy of this handle which can be reawakened later. - /// - /// See `DormantMutRef` for more details. - pub fn dormant(&self) -> Handle, HandleType> { - Handle { node: self.node.dormant(), idx: self.idx, _marker: PhantomData } - } -} - -impl Handle, HandleType> { - /// Revert to the unique borrow initially captured. - /// - /// # Safety - /// - /// The reborrow must have ended, i.e., the reference returned by `new` and - /// all pointers and references derived from it, must not be used anymore. - pub unsafe fn awaken<'a>(self) -> Handle, K, V, NodeType>, HandleType> { - Handle { node: unsafe { self.node.awaken() }, idx: self.idx, _marker: PhantomData } - } -} - -impl Handle, marker::Edge> { - /// Creates a new handle to an edge in `node`. - /// Unsafe because the caller must ensure that `idx <= node.len()`. - pub unsafe fn new_edge(node: NodeRef, idx: usize) -> Self { - debug_assert!(idx <= node.len()); - - Handle { node, idx, _marker: PhantomData } - } - - pub fn left_kv(self) -> Result, marker::KV>, Self> { - if self.idx > 0 { - Ok(unsafe { Handle::new_kv(self.node, self.idx - 1) }) - } else { - Err(self) - } - } - - pub fn right_kv(self) -> Result, marker::KV>, Self> { - if self.idx < self.node.len() { - Ok(unsafe { Handle::new_kv(self.node, self.idx) }) - } else { - Err(self) - } - } -} - -pub enum LeftOrRight { - Left(T), - Right(T), -} - -/// Given an edge index where we want to insert into a node filled to capacity, -/// computes a sensible KV index of a split point and where to perform the insertion. -/// The goal of the split point is for its key and value to end up in a parent node; -/// the keys, values and edges to the left of the split point become the left child; -/// the keys, values and edges to the right of the split point become the right child. -fn splitpoint(edge_idx: usize) -> (usize, LeftOrRight) { - debug_assert!(edge_idx <= CAPACITY); - // Rust issue #74834 tries to explain these symmetric rules. - match edge_idx { - 0..EDGE_IDX_LEFT_OF_CENTER => (KV_IDX_CENTER - 1, LeftOrRight::Left(edge_idx)), - EDGE_IDX_LEFT_OF_CENTER => (KV_IDX_CENTER, LeftOrRight::Left(edge_idx)), - EDGE_IDX_RIGHT_OF_CENTER => (KV_IDX_CENTER, LeftOrRight::Right(0)), - _ => (KV_IDX_CENTER + 1, LeftOrRight::Right(edge_idx - (KV_IDX_CENTER + 1 + 1))), - } -} - -impl<'a, K: 'a, V: 'a> Handle, K, V, marker::Leaf>, marker::Edge> { - /// Inserts a new key-value pair between the key-value pairs to the right and left of - /// this edge. This method assumes that there is enough space in the node for the new - /// pair to fit. - unsafe fn insert_fit( - mut self, - key: K, - val: V, - ) -> Handle, K, V, marker::Leaf>, marker::KV> { - debug_assert!(self.node.len() < CAPACITY); - let new_len = self.node.len() + 1; - - unsafe { - slice_insert(self.node.key_area_mut(..new_len), self.idx, key); - slice_insert(self.node.val_area_mut(..new_len), self.idx, val); - *self.node.len_mut() = new_len as u16; - - Handle::new_kv(self.node, self.idx) - } - } -} - -impl<'a, K: 'a, V: 'a> Handle, K, V, marker::Leaf>, marker::Edge> { - /// Inserts a new key-value pair between the key-value pairs to the right and left of - /// this edge. This method splits the node if there isn't enough room. - /// - /// Returns a dormant handle to the inserted node which can be reawakened - /// once splitting is complete. - fn insert( - self, - key: K, - val: V, - alloc: A, - ) -> ( - Option>, - Handle, marker::KV>, - ) { - if self.node.len() < CAPACITY { - // SAFETY: There is enough space in the node for insertion. - let handle = unsafe { self.insert_fit(key, val) }; - (None, handle.dormant()) - } else { - let (middle_kv_idx, insertion) = splitpoint(self.idx); - let middle = unsafe { Handle::new_kv(self.node, middle_kv_idx) }; - let mut result = middle.split(alloc); - let insertion_edge = match insertion { - LeftOrRight::Left(insert_idx) => unsafe { - Handle::new_edge(result.left.reborrow_mut(), insert_idx) - }, - LeftOrRight::Right(insert_idx) => unsafe { - Handle::new_edge(result.right.borrow_mut(), insert_idx) - }, - }; - // SAFETY: We just split the node, so there is enough space for - // insertion. - let handle = unsafe { insertion_edge.insert_fit(key, val).dormant() }; - (Some(result), handle) - } - } -} - -impl<'a, K, V> Handle, K, V, marker::Internal>, marker::Edge> { - /// Fixes the parent pointer and index in the child node that this edge - /// links to. This is useful when the ordering of edges has been changed, - fn correct_parent_link(self) { - // Create backpointer without invalidating other references to the node. - let ptr = unsafe { NonNull::new_unchecked(NodeRef::as_internal_ptr(&self.node)) }; - let idx = self.idx; - let mut child = self.descend(); - child.set_parent_link(ptr, idx); - } -} - -impl<'a, K: 'a, V: 'a> Handle, K, V, marker::Internal>, marker::Edge> { - /// Inserts a new key-value pair and an edge that will go to the right of that new pair - /// between this edge and the key-value pair to the right of this edge. This method assumes - /// that there is enough space in the node for the new pair to fit. - fn insert_fit(&mut self, key: K, val: V, edge: Root) { - debug_assert!(self.node.len() < CAPACITY); - debug_assert!(edge.height == self.node.height - 1); - let new_len = self.node.len() + 1; - - unsafe { - slice_insert(self.node.key_area_mut(..new_len), self.idx, key); - slice_insert(self.node.val_area_mut(..new_len), self.idx, val); - slice_insert(self.node.edge_area_mut(..new_len + 1), self.idx + 1, edge.node); - *self.node.len_mut() = new_len as u16; - - self.node.correct_childrens_parent_links(self.idx + 1..new_len + 1); - } - } - - /// Inserts a new key-value pair and an edge that will go to the right of that new pair - /// between this edge and the key-value pair to the right of this edge. This method splits - /// the node if there isn't enough room. - fn insert( - mut self, - key: K, - val: V, - edge: Root, - alloc: A, - ) -> Option> { - assert!(edge.height == self.node.height - 1); - - if self.node.len() < CAPACITY { - self.insert_fit(key, val, edge); - None - } else { - let (middle_kv_idx, insertion) = splitpoint(self.idx); - let middle = unsafe { Handle::new_kv(self.node, middle_kv_idx) }; - let mut result = middle.split(alloc); - let mut insertion_edge = match insertion { - LeftOrRight::Left(insert_idx) => unsafe { - Handle::new_edge(result.left.reborrow_mut(), insert_idx) - }, - LeftOrRight::Right(insert_idx) => unsafe { - Handle::new_edge(result.right.borrow_mut(), insert_idx) - }, - }; - insertion_edge.insert_fit(key, val, edge); - Some(result) - } - } -} - -impl<'a, K: 'a, V: 'a> Handle, K, V, marker::Leaf>, marker::Edge> { - /// Inserts a new key-value pair between the key-value pairs to the right and left of - /// this edge. This method splits the node if there isn't enough room, and tries to - /// insert the split off portion into the parent node recursively, until the root is reached. - /// - /// If the returned result is some `SplitResult`, the `left` field will be the root node. - /// The returned pointer points to the inserted value, which in the case of `SplitResult` - /// is in the `left` or `right` tree. - pub fn insert_recursing( - self, - key: K, - value: V, - alloc: A, - split_root: impl FnOnce(SplitResult<'a, K, V, marker::LeafOrInternal>), - ) -> Handle, K, V, marker::Leaf>, marker::KV> { - let (mut split, handle) = match self.insert(key, value, alloc.clone()) { - // SAFETY: we have finished splitting and can now re-awaken the - // handle to the inserted element. - (None, handle) => return unsafe { handle.awaken() }, - (Some(split), handle) => (split.forget_node_type(), handle), - }; - - loop { - split = match split.left.ascend() { - Ok(parent) => { - match parent.insert(split.kv.0, split.kv.1, split.right, alloc.clone()) { - // SAFETY: we have finished splitting and can now re-awaken the - // handle to the inserted element. - None => return unsafe { handle.awaken() }, - Some(split) => split.forget_node_type(), - } - } - Err(root) => { - split_root(SplitResult { left: root, ..split }); - // SAFETY: we have finished splitting and can now re-awaken the - // handle to the inserted element. - return unsafe { handle.awaken() }; - } - }; - } - } -} - -impl - Handle, marker::Edge> -{ - /// Finds the node pointed to by this edge. - /// - /// The method name assumes you picture trees with the root node on top. - /// - /// `edge.descend().ascend().unwrap()` and `node.ascend().unwrap().descend()` should - /// both, upon success, do nothing. - pub fn descend(self) -> NodeRef { - const { - assert!(BorrowType::TRAVERSAL_PERMIT); - } - - // We need to use raw pointers to nodes because, if BorrowType is - // marker::ValMut, there might be outstanding mutable references to - // values that we must not invalidate. There's no worry accessing the - // height field because that value is copied. Beware that, once the - // node pointer is dereferenced, we access the edges array with a - // reference (Rust issue #73987) and invalidate any other references - // to or inside the array, should any be around. - let parent_ptr = NodeRef::as_internal_ptr(&self.node); - let node = unsafe { (*parent_ptr).edges.get_unchecked(self.idx).assume_init_read() }; - NodeRef { node, height: self.node.height - 1, _marker: PhantomData } - } -} - -impl<'a, K: 'a, V: 'a, NodeType> Handle, K, V, NodeType>, marker::KV> { - pub fn into_kv(self) -> (&'a K, &'a V) { - debug_assert!(self.idx < self.node.len()); - let leaf = self.node.into_leaf(); - let k = unsafe { leaf.keys.get_unchecked(self.idx).assume_init_ref() }; - let v = unsafe { leaf.vals.get_unchecked(self.idx).assume_init_ref() }; - (k, v) - } -} - -impl<'a, K: 'a, V: 'a, NodeType> Handle, K, V, NodeType>, marker::KV> { - pub fn key_mut(&mut self) -> &mut K { - unsafe { self.node.key_area_mut(self.idx).assume_init_mut() } - } - - pub fn into_val_mut(self) -> &'a mut V { - debug_assert!(self.idx < self.node.len()); - let leaf = self.node.into_leaf_mut(); - unsafe { leaf.vals.get_unchecked_mut(self.idx).assume_init_mut() } - } - - pub fn into_kv_mut(self) -> (&'a mut K, &'a mut V) { - debug_assert!(self.idx < self.node.len()); - let leaf = self.node.into_leaf_mut(); - let k = unsafe { leaf.keys.get_unchecked_mut(self.idx).assume_init_mut() }; - let v = unsafe { leaf.vals.get_unchecked_mut(self.idx).assume_init_mut() }; - (k, v) - } -} - -impl<'a, K, V, NodeType> Handle, K, V, NodeType>, marker::KV> { - pub fn into_kv_valmut(self) -> (&'a K, &'a mut V) { - unsafe { self.node.into_key_val_mut_at(self.idx) } - } -} - -impl<'a, K: 'a, V: 'a, NodeType> Handle, K, V, NodeType>, marker::KV> { - pub fn kv_mut(&mut self) -> (&mut K, &mut V) { - debug_assert!(self.idx < self.node.len()); - // We cannot call separate key and value methods, because calling the second one - // invalidates the reference returned by the first. - unsafe { - let leaf = self.node.as_leaf_mut(); - let key = leaf.keys.get_unchecked_mut(self.idx).assume_init_mut(); - let val = leaf.vals.get_unchecked_mut(self.idx).assume_init_mut(); - (key, val) - } - } - - /// Replaces the key and value that the KV handle refers to. - pub fn replace_kv(&mut self, k: K, v: V) -> (K, V) { - let (key, val) = self.kv_mut(); - (mem::replace(key, k), mem::replace(val, v)) - } -} - -impl Handle, marker::KV> { - /// Extracts the key and value that the KV handle refers to. - /// # Safety - /// The node that the handle refers to must not yet have been deallocated. - pub unsafe fn into_key_val(mut self) -> (K, V) { - debug_assert!(self.idx < self.node.len()); - let leaf = self.node.as_leaf_dying(); - unsafe { - let key = leaf.keys.get_unchecked_mut(self.idx).assume_init_read(); - let val = leaf.vals.get_unchecked_mut(self.idx).assume_init_read(); - (key, val) - } - } - - /// Drops the key and value that the KV handle refers to. - /// # Safety - /// The node that the handle refers to must not yet have been deallocated. - #[inline] - pub unsafe fn drop_key_val(mut self) { - debug_assert!(self.idx < self.node.len()); - let leaf = self.node.as_leaf_dying(); - unsafe { - leaf.keys.get_unchecked_mut(self.idx).assume_init_drop(); - leaf.vals.get_unchecked_mut(self.idx).assume_init_drop(); - } - } -} - -impl<'a, K: 'a, V: 'a, NodeType> Handle, K, V, NodeType>, marker::KV> { - /// Helps implementations of `split` for a particular `NodeType`, - /// by taking care of leaf data. - fn split_leaf_data(&mut self, new_node: &mut LeafNode) -> (K, V) { - debug_assert!(self.idx < self.node.len()); - let old_len = self.node.len(); - let new_len = old_len - self.idx - 1; - new_node.len = new_len as u16; - unsafe { - let k = self.node.key_area_mut(self.idx).assume_init_read(); - let v = self.node.val_area_mut(self.idx).assume_init_read(); - - move_to_slice( - self.node.key_area_mut(self.idx + 1..old_len), - &mut new_node.keys[..new_len], - ); - move_to_slice( - self.node.val_area_mut(self.idx + 1..old_len), - &mut new_node.vals[..new_len], - ); - - *self.node.len_mut() = self.idx as u16; - (k, v) - } - } -} - -impl<'a, K: 'a, V: 'a> Handle, K, V, marker::Leaf>, marker::KV> { - /// Splits the underlying node into three parts: - /// - /// - The node is truncated to only contain the key-value pairs to the left of - /// this handle. - /// - The key and value pointed to by this handle are extracted. - /// - All the key-value pairs to the right of this handle are put into a newly - /// allocated node. - pub fn split(mut self, alloc: A) -> SplitResult<'a, K, V, marker::Leaf> { - let mut new_node = LeafNode::new(alloc); - - let kv = self.split_leaf_data(&mut new_node); - - let right = NodeRef::from_new_leaf(new_node); - SplitResult { left: self.node, kv, right } - } - - /// Removes the key-value pair pointed to by this handle and returns it, along with the edge - /// that the key-value pair collapsed into. - pub fn remove( - mut self, - ) -> ((K, V), Handle, K, V, marker::Leaf>, marker::Edge>) { - let old_len = self.node.len(); - unsafe { - let k = slice_remove(self.node.key_area_mut(..old_len), self.idx); - let v = slice_remove(self.node.val_area_mut(..old_len), self.idx); - *self.node.len_mut() = (old_len - 1) as u16; - ((k, v), self.left_edge()) - } - } -} - -impl<'a, K: 'a, V: 'a> Handle, K, V, marker::Internal>, marker::KV> { - /// Splits the underlying node into three parts: - /// - /// - The node is truncated to only contain the edges and key-value pairs to the - /// left of this handle. - /// - The key and value pointed to by this handle are extracted. - /// - All the edges and key-value pairs to the right of this handle are put into - /// a newly allocated node. - pub fn split( - mut self, - alloc: A, - ) -> SplitResult<'a, K, V, marker::Internal> { - let old_len = self.node.len(); - unsafe { - let mut new_node = InternalNode::new(alloc); - let kv = self.split_leaf_data(&mut new_node.data); - let new_len = usize::from(new_node.data.len); - move_to_slice( - self.node.edge_area_mut(self.idx + 1..old_len + 1), - &mut new_node.edges[..new_len + 1], - ); - - let height = self.node.height; - let right = NodeRef::from_new_internal(new_node, height); - - SplitResult { left: self.node, kv, right } - } - } -} - -/// Represents a session for evaluating and performing a balancing operation -/// around an internal key-value pair. -pub struct BalancingContext<'a, K, V> { - parent: Handle, K, V, marker::Internal>, marker::KV>, - left_child: NodeRef, K, V, marker::LeafOrInternal>, - right_child: NodeRef, K, V, marker::LeafOrInternal>, -} - -impl<'a, K, V> Handle, K, V, marker::Internal>, marker::KV> { - pub fn consider_for_balancing(self) -> BalancingContext<'a, K, V> { - let self1 = unsafe { ptr::read(&self) }; - let self2 = unsafe { ptr::read(&self) }; - BalancingContext { - parent: self, - left_child: self1.left_edge().descend(), - right_child: self2.right_edge().descend(), - } - } -} - -impl<'a, K, V> NodeRef, K, V, marker::LeafOrInternal> { - /// Chooses a balancing context involving the node as a child, thus between - /// the KV immediately to the left or to the right in the parent node. - /// Returns an `Err` if there is no parent. - /// Panics if the parent is empty. - /// - /// Prefers the left side, to be optimal if the given node is somehow - /// underfull, meaning here only that it has fewer elements than its left - /// sibling and than its right sibling, if they exist. In that case, - /// merging with the left sibling is faster, since we only need to move - /// the node's N elements, instead of shifting them to the right and moving - /// more than N elements in front. Stealing from the left sibling is also - /// typically faster, since we only need to shift the node's N elements to - /// the right, instead of shifting at least N of the sibling's elements to - /// the left. - pub fn choose_parent_kv(self) -> Result>, Self> { - match unsafe { ptr::read(&self) }.ascend() { - Ok(parent_edge) => match parent_edge.left_kv() { - Ok(left_parent_kv) => Ok(LeftOrRight::Left(BalancingContext { - parent: unsafe { ptr::read(&left_parent_kv) }, - left_child: left_parent_kv.left_edge().descend(), - right_child: self, - })), - Err(parent_edge) => match parent_edge.right_kv() { - Ok(right_parent_kv) => Ok(LeftOrRight::Right(BalancingContext { - parent: unsafe { ptr::read(&right_parent_kv) }, - left_child: self, - right_child: right_parent_kv.right_edge().descend(), - })), - Err(_) => unreachable!("empty internal node"), - }, - }, - Err(root) => Err(root), - } - } -} - -impl<'a, K, V> BalancingContext<'a, K, V> { - pub fn left_child_len(&self) -> usize { - self.left_child.len() - } - - pub fn right_child_len(&self) -> usize { - self.right_child.len() - } - - pub fn into_left_child(self) -> NodeRef, K, V, marker::LeafOrInternal> { - self.left_child - } - - pub fn into_right_child(self) -> NodeRef, K, V, marker::LeafOrInternal> { - self.right_child - } - - /// Returns whether merging is possible, i.e., whether there is enough room - /// in a node to combine the central KV with both adjacent child nodes. - pub fn can_merge(&self) -> bool { - self.left_child.len() + 1 + self.right_child.len() <= CAPACITY - } -} - -impl<'a, K: 'a, V: 'a> BalancingContext<'a, K, V> { - /// Performs a merge and lets a closure decide what to return. - fn do_merge< - F: FnOnce( - NodeRef, K, V, marker::Internal>, - NodeRef, K, V, marker::LeafOrInternal>, - ) -> R, - R, - A: Allocator, - >( - self, - result: F, - alloc: A, - ) -> R { - let Handle { node: mut parent_node, idx: parent_idx, _marker } = self.parent; - let old_parent_len = parent_node.len(); - let mut left_node = self.left_child; - let old_left_len = left_node.len(); - let mut right_node = self.right_child; - let right_len = right_node.len(); - let new_left_len = old_left_len + 1 + right_len; - - assert!(new_left_len <= CAPACITY); - - unsafe { - *left_node.len_mut() = new_left_len as u16; - - let parent_key = slice_remove(parent_node.key_area_mut(..old_parent_len), parent_idx); - left_node.key_area_mut(old_left_len).write(parent_key); - move_to_slice( - right_node.key_area_mut(..right_len), - left_node.key_area_mut(old_left_len + 1..new_left_len), - ); - - let parent_val = slice_remove(parent_node.val_area_mut(..old_parent_len), parent_idx); - left_node.val_area_mut(old_left_len).write(parent_val); - move_to_slice( - right_node.val_area_mut(..right_len), - left_node.val_area_mut(old_left_len + 1..new_left_len), - ); - - slice_remove(&mut parent_node.edge_area_mut(..old_parent_len + 1), parent_idx + 1); - parent_node.correct_childrens_parent_links(parent_idx + 1..old_parent_len); - *parent_node.len_mut() -= 1; - - if parent_node.height > 1 { - // SAFETY: the height of the nodes being merged is one below the height - // of the node of this edge, thus above zero, so they are internal. - let mut left_node = left_node.reborrow_mut().cast_to_internal_unchecked(); - let mut right_node = right_node.cast_to_internal_unchecked(); - move_to_slice( - right_node.edge_area_mut(..right_len + 1), - left_node.edge_area_mut(old_left_len + 1..new_left_len + 1), - ); - - left_node.correct_childrens_parent_links(old_left_len + 1..new_left_len + 1); - - alloc.deallocate(right_node.node.cast(), Layout::new::>()); - } else { - alloc.deallocate(right_node.node.cast(), Layout::new::>()); - } - } - result(parent_node, left_node) - } - - /// Merges the parent's key-value pair and both adjacent child nodes into - /// the left child node and returns the shrunk parent node. - /// - /// Panics unless we `.can_merge()`. - pub fn merge_tracking_parent( - self, - alloc: A, - ) -> NodeRef, K, V, marker::Internal> { - self.do_merge(|parent, _child| parent, alloc) - } - - /// Merges the parent's key-value pair and both adjacent child nodes into - /// the left child node and returns that child node. - /// - /// Panics unless we `.can_merge()`. - pub fn merge_tracking_child( - self, - alloc: A, - ) -> NodeRef, K, V, marker::LeafOrInternal> { - self.do_merge(|_parent, child| child, alloc) - } - - /// Merges the parent's key-value pair and both adjacent child nodes into - /// the left child node and returns the edge handle in that child node - /// where the tracked child edge ended up, - /// - /// Panics unless we `.can_merge()`. - pub fn merge_tracking_child_edge( - self, - track_edge_idx: LeftOrRight, - alloc: A, - ) -> Handle, K, V, marker::LeafOrInternal>, marker::Edge> { - let old_left_len = self.left_child.len(); - let right_len = self.right_child.len(); - assert!(match track_edge_idx { - LeftOrRight::Left(idx) => idx <= old_left_len, - LeftOrRight::Right(idx) => idx <= right_len, - }); - let child = self.merge_tracking_child(alloc); - let new_idx = match track_edge_idx { - LeftOrRight::Left(idx) => idx, - LeftOrRight::Right(idx) => old_left_len + 1 + idx, - }; - unsafe { Handle::new_edge(child, new_idx) } - } - - /// Removes a key-value pair from the left child and places it in the key-value storage - /// of the parent, while pushing the old parent key-value pair into the right child. - /// Returns a handle to the edge in the right child corresponding to where the original - /// edge specified by `track_right_edge_idx` ended up. - pub fn steal_left( - mut self, - track_right_edge_idx: usize, - ) -> Handle, K, V, marker::LeafOrInternal>, marker::Edge> { - self.bulk_steal_left(1); - unsafe { Handle::new_edge(self.right_child, 1 + track_right_edge_idx) } - } - - /// Removes a key-value pair from the right child and places it in the key-value storage - /// of the parent, while pushing the old parent key-value pair onto the left child. - /// Returns a handle to the edge in the left child specified by `track_left_edge_idx`, - /// which didn't move. - pub fn steal_right( - mut self, - track_left_edge_idx: usize, - ) -> Handle, K, V, marker::LeafOrInternal>, marker::Edge> { - self.bulk_steal_right(1); - unsafe { Handle::new_edge(self.left_child, track_left_edge_idx) } - } - - /// This does stealing similar to `steal_left` but steals multiple elements at once. - pub fn bulk_steal_left(&mut self, count: usize) { - assert!(count > 0); - unsafe { - let left_node = &mut self.left_child; - let old_left_len = left_node.len(); - let right_node = &mut self.right_child; - let old_right_len = right_node.len(); - - // Make sure that we may steal safely. - assert!(old_right_len + count <= CAPACITY); - assert!(old_left_len >= count); - - let new_left_len = old_left_len - count; - let new_right_len = old_right_len + count; - *left_node.len_mut() = new_left_len as u16; - *right_node.len_mut() = new_right_len as u16; - - // Move leaf data. - { - // Make room for stolen elements in the right child. - slice_shr(right_node.key_area_mut(..new_right_len), count); - slice_shr(right_node.val_area_mut(..new_right_len), count); - - // Move elements from the left child to the right one. - move_to_slice( - left_node.key_area_mut(new_left_len + 1..old_left_len), - right_node.key_area_mut(..count - 1), - ); - move_to_slice( - left_node.val_area_mut(new_left_len + 1..old_left_len), - right_node.val_area_mut(..count - 1), - ); - - // Move the left-most stolen pair to the parent. - let k = left_node.key_area_mut(new_left_len).assume_init_read(); - let v = left_node.val_area_mut(new_left_len).assume_init_read(); - let (k, v) = self.parent.replace_kv(k, v); - - // Move parent's key-value pair to the right child. - right_node.key_area_mut(count - 1).write(k); - right_node.val_area_mut(count - 1).write(v); - } - - match (left_node.reborrow_mut().force(), right_node.reborrow_mut().force()) { - (ForceResult::Internal(mut left), ForceResult::Internal(mut right)) => { - // Make room for stolen edges. - slice_shr(right.edge_area_mut(..new_right_len + 1), count); - - // Steal edges. - move_to_slice( - left.edge_area_mut(new_left_len + 1..old_left_len + 1), - right.edge_area_mut(..count), - ); - - right.correct_childrens_parent_links(0..new_right_len + 1); - } - (ForceResult::Leaf(_), ForceResult::Leaf(_)) => {} - _ => unreachable!(), - } - } - } - - /// The symmetric clone of `bulk_steal_left`. - pub fn bulk_steal_right(&mut self, count: usize) { - assert!(count > 0); - unsafe { - let left_node = &mut self.left_child; - let old_left_len = left_node.len(); - let right_node = &mut self.right_child; - let old_right_len = right_node.len(); - - // Make sure that we may steal safely. - assert!(old_left_len + count <= CAPACITY); - assert!(old_right_len >= count); - - let new_left_len = old_left_len + count; - let new_right_len = old_right_len - count; - *left_node.len_mut() = new_left_len as u16; - *right_node.len_mut() = new_right_len as u16; - - // Move leaf data. - { - // Move the right-most stolen pair to the parent. - let k = right_node.key_area_mut(count - 1).assume_init_read(); - let v = right_node.val_area_mut(count - 1).assume_init_read(); - let (k, v) = self.parent.replace_kv(k, v); - - // Move parent's key-value pair to the left child. - left_node.key_area_mut(old_left_len).write(k); - left_node.val_area_mut(old_left_len).write(v); - - // Move elements from the right child to the left one. - move_to_slice( - right_node.key_area_mut(..count - 1), - left_node.key_area_mut(old_left_len + 1..new_left_len), - ); - move_to_slice( - right_node.val_area_mut(..count - 1), - left_node.val_area_mut(old_left_len + 1..new_left_len), - ); - - // Fill gap where stolen elements used to be. - slice_shl(right_node.key_area_mut(..old_right_len), count); - slice_shl(right_node.val_area_mut(..old_right_len), count); - } - - match (left_node.reborrow_mut().force(), right_node.reborrow_mut().force()) { - (ForceResult::Internal(mut left), ForceResult::Internal(mut right)) => { - // Steal edges. - move_to_slice( - right.edge_area_mut(..count), - left.edge_area_mut(old_left_len + 1..new_left_len + 1), - ); - - // Fill gap where stolen edges used to be. - slice_shl(right.edge_area_mut(..old_right_len + 1), count); - - left.correct_childrens_parent_links(old_left_len + 1..new_left_len + 1); - right.correct_childrens_parent_links(0..new_right_len + 1); - } - (ForceResult::Leaf(_), ForceResult::Leaf(_)) => {} - _ => unreachable!(), - } - } - } -} - -impl Handle, marker::Edge> { - pub fn forget_node_type( - self, - ) -> Handle, marker::Edge> { - unsafe { Handle::new_edge(self.node.forget_type(), self.idx) } - } -} - -impl Handle, marker::Edge> { - pub fn forget_node_type( - self, - ) -> Handle, marker::Edge> { - unsafe { Handle::new_edge(self.node.forget_type(), self.idx) } - } -} - -impl Handle, marker::KV> { - pub fn forget_node_type( - self, - ) -> Handle, marker::KV> { - unsafe { Handle::new_kv(self.node.forget_type(), self.idx) } - } -} - -impl Handle, Type> { - /// Checks whether the underlying node is an `Internal` node or a `Leaf` node. - pub fn force( - self, - ) -> ForceResult< - Handle, Type>, - Handle, Type>, - > { - match self.node.force() { - ForceResult::Leaf(node) => { - ForceResult::Leaf(Handle { node, idx: self.idx, _marker: PhantomData }) - } - ForceResult::Internal(node) => { - ForceResult::Internal(Handle { node, idx: self.idx, _marker: PhantomData }) - } - } - } -} - -impl<'a, K, V, Type> Handle, K, V, marker::LeafOrInternal>, Type> { - /// Unsafely asserts to the compiler the static information that the handle's node is a `Leaf`. - pub unsafe fn cast_to_leaf_unchecked( - self, - ) -> Handle, K, V, marker::Leaf>, Type> { - let node = unsafe { self.node.cast_to_leaf_unchecked() }; - Handle { node, idx: self.idx, _marker: PhantomData } - } -} - -impl<'a, K, V> Handle, K, V, marker::LeafOrInternal>, marker::Edge> { - /// Move the suffix after `self` from one node to another one. `right` must be empty. - /// The first edge of `right` remains unchanged. - pub fn move_suffix( - &mut self, - right: &mut NodeRef, K, V, marker::LeafOrInternal>, - ) { - unsafe { - let new_left_len = self.idx; - let mut left_node = self.reborrow_mut().into_node(); - let old_left_len = left_node.len(); - - let new_right_len = old_left_len - new_left_len; - let mut right_node = right.reborrow_mut(); - - assert!(right_node.len() == 0); - assert!(left_node.height == right_node.height); - - if new_right_len > 0 { - *left_node.len_mut() = new_left_len as u16; - *right_node.len_mut() = new_right_len as u16; - - move_to_slice( - left_node.key_area_mut(new_left_len..old_left_len), - right_node.key_area_mut(..new_right_len), - ); - move_to_slice( - left_node.val_area_mut(new_left_len..old_left_len), - right_node.val_area_mut(..new_right_len), - ); - match (left_node.force(), right_node.force()) { - (ForceResult::Internal(mut left), ForceResult::Internal(mut right)) => { - move_to_slice( - left.edge_area_mut(new_left_len + 1..old_left_len + 1), - right.edge_area_mut(1..new_right_len + 1), - ); - right.correct_childrens_parent_links(1..new_right_len + 1); - } - (ForceResult::Leaf(_), ForceResult::Leaf(_)) => {} - _ => unreachable!(), - } - } - } - } -} - -pub enum ForceResult { - Leaf(Leaf), - Internal(Internal), -} - -/// Result of insertion, when a node needed to expand beyond its capacity. -pub struct SplitResult<'a, K, V, NodeType> { - // Altered node in existing tree with elements and edges that belong to the left of `kv`. - pub left: NodeRef, K, V, NodeType>, - // Some key and value that existed before and were split off, to be inserted elsewhere. - pub kv: (K, V), - // Owned, unattached, new node with elements and edges that belong to the right of `kv`. - pub right: NodeRef, -} - -impl<'a, K, V> SplitResult<'a, K, V, marker::Leaf> { - pub fn forget_node_type(self) -> SplitResult<'a, K, V, marker::LeafOrInternal> { - SplitResult { left: self.left.forget_type(), kv: self.kv, right: self.right.forget_type() } - } -} - -impl<'a, K, V> SplitResult<'a, K, V, marker::Internal> { - pub fn forget_node_type(self) -> SplitResult<'a, K, V, marker::LeafOrInternal> { - SplitResult { left: self.left.forget_type(), kv: self.kv, right: self.right.forget_type() } - } -} - -pub mod marker { - use core::marker::PhantomData; - - pub enum Leaf {} - pub enum Internal {} - pub enum LeafOrInternal {} - - pub enum Owned {} - pub enum Dying {} - pub enum DormantMut {} - pub struct Immut<'a>(PhantomData<&'a ()>); - pub struct Mut<'a>(PhantomData<&'a mut ()>); - pub struct ValMut<'a>(PhantomData<&'a mut ()>); - - pub trait BorrowType { - /// If node references of this borrow type allow traversing to other - /// nodes in the tree, this constant is set to `true`. It can be used - /// for a compile-time assertion. - const TRAVERSAL_PERMIT: bool = true; - } - impl BorrowType for Owned { - /// Reject traversal, because it isn't needed. Instead traversal - /// happens using the result of `borrow_mut`. - /// By disabling traversal, and only creating new references to roots, - /// we know that every reference of the `Owned` type is to a root node. - const TRAVERSAL_PERMIT: bool = false; - } - impl BorrowType for Dying {} - impl<'a> BorrowType for Immut<'a> {} - impl<'a> BorrowType for Mut<'a> {} - impl<'a> BorrowType for ValMut<'a> {} - impl BorrowType for DormantMut {} - - pub enum KV {} - pub enum Edge {} -} - -/// Inserts a value into a slice of initialized elements followed by one uninitialized element. -/// -/// # Safety -/// The slice has more than `idx` elements. -unsafe fn slice_insert(slice: &mut [MaybeUninit], idx: usize, val: T) { - unsafe { - let len = slice.len(); - debug_assert!(len > idx); - let slice_ptr = slice.as_mut_ptr(); - if len > idx + 1 { - ptr::copy(slice_ptr.add(idx), slice_ptr.add(idx + 1), len - idx - 1); - } - (*slice_ptr.add(idx)).write(val); - } -} - -/// Removes and returns a value from a slice of all initialized elements, leaving behind one -/// trailing uninitialized element. -/// -/// # Safety -/// The slice has more than `idx` elements. -unsafe fn slice_remove(slice: &mut [MaybeUninit], idx: usize) -> T { - unsafe { - let len = slice.len(); - debug_assert!(idx < len); - let slice_ptr = slice.as_mut_ptr(); - let ret = (*slice_ptr.add(idx)).assume_init_read(); - ptr::copy(slice_ptr.add(idx + 1), slice_ptr.add(idx), len - idx - 1); - ret - } -} - -/// Shifts the elements in a slice `distance` positions to the left. -/// -/// # Safety -/// The slice has at least `distance` elements. -unsafe fn slice_shl(slice: &mut [MaybeUninit], distance: usize) { - unsafe { - let slice_ptr = slice.as_mut_ptr(); - ptr::copy(slice_ptr.add(distance), slice_ptr, slice.len() - distance); - } -} - -/// Shifts the elements in a slice `distance` positions to the right. -/// -/// # Safety -/// The slice has at least `distance` elements. -unsafe fn slice_shr(slice: &mut [MaybeUninit], distance: usize) { - unsafe { - let slice_ptr = slice.as_mut_ptr(); - ptr::copy(slice_ptr, slice_ptr.add(distance), slice.len() - distance); - } -} - -/// Moves all values from a slice of initialized elements to a slice -/// of uninitialized elements, leaving behind `src` as all uninitialized. -/// Works like `dst.copy_from_slice(src)` but does not require `T` to be `Copy`. -fn move_to_slice(src: &mut [MaybeUninit], dst: &mut [MaybeUninit]) { - assert!(src.len() == dst.len()); - unsafe { - ptr::copy_nonoverlapping(src.as_ptr(), dst.as_mut_ptr(), src.len()); - } -} - -#[cfg(test)] -mod tests; diff --git a/library/alloc/src/collections/btree/node/tests.rs b/library/alloc/src/collections/btree/node/tests.rs deleted file mode 100644 index d230749d71231..0000000000000 --- a/library/alloc/src/collections/btree/node/tests.rs +++ /dev/null @@ -1,99 +0,0 @@ -use super::super::navigate; -use super::*; -use crate::alloc::Global; -use crate::fmt::Debug; -use crate::string::String; - -impl<'a, K: 'a, V: 'a> NodeRef, K, V, marker::LeafOrInternal> { - // Asserts that the back pointer in each reachable node points to its parent. - pub fn assert_back_pointers(self) { - if let ForceResult::Internal(node) = self.force() { - for idx in 0..=node.len() { - let edge = unsafe { Handle::new_edge(node, idx) }; - let child = edge.descend(); - assert!(child.ascend().ok() == Some(edge)); - child.assert_back_pointers(); - } - } - } - - // Renders a multi-line display of the keys in order and in tree hierarchy, - // picturing the tree growing sideways from its root on the left to its - // leaves on the right. - pub fn dump_keys(self) -> String - where - K: Debug, - { - let mut result = String::new(); - self.visit_nodes_in_order(|pos| match pos { - navigate::Position::Leaf(leaf) => { - let depth = self.height(); - let indent = " ".repeat(depth); - result += &format!("\n{}{:?}", indent, leaf.keys()); - } - navigate::Position::Internal(_) => {} - navigate::Position::InternalKV => {} - }); - result - } -} - -#[test] -fn test_splitpoint() { - for idx in 0..=CAPACITY { - let (middle_kv_idx, insertion) = splitpoint(idx); - - // Simulate performing the split: - let mut left_len = middle_kv_idx; - let mut right_len = CAPACITY - middle_kv_idx - 1; - match insertion { - LeftOrRight::Left(edge_idx) => { - assert!(edge_idx <= left_len); - left_len += 1; - } - LeftOrRight::Right(edge_idx) => { - assert!(edge_idx <= right_len); - right_len += 1; - } - } - assert!(left_len >= MIN_LEN_AFTER_SPLIT); - assert!(right_len >= MIN_LEN_AFTER_SPLIT); - assert!(left_len + right_len == CAPACITY); - } -} - -#[test] -fn test_partial_eq() { - let mut root1 = NodeRef::new_leaf(Global); - root1.borrow_mut().push(1, ()); - let mut root1 = NodeRef::new_internal(root1.forget_type(), Global).forget_type(); - let root2 = Root::new(Global); - root1.reborrow().assert_back_pointers(); - root2.reborrow().assert_back_pointers(); - - let leaf_edge_1a = root1.reborrow().first_leaf_edge().forget_node_type(); - let leaf_edge_1b = root1.reborrow().last_leaf_edge().forget_node_type(); - let top_edge_1 = root1.reborrow().first_edge(); - let top_edge_2 = root2.reborrow().first_edge(); - - assert!(leaf_edge_1a == leaf_edge_1a); - assert!(leaf_edge_1a != leaf_edge_1b); - assert!(leaf_edge_1a != top_edge_1); - assert!(leaf_edge_1a != top_edge_2); - assert!(top_edge_1 == top_edge_1); - assert!(top_edge_1 != top_edge_2); - - root1.pop_internal_level(Global); - unsafe { root1.into_dying().deallocate_and_ascend(Global) }; - unsafe { root2.into_dying().deallocate_and_ascend(Global) }; -} - -#[test] -#[cfg(target_arch = "x86_64")] -#[cfg_attr(miri, ignore)] // We'd like to run Miri with layout randomization -fn test_sizes() { - assert_eq!(core::mem::size_of::>(), 16); - assert_eq!(core::mem::size_of::>(), 16 + CAPACITY * 2 * 8); - assert_eq!(core::mem::size_of::>(), 16 + (CAPACITY + 1) * 8); - assert_eq!(core::mem::size_of::>(), 16 + (CAPACITY * 3 + 1) * 8); -} diff --git a/library/alloc/src/collections/btree/remove.rs b/library/alloc/src/collections/btree/remove.rs deleted file mode 100644 index 0904299254f0a..0000000000000 --- a/library/alloc/src/collections/btree/remove.rs +++ /dev/null @@ -1,95 +0,0 @@ -use super::map::MIN_LEN; -use super::node::{marker, ForceResult::*, Handle, LeftOrRight::*, NodeRef}; -use core::alloc::Allocator; - -impl<'a, K: 'a, V: 'a> Handle, K, V, marker::LeafOrInternal>, marker::KV> { - /// Removes a key-value pair from the tree, and returns that pair, as well as - /// the leaf edge corresponding to that former pair. It's possible this empties - /// a root node that is internal, which the caller should pop from the map - /// holding the tree. The caller should also decrement the map's length. - pub fn remove_kv_tracking( - self, - handle_emptied_internal_root: F, - alloc: A, - ) -> ((K, V), Handle, K, V, marker::Leaf>, marker::Edge>) { - match self.force() { - Leaf(node) => node.remove_leaf_kv(handle_emptied_internal_root, alloc), - Internal(node) => node.remove_internal_kv(handle_emptied_internal_root, alloc), - } - } -} - -impl<'a, K: 'a, V: 'a> Handle, K, V, marker::Leaf>, marker::KV> { - fn remove_leaf_kv( - self, - handle_emptied_internal_root: F, - alloc: A, - ) -> ((K, V), Handle, K, V, marker::Leaf>, marker::Edge>) { - let (old_kv, mut pos) = self.remove(); - let len = pos.reborrow().into_node().len(); - if len < MIN_LEN { - let idx = pos.idx(); - // We have to temporarily forget the child type, because there is no - // distinct node type for the immediate parents of a leaf. - let new_pos = match pos.into_node().forget_type().choose_parent_kv() { - Ok(Left(left_parent_kv)) => { - debug_assert!(left_parent_kv.right_child_len() == MIN_LEN - 1); - if left_parent_kv.can_merge() { - left_parent_kv.merge_tracking_child_edge(Right(idx), alloc.clone()) - } else { - debug_assert!(left_parent_kv.left_child_len() > MIN_LEN); - left_parent_kv.steal_left(idx) - } - } - Ok(Right(right_parent_kv)) => { - debug_assert!(right_parent_kv.left_child_len() == MIN_LEN - 1); - if right_parent_kv.can_merge() { - right_parent_kv.merge_tracking_child_edge(Left(idx), alloc.clone()) - } else { - debug_assert!(right_parent_kv.right_child_len() > MIN_LEN); - right_parent_kv.steal_right(idx) - } - } - Err(pos) => unsafe { Handle::new_edge(pos, idx) }, - }; - // SAFETY: `new_pos` is the leaf we started from or a sibling. - pos = unsafe { new_pos.cast_to_leaf_unchecked() }; - - // Only if we merged, the parent (if any) has shrunk, but skipping - // the following step otherwise does not pay off in benchmarks. - // - // SAFETY: We won't destroy or rearrange the leaf where `pos` is at - // by handling its parent recursively; at worst we will destroy or - // rearrange the parent through the grandparent, thus change the - // link to the parent inside the leaf. - if let Ok(parent) = unsafe { pos.reborrow_mut() }.into_node().ascend() { - if !parent.into_node().forget_type().fix_node_and_affected_ancestors(alloc) { - handle_emptied_internal_root(); - } - } - } - (old_kv, pos) - } -} - -impl<'a, K: 'a, V: 'a> Handle, K, V, marker::Internal>, marker::KV> { - fn remove_internal_kv( - self, - handle_emptied_internal_root: F, - alloc: A, - ) -> ((K, V), Handle, K, V, marker::Leaf>, marker::Edge>) { - // Remove an adjacent KV from its leaf and then put it back in place of - // the element we were asked to remove. Prefer the left adjacent KV, - // for the reasons listed in `choose_parent_kv`. - let left_leaf_kv = self.left_edge().descend().last_leaf_edge().left_kv(); - let left_leaf_kv = unsafe { left_leaf_kv.ok().unwrap_unchecked() }; - let (left_kv, left_hole) = left_leaf_kv.remove_leaf_kv(handle_emptied_internal_root, alloc); - - // The internal node may have been stolen from or merged. Go back right - // to find where the original KV ended up. - let mut internal = unsafe { left_hole.next_kv().ok().unwrap_unchecked() }; - let old_kv = internal.replace_kv(left_kv.0, left_kv.1); - let pos = internal.next_leaf_edge(); - (old_kv, pos) - } -} diff --git a/library/alloc/src/collections/btree/search.rs b/library/alloc/src/collections/btree/search.rs deleted file mode 100644 index ad3522b4e0418..0000000000000 --- a/library/alloc/src/collections/btree/search.rs +++ /dev/null @@ -1,285 +0,0 @@ -use core::borrow::Borrow; -use core::cmp::Ordering; -use core::ops::{Bound, RangeBounds}; - -use super::node::{marker, ForceResult::*, Handle, NodeRef}; - -use SearchBound::*; -use SearchResult::*; - -pub enum SearchBound { - /// An inclusive bound to look for, just like `Bound::Included(T)`. - Included(T), - /// An exclusive bound to look for, just like `Bound::Excluded(T)`. - Excluded(T), - /// An unconditional inclusive bound, just like `Bound::Unbounded`. - AllIncluded, - /// An unconditional exclusive bound. - AllExcluded, -} - -impl SearchBound { - pub fn from_range(range_bound: Bound) -> Self { - match range_bound { - Bound::Included(t) => Included(t), - Bound::Excluded(t) => Excluded(t), - Bound::Unbounded => AllIncluded, - } - } -} - -pub enum SearchResult { - Found(Handle, marker::KV>), - GoDown(Handle, marker::Edge>), -} - -pub enum IndexResult { - KV(usize), - Edge(usize), -} - -impl NodeRef { - /// Looks up a given key in a (sub)tree headed by the node, recursively. - /// Returns a `Found` with the handle of the matching KV, if any. Otherwise, - /// returns a `GoDown` with the handle of the leaf edge where the key belongs. - /// - /// The result is meaningful only if the tree is ordered by key, like the tree - /// in a `BTreeMap` is. - pub fn search_tree( - mut self, - key: &Q, - ) -> SearchResult - where - Q: Ord, - K: Borrow, - { - loop { - self = match self.search_node(key) { - Found(handle) => return Found(handle), - GoDown(handle) => match handle.force() { - Leaf(leaf) => return GoDown(leaf), - Internal(internal) => internal.descend(), - }, - } - } - } - - /// Descends to the nearest node where the edge matching the lower bound - /// of the range is different from the edge matching the upper bound, i.e., - /// the nearest node that has at least one key contained in the range. - /// - /// If found, returns an `Ok` with that node, the strictly ascending pair of - /// edge indices in the node delimiting the range, and the corresponding - /// pair of bounds for continuing the search in the child nodes, in case - /// the node is internal. - /// - /// If not found, returns an `Err` with the leaf edge matching the entire - /// range. - /// - /// As a diagnostic service, panics if the range specifies impossible bounds. - /// - /// The result is meaningful only if the tree is ordered by key. - pub fn search_tree_for_bifurcation<'r, Q: ?Sized, R>( - mut self, - range: &'r R, - ) -> Result< - ( - NodeRef, - usize, - usize, - SearchBound<&'r Q>, - SearchBound<&'r Q>, - ), - Handle, marker::Edge>, - > - where - Q: Ord, - K: Borrow, - R: RangeBounds, - { - // Determine if map or set is being searched - let is_set = ::is_set_val(); - - // Inlining these variables should be avoided. We assume the bounds reported by `range` - // remain the same, but an adversarial implementation could change between calls (#81138). - let (start, end) = (range.start_bound(), range.end_bound()); - match (start, end) { - (Bound::Excluded(s), Bound::Excluded(e)) if s == e => { - if is_set { - panic!("range start and end are equal and excluded in BTreeSet") - } else { - panic!("range start and end are equal and excluded in BTreeMap") - } - } - (Bound::Included(s) | Bound::Excluded(s), Bound::Included(e) | Bound::Excluded(e)) - if s > e => - { - if is_set { - panic!("range start is greater than range end in BTreeSet") - } else { - panic!("range start is greater than range end in BTreeMap") - } - } - _ => {} - } - let mut lower_bound = SearchBound::from_range(start); - let mut upper_bound = SearchBound::from_range(end); - loop { - let (lower_edge_idx, lower_child_bound) = self.find_lower_bound_index(lower_bound); - let (upper_edge_idx, upper_child_bound) = - unsafe { self.find_upper_bound_index(upper_bound, lower_edge_idx) }; - if lower_edge_idx < upper_edge_idx { - return Ok(( - self, - lower_edge_idx, - upper_edge_idx, - lower_child_bound, - upper_child_bound, - )); - } - debug_assert_eq!(lower_edge_idx, upper_edge_idx); - let common_edge = unsafe { Handle::new_edge(self, lower_edge_idx) }; - match common_edge.force() { - Leaf(common_edge) => return Err(common_edge), - Internal(common_edge) => { - self = common_edge.descend(); - lower_bound = lower_child_bound; - upper_bound = upper_child_bound; - } - } - } - } - - /// Finds an edge in the node delimiting the lower bound of a range. - /// Also returns the lower bound to be used for continuing the search in - /// the matching child node, if `self` is an internal node. - /// - /// The result is meaningful only if the tree is ordered by key. - pub fn find_lower_bound_edge<'r, Q>( - self, - bound: SearchBound<&'r Q>, - ) -> (Handle, SearchBound<&'r Q>) - where - Q: ?Sized + Ord, - K: Borrow, - { - let (edge_idx, bound) = self.find_lower_bound_index(bound); - let edge = unsafe { Handle::new_edge(self, edge_idx) }; - (edge, bound) - } - - /// Clone of `find_lower_bound_edge` for the upper bound. - pub fn find_upper_bound_edge<'r, Q>( - self, - bound: SearchBound<&'r Q>, - ) -> (Handle, SearchBound<&'r Q>) - where - Q: ?Sized + Ord, - K: Borrow, - { - let (edge_idx, bound) = unsafe { self.find_upper_bound_index(bound, 0) }; - let edge = unsafe { Handle::new_edge(self, edge_idx) }; - (edge, bound) - } -} - -impl NodeRef { - /// Looks up a given key in the node, without recursion. - /// Returns a `Found` with the handle of the matching KV, if any. Otherwise, - /// returns a `GoDown` with the handle of the edge where the key might be found - /// (if the node is internal) or where the key can be inserted. - /// - /// The result is meaningful only if the tree is ordered by key, like the tree - /// in a `BTreeMap` is. - pub fn search_node(self, key: &Q) -> SearchResult - where - Q: Ord, - K: Borrow, - { - match unsafe { self.find_key_index(key, 0) } { - IndexResult::KV(idx) => Found(unsafe { Handle::new_kv(self, idx) }), - IndexResult::Edge(idx) => GoDown(unsafe { Handle::new_edge(self, idx) }), - } - } - - /// Returns either the KV index in the node at which the key (or an equivalent) - /// exists, or the edge index where the key belongs, starting from a particular index. - /// - /// The result is meaningful only if the tree is ordered by key, like the tree - /// in a `BTreeMap` is. - /// - /// # Safety - /// `start_index` must be a valid edge index for the node. - unsafe fn find_key_index(&self, key: &Q, start_index: usize) -> IndexResult - where - Q: Ord, - K: Borrow, - { - let node = self.reborrow(); - let keys = node.keys(); - debug_assert!(start_index <= keys.len()); - for (offset, k) in unsafe { keys.get_unchecked(start_index..) }.iter().enumerate() { - match key.cmp(k.borrow()) { - Ordering::Greater => {} - Ordering::Equal => return IndexResult::KV(start_index + offset), - Ordering::Less => return IndexResult::Edge(start_index + offset), - } - } - IndexResult::Edge(keys.len()) - } - - /// Finds an edge index in the node delimiting the lower bound of a range. - /// Also returns the lower bound to be used for continuing the search in - /// the matching child node, if `self` is an internal node. - /// - /// The result is meaningful only if the tree is ordered by key. - fn find_lower_bound_index<'r, Q>( - &self, - bound: SearchBound<&'r Q>, - ) -> (usize, SearchBound<&'r Q>) - where - Q: ?Sized + Ord, - K: Borrow, - { - match bound { - Included(key) => match unsafe { self.find_key_index(key, 0) } { - IndexResult::KV(idx) => (idx, AllExcluded), - IndexResult::Edge(idx) => (idx, bound), - }, - Excluded(key) => match unsafe { self.find_key_index(key, 0) } { - IndexResult::KV(idx) => (idx + 1, AllIncluded), - IndexResult::Edge(idx) => (idx, bound), - }, - AllIncluded => (0, AllIncluded), - AllExcluded => (self.len(), AllExcluded), - } - } - - /// Mirror image of `find_lower_bound_index` for the upper bound, - /// with an additional parameter to skip part of the key array. - /// - /// # Safety - /// `start_index` must be a valid edge index for the node. - unsafe fn find_upper_bound_index<'r, Q>( - &self, - bound: SearchBound<&'r Q>, - start_index: usize, - ) -> (usize, SearchBound<&'r Q>) - where - Q: ?Sized + Ord, - K: Borrow, - { - match bound { - Included(key) => match unsafe { self.find_key_index(key, start_index) } { - IndexResult::KV(idx) => (idx + 1, AllExcluded), - IndexResult::Edge(idx) => (idx, bound), - }, - Excluded(key) => match unsafe { self.find_key_index(key, start_index) } { - IndexResult::KV(idx) => (idx, AllIncluded), - IndexResult::Edge(idx) => (idx, bound), - }, - AllIncluded => (self.len(), AllIncluded), - AllExcluded => (start_index, AllExcluded), - } - } -} diff --git a/library/alloc/src/collections/btree/set.rs b/library/alloc/src/collections/btree/set.rs deleted file mode 100644 index b0bd6ef2d3c63..0000000000000 --- a/library/alloc/src/collections/btree/set.rs +++ /dev/null @@ -1,1821 +0,0 @@ -use crate::vec::Vec; -use core::borrow::Borrow; -use core::cmp::Ordering::{self, Equal, Greater, Less}; -use core::cmp::{max, min}; -use core::fmt::{self, Debug}; -use core::hash::{Hash, Hasher}; -use core::iter::{FusedIterator, Peekable}; -use core::mem::ManuallyDrop; -use core::ops::{BitAnd, BitOr, BitXor, RangeBounds, Sub}; - -use super::map::{BTreeMap, Keys}; -use super::merge_iter::MergeIterInner; -use super::set_val::SetValZST; -use super::Recover; - -use crate::alloc::{Allocator, Global}; - -/// An ordered set based on a B-Tree. -/// -/// See [`BTreeMap`]'s documentation for a detailed discussion of this collection's performance -/// benefits and drawbacks. -/// -/// It is a logic error for an item to be modified in such a way that the item's ordering relative -/// to any other item, as determined by the [`Ord`] trait, changes while it is in the set. This is -/// normally only possible through [`Cell`], [`RefCell`], global state, I/O, or unsafe code. -/// The behavior resulting from such a logic error is not specified, but will be encapsulated to the -/// `BTreeSet` that observed the logic error and not result in undefined behavior. This could -/// include panics, incorrect results, aborts, memory leaks, and non-termination. -/// -/// Iterators returned by [`BTreeSet::iter`] and [`BTreeSet::into_iter`] produce their items in order, and take worst-case -/// logarithmic and amortized constant time per item returned. -/// -/// [`Cell`]: core::cell::Cell -/// [`RefCell`]: core::cell::RefCell -/// -/// # Examples -/// -/// ``` -/// use std::collections::BTreeSet; -/// -/// // Type inference lets us omit an explicit type signature (which -/// // would be `BTreeSet<&str>` in this example). -/// let mut books = BTreeSet::new(); -/// -/// // Add some books. -/// books.insert("A Dance With Dragons"); -/// books.insert("To Kill a Mockingbird"); -/// books.insert("The Odyssey"); -/// books.insert("The Great Gatsby"); -/// -/// // Check for a specific one. -/// if !books.contains("The Winds of Winter") { -/// println!("We have {} books, but The Winds of Winter ain't one.", -/// books.len()); -/// } -/// -/// // Remove a book. -/// books.remove("The Odyssey"); -/// -/// // Iterate over everything. -/// for book in &books { -/// println!("{book}"); -/// } -/// ``` -/// -/// A `BTreeSet` with a known list of items can be initialized from an array: -/// -/// ``` -/// use std::collections::BTreeSet; -/// -/// let set = BTreeSet::from([1, 2, 3]); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "BTreeSet")] -pub struct BTreeSet< - T, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator + Clone = Global, -> { - map: BTreeMap, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Hash for BTreeSet { - fn hash(&self, state: &mut H) { - self.map.hash(state) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for BTreeSet { - fn eq(&self, other: &BTreeSet) -> bool { - self.map.eq(&other.map) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Eq for BTreeSet {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialOrd for BTreeSet { - fn partial_cmp(&self, other: &BTreeSet) -> Option { - self.map.partial_cmp(&other.map) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for BTreeSet { - fn cmp(&self, other: &BTreeSet) -> Ordering { - self.map.cmp(&other.map) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for BTreeSet { - fn clone(&self) -> Self { - BTreeSet { map: self.map.clone() } - } - - fn clone_from(&mut self, source: &Self) { - self.map.clone_from(&source.map); - } -} - -/// An iterator over the items of a `BTreeSet`. -/// -/// This `struct` is created by the [`iter`] method on [`BTreeSet`]. -/// See its documentation for more. -/// -/// [`iter`]: BTreeSet::iter -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Iter<'a, T: 'a> { - iter: Keys<'a, T, SetValZST>, -} - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl fmt::Debug for Iter<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("Iter").field(&self.iter.clone()).finish() - } -} - -/// An owning iterator over the items of a `BTreeSet` in ascending order. -/// -/// This `struct` is created by the [`into_iter`] method on [`BTreeSet`] -/// (provided by the [`IntoIterator`] trait). See its documentation for more. -/// -/// [`into_iter`]: BTreeSet#method.into_iter -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Debug)] -pub struct IntoIter< - T, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator + Clone = Global, -> { - iter: super::map::IntoIter, -} - -/// An iterator over a sub-range of items in a `BTreeSet`. -/// -/// This `struct` is created by the [`range`] method on [`BTreeSet`]. -/// See its documentation for more. -/// -/// [`range`]: BTreeSet::range -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[derive(Debug)] -#[stable(feature = "btree_range", since = "1.17.0")] -pub struct Range<'a, T: 'a> { - iter: super::map::Range<'a, T, SetValZST>, -} - -/// A lazy iterator producing elements in the difference of `BTreeSet`s. -/// -/// This `struct` is created by the [`difference`] method on [`BTreeSet`]. -/// See its documentation for more. -/// -/// [`difference`]: BTreeSet::difference -#[must_use = "this returns the difference as an iterator, \ - without modifying either input set"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Difference< - 'a, - T: 'a, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator + Clone = Global, -> { - inner: DifferenceInner<'a, T, A>, -} -enum DifferenceInner<'a, T: 'a, A: Allocator + Clone> { - Stitch { - // iterate all of `self` and some of `other`, spotting matches along the way - self_iter: Iter<'a, T>, - other_iter: Peekable>, - }, - Search { - // iterate `self`, look up in `other` - self_iter: Iter<'a, T>, - other_set: &'a BTreeSet, - }, - Iterate(Iter<'a, T>), // simply produce all elements in `self` -} - -// Explicit Debug impl necessary because of issue #26925 -impl Debug for DifferenceInner<'_, T, A> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - match self { - DifferenceInner::Stitch { self_iter, other_iter } => f - .debug_struct("Stitch") - .field("self_iter", self_iter) - .field("other_iter", other_iter) - .finish(), - DifferenceInner::Search { self_iter, other_set } => f - .debug_struct("Search") - .field("self_iter", self_iter) - .field("other_iter", other_set) - .finish(), - DifferenceInner::Iterate(x) => f.debug_tuple("Iterate").field(x).finish(), - } - } -} - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl fmt::Debug for Difference<'_, T, A> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("Difference").field(&self.inner).finish() - } -} - -/// A lazy iterator producing elements in the symmetric difference of `BTreeSet`s. -/// -/// This `struct` is created by the [`symmetric_difference`] method on -/// [`BTreeSet`]. See its documentation for more. -/// -/// [`symmetric_difference`]: BTreeSet::symmetric_difference -#[must_use = "this returns the difference as an iterator, \ - without modifying either input set"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct SymmetricDifference<'a, T: 'a>(MergeIterInner>); - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl fmt::Debug for SymmetricDifference<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("SymmetricDifference").field(&self.0).finish() - } -} - -/// A lazy iterator producing elements in the intersection of `BTreeSet`s. -/// -/// This `struct` is created by the [`intersection`] method on [`BTreeSet`]. -/// See its documentation for more. -/// -/// [`intersection`]: BTreeSet::intersection -#[must_use = "this returns the intersection as an iterator, \ - without modifying either input set"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Intersection< - 'a, - T: 'a, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator + Clone = Global, -> { - inner: IntersectionInner<'a, T, A>, -} -enum IntersectionInner<'a, T: 'a, A: Allocator + Clone> { - Stitch { - // iterate similarly sized sets jointly, spotting matches along the way - a: Iter<'a, T>, - b: Iter<'a, T>, - }, - Search { - // iterate a small set, look up in the large set - small_iter: Iter<'a, T>, - large_set: &'a BTreeSet, - }, - Answer(Option<&'a T>), // return a specific element or emptiness -} - -// Explicit Debug impl necessary because of issue #26925 -impl Debug for IntersectionInner<'_, T, A> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - match self { - IntersectionInner::Stitch { a, b } => { - f.debug_struct("Stitch").field("a", a).field("b", b).finish() - } - IntersectionInner::Search { small_iter, large_set } => f - .debug_struct("Search") - .field("small_iter", small_iter) - .field("large_set", large_set) - .finish(), - IntersectionInner::Answer(x) => f.debug_tuple("Answer").field(x).finish(), - } - } -} - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl Debug for Intersection<'_, T, A> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("Intersection").field(&self.inner).finish() - } -} - -/// A lazy iterator producing elements in the union of `BTreeSet`s. -/// -/// This `struct` is created by the [`union`] method on [`BTreeSet`]. -/// See its documentation for more. -/// -/// [`union`]: BTreeSet::union -#[must_use = "this returns the union as an iterator, \ - without modifying either input set"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Union<'a, T: 'a>(MergeIterInner>); - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl fmt::Debug for Union<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("Union").field(&self.0).finish() - } -} - -// This constant is used by functions that compare two sets. -// It estimates the relative size at which searching performs better -// than iterating, based on the benchmarks in -// https://github.com/ssomers/rust_bench_btreeset_intersection. -// It's used to divide rather than multiply sizes, to rule out overflow, -// and it's a power of two to make that division cheap. -const ITER_PERFORMANCE_TIPPING_SIZE_DIFF: usize = 16; - -impl BTreeSet { - /// Makes a new, empty `BTreeSet`. - /// - /// Does not allocate anything on its own. - /// - /// # Examples - /// - /// ``` - /// # #![allow(unused_mut)] - /// use std::collections::BTreeSet; - /// - /// let mut set: BTreeSet = BTreeSet::new(); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_btree_new", since = "1.66.0")] - #[must_use] - pub const fn new() -> BTreeSet { - BTreeSet { map: BTreeMap::new() } - } -} - -impl BTreeSet { - /// Makes a new `BTreeSet` with a reasonable choice of B. - /// - /// # Examples - /// - /// ``` - /// # #![allow(unused_mut)] - /// # #![feature(allocator_api)] - /// # #![feature(btreemap_alloc)] - /// use std::collections::BTreeSet; - /// use std::alloc::Global; - /// - /// let mut set: BTreeSet = BTreeSet::new_in(Global); - /// ``` - #[unstable(feature = "btreemap_alloc", issue = "32838")] - pub const fn new_in(alloc: A) -> BTreeSet { - BTreeSet { map: BTreeMap::new_in(alloc) } - } - - /// Constructs a double-ended iterator over a sub-range of elements in the set. - /// The simplest way is to use the range syntax `min..max`, thus `range(min..max)` will - /// yield elements from min (inclusive) to max (exclusive). - /// The range may also be entered as `(Bound, Bound)`, so for example - /// `range((Excluded(4), Included(10)))` will yield a left-exclusive, right-inclusive - /// range from 4 to 10. - /// - /// # Panics - /// - /// Panics if range `start > end`. - /// Panics if range `start == end` and both bounds are `Excluded`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// use std::ops::Bound::Included; - /// - /// let mut set = BTreeSet::new(); - /// set.insert(3); - /// set.insert(5); - /// set.insert(8); - /// for &elem in set.range((Included(&4), Included(&8))) { - /// println!("{elem}"); - /// } - /// assert_eq!(Some(&5), set.range(4..).next()); - /// ``` - #[stable(feature = "btree_range", since = "1.17.0")] - pub fn range(&self, range: R) -> Range<'_, T> - where - K: Ord, - T: Borrow + Ord, - R: RangeBounds, - { - Range { iter: self.map.range(range) } - } - - /// Visits the elements representing the difference, - /// i.e., the elements that are in `self` but not in `other`, - /// in ascending order. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let mut a = BTreeSet::new(); - /// a.insert(1); - /// a.insert(2); - /// - /// let mut b = BTreeSet::new(); - /// b.insert(2); - /// b.insert(3); - /// - /// let diff: Vec<_> = a.difference(&b).cloned().collect(); - /// assert_eq!(diff, [1]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn difference<'a>(&'a self, other: &'a BTreeSet) -> Difference<'a, T, A> - where - T: Ord, - { - let (self_min, self_max) = - if let (Some(self_min), Some(self_max)) = (self.first(), self.last()) { - (self_min, self_max) - } else { - return Difference { inner: DifferenceInner::Iterate(self.iter()) }; - }; - let (other_min, other_max) = - if let (Some(other_min), Some(other_max)) = (other.first(), other.last()) { - (other_min, other_max) - } else { - return Difference { inner: DifferenceInner::Iterate(self.iter()) }; - }; - Difference { - inner: match (self_min.cmp(other_max), self_max.cmp(other_min)) { - (Greater, _) | (_, Less) => DifferenceInner::Iterate(self.iter()), - (Equal, _) => { - let mut self_iter = self.iter(); - self_iter.next(); - DifferenceInner::Iterate(self_iter) - } - (_, Equal) => { - let mut self_iter = self.iter(); - self_iter.next_back(); - DifferenceInner::Iterate(self_iter) - } - _ if self.len() <= other.len() / ITER_PERFORMANCE_TIPPING_SIZE_DIFF => { - DifferenceInner::Search { self_iter: self.iter(), other_set: other } - } - _ => DifferenceInner::Stitch { - self_iter: self.iter(), - other_iter: other.iter().peekable(), - }, - }, - } - } - - /// Visits the elements representing the symmetric difference, - /// i.e., the elements that are in `self` or in `other` but not in both, - /// in ascending order. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let mut a = BTreeSet::new(); - /// a.insert(1); - /// a.insert(2); - /// - /// let mut b = BTreeSet::new(); - /// b.insert(2); - /// b.insert(3); - /// - /// let sym_diff: Vec<_> = a.symmetric_difference(&b).cloned().collect(); - /// assert_eq!(sym_diff, [1, 3]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn symmetric_difference<'a>( - &'a self, - other: &'a BTreeSet, - ) -> SymmetricDifference<'a, T> - where - T: Ord, - { - SymmetricDifference(MergeIterInner::new(self.iter(), other.iter())) - } - - /// Visits the elements representing the intersection, - /// i.e., the elements that are both in `self` and `other`, - /// in ascending order. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let mut a = BTreeSet::new(); - /// a.insert(1); - /// a.insert(2); - /// - /// let mut b = BTreeSet::new(); - /// b.insert(2); - /// b.insert(3); - /// - /// let intersection: Vec<_> = a.intersection(&b).cloned().collect(); - /// assert_eq!(intersection, [2]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn intersection<'a>(&'a self, other: &'a BTreeSet) -> Intersection<'a, T, A> - where - T: Ord, - { - let (self_min, self_max) = - if let (Some(self_min), Some(self_max)) = (self.first(), self.last()) { - (self_min, self_max) - } else { - return Intersection { inner: IntersectionInner::Answer(None) }; - }; - let (other_min, other_max) = - if let (Some(other_min), Some(other_max)) = (other.first(), other.last()) { - (other_min, other_max) - } else { - return Intersection { inner: IntersectionInner::Answer(None) }; - }; - Intersection { - inner: match (self_min.cmp(other_max), self_max.cmp(other_min)) { - (Greater, _) | (_, Less) => IntersectionInner::Answer(None), - (Equal, _) => IntersectionInner::Answer(Some(self_min)), - (_, Equal) => IntersectionInner::Answer(Some(self_max)), - _ if self.len() <= other.len() / ITER_PERFORMANCE_TIPPING_SIZE_DIFF => { - IntersectionInner::Search { small_iter: self.iter(), large_set: other } - } - _ if other.len() <= self.len() / ITER_PERFORMANCE_TIPPING_SIZE_DIFF => { - IntersectionInner::Search { small_iter: other.iter(), large_set: self } - } - _ => IntersectionInner::Stitch { a: self.iter(), b: other.iter() }, - }, - } - } - - /// Visits the elements representing the union, - /// i.e., all the elements in `self` or `other`, without duplicates, - /// in ascending order. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let mut a = BTreeSet::new(); - /// a.insert(1); - /// - /// let mut b = BTreeSet::new(); - /// b.insert(2); - /// - /// let union: Vec<_> = a.union(&b).cloned().collect(); - /// assert_eq!(union, [1, 2]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn union<'a>(&'a self, other: &'a BTreeSet) -> Union<'a, T> - where - T: Ord, - { - Union(MergeIterInner::new(self.iter(), other.iter())) - } - - /// Clears the set, removing all elements. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let mut v = BTreeSet::new(); - /// v.insert(1); - /// v.clear(); - /// assert!(v.is_empty()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn clear(&mut self) - where - A: Clone, - { - self.map.clear() - } - - /// Returns `true` if the set contains an element equal to the value. - /// - /// The value may be any borrowed form of the set's element type, - /// but the ordering on the borrowed form *must* match the - /// ordering on the element type. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let set = BTreeSet::from([1, 2, 3]); - /// assert_eq!(set.contains(&1), true); - /// assert_eq!(set.contains(&4), false); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn contains(&self, value: &Q) -> bool - where - T: Borrow + Ord, - Q: Ord, - { - self.map.contains_key(value) - } - - /// Returns a reference to the element in the set, if any, that is equal to - /// the value. - /// - /// The value may be any borrowed form of the set's element type, - /// but the ordering on the borrowed form *must* match the - /// ordering on the element type. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let set = BTreeSet::from([1, 2, 3]); - /// assert_eq!(set.get(&2), Some(&2)); - /// assert_eq!(set.get(&4), None); - /// ``` - #[stable(feature = "set_recovery", since = "1.9.0")] - pub fn get(&self, value: &Q) -> Option<&T> - where - T: Borrow + Ord, - Q: Ord, - { - Recover::get(&self.map, value) - } - - /// Returns `true` if `self` has no elements in common with `other`. - /// This is equivalent to checking for an empty intersection. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let a = BTreeSet::from([1, 2, 3]); - /// let mut b = BTreeSet::new(); - /// - /// assert_eq!(a.is_disjoint(&b), true); - /// b.insert(4); - /// assert_eq!(a.is_disjoint(&b), true); - /// b.insert(1); - /// assert_eq!(a.is_disjoint(&b), false); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn is_disjoint(&self, other: &BTreeSet) -> bool - where - T: Ord, - { - self.intersection(other).next().is_none() - } - - /// Returns `true` if the set is a subset of another, - /// i.e., `other` contains at least all the elements in `self`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let sup = BTreeSet::from([1, 2, 3]); - /// let mut set = BTreeSet::new(); - /// - /// assert_eq!(set.is_subset(&sup), true); - /// set.insert(2); - /// assert_eq!(set.is_subset(&sup), true); - /// set.insert(4); - /// assert_eq!(set.is_subset(&sup), false); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn is_subset(&self, other: &BTreeSet) -> bool - where - T: Ord, - { - // Same result as self.difference(other).next().is_none() - // but the code below is faster (hugely in some cases). - if self.len() > other.len() { - return false; - } - let (self_min, self_max) = - if let (Some(self_min), Some(self_max)) = (self.first(), self.last()) { - (self_min, self_max) - } else { - return true; // self is empty - }; - let (other_min, other_max) = - if let (Some(other_min), Some(other_max)) = (other.first(), other.last()) { - (other_min, other_max) - } else { - return false; // other is empty - }; - let mut self_iter = self.iter(); - match self_min.cmp(other_min) { - Less => return false, - Equal => { - self_iter.next(); - } - Greater => (), - } - match self_max.cmp(other_max) { - Greater => return false, - Equal => { - self_iter.next_back(); - } - Less => (), - } - if self_iter.len() <= other.len() / ITER_PERFORMANCE_TIPPING_SIZE_DIFF { - for next in self_iter { - if !other.contains(next) { - return false; - } - } - } else { - let mut other_iter = other.iter(); - other_iter.next(); - other_iter.next_back(); - let mut self_next = self_iter.next(); - while let Some(self1) = self_next { - match other_iter.next().map_or(Less, |other1| self1.cmp(other1)) { - Less => return false, - Equal => self_next = self_iter.next(), - Greater => (), - } - } - } - true - } - - /// Returns `true` if the set is a superset of another, - /// i.e., `self` contains at least all the elements in `other`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let sub = BTreeSet::from([1, 2]); - /// let mut set = BTreeSet::new(); - /// - /// assert_eq!(set.is_superset(&sub), false); - /// - /// set.insert(0); - /// set.insert(1); - /// assert_eq!(set.is_superset(&sub), false); - /// - /// set.insert(2); - /// assert_eq!(set.is_superset(&sub), true); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn is_superset(&self, other: &BTreeSet) -> bool - where - T: Ord, - { - other.is_subset(self) - } - - /// Returns a reference to the first element in the set, if any. - /// This element is always the minimum of all elements in the set. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let mut set = BTreeSet::new(); - /// assert_eq!(set.first(), None); - /// set.insert(1); - /// assert_eq!(set.first(), Some(&1)); - /// set.insert(2); - /// assert_eq!(set.first(), Some(&1)); - /// ``` - #[must_use] - #[stable(feature = "map_first_last", since = "1.66.0")] - #[rustc_confusables("front")] - pub fn first(&self) -> Option<&T> - where - T: Ord, - { - self.map.first_key_value().map(|(k, _)| k) - } - - /// Returns a reference to the last element in the set, if any. - /// This element is always the maximum of all elements in the set. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let mut set = BTreeSet::new(); - /// assert_eq!(set.last(), None); - /// set.insert(1); - /// assert_eq!(set.last(), Some(&1)); - /// set.insert(2); - /// assert_eq!(set.last(), Some(&2)); - /// ``` - #[must_use] - #[stable(feature = "map_first_last", since = "1.66.0")] - #[rustc_confusables("back")] - pub fn last(&self) -> Option<&T> - where - T: Ord, - { - self.map.last_key_value().map(|(k, _)| k) - } - - /// Removes the first element from the set and returns it, if any. - /// The first element is always the minimum element in the set. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let mut set = BTreeSet::new(); - /// - /// set.insert(1); - /// while let Some(n) = set.pop_first() { - /// assert_eq!(n, 1); - /// } - /// assert!(set.is_empty()); - /// ``` - #[stable(feature = "map_first_last", since = "1.66.0")] - pub fn pop_first(&mut self) -> Option - where - T: Ord, - { - self.map.pop_first().map(|kv| kv.0) - } - - /// Removes the last element from the set and returns it, if any. - /// The last element is always the maximum element in the set. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let mut set = BTreeSet::new(); - /// - /// set.insert(1); - /// while let Some(n) = set.pop_last() { - /// assert_eq!(n, 1); - /// } - /// assert!(set.is_empty()); - /// ``` - #[stable(feature = "map_first_last", since = "1.66.0")] - pub fn pop_last(&mut self) -> Option - where - T: Ord, - { - self.map.pop_last().map(|kv| kv.0) - } - - /// Adds a value to the set. - /// - /// Returns whether the value was newly inserted. That is: - /// - /// - If the set did not previously contain an equal value, `true` is - /// returned. - /// - If the set already contained an equal value, `false` is returned, and - /// the entry is not updated. - /// - /// See the [module-level documentation] for more. - /// - /// [module-level documentation]: index.html#insert-and-complex-keys - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let mut set = BTreeSet::new(); - /// - /// assert_eq!(set.insert(2), true); - /// assert_eq!(set.insert(2), false); - /// assert_eq!(set.len(), 1); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("push", "put")] - pub fn insert(&mut self, value: T) -> bool - where - T: Ord, - { - self.map.insert(value, SetValZST::default()).is_none() - } - - /// Adds a value to the set, replacing the existing element, if any, that is - /// equal to the value. Returns the replaced element. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let mut set = BTreeSet::new(); - /// set.insert(Vec::::new()); - /// - /// assert_eq!(set.get(&[][..]).unwrap().capacity(), 0); - /// set.replace(Vec::with_capacity(10)); - /// assert_eq!(set.get(&[][..]).unwrap().capacity(), 10); - /// ``` - #[stable(feature = "set_recovery", since = "1.9.0")] - #[rustc_confusables("swap")] - pub fn replace(&mut self, value: T) -> Option - where - T: Ord, - { - Recover::replace(&mut self.map, value) - } - - /// If the set contains an element equal to the value, removes it from the - /// set and drops it. Returns whether such an element was present. - /// - /// The value may be any borrowed form of the set's element type, - /// but the ordering on the borrowed form *must* match the - /// ordering on the element type. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let mut set = BTreeSet::new(); - /// - /// set.insert(2); - /// assert_eq!(set.remove(&2), true); - /// assert_eq!(set.remove(&2), false); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn remove(&mut self, value: &Q) -> bool - where - T: Borrow + Ord, - Q: Ord, - { - self.map.remove(value).is_some() - } - - /// Removes and returns the element in the set, if any, that is equal to - /// the value. - /// - /// The value may be any borrowed form of the set's element type, - /// but the ordering on the borrowed form *must* match the - /// ordering on the element type. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let mut set = BTreeSet::from([1, 2, 3]); - /// assert_eq!(set.take(&2), Some(2)); - /// assert_eq!(set.take(&2), None); - /// ``` - #[stable(feature = "set_recovery", since = "1.9.0")] - pub fn take(&mut self, value: &Q) -> Option - where - T: Borrow + Ord, - Q: Ord, - { - Recover::take(&mut self.map, value) - } - - /// Retains only the elements specified by the predicate. - /// - /// In other words, remove all elements `e` for which `f(&e)` returns `false`. - /// The elements are visited in ascending order. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let mut set = BTreeSet::from([1, 2, 3, 4, 5, 6]); - /// // Keep only the even numbers. - /// set.retain(|&k| k % 2 == 0); - /// assert!(set.iter().eq([2, 4, 6].iter())); - /// ``` - #[stable(feature = "btree_retain", since = "1.53.0")] - pub fn retain(&mut self, mut f: F) - where - T: Ord, - F: FnMut(&T) -> bool, - { - self.extract_if(|v| !f(v)).for_each(drop); - } - - /// Moves all elements from `other` into `self`, leaving `other` empty. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let mut a = BTreeSet::new(); - /// a.insert(1); - /// a.insert(2); - /// a.insert(3); - /// - /// let mut b = BTreeSet::new(); - /// b.insert(3); - /// b.insert(4); - /// b.insert(5); - /// - /// a.append(&mut b); - /// - /// assert_eq!(a.len(), 5); - /// assert_eq!(b.len(), 0); - /// - /// assert!(a.contains(&1)); - /// assert!(a.contains(&2)); - /// assert!(a.contains(&3)); - /// assert!(a.contains(&4)); - /// assert!(a.contains(&5)); - /// ``` - #[stable(feature = "btree_append", since = "1.11.0")] - pub fn append(&mut self, other: &mut Self) - where - T: Ord, - A: Clone, - { - self.map.append(&mut other.map); - } - - /// Splits the collection into two at the value. Returns a new collection - /// with all elements greater than or equal to the value. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let mut a = BTreeSet::new(); - /// a.insert(1); - /// a.insert(2); - /// a.insert(3); - /// a.insert(17); - /// a.insert(41); - /// - /// let b = a.split_off(&3); - /// - /// assert_eq!(a.len(), 2); - /// assert_eq!(b.len(), 3); - /// - /// assert!(a.contains(&1)); - /// assert!(a.contains(&2)); - /// - /// assert!(b.contains(&3)); - /// assert!(b.contains(&17)); - /// assert!(b.contains(&41)); - /// ``` - #[stable(feature = "btree_split_off", since = "1.11.0")] - pub fn split_off(&mut self, value: &Q) -> Self - where - T: Borrow + Ord, - A: Clone, - { - BTreeSet { map: self.map.split_off(value) } - } - - /// Creates an iterator that visits all elements in ascending order and - /// uses a closure to determine if an element should be removed. - /// - /// If the closure returns `true`, the element is removed from the set and - /// yielded. If the closure returns `false`, or panics, the element remains - /// in the set and will not be yielded. - /// - /// If the returned `ExtractIf` is not exhausted, e.g. because it is dropped without iterating - /// or the iteration short-circuits, then the remaining elements will be retained. - /// Use [`retain`] with a negated predicate if you do not need the returned iterator. - /// - /// [`retain`]: BTreeSet::retain - /// # Examples - /// - /// Splitting a set into even and odd values, reusing the original set: - /// - /// ``` - /// #![feature(btree_extract_if)] - /// use std::collections::BTreeSet; - /// - /// let mut set: BTreeSet = (0..8).collect(); - /// let evens: BTreeSet<_> = set.extract_if(|v| v % 2 == 0).collect(); - /// let odds = set; - /// assert_eq!(evens.into_iter().collect::>(), vec![0, 2, 4, 6]); - /// assert_eq!(odds.into_iter().collect::>(), vec![1, 3, 5, 7]); - /// ``` - #[unstable(feature = "btree_extract_if", issue = "70530")] - pub fn extract_if<'a, F>(&'a mut self, pred: F) -> ExtractIf<'a, T, F, A> - where - T: Ord, - F: 'a + FnMut(&T) -> bool, - { - let (inner, alloc) = self.map.extract_if_inner(); - ExtractIf { pred, inner, alloc } - } - - /// Gets an iterator that visits the elements in the `BTreeSet` in ascending - /// order. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let set = BTreeSet::from([3, 1, 2]); - /// let mut set_iter = set.iter(); - /// assert_eq!(set_iter.next(), Some(&1)); - /// assert_eq!(set_iter.next(), Some(&2)); - /// assert_eq!(set_iter.next(), Some(&3)); - /// assert_eq!(set_iter.next(), None); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn iter(&self) -> Iter<'_, T> { - Iter { iter: self.map.keys() } - } - - /// Returns the number of elements in the set. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let mut v = BTreeSet::new(); - /// assert_eq!(v.len(), 0); - /// v.insert(1); - /// assert_eq!(v.len(), 1); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable( - feature = "const_btree_len", - issue = "71835", - implied_by = "const_btree_new" - )] - #[rustc_confusables("length", "size")] - pub const fn len(&self) -> usize { - self.map.len() - } - - /// Returns `true` if the set contains no elements. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let mut v = BTreeSet::new(); - /// assert!(v.is_empty()); - /// v.insert(1); - /// assert!(!v.is_empty()); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable( - feature = "const_btree_len", - issue = "71835", - implied_by = "const_btree_new" - )] - pub const fn is_empty(&self) -> bool { - self.len() == 0 - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl FromIterator for BTreeSet { - fn from_iter>(iter: I) -> BTreeSet { - let mut inputs: Vec<_> = iter.into_iter().collect(); - - if inputs.is_empty() { - return BTreeSet::new(); - } - - // use stable sort to preserve the insertion order. - inputs.sort(); - BTreeSet::from_sorted_iter(inputs.into_iter(), Global) - } -} - -impl BTreeSet { - fn from_sorted_iter>(iter: I, alloc: A) -> BTreeSet { - let iter = iter.map(|k| (k, SetValZST::default())); - let map = BTreeMap::bulk_build_from_sorted_iter(iter, alloc); - BTreeSet { map } - } -} - -#[stable(feature = "std_collections_from_array", since = "1.56.0")] -impl From<[T; N]> for BTreeSet { - /// Converts a `[T; N]` into a `BTreeSet`. - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let set1 = BTreeSet::from([1, 2, 3, 4]); - /// let set2: BTreeSet<_> = [1, 2, 3, 4].into(); - /// assert_eq!(set1, set2); - /// ``` - fn from(mut arr: [T; N]) -> Self { - if N == 0 { - return BTreeSet::new(); - } - - // use stable sort to preserve the insertion order. - arr.sort(); - let iter = IntoIterator::into_iter(arr).map(|k| (k, SetValZST::default())); - let map = BTreeMap::bulk_build_from_sorted_iter(iter, Global); - BTreeSet { map } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl IntoIterator for BTreeSet { - type Item = T; - type IntoIter = IntoIter; - - /// Gets an iterator for moving out the `BTreeSet`'s contents in ascending order. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let set = BTreeSet::from([1, 2, 3, 4]); - /// - /// let v: Vec<_> = set.into_iter().collect(); - /// assert_eq!(v, [1, 2, 3, 4]); - /// ``` - fn into_iter(self) -> IntoIter { - IntoIter { iter: self.map.into_iter() } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T, A: Allocator + Clone> IntoIterator for &'a BTreeSet { - type Item = &'a T; - type IntoIter = Iter<'a, T>; - - fn into_iter(self) -> Iter<'a, T> { - self.iter() - } -} - -/// An iterator produced by calling `extract_if` on BTreeSet. -#[unstable(feature = "btree_extract_if", issue = "70530")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct ExtractIf< - 'a, - T, - F, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator + Clone = Global, -> where - T: 'a, - F: 'a + FnMut(&T) -> bool, -{ - pred: F, - inner: super::map::ExtractIfInner<'a, T, SetValZST>, - /// The BTreeMap will outlive this IntoIter so we don't care about drop order for `alloc`. - alloc: A, -} - -#[unstable(feature = "btree_extract_if", issue = "70530")] -impl fmt::Debug for ExtractIf<'_, T, F, A> -where - T: fmt::Debug, - F: FnMut(&T) -> bool, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("ExtractIf").field(&self.inner.peek().map(|(k, _)| k)).finish() - } -} - -#[unstable(feature = "btree_extract_if", issue = "70530")] -impl<'a, T, F, A: Allocator + Clone> Iterator for ExtractIf<'_, T, F, A> -where - F: 'a + FnMut(&T) -> bool, -{ - type Item = T; - - fn next(&mut self) -> Option { - let pred = &mut self.pred; - let mut mapped_pred = |k: &T, _v: &mut SetValZST| pred(k); - self.inner.next(&mut mapped_pred, self.alloc.clone()).map(|(k, _)| k) - } - - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } -} - -#[unstable(feature = "btree_extract_if", issue = "70530")] -impl FusedIterator for ExtractIf<'_, T, F, A> where F: FnMut(&T) -> bool {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Extend for BTreeSet { - #[inline] - fn extend>(&mut self, iter: Iter) { - iter.into_iter().for_each(move |elem| { - self.insert(elem); - }); - } - - #[inline] - fn extend_one(&mut self, elem: T) { - self.insert(elem); - } -} - -#[stable(feature = "extend_ref", since = "1.2.0")] -impl<'a, T: 'a + Ord + Copy, A: Allocator + Clone> Extend<&'a T> for BTreeSet { - fn extend>(&mut self, iter: I) { - self.extend(iter.into_iter().cloned()); - } - - #[inline] - fn extend_one(&mut self, &elem: &'a T) { - self.insert(elem); - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Default for BTreeSet { - /// Creates an empty `BTreeSet`. - fn default() -> BTreeSet { - BTreeSet::new() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Sub<&BTreeSet> for &BTreeSet { - type Output = BTreeSet; - - /// Returns the difference of `self` and `rhs` as a new `BTreeSet`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let a = BTreeSet::from([1, 2, 3]); - /// let b = BTreeSet::from([3, 4, 5]); - /// - /// let result = &a - &b; - /// assert_eq!(result, BTreeSet::from([1, 2])); - /// ``` - fn sub(self, rhs: &BTreeSet) -> BTreeSet { - BTreeSet::from_sorted_iter( - self.difference(rhs).cloned(), - ManuallyDrop::into_inner(self.map.alloc.clone()), - ) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl BitXor<&BTreeSet> for &BTreeSet { - type Output = BTreeSet; - - /// Returns the symmetric difference of `self` and `rhs` as a new `BTreeSet`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let a = BTreeSet::from([1, 2, 3]); - /// let b = BTreeSet::from([2, 3, 4]); - /// - /// let result = &a ^ &b; - /// assert_eq!(result, BTreeSet::from([1, 4])); - /// ``` - fn bitxor(self, rhs: &BTreeSet) -> BTreeSet { - BTreeSet::from_sorted_iter( - self.symmetric_difference(rhs).cloned(), - ManuallyDrop::into_inner(self.map.alloc.clone()), - ) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl BitAnd<&BTreeSet> for &BTreeSet { - type Output = BTreeSet; - - /// Returns the intersection of `self` and `rhs` as a new `BTreeSet`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let a = BTreeSet::from([1, 2, 3]); - /// let b = BTreeSet::from([2, 3, 4]); - /// - /// let result = &a & &b; - /// assert_eq!(result, BTreeSet::from([2, 3])); - /// ``` - fn bitand(self, rhs: &BTreeSet) -> BTreeSet { - BTreeSet::from_sorted_iter( - self.intersection(rhs).cloned(), - ManuallyDrop::into_inner(self.map.alloc.clone()), - ) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl BitOr<&BTreeSet> for &BTreeSet { - type Output = BTreeSet; - - /// Returns the union of `self` and `rhs` as a new `BTreeSet`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::BTreeSet; - /// - /// let a = BTreeSet::from([1, 2, 3]); - /// let b = BTreeSet::from([3, 4, 5]); - /// - /// let result = &a | &b; - /// assert_eq!(result, BTreeSet::from([1, 2, 3, 4, 5])); - /// ``` - fn bitor(self, rhs: &BTreeSet) -> BTreeSet { - BTreeSet::from_sorted_iter( - self.union(rhs).cloned(), - ManuallyDrop::into_inner(self.map.alloc.clone()), - ) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Debug for BTreeSet { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_set().entries(self.iter()).finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Iter<'_, T> { - fn clone(&self) -> Self { - Iter { iter: self.iter.clone() } - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> Iterator for Iter<'a, T> { - type Item = &'a T; - - fn next(&mut self) -> Option<&'a T> { - self.iter.next() - } - - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } - - fn last(mut self) -> Option<&'a T> { - self.next_back() - } - - fn min(mut self) -> Option<&'a T> - where - &'a T: Ord, - { - self.next() - } - - fn max(mut self) -> Option<&'a T> - where - &'a T: Ord, - { - self.next_back() - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> DoubleEndedIterator for Iter<'a, T> { - fn next_back(&mut self) -> Option<&'a T> { - self.iter.next_back() - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Iter<'_, T> { - fn len(&self) -> usize { - self.iter.len() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Iter<'_, T> {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for IntoIter { - type Item = T; - - fn next(&mut self) -> Option { - self.iter.next().map(|(k, _)| k) - } - - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } -} - -#[stable(feature = "default_iters", since = "1.70.0")] -impl Default for Iter<'_, T> { - /// Creates an empty `btree_set::Iter`. - /// - /// ``` - /// # use std::collections::btree_set; - /// let iter: btree_set::Iter<'_, u8> = Default::default(); - /// assert_eq!(iter.len(), 0); - /// ``` - fn default() -> Self { - Iter { iter: Default::default() } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DoubleEndedIterator for IntoIter { - fn next_back(&mut self) -> Option { - self.iter.next_back().map(|(k, _)| k) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for IntoIter { - fn len(&self) -> usize { - self.iter.len() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for IntoIter {} - -#[stable(feature = "default_iters", since = "1.70.0")] -impl Default for IntoIter -where - A: Allocator + Default + Clone, -{ - /// Creates an empty `btree_set::IntoIter`. - /// - /// ``` - /// # use std::collections::btree_set; - /// let iter: btree_set::IntoIter = Default::default(); - /// assert_eq!(iter.len(), 0); - /// ``` - fn default() -> Self { - IntoIter { iter: Default::default() } - } -} - -#[stable(feature = "btree_range", since = "1.17.0")] -impl Clone for Range<'_, T> { - fn clone(&self) -> Self { - Range { iter: self.iter.clone() } - } -} - -#[stable(feature = "btree_range", since = "1.17.0")] -impl<'a, T> Iterator for Range<'a, T> { - type Item = &'a T; - - fn next(&mut self) -> Option<&'a T> { - self.iter.next().map(|(k, _)| k) - } - - fn last(mut self) -> Option<&'a T> { - self.next_back() - } - - fn min(mut self) -> Option<&'a T> - where - &'a T: Ord, - { - self.next() - } - - fn max(mut self) -> Option<&'a T> - where - &'a T: Ord, - { - self.next_back() - } -} - -#[stable(feature = "btree_range", since = "1.17.0")] -impl<'a, T> DoubleEndedIterator for Range<'a, T> { - fn next_back(&mut self) -> Option<&'a T> { - self.iter.next_back().map(|(k, _)| k) - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Range<'_, T> {} - -#[stable(feature = "default_iters", since = "1.70.0")] -impl Default for Range<'_, T> { - /// Creates an empty `btree_set::Range`. - /// - /// ``` - /// # use std::collections::btree_set; - /// let iter: btree_set::Range<'_, u8> = Default::default(); - /// assert_eq!(iter.count(), 0); - /// ``` - fn default() -> Self { - Range { iter: Default::default() } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Difference<'_, T, A> { - fn clone(&self) -> Self { - Difference { - inner: match &self.inner { - DifferenceInner::Stitch { self_iter, other_iter } => DifferenceInner::Stitch { - self_iter: self_iter.clone(), - other_iter: other_iter.clone(), - }, - DifferenceInner::Search { self_iter, other_set } => { - DifferenceInner::Search { self_iter: self_iter.clone(), other_set } - } - DifferenceInner::Iterate(iter) => DifferenceInner::Iterate(iter.clone()), - }, - } - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T: Ord, A: Allocator + Clone> Iterator for Difference<'a, T, A> { - type Item = &'a T; - - fn next(&mut self) -> Option<&'a T> { - match &mut self.inner { - DifferenceInner::Stitch { self_iter, other_iter } => { - let mut self_next = self_iter.next()?; - loop { - match other_iter.peek().map_or(Less, |other_next| self_next.cmp(other_next)) { - Less => return Some(self_next), - Equal => { - self_next = self_iter.next()?; - other_iter.next(); - } - Greater => { - other_iter.next(); - } - } - } - } - DifferenceInner::Search { self_iter, other_set } => loop { - let self_next = self_iter.next()?; - if !other_set.contains(&self_next) { - return Some(self_next); - } - }, - DifferenceInner::Iterate(iter) => iter.next(), - } - } - - fn size_hint(&self) -> (usize, Option) { - let (self_len, other_len) = match &self.inner { - DifferenceInner::Stitch { self_iter, other_iter } => { - (self_iter.len(), other_iter.len()) - } - DifferenceInner::Search { self_iter, other_set } => (self_iter.len(), other_set.len()), - DifferenceInner::Iterate(iter) => (iter.len(), 0), - }; - (self_len.saturating_sub(other_len), Some(self_len)) - } - - fn min(mut self) -> Option<&'a T> { - self.next() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Difference<'_, T, A> {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for SymmetricDifference<'_, T> { - fn clone(&self) -> Self { - SymmetricDifference(self.0.clone()) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T: Ord> Iterator for SymmetricDifference<'a, T> { - type Item = &'a T; - - fn next(&mut self) -> Option<&'a T> { - loop { - let (a_next, b_next) = self.0.nexts(Self::Item::cmp); - if a_next.and(b_next).is_none() { - return a_next.or(b_next); - } - } - } - - fn size_hint(&self) -> (usize, Option) { - let (a_len, b_len) = self.0.lens(); - // No checked_add, because even if a and b refer to the same set, - // and T is a zero-sized type, the storage overhead of sets limits - // the number of elements to less than half the range of usize. - (0, Some(a_len + b_len)) - } - - fn min(mut self) -> Option<&'a T> { - self.next() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for SymmetricDifference<'_, T> {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Intersection<'_, T, A> { - fn clone(&self) -> Self { - Intersection { - inner: match &self.inner { - IntersectionInner::Stitch { a, b } => { - IntersectionInner::Stitch { a: a.clone(), b: b.clone() } - } - IntersectionInner::Search { small_iter, large_set } => { - IntersectionInner::Search { small_iter: small_iter.clone(), large_set } - } - IntersectionInner::Answer(answer) => IntersectionInner::Answer(*answer), - }, - } - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T: Ord, A: Allocator + Clone> Iterator for Intersection<'a, T, A> { - type Item = &'a T; - - fn next(&mut self) -> Option<&'a T> { - match &mut self.inner { - IntersectionInner::Stitch { a, b } => { - let mut a_next = a.next()?; - let mut b_next = b.next()?; - loop { - match a_next.cmp(b_next) { - Less => a_next = a.next()?, - Greater => b_next = b.next()?, - Equal => return Some(a_next), - } - } - } - IntersectionInner::Search { small_iter, large_set } => loop { - let small_next = small_iter.next()?; - if large_set.contains(&small_next) { - return Some(small_next); - } - }, - IntersectionInner::Answer(answer) => answer.take(), - } - } - - fn size_hint(&self) -> (usize, Option) { - match &self.inner { - IntersectionInner::Stitch { a, b } => (0, Some(min(a.len(), b.len()))), - IntersectionInner::Search { small_iter, .. } => (0, Some(small_iter.len())), - IntersectionInner::Answer(None) => (0, Some(0)), - IntersectionInner::Answer(Some(_)) => (1, Some(1)), - } - } - - fn min(mut self) -> Option<&'a T> { - self.next() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Intersection<'_, T, A> {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Union<'_, T> { - fn clone(&self) -> Self { - Union(self.0.clone()) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T: Ord> Iterator for Union<'a, T> { - type Item = &'a T; - - fn next(&mut self) -> Option<&'a T> { - let (a_next, b_next) = self.0.nexts(Self::Item::cmp); - a_next.or(b_next) - } - - fn size_hint(&self) -> (usize, Option) { - let (a_len, b_len) = self.0.lens(); - // No checked_add - see SymmetricDifference::size_hint. - (max(a_len, b_len), Some(a_len + b_len)) - } - - fn min(mut self) -> Option<&'a T> { - self.next() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Union<'_, T> {} - -#[cfg(test)] -mod tests; diff --git a/library/alloc/src/collections/btree/set/tests.rs b/library/alloc/src/collections/btree/set/tests.rs deleted file mode 100644 index 688ce57e9da6a..0000000000000 --- a/library/alloc/src/collections/btree/set/tests.rs +++ /dev/null @@ -1,855 +0,0 @@ -use super::*; -use crate::testing::crash_test::{CrashTestDummy, Panic}; -use crate::testing::rng::DeterministicRng; -use std::ops::Bound::{Excluded, Included}; -use std::panic::{catch_unwind, AssertUnwindSafe}; - -#[test] -fn test_clone_eq() { - let mut m = BTreeSet::new(); - - m.insert(1); - m.insert(2); - - assert_eq!(m.clone(), m); -} - -#[test] -fn test_iter_min_max() { - let mut a = BTreeSet::new(); - assert_eq!(a.iter().min(), None); - assert_eq!(a.iter().max(), None); - assert_eq!(a.range(..).min(), None); - assert_eq!(a.range(..).max(), None); - assert_eq!(a.difference(&BTreeSet::new()).min(), None); - assert_eq!(a.difference(&BTreeSet::new()).max(), None); - assert_eq!(a.intersection(&a).min(), None); - assert_eq!(a.intersection(&a).max(), None); - assert_eq!(a.symmetric_difference(&BTreeSet::new()).min(), None); - assert_eq!(a.symmetric_difference(&BTreeSet::new()).max(), None); - assert_eq!(a.union(&a).min(), None); - assert_eq!(a.union(&a).max(), None); - a.insert(1); - a.insert(2); - assert_eq!(a.iter().min(), Some(&1)); - assert_eq!(a.iter().max(), Some(&2)); - assert_eq!(a.range(..).min(), Some(&1)); - assert_eq!(a.range(..).max(), Some(&2)); - assert_eq!(a.difference(&BTreeSet::new()).min(), Some(&1)); - assert_eq!(a.difference(&BTreeSet::new()).max(), Some(&2)); - assert_eq!(a.intersection(&a).min(), Some(&1)); - assert_eq!(a.intersection(&a).max(), Some(&2)); - assert_eq!(a.symmetric_difference(&BTreeSet::new()).min(), Some(&1)); - assert_eq!(a.symmetric_difference(&BTreeSet::new()).max(), Some(&2)); - assert_eq!(a.union(&a).min(), Some(&1)); - assert_eq!(a.union(&a).max(), Some(&2)); -} - -fn check(a: &[i32], b: &[i32], expected: &[i32], f: F) -where - F: FnOnce(&BTreeSet, &BTreeSet, &mut dyn FnMut(&i32) -> bool) -> bool, -{ - let mut set_a = BTreeSet::new(); - let mut set_b = BTreeSet::new(); - - for x in a { - assert!(set_a.insert(*x)) - } - for y in b { - assert!(set_b.insert(*y)) - } - - let mut i = 0; - f(&set_a, &set_b, &mut |&x| { - if i < expected.len() { - assert_eq!(x, expected[i]); - } - i += 1; - true - }); - assert_eq!(i, expected.len()); -} - -#[test] -fn test_intersection() { - fn check_intersection(a: &[i32], b: &[i32], expected: &[i32]) { - check(a, b, expected, |x, y, f| x.intersection(y).all(f)) - } - - check_intersection(&[], &[], &[]); - check_intersection(&[1, 2, 3], &[], &[]); - check_intersection(&[], &[1, 2, 3], &[]); - check_intersection(&[2], &[1, 2, 3], &[2]); - check_intersection(&[1, 2, 3], &[2], &[2]); - check_intersection(&[11, 1, 3, 77, 103, 5, -5], &[2, 11, 77, -9, -42, 5, 3], &[3, 5, 11, 77]); - - if cfg!(miri) { - // Miri is too slow - return; - } - - let large = Vec::from_iter(0..100); - check_intersection(&[], &large, &[]); - check_intersection(&large, &[], &[]); - check_intersection(&[-1], &large, &[]); - check_intersection(&large, &[-1], &[]); - check_intersection(&[0], &large, &[0]); - check_intersection(&large, &[0], &[0]); - check_intersection(&[99], &large, &[99]); - check_intersection(&large, &[99], &[99]); - check_intersection(&[100], &large, &[]); - check_intersection(&large, &[100], &[]); - check_intersection(&[11, 5000, 1, 3, 77, 8924], &large, &[1, 3, 11, 77]); -} - -#[test] -fn test_intersection_size_hint() { - let x = BTreeSet::from([3, 4]); - let y = BTreeSet::from([1, 2, 3]); - let mut iter = x.intersection(&y); - assert_eq!(iter.size_hint(), (1, Some(1))); - assert_eq!(iter.next(), Some(&3)); - assert_eq!(iter.size_hint(), (0, Some(0))); - assert_eq!(iter.next(), None); - - iter = y.intersection(&y); - assert_eq!(iter.size_hint(), (0, Some(3))); - assert_eq!(iter.next(), Some(&1)); - assert_eq!(iter.size_hint(), (0, Some(2))); -} - -#[test] -fn test_difference() { - fn check_difference(a: &[i32], b: &[i32], expected: &[i32]) { - check(a, b, expected, |x, y, f| x.difference(y).all(f)) - } - - check_difference(&[], &[], &[]); - check_difference(&[1, 12], &[], &[1, 12]); - check_difference(&[], &[1, 2, 3, 9], &[]); - check_difference(&[1, 3, 5, 9, 11], &[3, 9], &[1, 5, 11]); - check_difference(&[1, 3, 5, 9, 11], &[3, 6, 9], &[1, 5, 11]); - check_difference(&[1, 3, 5, 9, 11], &[0, 1], &[3, 5, 9, 11]); - check_difference(&[1, 3, 5, 9, 11], &[11, 12], &[1, 3, 5, 9]); - check_difference( - &[-5, 11, 22, 33, 40, 42], - &[-12, -5, 14, 23, 34, 38, 39, 50], - &[11, 22, 33, 40, 42], - ); - - if cfg!(miri) { - // Miri is too slow - return; - } - - let large = Vec::from_iter(0..100); - check_difference(&[], &large, &[]); - check_difference(&[-1], &large, &[-1]); - check_difference(&[0], &large, &[]); - check_difference(&[99], &large, &[]); - check_difference(&[100], &large, &[100]); - check_difference(&[11, 5000, 1, 3, 77, 8924], &large, &[5000, 8924]); - check_difference(&large, &[], &large); - check_difference(&large, &[-1], &large); - check_difference(&large, &[100], &large); -} - -#[test] -fn test_difference_size_hint() { - let s246 = BTreeSet::from([2, 4, 6]); - let s23456 = BTreeSet::from_iter(2..=6); - let mut iter = s246.difference(&s23456); - assert_eq!(iter.size_hint(), (0, Some(3))); - assert_eq!(iter.next(), None); - - let s12345 = BTreeSet::from_iter(1..=5); - iter = s246.difference(&s12345); - assert_eq!(iter.size_hint(), (0, Some(3))); - assert_eq!(iter.next(), Some(&6)); - assert_eq!(iter.size_hint(), (0, Some(0))); - assert_eq!(iter.next(), None); - - let s34567 = BTreeSet::from_iter(3..=7); - iter = s246.difference(&s34567); - assert_eq!(iter.size_hint(), (0, Some(3))); - assert_eq!(iter.next(), Some(&2)); - assert_eq!(iter.size_hint(), (0, Some(2))); - assert_eq!(iter.next(), None); - - let s1 = BTreeSet::from_iter(-9..=1); - iter = s246.difference(&s1); - assert_eq!(iter.size_hint(), (3, Some(3))); - - let s2 = BTreeSet::from_iter(-9..=2); - iter = s246.difference(&s2); - assert_eq!(iter.size_hint(), (2, Some(2))); - assert_eq!(iter.next(), Some(&4)); - assert_eq!(iter.size_hint(), (1, Some(1))); - - let s23 = BTreeSet::from([2, 3]); - iter = s246.difference(&s23); - assert_eq!(iter.size_hint(), (1, Some(3))); - assert_eq!(iter.next(), Some(&4)); - assert_eq!(iter.size_hint(), (1, Some(1))); - - let s4 = BTreeSet::from([4]); - iter = s246.difference(&s4); - assert_eq!(iter.size_hint(), (2, Some(3))); - assert_eq!(iter.next(), Some(&2)); - assert_eq!(iter.size_hint(), (1, Some(2))); - assert_eq!(iter.next(), Some(&6)); - assert_eq!(iter.size_hint(), (0, Some(0))); - assert_eq!(iter.next(), None); - - let s56 = BTreeSet::from([5, 6]); - iter = s246.difference(&s56); - assert_eq!(iter.size_hint(), (1, Some(3))); - assert_eq!(iter.next(), Some(&2)); - assert_eq!(iter.size_hint(), (0, Some(2))); - - let s6 = BTreeSet::from_iter(6..=19); - iter = s246.difference(&s6); - assert_eq!(iter.size_hint(), (2, Some(2))); - assert_eq!(iter.next(), Some(&2)); - assert_eq!(iter.size_hint(), (1, Some(1))); - - let s7 = BTreeSet::from_iter(7..=19); - iter = s246.difference(&s7); - assert_eq!(iter.size_hint(), (3, Some(3))); -} - -#[test] -fn test_symmetric_difference() { - fn check_symmetric_difference(a: &[i32], b: &[i32], expected: &[i32]) { - check(a, b, expected, |x, y, f| x.symmetric_difference(y).all(f)) - } - - check_symmetric_difference(&[], &[], &[]); - check_symmetric_difference(&[1, 2, 3], &[2], &[1, 3]); - check_symmetric_difference(&[2], &[1, 2, 3], &[1, 3]); - check_symmetric_difference(&[1, 3, 5, 9, 11], &[-2, 3, 9, 14, 22], &[-2, 1, 5, 11, 14, 22]); -} - -#[test] -fn test_symmetric_difference_size_hint() { - let x = BTreeSet::from([2, 4]); - let y = BTreeSet::from([1, 2, 3]); - let mut iter = x.symmetric_difference(&y); - assert_eq!(iter.size_hint(), (0, Some(5))); - assert_eq!(iter.next(), Some(&1)); - assert_eq!(iter.size_hint(), (0, Some(4))); - assert_eq!(iter.next(), Some(&3)); - assert_eq!(iter.size_hint(), (0, Some(1))); -} - -#[test] -fn test_union() { - fn check_union(a: &[i32], b: &[i32], expected: &[i32]) { - check(a, b, expected, |x, y, f| x.union(y).all(f)) - } - - check_union(&[], &[], &[]); - check_union(&[1, 2, 3], &[2], &[1, 2, 3]); - check_union(&[2], &[1, 2, 3], &[1, 2, 3]); - check_union( - &[1, 3, 5, 9, 11, 16, 19, 24], - &[-2, 1, 5, 9, 13, 19], - &[-2, 1, 3, 5, 9, 11, 13, 16, 19, 24], - ); -} - -#[test] -fn test_union_size_hint() { - let x = BTreeSet::from([2, 4]); - let y = BTreeSet::from([1, 2, 3]); - let mut iter = x.union(&y); - assert_eq!(iter.size_hint(), (3, Some(5))); - assert_eq!(iter.next(), Some(&1)); - assert_eq!(iter.size_hint(), (2, Some(4))); - assert_eq!(iter.next(), Some(&2)); - assert_eq!(iter.size_hint(), (1, Some(2))); -} - -#[test] -// Only tests the simple function definition with respect to intersection -fn test_is_disjoint() { - let one = BTreeSet::from([1]); - let two = BTreeSet::from([2]); - assert!(one.is_disjoint(&two)); -} - -#[test] -// Also implicitly tests the trivial function definition of is_superset -fn test_is_subset() { - fn is_subset(a: &[i32], b: &[i32]) -> bool { - let set_a = BTreeSet::from_iter(a.iter()); - let set_b = BTreeSet::from_iter(b.iter()); - set_a.is_subset(&set_b) - } - - assert_eq!(is_subset(&[], &[]), true); - assert_eq!(is_subset(&[], &[1, 2]), true); - assert_eq!(is_subset(&[0], &[1, 2]), false); - assert_eq!(is_subset(&[1], &[1, 2]), true); - assert_eq!(is_subset(&[2], &[1, 2]), true); - assert_eq!(is_subset(&[3], &[1, 2]), false); - assert_eq!(is_subset(&[1, 2], &[1]), false); - assert_eq!(is_subset(&[1, 2], &[1, 2]), true); - assert_eq!(is_subset(&[1, 2], &[2, 3]), false); - assert_eq!( - is_subset(&[-5, 11, 22, 33, 40, 42], &[-12, -5, 11, 14, 22, 23, 33, 34, 38, 39, 40, 42]), - true - ); - assert_eq!(is_subset(&[-5, 11, 22, 33, 40, 42], &[-12, -5, 11, 14, 22, 23, 34, 38]), false); - - if cfg!(miri) { - // Miri is too slow - return; - } - - let large = Vec::from_iter(0..100); - assert_eq!(is_subset(&[], &large), true); - assert_eq!(is_subset(&large, &[]), false); - assert_eq!(is_subset(&[-1], &large), false); - assert_eq!(is_subset(&[0], &large), true); - assert_eq!(is_subset(&[1, 2], &large), true); - assert_eq!(is_subset(&[99, 100], &large), false); -} - -#[test] -fn test_is_superset() { - fn is_superset(a: &[i32], b: &[i32]) -> bool { - let set_a = BTreeSet::from_iter(a.iter()); - let set_b = BTreeSet::from_iter(b.iter()); - set_a.is_superset(&set_b) - } - - assert_eq!(is_superset(&[], &[]), true); - assert_eq!(is_superset(&[], &[1, 2]), false); - assert_eq!(is_superset(&[0], &[1, 2]), false); - assert_eq!(is_superset(&[1], &[1, 2]), false); - assert_eq!(is_superset(&[4], &[1, 2]), false); - assert_eq!(is_superset(&[1, 4], &[1, 2]), false); - assert_eq!(is_superset(&[1, 2], &[1, 2]), true); - assert_eq!(is_superset(&[1, 2, 3], &[1, 3]), true); - assert_eq!(is_superset(&[1, 2, 3], &[]), true); - assert_eq!(is_superset(&[-1, 1, 2, 3], &[-1, 3]), true); - - if cfg!(miri) { - // Miri is too slow - return; - } - - let large = Vec::from_iter(0..100); - assert_eq!(is_superset(&[], &large), false); - assert_eq!(is_superset(&large, &[]), true); - assert_eq!(is_superset(&large, &[1]), true); - assert_eq!(is_superset(&large, &[50, 99]), true); - assert_eq!(is_superset(&large, &[100]), false); - assert_eq!(is_superset(&large, &[0, 99]), true); - assert_eq!(is_superset(&[-1], &large), false); - assert_eq!(is_superset(&[0], &large), false); - assert_eq!(is_superset(&[99, 100], &large), false); -} - -#[test] -fn test_retain() { - let mut set = BTreeSet::from([1, 2, 3, 4, 5, 6]); - set.retain(|&k| k % 2 == 0); - assert_eq!(set.len(), 3); - assert!(set.contains(&2)); - assert!(set.contains(&4)); - assert!(set.contains(&6)); -} - -#[test] -fn test_extract_if() { - let mut x = BTreeSet::from([1]); - let mut y = BTreeSet::from([1]); - - x.extract_if(|_| true).for_each(drop); - y.extract_if(|_| false).for_each(drop); - assert_eq!(x.len(), 0); - assert_eq!(y.len(), 1); -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_extract_if_drop_panic_leak() { - let a = CrashTestDummy::new(0); - let b = CrashTestDummy::new(1); - let c = CrashTestDummy::new(2); - let mut set = BTreeSet::new(); - set.insert(a.spawn(Panic::Never)); - set.insert(b.spawn(Panic::InDrop)); - set.insert(c.spawn(Panic::Never)); - - catch_unwind(move || set.extract_if(|dummy| dummy.query(true)).for_each(drop)).ok(); - - assert_eq!(a.queried(), 1); - assert_eq!(b.queried(), 1); - assert_eq!(c.queried(), 0); - assert_eq!(a.dropped(), 1); - assert_eq!(b.dropped(), 1); - assert_eq!(c.dropped(), 1); -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_extract_if_pred_panic_leak() { - let a = CrashTestDummy::new(0); - let b = CrashTestDummy::new(1); - let c = CrashTestDummy::new(2); - let mut set = BTreeSet::new(); - set.insert(a.spawn(Panic::Never)); - set.insert(b.spawn(Panic::InQuery)); - set.insert(c.spawn(Panic::InQuery)); - - catch_unwind(AssertUnwindSafe(|| set.extract_if(|dummy| dummy.query(true)).for_each(drop))) - .ok(); - - assert_eq!(a.queried(), 1); - assert_eq!(b.queried(), 1); - assert_eq!(c.queried(), 0); - assert_eq!(a.dropped(), 1); - assert_eq!(b.dropped(), 0); - assert_eq!(c.dropped(), 0); - assert_eq!(set.len(), 2); - assert_eq!(set.first().unwrap().id(), 1); - assert_eq!(set.last().unwrap().id(), 2); -} - -#[test] -fn test_clear() { - let mut x = BTreeSet::new(); - x.insert(1); - - x.clear(); - assert!(x.is_empty()); -} -#[test] -fn test_remove() { - let mut x = BTreeSet::new(); - assert!(x.is_empty()); - - x.insert(1); - x.insert(2); - x.insert(3); - x.insert(4); - - assert_eq!(x.remove(&2), true); - assert_eq!(x.remove(&0), false); - assert_eq!(x.remove(&5), false); - assert_eq!(x.remove(&1), true); - assert_eq!(x.remove(&2), false); - assert_eq!(x.remove(&3), true); - assert_eq!(x.remove(&4), true); - assert_eq!(x.remove(&4), false); - assert!(x.is_empty()); -} - -#[test] -fn test_zip() { - let mut x = BTreeSet::new(); - x.insert(5); - x.insert(12); - x.insert(11); - - let mut y = BTreeSet::new(); - y.insert("foo"); - y.insert("bar"); - - let x = x; - let y = y; - let mut z = x.iter().zip(&y); - - assert_eq!(z.next().unwrap(), (&5, &("bar"))); - assert_eq!(z.next().unwrap(), (&11, &("foo"))); - assert!(z.next().is_none()); -} - -#[test] -fn test_from_iter() { - let xs = [1, 2, 3, 4, 5, 6, 7, 8, 9]; - - let set = BTreeSet::from_iter(xs.iter()); - - for x in &xs { - assert!(set.contains(x)); - } -} - -#[test] -fn test_show() { - let mut set = BTreeSet::new(); - let empty = BTreeSet::::new(); - - set.insert(1); - set.insert(2); - - let set_str = format!("{set:?}"); - - assert_eq!(set_str, "{1, 2}"); - assert_eq!(format!("{empty:?}"), "{}"); -} - -#[test] -fn test_extend_ref() { - let mut a = BTreeSet::new(); - a.insert(1); - - a.extend(&[2, 3, 4]); - - assert_eq!(a.len(), 4); - assert!(a.contains(&1)); - assert!(a.contains(&2)); - assert!(a.contains(&3)); - assert!(a.contains(&4)); - - let mut b = BTreeSet::new(); - b.insert(5); - b.insert(6); - - a.extend(&b); - - assert_eq!(a.len(), 6); - assert!(a.contains(&1)); - assert!(a.contains(&2)); - assert!(a.contains(&3)); - assert!(a.contains(&4)); - assert!(a.contains(&5)); - assert!(a.contains(&6)); -} - -#[test] -fn test_recovery() { - #[derive(Debug)] - struct Foo(&'static str, #[allow(dead_code)] i32); - - impl PartialEq for Foo { - fn eq(&self, other: &Self) -> bool { - self.0 == other.0 - } - } - - impl Eq for Foo {} - - impl PartialOrd for Foo { - fn partial_cmp(&self, other: &Self) -> Option { - self.0.partial_cmp(&other.0) - } - } - - impl Ord for Foo { - fn cmp(&self, other: &Self) -> Ordering { - self.0.cmp(&other.0) - } - } - - let mut s = BTreeSet::new(); - assert_eq!(s.replace(Foo("a", 1)), None); - assert_eq!(s.len(), 1); - assert_eq!(s.replace(Foo("a", 2)), Some(Foo("a", 1))); - assert_eq!(s.len(), 1); - - { - let mut it = s.iter(); - assert_eq!(it.next(), Some(&Foo("a", 2))); - assert_eq!(it.next(), None); - } - - assert_eq!(s.get(&Foo("a", 1)), Some(&Foo("a", 2))); - assert_eq!(s.take(&Foo("a", 1)), Some(Foo("a", 2))); - assert_eq!(s.len(), 0); - - assert_eq!(s.get(&Foo("a", 1)), None); - assert_eq!(s.take(&Foo("a", 1)), None); - - assert_eq!(s.iter().next(), None); -} - -#[allow(dead_code)] -fn assert_covariance() { - fn set<'new>(v: BTreeSet<&'static str>) -> BTreeSet<&'new str> { - v - } - fn iter<'a, 'new>(v: Iter<'a, &'static str>) -> Iter<'a, &'new str> { - v - } - fn into_iter<'new>(v: IntoIter<&'static str>) -> IntoIter<&'new str> { - v - } - fn range<'a, 'new>(v: Range<'a, &'static str>) -> Range<'a, &'new str> { - v - } - // not applied to Difference, Intersection, SymmetricDifference, Union -} - -#[allow(dead_code)] -fn assert_sync() { - fn set(v: &BTreeSet) -> impl Sync + '_ { - v - } - - fn iter(v: &BTreeSet) -> impl Sync + '_ { - v.iter() - } - - fn into_iter(v: BTreeSet) -> impl Sync { - v.into_iter() - } - - fn range(v: &BTreeSet) -> impl Sync + '_ { - v.range(..) - } - - fn extract_if(v: &mut BTreeSet) -> impl Sync + '_ { - v.extract_if(|_| false) - } - - fn difference(v: &BTreeSet) -> impl Sync + '_ { - v.difference(&v) - } - - fn intersection(v: &BTreeSet) -> impl Sync + '_ { - v.intersection(&v) - } - - fn symmetric_difference(v: &BTreeSet) -> impl Sync + '_ { - v.symmetric_difference(&v) - } - - fn union(v: &BTreeSet) -> impl Sync + '_ { - v.union(&v) - } -} - -#[allow(dead_code)] -fn assert_send() { - fn set(v: BTreeSet) -> impl Send { - v - } - - fn iter(v: &BTreeSet) -> impl Send + '_ { - v.iter() - } - - fn into_iter(v: BTreeSet) -> impl Send { - v.into_iter() - } - - fn range(v: &BTreeSet) -> impl Send + '_ { - v.range(..) - } - - fn extract_if(v: &mut BTreeSet) -> impl Send + '_ { - v.extract_if(|_| false) - } - - fn difference(v: &BTreeSet) -> impl Send + '_ { - v.difference(&v) - } - - fn intersection(v: &BTreeSet) -> impl Send + '_ { - v.intersection(&v) - } - - fn symmetric_difference(v: &BTreeSet) -> impl Send + '_ { - v.symmetric_difference(&v) - } - - fn union(v: &BTreeSet) -> impl Send + '_ { - v.union(&v) - } -} - -#[allow(dead_code)] -// Check that the member-like functions conditionally provided by #[derive()] -// are not overridden by genuine member functions with a different signature. -fn assert_derives() { - fn hash(v: BTreeSet, state: &mut H) { - v.hash(state); - // Tested much more thoroughly outside the crate in btree_set_hash.rs - } - fn eq(v: BTreeSet) { - let _ = v.eq(&v); - } - fn ne(v: BTreeSet) { - let _ = v.ne(&v); - } - fn cmp(v: BTreeSet) { - let _ = v.cmp(&v); - } - fn min(v: BTreeSet, w: BTreeSet) { - let _ = v.min(w); - } - fn max(v: BTreeSet, w: BTreeSet) { - let _ = v.max(w); - } - fn clamp(v: BTreeSet, w: BTreeSet, x: BTreeSet) { - let _ = v.clamp(w, x); - } - fn partial_cmp(v: &BTreeSet) { - let _ = v.partial_cmp(&v); - } -} - -#[test] -fn test_ord_absence() { - fn set(mut set: BTreeSet) { - let _ = set.is_empty(); - let _ = set.len(); - set.clear(); - let _ = set.iter(); - let _ = set.into_iter(); - } - - fn set_debug(set: BTreeSet) { - format!("{set:?}"); - format!("{:?}", set.iter()); - format!("{:?}", set.into_iter()); - } - - fn set_clone(mut set: BTreeSet) { - set.clone_from(&set.clone()); - } - - #[derive(Debug, Clone)] - struct NonOrd; - set(BTreeSet::::new()); - set_debug(BTreeSet::::new()); - set_clone(BTreeSet::::default()); -} - -#[test] -fn test_append() { - let mut a = BTreeSet::new(); - a.insert(1); - a.insert(2); - a.insert(3); - - let mut b = BTreeSet::new(); - b.insert(3); - b.insert(4); - b.insert(5); - - a.append(&mut b); - - assert_eq!(a.len(), 5); - assert_eq!(b.len(), 0); - - assert_eq!(a.contains(&1), true); - assert_eq!(a.contains(&2), true); - assert_eq!(a.contains(&3), true); - assert_eq!(a.contains(&4), true); - assert_eq!(a.contains(&5), true); -} - -#[test] -fn test_first_last() { - let mut a = BTreeSet::new(); - assert_eq!(a.first(), None); - assert_eq!(a.last(), None); - a.insert(1); - assert_eq!(a.first(), Some(&1)); - assert_eq!(a.last(), Some(&1)); - a.insert(2); - assert_eq!(a.first(), Some(&1)); - assert_eq!(a.last(), Some(&2)); - for i in 3..=12 { - a.insert(i); - } - assert_eq!(a.first(), Some(&1)); - assert_eq!(a.last(), Some(&12)); - assert_eq!(a.pop_first(), Some(1)); - assert_eq!(a.pop_last(), Some(12)); - assert_eq!(a.pop_first(), Some(2)); - assert_eq!(a.pop_last(), Some(11)); - assert_eq!(a.pop_first(), Some(3)); - assert_eq!(a.pop_last(), Some(10)); - assert_eq!(a.pop_first(), Some(4)); - assert_eq!(a.pop_first(), Some(5)); - assert_eq!(a.pop_first(), Some(6)); - assert_eq!(a.pop_first(), Some(7)); - assert_eq!(a.pop_first(), Some(8)); - assert_eq!(a.clone().pop_last(), Some(9)); - assert_eq!(a.pop_first(), Some(9)); - assert_eq!(a.pop_first(), None); - assert_eq!(a.pop_last(), None); -} - -// Unlike the function with the same name in map/tests, returns no values. -// Which also means it returns different predetermined pseudo-random keys, -// and the test cases using this function explore slightly different trees. -fn rand_data(len: usize) -> Vec { - let mut rng = DeterministicRng::new(); - Vec::from_iter((0..len).map(|_| rng.next())) -} - -#[test] -fn test_split_off_empty_right() { - let mut data = rand_data(173); - - let mut set = BTreeSet::from_iter(data.clone()); - let right = set.split_off(&(data.iter().max().unwrap() + 1)); - - data.sort(); - assert!(set.into_iter().eq(data)); - assert!(right.into_iter().eq(None)); -} - -#[test] -fn test_split_off_empty_left() { - let mut data = rand_data(314); - - let mut set = BTreeSet::from_iter(data.clone()); - let right = set.split_off(data.iter().min().unwrap()); - - data.sort(); - assert!(set.into_iter().eq(None)); - assert!(right.into_iter().eq(data)); -} - -#[test] -fn test_split_off_large_random_sorted() { - // Miri is too slow - let mut data = if cfg!(miri) { rand_data(529) } else { rand_data(1529) }; - // special case with maximum height. - data.sort(); - - let mut set = BTreeSet::from_iter(data.clone()); - let key = data[data.len() / 2]; - let right = set.split_off(&key); - - assert!(set.into_iter().eq(data.clone().into_iter().filter(|x| *x < key))); - assert!(right.into_iter().eq(data.into_iter().filter(|x| *x >= key))); -} - -#[test] -fn from_array() { - let set = BTreeSet::from([1, 2, 3, 4]); - let unordered_duplicates = BTreeSet::from([4, 1, 4, 3, 2]); - assert_eq!(set, unordered_duplicates); -} - -#[should_panic(expected = "range start is greater than range end in BTreeSet")] -#[test] -fn test_range_panic_1() { - let mut set = BTreeSet::new(); - set.insert(3); - set.insert(5); - set.insert(8); - - let _invalid_range = set.range((Included(&8), Included(&3))); -} - -#[should_panic(expected = "range start and end are equal and excluded in BTreeSet")] -#[test] -fn test_range_panic_2() { - let mut set = BTreeSet::new(); - set.insert(3); - set.insert(5); - set.insert(8); - - let _invalid_range = set.range((Excluded(&5), Excluded(&5))); -} diff --git a/library/alloc/src/collections/btree/set_val.rs b/library/alloc/src/collections/btree/set_val.rs deleted file mode 100644 index 80c459bcf81db..0000000000000 --- a/library/alloc/src/collections/btree/set_val.rs +++ /dev/null @@ -1,29 +0,0 @@ -/// Zero-Sized Type (ZST) for internal `BTreeSet` values. -/// Used instead of `()` to differentiate between: -/// * `BTreeMap` (possible user-defined map) -/// * `BTreeMap` (internal set representation) -#[derive(Debug, Eq, PartialEq, Ord, PartialOrd, Hash, Clone, Default)] -pub struct SetValZST; - -/// A trait to differentiate between `BTreeMap` and `BTreeSet` values. -/// Returns `true` only for type `SetValZST`, `false` for all other types (blanket implementation). -/// `TypeId` requires a `'static` lifetime, use of this trait avoids that restriction. -/// -/// [`TypeId`]: std::any::TypeId -pub trait IsSetVal { - fn is_set_val() -> bool; -} - -// Blanket implementation -impl IsSetVal for V { - default fn is_set_val() -> bool { - false - } -} - -// Specialization -impl IsSetVal for SetValZST { - fn is_set_val() -> bool { - true - } -} diff --git a/library/alloc/src/collections/btree/split.rs b/library/alloc/src/collections/btree/split.rs deleted file mode 100644 index 638dc98fc3e41..0000000000000 --- a/library/alloc/src/collections/btree/split.rs +++ /dev/null @@ -1,73 +0,0 @@ -use super::node::{ForceResult::*, Root}; -use super::search::SearchResult::*; -use core::alloc::Allocator; -use core::borrow::Borrow; - -impl Root { - /// Calculates the length of both trees that result from splitting up - /// a given number of distinct key-value pairs. - pub fn calc_split_length( - total_num: usize, - root_a: &Root, - root_b: &Root, - ) -> (usize, usize) { - let (length_a, length_b); - if root_a.height() < root_b.height() { - length_a = root_a.reborrow().calc_length(); - length_b = total_num - length_a; - debug_assert_eq!(length_b, root_b.reborrow().calc_length()); - } else { - length_b = root_b.reborrow().calc_length(); - length_a = total_num - length_b; - debug_assert_eq!(length_a, root_a.reborrow().calc_length()); - } - (length_a, length_b) - } - - /// Split off a tree with key-value pairs at and after the given key. - /// The result is meaningful only if the tree is ordered by key, - /// and if the ordering of `Q` corresponds to that of `K`. - /// If `self` respects all `BTreeMap` tree invariants, then both - /// `self` and the returned tree will respect those invariants. - pub fn split_off(&mut self, key: &Q, alloc: A) -> Self - where - K: Borrow, - { - let left_root = self; - let mut right_root = Root::new_pillar(left_root.height(), alloc.clone()); - let mut left_node = left_root.borrow_mut(); - let mut right_node = right_root.borrow_mut(); - - loop { - let mut split_edge = match left_node.search_node(key) { - // key is going to the right tree - Found(kv) => kv.left_edge(), - GoDown(edge) => edge, - }; - - split_edge.move_suffix(&mut right_node); - - match (split_edge.force(), right_node.force()) { - (Internal(edge), Internal(node)) => { - left_node = edge.descend(); - right_node = node.first_edge().descend(); - } - (Leaf(_), Leaf(_)) => break, - _ => unreachable!(), - } - } - - left_root.fix_right_border(alloc.clone()); - right_root.fix_left_border(alloc); - right_root - } - - /// Creates a tree consisting of empty nodes. - fn new_pillar(height: usize, alloc: A) -> Self { - let mut root = Root::new(alloc.clone()); - for _ in 0..height { - root.push_internal_level(alloc.clone()); - } - root - } -} diff --git a/library/alloc/src/collections/linked_list.rs b/library/alloc/src/collections/linked_list.rs deleted file mode 100644 index 1c90c171a155b..0000000000000 --- a/library/alloc/src/collections/linked_list.rs +++ /dev/null @@ -1,2224 +0,0 @@ -//! A doubly-linked list with owned nodes. -//! -//! The `LinkedList` allows pushing and popping elements at either end -//! in constant time. -//! -//! NOTE: It is almost always better to use [`Vec`] or [`VecDeque`] because -//! array-based containers are generally faster, -//! more memory efficient, and make better use of CPU cache. -//! -//! [`Vec`]: crate::vec::Vec -//! [`VecDeque`]: super::vec_deque::VecDeque - -#![stable(feature = "rust1", since = "1.0.0")] - -use core::cmp::Ordering; -use core::fmt; -use core::hash::{Hash, Hasher}; -use core::iter::FusedIterator; -use core::marker::PhantomData; -use core::mem; -use core::ptr::NonNull; - -use super::SpecExtend; -use crate::alloc::{Allocator, Global}; -use crate::boxed::Box; - -#[cfg(test)] -mod tests; - -/// A doubly-linked list with owned nodes. -/// -/// The `LinkedList` allows pushing and popping elements at either end -/// in constant time. -/// -/// A `LinkedList` with a known list of items can be initialized from an array: -/// ``` -/// use std::collections::LinkedList; -/// -/// let list = LinkedList::from([1, 2, 3]); -/// ``` -/// -/// NOTE: It is almost always better to use [`Vec`] or [`VecDeque`] because -/// array-based containers are generally faster, -/// more memory efficient, and make better use of CPU cache. -/// -/// [`Vec`]: crate::vec::Vec -/// [`VecDeque`]: super::vec_deque::VecDeque -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "LinkedList")] -#[rustc_insignificant_dtor] -pub struct LinkedList< - T, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, -> { - head: Option>>, - tail: Option>>, - len: usize, - alloc: A, - marker: PhantomData, A>>, -} - -struct Node { - next: Option>>, - prev: Option>>, - element: T, -} - -/// An iterator over the elements of a `LinkedList`. -/// -/// This `struct` is created by [`LinkedList::iter()`]. See its -/// documentation for more. -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Iter<'a, T: 'a> { - head: Option>>, - tail: Option>>, - len: usize, - marker: PhantomData<&'a Node>, -} - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl fmt::Debug for Iter<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("Iter") - .field(&*mem::ManuallyDrop::new(LinkedList { - head: self.head, - tail: self.tail, - len: self.len, - alloc: Global, - marker: PhantomData, - })) - .field(&self.len) - .finish() - } -} - -// FIXME(#26925) Remove in favor of `#[derive(Clone)]` -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Iter<'_, T> { - fn clone(&self) -> Self { - Iter { ..*self } - } -} - -/// A mutable iterator over the elements of a `LinkedList`. -/// -/// This `struct` is created by [`LinkedList::iter_mut()`]. See its -/// documentation for more. -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct IterMut<'a, T: 'a> { - head: Option>>, - tail: Option>>, - len: usize, - marker: PhantomData<&'a mut Node>, -} - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl fmt::Debug for IterMut<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("IterMut") - .field(&*mem::ManuallyDrop::new(LinkedList { - head: self.head, - tail: self.tail, - len: self.len, - alloc: Global, - marker: PhantomData, - })) - .field(&self.len) - .finish() - } -} - -/// An owning iterator over the elements of a `LinkedList`. -/// -/// This `struct` is created by the [`into_iter`] method on [`LinkedList`] -/// (provided by the [`IntoIterator`] trait). See its documentation for more. -/// -/// [`into_iter`]: LinkedList::into_iter -#[derive(Clone)] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct IntoIter< - T, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, -> { - list: LinkedList, -} - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl fmt::Debug for IntoIter { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("IntoIter").field(&self.list).finish() - } -} - -impl Node { - fn new(element: T) -> Self { - Node { next: None, prev: None, element } - } - - fn into_element(self: Box) -> T { - self.element - } -} - -// private methods -impl LinkedList { - /// Adds the given node to the front of the list. - /// - /// # Safety - /// `node` must point to a valid node that was boxed and leaked using the list's allocator. - /// This method takes ownership of the node, so the pointer should not be used again. - #[inline] - unsafe fn push_front_node(&mut self, node: NonNull>) { - // This method takes care not to create mutable references to whole nodes, - // to maintain validity of aliasing pointers into `element`. - unsafe { - (*node.as_ptr()).next = self.head; - (*node.as_ptr()).prev = None; - let node = Some(node); - - match self.head { - None => self.tail = node, - // Not creating new mutable (unique!) references overlapping `element`. - Some(head) => (*head.as_ptr()).prev = node, - } - - self.head = node; - self.len += 1; - } - } - - /// Removes and returns the node at the front of the list. - #[inline] - fn pop_front_node(&mut self) -> Option, &A>> { - // This method takes care not to create mutable references to whole nodes, - // to maintain validity of aliasing pointers into `element`. - self.head.map(|node| unsafe { - let node = Box::from_raw_in(node.as_ptr(), &self.alloc); - self.head = node.next; - - match self.head { - None => self.tail = None, - // Not creating new mutable (unique!) references overlapping `element`. - Some(head) => (*head.as_ptr()).prev = None, - } - - self.len -= 1; - node - }) - } - - /// Adds the given node to the back of the list. - /// - /// # Safety - /// `node` must point to a valid node that was boxed and leaked using the list's allocator. - /// This method takes ownership of the node, so the pointer should not be used again. - #[inline] - unsafe fn push_back_node(&mut self, node: NonNull>) { - // This method takes care not to create mutable references to whole nodes, - // to maintain validity of aliasing pointers into `element`. - unsafe { - (*node.as_ptr()).next = None; - (*node.as_ptr()).prev = self.tail; - let node = Some(node); - - match self.tail { - None => self.head = node, - // Not creating new mutable (unique!) references overlapping `element`. - Some(tail) => (*tail.as_ptr()).next = node, - } - - self.tail = node; - self.len += 1; - } - } - - /// Removes and returns the node at the back of the list. - #[inline] - fn pop_back_node(&mut self) -> Option, &A>> { - // This method takes care not to create mutable references to whole nodes, - // to maintain validity of aliasing pointers into `element`. - self.tail.map(|node| unsafe { - let node = Box::from_raw_in(node.as_ptr(), &self.alloc); - self.tail = node.prev; - - match self.tail { - None => self.head = None, - // Not creating new mutable (unique!) references overlapping `element`. - Some(tail) => (*tail.as_ptr()).next = None, - } - - self.len -= 1; - node - }) - } - - /// Unlinks the specified node from the current list. - /// - /// Warning: this will not check that the provided node belongs to the current list. - /// - /// This method takes care not to create mutable references to `element`, to - /// maintain validity of aliasing pointers. - #[inline] - unsafe fn unlink_node(&mut self, mut node: NonNull>) { - let node = unsafe { node.as_mut() }; // this one is ours now, we can create an &mut. - - // Not creating new mutable (unique!) references overlapping `element`. - match node.prev { - Some(prev) => unsafe { (*prev.as_ptr()).next = node.next }, - // this node is the head node - None => self.head = node.next, - }; - - match node.next { - Some(next) => unsafe { (*next.as_ptr()).prev = node.prev }, - // this node is the tail node - None => self.tail = node.prev, - }; - - self.len -= 1; - } - - /// Splices a series of nodes between two existing nodes. - /// - /// Warning: this will not check that the provided node belongs to the two existing lists. - #[inline] - unsafe fn splice_nodes( - &mut self, - existing_prev: Option>>, - existing_next: Option>>, - mut splice_start: NonNull>, - mut splice_end: NonNull>, - splice_length: usize, - ) { - // This method takes care not to create multiple mutable references to whole nodes at the same time, - // to maintain validity of aliasing pointers into `element`. - if let Some(mut existing_prev) = existing_prev { - unsafe { - existing_prev.as_mut().next = Some(splice_start); - } - } else { - self.head = Some(splice_start); - } - if let Some(mut existing_next) = existing_next { - unsafe { - existing_next.as_mut().prev = Some(splice_end); - } - } else { - self.tail = Some(splice_end); - } - unsafe { - splice_start.as_mut().prev = existing_prev; - splice_end.as_mut().next = existing_next; - } - - self.len += splice_length; - } - - /// Detaches all nodes from a linked list as a series of nodes. - #[inline] - fn detach_all_nodes(mut self) -> Option<(NonNull>, NonNull>, usize)> { - let head = self.head.take(); - let tail = self.tail.take(); - let len = mem::replace(&mut self.len, 0); - if let Some(head) = head { - // SAFETY: In a LinkedList, either both the head and tail are None because - // the list is empty, or both head and tail are Some because the list is populated. - // Since we have verified the head is Some, we are sure the tail is Some too. - let tail = unsafe { tail.unwrap_unchecked() }; - Some((head, tail, len)) - } else { - None - } - } - - #[inline] - unsafe fn split_off_before_node( - &mut self, - split_node: Option>>, - at: usize, - ) -> Self - where - A: Clone, - { - // The split node is the new head node of the second part - if let Some(mut split_node) = split_node { - let first_part_head; - let first_part_tail; - unsafe { - first_part_tail = split_node.as_mut().prev.take(); - } - if let Some(mut tail) = first_part_tail { - unsafe { - tail.as_mut().next = None; - } - first_part_head = self.head; - } else { - first_part_head = None; - } - - let first_part = LinkedList { - head: first_part_head, - tail: first_part_tail, - len: at, - alloc: self.alloc.clone(), - marker: PhantomData, - }; - - // Fix the head ptr of the second part - self.head = Some(split_node); - self.len = self.len - at; - - first_part - } else { - mem::replace(self, LinkedList::new_in(self.alloc.clone())) - } - } - - #[inline] - unsafe fn split_off_after_node( - &mut self, - split_node: Option>>, - at: usize, - ) -> Self - where - A: Clone, - { - // The split node is the new tail node of the first part and owns - // the head of the second part. - if let Some(mut split_node) = split_node { - let second_part_head; - let second_part_tail; - unsafe { - second_part_head = split_node.as_mut().next.take(); - } - if let Some(mut head) = second_part_head { - unsafe { - head.as_mut().prev = None; - } - second_part_tail = self.tail; - } else { - second_part_tail = None; - } - - let second_part = LinkedList { - head: second_part_head, - tail: second_part_tail, - len: self.len - at, - alloc: self.alloc.clone(), - marker: PhantomData, - }; - - // Fix the tail ptr of the first part - self.tail = Some(split_node); - self.len = at; - - second_part - } else { - mem::replace(self, LinkedList::new_in(self.alloc.clone())) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Default for LinkedList { - /// Creates an empty `LinkedList`. - #[inline] - fn default() -> Self { - Self::new() - } -} - -impl LinkedList { - /// Creates an empty `LinkedList`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::LinkedList; - /// - /// let list: LinkedList = LinkedList::new(); - /// ``` - #[inline] - #[rustc_const_stable(feature = "const_linked_list_new", since = "1.39.0")] - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - pub const fn new() -> Self { - LinkedList { head: None, tail: None, len: 0, alloc: Global, marker: PhantomData } - } - - /// Moves all elements from `other` to the end of the list. - /// - /// This reuses all the nodes from `other` and moves them into `self`. After - /// this operation, `other` becomes empty. - /// - /// This operation should compute in *O*(1) time and *O*(1) memory. - /// - /// # Examples - /// - /// ``` - /// use std::collections::LinkedList; - /// - /// let mut list1 = LinkedList::new(); - /// list1.push_back('a'); - /// - /// let mut list2 = LinkedList::new(); - /// list2.push_back('b'); - /// list2.push_back('c'); - /// - /// list1.append(&mut list2); - /// - /// let mut iter = list1.iter(); - /// assert_eq!(iter.next(), Some(&'a')); - /// assert_eq!(iter.next(), Some(&'b')); - /// assert_eq!(iter.next(), Some(&'c')); - /// assert!(iter.next().is_none()); - /// - /// assert!(list2.is_empty()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn append(&mut self, other: &mut Self) { - match self.tail { - None => mem::swap(self, other), - Some(mut tail) => { - // `as_mut` is okay here because we have exclusive access to the entirety - // of both lists. - if let Some(mut other_head) = other.head.take() { - unsafe { - tail.as_mut().next = Some(other_head); - other_head.as_mut().prev = Some(tail); - } - - self.tail = other.tail.take(); - self.len += mem::replace(&mut other.len, 0); - } - } - } - } -} - -impl LinkedList { - /// Constructs an empty `LinkedList`. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// - /// use std::alloc::System; - /// use std::collections::LinkedList; - /// - /// let list: LinkedList = LinkedList::new_in(System); - /// ``` - #[inline] - #[unstable(feature = "allocator_api", issue = "32838")] - pub const fn new_in(alloc: A) -> Self { - LinkedList { head: None, tail: None, len: 0, alloc, marker: PhantomData } - } - /// Provides a forward iterator. - /// - /// # Examples - /// - /// ``` - /// use std::collections::LinkedList; - /// - /// let mut list: LinkedList = LinkedList::new(); - /// - /// list.push_back(0); - /// list.push_back(1); - /// list.push_back(2); - /// - /// let mut iter = list.iter(); - /// assert_eq!(iter.next(), Some(&0)); - /// assert_eq!(iter.next(), Some(&1)); - /// assert_eq!(iter.next(), Some(&2)); - /// assert_eq!(iter.next(), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn iter(&self) -> Iter<'_, T> { - Iter { head: self.head, tail: self.tail, len: self.len, marker: PhantomData } - } - - /// Provides a forward iterator with mutable references. - /// - /// # Examples - /// - /// ``` - /// use std::collections::LinkedList; - /// - /// let mut list: LinkedList = LinkedList::new(); - /// - /// list.push_back(0); - /// list.push_back(1); - /// list.push_back(2); - /// - /// for element in list.iter_mut() { - /// *element += 10; - /// } - /// - /// let mut iter = list.iter(); - /// assert_eq!(iter.next(), Some(&10)); - /// assert_eq!(iter.next(), Some(&11)); - /// assert_eq!(iter.next(), Some(&12)); - /// assert_eq!(iter.next(), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn iter_mut(&mut self) -> IterMut<'_, T> { - IterMut { head: self.head, tail: self.tail, len: self.len, marker: PhantomData } - } - - /// Provides a cursor at the front element. - /// - /// The cursor is pointing to the "ghost" non-element if the list is empty. - #[inline] - #[must_use] - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn cursor_front(&self) -> Cursor<'_, T, A> { - Cursor { index: 0, current: self.head, list: self } - } - - /// Provides a cursor with editing operations at the front element. - /// - /// The cursor is pointing to the "ghost" non-element if the list is empty. - #[inline] - #[must_use] - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn cursor_front_mut(&mut self) -> CursorMut<'_, T, A> { - CursorMut { index: 0, current: self.head, list: self } - } - - /// Provides a cursor at the back element. - /// - /// The cursor is pointing to the "ghost" non-element if the list is empty. - #[inline] - #[must_use] - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn cursor_back(&self) -> Cursor<'_, T, A> { - Cursor { index: self.len.checked_sub(1).unwrap_or(0), current: self.tail, list: self } - } - - /// Provides a cursor with editing operations at the back element. - /// - /// The cursor is pointing to the "ghost" non-element if the list is empty. - #[inline] - #[must_use] - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn cursor_back_mut(&mut self) -> CursorMut<'_, T, A> { - CursorMut { index: self.len.checked_sub(1).unwrap_or(0), current: self.tail, list: self } - } - - /// Returns `true` if the `LinkedList` is empty. - /// - /// This operation should compute in *O*(1) time. - /// - /// # Examples - /// - /// ``` - /// use std::collections::LinkedList; - /// - /// let mut dl = LinkedList::new(); - /// assert!(dl.is_empty()); - /// - /// dl.push_front("foo"); - /// assert!(!dl.is_empty()); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn is_empty(&self) -> bool { - self.head.is_none() - } - - /// Returns the length of the `LinkedList`. - /// - /// This operation should compute in *O*(1) time. - /// - /// # Examples - /// - /// ``` - /// use std::collections::LinkedList; - /// - /// let mut dl = LinkedList::new(); - /// - /// dl.push_front(2); - /// assert_eq!(dl.len(), 1); - /// - /// dl.push_front(1); - /// assert_eq!(dl.len(), 2); - /// - /// dl.push_back(3); - /// assert_eq!(dl.len(), 3); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("length", "size")] - pub fn len(&self) -> usize { - self.len - } - - /// Removes all elements from the `LinkedList`. - /// - /// This operation should compute in *O*(*n*) time. - /// - /// # Examples - /// - /// ``` - /// use std::collections::LinkedList; - /// - /// let mut dl = LinkedList::new(); - /// - /// dl.push_front(2); - /// dl.push_front(1); - /// assert_eq!(dl.len(), 2); - /// assert_eq!(dl.front(), Some(&1)); - /// - /// dl.clear(); - /// assert_eq!(dl.len(), 0); - /// assert_eq!(dl.front(), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn clear(&mut self) { - // We need to drop the nodes while keeping self.alloc - // We can do this by moving (head, tail, len) into a new list that borrows self.alloc - drop(LinkedList { - head: self.head.take(), - tail: self.tail.take(), - len: mem::take(&mut self.len), - alloc: &self.alloc, - marker: PhantomData, - }); - } - - /// Returns `true` if the `LinkedList` contains an element equal to the - /// given value. - /// - /// This operation should compute linearly in *O*(*n*) time. - /// - /// # Examples - /// - /// ``` - /// use std::collections::LinkedList; - /// - /// let mut list: LinkedList = LinkedList::new(); - /// - /// list.push_back(0); - /// list.push_back(1); - /// list.push_back(2); - /// - /// assert_eq!(list.contains(&0), true); - /// assert_eq!(list.contains(&10), false); - /// ``` - #[stable(feature = "linked_list_contains", since = "1.12.0")] - pub fn contains(&self, x: &T) -> bool - where - T: PartialEq, - { - self.iter().any(|e| e == x) - } - - /// Provides a reference to the front element, or `None` if the list is - /// empty. - /// - /// This operation should compute in *O*(1) time. - /// - /// # Examples - /// - /// ``` - /// use std::collections::LinkedList; - /// - /// let mut dl = LinkedList::new(); - /// assert_eq!(dl.front(), None); - /// - /// dl.push_front(1); - /// assert_eq!(dl.front(), Some(&1)); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("first")] - pub fn front(&self) -> Option<&T> { - unsafe { self.head.as_ref().map(|node| &node.as_ref().element) } - } - - /// Provides a mutable reference to the front element, or `None` if the list - /// is empty. - /// - /// This operation should compute in *O*(1) time. - /// - /// # Examples - /// - /// ``` - /// use std::collections::LinkedList; - /// - /// let mut dl = LinkedList::new(); - /// assert_eq!(dl.front(), None); - /// - /// dl.push_front(1); - /// assert_eq!(dl.front(), Some(&1)); - /// - /// match dl.front_mut() { - /// None => {}, - /// Some(x) => *x = 5, - /// } - /// assert_eq!(dl.front(), Some(&5)); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn front_mut(&mut self) -> Option<&mut T> { - unsafe { self.head.as_mut().map(|node| &mut node.as_mut().element) } - } - - /// Provides a reference to the back element, or `None` if the list is - /// empty. - /// - /// This operation should compute in *O*(1) time. - /// - /// # Examples - /// - /// ``` - /// use std::collections::LinkedList; - /// - /// let mut dl = LinkedList::new(); - /// assert_eq!(dl.back(), None); - /// - /// dl.push_back(1); - /// assert_eq!(dl.back(), Some(&1)); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn back(&self) -> Option<&T> { - unsafe { self.tail.as_ref().map(|node| &node.as_ref().element) } - } - - /// Provides a mutable reference to the back element, or `None` if the list - /// is empty. - /// - /// This operation should compute in *O*(1) time. - /// - /// # Examples - /// - /// ``` - /// use std::collections::LinkedList; - /// - /// let mut dl = LinkedList::new(); - /// assert_eq!(dl.back(), None); - /// - /// dl.push_back(1); - /// assert_eq!(dl.back(), Some(&1)); - /// - /// match dl.back_mut() { - /// None => {}, - /// Some(x) => *x = 5, - /// } - /// assert_eq!(dl.back(), Some(&5)); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn back_mut(&mut self) -> Option<&mut T> { - unsafe { self.tail.as_mut().map(|node| &mut node.as_mut().element) } - } - - /// Adds an element first in the list. - /// - /// This operation should compute in *O*(1) time. - /// - /// # Examples - /// - /// ``` - /// use std::collections::LinkedList; - /// - /// let mut dl = LinkedList::new(); - /// - /// dl.push_front(2); - /// assert_eq!(dl.front().unwrap(), &2); - /// - /// dl.push_front(1); - /// assert_eq!(dl.front().unwrap(), &1); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn push_front(&mut self, elt: T) { - let node = Box::new_in(Node::new(elt), &self.alloc); - let node_ptr = NonNull::from(Box::leak(node)); - // SAFETY: node_ptr is a unique pointer to a node we boxed with self.alloc and leaked - unsafe { - self.push_front_node(node_ptr); - } - } - - /// Removes the first element and returns it, or `None` if the list is - /// empty. - /// - /// This operation should compute in *O*(1) time. - /// - /// # Examples - /// - /// ``` - /// use std::collections::LinkedList; - /// - /// let mut d = LinkedList::new(); - /// assert_eq!(d.pop_front(), None); - /// - /// d.push_front(1); - /// d.push_front(3); - /// assert_eq!(d.pop_front(), Some(3)); - /// assert_eq!(d.pop_front(), Some(1)); - /// assert_eq!(d.pop_front(), None); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn pop_front(&mut self) -> Option { - self.pop_front_node().map(Node::into_element) - } - - /// Appends an element to the back of a list. - /// - /// This operation should compute in *O*(1) time. - /// - /// # Examples - /// - /// ``` - /// use std::collections::LinkedList; - /// - /// let mut d = LinkedList::new(); - /// d.push_back(1); - /// d.push_back(3); - /// assert_eq!(3, *d.back().unwrap()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("push", "append")] - pub fn push_back(&mut self, elt: T) { - let node = Box::new_in(Node::new(elt), &self.alloc); - let node_ptr = NonNull::from(Box::leak(node)); - // SAFETY: node_ptr is a unique pointer to a node we boxed with self.alloc and leaked - unsafe { - self.push_back_node(node_ptr); - } - } - - /// Removes the last element from a list and returns it, or `None` if - /// it is empty. - /// - /// This operation should compute in *O*(1) time. - /// - /// # Examples - /// - /// ``` - /// use std::collections::LinkedList; - /// - /// let mut d = LinkedList::new(); - /// assert_eq!(d.pop_back(), None); - /// d.push_back(1); - /// d.push_back(3); - /// assert_eq!(d.pop_back(), Some(3)); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn pop_back(&mut self) -> Option { - self.pop_back_node().map(Node::into_element) - } - - /// Splits the list into two at the given index. Returns everything after the given index, - /// including the index. - /// - /// This operation should compute in *O*(*n*) time. - /// - /// # Panics - /// - /// Panics if `at > len`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::LinkedList; - /// - /// let mut d = LinkedList::new(); - /// - /// d.push_front(1); - /// d.push_front(2); - /// d.push_front(3); - /// - /// let mut split = d.split_off(2); - /// - /// assert_eq!(split.pop_front(), Some(1)); - /// assert_eq!(split.pop_front(), None); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn split_off(&mut self, at: usize) -> LinkedList - where - A: Clone, - { - let len = self.len(); - assert!(at <= len, "Cannot split off at a nonexistent index"); - if at == 0 { - return mem::replace(self, Self::new_in(self.alloc.clone())); - } else if at == len { - return Self::new_in(self.alloc.clone()); - } - - // Below, we iterate towards the `i-1`th node, either from the start or the end, - // depending on which would be faster. - let split_node = if at - 1 <= len - 1 - (at - 1) { - let mut iter = self.iter_mut(); - // instead of skipping using .skip() (which creates a new struct), - // we skip manually so we can access the head field without - // depending on implementation details of Skip - for _ in 0..at - 1 { - iter.next(); - } - iter.head - } else { - // better off starting from the end - let mut iter = self.iter_mut(); - for _ in 0..len - 1 - (at - 1) { - iter.next_back(); - } - iter.tail - }; - unsafe { self.split_off_after_node(split_node, at) } - } - - /// Removes the element at the given index and returns it. - /// - /// This operation should compute in *O*(*n*) time. - /// - /// # Panics - /// Panics if at >= len - /// - /// # Examples - /// - /// ``` - /// #![feature(linked_list_remove)] - /// use std::collections::LinkedList; - /// - /// let mut d = LinkedList::new(); - /// - /// d.push_front(1); - /// d.push_front(2); - /// d.push_front(3); - /// - /// assert_eq!(d.remove(1), 2); - /// assert_eq!(d.remove(0), 3); - /// assert_eq!(d.remove(0), 1); - /// ``` - #[unstable(feature = "linked_list_remove", issue = "69210")] - #[rustc_confusables("delete", "take")] - pub fn remove(&mut self, at: usize) -> T { - let len = self.len(); - assert!(at < len, "Cannot remove at an index outside of the list bounds"); - - // Below, we iterate towards the node at the given index, either from - // the start or the end, depending on which would be faster. - let offset_from_end = len - at - 1; - if at <= offset_from_end { - let mut cursor = self.cursor_front_mut(); - for _ in 0..at { - cursor.move_next(); - } - cursor.remove_current().unwrap() - } else { - let mut cursor = self.cursor_back_mut(); - for _ in 0..offset_from_end { - cursor.move_prev(); - } - cursor.remove_current().unwrap() - } - } - - /// Retains only the elements specified by the predicate. - /// - /// In other words, remove all elements `e` for which `f(&e)` returns false. - /// This method operates in place, visiting each element exactly once in the - /// original order, and preserves the order of the retained elements. - /// - /// # Examples - /// - /// ``` - /// #![feature(linked_list_retain)] - /// use std::collections::LinkedList; - /// - /// let mut d = LinkedList::new(); - /// - /// d.push_front(1); - /// d.push_front(2); - /// d.push_front(3); - /// - /// d.retain(|&x| x % 2 == 0); - /// - /// assert_eq!(d.pop_front(), Some(2)); - /// assert_eq!(d.pop_front(), None); - /// ``` - /// - /// Because the elements are visited exactly once in the original order, - /// external state may be used to decide which elements to keep. - /// - /// ``` - /// #![feature(linked_list_retain)] - /// use std::collections::LinkedList; - /// - /// let mut d = LinkedList::new(); - /// - /// d.push_front(1); - /// d.push_front(2); - /// d.push_front(3); - /// - /// let keep = [false, true, false]; - /// let mut iter = keep.iter(); - /// d.retain(|_| *iter.next().unwrap()); - /// assert_eq!(d.pop_front(), Some(2)); - /// assert_eq!(d.pop_front(), None); - /// ``` - #[unstable(feature = "linked_list_retain", issue = "114135")] - pub fn retain(&mut self, mut f: F) - where - F: FnMut(&T) -> bool, - { - self.retain_mut(|elem| f(elem)); - } - - /// Retains only the elements specified by the predicate. - /// - /// In other words, remove all elements `e` for which `f(&e)` returns false. - /// This method operates in place, visiting each element exactly once in the - /// original order, and preserves the order of the retained elements. - /// - /// # Examples - /// - /// ``` - /// #![feature(linked_list_retain)] - /// use std::collections::LinkedList; - /// - /// let mut d = LinkedList::new(); - /// - /// d.push_front(1); - /// d.push_front(2); - /// d.push_front(3); - /// - /// d.retain_mut(|x| if *x % 2 == 0 { - /// *x += 1; - /// true - /// } else { - /// false - /// }); - /// assert_eq!(d.pop_front(), Some(3)); - /// assert_eq!(d.pop_front(), None); - /// ``` - #[unstable(feature = "linked_list_retain", issue = "114135")] - pub fn retain_mut(&mut self, mut f: F) - where - F: FnMut(&mut T) -> bool, - { - let mut cursor = self.cursor_front_mut(); - while let Some(node) = cursor.current() { - if !f(node) { - cursor.remove_current().unwrap(); - } else { - cursor.move_next(); - } - } - } - - /// Creates an iterator which uses a closure to determine if an element should be removed. - /// - /// If the closure returns true, then the element is removed and yielded. - /// If the closure returns false, the element will remain in the list and will not be yielded - /// by the iterator. - /// - /// If the returned `ExtractIf` is not exhausted, e.g. because it is dropped without iterating - /// or the iteration short-circuits, then the remaining elements will be retained. - /// Use `extract_if().for_each(drop)` if you do not need the returned iterator. - /// - /// Note that `extract_if` lets you mutate every element in the filter closure, regardless of - /// whether you choose to keep or remove it. - /// - /// # Examples - /// - /// Splitting a list into evens and odds, reusing the original list: - /// - /// ``` - /// #![feature(extract_if)] - /// use std::collections::LinkedList; - /// - /// let mut numbers: LinkedList = LinkedList::new(); - /// numbers.extend(&[1, 2, 3, 4, 5, 6, 8, 9, 11, 13, 14, 15]); - /// - /// let evens = numbers.extract_if(|x| *x % 2 == 0).collect::>(); - /// let odds = numbers; - /// - /// assert_eq!(evens.into_iter().collect::>(), vec![2, 4, 6, 8, 14]); - /// assert_eq!(odds.into_iter().collect::>(), vec![1, 3, 5, 9, 11, 13, 15]); - /// ``` - #[unstable(feature = "extract_if", reason = "recently added", issue = "43244")] - pub fn extract_if(&mut self, filter: F) -> ExtractIf<'_, T, F, A> - where - F: FnMut(&mut T) -> bool, - { - // avoid borrow issues. - let it = self.head; - let old_len = self.len; - - ExtractIf { list: self, it, pred: filter, idx: 0, old_len } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl<#[may_dangle] T, A: Allocator> Drop for LinkedList { - fn drop(&mut self) { - struct DropGuard<'a, T, A: Allocator>(&'a mut LinkedList); - - impl<'a, T, A: Allocator> Drop for DropGuard<'a, T, A> { - fn drop(&mut self) { - // Continue the same loop we do below. This only runs when a destructor has - // panicked. If another one panics this will abort. - while self.0.pop_front_node().is_some() {} - } - } - - // Wrap self so that if a destructor panics, we can try to keep looping - let guard = DropGuard(self); - while guard.0.pop_front_node().is_some() {} - mem::forget(guard); - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> Iterator for Iter<'a, T> { - type Item = &'a T; - - #[inline] - fn next(&mut self) -> Option<&'a T> { - if self.len == 0 { - None - } else { - self.head.map(|node| unsafe { - // Need an unbound lifetime to get 'a - let node = &*node.as_ptr(); - self.len -= 1; - self.head = node.next; - &node.element - }) - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - (self.len, Some(self.len)) - } - - #[inline] - fn last(mut self) -> Option<&'a T> { - self.next_back() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> DoubleEndedIterator for Iter<'a, T> { - #[inline] - fn next_back(&mut self) -> Option<&'a T> { - if self.len == 0 { - None - } else { - self.tail.map(|node| unsafe { - // Need an unbound lifetime to get 'a - let node = &*node.as_ptr(); - self.len -= 1; - self.tail = node.prev; - &node.element - }) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Iter<'_, T> {} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Iter<'_, T> {} - -#[stable(feature = "default_iters", since = "1.70.0")] -impl Default for Iter<'_, T> { - /// Creates an empty `linked_list::Iter`. - /// - /// ``` - /// # use std::collections::linked_list; - /// let iter: linked_list::Iter<'_, u8> = Default::default(); - /// assert_eq!(iter.len(), 0); - /// ``` - fn default() -> Self { - Iter { head: None, tail: None, len: 0, marker: Default::default() } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> Iterator for IterMut<'a, T> { - type Item = &'a mut T; - - #[inline] - fn next(&mut self) -> Option<&'a mut T> { - if self.len == 0 { - None - } else { - self.head.map(|node| unsafe { - // Need an unbound lifetime to get 'a - let node = &mut *node.as_ptr(); - self.len -= 1; - self.head = node.next; - &mut node.element - }) - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - (self.len, Some(self.len)) - } - - #[inline] - fn last(mut self) -> Option<&'a mut T> { - self.next_back() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> DoubleEndedIterator for IterMut<'a, T> { - #[inline] - fn next_back(&mut self) -> Option<&'a mut T> { - if self.len == 0 { - None - } else { - self.tail.map(|node| unsafe { - // Need an unbound lifetime to get 'a - let node = &mut *node.as_ptr(); - self.len -= 1; - self.tail = node.prev; - &mut node.element - }) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for IterMut<'_, T> {} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for IterMut<'_, T> {} - -#[stable(feature = "default_iters", since = "1.70.0")] -impl Default for IterMut<'_, T> { - fn default() -> Self { - IterMut { head: None, tail: None, len: 0, marker: Default::default() } - } -} - -/// A cursor over a `LinkedList`. -/// -/// A `Cursor` is like an iterator, except that it can freely seek back-and-forth. -/// -/// Cursors always rest between two elements in the list, and index in a logically circular way. -/// To accommodate this, there is a "ghost" non-element that yields `None` between the head and -/// tail of the list. -/// -/// When created, cursors start at the front of the list, or the "ghost" non-element if the list is empty. -#[unstable(feature = "linked_list_cursors", issue = "58533")] -pub struct Cursor< - 'a, - T: 'a, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, -> { - index: usize, - current: Option>>, - list: &'a LinkedList, -} - -#[unstable(feature = "linked_list_cursors", issue = "58533")] -impl Clone for Cursor<'_, T, A> { - fn clone(&self) -> Self { - let Cursor { index, current, list } = *self; - Cursor { index, current, list } - } -} - -#[unstable(feature = "linked_list_cursors", issue = "58533")] -impl fmt::Debug for Cursor<'_, T, A> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("Cursor").field(&self.list).field(&self.index()).finish() - } -} - -/// A cursor over a `LinkedList` with editing operations. -/// -/// A `Cursor` is like an iterator, except that it can freely seek back-and-forth, and can -/// safely mutate the list during iteration. This is because the lifetime of its yielded -/// references is tied to its own lifetime, instead of just the underlying list. This means -/// cursors cannot yield multiple elements at once. -/// -/// Cursors always rest between two elements in the list, and index in a logically circular way. -/// To accommodate this, there is a "ghost" non-element that yields `None` between the head and -/// tail of the list. -#[unstable(feature = "linked_list_cursors", issue = "58533")] -pub struct CursorMut< - 'a, - T: 'a, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, -> { - index: usize, - current: Option>>, - list: &'a mut LinkedList, -} - -#[unstable(feature = "linked_list_cursors", issue = "58533")] -impl fmt::Debug for CursorMut<'_, T, A> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("CursorMut").field(&self.list).field(&self.index()).finish() - } -} - -impl<'a, T, A: Allocator> Cursor<'a, T, A> { - /// Returns the cursor position index within the `LinkedList`. - /// - /// This returns `None` if the cursor is currently pointing to the - /// "ghost" non-element. - #[must_use] - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn index(&self) -> Option { - let _ = self.current?; - Some(self.index) - } - - /// Moves the cursor to the next element of the `LinkedList`. - /// - /// If the cursor is pointing to the "ghost" non-element then this will move it to - /// the first element of the `LinkedList`. If it is pointing to the last - /// element of the `LinkedList` then this will move it to the "ghost" non-element. - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn move_next(&mut self) { - match self.current.take() { - // We had no current element; the cursor was sitting at the start position - // Next element should be the head of the list - None => { - self.current = self.list.head; - self.index = 0; - } - // We had a previous element, so let's go to its next - Some(current) => unsafe { - self.current = current.as_ref().next; - self.index += 1; - }, - } - } - - /// Moves the cursor to the previous element of the `LinkedList`. - /// - /// If the cursor is pointing to the "ghost" non-element then this will move it to - /// the last element of the `LinkedList`. If it is pointing to the first - /// element of the `LinkedList` then this will move it to the "ghost" non-element. - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn move_prev(&mut self) { - match self.current.take() { - // No current. We're at the start of the list. Yield None and jump to the end. - None => { - self.current = self.list.tail; - self.index = self.list.len().checked_sub(1).unwrap_or(0); - } - // Have a prev. Yield it and go to the previous element. - Some(current) => unsafe { - self.current = current.as_ref().prev; - self.index = self.index.checked_sub(1).unwrap_or_else(|| self.list.len()); - }, - } - } - - /// Returns a reference to the element that the cursor is currently - /// pointing to. - /// - /// This returns `None` if the cursor is currently pointing to the - /// "ghost" non-element. - #[must_use] - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn current(&self) -> Option<&'a T> { - unsafe { self.current.map(|current| &(*current.as_ptr()).element) } - } - - /// Returns a reference to the next element. - /// - /// If the cursor is pointing to the "ghost" non-element then this returns - /// the first element of the `LinkedList`. If it is pointing to the last - /// element of the `LinkedList` then this returns `None`. - #[must_use] - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn peek_next(&self) -> Option<&'a T> { - unsafe { - let next = match self.current { - None => self.list.head, - Some(current) => current.as_ref().next, - }; - next.map(|next| &(*next.as_ptr()).element) - } - } - - /// Returns a reference to the previous element. - /// - /// If the cursor is pointing to the "ghost" non-element then this returns - /// the last element of the `LinkedList`. If it is pointing to the first - /// element of the `LinkedList` then this returns `None`. - #[must_use] - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn peek_prev(&self) -> Option<&'a T> { - unsafe { - let prev = match self.current { - None => self.list.tail, - Some(current) => current.as_ref().prev, - }; - prev.map(|prev| &(*prev.as_ptr()).element) - } - } - - /// Provides a reference to the front element of the cursor's parent list, - /// or None if the list is empty. - #[must_use] - #[unstable(feature = "linked_list_cursors", issue = "58533")] - #[rustc_confusables("first")] - pub fn front(&self) -> Option<&'a T> { - self.list.front() - } - - /// Provides a reference to the back element of the cursor's parent list, - /// or None if the list is empty. - #[must_use] - #[unstable(feature = "linked_list_cursors", issue = "58533")] - #[rustc_confusables("last")] - pub fn back(&self) -> Option<&'a T> { - self.list.back() - } -} - -impl<'a, T, A: Allocator> CursorMut<'a, T, A> { - /// Returns the cursor position index within the `LinkedList`. - /// - /// This returns `None` if the cursor is currently pointing to the - /// "ghost" non-element. - #[must_use] - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn index(&self) -> Option { - let _ = self.current?; - Some(self.index) - } - - /// Moves the cursor to the next element of the `LinkedList`. - /// - /// If the cursor is pointing to the "ghost" non-element then this will move it to - /// the first element of the `LinkedList`. If it is pointing to the last - /// element of the `LinkedList` then this will move it to the "ghost" non-element. - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn move_next(&mut self) { - match self.current.take() { - // We had no current element; the cursor was sitting at the start position - // Next element should be the head of the list - None => { - self.current = self.list.head; - self.index = 0; - } - // We had a previous element, so let's go to its next - Some(current) => unsafe { - self.current = current.as_ref().next; - self.index += 1; - }, - } - } - - /// Moves the cursor to the previous element of the `LinkedList`. - /// - /// If the cursor is pointing to the "ghost" non-element then this will move it to - /// the last element of the `LinkedList`. If it is pointing to the first - /// element of the `LinkedList` then this will move it to the "ghost" non-element. - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn move_prev(&mut self) { - match self.current.take() { - // No current. We're at the start of the list. Yield None and jump to the end. - None => { - self.current = self.list.tail; - self.index = self.list.len().checked_sub(1).unwrap_or(0); - } - // Have a prev. Yield it and go to the previous element. - Some(current) => unsafe { - self.current = current.as_ref().prev; - self.index = self.index.checked_sub(1).unwrap_or_else(|| self.list.len()); - }, - } - } - - /// Returns a reference to the element that the cursor is currently - /// pointing to. - /// - /// This returns `None` if the cursor is currently pointing to the - /// "ghost" non-element. - #[must_use] - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn current(&mut self) -> Option<&mut T> { - unsafe { self.current.map(|current| &mut (*current.as_ptr()).element) } - } - - /// Returns a reference to the next element. - /// - /// If the cursor is pointing to the "ghost" non-element then this returns - /// the first element of the `LinkedList`. If it is pointing to the last - /// element of the `LinkedList` then this returns `None`. - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn peek_next(&mut self) -> Option<&mut T> { - unsafe { - let next = match self.current { - None => self.list.head, - Some(current) => current.as_ref().next, - }; - next.map(|next| &mut (*next.as_ptr()).element) - } - } - - /// Returns a reference to the previous element. - /// - /// If the cursor is pointing to the "ghost" non-element then this returns - /// the last element of the `LinkedList`. If it is pointing to the first - /// element of the `LinkedList` then this returns `None`. - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn peek_prev(&mut self) -> Option<&mut T> { - unsafe { - let prev = match self.current { - None => self.list.tail, - Some(current) => current.as_ref().prev, - }; - prev.map(|prev| &mut (*prev.as_ptr()).element) - } - } - - /// Returns a read-only cursor pointing to the current element. - /// - /// The lifetime of the returned `Cursor` is bound to that of the - /// `CursorMut`, which means it cannot outlive the `CursorMut` and that the - /// `CursorMut` is frozen for the lifetime of the `Cursor`. - #[must_use] - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn as_cursor(&self) -> Cursor<'_, T, A> { - Cursor { list: self.list, current: self.current, index: self.index } - } -} - -// Now the list editing operations - -impl<'a, T> CursorMut<'a, T> { - /// Inserts the elements from the given `LinkedList` after the current one. - /// - /// If the cursor is pointing at the "ghost" non-element then the new elements are - /// inserted at the start of the `LinkedList`. - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn splice_after(&mut self, list: LinkedList) { - unsafe { - let (splice_head, splice_tail, splice_len) = match list.detach_all_nodes() { - Some(parts) => parts, - _ => return, - }; - let node_next = match self.current { - None => self.list.head, - Some(node) => node.as_ref().next, - }; - self.list.splice_nodes(self.current, node_next, splice_head, splice_tail, splice_len); - if self.current.is_none() { - // The "ghost" non-element's index has changed. - self.index = self.list.len; - } - } - } - - /// Inserts the elements from the given `LinkedList` before the current one. - /// - /// If the cursor is pointing at the "ghost" non-element then the new elements are - /// inserted at the end of the `LinkedList`. - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn splice_before(&mut self, list: LinkedList) { - unsafe { - let (splice_head, splice_tail, splice_len) = match list.detach_all_nodes() { - Some(parts) => parts, - _ => return, - }; - let node_prev = match self.current { - None => self.list.tail, - Some(node) => node.as_ref().prev, - }; - self.list.splice_nodes(node_prev, self.current, splice_head, splice_tail, splice_len); - self.index += splice_len; - } - } -} - -impl<'a, T, A: Allocator> CursorMut<'a, T, A> { - /// Inserts a new element into the `LinkedList` after the current one. - /// - /// If the cursor is pointing at the "ghost" non-element then the new element is - /// inserted at the front of the `LinkedList`. - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn insert_after(&mut self, item: T) { - unsafe { - let spliced_node = Box::leak(Box::new_in(Node::new(item), &self.list.alloc)).into(); - let node_next = match self.current { - None => self.list.head, - Some(node) => node.as_ref().next, - }; - self.list.splice_nodes(self.current, node_next, spliced_node, spliced_node, 1); - if self.current.is_none() { - // The "ghost" non-element's index has changed. - self.index = self.list.len; - } - } - } - - /// Inserts a new element into the `LinkedList` before the current one. - /// - /// If the cursor is pointing at the "ghost" non-element then the new element is - /// inserted at the end of the `LinkedList`. - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn insert_before(&mut self, item: T) { - unsafe { - let spliced_node = Box::leak(Box::new_in(Node::new(item), &self.list.alloc)).into(); - let node_prev = match self.current { - None => self.list.tail, - Some(node) => node.as_ref().prev, - }; - self.list.splice_nodes(node_prev, self.current, spliced_node, spliced_node, 1); - self.index += 1; - } - } - - /// Removes the current element from the `LinkedList`. - /// - /// The element that was removed is returned, and the cursor is - /// moved to point to the next element in the `LinkedList`. - /// - /// If the cursor is currently pointing to the "ghost" non-element then no element - /// is removed and `None` is returned. - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn remove_current(&mut self) -> Option { - let unlinked_node = self.current?; - unsafe { - self.current = unlinked_node.as_ref().next; - self.list.unlink_node(unlinked_node); - let unlinked_node = Box::from_raw(unlinked_node.as_ptr()); - Some(unlinked_node.element) - } - } - - /// Removes the current element from the `LinkedList` without deallocating the list node. - /// - /// The node that was removed is returned as a new `LinkedList` containing only this node. - /// The cursor is moved to point to the next element in the current `LinkedList`. - /// - /// If the cursor is currently pointing to the "ghost" non-element then no element - /// is removed and `None` is returned. - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn remove_current_as_list(&mut self) -> Option> - where - A: Clone, - { - let mut unlinked_node = self.current?; - unsafe { - self.current = unlinked_node.as_ref().next; - self.list.unlink_node(unlinked_node); - - unlinked_node.as_mut().prev = None; - unlinked_node.as_mut().next = None; - Some(LinkedList { - head: Some(unlinked_node), - tail: Some(unlinked_node), - len: 1, - alloc: self.list.alloc.clone(), - marker: PhantomData, - }) - } - } - - /// Splits the list into two after the current element. This will return a - /// new list consisting of everything after the cursor, with the original - /// list retaining everything before. - /// - /// If the cursor is pointing at the "ghost" non-element then the entire contents - /// of the `LinkedList` are moved. - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn split_after(&mut self) -> LinkedList - where - A: Clone, - { - let split_off_idx = if self.index == self.list.len { 0 } else { self.index + 1 }; - if self.index == self.list.len { - // The "ghost" non-element's index has changed to 0. - self.index = 0; - } - unsafe { self.list.split_off_after_node(self.current, split_off_idx) } - } - - /// Splits the list into two before the current element. This will return a - /// new list consisting of everything before the cursor, with the original - /// list retaining everything after. - /// - /// If the cursor is pointing at the "ghost" non-element then the entire contents - /// of the `LinkedList` are moved. - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn split_before(&mut self) -> LinkedList - where - A: Clone, - { - let split_off_idx = self.index; - self.index = 0; - unsafe { self.list.split_off_before_node(self.current, split_off_idx) } - } - - /// Appends an element to the front of the cursor's parent list. The node - /// that the cursor points to is unchanged, even if it is the "ghost" node. - /// - /// This operation should compute in *O*(1) time. - // `push_front` continues to point to "ghost" when it adds a node to mimic - // the behavior of `insert_before` on an empty list. - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn push_front(&mut self, elt: T) { - // Safety: We know that `push_front` does not change the position in - // memory of other nodes. This ensures that `self.current` remains - // valid. - self.list.push_front(elt); - self.index += 1; - } - - /// Appends an element to the back of the cursor's parent list. The node - /// that the cursor points to is unchanged, even if it is the "ghost" node. - /// - /// This operation should compute in *O*(1) time. - #[unstable(feature = "linked_list_cursors", issue = "58533")] - #[rustc_confusables("push", "append")] - pub fn push_back(&mut self, elt: T) { - // Safety: We know that `push_back` does not change the position in - // memory of other nodes. This ensures that `self.current` remains - // valid. - self.list.push_back(elt); - if self.current().is_none() { - // The index of "ghost" is the length of the list, so we just need - // to increment self.index to reflect the new length of the list. - self.index += 1; - } - } - - /// Removes the first element from the cursor's parent list and returns it, - /// or None if the list is empty. The element the cursor points to remains - /// unchanged, unless it was pointing to the front element. In that case, it - /// points to the new front element. - /// - /// This operation should compute in *O*(1) time. - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn pop_front(&mut self) -> Option { - // We can't check if current is empty, we must check the list directly. - // It is possible for `self.current == None` and the list to be - // non-empty. - if self.list.is_empty() { - None - } else { - // We can't point to the node that we pop. Copying the behavior of - // `remove_current`, we move on to the next node in the sequence. - // If the list is of length 1 then we end pointing to the "ghost" - // node at index 0, which is expected. - if self.list.head == self.current { - self.move_next(); - } else { - self.index -= 1; - } - self.list.pop_front() - } - } - - /// Removes the last element from the cursor's parent list and returns it, - /// or None if the list is empty. The element the cursor points to remains - /// unchanged, unless it was pointing to the back element. In that case, it - /// points to the "ghost" element. - /// - /// This operation should compute in *O*(1) time. - #[unstable(feature = "linked_list_cursors", issue = "58533")] - #[rustc_confusables("pop")] - pub fn pop_back(&mut self) -> Option { - if self.list.is_empty() { - None - } else { - if self.list.tail == self.current { - // The index now reflects the length of the list. It was the - // length of the list minus 1, but now the list is 1 smaller. No - // change is needed for `index`. - self.current = None; - } else if self.current.is_none() { - self.index = self.list.len - 1; - } - self.list.pop_back() - } - } - - /// Provides a reference to the front element of the cursor's parent list, - /// or None if the list is empty. - #[must_use] - #[unstable(feature = "linked_list_cursors", issue = "58533")] - #[rustc_confusables("first")] - pub fn front(&self) -> Option<&T> { - self.list.front() - } - - /// Provides a mutable reference to the front element of the cursor's - /// parent list, or None if the list is empty. - #[must_use] - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn front_mut(&mut self) -> Option<&mut T> { - self.list.front_mut() - } - - /// Provides a reference to the back element of the cursor's parent list, - /// or None if the list is empty. - #[must_use] - #[unstable(feature = "linked_list_cursors", issue = "58533")] - #[rustc_confusables("last")] - pub fn back(&self) -> Option<&T> { - self.list.back() - } - - /// Provides a mutable reference to back element of the cursor's parent - /// list, or `None` if the list is empty. - /// - /// # Examples - /// Building and mutating a list with a cursor, then getting the back element: - /// ``` - /// #![feature(linked_list_cursors)] - /// use std::collections::LinkedList; - /// let mut dl = LinkedList::new(); - /// dl.push_front(3); - /// dl.push_front(2); - /// dl.push_front(1); - /// let mut cursor = dl.cursor_front_mut(); - /// *cursor.current().unwrap() = 99; - /// *cursor.back_mut().unwrap() = 0; - /// let mut contents = dl.into_iter(); - /// assert_eq!(contents.next(), Some(99)); - /// assert_eq!(contents.next(), Some(2)); - /// assert_eq!(contents.next(), Some(0)); - /// assert_eq!(contents.next(), None); - /// ``` - #[must_use] - #[unstable(feature = "linked_list_cursors", issue = "58533")] - pub fn back_mut(&mut self) -> Option<&mut T> { - self.list.back_mut() - } -} - -/// An iterator produced by calling `extract_if` on LinkedList. -#[unstable(feature = "extract_if", reason = "recently added", issue = "43244")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct ExtractIf< - 'a, - T: 'a, - F: 'a, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, -> where - F: FnMut(&mut T) -> bool, -{ - list: &'a mut LinkedList, - it: Option>>, - pred: F, - idx: usize, - old_len: usize, -} - -#[unstable(feature = "extract_if", reason = "recently added", issue = "43244")] -impl Iterator for ExtractIf<'_, T, F, A> -where - F: FnMut(&mut T) -> bool, -{ - type Item = T; - - fn next(&mut self) -> Option { - while let Some(mut node) = self.it { - unsafe { - self.it = node.as_ref().next; - self.idx += 1; - - if (self.pred)(&mut node.as_mut().element) { - // `unlink_node` is okay with aliasing `element` references. - self.list.unlink_node(node); - return Some(Box::from_raw(node.as_ptr()).element); - } - } - } - - None - } - - fn size_hint(&self) -> (usize, Option) { - (0, Some(self.old_len - self.idx)) - } -} - -#[unstable(feature = "extract_if", reason = "recently added", issue = "43244")] -impl fmt::Debug for ExtractIf<'_, T, F> -where - F: FnMut(&mut T) -> bool, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("ExtractIf").field(&self.list).finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for IntoIter { - type Item = T; - - #[inline] - fn next(&mut self) -> Option { - self.list.pop_front() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - (self.list.len, Some(self.list.len)) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DoubleEndedIterator for IntoIter { - #[inline] - fn next_back(&mut self) -> Option { - self.list.pop_back() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for IntoIter {} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for IntoIter {} - -#[stable(feature = "default_iters", since = "1.70.0")] -impl Default for IntoIter { - /// Creates an empty `linked_list::IntoIter`. - /// - /// ``` - /// # use std::collections::linked_list; - /// let iter: linked_list::IntoIter = Default::default(); - /// assert_eq!(iter.len(), 0); - /// ``` - fn default() -> Self { - LinkedList::new().into_iter() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl FromIterator for LinkedList { - fn from_iter>(iter: I) -> Self { - let mut list = Self::new(); - list.extend(iter); - list - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl IntoIterator for LinkedList { - type Item = T; - type IntoIter = IntoIter; - - /// Consumes the list into an iterator yielding elements by value. - #[inline] - fn into_iter(self) -> IntoIter { - IntoIter { list: self } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T, A: Allocator> IntoIterator for &'a LinkedList { - type Item = &'a T; - type IntoIter = Iter<'a, T>; - - fn into_iter(self) -> Iter<'a, T> { - self.iter() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T, A: Allocator> IntoIterator for &'a mut LinkedList { - type Item = &'a mut T; - type IntoIter = IterMut<'a, T>; - - fn into_iter(self) -> IterMut<'a, T> { - self.iter_mut() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Extend for LinkedList { - fn extend>(&mut self, iter: I) { - >::spec_extend(self, iter); - } - - #[inline] - fn extend_one(&mut self, elem: T) { - self.push_back(elem); - } -} - -impl SpecExtend for LinkedList { - default fn spec_extend(&mut self, iter: I) { - iter.into_iter().for_each(move |elt| self.push_back(elt)); - } -} - -impl SpecExtend> for LinkedList { - fn spec_extend(&mut self, ref mut other: LinkedList) { - self.append(other); - } -} - -#[stable(feature = "extend_ref", since = "1.2.0")] -impl<'a, T: 'a + Copy, A: Allocator> Extend<&'a T> for LinkedList { - fn extend>(&mut self, iter: I) { - self.extend(iter.into_iter().cloned()); - } - - #[inline] - fn extend_one(&mut self, &elem: &'a T) { - self.push_back(elem); - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for LinkedList { - fn eq(&self, other: &Self) -> bool { - self.len() == other.len() && self.iter().eq(other) - } - - fn ne(&self, other: &Self) -> bool { - self.len() != other.len() || self.iter().ne(other) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Eq for LinkedList {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialOrd for LinkedList { - fn partial_cmp(&self, other: &Self) -> Option { - self.iter().partial_cmp(other) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for LinkedList { - #[inline] - fn cmp(&self, other: &Self) -> Ordering { - self.iter().cmp(other) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for LinkedList { - fn clone(&self) -> Self { - let mut list = Self::new_in(self.alloc.clone()); - list.extend(self.iter().cloned()); - list - } - - /// Overwrites the contents of `self` with a clone of the contents of `source`. - /// - /// This method is preferred over simply assigning `source.clone()` to `self`, - /// as it avoids reallocation of the nodes of the linked list. Additionally, - /// if the element type `T` overrides `clone_from()`, this will reuse the - /// resources of `self`'s elements as well. - fn clone_from(&mut self, source: &Self) { - let mut source_iter = source.iter(); - if self.len() > source.len() { - self.split_off(source.len()); - } - for (elem, source_elem) in self.iter_mut().zip(&mut source_iter) { - elem.clone_from(source_elem); - } - if !source_iter.is_empty() { - self.extend(source_iter.cloned()); - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for LinkedList { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self).finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Hash for LinkedList { - fn hash(&self, state: &mut H) { - state.write_length_prefix(self.len()); - for elt in self { - elt.hash(state); - } - } -} - -#[stable(feature = "std_collections_from_array", since = "1.56.0")] -impl From<[T; N]> for LinkedList { - /// Converts a `[T; N]` into a `LinkedList`. - /// - /// ``` - /// use std::collections::LinkedList; - /// - /// let list1 = LinkedList::from([1, 2, 3, 4]); - /// let list2: LinkedList<_> = [1, 2, 3, 4].into(); - /// assert_eq!(list1, list2); - /// ``` - fn from(arr: [T; N]) -> Self { - Self::from_iter(arr) - } -} - -// Ensure that `LinkedList` and its read-only iterators are covariant in their type parameters. -#[allow(dead_code)] -fn assert_covariance() { - fn a<'a>(x: LinkedList<&'static str>) -> LinkedList<&'a str> { - x - } - fn b<'i, 'a>(x: Iter<'i, &'static str>) -> Iter<'i, &'a str> { - x - } - fn c<'a>(x: IntoIter<&'static str>) -> IntoIter<&'a str> { - x - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Send for LinkedList {} - -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Sync for LinkedList {} - -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Send for Iter<'_, T> {} - -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Sync for Iter<'_, T> {} - -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Send for IterMut<'_, T> {} - -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Sync for IterMut<'_, T> {} - -#[unstable(feature = "linked_list_cursors", issue = "58533")] -unsafe impl Send for Cursor<'_, T, A> {} - -#[unstable(feature = "linked_list_cursors", issue = "58533")] -unsafe impl Sync for Cursor<'_, T, A> {} - -#[unstable(feature = "linked_list_cursors", issue = "58533")] -unsafe impl Send for CursorMut<'_, T, A> {} - -#[unstable(feature = "linked_list_cursors", issue = "58533")] -unsafe impl Sync for CursorMut<'_, T, A> {} diff --git a/library/alloc/src/collections/linked_list/tests.rs b/library/alloc/src/collections/linked_list/tests.rs deleted file mode 100644 index 8dcd59d12d927..0000000000000 --- a/library/alloc/src/collections/linked_list/tests.rs +++ /dev/null @@ -1,1166 +0,0 @@ -use super::*; -use crate::testing::crash_test::{CrashTestDummy, Panic}; -use crate::vec::Vec; - -use std::panic::{catch_unwind, AssertUnwindSafe}; -use std::thread; - -use rand::RngCore; - -#[test] -fn test_basic() { - let mut m = LinkedList::>::new(); - assert_eq!(m.pop_front(), None); - assert_eq!(m.pop_back(), None); - assert_eq!(m.pop_front(), None); - m.push_front(Box::new(1)); - assert_eq!(m.pop_front(), Some(Box::new(1))); - m.push_back(Box::new(2)); - m.push_back(Box::new(3)); - assert_eq!(m.len(), 2); - assert_eq!(m.pop_front(), Some(Box::new(2))); - assert_eq!(m.pop_front(), Some(Box::new(3))); - assert_eq!(m.len(), 0); - assert_eq!(m.pop_front(), None); - m.push_back(Box::new(1)); - m.push_back(Box::new(3)); - m.push_back(Box::new(5)); - m.push_back(Box::new(7)); - assert_eq!(m.pop_front(), Some(Box::new(1))); - - let mut n = LinkedList::new(); - n.push_front(2); - n.push_front(3); - { - assert_eq!(n.front().unwrap(), &3); - let x = n.front_mut().unwrap(); - assert_eq!(*x, 3); - *x = 0; - } - { - assert_eq!(n.back().unwrap(), &2); - let y = n.back_mut().unwrap(); - assert_eq!(*y, 2); - *y = 1; - } - assert_eq!(n.pop_front(), Some(0)); - assert_eq!(n.pop_front(), Some(1)); -} - -fn generate_test() -> LinkedList { - list_from(&[0, 1, 2, 3, 4, 5, 6]) -} - -fn list_from(v: &[T]) -> LinkedList { - v.iter().cloned().collect() -} - -pub fn check_links(list: &LinkedList) { - unsafe { - let mut len = 0; - let mut last_ptr: Option<&Node> = None; - let mut node_ptr: &Node; - match list.head { - None => { - // tail node should also be None. - assert!(list.tail.is_none()); - assert_eq!(0, list.len); - return; - } - Some(node) => node_ptr = &*node.as_ptr(), - } - loop { - match (last_ptr, node_ptr.prev) { - (None, None) => {} - (None, _) => panic!("prev link for head"), - (Some(p), Some(pptr)) => { - assert_eq!(p as *const Node, pptr.as_ptr() as *const Node); - } - _ => panic!("prev link is none, not good"), - } - match node_ptr.next { - Some(next) => { - last_ptr = Some(node_ptr); - node_ptr = &*next.as_ptr(); - len += 1; - } - None => { - len += 1; - break; - } - } - } - - // verify that the tail node points to the last node. - let tail = list.tail.as_ref().expect("some tail node").as_ref(); - assert_eq!(tail as *const Node, node_ptr as *const Node); - // check that len matches interior links. - assert_eq!(len, list.len); - } -} - -#[test] -fn test_append() { - // Empty to empty - { - let mut m = LinkedList::::new(); - let mut n = LinkedList::new(); - m.append(&mut n); - check_links(&m); - assert_eq!(m.len(), 0); - assert_eq!(n.len(), 0); - } - // Non-empty to empty - { - let mut m = LinkedList::new(); - let mut n = LinkedList::new(); - n.push_back(2); - m.append(&mut n); - check_links(&m); - assert_eq!(m.len(), 1); - assert_eq!(m.pop_back(), Some(2)); - assert_eq!(n.len(), 0); - check_links(&m); - } - // Empty to non-empty - { - let mut m = LinkedList::new(); - let mut n = LinkedList::new(); - m.push_back(2); - m.append(&mut n); - check_links(&m); - assert_eq!(m.len(), 1); - assert_eq!(m.pop_back(), Some(2)); - check_links(&m); - } - - // Non-empty to non-empty - let v = vec![1, 2, 3, 4, 5]; - let u = vec![9, 8, 1, 2, 3, 4, 5]; - let mut m = list_from(&v); - let mut n = list_from(&u); - m.append(&mut n); - check_links(&m); - let mut sum = v; - sum.extend_from_slice(&u); - assert_eq!(sum.len(), m.len()); - for elt in sum { - assert_eq!(m.pop_front(), Some(elt)) - } - assert_eq!(n.len(), 0); - // Let's make sure it's working properly, since we - // did some direct changes to private members. - n.push_back(3); - assert_eq!(n.len(), 1); - assert_eq!(n.pop_front(), Some(3)); - check_links(&n); -} - -#[test] -fn test_iterator() { - let m = generate_test(); - for (i, elt) in m.iter().enumerate() { - assert_eq!(i as i32, *elt); - } - let mut n = LinkedList::new(); - assert_eq!(n.iter().next(), None); - n.push_front(4); - let mut it = n.iter(); - assert_eq!(it.size_hint(), (1, Some(1))); - assert_eq!(it.next().unwrap(), &4); - assert_eq!(it.size_hint(), (0, Some(0))); - assert_eq!(it.next(), None); -} - -#[test] -fn test_iterator_clone() { - let mut n = LinkedList::new(); - n.push_back(2); - n.push_back(3); - n.push_back(4); - let mut it = n.iter(); - it.next(); - let mut jt = it.clone(); - assert_eq!(it.next(), jt.next()); - assert_eq!(it.next_back(), jt.next_back()); - assert_eq!(it.next(), jt.next()); -} - -#[test] -fn test_iterator_double_end() { - let mut n = LinkedList::new(); - assert_eq!(n.iter().next(), None); - n.push_front(4); - n.push_front(5); - n.push_front(6); - let mut it = n.iter(); - assert_eq!(it.size_hint(), (3, Some(3))); - assert_eq!(it.next().unwrap(), &6); - assert_eq!(it.size_hint(), (2, Some(2))); - assert_eq!(it.next_back().unwrap(), &4); - assert_eq!(it.size_hint(), (1, Some(1))); - assert_eq!(it.next_back().unwrap(), &5); - assert_eq!(it.next_back(), None); - assert_eq!(it.next(), None); -} - -#[test] -fn test_rev_iter() { - let m = generate_test(); - for (i, elt) in m.iter().rev().enumerate() { - assert_eq!((6 - i) as i32, *elt); - } - let mut n = LinkedList::new(); - assert_eq!(n.iter().rev().next(), None); - n.push_front(4); - let mut it = n.iter().rev(); - assert_eq!(it.size_hint(), (1, Some(1))); - assert_eq!(it.next().unwrap(), &4); - assert_eq!(it.size_hint(), (0, Some(0))); - assert_eq!(it.next(), None); -} - -#[test] -fn test_mut_iter() { - let mut m = generate_test(); - let mut len = m.len(); - for (i, elt) in m.iter_mut().enumerate() { - assert_eq!(i as i32, *elt); - len -= 1; - } - assert_eq!(len, 0); - let mut n = LinkedList::new(); - assert!(n.iter_mut().next().is_none()); - n.push_front(4); - n.push_back(5); - let mut it = n.iter_mut(); - assert_eq!(it.size_hint(), (2, Some(2))); - assert!(it.next().is_some()); - assert!(it.next().is_some()); - assert_eq!(it.size_hint(), (0, Some(0))); - assert!(it.next().is_none()); -} - -#[test] -fn test_iterator_mut_double_end() { - let mut n = LinkedList::new(); - assert!(n.iter_mut().next_back().is_none()); - n.push_front(4); - n.push_front(5); - n.push_front(6); - let mut it = n.iter_mut(); - assert_eq!(it.size_hint(), (3, Some(3))); - assert_eq!(*it.next().unwrap(), 6); - assert_eq!(it.size_hint(), (2, Some(2))); - assert_eq!(*it.next_back().unwrap(), 4); - assert_eq!(it.size_hint(), (1, Some(1))); - assert_eq!(*it.next_back().unwrap(), 5); - assert!(it.next_back().is_none()); - assert!(it.next().is_none()); -} - -#[test] -fn test_mut_rev_iter() { - let mut m = generate_test(); - for (i, elt) in m.iter_mut().rev().enumerate() { - assert_eq!((6 - i) as i32, *elt); - } - let mut n = LinkedList::new(); - assert!(n.iter_mut().rev().next().is_none()); - n.push_front(4); - let mut it = n.iter_mut().rev(); - assert!(it.next().is_some()); - assert!(it.next().is_none()); -} - -#[test] -fn test_clone_from() { - // Short cloned from long - { - let v = vec![1, 2, 3, 4, 5]; - let u = vec![8, 7, 6, 2, 3, 4, 5]; - let mut m = list_from(&v); - let n = list_from(&u); - m.clone_from(&n); - check_links(&m); - assert_eq!(m, n); - for elt in u { - assert_eq!(m.pop_front(), Some(elt)) - } - } - // Long cloned from short - { - let v = vec![1, 2, 3, 4, 5]; - let u = vec![6, 7, 8]; - let mut m = list_from(&v); - let n = list_from(&u); - m.clone_from(&n); - check_links(&m); - assert_eq!(m, n); - for elt in u { - assert_eq!(m.pop_front(), Some(elt)) - } - } - // Two equal length lists - { - let v = vec![1, 2, 3, 4, 5]; - let u = vec![9, 8, 1, 2, 3]; - let mut m = list_from(&v); - let n = list_from(&u); - m.clone_from(&n); - check_links(&m); - assert_eq!(m, n); - for elt in u { - assert_eq!(m.pop_front(), Some(elt)) - } - } -} - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn test_send() { - let n = list_from(&[1, 2, 3]); - thread::spawn(move || { - check_links(&n); - let a: &[_] = &[&1, &2, &3]; - assert_eq!(a, &*n.iter().collect::>()); - }) - .join() - .ok() - .unwrap(); -} - -#[test] -fn test_eq() { - let mut n = list_from(&[]); - let mut m = list_from(&[]); - assert!(n == m); - n.push_front(1); - assert!(n != m); - m.push_back(1); - assert!(n == m); - - let n = list_from(&[2, 3, 4]); - let m = list_from(&[1, 2, 3]); - assert!(n != m); -} - -#[test] -fn test_ord() { - let n = list_from(&[]); - let m = list_from(&[1, 2, 3]); - assert!(n < m); - assert!(m > n); - assert!(n <= n); - assert!(n >= n); -} - -#[test] -fn test_ord_nan() { - let nan = 0.0f64 / 0.0; - let n = list_from(&[nan]); - let m = list_from(&[nan]); - assert!(!(n < m)); - assert!(!(n > m)); - assert!(!(n <= m)); - assert!(!(n >= m)); - - let n = list_from(&[nan]); - let one = list_from(&[1.0f64]); - assert!(!(n < one)); - assert!(!(n > one)); - assert!(!(n <= one)); - assert!(!(n >= one)); - - let u = list_from(&[1.0f64, 2.0, nan]); - let v = list_from(&[1.0f64, 2.0, 3.0]); - assert!(!(u < v)); - assert!(!(u > v)); - assert!(!(u <= v)); - assert!(!(u >= v)); - - let s = list_from(&[1.0f64, 2.0, 4.0, 2.0]); - let t = list_from(&[1.0f64, 2.0, 3.0, 2.0]); - assert!(!(s < t)); - assert!(s > one); - assert!(!(s <= one)); - assert!(s >= one); -} - -#[test] -fn test_26021() { - // There was a bug in split_off that failed to null out the RHS's head's prev ptr. - // This caused the RHS's dtor to walk up into the LHS at drop and delete all of - // its nodes. - // - // https://github.com/rust-lang/rust/issues/26021 - let mut v1 = LinkedList::new(); - v1.push_front(1); - v1.push_front(1); - v1.push_front(1); - v1.push_front(1); - let _ = v1.split_off(3); // Dropping this now should not cause laundry consumption - assert_eq!(v1.len(), 3); - - assert_eq!(v1.iter().len(), 3); - assert_eq!(v1.iter().collect::>().len(), 3); -} - -#[test] -fn test_split_off() { - let mut v1 = LinkedList::new(); - v1.push_front(1); - v1.push_front(1); - v1.push_front(1); - v1.push_front(1); - - // test all splits - for ix in 0..1 + v1.len() { - let mut a = v1.clone(); - let b = a.split_off(ix); - check_links(&a); - check_links(&b); - a.extend(b); - assert_eq!(v1, a); - } -} - -#[test] -fn test_split_off_2() { - // singleton - { - let mut m = LinkedList::new(); - m.push_back(1); - - let p = m.split_off(0); - assert_eq!(m.len(), 0); - assert_eq!(p.len(), 1); - assert_eq!(p.back(), Some(&1)); - assert_eq!(p.front(), Some(&1)); - } - - // not singleton, forwards - { - let u = vec![1, 2, 3, 4, 5]; - let mut m = list_from(&u); - let mut n = m.split_off(2); - assert_eq!(m.len(), 2); - assert_eq!(n.len(), 3); - for elt in 1..3 { - assert_eq!(m.pop_front(), Some(elt)); - } - for elt in 3..6 { - assert_eq!(n.pop_front(), Some(elt)); - } - } - // not singleton, backwards - { - let u = vec![1, 2, 3, 4, 5]; - let mut m = list_from(&u); - let mut n = m.split_off(4); - assert_eq!(m.len(), 4); - assert_eq!(n.len(), 1); - for elt in 1..5 { - assert_eq!(m.pop_front(), Some(elt)); - } - for elt in 5..6 { - assert_eq!(n.pop_front(), Some(elt)); - } - } - - // no-op on the last index - { - let mut m = LinkedList::new(); - m.push_back(1); - - let p = m.split_off(1); - assert_eq!(m.len(), 1); - assert_eq!(p.len(), 0); - assert_eq!(m.back(), Some(&1)); - assert_eq!(m.front(), Some(&1)); - } -} - -fn fuzz_test(sz: i32, rng: &mut impl RngCore) { - let mut m: LinkedList<_> = LinkedList::new(); - let mut v = vec![]; - for i in 0..sz { - check_links(&m); - let r: u8 = rng.next_u32() as u8; - match r % 6 { - 0 => { - m.pop_back(); - v.pop(); - } - 1 => { - if !v.is_empty() { - m.pop_front(); - v.remove(0); - } - } - 2 | 4 => { - m.push_front(-i); - v.insert(0, -i); - } - 3 | 5 | _ => { - m.push_back(i); - v.push(i); - } - } - } - - check_links(&m); - - let mut i = 0; - for (a, &b) in m.into_iter().zip(&v) { - i += 1; - assert_eq!(a, b); - } - assert_eq!(i, v.len()); -} - -#[test] -fn test_fuzz() { - let mut rng = crate::test_helpers::test_rng(); - for _ in 0..25 { - fuzz_test(3, &mut rng); - fuzz_test(16, &mut rng); - #[cfg(not(miri))] // Miri is too slow - fuzz_test(189, &mut rng); - } -} - -#[test] -fn test_show() { - let list: LinkedList<_> = (0..10).collect(); - assert_eq!(format!("{list:?}"), "[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]"); - - let list: LinkedList<_> = ["just", "one", "test", "more"].into_iter().collect(); - assert_eq!(format!("{list:?}"), "[\"just\", \"one\", \"test\", \"more\"]"); -} - -#[test] -fn extract_if_test() { - let mut m: LinkedList = LinkedList::new(); - m.extend(&[1, 2, 3, 4, 5, 6]); - let deleted = m.extract_if(|v| *v < 4).collect::>(); - - check_links(&m); - - assert_eq!(deleted, &[1, 2, 3]); - assert_eq!(m.into_iter().collect::>(), &[4, 5, 6]); -} - -#[test] -fn drain_to_empty_test() { - let mut m: LinkedList = LinkedList::new(); - m.extend(&[1, 2, 3, 4, 5, 6]); - let deleted = m.extract_if(|_| true).collect::>(); - - check_links(&m); - - assert_eq!(deleted, &[1, 2, 3, 4, 5, 6]); - assert_eq!(m.into_iter().collect::>(), &[]); -} - -#[test] -fn test_cursor_move_peek() { - let mut m: LinkedList = LinkedList::new(); - m.extend(&[1, 2, 3, 4, 5, 6]); - let mut cursor = m.cursor_front(); - assert_eq!(cursor.current(), Some(&1)); - assert_eq!(cursor.peek_next(), Some(&2)); - assert_eq!(cursor.peek_prev(), None); - assert_eq!(cursor.index(), Some(0)); - cursor.move_prev(); - assert_eq!(cursor.current(), None); - assert_eq!(cursor.peek_next(), Some(&1)); - assert_eq!(cursor.peek_prev(), Some(&6)); - assert_eq!(cursor.index(), None); - cursor.move_next(); - cursor.move_next(); - assert_eq!(cursor.current(), Some(&2)); - assert_eq!(cursor.peek_next(), Some(&3)); - assert_eq!(cursor.peek_prev(), Some(&1)); - assert_eq!(cursor.index(), Some(1)); - - let mut cursor = m.cursor_back(); - assert_eq!(cursor.current(), Some(&6)); - assert_eq!(cursor.peek_next(), None); - assert_eq!(cursor.peek_prev(), Some(&5)); - assert_eq!(cursor.index(), Some(5)); - cursor.move_next(); - assert_eq!(cursor.current(), None); - assert_eq!(cursor.peek_next(), Some(&1)); - assert_eq!(cursor.peek_prev(), Some(&6)); - assert_eq!(cursor.index(), None); - cursor.move_prev(); - cursor.move_prev(); - assert_eq!(cursor.current(), Some(&5)); - assert_eq!(cursor.peek_next(), Some(&6)); - assert_eq!(cursor.peek_prev(), Some(&4)); - assert_eq!(cursor.index(), Some(4)); - - let mut m: LinkedList = LinkedList::new(); - m.extend(&[1, 2, 3, 4, 5, 6]); - let mut cursor = m.cursor_front_mut(); - assert_eq!(cursor.current(), Some(&mut 1)); - assert_eq!(cursor.peek_next(), Some(&mut 2)); - assert_eq!(cursor.peek_prev(), None); - assert_eq!(cursor.index(), Some(0)); - cursor.move_prev(); - assert_eq!(cursor.current(), None); - assert_eq!(cursor.peek_next(), Some(&mut 1)); - assert_eq!(cursor.peek_prev(), Some(&mut 6)); - assert_eq!(cursor.index(), None); - cursor.move_next(); - cursor.move_next(); - assert_eq!(cursor.current(), Some(&mut 2)); - assert_eq!(cursor.peek_next(), Some(&mut 3)); - assert_eq!(cursor.peek_prev(), Some(&mut 1)); - assert_eq!(cursor.index(), Some(1)); - let mut cursor2 = cursor.as_cursor(); - assert_eq!(cursor2.current(), Some(&2)); - assert_eq!(cursor2.index(), Some(1)); - cursor2.move_next(); - assert_eq!(cursor2.current(), Some(&3)); - assert_eq!(cursor2.index(), Some(2)); - assert_eq!(cursor.current(), Some(&mut 2)); - assert_eq!(cursor.index(), Some(1)); - - let mut m: LinkedList = LinkedList::new(); - m.extend(&[1, 2, 3, 4, 5, 6]); - let mut cursor = m.cursor_back_mut(); - assert_eq!(cursor.current(), Some(&mut 6)); - assert_eq!(cursor.peek_next(), None); - assert_eq!(cursor.peek_prev(), Some(&mut 5)); - assert_eq!(cursor.index(), Some(5)); - cursor.move_next(); - assert_eq!(cursor.current(), None); - assert_eq!(cursor.peek_next(), Some(&mut 1)); - assert_eq!(cursor.peek_prev(), Some(&mut 6)); - assert_eq!(cursor.index(), None); - cursor.move_prev(); - cursor.move_prev(); - assert_eq!(cursor.current(), Some(&mut 5)); - assert_eq!(cursor.peek_next(), Some(&mut 6)); - assert_eq!(cursor.peek_prev(), Some(&mut 4)); - assert_eq!(cursor.index(), Some(4)); - let mut cursor2 = cursor.as_cursor(); - assert_eq!(cursor2.current(), Some(&5)); - assert_eq!(cursor2.index(), Some(4)); - cursor2.move_prev(); - assert_eq!(cursor2.current(), Some(&4)); - assert_eq!(cursor2.index(), Some(3)); - assert_eq!(cursor.current(), Some(&mut 5)); - assert_eq!(cursor.index(), Some(4)); -} - -#[test] -fn test_cursor_mut_insert() { - let mut m: LinkedList = LinkedList::new(); - m.extend(&[1, 2, 3, 4, 5, 6]); - let mut cursor = m.cursor_front_mut(); - cursor.insert_before(7); - cursor.insert_after(8); - check_links(&m); - assert_eq!(m.iter().cloned().collect::>(), &[7, 1, 8, 2, 3, 4, 5, 6]); - let mut cursor = m.cursor_front_mut(); - cursor.move_prev(); - cursor.insert_before(9); - cursor.insert_after(10); - check_links(&m); - assert_eq!(m.iter().cloned().collect::>(), &[10, 7, 1, 8, 2, 3, 4, 5, 6, 9]); - let mut cursor = m.cursor_front_mut(); - cursor.move_prev(); - assert_eq!(cursor.remove_current(), None); - cursor.move_next(); - cursor.move_next(); - assert_eq!(cursor.remove_current(), Some(7)); - cursor.move_prev(); - cursor.move_prev(); - cursor.move_prev(); - assert_eq!(cursor.remove_current(), Some(9)); - cursor.move_next(); - assert_eq!(cursor.remove_current(), Some(10)); - check_links(&m); - assert_eq!(m.iter().cloned().collect::>(), &[1, 8, 2, 3, 4, 5, 6]); - let mut cursor = m.cursor_front_mut(); - let mut p: LinkedList = LinkedList::new(); - p.extend(&[100, 101, 102, 103]); - let mut q: LinkedList = LinkedList::new(); - q.extend(&[200, 201, 202, 203]); - cursor.splice_after(p); - cursor.splice_before(q); - check_links(&m); - assert_eq!( - m.iter().cloned().collect::>(), - &[200, 201, 202, 203, 1, 100, 101, 102, 103, 8, 2, 3, 4, 5, 6] - ); - let mut cursor = m.cursor_front_mut(); - cursor.move_prev(); - let tmp = cursor.split_before(); - assert_eq!(m.into_iter().collect::>(), &[]); - m = tmp; - let mut cursor = m.cursor_front_mut(); - cursor.move_next(); - cursor.move_next(); - cursor.move_next(); - cursor.move_next(); - cursor.move_next(); - cursor.move_next(); - let tmp = cursor.split_after(); - assert_eq!(tmp.into_iter().collect::>(), &[102, 103, 8, 2, 3, 4, 5, 6]); - check_links(&m); - assert_eq!(m.iter().cloned().collect::>(), &[200, 201, 202, 203, 1, 100, 101]); -} - -#[test] -fn test_cursor_push_front_back() { - let mut ll: LinkedList = LinkedList::new(); - ll.extend(&[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); - let mut c = ll.cursor_front_mut(); - assert_eq!(c.current(), Some(&mut 1)); - assert_eq!(c.index(), Some(0)); - c.push_front(0); - assert_eq!(c.current(), Some(&mut 1)); - assert_eq!(c.peek_prev(), Some(&mut 0)); - assert_eq!(c.index(), Some(1)); - c.push_back(11); - drop(c); - let p = ll.cursor_back().front().unwrap(); - assert_eq!(p, &0); - assert_eq!(ll, (0..12).collect()); - check_links(&ll); -} - -#[test] -fn test_cursor_pop_front_back() { - let mut ll: LinkedList = LinkedList::new(); - ll.extend(&[1, 2, 3, 4, 5, 6]); - let mut c = ll.cursor_back_mut(); - assert_eq!(c.pop_front(), Some(1)); - c.move_prev(); - c.move_prev(); - c.move_prev(); - assert_eq!(c.pop_back(), Some(6)); - let c = c.as_cursor(); - assert_eq!(c.front(), Some(&2)); - assert_eq!(c.back(), Some(&5)); - assert_eq!(c.index(), Some(1)); - drop(c); - assert_eq!(ll, (2..6).collect()); - check_links(&ll); - let mut c = ll.cursor_back_mut(); - assert_eq!(c.current(), Some(&mut 5)); - assert_eq!(c.index, 3); - assert_eq!(c.pop_back(), Some(5)); - assert_eq!(c.current(), None); - assert_eq!(c.index, 3); - assert_eq!(c.pop_back(), Some(4)); - assert_eq!(c.current(), None); - assert_eq!(c.index, 2); -} - -#[test] -fn test_extend_ref() { - let mut a = LinkedList::new(); - a.push_back(1); - - a.extend(&[2, 3, 4]); - - assert_eq!(a.len(), 4); - assert_eq!(a, list_from(&[1, 2, 3, 4])); - - let mut b = LinkedList::new(); - b.push_back(5); - b.push_back(6); - a.extend(&b); - - assert_eq!(a.len(), 6); - assert_eq!(a, list_from(&[1, 2, 3, 4, 5, 6])); -} - -#[test] -fn test_extend() { - let mut a = LinkedList::new(); - a.push_back(1); - a.extend(vec![2, 3, 4]); // uses iterator - - assert_eq!(a.len(), 4); - assert!(a.iter().eq(&[1, 2, 3, 4])); - - let b: LinkedList<_> = [5, 6, 7].into_iter().collect(); - a.extend(b); // specializes to `append` - - assert_eq!(a.len(), 7); - assert!(a.iter().eq(&[1, 2, 3, 4, 5, 6, 7])); -} - -#[test] -fn test_contains() { - let mut l = LinkedList::new(); - l.extend(&[2, 3, 4]); - - assert!(l.contains(&3)); - assert!(!l.contains(&1)); - - l.clear(); - - assert!(!l.contains(&3)); -} - -#[test] -fn extract_if_empty() { - let mut list: LinkedList = LinkedList::new(); - - { - let mut iter = list.extract_if(|_| true); - assert_eq!(iter.size_hint(), (0, Some(0))); - assert_eq!(iter.next(), None); - assert_eq!(iter.size_hint(), (0, Some(0))); - assert_eq!(iter.next(), None); - assert_eq!(iter.size_hint(), (0, Some(0))); - } - - assert_eq!(list.len(), 0); - assert_eq!(list.into_iter().collect::>(), vec![]); -} - -#[test] -fn extract_if_zst() { - let mut list: LinkedList<_> = [(), (), (), (), ()].into_iter().collect(); - let initial_len = list.len(); - let mut count = 0; - - { - let mut iter = list.extract_if(|_| true); - assert_eq!(iter.size_hint(), (0, Some(initial_len))); - while let Some(_) = iter.next() { - count += 1; - assert_eq!(iter.size_hint(), (0, Some(initial_len - count))); - } - assert_eq!(iter.size_hint(), (0, Some(0))); - assert_eq!(iter.next(), None); - assert_eq!(iter.size_hint(), (0, Some(0))); - } - - assert_eq!(count, initial_len); - assert_eq!(list.len(), 0); - assert_eq!(list.into_iter().collect::>(), vec![]); -} - -#[test] -fn extract_if_false() { - let mut list: LinkedList<_> = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10].into_iter().collect(); - - let initial_len = list.len(); - let mut count = 0; - - { - let mut iter = list.extract_if(|_| false); - assert_eq!(iter.size_hint(), (0, Some(initial_len))); - for _ in iter.by_ref() { - count += 1; - } - assert_eq!(iter.size_hint(), (0, Some(0))); - assert_eq!(iter.next(), None); - assert_eq!(iter.size_hint(), (0, Some(0))); - } - - assert_eq!(count, 0); - assert_eq!(list.len(), initial_len); - assert_eq!(list.into_iter().collect::>(), vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); -} - -#[test] -fn extract_if_true() { - let mut list: LinkedList<_> = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10].into_iter().collect(); - - let initial_len = list.len(); - let mut count = 0; - - { - let mut iter = list.extract_if(|_| true); - assert_eq!(iter.size_hint(), (0, Some(initial_len))); - while let Some(_) = iter.next() { - count += 1; - assert_eq!(iter.size_hint(), (0, Some(initial_len - count))); - } - assert_eq!(iter.size_hint(), (0, Some(0))); - assert_eq!(iter.next(), None); - assert_eq!(iter.size_hint(), (0, Some(0))); - } - - assert_eq!(count, initial_len); - assert_eq!(list.len(), 0); - assert_eq!(list.into_iter().collect::>(), vec![]); -} - -#[test] -fn extract_if_complex() { - { - // [+xxx++++++xxxxx++++x+x++] - let mut list = [ - 1, 2, 4, 6, 7, 9, 11, 13, 15, 17, 18, 20, 22, 24, 26, 27, 29, 31, 33, 34, 35, 36, 37, - 39, - ] - .into_iter() - .collect::>(); - - let removed = list.extract_if(|x| *x % 2 == 0).collect::>(); - assert_eq!(removed.len(), 10); - assert_eq!(removed, vec![2, 4, 6, 18, 20, 22, 24, 26, 34, 36]); - - assert_eq!(list.len(), 14); - assert_eq!( - list.into_iter().collect::>(), - vec![1, 7, 9, 11, 13, 15, 17, 27, 29, 31, 33, 35, 37, 39] - ); - } - - { - // [xxx++++++xxxxx++++x+x++] - let mut list = - [2, 4, 6, 7, 9, 11, 13, 15, 17, 18, 20, 22, 24, 26, 27, 29, 31, 33, 34, 35, 36, 37, 39] - .into_iter() - .collect::>(); - - let removed = list.extract_if(|x| *x % 2 == 0).collect::>(); - assert_eq!(removed.len(), 10); - assert_eq!(removed, vec![2, 4, 6, 18, 20, 22, 24, 26, 34, 36]); - - assert_eq!(list.len(), 13); - assert_eq!( - list.into_iter().collect::>(), - vec![7, 9, 11, 13, 15, 17, 27, 29, 31, 33, 35, 37, 39] - ); - } - - { - // [xxx++++++xxxxx++++x+x] - let mut list = - [2, 4, 6, 7, 9, 11, 13, 15, 17, 18, 20, 22, 24, 26, 27, 29, 31, 33, 34, 35, 36] - .into_iter() - .collect::>(); - - let removed = list.extract_if(|x| *x % 2 == 0).collect::>(); - assert_eq!(removed.len(), 10); - assert_eq!(removed, vec![2, 4, 6, 18, 20, 22, 24, 26, 34, 36]); - - assert_eq!(list.len(), 11); - assert_eq!( - list.into_iter().collect::>(), - vec![7, 9, 11, 13, 15, 17, 27, 29, 31, 33, 35] - ); - } - - { - // [xxxxxxxxxx+++++++++++] - let mut list = [2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 1, 3, 5, 7, 9, 11, 13, 15, 17, 19] - .into_iter() - .collect::>(); - - let removed = list.extract_if(|x| *x % 2 == 0).collect::>(); - assert_eq!(removed.len(), 10); - assert_eq!(removed, vec![2, 4, 6, 8, 10, 12, 14, 16, 18, 20]); - - assert_eq!(list.len(), 10); - assert_eq!(list.into_iter().collect::>(), vec![1, 3, 5, 7, 9, 11, 13, 15, 17, 19]); - } - - { - // [+++++++++++xxxxxxxxxx] - let mut list = [1, 3, 5, 7, 9, 11, 13, 15, 17, 19, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20] - .into_iter() - .collect::>(); - - let removed = list.extract_if(|x| *x % 2 == 0).collect::>(); - assert_eq!(removed.len(), 10); - assert_eq!(removed, vec![2, 4, 6, 8, 10, 12, 14, 16, 18, 20]); - - assert_eq!(list.len(), 10); - assert_eq!(list.into_iter().collect::>(), vec![1, 3, 5, 7, 9, 11, 13, 15, 17, 19]); - } -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn extract_if_drop_panic_leak() { - let d0 = CrashTestDummy::new(0); - let d1 = CrashTestDummy::new(1); - let d2 = CrashTestDummy::new(2); - let d3 = CrashTestDummy::new(3); - let d4 = CrashTestDummy::new(4); - let d5 = CrashTestDummy::new(5); - let d6 = CrashTestDummy::new(6); - let d7 = CrashTestDummy::new(7); - let mut q = LinkedList::new(); - q.push_back(d3.spawn(Panic::Never)); - q.push_back(d4.spawn(Panic::Never)); - q.push_back(d5.spawn(Panic::Never)); - q.push_back(d6.spawn(Panic::Never)); - q.push_back(d7.spawn(Panic::Never)); - q.push_front(d2.spawn(Panic::Never)); - q.push_front(d1.spawn(Panic::InDrop)); - q.push_front(d0.spawn(Panic::Never)); - - catch_unwind(AssertUnwindSafe(|| q.extract_if(|_| true).for_each(drop))).unwrap_err(); - - assert_eq!(d0.dropped(), 1); - assert_eq!(d1.dropped(), 1); - assert_eq!(d2.dropped(), 0); - assert_eq!(d3.dropped(), 0); - assert_eq!(d4.dropped(), 0); - assert_eq!(d5.dropped(), 0); - assert_eq!(d6.dropped(), 0); - assert_eq!(d7.dropped(), 0); - drop(q); - assert_eq!(d2.dropped(), 1); - assert_eq!(d3.dropped(), 1); - assert_eq!(d4.dropped(), 1); - assert_eq!(d5.dropped(), 1); - assert_eq!(d6.dropped(), 1); - assert_eq!(d7.dropped(), 1); -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn extract_if_pred_panic_leak() { - static mut DROPS: i32 = 0; - - #[derive(Debug)] - struct D(u32); - - impl Drop for D { - fn drop(&mut self) { - unsafe { - DROPS += 1; - } - } - } - - let mut q = LinkedList::new(); - q.push_back(D(3)); - q.push_back(D(4)); - q.push_back(D(5)); - q.push_back(D(6)); - q.push_back(D(7)); - q.push_front(D(2)); - q.push_front(D(1)); - q.push_front(D(0)); - - catch_unwind(AssertUnwindSafe(|| { - q.extract_if(|item| if item.0 >= 2 { panic!() } else { true }).for_each(drop) - })) - .ok(); - - assert_eq!(unsafe { DROPS }, 2); // 0 and 1 - assert_eq!(q.len(), 6); -} - -#[test] -fn test_drop() { - static mut DROPS: i32 = 0; - struct Elem; - impl Drop for Elem { - fn drop(&mut self) { - unsafe { - DROPS += 1; - } - } - } - - let mut ring = LinkedList::new(); - ring.push_back(Elem); - ring.push_front(Elem); - ring.push_back(Elem); - ring.push_front(Elem); - drop(ring); - - assert_eq!(unsafe { DROPS }, 4); -} - -#[test] -fn test_drop_with_pop() { - static mut DROPS: i32 = 0; - struct Elem; - impl Drop for Elem { - fn drop(&mut self) { - unsafe { - DROPS += 1; - } - } - } - - let mut ring = LinkedList::new(); - ring.push_back(Elem); - ring.push_front(Elem); - ring.push_back(Elem); - ring.push_front(Elem); - - drop(ring.pop_back()); - drop(ring.pop_front()); - assert_eq!(unsafe { DROPS }, 2); - - drop(ring); - assert_eq!(unsafe { DROPS }, 4); -} - -#[test] -fn test_drop_clear() { - static mut DROPS: i32 = 0; - struct Elem; - impl Drop for Elem { - fn drop(&mut self) { - unsafe { - DROPS += 1; - } - } - } - - let mut ring = LinkedList::new(); - ring.push_back(Elem); - ring.push_front(Elem); - ring.push_back(Elem); - ring.push_front(Elem); - ring.clear(); - assert_eq!(unsafe { DROPS }, 4); - - drop(ring); - assert_eq!(unsafe { DROPS }, 4); -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_drop_panic() { - static mut DROPS: i32 = 0; - - struct D(bool); - - impl Drop for D { - fn drop(&mut self) { - unsafe { - DROPS += 1; - } - - if self.0 { - panic!("panic in `drop`"); - } - } - } - - let mut q = LinkedList::new(); - q.push_back(D(false)); - q.push_back(D(false)); - q.push_back(D(false)); - q.push_back(D(false)); - q.push_back(D(false)); - q.push_front(D(false)); - q.push_front(D(false)); - q.push_front(D(true)); - - catch_unwind(move || drop(q)).ok(); - - assert_eq!(unsafe { DROPS }, 8); -} diff --git a/library/alloc/src/collections/mod.rs b/library/alloc/src/collections/mod.rs deleted file mode 100644 index 705b81535c279..0000000000000 --- a/library/alloc/src/collections/mod.rs +++ /dev/null @@ -1,158 +0,0 @@ -//! Collection types. - -#![stable(feature = "rust1", since = "1.0.0")] - -#[cfg(not(no_global_oom_handling))] -pub mod binary_heap; -#[cfg(not(no_global_oom_handling))] -mod btree; -#[cfg(not(no_global_oom_handling))] -pub mod linked_list; -#[cfg(not(no_global_oom_handling))] -pub mod vec_deque; - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -pub mod btree_map { - //! An ordered map based on a B-Tree. - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::btree::map::*; -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -pub mod btree_set { - //! An ordered set based on a B-Tree. - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::btree::set::*; -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(no_inline)] -pub use binary_heap::BinaryHeap; - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(no_inline)] -pub use btree_map::BTreeMap; - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(no_inline)] -pub use btree_set::BTreeSet; - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(no_inline)] -pub use linked_list::LinkedList; - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(no_inline)] -pub use vec_deque::VecDeque; - -use crate::alloc::{Layout, LayoutError}; -use core::fmt::Display; - -/// The error type for `try_reserve` methods. -#[derive(Clone, PartialEq, Eq, Debug)] -#[stable(feature = "try_reserve", since = "1.57.0")] -pub struct TryReserveError { - kind: TryReserveErrorKind, -} - -impl TryReserveError { - /// Details about the allocation that caused the error - #[inline] - #[must_use] - #[unstable( - feature = "try_reserve_kind", - reason = "Uncertain how much info should be exposed", - issue = "48043" - )] - pub fn kind(&self) -> TryReserveErrorKind { - self.kind.clone() - } -} - -/// Details of the allocation that caused a `TryReserveError` -#[derive(Clone, PartialEq, Eq, Debug)] -#[unstable( - feature = "try_reserve_kind", - reason = "Uncertain how much info should be exposed", - issue = "48043" -)] -pub enum TryReserveErrorKind { - /// Error due to the computed capacity exceeding the collection's maximum - /// (usually `isize::MAX` bytes). - CapacityOverflow, - - /// The memory allocator returned an error - AllocError { - /// The layout of allocation request that failed - layout: Layout, - - #[doc(hidden)] - #[unstable( - feature = "container_error_extra", - issue = "none", - reason = "\ - Enable exposing the allocator’s custom error value \ - if an associated type is added in the future: \ - https://github.com/rust-lang/wg-allocators/issues/23" - )] - non_exhaustive: (), - }, -} - -#[unstable( - feature = "try_reserve_kind", - reason = "Uncertain how much info should be exposed", - issue = "48043" -)] -impl From for TryReserveError { - #[inline] - fn from(kind: TryReserveErrorKind) -> Self { - Self { kind } - } -} - -#[unstable(feature = "try_reserve_kind", reason = "new API", issue = "48043")] -impl From for TryReserveErrorKind { - /// Always evaluates to [`TryReserveErrorKind::CapacityOverflow`]. - #[inline] - fn from(_: LayoutError) -> Self { - TryReserveErrorKind::CapacityOverflow - } -} - -#[stable(feature = "try_reserve", since = "1.57.0")] -impl Display for TryReserveError { - fn fmt( - &self, - fmt: &mut core::fmt::Formatter<'_>, - ) -> core::result::Result<(), core::fmt::Error> { - fmt.write_str("memory allocation failed")?; - let reason = match self.kind { - TryReserveErrorKind::CapacityOverflow => { - " because the computed capacity exceeded the collection's maximum" - } - TryReserveErrorKind::AllocError { .. } => { - " because the memory allocator returned an error" - } - }; - fmt.write_str(reason) - } -} - -/// An intermediate trait for specialization of `Extend`. -#[doc(hidden)] -#[cfg(not(no_global_oom_handling))] -trait SpecExtend { - /// Extends `self` with the contents of the given iterator. - fn spec_extend(&mut self, iter: I); -} - -#[stable(feature = "try_reserve", since = "1.57.0")] -impl core::error::Error for TryReserveError {} diff --git a/library/alloc/src/collections/vec_deque/drain.rs b/library/alloc/src/collections/vec_deque/drain.rs deleted file mode 100644 index 1373e60149274..0000000000000 --- a/library/alloc/src/collections/vec_deque/drain.rs +++ /dev/null @@ -1,275 +0,0 @@ -use core::iter::FusedIterator; -use core::marker::PhantomData; -use core::mem::{self, SizedTypeProperties}; -use core::ptr::NonNull; -use core::{fmt, ptr}; - -use crate::alloc::{Allocator, Global}; - -use super::VecDeque; - -/// A draining iterator over the elements of a `VecDeque`. -/// -/// This `struct` is created by the [`drain`] method on [`VecDeque`]. See its -/// documentation for more. -/// -/// [`drain`]: VecDeque::drain -#[stable(feature = "drain", since = "1.6.0")] -pub struct Drain< - 'a, - T: 'a, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, -> { - // We can't just use a &mut VecDeque, as that would make Drain invariant over T - // and we want it to be covariant instead - deque: NonNull>, - // drain_start is stored in deque.len - drain_len: usize, - // index into the logical array, not the physical one (always lies in [0..deque.len)) - idx: usize, - // number of elements remaining after dropping the drain - new_len: usize, - remaining: usize, - // Needed to make Drain covariant over T - _marker: PhantomData<&'a T>, -} - -impl<'a, T, A: Allocator> Drain<'a, T, A> { - pub(super) unsafe fn new( - deque: &'a mut VecDeque, - drain_start: usize, - drain_len: usize, - ) -> Self { - let orig_len = mem::replace(&mut deque.len, drain_start); - let new_len = orig_len - drain_len; - Drain { - deque: NonNull::from(deque), - drain_len, - idx: drain_start, - new_len, - remaining: drain_len, - _marker: PhantomData, - } - } - - // Only returns pointers to the slices, as that's all we need - // to drop them. May only be called if `self.remaining != 0`. - unsafe fn as_slices(&self) -> (*mut [T], *mut [T]) { - unsafe { - let deque = self.deque.as_ref(); - - // We know that `self.idx + self.remaining <= deque.len <= usize::MAX`, so this won't overflow. - let logical_remaining_range = self.idx..self.idx + self.remaining; - - // SAFETY: `logical_remaining_range` represents the - // range into the logical buffer of elements that - // haven't been drained yet, so they're all initialized, - // and `slice::range(start..end, end) == start..end`, - // so the preconditions for `slice_ranges` are met. - let (a_range, b_range) = - deque.slice_ranges(logical_remaining_range.clone(), logical_remaining_range.end); - (deque.buffer_range(a_range), deque.buffer_range(b_range)) - } - } -} - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl fmt::Debug for Drain<'_, T, A> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("Drain") - .field(&self.drain_len) - .field(&self.idx) - .field(&self.new_len) - .field(&self.remaining) - .finish() - } -} - -#[stable(feature = "drain", since = "1.6.0")] -unsafe impl Sync for Drain<'_, T, A> {} -#[stable(feature = "drain", since = "1.6.0")] -unsafe impl Send for Drain<'_, T, A> {} - -#[stable(feature = "drain", since = "1.6.0")] -impl Drop for Drain<'_, T, A> { - fn drop(&mut self) { - struct DropGuard<'r, 'a, T, A: Allocator>(&'r mut Drain<'a, T, A>); - - let guard = DropGuard(self); - - if mem::needs_drop::() && guard.0.remaining != 0 { - unsafe { - // SAFETY: We just checked that `self.remaining != 0`. - let (front, back) = guard.0.as_slices(); - // since idx is a logical index, we don't need to worry about wrapping. - guard.0.idx += front.len(); - guard.0.remaining -= front.len(); - ptr::drop_in_place(front); - guard.0.remaining = 0; - ptr::drop_in_place(back); - } - } - - // Dropping `guard` handles moving the remaining elements into place. - impl<'r, 'a, T, A: Allocator> Drop for DropGuard<'r, 'a, T, A> { - #[inline] - fn drop(&mut self) { - if mem::needs_drop::() && self.0.remaining != 0 { - unsafe { - // SAFETY: We just checked that `self.remaining != 0`. - let (front, back) = self.0.as_slices(); - ptr::drop_in_place(front); - ptr::drop_in_place(back); - } - } - - let source_deque = unsafe { self.0.deque.as_mut() }; - - let drain_len = self.0.drain_len; - let new_len = self.0.new_len; - - if T::IS_ZST { - // no need to copy around any memory if T is a ZST - source_deque.len = new_len; - return; - } - - let head_len = source_deque.len; // #elements in front of the drain - let tail_len = new_len - head_len; // #elements behind the drain - - // Next, we will fill the hole left by the drain with as few writes as possible. - // The code below handles the following control flow and reduces the amount of - // branches under the assumption that `head_len == 0 || tail_len == 0`, i.e. - // draining at the front or at the back of the dequeue is especially common. - // - // H = "head index" = `deque.head` - // h = elements in front of the drain - // d = elements in the drain - // t = elements behind the drain - // - // Note that the buffer may wrap at any point and the wrapping is handled by - // `wrap_copy` and `to_physical_idx`. - // - // Case 1: if `head_len == 0 && tail_len == 0` - // Everything was drained, reset the head index back to 0. - // H - // [ . . . . . d d d d . . . . . ] - // H - // [ . . . . . . . . . . . . . . ] - // - // Case 2: else if `tail_len == 0` - // Don't move data or the head index. - // H - // [ . . . h h h h d d d d . . . ] - // H - // [ . . . h h h h . . . . . . . ] - // - // Case 3: else if `head_len == 0` - // Don't move data, but move the head index. - // H - // [ . . . d d d d t t t t . . . ] - // H - // [ . . . . . . . t t t t . . . ] - // - // Case 4: else if `tail_len <= head_len` - // Move data, but not the head index. - // H - // [ . . h h h h d d d d t t . . ] - // H - // [ . . h h h h t t . . . . . . ] - // - // Case 5: else - // Move data and the head index. - // H - // [ . . h h d d d d t t t t . . ] - // H - // [ . . . . . . h h t t t t . . ] - - // When draining at the front (`.drain(..n)`) or at the back (`.drain(n..)`), - // we don't need to copy any data. The number of elements copied would be 0. - if head_len != 0 && tail_len != 0 { - join_head_and_tail_wrapping(source_deque, drain_len, head_len, tail_len); - // Marking this function as cold helps LLVM to eliminate it entirely if - // this branch is never taken. - // We use `#[cold]` instead of `#[inline(never)]`, because inlining this - // function into the general case (`.drain(n..m)`) is fine. - // See `tests/codegen/vecdeque-drain.rs` for a test. - #[cold] - fn join_head_and_tail_wrapping( - source_deque: &mut VecDeque, - drain_len: usize, - head_len: usize, - tail_len: usize, - ) { - // Pick whether to move the head or the tail here. - let (src, dst, len); - if head_len < tail_len { - src = source_deque.head; - dst = source_deque.to_physical_idx(drain_len); - len = head_len; - } else { - src = source_deque.to_physical_idx(head_len + drain_len); - dst = source_deque.to_physical_idx(head_len); - len = tail_len; - }; - - unsafe { - source_deque.wrap_copy(src, dst, len); - } - } - } - - if new_len == 0 { - // Special case: If the entire dequeue was drained, reset the head back to 0, - // like `.clear()` does. - source_deque.head = 0; - } else if head_len < tail_len { - // If we moved the head above, then we need to adjust the head index here. - source_deque.head = source_deque.to_physical_idx(drain_len); - } - source_deque.len = new_len; - } - } - } -} - -#[stable(feature = "drain", since = "1.6.0")] -impl Iterator for Drain<'_, T, A> { - type Item = T; - - #[inline] - fn next(&mut self) -> Option { - if self.remaining == 0 { - return None; - } - let wrapped_idx = unsafe { self.deque.as_ref().to_physical_idx(self.idx) }; - self.idx += 1; - self.remaining -= 1; - Some(unsafe { self.deque.as_mut().buffer_read(wrapped_idx) }) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let len = self.remaining; - (len, Some(len)) - } -} - -#[stable(feature = "drain", since = "1.6.0")] -impl DoubleEndedIterator for Drain<'_, T, A> { - #[inline] - fn next_back(&mut self) -> Option { - if self.remaining == 0 { - return None; - } - self.remaining -= 1; - let wrapped_idx = unsafe { self.deque.as_ref().to_physical_idx(self.idx + self.remaining) }; - Some(unsafe { self.deque.as_mut().buffer_read(wrapped_idx) }) - } -} - -#[stable(feature = "drain", since = "1.6.0")] -impl ExactSizeIterator for Drain<'_, T, A> {} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Drain<'_, T, A> {} diff --git a/library/alloc/src/collections/vec_deque/into_iter.rs b/library/alloc/src/collections/vec_deque/into_iter.rs deleted file mode 100644 index 692af7c197a30..0000000000000 --- a/library/alloc/src/collections/vec_deque/into_iter.rs +++ /dev/null @@ -1,261 +0,0 @@ -use core::iter::{FusedIterator, TrustedLen}; -use core::num::NonZero; -use core::{array, fmt, mem::MaybeUninit, ops::Try, ptr}; - -use crate::alloc::{Allocator, Global}; - -use super::VecDeque; - -/// An owning iterator over the elements of a `VecDeque`. -/// -/// This `struct` is created by the [`into_iter`] method on [`VecDeque`] -/// (provided by the [`IntoIterator`] trait). See its documentation for more. -/// -/// [`into_iter`]: VecDeque::into_iter -#[derive(Clone)] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct IntoIter< - T, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, -> { - inner: VecDeque, -} - -impl IntoIter { - pub(super) fn new(inner: VecDeque) -> Self { - IntoIter { inner } - } - - pub(super) fn into_vecdeque(self) -> VecDeque { - self.inner - } -} - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl fmt::Debug for IntoIter { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("IntoIter").field(&self.inner).finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for IntoIter { - type Item = T; - - #[inline] - fn next(&mut self) -> Option { - self.inner.pop_front() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let len = self.inner.len(); - (len, Some(len)) - } - - #[inline] - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - let len = self.inner.len; - let rem = if len < n { - self.inner.clear(); - n - len - } else { - self.inner.drain(..n); - 0 - }; - NonZero::new(rem).map_or(Ok(()), Err) - } - - #[inline] - fn count(self) -> usize { - self.inner.len - } - - fn try_fold(&mut self, mut init: B, mut f: F) -> R - where - F: FnMut(B, Self::Item) -> R, - R: Try, - { - struct Guard<'a, T, A: Allocator> { - deque: &'a mut VecDeque, - // `consumed <= deque.len` always holds. - consumed: usize, - } - - impl<'a, T, A: Allocator> Drop for Guard<'a, T, A> { - fn drop(&mut self) { - self.deque.len -= self.consumed; - self.deque.head = self.deque.to_physical_idx(self.consumed); - } - } - - let mut guard = Guard { deque: &mut self.inner, consumed: 0 }; - - let (head, tail) = guard.deque.as_slices(); - - init = head - .iter() - .map(|elem| { - guard.consumed += 1; - // SAFETY: Because we incremented `guard.consumed`, the - // deque effectively forgot the element, so we can take - // ownership - unsafe { ptr::read(elem) } - }) - .try_fold(init, &mut f)?; - - tail.iter() - .map(|elem| { - guard.consumed += 1; - // SAFETY: Same as above. - unsafe { ptr::read(elem) } - }) - .try_fold(init, &mut f) - } - - #[inline] - fn fold(mut self, init: B, mut f: F) -> B - where - F: FnMut(B, Self::Item) -> B, - { - match self.try_fold(init, |b, item| Ok::(f(b, item))) { - Ok(b) => b, - Err(e) => match e {}, - } - } - - #[inline] - fn last(mut self) -> Option { - self.inner.pop_back() - } - - fn next_chunk( - &mut self, - ) -> Result<[Self::Item; N], array::IntoIter> { - let mut raw_arr = MaybeUninit::uninit_array(); - let raw_arr_ptr = raw_arr.as_mut_ptr().cast(); - let (head, tail) = self.inner.as_slices(); - - if head.len() >= N { - // SAFETY: By manually adjusting the head and length of the deque, we effectively - // make it forget the first `N` elements, so taking ownership of them is safe. - unsafe { ptr::copy_nonoverlapping(head.as_ptr(), raw_arr_ptr, N) }; - self.inner.head = self.inner.to_physical_idx(N); - self.inner.len -= N; - // SAFETY: We initialized the entire array with items from `head` - return Ok(unsafe { raw_arr.transpose().assume_init() }); - } - - // SAFETY: Same argument as above. - unsafe { ptr::copy_nonoverlapping(head.as_ptr(), raw_arr_ptr, head.len()) }; - let remaining = N - head.len(); - - if tail.len() >= remaining { - // SAFETY: Same argument as above. - unsafe { - ptr::copy_nonoverlapping(tail.as_ptr(), raw_arr_ptr.add(head.len()), remaining) - }; - self.inner.head = self.inner.to_physical_idx(N); - self.inner.len -= N; - // SAFETY: We initialized the entire array with items from `head` and `tail` - Ok(unsafe { raw_arr.transpose().assume_init() }) - } else { - // SAFETY: Same argument as above. - unsafe { - ptr::copy_nonoverlapping(tail.as_ptr(), raw_arr_ptr.add(head.len()), tail.len()) - }; - let init = head.len() + tail.len(); - // We completely drained all the deques elements. - self.inner.head = 0; - self.inner.len = 0; - // SAFETY: We copied all elements from both slices to the beginning of the array, so - // the given range is initialized. - Err(unsafe { array::IntoIter::new_unchecked(raw_arr, 0..init) }) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DoubleEndedIterator for IntoIter { - #[inline] - fn next_back(&mut self) -> Option { - self.inner.pop_back() - } - - #[inline] - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - let len = self.inner.len; - let rem = if len < n { - self.inner.clear(); - n - len - } else { - self.inner.truncate(len - n); - 0 - }; - NonZero::new(rem).map_or(Ok(()), Err) - } - - fn try_rfold(&mut self, mut init: B, mut f: F) -> R - where - F: FnMut(B, Self::Item) -> R, - R: Try, - { - struct Guard<'a, T, A: Allocator> { - deque: &'a mut VecDeque, - // `consumed <= deque.len` always holds. - consumed: usize, - } - - impl<'a, T, A: Allocator> Drop for Guard<'a, T, A> { - fn drop(&mut self) { - self.deque.len -= self.consumed; - } - } - - let mut guard = Guard { deque: &mut self.inner, consumed: 0 }; - - let (head, tail) = guard.deque.as_slices(); - - init = tail - .iter() - .map(|elem| { - guard.consumed += 1; - // SAFETY: See `try_fold`'s safety comment. - unsafe { ptr::read(elem) } - }) - .try_rfold(init, &mut f)?; - - head.iter() - .map(|elem| { - guard.consumed += 1; - // SAFETY: Same as above. - unsafe { ptr::read(elem) } - }) - .try_rfold(init, &mut f) - } - - #[inline] - fn rfold(mut self, init: B, mut f: F) -> B - where - F: FnMut(B, Self::Item) -> B, - { - match self.try_rfold(init, |b, item| Ok::(f(b, item))) { - Ok(b) => b, - Err(e) => match e {}, - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for IntoIter { - #[inline] - fn is_empty(&self) -> bool { - self.inner.is_empty() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for IntoIter {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for IntoIter {} diff --git a/library/alloc/src/collections/vec_deque/iter.rs b/library/alloc/src/collections/vec_deque/iter.rs deleted file mode 100644 index 5a5e7f70854d8..0000000000000 --- a/library/alloc/src/collections/vec_deque/iter.rs +++ /dev/null @@ -1,184 +0,0 @@ -use core::iter::{FusedIterator, TrustedLen, TrustedRandomAccess, TrustedRandomAccessNoCoerce}; -use core::num::NonZero; -use core::ops::Try; -use core::{fmt, mem, slice}; - -/// An iterator over the elements of a `VecDeque`. -/// -/// This `struct` is created by the [`iter`] method on [`super::VecDeque`]. See its -/// documentation for more. -/// -/// [`iter`]: super::VecDeque::iter -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Iter<'a, T: 'a> { - i1: slice::Iter<'a, T>, - i2: slice::Iter<'a, T>, -} - -impl<'a, T> Iter<'a, T> { - pub(super) fn new(i1: slice::Iter<'a, T>, i2: slice::Iter<'a, T>) -> Self { - Self { i1, i2 } - } -} - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl fmt::Debug for Iter<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("Iter").field(&self.i1.as_slice()).field(&self.i2.as_slice()).finish() - } -} - -// FIXME(#26925) Remove in favor of `#[derive(Clone)]` -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Iter<'_, T> { - fn clone(&self) -> Self { - Iter { i1: self.i1.clone(), i2: self.i2.clone() } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> Iterator for Iter<'a, T> { - type Item = &'a T; - - #[inline] - fn next(&mut self) -> Option<&'a T> { - match self.i1.next() { - Some(val) => Some(val), - None => { - // most of the time, the iterator will either always - // call next(), or always call next_back(). By swapping - // the iterators once the first one is empty, we ensure - // that the first branch is taken as often as possible, - // without sacrificing correctness, as i1 is empty anyways - mem::swap(&mut self.i1, &mut self.i2); - self.i1.next() - } - } - } - - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - let remaining = self.i1.advance_by(n); - match remaining { - Ok(()) => return Ok(()), - Err(n) => { - mem::swap(&mut self.i1, &mut self.i2); - self.i1.advance_by(n.get()) - } - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let len = self.len(); - (len, Some(len)) - } - - fn fold(self, accum: Acc, mut f: F) -> Acc - where - F: FnMut(Acc, Self::Item) -> Acc, - { - let accum = self.i1.fold(accum, &mut f); - self.i2.fold(accum, &mut f) - } - - fn try_fold(&mut self, init: B, mut f: F) -> R - where - F: FnMut(B, Self::Item) -> R, - R: Try, - { - let acc = self.i1.try_fold(init, &mut f)?; - self.i2.try_fold(acc, &mut f) - } - - #[inline] - fn last(mut self) -> Option<&'a T> { - self.next_back() - } - - #[inline] - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item { - // Safety: The TrustedRandomAccess contract requires that callers only pass an index - // that is in bounds. - unsafe { - let i1_len = self.i1.len(); - if idx < i1_len { - self.i1.__iterator_get_unchecked(idx) - } else { - self.i2.__iterator_get_unchecked(idx - i1_len) - } - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> DoubleEndedIterator for Iter<'a, T> { - #[inline] - fn next_back(&mut self) -> Option<&'a T> { - match self.i2.next_back() { - Some(val) => Some(val), - None => { - // most of the time, the iterator will either always - // call next(), or always call next_back(). By swapping - // the iterators once the second one is empty, we ensure - // that the first branch is taken as often as possible, - // without sacrificing correctness, as i2 is empty anyways - mem::swap(&mut self.i1, &mut self.i2); - self.i2.next_back() - } - } - } - - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - match self.i2.advance_back_by(n) { - Ok(()) => return Ok(()), - Err(n) => { - mem::swap(&mut self.i1, &mut self.i2); - self.i2.advance_back_by(n.get()) - } - } - } - - fn rfold(self, accum: Acc, mut f: F) -> Acc - where - F: FnMut(Acc, Self::Item) -> Acc, - { - let accum = self.i2.rfold(accum, &mut f); - self.i1.rfold(accum, &mut f) - } - - fn try_rfold(&mut self, init: B, mut f: F) -> R - where - F: FnMut(B, Self::Item) -> R, - R: Try, - { - let acc = self.i2.try_rfold(init, &mut f)?; - self.i1.try_rfold(acc, &mut f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Iter<'_, T> { - fn len(&self) -> usize { - self.i1.len() + self.i2.len() - } - - fn is_empty(&self) -> bool { - self.i1.is_empty() && self.i2.is_empty() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Iter<'_, T> {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for Iter<'_, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl TrustedRandomAccess for Iter<'_, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl TrustedRandomAccessNoCoerce for Iter<'_, T> { - const MAY_HAVE_SIDE_EFFECT: bool = false; -} diff --git a/library/alloc/src/collections/vec_deque/iter_mut.rs b/library/alloc/src/collections/vec_deque/iter_mut.rs deleted file mode 100644 index 5061931afb7b7..0000000000000 --- a/library/alloc/src/collections/vec_deque/iter_mut.rs +++ /dev/null @@ -1,175 +0,0 @@ -use core::iter::{FusedIterator, TrustedLen, TrustedRandomAccess, TrustedRandomAccessNoCoerce}; -use core::num::NonZero; -use core::ops::Try; -use core::{fmt, mem, slice}; - -/// A mutable iterator over the elements of a `VecDeque`. -/// -/// This `struct` is created by the [`iter_mut`] method on [`super::VecDeque`]. See its -/// documentation for more. -/// -/// [`iter_mut`]: super::VecDeque::iter_mut -#[stable(feature = "rust1", since = "1.0.0")] -pub struct IterMut<'a, T: 'a> { - i1: slice::IterMut<'a, T>, - i2: slice::IterMut<'a, T>, -} - -impl<'a, T> IterMut<'a, T> { - pub(super) fn new(i1: slice::IterMut<'a, T>, i2: slice::IterMut<'a, T>) -> Self { - Self { i1, i2 } - } -} - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl fmt::Debug for IterMut<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("IterMut").field(&self.i1.as_slice()).field(&self.i2.as_slice()).finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> Iterator for IterMut<'a, T> { - type Item = &'a mut T; - - #[inline] - fn next(&mut self) -> Option<&'a mut T> { - match self.i1.next() { - Some(val) => Some(val), - None => { - // most of the time, the iterator will either always - // call next(), or always call next_back(). By swapping - // the iterators once the first one is empty, we ensure - // that the first branch is taken as often as possible, - // without sacrificing correctness, as i1 is empty anyways - mem::swap(&mut self.i1, &mut self.i2); - self.i1.next() - } - } - } - - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - match self.i1.advance_by(n) { - Ok(()) => return Ok(()), - Err(remaining) => { - mem::swap(&mut self.i1, &mut self.i2); - self.i1.advance_by(remaining.get()) - } - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let len = self.len(); - (len, Some(len)) - } - - fn fold(self, accum: Acc, mut f: F) -> Acc - where - F: FnMut(Acc, Self::Item) -> Acc, - { - let accum = self.i1.fold(accum, &mut f); - self.i2.fold(accum, &mut f) - } - - fn try_fold(&mut self, init: B, mut f: F) -> R - where - F: FnMut(B, Self::Item) -> R, - R: Try, - { - let acc = self.i1.try_fold(init, &mut f)?; - self.i2.try_fold(acc, &mut f) - } - - #[inline] - fn last(mut self) -> Option<&'a mut T> { - self.next_back() - } - - #[inline] - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item { - // Safety: The TrustedRandomAccess contract requires that callers only pass an index - // that is in bounds. - unsafe { - let i1_len = self.i1.len(); - if idx < i1_len { - self.i1.__iterator_get_unchecked(idx) - } else { - self.i2.__iterator_get_unchecked(idx - i1_len) - } - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> DoubleEndedIterator for IterMut<'a, T> { - #[inline] - fn next_back(&mut self) -> Option<&'a mut T> { - match self.i2.next_back() { - Some(val) => Some(val), - None => { - // most of the time, the iterator will either always - // call next(), or always call next_back(). By swapping - // the iterators once the first one is empty, we ensure - // that the first branch is taken as often as possible, - // without sacrificing correctness, as i2 is empty anyways - mem::swap(&mut self.i1, &mut self.i2); - self.i2.next_back() - } - } - } - - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - match self.i2.advance_back_by(n) { - Ok(()) => return Ok(()), - Err(remaining) => { - mem::swap(&mut self.i1, &mut self.i2); - self.i2.advance_back_by(remaining.get()) - } - } - } - - fn rfold(self, accum: Acc, mut f: F) -> Acc - where - F: FnMut(Acc, Self::Item) -> Acc, - { - let accum = self.i2.rfold(accum, &mut f); - self.i1.rfold(accum, &mut f) - } - - fn try_rfold(&mut self, init: B, mut f: F) -> R - where - F: FnMut(B, Self::Item) -> R, - R: Try, - { - let acc = self.i2.try_rfold(init, &mut f)?; - self.i1.try_rfold(acc, &mut f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for IterMut<'_, T> { - fn len(&self) -> usize { - self.i1.len() + self.i2.len() - } - - fn is_empty(&self) -> bool { - self.i1.is_empty() && self.i2.is_empty() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for IterMut<'_, T> {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for IterMut<'_, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl TrustedRandomAccess for IterMut<'_, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl TrustedRandomAccessNoCoerce for IterMut<'_, T> { - const MAY_HAVE_SIDE_EFFECT: bool = false; -} diff --git a/library/alloc/src/collections/vec_deque/macros.rs b/library/alloc/src/collections/vec_deque/macros.rs deleted file mode 100644 index 5c7913073fe87..0000000000000 --- a/library/alloc/src/collections/vec_deque/macros.rs +++ /dev/null @@ -1,19 +0,0 @@ -macro_rules! __impl_slice_eq1 { - ([$($vars:tt)*] $lhs:ty, $rhs:ty, $($constraints:tt)*) => { - #[stable(feature = "vec_deque_partial_eq_slice", since = "1.17.0")] - impl PartialEq<$rhs> for $lhs - where - T: PartialEq, - $($constraints)* - { - fn eq(&self, other: &$rhs) -> bool { - if self.len() != other.len() { - return false; - } - let (sa, sb) = self.as_slices(); - let (oa, ob) = other[..].split_at(sa.len()); - sa == oa && sb == ob - } - } - } -} diff --git a/library/alloc/src/collections/vec_deque/mod.rs b/library/alloc/src/collections/vec_deque/mod.rs deleted file mode 100644 index 4643a6bbe2ecd..0000000000000 --- a/library/alloc/src/collections/vec_deque/mod.rs +++ /dev/null @@ -1,2966 +0,0 @@ -//! A double-ended queue (deque) implemented with a growable ring buffer. -//! -//! This queue has *O*(1) amortized inserts and removals from both ends of the -//! container. It also has *O*(1) indexing like a vector. The contained elements -//! are not required to be copyable, and the queue will be sendable if the -//! contained type is sendable. - -#![stable(feature = "rust1", since = "1.0.0")] - -use core::cmp::{self, Ordering}; -use core::fmt; -use core::hash::{Hash, Hasher}; -use core::iter::{repeat_n, repeat_with, ByRefSized}; -use core::mem::{ManuallyDrop, SizedTypeProperties}; -use core::ops::{Index, IndexMut, Range, RangeBounds}; -use core::ptr; -use core::slice; - -// This is used in a bunch of intra-doc links. -// FIXME: For some reason, `#[cfg(doc)]` wasn't sufficient, resulting in -// failures in linkchecker even though rustdoc built the docs just fine. -#[allow(unused_imports)] -use core::mem; - -use crate::alloc::{Allocator, Global}; -use crate::collections::TryReserveError; -use crate::collections::TryReserveErrorKind; -use crate::raw_vec::RawVec; -use crate::vec::Vec; - -#[macro_use] -mod macros; - -#[stable(feature = "drain", since = "1.6.0")] -pub use self::drain::Drain; - -mod drain; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::iter_mut::IterMut; - -mod iter_mut; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::into_iter::IntoIter; - -mod into_iter; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::iter::Iter; - -mod iter; - -use self::spec_extend::SpecExtend; - -mod spec_extend; - -use self::spec_from_iter::SpecFromIter; - -mod spec_from_iter; - -#[cfg(test)] -mod tests; - -/// A double-ended queue implemented with a growable ring buffer. -/// -/// The "default" usage of this type as a queue is to use [`push_back`] to add to -/// the queue, and [`pop_front`] to remove from the queue. [`extend`] and [`append`] -/// push onto the back in this manner, and iterating over `VecDeque` goes front -/// to back. -/// -/// A `VecDeque` with a known list of items can be initialized from an array: -/// -/// ``` -/// use std::collections::VecDeque; -/// -/// let deq = VecDeque::from([-1, 0, 1]); -/// ``` -/// -/// Since `VecDeque` is a ring buffer, its elements are not necessarily contiguous -/// in memory. If you want to access the elements as a single slice, such as for -/// efficient sorting, you can use [`make_contiguous`]. It rotates the `VecDeque` -/// so that its elements do not wrap, and returns a mutable slice to the -/// now-contiguous element sequence. -/// -/// [`push_back`]: VecDeque::push_back -/// [`pop_front`]: VecDeque::pop_front -/// [`extend`]: VecDeque::extend -/// [`append`]: VecDeque::append -/// [`make_contiguous`]: VecDeque::make_contiguous -#[cfg_attr(not(test), rustc_diagnostic_item = "VecDeque")] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_insignificant_dtor] -pub struct VecDeque< - T, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, -> { - // `self[0]`, if it exists, is `buf[head]`. - // `head < buf.capacity()`, unless `buf.capacity() == 0` when `head == 0`. - head: usize, - // the number of initialized elements, starting from the one at `head` and potentially wrapping around. - // if `len == 0`, the exact value of `head` is unimportant. - // if `T` is zero-Sized, then `self.len <= usize::MAX`, otherwise `self.len <= isize::MAX as usize`. - len: usize, - buf: RawVec, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for VecDeque { - fn clone(&self) -> Self { - let mut deq = Self::with_capacity_in(self.len(), self.allocator().clone()); - deq.extend(self.iter().cloned()); - deq - } - - /// Overwrites the contents of `self` with a clone of the contents of `source`. - /// - /// This method is preferred over simply assigning `source.clone()` to `self`, - /// as it avoids reallocation if possible. - fn clone_from(&mut self, source: &Self) { - self.clear(); - self.extend(source.iter().cloned()); - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl<#[may_dangle] T, A: Allocator> Drop for VecDeque { - fn drop(&mut self) { - /// Runs the destructor for all items in the slice when it gets dropped (normally or - /// during unwinding). - struct Dropper<'a, T>(&'a mut [T]); - - impl<'a, T> Drop for Dropper<'a, T> { - fn drop(&mut self) { - unsafe { - ptr::drop_in_place(self.0); - } - } - } - - let (front, back) = self.as_mut_slices(); - unsafe { - let _back_dropper = Dropper(back); - // use drop for [T] - ptr::drop_in_place(front); - } - // RawVec handles deallocation - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Default for VecDeque { - /// Creates an empty deque. - #[inline] - fn default() -> VecDeque { - VecDeque::new() - } -} - -impl VecDeque { - /// Marginally more convenient - #[inline] - fn ptr(&self) -> *mut T { - self.buf.ptr() - } - - /// Moves an element out of the buffer - #[inline] - unsafe fn buffer_read(&mut self, off: usize) -> T { - unsafe { ptr::read(self.ptr().add(off)) } - } - - /// Writes an element into the buffer, moving it. - #[inline] - unsafe fn buffer_write(&mut self, off: usize, value: T) { - unsafe { - ptr::write(self.ptr().add(off), value); - } - } - - /// Returns a slice pointer into the buffer. - /// `range` must lie inside `0..self.capacity()`. - #[inline] - unsafe fn buffer_range(&self, range: Range) -> *mut [T] { - unsafe { - ptr::slice_from_raw_parts_mut(self.ptr().add(range.start), range.end - range.start) - } - } - - /// Returns `true` if the buffer is at full capacity. - #[inline] - fn is_full(&self) -> bool { - self.len == self.capacity() - } - - /// Returns the index in the underlying buffer for a given logical element - /// index + addend. - #[inline] - fn wrap_add(&self, idx: usize, addend: usize) -> usize { - wrap_index(idx.wrapping_add(addend), self.capacity()) - } - - #[inline] - fn to_physical_idx(&self, idx: usize) -> usize { - self.wrap_add(self.head, idx) - } - - /// Returns the index in the underlying buffer for a given logical element - /// index - subtrahend. - #[inline] - fn wrap_sub(&self, idx: usize, subtrahend: usize) -> usize { - wrap_index(idx.wrapping_sub(subtrahend).wrapping_add(self.capacity()), self.capacity()) - } - - /// Copies a contiguous block of memory len long from src to dst - #[inline] - unsafe fn copy(&mut self, src: usize, dst: usize, len: usize) { - debug_assert!( - dst + len <= self.capacity(), - "cpy dst={} src={} len={} cap={}", - dst, - src, - len, - self.capacity() - ); - debug_assert!( - src + len <= self.capacity(), - "cpy dst={} src={} len={} cap={}", - dst, - src, - len, - self.capacity() - ); - unsafe { - ptr::copy(self.ptr().add(src), self.ptr().add(dst), len); - } - } - - /// Copies a contiguous block of memory len long from src to dst - #[inline] - unsafe fn copy_nonoverlapping(&mut self, src: usize, dst: usize, len: usize) { - debug_assert!( - dst + len <= self.capacity(), - "cno dst={} src={} len={} cap={}", - dst, - src, - len, - self.capacity() - ); - debug_assert!( - src + len <= self.capacity(), - "cno dst={} src={} len={} cap={}", - dst, - src, - len, - self.capacity() - ); - unsafe { - ptr::copy_nonoverlapping(self.ptr().add(src), self.ptr().add(dst), len); - } - } - - /// Copies a potentially wrapping block of memory len long from src to dest. - /// (abs(dst - src) + len) must be no larger than capacity() (There must be at - /// most one continuous overlapping region between src and dest). - unsafe fn wrap_copy(&mut self, src: usize, dst: usize, len: usize) { - debug_assert!( - cmp::min(src.abs_diff(dst), self.capacity() - src.abs_diff(dst)) + len - <= self.capacity(), - "wrc dst={} src={} len={} cap={}", - dst, - src, - len, - self.capacity() - ); - - // If T is a ZST, don't do any copying. - if T::IS_ZST || src == dst || len == 0 { - return; - } - - let dst_after_src = self.wrap_sub(dst, src) < len; - - let src_pre_wrap_len = self.capacity() - src; - let dst_pre_wrap_len = self.capacity() - dst; - let src_wraps = src_pre_wrap_len < len; - let dst_wraps = dst_pre_wrap_len < len; - - match (dst_after_src, src_wraps, dst_wraps) { - (_, false, false) => { - // src doesn't wrap, dst doesn't wrap - // - // S . . . - // 1 [_ _ A A B B C C _] - // 2 [_ _ A A A A B B _] - // D . . . - // - unsafe { - self.copy(src, dst, len); - } - } - (false, false, true) => { - // dst before src, src doesn't wrap, dst wraps - // - // S . . . - // 1 [A A B B _ _ _ C C] - // 2 [A A B B _ _ _ A A] - // 3 [B B B B _ _ _ A A] - // . . D . - // - unsafe { - self.copy(src, dst, dst_pre_wrap_len); - self.copy(src + dst_pre_wrap_len, 0, len - dst_pre_wrap_len); - } - } - (true, false, true) => { - // src before dst, src doesn't wrap, dst wraps - // - // S . . . - // 1 [C C _ _ _ A A B B] - // 2 [B B _ _ _ A A B B] - // 3 [B B _ _ _ A A A A] - // . . D . - // - unsafe { - self.copy(src + dst_pre_wrap_len, 0, len - dst_pre_wrap_len); - self.copy(src, dst, dst_pre_wrap_len); - } - } - (false, true, false) => { - // dst before src, src wraps, dst doesn't wrap - // - // . . S . - // 1 [C C _ _ _ A A B B] - // 2 [C C _ _ _ B B B B] - // 3 [C C _ _ _ B B C C] - // D . . . - // - unsafe { - self.copy(src, dst, src_pre_wrap_len); - self.copy(0, dst + src_pre_wrap_len, len - src_pre_wrap_len); - } - } - (true, true, false) => { - // src before dst, src wraps, dst doesn't wrap - // - // . . S . - // 1 [A A B B _ _ _ C C] - // 2 [A A A A _ _ _ C C] - // 3 [C C A A _ _ _ C C] - // D . . . - // - unsafe { - self.copy(0, dst + src_pre_wrap_len, len - src_pre_wrap_len); - self.copy(src, dst, src_pre_wrap_len); - } - } - (false, true, true) => { - // dst before src, src wraps, dst wraps - // - // . . . S . - // 1 [A B C D _ E F G H] - // 2 [A B C D _ E G H H] - // 3 [A B C D _ E G H A] - // 4 [B C C D _ E G H A] - // . . D . . - // - debug_assert!(dst_pre_wrap_len > src_pre_wrap_len); - let delta = dst_pre_wrap_len - src_pre_wrap_len; - unsafe { - self.copy(src, dst, src_pre_wrap_len); - self.copy(0, dst + src_pre_wrap_len, delta); - self.copy(delta, 0, len - dst_pre_wrap_len); - } - } - (true, true, true) => { - // src before dst, src wraps, dst wraps - // - // . . S . . - // 1 [A B C D _ E F G H] - // 2 [A A B D _ E F G H] - // 3 [H A B D _ E F G H] - // 4 [H A B D _ E F F G] - // . . . D . - // - debug_assert!(src_pre_wrap_len > dst_pre_wrap_len); - let delta = src_pre_wrap_len - dst_pre_wrap_len; - unsafe { - self.copy(0, delta, len - src_pre_wrap_len); - self.copy(self.capacity() - delta, 0, delta); - self.copy(src, dst, dst_pre_wrap_len); - } - } - } - } - - /// Copies all values from `src` to `dst`, wrapping around if needed. - /// Assumes capacity is sufficient. - #[inline] - unsafe fn copy_slice(&mut self, dst: usize, src: &[T]) { - debug_assert!(src.len() <= self.capacity()); - let head_room = self.capacity() - dst; - if src.len() <= head_room { - unsafe { - ptr::copy_nonoverlapping(src.as_ptr(), self.ptr().add(dst), src.len()); - } - } else { - let (left, right) = src.split_at(head_room); - unsafe { - ptr::copy_nonoverlapping(left.as_ptr(), self.ptr().add(dst), left.len()); - ptr::copy_nonoverlapping(right.as_ptr(), self.ptr(), right.len()); - } - } - } - - /// Writes all values from `iter` to `dst`. - /// - /// # Safety - /// - /// Assumes no wrapping around happens. - /// Assumes capacity is sufficient. - #[inline] - unsafe fn write_iter( - &mut self, - dst: usize, - iter: impl Iterator, - written: &mut usize, - ) { - iter.enumerate().for_each(|(i, element)| unsafe { - self.buffer_write(dst + i, element); - *written += 1; - }); - } - - /// Writes all values from `iter` to `dst`, wrapping - /// at the end of the buffer and returns the number - /// of written values. - /// - /// # Safety - /// - /// Assumes that `iter` yields at most `len` items. - /// Assumes capacity is sufficient. - unsafe fn write_iter_wrapping( - &mut self, - dst: usize, - mut iter: impl Iterator, - len: usize, - ) -> usize { - struct Guard<'a, T, A: Allocator> { - deque: &'a mut VecDeque, - written: usize, - } - - impl<'a, T, A: Allocator> Drop for Guard<'a, T, A> { - fn drop(&mut self) { - self.deque.len += self.written; - } - } - - let head_room = self.capacity() - dst; - - let mut guard = Guard { deque: self, written: 0 }; - - if head_room >= len { - unsafe { guard.deque.write_iter(dst, iter, &mut guard.written) }; - } else { - unsafe { - guard.deque.write_iter( - dst, - ByRefSized(&mut iter).take(head_room), - &mut guard.written, - ); - guard.deque.write_iter(0, iter, &mut guard.written) - }; - } - - guard.written - } - - /// Frobs the head and tail sections around to handle the fact that we - /// just reallocated. Unsafe because it trusts old_capacity. - #[inline] - unsafe fn handle_capacity_increase(&mut self, old_capacity: usize) { - let new_capacity = self.capacity(); - debug_assert!(new_capacity >= old_capacity); - - // Move the shortest contiguous section of the ring buffer - // - // H := head - // L := last element (`self.to_physical_idx(self.len - 1)`) - // - // H L - // [o o o o o o o o ] - // H L - // A [o o o o o o o o . . . . . . . . ] - // L H - // [o o o o o o o o ] - // H L - // B [. . . o o o o o o o o . . . . . ] - // L H - // [o o o o o o o o ] - // L H - // C [o o o o o o . . . . . . . . o o ] - - // can't use is_contiguous() because the capacity is already updated. - if self.head <= old_capacity - self.len { - // A - // Nop - } else { - let head_len = old_capacity - self.head; - let tail_len = self.len - head_len; - if head_len > tail_len && new_capacity - old_capacity >= tail_len { - // B - unsafe { - self.copy_nonoverlapping(0, old_capacity, tail_len); - } - } else { - // C - let new_head = new_capacity - head_len; - unsafe { - // can't use copy_nonoverlapping here, because if e.g. head_len = 2 - // and new_capacity = old_capacity + 1, then the heads overlap. - self.copy(self.head, new_head, head_len); - } - self.head = new_head; - } - } - debug_assert!(self.head < self.capacity() || self.capacity() == 0); - } -} - -impl VecDeque { - /// Creates an empty deque. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let deque: VecDeque = VecDeque::new(); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_vec_deque_new", since = "1.68.0")] - #[must_use] - pub const fn new() -> VecDeque { - // FIXME: This should just be `VecDeque::new_in(Global)` once that hits stable. - VecDeque { head: 0, len: 0, buf: RawVec::NEW } - } - - /// Creates an empty deque with space for at least `capacity` elements. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let deque: VecDeque = VecDeque::with_capacity(10); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - pub fn with_capacity(capacity: usize) -> VecDeque { - Self::with_capacity_in(capacity, Global) - } - - /// Creates an empty deque with space for at least `capacity` elements. - /// - /// # Errors - /// - /// Returns an error if the capacity exceeds `isize::MAX` _bytes_, - /// or if the allocator reports allocation failure. - /// - /// # Examples - /// - /// ``` - /// # #![feature(try_with_capacity)] - /// # #[allow(unused)] - /// # fn example() -> Result<(), std::collections::TryReserveError> { - /// use std::collections::VecDeque; - /// - /// let deque: VecDeque = VecDeque::try_with_capacity(10)?; - /// # Ok(()) } - /// ``` - #[inline] - #[unstable(feature = "try_with_capacity", issue = "91913")] - pub fn try_with_capacity(capacity: usize) -> Result, TryReserveError> { - Ok(VecDeque { head: 0, len: 0, buf: RawVec::try_with_capacity_in(capacity, Global)? }) - } -} - -impl VecDeque { - /// Creates an empty deque. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let deque: VecDeque = VecDeque::new(); - /// ``` - #[inline] - #[unstable(feature = "allocator_api", issue = "32838")] - pub const fn new_in(alloc: A) -> VecDeque { - VecDeque { head: 0, len: 0, buf: RawVec::new_in(alloc) } - } - - /// Creates an empty deque with space for at least `capacity` elements. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let deque: VecDeque = VecDeque::with_capacity(10); - /// ``` - #[unstable(feature = "allocator_api", issue = "32838")] - pub fn with_capacity_in(capacity: usize, alloc: A) -> VecDeque { - VecDeque { head: 0, len: 0, buf: RawVec::with_capacity_in(capacity, alloc) } - } - - /// Creates a `VecDeque` from a raw allocation, when the initialized - /// part of that allocation forms a *contiguous* subslice thereof. - /// - /// For use by `vec::IntoIter::into_vecdeque` - /// - /// # Safety - /// - /// All the usual requirements on the allocated memory like in - /// `Vec::from_raw_parts_in`, but takes a *range* of elements that are - /// initialized rather than only supporting `0..len`. Requires that - /// `initialized.start` ≤ `initialized.end` ≤ `capacity`. - #[inline] - pub(crate) unsafe fn from_contiguous_raw_parts_in( - ptr: *mut T, - initialized: Range, - capacity: usize, - alloc: A, - ) -> Self { - debug_assert!(initialized.start <= initialized.end); - debug_assert!(initialized.end <= capacity); - - // SAFETY: Our safety precondition guarantees the range length won't wrap, - // and that the allocation is valid for use in `RawVec`. - unsafe { - VecDeque { - head: initialized.start, - len: initialized.end.unchecked_sub(initialized.start), - buf: RawVec::from_raw_parts_in(ptr, capacity, alloc), - } - } - } - - /// Provides a reference to the element at the given index. - /// - /// Element at index 0 is the front of the queue. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf = VecDeque::new(); - /// buf.push_back(3); - /// buf.push_back(4); - /// buf.push_back(5); - /// buf.push_back(6); - /// assert_eq!(buf.get(1), Some(&4)); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn get(&self, index: usize) -> Option<&T> { - if index < self.len { - let idx = self.to_physical_idx(index); - unsafe { Some(&*self.ptr().add(idx)) } - } else { - None - } - } - - /// Provides a mutable reference to the element at the given index. - /// - /// Element at index 0 is the front of the queue. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf = VecDeque::new(); - /// buf.push_back(3); - /// buf.push_back(4); - /// buf.push_back(5); - /// buf.push_back(6); - /// assert_eq!(buf[1], 4); - /// if let Some(elem) = buf.get_mut(1) { - /// *elem = 7; - /// } - /// assert_eq!(buf[1], 7); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn get_mut(&mut self, index: usize) -> Option<&mut T> { - if index < self.len { - let idx = self.to_physical_idx(index); - unsafe { Some(&mut *self.ptr().add(idx)) } - } else { - None - } - } - - /// Swaps elements at indices `i` and `j`. - /// - /// `i` and `j` may be equal. - /// - /// Element at index 0 is the front of the queue. - /// - /// # Panics - /// - /// Panics if either index is out of bounds. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf = VecDeque::new(); - /// buf.push_back(3); - /// buf.push_back(4); - /// buf.push_back(5); - /// assert_eq!(buf, [3, 4, 5]); - /// buf.swap(0, 2); - /// assert_eq!(buf, [5, 4, 3]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn swap(&mut self, i: usize, j: usize) { - assert!(i < self.len()); - assert!(j < self.len()); - let ri = self.to_physical_idx(i); - let rj = self.to_physical_idx(j); - unsafe { ptr::swap(self.ptr().add(ri), self.ptr().add(rj)) } - } - - /// Returns the number of elements the deque can hold without - /// reallocating. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let buf: VecDeque = VecDeque::with_capacity(10); - /// assert!(buf.capacity() >= 10); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn capacity(&self) -> usize { - if T::IS_ZST { usize::MAX } else { self.buf.capacity() } - } - - /// Reserves the minimum capacity for at least `additional` more elements to be inserted in the - /// given deque. Does nothing if the capacity is already sufficient. - /// - /// Note that the allocator may give the collection more space than it requests. Therefore - /// capacity can not be relied upon to be precisely minimal. Prefer [`reserve`] if future - /// insertions are expected. - /// - /// # Panics - /// - /// Panics if the new capacity overflows `usize`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf: VecDeque = [1].into(); - /// buf.reserve_exact(10); - /// assert!(buf.capacity() >= 11); - /// ``` - /// - /// [`reserve`]: VecDeque::reserve - #[stable(feature = "rust1", since = "1.0.0")] - pub fn reserve_exact(&mut self, additional: usize) { - let new_cap = self.len.checked_add(additional).expect("capacity overflow"); - let old_cap = self.capacity(); - - if new_cap > old_cap { - self.buf.reserve_exact(self.len, additional); - unsafe { - self.handle_capacity_increase(old_cap); - } - } - } - - /// Reserves capacity for at least `additional` more elements to be inserted in the given - /// deque. The collection may reserve more space to speculatively avoid frequent reallocations. - /// - /// # Panics - /// - /// Panics if the new capacity overflows `usize`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf: VecDeque = [1].into(); - /// buf.reserve(10); - /// assert!(buf.capacity() >= 11); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn reserve(&mut self, additional: usize) { - let new_cap = self.len.checked_add(additional).expect("capacity overflow"); - let old_cap = self.capacity(); - - if new_cap > old_cap { - // we don't need to reserve_exact(), as the size doesn't have - // to be a power of 2. - self.buf.reserve(self.len, additional); - unsafe { - self.handle_capacity_increase(old_cap); - } - } - } - - /// Tries to reserve the minimum capacity for at least `additional` more elements to - /// be inserted in the given deque. After calling `try_reserve_exact`, - /// capacity will be greater than or equal to `self.len() + additional` if - /// it returns `Ok(())`. Does nothing if the capacity is already sufficient. - /// - /// Note that the allocator may give the collection more space than it - /// requests. Therefore, capacity can not be relied upon to be precisely - /// minimal. Prefer [`try_reserve`] if future insertions are expected. - /// - /// [`try_reserve`]: VecDeque::try_reserve - /// - /// # Errors - /// - /// If the capacity overflows `usize`, or the allocator reports a failure, then an error - /// is returned. - /// - /// # Examples - /// - /// ``` - /// use std::collections::TryReserveError; - /// use std::collections::VecDeque; - /// - /// fn process_data(data: &[u32]) -> Result, TryReserveError> { - /// let mut output = VecDeque::new(); - /// - /// // Pre-reserve the memory, exiting if we can't - /// output.try_reserve_exact(data.len())?; - /// - /// // Now we know this can't OOM(Out-Of-Memory) in the middle of our complex work - /// output.extend(data.iter().map(|&val| { - /// val * 2 + 5 // very complicated - /// })); - /// - /// Ok(output) - /// } - /// # process_data(&[1, 2, 3]).expect("why is the test harness OOMing on 12 bytes?"); - /// ``` - #[stable(feature = "try_reserve", since = "1.57.0")] - pub fn try_reserve_exact(&mut self, additional: usize) -> Result<(), TryReserveError> { - let new_cap = - self.len.checked_add(additional).ok_or(TryReserveErrorKind::CapacityOverflow)?; - let old_cap = self.capacity(); - - if new_cap > old_cap { - self.buf.try_reserve_exact(self.len, additional)?; - unsafe { - self.handle_capacity_increase(old_cap); - } - } - Ok(()) - } - - /// Tries to reserve capacity for at least `additional` more elements to be inserted - /// in the given deque. The collection may reserve more space to speculatively avoid - /// frequent reallocations. After calling `try_reserve`, capacity will be - /// greater than or equal to `self.len() + additional` if it returns - /// `Ok(())`. Does nothing if capacity is already sufficient. This method - /// preserves the contents even if an error occurs. - /// - /// # Errors - /// - /// If the capacity overflows `usize`, or the allocator reports a failure, then an error - /// is returned. - /// - /// # Examples - /// - /// ``` - /// use std::collections::TryReserveError; - /// use std::collections::VecDeque; - /// - /// fn process_data(data: &[u32]) -> Result, TryReserveError> { - /// let mut output = VecDeque::new(); - /// - /// // Pre-reserve the memory, exiting if we can't - /// output.try_reserve(data.len())?; - /// - /// // Now we know this can't OOM in the middle of our complex work - /// output.extend(data.iter().map(|&val| { - /// val * 2 + 5 // very complicated - /// })); - /// - /// Ok(output) - /// } - /// # process_data(&[1, 2, 3]).expect("why is the test harness OOMing on 12 bytes?"); - /// ``` - #[stable(feature = "try_reserve", since = "1.57.0")] - pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> { - let new_cap = - self.len.checked_add(additional).ok_or(TryReserveErrorKind::CapacityOverflow)?; - let old_cap = self.capacity(); - - if new_cap > old_cap { - self.buf.try_reserve(self.len, additional)?; - unsafe { - self.handle_capacity_increase(old_cap); - } - } - Ok(()) - } - - /// Shrinks the capacity of the deque as much as possible. - /// - /// It will drop down as close as possible to the length but the allocator may still inform the - /// deque that there is space for a few more elements. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf = VecDeque::with_capacity(15); - /// buf.extend(0..4); - /// assert_eq!(buf.capacity(), 15); - /// buf.shrink_to_fit(); - /// assert!(buf.capacity() >= 4); - /// ``` - #[stable(feature = "deque_extras_15", since = "1.5.0")] - pub fn shrink_to_fit(&mut self) { - self.shrink_to(0); - } - - /// Shrinks the capacity of the deque with a lower bound. - /// - /// The capacity will remain at least as large as both the length - /// and the supplied value. - /// - /// If the current capacity is less than the lower limit, this is a no-op. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf = VecDeque::with_capacity(15); - /// buf.extend(0..4); - /// assert_eq!(buf.capacity(), 15); - /// buf.shrink_to(6); - /// assert!(buf.capacity() >= 6); - /// buf.shrink_to(0); - /// assert!(buf.capacity() >= 4); - /// ``` - #[stable(feature = "shrink_to", since = "1.56.0")] - pub fn shrink_to(&mut self, min_capacity: usize) { - let target_cap = min_capacity.max(self.len); - - // never shrink ZSTs - if T::IS_ZST || self.capacity() <= target_cap { - return; - } - - // There are three cases of interest: - // All elements are out of desired bounds - // Elements are contiguous, and tail is out of desired bounds - // Elements are discontiguous - // - // At all other times, element positions are unaffected. - - // `head` and `len` are at most `isize::MAX` and `target_cap < self.capacity()`, so nothing can - // overflow. - let tail_outside = (target_cap + 1..=self.capacity()).contains(&(self.head + self.len)); - - if self.len == 0 { - self.head = 0; - } else if self.head >= target_cap && tail_outside { - // Head and tail are both out of bounds, so copy all of them to the front. - // - // H := head - // L := last element - // H L - // [. . . . . . . . o o o o o o o . ] - // H L - // [o o o o o o o . ] - unsafe { - // nonoverlapping because `self.head >= target_cap >= self.len`. - self.copy_nonoverlapping(self.head, 0, self.len); - } - self.head = 0; - } else if self.head < target_cap && tail_outside { - // Head is in bounds, tail is out of bounds. - // Copy the overflowing part to the beginning of the - // buffer. This won't overlap because `target_cap >= self.len`. - // - // H := head - // L := last element - // H L - // [. . . o o o o o o o . . . . . . ] - // L H - // [o o . o o o o o ] - let len = self.head + self.len - target_cap; - unsafe { - self.copy_nonoverlapping(target_cap, 0, len); - } - } else if !self.is_contiguous() { - // The head slice is at least partially out of bounds, tail is in bounds. - // Copy the head backwards so it lines up with the target capacity. - // This won't overlap because `target_cap >= self.len`. - // - // H := head - // L := last element - // L H - // [o o o o o . . . . . . . . . o o ] - // L H - // [o o o o o . o o ] - let head_len = self.capacity() - self.head; - let new_head = target_cap - head_len; - unsafe { - // can't use `copy_nonoverlapping()` here because the new and old - // regions for the head might overlap. - self.copy(self.head, new_head, head_len); - } - self.head = new_head; - } - self.buf.shrink_to_fit(target_cap); - - debug_assert!(self.head < self.capacity() || self.capacity() == 0); - debug_assert!(self.len <= self.capacity()); - } - - /// Shortens the deque, keeping the first `len` elements and dropping - /// the rest. - /// - /// If `len` is greater or equal to the deque's current length, this has - /// no effect. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf = VecDeque::new(); - /// buf.push_back(5); - /// buf.push_back(10); - /// buf.push_back(15); - /// assert_eq!(buf, [5, 10, 15]); - /// buf.truncate(1); - /// assert_eq!(buf, [5]); - /// ``` - #[stable(feature = "deque_extras", since = "1.16.0")] - pub fn truncate(&mut self, len: usize) { - /// Runs the destructor for all items in the slice when it gets dropped (normally or - /// during unwinding). - struct Dropper<'a, T>(&'a mut [T]); - - impl<'a, T> Drop for Dropper<'a, T> { - fn drop(&mut self) { - unsafe { - ptr::drop_in_place(self.0); - } - } - } - - // Safe because: - // - // * Any slice passed to `drop_in_place` is valid; the second case has - // `len <= front.len()` and returning on `len > self.len()` ensures - // `begin <= back.len()` in the first case - // * The head of the VecDeque is moved before calling `drop_in_place`, - // so no value is dropped twice if `drop_in_place` panics - unsafe { - if len >= self.len { - return; - } - - let (front, back) = self.as_mut_slices(); - if len > front.len() { - let begin = len - front.len(); - let drop_back = back.get_unchecked_mut(begin..) as *mut _; - self.len = len; - ptr::drop_in_place(drop_back); - } else { - let drop_back = back as *mut _; - let drop_front = front.get_unchecked_mut(len..) as *mut _; - self.len = len; - - // Make sure the second half is dropped even when a destructor - // in the first one panics. - let _back_dropper = Dropper(&mut *drop_back); - ptr::drop_in_place(drop_front); - } - } - } - - /// Returns a reference to the underlying allocator. - #[unstable(feature = "allocator_api", issue = "32838")] - #[inline] - pub fn allocator(&self) -> &A { - self.buf.allocator() - } - - /// Returns a front-to-back iterator. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf = VecDeque::new(); - /// buf.push_back(5); - /// buf.push_back(3); - /// buf.push_back(4); - /// let b: &[_] = &[&5, &3, &4]; - /// let c: Vec<&i32> = buf.iter().collect(); - /// assert_eq!(&c[..], b); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn iter(&self) -> Iter<'_, T> { - let (a, b) = self.as_slices(); - Iter::new(a.iter(), b.iter()) - } - - /// Returns a front-to-back iterator that returns mutable references. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf = VecDeque::new(); - /// buf.push_back(5); - /// buf.push_back(3); - /// buf.push_back(4); - /// for num in buf.iter_mut() { - /// *num = *num - 2; - /// } - /// let b: &[_] = &[&mut 3, &mut 1, &mut 2]; - /// assert_eq!(&buf.iter_mut().collect::>()[..], b); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn iter_mut(&mut self) -> IterMut<'_, T> { - let (a, b) = self.as_mut_slices(); - IterMut::new(a.iter_mut(), b.iter_mut()) - } - - /// Returns a pair of slices which contain, in order, the contents of the - /// deque. - /// - /// If [`make_contiguous`] was previously called, all elements of the - /// deque will be in the first slice and the second slice will be empty. - /// - /// [`make_contiguous`]: VecDeque::make_contiguous - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut deque = VecDeque::new(); - /// - /// deque.push_back(0); - /// deque.push_back(1); - /// deque.push_back(2); - /// - /// assert_eq!(deque.as_slices(), (&[0, 1, 2][..], &[][..])); - /// - /// deque.push_front(10); - /// deque.push_front(9); - /// - /// assert_eq!(deque.as_slices(), (&[9, 10][..], &[0, 1, 2][..])); - /// ``` - #[inline] - #[stable(feature = "deque_extras_15", since = "1.5.0")] - pub fn as_slices(&self) -> (&[T], &[T]) { - let (a_range, b_range) = self.slice_ranges(.., self.len); - // SAFETY: `slice_ranges` always returns valid ranges into - // the physical buffer. - unsafe { (&*self.buffer_range(a_range), &*self.buffer_range(b_range)) } - } - - /// Returns a pair of slices which contain, in order, the contents of the - /// deque. - /// - /// If [`make_contiguous`] was previously called, all elements of the - /// deque will be in the first slice and the second slice will be empty. - /// - /// [`make_contiguous`]: VecDeque::make_contiguous - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut deque = VecDeque::new(); - /// - /// deque.push_back(0); - /// deque.push_back(1); - /// - /// deque.push_front(10); - /// deque.push_front(9); - /// - /// deque.as_mut_slices().0[0] = 42; - /// deque.as_mut_slices().1[0] = 24; - /// assert_eq!(deque.as_slices(), (&[42, 10][..], &[24, 1][..])); - /// ``` - #[inline] - #[stable(feature = "deque_extras_15", since = "1.5.0")] - pub fn as_mut_slices(&mut self) -> (&mut [T], &mut [T]) { - let (a_range, b_range) = self.slice_ranges(.., self.len); - // SAFETY: `slice_ranges` always returns valid ranges into - // the physical buffer. - unsafe { (&mut *self.buffer_range(a_range), &mut *self.buffer_range(b_range)) } - } - - /// Returns the number of elements in the deque. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut deque = VecDeque::new(); - /// assert_eq!(deque.len(), 0); - /// deque.push_back(1); - /// assert_eq!(deque.len(), 1); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("length", "size")] - pub fn len(&self) -> usize { - self.len - } - - /// Returns `true` if the deque is empty. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut deque = VecDeque::new(); - /// assert!(deque.is_empty()); - /// deque.push_front(1); - /// assert!(!deque.is_empty()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn is_empty(&self) -> bool { - self.len == 0 - } - - /// Given a range into the logical buffer of the deque, this function - /// return two ranges into the physical buffer that correspond to - /// the given range. The `len` parameter should usually just be `self.len`; - /// the reason it's passed explicitly is that if the deque is wrapped in - /// a `Drain`, then `self.len` is not actually the length of the deque. - /// - /// # Safety - /// - /// This function is always safe to call. For the resulting ranges to be valid - /// ranges into the physical buffer, the caller must ensure that the result of - /// calling `slice::range(range, ..len)` represents a valid range into the - /// logical buffer, and that all elements in that range are initialized. - fn slice_ranges(&self, range: R, len: usize) -> (Range, Range) - where - R: RangeBounds, - { - let Range { start, end } = slice::range(range, ..len); - let len = end - start; - - if len == 0 { - (0..0, 0..0) - } else { - // `slice::range` guarantees that `start <= end <= len`. - // because `len != 0`, we know that `start < end`, so `start < len` - // and the indexing is valid. - let wrapped_start = self.to_physical_idx(start); - - // this subtraction can never overflow because `wrapped_start` is - // at most `self.capacity()` (and if `self.capacity != 0`, then `wrapped_start` is strictly less - // than `self.capacity`). - let head_len = self.capacity() - wrapped_start; - - if head_len >= len { - // we know that `len + wrapped_start <= self.capacity <= usize::MAX`, so this addition can't overflow - (wrapped_start..wrapped_start + len, 0..0) - } else { - // can't overflow because of the if condition - let tail_len = len - head_len; - (wrapped_start..self.capacity(), 0..tail_len) - } - } - } - - /// Creates an iterator that covers the specified range in the deque. - /// - /// # Panics - /// - /// Panics if the starting point is greater than the end point or if - /// the end point is greater than the length of the deque. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let deque: VecDeque<_> = [1, 2, 3].into(); - /// let range = deque.range(2..).copied().collect::>(); - /// assert_eq!(range, [3]); - /// - /// // A full range covers all contents - /// let all = deque.range(..); - /// assert_eq!(all.len(), 3); - /// ``` - #[inline] - #[stable(feature = "deque_range", since = "1.51.0")] - pub fn range(&self, range: R) -> Iter<'_, T> - where - R: RangeBounds, - { - let (a_range, b_range) = self.slice_ranges(range, self.len); - // SAFETY: The ranges returned by `slice_ranges` - // are valid ranges into the physical buffer, so - // it's ok to pass them to `buffer_range` and - // dereference the result. - let a = unsafe { &*self.buffer_range(a_range) }; - let b = unsafe { &*self.buffer_range(b_range) }; - Iter::new(a.iter(), b.iter()) - } - - /// Creates an iterator that covers the specified mutable range in the deque. - /// - /// # Panics - /// - /// Panics if the starting point is greater than the end point or if - /// the end point is greater than the length of the deque. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut deque: VecDeque<_> = [1, 2, 3].into(); - /// for v in deque.range_mut(2..) { - /// *v *= 2; - /// } - /// assert_eq!(deque, [1, 2, 6]); - /// - /// // A full range covers all contents - /// for v in deque.range_mut(..) { - /// *v *= 2; - /// } - /// assert_eq!(deque, [2, 4, 12]); - /// ``` - #[inline] - #[stable(feature = "deque_range", since = "1.51.0")] - pub fn range_mut(&mut self, range: R) -> IterMut<'_, T> - where - R: RangeBounds, - { - let (a_range, b_range) = self.slice_ranges(range, self.len); - // SAFETY: The ranges returned by `slice_ranges` - // are valid ranges into the physical buffer, so - // it's ok to pass them to `buffer_range` and - // dereference the result. - let a = unsafe { &mut *self.buffer_range(a_range) }; - let b = unsafe { &mut *self.buffer_range(b_range) }; - IterMut::new(a.iter_mut(), b.iter_mut()) - } - - /// Removes the specified range from the deque in bulk, returning all - /// removed elements as an iterator. If the iterator is dropped before - /// being fully consumed, it drops the remaining removed elements. - /// - /// The returned iterator keeps a mutable borrow on the queue to optimize - /// its implementation. - /// - /// - /// # Panics - /// - /// Panics if the starting point is greater than the end point or if - /// the end point is greater than the length of the deque. - /// - /// # Leaking - /// - /// If the returned iterator goes out of scope without being dropped (due to - /// [`mem::forget`], for example), the deque may have lost and leaked - /// elements arbitrarily, including elements outside the range. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut deque: VecDeque<_> = [1, 2, 3].into(); - /// let drained = deque.drain(2..).collect::>(); - /// assert_eq!(drained, [3]); - /// assert_eq!(deque, [1, 2]); - /// - /// // A full range clears all contents, like `clear()` does - /// deque.drain(..); - /// assert!(deque.is_empty()); - /// ``` - #[inline] - #[stable(feature = "drain", since = "1.6.0")] - pub fn drain(&mut self, range: R) -> Drain<'_, T, A> - where - R: RangeBounds, - { - // Memory safety - // - // When the Drain is first created, the source deque is shortened to - // make sure no uninitialized or moved-from elements are accessible at - // all if the Drain's destructor never gets to run. - // - // Drain will ptr::read out the values to remove. - // When finished, the remaining data will be copied back to cover the hole, - // and the head/tail values will be restored correctly. - // - let Range { start, end } = slice::range(range, ..self.len); - let drain_start = start; - let drain_len = end - start; - - // The deque's elements are parted into three segments: - // * 0 -> drain_start - // * drain_start -> drain_start+drain_len - // * drain_start+drain_len -> self.len - // - // H = self.head; T = self.head+self.len; t = drain_start+drain_len; h = drain_head - // - // We store drain_start as self.len, and drain_len and self.len as - // drain_len and orig_len respectively on the Drain. This also - // truncates the effective array such that if the Drain is leaked, we - // have forgotten about the potentially moved values after the start of - // the drain. - // - // H h t T - // [. . . o o x x o o . . .] - // - // "forget" about the values after the start of the drain until after - // the drain is complete and the Drain destructor is run. - - unsafe { Drain::new(self, drain_start, drain_len) } - } - - /// Clears the deque, removing all values. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut deque = VecDeque::new(); - /// deque.push_back(1); - /// deque.clear(); - /// assert!(deque.is_empty()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn clear(&mut self) { - self.truncate(0); - // Not strictly necessary, but leaves things in a more consistent/predictable state. - self.head = 0; - } - - /// Returns `true` if the deque contains an element equal to the - /// given value. - /// - /// This operation is *O*(*n*). - /// - /// Note that if you have a sorted `VecDeque`, [`binary_search`] may be faster. - /// - /// [`binary_search`]: VecDeque::binary_search - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut deque: VecDeque = VecDeque::new(); - /// - /// deque.push_back(0); - /// deque.push_back(1); - /// - /// assert_eq!(deque.contains(&1), true); - /// assert_eq!(deque.contains(&10), false); - /// ``` - #[stable(feature = "vec_deque_contains", since = "1.12.0")] - pub fn contains(&self, x: &T) -> bool - where - T: PartialEq, - { - let (a, b) = self.as_slices(); - a.contains(x) || b.contains(x) - } - - /// Provides a reference to the front element, or `None` if the deque is - /// empty. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut d = VecDeque::new(); - /// assert_eq!(d.front(), None); - /// - /// d.push_back(1); - /// d.push_back(2); - /// assert_eq!(d.front(), Some(&1)); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("first")] - pub fn front(&self) -> Option<&T> { - self.get(0) - } - - /// Provides a mutable reference to the front element, or `None` if the - /// deque is empty. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut d = VecDeque::new(); - /// assert_eq!(d.front_mut(), None); - /// - /// d.push_back(1); - /// d.push_back(2); - /// match d.front_mut() { - /// Some(x) => *x = 9, - /// None => (), - /// } - /// assert_eq!(d.front(), Some(&9)); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn front_mut(&mut self) -> Option<&mut T> { - self.get_mut(0) - } - - /// Provides a reference to the back element, or `None` if the deque is - /// empty. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut d = VecDeque::new(); - /// assert_eq!(d.back(), None); - /// - /// d.push_back(1); - /// d.push_back(2); - /// assert_eq!(d.back(), Some(&2)); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("last")] - pub fn back(&self) -> Option<&T> { - self.get(self.len.wrapping_sub(1)) - } - - /// Provides a mutable reference to the back element, or `None` if the - /// deque is empty. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut d = VecDeque::new(); - /// assert_eq!(d.back(), None); - /// - /// d.push_back(1); - /// d.push_back(2); - /// match d.back_mut() { - /// Some(x) => *x = 9, - /// None => (), - /// } - /// assert_eq!(d.back(), Some(&9)); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn back_mut(&mut self) -> Option<&mut T> { - self.get_mut(self.len.wrapping_sub(1)) - } - - /// Removes the first element and returns it, or `None` if the deque is - /// empty. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut d = VecDeque::new(); - /// d.push_back(1); - /// d.push_back(2); - /// - /// assert_eq!(d.pop_front(), Some(1)); - /// assert_eq!(d.pop_front(), Some(2)); - /// assert_eq!(d.pop_front(), None); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn pop_front(&mut self) -> Option { - if self.is_empty() { - None - } else { - let old_head = self.head; - self.head = self.to_physical_idx(1); - self.len -= 1; - unsafe { - core::hint::assert_unchecked(self.len < self.capacity()); - Some(self.buffer_read(old_head)) - } - } - } - - /// Removes the last element from the deque and returns it, or `None` if - /// it is empty. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf = VecDeque::new(); - /// assert_eq!(buf.pop_back(), None); - /// buf.push_back(1); - /// buf.push_back(3); - /// assert_eq!(buf.pop_back(), Some(3)); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn pop_back(&mut self) -> Option { - if self.is_empty() { - None - } else { - self.len -= 1; - unsafe { - core::hint::assert_unchecked(self.len < self.capacity()); - Some(self.buffer_read(self.to_physical_idx(self.len))) - } - } - } - - /// Prepends an element to the deque. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut d = VecDeque::new(); - /// d.push_front(1); - /// d.push_front(2); - /// assert_eq!(d.front(), Some(&2)); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn push_front(&mut self, value: T) { - if self.is_full() { - self.grow(); - } - - self.head = self.wrap_sub(self.head, 1); - self.len += 1; - - unsafe { - self.buffer_write(self.head, value); - } - } - - /// Appends an element to the back of the deque. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf = VecDeque::new(); - /// buf.push_back(1); - /// buf.push_back(3); - /// assert_eq!(3, *buf.back().unwrap()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("push", "put", "append")] - pub fn push_back(&mut self, value: T) { - if self.is_full() { - self.grow(); - } - - unsafe { self.buffer_write(self.to_physical_idx(self.len), value) } - self.len += 1; - } - - #[inline] - fn is_contiguous(&self) -> bool { - // Do the calculation like this to avoid overflowing if len + head > usize::MAX - self.head <= self.capacity() - self.len - } - - /// Removes an element from anywhere in the deque and returns it, - /// replacing it with the first element. - /// - /// This does not preserve ordering, but is *O*(1). - /// - /// Returns `None` if `index` is out of bounds. - /// - /// Element at index 0 is the front of the queue. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf = VecDeque::new(); - /// assert_eq!(buf.swap_remove_front(0), None); - /// buf.push_back(1); - /// buf.push_back(2); - /// buf.push_back(3); - /// assert_eq!(buf, [1, 2, 3]); - /// - /// assert_eq!(buf.swap_remove_front(2), Some(3)); - /// assert_eq!(buf, [2, 1]); - /// ``` - #[stable(feature = "deque_extras_15", since = "1.5.0")] - pub fn swap_remove_front(&mut self, index: usize) -> Option { - let length = self.len; - if index < length && index != 0 { - self.swap(index, 0); - } else if index >= length { - return None; - } - self.pop_front() - } - - /// Removes an element from anywhere in the deque and returns it, - /// replacing it with the last element. - /// - /// This does not preserve ordering, but is *O*(1). - /// - /// Returns `None` if `index` is out of bounds. - /// - /// Element at index 0 is the front of the queue. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf = VecDeque::new(); - /// assert_eq!(buf.swap_remove_back(0), None); - /// buf.push_back(1); - /// buf.push_back(2); - /// buf.push_back(3); - /// assert_eq!(buf, [1, 2, 3]); - /// - /// assert_eq!(buf.swap_remove_back(0), Some(1)); - /// assert_eq!(buf, [3, 2]); - /// ``` - #[stable(feature = "deque_extras_15", since = "1.5.0")] - pub fn swap_remove_back(&mut self, index: usize) -> Option { - let length = self.len; - if length > 0 && index < length - 1 { - self.swap(index, length - 1); - } else if index >= length { - return None; - } - self.pop_back() - } - - /// Inserts an element at `index` within the deque, shifting all elements - /// with indices greater than or equal to `index` towards the back. - /// - /// Element at index 0 is the front of the queue. - /// - /// # Panics - /// - /// Panics if `index` is greater than deque's length - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut vec_deque = VecDeque::new(); - /// vec_deque.push_back('a'); - /// vec_deque.push_back('b'); - /// vec_deque.push_back('c'); - /// assert_eq!(vec_deque, &['a', 'b', 'c']); - /// - /// vec_deque.insert(1, 'd'); - /// assert_eq!(vec_deque, &['a', 'd', 'b', 'c']); - /// ``` - #[stable(feature = "deque_extras_15", since = "1.5.0")] - pub fn insert(&mut self, index: usize, value: T) { - assert!(index <= self.len(), "index out of bounds"); - if self.is_full() { - self.grow(); - } - - let k = self.len - index; - if k < index { - // `index + 1` can't overflow, because if index was usize::MAX, then either the - // assert would've failed, or the deque would've tried to grow past usize::MAX - // and panicked. - unsafe { - // see `remove()` for explanation why this wrap_copy() call is safe. - self.wrap_copy(self.to_physical_idx(index), self.to_physical_idx(index + 1), k); - self.buffer_write(self.to_physical_idx(index), value); - self.len += 1; - } - } else { - let old_head = self.head; - self.head = self.wrap_sub(self.head, 1); - unsafe { - self.wrap_copy(old_head, self.head, index); - self.buffer_write(self.to_physical_idx(index), value); - self.len += 1; - } - } - } - - /// Removes and returns the element at `index` from the deque. - /// Whichever end is closer to the removal point will be moved to make - /// room, and all the affected elements will be moved to new positions. - /// Returns `None` if `index` is out of bounds. - /// - /// Element at index 0 is the front of the queue. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf = VecDeque::new(); - /// buf.push_back(1); - /// buf.push_back(2); - /// buf.push_back(3); - /// assert_eq!(buf, [1, 2, 3]); - /// - /// assert_eq!(buf.remove(1), Some(2)); - /// assert_eq!(buf, [1, 3]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("delete", "take")] - pub fn remove(&mut self, index: usize) -> Option { - if self.len <= index { - return None; - } - - let wrapped_idx = self.to_physical_idx(index); - - let elem = unsafe { Some(self.buffer_read(wrapped_idx)) }; - - let k = self.len - index - 1; - // safety: due to the nature of the if-condition, whichever wrap_copy gets called, - // its length argument will be at most `self.len / 2`, so there can't be more than - // one overlapping area. - if k < index { - unsafe { self.wrap_copy(self.wrap_add(wrapped_idx, 1), wrapped_idx, k) }; - self.len -= 1; - } else { - let old_head = self.head; - self.head = self.to_physical_idx(1); - unsafe { self.wrap_copy(old_head, self.head, index) }; - self.len -= 1; - } - - elem - } - - /// Splits the deque into two at the given index. - /// - /// Returns a newly allocated `VecDeque`. `self` contains elements `[0, at)`, - /// and the returned deque contains elements `[at, len)`. - /// - /// Note that the capacity of `self` does not change. - /// - /// Element at index 0 is the front of the queue. - /// - /// # Panics - /// - /// Panics if `at > len`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf: VecDeque<_> = [1, 2, 3].into(); - /// let buf2 = buf.split_off(1); - /// assert_eq!(buf, [1]); - /// assert_eq!(buf2, [2, 3]); - /// ``` - #[inline] - #[must_use = "use `.truncate()` if you don't need the other half"] - #[stable(feature = "split_off", since = "1.4.0")] - pub fn split_off(&mut self, at: usize) -> Self - where - A: Clone, - { - let len = self.len; - assert!(at <= len, "`at` out of bounds"); - - let other_len = len - at; - let mut other = VecDeque::with_capacity_in(other_len, self.allocator().clone()); - - unsafe { - let (first_half, second_half) = self.as_slices(); - - let first_len = first_half.len(); - let second_len = second_half.len(); - if at < first_len { - // `at` lies in the first half. - let amount_in_first = first_len - at; - - ptr::copy_nonoverlapping(first_half.as_ptr().add(at), other.ptr(), amount_in_first); - - // just take all of the second half. - ptr::copy_nonoverlapping( - second_half.as_ptr(), - other.ptr().add(amount_in_first), - second_len, - ); - } else { - // `at` lies in the second half, need to factor in the elements we skipped - // in the first half. - let offset = at - first_len; - let amount_in_second = second_len - offset; - ptr::copy_nonoverlapping( - second_half.as_ptr().add(offset), - other.ptr(), - amount_in_second, - ); - } - } - - // Cleanup where the ends of the buffers are - self.len = at; - other.len = other_len; - - other - } - - /// Moves all the elements of `other` into `self`, leaving `other` empty. - /// - /// # Panics - /// - /// Panics if the new number of elements in self overflows a `usize`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf: VecDeque<_> = [1, 2].into(); - /// let mut buf2: VecDeque<_> = [3, 4].into(); - /// buf.append(&mut buf2); - /// assert_eq!(buf, [1, 2, 3, 4]); - /// assert_eq!(buf2, []); - /// ``` - #[inline] - #[stable(feature = "append", since = "1.4.0")] - pub fn append(&mut self, other: &mut Self) { - if T::IS_ZST { - self.len = self.len.checked_add(other.len).expect("capacity overflow"); - other.len = 0; - other.head = 0; - return; - } - - self.reserve(other.len); - unsafe { - let (left, right) = other.as_slices(); - self.copy_slice(self.to_physical_idx(self.len), left); - // no overflow, because self.capacity() >= old_cap + left.len() >= self.len + left.len() - self.copy_slice(self.to_physical_idx(self.len + left.len()), right); - } - // SAFETY: Update pointers after copying to avoid leaving doppelganger - // in case of panics. - self.len += other.len; - // Now that we own its values, forget everything in `other`. - other.len = 0; - other.head = 0; - } - - /// Retains only the elements specified by the predicate. - /// - /// In other words, remove all elements `e` for which `f(&e)` returns false. - /// This method operates in place, visiting each element exactly once in the - /// original order, and preserves the order of the retained elements. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf = VecDeque::new(); - /// buf.extend(1..5); - /// buf.retain(|&x| x % 2 == 0); - /// assert_eq!(buf, [2, 4]); - /// ``` - /// - /// Because the elements are visited exactly once in the original order, - /// external state may be used to decide which elements to keep. - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf = VecDeque::new(); - /// buf.extend(1..6); - /// - /// let keep = [false, true, true, false, true]; - /// let mut iter = keep.iter(); - /// buf.retain(|_| *iter.next().unwrap()); - /// assert_eq!(buf, [2, 3, 5]); - /// ``` - #[stable(feature = "vec_deque_retain", since = "1.4.0")] - pub fn retain(&mut self, mut f: F) - where - F: FnMut(&T) -> bool, - { - self.retain_mut(|elem| f(elem)); - } - - /// Retains only the elements specified by the predicate. - /// - /// In other words, remove all elements `e` for which `f(&e)` returns false. - /// This method operates in place, visiting each element exactly once in the - /// original order, and preserves the order of the retained elements. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf = VecDeque::new(); - /// buf.extend(1..5); - /// buf.retain_mut(|x| if *x % 2 == 0 { - /// *x += 1; - /// true - /// } else { - /// false - /// }); - /// assert_eq!(buf, [3, 5]); - /// ``` - #[stable(feature = "vec_retain_mut", since = "1.61.0")] - pub fn retain_mut(&mut self, mut f: F) - where - F: FnMut(&mut T) -> bool, - { - let len = self.len; - let mut idx = 0; - let mut cur = 0; - - // Stage 1: All values are retained. - while cur < len { - if !f(&mut self[cur]) { - cur += 1; - break; - } - cur += 1; - idx += 1; - } - // Stage 2: Swap retained value into current idx. - while cur < len { - if !f(&mut self[cur]) { - cur += 1; - continue; - } - - self.swap(idx, cur); - cur += 1; - idx += 1; - } - // Stage 3: Truncate all values after idx. - if cur != idx { - self.truncate(idx); - } - } - - // Double the buffer size. This method is inline(never), so we expect it to only - // be called in cold paths. - // This may panic or abort - #[inline(never)] - fn grow(&mut self) { - // Extend or possibly remove this assertion when valid use-cases for growing the - // buffer without it being full emerge - debug_assert!(self.is_full()); - let old_cap = self.capacity(); - self.buf.grow_one(); - unsafe { - self.handle_capacity_increase(old_cap); - } - debug_assert!(!self.is_full()); - } - - /// Modifies the deque in-place so that `len()` is equal to `new_len`, - /// either by removing excess elements from the back or by appending - /// elements generated by calling `generator` to the back. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf = VecDeque::new(); - /// buf.push_back(5); - /// buf.push_back(10); - /// buf.push_back(15); - /// assert_eq!(buf, [5, 10, 15]); - /// - /// buf.resize_with(5, Default::default); - /// assert_eq!(buf, [5, 10, 15, 0, 0]); - /// - /// buf.resize_with(2, || unreachable!()); - /// assert_eq!(buf, [5, 10]); - /// - /// let mut state = 100; - /// buf.resize_with(5, || { state += 1; state }); - /// assert_eq!(buf, [5, 10, 101, 102, 103]); - /// ``` - #[stable(feature = "vec_resize_with", since = "1.33.0")] - pub fn resize_with(&mut self, new_len: usize, generator: impl FnMut() -> T) { - let len = self.len; - - if new_len > len { - self.extend(repeat_with(generator).take(new_len - len)) - } else { - self.truncate(new_len); - } - } - - /// Rearranges the internal storage of this deque so it is one contiguous - /// slice, which is then returned. - /// - /// This method does not allocate and does not change the order of the - /// inserted elements. As it returns a mutable slice, this can be used to - /// sort a deque. - /// - /// Once the internal storage is contiguous, the [`as_slices`] and - /// [`as_mut_slices`] methods will return the entire contents of the - /// deque in a single slice. - /// - /// [`as_slices`]: VecDeque::as_slices - /// [`as_mut_slices`]: VecDeque::as_mut_slices - /// - /// # Examples - /// - /// Sorting the content of a deque. - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf = VecDeque::with_capacity(15); - /// - /// buf.push_back(2); - /// buf.push_back(1); - /// buf.push_front(3); - /// - /// // sorting the deque - /// buf.make_contiguous().sort(); - /// assert_eq!(buf.as_slices(), (&[1, 2, 3] as &[_], &[] as &[_])); - /// - /// // sorting it in reverse order - /// buf.make_contiguous().sort_by(|a, b| b.cmp(a)); - /// assert_eq!(buf.as_slices(), (&[3, 2, 1] as &[_], &[] as &[_])); - /// ``` - /// - /// Getting immutable access to the contiguous slice. - /// - /// ```rust - /// use std::collections::VecDeque; - /// - /// let mut buf = VecDeque::new(); - /// - /// buf.push_back(2); - /// buf.push_back(1); - /// buf.push_front(3); - /// - /// buf.make_contiguous(); - /// if let (slice, &[]) = buf.as_slices() { - /// // we can now be sure that `slice` contains all elements of the deque, - /// // while still having immutable access to `buf`. - /// assert_eq!(buf.len(), slice.len()); - /// assert_eq!(slice, &[3, 2, 1] as &[_]); - /// } - /// ``` - #[stable(feature = "deque_make_contiguous", since = "1.48.0")] - pub fn make_contiguous(&mut self) -> &mut [T] { - if T::IS_ZST { - self.head = 0; - } - - if self.is_contiguous() { - unsafe { return slice::from_raw_parts_mut(self.ptr().add(self.head), self.len) } - } - - let &mut Self { head, len, .. } = self; - let ptr = self.ptr(); - let cap = self.capacity(); - - let free = cap - len; - let head_len = cap - head; - let tail = len - head_len; - let tail_len = tail; - - if free >= head_len { - // there is enough free space to copy the head in one go, - // this means that we first shift the tail backwards, and then - // copy the head to the correct position. - // - // from: DEFGH....ABC - // to: ABCDEFGH.... - unsafe { - self.copy(0, head_len, tail_len); - // ...DEFGH.ABC - self.copy_nonoverlapping(head, 0, head_len); - // ABCDEFGH.... - } - - self.head = 0; - } else if free >= tail_len { - // there is enough free space to copy the tail in one go, - // this means that we first shift the head forwards, and then - // copy the tail to the correct position. - // - // from: FGH....ABCDE - // to: ...ABCDEFGH. - unsafe { - self.copy(head, tail, head_len); - // FGHABCDE.... - self.copy_nonoverlapping(0, tail + head_len, tail_len); - // ...ABCDEFGH. - } - - self.head = tail; - } else { - // `free` is smaller than both `head_len` and `tail_len`. - // the general algorithm for this first moves the slices - // right next to each other and then uses `slice::rotate` - // to rotate them into place: - // - // initially: HIJK..ABCDEFG - // step 1: ..HIJKABCDEFG - // step 2: ..ABCDEFGHIJK - // - // or: - // - // initially: FGHIJK..ABCDE - // step 1: FGHIJKABCDE.. - // step 2: ABCDEFGHIJK.. - - // pick the shorter of the 2 slices to reduce the amount - // of memory that needs to be moved around. - if head_len > tail_len { - // tail is shorter, so: - // 1. copy tail forwards - // 2. rotate used part of the buffer - // 3. update head to point to the new beginning (which is just `free`) - - unsafe { - // if there is no free space in the buffer, then the slices are already - // right next to each other and we don't need to move any memory. - if free != 0 { - // because we only move the tail forward as much as there's free space - // behind it, we don't overwrite any elements of the head slice, and - // the slices end up right next to each other. - self.copy(0, free, tail_len); - } - - // We just copied the tail right next to the head slice, - // so all of the elements in the range are initialized - let slice = &mut *self.buffer_range(free..self.capacity()); - - // because the deque wasn't contiguous, we know that `tail_len < self.len == slice.len()`, - // so this will never panic. - slice.rotate_left(tail_len); - - // the used part of the buffer now is `free..self.capacity()`, so set - // `head` to the beginning of that range. - self.head = free; - } - } else { - // head is shorter so: - // 1. copy head backwards - // 2. rotate used part of the buffer - // 3. update head to point to the new beginning (which is the beginning of the buffer) - - unsafe { - // if there is no free space in the buffer, then the slices are already - // right next to each other and we don't need to move any memory. - if free != 0 { - // copy the head slice to lie right behind the tail slice. - self.copy(self.head, tail_len, head_len); - } - - // because we copied the head slice so that both slices lie right - // next to each other, all the elements in the range are initialized. - let slice = &mut *self.buffer_range(0..self.len); - - // because the deque wasn't contiguous, we know that `head_len < self.len == slice.len()` - // so this will never panic. - slice.rotate_right(head_len); - - // the used part of the buffer now is `0..self.len`, so set - // `head` to the beginning of that range. - self.head = 0; - } - } - } - - unsafe { slice::from_raw_parts_mut(ptr.add(self.head), self.len) } - } - - /// Rotates the double-ended queue `n` places to the left. - /// - /// Equivalently, - /// - Rotates item `n` into the first position. - /// - Pops the first `n` items and pushes them to the end. - /// - Rotates `len() - n` places to the right. - /// - /// # Panics - /// - /// If `n` is greater than `len()`. Note that `n == len()` - /// does _not_ panic and is a no-op rotation. - /// - /// # Complexity - /// - /// Takes `*O*(min(n, len() - n))` time and no extra space. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf: VecDeque<_> = (0..10).collect(); - /// - /// buf.rotate_left(3); - /// assert_eq!(buf, [3, 4, 5, 6, 7, 8, 9, 0, 1, 2]); - /// - /// for i in 1..10 { - /// assert_eq!(i * 3 % 10, buf[0]); - /// buf.rotate_left(3); - /// } - /// assert_eq!(buf, [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]); - /// ``` - #[stable(feature = "vecdeque_rotate", since = "1.36.0")] - pub fn rotate_left(&mut self, n: usize) { - assert!(n <= self.len()); - let k = self.len - n; - if n <= k { - unsafe { self.rotate_left_inner(n) } - } else { - unsafe { self.rotate_right_inner(k) } - } - } - - /// Rotates the double-ended queue `n` places to the right. - /// - /// Equivalently, - /// - Rotates the first item into position `n`. - /// - Pops the last `n` items and pushes them to the front. - /// - Rotates `len() - n` places to the left. - /// - /// # Panics - /// - /// If `n` is greater than `len()`. Note that `n == len()` - /// does _not_ panic and is a no-op rotation. - /// - /// # Complexity - /// - /// Takes `*O*(min(n, len() - n))` time and no extra space. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf: VecDeque<_> = (0..10).collect(); - /// - /// buf.rotate_right(3); - /// assert_eq!(buf, [7, 8, 9, 0, 1, 2, 3, 4, 5, 6]); - /// - /// for i in 1..10 { - /// assert_eq!(0, buf[i * 3 % 10]); - /// buf.rotate_right(3); - /// } - /// assert_eq!(buf, [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]); - /// ``` - #[stable(feature = "vecdeque_rotate", since = "1.36.0")] - pub fn rotate_right(&mut self, n: usize) { - assert!(n <= self.len()); - let k = self.len - n; - if n <= k { - unsafe { self.rotate_right_inner(n) } - } else { - unsafe { self.rotate_left_inner(k) } - } - } - - // SAFETY: the following two methods require that the rotation amount - // be less than half the length of the deque. - // - // `wrap_copy` requires that `min(x, capacity() - x) + copy_len <= capacity()`, - // but then `min` is never more than half the capacity, regardless of x, - // so it's sound to call here because we're calling with something - // less than half the length, which is never above half the capacity. - - unsafe fn rotate_left_inner(&mut self, mid: usize) { - debug_assert!(mid * 2 <= self.len()); - unsafe { - self.wrap_copy(self.head, self.to_physical_idx(self.len), mid); - } - self.head = self.to_physical_idx(mid); - } - - unsafe fn rotate_right_inner(&mut self, k: usize) { - debug_assert!(k * 2 <= self.len()); - self.head = self.wrap_sub(self.head, k); - unsafe { - self.wrap_copy(self.to_physical_idx(self.len), self.head, k); - } - } - - /// Binary searches this `VecDeque` for a given element. - /// If the `VecDeque` is not sorted, the returned result is unspecified and - /// meaningless. - /// - /// If the value is found then [`Result::Ok`] is returned, containing the - /// index of the matching element. If there are multiple matches, then any - /// one of the matches could be returned. If the value is not found then - /// [`Result::Err`] is returned, containing the index where a matching - /// element could be inserted while maintaining sorted order. - /// - /// See also [`binary_search_by`], [`binary_search_by_key`], and [`partition_point`]. - /// - /// [`binary_search_by`]: VecDeque::binary_search_by - /// [`binary_search_by_key`]: VecDeque::binary_search_by_key - /// [`partition_point`]: VecDeque::partition_point - /// - /// # Examples - /// - /// Looks up a series of four elements. The first is found, with a - /// uniquely determined position; the second and third are not - /// found; the fourth could match any position in `[1, 4]`. - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let deque: VecDeque<_> = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55].into(); - /// - /// assert_eq!(deque.binary_search(&13), Ok(9)); - /// assert_eq!(deque.binary_search(&4), Err(7)); - /// assert_eq!(deque.binary_search(&100), Err(13)); - /// let r = deque.binary_search(&1); - /// assert!(matches!(r, Ok(1..=4))); - /// ``` - /// - /// If you want to insert an item to a sorted deque, while maintaining - /// sort order, consider using [`partition_point`]: - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut deque: VecDeque<_> = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55].into(); - /// let num = 42; - /// let idx = deque.partition_point(|&x| x <= num); - /// // If `num` is unique, `s.partition_point(|&x| x < num)` (with `<`) is equivalent to - /// // `s.binary_search(&num).unwrap_or_else(|x| x)`, but using `<=` may allow `insert` - /// // to shift less elements. - /// deque.insert(idx, num); - /// assert_eq!(deque, &[0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 42, 55]); - /// ``` - #[stable(feature = "vecdeque_binary_search", since = "1.54.0")] - #[inline] - pub fn binary_search(&self, x: &T) -> Result - where - T: Ord, - { - self.binary_search_by(|e| e.cmp(x)) - } - - /// Binary searches this `VecDeque` with a comparator function. - /// - /// The comparator function should return an order code that indicates - /// whether its argument is `Less`, `Equal` or `Greater` the desired - /// target. - /// If the `VecDeque` is not sorted or if the comparator function does not - /// implement an order consistent with the sort order of the underlying - /// `VecDeque`, the returned result is unspecified and meaningless. - /// - /// If the value is found then [`Result::Ok`] is returned, containing the - /// index of the matching element. If there are multiple matches, then any - /// one of the matches could be returned. If the value is not found then - /// [`Result::Err`] is returned, containing the index where a matching - /// element could be inserted while maintaining sorted order. - /// - /// See also [`binary_search`], [`binary_search_by_key`], and [`partition_point`]. - /// - /// [`binary_search`]: VecDeque::binary_search - /// [`binary_search_by_key`]: VecDeque::binary_search_by_key - /// [`partition_point`]: VecDeque::partition_point - /// - /// # Examples - /// - /// Looks up a series of four elements. The first is found, with a - /// uniquely determined position; the second and third are not - /// found; the fourth could match any position in `[1, 4]`. - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let deque: VecDeque<_> = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55].into(); - /// - /// assert_eq!(deque.binary_search_by(|x| x.cmp(&13)), Ok(9)); - /// assert_eq!(deque.binary_search_by(|x| x.cmp(&4)), Err(7)); - /// assert_eq!(deque.binary_search_by(|x| x.cmp(&100)), Err(13)); - /// let r = deque.binary_search_by(|x| x.cmp(&1)); - /// assert!(matches!(r, Ok(1..=4))); - /// ``` - #[stable(feature = "vecdeque_binary_search", since = "1.54.0")] - pub fn binary_search_by<'a, F>(&'a self, mut f: F) -> Result - where - F: FnMut(&'a T) -> Ordering, - { - let (front, back) = self.as_slices(); - let cmp_back = back.first().map(|elem| f(elem)); - - if let Some(Ordering::Equal) = cmp_back { - Ok(front.len()) - } else if let Some(Ordering::Less) = cmp_back { - back.binary_search_by(f).map(|idx| idx + front.len()).map_err(|idx| idx + front.len()) - } else { - front.binary_search_by(f) - } - } - - /// Binary searches this `VecDeque` with a key extraction function. - /// - /// Assumes that the deque is sorted by the key, for instance with - /// [`make_contiguous().sort_by_key()`] using the same key extraction function. - /// If the deque is not sorted by the key, the returned result is - /// unspecified and meaningless. - /// - /// If the value is found then [`Result::Ok`] is returned, containing the - /// index of the matching element. If there are multiple matches, then any - /// one of the matches could be returned. If the value is not found then - /// [`Result::Err`] is returned, containing the index where a matching - /// element could be inserted while maintaining sorted order. - /// - /// See also [`binary_search`], [`binary_search_by`], and [`partition_point`]. - /// - /// [`make_contiguous().sort_by_key()`]: VecDeque::make_contiguous - /// [`binary_search`]: VecDeque::binary_search - /// [`binary_search_by`]: VecDeque::binary_search_by - /// [`partition_point`]: VecDeque::partition_point - /// - /// # Examples - /// - /// Looks up a series of four elements in a slice of pairs sorted by - /// their second elements. The first is found, with a uniquely - /// determined position; the second and third are not found; the - /// fourth could match any position in `[1, 4]`. - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let deque: VecDeque<_> = [(0, 0), (2, 1), (4, 1), (5, 1), - /// (3, 1), (1, 2), (2, 3), (4, 5), (5, 8), (3, 13), - /// (1, 21), (2, 34), (4, 55)].into(); - /// - /// assert_eq!(deque.binary_search_by_key(&13, |&(a, b)| b), Ok(9)); - /// assert_eq!(deque.binary_search_by_key(&4, |&(a, b)| b), Err(7)); - /// assert_eq!(deque.binary_search_by_key(&100, |&(a, b)| b), Err(13)); - /// let r = deque.binary_search_by_key(&1, |&(a, b)| b); - /// assert!(matches!(r, Ok(1..=4))); - /// ``` - #[stable(feature = "vecdeque_binary_search", since = "1.54.0")] - #[inline] - pub fn binary_search_by_key<'a, B, F>(&'a self, b: &B, mut f: F) -> Result - where - F: FnMut(&'a T) -> B, - B: Ord, - { - self.binary_search_by(|k| f(k).cmp(b)) - } - - /// Returns the index of the partition point according to the given predicate - /// (the index of the first element of the second partition). - /// - /// The deque is assumed to be partitioned according to the given predicate. - /// This means that all elements for which the predicate returns true are at the start of the deque - /// and all elements for which the predicate returns false are at the end. - /// For example, `[7, 15, 3, 5, 4, 12, 6]` is partitioned under the predicate `x % 2 != 0` - /// (all odd numbers are at the start, all even at the end). - /// - /// If the deque is not partitioned, the returned result is unspecified and meaningless, - /// as this method performs a kind of binary search. - /// - /// See also [`binary_search`], [`binary_search_by`], and [`binary_search_by_key`]. - /// - /// [`binary_search`]: VecDeque::binary_search - /// [`binary_search_by`]: VecDeque::binary_search_by - /// [`binary_search_by_key`]: VecDeque::binary_search_by_key - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let deque: VecDeque<_> = [1, 2, 3, 3, 5, 6, 7].into(); - /// let i = deque.partition_point(|&x| x < 5); - /// - /// assert_eq!(i, 4); - /// assert!(deque.iter().take(i).all(|&x| x < 5)); - /// assert!(deque.iter().skip(i).all(|&x| !(x < 5))); - /// ``` - /// - /// If you want to insert an item to a sorted deque, while maintaining - /// sort order: - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut deque: VecDeque<_> = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55].into(); - /// let num = 42; - /// let idx = deque.partition_point(|&x| x < num); - /// deque.insert(idx, num); - /// assert_eq!(deque, &[0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 42, 55]); - /// ``` - #[stable(feature = "vecdeque_binary_search", since = "1.54.0")] - pub fn partition_point

AsyncIterator for Pin

-where - P: DerefMut, - P::Target: AsyncIterator, -{ - type Item = ::Item; - - fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll> { - ::poll_next(self.as_deref_mut(), cx) - } - - fn size_hint(&self) -> (usize, Option) { - (**self).size_hint() - } -} - -#[unstable(feature = "async_gen_internals", issue = "none")] -impl Poll> { - /// A helper function for internal desugaring -- produces `Ready(Some(t))`, - /// which corresponds to the async iterator yielding a value. - #[doc(hidden)] - #[unstable(feature = "async_gen_internals", issue = "none")] - #[lang = "AsyncGenReady"] - pub fn async_gen_ready(t: T) -> Self { - Poll::Ready(Some(t)) - } - - /// A helper constant for internal desugaring -- produces `Pending`, - /// which corresponds to the async iterator pending on an `.await`. - #[doc(hidden)] - #[unstable(feature = "async_gen_internals", issue = "none")] - #[lang = "AsyncGenPending"] - // FIXME(gen_blocks): This probably could be deduplicated. - pub const PENDING: Self = Poll::Pending; - - /// A helper constant for internal desugaring -- produces `Ready(None)`, - /// which corresponds to the async iterator finishing its iteration. - #[doc(hidden)] - #[unstable(feature = "async_gen_internals", issue = "none")] - #[lang = "AsyncGenFinished"] - pub const FINISHED: Self = Poll::Ready(None); -} - -/// Convert something into an async iterator -#[unstable(feature = "async_iterator", issue = "79024")] -pub trait IntoAsyncIterator { - /// The type of the item yielded by the iterator - type Item; - /// The type of the resulting iterator - type IntoAsyncIter: AsyncIterator; - - /// Converts `self` into an async iterator - #[lang = "into_async_iter_into_iter"] - fn into_async_iter(self) -> Self::IntoAsyncIter; -} - -#[unstable(feature = "async_iterator", issue = "79024")] -impl IntoAsyncIterator for I { - type Item = I::Item; - type IntoAsyncIter = I; - - fn into_async_iter(self) -> Self::IntoAsyncIter { - self - } -} diff --git a/library/core/src/async_iter/from_iter.rs b/library/core/src/async_iter/from_iter.rs deleted file mode 100644 index 3180187afc8c9..0000000000000 --- a/library/core/src/async_iter/from_iter.rs +++ /dev/null @@ -1,38 +0,0 @@ -use crate::pin::Pin; - -use crate::async_iter::AsyncIterator; -use crate::task::{Context, Poll}; - -/// An async iterator that was created from iterator. -/// -/// This async iterator is created by the [`from_iter`] function. -/// See it documentation for more. -/// -/// [`from_iter`]: fn.from_iter.html -#[unstable(feature = "async_iter_from_iter", issue = "81798")] -#[derive(Clone, Debug)] -pub struct FromIter { - iter: I, -} - -#[unstable(feature = "async_iter_from_iter", issue = "81798")] -impl Unpin for FromIter {} - -/// Converts an iterator into an async iterator. -#[unstable(feature = "async_iter_from_iter", issue = "81798")] -pub fn from_iter(iter: I) -> FromIter { - FromIter { iter: iter.into_iter() } -} - -#[unstable(feature = "async_iter_from_iter", issue = "81798")] -impl AsyncIterator for FromIter { - type Item = I::Item; - - fn poll_next(mut self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll> { - Poll::Ready(self.iter.next()) - } - - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } -} diff --git a/library/core/src/async_iter/mod.rs b/library/core/src/async_iter/mod.rs deleted file mode 100644 index e1f1c9075823d..0000000000000 --- a/library/core/src/async_iter/mod.rs +++ /dev/null @@ -1,128 +0,0 @@ -//! Composable asynchronous iteration. -//! -//! If you've found yourself with an asynchronous collection of some kind, -//! and needed to perform an operation on the elements of said collection, -//! you'll quickly run into 'async iterators'. Async Iterators are heavily used in -//! idiomatic asynchronous Rust code, so it's worth becoming familiar with them. -//! -//! Before explaining more, let's talk about how this module is structured: -//! -//! # Organization -//! -//! This module is largely organized by type: -//! -//! * [Traits] are the core portion: these traits define what kind of async iterators -//! exist and what you can do with them. The methods of these traits are worth -//! putting some extra study time into. -//! * Functions provide some helpful ways to create some basic async iterators. -//! * Structs are often the return types of the various methods on this -//! module's traits. You'll usually want to look at the method that creates -//! the `struct`, rather than the `struct` itself. For more detail about why, -//! see '[Implementing Async Iterator](#implementing-async-iterator)'. -//! -//! [Traits]: #traits -//! -//! That's it! Let's dig into async iterators. -//! -//! # Async Iterators -//! -//! The heart and soul of this module is the [`AsyncIterator`] trait. The core of -//! [`AsyncIterator`] looks like this: -//! -//! ``` -//! # use core::task::{Context, Poll}; -//! # use core::pin::Pin; -//! trait AsyncIterator { -//! type Item; -//! fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll>; -//! } -//! ``` -//! -//! Unlike `Iterator`, `AsyncIterator` makes a distinction between the [`poll_next`] -//! method which is used when implementing an `AsyncIterator`, and a (to-be-implemented) -//! `next` method which is used when consuming an async iterator. Consumers of `AsyncIterator` -//! only need to consider `next`, which when called, returns a future which -//! yields `Option`. -//! -//! The future returned by `next` will yield `Some(Item)` as long as there are -//! elements, and once they've all been exhausted, will yield `None` to indicate -//! that iteration is finished. If we're waiting on something asynchronous to -//! resolve, the future will wait until the async iterator is ready to yield again. -//! -//! Individual async iterators may choose to resume iteration, and so calling `next` -//! again may or may not eventually yield `Some(Item)` again at some point. -//! -//! [`AsyncIterator`]'s full definition includes a number of other methods as well, -//! but they are default methods, built on top of [`poll_next`], and so you get -//! them for free. -//! -//! [`Poll`]: super::task::Poll -//! [`poll_next`]: AsyncIterator::poll_next -//! -//! # Implementing Async Iterator -//! -//! Creating an async iterator of your own involves two steps: creating a `struct` to -//! hold the async iterator's state, and then implementing [`AsyncIterator`] for that -//! `struct`. -//! -//! Let's make an async iterator named `Counter` which counts from `1` to `5`: -//! -//! ```no_run -//! #![feature(async_iterator)] -//! # use core::async_iter::AsyncIterator; -//! # use core::task::{Context, Poll}; -//! # use core::pin::Pin; -//! -//! // First, the struct: -//! -//! /// An async iterator which counts from one to five -//! struct Counter { -//! count: usize, -//! } -//! -//! // we want our count to start at one, so let's add a new() method to help. -//! // This isn't strictly necessary, but is convenient. Note that we start -//! // `count` at zero, we'll see why in `poll_next()`'s implementation below. -//! impl Counter { -//! fn new() -> Counter { -//! Counter { count: 0 } -//! } -//! } -//! -//! // Then, we implement `AsyncIterator` for our `Counter`: -//! -//! impl AsyncIterator for Counter { -//! // we will be counting with usize -//! type Item = usize; -//! -//! // poll_next() is the only required method -//! fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll> { -//! // Increment our count. This is why we started at zero. -//! self.count += 1; -//! -//! // Check to see if we've finished counting or not. -//! if self.count < 6 { -//! Poll::Ready(Some(self.count)) -//! } else { -//! Poll::Ready(None) -//! } -//! } -//! } -//! ``` -//! -//! # Laziness -//! -//! Async iterators are *lazy*. This means that just creating an async iterator doesn't -//! _do_ a whole lot. Nothing really happens until you call `poll_next`. This is -//! sometimes a source of confusion when creating an async iterator solely for its side -//! effects. The compiler will warn us about this kind of behavior: -//! -//! ```text -//! warning: unused result that must be used: async iterators do nothing unless polled -//! ``` - -mod async_iter; -mod from_iter; - -pub use async_iter::{AsyncIterator, IntoAsyncIterator}; -pub use from_iter::{from_iter, FromIter}; diff --git a/library/core/src/bool.rs b/library/core/src/bool.rs deleted file mode 100644 index 03cdff9b13be1..0000000000000 --- a/library/core/src/bool.rs +++ /dev/null @@ -1,62 +0,0 @@ -//! impl bool {} - -impl bool { - /// Returns `Some(t)` if the `bool` is [`true`](../std/keyword.true.html), - /// or `None` otherwise. - /// - /// Arguments passed to `then_some` are eagerly evaluated; if you are - /// passing the result of a function call, it is recommended to use - /// [`then`], which is lazily evaluated. - /// - /// [`then`]: bool::then - /// - /// # Examples - /// - /// ``` - /// assert_eq!(false.then_some(0), None); - /// assert_eq!(true.then_some(0), Some(0)); - /// ``` - /// - /// ``` - /// let mut a = 0; - /// let mut function_with_side_effects = || { a += 1; }; - /// - /// true.then_some(function_with_side_effects()); - /// false.then_some(function_with_side_effects()); - /// - /// // `a` is incremented twice because the value passed to `then_some` is - /// // evaluated eagerly. - /// assert_eq!(a, 2); - /// ``` - #[stable(feature = "bool_to_option", since = "1.62.0")] - #[inline] - pub fn then_some(self, t: T) -> Option { - if self { Some(t) } else { None } - } - - /// Returns `Some(f())` if the `bool` is [`true`](../std/keyword.true.html), - /// or `None` otherwise. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(false.then(|| 0), None); - /// assert_eq!(true.then(|| 0), Some(0)); - /// ``` - /// - /// ``` - /// let mut a = 0; - /// - /// true.then(|| { a += 1; }); - /// false.then(|| { a += 1; }); - /// - /// // `a` is incremented once because the closure is evaluated lazily by - /// // `then`. - /// assert_eq!(a, 1); - /// ``` - #[stable(feature = "lazy_bool_to_option", since = "1.50.0")] - #[inline] - pub fn then T>(self, f: F) -> Option { - if self { Some(f()) } else { None } - } -} diff --git a/library/core/src/borrow.rs b/library/core/src/borrow.rs deleted file mode 100644 index bc026d0a44634..0000000000000 --- a/library/core/src/borrow.rs +++ /dev/null @@ -1,241 +0,0 @@ -//! Utilities for working with borrowed data. - -#![stable(feature = "rust1", since = "1.0.0")] - -/// A trait for borrowing data. -/// -/// In Rust, it is common to provide different representations of a type for -/// different use cases. For instance, storage location and management for a -/// value can be specifically chosen as appropriate for a particular use via -/// pointer types such as [`Box`] or [`Rc`]. Beyond these generic -/// wrappers that can be used with any type, some types provide optional -/// facets providing potentially costly functionality. An example for such a -/// type is [`String`] which adds the ability to extend a string to the basic -/// [`str`]. This requires keeping additional information unnecessary for a -/// simple, immutable string. -/// -/// These types provide access to the underlying data through references -/// to the type of that data. They are said to be ‘borrowed as’ that type. -/// For instance, a [`Box`] can be borrowed as `T` while a [`String`] -/// can be borrowed as `str`. -/// -/// Types express that they can be borrowed as some type `T` by implementing -/// `Borrow`, providing a reference to a `T` in the trait’s -/// [`borrow`] method. A type is free to borrow as several different types. -/// If it wishes to mutably borrow as the type, allowing the underlying data -/// to be modified, it can additionally implement [`BorrowMut`]. -/// -/// Further, when providing implementations for additional traits, it needs -/// to be considered whether they should behave identically to those of the -/// underlying type as a consequence of acting as a representation of that -/// underlying type. Generic code typically uses `Borrow` when it relies -/// on the identical behavior of these additional trait implementations. -/// These traits will likely appear as additional trait bounds. -/// -/// In particular `Eq`, `Ord` and `Hash` must be equivalent for -/// borrowed and owned values: `x.borrow() == y.borrow()` should give the -/// same result as `x == y`. -/// -/// If generic code merely needs to work for all types that can -/// provide a reference to related type `T`, it is often better to use -/// [`AsRef`] as more types can safely implement it. -/// -/// [`Box`]: ../../std/boxed/struct.Box.html -/// [`Mutex`]: ../../std/sync/struct.Mutex.html -/// [`Rc`]: ../../std/rc/struct.Rc.html -/// [`String`]: ../../std/string/struct.String.html -/// [`borrow`]: Borrow::borrow -/// -/// # Examples -/// -/// As a data collection, [`HashMap`] owns both keys and values. If -/// the key’s actual data is wrapped in a managing type of some kind, it -/// should, however, still be possible to search for a value using a -/// reference to the key’s data. For instance, if the key is a string, then -/// it is likely stored with the hash map as a [`String`], while it should -/// be possible to search using a [`&str`][`str`]. Thus, `insert` needs to -/// operate on a `String` while `get` needs to be able to use a `&str`. -/// -/// Slightly simplified, the relevant parts of `HashMap` look like -/// this: -/// -/// ``` -/// use std::borrow::Borrow; -/// use std::hash::Hash; -/// -/// pub struct HashMap { -/// # marker: ::std::marker::PhantomData<(K, V)>, -/// // fields omitted -/// } -/// -/// impl HashMap { -/// pub fn insert(&self, key: K, value: V) -> Option -/// where K: Hash + Eq -/// { -/// # unimplemented!() -/// // ... -/// } -/// -/// pub fn get(&self, k: &Q) -> Option<&V> -/// where -/// K: Borrow, -/// Q: Hash + Eq + ?Sized -/// { -/// # unimplemented!() -/// // ... -/// } -/// } -/// ``` -/// -/// The entire hash map is generic over a key type `K`. Because these keys -/// are stored with the hash map, this type has to own the key’s data. -/// When inserting a key-value pair, the map is given such a `K` and needs -/// to find the correct hash bucket and check if the key is already present -/// based on that `K`. It therefore requires `K: Hash + Eq`. -/// -/// When searching for a value in the map, however, having to provide a -/// reference to a `K` as the key to search for would require to always -/// create such an owned value. For string keys, this would mean a `String` -/// value needs to be created just for the search for cases where only a -/// `str` is available. -/// -/// Instead, the `get` method is generic over the type of the underlying key -/// data, called `Q` in the method signature above. It states that `K` -/// borrows as a `Q` by requiring that `K: Borrow`. By additionally -/// requiring `Q: Hash + Eq`, it signals the requirement that `K` and `Q` -/// have implementations of the `Hash` and `Eq` traits that produce identical -/// results. -/// -/// The implementation of `get` relies in particular on identical -/// implementations of `Hash` by determining the key’s hash bucket by calling -/// `Hash::hash` on the `Q` value even though it inserted the key based on -/// the hash value calculated from the `K` value. -/// -/// As a consequence, the hash map breaks if a `K` wrapping a `Q` value -/// produces a different hash than `Q`. For instance, imagine you have a -/// type that wraps a string but compares ASCII letters ignoring their case: -/// -/// ``` -/// pub struct CaseInsensitiveString(String); -/// -/// impl PartialEq for CaseInsensitiveString { -/// fn eq(&self, other: &Self) -> bool { -/// self.0.eq_ignore_ascii_case(&other.0) -/// } -/// } -/// -/// impl Eq for CaseInsensitiveString { } -/// ``` -/// -/// Because two equal values need to produce the same hash value, the -/// implementation of `Hash` needs to ignore ASCII case, too: -/// -/// ``` -/// # use std::hash::{Hash, Hasher}; -/// # pub struct CaseInsensitiveString(String); -/// impl Hash for CaseInsensitiveString { -/// fn hash(&self, state: &mut H) { -/// for c in self.0.as_bytes() { -/// c.to_ascii_lowercase().hash(state) -/// } -/// } -/// } -/// ``` -/// -/// Can `CaseInsensitiveString` implement `Borrow`? It certainly can -/// provide a reference to a string slice via its contained owned string. -/// But because its `Hash` implementation differs, it behaves differently -/// from `str` and therefore must not, in fact, implement `Borrow`. -/// If it wants to allow others access to the underlying `str`, it can do -/// that via `AsRef` which doesn’t carry any extra requirements. -/// -/// [`Hash`]: crate::hash::Hash -/// [`HashMap`]: ../../std/collections/struct.HashMap.html -/// [`String`]: ../../std/string/struct.String.html -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_diagnostic_item = "Borrow"] -pub trait Borrow { - /// Immutably borrows from an owned value. - /// - /// # Examples - /// - /// ``` - /// use std::borrow::Borrow; - /// - /// fn check>(s: T) { - /// assert_eq!("Hello", s.borrow()); - /// } - /// - /// let s = "Hello".to_string(); - /// - /// check(s); - /// - /// let s = "Hello"; - /// - /// check(s); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn borrow(&self) -> &Borrowed; -} - -/// A trait for mutably borrowing data. -/// -/// As a companion to [`Borrow`] this trait allows a type to borrow as -/// an underlying type by providing a mutable reference. See [`Borrow`] -/// for more information on borrowing as another type. -#[stable(feature = "rust1", since = "1.0.0")] -pub trait BorrowMut: Borrow { - /// Mutably borrows from an owned value. - /// - /// # Examples - /// - /// ``` - /// use std::borrow::BorrowMut; - /// - /// fn check>(mut v: T) { - /// assert_eq!(&mut [1, 2, 3], v.borrow_mut()); - /// } - /// - /// let v = vec![1, 2, 3]; - /// - /// check(v); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn borrow_mut(&mut self) -> &mut Borrowed; -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Borrow for T { - #[rustc_diagnostic_item = "noop_method_borrow"] - fn borrow(&self) -> &T { - self - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl BorrowMut for T { - fn borrow_mut(&mut self) -> &mut T { - self - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Borrow for &T { - fn borrow(&self) -> &T { - &**self - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Borrow for &mut T { - fn borrow(&self) -> &T { - &**self - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl BorrowMut for &mut T { - fn borrow_mut(&mut self) -> &mut T { - &mut **self - } -} diff --git a/library/core/src/cell.rs b/library/core/src/cell.rs deleted file mode 100644 index 4b491ffdafa70..0000000000000 --- a/library/core/src/cell.rs +++ /dev/null @@ -1,2381 +0,0 @@ -//! Shareable mutable containers. -//! -//! Rust memory safety is based on this rule: Given an object `T`, it is only possible to -//! have one of the following: -//! -//! - Having several immutable references (`&T`) to the object (also known as **aliasing**). -//! - Having one mutable reference (`&mut T`) to the object (also known as **mutability**). -//! -//! This is enforced by the Rust compiler. However, there are situations where this rule is not -//! flexible enough. Sometimes it is required to have multiple references to an object and yet -//! mutate it. -//! -//! Shareable mutable containers exist to permit mutability in a controlled manner, even in the -//! presence of aliasing. [`Cell`], [`RefCell`], and [`OnceCell`] allow doing this in -//! a single-threaded way—they do not implement [`Sync`]. (If you need to do aliasing and -//! mutation among multiple threads, [`Mutex`], [`RwLock`], [`OnceLock`] or [`atomic`] -//! types are the correct data structures to do so). -//! -//! Values of the `Cell`, `RefCell`, and `OnceCell` types may be mutated through shared -//! references (i.e. the common `&T` type), whereas most Rust types can only be mutated through -//! unique (`&mut T`) references. We say these cell types provide 'interior mutability' -//! (mutable via `&T`), in contrast with typical Rust types that exhibit 'inherited mutability' -//! (mutable only via `&mut T`). -//! -//! Cell types come in three flavors: `Cell`, `RefCell`, and `OnceCell`. Each provides -//! a different way of providing safe interior mutability. -//! -//! ## `Cell` -//! -//! [`Cell`] implements interior mutability by moving values in and out of the cell. That is, an -//! `&mut T` to the inner value can never be obtained, and the value itself cannot be directly -//! obtained without replacing it with something else. Both of these rules ensure that there is -//! never more than one reference pointing to the inner value. This type provides the following -//! methods: -//! -//! - For types that implement [`Copy`], the [`get`](Cell::get) method retrieves the current -//! interior value by duplicating it. -//! - For types that implement [`Default`], the [`take`](Cell::take) method replaces the current -//! interior value with [`Default::default()`] and returns the replaced value. -//! - All types have: -//! - [`replace`](Cell::replace): replaces the current interior value and returns the replaced -//! value. -//! - [`into_inner`](Cell::into_inner): this method consumes the `Cell` and returns the -//! interior value. -//! - [`set`](Cell::set): this method replaces the interior value, dropping the replaced value. -//! -//! `Cell` is typically used for more simple types where copying or moving values isn't too -//! resource intensive (e.g. numbers), and should usually be preferred over other cell types when -//! possible. For larger and non-copy types, `RefCell` provides some advantages. -//! -//! ## `RefCell` -//! -//! [`RefCell`] uses Rust's lifetimes to implement "dynamic borrowing", a process whereby one can -//! claim temporary, exclusive, mutable access to the inner value. Borrows for `RefCell`s are -//! tracked at _runtime_, unlike Rust's native reference types which are entirely tracked -//! statically, at compile time. -//! -//! An immutable reference to a `RefCell`'s inner value (`&T`) can be obtained with -//! [`borrow`](`RefCell::borrow`), and a mutable borrow (`&mut T`) can be obtained with -//! [`borrow_mut`](`RefCell::borrow_mut`). When these functions are called, they first verify that -//! Rust's borrow rules will be satisfied: any number of immutable borrows are allowed or a -//! single mutable borrow is allowed, but never both. If a borrow is attempted that would violate -//! these rules, the thread will panic. -//! -//! The corresponding [`Sync`] version of `RefCell` is [`RwLock`]. -//! -//! ## `OnceCell` -//! -//! [`OnceCell`] is somewhat of a hybrid of `Cell` and `RefCell` that works for values that -//! typically only need to be set once. This means that a reference `&T` can be obtained without -//! moving or copying the inner value (unlike `Cell`) but also without runtime checks (unlike -//! `RefCell`). However, its value can also not be updated once set unless you have a mutable -//! reference to the `OnceCell`. -//! -//! `OnceCell` provides the following methods: -//! -//! - [`get`](OnceCell::get): obtain a reference to the inner value -//! - [`set`](OnceCell::set): set the inner value if it is unset (returns a `Result`) -//! - [`get_or_init`](OnceCell::get_or_init): return the inner value, initializing it if needed -//! - [`get_mut`](OnceCell::get_mut): provide a mutable reference to the inner value, only available -//! if you have a mutable reference to the cell itself. -//! -//! The corresponding [`Sync`] version of `OnceCell` is [`OnceLock`]. -//! -//! -//! # When to choose interior mutability -//! -//! The more common inherited mutability, where one must have unique access to mutate a value, is -//! one of the key language elements that enables Rust to reason strongly about pointer aliasing, -//! statically preventing crash bugs. Because of that, inherited mutability is preferred, and -//! interior mutability is something of a last resort. Since cell types enable mutation where it -//! would otherwise be disallowed though, there are occasions when interior mutability might be -//! appropriate, or even *must* be used, e.g. -//! -//! * Introducing mutability 'inside' of something immutable -//! * Implementation details of logically-immutable methods. -//! * Mutating implementations of [`Clone`]. -//! -//! ## Introducing mutability 'inside' of something immutable -//! -//! Many shared smart pointer types, including [`Rc`] and [`Arc`], provide containers that can -//! be cloned and shared between multiple parties. Because the contained values may be -//! multiply-aliased, they can only be borrowed with `&`, not `&mut`. Without cells it would be -//! impossible to mutate data inside of these smart pointers at all. -//! -//! It's very common then to put a `RefCell` inside shared pointer types to reintroduce -//! mutability: -//! -//! ``` -//! use std::cell::{RefCell, RefMut}; -//! use std::collections::HashMap; -//! use std::rc::Rc; -//! -//! fn main() { -//! let shared_map: Rc> = Rc::new(RefCell::new(HashMap::new())); -//! // Create a new block to limit the scope of the dynamic borrow -//! { -//! let mut map: RefMut<'_, _> = shared_map.borrow_mut(); -//! map.insert("africa", 92388); -//! map.insert("kyoto", 11837); -//! map.insert("piccadilly", 11826); -//! map.insert("marbles", 38); -//! } -//! -//! // Note that if we had not let the previous borrow of the cache fall out -//! // of scope then the subsequent borrow would cause a dynamic thread panic. -//! // This is the major hazard of using `RefCell`. -//! let total: i32 = shared_map.borrow().values().sum(); -//! println!("{total}"); -//! } -//! ``` -//! -//! Note that this example uses `Rc` and not `Arc`. `RefCell`s are for single-threaded -//! scenarios. Consider using [`RwLock`] or [`Mutex`] if you need shared mutability in a -//! multi-threaded situation. -//! -//! ## Implementation details of logically-immutable methods -//! -//! Occasionally it may be desirable not to expose in an API that there is mutation happening -//! "under the hood". This may be because logically the operation is immutable, but e.g., caching -//! forces the implementation to perform mutation; or because you must employ mutation to implement -//! a trait method that was originally defined to take `&self`. -//! -//! ``` -//! # #![allow(dead_code)] -//! use std::cell::OnceCell; -//! -//! struct Graph { -//! edges: Vec<(i32, i32)>, -//! span_tree_cache: OnceCell> -//! } -//! -//! impl Graph { -//! fn minimum_spanning_tree(&self) -> Vec<(i32, i32)> { -//! self.span_tree_cache -//! .get_or_init(|| self.calc_span_tree()) -//! .clone() -//! } -//! -//! fn calc_span_tree(&self) -> Vec<(i32, i32)> { -//! // Expensive computation goes here -//! vec![] -//! } -//! } -//! ``` -//! -//! ## Mutating implementations of `Clone` -//! -//! This is simply a special - but common - case of the previous: hiding mutability for operations -//! that appear to be immutable. The [`clone`](Clone::clone) method is expected to not change the -//! source value, and is declared to take `&self`, not `&mut self`. Therefore, any mutation that -//! happens in the `clone` method must use cell types. For example, [`Rc`] maintains its -//! reference counts within a `Cell`. -//! -//! ``` -//! use std::cell::Cell; -//! use std::ptr::NonNull; -//! use std::process::abort; -//! use std::marker::PhantomData; -//! -//! struct Rc { -//! ptr: NonNull>, -//! phantom: PhantomData>, -//! } -//! -//! struct RcBox { -//! strong: Cell, -//! refcount: Cell, -//! value: T, -//! } -//! -//! impl Clone for Rc { -//! fn clone(&self) -> Rc { -//! self.inc_strong(); -//! Rc { -//! ptr: self.ptr, -//! phantom: PhantomData, -//! } -//! } -//! } -//! -//! trait RcBoxPtr { -//! -//! fn inner(&self) -> &RcBox; -//! -//! fn strong(&self) -> usize { -//! self.inner().strong.get() -//! } -//! -//! fn inc_strong(&self) { -//! self.inner() -//! .strong -//! .set(self.strong() -//! .checked_add(1) -//! .unwrap_or_else(|| abort() )); -//! } -//! } -//! -//! impl RcBoxPtr for Rc { -//! fn inner(&self) -> &RcBox { -//! unsafe { -//! self.ptr.as_ref() -//! } -//! } -//! } -//! ``` -//! -//! [`Arc`]: ../../std/sync/struct.Arc.html -//! [`Rc`]: ../../std/rc/struct.Rc.html -//! [`RwLock`]: ../../std/sync/struct.RwLock.html -//! [`Mutex`]: ../../std/sync/struct.Mutex.html -//! [`OnceLock`]: ../../std/sync/struct.OnceLock.html -//! [`Sync`]: ../../std/marker/trait.Sync.html -//! [`atomic`]: crate::sync::atomic - -#![stable(feature = "rust1", since = "1.0.0")] - -use crate::cmp::Ordering; -use crate::fmt::{self, Debug, Display}; -use crate::marker::{PhantomData, Unsize}; -use crate::mem::{self, size_of}; -use crate::ops::{CoerceUnsized, Deref, DerefMut, DerefPure, DispatchFromDyn}; -use crate::ptr::{self, NonNull}; - -mod lazy; -mod once; - -#[unstable(feature = "lazy_cell", issue = "109736")] -pub use lazy::LazyCell; -#[stable(feature = "once_cell", since = "1.70.0")] -pub use once::OnceCell; - -/// A mutable memory location. -/// -/// # Memory layout -/// -/// `Cell` has the same [memory layout and caveats as -/// `UnsafeCell`](UnsafeCell#memory-layout). In particular, this means that -/// `Cell` has the same in-memory representation as its inner type `T`. -/// -/// # Examples -/// -/// In this example, you can see that `Cell` enables mutation inside an -/// immutable struct. In other words, it enables "interior mutability". -/// -/// ``` -/// use std::cell::Cell; -/// -/// struct SomeStruct { -/// regular_field: u8, -/// special_field: Cell, -/// } -/// -/// let my_struct = SomeStruct { -/// regular_field: 0, -/// special_field: Cell::new(1), -/// }; -/// -/// let new_value = 100; -/// -/// // ERROR: `my_struct` is immutable -/// // my_struct.regular_field = new_value; -/// -/// // WORKS: although `my_struct` is immutable, `special_field` is a `Cell`, -/// // which can always be mutated -/// my_struct.special_field.set(new_value); -/// assert_eq!(my_struct.special_field.get(), new_value); -/// ``` -/// -/// See the [module-level documentation](self) for more. -#[stable(feature = "rust1", since = "1.0.0")] -#[repr(transparent)] -pub struct Cell { - value: UnsafeCell, -} - -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Send for Cell where T: Send {} - -// Note that this negative impl isn't strictly necessary for correctness, -// as `Cell` wraps `UnsafeCell`, which is itself `!Sync`. -// However, given how important `Cell`'s `!Sync`-ness is, -// having an explicit negative impl is nice for documentation purposes -// and results in nicer error messages. -#[stable(feature = "rust1", since = "1.0.0")] -impl !Sync for Cell {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Cell { - #[inline] - fn clone(&self) -> Cell { - Cell::new(self.get()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Default for Cell { - /// Creates a `Cell`, with the `Default` value for T. - #[inline] - fn default() -> Cell { - Cell::new(Default::default()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for Cell { - #[inline] - fn eq(&self, other: &Cell) -> bool { - self.get() == other.get() - } -} - -#[stable(feature = "cell_eq", since = "1.2.0")] -impl Eq for Cell {} - -#[stable(feature = "cell_ord", since = "1.10.0")] -impl PartialOrd for Cell { - #[inline] - fn partial_cmp(&self, other: &Cell) -> Option { - self.get().partial_cmp(&other.get()) - } - - #[inline] - fn lt(&self, other: &Cell) -> bool { - self.get() < other.get() - } - - #[inline] - fn le(&self, other: &Cell) -> bool { - self.get() <= other.get() - } - - #[inline] - fn gt(&self, other: &Cell) -> bool { - self.get() > other.get() - } - - #[inline] - fn ge(&self, other: &Cell) -> bool { - self.get() >= other.get() - } -} - -#[stable(feature = "cell_ord", since = "1.10.0")] -impl Ord for Cell { - #[inline] - fn cmp(&self, other: &Cell) -> Ordering { - self.get().cmp(&other.get()) - } -} - -#[stable(feature = "cell_from", since = "1.12.0")] -impl From for Cell { - /// Creates a new `Cell` containing the given value. - fn from(t: T) -> Cell { - Cell::new(t) - } -} - -impl Cell { - /// Creates a new `Cell` containing the given value. - /// - /// # Examples - /// - /// ``` - /// use std::cell::Cell; - /// - /// let c = Cell::new(5); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_cell_new", since = "1.24.0")] - #[inline] - pub const fn new(value: T) -> Cell { - Cell { value: UnsafeCell::new(value) } - } - - /// Sets the contained value. - /// - /// # Examples - /// - /// ``` - /// use std::cell::Cell; - /// - /// let c = Cell::new(5); - /// - /// c.set(10); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn set(&self, val: T) { - self.replace(val); - } - - /// Swaps the values of two `Cell`s. - /// Difference with `std::mem::swap` is that this function doesn't require `&mut` reference. - /// - /// # Panics - /// - /// This function will panic if `self` and `other` are different `Cell`s that partially overlap. - /// (Using just standard library methods, it is impossible to create such partially overlapping `Cell`s. - /// However, unsafe code is allowed to e.g. create two `&Cell<[i32; 2]>` that partially overlap.) - /// - /// # Examples - /// - /// ``` - /// use std::cell::Cell; - /// - /// let c1 = Cell::new(5i32); - /// let c2 = Cell::new(10i32); - /// c1.swap(&c2); - /// assert_eq!(10, c1.get()); - /// assert_eq!(5, c2.get()); - /// ``` - #[inline] - #[stable(feature = "move_cell", since = "1.17.0")] - pub fn swap(&self, other: &Self) { - // This function documents that it *will* panic, and intrinsics::is_nonoverlapping doesn't - // do the check in const, so trying to use it here would be inviting unnecessary fragility. - fn is_nonoverlapping(src: *const T, dst: *const T) -> bool { - let src_usize = src.addr(); - let dst_usize = dst.addr(); - let diff = src_usize.abs_diff(dst_usize); - diff >= size_of::() - } - - if ptr::eq(self, other) { - // Swapping wouldn't change anything. - return; - } - if !is_nonoverlapping(self, other) { - // See for why we need to stop here. - panic!("`Cell::swap` on overlapping non-identical `Cell`s"); - } - // SAFETY: This can be risky if called from separate threads, but `Cell` - // is `!Sync` so this won't happen. This also won't invalidate any - // pointers since `Cell` makes sure nothing else will be pointing into - // either of these `Cell`s. We also excluded shenanigans like partially overlapping `Cell`s, - // so `swap` will just properly copy two full values of type `T` back and forth. - unsafe { - mem::swap(&mut *self.value.get(), &mut *other.value.get()); - } - } - - /// Replaces the contained value with `val`, and returns the old contained value. - /// - /// # Examples - /// - /// ``` - /// use std::cell::Cell; - /// - /// let cell = Cell::new(5); - /// assert_eq!(cell.get(), 5); - /// assert_eq!(cell.replace(10), 5); - /// assert_eq!(cell.get(), 10); - /// ``` - #[inline] - #[stable(feature = "move_cell", since = "1.17.0")] - #[rustc_confusables("swap")] - pub fn replace(&self, val: T) -> T { - // SAFETY: This can cause data races if called from a separate thread, - // but `Cell` is `!Sync` so this won't happen. - mem::replace(unsafe { &mut *self.value.get() }, val) - } - - /// Unwraps the value, consuming the cell. - /// - /// # Examples - /// - /// ``` - /// use std::cell::Cell; - /// - /// let c = Cell::new(5); - /// let five = c.into_inner(); - /// - /// assert_eq!(five, 5); - /// ``` - #[stable(feature = "move_cell", since = "1.17.0")] - #[rustc_const_unstable(feature = "const_cell_into_inner", issue = "78729")] - pub const fn into_inner(self) -> T { - self.value.into_inner() - } -} - -impl Cell { - /// Returns a copy of the contained value. - /// - /// # Examples - /// - /// ``` - /// use std::cell::Cell; - /// - /// let c = Cell::new(5); - /// - /// let five = c.get(); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn get(&self) -> T { - // SAFETY: This can cause data races if called from a separate thread, - // but `Cell` is `!Sync` so this won't happen. - unsafe { *self.value.get() } - } - - /// Updates the contained value using a function and returns the new value. - /// - /// # Examples - /// - /// ``` - /// #![feature(cell_update)] - /// - /// use std::cell::Cell; - /// - /// let c = Cell::new(5); - /// let new = c.update(|x| x + 1); - /// - /// assert_eq!(new, 6); - /// assert_eq!(c.get(), 6); - /// ``` - #[inline] - #[unstable(feature = "cell_update", issue = "50186")] - pub fn update(&self, f: F) -> T - where - F: FnOnce(T) -> T, - { - let old = self.get(); - let new = f(old); - self.set(new); - new - } -} - -impl Cell { - /// Returns a raw pointer to the underlying data in this cell. - /// - /// # Examples - /// - /// ``` - /// use std::cell::Cell; - /// - /// let c = Cell::new(5); - /// - /// let ptr = c.as_ptr(); - /// ``` - #[inline] - #[stable(feature = "cell_as_ptr", since = "1.12.0")] - #[rustc_const_stable(feature = "const_cell_as_ptr", since = "1.32.0")] - #[rustc_never_returns_null_ptr] - pub const fn as_ptr(&self) -> *mut T { - self.value.get() - } - - /// Returns a mutable reference to the underlying data. - /// - /// This call borrows `Cell` mutably (at compile-time) which guarantees - /// that we possess the only reference. - /// - /// However be cautious: this method expects `self` to be mutable, which is - /// generally not the case when using a `Cell`. If you require interior - /// mutability by reference, consider using `RefCell` which provides - /// run-time checked mutable borrows through its [`borrow_mut`] method. - /// - /// [`borrow_mut`]: RefCell::borrow_mut() - /// - /// # Examples - /// - /// ``` - /// use std::cell::Cell; - /// - /// let mut c = Cell::new(5); - /// *c.get_mut() += 1; - /// - /// assert_eq!(c.get(), 6); - /// ``` - #[inline] - #[stable(feature = "cell_get_mut", since = "1.11.0")] - pub fn get_mut(&mut self) -> &mut T { - self.value.get_mut() - } - - /// Returns a `&Cell` from a `&mut T` - /// - /// # Examples - /// - /// ``` - /// use std::cell::Cell; - /// - /// let slice: &mut [i32] = &mut [1, 2, 3]; - /// let cell_slice: &Cell<[i32]> = Cell::from_mut(slice); - /// let slice_cell: &[Cell] = cell_slice.as_slice_of_cells(); - /// - /// assert_eq!(slice_cell.len(), 3); - /// ``` - #[inline] - #[stable(feature = "as_cell", since = "1.37.0")] - pub fn from_mut(t: &mut T) -> &Cell { - // SAFETY: `&mut` ensures unique access. - unsafe { &*(t as *mut T as *const Cell) } - } -} - -impl Cell { - /// Takes the value of the cell, leaving `Default::default()` in its place. - /// - /// # Examples - /// - /// ``` - /// use std::cell::Cell; - /// - /// let c = Cell::new(5); - /// let five = c.take(); - /// - /// assert_eq!(five, 5); - /// assert_eq!(c.into_inner(), 0); - /// ``` - #[stable(feature = "move_cell", since = "1.17.0")] - pub fn take(&self) -> T { - self.replace(Default::default()) - } -} - -#[unstable(feature = "coerce_unsized", issue = "18598")] -impl, U> CoerceUnsized> for Cell {} - -// Allow types that wrap `Cell` to also implement `DispatchFromDyn` -// and become object safe method receivers. -// Note that currently `Cell` itself cannot be a method receiver -// because it does not implement Deref. -// In other words: -// `self: Cell<&Self>` won't work -// `self: CellWrapper` becomes possible -#[unstable(feature = "dispatch_from_dyn", issue = "none")] -impl, U> DispatchFromDyn> for Cell {} - -impl Cell<[T]> { - /// Returns a `&[Cell]` from a `&Cell<[T]>` - /// - /// # Examples - /// - /// ``` - /// use std::cell::Cell; - /// - /// let slice: &mut [i32] = &mut [1, 2, 3]; - /// let cell_slice: &Cell<[i32]> = Cell::from_mut(slice); - /// let slice_cell: &[Cell] = cell_slice.as_slice_of_cells(); - /// - /// assert_eq!(slice_cell.len(), 3); - /// ``` - #[stable(feature = "as_cell", since = "1.37.0")] - pub fn as_slice_of_cells(&self) -> &[Cell] { - // SAFETY: `Cell` has the same memory layout as `T`. - unsafe { &*(self as *const Cell<[T]> as *const [Cell]) } - } -} - -impl Cell<[T; N]> { - /// Returns a `&[Cell; N]` from a `&Cell<[T; N]>` - /// - /// # Examples - /// - /// ``` - /// #![feature(as_array_of_cells)] - /// use std::cell::Cell; - /// - /// let mut array: [i32; 3] = [1, 2, 3]; - /// let cell_array: &Cell<[i32; 3]> = Cell::from_mut(&mut array); - /// let array_cell: &[Cell; 3] = cell_array.as_array_of_cells(); - /// ``` - #[unstable(feature = "as_array_of_cells", issue = "88248")] - pub fn as_array_of_cells(&self) -> &[Cell; N] { - // SAFETY: `Cell` has the same memory layout as `T`. - unsafe { &*(self as *const Cell<[T; N]> as *const [Cell; N]) } - } -} - -/// A mutable memory location with dynamically checked borrow rules -/// -/// See the [module-level documentation](self) for more. -#[cfg_attr(not(test), rustc_diagnostic_item = "RefCell")] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct RefCell { - borrow: Cell, - // Stores the location of the earliest currently active borrow. - // This gets updated whenever we go from having zero borrows - // to having a single borrow. When a borrow occurs, this gets included - // in the generated `BorrowError`/`BorrowMutError` - #[cfg(feature = "debug_refcell")] - borrowed_at: Cell>>, - value: UnsafeCell, -} - -/// An error returned by [`RefCell::try_borrow`]. -#[stable(feature = "try_borrow", since = "1.13.0")] -#[non_exhaustive] -pub struct BorrowError { - #[cfg(feature = "debug_refcell")] - location: &'static crate::panic::Location<'static>, -} - -#[stable(feature = "try_borrow", since = "1.13.0")] -impl Debug for BorrowError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let mut builder = f.debug_struct("BorrowError"); - - #[cfg(feature = "debug_refcell")] - builder.field("location", self.location); - - builder.finish() - } -} - -#[stable(feature = "try_borrow", since = "1.13.0")] -impl Display for BorrowError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - Display::fmt("already mutably borrowed", f) - } -} - -/// An error returned by [`RefCell::try_borrow_mut`]. -#[stable(feature = "try_borrow", since = "1.13.0")] -#[non_exhaustive] -pub struct BorrowMutError { - #[cfg(feature = "debug_refcell")] - location: &'static crate::panic::Location<'static>, -} - -#[stable(feature = "try_borrow", since = "1.13.0")] -impl Debug for BorrowMutError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let mut builder = f.debug_struct("BorrowMutError"); - - #[cfg(feature = "debug_refcell")] - builder.field("location", self.location); - - builder.finish() - } -} - -#[stable(feature = "try_borrow", since = "1.13.0")] -impl Display for BorrowMutError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - Display::fmt("already borrowed", f) - } -} - -// This ensures the panicking code is outlined from `borrow_mut` for `RefCell`. -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never))] -#[track_caller] -#[cold] -fn panic_already_borrowed(err: BorrowMutError) -> ! { - panic!("already borrowed: {:?}", err) -} - -// This ensures the panicking code is outlined from `borrow` for `RefCell`. -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never))] -#[track_caller] -#[cold] -fn panic_already_mutably_borrowed(err: BorrowError) -> ! { - panic!("already mutably borrowed: {:?}", err) -} - -// Positive values represent the number of `Ref` active. Negative values -// represent the number of `RefMut` active. Multiple `RefMut`s can only be -// active at a time if they refer to distinct, nonoverlapping components of a -// `RefCell` (e.g., different ranges of a slice). -// -// `Ref` and `RefMut` are both two words in size, and so there will likely never -// be enough `Ref`s or `RefMut`s in existence to overflow half of the `usize` -// range. Thus, a `BorrowFlag` will probably never overflow or underflow. -// However, this is not a guarantee, as a pathological program could repeatedly -// create and then mem::forget `Ref`s or `RefMut`s. Thus, all code must -// explicitly check for overflow and underflow in order to avoid unsafety, or at -// least behave correctly in the event that overflow or underflow happens (e.g., -// see BorrowRef::new). -type BorrowFlag = isize; -const UNUSED: BorrowFlag = 0; - -#[inline(always)] -fn is_writing(x: BorrowFlag) -> bool { - x < UNUSED -} - -#[inline(always)] -fn is_reading(x: BorrowFlag) -> bool { - x > UNUSED -} - -impl RefCell { - /// Creates a new `RefCell` containing `value`. - /// - /// # Examples - /// - /// ``` - /// use std::cell::RefCell; - /// - /// let c = RefCell::new(5); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_refcell_new", since = "1.24.0")] - #[inline] - pub const fn new(value: T) -> RefCell { - RefCell { - value: UnsafeCell::new(value), - borrow: Cell::new(UNUSED), - #[cfg(feature = "debug_refcell")] - borrowed_at: Cell::new(None), - } - } - - /// Consumes the `RefCell`, returning the wrapped value. - /// - /// # Examples - /// - /// ``` - /// use std::cell::RefCell; - /// - /// let c = RefCell::new(5); - /// - /// let five = c.into_inner(); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_cell_into_inner", issue = "78729")] - #[inline] - pub const fn into_inner(self) -> T { - // Since this function takes `self` (the `RefCell`) by value, the - // compiler statically verifies that it is not currently borrowed. - self.value.into_inner() - } - - /// Replaces the wrapped value with a new one, returning the old value, - /// without deinitializing either one. - /// - /// This function corresponds to [`std::mem::replace`](../mem/fn.replace.html). - /// - /// # Panics - /// - /// Panics if the value is currently borrowed. - /// - /// # Examples - /// - /// ``` - /// use std::cell::RefCell; - /// let cell = RefCell::new(5); - /// let old_value = cell.replace(6); - /// assert_eq!(old_value, 5); - /// assert_eq!(cell, RefCell::new(6)); - /// ``` - #[inline] - #[stable(feature = "refcell_replace", since = "1.24.0")] - #[track_caller] - #[rustc_confusables("swap")] - pub fn replace(&self, t: T) -> T { - mem::replace(&mut *self.borrow_mut(), t) - } - - /// Replaces the wrapped value with a new one computed from `f`, returning - /// the old value, without deinitializing either one. - /// - /// # Panics - /// - /// Panics if the value is currently borrowed. - /// - /// # Examples - /// - /// ``` - /// use std::cell::RefCell; - /// let cell = RefCell::new(5); - /// let old_value = cell.replace_with(|&mut old| old + 1); - /// assert_eq!(old_value, 5); - /// assert_eq!(cell, RefCell::new(6)); - /// ``` - #[inline] - #[stable(feature = "refcell_replace_swap", since = "1.35.0")] - #[track_caller] - pub fn replace_with T>(&self, f: F) -> T { - let mut_borrow = &mut *self.borrow_mut(); - let replacement = f(mut_borrow); - mem::replace(mut_borrow, replacement) - } - - /// Swaps the wrapped value of `self` with the wrapped value of `other`, - /// without deinitializing either one. - /// - /// This function corresponds to [`std::mem::swap`](../mem/fn.swap.html). - /// - /// # Panics - /// - /// Panics if the value in either `RefCell` is currently borrowed, or - /// if `self` and `other` point to the same `RefCell`. - /// - /// # Examples - /// - /// ``` - /// use std::cell::RefCell; - /// let c = RefCell::new(5); - /// let d = RefCell::new(6); - /// c.swap(&d); - /// assert_eq!(c, RefCell::new(6)); - /// assert_eq!(d, RefCell::new(5)); - /// ``` - #[inline] - #[stable(feature = "refcell_swap", since = "1.24.0")] - pub fn swap(&self, other: &Self) { - mem::swap(&mut *self.borrow_mut(), &mut *other.borrow_mut()) - } -} - -impl RefCell { - /// Immutably borrows the wrapped value. - /// - /// The borrow lasts until the returned `Ref` exits scope. Multiple - /// immutable borrows can be taken out at the same time. - /// - /// # Panics - /// - /// Panics if the value is currently mutably borrowed. For a non-panicking variant, use - /// [`try_borrow`](#method.try_borrow). - /// - /// # Examples - /// - /// ``` - /// use std::cell::RefCell; - /// - /// let c = RefCell::new(5); - /// - /// let borrowed_five = c.borrow(); - /// let borrowed_five2 = c.borrow(); - /// ``` - /// - /// An example of panic: - /// - /// ```should_panic - /// use std::cell::RefCell; - /// - /// let c = RefCell::new(5); - /// - /// let m = c.borrow_mut(); - /// let b = c.borrow(); // this causes a panic - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - #[track_caller] - pub fn borrow(&self) -> Ref<'_, T> { - match self.try_borrow() { - Ok(b) => b, - Err(err) => panic_already_mutably_borrowed(err), - } - } - - /// Immutably borrows the wrapped value, returning an error if the value is currently mutably - /// borrowed. - /// - /// The borrow lasts until the returned `Ref` exits scope. Multiple immutable borrows can be - /// taken out at the same time. - /// - /// This is the non-panicking variant of [`borrow`](#method.borrow). - /// - /// # Examples - /// - /// ``` - /// use std::cell::RefCell; - /// - /// let c = RefCell::new(5); - /// - /// { - /// let m = c.borrow_mut(); - /// assert!(c.try_borrow().is_err()); - /// } - /// - /// { - /// let m = c.borrow(); - /// assert!(c.try_borrow().is_ok()); - /// } - /// ``` - #[stable(feature = "try_borrow", since = "1.13.0")] - #[inline] - #[cfg_attr(feature = "debug_refcell", track_caller)] - pub fn try_borrow(&self) -> Result, BorrowError> { - match BorrowRef::new(&self.borrow) { - Some(b) => { - #[cfg(feature = "debug_refcell")] - { - // `borrowed_at` is always the *first* active borrow - if b.borrow.get() == 1 { - self.borrowed_at.set(Some(crate::panic::Location::caller())); - } - } - - // SAFETY: `BorrowRef` ensures that there is only immutable access - // to the value while borrowed. - let value = unsafe { NonNull::new_unchecked(self.value.get()) }; - Ok(Ref { value, borrow: b }) - } - None => Err(BorrowError { - // If a borrow occurred, then we must already have an outstanding borrow, - // so `borrowed_at` will be `Some` - #[cfg(feature = "debug_refcell")] - location: self.borrowed_at.get().unwrap(), - }), - } - } - - /// Mutably borrows the wrapped value. - /// - /// The borrow lasts until the returned `RefMut` or all `RefMut`s derived - /// from it exit scope. The value cannot be borrowed while this borrow is - /// active. - /// - /// # Panics - /// - /// Panics if the value is currently borrowed. For a non-panicking variant, use - /// [`try_borrow_mut`](#method.try_borrow_mut). - /// - /// # Examples - /// - /// ``` - /// use std::cell::RefCell; - /// - /// let c = RefCell::new("hello".to_owned()); - /// - /// *c.borrow_mut() = "bonjour".to_owned(); - /// - /// assert_eq!(&*c.borrow(), "bonjour"); - /// ``` - /// - /// An example of panic: - /// - /// ```should_panic - /// use std::cell::RefCell; - /// - /// let c = RefCell::new(5); - /// let m = c.borrow(); - /// - /// let b = c.borrow_mut(); // this causes a panic - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - #[track_caller] - pub fn borrow_mut(&self) -> RefMut<'_, T> { - match self.try_borrow_mut() { - Ok(b) => b, - Err(err) => panic_already_borrowed(err), - } - } - - /// Mutably borrows the wrapped value, returning an error if the value is currently borrowed. - /// - /// The borrow lasts until the returned `RefMut` or all `RefMut`s derived - /// from it exit scope. The value cannot be borrowed while this borrow is - /// active. - /// - /// This is the non-panicking variant of [`borrow_mut`](#method.borrow_mut). - /// - /// # Examples - /// - /// ``` - /// use std::cell::RefCell; - /// - /// let c = RefCell::new(5); - /// - /// { - /// let m = c.borrow(); - /// assert!(c.try_borrow_mut().is_err()); - /// } - /// - /// assert!(c.try_borrow_mut().is_ok()); - /// ``` - #[stable(feature = "try_borrow", since = "1.13.0")] - #[inline] - #[cfg_attr(feature = "debug_refcell", track_caller)] - pub fn try_borrow_mut(&self) -> Result, BorrowMutError> { - match BorrowRefMut::new(&self.borrow) { - Some(b) => { - #[cfg(feature = "debug_refcell")] - { - self.borrowed_at.set(Some(crate::panic::Location::caller())); - } - - // SAFETY: `BorrowRefMut` guarantees unique access. - let value = unsafe { NonNull::new_unchecked(self.value.get()) }; - Ok(RefMut { value, borrow: b, marker: PhantomData }) - } - None => Err(BorrowMutError { - // If a borrow occurred, then we must already have an outstanding borrow, - // so `borrowed_at` will be `Some` - #[cfg(feature = "debug_refcell")] - location: self.borrowed_at.get().unwrap(), - }), - } - } - - /// Returns a raw pointer to the underlying data in this cell. - /// - /// # Examples - /// - /// ``` - /// use std::cell::RefCell; - /// - /// let c = RefCell::new(5); - /// - /// let ptr = c.as_ptr(); - /// ``` - #[inline] - #[stable(feature = "cell_as_ptr", since = "1.12.0")] - #[rustc_never_returns_null_ptr] - pub fn as_ptr(&self) -> *mut T { - self.value.get() - } - - /// Returns a mutable reference to the underlying data. - /// - /// Since this method borrows `RefCell` mutably, it is statically guaranteed - /// that no borrows to the underlying data exist. The dynamic checks inherent - /// in [`borrow_mut`] and most other methods of `RefCell` are therefore - /// unnecessary. - /// - /// This method can only be called if `RefCell` can be mutably borrowed, - /// which in general is only the case directly after the `RefCell` has - /// been created. In these situations, skipping the aforementioned dynamic - /// borrowing checks may yield better ergonomics and runtime-performance. - /// - /// In most situations where `RefCell` is used, it can't be borrowed mutably. - /// Use [`borrow_mut`] to get mutable access to the underlying data then. - /// - /// [`borrow_mut`]: RefCell::borrow_mut() - /// - /// # Examples - /// - /// ``` - /// use std::cell::RefCell; - /// - /// let mut c = RefCell::new(5); - /// *c.get_mut() += 1; - /// - /// assert_eq!(c, RefCell::new(6)); - /// ``` - #[inline] - #[stable(feature = "cell_get_mut", since = "1.11.0")] - pub fn get_mut(&mut self) -> &mut T { - self.value.get_mut() - } - - /// Undo the effect of leaked guards on the borrow state of the `RefCell`. - /// - /// This call is similar to [`get_mut`] but more specialized. It borrows `RefCell` mutably to - /// ensure no borrows exist and then resets the state tracking shared borrows. This is relevant - /// if some `Ref` or `RefMut` borrows have been leaked. - /// - /// [`get_mut`]: RefCell::get_mut() - /// - /// # Examples - /// - /// ``` - /// #![feature(cell_leak)] - /// use std::cell::RefCell; - /// - /// let mut c = RefCell::new(0); - /// std::mem::forget(c.borrow_mut()); - /// - /// assert!(c.try_borrow().is_err()); - /// c.undo_leak(); - /// assert!(c.try_borrow().is_ok()); - /// ``` - #[unstable(feature = "cell_leak", issue = "69099")] - pub fn undo_leak(&mut self) -> &mut T { - *self.borrow.get_mut() = UNUSED; - self.get_mut() - } - - /// Immutably borrows the wrapped value, returning an error if the value is - /// currently mutably borrowed. - /// - /// # Safety - /// - /// Unlike `RefCell::borrow`, this method is unsafe because it does not - /// return a `Ref`, thus leaving the borrow flag untouched. Mutably - /// borrowing the `RefCell` while the reference returned by this method - /// is alive is undefined behaviour. - /// - /// # Examples - /// - /// ``` - /// use std::cell::RefCell; - /// - /// let c = RefCell::new(5); - /// - /// { - /// let m = c.borrow_mut(); - /// assert!(unsafe { c.try_borrow_unguarded() }.is_err()); - /// } - /// - /// { - /// let m = c.borrow(); - /// assert!(unsafe { c.try_borrow_unguarded() }.is_ok()); - /// } - /// ``` - #[stable(feature = "borrow_state", since = "1.37.0")] - #[inline] - pub unsafe fn try_borrow_unguarded(&self) -> Result<&T, BorrowError> { - if !is_writing(self.borrow.get()) { - // SAFETY: We check that nobody is actively writing now, but it is - // the caller's responsibility to ensure that nobody writes until - // the returned reference is no longer in use. - // Also, `self.value.get()` refers to the value owned by `self` - // and is thus guaranteed to be valid for the lifetime of `self`. - Ok(unsafe { &*self.value.get() }) - } else { - Err(BorrowError { - // If a borrow occurred, then we must already have an outstanding borrow, - // so `borrowed_at` will be `Some` - #[cfg(feature = "debug_refcell")] - location: self.borrowed_at.get().unwrap(), - }) - } - } -} - -impl RefCell { - /// Takes the wrapped value, leaving `Default::default()` in its place. - /// - /// # Panics - /// - /// Panics if the value is currently borrowed. - /// - /// # Examples - /// - /// ``` - /// use std::cell::RefCell; - /// - /// let c = RefCell::new(5); - /// let five = c.take(); - /// - /// assert_eq!(five, 5); - /// assert_eq!(c.into_inner(), 0); - /// ``` - #[stable(feature = "refcell_take", since = "1.50.0")] - pub fn take(&self) -> T { - self.replace(Default::default()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Send for RefCell where T: Send {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl !Sync for RefCell {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for RefCell { - /// # Panics - /// - /// Panics if the value is currently mutably borrowed. - #[inline] - #[track_caller] - fn clone(&self) -> RefCell { - RefCell::new(self.borrow().clone()) - } - - /// # Panics - /// - /// Panics if `source` is currently mutably borrowed. - #[inline] - #[track_caller] - fn clone_from(&mut self, source: &Self) { - self.get_mut().clone_from(&source.borrow()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Default for RefCell { - /// Creates a `RefCell`, with the `Default` value for T. - #[inline] - fn default() -> RefCell { - RefCell::new(Default::default()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for RefCell { - /// # Panics - /// - /// Panics if the value in either `RefCell` is currently mutably borrowed. - #[inline] - fn eq(&self, other: &RefCell) -> bool { - *self.borrow() == *other.borrow() - } -} - -#[stable(feature = "cell_eq", since = "1.2.0")] -impl Eq for RefCell {} - -#[stable(feature = "cell_ord", since = "1.10.0")] -impl PartialOrd for RefCell { - /// # Panics - /// - /// Panics if the value in either `RefCell` is currently mutably borrowed. - #[inline] - fn partial_cmp(&self, other: &RefCell) -> Option { - self.borrow().partial_cmp(&*other.borrow()) - } - - /// # Panics - /// - /// Panics if the value in either `RefCell` is currently mutably borrowed. - #[inline] - fn lt(&self, other: &RefCell) -> bool { - *self.borrow() < *other.borrow() - } - - /// # Panics - /// - /// Panics if the value in either `RefCell` is currently mutably borrowed. - #[inline] - fn le(&self, other: &RefCell) -> bool { - *self.borrow() <= *other.borrow() - } - - /// # Panics - /// - /// Panics if the value in either `RefCell` is currently mutably borrowed. - #[inline] - fn gt(&self, other: &RefCell) -> bool { - *self.borrow() > *other.borrow() - } - - /// # Panics - /// - /// Panics if the value in either `RefCell` is currently mutably borrowed. - #[inline] - fn ge(&self, other: &RefCell) -> bool { - *self.borrow() >= *other.borrow() - } -} - -#[stable(feature = "cell_ord", since = "1.10.0")] -impl Ord for RefCell { - /// # Panics - /// - /// Panics if the value in either `RefCell` is currently mutably borrowed. - #[inline] - fn cmp(&self, other: &RefCell) -> Ordering { - self.borrow().cmp(&*other.borrow()) - } -} - -#[stable(feature = "cell_from", since = "1.12.0")] -impl From for RefCell { - /// Creates a new `RefCell` containing the given value. - fn from(t: T) -> RefCell { - RefCell::new(t) - } -} - -#[unstable(feature = "coerce_unsized", issue = "18598")] -impl, U> CoerceUnsized> for RefCell {} - -struct BorrowRef<'b> { - borrow: &'b Cell, -} - -impl<'b> BorrowRef<'b> { - #[inline] - fn new(borrow: &'b Cell) -> Option> { - let b = borrow.get().wrapping_add(1); - if !is_reading(b) { - // Incrementing borrow can result in a non-reading value (<= 0) in these cases: - // 1. It was < 0, i.e. there are writing borrows, so we can't allow a read borrow - // due to Rust's reference aliasing rules - // 2. It was isize::MAX (the max amount of reading borrows) and it overflowed - // into isize::MIN (the max amount of writing borrows) so we can't allow - // an additional read borrow because isize can't represent so many read borrows - // (this can only happen if you mem::forget more than a small constant amount of - // `Ref`s, which is not good practice) - None - } else { - // Incrementing borrow can result in a reading value (> 0) in these cases: - // 1. It was = 0, i.e. it wasn't borrowed, and we are taking the first read borrow - // 2. It was > 0 and < isize::MAX, i.e. there were read borrows, and isize - // is large enough to represent having one more read borrow - borrow.set(b); - Some(BorrowRef { borrow }) - } - } -} - -impl Drop for BorrowRef<'_> { - #[inline] - fn drop(&mut self) { - let borrow = self.borrow.get(); - debug_assert!(is_reading(borrow)); - self.borrow.set(borrow - 1); - } -} - -impl Clone for BorrowRef<'_> { - #[inline] - fn clone(&self) -> Self { - // Since this Ref exists, we know the borrow flag - // is a reading borrow. - let borrow = self.borrow.get(); - debug_assert!(is_reading(borrow)); - // Prevent the borrow counter from overflowing into - // a writing borrow. - assert!(borrow != BorrowFlag::MAX); - self.borrow.set(borrow + 1); - BorrowRef { borrow: self.borrow } - } -} - -/// Wraps a borrowed reference to a value in a `RefCell` box. -/// A wrapper type for an immutably borrowed value from a `RefCell`. -/// -/// See the [module-level documentation](self) for more. -#[stable(feature = "rust1", since = "1.0.0")] -#[must_not_suspend = "holding a Ref across suspend points can cause BorrowErrors"] -#[rustc_diagnostic_item = "RefCellRef"] -pub struct Ref<'b, T: ?Sized + 'b> { - // NB: we use a pointer instead of `&'b T` to avoid `noalias` violations, because a - // `Ref` argument doesn't hold immutability for its whole scope, only until it drops. - // `NonNull` is also covariant over `T`, just like we would have with `&T`. - value: NonNull, - borrow: BorrowRef<'b>, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Deref for Ref<'_, T> { - type Target = T; - - #[inline] - fn deref(&self) -> &T { - // SAFETY: the value is accessible as long as we hold our borrow. - unsafe { self.value.as_ref() } - } -} - -#[unstable(feature = "deref_pure_trait", issue = "87121")] -unsafe impl DerefPure for Ref<'_, T> {} - -impl<'b, T: ?Sized> Ref<'b, T> { - /// Copies a `Ref`. - /// - /// The `RefCell` is already immutably borrowed, so this cannot fail. - /// - /// This is an associated function that needs to be used as - /// `Ref::clone(...)`. A `Clone` implementation or a method would interfere - /// with the widespread use of `r.borrow().clone()` to clone the contents of - /// a `RefCell`. - #[stable(feature = "cell_extras", since = "1.15.0")] - #[must_use] - #[inline] - pub fn clone(orig: &Ref<'b, T>) -> Ref<'b, T> { - Ref { value: orig.value, borrow: orig.borrow.clone() } - } - - /// Makes a new `Ref` for a component of the borrowed data. - /// - /// The `RefCell` is already immutably borrowed, so this cannot fail. - /// - /// This is an associated function that needs to be used as `Ref::map(...)`. - /// A method would interfere with methods of the same name on the contents - /// of a `RefCell` used through `Deref`. - /// - /// # Examples - /// - /// ``` - /// use std::cell::{RefCell, Ref}; - /// - /// let c = RefCell::new((5, 'b')); - /// let b1: Ref<'_, (u32, char)> = c.borrow(); - /// let b2: Ref<'_, u32> = Ref::map(b1, |t| &t.0); - /// assert_eq!(*b2, 5) - /// ``` - #[stable(feature = "cell_map", since = "1.8.0")] - #[inline] - pub fn map(orig: Ref<'b, T>, f: F) -> Ref<'b, U> - where - F: FnOnce(&T) -> &U, - { - Ref { value: NonNull::from(f(&*orig)), borrow: orig.borrow } - } - - /// Makes a new `Ref` for an optional component of the borrowed data. The - /// original guard is returned as an `Err(..)` if the closure returns - /// `None`. - /// - /// The `RefCell` is already immutably borrowed, so this cannot fail. - /// - /// This is an associated function that needs to be used as - /// `Ref::filter_map(...)`. A method would interfere with methods of the same - /// name on the contents of a `RefCell` used through `Deref`. - /// - /// # Examples - /// - /// ``` - /// use std::cell::{RefCell, Ref}; - /// - /// let c = RefCell::new(vec![1, 2, 3]); - /// let b1: Ref<'_, Vec> = c.borrow(); - /// let b2: Result, _> = Ref::filter_map(b1, |v| v.get(1)); - /// assert_eq!(*b2.unwrap(), 2); - /// ``` - #[stable(feature = "cell_filter_map", since = "1.63.0")] - #[inline] - pub fn filter_map(orig: Ref<'b, T>, f: F) -> Result, Self> - where - F: FnOnce(&T) -> Option<&U>, - { - match f(&*orig) { - Some(value) => Ok(Ref { value: NonNull::from(value), borrow: orig.borrow }), - None => Err(orig), - } - } - - /// Splits a `Ref` into multiple `Ref`s for different components of the - /// borrowed data. - /// - /// The `RefCell` is already immutably borrowed, so this cannot fail. - /// - /// This is an associated function that needs to be used as - /// `Ref::map_split(...)`. A method would interfere with methods of the same - /// name on the contents of a `RefCell` used through `Deref`. - /// - /// # Examples - /// - /// ``` - /// use std::cell::{Ref, RefCell}; - /// - /// let cell = RefCell::new([1, 2, 3, 4]); - /// let borrow = cell.borrow(); - /// let (begin, end) = Ref::map_split(borrow, |slice| slice.split_at(2)); - /// assert_eq!(*begin, [1, 2]); - /// assert_eq!(*end, [3, 4]); - /// ``` - #[stable(feature = "refcell_map_split", since = "1.35.0")] - #[inline] - pub fn map_split(orig: Ref<'b, T>, f: F) -> (Ref<'b, U>, Ref<'b, V>) - where - F: FnOnce(&T) -> (&U, &V), - { - let (a, b) = f(&*orig); - let borrow = orig.borrow.clone(); - ( - Ref { value: NonNull::from(a), borrow }, - Ref { value: NonNull::from(b), borrow: orig.borrow }, - ) - } - - /// Convert into a reference to the underlying data. - /// - /// The underlying `RefCell` can never be mutably borrowed from again and will always appear - /// already immutably borrowed. It is not a good idea to leak more than a constant number of - /// references. The `RefCell` can be immutably borrowed again if only a smaller number of leaks - /// have occurred in total. - /// - /// This is an associated function that needs to be used as - /// `Ref::leak(...)`. A method would interfere with methods of the - /// same name on the contents of a `RefCell` used through `Deref`. - /// - /// # Examples - /// - /// ``` - /// #![feature(cell_leak)] - /// use std::cell::{RefCell, Ref}; - /// let cell = RefCell::new(0); - /// - /// let value = Ref::leak(cell.borrow()); - /// assert_eq!(*value, 0); - /// - /// assert!(cell.try_borrow().is_ok()); - /// assert!(cell.try_borrow_mut().is_err()); - /// ``` - #[unstable(feature = "cell_leak", issue = "69099")] - pub fn leak(orig: Ref<'b, T>) -> &'b T { - // By forgetting this Ref we ensure that the borrow counter in the RefCell can't go back to - // UNUSED within the lifetime `'b`. Resetting the reference tracking state would require a - // unique reference to the borrowed RefCell. No further mutable references can be created - // from the original cell. - mem::forget(orig.borrow); - // SAFETY: after forgetting, we can form a reference for the rest of lifetime `'b`. - unsafe { orig.value.as_ref() } - } -} - -#[unstable(feature = "coerce_unsized", issue = "18598")] -impl<'b, T: ?Sized + Unsize, U: ?Sized> CoerceUnsized> for Ref<'b, T> {} - -#[stable(feature = "std_guard_impls", since = "1.20.0")] -impl fmt::Display for Ref<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - (**self).fmt(f) - } -} - -impl<'b, T: ?Sized> RefMut<'b, T> { - /// Makes a new `RefMut` for a component of the borrowed data, e.g., an enum - /// variant. - /// - /// The `RefCell` is already mutably borrowed, so this cannot fail. - /// - /// This is an associated function that needs to be used as - /// `RefMut::map(...)`. A method would interfere with methods of the same - /// name on the contents of a `RefCell` used through `Deref`. - /// - /// # Examples - /// - /// ``` - /// use std::cell::{RefCell, RefMut}; - /// - /// let c = RefCell::new((5, 'b')); - /// { - /// let b1: RefMut<'_, (u32, char)> = c.borrow_mut(); - /// let mut b2: RefMut<'_, u32> = RefMut::map(b1, |t| &mut t.0); - /// assert_eq!(*b2, 5); - /// *b2 = 42; - /// } - /// assert_eq!(*c.borrow(), (42, 'b')); - /// ``` - #[stable(feature = "cell_map", since = "1.8.0")] - #[inline] - pub fn map(mut orig: RefMut<'b, T>, f: F) -> RefMut<'b, U> - where - F: FnOnce(&mut T) -> &mut U, - { - let value = NonNull::from(f(&mut *orig)); - RefMut { value, borrow: orig.borrow, marker: PhantomData } - } - - /// Makes a new `RefMut` for an optional component of the borrowed data. The - /// original guard is returned as an `Err(..)` if the closure returns - /// `None`. - /// - /// The `RefCell` is already mutably borrowed, so this cannot fail. - /// - /// This is an associated function that needs to be used as - /// `RefMut::filter_map(...)`. A method would interfere with methods of the - /// same name on the contents of a `RefCell` used through `Deref`. - /// - /// # Examples - /// - /// ``` - /// use std::cell::{RefCell, RefMut}; - /// - /// let c = RefCell::new(vec![1, 2, 3]); - /// - /// { - /// let b1: RefMut<'_, Vec> = c.borrow_mut(); - /// let mut b2: Result, _> = RefMut::filter_map(b1, |v| v.get_mut(1)); - /// - /// if let Ok(mut b2) = b2 { - /// *b2 += 2; - /// } - /// } - /// - /// assert_eq!(*c.borrow(), vec![1, 4, 3]); - /// ``` - #[stable(feature = "cell_filter_map", since = "1.63.0")] - #[inline] - pub fn filter_map(mut orig: RefMut<'b, T>, f: F) -> Result, Self> - where - F: FnOnce(&mut T) -> Option<&mut U>, - { - // SAFETY: function holds onto an exclusive reference for the duration - // of its call through `orig`, and the pointer is only de-referenced - // inside of the function call never allowing the exclusive reference to - // escape. - match f(&mut *orig) { - Some(value) => { - Ok(RefMut { value: NonNull::from(value), borrow: orig.borrow, marker: PhantomData }) - } - None => Err(orig), - } - } - - /// Splits a `RefMut` into multiple `RefMut`s for different components of the - /// borrowed data. - /// - /// The underlying `RefCell` will remain mutably borrowed until both - /// returned `RefMut`s go out of scope. - /// - /// The `RefCell` is already mutably borrowed, so this cannot fail. - /// - /// This is an associated function that needs to be used as - /// `RefMut::map_split(...)`. A method would interfere with methods of the - /// same name on the contents of a `RefCell` used through `Deref`. - /// - /// # Examples - /// - /// ``` - /// use std::cell::{RefCell, RefMut}; - /// - /// let cell = RefCell::new([1, 2, 3, 4]); - /// let borrow = cell.borrow_mut(); - /// let (mut begin, mut end) = RefMut::map_split(borrow, |slice| slice.split_at_mut(2)); - /// assert_eq!(*begin, [1, 2]); - /// assert_eq!(*end, [3, 4]); - /// begin.copy_from_slice(&[4, 3]); - /// end.copy_from_slice(&[2, 1]); - /// ``` - #[stable(feature = "refcell_map_split", since = "1.35.0")] - #[inline] - pub fn map_split( - mut orig: RefMut<'b, T>, - f: F, - ) -> (RefMut<'b, U>, RefMut<'b, V>) - where - F: FnOnce(&mut T) -> (&mut U, &mut V), - { - let borrow = orig.borrow.clone(); - let (a, b) = f(&mut *orig); - ( - RefMut { value: NonNull::from(a), borrow, marker: PhantomData }, - RefMut { value: NonNull::from(b), borrow: orig.borrow, marker: PhantomData }, - ) - } - - /// Convert into a mutable reference to the underlying data. - /// - /// The underlying `RefCell` can not be borrowed from again and will always appear already - /// mutably borrowed, making the returned reference the only to the interior. - /// - /// This is an associated function that needs to be used as - /// `RefMut::leak(...)`. A method would interfere with methods of the - /// same name on the contents of a `RefCell` used through `Deref`. - /// - /// # Examples - /// - /// ``` - /// #![feature(cell_leak)] - /// use std::cell::{RefCell, RefMut}; - /// let cell = RefCell::new(0); - /// - /// let value = RefMut::leak(cell.borrow_mut()); - /// assert_eq!(*value, 0); - /// *value = 1; - /// - /// assert!(cell.try_borrow_mut().is_err()); - /// ``` - #[unstable(feature = "cell_leak", issue = "69099")] - pub fn leak(mut orig: RefMut<'b, T>) -> &'b mut T { - // By forgetting this BorrowRefMut we ensure that the borrow counter in the RefCell can't - // go back to UNUSED within the lifetime `'b`. Resetting the reference tracking state would - // require a unique reference to the borrowed RefCell. No further references can be created - // from the original cell within that lifetime, making the current borrow the only - // reference for the remaining lifetime. - mem::forget(orig.borrow); - // SAFETY: after forgetting, we can form a reference for the rest of lifetime `'b`. - unsafe { orig.value.as_mut() } - } -} - -struct BorrowRefMut<'b> { - borrow: &'b Cell, -} - -impl Drop for BorrowRefMut<'_> { - #[inline] - fn drop(&mut self) { - let borrow = self.borrow.get(); - debug_assert!(is_writing(borrow)); - self.borrow.set(borrow + 1); - } -} - -impl<'b> BorrowRefMut<'b> { - #[inline] - fn new(borrow: &'b Cell) -> Option> { - // NOTE: Unlike BorrowRefMut::clone, new is called to create the initial - // mutable reference, and so there must currently be no existing - // references. Thus, while clone increments the mutable refcount, here - // we explicitly only allow going from UNUSED to UNUSED - 1. - match borrow.get() { - UNUSED => { - borrow.set(UNUSED - 1); - Some(BorrowRefMut { borrow }) - } - _ => None, - } - } - - // Clones a `BorrowRefMut`. - // - // This is only valid if each `BorrowRefMut` is used to track a mutable - // reference to a distinct, nonoverlapping range of the original object. - // This isn't in a Clone impl so that code doesn't call this implicitly. - #[inline] - fn clone(&self) -> BorrowRefMut<'b> { - let borrow = self.borrow.get(); - debug_assert!(is_writing(borrow)); - // Prevent the borrow counter from underflowing. - assert!(borrow != BorrowFlag::MIN); - self.borrow.set(borrow - 1); - BorrowRefMut { borrow: self.borrow } - } -} - -/// A wrapper type for a mutably borrowed value from a `RefCell`. -/// -/// See the [module-level documentation](self) for more. -#[stable(feature = "rust1", since = "1.0.0")] -#[must_not_suspend = "holding a RefMut across suspend points can cause BorrowErrors"] -#[rustc_diagnostic_item = "RefCellRefMut"] -pub struct RefMut<'b, T: ?Sized + 'b> { - // NB: we use a pointer instead of `&'b mut T` to avoid `noalias` violations, because a - // `RefMut` argument doesn't hold exclusivity for its whole scope, only until it drops. - value: NonNull, - borrow: BorrowRefMut<'b>, - // `NonNull` is covariant over `T`, so we need to reintroduce invariance. - marker: PhantomData<&'b mut T>, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Deref for RefMut<'_, T> { - type Target = T; - - #[inline] - fn deref(&self) -> &T { - // SAFETY: the value is accessible as long as we hold our borrow. - unsafe { self.value.as_ref() } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DerefMut for RefMut<'_, T> { - #[inline] - fn deref_mut(&mut self) -> &mut T { - // SAFETY: the value is accessible as long as we hold our borrow. - unsafe { self.value.as_mut() } - } -} - -#[unstable(feature = "deref_pure_trait", issue = "87121")] -unsafe impl DerefPure for RefMut<'_, T> {} - -#[unstable(feature = "coerce_unsized", issue = "18598")] -impl<'b, T: ?Sized + Unsize, U: ?Sized> CoerceUnsized> for RefMut<'b, T> {} - -#[stable(feature = "std_guard_impls", since = "1.20.0")] -impl fmt::Display for RefMut<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - (**self).fmt(f) - } -} - -/// The core primitive for interior mutability in Rust. -/// -/// If you have a reference `&T`, then normally in Rust the compiler performs optimizations based on -/// the knowledge that `&T` points to immutable data. Mutating that data, for example through an -/// alias or by transmuting an `&T` into an `&mut T`, is considered undefined behavior. -/// `UnsafeCell` opts-out of the immutability guarantee for `&T`: a shared reference -/// `&UnsafeCell` may point to data that is being mutated. This is called "interior mutability". -/// -/// All other types that allow internal mutability, such as [`Cell`] and [`RefCell`], internally -/// use `UnsafeCell` to wrap their data. -/// -/// Note that only the immutability guarantee for shared references is affected by `UnsafeCell`. The -/// uniqueness guarantee for mutable references is unaffected. There is *no* legal way to obtain -/// aliasing `&mut`, not even with `UnsafeCell`. -/// -/// The `UnsafeCell` API itself is technically very simple: [`.get()`] gives you a raw pointer -/// `*mut T` to its contents. It is up to _you_ as the abstraction designer to use that raw pointer -/// correctly. -/// -/// [`.get()`]: `UnsafeCell::get` -/// -/// The precise Rust aliasing rules are somewhat in flux, but the main points are not contentious: -/// -/// - If you create a safe reference with lifetime `'a` (either a `&T` or `&mut T` reference), then -/// you must not access the data in any way that contradicts that reference for the remainder of -/// `'a`. For example, this means that if you take the `*mut T` from an `UnsafeCell` and cast it -/// to an `&T`, then the data in `T` must remain immutable (modulo any `UnsafeCell` data found -/// within `T`, of course) until that reference's lifetime expires. Similarly, if you create a `&mut -/// T` reference that is released to safe code, then you must not access the data within the -/// `UnsafeCell` until that reference expires. -/// -/// - For both `&T` without `UnsafeCell<_>` and `&mut T`, you must also not deallocate the data -/// until the reference expires. As a special exception, given an `&T`, any part of it that is -/// inside an `UnsafeCell<_>` may be deallocated during the lifetime of the reference, after the -/// last time the reference is used (dereferenced or reborrowed). Since you cannot deallocate a part -/// of what a reference points to, this means the memory an `&T` points to can be deallocated only if -/// *every part of it* (including padding) is inside an `UnsafeCell`. -/// -/// However, whenever a `&UnsafeCell` is constructed or dereferenced, it must still point to -/// live memory and the compiler is allowed to insert spurious reads if it can prove that this -/// memory has not yet been deallocated. -/// -/// - At all times, you must avoid data races. If multiple threads have access to -/// the same `UnsafeCell`, then any writes must have a proper happens-before relation to all other -/// accesses (or use atomics). -/// -/// To assist with proper design, the following scenarios are explicitly declared legal -/// for single-threaded code: -/// -/// 1. A `&T` reference can be released to safe code and there it can co-exist with other `&T` -/// references, but not with a `&mut T` -/// -/// 2. A `&mut T` reference may be released to safe code provided neither other `&mut T` nor `&T` -/// co-exist with it. A `&mut T` must always be unique. -/// -/// Note that whilst mutating the contents of an `&UnsafeCell` (even while other -/// `&UnsafeCell` references alias the cell) is -/// ok (provided you enforce the above invariants some other way), it is still undefined behavior -/// to have multiple `&mut UnsafeCell` aliases. That is, `UnsafeCell` is a wrapper -/// designed to have a special interaction with _shared_ accesses (_i.e._, through an -/// `&UnsafeCell<_>` reference); there is no magic whatsoever when dealing with _exclusive_ -/// accesses (_e.g._, through an `&mut UnsafeCell<_>`): neither the cell nor the wrapped value -/// may be aliased for the duration of that `&mut` borrow. -/// This is showcased by the [`.get_mut()`] accessor, which is a _safe_ getter that yields -/// a `&mut T`. -/// -/// [`.get_mut()`]: `UnsafeCell::get_mut` -/// -/// # Memory layout -/// -/// `UnsafeCell` has the same in-memory representation as its inner type `T`. A consequence -/// of this guarantee is that it is possible to convert between `T` and `UnsafeCell`. -/// Special care has to be taken when converting a nested `T` inside of an `Outer` type -/// to an `Outer>` type: this is not sound when the `Outer` type enables [niche] -/// optimizations. For example, the type `Option>` is typically 8 bytes large on -/// 64-bit platforms, but the type `Option>>` takes up 16 bytes of space. -/// Therefore this is not a valid conversion, despite `NonNull` and `UnsafeCell>>` -/// having the same memory layout. This is because `UnsafeCell` disables niche optimizations in -/// order to avoid its interior mutability property from spreading from `T` into the `Outer` type, -/// thus this can cause distortions in the type size in these cases. -/// -/// Note that the only valid way to obtain a `*mut T` pointer to the contents of a -/// _shared_ `UnsafeCell` is through [`.get()`] or [`.raw_get()`]. A `&mut T` reference -/// can be obtained by either dereferencing this pointer or by calling [`.get_mut()`] -/// on an _exclusive_ `UnsafeCell`. Even though `T` and `UnsafeCell` have the -/// same memory layout, the following is not allowed and undefined behavior: -/// -/// ```rust,compile_fail -/// # use std::cell::UnsafeCell; -/// unsafe fn not_allowed(ptr: &UnsafeCell) -> &mut T { -/// let t = ptr as *const UnsafeCell as *mut T; -/// // This is undefined behavior, because the `*mut T` pointer -/// // was not obtained through `.get()` nor `.raw_get()`: -/// unsafe { &mut *t } -/// } -/// ``` -/// -/// Instead, do this: -/// -/// ```rust -/// # use std::cell::UnsafeCell; -/// // Safety: the caller must ensure that there are no references that -/// // point to the *contents* of the `UnsafeCell`. -/// unsafe fn get_mut(ptr: &UnsafeCell) -> &mut T { -/// unsafe { &mut *ptr.get() } -/// } -/// ``` -/// -/// Converting in the other direction from a `&mut T` -/// to an `&UnsafeCell` is allowed: -/// -/// ```rust -/// # use std::cell::UnsafeCell; -/// fn get_shared(ptr: &mut T) -> &UnsafeCell { -/// let t = ptr as *mut T as *const UnsafeCell; -/// // SAFETY: `T` and `UnsafeCell` have the same memory layout -/// unsafe { &*t } -/// } -/// ``` -/// -/// [niche]: https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#niche -/// [`.raw_get()`]: `UnsafeCell::raw_get` -/// -/// # Examples -/// -/// Here is an example showcasing how to soundly mutate the contents of an `UnsafeCell<_>` despite -/// there being multiple references aliasing the cell: -/// -/// ``` -/// use std::cell::UnsafeCell; -/// -/// let x: UnsafeCell = 42.into(); -/// // Get multiple / concurrent / shared references to the same `x`. -/// let (p1, p2): (&UnsafeCell, &UnsafeCell) = (&x, &x); -/// -/// unsafe { -/// // SAFETY: within this scope there are no other references to `x`'s contents, -/// // so ours is effectively unique. -/// let p1_exclusive: &mut i32 = &mut *p1.get(); // -- borrow --+ -/// *p1_exclusive += 27; // | -/// } // <---------- cannot go beyond this point -------------------+ -/// -/// unsafe { -/// // SAFETY: within this scope nobody expects to have exclusive access to `x`'s contents, -/// // so we can have multiple shared accesses concurrently. -/// let p2_shared: &i32 = &*p2.get(); -/// assert_eq!(*p2_shared, 42 + 27); -/// let p1_shared: &i32 = &*p1.get(); -/// assert_eq!(*p1_shared, *p2_shared); -/// } -/// ``` -/// -/// The following example showcases the fact that exclusive access to an `UnsafeCell` -/// implies exclusive access to its `T`: -/// -/// ```rust -/// #![forbid(unsafe_code)] // with exclusive accesses, -/// // `UnsafeCell` is a transparent no-op wrapper, -/// // so no need for `unsafe` here. -/// use std::cell::UnsafeCell; -/// -/// let mut x: UnsafeCell = 42.into(); -/// -/// // Get a compile-time-checked unique reference to `x`. -/// let p_unique: &mut UnsafeCell = &mut x; -/// // With an exclusive reference, we can mutate the contents for free. -/// *p_unique.get_mut() = 0; -/// // Or, equivalently: -/// x = UnsafeCell::new(0); -/// -/// // When we own the value, we can extract the contents for free. -/// let contents: i32 = x.into_inner(); -/// assert_eq!(contents, 0); -/// ``` -#[lang = "unsafe_cell"] -#[stable(feature = "rust1", since = "1.0.0")] -#[repr(transparent)] -pub struct UnsafeCell { - value: T, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl !Sync for UnsafeCell {} - -impl UnsafeCell { - /// Constructs a new instance of `UnsafeCell` which will wrap the specified - /// value. - /// - /// All access to the inner value through `&UnsafeCell` requires `unsafe` code. - /// - /// # Examples - /// - /// ``` - /// use std::cell::UnsafeCell; - /// - /// let uc = UnsafeCell::new(5); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_unsafe_cell_new", since = "1.32.0")] - #[inline(always)] - pub const fn new(value: T) -> UnsafeCell { - UnsafeCell { value } - } - - /// Unwraps the value, consuming the cell. - /// - /// # Examples - /// - /// ``` - /// use std::cell::UnsafeCell; - /// - /// let uc = UnsafeCell::new(5); - /// - /// let five = uc.into_inner(); - /// ``` - #[inline(always)] - #[stable(feature = "rust1", since = "1.0.0")] - // When this is const stabilized, please remove `primitive_into_inner` below. - #[rustc_const_unstable(feature = "const_cell_into_inner", issue = "78729")] - pub const fn into_inner(self) -> T { - self.value - } -} - -impl UnsafeCell { - /// Converts from `&mut T` to `&mut UnsafeCell`. - /// - /// # Examples - /// - /// ``` - /// # #![feature(unsafe_cell_from_mut)] - /// use std::cell::UnsafeCell; - /// - /// let mut val = 42; - /// let uc = UnsafeCell::from_mut(&mut val); - /// - /// *uc.get_mut() -= 1; - /// assert_eq!(*uc.get_mut(), 41); - /// ``` - #[inline(always)] - #[unstable(feature = "unsafe_cell_from_mut", issue = "111645")] - pub const fn from_mut(value: &mut T) -> &mut UnsafeCell { - // SAFETY: `UnsafeCell` has the same memory layout as `T` due to #[repr(transparent)]. - unsafe { &mut *(value as *mut T as *mut UnsafeCell) } - } - - /// Gets a mutable pointer to the wrapped value. - /// - /// This can be cast to a pointer of any kind. - /// Ensure that the access is unique (no active references, mutable or not) - /// when casting to `&mut T`, and ensure that there are no mutations - /// or mutable aliases going on when casting to `&T` - /// - /// # Examples - /// - /// ``` - /// use std::cell::UnsafeCell; - /// - /// let uc = UnsafeCell::new(5); - /// - /// let five = uc.get(); - /// ``` - #[inline(always)] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_unsafecell_get", since = "1.32.0")] - #[rustc_never_returns_null_ptr] - pub const fn get(&self) -> *mut T { - // We can just cast the pointer from `UnsafeCell` to `T` because of - // #[repr(transparent)]. This exploits std's special status, there is - // no guarantee for user code that this will work in future versions of the compiler! - self as *const UnsafeCell as *const T as *mut T - } - - /// Returns a mutable reference to the underlying data. - /// - /// This call borrows the `UnsafeCell` mutably (at compile-time) which - /// guarantees that we possess the only reference. - /// - /// # Examples - /// - /// ``` - /// use std::cell::UnsafeCell; - /// - /// let mut c = UnsafeCell::new(5); - /// *c.get_mut() += 1; - /// - /// assert_eq!(*c.get_mut(), 6); - /// ``` - #[inline(always)] - #[stable(feature = "unsafe_cell_get_mut", since = "1.50.0")] - #[rustc_const_unstable(feature = "const_unsafecell_get_mut", issue = "88836")] - pub const fn get_mut(&mut self) -> &mut T { - &mut self.value - } - - /// Gets a mutable pointer to the wrapped value. - /// The difference from [`get`] is that this function accepts a raw pointer, - /// which is useful to avoid the creation of temporary references. - /// - /// The result can be cast to a pointer of any kind. - /// Ensure that the access is unique (no active references, mutable or not) - /// when casting to `&mut T`, and ensure that there are no mutations - /// or mutable aliases going on when casting to `&T`. - /// - /// [`get`]: UnsafeCell::get() - /// - /// # Examples - /// - /// Gradual initialization of an `UnsafeCell` requires `raw_get`, as - /// calling `get` would require creating a reference to uninitialized data: - /// - /// ``` - /// use std::cell::UnsafeCell; - /// use std::mem::MaybeUninit; - /// - /// let m = MaybeUninit::>::uninit(); - /// unsafe { UnsafeCell::raw_get(m.as_ptr()).write(5); } - /// // avoid below which references to uninitialized data - /// // unsafe { UnsafeCell::get(&*m.as_ptr()).write(5); } - /// let uc = unsafe { m.assume_init() }; - /// - /// assert_eq!(uc.into_inner(), 5); - /// ``` - #[inline(always)] - #[stable(feature = "unsafe_cell_raw_get", since = "1.56.0")] - #[rustc_const_stable(feature = "unsafe_cell_raw_get", since = "1.56.0")] - #[rustc_diagnostic_item = "unsafe_cell_raw_get"] - pub const fn raw_get(this: *const Self) -> *mut T { - // We can just cast the pointer from `UnsafeCell` to `T` because of - // #[repr(transparent)]. This exploits std's special status, there is - // no guarantee for user code that this will work in future versions of the compiler! - this as *const T as *mut T - } -} - -#[stable(feature = "unsafe_cell_default", since = "1.10.0")] -impl Default for UnsafeCell { - /// Creates an `UnsafeCell`, with the `Default` value for T. - fn default() -> UnsafeCell { - UnsafeCell::new(Default::default()) - } -} - -#[stable(feature = "cell_from", since = "1.12.0")] -impl From for UnsafeCell { - /// Creates a new `UnsafeCell` containing the given value. - fn from(t: T) -> UnsafeCell { - UnsafeCell::new(t) - } -} - -#[unstable(feature = "coerce_unsized", issue = "18598")] -impl, U> CoerceUnsized> for UnsafeCell {} - -// Allow types that wrap `UnsafeCell` to also implement `DispatchFromDyn` -// and become object safe method receivers. -// Note that currently `UnsafeCell` itself cannot be a method receiver -// because it does not implement Deref. -// In other words: -// `self: UnsafeCell<&Self>` won't work -// `self: UnsafeCellWrapper` becomes possible -#[unstable(feature = "dispatch_from_dyn", issue = "none")] -impl, U> DispatchFromDyn> for UnsafeCell {} - -// Special cases of UnsafeCell::into_inner where T is a primitive. These are -// used by Atomic*::into_inner. -// -// The real UnsafeCell::into_inner cannot be used yet in a stable const function. -// That is blocked on a "precise drop analysis" unstable const feature. -// https://github.com/rust-lang/rust/issues/73255 -macro_rules! unsafe_cell_primitive_into_inner { - ($($primitive:ident $atomic:literal)*) => { - $( - #[cfg(target_has_atomic_load_store = $atomic)] - impl UnsafeCell<$primitive> { - pub(crate) const fn primitive_into_inner(self) -> $primitive { - self.value - } - } - )* - }; -} - -unsafe_cell_primitive_into_inner! { - i8 "8" - u8 "8" - i16 "16" - u16 "16" - i32 "32" - u32 "32" - i64 "64" - u64 "64" - i128 "128" - u128 "128" - isize "ptr" - usize "ptr" -} - -#[cfg(target_has_atomic_load_store = "ptr")] -impl UnsafeCell<*mut T> { - pub(crate) const fn primitive_into_inner(self) -> *mut T { - self.value - } -} - -/// [`UnsafeCell`], but [`Sync`]. -/// -/// This is just an `UnsafeCell`, except it implements `Sync` -/// if `T` implements `Sync`. -/// -/// `UnsafeCell` doesn't implement `Sync`, to prevent accidental mis-use. -/// You can use `SyncUnsafeCell` instead of `UnsafeCell` to allow it to be -/// shared between threads, if that's intentional. -/// Providing proper synchronization is still the task of the user, -/// making this type just as unsafe to use. -/// -/// See [`UnsafeCell`] for details. -#[unstable(feature = "sync_unsafe_cell", issue = "95439")] -#[repr(transparent)] -pub struct SyncUnsafeCell { - value: UnsafeCell, -} - -#[unstable(feature = "sync_unsafe_cell", issue = "95439")] -unsafe impl Sync for SyncUnsafeCell {} - -#[unstable(feature = "sync_unsafe_cell", issue = "95439")] -impl SyncUnsafeCell { - /// Constructs a new instance of `SyncUnsafeCell` which will wrap the specified value. - #[inline] - pub const fn new(value: T) -> Self { - Self { value: UnsafeCell { value } } - } - - /// Unwraps the value, consuming the cell. - #[inline] - pub const fn into_inner(self) -> T { - self.value.into_inner() - } -} - -#[unstable(feature = "sync_unsafe_cell", issue = "95439")] -impl SyncUnsafeCell { - /// Gets a mutable pointer to the wrapped value. - /// - /// This can be cast to a pointer of any kind. - /// Ensure that the access is unique (no active references, mutable or not) - /// when casting to `&mut T`, and ensure that there are no mutations - /// or mutable aliases going on when casting to `&T` - #[inline] - #[rustc_never_returns_null_ptr] - pub const fn get(&self) -> *mut T { - self.value.get() - } - - /// Returns a mutable reference to the underlying data. - /// - /// This call borrows the `SyncUnsafeCell` mutably (at compile-time) which - /// guarantees that we possess the only reference. - #[inline] - pub const fn get_mut(&mut self) -> &mut T { - self.value.get_mut() - } - - /// Gets a mutable pointer to the wrapped value. - /// - /// See [`UnsafeCell::get`] for details. - #[inline] - pub const fn raw_get(this: *const Self) -> *mut T { - // We can just cast the pointer from `SyncUnsafeCell` to `T` because - // of #[repr(transparent)] on both SyncUnsafeCell and UnsafeCell. - // See UnsafeCell::raw_get. - this as *const T as *mut T - } -} - -#[unstable(feature = "sync_unsafe_cell", issue = "95439")] -impl Default for SyncUnsafeCell { - /// Creates an `SyncUnsafeCell`, with the `Default` value for T. - fn default() -> SyncUnsafeCell { - SyncUnsafeCell::new(Default::default()) - } -} - -#[unstable(feature = "sync_unsafe_cell", issue = "95439")] -impl From for SyncUnsafeCell { - /// Creates a new `SyncUnsafeCell` containing the given value. - fn from(t: T) -> SyncUnsafeCell { - SyncUnsafeCell::new(t) - } -} - -#[unstable(feature = "coerce_unsized", issue = "18598")] -//#[unstable(feature = "sync_unsafe_cell", issue = "95439")] -impl, U> CoerceUnsized> for SyncUnsafeCell {} - -// Allow types that wrap `SyncUnsafeCell` to also implement `DispatchFromDyn` -// and become object safe method receivers. -// Note that currently `SyncUnsafeCell` itself cannot be a method receiver -// because it does not implement Deref. -// In other words: -// `self: SyncUnsafeCell<&Self>` won't work -// `self: SyncUnsafeCellWrapper` becomes possible -#[unstable(feature = "dispatch_from_dyn", issue = "none")] -//#[unstable(feature = "sync_unsafe_cell", issue = "95439")] -impl, U> DispatchFromDyn> for SyncUnsafeCell {} - -#[allow(unused)] -fn assert_coerce_unsized( - a: UnsafeCell<&i32>, - b: SyncUnsafeCell<&i32>, - c: Cell<&i32>, - d: RefCell<&i32>, -) { - let _: UnsafeCell<&dyn Send> = a; - let _: SyncUnsafeCell<&dyn Send> = b; - let _: Cell<&dyn Send> = c; - let _: RefCell<&dyn Send> = d; -} diff --git a/library/core/src/cell/lazy.rs b/library/core/src/cell/lazy.rs deleted file mode 100644 index 1b213f6a2941b..0000000000000 --- a/library/core/src/cell/lazy.rs +++ /dev/null @@ -1,204 +0,0 @@ -use crate::ops::Deref; -use crate::{fmt, mem}; - -use super::UnsafeCell; - -enum State { - Uninit(F), - Init(T), - Poisoned, -} - -/// A value which is initialized on the first access. -/// -/// For a thread-safe version of this struct, see [`std::sync::LazyLock`]. -/// -/// [`std::sync::LazyLock`]: ../../std/sync/struct.LazyLock.html -/// -/// # Examples -/// -/// ``` -/// #![feature(lazy_cell)] -/// -/// use std::cell::LazyCell; -/// -/// let lazy: LazyCell = LazyCell::new(|| { -/// println!("initializing"); -/// 92 -/// }); -/// println!("ready"); -/// println!("{}", *lazy); -/// println!("{}", *lazy); -/// -/// // Prints: -/// // ready -/// // initializing -/// // 92 -/// // 92 -/// ``` -#[unstable(feature = "lazy_cell", issue = "109736")] -pub struct LazyCell T> { - state: UnsafeCell>, -} - -impl T> LazyCell { - /// Creates a new lazy value with the given initializing function. - /// - /// # Examples - /// - /// ``` - /// #![feature(lazy_cell)] - /// - /// use std::cell::LazyCell; - /// - /// let hello = "Hello, World!".to_string(); - /// - /// let lazy = LazyCell::new(|| hello.to_uppercase()); - /// - /// assert_eq!(&*lazy, "HELLO, WORLD!"); - /// ``` - #[inline] - #[unstable(feature = "lazy_cell", issue = "109736")] - pub const fn new(f: F) -> LazyCell { - LazyCell { state: UnsafeCell::new(State::Uninit(f)) } - } - - /// Consumes this `LazyCell` returning the stored value. - /// - /// Returns `Ok(value)` if `Lazy` is initialized and `Err(f)` otherwise. - /// - /// # Examples - /// - /// ``` - /// #![feature(lazy_cell)] - /// #![feature(lazy_cell_consume)] - /// - /// use std::cell::LazyCell; - /// - /// let hello = "Hello, World!".to_string(); - /// - /// let lazy = LazyCell::new(|| hello.to_uppercase()); - /// - /// assert_eq!(&*lazy, "HELLO, WORLD!"); - /// assert_eq!(LazyCell::into_inner(lazy).ok(), Some("HELLO, WORLD!".to_string())); - /// ``` - #[unstable(feature = "lazy_cell_consume", issue = "109736")] - pub fn into_inner(this: Self) -> Result { - match this.state.into_inner() { - State::Init(data) => Ok(data), - State::Uninit(f) => Err(f), - State::Poisoned => panic!("LazyCell instance has previously been poisoned"), - } - } - - /// Forces the evaluation of this lazy value and returns a reference to - /// the result. - /// - /// This is equivalent to the `Deref` impl, but is explicit. - /// - /// # Examples - /// - /// ``` - /// #![feature(lazy_cell)] - /// - /// use std::cell::LazyCell; - /// - /// let lazy = LazyCell::new(|| 92); - /// - /// assert_eq!(LazyCell::force(&lazy), &92); - /// assert_eq!(&*lazy, &92); - /// ``` - #[inline] - #[unstable(feature = "lazy_cell", issue = "109736")] - pub fn force(this: &LazyCell) -> &T { - // SAFETY: - // This invalidates any mutable references to the data. The resulting - // reference lives either until the end of the borrow of `this` (in the - // initialized case) or is invalidated in `really_init` (in the - // uninitialized case; `really_init` will create and return a fresh reference). - let state = unsafe { &*this.state.get() }; - match state { - State::Init(data) => data, - // SAFETY: The state is uninitialized. - State::Uninit(_) => unsafe { LazyCell::really_init(this) }, - State::Poisoned => panic!("LazyCell has previously been poisoned"), - } - } - - /// # Safety - /// May only be called when the state is `Uninit`. - #[cold] - unsafe fn really_init(this: &LazyCell) -> &T { - // SAFETY: - // This function is only called when the state is uninitialized, - // so no references to `state` can exist except for the reference - // in `force`, which is invalidated here and not accessed again. - let state = unsafe { &mut *this.state.get() }; - // Temporarily mark the state as poisoned. This prevents reentrant - // accesses and correctly poisons the cell if the closure panicked. - let State::Uninit(f) = mem::replace(state, State::Poisoned) else { unreachable!() }; - - let data = f(); - - // SAFETY: - // If the closure accessed the cell through something like a reentrant - // mutex, but caught the panic resulting from the state being poisoned, - // the mutable borrow for `state` will be invalidated, so we need to - // go through the `UnsafeCell` pointer here. The state can only be - // poisoned at this point, so using `write` to skip the destructor - // of `State` should help the optimizer. - unsafe { this.state.get().write(State::Init(data)) }; - - // SAFETY: - // The previous references were invalidated by the `write` call above, - // so do a new shared borrow of the state instead. - let state = unsafe { &*this.state.get() }; - let State::Init(data) = state else { unreachable!() }; - data - } -} - -impl LazyCell { - #[inline] - fn get(&self) -> Option<&T> { - // SAFETY: - // This is sound for the same reason as in `force`: once the state is - // initialized, it will not be mutably accessed again, so this reference - // will stay valid for the duration of the borrow to `self`. - let state = unsafe { &*self.state.get() }; - match state { - State::Init(data) => Some(data), - _ => None, - } - } -} - -#[unstable(feature = "lazy_cell", issue = "109736")] -impl T> Deref for LazyCell { - type Target = T; - #[inline] - fn deref(&self) -> &T { - LazyCell::force(self) - } -} - -#[unstable(feature = "lazy_cell", issue = "109736")] -impl Default for LazyCell { - /// Creates a new lazy value using `Default` as the initializing function. - #[inline] - fn default() -> LazyCell { - LazyCell::new(T::default) - } -} - -#[unstable(feature = "lazy_cell", issue = "109736")] -impl fmt::Debug for LazyCell { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let mut d = f.debug_tuple("LazyCell"); - match self.get() { - Some(data) => d.field(data), - None => d.field(&format_args!("")), - }; - d.finish() - } -} diff --git a/library/core/src/cell/once.rs b/library/core/src/cell/once.rs deleted file mode 100644 index a7c3dfc982d12..0000000000000 --- a/library/core/src/cell/once.rs +++ /dev/null @@ -1,402 +0,0 @@ -use crate::cell::UnsafeCell; -use crate::fmt; -use crate::mem; - -/// A cell which can be written to only once. -/// -/// This allows obtaining a shared `&T` reference to its inner value without copying or replacing -/// it (unlike [`Cell`]), and without runtime borrow checks (unlike [`RefCell`]). However, -/// only immutable references can be obtained unless one has a mutable reference to the cell -/// itself. -/// -/// For a thread-safe version of this struct, see [`std::sync::OnceLock`]. -/// -/// [`RefCell`]: crate::cell::RefCell -/// [`Cell`]: crate::cell::Cell -/// [`std::sync::OnceLock`]: ../../std/sync/struct.OnceLock.html -/// -/// # Examples -/// -/// ``` -/// use std::cell::OnceCell; -/// -/// let cell = OnceCell::new(); -/// assert!(cell.get().is_none()); -/// -/// let value: &String = cell.get_or_init(|| { -/// "Hello, World!".to_string() -/// }); -/// assert_eq!(value, "Hello, World!"); -/// assert!(cell.get().is_some()); -/// ``` -#[stable(feature = "once_cell", since = "1.70.0")] -pub struct OnceCell { - // Invariant: written to at most once. - inner: UnsafeCell>, -} - -impl OnceCell { - /// Creates a new empty cell. - #[inline] - #[must_use] - #[stable(feature = "once_cell", since = "1.70.0")] - #[rustc_const_stable(feature = "once_cell", since = "1.70.0")] - pub const fn new() -> OnceCell { - OnceCell { inner: UnsafeCell::new(None) } - } - - /// Gets the reference to the underlying value. - /// - /// Returns `None` if the cell is empty. - #[inline] - #[stable(feature = "once_cell", since = "1.70.0")] - pub fn get(&self) -> Option<&T> { - // SAFETY: Safe due to `inner`'s invariant - unsafe { &*self.inner.get() }.as_ref() - } - - /// Gets the mutable reference to the underlying value. - /// - /// Returns `None` if the cell is empty. - #[inline] - #[stable(feature = "once_cell", since = "1.70.0")] - pub fn get_mut(&mut self) -> Option<&mut T> { - self.inner.get_mut().as_mut() - } - - /// Sets the contents of the cell to `value`. - /// - /// # Errors - /// - /// This method returns `Ok(())` if the cell was empty and `Err(value)` if - /// it was full. - /// - /// # Examples - /// - /// ``` - /// use std::cell::OnceCell; - /// - /// let cell = OnceCell::new(); - /// assert!(cell.get().is_none()); - /// - /// assert_eq!(cell.set(92), Ok(())); - /// assert_eq!(cell.set(62), Err(62)); - /// - /// assert!(cell.get().is_some()); - /// ``` - #[inline] - #[stable(feature = "once_cell", since = "1.70.0")] - pub fn set(&self, value: T) -> Result<(), T> { - match self.try_insert(value) { - Ok(_) => Ok(()), - Err((_, value)) => Err(value), - } - } - - /// Sets the contents of the cell to `value` if the cell was empty, then - /// returns a reference to it. - /// - /// # Errors - /// - /// This method returns `Ok(&value)` if the cell was empty and - /// `Err(¤t_value, value)` if it was full. - /// - /// # Examples - /// - /// ``` - /// #![feature(once_cell_try_insert)] - /// - /// use std::cell::OnceCell; - /// - /// let cell = OnceCell::new(); - /// assert!(cell.get().is_none()); - /// - /// assert_eq!(cell.try_insert(92), Ok(&92)); - /// assert_eq!(cell.try_insert(62), Err((&92, 62))); - /// - /// assert!(cell.get().is_some()); - /// ``` - #[inline] - #[unstable(feature = "once_cell_try_insert", issue = "116693")] - pub fn try_insert(&self, value: T) -> Result<&T, (&T, T)> { - if let Some(old) = self.get() { - return Err((old, value)); - } - - // SAFETY: This is the only place where we set the slot, no races - // due to reentrancy/concurrency are possible, and we've - // checked that slot is currently `None`, so this write - // maintains the `inner`'s invariant. - let slot = unsafe { &mut *self.inner.get() }; - Ok(slot.insert(value)) - } - - /// Gets the contents of the cell, initializing it with `f` - /// if the cell was empty. - /// - /// # Panics - /// - /// If `f` panics, the panic is propagated to the caller, and the cell - /// remains uninitialized. - /// - /// It is an error to reentrantly initialize the cell from `f`. Doing - /// so results in a panic. - /// - /// # Examples - /// - /// ``` - /// use std::cell::OnceCell; - /// - /// let cell = OnceCell::new(); - /// let value = cell.get_or_init(|| 92); - /// assert_eq!(value, &92); - /// let value = cell.get_or_init(|| unreachable!()); - /// assert_eq!(value, &92); - /// ``` - #[inline] - #[stable(feature = "once_cell", since = "1.70.0")] - pub fn get_or_init(&self, f: F) -> &T - where - F: FnOnce() -> T, - { - match self.get_or_try_init(|| Ok::(f())) { - Ok(val) => val, - } - } - - /// Gets the mutable reference of the contents of the cell, - /// initializing it with `f` if the cell was empty. - /// - /// # Panics - /// - /// If `f` panics, the panic is propagated to the caller, and the cell - /// remains uninitialized. - /// - /// # Examples - /// - /// ``` - /// #![feature(once_cell_get_mut)] - /// - /// use std::cell::OnceCell; - /// - /// let mut cell = OnceCell::new(); - /// let value = cell.get_mut_or_init(|| 92); - /// assert_eq!(*value, 92); - /// - /// *value += 2; - /// assert_eq!(*value, 94); - /// - /// let value = cell.get_mut_or_init(|| unreachable!()); - /// assert_eq!(*value, 94); - /// ``` - #[inline] - #[unstable(feature = "once_cell_get_mut", issue = "121641")] - pub fn get_mut_or_init(&mut self, f: F) -> &mut T - where - F: FnOnce() -> T, - { - match self.get_mut_or_try_init(|| Ok::(f())) { - Ok(val) => val, - } - } - - /// Gets the contents of the cell, initializing it with `f` if - /// the cell was empty. If the cell was empty and `f` failed, an - /// error is returned. - /// - /// # Panics - /// - /// If `f` panics, the panic is propagated to the caller, and the cell - /// remains uninitialized. - /// - /// It is an error to reentrantly initialize the cell from `f`. Doing - /// so results in a panic. - /// - /// # Examples - /// - /// ``` - /// #![feature(once_cell_try)] - /// - /// use std::cell::OnceCell; - /// - /// let cell = OnceCell::new(); - /// assert_eq!(cell.get_or_try_init(|| Err(())), Err(())); - /// assert!(cell.get().is_none()); - /// let value = cell.get_or_try_init(|| -> Result { - /// Ok(92) - /// }); - /// assert_eq!(value, Ok(&92)); - /// assert_eq!(cell.get(), Some(&92)) - /// ``` - #[unstable(feature = "once_cell_try", issue = "109737")] - pub fn get_or_try_init(&self, f: F) -> Result<&T, E> - where - F: FnOnce() -> Result, - { - if let Some(val) = self.get() { - return Ok(val); - } - self.try_init(f) - } - - /// Gets the mutable reference of the contents of the cell, initializing - /// it with `f` if the cell was empty. If the cell was empty and `f` failed, - /// an error is returned. - /// - /// # Panics - /// - /// If `f` panics, the panic is propagated to the caller, and the cell - /// remains uninitialized. - /// - /// # Examples - /// - /// ``` - /// #![feature(once_cell_get_mut)] - /// - /// use std::cell::OnceCell; - /// - /// let mut cell: OnceCell = OnceCell::new(); - /// - /// // Failed initializers do not change the value - /// assert!(cell.get_mut_or_try_init(|| "not a number!".parse()).is_err()); - /// assert!(cell.get().is_none()); - /// - /// let value = cell.get_mut_or_try_init(|| "1234".parse()); - /// assert_eq!(value, Ok(&mut 1234)); - /// *value.unwrap() += 2; - /// assert_eq!(cell.get(), Some(&1236)) - /// ``` - #[unstable(feature = "once_cell_get_mut", issue = "121641")] - pub fn get_mut_or_try_init(&mut self, f: F) -> Result<&mut T, E> - where - F: FnOnce() -> Result, - { - if self.get().is_none() { - self.try_init(f)?; - } - Ok(self.get_mut().unwrap()) - } - - // Avoid inlining the initialization closure into the common path that fetches - // the already initialized value - #[cold] - fn try_init(&self, f: F) -> Result<&T, E> - where - F: FnOnce() -> Result, - { - let val = f()?; - // Note that *some* forms of reentrant initialization might lead to - // UB (see `reentrant_init` test). I believe that just removing this - // `panic`, while keeping `try_insert` would be sound, but it seems - // better to panic, rather than to silently use an old value. - if let Ok(val) = self.try_insert(val) { Ok(val) } else { panic!("reentrant init") } - } - - /// Consumes the cell, returning the wrapped value. - /// - /// Returns `None` if the cell was empty. - /// - /// # Examples - /// - /// ``` - /// use std::cell::OnceCell; - /// - /// let cell: OnceCell = OnceCell::new(); - /// assert_eq!(cell.into_inner(), None); - /// - /// let cell = OnceCell::new(); - /// cell.set("hello".to_string()).unwrap(); - /// assert_eq!(cell.into_inner(), Some("hello".to_string())); - /// ``` - #[inline] - #[stable(feature = "once_cell", since = "1.70.0")] - pub fn into_inner(self) -> Option { - // Because `into_inner` takes `self` by value, the compiler statically verifies - // that it is not currently borrowed. So it is safe to move out `Option`. - self.inner.into_inner() - } - - /// Takes the value out of this `OnceCell`, moving it back to an uninitialized state. - /// - /// Has no effect and returns `None` if the `OnceCell` hasn't been initialized. - /// - /// Safety is guaranteed by requiring a mutable reference. - /// - /// # Examples - /// - /// ``` - /// use std::cell::OnceCell; - /// - /// let mut cell: OnceCell = OnceCell::new(); - /// assert_eq!(cell.take(), None); - /// - /// let mut cell = OnceCell::new(); - /// cell.set("hello".to_string()).unwrap(); - /// assert_eq!(cell.take(), Some("hello".to_string())); - /// assert_eq!(cell.get(), None); - /// ``` - #[inline] - #[stable(feature = "once_cell", since = "1.70.0")] - pub fn take(&mut self) -> Option { - mem::take(self).into_inner() - } -} - -#[stable(feature = "once_cell", since = "1.70.0")] -impl Default for OnceCell { - #[inline] - fn default() -> Self { - Self::new() - } -} - -#[stable(feature = "once_cell", since = "1.70.0")] -impl fmt::Debug for OnceCell { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let mut d = f.debug_tuple("OnceCell"); - match self.get() { - Some(v) => d.field(v), - None => d.field(&format_args!("")), - }; - d.finish() - } -} - -#[stable(feature = "once_cell", since = "1.70.0")] -impl Clone for OnceCell { - #[inline] - fn clone(&self) -> OnceCell { - let res = OnceCell::new(); - if let Some(value) = self.get() { - match res.set(value.clone()) { - Ok(()) => (), - Err(_) => unreachable!(), - } - } - res - } -} - -#[stable(feature = "once_cell", since = "1.70.0")] -impl PartialEq for OnceCell { - #[inline] - fn eq(&self, other: &Self) -> bool { - self.get() == other.get() - } -} - -#[stable(feature = "once_cell", since = "1.70.0")] -impl Eq for OnceCell {} - -#[stable(feature = "once_cell", since = "1.70.0")] -impl From for OnceCell { - /// Creates a new `OnceCell` which already contains the given `value`. - #[inline] - fn from(value: T) -> Self { - OnceCell { inner: UnsafeCell::new(Some(value)) } - } -} - -// Just like for `Cell` this isn't needed, but results in nicer error messages. -#[stable(feature = "once_cell", since = "1.70.0")] -impl !Sync for OnceCell {} diff --git a/library/core/src/char/convert.rs b/library/core/src/char/convert.rs deleted file mode 100644 index f0c2636307fcf..0000000000000 --- a/library/core/src/char/convert.rs +++ /dev/null @@ -1,292 +0,0 @@ -//! Character conversions. - -use crate::char::TryFromCharError; -use crate::error::Error; -use crate::fmt; -use crate::mem::transmute; -use crate::str::FromStr; -use crate::ub_checks::assert_unsafe_precondition; - -/// Converts a `u32` to a `char`. See [`char::from_u32`]. -#[must_use] -#[inline] -pub(super) const fn from_u32(i: u32) -> Option { - // FIXME: once Result::ok is const fn, use it here - match char_try_from_u32(i) { - Ok(c) => Some(c), - Err(_) => None, - } -} - -/// Converts a `u32` to a `char`, ignoring validity. See [`char::from_u32_unchecked`]. -#[inline] -#[must_use] -pub(super) const unsafe fn from_u32_unchecked(i: u32) -> char { - // SAFETY: the caller must guarantee that `i` is a valid char value. - unsafe { - assert_unsafe_precondition!( - check_language_ub, - "invalid value for `char`", - (i: u32 = i) => char_try_from_u32(i).is_ok() - ); - transmute(i) - } -} - -#[stable(feature = "char_convert", since = "1.13.0")] -impl From for u32 { - /// Converts a [`char`] into a [`u32`]. - /// - /// # Examples - /// - /// ``` - /// use std::mem; - /// - /// let c = 'c'; - /// let u = u32::from(c); - /// assert!(4 == mem::size_of_val(&u)) - /// ``` - #[inline] - fn from(c: char) -> Self { - c as u32 - } -} - -#[stable(feature = "more_char_conversions", since = "1.51.0")] -impl From for u64 { - /// Converts a [`char`] into a [`u64`]. - /// - /// # Examples - /// - /// ``` - /// use std::mem; - /// - /// let c = '👤'; - /// let u = u64::from(c); - /// assert!(8 == mem::size_of_val(&u)) - /// ``` - #[inline] - fn from(c: char) -> Self { - // The char is casted to the value of the code point, then zero-extended to 64 bit. - // See [https://doc.rust-lang.org/reference/expressions/operator-expr.html#semantics] - c as u64 - } -} - -#[stable(feature = "more_char_conversions", since = "1.51.0")] -impl From for u128 { - /// Converts a [`char`] into a [`u128`]. - /// - /// # Examples - /// - /// ``` - /// use std::mem; - /// - /// let c = '⚙'; - /// let u = u128::from(c); - /// assert!(16 == mem::size_of_val(&u)) - /// ``` - #[inline] - fn from(c: char) -> Self { - // The char is casted to the value of the code point, then zero-extended to 128 bit. - // See [https://doc.rust-lang.org/reference/expressions/operator-expr.html#semantics] - c as u128 - } -} - -/// Maps a `char` with code point in U+0000..=U+00FF to a byte in 0x00..=0xFF with same value, -/// failing if the code point is greater than U+00FF. -/// -/// See [`impl From for char`](char#impl-From-for-char) for details on the encoding. -#[stable(feature = "u8_from_char", since = "1.59.0")] -impl TryFrom for u8 { - type Error = TryFromCharError; - - /// Tries to convert a [`char`] into a [`u8`]. - /// - /// # Examples - /// - /// ``` - /// let a = 'ÿ'; // U+00FF - /// let b = 'Ā'; // U+0100 - /// assert_eq!(u8::try_from(a), Ok(0xFF_u8)); - /// assert!(u8::try_from(b).is_err()); - /// ``` - #[inline] - fn try_from(c: char) -> Result { - u8::try_from(u32::from(c)).map_err(|_| TryFromCharError(())) - } -} - -/// Maps a `char` with code point in U+0000..=U+FFFF to a `u16` in 0x0000..=0xFFFF with same value, -/// failing if the code point is greater than U+FFFF. -/// -/// This corresponds to the UCS-2 encoding, as specified in ISO/IEC 10646:2003. -#[stable(feature = "u16_from_char", since = "1.74.0")] -impl TryFrom for u16 { - type Error = TryFromCharError; - - /// Tries to convert a [`char`] into a [`u16`]. - /// - /// # Examples - /// - /// ``` - /// let trans_rights = '⚧'; // U+26A7 - /// let ninjas = '🥷'; // U+1F977 - /// assert_eq!(u16::try_from(trans_rights), Ok(0x26A7_u16)); - /// assert!(u16::try_from(ninjas).is_err()); - /// ``` - #[inline] - fn try_from(c: char) -> Result { - u16::try_from(u32::from(c)).map_err(|_| TryFromCharError(())) - } -} - -/// Maps a byte in 0x00..=0xFF to a `char` whose code point has the same value, in U+0000..=U+00FF. -/// -/// Unicode is designed such that this effectively decodes bytes -/// with the character encoding that IANA calls ISO-8859-1. -/// This encoding is compatible with ASCII. -/// -/// Note that this is different from ISO/IEC 8859-1 a.k.a. ISO 8859-1 (with one less hyphen), -/// which leaves some "blanks", byte values that are not assigned to any character. -/// ISO-8859-1 (the IANA one) assigns them to the C0 and C1 control codes. -/// -/// Note that this is *also* different from Windows-1252 a.k.a. code page 1252, -/// which is a superset ISO/IEC 8859-1 that assigns some (not all!) blanks -/// to punctuation and various Latin characters. -/// -/// To confuse things further, [on the Web](https://encoding.spec.whatwg.org/) -/// `ascii`, `iso-8859-1`, and `windows-1252` are all aliases -/// for a superset of Windows-1252 that fills the remaining blanks with corresponding -/// C0 and C1 control codes. -#[stable(feature = "char_convert", since = "1.13.0")] -impl From for char { - /// Converts a [`u8`] into a [`char`]. - /// - /// # Examples - /// - /// ``` - /// use std::mem; - /// - /// let u = 32 as u8; - /// let c = char::from(u); - /// assert!(4 == mem::size_of_val(&c)) - /// ``` - #[inline] - fn from(i: u8) -> Self { - i as char - } -} - -/// An error which can be returned when parsing a char. -/// -/// This `struct` is created when using the [`char::from_str`] method. -#[stable(feature = "char_from_str", since = "1.20.0")] -#[derive(Clone, Debug, PartialEq, Eq)] -pub struct ParseCharError { - kind: CharErrorKind, -} - -#[derive(Copy, Clone, Debug, PartialEq, Eq)] -enum CharErrorKind { - EmptyString, - TooManyChars, -} - -#[stable(feature = "char_from_str", since = "1.20.0")] -impl Error for ParseCharError { - #[allow(deprecated)] - fn description(&self) -> &str { - match self.kind { - CharErrorKind::EmptyString => "cannot parse char from empty string", - CharErrorKind::TooManyChars => "too many characters in string", - } - } -} - -#[stable(feature = "char_from_str", since = "1.20.0")] -impl fmt::Display for ParseCharError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - #[allow(deprecated)] - self.description().fmt(f) - } -} - -#[stable(feature = "char_from_str", since = "1.20.0")] -impl FromStr for char { - type Err = ParseCharError; - - #[inline] - fn from_str(s: &str) -> Result { - let mut chars = s.chars(); - match (chars.next(), chars.next()) { - (None, _) => Err(ParseCharError { kind: CharErrorKind::EmptyString }), - (Some(c), None) => Ok(c), - _ => Err(ParseCharError { kind: CharErrorKind::TooManyChars }), - } - } -} - -#[inline] -const fn char_try_from_u32(i: u32) -> Result { - // This is an optimized version of the check - // (i > MAX as u32) || (i >= 0xD800 && i <= 0xDFFF), - // which can also be written as - // i >= 0x110000 || (i >= 0xD800 && i < 0xE000). - // - // The XOR with 0xD800 permutes the ranges such that 0xD800..0xE000 is - // mapped to 0x0000..0x0800, while keeping all the high bits outside 0xFFFF the same. - // In particular, numbers >= 0x110000 stay in this range. - // - // Subtracting 0x800 causes 0x0000..0x0800 to wrap, meaning that a single - // unsigned comparison against 0x110000 - 0x800 will detect both the wrapped - // surrogate range as well as the numbers originally larger than 0x110000. - // - if (i ^ 0xD800).wrapping_sub(0x800) >= 0x110000 - 0x800 { - Err(CharTryFromError(())) - } else { - // SAFETY: checked that it's a legal unicode value - Ok(unsafe { transmute(i) }) - } -} - -#[stable(feature = "try_from", since = "1.34.0")] -impl TryFrom for char { - type Error = CharTryFromError; - - #[inline] - fn try_from(i: u32) -> Result { - char_try_from_u32(i) - } -} - -/// The error type returned when a conversion from [`prim@u32`] to [`prim@char`] fails. -/// -/// This `struct` is created by the [`char::try_from`](char#impl-TryFrom-for-char) method. -/// See its documentation for more. -#[stable(feature = "try_from", since = "1.34.0")] -#[derive(Copy, Clone, Debug, PartialEq, Eq)] -pub struct CharTryFromError(()); - -#[stable(feature = "try_from", since = "1.34.0")] -impl fmt::Display for CharTryFromError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - "converted integer out of range for `char`".fmt(f) - } -} - -/// Converts a digit in the given radix to a `char`. See [`char::from_digit`]. -#[inline] -#[must_use] -pub(super) const fn from_digit(num: u32, radix: u32) -> Option { - if radix > 36 { - panic!("from_digit: radix is too high (maximum 36)"); - } - if num < radix { - let num = num as u8; - if num < 10 { Some((b'0' + num) as char) } else { Some((b'a' + num - 10) as char) } - } else { - None - } -} diff --git a/library/core/src/char/decode.rs b/library/core/src/char/decode.rs deleted file mode 100644 index 23319fbe5ddc4..0000000000000 --- a/library/core/src/char/decode.rs +++ /dev/null @@ -1,134 +0,0 @@ -//! UTF-8 and UTF-16 decoding iterators - -use crate::error::Error; -use crate::fmt; -use crate::iter::FusedIterator; - -/// An iterator that decodes UTF-16 encoded code points from an iterator of `u16`s. -/// -/// This `struct` is created by the [`decode_utf16`] method on [`char`]. See its -/// documentation for more. -/// -/// [`decode_utf16`]: char::decode_utf16 -#[stable(feature = "decode_utf16", since = "1.9.0")] -#[derive(Clone, Debug)] -pub struct DecodeUtf16 -where - I: Iterator, -{ - iter: I, - buf: Option, -} - -/// An error that can be returned when decoding UTF-16 code points. -/// -/// This `struct` is created when using the [`DecodeUtf16`] type. -#[stable(feature = "decode_utf16", since = "1.9.0")] -#[derive(Debug, Clone, Eq, PartialEq)] -pub struct DecodeUtf16Error { - code: u16, -} - -/// Creates an iterator over the UTF-16 encoded code points in `iter`, -/// returning unpaired surrogates as `Err`s. See [`char::decode_utf16`]. -#[inline] -pub(super) fn decode_utf16>(iter: I) -> DecodeUtf16 { - DecodeUtf16 { iter: iter.into_iter(), buf: None } -} - -#[stable(feature = "decode_utf16", since = "1.9.0")] -impl> Iterator for DecodeUtf16 { - type Item = Result; - - fn next(&mut self) -> Option> { - let u = match self.buf.take() { - Some(buf) => buf, - None => self.iter.next()?, - }; - - if !u.is_utf16_surrogate() { - // SAFETY: not a surrogate - Some(Ok(unsafe { char::from_u32_unchecked(u as u32) })) - } else if u >= 0xDC00 { - // a trailing surrogate - Some(Err(DecodeUtf16Error { code: u })) - } else { - let u2 = match self.iter.next() { - Some(u2) => u2, - // eof - None => return Some(Err(DecodeUtf16Error { code: u })), - }; - if u2 < 0xDC00 || u2 > 0xDFFF { - // not a trailing surrogate so we're not a valid - // surrogate pair, so rewind to redecode u2 next time. - self.buf = Some(u2); - return Some(Err(DecodeUtf16Error { code: u })); - } - - // all ok, so lets decode it. - let c = (((u & 0x3ff) as u32) << 10 | (u2 & 0x3ff) as u32) + 0x1_0000; - // SAFETY: we checked that it's a legal unicode value - Some(Ok(unsafe { char::from_u32_unchecked(c) })) - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let (low, high) = self.iter.size_hint(); - - let (low_buf, high_buf) = match self.buf { - // buf is empty, no additional elements from it. - None => (0, 0), - // `u` is a non surrogate, so it's always an additional character. - Some(u) if !u.is_utf16_surrogate() => (1, 1), - // `u` is a leading surrogate (it can never be a trailing surrogate and - // it's a surrogate due to the previous branch) and `self.iter` is empty. - // - // `u` can't be paired, since the `self.iter` is empty, - // so it will always become an additional element (error). - Some(_u) if high == Some(0) => (1, 1), - // `u` is a leading surrogate and `iter` may be non-empty. - // - // `u` can either pair with a trailing surrogate, in which case no additional elements - // are produced, or it can become an error, in which case it's an additional character (error). - Some(_u) => (0, 1), - }; - - // `self.iter` could contain entirely valid surrogates (2 elements per - // char), or entirely non-surrogates (1 element per char). - // - // On odd lower bound, at least one element must stay unpaired - // (with other elements from `self.iter`), so we round up. - let low = low.div_ceil(2) + low_buf; - let high = high.and_then(|h| h.checked_add(high_buf)); - - (low, high) - } -} - -#[stable(feature = "decode_utf16_fused_iterator", since = "1.75.0")] -impl + FusedIterator> FusedIterator for DecodeUtf16 {} - -impl DecodeUtf16Error { - /// Returns the unpaired surrogate which caused this error. - #[must_use] - #[stable(feature = "decode_utf16", since = "1.9.0")] - pub fn unpaired_surrogate(&self) -> u16 { - self.code - } -} - -#[stable(feature = "decode_utf16", since = "1.9.0")] -impl fmt::Display for DecodeUtf16Error { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "unpaired surrogate found: {:x}", self.code) - } -} - -#[stable(feature = "decode_utf16", since = "1.9.0")] -impl Error for DecodeUtf16Error { - #[allow(deprecated)] - fn description(&self) -> &str { - "unpaired surrogate found" - } -} diff --git a/library/core/src/char/methods.rs b/library/core/src/char/methods.rs deleted file mode 100644 index 458be49fb152a..0000000000000 --- a/library/core/src/char/methods.rs +++ /dev/null @@ -1,1835 +0,0 @@ -//! impl char {} - -use crate::slice; -use crate::str::from_utf8_unchecked_mut; -use crate::unicode::printable::is_printable; -use crate::unicode::{self, conversions}; - -use super::*; - -impl char { - /// The lowest valid code point a `char` can have, `'\0'`. - /// - /// Unlike integer types, `char` actually has a gap in the middle, - /// meaning that the range of possible `char`s is smaller than you - /// might expect. Ranges of `char` will automatically hop this gap - /// for you: - /// - /// ``` - /// #![feature(char_min)] - /// let dist = u32::from(char::MAX) - u32::from(char::MIN); - /// let size = (char::MIN..=char::MAX).count() as u32; - /// assert!(size < dist); - /// ``` - /// - /// Despite this gap, the `MIN` and [`MAX`] values can be used as bounds for - /// all `char` values. - /// - /// [`MAX`]: char::MAX - /// - /// # Examples - /// - /// ``` - /// #![feature(char_min)] - /// # fn something_which_returns_char() -> char { 'a' } - /// let c: char = something_which_returns_char(); - /// assert!(char::MIN <= c); - /// - /// let value_at_min = u32::from(char::MIN); - /// assert_eq!(char::from_u32(value_at_min), Some('\0')); - /// ``` - #[unstable(feature = "char_min", issue = "114298")] - pub const MIN: char = '\0'; - - /// The highest valid code point a `char` can have, `'\u{10FFFF}'`. - /// - /// Unlike integer types, `char` actually has a gap in the middle, - /// meaning that the range of possible `char`s is smaller than you - /// might expect. Ranges of `char` will automatically hop this gap - /// for you: - /// - /// ``` - /// #![feature(char_min)] - /// let dist = u32::from(char::MAX) - u32::from(char::MIN); - /// let size = (char::MIN..=char::MAX).count() as u32; - /// assert!(size < dist); - /// ``` - /// - /// Despite this gap, the [`MIN`] and `MAX` values can be used as bounds for - /// all `char` values. - /// - /// [`MIN`]: char::MIN - /// - /// # Examples - /// - /// ``` - /// # fn something_which_returns_char() -> char { 'a' } - /// let c: char = something_which_returns_char(); - /// assert!(c <= char::MAX); - /// - /// let value_at_max = u32::from(char::MAX); - /// assert_eq!(char::from_u32(value_at_max), Some('\u{10FFFF}')); - /// assert_eq!(char::from_u32(value_at_max + 1), None); - /// ``` - #[stable(feature = "assoc_char_consts", since = "1.52.0")] - pub const MAX: char = '\u{10ffff}'; - - /// `U+FFFD REPLACEMENT CHARACTER` (�) is used in Unicode to represent a - /// decoding error. - /// - /// It can occur, for example, when giving ill-formed UTF-8 bytes to - /// [`String::from_utf8_lossy`](../std/string/struct.String.html#method.from_utf8_lossy). - #[stable(feature = "assoc_char_consts", since = "1.52.0")] - pub const REPLACEMENT_CHARACTER: char = '\u{FFFD}'; - - /// The version of [Unicode](https://www.unicode.org/) that the Unicode parts of - /// `char` and `str` methods are based on. - /// - /// New versions of Unicode are released regularly and subsequently all methods - /// in the standard library depending on Unicode are updated. Therefore the - /// behavior of some `char` and `str` methods and the value of this constant - /// changes over time. This is *not* considered to be a breaking change. - /// - /// The version numbering scheme is explained in - /// [Unicode 11.0 or later, Section 3.1 Versions of the Unicode Standard](https://www.unicode.org/versions/Unicode11.0.0/ch03.pdf#page=4). - #[stable(feature = "assoc_char_consts", since = "1.52.0")] - pub const UNICODE_VERSION: (u8, u8, u8) = crate::unicode::UNICODE_VERSION; - - /// Creates an iterator over the UTF-16 encoded code points in `iter`, - /// returning unpaired surrogates as `Err`s. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// // 𝄞music - /// let v = [ - /// 0xD834, 0xDD1E, 0x006d, 0x0075, 0x0073, 0xDD1E, 0x0069, 0x0063, 0xD834, - /// ]; - /// - /// assert_eq!( - /// char::decode_utf16(v) - /// .map(|r| r.map_err(|e| e.unpaired_surrogate())) - /// .collect::>(), - /// vec![ - /// Ok('𝄞'), - /// Ok('m'), Ok('u'), Ok('s'), - /// Err(0xDD1E), - /// Ok('i'), Ok('c'), - /// Err(0xD834) - /// ] - /// ); - /// ``` - /// - /// A lossy decoder can be obtained by replacing `Err` results with the replacement character: - /// - /// ``` - /// // 𝄞music - /// let v = [ - /// 0xD834, 0xDD1E, 0x006d, 0x0075, 0x0073, 0xDD1E, 0x0069, 0x0063, 0xD834, - /// ]; - /// - /// assert_eq!( - /// char::decode_utf16(v) - /// .map(|r| r.unwrap_or(char::REPLACEMENT_CHARACTER)) - /// .collect::(), - /// "𝄞mus�ic�" - /// ); - /// ``` - #[stable(feature = "assoc_char_funcs", since = "1.52.0")] - #[inline] - pub fn decode_utf16>(iter: I) -> DecodeUtf16 { - super::decode::decode_utf16(iter) - } - - /// Converts a `u32` to a `char`. - /// - /// Note that all `char`s are valid [`u32`]s, and can be cast to one with - /// [`as`](../std/keyword.as.html): - /// - /// ``` - /// let c = '💯'; - /// let i = c as u32; - /// - /// assert_eq!(128175, i); - /// ``` - /// - /// However, the reverse is not true: not all valid [`u32`]s are valid - /// `char`s. `from_u32()` will return `None` if the input is not a valid value - /// for a `char`. - /// - /// For an unsafe version of this function which ignores these checks, see - /// [`from_u32_unchecked`]. - /// - /// [`from_u32_unchecked`]: #method.from_u32_unchecked - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let c = char::from_u32(0x2764); - /// - /// assert_eq!(Some('❤'), c); - /// ``` - /// - /// Returning `None` when the input is not a valid `char`: - /// - /// ``` - /// let c = char::from_u32(0x110000); - /// - /// assert_eq!(None, c); - /// ``` - #[stable(feature = "assoc_char_funcs", since = "1.52.0")] - #[rustc_const_stable(feature = "const_char_convert", since = "1.67.0")] - #[must_use] - #[inline] - pub const fn from_u32(i: u32) -> Option { - super::convert::from_u32(i) - } - - /// Converts a `u32` to a `char`, ignoring validity. - /// - /// Note that all `char`s are valid [`u32`]s, and can be cast to one with - /// `as`: - /// - /// ``` - /// let c = '💯'; - /// let i = c as u32; - /// - /// assert_eq!(128175, i); - /// ``` - /// - /// However, the reverse is not true: not all valid [`u32`]s are valid - /// `char`s. `from_u32_unchecked()` will ignore this, and blindly cast to - /// `char`, possibly creating an invalid one. - /// - /// # Safety - /// - /// This function is unsafe, as it may construct invalid `char` values. - /// - /// For a safe version of this function, see the [`from_u32`] function. - /// - /// [`from_u32`]: #method.from_u32 - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let c = unsafe { char::from_u32_unchecked(0x2764) }; - /// - /// assert_eq!('❤', c); - /// ``` - #[stable(feature = "assoc_char_funcs", since = "1.52.0")] - #[rustc_const_unstable(feature = "const_char_from_u32_unchecked", issue = "89259")] - #[must_use] - #[inline] - pub const unsafe fn from_u32_unchecked(i: u32) -> char { - // SAFETY: the safety contract must be upheld by the caller. - unsafe { super::convert::from_u32_unchecked(i) } - } - - /// Converts a digit in the given radix to a `char`. - /// - /// A 'radix' here is sometimes also called a 'base'. A radix of two - /// indicates a binary number, a radix of ten, decimal, and a radix of - /// sixteen, hexadecimal, to give some common values. Arbitrary - /// radices are supported. - /// - /// `from_digit()` will return `None` if the input is not a digit in - /// the given radix. - /// - /// # Panics - /// - /// Panics if given a radix larger than 36. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let c = char::from_digit(4, 10); - /// - /// assert_eq!(Some('4'), c); - /// - /// // Decimal 11 is a single digit in base 16 - /// let c = char::from_digit(11, 16); - /// - /// assert_eq!(Some('b'), c); - /// ``` - /// - /// Returning `None` when the input is not a digit: - /// - /// ``` - /// let c = char::from_digit(20, 10); - /// - /// assert_eq!(None, c); - /// ``` - /// - /// Passing a large radix, causing a panic: - /// - /// ```should_panic - /// // this panics - /// let _c = char::from_digit(1, 37); - /// ``` - #[stable(feature = "assoc_char_funcs", since = "1.52.0")] - #[rustc_const_stable(feature = "const_char_convert", since = "1.67.0")] - #[must_use] - #[inline] - pub const fn from_digit(num: u32, radix: u32) -> Option { - super::convert::from_digit(num, radix) - } - - /// Checks if a `char` is a digit in the given radix. - /// - /// A 'radix' here is sometimes also called a 'base'. A radix of two - /// indicates a binary number, a radix of ten, decimal, and a radix of - /// sixteen, hexadecimal, to give some common values. Arbitrary - /// radices are supported. - /// - /// Compared to [`is_numeric()`], this function only recognizes the characters - /// `0-9`, `a-z` and `A-Z`. - /// - /// 'Digit' is defined to be only the following characters: - /// - /// * `0-9` - /// * `a-z` - /// * `A-Z` - /// - /// For a more comprehensive understanding of 'digit', see [`is_numeric()`]. - /// - /// [`is_numeric()`]: #method.is_numeric - /// - /// # Panics - /// - /// Panics if given a radix larger than 36. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// assert!('1'.is_digit(10)); - /// assert!('f'.is_digit(16)); - /// assert!(!'f'.is_digit(10)); - /// ``` - /// - /// Passing a large radix, causing a panic: - /// - /// ```should_panic - /// // this panics - /// '1'.is_digit(37); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn is_digit(self, radix: u32) -> bool { - self.to_digit(radix).is_some() - } - - /// Converts a `char` to a digit in the given radix. - /// - /// A 'radix' here is sometimes also called a 'base'. A radix of two - /// indicates a binary number, a radix of ten, decimal, and a radix of - /// sixteen, hexadecimal, to give some common values. Arbitrary - /// radices are supported. - /// - /// 'Digit' is defined to be only the following characters: - /// - /// * `0-9` - /// * `a-z` - /// * `A-Z` - /// - /// # Errors - /// - /// Returns `None` if the `char` does not refer to a digit in the given radix. - /// - /// # Panics - /// - /// Panics if given a radix larger than 36. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// assert_eq!('1'.to_digit(10), Some(1)); - /// assert_eq!('f'.to_digit(16), Some(15)); - /// ``` - /// - /// Passing a non-digit results in failure: - /// - /// ``` - /// assert_eq!('f'.to_digit(10), None); - /// assert_eq!('z'.to_digit(16), None); - /// ``` - /// - /// Passing a large radix, causing a panic: - /// - /// ```should_panic - /// // this panics - /// let _ = '1'.to_digit(37); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_char_convert", since = "1.67.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn to_digit(self, radix: u32) -> Option { - // If not a digit, a number greater than radix will be created. - let mut digit = (self as u32).wrapping_sub('0' as u32); - if radix > 10 { - assert!(radix <= 36, "to_digit: radix is too high (maximum 36)"); - if digit < 10 { - return Some(digit); - } - // Force the 6th bit to be set to ensure ascii is lower case. - digit = (self as u32 | 0b10_0000).wrapping_sub('a' as u32).saturating_add(10); - } - // FIXME: once then_some is const fn, use it here - if digit < radix { Some(digit) } else { None } - } - - /// Returns an iterator that yields the hexadecimal Unicode escape of a - /// character as `char`s. - /// - /// This will escape characters with the Rust syntax of the form - /// `\u{NNNNNN}` where `NNNNNN` is a hexadecimal representation. - /// - /// # Examples - /// - /// As an iterator: - /// - /// ``` - /// for c in '❤'.escape_unicode() { - /// print!("{c}"); - /// } - /// println!(); - /// ``` - /// - /// Using `println!` directly: - /// - /// ``` - /// println!("{}", '❤'.escape_unicode()); - /// ``` - /// - /// Both are equivalent to: - /// - /// ``` - /// println!("\\u{{2764}}"); - /// ``` - /// - /// Using [`to_string`](../std/string/trait.ToString.html#tymethod.to_string): - /// - /// ``` - /// assert_eq!('❤'.escape_unicode().to_string(), "\\u{2764}"); - /// ``` - #[must_use = "this returns the escaped char as an iterator, \ - without modifying the original"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn escape_unicode(self) -> EscapeUnicode { - EscapeUnicode::new(self) - } - - /// An extended version of `escape_debug` that optionally permits escaping - /// Extended Grapheme codepoints, single quotes, and double quotes. This - /// allows us to format characters like nonspacing marks better when they're - /// at the start of a string, and allows escaping single quotes in - /// characters, and double quotes in strings. - #[inline] - pub(crate) fn escape_debug_ext(self, args: EscapeDebugExtArgs) -> EscapeDebug { - match self { - '\0' => EscapeDebug::backslash(ascii::Char::Digit0), - '\t' => EscapeDebug::backslash(ascii::Char::SmallT), - '\r' => EscapeDebug::backslash(ascii::Char::SmallR), - '\n' => EscapeDebug::backslash(ascii::Char::SmallN), - '\\' => EscapeDebug::backslash(ascii::Char::ReverseSolidus), - '\"' if args.escape_double_quote => EscapeDebug::backslash(ascii::Char::QuotationMark), - '\'' if args.escape_single_quote => EscapeDebug::backslash(ascii::Char::Apostrophe), - _ if args.escape_grapheme_extended && self.is_grapheme_extended() => { - EscapeDebug::unicode(self) - } - _ if is_printable(self) => EscapeDebug::printable(self), - _ => EscapeDebug::unicode(self), - } - } - - /// Returns an iterator that yields the literal escape code of a character - /// as `char`s. - /// - /// This will escape the characters similar to the [`Debug`](core::fmt::Debug) implementations - /// of `str` or `char`. - /// - /// # Examples - /// - /// As an iterator: - /// - /// ``` - /// for c in '\n'.escape_debug() { - /// print!("{c}"); - /// } - /// println!(); - /// ``` - /// - /// Using `println!` directly: - /// - /// ``` - /// println!("{}", '\n'.escape_debug()); - /// ``` - /// - /// Both are equivalent to: - /// - /// ``` - /// println!("\\n"); - /// ``` - /// - /// Using [`to_string`](../std/string/trait.ToString.html#tymethod.to_string): - /// - /// ``` - /// assert_eq!('\n'.escape_debug().to_string(), "\\n"); - /// ``` - #[must_use = "this returns the escaped char as an iterator, \ - without modifying the original"] - #[stable(feature = "char_escape_debug", since = "1.20.0")] - #[inline] - pub fn escape_debug(self) -> EscapeDebug { - self.escape_debug_ext(EscapeDebugExtArgs::ESCAPE_ALL) - } - - /// Returns an iterator that yields the literal escape code of a character - /// as `char`s. - /// - /// The default is chosen with a bias toward producing literals that are - /// legal in a variety of languages, including C++11 and similar C-family - /// languages. The exact rules are: - /// - /// * Tab is escaped as `\t`. - /// * Carriage return is escaped as `\r`. - /// * Line feed is escaped as `\n`. - /// * Single quote is escaped as `\'`. - /// * Double quote is escaped as `\"`. - /// * Backslash is escaped as `\\`. - /// * Any character in the 'printable ASCII' range `0x20` .. `0x7e` - /// inclusive is not escaped. - /// * All other characters are given hexadecimal Unicode escapes; see - /// [`escape_unicode`]. - /// - /// [`escape_unicode`]: #method.escape_unicode - /// - /// # Examples - /// - /// As an iterator: - /// - /// ``` - /// for c in '"'.escape_default() { - /// print!("{c}"); - /// } - /// println!(); - /// ``` - /// - /// Using `println!` directly: - /// - /// ``` - /// println!("{}", '"'.escape_default()); - /// ``` - /// - /// Both are equivalent to: - /// - /// ``` - /// println!("\\\""); - /// ``` - /// - /// Using [`to_string`](../std/string/trait.ToString.html#tymethod.to_string): - /// - /// ``` - /// assert_eq!('"'.escape_default().to_string(), "\\\""); - /// ``` - #[must_use = "this returns the escaped char as an iterator, \ - without modifying the original"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn escape_default(self) -> EscapeDefault { - match self { - '\t' => EscapeDefault::backslash(ascii::Char::SmallT), - '\r' => EscapeDefault::backslash(ascii::Char::SmallR), - '\n' => EscapeDefault::backslash(ascii::Char::SmallN), - '\\' | '\'' | '\"' => EscapeDefault::backslash(self.as_ascii().unwrap()), - '\x20'..='\x7e' => EscapeDefault::printable(self.as_ascii().unwrap()), - _ => EscapeDefault::unicode(self), - } - } - - /// Returns the number of bytes this `char` would need if encoded in UTF-8. - /// - /// That number of bytes is always between 1 and 4, inclusive. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let len = 'A'.len_utf8(); - /// assert_eq!(len, 1); - /// - /// let len = 'ß'.len_utf8(); - /// assert_eq!(len, 2); - /// - /// let len = 'ℝ'.len_utf8(); - /// assert_eq!(len, 3); - /// - /// let len = '💣'.len_utf8(); - /// assert_eq!(len, 4); - /// ``` - /// - /// The `&str` type guarantees that its contents are UTF-8, and so we can compare the length it - /// would take if each code point was represented as a `char` vs in the `&str` itself: - /// - /// ``` - /// // as chars - /// let eastern = '東'; - /// let capital = '京'; - /// - /// // both can be represented as three bytes - /// assert_eq!(3, eastern.len_utf8()); - /// assert_eq!(3, capital.len_utf8()); - /// - /// // as a &str, these two are encoded in UTF-8 - /// let tokyo = "東京"; - /// - /// let len = eastern.len_utf8() + capital.len_utf8(); - /// - /// // we can see that they take six bytes total... - /// assert_eq!(6, tokyo.len()); - /// - /// // ... just like the &str - /// assert_eq!(len, tokyo.len()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_char_len_utf", since = "1.52.0")] - #[inline] - pub const fn len_utf8(self) -> usize { - len_utf8(self as u32) - } - - /// Returns the number of 16-bit code units this `char` would need if - /// encoded in UTF-16. - /// - /// That number of code units is always either 1 or 2, for unicode scalar values in - /// the [basic multilingual plane] or [supplementary planes] respectively. - /// - /// See the documentation for [`len_utf8()`] for more explanation of this - /// concept. This function is a mirror, but for UTF-16 instead of UTF-8. - /// - /// [basic multilingual plane]: http://www.unicode.org/glossary/#basic_multilingual_plane - /// [supplementary planes]: http://www.unicode.org/glossary/#supplementary_planes - /// [`len_utf8()`]: #method.len_utf8 - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let n = 'ß'.len_utf16(); - /// assert_eq!(n, 1); - /// - /// let len = '💣'.len_utf16(); - /// assert_eq!(len, 2); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_char_len_utf", since = "1.52.0")] - #[inline] - pub const fn len_utf16(self) -> usize { - let ch = self as u32; - if (ch & 0xFFFF) == ch { 1 } else { 2 } - } - - /// Encodes this character as UTF-8 into the provided byte buffer, - /// and then returns the subslice of the buffer that contains the encoded character. - /// - /// # Panics - /// - /// Panics if the buffer is not large enough. - /// A buffer of length four is large enough to encode any `char`. - /// - /// # Examples - /// - /// In both of these examples, 'ß' takes two bytes to encode. - /// - /// ``` - /// let mut b = [0; 2]; - /// - /// let result = 'ß'.encode_utf8(&mut b); - /// - /// assert_eq!(result, "ß"); - /// - /// assert_eq!(result.len(), 2); - /// ``` - /// - /// A buffer that's too small: - /// - /// ```should_panic - /// let mut b = [0; 1]; - /// - /// // this panics - /// 'ß'.encode_utf8(&mut b); - /// ``` - #[stable(feature = "unicode_encode_char", since = "1.15.0")] - #[inline] - pub fn encode_utf8(self, dst: &mut [u8]) -> &mut str { - // SAFETY: `char` is not a surrogate, so this is valid UTF-8. - unsafe { from_utf8_unchecked_mut(encode_utf8_raw(self as u32, dst)) } - } - - /// Encodes this character as UTF-16 into the provided `u16` buffer, - /// and then returns the subslice of the buffer that contains the encoded character. - /// - /// # Panics - /// - /// Panics if the buffer is not large enough. - /// A buffer of length 2 is large enough to encode any `char`. - /// - /// # Examples - /// - /// In both of these examples, '𝕊' takes two `u16`s to encode. - /// - /// ``` - /// let mut b = [0; 2]; - /// - /// let result = '𝕊'.encode_utf16(&mut b); - /// - /// assert_eq!(result.len(), 2); - /// ``` - /// - /// A buffer that's too small: - /// - /// ```should_panic - /// let mut b = [0; 1]; - /// - /// // this panics - /// '𝕊'.encode_utf16(&mut b); - /// ``` - #[stable(feature = "unicode_encode_char", since = "1.15.0")] - #[inline] - pub fn encode_utf16(self, dst: &mut [u16]) -> &mut [u16] { - encode_utf16_raw(self as u32, dst) - } - - /// Returns `true` if this `char` has the `Alphabetic` property. - /// - /// `Alphabetic` is described in Chapter 4 (Character Properties) of the [Unicode Standard] and - /// specified in the [Unicode Character Database][ucd] [`DerivedCoreProperties.txt`]. - /// - /// [Unicode Standard]: https://www.unicode.org/versions/latest/ - /// [ucd]: https://www.unicode.org/reports/tr44/ - /// [`DerivedCoreProperties.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/DerivedCoreProperties.txt - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// assert!('a'.is_alphabetic()); - /// assert!('京'.is_alphabetic()); - /// - /// let c = '💝'; - /// // love is many things, but it is not alphabetic - /// assert!(!c.is_alphabetic()); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn is_alphabetic(self) -> bool { - match self { - 'a'..='z' | 'A'..='Z' => true, - c => c > '\x7f' && unicode::Alphabetic(c), - } - } - - /// Returns `true` if this `char` has the `Lowercase` property. - /// - /// `Lowercase` is described in Chapter 4 (Character Properties) of the [Unicode Standard] and - /// specified in the [Unicode Character Database][ucd] [`DerivedCoreProperties.txt`]. - /// - /// [Unicode Standard]: https://www.unicode.org/versions/latest/ - /// [ucd]: https://www.unicode.org/reports/tr44/ - /// [`DerivedCoreProperties.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/DerivedCoreProperties.txt - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// assert!('a'.is_lowercase()); - /// assert!('δ'.is_lowercase()); - /// assert!(!'A'.is_lowercase()); - /// assert!(!'Δ'.is_lowercase()); - /// - /// // The various Chinese scripts and punctuation do not have case, and so: - /// assert!(!'中'.is_lowercase()); - /// assert!(!' '.is_lowercase()); - /// ``` - /// - /// In a const context: - /// - /// ``` - /// #![feature(const_unicode_case_lookup)] - /// const CAPITAL_DELTA_IS_LOWERCASE: bool = 'Δ'.is_lowercase(); - /// assert!(!CAPITAL_DELTA_IS_LOWERCASE); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_unicode_case_lookup", issue = "101400")] - #[inline] - pub const fn is_lowercase(self) -> bool { - match self { - 'a'..='z' => true, - c => c > '\x7f' && unicode::Lowercase(c), - } - } - - /// Returns `true` if this `char` has the `Uppercase` property. - /// - /// `Uppercase` is described in Chapter 4 (Character Properties) of the [Unicode Standard] and - /// specified in the [Unicode Character Database][ucd] [`DerivedCoreProperties.txt`]. - /// - /// [Unicode Standard]: https://www.unicode.org/versions/latest/ - /// [ucd]: https://www.unicode.org/reports/tr44/ - /// [`DerivedCoreProperties.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/DerivedCoreProperties.txt - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// assert!(!'a'.is_uppercase()); - /// assert!(!'δ'.is_uppercase()); - /// assert!('A'.is_uppercase()); - /// assert!('Δ'.is_uppercase()); - /// - /// // The various Chinese scripts and punctuation do not have case, and so: - /// assert!(!'中'.is_uppercase()); - /// assert!(!' '.is_uppercase()); - /// ``` - /// - /// In a const context: - /// - /// ``` - /// #![feature(const_unicode_case_lookup)] - /// const CAPITAL_DELTA_IS_UPPERCASE: bool = 'Δ'.is_uppercase(); - /// assert!(CAPITAL_DELTA_IS_UPPERCASE); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_unicode_case_lookup", issue = "101400")] - #[inline] - pub const fn is_uppercase(self) -> bool { - match self { - 'A'..='Z' => true, - c => c > '\x7f' && unicode::Uppercase(c), - } - } - - /// Returns `true` if this `char` has the `White_Space` property. - /// - /// `White_Space` is specified in the [Unicode Character Database][ucd] [`PropList.txt`]. - /// - /// [ucd]: https://www.unicode.org/reports/tr44/ - /// [`PropList.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/PropList.txt - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// assert!(' '.is_whitespace()); - /// - /// // line break - /// assert!('\n'.is_whitespace()); - /// - /// // a non-breaking space - /// assert!('\u{A0}'.is_whitespace()); - /// - /// assert!(!'越'.is_whitespace()); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn is_whitespace(self) -> bool { - match self { - ' ' | '\x09'..='\x0d' => true, - c => c > '\x7f' && unicode::White_Space(c), - } - } - - /// Returns `true` if this `char` satisfies either [`is_alphabetic()`] or [`is_numeric()`]. - /// - /// [`is_alphabetic()`]: #method.is_alphabetic - /// [`is_numeric()`]: #method.is_numeric - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// assert!('٣'.is_alphanumeric()); - /// assert!('7'.is_alphanumeric()); - /// assert!('৬'.is_alphanumeric()); - /// assert!('¾'.is_alphanumeric()); - /// assert!('①'.is_alphanumeric()); - /// assert!('K'.is_alphanumeric()); - /// assert!('و'.is_alphanumeric()); - /// assert!('藏'.is_alphanumeric()); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn is_alphanumeric(self) -> bool { - self.is_alphabetic() || self.is_numeric() - } - - /// Returns `true` if this `char` has the general category for control codes. - /// - /// Control codes (code points with the general category of `Cc`) are described in Chapter 4 - /// (Character Properties) of the [Unicode Standard] and specified in the [Unicode Character - /// Database][ucd] [`UnicodeData.txt`]. - /// - /// [Unicode Standard]: https://www.unicode.org/versions/latest/ - /// [ucd]: https://www.unicode.org/reports/tr44/ - /// [`UnicodeData.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/UnicodeData.txt - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// // U+009C, STRING TERMINATOR - /// assert!('œ'.is_control()); - /// assert!(!'q'.is_control()); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn is_control(self) -> bool { - unicode::Cc(self) - } - - /// Returns `true` if this `char` has the `Grapheme_Extend` property. - /// - /// `Grapheme_Extend` is described in [Unicode Standard Annex #29 (Unicode Text - /// Segmentation)][uax29] and specified in the [Unicode Character Database][ucd] - /// [`DerivedCoreProperties.txt`]. - /// - /// [uax29]: https://www.unicode.org/reports/tr29/ - /// [ucd]: https://www.unicode.org/reports/tr44/ - /// [`DerivedCoreProperties.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/DerivedCoreProperties.txt - #[must_use] - #[inline] - pub(crate) fn is_grapheme_extended(self) -> bool { - unicode::Grapheme_Extend(self) - } - - /// Returns `true` if this `char` has one of the general categories for numbers. - /// - /// The general categories for numbers (`Nd` for decimal digits, `Nl` for letter-like numeric - /// characters, and `No` for other numeric characters) are specified in the [Unicode Character - /// Database][ucd] [`UnicodeData.txt`]. - /// - /// This method doesn't cover everything that could be considered a number, e.g. ideographic numbers like '三'. - /// If you want everything including characters with overlapping purposes then you might want to use - /// a unicode or language-processing library that exposes the appropriate character properties instead - /// of looking at the unicode categories. - /// - /// If you want to parse ASCII decimal digits (0-9) or ASCII base-N, use - /// `is_ascii_digit` or `is_digit` instead. - /// - /// [Unicode Standard]: https://www.unicode.org/versions/latest/ - /// [ucd]: https://www.unicode.org/reports/tr44/ - /// [`UnicodeData.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/UnicodeData.txt - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// assert!('٣'.is_numeric()); - /// assert!('7'.is_numeric()); - /// assert!('৬'.is_numeric()); - /// assert!('¾'.is_numeric()); - /// assert!('①'.is_numeric()); - /// assert!(!'K'.is_numeric()); - /// assert!(!'و'.is_numeric()); - /// assert!(!'藏'.is_numeric()); - /// assert!(!'三'.is_numeric()); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn is_numeric(self) -> bool { - match self { - '0'..='9' => true, - c => c > '\x7f' && unicode::N(c), - } - } - - /// Returns an iterator that yields the lowercase mapping of this `char` as one or more - /// `char`s. - /// - /// If this `char` does not have a lowercase mapping, the iterator yields the same `char`. - /// - /// If this `char` has a one-to-one lowercase mapping given by the [Unicode Character - /// Database][ucd] [`UnicodeData.txt`], the iterator yields that `char`. - /// - /// [ucd]: https://www.unicode.org/reports/tr44/ - /// [`UnicodeData.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/UnicodeData.txt - /// - /// If this `char` requires special considerations (e.g. multiple `char`s) the iterator yields - /// the `char`(s) given by [`SpecialCasing.txt`]. - /// - /// [`SpecialCasing.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/SpecialCasing.txt - /// - /// This operation performs an unconditional mapping without tailoring. That is, the conversion - /// is independent of context and language. - /// - /// In the [Unicode Standard], Chapter 4 (Character Properties) discusses case mapping in - /// general and Chapter 3 (Conformance) discusses the default algorithm for case conversion. - /// - /// [Unicode Standard]: https://www.unicode.org/versions/latest/ - /// - /// # Examples - /// - /// As an iterator: - /// - /// ``` - /// for c in 'İ'.to_lowercase() { - /// print!("{c}"); - /// } - /// println!(); - /// ``` - /// - /// Using `println!` directly: - /// - /// ``` - /// println!("{}", 'İ'.to_lowercase()); - /// ``` - /// - /// Both are equivalent to: - /// - /// ``` - /// println!("i\u{307}"); - /// ``` - /// - /// Using [`to_string`](../std/string/trait.ToString.html#tymethod.to_string): - /// - /// ``` - /// assert_eq!('C'.to_lowercase().to_string(), "c"); - /// - /// // Sometimes the result is more than one character: - /// assert_eq!('İ'.to_lowercase().to_string(), "i\u{307}"); - /// - /// // Characters that do not have both uppercase and lowercase - /// // convert into themselves. - /// assert_eq!('山'.to_lowercase().to_string(), "山"); - /// ``` - #[must_use = "this returns the lowercase character as a new iterator, \ - without modifying the original"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn to_lowercase(self) -> ToLowercase { - ToLowercase(CaseMappingIter::new(conversions::to_lower(self))) - } - - /// Returns an iterator that yields the uppercase mapping of this `char` as one or more - /// `char`s. - /// - /// If this `char` does not have an uppercase mapping, the iterator yields the same `char`. - /// - /// If this `char` has a one-to-one uppercase mapping given by the [Unicode Character - /// Database][ucd] [`UnicodeData.txt`], the iterator yields that `char`. - /// - /// [ucd]: https://www.unicode.org/reports/tr44/ - /// [`UnicodeData.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/UnicodeData.txt - /// - /// If this `char` requires special considerations (e.g. multiple `char`s) the iterator yields - /// the `char`(s) given by [`SpecialCasing.txt`]. - /// - /// [`SpecialCasing.txt`]: https://www.unicode.org/Public/UCD/latest/ucd/SpecialCasing.txt - /// - /// This operation performs an unconditional mapping without tailoring. That is, the conversion - /// is independent of context and language. - /// - /// In the [Unicode Standard], Chapter 4 (Character Properties) discusses case mapping in - /// general and Chapter 3 (Conformance) discusses the default algorithm for case conversion. - /// - /// [Unicode Standard]: https://www.unicode.org/versions/latest/ - /// - /// # Examples - /// - /// As an iterator: - /// - /// ``` - /// for c in 'ß'.to_uppercase() { - /// print!("{c}"); - /// } - /// println!(); - /// ``` - /// - /// Using `println!` directly: - /// - /// ``` - /// println!("{}", 'ß'.to_uppercase()); - /// ``` - /// - /// Both are equivalent to: - /// - /// ``` - /// println!("SS"); - /// ``` - /// - /// Using [`to_string`](../std/string/trait.ToString.html#tymethod.to_string): - /// - /// ``` - /// assert_eq!('c'.to_uppercase().to_string(), "C"); - /// - /// // Sometimes the result is more than one character: - /// assert_eq!('ß'.to_uppercase().to_string(), "SS"); - /// - /// // Characters that do not have both uppercase and lowercase - /// // convert into themselves. - /// assert_eq!('山'.to_uppercase().to_string(), "山"); - /// ``` - /// - /// # Note on locale - /// - /// In Turkish, the equivalent of 'i' in Latin has five forms instead of two: - /// - /// * 'Dotless': I / ı, sometimes written ï - /// * 'Dotted': İ / i - /// - /// Note that the lowercase dotted 'i' is the same as the Latin. Therefore: - /// - /// ``` - /// let upper_i = 'i'.to_uppercase().to_string(); - /// ``` - /// - /// The value of `upper_i` here relies on the language of the text: if we're - /// in `en-US`, it should be `"I"`, but if we're in `tr_TR`, it should - /// be `"İ"`. `to_uppercase()` does not take this into account, and so: - /// - /// ``` - /// let upper_i = 'i'.to_uppercase().to_string(); - /// - /// assert_eq!(upper_i, "I"); - /// ``` - /// - /// holds across languages. - #[must_use = "this returns the uppercase character as a new iterator, \ - without modifying the original"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn to_uppercase(self) -> ToUppercase { - ToUppercase(CaseMappingIter::new(conversions::to_upper(self))) - } - - /// Checks if the value is within the ASCII range. - /// - /// # Examples - /// - /// ``` - /// let ascii = 'a'; - /// let non_ascii = '❤'; - /// - /// assert!(ascii.is_ascii()); - /// assert!(!non_ascii.is_ascii()); - /// ``` - #[must_use] - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[rustc_const_stable(feature = "const_char_is_ascii", since = "1.32.0")] - #[inline] - pub const fn is_ascii(&self) -> bool { - *self as u32 <= 0x7F - } - - /// Returns `Some` if the value is within the ASCII range, - /// or `None` if it's not. - /// - /// This is preferred to [`Self::is_ascii`] when you're passing the value - /// along to something else that can take [`ascii::Char`] rather than - /// needing to check again for itself whether the value is in ASCII. - #[must_use] - #[unstable(feature = "ascii_char", issue = "110998")] - #[inline] - pub const fn as_ascii(&self) -> Option { - if self.is_ascii() { - // SAFETY: Just checked that this is ASCII. - Some(unsafe { ascii::Char::from_u8_unchecked(*self as u8) }) - } else { - None - } - } - - /// Makes a copy of the value in its ASCII upper case equivalent. - /// - /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', - /// but non-ASCII letters are unchanged. - /// - /// To uppercase the value in-place, use [`make_ascii_uppercase()`]. - /// - /// To uppercase ASCII characters in addition to non-ASCII characters, use - /// [`to_uppercase()`]. - /// - /// # Examples - /// - /// ``` - /// let ascii = 'a'; - /// let non_ascii = '❤'; - /// - /// assert_eq!('A', ascii.to_ascii_uppercase()); - /// assert_eq!('❤', non_ascii.to_ascii_uppercase()); - /// ``` - /// - /// [`make_ascii_uppercase()`]: #method.make_ascii_uppercase - /// [`to_uppercase()`]: #method.to_uppercase - #[must_use = "to uppercase the value in-place, use `make_ascii_uppercase()`"] - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")] - #[inline] - pub const fn to_ascii_uppercase(&self) -> char { - if self.is_ascii_lowercase() { - (*self as u8).ascii_change_case_unchecked() as char - } else { - *self - } - } - - /// Makes a copy of the value in its ASCII lower case equivalent. - /// - /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', - /// but non-ASCII letters are unchanged. - /// - /// To lowercase the value in-place, use [`make_ascii_lowercase()`]. - /// - /// To lowercase ASCII characters in addition to non-ASCII characters, use - /// [`to_lowercase()`]. - /// - /// # Examples - /// - /// ``` - /// let ascii = 'A'; - /// let non_ascii = '❤'; - /// - /// assert_eq!('a', ascii.to_ascii_lowercase()); - /// assert_eq!('❤', non_ascii.to_ascii_lowercase()); - /// ``` - /// - /// [`make_ascii_lowercase()`]: #method.make_ascii_lowercase - /// [`to_lowercase()`]: #method.to_lowercase - #[must_use = "to lowercase the value in-place, use `make_ascii_lowercase()`"] - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")] - #[inline] - pub const fn to_ascii_lowercase(&self) -> char { - if self.is_ascii_uppercase() { - (*self as u8).ascii_change_case_unchecked() as char - } else { - *self - } - } - - /// Checks that two values are an ASCII case-insensitive match. - /// - /// Equivalent to [to_ascii_lowercase]\(a) == [to_ascii_lowercase]\(b). - /// - /// # Examples - /// - /// ``` - /// let upper_a = 'A'; - /// let lower_a = 'a'; - /// let lower_z = 'z'; - /// - /// assert!(upper_a.eq_ignore_ascii_case(&lower_a)); - /// assert!(upper_a.eq_ignore_ascii_case(&upper_a)); - /// assert!(!upper_a.eq_ignore_ascii_case(&lower_z)); - /// ``` - /// - /// [to_ascii_lowercase]: #method.to_ascii_lowercase - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")] - #[inline] - pub const fn eq_ignore_ascii_case(&self, other: &char) -> bool { - self.to_ascii_lowercase() == other.to_ascii_lowercase() - } - - /// Converts this type to its ASCII upper case equivalent in-place. - /// - /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', - /// but non-ASCII letters are unchanged. - /// - /// To return a new uppercased value without modifying the existing one, use - /// [`to_ascii_uppercase()`]. - /// - /// # Examples - /// - /// ``` - /// let mut ascii = 'a'; - /// - /// ascii.make_ascii_uppercase(); - /// - /// assert_eq!('A', ascii); - /// ``` - /// - /// [`to_ascii_uppercase()`]: #method.to_ascii_uppercase - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[inline] - pub fn make_ascii_uppercase(&mut self) { - *self = self.to_ascii_uppercase(); - } - - /// Converts this type to its ASCII lower case equivalent in-place. - /// - /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', - /// but non-ASCII letters are unchanged. - /// - /// To return a new lowercased value without modifying the existing one, use - /// [`to_ascii_lowercase()`]. - /// - /// # Examples - /// - /// ``` - /// let mut ascii = 'A'; - /// - /// ascii.make_ascii_lowercase(); - /// - /// assert_eq!('a', ascii); - /// ``` - /// - /// [`to_ascii_lowercase()`]: #method.to_ascii_lowercase - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[inline] - pub fn make_ascii_lowercase(&mut self) { - *self = self.to_ascii_lowercase(); - } - - /// Checks if the value is an ASCII alphabetic character: - /// - /// - U+0041 'A' ..= U+005A 'Z', or - /// - U+0061 'a' ..= U+007A 'z'. - /// - /// # Examples - /// - /// ``` - /// let uppercase_a = 'A'; - /// let uppercase_g = 'G'; - /// let a = 'a'; - /// let g = 'g'; - /// let zero = '0'; - /// let percent = '%'; - /// let space = ' '; - /// let lf = '\n'; - /// let esc = '\x1b'; - /// - /// assert!(uppercase_a.is_ascii_alphabetic()); - /// assert!(uppercase_g.is_ascii_alphabetic()); - /// assert!(a.is_ascii_alphabetic()); - /// assert!(g.is_ascii_alphabetic()); - /// assert!(!zero.is_ascii_alphabetic()); - /// assert!(!percent.is_ascii_alphabetic()); - /// assert!(!space.is_ascii_alphabetic()); - /// assert!(!lf.is_ascii_alphabetic()); - /// assert!(!esc.is_ascii_alphabetic()); - /// ``` - #[must_use] - #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")] - #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")] - #[inline] - pub const fn is_ascii_alphabetic(&self) -> bool { - matches!(*self, 'A'..='Z' | 'a'..='z') - } - - /// Checks if the value is an ASCII uppercase character: - /// U+0041 'A' ..= U+005A 'Z'. - /// - /// # Examples - /// - /// ``` - /// let uppercase_a = 'A'; - /// let uppercase_g = 'G'; - /// let a = 'a'; - /// let g = 'g'; - /// let zero = '0'; - /// let percent = '%'; - /// let space = ' '; - /// let lf = '\n'; - /// let esc = '\x1b'; - /// - /// assert!(uppercase_a.is_ascii_uppercase()); - /// assert!(uppercase_g.is_ascii_uppercase()); - /// assert!(!a.is_ascii_uppercase()); - /// assert!(!g.is_ascii_uppercase()); - /// assert!(!zero.is_ascii_uppercase()); - /// assert!(!percent.is_ascii_uppercase()); - /// assert!(!space.is_ascii_uppercase()); - /// assert!(!lf.is_ascii_uppercase()); - /// assert!(!esc.is_ascii_uppercase()); - /// ``` - #[must_use] - #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")] - #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")] - #[inline] - pub const fn is_ascii_uppercase(&self) -> bool { - matches!(*self, 'A'..='Z') - } - - /// Checks if the value is an ASCII lowercase character: - /// U+0061 'a' ..= U+007A 'z'. - /// - /// # Examples - /// - /// ``` - /// let uppercase_a = 'A'; - /// let uppercase_g = 'G'; - /// let a = 'a'; - /// let g = 'g'; - /// let zero = '0'; - /// let percent = '%'; - /// let space = ' '; - /// let lf = '\n'; - /// let esc = '\x1b'; - /// - /// assert!(!uppercase_a.is_ascii_lowercase()); - /// assert!(!uppercase_g.is_ascii_lowercase()); - /// assert!(a.is_ascii_lowercase()); - /// assert!(g.is_ascii_lowercase()); - /// assert!(!zero.is_ascii_lowercase()); - /// assert!(!percent.is_ascii_lowercase()); - /// assert!(!space.is_ascii_lowercase()); - /// assert!(!lf.is_ascii_lowercase()); - /// assert!(!esc.is_ascii_lowercase()); - /// ``` - #[must_use] - #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")] - #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")] - #[inline] - pub const fn is_ascii_lowercase(&self) -> bool { - matches!(*self, 'a'..='z') - } - - /// Checks if the value is an ASCII alphanumeric character: - /// - /// - U+0041 'A' ..= U+005A 'Z', or - /// - U+0061 'a' ..= U+007A 'z', or - /// - U+0030 '0' ..= U+0039 '9'. - /// - /// # Examples - /// - /// ``` - /// let uppercase_a = 'A'; - /// let uppercase_g = 'G'; - /// let a = 'a'; - /// let g = 'g'; - /// let zero = '0'; - /// let percent = '%'; - /// let space = ' '; - /// let lf = '\n'; - /// let esc = '\x1b'; - /// - /// assert!(uppercase_a.is_ascii_alphanumeric()); - /// assert!(uppercase_g.is_ascii_alphanumeric()); - /// assert!(a.is_ascii_alphanumeric()); - /// assert!(g.is_ascii_alphanumeric()); - /// assert!(zero.is_ascii_alphanumeric()); - /// assert!(!percent.is_ascii_alphanumeric()); - /// assert!(!space.is_ascii_alphanumeric()); - /// assert!(!lf.is_ascii_alphanumeric()); - /// assert!(!esc.is_ascii_alphanumeric()); - /// ``` - #[must_use] - #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")] - #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")] - #[inline] - pub const fn is_ascii_alphanumeric(&self) -> bool { - matches!(*self, '0'..='9') | matches!(*self, 'A'..='Z') | matches!(*self, 'a'..='z') - } - - /// Checks if the value is an ASCII decimal digit: - /// U+0030 '0' ..= U+0039 '9'. - /// - /// # Examples - /// - /// ``` - /// let uppercase_a = 'A'; - /// let uppercase_g = 'G'; - /// let a = 'a'; - /// let g = 'g'; - /// let zero = '0'; - /// let percent = '%'; - /// let space = ' '; - /// let lf = '\n'; - /// let esc = '\x1b'; - /// - /// assert!(!uppercase_a.is_ascii_digit()); - /// assert!(!uppercase_g.is_ascii_digit()); - /// assert!(!a.is_ascii_digit()); - /// assert!(!g.is_ascii_digit()); - /// assert!(zero.is_ascii_digit()); - /// assert!(!percent.is_ascii_digit()); - /// assert!(!space.is_ascii_digit()); - /// assert!(!lf.is_ascii_digit()); - /// assert!(!esc.is_ascii_digit()); - /// ``` - #[must_use] - #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")] - #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")] - #[inline] - pub const fn is_ascii_digit(&self) -> bool { - matches!(*self, '0'..='9') - } - - /// Checks if the value is an ASCII octal digit: - /// U+0030 '0' ..= U+0037 '7'. - /// - /// # Examples - /// - /// ``` - /// #![feature(is_ascii_octdigit)] - /// - /// let uppercase_a = 'A'; - /// let a = 'a'; - /// let zero = '0'; - /// let seven = '7'; - /// let nine = '9'; - /// let percent = '%'; - /// let lf = '\n'; - /// - /// assert!(!uppercase_a.is_ascii_octdigit()); - /// assert!(!a.is_ascii_octdigit()); - /// assert!(zero.is_ascii_octdigit()); - /// assert!(seven.is_ascii_octdigit()); - /// assert!(!nine.is_ascii_octdigit()); - /// assert!(!percent.is_ascii_octdigit()); - /// assert!(!lf.is_ascii_octdigit()); - /// ``` - #[must_use] - #[unstable(feature = "is_ascii_octdigit", issue = "101288")] - #[rustc_const_unstable(feature = "is_ascii_octdigit", issue = "101288")] - #[inline] - pub const fn is_ascii_octdigit(&self) -> bool { - matches!(*self, '0'..='7') - } - - /// Checks if the value is an ASCII hexadecimal digit: - /// - /// - U+0030 '0' ..= U+0039 '9', or - /// - U+0041 'A' ..= U+0046 'F', or - /// - U+0061 'a' ..= U+0066 'f'. - /// - /// # Examples - /// - /// ``` - /// let uppercase_a = 'A'; - /// let uppercase_g = 'G'; - /// let a = 'a'; - /// let g = 'g'; - /// let zero = '0'; - /// let percent = '%'; - /// let space = ' '; - /// let lf = '\n'; - /// let esc = '\x1b'; - /// - /// assert!(uppercase_a.is_ascii_hexdigit()); - /// assert!(!uppercase_g.is_ascii_hexdigit()); - /// assert!(a.is_ascii_hexdigit()); - /// assert!(!g.is_ascii_hexdigit()); - /// assert!(zero.is_ascii_hexdigit()); - /// assert!(!percent.is_ascii_hexdigit()); - /// assert!(!space.is_ascii_hexdigit()); - /// assert!(!lf.is_ascii_hexdigit()); - /// assert!(!esc.is_ascii_hexdigit()); - /// ``` - #[must_use] - #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")] - #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")] - #[inline] - pub const fn is_ascii_hexdigit(&self) -> bool { - matches!(*self, '0'..='9') | matches!(*self, 'A'..='F') | matches!(*self, 'a'..='f') - } - - /// Checks if the value is an ASCII punctuation character: - /// - /// - U+0021 ..= U+002F `! " # $ % & ' ( ) * + , - . /`, or - /// - U+003A ..= U+0040 `: ; < = > ? @`, or - /// - U+005B ..= U+0060 ``[ \ ] ^ _ ` ``, or - /// - U+007B ..= U+007E `{ | } ~` - /// - /// # Examples - /// - /// ``` - /// let uppercase_a = 'A'; - /// let uppercase_g = 'G'; - /// let a = 'a'; - /// let g = 'g'; - /// let zero = '0'; - /// let percent = '%'; - /// let space = ' '; - /// let lf = '\n'; - /// let esc = '\x1b'; - /// - /// assert!(!uppercase_a.is_ascii_punctuation()); - /// assert!(!uppercase_g.is_ascii_punctuation()); - /// assert!(!a.is_ascii_punctuation()); - /// assert!(!g.is_ascii_punctuation()); - /// assert!(!zero.is_ascii_punctuation()); - /// assert!(percent.is_ascii_punctuation()); - /// assert!(!space.is_ascii_punctuation()); - /// assert!(!lf.is_ascii_punctuation()); - /// assert!(!esc.is_ascii_punctuation()); - /// ``` - #[must_use] - #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")] - #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")] - #[inline] - pub const fn is_ascii_punctuation(&self) -> bool { - matches!(*self, '!'..='/') - | matches!(*self, ':'..='@') - | matches!(*self, '['..='`') - | matches!(*self, '{'..='~') - } - - /// Checks if the value is an ASCII graphic character: - /// U+0021 '!' ..= U+007E '~'. - /// - /// # Examples - /// - /// ``` - /// let uppercase_a = 'A'; - /// let uppercase_g = 'G'; - /// let a = 'a'; - /// let g = 'g'; - /// let zero = '0'; - /// let percent = '%'; - /// let space = ' '; - /// let lf = '\n'; - /// let esc = '\x1b'; - /// - /// assert!(uppercase_a.is_ascii_graphic()); - /// assert!(uppercase_g.is_ascii_graphic()); - /// assert!(a.is_ascii_graphic()); - /// assert!(g.is_ascii_graphic()); - /// assert!(zero.is_ascii_graphic()); - /// assert!(percent.is_ascii_graphic()); - /// assert!(!space.is_ascii_graphic()); - /// assert!(!lf.is_ascii_graphic()); - /// assert!(!esc.is_ascii_graphic()); - /// ``` - #[must_use] - #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")] - #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")] - #[inline] - pub const fn is_ascii_graphic(&self) -> bool { - matches!(*self, '!'..='~') - } - - /// Checks if the value is an ASCII whitespace character: - /// U+0020 SPACE, U+0009 HORIZONTAL TAB, U+000A LINE FEED, - /// U+000C FORM FEED, or U+000D CARRIAGE RETURN. - /// - /// Rust uses the WhatWG Infra Standard's [definition of ASCII - /// whitespace][infra-aw]. There are several other definitions in - /// wide use. For instance, [the POSIX locale][pct] includes - /// U+000B VERTICAL TAB as well as all the above characters, - /// but—from the very same specification—[the default rule for - /// "field splitting" in the Bourne shell][bfs] considers *only* - /// SPACE, HORIZONTAL TAB, and LINE FEED as whitespace. - /// - /// If you are writing a program that will process an existing - /// file format, check what that format's definition of whitespace is - /// before using this function. - /// - /// [infra-aw]: https://infra.spec.whatwg.org/#ascii-whitespace - /// [pct]: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html#tag_07_03_01 - /// [bfs]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_05 - /// - /// # Examples - /// - /// ``` - /// let uppercase_a = 'A'; - /// let uppercase_g = 'G'; - /// let a = 'a'; - /// let g = 'g'; - /// let zero = '0'; - /// let percent = '%'; - /// let space = ' '; - /// let lf = '\n'; - /// let esc = '\x1b'; - /// - /// assert!(!uppercase_a.is_ascii_whitespace()); - /// assert!(!uppercase_g.is_ascii_whitespace()); - /// assert!(!a.is_ascii_whitespace()); - /// assert!(!g.is_ascii_whitespace()); - /// assert!(!zero.is_ascii_whitespace()); - /// assert!(!percent.is_ascii_whitespace()); - /// assert!(space.is_ascii_whitespace()); - /// assert!(lf.is_ascii_whitespace()); - /// assert!(!esc.is_ascii_whitespace()); - /// ``` - #[must_use] - #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")] - #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")] - #[inline] - pub const fn is_ascii_whitespace(&self) -> bool { - matches!(*self, '\t' | '\n' | '\x0C' | '\r' | ' ') - } - - /// Checks if the value is an ASCII control character: - /// U+0000 NUL ..= U+001F UNIT SEPARATOR, or U+007F DELETE. - /// Note that most ASCII whitespace characters are control - /// characters, but SPACE is not. - /// - /// # Examples - /// - /// ``` - /// let uppercase_a = 'A'; - /// let uppercase_g = 'G'; - /// let a = 'a'; - /// let g = 'g'; - /// let zero = '0'; - /// let percent = '%'; - /// let space = ' '; - /// let lf = '\n'; - /// let esc = '\x1b'; - /// - /// assert!(!uppercase_a.is_ascii_control()); - /// assert!(!uppercase_g.is_ascii_control()); - /// assert!(!a.is_ascii_control()); - /// assert!(!g.is_ascii_control()); - /// assert!(!zero.is_ascii_control()); - /// assert!(!percent.is_ascii_control()); - /// assert!(!space.is_ascii_control()); - /// assert!(lf.is_ascii_control()); - /// assert!(esc.is_ascii_control()); - /// ``` - #[must_use] - #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")] - #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")] - #[inline] - pub const fn is_ascii_control(&self) -> bool { - matches!(*self, '\0'..='\x1F' | '\x7F') - } -} - -pub(crate) struct EscapeDebugExtArgs { - /// Escape Extended Grapheme codepoints? - pub(crate) escape_grapheme_extended: bool, - - /// Escape single quotes? - pub(crate) escape_single_quote: bool, - - /// Escape double quotes? - pub(crate) escape_double_quote: bool, -} - -impl EscapeDebugExtArgs { - pub(crate) const ESCAPE_ALL: Self = Self { - escape_grapheme_extended: true, - escape_single_quote: true, - escape_double_quote: true, - }; -} - -#[inline] -const fn len_utf8(code: u32) -> usize { - if code < MAX_ONE_B { - 1 - } else if code < MAX_TWO_B { - 2 - } else if code < MAX_THREE_B { - 3 - } else { - 4 - } -} - -/// Encodes a raw u32 value as UTF-8 into the provided byte buffer, -/// and then returns the subslice of the buffer that contains the encoded character. -/// -/// Unlike `char::encode_utf8`, this method also handles codepoints in the surrogate range. -/// (Creating a `char` in the surrogate range is UB.) -/// The result is valid [generalized UTF-8] but not valid UTF-8. -/// -/// [generalized UTF-8]: https://simonsapin.github.io/wtf-8/#generalized-utf8 -/// -/// # Panics -/// -/// Panics if the buffer is not large enough. -/// A buffer of length four is large enough to encode any `char`. -#[unstable(feature = "char_internals", reason = "exposed only for libstd", issue = "none")] -#[doc(hidden)] -#[inline] -pub fn encode_utf8_raw(code: u32, dst: &mut [u8]) -> &mut [u8] { - let len = len_utf8(code); - match (len, &mut dst[..]) { - (1, [a, ..]) => { - *a = code as u8; - } - (2, [a, b, ..]) => { - *a = (code >> 6 & 0x1F) as u8 | TAG_TWO_B; - *b = (code & 0x3F) as u8 | TAG_CONT; - } - (3, [a, b, c, ..]) => { - *a = (code >> 12 & 0x0F) as u8 | TAG_THREE_B; - *b = (code >> 6 & 0x3F) as u8 | TAG_CONT; - *c = (code & 0x3F) as u8 | TAG_CONT; - } - (4, [a, b, c, d, ..]) => { - *a = (code >> 18 & 0x07) as u8 | TAG_FOUR_B; - *b = (code >> 12 & 0x3F) as u8 | TAG_CONT; - *c = (code >> 6 & 0x3F) as u8 | TAG_CONT; - *d = (code & 0x3F) as u8 | TAG_CONT; - } - _ => panic!( - "encode_utf8: need {} bytes to encode U+{:X}, but the buffer has {}", - len, - code, - dst.len(), - ), - }; - &mut dst[..len] -} - -/// Encodes a raw u32 value as UTF-16 into the provided `u16` buffer, -/// and then returns the subslice of the buffer that contains the encoded character. -/// -/// Unlike `char::encode_utf16`, this method also handles codepoints in the surrogate range. -/// (Creating a `char` in the surrogate range is UB.) -/// -/// # Panics -/// -/// Panics if the buffer is not large enough. -/// A buffer of length 2 is large enough to encode any `char`. -#[unstable(feature = "char_internals", reason = "exposed only for libstd", issue = "none")] -#[doc(hidden)] -#[inline] -pub fn encode_utf16_raw(mut code: u32, dst: &mut [u16]) -> &mut [u16] { - // SAFETY: each arm checks whether there are enough bits to write into - unsafe { - if (code & 0xFFFF) == code && !dst.is_empty() { - // The BMP falls through - *dst.get_unchecked_mut(0) = code as u16; - slice::from_raw_parts_mut(dst.as_mut_ptr(), 1) - } else if dst.len() >= 2 { - // Supplementary planes break into surrogates. - code -= 0x1_0000; - *dst.get_unchecked_mut(0) = 0xD800 | ((code >> 10) as u16); - *dst.get_unchecked_mut(1) = 0xDC00 | ((code as u16) & 0x3FF); - slice::from_raw_parts_mut(dst.as_mut_ptr(), 2) - } else { - panic!( - "encode_utf16: need {} units to encode U+{:X}, but the buffer has {}", - char::from_u32_unchecked(code).len_utf16(), - code, - dst.len(), - ) - } - } -} diff --git a/library/core/src/char/mod.rs b/library/core/src/char/mod.rs deleted file mode 100644 index f3683fe3f9c83..0000000000000 --- a/library/core/src/char/mod.rs +++ /dev/null @@ -1,617 +0,0 @@ -//! Utilities for the `char` primitive type. -//! -//! *[See also the `char` primitive type](primitive@char).* -//! -//! The `char` type represents a single character. More specifically, since -//! 'character' isn't a well-defined concept in Unicode, `char` is a '[Unicode -//! scalar value]', which is similar to, but not the same as, a '[Unicode code -//! point]'. -//! -//! [Unicode scalar value]: https://www.unicode.org/glossary/#unicode_scalar_value -//! [Unicode code point]: https://www.unicode.org/glossary/#code_point -//! -//! This module exists for technical reasons, the primary documentation for -//! `char` is directly on [the `char` primitive type][char] itself. -//! -//! This module is the home of the iterator implementations for the iterators -//! implemented on `char`, as well as some useful constants and conversion -//! functions that convert various types to `char`. - -#![allow(non_snake_case)] -#![stable(feature = "core_char", since = "1.2.0")] - -mod convert; -mod decode; -mod methods; - -// stable re-exports -#[stable(feature = "try_from", since = "1.34.0")] -pub use self::convert::CharTryFromError; -#[stable(feature = "char_from_str", since = "1.20.0")] -pub use self::convert::ParseCharError; -#[stable(feature = "decode_utf16", since = "1.9.0")] -pub use self::decode::{DecodeUtf16, DecodeUtf16Error}; - -// perma-unstable re-exports -#[unstable(feature = "char_internals", reason = "exposed only for libstd", issue = "none")] -pub use self::methods::encode_utf16_raw; -#[unstable(feature = "char_internals", reason = "exposed only for libstd", issue = "none")] -pub use self::methods::encode_utf8_raw; - -use crate::ascii; -use crate::error::Error; -use crate::escape; -use crate::fmt::{self, Write}; -use crate::iter::{FusedIterator, TrustedLen, TrustedRandomAccess, TrustedRandomAccessNoCoerce}; -use crate::num::NonZero; - -pub(crate) use self::methods::EscapeDebugExtArgs; - -// UTF-8 ranges and tags for encoding characters -const TAG_CONT: u8 = 0b1000_0000; -const TAG_TWO_B: u8 = 0b1100_0000; -const TAG_THREE_B: u8 = 0b1110_0000; -const TAG_FOUR_B: u8 = 0b1111_0000; -const MAX_ONE_B: u32 = 0x80; -const MAX_TWO_B: u32 = 0x800; -const MAX_THREE_B: u32 = 0x10000; - -/* - Lu Uppercase_Letter an uppercase letter - Ll Lowercase_Letter a lowercase letter - Lt Titlecase_Letter a digraphic character, with first part uppercase - Lm Modifier_Letter a modifier letter - Lo Other_Letter other letters, including syllables and ideographs - Mn Nonspacing_Mark a nonspacing combining mark (zero advance width) - Mc Spacing_Mark a spacing combining mark (positive advance width) - Me Enclosing_Mark an enclosing combining mark - Nd Decimal_Number a decimal digit - Nl Letter_Number a letterlike numeric character - No Other_Number a numeric character of other type - Pc Connector_Punctuation a connecting punctuation mark, like a tie - Pd Dash_Punctuation a dash or hyphen punctuation mark - Ps Open_Punctuation an opening punctuation mark (of a pair) - Pe Close_Punctuation a closing punctuation mark (of a pair) - Pi Initial_Punctuation an initial quotation mark - Pf Final_Punctuation a final quotation mark - Po Other_Punctuation a punctuation mark of other type - Sm Math_Symbol a symbol of primarily mathematical use - Sc Currency_Symbol a currency sign - Sk Modifier_Symbol a non-letterlike modifier symbol - So Other_Symbol a symbol of other type - Zs Space_Separator a space character (of various non-zero widths) - Zl Line_Separator U+2028 LINE SEPARATOR only - Zp Paragraph_Separator U+2029 PARAGRAPH SEPARATOR only - Cc Control a C0 or C1 control code - Cf Format a format control character - Cs Surrogate a surrogate code point - Co Private_Use a private-use character - Cn Unassigned a reserved unassigned code point or a noncharacter -*/ - -/// The highest valid code point a `char` can have, `'\u{10FFFF}'`. Use [`char::MAX`] instead. -#[stable(feature = "rust1", since = "1.0.0")] -pub const MAX: char = char::MAX; - -/// `U+FFFD REPLACEMENT CHARACTER` (�) is used in Unicode to represent a -/// decoding error. Use [`char::REPLACEMENT_CHARACTER`] instead. -#[stable(feature = "decode_utf16", since = "1.9.0")] -pub const REPLACEMENT_CHARACTER: char = char::REPLACEMENT_CHARACTER; - -/// The version of [Unicode](https://www.unicode.org/) that the Unicode parts of -/// `char` and `str` methods are based on. Use [`char::UNICODE_VERSION`] instead. -#[stable(feature = "unicode_version", since = "1.45.0")] -pub const UNICODE_VERSION: (u8, u8, u8) = char::UNICODE_VERSION; - -/// Creates an iterator over the UTF-16 encoded code points in `iter`, returning -/// unpaired surrogates as `Err`s. Use [`char::decode_utf16`] instead. -#[stable(feature = "decode_utf16", since = "1.9.0")] -#[inline] -pub fn decode_utf16>(iter: I) -> DecodeUtf16 { - self::decode::decode_utf16(iter) -} - -/// Converts a `u32` to a `char`. Use [`char::from_u32`] instead. -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_const_stable(feature = "const_char_convert", since = "1.67.0")] -#[must_use] -#[inline] -pub const fn from_u32(i: u32) -> Option { - self::convert::from_u32(i) -} - -/// Converts a `u32` to a `char`, ignoring validity. Use [`char::from_u32_unchecked`]. -/// instead. -#[stable(feature = "char_from_unchecked", since = "1.5.0")] -#[rustc_const_unstable(feature = "const_char_from_u32_unchecked", issue = "89259")] -#[must_use] -#[inline] -pub const unsafe fn from_u32_unchecked(i: u32) -> char { - // SAFETY: the safety contract must be upheld by the caller. - unsafe { self::convert::from_u32_unchecked(i) } -} - -/// Converts a digit in the given radix to a `char`. Use [`char::from_digit`] instead. -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_const_stable(feature = "const_char_convert", since = "1.67.0")] -#[must_use] -#[inline] -pub const fn from_digit(num: u32, radix: u32) -> Option { - self::convert::from_digit(num, radix) -} - -/// Returns an iterator that yields the hexadecimal Unicode escape of a -/// character, as `char`s. -/// -/// This `struct` is created by the [`escape_unicode`] method on [`char`]. See -/// its documentation for more. -/// -/// [`escape_unicode`]: char::escape_unicode -#[derive(Clone, Debug)] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct EscapeUnicode(escape::EscapeIterInner<10>); - -impl EscapeUnicode { - #[inline] - const fn new(c: char) -> Self { - Self(escape::EscapeIterInner::unicode(c)) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for EscapeUnicode { - type Item = char; - - #[inline] - fn next(&mut self) -> Option { - self.0.next().map(char::from) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let n = self.0.len(); - (n, Some(n)) - } - - #[inline] - fn count(self) -> usize { - self.0.len() - } - - #[inline] - fn last(mut self) -> Option { - self.0.next_back().map(char::from) - } - - #[inline] - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - self.0.advance_by(n) - } -} - -#[stable(feature = "exact_size_escape", since = "1.11.0")] -impl ExactSizeIterator for EscapeUnicode { - #[inline] - fn len(&self) -> usize { - self.0.len() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for EscapeUnicode {} - -#[stable(feature = "char_struct_display", since = "1.16.0")] -impl fmt::Display for EscapeUnicode { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str(self.0.as_str()) - } -} - -/// An iterator that yields the literal escape code of a `char`. -/// -/// This `struct` is created by the [`escape_default`] method on [`char`]. See -/// its documentation for more. -/// -/// [`escape_default`]: char::escape_default -#[derive(Clone, Debug)] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct EscapeDefault(escape::EscapeIterInner<10>); - -impl EscapeDefault { - #[inline] - const fn printable(c: ascii::Char) -> Self { - Self(escape::EscapeIterInner::ascii(c.to_u8())) - } - - #[inline] - const fn backslash(c: ascii::Char) -> Self { - Self(escape::EscapeIterInner::backslash(c)) - } - - #[inline] - const fn unicode(c: char) -> Self { - Self(escape::EscapeIterInner::unicode(c)) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for EscapeDefault { - type Item = char; - - #[inline] - fn next(&mut self) -> Option { - self.0.next().map(char::from) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let n = self.0.len(); - (n, Some(n)) - } - - #[inline] - fn count(self) -> usize { - self.0.len() - } - - #[inline] - fn last(mut self) -> Option { - self.0.next_back().map(char::from) - } - - #[inline] - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - self.0.advance_by(n) - } -} - -#[stable(feature = "exact_size_escape", since = "1.11.0")] -impl ExactSizeIterator for EscapeDefault { - #[inline] - fn len(&self) -> usize { - self.0.len() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for EscapeDefault {} - -#[stable(feature = "char_struct_display", since = "1.16.0")] -impl fmt::Display for EscapeDefault { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str(self.0.as_str()) - } -} - -/// An iterator that yields the literal escape code of a `char`. -/// -/// This `struct` is created by the [`escape_debug`] method on [`char`]. See its -/// documentation for more. -/// -/// [`escape_debug`]: char::escape_debug -#[stable(feature = "char_escape_debug", since = "1.20.0")] -#[derive(Clone, Debug)] -pub struct EscapeDebug(EscapeDebugInner); - -#[derive(Clone, Debug)] -// Note: It’s possible to manually encode the EscapeDebugInner inside of -// EscapeIterInner (e.g. with alive=254..255 indicating that data[0..4] holds -// a char) which would likely result in a more optimised code. For now we use -// the option easier to implement. -enum EscapeDebugInner { - Bytes(escape::EscapeIterInner<10>), - Char(char), -} - -impl EscapeDebug { - #[inline] - const fn printable(chr: char) -> Self { - Self(EscapeDebugInner::Char(chr)) - } - - #[inline] - const fn backslash(c: ascii::Char) -> Self { - Self(EscapeDebugInner::Bytes(escape::EscapeIterInner::backslash(c))) - } - - #[inline] - const fn unicode(c: char) -> Self { - Self(EscapeDebugInner::Bytes(escape::EscapeIterInner::unicode(c))) - } - - #[inline] - fn clear(&mut self) { - self.0 = EscapeDebugInner::Bytes(escape::EscapeIterInner::empty()); - } -} - -#[stable(feature = "char_escape_debug", since = "1.20.0")] -impl Iterator for EscapeDebug { - type Item = char; - - #[inline] - fn next(&mut self) -> Option { - match self.0 { - EscapeDebugInner::Bytes(ref mut bytes) => bytes.next().map(char::from), - EscapeDebugInner::Char(chr) => { - self.clear(); - Some(chr) - } - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let n = self.len(); - (n, Some(n)) - } - - #[inline] - fn count(self) -> usize { - self.len() - } -} - -#[stable(feature = "char_escape_debug", since = "1.20.0")] -impl ExactSizeIterator for EscapeDebug { - fn len(&self) -> usize { - match &self.0 { - EscapeDebugInner::Bytes(bytes) => bytes.len(), - EscapeDebugInner::Char(_) => 1, - } - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for EscapeDebug {} - -#[stable(feature = "char_escape_debug", since = "1.20.0")] -impl fmt::Display for EscapeDebug { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - match &self.0 { - EscapeDebugInner::Bytes(bytes) => f.write_str(bytes.as_str()), - EscapeDebugInner::Char(chr) => f.write_char(*chr), - } - } -} - -macro_rules! casemappingiter_impls { - ($(#[$attr:meta])* $ITER_NAME:ident) => { - $(#[$attr])* - #[stable(feature = "rust1", since = "1.0.0")] - #[derive(Debug, Clone)] - pub struct $ITER_NAME(CaseMappingIter); - - #[stable(feature = "rust1", since = "1.0.0")] - impl Iterator for $ITER_NAME { - type Item = char; - fn next(&mut self) -> Option { - self.0.next() - } - - fn size_hint(&self) -> (usize, Option) { - self.0.size_hint() - } - - fn fold(self, init: Acc, fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - self.0.fold(init, fold) - } - - fn count(self) -> usize { - self.0.count() - } - - fn last(self) -> Option { - self.0.last() - } - - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - self.0.advance_by(n) - } - - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item { - // SAFETY: just forwarding requirements to caller - unsafe { self.0.__iterator_get_unchecked(idx) } - } - } - - #[stable(feature = "case_mapping_double_ended", since = "1.59.0")] - impl DoubleEndedIterator for $ITER_NAME { - fn next_back(&mut self) -> Option { - self.0.next_back() - } - - fn rfold(self, init: Acc, rfold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - self.0.rfold(init, rfold) - } - - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - self.0.advance_back_by(n) - } - } - - #[stable(feature = "fused", since = "1.26.0")] - impl FusedIterator for $ITER_NAME {} - - #[stable(feature = "exact_size_case_mapping_iter", since = "1.35.0")] - impl ExactSizeIterator for $ITER_NAME { - fn len(&self) -> usize { - self.0.len() - } - - fn is_empty(&self) -> bool { - self.0.is_empty() - } - } - - // SAFETY: forwards to inner `array::IntoIter` - #[unstable(feature = "trusted_len", issue = "37572")] - unsafe impl TrustedLen for $ITER_NAME {} - - // SAFETY: forwards to inner `array::IntoIter` - #[doc(hidden)] - #[unstable(feature = "std_internals", issue = "none")] - unsafe impl TrustedRandomAccessNoCoerce for $ITER_NAME { - const MAY_HAVE_SIDE_EFFECT: bool = false; - } - - // SAFETY: this iter has no subtypes/supertypes - #[doc(hidden)] - #[unstable(feature = "std_internals", issue = "none")] - unsafe impl TrustedRandomAccess for $ITER_NAME {} - - #[stable(feature = "char_struct_display", since = "1.16.0")] - impl fmt::Display for $ITER_NAME { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt(&self.0, f) - } - } - } -} - -casemappingiter_impls! { - /// Returns an iterator that yields the lowercase equivalent of a `char`. - /// - /// This `struct` is created by the [`to_lowercase`] method on [`char`]. See - /// its documentation for more. - /// - /// [`to_lowercase`]: char::to_lowercase - ToLowercase -} - -casemappingiter_impls! { - /// Returns an iterator that yields the uppercase equivalent of a `char`. - /// - /// This `struct` is created by the [`to_uppercase`] method on [`char`]. See - /// its documentation for more. - /// - /// [`to_uppercase`]: char::to_uppercase - ToUppercase -} - -#[derive(Debug, Clone)] -struct CaseMappingIter(core::array::IntoIter); - -impl CaseMappingIter { - #[inline] - fn new(chars: [char; 3]) -> CaseMappingIter { - let mut iter = chars.into_iter(); - if chars[2] == '\0' { - iter.next_back(); - if chars[1] == '\0' { - iter.next_back(); - - // Deliberately don't check `chars[0]`, - // as '\0' lowercases to itself - } - } - CaseMappingIter(iter) - } -} - -impl Iterator for CaseMappingIter { - type Item = char; - - fn next(&mut self) -> Option { - self.0.next() - } - - fn size_hint(&self) -> (usize, Option) { - self.0.size_hint() - } - - fn fold(self, init: Acc, fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - self.0.fold(init, fold) - } - - fn count(self) -> usize { - self.0.count() - } - - fn last(self) -> Option { - self.0.last() - } - - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - self.0.advance_by(n) - } - - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item { - // SAFETY: just forwarding requirements to caller - unsafe { self.0.__iterator_get_unchecked(idx) } - } -} - -impl DoubleEndedIterator for CaseMappingIter { - fn next_back(&mut self) -> Option { - self.0.next_back() - } - - fn rfold(self, init: Acc, rfold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - self.0.rfold(init, rfold) - } - - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - self.0.advance_back_by(n) - } -} - -impl ExactSizeIterator for CaseMappingIter { - fn len(&self) -> usize { - self.0.len() - } - - fn is_empty(&self) -> bool { - self.0.is_empty() - } -} - -impl FusedIterator for CaseMappingIter {} - -// SAFETY: forwards to inner `array::IntoIter` -unsafe impl TrustedLen for CaseMappingIter {} - -// SAFETY: forwards to inner `array::IntoIter` -unsafe impl TrustedRandomAccessNoCoerce for CaseMappingIter { - const MAY_HAVE_SIDE_EFFECT: bool = false; -} - -// SAFETY: `CaseMappingIter` has no subtypes/supertypes -unsafe impl TrustedRandomAccess for CaseMappingIter {} - -impl fmt::Display for CaseMappingIter { - #[inline] - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - for c in self.0.clone() { - f.write_char(c)?; - } - Ok(()) - } -} - -/// The error type returned when a checked char conversion fails. -#[stable(feature = "u8_from_char", since = "1.59.0")] -#[derive(Debug, Copy, Clone, PartialEq, Eq)] -pub struct TryFromCharError(pub(crate) ()); - -#[stable(feature = "u8_from_char", since = "1.59.0")] -impl fmt::Display for TryFromCharError { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - "unicode code point out of range".fmt(fmt) - } -} - -#[stable(feature = "u8_from_char", since = "1.59.0")] -impl Error for TryFromCharError {} diff --git a/library/core/src/clone.rs b/library/core/src/clone.rs deleted file mode 100644 index d448c5338fc46..0000000000000 --- a/library/core/src/clone.rs +++ /dev/null @@ -1,271 +0,0 @@ -//! The `Clone` trait for types that cannot be 'implicitly copied'. -//! -//! In Rust, some simple types are "implicitly copyable" and when you -//! assign them or pass them as arguments, the receiver will get a copy, -//! leaving the original value in place. These types do not require -//! allocation to copy and do not have finalizers (i.e., they do not -//! contain owned boxes or implement [`Drop`]), so the compiler considers -//! them cheap and safe to copy. For other types copies must be made -//! explicitly, by convention implementing the [`Clone`] trait and calling -//! the [`clone`] method. -//! -//! [`clone`]: Clone::clone -//! -//! Basic usage example: -//! -//! ``` -//! let s = String::new(); // String type implements Clone -//! let copy = s.clone(); // so we can clone it -//! ``` -//! -//! To easily implement the Clone trait, you can also use -//! `#[derive(Clone)]`. Example: -//! -//! ``` -//! #[derive(Clone)] // we add the Clone trait to Morpheus struct -//! struct Morpheus { -//! blue_pill: f32, -//! red_pill: i64, -//! } -//! -//! fn main() { -//! let f = Morpheus { blue_pill: 0.0, red_pill: 0 }; -//! let copy = f.clone(); // and now we can clone it! -//! } -//! ``` - -#![stable(feature = "rust1", since = "1.0.0")] - -/// A common trait for the ability to explicitly duplicate an object. -/// -/// Differs from [`Copy`] in that [`Copy`] is implicit and an inexpensive bit-wise copy, while -/// `Clone` is always explicit and may or may not be expensive. In order to enforce -/// these characteristics, Rust does not allow you to reimplement [`Copy`], but you -/// may reimplement `Clone` and run arbitrary code. -/// -/// Since `Clone` is more general than [`Copy`], you can automatically make anything -/// [`Copy`] be `Clone` as well. -/// -/// ## Derivable -/// -/// This trait can be used with `#[derive]` if all fields are `Clone`. The `derive`d -/// implementation of [`Clone`] calls [`clone`] on each field. -/// -/// [`clone`]: Clone::clone -/// -/// For a generic struct, `#[derive]` implements `Clone` conditionally by adding bound `Clone` on -/// generic parameters. -/// -/// ``` -/// // `derive` implements Clone for Reading when T is Clone. -/// #[derive(Clone)] -/// struct Reading { -/// frequency: T, -/// } -/// ``` -/// -/// ## How can I implement `Clone`? -/// -/// Types that are [`Copy`] should have a trivial implementation of `Clone`. More formally: -/// if `T: Copy`, `x: T`, and `y: &T`, then `let x = y.clone();` is equivalent to `let x = *y;`. -/// Manual implementations should be careful to uphold this invariant; however, unsafe code -/// must not rely on it to ensure memory safety. -/// -/// An example is a generic struct holding a function pointer. In this case, the -/// implementation of `Clone` cannot be `derive`d, but can be implemented as: -/// -/// ``` -/// struct Generate(fn() -> T); -/// -/// impl Copy for Generate {} -/// -/// impl Clone for Generate { -/// fn clone(&self) -> Self { -/// *self -/// } -/// } -/// ``` -/// -/// If we `derive`: -/// -/// ``` -/// #[derive(Copy, Clone)] -/// struct Generate(fn() -> T); -/// ``` -/// -/// the auto-derived implementations will have unnecessary `T: Copy` and `T: Clone` bounds: -/// -/// ``` -/// # struct Generate(fn() -> T); -/// -/// // Automatically derived -/// impl Copy for Generate { } -/// -/// // Automatically derived -/// impl Clone for Generate { -/// fn clone(&self) -> Generate { -/// Generate(Clone::clone(&self.0)) -/// } -/// } -/// ``` -/// -/// The bounds are unnecessary because clearly the function itself should be -/// copy- and cloneable even if its return type is not: -/// -/// ```compile_fail,E0599 -/// #[derive(Copy, Clone)] -/// struct Generate(fn() -> T); -/// -/// struct NotCloneable; -/// -/// fn generate_not_cloneable() -> NotCloneable { -/// NotCloneable -/// } -/// -/// Generate(generate_not_cloneable).clone(); // error: trait bounds were not satisfied -/// // Note: With the manual implementations the above line will compile. -/// ``` -/// -/// ## Additional implementors -/// -/// In addition to the [implementors listed below][impls], -/// the following types also implement `Clone`: -/// -/// * Function item types (i.e., the distinct types defined for each function) -/// * Function pointer types (e.g., `fn() -> i32`) -/// * Closure types, if they capture no value from the environment -/// or if all such captured values implement `Clone` themselves. -/// Note that variables captured by shared reference always implement `Clone` -/// (even if the referent doesn't), -/// while variables captured by mutable reference never implement `Clone`. -/// -/// [impls]: #implementors -#[stable(feature = "rust1", since = "1.0.0")] -#[lang = "clone"] -#[rustc_diagnostic_item = "Clone"] -#[rustc_trivial_field_reads] -pub trait Clone: Sized { - /// Returns a copy of the value. - /// - /// # Examples - /// - /// ``` - /// # #![allow(noop_method_call)] - /// let hello = "Hello"; // &str implements Clone - /// - /// assert_eq!("Hello", hello.clone()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use = "cloning is often expensive and is not expected to have side effects"] - fn clone(&self) -> Self; - - /// Performs copy-assignment from `source`. - /// - /// `a.clone_from(&b)` is equivalent to `a = b.clone()` in functionality, - /// but can be overridden to reuse the resources of `a` to avoid unnecessary - /// allocations. - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - fn clone_from(&mut self, source: &Self) { - *self = source.clone() - } -} - -/// Derive macro generating an impl of the trait `Clone`. -#[rustc_builtin_macro] -#[stable(feature = "builtin_macro_prelude", since = "1.38.0")] -#[allow_internal_unstable(core_intrinsics, derive_clone_copy)] -pub macro Clone($item:item) { - /* compiler built-in */ -} - -// FIXME(aburka): these structs are used solely by #[derive] to -// assert that every component of a type implements Clone or Copy. -// -// These structs should never appear in user code. -#[doc(hidden)] -#[allow(missing_debug_implementations)] -#[unstable( - feature = "derive_clone_copy", - reason = "deriving hack, should not be public", - issue = "none" -)] -pub struct AssertParamIsClone { - _field: crate::marker::PhantomData, -} -#[doc(hidden)] -#[allow(missing_debug_implementations)] -#[unstable( - feature = "derive_clone_copy", - reason = "deriving hack, should not be public", - issue = "none" -)] -pub struct AssertParamIsCopy { - _field: crate::marker::PhantomData, -} - -/// Implementations of `Clone` for primitive types. -/// -/// Implementations that cannot be described in Rust -/// are implemented in `traits::SelectionContext::copy_clone_conditions()` -/// in `rustc_trait_selection`. -mod impls { - macro_rules! impl_clone { - ($($t:ty)*) => { - $( - #[stable(feature = "rust1", since = "1.0.0")] - impl Clone for $t { - #[inline(always)] - fn clone(&self) -> Self { - *self - } - } - )* - } - } - - impl_clone! { - usize u8 u16 u32 u64 u128 - isize i8 i16 i32 i64 i128 - f16 f32 f64 f128 - bool char - } - - #[unstable(feature = "never_type", issue = "35121")] - impl Clone for ! { - #[inline] - fn clone(&self) -> Self { - *self - } - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl Clone for *const T { - #[inline(always)] - fn clone(&self) -> Self { - *self - } - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl Clone for *mut T { - #[inline(always)] - fn clone(&self) -> Self { - *self - } - } - - /// Shared references can be cloned, but mutable references *cannot*! - #[stable(feature = "rust1", since = "1.0.0")] - impl Clone for &T { - #[inline(always)] - #[rustc_diagnostic_item = "noop_method_clone"] - fn clone(&self) -> Self { - *self - } - } - - /// Shared references can be cloned, but mutable references *cannot*! - #[stable(feature = "rust1", since = "1.0.0")] - impl !Clone for &mut T {} -} diff --git a/library/core/src/cmp.rs b/library/core/src/cmp.rs deleted file mode 100644 index f3f757ce69df7..0000000000000 --- a/library/core/src/cmp.rs +++ /dev/null @@ -1,1793 +0,0 @@ -//! Utilities for comparing and ordering values. -//! -//! This module contains various tools for comparing and ordering values. In -//! summary: -//! -//! * [`PartialEq`] overloads the `==` and `!=` operators. In cases where -//! `Rhs` (the right hand side's type) is `Self`, this trait corresponds to a -//! partial equivalence relation. -//! * [`Eq`] indicates that the overloaded `==` operator corresponds to an -//! equivalence relation. -//! * [`Ord`] and [`PartialOrd`] are traits that allow you to define total and -//! partial orderings between values, respectively. Implementing them overloads -//! the `<`, `<=`, `>`, and `>=` operators. -//! * [`Ordering`] is an enum returned by the main functions of [`Ord`] and -//! [`PartialOrd`], and describes an ordering of two values (less, equal, or -//! greater). -//! * [`Reverse`] is a struct that allows you to easily reverse an ordering. -//! * [`max`] and [`min`] are functions that build off of [`Ord`] and allow you -//! to find the maximum or minimum of two values. -//! -//! For more details, see the respective documentation of each item in the list. -//! -//! [`max`]: Ord::max -//! [`min`]: Ord::min - -#![stable(feature = "rust1", since = "1.0.0")] - -mod bytewise; -pub(crate) use bytewise::BytewiseEq; - -use self::Ordering::*; - -/// Trait for comparisons using the equality operator. -/// -/// Implementing this trait for types provides the `==` and `!=` operators for -/// those types. -/// -/// `x.eq(y)` can also be written `x == y`, and `x.ne(y)` can be written `x != y`. -/// We use the easier-to-read infix notation in the remainder of this documentation. -/// -/// This trait allows for comparisons using the equality operator, for types -/// that do not have a full equivalence relation. For example, in floating point -/// numbers `NaN != NaN`, so floating point types implement `PartialEq` but not -/// [`trait@Eq`]. Formally speaking, when `Rhs == Self`, this trait corresponds -/// to a [partial equivalence relation]. -/// -/// [partial equivalence relation]: https://en.wikipedia.org/wiki/Partial_equivalence_relation -/// -/// Implementations must ensure that `eq` and `ne` are consistent with each other: -/// -/// - `a != b` if and only if `!(a == b)`. -/// -/// The default implementation of `ne` provides this consistency and is almost -/// always sufficient. It should not be overridden without very good reason. -/// -/// If [`PartialOrd`] or [`Ord`] are also implemented for `Self` and `Rhs`, their methods must also -/// be consistent with `PartialEq` (see the documentation of those traits for the exact -/// requirements). It's easy to accidentally make them disagree by deriving some of the traits and -/// manually implementing others. -/// -/// The equality relation `==` must satisfy the following conditions -/// (for all `a`, `b`, `c` of type `A`, `B`, `C`): -/// -/// - **Symmetry**: if `A: PartialEq` and `B: PartialEq`, then **`a == b` -/// implies `b == a`**; and -/// -/// - **Transitivity**: if `A: PartialEq` and `B: PartialEq` and `A: -/// PartialEq`, then **`a == b` and `b == c` implies `a == c`**. -/// This must also work for longer chains, such as when `A: PartialEq`, `B: PartialEq`, -/// `C: PartialEq`, and `A: PartialEq` all exist. -/// -/// Note that the `B: PartialEq` (symmetric) and `A: PartialEq` -/// (transitive) impls are not forced to exist, but these requirements apply -/// whenever they do exist. -/// -/// Violating these requirements is a logic error. The behavior resulting from a logic error is not -/// specified, but users of the trait must ensure that such logic errors do *not* result in -/// undefined behavior. This means that `unsafe` code **must not** rely on the correctness of these -/// methods. -/// -/// ## Cross-crate considerations -/// -/// Upholding the requirements stated above can become tricky when one crate implements `PartialEq` -/// for a type of another crate (i.e., to allow comparing one of its own types with a type from the -/// standard library). The recommendation is to never implement this trait for a foreign type. In -/// other words, such a crate should do `impl PartialEq for LocalType`, but it should -/// *not* do `impl PartialEq for ForeignType`. -/// -/// This avoids the problem of transitive chains that criss-cross crate boundaries: for all local -/// types `T`, you may assume that no other crate will add `impl`s that allow comparing `T == U`. In -/// other words, if other crates add `impl`s that allow building longer transitive chains `U1 == ... -/// == T == V1 == ...`, then all the types that appear to the right of `T` must be types that the -/// crate defining `T` already knows about. This rules out transitive chains where downstream crates -/// can add new `impl`s that "stitch together" comparisons of foreign types in ways that violate -/// transitivity. -/// -/// Not having such foreign `impl`s also avoids forward compatibility issues where one crate adding -/// more `PartialEq` implementations can cause build failures in downstream crates. -/// -/// ## Derivable -/// -/// This trait can be used with `#[derive]`. When `derive`d on structs, two -/// instances are equal if all fields are equal, and not equal if any fields -/// are not equal. When `derive`d on enums, two instances are equal if they -/// are the same variant and all fields are equal. -/// -/// ## How can I implement `PartialEq`? -/// -/// An example implementation for a domain in which two books are considered -/// the same book if their ISBN matches, even if the formats differ: -/// -/// ``` -/// enum BookFormat { -/// Paperback, -/// Hardback, -/// Ebook, -/// } -/// -/// struct Book { -/// isbn: i32, -/// format: BookFormat, -/// } -/// -/// impl PartialEq for Book { -/// fn eq(&self, other: &Self) -> bool { -/// self.isbn == other.isbn -/// } -/// } -/// -/// let b1 = Book { isbn: 3, format: BookFormat::Paperback }; -/// let b2 = Book { isbn: 3, format: BookFormat::Ebook }; -/// let b3 = Book { isbn: 10, format: BookFormat::Paperback }; -/// -/// assert!(b1 == b2); -/// assert!(b1 != b3); -/// ``` -/// -/// ## How can I compare two different types? -/// -/// The type you can compare with is controlled by `PartialEq`'s type parameter. -/// For example, let's tweak our previous code a bit: -/// -/// ``` -/// // The derive implements == comparisons -/// #[derive(PartialEq)] -/// enum BookFormat { -/// Paperback, -/// Hardback, -/// Ebook, -/// } -/// -/// struct Book { -/// isbn: i32, -/// format: BookFormat, -/// } -/// -/// // Implement == comparisons -/// impl PartialEq for Book { -/// fn eq(&self, other: &BookFormat) -> bool { -/// self.format == *other -/// } -/// } -/// -/// // Implement == comparisons -/// impl PartialEq for BookFormat { -/// fn eq(&self, other: &Book) -> bool { -/// *self == other.format -/// } -/// } -/// -/// let b1 = Book { isbn: 3, format: BookFormat::Paperback }; -/// -/// assert!(b1 == BookFormat::Paperback); -/// assert!(BookFormat::Ebook != b1); -/// ``` -/// -/// By changing `impl PartialEq for Book` to `impl PartialEq for Book`, -/// we allow `BookFormat`s to be compared with `Book`s. -/// -/// A comparison like the one above, which ignores some fields of the struct, -/// can be dangerous. It can easily lead to an unintended violation of the -/// requirements for a partial equivalence relation. For example, if we kept -/// the above implementation of `PartialEq` for `BookFormat` and added an -/// implementation of `PartialEq` for `Book` (either via a `#[derive]` or -/// via the manual implementation from the first example) then the result would -/// violate transitivity: -/// -/// ```should_panic -/// #[derive(PartialEq)] -/// enum BookFormat { -/// Paperback, -/// Hardback, -/// Ebook, -/// } -/// -/// #[derive(PartialEq)] -/// struct Book { -/// isbn: i32, -/// format: BookFormat, -/// } -/// -/// impl PartialEq for Book { -/// fn eq(&self, other: &BookFormat) -> bool { -/// self.format == *other -/// } -/// } -/// -/// impl PartialEq for BookFormat { -/// fn eq(&self, other: &Book) -> bool { -/// *self == other.format -/// } -/// } -/// -/// fn main() { -/// let b1 = Book { isbn: 1, format: BookFormat::Paperback }; -/// let b2 = Book { isbn: 2, format: BookFormat::Paperback }; -/// -/// assert!(b1 == BookFormat::Paperback); -/// assert!(BookFormat::Paperback == b2); -/// -/// // The following should hold by transitivity but doesn't. -/// assert!(b1 == b2); // <-- PANICS -/// } -/// ``` -/// -/// # Examples -/// -/// ``` -/// let x: u32 = 0; -/// let y: u32 = 1; -/// -/// assert_eq!(x == y, false); -/// assert_eq!(x.eq(&y), false); -/// ``` -/// -/// [`eq`]: PartialEq::eq -/// [`ne`]: PartialEq::ne -#[lang = "eq"] -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(alias = "==")] -#[doc(alias = "!=")] -#[rustc_on_unimplemented( - message = "can't compare `{Self}` with `{Rhs}`", - label = "no implementation for `{Self} == {Rhs}`", - append_const_msg -)] -#[rustc_diagnostic_item = "PartialEq"] -#[const_trait] -pub trait PartialEq { - /// This method tests for `self` and `other` values to be equal, and is used - /// by `==`. - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_diagnostic_item = "cmp_partialeq_eq"] - fn eq(&self, other: &Rhs) -> bool; - - /// This method tests for `!=`. The default implementation is almost always - /// sufficient, and should not be overridden without very good reason. - #[inline] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_diagnostic_item = "cmp_partialeq_ne"] - fn ne(&self, other: &Rhs) -> bool { - !self.eq(other) - } -} - -/// Derive macro generating an impl of the trait [`PartialEq`]. -/// The behavior of this macro is described in detail [here](PartialEq#derivable). -#[rustc_builtin_macro] -#[stable(feature = "builtin_macro_prelude", since = "1.38.0")] -#[allow_internal_unstable(core_intrinsics, structural_match)] -pub macro PartialEq($item:item) { - /* compiler built-in */ -} - -/// Trait for comparisons corresponding to [equivalence relations]( -/// https://en.wikipedia.org/wiki/Equivalence_relation). -/// -/// This means, that in addition to `a == b` and `a != b` being strict inverses, -/// the relation must be (for all `a`, `b` and `c`): -/// -/// - reflexive: `a == a`; -/// - symmetric: `a == b` implies `b == a` (required by `PartialEq` as well); and -/// - transitive: `a == b` and `b == c` implies `a == c` (required by `PartialEq` as well). -/// -/// This property cannot be checked by the compiler, and therefore `Eq` implies -/// [`PartialEq`], and has no extra methods. -/// -/// Violating this property is a logic error. The behavior resulting from a logic error is not -/// specified, but users of the trait must ensure that such logic errors do *not* result in -/// undefined behavior. This means that `unsafe` code **must not** rely on the correctness of these -/// methods. -/// -/// Implement `Eq` in addition to `PartialEq` if it's guaranteed that -/// `PartialEq::eq(a, a)` always returns `true` (reflexivity), in addition to -/// the symmetric and transitive properties already required by `PartialEq`. -/// -/// ## Derivable -/// -/// This trait can be used with `#[derive]`. When `derive`d, because `Eq` has -/// no extra methods, it is only informing the compiler that this is an -/// equivalence relation rather than a partial equivalence relation. Note that -/// the `derive` strategy requires all fields are `Eq`, which isn't -/// always desired. -/// -/// ## How can I implement `Eq`? -/// -/// If you cannot use the `derive` strategy, specify that your type implements -/// `Eq`, which has no methods: -/// -/// ``` -/// enum BookFormat { Paperback, Hardback, Ebook } -/// struct Book { -/// isbn: i32, -/// format: BookFormat, -/// } -/// impl PartialEq for Book { -/// fn eq(&self, other: &Self) -> bool { -/// self.isbn == other.isbn -/// } -/// } -/// impl Eq for Book {} -/// ``` -#[doc(alias = "==")] -#[doc(alias = "!=")] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_diagnostic_item = "Eq"] -pub trait Eq: PartialEq { - // this method is used solely by #[derive(Eq)] to assert - // that every component of a type implements `Eq` - // itself. The current deriving infrastructure means doing this - // assertion without using a method on this trait is nearly - // impossible. - // - // This should never be implemented by hand. - #[doc(hidden)] - #[coverage(off)] - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - fn assert_receiver_is_total_eq(&self) {} -} - -/// Derive macro generating an impl of the trait [`Eq`]. -#[rustc_builtin_macro] -#[stable(feature = "builtin_macro_prelude", since = "1.38.0")] -#[allow_internal_unstable(core_intrinsics, derive_eq, structural_match)] -#[allow_internal_unstable(coverage_attribute)] -pub macro Eq($item:item) { - /* compiler built-in */ -} - -// FIXME: this struct is used solely by #[derive] to -// assert that every component of a type implements Eq. -// -// This struct should never appear in user code. -#[doc(hidden)] -#[allow(missing_debug_implementations)] -#[unstable(feature = "derive_eq", reason = "deriving hack, should not be public", issue = "none")] -pub struct AssertParamIsEq { - _field: crate::marker::PhantomData, -} - -/// An `Ordering` is the result of a comparison between two values. -/// -/// # Examples -/// -/// ``` -/// use std::cmp::Ordering; -/// -/// assert_eq!(1.cmp(&2), Ordering::Less); -/// -/// assert_eq!(1.cmp(&1), Ordering::Equal); -/// -/// assert_eq!(2.cmp(&1), Ordering::Greater); -/// ``` -#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)] -#[stable(feature = "rust1", since = "1.0.0")] -// This is a lang item only so that `BinOp::Cmp` in MIR can return it. -// It has no special behaviour, but does require that the three variants -// `Less`/`Equal`/`Greater` remain `-1_i8`/`0_i8`/`+1_i8` respectively. -#[lang = "Ordering"] -#[repr(i8)] -pub enum Ordering { - /// An ordering where a compared value is less than another. - #[stable(feature = "rust1", since = "1.0.0")] - Less = -1, - /// An ordering where a compared value is equal to another. - #[stable(feature = "rust1", since = "1.0.0")] - Equal = 0, - /// An ordering where a compared value is greater than another. - #[stable(feature = "rust1", since = "1.0.0")] - Greater = 1, -} - -impl Ordering { - /// Returns `true` if the ordering is the `Equal` variant. - /// - /// # Examples - /// - /// ``` - /// use std::cmp::Ordering; - /// - /// assert_eq!(Ordering::Less.is_eq(), false); - /// assert_eq!(Ordering::Equal.is_eq(), true); - /// assert_eq!(Ordering::Greater.is_eq(), false); - /// ``` - #[inline] - #[must_use] - #[rustc_const_stable(feature = "ordering_helpers", since = "1.53.0")] - #[stable(feature = "ordering_helpers", since = "1.53.0")] - pub const fn is_eq(self) -> bool { - matches!(self, Equal) - } - - /// Returns `true` if the ordering is not the `Equal` variant. - /// - /// # Examples - /// - /// ``` - /// use std::cmp::Ordering; - /// - /// assert_eq!(Ordering::Less.is_ne(), true); - /// assert_eq!(Ordering::Equal.is_ne(), false); - /// assert_eq!(Ordering::Greater.is_ne(), true); - /// ``` - #[inline] - #[must_use] - #[rustc_const_stable(feature = "ordering_helpers", since = "1.53.0")] - #[stable(feature = "ordering_helpers", since = "1.53.0")] - pub const fn is_ne(self) -> bool { - !matches!(self, Equal) - } - - /// Returns `true` if the ordering is the `Less` variant. - /// - /// # Examples - /// - /// ``` - /// use std::cmp::Ordering; - /// - /// assert_eq!(Ordering::Less.is_lt(), true); - /// assert_eq!(Ordering::Equal.is_lt(), false); - /// assert_eq!(Ordering::Greater.is_lt(), false); - /// ``` - #[inline] - #[must_use] - #[rustc_const_stable(feature = "ordering_helpers", since = "1.53.0")] - #[stable(feature = "ordering_helpers", since = "1.53.0")] - pub const fn is_lt(self) -> bool { - matches!(self, Less) - } - - /// Returns `true` if the ordering is the `Greater` variant. - /// - /// # Examples - /// - /// ``` - /// use std::cmp::Ordering; - /// - /// assert_eq!(Ordering::Less.is_gt(), false); - /// assert_eq!(Ordering::Equal.is_gt(), false); - /// assert_eq!(Ordering::Greater.is_gt(), true); - /// ``` - #[inline] - #[must_use] - #[rustc_const_stable(feature = "ordering_helpers", since = "1.53.0")] - #[stable(feature = "ordering_helpers", since = "1.53.0")] - pub const fn is_gt(self) -> bool { - matches!(self, Greater) - } - - /// Returns `true` if the ordering is either the `Less` or `Equal` variant. - /// - /// # Examples - /// - /// ``` - /// use std::cmp::Ordering; - /// - /// assert_eq!(Ordering::Less.is_le(), true); - /// assert_eq!(Ordering::Equal.is_le(), true); - /// assert_eq!(Ordering::Greater.is_le(), false); - /// ``` - #[inline] - #[must_use] - #[rustc_const_stable(feature = "ordering_helpers", since = "1.53.0")] - #[stable(feature = "ordering_helpers", since = "1.53.0")] - pub const fn is_le(self) -> bool { - !matches!(self, Greater) - } - - /// Returns `true` if the ordering is either the `Greater` or `Equal` variant. - /// - /// # Examples - /// - /// ``` - /// use std::cmp::Ordering; - /// - /// assert_eq!(Ordering::Less.is_ge(), false); - /// assert_eq!(Ordering::Equal.is_ge(), true); - /// assert_eq!(Ordering::Greater.is_ge(), true); - /// ``` - #[inline] - #[must_use] - #[rustc_const_stable(feature = "ordering_helpers", since = "1.53.0")] - #[stable(feature = "ordering_helpers", since = "1.53.0")] - pub const fn is_ge(self) -> bool { - !matches!(self, Less) - } - - /// Reverses the `Ordering`. - /// - /// * `Less` becomes `Greater`. - /// * `Greater` becomes `Less`. - /// * `Equal` becomes `Equal`. - /// - /// # Examples - /// - /// Basic behavior: - /// - /// ``` - /// use std::cmp::Ordering; - /// - /// assert_eq!(Ordering::Less.reverse(), Ordering::Greater); - /// assert_eq!(Ordering::Equal.reverse(), Ordering::Equal); - /// assert_eq!(Ordering::Greater.reverse(), Ordering::Less); - /// ``` - /// - /// This method can be used to reverse a comparison: - /// - /// ``` - /// let data: &mut [_] = &mut [2, 10, 5, 8]; - /// - /// // sort the array from largest to smallest. - /// data.sort_by(|a, b| a.cmp(b).reverse()); - /// - /// let b: &mut [_] = &mut [10, 8, 5, 2]; - /// assert!(data == b); - /// ``` - #[inline] - #[must_use] - #[rustc_const_stable(feature = "const_ordering", since = "1.48.0")] - #[stable(feature = "rust1", since = "1.0.0")] - pub const fn reverse(self) -> Ordering { - match self { - Less => Greater, - Equal => Equal, - Greater => Less, - } - } - - /// Chains two orderings. - /// - /// Returns `self` when it's not `Equal`. Otherwise returns `other`. - /// - /// # Examples - /// - /// ``` - /// use std::cmp::Ordering; - /// - /// let result = Ordering::Equal.then(Ordering::Less); - /// assert_eq!(result, Ordering::Less); - /// - /// let result = Ordering::Less.then(Ordering::Equal); - /// assert_eq!(result, Ordering::Less); - /// - /// let result = Ordering::Less.then(Ordering::Greater); - /// assert_eq!(result, Ordering::Less); - /// - /// let result = Ordering::Equal.then(Ordering::Equal); - /// assert_eq!(result, Ordering::Equal); - /// - /// let x: (i64, i64, i64) = (1, 2, 7); - /// let y: (i64, i64, i64) = (1, 5, 3); - /// let result = x.0.cmp(&y.0).then(x.1.cmp(&y.1)).then(x.2.cmp(&y.2)); - /// - /// assert_eq!(result, Ordering::Less); - /// ``` - #[inline] - #[must_use] - #[rustc_const_stable(feature = "const_ordering", since = "1.48.0")] - #[stable(feature = "ordering_chaining", since = "1.17.0")] - pub const fn then(self, other: Ordering) -> Ordering { - match self { - Equal => other, - _ => self, - } - } - - /// Chains the ordering with the given function. - /// - /// Returns `self` when it's not `Equal`. Otherwise calls `f` and returns - /// the result. - /// - /// # Examples - /// - /// ``` - /// use std::cmp::Ordering; - /// - /// let result = Ordering::Equal.then_with(|| Ordering::Less); - /// assert_eq!(result, Ordering::Less); - /// - /// let result = Ordering::Less.then_with(|| Ordering::Equal); - /// assert_eq!(result, Ordering::Less); - /// - /// let result = Ordering::Less.then_with(|| Ordering::Greater); - /// assert_eq!(result, Ordering::Less); - /// - /// let result = Ordering::Equal.then_with(|| Ordering::Equal); - /// assert_eq!(result, Ordering::Equal); - /// - /// let x: (i64, i64, i64) = (1, 2, 7); - /// let y: (i64, i64, i64) = (1, 5, 3); - /// let result = x.0.cmp(&y.0).then_with(|| x.1.cmp(&y.1)).then_with(|| x.2.cmp(&y.2)); - /// - /// assert_eq!(result, Ordering::Less); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "ordering_chaining", since = "1.17.0")] - pub fn then_with Ordering>(self, f: F) -> Ordering { - match self { - Equal => f(), - _ => self, - } - } -} - -/// A helper struct for reverse ordering. -/// -/// This struct is a helper to be used with functions like [`Vec::sort_by_key`] and -/// can be used to reverse order a part of a key. -/// -/// [`Vec::sort_by_key`]: ../../std/vec/struct.Vec.html#method.sort_by_key -/// -/// # Examples -/// -/// ``` -/// use std::cmp::Reverse; -/// -/// let mut v = vec![1, 2, 3, 4, 5, 6]; -/// v.sort_by_key(|&num| (num > 3, Reverse(num))); -/// assert_eq!(v, vec![3, 2, 1, 6, 5, 4]); -/// ``` -#[derive(PartialEq, Eq, Debug, Copy, Default, Hash)] -#[stable(feature = "reverse_cmp_key", since = "1.19.0")] -#[repr(transparent)] -pub struct Reverse(#[stable(feature = "reverse_cmp_key", since = "1.19.0")] pub T); - -#[stable(feature = "reverse_cmp_key", since = "1.19.0")] -impl PartialOrd for Reverse { - #[inline] - fn partial_cmp(&self, other: &Reverse) -> Option { - other.0.partial_cmp(&self.0) - } - - #[inline] - fn lt(&self, other: &Self) -> bool { - other.0 < self.0 - } - #[inline] - fn le(&self, other: &Self) -> bool { - other.0 <= self.0 - } - #[inline] - fn gt(&self, other: &Self) -> bool { - other.0 > self.0 - } - #[inline] - fn ge(&self, other: &Self) -> bool { - other.0 >= self.0 - } -} - -#[stable(feature = "reverse_cmp_key", since = "1.19.0")] -impl Ord for Reverse { - #[inline] - fn cmp(&self, other: &Reverse) -> Ordering { - other.0.cmp(&self.0) - } -} - -#[stable(feature = "reverse_cmp_key", since = "1.19.0")] -impl Clone for Reverse { - #[inline] - fn clone(&self) -> Reverse { - Reverse(self.0.clone()) - } - - #[inline] - fn clone_from(&mut self, source: &Self) { - self.0.clone_from(&source.0) - } -} - -/// Trait for types that form a [total order](https://en.wikipedia.org/wiki/Total_order). -/// -/// Implementations must be consistent with the [`PartialOrd`] implementation, and ensure -/// `max`, `min`, and `clamp` are consistent with `cmp`: -/// -/// - `partial_cmp(a, b) == Some(cmp(a, b))`. -/// - `max(a, b) == max_by(a, b, cmp)` (ensured by the default implementation). -/// - `min(a, b) == min_by(a, b, cmp)` (ensured by the default implementation). -/// - For `a.clamp(min, max)`, see the [method docs](#method.clamp) -/// (ensured by the default implementation). -/// -/// It's easy to accidentally make `cmp` and `partial_cmp` disagree by -/// deriving some of the traits and manually implementing others. -/// -/// Violating these requirements is a logic error. The behavior resulting from a logic error is not -/// specified, but users of the trait must ensure that such logic errors do *not* result in -/// undefined behavior. This means that `unsafe` code **must not** rely on the correctness of these -/// methods. -/// -/// ## Corollaries -/// -/// From the above and the requirements of `PartialOrd`, it follows that for -/// all `a`, `b` and `c`: -/// -/// - exactly one of `a < b`, `a == b` or `a > b` is true; and -/// - `<` is transitive: `a < b` and `b < c` implies `a < c`. The same must hold for both `==` and `>`. -/// -/// Mathematically speaking, the `<` operator defines a strict [weak order]. In -/// cases where `==` conforms to mathematical equality, it also defines a -/// strict [total order]. -/// -/// [weak order]: https://en.wikipedia.org/wiki/Weak_ordering -/// [total order]: https://en.wikipedia.org/wiki/Total_order -/// -/// ## Derivable -/// -/// This trait can be used with `#[derive]`. -/// -/// When `derive`d on structs, it will produce a -/// [lexicographic](https://en.wikipedia.org/wiki/Lexicographic_order) ordering -/// based on the top-to-bottom declaration order of the struct's members. -/// -/// When `derive`d on enums, variants are ordered primarily by their discriminants. -/// Secondarily, they are ordered by their fields. -/// By default, the discriminant is smallest for variants at the top, and -/// largest for variants at the bottom. Here's an example: -/// -/// ``` -/// #[derive(PartialEq, Eq, PartialOrd, Ord)] -/// enum E { -/// Top, -/// Bottom, -/// } -/// -/// assert!(E::Top < E::Bottom); -/// ``` -/// -/// However, manually setting the discriminants can override this default -/// behavior: -/// -/// ``` -/// #[derive(PartialEq, Eq, PartialOrd, Ord)] -/// enum E { -/// Top = 2, -/// Bottom = 1, -/// } -/// -/// assert!(E::Bottom < E::Top); -/// ``` -/// -/// ## Lexicographical comparison -/// -/// Lexicographical comparison is an operation with the following properties: -/// - Two sequences are compared element by element. -/// - The first mismatching element defines which sequence is lexicographically less or greater than the other. -/// - If one sequence is a prefix of another, the shorter sequence is lexicographically less than the other. -/// - If two sequences have equivalent elements and are of the same length, then the sequences are lexicographically equal. -/// - An empty sequence is lexicographically less than any non-empty sequence. -/// - Two empty sequences are lexicographically equal. -/// -/// ## How can I implement `Ord`? -/// -/// `Ord` requires that the type also be [`PartialOrd`] and [`Eq`] (which requires [`PartialEq`]). -/// -/// Then you must define an implementation for [`cmp`]. You may find it useful to use -/// [`cmp`] on your type's fields. -/// -/// Here's an example where you want to sort people by height only, disregarding `id` -/// and `name`: -/// -/// ``` -/// use std::cmp::Ordering; -/// -/// #[derive(Eq)] -/// struct Person { -/// id: u32, -/// name: String, -/// height: u32, -/// } -/// -/// impl Ord for Person { -/// fn cmp(&self, other: &Self) -> Ordering { -/// self.height.cmp(&other.height) -/// } -/// } -/// -/// impl PartialOrd for Person { -/// fn partial_cmp(&self, other: &Self) -> Option { -/// Some(self.cmp(other)) -/// } -/// } -/// -/// impl PartialEq for Person { -/// fn eq(&self, other: &Self) -> bool { -/// self.height == other.height -/// } -/// } -/// ``` -/// -/// [`cmp`]: Ord::cmp -#[doc(alias = "<")] -#[doc(alias = ">")] -#[doc(alias = "<=")] -#[doc(alias = ">=")] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_diagnostic_item = "Ord"] -pub trait Ord: Eq + PartialOrd { - /// This method returns an [`Ordering`] between `self` and `other`. - /// - /// By convention, `self.cmp(&other)` returns the ordering matching the expression - /// `self other` if true. - /// - /// # Examples - /// - /// ``` - /// use std::cmp::Ordering; - /// - /// assert_eq!(5.cmp(&10), Ordering::Less); - /// assert_eq!(10.cmp(&5), Ordering::Greater); - /// assert_eq!(5.cmp(&5), Ordering::Equal); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_diagnostic_item = "ord_cmp_method"] - fn cmp(&self, other: &Self) -> Ordering; - - /// Compares and returns the maximum of two values. - /// - /// Returns the second argument if the comparison determines them to be equal. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(1.max(2), 2); - /// assert_eq!(2.max(2), 2); - /// ``` - #[stable(feature = "ord_max_min", since = "1.21.0")] - #[inline] - #[must_use] - #[rustc_diagnostic_item = "cmp_ord_max"] - fn max(self, other: Self) -> Self - where - Self: Sized, - { - max_by(self, other, Ord::cmp) - } - - /// Compares and returns the minimum of two values. - /// - /// Returns the first argument if the comparison determines them to be equal. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(1.min(2), 1); - /// assert_eq!(2.min(2), 2); - /// ``` - #[stable(feature = "ord_max_min", since = "1.21.0")] - #[inline] - #[must_use] - #[rustc_diagnostic_item = "cmp_ord_min"] - fn min(self, other: Self) -> Self - where - Self: Sized, - { - min_by(self, other, Ord::cmp) - } - - /// Restrict a value to a certain interval. - /// - /// Returns `max` if `self` is greater than `max`, and `min` if `self` is - /// less than `min`. Otherwise this returns `self`. - /// - /// # Panics - /// - /// Panics if `min > max`. - /// - /// # Examples - /// - /// ``` - /// assert_eq!((-3).clamp(-2, 1), -2); - /// assert_eq!(0.clamp(-2, 1), 0); - /// assert_eq!(2.clamp(-2, 1), 1); - /// ``` - #[must_use] - #[inline] - #[stable(feature = "clamp", since = "1.50.0")] - fn clamp(self, min: Self, max: Self) -> Self - where - Self: Sized, - Self: PartialOrd, - { - assert!(min <= max); - if self < min { - min - } else if self > max { - max - } else { - self - } - } -} - -/// Derive macro generating an impl of the trait [`Ord`]. -/// The behavior of this macro is described in detail [here](Ord#derivable). -#[rustc_builtin_macro] -#[stable(feature = "builtin_macro_prelude", since = "1.38.0")] -#[allow_internal_unstable(core_intrinsics)] -pub macro Ord($item:item) { - /* compiler built-in */ -} - -/// Trait for types that form a [partial order](https://en.wikipedia.org/wiki/Partial_order). -/// -/// The `lt`, `le`, `gt`, and `ge` methods of this trait can be called using -/// the `<`, `<=`, `>`, and `>=` operators, respectively. -/// -/// The methods of this trait must be consistent with each other and with those of [`PartialEq`]. -/// The following conditions must hold: -/// -/// 1. `a == b` if and only if `partial_cmp(a, b) == Some(Equal)`. -/// 2. `a < b` if and only if `partial_cmp(a, b) == Some(Less)` -/// 3. `a > b` if and only if `partial_cmp(a, b) == Some(Greater)` -/// 4. `a <= b` if and only if `a < b || a == b` -/// 5. `a >= b` if and only if `a > b || a == b` -/// 6. `a != b` if and only if `!(a == b)`. -/// -/// Conditions 2–5 above are ensured by the default implementation. -/// Condition 6 is already ensured by [`PartialEq`]. -/// -/// If [`Ord`] is also implemented for `Self` and `Rhs`, it must also be consistent with -/// `partial_cmp` (see the documentation of that trait for the exact requirements). It's -/// easy to accidentally make them disagree by deriving some of the traits and manually -/// implementing others. -/// -/// The comparison relations must satisfy the following conditions -/// (for all `a`, `b`, `c` of type `A`, `B`, `C`): -/// -/// - **Transitivity**: if `A: PartialOrd` and `B: PartialOrd` and `A: -/// PartialOrd`, then `a < b` and `b < c` implies `a < c`. The same must hold for both `==` and `>`. -/// This must also work for longer chains, such as when `A: PartialOrd`, `B: PartialOrd`, -/// `C: PartialOrd`, and `A: PartialOrd` all exist. -/// - **Duality**: if `A: PartialOrd` and `B: PartialOrd`, then `a < b` if and only if `b > a`. -/// -/// Note that the `B: PartialOrd` (dual) and `A: PartialOrd` -/// (transitive) impls are not forced to exist, but these requirements apply -/// whenever they do exist. -/// -/// Violating these requirements is a logic error. The behavior resulting from a logic error is not -/// specified, but users of the trait must ensure that such logic errors do *not* result in -/// undefined behavior. This means that `unsafe` code **must not** rely on the correctness of these -/// methods. -/// -/// ## Cross-crate considerations -/// -/// Upholding the requirements stated above can become tricky when one crate implements `PartialOrd` -/// for a type of another crate (i.e., to allow comparing one of its own types with a type from the -/// standard library). The recommendation is to never implement this trait for a foreign type. In -/// other words, such a crate should do `impl PartialOrd for LocalType`, but it should -/// *not* do `impl PartialOrd for ForeignType`. -/// -/// This avoids the problem of transitive chains that criss-cross crate boundaries: for all local -/// types `T`, you may assume that no other crate will add `impl`s that allow comparing `T < U`. In -/// other words, if other crates add `impl`s that allow building longer transitive chains `U1 < ... -/// < T < V1 < ...`, then all the types that appear to the right of `T` must be types that the crate -/// defining `T` already knows about. This rules out transitive chains where downstream crates can -/// add new `impl`s that "stitch together" comparisons of foreign types in ways that violate -/// transitivity. -/// -/// Not having such foreign `impl`s also avoids forward compatibility issues where one crate adding -/// more `PartialOrd` implementations can cause build failures in downstream crates. -/// -/// ## Corollaries -/// -/// The following corollaries follow from the above requirements: -/// -/// - irreflexivity of `<` and `>`: `!(a < a)`, `!(a > a)` -/// - transitivity of `>`: if `a > b` and `b > c` then `a > c` -/// - duality of `partial_cmp`: `partial_cmp(a, b) == partial_cmp(b, a).map(Ordering::reverse)` -/// -/// ## Strict and non-strict partial orders -/// -/// The `<` and `>` operators behave according to a *strict* partial order. -/// However, `<=` and `>=` do **not** behave according to a *non-strict* -/// partial order. -/// That is because mathematically, a non-strict partial order would require -/// reflexivity, i.e. `a <= a` would need to be true for every `a`. This isn't -/// always the case for types that implement `PartialOrd`, for example: -/// -/// ``` -/// let a = f64::sqrt(-1.0); -/// assert_eq!(a <= a, false); -/// ``` -/// -/// ## Derivable -/// -/// This trait can be used with `#[derive]`. -/// -/// When `derive`d on structs, it will produce a -/// [lexicographic](https://en.wikipedia.org/wiki/Lexicographic_order) ordering -/// based on the top-to-bottom declaration order of the struct's members. -/// -/// When `derive`d on enums, variants are primarily ordered by their discriminants. -/// Secondarily, they are ordered by their fields. -/// By default, the discriminant is smallest for variants at the top, and -/// largest for variants at the bottom. Here's an example: -/// -/// ``` -/// #[derive(PartialEq, PartialOrd)] -/// enum E { -/// Top, -/// Bottom, -/// } -/// -/// assert!(E::Top < E::Bottom); -/// ``` -/// -/// However, manually setting the discriminants can override this default -/// behavior: -/// -/// ``` -/// #[derive(PartialEq, PartialOrd)] -/// enum E { -/// Top = 2, -/// Bottom = 1, -/// } -/// -/// assert!(E::Bottom < E::Top); -/// ``` -/// -/// ## How can I implement `PartialOrd`? -/// -/// `PartialOrd` only requires implementation of the [`partial_cmp`] method, with the others -/// generated from default implementations. -/// -/// However it remains possible to implement the others separately for types which do not have a -/// total order. For example, for floating point numbers, `NaN < 0 == false` and `NaN >= 0 == -/// false` (cf. IEEE 754-2008 section 5.11). -/// -/// `PartialOrd` requires your type to be [`PartialEq`]. -/// -/// If your type is [`Ord`], you can implement [`partial_cmp`] by using [`cmp`]: -/// -/// ``` -/// use std::cmp::Ordering; -/// -/// #[derive(Eq)] -/// struct Person { -/// id: u32, -/// name: String, -/// height: u32, -/// } -/// -/// impl PartialOrd for Person { -/// fn partial_cmp(&self, other: &Self) -> Option { -/// Some(self.cmp(other)) -/// } -/// } -/// -/// impl Ord for Person { -/// fn cmp(&self, other: &Self) -> Ordering { -/// self.height.cmp(&other.height) -/// } -/// } -/// -/// impl PartialEq for Person { -/// fn eq(&self, other: &Self) -> bool { -/// self.height == other.height -/// } -/// } -/// ``` -/// -/// You may also find it useful to use [`partial_cmp`] on your type's fields. Here -/// is an example of `Person` types who have a floating-point `height` field that -/// is the only field to be used for sorting: -/// -/// ``` -/// use std::cmp::Ordering; -/// -/// struct Person { -/// id: u32, -/// name: String, -/// height: f64, -/// } -/// -/// impl PartialOrd for Person { -/// fn partial_cmp(&self, other: &Self) -> Option { -/// self.height.partial_cmp(&other.height) -/// } -/// } -/// -/// impl PartialEq for Person { -/// fn eq(&self, other: &Self) -> bool { -/// self.height == other.height -/// } -/// } -/// ``` -/// -/// # Examples -/// -/// ``` -/// let x: u32 = 0; -/// let y: u32 = 1; -/// -/// assert_eq!(x < y, true); -/// assert_eq!(x.lt(&y), true); -/// ``` -/// -/// [`partial_cmp`]: PartialOrd::partial_cmp -/// [`cmp`]: Ord::cmp -#[lang = "partial_ord"] -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(alias = ">")] -#[doc(alias = "<")] -#[doc(alias = "<=")] -#[doc(alias = ">=")] -#[rustc_on_unimplemented( - message = "can't compare `{Self}` with `{Rhs}`", - label = "no implementation for `{Self} < {Rhs}` and `{Self} > {Rhs}`", - append_const_msg -)] -#[rustc_diagnostic_item = "PartialOrd"] -pub trait PartialOrd: PartialEq { - /// This method returns an ordering between `self` and `other` values if one exists. - /// - /// # Examples - /// - /// ``` - /// use std::cmp::Ordering; - /// - /// let result = 1.0.partial_cmp(&2.0); - /// assert_eq!(result, Some(Ordering::Less)); - /// - /// let result = 1.0.partial_cmp(&1.0); - /// assert_eq!(result, Some(Ordering::Equal)); - /// - /// let result = 2.0.partial_cmp(&1.0); - /// assert_eq!(result, Some(Ordering::Greater)); - /// ``` - /// - /// When comparison is impossible: - /// - /// ``` - /// let result = f64::NAN.partial_cmp(&1.0); - /// assert_eq!(result, None); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_diagnostic_item = "cmp_partialord_cmp"] - fn partial_cmp(&self, other: &Rhs) -> Option; - - /// This method tests less than (for `self` and `other`) and is used by the `<` operator. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(1.0 < 1.0, false); - /// assert_eq!(1.0 < 2.0, true); - /// assert_eq!(2.0 < 1.0, false); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_diagnostic_item = "cmp_partialord_lt"] - fn lt(&self, other: &Rhs) -> bool { - matches!(self.partial_cmp(other), Some(Less)) - } - - /// This method tests less than or equal to (for `self` and `other`) and is used by the `<=` - /// operator. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(1.0 <= 1.0, true); - /// assert_eq!(1.0 <= 2.0, true); - /// assert_eq!(2.0 <= 1.0, false); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_diagnostic_item = "cmp_partialord_le"] - fn le(&self, other: &Rhs) -> bool { - matches!(self.partial_cmp(other), Some(Less | Equal)) - } - - /// This method tests greater than (for `self` and `other`) and is used by the `>` operator. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(1.0 > 1.0, false); - /// assert_eq!(1.0 > 2.0, false); - /// assert_eq!(2.0 > 1.0, true); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_diagnostic_item = "cmp_partialord_gt"] - fn gt(&self, other: &Rhs) -> bool { - matches!(self.partial_cmp(other), Some(Greater)) - } - - /// This method tests greater than or equal to (for `self` and `other`) and is used by the `>=` - /// operator. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(1.0 >= 1.0, true); - /// assert_eq!(1.0 >= 2.0, false); - /// assert_eq!(2.0 >= 1.0, true); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_diagnostic_item = "cmp_partialord_ge"] - fn ge(&self, other: &Rhs) -> bool { - matches!(self.partial_cmp(other), Some(Greater | Equal)) - } -} - -/// Derive macro generating an impl of the trait [`PartialOrd`]. -/// The behavior of this macro is described in detail [here](PartialOrd#derivable). -#[rustc_builtin_macro] -#[stable(feature = "builtin_macro_prelude", since = "1.38.0")] -#[allow_internal_unstable(core_intrinsics)] -pub macro PartialOrd($item:item) { - /* compiler built-in */ -} - -/// Compares and returns the minimum of two values. -/// -/// Returns the first argument if the comparison determines them to be equal. -/// -/// Internally uses an alias to [`Ord::min`]. -/// -/// # Examples -/// -/// ``` -/// use std::cmp; -/// -/// assert_eq!(cmp::min(1, 2), 1); -/// assert_eq!(cmp::min(2, 2), 2); -/// ``` -#[inline] -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "cmp_min")] -pub fn min(v1: T, v2: T) -> T { - v1.min(v2) -} - -/// Returns the minimum of two values with respect to the specified comparison function. -/// -/// Returns the first argument if the comparison determines them to be equal. -/// -/// # Examples -/// -/// ``` -/// use std::cmp; -/// -/// let result = cmp::min_by(-2, 1, |x: &i32, y: &i32| x.abs().cmp(&y.abs())); -/// assert_eq!(result, 1); -/// -/// let result = cmp::min_by(-2, 3, |x: &i32, y: &i32| x.abs().cmp(&y.abs())); -/// assert_eq!(result, -2); -/// ``` -#[inline] -#[must_use] -#[stable(feature = "cmp_min_max_by", since = "1.53.0")] -pub fn min_by Ordering>(v1: T, v2: T, compare: F) -> T { - match compare(&v1, &v2) { - Ordering::Less | Ordering::Equal => v1, - Ordering::Greater => v2, - } -} - -/// Returns the element that gives the minimum value from the specified function. -/// -/// Returns the first argument if the comparison determines them to be equal. -/// -/// # Examples -/// -/// ``` -/// use std::cmp; -/// -/// let result = cmp::min_by_key(-2, 1, |x: &i32| x.abs()); -/// assert_eq!(result, 1); -/// -/// let result = cmp::min_by_key(-2, 2, |x: &i32| x.abs()); -/// assert_eq!(result, -2); -/// ``` -#[inline] -#[must_use] -#[stable(feature = "cmp_min_max_by", since = "1.53.0")] -pub fn min_by_key K, K: Ord>(v1: T, v2: T, mut f: F) -> T { - min_by(v1, v2, |v1, v2| f(v1).cmp(&f(v2))) -} - -/// Compares and returns the maximum of two values. -/// -/// Returns the second argument if the comparison determines them to be equal. -/// -/// Internally uses an alias to [`Ord::max`]. -/// -/// # Examples -/// -/// ``` -/// use std::cmp; -/// -/// assert_eq!(cmp::max(1, 2), 2); -/// assert_eq!(cmp::max(2, 2), 2); -/// ``` -#[inline] -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "cmp_max")] -pub fn max(v1: T, v2: T) -> T { - v1.max(v2) -} - -/// Returns the maximum of two values with respect to the specified comparison function. -/// -/// Returns the second argument if the comparison determines them to be equal. -/// -/// # Examples -/// -/// ``` -/// use std::cmp; -/// -/// let result = cmp::max_by(-2, 1, |x: &i32, y: &i32| x.abs().cmp(&y.abs())); -/// assert_eq!(result, -2); -/// -/// let result = cmp::max_by(-2, 2, |x: &i32, y: &i32| x.abs().cmp(&y.abs())) ; -/// assert_eq!(result, 2); -/// ``` -#[inline] -#[must_use] -#[stable(feature = "cmp_min_max_by", since = "1.53.0")] -pub fn max_by Ordering>(v1: T, v2: T, compare: F) -> T { - match compare(&v1, &v2) { - Ordering::Less | Ordering::Equal => v2, - Ordering::Greater => v1, - } -} - -/// Returns the element that gives the maximum value from the specified function. -/// -/// Returns the second argument if the comparison determines them to be equal. -/// -/// # Examples -/// -/// ``` -/// use std::cmp; -/// -/// let result = cmp::max_by_key(-2, 1, |x: &i32| x.abs()); -/// assert_eq!(result, -2); -/// -/// let result = cmp::max_by_key(-2, 2, |x: &i32| x.abs()); -/// assert_eq!(result, 2); -/// ``` -#[inline] -#[must_use] -#[stable(feature = "cmp_min_max_by", since = "1.53.0")] -pub fn max_by_key K, K: Ord>(v1: T, v2: T, mut f: F) -> T { - max_by(v1, v2, |v1, v2| f(v1).cmp(&f(v2))) -} - -/// Compares and sorts two values, returning minimum and maximum. -/// -/// Returns `[v1, v2]` if the comparison determines them to be equal. -/// -/// # Examples -/// -/// ``` -/// #![feature(cmp_minmax)] -/// use std::cmp; -/// -/// assert_eq!(cmp::minmax(1, 2), [1, 2]); -/// assert_eq!(cmp::minmax(2, 2), [2, 2]); -/// -/// // You can destructure the result using array patterns -/// let [min, max] = cmp::minmax(42, 17); -/// assert_eq!(min, 17); -/// assert_eq!(max, 42); -/// ``` -#[inline] -#[must_use] -#[unstable(feature = "cmp_minmax", issue = "115939")] -pub fn minmax(v1: T, v2: T) -> [T; 2] -where - T: Ord, -{ - if v1 <= v2 { [v1, v2] } else { [v2, v1] } -} - -/// Returns minimum and maximum values with respect to the specified comparison function. -/// -/// Returns `[v1, v2]` if the comparison determines them to be equal. -/// -/// # Examples -/// -/// ``` -/// #![feature(cmp_minmax)] -/// use std::cmp; -/// -/// assert_eq!(cmp::minmax_by(-2, 1, |x: &i32, y: &i32| x.abs().cmp(&y.abs())), [1, -2]); -/// assert_eq!(cmp::minmax_by(-2, 2, |x: &i32, y: &i32| x.abs().cmp(&y.abs())), [-2, 2]); -/// -/// // You can destructure the result using array patterns -/// let [min, max] = cmp::minmax_by(-42, 17, |x: &i32, y: &i32| x.abs().cmp(&y.abs())); -/// assert_eq!(min, 17); -/// assert_eq!(max, -42); -/// ``` -#[inline] -#[must_use] -#[unstable(feature = "cmp_minmax", issue = "115939")] -pub fn minmax_by(v1: T, v2: T, compare: F) -> [T; 2] -where - F: FnOnce(&T, &T) -> Ordering, -{ - if compare(&v1, &v2).is_le() { [v1, v2] } else { [v2, v1] } -} - -/// Returns minimum and maximum values with respect to the specified key function. -/// -/// Returns `[v1, v2]` if the comparison determines them to be equal. -/// -/// # Examples -/// -/// ``` -/// #![feature(cmp_minmax)] -/// use std::cmp; -/// -/// assert_eq!(cmp::minmax_by_key(-2, 1, |x: &i32| x.abs()), [1, -2]); -/// assert_eq!(cmp::minmax_by_key(-2, 2, |x: &i32| x.abs()), [-2, 2]); -/// -/// // You can destructure the result using array patterns -/// let [min, max] = cmp::minmax_by_key(-42, 17, |x: &i32| x.abs()); -/// assert_eq!(min, 17); -/// assert_eq!(max, -42); -/// ``` -#[inline] -#[must_use] -#[unstable(feature = "cmp_minmax", issue = "115939")] -pub fn minmax_by_key(v1: T, v2: T, mut f: F) -> [T; 2] -where - F: FnMut(&T) -> K, - K: Ord, -{ - minmax_by(v1, v2, |v1, v2| f(v1).cmp(&f(v2))) -} - -// Implementation of PartialEq, Eq, PartialOrd and Ord for primitive types -mod impls { - use crate::cmp::Ordering::{self, Equal, Greater, Less}; - use crate::hint::unreachable_unchecked; - - macro_rules! partial_eq_impl { - ($($t:ty)*) => ($( - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_cmp", issue = "92391")] - impl const PartialEq for $t { - #[inline] - fn eq(&self, other: &$t) -> bool { (*self) == (*other) } - #[inline] - fn ne(&self, other: &$t) -> bool { (*self) != (*other) } - } - )*) - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl PartialEq for () { - #[inline] - fn eq(&self, _other: &()) -> bool { - true - } - #[inline] - fn ne(&self, _other: &()) -> bool { - false - } - } - - partial_eq_impl! { - bool char usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f16 f32 f64 f128 - } - - macro_rules! eq_impl { - ($($t:ty)*) => ($( - #[stable(feature = "rust1", since = "1.0.0")] - impl Eq for $t {} - )*) - } - - eq_impl! { () bool char usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 } - - macro_rules! partial_ord_impl { - ($($t:ty)*) => ($( - #[stable(feature = "rust1", since = "1.0.0")] - impl PartialOrd for $t { - #[inline] - fn partial_cmp(&self, other: &$t) -> Option { - match (*self <= *other, *self >= *other) { - (false, false) => None, - (false, true) => Some(Greater), - (true, false) => Some(Less), - (true, true) => Some(Equal), - } - } - #[inline(always)] - fn lt(&self, other: &$t) -> bool { (*self) < (*other) } - #[inline(always)] - fn le(&self, other: &$t) -> bool { (*self) <= (*other) } - #[inline(always)] - fn ge(&self, other: &$t) -> bool { (*self) >= (*other) } - #[inline(always)] - fn gt(&self, other: &$t) -> bool { (*self) > (*other) } - } - )*) - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl PartialOrd for () { - #[inline] - fn partial_cmp(&self, _: &()) -> Option { - Some(Equal) - } - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl PartialOrd for bool { - #[inline] - fn partial_cmp(&self, other: &bool) -> Option { - Some(self.cmp(other)) - } - } - - partial_ord_impl! { f16 f32 f64 f128 } - - macro_rules! ord_impl { - ($($t:ty)*) => ($( - #[stable(feature = "rust1", since = "1.0.0")] - impl PartialOrd for $t { - #[inline] - fn partial_cmp(&self, other: &$t) -> Option { - Some(crate::intrinsics::three_way_compare(*self, *other)) - } - #[inline(always)] - fn lt(&self, other: &$t) -> bool { (*self) < (*other) } - #[inline(always)] - fn le(&self, other: &$t) -> bool { (*self) <= (*other) } - #[inline(always)] - fn ge(&self, other: &$t) -> bool { (*self) >= (*other) } - #[inline(always)] - fn gt(&self, other: &$t) -> bool { (*self) > (*other) } - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl Ord for $t { - #[inline] - fn cmp(&self, other: &$t) -> Ordering { - crate::intrinsics::three_way_compare(*self, *other) - } - } - )*) - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl Ord for () { - #[inline] - fn cmp(&self, _other: &()) -> Ordering { - Equal - } - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl Ord for bool { - #[inline] - fn cmp(&self, other: &bool) -> Ordering { - // Casting to i8's and converting the difference to an Ordering generates - // more optimal assembly. - // See for more info. - match (*self as i8) - (*other as i8) { - -1 => Less, - 0 => Equal, - 1 => Greater, - // SAFETY: bool as i8 returns 0 or 1, so the difference can't be anything else - _ => unsafe { unreachable_unchecked() }, - } - } - - #[inline] - fn min(self, other: bool) -> bool { - self & other - } - - #[inline] - fn max(self, other: bool) -> bool { - self | other - } - - #[inline] - fn clamp(self, min: bool, max: bool) -> bool { - assert!(min <= max); - self.max(min).min(max) - } - } - - ord_impl! { char usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 } - - #[unstable(feature = "never_type", issue = "35121")] - impl PartialEq for ! { - #[inline] - fn eq(&self, _: &!) -> bool { - *self - } - } - - #[unstable(feature = "never_type", issue = "35121")] - impl Eq for ! {} - - #[unstable(feature = "never_type", issue = "35121")] - impl PartialOrd for ! { - #[inline] - fn partial_cmp(&self, _: &!) -> Option { - *self - } - } - - #[unstable(feature = "never_type", issue = "35121")] - impl Ord for ! { - #[inline] - fn cmp(&self, _: &!) -> Ordering { - *self - } - } - - // & pointers - - #[stable(feature = "rust1", since = "1.0.0")] - impl PartialEq<&B> for &A - where - A: PartialEq, - { - #[inline] - fn eq(&self, other: &&B) -> bool { - PartialEq::eq(*self, *other) - } - #[inline] - fn ne(&self, other: &&B) -> bool { - PartialEq::ne(*self, *other) - } - } - #[stable(feature = "rust1", since = "1.0.0")] - impl PartialOrd<&B> for &A - where - A: PartialOrd, - { - #[inline] - fn partial_cmp(&self, other: &&B) -> Option { - PartialOrd::partial_cmp(*self, *other) - } - #[inline] - fn lt(&self, other: &&B) -> bool { - PartialOrd::lt(*self, *other) - } - #[inline] - fn le(&self, other: &&B) -> bool { - PartialOrd::le(*self, *other) - } - #[inline] - fn gt(&self, other: &&B) -> bool { - PartialOrd::gt(*self, *other) - } - #[inline] - fn ge(&self, other: &&B) -> bool { - PartialOrd::ge(*self, *other) - } - } - #[stable(feature = "rust1", since = "1.0.0")] - impl Ord for &A - where - A: Ord, - { - #[inline] - fn cmp(&self, other: &Self) -> Ordering { - Ord::cmp(*self, *other) - } - } - #[stable(feature = "rust1", since = "1.0.0")] - impl Eq for &A where A: Eq {} - - // &mut pointers - - #[stable(feature = "rust1", since = "1.0.0")] - impl PartialEq<&mut B> for &mut A - where - A: PartialEq, - { - #[inline] - fn eq(&self, other: &&mut B) -> bool { - PartialEq::eq(*self, *other) - } - #[inline] - fn ne(&self, other: &&mut B) -> bool { - PartialEq::ne(*self, *other) - } - } - #[stable(feature = "rust1", since = "1.0.0")] - impl PartialOrd<&mut B> for &mut A - where - A: PartialOrd, - { - #[inline] - fn partial_cmp(&self, other: &&mut B) -> Option { - PartialOrd::partial_cmp(*self, *other) - } - #[inline] - fn lt(&self, other: &&mut B) -> bool { - PartialOrd::lt(*self, *other) - } - #[inline] - fn le(&self, other: &&mut B) -> bool { - PartialOrd::le(*self, *other) - } - #[inline] - fn gt(&self, other: &&mut B) -> bool { - PartialOrd::gt(*self, *other) - } - #[inline] - fn ge(&self, other: &&mut B) -> bool { - PartialOrd::ge(*self, *other) - } - } - #[stable(feature = "rust1", since = "1.0.0")] - impl Ord for &mut A - where - A: Ord, - { - #[inline] - fn cmp(&self, other: &Self) -> Ordering { - Ord::cmp(*self, *other) - } - } - #[stable(feature = "rust1", since = "1.0.0")] - impl Eq for &mut A where A: Eq {} - - #[stable(feature = "rust1", since = "1.0.0")] - impl PartialEq<&mut B> for &A - where - A: PartialEq, - { - #[inline] - fn eq(&self, other: &&mut B) -> bool { - PartialEq::eq(*self, *other) - } - #[inline] - fn ne(&self, other: &&mut B) -> bool { - PartialEq::ne(*self, *other) - } - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl PartialEq<&B> for &mut A - where - A: PartialEq, - { - #[inline] - fn eq(&self, other: &&B) -> bool { - PartialEq::eq(*self, *other) - } - #[inline] - fn ne(&self, other: &&B) -> bool { - PartialEq::ne(*self, *other) - } - } -} diff --git a/library/core/src/cmp/bytewise.rs b/library/core/src/cmp/bytewise.rs deleted file mode 100644 index a06a5227fe285..0000000000000 --- a/library/core/src/cmp/bytewise.rs +++ /dev/null @@ -1,82 +0,0 @@ -use crate::num::NonZero; - -/// Types where `==` & `!=` are equivalent to comparing their underlying bytes. -/// -/// Importantly, this means no floating-point types, as those have different -/// byte representations (like `-0` and `+0`) which compare as the same. -/// Since byte arrays are `Eq`, that implies that these types are probably also -/// `Eq`, but that's not technically required to use this trait. -/// -/// `Rhs` is *de facto* always `Self`, but the separate parameter is important -/// to avoid the `specializing impl repeats parameter` error when consuming this. -/// -/// # Safety -/// -/// - `Self` and `Rhs` have no padding. -/// - `Self` and `Rhs` have the same layout (size and alignment). -/// - Neither `Self` nor `Rhs` have provenance, so integer comparisons are correct. -/// - `>::{eq,ne}` are equivalent to comparing the bytes. -#[rustc_specialization_trait] -pub(crate) unsafe trait BytewiseEq: PartialEq + Sized {} - -macro_rules! is_bytewise_comparable { - ($($t:ty),+ $(,)?) => {$( - unsafe impl BytewiseEq for $t {} - )+}; -} - -// SAFETY: All the ordinary integer types have no padding, and are not pointers. -is_bytewise_comparable!(u8, u16, u32, u64, u128, usize, i8, i16, i32, i64, i128, isize); - -// SAFETY: These have *niches*, but no *padding* and no *provenance*, -// so we can compare them directly. -is_bytewise_comparable!(bool, char, super::Ordering); - -// SAFETY: Similarly, the `NonZero` type has a niche, but no undef and no pointers, -// and they compare like their underlying numeric type. -is_bytewise_comparable!( - NonZero, - NonZero, - NonZero, - NonZero, - NonZero, - NonZero, - NonZero, - NonZero, - NonZero, - NonZero, - NonZero, - NonZero, -); - -// SAFETY: The `NonZero` type has the "null" optimization guaranteed, and thus -// are also safe to equality-compare bitwise inside an `Option`. -// The way `PartialOrd` is defined for `Option` means that this wouldn't work -// for `<` or `>` on the signed types, but since we only do `==` it's fine. -is_bytewise_comparable!( - Option>, - Option>, - Option>, - Option>, - Option>, - Option>, - Option>, - Option>, - Option>, - Option>, - Option>, - Option>, -); - -macro_rules! is_bytewise_comparable_array_length { - ($($n:literal),+ $(,)?) => {$( - // SAFETY: Arrays have no padding between elements, so if the elements are - // `BytewiseEq`, then the whole array can be too. - unsafe impl, U> BytewiseEq<[U; $n]> for [T; $n] {} - )+}; -} - -// Frustratingly, this can't be made const-generic as it gets -// error: specializing impl repeats parameter `N` -// so just do it for a couple of plausibly-common ones. -is_bytewise_comparable_array_length!(0, 1, 2, 3, 4, 6, 8, 12, 16, 24, 32, 48, 64); diff --git a/library/core/src/convert/mod.rs b/library/core/src/convert/mod.rs deleted file mode 100644 index 432e55e8c9a4c..0000000000000 --- a/library/core/src/convert/mod.rs +++ /dev/null @@ -1,971 +0,0 @@ -//! Traits for conversions between types. -//! -//! The traits in this module provide a way to convert from one type to another type. -//! Each trait serves a different purpose: -//! -//! - Implement the [`AsRef`] trait for cheap reference-to-reference conversions -//! - Implement the [`AsMut`] trait for cheap mutable-to-mutable conversions -//! - Implement the [`From`] trait for consuming value-to-value conversions -//! - Implement the [`Into`] trait for consuming value-to-value conversions to types -//! outside the current crate -//! - The [`TryFrom`] and [`TryInto`] traits behave like [`From`] and [`Into`], -//! but should be implemented when the conversion can fail. -//! -//! The traits in this module are often used as trait bounds for generic functions such that to -//! arguments of multiple types are supported. See the documentation of each trait for examples. -//! -//! As a library author, you should always prefer implementing [`From`][`From`] or -//! [`TryFrom`][`TryFrom`] rather than [`Into`][`Into`] or [`TryInto`][`TryInto`], -//! as [`From`] and [`TryFrom`] provide greater flexibility and offer -//! equivalent [`Into`] or [`TryInto`] implementations for free, thanks to a -//! blanket implementation in the standard library. When targeting a version prior to Rust 1.41, it -//! may be necessary to implement [`Into`] or [`TryInto`] directly when converting to a type -//! outside the current crate. -//! -//! # Generic Implementations -//! -//! - [`AsRef`] and [`AsMut`] auto-dereference if the inner type is a reference -//! (but not generally for all [dereferenceable types][core::ops::Deref]) -//! - [`From`]` for T` implies [`Into`]` for U` -//! - [`TryFrom`]` for T` implies [`TryInto`]` for U` -//! - [`From`] and [`Into`] are reflexive, which means that all types can -//! `into` themselves and `from` themselves -//! -//! See each trait for usage examples. - -#![stable(feature = "rust1", since = "1.0.0")] - -use crate::error::Error; -use crate::fmt; -use crate::hash::{Hash, Hasher}; - -mod num; - -#[unstable(feature = "convert_float_to_int", issue = "67057")] -pub use num::FloatToInt; - -/// The identity function. -/// -/// Two things are important to note about this function: -/// -/// - It is not always equivalent to a closure like `|x| x`, since the -/// closure may coerce `x` into a different type. -/// -/// - It moves the input `x` passed to the function. -/// -/// While it might seem strange to have a function that just returns back the -/// input, there are some interesting uses. -/// -/// # Examples -/// -/// Using `identity` to do nothing in a sequence of other, interesting, -/// functions: -/// -/// ```rust -/// use std::convert::identity; -/// -/// fn manipulation(x: u32) -> u32 { -/// // Let's pretend that adding one is an interesting function. -/// x + 1 -/// } -/// -/// let _arr = &[identity, manipulation]; -/// ``` -/// -/// Using `identity` as a "do nothing" base case in a conditional: -/// -/// ```rust -/// use std::convert::identity; -/// -/// # let condition = true; -/// # -/// # fn manipulation(x: u32) -> u32 { x + 1 } -/// # -/// let do_stuff = if condition { manipulation } else { identity }; -/// -/// // Do more interesting stuff... -/// -/// let _results = do_stuff(42); -/// ``` -/// -/// Using `identity` to keep the `Some` variants of an iterator of `Option`: -/// -/// ```rust -/// use std::convert::identity; -/// -/// let iter = [Some(1), None, Some(3)].into_iter(); -/// let filtered = iter.filter_map(identity).collect::>(); -/// assert_eq!(vec![1, 3], filtered); -/// ``` -#[stable(feature = "convert_id", since = "1.33.0")] -#[rustc_const_stable(feature = "const_identity", since = "1.33.0")] -#[inline(always)] -#[rustc_diagnostic_item = "convert_identity"] -pub const fn identity(x: T) -> T { - x -} - -/// Used to do a cheap reference-to-reference conversion. -/// -/// This trait is similar to [`AsMut`] which is used for converting between mutable references. -/// If you need to do a costly conversion it is better to implement [`From`] with type -/// `&T` or write a custom function. -/// -/// # Relation to `Borrow` -/// -/// `AsRef` has the same signature as [`Borrow`], but [`Borrow`] is different in a few aspects: -/// -/// - Unlike `AsRef`, [`Borrow`] has a blanket impl for any `T`, and can be used to accept either -/// a reference or a value. (See also note on `AsRef`'s reflexibility below.) -/// - [`Borrow`] also requires that [`Hash`], [`Eq`] and [`Ord`] for a borrowed value are -/// equivalent to those of the owned value. For this reason, if you want to -/// borrow only a single field of a struct you can implement `AsRef`, but not [`Borrow`]. -/// -/// **Note: This trait must not fail**. If the conversion can fail, use a -/// dedicated method which returns an [`Option`] or a [`Result`]. -/// -/// # Generic Implementations -/// -/// `AsRef` auto-dereferences if the inner type is a reference or a mutable reference -/// (e.g.: `foo.as_ref()` will work the same if `foo` has type `&mut Foo` or `&&mut Foo`). -/// -/// Note that due to historic reasons, the above currently does not hold generally for all -/// [dereferenceable types], e.g. `foo.as_ref()` will *not* work the same as -/// `Box::new(foo).as_ref()`. Instead, many smart pointers provide an `as_ref` implementation which -/// simply returns a reference to the [pointed-to value] (but do not perform a cheap -/// reference-to-reference conversion for that value). However, [`AsRef::as_ref`] should not be -/// used for the sole purpose of dereferencing; instead ['`Deref` coercion'] can be used: -/// -/// [dereferenceable types]: core::ops::Deref -/// [pointed-to value]: core::ops::Deref::Target -/// ['`Deref` coercion']: core::ops::Deref#deref-coercion -/// -/// ``` -/// let x = Box::new(5i32); -/// // Avoid this: -/// // let y: &i32 = x.as_ref(); -/// // Better just write: -/// let y: &i32 = &x; -/// ``` -/// -/// Types which implement [`Deref`] should consider implementing `AsRef` as follows: -/// -/// [`Deref`]: core::ops::Deref -/// -/// ``` -/// # use core::ops::Deref; -/// # struct SomeType; -/// # impl Deref for SomeType { -/// # type Target = [u8]; -/// # fn deref(&self) -> &[u8] { -/// # &[] -/// # } -/// # } -/// impl AsRef for SomeType -/// where -/// T: ?Sized, -/// ::Target: AsRef, -/// { -/// fn as_ref(&self) -> &T { -/// self.deref().as_ref() -/// } -/// } -/// ``` -/// -/// # Reflexivity -/// -/// Ideally, `AsRef` would be reflexive, i.e. there would be an `impl AsRef for T` -/// with [`as_ref`] simply returning its argument unchanged. -/// Such a blanket implementation is currently *not* provided due to technical restrictions of -/// Rust's type system (it would be overlapping with another existing blanket implementation for -/// `&T where T: AsRef` which allows `AsRef` to auto-dereference, see "Generic Implementations" -/// above). -/// -/// [`as_ref`]: AsRef::as_ref -/// -/// A trivial implementation of `AsRef for T` must be added explicitly for a particular type `T` -/// where needed or desired. Note, however, that not all types from `std` contain such an -/// implementation, and those cannot be added by external code due to orphan rules. -/// -/// # Examples -/// -/// By using trait bounds we can accept arguments of different types as long as they can be -/// converted to the specified type `T`. -/// -/// For example: By creating a generic function that takes an `AsRef` we express that we -/// want to accept all references that can be converted to [`&str`] as an argument. -/// Since both [`String`] and [`&str`] implement `AsRef` we can accept both as input argument. -/// -/// [`&str`]: primitive@str -/// [`Borrow`]: crate::borrow::Borrow -/// [`Eq`]: crate::cmp::Eq -/// [`Ord`]: crate::cmp::Ord -/// [`String`]: ../../std/string/struct.String.html -/// -/// ``` -/// fn is_hello>(s: T) { -/// assert_eq!("hello", s.as_ref()); -/// } -/// -/// let s = "hello"; -/// is_hello(s); -/// -/// let s = "hello".to_string(); -/// is_hello(s); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "AsRef")] -pub trait AsRef { - /// Converts this type into a shared reference of the (usually inferred) input type. - #[stable(feature = "rust1", since = "1.0.0")] - fn as_ref(&self) -> &T; -} - -/// Used to do a cheap mutable-to-mutable reference conversion. -/// -/// This trait is similar to [`AsRef`] but used for converting between mutable -/// references. If you need to do a costly conversion it is better to -/// implement [`From`] with type `&mut T` or write a custom function. -/// -/// **Note: This trait must not fail**. If the conversion can fail, use a -/// dedicated method which returns an [`Option`] or a [`Result`]. -/// -/// # Generic Implementations -/// -/// `AsMut` auto-dereferences if the inner type is a mutable reference -/// (e.g.: `foo.as_mut()` will work the same if `foo` has type `&mut Foo` or `&mut &mut Foo`). -/// -/// Note that due to historic reasons, the above currently does not hold generally for all -/// [mutably dereferenceable types], e.g. `foo.as_mut()` will *not* work the same as -/// `Box::new(foo).as_mut()`. Instead, many smart pointers provide an `as_mut` implementation which -/// simply returns a reference to the [pointed-to value] (but do not perform a cheap -/// reference-to-reference conversion for that value). However, [`AsMut::as_mut`] should not be -/// used for the sole purpose of mutable dereferencing; instead ['`Deref` coercion'] can be used: -/// -/// [mutably dereferenceable types]: core::ops::DerefMut -/// [pointed-to value]: core::ops::Deref::Target -/// ['`Deref` coercion']: core::ops::DerefMut#mutable-deref-coercion -/// -/// ``` -/// let mut x = Box::new(5i32); -/// // Avoid this: -/// // let y: &mut i32 = x.as_mut(); -/// // Better just write: -/// let y: &mut i32 = &mut x; -/// ``` -/// -/// Types which implement [`DerefMut`] should consider to add an implementation of `AsMut` as -/// follows: -/// -/// [`DerefMut`]: core::ops::DerefMut -/// -/// ``` -/// # use core::ops::{Deref, DerefMut}; -/// # struct SomeType; -/// # impl Deref for SomeType { -/// # type Target = [u8]; -/// # fn deref(&self) -> &[u8] { -/// # &[] -/// # } -/// # } -/// # impl DerefMut for SomeType { -/// # fn deref_mut(&mut self) -> &mut [u8] { -/// # &mut [] -/// # } -/// # } -/// impl AsMut for SomeType -/// where -/// ::Target: AsMut, -/// { -/// fn as_mut(&mut self) -> &mut T { -/// self.deref_mut().as_mut() -/// } -/// } -/// ``` -/// -/// # Reflexivity -/// -/// Ideally, `AsMut` would be reflexive, i.e. there would be an `impl AsMut for T` -/// with [`as_mut`] simply returning its argument unchanged. -/// Such a blanket implementation is currently *not* provided due to technical restrictions of -/// Rust's type system (it would be overlapping with another existing blanket implementation for -/// `&mut T where T: AsMut` which allows `AsMut` to auto-dereference, see "Generic -/// Implementations" above). -/// -/// [`as_mut`]: AsMut::as_mut -/// -/// A trivial implementation of `AsMut for T` must be added explicitly for a particular type `T` -/// where needed or desired. Note, however, that not all types from `std` contain such an -/// implementation, and those cannot be added by external code due to orphan rules. -/// -/// # Examples -/// -/// Using `AsMut` as trait bound for a generic function, we can accept all mutable references that -/// can be converted to type `&mut T`. Unlike [dereference], which has a single [target type], -/// there can be multiple implementations of `AsMut` for a type. In particular, `Vec` implements -/// both `AsMut>` and `AsMut<[T]>`. -/// -/// In the following, the example functions `caesar` and `null_terminate` provide a generic -/// interface which work with any type that can be converted by cheap mutable-to-mutable conversion -/// into a byte slice (`[u8]`) or byte vector (`Vec`), respectively. -/// -/// [dereference]: core::ops::DerefMut -/// [target type]: core::ops::Deref::Target -/// -/// ``` -/// struct Document { -/// info: String, -/// content: Vec, -/// } -/// -/// impl AsMut for Document -/// where -/// Vec: AsMut, -/// { -/// fn as_mut(&mut self) -> &mut T { -/// self.content.as_mut() -/// } -/// } -/// -/// fn caesar>(data: &mut T, key: u8) { -/// for byte in data.as_mut() { -/// *byte = byte.wrapping_add(key); -/// } -/// } -/// -/// fn null_terminate>>(data: &mut T) { -/// // Using a non-generic inner function, which contains most of the -/// // functionality, helps to minimize monomorphization overhead. -/// fn doit(data: &mut Vec) { -/// let len = data.len(); -/// if len == 0 || data[len-1] != 0 { -/// data.push(0); -/// } -/// } -/// doit(data.as_mut()); -/// } -/// -/// fn main() { -/// let mut v: Vec = vec![1, 2, 3]; -/// caesar(&mut v, 5); -/// assert_eq!(v, [6, 7, 8]); -/// null_terminate(&mut v); -/// assert_eq!(v, [6, 7, 8, 0]); -/// let mut doc = Document { -/// info: String::from("Example"), -/// content: vec![17, 19, 8], -/// }; -/// caesar(&mut doc, 1); -/// assert_eq!(doc.content, [18, 20, 9]); -/// null_terminate(&mut doc); -/// assert_eq!(doc.content, [18, 20, 9, 0]); -/// } -/// ``` -/// -/// Note, however, that APIs don't need to be generic. In many cases taking a `&mut [u8]` or -/// `&mut Vec`, for example, is the better choice (callers need to pass the correct type then). -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "AsMut")] -pub trait AsMut { - /// Converts this type into a mutable reference of the (usually inferred) input type. - #[stable(feature = "rust1", since = "1.0.0")] - fn as_mut(&mut self) -> &mut T; -} - -/// A value-to-value conversion that consumes the input value. The -/// opposite of [`From`]. -/// -/// One should avoid implementing [`Into`] and implement [`From`] instead. -/// Implementing [`From`] automatically provides one with an implementation of [`Into`] -/// thanks to the blanket implementation in the standard library. -/// -/// Prefer using [`Into`] over [`From`] when specifying trait bounds on a generic function -/// to ensure that types that only implement [`Into`] can be used as well. -/// -/// **Note: This trait must not fail**. If the conversion can fail, use [`TryInto`]. -/// -/// # Generic Implementations -/// -/// - [`From`]` for U` implies `Into for T` -/// - [`Into`] is reflexive, which means that `Into for T` is implemented -/// -/// # Implementing [`Into`] for conversions to external types in old versions of Rust -/// -/// Prior to Rust 1.41, if the destination type was not part of the current crate -/// then you couldn't implement [`From`] directly. -/// For example, take this code: -/// -/// ``` -/// # #![allow(non_local_definitions)] -/// struct Wrapper(Vec); -/// impl From> for Vec { -/// fn from(w: Wrapper) -> Vec { -/// w.0 -/// } -/// } -/// ``` -/// This will fail to compile in older versions of the language because Rust's orphaning rules -/// used to be a little bit more strict. To bypass this, you could implement [`Into`] directly: -/// -/// ``` -/// struct Wrapper(Vec); -/// impl Into> for Wrapper { -/// fn into(self) -> Vec { -/// self.0 -/// } -/// } -/// ``` -/// -/// It is important to understand that [`Into`] does not provide a [`From`] implementation -/// (as [`From`] does with [`Into`]). Therefore, you should always try to implement [`From`] -/// and then fall back to [`Into`] if [`From`] can't be implemented. -/// -/// # Examples -/// -/// [`String`] implements [`Into`]`<`[`Vec`]`<`[`u8`]`>>`: -/// -/// In order to express that we want a generic function to take all arguments that can be -/// converted to a specified type `T`, we can use a trait bound of [`Into`]``. -/// For example: The function `is_hello` takes all arguments that can be converted into a -/// [`Vec`]`<`[`u8`]`>`. -/// -/// ``` -/// fn is_hello>>(s: T) { -/// let bytes = b"hello".to_vec(); -/// assert_eq!(bytes, s.into()); -/// } -/// -/// let s = "hello".to_string(); -/// is_hello(s); -/// ``` -/// -/// [`String`]: ../../std/string/struct.String.html -/// [`Vec`]: ../../std/vec/struct.Vec.html -#[rustc_diagnostic_item = "Into"] -#[stable(feature = "rust1", since = "1.0.0")] -pub trait Into: Sized { - /// Converts this type into the (usually inferred) input type. - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - fn into(self) -> T; -} - -/// Used to do value-to-value conversions while consuming the input value. It is the reciprocal of -/// [`Into`]. -/// -/// One should always prefer implementing `From` over [`Into`] -/// because implementing `From` automatically provides one with an implementation of [`Into`] -/// thanks to the blanket implementation in the standard library. -/// -/// Only implement [`Into`] when targeting a version prior to Rust 1.41 and converting to a type -/// outside the current crate. -/// `From` was not able to do these types of conversions in earlier versions because of Rust's -/// orphaning rules. -/// See [`Into`] for more details. -/// -/// Prefer using [`Into`] over using `From` when specifying trait bounds on a generic function. -/// This way, types that directly implement [`Into`] can be used as arguments as well. -/// -/// The `From` trait is also very useful when performing error handling. When constructing a function -/// that is capable of failing, the return type will generally be of the form `Result`. -/// `From` simplifies error handling by allowing a function to return a single error type -/// that encapsulates multiple error types. See the "Examples" section and [the book][book] for more -/// details. -/// -/// **Note: This trait must not fail**. The `From` trait is intended for perfect conversions. -/// If the conversion can fail or is not perfect, use [`TryFrom`]. -/// -/// # Generic Implementations -/// -/// - `From for U` implies [`Into`]` for T` -/// - `From` is reflexive, which means that `From for T` is implemented -/// -/// # When to implement `From` -/// -/// While there's no technical restrictions on which conversions can be done using -/// a `From` implementation, the general expectation is that the conversions -/// should typically be restricted as follows: -/// -/// * The conversion is *infallible*: if the conversion can fail, use [`TryFrom`] -/// instead; don't provide a `From` impl that panics. -/// -/// * The conversion is *lossless*: semantically, it should not lose or discard -/// information. For example, `i32: From` exists, where the original -/// value can be recovered using `u16: TryFrom`. And `String: From<&str>` -/// exists, where you can get something equivalent to the original value via -/// `Deref`. But `From` cannot be used to convert from `u32` to `u16`, since -/// that cannot succeed in a lossless way. (There's some wiggle room here for -/// information not considered semantically relevant. For example, -/// `Box<[T]>: From>` exists even though it might not preserve capacity, -/// like how two vectors can be equal despite differing capacities.) -/// -/// * The conversion is *value-preserving*: the conceptual kind and meaning of -/// the resulting value is the same, even though the Rust type and technical -/// representation might be different. For example `-1_i8 as u8` is *lossless*, -/// since `as` casting back can recover the original value, but that conversion -/// is *not* available via `From` because `-1` and `255` are different conceptual -/// values (despite being identical bit patterns technically). But -/// `f32: From` *is* available because `1_i16` and `1.0_f32` are conceptually -/// the same real number (despite having very different bit patterns technically). -/// `String: From` is available because they're both *text*, but -/// `String: From` is *not* available, since `1` (a number) and `"1"` -/// (text) are too different. (Converting values to text is instead covered -/// by the [`Display`](crate::fmt::Display) trait.) -/// -/// * The conversion is *obvious*: it's the only reasonable conversion between -/// the two types. Otherwise it's better to have it be a named method or -/// constructor, like how [`str::as_bytes`] is a method and how integers have -/// methods like [`u32::from_ne_bytes`], [`u32::from_le_bytes`], and -/// [`u32::from_be_bytes`], none of which are `From` implementations. Whereas -/// there's only one reasonable way to wrap an [`Ipv6Addr`](crate::net::Ipv6Addr) -/// into an [`IpAddr`](crate::net::IpAddr), thus `IpAddr: From` exists. -/// -/// # Examples -/// -/// [`String`] implements `From<&str>`: -/// -/// An explicit conversion from a `&str` to a String is done as follows: -/// -/// ``` -/// let string = "hello".to_string(); -/// let other_string = String::from("hello"); -/// -/// assert_eq!(string, other_string); -/// ``` -/// -/// While performing error handling it is often useful to implement `From` for your own error type. -/// By converting underlying error types to our own custom error type that encapsulates the -/// underlying error type, we can return a single error type without losing information on the -/// underlying cause. The '?' operator automatically converts the underlying error type to our -/// custom error type with `From::from`. -/// -/// ``` -/// use std::fs; -/// use std::io; -/// use std::num; -/// -/// enum CliError { -/// IoError(io::Error), -/// ParseError(num::ParseIntError), -/// } -/// -/// impl From for CliError { -/// fn from(error: io::Error) -> Self { -/// CliError::IoError(error) -/// } -/// } -/// -/// impl From for CliError { -/// fn from(error: num::ParseIntError) -> Self { -/// CliError::ParseError(error) -/// } -/// } -/// -/// fn open_and_parse_file(file_name: &str) -> Result { -/// let mut contents = fs::read_to_string(&file_name)?; -/// let num: i32 = contents.trim().parse()?; -/// Ok(num) -/// } -/// ``` -/// -/// [`String`]: ../../std/string/struct.String.html -/// [`from`]: From::from -/// [book]: ../../book/ch09-00-error-handling.html -#[rustc_diagnostic_item = "From"] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_on_unimplemented(on( - all(_Self = "&str", T = "alloc::string::String"), - note = "to coerce a `{T}` into a `{Self}`, use `&*` as a prefix", -))] -pub trait From: Sized { - /// Converts to this type from the input type. - #[rustc_diagnostic_item = "from_fn"] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - fn from(value: T) -> Self; -} - -/// An attempted conversion that consumes `self`, which may or may not be -/// expensive. -/// -/// Library authors should usually not directly implement this trait, -/// but should prefer implementing the [`TryFrom`] trait, which offers -/// greater flexibility and provides an equivalent `TryInto` -/// implementation for free, thanks to a blanket implementation in the -/// standard library. For more information on this, see the -/// documentation for [`Into`]. -/// -/// # Implementing `TryInto` -/// -/// This suffers the same restrictions and reasoning as implementing -/// [`Into`], see there for details. -#[rustc_diagnostic_item = "TryInto"] -#[stable(feature = "try_from", since = "1.34.0")] -pub trait TryInto: Sized { - /// The type returned in the event of a conversion error. - #[stable(feature = "try_from", since = "1.34.0")] - type Error; - - /// Performs the conversion. - #[stable(feature = "try_from", since = "1.34.0")] - fn try_into(self) -> Result; -} - -/// Simple and safe type conversions that may fail in a controlled -/// way under some circumstances. It is the reciprocal of [`TryInto`]. -/// -/// This is useful when you are doing a type conversion that may -/// trivially succeed but may also need special handling. -/// For example, there is no way to convert an [`i64`] into an [`i32`] -/// using the [`From`] trait, because an [`i64`] may contain a value -/// that an [`i32`] cannot represent and so the conversion would lose data. -/// This might be handled by truncating the [`i64`] to an [`i32`] or by -/// simply returning [`i32::MAX`], or by some other method. The [`From`] -/// trait is intended for perfect conversions, so the `TryFrom` trait -/// informs the programmer when a type conversion could go bad and lets -/// them decide how to handle it. -/// -/// # Generic Implementations -/// -/// - `TryFrom for U` implies [`TryInto`]` for T` -/// - [`try_from`] is reflexive, which means that `TryFrom for T` -/// is implemented and cannot fail -- the associated `Error` type for -/// calling `T::try_from()` on a value of type `T` is [`Infallible`]. -/// When the [`!`] type is stabilized [`Infallible`] and [`!`] will be -/// equivalent. -/// -/// `TryFrom` can be implemented as follows: -/// -/// ``` -/// struct GreaterThanZero(i32); -/// -/// impl TryFrom for GreaterThanZero { -/// type Error = &'static str; -/// -/// fn try_from(value: i32) -> Result { -/// if value <= 0 { -/// Err("GreaterThanZero only accepts values greater than zero!") -/// } else { -/// Ok(GreaterThanZero(value)) -/// } -/// } -/// } -/// ``` -/// -/// # Examples -/// -/// As described, [`i32`] implements `TryFrom<`[`i64`]`>`: -/// -/// ``` -/// let big_number = 1_000_000_000_000i64; -/// // Silently truncates `big_number`, requires detecting -/// // and handling the truncation after the fact. -/// let smaller_number = big_number as i32; -/// assert_eq!(smaller_number, -727379968); -/// -/// // Returns an error because `big_number` is too big to -/// // fit in an `i32`. -/// let try_smaller_number = i32::try_from(big_number); -/// assert!(try_smaller_number.is_err()); -/// -/// // Returns `Ok(3)`. -/// let try_successful_smaller_number = i32::try_from(3); -/// assert!(try_successful_smaller_number.is_ok()); -/// ``` -/// -/// [`try_from`]: TryFrom::try_from -#[rustc_diagnostic_item = "TryFrom"] -#[stable(feature = "try_from", since = "1.34.0")] -pub trait TryFrom: Sized { - /// The type returned in the event of a conversion error. - #[stable(feature = "try_from", since = "1.34.0")] - type Error; - - /// Performs the conversion. - #[stable(feature = "try_from", since = "1.34.0")] - #[rustc_diagnostic_item = "try_from_fn"] - fn try_from(value: T) -> Result; -} - -//////////////////////////////////////////////////////////////////////////////// -// GENERIC IMPLS -//////////////////////////////////////////////////////////////////////////////// - -// As lifts over & -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef for &T -where - T: AsRef, -{ - #[inline] - fn as_ref(&self) -> &U { - >::as_ref(*self) - } -} - -// As lifts over &mut -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef for &mut T -where - T: AsRef, -{ - #[inline] - fn as_ref(&self) -> &U { - >::as_ref(*self) - } -} - -// FIXME (#45742): replace the above impls for &/&mut with the following more general one: -// // As lifts over Deref -// impl>, U: ?Sized> AsRef for D { -// fn as_ref(&self) -> &U { -// self.deref().as_ref() -// } -// } - -// AsMut lifts over &mut -#[stable(feature = "rust1", since = "1.0.0")] -impl AsMut for &mut T -where - T: AsMut, -{ - #[inline] - fn as_mut(&mut self) -> &mut U { - (*self).as_mut() - } -} - -// FIXME (#45742): replace the above impl for &mut with the following more general one: -// // AsMut lifts over DerefMut -// impl>, U: ?Sized> AsMut for D { -// fn as_mut(&mut self) -> &mut U { -// self.deref_mut().as_mut() -// } -// } - -// From implies Into -#[stable(feature = "rust1", since = "1.0.0")] -impl Into for T -where - U: From, -{ - /// Calls `U::from(self)`. - /// - /// That is, this conversion is whatever the implementation of - /// [From]<T> for U chooses to do. - #[inline] - #[track_caller] - fn into(self) -> U { - U::from(self) - } -} - -// From (and thus Into) is reflexive -#[stable(feature = "rust1", since = "1.0.0")] -impl From for T { - /// Returns the argument unchanged. - #[inline(always)] - fn from(t: T) -> T { - t - } -} - -/// **Stability note:** This impl does not yet exist, but we are -/// "reserving space" to add it in the future. See -/// [rust-lang/rust#64715][#64715] for details. -/// -/// [#64715]: https://github.com/rust-lang/rust/issues/64715 -#[stable(feature = "convert_infallible", since = "1.34.0")] -#[allow(unused_attributes)] // FIXME(#58633): do a principled fix instead. -#[rustc_reservation_impl = "permitting this impl would forbid us from adding \ - `impl From for T` later; see rust-lang/rust#64715 for details"] -impl From for T { - fn from(t: !) -> T { - t - } -} - -// TryFrom implies TryInto -#[stable(feature = "try_from", since = "1.34.0")] -impl TryInto for T -where - U: TryFrom, -{ - type Error = U::Error; - - #[inline] - fn try_into(self) -> Result { - U::try_from(self) - } -} - -// Infallible conversions are semantically equivalent to fallible conversions -// with an uninhabited error type. -#[stable(feature = "try_from", since = "1.34.0")] -impl TryFrom for T -where - U: Into, -{ - type Error = Infallible; - - #[inline] - fn try_from(value: U) -> Result { - Ok(U::into(value)) - } -} - -//////////////////////////////////////////////////////////////////////////////// -// CONCRETE IMPLS -//////////////////////////////////////////////////////////////////////////////// - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef<[T]> for [T] { - #[inline(always)] - fn as_ref(&self) -> &[T] { - self - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsMut<[T]> for [T] { - #[inline(always)] - fn as_mut(&mut self) -> &mut [T] { - self - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef for str { - #[inline(always)] - fn as_ref(&self) -> &str { - self - } -} - -#[stable(feature = "as_mut_str_for_str", since = "1.51.0")] -impl AsMut for str { - #[inline(always)] - fn as_mut(&mut self) -> &mut str { - self - } -} - -//////////////////////////////////////////////////////////////////////////////// -// THE NO-ERROR ERROR TYPE -//////////////////////////////////////////////////////////////////////////////// - -/// The error type for errors that can never happen. -/// -/// Since this enum has no variant, a value of this type can never actually exist. -/// This can be useful for generic APIs that use [`Result`] and parameterize the error type, -/// to indicate that the result is always [`Ok`]. -/// -/// For example, the [`TryFrom`] trait (conversion that returns a [`Result`]) -/// has a blanket implementation for all types where a reverse [`Into`] implementation exists. -/// -/// ```ignore (illustrates std code, duplicating the impl in a doctest would be an error) -/// impl TryFrom for T where U: Into { -/// type Error = Infallible; -/// -/// fn try_from(value: U) -> Result { -/// Ok(U::into(value)) // Never returns `Err` -/// } -/// } -/// ``` -/// -/// # Future compatibility -/// -/// This enum has the same role as [the `!` “never” type][never], -/// which is unstable in this version of Rust. -/// When `!` is stabilized, we plan to make `Infallible` a type alias to it: -/// -/// ```ignore (illustrates future std change) -/// pub type Infallible = !; -/// ``` -/// -/// … and eventually deprecate `Infallible`. -/// -/// However there is one case where `!` syntax can be used -/// before `!` is stabilized as a full-fledged type: in the position of a function’s return type. -/// Specifically, it is possible to have implementations for two different function pointer types: -/// -/// ``` -/// trait MyTrait {} -/// impl MyTrait for fn() -> ! {} -/// impl MyTrait for fn() -> std::convert::Infallible {} -/// ``` -/// -/// With `Infallible` being an enum, this code is valid. -/// However when `Infallible` becomes an alias for the never type, -/// the two `impl`s will start to overlap -/// and therefore will be disallowed by the language’s trait coherence rules. -#[stable(feature = "convert_infallible", since = "1.34.0")] -#[derive(Copy)] -pub enum Infallible {} - -#[stable(feature = "convert_infallible", since = "1.34.0")] -impl Clone for Infallible { - fn clone(&self) -> Infallible { - match *self {} - } -} - -#[stable(feature = "convert_infallible", since = "1.34.0")] -impl fmt::Debug for Infallible { - fn fmt(&self, _: &mut fmt::Formatter<'_>) -> fmt::Result { - match *self {} - } -} - -#[stable(feature = "convert_infallible", since = "1.34.0")] -impl fmt::Display for Infallible { - fn fmt(&self, _: &mut fmt::Formatter<'_>) -> fmt::Result { - match *self {} - } -} - -#[stable(feature = "str_parse_error2", since = "1.8.0")] -impl Error for Infallible { - fn description(&self) -> &str { - match *self {} - } -} - -#[stable(feature = "convert_infallible", since = "1.34.0")] -impl PartialEq for Infallible { - fn eq(&self, _: &Infallible) -> bool { - match *self {} - } -} - -#[stable(feature = "convert_infallible", since = "1.34.0")] -impl Eq for Infallible {} - -#[stable(feature = "convert_infallible", since = "1.34.0")] -impl PartialOrd for Infallible { - fn partial_cmp(&self, _other: &Self) -> Option { - match *self {} - } -} - -#[stable(feature = "convert_infallible", since = "1.34.0")] -impl Ord for Infallible { - fn cmp(&self, _other: &Self) -> crate::cmp::Ordering { - match *self {} - } -} - -#[stable(feature = "convert_infallible", since = "1.34.0")] -impl From for Infallible { - #[inline] - fn from(x: !) -> Self { - x - } -} - -#[stable(feature = "convert_infallible_hash", since = "1.44.0")] -impl Hash for Infallible { - fn hash(&self, _: &mut H) { - match *self {} - } -} diff --git a/library/core/src/convert/num.rs b/library/core/src/convert/num.rs deleted file mode 100644 index 86c4ea9fab088..0000000000000 --- a/library/core/src/convert/num.rs +++ /dev/null @@ -1,542 +0,0 @@ -use crate::num::TryFromIntError; - -mod private { - /// This trait being unreachable from outside the crate - /// prevents other implementations of the `FloatToInt` trait, - /// which allows potentially adding more trait methods after the trait is `#[stable]`. - #[unstable(feature = "convert_float_to_int", issue = "67057")] - pub trait Sealed {} -} - -/// Supporting trait for inherent methods of `f32` and `f64` such as `to_int_unchecked`. -/// Typically doesn’t need to be used directly. -#[unstable(feature = "convert_float_to_int", issue = "67057")] -pub trait FloatToInt: private::Sealed + Sized { - #[unstable(feature = "convert_float_to_int", issue = "67057")] - #[doc(hidden)] - unsafe fn to_int_unchecked(self) -> Int; -} - -macro_rules! impl_float_to_int { - ($Float:ty => $($Int:ty),+) => { - #[unstable(feature = "convert_float_to_int", issue = "67057")] - impl private::Sealed for $Float {} - $( - #[unstable(feature = "convert_float_to_int", issue = "67057")] - impl FloatToInt<$Int> for $Float { - #[inline] - unsafe fn to_int_unchecked(self) -> $Int { - // SAFETY: the safety contract must be upheld by the caller. - unsafe { crate::intrinsics::float_to_int_unchecked(self) } - } - } - )+ - } -} - -impl_float_to_int!(f16 => u8, u16, u32, u64, u128, usize, i8, i16, i32, i64, i128, isize); -impl_float_to_int!(f32 => u8, u16, u32, u64, u128, usize, i8, i16, i32, i64, i128, isize); -impl_float_to_int!(f64 => u8, u16, u32, u64, u128, usize, i8, i16, i32, i64, i128, isize); -impl_float_to_int!(f128 => u8, u16, u32, u64, u128, usize, i8, i16, i32, i64, i128, isize); - -// Conversion traits for primitive integer and float types -// Conversions T -> T are covered by a blanket impl and therefore excluded -// Some conversions from and to usize/isize are not implemented due to portability concerns -macro_rules! impl_from { - (bool => $Int:ty $(,)?) => { - impl_from!( - bool => $Int, - #[stable(feature = "from_bool", since = "1.28.0")], - concat!( - "Converts a [`bool`] to [`", stringify!($Int), "`] losslessly.\n", - "The resulting value is `0` for `false` and `1` for `true` values.\n", - "\n", - "# Examples\n", - "\n", - "```\n", - "assert_eq!(", stringify!($Int), "::from(true), 1);\n", - "assert_eq!(", stringify!($Int), "::from(false), 0);\n", - "```\n", - ), - ); - }; - ($Small:ty => $Large:ty, #[$attr:meta] $(,)?) => { - impl_from!( - $Small => $Large, - #[$attr], - concat!("Converts [`", stringify!($Small), "`] to [`", stringify!($Large), "`] losslessly."), - ); - }; - ($Small:ty => $Large:ty, #[$attr:meta], $doc:expr $(,)?) => { - #[$attr] - impl From<$Small> for $Large { - // Rustdocs on the impl block show a "[+] show undocumented items" toggle. - // Rustdocs on functions do not. - #[doc = $doc] - #[inline(always)] - fn from(small: $Small) -> Self { - small as Self - } - } - }; -} - -// boolean -> integer -impl_from!(bool => u8); -impl_from!(bool => u16); -impl_from!(bool => u32); -impl_from!(bool => u64); -impl_from!(bool => u128); -impl_from!(bool => usize); -impl_from!(bool => i8); -impl_from!(bool => i16); -impl_from!(bool => i32); -impl_from!(bool => i64); -impl_from!(bool => i128); -impl_from!(bool => isize); - -// unsigned integer -> unsigned integer -impl_from!(u8 => u16, #[stable(feature = "lossless_int_conv", since = "1.5.0")]); -impl_from!(u8 => u32, #[stable(feature = "lossless_int_conv", since = "1.5.0")]); -impl_from!(u8 => u64, #[stable(feature = "lossless_int_conv", since = "1.5.0")]); -impl_from!(u8 => u128, #[stable(feature = "i128", since = "1.26.0")]); -impl_from!(u8 => usize, #[stable(feature = "lossless_int_conv", since = "1.5.0")]); -impl_from!(u16 => u32, #[stable(feature = "lossless_int_conv", since = "1.5.0")]); -impl_from!(u16 => u64, #[stable(feature = "lossless_int_conv", since = "1.5.0")]); -impl_from!(u16 => u128, #[stable(feature = "i128", since = "1.26.0")]); -impl_from!(u32 => u64, #[stable(feature = "lossless_int_conv", since = "1.5.0")]); -impl_from!(u32 => u128, #[stable(feature = "i128", since = "1.26.0")]); -impl_from!(u64 => u128, #[stable(feature = "i128", since = "1.26.0")]); - -// signed integer -> signed integer -impl_from!(i8 => i16, #[stable(feature = "lossless_int_conv", since = "1.5.0")]); -impl_from!(i8 => i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")]); -impl_from!(i8 => i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")]); -impl_from!(i8 => i128, #[stable(feature = "i128", since = "1.26.0")]); -impl_from!(i8 => isize, #[stable(feature = "lossless_int_conv", since = "1.5.0")]); -impl_from!(i16 => i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")]); -impl_from!(i16 => i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")]); -impl_from!(i16 => i128, #[stable(feature = "i128", since = "1.26.0")]); -impl_from!(i32 => i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")]); -impl_from!(i32 => i128, #[stable(feature = "i128", since = "1.26.0")]); -impl_from!(i64 => i128, #[stable(feature = "i128", since = "1.26.0")]); - -// unsigned integer -> signed integer -impl_from!(u8 => i16, #[stable(feature = "lossless_int_conv", since = "1.5.0")]); -impl_from!(u8 => i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")]); -impl_from!(u8 => i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")]); -impl_from!(u8 => i128, #[stable(feature = "i128", since = "1.26.0")]); -impl_from!(u16 => i32, #[stable(feature = "lossless_int_conv", since = "1.5.0")]); -impl_from!(u16 => i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")]); -impl_from!(u16 => i128, #[stable(feature = "i128", since = "1.26.0")]); -impl_from!(u32 => i64, #[stable(feature = "lossless_int_conv", since = "1.5.0")]); -impl_from!(u32 => i128, #[stable(feature = "i128", since = "1.26.0")]); -impl_from!(u64 => i128, #[stable(feature = "i128", since = "1.26.0")]); - -// The C99 standard defines bounds on INTPTR_MIN, INTPTR_MAX, and UINTPTR_MAX -// which imply that pointer-sized integers must be at least 16 bits: -// https://port70.net/~nsz/c/c99/n1256.html#7.18.2.4 -impl_from!(u16 => usize, #[stable(feature = "lossless_iusize_conv", since = "1.26.0")]); -impl_from!(u8 => isize, #[stable(feature = "lossless_iusize_conv", since = "1.26.0")]); -impl_from!(i16 => isize, #[stable(feature = "lossless_iusize_conv", since = "1.26.0")]); - -// RISC-V defines the possibility of a 128-bit address space (RV128). - -// CHERI proposes 128-bit “capabilities”. Unclear if this would be relevant to usize/isize. -// https://www.cl.cam.ac.uk/research/security/ctsrd/pdfs/20171017a-cheri-poster.pdf -// https://www.cl.cam.ac.uk/techreports/UCAM-CL-TR-951.pdf - -// Note: integers can only be represented with full precision in a float if -// they fit in the significand, which is 24 bits in f32 and 53 bits in f64. -// Lossy float conversions are not implemented at this time. - -// signed integer -> float -impl_from!(i8 => f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")]); -impl_from!(i8 => f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")]); -impl_from!(i16 => f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")]); -impl_from!(i16 => f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")]); -impl_from!(i32 => f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")]); - -// unsigned integer -> float -impl_from!(u8 => f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")]); -impl_from!(u8 => f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")]); -impl_from!(u16 => f32, #[stable(feature = "lossless_float_conv", since = "1.6.0")]); -impl_from!(u16 => f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")]); -impl_from!(u32 => f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")]); - -// float -> float -// FIXME(f16_f128): adding additional `From<{float}>` impls to `f32` breaks inference. See -// -impl_from!(f16 => f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")]); -impl_from!(f16 => f128, #[stable(feature = "lossless_float_conv", since = "1.6.0")]); -impl_from!(f32 => f64, #[stable(feature = "lossless_float_conv", since = "1.6.0")]); -impl_from!(f32 => f128, #[stable(feature = "lossless_float_conv", since = "1.6.0")]); -impl_from!(f64 => f128, #[stable(feature = "lossless_float_conv", since = "1.6.0")]); - -macro_rules! impl_float_from_bool { - ($float:ty) => { - #[stable(feature = "float_from_bool", since = "1.68.0")] - impl From for $float { - #[doc = concat!("Converts a [`bool`] to [`", stringify!($float),"`] losslessly.")] - /// The resulting value is positive `0.0` for `false` and `1.0` for `true` values. - /// - /// # Examples - /// ``` - #[doc = concat!("let x: ", stringify!($float)," = false.into();")] - /// assert_eq!(x, 0.0); - /// assert!(x.is_sign_positive()); - /// - #[doc = concat!("let y: ", stringify!($float)," = true.into();")] - /// assert_eq!(y, 1.0); - /// ``` - #[inline] - fn from(small: bool) -> Self { - small as u8 as Self - } - } - }; -} - -// boolean -> float -impl_float_from_bool!(f32); -impl_float_from_bool!(f64); - -// no possible bounds violation -macro_rules! impl_try_from_unbounded { - ($source:ty => $($target:ty),+) => {$( - #[stable(feature = "try_from", since = "1.34.0")] - impl TryFrom<$source> for $target { - type Error = TryFromIntError; - - /// Try to create the target number type from a source - /// number type. This returns an error if the source value - /// is outside of the range of the target type. - #[inline] - fn try_from(value: $source) -> Result { - Ok(value as Self) - } - } - )*} -} - -// only negative bounds -macro_rules! impl_try_from_lower_bounded { - ($source:ty => $($target:ty),+) => {$( - #[stable(feature = "try_from", since = "1.34.0")] - impl TryFrom<$source> for $target { - type Error = TryFromIntError; - - /// Try to create the target number type from a source - /// number type. This returns an error if the source value - /// is outside of the range of the target type. - #[inline] - fn try_from(u: $source) -> Result { - if u >= 0 { - Ok(u as Self) - } else { - Err(TryFromIntError(())) - } - } - } - )*} -} - -// unsigned to signed (only positive bound) -macro_rules! impl_try_from_upper_bounded { - ($source:ty => $($target:ty),+) => {$( - #[stable(feature = "try_from", since = "1.34.0")] - impl TryFrom<$source> for $target { - type Error = TryFromIntError; - - /// Try to create the target number type from a source - /// number type. This returns an error if the source value - /// is outside of the range of the target type. - #[inline] - fn try_from(u: $source) -> Result { - if u > (Self::MAX as $source) { - Err(TryFromIntError(())) - } else { - Ok(u as Self) - } - } - } - )*} -} - -// all other cases -macro_rules! impl_try_from_both_bounded { - ($source:ty => $($target:ty),+) => {$( - #[stable(feature = "try_from", since = "1.34.0")] - impl TryFrom<$source> for $target { - type Error = TryFromIntError; - - /// Try to create the target number type from a source - /// number type. This returns an error if the source value - /// is outside of the range of the target type. - #[inline] - fn try_from(u: $source) -> Result { - let min = Self::MIN as $source; - let max = Self::MAX as $source; - if u < min || u > max { - Err(TryFromIntError(())) - } else { - Ok(u as Self) - } - } - } - )*} -} - -macro_rules! rev { - ($mac:ident, $source:ty => $($target:ty),+) => {$( - $mac!($target => $source); - )*} -} - -// unsigned integer -> unsigned integer -impl_try_from_upper_bounded!(u16 => u8); -impl_try_from_upper_bounded!(u32 => u8, u16); -impl_try_from_upper_bounded!(u64 => u8, u16, u32); -impl_try_from_upper_bounded!(u128 => u8, u16, u32, u64); - -// signed integer -> signed integer -impl_try_from_both_bounded!(i16 => i8); -impl_try_from_both_bounded!(i32 => i8, i16); -impl_try_from_both_bounded!(i64 => i8, i16, i32); -impl_try_from_both_bounded!(i128 => i8, i16, i32, i64); - -// unsigned integer -> signed integer -impl_try_from_upper_bounded!(u8 => i8); -impl_try_from_upper_bounded!(u16 => i8, i16); -impl_try_from_upper_bounded!(u32 => i8, i16, i32); -impl_try_from_upper_bounded!(u64 => i8, i16, i32, i64); -impl_try_from_upper_bounded!(u128 => i8, i16, i32, i64, i128); - -// signed integer -> unsigned integer -impl_try_from_lower_bounded!(i8 => u8, u16, u32, u64, u128); -impl_try_from_both_bounded!(i16 => u8); -impl_try_from_lower_bounded!(i16 => u16, u32, u64, u128); -impl_try_from_both_bounded!(i32 => u8, u16); -impl_try_from_lower_bounded!(i32 => u32, u64, u128); -impl_try_from_both_bounded!(i64 => u8, u16, u32); -impl_try_from_lower_bounded!(i64 => u64, u128); -impl_try_from_both_bounded!(i128 => u8, u16, u32, u64); -impl_try_from_lower_bounded!(i128 => u128); - -// usize/isize -impl_try_from_upper_bounded!(usize => isize); -impl_try_from_lower_bounded!(isize => usize); - -#[cfg(target_pointer_width = "16")] -mod ptr_try_from_impls { - use super::TryFromIntError; - - impl_try_from_upper_bounded!(usize => u8); - impl_try_from_unbounded!(usize => u16, u32, u64, u128); - impl_try_from_upper_bounded!(usize => i8, i16); - impl_try_from_unbounded!(usize => i32, i64, i128); - - impl_try_from_both_bounded!(isize => u8); - impl_try_from_lower_bounded!(isize => u16, u32, u64, u128); - impl_try_from_both_bounded!(isize => i8); - impl_try_from_unbounded!(isize => i16, i32, i64, i128); - - rev!(impl_try_from_upper_bounded, usize => u32, u64, u128); - rev!(impl_try_from_lower_bounded, usize => i8, i16); - rev!(impl_try_from_both_bounded, usize => i32, i64, i128); - - rev!(impl_try_from_upper_bounded, isize => u16, u32, u64, u128); - rev!(impl_try_from_both_bounded, isize => i32, i64, i128); -} - -#[cfg(target_pointer_width = "32")] -mod ptr_try_from_impls { - use super::TryFromIntError; - - impl_try_from_upper_bounded!(usize => u8, u16); - impl_try_from_unbounded!(usize => u32, u64, u128); - impl_try_from_upper_bounded!(usize => i8, i16, i32); - impl_try_from_unbounded!(usize => i64, i128); - - impl_try_from_both_bounded!(isize => u8, u16); - impl_try_from_lower_bounded!(isize => u32, u64, u128); - impl_try_from_both_bounded!(isize => i8, i16); - impl_try_from_unbounded!(isize => i32, i64, i128); - - rev!(impl_try_from_unbounded, usize => u32); - rev!(impl_try_from_upper_bounded, usize => u64, u128); - rev!(impl_try_from_lower_bounded, usize => i8, i16, i32); - rev!(impl_try_from_both_bounded, usize => i64, i128); - - rev!(impl_try_from_unbounded, isize => u16); - rev!(impl_try_from_upper_bounded, isize => u32, u64, u128); - rev!(impl_try_from_unbounded, isize => i32); - rev!(impl_try_from_both_bounded, isize => i64, i128); -} - -#[cfg(target_pointer_width = "64")] -mod ptr_try_from_impls { - use super::TryFromIntError; - - impl_try_from_upper_bounded!(usize => u8, u16, u32); - impl_try_from_unbounded!(usize => u64, u128); - impl_try_from_upper_bounded!(usize => i8, i16, i32, i64); - impl_try_from_unbounded!(usize => i128); - - impl_try_from_both_bounded!(isize => u8, u16, u32); - impl_try_from_lower_bounded!(isize => u64, u128); - impl_try_from_both_bounded!(isize => i8, i16, i32); - impl_try_from_unbounded!(isize => i64, i128); - - rev!(impl_try_from_unbounded, usize => u32, u64); - rev!(impl_try_from_upper_bounded, usize => u128); - rev!(impl_try_from_lower_bounded, usize => i8, i16, i32, i64); - rev!(impl_try_from_both_bounded, usize => i128); - - rev!(impl_try_from_unbounded, isize => u16, u32); - rev!(impl_try_from_upper_bounded, isize => u64, u128); - rev!(impl_try_from_unbounded, isize => i32, i64); - rev!(impl_try_from_both_bounded, isize => i128); -} - -// Conversion traits for non-zero integer types -use crate::num::NonZero; - -macro_rules! impl_nonzero_int_from_nonzero_int { - ($Small:ty => $Large:ty) => { - #[stable(feature = "nz_int_conv", since = "1.41.0")] - impl From> for NonZero<$Large> { - // Rustdocs on the impl block show a "[+] show undocumented items" toggle. - // Rustdocs on functions do not. - #[doc = concat!("Converts [NonZero]\\<[", stringify!($Small), "]> ")] - #[doc = concat!("to [NonZero]\\<[", stringify!($Large), "]> losslessly.")] - #[inline] - fn from(small: NonZero<$Small>) -> Self { - // SAFETY: input type guarantees the value is non-zero - unsafe { Self::new_unchecked(From::from(small.get())) } - } - } - }; -} - -// non-zero unsigned integer -> non-zero unsigned integer -impl_nonzero_int_from_nonzero_int!(u8 => u16); -impl_nonzero_int_from_nonzero_int!(u8 => u32); -impl_nonzero_int_from_nonzero_int!(u8 => u64); -impl_nonzero_int_from_nonzero_int!(u8 => u128); -impl_nonzero_int_from_nonzero_int!(u8 => usize); -impl_nonzero_int_from_nonzero_int!(u16 => u32); -impl_nonzero_int_from_nonzero_int!(u16 => u64); -impl_nonzero_int_from_nonzero_int!(u16 => u128); -impl_nonzero_int_from_nonzero_int!(u16 => usize); -impl_nonzero_int_from_nonzero_int!(u32 => u64); -impl_nonzero_int_from_nonzero_int!(u32 => u128); -impl_nonzero_int_from_nonzero_int!(u64 => u128); - -// non-zero signed integer -> non-zero signed integer -impl_nonzero_int_from_nonzero_int!(i8 => i16); -impl_nonzero_int_from_nonzero_int!(i8 => i32); -impl_nonzero_int_from_nonzero_int!(i8 => i64); -impl_nonzero_int_from_nonzero_int!(i8 => i128); -impl_nonzero_int_from_nonzero_int!(i8 => isize); -impl_nonzero_int_from_nonzero_int!(i16 => i32); -impl_nonzero_int_from_nonzero_int!(i16 => i64); -impl_nonzero_int_from_nonzero_int!(i16 => i128); -impl_nonzero_int_from_nonzero_int!(i16 => isize); -impl_nonzero_int_from_nonzero_int!(i32 => i64); -impl_nonzero_int_from_nonzero_int!(i32 => i128); -impl_nonzero_int_from_nonzero_int!(i64 => i128); - -// non-zero unsigned -> non-zero signed integer -impl_nonzero_int_from_nonzero_int!(u8 => i16); -impl_nonzero_int_from_nonzero_int!(u8 => i32); -impl_nonzero_int_from_nonzero_int!(u8 => i64); -impl_nonzero_int_from_nonzero_int!(u8 => i128); -impl_nonzero_int_from_nonzero_int!(u8 => isize); -impl_nonzero_int_from_nonzero_int!(u16 => i32); -impl_nonzero_int_from_nonzero_int!(u16 => i64); -impl_nonzero_int_from_nonzero_int!(u16 => i128); -impl_nonzero_int_from_nonzero_int!(u32 => i64); -impl_nonzero_int_from_nonzero_int!(u32 => i128); -impl_nonzero_int_from_nonzero_int!(u64 => i128); - -macro_rules! impl_nonzero_int_try_from_int { - ($Int:ty) => { - #[stable(feature = "nzint_try_from_int_conv", since = "1.46.0")] - impl TryFrom<$Int> for NonZero<$Int> { - type Error = TryFromIntError; - - // Rustdocs on the impl block show a "[+] show undocumented items" toggle. - // Rustdocs on functions do not. - #[doc = concat!("Attempts to convert [`", stringify!($Int), "`] ")] - #[doc = concat!("to [NonZero]\\<[", stringify!($Int), "]>.")] - #[inline] - fn try_from(value: $Int) -> Result { - Self::new(value).ok_or(TryFromIntError(())) - } - } - }; -} - -// integer -> non-zero integer -impl_nonzero_int_try_from_int!(u8); -impl_nonzero_int_try_from_int!(u16); -impl_nonzero_int_try_from_int!(u32); -impl_nonzero_int_try_from_int!(u64); -impl_nonzero_int_try_from_int!(u128); -impl_nonzero_int_try_from_int!(usize); -impl_nonzero_int_try_from_int!(i8); -impl_nonzero_int_try_from_int!(i16); -impl_nonzero_int_try_from_int!(i32); -impl_nonzero_int_try_from_int!(i64); -impl_nonzero_int_try_from_int!(i128); -impl_nonzero_int_try_from_int!(isize); - -macro_rules! impl_nonzero_int_try_from_nonzero_int { - ($source:ty => $($target:ty),+) => {$( - #[stable(feature = "nzint_try_from_nzint_conv", since = "1.49.0")] - impl TryFrom> for NonZero<$target> { - type Error = TryFromIntError; - - // Rustdocs on the impl block show a "[+] show undocumented items" toggle. - // Rustdocs on functions do not. - #[doc = concat!("Attempts to convert [NonZero]\\<[", stringify!($source), "]> ")] - #[doc = concat!("to [NonZero]\\<[", stringify!($target), "]>.")] - #[inline] - fn try_from(value: NonZero<$source>) -> Result { - // SAFETY: Input is guaranteed to be non-zero. - Ok(unsafe { Self::new_unchecked(<$target>::try_from(value.get())?) }) - } - } - )*}; -} - -// unsigned non-zero integer -> unsigned non-zero integer -impl_nonzero_int_try_from_nonzero_int!(u16 => u8); -impl_nonzero_int_try_from_nonzero_int!(u32 => u8, u16, usize); -impl_nonzero_int_try_from_nonzero_int!(u64 => u8, u16, u32, usize); -impl_nonzero_int_try_from_nonzero_int!(u128 => u8, u16, u32, u64, usize); -impl_nonzero_int_try_from_nonzero_int!(usize => u8, u16, u32, u64, u128); - -// signed non-zero integer -> signed non-zero integer -impl_nonzero_int_try_from_nonzero_int!(i16 => i8); -impl_nonzero_int_try_from_nonzero_int!(i32 => i8, i16, isize); -impl_nonzero_int_try_from_nonzero_int!(i64 => i8, i16, i32, isize); -impl_nonzero_int_try_from_nonzero_int!(i128 => i8, i16, i32, i64, isize); -impl_nonzero_int_try_from_nonzero_int!(isize => i8, i16, i32, i64, i128); - -// unsigned non-zero integer -> signed non-zero integer -impl_nonzero_int_try_from_nonzero_int!(u8 => i8); -impl_nonzero_int_try_from_nonzero_int!(u16 => i8, i16, isize); -impl_nonzero_int_try_from_nonzero_int!(u32 => i8, i16, i32, isize); -impl_nonzero_int_try_from_nonzero_int!(u64 => i8, i16, i32, i64, isize); -impl_nonzero_int_try_from_nonzero_int!(u128 => i8, i16, i32, i64, i128, isize); -impl_nonzero_int_try_from_nonzero_int!(usize => i8, i16, i32, i64, i128, isize); - -// signed non-zero integer -> unsigned non-zero integer -impl_nonzero_int_try_from_nonzero_int!(i8 => u8, u16, u32, u64, u128, usize); -impl_nonzero_int_try_from_nonzero_int!(i16 => u8, u16, u32, u64, u128, usize); -impl_nonzero_int_try_from_nonzero_int!(i32 => u8, u16, u32, u64, u128, usize); -impl_nonzero_int_try_from_nonzero_int!(i64 => u8, u16, u32, u64, u128, usize); -impl_nonzero_int_try_from_nonzero_int!(i128 => u8, u16, u32, u64, u128, usize); -impl_nonzero_int_try_from_nonzero_int!(isize => u8, u16, u32, u64, u128, usize); diff --git a/library/core/src/default.rs b/library/core/src/default.rs deleted file mode 100644 index 4524b352ec817..0000000000000 --- a/library/core/src/default.rs +++ /dev/null @@ -1,184 +0,0 @@ -//! The `Default` trait for types with a default value. - -#![stable(feature = "rust1", since = "1.0.0")] - -use crate::ascii::Char as AsciiChar; - -/// A trait for giving a type a useful default value. -/// -/// Sometimes, you want to fall back to some kind of default value, and -/// don't particularly care what it is. This comes up often with `struct`s -/// that define a set of options: -/// -/// ``` -/// # #[allow(dead_code)] -/// struct SomeOptions { -/// foo: i32, -/// bar: f32, -/// } -/// ``` -/// -/// How can we define some default values? You can use `Default`: -/// -/// ``` -/// # #[allow(dead_code)] -/// #[derive(Default)] -/// struct SomeOptions { -/// foo: i32, -/// bar: f32, -/// } -/// -/// fn main() { -/// let options: SomeOptions = Default::default(); -/// } -/// ``` -/// -/// Now, you get all of the default values. Rust implements `Default` for various primitives types. -/// -/// If you want to override a particular option, but still retain the other defaults: -/// -/// ``` -/// # #[allow(dead_code)] -/// # #[derive(Default)] -/// # struct SomeOptions { -/// # foo: i32, -/// # bar: f32, -/// # } -/// fn main() { -/// let options = SomeOptions { foo: 42, ..Default::default() }; -/// } -/// ``` -/// -/// ## Derivable -/// -/// This trait can be used with `#[derive]` if all of the type's fields implement -/// `Default`. When `derive`d, it will use the default value for each field's type. -/// -/// ### `enum`s -/// -/// When using `#[derive(Default)]` on an `enum`, you need to choose which unit variant will be -/// default. You do this by placing the `#[default]` attribute on the variant. -/// -/// ``` -/// #[derive(Default)] -/// enum Kind { -/// #[default] -/// A, -/// B, -/// C, -/// } -/// ``` -/// -/// You cannot use the `#[default]` attribute on non-unit or non-exhaustive variants. -/// -/// The `#[default]` attribute was stabilized in Rust 1.62.0. -/// -/// ## How can I implement `Default`? -/// -/// Provide an implementation for the `default()` method that returns the value of -/// your type that should be the default: -/// -/// ``` -/// # #![allow(dead_code)] -/// enum Kind { -/// A, -/// B, -/// C, -/// } -/// -/// impl Default for Kind { -/// fn default() -> Self { Kind::A } -/// } -/// ``` -/// -/// # Examples -/// -/// ``` -/// # #[allow(dead_code)] -/// #[derive(Default)] -/// struct SomeOptions { -/// foo: i32, -/// bar: f32, -/// } -/// ``` -#[cfg_attr(not(test), rustc_diagnostic_item = "Default")] -#[stable(feature = "rust1", since = "1.0.0")] -pub trait Default: Sized { - /// Returns the "default value" for a type. - /// - /// Default values are often some kind of initial value, identity value, or anything else that - /// may make sense as a default. - /// - /// # Examples - /// - /// Using built-in default values: - /// - /// ``` - /// let i: i8 = Default::default(); - /// let (x, y): (Option, f64) = Default::default(); - /// let (a, b, (c, d)): (i32, u32, (bool, bool)) = Default::default(); - /// ``` - /// - /// Making your own: - /// - /// ``` - /// # #[allow(dead_code)] - /// enum Kind { - /// A, - /// B, - /// C, - /// } - /// - /// impl Default for Kind { - /// fn default() -> Self { Kind::A } - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_diagnostic_item = "default_fn"] - fn default() -> Self; -} - -/// Derive macro generating an impl of the trait `Default`. -#[rustc_builtin_macro(Default, attributes(default))] -#[stable(feature = "builtin_macro_prelude", since = "1.38.0")] -#[allow_internal_unstable(core_intrinsics)] -pub macro Default($item:item) { - /* compiler built-in */ -} - -macro_rules! default_impl { - ($t:ty, $v:expr, $doc:tt) => { - #[stable(feature = "rust1", since = "1.0.0")] - impl Default for $t { - #[inline(always)] - #[doc = $doc] - fn default() -> $t { - $v - } - } - }; -} - -default_impl! { (), (), "Returns the default value of `()`" } -default_impl! { bool, false, "Returns the default value of `false`" } -default_impl! { char, '\x00', "Returns the default value of `\\x00`" } -default_impl! { AsciiChar, AsciiChar::Null, "Returns the default value of `Null`" } - -default_impl! { usize, 0, "Returns the default value of `0`" } -default_impl! { u8, 0, "Returns the default value of `0`" } -default_impl! { u16, 0, "Returns the default value of `0`" } -default_impl! { u32, 0, "Returns the default value of `0`" } -default_impl! { u64, 0, "Returns the default value of `0`" } -default_impl! { u128, 0, "Returns the default value of `0`" } - -default_impl! { isize, 0, "Returns the default value of `0`" } -default_impl! { i8, 0, "Returns the default value of `0`" } -default_impl! { i16, 0, "Returns the default value of `0`" } -default_impl! { i32, 0, "Returns the default value of `0`" } -default_impl! { i64, 0, "Returns the default value of `0`" } -default_impl! { i128, 0, "Returns the default value of `0`" } - -default_impl! { f16, 0.0f16, "Returns the default value of `0.0`" } -default_impl! { f32, 0.0f32, "Returns the default value of `0.0`" } -default_impl! { f64, 0.0f64, "Returns the default value of `0.0`" } -default_impl! { f128, 0.0f128, "Returns the default value of `0.0`" } diff --git a/library/core/src/error.md b/library/core/src/error.md deleted file mode 100644 index a5deb71e6b80a..0000000000000 --- a/library/core/src/error.md +++ /dev/null @@ -1,139 +0,0 @@ -Interfaces for working with Errors. - -# Error Handling In Rust - -The Rust language provides two complementary systems for constructing / -representing, reporting, propagating, reacting to, and discarding errors. -These responsibilities are collectively known as "error handling." The -components of the first system, the panic runtime and interfaces, are most -commonly used to represent bugs that have been detected in your program. The -components of the second system, `Result`, the error traits, and user -defined types, are used to represent anticipated runtime failure modes of -your program. - -## The Panic Interfaces - -The following are the primary interfaces of the panic system and the -responsibilities they cover: - -* [`panic!`] and [`panic_any`] (Constructing, Propagated automatically) -* [`PanicInfo`] (Reporting) -* [`set_hook`], [`take_hook`], and [`#[panic_handler]`][panic-handler] (Reporting) -* [`catch_unwind`] and [`resume_unwind`] (Discarding, Propagating) - -The following are the primary interfaces of the error system and the -responsibilities they cover: - -* [`Result`] (Propagating, Reacting) -* The [`Error`] trait (Reporting) -* User defined types (Constructing / Representing) -* [`match`] and [`downcast`] (Reacting) -* The question mark operator ([`?`]) (Propagating) -* The partially stable [`Try`] traits (Propagating, Constructing) -* [`Termination`] (Reporting) - -## Converting Errors into Panics - -The panic and error systems are not entirely distinct. Often times errors -that are anticipated runtime failures in an API might instead represent bugs -to a caller. For these situations the standard library provides APIs for -constructing panics with an `Error` as its source. - -* [`Result::unwrap`] -* [`Result::expect`] - -These functions are equivalent, they either return the inner value if the -`Result` is `Ok` or panic if the `Result` is `Err` printing the inner error -as the source. The only difference between them is that with `expect` you -provide a panic error message to be printed alongside the source, whereas -`unwrap` has a default message indicating only that you unwrapped an `Err`. - -Of the two, `expect` is generally preferred since its `msg` field allows you -to convey your intent and assumptions which makes tracking down the source -of a panic easier. `unwrap` on the other hand can still be a good fit in -situations where you can trivially show that a piece of code will never -panic, such as `"127.0.0.1".parse::().unwrap()` or early -prototyping. - -# Common Message Styles - -There are two common styles for how people word `expect` messages. Using -the message to present information to users encountering a panic -("expect as error message") or using the message to present information -to developers debugging the panic ("expect as precondition"). - -In the former case the expect message is used to describe the error that -has occurred which is considered a bug. Consider the following example: - -```should_panic -// Read environment variable, panic if it is not present -let path = std::env::var("IMPORTANT_PATH").unwrap(); -``` - -In the "expect as error message" style we would use expect to describe -that the environment variable was not set when it should have been: - -```should_panic -let path = std::env::var("IMPORTANT_PATH") - .expect("env variable `IMPORTANT_PATH` is not set"); -``` - -In the "expect as precondition" style, we would instead describe the -reason we _expect_ the `Result` should be `Ok`. With this style we would -prefer to write: - -```should_panic -let path = std::env::var("IMPORTANT_PATH") - .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`"); -``` - -The "expect as error message" style does not work as well with the -default output of the std panic hooks, and often ends up repeating -information that is already communicated by the source error being -unwrapped: - -```text -thread 'main' panicked at src/main.rs:4:6: -env variable `IMPORTANT_PATH` is not set: NotPresent -``` - -In this example we end up mentioning that an env variable is not set, -followed by our source message that says the env is not present, the -only additional information we're communicating is the name of the -environment variable being checked. - -The "expect as precondition" style instead focuses on source code -readability, making it easier to understand what must have gone wrong in -situations where panics are being used to represent bugs exclusively. -Also, by framing our expect in terms of what "SHOULD" have happened to -prevent the source error, we end up introducing new information that is -independent from our source error. - -```text -thread 'main' panicked at src/main.rs:4:6: -env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`: NotPresent -``` - -In this example we are communicating not only the name of the -environment variable that should have been set, but also an explanation -for why it should have been set, and we let the source error display as -a clear contradiction to our expectation. - -**Hint**: If you're having trouble remembering how to phrase -expect-as-precondition style error messages remember to focus on the word -"should" as in "env variable should be set by blah" or "the given binary -should be available and executable by the current user". - -[`panic_any`]: ../../std/panic/fn.panic_any.html -[`PanicInfo`]: crate::panic::PanicInfo -[`catch_unwind`]: ../../std/panic/fn.catch_unwind.html -[`resume_unwind`]: ../../std/panic/fn.resume_unwind.html -[`downcast`]: crate::error::Error -[`Termination`]: ../../std/process/trait.Termination.html -[`Try`]: crate::ops::Try -[panic hook]: ../../std/panic/fn.set_hook.html -[`set_hook`]: ../../std/panic/fn.set_hook.html -[`take_hook`]: ../../std/panic/fn.take_hook.html -[panic-handler]: -[`match`]: ../../std/keyword.match.html -[`?`]: ../../std/result/index.html#the-question-mark-operator- diff --git a/library/core/src/error.rs b/library/core/src/error.rs deleted file mode 100644 index a3f2b767054e1..0000000000000 --- a/library/core/src/error.rs +++ /dev/null @@ -1,1086 +0,0 @@ -#![doc = include_str!("error.md")] -#![unstable(feature = "error_in_core", issue = "103765")] - -#[cfg(test)] -mod tests; - -use crate::any::TypeId; -use crate::fmt::{Debug, Display, Formatter, Result}; - -/// `Error` is a trait representing the basic expectations for error values, -/// i.e., values of type `E` in [`Result`]. -/// -/// Errors must describe themselves through the [`Display`] and [`Debug`] -/// traits. Error messages are typically concise lowercase sentences without -/// trailing punctuation: -/// -/// ``` -/// let err = "NaN".parse::().unwrap_err(); -/// assert_eq!(err.to_string(), "invalid digit found in string"); -/// ``` -/// -/// Errors may provide cause information. [`Error::source()`] is generally -/// used when errors cross "abstraction boundaries". If one module must report -/// an error that is caused by an error from a lower-level module, it can allow -/// accessing that error via [`Error::source()`]. This makes it possible for the -/// high-level module to provide its own errors while also revealing some of the -/// implementation for debugging. -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "Error")] -#[rustc_has_incoherent_inherent_impls] -#[allow(multiple_supertrait_upcastable)] -pub trait Error: Debug + Display { - /// The lower-level source of this error, if any. - /// - /// # Examples - /// - /// ``` - /// use std::error::Error; - /// use std::fmt; - /// - /// #[derive(Debug)] - /// struct SuperError { - /// source: SuperErrorSideKick, - /// } - /// - /// impl fmt::Display for SuperError { - /// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - /// write!(f, "SuperError is here!") - /// } - /// } - /// - /// impl Error for SuperError { - /// fn source(&self) -> Option<&(dyn Error + 'static)> { - /// Some(&self.source) - /// } - /// } - /// - /// #[derive(Debug)] - /// struct SuperErrorSideKick; - /// - /// impl fmt::Display for SuperErrorSideKick { - /// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - /// write!(f, "SuperErrorSideKick is here!") - /// } - /// } - /// - /// impl Error for SuperErrorSideKick {} - /// - /// fn get_super_error() -> Result<(), SuperError> { - /// Err(SuperError { source: SuperErrorSideKick }) - /// } - /// - /// fn main() { - /// match get_super_error() { - /// Err(e) => { - /// println!("Error: {e}"); - /// println!("Caused by: {}", e.source().unwrap()); - /// } - /// _ => println!("No error"), - /// } - /// } - /// ``` - #[stable(feature = "error_source", since = "1.30.0")] - fn source(&self) -> Option<&(dyn Error + 'static)> { - None - } - - /// Gets the `TypeId` of `self`. - #[doc(hidden)] - #[unstable( - feature = "error_type_id", - reason = "this is memory-unsafe to override in user code", - issue = "60784" - )] - fn type_id(&self, _: private::Internal) -> TypeId - where - Self: 'static, - { - TypeId::of::() - } - - /// ``` - /// if let Err(e) = "xc".parse::() { - /// // Print `e` itself, no need for description(). - /// eprintln!("Error: {e}"); - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[deprecated(since = "1.42.0", note = "use the Display impl or to_string()")] - fn description(&self) -> &str { - "description() is deprecated; use Display" - } - - #[stable(feature = "rust1", since = "1.0.0")] - #[deprecated( - since = "1.33.0", - note = "replaced by Error::source, which can support downcasting" - )] - #[allow(missing_docs)] - fn cause(&self) -> Option<&dyn Error> { - self.source() - } - - /// Provides type based access to context intended for error reports. - /// - /// Used in conjunction with [`Request::provide_value`] and [`Request::provide_ref`] to extract - /// references to member variables from `dyn Error` trait objects. - /// - /// # Example - /// - /// ```rust - /// #![feature(error_generic_member_access)] - /// #![feature(error_in_core)] - /// use core::fmt; - /// use core::error::{request_ref, Request}; - /// - /// #[derive(Debug)] - /// enum MyLittleTeaPot { - /// Empty, - /// } - /// - /// #[derive(Debug)] - /// struct MyBacktrace { - /// // ... - /// } - /// - /// impl MyBacktrace { - /// fn new() -> MyBacktrace { - /// // ... - /// # MyBacktrace {} - /// } - /// } - /// - /// #[derive(Debug)] - /// struct Error { - /// backtrace: MyBacktrace, - /// } - /// - /// impl fmt::Display for Error { - /// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - /// write!(f, "Example Error") - /// } - /// } - /// - /// impl std::error::Error for Error { - /// fn provide<'a>(&'a self, request: &mut Request<'a>) { - /// request - /// .provide_ref::(&self.backtrace); - /// } - /// } - /// - /// fn main() { - /// let backtrace = MyBacktrace::new(); - /// let error = Error { backtrace }; - /// let dyn_error = &error as &dyn std::error::Error; - /// let backtrace_ref = request_ref::(dyn_error).unwrap(); - /// - /// assert!(core::ptr::eq(&error.backtrace, backtrace_ref)); - /// assert!(request_ref::(dyn_error).is_none()); - /// } - /// ``` - #[unstable(feature = "error_generic_member_access", issue = "99301")] - #[allow(unused_variables)] - fn provide<'a>(&'a self, request: &mut Request<'a>) {} -} - -mod private { - // This is a hack to prevent `type_id` from being overridden by `Error` - // implementations, since that can enable unsound downcasting. - #[unstable(feature = "error_type_id", issue = "60784")] - #[derive(Debug)] - pub struct Internal; -} - -#[unstable(feature = "never_type", issue = "35121")] -impl Error for ! {} - -// Copied from `any.rs`. -impl dyn Error + 'static { - /// Returns `true` if the inner type is the same as `T`. - #[stable(feature = "error_downcast", since = "1.3.0")] - #[inline] - pub fn is(&self) -> bool { - // Get `TypeId` of the type this function is instantiated with. - let t = TypeId::of::(); - - // Get `TypeId` of the type in the trait object (`self`). - let concrete = self.type_id(private::Internal); - - // Compare both `TypeId`s on equality. - t == concrete - } - - /// Returns some reference to the inner value if it is of type `T`, or - /// `None` if it isn't. - #[stable(feature = "error_downcast", since = "1.3.0")] - #[inline] - pub fn downcast_ref(&self) -> Option<&T> { - if self.is::() { - // SAFETY: `is` ensures this type cast is correct - unsafe { Some(&*(self as *const dyn Error as *const T)) } - } else { - None - } - } - - /// Returns some mutable reference to the inner value if it is of type `T`, or - /// `None` if it isn't. - #[stable(feature = "error_downcast", since = "1.3.0")] - #[inline] - pub fn downcast_mut(&mut self) -> Option<&mut T> { - if self.is::() { - // SAFETY: `is` ensures this type cast is correct - unsafe { Some(&mut *(self as *mut dyn Error as *mut T)) } - } else { - None - } - } -} - -impl dyn Error + 'static + Send { - /// Forwards to the method defined on the type `dyn Error`. - #[stable(feature = "error_downcast", since = "1.3.0")] - #[inline] - pub fn is(&self) -> bool { - ::is::(self) - } - - /// Forwards to the method defined on the type `dyn Error`. - #[stable(feature = "error_downcast", since = "1.3.0")] - #[inline] - pub fn downcast_ref(&self) -> Option<&T> { - ::downcast_ref::(self) - } - - /// Forwards to the method defined on the type `dyn Error`. - #[stable(feature = "error_downcast", since = "1.3.0")] - #[inline] - pub fn downcast_mut(&mut self) -> Option<&mut T> { - ::downcast_mut::(self) - } -} - -impl dyn Error + 'static + Send + Sync { - /// Forwards to the method defined on the type `dyn Error`. - #[stable(feature = "error_downcast", since = "1.3.0")] - #[inline] - pub fn is(&self) -> bool { - ::is::(self) - } - - /// Forwards to the method defined on the type `dyn Error`. - #[stable(feature = "error_downcast", since = "1.3.0")] - #[inline] - pub fn downcast_ref(&self) -> Option<&T> { - ::downcast_ref::(self) - } - - /// Forwards to the method defined on the type `dyn Error`. - #[stable(feature = "error_downcast", since = "1.3.0")] - #[inline] - pub fn downcast_mut(&mut self) -> Option<&mut T> { - ::downcast_mut::(self) - } -} - -impl dyn Error { - /// Returns an iterator starting with the current error and continuing with - /// recursively calling [`Error::source`]. - /// - /// If you want to omit the current error and only use its sources, - /// use `skip(1)`. - /// - /// # Examples - /// - /// ``` - /// #![feature(error_iter)] - /// use std::error::Error; - /// use std::fmt; - /// - /// #[derive(Debug)] - /// struct A; - /// - /// #[derive(Debug)] - /// struct B(Option>); - /// - /// impl fmt::Display for A { - /// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - /// write!(f, "A") - /// } - /// } - /// - /// impl fmt::Display for B { - /// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - /// write!(f, "B") - /// } - /// } - /// - /// impl Error for A {} - /// - /// impl Error for B { - /// fn source(&self) -> Option<&(dyn Error + 'static)> { - /// self.0.as_ref().map(|e| e.as_ref()) - /// } - /// } - /// - /// let b = B(Some(Box::new(A))); - /// - /// // let err : Box = b.into(); // or - /// let err = &b as &(dyn Error); - /// - /// let mut iter = err.sources(); - /// - /// assert_eq!("B".to_string(), iter.next().unwrap().to_string()); - /// assert_eq!("A".to_string(), iter.next().unwrap().to_string()); - /// assert!(iter.next().is_none()); - /// assert!(iter.next().is_none()); - /// ``` - #[unstable(feature = "error_iter", issue = "58520")] - #[inline] - pub fn sources(&self) -> Source<'_> { - // You may think this method would be better in the Error trait, and you'd be right. - // Unfortunately that doesn't work, not because of the object safety rules but because we - // save a reference to self in Sources below as a trait object. If this method was - // declared in Error, then self would have the type &T where T is some concrete type which - // implements Error. We would need to coerce self to have type &dyn Error, but that requires - // that Self has a known size (i.e., Self: Sized). We can't put that bound on Error - // since that would forbid Error trait objects, and we can't put that bound on the method - // because that means the method can't be called on trait objects (we'd also need the - // 'static bound, but that isn't allowed because methods with bounds on Self other than - // Sized are not object-safe). Requiring an Unsize bound is not backwards compatible. - - Source { current: Some(self) } - } -} - -/// Request a value of type `T` from the given `impl Error`. -/// -/// # Examples -/// -/// Get a string value from an error. -/// -/// ```rust -/// # #![feature(error_generic_member_access)] -/// # #![feature(error_in_core)] -/// use std::error::Error; -/// use core::error::request_value; -/// -/// fn get_string(err: &impl Error) -> String { -/// request_value::(err).unwrap() -/// } -/// ``` -#[unstable(feature = "error_generic_member_access", issue = "99301")] -pub fn request_value<'a, T>(err: &'a (impl Error + ?Sized)) -> Option -where - T: 'static, -{ - request_by_type_tag::<'a, tags::Value>(err) -} - -/// Request a reference of type `T` from the given `impl Error`. -/// -/// # Examples -/// -/// Get a string reference from an error. -/// -/// ```rust -/// # #![feature(error_generic_member_access)] -/// # #![feature(error_in_core)] -/// use core::error::Error; -/// use core::error::request_ref; -/// -/// fn get_str(err: &impl Error) -> &str { -/// request_ref::(err).unwrap() -/// } -/// ``` -#[unstable(feature = "error_generic_member_access", issue = "99301")] -pub fn request_ref<'a, T>(err: &'a (impl Error + ?Sized)) -> Option<&'a T> -where - T: 'static + ?Sized, -{ - request_by_type_tag::<'a, tags::Ref>>(err) -} - -/// Request a specific value by tag from the `Error`. -fn request_by_type_tag<'a, I>(err: &'a (impl Error + ?Sized)) -> Option -where - I: tags::Type<'a>, -{ - let mut tagged = TaggedOption::<'a, I>(None); - err.provide(tagged.as_request()); - tagged.0 -} - -/////////////////////////////////////////////////////////////////////////////// -// Request and its methods -/////////////////////////////////////////////////////////////////////////////// - -/// `Request` supports generic, type-driven access to data. Its use is currently restricted to the -/// standard library in cases where trait authors wish to allow trait implementors to share generic -/// information across trait boundaries. The motivating and prototypical use case is -/// `core::error::Error` which would otherwise require a method per concrete type (eg. -/// `std::backtrace::Backtrace` instance that implementors want to expose to users). -/// -/// # Data flow -/// -/// To describe the intended data flow for Request objects, let's consider two conceptual users -/// separated by API boundaries: -/// -/// * Consumer - the consumer requests objects using a Request instance; eg a crate that offers -/// fancy `Error`/`Result` reporting to users wants to request a Backtrace from a given `dyn Error`. -/// -/// * Producer - the producer provides objects when requested via Request; eg. a library with an -/// an `Error` implementation that automatically captures backtraces at the time instances are -/// created. -/// -/// The consumer only needs to know where to submit their request and are expected to handle the -/// request not being fulfilled by the use of `Option` in the responses offered by the producer. -/// -/// * A Producer initializes the value of one of its fields of a specific type. (or is otherwise -/// prepared to generate a value requested). eg, `backtrace::Backtrace` or -/// `std::backtrace::Backtrace` -/// * A Consumer requests an object of a specific type (say `std::backtrace::Backtrace`). In the -/// case of a `dyn Error` trait object (the Producer), there are functions called `request_ref` and -/// `request_value` to simplify obtaining an `Option` for a given type. -/// * The Producer, when requested, populates the given Request object which is given as a mutable -/// reference. -/// * The Consumer extracts a value or reference to the requested type from the `Request` object -/// wrapped in an `Option`; in the case of `dyn Error` the aforementioned `request_ref` and ` -/// request_value` methods mean that `dyn Error` users don't have to deal with the `Request` type at -/// all (but `Error` implementors do). The `None` case of the `Option` suggests only that the -/// Producer cannot currently offer an instance of the requested type, not it can't or never will. -/// -/// # Examples -/// -/// The best way to demonstrate this is using an example implementation of `Error`'s `provide` trait -/// method: -/// -/// ``` -/// #![feature(error_generic_member_access)] -/// #![feature(error_in_core)] -/// use core::fmt; -/// use core::error::Request; -/// use core::error::request_ref; -/// -/// #[derive(Debug)] -/// enum MyLittleTeaPot { -/// Empty, -/// } -/// -/// #[derive(Debug)] -/// struct MyBacktrace { -/// // ... -/// } -/// -/// impl MyBacktrace { -/// fn new() -> MyBacktrace { -/// // ... -/// # MyBacktrace {} -/// } -/// } -/// -/// #[derive(Debug)] -/// struct Error { -/// backtrace: MyBacktrace, -/// } -/// -/// impl fmt::Display for Error { -/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { -/// write!(f, "Example Error") -/// } -/// } -/// -/// impl std::error::Error for Error { -/// fn provide<'a>(&'a self, request: &mut Request<'a>) { -/// request -/// .provide_ref::(&self.backtrace); -/// } -/// } -/// -/// fn main() { -/// let backtrace = MyBacktrace::new(); -/// let error = Error { backtrace }; -/// let dyn_error = &error as &dyn std::error::Error; -/// let backtrace_ref = request_ref::(dyn_error).unwrap(); -/// -/// assert!(core::ptr::eq(&error.backtrace, backtrace_ref)); -/// assert!(request_ref::(dyn_error).is_none()); -/// } -/// ``` -/// -#[unstable(feature = "error_generic_member_access", issue = "99301")] -#[cfg_attr(not(doc), repr(transparent))] // work around https://github.com/rust-lang/rust/issues/90435 -pub struct Request<'a>(dyn Erased<'a> + 'a); - -impl<'a> Request<'a> { - /// Create a new `&mut Request` from a `&mut dyn Erased` trait object. - fn new<'b>(erased: &'b mut (dyn Erased<'a> + 'a)) -> &'b mut Request<'a> { - // SAFETY: transmuting `&mut (dyn Erased<'a> + 'a)` to `&mut Request<'a>` is safe since - // `Request` is repr(transparent). - unsafe { &mut *(erased as *mut dyn Erased<'a> as *mut Request<'a>) } - } - - /// Provide a value or other type with only static lifetimes. - /// - /// # Examples - /// - /// Provides an `u8`. - /// - /// ```rust - /// #![feature(error_generic_member_access)] - /// #![feature(error_in_core)] - /// - /// use core::error::Request; - /// - /// #[derive(Debug)] - /// struct SomeConcreteType { field: u8 } - /// - /// impl std::fmt::Display for SomeConcreteType { - /// fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - /// write!(f, "{} failed", self.field) - /// } - /// } - /// - /// impl std::error::Error for SomeConcreteType { - /// fn provide<'a>(&'a self, request: &mut Request<'a>) { - /// request.provide_value::(self.field); - /// } - /// } - /// ``` - #[unstable(feature = "error_generic_member_access", issue = "99301")] - pub fn provide_value(&mut self, value: T) -> &mut Self - where - T: 'static, - { - self.provide::>(value) - } - - /// Provide a value or other type with only static lifetimes computed using a closure. - /// - /// # Examples - /// - /// Provides a `String` by cloning. - /// - /// ```rust - /// #![feature(error_generic_member_access)] - /// #![feature(error_in_core)] - /// - /// use core::error::Request; - /// - /// #[derive(Debug)] - /// struct SomeConcreteType { field: String } - /// - /// impl std::fmt::Display for SomeConcreteType { - /// fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - /// write!(f, "{} failed", self.field) - /// } - /// } - /// - /// impl std::error::Error for SomeConcreteType { - /// fn provide<'a>(&'a self, request: &mut Request<'a>) { - /// request.provide_value_with::(|| self.field.clone()); - /// } - /// } - /// ``` - #[unstable(feature = "error_generic_member_access", issue = "99301")] - pub fn provide_value_with(&mut self, fulfil: impl FnOnce() -> T) -> &mut Self - where - T: 'static, - { - self.provide_with::>(fulfil) - } - - /// Provide a reference. The referee type must be bounded by `'static`, - /// but may be unsized. - /// - /// # Examples - /// - /// Provides a reference to a field as a `&str`. - /// - /// ```rust - /// #![feature(error_generic_member_access)] - /// #![feature(error_in_core)] - /// - /// use core::error::Request; - /// - /// #[derive(Debug)] - /// struct SomeConcreteType { field: String } - /// - /// impl std::fmt::Display for SomeConcreteType { - /// fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - /// write!(f, "{} failed", self.field) - /// } - /// } - /// - /// impl std::error::Error for SomeConcreteType { - /// fn provide<'a>(&'a self, request: &mut Request<'a>) { - /// request.provide_ref::(&self.field); - /// } - /// } - /// ``` - #[unstable(feature = "error_generic_member_access", issue = "99301")] - pub fn provide_ref(&mut self, value: &'a T) -> &mut Self { - self.provide::>>(value) - } - - /// Provide a reference computed using a closure. The referee type - /// must be bounded by `'static`, but may be unsized. - /// - /// # Examples - /// - /// Provides a reference to a field as a `&str`. - /// - /// ```rust - /// #![feature(error_generic_member_access)] - /// #![feature(error_in_core)] - /// - /// use core::error::Request; - /// - /// #[derive(Debug)] - /// struct SomeConcreteType { business: String, party: String } - /// fn today_is_a_weekday() -> bool { true } - /// - /// impl std::fmt::Display for SomeConcreteType { - /// fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - /// write!(f, "{} failed", self.business) - /// } - /// } - /// - /// impl std::error::Error for SomeConcreteType { - /// fn provide<'a>(&'a self, request: &mut Request<'a>) { - /// request.provide_ref_with::(|| { - /// if today_is_a_weekday() { - /// &self.business - /// } else { - /// &self.party - /// } - /// }); - /// } - /// } - /// ``` - #[unstable(feature = "error_generic_member_access", issue = "99301")] - pub fn provide_ref_with( - &mut self, - fulfil: impl FnOnce() -> &'a T, - ) -> &mut Self { - self.provide_with::>>(fulfil) - } - - /// Provide a value with the given `Type` tag. - fn provide(&mut self, value: I::Reified) -> &mut Self - where - I: tags::Type<'a>, - { - if let Some(res @ TaggedOption(None)) = self.0.downcast_mut::() { - res.0 = Some(value); - } - self - } - - /// Provide a value with the given `Type` tag, using a closure to prevent unnecessary work. - fn provide_with(&mut self, fulfil: impl FnOnce() -> I::Reified) -> &mut Self - where - I: tags::Type<'a>, - { - if let Some(res @ TaggedOption(None)) = self.0.downcast_mut::() { - res.0 = Some(fulfil()); - } - self - } - - /// Check if the `Request` would be satisfied if provided with a - /// value of the specified type. If the type does not match or has - /// already been provided, returns false. - /// - /// # Examples - /// - /// Check if an `u8` still needs to be provided and then provides - /// it. - /// - /// ```rust - /// #![feature(error_generic_member_access)] - /// #![feature(error_in_core)] - /// - /// use core::error::Request; - /// use core::error::request_value; - /// - /// #[derive(Debug)] - /// struct Parent(Option); - /// - /// impl std::fmt::Display for Parent { - /// fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - /// write!(f, "a parent failed") - /// } - /// } - /// - /// impl std::error::Error for Parent { - /// fn provide<'a>(&'a self, request: &mut Request<'a>) { - /// if let Some(v) = self.0 { - /// request.provide_value::(v); - /// } - /// } - /// } - /// - /// #[derive(Debug)] - /// struct Child { - /// parent: Parent, - /// } - /// - /// impl Child { - /// // Pretend that this takes a lot of resources to evaluate. - /// fn an_expensive_computation(&self) -> Option { - /// Some(99) - /// } - /// } - /// - /// impl std::fmt::Display for Child { - /// fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - /// write!(f, "child failed: \n because of parent: {}", self.parent) - /// } - /// } - /// - /// impl std::error::Error for Child { - /// fn provide<'a>(&'a self, request: &mut Request<'a>) { - /// // In general, we don't know if this call will provide - /// // an `u8` value or not... - /// self.parent.provide(request); - /// - /// // ...so we check to see if the `u8` is needed before - /// // we run our expensive computation. - /// if request.would_be_satisfied_by_value_of::() { - /// if let Some(v) = self.an_expensive_computation() { - /// request.provide_value::(v); - /// } - /// } - /// - /// // The request will be satisfied now, regardless of if - /// // the parent provided the value or we did. - /// assert!(!request.would_be_satisfied_by_value_of::()); - /// } - /// } - /// - /// let parent = Parent(Some(42)); - /// let child = Child { parent }; - /// assert_eq!(Some(42), request_value::(&child)); - /// - /// let parent = Parent(None); - /// let child = Child { parent }; - /// assert_eq!(Some(99), request_value::(&child)); - /// - /// ``` - #[unstable(feature = "error_generic_member_access", issue = "99301")] - pub fn would_be_satisfied_by_value_of(&self) -> bool - where - T: 'static, - { - self.would_be_satisfied_by::>() - } - - /// Check if the `Request` would be satisfied if provided with a - /// reference to a value of the specified type. If the type does - /// not match or has already been provided, returns false. - /// - /// # Examples - /// - /// Check if a `&str` still needs to be provided and then provides - /// it. - /// - /// ```rust - /// #![feature(error_generic_member_access)] - /// #![feature(error_in_core)] - /// - /// use core::error::Request; - /// use core::error::request_ref; - /// - /// #[derive(Debug)] - /// struct Parent(Option); - /// - /// impl std::fmt::Display for Parent { - /// fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - /// write!(f, "a parent failed") - /// } - /// } - /// - /// impl std::error::Error for Parent { - /// fn provide<'a>(&'a self, request: &mut Request<'a>) { - /// if let Some(v) = &self.0 { - /// request.provide_ref::(v); - /// } - /// } - /// } - /// - /// #[derive(Debug)] - /// struct Child { - /// parent: Parent, - /// name: String, - /// } - /// - /// impl Child { - /// // Pretend that this takes a lot of resources to evaluate. - /// fn an_expensive_computation(&self) -> Option<&str> { - /// Some(&self.name) - /// } - /// } - /// - /// impl std::fmt::Display for Child { - /// fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - /// write!(f, "{} failed: \n {}", self.name, self.parent) - /// } - /// } - /// - /// impl std::error::Error for Child { - /// fn provide<'a>(&'a self, request: &mut Request<'a>) { - /// // In general, we don't know if this call will provide - /// // a `str` reference or not... - /// self.parent.provide(request); - /// - /// // ...so we check to see if the `&str` is needed before - /// // we run our expensive computation. - /// if request.would_be_satisfied_by_ref_of::() { - /// if let Some(v) = self.an_expensive_computation() { - /// request.provide_ref::(v); - /// } - /// } - /// - /// // The request will be satisfied now, regardless of if - /// // the parent provided the reference or we did. - /// assert!(!request.would_be_satisfied_by_ref_of::()); - /// } - /// } - /// - /// let parent = Parent(Some("parent".into())); - /// let child = Child { parent, name: "child".into() }; - /// assert_eq!(Some("parent"), request_ref::(&child)); - /// - /// let parent = Parent(None); - /// let child = Child { parent, name: "child".into() }; - /// assert_eq!(Some("child"), request_ref::(&child)); - /// ``` - #[unstable(feature = "error_generic_member_access", issue = "99301")] - pub fn would_be_satisfied_by_ref_of(&self) -> bool - where - T: ?Sized + 'static, - { - self.would_be_satisfied_by::>>() - } - - fn would_be_satisfied_by(&self) -> bool - where - I: tags::Type<'a>, - { - matches!(self.0.downcast::(), Some(TaggedOption(None))) - } -} - -#[unstable(feature = "error_generic_member_access", issue = "99301")] -impl<'a> Debug for Request<'a> { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - f.debug_struct("Request").finish_non_exhaustive() - } -} - -/////////////////////////////////////////////////////////////////////////////// -// Type tags -/////////////////////////////////////////////////////////////////////////////// - -pub(crate) mod tags { - //! Type tags are used to identify a type using a separate value. This module includes type tags - //! for some very common types. - //! - //! Currently type tags are not exposed to the user. But in the future, if you want to use the - //! Request API with more complex types (typically those including lifetime parameters), you - //! will need to write your own tags. - - use crate::marker::PhantomData; - - /// This trait is implemented by specific tag types in order to allow - /// describing a type which can be requested for a given lifetime `'a`. - /// - /// A few example implementations for type-driven tags can be found in this - /// module, although crates may also implement their own tags for more - /// complex types with internal lifetimes. - pub(crate) trait Type<'a>: Sized + 'static { - /// The type of values which may be tagged by this tag for the given - /// lifetime. - type Reified: 'a; - } - - /// Similar to the [`Type`] trait, but represents a type which may be unsized (i.e., has a - /// `?Sized` bound). E.g., `str`. - pub(crate) trait MaybeSizedType<'a>: Sized + 'static { - type Reified: 'a + ?Sized; - } - - impl<'a, T: Type<'a>> MaybeSizedType<'a> for T { - type Reified = T::Reified; - } - - /// Type-based tag for types bounded by `'static`, i.e., with no borrowed elements. - #[derive(Debug)] - pub(crate) struct Value(PhantomData); - - impl<'a, T: 'static> Type<'a> for Value { - type Reified = T; - } - - /// Type-based tag similar to [`Value`] but which may be unsized (i.e., has a `?Sized` bound). - #[derive(Debug)] - pub(crate) struct MaybeSizedValue(PhantomData); - - impl<'a, T: ?Sized + 'static> MaybeSizedType<'a> for MaybeSizedValue { - type Reified = T; - } - - /// Type-based tag for reference types (`&'a T`, where T is represented by - /// `>::Reified`. - #[derive(Debug)] - pub(crate) struct Ref(PhantomData); - - impl<'a, I: MaybeSizedType<'a>> Type<'a> for Ref { - type Reified = &'a I::Reified; - } -} - -/// An `Option` with a type tag `I`. -/// -/// Since this struct implements `Erased`, the type can be erased to make a dynamically typed -/// option. The type can be checked dynamically using `Erased::tag_id` and since this is statically -/// checked for the concrete type, there is some degree of type safety. -#[repr(transparent)] -pub(crate) struct TaggedOption<'a, I: tags::Type<'a>>(pub Option); - -impl<'a, I: tags::Type<'a>> TaggedOption<'a, I> { - pub(crate) fn as_request(&mut self) -> &mut Request<'a> { - Request::new(self as &mut (dyn Erased<'a> + 'a)) - } -} - -/// Represents a type-erased but identifiable object. -/// -/// This trait is exclusively implemented by the `TaggedOption` type. -unsafe trait Erased<'a>: 'a { - /// The `TypeId` of the erased type. - fn tag_id(&self) -> TypeId; -} - -unsafe impl<'a, I: tags::Type<'a>> Erased<'a> for TaggedOption<'a, I> { - fn tag_id(&self) -> TypeId { - TypeId::of::() - } -} - -impl<'a> dyn Erased<'a> + 'a { - /// Returns some reference to the dynamic value if it is tagged with `I`, - /// or `None` otherwise. - #[inline] - fn downcast(&self) -> Option<&TaggedOption<'a, I>> - where - I: tags::Type<'a>, - { - if self.tag_id() == TypeId::of::() { - // SAFETY: Just checked whether we're pointing to an I. - Some(unsafe { &*(self as *const Self).cast::>() }) - } else { - None - } - } - - /// Returns some mutable reference to the dynamic value if it is tagged with `I`, - /// or `None` otherwise. - #[inline] - fn downcast_mut(&mut self) -> Option<&mut TaggedOption<'a, I>> - where - I: tags::Type<'a>, - { - if self.tag_id() == TypeId::of::() { - // SAFETY: Just checked whether we're pointing to an I. - Some(unsafe { &mut *(self as *mut Self).cast::>() }) - } else { - None - } - } -} - -/// An iterator over an [`Error`] and its sources. -/// -/// If you want to omit the initial error and only process -/// its sources, use `skip(1)`. -#[unstable(feature = "error_iter", issue = "58520")] -#[derive(Clone, Debug)] -pub struct Source<'a> { - current: Option<&'a (dyn Error + 'static)>, -} - -#[unstable(feature = "error_iter", issue = "58520")] -impl<'a> Iterator for Source<'a> { - type Item = &'a (dyn Error + 'static); - - fn next(&mut self) -> Option { - let current = self.current; - self.current = self.current.and_then(Error::source); - current - } -} - -#[stable(feature = "error_by_ref", since = "1.51.0")] -impl<'a, T: Error + ?Sized> Error for &'a T { - #[allow(deprecated, deprecated_in_future)] - fn description(&self) -> &str { - Error::description(&**self) - } - - #[allow(deprecated)] - fn cause(&self) -> Option<&dyn Error> { - Error::cause(&**self) - } - - fn source(&self) -> Option<&(dyn Error + 'static)> { - Error::source(&**self) - } - - fn provide<'b>(&'b self, request: &mut Request<'b>) { - Error::provide(&**self, request); - } -} - -#[stable(feature = "fmt_error", since = "1.11.0")] -impl Error for crate::fmt::Error { - #[allow(deprecated)] - fn description(&self) -> &str { - "an error occurred when formatting an argument" - } -} - -#[stable(feature = "try_borrow", since = "1.13.0")] -impl Error for crate::cell::BorrowError { - #[allow(deprecated)] - fn description(&self) -> &str { - "already mutably borrowed" - } -} - -#[stable(feature = "try_borrow", since = "1.13.0")] -impl Error for crate::cell::BorrowMutError { - #[allow(deprecated)] - fn description(&self) -> &str { - "already borrowed" - } -} - -#[stable(feature = "try_from", since = "1.34.0")] -impl Error for crate::char::CharTryFromError { - #[allow(deprecated)] - fn description(&self) -> &str { - "converted integer out of range for `char`" - } -} - -#[stable(feature = "duration_checked_float", since = "1.66.0")] -impl Error for crate::time::TryFromFloatSecsError {} - -#[stable(feature = "cstr_from_bytes_until_nul", since = "1.69.0")] -impl Error for crate::ffi::FromBytesUntilNulError {} - -#[unstable(feature = "get_many_mut", issue = "104642")] -impl Error for crate::slice::GetManyMutError {} diff --git a/library/core/src/escape.rs b/library/core/src/escape.rs deleted file mode 100644 index f6ec30b9f793a..0000000000000 --- a/library/core/src/escape.rs +++ /dev/null @@ -1,157 +0,0 @@ -//! Helper code for character escaping. - -use crate::ascii; -use crate::num::NonZero; -use crate::ops::Range; - -const HEX_DIGITS: [ascii::Char; 16] = *b"0123456789abcdef".as_ascii().unwrap(); - -#[inline] -const fn backslash(a: ascii::Char) -> ([ascii::Char; N], Range) { - const { assert!(N >= 2) }; - - let mut output = [ascii::Char::Null; N]; - - output[0] = ascii::Char::ReverseSolidus; - output[1] = a; - - (output, 0..2) -} - -/// Escapes an ASCII character. -/// -/// Returns a buffer and the length of the escaped representation. -const fn escape_ascii(byte: u8) -> ([ascii::Char; N], Range) { - const { assert!(N >= 4) }; - - match byte { - b'\t' => backslash(ascii::Char::SmallT), - b'\r' => backslash(ascii::Char::SmallR), - b'\n' => backslash(ascii::Char::SmallN), - b'\\' => backslash(ascii::Char::ReverseSolidus), - b'\'' => backslash(ascii::Char::Apostrophe), - b'\"' => backslash(ascii::Char::QuotationMark), - byte => { - let mut output = [ascii::Char::Null; N]; - - if let Some(c) = byte.as_ascii() - && !byte.is_ascii_control() - { - output[0] = c; - (output, 0..1) - } else { - let hi = HEX_DIGITS[(byte >> 4) as usize]; - let lo = HEX_DIGITS[(byte & 0xf) as usize]; - - output[0] = ascii::Char::ReverseSolidus; - output[1] = ascii::Char::SmallX; - output[2] = hi; - output[3] = lo; - - (output, 0..4) - } - } - } -} - -/// Escapes a character `\u{NNNN}` representation. -/// -/// Returns a buffer and the length of the escaped representation. -const fn escape_unicode(c: char) -> ([ascii::Char; N], Range) { - const { assert!(N >= 10 && N < u8::MAX as usize) }; - - let c = u32::from(c); - - // OR-ing `1` ensures that for `c == 0` the code computes that - // one digit should be printed. - let start = (c | 1).leading_zeros() as usize / 4 - 2; - - let mut output = [ascii::Char::Null; N]; - output[3] = HEX_DIGITS[((c >> 20) & 15) as usize]; - output[4] = HEX_DIGITS[((c >> 16) & 15) as usize]; - output[5] = HEX_DIGITS[((c >> 12) & 15) as usize]; - output[6] = HEX_DIGITS[((c >> 8) & 15) as usize]; - output[7] = HEX_DIGITS[((c >> 4) & 15) as usize]; - output[8] = HEX_DIGITS[((c >> 0) & 15) as usize]; - output[9] = ascii::Char::RightCurlyBracket; - output[start + 0] = ascii::Char::ReverseSolidus; - output[start + 1] = ascii::Char::SmallU; - output[start + 2] = ascii::Char::LeftCurlyBracket; - - (output, (start as u8)..(N as u8)) -} - -/// An iterator over an fixed-size array. -/// -/// This is essentially equivalent to array’s IntoIter except that indexes are -/// limited to u8 to reduce size of the structure. -#[derive(Clone, Debug)] -pub(crate) struct EscapeIterInner { - // The element type ensures this is always ASCII, and thus also valid UTF-8. - data: [ascii::Char; N], - - // Invariant: `alive.start <= alive.end <= N` - alive: Range, -} - -impl EscapeIterInner { - pub const fn backslash(c: ascii::Char) -> Self { - let (data, range) = backslash(c); - Self { data, alive: range } - } - - pub const fn ascii(c: u8) -> Self { - let (data, range) = escape_ascii(c); - Self { data, alive: range } - } - - pub const fn unicode(c: char) -> Self { - let (data, range) = escape_unicode(c); - Self { data, alive: range } - } - - #[inline] - pub const fn empty() -> Self { - Self { data: [ascii::Char::Null; N], alive: 0..0 } - } - - #[inline] - pub fn as_ascii(&self) -> &[ascii::Char] { - // SAFETY: `self.alive` is guaranteed to be a valid range for indexing `self.data`. - unsafe { - self.data.get_unchecked(usize::from(self.alive.start)..usize::from(self.alive.end)) - } - } - - #[inline] - pub fn as_str(&self) -> &str { - self.as_ascii().as_str() - } - - #[inline] - pub fn len(&self) -> usize { - usize::from(self.alive.end - self.alive.start) - } - - pub fn next(&mut self) -> Option { - let i = self.alive.next()?; - - // SAFETY: `i` is guaranteed to be a valid index for `self.data`. - unsafe { Some(self.data.get_unchecked(usize::from(i)).to_u8()) } - } - - pub fn next_back(&mut self) -> Option { - let i = self.alive.next_back()?; - - // SAFETY: `i` is guaranteed to be a valid index for `self.data`. - unsafe { Some(self.data.get_unchecked(usize::from(i)).to_u8()) } - } - - pub fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - self.alive.advance_by(n) - } - - pub fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - self.alive.advance_back_by(n) - } -} diff --git a/library/core/src/ffi/c_char.md b/library/core/src/ffi/c_char.md deleted file mode 100644 index b262a3663b3c1..0000000000000 --- a/library/core/src/ffi/c_char.md +++ /dev/null @@ -1,8 +0,0 @@ -Equivalent to C's `char` type. - -[C's `char` type] is completely unlike [Rust's `char` type]; while Rust's type represents a unicode scalar value, C's `char` type is just an ordinary integer. On modern architectures this type will always be either [`i8`] or [`u8`], as they use byte-addresses memory with 8-bit bytes. - -C chars are most commonly used to make C strings. Unlike Rust, where the length of a string is included alongside the string, C strings mark the end of a string with the character `'\0'`. See `CStr` for more information. - -[C's `char` type]: https://en.wikipedia.org/wiki/C_data_types#Basic_types -[Rust's `char` type]: char diff --git a/library/core/src/ffi/c_double.md b/library/core/src/ffi/c_double.md deleted file mode 100644 index d49e29b6e6e7f..0000000000000 --- a/library/core/src/ffi/c_double.md +++ /dev/null @@ -1,6 +0,0 @@ -Equivalent to C's `double` type. - -This type will almost always be [`f64`], which is guaranteed to be an [IEEE 754 double-precision float] in Rust. That said, the standard technically only guarantees that it be a floating-point number with at least the precision of a [`float`], and it may be `f32` or something entirely different from the IEEE-754 standard. - -[IEEE 754 double-precision float]: https://en.wikipedia.org/wiki/IEEE_754 -[`float`]: c_float diff --git a/library/core/src/ffi/c_float.md b/library/core/src/ffi/c_float.md deleted file mode 100644 index 36374ef436181..0000000000000 --- a/library/core/src/ffi/c_float.md +++ /dev/null @@ -1,5 +0,0 @@ -Equivalent to C's `float` type. - -This type will almost always be [`f32`], which is guaranteed to be an [IEEE 754 single-precision float] in Rust. That said, the standard technically only guarantees that it be a floating-point number, and it may have less precision than `f32` or not follow the IEEE-754 standard at all. - -[IEEE 754 single-precision float]: https://en.wikipedia.org/wiki/IEEE_754 diff --git a/library/core/src/ffi/c_int.md b/library/core/src/ffi/c_int.md deleted file mode 100644 index 8062ff2307a95..0000000000000 --- a/library/core/src/ffi/c_int.md +++ /dev/null @@ -1,5 +0,0 @@ -Equivalent to C's `signed int` (`int`) type. - -This type will almost always be [`i32`], but may differ on some esoteric systems. The C standard technically only requires that this type be a signed integer that is at least the size of a [`short`]; some systems define it as an [`i16`], for example. - -[`short`]: c_short diff --git a/library/core/src/ffi/c_long.md b/library/core/src/ffi/c_long.md deleted file mode 100644 index cc160783f78b7..0000000000000 --- a/library/core/src/ffi/c_long.md +++ /dev/null @@ -1,5 +0,0 @@ -Equivalent to C's `signed long` (`long`) type. - -This type will always be [`i32`] or [`i64`]. Most notably, many Linux-based systems assume an `i64`, but Windows assumes `i32`. The C standard technically only requires that this type be a signed integer that is at least 32 bits and at least the size of an [`int`], although in practice, no system would have a `long` that is neither an `i32` nor `i64`. - -[`int`]: c_int diff --git a/library/core/src/ffi/c_longlong.md b/library/core/src/ffi/c_longlong.md deleted file mode 100644 index 49c61bd61f4ad..0000000000000 --- a/library/core/src/ffi/c_longlong.md +++ /dev/null @@ -1,5 +0,0 @@ -Equivalent to C's `signed long long` (`long long`) type. - -This type will almost always be [`i64`], but may differ on some systems. The C standard technically only requires that this type be a signed integer that is at least 64 bits and at least the size of a [`long`], although in practice, no system would have a `long long` that is not an `i64`, as most systems do not have a standardised [`i128`] type. - -[`long`]: c_int diff --git a/library/core/src/ffi/c_schar.md b/library/core/src/ffi/c_schar.md deleted file mode 100644 index 69879c9f17f4d..0000000000000 --- a/library/core/src/ffi/c_schar.md +++ /dev/null @@ -1,5 +0,0 @@ -Equivalent to C's `signed char` type. - -This type will always be [`i8`], but is included for completeness. It is defined as being a signed integer the same size as a C [`char`]. - -[`char`]: c_char diff --git a/library/core/src/ffi/c_short.md b/library/core/src/ffi/c_short.md deleted file mode 100644 index 3d1e53d1325f3..0000000000000 --- a/library/core/src/ffi/c_short.md +++ /dev/null @@ -1,5 +0,0 @@ -Equivalent to C's `signed short` (`short`) type. - -This type will almost always be [`i16`], but may differ on some esoteric systems. The C standard technically only requires that this type be a signed integer with at least 16 bits; some systems may define it as `i32`, for example. - -[`char`]: c_char diff --git a/library/core/src/ffi/c_str.rs b/library/core/src/ffi/c_str.rs deleted file mode 100644 index 297f52e756bc6..0000000000000 --- a/library/core/src/ffi/c_str.rs +++ /dev/null @@ -1,827 +0,0 @@ -//! [`CStr`] and its related types. - -use crate::cmp::Ordering; -use crate::error::Error; -use crate::ffi::c_char; -use crate::fmt; -use crate::intrinsics; -use crate::iter::FusedIterator; -use crate::marker::PhantomData; -use crate::ops; -use crate::ptr::addr_of; -use crate::ptr::NonNull; -use crate::slice; -use crate::slice::memchr; -use crate::str; - -// FIXME: because this is doc(inline)d, we *have* to use intra-doc links because the actual link -// depends on where the item is being documented. however, since this is libcore, we can't -// actually reference libstd or liballoc in intra-doc links. so, the best we can do is remove the -// links to `CString` and `String` for now until a solution is developed - -/// Representation of a borrowed C string. -/// -/// This type represents a borrowed reference to a nul-terminated -/// array of bytes. It can be constructed safely from a &[[u8]] -/// slice, or unsafely from a raw `*const c_char`. It can be expressed as a -/// literal in the form `c"Hello world"`. -/// -/// The `CStr` can then be converted to a Rust &[str] by performing -/// UTF-8 validation, or into an owned `CString`. -/// -/// `&CStr` is to `CString` as &[str] is to `String`: the former -/// in each pair are borrowed references; the latter are owned -/// strings. -/// -/// Note that this structure does **not** have a guaranteed layout (the `repr(transparent)` -/// notwithstanding) and should not be placed in the signatures of FFI functions. -/// Instead, safe wrappers of FFI functions may leverage [`CStr::as_ptr`] and the unsafe -/// [`CStr::from_ptr`] constructor to provide a safe interface to other consumers. -/// -/// # Examples -/// -/// Inspecting a foreign C string: -/// -/// ``` -/// use std::ffi::CStr; -/// use std::os::raw::c_char; -/// -/// # /* Extern functions are awkward in doc comments - fake it instead -/// extern "C" { fn my_string() -> *const c_char; } -/// # */ unsafe extern "C" fn my_string() -> *const c_char { c"hello".as_ptr() } -/// -/// unsafe { -/// let slice = CStr::from_ptr(my_string()); -/// println!("string buffer size without nul terminator: {}", slice.to_bytes().len()); -/// } -/// ``` -/// -/// Passing a Rust-originating C string: -/// -/// ``` -/// use std::ffi::{CString, CStr}; -/// use std::os::raw::c_char; -/// -/// fn work(data: &CStr) { -/// # /* Extern functions are awkward in doc comments - fake it instead -/// extern "C" { fn work_with(data: *const c_char); } -/// # */ unsafe extern "C" fn work_with(s: *const c_char) {} -/// -/// unsafe { work_with(data.as_ptr()) } -/// } -/// -/// let s = CString::new("data data data data").expect("CString::new failed"); -/// work(&s); -/// ``` -/// -/// Converting a foreign C string into a Rust `String`: -/// -/// ``` -/// use std::ffi::CStr; -/// use std::os::raw::c_char; -/// -/// # /* Extern functions are awkward in doc comments - fake it instead -/// extern "C" { fn my_string() -> *const c_char; } -/// # */ unsafe extern "C" fn my_string() -> *const c_char { c"hello".as_ptr() } -/// -/// fn my_string_safe() -> String { -/// let cstr = unsafe { CStr::from_ptr(my_string()) }; -/// // Get copy-on-write Cow<'_, str>, then guarantee a freshly-owned String allocation -/// String::from_utf8_lossy(cstr.to_bytes()).to_string() -/// } -/// -/// println!("string: {}", my_string_safe()); -/// ``` -/// -/// [str]: prim@str "str" -#[derive(Hash)] -#[stable(feature = "core_c_str", since = "1.64.0")] -#[rustc_has_incoherent_inherent_impls] -#[lang = "CStr"] -// `fn from` in `impl From<&CStr> for Box` current implementation relies -// on `CStr` being layout-compatible with `[u8]`. -// However, `CStr` layout is considered an implementation detail and must not be relied upon. We -// want `repr(transparent)` but we don't want it to show up in rustdoc, so we hide it under -// `cfg(doc)`. This is an ad-hoc implementation of attribute privacy. -#[cfg_attr(not(doc), repr(transparent))] -#[allow(clippy::derived_hash_with_manual_eq)] -pub struct CStr { - // FIXME: this should not be represented with a DST slice but rather with - // just a raw `c_char` along with some form of marker to make - // this an unsized type. Essentially `sizeof(&CStr)` should be the - // same as `sizeof(&c_char)` but `CStr` should be an unsized type. - inner: [c_char], -} - -/// An error indicating that a nul byte was not in the expected position. -/// -/// The slice used to create a [`CStr`] must have one and only one nul byte, -/// positioned at the end. -/// -/// This error is created by the [`CStr::from_bytes_with_nul`] method. -/// See its documentation for more. -/// -/// # Examples -/// -/// ``` -/// use std::ffi::{CStr, FromBytesWithNulError}; -/// -/// let _: FromBytesWithNulError = CStr::from_bytes_with_nul(b"f\0oo").unwrap_err(); -/// ``` -#[derive(Clone, PartialEq, Eq, Debug)] -#[stable(feature = "core_c_str", since = "1.64.0")] -pub struct FromBytesWithNulError { - kind: FromBytesWithNulErrorKind, -} - -#[derive(Clone, PartialEq, Eq, Debug)] -enum FromBytesWithNulErrorKind { - InteriorNul(usize), - NotNulTerminated, -} - -// FIXME: const stability attributes should not be required here, I think -impl FromBytesWithNulError { - #[rustc_const_stable(feature = "const_cstr_methods", since = "1.72.0")] - const fn interior_nul(pos: usize) -> FromBytesWithNulError { - FromBytesWithNulError { kind: FromBytesWithNulErrorKind::InteriorNul(pos) } - } - #[rustc_const_stable(feature = "const_cstr_methods", since = "1.72.0")] - const fn not_nul_terminated() -> FromBytesWithNulError { - FromBytesWithNulError { kind: FromBytesWithNulErrorKind::NotNulTerminated } - } -} - -#[stable(feature = "frombyteswithnulerror_impls", since = "1.17.0")] -impl Error for FromBytesWithNulError { - #[allow(deprecated)] - fn description(&self) -> &str { - match self.kind { - FromBytesWithNulErrorKind::InteriorNul(..) => { - "data provided contains an interior nul byte" - } - FromBytesWithNulErrorKind::NotNulTerminated => "data provided is not nul terminated", - } - } -} - -/// An error indicating that no nul byte was present. -/// -/// A slice used to create a [`CStr`] must contain a nul byte somewhere -/// within the slice. -/// -/// This error is created by the [`CStr::from_bytes_until_nul`] method. -/// -#[derive(Clone, PartialEq, Eq, Debug)] -#[stable(feature = "cstr_from_bytes_until_nul", since = "1.69.0")] -pub struct FromBytesUntilNulError(()); - -#[stable(feature = "cstr_from_bytes_until_nul", since = "1.69.0")] -impl fmt::Display for FromBytesUntilNulError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "data provided does not contain a nul") - } -} - -#[stable(feature = "cstr_debug", since = "1.3.0")] -impl fmt::Debug for CStr { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "\"{}\"", self.to_bytes().escape_ascii()) - } -} - -#[stable(feature = "cstr_default", since = "1.10.0")] -impl Default for &CStr { - #[inline] - fn default() -> Self { - const SLICE: &[c_char] = &[0]; - // SAFETY: `SLICE` is indeed pointing to a valid nul-terminated string. - unsafe { CStr::from_ptr(SLICE.as_ptr()) } - } -} - -#[stable(feature = "frombyteswithnulerror_impls", since = "1.17.0")] -impl fmt::Display for FromBytesWithNulError { - #[allow(deprecated, deprecated_in_future)] - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str(self.description())?; - if let FromBytesWithNulErrorKind::InteriorNul(pos) = self.kind { - write!(f, " at byte pos {pos}")?; - } - Ok(()) - } -} - -impl CStr { - /// Wraps a raw C string with a safe C string wrapper. - /// - /// This function will wrap the provided `ptr` with a `CStr` wrapper, which - /// allows inspection and interoperation of non-owned C strings. The total - /// size of the terminated buffer must be smaller than [`isize::MAX`] **bytes** - /// in memory (a restriction from [`slice::from_raw_parts`]). - /// - /// # Safety - /// - /// * The memory pointed to by `ptr` must contain a valid nul terminator at the - /// end of the string. - /// - /// * `ptr` must be [valid] for reads of bytes up to and including the nul terminator. - /// This means in particular: - /// - /// * The entire memory range of this `CStr` must be contained within a single allocated object! - /// * `ptr` must be non-null even for a zero-length cstr. - /// - /// * The memory referenced by the returned `CStr` must not be mutated for - /// the duration of lifetime `'a`. - /// - /// * The nul terminator must be within `isize::MAX` from `ptr` - /// - /// > **Note**: This operation is intended to be a 0-cost cast but it is - /// > currently implemented with an up-front calculation of the length of - /// > the string. This is not guaranteed to always be the case. - /// - /// # Caveat - /// - /// The lifetime for the returned slice is inferred from its usage. To prevent accidental misuse, - /// it's suggested to tie the lifetime to whichever source lifetime is safe in the context, - /// such as by providing a helper function taking the lifetime of a host value for the slice, - /// or by explicit annotation. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::{c_char, CStr}; - /// - /// fn my_string() -> *const c_char { - /// c"hello".as_ptr() - /// } - /// - /// unsafe { - /// let slice = CStr::from_ptr(my_string()); - /// assert_eq!(slice.to_str().unwrap(), "hello"); - /// } - /// ``` - /// - /// ``` - /// #![feature(const_cstr_from_ptr)] - /// - /// use std::ffi::{c_char, CStr}; - /// - /// const HELLO_PTR: *const c_char = { - /// const BYTES: &[u8] = b"Hello, world!\0"; - /// BYTES.as_ptr().cast() - /// }; - /// const HELLO: &CStr = unsafe { CStr::from_ptr(HELLO_PTR) }; - /// - /// assert_eq!(c"Hello, world!", HELLO); - /// ``` - /// - /// [valid]: core::ptr#safety - #[inline] // inline is necessary for codegen to see strlen. - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_cstr_from_ptr", issue = "113219")] - pub const unsafe fn from_ptr<'a>(ptr: *const c_char) -> &'a CStr { - // SAFETY: The caller has provided a pointer that points to a valid C - // string with a NUL terminator less than `isize::MAX` from `ptr`. - let len = unsafe { const_strlen(ptr) }; - - // SAFETY: The caller has provided a valid pointer with length less than - // `isize::MAX`, so `from_raw_parts` is safe. The content remains valid - // and doesn't change for the lifetime of the returned `CStr`. This - // means the call to `from_bytes_with_nul_unchecked` is correct. - // - // The cast from c_char to u8 is ok because a c_char is always one byte. - unsafe { Self::from_bytes_with_nul_unchecked(slice::from_raw_parts(ptr.cast(), len + 1)) } - } - - /// Creates a C string wrapper from a byte slice with any number of nuls. - /// - /// This method will create a `CStr` from any byte slice that contains at - /// least one nul byte. Unlike with [`CStr::from_bytes_with_nul`], the caller - /// does not need to know where the nul byte is located. - /// - /// If the first byte is a nul character, this method will return an - /// empty `CStr`. If multiple nul characters are present, the `CStr` will - /// end at the first one. - /// - /// If the slice only has a single nul byte at the end, this method is - /// equivalent to [`CStr::from_bytes_with_nul`]. - /// - /// # Examples - /// ``` - /// use std::ffi::CStr; - /// - /// let mut buffer = [0u8; 16]; - /// unsafe { - /// // Here we might call an unsafe C function that writes a string - /// // into the buffer. - /// let buf_ptr = buffer.as_mut_ptr(); - /// buf_ptr.write_bytes(b'A', 8); - /// } - /// // Attempt to extract a C nul-terminated string from the buffer. - /// let c_str = CStr::from_bytes_until_nul(&buffer[..]).unwrap(); - /// assert_eq!(c_str.to_str().unwrap(), "AAAAAAAA"); - /// ``` - /// - #[stable(feature = "cstr_from_bytes_until_nul", since = "1.69.0")] - #[rustc_const_stable(feature = "cstr_from_bytes_until_nul", since = "1.69.0")] - pub const fn from_bytes_until_nul(bytes: &[u8]) -> Result<&CStr, FromBytesUntilNulError> { - let nul_pos = memchr::memchr(0, bytes); - match nul_pos { - Some(nul_pos) => { - // FIXME(const-hack) replace with range index - // SAFETY: nul_pos + 1 <= bytes.len() - let subslice = unsafe { crate::slice::from_raw_parts(bytes.as_ptr(), nul_pos + 1) }; - // SAFETY: We know there is a nul byte at nul_pos, so this slice - // (ending at the nul byte) is a well-formed C string. - Ok(unsafe { CStr::from_bytes_with_nul_unchecked(subslice) }) - } - None => Err(FromBytesUntilNulError(())), - } - } - - /// Creates a C string wrapper from a byte slice with exactly one nul - /// terminator. - /// - /// This function will cast the provided `bytes` to a `CStr` - /// wrapper after ensuring that the byte slice is nul-terminated - /// and does not contain any interior nul bytes. - /// - /// If the nul byte may not be at the end, - /// [`CStr::from_bytes_until_nul`] can be used instead. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::CStr; - /// - /// let cstr = CStr::from_bytes_with_nul(b"hello\0"); - /// assert!(cstr.is_ok()); - /// ``` - /// - /// Creating a `CStr` without a trailing nul terminator is an error: - /// - /// ``` - /// use std::ffi::CStr; - /// - /// let cstr = CStr::from_bytes_with_nul(b"hello"); - /// assert!(cstr.is_err()); - /// ``` - /// - /// Creating a `CStr` with an interior nul byte is an error: - /// - /// ``` - /// use std::ffi::CStr; - /// - /// let cstr = CStr::from_bytes_with_nul(b"he\0llo\0"); - /// assert!(cstr.is_err()); - /// ``` - #[stable(feature = "cstr_from_bytes", since = "1.10.0")] - #[rustc_const_stable(feature = "const_cstr_methods", since = "1.72.0")] - pub const fn from_bytes_with_nul(bytes: &[u8]) -> Result<&Self, FromBytesWithNulError> { - let nul_pos = memchr::memchr(0, bytes); - match nul_pos { - Some(nul_pos) if nul_pos + 1 == bytes.len() => { - // SAFETY: We know there is only one nul byte, at the end - // of the byte slice. - Ok(unsafe { Self::from_bytes_with_nul_unchecked(bytes) }) - } - Some(nul_pos) => Err(FromBytesWithNulError::interior_nul(nul_pos)), - None => Err(FromBytesWithNulError::not_nul_terminated()), - } - } - - /// Unsafely creates a C string wrapper from a byte slice. - /// - /// This function will cast the provided `bytes` to a `CStr` wrapper without - /// performing any sanity checks. - /// - /// # Safety - /// The provided slice **must** be nul-terminated and not contain any interior - /// nul bytes. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::{CStr, CString}; - /// - /// unsafe { - /// let cstring = CString::new("hello").expect("CString::new failed"); - /// let cstr = CStr::from_bytes_with_nul_unchecked(cstring.to_bytes_with_nul()); - /// assert_eq!(cstr, &*cstring); - /// } - /// ``` - #[inline] - #[must_use] - #[stable(feature = "cstr_from_bytes", since = "1.10.0")] - #[rustc_const_stable(feature = "const_cstr_unchecked", since = "1.59.0")] - #[rustc_allow_const_fn_unstable(const_eval_select)] - pub const unsafe fn from_bytes_with_nul_unchecked(bytes: &[u8]) -> &CStr { - #[inline] - fn rt_impl(bytes: &[u8]) -> &CStr { - // Chance at catching some UB at runtime with debug builds. - debug_assert!(!bytes.is_empty() && bytes[bytes.len() - 1] == 0); - - // SAFETY: Casting to CStr is safe because its internal representation - // is a [u8] too (safe only inside std). - // Dereferencing the obtained pointer is safe because it comes from a - // reference. Making a reference is then safe because its lifetime - // is bound by the lifetime of the given `bytes`. - unsafe { &*(bytes as *const [u8] as *const CStr) } - } - - const fn const_impl(bytes: &[u8]) -> &CStr { - // Saturating so that an empty slice panics in the assert with a good - // message, not here due to underflow. - let mut i = bytes.len().saturating_sub(1); - assert!(!bytes.is_empty() && bytes[i] == 0, "input was not nul-terminated"); - - // Ending nul byte exists, skip to the rest. - while i != 0 { - i -= 1; - let byte = bytes[i]; - assert!(byte != 0, "input contained interior nul"); - } - - // SAFETY: See `rt_impl` cast. - unsafe { &*(bytes as *const [u8] as *const CStr) } - } - - intrinsics::const_eval_select((bytes,), const_impl, rt_impl) - } - - /// Returns the inner pointer to this C string. - /// - /// The returned pointer will be valid for as long as `self` is, and points - /// to a contiguous region of memory terminated with a 0 byte to represent - /// the end of the string. - /// - /// The type of the returned pointer is - /// [`*const c_char`][crate::ffi::c_char], and whether it's - /// an alias for `*const i8` or `*const u8` is platform-specific. - /// - /// **WARNING** - /// - /// The returned pointer is read-only; writing to it (including passing it - /// to C code that writes to it) causes undefined behavior. - /// - /// It is your responsibility to make sure that the underlying memory is not - /// freed too early. For example, the following code will cause undefined - /// behavior when `ptr` is used inside the `unsafe` block: - /// - /// ```no_run - /// # #![allow(unused_must_use)] #![allow(temporary_cstring_as_ptr)] - /// use std::ffi::CString; - /// - /// // Do not do this: - /// let ptr = CString::new("Hello").expect("CString::new failed").as_ptr(); - /// unsafe { - /// // `ptr` is dangling - /// *ptr; - /// } - /// ``` - /// - /// This happens because the pointer returned by `as_ptr` does not carry any - /// lifetime information and the `CString` is deallocated immediately after - /// the `CString::new("Hello").expect("CString::new failed").as_ptr()` - /// expression is evaluated. - /// To fix the problem, bind the `CString` to a local variable: - /// - /// ```no_run - /// # #![allow(unused_must_use)] - /// use std::ffi::CString; - /// - /// let hello = CString::new("Hello").expect("CString::new failed"); - /// let ptr = hello.as_ptr(); - /// unsafe { - /// // `ptr` is valid because `hello` is in scope - /// *ptr; - /// } - /// ``` - /// - /// This way, the lifetime of the `CString` in `hello` encompasses - /// the lifetime of `ptr` and the `unsafe` block. - #[inline] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_str_as_ptr", since = "1.32.0")] - #[rustc_never_returns_null_ptr] - pub const fn as_ptr(&self) -> *const c_char { - self.inner.as_ptr() - } - - /// We could eventually expose this publicly, if we wanted. - #[inline] - #[must_use] - const fn as_non_null_ptr(&self) -> NonNull { - NonNull::from(&self.inner).as_non_null_ptr() - } - - /// Returns the length of `self`. Like C's `strlen`, this does not include the nul terminator. - /// - /// > **Note**: This method is currently implemented as a constant-time - /// > cast, but it is planned to alter its definition in the future to - /// > perform the length calculation whenever this method is called. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::CStr; - /// - /// let cstr = CStr::from_bytes_with_nul(b"foo\0").unwrap(); - /// assert_eq!(cstr.count_bytes(), 3); - /// - /// let cstr = CStr::from_bytes_with_nul(b"\0").unwrap(); - /// assert_eq!(cstr.count_bytes(), 0); - /// ``` - #[inline] - #[must_use] - #[doc(alias("len", "strlen"))] - #[stable(feature = "cstr_count_bytes", since = "1.79.0")] - #[rustc_const_unstable(feature = "const_cstr_from_ptr", issue = "113219")] - pub const fn count_bytes(&self) -> usize { - self.inner.len() - 1 - } - - /// Returns `true` if `self.to_bytes()` has a length of 0. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::CStr; - /// # use std::ffi::FromBytesWithNulError; - /// - /// # fn main() { test().unwrap(); } - /// # fn test() -> Result<(), FromBytesWithNulError> { - /// let cstr = CStr::from_bytes_with_nul(b"foo\0")?; - /// assert!(!cstr.is_empty()); - /// - /// let empty_cstr = CStr::from_bytes_with_nul(b"\0")?; - /// assert!(empty_cstr.is_empty()); - /// assert!(c"".is_empty()); - /// # Ok(()) - /// # } - /// ``` - #[inline] - #[stable(feature = "cstr_is_empty", since = "1.71.0")] - #[rustc_const_stable(feature = "cstr_is_empty", since = "1.71.0")] - pub const fn is_empty(&self) -> bool { - // SAFETY: We know there is at least one byte; for empty strings it - // is the NUL terminator. - // FIXME(const-hack): use get_unchecked - unsafe { *self.inner.as_ptr() == 0 } - } - - /// Converts this C string to a byte slice. - /// - /// The returned slice will **not** contain the trailing nul terminator that this C - /// string has. - /// - /// > **Note**: This method is currently implemented as a constant-time - /// > cast, but it is planned to alter its definition in the future to - /// > perform the length calculation whenever this method is called. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::CStr; - /// - /// let cstr = CStr::from_bytes_with_nul(b"foo\0").expect("CStr::from_bytes_with_nul failed"); - /// assert_eq!(cstr.to_bytes(), b"foo"); - /// ``` - #[inline] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_cstr_methods", since = "1.72.0")] - pub const fn to_bytes(&self) -> &[u8] { - let bytes = self.to_bytes_with_nul(); - // FIXME(const-hack) replace with range index - // SAFETY: to_bytes_with_nul returns slice with length at least 1 - unsafe { slice::from_raw_parts(bytes.as_ptr(), bytes.len() - 1) } - } - - /// Converts this C string to a byte slice containing the trailing 0 byte. - /// - /// This function is the equivalent of [`CStr::to_bytes`] except that it - /// will retain the trailing nul terminator instead of chopping it off. - /// - /// > **Note**: This method is currently implemented as a 0-cost cast, but - /// > it is planned to alter its definition in the future to perform the - /// > length calculation whenever this method is called. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::CStr; - /// - /// let cstr = CStr::from_bytes_with_nul(b"foo\0").expect("CStr::from_bytes_with_nul failed"); - /// assert_eq!(cstr.to_bytes_with_nul(), b"foo\0"); - /// ``` - #[inline] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_cstr_methods", since = "1.72.0")] - pub const fn to_bytes_with_nul(&self) -> &[u8] { - // SAFETY: Transmuting a slice of `c_char`s to a slice of `u8`s - // is safe on all supported targets. - unsafe { &*(addr_of!(self.inner) as *const [u8]) } - } - - /// Iterates over the bytes in this C string. - /// - /// The returned iterator will **not** contain the trailing nul terminator - /// that this C string has. - /// - /// # Examples - /// - /// ``` - /// #![feature(cstr_bytes)] - /// use std::ffi::CStr; - /// - /// let cstr = CStr::from_bytes_with_nul(b"foo\0").expect("CStr::from_bytes_with_nul failed"); - /// assert!(cstr.bytes().eq(*b"foo")); - /// ``` - #[inline] - #[unstable(feature = "cstr_bytes", issue = "112115")] - pub fn bytes(&self) -> Bytes<'_> { - Bytes::new(self) - } - - /// Yields a &[str] slice if the `CStr` contains valid UTF-8. - /// - /// If the contents of the `CStr` are valid UTF-8 data, this - /// function will return the corresponding &[str] slice. Otherwise, - /// it will return an error with details of where UTF-8 validation failed. - /// - /// [str]: prim@str "str" - /// - /// # Examples - /// - /// ``` - /// use std::ffi::CStr; - /// - /// let cstr = CStr::from_bytes_with_nul(b"foo\0").expect("CStr::from_bytes_with_nul failed"); - /// assert_eq!(cstr.to_str(), Ok("foo")); - /// ``` - #[stable(feature = "cstr_to_str", since = "1.4.0")] - #[rustc_const_stable(feature = "const_cstr_methods", since = "1.72.0")] - pub const fn to_str(&self) -> Result<&str, str::Utf8Error> { - // N.B., when `CStr` is changed to perform the length check in `.to_bytes()` - // instead of in `from_ptr()`, it may be worth considering if this should - // be rewritten to do the UTF-8 check inline with the length calculation - // instead of doing it afterwards. - str::from_utf8(self.to_bytes()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for CStr { - #[inline] - fn eq(&self, other: &CStr) -> bool { - self.to_bytes().eq(other.to_bytes()) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl Eq for CStr {} -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialOrd for CStr { - #[inline] - fn partial_cmp(&self, other: &CStr) -> Option { - self.to_bytes().partial_cmp(&other.to_bytes()) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for CStr { - #[inline] - fn cmp(&self, other: &CStr) -> Ordering { - self.to_bytes().cmp(&other.to_bytes()) - } -} - -#[stable(feature = "cstr_range_from", since = "1.47.0")] -impl ops::Index> for CStr { - type Output = CStr; - - #[inline] - fn index(&self, index: ops::RangeFrom) -> &CStr { - let bytes = self.to_bytes_with_nul(); - // we need to manually check the starting index to account for the null - // byte, since otherwise we could get an empty string that doesn't end - // in a null. - if index.start < bytes.len() { - // SAFETY: Non-empty tail of a valid `CStr` is still a valid `CStr`. - unsafe { CStr::from_bytes_with_nul_unchecked(&bytes[index.start..]) } - } else { - panic!( - "index out of bounds: the len is {} but the index is {}", - bytes.len(), - index.start - ); - } - } -} - -#[stable(feature = "cstring_asref", since = "1.7.0")] -impl AsRef for CStr { - #[inline] - fn as_ref(&self) -> &CStr { - self - } -} - -/// Calculate the length of a nul-terminated string. Defers to C's `strlen` when possible. -/// -/// # Safety -/// -/// The pointer must point to a valid buffer that contains a NUL terminator. The NUL must be -/// located within `isize::MAX` from `ptr`. -#[inline] -const unsafe fn const_strlen(ptr: *const c_char) -> usize { - const fn strlen_ct(s: *const c_char) -> usize { - let mut len = 0; - - // SAFETY: Outer caller has provided a pointer to a valid C string. - while unsafe { *s.add(len) } != 0 { - len += 1; - } - - len - } - - #[inline] - fn strlen_rt(s: *const c_char) -> usize { - extern "C" { - /// Provided by libc or compiler_builtins. - fn strlen(s: *const c_char) -> usize; - } - - // SAFETY: Outer caller has provided a pointer to a valid C string. - unsafe { strlen(s) } - } - - intrinsics::const_eval_select((ptr,), strlen_ct, strlen_rt) -} - -/// An iterator over the bytes of a [`CStr`], without the nul terminator. -/// -/// This struct is created by the [`bytes`] method on [`CStr`]. -/// See its documentation for more. -/// -/// [`bytes`]: CStr::bytes -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[unstable(feature = "cstr_bytes", issue = "112115")] -#[derive(Clone, Debug)] -pub struct Bytes<'a> { - // since we know the string is nul-terminated, we only need one pointer - ptr: NonNull, - phantom: PhantomData<&'a u8>, -} -impl<'a> Bytes<'a> { - #[inline] - fn new(s: &'a CStr) -> Self { - Self { ptr: s.as_non_null_ptr().cast(), phantom: PhantomData } - } - - #[inline] - fn is_empty(&self) -> bool { - // SAFETY: We uphold that the pointer is always valid to dereference - // by starting with a valid C string and then never incrementing beyond - // the nul terminator. - unsafe { self.ptr.read() == 0 } - } -} - -#[unstable(feature = "cstr_bytes", issue = "112115")] -impl Iterator for Bytes<'_> { - type Item = u8; - - #[inline] - fn next(&mut self) -> Option { - // SAFETY: We only choose a pointer from a valid C string, which must - // be non-null and contain at least one value. Since we always stop at - // the nul terminator, which is guaranteed to exist, we can assume that - // the pointer is non-null and valid. This lets us safely dereference - // it and assume that adding 1 will create a new, non-null, valid - // pointer. - unsafe { - let ret = self.ptr.read(); - if ret == 0 { - None - } else { - self.ptr = self.ptr.offset(1); - Some(ret) - } - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - if self.is_empty() { (0, Some(0)) } else { (1, None) } - } -} - -#[unstable(feature = "cstr_bytes", issue = "112115")] -impl FusedIterator for Bytes<'_> {} diff --git a/library/core/src/ffi/c_uchar.md b/library/core/src/ffi/c_uchar.md deleted file mode 100644 index b633bb7f8dacf..0000000000000 --- a/library/core/src/ffi/c_uchar.md +++ /dev/null @@ -1,5 +0,0 @@ -Equivalent to C's `unsigned char` type. - -This type will always be [`u8`], but is included for completeness. It is defined as being an unsigned integer the same size as a C [`char`]. - -[`char`]: c_char diff --git a/library/core/src/ffi/c_uint.md b/library/core/src/ffi/c_uint.md deleted file mode 100644 index f3abea35937ab..0000000000000 --- a/library/core/src/ffi/c_uint.md +++ /dev/null @@ -1,5 +0,0 @@ -Equivalent to C's `unsigned int` type. - -This type will almost always be [`u32`], but may differ on some esoteric systems. The C standard technically only requires that this type be an unsigned integer with the same size as an [`int`]; some systems define it as a [`u16`], for example. - -[`int`]: c_int diff --git a/library/core/src/ffi/c_ulong.md b/library/core/src/ffi/c_ulong.md deleted file mode 100644 index 4ab304e657773..0000000000000 --- a/library/core/src/ffi/c_ulong.md +++ /dev/null @@ -1,5 +0,0 @@ -Equivalent to C's `unsigned long` type. - -This type will always be [`u32`] or [`u64`]. Most notably, many Linux-based systems assume an `u64`, but Windows assumes `u32`. The C standard technically only requires that this type be an unsigned integer with the size of a [`long`], although in practice, no system would have a `ulong` that is neither a `u32` nor `u64`. - -[`long`]: c_long diff --git a/library/core/src/ffi/c_ulonglong.md b/library/core/src/ffi/c_ulonglong.md deleted file mode 100644 index a27d70e17537d..0000000000000 --- a/library/core/src/ffi/c_ulonglong.md +++ /dev/null @@ -1,5 +0,0 @@ -Equivalent to C's `unsigned long long` type. - -This type will almost always be [`u64`], but may differ on some systems. The C standard technically only requires that this type be an unsigned integer with the size of a [`long long`], although in practice, no system would have a `long long` that is not a `u64`, as most systems do not have a standardised [`u128`] type. - -[`long long`]: c_longlong diff --git a/library/core/src/ffi/c_ushort.md b/library/core/src/ffi/c_ushort.md deleted file mode 100644 index 6928e51b352c8..0000000000000 --- a/library/core/src/ffi/c_ushort.md +++ /dev/null @@ -1,5 +0,0 @@ -Equivalent to C's `unsigned short` type. - -This type will almost always be [`u16`], but may differ on some esoteric systems. The C standard technically only requires that this type be an unsigned integer with the same size as a [`short`]. - -[`short`]: c_short diff --git a/library/core/src/ffi/c_void.md b/library/core/src/ffi/c_void.md deleted file mode 100644 index ee7403aa04099..0000000000000 --- a/library/core/src/ffi/c_void.md +++ /dev/null @@ -1,16 +0,0 @@ -Equivalent to C's `void` type when used as a [pointer]. - -In essence, `*const c_void` is equivalent to C's `const void*` -and `*mut c_void` is equivalent to C's `void*`. That said, this is -*not* the same as C's `void` return type, which is Rust's `()` type. - -To model pointers to opaque types in FFI, until `extern type` is -stabilized, it is recommended to use a newtype wrapper around an empty -byte array. See the [Nomicon] for details. - -One could use `std::os::raw::c_void` if they want to support old Rust -compiler down to 1.1.0. After Rust 1.30.0, it was re-exported by -this definition. For more information, please read [RFC 2521]. - -[Nomicon]: https://doc.rust-lang.org/nomicon/ffi.html#representing-opaque-structs -[RFC 2521]: https://github.com/rust-lang/rfcs/blob/master/text/2521-c_void-reunification.md diff --git a/library/core/src/ffi/mod.rs b/library/core/src/ffi/mod.rs deleted file mode 100644 index 27dacbb23d958..0000000000000 --- a/library/core/src/ffi/mod.rs +++ /dev/null @@ -1,612 +0,0 @@ -//! Platform-specific types, as defined by C. -//! -//! Code that interacts via FFI will almost certainly be using the -//! base types provided by C, which aren't nearly as nicely defined -//! as Rust's primitive types. This module provides types which will -//! match those defined by C, so that code that interacts with C will -//! refer to the correct types. - -#![stable(feature = "core_ffi", since = "1.30.0")] -#![allow(non_camel_case_types)] - -use crate::fmt; -use crate::marker::PhantomData; -use crate::ops::{Deref, DerefMut}; - -#[doc(no_inline)] -#[stable(feature = "core_c_str", since = "1.64.0")] -pub use self::c_str::FromBytesWithNulError; - -#[doc(no_inline)] -#[stable(feature = "cstr_from_bytes_until_nul", since = "1.69.0")] -pub use self::c_str::FromBytesUntilNulError; - -#[doc(inline)] -#[stable(feature = "core_c_str", since = "1.64.0")] -pub use self::c_str::CStr; - -#[unstable(feature = "c_str_module", issue = "112134")] -pub mod c_str; - -macro_rules! type_alias { - { - $Docfile:tt, $Alias:ident = $Real:ty; - $( $Cfg:tt )* - } => { - #[doc = include_str!($Docfile)] - $( $Cfg )* - #[stable(feature = "core_ffi_c", since = "1.64.0")] - pub type $Alias = $Real; - } -} - -type_alias! { "c_char.md", c_char = c_char_definition::c_char; #[doc(cfg(all()))] } - -type_alias! { "c_schar.md", c_schar = i8; } -type_alias! { "c_uchar.md", c_uchar = u8; } -type_alias! { "c_short.md", c_short = i16; } -type_alias! { "c_ushort.md", c_ushort = u16; } - -type_alias! { "c_int.md", c_int = c_int_definition::c_int; #[doc(cfg(all()))] } -type_alias! { "c_uint.md", c_uint = c_int_definition::c_uint; #[doc(cfg(all()))] } - -type_alias! { "c_long.md", c_long = c_long_definition::c_long; #[doc(cfg(all()))] } -type_alias! { "c_ulong.md", c_ulong = c_long_definition::c_ulong; #[doc(cfg(all()))] } - -type_alias! { "c_longlong.md", c_longlong = i64; } -type_alias! { "c_ulonglong.md", c_ulonglong = u64; } - -type_alias! { "c_float.md", c_float = f32; } -type_alias! { "c_double.md", c_double = f64; } - -/// Equivalent to C's `size_t` type, from `stddef.h` (or `cstddef` for C++). -/// -/// This type is currently always [`usize`], however in the future there may be -/// platforms where this is not the case. -#[unstable(feature = "c_size_t", issue = "88345")] -pub type c_size_t = usize; - -/// Equivalent to C's `ptrdiff_t` type, from `stddef.h` (or `cstddef` for C++). -/// -/// This type is currently always [`isize`], however in the future there may be -/// platforms where this is not the case. -#[unstable(feature = "c_size_t", issue = "88345")] -pub type c_ptrdiff_t = isize; - -/// Equivalent to C's `ssize_t` (on POSIX) or `SSIZE_T` (on Windows) type. -/// -/// This type is currently always [`isize`], however in the future there may be -/// platforms where this is not the case. -#[unstable(feature = "c_size_t", issue = "88345")] -pub type c_ssize_t = isize; - -mod c_char_definition { - cfg_if! { - // These are the targets on which c_char is unsigned. - if #[cfg(any( - all( - target_os = "linux", - any( - target_arch = "aarch64", - target_arch = "arm", - target_arch = "hexagon", - target_arch = "powerpc", - target_arch = "powerpc64", - target_arch = "s390x", - target_arch = "riscv64", - target_arch = "riscv32", - target_arch = "csky" - ) - ), - all(target_os = "android", any(target_arch = "aarch64", target_arch = "arm")), - all(target_os = "l4re", target_arch = "x86_64"), - all( - any(target_os = "freebsd", target_os = "openbsd"), - any( - target_arch = "aarch64", - target_arch = "arm", - target_arch = "powerpc", - target_arch = "powerpc64", - target_arch = "riscv64" - ) - ), - all( - target_os = "netbsd", - any( - target_arch = "aarch64", - target_arch = "arm", - target_arch = "powerpc", - target_arch = "riscv64" - ) - ), - all( - target_os = "vxworks", - any( - target_arch = "aarch64", - target_arch = "arm", - target_arch = "powerpc64", - target_arch = "powerpc" - ) - ), - all( - target_os = "fuchsia", - any(target_arch = "aarch64", target_arch = "riscv64") - ), - all(target_os = "nto", target_arch = "aarch64"), - target_os = "horizon" - ))] { - pub type c_char = u8; - } else { - // On every other target, c_char is signed. - pub type c_char = i8; - } - } -} - -mod c_int_definition { - cfg_if! { - if #[cfg(any(target_arch = "avr", target_arch = "msp430"))] { - pub type c_int = i16; - pub type c_uint = u16; - } else { - pub type c_int = i32; - pub type c_uint = u32; - } - } -} - -mod c_long_definition { - cfg_if! { - if #[cfg(all(target_pointer_width = "64", not(windows)))] { - pub type c_long = i64; - pub type c_ulong = u64; - } else { - // The minimal size of `long` in the C standard is 32 bits - pub type c_long = i32; - pub type c_ulong = u32; - } - } -} - -// N.B., for LLVM to recognize the void pointer type and by extension -// functions like malloc(), we need to have it represented as i8* in -// LLVM bitcode. The enum used here ensures this and prevents misuse -// of the "raw" type by only having private variants. We need two -// variants, because the compiler complains about the repr attribute -// otherwise and we need at least one variant as otherwise the enum -// would be uninhabited and at least dereferencing such pointers would -// be UB. -#[doc = include_str!("c_void.md")] -#[lang = "c_void"] -#[cfg_attr(not(doc), repr(u8))] // work around https://github.com/rust-lang/rust/issues/90435 -#[stable(feature = "core_c_void", since = "1.30.0")] -pub enum c_void { - #[unstable( - feature = "c_void_variant", - reason = "temporary implementation detail", - issue = "none" - )] - #[doc(hidden)] - __variant1, - #[unstable( - feature = "c_void_variant", - reason = "temporary implementation detail", - issue = "none" - )] - #[doc(hidden)] - __variant2, -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for c_void { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("c_void").finish() - } -} - -/// Basic implementation of a `va_list`. -// The name is WIP, using `VaListImpl` for now. -#[cfg(any( - all( - not(target_arch = "aarch64"), - not(target_arch = "powerpc"), - not(target_arch = "s390x"), - not(target_arch = "x86_64") - ), - all(target_arch = "aarch64", target_vendor = "apple"), - target_family = "wasm", - target_os = "uefi", - windows, -))] -#[cfg_attr(not(doc), repr(transparent))] // work around https://github.com/rust-lang/rust/issues/90435 -#[unstable( - feature = "c_variadic", - reason = "the `c_variadic` feature has not been properly tested on \ - all supported platforms", - issue = "44930" -)] -#[lang = "va_list"] -pub struct VaListImpl<'f> { - ptr: *mut c_void, - - // Invariant over `'f`, so each `VaListImpl<'f>` object is tied to - // the region of the function it's defined in - _marker: PhantomData<&'f mut &'f c_void>, -} - -#[cfg(any( - all( - not(target_arch = "aarch64"), - not(target_arch = "powerpc"), - not(target_arch = "s390x"), - not(target_arch = "x86_64") - ), - all(target_arch = "aarch64", target_vendor = "apple"), - target_family = "wasm", - target_os = "uefi", - windows, -))] -#[unstable( - feature = "c_variadic", - reason = "the `c_variadic` feature has not been properly tested on \ - all supported platforms", - issue = "44930" -)] -impl<'f> fmt::Debug for VaListImpl<'f> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "va_list* {:p}", self.ptr) - } -} - -/// AArch64 ABI implementation of a `va_list`. See the -/// [AArch64 Procedure Call Standard] for more details. -/// -/// [AArch64 Procedure Call Standard]: -/// http://infocenter.arm.com/help/topic/com.arm.doc.ihi0055b/IHI0055B_aapcs64.pdf -#[cfg(all( - target_arch = "aarch64", - not(target_vendor = "apple"), - not(target_os = "uefi"), - not(windows), -))] -#[cfg_attr(not(doc), repr(C))] // work around https://github.com/rust-lang/rust/issues/66401 -#[derive(Debug)] -#[unstable( - feature = "c_variadic", - reason = "the `c_variadic` feature has not been properly tested on \ - all supported platforms", - issue = "44930" -)] -#[lang = "va_list"] -pub struct VaListImpl<'f> { - stack: *mut c_void, - gr_top: *mut c_void, - vr_top: *mut c_void, - gr_offs: i32, - vr_offs: i32, - _marker: PhantomData<&'f mut &'f c_void>, -} - -/// PowerPC ABI implementation of a `va_list`. -#[cfg(all(target_arch = "powerpc", not(target_os = "uefi"), not(windows)))] -#[cfg_attr(not(doc), repr(C))] // work around https://github.com/rust-lang/rust/issues/66401 -#[derive(Debug)] -#[unstable( - feature = "c_variadic", - reason = "the `c_variadic` feature has not been properly tested on \ - all supported platforms", - issue = "44930" -)] -#[lang = "va_list"] -pub struct VaListImpl<'f> { - gpr: u8, - fpr: u8, - reserved: u16, - overflow_arg_area: *mut c_void, - reg_save_area: *mut c_void, - _marker: PhantomData<&'f mut &'f c_void>, -} - -/// s390x ABI implementation of a `va_list`. -#[cfg(target_arch = "s390x")] -#[cfg_attr(not(doc), repr(C))] // work around https://github.com/rust-lang/rust/issues/66401 -#[derive(Debug)] -#[unstable( - feature = "c_variadic", - reason = "the `c_variadic` feature has not been properly tested on \ - all supported platforms", - issue = "44930" -)] -#[lang = "va_list"] -pub struct VaListImpl<'f> { - gpr: i64, - fpr: i64, - overflow_arg_area: *mut c_void, - reg_save_area: *mut c_void, - _marker: PhantomData<&'f mut &'f c_void>, -} - -/// x86_64 ABI implementation of a `va_list`. -#[cfg(all(target_arch = "x86_64", not(target_os = "uefi"), not(windows)))] -#[cfg_attr(not(doc), repr(C))] // work around https://github.com/rust-lang/rust/issues/66401 -#[derive(Debug)] -#[unstable( - feature = "c_variadic", - reason = "the `c_variadic` feature has not been properly tested on \ - all supported platforms", - issue = "44930" -)] -#[lang = "va_list"] -pub struct VaListImpl<'f> { - gp_offset: i32, - fp_offset: i32, - overflow_arg_area: *mut c_void, - reg_save_area: *mut c_void, - _marker: PhantomData<&'f mut &'f c_void>, -} - -/// A wrapper for a `va_list` -#[cfg_attr(not(doc), repr(transparent))] // work around https://github.com/rust-lang/rust/issues/90435 -#[derive(Debug)] -#[unstable( - feature = "c_variadic", - reason = "the `c_variadic` feature has not been properly tested on \ - all supported platforms", - issue = "44930" -)] -pub struct VaList<'a, 'f: 'a> { - #[cfg(any( - all( - not(target_arch = "aarch64"), - not(target_arch = "powerpc"), - not(target_arch = "s390x"), - not(target_arch = "x86_64") - ), - all(target_arch = "aarch64", target_vendor = "apple"), - target_family = "wasm", - target_os = "uefi", - windows, - ))] - inner: VaListImpl<'f>, - - #[cfg(all( - any( - target_arch = "aarch64", - target_arch = "powerpc", - target_arch = "s390x", - target_arch = "x86_64" - ), - any(not(target_arch = "aarch64"), not(target_vendor = "apple")), - not(target_family = "wasm"), - not(target_os = "uefi"), - not(windows), - ))] - inner: &'a mut VaListImpl<'f>, - - _marker: PhantomData<&'a mut VaListImpl<'f>>, -} - -#[cfg(any( - all( - not(target_arch = "aarch64"), - not(target_arch = "powerpc"), - not(target_arch = "s390x"), - not(target_arch = "x86_64") - ), - all(target_arch = "aarch64", target_vendor = "apple"), - target_family = "wasm", - target_os = "uefi", - windows, -))] -#[unstable( - feature = "c_variadic", - reason = "the `c_variadic` feature has not been properly tested on \ - all supported platforms", - issue = "44930" -)] -impl<'f> VaListImpl<'f> { - /// Convert a `VaListImpl` into a `VaList` that is binary-compatible with C's `va_list`. - #[inline] - pub fn as_va_list<'a>(&'a mut self) -> VaList<'a, 'f> { - VaList { inner: VaListImpl { ..*self }, _marker: PhantomData } - } -} - -#[cfg(all( - any( - target_arch = "aarch64", - target_arch = "powerpc", - target_arch = "s390x", - target_arch = "x86_64" - ), - any(not(target_arch = "aarch64"), not(target_vendor = "apple")), - not(target_family = "wasm"), - not(target_os = "uefi"), - not(windows), -))] -#[unstable( - feature = "c_variadic", - reason = "the `c_variadic` feature has not been properly tested on \ - all supported platforms", - issue = "44930" -)] -impl<'f> VaListImpl<'f> { - /// Convert a `VaListImpl` into a `VaList` that is binary-compatible with C's `va_list`. - #[inline] - pub fn as_va_list<'a>(&'a mut self) -> VaList<'a, 'f> { - VaList { inner: self, _marker: PhantomData } - } -} - -#[unstable( - feature = "c_variadic", - reason = "the `c_variadic` feature has not been properly tested on \ - all supported platforms", - issue = "44930" -)] -impl<'a, 'f: 'a> Deref for VaList<'a, 'f> { - type Target = VaListImpl<'f>; - - #[inline] - fn deref(&self) -> &VaListImpl<'f> { - &self.inner - } -} - -#[unstable( - feature = "c_variadic", - reason = "the `c_variadic` feature has not been properly tested on \ - all supported platforms", - issue = "44930" -)] -impl<'a, 'f: 'a> DerefMut for VaList<'a, 'f> { - #[inline] - fn deref_mut(&mut self) -> &mut VaListImpl<'f> { - &mut self.inner - } -} - -// The VaArgSafe trait needs to be used in public interfaces, however, the trait -// itself must not be allowed to be used outside this module. Allowing users to -// implement the trait for a new type (thereby allowing the va_arg intrinsic to -// be used on a new type) is likely to cause undefined behavior. -// -// FIXME(dlrobertson): In order to use the VaArgSafe trait in a public interface -// but also ensure it cannot be used elsewhere, the trait needs to be public -// within a private module. Once RFC 2145 has been implemented look into -// improving this. -mod sealed_trait { - /// Trait which permits the allowed types to be used with [super::VaListImpl::arg]. - #[unstable( - feature = "c_variadic", - reason = "the `c_variadic` feature has not been properly tested on \ - all supported platforms", - issue = "44930" - )] - pub trait VaArgSafe {} -} - -macro_rules! impl_va_arg_safe { - ($($t:ty),+) => { - $( - #[unstable(feature = "c_variadic", - reason = "the `c_variadic` feature has not been properly tested on \ - all supported platforms", - issue = "44930")] - impl sealed_trait::VaArgSafe for $t {} - )+ - } -} - -impl_va_arg_safe! {i8, i16, i32, i64, usize} -impl_va_arg_safe! {u8, u16, u32, u64, isize} -impl_va_arg_safe! {f64} - -#[unstable( - feature = "c_variadic", - reason = "the `c_variadic` feature has not been properly tested on \ - all supported platforms", - issue = "44930" -)] -impl sealed_trait::VaArgSafe for *mut T {} -#[unstable( - feature = "c_variadic", - reason = "the `c_variadic` feature has not been properly tested on \ - all supported platforms", - issue = "44930" -)] -impl sealed_trait::VaArgSafe for *const T {} - -#[unstable( - feature = "c_variadic", - reason = "the `c_variadic` feature has not been properly tested on \ - all supported platforms", - issue = "44930" -)] -impl<'f> VaListImpl<'f> { - /// Advance to the next arg. - #[inline] - pub unsafe fn arg(&mut self) -> T { - // SAFETY: the caller must uphold the safety contract for `va_arg`. - unsafe { va_arg(self) } - } - - /// Copies the `va_list` at the current location. - pub unsafe fn with_copy(&self, f: F) -> R - where - F: for<'copy> FnOnce(VaList<'copy, 'f>) -> R, - { - let mut ap = self.clone(); - let ret = f(ap.as_va_list()); - // SAFETY: the caller must uphold the safety contract for `va_end`. - unsafe { - va_end(&mut ap); - } - ret - } -} - -#[unstable( - feature = "c_variadic", - reason = "the `c_variadic` feature has not been properly tested on \ - all supported platforms", - issue = "44930" -)] -impl<'f> Clone for VaListImpl<'f> { - #[inline] - fn clone(&self) -> Self { - let mut dest = crate::mem::MaybeUninit::uninit(); - // SAFETY: we write to the `MaybeUninit`, thus it is initialized and `assume_init` is legal - unsafe { - va_copy(dest.as_mut_ptr(), self); - dest.assume_init() - } - } -} - -#[unstable( - feature = "c_variadic", - reason = "the `c_variadic` feature has not been properly tested on \ - all supported platforms", - issue = "44930" -)] -impl<'f> Drop for VaListImpl<'f> { - fn drop(&mut self) { - // FIXME: this should call `va_end`, but there's no clean way to - // guarantee that `drop` always gets inlined into its caller, - // so the `va_end` would get directly called from the same function as - // the corresponding `va_copy`. `man va_end` states that C requires this, - // and LLVM basically follows the C semantics, so we need to make sure - // that `va_end` is always called from the same function as `va_copy`. - // For more details, see https://github.com/rust-lang/rust/pull/59625 - // and https://llvm.org/docs/LangRef.html#llvm-va-end-intrinsic. - // - // This works for now, since `va_end` is a no-op on all current LLVM targets. - } -} - -extern "rust-intrinsic" { - /// Destroy the arglist `ap` after initialization with `va_start` or - /// `va_copy`. - #[rustc_nounwind] - fn va_end(ap: &mut VaListImpl<'_>); - - /// Copies the current location of arglist `src` to the arglist `dst`. - #[rustc_nounwind] - fn va_copy<'f>(dest: *mut VaListImpl<'f>, src: &VaListImpl<'f>); - - /// Loads an argument of type `T` from the `va_list` `ap` and increment the - /// argument `ap` points to. - #[rustc_nounwind] - fn va_arg(ap: &mut VaListImpl<'_>) -> T; -} - -// Link the MSVC default lib -#[cfg(all(windows, target_env = "msvc"))] -#[link( - name = "/defaultlib:msvcrt", - modifiers = "+verbatim", - cfg(not(target_feature = "crt-static")) -)] -#[link(name = "/defaultlib:libcmt", modifiers = "+verbatim", cfg(target_feature = "crt-static"))] -extern "C" {} diff --git a/library/core/src/fmt/builders.rs b/library/core/src/fmt/builders.rs deleted file mode 100644 index 4ccb585862cdf..0000000000000 --- a/library/core/src/fmt/builders.rs +++ /dev/null @@ -1,1056 +0,0 @@ -#![allow(unused_imports)] - -use crate::fmt::{self, Debug, Formatter}; - -struct PadAdapter<'buf, 'state> { - buf: &'buf mut (dyn fmt::Write + 'buf), - state: &'state mut PadAdapterState, -} - -struct PadAdapterState { - on_newline: bool, -} - -impl Default for PadAdapterState { - fn default() -> Self { - PadAdapterState { on_newline: true } - } -} - -impl<'buf, 'state> PadAdapter<'buf, 'state> { - fn wrap<'slot, 'fmt: 'buf + 'slot>( - fmt: &'fmt mut fmt::Formatter<'_>, - slot: &'slot mut Option, - state: &'state mut PadAdapterState, - ) -> fmt::Formatter<'slot> { - fmt.wrap_buf(move |buf| slot.insert(PadAdapter { buf, state })) - } -} - -impl fmt::Write for PadAdapter<'_, '_> { - fn write_str(&mut self, s: &str) -> fmt::Result { - for s in s.split_inclusive('\n') { - if self.state.on_newline { - self.buf.write_str(" ")?; - } - - self.state.on_newline = s.ends_with('\n'); - self.buf.write_str(s)?; - } - - Ok(()) - } - - fn write_char(&mut self, c: char) -> fmt::Result { - if self.state.on_newline { - self.buf.write_str(" ")?; - } - self.state.on_newline = c == '\n'; - self.buf.write_char(c) - } -} - -/// A struct to help with [`fmt::Debug`](Debug) implementations. -/// -/// This is useful when you wish to output a formatted struct as a part of your -/// [`Debug::fmt`] implementation. -/// -/// This can be constructed by the [`Formatter::debug_struct`] method. -/// -/// # Examples -/// -/// ``` -/// use std::fmt; -/// -/// struct Foo { -/// bar: i32, -/// baz: String, -/// } -/// -/// impl fmt::Debug for Foo { -/// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { -/// fmt.debug_struct("Foo") -/// .field("bar", &self.bar) -/// .field("baz", &self.baz) -/// .finish() -/// } -/// } -/// -/// assert_eq!( -/// format!("{:?}", Foo { bar: 10, baz: "Hello World".to_string() }), -/// "Foo { bar: 10, baz: \"Hello World\" }", -/// ); -/// ``` -#[must_use = "must eventually call `finish()` on Debug builders"] -#[allow(missing_debug_implementations)] -#[stable(feature = "debug_builders", since = "1.2.0")] -#[rustc_diagnostic_item = "DebugStruct"] -pub struct DebugStruct<'a, 'b: 'a> { - fmt: &'a mut fmt::Formatter<'b>, - result: fmt::Result, - has_fields: bool, -} - -pub(super) fn debug_struct_new<'a, 'b>( - fmt: &'a mut fmt::Formatter<'b>, - name: &str, -) -> DebugStruct<'a, 'b> { - let result = fmt.write_str(name); - DebugStruct { fmt, result, has_fields: false } -} - -impl<'a, 'b: 'a> DebugStruct<'a, 'b> { - /// Adds a new field to the generated struct output. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Bar { - /// bar: i32, - /// another: String, - /// } - /// - /// impl fmt::Debug for Bar { - /// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - /// fmt.debug_struct("Bar") - /// .field("bar", &self.bar) // We add `bar` field. - /// .field("another", &self.another) // We add `another` field. - /// // We even add a field which doesn't exist (because why not?). - /// .field("nonexistent_field", &1) - /// .finish() // We're good to go! - /// } - /// } - /// - /// assert_eq!( - /// format!("{:?}", Bar { bar: 10, another: "Hello World".to_string() }), - /// "Bar { bar: 10, another: \"Hello World\", nonexistent_field: 1 }", - /// ); - /// ``` - #[stable(feature = "debug_builders", since = "1.2.0")] - pub fn field(&mut self, name: &str, value: &dyn fmt::Debug) -> &mut Self { - self.field_with(name, |f| value.fmt(f)) - } - - /// Adds a new field to the generated struct output. - /// - /// This method is equivalent to [`DebugStruct::field`], but formats the - /// value using a provided closure rather than by calling [`Debug::fmt`]. - #[unstable(feature = "debug_closure_helpers", issue = "117729")] - pub fn field_with(&mut self, name: &str, value_fmt: F) -> &mut Self - where - F: FnOnce(&mut fmt::Formatter<'_>) -> fmt::Result, - { - self.result = self.result.and_then(|_| { - if self.is_pretty() { - if !self.has_fields { - self.fmt.write_str(" {\n")?; - } - let mut slot = None; - let mut state = Default::default(); - let mut writer = PadAdapter::wrap(self.fmt, &mut slot, &mut state); - writer.write_str(name)?; - writer.write_str(": ")?; - value_fmt(&mut writer)?; - writer.write_str(",\n") - } else { - let prefix = if self.has_fields { ", " } else { " { " }; - self.fmt.write_str(prefix)?; - self.fmt.write_str(name)?; - self.fmt.write_str(": ")?; - value_fmt(self.fmt) - } - }); - - self.has_fields = true; - self - } - - /// Marks the struct as non-exhaustive, indicating to the reader that there are some other - /// fields that are not shown in the debug representation. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Bar { - /// bar: i32, - /// hidden: f32, - /// } - /// - /// impl fmt::Debug for Bar { - /// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - /// fmt.debug_struct("Bar") - /// .field("bar", &self.bar) - /// .finish_non_exhaustive() // Show that some other field(s) exist. - /// } - /// } - /// - /// assert_eq!( - /// format!("{:?}", Bar { bar: 10, hidden: 1.0 }), - /// "Bar { bar: 10, .. }", - /// ); - /// ``` - #[stable(feature = "debug_non_exhaustive", since = "1.53.0")] - pub fn finish_non_exhaustive(&mut self) -> fmt::Result { - self.result = self.result.and_then(|_| { - if self.has_fields { - if self.is_pretty() { - let mut slot = None; - let mut state = Default::default(); - let mut writer = PadAdapter::wrap(self.fmt, &mut slot, &mut state); - writer.write_str("..\n")?; - self.fmt.write_str("}") - } else { - self.fmt.write_str(", .. }") - } - } else { - self.fmt.write_str(" { .. }") - } - }); - self.result - } - - /// Finishes output and returns any error encountered. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Bar { - /// bar: i32, - /// baz: String, - /// } - /// - /// impl fmt::Debug for Bar { - /// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - /// fmt.debug_struct("Bar") - /// .field("bar", &self.bar) - /// .field("baz", &self.baz) - /// .finish() // You need to call it to "finish" the - /// // struct formatting. - /// } - /// } - /// - /// assert_eq!( - /// format!("{:?}", Bar { bar: 10, baz: "Hello World".to_string() }), - /// "Bar { bar: 10, baz: \"Hello World\" }", - /// ); - /// ``` - #[stable(feature = "debug_builders", since = "1.2.0")] - pub fn finish(&mut self) -> fmt::Result { - if self.has_fields { - self.result = self.result.and_then(|_| { - if self.is_pretty() { self.fmt.write_str("}") } else { self.fmt.write_str(" }") } - }); - } - self.result - } - - fn is_pretty(&self) -> bool { - self.fmt.alternate() - } -} - -/// A struct to help with [`fmt::Debug`](Debug) implementations. -/// -/// This is useful when you wish to output a formatted tuple as a part of your -/// [`Debug::fmt`] implementation. -/// -/// This can be constructed by the [`Formatter::debug_tuple`] method. -/// -/// # Examples -/// -/// ``` -/// use std::fmt; -/// -/// struct Foo(i32, String); -/// -/// impl fmt::Debug for Foo { -/// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { -/// fmt.debug_tuple("Foo") -/// .field(&self.0) -/// .field(&self.1) -/// .finish() -/// } -/// } -/// -/// assert_eq!( -/// format!("{:?}", Foo(10, "Hello World".to_string())), -/// "Foo(10, \"Hello World\")", -/// ); -/// ``` -#[must_use = "must eventually call `finish()` on Debug builders"] -#[allow(missing_debug_implementations)] -#[stable(feature = "debug_builders", since = "1.2.0")] -pub struct DebugTuple<'a, 'b: 'a> { - fmt: &'a mut fmt::Formatter<'b>, - result: fmt::Result, - fields: usize, - empty_name: bool, -} - -pub(super) fn debug_tuple_new<'a, 'b>( - fmt: &'a mut fmt::Formatter<'b>, - name: &str, -) -> DebugTuple<'a, 'b> { - let result = fmt.write_str(name); - DebugTuple { fmt, result, fields: 0, empty_name: name.is_empty() } -} - -impl<'a, 'b: 'a> DebugTuple<'a, 'b> { - /// Adds a new field to the generated tuple struct output. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo(i32, String); - /// - /// impl fmt::Debug for Foo { - /// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - /// fmt.debug_tuple("Foo") - /// .field(&self.0) // We add the first field. - /// .field(&self.1) // We add the second field. - /// .finish() // We're good to go! - /// } - /// } - /// - /// assert_eq!( - /// format!("{:?}", Foo(10, "Hello World".to_string())), - /// "Foo(10, \"Hello World\")", - /// ); - /// ``` - #[stable(feature = "debug_builders", since = "1.2.0")] - pub fn field(&mut self, value: &dyn fmt::Debug) -> &mut Self { - self.field_with(|f| value.fmt(f)) - } - - /// Adds a new field to the generated tuple struct output. - /// - /// This method is equivalent to [`DebugTuple::field`], but formats the - /// value using a provided closure rather than by calling [`Debug::fmt`]. - #[unstable(feature = "debug_closure_helpers", issue = "117729")] - pub fn field_with(&mut self, value_fmt: F) -> &mut Self - where - F: FnOnce(&mut fmt::Formatter<'_>) -> fmt::Result, - { - self.result = self.result.and_then(|_| { - if self.is_pretty() { - if self.fields == 0 { - self.fmt.write_str("(\n")?; - } - let mut slot = None; - let mut state = Default::default(); - let mut writer = PadAdapter::wrap(self.fmt, &mut slot, &mut state); - value_fmt(&mut writer)?; - writer.write_str(",\n") - } else { - let prefix = if self.fields == 0 { "(" } else { ", " }; - self.fmt.write_str(prefix)?; - value_fmt(self.fmt) - } - }); - - self.fields += 1; - self - } - - /// Finishes output and returns any error encountered. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo(i32, String); - /// - /// impl fmt::Debug for Foo { - /// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - /// fmt.debug_tuple("Foo") - /// .field(&self.0) - /// .field(&self.1) - /// .finish() // You need to call it to "finish" the - /// // tuple formatting. - /// } - /// } - /// - /// assert_eq!( - /// format!("{:?}", Foo(10, "Hello World".to_string())), - /// "Foo(10, \"Hello World\")", - /// ); - /// ``` - #[stable(feature = "debug_builders", since = "1.2.0")] - pub fn finish(&mut self) -> fmt::Result { - if self.fields > 0 { - self.result = self.result.and_then(|_| { - if self.fields == 1 && self.empty_name && !self.is_pretty() { - self.fmt.write_str(",")?; - } - self.fmt.write_str(")") - }); - } - self.result - } - - fn is_pretty(&self) -> bool { - self.fmt.alternate() - } -} - -struct DebugInner<'a, 'b: 'a> { - fmt: &'a mut fmt::Formatter<'b>, - result: fmt::Result, - has_fields: bool, -} - -impl<'a, 'b: 'a> DebugInner<'a, 'b> { - fn entry_with(&mut self, entry_fmt: F) - where - F: FnOnce(&mut fmt::Formatter<'_>) -> fmt::Result, - { - self.result = self.result.and_then(|_| { - if self.is_pretty() { - if !self.has_fields { - self.fmt.write_str("\n")?; - } - let mut slot = None; - let mut state = Default::default(); - let mut writer = PadAdapter::wrap(self.fmt, &mut slot, &mut state); - entry_fmt(&mut writer)?; - writer.write_str(",\n") - } else { - if self.has_fields { - self.fmt.write_str(", ")? - } - entry_fmt(self.fmt) - } - }); - - self.has_fields = true; - } - - fn is_pretty(&self) -> bool { - self.fmt.alternate() - } -} - -/// A struct to help with [`fmt::Debug`](Debug) implementations. -/// -/// This is useful when you wish to output a formatted set of items as a part -/// of your [`Debug::fmt`] implementation. -/// -/// This can be constructed by the [`Formatter::debug_set`] method. -/// -/// # Examples -/// -/// ``` -/// use std::fmt; -/// -/// struct Foo(Vec); -/// -/// impl fmt::Debug for Foo { -/// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { -/// fmt.debug_set().entries(self.0.iter()).finish() -/// } -/// } -/// -/// assert_eq!( -/// format!("{:?}", Foo(vec![10, 11])), -/// "{10, 11}", -/// ); -/// ``` -#[must_use = "must eventually call `finish()` on Debug builders"] -#[allow(missing_debug_implementations)] -#[stable(feature = "debug_builders", since = "1.2.0")] -pub struct DebugSet<'a, 'b: 'a> { - inner: DebugInner<'a, 'b>, -} - -pub(super) fn debug_set_new<'a, 'b>(fmt: &'a mut fmt::Formatter<'b>) -> DebugSet<'a, 'b> { - let result = fmt.write_str("{"); - DebugSet { inner: DebugInner { fmt, result, has_fields: false } } -} - -impl<'a, 'b: 'a> DebugSet<'a, 'b> { - /// Adds a new entry to the set output. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo(Vec, Vec); - /// - /// impl fmt::Debug for Foo { - /// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - /// fmt.debug_set() - /// .entry(&self.0) // Adds the first "entry". - /// .entry(&self.1) // Adds the second "entry". - /// .finish() - /// } - /// } - /// - /// assert_eq!( - /// format!("{:?}", Foo(vec![10, 11], vec![12, 13])), - /// "{[10, 11], [12, 13]}", - /// ); - /// ``` - #[stable(feature = "debug_builders", since = "1.2.0")] - pub fn entry(&mut self, entry: &dyn fmt::Debug) -> &mut Self { - self.inner.entry_with(|f| entry.fmt(f)); - self - } - - /// Adds a new entry to the set output. - /// - /// This method is equivalent to [`DebugSet::entry`], but formats the - /// entry using a provided closure rather than by calling [`Debug::fmt`]. - #[unstable(feature = "debug_closure_helpers", issue = "117729")] - pub fn entry_with(&mut self, entry_fmt: F) -> &mut Self - where - F: FnOnce(&mut fmt::Formatter<'_>) -> fmt::Result, - { - self.inner.entry_with(entry_fmt); - self - } - - /// Adds the contents of an iterator of entries to the set output. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo(Vec, Vec); - /// - /// impl fmt::Debug for Foo { - /// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - /// fmt.debug_set() - /// .entries(self.0.iter()) // Adds the first "entry". - /// .entries(self.1.iter()) // Adds the second "entry". - /// .finish() - /// } - /// } - /// - /// assert_eq!( - /// format!("{:?}", Foo(vec![10, 11], vec![12, 13])), - /// "{10, 11, 12, 13}", - /// ); - /// ``` - #[stable(feature = "debug_builders", since = "1.2.0")] - pub fn entries(&mut self, entries: I) -> &mut Self - where - D: fmt::Debug, - I: IntoIterator, - { - for entry in entries { - self.entry(&entry); - } - self - } - - /// Finishes output and returns any error encountered. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo(Vec); - /// - /// impl fmt::Debug for Foo { - /// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - /// fmt.debug_set() - /// .entries(self.0.iter()) - /// .finish() // Ends the set formatting. - /// } - /// } - /// - /// assert_eq!( - /// format!("{:?}", Foo(vec![10, 11])), - /// "{10, 11}", - /// ); - /// ``` - #[stable(feature = "debug_builders", since = "1.2.0")] - pub fn finish(&mut self) -> fmt::Result { - self.inner.result.and_then(|_| self.inner.fmt.write_str("}")) - } -} - -/// A struct to help with [`fmt::Debug`](Debug) implementations. -/// -/// This is useful when you wish to output a formatted list of items as a part -/// of your [`Debug::fmt`] implementation. -/// -/// This can be constructed by the [`Formatter::debug_list`] method. -/// -/// # Examples -/// -/// ``` -/// use std::fmt; -/// -/// struct Foo(Vec); -/// -/// impl fmt::Debug for Foo { -/// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { -/// fmt.debug_list().entries(self.0.iter()).finish() -/// } -/// } -/// -/// assert_eq!( -/// format!("{:?}", Foo(vec![10, 11])), -/// "[10, 11]", -/// ); -/// ``` -#[must_use = "must eventually call `finish()` on Debug builders"] -#[allow(missing_debug_implementations)] -#[stable(feature = "debug_builders", since = "1.2.0")] -pub struct DebugList<'a, 'b: 'a> { - inner: DebugInner<'a, 'b>, -} - -pub(super) fn debug_list_new<'a, 'b>(fmt: &'a mut fmt::Formatter<'b>) -> DebugList<'a, 'b> { - let result = fmt.write_str("["); - DebugList { inner: DebugInner { fmt, result, has_fields: false } } -} - -impl<'a, 'b: 'a> DebugList<'a, 'b> { - /// Adds a new entry to the list output. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo(Vec, Vec); - /// - /// impl fmt::Debug for Foo { - /// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - /// fmt.debug_list() - /// .entry(&self.0) // We add the first "entry". - /// .entry(&self.1) // We add the second "entry". - /// .finish() - /// } - /// } - /// - /// assert_eq!( - /// format!("{:?}", Foo(vec![10, 11], vec![12, 13])), - /// "[[10, 11], [12, 13]]", - /// ); - /// ``` - #[stable(feature = "debug_builders", since = "1.2.0")] - pub fn entry(&mut self, entry: &dyn fmt::Debug) -> &mut Self { - self.inner.entry_with(|f| entry.fmt(f)); - self - } - - /// Adds a new entry to the list output. - /// - /// This method is equivalent to [`DebugList::entry`], but formats the - /// entry using a provided closure rather than by calling [`Debug::fmt`]. - #[unstable(feature = "debug_closure_helpers", issue = "117729")] - pub fn entry_with(&mut self, entry_fmt: F) -> &mut Self - where - F: FnOnce(&mut fmt::Formatter<'_>) -> fmt::Result, - { - self.inner.entry_with(entry_fmt); - self - } - - /// Adds the contents of an iterator of entries to the list output. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo(Vec, Vec); - /// - /// impl fmt::Debug for Foo { - /// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - /// fmt.debug_list() - /// .entries(self.0.iter()) - /// .entries(self.1.iter()) - /// .finish() - /// } - /// } - /// - /// assert_eq!( - /// format!("{:?}", Foo(vec![10, 11], vec![12, 13])), - /// "[10, 11, 12, 13]", - /// ); - /// ``` - #[stable(feature = "debug_builders", since = "1.2.0")] - pub fn entries(&mut self, entries: I) -> &mut Self - where - D: fmt::Debug, - I: IntoIterator, - { - for entry in entries { - self.entry(&entry); - } - self - } - - /// Finishes output and returns any error encountered. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo(Vec); - /// - /// impl fmt::Debug for Foo { - /// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - /// fmt.debug_list() - /// .entries(self.0.iter()) - /// .finish() // Ends the list formatting. - /// } - /// } - /// - /// assert_eq!( - /// format!("{:?}", Foo(vec![10, 11])), - /// "[10, 11]", - /// ); - /// ``` - #[stable(feature = "debug_builders", since = "1.2.0")] - pub fn finish(&mut self) -> fmt::Result { - self.inner.result.and_then(|_| self.inner.fmt.write_str("]")) - } -} - -/// A struct to help with [`fmt::Debug`](Debug) implementations. -/// -/// This is useful when you wish to output a formatted map as a part of your -/// [`Debug::fmt`] implementation. -/// -/// This can be constructed by the [`Formatter::debug_map`] method. -/// -/// # Examples -/// -/// ``` -/// use std::fmt; -/// -/// struct Foo(Vec<(String, i32)>); -/// -/// impl fmt::Debug for Foo { -/// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { -/// fmt.debug_map().entries(self.0.iter().map(|&(ref k, ref v)| (k, v))).finish() -/// } -/// } -/// -/// assert_eq!( -/// format!("{:?}", Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])), -/// "{\"A\": 10, \"B\": 11}", -/// ); -/// ``` -#[must_use = "must eventually call `finish()` on Debug builders"] -#[allow(missing_debug_implementations)] -#[stable(feature = "debug_builders", since = "1.2.0")] -pub struct DebugMap<'a, 'b: 'a> { - fmt: &'a mut fmt::Formatter<'b>, - result: fmt::Result, - has_fields: bool, - has_key: bool, - // The state of newlines is tracked between keys and values - state: PadAdapterState, -} - -pub(super) fn debug_map_new<'a, 'b>(fmt: &'a mut fmt::Formatter<'b>) -> DebugMap<'a, 'b> { - let result = fmt.write_str("{"); - DebugMap { fmt, result, has_fields: false, has_key: false, state: Default::default() } -} - -impl<'a, 'b: 'a> DebugMap<'a, 'b> { - /// Adds a new entry to the map output. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo(Vec<(String, i32)>); - /// - /// impl fmt::Debug for Foo { - /// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - /// fmt.debug_map() - /// .entry(&"whole", &self.0) // We add the "whole" entry. - /// .finish() - /// } - /// } - /// - /// assert_eq!( - /// format!("{:?}", Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])), - /// "{\"whole\": [(\"A\", 10), (\"B\", 11)]}", - /// ); - /// ``` - #[stable(feature = "debug_builders", since = "1.2.0")] - pub fn entry(&mut self, key: &dyn fmt::Debug, value: &dyn fmt::Debug) -> &mut Self { - self.key(key).value(value) - } - - /// Adds the key part of a new entry to the map output. - /// - /// This method, together with `value`, is an alternative to `entry` that - /// can be used when the complete entry isn't known upfront. Prefer the `entry` - /// method when it's possible to use. - /// - /// # Panics - /// - /// `key` must be called before `value` and each call to `key` must be followed - /// by a corresponding call to `value`. Otherwise this method will panic. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo(Vec<(String, i32)>); - /// - /// impl fmt::Debug for Foo { - /// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - /// fmt.debug_map() - /// .key(&"whole").value(&self.0) // We add the "whole" entry. - /// .finish() - /// } - /// } - /// - /// assert_eq!( - /// format!("{:?}", Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])), - /// "{\"whole\": [(\"A\", 10), (\"B\", 11)]}", - /// ); - /// ``` - #[stable(feature = "debug_map_key_value", since = "1.42.0")] - pub fn key(&mut self, key: &dyn fmt::Debug) -> &mut Self { - self.key_with(|f| key.fmt(f)) - } - - /// Adds the key part of a new entry to the map output. - /// - /// This method is equivalent to [`DebugMap::key`], but formats the - /// key using a provided closure rather than by calling [`Debug::fmt`]. - #[unstable(feature = "debug_closure_helpers", issue = "117729")] - pub fn key_with(&mut self, key_fmt: F) -> &mut Self - where - F: FnOnce(&mut fmt::Formatter<'_>) -> fmt::Result, - { - self.result = self.result.and_then(|_| { - assert!( - !self.has_key, - "attempted to begin a new map entry \ - without completing the previous one" - ); - - if self.is_pretty() { - if !self.has_fields { - self.fmt.write_str("\n")?; - } - let mut slot = None; - self.state = Default::default(); - let mut writer = PadAdapter::wrap(self.fmt, &mut slot, &mut self.state); - key_fmt(&mut writer)?; - writer.write_str(": ")?; - } else { - if self.has_fields { - self.fmt.write_str(", ")? - } - key_fmt(self.fmt)?; - self.fmt.write_str(": ")?; - } - - self.has_key = true; - Ok(()) - }); - - self - } - - /// Adds the value part of a new entry to the map output. - /// - /// This method, together with `key`, is an alternative to `entry` that - /// can be used when the complete entry isn't known upfront. Prefer the `entry` - /// method when it's possible to use. - /// - /// # Panics - /// - /// `key` must be called before `value` and each call to `key` must be followed - /// by a corresponding call to `value`. Otherwise this method will panic. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo(Vec<(String, i32)>); - /// - /// impl fmt::Debug for Foo { - /// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - /// fmt.debug_map() - /// .key(&"whole").value(&self.0) // We add the "whole" entry. - /// .finish() - /// } - /// } - /// - /// assert_eq!( - /// format!("{:?}", Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])), - /// "{\"whole\": [(\"A\", 10), (\"B\", 11)]}", - /// ); - /// ``` - #[stable(feature = "debug_map_key_value", since = "1.42.0")] - pub fn value(&mut self, value: &dyn fmt::Debug) -> &mut Self { - self.value_with(|f| value.fmt(f)) - } - - /// Adds the value part of a new entry to the map output. - /// - /// This method is equivalent to [`DebugMap::value`], but formats the - /// value using a provided closure rather than by calling [`Debug::fmt`]. - #[unstable(feature = "debug_closure_helpers", issue = "117729")] - pub fn value_with(&mut self, value_fmt: F) -> &mut Self - where - F: FnOnce(&mut fmt::Formatter<'_>) -> fmt::Result, - { - self.result = self.result.and_then(|_| { - assert!(self.has_key, "attempted to format a map value before its key"); - - if self.is_pretty() { - let mut slot = None; - let mut writer = PadAdapter::wrap(self.fmt, &mut slot, &mut self.state); - value_fmt(&mut writer)?; - writer.write_str(",\n")?; - } else { - value_fmt(self.fmt)?; - } - - self.has_key = false; - Ok(()) - }); - - self.has_fields = true; - self - } - - /// Adds the contents of an iterator of entries to the map output. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo(Vec<(String, i32)>); - /// - /// impl fmt::Debug for Foo { - /// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - /// fmt.debug_map() - /// // We map our vec so each entries' first field will become - /// // the "key". - /// .entries(self.0.iter().map(|&(ref k, ref v)| (k, v))) - /// .finish() - /// } - /// } - /// - /// assert_eq!( - /// format!("{:?}", Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])), - /// "{\"A\": 10, \"B\": 11}", - /// ); - /// ``` - #[stable(feature = "debug_builders", since = "1.2.0")] - pub fn entries(&mut self, entries: I) -> &mut Self - where - K: fmt::Debug, - V: fmt::Debug, - I: IntoIterator, - { - for (k, v) in entries { - self.entry(&k, &v); - } - self - } - - /// Finishes output and returns any error encountered. - /// - /// # Panics - /// - /// `key` must be called before `value` and each call to `key` must be followed - /// by a corresponding call to `value`. Otherwise this method will panic. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo(Vec<(String, i32)>); - /// - /// impl fmt::Debug for Foo { - /// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - /// fmt.debug_map() - /// .entries(self.0.iter().map(|&(ref k, ref v)| (k, v))) - /// .finish() // Ends the map formatting. - /// } - /// } - /// - /// assert_eq!( - /// format!("{:?}", Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])), - /// "{\"A\": 10, \"B\": 11}", - /// ); - /// ``` - #[stable(feature = "debug_builders", since = "1.2.0")] - pub fn finish(&mut self) -> fmt::Result { - self.result.and_then(|_| { - assert!(!self.has_key, "attempted to finish a map with a partial entry"); - - self.fmt.write_str("}") - }) - } - - fn is_pretty(&self) -> bool { - self.fmt.alternate() - } -} - -/// Implements [`fmt::Debug`] and [`fmt::Display`] using a function. -/// -/// # Examples -/// -/// ``` -/// #![feature(debug_closure_helpers)] -/// use std::fmt; -/// -/// let value = 'a'; -/// assert_eq!(format!("{}", value), "a"); -/// assert_eq!(format!("{:?}", value), "'a'"); -/// -/// let wrapped = fmt::FormatterFn(|f| write!(f, "{:?}", &value)); -/// assert_eq!(format!("{}", wrapped), "'a'"); -/// assert_eq!(format!("{:?}", wrapped), "'a'"); -/// ``` -#[unstable(feature = "debug_closure_helpers", issue = "117729")] -pub struct FormatterFn(pub F) -where - F: Fn(&mut fmt::Formatter<'_>) -> fmt::Result; - -#[unstable(feature = "debug_closure_helpers", issue = "117729")] -impl fmt::Debug for FormatterFn -where - F: Fn(&mut fmt::Formatter<'_>) -> fmt::Result, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - (self.0)(f) - } -} - -#[unstable(feature = "debug_closure_helpers", issue = "117729")] -impl fmt::Display for FormatterFn -where - F: Fn(&mut fmt::Formatter<'_>) -> fmt::Result, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - (self.0)(f) - } -} diff --git a/library/core/src/fmt/float.rs b/library/core/src/fmt/float.rs deleted file mode 100644 index 7f23d3c09567c..0000000000000 --- a/library/core/src/fmt/float.rs +++ /dev/null @@ -1,246 +0,0 @@ -use crate::fmt::{Debug, Display, Formatter, LowerExp, Result, UpperExp}; -use crate::mem::MaybeUninit; -use crate::num::flt2dec; -use crate::num::fmt as numfmt; - -#[doc(hidden)] -trait GeneralFormat: PartialOrd { - /// Determines if a value should use exponential based on its magnitude, given the precondition - /// that it will not be rounded any further before it is displayed. - fn already_rounded_value_should_use_exponential(&self) -> bool; -} - -macro_rules! impl_general_format { - ($($t:ident)*) => { - $(impl GeneralFormat for $t { - fn already_rounded_value_should_use_exponential(&self) -> bool { - let abs = $t::abs_private(*self); - (abs != 0.0 && abs < 1e-4) || abs >= 1e+16 - } - })* - } -} - -impl_general_format! { f32 f64 } - -// Don't inline this so callers don't use the stack space this function -// requires unless they have to. -#[inline(never)] -fn float_to_decimal_common_exact( - fmt: &mut Formatter<'_>, - num: &T, - sign: flt2dec::Sign, - precision: usize, -) -> Result -where - T: flt2dec::DecodableFloat, -{ - let mut buf: [MaybeUninit; 1024] = MaybeUninit::uninit_array(); // enough for f32 and f64 - let mut parts: [MaybeUninit>; 4] = MaybeUninit::uninit_array(); - let formatted = flt2dec::to_exact_fixed_str( - flt2dec::strategy::grisu::format_exact, - *num, - sign, - precision, - &mut buf, - &mut parts, - ); - // SAFETY: `to_exact_fixed_str` and `format_exact` produce only ASCII characters. - unsafe { fmt.pad_formatted_parts(&formatted) } -} - -// Don't inline this so callers that call both this and the above won't wind -// up using the combined stack space of both functions in some cases. -#[inline(never)] -fn float_to_decimal_common_shortest( - fmt: &mut Formatter<'_>, - num: &T, - sign: flt2dec::Sign, - precision: usize, -) -> Result -where - T: flt2dec::DecodableFloat, -{ - // enough for f32 and f64 - let mut buf: [MaybeUninit; flt2dec::MAX_SIG_DIGITS] = MaybeUninit::uninit_array(); - let mut parts: [MaybeUninit>; 4] = MaybeUninit::uninit_array(); - let formatted = flt2dec::to_shortest_str( - flt2dec::strategy::grisu::format_shortest, - *num, - sign, - precision, - &mut buf, - &mut parts, - ); - // SAFETY: `to_shortest_str` and `format_shortest` produce only ASCII characters. - unsafe { fmt.pad_formatted_parts(&formatted) } -} - -fn float_to_decimal_display(fmt: &mut Formatter<'_>, num: &T) -> Result -where - T: flt2dec::DecodableFloat, -{ - let force_sign = fmt.sign_plus(); - let sign = match force_sign { - false => flt2dec::Sign::Minus, - true => flt2dec::Sign::MinusPlus, - }; - - if let Some(precision) = fmt.precision { - float_to_decimal_common_exact(fmt, num, sign, precision) - } else { - let min_precision = 0; - float_to_decimal_common_shortest(fmt, num, sign, min_precision) - } -} - -// Don't inline this so callers don't use the stack space this function -// requires unless they have to. -#[inline(never)] -fn float_to_exponential_common_exact( - fmt: &mut Formatter<'_>, - num: &T, - sign: flt2dec::Sign, - precision: usize, - upper: bool, -) -> Result -where - T: flt2dec::DecodableFloat, -{ - let mut buf: [MaybeUninit; 1024] = MaybeUninit::uninit_array(); // enough for f32 and f64 - let mut parts: [MaybeUninit>; 6] = MaybeUninit::uninit_array(); - let formatted = flt2dec::to_exact_exp_str( - flt2dec::strategy::grisu::format_exact, - *num, - sign, - precision, - upper, - &mut buf, - &mut parts, - ); - // SAFETY: `to_exact_exp_str` and `format_exact` produce only ASCII characters. - unsafe { fmt.pad_formatted_parts(&formatted) } -} - -// Don't inline this so callers that call both this and the above won't wind -// up using the combined stack space of both functions in some cases. -#[inline(never)] -fn float_to_exponential_common_shortest( - fmt: &mut Formatter<'_>, - num: &T, - sign: flt2dec::Sign, - upper: bool, -) -> Result -where - T: flt2dec::DecodableFloat, -{ - // enough for f32 and f64 - let mut buf: [MaybeUninit; flt2dec::MAX_SIG_DIGITS] = MaybeUninit::uninit_array(); - let mut parts: [MaybeUninit>; 6] = MaybeUninit::uninit_array(); - let formatted = flt2dec::to_shortest_exp_str( - flt2dec::strategy::grisu::format_shortest, - *num, - sign, - (0, 0), - upper, - &mut buf, - &mut parts, - ); - // SAFETY: `to_shortest_exp_str` and `format_shortest` produce only ASCII characters. - unsafe { fmt.pad_formatted_parts(&formatted) } -} - -// Common code of floating point LowerExp and UpperExp. -fn float_to_exponential_common(fmt: &mut Formatter<'_>, num: &T, upper: bool) -> Result -where - T: flt2dec::DecodableFloat, -{ - let force_sign = fmt.sign_plus(); - let sign = match force_sign { - false => flt2dec::Sign::Minus, - true => flt2dec::Sign::MinusPlus, - }; - - if let Some(precision) = fmt.precision { - // 1 integral digit + `precision` fractional digits = `precision + 1` total digits - float_to_exponential_common_exact(fmt, num, sign, precision + 1, upper) - } else { - float_to_exponential_common_shortest(fmt, num, sign, upper) - } -} - -fn float_to_general_debug(fmt: &mut Formatter<'_>, num: &T) -> Result -where - T: flt2dec::DecodableFloat + GeneralFormat, -{ - let force_sign = fmt.sign_plus(); - let sign = match force_sign { - false => flt2dec::Sign::Minus, - true => flt2dec::Sign::MinusPlus, - }; - - if let Some(precision) = fmt.precision { - // this behavior of {:.PREC?} predates exponential formatting for {:?} - float_to_decimal_common_exact(fmt, num, sign, precision) - } else { - // since there is no precision, there will be no rounding - if num.already_rounded_value_should_use_exponential() { - let upper = false; - float_to_exponential_common_shortest(fmt, num, sign, upper) - } else { - let min_precision = 1; - float_to_decimal_common_shortest(fmt, num, sign, min_precision) - } - } -} - -macro_rules! floating { - ($ty:ident) => { - #[stable(feature = "rust1", since = "1.0.0")] - impl Debug for $ty { - fn fmt(&self, fmt: &mut Formatter<'_>) -> Result { - float_to_general_debug(fmt, self) - } - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl Display for $ty { - fn fmt(&self, fmt: &mut Formatter<'_>) -> Result { - float_to_decimal_display(fmt, self) - } - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl LowerExp for $ty { - fn fmt(&self, fmt: &mut Formatter<'_>) -> Result { - float_to_exponential_common(fmt, self, false) - } - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl UpperExp for $ty { - fn fmt(&self, fmt: &mut Formatter<'_>) -> Result { - float_to_exponential_common(fmt, self, true) - } - } - }; -} - -floating! { f32 } -floating! { f64 } - -#[stable(feature = "rust1", since = "1.0.0")] -impl Debug for f16 { - #[inline] - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - write!(f, "{:#06x}", self.to_bits()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Debug for f128 { - #[inline] - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - write!(f, "{:#034x}", self.to_bits()) - } -} diff --git a/library/core/src/fmt/fmt_trait_method_doc.md b/library/core/src/fmt/fmt_trait_method_doc.md deleted file mode 100644 index 493d929243d2d..0000000000000 --- a/library/core/src/fmt/fmt_trait_method_doc.md +++ /dev/null @@ -1,8 +0,0 @@ -Formats the value using the given formatter. - -# Errors - -This function should return [`Err`] if, and only if, the provided [`Formatter`] returns [`Err`]. -String formatting is considered an infallible operation; this function only -returns a [`Result`] because writing to the underlying stream might fail and it must -provide a way to propagate the fact that an error has occurred back up the stack. diff --git a/library/core/src/fmt/mod.rs b/library/core/src/fmt/mod.rs deleted file mode 100644 index 1324fb6e056be..0000000000000 --- a/library/core/src/fmt/mod.rs +++ /dev/null @@ -1,2676 +0,0 @@ -//! Utilities for formatting and printing strings. - -#![stable(feature = "rust1", since = "1.0.0")] - -use crate::cell::{Cell, Ref, RefCell, RefMut, SyncUnsafeCell, UnsafeCell}; -use crate::char::EscapeDebugExtArgs; -use crate::iter; -use crate::marker::PhantomData; -use crate::mem; -use crate::num::fmt as numfmt; -use crate::ops::Deref; -use crate::result; -use crate::str; - -mod builders; -#[cfg(not(no_fp_fmt_parse))] -mod float; -#[cfg(no_fp_fmt_parse)] -mod nofloat; -mod num; -mod rt; - -#[stable(feature = "fmt_flags_align", since = "1.28.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "Alignment")] -/// Possible alignments returned by `Formatter::align` -#[derive(Copy, Clone, Debug, PartialEq, Eq)] -pub enum Alignment { - #[stable(feature = "fmt_flags_align", since = "1.28.0")] - /// Indication that contents should be left-aligned. - Left, - #[stable(feature = "fmt_flags_align", since = "1.28.0")] - /// Indication that contents should be right-aligned. - Right, - #[stable(feature = "fmt_flags_align", since = "1.28.0")] - /// Indication that contents should be center-aligned. - Center, -} - -#[stable(feature = "debug_builders", since = "1.2.0")] -pub use self::builders::{DebugList, DebugMap, DebugSet, DebugStruct, DebugTuple}; - -#[unstable(feature = "debug_closure_helpers", issue = "117729")] -pub use self::builders::FormatterFn; - -/// The type returned by formatter methods. -/// -/// # Examples -/// -/// ``` -/// use std::fmt; -/// -/// #[derive(Debug)] -/// struct Triangle { -/// a: f32, -/// b: f32, -/// c: f32 -/// } -/// -/// impl fmt::Display for Triangle { -/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { -/// write!(f, "({}, {}, {})", self.a, self.b, self.c) -/// } -/// } -/// -/// let pythagorean_triple = Triangle { a: 3.0, b: 4.0, c: 5.0 }; -/// -/// assert_eq!(format!("{pythagorean_triple}"), "(3, 4, 5)"); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub type Result = result::Result<(), Error>; - -/// The error type which is returned from formatting a message into a stream. -/// -/// This type does not support transmission of an error other than that an error -/// occurred. This is because, despite the existence of this error, -/// string formatting is considered an infallible operation. -/// `fmt()` implementors should not return this `Error` unless they received it from their -/// [`Formatter`]. The only time your code should create a new instance of this -/// error is when implementing `fmt::Write`, in order to cancel the formatting operation when -/// writing to the underlying stream fails. -/// -/// Any extra information must be arranged to be transmitted through some other means, -/// such as storing it in a field to be consulted after the formatting operation has been -/// cancelled. (For example, this is how [`std::io::Write::write_fmt()`] propagates IO errors -/// during writing.) -/// -/// This type, `fmt::Error`, should not be -/// confused with [`std::io::Error`] or [`std::error::Error`], which you may also -/// have in scope. -/// -/// [`std::io::Error`]: ../../std/io/struct.Error.html -/// [`std::io::Write::write_fmt()`]: ../../std/io/trait.Write.html#method.write_fmt -/// [`std::error::Error`]: ../../std/error/trait.Error.html -/// -/// # Examples -/// -/// ```rust -/// use std::fmt::{self, write}; -/// -/// let mut output = String::new(); -/// if let Err(fmt::Error) = write(&mut output, format_args!("Hello {}!", "world")) { -/// panic!("An error occurred"); -/// } -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Copy, Clone, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd)] -pub struct Error; - -/// A trait for writing or formatting into Unicode-accepting buffers or streams. -/// -/// This trait only accepts UTF-8–encoded data and is not [flushable]. If you only -/// want to accept Unicode and you don't need flushing, you should implement this trait; -/// otherwise you should implement [`std::io::Write`]. -/// -/// [`std::io::Write`]: ../../std/io/trait.Write.html -/// [flushable]: ../../std/io/trait.Write.html#tymethod.flush -#[stable(feature = "rust1", since = "1.0.0")] -pub trait Write { - /// Writes a string slice into this writer, returning whether the write - /// succeeded. - /// - /// This method can only succeed if the entire string slice was successfully - /// written, and this method will not return until all data has been - /// written or an error occurs. - /// - /// # Errors - /// - /// This function will return an instance of [`std::fmt::Error`][Error] on error. - /// - /// The purpose of that error is to abort the formatting operation when the underlying - /// destination encounters some error preventing it from accepting more text; - /// in particular, it does not communicate any information about *what* error occurred. - /// It should generally be propagated rather than handled, at least when implementing - /// formatting traits. - /// - /// # Examples - /// - /// ``` - /// use std::fmt::{Error, Write}; - /// - /// fn writer(f: &mut W, s: &str) -> Result<(), Error> { - /// f.write_str(s) - /// } - /// - /// let mut buf = String::new(); - /// writer(&mut buf, "hola").unwrap(); - /// assert_eq!(&buf, "hola"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn write_str(&mut self, s: &str) -> Result; - - /// Writes a [`char`] into this writer, returning whether the write succeeded. - /// - /// A single [`char`] may be encoded as more than one byte. - /// This method can only succeed if the entire byte sequence was successfully - /// written, and this method will not return until all data has been - /// written or an error occurs. - /// - /// # Errors - /// - /// This function will return an instance of [`Error`] on error. - /// - /// # Examples - /// - /// ``` - /// use std::fmt::{Error, Write}; - /// - /// fn writer(f: &mut W, c: char) -> Result<(), Error> { - /// f.write_char(c) - /// } - /// - /// let mut buf = String::new(); - /// writer(&mut buf, 'a').unwrap(); - /// writer(&mut buf, 'b').unwrap(); - /// assert_eq!(&buf, "ab"); - /// ``` - #[stable(feature = "fmt_write_char", since = "1.1.0")] - fn write_char(&mut self, c: char) -> Result { - self.write_str(c.encode_utf8(&mut [0; 4])) - } - - /// Glue for usage of the [`write!`] macro with implementors of this trait. - /// - /// This method should generally not be invoked manually, but rather through - /// the [`write!`] macro itself. - /// - /// # Errors - /// - /// This function will return an instance of [`Error`] on error. Please see - /// [write_str](Write::write_str) for details. - /// - /// # Examples - /// - /// ``` - /// use std::fmt::{Error, Write}; - /// - /// fn writer(f: &mut W, s: &str) -> Result<(), Error> { - /// f.write_fmt(format_args!("{s}")) - /// } - /// - /// let mut buf = String::new(); - /// writer(&mut buf, "world").unwrap(); - /// assert_eq!(&buf, "world"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn write_fmt(&mut self, args: Arguments<'_>) -> Result { - // We use a specialization for `Sized` types to avoid an indirection - // through `&mut self` - trait SpecWriteFmt { - fn spec_write_fmt(self, args: Arguments<'_>) -> Result; - } - - impl SpecWriteFmt for &mut W { - #[inline] - default fn spec_write_fmt(mut self, args: Arguments<'_>) -> Result { - if let Some(s) = args.as_statically_known_str() { - self.write_str(s) - } else { - write(&mut self, args) - } - } - } - - impl SpecWriteFmt for &mut W { - #[inline] - fn spec_write_fmt(self, args: Arguments<'_>) -> Result { - if let Some(s) = args.as_statically_known_str() { - self.write_str(s) - } else { - write(self, args) - } - } - } - - self.spec_write_fmt(args) - } -} - -#[stable(feature = "fmt_write_blanket_impl", since = "1.4.0")] -impl Write for &mut W { - fn write_str(&mut self, s: &str) -> Result { - (**self).write_str(s) - } - - fn write_char(&mut self, c: char) -> Result { - (**self).write_char(c) - } - - fn write_fmt(&mut self, args: Arguments<'_>) -> Result { - (**self).write_fmt(args) - } -} - -/// Configuration for formatting. -/// -/// A `Formatter` represents various options related to formatting. Users do not -/// construct `Formatter`s directly; a mutable reference to one is passed to -/// the `fmt` method of all formatting traits, like [`Debug`] and [`Display`]. -/// -/// To interact with a `Formatter`, you'll call various methods to change the -/// various options related to formatting. For examples, please see the -/// documentation of the methods defined on `Formatter` below. -#[allow(missing_debug_implementations)] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_diagnostic_item = "Formatter"] -pub struct Formatter<'a> { - flags: u32, - fill: char, - align: rt::Alignment, - width: Option, - precision: Option, - - buf: &'a mut (dyn Write + 'a), -} - -impl<'a> Formatter<'a> { - /// Creates a new formatter with default settings. - /// - /// This can be used as a micro-optimization in cases where a full `Arguments` - /// structure (as created by `format_args!`) is not necessary; `Arguments` - /// is a little more expensive to use in simple formatting scenarios. - /// - /// Currently not intended for use outside of the standard library. - #[unstable(feature = "fmt_internals", reason = "internal to standard library", issue = "none")] - #[doc(hidden)] - pub fn new(buf: &'a mut (dyn Write + 'a)) -> Formatter<'a> { - Formatter { - flags: 0, - fill: ' ', - align: rt::Alignment::Unknown, - width: None, - precision: None, - buf, - } - } -} - -/// This structure represents a safely precompiled version of a format string -/// and its arguments. This cannot be generated at runtime because it cannot -/// safely be done, so no constructors are given and the fields are private -/// to prevent modification. -/// -/// The [`format_args!`] macro will safely create an instance of this structure. -/// The macro validates the format string at compile-time so usage of the -/// [`write()`] and [`format()`] functions can be safely performed. -/// -/// You can use the `Arguments<'a>` that [`format_args!`] returns in `Debug` -/// and `Display` contexts as seen below. The example also shows that `Debug` -/// and `Display` format to the same thing: the interpolated format string -/// in `format_args!`. -/// -/// ```rust -/// let debug = format!("{:?}", format_args!("{} foo {:?}", 1, 2)); -/// let display = format!("{}", format_args!("{} foo {:?}", 1, 2)); -/// assert_eq!("1 foo 2", display); -/// assert_eq!(display, debug); -/// ``` -/// -/// [`format()`]: ../../std/fmt/fn.format.html -#[lang = "format_arguments"] -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Copy, Clone)] -pub struct Arguments<'a> { - // Format string pieces to print. - pieces: &'a [&'static str], - - // Placeholder specs, or `None` if all specs are default (as in "{}{}"). - fmt: Option<&'a [rt::Placeholder]>, - - // Dynamic arguments for interpolation, to be interleaved with string - // pieces. (Every argument is preceded by a string piece.) - args: &'a [rt::Argument<'a>], -} - -/// Used by the format_args!() macro to create a fmt::Arguments object. -#[doc(hidden)] -#[unstable(feature = "fmt_internals", issue = "none")] -impl<'a> Arguments<'a> { - #[inline] - #[rustc_const_unstable(feature = "const_fmt_arguments_new", issue = "none")] - pub const fn new_const(pieces: &'a [&'static str]) -> Self { - if pieces.len() > 1 { - // Since panic!() expands to panic_fmt(format_args!()), using panic! here is both a - // bit silly and also significantly increases the amount of MIR generated by panics. - crate::panicking::panic_nounwind("invalid args"); - } - Arguments { pieces, fmt: None, args: &[] } - } - - /// When using the format_args!() macro, this function is used to generate the - /// Arguments structure. - #[inline] - pub fn new_v1(pieces: &'a [&'static str], args: &'a [rt::Argument<'a>]) -> Arguments<'a> { - if pieces.len() < args.len() || pieces.len() > args.len() + 1 { - // See Arguments::new_const for why we don't use panic!. - crate::panicking::panic_nounwind("invalid args"); - } - Arguments { pieces, fmt: None, args } - } - - /// This function is used to specify nonstandard formatting parameters. - /// - /// An `rt::UnsafeArg` is required because the following invariants must be held - /// in order for this function to be safe: - /// 1. The `pieces` slice must be at least as long as `fmt`. - /// 2. Every `rt::Placeholder::position` value within `fmt` must be a valid index of `args`. - /// 3. Every `rt::Count::Param` within `fmt` must contain a valid index of `args`. - #[inline] - pub fn new_v1_formatted( - pieces: &'a [&'static str], - args: &'a [rt::Argument<'a>], - fmt: &'a [rt::Placeholder], - _unsafe_arg: rt::UnsafeArg, - ) -> Arguments<'a> { - Arguments { pieces, fmt: Some(fmt), args } - } - - /// Estimates the length of the formatted text. - /// - /// This is intended to be used for setting initial `String` capacity - /// when using `format!`. Note: this is neither the lower nor upper bound. - #[inline] - pub fn estimated_capacity(&self) -> usize { - let pieces_length: usize = self.pieces.iter().map(|x| x.len()).sum(); - - if self.args.is_empty() { - pieces_length - } else if !self.pieces.is_empty() && self.pieces[0].is_empty() && pieces_length < 16 { - // If the format string starts with an argument, - // don't preallocate anything, unless length - // of pieces is significant. - 0 - } else { - // There are some arguments, so any additional push - // will reallocate the string. To avoid that, - // we're "pre-doubling" the capacity here. - pieces_length.checked_mul(2).unwrap_or(0) - } - } -} - -impl<'a> Arguments<'a> { - /// Get the formatted string, if it has no arguments to be formatted at runtime. - /// - /// This can be used to avoid allocations in some cases. - /// - /// # Guarantees - /// - /// For `format_args!("just a literal")`, this function is guaranteed to - /// return `Some("just a literal")`. - /// - /// For most cases with placeholders, this function will return `None`. - /// - /// However, the compiler may perform optimizations that can cause this - /// function to return `Some(_)` even if the format string contains - /// placeholders. For example, `format_args!("Hello, {}!", "world")` may be - /// optimized to `format_args!("Hello, world!")`, such that `as_str()` - /// returns `Some("Hello, world!")`. - /// - /// The behavior for anything but the trivial case (without placeholders) - /// is not guaranteed, and should not be relied upon for anything other - /// than optimization. - /// - /// # Examples - /// - /// ```rust - /// use std::fmt::Arguments; - /// - /// fn write_str(_: &str) { /* ... */ } - /// - /// fn write_fmt(args: &Arguments<'_>) { - /// if let Some(s) = args.as_str() { - /// write_str(s) - /// } else { - /// write_str(&args.to_string()); - /// } - /// } - /// ``` - /// - /// ```rust - /// assert_eq!(format_args!("hello").as_str(), Some("hello")); - /// assert_eq!(format_args!("").as_str(), Some("")); - /// assert_eq!(format_args!("{:?}", std::env::current_dir()).as_str(), None); - /// ``` - #[stable(feature = "fmt_as_str", since = "1.52.0")] - #[rustc_const_unstable(feature = "const_arguments_as_str", issue = "103900")] - #[must_use] - #[inline] - pub const fn as_str(&self) -> Option<&'static str> { - match (self.pieces, self.args) { - ([], []) => Some(""), - ([s], []) => Some(s), - _ => None, - } - } - - /// Same as [`Arguments::as_str`], but will only return `Some(s)` if it can be determined at compile time. - #[must_use] - #[inline] - fn as_statically_known_str(&self) -> Option<&'static str> { - let s = self.as_str(); - if core::intrinsics::is_val_statically_known(s.is_some()) { s } else { None } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Debug for Arguments<'_> { - fn fmt(&self, fmt: &mut Formatter<'_>) -> Result { - Display::fmt(self, fmt) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Display for Arguments<'_> { - fn fmt(&self, fmt: &mut Formatter<'_>) -> Result { - write(fmt.buf, *self) - } -} - -/// `?` formatting. -/// -/// `Debug` should format the output in a programmer-facing, debugging context. -/// -/// Generally speaking, you should just `derive` a `Debug` implementation. -/// -/// When used with the alternate format specifier `#?`, the output is pretty-printed. -/// -/// For more information on formatters, see [the module-level documentation][module]. -/// -/// [module]: ../../std/fmt/index.html -/// -/// This trait can be used with `#[derive]` if all fields implement `Debug`. When -/// `derive`d for structs, it will use the name of the `struct`, then `{`, then a -/// comma-separated list of each field's name and `Debug` value, then `}`. For -/// `enum`s, it will use the name of the variant and, if applicable, `(`, then the -/// `Debug` values of the fields, then `)`. -/// -/// # Stability -/// -/// Derived `Debug` formats are not stable, and so may change with future Rust -/// versions. Additionally, `Debug` implementations of types provided by the -/// standard library (`std`, `core`, `alloc`, etc.) are not stable, and -/// may also change with future Rust versions. -/// -/// # Examples -/// -/// Deriving an implementation: -/// -/// ``` -/// #[derive(Debug)] -/// struct Point { -/// x: i32, -/// y: i32, -/// } -/// -/// let origin = Point { x: 0, y: 0 }; -/// -/// assert_eq!(format!("The origin is: {origin:?}"), "The origin is: Point { x: 0, y: 0 }"); -/// ``` -/// -/// Manually implementing: -/// -/// ``` -/// use std::fmt; -/// -/// struct Point { -/// x: i32, -/// y: i32, -/// } -/// -/// impl fmt::Debug for Point { -/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { -/// f.debug_struct("Point") -/// .field("x", &self.x) -/// .field("y", &self.y) -/// .finish() -/// } -/// } -/// -/// let origin = Point { x: 0, y: 0 }; -/// -/// assert_eq!(format!("The origin is: {origin:?}"), "The origin is: Point { x: 0, y: 0 }"); -/// ``` -/// -/// There are a number of helper methods on the [`Formatter`] struct to help you with manual -/// implementations, such as [`debug_struct`]. -/// -/// [`debug_struct`]: Formatter::debug_struct -/// -/// Types that do not wish to use the standard suite of debug representations -/// provided by the `Formatter` trait (`debug_struct`, `debug_tuple`, -/// `debug_list`, `debug_set`, `debug_map`) can do something totally custom by -/// manually writing an arbitrary representation to the `Formatter`. -/// -/// ``` -/// # use std::fmt; -/// # struct Point { -/// # x: i32, -/// # y: i32, -/// # } -/// # -/// impl fmt::Debug for Point { -/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { -/// write!(f, "Point [{} {}]", self.x, self.y) -/// } -/// } -/// ``` -/// -/// `Debug` implementations using either `derive` or the debug builder API -/// on [`Formatter`] support pretty-printing using the alternate flag: `{:#?}`. -/// -/// Pretty-printing with `#?`: -/// -/// ``` -/// #[derive(Debug)] -/// struct Point { -/// x: i32, -/// y: i32, -/// } -/// -/// let origin = Point { x: 0, y: 0 }; -/// -/// assert_eq!(format!("The origin is: {origin:#?}"), -/// "The origin is: Point { -/// x: 0, -/// y: 0, -/// }"); -/// ``` - -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_on_unimplemented( - on( - crate_local, - label = "`{Self}` cannot be formatted using `{{:?}}`", - note = "add `#[derive(Debug)]` to `{Self}` or manually `impl {Debug} for {Self}`" - ), - message = "`{Self}` doesn't implement `{Debug}`", - label = "`{Self}` cannot be formatted using `{{:?}}` because it doesn't implement `{Debug}`" -)] -#[doc(alias = "{:?}")] -#[rustc_diagnostic_item = "Debug"] -#[rustc_trivial_field_reads] -pub trait Debug { - #[doc = include_str!("fmt_trait_method_doc.md")] - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Position { - /// longitude: f32, - /// latitude: f32, - /// } - /// - /// impl fmt::Debug for Position { - /// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - /// f.debug_tuple("") - /// .field(&self.longitude) - /// .field(&self.latitude) - /// .finish() - /// } - /// } - /// - /// let position = Position { longitude: 1.987, latitude: 2.983 }; - /// assert_eq!(format!("{position:?}"), "(1.987, 2.983)"); - /// - /// assert_eq!(format!("{position:#?}"), "( - /// 1.987, - /// 2.983, - /// )"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn fmt(&self, f: &mut Formatter<'_>) -> Result; -} - -// Separate module to reexport the macro `Debug` from prelude without the trait `Debug`. -pub(crate) mod macros { - /// Derive macro generating an impl of the trait `Debug`. - #[rustc_builtin_macro] - #[stable(feature = "builtin_macro_prelude", since = "1.38.0")] - #[allow_internal_unstable(core_intrinsics, fmt_helpers_for_derive)] - pub macro Debug($item:item) { - /* compiler built-in */ - } -} -#[stable(feature = "builtin_macro_prelude", since = "1.38.0")] -#[doc(inline)] -pub use macros::Debug; - -/// Format trait for an empty format, `{}`. -/// -/// Implementing this trait for a type will automatically implement the -/// [`ToString`][tostring] trait for the type, allowing the usage -/// of the [`.to_string()`][tostring_function] method. Prefer implementing -/// the `Display` trait for a type, rather than [`ToString`][tostring]. -/// -/// `Display` is similar to [`Debug`], but `Display` is for user-facing -/// output, and so cannot be derived. -/// -/// For more information on formatters, see [the module-level documentation][module]. -/// -/// [module]: ../../std/fmt/index.html -/// [tostring]: ../../std/string/trait.ToString.html -/// [tostring_function]: ../../std/string/trait.ToString.html#tymethod.to_string -/// -/// # Internationalization -/// -/// Because a type can only have one `Display` implementation, it is often preferable -/// to only implement `Display` when there is a single most "obvious" way that -/// values can be formatted as text. This could mean formatting according to the -/// "invariant" culture and "undefined" locale, or it could mean that the type -/// display is designed for a specific culture/locale, such as developer logs. -/// -/// If not all values have a justifiably canonical textual format or if you want -/// to support alternative formats not covered by the standard set of possible -/// [formatting traits], the most flexible approach is display adapters: methods -/// like [`str::escape_default`] or [`Path::display`] which create a wrapper -/// implementing `Display` to output the specific display format. -/// -/// [formatting traits]: ../../std/fmt/index.html#formatting-traits -/// [`Path::display`]: ../../std/path/struct.Path.html#method.display -/// -/// # Examples -/// -/// Implementing `Display` on a type: -/// -/// ``` -/// use std::fmt; -/// -/// struct Point { -/// x: i32, -/// y: i32, -/// } -/// -/// impl fmt::Display for Point { -/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { -/// write!(f, "({}, {})", self.x, self.y) -/// } -/// } -/// -/// let origin = Point { x: 0, y: 0 }; -/// -/// assert_eq!(format!("The origin is: {origin}"), "The origin is: (0, 0)"); -/// ``` -#[rustc_on_unimplemented( - on( - any(_Self = "std::path::Path", _Self = "std::path::PathBuf"), - label = "`{Self}` cannot be formatted with the default formatter; call `.display()` on it", - note = "call `.display()` or `.to_string_lossy()` to safely print paths, \ - as they may contain non-Unicode data" - ), - message = "`{Self}` doesn't implement `{Display}`", - label = "`{Self}` cannot be formatted with the default formatter", - note = "in format strings you may be able to use `{{:?}}` (or {{:#?}} for pretty-print) instead" -)] -#[doc(alias = "{}")] -#[rustc_diagnostic_item = "Display"] -#[stable(feature = "rust1", since = "1.0.0")] -pub trait Display { - #[doc = include_str!("fmt_trait_method_doc.md")] - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Position { - /// longitude: f32, - /// latitude: f32, - /// } - /// - /// impl fmt::Display for Position { - /// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - /// write!(f, "({}, {})", self.longitude, self.latitude) - /// } - /// } - /// - /// assert_eq!("(1.987, 2.983)", - /// format!("{}", Position { longitude: 1.987, latitude: 2.983, })); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn fmt(&self, f: &mut Formatter<'_>) -> Result; -} - -/// `o` formatting. -/// -/// The `Octal` trait should format its output as a number in base-8. -/// -/// For primitive signed integers (`i8` to `i128`, and `isize`), -/// negative values are formatted as the two’s complement representation. -/// -/// The alternate flag, `#`, adds a `0o` in front of the output. -/// -/// For more information on formatters, see [the module-level documentation][module]. -/// -/// [module]: ../../std/fmt/index.html -/// -/// # Examples -/// -/// Basic usage with `i32`: -/// -/// ``` -/// let x = 42; // 42 is '52' in octal -/// -/// assert_eq!(format!("{x:o}"), "52"); -/// assert_eq!(format!("{x:#o}"), "0o52"); -/// -/// assert_eq!(format!("{:o}", -16), "37777777760"); -/// ``` -/// -/// Implementing `Octal` on a type: -/// -/// ``` -/// use std::fmt; -/// -/// struct Length(i32); -/// -/// impl fmt::Octal for Length { -/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { -/// let val = self.0; -/// -/// fmt::Octal::fmt(&val, f) // delegate to i32's implementation -/// } -/// } -/// -/// let l = Length(9); -/// -/// assert_eq!(format!("l as octal is: {l:o}"), "l as octal is: 11"); -/// -/// assert_eq!(format!("l as octal is: {l:#06o}"), "l as octal is: 0o0011"); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub trait Octal { - #[doc = include_str!("fmt_trait_method_doc.md")] - #[stable(feature = "rust1", since = "1.0.0")] - fn fmt(&self, f: &mut Formatter<'_>) -> Result; -} - -/// `b` formatting. -/// -/// The `Binary` trait should format its output as a number in binary. -/// -/// For primitive signed integers ([`i8`] to [`i128`], and [`isize`]), -/// negative values are formatted as the two’s complement representation. -/// -/// The alternate flag, `#`, adds a `0b` in front of the output. -/// -/// For more information on formatters, see [the module-level documentation][module]. -/// -/// [module]: ../../std/fmt/index.html -/// -/// # Examples -/// -/// Basic usage with [`i32`]: -/// -/// ``` -/// let x = 42; // 42 is '101010' in binary -/// -/// assert_eq!(format!("{x:b}"), "101010"); -/// assert_eq!(format!("{x:#b}"), "0b101010"); -/// -/// assert_eq!(format!("{:b}", -16), "11111111111111111111111111110000"); -/// ``` -/// -/// Implementing `Binary` on a type: -/// -/// ``` -/// use std::fmt; -/// -/// struct Length(i32); -/// -/// impl fmt::Binary for Length { -/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { -/// let val = self.0; -/// -/// fmt::Binary::fmt(&val, f) // delegate to i32's implementation -/// } -/// } -/// -/// let l = Length(107); -/// -/// assert_eq!(format!("l as binary is: {l:b}"), "l as binary is: 1101011"); -/// -/// assert_eq!( -/// // Note that the `0b` prefix added by `#` is included in the total width, so we -/// // need to add two to correctly display all 32 bits. -/// format!("l as binary is: {l:#034b}"), -/// "l as binary is: 0b00000000000000000000000001101011" -/// ); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub trait Binary { - #[doc = include_str!("fmt_trait_method_doc.md")] - #[stable(feature = "rust1", since = "1.0.0")] - fn fmt(&self, f: &mut Formatter<'_>) -> Result; -} - -/// `x` formatting. -/// -/// The `LowerHex` trait should format its output as a number in hexadecimal, with `a` through `f` -/// in lower case. -/// -/// For primitive signed integers (`i8` to `i128`, and `isize`), -/// negative values are formatted as the two’s complement representation. -/// -/// The alternate flag, `#`, adds a `0x` in front of the output. -/// -/// For more information on formatters, see [the module-level documentation][module]. -/// -/// [module]: ../../std/fmt/index.html -/// -/// # Examples -/// -/// Basic usage with `i32`: -/// -/// ``` -/// let y = 42; // 42 is '2a' in hex -/// -/// assert_eq!(format!("{y:x}"), "2a"); -/// assert_eq!(format!("{y:#x}"), "0x2a"); -/// -/// assert_eq!(format!("{:x}", -16), "fffffff0"); -/// ``` -/// -/// Implementing `LowerHex` on a type: -/// -/// ``` -/// use std::fmt; -/// -/// struct Length(i32); -/// -/// impl fmt::LowerHex for Length { -/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { -/// let val = self.0; -/// -/// fmt::LowerHex::fmt(&val, f) // delegate to i32's implementation -/// } -/// } -/// -/// let l = Length(9); -/// -/// assert_eq!(format!("l as hex is: {l:x}"), "l as hex is: 9"); -/// -/// assert_eq!(format!("l as hex is: {l:#010x}"), "l as hex is: 0x00000009"); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub trait LowerHex { - #[doc = include_str!("fmt_trait_method_doc.md")] - #[stable(feature = "rust1", since = "1.0.0")] - fn fmt(&self, f: &mut Formatter<'_>) -> Result; -} - -/// `X` formatting. -/// -/// The `UpperHex` trait should format its output as a number in hexadecimal, with `A` through `F` -/// in upper case. -/// -/// For primitive signed integers (`i8` to `i128`, and `isize`), -/// negative values are formatted as the two’s complement representation. -/// -/// The alternate flag, `#`, adds a `0x` in front of the output. -/// -/// For more information on formatters, see [the module-level documentation][module]. -/// -/// [module]: ../../std/fmt/index.html -/// -/// # Examples -/// -/// Basic usage with `i32`: -/// -/// ``` -/// let y = 42; // 42 is '2A' in hex -/// -/// assert_eq!(format!("{y:X}"), "2A"); -/// assert_eq!(format!("{y:#X}"), "0x2A"); -/// -/// assert_eq!(format!("{:X}", -16), "FFFFFFF0"); -/// ``` -/// -/// Implementing `UpperHex` on a type: -/// -/// ``` -/// use std::fmt; -/// -/// struct Length(i32); -/// -/// impl fmt::UpperHex for Length { -/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { -/// let val = self.0; -/// -/// fmt::UpperHex::fmt(&val, f) // delegate to i32's implementation -/// } -/// } -/// -/// let l = Length(i32::MAX); -/// -/// assert_eq!(format!("l as hex is: {l:X}"), "l as hex is: 7FFFFFFF"); -/// -/// assert_eq!(format!("l as hex is: {l:#010X}"), "l as hex is: 0x7FFFFFFF"); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub trait UpperHex { - #[doc = include_str!("fmt_trait_method_doc.md")] - #[stable(feature = "rust1", since = "1.0.0")] - fn fmt(&self, f: &mut Formatter<'_>) -> Result; -} - -/// `p` formatting. -/// -/// The `Pointer` trait should format its output as a memory location. This is commonly presented -/// as hexadecimal. -/// -/// For more information on formatters, see [the module-level documentation][module]. -/// -/// [module]: ../../std/fmt/index.html -/// -/// # Examples -/// -/// Basic usage with `&i32`: -/// -/// ``` -/// let x = &42; -/// -/// let address = format!("{x:p}"); // this produces something like '0x7f06092ac6d0' -/// ``` -/// -/// Implementing `Pointer` on a type: -/// -/// ``` -/// use std::fmt; -/// -/// struct Length(i32); -/// -/// impl fmt::Pointer for Length { -/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { -/// // use `as` to convert to a `*const T`, which implements Pointer, which we can use -/// -/// let ptr = self as *const Self; -/// fmt::Pointer::fmt(&ptr, f) -/// } -/// } -/// -/// let l = Length(42); -/// -/// println!("l is in memory here: {l:p}"); -/// -/// let l_ptr = format!("{l:018p}"); -/// assert_eq!(l_ptr.len(), 18); -/// assert_eq!(&l_ptr[..2], "0x"); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_diagnostic_item = "Pointer"] -pub trait Pointer { - #[doc = include_str!("fmt_trait_method_doc.md")] - #[stable(feature = "rust1", since = "1.0.0")] - fn fmt(&self, f: &mut Formatter<'_>) -> Result; -} - -/// `e` formatting. -/// -/// The `LowerExp` trait should format its output in scientific notation with a lower-case `e`. -/// -/// For more information on formatters, see [the module-level documentation][module]. -/// -/// [module]: ../../std/fmt/index.html -/// -/// # Examples -/// -/// Basic usage with `f64`: -/// -/// ``` -/// let x = 42.0; // 42.0 is '4.2e1' in scientific notation -/// -/// assert_eq!(format!("{x:e}"), "4.2e1"); -/// ``` -/// -/// Implementing `LowerExp` on a type: -/// -/// ``` -/// use std::fmt; -/// -/// struct Length(i32); -/// -/// impl fmt::LowerExp for Length { -/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { -/// let val = f64::from(self.0); -/// fmt::LowerExp::fmt(&val, f) // delegate to f64's implementation -/// } -/// } -/// -/// let l = Length(100); -/// -/// assert_eq!( -/// format!("l in scientific notation is: {l:e}"), -/// "l in scientific notation is: 1e2" -/// ); -/// -/// assert_eq!( -/// format!("l in scientific notation is: {l:05e}"), -/// "l in scientific notation is: 001e2" -/// ); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub trait LowerExp { - #[doc = include_str!("fmt_trait_method_doc.md")] - #[stable(feature = "rust1", since = "1.0.0")] - fn fmt(&self, f: &mut Formatter<'_>) -> Result; -} - -/// `E` formatting. -/// -/// The `UpperExp` trait should format its output in scientific notation with an upper-case `E`. -/// -/// For more information on formatters, see [the module-level documentation][module]. -/// -/// [module]: ../../std/fmt/index.html -/// -/// # Examples -/// -/// Basic usage with `f64`: -/// -/// ``` -/// let x = 42.0; // 42.0 is '4.2E1' in scientific notation -/// -/// assert_eq!(format!("{x:E}"), "4.2E1"); -/// ``` -/// -/// Implementing `UpperExp` on a type: -/// -/// ``` -/// use std::fmt; -/// -/// struct Length(i32); -/// -/// impl fmt::UpperExp for Length { -/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { -/// let val = f64::from(self.0); -/// fmt::UpperExp::fmt(&val, f) // delegate to f64's implementation -/// } -/// } -/// -/// let l = Length(100); -/// -/// assert_eq!( -/// format!("l in scientific notation is: {l:E}"), -/// "l in scientific notation is: 1E2" -/// ); -/// -/// assert_eq!( -/// format!("l in scientific notation is: {l:05E}"), -/// "l in scientific notation is: 001E2" -/// ); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub trait UpperExp { - #[doc = include_str!("fmt_trait_method_doc.md")] - #[stable(feature = "rust1", since = "1.0.0")] - fn fmt(&self, f: &mut Formatter<'_>) -> Result; -} - -/// The `write` function takes an output stream, and an `Arguments` struct -/// that can be precompiled with the `format_args!` macro. -/// -/// The arguments will be formatted according to the specified format string -/// into the output stream provided. -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// use std::fmt; -/// -/// let mut output = String::new(); -/// fmt::write(&mut output, format_args!("Hello {}!", "world")) -/// .expect("Error occurred while trying to write in String"); -/// assert_eq!(output, "Hello world!"); -/// ``` -/// -/// Please note that using [`write!`] might be preferable. Example: -/// -/// ``` -/// use std::fmt::Write; -/// -/// let mut output = String::new(); -/// write!(&mut output, "Hello {}!", "world") -/// .expect("Error occurred while trying to write in String"); -/// assert_eq!(output, "Hello world!"); -/// ``` -/// -/// [`write!`]: crate::write! -#[stable(feature = "rust1", since = "1.0.0")] -pub fn write(output: &mut dyn Write, args: Arguments<'_>) -> Result { - let mut formatter = Formatter::new(output); - let mut idx = 0; - - match args.fmt { - None => { - // We can use default formatting parameters for all arguments. - for (i, arg) in args.args.iter().enumerate() { - // SAFETY: args.args and args.pieces come from the same Arguments, - // which guarantees the indexes are always within bounds. - let piece = unsafe { args.pieces.get_unchecked(i) }; - if !piece.is_empty() { - formatter.buf.write_str(*piece)?; - } - - // SAFETY: There are no formatting parameters and hence no - // count arguments. - unsafe { - arg.fmt(&mut formatter)?; - } - idx += 1; - } - } - Some(fmt) => { - // Every spec has a corresponding argument that is preceded by - // a string piece. - for (i, arg) in fmt.iter().enumerate() { - // SAFETY: fmt and args.pieces come from the same Arguments, - // which guarantees the indexes are always within bounds. - let piece = unsafe { args.pieces.get_unchecked(i) }; - if !piece.is_empty() { - formatter.buf.write_str(*piece)?; - } - // SAFETY: arg and args.args come from the same Arguments, - // which guarantees the indexes are always within bounds. - unsafe { run(&mut formatter, arg, args.args) }?; - idx += 1; - } - } - } - - // There can be only one trailing string piece left. - if let Some(piece) = args.pieces.get(idx) { - formatter.buf.write_str(*piece)?; - } - - Ok(()) -} - -unsafe fn run(fmt: &mut Formatter<'_>, arg: &rt::Placeholder, args: &[rt::Argument<'_>]) -> Result { - fmt.fill = arg.fill; - fmt.align = arg.align; - fmt.flags = arg.flags; - // SAFETY: arg and args come from the same Arguments, - // which guarantees the indexes are always within bounds. - unsafe { - fmt.width = getcount(args, &arg.width); - fmt.precision = getcount(args, &arg.precision); - } - - // Extract the correct argument - debug_assert!(arg.position < args.len()); - // SAFETY: arg and args come from the same Arguments, - // which guarantees its index is always within bounds. - let value = unsafe { args.get_unchecked(arg.position) }; - - // Then actually do some printing - // SAFETY: this is a placeholder argument. - unsafe { value.fmt(fmt) } -} - -unsafe fn getcount(args: &[rt::Argument<'_>], cnt: &rt::Count) -> Option { - match *cnt { - rt::Count::Is(n) => Some(n), - rt::Count::Implied => None, - rt::Count::Param(i) => { - debug_assert!(i < args.len()); - // SAFETY: cnt and args come from the same Arguments, - // which guarantees this index is always within bounds. - unsafe { args.get_unchecked(i).as_usize() } - } - } -} - -/// Padding after the end of something. Returned by `Formatter::padding`. -#[must_use = "don't forget to write the post padding"] -pub(crate) struct PostPadding { - fill: char, - padding: usize, -} - -impl PostPadding { - fn new(fill: char, padding: usize) -> PostPadding { - PostPadding { fill, padding } - } - - /// Write this post padding. - pub(crate) fn write(self, f: &mut Formatter<'_>) -> Result { - for _ in 0..self.padding { - f.buf.write_char(self.fill)?; - } - Ok(()) - } -} - -impl<'a> Formatter<'a> { - fn wrap_buf<'b, 'c, F>(&'b mut self, wrap: F) -> Formatter<'c> - where - 'b: 'c, - F: FnOnce(&'b mut (dyn Write + 'b)) -> &'c mut (dyn Write + 'c), - { - Formatter { - // We want to change this - buf: wrap(self.buf), - - // And preserve these - flags: self.flags, - fill: self.fill, - align: self.align, - width: self.width, - precision: self.precision, - } - } - - // Helper methods used for padding and processing formatting arguments that - // all formatting traits can use. - - /// Performs the correct padding for an integer which has already been - /// emitted into a str. The str should *not* contain the sign for the - /// integer, that will be added by this method. - /// - /// # Arguments - /// - /// * is_nonnegative - whether the original integer was either positive or zero. - /// * prefix - if the '#' character (Alternate) is provided, this - /// is the prefix to put in front of the number. - /// * buf - the byte array that the number has been formatted into - /// - /// This function will correctly account for the flags provided as well as - /// the minimum width. It will not take precision into account. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo { nb: i32 } - /// - /// impl Foo { - /// fn new(nb: i32) -> Foo { - /// Foo { - /// nb, - /// } - /// } - /// } - /// - /// impl fmt::Display for Foo { - /// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - /// // We need to remove "-" from the number output. - /// let tmp = self.nb.abs().to_string(); - /// - /// formatter.pad_integral(self.nb >= 0, "Foo ", &tmp) - /// } - /// } - /// - /// assert_eq!(format!("{}", Foo::new(2)), "2"); - /// assert_eq!(format!("{}", Foo::new(-1)), "-1"); - /// assert_eq!(format!("{}", Foo::new(0)), "0"); - /// assert_eq!(format!("{:#}", Foo::new(-1)), "-Foo 1"); - /// assert_eq!(format!("{:0>#8}", Foo::new(-1)), "00-Foo 1"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn pad_integral(&mut self, is_nonnegative: bool, prefix: &str, buf: &str) -> Result { - let mut width = buf.len(); - - let mut sign = None; - if !is_nonnegative { - sign = Some('-'); - width += 1; - } else if self.sign_plus() { - sign = Some('+'); - width += 1; - } - - let prefix = if self.alternate() { - width += prefix.chars().count(); - Some(prefix) - } else { - None - }; - - // Writes the sign if it exists, and then the prefix if it was requested - #[inline(never)] - fn write_prefix(f: &mut Formatter<'_>, sign: Option, prefix: Option<&str>) -> Result { - if let Some(c) = sign { - f.buf.write_char(c)?; - } - if let Some(prefix) = prefix { f.buf.write_str(prefix) } else { Ok(()) } - } - - // The `width` field is more of a `min-width` parameter at this point. - match self.width { - // If there's no minimum length requirements then we can just - // write the bytes. - None => { - write_prefix(self, sign, prefix)?; - self.buf.write_str(buf) - } - // Check if we're over the minimum width, if so then we can also - // just write the bytes. - Some(min) if width >= min => { - write_prefix(self, sign, prefix)?; - self.buf.write_str(buf) - } - // The sign and prefix goes before the padding if the fill character - // is zero - Some(min) if self.sign_aware_zero_pad() => { - let old_fill = crate::mem::replace(&mut self.fill, '0'); - let old_align = crate::mem::replace(&mut self.align, rt::Alignment::Right); - write_prefix(self, sign, prefix)?; - let post_padding = self.padding(min - width, Alignment::Right)?; - self.buf.write_str(buf)?; - post_padding.write(self)?; - self.fill = old_fill; - self.align = old_align; - Ok(()) - } - // Otherwise, the sign and prefix goes after the padding - Some(min) => { - let post_padding = self.padding(min - width, Alignment::Right)?; - write_prefix(self, sign, prefix)?; - self.buf.write_str(buf)?; - post_padding.write(self) - } - } - } - - /// This function takes a string slice and emits it to the internal buffer - /// after applying the relevant formatting flags specified. The flags - /// recognized for generic strings are: - /// - /// * width - the minimum width of what to emit - /// * fill/align - what to emit and where to emit it if the string - /// provided needs to be padded - /// * precision - the maximum length to emit, the string is truncated if it - /// is longer than this length - /// - /// Notably this function ignores the `flag` parameters. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo; - /// - /// impl fmt::Display for Foo { - /// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - /// formatter.pad("Foo") - /// } - /// } - /// - /// assert_eq!(format!("{Foo:<4}"), "Foo "); - /// assert_eq!(format!("{Foo:0>4}"), "0Foo"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn pad(&mut self, s: &str) -> Result { - // Make sure there's a fast path up front - if self.width.is_none() && self.precision.is_none() { - return self.buf.write_str(s); - } - // The `precision` field can be interpreted as a `max-width` for the - // string being formatted. - let s = if let Some(max) = self.precision { - // If our string is longer that the precision, then we must have - // truncation. However other flags like `fill`, `width` and `align` - // must act as always. - if let Some((i, _)) = s.char_indices().nth(max) { - // LLVM here can't prove that `..i` won't panic `&s[..i]`, but - // we know that it can't panic. Use `get` + `unwrap_or` to avoid - // `unsafe` and otherwise don't emit any panic-related code - // here. - s.get(..i).unwrap_or(s) - } else { - &s - } - } else { - &s - }; - // The `width` field is more of a `min-width` parameter at this point. - match self.width { - // If we're under the maximum length, and there's no minimum length - // requirements, then we can just emit the string - None => self.buf.write_str(s), - Some(width) => { - let chars_count = s.chars().count(); - // If we're under the maximum width, check if we're over the minimum - // width, if so it's as easy as just emitting the string. - if chars_count >= width { - self.buf.write_str(s) - } - // If we're under both the maximum and the minimum width, then fill - // up the minimum width with the specified string + some alignment. - else { - let align = Alignment::Left; - let post_padding = self.padding(width - chars_count, align)?; - self.buf.write_str(s)?; - post_padding.write(self) - } - } - } - } - - /// Write the pre-padding and return the unwritten post-padding. Callers are - /// responsible for ensuring post-padding is written after the thing that is - /// being padded. - pub(crate) fn padding( - &mut self, - padding: usize, - default: Alignment, - ) -> result::Result { - let align = match self.align { - rt::Alignment::Unknown => default, - rt::Alignment::Left => Alignment::Left, - rt::Alignment::Right => Alignment::Right, - rt::Alignment::Center => Alignment::Center, - }; - - let (pre_pad, post_pad) = match align { - Alignment::Left => (0, padding), - Alignment::Right => (padding, 0), - Alignment::Center => (padding / 2, (padding + 1) / 2), - }; - - for _ in 0..pre_pad { - self.buf.write_char(self.fill)?; - } - - Ok(PostPadding::new(self.fill, post_pad)) - } - - /// Takes the formatted parts and applies the padding. - /// Assumes that the caller already has rendered the parts with required precision, - /// so that `self.precision` can be ignored. - /// - /// # Safety - /// - /// Any `numfmt::Part::Copy` parts in `formatted` must contain valid UTF-8. - unsafe fn pad_formatted_parts(&mut self, formatted: &numfmt::Formatted<'_>) -> Result { - if let Some(mut width) = self.width { - // for the sign-aware zero padding, we render the sign first and - // behave as if we had no sign from the beginning. - let mut formatted = formatted.clone(); - let old_fill = self.fill; - let old_align = self.align; - if self.sign_aware_zero_pad() { - // a sign always goes first - let sign = formatted.sign; - self.buf.write_str(sign)?; - - // remove the sign from the formatted parts - formatted.sign = ""; - width = width.saturating_sub(sign.len()); - self.fill = '0'; - self.align = rt::Alignment::Right; - } - - // remaining parts go through the ordinary padding process. - let len = formatted.len(); - let ret = if width <= len { - // no padding - // SAFETY: Per the precondition. - unsafe { self.write_formatted_parts(&formatted) } - } else { - let post_padding = self.padding(width - len, Alignment::Right)?; - // SAFETY: Per the precondition. - unsafe { - self.write_formatted_parts(&formatted)?; - } - post_padding.write(self) - }; - self.fill = old_fill; - self.align = old_align; - ret - } else { - // this is the common case and we take a shortcut - // SAFETY: Per the precondition. - unsafe { self.write_formatted_parts(formatted) } - } - } - - /// # Safety - /// - /// Any `numfmt::Part::Copy` parts in `formatted` must contain valid UTF-8. - unsafe fn write_formatted_parts(&mut self, formatted: &numfmt::Formatted<'_>) -> Result { - unsafe fn write_bytes(buf: &mut dyn Write, s: &[u8]) -> Result { - // SAFETY: This is used for `numfmt::Part::Num` and `numfmt::Part::Copy`. - // It's safe to use for `numfmt::Part::Num` since every char `c` is between - // `b'0'` and `b'9'`, which means `s` is valid UTF-8. It's safe to use for - // `numfmt::Part::Copy` due to this function's precondition. - buf.write_str(unsafe { str::from_utf8_unchecked(s) }) - } - - if !formatted.sign.is_empty() { - self.buf.write_str(formatted.sign)?; - } - for part in formatted.parts { - match *part { - numfmt::Part::Zero(mut nzeroes) => { - const ZEROES: &str = // 64 zeroes - "0000000000000000000000000000000000000000000000000000000000000000"; - while nzeroes > ZEROES.len() { - self.buf.write_str(ZEROES)?; - nzeroes -= ZEROES.len(); - } - if nzeroes > 0 { - self.buf.write_str(&ZEROES[..nzeroes])?; - } - } - numfmt::Part::Num(mut v) => { - let mut s = [0; 5]; - let len = part.len(); - for c in s[..len].iter_mut().rev() { - *c = b'0' + (v % 10) as u8; - v /= 10; - } - // SAFETY: Per the precondition. - unsafe { - write_bytes(self.buf, &s[..len])?; - } - } - // SAFETY: Per the precondition. - numfmt::Part::Copy(buf) => unsafe { - write_bytes(self.buf, buf)?; - }, - } - } - Ok(()) - } - - /// Writes some data to the underlying buffer contained within this - /// formatter. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo; - /// - /// impl fmt::Display for Foo { - /// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - /// formatter.write_str("Foo") - /// // This is equivalent to: - /// // write!(formatter, "Foo") - /// } - /// } - /// - /// assert_eq!(format!("{Foo}"), "Foo"); - /// assert_eq!(format!("{Foo:0>8}"), "Foo"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn write_str(&mut self, data: &str) -> Result { - self.buf.write_str(data) - } - - /// Writes some formatted information into this instance. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo(i32); - /// - /// impl fmt::Display for Foo { - /// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - /// formatter.write_fmt(format_args!("Foo {}", self.0)) - /// } - /// } - /// - /// assert_eq!(format!("{}", Foo(-1)), "Foo -1"); - /// assert_eq!(format!("{:0>8}", Foo(2)), "Foo 2"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result { - if let Some(s) = fmt.as_statically_known_str() { - self.buf.write_str(s) - } else { - write(self.buf, fmt) - } - } - - /// Flags for formatting - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[deprecated( - since = "1.24.0", - note = "use the `sign_plus`, `sign_minus`, `alternate`, \ - or `sign_aware_zero_pad` methods instead" - )] - pub fn flags(&self) -> u32 { - self.flags - } - - /// Character used as 'fill' whenever there is alignment. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo; - /// - /// impl fmt::Display for Foo { - /// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - /// let c = formatter.fill(); - /// if let Some(width) = formatter.width() { - /// for _ in 0..width { - /// write!(formatter, "{c}")?; - /// } - /// Ok(()) - /// } else { - /// write!(formatter, "{c}") - /// } - /// } - /// } - /// - /// // We set alignment to the right with ">". - /// assert_eq!(format!("{Foo:G>3}"), "GGG"); - /// assert_eq!(format!("{Foo:t>6}"), "tttttt"); - /// ``` - #[must_use] - #[stable(feature = "fmt_flags", since = "1.5.0")] - pub fn fill(&self) -> char { - self.fill - } - - /// Flag indicating what form of alignment was requested. - /// - /// # Examples - /// - /// ``` - /// use std::fmt::{self, Alignment}; - /// - /// struct Foo; - /// - /// impl fmt::Display for Foo { - /// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - /// let s = if let Some(s) = formatter.align() { - /// match s { - /// Alignment::Left => "left", - /// Alignment::Right => "right", - /// Alignment::Center => "center", - /// } - /// } else { - /// "into the void" - /// }; - /// write!(formatter, "{s}") - /// } - /// } - /// - /// assert_eq!(format!("{Foo:<}"), "left"); - /// assert_eq!(format!("{Foo:>}"), "right"); - /// assert_eq!(format!("{Foo:^}"), "center"); - /// assert_eq!(format!("{Foo}"), "into the void"); - /// ``` - #[must_use] - #[stable(feature = "fmt_flags_align", since = "1.28.0")] - pub fn align(&self) -> Option { - match self.align { - rt::Alignment::Left => Some(Alignment::Left), - rt::Alignment::Right => Some(Alignment::Right), - rt::Alignment::Center => Some(Alignment::Center), - rt::Alignment::Unknown => None, - } - } - - /// Optionally specified integer width that the output should be. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo(i32); - /// - /// impl fmt::Display for Foo { - /// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - /// if let Some(width) = formatter.width() { - /// // If we received a width, we use it - /// write!(formatter, "{:width$}", format!("Foo({})", self.0), width = width) - /// } else { - /// // Otherwise we do nothing special - /// write!(formatter, "Foo({})", self.0) - /// } - /// } - /// } - /// - /// assert_eq!(format!("{:10}", Foo(23)), "Foo(23) "); - /// assert_eq!(format!("{}", Foo(23)), "Foo(23)"); - /// ``` - #[must_use] - #[stable(feature = "fmt_flags", since = "1.5.0")] - pub fn width(&self) -> Option { - self.width - } - - /// Optionally specified precision for numeric types. Alternatively, the - /// maximum width for string types. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo(f32); - /// - /// impl fmt::Display for Foo { - /// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - /// if let Some(precision) = formatter.precision() { - /// // If we received a precision, we use it. - /// write!(formatter, "Foo({1:.*})", precision, self.0) - /// } else { - /// // Otherwise we default to 2. - /// write!(formatter, "Foo({:.2})", self.0) - /// } - /// } - /// } - /// - /// assert_eq!(format!("{:.4}", Foo(23.2)), "Foo(23.2000)"); - /// assert_eq!(format!("{}", Foo(23.2)), "Foo(23.20)"); - /// ``` - #[must_use] - #[stable(feature = "fmt_flags", since = "1.5.0")] - pub fn precision(&self) -> Option { - self.precision - } - - /// Determines if the `+` flag was specified. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo(i32); - /// - /// impl fmt::Display for Foo { - /// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - /// if formatter.sign_plus() { - /// write!(formatter, - /// "Foo({}{})", - /// if self.0 < 0 { '-' } else { '+' }, - /// self.0.abs()) - /// } else { - /// write!(formatter, "Foo({})", self.0) - /// } - /// } - /// } - /// - /// assert_eq!(format!("{:+}", Foo(23)), "Foo(+23)"); - /// assert_eq!(format!("{:+}", Foo(-23)), "Foo(-23)"); - /// assert_eq!(format!("{}", Foo(23)), "Foo(23)"); - /// ``` - #[must_use] - #[stable(feature = "fmt_flags", since = "1.5.0")] - pub fn sign_plus(&self) -> bool { - self.flags & (1 << rt::Flag::SignPlus as u32) != 0 - } - - /// Determines if the `-` flag was specified. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo(i32); - /// - /// impl fmt::Display for Foo { - /// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - /// if formatter.sign_minus() { - /// // You want a minus sign? Have one! - /// write!(formatter, "-Foo({})", self.0) - /// } else { - /// write!(formatter, "Foo({})", self.0) - /// } - /// } - /// } - /// - /// assert_eq!(format!("{:-}", Foo(23)), "-Foo(23)"); - /// assert_eq!(format!("{}", Foo(23)), "Foo(23)"); - /// ``` - #[must_use] - #[stable(feature = "fmt_flags", since = "1.5.0")] - pub fn sign_minus(&self) -> bool { - self.flags & (1 << rt::Flag::SignMinus as u32) != 0 - } - - /// Determines if the `#` flag was specified. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo(i32); - /// - /// impl fmt::Display for Foo { - /// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - /// if formatter.alternate() { - /// write!(formatter, "Foo({})", self.0) - /// } else { - /// write!(formatter, "{}", self.0) - /// } - /// } - /// } - /// - /// assert_eq!(format!("{:#}", Foo(23)), "Foo(23)"); - /// assert_eq!(format!("{}", Foo(23)), "23"); - /// ``` - #[must_use] - #[stable(feature = "fmt_flags", since = "1.5.0")] - pub fn alternate(&self) -> bool { - self.flags & (1 << rt::Flag::Alternate as u32) != 0 - } - - /// Determines if the `0` flag was specified. - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// struct Foo(i32); - /// - /// impl fmt::Display for Foo { - /// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - /// assert!(formatter.sign_aware_zero_pad()); - /// assert_eq!(formatter.width(), Some(4)); - /// // We ignore the formatter's options. - /// write!(formatter, "{}", self.0) - /// } - /// } - /// - /// assert_eq!(format!("{:04}", Foo(23)), "23"); - /// ``` - #[must_use] - #[stable(feature = "fmt_flags", since = "1.5.0")] - pub fn sign_aware_zero_pad(&self) -> bool { - self.flags & (1 << rt::Flag::SignAwareZeroPad as u32) != 0 - } - - // FIXME: Decide what public API we want for these two flags. - // https://github.com/rust-lang/rust/issues/48584 - fn debug_lower_hex(&self) -> bool { - self.flags & (1 << rt::Flag::DebugLowerHex as u32) != 0 - } - - fn debug_upper_hex(&self) -> bool { - self.flags & (1 << rt::Flag::DebugUpperHex as u32) != 0 - } - - /// Creates a [`DebugStruct`] builder designed to assist with creation of - /// [`fmt::Debug`] implementations for structs. - /// - /// [`fmt::Debug`]: self::Debug - /// - /// # Examples - /// - /// ```rust - /// use std::fmt; - /// use std::net::Ipv4Addr; - /// - /// struct Foo { - /// bar: i32, - /// baz: String, - /// addr: Ipv4Addr, - /// } - /// - /// impl fmt::Debug for Foo { - /// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - /// fmt.debug_struct("Foo") - /// .field("bar", &self.bar) - /// .field("baz", &self.baz) - /// .field("addr", &format_args!("{}", self.addr)) - /// .finish() - /// } - /// } - /// - /// assert_eq!( - /// "Foo { bar: 10, baz: \"Hello World\", addr: 127.0.0.1 }", - /// format!("{:?}", Foo { - /// bar: 10, - /// baz: "Hello World".to_string(), - /// addr: Ipv4Addr::new(127, 0, 0, 1), - /// }) - /// ); - /// ``` - #[stable(feature = "debug_builders", since = "1.2.0")] - pub fn debug_struct<'b>(&'b mut self, name: &str) -> DebugStruct<'b, 'a> { - builders::debug_struct_new(self, name) - } - - /// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. - /// `debug_struct_fields_finish` is more general, but this is faster for 1 field. - #[doc(hidden)] - #[unstable(feature = "fmt_helpers_for_derive", issue = "none")] - pub fn debug_struct_field1_finish<'b>( - &'b mut self, - name: &str, - name1: &str, - value1: &dyn Debug, - ) -> Result { - let mut builder = builders::debug_struct_new(self, name); - builder.field(name1, value1); - builder.finish() - } - - /// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. - /// `debug_struct_fields_finish` is more general, but this is faster for 2 fields. - #[doc(hidden)] - #[unstable(feature = "fmt_helpers_for_derive", issue = "none")] - pub fn debug_struct_field2_finish<'b>( - &'b mut self, - name: &str, - name1: &str, - value1: &dyn Debug, - name2: &str, - value2: &dyn Debug, - ) -> Result { - let mut builder = builders::debug_struct_new(self, name); - builder.field(name1, value1); - builder.field(name2, value2); - builder.finish() - } - - /// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. - /// `debug_struct_fields_finish` is more general, but this is faster for 3 fields. - #[doc(hidden)] - #[unstable(feature = "fmt_helpers_for_derive", issue = "none")] - pub fn debug_struct_field3_finish<'b>( - &'b mut self, - name: &str, - name1: &str, - value1: &dyn Debug, - name2: &str, - value2: &dyn Debug, - name3: &str, - value3: &dyn Debug, - ) -> Result { - let mut builder = builders::debug_struct_new(self, name); - builder.field(name1, value1); - builder.field(name2, value2); - builder.field(name3, value3); - builder.finish() - } - - /// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. - /// `debug_struct_fields_finish` is more general, but this is faster for 4 fields. - #[doc(hidden)] - #[unstable(feature = "fmt_helpers_for_derive", issue = "none")] - pub fn debug_struct_field4_finish<'b>( - &'b mut self, - name: &str, - name1: &str, - value1: &dyn Debug, - name2: &str, - value2: &dyn Debug, - name3: &str, - value3: &dyn Debug, - name4: &str, - value4: &dyn Debug, - ) -> Result { - let mut builder = builders::debug_struct_new(self, name); - builder.field(name1, value1); - builder.field(name2, value2); - builder.field(name3, value3); - builder.field(name4, value4); - builder.finish() - } - - /// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. - /// `debug_struct_fields_finish` is more general, but this is faster for 5 fields. - #[doc(hidden)] - #[unstable(feature = "fmt_helpers_for_derive", issue = "none")] - pub fn debug_struct_field5_finish<'b>( - &'b mut self, - name: &str, - name1: &str, - value1: &dyn Debug, - name2: &str, - value2: &dyn Debug, - name3: &str, - value3: &dyn Debug, - name4: &str, - value4: &dyn Debug, - name5: &str, - value5: &dyn Debug, - ) -> Result { - let mut builder = builders::debug_struct_new(self, name); - builder.field(name1, value1); - builder.field(name2, value2); - builder.field(name3, value3); - builder.field(name4, value4); - builder.field(name5, value5); - builder.finish() - } - - /// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. - /// For the cases not covered by `debug_struct_field[12345]_finish`. - #[doc(hidden)] - #[unstable(feature = "fmt_helpers_for_derive", issue = "none")] - pub fn debug_struct_fields_finish<'b>( - &'b mut self, - name: &str, - names: &[&str], - values: &[&dyn Debug], - ) -> Result { - assert_eq!(names.len(), values.len()); - let mut builder = builders::debug_struct_new(self, name); - for (name, value) in iter::zip(names, values) { - builder.field(name, value); - } - builder.finish() - } - - /// Creates a `DebugTuple` builder designed to assist with creation of - /// `fmt::Debug` implementations for tuple structs. - /// - /// # Examples - /// - /// ```rust - /// use std::fmt; - /// use std::marker::PhantomData; - /// - /// struct Foo(i32, String, PhantomData); - /// - /// impl fmt::Debug for Foo { - /// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - /// fmt.debug_tuple("Foo") - /// .field(&self.0) - /// .field(&self.1) - /// .field(&format_args!("_")) - /// .finish() - /// } - /// } - /// - /// assert_eq!( - /// "Foo(10, \"Hello\", _)", - /// format!("{:?}", Foo(10, "Hello".to_string(), PhantomData::)) - /// ); - /// ``` - #[stable(feature = "debug_builders", since = "1.2.0")] - pub fn debug_tuple<'b>(&'b mut self, name: &str) -> DebugTuple<'b, 'a> { - builders::debug_tuple_new(self, name) - } - - /// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. - /// `debug_tuple_fields_finish` is more general, but this is faster for 1 field. - #[doc(hidden)] - #[unstable(feature = "fmt_helpers_for_derive", issue = "none")] - pub fn debug_tuple_field1_finish<'b>(&'b mut self, name: &str, value1: &dyn Debug) -> Result { - let mut builder = builders::debug_tuple_new(self, name); - builder.field(value1); - builder.finish() - } - - /// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. - /// `debug_tuple_fields_finish` is more general, but this is faster for 2 fields. - #[doc(hidden)] - #[unstable(feature = "fmt_helpers_for_derive", issue = "none")] - pub fn debug_tuple_field2_finish<'b>( - &'b mut self, - name: &str, - value1: &dyn Debug, - value2: &dyn Debug, - ) -> Result { - let mut builder = builders::debug_tuple_new(self, name); - builder.field(value1); - builder.field(value2); - builder.finish() - } - - /// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. - /// `debug_tuple_fields_finish` is more general, but this is faster for 3 fields. - #[doc(hidden)] - #[unstable(feature = "fmt_helpers_for_derive", issue = "none")] - pub fn debug_tuple_field3_finish<'b>( - &'b mut self, - name: &str, - value1: &dyn Debug, - value2: &dyn Debug, - value3: &dyn Debug, - ) -> Result { - let mut builder = builders::debug_tuple_new(self, name); - builder.field(value1); - builder.field(value2); - builder.field(value3); - builder.finish() - } - - /// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. - /// `debug_tuple_fields_finish` is more general, but this is faster for 4 fields. - #[doc(hidden)] - #[unstable(feature = "fmt_helpers_for_derive", issue = "none")] - pub fn debug_tuple_field4_finish<'b>( - &'b mut self, - name: &str, - value1: &dyn Debug, - value2: &dyn Debug, - value3: &dyn Debug, - value4: &dyn Debug, - ) -> Result { - let mut builder = builders::debug_tuple_new(self, name); - builder.field(value1); - builder.field(value2); - builder.field(value3); - builder.field(value4); - builder.finish() - } - - /// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. - /// `debug_tuple_fields_finish` is more general, but this is faster for 5 fields. - #[doc(hidden)] - #[unstable(feature = "fmt_helpers_for_derive", issue = "none")] - pub fn debug_tuple_field5_finish<'b>( - &'b mut self, - name: &str, - value1: &dyn Debug, - value2: &dyn Debug, - value3: &dyn Debug, - value4: &dyn Debug, - value5: &dyn Debug, - ) -> Result { - let mut builder = builders::debug_tuple_new(self, name); - builder.field(value1); - builder.field(value2); - builder.field(value3); - builder.field(value4); - builder.field(value5); - builder.finish() - } - - /// Used to shrink `derive(Debug)` code, for faster compilation and smaller binaries. - /// For the cases not covered by `debug_tuple_field[12345]_finish`. - #[doc(hidden)] - #[unstable(feature = "fmt_helpers_for_derive", issue = "none")] - pub fn debug_tuple_fields_finish<'b>( - &'b mut self, - name: &str, - values: &[&dyn Debug], - ) -> Result { - let mut builder = builders::debug_tuple_new(self, name); - for value in values { - builder.field(value); - } - builder.finish() - } - - /// Creates a `DebugList` builder designed to assist with creation of - /// `fmt::Debug` implementations for list-like structures. - /// - /// # Examples - /// - /// ```rust - /// use std::fmt; - /// - /// struct Foo(Vec); - /// - /// impl fmt::Debug for Foo { - /// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - /// fmt.debug_list().entries(self.0.iter()).finish() - /// } - /// } - /// - /// assert_eq!(format!("{:?}", Foo(vec![10, 11])), "[10, 11]"); - /// ``` - #[stable(feature = "debug_builders", since = "1.2.0")] - pub fn debug_list<'b>(&'b mut self) -> DebugList<'b, 'a> { - builders::debug_list_new(self) - } - - /// Creates a `DebugSet` builder designed to assist with creation of - /// `fmt::Debug` implementations for set-like structures. - /// - /// # Examples - /// - /// ```rust - /// use std::fmt; - /// - /// struct Foo(Vec); - /// - /// impl fmt::Debug for Foo { - /// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - /// fmt.debug_set().entries(self.0.iter()).finish() - /// } - /// } - /// - /// assert_eq!(format!("{:?}", Foo(vec![10, 11])), "{10, 11}"); - /// ``` - /// - /// [`format_args!`]: crate::format_args - /// - /// In this more complex example, we use [`format_args!`] and `.debug_set()` - /// to build a list of match arms: - /// - /// ```rust - /// use std::fmt; - /// - /// struct Arm<'a, L, R>(&'a (L, R)); - /// struct Table<'a, K, V>(&'a [(K, V)], V); - /// - /// impl<'a, L, R> fmt::Debug for Arm<'a, L, R> - /// where - /// L: 'a + fmt::Debug, R: 'a + fmt::Debug - /// { - /// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - /// L::fmt(&(self.0).0, fmt)?; - /// fmt.write_str(" => ")?; - /// R::fmt(&(self.0).1, fmt) - /// } - /// } - /// - /// impl<'a, K, V> fmt::Debug for Table<'a, K, V> - /// where - /// K: 'a + fmt::Debug, V: 'a + fmt::Debug - /// { - /// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - /// fmt.debug_set() - /// .entries(self.0.iter().map(Arm)) - /// .entry(&Arm(&(format_args!("_"), &self.1))) - /// .finish() - /// } - /// } - /// ``` - #[stable(feature = "debug_builders", since = "1.2.0")] - pub fn debug_set<'b>(&'b mut self) -> DebugSet<'b, 'a> { - builders::debug_set_new(self) - } - - /// Creates a `DebugMap` builder designed to assist with creation of - /// `fmt::Debug` implementations for map-like structures. - /// - /// # Examples - /// - /// ```rust - /// use std::fmt; - /// - /// struct Foo(Vec<(String, i32)>); - /// - /// impl fmt::Debug for Foo { - /// fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - /// fmt.debug_map().entries(self.0.iter().map(|&(ref k, ref v)| (k, v))).finish() - /// } - /// } - /// - /// assert_eq!( - /// format!("{:?}", Foo(vec![("A".to_string(), 10), ("B".to_string(), 11)])), - /// r#"{"A": 10, "B": 11}"# - /// ); - /// ``` - #[stable(feature = "debug_builders", since = "1.2.0")] - pub fn debug_map<'b>(&'b mut self) -> DebugMap<'b, 'a> { - builders::debug_map_new(self) - } -} - -#[stable(since = "1.2.0", feature = "formatter_write")] -impl Write for Formatter<'_> { - fn write_str(&mut self, s: &str) -> Result { - self.buf.write_str(s) - } - - fn write_char(&mut self, c: char) -> Result { - self.buf.write_char(c) - } - - #[inline] - fn write_fmt(&mut self, args: Arguments<'_>) -> Result { - if let Some(s) = args.as_statically_known_str() { - self.buf.write_str(s) - } else { - write(self.buf, args) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Display for Error { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - Display::fmt("an error occurred when formatting an argument", f) - } -} - -// Implementations of the core formatting traits - -macro_rules! fmt_refs { - ($($tr:ident),*) => { - $( - #[stable(feature = "rust1", since = "1.0.0")] - impl $tr for &T { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { $tr::fmt(&**self, f) } - } - #[stable(feature = "rust1", since = "1.0.0")] - impl $tr for &mut T { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { $tr::fmt(&**self, f) } - } - )* - } -} - -fmt_refs! { Debug, Display, Octal, Binary, LowerHex, UpperHex, LowerExp, UpperExp } - -#[unstable(feature = "never_type", issue = "35121")] -impl Debug for ! { - #[inline] - fn fmt(&self, _: &mut Formatter<'_>) -> Result { - *self - } -} - -#[unstable(feature = "never_type", issue = "35121")] -impl Display for ! { - #[inline] - fn fmt(&self, _: &mut Formatter<'_>) -> Result { - *self - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Debug for bool { - #[inline] - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - Display::fmt(self, f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Display for bool { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - Display::fmt(if *self { "true" } else { "false" }, f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Debug for str { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - f.write_char('"')?; - - // substring we know is printable - let mut printable_range = 0..0; - - fn needs_escape(b: u8) -> bool { - b > 0x7E || b < 0x20 || b == b'\\' || b == b'"' - } - - // the loop here first skips over runs of printable ASCII as a fast path. - // other chars (unicode, or ASCII that needs escaping) are then handled per-`char`. - let mut rest = self; - while rest.len() > 0 { - let Some(non_printable_start) = rest.as_bytes().iter().position(|&b| needs_escape(b)) - else { - printable_range.end += rest.len(); - break; - }; - - printable_range.end += non_printable_start; - // SAFETY: the position was derived from an iterator, so is known to be within bounds, and at a char boundary - rest = unsafe { rest.get_unchecked(non_printable_start..) }; - - let mut chars = rest.chars(); - if let Some(c) = chars.next() { - let esc = c.escape_debug_ext(EscapeDebugExtArgs { - escape_grapheme_extended: true, - escape_single_quote: false, - escape_double_quote: true, - }); - if esc.len() != 1 { - f.write_str(&self[printable_range.clone()])?; - Display::fmt(&esc, f)?; - printable_range.start = printable_range.end + c.len_utf8(); - } - printable_range.end += c.len_utf8(); - } - rest = chars.as_str(); - } - - f.write_str(&self[printable_range])?; - - f.write_char('"') - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Display for str { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - f.pad(self) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Debug for char { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - f.write_char('\'')?; - let esc = self.escape_debug_ext(EscapeDebugExtArgs { - escape_grapheme_extended: true, - escape_single_quote: true, - escape_double_quote: false, - }); - Display::fmt(&esc, f)?; - f.write_char('\'') - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Display for char { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - if f.width.is_none() && f.precision.is_none() { - f.write_char(*self) - } else { - f.pad(self.encode_utf8(&mut [0; 4])) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Pointer for *const T { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - // Cast is needed here because `.expose_provenance()` requires `T: Sized`. - pointer_fmt_inner((*self as *const ()).expose_provenance(), f) - } -} - -/// Since the formatting will be identical for all pointer types, use a non-monomorphized -/// implementation for the actual formatting to reduce the amount of codegen work needed. -/// -/// This uses `ptr_addr: usize` and not `ptr: *const ()` to be able to use this for -/// `fn(...) -> ...` without using [problematic] "Oxford Casts". -/// -/// [problematic]: https://github.com/rust-lang/rust/issues/95489 -pub(crate) fn pointer_fmt_inner(ptr_addr: usize, f: &mut Formatter<'_>) -> Result { - let old_width = f.width; - let old_flags = f.flags; - - // The alternate flag is already treated by LowerHex as being special- - // it denotes whether to prefix with 0x. We use it to work out whether - // or not to zero extend, and then unconditionally set it to get the - // prefix. - if f.alternate() { - f.flags |= 1 << (rt::Flag::SignAwareZeroPad as u32); - - if f.width.is_none() { - f.width = Some((usize::BITS / 4) as usize + 2); - } - } - f.flags |= 1 << (rt::Flag::Alternate as u32); - - let ret = LowerHex::fmt(&ptr_addr, f); - - f.width = old_width; - f.flags = old_flags; - - ret -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Pointer for *mut T { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - Pointer::fmt(&(*self as *const T), f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Pointer for &T { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - Pointer::fmt(&(*self as *const T), f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Pointer for &mut T { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - Pointer::fmt(&(&**self as *const T), f) - } -} - -// Implementation of Display/Debug for various core types - -#[stable(feature = "rust1", since = "1.0.0")] -impl Debug for *const T { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - Pointer::fmt(self, f) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl Debug for *mut T { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - Pointer::fmt(self, f) - } -} - -macro_rules! peel { - ($name:ident, $($other:ident,)*) => (tuple! { $($other,)* }) -} - -macro_rules! tuple { - () => (); - ( $($name:ident,)+ ) => ( - maybe_tuple_doc! { - $($name)+ @ - #[stable(feature = "rust1", since = "1.0.0")] - impl<$($name:Debug),+> Debug for ($($name,)+) where last_type!($($name,)+): ?Sized { - #[allow(non_snake_case, unused_assignments)] - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - let mut builder = f.debug_tuple(""); - let ($(ref $name,)+) = *self; - $( - builder.field(&$name); - )+ - - builder.finish() - } - } - } - peel! { $($name,)+ } - ) -} - -macro_rules! maybe_tuple_doc { - ($a:ident @ #[$meta:meta] $item:item) => { - #[doc(fake_variadic)] - #[doc = "This trait is implemented for tuples up to twelve items long."] - #[$meta] - $item - }; - ($a:ident $($rest_a:ident)+ @ #[$meta:meta] $item:item) => { - #[doc(hidden)] - #[$meta] - $item - }; -} - -macro_rules! last_type { - ($a:ident,) => { $a }; - ($a:ident, $($rest_a:ident,)+) => { last_type!($($rest_a,)+) }; -} - -tuple! { E, D, C, B, A, Z, Y, X, W, V, U, T, } - -#[stable(feature = "rust1", since = "1.0.0")] -impl Debug for [T] { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - f.debug_list().entries(self.iter()).finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Debug for () { - #[inline] - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - f.pad("()") - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl Debug for PhantomData { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - write!(f, "PhantomData<{}>", crate::any::type_name::()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Debug for Cell { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - f.debug_struct("Cell").field("value", &self.get()).finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Debug for RefCell { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - let mut d = f.debug_struct("RefCell"); - match self.try_borrow() { - Ok(borrow) => d.field("value", &borrow), - Err(_) => d.field("value", &format_args!("")), - }; - d.finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Debug for Ref<'_, T> { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - Debug::fmt(&**self, f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Debug for RefMut<'_, T> { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - Debug::fmt(&*(self.deref()), f) - } -} - -#[stable(feature = "core_impl_debug", since = "1.9.0")] -impl Debug for UnsafeCell { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - f.debug_struct("UnsafeCell").finish_non_exhaustive() - } -} - -#[unstable(feature = "sync_unsafe_cell", issue = "95439")] -impl Debug for SyncUnsafeCell { - fn fmt(&self, f: &mut Formatter<'_>) -> Result { - f.debug_struct("SyncUnsafeCell").finish_non_exhaustive() - } -} - -// If you expected tests to be here, look instead at the core/tests/fmt.rs file, -// it's a lot easier than creating all of the rt::Piece structures here. -// There are also tests in the alloc crate, for those that need allocations. diff --git a/library/core/src/fmt/nofloat.rs b/library/core/src/fmt/nofloat.rs deleted file mode 100644 index 6b07236f1da12..0000000000000 --- a/library/core/src/fmt/nofloat.rs +++ /dev/null @@ -1,18 +0,0 @@ -use crate::fmt::{Debug, Formatter, Result}; - -macro_rules! floating { - ($ty:ident) => { - #[stable(feature = "rust1", since = "1.0.0")] - impl Debug for $ty { - #[inline] - fn fmt(&self, _fmt: &mut Formatter<'_>) -> Result { - panic!("floating point support is turned off"); - } - } - }; -} - -floating! { f16 } -floating! { f32 } -floating! { f64 } -floating! { f128 } diff --git a/library/core/src/fmt/num.rs b/library/core/src/fmt/num.rs deleted file mode 100644 index ab2158394bf1e..0000000000000 --- a/library/core/src/fmt/num.rs +++ /dev/null @@ -1,693 +0,0 @@ -//! Integer and floating-point number formatting - -use crate::fmt; -use crate::mem::MaybeUninit; -use crate::num::fmt as numfmt; -use crate::ops::{Div, Rem, Sub}; -use crate::ptr; -use crate::slice; -use crate::str; - -#[doc(hidden)] -trait DisplayInt: - PartialEq + PartialOrd + Div + Rem + Sub + Copy -{ - fn zero() -> Self; - fn from_u8(u: u8) -> Self; - fn to_u8(&self) -> u8; - #[cfg(not(any(target_pointer_width = "64", target_arch = "wasm32")))] - fn to_u32(&self) -> u32; - fn to_u64(&self) -> u64; - fn to_u128(&self) -> u128; -} - -macro_rules! impl_int { - ($($t:ident)*) => ( - $(impl DisplayInt for $t { - fn zero() -> Self { 0 } - fn from_u8(u: u8) -> Self { u as Self } - fn to_u8(&self) -> u8 { *self as u8 } - #[cfg(not(any(target_pointer_width = "64", target_arch = "wasm32")))] - fn to_u32(&self) -> u32 { *self as u32 } - fn to_u64(&self) -> u64 { *self as u64 } - fn to_u128(&self) -> u128 { *self as u128 } - })* - ) -} -macro_rules! impl_uint { - ($($t:ident)*) => ( - $(impl DisplayInt for $t { - fn zero() -> Self { 0 } - fn from_u8(u: u8) -> Self { u as Self } - fn to_u8(&self) -> u8 { *self as u8 } - #[cfg(not(any(target_pointer_width = "64", target_arch = "wasm32")))] - fn to_u32(&self) -> u32 { *self as u32 } - fn to_u64(&self) -> u64 { *self as u64 } - fn to_u128(&self) -> u128 { *self as u128 } - })* - ) -} - -impl_int! { i8 i16 i32 i64 i128 isize } -impl_uint! { u8 u16 u32 u64 u128 usize } - -/// A type that represents a specific radix -/// -/// # Safety -/// -/// `digit` must return an ASCII character. -#[doc(hidden)] -unsafe trait GenericRadix: Sized { - /// The number of digits. - const BASE: u8; - - /// A radix-specific prefix string. - const PREFIX: &'static str; - - /// Converts an integer to corresponding radix digit. - fn digit(x: u8) -> u8; - - /// Format an integer using the radix using a formatter. - fn fmt_int(&self, mut x: T, f: &mut fmt::Formatter<'_>) -> fmt::Result { - // The radix can be as low as 2, so we need a buffer of at least 128 - // characters for a base 2 number. - let zero = T::zero(); - let is_nonnegative = x >= zero; - let mut buf = [MaybeUninit::::uninit(); 128]; - let mut curr = buf.len(); - let base = T::from_u8(Self::BASE); - if is_nonnegative { - // Accumulate each digit of the number from the least significant - // to the most significant figure. - for byte in buf.iter_mut().rev() { - let n = x % base; // Get the current place value. - x = x / base; // Deaccumulate the number. - byte.write(Self::digit(n.to_u8())); // Store the digit in the buffer. - curr -= 1; - if x == zero { - // No more digits left to accumulate. - break; - }; - } - } else { - // Do the same as above, but accounting for two's complement. - for byte in buf.iter_mut().rev() { - let n = zero - (x % base); // Get the current place value. - x = x / base; // Deaccumulate the number. - byte.write(Self::digit(n.to_u8())); // Store the digit in the buffer. - curr -= 1; - if x == zero { - // No more digits left to accumulate. - break; - }; - } - } - let buf = &buf[curr..]; - // SAFETY: The only chars in `buf` are created by `Self::digit` which are assumed to be - // valid UTF-8 - let buf = unsafe { - str::from_utf8_unchecked(slice::from_raw_parts( - MaybeUninit::slice_as_ptr(buf), - buf.len(), - )) - }; - f.pad_integral(is_nonnegative, Self::PREFIX, buf) - } -} - -/// A binary (base 2) radix -#[derive(Clone, PartialEq)] -struct Binary; - -/// An octal (base 8) radix -#[derive(Clone, PartialEq)] -struct Octal; - -/// A hexadecimal (base 16) radix, formatted with lower-case characters -#[derive(Clone, PartialEq)] -struct LowerHex; - -/// A hexadecimal (base 16) radix, formatted with upper-case characters -#[derive(Clone, PartialEq)] -struct UpperHex; - -macro_rules! radix { - ($T:ident, $base:expr, $prefix:expr, $($x:pat => $conv:expr),+) => { - unsafe impl GenericRadix for $T { - const BASE: u8 = $base; - const PREFIX: &'static str = $prefix; - fn digit(x: u8) -> u8 { - match x { - $($x => $conv,)+ - x => panic!("number not in the range 0..={}: {}", Self::BASE - 1, x), - } - } - } - } -} - -radix! { Binary, 2, "0b", x @ 0 ..= 1 => b'0' + x } -radix! { Octal, 8, "0o", x @ 0 ..= 7 => b'0' + x } -radix! { LowerHex, 16, "0x", x @ 0 ..= 9 => b'0' + x, x @ 10 ..= 15 => b'a' + (x - 10) } -radix! { UpperHex, 16, "0x", x @ 0 ..= 9 => b'0' + x, x @ 10 ..= 15 => b'A' + (x - 10) } - -macro_rules! int_base { - (fmt::$Trait:ident for $T:ident as $U:ident -> $Radix:ident) => { - #[stable(feature = "rust1", since = "1.0.0")] - impl fmt::$Trait for $T { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - $Radix.fmt_int(*self as $U, f) - } - } - }; -} - -macro_rules! integer { - ($Int:ident, $Uint:ident) => { - int_base! { fmt::Binary for $Int as $Uint -> Binary } - int_base! { fmt::Octal for $Int as $Uint -> Octal } - int_base! { fmt::LowerHex for $Int as $Uint -> LowerHex } - int_base! { fmt::UpperHex for $Int as $Uint -> UpperHex } - - int_base! { fmt::Binary for $Uint as $Uint -> Binary } - int_base! { fmt::Octal for $Uint as $Uint -> Octal } - int_base! { fmt::LowerHex for $Uint as $Uint -> LowerHex } - int_base! { fmt::UpperHex for $Uint as $Uint -> UpperHex } - }; -} -integer! { isize, usize } -integer! { i8, u8 } -integer! { i16, u16 } -integer! { i32, u32 } -integer! { i64, u64 } -integer! { i128, u128 } -macro_rules! debug { - ($($T:ident)*) => {$( - #[stable(feature = "rust1", since = "1.0.0")] - impl fmt::Debug for $T { - #[inline] - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - if f.debug_lower_hex() { - fmt::LowerHex::fmt(self, f) - } else if f.debug_upper_hex() { - fmt::UpperHex::fmt(self, f) - } else { - fmt::Display::fmt(self, f) - } - } - } - )*}; -} -debug! { - i8 i16 i32 i64 i128 isize - u8 u16 u32 u64 u128 usize -} - -// 2 digit decimal look up table -static DEC_DIGITS_LUT: &[u8; 200] = b"0001020304050607080910111213141516171819\ - 2021222324252627282930313233343536373839\ - 4041424344454647484950515253545556575859\ - 6061626364656667686970717273747576777879\ - 8081828384858687888990919293949596979899"; - -macro_rules! impl_Display { - ($($t:ident),* as $u:ident via $conv_fn:ident named $name:ident) => { - fn $name(mut n: $u, is_nonnegative: bool, f: &mut fmt::Formatter<'_>) -> fmt::Result { - // 2^128 is about 3*10^38, so 39 gives an extra byte of space - let mut buf = [MaybeUninit::::uninit(); 39]; - let mut curr = buf.len(); - let buf_ptr = MaybeUninit::slice_as_mut_ptr(&mut buf); - let lut_ptr = DEC_DIGITS_LUT.as_ptr(); - - // SAFETY: Since `d1` and `d2` are always less than or equal to `198`, we - // can copy from `lut_ptr[d1..d1 + 1]` and `lut_ptr[d2..d2 + 1]`. To show - // that it's OK to copy into `buf_ptr`, notice that at the beginning - // `curr == buf.len() == 39 > log(n)` since `n < 2^128 < 10^39`, and at - // each step this is kept the same as `n` is divided. Since `n` is always - // non-negative, this means that `curr > 0` so `buf_ptr[curr..curr + 1]` - // is safe to access. - unsafe { - // need at least 16 bits for the 4-characters-at-a-time to work. - assert!(crate::mem::size_of::<$u>() >= 2); - - // eagerly decode 4 characters at a time - while n >= 10000 { - let rem = (n % 10000) as usize; - n /= 10000; - - let d1 = (rem / 100) << 1; - let d2 = (rem % 100) << 1; - curr -= 4; - - // We are allowed to copy to `buf_ptr[curr..curr + 3]` here since - // otherwise `curr < 0`. But then `n` was originally at least `10000^10` - // which is `10^40 > 2^128 > n`. - ptr::copy_nonoverlapping(lut_ptr.add(d1), buf_ptr.add(curr), 2); - ptr::copy_nonoverlapping(lut_ptr.add(d2), buf_ptr.add(curr + 2), 2); - } - - // if we reach here numbers are <= 9999, so at most 4 chars long - let mut n = n as usize; // possibly reduce 64bit math - - // decode 2 more chars, if > 2 chars - if n >= 100 { - let d1 = (n % 100) << 1; - n /= 100; - curr -= 2; - ptr::copy_nonoverlapping(lut_ptr.add(d1), buf_ptr.add(curr), 2); - } - - // decode last 1 or 2 chars - if n < 10 { - curr -= 1; - *buf_ptr.add(curr) = (n as u8) + b'0'; - } else { - let d1 = n << 1; - curr -= 2; - ptr::copy_nonoverlapping(lut_ptr.add(d1), buf_ptr.add(curr), 2); - } - } - - // SAFETY: `curr` > 0 (since we made `buf` large enough), and all the chars are valid - // UTF-8 since `DEC_DIGITS_LUT` is - let buf_slice = unsafe { - str::from_utf8_unchecked( - slice::from_raw_parts(buf_ptr.add(curr), buf.len() - curr)) - }; - f.pad_integral(is_nonnegative, "", buf_slice) - } - - $(#[stable(feature = "rust1", since = "1.0.0")] - impl fmt::Display for $t { - #[allow(unused_comparisons)] - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let is_nonnegative = *self >= 0; - let n = if is_nonnegative { - self.$conv_fn() - } else { - // convert the negative num to positive by summing 1 to it's 2 complement - (!self.$conv_fn()).wrapping_add(1) - }; - $name(n, is_nonnegative, f) - } - })* - }; -} - -macro_rules! impl_Exp { - ($($t:ident),* as $u:ident via $conv_fn:ident named $name:ident) => { - fn $name( - mut n: $u, - is_nonnegative: bool, - upper: bool, - f: &mut fmt::Formatter<'_> - ) -> fmt::Result { - let (mut n, mut exponent, trailing_zeros, added_precision) = { - let mut exponent = 0; - // count and remove trailing decimal zeroes - while n % 10 == 0 && n >= 10 { - n /= 10; - exponent += 1; - } - let (added_precision, subtracted_precision) = match f.precision() { - Some(fmt_prec) => { - // number of decimal digits minus 1 - let mut tmp = n; - let mut prec = 0; - while tmp >= 10 { - tmp /= 10; - prec += 1; - } - (fmt_prec.saturating_sub(prec), prec.saturating_sub(fmt_prec)) - } - None => (0, 0) - }; - for _ in 1..subtracted_precision { - n /= 10; - exponent += 1; - } - if subtracted_precision != 0 { - let rem = n % 10; - n /= 10; - exponent += 1; - // round up last digit, round to even on a tie - if rem > 5 || (rem == 5 && (n % 2 != 0 || subtracted_precision > 1 )) { - n += 1; - // if the digit is rounded to the next power - // instead adjust the exponent - if n.ilog10() > (n - 1).ilog10() { - n /= 10; - exponent += 1; - } - } - } - (n, exponent, exponent, added_precision) - }; - - // 39 digits (worst case u128) + . = 40 - // Since `curr` always decreases by the number of digits copied, this means - // that `curr >= 0`. - let mut buf = [MaybeUninit::::uninit(); 40]; - let mut curr = buf.len(); //index for buf - let buf_ptr = MaybeUninit::slice_as_mut_ptr(&mut buf); - let lut_ptr = DEC_DIGITS_LUT.as_ptr(); - - // decode 2 chars at a time - while n >= 100 { - let d1 = ((n % 100) as usize) << 1; - curr -= 2; - // SAFETY: `d1 <= 198`, so we can copy from `lut_ptr[d1..d1 + 2]` since - // `DEC_DIGITS_LUT` has a length of 200. - unsafe { - ptr::copy_nonoverlapping(lut_ptr.add(d1), buf_ptr.add(curr), 2); - } - n /= 100; - exponent += 2; - } - // n is <= 99, so at most 2 chars long - let mut n = n as isize; // possibly reduce 64bit math - // decode second-to-last character - if n >= 10 { - curr -= 1; - // SAFETY: Safe since `40 > curr >= 0` (see comment) - unsafe { - *buf_ptr.add(curr) = (n as u8 % 10_u8) + b'0'; - } - n /= 10; - exponent += 1; - } - // add decimal point iff >1 mantissa digit will be printed - if exponent != trailing_zeros || added_precision != 0 { - curr -= 1; - // SAFETY: Safe since `40 > curr >= 0` - unsafe { - *buf_ptr.add(curr) = b'.'; - } - } - - // SAFETY: Safe since `40 > curr >= 0` - let buf_slice = unsafe { - // decode last character - curr -= 1; - *buf_ptr.add(curr) = (n as u8) + b'0'; - - let len = buf.len() - curr as usize; - slice::from_raw_parts(buf_ptr.add(curr), len) - }; - - // stores 'e' (or 'E') and the up to 2-digit exponent - let mut exp_buf = [MaybeUninit::::uninit(); 3]; - let exp_ptr = MaybeUninit::slice_as_mut_ptr(&mut exp_buf); - // SAFETY: In either case, `exp_buf` is written within bounds and `exp_ptr[..len]` - // is contained within `exp_buf` since `len <= 3`. - let exp_slice = unsafe { - *exp_ptr.add(0) = if upper { b'E' } else { b'e' }; - let len = if exponent < 10 { - *exp_ptr.add(1) = (exponent as u8) + b'0'; - 2 - } else { - let off = exponent << 1; - ptr::copy_nonoverlapping(lut_ptr.add(off), exp_ptr.add(1), 2); - 3 - }; - slice::from_raw_parts(exp_ptr, len) - }; - - let parts = &[ - numfmt::Part::Copy(buf_slice), - numfmt::Part::Zero(added_precision), - numfmt::Part::Copy(exp_slice), - ]; - let sign = if !is_nonnegative { - "-" - } else if f.sign_plus() { - "+" - } else { - "" - }; - let formatted = numfmt::Formatted { sign, parts }; - // SAFETY: `buf_slice` and `exp_slice` contain only ASCII characters. - unsafe { f.pad_formatted_parts(&formatted) } - } - - $( - #[stable(feature = "integer_exp_format", since = "1.42.0")] - impl fmt::LowerExp for $t { - #[allow(unused_comparisons)] - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let is_nonnegative = *self >= 0; - let n = if is_nonnegative { - self.$conv_fn() - } else { - // convert the negative num to positive by summing 1 to it's 2 complement - (!self.$conv_fn()).wrapping_add(1) - }; - $name(n, is_nonnegative, false, f) - } - })* - $( - #[stable(feature = "integer_exp_format", since = "1.42.0")] - impl fmt::UpperExp for $t { - #[allow(unused_comparisons)] - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let is_nonnegative = *self >= 0; - let n = if is_nonnegative { - self.$conv_fn() - } else { - // convert the negative num to positive by summing 1 to it's 2 complement - (!self.$conv_fn()).wrapping_add(1) - }; - $name(n, is_nonnegative, true, f) - } - })* - }; -} - -// Include wasm32 in here since it doesn't reflect the native pointer size, and -// often cares strongly about getting a smaller code size. -#[cfg(any(target_pointer_width = "64", target_arch = "wasm32"))] -mod imp { - use super::*; - impl_Display!( - i8, u8, i16, u16, i32, u32, i64, u64, usize, isize - as u64 via to_u64 named fmt_u64 - ); - impl_Exp!( - i8, u8, i16, u16, i32, u32, i64, u64, usize, isize - as u64 via to_u64 named exp_u64 - ); -} - -#[cfg(not(any(target_pointer_width = "64", target_arch = "wasm32")))] -mod imp { - use super::*; - impl_Display!(i8, u8, i16, u16, i32, u32, isize, usize as u32 via to_u32 named fmt_u32); - impl_Display!(i64, u64 as u64 via to_u64 named fmt_u64); - impl_Exp!(i8, u8, i16, u16, i32, u32, isize, usize as u32 via to_u32 named exp_u32); - impl_Exp!(i64, u64 as u64 via to_u64 named exp_u64); -} -impl_Exp!(i128, u128 as u128 via to_u128 named exp_u128); - -/// Helper function for writing a u64 into `buf` going from last to first, with `curr`. -fn parse_u64_into(mut n: u64, buf: &mut [MaybeUninit; N], curr: &mut usize) { - let buf_ptr = MaybeUninit::slice_as_mut_ptr(buf); - let lut_ptr = DEC_DIGITS_LUT.as_ptr(); - assert!(*curr > 19); - - // SAFETY: - // Writes at most 19 characters into the buffer. Guaranteed that any ptr into LUT is at most - // 198, so will never OOB. There is a check above that there are at least 19 characters - // remaining. - unsafe { - if n >= 1e16 as u64 { - let to_parse = n % 1e16 as u64; - n /= 1e16 as u64; - - // Some of these are nops but it looks more elegant this way. - let d1 = ((to_parse / 1e14 as u64) % 100) << 1; - let d2 = ((to_parse / 1e12 as u64) % 100) << 1; - let d3 = ((to_parse / 1e10 as u64) % 100) << 1; - let d4 = ((to_parse / 1e8 as u64) % 100) << 1; - let d5 = ((to_parse / 1e6 as u64) % 100) << 1; - let d6 = ((to_parse / 1e4 as u64) % 100) << 1; - let d7 = ((to_parse / 1e2 as u64) % 100) << 1; - let d8 = ((to_parse / 1e0 as u64) % 100) << 1; - - *curr -= 16; - - ptr::copy_nonoverlapping(lut_ptr.add(d1 as usize), buf_ptr.add(*curr + 0), 2); - ptr::copy_nonoverlapping(lut_ptr.add(d2 as usize), buf_ptr.add(*curr + 2), 2); - ptr::copy_nonoverlapping(lut_ptr.add(d3 as usize), buf_ptr.add(*curr + 4), 2); - ptr::copy_nonoverlapping(lut_ptr.add(d4 as usize), buf_ptr.add(*curr + 6), 2); - ptr::copy_nonoverlapping(lut_ptr.add(d5 as usize), buf_ptr.add(*curr + 8), 2); - ptr::copy_nonoverlapping(lut_ptr.add(d6 as usize), buf_ptr.add(*curr + 10), 2); - ptr::copy_nonoverlapping(lut_ptr.add(d7 as usize), buf_ptr.add(*curr + 12), 2); - ptr::copy_nonoverlapping(lut_ptr.add(d8 as usize), buf_ptr.add(*curr + 14), 2); - } - if n >= 1e8 as u64 { - let to_parse = n % 1e8 as u64; - n /= 1e8 as u64; - - // Some of these are nops but it looks more elegant this way. - let d1 = ((to_parse / 1e6 as u64) % 100) << 1; - let d2 = ((to_parse / 1e4 as u64) % 100) << 1; - let d3 = ((to_parse / 1e2 as u64) % 100) << 1; - let d4 = ((to_parse / 1e0 as u64) % 100) << 1; - *curr -= 8; - - ptr::copy_nonoverlapping(lut_ptr.add(d1 as usize), buf_ptr.add(*curr + 0), 2); - ptr::copy_nonoverlapping(lut_ptr.add(d2 as usize), buf_ptr.add(*curr + 2), 2); - ptr::copy_nonoverlapping(lut_ptr.add(d3 as usize), buf_ptr.add(*curr + 4), 2); - ptr::copy_nonoverlapping(lut_ptr.add(d4 as usize), buf_ptr.add(*curr + 6), 2); - } - // `n` < 1e8 < (1 << 32) - let mut n = n as u32; - if n >= 1e4 as u32 { - let to_parse = n % 1e4 as u32; - n /= 1e4 as u32; - - let d1 = (to_parse / 100) << 1; - let d2 = (to_parse % 100) << 1; - *curr -= 4; - - ptr::copy_nonoverlapping(lut_ptr.add(d1 as usize), buf_ptr.add(*curr + 0), 2); - ptr::copy_nonoverlapping(lut_ptr.add(d2 as usize), buf_ptr.add(*curr + 2), 2); - } - - // `n` < 1e4 < (1 << 16) - let mut n = n as u16; - if n >= 100 { - let d1 = (n % 100) << 1; - n /= 100; - *curr -= 2; - ptr::copy_nonoverlapping(lut_ptr.add(d1 as usize), buf_ptr.add(*curr), 2); - } - - // decode last 1 or 2 chars - if n < 10 { - *curr -= 1; - *buf_ptr.add(*curr) = (n as u8) + b'0'; - } else { - let d1 = n << 1; - *curr -= 2; - ptr::copy_nonoverlapping(lut_ptr.add(d1 as usize), buf_ptr.add(*curr), 2); - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for u128 { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt_u128(*self, true, f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for i128 { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let is_nonnegative = *self >= 0; - let n = if is_nonnegative { - self.to_u128() - } else { - // convert the negative num to positive by summing 1 to it's 2 complement - (!self.to_u128()).wrapping_add(1) - }; - fmt_u128(n, is_nonnegative, f) - } -} - -/// Specialized optimization for u128. Instead of taking two items at a time, it splits -/// into at most 2 u64s, and then chunks by 10e16, 10e8, 10e4, 10e2, and then 10e1. -/// It also has to handle 1 last item, as 10^40 > 2^128 > 10^39, whereas -/// 10^20 > 2^64 > 10^19. -fn fmt_u128(n: u128, is_nonnegative: bool, f: &mut fmt::Formatter<'_>) -> fmt::Result { - // 2^128 is about 3*10^38, so 39 gives an extra byte of space - let mut buf = [MaybeUninit::::uninit(); 39]; - let mut curr = buf.len(); - - let (n, rem) = udiv_1e19(n); - parse_u64_into(rem, &mut buf, &mut curr); - - if n != 0 { - // 0 pad up to point - let target = buf.len() - 19; - // SAFETY: Guaranteed that we wrote at most 19 bytes, and there must be space - // remaining since it has length 39 - unsafe { - ptr::write_bytes( - MaybeUninit::slice_as_mut_ptr(&mut buf).add(target), - b'0', - curr - target, - ); - } - curr = target; - - let (n, rem) = udiv_1e19(n); - parse_u64_into(rem, &mut buf, &mut curr); - // Should this following branch be annotated with unlikely? - if n != 0 { - let target = buf.len() - 38; - // The raw `buf_ptr` pointer is only valid until `buf` is used the next time, - // buf `buf` is not used in this scope so we are good. - let buf_ptr = MaybeUninit::slice_as_mut_ptr(&mut buf); - // SAFETY: At this point we wrote at most 38 bytes, pad up to that point, - // There can only be at most 1 digit remaining. - unsafe { - ptr::write_bytes(buf_ptr.add(target), b'0', curr - target); - curr = target - 1; - *buf_ptr.add(curr) = (n as u8) + b'0'; - } - } - } - - // SAFETY: `curr` > 0 (since we made `buf` large enough), and all the chars are valid - // UTF-8 since `DEC_DIGITS_LUT` is - let buf_slice = unsafe { - str::from_utf8_unchecked(slice::from_raw_parts( - MaybeUninit::slice_as_mut_ptr(&mut buf).add(curr), - buf.len() - curr, - )) - }; - f.pad_integral(is_nonnegative, "", buf_slice) -} - -/// Partition of `n` into n > 1e19 and rem <= 1e19 -/// -/// Integer division algorithm is based on the following paper: -/// -/// T. Granlund and P. Montgomery, “Division by Invariant Integers Using Multiplication” -/// in Proc. of the SIGPLAN94 Conference on Programming Language Design and -/// Implementation, 1994, pp. 61–72 -/// -fn udiv_1e19(n: u128) -> (u128, u64) { - const DIV: u64 = 1e19 as u64; - const FACTOR: u128 = 156927543384667019095894735580191660403; - - let quot = if n < 1 << 83 { - ((n >> 19) as u64 / (DIV >> 19)) as u128 - } else { - u128_mulhi(n, FACTOR) >> 62 - }; - - let rem = (n - quot * DIV as u128) as u64; - (quot, rem) -} - -/// Multiply unsigned 128 bit integers, return upper 128 bits of the result -#[inline] -fn u128_mulhi(x: u128, y: u128) -> u128 { - let x_lo = x as u64; - let x_hi = (x >> 64) as u64; - let y_lo = y as u64; - let y_hi = (y >> 64) as u64; - - // handle possibility of overflow - let carry = (x_lo as u128 * y_lo as u128) >> 64; - let m = x_lo as u128 * y_hi as u128 + carry; - let high1 = m >> 64; - - let m_lo = m as u64; - let high2 = (x_hi as u128 * y_lo as u128 + m_lo as u128) >> 64; - - x_hi as u128 * y_hi as u128 + high1 + high2 -} diff --git a/library/core/src/fmt/rt.rs b/library/core/src/fmt/rt.rs deleted file mode 100644 index 92626feabf3d7..0000000000000 --- a/library/core/src/fmt/rt.rs +++ /dev/null @@ -1,214 +0,0 @@ -#![allow(missing_debug_implementations)] -#![unstable(feature = "fmt_internals", reason = "internal to format_args!", issue = "none")] - -//! These are the lang items used by format_args!(). - -use super::*; -use crate::hint::unreachable_unchecked; - -#[lang = "format_placeholder"] -#[derive(Copy, Clone)] -pub struct Placeholder { - pub position: usize, - pub fill: char, - pub align: Alignment, - pub flags: u32, - pub precision: Count, - pub width: Count, -} - -impl Placeholder { - #[inline(always)] - pub const fn new( - position: usize, - fill: char, - align: Alignment, - flags: u32, - precision: Count, - width: Count, - ) -> Self { - Self { position, fill, align, flags, precision, width } - } -} - -#[lang = "format_alignment"] -#[derive(Copy, Clone, PartialEq, Eq)] -pub enum Alignment { - Left, - Right, - Center, - Unknown, -} - -/// Used by [width](https://doc.rust-lang.org/std/fmt/#width) -/// and [precision](https://doc.rust-lang.org/std/fmt/#precision) specifiers. -#[lang = "format_count"] -#[derive(Copy, Clone)] -pub enum Count { - /// Specified with a literal number, stores the value - Is(usize), - /// Specified using `$` and `*` syntaxes, stores the index into `args` - Param(usize), - /// Not specified - Implied, -} - -// This needs to match the order of flags in compiler/rustc_ast_lowering/src/format.rs. -#[derive(Copy, Clone)] -pub(super) enum Flag { - SignPlus, - SignMinus, - Alternate, - SignAwareZeroPad, - DebugLowerHex, - DebugUpperHex, -} - -#[derive(Copy, Clone)] -enum ArgumentType<'a> { - Placeholder { value: &'a Opaque, formatter: fn(&Opaque, &mut Formatter<'_>) -> Result }, - Count(usize), -} - -/// This struct represents a generic "argument" which is taken by format_args!(). -/// -/// This can be either a placeholder argument or a count argument. -/// * A placeholder argument contains a function to format the given value. At -/// compile time it is ensured that the function and the value have the correct -/// types, and then this struct is used to canonicalize arguments to one type. -/// Placeholder arguments are essentially an optimized partially applied formatting -/// function, equivalent to `exists T.(&T, fn(&T, &mut Formatter<'_>) -> Result`. -/// * A count argument contains a count for dynamic formatting parameters like -/// precision and width. -#[lang = "format_argument"] -#[derive(Copy, Clone)] -pub struct Argument<'a> { - ty: ArgumentType<'a>, -} - -#[rustc_diagnostic_item = "ArgumentMethods"] -impl<'a> Argument<'a> { - #[inline(always)] - fn new<'b, T>(x: &'b T, f: fn(&T, &mut Formatter<'_>) -> Result) -> Argument<'b> { - // SAFETY: `mem::transmute(x)` is safe because - // 1. `&'b T` keeps the lifetime it originated with `'b` - // (so as to not have an unbounded lifetime) - // 2. `&'b T` and `&'b Opaque` have the same memory layout - // (when `T` is `Sized`, as it is here) - // `mem::transmute(f)` is safe since `fn(&T, &mut Formatter<'_>) -> Result` - // and `fn(&Opaque, &mut Formatter<'_>) -> Result` have the same ABI - // (as long as `T` is `Sized`) - unsafe { - Argument { - ty: ArgumentType::Placeholder { - formatter: mem::transmute(f), - value: mem::transmute(x), - }, - } - } - } - - #[inline(always)] - pub fn new_display<'b, T: Display>(x: &'b T) -> Argument<'_> { - Self::new(x, Display::fmt) - } - #[inline(always)] - pub fn new_debug<'b, T: Debug>(x: &'b T) -> Argument<'_> { - Self::new(x, Debug::fmt) - } - #[inline(always)] - pub fn new_octal<'b, T: Octal>(x: &'b T) -> Argument<'_> { - Self::new(x, Octal::fmt) - } - #[inline(always)] - pub fn new_lower_hex<'b, T: LowerHex>(x: &'b T) -> Argument<'_> { - Self::new(x, LowerHex::fmt) - } - #[inline(always)] - pub fn new_upper_hex<'b, T: UpperHex>(x: &'b T) -> Argument<'_> { - Self::new(x, UpperHex::fmt) - } - #[inline(always)] - pub fn new_pointer<'b, T: Pointer>(x: &'b T) -> Argument<'_> { - Self::new(x, Pointer::fmt) - } - #[inline(always)] - pub fn new_binary<'b, T: Binary>(x: &'b T) -> Argument<'_> { - Self::new(x, Binary::fmt) - } - #[inline(always)] - pub fn new_lower_exp<'b, T: LowerExp>(x: &'b T) -> Argument<'_> { - Self::new(x, LowerExp::fmt) - } - #[inline(always)] - pub fn new_upper_exp<'b, T: UpperExp>(x: &'b T) -> Argument<'_> { - Self::new(x, UpperExp::fmt) - } - #[inline(always)] - pub fn from_usize(x: &usize) -> Argument<'_> { - Argument { ty: ArgumentType::Count(*x) } - } - - /// Format this placeholder argument. - /// - /// # Safety - /// - /// This argument must actually be a placeholder argument. - /// - // FIXME: Transmuting formatter in new and indirectly branching to/calling - // it here is an explicit CFI violation. - #[allow(inline_no_sanitize)] - #[no_sanitize(cfi, kcfi)] - #[inline(always)] - pub(super) unsafe fn fmt(&self, f: &mut Formatter<'_>) -> Result { - match self.ty { - ArgumentType::Placeholder { formatter, value } => formatter(value, f), - // SAFETY: the caller promised this. - ArgumentType::Count(_) => unsafe { unreachable_unchecked() }, - } - } - - #[inline(always)] - pub(super) fn as_usize(&self) -> Option { - match self.ty { - ArgumentType::Count(count) => Some(count), - ArgumentType::Placeholder { .. } => None, - } - } - - /// Used by `format_args` when all arguments are gone after inlining, - /// when using `&[]` would incorrectly allow for a bigger lifetime. - /// - /// This fails without format argument inlining, and that shouldn't be different - /// when the argument is inlined: - /// - /// ```compile_fail,E0716 - /// let f = format_args!("{}", "a"); - /// println!("{f}"); - /// ``` - #[inline(always)] - pub fn none() -> [Self; 0] { - [] - } -} - -/// This struct represents the unsafety of constructing an `Arguments`. -/// It exists, rather than an unsafe function, in order to simplify the expansion -/// of `format_args!(..)` and reduce the scope of the `unsafe` block. -#[lang = "format_unsafe_arg"] -pub struct UnsafeArg { - _private: (), -} - -impl UnsafeArg { - /// See documentation where `UnsafeArg` is required to know when it is safe to - /// create and use `UnsafeArg`. - #[inline(always)] - pub unsafe fn new() -> Self { - Self { _private: () } - } -} - -extern "C" { - type Opaque; -} diff --git a/library/core/src/future/async_drop.rs b/library/core/src/future/async_drop.rs deleted file mode 100644 index 0eb8d7bb32899..0000000000000 --- a/library/core/src/future/async_drop.rs +++ /dev/null @@ -1,271 +0,0 @@ -#![unstable(feature = "async_drop", issue = "none")] - -use crate::fmt; -use crate::future::{Future, IntoFuture}; -use crate::intrinsics::discriminant_value; -use crate::marker::{DiscriminantKind, PhantomPinned}; -use crate::mem::MaybeUninit; -use crate::pin::Pin; -use crate::task::{ready, Context, Poll}; - -/// Asynchronously drops a value by running `AsyncDrop::async_drop` -/// on a value and its fields recursively. -#[unstable(feature = "async_drop", issue = "none")] -pub fn async_drop(value: T) -> AsyncDropOwning { - AsyncDropOwning { value: MaybeUninit::new(value), dtor: None, _pinned: PhantomPinned } -} - -/// A future returned by the [`async_drop`]. -#[unstable(feature = "async_drop", issue = "none")] -pub struct AsyncDropOwning { - value: MaybeUninit, - dtor: Option>, - _pinned: PhantomPinned, -} - -#[unstable(feature = "async_drop", issue = "none")] -impl fmt::Debug for AsyncDropOwning { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("AsyncDropOwning").finish_non_exhaustive() - } -} - -#[unstable(feature = "async_drop", issue = "none")] -impl Future for AsyncDropOwning { - type Output = (); - - fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll { - // SAFETY: Self is pinned thus it is ok to store references to self - unsafe { - let this = self.get_unchecked_mut(); - let dtor = Pin::new_unchecked( - this.dtor.get_or_insert_with(|| async_drop_in_place(this.value.as_mut_ptr())), - ); - // AsyncDestuctors are idempotent so Self gets idempotency as well - dtor.poll(cx) - } - } -} - -#[lang = "async_drop_in_place"] -#[allow(unconditional_recursion)] -// FIXME: Consider if `#[rustc_diagnostic_item = "ptr_drop_in_place"]` is needed? -unsafe fn async_drop_in_place_raw( - to_drop: *mut T, -) -> ::AsyncDestructor { - // Code here does not matter - this is replaced by the - // real async drop glue constructor by the compiler. - - // SAFETY: see comment above - unsafe { async_drop_in_place_raw(to_drop) } -} - -/// Creates the asynchronous destructor of the pointed-to value. -/// -/// # Safety -/// -/// Behavior is undefined if any of the following conditions are violated: -/// -/// * `to_drop` must be [valid](crate::ptr#safety) for both reads and writes. -/// -/// * `to_drop` must be properly aligned, even if `T` has size 0. -/// -/// * `to_drop` must be nonnull, even if `T` has size 0. -/// -/// * The value `to_drop` points to must be valid for async dropping, -/// which may mean it must uphold additional invariants. These -/// invariants depend on the type of the value being dropped. For -/// instance, when dropping a Box, the box's pointer to the heap must -/// be valid. -/// -/// * While `async_drop_in_place` is executing or the returned async -/// destructor is alive, the only way to access parts of `to_drop` -/// is through the `self: Pin<&mut Self>` references supplied to -/// the `AsyncDrop::async_drop` methods that `async_drop_in_place` -/// or `AsyncDropInPlace::poll` invokes. This usually means the -/// returned future stores the `to_drop` pointer and user is required -/// to guarantee that dropped value doesn't move. -/// -#[unstable(feature = "async_drop", issue = "none")] -pub unsafe fn async_drop_in_place(to_drop: *mut T) -> AsyncDropInPlace { - // SAFETY: `async_drop_in_place_raw` has the same safety requirements - unsafe { AsyncDropInPlace(async_drop_in_place_raw(to_drop)) } -} - -/// A future returned by the [`async_drop_in_place`]. -#[unstable(feature = "async_drop", issue = "none")] -pub struct AsyncDropInPlace(::AsyncDestructor); - -#[unstable(feature = "async_drop", issue = "none")] -impl fmt::Debug for AsyncDropInPlace { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("AsyncDropInPlace").finish_non_exhaustive() - } -} - -#[unstable(feature = "async_drop", issue = "none")] -impl Future for AsyncDropInPlace { - type Output = (); - - #[inline(always)] - fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll { - // SAFETY: This code simply forwards poll call to the inner future - unsafe { Pin::new_unchecked(&mut self.get_unchecked_mut().0) }.poll(cx) - } -} - -// FIXME(zetanumbers): Add same restrictions on AsyncDrop impls as -// with Drop impls -/// Custom code within the asynchronous destructor. -#[unstable(feature = "async_drop", issue = "none")] -#[lang = "async_drop"] -pub trait AsyncDrop { - /// A future returned by the [`AsyncDrop::async_drop`] to be part - /// of the async destructor. - #[unstable(feature = "async_drop", issue = "none")] - type Dropper<'a>: Future - where - Self: 'a; - - /// Constructs the asynchronous destructor for this type. - #[unstable(feature = "async_drop", issue = "none")] - fn async_drop(self: Pin<&mut Self>) -> Self::Dropper<'_>; -} - -#[lang = "async_destruct"] -#[rustc_deny_explicit_impl(implement_via_object = false)] -trait AsyncDestruct { - type AsyncDestructor: Future; -} - -/// Basically calls `AsyncDrop::async_drop` with pointer. Used to simplify -/// generation of the code for `async_drop_in_place_raw` -#[lang = "surface_async_drop_in_place"] -async unsafe fn surface_async_drop_in_place(ptr: *mut T) { - // SAFETY: We call this from async drop `async_drop_in_place_raw` - // which has the same safety requirements - unsafe { ::async_drop(Pin::new_unchecked(&mut *ptr)).await } -} - -/// Basically calls `Drop::drop` with pointer. Used to simplify generation -/// of the code for `async_drop_in_place_raw` -#[allow(drop_bounds)] -#[lang = "async_drop_surface_drop_in_place"] -async unsafe fn surface_drop_in_place(ptr: *mut T) { - // SAFETY: We call this from async drop `async_drop_in_place_raw` - // which has the same safety requirements - unsafe { crate::ops::fallback_surface_drop(&mut *ptr) } -} - -/// Wraps a future to continue outputing `Poll::Ready(())` once after -/// wrapped future completes by returning `Poll::Ready(())` on poll. This -/// is useful for constructing async destructors to guarantee this -/// "fuse" property -struct Fuse { - inner: Option, -} - -#[lang = "async_drop_fuse"] -fn fuse(inner: T) -> Fuse { - Fuse { inner: Some(inner) } -} - -impl Future for Fuse -where - T: Future, -{ - type Output = (); - - fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll { - // SAFETY: pin projection into `self.inner` - unsafe { - let this = self.get_unchecked_mut(); - if let Some(inner) = &mut this.inner { - ready!(Pin::new_unchecked(inner).poll(cx)); - this.inner = None; - } - } - Poll::Ready(()) - } -} - -/// Async destructor for arrays and slices. -#[lang = "async_drop_slice"] -async unsafe fn slice(s: *mut [T]) { - let len = s.len(); - let ptr = s.as_mut_ptr(); - for i in 0..len { - // SAFETY: we iterate over elements of `s` slice - unsafe { async_drop_in_place_raw(ptr.add(i)).await } - } -} - -/// Construct a chain of two futures, which awaits them sequentially as -/// a future. -#[lang = "async_drop_chain"] -async fn chain(first: F, last: G) -where - F: IntoFuture, - G: IntoFuture, -{ - first.await; - last.await; -} - -/// Basically a lazy version of `async_drop_in_place`. Returns a future -/// that would call `AsyncDrop::async_drop` on a first poll. -/// -/// # Safety -/// -/// Same as `async_drop_in_place` except is lazy to avoid creating -/// multiple mutable refernces. -#[lang = "async_drop_defer"] -async unsafe fn defer(to_drop: *mut T) { - // SAFETY: same safety requirements as `async_drop_in_place` - unsafe { async_drop_in_place(to_drop) }.await -} - -/// If `T`'s discriminant is equal to the stored one then awaits `M` -/// otherwise awaits the `O`. -/// -/// # Safety -/// -/// User should carefully manage returned future, since it would -/// try creating an immutable referece from `this` and get pointee's -/// discriminant. -// FIXME(zetanumbers): Send and Sync impls -#[lang = "async_drop_either"] -async unsafe fn either, M: IntoFuture, T>( - other: O, - matched: M, - this: *mut T, - discr: ::Discriminant, -) { - // SAFETY: Guaranteed by the safety section of this funtion's documentation - if unsafe { discriminant_value(&*this) } == discr { - drop(other); - matched.await - } else { - drop(matched); - other.await - } -} - -/// Used for noop async destructors. We don't use [`core::future::Ready`] -/// because it panics after its second poll, which could be potentially -/// bad if that would happen during the cleanup. -#[derive(Clone, Copy)] -struct Noop; - -#[lang = "async_drop_noop"] -fn noop() -> Noop { - Noop -} - -impl Future for Noop { - type Output = (); - - fn poll(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll { - Poll::Ready(()) - } -} diff --git a/library/core/src/future/future.rs b/library/core/src/future/future.rs deleted file mode 100644 index f965afc8a5937..0000000000000 --- a/library/core/src/future/future.rs +++ /dev/null @@ -1,125 +0,0 @@ -#![stable(feature = "futures_api", since = "1.36.0")] - -use crate::ops; -use crate::pin::Pin; -use crate::task::{Context, Poll}; - -/// A future represents an asynchronous computation obtained by use of [`async`]. -/// -/// A future is a value that might not have finished computing yet. This kind of -/// "asynchronous value" makes it possible for a thread to continue doing useful -/// work while it waits for the value to become available. -/// -/// # The `poll` method -/// -/// The core method of future, `poll`, *attempts* to resolve the future into a -/// final value. This method does not block if the value is not ready. Instead, -/// the current task is scheduled to be woken up when it's possible to make -/// further progress by `poll`ing again. The `context` passed to the `poll` -/// method can provide a [`Waker`], which is a handle for waking up the current -/// task. -/// -/// When using a future, you generally won't call `poll` directly, but instead -/// `.await` the value. -/// -/// [`async`]: ../../std/keyword.async.html -/// [`Waker`]: crate::task::Waker -#[doc(notable_trait)] -#[must_use = "futures do nothing unless you `.await` or poll them"] -#[stable(feature = "futures_api", since = "1.36.0")] -#[lang = "future_trait"] -#[diagnostic::on_unimplemented( - label = "`{Self}` is not a future", - message = "`{Self}` is not a future" -)] -pub trait Future { - /// The type of value produced on completion. - #[stable(feature = "futures_api", since = "1.36.0")] - #[rustc_diagnostic_item = "FutureOutput"] - type Output; - - /// Attempt to resolve the future to a final value, registering - /// the current task for wakeup if the value is not yet available. - /// - /// # Return value - /// - /// This function returns: - /// - /// - [`Poll::Pending`] if the future is not ready yet - /// - [`Poll::Ready(val)`] with the result `val` of this future if it - /// finished successfully. - /// - /// Once a future has finished, clients should not `poll` it again. - /// - /// When a future is not ready yet, `poll` returns `Poll::Pending` and - /// stores a clone of the [`Waker`] copied from the current [`Context`]. - /// This [`Waker`] is then woken once the future can make progress. - /// For example, a future waiting for a socket to become - /// readable would call `.clone()` on the [`Waker`] and store it. - /// When a signal arrives elsewhere indicating that the socket is readable, - /// [`Waker::wake`] is called and the socket future's task is awoken. - /// Once a task has been woken up, it should attempt to `poll` the future - /// again, which may or may not produce a final value. - /// - /// Note that on multiple calls to `poll`, only the [`Waker`] from the - /// [`Context`] passed to the most recent call should be scheduled to - /// receive a wakeup. - /// - /// # Runtime characteristics - /// - /// Futures alone are *inert*; they must be *actively* `poll`ed to make - /// progress, meaning that each time the current task is woken up, it should - /// actively re-`poll` pending futures that it still has an interest in. - /// - /// The `poll` function is not called repeatedly in a tight loop -- instead, - /// it should only be called when the future indicates that it is ready to - /// make progress (by calling `wake()`). If you're familiar with the - /// `poll(2)` or `select(2)` syscalls on Unix it's worth noting that futures - /// typically do *not* suffer the same problems of "all wakeups must poll - /// all events"; they are more like `epoll(4)`. - /// - /// An implementation of `poll` should strive to return quickly, and should - /// not block. Returning quickly prevents unnecessarily clogging up - /// threads or event loops. If it is known ahead of time that a call to - /// `poll` may end up taking a while, the work should be offloaded to a - /// thread pool (or something similar) to ensure that `poll` can return - /// quickly. - /// - /// # Panics - /// - /// Once a future has completed (returned `Ready` from `poll`), calling its - /// `poll` method again may panic, block forever, or cause other kinds of - /// problems; the `Future` trait places no requirements on the effects of - /// such a call. However, as the `poll` method is not marked `unsafe`, - /// Rust's usual rules apply: calls must never cause undefined behavior - /// (memory corruption, incorrect use of `unsafe` functions, or the like), - /// regardless of the future's state. - /// - /// [`Poll::Ready(val)`]: Poll::Ready - /// [`Waker`]: crate::task::Waker - /// [`Waker::wake`]: crate::task::Waker::wake - #[lang = "poll"] - #[stable(feature = "futures_api", since = "1.36.0")] - fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll; -} - -#[stable(feature = "futures_api", since = "1.36.0")] -impl Future for &mut F { - type Output = F::Output; - - fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll { - F::poll(Pin::new(&mut **self), cx) - } -} - -#[stable(feature = "futures_api", since = "1.36.0")] -impl

Future for Pin

-where - P: ops::DerefMut, -{ - type Output = <

::Target as Future>::Output; - - fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll { - ::poll(self.as_deref_mut(), cx) - } -} diff --git a/library/core/src/future/into_future.rs b/library/core/src/future/into_future.rs deleted file mode 100644 index eb5a9b72dd0f2..0000000000000 --- a/library/core/src/future/into_future.rs +++ /dev/null @@ -1,145 +0,0 @@ -use crate::future::Future; - -/// Conversion into a `Future`. -/// -/// By implementing `IntoFuture` for a type, you define how it will be -/// converted to a future. -/// -/// # `.await` desugaring -/// -/// The `.await` keyword desugars into a call to `IntoFuture::into_future` -/// first before polling the future to completion. `IntoFuture` is implemented -/// for all `T: Future` which means the `into_future` method will be available -/// on all futures. -/// -/// ```no_run -/// use std::future::IntoFuture; -/// -/// # async fn foo() { -/// let v = async { "meow" }; -/// let mut fut = v.into_future(); -/// assert_eq!("meow", fut.await); -/// # } -/// ``` -/// -/// # Async builders -/// -/// When implementing futures manually there will often be a choice between -/// implementing `Future` or `IntoFuture` for a type. Implementing `Future` is a -/// good choice in most cases. But implementing `IntoFuture` is most useful when -/// implementing "async builder" types, which allow their values to be modified -/// multiple times before being `.await`ed. -/// -/// ```rust -/// use std::future::{ready, Ready, IntoFuture}; -/// -/// /// Eventually multiply two numbers -/// pub struct Multiply { -/// num: u16, -/// factor: u16, -/// } -/// -/// impl Multiply { -/// /// Construct a new instance of `Multiply`. -/// pub fn new(num: u16, factor: u16) -> Self { -/// Self { num, factor } -/// } -/// -/// /// Set the number to multiply by the factor. -/// pub fn number(mut self, num: u16) -> Self { -/// self.num = num; -/// self -/// } -/// -/// /// Set the factor to multiply the number with. -/// pub fn factor(mut self, factor: u16) -> Self { -/// self.factor = factor; -/// self -/// } -/// } -/// -/// impl IntoFuture for Multiply { -/// type Output = u16; -/// type IntoFuture = Ready; -/// -/// fn into_future(self) -> Self::IntoFuture { -/// ready(self.num * self.factor) -/// } -/// } -/// -/// // NOTE: Rust does not yet have an `async fn main` function, that functionality -/// // currently only exists in the ecosystem. -/// async fn run() { -/// let num = Multiply::new(0, 0) // initialize the builder to number: 0, factor: 0 -/// .number(2) // change the number to 2 -/// .factor(2) // change the factor to 2 -/// .await; // convert to future and .await -/// -/// assert_eq!(num, 4); -/// } -/// ``` -/// -/// # Usage in trait bounds -/// -/// Using `IntoFuture` in trait bounds allows a function to be generic over both -/// `Future` and `IntoFuture`. This is convenient for users of the function, so -/// when they are using it they don't have to make an extra call to -/// `IntoFuture::into_future` to obtain an instance of `Future`: -/// -/// ```rust -/// use std::future::IntoFuture; -/// -/// /// Convert the output of a future to a string. -/// async fn fut_to_string(fut: Fut) -> String -/// where -/// Fut: IntoFuture, -/// Fut::Output: std::fmt::Debug, -/// { -/// format!("{:?}", fut.await) -/// } -/// ``` -#[stable(feature = "into_future", since = "1.64.0")] -#[rustc_diagnostic_item = "IntoFuture"] -#[diagnostic::on_unimplemented( - label = "`{Self}` is not a future", - message = "`{Self}` is not a future", - note = "{Self} must be a future or must implement `IntoFuture` to be awaited" -)] -pub trait IntoFuture { - /// The output that the future will produce on completion. - #[stable(feature = "into_future", since = "1.64.0")] - type Output; - - /// Which kind of future are we turning this into? - #[stable(feature = "into_future", since = "1.64.0")] - type IntoFuture: Future; - - /// Creates a future from a value. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ```no_run - /// use std::future::IntoFuture; - /// - /// # async fn foo() { - /// let v = async { "meow" }; - /// let mut fut = v.into_future(); - /// assert_eq!("meow", fut.await); - /// # } - /// ``` - #[stable(feature = "into_future", since = "1.64.0")] - #[lang = "into_future"] - fn into_future(self) -> Self::IntoFuture; -} - -#[stable(feature = "into_future", since = "1.64.0")] -impl IntoFuture for F { - type Output = F::Output; - type IntoFuture = F; - - fn into_future(self) -> Self::IntoFuture { - self - } -} diff --git a/library/core/src/future/join.rs b/library/core/src/future/join.rs deleted file mode 100644 index 3f35179ddc29b..0000000000000 --- a/library/core/src/future/join.rs +++ /dev/null @@ -1,193 +0,0 @@ -#![allow(unused_imports, unused_macros)] // items are used by the macro - -use crate::cell::UnsafeCell; -use crate::future::{poll_fn, Future}; -use crate::mem; -use crate::pin::Pin; -use crate::task::{ready, Context, Poll}; - -/// Polls multiple futures simultaneously, returning a tuple -/// of all results once complete. -/// -/// While `join!(a, b).await` is similar to `(a.await, b.await)`, -/// `join!` polls both futures concurrently and is therefore more efficient. -/// -/// # Examples -/// -/// ``` -/// #![feature(future_join)] -/// -/// use std::future::join; -/// -/// async fn one() -> usize { 1 } -/// async fn two() -> usize { 2 } -/// -/// # let _ = async { -/// let x = join!(one(), two()).await; -/// assert_eq!(x, (1, 2)); -/// # }; -/// ``` -/// -/// `join!` is variadic, so you can pass any number of futures: -/// -/// ``` -/// #![feature(future_join)] -/// -/// use std::future::join; -/// -/// async fn one() -> usize { 1 } -/// async fn two() -> usize { 2 } -/// async fn three() -> usize { 3 } -/// -/// # let _ = async { -/// let x = join!(one(), two(), three()).await; -/// assert_eq!(x, (1, 2, 3)); -/// # }; -/// ``` -#[unstable(feature = "future_join", issue = "91642")] -pub macro join( $($fut:expr),+ $(,)? ) { - // Funnel through an internal macro not to leak implementation details. - join_internal! { - current_position: [] - futures_and_positions: [] - munching: [ $($fut)+ ] - } -} - -// FIXME(danielhenrymantilla): a private macro should need no stability guarantee. -#[unstable(feature = "future_join", issue = "91642")] -/// To be able to *name* the i-th future in the tuple (say we want the .4-th), -/// the following trick will be used: `let (_, _, _, _, it, ..) = tuple;` -/// In order to do that, we need to generate a `i`-long repetition of `_`, -/// for each i-th fut. Hence the recursive muncher approach. -macro join_internal { - // Recursion step: map each future with its "position" (underscore count). - ( - // Accumulate a token for each future that has been expanded: "_ _ _". - current_position: [ - $($underscores:tt)* - ] - // Accumulate Futures and their positions in the tuple: `_0th () _1st ( _ ) …`. - futures_and_positions: [ - $($acc:tt)* - ] - // Munch one future. - munching: [ - $current:tt - $($rest:tt)* - ] - ) => ( - join_internal! { - current_position: [ - $($underscores)* - _ - ] - futures_and_positions: [ - $($acc)* - $current ( $($underscores)* ) - ] - munching: [ - $($rest)* - ] - } - ), - - // End of recursion: generate the output future. - ( - current_position: $_:tt - futures_and_positions: [ - $( - $fut_expr:tt ( $($pos:tt)* ) - )* - ] - // Nothing left to munch. - munching: [] - ) => ( - match ( $( MaybeDone::Future($fut_expr), )* ) { futures => async { - let mut futures = futures; - // SAFETY: this is `pin_mut!`. - let mut futures = unsafe { Pin::new_unchecked(&mut futures) }; - poll_fn(move |cx| { - let mut done = true; - // For each `fut`, pin-project to it, and poll it. - $( - // SAFETY: pinning projection - let fut = unsafe { - futures.as_mut().map_unchecked_mut(|it| { - let ( $($pos,)* fut, .. ) = it; - fut - }) - }; - // Despite how tempting it may be to `let () = ready!(fut.poll(cx));` - // doing so would defeat the point of `join!`: to start polling eagerly all - // of the futures, to allow parallelizing the waits. - done &= fut.poll(cx).is_ready(); - )* - if !done { - return Poll::Pending; - } - // All ready; time to extract all the outputs. - - // SAFETY: `.take_output()` does not break the `Pin` invariants for that `fut`. - let futures = unsafe { - futures.as_mut().get_unchecked_mut() - }; - Poll::Ready( - ($( - { - let ( $($pos,)* fut, .. ) = &mut *futures; - fut.take_output().unwrap() - } - ),*) // <- no trailing comma since we don't want 1-tuples. - ) - }).await - }} - ), -} - -/// Future used by `join!` that stores it's output to -/// be later taken and doesn't panic when polled after ready. -/// -/// This type is public in a private module for use by the macro. -#[allow(missing_debug_implementations)] -#[unstable(feature = "future_join", issue = "91642")] -pub enum MaybeDone { - Future(F), - Done(F::Output), - Taken, -} - -#[unstable(feature = "future_join", issue = "91642")] -impl MaybeDone { - pub fn take_output(&mut self) -> Option { - match *self { - MaybeDone::Done(_) => match mem::replace(self, Self::Taken) { - MaybeDone::Done(val) => Some(val), - _ => unreachable!(), - }, - _ => None, - } - } -} - -#[unstable(feature = "future_join", issue = "91642")] -impl Future for MaybeDone { - type Output = (); - - fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll { - // SAFETY: pinning in structural for `f` - unsafe { - // Do not mix match ergonomics with unsafe. - match *self.as_mut().get_unchecked_mut() { - MaybeDone::Future(ref mut f) => { - let val = ready!(Pin::new_unchecked(f).poll(cx)); - self.set(Self::Done(val)); - } - MaybeDone::Done(_) => {} - MaybeDone::Taken => unreachable!(), - } - } - - Poll::Ready(()) - } -} diff --git a/library/core/src/future/mod.rs b/library/core/src/future/mod.rs deleted file mode 100644 index 873cccc7e96fd..0000000000000 --- a/library/core/src/future/mod.rs +++ /dev/null @@ -1,72 +0,0 @@ -#![stable(feature = "futures_api", since = "1.36.0")] - -//! Asynchronous basic functionality. -//! -//! Please see the fundamental [`async`] and [`await`] keywords and the [async book] -//! for more information on asynchronous programming in Rust. -//! -//! [`async`]: ../../std/keyword.async.html -//! [`await`]: ../../std/keyword.await.html -//! [async book]: https://rust-lang.github.io/async-book/ - -use crate::ptr::NonNull; -use crate::task::Context; - -mod async_drop; -mod future; -mod into_future; -mod join; -mod pending; -mod poll_fn; -mod ready; - -#[stable(feature = "futures_api", since = "1.36.0")] -pub use self::future::Future; - -#[unstable(feature = "future_join", issue = "91642")] -pub use self::join::join; - -#[stable(feature = "into_future", since = "1.64.0")] -pub use into_future::IntoFuture; - -#[stable(feature = "future_readiness_fns", since = "1.48.0")] -pub use pending::{pending, Pending}; -#[stable(feature = "future_readiness_fns", since = "1.48.0")] -pub use ready::{ready, Ready}; - -#[stable(feature = "future_poll_fn", since = "1.64.0")] -pub use poll_fn::{poll_fn, PollFn}; - -#[unstable(feature = "async_drop", issue = "none")] -pub use async_drop::{async_drop, async_drop_in_place, AsyncDrop, AsyncDropInPlace}; - -/// This type is needed because: -/// -/// a) Coroutines cannot implement `for<'a, 'b> Coroutine<&'a mut Context<'b>>`, so we need to pass -/// a raw pointer (see ). -/// b) Raw pointers and `NonNull` aren't `Send` or `Sync`, so that would make every single future -/// non-Send/Sync as well, and we don't want that. -/// -/// It also simplifies the HIR lowering of `.await`. -#[lang = "ResumeTy"] -#[doc(hidden)] -#[unstable(feature = "gen_future", issue = "50547")] -#[derive(Debug, Copy, Clone)] -pub struct ResumeTy(NonNull>); - -#[unstable(feature = "gen_future", issue = "50547")] -unsafe impl Send for ResumeTy {} - -#[unstable(feature = "gen_future", issue = "50547")] -unsafe impl Sync for ResumeTy {} - -#[lang = "get_context"] -#[doc(hidden)] -#[unstable(feature = "gen_future", issue = "50547")] -#[must_use] -#[inline] -pub unsafe fn get_context<'a, 'b>(cx: ResumeTy) -> &'a mut Context<'b> { - // SAFETY: the caller must guarantee that `cx.0` is a valid pointer - // that fulfills all the requirements for a mutable reference. - unsafe { &mut *cx.0.as_ptr().cast() } -} diff --git a/library/core/src/future/pending.rs b/library/core/src/future/pending.rs deleted file mode 100644 index 2877e66eca885..0000000000000 --- a/library/core/src/future/pending.rs +++ /dev/null @@ -1,58 +0,0 @@ -use crate::fmt::{self, Debug}; -use crate::future::Future; -use crate::marker; -use crate::pin::Pin; -use crate::task::{Context, Poll}; - -/// Creates a future which never resolves, representing a computation that never -/// finishes. -/// -/// This `struct` is created by [`pending()`]. See its -/// documentation for more. -#[stable(feature = "future_readiness_fns", since = "1.48.0")] -#[must_use = "futures do nothing unless you `.await` or poll them"] -pub struct Pending { - _data: marker::PhantomData T>, -} - -/// Creates a future which never resolves, representing a computation that never -/// finishes. -/// -/// # Examples -/// -/// ```no_run -/// use std::future; -/// -/// # async fn run() { -/// let future = future::pending(); -/// let () = future.await; -/// unreachable!(); -/// # } -/// ``` -#[stable(feature = "future_readiness_fns", since = "1.48.0")] -pub fn pending() -> Pending { - Pending { _data: marker::PhantomData } -} - -#[stable(feature = "future_readiness_fns", since = "1.48.0")] -impl Future for Pending { - type Output = T; - - fn poll(self: Pin<&mut Self>, _: &mut Context<'_>) -> Poll { - Poll::Pending - } -} - -#[stable(feature = "future_readiness_fns", since = "1.48.0")] -impl Debug for Pending { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Pending").finish() - } -} - -#[stable(feature = "future_readiness_fns", since = "1.48.0")] -impl Clone for Pending { - fn clone(&self) -> Self { - pending() - } -} diff --git a/library/core/src/future/poll_fn.rs b/library/core/src/future/poll_fn.rs deleted file mode 100644 index d27a9dfc176e3..0000000000000 --- a/library/core/src/future/poll_fn.rs +++ /dev/null @@ -1,153 +0,0 @@ -use crate::fmt; -use crate::future::Future; -use crate::pin::Pin; -use crate::task::{Context, Poll}; - -/// Creates a future that wraps a function returning [`Poll`]. -/// -/// Polling the future delegates to the wrapped function. If the returned future is pinned, then the -/// captured environment of the wrapped function is also pinned in-place, so as long as the closure -/// does not move out of its captures it can soundly create pinned references to them. -/// -/// # Examples -/// -/// ``` -/// # async fn run() { -/// use core::future::poll_fn; -/// use std::task::{Context, Poll}; -/// -/// fn read_line(_cx: &mut Context<'_>) -> Poll { -/// Poll::Ready("Hello, World!".into()) -/// } -/// -/// let read_future = poll_fn(read_line); -/// assert_eq!(read_future.await, "Hello, World!".to_owned()); -/// # } -/// ``` -/// -/// ## Capturing a pinned state -/// -/// Example of a closure wrapping inner futures: -/// -/// ``` -/// # async fn run() { -/// use core::future::{self, Future}; -/// use core::task::Poll; -/// -/// /// Resolves to the first future that completes. In the event of a tie, `a` wins. -/// fn naive_select( -/// a: impl Future, -/// b: impl Future, -/// ) -> impl Future -/// { -/// let (mut a, mut b) = (Box::pin(a), Box::pin(b)); -/// future::poll_fn(move |cx| { -/// if let Poll::Ready(r) = a.as_mut().poll(cx) { -/// Poll::Ready(r) -/// } else if let Poll::Ready(r) = b.as_mut().poll(cx) { -/// Poll::Ready(r) -/// } else { -/// Poll::Pending -/// } -/// }) -/// } -/// -/// let a = async { 42 }; -/// let b = future::pending(); -/// let v = naive_select(a, b).await; -/// assert_eq!(v, 42); -/// -/// let a = future::pending(); -/// let b = async { 27 }; -/// let v = naive_select(a, b).await; -/// assert_eq!(v, 27); -/// -/// let a = async { 42 }; -/// let b = async { 27 }; -/// let v = naive_select(a, b).await; -/// assert_eq!(v, 42); // biased towards `a` in case of tie! -/// # } -/// ``` -/// -/// This time without [`Box::pin`]ning: -/// -/// [`Box::pin`]: ../../std/boxed/struct.Box.html#method.pin -/// -/// ``` -/// # async fn run() { -/// use core::future::{self, Future}; -/// use core::pin::pin; -/// use core::task::Poll; -/// -/// /// Resolves to the first future that completes. In the event of a tie, `a` wins. -/// fn naive_select( -/// a: impl Future, -/// b: impl Future, -/// ) -> impl Future -/// { -/// async { -/// let (mut a, mut b) = (pin!(a), pin!(b)); -/// future::poll_fn(move |cx| { -/// if let Poll::Ready(r) = a.as_mut().poll(cx) { -/// Poll::Ready(r) -/// } else if let Poll::Ready(r) = b.as_mut().poll(cx) { -/// Poll::Ready(r) -/// } else { -/// Poll::Pending -/// } -/// }).await -/// } -/// } -/// -/// let a = async { 42 }; -/// let b = future::pending(); -/// let v = naive_select(a, b).await; -/// assert_eq!(v, 42); -/// # } -/// ``` -/// -/// - Notice how, by virtue of being in an `async` context, we have been able to make the [`pin!`] -/// macro work, thereby avoiding any need for the `unsafe` -/// [Pin::new_unchecked](&mut fut) constructor. -/// -/// [`pin!`]: crate::pin::pin! -#[stable(feature = "future_poll_fn", since = "1.64.0")] -pub fn poll_fn(f: F) -> PollFn -where - F: FnMut(&mut Context<'_>) -> Poll, -{ - PollFn { f } -} - -/// A Future that wraps a function returning [`Poll`]. -/// -/// This `struct` is created by [`poll_fn()`]. See its -/// documentation for more. -#[must_use = "futures do nothing unless you `.await` or poll them"] -#[stable(feature = "future_poll_fn", since = "1.64.0")] -pub struct PollFn { - f: F, -} - -#[stable(feature = "future_poll_fn", since = "1.64.0")] -impl Unpin for PollFn {} - -#[stable(feature = "future_poll_fn", since = "1.64.0")] -impl fmt::Debug for PollFn { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("PollFn").finish() - } -} - -#[stable(feature = "future_poll_fn", since = "1.64.0")] -impl Future for PollFn -where - F: FnMut(&mut Context<'_>) -> Poll, -{ - type Output = T; - - fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll { - // SAFETY: We are not moving out of the pinned field. - (unsafe { &mut self.get_unchecked_mut().f })(cx) - } -} diff --git a/library/core/src/future/ready.rs b/library/core/src/future/ready.rs deleted file mode 100644 index a07b63fb62b90..0000000000000 --- a/library/core/src/future/ready.rs +++ /dev/null @@ -1,70 +0,0 @@ -use crate::future::Future; -use crate::pin::Pin; -use crate::task::{Context, Poll}; - -/// A future that is immediately ready with a value. -/// -/// This `struct` is created by [`ready()`]. See its -/// documentation for more. -#[stable(feature = "future_readiness_fns", since = "1.48.0")] -#[derive(Debug, Clone)] -#[must_use = "futures do nothing unless you `.await` or poll them"] -pub struct Ready(Option); - -#[stable(feature = "future_readiness_fns", since = "1.48.0")] -impl Unpin for Ready {} - -#[stable(feature = "future_readiness_fns", since = "1.48.0")] -impl Future for Ready { - type Output = T; - - #[inline] - fn poll(mut self: Pin<&mut Self>, _cx: &mut Context<'_>) -> Poll { - Poll::Ready(self.0.take().expect("`Ready` polled after completion")) - } -} - -impl Ready { - /// Consumes the `Ready`, returning the wrapped value. - /// - /// # Panics - /// - /// Will panic if this [`Ready`] was already polled to completion. - /// - /// # Examples - /// - /// ``` - /// #![feature(ready_into_inner)] - /// use std::future; - /// - /// let a = future::ready(1); - /// assert_eq!(a.into_inner(), 1); - /// ``` - #[unstable(feature = "ready_into_inner", issue = "101196")] - #[must_use] - #[inline] - pub fn into_inner(self) -> T { - self.0.expect("Called `into_inner()` on `Ready` after completion") - } -} - -/// Creates a future that is immediately ready with a value. -/// -/// Futures created through this function are functionally similar to those -/// created through `async {}`. The main difference is that futures created -/// through this function are named and implement `Unpin`. -/// -/// # Examples -/// -/// ``` -/// use std::future; -/// -/// # async fn run() { -/// let a = future::ready(1); -/// assert_eq!(a.await, 1); -/// # } -/// ``` -#[stable(feature = "future_readiness_fns", since = "1.48.0")] -pub fn ready(t: T) -> Ready { - Ready(Some(t)) -} diff --git a/library/core/src/hash/mod.rs b/library/core/src/hash/mod.rs deleted file mode 100644 index 1c93a7b28fd35..0000000000000 --- a/library/core/src/hash/mod.rs +++ /dev/null @@ -1,985 +0,0 @@ -//! Generic hashing support. -//! -//! This module provides a generic way to compute the [hash] of a value. -//! Hashes are most commonly used with [`HashMap`] and [`HashSet`]. -//! -//! [hash]: https://en.wikipedia.org/wiki/Hash_function -//! [`HashMap`]: ../../std/collections/struct.HashMap.html -//! [`HashSet`]: ../../std/collections/struct.HashSet.html -//! -//! The simplest way to make a type hashable is to use `#[derive(Hash)]`: -//! -//! # Examples -//! -//! ```rust -//! use std::hash::{DefaultHasher, Hash, Hasher}; -//! -//! #[derive(Hash)] -//! struct Person { -//! id: u32, -//! name: String, -//! phone: u64, -//! } -//! -//! let person1 = Person { -//! id: 5, -//! name: "Janet".to_string(), -//! phone: 555_666_7777, -//! }; -//! let person2 = Person { -//! id: 5, -//! name: "Bob".to_string(), -//! phone: 555_666_7777, -//! }; -//! -//! assert!(calculate_hash(&person1) != calculate_hash(&person2)); -//! -//! fn calculate_hash(t: &T) -> u64 { -//! let mut s = DefaultHasher::new(); -//! t.hash(&mut s); -//! s.finish() -//! } -//! ``` -//! -//! If you need more control over how a value is hashed, you need to implement -//! the [`Hash`] trait: -//! -//! ```rust -//! use std::hash::{DefaultHasher, Hash, Hasher}; -//! -//! struct Person { -//! id: u32, -//! # #[allow(dead_code)] -//! name: String, -//! phone: u64, -//! } -//! -//! impl Hash for Person { -//! fn hash(&self, state: &mut H) { -//! self.id.hash(state); -//! self.phone.hash(state); -//! } -//! } -//! -//! let person1 = Person { -//! id: 5, -//! name: "Janet".to_string(), -//! phone: 555_666_7777, -//! }; -//! let person2 = Person { -//! id: 5, -//! name: "Bob".to_string(), -//! phone: 555_666_7777, -//! }; -//! -//! assert_eq!(calculate_hash(&person1), calculate_hash(&person2)); -//! -//! fn calculate_hash(t: &T) -> u64 { -//! let mut s = DefaultHasher::new(); -//! t.hash(&mut s); -//! s.finish() -//! } -//! ``` - -#![stable(feature = "rust1", since = "1.0.0")] - -use crate::fmt; -use crate::marker; - -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated)] -pub use self::sip::SipHasher; - -#[unstable(feature = "hashmap_internals", issue = "none")] -#[allow(deprecated)] -#[doc(hidden)] -pub use self::sip::SipHasher13; - -mod sip; - -/// A hashable type. -/// -/// Types implementing `Hash` are able to be [`hash`]ed with an instance of -/// [`Hasher`]. -/// -/// ## Implementing `Hash` -/// -/// You can derive `Hash` with `#[derive(Hash)]` if all fields implement `Hash`. -/// The resulting hash will be the combination of the values from calling -/// [`hash`] on each field. -/// -/// ``` -/// #[derive(Hash)] -/// struct Rustacean { -/// name: String, -/// country: String, -/// } -/// ``` -/// -/// If you need more control over how a value is hashed, you can of course -/// implement the `Hash` trait yourself: -/// -/// ``` -/// use std::hash::{Hash, Hasher}; -/// -/// struct Person { -/// id: u32, -/// name: String, -/// phone: u64, -/// } -/// -/// impl Hash for Person { -/// fn hash(&self, state: &mut H) { -/// self.id.hash(state); -/// self.phone.hash(state); -/// } -/// } -/// ``` -/// -/// ## `Hash` and `Eq` -/// -/// When implementing both `Hash` and [`Eq`], it is important that the following -/// property holds: -/// -/// ```text -/// k1 == k2 -> hash(k1) == hash(k2) -/// ``` -/// -/// In other words, if two keys are equal, their hashes must also be equal. -/// [`HashMap`] and [`HashSet`] both rely on this behavior. -/// -/// Thankfully, you won't need to worry about upholding this property when -/// deriving both [`Eq`] and `Hash` with `#[derive(PartialEq, Eq, Hash)]`. -/// -/// Violating this property is a logic error. The behavior resulting from a logic error is not -/// specified, but users of the trait must ensure that such logic errors do *not* result in -/// undefined behavior. This means that `unsafe` code **must not** rely on the correctness of these -/// methods. -/// -/// ## Prefix collisions -/// -/// Implementations of `hash` should ensure that the data they -/// pass to the `Hasher` are prefix-free. That is, -/// values which are not equal should cause two different sequences of values to be written, -/// and neither of the two sequences should be a prefix of the other. -/// -/// For example, the standard implementation of [`Hash` for `&str`][impl] passes an extra -/// `0xFF` byte to the `Hasher` so that the values `("ab", "c")` and `("a", -/// "bc")` hash differently. -/// -/// ## Portability -/// -/// Due to differences in endianness and type sizes, data fed by `Hash` to a `Hasher` -/// should not be considered portable across platforms. Additionally the data passed by most -/// standard library types should not be considered stable between compiler versions. -/// -/// This means tests shouldn't probe hard-coded hash values or data fed to a `Hasher` and -/// instead should check consistency with `Eq`. -/// -/// Serialization formats intended to be portable between platforms or compiler versions should -/// either avoid encoding hashes or only rely on `Hash` and `Hasher` implementations that -/// provide additional guarantees. -/// -/// [`HashMap`]: ../../std/collections/struct.HashMap.html -/// [`HashSet`]: ../../std/collections/struct.HashSet.html -/// [`hash`]: Hash::hash -/// [impl]: ../../std/primitive.str.html#impl-Hash-for-str -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_diagnostic_item = "Hash"] -pub trait Hash { - /// Feeds this value into the given [`Hasher`]. - /// - /// # Examples - /// - /// ``` - /// use std::hash::{DefaultHasher, Hash, Hasher}; - /// - /// let mut hasher = DefaultHasher::new(); - /// 7920.hash(&mut hasher); - /// println!("Hash is {:x}!", hasher.finish()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn hash(&self, state: &mut H); - - /// Feeds a slice of this type into the given [`Hasher`]. - /// - /// This method is meant as a convenience, but its implementation is - /// also explicitly left unspecified. It isn't guaranteed to be - /// equivalent to repeated calls of [`hash`] and implementations of - /// [`Hash`] should keep that in mind and call [`hash`] themselves - /// if the slice isn't treated as a whole unit in the [`PartialEq`] - /// implementation. - /// - /// For example, a [`VecDeque`] implementation might naïvely call - /// [`as_slices`] and then [`hash_slice`] on each slice, but this - /// is wrong since the two slices can change with a call to - /// [`make_contiguous`] without affecting the [`PartialEq`] - /// result. Since these slices aren't treated as singular - /// units, and instead part of a larger deque, this method cannot - /// be used. - /// - /// # Examples - /// - /// ``` - /// use std::hash::{DefaultHasher, Hash, Hasher}; - /// - /// let mut hasher = DefaultHasher::new(); - /// let numbers = [6, 28, 496, 8128]; - /// Hash::hash_slice(&numbers, &mut hasher); - /// println!("Hash is {:x}!", hasher.finish()); - /// ``` - /// - /// [`VecDeque`]: ../../std/collections/struct.VecDeque.html - /// [`as_slices`]: ../../std/collections/struct.VecDeque.html#method.as_slices - /// [`make_contiguous`]: ../../std/collections/struct.VecDeque.html#method.make_contiguous - /// [`hash`]: Hash::hash - /// [`hash_slice`]: Hash::hash_slice - #[stable(feature = "hash_slice", since = "1.3.0")] - fn hash_slice(data: &[Self], state: &mut H) - where - Self: Sized, - { - for piece in data { - piece.hash(state) - } - } -} - -// Separate module to reexport the macro `Hash` from prelude without the trait `Hash`. -pub(crate) mod macros { - /// Derive macro generating an impl of the trait `Hash`. - #[rustc_builtin_macro] - #[stable(feature = "builtin_macro_prelude", since = "1.38.0")] - #[allow_internal_unstable(core_intrinsics)] - pub macro Hash($item:item) { - /* compiler built-in */ - } -} -#[stable(feature = "builtin_macro_prelude", since = "1.38.0")] -#[doc(inline)] -pub use macros::Hash; - -/// A trait for hashing an arbitrary stream of bytes. -/// -/// Instances of `Hasher` usually represent state that is changed while hashing -/// data. -/// -/// `Hasher` provides a fairly basic interface for retrieving the generated hash -/// (with [`finish`]), and writing integers as well as slices of bytes into an -/// instance (with [`write`] and [`write_u8`] etc.). Most of the time, `Hasher` -/// instances are used in conjunction with the [`Hash`] trait. -/// -/// This trait provides no guarantees about how the various `write_*` methods are -/// defined and implementations of [`Hash`] should not assume that they work one -/// way or another. You cannot assume, for example, that a [`write_u32`] call is -/// equivalent to four calls of [`write_u8`]. Nor can you assume that adjacent -/// `write` calls are merged, so it's possible, for example, that -/// ``` -/// # fn foo(hasher: &mut impl std::hash::Hasher) { -/// hasher.write(&[1, 2]); -/// hasher.write(&[3, 4, 5, 6]); -/// # } -/// ``` -/// and -/// ``` -/// # fn foo(hasher: &mut impl std::hash::Hasher) { -/// hasher.write(&[1, 2, 3, 4]); -/// hasher.write(&[5, 6]); -/// # } -/// ``` -/// end up producing different hashes. -/// -/// Thus to produce the same hash value, [`Hash`] implementations must ensure -/// for equivalent items that exactly the same sequence of calls is made -- the -/// same methods with the same parameters in the same order. -/// -/// # Examples -/// -/// ``` -/// use std::hash::{DefaultHasher, Hasher}; -/// -/// let mut hasher = DefaultHasher::new(); -/// -/// hasher.write_u32(1989); -/// hasher.write_u8(11); -/// hasher.write_u8(9); -/// hasher.write(b"Huh?"); -/// -/// println!("Hash is {:x}!", hasher.finish()); -/// ``` -/// -/// [`finish`]: Hasher::finish -/// [`write`]: Hasher::write -/// [`write_u8`]: Hasher::write_u8 -/// [`write_u32`]: Hasher::write_u32 -#[stable(feature = "rust1", since = "1.0.0")] -pub trait Hasher { - /// Returns the hash value for the values written so far. - /// - /// Despite its name, the method does not reset the hasher’s internal - /// state. Additional [`write`]s will continue from the current value. - /// If you need to start a fresh hash value, you will have to create - /// a new hasher. - /// - /// # Examples - /// - /// ``` - /// use std::hash::{DefaultHasher, Hasher}; - /// - /// let mut hasher = DefaultHasher::new(); - /// hasher.write(b"Cool!"); - /// - /// println!("Hash is {:x}!", hasher.finish()); - /// ``` - /// - /// [`write`]: Hasher::write - #[stable(feature = "rust1", since = "1.0.0")] - fn finish(&self) -> u64; - - /// Writes some data into this `Hasher`. - /// - /// # Examples - /// - /// ``` - /// use std::hash::{DefaultHasher, Hasher}; - /// - /// let mut hasher = DefaultHasher::new(); - /// let data = [0x01, 0x23, 0x45, 0x67, 0x89, 0xab, 0xcd, 0xef]; - /// - /// hasher.write(&data); - /// - /// println!("Hash is {:x}!", hasher.finish()); - /// ``` - /// - /// # Note to Implementers - /// - /// You generally should not do length-prefixing as part of implementing - /// this method. It's up to the [`Hash`] implementation to call - /// [`Hasher::write_length_prefix`] before sequences that need it. - #[stable(feature = "rust1", since = "1.0.0")] - fn write(&mut self, bytes: &[u8]); - - /// Writes a single `u8` into this hasher. - #[inline] - #[stable(feature = "hasher_write", since = "1.3.0")] - fn write_u8(&mut self, i: u8) { - self.write(&[i]) - } - /// Writes a single `u16` into this hasher. - #[inline] - #[stable(feature = "hasher_write", since = "1.3.0")] - fn write_u16(&mut self, i: u16) { - self.write(&i.to_ne_bytes()) - } - /// Writes a single `u32` into this hasher. - #[inline] - #[stable(feature = "hasher_write", since = "1.3.0")] - fn write_u32(&mut self, i: u32) { - self.write(&i.to_ne_bytes()) - } - /// Writes a single `u64` into this hasher. - #[inline] - #[stable(feature = "hasher_write", since = "1.3.0")] - fn write_u64(&mut self, i: u64) { - self.write(&i.to_ne_bytes()) - } - /// Writes a single `u128` into this hasher. - #[inline] - #[stable(feature = "i128", since = "1.26.0")] - fn write_u128(&mut self, i: u128) { - self.write(&i.to_ne_bytes()) - } - /// Writes a single `usize` into this hasher. - #[inline] - #[stable(feature = "hasher_write", since = "1.3.0")] - fn write_usize(&mut self, i: usize) { - self.write(&i.to_ne_bytes()) - } - - /// Writes a single `i8` into this hasher. - #[inline] - #[stable(feature = "hasher_write", since = "1.3.0")] - fn write_i8(&mut self, i: i8) { - self.write_u8(i as u8) - } - /// Writes a single `i16` into this hasher. - #[inline] - #[stable(feature = "hasher_write", since = "1.3.0")] - fn write_i16(&mut self, i: i16) { - self.write_u16(i as u16) - } - /// Writes a single `i32` into this hasher. - #[inline] - #[stable(feature = "hasher_write", since = "1.3.0")] - fn write_i32(&mut self, i: i32) { - self.write_u32(i as u32) - } - /// Writes a single `i64` into this hasher. - #[inline] - #[stable(feature = "hasher_write", since = "1.3.0")] - fn write_i64(&mut self, i: i64) { - self.write_u64(i as u64) - } - /// Writes a single `i128` into this hasher. - #[inline] - #[stable(feature = "i128", since = "1.26.0")] - fn write_i128(&mut self, i: i128) { - self.write_u128(i as u128) - } - /// Writes a single `isize` into this hasher. - #[inline] - #[stable(feature = "hasher_write", since = "1.3.0")] - fn write_isize(&mut self, i: isize) { - self.write_usize(i as usize) - } - - /// Writes a length prefix into this hasher, as part of being prefix-free. - /// - /// If you're implementing [`Hash`] for a custom collection, call this before - /// writing its contents to this `Hasher`. That way - /// `(collection![1, 2, 3], collection![4, 5])` and - /// `(collection![1, 2], collection![3, 4, 5])` will provide different - /// sequences of values to the `Hasher` - /// - /// The `impl Hash for [T]` includes a call to this method, so if you're - /// hashing a slice (or array or vector) via its `Hash::hash` method, - /// you should **not** call this yourself. - /// - /// This method is only for providing domain separation. If you want to - /// hash a `usize` that represents part of the *data*, then it's important - /// that you pass it to [`Hasher::write_usize`] instead of to this method. - /// - /// # Examples - /// - /// ``` - /// #![feature(hasher_prefixfree_extras)] - /// # // Stubs to make the `impl` below pass the compiler - /// # #![allow(non_local_definitions)] - /// # struct MyCollection(Option); - /// # impl MyCollection { - /// # fn len(&self) -> usize { todo!() } - /// # } - /// # impl<'a, T> IntoIterator for &'a MyCollection { - /// # type Item = T; - /// # type IntoIter = std::iter::Empty; - /// # fn into_iter(self) -> Self::IntoIter { todo!() } - /// # } - /// - /// use std::hash::{Hash, Hasher}; - /// impl Hash for MyCollection { - /// fn hash(&self, state: &mut H) { - /// state.write_length_prefix(self.len()); - /// for elt in self { - /// elt.hash(state); - /// } - /// } - /// } - /// ``` - /// - /// # Note to Implementers - /// - /// If you've decided that your `Hasher` is willing to be susceptible to - /// Hash-DoS attacks, then you might consider skipping hashing some or all - /// of the `len` provided in the name of increased performance. - #[inline] - #[unstable(feature = "hasher_prefixfree_extras", issue = "96762")] - fn write_length_prefix(&mut self, len: usize) { - self.write_usize(len); - } - - /// Writes a single `str` into this hasher. - /// - /// If you're implementing [`Hash`], you generally do not need to call this, - /// as the `impl Hash for str` does, so you should prefer that instead. - /// - /// This includes the domain separator for prefix-freedom, so you should - /// **not** call `Self::write_length_prefix` before calling this. - /// - /// # Note to Implementers - /// - /// There are at least two reasonable default ways to implement this. - /// Which one will be the default is not yet decided, so for now - /// you probably want to override it specifically. - /// - /// ## The general answer - /// - /// It's always correct to implement this with a length prefix: - /// - /// ``` - /// # #![feature(hasher_prefixfree_extras)] - /// # struct Foo; - /// # impl std::hash::Hasher for Foo { - /// # fn finish(&self) -> u64 { unimplemented!() } - /// # fn write(&mut self, _bytes: &[u8]) { unimplemented!() } - /// fn write_str(&mut self, s: &str) { - /// self.write_length_prefix(s.len()); - /// self.write(s.as_bytes()); - /// } - /// # } - /// ``` - /// - /// And, if your `Hasher` works in `usize` chunks, this is likely a very - /// efficient way to do it, as anything more complicated may well end up - /// slower than just running the round with the length. - /// - /// ## If your `Hasher` works byte-wise - /// - /// One nice thing about `str` being UTF-8 is that the `b'\xFF'` byte - /// never happens. That means that you can append that to the byte stream - /// being hashed and maintain prefix-freedom: - /// - /// ``` - /// # #![feature(hasher_prefixfree_extras)] - /// # struct Foo; - /// # impl std::hash::Hasher for Foo { - /// # fn finish(&self) -> u64 { unimplemented!() } - /// # fn write(&mut self, _bytes: &[u8]) { unimplemented!() } - /// fn write_str(&mut self, s: &str) { - /// self.write(s.as_bytes()); - /// self.write_u8(0xff); - /// } - /// # } - /// ``` - /// - /// This does require that your implementation not add extra padding, and - /// thus generally requires that you maintain a buffer, running a round - /// only once that buffer is full (or `finish` is called). - /// - /// That's because if `write` pads data out to a fixed chunk size, it's - /// likely that it does it in such a way that `"a"` and `"a\x00"` would - /// end up hashing the same sequence of things, introducing conflicts. - #[inline] - #[unstable(feature = "hasher_prefixfree_extras", issue = "96762")] - fn write_str(&mut self, s: &str) { - self.write(s.as_bytes()); - self.write_u8(0xff); - } -} - -#[stable(feature = "indirect_hasher_impl", since = "1.22.0")] -impl Hasher for &mut H { - fn finish(&self) -> u64 { - (**self).finish() - } - fn write(&mut self, bytes: &[u8]) { - (**self).write(bytes) - } - fn write_u8(&mut self, i: u8) { - (**self).write_u8(i) - } - fn write_u16(&mut self, i: u16) { - (**self).write_u16(i) - } - fn write_u32(&mut self, i: u32) { - (**self).write_u32(i) - } - fn write_u64(&mut self, i: u64) { - (**self).write_u64(i) - } - fn write_u128(&mut self, i: u128) { - (**self).write_u128(i) - } - fn write_usize(&mut self, i: usize) { - (**self).write_usize(i) - } - fn write_i8(&mut self, i: i8) { - (**self).write_i8(i) - } - fn write_i16(&mut self, i: i16) { - (**self).write_i16(i) - } - fn write_i32(&mut self, i: i32) { - (**self).write_i32(i) - } - fn write_i64(&mut self, i: i64) { - (**self).write_i64(i) - } - fn write_i128(&mut self, i: i128) { - (**self).write_i128(i) - } - fn write_isize(&mut self, i: isize) { - (**self).write_isize(i) - } - fn write_length_prefix(&mut self, len: usize) { - (**self).write_length_prefix(len) - } - fn write_str(&mut self, s: &str) { - (**self).write_str(s) - } -} - -/// A trait for creating instances of [`Hasher`]. -/// -/// A `BuildHasher` is typically used (e.g., by [`HashMap`]) to create -/// [`Hasher`]s for each key such that they are hashed independently of one -/// another, since [`Hasher`]s contain state. -/// -/// For each instance of `BuildHasher`, the [`Hasher`]s created by -/// [`build_hasher`] should be identical. That is, if the same stream of bytes -/// is fed into each hasher, the same output will also be generated. -/// -/// # Examples -/// -/// ``` -/// use std::hash::{BuildHasher, Hasher, RandomState}; -/// -/// let s = RandomState::new(); -/// let mut hasher_1 = s.build_hasher(); -/// let mut hasher_2 = s.build_hasher(); -/// -/// hasher_1.write_u32(8128); -/// hasher_2.write_u32(8128); -/// -/// assert_eq!(hasher_1.finish(), hasher_2.finish()); -/// ``` -/// -/// [`build_hasher`]: BuildHasher::build_hasher -/// [`HashMap`]: ../../std/collections/struct.HashMap.html -#[stable(since = "1.7.0", feature = "build_hasher")] -pub trait BuildHasher { - /// Type of the hasher that will be created. - #[stable(since = "1.7.0", feature = "build_hasher")] - type Hasher: Hasher; - - /// Creates a new hasher. - /// - /// Each call to `build_hasher` on the same instance should produce identical - /// [`Hasher`]s. - /// - /// # Examples - /// - /// ``` - /// use std::hash::{BuildHasher, RandomState}; - /// - /// let s = RandomState::new(); - /// let new_s = s.build_hasher(); - /// ``` - #[stable(since = "1.7.0", feature = "build_hasher")] - fn build_hasher(&self) -> Self::Hasher; - - /// Calculates the hash of a single value. - /// - /// This is intended as a convenience for code which *consumes* hashes, such - /// as the implementation of a hash table or in unit tests that check - /// whether a custom [`Hash`] implementation behaves as expected. - /// - /// This must not be used in any code which *creates* hashes, such as in an - /// implementation of [`Hash`]. The way to create a combined hash of - /// multiple values is to call [`Hash::hash`] multiple times using the same - /// [`Hasher`], not to call this method repeatedly and combine the results. - /// - /// # Example - /// - /// ``` - /// use std::cmp::{max, min}; - /// use std::hash::{BuildHasher, Hash, Hasher}; - /// struct OrderAmbivalentPair(T, T); - /// impl Hash for OrderAmbivalentPair { - /// fn hash(&self, hasher: &mut H) { - /// min(&self.0, &self.1).hash(hasher); - /// max(&self.0, &self.1).hash(hasher); - /// } - /// } - /// - /// // Then later, in a `#[test]` for the type... - /// let bh = std::hash::RandomState::new(); - /// assert_eq!( - /// bh.hash_one(OrderAmbivalentPair(1, 2)), - /// bh.hash_one(OrderAmbivalentPair(2, 1)) - /// ); - /// assert_eq!( - /// bh.hash_one(OrderAmbivalentPair(10, 2)), - /// bh.hash_one(&OrderAmbivalentPair(2, 10)) - /// ); - /// ``` - #[stable(feature = "build_hasher_simple_hash_one", since = "1.71.0")] - fn hash_one(&self, x: T) -> u64 - where - Self: Sized, - Self::Hasher: Hasher, - { - let mut hasher = self.build_hasher(); - x.hash(&mut hasher); - hasher.finish() - } -} - -/// Used to create a default [`BuildHasher`] instance for types that implement -/// [`Hasher`] and [`Default`]. -/// -/// `BuildHasherDefault` can be used when a type `H` implements [`Hasher`] and -/// [`Default`], and you need a corresponding [`BuildHasher`] instance, but none is -/// defined. -/// -/// Any `BuildHasherDefault` is [zero-sized]. It can be created with -/// [`default`][method.default]. When using `BuildHasherDefault` with [`HashMap`] or -/// [`HashSet`], this doesn't need to be done, since they implement appropriate -/// [`Default`] instances themselves. -/// -/// # Examples -/// -/// Using `BuildHasherDefault` to specify a custom [`BuildHasher`] for -/// [`HashMap`]: -/// -/// ``` -/// use std::collections::HashMap; -/// use std::hash::{BuildHasherDefault, Hasher}; -/// -/// #[derive(Default)] -/// struct MyHasher; -/// -/// impl Hasher for MyHasher { -/// fn write(&mut self, bytes: &[u8]) { -/// // Your hashing algorithm goes here! -/// unimplemented!() -/// } -/// -/// fn finish(&self) -> u64 { -/// // Your hashing algorithm goes here! -/// unimplemented!() -/// } -/// } -/// -/// type MyBuildHasher = BuildHasherDefault; -/// -/// let hash_map = HashMap::::default(); -/// ``` -/// -/// [method.default]: BuildHasherDefault::default -/// [`HashMap`]: ../../std/collections/struct.HashMap.html -/// [`HashSet`]: ../../std/collections/struct.HashSet.html -/// [zero-sized]: https://doc.rust-lang.org/nomicon/exotic-sizes.html#zero-sized-types-zsts -#[stable(since = "1.7.0", feature = "build_hasher")] -pub struct BuildHasherDefault(marker::PhantomData H>); - -impl BuildHasherDefault { - /// Creates a new BuildHasherDefault for Hasher `H`. - #[unstable( - feature = "build_hasher_default_const_new", - issue = "123197", - reason = "recently added" - )] - pub const fn new() -> Self { - BuildHasherDefault(marker::PhantomData) - } -} - -#[stable(since = "1.9.0", feature = "core_impl_debug")] -impl fmt::Debug for BuildHasherDefault { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("BuildHasherDefault").finish() - } -} - -#[stable(since = "1.7.0", feature = "build_hasher")] -impl BuildHasher for BuildHasherDefault { - type Hasher = H; - - fn build_hasher(&self) -> H { - H::default() - } -} - -#[stable(since = "1.7.0", feature = "build_hasher")] -impl Clone for BuildHasherDefault { - fn clone(&self) -> BuildHasherDefault { - BuildHasherDefault(marker::PhantomData) - } -} - -#[stable(since = "1.7.0", feature = "build_hasher")] -impl Default for BuildHasherDefault { - fn default() -> BuildHasherDefault { - Self::new() - } -} - -#[stable(since = "1.29.0", feature = "build_hasher_eq")] -impl PartialEq for BuildHasherDefault { - fn eq(&self, _other: &BuildHasherDefault) -> bool { - true - } -} - -#[stable(since = "1.29.0", feature = "build_hasher_eq")] -impl Eq for BuildHasherDefault {} - -mod impls { - use crate::mem; - use crate::slice; - - use super::*; - - macro_rules! impl_write { - ($(($ty:ident, $meth:ident),)*) => {$( - #[stable(feature = "rust1", since = "1.0.0")] - impl Hash for $ty { - #[inline] - fn hash(&self, state: &mut H) { - state.$meth(*self) - } - - #[inline] - fn hash_slice(data: &[$ty], state: &mut H) { - let newlen = mem::size_of_val(data); - let ptr = data.as_ptr() as *const u8; - // SAFETY: `ptr` is valid and aligned, as this macro is only used - // for numeric primitives which have no padding. The new slice only - // spans across `data` and is never mutated, and its total size is the - // same as the original `data` so it can't be over `isize::MAX`. - state.write(unsafe { slice::from_raw_parts(ptr, newlen) }) - } - } - )*} - } - - impl_write! { - (u8, write_u8), - (u16, write_u16), - (u32, write_u32), - (u64, write_u64), - (usize, write_usize), - (i8, write_i8), - (i16, write_i16), - (i32, write_i32), - (i64, write_i64), - (isize, write_isize), - (u128, write_u128), - (i128, write_i128), - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl Hash for bool { - #[inline] - fn hash(&self, state: &mut H) { - state.write_u8(*self as u8) - } - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl Hash for char { - #[inline] - fn hash(&self, state: &mut H) { - state.write_u32(*self as u32) - } - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl Hash for str { - #[inline] - fn hash(&self, state: &mut H) { - state.write_str(self); - } - } - - #[stable(feature = "never_hash", since = "1.29.0")] - impl Hash for ! { - #[inline] - fn hash(&self, _: &mut H) { - *self - } - } - - macro_rules! impl_hash_tuple { - () => ( - #[stable(feature = "rust1", since = "1.0.0")] - impl Hash for () { - #[inline] - fn hash(&self, _state: &mut H) {} - } - ); - - ( $($name:ident)+) => ( - maybe_tuple_doc! { - $($name)+ @ - #[stable(feature = "rust1", since = "1.0.0")] - impl<$($name: Hash),+> Hash for ($($name,)+) where last_type!($($name,)+): ?Sized { - #[allow(non_snake_case)] - #[inline] - fn hash(&self, state: &mut S) { - let ($(ref $name,)+) = *self; - $($name.hash(state);)+ - } - } - } - ); - } - - macro_rules! maybe_tuple_doc { - ($a:ident @ #[$meta:meta] $item:item) => { - #[doc(fake_variadic)] - #[doc = "This trait is implemented for tuples up to twelve items long."] - #[$meta] - $item - }; - ($a:ident $($rest_a:ident)+ @ #[$meta:meta] $item:item) => { - #[doc(hidden)] - #[$meta] - $item - }; - } - - macro_rules! last_type { - ($a:ident,) => { $a }; - ($a:ident, $($rest_a:ident,)+) => { last_type!($($rest_a,)+) }; - } - - impl_hash_tuple! {} - impl_hash_tuple! { T } - impl_hash_tuple! { T B } - impl_hash_tuple! { T B C } - impl_hash_tuple! { T B C D } - impl_hash_tuple! { T B C D E } - impl_hash_tuple! { T B C D E F } - impl_hash_tuple! { T B C D E F G } - impl_hash_tuple! { T B C D E F G H } - impl_hash_tuple! { T B C D E F G H I } - impl_hash_tuple! { T B C D E F G H I J } - impl_hash_tuple! { T B C D E F G H I J K } - impl_hash_tuple! { T B C D E F G H I J K L } - - #[stable(feature = "rust1", since = "1.0.0")] - impl Hash for [T] { - #[inline] - fn hash(&self, state: &mut H) { - state.write_length_prefix(self.len()); - Hash::hash_slice(self, state) - } - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl Hash for &T { - #[inline] - fn hash(&self, state: &mut H) { - (**self).hash(state); - } - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl Hash for &mut T { - #[inline] - fn hash(&self, state: &mut H) { - (**self).hash(state); - } - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl Hash for *const T { - #[inline] - fn hash(&self, state: &mut H) { - let (address, metadata) = self.to_raw_parts(); - state.write_usize(address.addr()); - metadata.hash(state); - } - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl Hash for *mut T { - #[inline] - fn hash(&self, state: &mut H) { - let (address, metadata) = self.to_raw_parts(); - state.write_usize(address.addr()); - metadata.hash(state); - } - } -} diff --git a/library/core/src/hash/sip.rs b/library/core/src/hash/sip.rs deleted file mode 100644 index 78a232faaf88c..0000000000000 --- a/library/core/src/hash/sip.rs +++ /dev/null @@ -1,394 +0,0 @@ -//! An implementation of SipHash. - -#![allow(deprecated)] // the types in this module are deprecated - -use crate::cmp; -use crate::marker::PhantomData; -use crate::mem; -use crate::ptr; - -/// An implementation of SipHash 1-3. -/// -/// This is currently the default hashing function used by standard library -/// (e.g., `collections::HashMap` uses it by default). -/// -/// See: -#[unstable(feature = "hashmap_internals", issue = "none")] -#[deprecated(since = "1.13.0", note = "use `std::hash::DefaultHasher` instead")] -#[derive(Debug, Clone, Default)] -#[doc(hidden)] -pub struct SipHasher13 { - hasher: Hasher, -} - -/// An implementation of SipHash 2-4. -/// -/// See: -#[unstable(feature = "hashmap_internals", issue = "none")] -#[deprecated(since = "1.13.0", note = "use `std::hash::DefaultHasher` instead")] -#[derive(Debug, Clone, Default)] -struct SipHasher24 { - hasher: Hasher, -} - -/// An implementation of SipHash 2-4. -/// -/// See: -/// -/// SipHash is a general-purpose hashing function: it runs at a good -/// speed (competitive with Spooky and City) and permits strong _keyed_ -/// hashing. This lets you key your hash tables from a strong RNG, such as -/// [`rand::os::OsRng`](https://docs.rs/rand/latest/rand/rngs/struct.OsRng.html). -/// -/// Although the SipHash algorithm is considered to be generally strong, -/// it is not intended for cryptographic purposes. As such, all -/// cryptographic uses of this implementation are _strongly discouraged_. -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "1.13.0", note = "use `std::hash::DefaultHasher` instead")] -#[derive(Debug, Clone, Default)] -pub struct SipHasher(SipHasher24); - -#[derive(Debug)] -struct Hasher { - k0: u64, - k1: u64, - length: usize, // how many bytes we've processed - state: State, // hash State - tail: u64, // unprocessed bytes le - ntail: usize, // how many bytes in tail are valid - _marker: PhantomData, -} - -#[derive(Debug, Clone, Copy)] -#[repr(C)] -struct State { - // v0, v2 and v1, v3 show up in pairs in the algorithm, - // and simd implementations of SipHash will use vectors - // of v02 and v13. By placing them in this order in the struct, - // the compiler can pick up on just a few simd optimizations by itself. - v0: u64, - v2: u64, - v1: u64, - v3: u64, -} - -macro_rules! compress { - ($state:expr) => {{ compress!($state.v0, $state.v1, $state.v2, $state.v3) }}; - ($v0:expr, $v1:expr, $v2:expr, $v3:expr) => {{ - $v0 = $v0.wrapping_add($v1); - $v1 = $v1.rotate_left(13); - $v1 ^= $v0; - $v0 = $v0.rotate_left(32); - $v2 = $v2.wrapping_add($v3); - $v3 = $v3.rotate_left(16); - $v3 ^= $v2; - $v0 = $v0.wrapping_add($v3); - $v3 = $v3.rotate_left(21); - $v3 ^= $v0; - $v2 = $v2.wrapping_add($v1); - $v1 = $v1.rotate_left(17); - $v1 ^= $v2; - $v2 = $v2.rotate_left(32); - }}; -} - -/// Loads an integer of the desired type from a byte stream, in LE order. Uses -/// `copy_nonoverlapping` to let the compiler generate the most efficient way -/// to load it from a possibly unaligned address. -/// -/// Safety: this performs unchecked indexing of `$buf` at -/// `$i..$i+size_of::<$int_ty>()`, so that must be in-bounds. -macro_rules! load_int_le { - ($buf:expr, $i:expr, $int_ty:ident) => {{ - debug_assert!($i + mem::size_of::<$int_ty>() <= $buf.len()); - let mut data = 0 as $int_ty; - ptr::copy_nonoverlapping( - $buf.as_ptr().add($i), - &mut data as *mut _ as *mut u8, - mem::size_of::<$int_ty>(), - ); - data.to_le() - }}; -} - -/// Loads a u64 using up to 7 bytes of a byte slice. It looks clumsy but the -/// `copy_nonoverlapping` calls that occur (via `load_int_le!`) all have fixed -/// sizes and avoid calling `memcpy`, which is good for speed. -/// -/// Safety: this performs unchecked indexing of `buf` at `start..start+len`, so -/// that must be in-bounds. -#[inline] -unsafe fn u8to64_le(buf: &[u8], start: usize, len: usize) -> u64 { - debug_assert!(len < 8); - let mut i = 0; // current byte index (from LSB) in the output u64 - let mut out = 0; - if i + 3 < len { - // SAFETY: `i` cannot be greater than `len`, and the caller must guarantee - // that the index start..start+len is in bounds. - out = unsafe { load_int_le!(buf, start + i, u32) } as u64; - i += 4; - } - if i + 1 < len { - // SAFETY: same as above. - out |= (unsafe { load_int_le!(buf, start + i, u16) } as u64) << (i * 8); - i += 2 - } - if i < len { - // SAFETY: same as above. - out |= (unsafe { *buf.get_unchecked(start + i) } as u64) << (i * 8); - i += 1; - } - //FIXME(fee1-dead): use debug_assert_eq - debug_assert!(i == len); - out -} - -impl SipHasher { - /// Creates a new `SipHasher` with the two initial keys set to 0. - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[deprecated(since = "1.13.0", note = "use `std::hash::DefaultHasher` instead")] - #[rustc_const_unstable(feature = "const_hash", issue = "104061")] - #[must_use] - pub const fn new() -> SipHasher { - SipHasher::new_with_keys(0, 0) - } - - /// Creates a `SipHasher` that is keyed off the provided keys. - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[deprecated(since = "1.13.0", note = "use `std::hash::DefaultHasher` instead")] - #[rustc_const_unstable(feature = "const_hash", issue = "104061")] - #[must_use] - pub const fn new_with_keys(key0: u64, key1: u64) -> SipHasher { - SipHasher(SipHasher24 { hasher: Hasher::new_with_keys(key0, key1) }) - } -} - -impl SipHasher13 { - /// Creates a new `SipHasher13` with the two initial keys set to 0. - #[inline] - #[unstable(feature = "hashmap_internals", issue = "none")] - #[deprecated(since = "1.13.0", note = "use `std::hash::DefaultHasher` instead")] - #[rustc_const_unstable(feature = "const_hash", issue = "104061")] - pub const fn new() -> SipHasher13 { - SipHasher13::new_with_keys(0, 0) - } - - /// Creates a `SipHasher13` that is keyed off the provided keys. - #[inline] - #[unstable(feature = "hashmap_internals", issue = "none")] - #[deprecated(since = "1.13.0", note = "use `std::hash::DefaultHasher` instead")] - #[rustc_const_unstable(feature = "const_hash", issue = "104061")] - pub const fn new_with_keys(key0: u64, key1: u64) -> SipHasher13 { - SipHasher13 { hasher: Hasher::new_with_keys(key0, key1) } - } -} - -impl Hasher { - #[inline] - const fn new_with_keys(key0: u64, key1: u64) -> Hasher { - let mut state = Hasher { - k0: key0, - k1: key1, - length: 0, - state: State { v0: 0, v1: 0, v2: 0, v3: 0 }, - tail: 0, - ntail: 0, - _marker: PhantomData, - }; - state.reset(); - state - } - - #[inline] - const fn reset(&mut self) { - self.length = 0; - self.state.v0 = self.k0 ^ 0x736f6d6570736575; - self.state.v1 = self.k1 ^ 0x646f72616e646f6d; - self.state.v2 = self.k0 ^ 0x6c7967656e657261; - self.state.v3 = self.k1 ^ 0x7465646279746573; - self.ntail = 0; - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl super::Hasher for SipHasher { - #[inline] - fn write(&mut self, msg: &[u8]) { - self.0.hasher.write(msg) - } - - #[inline] - fn write_str(&mut self, s: &str) { - self.0.hasher.write_str(s); - } - - #[inline] - fn finish(&self) -> u64 { - self.0.hasher.finish() - } -} - -#[unstable(feature = "hashmap_internals", issue = "none")] -impl super::Hasher for SipHasher13 { - #[inline] - fn write(&mut self, msg: &[u8]) { - self.hasher.write(msg) - } - - #[inline] - fn write_str(&mut self, s: &str) { - self.hasher.write_str(s); - } - - #[inline] - fn finish(&self) -> u64 { - self.hasher.finish() - } -} - -impl super::Hasher for Hasher { - // Note: no integer hashing methods (`write_u*`, `write_i*`) are defined - // for this type. We could add them, copy the `short_write` implementation - // in librustc_data_structures/sip128.rs, and add `write_u*`/`write_i*` - // methods to `SipHasher`, `SipHasher13`, and `DefaultHasher`. This would - // greatly speed up integer hashing by those hashers, at the cost of - // slightly slowing down compile speeds on some benchmarks. See #69152 for - // details. - #[inline] - fn write(&mut self, msg: &[u8]) { - let length = msg.len(); - self.length += length; - - let mut needed = 0; - - if self.ntail != 0 { - needed = 8 - self.ntail; - // SAFETY: `cmp::min(length, needed)` is guaranteed to not be over `length` - self.tail |= unsafe { u8to64_le(msg, 0, cmp::min(length, needed)) } << (8 * self.ntail); - if length < needed { - self.ntail += length; - return; - } else { - self.state.v3 ^= self.tail; - S::c_rounds(&mut self.state); - self.state.v0 ^= self.tail; - self.ntail = 0; - } - } - - // Buffered tail is now flushed, process new input. - let len = length - needed; - let left = len & 0x7; // len % 8 - - let mut i = needed; - while i < len - left { - // SAFETY: because `len - left` is the biggest multiple of 8 under - // `len`, and because `i` starts at `needed` where `len` is `length - needed`, - // `i + 8` is guaranteed to be less than or equal to `length`. - let mi = unsafe { load_int_le!(msg, i, u64) }; - - self.state.v3 ^= mi; - S::c_rounds(&mut self.state); - self.state.v0 ^= mi; - - i += 8; - } - - // SAFETY: `i` is now `needed + len.div_euclid(8) * 8`, - // so `i + left` = `needed + len` = `length`, which is by - // definition equal to `msg.len()`. - self.tail = unsafe { u8to64_le(msg, i, left) }; - self.ntail = left; - } - - #[inline] - fn write_str(&mut self, s: &str) { - // This hasher works byte-wise, and `0xFF` cannot show up in a `str`, - // so just hashing the one extra byte is enough to be prefix-free. - self.write(s.as_bytes()); - self.write_u8(0xFF); - } - - #[inline] - fn finish(&self) -> u64 { - let mut state = self.state; - - let b: u64 = ((self.length as u64 & 0xff) << 56) | self.tail; - - state.v3 ^= b; - S::c_rounds(&mut state); - state.v0 ^= b; - - state.v2 ^= 0xff; - S::d_rounds(&mut state); - - state.v0 ^ state.v1 ^ state.v2 ^ state.v3 - } -} - -impl Clone for Hasher { - #[inline] - fn clone(&self) -> Hasher { - Hasher { - k0: self.k0, - k1: self.k1, - length: self.length, - state: self.state, - tail: self.tail, - ntail: self.ntail, - _marker: self._marker, - } - } -} - -impl Default for Hasher { - /// Creates a `Hasher` with the two initial keys set to 0. - #[inline] - fn default() -> Hasher { - Hasher::new_with_keys(0, 0) - } -} - -#[doc(hidden)] -trait Sip { - fn c_rounds(_: &mut State); - fn d_rounds(_: &mut State); -} - -#[derive(Debug, Clone, Default)] -struct Sip13Rounds; - -impl Sip for Sip13Rounds { - #[inline] - fn c_rounds(state: &mut State) { - compress!(state); - } - - #[inline] - fn d_rounds(state: &mut State) { - compress!(state); - compress!(state); - compress!(state); - } -} - -#[derive(Debug, Clone, Default)] -struct Sip24Rounds; - -impl Sip for Sip24Rounds { - #[inline] - fn c_rounds(state: &mut State) { - compress!(state); - compress!(state); - } - - #[inline] - fn d_rounds(state: &mut State) { - compress!(state); - compress!(state); - compress!(state); - compress!(state); - } -} diff --git a/library/core/src/hint.rs b/library/core/src/hint.rs deleted file mode 100644 index 6e2d88c6b8337..0000000000000 --- a/library/core/src/hint.rs +++ /dev/null @@ -1,463 +0,0 @@ -#![stable(feature = "core_hint", since = "1.27.0")] - -//! Hints to compiler that affects how code should be emitted or optimized. -//! Hints may be compile time or runtime. - -use crate::intrinsics; -use crate::ub_checks; - -/// Informs the compiler that the site which is calling this function is not -/// reachable, possibly enabling further optimizations. -/// -/// # Safety -/// -/// Reaching this function is *Undefined Behavior*. -/// -/// As the compiler assumes that all forms of Undefined Behavior can never -/// happen, it will eliminate all branches in the surrounding code that it can -/// determine will invariably lead to a call to `unreachable_unchecked()`. -/// -/// If the assumptions embedded in using this function turn out to be wrong - -/// that is, if the site which is calling `unreachable_unchecked()` is actually -/// reachable at runtime - the compiler may have generated nonsensical machine -/// instructions for this situation, including in seemingly unrelated code, -/// causing difficult-to-debug problems. -/// -/// Use this function sparingly. Consider using the [`unreachable!`] macro, -/// which may prevent some optimizations but will safely panic in case it is -/// actually reached at runtime. Benchmark your code to find out if using -/// `unreachable_unchecked()` comes with a performance benefit. -/// -/// # Examples -/// -/// `unreachable_unchecked()` can be used in situations where the compiler -/// can't prove invariants that were previously established. Such situations -/// have a higher chance of occurring if those invariants are upheld by -/// external code that the compiler can't analyze. -/// ``` -/// fn prepare_inputs(divisors: &mut Vec) { -/// // Note to future-self when making changes: The invariant established -/// // here is NOT checked in `do_computation()`; if this changes, you HAVE -/// // to change `do_computation()`. -/// divisors.retain(|divisor| *divisor != 0) -/// } -/// -/// /// # Safety -/// /// All elements of `divisor` must be non-zero. -/// unsafe fn do_computation(i: u32, divisors: &[u32]) -> u32 { -/// divisors.iter().fold(i, |acc, divisor| { -/// // Convince the compiler that a division by zero can't happen here -/// // and a check is not needed below. -/// if *divisor == 0 { -/// // Safety: `divisor` can't be zero because of `prepare_inputs`, -/// // but the compiler does not know about this. We *promise* -/// // that we always call `prepare_inputs`. -/// std::hint::unreachable_unchecked() -/// } -/// // The compiler would normally introduce a check here that prevents -/// // a division by zero. However, if `divisor` was zero, the branch -/// // above would reach what we explicitly marked as unreachable. -/// // The compiler concludes that `divisor` can't be zero at this point -/// // and removes the - now proven useless - check. -/// acc / divisor -/// }) -/// } -/// -/// let mut divisors = vec![2, 0, 4]; -/// prepare_inputs(&mut divisors); -/// let result = unsafe { -/// // Safety: prepare_inputs() guarantees that divisors is non-zero -/// do_computation(100, &divisors) -/// }; -/// assert_eq!(result, 12); -/// -/// ``` -/// -/// While using `unreachable_unchecked()` is perfectly sound in the following -/// example, as the compiler is able to prove that a division by zero is not -/// possible, benchmarking reveals that `unreachable_unchecked()` provides -/// no benefit over using [`unreachable!`], while the latter does not introduce -/// the possibility of Undefined Behavior. -/// -/// ``` -/// fn div_1(a: u32, b: u32) -> u32 { -/// use std::hint::unreachable_unchecked; -/// -/// // `b.saturating_add(1)` is always positive (not zero), -/// // hence `checked_div` will never return `None`. -/// // Therefore, the else branch is unreachable. -/// a.checked_div(b.saturating_add(1)) -/// .unwrap_or_else(|| unsafe { unreachable_unchecked() }) -/// } -/// -/// assert_eq!(div_1(7, 0), 7); -/// assert_eq!(div_1(9, 1), 4); -/// assert_eq!(div_1(11, u32::MAX), 0); -/// ``` -#[inline] -#[stable(feature = "unreachable", since = "1.27.0")] -#[rustc_const_stable(feature = "const_unreachable_unchecked", since = "1.57.0")] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -pub const unsafe fn unreachable_unchecked() -> ! { - ub_checks::assert_unsafe_precondition!( - check_language_ub, - "hint::unreachable_unchecked must never be reached", - () => false - ); - // SAFETY: the safety contract for `intrinsics::unreachable` must - // be upheld by the caller. - unsafe { intrinsics::unreachable() } -} - -/// Makes a *soundness* promise to the compiler that `cond` holds. -/// -/// This may allow the optimizer to simplify things, -/// but it might also make the generated code slower. -/// Either way, calling it will most likely make compilation take longer. -/// -/// This is a situational tool for micro-optimization, and is allowed to do nothing. -/// Any use should come with a repeatable benchmark to show the value -/// and allow removing it later should the optimizer get smarter and no longer need it. -/// -/// The more complicated the condition the less likely this is to be fruitful. -/// For example, `assert_unchecked(foo.is_sorted())` is a complex enough value -/// that the compiler is unlikely to be able to take advantage of it. -/// -/// There's also no need to `assert_unchecked` basic properties of things. For -/// example, the compiler already knows the range of `count_ones`, so there's no -/// benefit to `let n = u32::count_ones(x); assert_unchecked(n <= u32::BITS);`. -/// -/// If ever you're tempted to write `assert_unchecked(false)`, then you're -/// actually looking for [`unreachable_unchecked()`]. -/// -/// You may know this from other places -/// as [`llvm.assume`](https://llvm.org/docs/LangRef.html#llvm-assume-intrinsic) -/// or [`__builtin_assume`](https://clang.llvm.org/docs/LanguageExtensions.html#builtin-assume). -/// -/// This promotes a correctness requirement to a soundness requirement. -/// Don't do that without very good reason. -/// -/// # Safety -/// -/// `cond` must be `true`. It's immediate UB to call this with `false`. -/// -#[inline(always)] -#[doc(alias = "assume")] -#[track_caller] -#[unstable(feature = "hint_assert_unchecked", issue = "119131")] -#[rustc_const_unstable(feature = "const_hint_assert_unchecked", issue = "119131")] -pub const unsafe fn assert_unchecked(cond: bool) { - // SAFETY: The caller promised `cond` is true. - unsafe { - ub_checks::assert_unsafe_precondition!( - check_language_ub, - "hint::assert_unchecked must never be called when the condition is false", - (cond: bool = cond) => cond, - ); - crate::intrinsics::assume(cond); - } -} - -/// Emits a machine instruction to signal the processor that it is running in -/// a busy-wait spin-loop ("spin lock"). -/// -/// Upon receiving the spin-loop signal the processor can optimize its behavior by, -/// for example, saving power or switching hyper-threads. -/// -/// This function is different from [`thread::yield_now`] which directly -/// yields to the system's scheduler, whereas `spin_loop` does not interact -/// with the operating system. -/// -/// A common use case for `spin_loop` is implementing bounded optimistic -/// spinning in a CAS loop in synchronization primitives. To avoid problems -/// like priority inversion, it is strongly recommended that the spin loop is -/// terminated after a finite amount of iterations and an appropriate blocking -/// syscall is made. -/// -/// **Note**: On platforms that do not support receiving spin-loop hints this -/// function does not do anything at all. -/// -/// # Examples -/// -/// ``` -/// use std::sync::atomic::{AtomicBool, Ordering}; -/// use std::sync::Arc; -/// use std::{hint, thread}; -/// -/// // A shared atomic value that threads will use to coordinate -/// let live = Arc::new(AtomicBool::new(false)); -/// -/// // In a background thread we'll eventually set the value -/// let bg_work = { -/// let live = live.clone(); -/// thread::spawn(move || { -/// // Do some work, then make the value live -/// do_some_work(); -/// live.store(true, Ordering::Release); -/// }) -/// }; -/// -/// // Back on our current thread, we wait for the value to be set -/// while !live.load(Ordering::Acquire) { -/// // The spin loop is a hint to the CPU that we're waiting, but probably -/// // not for very long -/// hint::spin_loop(); -/// } -/// -/// // The value is now set -/// # fn do_some_work() {} -/// do_some_work(); -/// bg_work.join()?; -/// # Ok::<(), Box>(()) -/// ``` -/// -/// [`thread::yield_now`]: ../../std/thread/fn.yield_now.html -#[inline(always)] -#[stable(feature = "renamed_spin_loop", since = "1.49.0")] -pub fn spin_loop() { - #[cfg(target_arch = "x86")] - { - // SAFETY: the `cfg` attr ensures that we only execute this on x86 targets. - unsafe { crate::arch::x86::_mm_pause() }; - } - - #[cfg(target_arch = "x86_64")] - { - // SAFETY: the `cfg` attr ensures that we only execute this on x86_64 targets. - unsafe { crate::arch::x86_64::_mm_pause() }; - } - - #[cfg(target_arch = "riscv32")] - { - crate::arch::riscv32::pause(); - } - - #[cfg(target_arch = "riscv64")] - { - crate::arch::riscv64::pause(); - } - - #[cfg(any(target_arch = "aarch64", target_arch = "arm64ec"))] - { - // SAFETY: the `cfg` attr ensures that we only execute this on aarch64 targets. - unsafe { crate::arch::aarch64::__isb(crate::arch::aarch64::SY) }; - } - - #[cfg(all(target_arch = "arm", target_feature = "v6"))] - { - // SAFETY: the `cfg` attr ensures that we only execute this on arm targets - // with support for the v6 feature. - unsafe { crate::arch::arm::__yield() }; - } -} - -/// An identity function that *__hints__* to the compiler to be maximally pessimistic about what -/// `black_box` could do. -/// -/// Unlike [`std::convert::identity`], a Rust compiler is encouraged to assume that `black_box` can -/// use `dummy` in any possible valid way that Rust code is allowed to without introducing undefined -/// behavior in the calling code. This property makes `black_box` useful for writing code in which -/// certain optimizations are not desired, such as benchmarks. -/// -/// Note however, that `black_box` is only (and can only be) provided on a "best-effort" basis. The -/// extent to which it can block optimisations may vary depending upon the platform and code-gen -/// backend used. Programs cannot rely on `black_box` for *correctness*, beyond it behaving as the -/// identity function. As such, it **must not be relied upon to control critical program behavior.** -/// This _immediately_ precludes any direct use of this function for cryptographic or security -/// purposes. -/// -/// [`std::convert::identity`]: crate::convert::identity -/// -/// # When is this useful? -/// -/// While not suitable in those mission-critical cases, `black_box`'s functionality can generally be -/// relied upon for benchmarking, and should be used there. It will try to ensure that the -/// compiler doesn't optimize away part of the intended test code based on context. For -/// example: -/// -/// ``` -/// fn contains(haystack: &[&str], needle: &str) -> bool { -/// haystack.iter().any(|x| x == &needle) -/// } -/// -/// pub fn benchmark() { -/// let haystack = vec!["abc", "def", "ghi", "jkl", "mno"]; -/// let needle = "ghi"; -/// for _ in 0..10 { -/// contains(&haystack, needle); -/// } -/// } -/// ``` -/// -/// The compiler could theoretically make optimizations like the following: -/// -/// - The `needle` and `haystack` do not change, move the call to `contains` outside the loop and -/// delete the loop -/// - Inline `contains` -/// - `needle` and `haystack` have values known at compile time, `contains` is always true. Remove -/// the call and replace with `true` -/// - Nothing is done with the result of `contains`: delete this function call entirely -/// - `benchmark` now has no purpose: delete this function -/// -/// It is not likely that all of the above happens, but the compiler is definitely able to make some -/// optimizations that could result in a very inaccurate benchmark. This is where `black_box` comes -/// in: -/// -/// ``` -/// use std::hint::black_box; -/// -/// // Same `contains` function -/// fn contains(haystack: &[&str], needle: &str) -> bool { -/// haystack.iter().any(|x| x == &needle) -/// } -/// -/// pub fn benchmark() { -/// let haystack = vec!["abc", "def", "ghi", "jkl", "mno"]; -/// let needle = "ghi"; -/// for _ in 0..10 { -/// // Adjust our benchmark loop contents -/// black_box(contains(black_box(&haystack), black_box(needle))); -/// } -/// } -/// ``` -/// -/// This essentially tells the compiler to block optimizations across any calls to `black_box`. So, -/// it now: -/// -/// - Treats both arguments to `contains` as unpredictable: the body of `contains` can no longer be -/// optimized based on argument values -/// - Treats the call to `contains` and its result as volatile: the body of `benchmark` cannot -/// optimize this away -/// -/// This makes our benchmark much more realistic to how the function would actually be used, where -/// arguments are usually not known at compile time and the result is used in some way. -#[inline] -#[stable(feature = "bench_black_box", since = "1.66.0")] -#[rustc_const_unstable(feature = "const_black_box", issue = "none")] -pub const fn black_box(dummy: T) -> T { - crate::intrinsics::black_box(dummy) -} - -/// An identity function that causes an `unused_must_use` warning to be -/// triggered if the given value is not used (returned, stored in a variable, -/// etc) by the caller. -/// -/// This is primarily intended for use in macro-generated code, in which a -/// [`#[must_use]` attribute][must_use] either on a type or a function would not -/// be convenient. -/// -/// [must_use]: https://doc.rust-lang.org/reference/attributes/diagnostics.html#the-must_use-attribute -/// -/// # Example -/// -/// ``` -/// #![feature(hint_must_use)] -/// -/// use core::fmt; -/// -/// pub struct Error(/* ... */); -/// -/// #[macro_export] -/// macro_rules! make_error { -/// ($($args:expr),*) => { -/// core::hint::must_use({ -/// let error = $crate::make_error(core::format_args!($($args),*)); -/// error -/// }) -/// }; -/// } -/// -/// // Implementation detail of make_error! macro. -/// #[doc(hidden)] -/// pub fn make_error(args: fmt::Arguments<'_>) -> Error { -/// Error(/* ... */) -/// } -/// -/// fn demo() -> Option { -/// if true { -/// // Oops, meant to write `return Some(make_error!("..."));` -/// Some(make_error!("...")); -/// } -/// None -/// } -/// # -/// # // Make rustdoc not wrap the whole snippet in fn main, so that $crate::make_error works -/// # fn main() {} -/// ``` -/// -/// In the above example, we'd like an `unused_must_use` lint to apply to the -/// value created by `make_error!`. However, neither `#[must_use]` on a struct -/// nor `#[must_use]` on a function is appropriate here, so the macro expands -/// using `core::hint::must_use` instead. -/// -/// - We wouldn't want `#[must_use]` on the `struct Error` because that would -/// make the following unproblematic code trigger a warning: -/// -/// ``` -/// # struct Error; -/// # -/// fn f(arg: &str) -> Result<(), Error> -/// # { Ok(()) } -/// -/// #[test] -/// fn t() { -/// // Assert that `f` returns error if passed an empty string. -/// // A value of type `Error` is unused here but that's not a problem. -/// f("").unwrap_err(); -/// } -/// ``` -/// -/// - Using `#[must_use]` on `fn make_error` can't help because the return value -/// *is* used, as the right-hand side of a `let` statement. The `let` -/// statement looks useless but is in fact necessary for ensuring that -/// temporaries within the `format_args` expansion are not kept alive past the -/// creation of the `Error`, as keeping them alive past that point can cause -/// autotrait issues in async code: -/// -/// ``` -/// # #![feature(hint_must_use)] -/// # -/// # struct Error; -/// # -/// # macro_rules! make_error { -/// # ($($args:expr),*) => { -/// # core::hint::must_use({ -/// # // If `let` isn't used, then `f()` produces a non-Send future. -/// # let error = make_error(core::format_args!($($args),*)); -/// # error -/// # }) -/// # }; -/// # } -/// # -/// # fn make_error(args: core::fmt::Arguments<'_>) -> Error { -/// # Error -/// # } -/// # -/// async fn f() { -/// // Using `let` inside the make_error expansion causes temporaries like -/// // `unsync()` to drop at the semicolon of that `let` statement, which -/// // is prior to the await point. They would otherwise stay around until -/// // the semicolon on *this* statement, which is after the await point, -/// // and the enclosing Future would not implement Send. -/// log(make_error!("look: {:p}", unsync())).await; -/// } -/// -/// async fn log(error: Error) {/* ... */} -/// -/// // Returns something without a Sync impl. -/// fn unsync() -> *const () { -/// 0 as *const () -/// } -/// # -/// # fn test() { -/// # fn assert_send(_: impl Send) {} -/// # assert_send(f()); -/// # } -/// ``` -#[unstable(feature = "hint_must_use", issue = "94745")] -#[rustc_const_unstable(feature = "hint_must_use", issue = "94745")] -#[must_use] // <-- :) -#[inline(always)] -pub const fn must_use(value: T) -> T { - value -} diff --git a/library/core/src/internal_macros.rs b/library/core/src/internal_macros.rs deleted file mode 100644 index d3a4d6aff2d8b..0000000000000 --- a/library/core/src/internal_macros.rs +++ /dev/null @@ -1,158 +0,0 @@ -// implements the unary operator "op &T" -// based on "op T" where T is expected to be `Copy`able -macro_rules! forward_ref_unop { - (impl $imp:ident, $method:ident for $t:ty) => { - forward_ref_unop!(impl $imp, $method for $t, - #[stable(feature = "rust1", since = "1.0.0")]); - }; - (impl $imp:ident, $method:ident for $t:ty, #[$attr:meta]) => { - #[$attr] - impl $imp for &$t { - type Output = <$t as $imp>::Output; - - #[inline] - fn $method(self) -> <$t as $imp>::Output { - $imp::$method(*self) - } - } - } -} - -// implements binary operators "&T op U", "T op &U", "&T op &U" -// based on "T op U" where T and U are expected to be `Copy`able -macro_rules! forward_ref_binop { - (impl $imp:ident, $method:ident for $t:ty, $u:ty) => { - forward_ref_binop!(impl $imp, $method for $t, $u, - #[stable(feature = "rust1", since = "1.0.0")]); - }; - (impl $imp:ident, $method:ident for $t:ty, $u:ty, #[$attr:meta]) => { - #[$attr] - impl<'a> $imp<$u> for &'a $t { - type Output = <$t as $imp<$u>>::Output; - - #[inline] - #[track_caller] - fn $method(self, other: $u) -> <$t as $imp<$u>>::Output { - $imp::$method(*self, other) - } - } - - #[$attr] - impl $imp<&$u> for $t { - type Output = <$t as $imp<$u>>::Output; - - #[inline] - #[track_caller] - fn $method(self, other: &$u) -> <$t as $imp<$u>>::Output { - $imp::$method(self, *other) - } - } - - #[$attr] - impl $imp<&$u> for &$t { - type Output = <$t as $imp<$u>>::Output; - - #[inline] - #[track_caller] - fn $method(self, other: &$u) -> <$t as $imp<$u>>::Output { - $imp::$method(*self, *other) - } - } - } -} - -// implements "T op= &U", based on "T op= U" -// where U is expected to be `Copy`able -macro_rules! forward_ref_op_assign { - (impl $imp:ident, $method:ident for $t:ty, $u:ty) => { - forward_ref_op_assign!(impl $imp, $method for $t, $u, - #[stable(feature = "op_assign_builtins_by_ref", since = "1.22.0")]); - }; - (impl $imp:ident, $method:ident for $t:ty, $u:ty, #[$attr:meta]) => { - #[$attr] - impl $imp<&$u> for $t { - #[inline] - #[track_caller] - fn $method(&mut self, other: &$u) { - $imp::$method(self, *other); - } - } - } -} - -/// A macro for defining `#[cfg]` if-else statements. -/// -/// `cfg_if` is similar to the `if/elif` C preprocessor macro by allowing definition of a cascade -/// of `#[cfg]` cases, emitting the implementation which matches first. -/// -/// This allows you to conveniently provide a long list `#[cfg]`'d blocks of code without having to -/// rewrite each clause multiple times. -/// -/// # Example -/// -/// ```ignore(cannot-test-this-because-non-exported-macro) -/// cfg_if! { -/// if #[cfg(unix)] { -/// fn foo() { /* unix specific functionality */ } -/// } else if #[cfg(target_pointer_width = "32")] { -/// fn foo() { /* non-unix, 32-bit functionality */ } -/// } else { -/// fn foo() { /* fallback implementation */ } -/// } -/// } -/// -/// # fn main() {} -/// ``` -// This is a copy of `cfg_if!` from the `cfg_if` crate. -// The recursive invocations should use $crate if this is ever exported. -macro_rules! cfg_if { - // match if/else chains with a final `else` - ( - $( - if #[cfg( $i_meta:meta )] { $( $i_tokens:tt )* } - ) else+ - else { $( $e_tokens:tt )* } - ) => { - cfg_if! { - @__items () ; - $( - (( $i_meta ) ( $( $i_tokens )* )) , - )+ - (() ( $( $e_tokens )* )) , - } - }; - - // Internal and recursive macro to emit all the items - // - // Collects all the previous cfgs in a list at the beginning, so they can be - // negated. After the semicolon is all the remaining items. - (@__items ( $( $_:meta , )* ) ; ) => {}; - ( - @__items ( $( $no:meta , )* ) ; - (( $( $yes:meta )? ) ( $( $tokens:tt )* )) , - $( $rest:tt , )* - ) => { - // Emit all items within one block, applying an appropriate #[cfg]. The - // #[cfg] will require all `$yes` matchers specified and must also negate - // all previous matchers. - #[cfg(all( - $( $yes , )? - not(any( $( $no ),* )) - ))] - cfg_if! { @__identity $( $tokens )* } - - // Recurse to emit all other items in `$rest`, and when we do so add all - // our `$yes` matchers to the list of `$no` matchers as future emissions - // will have to negate everything we just matched as well. - cfg_if! { - @__items ( $( $no , )* $( $yes , )? ) ; - $( $rest , )* - } - }; - - // Internal macro to make __apply work out right for different match types, - // because of how macros match/expand stuff. - (@__identity $( $tokens:tt )* ) => { - $( $tokens )* - }; -} diff --git a/library/core/src/intrinsics.rs b/library/core/src/intrinsics.rs deleted file mode 100644 index 1ab7ef9b5dc72..0000000000000 --- a/library/core/src/intrinsics.rs +++ /dev/null @@ -1,3188 +0,0 @@ -//! Compiler intrinsics. -//! -//! The corresponding definitions are in . -//! The corresponding const implementations are in . -//! -//! # Const intrinsics -//! -//! Note: any changes to the constness of intrinsics should be discussed with the language team. -//! This includes changes in the stability of the constness. -//! -//! In order to make an intrinsic usable at compile-time, one needs to copy the implementation -//! from to -//! and add a -//! `#[rustc_const_unstable(feature = "const_such_and_such", issue = "01234")]` to the intrinsic declaration. -//! -//! If an intrinsic is supposed to be used from a `const fn` with a `rustc_const_stable` attribute, -//! the intrinsic's attribute must be `rustc_const_stable`, too. Such a change should not be done -//! without T-lang consultation, because it bakes a feature into the language that cannot be -//! replicated in user code without compiler support. -//! -//! # Volatiles -//! -//! The volatile intrinsics provide operations intended to act on I/O -//! memory, which are guaranteed to not be reordered by the compiler -//! across other volatile intrinsics. See the LLVM documentation on -//! [[volatile]]. -//! -//! [volatile]: https://llvm.org/docs/LangRef.html#volatile-memory-accesses -//! -//! # Atomics -//! -//! The atomic intrinsics provide common atomic operations on machine -//! words, with multiple possible memory orderings. They obey the same -//! semantics as C++11. See the LLVM documentation on [[atomics]]. -//! -//! [atomics]: https://llvm.org/docs/Atomics.html -//! -//! A quick refresher on memory ordering: -//! -//! * Acquire - a barrier for acquiring a lock. Subsequent reads and writes -//! take place after the barrier. -//! * Release - a barrier for releasing a lock. Preceding reads and writes -//! take place before the barrier. -//! * Sequentially consistent - sequentially consistent operations are -//! guaranteed to happen in order. This is the standard mode for working -//! with atomic types and is equivalent to Java's `volatile`. -//! -//! # Unwinding -//! -//! Rust intrinsics may, in general, unwind. If an intrinsic can never unwind, add the -//! `#[rustc_nounwind]` attribute so that the compiler can make use of this fact. -//! -//! However, even for intrinsics that may unwind, rustc assumes that a Rust intrinsics will never -//! initiate a foreign (non-Rust) unwind, and thus for panic=abort we can always assume that these -//! intrinsics cannot unwind. - -#![unstable( - feature = "core_intrinsics", - reason = "intrinsics are unlikely to ever be stabilized, instead \ - they should be used through stabilized interfaces \ - in the rest of the standard library", - issue = "none" -)] -#![allow(missing_docs)] - -use safety::requires; -use crate::marker::DiscriminantKind; -use crate::marker::Tuple; -use crate::mem::align_of; -use crate::ptr; -use crate::ub_checks; - -#[cfg(kani)] -use crate::kani; - -pub mod mir; -pub mod simd; - -// These imports are used for simplifying intra-doc links -#[allow(unused_imports)] -#[cfg(all(target_has_atomic = "8", target_has_atomic = "32", target_has_atomic = "ptr"))] -use crate::sync::atomic::{self, AtomicBool, AtomicI32, AtomicIsize, AtomicU32, Ordering}; - -#[stable(feature = "drop_in_place", since = "1.8.0")] -#[rustc_allowed_through_unstable_modules] -#[deprecated(note = "no longer an intrinsic - use `ptr::drop_in_place` directly", since = "1.52.0")] -#[inline] -pub unsafe fn drop_in_place(to_drop: *mut T) { - // SAFETY: see `ptr::drop_in_place` - unsafe { crate::ptr::drop_in_place(to_drop) } -} - -extern "rust-intrinsic" { - // N.B., these intrinsics take raw pointers because they mutate aliased - // memory, which is not valid for either `&` or `&mut`. - - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange` method by passing - /// [`Ordering::Relaxed`] as both the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange`]. - #[rustc_nounwind] - pub fn atomic_cxchg_relaxed_relaxed(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange` method by passing - /// [`Ordering::Relaxed`] and [`Ordering::Acquire`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange`]. - #[rustc_nounwind] - pub fn atomic_cxchg_relaxed_acquire(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange` method by passing - /// [`Ordering::Relaxed`] and [`Ordering::SeqCst`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange`]. - #[rustc_nounwind] - pub fn atomic_cxchg_relaxed_seqcst(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange` method by passing - /// [`Ordering::Acquire`] and [`Ordering::Relaxed`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange`]. - #[rustc_nounwind] - pub fn atomic_cxchg_acquire_relaxed(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange` method by passing - /// [`Ordering::Acquire`] as both the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange`]. - #[rustc_nounwind] - pub fn atomic_cxchg_acquire_acquire(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange` method by passing - /// [`Ordering::Acquire`] and [`Ordering::SeqCst`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange`]. - #[rustc_nounwind] - pub fn atomic_cxchg_acquire_seqcst(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange` method by passing - /// [`Ordering::Release`] and [`Ordering::Relaxed`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange`]. - #[rustc_nounwind] - pub fn atomic_cxchg_release_relaxed(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange` method by passing - /// [`Ordering::Release`] and [`Ordering::Acquire`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange`]. - #[rustc_nounwind] - pub fn atomic_cxchg_release_acquire(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange` method by passing - /// [`Ordering::Release`] and [`Ordering::SeqCst`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange`]. - #[rustc_nounwind] - pub fn atomic_cxchg_release_seqcst(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange` method by passing - /// [`Ordering::AcqRel`] and [`Ordering::Relaxed`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange`]. - #[rustc_nounwind] - pub fn atomic_cxchg_acqrel_relaxed(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange` method by passing - /// [`Ordering::AcqRel`] and [`Ordering::Acquire`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange`]. - #[rustc_nounwind] - pub fn atomic_cxchg_acqrel_acquire(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange` method by passing - /// [`Ordering::AcqRel`] and [`Ordering::SeqCst`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange`]. - #[rustc_nounwind] - pub fn atomic_cxchg_acqrel_seqcst(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange` method by passing - /// [`Ordering::SeqCst`] and [`Ordering::Relaxed`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange`]. - #[rustc_nounwind] - pub fn atomic_cxchg_seqcst_relaxed(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange` method by passing - /// [`Ordering::SeqCst`] and [`Ordering::Acquire`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange`]. - #[rustc_nounwind] - pub fn atomic_cxchg_seqcst_acquire(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange` method by passing - /// [`Ordering::SeqCst`] as both the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange`]. - #[rustc_nounwind] - pub fn atomic_cxchg_seqcst_seqcst(dst: *mut T, old: T, src: T) -> (T, bool); - - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange_weak` method by passing - /// [`Ordering::Relaxed`] as both the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange_weak`]. - #[rustc_nounwind] - pub fn atomic_cxchgweak_relaxed_relaxed(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange_weak` method by passing - /// [`Ordering::Relaxed`] and [`Ordering::Acquire`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange_weak`]. - #[rustc_nounwind] - pub fn atomic_cxchgweak_relaxed_acquire(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange_weak` method by passing - /// [`Ordering::Relaxed`] and [`Ordering::SeqCst`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange_weak`]. - #[rustc_nounwind] - pub fn atomic_cxchgweak_relaxed_seqcst(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange_weak` method by passing - /// [`Ordering::Acquire`] and [`Ordering::Relaxed`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange_weak`]. - #[rustc_nounwind] - pub fn atomic_cxchgweak_acquire_relaxed(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange_weak` method by passing - /// [`Ordering::Acquire`] as both the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange_weak`]. - #[rustc_nounwind] - pub fn atomic_cxchgweak_acquire_acquire(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange_weak` method by passing - /// [`Ordering::Acquire`] and [`Ordering::SeqCst`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange_weak`]. - #[rustc_nounwind] - pub fn atomic_cxchgweak_acquire_seqcst(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange_weak` method by passing - /// [`Ordering::Release`] and [`Ordering::Relaxed`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange_weak`]. - #[rustc_nounwind] - pub fn atomic_cxchgweak_release_relaxed(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange_weak` method by passing - /// [`Ordering::Release`] and [`Ordering::Acquire`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange_weak`]. - #[rustc_nounwind] - pub fn atomic_cxchgweak_release_acquire(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange_weak` method by passing - /// [`Ordering::Release`] and [`Ordering::SeqCst`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange_weak`]. - #[rustc_nounwind] - pub fn atomic_cxchgweak_release_seqcst(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange_weak` method by passing - /// [`Ordering::AcqRel`] and [`Ordering::Relaxed`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange_weak`]. - #[rustc_nounwind] - pub fn atomic_cxchgweak_acqrel_relaxed(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange_weak` method by passing - /// [`Ordering::AcqRel`] and [`Ordering::Acquire`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange_weak`]. - #[rustc_nounwind] - pub fn atomic_cxchgweak_acqrel_acquire(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange_weak` method by passing - /// [`Ordering::AcqRel`] and [`Ordering::SeqCst`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange_weak`]. - #[rustc_nounwind] - pub fn atomic_cxchgweak_acqrel_seqcst(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange_weak` method by passing - /// [`Ordering::SeqCst`] and [`Ordering::Relaxed`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange_weak`]. - #[rustc_nounwind] - pub fn atomic_cxchgweak_seqcst_relaxed(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange_weak` method by passing - /// [`Ordering::SeqCst`] and [`Ordering::Acquire`] as the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange_weak`]. - #[rustc_nounwind] - pub fn atomic_cxchgweak_seqcst_acquire(dst: *mut T, old: T, src: T) -> (T, bool); - /// Stores a value if the current value is the same as the `old` value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `compare_exchange_weak` method by passing - /// [`Ordering::SeqCst`] as both the success and failure parameters. - /// For example, [`AtomicBool::compare_exchange_weak`]. - #[rustc_nounwind] - pub fn atomic_cxchgweak_seqcst_seqcst(dst: *mut T, old: T, src: T) -> (T, bool); - - /// Loads the current value of the pointer. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `load` method by passing - /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::load`]. - #[rustc_nounwind] - pub fn atomic_load_seqcst(src: *const T) -> T; - /// Loads the current value of the pointer. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `load` method by passing - /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::load`]. - #[rustc_nounwind] - pub fn atomic_load_acquire(src: *const T) -> T; - /// Loads the current value of the pointer. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `load` method by passing - /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::load`]. - #[rustc_nounwind] - pub fn atomic_load_relaxed(src: *const T) -> T; - /// Do NOT use this intrinsic; "unordered" operations do not exist in our memory model! - /// In terms of the Rust Abstract Machine, this operation is equivalent to `src.read()`, - /// i.e., it performs a non-atomic read. - #[rustc_nounwind] - pub fn atomic_load_unordered(src: *const T) -> T; - - /// Stores the value at the specified memory location. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `store` method by passing - /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::store`]. - #[rustc_nounwind] - pub fn atomic_store_seqcst(dst: *mut T, val: T); - /// Stores the value at the specified memory location. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `store` method by passing - /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::store`]. - #[rustc_nounwind] - pub fn atomic_store_release(dst: *mut T, val: T); - /// Stores the value at the specified memory location. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `store` method by passing - /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::store`]. - #[rustc_nounwind] - pub fn atomic_store_relaxed(dst: *mut T, val: T); - /// Do NOT use this intrinsic; "unordered" operations do not exist in our memory model! - /// In terms of the Rust Abstract Machine, this operation is equivalent to `dst.write(val)`, - /// i.e., it performs a non-atomic write. - #[rustc_nounwind] - pub fn atomic_store_unordered(dst: *mut T, val: T); - - /// Stores the value at the specified memory location, returning the old value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `swap` method by passing - /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::swap`]. - #[rustc_nounwind] - pub fn atomic_xchg_seqcst(dst: *mut T, src: T) -> T; - /// Stores the value at the specified memory location, returning the old value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `swap` method by passing - /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::swap`]. - #[rustc_nounwind] - pub fn atomic_xchg_acquire(dst: *mut T, src: T) -> T; - /// Stores the value at the specified memory location, returning the old value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `swap` method by passing - /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::swap`]. - #[rustc_nounwind] - pub fn atomic_xchg_release(dst: *mut T, src: T) -> T; - /// Stores the value at the specified memory location, returning the old value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `swap` method by passing - /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::swap`]. - #[rustc_nounwind] - pub fn atomic_xchg_acqrel(dst: *mut T, src: T) -> T; - /// Stores the value at the specified memory location, returning the old value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `swap` method by passing - /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::swap`]. - #[rustc_nounwind] - pub fn atomic_xchg_relaxed(dst: *mut T, src: T) -> T; - - /// Adds to the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_add` method by passing - /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicIsize::fetch_add`]. - #[rustc_nounwind] - pub fn atomic_xadd_seqcst(dst: *mut T, src: T) -> T; - /// Adds to the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_add` method by passing - /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicIsize::fetch_add`]. - #[rustc_nounwind] - pub fn atomic_xadd_acquire(dst: *mut T, src: T) -> T; - /// Adds to the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_add` method by passing - /// [`Ordering::Release`] as the `order`. For example, [`AtomicIsize::fetch_add`]. - #[rustc_nounwind] - pub fn atomic_xadd_release(dst: *mut T, src: T) -> T; - /// Adds to the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_add` method by passing - /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicIsize::fetch_add`]. - #[rustc_nounwind] - pub fn atomic_xadd_acqrel(dst: *mut T, src: T) -> T; - /// Adds to the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_add` method by passing - /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicIsize::fetch_add`]. - #[rustc_nounwind] - pub fn atomic_xadd_relaxed(dst: *mut T, src: T) -> T; - - /// Subtract from the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_sub` method by passing - /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicIsize::fetch_sub`]. - #[rustc_nounwind] - pub fn atomic_xsub_seqcst(dst: *mut T, src: T) -> T; - /// Subtract from the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_sub` method by passing - /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicIsize::fetch_sub`]. - #[rustc_nounwind] - pub fn atomic_xsub_acquire(dst: *mut T, src: T) -> T; - /// Subtract from the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_sub` method by passing - /// [`Ordering::Release`] as the `order`. For example, [`AtomicIsize::fetch_sub`]. - #[rustc_nounwind] - pub fn atomic_xsub_release(dst: *mut T, src: T) -> T; - /// Subtract from the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_sub` method by passing - /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicIsize::fetch_sub`]. - #[rustc_nounwind] - pub fn atomic_xsub_acqrel(dst: *mut T, src: T) -> T; - /// Subtract from the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_sub` method by passing - /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicIsize::fetch_sub`]. - #[rustc_nounwind] - pub fn atomic_xsub_relaxed(dst: *mut T, src: T) -> T; - - /// Bitwise and with the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_and` method by passing - /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::fetch_and`]. - #[rustc_nounwind] - pub fn atomic_and_seqcst(dst: *mut T, src: T) -> T; - /// Bitwise and with the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_and` method by passing - /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::fetch_and`]. - #[rustc_nounwind] - pub fn atomic_and_acquire(dst: *mut T, src: T) -> T; - /// Bitwise and with the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_and` method by passing - /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::fetch_and`]. - #[rustc_nounwind] - pub fn atomic_and_release(dst: *mut T, src: T) -> T; - /// Bitwise and with the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_and` method by passing - /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::fetch_and`]. - #[rustc_nounwind] - pub fn atomic_and_acqrel(dst: *mut T, src: T) -> T; - /// Bitwise and with the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_and` method by passing - /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::fetch_and`]. - #[rustc_nounwind] - pub fn atomic_and_relaxed(dst: *mut T, src: T) -> T; - - /// Bitwise nand with the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`AtomicBool`] type via the `fetch_nand` method by passing - /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::fetch_nand`]. - #[rustc_nounwind] - pub fn atomic_nand_seqcst(dst: *mut T, src: T) -> T; - /// Bitwise nand with the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`AtomicBool`] type via the `fetch_nand` method by passing - /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::fetch_nand`]. - #[rustc_nounwind] - pub fn atomic_nand_acquire(dst: *mut T, src: T) -> T; - /// Bitwise nand with the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`AtomicBool`] type via the `fetch_nand` method by passing - /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::fetch_nand`]. - #[rustc_nounwind] - pub fn atomic_nand_release(dst: *mut T, src: T) -> T; - /// Bitwise nand with the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`AtomicBool`] type via the `fetch_nand` method by passing - /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::fetch_nand`]. - #[rustc_nounwind] - pub fn atomic_nand_acqrel(dst: *mut T, src: T) -> T; - /// Bitwise nand with the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`AtomicBool`] type via the `fetch_nand` method by passing - /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::fetch_nand`]. - #[rustc_nounwind] - pub fn atomic_nand_relaxed(dst: *mut T, src: T) -> T; - - /// Bitwise or with the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_or` method by passing - /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::fetch_or`]. - #[rustc_nounwind] - pub fn atomic_or_seqcst(dst: *mut T, src: T) -> T; - /// Bitwise or with the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_or` method by passing - /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::fetch_or`]. - #[rustc_nounwind] - pub fn atomic_or_acquire(dst: *mut T, src: T) -> T; - /// Bitwise or with the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_or` method by passing - /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::fetch_or`]. - #[rustc_nounwind] - pub fn atomic_or_release(dst: *mut T, src: T) -> T; - /// Bitwise or with the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_or` method by passing - /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::fetch_or`]. - #[rustc_nounwind] - pub fn atomic_or_acqrel(dst: *mut T, src: T) -> T; - /// Bitwise or with the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_or` method by passing - /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::fetch_or`]. - #[rustc_nounwind] - pub fn atomic_or_relaxed(dst: *mut T, src: T) -> T; - - /// Bitwise xor with the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_xor` method by passing - /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicBool::fetch_xor`]. - #[rustc_nounwind] - pub fn atomic_xor_seqcst(dst: *mut T, src: T) -> T; - /// Bitwise xor with the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_xor` method by passing - /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicBool::fetch_xor`]. - #[rustc_nounwind] - pub fn atomic_xor_acquire(dst: *mut T, src: T) -> T; - /// Bitwise xor with the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_xor` method by passing - /// [`Ordering::Release`] as the `order`. For example, [`AtomicBool::fetch_xor`]. - #[rustc_nounwind] - pub fn atomic_xor_release(dst: *mut T, src: T) -> T; - /// Bitwise xor with the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_xor` method by passing - /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicBool::fetch_xor`]. - #[rustc_nounwind] - pub fn atomic_xor_acqrel(dst: *mut T, src: T) -> T; - /// Bitwise xor with the current value, returning the previous value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] types via the `fetch_xor` method by passing - /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicBool::fetch_xor`]. - #[rustc_nounwind] - pub fn atomic_xor_relaxed(dst: *mut T, src: T) -> T; - - /// Maximum with the current value using a signed comparison. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] signed integer types via the `fetch_max` method by passing - /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicI32::fetch_max`]. - #[rustc_nounwind] - pub fn atomic_max_seqcst(dst: *mut T, src: T) -> T; - /// Maximum with the current value using a signed comparison. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] signed integer types via the `fetch_max` method by passing - /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicI32::fetch_max`]. - #[rustc_nounwind] - pub fn atomic_max_acquire(dst: *mut T, src: T) -> T; - /// Maximum with the current value using a signed comparison. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] signed integer types via the `fetch_max` method by passing - /// [`Ordering::Release`] as the `order`. For example, [`AtomicI32::fetch_max`]. - #[rustc_nounwind] - pub fn atomic_max_release(dst: *mut T, src: T) -> T; - /// Maximum with the current value using a signed comparison. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] signed integer types via the `fetch_max` method by passing - /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicI32::fetch_max`]. - #[rustc_nounwind] - pub fn atomic_max_acqrel(dst: *mut T, src: T) -> T; - /// Maximum with the current value. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] signed integer types via the `fetch_max` method by passing - /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicI32::fetch_max`]. - #[rustc_nounwind] - pub fn atomic_max_relaxed(dst: *mut T, src: T) -> T; - - /// Minimum with the current value using a signed comparison. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] signed integer types via the `fetch_min` method by passing - /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicI32::fetch_min`]. - #[rustc_nounwind] - pub fn atomic_min_seqcst(dst: *mut T, src: T) -> T; - /// Minimum with the current value using a signed comparison. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] signed integer types via the `fetch_min` method by passing - /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicI32::fetch_min`]. - #[rustc_nounwind] - pub fn atomic_min_acquire(dst: *mut T, src: T) -> T; - /// Minimum with the current value using a signed comparison. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] signed integer types via the `fetch_min` method by passing - /// [`Ordering::Release`] as the `order`. For example, [`AtomicI32::fetch_min`]. - #[rustc_nounwind] - pub fn atomic_min_release(dst: *mut T, src: T) -> T; - /// Minimum with the current value using a signed comparison. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] signed integer types via the `fetch_min` method by passing - /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicI32::fetch_min`]. - #[rustc_nounwind] - pub fn atomic_min_acqrel(dst: *mut T, src: T) -> T; - /// Minimum with the current value using a signed comparison. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] signed integer types via the `fetch_min` method by passing - /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicI32::fetch_min`]. - #[rustc_nounwind] - pub fn atomic_min_relaxed(dst: *mut T, src: T) -> T; - - /// Minimum with the current value using an unsigned comparison. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] unsigned integer types via the `fetch_min` method by passing - /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicU32::fetch_min`]. - #[rustc_nounwind] - pub fn atomic_umin_seqcst(dst: *mut T, src: T) -> T; - /// Minimum with the current value using an unsigned comparison. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] unsigned integer types via the `fetch_min` method by passing - /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicU32::fetch_min`]. - #[rustc_nounwind] - pub fn atomic_umin_acquire(dst: *mut T, src: T) -> T; - /// Minimum with the current value using an unsigned comparison. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] unsigned integer types via the `fetch_min` method by passing - /// [`Ordering::Release`] as the `order`. For example, [`AtomicU32::fetch_min`]. - #[rustc_nounwind] - pub fn atomic_umin_release(dst: *mut T, src: T) -> T; - /// Minimum with the current value using an unsigned comparison. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] unsigned integer types via the `fetch_min` method by passing - /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicU32::fetch_min`]. - #[rustc_nounwind] - pub fn atomic_umin_acqrel(dst: *mut T, src: T) -> T; - /// Minimum with the current value using an unsigned comparison. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] unsigned integer types via the `fetch_min` method by passing - /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicU32::fetch_min`]. - #[rustc_nounwind] - pub fn atomic_umin_relaxed(dst: *mut T, src: T) -> T; - - /// Maximum with the current value using an unsigned comparison. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] unsigned integer types via the `fetch_max` method by passing - /// [`Ordering::SeqCst`] as the `order`. For example, [`AtomicU32::fetch_max`]. - #[rustc_nounwind] - pub fn atomic_umax_seqcst(dst: *mut T, src: T) -> T; - /// Maximum with the current value using an unsigned comparison. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] unsigned integer types via the `fetch_max` method by passing - /// [`Ordering::Acquire`] as the `order`. For example, [`AtomicU32::fetch_max`]. - #[rustc_nounwind] - pub fn atomic_umax_acquire(dst: *mut T, src: T) -> T; - /// Maximum with the current value using an unsigned comparison. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] unsigned integer types via the `fetch_max` method by passing - /// [`Ordering::Release`] as the `order`. For example, [`AtomicU32::fetch_max`]. - #[rustc_nounwind] - pub fn atomic_umax_release(dst: *mut T, src: T) -> T; - /// Maximum with the current value using an unsigned comparison. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] unsigned integer types via the `fetch_max` method by passing - /// [`Ordering::AcqRel`] as the `order`. For example, [`AtomicU32::fetch_max`]. - #[rustc_nounwind] - pub fn atomic_umax_acqrel(dst: *mut T, src: T) -> T; - /// Maximum with the current value using an unsigned comparison. - /// - /// The stabilized version of this intrinsic is available on the - /// [`atomic`] unsigned integer types via the `fetch_max` method by passing - /// [`Ordering::Relaxed`] as the `order`. For example, [`AtomicU32::fetch_max`]. - #[rustc_nounwind] - pub fn atomic_umax_relaxed(dst: *mut T, src: T) -> T; - - /// An atomic fence. - /// - /// The stabilized version of this intrinsic is available in - /// [`atomic::fence`] by passing [`Ordering::SeqCst`] - /// as the `order`. - #[rustc_nounwind] - pub fn atomic_fence_seqcst(); - /// An atomic fence. - /// - /// The stabilized version of this intrinsic is available in - /// [`atomic::fence`] by passing [`Ordering::Acquire`] - /// as the `order`. - #[rustc_nounwind] - pub fn atomic_fence_acquire(); - /// An atomic fence. - /// - /// The stabilized version of this intrinsic is available in - /// [`atomic::fence`] by passing [`Ordering::Release`] - /// as the `order`. - #[rustc_nounwind] - pub fn atomic_fence_release(); - /// An atomic fence. - /// - /// The stabilized version of this intrinsic is available in - /// [`atomic::fence`] by passing [`Ordering::AcqRel`] - /// as the `order`. - #[rustc_nounwind] - pub fn atomic_fence_acqrel(); - - /// A compiler-only memory barrier. - /// - /// Memory accesses will never be reordered across this barrier by the - /// compiler, but no instructions will be emitted for it. This is - /// appropriate for operations on the same thread that may be preempted, - /// such as when interacting with signal handlers. - /// - /// The stabilized version of this intrinsic is available in - /// [`atomic::compiler_fence`] by passing [`Ordering::SeqCst`] - /// as the `order`. - #[rustc_nounwind] - pub fn atomic_singlethreadfence_seqcst(); - /// A compiler-only memory barrier. - /// - /// Memory accesses will never be reordered across this barrier by the - /// compiler, but no instructions will be emitted for it. This is - /// appropriate for operations on the same thread that may be preempted, - /// such as when interacting with signal handlers. - /// - /// The stabilized version of this intrinsic is available in - /// [`atomic::compiler_fence`] by passing [`Ordering::Acquire`] - /// as the `order`. - #[rustc_nounwind] - pub fn atomic_singlethreadfence_acquire(); - /// A compiler-only memory barrier. - /// - /// Memory accesses will never be reordered across this barrier by the - /// compiler, but no instructions will be emitted for it. This is - /// appropriate for operations on the same thread that may be preempted, - /// such as when interacting with signal handlers. - /// - /// The stabilized version of this intrinsic is available in - /// [`atomic::compiler_fence`] by passing [`Ordering::Release`] - /// as the `order`. - #[rustc_nounwind] - pub fn atomic_singlethreadfence_release(); - /// A compiler-only memory barrier. - /// - /// Memory accesses will never be reordered across this barrier by the - /// compiler, but no instructions will be emitted for it. This is - /// appropriate for operations on the same thread that may be preempted, - /// such as when interacting with signal handlers. - /// - /// The stabilized version of this intrinsic is available in - /// [`atomic::compiler_fence`] by passing [`Ordering::AcqRel`] - /// as the `order`. - #[rustc_nounwind] - pub fn atomic_singlethreadfence_acqrel(); - - /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction - /// if supported; otherwise, it is a no-op. - /// Prefetches have no effect on the behavior of the program but can change its performance - /// characteristics. - /// - /// The `locality` argument must be a constant integer and is a temporal locality specifier - /// ranging from (0) - no locality, to (3) - extremely local keep in cache. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - pub fn prefetch_read_data(data: *const T, locality: i32); - /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction - /// if supported; otherwise, it is a no-op. - /// Prefetches have no effect on the behavior of the program but can change its performance - /// characteristics. - /// - /// The `locality` argument must be a constant integer and is a temporal locality specifier - /// ranging from (0) - no locality, to (3) - extremely local keep in cache. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - pub fn prefetch_write_data(data: *const T, locality: i32); - /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction - /// if supported; otherwise, it is a no-op. - /// Prefetches have no effect on the behavior of the program but can change its performance - /// characteristics. - /// - /// The `locality` argument must be a constant integer and is a temporal locality specifier - /// ranging from (0) - no locality, to (3) - extremely local keep in cache. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - pub fn prefetch_read_instruction(data: *const T, locality: i32); - /// The `prefetch` intrinsic is a hint to the code generator to insert a prefetch instruction - /// if supported; otherwise, it is a no-op. - /// Prefetches have no effect on the behavior of the program but can change its performance - /// characteristics. - /// - /// The `locality` argument must be a constant integer and is a temporal locality specifier - /// ranging from (0) - no locality, to (3) - extremely local keep in cache. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - pub fn prefetch_write_instruction(data: *const T, locality: i32); - - /// Magic intrinsic that derives its meaning from attributes - /// attached to the function. - /// - /// For example, dataflow uses this to inject static assertions so - /// that `rustc_peek(potentially_uninitialized)` would actually - /// double-check that dataflow did indeed compute that it is - /// uninitialized at that point in the control flow. - /// - /// This intrinsic should not be used outside of the compiler. - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn rustc_peek(_: T) -> T; - - /// Aborts the execution of the process. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// [`std::process::abort`](../../std/process/fn.abort.html) is to be preferred if possible, - /// as its behavior is more user-friendly and more stable. - /// - /// The current implementation of `intrinsics::abort` is to invoke an invalid instruction, - /// on most platforms. - /// On Unix, the - /// process will probably terminate with a signal like `SIGABRT`, `SIGILL`, `SIGTRAP`, `SIGSEGV` or - /// `SIGBUS`. The precise behaviour is not guaranteed and not stable. - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn abort() -> !; - - /// Informs the optimizer that this point in the code is not reachable, - /// enabling further optimizations. - /// - /// N.B., this is very different from the `unreachable!()` macro: Unlike the - /// macro, which panics when it is executed, it is *undefined behavior* to - /// reach code marked with this function. - /// - /// The stabilized version of this intrinsic is [`core::hint::unreachable_unchecked`]. - #[rustc_const_stable(feature = "const_unreachable_unchecked", since = "1.57.0")] - #[rustc_nounwind] - pub fn unreachable() -> !; - -} - -/// Informs the optimizer that a condition is always true. -/// If the condition is false, the behavior is undefined. -/// -/// No code is generated for this intrinsic, but the optimizer will try -/// to preserve it (and its condition) between passes, which may interfere -/// with optimization of surrounding code and reduce performance. It should -/// not be used if the invariant can be discovered by the optimizer on its -/// own, or if it does not enable any significant optimizations. -/// -/// This intrinsic does not have a stable counterpart. -#[rustc_const_stable(feature = "const_assume", since = "1.77.0")] -#[rustc_nounwind] -#[unstable(feature = "core_intrinsics", issue = "none")] -#[rustc_intrinsic] -pub const unsafe fn assume(b: bool) { - if !b { - // SAFETY: the caller must guarantee the argument is never `false` - unsafe { unreachable() } - } -} - -/// Hints to the compiler that branch condition is likely to be true. -/// Returns the value passed to it. -/// -/// Any use other than with `if` statements will probably not have an effect. -/// -/// Note that, unlike most intrinsics, this is safe to call; -/// it does not require an `unsafe` block. -/// Therefore, implementations must not require the user to uphold -/// any safety invariants. -/// -/// This intrinsic does not have a stable counterpart. -#[rustc_const_unstable(feature = "const_likely", issue = "none")] -#[unstable(feature = "core_intrinsics", issue = "none")] -#[rustc_intrinsic] -#[rustc_nounwind] -#[cfg_attr(not(bootstrap), miri::intrinsic_fallback_is_spec)] -pub const fn likely(b: bool) -> bool { - b -} - -/// Hints to the compiler that branch condition is likely to be false. -/// Returns the value passed to it. -/// -/// Any use other than with `if` statements will probably not have an effect. -/// -/// Note that, unlike most intrinsics, this is safe to call; -/// it does not require an `unsafe` block. -/// Therefore, implementations must not require the user to uphold -/// any safety invariants. -/// -/// This intrinsic does not have a stable counterpart. -#[rustc_const_unstable(feature = "const_likely", issue = "none")] -#[unstable(feature = "core_intrinsics", issue = "none")] -#[rustc_intrinsic] -#[rustc_nounwind] -#[cfg_attr(not(bootstrap), miri::intrinsic_fallback_is_spec)] -pub const fn unlikely(b: bool) -> bool { - b -} - -extern "rust-intrinsic" { - /// Executes a breakpoint trap, for inspection by a debugger. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - pub fn breakpoint(); - - /// The size of a type in bytes. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// More specifically, this is the offset in bytes between successive - /// items of the same type, including alignment padding. - /// - /// The stabilized version of this intrinsic is [`core::mem::size_of`]. - #[rustc_const_stable(feature = "const_size_of", since = "1.40.0")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn size_of() -> usize; - - /// The minimum alignment of a type. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized version of this intrinsic is [`core::mem::align_of`]. - #[rustc_const_stable(feature = "const_min_align_of", since = "1.40.0")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn min_align_of() -> usize; - /// The preferred alignment of a type. - /// - /// This intrinsic does not have a stable counterpart. - /// It's "tracking issue" is [#91971](https://github.com/rust-lang/rust/issues/91971). - #[rustc_const_unstable(feature = "const_pref_align_of", issue = "91971")] - #[rustc_nounwind] - pub fn pref_align_of() -> usize; - - /// The size of the referenced value in bytes. - /// - /// The stabilized version of this intrinsic is [`crate::mem::size_of_val`]. - #[rustc_const_unstable(feature = "const_size_of_val", issue = "46571")] - #[rustc_nounwind] - pub fn size_of_val(_: *const T) -> usize; - /// The required alignment of the referenced value. - /// - /// The stabilized version of this intrinsic is [`core::mem::align_of_val`]. - #[rustc_const_unstable(feature = "const_align_of_val", issue = "46571")] - #[rustc_nounwind] - pub fn min_align_of_val(_: *const T) -> usize; - - /// Gets a static string slice containing the name of a type. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized version of this intrinsic is [`core::any::type_name`]. - #[rustc_const_unstable(feature = "const_type_name", issue = "63084")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn type_name() -> &'static str; - - /// Gets an identifier which is globally unique to the specified type. This - /// function will return the same value for a type regardless of whichever - /// crate it is invoked in. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized version of this intrinsic is [`core::any::TypeId::of`]. - #[rustc_const_unstable(feature = "const_type_id", issue = "77125")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn type_id() -> u128; - - /// A guard for unsafe functions that cannot ever be executed if `T` is uninhabited: - /// This will statically either panic, or do nothing. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_const_stable(feature = "const_assert_type", since = "1.59.0")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn assert_inhabited(); - - /// A guard for unsafe functions that cannot ever be executed if `T` does not permit - /// zero-initialization: This will statically either panic, or do nothing. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_const_stable(feature = "const_assert_type2", since = "1.75.0")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn assert_zero_valid(); - - /// A guard for `std::mem::uninitialized`. This will statically either panic, or do nothing. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_const_stable(feature = "const_assert_type2", since = "1.75.0")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn assert_mem_uninitialized_valid(); - - /// Gets a reference to a static `Location` indicating where it was called. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// Consider using [`core::panic::Location::caller`] instead. - #[rustc_const_stable(feature = "const_caller_location", since = "1.79.0")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn caller_location() -> &'static crate::panic::Location<'static>; - - /// Moves a value out of scope without running drop glue. - /// - /// This exists solely for [`crate::mem::forget_unsized`]; normal `forget` uses - /// `ManuallyDrop` instead. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - #[rustc_const_unstable(feature = "const_intrinsic_forget", issue = "none")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn forget(_: T); - - /// Reinterprets the bits of a value of one type as another type. - /// - /// Both types must have the same size. Compilation will fail if this is not guaranteed. - /// - /// `transmute` is semantically equivalent to a bitwise move of one type - /// into another. It copies the bits from the source value into the - /// destination value, then forgets the original. Note that source and destination - /// are passed by-value, which means if `Src` or `Dst` contain padding, that padding - /// is *not* guaranteed to be preserved by `transmute`. - /// - /// Both the argument and the result must be [valid](../../nomicon/what-unsafe-does.html) at - /// their given type. Violating this condition leads to [undefined behavior][ub]. The compiler - /// will generate code *assuming that you, the programmer, ensure that there will never be - /// undefined behavior*. It is therefore your responsibility to guarantee that every value - /// passed to `transmute` is valid at both types `Src` and `Dst`. Failing to uphold this condition - /// may lead to unexpected and unstable compilation results. This makes `transmute` **incredibly - /// unsafe**. `transmute` should be the absolute last resort. - /// - /// Because `transmute` is a by-value operation, alignment of the *transmuted values - /// themselves* is not a concern. As with any other function, the compiler already ensures - /// both `Src` and `Dst` are properly aligned. However, when transmuting values that *point - /// elsewhere* (such as pointers, references, boxes…), the caller has to ensure proper - /// alignment of the pointed-to values. - /// - /// The [nomicon](../../nomicon/transmutes.html) has additional documentation. - /// - /// [ub]: ../../reference/behavior-considered-undefined.html - /// - /// # Transmutation between pointers and integers - /// - /// Special care has to be taken when transmuting between pointers and integers, e.g. - /// transmuting between `*const ()` and `usize`. - /// - /// Transmuting *pointers to integers* in a `const` context is [undefined behavior][ub], unless - /// the pointer was originally created *from* an integer. (That includes this function - /// specifically, integer-to-pointer casts, and helpers like [`dangling`][crate::ptr::dangling], - /// but also semantically-equivalent conversions such as punning through `repr(C)` union - /// fields.) Any attempt to use the resulting value for integer operations will abort - /// const-evaluation. (And even outside `const`, such transmutation is touching on many - /// unspecified aspects of the Rust memory model and should be avoided. See below for - /// alternatives.) - /// - /// Transmuting *integers to pointers* is a largely unspecified operation. It is likely *not* - /// equivalent to an `as` cast. Doing non-zero-sized memory accesses with a pointer constructed - /// this way is currently considered undefined behavior. - /// - /// All this also applies when the integer is nested inside an array, tuple, struct, or enum. - /// However, `MaybeUninit` is not considered an integer type for the purpose of this - /// section. Transmuting `*const ()` to `MaybeUninit` is fine---but then calling - /// `assume_init()` on that result is considered as completing the pointer-to-integer transmute - /// and thus runs into the issues discussed above. - /// - /// In particular, doing a pointer-to-integer-to-pointer roundtrip via `transmute` is *not* a - /// lossless process. If you want to round-trip a pointer through an integer in a way that you - /// can get back the original pointer, you need to use `as` casts, or replace the integer type - /// by `MaybeUninit<$int>` (and never call `assume_init()`). If you are looking for a way to - /// store data of arbitrary type, also use `MaybeUninit` (that will also handle uninitialized - /// memory due to padding). If you specifically need to store something that is "either an - /// integer or a pointer", use `*mut ()`: integers can be converted to pointers and back without - /// any loss (via `as` casts or via `transmute`). - /// - /// # Examples - /// - /// There are a few things that `transmute` is really useful for. - /// - /// Turning a pointer into a function pointer. This is *not* portable to - /// machines where function pointers and data pointers have different sizes. - /// - /// ``` - /// fn foo() -> i32 { - /// 0 - /// } - /// // Crucially, we `as`-cast to a raw pointer before `transmute`ing to a function pointer. - /// // This avoids an integer-to-pointer `transmute`, which can be problematic. - /// // Transmuting between raw pointers and function pointers (i.e., two pointer types) is fine. - /// let pointer = foo as *const (); - /// let function = unsafe { - /// std::mem::transmute::<*const (), fn() -> i32>(pointer) - /// }; - /// assert_eq!(function(), 0); - /// ``` - /// - /// Extending a lifetime, or shortening an invariant lifetime. This is - /// advanced, very unsafe Rust! - /// - /// ``` - /// struct R<'a>(&'a i32); - /// unsafe fn extend_lifetime<'b>(r: R<'b>) -> R<'static> { - /// std::mem::transmute::, R<'static>>(r) - /// } - /// - /// unsafe fn shorten_invariant_lifetime<'b, 'c>(r: &'b mut R<'static>) - /// -> &'b mut R<'c> { - /// std::mem::transmute::<&'b mut R<'static>, &'b mut R<'c>>(r) - /// } - /// ``` - /// - /// # Alternatives - /// - /// Don't despair: many uses of `transmute` can be achieved through other means. - /// Below are common applications of `transmute` which can be replaced with safer - /// constructs. - /// - /// Turning raw bytes (`[u8; SZ]`) into `u32`, `f64`, etc.: - /// - /// ``` - /// let raw_bytes = [0x78, 0x56, 0x34, 0x12]; - /// - /// let num = unsafe { - /// std::mem::transmute::<[u8; 4], u32>(raw_bytes) - /// }; - /// - /// // use `u32::from_ne_bytes` instead - /// let num = u32::from_ne_bytes(raw_bytes); - /// // or use `u32::from_le_bytes` or `u32::from_be_bytes` to specify the endianness - /// let num = u32::from_le_bytes(raw_bytes); - /// assert_eq!(num, 0x12345678); - /// let num = u32::from_be_bytes(raw_bytes); - /// assert_eq!(num, 0x78563412); - /// ``` - /// - /// Turning a pointer into a `usize`: - /// - /// ```no_run - /// let ptr = &0; - /// let ptr_num_transmute = unsafe { - /// std::mem::transmute::<&i32, usize>(ptr) - /// }; - /// - /// // Use an `as` cast instead - /// let ptr_num_cast = ptr as *const i32 as usize; - /// ``` - /// - /// Note that using `transmute` to turn a pointer to a `usize` is (as noted above) [undefined - /// behavior][ub] in `const` contexts. Also outside of consts, this operation might not behave - /// as expected -- this is touching on many unspecified aspects of the Rust memory model. - /// Depending on what the code is doing, the following alternatives are preferable to - /// pointer-to-integer transmutation: - /// - If the code just wants to store data of arbitrary type in some buffer and needs to pick a - /// type for that buffer, it can use [`MaybeUninit`][crate::mem::MaybeUninit]. - /// - If the code actually wants to work on the address the pointer points to, it can use `as` - /// casts or [`ptr.addr()`][pointer::addr]. - /// - /// Turning a `*mut T` into an `&mut T`: - /// - /// ``` - /// let ptr: *mut i32 = &mut 0; - /// let ref_transmuted = unsafe { - /// std::mem::transmute::<*mut i32, &mut i32>(ptr) - /// }; - /// - /// // Use a reborrow instead - /// let ref_casted = unsafe { &mut *ptr }; - /// ``` - /// - /// Turning an `&mut T` into an `&mut U`: - /// - /// ``` - /// let ptr = &mut 0; - /// let val_transmuted = unsafe { - /// std::mem::transmute::<&mut i32, &mut u32>(ptr) - /// }; - /// - /// // Now, put together `as` and reborrowing - note the chaining of `as` - /// // `as` is not transitive - /// let val_casts = unsafe { &mut *(ptr as *mut i32 as *mut u32) }; - /// ``` - /// - /// Turning an `&str` into a `&[u8]`: - /// - /// ``` - /// // this is not a good way to do this. - /// let slice = unsafe { std::mem::transmute::<&str, &[u8]>("Rust") }; - /// assert_eq!(slice, &[82, 117, 115, 116]); - /// - /// // You could use `str::as_bytes` - /// let slice = "Rust".as_bytes(); - /// assert_eq!(slice, &[82, 117, 115, 116]); - /// - /// // Or, just use a byte string, if you have control over the string - /// // literal - /// assert_eq!(b"Rust", &[82, 117, 115, 116]); - /// ``` - /// - /// Turning a `Vec<&T>` into a `Vec>`. - /// - /// To transmute the inner type of the contents of a container, you must make sure to not - /// violate any of the container's invariants. For `Vec`, this means that both the size - /// *and alignment* of the inner types have to match. Other containers might rely on the - /// size of the type, alignment, or even the `TypeId`, in which case transmuting wouldn't - /// be possible at all without violating the container invariants. - /// - /// ``` - /// let store = [0, 1, 2, 3]; - /// let v_orig = store.iter().collect::>(); - /// - /// // clone the vector as we will reuse them later - /// let v_clone = v_orig.clone(); - /// - /// // Using transmute: this relies on the unspecified data layout of `Vec`, which is a - /// // bad idea and could cause Undefined Behavior. - /// // However, it is no-copy. - /// let v_transmuted = unsafe { - /// std::mem::transmute::, Vec>>(v_clone) - /// }; - /// - /// let v_clone = v_orig.clone(); - /// - /// // This is the suggested, safe way. - /// // It may copy the entire vector into a new one though, but also may not. - /// let v_collected = v_clone.into_iter() - /// .map(Some) - /// .collect::>>(); - /// - /// let v_clone = v_orig.clone(); - /// - /// // This is the proper no-copy, unsafe way of "transmuting" a `Vec`, without relying on the - /// // data layout. Instead of literally calling `transmute`, we perform a pointer cast, but - /// // in terms of converting the original inner type (`&i32`) to the new one (`Option<&i32>`), - /// // this has all the same caveats. Besides the information provided above, also consult the - /// // [`from_raw_parts`] documentation. - /// let v_from_raw = unsafe { - // FIXME Update this when vec_into_raw_parts is stabilized - /// // Ensure the original vector is not dropped. - /// let mut v_clone = std::mem::ManuallyDrop::new(v_clone); - /// Vec::from_raw_parts(v_clone.as_mut_ptr() as *mut Option<&i32>, - /// v_clone.len(), - /// v_clone.capacity()) - /// }; - /// ``` - /// - /// [`from_raw_parts`]: ../../std/vec/struct.Vec.html#method.from_raw_parts - /// - /// Implementing `split_at_mut`: - /// - /// ``` - /// use std::{slice, mem}; - /// - /// // There are multiple ways to do this, and there are multiple problems - /// // with the following (transmute) way. - /// fn split_at_mut_transmute(slice: &mut [T], mid: usize) - /// -> (&mut [T], &mut [T]) { - /// let len = slice.len(); - /// assert!(mid <= len); - /// unsafe { - /// let slice2 = mem::transmute::<&mut [T], &mut [T]>(slice); - /// // first: transmute is not type safe; all it checks is that T and - /// // U are of the same size. Second, right here, you have two - /// // mutable references pointing to the same memory. - /// (&mut slice[0..mid], &mut slice2[mid..len]) - /// } - /// } - /// - /// // This gets rid of the type safety problems; `&mut *` will *only* give - /// // you an `&mut T` from an `&mut T` or `*mut T`. - /// fn split_at_mut_casts(slice: &mut [T], mid: usize) - /// -> (&mut [T], &mut [T]) { - /// let len = slice.len(); - /// assert!(mid <= len); - /// unsafe { - /// let slice2 = &mut *(slice as *mut [T]); - /// // however, you still have two mutable references pointing to - /// // the same memory. - /// (&mut slice[0..mid], &mut slice2[mid..len]) - /// } - /// } - /// - /// // This is how the standard library does it. This is the best method, if - /// // you need to do something like this - /// fn split_at_stdlib(slice: &mut [T], mid: usize) - /// -> (&mut [T], &mut [T]) { - /// let len = slice.len(); - /// assert!(mid <= len); - /// unsafe { - /// let ptr = slice.as_mut_ptr(); - /// // This now has three mutable references pointing at the same - /// // memory. `slice`, the rvalue ret.0, and the rvalue ret.1. - /// // `slice` is never used after `let ptr = ...`, and so one can - /// // treat it as "dead", and therefore, you only have two real - /// // mutable slices. - /// (slice::from_raw_parts_mut(ptr, mid), - /// slice::from_raw_parts_mut(ptr.add(mid), len - mid)) - /// } - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_allowed_through_unstable_modules] - #[rustc_const_stable(feature = "const_transmute", since = "1.56.0")] - #[rustc_diagnostic_item = "transmute"] - #[rustc_nounwind] - pub fn transmute(src: Src) -> Dst; - - /// Like [`transmute`], but even less checked at compile-time: rather than - /// giving an error for `size_of::() != size_of::()`, it's - /// **Undefined Behaviour** at runtime. - /// - /// Prefer normal `transmute` where possible, for the extra checking, since - /// both do exactly the same thing at runtime, if they both compile. - /// - /// This is not expected to ever be exposed directly to users, rather it - /// may eventually be exposed through some more-constrained API. - #[rustc_const_stable(feature = "const_transmute", since = "1.56.0")] - #[rustc_nounwind] - pub fn transmute_unchecked(src: Src) -> Dst; - - /// Returns `true` if the actual type given as `T` requires drop - /// glue; returns `false` if the actual type provided for `T` - /// implements `Copy`. - /// - /// If the actual type neither requires drop glue nor implements - /// `Copy`, then the return value of this function is unspecified. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized version of this intrinsic is [`mem::needs_drop`](crate::mem::needs_drop). - #[rustc_const_stable(feature = "const_needs_drop", since = "1.40.0")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn needs_drop() -> bool; - - /// Calculates the offset from a pointer. - /// - /// This is implemented as an intrinsic to avoid converting to and from an - /// integer, since the conversion would throw away aliasing information. - /// - /// This can only be used with `Ptr` as a raw pointer type (`*mut` or `*const`) - /// to a `Sized` pointee and with `Delta` as `usize` or `isize`. Any other - /// instantiations may arbitrarily misbehave, and that's *not* a compiler bug. - /// - /// # Safety - /// - /// If the computed offset is non-zero, then both the starting and resulting pointer must be - /// either in bounds or at the end of an allocated object. If either pointer is out - /// of bounds or arithmetic overflow occurs then any further use of the returned value will - /// result in undefined behavior. - /// - /// The stabilized version of this intrinsic is [`pointer::offset`]. - #[must_use = "returns a new pointer rather than modifying its argument"] - #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")] - #[rustc_nounwind] - pub fn offset(dst: Ptr, offset: Delta) -> Ptr; - - /// Calculates the offset from a pointer, potentially wrapping. - /// - /// This is implemented as an intrinsic to avoid converting to and from an - /// integer, since the conversion inhibits certain optimizations. - /// - /// # Safety - /// - /// Unlike the `offset` intrinsic, this intrinsic does not restrict the - /// resulting pointer to point into or at the end of an allocated - /// object, and it wraps with two's complement arithmetic. The resulting - /// value is not necessarily valid to be used to actually access memory. - /// - /// The stabilized version of this intrinsic is [`pointer::wrapping_offset`]. - #[must_use = "returns a new pointer rather than modifying its argument"] - #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")] - #[rustc_nounwind] - pub fn arith_offset(dst: *const T, offset: isize) -> *const T; - - /// Masks out bits of the pointer according to a mask. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// Consider using [`pointer::mask`] instead. - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn ptr_mask(ptr: *const T, mask: usize) -> *const T; - - /// Equivalent to the appropriate `llvm.memcpy.p0i8.0i8.*` intrinsic, with - /// a size of `count` * `size_of::()` and an alignment of - /// `min_align_of::()` - /// - /// The volatile parameter is set to `true`, so it will not be optimized out - /// unless size is equal to zero. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - pub fn volatile_copy_nonoverlapping_memory(dst: *mut T, src: *const T, count: usize); - /// Equivalent to the appropriate `llvm.memmove.p0i8.0i8.*` intrinsic, with - /// a size of `count * size_of::()` and an alignment of - /// `min_align_of::()` - /// - /// The volatile parameter is set to `true`, so it will not be optimized out - /// unless size is equal to zero. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - pub fn volatile_copy_memory(dst: *mut T, src: *const T, count: usize); - /// Equivalent to the appropriate `llvm.memset.p0i8.*` intrinsic, with a - /// size of `count * size_of::()` and an alignment of - /// `min_align_of::()`. - /// - /// The volatile parameter is set to `true`, so it will not be optimized out - /// unless size is equal to zero. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - pub fn volatile_set_memory(dst: *mut T, val: u8, count: usize); - - /// Performs a volatile load from the `src` pointer. - /// - /// The stabilized version of this intrinsic is [`core::ptr::read_volatile`]. - #[rustc_nounwind] - pub fn volatile_load(src: *const T) -> T; - /// Performs a volatile store to the `dst` pointer. - /// - /// The stabilized version of this intrinsic is [`core::ptr::write_volatile`]. - #[rustc_nounwind] - pub fn volatile_store(dst: *mut T, val: T); - - /// Performs a volatile load from the `src` pointer - /// The pointer is not required to be aligned. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - #[rustc_diagnostic_item = "intrinsics_unaligned_volatile_load"] - pub fn unaligned_volatile_load(src: *const T) -> T; - /// Performs a volatile store to the `dst` pointer. - /// The pointer is not required to be aligned. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - #[rustc_diagnostic_item = "intrinsics_unaligned_volatile_store"] - pub fn unaligned_volatile_store(dst: *mut T, val: T); - - /// Returns the square root of an `f32` - /// - /// The stabilized version of this intrinsic is - /// [`f32::sqrt`](../../std/primitive.f32.html#method.sqrt) - #[rustc_nounwind] - pub fn sqrtf32(x: f32) -> f32; - /// Returns the square root of an `f64` - /// - /// The stabilized version of this intrinsic is - /// [`f64::sqrt`](../../std/primitive.f64.html#method.sqrt) - #[rustc_nounwind] - pub fn sqrtf64(x: f64) -> f64; - - /// Raises an `f16` to an integer power. - /// - /// The stabilized version of this intrinsic is - /// [`f16::powi`](../../std/primitive.f16.html#method.powi) - #[rustc_nounwind] - pub fn powif16(a: f16, x: i32) -> f16; - /// Raises an `f32` to an integer power. - /// - /// The stabilized version of this intrinsic is - /// [`f32::powi`](../../std/primitive.f32.html#method.powi) - #[rustc_nounwind] - pub fn powif32(a: f32, x: i32) -> f32; - /// Raises an `f64` to an integer power. - /// - /// The stabilized version of this intrinsic is - /// [`f64::powi`](../../std/primitive.f64.html#method.powi) - #[rustc_nounwind] - pub fn powif64(a: f64, x: i32) -> f64; - /// Raises an `f128` to an integer power. - /// - /// The stabilized version of this intrinsic is - /// [`f128::powi`](../../std/primitive.f128.html#method.powi) - #[rustc_nounwind] - pub fn powif128(a: f128, x: i32) -> f128; - - /// Returns the sine of an `f32`. - /// - /// The stabilized version of this intrinsic is - /// [`f32::sin`](../../std/primitive.f32.html#method.sin) - #[rustc_nounwind] - pub fn sinf32(x: f32) -> f32; - /// Returns the sine of an `f64`. - /// - /// The stabilized version of this intrinsic is - /// [`f64::sin`](../../std/primitive.f64.html#method.sin) - #[rustc_nounwind] - pub fn sinf64(x: f64) -> f64; - - /// Returns the cosine of an `f32`. - /// - /// The stabilized version of this intrinsic is - /// [`f32::cos`](../../std/primitive.f32.html#method.cos) - #[rustc_nounwind] - pub fn cosf32(x: f32) -> f32; - /// Returns the cosine of an `f64`. - /// - /// The stabilized version of this intrinsic is - /// [`f64::cos`](../../std/primitive.f64.html#method.cos) - #[rustc_nounwind] - pub fn cosf64(x: f64) -> f64; - - /// Raises an `f32` to an `f32` power. - /// - /// The stabilized version of this intrinsic is - /// [`f32::powf`](../../std/primitive.f32.html#method.powf) - #[rustc_nounwind] - pub fn powf32(a: f32, x: f32) -> f32; - /// Raises an `f64` to an `f64` power. - /// - /// The stabilized version of this intrinsic is - /// [`f64::powf`](../../std/primitive.f64.html#method.powf) - #[rustc_nounwind] - pub fn powf64(a: f64, x: f64) -> f64; - - /// Returns the exponential of an `f32`. - /// - /// The stabilized version of this intrinsic is - /// [`f32::exp`](../../std/primitive.f32.html#method.exp) - #[rustc_nounwind] - pub fn expf32(x: f32) -> f32; - /// Returns the exponential of an `f64`. - /// - /// The stabilized version of this intrinsic is - /// [`f64::exp`](../../std/primitive.f64.html#method.exp) - #[rustc_nounwind] - pub fn expf64(x: f64) -> f64; - - /// Returns 2 raised to the power of an `f32`. - /// - /// The stabilized version of this intrinsic is - /// [`f32::exp2`](../../std/primitive.f32.html#method.exp2) - #[rustc_nounwind] - pub fn exp2f32(x: f32) -> f32; - /// Returns 2 raised to the power of an `f64`. - /// - /// The stabilized version of this intrinsic is - /// [`f64::exp2`](../../std/primitive.f64.html#method.exp2) - #[rustc_nounwind] - pub fn exp2f64(x: f64) -> f64; - - /// Returns the natural logarithm of an `f32`. - /// - /// The stabilized version of this intrinsic is - /// [`f32::ln`](../../std/primitive.f32.html#method.ln) - #[rustc_nounwind] - pub fn logf32(x: f32) -> f32; - /// Returns the natural logarithm of an `f64`. - /// - /// The stabilized version of this intrinsic is - /// [`f64::ln`](../../std/primitive.f64.html#method.ln) - #[rustc_nounwind] - pub fn logf64(x: f64) -> f64; - - /// Returns the base 10 logarithm of an `f32`. - /// - /// The stabilized version of this intrinsic is - /// [`f32::log10`](../../std/primitive.f32.html#method.log10) - #[rustc_nounwind] - pub fn log10f32(x: f32) -> f32; - /// Returns the base 10 logarithm of an `f64`. - /// - /// The stabilized version of this intrinsic is - /// [`f64::log10`](../../std/primitive.f64.html#method.log10) - #[rustc_nounwind] - pub fn log10f64(x: f64) -> f64; - - /// Returns the base 2 logarithm of an `f32`. - /// - /// The stabilized version of this intrinsic is - /// [`f32::log2`](../../std/primitive.f32.html#method.log2) - #[rustc_nounwind] - pub fn log2f32(x: f32) -> f32; - /// Returns the base 2 logarithm of an `f64`. - /// - /// The stabilized version of this intrinsic is - /// [`f64::log2`](../../std/primitive.f64.html#method.log2) - #[rustc_nounwind] - pub fn log2f64(x: f64) -> f64; - - /// Returns `a * b + c` for `f32` values. - /// - /// The stabilized version of this intrinsic is - /// [`f32::mul_add`](../../std/primitive.f32.html#method.mul_add) - #[rustc_nounwind] - pub fn fmaf32(a: f32, b: f32, c: f32) -> f32; - /// Returns `a * b + c` for `f64` values. - /// - /// The stabilized version of this intrinsic is - /// [`f64::mul_add`](../../std/primitive.f64.html#method.mul_add) - #[rustc_nounwind] - pub fn fmaf64(a: f64, b: f64, c: f64) -> f64; - - /// Returns the absolute value of an `f32`. - /// - /// The stabilized version of this intrinsic is - /// [`f32::abs`](../../std/primitive.f32.html#method.abs) - #[rustc_nounwind] - pub fn fabsf32(x: f32) -> f32; - /// Returns the absolute value of an `f64`. - /// - /// The stabilized version of this intrinsic is - /// [`f64::abs`](../../std/primitive.f64.html#method.abs) - #[rustc_nounwind] - pub fn fabsf64(x: f64) -> f64; - - /// Returns the minimum of two `f32` values. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized version of this intrinsic is - /// [`f32::min`] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn minnumf32(x: f32, y: f32) -> f32; - /// Returns the minimum of two `f64` values. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized version of this intrinsic is - /// [`f64::min`] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn minnumf64(x: f64, y: f64) -> f64; - /// Returns the maximum of two `f32` values. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized version of this intrinsic is - /// [`f32::max`] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn maxnumf32(x: f32, y: f32) -> f32; - /// Returns the maximum of two `f64` values. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized version of this intrinsic is - /// [`f64::max`] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn maxnumf64(x: f64, y: f64) -> f64; - - /// Copies the sign from `y` to `x` for `f32` values. - /// - /// The stabilized version of this intrinsic is - /// [`f32::copysign`](../../std/primitive.f32.html#method.copysign) - #[rustc_nounwind] - pub fn copysignf32(x: f32, y: f32) -> f32; - /// Copies the sign from `y` to `x` for `f64` values. - /// - /// The stabilized version of this intrinsic is - /// [`f64::copysign`](../../std/primitive.f64.html#method.copysign) - #[rustc_nounwind] - pub fn copysignf64(x: f64, y: f64) -> f64; - - /// Returns the largest integer less than or equal to an `f32`. - /// - /// The stabilized version of this intrinsic is - /// [`f32::floor`](../../std/primitive.f32.html#method.floor) - #[rustc_nounwind] - pub fn floorf32(x: f32) -> f32; - /// Returns the largest integer less than or equal to an `f64`. - /// - /// The stabilized version of this intrinsic is - /// [`f64::floor`](../../std/primitive.f64.html#method.floor) - #[rustc_nounwind] - pub fn floorf64(x: f64) -> f64; - - /// Returns the smallest integer greater than or equal to an `f32`. - /// - /// The stabilized version of this intrinsic is - /// [`f32::ceil`](../../std/primitive.f32.html#method.ceil) - #[rustc_nounwind] - pub fn ceilf32(x: f32) -> f32; - /// Returns the smallest integer greater than or equal to an `f64`. - /// - /// The stabilized version of this intrinsic is - /// [`f64::ceil`](../../std/primitive.f64.html#method.ceil) - #[rustc_nounwind] - pub fn ceilf64(x: f64) -> f64; - - /// Returns the integer part of an `f32`. - /// - /// The stabilized version of this intrinsic is - /// [`f32::trunc`](../../std/primitive.f32.html#method.trunc) - #[rustc_nounwind] - pub fn truncf32(x: f32) -> f32; - /// Returns the integer part of an `f64`. - /// - /// The stabilized version of this intrinsic is - /// [`f64::trunc`](../../std/primitive.f64.html#method.trunc) - #[rustc_nounwind] - pub fn truncf64(x: f64) -> f64; - - /// Returns the nearest integer to an `f32`. Changing the rounding mode is not possible in Rust, - /// so this rounds half-way cases to the number with an even least significant digit. - /// - /// May raise an inexact floating-point exception if the argument is not an integer. - /// However, Rust assumes floating-point exceptions cannot be observed, so these exceptions - /// cannot actually be utilized from Rust code. - /// In other words, this intrinsic is equivalent in behavior to `nearbyintf32` and `roundevenf32`. - /// - /// The stabilized version of this intrinsic is - /// [`f32::round_ties_even`](../../std/primitive.f32.html#method.round_ties_even) - #[rustc_nounwind] - pub fn rintf32(x: f32) -> f32; - /// Returns the nearest integer to an `f64`. Changing the rounding mode is not possible in Rust, - /// so this rounds half-way cases to the number with an even least significant digit. - /// - /// May raise an inexact floating-point exception if the argument is not an integer. - /// However, Rust assumes floating-point exceptions cannot be observed, so these exceptions - /// cannot actually be utilized from Rust code. - /// In other words, this intrinsic is equivalent in behavior to `nearbyintf64` and `roundevenf64`. - /// - /// The stabilized version of this intrinsic is - /// [`f64::round_ties_even`](../../std/primitive.f64.html#method.round_ties_even) - #[rustc_nounwind] - pub fn rintf64(x: f64) -> f64; - - /// Returns the nearest integer to an `f32`. Changing the rounding mode is not possible in Rust, - /// so this rounds half-way cases to the number with an even least significant digit. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - pub fn nearbyintf32(x: f32) -> f32; - /// Returns the nearest integer to an `f64`. Changing the rounding mode is not possible in Rust, - /// so this rounds half-way cases to the number with an even least significant digit. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - pub fn nearbyintf64(x: f64) -> f64; - - /// Returns the nearest integer to an `f32`. Rounds half-way cases away from zero. - /// - /// The stabilized version of this intrinsic is - /// [`f32::round`](../../std/primitive.f32.html#method.round) - #[rustc_nounwind] - pub fn roundf32(x: f32) -> f32; - /// Returns the nearest integer to an `f64`. Rounds half-way cases away from zero. - /// - /// The stabilized version of this intrinsic is - /// [`f64::round`](../../std/primitive.f64.html#method.round) - #[rustc_nounwind] - pub fn roundf64(x: f64) -> f64; - - /// Returns the nearest integer to an `f32`. Rounds half-way cases to the number - /// with an even least significant digit. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - pub fn roundevenf32(x: f32) -> f32; - /// Returns the nearest integer to an `f64`. Rounds half-way cases to the number - /// with an even least significant digit. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - pub fn roundevenf64(x: f64) -> f64; - - /// Float addition that allows optimizations based on algebraic rules. - /// May assume inputs are finite. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - pub fn fadd_fast(a: T, b: T) -> T; - - /// Float subtraction that allows optimizations based on algebraic rules. - /// May assume inputs are finite. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - pub fn fsub_fast(a: T, b: T) -> T; - - /// Float multiplication that allows optimizations based on algebraic rules. - /// May assume inputs are finite. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - pub fn fmul_fast(a: T, b: T) -> T; - - /// Float division that allows optimizations based on algebraic rules. - /// May assume inputs are finite. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - pub fn fdiv_fast(a: T, b: T) -> T; - - /// Float remainder that allows optimizations based on algebraic rules. - /// May assume inputs are finite. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - pub fn frem_fast(a: T, b: T) -> T; - - /// Float addition that allows optimizations based on algebraic rules. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - #[rustc_safe_intrinsic] - pub fn fadd_algebraic(a: T, b: T) -> T; - - /// Float subtraction that allows optimizations based on algebraic rules. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - #[rustc_safe_intrinsic] - pub fn fsub_algebraic(a: T, b: T) -> T; - - /// Float multiplication that allows optimizations based on algebraic rules. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - #[rustc_safe_intrinsic] - pub fn fmul_algebraic(a: T, b: T) -> T; - - /// Float division that allows optimizations based on algebraic rules. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - #[rustc_safe_intrinsic] - pub fn fdiv_algebraic(a: T, b: T) -> T; - - /// Float remainder that allows optimizations based on algebraic rules. - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_nounwind] - #[rustc_safe_intrinsic] - pub fn frem_algebraic(a: T, b: T) -> T; - - /// Convert with LLVM’s fptoui/fptosi, which may return undef for values out of range - /// () - /// - /// Stabilized as [`f32::to_int_unchecked`] and [`f64::to_int_unchecked`]. - #[rustc_nounwind] - pub fn float_to_int_unchecked(value: Float) -> Int; - - /// Returns the number of bits set in an integer type `T` - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized versions of this intrinsic are available on the integer - /// primitives via the `count_ones` method. For example, - /// [`u32::count_ones`] - #[rustc_const_stable(feature = "const_ctpop", since = "1.40.0")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn ctpop(x: T) -> u32; - - /// Returns the number of leading unset bits (zeroes) in an integer type `T`. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized versions of this intrinsic are available on the integer - /// primitives via the `leading_zeros` method. For example, - /// [`u32::leading_zeros`] - /// - /// # Examples - /// - /// ``` - /// #![feature(core_intrinsics)] - /// # #![allow(internal_features)] - /// - /// use std::intrinsics::ctlz; - /// - /// let x = 0b0001_1100_u8; - /// let num_leading = ctlz(x); - /// assert_eq!(num_leading, 3); - /// ``` - /// - /// An `x` with value `0` will return the bit width of `T`. - /// - /// ``` - /// #![feature(core_intrinsics)] - /// # #![allow(internal_features)] - /// - /// use std::intrinsics::ctlz; - /// - /// let x = 0u16; - /// let num_leading = ctlz(x); - /// assert_eq!(num_leading, 16); - /// ``` - #[rustc_const_stable(feature = "const_ctlz", since = "1.40.0")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn ctlz(x: T) -> u32; - - /// Like `ctlz`, but extra-unsafe as it returns `undef` when - /// given an `x` with value `0`. - /// - /// This intrinsic does not have a stable counterpart. - /// - /// # Examples - /// - /// ``` - /// #![feature(core_intrinsics)] - /// # #![allow(internal_features)] - /// - /// use std::intrinsics::ctlz_nonzero; - /// - /// let x = 0b0001_1100_u8; - /// let num_leading = unsafe { ctlz_nonzero(x) }; - /// assert_eq!(num_leading, 3); - /// ``` - #[rustc_const_stable(feature = "constctlz", since = "1.50.0")] - #[rustc_nounwind] - pub fn ctlz_nonzero(x: T) -> u32; - - /// Returns the number of trailing unset bits (zeroes) in an integer type `T`. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized versions of this intrinsic are available on the integer - /// primitives via the `trailing_zeros` method. For example, - /// [`u32::trailing_zeros`] - /// - /// # Examples - /// - /// ``` - /// #![feature(core_intrinsics)] - /// # #![allow(internal_features)] - /// - /// use std::intrinsics::cttz; - /// - /// let x = 0b0011_1000_u8; - /// let num_trailing = cttz(x); - /// assert_eq!(num_trailing, 3); - /// ``` - /// - /// An `x` with value `0` will return the bit width of `T`: - /// - /// ``` - /// #![feature(core_intrinsics)] - /// # #![allow(internal_features)] - /// - /// use std::intrinsics::cttz; - /// - /// let x = 0u16; - /// let num_trailing = cttz(x); - /// assert_eq!(num_trailing, 16); - /// ``` - #[rustc_const_stable(feature = "const_cttz", since = "1.40.0")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn cttz(x: T) -> u32; - - /// Like `cttz`, but extra-unsafe as it returns `undef` when - /// given an `x` with value `0`. - /// - /// This intrinsic does not have a stable counterpart. - /// - /// # Examples - /// - /// ``` - /// #![feature(core_intrinsics)] - /// # #![allow(internal_features)] - /// - /// use std::intrinsics::cttz_nonzero; - /// - /// let x = 0b0011_1000_u8; - /// let num_trailing = unsafe { cttz_nonzero(x) }; - /// assert_eq!(num_trailing, 3); - /// ``` - #[rustc_const_stable(feature = "const_cttz_nonzero", since = "1.53.0")] - #[rustc_nounwind] - pub fn cttz_nonzero(x: T) -> u32; - - /// Reverses the bytes in an integer type `T`. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized versions of this intrinsic are available on the integer - /// primitives via the `swap_bytes` method. For example, - /// [`u32::swap_bytes`] - #[rustc_const_stable(feature = "const_bswap", since = "1.40.0")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn bswap(x: T) -> T; - - /// Reverses the bits in an integer type `T`. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized versions of this intrinsic are available on the integer - /// primitives via the `reverse_bits` method. For example, - /// [`u32::reverse_bits`] - #[rustc_const_stable(feature = "const_bitreverse", since = "1.40.0")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn bitreverse(x: T) -> T; - - /// Does a three-way comparison between the two integer arguments. - /// - /// This is included as an intrinsic as it's useful to let it be one thing - /// in MIR, rather than the multiple checks and switches that make its IR - /// large and difficult to optimize. - /// - /// The stabilized version of this intrinsic is [`Ord::cmp`]. - #[rustc_const_unstable(feature = "const_three_way_compare", issue = "none")] - #[rustc_safe_intrinsic] - pub fn three_way_compare(lhs: T, rhs: T) -> crate::cmp::Ordering; - - /// Performs checked integer addition. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized versions of this intrinsic are available on the integer - /// primitives via the `overflowing_add` method. For example, - /// [`u32::overflowing_add`] - #[rustc_const_stable(feature = "const_int_overflow", since = "1.40.0")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn add_with_overflow(x: T, y: T) -> (T, bool); - - /// Performs checked integer subtraction - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized versions of this intrinsic are available on the integer - /// primitives via the `overflowing_sub` method. For example, - /// [`u32::overflowing_sub`] - #[rustc_const_stable(feature = "const_int_overflow", since = "1.40.0")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn sub_with_overflow(x: T, y: T) -> (T, bool); - - /// Performs checked integer multiplication - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized versions of this intrinsic are available on the integer - /// primitives via the `overflowing_mul` method. For example, - /// [`u32::overflowing_mul`] - #[rustc_const_stable(feature = "const_int_overflow", since = "1.40.0")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn mul_with_overflow(x: T, y: T) -> (T, bool); - - /// Performs an exact division, resulting in undefined behavior where - /// `x % y != 0` or `y == 0` or `x == T::MIN && y == -1` - /// - /// This intrinsic does not have a stable counterpart. - #[rustc_const_unstable(feature = "const_exact_div", issue = "none")] - #[rustc_nounwind] - pub fn exact_div(x: T, y: T) -> T; - - /// Performs an unchecked division, resulting in undefined behavior - /// where `y == 0` or `x == T::MIN && y == -1` - /// - /// Safe wrappers for this intrinsic are available on the integer - /// primitives via the `checked_div` method. For example, - /// [`u32::checked_div`] - #[rustc_const_stable(feature = "const_int_unchecked_div", since = "1.52.0")] - #[rustc_nounwind] - pub fn unchecked_div(x: T, y: T) -> T; - /// Returns the remainder of an unchecked division, resulting in - /// undefined behavior when `y == 0` or `x == T::MIN && y == -1` - /// - /// Safe wrappers for this intrinsic are available on the integer - /// primitives via the `checked_rem` method. For example, - /// [`u32::checked_rem`] - #[rustc_const_stable(feature = "const_int_unchecked_rem", since = "1.52.0")] - #[rustc_nounwind] - pub fn unchecked_rem(x: T, y: T) -> T; - - /// Performs an unchecked left shift, resulting in undefined behavior when - /// `y < 0` or `y >= N`, where N is the width of T in bits. - /// - /// Safe wrappers for this intrinsic are available on the integer - /// primitives via the `checked_shl` method. For example, - /// [`u32::checked_shl`] - #[rustc_const_stable(feature = "const_int_unchecked", since = "1.40.0")] - #[rustc_nounwind] - pub fn unchecked_shl(x: T, y: U) -> T; - /// Performs an unchecked right shift, resulting in undefined behavior when - /// `y < 0` or `y >= N`, where N is the width of T in bits. - /// - /// Safe wrappers for this intrinsic are available on the integer - /// primitives via the `checked_shr` method. For example, - /// [`u32::checked_shr`] - #[rustc_const_stable(feature = "const_int_unchecked", since = "1.40.0")] - #[rustc_nounwind] - pub fn unchecked_shr(x: T, y: U) -> T; - - /// Returns the result of an unchecked addition, resulting in - /// undefined behavior when `x + y > T::MAX` or `x + y < T::MIN`. - /// - /// The stable counterpart of this intrinsic is `unchecked_add` on the various - /// integer types, such as [`u16::unchecked_add`] and [`i64::unchecked_add`]. - #[rustc_const_stable(feature = "unchecked_math", since = "1.79.0")] - #[rustc_nounwind] - pub fn unchecked_add(x: T, y: T) -> T; - - /// Returns the result of an unchecked subtraction, resulting in - /// undefined behavior when `x - y > T::MAX` or `x - y < T::MIN`. - /// - /// The stable counterpart of this intrinsic is `unchecked_sub` on the various - /// integer types, such as [`u16::unchecked_sub`] and [`i64::unchecked_sub`]. - #[rustc_const_stable(feature = "unchecked_math", since = "1.79.0")] - #[rustc_nounwind] - pub fn unchecked_sub(x: T, y: T) -> T; - - /// Returns the result of an unchecked multiplication, resulting in - /// undefined behavior when `x * y > T::MAX` or `x * y < T::MIN`. - /// - /// The stable counterpart of this intrinsic is `unchecked_mul` on the various - /// integer types, such as [`u16::unchecked_mul`] and [`i64::unchecked_mul`]. - #[rustc_const_stable(feature = "unchecked_math", since = "1.79.0")] - #[rustc_nounwind] - pub fn unchecked_mul(x: T, y: T) -> T; - - /// Performs rotate left. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized versions of this intrinsic are available on the integer - /// primitives via the `rotate_left` method. For example, - /// [`u32::rotate_left`] - #[rustc_const_stable(feature = "const_int_rotate", since = "1.40.0")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn rotate_left(x: T, shift: u32) -> T; - - /// Performs rotate right. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized versions of this intrinsic are available on the integer - /// primitives via the `rotate_right` method. For example, - /// [`u32::rotate_right`] - #[rustc_const_stable(feature = "const_int_rotate", since = "1.40.0")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn rotate_right(x: T, shift: u32) -> T; - - /// Returns (a + b) mod 2N, where N is the width of T in bits. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized versions of this intrinsic are available on the integer - /// primitives via the `wrapping_add` method. For example, - /// [`u32::wrapping_add`] - #[rustc_const_stable(feature = "const_int_wrapping", since = "1.40.0")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn wrapping_add(a: T, b: T) -> T; - /// Returns (a - b) mod 2N, where N is the width of T in bits. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized versions of this intrinsic are available on the integer - /// primitives via the `wrapping_sub` method. For example, - /// [`u32::wrapping_sub`] - #[rustc_const_stable(feature = "const_int_wrapping", since = "1.40.0")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn wrapping_sub(a: T, b: T) -> T; - /// Returns (a * b) mod 2N, where N is the width of T in bits. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized versions of this intrinsic are available on the integer - /// primitives via the `wrapping_mul` method. For example, - /// [`u32::wrapping_mul`] - #[rustc_const_stable(feature = "const_int_wrapping", since = "1.40.0")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn wrapping_mul(a: T, b: T) -> T; - - /// Computes `a + b`, saturating at numeric bounds. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized versions of this intrinsic are available on the integer - /// primitives via the `saturating_add` method. For example, - /// [`u32::saturating_add`] - #[rustc_const_stable(feature = "const_int_saturating", since = "1.40.0")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn saturating_add(a: T, b: T) -> T; - /// Computes `a - b`, saturating at numeric bounds. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized versions of this intrinsic are available on the integer - /// primitives via the `saturating_sub` method. For example, - /// [`u32::saturating_sub`] - #[rustc_const_stable(feature = "const_int_saturating", since = "1.40.0")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn saturating_sub(a: T, b: T) -> T; - - /// This is an implementation detail of [`crate::ptr::read`] and should - /// not be used anywhere else. See its comments for why this exists. - /// - /// This intrinsic can *only* be called where the pointer is a local without - /// projections (`read_via_copy(ptr)`, not `read_via_copy(*ptr)`) so that it - /// trivially obeys runtime-MIR rules about derefs in operands. - #[rustc_const_stable(feature = "const_ptr_read", since = "1.71.0")] - #[rustc_nounwind] - pub fn read_via_copy(ptr: *const T) -> T; - - /// This is an implementation detail of [`crate::ptr::write`] and should - /// not be used anywhere else. See its comments for why this exists. - /// - /// This intrinsic can *only* be called where the pointer is a local without - /// projections (`write_via_move(ptr, x)`, not `write_via_move(*ptr, x)`) so - /// that it trivially obeys runtime-MIR rules about derefs in operands. - #[rustc_const_unstable(feature = "const_ptr_write", issue = "86302")] - #[rustc_nounwind] - pub fn write_via_move(ptr: *mut T, value: T); - - /// Returns the value of the discriminant for the variant in 'v'; - /// if `T` has no discriminant, returns `0`. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The stabilized version of this intrinsic is [`core::mem::discriminant`]. - #[rustc_const_stable(feature = "const_discriminant", since = "1.75.0")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn discriminant_value(v: &T) -> ::Discriminant; - - /// Returns the number of variants of the type `T` cast to a `usize`; - /// if `T` has no variants, returns `0`. Uninhabited variants will be counted. - /// - /// Note that, unlike most intrinsics, this is safe to call; - /// it does not require an `unsafe` block. - /// Therefore, implementations must not require the user to uphold - /// any safety invariants. - /// - /// The to-be-stabilized version of this intrinsic is [`crate::mem::variant_count`]. - #[rustc_const_unstable(feature = "variant_count", issue = "73662")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn variant_count() -> usize; - - /// Rust's "try catch" construct for unwinding. Invokes the function pointer `try_fn` with the - /// data pointer `data`, and calls `catch_fn` if unwinding occurs while `try_fn` runs. - /// - /// `catch_fn` must not unwind. - /// - /// The third argument is a function called if an unwind occurs (both Rust unwinds and foreign - /// unwinds). This function takes the data pointer and a pointer to the target-specific - /// exception object that was caught. For more information, see the compiler's source as well as - /// std's `catch_unwind` implementation. - /// - /// The stable version of this intrinsic is `std::panic::catch_unwind`. - #[rustc_nounwind] - pub fn catch_unwind(try_fn: fn(*mut u8), data: *mut u8, catch_fn: fn(*mut u8, *mut u8)) -> i32; - - /// Emits a `!nontemporal` store according to LLVM (see their docs). - /// Probably will never become stable. - /// - /// Do NOT use this intrinsic; "nontemporal" operations do not exist in our memory model! - /// It exists to support current stdarch, but the plan is to change stdarch and remove this intrinsic. - /// See for some more discussion. - #[rustc_nounwind] - pub fn nontemporal_store(ptr: *mut T, val: T); - - /// See documentation of `<*const T>::offset_from` for details. - #[rustc_const_stable(feature = "const_ptr_offset_from", since = "1.65.0")] - #[rustc_nounwind] - pub fn ptr_offset_from(ptr: *const T, base: *const T) -> isize; - - /// See documentation of `<*const T>::sub_ptr` for details. - #[rustc_const_unstable(feature = "const_ptr_sub_ptr", issue = "95892")] - #[rustc_nounwind] - pub fn ptr_offset_from_unsigned(ptr: *const T, base: *const T) -> usize; -} - -/// See documentation of `<*const T>::guaranteed_eq` for details. -/// Returns `2` if the result is unknown. -/// Returns `1` if the pointers are guaranteed equal -/// Returns `0` if the pointers are guaranteed inequal -#[rustc_const_unstable(feature = "const_raw_ptr_comparison", issue = "53020")] -#[unstable(feature = "core_intrinsics", issue = "none")] -#[rustc_intrinsic] -#[rustc_nounwind] -#[rustc_do_not_const_check] -#[inline] -#[cfg_attr(not(bootstrap), miri::intrinsic_fallback_is_spec)] -pub const fn ptr_guaranteed_cmp(ptr: *const T, other: *const T) -> u8 { - (ptr == other) as u8 -} - -extern "rust-intrinsic" { - /// Determines whether the raw bytes of the two values are equal. - /// - /// This is particularly handy for arrays, since it allows things like just - /// comparing `i96`s instead of forcing `alloca`s for `[6 x i16]`. - /// - /// Above some backend-decided threshold this will emit calls to `memcmp`, - /// like slice equality does, instead of causing massive code size. - /// - /// Since this works by comparing the underlying bytes, the actual `T` is - /// not particularly important. It will be used for its size and alignment, - /// but any validity restrictions will be ignored, not enforced. - /// - /// # Safety - /// - /// It's UB to call this if any of the *bytes* in `*a` or `*b` are uninitialized or carry a - /// pointer value. - /// Note that this is a stricter criterion than just the *values* being - /// fully-initialized: if `T` has padding, it's UB to call this intrinsic. - /// - /// (The implementation is allowed to branch on the results of comparisons, - /// which is UB if any of their inputs are `undef`.) - #[rustc_const_unstable(feature = "const_intrinsic_raw_eq", issue = "none")] - #[rustc_nounwind] - pub fn raw_eq(a: &T, b: &T) -> bool; - - /// Lexicographically compare `[left, left + bytes)` and `[right, right + bytes)` - /// as unsigned bytes, returning negative if `left` is less, zero if all the - /// bytes match, or positive if `right` is greater. - /// - /// This underlies things like `<[u8]>::cmp`, and will usually lower to `memcmp`. - /// - /// # Safety - /// - /// `left` and `right` must each be [valid] for reads of `bytes` bytes. - /// - /// Note that this applies to the whole range, not just until the first byte - /// that differs. That allows optimizations that can read in large chunks. - /// - /// [valid]: crate::ptr#safety - #[rustc_const_unstable(feature = "const_intrinsic_compare_bytes", issue = "none")] - #[rustc_nounwind] - pub fn compare_bytes(left: *const u8, right: *const u8, bytes: usize) -> i32; - - /// See documentation of [`std::hint::black_box`] for details. - /// - /// [`std::hint::black_box`]: crate::hint::black_box - #[rustc_const_unstable(feature = "const_black_box", issue = "none")] - #[rustc_safe_intrinsic] - #[rustc_nounwind] - pub fn black_box(dummy: T) -> T; -} - -/// Selects which function to call depending on the context. -/// -/// If this function is evaluated at compile-time, then a call to this -/// intrinsic will be replaced with a call to `called_in_const`. It gets -/// replaced with a call to `called_at_rt` otherwise. -/// -/// This function is safe to call, but note the stability concerns below. -/// -/// # Type Requirements -/// -/// The two functions must be both function items. They cannot be function -/// pointers or closures. The first function must be a `const fn`. -/// -/// `arg` will be the tupled arguments that will be passed to either one of -/// the two functions, therefore, both functions must accept the same type of -/// arguments. Both functions must return RET. -/// -/// # Stability concerns -/// -/// Rust has not yet decided that `const fn` are allowed to tell whether -/// they run at compile-time or at runtime. Therefore, when using this -/// intrinsic anywhere that can be reached from stable, it is crucial that -/// the end-to-end behavior of the stable `const fn` is the same for both -/// modes of execution. (Here, Undefined Behavior is considered "the same" -/// as any other behavior, so if the function exhibits UB at runtime then -/// it may do whatever it wants at compile-time.) -/// -/// Here is an example of how this could cause a problem: -/// ```no_run -/// #![feature(const_eval_select)] -/// #![feature(core_intrinsics)] -/// # #![allow(internal_features)] -/// use std::intrinsics::const_eval_select; -/// -/// // Standard library -/// pub const fn inconsistent() -> i32 { -/// fn runtime() -> i32 { 1 } -/// const fn compiletime() -> i32 { 2 } -/// -// // ⚠ This code violates the required equivalence of `compiletime` -/// // and `runtime`. -/// const_eval_select((), compiletime, runtime) -/// } -/// -/// // User Crate -/// const X: i32 = inconsistent(); -/// let x = inconsistent(); -/// assert_eq!(x, X); -/// ``` -/// -/// Currently such an assertion would always succeed; until Rust decides -/// otherwise, that principle should not be violated. -#[rustc_const_unstable(feature = "const_eval_select", issue = "124625")] -#[rustc_intrinsic] -#[rustc_intrinsic_must_be_overridden] -pub const fn const_eval_select( - _arg: ARG, - _called_in_const: F, - _called_at_rt: G, -) -> RET -where - G: FnOnce, - F: FnOnce, -{ - unreachable!() -} - -/// Returns whether the argument's value is statically known at -/// compile-time. -/// -/// This is useful when there is a way of writing the code that will -/// be *faster* when some variables have known values, but *slower* -/// in the general case: an `if is_val_statically_known(var)` can be used -/// to select between these two variants. The `if` will be optimized away -/// and only the desired branch remains. -/// -/// Formally speaking, this function non-deterministically returns `true` -/// or `false`, and the caller has to ensure sound behavior for both cases. -/// In other words, the following code has *Undefined Behavior*: -/// -/// ```no_run -/// #![feature(is_val_statically_known)] -/// #![feature(core_intrinsics)] -/// # #![allow(internal_features)] -/// use std::hint::unreachable_unchecked; -/// use std::intrinsics::is_val_statically_known; -/// -/// if !is_val_statically_known(0) { unsafe { unreachable_unchecked(); } } -/// ``` -/// -/// This also means that the following code's behavior is unspecified; it -/// may panic, or it may not: -/// -/// ```no_run -/// #![feature(is_val_statically_known)] -/// #![feature(core_intrinsics)] -/// # #![allow(internal_features)] -/// use std::intrinsics::is_val_statically_known; -/// -/// assert_eq!(is_val_statically_known(0), is_val_statically_known(0)); -/// ``` -/// -/// Unsafe code may not rely on `is_val_statically_known` returning any -/// particular value, ever. However, the compiler will generally make it -/// return `true` only if the value of the argument is actually known. -/// -/// # Stability concerns -/// -/// While it is safe to call, this intrinsic may behave differently in -/// a `const` context than otherwise. See the [`const_eval_select`] -/// documentation for an explanation of the issues this can cause. Unlike -/// `const_eval_select`, this intrinsic isn't guaranteed to behave -/// deterministically even in a `const` context. -/// -/// # Type Requirements -/// -/// `T` must be either a `bool`, a `char`, a primitive numeric type (e.g. `f32`, -/// but not `NonZeroISize`), or any thin pointer (e.g. `*mut String`). -/// Any other argument types *may* cause a compiler error. -/// -/// ## Pointers -/// -/// When the input is a pointer, only the pointer itself is -/// ever considered. The pointee has no effect. Currently, these functions -/// behave identically: -/// -/// ``` -/// #![feature(is_val_statically_known)] -/// #![feature(core_intrinsics)] -/// # #![allow(internal_features)] -/// #![feature(strict_provenance)] -/// use std::intrinsics::is_val_statically_known; -/// -/// fn foo(x: &i32) -> bool { -/// is_val_statically_known(x) -/// } -/// -/// fn bar(x: &i32) -> bool { -/// is_val_statically_known( -/// (x as *const i32).addr() -/// ) -/// } -/// # _ = foo(&5_i32); -/// # _ = bar(&5_i32); -/// ``` -#[rustc_const_unstable(feature = "is_val_statically_known", issue = "none")] -#[rustc_nounwind] -#[unstable(feature = "core_intrinsics", issue = "none")] -#[rustc_intrinsic] -pub const fn is_val_statically_known(_arg: T) -> bool { - false -} - -/// Non-overlapping *typed* swap of a single value. -/// -/// The codegen backends will replace this with a better implementation when -/// `T` is a simple type that can be loaded and stored as an immediate. -/// -/// The stabilized form of this intrinsic is [`crate::mem::swap`]. -/// -/// # Safety -/// -/// `x` and `y` are readable and writable as `T`, and non-overlapping. -#[rustc_nounwind] -#[inline] -#[rustc_intrinsic] -// This has fallback `const fn` MIR, so shouldn't need stability, see #122652 -#[rustc_const_unstable(feature = "const_typed_swap", issue = "none")] -#[cfg_attr(kani, kani::modifies(x))] -#[cfg_attr(kani, kani::modifies(y))] -#[requires(ub_checks::can_dereference(x) && ub_checks::can_write(x))] -#[requires(ub_checks::can_dereference(y) && ub_checks::can_write(y))] -#[requires(x.addr() != y.addr() || core::mem::size_of::() == 0)] -#[requires((x.addr() >= y.addr() + core::mem::size_of::()) || (y.addr() >= x.addr() + core::mem::size_of::()))] -pub const unsafe fn typed_swap(x: *mut T, y: *mut T) { - // SAFETY: The caller provided single non-overlapping items behind - // pointers, so swapping them with `count: 1` is fine. - unsafe { ptr::swap_nonoverlapping(x, y, 1) }; -} - -/// Returns whether we should perform some UB-checking at runtime. This eventually evaluates to -/// `cfg!(ub_checks)`, but behaves different from `cfg!` when mixing crates built with different -/// flags: if the crate has UB checks enabled or carries the `#[rustc_preserve_ub_checks]` -/// attribute, evaluation is delayed until monomorphization (or until the call gets inlined into -/// a crate that does not delay evaluation further); otherwise it can happen any time. -/// -/// The common case here is a user program built with ub_checks linked against the distributed -/// sysroot which is built without ub_checks but with `#[rustc_preserve_ub_checks]`. -/// For code that gets monomorphized in the user crate (i.e., generic functions and functions with -/// `#[inline]`), gating assertions on `ub_checks()` rather than `cfg!(ub_checks)` means that -/// assertions are enabled whenever the *user crate* has UB checks enabled. However if the -/// user has UB checks disabled, the checks will still get optimized out. This intrinsic is -/// primarily used by [`ub_checks::assert_unsafe_precondition`]. -#[rustc_const_unstable(feature = "const_ub_checks", issue = "none")] -#[unstable(feature = "core_intrinsics", issue = "none")] -#[inline(always)] -#[rustc_intrinsic] -pub const fn ub_checks() -> bool { - cfg!(debug_assertions) -} - -/// Allocates a block of memory at compile time. -/// At runtime, just returns a null pointer. -/// -/// # Safety -/// -/// - The `align` argument must be a power of two. -/// - At compile time, a compile error occurs if this constraint is violated. -/// - At runtime, it is not checked. -#[rustc_const_unstable(feature = "const_heap", issue = "79597")] -#[unstable(feature = "core_intrinsics", issue = "none")] -#[rustc_nounwind] -#[rustc_intrinsic] -#[cfg_attr(not(bootstrap), miri::intrinsic_fallback_is_spec)] -pub const unsafe fn const_allocate(_size: usize, _align: usize) -> *mut u8 { - // const eval overrides this function, but runtime code for now just returns null pointers. - // See . - crate::ptr::null_mut() -} - -/// Deallocates a memory which allocated by `intrinsics::const_allocate` at compile time. -/// At runtime, does nothing. -/// -/// # Safety -/// -/// - The `align` argument must be a power of two. -/// - At compile time, a compile error occurs if this constraint is violated. -/// - At runtime, it is not checked. -/// - If the `ptr` is created in an another const, this intrinsic doesn't deallocate it. -/// - If the `ptr` is pointing to a local variable, this intrinsic doesn't deallocate it. -#[rustc_const_unstable(feature = "const_heap", issue = "79597")] -#[unstable(feature = "core_intrinsics", issue = "none")] -#[rustc_nounwind] -#[rustc_intrinsic] -#[cfg_attr(not(bootstrap), miri::intrinsic_fallback_is_spec)] -pub const unsafe fn const_deallocate(_ptr: *mut u8, _size: usize, _align: usize) { - // Runtime NOP -} - -/// `ptr` must point to a vtable. -/// The intrinsic will return the size stored in that vtable. -#[rustc_nounwind] -#[unstable(feature = "core_intrinsics", issue = "none")] -#[rustc_intrinsic] -#[rustc_intrinsic_must_be_overridden] -pub unsafe fn vtable_size(_ptr: *const ()) -> usize { - unreachable!() -} - -/// `ptr` must point to a vtable. -/// The intrinsic will return the alignment stored in that vtable. -#[rustc_nounwind] -#[unstable(feature = "core_intrinsics", issue = "none")] -#[rustc_intrinsic] -#[rustc_intrinsic_must_be_overridden] -pub unsafe fn vtable_align(_ptr: *const ()) -> usize { - unreachable!() -} - -/// Lowers in MIR to `Rvalue::Aggregate` with `AggregateKind::RawPtr`. -/// -/// This is used to implement functions like `slice::from_raw_parts_mut` and -/// `ptr::from_raw_parts` in a way compatible with the compiler being able to -/// change the possible layouts of pointers. -#[rustc_nounwind] -#[unstable(feature = "core_intrinsics", issue = "none")] -#[rustc_const_unstable(feature = "ptr_metadata", issue = "81513")] -#[rustc_intrinsic] -#[rustc_intrinsic_must_be_overridden] -pub const fn aggregate_raw_ptr, D, M>(_data: D, _meta: M) -> P { - // To implement a fallback we'd have to assume the layout of the pointer, - // but the whole point of this intrinsic is that we shouldn't do that. - unreachable!() -} - -#[unstable(feature = "core_intrinsics", issue = "none")] -pub trait AggregateRawPtr { - type Metadata: Copy; -} -impl AggregateRawPtr<*const T> for *const P { - type Metadata =

::Metadata; -} -impl AggregateRawPtr<*mut T> for *mut P { - type Metadata =

::Metadata; -} - -// Some functions are defined here because they accidentally got made -// available in this module on stable. See . -// (`transmute` also falls into this category, but it cannot be wrapped due to the -// check that `T` and `U` have the same size.) - -/// Copies `count * size_of::()` bytes from `src` to `dst`. The source -/// and destination must *not* overlap. -/// -/// For regions of memory which might overlap, use [`copy`] instead. -/// -/// `copy_nonoverlapping` is semantically equivalent to C's [`memcpy`], but -/// with the argument order swapped. -/// -/// The copy is "untyped" in the sense that data may be uninitialized or otherwise violate the -/// requirements of `T`. The initialization state is preserved exactly. -/// -/// [`memcpy`]: https://en.cppreference.com/w/c/string/byte/memcpy -/// -/// # Safety -/// -/// Behavior is undefined if any of the following conditions are violated: -/// -/// * `src` must be [valid] for reads of `count * size_of::()` bytes. -/// -/// * `dst` must be [valid] for writes of `count * size_of::()` bytes. -/// -/// * Both `src` and `dst` must be properly aligned. -/// -/// * The region of memory beginning at `src` with a size of `count * -/// size_of::()` bytes must *not* overlap with the region of memory -/// beginning at `dst` with the same size. -/// -/// Like [`read`], `copy_nonoverlapping` creates a bitwise copy of `T`, regardless of -/// whether `T` is [`Copy`]. If `T` is not [`Copy`], using *both* the values -/// in the region beginning at `*src` and the region beginning at `*dst` can -/// [violate memory safety][read-ownership]. -/// -/// Note that even if the effectively copied size (`count * size_of::()`) is -/// `0`, the pointers must be non-null and properly aligned. -/// -/// [`read`]: crate::ptr::read -/// [read-ownership]: crate::ptr::read#ownership-of-the-returned-value -/// [valid]: crate::ptr#safety -/// -/// # Examples -/// -/// Manually implement [`Vec::append`]: -/// -/// ``` -/// use std::ptr; -/// -/// /// Moves all the elements of `src` into `dst`, leaving `src` empty. -/// fn append(dst: &mut Vec, src: &mut Vec) { -/// let src_len = src.len(); -/// let dst_len = dst.len(); -/// -/// // Ensure that `dst` has enough capacity to hold all of `src`. -/// dst.reserve(src_len); -/// -/// unsafe { -/// // The call to add is always safe because `Vec` will never -/// // allocate more than `isize::MAX` bytes. -/// let dst_ptr = dst.as_mut_ptr().add(dst_len); -/// let src_ptr = src.as_ptr(); -/// -/// // Truncate `src` without dropping its contents. We do this first, -/// // to avoid problems in case something further down panics. -/// src.set_len(0); -/// -/// // The two regions cannot overlap because mutable references do -/// // not alias, and two different vectors cannot own the same -/// // memory. -/// ptr::copy_nonoverlapping(src_ptr, dst_ptr, src_len); -/// -/// // Notify `dst` that it now holds the contents of `src`. -/// dst.set_len(dst_len + src_len); -/// } -/// } -/// -/// let mut a = vec!['r']; -/// let mut b = vec!['u', 's', 't']; -/// -/// append(&mut a, &mut b); -/// -/// assert_eq!(a, &['r', 'u', 's', 't']); -/// assert!(b.is_empty()); -/// ``` -/// -/// [`Vec::append`]: ../../std/vec/struct.Vec.html#method.append -#[doc(alias = "memcpy")] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_allowed_through_unstable_modules] -#[rustc_const_unstable(feature = "const_intrinsic_copy", issue = "80697")] -#[inline(always)] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -#[rustc_diagnostic_item = "ptr_copy_nonoverlapping"] -pub const unsafe fn copy_nonoverlapping(src: *const T, dst: *mut T, count: usize) { - extern "rust-intrinsic" { - #[rustc_const_unstable(feature = "const_intrinsic_copy", issue = "80697")] - #[rustc_nounwind] - pub fn copy_nonoverlapping(src: *const T, dst: *mut T, count: usize); - } - - ub_checks::assert_unsafe_precondition!( - check_language_ub, - "ptr::copy_nonoverlapping requires that both pointer arguments are aligned and non-null \ - and the specified memory ranges do not overlap", - ( - src: *const () = src as *const (), - dst: *mut () = dst as *mut (), - size: usize = size_of::(), - align: usize = align_of::(), - count: usize = count, - ) => - ub_checks::is_aligned_and_not_null(src, align) - && ub_checks::is_aligned_and_not_null(dst, align) - && ub_checks::is_nonoverlapping(src, dst, size, count) - ); - - // SAFETY: the safety contract for `copy_nonoverlapping` must be - // upheld by the caller. - unsafe { copy_nonoverlapping(src, dst, count) } -} - -/// Copies `count * size_of::()` bytes from `src` to `dst`. The source -/// and destination may overlap. -/// -/// If the source and destination will *never* overlap, -/// [`copy_nonoverlapping`] can be used instead. -/// -/// `copy` is semantically equivalent to C's [`memmove`], but with the argument -/// order swapped. Copying takes place as if the bytes were copied from `src` -/// to a temporary array and then copied from the array to `dst`. -/// -/// The copy is "untyped" in the sense that data may be uninitialized or otherwise violate the -/// requirements of `T`. The initialization state is preserved exactly. -/// -/// [`memmove`]: https://en.cppreference.com/w/c/string/byte/memmove -/// -/// # Safety -/// -/// Behavior is undefined if any of the following conditions are violated: -/// -/// * `src` must be [valid] for reads of `count * size_of::()` bytes, and must remain valid even -/// when `dst` is written for `count * size_of::()` bytes. (This means if the memory ranges -/// overlap, the two pointers must not be subject to aliasing restrictions relative to each -/// other.) -/// -/// * `dst` must be [valid] for writes of `count * size_of::()` bytes, and must remain valid even -/// when `src` is read for `count * size_of::()` bytes. -/// -/// * Both `src` and `dst` must be properly aligned. -/// -/// Like [`read`], `copy` creates a bitwise copy of `T`, regardless of -/// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the values -/// in the region beginning at `*src` and the region beginning at `*dst` can -/// [violate memory safety][read-ownership]. -/// -/// Note that even if the effectively copied size (`count * size_of::()`) is -/// `0`, the pointers must be non-null and properly aligned. -/// -/// [`read`]: crate::ptr::read -/// [read-ownership]: crate::ptr::read#ownership-of-the-returned-value -/// [valid]: crate::ptr#safety -/// -/// # Examples -/// -/// Efficiently create a Rust vector from an unsafe buffer: -/// -/// ``` -/// use std::ptr; -/// -/// /// # Safety -/// /// -/// /// * `ptr` must be correctly aligned for its type and non-zero. -/// /// * `ptr` must be valid for reads of `elts` contiguous elements of type `T`. -/// /// * Those elements must not be used after calling this function unless `T: Copy`. -/// # #[allow(dead_code)] -/// unsafe fn from_buf_raw(ptr: *const T, elts: usize) -> Vec { -/// let mut dst = Vec::with_capacity(elts); -/// -/// // SAFETY: Our precondition ensures the source is aligned and valid, -/// // and `Vec::with_capacity` ensures that we have usable space to write them. -/// ptr::copy(ptr, dst.as_mut_ptr(), elts); -/// -/// // SAFETY: We created it with this much capacity earlier, -/// // and the previous `copy` has initialized these elements. -/// dst.set_len(elts); -/// dst -/// } -/// ``` -#[doc(alias = "memmove")] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_allowed_through_unstable_modules] -#[rustc_const_unstable(feature = "const_intrinsic_copy", issue = "80697")] -#[inline(always)] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -#[rustc_diagnostic_item = "ptr_copy"] -pub const unsafe fn copy(src: *const T, dst: *mut T, count: usize) { - extern "rust-intrinsic" { - #[rustc_const_unstable(feature = "const_intrinsic_copy", issue = "80697")] - #[rustc_nounwind] - fn copy(src: *const T, dst: *mut T, count: usize); - } - - // SAFETY: the safety contract for `copy` must be upheld by the caller. - unsafe { - ub_checks::assert_unsafe_precondition!( - check_language_ub, - "ptr::copy_nonoverlapping requires that both pointer arguments are aligned and non-null \ - and the specified memory ranges do not overlap", - ( - src: *const () = src as *const (), - dst: *mut () = dst as *mut (), - align: usize = align_of::(), - ) => - ub_checks::is_aligned_and_not_null(src, align) - && ub_checks::is_aligned_and_not_null(dst, align) - ); - copy(src, dst, count) - } -} - -/// Sets `count * size_of::()` bytes of memory starting at `dst` to -/// `val`. -/// -/// `write_bytes` is similar to C's [`memset`], but sets `count * -/// size_of::()` bytes to `val`. -/// -/// [`memset`]: https://en.cppreference.com/w/c/string/byte/memset -/// -/// # Safety -/// -/// Behavior is undefined if any of the following conditions are violated: -/// -/// * `dst` must be [valid] for writes of `count * size_of::()` bytes. -/// -/// * `dst` must be properly aligned. -/// -/// Note that even if the effectively copied size (`count * size_of::()`) is -/// `0`, the pointer must be non-null and properly aligned. -/// -/// Additionally, note that changing `*dst` in this way can easily lead to undefined behavior (UB) -/// later if the written bytes are not a valid representation of some `T`. For instance, the -/// following is an **incorrect** use of this function: -/// -/// ```rust,no_run -/// unsafe { -/// let mut value: u8 = 0; -/// let ptr: *mut bool = &mut value as *mut u8 as *mut bool; -/// let _bool = ptr.read(); // This is fine, `ptr` points to a valid `bool`. -/// ptr.write_bytes(42u8, 1); // This function itself does not cause UB... -/// let _bool = ptr.read(); // ...but it makes this operation UB! ⚠️ -/// } -/// ``` -/// -/// [valid]: crate::ptr#safety -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// use std::ptr; -/// -/// let mut vec = vec![0u32; 4]; -/// unsafe { -/// let vec_ptr = vec.as_mut_ptr(); -/// ptr::write_bytes(vec_ptr, 0xfe, 2); -/// } -/// assert_eq!(vec, [0xfefefefe, 0xfefefefe, 0, 0]); -/// ``` -#[doc(alias = "memset")] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_allowed_through_unstable_modules] -#[rustc_const_unstable(feature = "const_ptr_write", issue = "86302")] -#[inline(always)] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -#[rustc_diagnostic_item = "ptr_write_bytes"] -pub const unsafe fn write_bytes(dst: *mut T, val: u8, count: usize) { - extern "rust-intrinsic" { - #[rustc_const_unstable(feature = "const_ptr_write", issue = "86302")] - #[rustc_nounwind] - fn write_bytes(dst: *mut T, val: u8, count: usize); - } - - // SAFETY: the safety contract for `write_bytes` must be upheld by the caller. - unsafe { - ub_checks::assert_unsafe_precondition!( - check_language_ub, - "ptr::write_bytes requires that the destination pointer is aligned and non-null", - ( - addr: *const () = dst as *const (), - align: usize = align_of::(), - ) => ub_checks::is_aligned_and_not_null(addr, align) - ); - write_bytes(dst, val, count) - } -} - -/// Inform Miri that a given pointer definitely has a certain alignment. -#[cfg(miri)] -pub(crate) const fn miri_promise_symbolic_alignment(ptr: *const (), align: usize) { - extern "Rust" { - /// Miri-provided extern function to promise that a given pointer is properly aligned for - /// "symbolic" alignment checks. Will fail if the pointer is not actually aligned or `align` is - /// not a power of two. Has no effect when alignment checks are concrete (which is the default). - fn miri_promise_symbolic_alignment(ptr: *const (), align: usize); - } - - fn runtime(ptr: *const (), align: usize) { - // SAFETY: this call is always safe. - unsafe { - miri_promise_symbolic_alignment(ptr, align); - } - } - - const fn compiletime(_ptr: *const (), _align: usize) {} - - const_eval_select((ptr, align), compiletime, runtime); -} - -#[cfg(kani)] -#[unstable(feature="kani", issue="none")] -mod verify { - use core::{cmp, fmt}; - use super::*; - use crate::kani; - - #[kani::proof_for_contract(typed_swap)] - pub fn check_typed_swap_u8() { - check_swap::() - } - - #[kani::proof_for_contract(typed_swap)] - pub fn check_typed_swap_char() { - check_swap::() - } - - #[kani::proof_for_contract(typed_swap)] - pub fn check_typed_swap_non_zero() { - check_swap::() - } - - pub fn check_swap() { - let mut x = kani::any::(); - let old_x = x; - let mut y = kani::any::(); - let old_y = y; - - unsafe { typed_swap(&mut x, &mut y) }; - assert_eq!(y, old_x); - assert_eq!(x, old_y); - } -} diff --git a/library/core/src/intrinsics/mir.rs b/library/core/src/intrinsics/mir.rs deleted file mode 100644 index 02665b2676cc1..0000000000000 --- a/library/core/src/intrinsics/mir.rs +++ /dev/null @@ -1,679 +0,0 @@ -//! Rustc internal tooling for hand-writing MIR. -//! -//! If for some reasons you are not writing rustc tests and have found yourself considering using -//! this feature, turn back. This is *exceptionally* unstable. There is no attempt at all to make -//! anything work besides those things which the rustc test suite happened to need. If you make a -//! typo you'll probably ICE. Really, this is not the solution to your problems. Consider instead -//! supporting the [stable MIR project group](https://github.com/rust-lang/project-stable-mir). -//! -//! The documentation for this module describes how to use this feature. If you are interested in -//! hacking on the implementation, most of that documentation lives at -//! `rustc_mir_build/src/build/custom/mod.rs`. -//! -//! Typical usage will look like this: -//! -//! ```rust -//! #![feature(core_intrinsics, custom_mir)] -//! #![allow(internal_features)] -//! -//! use core::intrinsics::mir::*; -//! -//! #[custom_mir(dialect = "built")] -//! pub fn simple(x: i32) -> i32 { -//! mir!( -//! let temp2: i32; -//! -//! { -//! let temp1 = x; -//! Goto(my_second_block) -//! } -//! -//! my_second_block = { -//! temp2 = Move(temp1); -//! RET = temp2; -//! Return() -//! } -//! ) -//! } -//! ``` -//! -//! The `custom_mir` attribute tells the compiler to treat the function as being custom MIR. This -//! attribute only works on functions - there is no way to insert custom MIR into the middle of -//! another function. The `dialect` and `phase` parameters indicate which [version of MIR][dialect -//! docs] you are inserting here. Generally you'll want to use `#![custom_mir(dialect = "built")]` -//! if you want your MIR to be modified by the full MIR pipeline, or `#![custom_mir(dialect = -//! "runtime", phase = "optimized")]` if you don't. -//! -//! [dialect docs]: -//! https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/enum.MirPhase.html -//! -//! The input to the [`mir!`] macro is: -//! -//! - An optional return type annotation in the form of `type RET = ...;`. This may be required -//! if the compiler cannot infer the type of RET. -//! - A possibly empty list of local declarations. Locals can also be declared inline on -//! assignments via `let`. Type inference generally works. Shadowing does not. -//! - A list of basic blocks. The first of these is the start block and is where execution begins. -//! All blocks other than the start block need to be given a name, so that they can be referred -//! to later. -//! - Each block is a list of semicolon terminated statements, followed by a terminator. The -//! syntax for the various statements and terminators is designed to be as similar as possible -//! to the syntax for analogous concepts in native Rust. See below for a list. -//! -//! # Examples -//! -//! ```rust -//! #![feature(core_intrinsics, custom_mir)] -//! #![allow(internal_features)] -//! #![allow(unused_assignments)] -//! -//! use core::intrinsics::mir::*; -//! -//! #[custom_mir(dialect = "built")] -//! pub fn choose_load(a: &i32, b: &i32, c: bool) -> i32 { -//! mir!( -//! { -//! match c { -//! true => t, -//! _ => f, -//! } -//! } -//! -//! t = { -//! let temp = a; -//! Goto(load_and_exit) -//! } -//! -//! f = { -//! temp = b; -//! Goto(load_and_exit) -//! } -//! -//! load_and_exit = { -//! RET = *temp; -//! Return() -//! } -//! ) -//! } -//! -//! #[custom_mir(dialect = "built")] -//! fn unwrap_unchecked(opt: Option) -> T { -//! mir!({ -//! RET = Move(Field(Variant(opt, 1), 0)); -//! Return() -//! }) -//! } -//! -//! #[custom_mir(dialect = "runtime", phase = "optimized")] -//! fn push_and_pop(v: &mut Vec, value: T) { -//! mir!( -//! let _unused; -//! let popped; -//! -//! { -//! Call(_unused = Vec::push(v, value), ReturnTo(pop), UnwindContinue()) -//! } -//! -//! pop = { -//! Call(popped = Vec::pop(v), ReturnTo(drop), UnwindContinue()) -//! } -//! -//! drop = { -//! Drop(popped, ReturnTo(ret), UnwindContinue()) -//! } -//! -//! ret = { -//! Return() -//! } -//! ) -//! } -//! -//! #[custom_mir(dialect = "runtime", phase = "optimized")] -//! fn annotated_return_type() -> (i32, bool) { -//! mir!( -//! type RET = (i32, bool); -//! { -//! RET.0 = 1; -//! RET.1 = true; -//! Return() -//! } -//! ) -//! } -//! ``` -//! -//! We can also set off compilation failures that happen in sufficiently late stages of the -//! compiler: -//! -//! ```rust,compile_fail -//! #![feature(core_intrinsics, custom_mir)] -//! -//! extern crate core; -//! use core::intrinsics::mir::*; -//! -//! #[custom_mir(dialect = "built")] -//! fn borrow_error(should_init: bool) -> i32 { -//! mir!( -//! let temp: i32; -//! -//! { -//! match should_init { -//! true => init, -//! _ => use_temp, -//! } -//! } -//! -//! init = { -//! temp = 0; -//! Goto(use_temp) -//! } -//! -//! use_temp = { -//! RET = temp; -//! Return() -//! } -//! ) -//! } -//! ``` -//! -//! ```text -//! error[E0381]: used binding is possibly-uninitialized -//! --> test.rs:24:13 -//! | -//! 8 | / mir!( -//! 9 | | let temp: i32; -//! 10 | | -//! 11 | | { -//! ... | -//! 19 | | temp = 0; -//! | | -------- binding initialized here in some conditions -//! ... | -//! 24 | | RET = temp; -//! | | ^^^^^^^^^^ value used here but it is possibly-uninitialized -//! 25 | | Return() -//! 26 | | } -//! 27 | | ) -//! | |_____- binding declared here but left uninitialized -//! -//! error: aborting due to 1 previous error -//! -//! For more information about this error, try `rustc --explain E0381`. -//! ``` -//! -//! # Syntax -//! -//! The lists below are an exhaustive description of how various MIR constructs can be created. -//! Anything missing from the list should be assumed to not be supported, PRs welcome. -//! -//! #### Locals -//! -//! - The `_0` return local can always be accessed via `RET`. -//! - Arguments can be accessed via their regular name. -//! - All other locals need to be declared with `let` somewhere and then can be accessed by name. -//! -//! #### Places -//! - Locals implicit convert to places. -//! - Field accesses, derefs, and indexing work normally. -//! - Fields in variants can be accessed via the [`Variant`] and [`Field`] associated functions, -//! see their documentation for details. -//! -//! #### Operands -//! - Places implicitly convert to `Copy` operands. -//! - `Move` operands can be created via [`Move`]. -//! - Const blocks, literals, named constants, and const params all just work. -//! - [`Static`] and [`StaticMut`] can be used to create `&T` and `*mut T`s to statics. These are -//! constants in MIR and the only way to access statics. -//! -//! #### Statements -//! - Assign statements work via normal Rust assignment. -//! - [`Retag`], [`StorageLive`], [`StorageDead`], [`Deinit`] statements have an associated function. -//! -//! #### Rvalues -//! -//! - Operands implicitly convert to `Use` rvalues. -//! - `&`, `&mut`, `addr_of!`, and `addr_of_mut!` all work to create their associated rvalue. -//! - [`Discriminant`], [`Len`], and [`CopyForDeref`] have associated functions. -//! - Unary and binary operations use their normal Rust syntax - `a * b`, `!c`, etc. -//! - The binary operation `Offset` can be created via [`Offset`]. -//! - Checked binary operations are represented by wrapping the associated binop in [`Checked`]. -//! - Array repetition syntax (`[foo; 10]`) creates the associated rvalue. -//! -//! #### Terminators -//! -//! - [`Goto`], [`Return`], [`Unreachable`] and [`Drop`](Drop()) have associated functions. -//! - `match some_int_operand` becomes a `SwitchInt`. Each arm should be `literal => basic_block` -//! - The exception is the last arm, which must be `_ => basic_block` and corresponds to the -//! otherwise branch. -//! - [`Call`] has an associated function as well, with special syntax: -//! `Call(ret_val = function(arg1, arg2, ...), ReturnTo(next_block), UnwindContinue())`. - -#![unstable( - feature = "custom_mir", - reason = "MIR is an implementation detail and extremely unstable", - issue = "none" -)] -#![allow(unused_variables, non_snake_case, missing_debug_implementations)] - -/// Type representing basic blocks. -/// -/// All terminators will have this type as a return type. It helps achieve some type safety. -#[rustc_diagnostic_item = "mir_basic_block"] -pub enum BasicBlock { - /// A non-cleanup basic block. - Normal, - /// A basic block that lies on an unwind path. - Cleanup, -} - -/// The reason we are terminating the process during unwinding. -#[rustc_diagnostic_item = "mir_unwind_terminate_reason"] -pub enum UnwindTerminateReason { - /// Unwinding is just not possible given the ABI of this function. - Abi, - /// We were already cleaning up for an ongoing unwind, and a *second*, *nested* unwind was - /// triggered by the drop glue. - InCleanup, -} - -pub use UnwindTerminateReason::Abi as ReasonAbi; -pub use UnwindTerminateReason::InCleanup as ReasonInCleanup; - -macro_rules! define { - ($name:literal, $( #[ $meta:meta ] )* fn $($sig:tt)*) => { - #[rustc_diagnostic_item = $name] - #[inline] - $( #[ $meta ] )* - pub fn $($sig)* { panic!() } - } -} - -// Unwind actions -pub struct UnwindActionArg; -define!( - "mir_unwind_continue", - /// An unwind action that continues unwinding. - fn UnwindContinue() -> UnwindActionArg -); -define!( - "mir_unwind_unreachable", - /// An unwind action that triggers undefined behaviour. - fn UnwindUnreachable() -> UnwindActionArg -); -define!( - "mir_unwind_terminate", - /// An unwind action that terminates the execution. - /// - /// `UnwindTerminate` can also be used as a terminator. - fn UnwindTerminate(reason: UnwindTerminateReason) -> UnwindActionArg -); -define!( - "mir_unwind_cleanup", - /// An unwind action that continues execution in a given basic blok. - fn UnwindCleanup(goto: BasicBlock) -> UnwindActionArg -); - -// Return destination for `Call` -pub struct ReturnToArg; -define!("mir_return_to", fn ReturnTo(goto: BasicBlock) -> ReturnToArg); - -// Terminators -define!("mir_return", fn Return() -> BasicBlock); -define!("mir_goto", fn Goto(destination: BasicBlock) -> BasicBlock); -define!("mir_unreachable", fn Unreachable() -> BasicBlock); -define!("mir_drop", - /// Drop the contents of a place. - /// - /// The first argument must be a place. - /// - /// The second argument must be of the form `ReturnTo(bb)`, where `bb` is the basic block that - /// will be jumped to after the destructor returns. - /// - /// The third argument describes what happens on unwind. It can be one of: - /// - [`UnwindContinue`] - /// - [`UnwindUnreachable`] - /// - [`UnwindTerminate`] - /// - [`UnwindCleanup`] - fn Drop(place: T, goto: ReturnToArg, unwind_action: UnwindActionArg) -); -define!("mir_call", - /// Call a function. - /// - /// The first argument must be of the form `ret_val = fun(arg1, arg2, ...)`. - /// - /// The second argument must be of the form `ReturnTo(bb)`, where `bb` is the basic block that - /// will be jumped to after the function returns. - /// - /// The third argument describes what happens on unwind. It can be one of: - /// - [`UnwindContinue`] - /// - [`UnwindUnreachable`] - /// - [`UnwindTerminate`] - /// - [`UnwindCleanup`] - fn Call(call: (), goto: ReturnToArg, unwind_action: UnwindActionArg) -); -define!("mir_unwind_resume", - /// A terminator that resumes the unwinding. - fn UnwindResume() -); - -define!("mir_storage_live", fn StorageLive(local: T)); -define!("mir_storage_dead", fn StorageDead(local: T)); -define!("mir_assume", fn Assume(operand: bool)); -define!("mir_deinit", fn Deinit(place: T)); -define!("mir_checked", fn Checked(binop: T) -> (T, bool)); -define!("mir_len", fn Len(place: T) -> usize); -define!("mir_copy_for_deref", fn CopyForDeref(place: T) -> T); -define!("mir_retag", fn Retag(place: T)); -define!("mir_move", fn Move(place: T) -> T); -define!("mir_static", fn Static(s: T) -> &'static T); -define!("mir_static_mut", fn StaticMut(s: T) -> *mut T); -define!( - "mir_discriminant", - /// Gets the discriminant of a place. - fn Discriminant(place: T) -> ::Discriminant -); -define!("mir_set_discriminant", fn SetDiscriminant(place: T, index: u32)); -define!("mir_offset", fn Offset(ptr: T, count: U) -> T); -define!( - "mir_field", - /// Access the field with the given index of some place. - /// - /// This only makes sense to use in conjunction with [`Variant`]. If the type you are looking to - /// access the field of does not have variants, you can use normal field projection syntax. - /// - /// There is no proper way to do a place projection to a variant in Rust, and so these two - /// functions are a workaround. You can access a field of a variant via `Field(Variant(place, - /// var_idx), field_idx)`, where `var_idx` and `field_idx` are appropriate literals. Some - /// caveats: - /// - /// - The return type of `Variant` is always `()`. Don't worry about that, the correct MIR will - /// still be generated. - /// - In some situations, the return type of `Field` cannot be inferred. You may need to - /// annotate it on the function in these cases. - /// - Since `Field` is a function call which is not a place expression, using this on the left - /// hand side of an expression is rejected by the compiler. [`place!`] is a macro provided to - /// work around that issue. Wrap the left hand side of an assignment in the macro to convince - /// the compiler that it's ok. - /// - /// # Examples - /// - /// ```rust - /// #![allow(internal_features)] - /// #![feature(custom_mir, core_intrinsics)] - /// - /// use core::intrinsics::mir::*; - /// - /// #[custom_mir(dialect = "built")] - /// fn unwrap_deref(opt: Option<&i32>) -> i32 { - /// mir!({ - /// RET = *Field::<&i32>(Variant(opt, 1), 0); - /// Return() - /// }) - /// } - /// - /// #[custom_mir(dialect = "built")] - /// fn set(opt: &mut Option) { - /// mir!({ - /// place!(Field(Variant(*opt, 1), 0)) = 5; - /// Return() - /// }) - /// } - /// ``` - fn Field(place: (), field: u32) -> F -); -define!( - "mir_variant", - /// Adds a variant projection with the given index to the place. - /// - /// See [`Field`] for documentation. - fn Variant(place: T, index: u32) -> () -); -define!( - "mir_cast_transmute", - /// Emits a `CastKind::Transmute` cast. - /// - /// Needed to test the UB when `sizeof(T) != sizeof(U)`, which can't be - /// generated via the normal `mem::transmute`. - fn CastTransmute(operand: T) -> U -); -define!( - "mir_make_place", - #[doc(hidden)] - fn __internal_make_place(place: T) -> *mut T -); -define!( - "mir_debuginfo", - #[doc(hidden)] - fn __debuginfo(name: &'static str, s: T) -); - -/// Macro for generating custom MIR. -/// -/// See the module documentation for syntax details. This macro is not magic - it only transforms -/// your MIR into something that is easier to parse in the compiler. -#[rustc_macro_transparency = "transparent"] -pub macro mir { - ( - $(type RET = $ret_ty:ty ;)? - $(let $local_decl:ident $(: $local_decl_ty:ty)? ;)* - $(debug $dbg_name:ident => $dbg_data:expr ;)* - - { - $($entry:tt)* - } - - $( - $block_name:ident $(($block_cleanup:ident))? = { - $($block:tt)* - } - )* - ) => {{ - // First, we declare all basic blocks. - __internal_declare_basic_blocks!($( - $block_name $(($block_cleanup))? - )*); - { - // Now all locals - #[allow(non_snake_case)] - let RET $(: $ret_ty)?; - $( - let $local_decl $(: $local_decl_ty)? ; - )* - ::core::intrinsics::mir::__internal_extract_let!($($entry)*); - $( - ::core::intrinsics::mir::__internal_extract_let!($($block)*); - )* - - { - // Now debuginfo - $( - __debuginfo(stringify!($dbg_name), $dbg_data); - )* - - { - // Finally, the contents of the basic blocks - ::core::intrinsics::mir::__internal_remove_let!({ - {} - { $($entry)* } - }); - $( - ::core::intrinsics::mir::__internal_remove_let!({ - {} - { $($block)* } - }); - )* - - RET - } - } - } - }} -} - -/// Helper macro that allows you to treat a value expression like a place expression. -/// -/// See the documentation on [`Variant`] for why this is necessary and how to use it. -pub macro place($e:expr) { - (*::core::intrinsics::mir::__internal_make_place($e)) -} - -/// Helper macro that extracts the `let` declarations out of a bunch of statements. -/// -/// This macro is written using the "statement muncher" strategy. Each invocation parses the first -/// statement out of the input, does the appropriate thing with it, and then recursively calls the -/// same macro on the remainder of the input. -#[doc(hidden)] -pub macro __internal_extract_let { - // If it's a `let` like statement, keep the `let` - ( - let $var:ident $(: $ty:ty)? = $expr:expr; $($rest:tt)* - ) => { - let $var $(: $ty)?; - ::core::intrinsics::mir::__internal_extract_let!($($rest)*); - }, - // Due to #86730, we have to handle const blocks separately - ( - let $var:ident $(: $ty:ty)? = const $block:block; $($rest:tt)* - ) => { - let $var $(: $ty)?; - ::core::intrinsics::mir::__internal_extract_let!($($rest)*); - }, - // Otherwise, output nothing - ( - $stmt:stmt; $($rest:tt)* - ) => { - ::core::intrinsics::mir::__internal_extract_let!($($rest)*); - }, - ( - $expr:expr - ) => {} -} - -/// Helper macro that removes the `let` declarations from a bunch of statements. -/// -/// Because expression position macros cannot expand to statements + expressions, we need to be -/// slightly creative here. The general strategy is also statement munching as above, but the output -/// of the macro is "stored" in the subsequent macro invocation. Easiest understood via example: -/// ```text -/// invoke!( -/// { -/// { -/// x = 5; -/// } -/// { -/// let d = e; -/// Call() -/// } -/// } -/// ) -/// ``` -/// becomes -/// ```text -/// invoke!( -/// { -/// { -/// x = 5; -/// d = e; -/// } -/// { -/// Call() -/// } -/// } -/// ) -/// ``` -#[doc(hidden)] -pub macro __internal_remove_let { - // If it's a `let` like statement, remove the `let` - ( - { - { - $($already_parsed:tt)* - } - { - let $var:ident $(: $ty:ty)? = $expr:expr; - $($rest:tt)* - } - } - ) => { ::core::intrinsics::mir::__internal_remove_let!( - { - { - $($already_parsed)* - $var = $expr; - } - { - $($rest)* - } - } - )}, - // Due to #86730 , we have to handle const blocks separately - ( - { - { - $($already_parsed:tt)* - } - { - let $var:ident $(: $ty:ty)? = const $block:block; - $($rest:tt)* - } - } - ) => { ::core::intrinsics::mir::__internal_remove_let!( - { - { - $($already_parsed)* - $var = const $block; - } - { - $($rest)* - } - } - )}, - // Otherwise, keep going - ( - { - { - $($already_parsed:tt)* - } - { - $stmt:stmt; - $($rest:tt)* - } - } - ) => { ::core::intrinsics::mir::__internal_remove_let!( - { - { - $($already_parsed)* - $stmt; - } - { - $($rest)* - } - } - )}, - ( - { - { - $($already_parsed:tt)* - } - { - $expr:expr - } - } - ) => { - { - $($already_parsed)* - $expr - } - }, -} - -/// Helper macro that declares the basic blocks. -#[doc(hidden)] -pub macro __internal_declare_basic_blocks { - () => {}, - ($name:ident (cleanup) $($rest:tt)*) => { - let $name = ::core::intrinsics::mir::BasicBlock::Cleanup; - __internal_declare_basic_blocks!($($rest)*) - }, - ($name:ident $($rest:tt)*) => { - let $name = ::core::intrinsics::mir::BasicBlock::Normal; - __internal_declare_basic_blocks!($($rest)*) - }, -} diff --git a/library/core/src/intrinsics/simd.rs b/library/core/src/intrinsics/simd.rs deleted file mode 100644 index d1be534eaf083..0000000000000 --- a/library/core/src/intrinsics/simd.rs +++ /dev/null @@ -1,664 +0,0 @@ -//! SIMD compiler intrinsics. -//! -//! In this module, a "vector" is any `repr(simd)` type. - -extern "rust-intrinsic" { - /// Insert an element into a vector, returning the updated vector. - /// - /// `T` must be a vector with element type `U`. - /// - /// # Safety - /// - /// `idx` must be in-bounds of the vector. - #[rustc_nounwind] - pub fn simd_insert(x: T, idx: u32, val: U) -> T; - - /// Extract an element from a vector. - /// - /// `T` must be a vector with element type `U`. - /// - /// # Safety - /// - /// `idx` must be in-bounds of the vector. - #[rustc_nounwind] - pub fn simd_extract(x: T, idx: u32) -> U; - - /// Add two simd vectors elementwise. - /// - /// `T` must be a vector of integer or floating point primitive types. - #[rustc_nounwind] - pub fn simd_add(x: T, y: T) -> T; - - /// Subtract `rhs` from `lhs` elementwise. - /// - /// `T` must be a vector of integer or floating point primitive types. - #[rustc_nounwind] - pub fn simd_sub(lhs: T, rhs: T) -> T; - - /// Multiply two simd vectors elementwise. - /// - /// `T` must be a vector of integer or floating point primitive types. - #[rustc_nounwind] - pub fn simd_mul(x: T, y: T) -> T; - - /// Divide `lhs` by `rhs` elementwise. - /// - /// `T` must be a vector of integer or floating point primitive types. - /// - /// # Safety - /// For integers, `rhs` must not contain any zero elements. - /// Additionally for signed integers, `::MIN / -1` is undefined behavior. - #[rustc_nounwind] - pub fn simd_div(lhs: T, rhs: T) -> T; - - /// Remainder of two vectors elementwise - /// - /// `T` must be a vector of integer or floating point primitive types. - /// - /// # Safety - /// For integers, `rhs` must not contain any zero elements. - /// Additionally for signed integers, `::MIN / -1` is undefined behavior. - #[rustc_nounwind] - pub fn simd_rem(lhs: T, rhs: T) -> T; - - /// Elementwise vector left shift, with UB on overflow. - /// - /// Shift `lhs` left by `rhs`, shifting in sign bits for signed types. - /// - /// `T` must be a vector of integer primitive types. - /// - /// # Safety - /// - /// Each element of `rhs` must be less than `::BITS`. - #[rustc_nounwind] - pub fn simd_shl(lhs: T, rhs: T) -> T; - - /// Elementwise vector right shift, with UB on overflow. - /// - /// `T` must be a vector of integer primitive types. - /// - /// Shift `lhs` right by `rhs`, shifting in sign bits for signed types. - /// - /// # Safety - /// - /// Each element of `rhs` must be less than `::BITS`. - #[rustc_nounwind] - pub fn simd_shr(lhs: T, rhs: T) -> T; - - /// Elementwise vector "and". - /// - /// `T` must be a vector of integer primitive types. - #[rustc_nounwind] - pub fn simd_and(x: T, y: T) -> T; - - /// Elementwise vector "or". - /// - /// `T` must be a vector of integer primitive types. - #[rustc_nounwind] - pub fn simd_or(x: T, y: T) -> T; - - /// Elementwise vector "exclusive or". - /// - /// `T` must be a vector of integer primitive types. - #[rustc_nounwind] - pub fn simd_xor(x: T, y: T) -> T; - - /// Numerically cast a vector, elementwise. - /// - /// `T` and `U` must be vectors of integer or floating point primitive types, and must have the - /// same length. - /// - /// When casting floats to integers, the result is truncated. Out-of-bounds result lead to UB. - /// When casting integers to floats, the result is rounded. - /// Otherwise, truncates or extends the value, maintaining the sign for signed integers. - /// - /// # Safety - /// Casting from integer types is always safe. - /// Casting between two float types is also always safe. - /// - /// Casting floats to integers truncates, following the same rules as `to_int_unchecked`. - /// Specifically, each element must: - /// * Not be `NaN` - /// * Not be infinite - /// * Be representable in the return type, after truncating off its fractional part - #[rustc_nounwind] - pub fn simd_cast(x: T) -> U; - - /// Numerically cast a vector, elementwise. - /// - /// `T` and `U` be a vectors of integer or floating point primitive types, and must have the - /// same length. - /// - /// Like `simd_cast`, but saturates float-to-integer conversions (NaN becomes 0). - /// This matches regular `as` and is always safe. - /// - /// When casting floats to integers, the result is truncated. - /// When casting integers to floats, the result is rounded. - /// Otherwise, truncates or extends the value, maintaining the sign for signed integers. - #[rustc_nounwind] - pub fn simd_as(x: T) -> U; - - /// Elementwise negation of a vector. - /// - /// `T` must be a vector of integer or floating-point primitive types. - /// - /// Rust panics for `-::Min` due to overflow, but it is not UB with this intrinsic. - #[rustc_nounwind] - pub fn simd_neg(x: T) -> T; - - /// Elementwise absolute value of a vector. - /// - /// `T` must be a vector of floating-point primitive types. - #[rustc_nounwind] - pub fn simd_fabs(x: T) -> T; - - /// Elementwise minimum of a vector. - /// - /// `T` must be a vector of floating-point primitive types. - /// - /// Follows IEEE-754 `minNum` semantics. - #[rustc_nounwind] - pub fn simd_fmin(x: T, y: T) -> T; - - /// Elementwise maximum of a vector. - /// - /// `T` must be a vector of floating-point primitive types. - /// - /// Follows IEEE-754 `maxNum` semantics. - #[rustc_nounwind] - pub fn simd_fmax(x: T, y: T) -> T; - - /// Tests elementwise equality of two vectors. - /// - /// `T` must be a vector of floating-point primitive types. - /// - /// `U` must be a vector of integers with the same number of elements and element size as `T`. - /// - /// Returns `0` for false and `!0` for true. - #[rustc_nounwind] - pub fn simd_eq(x: T, y: T) -> U; - - /// Tests elementwise inequality equality of two vectors. - /// - /// `T` must be a vector of floating-point primitive types. - /// - /// `U` must be a vector of integers with the same number of elements and element size as `T`. - /// - /// Returns `0` for false and `!0` for true. - #[rustc_nounwind] - pub fn simd_ne(x: T, y: T) -> U; - - /// Tests if `x` is less than `y`, elementwise. - /// - /// `T` must be a vector of floating-point primitive types. - /// - /// `U` must be a vector of integers with the same number of elements and element size as `T`. - /// - /// Returns `0` for false and `!0` for true. - #[rustc_nounwind] - pub fn simd_lt(x: T, y: T) -> U; - - /// Tests if `x` is less than or equal to `y`, elementwise. - /// - /// `T` must be a vector of floating-point primitive types. - /// - /// `U` must be a vector of integers with the same number of elements and element size as `T`. - /// - /// Returns `0` for false and `!0` for true. - #[rustc_nounwind] - pub fn simd_le(x: T, y: T) -> U; - - /// Tests if `x` is greater than `y`, elementwise. - /// - /// `T` must be a vector of floating-point primitive types. - /// - /// `U` must be a vector of integers with the same number of elements and element size as `T`. - /// - /// Returns `0` for false and `!0` for true. - #[rustc_nounwind] - pub fn simd_gt(x: T, y: T) -> U; - - /// Tests if `x` is greater than or equal to `y`, elementwise. - /// - /// `T` must be a vector of floating-point primitive types. - /// - /// `U` must be a vector of integers with the same number of elements and element size as `T`. - /// - /// Returns `0` for false and `!0` for true. - #[rustc_nounwind] - pub fn simd_ge(x: T, y: T) -> U; - - /// Shuffle two vectors by const indices. - /// - /// `T` must be a vector. - /// - /// `U` must be a **const** array of `i32`s. This means it must either refer to a named - /// const or be given as an inline const expression (`const { ... }`). - /// - /// `V` must be a vector with the same element type as `T` and the same length as `U`. - /// - /// Returns a new vector such that element `i` is selected from `xy[idx[i]]`, where `xy` - /// is the concatenation of `x` and `y`. It is a compile-time error if `idx[i]` is out-of-bounds - /// of `xy`. - #[rustc_nounwind] - pub fn simd_shuffle(x: T, y: T, idx: U) -> V; - - /// Shuffle two vectors by const indices. - /// - /// `T` must be a vector. - /// - /// `U` must be a vector with the same element type as `T` and the same length as `IDX`. - /// - /// Returns a new vector such that element `i` is selected from `xy[IDX[i]]`, where `xy` - /// is the concatenation of `x` and `y`. It is a compile-time error if `IDX[i]` is out-of-bounds - /// of `xy`. - #[rustc_nounwind] - pub fn simd_shuffle_generic(x: T, y: T) -> U; - - /// Read a vector of pointers. - /// - /// `T` must be a vector. - /// - /// `U` must be a vector of pointers to the element type of `T`, with the same length as `T`. - /// - /// `V` must be a vector of integers with the same length as `T` (but any element size). - /// - /// `idx` must be a constant: either naming a constant item, or an inline - /// `const {}` expression. - /// - /// For each pointer in `ptr`, if the corresponding value in `mask` is `!0`, read the pointer. - /// Otherwise if the corresponding value in `mask` is `0`, return the corresponding value from - /// `val`. - /// - /// # Safety - /// Unmasked values in `T` must be readable as if by `::read` (e.g. aligned to the element - /// type). - /// - /// `mask` must only contain `0` or `!0` values. - #[rustc_nounwind] - pub fn simd_gather(val: T, ptr: U, mask: V) -> T; - - /// Write to a vector of pointers. - /// - /// `T` must be a vector. - /// - /// `U` must be a vector of pointers to the element type of `T`, with the same length as `T`. - /// - /// `V` must be a vector of integers with the same length as `T` (but any element size). - /// - /// For each pointer in `ptr`, if the corresponding value in `mask` is `!0`, write the - /// corresponding value in `val` to the pointer. - /// Otherwise if the corresponding value in `mask` is `0`, do nothing. - /// - /// The stores happen in left-to-right order. - /// (This is relevant in case two of the stores overlap.) - /// - /// # Safety - /// Unmasked values in `T` must be writeable as if by `::write` (e.g. aligned to the element - /// type). - /// - /// `mask` must only contain `0` or `!0` values. - #[rustc_nounwind] - pub fn simd_scatter(val: T, ptr: U, mask: V); - - /// Read a vector of pointers. - /// - /// `T` must be a vector. - /// - /// `U` must be a pointer to the element type of `T` - /// - /// `V` must be a vector of integers with the same length as `T` (but any element size). - /// - /// For each element, if the corresponding value in `mask` is `!0`, read the corresponding - /// pointer offset from `ptr`. - /// The first element is loaded from `ptr`, the second from `ptr.wrapping_offset(1)` and so on. - /// Otherwise if the corresponding value in `mask` is `0`, return the corresponding value from - /// `val`. - /// - /// # Safety - /// Unmasked values in `T` must be readable as if by `::read` (e.g. aligned to the element - /// type). - /// - /// `mask` must only contain `0` or `!0` values. - #[rustc_nounwind] - pub fn simd_masked_load(mask: V, ptr: U, val: T) -> T; - - /// Write to a vector of pointers. - /// - /// `T` must be a vector. - /// - /// `U` must be a pointer to the element type of `T` - /// - /// `V` must be a vector of integers with the same length as `T` (but any element size). - /// - /// For each element, if the corresponding value in `mask` is `!0`, write the corresponding - /// value in `val` to the pointer offset from `ptr`. - /// The first element is written to `ptr`, the second to `ptr.wrapping_offset(1)` and so on. - /// Otherwise if the corresponding value in `mask` is `0`, do nothing. - /// - /// # Safety - /// Unmasked values in `T` must be writeable as if by `::write` (e.g. aligned to the element - /// type). - /// - /// `mask` must only contain `0` or `!0` values. - #[rustc_nounwind] - pub fn simd_masked_store(mask: V, ptr: U, val: T); - - /// Add two simd vectors elementwise, with saturation. - /// - /// `T` must be a vector of integer primitive types. - #[rustc_nounwind] - pub fn simd_saturating_add(x: T, y: T) -> T; - - /// Subtract two simd vectors elementwise, with saturation. - /// - /// `T` must be a vector of integer primitive types. - /// - /// Subtract `rhs` from `lhs`. - #[rustc_nounwind] - pub fn simd_saturating_sub(lhs: T, rhs: T) -> T; - - /// Add elements within a vector from left to right. - /// - /// `T` must be a vector of integer or floating-point primitive types. - /// - /// `U` must be the element type of `T`. - /// - /// Starting with the value `y`, add the elements of `x` and accumulate. - #[rustc_nounwind] - pub fn simd_reduce_add_ordered(x: T, y: U) -> U; - - /// Add elements within a vector in arbitrary order. May also be re-associated with - /// unordered additions on the inputs/outputs. - /// - /// `T` must be a vector of integer or floating-point primitive types. - /// - /// `U` must be the element type of `T`. - #[rustc_nounwind] - pub fn simd_reduce_add_unordered(x: T) -> U; - - /// Multiply elements within a vector from left to right. - /// - /// `T` must be a vector of integer or floating-point primitive types. - /// - /// `U` must be the element type of `T`. - /// - /// Starting with the value `y`, multiply the elements of `x` and accumulate. - #[rustc_nounwind] - pub fn simd_reduce_mul_ordered(x: T, y: U) -> U; - - /// Add elements within a vector in arbitrary order. May also be re-associated with - /// unordered additions on the inputs/outputs. - /// - /// `T` must be a vector of integer or floating-point primitive types. - /// - /// `U` must be the element type of `T`. - #[rustc_nounwind] - pub fn simd_reduce_mul_unordered(x: T) -> U; - - /// Check if all mask values are true. - /// - /// `T` must be a vector of integer primitive types. - /// - /// # Safety - /// `x` must contain only `0` or `!0`. - #[rustc_nounwind] - pub fn simd_reduce_all(x: T) -> bool; - - /// Check if all mask values are true. - /// - /// `T` must be a vector of integer primitive types. - /// - /// # Safety - /// `x` must contain only `0` or `!0`. - #[rustc_nounwind] - pub fn simd_reduce_any(x: T) -> bool; - - /// Return the maximum element of a vector. - /// - /// `T` must be a vector of integer or floating-point primitive types. - /// - /// `U` must be the element type of `T`. - /// - /// For floating-point values, uses IEEE-754 `maxNum`. - #[rustc_nounwind] - pub fn simd_reduce_max(x: T) -> U; - - /// Return the minimum element of a vector. - /// - /// `T` must be a vector of integer or floating-point primitive types. - /// - /// `U` must be the element type of `T`. - /// - /// For floating-point values, uses IEEE-754 `minNum`. - #[rustc_nounwind] - pub fn simd_reduce_min(x: T) -> U; - - /// Logical "and" all elements together. - /// - /// `T` must be a vector of integer or floating-point primitive types. - /// - /// `U` must be the element type of `T`. - #[rustc_nounwind] - pub fn simd_reduce_and(x: T) -> U; - - /// Logical "or" all elements together. - /// - /// `T` must be a vector of integer or floating-point primitive types. - /// - /// `U` must be the element type of `T`. - #[rustc_nounwind] - pub fn simd_reduce_or(x: T) -> U; - - /// Logical "exclusive or" all elements together. - /// - /// `T` must be a vector of integer or floating-point primitive types. - /// - /// `U` must be the element type of `T`. - #[rustc_nounwind] - pub fn simd_reduce_xor(x: T) -> U; - - /// Truncate an integer vector to a bitmask. - /// - /// `T` must be an integer vector. - /// - /// `U` must be either the smallest unsigned integer with at least as many bits as the length - /// of `T`, or the smallest array of `u8` with as many bits as the length of `T`. - /// - /// Each element is truncated to a single bit and packed into the result. - /// - /// No matter whether the output is an array or an unsigned integer, it is treated as a single - /// contiguous list of bits. The bitmask is always packed on the least-significant side of the - /// output, and padded with 0s in the most-significant bits. The order of the bits depends on - /// endianness: - /// - /// * On little endian, the least significant bit corresponds to the first vector element. - /// * On big endian, the least significant bit corresponds to the last vector element. - /// - /// For example, `[!0, 0, !0, !0]` packs to `0b1101` on little endian and `0b1011` on big - /// endian. - /// - /// To consider a larger example, `[!0, 0, 0, 0, 0, 0, 0, 0, !0, !0, 0, 0, 0, 0, !0, 0]` packs - /// to `[0b00000001, 0b01000011]` or `0b0100001100000001` on little endian, and `[0b10000000, - /// 0b11000010]` or `0b1000000011000010` on big endian. - /// - /// # Safety - /// `x` must contain only `0` and `!0`. - #[rustc_nounwind] - pub fn simd_bitmask(x: T) -> U; - - /// Select elements from a mask. - /// - /// `M` must be an integer vector. - /// - /// `T` must be a vector with the same number of elements as `M`. - /// - /// For each element, if the corresponding value in `mask` is `!0`, select the element from - /// `if_true`. If the corresponding value in `mask` is `0`, select the element from - /// `if_false`. - /// - /// # Safety - /// `mask` must only contain `0` and `!0`. - #[rustc_nounwind] - pub fn simd_select(mask: M, if_true: T, if_false: T) -> T; - - /// Select elements from a bitmask. - /// - /// `M` must be an unsigned integer or array of `u8`, matching `simd_bitmask`. - /// - /// `T` must be a vector. - /// - /// For each element, if the bit in `mask` is `1`, select the element from - /// `if_true`. If the corresponding bit in `mask` is `0`, select the element from - /// `if_false`. - /// - /// The bitmask bit order matches `simd_bitmask`. - /// - /// # Safety - /// Padding bits must be all zero. - #[rustc_nounwind] - pub fn simd_select_bitmask(m: M, yes: T, no: T) -> T; - - /// Elementwise calculates the offset from a pointer vector, potentially wrapping. - /// - /// `T` must be a vector of pointers. - /// - /// `U` must be a vector of `isize` or `usize` with the same number of elements as `T`. - /// - /// Operates as if by `::wrapping_offset`. - #[rustc_nounwind] - pub fn simd_arith_offset(ptr: T, offset: U) -> T; - - /// Cast a vector of pointers. - /// - /// `T` and `U` must be vectors of pointers with the same number of elements. - #[rustc_nounwind] - pub fn simd_cast_ptr(ptr: T) -> U; - - /// Expose a vector of pointers as a vector of addresses. - /// - /// `T` must be a vector of pointers. - /// - /// `U` must be a vector of `usize` with the same length as `T`. - #[rustc_nounwind] - pub fn simd_expose_provenance(ptr: T) -> U; - - /// Create a vector of pointers from a vector of addresses. - /// - /// `T` must be a vector of `usize`. - /// - /// `U` must be a vector of pointers, with the same length as `T`. - #[rustc_nounwind] - pub fn simd_with_exposed_provenance(addr: T) -> U; - - /// Swap bytes of each element. - /// - /// `T` must be a vector of integers. - #[rustc_nounwind] - pub fn simd_bswap(x: T) -> T; - - /// Reverse bits of each element. - /// - /// `T` must be a vector of integers. - #[rustc_nounwind] - pub fn simd_bitreverse(x: T) -> T; - - /// Count the leading zeros of each element. - /// - /// `T` must be a vector of integers. - #[rustc_nounwind] - pub fn simd_ctlz(x: T) -> T; - - /// Count the number of ones in each element. - /// - /// `T` must be a vector of integers. - #[rustc_nounwind] - #[cfg(not(bootstrap))] - pub fn simd_ctpop(x: T) -> T; - - /// Count the trailing zeros of each element. - /// - /// `T` must be a vector of integers. - #[rustc_nounwind] - pub fn simd_cttz(x: T) -> T; - - /// Round up each element to the next highest integer-valued float. - /// - /// `T` must be a vector of floats. - #[rustc_nounwind] - pub fn simd_ceil(x: T) -> T; - - /// Round down each element to the next lowest integer-valued float. - /// - /// `T` must be a vector of floats. - #[rustc_nounwind] - pub fn simd_floor(x: T) -> T; - - /// Round each element to the closest integer-valued float. - /// Ties are resolved by rounding away from 0. - /// - /// `T` must be a vector of floats. - #[rustc_nounwind] - pub fn simd_round(x: T) -> T; - - /// Return the integer part of each element as an integer-valued float. - /// In other words, non-integer values are truncated towards zero. - /// - /// `T` must be a vector of floats. - #[rustc_nounwind] - pub fn simd_trunc(x: T) -> T; - - /// Takes the square root of each element. - /// - /// `T` must be a vector of floats. - #[rustc_nounwind] - pub fn simd_fsqrt(x: T) -> T; - - /// Computes `(x*y) + z` for each element, but without any intermediate rounding. - /// - /// `T` must be a vector of floats. - #[rustc_nounwind] - pub fn simd_fma(x: T, y: T, z: T) -> T; - - // Computes the sine of each element. - /// - /// `T` must be a vector of floats. - #[rustc_nounwind] - pub fn simd_fsin(a: T) -> T; - - // Computes the cosine of each element. - /// - /// `T` must be a vector of floats. - #[rustc_nounwind] - pub fn simd_fcos(a: T) -> T; - - // Computes the exponential function of each element. - /// - /// `T` must be a vector of floats. - #[rustc_nounwind] - pub fn simd_fexp(a: T) -> T; - - // Computes 2 raised to the power of each element. - /// - /// `T` must be a vector of floats. - #[rustc_nounwind] - pub fn simd_fexp2(a: T) -> T; - - // Computes the base 10 logarithm of each element. - /// - /// `T` must be a vector of floats. - #[rustc_nounwind] - pub fn simd_flog10(a: T) -> T; - - // Computes the base 2 logarithm of each element. - /// - /// `T` must be a vector of floats. - #[rustc_nounwind] - pub fn simd_flog2(a: T) -> T; - - // Computes the natural logarithm of each element. - /// - /// `T` must be a vector of floats. - #[rustc_nounwind] - pub fn simd_flog(a: T) -> T; -} diff --git a/library/core/src/io/borrowed_buf.rs b/library/core/src/io/borrowed_buf.rs deleted file mode 100644 index d497da33dd923..0000000000000 --- a/library/core/src/io/borrowed_buf.rs +++ /dev/null @@ -1,336 +0,0 @@ -#![unstable(feature = "core_io_borrowed_buf", issue = "117693")] - -use crate::fmt::{self, Debug, Formatter}; -use crate::mem::{self, MaybeUninit}; -use crate::{cmp, ptr}; - -/// A borrowed byte buffer which is incrementally filled and initialized. -/// -/// This type is a sort of "double cursor". It tracks three regions in the buffer: a region at the beginning of the -/// buffer that has been logically filled with data, a region that has been initialized at some point but not yet -/// logically filled, and a region at the end that is fully uninitialized. The filled region is guaranteed to be a -/// subset of the initialized region. -/// -/// In summary, the contents of the buffer can be visualized as: -/// ```not_rust -/// [ capacity ] -/// [ filled | unfilled ] -/// [ initialized | uninitialized ] -/// ``` -/// -/// A `BorrowedBuf` is created around some existing data (or capacity for data) via a unique reference -/// (`&mut`). The `BorrowedBuf` can be configured (e.g., using `clear` or `set_init`), but cannot be -/// directly written. To write into the buffer, use `unfilled` to create a `BorrowedCursor`. The cursor -/// has write-only access to the unfilled portion of the buffer (you can think of it as a -/// write-only iterator). -/// -/// The lifetime `'data` is a bound on the lifetime of the underlying data. -pub struct BorrowedBuf<'data> { - /// The buffer's underlying data. - buf: &'data mut [MaybeUninit], - /// The length of `self.buf` which is known to be filled. - filled: usize, - /// The length of `self.buf` which is known to be initialized. - init: usize, -} - -impl Debug for BorrowedBuf<'_> { - fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { - f.debug_struct("BorrowedBuf") - .field("init", &self.init) - .field("filled", &self.filled) - .field("capacity", &self.capacity()) - .finish() - } -} - -/// Create a new `BorrowedBuf` from a fully initialized slice. -impl<'data> From<&'data mut [u8]> for BorrowedBuf<'data> { - #[inline] - fn from(slice: &'data mut [u8]) -> BorrowedBuf<'data> { - let len = slice.len(); - - BorrowedBuf { - // SAFETY: initialized data never becoming uninitialized is an invariant of BorrowedBuf - buf: unsafe { (slice as *mut [u8]).as_uninit_slice_mut().unwrap() }, - filled: 0, - init: len, - } - } -} - -/// Create a new `BorrowedBuf` from an uninitialized buffer. -/// -/// Use `set_init` if part of the buffer is known to be already initialized. -impl<'data> From<&'data mut [MaybeUninit]> for BorrowedBuf<'data> { - #[inline] - fn from(buf: &'data mut [MaybeUninit]) -> BorrowedBuf<'data> { - BorrowedBuf { buf, filled: 0, init: 0 } - } -} - -impl<'data> BorrowedBuf<'data> { - /// Returns the total capacity of the buffer. - #[inline] - pub fn capacity(&self) -> usize { - self.buf.len() - } - - /// Returns the length of the filled part of the buffer. - #[inline] - pub fn len(&self) -> usize { - self.filled - } - - /// Returns the length of the initialized part of the buffer. - #[inline] - pub fn init_len(&self) -> usize { - self.init - } - - /// Returns a shared reference to the filled portion of the buffer. - #[inline] - pub fn filled(&self) -> &[u8] { - // SAFETY: We only slice the filled part of the buffer, which is always valid - unsafe { - let buf = self.buf.get_unchecked(..self.filled); - MaybeUninit::slice_assume_init_ref(buf) - } - } - - /// Returns a mutable reference to the filled portion of the buffer. - #[inline] - pub fn filled_mut(&mut self) -> &mut [u8] { - // SAFETY: We only slice the filled part of the buffer, which is always valid - unsafe { - let buf = self.buf.get_unchecked_mut(..self.filled); - MaybeUninit::slice_assume_init_mut(buf) - } - } - - /// Returns a cursor over the unfilled part of the buffer. - #[inline] - pub fn unfilled<'this>(&'this mut self) -> BorrowedCursor<'this> { - BorrowedCursor { - start: self.filled, - // SAFETY: we never assign into `BorrowedCursor::buf`, so treating its - // lifetime covariantly is safe. - buf: unsafe { - mem::transmute::<&'this mut BorrowedBuf<'data>, &'this mut BorrowedBuf<'this>>(self) - }, - } - } - - /// Clears the buffer, resetting the filled region to empty. - /// - /// The number of initialized bytes is not changed, and the contents of the buffer are not modified. - #[inline] - pub fn clear(&mut self) -> &mut Self { - self.filled = 0; - self - } - - /// Asserts that the first `n` bytes of the buffer are initialized. - /// - /// `BorrowedBuf` assumes that bytes are never de-initialized, so this method does nothing when called with fewer - /// bytes than are already known to be initialized. - /// - /// # Safety - /// - /// The caller must ensure that the first `n` unfilled bytes of the buffer have already been initialized. - #[inline] - pub unsafe fn set_init(&mut self, n: usize) -> &mut Self { - self.init = cmp::max(self.init, n); - self - } -} - -/// A writeable view of the unfilled portion of a [`BorrowedBuf`]. -/// -/// The unfilled portion consists of an initialized and an uninitialized part; see [`BorrowedBuf`] -/// for details. -/// -/// Data can be written directly to the cursor by using [`append`](BorrowedCursor::append) or -/// indirectly by getting a slice of part or all of the cursor and writing into the slice. In the -/// indirect case, the caller must call [`advance`](BorrowedCursor::advance) after writing to inform -/// the cursor how many bytes have been written. -/// -/// Once data is written to the cursor, it becomes part of the filled portion of the underlying -/// `BorrowedBuf` and can no longer be accessed or re-written by the cursor. I.e., the cursor tracks -/// the unfilled part of the underlying `BorrowedBuf`. -/// -/// The lifetime `'a` is a bound on the lifetime of the underlying buffer (which means it is a bound -/// on the data in that buffer by transitivity). -#[derive(Debug)] -pub struct BorrowedCursor<'a> { - /// The underlying buffer. - // Safety invariant: we treat the type of buf as covariant in the lifetime of `BorrowedBuf` when - // we create a `BorrowedCursor`. This is only safe if we never replace `buf` by assigning into - // it, so don't do that! - buf: &'a mut BorrowedBuf<'a>, - /// The length of the filled portion of the underlying buffer at the time of the cursor's - /// creation. - start: usize, -} - -impl<'a> BorrowedCursor<'a> { - /// Reborrow this cursor by cloning it with a smaller lifetime. - /// - /// Since a cursor maintains unique access to its underlying buffer, the borrowed cursor is - /// not accessible while the new cursor exists. - #[inline] - pub fn reborrow<'this>(&'this mut self) -> BorrowedCursor<'this> { - BorrowedCursor { - // SAFETY: we never assign into `BorrowedCursor::buf`, so treating its - // lifetime covariantly is safe. - buf: unsafe { - mem::transmute::<&'this mut BorrowedBuf<'a>, &'this mut BorrowedBuf<'this>>( - self.buf, - ) - }, - start: self.start, - } - } - - /// Returns the available space in the cursor. - #[inline] - pub fn capacity(&self) -> usize { - self.buf.capacity() - self.buf.filled - } - - /// Returns the number of bytes written to this cursor since it was created from a `BorrowedBuf`. - /// - /// Note that if this cursor is a reborrowed clone of another, then the count returned is the - /// count written via either cursor, not the count since the cursor was reborrowed. - #[inline] - pub fn written(&self) -> usize { - self.buf.filled - self.start - } - - /// Returns a shared reference to the initialized portion of the cursor. - #[inline] - pub fn init_ref(&self) -> &[u8] { - // SAFETY: We only slice the initialized part of the buffer, which is always valid - unsafe { - let buf = self.buf.buf.get_unchecked(self.buf.filled..self.buf.init); - MaybeUninit::slice_assume_init_ref(buf) - } - } - - /// Returns a mutable reference to the initialized portion of the cursor. - #[inline] - pub fn init_mut(&mut self) -> &mut [u8] { - // SAFETY: We only slice the initialized part of the buffer, which is always valid - unsafe { - let buf = self.buf.buf.get_unchecked_mut(self.buf.filled..self.buf.init); - MaybeUninit::slice_assume_init_mut(buf) - } - } - - /// Returns a mutable reference to the uninitialized part of the cursor. - /// - /// It is safe to uninitialize any of these bytes. - #[inline] - pub fn uninit_mut(&mut self) -> &mut [MaybeUninit] { - // SAFETY: always in bounds - unsafe { self.buf.buf.get_unchecked_mut(self.buf.init..) } - } - - /// Returns a mutable reference to the whole cursor. - /// - /// # Safety - /// - /// The caller must not uninitialize any bytes in the initialized portion of the cursor. - #[inline] - pub unsafe fn as_mut(&mut self) -> &mut [MaybeUninit] { - // SAFETY: always in bounds - unsafe { self.buf.buf.get_unchecked_mut(self.buf.filled..) } - } - - /// Advance the cursor by asserting that `n` bytes have been filled. - /// - /// After advancing, the `n` bytes are no longer accessible via the cursor and can only be - /// accessed via the underlying buffer. I.e., the buffer's filled portion grows by `n` elements - /// and its unfilled portion (and the capacity of this cursor) shrinks by `n` elements. - /// - /// If less than `n` bytes initialized (by the cursor's point of view), `set_init` should be - /// called first. - /// - /// # Panics - /// - /// Panics if there are less than `n` bytes initialized. - #[inline] - pub fn advance(&mut self, n: usize) -> &mut Self { - let filled = self.buf.filled.strict_add(n); - assert!(filled <= self.buf.init); - - self.buf.filled = filled; - self - } - - /// Advance the cursor by asserting that `n` bytes have been filled. - /// - /// After advancing, the `n` bytes are no longer accessible via the cursor and can only be - /// accessed via the underlying buffer. I.e., the buffer's filled portion grows by `n` elements - /// and its unfilled portion (and the capacity of this cursor) shrinks by `n` elements. - /// - /// # Safety - /// - /// The caller must ensure that the first `n` bytes of the cursor have been properly - /// initialised. - #[inline] - pub unsafe fn advance_unchecked(&mut self, n: usize) -> &mut Self { - self.buf.filled += n; - self.buf.init = cmp::max(self.buf.init, self.buf.filled); - self - } - - /// Initializes all bytes in the cursor. - #[inline] - pub fn ensure_init(&mut self) -> &mut Self { - let uninit = self.uninit_mut(); - // SAFETY: 0 is a valid value for MaybeUninit and the length matches the allocation - // since it is comes from a slice reference. - unsafe { - ptr::write_bytes(uninit.as_mut_ptr(), 0, uninit.len()); - } - self.buf.init = self.buf.capacity(); - - self - } - - /// Asserts that the first `n` unfilled bytes of the cursor are initialized. - /// - /// `BorrowedBuf` assumes that bytes are never de-initialized, so this method does nothing when - /// called with fewer bytes than are already known to be initialized. - /// - /// # Safety - /// - /// The caller must ensure that the first `n` bytes of the buffer have already been initialized. - #[inline] - pub unsafe fn set_init(&mut self, n: usize) -> &mut Self { - self.buf.init = cmp::max(self.buf.init, self.buf.filled + n); - self - } - - /// Appends data to the cursor, advancing position within its buffer. - /// - /// # Panics - /// - /// Panics if `self.capacity()` is less than `buf.len()`. - #[inline] - pub fn append(&mut self, buf: &[u8]) { - assert!(self.capacity() >= buf.len()); - - // SAFETY: we do not de-initialize any of the elements of the slice - unsafe { - MaybeUninit::copy_from_slice(&mut self.as_mut()[..buf.len()], buf); - } - - // SAFETY: We just added the entire contents of buf to the filled section. - unsafe { - self.set_init(buf.len()); - } - self.buf.filled += buf.len(); - } -} diff --git a/library/core/src/io/mod.rs b/library/core/src/io/mod.rs deleted file mode 100644 index 2f20180cdc9a2..0000000000000 --- a/library/core/src/io/mod.rs +++ /dev/null @@ -1,6 +0,0 @@ -//! Traits, helpers, and type definitions for core I/O functionality. - -mod borrowed_buf; - -#[unstable(feature = "core_io_borrowed_buf", issue = "117693")] -pub use self::borrowed_buf::{BorrowedBuf, BorrowedCursor}; diff --git a/library/core/src/iter/adapters/array_chunks.rs b/library/core/src/iter/adapters/array_chunks.rs deleted file mode 100644 index 8f1744fc5fbb7..0000000000000 --- a/library/core/src/iter/adapters/array_chunks.rs +++ /dev/null @@ -1,276 +0,0 @@ -use crate::array; -use crate::iter::adapters::SourceIter; -use crate::iter::{ - ByRefSized, FusedIterator, InPlaceIterable, TrustedFused, TrustedRandomAccessNoCoerce, -}; -use crate::num::NonZero; -use crate::ops::{ControlFlow, NeverShortCircuit, Try}; - -/// An iterator over `N` elements of the iterator at a time. -/// -/// The chunks do not overlap. If `N` does not divide the length of the -/// iterator, then the last up to `N-1` elements will be omitted. -/// -/// This `struct` is created by the [`array_chunks`][Iterator::array_chunks] -/// method on [`Iterator`]. See its documentation for more. -#[derive(Debug, Clone)] -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[unstable(feature = "iter_array_chunks", reason = "recently added", issue = "100450")] -pub struct ArrayChunks { - iter: I, - remainder: Option>, -} - -impl ArrayChunks -where - I: Iterator, -{ - #[track_caller] - pub(in crate::iter) fn new(iter: I) -> Self { - assert!(N != 0, "chunk size must be non-zero"); - Self { iter, remainder: None } - } - - /// Returns an iterator over the remaining elements of the original iterator - /// that are not going to be returned by this iterator. The returned - /// iterator will yield at most `N-1` elements. - /// - /// # Example - /// ``` - /// # // Also serves as a regression test for https://github.com/rust-lang/rust/issues/123333 - /// # #![feature(iter_array_chunks)] - /// let x = [1,2,3,4,5].into_iter().array_chunks::<2>(); - /// let mut rem = x.into_remainder().unwrap(); - /// assert_eq!(rem.next(), Some(5)); - /// assert_eq!(rem.next(), None); - /// ``` - #[unstable(feature = "iter_array_chunks", reason = "recently added", issue = "100450")] - #[inline] - pub fn into_remainder(mut self) -> Option> { - if self.remainder.is_none() { - while let Some(_) = self.next() {} - } - self.remainder - } -} - -#[unstable(feature = "iter_array_chunks", reason = "recently added", issue = "100450")] -impl Iterator for ArrayChunks -where - I: Iterator, -{ - type Item = [I::Item; N]; - - #[inline] - fn next(&mut self) -> Option { - self.try_for_each(ControlFlow::Break).break_value() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let (lower, upper) = self.iter.size_hint(); - - (lower / N, upper.map(|n| n / N)) - } - - #[inline] - fn count(self) -> usize { - self.iter.count() / N - } - - fn try_fold(&mut self, init: B, mut f: F) -> R - where - Self: Sized, - F: FnMut(B, Self::Item) -> R, - R: Try, - { - let mut acc = init; - loop { - match self.iter.next_chunk() { - Ok(chunk) => acc = f(acc, chunk)?, - Err(remainder) => { - // Make sure to not override `self.remainder` with an empty array - // when `next` is called after `ArrayChunks` exhaustion. - self.remainder.get_or_insert(remainder); - - break try { acc }; - } - } - } - } - - fn fold(self, init: B, f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - ::fold(self, init, f) - } -} - -#[unstable(feature = "iter_array_chunks", reason = "recently added", issue = "100450")] -impl DoubleEndedIterator for ArrayChunks -where - I: DoubleEndedIterator + ExactSizeIterator, -{ - #[inline] - fn next_back(&mut self) -> Option { - self.try_rfold((), |(), x| ControlFlow::Break(x)).break_value() - } - - fn try_rfold(&mut self, init: B, mut f: F) -> R - where - Self: Sized, - F: FnMut(B, Self::Item) -> R, - R: Try, - { - // We are iterating from the back we need to first handle the remainder. - self.next_back_remainder(); - - let mut acc = init; - let mut iter = ByRefSized(&mut self.iter).rev(); - - // NB remainder is handled by `next_back_remainder`, so - // `next_chunk` can't return `Err` with non-empty remainder - // (assuming correct `I as ExactSizeIterator` impl). - while let Ok(mut chunk) = iter.next_chunk() { - // FIXME: do not do double reverse - // (we could instead add `next_chunk_back` for example) - chunk.reverse(); - acc = f(acc, chunk)? - } - - try { acc } - } - - impl_fold_via_try_fold! { rfold -> try_rfold } -} - -impl ArrayChunks -where - I: DoubleEndedIterator + ExactSizeIterator, -{ - /// Updates `self.remainder` such that `self.iter.len` is divisible by `N`. - fn next_back_remainder(&mut self) { - // Make sure to not override `self.remainder` with an empty array - // when `next_back` is called after `ArrayChunks` exhaustion. - if self.remainder.is_some() { - return; - } - - // We use the `ExactSizeIterator` implementation of the underlying - // iterator to know how many remaining elements there are. - let rem = self.iter.len() % N; - - // Take the last `rem` elements out of `self.iter`. - let mut remainder = - // SAFETY: `unwrap_err` always succeeds because x % N < N for all x. - unsafe { self.iter.by_ref().rev().take(rem).next_chunk().unwrap_err_unchecked() }; - - // We used `.rev()` above, so we need to re-reverse the reminder - remainder.as_mut_slice().reverse(); - self.remainder = Some(remainder); - } -} - -#[unstable(feature = "iter_array_chunks", reason = "recently added", issue = "100450")] -impl FusedIterator for ArrayChunks where I: FusedIterator {} - -#[unstable(issue = "none", feature = "trusted_fused")] -unsafe impl TrustedFused for ArrayChunks where I: TrustedFused + Iterator {} - -#[unstable(feature = "iter_array_chunks", reason = "recently added", issue = "100450")] -impl ExactSizeIterator for ArrayChunks -where - I: ExactSizeIterator, -{ - #[inline] - fn len(&self) -> usize { - self.iter.len() / N - } - - #[inline] - fn is_empty(&self) -> bool { - self.iter.len() < N - } -} - -trait SpecFold: Iterator { - fn fold(self, init: B, f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B; -} - -impl SpecFold for ArrayChunks -where - I: Iterator, -{ - #[inline] - default fn fold(mut self, init: B, f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - self.try_fold(init, NeverShortCircuit::wrap_mut_2(f)).0 - } -} - -impl SpecFold for ArrayChunks -where - I: Iterator + TrustedRandomAccessNoCoerce, -{ - #[inline] - fn fold(mut self, init: B, mut f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - let mut accum = init; - let inner_len = self.iter.size(); - let mut i = 0; - // Use a while loop because (0..len).step_by(N) doesn't optimize well. - while inner_len - i >= N { - let chunk = crate::array::from_fn(|local| { - // SAFETY: The method consumes the iterator and the loop condition ensures that - // all accesses are in bounds and only happen once. - unsafe { - let idx = i + local; - self.iter.__iterator_get_unchecked(idx) - } - }); - accum = f(accum, chunk); - i += N; - } - - // unlike try_fold this method does not need to take care of the remainder - // since `self` will be dropped - - accum - } -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl SourceIter for ArrayChunks -where - I: SourceIter + Iterator, -{ - type Source = I::Source; - - #[inline] - unsafe fn as_inner(&mut self) -> &mut I::Source { - // SAFETY: unsafe function forwarding to unsafe function with the same requirements - unsafe { SourceIter::as_inner(&mut self.iter) } - } -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl InPlaceIterable for ArrayChunks { - const EXPAND_BY: Option> = I::EXPAND_BY; - const MERGE_BY: Option> = const { - match (I::MERGE_BY, NonZero::new(N)) { - (Some(m), Some(n)) => m.checked_mul(n), - _ => None, - } - }; -} diff --git a/library/core/src/iter/adapters/by_ref_sized.rs b/library/core/src/iter/adapters/by_ref_sized.rs deleted file mode 100644 index d084bede1eba6..0000000000000 --- a/library/core/src/iter/adapters/by_ref_sized.rs +++ /dev/null @@ -1,92 +0,0 @@ -use crate::num::NonZero; -use crate::ops::{NeverShortCircuit, Try}; - -/// Like `Iterator::by_ref`, but requiring `Sized` so it can forward generics. -/// -/// Ideally this will no longer be required, eventually, but as can be seen in -/// the benchmarks (as of Feb 2022 at least) `by_ref` can have performance cost. -#[unstable(feature = "std_internals", issue = "none")] -#[derive(Debug)] -pub struct ByRefSized<'a, I>(pub &'a mut I); - -// The following implementations use UFCS-style, rather than trusting autoderef, -// to avoid accidentally calling the `&mut Iterator` implementations. - -#[unstable(feature = "std_internals", issue = "none")] -impl Iterator for ByRefSized<'_, I> { - type Item = I::Item; - - #[inline] - fn next(&mut self) -> Option { - I::next(self.0) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - I::size_hint(self.0) - } - - #[inline] - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - I::advance_by(self.0, n) - } - - #[inline] - fn nth(&mut self, n: usize) -> Option { - I::nth(self.0, n) - } - - #[inline] - fn fold(self, init: B, f: F) -> B - where - F: FnMut(B, Self::Item) -> B, - { - // `fold` needs ownership, so this can't forward directly. - I::try_fold(self.0, init, NeverShortCircuit::wrap_mut_2(f)).0 - } - - #[inline] - fn try_fold(&mut self, init: B, f: F) -> R - where - F: FnMut(B, Self::Item) -> R, - R: Try, - { - I::try_fold(self.0, init, f) - } -} - -#[unstable(feature = "std_internals", issue = "none")] -impl DoubleEndedIterator for ByRefSized<'_, I> { - #[inline] - fn next_back(&mut self) -> Option { - I::next_back(self.0) - } - - #[inline] - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - I::advance_back_by(self.0, n) - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option { - I::nth_back(self.0, n) - } - - #[inline] - fn rfold(self, init: B, f: F) -> B - where - F: FnMut(B, Self::Item) -> B, - { - // `rfold` needs ownership, so this can't forward directly. - I::try_rfold(self.0, init, NeverShortCircuit::wrap_mut_2(f)).0 - } - - #[inline] - fn try_rfold(&mut self, init: B, f: F) -> R - where - F: FnMut(B, Self::Item) -> R, - R: Try, - { - I::try_rfold(self.0, init, f) - } -} diff --git a/library/core/src/iter/adapters/chain.rs b/library/core/src/iter/adapters/chain.rs deleted file mode 100644 index bcaac2f42cf04..0000000000000 --- a/library/core/src/iter/adapters/chain.rs +++ /dev/null @@ -1,305 +0,0 @@ -use crate::iter::{FusedIterator, TrustedLen}; -use crate::num::NonZero; -use crate::ops::Try; - -/// An iterator that links two iterators together, in a chain. -/// -/// This `struct` is created by [`Iterator::chain`]. See its documentation -/// for more. -/// -/// # Examples -/// -/// ``` -/// use std::iter::Chain; -/// use std::slice::Iter; -/// -/// let a1 = [1, 2, 3]; -/// let a2 = [4, 5, 6]; -/// let iter: Chain, Iter<'_, _>> = a1.iter().chain(a2.iter()); -/// ``` -#[derive(Clone, Debug)] -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Chain { - // These are "fused" with `Option` so we don't need separate state to track which part is - // already exhausted, and we may also get niche layout for `None`. We don't use the real `Fuse` - // adapter because its specialization for `FusedIterator` unconditionally descends into the - // iterator, and that could be expensive to keep revisiting stuff like nested chains. It also - // hurts compiler performance to add more iterator layers to `Chain`. - // - // Only the "first" iterator is actually set `None` when exhausted, depending on whether you - // iterate forward or backward. If you mix directions, then both sides may be `None`. - a: Option, - b: Option, -} -impl Chain { - pub(in super::super) fn new(a: A, b: B) -> Chain { - Chain { a: Some(a), b: Some(b) } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for Chain -where - A: Iterator, - B: Iterator, -{ - type Item = A::Item; - - #[inline] - fn next(&mut self) -> Option { - and_then_or_clear(&mut self.a, Iterator::next).or_else(|| self.b.as_mut()?.next()) - } - - #[inline] - #[rustc_inherit_overflow_checks] - fn count(self) -> usize { - let a_count = match self.a { - Some(a) => a.count(), - None => 0, - }; - let b_count = match self.b { - Some(b) => b.count(), - None => 0, - }; - a_count + b_count - } - - fn try_fold(&mut self, mut acc: Acc, mut f: F) -> R - where - Self: Sized, - F: FnMut(Acc, Self::Item) -> R, - R: Try, - { - if let Some(ref mut a) = self.a { - acc = a.try_fold(acc, &mut f)?; - self.a = None; - } - if let Some(ref mut b) = self.b { - acc = b.try_fold(acc, f)?; - // we don't fuse the second iterator - } - try { acc } - } - - fn fold(self, mut acc: Acc, mut f: F) -> Acc - where - F: FnMut(Acc, Self::Item) -> Acc, - { - if let Some(a) = self.a { - acc = a.fold(acc, &mut f); - } - if let Some(b) = self.b { - acc = b.fold(acc, f); - } - acc - } - - #[inline] - fn advance_by(&mut self, mut n: usize) -> Result<(), NonZero> { - if let Some(ref mut a) = self.a { - n = match a.advance_by(n) { - Ok(()) => return Ok(()), - Err(k) => k.get(), - }; - self.a = None; - } - - if let Some(ref mut b) = self.b { - return b.advance_by(n); - // we don't fuse the second iterator - } - - NonZero::new(n).map_or(Ok(()), Err) - } - - #[inline] - fn nth(&mut self, mut n: usize) -> Option { - if let Some(ref mut a) = self.a { - n = match a.advance_by(n) { - Ok(()) => match a.next() { - None => 0, - x => return x, - }, - Err(k) => k.get(), - }; - - self.a = None; - } - - self.b.as_mut()?.nth(n) - } - - #[inline] - fn find

(&mut self, mut predicate: P) -> Option - where - P: FnMut(&Self::Item) -> bool, - { - and_then_or_clear(&mut self.a, |a| a.find(&mut predicate)) - .or_else(|| self.b.as_mut()?.find(predicate)) - } - - #[inline] - fn last(self) -> Option { - // Must exhaust a before b. - let a_last = self.a.and_then(Iterator::last); - let b_last = self.b.and_then(Iterator::last); - b_last.or(a_last) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - match self { - Chain { a: Some(a), b: Some(b) } => { - let (a_lower, a_upper) = a.size_hint(); - let (b_lower, b_upper) = b.size_hint(); - - let lower = a_lower.saturating_add(b_lower); - - let upper = match (a_upper, b_upper) { - (Some(x), Some(y)) => x.checked_add(y), - _ => None, - }; - - (lower, upper) - } - Chain { a: Some(a), b: None } => a.size_hint(), - Chain { a: None, b: Some(b) } => b.size_hint(), - Chain { a: None, b: None } => (0, Some(0)), - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DoubleEndedIterator for Chain -where - A: DoubleEndedIterator, - B: DoubleEndedIterator, -{ - #[inline] - fn next_back(&mut self) -> Option { - and_then_or_clear(&mut self.b, |b| b.next_back()).or_else(|| self.a.as_mut()?.next_back()) - } - - #[inline] - fn advance_back_by(&mut self, mut n: usize) -> Result<(), NonZero> { - if let Some(ref mut b) = self.b { - n = match b.advance_back_by(n) { - Ok(()) => return Ok(()), - Err(k) => k.get(), - }; - self.b = None; - } - - if let Some(ref mut a) = self.a { - return a.advance_back_by(n); - // we don't fuse the second iterator - } - - NonZero::new(n).map_or(Ok(()), Err) - } - - #[inline] - fn nth_back(&mut self, mut n: usize) -> Option { - if let Some(ref mut b) = self.b { - n = match b.advance_back_by(n) { - Ok(()) => match b.next_back() { - None => 0, - x => return x, - }, - Err(k) => k.get(), - }; - - self.b = None; - } - - self.a.as_mut()?.nth_back(n) - } - - #[inline] - fn rfind

(&mut self, mut predicate: P) -> Option - where - P: FnMut(&Self::Item) -> bool, - { - and_then_or_clear(&mut self.b, |b| b.rfind(&mut predicate)) - .or_else(|| self.a.as_mut()?.rfind(predicate)) - } - - fn try_rfold(&mut self, mut acc: Acc, mut f: F) -> R - where - Self: Sized, - F: FnMut(Acc, Self::Item) -> R, - R: Try, - { - if let Some(ref mut b) = self.b { - acc = b.try_rfold(acc, &mut f)?; - self.b = None; - } - if let Some(ref mut a) = self.a { - acc = a.try_rfold(acc, f)?; - // we don't fuse the second iterator - } - try { acc } - } - - fn rfold(self, mut acc: Acc, mut f: F) -> Acc - where - F: FnMut(Acc, Self::Item) -> Acc, - { - if let Some(b) = self.b { - acc = b.rfold(acc, &mut f); - } - if let Some(a) = self.a { - acc = a.rfold(acc, f); - } - acc - } -} - -// Note: *both* must be fused to handle double-ended iterators. -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Chain -where - A: FusedIterator, - B: FusedIterator, -{ -} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for Chain -where - A: TrustedLen, - B: TrustedLen, -{ -} - -#[stable(feature = "default_iters", since = "1.70.0")] -impl Default for Chain { - /// Creates a `Chain` from the default values for `A` and `B`. - /// - /// ``` - /// # use core::iter::Chain; - /// # use core::slice; - /// # use std::collections::{btree_set, BTreeSet}; - /// # use std::mem; - /// struct Foo<'a>(Chain, btree_set::Iter<'a, u8>>); - /// - /// let set = BTreeSet::::new(); - /// let slice: &[u8] = &[]; - /// let mut foo = Foo(slice.iter().chain(set.iter())); - /// - /// // take requires `Default` - /// let _: Chain<_, _> = mem::take(&mut foo.0); - fn default() -> Self { - Chain::new(Default::default(), Default::default()) - } -} - -#[inline] -fn and_then_or_clear(opt: &mut Option, f: impl FnOnce(&mut T) -> Option) -> Option { - let x = f(opt.as_mut()?); - if x.is_none() { - *opt = None; - } - x -} diff --git a/library/core/src/iter/adapters/cloned.rs b/library/core/src/iter/adapters/cloned.rs deleted file mode 100644 index 1a106ef97942b..0000000000000 --- a/library/core/src/iter/adapters/cloned.rs +++ /dev/null @@ -1,190 +0,0 @@ -use crate::iter::adapters::{ - zip::try_get_unchecked, SourceIter, TrustedRandomAccess, TrustedRandomAccessNoCoerce, -}; -use crate::iter::{FusedIterator, InPlaceIterable, TrustedLen, UncheckedIterator}; -use crate::ops::Try; -use core::num::NonZero; - -/// An iterator that clones the elements of an underlying iterator. -/// -/// This `struct` is created by the [`cloned`] method on [`Iterator`]. See its -/// documentation for more. -/// -/// [`cloned`]: Iterator::cloned -/// [`Iterator`]: trait.Iterator.html -#[stable(feature = "iter_cloned", since = "1.1.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[derive(Clone, Debug)] -pub struct Cloned { - it: I, -} - -impl Cloned { - pub(in crate::iter) fn new(it: I) -> Cloned { - Cloned { it } - } -} - -fn clone_try_fold(mut f: impl FnMut(Acc, T) -> R) -> impl FnMut(Acc, &T) -> R { - move |acc, elt| f(acc, elt.clone()) -} - -#[stable(feature = "iter_cloned", since = "1.1.0")] -impl<'a, I, T: 'a> Iterator for Cloned -where - I: Iterator, - T: Clone, -{ - type Item = T; - - fn next(&mut self) -> Option { - self.it.next().cloned() - } - - fn size_hint(&self) -> (usize, Option) { - self.it.size_hint() - } - - fn try_fold(&mut self, init: B, f: F) -> R - where - Self: Sized, - F: FnMut(B, Self::Item) -> R, - R: Try, - { - self.it.try_fold(init, clone_try_fold(f)) - } - - fn fold(self, init: Acc, f: F) -> Acc - where - F: FnMut(Acc, Self::Item) -> Acc, - { - self.it.map(T::clone).fold(init, f) - } - - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> T - where - Self: TrustedRandomAccessNoCoerce, - { - // SAFETY: the caller must uphold the contract for - // `Iterator::__iterator_get_unchecked`. - unsafe { try_get_unchecked(&mut self.it, idx).clone() } - } -} - -#[stable(feature = "iter_cloned", since = "1.1.0")] -impl<'a, I, T: 'a> DoubleEndedIterator for Cloned -where - I: DoubleEndedIterator, - T: Clone, -{ - fn next_back(&mut self) -> Option { - self.it.next_back().cloned() - } - - fn try_rfold(&mut self, init: B, f: F) -> R - where - Self: Sized, - F: FnMut(B, Self::Item) -> R, - R: Try, - { - self.it.try_rfold(init, clone_try_fold(f)) - } - - fn rfold(self, init: Acc, f: F) -> Acc - where - F: FnMut(Acc, Self::Item) -> Acc, - { - self.it.map(T::clone).rfold(init, f) - } -} - -#[stable(feature = "iter_cloned", since = "1.1.0")] -impl<'a, I, T: 'a> ExactSizeIterator for Cloned -where - I: ExactSizeIterator, - T: Clone, -{ - fn len(&self) -> usize { - self.it.len() - } - - fn is_empty(&self) -> bool { - self.it.is_empty() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl<'a, I, T: 'a> FusedIterator for Cloned -where - I: FusedIterator, - T: Clone, -{ -} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl TrustedRandomAccess for Cloned where I: TrustedRandomAccess {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl TrustedRandomAccessNoCoerce for Cloned -where - I: TrustedRandomAccessNoCoerce, -{ - const MAY_HAVE_SIDE_EFFECT: bool = true; -} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl<'a, I, T: 'a> TrustedLen for Cloned -where - I: TrustedLen, - T: Clone, -{ -} - -impl<'a, I, T: 'a> UncheckedIterator for Cloned -where - I: UncheckedIterator, - T: Clone, -{ - unsafe fn next_unchecked(&mut self) -> T { - // SAFETY: `Cloned` is 1:1 with the inner iterator, so if the caller promised - // that there's an element left, the inner iterator has one too. - let item = unsafe { self.it.next_unchecked() }; - item.clone() - } -} - -#[stable(feature = "default_iters", since = "1.70.0")] -impl Default for Cloned { - /// Creates a `Cloned` iterator from the default value of `I` - /// ``` - /// # use core::slice; - /// # use core::iter::Cloned; - /// let iter: Cloned> = Default::default(); - /// assert_eq!(iter.len(), 0); - /// ``` - fn default() -> Self { - Self::new(Default::default()) - } -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl SourceIter for Cloned -where - I: SourceIter, -{ - type Source = I::Source; - - #[inline] - unsafe fn as_inner(&mut self) -> &mut I::Source { - // SAFETY: unsafe function forwarding to unsafe function with the same requirements - unsafe { SourceIter::as_inner(&mut self.it) } - } -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl InPlaceIterable for Cloned { - const EXPAND_BY: Option> = I::EXPAND_BY; - const MERGE_BY: Option> = I::MERGE_BY; -} diff --git a/library/core/src/iter/adapters/copied.rs b/library/core/src/iter/adapters/copied.rs deleted file mode 100644 index 6d82d1581f79d..0000000000000 --- a/library/core/src/iter/adapters/copied.rs +++ /dev/null @@ -1,277 +0,0 @@ -use crate::iter::adapters::{ - zip::try_get_unchecked, SourceIter, TrustedRandomAccess, TrustedRandomAccessNoCoerce, -}; -use crate::iter::{FusedIterator, InPlaceIterable, TrustedLen}; -use crate::mem::MaybeUninit; -use crate::mem::SizedTypeProperties; -use crate::num::NonZero; -use crate::ops::Try; -use crate::{array, ptr}; - -/// An iterator that copies the elements of an underlying iterator. -/// -/// This `struct` is created by the [`copied`] method on [`Iterator`]. See its -/// documentation for more. -/// -/// [`copied`]: Iterator::copied -/// [`Iterator`]: trait.Iterator.html -#[stable(feature = "iter_copied", since = "1.36.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[derive(Clone, Debug)] -pub struct Copied { - it: I, -} - -impl Copied { - pub(in crate::iter) fn new(it: I) -> Copied { - Copied { it } - } -} - -fn copy_fold(mut f: impl FnMut(Acc, T) -> Acc) -> impl FnMut(Acc, &T) -> Acc { - move |acc, &elt| f(acc, elt) -} - -fn copy_try_fold(mut f: impl FnMut(Acc, T) -> R) -> impl FnMut(Acc, &T) -> R { - move |acc, &elt| f(acc, elt) -} - -#[stable(feature = "iter_copied", since = "1.36.0")] -impl<'a, I, T: 'a> Iterator for Copied -where - I: Iterator, - T: Copy, -{ - type Item = T; - - fn next(&mut self) -> Option { - self.it.next().copied() - } - - fn next_chunk( - &mut self, - ) -> Result<[Self::Item; N], array::IntoIter> - where - Self: Sized, - { - >::spec_next_chunk(&mut self.it) - } - - fn size_hint(&self) -> (usize, Option) { - self.it.size_hint() - } - - fn try_fold(&mut self, init: B, f: F) -> R - where - Self: Sized, - F: FnMut(B, Self::Item) -> R, - R: Try, - { - self.it.try_fold(init, copy_try_fold(f)) - } - - fn fold(self, init: Acc, f: F) -> Acc - where - F: FnMut(Acc, Self::Item) -> Acc, - { - self.it.fold(init, copy_fold(f)) - } - - fn nth(&mut self, n: usize) -> Option { - self.it.nth(n).copied() - } - - fn last(self) -> Option { - self.it.last().copied() - } - - fn count(self) -> usize { - self.it.count() - } - - #[inline] - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - self.it.advance_by(n) - } - - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> T - where - Self: TrustedRandomAccessNoCoerce, - { - // SAFETY: the caller must uphold the contract for - // `Iterator::__iterator_get_unchecked`. - *unsafe { try_get_unchecked(&mut self.it, idx) } - } -} - -#[stable(feature = "iter_copied", since = "1.36.0")] -impl<'a, I, T: 'a> DoubleEndedIterator for Copied -where - I: DoubleEndedIterator, - T: Copy, -{ - fn next_back(&mut self) -> Option { - self.it.next_back().copied() - } - - fn try_rfold(&mut self, init: B, f: F) -> R - where - Self: Sized, - F: FnMut(B, Self::Item) -> R, - R: Try, - { - self.it.try_rfold(init, copy_try_fold(f)) - } - - fn rfold(self, init: Acc, f: F) -> Acc - where - F: FnMut(Acc, Self::Item) -> Acc, - { - self.it.rfold(init, copy_fold(f)) - } - - #[inline] - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - self.it.advance_back_by(n) - } -} - -#[stable(feature = "iter_copied", since = "1.36.0")] -impl<'a, I, T: 'a> ExactSizeIterator for Copied -where - I: ExactSizeIterator, - T: Copy, -{ - fn len(&self) -> usize { - self.it.len() - } - - fn is_empty(&self) -> bool { - self.it.is_empty() - } -} - -#[stable(feature = "iter_copied", since = "1.36.0")] -impl<'a, I, T: 'a> FusedIterator for Copied -where - I: FusedIterator, - T: Copy, -{ -} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl TrustedRandomAccess for Copied where I: TrustedRandomAccess {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl TrustedRandomAccessNoCoerce for Copied -where - I: TrustedRandomAccessNoCoerce, -{ - const MAY_HAVE_SIDE_EFFECT: bool = I::MAY_HAVE_SIDE_EFFECT; -} - -#[stable(feature = "iter_copied", since = "1.36.0")] -unsafe impl<'a, I, T: 'a> TrustedLen for Copied -where - I: TrustedLen, - T: Copy, -{ -} - -trait SpecNextChunk<'a, const N: usize, T: 'a>: Iterator -where - T: Copy, -{ - fn spec_next_chunk(&mut self) -> Result<[T; N], array::IntoIter>; -} - -impl<'a, const N: usize, I, T: 'a> SpecNextChunk<'a, N, T> for I -where - I: Iterator, - T: Copy, -{ - default fn spec_next_chunk(&mut self) -> Result<[T; N], array::IntoIter> { - array::iter_next_chunk(&mut self.copied()) - } -} - -impl<'a, const N: usize, T: 'a> SpecNextChunk<'a, N, T> for crate::slice::Iter<'a, T> -where - T: Copy, -{ - fn spec_next_chunk(&mut self) -> Result<[T; N], array::IntoIter> { - let mut raw_array = MaybeUninit::uninit_array(); - - let len = self.len(); - - if T::IS_ZST { - if len < N { - let _ = self.advance_by(len); - // SAFETY: ZSTs can be conjured ex nihilo; only the amount has to be correct - return Err(unsafe { array::IntoIter::new_unchecked(raw_array, 0..len) }); - } - - let _ = self.advance_by(N); - // SAFETY: ditto - return Ok(unsafe { MaybeUninit::array_assume_init(raw_array) }); - } - - if len < N { - // SAFETY: `len` indicates that this many elements are available and we just checked that - // it fits into the array. - unsafe { - ptr::copy_nonoverlapping( - self.as_ref().as_ptr(), - raw_array.as_mut_ptr() as *mut T, - len, - ); - let _ = self.advance_by(len); - return Err(array::IntoIter::new_unchecked(raw_array, 0..len)); - } - } - - // SAFETY: `len` is larger than the array size. Copy a fixed amount here to fully initialize - // the array. - unsafe { - ptr::copy_nonoverlapping(self.as_ref().as_ptr(), raw_array.as_mut_ptr() as *mut T, N); - let _ = self.advance_by(N); - Ok(MaybeUninit::array_assume_init(raw_array)) - } - } -} - -#[stable(feature = "default_iters", since = "1.70.0")] -impl Default for Copied { - /// Creates a `Copied` iterator from the default value of `I` - /// ``` - /// # use core::slice; - /// # use core::iter::Copied; - /// let iter: Copied> = Default::default(); - /// assert_eq!(iter.len(), 0); - /// ``` - fn default() -> Self { - Self::new(Default::default()) - } -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl SourceIter for Copied -where - I: SourceIter, -{ - type Source = I::Source; - - #[inline] - unsafe fn as_inner(&mut self) -> &mut I::Source { - // SAFETY: unsafe function forwarding to unsafe function with the same requirements - unsafe { SourceIter::as_inner(&mut self.it) } - } -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl InPlaceIterable for Copied { - const EXPAND_BY: Option> = I::EXPAND_BY; - const MERGE_BY: Option> = I::MERGE_BY; -} diff --git a/library/core/src/iter/adapters/cycle.rs b/library/core/src/iter/adapters/cycle.rs deleted file mode 100644 index b35ed8442032d..0000000000000 --- a/library/core/src/iter/adapters/cycle.rs +++ /dev/null @@ -1,108 +0,0 @@ -use crate::num::NonZero; -use crate::{iter::FusedIterator, ops::Try}; - -/// An iterator that repeats endlessly. -/// -/// This `struct` is created by the [`cycle`] method on [`Iterator`]. See its -/// documentation for more. -/// -/// [`cycle`]: Iterator::cycle -/// [`Iterator`]: trait.Iterator.html -#[derive(Clone, Debug)] -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Cycle { - orig: I, - iter: I, -} - -impl Cycle { - pub(in crate::iter) fn new(iter: I) -> Cycle { - Cycle { orig: iter.clone(), iter } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for Cycle -where - I: Clone + Iterator, -{ - type Item = ::Item; - - #[inline] - fn next(&mut self) -> Option<::Item> { - match self.iter.next() { - None => { - self.iter = self.orig.clone(); - self.iter.next() - } - y => y, - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - // the cycle iterator is either empty or infinite - match self.orig.size_hint() { - sz @ (0, Some(0)) => sz, - (0, _) => (0, None), - _ => (usize::MAX, None), - } - } - - #[inline] - fn try_fold(&mut self, mut acc: Acc, mut f: F) -> R - where - F: FnMut(Acc, Self::Item) -> R, - R: Try, - { - // fully iterate the current iterator. this is necessary because - // `self.iter` may be empty even when `self.orig` isn't - acc = self.iter.try_fold(acc, &mut f)?; - self.iter = self.orig.clone(); - - // complete a full cycle, keeping track of whether the cycled - // iterator is empty or not. we need to return early in case - // of an empty iterator to prevent an infinite loop - let mut is_empty = true; - acc = self.iter.try_fold(acc, |acc, x| { - is_empty = false; - f(acc, x) - })?; - - if is_empty { - return try { acc }; - } - - loop { - self.iter = self.orig.clone(); - acc = self.iter.try_fold(acc, &mut f)?; - } - } - - #[inline] - #[rustc_inherit_overflow_checks] - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - let mut n = match self.iter.advance_by(n) { - Ok(()) => return Ok(()), - Err(rem) => rem.get(), - }; - - while n > 0 { - self.iter = self.orig.clone(); - n = match self.iter.advance_by(n) { - Ok(()) => return Ok(()), - e @ Err(rem) if rem.get() == n => return e, - Err(rem) => rem.get(), - }; - } - - NonZero::new(n).map_or(Ok(()), Err) - } - - // No `fold` override, because `fold` doesn't make much sense for `Cycle`, - // and we can't do anything better than the default. -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Cycle where I: Clone + Iterator {} diff --git a/library/core/src/iter/adapters/enumerate.rs b/library/core/src/iter/adapters/enumerate.rs deleted file mode 100644 index 7adbabf69e490..0000000000000 --- a/library/core/src/iter/adapters/enumerate.rs +++ /dev/null @@ -1,285 +0,0 @@ -use crate::iter::adapters::{ - zip::try_get_unchecked, SourceIter, TrustedRandomAccess, TrustedRandomAccessNoCoerce, -}; -use crate::iter::{FusedIterator, InPlaceIterable, TrustedFused, TrustedLen}; -use crate::num::NonZero; -use crate::ops::Try; - -/// An iterator that yields the current count and the element during iteration. -/// -/// This `struct` is created by the [`enumerate`] method on [`Iterator`]. See its -/// documentation for more. -/// -/// [`enumerate`]: Iterator::enumerate -/// [`Iterator`]: trait.Iterator.html -#[derive(Clone, Debug)] -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "Enumerate")] -pub struct Enumerate { - iter: I, - count: usize, -} -impl Enumerate { - pub(in crate::iter) fn new(iter: I) -> Enumerate { - Enumerate { iter, count: 0 } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for Enumerate -where - I: Iterator, -{ - type Item = (usize, ::Item); - - /// # Overflow Behavior - /// - /// The method does no guarding against overflows, so enumerating more than - /// `usize::MAX` elements either produces the wrong result or panics. If - /// debug assertions are enabled, a panic is guaranteed. - /// - /// # Panics - /// - /// Might panic if the index of the element overflows a `usize`. - #[inline] - #[rustc_inherit_overflow_checks] - fn next(&mut self) -> Option<(usize, ::Item)> { - let a = self.iter.next()?; - let i = self.count; - self.count += 1; - Some((i, a)) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } - - #[inline] - #[rustc_inherit_overflow_checks] - fn nth(&mut self, n: usize) -> Option<(usize, I::Item)> { - let a = self.iter.nth(n)?; - let i = self.count + n; - self.count = i + 1; - Some((i, a)) - } - - #[inline] - fn count(self) -> usize { - self.iter.count() - } - - #[inline] - fn try_fold(&mut self, init: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - #[inline] - fn enumerate<'a, T, Acc, R>( - count: &'a mut usize, - mut fold: impl FnMut(Acc, (usize, T)) -> R + 'a, - ) -> impl FnMut(Acc, T) -> R + 'a { - #[rustc_inherit_overflow_checks] - move |acc, item| { - let acc = fold(acc, (*count, item)); - *count += 1; - acc - } - } - - self.iter.try_fold(init, enumerate(&mut self.count, fold)) - } - - #[inline] - fn fold(self, init: Acc, fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - #[inline] - fn enumerate( - mut count: usize, - mut fold: impl FnMut(Acc, (usize, T)) -> Acc, - ) -> impl FnMut(Acc, T) -> Acc { - #[rustc_inherit_overflow_checks] - move |acc, item| { - let acc = fold(acc, (count, item)); - count += 1; - acc - } - } - - self.iter.fold(init, enumerate(self.count, fold)) - } - - #[inline] - #[rustc_inherit_overflow_checks] - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - let remaining = self.iter.advance_by(n); - let advanced = match remaining { - Ok(()) => n, - Err(rem) => n - rem.get(), - }; - self.count += advanced; - remaining - } - - #[rustc_inherit_overflow_checks] - #[inline] - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> ::Item - where - Self: TrustedRandomAccessNoCoerce, - { - // SAFETY: the caller must uphold the contract for - // `Iterator::__iterator_get_unchecked`. - let value = unsafe { try_get_unchecked(&mut self.iter, idx) }; - (self.count + idx, value) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DoubleEndedIterator for Enumerate -where - I: ExactSizeIterator + DoubleEndedIterator, -{ - #[inline] - fn next_back(&mut self) -> Option<(usize, ::Item)> { - let a = self.iter.next_back()?; - let len = self.iter.len(); - // Can safely add, `ExactSizeIterator` promises that the number of - // elements fits into a `usize`. - Some((self.count + len, a)) - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option<(usize, ::Item)> { - let a = self.iter.nth_back(n)?; - let len = self.iter.len(); - // Can safely add, `ExactSizeIterator` promises that the number of - // elements fits into a `usize`. - Some((self.count + len, a)) - } - - #[inline] - fn try_rfold(&mut self, init: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - // Can safely add and subtract the count, as `ExactSizeIterator` promises - // that the number of elements fits into a `usize`. - fn enumerate( - mut count: usize, - mut fold: impl FnMut(Acc, (usize, T)) -> R, - ) -> impl FnMut(Acc, T) -> R { - move |acc, item| { - count -= 1; - fold(acc, (count, item)) - } - } - - let count = self.count + self.iter.len(); - self.iter.try_rfold(init, enumerate(count, fold)) - } - - #[inline] - fn rfold(self, init: Acc, fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - // Can safely add and subtract the count, as `ExactSizeIterator` promises - // that the number of elements fits into a `usize`. - fn enumerate( - mut count: usize, - mut fold: impl FnMut(Acc, (usize, T)) -> Acc, - ) -> impl FnMut(Acc, T) -> Acc { - move |acc, item| { - count -= 1; - fold(acc, (count, item)) - } - } - - let count = self.count + self.iter.len(); - self.iter.rfold(init, enumerate(count, fold)) - } - - #[inline] - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - // we do not need to update the count since that only tallies the number of items - // consumed from the front. consuming items from the back can never reduce that. - self.iter.advance_back_by(n) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Enumerate -where - I: ExactSizeIterator, -{ - fn len(&self) -> usize { - self.iter.len() - } - - fn is_empty(&self) -> bool { - self.iter.is_empty() - } -} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl TrustedRandomAccess for Enumerate where I: TrustedRandomAccess {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl TrustedRandomAccessNoCoerce for Enumerate -where - I: TrustedRandomAccessNoCoerce, -{ - const MAY_HAVE_SIDE_EFFECT: bool = I::MAY_HAVE_SIDE_EFFECT; -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Enumerate where I: FusedIterator {} - -#[unstable(issue = "none", feature = "trusted_fused")] -unsafe impl TrustedFused for Enumerate {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for Enumerate where I: TrustedLen {} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl SourceIter for Enumerate -where - I: SourceIter, -{ - type Source = I::Source; - - #[inline] - unsafe fn as_inner(&mut self) -> &mut I::Source { - // SAFETY: unsafe function forwarding to unsafe function with the same requirements - unsafe { SourceIter::as_inner(&mut self.iter) } - } -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl InPlaceIterable for Enumerate { - const EXPAND_BY: Option> = I::EXPAND_BY; - const MERGE_BY: Option> = I::MERGE_BY; -} - -#[stable(feature = "default_iters", since = "1.70.0")] -impl Default for Enumerate { - /// Creates an `Enumerate` iterator from the default value of `I` - /// ``` - /// # use core::slice; - /// # use std::iter::Enumerate; - /// let iter: Enumerate> = Default::default(); - /// assert_eq!(iter.len(), 0); - /// ``` - fn default() -> Self { - Enumerate::new(Default::default()) - } -} diff --git a/library/core/src/iter/adapters/filter.rs b/library/core/src/iter/adapters/filter.rs deleted file mode 100644 index a7f1fde6975c0..0000000000000 --- a/library/core/src/iter/adapters/filter.rs +++ /dev/null @@ -1,214 +0,0 @@ -use crate::fmt; -use crate::iter::{adapters::SourceIter, FusedIterator, InPlaceIterable, TrustedFused}; -use crate::num::NonZero; -use crate::ops::Try; -use core::array; -use core::mem::{ManuallyDrop, MaybeUninit}; -use core::ops::ControlFlow; - -/// An iterator that filters the elements of `iter` with `predicate`. -/// -/// This `struct` is created by the [`filter`] method on [`Iterator`]. See its -/// documentation for more. -/// -/// [`filter`]: Iterator::filter -/// [`Iterator`]: trait.Iterator.html -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Clone)] -pub struct Filter { - // Used for `SplitWhitespace` and `SplitAsciiWhitespace` `as_str` methods - pub(crate) iter: I, - predicate: P, -} -impl Filter { - pub(in crate::iter) fn new(iter: I, predicate: P) -> Filter { - Filter { iter, predicate } - } -} - -#[stable(feature = "core_impl_debug", since = "1.9.0")] -impl fmt::Debug for Filter { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Filter").field("iter", &self.iter).finish() - } -} - -fn filter_fold( - mut predicate: impl FnMut(&T) -> bool, - mut fold: impl FnMut(Acc, T) -> Acc, -) -> impl FnMut(Acc, T) -> Acc { - move |acc, item| if predicate(&item) { fold(acc, item) } else { acc } -} - -fn filter_try_fold<'a, T, Acc, R: Try>( - predicate: &'a mut impl FnMut(&T) -> bool, - mut fold: impl FnMut(Acc, T) -> R + 'a, -) -> impl FnMut(Acc, T) -> R + 'a { - move |acc, item| if predicate(&item) { fold(acc, item) } else { try { acc } } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for Filter -where - P: FnMut(&I::Item) -> bool, -{ - type Item = I::Item; - - #[inline] - fn next(&mut self) -> Option { - self.iter.find(&mut self.predicate) - } - - #[inline] - fn next_chunk( - &mut self, - ) -> Result<[Self::Item; N], array::IntoIter> { - let mut array: [MaybeUninit; N] = MaybeUninit::uninit_array(); - - struct Guard<'a, T> { - array: &'a mut [MaybeUninit], - initialized: usize, - } - - impl Drop for Guard<'_, T> { - #[inline] - fn drop(&mut self) { - if const { crate::mem::needs_drop::() } { - // SAFETY: self.initialized is always <= N, which also is the length of the array. - unsafe { - core::ptr::drop_in_place(MaybeUninit::slice_assume_init_mut( - self.array.get_unchecked_mut(..self.initialized), - )); - } - } - } - } - - let mut guard = Guard { array: &mut array, initialized: 0 }; - - let result = self.iter.try_for_each(|element| { - let idx = guard.initialized; - guard.initialized = idx + (self.predicate)(&element) as usize; - - // SAFETY: Loop conditions ensure the index is in bounds. - unsafe { guard.array.get_unchecked_mut(idx) }.write(element); - - if guard.initialized < N { ControlFlow::Continue(()) } else { ControlFlow::Break(()) } - }); - - let guard = ManuallyDrop::new(guard); - - match result { - ControlFlow::Break(()) => { - // SAFETY: The loop above is only explicitly broken when the array has been fully initialized - Ok(unsafe { MaybeUninit::array_assume_init(array) }) - } - ControlFlow::Continue(()) => { - let initialized = guard.initialized; - // SAFETY: The range is in bounds since the loop breaks when reaching N elements. - Err(unsafe { array::IntoIter::new_unchecked(array, 0..initialized) }) - } - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let (_, upper) = self.iter.size_hint(); - (0, upper) // can't know a lower bound, due to the predicate - } - - // this special case allows the compiler to make `.filter(_).count()` - // branchless. Barring perfect branch prediction (which is unattainable in - // the general case), this will be much faster in >90% of cases (containing - // virtually all real workloads) and only a tiny bit slower in the rest. - // - // Having this specialization thus allows us to write `.filter(p).count()` - // where we would otherwise write `.map(|x| p(x) as usize).sum()`, which is - // less readable and also less backwards-compatible to Rust before 1.10. - // - // Using the branchless version will also simplify the LLVM byte code, thus - // leaving more budget for LLVM optimizations. - #[inline] - fn count(self) -> usize { - #[inline] - fn to_usize(mut predicate: impl FnMut(&T) -> bool) -> impl FnMut(T) -> usize { - move |x| predicate(&x) as usize - } - - self.iter.map(to_usize(self.predicate)).sum() - } - - #[inline] - fn try_fold(&mut self, init: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - self.iter.try_fold(init, filter_try_fold(&mut self.predicate, fold)) - } - - #[inline] - fn fold(self, init: Acc, fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - self.iter.fold(init, filter_fold(self.predicate, fold)) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DoubleEndedIterator for Filter -where - P: FnMut(&I::Item) -> bool, -{ - #[inline] - fn next_back(&mut self) -> Option { - self.iter.rfind(&mut self.predicate) - } - - #[inline] - fn try_rfold(&mut self, init: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - self.iter.try_rfold(init, filter_try_fold(&mut self.predicate, fold)) - } - - #[inline] - fn rfold(self, init: Acc, fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - self.iter.rfold(init, filter_fold(self.predicate, fold)) - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Filter where P: FnMut(&I::Item) -> bool {} - -#[unstable(issue = "none", feature = "trusted_fused")] -unsafe impl TrustedFused for Filter {} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl SourceIter for Filter -where - I: SourceIter, -{ - type Source = I::Source; - - #[inline] - unsafe fn as_inner(&mut self) -> &mut I::Source { - // SAFETY: unsafe function forwarding to unsafe function with the same requirements - unsafe { SourceIter::as_inner(&mut self.iter) } - } -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl InPlaceIterable for Filter { - const EXPAND_BY: Option> = I::EXPAND_BY; - const MERGE_BY: Option> = I::MERGE_BY; -} diff --git a/library/core/src/iter/adapters/filter_map.rs b/library/core/src/iter/adapters/filter_map.rs deleted file mode 100644 index 1a5f9e6265454..0000000000000 --- a/library/core/src/iter/adapters/filter_map.rs +++ /dev/null @@ -1,215 +0,0 @@ -use crate::iter::{adapters::SourceIter, FusedIterator, InPlaceIterable, TrustedFused}; -use crate::mem::{ManuallyDrop, MaybeUninit}; -use crate::num::NonZero; -use crate::ops::{ControlFlow, Try}; -use crate::ptr::addr_of; -use crate::{array, fmt}; - -/// An iterator that uses `f` to both filter and map elements from `iter`. -/// -/// This `struct` is created by the [`filter_map`] method on [`Iterator`]. See its -/// documentation for more. -/// -/// [`filter_map`]: Iterator::filter_map -/// [`Iterator`]: trait.Iterator.html -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Clone)] -pub struct FilterMap { - iter: I, - f: F, -} -impl FilterMap { - pub(in crate::iter) fn new(iter: I, f: F) -> FilterMap { - FilterMap { iter, f } - } -} - -#[stable(feature = "core_impl_debug", since = "1.9.0")] -impl fmt::Debug for FilterMap { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("FilterMap").field("iter", &self.iter).finish() - } -} - -fn filter_map_fold( - mut f: impl FnMut(T) -> Option, - mut fold: impl FnMut(Acc, B) -> Acc, -) -> impl FnMut(Acc, T) -> Acc { - move |acc, item| match f(item) { - Some(x) => fold(acc, x), - None => acc, - } -} - -fn filter_map_try_fold<'a, T, B, Acc, R: Try>( - f: &'a mut impl FnMut(T) -> Option, - mut fold: impl FnMut(Acc, B) -> R + 'a, -) -> impl FnMut(Acc, T) -> R + 'a { - move |acc, item| match f(item) { - Some(x) => fold(acc, x), - None => try { acc }, - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for FilterMap -where - F: FnMut(I::Item) -> Option, -{ - type Item = B; - - #[inline] - fn next(&mut self) -> Option { - self.iter.find_map(&mut self.f) - } - - #[inline] - fn next_chunk( - &mut self, - ) -> Result<[Self::Item; N], array::IntoIter> { - let mut array: [MaybeUninit; N] = MaybeUninit::uninit_array(); - - struct Guard<'a, T> { - array: &'a mut [MaybeUninit], - initialized: usize, - } - - impl Drop for Guard<'_, T> { - #[inline] - fn drop(&mut self) { - if const { crate::mem::needs_drop::() } { - // SAFETY: self.initialized is always <= N, which also is the length of the array. - unsafe { - core::ptr::drop_in_place(MaybeUninit::slice_assume_init_mut( - self.array.get_unchecked_mut(..self.initialized), - )); - } - } - } - } - - let mut guard = Guard { array: &mut array, initialized: 0 }; - - let result = self.iter.try_for_each(|element| { - let idx = guard.initialized; - let val = (self.f)(element); - guard.initialized = idx + val.is_some() as usize; - - // SAFETY: Loop conditions ensure the index is in bounds. - - unsafe { - let opt_payload_at: *const MaybeUninit = - addr_of!(val).byte_add(core::mem::offset_of!(Option, Some.0)).cast(); - let dst = guard.array.as_mut_ptr().add(idx); - crate::ptr::copy_nonoverlapping(opt_payload_at, dst, 1); - crate::mem::forget(val); - }; - - if guard.initialized < N { ControlFlow::Continue(()) } else { ControlFlow::Break(()) } - }); - - let guard = ManuallyDrop::new(guard); - - match result { - ControlFlow::Break(()) => { - // SAFETY: The loop above is only explicitly broken when the array has been fully initialized - Ok(unsafe { MaybeUninit::array_assume_init(array) }) - } - ControlFlow::Continue(()) => { - let initialized = guard.initialized; - // SAFETY: The range is in bounds since the loop breaks when reaching N elements. - Err(unsafe { array::IntoIter::new_unchecked(array, 0..initialized) }) - } - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let (_, upper) = self.iter.size_hint(); - (0, upper) // can't know a lower bound, due to the predicate - } - - #[inline] - fn try_fold(&mut self, init: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - self.iter.try_fold(init, filter_map_try_fold(&mut self.f, fold)) - } - - #[inline] - fn fold(self, init: Acc, fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - self.iter.fold(init, filter_map_fold(self.f, fold)) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DoubleEndedIterator for FilterMap -where - F: FnMut(I::Item) -> Option, -{ - #[inline] - fn next_back(&mut self) -> Option { - #[inline] - fn find( - f: &mut impl FnMut(T) -> Option, - ) -> impl FnMut((), T) -> ControlFlow + '_ { - move |(), x| match f(x) { - Some(x) => ControlFlow::Break(x), - None => ControlFlow::Continue(()), - } - } - - self.iter.try_rfold((), find(&mut self.f)).break_value() - } - - #[inline] - fn try_rfold(&mut self, init: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - self.iter.try_rfold(init, filter_map_try_fold(&mut self.f, fold)) - } - - #[inline] - fn rfold(self, init: Acc, fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - self.iter.rfold(init, filter_map_fold(self.f, fold)) - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for FilterMap where F: FnMut(I::Item) -> Option {} - -#[unstable(issue = "none", feature = "trusted_fused")] -unsafe impl TrustedFused for FilterMap {} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl SourceIter for FilterMap -where - I: SourceIter, -{ - type Source = I::Source; - - #[inline] - unsafe fn as_inner(&mut self) -> &mut I::Source { - // SAFETY: unsafe function forwarding to unsafe function with the same requirements - unsafe { SourceIter::as_inner(&mut self.iter) } - } -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl InPlaceIterable for FilterMap { - const EXPAND_BY: Option> = I::EXPAND_BY; - const MERGE_BY: Option> = I::MERGE_BY; -} diff --git a/library/core/src/iter/adapters/flatten.rs b/library/core/src/iter/adapters/flatten.rs deleted file mode 100644 index 145c9d3dacc84..0000000000000 --- a/library/core/src/iter/adapters/flatten.rs +++ /dev/null @@ -1,1040 +0,0 @@ -use crate::iter::adapters::SourceIter; -use crate::iter::{ - Cloned, Copied, Filter, FilterMap, Fuse, FusedIterator, InPlaceIterable, Map, TrustedFused, - TrustedLen, -}; -use crate::iter::{Empty, Once, OnceWith}; -use crate::num::NonZero; -use crate::ops::{ControlFlow, Try}; -use crate::result; -use crate::{array, fmt, option}; - -/// An iterator that maps each element to an iterator, and yields the elements -/// of the produced iterators. -/// -/// This `struct` is created by [`Iterator::flat_map`]. See its documentation -/// for more. -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct FlatMap { - inner: FlattenCompat, ::IntoIter>, -} - -impl U> FlatMap { - pub(in crate::iter) fn new(iter: I, f: F) -> FlatMap { - FlatMap { inner: FlattenCompat::new(iter.map(f)) } - } - - pub(crate) fn into_parts(self) -> (Option, Option, Option) { - ( - self.inner.frontiter, - self.inner.iter.into_inner().map(Map::into_inner), - self.inner.backiter, - ) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for FlatMap -where - U: Clone + IntoIterator, -{ - fn clone(&self) -> Self { - FlatMap { inner: self.inner.clone() } - } -} - -#[stable(feature = "core_impl_debug", since = "1.9.0")] -impl fmt::Debug for FlatMap -where - U: IntoIterator, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("FlatMap").field("inner", &self.inner).finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for FlatMap -where - F: FnMut(I::Item) -> U, -{ - type Item = U::Item; - - #[inline] - fn next(&mut self) -> Option { - self.inner.next() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } - - #[inline] - fn try_fold(&mut self, init: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - self.inner.try_fold(init, fold) - } - - #[inline] - fn fold(self, init: Acc, fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - self.inner.fold(init, fold) - } - - #[inline] - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - self.inner.advance_by(n) - } - - #[inline] - fn count(self) -> usize { - self.inner.count() - } - - #[inline] - fn last(self) -> Option { - self.inner.last() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DoubleEndedIterator for FlatMap -where - F: FnMut(I::Item) -> U, - U: IntoIterator, -{ - #[inline] - fn next_back(&mut self) -> Option { - self.inner.next_back() - } - - #[inline] - fn try_rfold(&mut self, init: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - self.inner.try_rfold(init, fold) - } - - #[inline] - fn rfold(self, init: Acc, fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - self.inner.rfold(init, fold) - } - - #[inline] - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - self.inner.advance_back_by(n) - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for FlatMap -where - I: FusedIterator, - U: IntoIterator, - F: FnMut(I::Item) -> U, -{ -} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for FlatMap -where - I: Iterator, - U: IntoIterator, - F: FnMut(I::Item) -> U, - FlattenCompat, ::IntoIter>: TrustedLen, -{ -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl InPlaceIterable for FlatMap -where - I: InPlaceIterable, - U: BoundedSize + IntoIterator, -{ - const EXPAND_BY: Option> = const { - match (I::EXPAND_BY, U::UPPER_BOUND) { - (Some(m), Some(n)) => m.checked_mul(n), - _ => None, - } - }; - const MERGE_BY: Option> = I::MERGE_BY; -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl SourceIter for FlatMap -where - I: SourceIter + TrustedFused, - U: IntoIterator, -{ - type Source = I::Source; - - #[inline] - unsafe fn as_inner(&mut self) -> &mut I::Source { - // SAFETY: unsafe function forwarding to unsafe function with the same requirements - unsafe { SourceIter::as_inner(&mut self.inner.iter) } - } -} - -/// Marker trait for iterators/iterables which have a statically known upper -/// bound of the number of items they can produce. -/// -/// # Safety -/// -/// Implementations must not yield more elements than indicated by UPPER_BOUND if it is `Some`. -/// Used in specializations. Implementations must not be conditional on lifetimes or -/// user-implementable traits. -#[rustc_specialization_trait] -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe trait BoundedSize { - const UPPER_BOUND: Option> = NonZero::new(1); -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl BoundedSize for Option {} -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl BoundedSize for option::IntoIter {} -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl BoundedSize for Result {} -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl BoundedSize for result::IntoIter {} -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl BoundedSize for Once {} -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl BoundedSize for OnceWith {} -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl BoundedSize for [T; N] { - const UPPER_BOUND: Option> = NonZero::new(N); -} -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl BoundedSize for array::IntoIter { - const UPPER_BOUND: Option> = NonZero::new(N); -} -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl BoundedSize for Filter { - const UPPER_BOUND: Option> = I::UPPER_BOUND; -} -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl BoundedSize for FilterMap { - const UPPER_BOUND: Option> = I::UPPER_BOUND; -} -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl BoundedSize for Map { - const UPPER_BOUND: Option> = I::UPPER_BOUND; -} -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl BoundedSize for Copied { - const UPPER_BOUND: Option> = I::UPPER_BOUND; -} -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl BoundedSize for Cloned { - const UPPER_BOUND: Option> = I::UPPER_BOUND; -} - -/// An iterator that flattens one level of nesting in an iterator of things -/// that can be turned into iterators. -/// -/// This `struct` is created by the [`flatten`] method on [`Iterator`]. See its -/// documentation for more. -/// -/// [`flatten`]: Iterator::flatten() -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "iterator_flatten", since = "1.29.0")] -pub struct Flatten> { - inner: FlattenCompat::IntoIter>, -} - -impl> Flatten { - pub(in super::super) fn new(iter: I) -> Flatten { - Flatten { inner: FlattenCompat::new(iter) } - } -} - -#[stable(feature = "iterator_flatten", since = "1.29.0")] -impl fmt::Debug for Flatten -where - I: fmt::Debug + Iterator>, - U: fmt::Debug + Iterator, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Flatten").field("inner", &self.inner).finish() - } -} - -#[stable(feature = "iterator_flatten", since = "1.29.0")] -impl Clone for Flatten -where - I: Clone + Iterator>, - U: Clone + Iterator, -{ - fn clone(&self) -> Self { - Flatten { inner: self.inner.clone() } - } -} - -#[stable(feature = "iterator_flatten", since = "1.29.0")] -impl Iterator for Flatten -where - I: Iterator>, - U: Iterator, -{ - type Item = U::Item; - - #[inline] - fn next(&mut self) -> Option { - self.inner.next() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } - - #[inline] - fn try_fold(&mut self, init: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - self.inner.try_fold(init, fold) - } - - #[inline] - fn fold(self, init: Acc, fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - self.inner.fold(init, fold) - } - - #[inline] - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - self.inner.advance_by(n) - } - - #[inline] - fn count(self) -> usize { - self.inner.count() - } - - #[inline] - fn last(self) -> Option { - self.inner.last() - } -} - -#[stable(feature = "iterator_flatten", since = "1.29.0")] -impl DoubleEndedIterator for Flatten -where - I: DoubleEndedIterator>, - U: DoubleEndedIterator, -{ - #[inline] - fn next_back(&mut self) -> Option { - self.inner.next_back() - } - - #[inline] - fn try_rfold(&mut self, init: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - self.inner.try_rfold(init, fold) - } - - #[inline] - fn rfold(self, init: Acc, fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - self.inner.rfold(init, fold) - } - - #[inline] - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - self.inner.advance_back_by(n) - } -} - -#[stable(feature = "iterator_flatten", since = "1.29.0")] -impl FusedIterator for Flatten -where - I: FusedIterator>, - U: Iterator, -{ -} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for Flatten -where - I: Iterator, - FlattenCompat::IntoIter>: TrustedLen, -{ -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl InPlaceIterable for Flatten -where - I: InPlaceIterable + Iterator, - ::Item: IntoIterator + BoundedSize, -{ - const EXPAND_BY: Option> = const { - match (I::EXPAND_BY, I::Item::UPPER_BOUND) { - (Some(m), Some(n)) => m.checked_mul(n), - _ => None, - } - }; - const MERGE_BY: Option> = I::MERGE_BY; -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl SourceIter for Flatten -where - I: SourceIter + TrustedFused + Iterator, - ::Item: IntoIterator, -{ - type Source = I::Source; - - #[inline] - unsafe fn as_inner(&mut self) -> &mut I::Source { - // SAFETY: unsafe function forwarding to unsafe function with the same requirements - unsafe { SourceIter::as_inner(&mut self.inner.iter) } - } -} - -#[stable(feature = "default_iters", since = "1.70.0")] -impl Default for Flatten -where - I: Default + Iterator, -{ - /// Creates a `Flatten` iterator from the default value of `I`. - /// - /// ``` - /// # use core::slice; - /// # use std::iter::Flatten; - /// let iter: Flatten> = Default::default(); - /// assert_eq!(iter.count(), 0); - /// ``` - fn default() -> Self { - Flatten::new(Default::default()) - } -} - -/// Real logic of both `Flatten` and `FlatMap` which simply delegate to -/// this type. -#[derive(Clone, Debug)] -#[unstable(feature = "trusted_len", issue = "37572")] -struct FlattenCompat { - iter: Fuse, - frontiter: Option, - backiter: Option, -} -impl FlattenCompat -where - I: Iterator, -{ - /// Adapts an iterator by flattening it, for use in `flatten()` and `flat_map()`. - fn new(iter: I) -> FlattenCompat { - FlattenCompat { iter: iter.fuse(), frontiter: None, backiter: None } - } -} - -impl FlattenCompat -where - I: Iterator>, -{ - /// Folds the inner iterators into an accumulator by applying an operation. - /// - /// Folds over the inner iterators, not over their elements. Is used by the `fold`, `count`, - /// and `last` methods. - #[inline] - fn iter_fold(self, mut acc: Acc, mut fold: Fold) -> Acc - where - Fold: FnMut(Acc, U) -> Acc, - { - #[inline] - fn flatten( - fold: &mut impl FnMut(Acc, T::IntoIter) -> Acc, - ) -> impl FnMut(Acc, T) -> Acc + '_ { - move |acc, iter| fold(acc, iter.into_iter()) - } - - if let Some(iter) = self.frontiter { - acc = fold(acc, iter); - } - - acc = self.iter.fold(acc, flatten(&mut fold)); - - if let Some(iter) = self.backiter { - acc = fold(acc, iter); - } - - acc - } - - /// Folds over the inner iterators as long as the given function returns successfully, - /// always storing the most recent inner iterator in `self.frontiter`. - /// - /// Folds over the inner iterators, not over their elements. Is used by the `try_fold` and - /// `advance_by` methods. - #[inline] - fn iter_try_fold(&mut self, mut acc: Acc, mut fold: Fold) -> R - where - Fold: FnMut(Acc, &mut U) -> R, - R: Try, - { - #[inline] - fn flatten<'a, T: IntoIterator, Acc, R: Try>( - frontiter: &'a mut Option, - fold: &'a mut impl FnMut(Acc, &mut T::IntoIter) -> R, - ) -> impl FnMut(Acc, T) -> R + 'a { - move |acc, iter| fold(acc, frontiter.insert(iter.into_iter())) - } - - if let Some(iter) = &mut self.frontiter { - acc = fold(acc, iter)?; - } - self.frontiter = None; - - acc = self.iter.try_fold(acc, flatten(&mut self.frontiter, &mut fold))?; - self.frontiter = None; - - if let Some(iter) = &mut self.backiter { - acc = fold(acc, iter)?; - } - self.backiter = None; - - try { acc } - } -} - -impl FlattenCompat -where - I: DoubleEndedIterator>, -{ - /// Folds the inner iterators into an accumulator by applying an operation, starting form the - /// back. - /// - /// Folds over the inner iterators, not over their elements. Is used by the `rfold` method. - #[inline] - fn iter_rfold(self, mut acc: Acc, mut fold: Fold) -> Acc - where - Fold: FnMut(Acc, U) -> Acc, - { - #[inline] - fn flatten( - fold: &mut impl FnMut(Acc, T::IntoIter) -> Acc, - ) -> impl FnMut(Acc, T) -> Acc + '_ { - move |acc, iter| fold(acc, iter.into_iter()) - } - - if let Some(iter) = self.backiter { - acc = fold(acc, iter); - } - - acc = self.iter.rfold(acc, flatten(&mut fold)); - - if let Some(iter) = self.frontiter { - acc = fold(acc, iter); - } - - acc - } - - /// Folds over the inner iterators in reverse order as long as the given function returns - /// successfully, always storing the most recent inner iterator in `self.backiter`. - /// - /// Folds over the inner iterators, not over their elements. Is used by the `try_rfold` and - /// `advance_back_by` methods. - #[inline] - fn iter_try_rfold(&mut self, mut acc: Acc, mut fold: Fold) -> R - where - Fold: FnMut(Acc, &mut U) -> R, - R: Try, - { - #[inline] - fn flatten<'a, T: IntoIterator, Acc, R: Try>( - backiter: &'a mut Option, - fold: &'a mut impl FnMut(Acc, &mut T::IntoIter) -> R, - ) -> impl FnMut(Acc, T) -> R + 'a { - move |acc, iter| fold(acc, backiter.insert(iter.into_iter())) - } - - if let Some(iter) = &mut self.backiter { - acc = fold(acc, iter)?; - } - self.backiter = None; - - acc = self.iter.try_rfold(acc, flatten(&mut self.backiter, &mut fold))?; - self.backiter = None; - - if let Some(iter) = &mut self.frontiter { - acc = fold(acc, iter)?; - } - self.frontiter = None; - - try { acc } - } -} - -// See also the `OneShot` specialization below. -impl Iterator for FlattenCompat -where - I: Iterator>, - U: Iterator, -{ - type Item = U::Item; - - #[inline] - default fn next(&mut self) -> Option { - loop { - if let elt @ Some(_) = and_then_or_clear(&mut self.frontiter, Iterator::next) { - return elt; - } - match self.iter.next() { - None => return and_then_or_clear(&mut self.backiter, Iterator::next), - Some(inner) => self.frontiter = Some(inner.into_iter()), - } - } - } - - #[inline] - default fn size_hint(&self) -> (usize, Option) { - let (flo, fhi) = self.frontiter.as_ref().map_or((0, Some(0)), U::size_hint); - let (blo, bhi) = self.backiter.as_ref().map_or((0, Some(0)), U::size_hint); - let lo = flo.saturating_add(blo); - - if let Some(fixed_size) = <::Item as ConstSizeIntoIterator>::size() { - let (lower, upper) = self.iter.size_hint(); - - let lower = lower.saturating_mul(fixed_size).saturating_add(lo); - let upper = - try { fhi?.checked_add(bhi?)?.checked_add(fixed_size.checked_mul(upper?)?)? }; - - return (lower, upper); - } - - match (self.iter.size_hint(), fhi, bhi) { - ((0, Some(0)), Some(a), Some(b)) => (lo, a.checked_add(b)), - _ => (lo, None), - } - } - - #[inline] - default fn try_fold(&mut self, init: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - #[inline] - fn flatten>( - mut fold: impl FnMut(Acc, U::Item) -> R, - ) -> impl FnMut(Acc, &mut U) -> R { - move |acc, iter| iter.try_fold(acc, &mut fold) - } - - self.iter_try_fold(init, flatten(fold)) - } - - #[inline] - default fn fold(self, init: Acc, fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - #[inline] - fn flatten( - mut fold: impl FnMut(Acc, U::Item) -> Acc, - ) -> impl FnMut(Acc, U) -> Acc { - move |acc, iter| iter.fold(acc, &mut fold) - } - - self.iter_fold(init, flatten(fold)) - } - - #[inline] - #[rustc_inherit_overflow_checks] - default fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - #[inline] - #[rustc_inherit_overflow_checks] - fn advance(n: usize, iter: &mut U) -> ControlFlow<(), usize> { - match iter.advance_by(n) { - Ok(()) => ControlFlow::Break(()), - Err(remaining) => ControlFlow::Continue(remaining.get()), - } - } - - match self.iter_try_fold(n, advance) { - ControlFlow::Continue(remaining) => NonZero::new(remaining).map_or(Ok(()), Err), - _ => Ok(()), - } - } - - #[inline] - default fn count(self) -> usize { - #[inline] - #[rustc_inherit_overflow_checks] - fn count(acc: usize, iter: U) -> usize { - acc + iter.count() - } - - self.iter_fold(0, count) - } - - #[inline] - default fn last(self) -> Option { - #[inline] - fn last(last: Option, iter: U) -> Option { - iter.last().or(last) - } - - self.iter_fold(None, last) - } -} - -// See also the `OneShot` specialization below. -impl DoubleEndedIterator for FlattenCompat -where - I: DoubleEndedIterator>, - U: DoubleEndedIterator, -{ - #[inline] - default fn next_back(&mut self) -> Option { - loop { - if let elt @ Some(_) = and_then_or_clear(&mut self.backiter, |b| b.next_back()) { - return elt; - } - match self.iter.next_back() { - None => return and_then_or_clear(&mut self.frontiter, |f| f.next_back()), - Some(inner) => self.backiter = Some(inner.into_iter()), - } - } - } - - #[inline] - default fn try_rfold(&mut self, init: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - #[inline] - fn flatten>( - mut fold: impl FnMut(Acc, U::Item) -> R, - ) -> impl FnMut(Acc, &mut U) -> R { - move |acc, iter| iter.try_rfold(acc, &mut fold) - } - - self.iter_try_rfold(init, flatten(fold)) - } - - #[inline] - default fn rfold(self, init: Acc, fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - #[inline] - fn flatten( - mut fold: impl FnMut(Acc, U::Item) -> Acc, - ) -> impl FnMut(Acc, U) -> Acc { - move |acc, iter| iter.rfold(acc, &mut fold) - } - - self.iter_rfold(init, flatten(fold)) - } - - #[inline] - #[rustc_inherit_overflow_checks] - default fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - #[inline] - #[rustc_inherit_overflow_checks] - fn advance(n: usize, iter: &mut U) -> ControlFlow<(), usize> { - match iter.advance_back_by(n) { - Ok(()) => ControlFlow::Break(()), - Err(remaining) => ControlFlow::Continue(remaining.get()), - } - } - - match self.iter_try_rfold(n, advance) { - ControlFlow::Continue(remaining) => NonZero::new(remaining).map_or(Ok(()), Err), - _ => Ok(()), - } - } -} - -unsafe impl TrustedLen - for FlattenCompat::IntoIter> -where - I: TrustedLen, -{ -} - -unsafe impl<'a, const N: usize, I, T> TrustedLen - for FlattenCompat::IntoIter> -where - I: TrustedLen, -{ -} - -unsafe impl<'a, const N: usize, I, T> TrustedLen - for FlattenCompat::IntoIter> -where - I: TrustedLen, -{ -} - -trait ConstSizeIntoIterator: IntoIterator { - // FIXME(#31844): convert to an associated const once specialization supports that - fn size() -> Option; -} - -impl ConstSizeIntoIterator for T -where - T: IntoIterator, -{ - #[inline] - default fn size() -> Option { - None - } -} - -impl ConstSizeIntoIterator for [T; N] { - #[inline] - fn size() -> Option { - Some(N) - } -} - -impl ConstSizeIntoIterator for &[T; N] { - #[inline] - fn size() -> Option { - Some(N) - } -} - -impl ConstSizeIntoIterator for &mut [T; N] { - #[inline] - fn size() -> Option { - Some(N) - } -} - -#[inline] -fn and_then_or_clear(opt: &mut Option, f: impl FnOnce(&mut T) -> Option) -> Option { - let x = f(opt.as_mut()?); - if x.is_none() { - *opt = None; - } - x -} - -/// Specialization trait for iterator types that never return more than one item. -/// -/// Note that we still have to deal with the possibility that the iterator was -/// already exhausted before it came into our control. -#[rustc_specialization_trait] -trait OneShot {} - -// These all have exactly one item, if not already consumed. -impl OneShot for Once {} -impl OneShot for OnceWith {} -impl OneShot for array::IntoIter {} -impl OneShot for option::IntoIter {} -impl OneShot for option::Iter<'_, T> {} -impl OneShot for option::IterMut<'_, T> {} -impl OneShot for result::IntoIter {} -impl OneShot for result::Iter<'_, T> {} -impl OneShot for result::IterMut<'_, T> {} - -// These are always empty, which is fine to optimize too. -impl OneShot for Empty {} -impl OneShot for array::IntoIter {} - -// These adaptors never increase the number of items. -// (There are more possible, but for now this matches BoundedSize above.) -impl OneShot for Cloned {} -impl OneShot for Copied {} -impl OneShot for Filter {} -impl OneShot for FilterMap {} -impl OneShot for Map {} - -// Blanket impls pass this property through as well -// (but we can't do `Box` unless we expose this trait to alloc) -impl OneShot for &mut I {} - -#[inline] -fn into_item(inner: I) -> Option -where - I: IntoIterator, -{ - inner.into_iter().next() -} - -#[inline] -fn flatten_one, Acc>( - mut fold: impl FnMut(Acc, I::Item) -> Acc, -) -> impl FnMut(Acc, I) -> Acc { - move |acc, inner| match inner.into_iter().next() { - Some(item) => fold(acc, item), - None => acc, - } -} - -#[inline] -fn try_flatten_one, Acc, R: Try>( - mut fold: impl FnMut(Acc, I::Item) -> R, -) -> impl FnMut(Acc, I) -> R { - move |acc, inner| match inner.into_iter().next() { - Some(item) => fold(acc, item), - None => try { acc }, - } -} - -#[inline] -fn advance_by_one(n: NonZero, inner: I) -> Option> -where - I: IntoIterator, -{ - match inner.into_iter().next() { - Some(_) => NonZero::new(n.get() - 1), - None => Some(n), - } -} - -// Specialization: When the inner iterator `U` never returns more than one item, the `frontiter` and -// `backiter` states are a waste, because they'll always have already consumed their item. So in -// this impl, we completely ignore them and just focus on `self.iter`, and we only call the inner -// `U::next()` one time. -// -// It's mostly fine if we accidentally mix this with the more generic impls, e.g. by forgetting to -// specialize one of the methods. If the other impl did set the front or back, we wouldn't see it -// here, but it would be empty anyway; and if the other impl looked for a front or back that we -// didn't bother setting, it would just see `None` (or a previous empty) and move on. -// -// An exception to that is `advance_by(0)` and `advance_back_by(0)`, where the generic impls may set -// `frontiter` or `backiter` without consuming the item, so we **must** override those. -impl Iterator for FlattenCompat -where - I: Iterator>, - U: Iterator + OneShot, -{ - #[inline] - fn next(&mut self) -> Option { - while let Some(inner) = self.iter.next() { - if let item @ Some(_) = inner.into_iter().next() { - return item; - } - } - None - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let (lower, upper) = self.iter.size_hint(); - match ::size() { - Some(0) => (0, Some(0)), - Some(1) => (lower, upper), - _ => (0, upper), - } - } - - #[inline] - fn try_fold(&mut self, init: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - self.iter.try_fold(init, try_flatten_one(fold)) - } - - #[inline] - fn fold(self, init: Acc, fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - self.iter.fold(init, flatten_one(fold)) - } - - #[inline] - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - if let Some(n) = NonZero::new(n) { - self.iter.try_fold(n, advance_by_one).map_or(Ok(()), Err) - } else { - // Just advance the outer iterator - self.iter.advance_by(0) - } - } - - #[inline] - fn count(self) -> usize { - self.iter.filter_map(into_item).count() - } - - #[inline] - fn last(self) -> Option { - self.iter.filter_map(into_item).last() - } -} - -// Note: We don't actually care about `U: DoubleEndedIterator`, since forward and backward are the -// same for a one-shot iterator, but we have to keep that to match the default specialization. -impl DoubleEndedIterator for FlattenCompat -where - I: DoubleEndedIterator>, - U: DoubleEndedIterator + OneShot, -{ - #[inline] - fn next_back(&mut self) -> Option { - while let Some(inner) = self.iter.next_back() { - if let item @ Some(_) = inner.into_iter().next() { - return item; - } - } - None - } - - #[inline] - fn try_rfold(&mut self, init: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - self.iter.try_rfold(init, try_flatten_one(fold)) - } - - #[inline] - fn rfold(self, init: Acc, fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - self.iter.rfold(init, flatten_one(fold)) - } - - #[inline] - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - if let Some(n) = NonZero::new(n) { - self.iter.try_rfold(n, advance_by_one).map_or(Ok(()), Err) - } else { - // Just advance the outer iterator - self.iter.advance_back_by(0) - } - } -} diff --git a/library/core/src/iter/adapters/fuse.rs b/library/core/src/iter/adapters/fuse.rs deleted file mode 100644 index 7781ed088b76c..0000000000000 --- a/library/core/src/iter/adapters/fuse.rs +++ /dev/null @@ -1,452 +0,0 @@ -use crate::intrinsics; -use crate::iter::adapters::zip::try_get_unchecked; -use crate::iter::adapters::SourceIter; -use crate::iter::{ - FusedIterator, TrustedFused, TrustedLen, TrustedRandomAccess, TrustedRandomAccessNoCoerce, -}; -use crate::ops::Try; - -/// An iterator that yields `None` forever after the underlying iterator -/// yields `None` once. -/// -/// This `struct` is created by [`Iterator::fuse`]. See its documentation -/// for more. -#[derive(Clone, Debug)] -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Fuse { - // NOTE: for `I: FusedIterator`, we never bother setting `None`, but - // we still have to be prepared for that state due to variance. - // See rust-lang/rust#85863 - iter: Option, -} -impl Fuse { - pub(in crate::iter) fn new(iter: I) -> Fuse { - Fuse { iter: Some(iter) } - } - - pub(crate) fn into_inner(self) -> Option { - self.iter - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Fuse where I: Iterator {} - -#[unstable(issue = "none", feature = "trusted_fused")] -unsafe impl TrustedFused for Fuse where I: TrustedFused {} - -// Any specialized implementation here is made internal -// to avoid exposing default fns outside this trait. -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for Fuse -where - I: Iterator, -{ - type Item = ::Item; - - #[inline] - fn next(&mut self) -> Option { - FuseImpl::next(self) - } - - #[inline] - fn nth(&mut self, n: usize) -> Option { - FuseImpl::nth(self, n) - } - - #[inline] - fn last(self) -> Option { - match self.iter { - Some(iter) => iter.last(), - None => None, - } - } - - #[inline] - fn count(self) -> usize { - match self.iter { - Some(iter) => iter.count(), - None => 0, - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - match self.iter { - Some(ref iter) => iter.size_hint(), - None => (0, Some(0)), - } - } - - #[inline] - fn try_fold(&mut self, acc: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - FuseImpl::try_fold(self, acc, fold) - } - - #[inline] - fn fold(self, mut acc: Acc, fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - if let Some(iter) = self.iter { - acc = iter.fold(acc, fold); - } - acc - } - - #[inline] - fn find

(&mut self, predicate: P) -> Option - where - P: FnMut(&Self::Item) -> bool, - { - FuseImpl::find(self, predicate) - } - - #[inline] - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item - where - Self: TrustedRandomAccessNoCoerce, - { - match self.iter { - // SAFETY: the caller must uphold the contract for - // `Iterator::__iterator_get_unchecked`. - Some(ref mut iter) => unsafe { try_get_unchecked(iter, idx) }, - // SAFETY: the caller asserts there is an item at `i`, so we're not exhausted. - None => unsafe { intrinsics::unreachable() }, - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DoubleEndedIterator for Fuse -where - I: DoubleEndedIterator, -{ - #[inline] - fn next_back(&mut self) -> Option<::Item> { - FuseImpl::next_back(self) - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option<::Item> { - FuseImpl::nth_back(self, n) - } - - #[inline] - fn try_rfold(&mut self, acc: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - FuseImpl::try_rfold(self, acc, fold) - } - - #[inline] - fn rfold(self, mut acc: Acc, fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - if let Some(iter) = self.iter { - acc = iter.rfold(acc, fold); - } - acc - } - - #[inline] - fn rfind

(&mut self, predicate: P) -> Option - where - P: FnMut(&Self::Item) -> bool, - { - FuseImpl::rfind(self, predicate) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Fuse -where - I: ExactSizeIterator, -{ - fn len(&self) -> usize { - match self.iter { - Some(ref iter) => iter.len(), - None => 0, - } - } - - fn is_empty(&self) -> bool { - match self.iter { - Some(ref iter) => iter.is_empty(), - None => true, - } - } -} - -#[stable(feature = "default_iters", since = "1.70.0")] -impl Default for Fuse { - /// Creates a `Fuse` iterator from the default value of `I`. - /// - /// ``` - /// # use core::slice; - /// # use std::iter::Fuse; - /// let iter: Fuse> = Default::default(); - /// assert_eq!(iter.len(), 0); - /// ``` - fn default() -> Self { - Fuse { iter: Default::default() } - } -} - -#[unstable(feature = "trusted_len", issue = "37572")] -// SAFETY: `TrustedLen` requires that an accurate length is reported via `size_hint()`. As `Fuse` -// is just forwarding this to the wrapped iterator `I` this property is preserved and it is safe to -// implement `TrustedLen` here. -unsafe impl TrustedLen for Fuse where I: TrustedLen {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -// SAFETY: `TrustedRandomAccess` requires that `size_hint()` must be exact and cheap to call, and -// `Iterator::__iterator_get_unchecked()` must be implemented accordingly. -// -// This is safe to implement as `Fuse` is just forwarding these to the wrapped iterator `I`, which -// preserves these properties. -unsafe impl TrustedRandomAccess for Fuse where I: TrustedRandomAccess {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl TrustedRandomAccessNoCoerce for Fuse -where - I: TrustedRandomAccessNoCoerce, -{ - const MAY_HAVE_SIDE_EFFECT: bool = I::MAY_HAVE_SIDE_EFFECT; -} - -/// Fuse specialization trait -/// -/// We only need to worry about `&mut self` methods, which -/// may exhaust the iterator without consuming it. -#[doc(hidden)] -trait FuseImpl { - type Item; - - // Functions specific to any normal Iterators - fn next(&mut self) -> Option; - fn nth(&mut self, n: usize) -> Option; - fn try_fold(&mut self, acc: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try; - fn find

(&mut self, predicate: P) -> Option - where - P: FnMut(&Self::Item) -> bool; - - // Functions specific to DoubleEndedIterators - fn next_back(&mut self) -> Option - where - I: DoubleEndedIterator; - fn nth_back(&mut self, n: usize) -> Option - where - I: DoubleEndedIterator; - fn try_rfold(&mut self, acc: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - I: DoubleEndedIterator; - fn rfind

(&mut self, predicate: P) -> Option - where - P: FnMut(&Self::Item) -> bool, - I: DoubleEndedIterator; -} - -/// General `Fuse` impl which sets `iter = None` when exhausted. -#[doc(hidden)] -impl FuseImpl for Fuse -where - I: Iterator, -{ - type Item = ::Item; - - #[inline] - default fn next(&mut self) -> Option<::Item> { - and_then_or_clear(&mut self.iter, Iterator::next) - } - - #[inline] - default fn nth(&mut self, n: usize) -> Option { - and_then_or_clear(&mut self.iter, |iter| iter.nth(n)) - } - - #[inline] - default fn try_fold(&mut self, mut acc: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - if let Some(ref mut iter) = self.iter { - acc = iter.try_fold(acc, fold)?; - self.iter = None; - } - try { acc } - } - - #[inline] - default fn find

(&mut self, predicate: P) -> Option - where - P: FnMut(&Self::Item) -> bool, - { - and_then_or_clear(&mut self.iter, |iter| iter.find(predicate)) - } - - #[inline] - default fn next_back(&mut self) -> Option<::Item> - where - I: DoubleEndedIterator, - { - and_then_or_clear(&mut self.iter, |iter| iter.next_back()) - } - - #[inline] - default fn nth_back(&mut self, n: usize) -> Option<::Item> - where - I: DoubleEndedIterator, - { - and_then_or_clear(&mut self.iter, |iter| iter.nth_back(n)) - } - - #[inline] - default fn try_rfold(&mut self, mut acc: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - I: DoubleEndedIterator, - { - if let Some(ref mut iter) = self.iter { - acc = iter.try_rfold(acc, fold)?; - self.iter = None; - } - try { acc } - } - - #[inline] - default fn rfind

(&mut self, predicate: P) -> Option - where - P: FnMut(&Self::Item) -> bool, - I: DoubleEndedIterator, - { - and_then_or_clear(&mut self.iter, |iter| iter.rfind(predicate)) - } -} - -/// Specialized `Fuse` impl which doesn't bother clearing `iter` when exhausted. -/// However, we must still be prepared for the possibility that it was already cleared! -#[doc(hidden)] -impl FuseImpl for Fuse -where - I: FusedIterator, -{ - #[inline] - fn next(&mut self) -> Option<::Item> { - self.iter.as_mut()?.next() - } - - #[inline] - fn nth(&mut self, n: usize) -> Option { - self.iter.as_mut()?.nth(n) - } - - #[inline] - fn try_fold(&mut self, mut acc: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - if let Some(ref mut iter) = self.iter { - acc = iter.try_fold(acc, fold)?; - } - try { acc } - } - - #[inline] - fn find

(&mut self, predicate: P) -> Option - where - P: FnMut(&Self::Item) -> bool, - { - self.iter.as_mut()?.find(predicate) - } - - #[inline] - fn next_back(&mut self) -> Option<::Item> - where - I: DoubleEndedIterator, - { - self.iter.as_mut()?.next_back() - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option<::Item> - where - I: DoubleEndedIterator, - { - self.iter.as_mut()?.nth_back(n) - } - - #[inline] - fn try_rfold(&mut self, mut acc: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - I: DoubleEndedIterator, - { - if let Some(ref mut iter) = self.iter { - acc = iter.try_rfold(acc, fold)?; - } - try { acc } - } - - #[inline] - fn rfind

(&mut self, predicate: P) -> Option - where - P: FnMut(&Self::Item) -> bool, - I: DoubleEndedIterator, - { - self.iter.as_mut()?.rfind(predicate) - } -} - -// This is used by Flatten's SourceIter impl -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl SourceIter for Fuse -where - I: SourceIter + TrustedFused, -{ - type Source = I::Source; - - #[inline] - unsafe fn as_inner(&mut self) -> &mut I::Source { - // SAFETY: unsafe function forwarding to unsafe function with the same requirements. - // TrustedFused guarantees that we'll never encounter a case where `self.iter` would - // be set to None. - unsafe { SourceIter::as_inner(self.iter.as_mut().unwrap_unchecked()) } - } -} - -#[inline] -fn and_then_or_clear(opt: &mut Option, f: impl FnOnce(&mut T) -> Option) -> Option { - let x = f(opt.as_mut()?); - if x.is_none() { - *opt = None; - } - x -} diff --git a/library/core/src/iter/adapters/inspect.rs b/library/core/src/iter/adapters/inspect.rs deleted file mode 100644 index 1c4656a649a37..0000000000000 --- a/library/core/src/iter/adapters/inspect.rs +++ /dev/null @@ -1,173 +0,0 @@ -use crate::fmt; -use crate::iter::{adapters::SourceIter, FusedIterator, InPlaceIterable, TrustedFused}; -use crate::num::NonZero; -use crate::ops::Try; - -/// An iterator that calls a function with a reference to each element before -/// yielding it. -/// -/// This `struct` is created by the [`inspect`] method on [`Iterator`]. See its -/// documentation for more. -/// -/// [`inspect`]: Iterator::inspect -/// [`Iterator`]: trait.Iterator.html -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Clone)] -pub struct Inspect { - iter: I, - f: F, -} -impl Inspect { - pub(in crate::iter) fn new(iter: I, f: F) -> Inspect { - Inspect { iter, f } - } -} - -#[stable(feature = "core_impl_debug", since = "1.9.0")] -impl fmt::Debug for Inspect { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Inspect").field("iter", &self.iter).finish() - } -} - -impl Inspect -where - F: FnMut(&I::Item), -{ - #[inline] - fn do_inspect(&mut self, elt: Option) -> Option { - if let Some(ref a) = elt { - (self.f)(a); - } - - elt - } -} - -fn inspect_fold( - mut f: impl FnMut(&T), - mut fold: impl FnMut(Acc, T) -> Acc, -) -> impl FnMut(Acc, T) -> Acc { - move |acc, item| { - f(&item); - fold(acc, item) - } -} - -fn inspect_try_fold<'a, T, Acc, R>( - f: &'a mut impl FnMut(&T), - mut fold: impl FnMut(Acc, T) -> R + 'a, -) -> impl FnMut(Acc, T) -> R + 'a { - move |acc, item| { - f(&item); - fold(acc, item) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for Inspect -where - F: FnMut(&I::Item), -{ - type Item = I::Item; - - #[inline] - fn next(&mut self) -> Option { - let next = self.iter.next(); - self.do_inspect(next) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } - - #[inline] - fn try_fold(&mut self, init: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - self.iter.try_fold(init, inspect_try_fold(&mut self.f, fold)) - } - - #[inline] - fn fold(self, init: Acc, fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - self.iter.fold(init, inspect_fold(self.f, fold)) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DoubleEndedIterator for Inspect -where - F: FnMut(&I::Item), -{ - #[inline] - fn next_back(&mut self) -> Option { - let next = self.iter.next_back(); - self.do_inspect(next) - } - - #[inline] - fn try_rfold(&mut self, init: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - self.iter.try_rfold(init, inspect_try_fold(&mut self.f, fold)) - } - - #[inline] - fn rfold(self, init: Acc, fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - self.iter.rfold(init, inspect_fold(self.f, fold)) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Inspect -where - F: FnMut(&I::Item), -{ - fn len(&self) -> usize { - self.iter.len() - } - - fn is_empty(&self) -> bool { - self.iter.is_empty() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Inspect where F: FnMut(&I::Item) {} - -#[unstable(issue = "none", feature = "trusted_fused")] -unsafe impl TrustedFused for Inspect {} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl SourceIter for Inspect -where - I: SourceIter, -{ - type Source = I::Source; - - #[inline] - unsafe fn as_inner(&mut self) -> &mut I::Source { - // SAFETY: unsafe function forwarding to unsafe function with the same requirements - unsafe { SourceIter::as_inner(&mut self.iter) } - } -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl InPlaceIterable for Inspect { - const EXPAND_BY: Option> = I::EXPAND_BY; - const MERGE_BY: Option> = I::MERGE_BY; -} diff --git a/library/core/src/iter/adapters/intersperse.rs b/library/core/src/iter/adapters/intersperse.rs deleted file mode 100644 index c97a59b614f9d..0000000000000 --- a/library/core/src/iter/adapters/intersperse.rs +++ /dev/null @@ -1,236 +0,0 @@ -use crate::fmt; -use crate::iter::{Fuse, FusedIterator}; - -/// An iterator adapter that places a separator between all elements. -/// -/// This `struct` is created by [`Iterator::intersperse`]. See its documentation -/// for more information. -#[unstable(feature = "iter_intersperse", reason = "recently added", issue = "79524")] -#[derive(Debug, Clone)] -pub struct Intersperse -where - I::Item: Clone, -{ - started: bool, - separator: I::Item, - next_item: Option, - iter: Fuse, -} - -#[unstable(feature = "iter_intersperse", reason = "recently added", issue = "79524")] -impl FusedIterator for Intersperse -where - I: FusedIterator, - I::Item: Clone, -{ -} - -impl Intersperse -where - I::Item: Clone, -{ - pub(in crate::iter) fn new(iter: I, separator: I::Item) -> Self { - Self { started: false, separator, next_item: None, iter: iter.fuse() } - } -} - -#[unstable(feature = "iter_intersperse", reason = "recently added", issue = "79524")] -impl Iterator for Intersperse -where - I: Iterator, - I::Item: Clone, -{ - type Item = I::Item; - - #[inline] - fn next(&mut self) -> Option { - if self.started { - if let Some(v) = self.next_item.take() { - Some(v) - } else { - let next_item = self.iter.next(); - if next_item.is_some() { - self.next_item = next_item; - Some(self.separator.clone()) - } else { - None - } - } - } else { - self.started = true; - self.iter.next() - } - } - - fn size_hint(&self) -> (usize, Option) { - intersperse_size_hint(&self.iter, self.started, self.next_item.is_some()) - } - - fn fold(self, init: B, f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - let separator = self.separator; - intersperse_fold( - self.iter, - init, - f, - move || separator.clone(), - self.started, - self.next_item, - ) - } -} - -/// An iterator adapter that places a separator between all elements. -/// -/// This `struct` is created by [`Iterator::intersperse_with`]. See its -/// documentation for more information. -#[unstable(feature = "iter_intersperse", reason = "recently added", issue = "79524")] -pub struct IntersperseWith -where - I: Iterator, -{ - started: bool, - separator: G, - next_item: Option, - iter: Fuse, -} - -#[unstable(feature = "iter_intersperse", reason = "recently added", issue = "79524")] -impl FusedIterator for IntersperseWith -where - I: FusedIterator, - G: FnMut() -> I::Item, -{ -} - -#[unstable(feature = "iter_intersperse", reason = "recently added", issue = "79524")] -impl fmt::Debug for IntersperseWith -where - I: Iterator + fmt::Debug, - I::Item: fmt::Debug, - G: fmt::Debug, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("IntersperseWith") - .field("started", &self.started) - .field("separator", &self.separator) - .field("iter", &self.iter) - .field("next_item", &self.next_item) - .finish() - } -} - -#[unstable(feature = "iter_intersperse", reason = "recently added", issue = "79524")] -impl Clone for IntersperseWith -where - I: Iterator + Clone, - I::Item: Clone, - G: Clone, -{ - fn clone(&self) -> Self { - Self { - started: self.started, - separator: self.separator.clone(), - iter: self.iter.clone(), - next_item: self.next_item.clone(), - } - } -} - -impl IntersperseWith -where - I: Iterator, - G: FnMut() -> I::Item, -{ - pub(in crate::iter) fn new(iter: I, separator: G) -> Self { - Self { started: false, separator, next_item: None, iter: iter.fuse() } - } -} - -#[unstable(feature = "iter_intersperse", reason = "recently added", issue = "79524")] -impl Iterator for IntersperseWith -where - I: Iterator, - G: FnMut() -> I::Item, -{ - type Item = I::Item; - - #[inline] - fn next(&mut self) -> Option { - if self.started { - if let Some(v) = self.next_item.take() { - Some(v) - } else { - let next_item = self.iter.next(); - if next_item.is_some() { - self.next_item = next_item; - Some((self.separator)()) - } else { - None - } - } - } else { - self.started = true; - self.iter.next() - } - } - - fn size_hint(&self) -> (usize, Option) { - intersperse_size_hint(&self.iter, self.started, self.next_item.is_some()) - } - - fn fold(self, init: B, f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - intersperse_fold(self.iter, init, f, self.separator, self.started, self.next_item) - } -} - -fn intersperse_size_hint(iter: &I, started: bool, next_is_some: bool) -> (usize, Option) -where - I: Iterator, -{ - let (lo, hi) = iter.size_hint(); - ( - lo.saturating_sub(!started as usize) - .saturating_add(next_is_some as usize) - .saturating_add(lo), - hi.and_then(|hi| { - hi.saturating_sub(!started as usize) - .saturating_add(next_is_some as usize) - .checked_add(hi) - }), - ) -} - -fn intersperse_fold( - mut iter: I, - init: B, - mut f: F, - mut separator: G, - started: bool, - mut next_item: Option, -) -> B -where - I: Iterator, - F: FnMut(B, I::Item) -> B, - G: FnMut() -> I::Item, -{ - let mut accum = init; - - let first = if started { next_item.take() } else { iter.next() }; - if let Some(x) = first { - accum = f(accum, x); - } - - iter.fold(accum, |mut accum, x| { - accum = f(accum, separator()); - accum = f(accum, x); - accum - }) -} diff --git a/library/core/src/iter/adapters/map.rs b/library/core/src/iter/adapters/map.rs deleted file mode 100644 index 6e163e20d8ec4..0000000000000 --- a/library/core/src/iter/adapters/map.rs +++ /dev/null @@ -1,242 +0,0 @@ -use crate::fmt; -use crate::iter::adapters::{ - zip::try_get_unchecked, SourceIter, TrustedRandomAccess, TrustedRandomAccessNoCoerce, -}; -use crate::iter::{FusedIterator, InPlaceIterable, TrustedFused, TrustedLen, UncheckedIterator}; -use crate::num::NonZero; -use crate::ops::Try; - -/// An iterator that maps the values of `iter` with `f`. -/// -/// This `struct` is created by the [`map`] method on [`Iterator`]. See its -/// documentation for more. -/// -/// [`map`]: Iterator::map -/// [`Iterator`]: trait.Iterator.html -/// -/// # Notes about side effects -/// -/// The [`map`] iterator implements [`DoubleEndedIterator`], meaning that -/// you can also [`map`] backwards: -/// -/// ```rust -/// let v: Vec = [1, 2, 3].into_iter().map(|x| x + 1).rev().collect(); -/// -/// assert_eq!(v, [4, 3, 2]); -/// ``` -/// -/// [`DoubleEndedIterator`]: trait.DoubleEndedIterator.html -/// -/// But if your closure has state, iterating backwards may act in a way you do -/// not expect. Let's go through an example. First, in the forward direction: -/// -/// ```rust -/// let mut c = 0; -/// -/// for pair in ['a', 'b', 'c'].into_iter() -/// .map(|letter| { c += 1; (letter, c) }) { -/// println!("{pair:?}"); -/// } -/// ``` -/// -/// This will print `('a', 1), ('b', 2), ('c', 3)`. -/// -/// Now consider this twist where we add a call to `rev`. This version will -/// print `('c', 1), ('b', 2), ('a', 3)`. Note that the letters are reversed, -/// but the values of the counter still go in order. This is because `map()` is -/// still being called lazily on each item, but we are popping items off the -/// back of the vector now, instead of shifting them from the front. -/// -/// ```rust -/// let mut c = 0; -/// -/// for pair in ['a', 'b', 'c'].into_iter() -/// .map(|letter| { c += 1; (letter, c) }) -/// .rev() { -/// println!("{pair:?}"); -/// } -/// ``` -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Clone)] -pub struct Map { - // Used for `SplitWhitespace` and `SplitAsciiWhitespace` `as_str` methods - pub(crate) iter: I, - f: F, -} - -impl Map { - pub(in crate::iter) fn new(iter: I, f: F) -> Map { - Map { iter, f } - } - - pub(crate) fn into_inner(self) -> I { - self.iter - } -} - -#[stable(feature = "core_impl_debug", since = "1.9.0")] -impl fmt::Debug for Map { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Map").field("iter", &self.iter).finish() - } -} - -fn map_fold( - mut f: impl FnMut(T) -> B, - mut g: impl FnMut(Acc, B) -> Acc, -) -> impl FnMut(Acc, T) -> Acc { - move |acc, elt| g(acc, f(elt)) -} - -fn map_try_fold<'a, T, B, Acc, R>( - f: &'a mut impl FnMut(T) -> B, - mut g: impl FnMut(Acc, B) -> R + 'a, -) -> impl FnMut(Acc, T) -> R + 'a { - move |acc, elt| g(acc, f(elt)) -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for Map -where - F: FnMut(I::Item) -> B, -{ - type Item = B; - - #[inline] - fn next(&mut self) -> Option { - self.iter.next().map(&mut self.f) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } - - fn try_fold(&mut self, init: Acc, g: G) -> R - where - Self: Sized, - G: FnMut(Acc, Self::Item) -> R, - R: Try, - { - self.iter.try_fold(init, map_try_fold(&mut self.f, g)) - } - - fn fold(self, init: Acc, g: G) -> Acc - where - G: FnMut(Acc, Self::Item) -> Acc, - { - self.iter.fold(init, map_fold(self.f, g)) - } - - #[inline] - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> B - where - Self: TrustedRandomAccessNoCoerce, - { - // SAFETY: the caller must uphold the contract for - // `Iterator::__iterator_get_unchecked`. - unsafe { (self.f)(try_get_unchecked(&mut self.iter, idx)) } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DoubleEndedIterator for Map -where - F: FnMut(I::Item) -> B, -{ - #[inline] - fn next_back(&mut self) -> Option { - self.iter.next_back().map(&mut self.f) - } - - fn try_rfold(&mut self, init: Acc, g: G) -> R - where - Self: Sized, - G: FnMut(Acc, Self::Item) -> R, - R: Try, - { - self.iter.try_rfold(init, map_try_fold(&mut self.f, g)) - } - - fn rfold(self, init: Acc, g: G) -> Acc - where - G: FnMut(Acc, Self::Item) -> Acc, - { - self.iter.rfold(init, map_fold(self.f, g)) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Map -where - F: FnMut(I::Item) -> B, -{ - fn len(&self) -> usize { - self.iter.len() - } - - fn is_empty(&self) -> bool { - self.iter.is_empty() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Map where F: FnMut(I::Item) -> B {} - -#[unstable(issue = "none", feature = "trusted_fused")] -unsafe impl TrustedFused for Map {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for Map -where - I: TrustedLen, - F: FnMut(I::Item) -> B, -{ -} - -impl UncheckedIterator for Map -where - I: UncheckedIterator, - F: FnMut(I::Item) -> B, -{ - unsafe fn next_unchecked(&mut self) -> B { - // SAFETY: `Map` is 1:1 with the inner iterator, so if the caller promised - // that there's an element left, the inner iterator has one too. - let item = unsafe { self.iter.next_unchecked() }; - (self.f)(item) - } -} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl TrustedRandomAccess for Map where I: TrustedRandomAccess {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl TrustedRandomAccessNoCoerce for Map -where - I: TrustedRandomAccessNoCoerce, -{ - const MAY_HAVE_SIDE_EFFECT: bool = true; -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl SourceIter for Map -where - I: SourceIter, -{ - type Source = I::Source; - - #[inline] - unsafe fn as_inner(&mut self) -> &mut I::Source { - // SAFETY: unsafe function forwarding to unsafe function with the same requirements - unsafe { SourceIter::as_inner(&mut self.iter) } - } -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl InPlaceIterable for Map { - const EXPAND_BY: Option> = I::EXPAND_BY; - const MERGE_BY: Option> = I::MERGE_BY; -} diff --git a/library/core/src/iter/adapters/map_while.rs b/library/core/src/iter/adapters/map_while.rs deleted file mode 100644 index 9ad50048c25ea..0000000000000 --- a/library/core/src/iter/adapters/map_while.rs +++ /dev/null @@ -1,89 +0,0 @@ -use crate::fmt; -use crate::iter::{adapters::SourceIter, InPlaceIterable}; -use crate::num::NonZero; -use crate::ops::{ControlFlow, Try}; - -/// An iterator that only accepts elements while `predicate` returns `Some(_)`. -/// -/// This `struct` is created by the [`map_while`] method on [`Iterator`]. See its -/// documentation for more. -/// -/// [`map_while`]: Iterator::map_while -/// [`Iterator`]: trait.Iterator.html -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "iter_map_while", since = "1.57.0")] -#[derive(Clone)] -pub struct MapWhile { - iter: I, - predicate: P, -} - -impl MapWhile { - pub(in crate::iter) fn new(iter: I, predicate: P) -> MapWhile { - MapWhile { iter, predicate } - } -} - -#[stable(feature = "iter_map_while", since = "1.57.0")] -impl fmt::Debug for MapWhile { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("MapWhile").field("iter", &self.iter).finish() - } -} - -#[stable(feature = "iter_map_while", since = "1.57.0")] -impl Iterator for MapWhile -where - P: FnMut(I::Item) -> Option, -{ - type Item = B; - - #[inline] - fn next(&mut self) -> Option { - let x = self.iter.next()?; - (self.predicate)(x) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let (_, upper) = self.iter.size_hint(); - (0, upper) // can't know a lower bound, due to the predicate - } - - #[inline] - fn try_fold(&mut self, init: Acc, mut fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - let Self { iter, predicate } = self; - iter.try_fold(init, |acc, x| match predicate(x) { - Some(item) => ControlFlow::from_try(fold(acc, item)), - None => ControlFlow::Break(try { acc }), - }) - .into_try() - } - - impl_fold_via_try_fold! { fold -> try_fold } -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl SourceIter for MapWhile -where - I: SourceIter, -{ - type Source = I::Source; - - #[inline] - unsafe fn as_inner(&mut self) -> &mut I::Source { - // SAFETY: unsafe function forwarding to unsafe function with the same requirements - unsafe { SourceIter::as_inner(&mut self.iter) } - } -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl InPlaceIterable for MapWhile { - const EXPAND_BY: Option> = I::EXPAND_BY; - const MERGE_BY: Option> = I::MERGE_BY; -} diff --git a/library/core/src/iter/adapters/map_windows.rs b/library/core/src/iter/adapters/map_windows.rs deleted file mode 100644 index 5f39b24583427..0000000000000 --- a/library/core/src/iter/adapters/map_windows.rs +++ /dev/null @@ -1,293 +0,0 @@ -use crate::{ - fmt, - iter::FusedIterator, - mem::{self, MaybeUninit}, - ptr, -}; - -/// An iterator over the mapped windows of another iterator. -/// -/// This `struct` is created by the [`Iterator::map_windows`]. See its -/// documentation for more information. -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[unstable(feature = "iter_map_windows", reason = "recently added", issue = "87155")] -pub struct MapWindows { - f: F, - inner: MapWindowsInner, -} - -struct MapWindowsInner { - // We fuse the inner iterator because there shouldn't be "holes" in - // the sliding window. Once the iterator returns a `None`, we make - // our `MapWindows` iterator return `None` forever. - iter: Option, - // Since iterators are assumed lazy, i.e. it only yields an item when - // `Iterator::next()` is called, and `MapWindows` is not an exception. - // - // Before the first iteration, we keep the buffer `None`. When the user - // first call `next` or other methods that makes the iterator advance, - // we collect the first `N` items yielded from the inner iterator and - // put it into the buffer. - // - // When the inner iterator has returned a `None` (i.e. fused), we take - // away this `buffer` and leave it `None` to reclaim its resources. - // - // FIXME: should we shrink the size of `buffer` using niche optimization? - buffer: Option>, -} - -// `Buffer` uses two times of space to reduce moves among the iterations. -// `Buffer` is semantically `[MaybeUninit; 2 * N]`. However, due -// to limitations of const generics, we use this different type. Note that -// it has the same underlying memory layout. -struct Buffer { - // Invariant: `self.buffer[self.start..self.start + N]` is initialized, - // with all other elements being uninitialized. This also - // implies that `self.start <= N`. - buffer: [[MaybeUninit; N]; 2], - start: usize, -} - -impl MapWindows { - pub(in crate::iter) fn new(iter: I, f: F) -> Self { - assert!(N != 0, "array in `Iterator::map_windows` must contain more than 0 elements"); - - // Only ZST arrays' length can be so large. - if mem::size_of::() == 0 { - assert!( - N.checked_mul(2).is_some(), - "array size of `Iterator::map_windows` is too large" - ); - } - - Self { inner: MapWindowsInner::new(iter), f } - } -} - -impl MapWindowsInner { - #[inline] - fn new(iter: I) -> Self { - Self { iter: Some(iter), buffer: None } - } - - fn next_window(&mut self) -> Option<&[I::Item; N]> { - let iter = self.iter.as_mut()?; - match self.buffer { - // It is the first time to advance. We collect - // the first `N` items from `self.iter` to initialize `self.buffer`. - None => self.buffer = Buffer::try_from_iter(iter), - Some(ref mut buffer) => match iter.next() { - None => { - // Fuse the inner iterator since it yields a `None`. - self.iter.take(); - self.buffer.take(); - } - // Advance the iterator. We first call `next` before changing our buffer - // at all. This means that if `next` panics, our invariant is upheld and - // our `Drop` impl drops the correct elements. - Some(item) => buffer.push(item), - }, - } - self.buffer.as_ref().map(Buffer::as_array_ref) - } - - fn size_hint(&self) -> (usize, Option) { - let Some(ref iter) = self.iter else { return (0, Some(0)) }; - let (lo, hi) = iter.size_hint(); - if self.buffer.is_some() { - // If the first `N` items are already yielded by the inner iterator, - // the size hint is then equal to the that of the inner iterator's. - (lo, hi) - } else { - // If the first `N` items are not yet yielded by the inner iterator, - // the first `N` elements should be counted as one window, so both bounds - // should subtract `N - 1`. - (lo.saturating_sub(N - 1), hi.map(|hi| hi.saturating_sub(N - 1))) - } - } -} - -impl Buffer { - fn try_from_iter(iter: &mut impl Iterator) -> Option { - let first_half = crate::array::iter_next_chunk(iter).ok()?; - let buffer = [MaybeUninit::new(first_half).transpose(), MaybeUninit::uninit_array()]; - Some(Self { buffer, start: 0 }) - } - - #[inline] - fn buffer_ptr(&self) -> *const MaybeUninit { - self.buffer.as_ptr().cast() - } - - #[inline] - fn buffer_mut_ptr(&mut self) -> *mut MaybeUninit { - self.buffer.as_mut_ptr().cast() - } - - #[inline] - fn as_array_ref(&self) -> &[T; N] { - debug_assert!(self.start + N <= 2 * N); - - // SAFETY: our invariant guarantees these elements are initialized. - unsafe { &*self.buffer_ptr().add(self.start).cast() } - } - - #[inline] - fn as_uninit_array_mut(&mut self) -> &mut MaybeUninit<[T; N]> { - debug_assert!(self.start + N <= 2 * N); - - // SAFETY: our invariant guarantees these elements are in bounds. - unsafe { &mut *self.buffer_mut_ptr().add(self.start).cast() } - } - - /// Pushes a new item `next` to the back, and pops the front-most one. - /// - /// All the elements will be shifted to the front end when pushing reaches - /// the back end. - fn push(&mut self, next: T) { - let buffer_mut_ptr = self.buffer_mut_ptr(); - debug_assert!(self.start + N <= 2 * N); - - let to_drop = if self.start == N { - // We have reached the end of our buffer and have to copy - // everything to the start. Example layout for N = 3. - // - // 0 1 2 3 4 5 0 1 2 3 4 5 - // ┌───┬───┬───┬───┬───┬───┐ ┌───┬───┬───┬───┬───┬───┐ - // │ - │ - │ - │ a │ b │ c │ -> │ b │ c │ n │ - │ - │ - │ - // └───┴───┴───┴───┴───┴───┘ └───┴───┴───┴───┴───┴───┘ - // ↑ ↑ - // start start - - // SAFETY: the two pointers are valid for reads/writes of N -1 - // elements because our array's size is semantically 2 * N. The - // regions also don't overlap for the same reason. - // - // We leave the old elements in place. As soon as `start` is set - // to 0, we treat them as uninitialized and treat their copies - // as initialized. - let to_drop = unsafe { - ptr::copy_nonoverlapping(buffer_mut_ptr.add(self.start + 1), buffer_mut_ptr, N - 1); - (*buffer_mut_ptr.add(N - 1)).write(next); - buffer_mut_ptr.add(self.start) - }; - self.start = 0; - to_drop - } else { - // SAFETY: `self.start` is < N as guaranteed by the invariant - // plus the check above. Even if the drop at the end panics, - // the invariant is upheld. - // - // Example layout for N = 3: - // - // 0 1 2 3 4 5 0 1 2 3 4 5 - // ┌───┬───┬───┬───┬───┬───┐ ┌───┬───┬───┬───┬───┬───┐ - // │ - │ a │ b │ c │ - │ - │ -> │ - │ - │ b │ c │ n │ - │ - // └───┴───┴───┴───┴───┴───┘ └───┴───┴───┴───┴───┴───┘ - // ↑ ↑ - // start start - // - let to_drop = unsafe { - (*buffer_mut_ptr.add(self.start + N)).write(next); - buffer_mut_ptr.add(self.start) - }; - self.start += 1; - to_drop - }; - - // SAFETY: the index is valid and this is element `a` in the - // diagram above and has not been dropped yet. - unsafe { ptr::drop_in_place(to_drop.cast::()) }; - } -} - -impl Clone for Buffer { - fn clone(&self) -> Self { - let mut buffer = Buffer { - buffer: [MaybeUninit::uninit_array(), MaybeUninit::uninit_array()], - start: self.start, - }; - buffer.as_uninit_array_mut().write(self.as_array_ref().clone()); - buffer - } -} - -impl Clone for MapWindowsInner -where - I: Iterator + Clone, - I::Item: Clone, -{ - fn clone(&self) -> Self { - Self { iter: self.iter.clone(), buffer: self.buffer.clone() } - } -} - -impl Drop for Buffer { - fn drop(&mut self) { - // SAFETY: our invariant guarantees that N elements starting from - // `self.start` are initialized. We drop them here. - unsafe { - let initialized_part: *mut [T] = crate::ptr::slice_from_raw_parts_mut( - self.buffer_mut_ptr().add(self.start).cast(), - N, - ); - ptr::drop_in_place(initialized_part); - } - } -} - -#[unstable(feature = "iter_map_windows", reason = "recently added", issue = "87155")] -impl Iterator for MapWindows -where - I: Iterator, - F: FnMut(&[I::Item; N]) -> R, -{ - type Item = R; - - fn next(&mut self) -> Option { - let window = self.inner.next_window()?; - let out = (self.f)(window); - Some(out) - } - - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } -} - -// Note that even if the inner iterator not fused, the `MapWindows` is still fused, -// because we don't allow "holes" in the mapping window. -#[unstable(feature = "iter_map_windows", reason = "recently added", issue = "87155")] -impl FusedIterator for MapWindows -where - I: Iterator, - F: FnMut(&[I::Item; N]) -> R, -{ -} - -#[unstable(feature = "iter_map_windows", reason = "recently added", issue = "87155")] -impl ExactSizeIterator for MapWindows -where - I: ExactSizeIterator, - F: FnMut(&[I::Item; N]) -> R, -{ -} - -#[unstable(feature = "iter_map_windows", reason = "recently added", issue = "87155")] -impl fmt::Debug for MapWindows { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("MapWindows").field("iter", &self.inner.iter).finish() - } -} - -#[unstable(feature = "iter_map_windows", reason = "recently added", issue = "87155")] -impl Clone for MapWindows -where - I: Iterator + Clone, - F: Clone, - I::Item: Clone, -{ - fn clone(&self) -> Self { - Self { f: self.f.clone(), inner: self.inner.clone() } - } -} diff --git a/library/core/src/iter/adapters/mod.rs b/library/core/src/iter/adapters/mod.rs deleted file mode 100644 index cc514bd914f14..0000000000000 --- a/library/core/src/iter/adapters/mod.rs +++ /dev/null @@ -1,239 +0,0 @@ -use crate::iter::InPlaceIterable; -use crate::num::NonZero; -use crate::ops::{ChangeOutputType, ControlFlow, FromResidual, Residual, Try}; - -mod array_chunks; -mod by_ref_sized; -mod chain; -mod cloned; -mod copied; -mod cycle; -mod enumerate; -mod filter; -mod filter_map; -mod flatten; -mod fuse; -mod inspect; -mod intersperse; -mod map; -mod map_while; -mod map_windows; -mod peekable; -mod rev; -mod scan; -mod skip; -mod skip_while; -mod step_by; -mod take; -mod take_while; -mod zip; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::{ - chain::Chain, cycle::Cycle, enumerate::Enumerate, filter::Filter, filter_map::FilterMap, - flatten::FlatMap, fuse::Fuse, inspect::Inspect, map::Map, peekable::Peekable, rev::Rev, - scan::Scan, skip::Skip, skip_while::SkipWhile, take::Take, take_while::TakeWhile, zip::Zip, -}; - -#[unstable(feature = "iter_array_chunks", reason = "recently added", issue = "100450")] -pub use self::array_chunks::ArrayChunks; - -#[unstable(feature = "std_internals", issue = "none")] -pub use self::by_ref_sized::ByRefSized; - -#[stable(feature = "iter_cloned", since = "1.1.0")] -pub use self::cloned::Cloned; - -#[stable(feature = "iterator_step_by", since = "1.28.0")] -pub use self::step_by::StepBy; - -#[stable(feature = "iterator_flatten", since = "1.29.0")] -pub use self::flatten::Flatten; - -#[stable(feature = "iter_copied", since = "1.36.0")] -pub use self::copied::Copied; - -#[unstable(feature = "iter_intersperse", reason = "recently added", issue = "79524")] -pub use self::intersperse::{Intersperse, IntersperseWith}; - -#[stable(feature = "iter_map_while", since = "1.57.0")] -pub use self::map_while::MapWhile; - -#[unstable(feature = "iter_map_windows", reason = "recently added", issue = "87155")] -pub use self::map_windows::MapWindows; - -#[unstable(feature = "trusted_random_access", issue = "none")] -pub use self::zip::TrustedRandomAccess; - -#[unstable(feature = "trusted_random_access", issue = "none")] -pub use self::zip::TrustedRandomAccessNoCoerce; - -#[stable(feature = "iter_zip", since = "1.59.0")] -pub use self::zip::zip; - -/// This trait provides transitive access to source-stage in an iterator-adapter pipeline -/// under the conditions that -/// * the iterator source `S` itself implements `SourceIter` -/// * there is a delegating implementation of this trait for each adapter in the pipeline between -/// the source and the pipeline consumer. -/// -/// When the source is an owning iterator struct (commonly called `IntoIter`) then -/// this can be useful for specializing [`FromIterator`] implementations or recovering the -/// remaining elements after an iterator has been partially exhausted. -/// -/// Note that implementations do not necessarily have to provide access to the inner-most -/// source of a pipeline. A stateful intermediate adapter might eagerly evaluate a part -/// of the pipeline and expose its internal storage as source. -/// -/// The trait is unsafe because implementers must uphold additional safety properties. -/// See [`as_inner`] for details. -/// -/// The primary use of this trait is in-place iteration. Refer to the [`vec::in_place_collect`] -/// module documentation for more information. -/// -/// [`vec::in_place_collect`]: ../../../../alloc/vec/in_place_collect/index.html -/// -/// # Examples -/// -/// Retrieving a partially consumed source: -/// -/// ``` -/// # #![feature(inplace_iteration)] -/// # use std::iter::SourceIter; -/// -/// let mut iter = vec![9, 9, 9].into_iter().map(|i| i * i); -/// let _ = iter.next(); -/// let mut remainder = std::mem::replace(unsafe { iter.as_inner() }, Vec::new().into_iter()); -/// println!("n = {} elements remaining", remainder.len()); -/// ``` -/// -/// [`FromIterator`]: crate::iter::FromIterator -/// [`as_inner`]: SourceIter::as_inner -#[unstable(issue = "none", feature = "inplace_iteration")] -#[doc(hidden)] -#[rustc_specialization_trait] -pub unsafe trait SourceIter { - /// A source stage in an iterator pipeline. - type Source; - - /// Retrieve the source of an iterator pipeline. - /// - /// # Safety - /// - /// Implementations must return the same mutable reference for their lifetime, unless - /// replaced by a caller. - /// - /// Callers may only replace the reference when they stopped iteration and drop the - /// iterator pipeline after extracting the source. - /// - /// This means iterator adapters can rely on the source not changing during - /// iteration but they cannot rely on it in their Drop implementations. - /// - /// Implementing this method means adapters relinquish private-only access to their - /// source and can only rely on guarantees made based on method receiver types. - /// The lack of restricted access also requires that adapters must uphold the source's - /// public API even when they have access to its internals. - /// - /// Callers in turn must expect the source to be in any state that is consistent with - /// its public API since adapters sitting between it and the source have the same - /// access. In particular an adapter may have consumed more elements than strictly necessary. - /// - /// The overall goal of these requirements is to let the consumer of a pipeline use - /// * whatever remains in the source after iteration has stopped - /// * the memory that has become unused by advancing a consuming iterator - /// - /// [`next()`]: Iterator::next() - unsafe fn as_inner(&mut self) -> &mut Self::Source; -} - -/// An iterator adapter that produces output as long as the underlying -/// iterator produces values where `Try::branch` says to `ControlFlow::Continue`. -/// -/// If a `ControlFlow::Break` is encountered, the iterator stops and the -/// residual is stored. -pub(crate) struct GenericShunt<'a, I, R> { - iter: I, - residual: &'a mut Option, -} - -/// Process the given iterator as if it yielded a the item's `Try::Output` -/// type instead. Any `Try::Residual`s encountered will stop the inner iterator -/// and be propagated back to the overall result. -pub(crate) fn try_process(iter: I, mut f: F) -> ChangeOutputType -where - I: Iterator>, - for<'a> F: FnMut(GenericShunt<'a, I, R>) -> U, - R: Residual, -{ - let mut residual = None; - let shunt = GenericShunt { iter, residual: &mut residual }; - let value = f(shunt); - match residual { - Some(r) => FromResidual::from_residual(r), - None => Try::from_output(value), - } -} - -impl Iterator for GenericShunt<'_, I, R> -where - I: Iterator>, -{ - type Item = ::Output; - - fn next(&mut self) -> Option { - self.try_for_each(ControlFlow::Break).break_value() - } - - fn size_hint(&self) -> (usize, Option) { - if self.residual.is_some() { - (0, Some(0)) - } else { - let (_, upper) = self.iter.size_hint(); - (0, upper) - } - } - - fn try_fold(&mut self, init: B, mut f: F) -> T - where - F: FnMut(B, Self::Item) -> T, - T: Try, - { - self.iter - .try_fold(init, |acc, x| match Try::branch(x) { - ControlFlow::Continue(x) => ControlFlow::from_try(f(acc, x)), - ControlFlow::Break(r) => { - *self.residual = Some(r); - ControlFlow::Break(try { acc }) - } - }) - .into_try() - } - - impl_fold_via_try_fold! { fold -> try_fold } -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl SourceIter for GenericShunt<'_, I, R> -where - I: SourceIter, -{ - type Source = I::Source; - - #[inline] - unsafe fn as_inner(&mut self) -> &mut Self::Source { - // SAFETY: unsafe function forwarding to unsafe function with the same requirements - unsafe { SourceIter::as_inner(&mut self.iter) } - } -} - -// SAFETY: GenericShunt::next calls `I::try_for_each`, which has to advance `iter` -// in order to return `Some(_)`. Since `iter` has type `I: InPlaceIterable` it's -// guaranteed that at least one item will be moved out from the underlying source. -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl InPlaceIterable for GenericShunt<'_, I, R> -where - I: InPlaceIterable, -{ - const EXPAND_BY: Option> = I::EXPAND_BY; - const MERGE_BY: Option> = I::MERGE_BY; -} diff --git a/library/core/src/iter/adapters/peekable.rs b/library/core/src/iter/adapters/peekable.rs deleted file mode 100644 index 65ba42920c93d..0000000000000 --- a/library/core/src/iter/adapters/peekable.rs +++ /dev/null @@ -1,336 +0,0 @@ -use crate::iter::{adapters::SourceIter, FusedIterator, TrustedLen}; -use crate::ops::{ControlFlow, Try}; - -/// An iterator with a `peek()` that returns an optional reference to the next -/// element. -/// -/// This `struct` is created by the [`peekable`] method on [`Iterator`]. See its -/// documentation for more. -/// -/// [`peekable`]: Iterator::peekable -/// [`Iterator`]: trait.Iterator.html -#[derive(Clone, Debug)] -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_diagnostic_item = "IterPeekable"] -pub struct Peekable { - iter: I, - /// Remember a peeked value, even if it was None. - peeked: Option>, -} - -impl Peekable { - pub(in crate::iter) fn new(iter: I) -> Peekable { - Peekable { iter, peeked: None } - } -} - -// Peekable must remember if a None has been seen in the `.peek()` method. -// It ensures that `.peek(); .peek();` or `.peek(); .next();` only advances the -// underlying iterator at most once. This does not by itself make the iterator -// fused. -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for Peekable { - type Item = I::Item; - - #[inline] - fn next(&mut self) -> Option { - match self.peeked.take() { - Some(v) => v, - None => self.iter.next(), - } - } - - #[inline] - #[rustc_inherit_overflow_checks] - fn count(mut self) -> usize { - match self.peeked.take() { - Some(None) => 0, - Some(Some(_)) => 1 + self.iter.count(), - None => self.iter.count(), - } - } - - #[inline] - fn nth(&mut self, n: usize) -> Option { - match self.peeked.take() { - Some(None) => None, - Some(v @ Some(_)) if n == 0 => v, - Some(Some(_)) => self.iter.nth(n - 1), - None => self.iter.nth(n), - } - } - - #[inline] - fn last(mut self) -> Option { - let peek_opt = match self.peeked.take() { - Some(None) => return None, - Some(v) => v, - None => None, - }; - self.iter.last().or(peek_opt) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let peek_len = match self.peeked { - Some(None) => return (0, Some(0)), - Some(Some(_)) => 1, - None => 0, - }; - let (lo, hi) = self.iter.size_hint(); - let lo = lo.saturating_add(peek_len); - let hi = match hi { - Some(x) => x.checked_add(peek_len), - None => None, - }; - (lo, hi) - } - - #[inline] - fn try_fold(&mut self, init: B, mut f: F) -> R - where - Self: Sized, - F: FnMut(B, Self::Item) -> R, - R: Try, - { - let acc = match self.peeked.take() { - Some(None) => return try { init }, - Some(Some(v)) => f(init, v)?, - None => init, - }; - self.iter.try_fold(acc, f) - } - - #[inline] - fn fold(self, init: Acc, mut fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - let acc = match self.peeked { - Some(None) => return init, - Some(Some(v)) => fold(init, v), - None => init, - }; - self.iter.fold(acc, fold) - } -} - -#[stable(feature = "double_ended_peek_iterator", since = "1.38.0")] -impl DoubleEndedIterator for Peekable -where - I: DoubleEndedIterator, -{ - #[inline] - fn next_back(&mut self) -> Option { - match self.peeked.as_mut() { - Some(v @ Some(_)) => self.iter.next_back().or_else(|| v.take()), - Some(None) => None, - None => self.iter.next_back(), - } - } - - #[inline] - fn try_rfold(&mut self, init: B, mut f: F) -> R - where - Self: Sized, - F: FnMut(B, Self::Item) -> R, - R: Try, - { - match self.peeked.take() { - Some(None) => try { init }, - Some(Some(v)) => match self.iter.try_rfold(init, &mut f).branch() { - ControlFlow::Continue(acc) => f(acc, v), - ControlFlow::Break(r) => { - self.peeked = Some(Some(v)); - R::from_residual(r) - } - }, - None => self.iter.try_rfold(init, f), - } - } - - #[inline] - fn rfold(self, init: Acc, mut fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - match self.peeked { - Some(None) => init, - Some(Some(v)) => { - let acc = self.iter.rfold(init, &mut fold); - fold(acc, v) - } - None => self.iter.rfold(init, fold), - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Peekable {} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Peekable {} - -impl Peekable { - /// Returns a reference to the next() value without advancing the iterator. - /// - /// Like [`next`], if there is a value, it is wrapped in a `Some(T)`. - /// But if the iteration is over, `None` is returned. - /// - /// [`next`]: Iterator::next - /// - /// Because `peek()` returns a reference, and many iterators iterate over - /// references, there can be a possibly confusing situation where the - /// return value is a double reference. You can see this effect in the - /// examples below. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let xs = [1, 2, 3]; - /// - /// let mut iter = xs.iter().peekable(); - /// - /// // peek() lets us see into the future - /// assert_eq!(iter.peek(), Some(&&1)); - /// assert_eq!(iter.next(), Some(&1)); - /// - /// assert_eq!(iter.next(), Some(&2)); - /// - /// // The iterator does not advance even if we `peek` multiple times - /// assert_eq!(iter.peek(), Some(&&3)); - /// assert_eq!(iter.peek(), Some(&&3)); - /// - /// assert_eq!(iter.next(), Some(&3)); - /// - /// // After the iterator is finished, so is `peek()` - /// assert_eq!(iter.peek(), None); - /// assert_eq!(iter.next(), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn peek(&mut self) -> Option<&I::Item> { - let iter = &mut self.iter; - self.peeked.get_or_insert_with(|| iter.next()).as_ref() - } - - /// Returns a mutable reference to the next() value without advancing the iterator. - /// - /// Like [`next`], if there is a value, it is wrapped in a `Some(T)`. - /// But if the iteration is over, `None` is returned. - /// - /// Because `peek_mut()` returns a reference, and many iterators iterate over - /// references, there can be a possibly confusing situation where the - /// return value is a double reference. You can see this effect in the examples - /// below. - /// - /// [`next`]: Iterator::next - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let mut iter = [1, 2, 3].iter().peekable(); - /// - /// // Like with `peek()`, we can see into the future without advancing the iterator. - /// assert_eq!(iter.peek_mut(), Some(&mut &1)); - /// assert_eq!(iter.peek_mut(), Some(&mut &1)); - /// assert_eq!(iter.next(), Some(&1)); - /// - /// // Peek into the iterator and set the value behind the mutable reference. - /// if let Some(p) = iter.peek_mut() { - /// assert_eq!(*p, &2); - /// *p = &5; - /// } - /// - /// // The value we put in reappears as the iterator continues. - /// assert_eq!(iter.collect::>(), vec![&5, &3]); - /// ``` - #[inline] - #[stable(feature = "peekable_peek_mut", since = "1.53.0")] - pub fn peek_mut(&mut self) -> Option<&mut I::Item> { - let iter = &mut self.iter; - self.peeked.get_or_insert_with(|| iter.next()).as_mut() - } - - /// Consume and return the next value of this iterator if a condition is true. - /// - /// If `func` returns `true` for the next value of this iterator, consume and return it. - /// Otherwise, return `None`. - /// - /// # Examples - /// Consume a number if it's equal to 0. - /// ``` - /// let mut iter = (0..5).peekable(); - /// // The first item of the iterator is 0; consume it. - /// assert_eq!(iter.next_if(|&x| x == 0), Some(0)); - /// // The next item returned is now 1, so `consume` will return `false`. - /// assert_eq!(iter.next_if(|&x| x == 0), None); - /// // `next_if` saves the value of the next item if it was not equal to `expected`. - /// assert_eq!(iter.next(), Some(1)); - /// ``` - /// - /// Consume any number less than 10. - /// ``` - /// let mut iter = (1..20).peekable(); - /// // Consume all numbers less than 10 - /// while iter.next_if(|&x| x < 10).is_some() {} - /// // The next value returned will be 10 - /// assert_eq!(iter.next(), Some(10)); - /// ``` - #[stable(feature = "peekable_next_if", since = "1.51.0")] - pub fn next_if(&mut self, func: impl FnOnce(&I::Item) -> bool) -> Option { - match self.next() { - Some(matched) if func(&matched) => Some(matched), - other => { - // Since we called `self.next()`, we consumed `self.peeked`. - assert!(self.peeked.is_none()); - self.peeked = Some(other); - None - } - } - } - - /// Consume and return the next item if it is equal to `expected`. - /// - /// # Example - /// Consume a number if it's equal to 0. - /// ``` - /// let mut iter = (0..5).peekable(); - /// // The first item of the iterator is 0; consume it. - /// assert_eq!(iter.next_if_eq(&0), Some(0)); - /// // The next item returned is now 1, so `consume` will return `false`. - /// assert_eq!(iter.next_if_eq(&0), None); - /// // `next_if_eq` saves the value of the next item if it was not equal to `expected`. - /// assert_eq!(iter.next(), Some(1)); - /// ``` - #[stable(feature = "peekable_next_if", since = "1.51.0")] - pub fn next_if_eq(&mut self, expected: &T) -> Option - where - T: ?Sized, - I::Item: PartialEq, - { - self.next_if(|next| next == expected) - } -} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for Peekable where I: TrustedLen {} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl SourceIter for Peekable -where - I: SourceIter, -{ - type Source = I::Source; - - #[inline] - unsafe fn as_inner(&mut self) -> &mut I::Source { - // SAFETY: unsafe function forwarding to unsafe function with the same requirements - unsafe { SourceIter::as_inner(&mut self.iter) } - } -} diff --git a/library/core/src/iter/adapters/rev.rs b/library/core/src/iter/adapters/rev.rs deleted file mode 100644 index 06ab15d5e900d..0000000000000 --- a/library/core/src/iter/adapters/rev.rs +++ /dev/null @@ -1,152 +0,0 @@ -use crate::iter::{FusedIterator, TrustedLen}; -use crate::num::NonZero; -use crate::ops::Try; - -/// A double-ended iterator with the direction inverted. -/// -/// This `struct` is created by the [`rev`] method on [`Iterator`]. See its -/// documentation for more. -/// -/// [`rev`]: Iterator::rev -/// [`Iterator`]: trait.Iterator.html -#[derive(Clone, Debug)] -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Rev { - iter: T, -} - -impl Rev { - pub(in crate::iter) fn new(iter: T) -> Rev { - Rev { iter } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for Rev -where - I: DoubleEndedIterator, -{ - type Item = ::Item; - - #[inline] - fn next(&mut self) -> Option<::Item> { - self.iter.next_back() - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } - - #[inline] - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - self.iter.advance_back_by(n) - } - - #[inline] - fn nth(&mut self, n: usize) -> Option<::Item> { - self.iter.nth_back(n) - } - - fn try_fold(&mut self, init: B, f: F) -> R - where - Self: Sized, - F: FnMut(B, Self::Item) -> R, - R: Try, - { - self.iter.try_rfold(init, f) - } - - fn fold(self, init: Acc, f: F) -> Acc - where - F: FnMut(Acc, Self::Item) -> Acc, - { - self.iter.rfold(init, f) - } - - #[inline] - fn find

(&mut self, predicate: P) -> Option - where - P: FnMut(&Self::Item) -> bool, - { - self.iter.rfind(predicate) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DoubleEndedIterator for Rev -where - I: DoubleEndedIterator, -{ - #[inline] - fn next_back(&mut self) -> Option<::Item> { - self.iter.next() - } - - #[inline] - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - self.iter.advance_by(n) - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option<::Item> { - self.iter.nth(n) - } - - fn try_rfold(&mut self, init: B, f: F) -> R - where - Self: Sized, - F: FnMut(B, Self::Item) -> R, - R: Try, - { - self.iter.try_fold(init, f) - } - - fn rfold(self, init: Acc, f: F) -> Acc - where - F: FnMut(Acc, Self::Item) -> Acc, - { - self.iter.fold(init, f) - } - - fn rfind

(&mut self, predicate: P) -> Option - where - P: FnMut(&Self::Item) -> bool, - { - self.iter.find(predicate) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Rev -where - I: ExactSizeIterator + DoubleEndedIterator, -{ - fn len(&self) -> usize { - self.iter.len() - } - - fn is_empty(&self) -> bool { - self.iter.is_empty() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Rev where I: FusedIterator + DoubleEndedIterator {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for Rev where I: TrustedLen + DoubleEndedIterator {} - -#[stable(feature = "default_iters", since = "1.70.0")] -impl Default for Rev { - /// Creates a `Rev` iterator from the default value of `I` - /// ``` - /// # use core::slice; - /// # use core::iter::Rev; - /// let iter: Rev> = Default::default(); - /// assert_eq!(iter.len(), 0); - /// ``` - fn default() -> Self { - Rev::new(Default::default()) - } -} diff --git a/library/core/src/iter/adapters/scan.rs b/library/core/src/iter/adapters/scan.rs deleted file mode 100644 index d261a535b183a..0000000000000 --- a/library/core/src/iter/adapters/scan.rs +++ /dev/null @@ -1,99 +0,0 @@ -use crate::fmt; -use crate::iter::{adapters::SourceIter, InPlaceIterable}; -use crate::num::NonZero; -use crate::ops::{ControlFlow, Try}; - -/// An iterator to maintain state while iterating another iterator. -/// -/// This `struct` is created by the [`scan`] method on [`Iterator`]. See its -/// documentation for more. -/// -/// [`scan`]: Iterator::scan -/// [`Iterator`]: trait.Iterator.html -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Clone)] -pub struct Scan { - iter: I, - f: F, - state: St, -} - -impl Scan { - pub(in crate::iter) fn new(iter: I, state: St, f: F) -> Scan { - Scan { iter, state, f } - } -} - -#[stable(feature = "core_impl_debug", since = "1.9.0")] -impl fmt::Debug for Scan { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Scan").field("iter", &self.iter).field("state", &self.state).finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for Scan -where - I: Iterator, - F: FnMut(&mut St, I::Item) -> Option, -{ - type Item = B; - - #[inline] - fn next(&mut self) -> Option { - let a = self.iter.next()?; - (self.f)(&mut self.state, a) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let (_, upper) = self.iter.size_hint(); - (0, upper) // can't know a lower bound, due to the scan function - } - - #[inline] - fn try_fold(&mut self, init: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - fn scan<'a, T, St, B, Acc, R: Try>( - state: &'a mut St, - f: &'a mut impl FnMut(&mut St, T) -> Option, - mut fold: impl FnMut(Acc, B) -> R + 'a, - ) -> impl FnMut(Acc, T) -> ControlFlow + 'a { - move |acc, x| match f(state, x) { - None => ControlFlow::Break(try { acc }), - Some(x) => ControlFlow::from_try(fold(acc, x)), - } - } - - let state = &mut self.state; - let f = &mut self.f; - self.iter.try_fold(init, scan(state, f, fold)).into_try() - } - - impl_fold_via_try_fold! { fold -> try_fold } -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl SourceIter for Scan -where - I: SourceIter, -{ - type Source = I::Source; - - #[inline] - unsafe fn as_inner(&mut self) -> &mut I::Source { - // SAFETY: unsafe function forwarding to unsafe function with the same requirements - unsafe { SourceIter::as_inner(&mut self.iter) } - } -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl InPlaceIterable for Scan { - const EXPAND_BY: Option> = I::EXPAND_BY; - const MERGE_BY: Option> = I::MERGE_BY; -} diff --git a/library/core/src/iter/adapters/skip.rs b/library/core/src/iter/adapters/skip.rs deleted file mode 100644 index f51a2c39b8e28..0000000000000 --- a/library/core/src/iter/adapters/skip.rs +++ /dev/null @@ -1,289 +0,0 @@ -use crate::intrinsics::unlikely; -use crate::iter::adapters::zip::try_get_unchecked; -use crate::iter::TrustedFused; -use crate::iter::{ - adapters::SourceIter, FusedIterator, InPlaceIterable, TrustedLen, TrustedRandomAccess, - TrustedRandomAccessNoCoerce, -}; -use crate::num::NonZero; -use crate::ops::{ControlFlow, Try}; - -/// An iterator that skips over `n` elements of `iter`. -/// -/// This `struct` is created by the [`skip`] method on [`Iterator`]. See its -/// documentation for more. -/// -/// [`skip`]: Iterator::skip -/// [`Iterator`]: trait.Iterator.html -#[derive(Clone, Debug)] -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Skip { - iter: I, - n: usize, -} - -impl Skip { - pub(in crate::iter) fn new(iter: I, n: usize) -> Skip { - Skip { iter, n } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for Skip -where - I: Iterator, -{ - type Item = ::Item; - - #[inline] - fn next(&mut self) -> Option { - if unlikely(self.n > 0) { - self.iter.nth(crate::mem::take(&mut self.n)) - } else { - self.iter.next() - } - } - - #[inline] - fn nth(&mut self, n: usize) -> Option { - if self.n > 0 { - let skip: usize = crate::mem::take(&mut self.n); - // Checked add to handle overflow case. - let n = match skip.checked_add(n) { - Some(nth) => nth, - None => { - // In case of overflow, load skip value, before loading `n`. - // Because the amount of elements to iterate is beyond `usize::MAX`, this - // is split into two `nth` calls where the `skip` `nth` call is discarded. - self.iter.nth(skip - 1)?; - n - } - }; - // Load nth element including skip. - self.iter.nth(n) - } else { - self.iter.nth(n) - } - } - - #[inline] - fn count(mut self) -> usize { - if self.n > 0 { - // nth(n) skips n+1 - if self.iter.nth(self.n - 1).is_none() { - return 0; - } - } - self.iter.count() - } - - #[inline] - fn last(mut self) -> Option { - if self.n > 0 { - // nth(n) skips n+1 - self.iter.nth(self.n - 1)?; - } - self.iter.last() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let (lower, upper) = self.iter.size_hint(); - - let lower = lower.saturating_sub(self.n); - let upper = match upper { - Some(x) => Some(x.saturating_sub(self.n)), - None => None, - }; - - (lower, upper) - } - - #[inline] - fn try_fold(&mut self, init: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - let n = self.n; - self.n = 0; - if n > 0 { - // nth(n) skips n+1 - if self.iter.nth(n - 1).is_none() { - return try { init }; - } - } - self.iter.try_fold(init, fold) - } - - #[inline] - fn fold(mut self, init: Acc, fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - if self.n > 0 { - // nth(n) skips n+1 - if self.iter.nth(self.n - 1).is_none() { - return init; - } - } - self.iter.fold(init, fold) - } - - #[inline] - #[rustc_inherit_overflow_checks] - fn advance_by(&mut self, mut n: usize) -> Result<(), NonZero> { - let skip_inner = self.n; - let skip_and_advance = skip_inner.saturating_add(n); - - let remainder = match self.iter.advance_by(skip_and_advance) { - Ok(()) => 0, - Err(n) => n.get(), - }; - let advanced_inner = skip_and_advance - remainder; - n -= advanced_inner.saturating_sub(skip_inner); - self.n = self.n.saturating_sub(advanced_inner); - - // skip_and_advance may have saturated - if unlikely(remainder == 0 && n > 0) { - n = match self.iter.advance_by(n) { - Ok(()) => 0, - Err(n) => n.get(), - } - } - - NonZero::new(n).map_or(Ok(()), Err) - } - - #[doc(hidden)] - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item - where - Self: TrustedRandomAccessNoCoerce, - { - // SAFETY: the caller must uphold the contract for - // `Iterator::__iterator_get_unchecked`. - // - // Dropping the skipped prefix when index 0 is passed is safe - // since - // * the caller passing index 0 means that the inner iterator has more items than `self.n` - // * TRA contract requires that get_unchecked will only be called once - // (unless elements are copyable) - // * it does not conflict with in-place iteration since index 0 must be accessed - // before something is written into the storage used by the prefix - unsafe { - if Self::MAY_HAVE_SIDE_EFFECT && idx == 0 { - for skipped_idx in 0..self.n { - drop(try_get_unchecked(&mut self.iter, skipped_idx)); - } - } - - try_get_unchecked(&mut self.iter, idx + self.n) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Skip where I: ExactSizeIterator {} - -#[stable(feature = "double_ended_skip_iterator", since = "1.9.0")] -impl DoubleEndedIterator for Skip -where - I: DoubleEndedIterator + ExactSizeIterator, -{ - fn next_back(&mut self) -> Option { - if self.len() > 0 { self.iter.next_back() } else { None } - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option { - let len = self.len(); - if n < len { - self.iter.nth_back(n) - } else { - if len > 0 { - // consume the original iterator - self.iter.nth_back(len - 1); - } - None - } - } - - fn try_rfold(&mut self, init: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - fn check>( - mut n: usize, - mut fold: impl FnMut(Acc, T) -> R, - ) -> impl FnMut(Acc, T) -> ControlFlow { - move |acc, x| { - n -= 1; - let r = fold(acc, x); - if n == 0 { ControlFlow::Break(r) } else { ControlFlow::from_try(r) } - } - } - - let n = self.len(); - if n == 0 { try { init } } else { self.iter.try_rfold(init, check(n, fold)).into_try() } - } - - impl_fold_via_try_fold! { rfold -> try_rfold } - - #[inline] - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - let min = crate::cmp::min(self.len(), n); - let rem = self.iter.advance_back_by(min); - assert!(rem.is_ok(), "ExactSizeIterator contract violation"); - NonZero::new(n - min).map_or(Ok(()), Err) - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Skip where I: FusedIterator {} - -#[unstable(issue = "none", feature = "trusted_fused")] -unsafe impl TrustedFused for Skip {} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl SourceIter for Skip -where - I: SourceIter, -{ - type Source = I::Source; - - #[inline] - unsafe fn as_inner(&mut self) -> &mut I::Source { - // SAFETY: unsafe function forwarding to unsafe function with the same requirements - unsafe { SourceIter::as_inner(&mut self.iter) } - } -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl InPlaceIterable for Skip { - const EXPAND_BY: Option> = I::EXPAND_BY; - const MERGE_BY: Option> = I::MERGE_BY; -} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl TrustedRandomAccess for Skip where I: TrustedRandomAccess {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl TrustedRandomAccessNoCoerce for Skip -where - I: TrustedRandomAccessNoCoerce, -{ - const MAY_HAVE_SIDE_EFFECT: bool = I::MAY_HAVE_SIDE_EFFECT; -} - -// SAFETY: This adapter is shortening. TrustedLen requires the upper bound to be calculated correctly. -// These requirements can only be satisfied when the upper bound of the inner iterator's upper -// bound is never `None`. I: TrustedRandomAccess happens to provide this guarantee while -// I: TrustedLen would not. -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for Skip where I: Iterator + TrustedRandomAccess {} diff --git a/library/core/src/iter/adapters/skip_while.rs b/library/core/src/iter/adapters/skip_while.rs deleted file mode 100644 index 8001e6e64713a..0000000000000 --- a/library/core/src/iter/adapters/skip_while.rs +++ /dev/null @@ -1,129 +0,0 @@ -use crate::fmt; -use crate::iter::{adapters::SourceIter, FusedIterator, InPlaceIterable, TrustedFused}; -use crate::num::NonZero; -use crate::ops::Try; - -/// An iterator that rejects elements while `predicate` returns `true`. -/// -/// This `struct` is created by the [`skip_while`] method on [`Iterator`]. See its -/// documentation for more. -/// -/// [`skip_while`]: Iterator::skip_while -/// [`Iterator`]: trait.Iterator.html -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Clone)] -pub struct SkipWhile { - iter: I, - flag: bool, - predicate: P, -} - -impl SkipWhile { - pub(in crate::iter) fn new(iter: I, predicate: P) -> SkipWhile { - SkipWhile { iter, flag: false, predicate } - } -} - -#[stable(feature = "core_impl_debug", since = "1.9.0")] -impl fmt::Debug for SkipWhile { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("SkipWhile").field("iter", &self.iter).field("flag", &self.flag).finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for SkipWhile -where - P: FnMut(&I::Item) -> bool, -{ - type Item = I::Item; - - #[inline] - fn next(&mut self) -> Option { - fn check<'a, T>( - flag: &'a mut bool, - pred: &'a mut impl FnMut(&T) -> bool, - ) -> impl FnMut(&T) -> bool + 'a { - move |x| { - if *flag || !pred(x) { - *flag = true; - true - } else { - false - } - } - } - - let flag = &mut self.flag; - let pred = &mut self.predicate; - self.iter.find(check(flag, pred)) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let (_, upper) = self.iter.size_hint(); - (0, upper) // can't know a lower bound, due to the predicate - } - - #[inline] - fn try_fold(&mut self, mut init: Acc, mut fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - if !self.flag { - match self.next() { - Some(v) => init = fold(init, v)?, - None => return try { init }, - } - } - self.iter.try_fold(init, fold) - } - - #[inline] - fn fold(mut self, mut init: Acc, mut fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - if !self.flag { - match self.next() { - Some(v) => init = fold(init, v), - None => return init, - } - } - self.iter.fold(init, fold) - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for SkipWhile -where - I: FusedIterator, - P: FnMut(&I::Item) -> bool, -{ -} - -#[unstable(issue = "none", feature = "trusted_fused")] -unsafe impl TrustedFused for SkipWhile {} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl SourceIter for SkipWhile -where - I: SourceIter, -{ - type Source = I::Source; - - #[inline] - unsafe fn as_inner(&mut self) -> &mut I::Source { - // SAFETY: unsafe function forwarding to unsafe function with the same requirements - unsafe { SourceIter::as_inner(&mut self.iter) } - } -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl InPlaceIterable for SkipWhile { - const EXPAND_BY: Option> = I::EXPAND_BY; - const MERGE_BY: Option> = I::MERGE_BY; -} diff --git a/library/core/src/iter/adapters/step_by.rs b/library/core/src/iter/adapters/step_by.rs deleted file mode 100644 index abdf2f415fe55..0000000000000 --- a/library/core/src/iter/adapters/step_by.rs +++ /dev/null @@ -1,583 +0,0 @@ -use crate::{ - intrinsics, - iter::{from_fn, TrustedLen, TrustedRandomAccess}, - num::NonZero, - ops::{Range, Try}, -}; - -/// An iterator for stepping iterators by a custom amount. -/// -/// This `struct` is created by the [`step_by`] method on [`Iterator`]. See -/// its documentation for more. -/// -/// [`step_by`]: Iterator::step_by -/// [`Iterator`]: trait.Iterator.html -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "iterator_step_by", since = "1.28.0")] -#[derive(Clone, Debug)] -pub struct StepBy { - /// This field is guaranteed to be preprocessed by the specialized `SpecRangeSetup::setup` - /// in the constructor. - /// For most iterators that processing is a no-op, but for Range<{integer}> types it is lossy - /// which means the inner iterator cannot be returned to user code. - /// Additionally this type-dependent preprocessing means specialized implementations - /// cannot be used interchangeably. - iter: I, - /// This field is `step - 1`, aka the correct amount to pass to `nth` when iterating. - /// It MUST NOT be `usize::MAX`, as `unsafe` code depends on being able to add one - /// without the risk of overflow. (This is important so that length calculations - /// don't need to check for division-by-zero, for example.) - step_minus_one: usize, - first_take: bool, -} - -impl StepBy { - #[inline] - pub(in crate::iter) fn new(iter: I, step: usize) -> StepBy { - assert!(step != 0); - let iter = >::setup(iter, step); - StepBy { iter, step_minus_one: step - 1, first_take: true } - } - - /// The `step` that was originally passed to `Iterator::step_by(step)`, - /// aka `self.step_minus_one + 1`. - #[inline] - fn original_step(&self) -> NonZero { - // SAFETY: By type invariant, `step_minus_one` cannot be `MAX`, which - // means the addition cannot overflow and the result cannot be zero. - unsafe { NonZero::new_unchecked(intrinsics::unchecked_add(self.step_minus_one, 1)) } - } -} - -#[stable(feature = "iterator_step_by", since = "1.28.0")] -impl Iterator for StepBy -where - I: Iterator, -{ - type Item = I::Item; - - #[inline] - fn next(&mut self) -> Option { - self.spec_next() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.spec_size_hint() - } - - #[inline] - fn nth(&mut self, n: usize) -> Option { - self.spec_nth(n) - } - - fn try_fold(&mut self, acc: Acc, f: F) -> R - where - F: FnMut(Acc, Self::Item) -> R, - R: Try, - { - self.spec_try_fold(acc, f) - } - - #[inline] - fn fold(self, acc: Acc, f: F) -> Acc - where - F: FnMut(Acc, Self::Item) -> Acc, - { - self.spec_fold(acc, f) - } -} - -impl StepBy -where - I: ExactSizeIterator, -{ - // The zero-based index starting from the end of the iterator of the - // last element. Used in the `DoubleEndedIterator` implementation. - fn next_back_index(&self) -> usize { - let rem = self.iter.len() % self.original_step(); - if self.first_take { if rem == 0 { self.step_minus_one } else { rem - 1 } } else { rem } - } -} - -#[stable(feature = "double_ended_step_by_iterator", since = "1.38.0")] -impl DoubleEndedIterator for StepBy -where - I: DoubleEndedIterator + ExactSizeIterator, -{ - #[inline] - fn next_back(&mut self) -> Option { - self.spec_next_back() - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option { - self.spec_nth_back(n) - } - - fn try_rfold(&mut self, init: Acc, f: F) -> R - where - F: FnMut(Acc, Self::Item) -> R, - R: Try, - { - self.spec_try_rfold(init, f) - } - - #[inline] - fn rfold(self, init: Acc, f: F) -> Acc - where - Self: Sized, - F: FnMut(Acc, Self::Item) -> Acc, - { - self.spec_rfold(init, f) - } -} - -// StepBy can only make the iterator shorter, so the len will still fit. -#[stable(feature = "iterator_step_by", since = "1.28.0")] -impl ExactSizeIterator for StepBy where I: ExactSizeIterator {} - -// SAFETY: This adapter is shortening. TrustedLen requires the upper bound to be calculated correctly. -// These requirements can only be satisfied when the upper bound of the inner iterator's upper -// bound is never `None`. I: TrustedRandomAccess happens to provide this guarantee while -// I: TrustedLen would not. -// This also covers the Range specializations since the ranges also implement TRA -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for StepBy where I: Iterator + TrustedRandomAccess {} - -trait SpecRangeSetup { - fn setup(inner: T, step: usize) -> T; -} - -impl SpecRangeSetup for T { - #[inline] - default fn setup(inner: T, _step: usize) -> T { - inner - } -} - -/// Specialization trait to optimize `StepBy>` iteration. -/// -/// # Safety -/// -/// Technically this is safe to implement (look ma, no unsafe!), but in reality -/// a lot of unsafe code relies on ranges over integers being correct. -/// -/// For correctness *all* public StepBy methods must be specialized -/// because `setup` drastically alters the meaning of the struct fields so that mixing -/// different implementations would lead to incorrect results. -unsafe trait StepByImpl { - type Item; - - fn spec_next(&mut self) -> Option; - - fn spec_size_hint(&self) -> (usize, Option); - - fn spec_nth(&mut self, n: usize) -> Option; - - fn spec_try_fold(&mut self, acc: Acc, f: F) -> R - where - F: FnMut(Acc, Self::Item) -> R, - R: Try; - - fn spec_fold(self, acc: Acc, f: F) -> Acc - where - F: FnMut(Acc, Self::Item) -> Acc; -} - -/// Specialization trait for double-ended iteration. -/// -/// See also: `StepByImpl` -/// -/// # Safety -/// -/// The specializations must be implemented together with `StepByImpl` -/// where applicable. I.e. if `StepBy` does support backwards iteration -/// for a given iterator and that is specialized for forward iteration then -/// it must also be specialized for backwards iteration. -unsafe trait StepByBackImpl { - type Item; - - fn spec_next_back(&mut self) -> Option - where - I: DoubleEndedIterator + ExactSizeIterator; - - fn spec_nth_back(&mut self, n: usize) -> Option - where - I: DoubleEndedIterator + ExactSizeIterator; - - fn spec_try_rfold(&mut self, init: Acc, f: F) -> R - where - I: DoubleEndedIterator + ExactSizeIterator, - F: FnMut(Acc, Self::Item) -> R, - R: Try; - - fn spec_rfold(self, init: Acc, f: F) -> Acc - where - I: DoubleEndedIterator + ExactSizeIterator, - F: FnMut(Acc, Self::Item) -> Acc; -} - -unsafe impl StepByImpl for StepBy { - type Item = I::Item; - - #[inline] - default fn spec_next(&mut self) -> Option { - let step_size = if self.first_take { 0 } else { self.step_minus_one }; - self.first_take = false; - self.iter.nth(step_size) - } - - #[inline] - default fn spec_size_hint(&self) -> (usize, Option) { - #[inline] - fn first_size(step: NonZero) -> impl Fn(usize) -> usize { - move |n| if n == 0 { 0 } else { 1 + (n - 1) / step } - } - - #[inline] - fn other_size(step: NonZero) -> impl Fn(usize) -> usize { - move |n| n / step - } - - let (low, high) = self.iter.size_hint(); - - if self.first_take { - let f = first_size(self.original_step()); - (f(low), high.map(f)) - } else { - let f = other_size(self.original_step()); - (f(low), high.map(f)) - } - } - - #[inline] - default fn spec_nth(&mut self, mut n: usize) -> Option { - if self.first_take { - self.first_take = false; - let first = self.iter.next(); - if n == 0 { - return first; - } - n -= 1; - } - // n and self.step_minus_one are indices, we need to add 1 to get the amount of elements - // When calling `.nth`, we need to subtract 1 again to convert back to an index - let mut step = self.original_step().get(); - // n + 1 could overflow - // thus, if n is usize::MAX, instead of adding one, we call .nth(step) - if n == usize::MAX { - self.iter.nth(step - 1); - } else { - n += 1; - } - - // overflow handling - loop { - let mul = n.checked_mul(step); - { - if intrinsics::likely(mul.is_some()) { - return self.iter.nth(mul.unwrap() - 1); - } - } - let div_n = usize::MAX / n; - let div_step = usize::MAX / step; - let nth_n = div_n * n; - let nth_step = div_step * step; - let nth = if nth_n > nth_step { - step -= div_n; - nth_n - } else { - n -= div_step; - nth_step - }; - self.iter.nth(nth - 1); - } - } - - default fn spec_try_fold(&mut self, mut acc: Acc, mut f: F) -> R - where - F: FnMut(Acc, Self::Item) -> R, - R: Try, - { - #[inline] - fn nth( - iter: &mut I, - step_minus_one: usize, - ) -> impl FnMut() -> Option + '_ { - move || iter.nth(step_minus_one) - } - - if self.first_take { - self.first_take = false; - match self.iter.next() { - None => return try { acc }, - Some(x) => acc = f(acc, x)?, - } - } - from_fn(nth(&mut self.iter, self.step_minus_one)).try_fold(acc, f) - } - - default fn spec_fold(mut self, mut acc: Acc, mut f: F) -> Acc - where - F: FnMut(Acc, Self::Item) -> Acc, - { - #[inline] - fn nth( - iter: &mut I, - step_minus_one: usize, - ) -> impl FnMut() -> Option + '_ { - move || iter.nth(step_minus_one) - } - - if self.first_take { - self.first_take = false; - match self.iter.next() { - None => return acc, - Some(x) => acc = f(acc, x), - } - } - from_fn(nth(&mut self.iter, self.step_minus_one)).fold(acc, f) - } -} - -unsafe impl StepByBackImpl for StepBy { - type Item = I::Item; - - #[inline] - default fn spec_next_back(&mut self) -> Option { - self.iter.nth_back(self.next_back_index()) - } - - #[inline] - default fn spec_nth_back(&mut self, n: usize) -> Option { - // `self.iter.nth_back(usize::MAX)` does the right thing here when `n` - // is out of bounds because the length of `self.iter` does not exceed - // `usize::MAX` (because `I: ExactSizeIterator`) and `nth_back` is - // zero-indexed - let n = n.saturating_mul(self.original_step().get()).saturating_add(self.next_back_index()); - self.iter.nth_back(n) - } - - default fn spec_try_rfold(&mut self, init: Acc, mut f: F) -> R - where - F: FnMut(Acc, Self::Item) -> R, - R: Try, - { - #[inline] - fn nth_back( - iter: &mut I, - step_minus_one: usize, - ) -> impl FnMut() -> Option + '_ { - move || iter.nth_back(step_minus_one) - } - - match self.next_back() { - None => try { init }, - Some(x) => { - let acc = f(init, x)?; - from_fn(nth_back(&mut self.iter, self.step_minus_one)).try_fold(acc, f) - } - } - } - - #[inline] - default fn spec_rfold(mut self, init: Acc, mut f: F) -> Acc - where - Self: Sized, - F: FnMut(Acc, I::Item) -> Acc, - { - #[inline] - fn nth_back( - iter: &mut I, - step_minus_one: usize, - ) -> impl FnMut() -> Option + '_ { - move || iter.nth_back(step_minus_one) - } - - match self.next_back() { - None => init, - Some(x) => { - let acc = f(init, x); - from_fn(nth_back(&mut self.iter, self.step_minus_one)).fold(acc, f) - } - } - } -} - -/// For these implementations, `SpecRangeSetup` calculates the number -/// of iterations that will be needed and stores that in `iter.end`. -/// -/// The various iterator implementations then rely on that to not need -/// overflow checking, letting loops just be counted instead. -/// -/// These only work for unsigned types, and will need to be reworked -/// if you want to use it to specialize on signed types. -/// -/// Currently these are only implemented for integers up to usize due to -/// correctness issues around ExactSizeIterator impls on 16bit platforms. -/// And since ExactSizeIterator is a prerequisite for backwards iteration -/// and we must consistently specialize backwards and forwards iteration -/// that makes the situation complicated enough that it's not covered -/// for now. -macro_rules! spec_int_ranges { - ($($t:ty)*) => ($( - - const _: () = assert!(usize::BITS >= <$t>::BITS); - - impl SpecRangeSetup> for Range<$t> { - #[inline] - fn setup(mut r: Range<$t>, step: usize) -> Range<$t> { - let inner_len = r.size_hint().0; - // If step exceeds $t::MAX, then the count will be at most 1 and - // thus always fit into $t. - let yield_count = inner_len.div_ceil(step); - // Turn the range end into an iteration counter - r.end = yield_count as $t; - r - } - } - - unsafe impl StepByImpl> for StepBy> { - #[inline] - fn spec_next(&mut self) -> Option<$t> { - // if a step size larger than the type has been specified fall back to - // t::MAX, in which case remaining will be at most 1. - let step = <$t>::try_from(self.original_step().get()).unwrap_or(<$t>::MAX); - let remaining = self.iter.end; - if remaining > 0 { - let val = self.iter.start; - // this can only overflow during the last step, after which the value - // will not be used - self.iter.start = val.wrapping_add(step); - self.iter.end = remaining - 1; - Some(val) - } else { - None - } - } - - #[inline] - fn spec_size_hint(&self) -> (usize, Option) { - let remaining = self.iter.end as usize; - (remaining, Some(remaining)) - } - - // The methods below are all copied from the Iterator trait default impls. - // We have to repeat them here so that the specialization overrides the StepByImpl defaults - - #[inline] - fn spec_nth(&mut self, n: usize) -> Option { - self.advance_by(n).ok()?; - self.next() - } - - #[inline] - fn spec_try_fold(&mut self, init: Acc, mut f: F) -> R - where - F: FnMut(Acc, Self::Item) -> R, - R: Try - { - let mut accum = init; - while let Some(x) = self.next() { - accum = f(accum, x)?; - } - try { accum } - } - - #[inline] - fn spec_fold(self, init: Acc, mut f: F) -> Acc - where - F: FnMut(Acc, Self::Item) -> Acc - { - // if a step size larger than the type has been specified fall back to - // t::MAX, in which case remaining will be at most 1. - let step = <$t>::try_from(self.original_step().get()).unwrap_or(<$t>::MAX); - let remaining = self.iter.end; - let mut acc = init; - let mut val = self.iter.start; - for _ in 0..remaining { - acc = f(acc, val); - // this can only overflow during the last step, after which the value - // will no longer be used - val = val.wrapping_add(step); - } - acc - } - } - )*) -} - -macro_rules! spec_int_ranges_r { - ($($t:ty)*) => ($( - const _: () = assert!(usize::BITS >= <$t>::BITS); - - unsafe impl StepByBackImpl> for StepBy> { - - #[inline] - fn spec_next_back(&mut self) -> Option { - let step = self.original_step().get() as $t; - let remaining = self.iter.end; - if remaining > 0 { - let start = self.iter.start; - self.iter.end = remaining - 1; - Some(start + step * (remaining - 1)) - } else { - None - } - } - - // The methods below are all copied from the Iterator trait default impls. - // We have to repeat them here so that the specialization overrides the StepByImplBack defaults - - #[inline] - fn spec_nth_back(&mut self, n: usize) -> Option { - if self.advance_back_by(n).is_err() { - return None; - } - self.next_back() - } - - #[inline] - fn spec_try_rfold(&mut self, init: Acc, mut f: F) -> R - where - F: FnMut(Acc, Self::Item) -> R, - R: Try - { - let mut accum = init; - while let Some(x) = self.next_back() { - accum = f(accum, x)?; - } - try { accum } - } - - #[inline] - fn spec_rfold(mut self, init: Acc, mut f: F) -> Acc - where - F: FnMut(Acc, Self::Item) -> Acc - { - let mut accum = init; - while let Some(x) = self.next_back() { - accum = f(accum, x); - } - accum - } - } - )*) -} - -#[cfg(target_pointer_width = "64")] -spec_int_ranges!(u8 u16 u32 u64 usize); -// DoubleEndedIterator requires ExactSizeIterator, which isn't implemented for Range -#[cfg(target_pointer_width = "64")] -spec_int_ranges_r!(u8 u16 u32 usize); - -#[cfg(target_pointer_width = "32")] -spec_int_ranges!(u8 u16 u32 usize); -#[cfg(target_pointer_width = "32")] -spec_int_ranges_r!(u8 u16 u32 usize); - -#[cfg(target_pointer_width = "16")] -spec_int_ranges!(u8 u16 usize); -#[cfg(target_pointer_width = "16")] -spec_int_ranges_r!(u8 u16 usize); diff --git a/library/core/src/iter/adapters/take.rs b/library/core/src/iter/adapters/take.rs deleted file mode 100644 index 6870c677b1e07..0000000000000 --- a/library/core/src/iter/adapters/take.rs +++ /dev/null @@ -1,321 +0,0 @@ -use crate::cmp; -use crate::iter::{ - adapters::SourceIter, FusedIterator, InPlaceIterable, TrustedFused, TrustedLen, - TrustedRandomAccess, -}; -use crate::num::NonZero; -use crate::ops::{ControlFlow, Try}; - -/// An iterator that only iterates over the first `n` iterations of `iter`. -/// -/// This `struct` is created by the [`take`] method on [`Iterator`]. See its -/// documentation for more. -/// -/// [`take`]: Iterator::take -/// [`Iterator`]: trait.Iterator.html -#[derive(Clone, Debug)] -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Take { - iter: I, - n: usize, -} - -impl Take { - pub(in crate::iter) fn new(iter: I, n: usize) -> Take { - Take { iter, n } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for Take -where - I: Iterator, -{ - type Item = ::Item; - - #[inline] - fn next(&mut self) -> Option<::Item> { - if self.n != 0 { - self.n -= 1; - self.iter.next() - } else { - None - } - } - - #[inline] - fn nth(&mut self, n: usize) -> Option { - if self.n > n { - self.n -= n + 1; - self.iter.nth(n) - } else { - if self.n > 0 { - self.iter.nth(self.n - 1); - self.n = 0; - } - None - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - if self.n == 0 { - return (0, Some(0)); - } - - let (lower, upper) = self.iter.size_hint(); - - let lower = cmp::min(lower, self.n); - - let upper = match upper { - Some(x) if x < self.n => Some(x), - _ => Some(self.n), - }; - - (lower, upper) - } - - #[inline] - fn try_fold(&mut self, init: Acc, fold: Fold) -> R - where - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - fn check<'a, T, Acc, R: Try>( - n: &'a mut usize, - mut fold: impl FnMut(Acc, T) -> R + 'a, - ) -> impl FnMut(Acc, T) -> ControlFlow + 'a { - move |acc, x| { - *n -= 1; - let r = fold(acc, x); - if *n == 0 { ControlFlow::Break(r) } else { ControlFlow::from_try(r) } - } - } - - if self.n == 0 { - try { init } - } else { - let n = &mut self.n; - self.iter.try_fold(init, check(n, fold)).into_try() - } - } - - #[inline] - fn fold(self, init: B, f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - Self::spec_fold(self, init, f) - } - - #[inline] - fn for_each(self, f: F) { - Self::spec_for_each(self, f) - } - - #[inline] - #[rustc_inherit_overflow_checks] - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - let min = self.n.min(n); - let rem = match self.iter.advance_by(min) { - Ok(()) => 0, - Err(rem) => rem.get(), - }; - let advanced = min - rem; - self.n -= advanced; - NonZero::new(n - advanced).map_or(Ok(()), Err) - } -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl SourceIter for Take -where - I: SourceIter, -{ - type Source = I::Source; - - #[inline] - unsafe fn as_inner(&mut self) -> &mut I::Source { - // SAFETY: unsafe function forwarding to unsafe function with the same requirements - unsafe { SourceIter::as_inner(&mut self.iter) } - } -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl InPlaceIterable for Take { - const EXPAND_BY: Option> = I::EXPAND_BY; - const MERGE_BY: Option> = I::MERGE_BY; -} - -#[stable(feature = "double_ended_take_iterator", since = "1.38.0")] -impl DoubleEndedIterator for Take -where - I: DoubleEndedIterator + ExactSizeIterator, -{ - #[inline] - fn next_back(&mut self) -> Option { - if self.n == 0 { - None - } else { - let n = self.n; - self.n -= 1; - self.iter.nth_back(self.iter.len().saturating_sub(n)) - } - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option { - let len = self.iter.len(); - if self.n > n { - let m = len.saturating_sub(self.n) + n; - self.n -= n + 1; - self.iter.nth_back(m) - } else { - if len > 0 { - self.iter.nth_back(len - 1); - } - None - } - } - - #[inline] - fn try_rfold(&mut self, init: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - if self.n == 0 { - try { init } - } else { - let len = self.iter.len(); - if len > self.n && self.iter.nth_back(len - self.n - 1).is_none() { - try { init } - } else { - self.iter.try_rfold(init, fold) - } - } - } - - #[inline] - fn rfold(mut self, init: Acc, fold: Fold) -> Acc - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> Acc, - { - if self.n == 0 { - init - } else { - let len = self.iter.len(); - if len > self.n && self.iter.nth_back(len - self.n - 1).is_none() { - init - } else { - self.iter.rfold(init, fold) - } - } - } - - #[inline] - #[rustc_inherit_overflow_checks] - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - // The amount by which the inner iterator needs to be shortened for it to be - // at most as long as the take() amount. - let trim_inner = self.iter.len().saturating_sub(self.n); - // The amount we need to advance inner to fulfill the caller's request. - // take(), advance_by() and len() all can be at most usize, so we don't have to worry - // about having to advance more than usize::MAX here. - let advance_by = trim_inner.saturating_add(n); - - let remainder = match self.iter.advance_back_by(advance_by) { - Ok(()) => 0, - Err(rem) => rem.get(), - }; - let advanced_by_inner = advance_by - remainder; - let advanced_by = advanced_by_inner - trim_inner; - self.n -= advanced_by; - NonZero::new(n - advanced_by).map_or(Ok(()), Err) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Take where I: ExactSizeIterator {} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Take where I: FusedIterator {} - -#[unstable(issue = "none", feature = "trusted_fused")] -unsafe impl TrustedFused for Take {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for Take {} - -trait SpecTake: Iterator { - fn spec_fold(self, init: B, f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B; - - fn spec_for_each(self, f: F); -} - -impl SpecTake for Take { - #[inline] - default fn spec_fold(mut self, init: B, f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - use crate::ops::NeverShortCircuit; - self.try_fold(init, NeverShortCircuit::wrap_mut_2(f)).0 - } - - #[inline] - default fn spec_for_each(mut self, f: F) { - // The default implementation would use a unit accumulator, so we can - // avoid a stateful closure by folding over the remaining number - // of items we wish to return instead. - fn check<'a, Item>( - mut action: impl FnMut(Item) + 'a, - ) -> impl FnMut(usize, Item) -> Option + 'a { - move |more, x| { - action(x); - more.checked_sub(1) - } - } - - let remaining = self.n; - if remaining > 0 { - self.iter.try_fold(remaining - 1, check(f)); - } - } -} - -impl SpecTake for Take { - #[inline] - fn spec_fold(mut self, init: B, mut f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - let mut acc = init; - let end = self.n.min(self.iter.size()); - for i in 0..end { - // SAFETY: i < end <= self.iter.size() and we discard the iterator at the end - let val = unsafe { self.iter.__iterator_get_unchecked(i) }; - acc = f(acc, val); - } - acc - } - - #[inline] - fn spec_for_each(mut self, mut f: F) { - let end = self.n.min(self.iter.size()); - for i in 0..end { - // SAFETY: i < end <= self.iter.size() and we discard the iterator at the end - let val = unsafe { self.iter.__iterator_get_unchecked(i) }; - f(val); - } - } -} diff --git a/library/core/src/iter/adapters/take_while.rs b/library/core/src/iter/adapters/take_while.rs deleted file mode 100644 index d3f09ab356ad8..0000000000000 --- a/library/core/src/iter/adapters/take_while.rs +++ /dev/null @@ -1,130 +0,0 @@ -use crate::fmt; -use crate::iter::{adapters::SourceIter, FusedIterator, InPlaceIterable, TrustedFused}; -use crate::num::NonZero; -use crate::ops::{ControlFlow, Try}; - -/// An iterator that only accepts elements while `predicate` returns `true`. -/// -/// This `struct` is created by the [`take_while`] method on [`Iterator`]. See its -/// documentation for more. -/// -/// [`take_while`]: Iterator::take_while -/// [`Iterator`]: trait.Iterator.html -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Clone)] -pub struct TakeWhile { - iter: I, - flag: bool, - predicate: P, -} - -impl TakeWhile { - pub(in crate::iter) fn new(iter: I, predicate: P) -> TakeWhile { - TakeWhile { iter, flag: false, predicate } - } -} - -#[stable(feature = "core_impl_debug", since = "1.9.0")] -impl fmt::Debug for TakeWhile { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("TakeWhile").field("iter", &self.iter).field("flag", &self.flag).finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for TakeWhile -where - P: FnMut(&I::Item) -> bool, -{ - type Item = I::Item; - - #[inline] - fn next(&mut self) -> Option { - if self.flag { - None - } else { - let x = self.iter.next()?; - if (self.predicate)(&x) { - Some(x) - } else { - self.flag = true; - None - } - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - if self.flag { - (0, Some(0)) - } else { - let (_, upper) = self.iter.size_hint(); - (0, upper) // can't know a lower bound, due to the predicate - } - } - - #[inline] - fn try_fold(&mut self, init: Acc, fold: Fold) -> R - where - Self: Sized, - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - fn check<'a, T, Acc, R: Try>( - flag: &'a mut bool, - p: &'a mut impl FnMut(&T) -> bool, - mut fold: impl FnMut(Acc, T) -> R + 'a, - ) -> impl FnMut(Acc, T) -> ControlFlow + 'a { - move |acc, x| { - if p(&x) { - ControlFlow::from_try(fold(acc, x)) - } else { - *flag = true; - ControlFlow::Break(try { acc }) - } - } - } - - if self.flag { - try { init } - } else { - let flag = &mut self.flag; - let p = &mut self.predicate; - self.iter.try_fold(init, check(flag, p, fold)).into_try() - } - } - - impl_fold_via_try_fold! { fold -> try_fold } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for TakeWhile -where - I: FusedIterator, - P: FnMut(&I::Item) -> bool, -{ -} - -#[unstable(issue = "none", feature = "trusted_fused")] -unsafe impl TrustedFused for TakeWhile {} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl SourceIter for TakeWhile -where - I: SourceIter, -{ - type Source = I::Source; - - #[inline] - unsafe fn as_inner(&mut self) -> &mut I::Source { - // SAFETY: unsafe function forwarding to unsafe function with the same requirements - unsafe { SourceIter::as_inner(&mut self.iter) } - } -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl InPlaceIterable for TakeWhile { - const EXPAND_BY: Option> = I::EXPAND_BY; - const MERGE_BY: Option> = I::MERGE_BY; -} diff --git a/library/core/src/iter/adapters/zip.rs b/library/core/src/iter/adapters/zip.rs deleted file mode 100644 index 2e885f06b5272..0000000000000 --- a/library/core/src/iter/adapters/zip.rs +++ /dev/null @@ -1,694 +0,0 @@ -use crate::cmp; -use crate::fmt::{self, Debug}; -use crate::iter::{FusedIterator, TrustedFused}; -use crate::iter::{InPlaceIterable, SourceIter, TrustedLen, UncheckedIterator}; -use crate::num::NonZero; - -/// An iterator that iterates two other iterators simultaneously. -/// -/// This `struct` is created by [`zip`] or [`Iterator::zip`]. -/// See their documentation for more. -#[derive(Clone)] -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Zip { - a: A, - b: B, - // index, len and a_len are only used by the specialized version of zip - index: usize, - len: usize, - a_len: usize, -} -impl Zip { - pub(in crate::iter) fn new(a: A, b: B) -> Zip { - ZipImpl::new(a, b) - } - fn super_nth(&mut self, mut n: usize) -> Option<(A::Item, B::Item)> { - while let Some(x) = Iterator::next(self) { - if n == 0 { - return Some(x); - } - n -= 1; - } - None - } -} - -/// Converts the arguments to iterators and zips them. -/// -/// See the documentation of [`Iterator::zip`] for more. -/// -/// # Examples -/// -/// ``` -/// use std::iter::zip; -/// -/// let xs = [1, 2, 3]; -/// let ys = [4, 5, 6]; -/// -/// let mut iter = zip(xs, ys); -/// -/// assert_eq!(iter.next().unwrap(), (1, 4)); -/// assert_eq!(iter.next().unwrap(), (2, 5)); -/// assert_eq!(iter.next().unwrap(), (3, 6)); -/// assert!(iter.next().is_none()); -/// -/// // Nested zips are also possible: -/// let zs = [7, 8, 9]; -/// -/// let mut iter = zip(zip(xs, ys), zs); -/// -/// assert_eq!(iter.next().unwrap(), ((1, 4), 7)); -/// assert_eq!(iter.next().unwrap(), ((2, 5), 8)); -/// assert_eq!(iter.next().unwrap(), ((3, 6), 9)); -/// assert!(iter.next().is_none()); -/// ``` -#[stable(feature = "iter_zip", since = "1.59.0")] -pub fn zip(a: A, b: B) -> Zip -where - A: IntoIterator, - B: IntoIterator, -{ - ZipImpl::new(a.into_iter(), b.into_iter()) -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for Zip -where - A: Iterator, - B: Iterator, -{ - type Item = (A::Item, B::Item); - - #[inline] - fn next(&mut self) -> Option { - ZipImpl::next(self) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - ZipImpl::size_hint(self) - } - - #[inline] - fn nth(&mut self, n: usize) -> Option { - ZipImpl::nth(self, n) - } - - #[inline] - fn fold(self, init: Acc, f: F) -> Acc - where - F: FnMut(Acc, Self::Item) -> Acc, - { - ZipImpl::fold(self, init, f) - } - - #[inline] - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item - where - Self: TrustedRandomAccessNoCoerce, - { - // SAFETY: `ZipImpl::__iterator_get_unchecked` has same safety - // requirements as `Iterator::__iterator_get_unchecked`. - unsafe { ZipImpl::get_unchecked(self, idx) } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DoubleEndedIterator for Zip -where - A: DoubleEndedIterator + ExactSizeIterator, - B: DoubleEndedIterator + ExactSizeIterator, -{ - #[inline] - fn next_back(&mut self) -> Option<(A::Item, B::Item)> { - ZipImpl::next_back(self) - } -} - -// Zip specialization trait -#[doc(hidden)] -trait ZipImpl { - type Item; - fn new(a: A, b: B) -> Self; - fn next(&mut self) -> Option; - fn size_hint(&self) -> (usize, Option); - fn nth(&mut self, n: usize) -> Option; - fn next_back(&mut self) -> Option - where - A: DoubleEndedIterator + ExactSizeIterator, - B: DoubleEndedIterator + ExactSizeIterator; - fn fold(self, init: Acc, f: F) -> Acc - where - F: FnMut(Acc, Self::Item) -> Acc; - // This has the same safety requirements as `Iterator::__iterator_get_unchecked` - unsafe fn get_unchecked(&mut self, idx: usize) -> ::Item - where - Self: Iterator + TrustedRandomAccessNoCoerce; -} - -// Work around limitations of specialization, requiring `default` impls to be repeated -// in intermediary impls. -macro_rules! zip_impl_general_defaults { - () => { - default fn new(a: A, b: B) -> Self { - Zip { - a, - b, - index: 0, // unused - len: 0, // unused - a_len: 0, // unused - } - } - - #[inline] - default fn next(&mut self) -> Option<(A::Item, B::Item)> { - let x = self.a.next()?; - let y = self.b.next()?; - Some((x, y)) - } - - #[inline] - default fn nth(&mut self, n: usize) -> Option { - self.super_nth(n) - } - - #[inline] - default fn next_back(&mut self) -> Option<(A::Item, B::Item)> - where - A: DoubleEndedIterator + ExactSizeIterator, - B: DoubleEndedIterator + ExactSizeIterator, - { - // The function body below only uses `self.a/b.len()` and `self.a/b.next_back()` - // and doesn’t call `next_back` too often, so this implementation is safe in - // the `TrustedRandomAccessNoCoerce` specialization - - let a_sz = self.a.len(); - let b_sz = self.b.len(); - if a_sz != b_sz { - // Adjust a, b to equal length - if a_sz > b_sz { - for _ in 0..a_sz - b_sz { - self.a.next_back(); - } - } else { - for _ in 0..b_sz - a_sz { - self.b.next_back(); - } - } - } - match (self.a.next_back(), self.b.next_back()) { - (Some(x), Some(y)) => Some((x, y)), - (None, None) => None, - _ => unreachable!(), - } - } - }; -} - -// General Zip impl -#[doc(hidden)] -impl ZipImpl for Zip -where - A: Iterator, - B: Iterator, -{ - type Item = (A::Item, B::Item); - - zip_impl_general_defaults! {} - - #[inline] - default fn size_hint(&self) -> (usize, Option) { - let (a_lower, a_upper) = self.a.size_hint(); - let (b_lower, b_upper) = self.b.size_hint(); - - let lower = cmp::min(a_lower, b_lower); - - let upper = match (a_upper, b_upper) { - (Some(x), Some(y)) => Some(cmp::min(x, y)), - (Some(x), None) => Some(x), - (None, Some(y)) => Some(y), - (None, None) => None, - }; - - (lower, upper) - } - - default unsafe fn get_unchecked(&mut self, _idx: usize) -> ::Item - where - Self: TrustedRandomAccessNoCoerce, - { - unreachable!("Always specialized"); - } - - #[inline] - default fn fold(self, init: Acc, f: F) -> Acc - where - F: FnMut(Acc, Self::Item) -> Acc, - { - SpecFold::spec_fold(self, init, f) - } -} - -#[doc(hidden)] -impl ZipImpl for Zip -where - A: TrustedRandomAccessNoCoerce + Iterator, - B: TrustedRandomAccessNoCoerce + Iterator, -{ - zip_impl_general_defaults! {} - - #[inline] - default fn size_hint(&self) -> (usize, Option) { - let size = cmp::min(self.a.size(), self.b.size()); - (size, Some(size)) - } - - #[inline] - unsafe fn get_unchecked(&mut self, idx: usize) -> ::Item { - let idx = self.index + idx; - // SAFETY: the caller must uphold the contract for - // `Iterator::__iterator_get_unchecked`. - unsafe { (self.a.__iterator_get_unchecked(idx), self.b.__iterator_get_unchecked(idx)) } - } - - #[inline] - fn fold(mut self, init: Acc, mut f: F) -> Acc - where - F: FnMut(Acc, Self::Item) -> Acc, - { - let mut accum = init; - let len = ZipImpl::size_hint(&self).0; - for i in 0..len { - // SAFETY: since Self: TrustedRandomAccessNoCoerce we can trust the size-hint to - // calculate the length and then use that to do unchecked iteration. - // fold consumes the iterator so we don't need to fixup any state. - unsafe { - accum = f(accum, self.get_unchecked(i)); - } - } - accum - } -} - -#[doc(hidden)] -impl ZipImpl for Zip -where - A: TrustedRandomAccess + Iterator, - B: TrustedRandomAccess + Iterator, -{ - fn new(a: A, b: B) -> Self { - let a_len = a.size(); - let len = cmp::min(a_len, b.size()); - Zip { a, b, index: 0, len, a_len } - } - - #[inline] - fn next(&mut self) -> Option<(A::Item, B::Item)> { - if self.index < self.len { - let i = self.index; - // since get_unchecked executes code which can panic we increment the counters beforehand - // so that the same index won't be accessed twice, as required by TrustedRandomAccess - self.index += 1; - // SAFETY: `i` is smaller than `self.len`, thus smaller than `self.a.len()` and `self.b.len()` - unsafe { - Some((self.a.__iterator_get_unchecked(i), self.b.__iterator_get_unchecked(i))) - } - } else if A::MAY_HAVE_SIDE_EFFECT && self.index < self.a_len { - let i = self.index; - // as above, increment before executing code that may panic - self.index += 1; - self.len += 1; - // match the base implementation's potential side effects - // SAFETY: we just checked that `i` < `self.a.len()` - unsafe { - self.a.__iterator_get_unchecked(i); - } - None - } else { - None - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let len = self.len - self.index; - (len, Some(len)) - } - - #[inline] - fn nth(&mut self, n: usize) -> Option { - let delta = cmp::min(n, self.len - self.index); - let end = self.index + delta; - while self.index < end { - let i = self.index; - // since get_unchecked executes code which can panic we increment the counters beforehand - // so that the same index won't be accessed twice, as required by TrustedRandomAccess - self.index += 1; - if A::MAY_HAVE_SIDE_EFFECT { - // SAFETY: the usage of `cmp::min` to calculate `delta` - // ensures that `end` is smaller than or equal to `self.len`, - // so `i` is also smaller than `self.len`. - unsafe { - self.a.__iterator_get_unchecked(i); - } - } - if B::MAY_HAVE_SIDE_EFFECT { - // SAFETY: same as above. - unsafe { - self.b.__iterator_get_unchecked(i); - } - } - } - - self.super_nth(n - delta) - } - - #[inline] - fn next_back(&mut self) -> Option<(A::Item, B::Item)> - where - A: DoubleEndedIterator + ExactSizeIterator, - B: DoubleEndedIterator + ExactSizeIterator, - { - if A::MAY_HAVE_SIDE_EFFECT || B::MAY_HAVE_SIDE_EFFECT { - let sz_a = self.a.size(); - let sz_b = self.b.size(); - // Adjust a, b to equal length, make sure that only the first call - // of `next_back` does this, otherwise we will break the restriction - // on calls to `self.next_back()` after calling `get_unchecked()`. - if sz_a != sz_b { - let sz_a = self.a.size(); - if A::MAY_HAVE_SIDE_EFFECT && sz_a > self.len { - for _ in 0..sz_a - self.len { - // since next_back() may panic we increment the counters beforehand - // to keep Zip's state in sync with the underlying iterator source - self.a_len -= 1; - self.a.next_back(); - } - debug_assert_eq!(self.a_len, self.len); - } - let sz_b = self.b.size(); - if B::MAY_HAVE_SIDE_EFFECT && sz_b > self.len { - for _ in 0..sz_b - self.len { - self.b.next_back(); - } - } - } - } - if self.index < self.len { - // since get_unchecked executes code which can panic we increment the counters beforehand - // so that the same index won't be accessed twice, as required by TrustedRandomAccess - self.len -= 1; - self.a_len -= 1; - let i = self.len; - // SAFETY: `i` is smaller than the previous value of `self.len`, - // which is also smaller than or equal to `self.a.len()` and `self.b.len()` - unsafe { - Some((self.a.__iterator_get_unchecked(i), self.b.__iterator_get_unchecked(i))) - } - } else { - None - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Zip -where - A: ExactSizeIterator, - B: ExactSizeIterator, -{ -} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl TrustedRandomAccess for Zip -where - A: TrustedRandomAccess, - B: TrustedRandomAccess, -{ -} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl TrustedRandomAccessNoCoerce for Zip -where - A: TrustedRandomAccessNoCoerce, - B: TrustedRandomAccessNoCoerce, -{ - const MAY_HAVE_SIDE_EFFECT: bool = A::MAY_HAVE_SIDE_EFFECT || B::MAY_HAVE_SIDE_EFFECT; -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Zip -where - A: FusedIterator, - B: FusedIterator, -{ -} - -#[unstable(issue = "none", feature = "trusted_fused")] -unsafe impl TrustedFused for Zip -where - A: TrustedFused, - B: TrustedFused, -{ -} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for Zip -where - A: TrustedLen, - B: TrustedLen, -{ -} - -impl UncheckedIterator for Zip -where - A: UncheckedIterator, - B: UncheckedIterator, -{ -} - -// Arbitrarily selects the left side of the zip iteration as extractable "source" -// it would require negative trait bounds to be able to try both -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl SourceIter for Zip -where - A: SourceIter, -{ - type Source = A::Source; - - #[inline] - unsafe fn as_inner(&mut self) -> &mut A::Source { - // SAFETY: unsafe function forwarding to unsafe function with the same requirements - unsafe { SourceIter::as_inner(&mut self.a) } - } -} - -// Since SourceIter forwards the left hand side we do the same here -#[unstable(issue = "none", feature = "inplace_iteration")] -unsafe impl InPlaceIterable for Zip { - const EXPAND_BY: Option> = A::EXPAND_BY; - const MERGE_BY: Option> = A::MERGE_BY; -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Debug for Zip { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - ZipFmt::fmt(self, f) - } -} - -trait ZipFmt { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result; -} - -impl ZipFmt for Zip { - default fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Zip").field("a", &self.a).field("b", &self.b).finish() - } -} - -impl ZipFmt - for Zip -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - // It's *not safe* to call fmt on the contained iterators, since once - // we start iterating they're in strange, potentially unsafe, states. - f.debug_struct("Zip").finish() - } -} - -/// An iterator whose items are random-accessible efficiently -/// -/// # Safety -/// -/// The iterator's `size_hint` must be exact and cheap to call. -/// -/// `TrustedRandomAccessNoCoerce::size` may not be overridden. -/// -/// All subtypes and all supertypes of `Self` must also implement `TrustedRandomAccess`. -/// In particular, this means that types with non-invariant parameters usually can not have -/// an impl for `TrustedRandomAccess` that depends on any trait bounds on such parameters, except -/// for bounds that come from the respective struct/enum definition itself, or bounds involving -/// traits that themselves come with a guarantee similar to this one. -/// -/// If `Self: ExactSizeIterator` then `self.len()` must always produce results consistent -/// with `self.size()`. -/// -/// If `Self: Iterator`, then `::__iterator_get_unchecked(&mut self, idx)` -/// must be safe to call provided the following conditions are met. -/// -/// 1. `0 <= idx` and `idx < self.size()`. -/// 2. If `Self: !Clone`, then `self.__iterator_get_unchecked(idx)` is never called with the same -/// index on `self` more than once. -/// 3. After `self.__iterator_get_unchecked(idx)` has been called, then `self.next_back()` will -/// only be called at most `self.size() - idx - 1` times. If `Self: Clone` and `self` is cloned, -/// then this number is calculated for `self` and its clone individually, -/// but `self.next_back()` calls that happened before the cloning count for both `self` and the clone. -/// 4. After `self.__iterator_get_unchecked(idx)` has been called, then only the following methods -/// will be called on `self` or on any new clones of `self`: -/// * `std::clone::Clone::clone` -/// * `std::iter::Iterator::size_hint` -/// * `std::iter::DoubleEndedIterator::next_back` -/// * `std::iter::ExactSizeIterator::len` -/// * `std::iter::Iterator::__iterator_get_unchecked` -/// * `std::iter::TrustedRandomAccessNoCoerce::size` -/// 5. If `T` is a subtype of `Self`, then `self` is allowed to be coerced -/// to `T`. If `self` is coerced to `T` after `self.__iterator_get_unchecked(idx)` has already -/// been called, then no methods except for the ones listed under 4. are allowed to be called -/// on the resulting value of type `T`, either. Multiple such coercion steps are allowed. -/// Regarding 2. and 3., the number of times `__iterator_get_unchecked(idx)` or `next_back()` is -/// called on `self` and the resulting value of type `T` (and on further coercion results with -/// sub-subtypes) are added together and their sums must not exceed the specified bounds. -/// -/// Further, given that these conditions are met, it must guarantee that: -/// -/// * It does not change the value returned from `size_hint` -/// * It must be safe to call the methods listed above on `self` after calling -/// `self.__iterator_get_unchecked(idx)`, assuming that the required traits are implemented. -/// * It must also be safe to drop `self` after calling `self.__iterator_get_unchecked(idx)`. -/// * If `T` is a subtype of `Self`, then it must be safe to coerce `self` to `T`. -// -// FIXME: Clarify interaction with SourceIter/InPlaceIterable. Calling `SourceIter::as_inner` -// after `__iterator_get_unchecked` is supposed to be allowed. -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -#[rustc_specialization_trait] -pub unsafe trait TrustedRandomAccess: TrustedRandomAccessNoCoerce {} - -/// Like [`TrustedRandomAccess`] but without any of the requirements / guarantees around -/// coercions to subtypes after `__iterator_get_unchecked` (they aren’t allowed here!), and -/// without the requirement that subtypes / supertypes implement `TrustedRandomAccessNoCoerce`. -/// -/// This trait was created in PR #85874 to fix soundness issue #85873 without performance regressions. -/// It is subject to change as we might want to build a more generally useful (for performance -/// optimizations) and more sophisticated trait or trait hierarchy that replaces or extends -/// [`TrustedRandomAccess`] and `TrustedRandomAccessNoCoerce`. -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -#[rustc_specialization_trait] -pub unsafe trait TrustedRandomAccessNoCoerce: Sized { - // Convenience method. - fn size(&self) -> usize - where - Self: Iterator, - { - self.size_hint().0 - } - /// `true` if getting an iterator element may have side effects. - /// Remember to take inner iterators into account. - const MAY_HAVE_SIDE_EFFECT: bool; -} - -/// Like `Iterator::__iterator_get_unchecked`, but doesn't require the compiler to -/// know that `U: TrustedRandomAccess`. -/// -/// ## Safety -/// -/// Same requirements calling `get_unchecked` directly. -#[doc(hidden)] -#[inline] -pub(in crate::iter::adapters) unsafe fn try_get_unchecked(it: &mut I, idx: usize) -> I::Item -where - I: Iterator, -{ - // SAFETY: the caller must uphold the contract for - // `Iterator::__iterator_get_unchecked`. - unsafe { it.try_get_unchecked(idx) } -} - -unsafe trait SpecTrustedRandomAccess: Iterator { - /// If `Self: TrustedRandomAccess`, it must be safe to call - /// `Iterator::__iterator_get_unchecked(self, index)`. - unsafe fn try_get_unchecked(&mut self, index: usize) -> Self::Item; -} - -unsafe impl SpecTrustedRandomAccess for I { - default unsafe fn try_get_unchecked(&mut self, _: usize) -> Self::Item { - panic!("Should only be called on TrustedRandomAccess iterators"); - } -} - -unsafe impl SpecTrustedRandomAccess for I { - #[inline] - unsafe fn try_get_unchecked(&mut self, index: usize) -> Self::Item { - // SAFETY: the caller must uphold the contract for - // `Iterator::__iterator_get_unchecked`. - unsafe { self.__iterator_get_unchecked(index) } - } -} - -trait SpecFold: Iterator { - fn spec_fold(self, init: B, f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B; -} - -impl SpecFold for Zip { - // Adapted from default impl from the Iterator trait - #[inline] - default fn spec_fold(mut self, init: Acc, mut f: F) -> Acc - where - F: FnMut(Acc, Self::Item) -> Acc, - { - let mut accum = init; - while let Some(x) = ZipImpl::next(&mut self) { - accum = f(accum, x); - } - accum - } -} - -impl SpecFold for Zip { - #[inline] - fn spec_fold(mut self, init: Acc, mut f: F) -> Acc - where - F: FnMut(Acc, Self::Item) -> Acc, - { - let mut accum = init; - loop { - let (upper, more) = if let Some(upper) = ZipImpl::size_hint(&self).1 { - (upper, false) - } else { - // Per TrustedLen contract a None upper bound means more than usize::MAX items - (usize::MAX, true) - }; - - for _ in 0..upper { - let pair = - // SAFETY: TrustedLen guarantees that at least `upper` many items are available - // therefore we know they can't be None - unsafe { (self.a.next().unwrap_unchecked(), self.b.next().unwrap_unchecked()) }; - accum = f(accum, pair); - } - - if !more { - break; - } - } - accum - } -} diff --git a/library/core/src/iter/mod.rs b/library/core/src/iter/mod.rs deleted file mode 100644 index 44fef3e145b78..0000000000000 --- a/library/core/src/iter/mod.rs +++ /dev/null @@ -1,469 +0,0 @@ -//! Composable external iteration. -//! -//! If you've found yourself with a collection of some kind, and needed to -//! perform an operation on the elements of said collection, you'll quickly run -//! into 'iterators'. Iterators are heavily used in idiomatic Rust code, so -//! it's worth becoming familiar with them. -//! -//! Before explaining more, let's talk about how this module is structured: -//! -//! # Organization -//! -//! This module is largely organized by type: -//! -//! * [Traits] are the core portion: these traits define what kind of iterators -//! exist and what you can do with them. The methods of these traits are worth -//! putting some extra study time into. -//! * [Functions] provide some helpful ways to create some basic iterators. -//! * [Structs] are often the return types of the various methods on this -//! module's traits. You'll usually want to look at the method that creates -//! the `struct`, rather than the `struct` itself. For more detail about why, -//! see '[Implementing Iterator](#implementing-iterator)'. -//! -//! [Traits]: #traits -//! [Functions]: #functions -//! [Structs]: #structs -//! -//! That's it! Let's dig into iterators. -//! -//! # Iterator -//! -//! The heart and soul of this module is the [`Iterator`] trait. The core of -//! [`Iterator`] looks like this: -//! -//! ``` -//! trait Iterator { -//! type Item; -//! fn next(&mut self) -> Option; -//! } -//! ``` -//! -//! An iterator has a method, [`next`], which when called, returns an -//! [Option]\. Calling [`next`] will return [`Some(Item)`] as long as there -//! are elements, and once they've all been exhausted, will return `None` to -//! indicate that iteration is finished. Individual iterators may choose to -//! resume iteration, and so calling [`next`] again may or may not eventually -//! start returning [`Some(Item)`] again at some point (for example, see [`TryIter`]). -//! -//! [`Iterator`]'s full definition includes a number of other methods as well, -//! but they are default methods, built on top of [`next`], and so you get -//! them for free. -//! -//! Iterators are also composable, and it's common to chain them together to do -//! more complex forms of processing. See the [Adapters](#adapters) section -//! below for more details. -//! -//! [`Some(Item)`]: Some -//! [`next`]: Iterator::next -//! [`TryIter`]: ../../std/sync/mpsc/struct.TryIter.html -//! -//! # The three forms of iteration -//! -//! There are three common methods which can create iterators from a collection: -//! -//! * `iter()`, which iterates over `&T`. -//! * `iter_mut()`, which iterates over `&mut T`. -//! * `into_iter()`, which iterates over `T`. -//! -//! Various things in the standard library may implement one or more of the -//! three, where appropriate. -//! -//! # Implementing Iterator -//! -//! Creating an iterator of your own involves two steps: creating a `struct` to -//! hold the iterator's state, and then implementing [`Iterator`] for that `struct`. -//! This is why there are so many `struct`s in this module: there is one for -//! each iterator and iterator adapter. -//! -//! Let's make an iterator named `Counter` which counts from `1` to `5`: -//! -//! ``` -//! // First, the struct: -//! -//! /// An iterator which counts from one to five -//! struct Counter { -//! count: usize, -//! } -//! -//! // we want our count to start at one, so let's add a new() method to help. -//! // This isn't strictly necessary, but is convenient. Note that we start -//! // `count` at zero, we'll see why in `next()`'s implementation below. -//! impl Counter { -//! fn new() -> Counter { -//! Counter { count: 0 } -//! } -//! } -//! -//! // Then, we implement `Iterator` for our `Counter`: -//! -//! impl Iterator for Counter { -//! // we will be counting with usize -//! type Item = usize; -//! -//! // next() is the only required method -//! fn next(&mut self) -> Option { -//! // Increment our count. This is why we started at zero. -//! self.count += 1; -//! -//! // Check to see if we've finished counting or not. -//! if self.count < 6 { -//! Some(self.count) -//! } else { -//! None -//! } -//! } -//! } -//! -//! // And now we can use it! -//! -//! let mut counter = Counter::new(); -//! -//! assert_eq!(counter.next(), Some(1)); -//! assert_eq!(counter.next(), Some(2)); -//! assert_eq!(counter.next(), Some(3)); -//! assert_eq!(counter.next(), Some(4)); -//! assert_eq!(counter.next(), Some(5)); -//! assert_eq!(counter.next(), None); -//! ``` -//! -//! Calling [`next`] this way gets repetitive. Rust has a construct which can -//! call [`next`] on your iterator, until it reaches `None`. Let's go over that -//! next. -//! -//! Also note that `Iterator` provides a default implementation of methods such as `nth` and `fold` -//! which call `next` internally. However, it is also possible to write a custom implementation of -//! methods like `nth` and `fold` if an iterator can compute them more efficiently without calling -//! `next`. -//! -//! # `for` loops and `IntoIterator` -//! -//! Rust's `for` loop syntax is actually sugar for iterators. Here's a basic -//! example of `for`: -//! -//! ``` -//! let values = vec![1, 2, 3, 4, 5]; -//! -//! for x in values { -//! println!("{x}"); -//! } -//! ``` -//! -//! This will print the numbers one through five, each on their own line. But -//! you'll notice something here: we never called anything on our vector to -//! produce an iterator. What gives? -//! -//! There's a trait in the standard library for converting something into an -//! iterator: [`IntoIterator`]. This trait has one method, [`into_iter`], -//! which converts the thing implementing [`IntoIterator`] into an iterator. -//! Let's take a look at that `for` loop again, and what the compiler converts -//! it into: -//! -//! [`into_iter`]: IntoIterator::into_iter -//! -//! ``` -//! let values = vec![1, 2, 3, 4, 5]; -//! -//! for x in values { -//! println!("{x}"); -//! } -//! ``` -//! -//! Rust de-sugars this into: -//! -//! ``` -//! let values = vec![1, 2, 3, 4, 5]; -//! { -//! let result = match IntoIterator::into_iter(values) { -//! mut iter => loop { -//! let next; -//! match iter.next() { -//! Some(val) => next = val, -//! None => break, -//! }; -//! let x = next; -//! let () = { println!("{x}"); }; -//! }, -//! }; -//! result -//! } -//! ``` -//! -//! First, we call `into_iter()` on the value. Then, we match on the iterator -//! that returns, calling [`next`] over and over until we see a `None`. At -//! that point, we `break` out of the loop, and we're done iterating. -//! -//! There's one more subtle bit here: the standard library contains an -//! interesting implementation of [`IntoIterator`]: -//! -//! ```ignore (only-for-syntax-highlight) -//! impl IntoIterator for I -//! ``` -//! -//! In other words, all [`Iterator`]s implement [`IntoIterator`], by just -//! returning themselves. This means two things: -//! -//! 1. If you're writing an [`Iterator`], you can use it with a `for` loop. -//! 2. If you're creating a collection, implementing [`IntoIterator`] for it -//! will allow your collection to be used with the `for` loop. -//! -//! # Iterating by reference -//! -//! Since [`into_iter()`] takes `self` by value, using a `for` loop to iterate -//! over a collection consumes that collection. Often, you may want to iterate -//! over a collection without consuming it. Many collections offer methods that -//! provide iterators over references, conventionally called `iter()` and -//! `iter_mut()` respectively: -//! -//! ``` -//! let mut values = vec![41]; -//! for x in values.iter_mut() { -//! *x += 1; -//! } -//! for x in values.iter() { -//! assert_eq!(*x, 42); -//! } -//! assert_eq!(values.len(), 1); // `values` is still owned by this function. -//! ``` -//! -//! If a collection type `C` provides `iter()`, it usually also implements -//! `IntoIterator` for `&C`, with an implementation that just calls `iter()`. -//! Likewise, a collection `C` that provides `iter_mut()` generally implements -//! `IntoIterator` for `&mut C` by delegating to `iter_mut()`. This enables a -//! convenient shorthand: -//! -//! ``` -//! let mut values = vec![41]; -//! for x in &mut values { // same as `values.iter_mut()` -//! *x += 1; -//! } -//! for x in &values { // same as `values.iter()` -//! assert_eq!(*x, 42); -//! } -//! assert_eq!(values.len(), 1); -//! ``` -//! -//! While many collections offer `iter()`, not all offer `iter_mut()`. For -//! example, mutating the keys of a [`HashSet`] could put the collection -//! into an inconsistent state if the key hashes change, so this collection -//! only offers `iter()`. -//! -//! [`into_iter()`]: IntoIterator::into_iter -//! [`HashSet`]: ../../std/collections/struct.HashSet.html -//! -//! # Adapters -//! -//! Functions which take an [`Iterator`] and return another [`Iterator`] are -//! often called 'iterator adapters', as they're a form of the 'adapter -//! pattern'. -//! -//! Common iterator adapters include [`map`], [`take`], and [`filter`]. -//! For more, see their documentation. -//! -//! If an iterator adapter panics, the iterator will be in an unspecified (but -//! memory safe) state. This state is also not guaranteed to stay the same -//! across versions of Rust, so you should avoid relying on the exact values -//! returned by an iterator which panicked. -//! -//! [`map`]: Iterator::map -//! [`take`]: Iterator::take -//! [`filter`]: Iterator::filter -//! -//! # Laziness -//! -//! Iterators (and iterator [adapters](#adapters)) are *lazy*. This means that -//! just creating an iterator doesn't _do_ a whole lot. Nothing really happens -//! until you call [`next`]. This is sometimes a source of confusion when -//! creating an iterator solely for its side effects. For example, the [`map`] -//! method calls a closure on each element it iterates over: -//! -//! ``` -//! # #![allow(unused_must_use)] -//! # #![allow(map_unit_fn)] -//! let v = vec![1, 2, 3, 4, 5]; -//! v.iter().map(|x| println!("{x}")); -//! ``` -//! -//! This will not print any values, as we only created an iterator, rather than -//! using it. The compiler will warn us about this kind of behavior: -//! -//! ```text -//! warning: unused result that must be used: iterators are lazy and -//! do nothing unless consumed -//! ``` -//! -//! The idiomatic way to write a [`map`] for its side effects is to use a -//! `for` loop or call the [`for_each`] method: -//! -//! ``` -//! let v = vec![1, 2, 3, 4, 5]; -//! -//! v.iter().for_each(|x| println!("{x}")); -//! // or -//! for x in &v { -//! println!("{x}"); -//! } -//! ``` -//! -//! [`map`]: Iterator::map -//! [`for_each`]: Iterator::for_each -//! -//! Another common way to evaluate an iterator is to use the [`collect`] -//! method to produce a new collection. -//! -//! [`collect`]: Iterator::collect -//! -//! # Infinity -//! -//! Iterators do not have to be finite. As an example, an open-ended range is -//! an infinite iterator: -//! -//! ``` -//! let numbers = 0..; -//! ``` -//! -//! It is common to use the [`take`] iterator adapter to turn an infinite -//! iterator into a finite one: -//! -//! ``` -//! let numbers = 0..; -//! let five_numbers = numbers.take(5); -//! -//! for number in five_numbers { -//! println!("{number}"); -//! } -//! ``` -//! -//! This will print the numbers `0` through `4`, each on their own line. -//! -//! Bear in mind that methods on infinite iterators, even those for which a -//! result can be determined mathematically in finite time, might not terminate. -//! Specifically, methods such as [`min`], which in the general case require -//! traversing every element in the iterator, are likely not to return -//! successfully for any infinite iterators. -//! -//! ```no_run -//! let ones = std::iter::repeat(1); -//! let least = ones.min().unwrap(); // Oh no! An infinite loop! -//! // `ones.min()` causes an infinite loop, so we won't reach this point! -//! println!("The smallest number one is {least}."); -//! ``` -//! -//! [`take`]: Iterator::take -//! [`min`]: Iterator::min - -#![stable(feature = "rust1", since = "1.0.0")] - -// This needs to be up here in order to be usable in the child modules -macro_rules! impl_fold_via_try_fold { - (fold -> try_fold) => { - impl_fold_via_try_fold! { @internal fold -> try_fold } - }; - (rfold -> try_rfold) => { - impl_fold_via_try_fold! { @internal rfold -> try_rfold } - }; - (spec_fold -> spec_try_fold) => { - impl_fold_via_try_fold! { @internal spec_fold -> spec_try_fold } - }; - (spec_rfold -> spec_try_rfold) => { - impl_fold_via_try_fold! { @internal spec_rfold -> spec_try_rfold } - }; - (@internal $fold:ident -> $try_fold:ident) => { - #[inline] - fn $fold(mut self, init: AAA, fold: FFF) -> AAA - where - FFF: FnMut(AAA, Self::Item) -> AAA, - { - use crate::ops::NeverShortCircuit; - - self.$try_fold(init, NeverShortCircuit::wrap_mut_2(fold)).0 - } - }; -} - -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::traits::Iterator; - -#[unstable( - feature = "step_trait", - reason = "likely to be replaced by finer-grained traits", - issue = "42168" -)] -pub use self::range::Step; - -#[unstable( - feature = "iter_from_coroutine", - issue = "43122", - reason = "coroutines are unstable" -)] -pub use self::sources::from_coroutine; -#[stable(feature = "iter_empty", since = "1.2.0")] -pub use self::sources::{empty, Empty}; -#[stable(feature = "iter_from_fn", since = "1.34.0")] -pub use self::sources::{from_fn, FromFn}; -#[stable(feature = "iter_once", since = "1.2.0")] -pub use self::sources::{once, Once}; -#[stable(feature = "iter_once_with", since = "1.43.0")] -pub use self::sources::{once_with, OnceWith}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::sources::{repeat, Repeat}; -#[unstable(feature = "iter_repeat_n", issue = "104434")] -pub use self::sources::{repeat_n, RepeatN}; -#[stable(feature = "iterator_repeat_with", since = "1.28.0")] -pub use self::sources::{repeat_with, RepeatWith}; -#[stable(feature = "iter_successors", since = "1.34.0")] -pub use self::sources::{successors, Successors}; - -#[stable(feature = "fused", since = "1.26.0")] -pub use self::traits::FusedIterator; -#[unstable(issue = "none", feature = "inplace_iteration")] -pub use self::traits::InPlaceIterable; -#[unstable(issue = "none", feature = "trusted_fused")] -pub use self::traits::TrustedFused; -#[unstable(feature = "trusted_len", issue = "37572")] -pub use self::traits::TrustedLen; -#[unstable(feature = "trusted_step", issue = "85731")] -pub use self::traits::TrustedStep; -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::traits::{ - DoubleEndedIterator, ExactSizeIterator, Extend, FromIterator, IntoIterator, Product, Sum, -}; - -#[stable(feature = "iter_zip", since = "1.59.0")] -pub use self::adapters::zip; -#[unstable(feature = "iter_array_chunks", reason = "recently added", issue = "100450")] -pub use self::adapters::ArrayChunks; -#[unstable(feature = "std_internals", issue = "none")] -pub use self::adapters::ByRefSized; -#[stable(feature = "iter_cloned", since = "1.1.0")] -pub use self::adapters::Cloned; -#[stable(feature = "iter_copied", since = "1.36.0")] -pub use self::adapters::Copied; -#[stable(feature = "iterator_flatten", since = "1.29.0")] -pub use self::adapters::Flatten; -#[stable(feature = "iter_map_while", since = "1.57.0")] -pub use self::adapters::MapWhile; -#[unstable(feature = "iter_map_windows", reason = "recently added", issue = "87155")] -pub use self::adapters::MapWindows; -#[unstable(feature = "inplace_iteration", issue = "none")] -pub use self::adapters::SourceIter; -#[stable(feature = "iterator_step_by", since = "1.28.0")] -pub use self::adapters::StepBy; -#[unstable(feature = "trusted_random_access", issue = "none")] -pub use self::adapters::TrustedRandomAccess; -#[unstable(feature = "trusted_random_access", issue = "none")] -pub use self::adapters::TrustedRandomAccessNoCoerce; -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::adapters::{ - Chain, Cycle, Enumerate, Filter, FilterMap, FlatMap, Fuse, Inspect, Map, Peekable, Rev, Scan, - Skip, SkipWhile, Take, TakeWhile, Zip, -}; -#[unstable(feature = "iter_intersperse", reason = "recently added", issue = "79524")] -pub use self::adapters::{Intersperse, IntersperseWith}; - -pub(crate) use self::adapters::try_process; -pub(crate) use self::traits::UncheckedIterator; - -mod adapters; -mod range; -mod sources; -mod traits; diff --git a/library/core/src/iter/range.rs b/library/core/src/iter/range.rs deleted file mode 100644 index 644a169294396..0000000000000 --- a/library/core/src/iter/range.rs +++ /dev/null @@ -1,1394 +0,0 @@ -use crate::ascii::Char as AsciiChar; -use crate::mem; -use crate::net::{Ipv4Addr, Ipv6Addr}; -use crate::num::NonZero; -use crate::ops::{self, Try}; - -use super::{ - FusedIterator, TrustedLen, TrustedRandomAccess, TrustedRandomAccessNoCoerce, TrustedStep, -}; - -// Safety: All invariants are upheld. -macro_rules! unsafe_impl_trusted_step { - ($($type:ty)*) => {$( - #[unstable(feature = "trusted_step", issue = "85731")] - unsafe impl TrustedStep for $type {} - )*}; -} -unsafe_impl_trusted_step![AsciiChar char i8 i16 i32 i64 i128 isize u8 u16 u32 u64 u128 usize Ipv4Addr Ipv6Addr]; - -/// Objects that have a notion of *successor* and *predecessor* operations. -/// -/// The *successor* operation moves towards values that compare greater. -/// The *predecessor* operation moves towards values that compare lesser. -#[unstable(feature = "step_trait", issue = "42168")] -pub trait Step: Clone + PartialOrd + Sized { - /// Returns the number of *successor* steps required to get from `start` to `end`. - /// - /// Returns `None` if the number of steps would overflow `usize` - /// (or is infinite, or if `end` would never be reached). - /// - /// # Invariants - /// - /// For any `a`, `b`, and `n`: - /// - /// * `steps_between(&a, &b) == Some(n)` if and only if `Step::forward_checked(&a, n) == Some(b)` - /// * `steps_between(&a, &b) == Some(n)` if and only if `Step::backward_checked(&b, n) == Some(a)` - /// * `steps_between(&a, &b) == Some(n)` only if `a <= b` - /// * Corollary: `steps_between(&a, &b) == Some(0)` if and only if `a == b` - /// * Note that `a <= b` does _not_ imply `steps_between(&a, &b) != None`; - /// this is the case when it would require more than `usize::MAX` steps to get to `b` - /// * `steps_between(&a, &b) == None` if `a > b` - fn steps_between(start: &Self, end: &Self) -> Option; - - /// Returns the value that would be obtained by taking the *successor* - /// of `self` `count` times. - /// - /// If this would overflow the range of values supported by `Self`, returns `None`. - /// - /// # Invariants - /// - /// For any `a`, `n`, and `m`: - /// - /// * `Step::forward_checked(a, n).and_then(|x| Step::forward_checked(x, m)) == Step::forward_checked(a, m).and_then(|x| Step::forward_checked(x, n))` - /// * `Step::forward_checked(a, n).and_then(|x| Step::forward_checked(x, m)) == try { Step::forward_checked(a, n.checked_add(m)) }` - /// - /// For any `a` and `n`: - /// - /// * `Step::forward_checked(a, n) == (0..n).try_fold(a, |x, _| Step::forward_checked(&x, 1))` - /// * Corollary: `Step::forward_checked(a, 0) == Some(a)` - fn forward_checked(start: Self, count: usize) -> Option; - - /// Returns the value that would be obtained by taking the *successor* - /// of `self` `count` times. - /// - /// If this would overflow the range of values supported by `Self`, - /// this function is allowed to panic, wrap, or saturate. - /// The suggested behavior is to panic when debug assertions are enabled, - /// and to wrap or saturate otherwise. - /// - /// Unsafe code should not rely on the correctness of behavior after overflow. - /// - /// # Invariants - /// - /// For any `a`, `n`, and `m`, where no overflow occurs: - /// - /// * `Step::forward(Step::forward(a, n), m) == Step::forward(a, n + m)` - /// - /// For any `a` and `n`, where no overflow occurs: - /// - /// * `Step::forward_checked(a, n) == Some(Step::forward(a, n))` - /// * `Step::forward(a, n) == (0..n).fold(a, |x, _| Step::forward(x, 1))` - /// * Corollary: `Step::forward(a, 0) == a` - /// * `Step::forward(a, n) >= a` - /// * `Step::backward(Step::forward(a, n), n) == a` - fn forward(start: Self, count: usize) -> Self { - Step::forward_checked(start, count).expect("overflow in `Step::forward`") - } - - /// Returns the value that would be obtained by taking the *successor* - /// of `self` `count` times. - /// - /// # Safety - /// - /// It is undefined behavior for this operation to overflow the - /// range of values supported by `Self`. If you cannot guarantee that this - /// will not overflow, use `forward` or `forward_checked` instead. - /// - /// # Invariants - /// - /// For any `a`: - /// - /// * if there exists `b` such that `b > a`, it is safe to call `Step::forward_unchecked(a, 1)` - /// * if there exists `b`, `n` such that `steps_between(&a, &b) == Some(n)`, - /// it is safe to call `Step::forward_unchecked(a, m)` for any `m <= n`. - /// * Corollary: `Step::forward_unchecked(a, 0)` is always safe. - /// - /// For any `a` and `n`, where no overflow occurs: - /// - /// * `Step::forward_unchecked(a, n)` is equivalent to `Step::forward(a, n)` - unsafe fn forward_unchecked(start: Self, count: usize) -> Self { - Step::forward(start, count) - } - - /// Returns the value that would be obtained by taking the *predecessor* - /// of `self` `count` times. - /// - /// If this would overflow the range of values supported by `Self`, returns `None`. - /// - /// # Invariants - /// - /// For any `a`, `n`, and `m`: - /// - /// * `Step::backward_checked(a, n).and_then(|x| Step::backward_checked(x, m)) == n.checked_add(m).and_then(|x| Step::backward_checked(a, x))` - /// * `Step::backward_checked(a, n).and_then(|x| Step::backward_checked(x, m)) == try { Step::backward_checked(a, n.checked_add(m)?) }` - /// - /// For any `a` and `n`: - /// - /// * `Step::backward_checked(a, n) == (0..n).try_fold(a, |x, _| Step::backward_checked(x, 1))` - /// * Corollary: `Step::backward_checked(a, 0) == Some(a)` - fn backward_checked(start: Self, count: usize) -> Option; - - /// Returns the value that would be obtained by taking the *predecessor* - /// of `self` `count` times. - /// - /// If this would overflow the range of values supported by `Self`, - /// this function is allowed to panic, wrap, or saturate. - /// The suggested behavior is to panic when debug assertions are enabled, - /// and to wrap or saturate otherwise. - /// - /// Unsafe code should not rely on the correctness of behavior after overflow. - /// - /// # Invariants - /// - /// For any `a`, `n`, and `m`, where no overflow occurs: - /// - /// * `Step::backward(Step::backward(a, n), m) == Step::backward(a, n + m)` - /// - /// For any `a` and `n`, where no overflow occurs: - /// - /// * `Step::backward_checked(a, n) == Some(Step::backward(a, n))` - /// * `Step::backward(a, n) == (0..n).fold(a, |x, _| Step::backward(x, 1))` - /// * Corollary: `Step::backward(a, 0) == a` - /// * `Step::backward(a, n) <= a` - /// * `Step::forward(Step::backward(a, n), n) == a` - fn backward(start: Self, count: usize) -> Self { - Step::backward_checked(start, count).expect("overflow in `Step::backward`") - } - - /// Returns the value that would be obtained by taking the *predecessor* - /// of `self` `count` times. - /// - /// # Safety - /// - /// It is undefined behavior for this operation to overflow the - /// range of values supported by `Self`. If you cannot guarantee that this - /// will not overflow, use `backward` or `backward_checked` instead. - /// - /// # Invariants - /// - /// For any `a`: - /// - /// * if there exists `b` such that `b < a`, it is safe to call `Step::backward_unchecked(a, 1)` - /// * if there exists `b`, `n` such that `steps_between(&b, &a) == Some(n)`, - /// it is safe to call `Step::backward_unchecked(a, m)` for any `m <= n`. - /// * Corollary: `Step::backward_unchecked(a, 0)` is always safe. - /// - /// For any `a` and `n`, where no overflow occurs: - /// - /// * `Step::backward_unchecked(a, n)` is equivalent to `Step::backward(a, n)` - unsafe fn backward_unchecked(start: Self, count: usize) -> Self { - Step::backward(start, count) - } -} - -// Separate impls for signed ranges because the distance within a signed range can be larger -// than the signed::MAX value. Therefore `as` casting to the signed type would be incorrect. -macro_rules! step_signed_methods { - ($unsigned: ty) => { - #[inline] - unsafe fn forward_unchecked(start: Self, n: usize) -> Self { - // SAFETY: the caller has to guarantee that `start + n` doesn't overflow. - unsafe { start.checked_add_unsigned(n as $unsigned).unwrap_unchecked() } - } - - #[inline] - unsafe fn backward_unchecked(start: Self, n: usize) -> Self { - // SAFETY: the caller has to guarantee that `start - n` doesn't overflow. - unsafe { start.checked_sub_unsigned(n as $unsigned).unwrap_unchecked() } - } - }; -} - -macro_rules! step_unsigned_methods { - () => { - #[inline] - unsafe fn forward_unchecked(start: Self, n: usize) -> Self { - // SAFETY: the caller has to guarantee that `start + n` doesn't overflow. - unsafe { start.unchecked_add(n as Self) } - } - - #[inline] - unsafe fn backward_unchecked(start: Self, n: usize) -> Self { - // SAFETY: the caller has to guarantee that `start - n` doesn't overflow. - unsafe { start.unchecked_sub(n as Self) } - } - }; -} - -// These are still macro-generated because the integer literals resolve to different types. -macro_rules! step_identical_methods { - () => { - #[inline] - #[allow(arithmetic_overflow)] - #[rustc_inherit_overflow_checks] - fn forward(start: Self, n: usize) -> Self { - // In debug builds, trigger a panic on overflow. - // This should optimize completely out in release builds. - if Self::forward_checked(start, n).is_none() { - let _ = Self::MAX + 1; - } - // Do wrapping math to allow e.g. `Step::forward(-128i8, 255)`. - start.wrapping_add(n as Self) - } - - #[inline] - #[allow(arithmetic_overflow)] - #[rustc_inherit_overflow_checks] - fn backward(start: Self, n: usize) -> Self { - // In debug builds, trigger a panic on overflow. - // This should optimize completely out in release builds. - if Self::backward_checked(start, n).is_none() { - let _ = Self::MIN - 1; - } - // Do wrapping math to allow e.g. `Step::backward(127i8, 255)`. - start.wrapping_sub(n as Self) - } - }; -} - -macro_rules! step_integer_impls { - { - narrower than or same width as usize: - $( [ $u_narrower:ident $i_narrower:ident ] ),+; - wider than usize: - $( [ $u_wider:ident $i_wider:ident ] ),+; - } => { - $( - #[allow(unreachable_patterns)] - #[unstable(feature = "step_trait", reason = "recently redesigned", issue = "42168")] - impl Step for $u_narrower { - step_identical_methods!(); - step_unsigned_methods!(); - - #[inline] - fn steps_between(start: &Self, end: &Self) -> Option { - if *start <= *end { - // This relies on $u_narrower <= usize - Some((*end - *start) as usize) - } else { - None - } - } - - #[inline] - fn forward_checked(start: Self, n: usize) -> Option { - match Self::try_from(n) { - Ok(n) => start.checked_add(n), - Err(_) => None, // if n is out of range, `unsigned_start + n` is too - } - } - - #[inline] - fn backward_checked(start: Self, n: usize) -> Option { - match Self::try_from(n) { - Ok(n) => start.checked_sub(n), - Err(_) => None, // if n is out of range, `unsigned_start - n` is too - } - } - } - - #[allow(unreachable_patterns)] - #[unstable(feature = "step_trait", reason = "recently redesigned", issue = "42168")] - impl Step for $i_narrower { - step_identical_methods!(); - step_signed_methods!($u_narrower); - - #[inline] - fn steps_between(start: &Self, end: &Self) -> Option { - if *start <= *end { - // This relies on $i_narrower <= usize - // - // Casting to isize extends the width but preserves the sign. - // Use wrapping_sub in isize space and cast to usize to compute - // the difference that might not fit inside the range of isize. - Some((*end as isize).wrapping_sub(*start as isize) as usize) - } else { - None - } - } - - #[inline] - fn forward_checked(start: Self, n: usize) -> Option { - match $u_narrower::try_from(n) { - Ok(n) => { - // Wrapping handles cases like - // `Step::forward(-120_i8, 200) == Some(80_i8)`, - // even though 200 is out of range for i8. - let wrapped = start.wrapping_add(n as Self); - if wrapped >= start { - Some(wrapped) - } else { - None // Addition overflowed - } - } - // If n is out of range of e.g. u8, - // then it is bigger than the entire range for i8 is wide - // so `any_i8 + n` necessarily overflows i8. - Err(_) => None, - } - } - - #[inline] - fn backward_checked(start: Self, n: usize) -> Option { - match $u_narrower::try_from(n) { - Ok(n) => { - // Wrapping handles cases like - // `Step::forward(-120_i8, 200) == Some(80_i8)`, - // even though 200 is out of range for i8. - let wrapped = start.wrapping_sub(n as Self); - if wrapped <= start { - Some(wrapped) - } else { - None // Subtraction overflowed - } - } - // If n is out of range of e.g. u8, - // then it is bigger than the entire range for i8 is wide - // so `any_i8 - n` necessarily overflows i8. - Err(_) => None, - } - } - } - )+ - - $( - #[allow(unreachable_patterns)] - #[unstable(feature = "step_trait", reason = "recently redesigned", issue = "42168")] - impl Step for $u_wider { - step_identical_methods!(); - step_unsigned_methods!(); - - #[inline] - fn steps_between(start: &Self, end: &Self) -> Option { - if *start <= *end { - usize::try_from(*end - *start).ok() - } else { - None - } - } - - #[inline] - fn forward_checked(start: Self, n: usize) -> Option { - start.checked_add(n as Self) - } - - #[inline] - fn backward_checked(start: Self, n: usize) -> Option { - start.checked_sub(n as Self) - } - } - - #[allow(unreachable_patterns)] - #[unstable(feature = "step_trait", reason = "recently redesigned", issue = "42168")] - impl Step for $i_wider { - step_identical_methods!(); - step_signed_methods!($u_wider); - - #[inline] - fn steps_between(start: &Self, end: &Self) -> Option { - if *start <= *end { - match end.checked_sub(*start) { - Some(result) => usize::try_from(result).ok(), - // If the difference is too big for e.g. i128, - // it's also gonna be too big for usize with fewer bits. - None => None, - } - } else { - None - } - } - - #[inline] - fn forward_checked(start: Self, n: usize) -> Option { - start.checked_add(n as Self) - } - - #[inline] - fn backward_checked(start: Self, n: usize) -> Option { - start.checked_sub(n as Self) - } - } - )+ - }; -} - -#[cfg(target_pointer_width = "64")] -step_integer_impls! { - narrower than or same width as usize: [u8 i8], [u16 i16], [u32 i32], [u64 i64], [usize isize]; - wider than usize: [u128 i128]; -} - -#[cfg(target_pointer_width = "32")] -step_integer_impls! { - narrower than or same width as usize: [u8 i8], [u16 i16], [u32 i32], [usize isize]; - wider than usize: [u64 i64], [u128 i128]; -} - -#[cfg(target_pointer_width = "16")] -step_integer_impls! { - narrower than or same width as usize: [u8 i8], [u16 i16], [usize isize]; - wider than usize: [u32 i32], [u64 i64], [u128 i128]; -} - -#[unstable(feature = "step_trait", reason = "recently redesigned", issue = "42168")] -impl Step for char { - #[inline] - fn steps_between(&start: &char, &end: &char) -> Option { - let start = start as u32; - let end = end as u32; - if start <= end { - let count = end - start; - if start < 0xD800 && 0xE000 <= end { - usize::try_from(count - 0x800).ok() - } else { - usize::try_from(count).ok() - } - } else { - None - } - } - - #[inline] - fn forward_checked(start: char, count: usize) -> Option { - let start = start as u32; - let mut res = Step::forward_checked(start, count)?; - if start < 0xD800 && 0xD800 <= res { - res = Step::forward_checked(res, 0x800)?; - } - if res <= char::MAX as u32 { - // SAFETY: res is a valid unicode scalar - // (below 0x110000 and not in 0xD800..0xE000) - Some(unsafe { char::from_u32_unchecked(res) }) - } else { - None - } - } - - #[inline] - fn backward_checked(start: char, count: usize) -> Option { - let start = start as u32; - let mut res = Step::backward_checked(start, count)?; - if start >= 0xE000 && 0xE000 > res { - res = Step::backward_checked(res, 0x800)?; - } - // SAFETY: res is a valid unicode scalar - // (below 0x110000 and not in 0xD800..0xE000) - Some(unsafe { char::from_u32_unchecked(res) }) - } - - #[inline] - unsafe fn forward_unchecked(start: char, count: usize) -> char { - let start = start as u32; - // SAFETY: the caller must guarantee that this doesn't overflow - // the range of values for a char. - let mut res = unsafe { Step::forward_unchecked(start, count) }; - if start < 0xD800 && 0xD800 <= res { - // SAFETY: the caller must guarantee that this doesn't overflow - // the range of values for a char. - res = unsafe { Step::forward_unchecked(res, 0x800) }; - } - // SAFETY: because of the previous contract, this is guaranteed - // by the caller to be a valid char. - unsafe { char::from_u32_unchecked(res) } - } - - #[inline] - unsafe fn backward_unchecked(start: char, count: usize) -> char { - let start = start as u32; - // SAFETY: the caller must guarantee that this doesn't overflow - // the range of values for a char. - let mut res = unsafe { Step::backward_unchecked(start, count) }; - if start >= 0xE000 && 0xE000 > res { - // SAFETY: the caller must guarantee that this doesn't overflow - // the range of values for a char. - res = unsafe { Step::backward_unchecked(res, 0x800) }; - } - // SAFETY: because of the previous contract, this is guaranteed - // by the caller to be a valid char. - unsafe { char::from_u32_unchecked(res) } - } -} - -#[unstable(feature = "step_trait", reason = "recently redesigned", issue = "42168")] -impl Step for AsciiChar { - #[inline] - fn steps_between(&start: &AsciiChar, &end: &AsciiChar) -> Option { - Step::steps_between(&start.to_u8(), &end.to_u8()) - } - - #[inline] - fn forward_checked(start: AsciiChar, count: usize) -> Option { - let end = Step::forward_checked(start.to_u8(), count)?; - AsciiChar::from_u8(end) - } - - #[inline] - fn backward_checked(start: AsciiChar, count: usize) -> Option { - let end = Step::backward_checked(start.to_u8(), count)?; - - // SAFETY: Values below that of a valid ASCII character are also valid ASCII - Some(unsafe { AsciiChar::from_u8_unchecked(end) }) - } - - #[inline] - unsafe fn forward_unchecked(start: AsciiChar, count: usize) -> AsciiChar { - // SAFETY: Caller asserts that result is a valid ASCII character, - // and therefore it is a valid u8. - let end = unsafe { Step::forward_unchecked(start.to_u8(), count) }; - - // SAFETY: Caller asserts that result is a valid ASCII character. - unsafe { AsciiChar::from_u8_unchecked(end) } - } - - #[inline] - unsafe fn backward_unchecked(start: AsciiChar, count: usize) -> AsciiChar { - // SAFETY: Caller asserts that result is a valid ASCII character, - // and therefore it is a valid u8. - let end = unsafe { Step::backward_unchecked(start.to_u8(), count) }; - - // SAFETY: Caller asserts that result is a valid ASCII character. - unsafe { AsciiChar::from_u8_unchecked(end) } - } -} - -#[unstable(feature = "step_trait", reason = "recently redesigned", issue = "42168")] -impl Step for Ipv4Addr { - #[inline] - fn steps_between(&start: &Ipv4Addr, &end: &Ipv4Addr) -> Option { - u32::steps_between(&start.to_bits(), &end.to_bits()) - } - - #[inline] - fn forward_checked(start: Ipv4Addr, count: usize) -> Option { - u32::forward_checked(start.to_bits(), count).map(Ipv4Addr::from_bits) - } - - #[inline] - fn backward_checked(start: Ipv4Addr, count: usize) -> Option { - u32::backward_checked(start.to_bits(), count).map(Ipv4Addr::from_bits) - } - - #[inline] - unsafe fn forward_unchecked(start: Ipv4Addr, count: usize) -> Ipv4Addr { - // SAFETY: Since u32 and Ipv4Addr are losslessly convertible, - // this is as safe as the u32 version. - Ipv4Addr::from_bits(unsafe { u32::forward_unchecked(start.to_bits(), count) }) - } - - #[inline] - unsafe fn backward_unchecked(start: Ipv4Addr, count: usize) -> Ipv4Addr { - // SAFETY: Since u32 and Ipv4Addr are losslessly convertible, - // this is as safe as the u32 version. - Ipv4Addr::from_bits(unsafe { u32::backward_unchecked(start.to_bits(), count) }) - } -} - -#[unstable(feature = "step_trait", reason = "recently redesigned", issue = "42168")] -impl Step for Ipv6Addr { - #[inline] - fn steps_between(&start: &Ipv6Addr, &end: &Ipv6Addr) -> Option { - u128::steps_between(&start.to_bits(), &end.to_bits()) - } - - #[inline] - fn forward_checked(start: Ipv6Addr, count: usize) -> Option { - u128::forward_checked(start.to_bits(), count).map(Ipv6Addr::from_bits) - } - - #[inline] - fn backward_checked(start: Ipv6Addr, count: usize) -> Option { - u128::backward_checked(start.to_bits(), count).map(Ipv6Addr::from_bits) - } - - #[inline] - unsafe fn forward_unchecked(start: Ipv6Addr, count: usize) -> Ipv6Addr { - // SAFETY: Since u128 and Ipv6Addr are losslessly convertible, - // this is as safe as the u128 version. - Ipv6Addr::from_bits(unsafe { u128::forward_unchecked(start.to_bits(), count) }) - } - - #[inline] - unsafe fn backward_unchecked(start: Ipv6Addr, count: usize) -> Ipv6Addr { - // SAFETY: Since u128 and Ipv6Addr are losslessly convertible, - // this is as safe as the u128 version. - Ipv6Addr::from_bits(unsafe { u128::backward_unchecked(start.to_bits(), count) }) - } -} - -macro_rules! range_exact_iter_impl { - ($($t:ty)*) => ($( - #[stable(feature = "rust1", since = "1.0.0")] - impl ExactSizeIterator for ops::Range<$t> { } - )*) -} - -/// Safety: This macro must only be used on types that are `Copy` and result in ranges -/// which have an exact `size_hint()` where the upper bound must not be `None`. -macro_rules! unsafe_range_trusted_random_access_impl { - ($($t:ty)*) => ($( - #[doc(hidden)] - #[unstable(feature = "trusted_random_access", issue = "none")] - unsafe impl TrustedRandomAccess for ops::Range<$t> {} - - #[doc(hidden)] - #[unstable(feature = "trusted_random_access", issue = "none")] - unsafe impl TrustedRandomAccessNoCoerce for ops::Range<$t> { - const MAY_HAVE_SIDE_EFFECT: bool = false; - } - )*) -} - -macro_rules! range_incl_exact_iter_impl { - ($($t:ty)*) => ($( - #[stable(feature = "inclusive_range", since = "1.26.0")] - impl ExactSizeIterator for ops::RangeInclusive<$t> { } - )*) -} - -/// Specialization implementations for `Range`. -trait RangeIteratorImpl { - type Item; - - // Iterator - fn spec_next(&mut self) -> Option; - fn spec_nth(&mut self, n: usize) -> Option; - fn spec_advance_by(&mut self, n: usize) -> Result<(), NonZero>; - - // DoubleEndedIterator - fn spec_next_back(&mut self) -> Option; - fn spec_nth_back(&mut self, n: usize) -> Option; - fn spec_advance_back_by(&mut self, n: usize) -> Result<(), NonZero>; -} - -impl RangeIteratorImpl for ops::Range { - type Item = A; - - #[inline] - default fn spec_next(&mut self) -> Option { - if self.start < self.end { - let n = - Step::forward_checked(self.start.clone(), 1).expect("`Step` invariants not upheld"); - Some(mem::replace(&mut self.start, n)) - } else { - None - } - } - - #[inline] - default fn spec_nth(&mut self, n: usize) -> Option { - if let Some(plus_n) = Step::forward_checked(self.start.clone(), n) { - if plus_n < self.end { - self.start = - Step::forward_checked(plus_n.clone(), 1).expect("`Step` invariants not upheld"); - return Some(plus_n); - } - } - - self.start = self.end.clone(); - None - } - - #[inline] - default fn spec_advance_by(&mut self, n: usize) -> Result<(), NonZero> { - let available = if self.start <= self.end { - Step::steps_between(&self.start, &self.end).unwrap_or(usize::MAX) - } else { - 0 - }; - - let taken = available.min(n); - - self.start = - Step::forward_checked(self.start.clone(), taken).expect("`Step` invariants not upheld"); - - NonZero::new(n - taken).map_or(Ok(()), Err) - } - - #[inline] - default fn spec_next_back(&mut self) -> Option { - if self.start < self.end { - self.end = - Step::backward_checked(self.end.clone(), 1).expect("`Step` invariants not upheld"); - Some(self.end.clone()) - } else { - None - } - } - - #[inline] - default fn spec_nth_back(&mut self, n: usize) -> Option { - if let Some(minus_n) = Step::backward_checked(self.end.clone(), n) { - if minus_n > self.start { - self.end = - Step::backward_checked(minus_n, 1).expect("`Step` invariants not upheld"); - return Some(self.end.clone()); - } - } - - self.end = self.start.clone(); - None - } - - #[inline] - default fn spec_advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - let available = if self.start <= self.end { - Step::steps_between(&self.start, &self.end).unwrap_or(usize::MAX) - } else { - 0 - }; - - let taken = available.min(n); - - self.end = - Step::backward_checked(self.end.clone(), taken).expect("`Step` invariants not upheld"); - - NonZero::new(n - taken).map_or(Ok(()), Err) - } -} - -impl RangeIteratorImpl for ops::Range { - #[inline] - fn spec_next(&mut self) -> Option { - if self.start < self.end { - let old = self.start; - // SAFETY: just checked precondition - self.start = unsafe { Step::forward_unchecked(old, 1) }; - Some(old) - } else { - None - } - } - - #[inline] - fn spec_nth(&mut self, n: usize) -> Option { - if let Some(plus_n) = Step::forward_checked(self.start, n) { - if plus_n < self.end { - // SAFETY: just checked precondition - self.start = unsafe { Step::forward_unchecked(plus_n, 1) }; - return Some(plus_n); - } - } - - self.start = self.end; - None - } - - #[inline] - fn spec_advance_by(&mut self, n: usize) -> Result<(), NonZero> { - let available = if self.start <= self.end { - Step::steps_between(&self.start, &self.end).unwrap_or(usize::MAX) - } else { - 0 - }; - - let taken = available.min(n); - - // SAFETY: the conditions above ensure that the count is in bounds. If start <= end - // then steps_between either returns a bound to which we clamp or returns None which - // together with the initial inequality implies more than usize::MAX steps. - // Otherwise 0 is returned which always safe to use. - self.start = unsafe { Step::forward_unchecked(self.start, taken) }; - - NonZero::new(n - taken).map_or(Ok(()), Err) - } - - #[inline] - fn spec_next_back(&mut self) -> Option { - if self.start < self.end { - // SAFETY: just checked precondition - self.end = unsafe { Step::backward_unchecked(self.end, 1) }; - Some(self.end) - } else { - None - } - } - - #[inline] - fn spec_nth_back(&mut self, n: usize) -> Option { - if let Some(minus_n) = Step::backward_checked(self.end, n) { - if minus_n > self.start { - // SAFETY: just checked precondition - self.end = unsafe { Step::backward_unchecked(minus_n, 1) }; - return Some(self.end); - } - } - - self.end = self.start; - None - } - - #[inline] - fn spec_advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - let available = if self.start <= self.end { - Step::steps_between(&self.start, &self.end).unwrap_or(usize::MAX) - } else { - 0 - }; - - let taken = available.min(n); - - // SAFETY: same as the spec_advance_by() implementation - self.end = unsafe { Step::backward_unchecked(self.end, taken) }; - - NonZero::new(n - taken).map_or(Ok(()), Err) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for ops::Range { - type Item = A; - - #[inline] - fn next(&mut self) -> Option { - self.spec_next() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - if self.start < self.end { - let hint = Step::steps_between(&self.start, &self.end); - (hint.unwrap_or(usize::MAX), hint) - } else { - (0, Some(0)) - } - } - - #[inline] - fn count(self) -> usize { - if self.start < self.end { - Step::steps_between(&self.start, &self.end).expect("count overflowed usize") - } else { - 0 - } - } - - #[inline] - fn nth(&mut self, n: usize) -> Option { - self.spec_nth(n) - } - - #[inline] - fn last(mut self) -> Option { - self.next_back() - } - - #[inline] - fn min(mut self) -> Option - where - A: Ord, - { - self.next() - } - - #[inline] - fn max(mut self) -> Option - where - A: Ord, - { - self.next_back() - } - - #[inline] - fn is_sorted(self) -> bool { - true - } - - #[inline] - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - self.spec_advance_by(n) - } - - #[inline] - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item - where - Self: TrustedRandomAccessNoCoerce, - { - // SAFETY: The TrustedRandomAccess contract requires that callers only pass an index - // that is in bounds. - // Additionally Self: TrustedRandomAccess is only implemented for Copy types - // which means even repeated reads of the same index would be safe. - unsafe { Step::forward_unchecked(self.start.clone(), idx) } - } -} - -// These macros generate `ExactSizeIterator` impls for various range types. -// -// * `ExactSizeIterator::len` is required to always return an exact `usize`, -// so no range can be longer than `usize::MAX`. -// * For integer types in `Range<_>` this is the case for types narrower than or as wide as `usize`. -// For integer types in `RangeInclusive<_>` -// this is the case for types *strictly narrower* than `usize` -// since e.g. `(0..=u64::MAX).len()` would be `u64::MAX + 1`. -range_exact_iter_impl! { - usize u8 u16 - isize i8 i16 - - // These are incorrect per the reasoning above, - // but removing them would be a breaking change as they were stabilized in Rust 1.0.0. - // So e.g. `(0..66_000_u32).len()` for example will compile without error or warnings - // on 16-bit platforms, but continue to give a wrong result. - u32 - i32 -} - -unsafe_range_trusted_random_access_impl! { - usize u8 u16 - isize i8 i16 -} - -#[cfg(target_pointer_width = "32")] -unsafe_range_trusted_random_access_impl! { - u32 i32 -} - -#[cfg(target_pointer_width = "64")] -unsafe_range_trusted_random_access_impl! { - u32 i32 - u64 i64 -} - -range_incl_exact_iter_impl! { - u8 - i8 - - // These are incorrect per the reasoning above, - // but removing them would be a breaking change as they were stabilized in Rust 1.26.0. - // So e.g. `(0..=u16::MAX).len()` for example will compile without error or warnings - // on 16-bit platforms, but continue to give a wrong result. - u16 - i16 -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DoubleEndedIterator for ops::Range { - #[inline] - fn next_back(&mut self) -> Option { - self.spec_next_back() - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option { - self.spec_nth_back(n) - } - - #[inline] - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - self.spec_advance_back_by(n) - } -} - -// Safety: -// The following invariants for `Step::steps_between` exist: -// -// > * `steps_between(&a, &b) == Some(n)` only if `a <= b` -// > * Note that `a <= b` does _not_ imply `steps_between(&a, &b) != None`; -// > this is the case when it would require more than `usize::MAX` steps to -// > get to `b` -// > * `steps_between(&a, &b) == None` if `a > b` -// -// The first invariant is what is generally required for `TrustedLen` to be -// sound. The note addendum satisfies an additional `TrustedLen` invariant. -// -// > The upper bound must only be `None` if the actual iterator length is larger -// > than `usize::MAX` -// -// The second invariant logically follows the first so long as the `PartialOrd` -// implementation is correct; regardless it is explicitly stated. If `a < b` -// then `(0, Some(0))` is returned by `ops::Range::size_hint`. As such -// the second invariant is upheld. -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for ops::Range {} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for ops::Range {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for ops::RangeFrom { - type Item = A; - - #[inline] - fn next(&mut self) -> Option { - let n = Step::forward(self.start.clone(), 1); - Some(mem::replace(&mut self.start, n)) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - (usize::MAX, None) - } - - #[inline] - fn nth(&mut self, n: usize) -> Option { - let plus_n = Step::forward(self.start.clone(), n); - self.start = Step::forward(plus_n.clone(), 1); - Some(plus_n) - } -} - -// Safety: See above implementation for `ops::Range` -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for ops::RangeFrom {} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for ops::RangeFrom {} - -trait RangeInclusiveIteratorImpl { - type Item; - - // Iterator - fn spec_next(&mut self) -> Option; - fn spec_try_fold(&mut self, init: B, f: F) -> R - where - Self: Sized, - F: FnMut(B, Self::Item) -> R, - R: Try; - - // DoubleEndedIterator - fn spec_next_back(&mut self) -> Option; - fn spec_try_rfold(&mut self, init: B, f: F) -> R - where - Self: Sized, - F: FnMut(B, Self::Item) -> R, - R: Try; -} - -impl RangeInclusiveIteratorImpl for ops::RangeInclusive { - type Item = A; - - #[inline] - default fn spec_next(&mut self) -> Option { - if self.is_empty() { - return None; - } - let is_iterating = self.start < self.end; - Some(if is_iterating { - let n = - Step::forward_checked(self.start.clone(), 1).expect("`Step` invariants not upheld"); - mem::replace(&mut self.start, n) - } else { - self.exhausted = true; - self.start.clone() - }) - } - - #[inline] - default fn spec_try_fold(&mut self, init: B, mut f: F) -> R - where - Self: Sized, - F: FnMut(B, A) -> R, - R: Try, - { - if self.is_empty() { - return try { init }; - } - - let mut accum = init; - - while self.start < self.end { - let n = - Step::forward_checked(self.start.clone(), 1).expect("`Step` invariants not upheld"); - let n = mem::replace(&mut self.start, n); - accum = f(accum, n)?; - } - - self.exhausted = true; - - if self.start == self.end { - accum = f(accum, self.start.clone())?; - } - - try { accum } - } - - #[inline] - default fn spec_next_back(&mut self) -> Option { - if self.is_empty() { - return None; - } - let is_iterating = self.start < self.end; - Some(if is_iterating { - let n = - Step::backward_checked(self.end.clone(), 1).expect("`Step` invariants not upheld"); - mem::replace(&mut self.end, n) - } else { - self.exhausted = true; - self.end.clone() - }) - } - - #[inline] - default fn spec_try_rfold(&mut self, init: B, mut f: F) -> R - where - Self: Sized, - F: FnMut(B, A) -> R, - R: Try, - { - if self.is_empty() { - return try { init }; - } - - let mut accum = init; - - while self.start < self.end { - let n = - Step::backward_checked(self.end.clone(), 1).expect("`Step` invariants not upheld"); - let n = mem::replace(&mut self.end, n); - accum = f(accum, n)?; - } - - self.exhausted = true; - - if self.start == self.end { - accum = f(accum, self.start.clone())?; - } - - try { accum } - } -} - -impl RangeInclusiveIteratorImpl for ops::RangeInclusive { - #[inline] - fn spec_next(&mut self) -> Option { - if self.is_empty() { - return None; - } - let is_iterating = self.start < self.end; - Some(if is_iterating { - // SAFETY: just checked precondition - let n = unsafe { Step::forward_unchecked(self.start, 1) }; - mem::replace(&mut self.start, n) - } else { - self.exhausted = true; - self.start - }) - } - - #[inline] - fn spec_try_fold(&mut self, init: B, mut f: F) -> R - where - Self: Sized, - F: FnMut(B, T) -> R, - R: Try, - { - if self.is_empty() { - return try { init }; - } - - let mut accum = init; - - while self.start < self.end { - // SAFETY: just checked precondition - let n = unsafe { Step::forward_unchecked(self.start, 1) }; - let n = mem::replace(&mut self.start, n); - accum = f(accum, n)?; - } - - self.exhausted = true; - - if self.start == self.end { - accum = f(accum, self.start)?; - } - - try { accum } - } - - #[inline] - fn spec_next_back(&mut self) -> Option { - if self.is_empty() { - return None; - } - let is_iterating = self.start < self.end; - Some(if is_iterating { - // SAFETY: just checked precondition - let n = unsafe { Step::backward_unchecked(self.end, 1) }; - mem::replace(&mut self.end, n) - } else { - self.exhausted = true; - self.end - }) - } - - #[inline] - fn spec_try_rfold(&mut self, init: B, mut f: F) -> R - where - Self: Sized, - F: FnMut(B, T) -> R, - R: Try, - { - if self.is_empty() { - return try { init }; - } - - let mut accum = init; - - while self.start < self.end { - // SAFETY: just checked precondition - let n = unsafe { Step::backward_unchecked(self.end, 1) }; - let n = mem::replace(&mut self.end, n); - accum = f(accum, n)?; - } - - self.exhausted = true; - - if self.start == self.end { - accum = f(accum, self.start)?; - } - - try { accum } - } -} - -#[stable(feature = "inclusive_range", since = "1.26.0")] -impl Iterator for ops::RangeInclusive { - type Item = A; - - #[inline] - fn next(&mut self) -> Option { - self.spec_next() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - if self.is_empty() { - return (0, Some(0)); - } - - match Step::steps_between(&self.start, &self.end) { - Some(hint) => (hint.saturating_add(1), hint.checked_add(1)), - None => (usize::MAX, None), - } - } - - #[inline] - fn count(self) -> usize { - if self.is_empty() { - return 0; - } - - Step::steps_between(&self.start, &self.end) - .and_then(|steps| steps.checked_add(1)) - .expect("count overflowed usize") - } - - #[inline] - fn nth(&mut self, n: usize) -> Option { - if self.is_empty() { - return None; - } - - if let Some(plus_n) = Step::forward_checked(self.start.clone(), n) { - use crate::cmp::Ordering::*; - - match plus_n.partial_cmp(&self.end) { - Some(Less) => { - self.start = Step::forward(plus_n.clone(), 1); - return Some(plus_n); - } - Some(Equal) => { - self.start = plus_n.clone(); - self.exhausted = true; - return Some(plus_n); - } - _ => {} - } - } - - self.start = self.end.clone(); - self.exhausted = true; - None - } - - #[inline] - fn try_fold(&mut self, init: B, f: F) -> R - where - Self: Sized, - F: FnMut(B, Self::Item) -> R, - R: Try, - { - self.spec_try_fold(init, f) - } - - impl_fold_via_try_fold! { fold -> try_fold } - - #[inline] - fn last(mut self) -> Option { - self.next_back() - } - - #[inline] - fn min(mut self) -> Option - where - A: Ord, - { - self.next() - } - - #[inline] - fn max(mut self) -> Option - where - A: Ord, - { - self.next_back() - } - - #[inline] - fn is_sorted(self) -> bool { - true - } -} - -#[stable(feature = "inclusive_range", since = "1.26.0")] -impl DoubleEndedIterator for ops::RangeInclusive { - #[inline] - fn next_back(&mut self) -> Option { - self.spec_next_back() - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option { - if self.is_empty() { - return None; - } - - if let Some(minus_n) = Step::backward_checked(self.end.clone(), n) { - use crate::cmp::Ordering::*; - - match minus_n.partial_cmp(&self.start) { - Some(Greater) => { - self.end = Step::backward(minus_n.clone(), 1); - return Some(minus_n); - } - Some(Equal) => { - self.end = minus_n.clone(); - self.exhausted = true; - return Some(minus_n); - } - _ => {} - } - } - - self.end = self.start.clone(); - self.exhausted = true; - None - } - - #[inline] - fn try_rfold(&mut self, init: B, f: F) -> R - where - Self: Sized, - F: FnMut(B, Self::Item) -> R, - R: Try, - { - self.spec_try_rfold(init, f) - } - - impl_fold_via_try_fold! { rfold -> try_rfold } -} - -// Safety: See above implementation for `ops::Range` -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for ops::RangeInclusive {} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for ops::RangeInclusive {} diff --git a/library/core/src/iter/sources.rs b/library/core/src/iter/sources.rs deleted file mode 100644 index 56c1f86079a3a..0000000000000 --- a/library/core/src/iter/sources.rs +++ /dev/null @@ -1,40 +0,0 @@ -mod empty; -mod from_coroutine; -mod from_fn; -mod once; -mod once_with; -mod repeat; -mod repeat_n; -mod repeat_with; -mod successors; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::repeat::{repeat, Repeat}; - -#[stable(feature = "iter_empty", since = "1.2.0")] -pub use self::empty::{empty, Empty}; - -#[stable(feature = "iter_once", since = "1.2.0")] -pub use self::once::{once, Once}; - -#[unstable(feature = "iter_repeat_n", issue = "104434")] -pub use self::repeat_n::{repeat_n, RepeatN}; - -#[stable(feature = "iterator_repeat_with", since = "1.28.0")] -pub use self::repeat_with::{repeat_with, RepeatWith}; - -#[stable(feature = "iter_from_fn", since = "1.34.0")] -pub use self::from_fn::{from_fn, FromFn}; - -#[unstable( - feature = "iter_from_coroutine", - issue = "43122", - reason = "coroutines are unstable" -)] -pub use self::from_coroutine::from_coroutine; - -#[stable(feature = "iter_successors", since = "1.34.0")] -pub use self::successors::{successors, Successors}; - -#[stable(feature = "iter_once_with", since = "1.43.0")] -pub use self::once_with::{once_with, OnceWith}; diff --git a/library/core/src/iter/sources/empty.rs b/library/core/src/iter/sources/empty.rs deleted file mode 100644 index 438e046a4dfdc..0000000000000 --- a/library/core/src/iter/sources/empty.rs +++ /dev/null @@ -1,89 +0,0 @@ -use crate::fmt; -use crate::iter::{FusedIterator, TrustedLen}; -use crate::marker; - -/// Creates an iterator that yields nothing. -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// use std::iter; -/// -/// // this could have been an iterator over i32, but alas, it's just not. -/// let mut nope = iter::empty::(); -/// -/// assert_eq!(None, nope.next()); -/// ``` -#[stable(feature = "iter_empty", since = "1.2.0")] -#[rustc_const_stable(feature = "const_iter_empty", since = "1.32.0")] -pub const fn empty() -> Empty { - Empty(marker::PhantomData) -} - -/// An iterator that yields nothing. -/// -/// This `struct` is created by the [`empty()`] function. See its documentation for more. -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "iter_empty", since = "1.2.0")] -#[rustc_diagnostic_item = "IterEmpty"] -pub struct Empty(marker::PhantomData T>); - -#[stable(feature = "core_impl_debug", since = "1.9.0")] -impl fmt::Debug for Empty { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Empty").finish() - } -} - -#[stable(feature = "iter_empty", since = "1.2.0")] -impl Iterator for Empty { - type Item = T; - - fn next(&mut self) -> Option { - None - } - - fn size_hint(&self) -> (usize, Option) { - (0, Some(0)) - } -} - -#[stable(feature = "iter_empty", since = "1.2.0")] -impl DoubleEndedIterator for Empty { - fn next_back(&mut self) -> Option { - None - } -} - -#[stable(feature = "iter_empty", since = "1.2.0")] -impl ExactSizeIterator for Empty { - fn len(&self) -> usize { - 0 - } -} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for Empty {} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Empty {} - -// not #[derive] because that adds a Clone bound on T, -// which isn't necessary. -#[stable(feature = "iter_empty", since = "1.2.0")] -impl Clone for Empty { - fn clone(&self) -> Empty { - Empty(marker::PhantomData) - } -} - -// not #[derive] because that adds a Default bound on T, -// which isn't necessary. -#[stable(feature = "iter_empty", since = "1.2.0")] -impl Default for Empty { - fn default() -> Empty { - Empty(marker::PhantomData) - } -} diff --git a/library/core/src/iter/sources/from_coroutine.rs b/library/core/src/iter/sources/from_coroutine.rs deleted file mode 100644 index 710ba504ded64..0000000000000 --- a/library/core/src/iter/sources/from_coroutine.rs +++ /dev/null @@ -1,58 +0,0 @@ -use crate::fmt; -use crate::ops::{Coroutine, CoroutineState}; -use crate::pin::Pin; - -/// Creates a new iterator where each iteration calls the provided coroutine. -/// -/// Similar to [`iter::from_fn`]. -/// -/// [`iter::from_fn`]: crate::iter::from_fn -/// -/// # Examples -/// -/// ``` -/// #![feature(coroutines)] -/// #![feature(iter_from_coroutine)] -/// -/// let it = std::iter::from_coroutine(#[coroutine] || { -/// yield 1; -/// yield 2; -/// yield 3; -/// }); -/// let v: Vec<_> = it.collect(); -/// assert_eq!(v, [1, 2, 3]); -/// ``` -#[inline] -#[unstable(feature = "iter_from_coroutine", issue = "43122", reason = "coroutines are unstable")] -pub fn from_coroutine + Unpin>(coroutine: G) -> FromCoroutine { - FromCoroutine(coroutine) -} - -/// An iterator over the values yielded by an underlying coroutine. -/// -/// This `struct` is created by the [`iter::from_coroutine()`] function. See its documentation for -/// more. -/// -/// [`iter::from_coroutine()`]: from_coroutine -#[unstable(feature = "iter_from_coroutine", issue = "43122", reason = "coroutines are unstable")] -#[derive(Clone)] -pub struct FromCoroutine(G); - -#[unstable(feature = "iter_from_coroutine", issue = "43122", reason = "coroutines are unstable")] -impl + Unpin> Iterator for FromCoroutine { - type Item = G::Yield; - - fn next(&mut self) -> Option { - match Pin::new(&mut self.0).resume(()) { - CoroutineState::Yielded(n) => Some(n), - CoroutineState::Complete(()) => None, - } - } -} - -#[unstable(feature = "iter_from_coroutine", issue = "43122", reason = "coroutines are unstable")] -impl fmt::Debug for FromCoroutine { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("FromCoroutine").finish() - } -} diff --git a/library/core/src/iter/sources/from_fn.rs b/library/core/src/iter/sources/from_fn.rs deleted file mode 100644 index 3cd3830471cfe..0000000000000 --- a/library/core/src/iter/sources/from_fn.rs +++ /dev/null @@ -1,78 +0,0 @@ -use crate::fmt; - -/// Creates a new iterator where each iteration calls the provided closure -/// `F: FnMut() -> Option`. -/// -/// This allows creating a custom iterator with any behavior -/// without using the more verbose syntax of creating a dedicated type -/// and implementing the [`Iterator`] trait for it. -/// -/// Note that the `FromFn` iterator doesn’t make assumptions about the behavior of the closure, -/// and therefore conservatively does not implement [`FusedIterator`], -/// or override [`Iterator::size_hint()`] from its default `(0, None)`. -/// -/// The closure can use captures and its environment to track state across iterations. Depending on -/// how the iterator is used, this may require specifying the [`move`] keyword on the closure. -/// -/// [`move`]: ../../std/keyword.move.html -/// [`FusedIterator`]: crate::iter::FusedIterator -/// -/// # Examples -/// -/// Let’s re-implement the counter iterator from [module-level documentation]: -/// -/// [module-level documentation]: crate::iter -/// -/// ``` -/// let mut count = 0; -/// let counter = std::iter::from_fn(move || { -/// // Increment our count. This is why we started at zero. -/// count += 1; -/// -/// // Check to see if we've finished counting or not. -/// if count < 6 { -/// Some(count) -/// } else { -/// None -/// } -/// }); -/// assert_eq!(counter.collect::>(), &[1, 2, 3, 4, 5]); -/// ``` -#[inline] -#[stable(feature = "iter_from_fn", since = "1.34.0")] -pub fn from_fn(f: F) -> FromFn -where - F: FnMut() -> Option, -{ - FromFn(f) -} - -/// An iterator where each iteration calls the provided closure `F: FnMut() -> Option`. -/// -/// This `struct` is created by the [`iter::from_fn()`] function. -/// See its documentation for more. -/// -/// [`iter::from_fn()`]: from_fn -#[derive(Clone)] -#[stable(feature = "iter_from_fn", since = "1.34.0")] -pub struct FromFn(F); - -#[stable(feature = "iter_from_fn", since = "1.34.0")] -impl Iterator for FromFn -where - F: FnMut() -> Option, -{ - type Item = T; - - #[inline] - fn next(&mut self) -> Option { - (self.0)() - } -} - -#[stable(feature = "iter_from_fn", since = "1.34.0")] -impl fmt::Debug for FromFn { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("FromFn").finish() - } -} diff --git a/library/core/src/iter/sources/once.rs b/library/core/src/iter/sources/once.rs deleted file mode 100644 index 21be4377da1ca..0000000000000 --- a/library/core/src/iter/sources/once.rs +++ /dev/null @@ -1,100 +0,0 @@ -use crate::iter::{FusedIterator, TrustedLen}; - -/// Creates an iterator that yields an element exactly once. -/// -/// This is commonly used to adapt a single value into a [`chain()`] of other -/// kinds of iteration. Maybe you have an iterator that covers almost -/// everything, but you need an extra special case. Maybe you have a function -/// which works on iterators, but you only need to process one value. -/// -/// [`chain()`]: Iterator::chain -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// use std::iter; -/// -/// // one is the loneliest number -/// let mut one = iter::once(1); -/// -/// assert_eq!(Some(1), one.next()); -/// -/// // just one, that's all we get -/// assert_eq!(None, one.next()); -/// ``` -/// -/// Chaining together with another iterator. Let's say that we want to iterate -/// over each file of the `.foo` directory, but also a configuration file, -/// `.foorc`: -/// -/// ```no_run -/// use std::iter; -/// use std::fs; -/// use std::path::PathBuf; -/// -/// let dirs = fs::read_dir(".foo").unwrap(); -/// -/// // we need to convert from an iterator of DirEntry-s to an iterator of -/// // PathBufs, so we use map -/// let dirs = dirs.map(|file| file.unwrap().path()); -/// -/// // now, our iterator just for our config file -/// let config = iter::once(PathBuf::from(".foorc")); -/// -/// // chain the two iterators together into one big iterator -/// let files = dirs.chain(config); -/// -/// // this will give us all of the files in .foo as well as .foorc -/// for f in files { -/// println!("{f:?}"); -/// } -/// ``` -#[stable(feature = "iter_once", since = "1.2.0")] -pub fn once(value: T) -> Once { - Once { inner: Some(value).into_iter() } -} - -/// An iterator that yields an element exactly once. -/// -/// This `struct` is created by the [`once()`] function. See its documentation for more. -#[derive(Clone, Debug)] -#[stable(feature = "iter_once", since = "1.2.0")] -#[rustc_diagnostic_item = "IterOnce"] -pub struct Once { - inner: crate::option::IntoIter, -} - -#[stable(feature = "iter_once", since = "1.2.0")] -impl Iterator for Once { - type Item = T; - - fn next(&mut self) -> Option { - self.inner.next() - } - - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } -} - -#[stable(feature = "iter_once", since = "1.2.0")] -impl DoubleEndedIterator for Once { - fn next_back(&mut self) -> Option { - self.inner.next_back() - } -} - -#[stable(feature = "iter_once", since = "1.2.0")] -impl ExactSizeIterator for Once { - fn len(&self) -> usize { - self.inner.len() - } -} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for Once {} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Once {} diff --git a/library/core/src/iter/sources/once_with.rs b/library/core/src/iter/sources/once_with.rs deleted file mode 100644 index 8b31ab2ff90c0..0000000000000 --- a/library/core/src/iter/sources/once_with.rs +++ /dev/null @@ -1,121 +0,0 @@ -use crate::fmt; -use crate::iter::{FusedIterator, TrustedLen}; - -/// Creates an iterator that lazily generates a value exactly once by invoking -/// the provided closure. -/// -/// This is commonly used to adapt a single value coroutine into a [`chain()`] of -/// other kinds of iteration. Maybe you have an iterator that covers almost -/// everything, but you need an extra special case. Maybe you have a function -/// which works on iterators, but you only need to process one value. -/// -/// Unlike [`once()`], this function will lazily generate the value on request. -/// -/// [`chain()`]: Iterator::chain -/// [`once()`]: crate::iter::once -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// use std::iter; -/// -/// // one is the loneliest number -/// let mut one = iter::once_with(|| 1); -/// -/// assert_eq!(Some(1), one.next()); -/// -/// // just one, that's all we get -/// assert_eq!(None, one.next()); -/// ``` -/// -/// Chaining together with another iterator. Let's say that we want to iterate -/// over each file of the `.foo` directory, but also a configuration file, -/// `.foorc`: -/// -/// ```no_run -/// use std::iter; -/// use std::fs; -/// use std::path::PathBuf; -/// -/// let dirs = fs::read_dir(".foo").unwrap(); -/// -/// // we need to convert from an iterator of DirEntry-s to an iterator of -/// // PathBufs, so we use map -/// let dirs = dirs.map(|file| file.unwrap().path()); -/// -/// // now, our iterator just for our config file -/// let config = iter::once_with(|| PathBuf::from(".foorc")); -/// -/// // chain the two iterators together into one big iterator -/// let files = dirs.chain(config); -/// -/// // this will give us all of the files in .foo as well as .foorc -/// for f in files { -/// println!("{f:?}"); -/// } -/// ``` -#[inline] -#[stable(feature = "iter_once_with", since = "1.43.0")] -pub fn once_with A>(gen: F) -> OnceWith { - OnceWith { gen: Some(gen) } -} - -/// An iterator that yields a single element of type `A` by -/// applying the provided closure `F: FnOnce() -> A`. -/// -/// This `struct` is created by the [`once_with()`] function. -/// See its documentation for more. -#[derive(Clone)] -#[stable(feature = "iter_once_with", since = "1.43.0")] -pub struct OnceWith { - gen: Option, -} - -#[stable(feature = "iter_once_with_debug", since = "1.68.0")] -impl fmt::Debug for OnceWith { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - if self.gen.is_some() { - f.write_str("OnceWith(Some(_))") - } else { - f.write_str("OnceWith(None)") - } - } -} - -#[stable(feature = "iter_once_with", since = "1.43.0")] -impl A> Iterator for OnceWith { - type Item = A; - - #[inline] - fn next(&mut self) -> Option { - let f = self.gen.take()?; - Some(f()) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.gen.iter().size_hint() - } -} - -#[stable(feature = "iter_once_with", since = "1.43.0")] -impl A> DoubleEndedIterator for OnceWith { - fn next_back(&mut self) -> Option { - self.next() - } -} - -#[stable(feature = "iter_once_with", since = "1.43.0")] -impl A> ExactSizeIterator for OnceWith { - fn len(&self) -> usize { - self.gen.iter().len() - } -} - -#[stable(feature = "iter_once_with", since = "1.43.0")] -impl A> FusedIterator for OnceWith {} - -#[stable(feature = "iter_once_with", since = "1.43.0")] -unsafe impl A> TrustedLen for OnceWith {} diff --git a/library/core/src/iter/sources/repeat.rs b/library/core/src/iter/sources/repeat.rs deleted file mode 100644 index 0168b11c7394a..0000000000000 --- a/library/core/src/iter/sources/repeat.rs +++ /dev/null @@ -1,130 +0,0 @@ -use crate::iter::{FusedIterator, TrustedLen}; -use crate::num::NonZero; - -/// Creates a new iterator that endlessly repeats a single element. -/// -/// The `repeat()` function repeats a single value over and over again. -/// -/// Infinite iterators like `repeat()` are often used with adapters like -/// [`Iterator::take()`], in order to make them finite. -/// -/// If the element type of the iterator you need does not implement `Clone`, -/// or if you do not want to keep the repeated element in memory, you can -/// instead use the [`repeat_with()`] function. -/// -/// [`repeat_with()`]: crate::iter::repeat_with -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// use std::iter; -/// -/// // the number four 4ever: -/// let mut fours = iter::repeat(4); -/// -/// assert_eq!(Some(4), fours.next()); -/// assert_eq!(Some(4), fours.next()); -/// assert_eq!(Some(4), fours.next()); -/// assert_eq!(Some(4), fours.next()); -/// assert_eq!(Some(4), fours.next()); -/// -/// // yup, still four -/// assert_eq!(Some(4), fours.next()); -/// ``` -/// -/// Going finite with [`Iterator::take()`]: -/// -/// ``` -/// use std::iter; -/// -/// // that last example was too many fours. Let's only have four fours. -/// let mut four_fours = iter::repeat(4).take(4); -/// -/// assert_eq!(Some(4), four_fours.next()); -/// assert_eq!(Some(4), four_fours.next()); -/// assert_eq!(Some(4), four_fours.next()); -/// assert_eq!(Some(4), four_fours.next()); -/// -/// // ... and now we're done -/// assert_eq!(None, four_fours.next()); -/// ``` -#[inline] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "iter_repeat")] -pub fn repeat(elt: T) -> Repeat { - Repeat { element: elt } -} - -/// An iterator that repeats an element endlessly. -/// -/// This `struct` is created by the [`repeat()`] function. See its documentation for more. -#[derive(Clone, Debug)] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Repeat { - element: A, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for Repeat { - type Item = A; - - #[inline] - fn next(&mut self) -> Option { - Some(self.element.clone()) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - (usize::MAX, None) - } - - #[inline] - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - // Advancing an infinite iterator of a single element is a no-op. - let _ = n; - Ok(()) - } - - #[inline] - fn nth(&mut self, n: usize) -> Option { - let _ = n; - Some(self.element.clone()) - } - - fn last(self) -> Option { - loop {} - } - - fn count(self) -> usize { - loop {} - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DoubleEndedIterator for Repeat { - #[inline] - fn next_back(&mut self) -> Option { - Some(self.element.clone()) - } - - #[inline] - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - // Advancing an infinite iterator of a single element is a no-op. - let _ = n; - Ok(()) - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option { - let _ = n; - Some(self.element.clone()) - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Repeat {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for Repeat {} diff --git a/library/core/src/iter/sources/repeat_n.rs b/library/core/src/iter/sources/repeat_n.rs deleted file mode 100644 index 8224e4b12a0eb..0000000000000 --- a/library/core/src/iter/sources/repeat_n.rs +++ /dev/null @@ -1,195 +0,0 @@ -use crate::iter::{FusedIterator, TrustedLen}; -use crate::mem::ManuallyDrop; -use crate::num::NonZero; - -/// Creates a new iterator that repeats a single element a given number of times. -/// -/// The `repeat_n()` function repeats a single value exactly `n` times. -/// -/// This is very similar to using [`repeat()`] with [`Iterator::take()`], -/// but there are two differences: -/// - `repeat_n()` can return the original value, rather than always cloning. -/// - `repeat_n()` produces an [`ExactSizeIterator`]. -/// -/// [`repeat()`]: crate::iter::repeat -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// #![feature(iter_repeat_n)] -/// use std::iter; -/// -/// // four of the number four: -/// let mut four_fours = iter::repeat_n(4, 4); -/// -/// assert_eq!(Some(4), four_fours.next()); -/// assert_eq!(Some(4), four_fours.next()); -/// assert_eq!(Some(4), four_fours.next()); -/// assert_eq!(Some(4), four_fours.next()); -/// -/// // no more fours -/// assert_eq!(None, four_fours.next()); -/// ``` -/// -/// For non-`Copy` types, -/// -/// ``` -/// #![feature(iter_repeat_n)] -/// use std::iter; -/// -/// let v: Vec = Vec::with_capacity(123); -/// let mut it = iter::repeat_n(v, 5); -/// -/// for i in 0..4 { -/// // It starts by cloning things -/// let cloned = it.next().unwrap(); -/// assert_eq!(cloned.len(), 0); -/// assert_eq!(cloned.capacity(), 0); -/// } -/// -/// // ... but the last item is the original one -/// let last = it.next().unwrap(); -/// assert_eq!(last.len(), 0); -/// assert_eq!(last.capacity(), 123); -/// -/// // ... and now we're done -/// assert_eq!(None, it.next()); -/// ``` -#[inline] -#[unstable(feature = "iter_repeat_n", issue = "104434")] -pub fn repeat_n(element: T, count: usize) -> RepeatN { - let mut element = ManuallyDrop::new(element); - - if count == 0 { - // SAFETY: we definitely haven't dropped it yet, since we only just got - // passed it in, and because the count is zero the instance we're about - // to create won't drop it, so to avoid leaking we need to now. - unsafe { ManuallyDrop::drop(&mut element) }; - } - - RepeatN { element, count } -} - -/// An iterator that repeats an element an exact number of times. -/// -/// This `struct` is created by the [`repeat_n()`] function. -/// See its documentation for more. -#[derive(Clone, Debug)] -#[unstable(feature = "iter_repeat_n", issue = "104434")] -pub struct RepeatN { - count: usize, - // Invariant: has been dropped iff count == 0. - element: ManuallyDrop, -} - -impl RepeatN { - /// If we haven't already dropped the element, return it in an option. - /// - /// Clears the count so it won't be dropped again later. - #[inline] - fn take_element(&mut self) -> Option { - if self.count > 0 { - self.count = 0; - // SAFETY: We just set count to zero so it won't be dropped again, - // and it used to be non-zero so it hasn't already been dropped. - unsafe { Some(ManuallyDrop::take(&mut self.element)) } - } else { - None - } - } -} - -#[unstable(feature = "iter_repeat_n", issue = "104434")] -impl Drop for RepeatN { - fn drop(&mut self) { - self.take_element(); - } -} - -#[unstable(feature = "iter_repeat_n", issue = "104434")] -impl Iterator for RepeatN { - type Item = A; - - #[inline] - fn next(&mut self) -> Option { - if self.count == 0 { - return None; - } - - self.count -= 1; - Some(if self.count == 0 { - // SAFETY: the check above ensured that the count used to be non-zero, - // so element hasn't been dropped yet, and we just lowered the count to - // zero so it won't be dropped later, and thus it's okay to take it here. - unsafe { ManuallyDrop::take(&mut self.element) } - } else { - A::clone(&self.element) - }) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let len = self.len(); - (len, Some(len)) - } - - #[inline] - fn advance_by(&mut self, skip: usize) -> Result<(), NonZero> { - let len = self.count; - - if skip >= len { - self.take_element(); - } - - if skip > len { - // SAFETY: we just checked that the difference is positive - Err(unsafe { NonZero::new_unchecked(skip - len) }) - } else { - self.count = len - skip; - Ok(()) - } - } - - #[inline] - fn last(mut self) -> Option { - self.take_element() - } - - #[inline] - fn count(self) -> usize { - self.len() - } -} - -#[unstable(feature = "iter_repeat_n", issue = "104434")] -impl ExactSizeIterator for RepeatN { - fn len(&self) -> usize { - self.count - } -} - -#[unstable(feature = "iter_repeat_n", issue = "104434")] -impl DoubleEndedIterator for RepeatN { - #[inline] - fn next_back(&mut self) -> Option { - self.next() - } - - #[inline] - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - self.advance_by(n) - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option { - self.nth(n) - } -} - -#[unstable(feature = "iter_repeat_n", issue = "104434")] -impl FusedIterator for RepeatN {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for RepeatN {} diff --git a/library/core/src/iter/sources/repeat_with.rs b/library/core/src/iter/sources/repeat_with.rs deleted file mode 100644 index d3cd74a448375..0000000000000 --- a/library/core/src/iter/sources/repeat_with.rs +++ /dev/null @@ -1,122 +0,0 @@ -use crate::fmt; -use crate::iter::{FusedIterator, TrustedLen}; -use crate::ops::Try; - -/// Creates a new iterator that repeats elements of type `A` endlessly by -/// applying the provided closure, the repeater, `F: FnMut() -> A`. -/// -/// The `repeat_with()` function calls the repeater over and over again. -/// -/// Infinite iterators like `repeat_with()` are often used with adapters like -/// [`Iterator::take()`], in order to make them finite. -/// -/// If the element type of the iterator you need implements [`Clone`], and -/// it is OK to keep the source element in memory, you should instead use -/// the [`repeat()`] function. -/// -/// An iterator produced by `repeat_with()` is not a [`DoubleEndedIterator`]. -/// If you need `repeat_with()` to return a [`DoubleEndedIterator`], -/// please open a GitHub issue explaining your use case. -/// -/// [`repeat()`]: crate::iter::repeat -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// use std::iter; -/// -/// // let's assume we have some value of a type that is not `Clone` -/// // or which we don't want to have in memory just yet because it is expensive: -/// #[derive(PartialEq, Debug)] -/// struct Expensive; -/// -/// // a particular value forever: -/// let mut things = iter::repeat_with(|| Expensive); -/// -/// assert_eq!(Some(Expensive), things.next()); -/// assert_eq!(Some(Expensive), things.next()); -/// assert_eq!(Some(Expensive), things.next()); -/// assert_eq!(Some(Expensive), things.next()); -/// assert_eq!(Some(Expensive), things.next()); -/// ``` -/// -/// Using mutation and going finite: -/// -/// ```rust -/// use std::iter; -/// -/// // From the zeroth to the third power of two: -/// let mut curr = 1; -/// let mut pow2 = iter::repeat_with(|| { let tmp = curr; curr *= 2; tmp }) -/// .take(4); -/// -/// assert_eq!(Some(1), pow2.next()); -/// assert_eq!(Some(2), pow2.next()); -/// assert_eq!(Some(4), pow2.next()); -/// assert_eq!(Some(8), pow2.next()); -/// -/// // ... and now we're done -/// assert_eq!(None, pow2.next()); -/// ``` -#[inline] -#[stable(feature = "iterator_repeat_with", since = "1.28.0")] -pub fn repeat_with A>(repeater: F) -> RepeatWith { - RepeatWith { repeater } -} - -/// An iterator that repeats elements of type `A` endlessly by -/// applying the provided closure `F: FnMut() -> A`. -/// -/// This `struct` is created by the [`repeat_with()`] function. -/// See its documentation for more. -#[derive(Copy, Clone)] -#[stable(feature = "iterator_repeat_with", since = "1.28.0")] -pub struct RepeatWith { - repeater: F, -} - -#[stable(feature = "iterator_repeat_with_debug", since = "1.68.0")] -impl fmt::Debug for RepeatWith { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("RepeatWith").finish_non_exhaustive() - } -} - -#[stable(feature = "iterator_repeat_with", since = "1.28.0")] -impl A> Iterator for RepeatWith { - type Item = A; - - #[inline] - fn next(&mut self) -> Option { - Some((self.repeater)()) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - (usize::MAX, None) - } - - #[inline] - fn try_fold(&mut self, mut init: Acc, mut fold: Fold) -> R - where - Fold: FnMut(Acc, Self::Item) -> R, - R: Try, - { - // This override isn't strictly needed, but avoids the need to optimize - // away the `next`-always-returns-`Some` and emphasizes that the `?` - // is the only way to exit the loop. - - loop { - let item = (self.repeater)(); - init = fold(init, item)?; - } - } -} - -#[stable(feature = "iterator_repeat_with", since = "1.28.0")] -impl A> FusedIterator for RepeatWith {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl A> TrustedLen for RepeatWith {} diff --git a/library/core/src/iter/sources/successors.rs b/library/core/src/iter/sources/successors.rs deleted file mode 100644 index 7f7b2c7756628..0000000000000 --- a/library/core/src/iter/sources/successors.rs +++ /dev/null @@ -1,66 +0,0 @@ -use crate::{fmt, iter::FusedIterator}; - -/// Creates a new iterator where each successive item is computed based on the preceding one. -/// -/// The iterator starts with the given first item (if any) -/// and calls the given `FnMut(&T) -> Option` closure to compute each item’s successor. -/// -/// ``` -/// use std::iter::successors; -/// -/// let powers_of_10 = successors(Some(1_u16), |n| n.checked_mul(10)); -/// assert_eq!(powers_of_10.collect::>(), &[1, 10, 100, 1_000, 10_000]); -/// ``` -#[stable(feature = "iter_successors", since = "1.34.0")] -pub fn successors(first: Option, succ: F) -> Successors -where - F: FnMut(&T) -> Option, -{ - // If this function returned `impl Iterator` - // it could be based on `from_fn` and not need a dedicated type. - // However having a named `Successors` type allows it to be `Clone` when `T` and `F` are. - Successors { next: first, succ } -} - -/// A new iterator where each successive item is computed based on the preceding one. -/// -/// This `struct` is created by the [`iter::successors()`] function. -/// See its documentation for more. -/// -/// [`iter::successors()`]: successors -#[derive(Clone)] -#[stable(feature = "iter_successors", since = "1.34.0")] -pub struct Successors { - next: Option, - succ: F, -} - -#[stable(feature = "iter_successors", since = "1.34.0")] -impl Iterator for Successors -where - F: FnMut(&T) -> Option, -{ - type Item = T; - - #[inline] - fn next(&mut self) -> Option { - let item = self.next.take()?; - self.next = (self.succ)(&item); - Some(item) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - if self.next.is_some() { (1, None) } else { (0, Some(0)) } - } -} - -#[stable(feature = "iter_successors", since = "1.34.0")] -impl FusedIterator for Successors where F: FnMut(&T) -> Option {} - -#[stable(feature = "iter_successors", since = "1.34.0")] -impl fmt::Debug for Successors { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Successors").field("next", &self.next).finish() - } -} diff --git a/library/core/src/iter/traits/accum.rs b/library/core/src/iter/traits/accum.rs deleted file mode 100644 index f9c7eb8f9383e..0000000000000 --- a/library/core/src/iter/traits/accum.rs +++ /dev/null @@ -1,271 +0,0 @@ -use crate::iter; -use crate::num::Wrapping; - -/// Trait to represent types that can be created by summing up an iterator. -/// -/// This trait is used to implement [`Iterator::sum()`]. Types which implement -/// this trait can be generated by using the [`sum()`] method on an iterator. -/// Like [`FromIterator`], this trait should rarely be called directly. -/// -/// [`sum()`]: Iterator::sum -/// [`FromIterator`]: iter::FromIterator -#[stable(feature = "iter_arith_traits", since = "1.12.0")] -#[rustc_on_unimplemented( - message = "a value of type `{Self}` cannot be made by summing an iterator over elements of type `{A}`", - label = "value of type `{Self}` cannot be made by summing a `std::iter::Iterator`" -)] -pub trait Sum: Sized { - /// Method which takes an iterator and generates `Self` from the elements by - /// "summing up" the items. - #[stable(feature = "iter_arith_traits", since = "1.12.0")] - fn sum>(iter: I) -> Self; -} - -/// Trait to represent types that can be created by multiplying elements of an -/// iterator. -/// -/// This trait is used to implement [`Iterator::product()`]. Types which implement -/// this trait can be generated by using the [`product()`] method on an iterator. -/// Like [`FromIterator`], this trait should rarely be called directly. -/// -/// [`product()`]: Iterator::product -/// [`FromIterator`]: iter::FromIterator -#[stable(feature = "iter_arith_traits", since = "1.12.0")] -#[rustc_on_unimplemented( - message = "a value of type `{Self}` cannot be made by multiplying all elements of type `{A}` from an iterator", - label = "value of type `{Self}` cannot be made by multiplying all elements from a `std::iter::Iterator`" -)] -pub trait Product: Sized { - /// Method which takes an iterator and generates `Self` from the elements by - /// multiplying the items. - #[stable(feature = "iter_arith_traits", since = "1.12.0")] - fn product>(iter: I) -> Self; -} - -macro_rules! integer_sum_product { - (@impls $zero:expr, $one:expr, #[$attr:meta], $($a:ty)*) => ($( - #[$attr] - impl Sum for $a { - fn sum>(iter: I) -> Self { - iter.fold( - $zero, - #[rustc_inherit_overflow_checks] - |a, b| a + b, - ) - } - } - - #[$attr] - impl Product for $a { - fn product>(iter: I) -> Self { - iter.fold( - $one, - #[rustc_inherit_overflow_checks] - |a, b| a * b, - ) - } - } - - #[$attr] - impl<'a> Sum<&'a $a> for $a { - fn sum>(iter: I) -> Self { - iter.fold( - $zero, - #[rustc_inherit_overflow_checks] - |a, b| a + b, - ) - } - } - - #[$attr] - impl<'a> Product<&'a $a> for $a { - fn product>(iter: I) -> Self { - iter.fold( - $one, - #[rustc_inherit_overflow_checks] - |a, b| a * b, - ) - } - } - )*); - ($($a:ty)*) => ( - integer_sum_product!(@impls 0, 1, - #[stable(feature = "iter_arith_traits", since = "1.12.0")], - $($a)*); - integer_sum_product!(@impls Wrapping(0), Wrapping(1), - #[stable(feature = "wrapping_iter_arith", since = "1.14.0")], - $(Wrapping<$a>)*); - ); -} - -macro_rules! float_sum_product { - ($($a:ident)*) => ($( - #[stable(feature = "iter_arith_traits", since = "1.12.0")] - impl Sum for $a { - fn sum>(iter: I) -> Self { - iter.fold( - 0.0, - #[rustc_inherit_overflow_checks] - |a, b| a + b, - ) - } - } - - #[stable(feature = "iter_arith_traits", since = "1.12.0")] - impl Product for $a { - fn product>(iter: I) -> Self { - iter.fold( - 1.0, - #[rustc_inherit_overflow_checks] - |a, b| a * b, - ) - } - } - - #[stable(feature = "iter_arith_traits", since = "1.12.0")] - impl<'a> Sum<&'a $a> for $a { - fn sum>(iter: I) -> Self { - iter.fold( - 0.0, - #[rustc_inherit_overflow_checks] - |a, b| a + b, - ) - } - } - - #[stable(feature = "iter_arith_traits", since = "1.12.0")] - impl<'a> Product<&'a $a> for $a { - fn product>(iter: I) -> Self { - iter.fold( - 1.0, - #[rustc_inherit_overflow_checks] - |a, b| a * b, - ) - } - } - )*) -} - -integer_sum_product! { i8 i16 i32 i64 i128 isize u8 u16 u32 u64 u128 usize } -float_sum_product! { f32 f64 } - -#[stable(feature = "iter_arith_traits_result", since = "1.16.0")] -impl Sum> for Result -where - T: Sum, -{ - /// Takes each element in the [`Iterator`]: if it is an [`Err`], no further - /// elements are taken, and the [`Err`] is returned. Should no [`Err`] - /// occur, the sum of all elements is returned. - /// - /// # Examples - /// - /// This sums up every integer in a vector, rejecting the sum if a negative - /// element is encountered: - /// - /// ``` - /// let f = |&x: &i32| if x < 0 { Err("Negative element found") } else { Ok(x) }; - /// let v = vec![1, 2]; - /// let res: Result = v.iter().map(f).sum(); - /// assert_eq!(res, Ok(3)); - /// let v = vec![1, -2]; - /// let res: Result = v.iter().map(f).sum(); - /// assert_eq!(res, Err("Negative element found")); - /// ``` - fn sum(iter: I) -> Result - where - I: Iterator>, - { - iter::try_process(iter, |i| i.sum()) - } -} - -#[stable(feature = "iter_arith_traits_result", since = "1.16.0")] -impl Product> for Result -where - T: Product, -{ - /// Takes each element in the [`Iterator`]: if it is an [`Err`], no further - /// elements are taken, and the [`Err`] is returned. Should no [`Err`] - /// occur, the product of all elements is returned. - /// - /// # Examples - /// - /// This multiplies each number in a vector of strings, - /// if a string could not be parsed the operation returns `Err`: - /// - /// ``` - /// let nums = vec!["5", "10", "1", "2"]; - /// let total: Result = nums.iter().map(|w| w.parse::()).product(); - /// assert_eq!(total, Ok(100)); - /// let nums = vec!["5", "10", "one", "2"]; - /// let total: Result = nums.iter().map(|w| w.parse::()).product(); - /// assert!(total.is_err()); - /// ``` - fn product(iter: I) -> Result - where - I: Iterator>, - { - iter::try_process(iter, |i| i.product()) - } -} - -#[stable(feature = "iter_arith_traits_option", since = "1.37.0")] -impl Sum> for Option -where - T: Sum, -{ - /// Takes each element in the [`Iterator`]: if it is a [`None`], no further - /// elements are taken, and the [`None`] is returned. Should no [`None`] - /// occur, the sum of all elements is returned. - /// - /// # Examples - /// - /// This sums up the position of the character 'a' in a vector of strings, - /// if a word did not have the character 'a' the operation returns `None`: - /// - /// ``` - /// let words = vec!["have", "a", "great", "day"]; - /// let total: Option = words.iter().map(|w| w.find('a')).sum(); - /// assert_eq!(total, Some(5)); - /// let words = vec!["have", "a", "good", "day"]; - /// let total: Option = words.iter().map(|w| w.find('a')).sum(); - /// assert_eq!(total, None); - /// ``` - fn sum(iter: I) -> Option - where - I: Iterator>, - { - iter::try_process(iter, |i| i.sum()) - } -} - -#[stable(feature = "iter_arith_traits_option", since = "1.37.0")] -impl Product> for Option -where - T: Product, -{ - /// Takes each element in the [`Iterator`]: if it is a [`None`], no further - /// elements are taken, and the [`None`] is returned. Should no [`None`] - /// occur, the product of all elements is returned. - /// - /// # Examples - /// - /// This multiplies each number in a vector of strings, - /// if a string could not be parsed the operation returns `None`: - /// - /// ``` - /// let nums = vec!["5", "10", "1", "2"]; - /// let total: Option = nums.iter().map(|w| w.parse::().ok()).product(); - /// assert_eq!(total, Some(100)); - /// let nums = vec!["5", "10", "one", "2"]; - /// let total: Option = nums.iter().map(|w| w.parse::().ok()).product(); - /// assert_eq!(total, None); - /// ``` - fn product(iter: I) -> Option - where - I: Iterator>, - { - iter::try_process(iter, |i| i.product()) - } -} diff --git a/library/core/src/iter/traits/collect.rs b/library/core/src/iter/traits/collect.rs deleted file mode 100644 index d9d860c7b6cba..0000000000000 --- a/library/core/src/iter/traits/collect.rs +++ /dev/null @@ -1,532 +0,0 @@ -/// Conversion from an [`Iterator`]. -/// -/// By implementing `FromIterator` for a type, you define how it will be -/// created from an iterator. This is common for types which describe a -/// collection of some kind. -/// -/// If you want to create a collection from the contents of an iterator, the -/// [`Iterator::collect()`] method is preferred. However, when you need to -/// specify the container type, [`FromIterator::from_iter()`] can be more -/// readable than using a turbofish (e.g. `::>()`). See the -/// [`Iterator::collect()`] documentation for more examples of its use. -/// -/// See also: [`IntoIterator`]. -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// let five_fives = std::iter::repeat(5).take(5); -/// -/// let v = Vec::from_iter(five_fives); -/// -/// assert_eq!(v, vec![5, 5, 5, 5, 5]); -/// ``` -/// -/// Using [`Iterator::collect()`] to implicitly use `FromIterator`: -/// -/// ``` -/// let five_fives = std::iter::repeat(5).take(5); -/// -/// let v: Vec = five_fives.collect(); -/// -/// assert_eq!(v, vec![5, 5, 5, 5, 5]); -/// ``` -/// -/// Using [`FromIterator::from_iter()`] as a more readable alternative to -/// [`Iterator::collect()`]: -/// -/// ``` -/// use std::collections::VecDeque; -/// let first = (0..10).collect::>(); -/// let second = VecDeque::from_iter(0..10); -/// -/// assert_eq!(first, second); -/// ``` -/// -/// Implementing `FromIterator` for your type: -/// -/// ``` -/// // A sample collection, that's just a wrapper over Vec -/// #[derive(Debug)] -/// struct MyCollection(Vec); -/// -/// // Let's give it some methods so we can create one and add things -/// // to it. -/// impl MyCollection { -/// fn new() -> MyCollection { -/// MyCollection(Vec::new()) -/// } -/// -/// fn add(&mut self, elem: i32) { -/// self.0.push(elem); -/// } -/// } -/// -/// // and we'll implement FromIterator -/// impl FromIterator for MyCollection { -/// fn from_iter>(iter: I) -> Self { -/// let mut c = MyCollection::new(); -/// -/// for i in iter { -/// c.add(i); -/// } -/// -/// c -/// } -/// } -/// -/// // Now we can make a new iterator... -/// let iter = (0..5).into_iter(); -/// -/// // ... and make a MyCollection out of it -/// let c = MyCollection::from_iter(iter); -/// -/// assert_eq!(c.0, vec![0, 1, 2, 3, 4]); -/// -/// // collect works too! -/// -/// let iter = (0..5).into_iter(); -/// let c: MyCollection = iter.collect(); -/// -/// assert_eq!(c.0, vec![0, 1, 2, 3, 4]); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_on_unimplemented( - on( - _Self = "&[{A}]", - message = "a slice of type `{Self}` cannot be built since we need to store the elements somewhere", - label = "try explicitly collecting into a `Vec<{A}>`", - ), - on( - all(A = "{integer}", any(_Self = "&[{integral}]",)), - message = "a slice of type `{Self}` cannot be built since we need to store the elements somewhere", - label = "try explicitly collecting into a `Vec<{A}>`", - ), - on( - _Self = "[{A}]", - message = "a slice of type `{Self}` cannot be built since `{Self}` has no definite size", - label = "try explicitly collecting into a `Vec<{A}>`", - ), - on( - all(A = "{integer}", any(_Self = "[{integral}]",)), - message = "a slice of type `{Self}` cannot be built since `{Self}` has no definite size", - label = "try explicitly collecting into a `Vec<{A}>`", - ), - on( - _Self = "[{A}; _]", - message = "an array of type `{Self}` cannot be built directly from an iterator", - label = "try collecting into a `Vec<{A}>`, then using `.try_into()`", - ), - on( - all(A = "{integer}", any(_Self = "[{integral}; _]",)), - message = "an array of type `{Self}` cannot be built directly from an iterator", - label = "try collecting into a `Vec<{A}>`, then using `.try_into()`", - ), - message = "a value of type `{Self}` cannot be built from an iterator \ - over elements of type `{A}`", - label = "value of type `{Self}` cannot be built from `std::iter::Iterator`" -)] -#[rustc_diagnostic_item = "FromIterator"] -pub trait FromIterator: Sized { - /// Creates a value from an iterator. - /// - /// See the [module-level documentation] for more. - /// - /// [module-level documentation]: crate::iter - /// - /// # Examples - /// - /// ``` - /// let five_fives = std::iter::repeat(5).take(5); - /// - /// let v = Vec::from_iter(five_fives); - /// - /// assert_eq!(v, vec![5, 5, 5, 5, 5]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_diagnostic_item = "from_iter_fn"] - fn from_iter>(iter: T) -> Self; -} - -/// This implementation turns an iterator of tuples into a tuple of types which implement -/// [`Default`] and [`Extend`]. -/// -/// This is similar to [`Iterator::unzip`], but is also composable with other [`FromIterator`] -/// implementations: -/// -/// ```rust -/// # fn main() -> Result<(), core::num::ParseIntError> { -/// let string = "1,2,123,4"; -/// -/// let (numbers, lengths): (Vec<_>, Vec<_>) = string -/// .split(',') -/// .map(|s| s.parse().map(|n: u32| (n, s.len()))) -/// .collect::>()?; -/// -/// assert_eq!(numbers, [1, 2, 123, 4]); -/// assert_eq!(lengths, [1, 1, 3, 1]); -/// # Ok(()) } -/// ``` -#[stable(feature = "from_iterator_for_tuple", since = "1.79.0")] -impl FromIterator<(AE, BE)> for (A, B) -where - A: Default + Extend, - B: Default + Extend, -{ - fn from_iter>(iter: I) -> Self { - let mut res = <(A, B)>::default(); - res.extend(iter); - - res - } -} - -/// Conversion into an [`Iterator`]. -/// -/// By implementing `IntoIterator` for a type, you define how it will be -/// converted to an iterator. This is common for types which describe a -/// collection of some kind. -/// -/// One benefit of implementing `IntoIterator` is that your type will [work -/// with Rust's `for` loop syntax](crate::iter#for-loops-and-intoiterator). -/// -/// See also: [`FromIterator`]. -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// let v = [1, 2, 3]; -/// let mut iter = v.into_iter(); -/// -/// assert_eq!(Some(1), iter.next()); -/// assert_eq!(Some(2), iter.next()); -/// assert_eq!(Some(3), iter.next()); -/// assert_eq!(None, iter.next()); -/// ``` -/// Implementing `IntoIterator` for your type: -/// -/// ``` -/// // A sample collection, that's just a wrapper over Vec -/// #[derive(Debug)] -/// struct MyCollection(Vec); -/// -/// // Let's give it some methods so we can create one and add things -/// // to it. -/// impl MyCollection { -/// fn new() -> MyCollection { -/// MyCollection(Vec::new()) -/// } -/// -/// fn add(&mut self, elem: i32) { -/// self.0.push(elem); -/// } -/// } -/// -/// // and we'll implement IntoIterator -/// impl IntoIterator for MyCollection { -/// type Item = i32; -/// type IntoIter = std::vec::IntoIter; -/// -/// fn into_iter(self) -> Self::IntoIter { -/// self.0.into_iter() -/// } -/// } -/// -/// // Now we can make a new collection... -/// let mut c = MyCollection::new(); -/// -/// // ... add some stuff to it ... -/// c.add(0); -/// c.add(1); -/// c.add(2); -/// -/// // ... and then turn it into an Iterator: -/// for (i, n) in c.into_iter().enumerate() { -/// assert_eq!(i as i32, n); -/// } -/// ``` -/// -/// It is common to use `IntoIterator` as a trait bound. This allows -/// the input collection type to change, so long as it is still an -/// iterator. Additional bounds can be specified by restricting on -/// `Item`: -/// -/// ```rust -/// fn collect_as_strings(collection: T) -> Vec -/// where -/// T: IntoIterator, -/// T::Item: std::fmt::Debug, -/// { -/// collection -/// .into_iter() -/// .map(|item| format!("{item:?}")) -/// .collect() -/// } -/// ``` -#[rustc_diagnostic_item = "IntoIterator"] -#[rustc_on_unimplemented( - on( - _Self = "core::ops::range::RangeTo", - label = "if you meant to iterate until a value, add a starting value", - note = "`..end` is a `RangeTo`, which cannot be iterated on; you might have meant to have a \ - bounded `Range`: `0..end`" - ), - on( - _Self = "core::ops::range::RangeToInclusive", - label = "if you meant to iterate until a value (including it), add a starting value", - note = "`..=end` is a `RangeToInclusive`, which cannot be iterated on; you might have meant \ - to have a bounded `RangeInclusive`: `0..=end`" - ), - on( - _Self = "[]", - label = "`{Self}` is not an iterator; try calling `.into_iter()` or `.iter()`" - ), - on(_Self = "&[]", label = "`{Self}` is not an iterator; try calling `.iter()`"), - on( - _Self = "alloc::vec::Vec", - label = "`{Self}` is not an iterator; try calling `.into_iter()` or `.iter()`" - ), - on( - _Self = "&str", - label = "`{Self}` is not an iterator; try calling `.chars()` or `.bytes()`" - ), - on( - _Self = "alloc::string::String", - label = "`{Self}` is not an iterator; try calling `.chars()` or `.bytes()`" - ), - on( - _Self = "{integral}", - note = "if you want to iterate between `start` until a value `end`, use the exclusive range \ - syntax `start..end` or the inclusive range syntax `start..=end`" - ), - on( - _Self = "{float}", - note = "if you want to iterate between `start` until a value `end`, use the exclusive range \ - syntax `start..end` or the inclusive range syntax `start..=end`" - ), - label = "`{Self}` is not an iterator", - message = "`{Self}` is not an iterator" -)] -#[cfg_attr(bootstrap, rustc_skip_array_during_method_dispatch)] -#[cfg_attr(not(bootstrap), rustc_skip_during_method_dispatch(array, boxed_slice))] -#[stable(feature = "rust1", since = "1.0.0")] -pub trait IntoIterator { - /// The type of the elements being iterated over. - #[stable(feature = "rust1", since = "1.0.0")] - type Item; - - /// Which kind of iterator are we turning this into? - #[stable(feature = "rust1", since = "1.0.0")] - type IntoIter: Iterator; - - /// Creates an iterator from a value. - /// - /// See the [module-level documentation] for more. - /// - /// [module-level documentation]: crate::iter - /// - /// # Examples - /// - /// ``` - /// let v = [1, 2, 3]; - /// let mut iter = v.into_iter(); - /// - /// assert_eq!(Some(1), iter.next()); - /// assert_eq!(Some(2), iter.next()); - /// assert_eq!(Some(3), iter.next()); - /// assert_eq!(None, iter.next()); - /// ``` - #[lang = "into_iter"] - #[stable(feature = "rust1", since = "1.0.0")] - fn into_iter(self) -> Self::IntoIter; -} - -#[rustc_const_unstable(feature = "const_intoiterator_identity", issue = "90603")] -#[stable(feature = "rust1", since = "1.0.0")] -impl IntoIterator for I { - type Item = I::Item; - type IntoIter = I; - - #[inline] - fn into_iter(self) -> I { - self - } -} - -/// Extend a collection with the contents of an iterator. -/// -/// Iterators produce a series of values, and collections can also be thought -/// of as a series of values. The `Extend` trait bridges this gap, allowing you -/// to extend a collection by including the contents of that iterator. When -/// extending a collection with an already existing key, that entry is updated -/// or, in the case of collections that permit multiple entries with equal -/// keys, that entry is inserted. -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// // You can extend a String with some chars: -/// let mut message = String::from("The first three letters are: "); -/// -/// message.extend(&['a', 'b', 'c']); -/// -/// assert_eq!("abc", &message[29..32]); -/// ``` -/// -/// Implementing `Extend`: -/// -/// ``` -/// // A sample collection, that's just a wrapper over Vec -/// #[derive(Debug)] -/// struct MyCollection(Vec); -/// -/// // Let's give it some methods so we can create one and add things -/// // to it. -/// impl MyCollection { -/// fn new() -> MyCollection { -/// MyCollection(Vec::new()) -/// } -/// -/// fn add(&mut self, elem: i32) { -/// self.0.push(elem); -/// } -/// } -/// -/// // since MyCollection has a list of i32s, we implement Extend for i32 -/// impl Extend for MyCollection { -/// -/// // This is a bit simpler with the concrete type signature: we can call -/// // extend on anything which can be turned into an Iterator which gives -/// // us i32s. Because we need i32s to put into MyCollection. -/// fn extend>(&mut self, iter: T) { -/// -/// // The implementation is very straightforward: loop through the -/// // iterator, and add() each element to ourselves. -/// for elem in iter { -/// self.add(elem); -/// } -/// } -/// } -/// -/// let mut c = MyCollection::new(); -/// -/// c.add(5); -/// c.add(6); -/// c.add(7); -/// -/// // let's extend our collection with three more numbers -/// c.extend(vec![1, 2, 3]); -/// -/// // we've added these elements onto the end -/// assert_eq!("MyCollection([5, 6, 7, 1, 2, 3])", format!("{c:?}")); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub trait Extend { - /// Extends a collection with the contents of an iterator. - /// - /// As this is the only required method for this trait, the [trait-level] docs - /// contain more details. - /// - /// [trait-level]: Extend - /// - /// # Examples - /// - /// ``` - /// // You can extend a String with some chars: - /// let mut message = String::from("abc"); - /// - /// message.extend(['d', 'e', 'f'].iter()); - /// - /// assert_eq!("abcdef", &message); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn extend>(&mut self, iter: T); - - /// Extends a collection with exactly one element. - #[unstable(feature = "extend_one", issue = "72631")] - fn extend_one(&mut self, item: A) { - self.extend(Some(item)); - } - - /// Reserves capacity in a collection for the given number of additional elements. - /// - /// The default implementation does nothing. - #[unstable(feature = "extend_one", issue = "72631")] - fn extend_reserve(&mut self, additional: usize) { - let _ = additional; - } -} - -#[stable(feature = "extend_for_unit", since = "1.28.0")] -impl Extend<()> for () { - fn extend>(&mut self, iter: T) { - iter.into_iter().for_each(drop) - } - fn extend_one(&mut self, _item: ()) {} -} - -#[stable(feature = "extend_for_tuple", since = "1.56.0")] -impl Extend<(A, B)> for (ExtendA, ExtendB) -where - ExtendA: Extend, - ExtendB: Extend, -{ - /// Allows to `extend` a tuple of collections that also implement `Extend`. - /// - /// See also: [`Iterator::unzip`] - /// - /// # Examples - /// ``` - /// let mut tuple = (vec![0], vec![1]); - /// tuple.extend([(2, 3), (4, 5), (6, 7)]); - /// assert_eq!(tuple.0, [0, 2, 4, 6]); - /// assert_eq!(tuple.1, [1, 3, 5, 7]); - /// - /// // also allows for arbitrarily nested tuples as elements - /// let mut nested_tuple = (vec![1], (vec![2], vec![3])); - /// nested_tuple.extend([(4, (5, 6)), (7, (8, 9))]); - /// - /// let (a, (b, c)) = nested_tuple; - /// assert_eq!(a, [1, 4, 7]); - /// assert_eq!(b, [2, 5, 8]); - /// assert_eq!(c, [3, 6, 9]); - /// ``` - fn extend>(&mut self, into_iter: T) { - let (a, b) = self; - let iter = into_iter.into_iter(); - - fn extend<'a, A, B>( - a: &'a mut impl Extend, - b: &'a mut impl Extend, - ) -> impl FnMut((), (A, B)) + 'a { - move |(), (t, u)| { - a.extend_one(t); - b.extend_one(u); - } - } - - let (lower_bound, _) = iter.size_hint(); - if lower_bound > 0 { - a.extend_reserve(lower_bound); - b.extend_reserve(lower_bound); - } - - iter.fold((), extend(a, b)); - } - - fn extend_one(&mut self, item: (A, B)) { - self.0.extend_one(item.0); - self.1.extend_one(item.1); - } - - fn extend_reserve(&mut self, additional: usize) { - self.0.extend_reserve(additional); - self.1.extend_reserve(additional); - } -} diff --git a/library/core/src/iter/traits/double_ended.rs b/library/core/src/iter/traits/double_ended.rs deleted file mode 100644 index 3b12678572841..0000000000000 --- a/library/core/src/iter/traits/double_ended.rs +++ /dev/null @@ -1,445 +0,0 @@ -use crate::num::NonZero; -use crate::ops::{ControlFlow, Try}; - -/// An iterator able to yield elements from both ends. -/// -/// Something that implements `DoubleEndedIterator` has one extra capability -/// over something that implements [`Iterator`]: the ability to also take -/// `Item`s from the back, as well as the front. -/// -/// It is important to note that both back and forth work on the same range, -/// and do not cross: iteration is over when they meet in the middle. -/// -/// In a similar fashion to the [`Iterator`] protocol, once a -/// `DoubleEndedIterator` returns [`None`] from a [`next_back()`], calling it -/// again may or may not ever return [`Some`] again. [`next()`] and -/// [`next_back()`] are interchangeable for this purpose. -/// -/// [`next_back()`]: DoubleEndedIterator::next_back -/// [`next()`]: Iterator::next -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// let numbers = vec![1, 2, 3, 4, 5, 6]; -/// -/// let mut iter = numbers.iter(); -/// -/// assert_eq!(Some(&1), iter.next()); -/// assert_eq!(Some(&6), iter.next_back()); -/// assert_eq!(Some(&5), iter.next_back()); -/// assert_eq!(Some(&2), iter.next()); -/// assert_eq!(Some(&3), iter.next()); -/// assert_eq!(Some(&4), iter.next()); -/// assert_eq!(None, iter.next()); -/// assert_eq!(None, iter.next_back()); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "DoubleEndedIterator")] -pub trait DoubleEndedIterator: Iterator { - /// Removes and returns an element from the end of the iterator. - /// - /// Returns `None` when there are no more elements. - /// - /// The [trait-level] docs contain more details. - /// - /// [trait-level]: DoubleEndedIterator - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let numbers = vec![1, 2, 3, 4, 5, 6]; - /// - /// let mut iter = numbers.iter(); - /// - /// assert_eq!(Some(&1), iter.next()); - /// assert_eq!(Some(&6), iter.next_back()); - /// assert_eq!(Some(&5), iter.next_back()); - /// assert_eq!(Some(&2), iter.next()); - /// assert_eq!(Some(&3), iter.next()); - /// assert_eq!(Some(&4), iter.next()); - /// assert_eq!(None, iter.next()); - /// assert_eq!(None, iter.next_back()); - /// ``` - /// - /// # Remarks - /// - /// The elements yielded by `DoubleEndedIterator`'s methods may differ from - /// the ones yielded by [`Iterator`]'s methods: - /// - /// ``` - /// let vec = vec![(1, 'a'), (1, 'b'), (1, 'c'), (2, 'a'), (2, 'b')]; - /// let uniq_by_fst_comp = || { - /// let mut seen = std::collections::HashSet::new(); - /// vec.iter().copied().filter(move |x| seen.insert(x.0)) - /// }; - /// - /// assert_eq!(uniq_by_fst_comp().last(), Some((2, 'a'))); - /// assert_eq!(uniq_by_fst_comp().next_back(), Some((2, 'b'))); - /// - /// assert_eq!( - /// uniq_by_fst_comp().fold(vec![], |mut v, x| {v.push(x); v}), - /// vec![(1, 'a'), (2, 'a')] - /// ); - /// assert_eq!( - /// uniq_by_fst_comp().rfold(vec![], |mut v, x| {v.push(x); v}), - /// vec![(2, 'b'), (1, 'c')] - /// ); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn next_back(&mut self) -> Option; - - /// Advances the iterator from the back by `n` elements. - /// - /// `advance_back_by` is the reverse version of [`advance_by`]. This method will - /// eagerly skip `n` elements starting from the back by calling [`next_back`] up - /// to `n` times until [`None`] is encountered. - /// - /// `advance_back_by(n)` will return `Ok(())` if the iterator successfully advances by - /// `n` elements, or a `Err(NonZero)` with value `k` if [`None`] is encountered, where `k` - /// is remaining number of steps that could not be advanced because the iterator ran out. - /// If `self` is empty and `n` is non-zero, then this returns `Err(n)`. - /// Otherwise, `k` is always less than `n`. - /// - /// Calling `advance_back_by(0)` can do meaningful work, for example [`Flatten`] can advance its - /// outer iterator until it finds an inner iterator that is not empty, which then often - /// allows it to return a more accurate `size_hint()` than in its initial state. - /// - /// [`advance_by`]: Iterator::advance_by - /// [`Flatten`]: crate::iter::Flatten - /// [`next_back`]: DoubleEndedIterator::next_back - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(iter_advance_by)] - /// - /// use std::num::NonZero; - /// - /// let a = [3, 4, 5, 6]; - /// let mut iter = a.iter(); - /// - /// assert_eq!(iter.advance_back_by(2), Ok(())); - /// assert_eq!(iter.next_back(), Some(&4)); - /// assert_eq!(iter.advance_back_by(0), Ok(())); - /// assert_eq!(iter.advance_back_by(100), Err(NonZero::new(99).unwrap())); // only `&3` was skipped - /// ``` - /// - /// [`Ok(())`]: Ok - /// [`Err(k)`]: Err - #[inline] - #[unstable(feature = "iter_advance_by", reason = "recently added", issue = "77404")] - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - for i in 0..n { - if self.next_back().is_none() { - // SAFETY: `i` is always less than `n`. - return Err(unsafe { NonZero::new_unchecked(n - i) }); - } - } - Ok(()) - } - - /// Returns the `n`th element from the end of the iterator. - /// - /// This is essentially the reversed version of [`Iterator::nth()`]. - /// Although like most indexing operations, the count starts from zero, so - /// `nth_back(0)` returns the first value from the end, `nth_back(1)` the - /// second, and so on. - /// - /// Note that all elements between the end and the returned element will be - /// consumed, including the returned element. This also means that calling - /// `nth_back(0)` multiple times on the same iterator will return different - /// elements. - /// - /// `nth_back()` will return [`None`] if `n` is greater than or equal to the - /// length of the iterator. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = [1, 2, 3]; - /// assert_eq!(a.iter().nth_back(2), Some(&1)); - /// ``` - /// - /// Calling `nth_back()` multiple times doesn't rewind the iterator: - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// let mut iter = a.iter(); - /// - /// assert_eq!(iter.nth_back(1), Some(&2)); - /// assert_eq!(iter.nth_back(1), None); - /// ``` - /// - /// Returning `None` if there are less than `n + 1` elements: - /// - /// ``` - /// let a = [1, 2, 3]; - /// assert_eq!(a.iter().nth_back(10), None); - /// ``` - #[inline] - #[stable(feature = "iter_nth_back", since = "1.37.0")] - fn nth_back(&mut self, n: usize) -> Option { - if self.advance_back_by(n).is_err() { - return None; - } - self.next_back() - } - - /// This is the reverse version of [`Iterator::try_fold()`]: it takes - /// elements starting from the back of the iterator. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = ["1", "2", "3"]; - /// let sum = a.iter() - /// .map(|&s| s.parse::()) - /// .try_rfold(0, |acc, x| x.and_then(|y| Ok(acc + y))); - /// assert_eq!(sum, Ok(6)); - /// ``` - /// - /// Short-circuiting: - /// - /// ``` - /// let a = ["1", "rust", "3"]; - /// let mut it = a.iter(); - /// let sum = it - /// .by_ref() - /// .map(|&s| s.parse::()) - /// .try_rfold(0, |acc, x| x.and_then(|y| Ok(acc + y))); - /// assert!(sum.is_err()); - /// - /// // Because it short-circuited, the remaining elements are still - /// // available through the iterator. - /// assert_eq!(it.next_back(), Some(&"1")); - /// ``` - #[inline] - #[stable(feature = "iterator_try_fold", since = "1.27.0")] - fn try_rfold(&mut self, init: B, mut f: F) -> R - where - Self: Sized, - F: FnMut(B, Self::Item) -> R, - R: Try, - { - let mut accum = init; - while let Some(x) = self.next_back() { - accum = f(accum, x)?; - } - try { accum } - } - - /// An iterator method that reduces the iterator's elements to a single, - /// final value, starting from the back. - /// - /// This is the reverse version of [`Iterator::fold()`]: it takes elements - /// starting from the back of the iterator. - /// - /// `rfold()` takes two arguments: an initial value, and a closure with two - /// arguments: an 'accumulator', and an element. The closure returns the value that - /// the accumulator should have for the next iteration. - /// - /// The initial value is the value the accumulator will have on the first - /// call. - /// - /// After applying this closure to every element of the iterator, `rfold()` - /// returns the accumulator. - /// - /// This operation is sometimes called 'reduce' or 'inject'. - /// - /// Folding is useful whenever you have a collection of something, and want - /// to produce a single value from it. - /// - /// Note: `rfold()` combines elements in a *right-associative* fashion. For associative - /// operators like `+`, the order the elements are combined in is not important, but for non-associative - /// operators like `-` the order will affect the final result. - /// For a *left-associative* version of `rfold()`, see [`Iterator::fold()`]. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// // the sum of all of the elements of a - /// let sum = a.iter() - /// .rfold(0, |acc, &x| acc + x); - /// - /// assert_eq!(sum, 6); - /// ``` - /// - /// This example demonstrates the right-associative nature of `rfold()`: - /// it builds a string, starting with an initial value - /// and continuing with each element from the back until the front: - /// - /// ``` - /// let numbers = [1, 2, 3, 4, 5]; - /// - /// let zero = "0".to_string(); - /// - /// let result = numbers.iter().rfold(zero, |acc, &x| { - /// format!("({x} + {acc})") - /// }); - /// - /// assert_eq!(result, "(1 + (2 + (3 + (4 + (5 + 0)))))"); - /// ``` - #[doc(alias = "foldr")] - #[inline] - #[stable(feature = "iter_rfold", since = "1.27.0")] - fn rfold(mut self, init: B, mut f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - let mut accum = init; - while let Some(x) = self.next_back() { - accum = f(accum, x); - } - accum - } - - /// Searches for an element of an iterator from the back that satisfies a predicate. - /// - /// `rfind()` takes a closure that returns `true` or `false`. It applies - /// this closure to each element of the iterator, starting at the end, and if any - /// of them return `true`, then `rfind()` returns [`Some(element)`]. If they all return - /// `false`, it returns [`None`]. - /// - /// `rfind()` is short-circuiting; in other words, it will stop processing - /// as soon as the closure returns `true`. - /// - /// Because `rfind()` takes a reference, and many iterators iterate over - /// references, this leads to a possibly confusing situation where the - /// argument is a double reference. You can see this effect in the - /// examples below, with `&&x`. - /// - /// [`Some(element)`]: Some - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// assert_eq!(a.iter().rfind(|&&x| x == 2), Some(&2)); - /// - /// assert_eq!(a.iter().rfind(|&&x| x == 5), None); - /// ``` - /// - /// Stopping at the first `true`: - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// let mut iter = a.iter(); - /// - /// assert_eq!(iter.rfind(|&&x| x == 2), Some(&2)); - /// - /// // we can still use `iter`, as there are more elements. - /// assert_eq!(iter.next_back(), Some(&1)); - /// ``` - #[inline] - #[stable(feature = "iter_rfind", since = "1.27.0")] - fn rfind

(&mut self, predicate: P) -> Option - where - Self: Sized, - P: FnMut(&Self::Item) -> bool, - { - #[inline] - fn check(mut predicate: impl FnMut(&T) -> bool) -> impl FnMut((), T) -> ControlFlow { - move |(), x| { - if predicate(&x) { ControlFlow::Break(x) } else { ControlFlow::Continue(()) } - } - } - - self.try_rfold((), check(predicate)).break_value() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, I: DoubleEndedIterator + ?Sized> DoubleEndedIterator for &'a mut I { - fn next_back(&mut self) -> Option { - (**self).next_back() - } - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - (**self).advance_back_by(n) - } - fn nth_back(&mut self, n: usize) -> Option { - (**self).nth_back(n) - } - fn rfold(self, init: B, f: F) -> B - where - F: FnMut(B, Self::Item) -> B, - { - self.spec_rfold(init, f) - } - fn try_rfold(&mut self, init: B, f: F) -> R - where - F: FnMut(B, Self::Item) -> R, - R: Try, - { - self.spec_try_rfold(init, f) - } -} - -/// Helper trait to specialize `rfold` and `rtry_fold` for `&mut I where I: Sized` -trait DoubleEndedIteratorRefSpec: DoubleEndedIterator { - fn spec_rfold(self, init: B, f: F) -> B - where - F: FnMut(B, Self::Item) -> B; - - fn spec_try_rfold(&mut self, init: B, f: F) -> R - where - F: FnMut(B, Self::Item) -> R, - R: Try; -} - -impl DoubleEndedIteratorRefSpec for &mut I { - default fn spec_rfold(self, init: B, mut f: F) -> B - where - F: FnMut(B, Self::Item) -> B, - { - let mut accum = init; - while let Some(x) = self.next_back() { - accum = f(accum, x); - } - accum - } - - default fn spec_try_rfold(&mut self, init: B, mut f: F) -> R - where - F: FnMut(B, Self::Item) -> R, - R: Try, - { - let mut accum = init; - while let Some(x) = self.next_back() { - accum = f(accum, x)?; - } - try { accum } - } -} - -impl DoubleEndedIteratorRefSpec for &mut I { - impl_fold_via_try_fold! { spec_rfold -> spec_try_rfold } - - fn spec_try_rfold(&mut self, init: B, f: F) -> R - where - F: FnMut(B, Self::Item) -> R, - R: Try, - { - (**self).try_rfold(init, f) - } -} diff --git a/library/core/src/iter/traits/exact_size.rs b/library/core/src/iter/traits/exact_size.rs deleted file mode 100644 index 908830d8a9514..0000000000000 --- a/library/core/src/iter/traits/exact_size.rs +++ /dev/null @@ -1,161 +0,0 @@ -/// An iterator that knows its exact length. -/// -/// Many [`Iterator`]s don't know how many times they will iterate, but some do. -/// If an iterator knows how many times it can iterate, providing access to -/// that information can be useful. For example, if you want to iterate -/// backwards, a good start is to know where the end is. -/// -/// When implementing an `ExactSizeIterator`, you must also implement -/// [`Iterator`]. When doing so, the implementation of [`Iterator::size_hint`] -/// *must* return the exact size of the iterator. -/// -/// The [`len`] method has a default implementation, so you usually shouldn't -/// implement it. However, you may be able to provide a more performant -/// implementation than the default, so overriding it in this case makes sense. -/// -/// Note that this trait is a safe trait and as such does *not* and *cannot* -/// guarantee that the returned length is correct. This means that `unsafe` -/// code **must not** rely on the correctness of [`Iterator::size_hint`]. The -/// unstable and unsafe [`TrustedLen`](super::marker::TrustedLen) trait gives -/// this additional guarantee. -/// -/// [`len`]: ExactSizeIterator::len -/// -/// # When *shouldn't* an adapter be `ExactSizeIterator`? -/// -/// If an adapter makes an iterator *longer*, then it's usually incorrect for -/// that adapter to implement `ExactSizeIterator`. The inner exact-sized -/// iterator might already be `usize::MAX`-long, and thus the length of the -/// longer adapted iterator would no longer be exactly representable in `usize`. -/// -/// This is why [`Chain`](crate::iter::Chain) isn't `ExactSizeIterator`, -/// even when `A` and `B` are both `ExactSizeIterator`. -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// // a finite range knows exactly how many times it will iterate -/// let five = 0..5; -/// -/// assert_eq!(5, five.len()); -/// ``` -/// -/// In the [module-level docs], we implemented an [`Iterator`], `Counter`. -/// Let's implement `ExactSizeIterator` for it as well: -/// -/// [module-level docs]: crate::iter -/// -/// ``` -/// # struct Counter { -/// # count: usize, -/// # } -/// # impl Counter { -/// # fn new() -> Counter { -/// # Counter { count: 0 } -/// # } -/// # } -/// # impl Iterator for Counter { -/// # type Item = usize; -/// # fn next(&mut self) -> Option { -/// # self.count += 1; -/// # if self.count < 6 { -/// # Some(self.count) -/// # } else { -/// # None -/// # } -/// # } -/// # } -/// impl ExactSizeIterator for Counter { -/// // We can easily calculate the remaining number of iterations. -/// fn len(&self) -> usize { -/// 5 - self.count -/// } -/// } -/// -/// // And now we can use it! -/// -/// let mut counter = Counter::new(); -/// -/// assert_eq!(5, counter.len()); -/// let _ = counter.next(); -/// assert_eq!(4, counter.len()); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub trait ExactSizeIterator: Iterator { - /// Returns the exact remaining length of the iterator. - /// - /// The implementation ensures that the iterator will return exactly `len()` - /// more times a [`Some(T)`] value, before returning [`None`]. - /// This method has a default implementation, so you usually should not - /// implement it directly. However, if you can provide a more efficient - /// implementation, you can do so. See the [trait-level] docs for an - /// example. - /// - /// This function has the same safety guarantees as the - /// [`Iterator::size_hint`] function. - /// - /// [trait-level]: ExactSizeIterator - /// [`Some(T)`]: Some - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// // a finite range knows exactly how many times it will iterate - /// let mut range = 0..5; - /// - /// assert_eq!(5, range.len()); - /// let _ = range.next(); - /// assert_eq!(4, range.len()); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - fn len(&self) -> usize { - let (lower, upper) = self.size_hint(); - // Note: This assertion is overly defensive, but it checks the invariant - // guaranteed by the trait. If this trait were rust-internal, - // we could use debug_assert!; assert_eq! will check all Rust user - // implementations too. - assert_eq!(upper, Some(lower)); - lower - } - - /// Returns `true` if the iterator is empty. - /// - /// This method has a default implementation using - /// [`ExactSizeIterator::len()`], so you don't need to implement it yourself. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(exact_size_is_empty)] - /// - /// let mut one_element = std::iter::once(0); - /// assert!(!one_element.is_empty()); - /// - /// assert_eq!(one_element.next(), Some(0)); - /// assert!(one_element.is_empty()); - /// - /// assert_eq!(one_element.next(), None); - /// ``` - #[inline] - #[unstable(feature = "exact_size_is_empty", issue = "35428")] - fn is_empty(&self) -> bool { - self.len() == 0 - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for &mut I { - fn len(&self) -> usize { - (**self).len() - } - fn is_empty(&self) -> bool { - (**self).is_empty() - } -} diff --git a/library/core/src/iter/traits/iterator.rs b/library/core/src/iter/traits/iterator.rs deleted file mode 100644 index cee99e28b5a97..0000000000000 --- a/library/core/src/iter/traits/iterator.rs +++ /dev/null @@ -1,4182 +0,0 @@ -use crate::array; -use crate::cmp::{self, Ordering}; -use crate::num::NonZero; -use crate::ops::{ChangeOutputType, ControlFlow, FromResidual, Residual, Try}; - -use super::super::try_process; -use super::super::ByRefSized; -use super::super::TrustedRandomAccessNoCoerce; -use super::super::{ArrayChunks, Chain, Cloned, Copied, Cycle, Enumerate, Filter, FilterMap, Fuse}; -use super::super::{FlatMap, Flatten}; -use super::super::{ - Inspect, Map, MapWhile, MapWindows, Peekable, Rev, Scan, Skip, SkipWhile, StepBy, Take, - TakeWhile, -}; -use super::super::{Intersperse, IntersperseWith, Product, Sum, Zip}; - -fn _assert_is_object_safe(_: &dyn Iterator) {} - -/// A trait for dealing with iterators. -/// -/// This is the main iterator trait. For more about the concept of iterators -/// generally, please see the [module-level documentation]. In particular, you -/// may want to know how to [implement `Iterator`][impl]. -/// -/// [module-level documentation]: crate::iter -/// [impl]: crate::iter#implementing-iterator -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_on_unimplemented( - on( - _Self = "core::ops::range::RangeTo", - note = "you might have meant to use a bounded `Range`" - ), - on( - _Self = "core::ops::range::RangeToInclusive", - note = "you might have meant to use a bounded `RangeInclusive`" - ), - label = "`{Self}` is not an iterator", - message = "`{Self}` is not an iterator" -)] -#[doc(notable_trait)] -#[lang = "iterator"] -#[rustc_diagnostic_item = "Iterator"] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub trait Iterator { - /// The type of the elements being iterated over. - #[rustc_diagnostic_item = "IteratorItem"] - #[stable(feature = "rust1", since = "1.0.0")] - type Item; - - /// Advances the iterator and returns the next value. - /// - /// Returns [`None`] when iteration is finished. Individual iterator - /// implementations may choose to resume iteration, and so calling `next()` - /// again may or may not eventually start returning [`Some(Item)`] again at some - /// point. - /// - /// [`Some(Item)`]: Some - /// - /// # Examples - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// let mut iter = a.iter(); - /// - /// // A call to next() returns the next value... - /// assert_eq!(Some(&1), iter.next()); - /// assert_eq!(Some(&2), iter.next()); - /// assert_eq!(Some(&3), iter.next()); - /// - /// // ... and then None once it's over. - /// assert_eq!(None, iter.next()); - /// - /// // More calls may or may not return `None`. Here, they always will. - /// assert_eq!(None, iter.next()); - /// assert_eq!(None, iter.next()); - /// ``` - #[lang = "next"] - #[stable(feature = "rust1", since = "1.0.0")] - fn next(&mut self) -> Option; - - /// Advances the iterator and returns an array containing the next `N` values. - /// - /// If there are not enough elements to fill the array then `Err` is returned - /// containing an iterator over the remaining elements. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(iter_next_chunk)] - /// - /// let mut iter = "lorem".chars(); - /// - /// assert_eq!(iter.next_chunk().unwrap(), ['l', 'o']); // N is inferred as 2 - /// assert_eq!(iter.next_chunk().unwrap(), ['r', 'e', 'm']); // N is inferred as 3 - /// assert_eq!(iter.next_chunk::<4>().unwrap_err().as_slice(), &[]); // N is explicitly 4 - /// ``` - /// - /// Split a string and get the first three items. - /// - /// ``` - /// #![feature(iter_next_chunk)] - /// - /// let quote = "not all those who wander are lost"; - /// let [first, second, third] = quote.split_whitespace().next_chunk().unwrap(); - /// assert_eq!(first, "not"); - /// assert_eq!(second, "all"); - /// assert_eq!(third, "those"); - /// ``` - #[inline] - #[unstable(feature = "iter_next_chunk", reason = "recently added", issue = "98326")] - #[rustc_do_not_const_check] - fn next_chunk( - &mut self, - ) -> Result<[Self::Item; N], array::IntoIter> - where - Self: Sized, - { - array::iter_next_chunk(self) - } - - /// Returns the bounds on the remaining length of the iterator. - /// - /// Specifically, `size_hint()` returns a tuple where the first element - /// is the lower bound, and the second element is the upper bound. - /// - /// The second half of the tuple that is returned is an [Option]<[usize]>. - /// A [`None`] here means that either there is no known upper bound, or the - /// upper bound is larger than [`usize`]. - /// - /// # Implementation notes - /// - /// It is not enforced that an iterator implementation yields the declared - /// number of elements. A buggy iterator may yield less than the lower bound - /// or more than the upper bound of elements. - /// - /// `size_hint()` is primarily intended to be used for optimizations such as - /// reserving space for the elements of the iterator, but must not be - /// trusted to e.g., omit bounds checks in unsafe code. An incorrect - /// implementation of `size_hint()` should not lead to memory safety - /// violations. - /// - /// That said, the implementation should provide a correct estimation, - /// because otherwise it would be a violation of the trait's protocol. - /// - /// The default implementation returns (0, [None]) which is correct for any - /// iterator. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = [1, 2, 3]; - /// let mut iter = a.iter(); - /// - /// assert_eq!((3, Some(3)), iter.size_hint()); - /// let _ = iter.next(); - /// assert_eq!((2, Some(2)), iter.size_hint()); - /// ``` - /// - /// A more complex example: - /// - /// ``` - /// // The even numbers in the range of zero to nine. - /// let iter = (0..10).filter(|x| x % 2 == 0); - /// - /// // We might iterate from zero to ten times. Knowing that it's five - /// // exactly wouldn't be possible without executing filter(). - /// assert_eq!((0, Some(10)), iter.size_hint()); - /// - /// // Let's add five more numbers with chain() - /// let iter = (0..10).filter(|x| x % 2 == 0).chain(15..20); - /// - /// // now both bounds are increased by five - /// assert_eq!((5, Some(15)), iter.size_hint()); - /// ``` - /// - /// Returning `None` for an upper bound: - /// - /// ``` - /// // an infinite iterator has no upper bound - /// // and the maximum possible lower bound - /// let iter = 0..; - /// - /// assert_eq!((usize::MAX, None), iter.size_hint()); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn size_hint(&self) -> (usize, Option) { - (0, None) - } - - /// Consumes the iterator, counting the number of iterations and returning it. - /// - /// This method will call [`next`] repeatedly until [`None`] is encountered, - /// returning the number of times it saw [`Some`]. Note that [`next`] has to be - /// called at least once even if the iterator does not have any elements. - /// - /// [`next`]: Iterator::next - /// - /// # Overflow Behavior - /// - /// The method does no guarding against overflows, so counting elements of - /// an iterator with more than [`usize::MAX`] elements either produces the - /// wrong result or panics. If debug assertions are enabled, a panic is - /// guaranteed. - /// - /// # Panics - /// - /// This function might panic if the iterator has more than [`usize::MAX`] - /// elements. - /// - /// # Examples - /// - /// ``` - /// let a = [1, 2, 3]; - /// assert_eq!(a.iter().count(), 3); - /// - /// let a = [1, 2, 3, 4, 5]; - /// assert_eq!(a.iter().count(), 5); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn count(self) -> usize - where - Self: Sized, - { - self.fold( - 0, - #[rustc_inherit_overflow_checks] - |count, _| count + 1, - ) - } - - /// Consumes the iterator, returning the last element. - /// - /// This method will evaluate the iterator until it returns [`None`]. While - /// doing so, it keeps track of the current element. After [`None`] is - /// returned, `last()` will then return the last element it saw. - /// - /// # Examples - /// - /// ``` - /// let a = [1, 2, 3]; - /// assert_eq!(a.iter().last(), Some(&3)); - /// - /// let a = [1, 2, 3, 4, 5]; - /// assert_eq!(a.iter().last(), Some(&5)); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn last(self) -> Option - where - Self: Sized, - { - #[inline] - fn some(_: Option, x: T) -> Option { - Some(x) - } - - self.fold(None, some) - } - - /// Advances the iterator by `n` elements. - /// - /// This method will eagerly skip `n` elements by calling [`next`] up to `n` - /// times until [`None`] is encountered. - /// - /// `advance_by(n)` will return `Ok(())` if the iterator successfully advances by - /// `n` elements, or a `Err(NonZero)` with value `k` if [`None`] is encountered, - /// where `k` is remaining number of steps that could not be advanced because the iterator ran out. - /// If `self` is empty and `n` is non-zero, then this returns `Err(n)`. - /// Otherwise, `k` is always less than `n`. - /// - /// Calling `advance_by(0)` can do meaningful work, for example [`Flatten`] - /// can advance its outer iterator until it finds an inner iterator that is not empty, which - /// then often allows it to return a more accurate `size_hint()` than in its initial state. - /// - /// [`Flatten`]: crate::iter::Flatten - /// [`next`]: Iterator::next - /// - /// # Examples - /// - /// ``` - /// #![feature(iter_advance_by)] - /// - /// use std::num::NonZero; - /// - /// let a = [1, 2, 3, 4]; - /// let mut iter = a.iter(); - /// - /// assert_eq!(iter.advance_by(2), Ok(())); - /// assert_eq!(iter.next(), Some(&3)); - /// assert_eq!(iter.advance_by(0), Ok(())); - /// assert_eq!(iter.advance_by(100), Err(NonZero::new(99).unwrap())); // only `&4` was skipped - /// ``` - #[inline] - #[unstable(feature = "iter_advance_by", reason = "recently added", issue = "77404")] - #[rustc_do_not_const_check] - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - for i in 0..n { - if self.next().is_none() { - // SAFETY: `i` is always less than `n`. - return Err(unsafe { NonZero::new_unchecked(n - i) }); - } - } - Ok(()) - } - - /// Returns the `n`th element of the iterator. - /// - /// Like most indexing operations, the count starts from zero, so `nth(0)` - /// returns the first value, `nth(1)` the second, and so on. - /// - /// Note that all preceding elements, as well as the returned element, will be - /// consumed from the iterator. That means that the preceding elements will be - /// discarded, and also that calling `nth(0)` multiple times on the same iterator - /// will return different elements. - /// - /// `nth()` will return [`None`] if `n` is greater than or equal to the length of the - /// iterator. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = [1, 2, 3]; - /// assert_eq!(a.iter().nth(1), Some(&2)); - /// ``` - /// - /// Calling `nth()` multiple times doesn't rewind the iterator: - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// let mut iter = a.iter(); - /// - /// assert_eq!(iter.nth(1), Some(&2)); - /// assert_eq!(iter.nth(1), None); - /// ``` - /// - /// Returning `None` if there are less than `n + 1` elements: - /// - /// ``` - /// let a = [1, 2, 3]; - /// assert_eq!(a.iter().nth(10), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn nth(&mut self, n: usize) -> Option { - self.advance_by(n).ok()?; - self.next() - } - - /// Creates an iterator starting at the same point, but stepping by - /// the given amount at each iteration. - /// - /// Note 1: The first element of the iterator will always be returned, - /// regardless of the step given. - /// - /// Note 2: The time at which ignored elements are pulled is not fixed. - /// `StepBy` behaves like the sequence `self.next()`, `self.nth(step-1)`, - /// `self.nth(step-1)`, …, but is also free to behave like the sequence - /// `advance_n_and_return_first(&mut self, step)`, - /// `advance_n_and_return_first(&mut self, step)`, … - /// Which way is used may change for some iterators for performance reasons. - /// The second way will advance the iterator earlier and may consume more items. - /// - /// `advance_n_and_return_first` is the equivalent of: - /// ``` - /// fn advance_n_and_return_first(iter: &mut I, n: usize) -> Option - /// where - /// I: Iterator, - /// { - /// let next = iter.next(); - /// if n > 1 { - /// iter.nth(n - 2); - /// } - /// next - /// } - /// ``` - /// - /// # Panics - /// - /// The method will panic if the given step is `0`. - /// - /// # Examples - /// - /// ``` - /// let a = [0, 1, 2, 3, 4, 5]; - /// let mut iter = a.iter().step_by(2); - /// - /// assert_eq!(iter.next(), Some(&0)); - /// assert_eq!(iter.next(), Some(&2)); - /// assert_eq!(iter.next(), Some(&4)); - /// assert_eq!(iter.next(), None); - /// ``` - #[inline] - #[stable(feature = "iterator_step_by", since = "1.28.0")] - #[rustc_do_not_const_check] - fn step_by(self, step: usize) -> StepBy - where - Self: Sized, - { - StepBy::new(self, step) - } - - /// Takes two iterators and creates a new iterator over both in sequence. - /// - /// `chain()` will return a new iterator which will first iterate over - /// values from the first iterator and then over values from the second - /// iterator. - /// - /// In other words, it links two iterators together, in a chain. 🔗 - /// - /// [`once`] is commonly used to adapt a single value into a chain of - /// other kinds of iteration. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a1 = [1, 2, 3]; - /// let a2 = [4, 5, 6]; - /// - /// let mut iter = a1.iter().chain(a2.iter()); - /// - /// assert_eq!(iter.next(), Some(&1)); - /// assert_eq!(iter.next(), Some(&2)); - /// assert_eq!(iter.next(), Some(&3)); - /// assert_eq!(iter.next(), Some(&4)); - /// assert_eq!(iter.next(), Some(&5)); - /// assert_eq!(iter.next(), Some(&6)); - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// Since the argument to `chain()` uses [`IntoIterator`], we can pass - /// anything that can be converted into an [`Iterator`], not just an - /// [`Iterator`] itself. For example, slices (`&[T]`) implement - /// [`IntoIterator`], and so can be passed to `chain()` directly: - /// - /// ``` - /// let s1 = &[1, 2, 3]; - /// let s2 = &[4, 5, 6]; - /// - /// let mut iter = s1.iter().chain(s2); - /// - /// assert_eq!(iter.next(), Some(&1)); - /// assert_eq!(iter.next(), Some(&2)); - /// assert_eq!(iter.next(), Some(&3)); - /// assert_eq!(iter.next(), Some(&4)); - /// assert_eq!(iter.next(), Some(&5)); - /// assert_eq!(iter.next(), Some(&6)); - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// If you work with Windows API, you may wish to convert [`OsStr`] to `Vec`: - /// - /// ``` - /// #[cfg(windows)] - /// fn os_str_to_utf16(s: &std::ffi::OsStr) -> Vec { - /// use std::os::windows::ffi::OsStrExt; - /// s.encode_wide().chain(std::iter::once(0)).collect() - /// } - /// ``` - /// - /// [`once`]: crate::iter::once - /// [`OsStr`]: ../../std/ffi/struct.OsStr.html - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn chain(self, other: U) -> Chain - where - Self: Sized, - U: IntoIterator, - { - Chain::new(self, other.into_iter()) - } - - /// 'Zips up' two iterators into a single iterator of pairs. - /// - /// `zip()` returns a new iterator that will iterate over two other - /// iterators, returning a tuple where the first element comes from the - /// first iterator, and the second element comes from the second iterator. - /// - /// In other words, it zips two iterators together, into a single one. - /// - /// If either iterator returns [`None`], [`next`] from the zipped iterator - /// will return [`None`]. - /// If the zipped iterator has no more elements to return then each further attempt to advance - /// it will first try to advance the first iterator at most one time and if it still yielded an item - /// try to advance the second iterator at most one time. - /// - /// To 'undo' the result of zipping up two iterators, see [`unzip`]. - /// - /// [`unzip`]: Iterator::unzip - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a1 = [1, 2, 3]; - /// let a2 = [4, 5, 6]; - /// - /// let mut iter = a1.iter().zip(a2.iter()); - /// - /// assert_eq!(iter.next(), Some((&1, &4))); - /// assert_eq!(iter.next(), Some((&2, &5))); - /// assert_eq!(iter.next(), Some((&3, &6))); - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// Since the argument to `zip()` uses [`IntoIterator`], we can pass - /// anything that can be converted into an [`Iterator`], not just an - /// [`Iterator`] itself. For example, slices (`&[T]`) implement - /// [`IntoIterator`], and so can be passed to `zip()` directly: - /// - /// ``` - /// let s1 = &[1, 2, 3]; - /// let s2 = &[4, 5, 6]; - /// - /// let mut iter = s1.iter().zip(s2); - /// - /// assert_eq!(iter.next(), Some((&1, &4))); - /// assert_eq!(iter.next(), Some((&2, &5))); - /// assert_eq!(iter.next(), Some((&3, &6))); - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// `zip()` is often used to zip an infinite iterator to a finite one. - /// This works because the finite iterator will eventually return [`None`], - /// ending the zipper. Zipping with `(0..)` can look a lot like [`enumerate`]: - /// - /// ``` - /// let enumerate: Vec<_> = "foo".chars().enumerate().collect(); - /// - /// let zipper: Vec<_> = (0..).zip("foo".chars()).collect(); - /// - /// assert_eq!((0, 'f'), enumerate[0]); - /// assert_eq!((0, 'f'), zipper[0]); - /// - /// assert_eq!((1, 'o'), enumerate[1]); - /// assert_eq!((1, 'o'), zipper[1]); - /// - /// assert_eq!((2, 'o'), enumerate[2]); - /// assert_eq!((2, 'o'), zipper[2]); - /// ``` - /// - /// If both iterators have roughly equivalent syntax, it may be more readable to use [`zip`]: - /// - /// ``` - /// use std::iter::zip; - /// - /// let a = [1, 2, 3]; - /// let b = [2, 3, 4]; - /// - /// let mut zipped = zip( - /// a.into_iter().map(|x| x * 2).skip(1), - /// b.into_iter().map(|x| x * 2).skip(1), - /// ); - /// - /// assert_eq!(zipped.next(), Some((4, 6))); - /// assert_eq!(zipped.next(), Some((6, 8))); - /// assert_eq!(zipped.next(), None); - /// ``` - /// - /// compared to: - /// - /// ``` - /// # let a = [1, 2, 3]; - /// # let b = [2, 3, 4]; - /// # - /// let mut zipped = a - /// .into_iter() - /// .map(|x| x * 2) - /// .skip(1) - /// .zip(b.into_iter().map(|x| x * 2).skip(1)); - /// # - /// # assert_eq!(zipped.next(), Some((4, 6))); - /// # assert_eq!(zipped.next(), Some((6, 8))); - /// # assert_eq!(zipped.next(), None); - /// ``` - /// - /// [`enumerate`]: Iterator::enumerate - /// [`next`]: Iterator::next - /// [`zip`]: crate::iter::zip - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn zip(self, other: U) -> Zip - where - Self: Sized, - U: IntoIterator, - { - Zip::new(self, other.into_iter()) - } - - /// Creates a new iterator which places a copy of `separator` between adjacent - /// items of the original iterator. - /// - /// In case `separator` does not implement [`Clone`] or needs to be - /// computed every time, use [`intersperse_with`]. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(iter_intersperse)] - /// - /// let mut a = [0, 1, 2].iter().intersperse(&100); - /// assert_eq!(a.next(), Some(&0)); // The first element from `a`. - /// assert_eq!(a.next(), Some(&100)); // The separator. - /// assert_eq!(a.next(), Some(&1)); // The next element from `a`. - /// assert_eq!(a.next(), Some(&100)); // The separator. - /// assert_eq!(a.next(), Some(&2)); // The last element from `a`. - /// assert_eq!(a.next(), None); // The iterator is finished. - /// ``` - /// - /// `intersperse` can be very useful to join an iterator's items using a common element: - /// ``` - /// #![feature(iter_intersperse)] - /// - /// let hello = ["Hello", "World", "!"].iter().copied().intersperse(" ").collect::(); - /// assert_eq!(hello, "Hello World !"); - /// ``` - /// - /// [`Clone`]: crate::clone::Clone - /// [`intersperse_with`]: Iterator::intersperse_with - #[inline] - #[unstable(feature = "iter_intersperse", reason = "recently added", issue = "79524")] - #[rustc_do_not_const_check] - fn intersperse(self, separator: Self::Item) -> Intersperse - where - Self: Sized, - Self::Item: Clone, - { - Intersperse::new(self, separator) - } - - /// Creates a new iterator which places an item generated by `separator` - /// between adjacent items of the original iterator. - /// - /// The closure will be called exactly once each time an item is placed - /// between two adjacent items from the underlying iterator; specifically, - /// the closure is not called if the underlying iterator yields less than - /// two items and after the last item is yielded. - /// - /// If the iterator's item implements [`Clone`], it may be easier to use - /// [`intersperse`]. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(iter_intersperse)] - /// - /// #[derive(PartialEq, Debug)] - /// struct NotClone(usize); - /// - /// let v = [NotClone(0), NotClone(1), NotClone(2)]; - /// let mut it = v.into_iter().intersperse_with(|| NotClone(99)); - /// - /// assert_eq!(it.next(), Some(NotClone(0))); // The first element from `v`. - /// assert_eq!(it.next(), Some(NotClone(99))); // The separator. - /// assert_eq!(it.next(), Some(NotClone(1))); // The next element from `v`. - /// assert_eq!(it.next(), Some(NotClone(99))); // The separator. - /// assert_eq!(it.next(), Some(NotClone(2))); // The last element from `v`. - /// assert_eq!(it.next(), None); // The iterator is finished. - /// ``` - /// - /// `intersperse_with` can be used in situations where the separator needs - /// to be computed: - /// ``` - /// #![feature(iter_intersperse)] - /// - /// let src = ["Hello", "to", "all", "people", "!!"].iter().copied(); - /// - /// // The closure mutably borrows its context to generate an item. - /// let mut happy_emojis = [" ❤️ ", " 😀 "].iter().copied(); - /// let separator = || happy_emojis.next().unwrap_or(" 🦀 "); - /// - /// let result = src.intersperse_with(separator).collect::(); - /// assert_eq!(result, "Hello ❤️ to 😀 all 🦀 people 🦀 !!"); - /// ``` - /// [`Clone`]: crate::clone::Clone - /// [`intersperse`]: Iterator::intersperse - #[inline] - #[unstable(feature = "iter_intersperse", reason = "recently added", issue = "79524")] - #[rustc_do_not_const_check] - fn intersperse_with(self, separator: G) -> IntersperseWith - where - Self: Sized, - G: FnMut() -> Self::Item, - { - IntersperseWith::new(self, separator) - } - - /// Takes a closure and creates an iterator which calls that closure on each - /// element. - /// - /// `map()` transforms one iterator into another, by means of its argument: - /// something that implements [`FnMut`]. It produces a new iterator which - /// calls this closure on each element of the original iterator. - /// - /// If you are good at thinking in types, you can think of `map()` like this: - /// If you have an iterator that gives you elements of some type `A`, and - /// you want an iterator of some other type `B`, you can use `map()`, - /// passing a closure that takes an `A` and returns a `B`. - /// - /// `map()` is conceptually similar to a [`for`] loop. However, as `map()` is - /// lazy, it is best used when you're already working with other iterators. - /// If you're doing some sort of looping for a side effect, it's considered - /// more idiomatic to use [`for`] than `map()`. - /// - /// [`for`]: ../../book/ch03-05-control-flow.html#looping-through-a-collection-with-for - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// let mut iter = a.iter().map(|x| 2 * x); - /// - /// assert_eq!(iter.next(), Some(2)); - /// assert_eq!(iter.next(), Some(4)); - /// assert_eq!(iter.next(), Some(6)); - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// If you're doing some sort of side effect, prefer [`for`] to `map()`: - /// - /// ``` - /// # #![allow(unused_must_use)] - /// // don't do this: - /// (0..5).map(|x| println!("{x}")); - /// - /// // it won't even execute, as it is lazy. Rust will warn you about this. - /// - /// // Instead, use for: - /// for x in 0..5 { - /// println!("{x}"); - /// } - /// ``` - #[rustc_diagnostic_item = "IteratorMap"] - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn map(self, f: F) -> Map - where - Self: Sized, - F: FnMut(Self::Item) -> B, - { - Map::new(self, f) - } - - /// Calls a closure on each element of an iterator. - /// - /// This is equivalent to using a [`for`] loop on the iterator, although - /// `break` and `continue` are not possible from a closure. It's generally - /// more idiomatic to use a `for` loop, but `for_each` may be more legible - /// when processing items at the end of longer iterator chains. In some - /// cases `for_each` may also be faster than a loop, because it will use - /// internal iteration on adapters like `Chain`. - /// - /// [`for`]: ../../book/ch03-05-control-flow.html#looping-through-a-collection-with-for - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::sync::mpsc::channel; - /// - /// let (tx, rx) = channel(); - /// (0..5).map(|x| x * 2 + 1) - /// .for_each(move |x| tx.send(x).unwrap()); - /// - /// let v: Vec<_> = rx.iter().collect(); - /// assert_eq!(v, vec![1, 3, 5, 7, 9]); - /// ``` - /// - /// For such a small example, a `for` loop may be cleaner, but `for_each` - /// might be preferable to keep a functional style with longer iterators: - /// - /// ``` - /// (0..5).flat_map(|x| x * 100 .. x * 110) - /// .enumerate() - /// .filter(|&(i, x)| (i + x) % 3 == 0) - /// .for_each(|(i, x)| println!("{i}:{x}")); - /// ``` - #[inline] - #[stable(feature = "iterator_for_each", since = "1.21.0")] - #[rustc_do_not_const_check] - fn for_each(self, f: F) - where - Self: Sized, - F: FnMut(Self::Item), - { - #[inline] - fn call(mut f: impl FnMut(T)) -> impl FnMut((), T) { - move |(), item| f(item) - } - - self.fold((), call(f)); - } - - /// Creates an iterator which uses a closure to determine if an element - /// should be yielded. - /// - /// Given an element the closure must return `true` or `false`. The returned - /// iterator will yield only the elements for which the closure returns - /// true. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = [0i32, 1, 2]; - /// - /// let mut iter = a.iter().filter(|x| x.is_positive()); - /// - /// assert_eq!(iter.next(), Some(&1)); - /// assert_eq!(iter.next(), Some(&2)); - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// Because the closure passed to `filter()` takes a reference, and many - /// iterators iterate over references, this leads to a possibly confusing - /// situation, where the type of the closure is a double reference: - /// - /// ``` - /// let a = [0, 1, 2]; - /// - /// let mut iter = a.iter().filter(|x| **x > 1); // need two *s! - /// - /// assert_eq!(iter.next(), Some(&2)); - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// It's common to instead use destructuring on the argument to strip away - /// one: - /// - /// ``` - /// let a = [0, 1, 2]; - /// - /// let mut iter = a.iter().filter(|&x| *x > 1); // both & and * - /// - /// assert_eq!(iter.next(), Some(&2)); - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// or both: - /// - /// ``` - /// let a = [0, 1, 2]; - /// - /// let mut iter = a.iter().filter(|&&x| x > 1); // two &s - /// - /// assert_eq!(iter.next(), Some(&2)); - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// of these layers. - /// - /// Note that `iter.filter(f).next()` is equivalent to `iter.find(f)`. - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn filter

(self, predicate: P) -> Filter - where - Self: Sized, - P: FnMut(&Self::Item) -> bool, - { - Filter::new(self, predicate) - } - - /// Creates an iterator that both filters and maps. - /// - /// The returned iterator yields only the `value`s for which the supplied - /// closure returns `Some(value)`. - /// - /// `filter_map` can be used to make chains of [`filter`] and [`map`] more - /// concise. The example below shows how a `map().filter().map()` can be - /// shortened to a single call to `filter_map`. - /// - /// [`filter`]: Iterator::filter - /// [`map`]: Iterator::map - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = ["1", "two", "NaN", "four", "5"]; - /// - /// let mut iter = a.iter().filter_map(|s| s.parse().ok()); - /// - /// assert_eq!(iter.next(), Some(1)); - /// assert_eq!(iter.next(), Some(5)); - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// Here's the same example, but with [`filter`] and [`map`]: - /// - /// ``` - /// let a = ["1", "two", "NaN", "four", "5"]; - /// let mut iter = a.iter().map(|s| s.parse()).filter(|s| s.is_ok()).map(|s| s.unwrap()); - /// assert_eq!(iter.next(), Some(1)); - /// assert_eq!(iter.next(), Some(5)); - /// assert_eq!(iter.next(), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn filter_map(self, f: F) -> FilterMap - where - Self: Sized, - F: FnMut(Self::Item) -> Option, - { - FilterMap::new(self, f) - } - - /// Creates an iterator which gives the current iteration count as well as - /// the next value. - /// - /// The iterator returned yields pairs `(i, val)`, where `i` is the - /// current index of iteration and `val` is the value returned by the - /// iterator. - /// - /// `enumerate()` keeps its count as a [`usize`]. If you want to count by a - /// different sized integer, the [`zip`] function provides similar - /// functionality. - /// - /// # Overflow Behavior - /// - /// The method does no guarding against overflows, so enumerating more than - /// [`usize::MAX`] elements either produces the wrong result or panics. If - /// debug assertions are enabled, a panic is guaranteed. - /// - /// # Panics - /// - /// The returned iterator might panic if the to-be-returned index would - /// overflow a [`usize`]. - /// - /// [`zip`]: Iterator::zip - /// - /// # Examples - /// - /// ``` - /// let a = ['a', 'b', 'c']; - /// - /// let mut iter = a.iter().enumerate(); - /// - /// assert_eq!(iter.next(), Some((0, &'a'))); - /// assert_eq!(iter.next(), Some((1, &'b'))); - /// assert_eq!(iter.next(), Some((2, &'c'))); - /// assert_eq!(iter.next(), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - #[cfg_attr(not(test), rustc_diagnostic_item = "enumerate_method")] - fn enumerate(self) -> Enumerate - where - Self: Sized, - { - Enumerate::new(self) - } - - /// Creates an iterator which can use the [`peek`] and [`peek_mut`] methods - /// to look at the next element of the iterator without consuming it. See - /// their documentation for more information. - /// - /// Note that the underlying iterator is still advanced when [`peek`] or - /// [`peek_mut`] are called for the first time: In order to retrieve the - /// next element, [`next`] is called on the underlying iterator, hence any - /// side effects (i.e. anything other than fetching the next value) of - /// the [`next`] method will occur. - /// - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let xs = [1, 2, 3]; - /// - /// let mut iter = xs.iter().peekable(); - /// - /// // peek() lets us see into the future - /// assert_eq!(iter.peek(), Some(&&1)); - /// assert_eq!(iter.next(), Some(&1)); - /// - /// assert_eq!(iter.next(), Some(&2)); - /// - /// // we can peek() multiple times, the iterator won't advance - /// assert_eq!(iter.peek(), Some(&&3)); - /// assert_eq!(iter.peek(), Some(&&3)); - /// - /// assert_eq!(iter.next(), Some(&3)); - /// - /// // after the iterator is finished, so is peek() - /// assert_eq!(iter.peek(), None); - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// Using [`peek_mut`] to mutate the next item without advancing the - /// iterator: - /// - /// ``` - /// let xs = [1, 2, 3]; - /// - /// let mut iter = xs.iter().peekable(); - /// - /// // `peek_mut()` lets us see into the future - /// assert_eq!(iter.peek_mut(), Some(&mut &1)); - /// assert_eq!(iter.peek_mut(), Some(&mut &1)); - /// assert_eq!(iter.next(), Some(&1)); - /// - /// if let Some(mut p) = iter.peek_mut() { - /// assert_eq!(*p, &2); - /// // put a value into the iterator - /// *p = &1000; - /// } - /// - /// // The value reappears as the iterator continues - /// assert_eq!(iter.collect::>(), vec![&1000, &3]); - /// ``` - /// [`peek`]: Peekable::peek - /// [`peek_mut`]: Peekable::peek_mut - /// [`next`]: Iterator::next - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn peekable(self) -> Peekable - where - Self: Sized, - { - Peekable::new(self) - } - - /// Creates an iterator that [`skip`]s elements based on a predicate. - /// - /// [`skip`]: Iterator::skip - /// - /// `skip_while()` takes a closure as an argument. It will call this - /// closure on each element of the iterator, and ignore elements - /// until it returns `false`. - /// - /// After `false` is returned, `skip_while()`'s job is over, and the - /// rest of the elements are yielded. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = [-1i32, 0, 1]; - /// - /// let mut iter = a.iter().skip_while(|x| x.is_negative()); - /// - /// assert_eq!(iter.next(), Some(&0)); - /// assert_eq!(iter.next(), Some(&1)); - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// Because the closure passed to `skip_while()` takes a reference, and many - /// iterators iterate over references, this leads to a possibly confusing - /// situation, where the type of the closure argument is a double reference: - /// - /// ``` - /// let a = [-1, 0, 1]; - /// - /// let mut iter = a.iter().skip_while(|x| **x < 0); // need two *s! - /// - /// assert_eq!(iter.next(), Some(&0)); - /// assert_eq!(iter.next(), Some(&1)); - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// Stopping after an initial `false`: - /// - /// ``` - /// let a = [-1, 0, 1, -2]; - /// - /// let mut iter = a.iter().skip_while(|x| **x < 0); - /// - /// assert_eq!(iter.next(), Some(&0)); - /// assert_eq!(iter.next(), Some(&1)); - /// - /// // while this would have been false, since we already got a false, - /// // skip_while() isn't used any more - /// assert_eq!(iter.next(), Some(&-2)); - /// - /// assert_eq!(iter.next(), None); - /// ``` - #[inline] - #[doc(alias = "drop_while")] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn skip_while

(self, predicate: P) -> SkipWhile - where - Self: Sized, - P: FnMut(&Self::Item) -> bool, - { - SkipWhile::new(self, predicate) - } - - /// Creates an iterator that yields elements based on a predicate. - /// - /// `take_while()` takes a closure as an argument. It will call this - /// closure on each element of the iterator, and yield elements - /// while it returns `true`. - /// - /// After `false` is returned, `take_while()`'s job is over, and the - /// rest of the elements are ignored. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = [-1i32, 0, 1]; - /// - /// let mut iter = a.iter().take_while(|x| x.is_negative()); - /// - /// assert_eq!(iter.next(), Some(&-1)); - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// Because the closure passed to `take_while()` takes a reference, and many - /// iterators iterate over references, this leads to a possibly confusing - /// situation, where the type of the closure is a double reference: - /// - /// ``` - /// let a = [-1, 0, 1]; - /// - /// let mut iter = a.iter().take_while(|x| **x < 0); // need two *s! - /// - /// assert_eq!(iter.next(), Some(&-1)); - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// Stopping after an initial `false`: - /// - /// ``` - /// let a = [-1, 0, 1, -2]; - /// - /// let mut iter = a.iter().take_while(|x| **x < 0); - /// - /// assert_eq!(iter.next(), Some(&-1)); - /// - /// // We have more elements that are less than zero, but since we already - /// // got a false, take_while() isn't used any more - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// Because `take_while()` needs to look at the value in order to see if it - /// should be included or not, consuming iterators will see that it is - /// removed: - /// - /// ``` - /// let a = [1, 2, 3, 4]; - /// let mut iter = a.iter(); - /// - /// let result: Vec = iter.by_ref() - /// .take_while(|n| **n != 3) - /// .cloned() - /// .collect(); - /// - /// assert_eq!(result, &[1, 2]); - /// - /// let result: Vec = iter.cloned().collect(); - /// - /// assert_eq!(result, &[4]); - /// ``` - /// - /// The `3` is no longer there, because it was consumed in order to see if - /// the iteration should stop, but wasn't placed back into the iterator. - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn take_while

(self, predicate: P) -> TakeWhile - where - Self: Sized, - P: FnMut(&Self::Item) -> bool, - { - TakeWhile::new(self, predicate) - } - - /// Creates an iterator that both yields elements based on a predicate and maps. - /// - /// `map_while()` takes a closure as an argument. It will call this - /// closure on each element of the iterator, and yield elements - /// while it returns [`Some(_)`][`Some`]. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = [-1i32, 4, 0, 1]; - /// - /// let mut iter = a.iter().map_while(|x| 16i32.checked_div(*x)); - /// - /// assert_eq!(iter.next(), Some(-16)); - /// assert_eq!(iter.next(), Some(4)); - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// Here's the same example, but with [`take_while`] and [`map`]: - /// - /// [`take_while`]: Iterator::take_while - /// [`map`]: Iterator::map - /// - /// ``` - /// let a = [-1i32, 4, 0, 1]; - /// - /// let mut iter = a.iter() - /// .map(|x| 16i32.checked_div(*x)) - /// .take_while(|x| x.is_some()) - /// .map(|x| x.unwrap()); - /// - /// assert_eq!(iter.next(), Some(-16)); - /// assert_eq!(iter.next(), Some(4)); - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// Stopping after an initial [`None`]: - /// - /// ``` - /// let a = [0, 1, 2, -3, 4, 5, -6]; - /// - /// let iter = a.iter().map_while(|x| u32::try_from(*x).ok()); - /// let vec = iter.collect::>(); - /// - /// // We have more elements which could fit in u32 (4, 5), but `map_while` returned `None` for `-3` - /// // (as the `predicate` returned `None`) and `collect` stops at the first `None` encountered. - /// assert_eq!(vec, vec![0, 1, 2]); - /// ``` - /// - /// Because `map_while()` needs to look at the value in order to see if it - /// should be included or not, consuming iterators will see that it is - /// removed: - /// - /// ``` - /// let a = [1, 2, -3, 4]; - /// let mut iter = a.iter(); - /// - /// let result: Vec = iter.by_ref() - /// .map_while(|n| u32::try_from(*n).ok()) - /// .collect(); - /// - /// assert_eq!(result, &[1, 2]); - /// - /// let result: Vec = iter.cloned().collect(); - /// - /// assert_eq!(result, &[4]); - /// ``` - /// - /// The `-3` is no longer there, because it was consumed in order to see if - /// the iteration should stop, but wasn't placed back into the iterator. - /// - /// Note that unlike [`take_while`] this iterator is **not** fused. - /// It is also not specified what this iterator returns after the first [`None`] is returned. - /// If you need fused iterator, use [`fuse`]. - /// - /// [`fuse`]: Iterator::fuse - #[inline] - #[stable(feature = "iter_map_while", since = "1.57.0")] - #[rustc_do_not_const_check] - fn map_while(self, predicate: P) -> MapWhile - where - Self: Sized, - P: FnMut(Self::Item) -> Option, - { - MapWhile::new(self, predicate) - } - - /// Creates an iterator that skips the first `n` elements. - /// - /// `skip(n)` skips elements until `n` elements are skipped or the end of the - /// iterator is reached (whichever happens first). After that, all the remaining - /// elements are yielded. In particular, if the original iterator is too short, - /// then the returned iterator is empty. - /// - /// Rather than overriding this method directly, instead override the `nth` method. - /// - /// # Examples - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// let mut iter = a.iter().skip(2); - /// - /// assert_eq!(iter.next(), Some(&3)); - /// assert_eq!(iter.next(), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn skip(self, n: usize) -> Skip - where - Self: Sized, - { - Skip::new(self, n) - } - - /// Creates an iterator that yields the first `n` elements, or fewer - /// if the underlying iterator ends sooner. - /// - /// `take(n)` yields elements until `n` elements are yielded or the end of - /// the iterator is reached (whichever happens first). - /// The returned iterator is a prefix of length `n` if the original iterator - /// contains at least `n` elements, otherwise it contains all of the - /// (fewer than `n`) elements of the original iterator. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// let mut iter = a.iter().take(2); - /// - /// assert_eq!(iter.next(), Some(&1)); - /// assert_eq!(iter.next(), Some(&2)); - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// `take()` is often used with an infinite iterator, to make it finite: - /// - /// ``` - /// let mut iter = (0..).take(3); - /// - /// assert_eq!(iter.next(), Some(0)); - /// assert_eq!(iter.next(), Some(1)); - /// assert_eq!(iter.next(), Some(2)); - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// If less than `n` elements are available, - /// `take` will limit itself to the size of the underlying iterator: - /// - /// ``` - /// let v = [1, 2]; - /// let mut iter = v.into_iter().take(5); - /// assert_eq!(iter.next(), Some(1)); - /// assert_eq!(iter.next(), Some(2)); - /// assert_eq!(iter.next(), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn take(self, n: usize) -> Take - where - Self: Sized, - { - Take::new(self, n) - } - - /// An iterator adapter which, like [`fold`], holds internal state, but - /// unlike [`fold`], produces a new iterator. - /// - /// [`fold`]: Iterator::fold - /// - /// `scan()` takes two arguments: an initial value which seeds the internal - /// state, and a closure with two arguments, the first being a mutable - /// reference to the internal state and the second an iterator element. - /// The closure can assign to the internal state to share state between - /// iterations. - /// - /// On iteration, the closure will be applied to each element of the - /// iterator and the return value from the closure, an [`Option`], is - /// returned by the `next` method. Thus the closure can return - /// `Some(value)` to yield `value`, or `None` to end the iteration. - /// - /// # Examples - /// - /// ``` - /// let a = [1, 2, 3, 4]; - /// - /// let mut iter = a.iter().scan(1, |state, &x| { - /// // each iteration, we'll multiply the state by the element ... - /// *state = *state * x; - /// - /// // ... and terminate if the state exceeds 6 - /// if *state > 6 { - /// return None; - /// } - /// // ... else yield the negation of the state - /// Some(-*state) - /// }); - /// - /// assert_eq!(iter.next(), Some(-1)); - /// assert_eq!(iter.next(), Some(-2)); - /// assert_eq!(iter.next(), Some(-6)); - /// assert_eq!(iter.next(), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn scan(self, initial_state: St, f: F) -> Scan - where - Self: Sized, - F: FnMut(&mut St, Self::Item) -> Option, - { - Scan::new(self, initial_state, f) - } - - /// Creates an iterator that works like map, but flattens nested structure. - /// - /// The [`map`] adapter is very useful, but only when the closure - /// argument produces values. If it produces an iterator instead, there's - /// an extra layer of indirection. `flat_map()` will remove this extra layer - /// on its own. - /// - /// You can think of `flat_map(f)` as the semantic equivalent - /// of [`map`]ping, and then [`flatten`]ing as in `map(f).flatten()`. - /// - /// Another way of thinking about `flat_map()`: [`map`]'s closure returns - /// one item for each element, and `flat_map()`'s closure returns an - /// iterator for each element. - /// - /// [`map`]: Iterator::map - /// [`flatten`]: Iterator::flatten - /// - /// # Examples - /// - /// ``` - /// let words = ["alpha", "beta", "gamma"]; - /// - /// // chars() returns an iterator - /// let merged: String = words.iter() - /// .flat_map(|s| s.chars()) - /// .collect(); - /// assert_eq!(merged, "alphabetagamma"); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn flat_map(self, f: F) -> FlatMap - where - Self: Sized, - U: IntoIterator, - F: FnMut(Self::Item) -> U, - { - FlatMap::new(self, f) - } - - /// Creates an iterator that flattens nested structure. - /// - /// This is useful when you have an iterator of iterators or an iterator of - /// things that can be turned into iterators and you want to remove one - /// level of indirection. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let data = vec![vec![1, 2, 3, 4], vec![5, 6]]; - /// let flattened = data.into_iter().flatten().collect::>(); - /// assert_eq!(flattened, &[1, 2, 3, 4, 5, 6]); - /// ``` - /// - /// Mapping and then flattening: - /// - /// ``` - /// let words = ["alpha", "beta", "gamma"]; - /// - /// // chars() returns an iterator - /// let merged: String = words.iter() - /// .map(|s| s.chars()) - /// .flatten() - /// .collect(); - /// assert_eq!(merged, "alphabetagamma"); - /// ``` - /// - /// You can also rewrite this in terms of [`flat_map()`], which is preferable - /// in this case since it conveys intent more clearly: - /// - /// ``` - /// let words = ["alpha", "beta", "gamma"]; - /// - /// // chars() returns an iterator - /// let merged: String = words.iter() - /// .flat_map(|s| s.chars()) - /// .collect(); - /// assert_eq!(merged, "alphabetagamma"); - /// ``` - /// - /// Flattening works on any `IntoIterator` type, including `Option` and `Result`: - /// - /// ``` - /// let options = vec![Some(123), Some(321), None, Some(231)]; - /// let flattened_options: Vec<_> = options.into_iter().flatten().collect(); - /// assert_eq!(flattened_options, vec![123, 321, 231]); - /// - /// let results = vec![Ok(123), Ok(321), Err(456), Ok(231)]; - /// let flattened_results: Vec<_> = results.into_iter().flatten().collect(); - /// assert_eq!(flattened_results, vec![123, 321, 231]); - /// ``` - /// - /// Flattening only removes one level of nesting at a time: - /// - /// ``` - /// let d3 = [[[1, 2], [3, 4]], [[5, 6], [7, 8]]]; - /// - /// let d2 = d3.iter().flatten().collect::>(); - /// assert_eq!(d2, [&[1, 2], &[3, 4], &[5, 6], &[7, 8]]); - /// - /// let d1 = d3.iter().flatten().flatten().collect::>(); - /// assert_eq!(d1, [&1, &2, &3, &4, &5, &6, &7, &8]); - /// ``` - /// - /// Here we see that `flatten()` does not perform a "deep" flatten. - /// Instead, only one level of nesting is removed. That is, if you - /// `flatten()` a three-dimensional array, the result will be - /// two-dimensional and not one-dimensional. To get a one-dimensional - /// structure, you have to `flatten()` again. - /// - /// [`flat_map()`]: Iterator::flat_map - #[inline] - #[stable(feature = "iterator_flatten", since = "1.29.0")] - #[rustc_do_not_const_check] - fn flatten(self) -> Flatten - where - Self: Sized, - Self::Item: IntoIterator, - { - Flatten::new(self) - } - - /// Calls the given function `f` for each contiguous window of size `N` over - /// `self` and returns an iterator over the outputs of `f`. Like [`slice::windows()`], - /// the windows during mapping overlap as well. - /// - /// In the following example, the closure is called three times with the - /// arguments `&['a', 'b']`, `&['b', 'c']` and `&['c', 'd']` respectively. - /// - /// ``` - /// #![feature(iter_map_windows)] - /// - /// let strings = "abcd".chars() - /// .map_windows(|[x, y]| format!("{}+{}", x, y)) - /// .collect::>(); - /// - /// assert_eq!(strings, vec!["a+b", "b+c", "c+d"]); - /// ``` - /// - /// Note that the const parameter `N` is usually inferred by the - /// destructured argument in the closure. - /// - /// The returned iterator yields 𝑘 − `N` + 1 items (where 𝑘 is the number of - /// items yielded by `self`). If 𝑘 is less than `N`, this method yields an - /// empty iterator. - /// - /// The returned iterator implements [`FusedIterator`], because once `self` - /// returns `None`, even if it returns a `Some(T)` again in the next iterations, - /// we cannot put it into a contiguous array buffer, and thus the returned iterator - /// should be fused. - /// - /// [`slice::windows()`]: slice::windows - /// [`FusedIterator`]: crate::iter::FusedIterator - /// - /// # Panics - /// - /// Panics if `N` is 0. This check will most probably get changed to a - /// compile time error before this method gets stabilized. - /// - /// ```should_panic - /// #![feature(iter_map_windows)] - /// - /// let iter = std::iter::repeat(0).map_windows(|&[]| ()); - /// ``` - /// - /// # Examples - /// - /// Building the sums of neighboring numbers. - /// - /// ``` - /// #![feature(iter_map_windows)] - /// - /// let mut it = [1, 3, 8, 1].iter().map_windows(|&[a, b]| a + b); - /// assert_eq!(it.next(), Some(4)); // 1 + 3 - /// assert_eq!(it.next(), Some(11)); // 3 + 8 - /// assert_eq!(it.next(), Some(9)); // 8 + 1 - /// assert_eq!(it.next(), None); - /// ``` - /// - /// Since the elements in the following example implement `Copy`, we can - /// just copy the array and get an iterator over the windows. - /// - /// ``` - /// #![feature(iter_map_windows)] - /// - /// let mut it = "ferris".chars().map_windows(|w: &[_; 3]| *w); - /// assert_eq!(it.next(), Some(['f', 'e', 'r'])); - /// assert_eq!(it.next(), Some(['e', 'r', 'r'])); - /// assert_eq!(it.next(), Some(['r', 'r', 'i'])); - /// assert_eq!(it.next(), Some(['r', 'i', 's'])); - /// assert_eq!(it.next(), None); - /// ``` - /// - /// You can also use this function to check the sortedness of an iterator. - /// For the simple case, rather use [`Iterator::is_sorted`]. - /// - /// ``` - /// #![feature(iter_map_windows)] - /// - /// let mut it = [0.5, 1.0, 3.5, 3.0, 8.5, 8.5, f32::NAN].iter() - /// .map_windows(|[a, b]| a <= b); - /// - /// assert_eq!(it.next(), Some(true)); // 0.5 <= 1.0 - /// assert_eq!(it.next(), Some(true)); // 1.0 <= 3.5 - /// assert_eq!(it.next(), Some(false)); // 3.5 <= 3.0 - /// assert_eq!(it.next(), Some(true)); // 3.0 <= 8.5 - /// assert_eq!(it.next(), Some(true)); // 8.5 <= 8.5 - /// assert_eq!(it.next(), Some(false)); // 8.5 <= NAN - /// assert_eq!(it.next(), None); - /// ``` - /// - /// For non-fused iterators, they are fused after `map_windows`. - /// - /// ``` - /// #![feature(iter_map_windows)] - /// - /// #[derive(Default)] - /// struct NonFusedIterator { - /// state: i32, - /// } - /// - /// impl Iterator for NonFusedIterator { - /// type Item = i32; - /// - /// fn next(&mut self) -> Option { - /// let val = self.state; - /// self.state = self.state + 1; - /// - /// // yields `0..5` first, then only even numbers since `6..`. - /// if val < 5 || val % 2 == 0 { - /// Some(val) - /// } else { - /// None - /// } - /// } - /// } - /// - /// - /// let mut iter = NonFusedIterator::default(); - /// - /// // yields 0..5 first. - /// assert_eq!(iter.next(), Some(0)); - /// assert_eq!(iter.next(), Some(1)); - /// assert_eq!(iter.next(), Some(2)); - /// assert_eq!(iter.next(), Some(3)); - /// assert_eq!(iter.next(), Some(4)); - /// // then we can see our iterator going back and forth - /// assert_eq!(iter.next(), None); - /// assert_eq!(iter.next(), Some(6)); - /// assert_eq!(iter.next(), None); - /// assert_eq!(iter.next(), Some(8)); - /// assert_eq!(iter.next(), None); - /// - /// // however, with `.map_windows()`, it is fused. - /// let mut iter = NonFusedIterator::default() - /// .map_windows(|arr: &[_; 2]| *arr); - /// - /// assert_eq!(iter.next(), Some([0, 1])); - /// assert_eq!(iter.next(), Some([1, 2])); - /// assert_eq!(iter.next(), Some([2, 3])); - /// assert_eq!(iter.next(), Some([3, 4])); - /// assert_eq!(iter.next(), None); - /// - /// // it will always return `None` after the first time. - /// assert_eq!(iter.next(), None); - /// assert_eq!(iter.next(), None); - /// assert_eq!(iter.next(), None); - /// ``` - #[inline] - #[unstable(feature = "iter_map_windows", reason = "recently added", issue = "87155")] - #[rustc_do_not_const_check] - fn map_windows(self, f: F) -> MapWindows - where - Self: Sized, - F: FnMut(&[Self::Item; N]) -> R, - { - MapWindows::new(self, f) - } - - /// Creates an iterator which ends after the first [`None`]. - /// - /// After an iterator returns [`None`], future calls may or may not yield - /// [`Some(T)`] again. `fuse()` adapts an iterator, ensuring that after a - /// [`None`] is given, it will always return [`None`] forever. - /// - /// Note that the [`Fuse`] wrapper is a no-op on iterators that implement - /// the [`FusedIterator`] trait. `fuse()` may therefore behave incorrectly - /// if the [`FusedIterator`] trait is improperly implemented. - /// - /// [`Some(T)`]: Some - /// [`FusedIterator`]: crate::iter::FusedIterator - /// - /// # Examples - /// - /// ``` - /// // an iterator which alternates between Some and None - /// struct Alternate { - /// state: i32, - /// } - /// - /// impl Iterator for Alternate { - /// type Item = i32; - /// - /// fn next(&mut self) -> Option { - /// let val = self.state; - /// self.state = self.state + 1; - /// - /// // if it's even, Some(i32), else None - /// if val % 2 == 0 { - /// Some(val) - /// } else { - /// None - /// } - /// } - /// } - /// - /// let mut iter = Alternate { state: 0 }; - /// - /// // we can see our iterator going back and forth - /// assert_eq!(iter.next(), Some(0)); - /// assert_eq!(iter.next(), None); - /// assert_eq!(iter.next(), Some(2)); - /// assert_eq!(iter.next(), None); - /// - /// // however, once we fuse it... - /// let mut iter = iter.fuse(); - /// - /// assert_eq!(iter.next(), Some(4)); - /// assert_eq!(iter.next(), None); - /// - /// // it will always return `None` after the first time. - /// assert_eq!(iter.next(), None); - /// assert_eq!(iter.next(), None); - /// assert_eq!(iter.next(), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn fuse(self) -> Fuse - where - Self: Sized, - { - Fuse::new(self) - } - - /// Does something with each element of an iterator, passing the value on. - /// - /// When using iterators, you'll often chain several of them together. - /// While working on such code, you might want to check out what's - /// happening at various parts in the pipeline. To do that, insert - /// a call to `inspect()`. - /// - /// It's more common for `inspect()` to be used as a debugging tool than to - /// exist in your final code, but applications may find it useful in certain - /// situations when errors need to be logged before being discarded. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = [1, 4, 2, 3]; - /// - /// // this iterator sequence is complex. - /// let sum = a.iter() - /// .cloned() - /// .filter(|x| x % 2 == 0) - /// .fold(0, |sum, i| sum + i); - /// - /// println!("{sum}"); - /// - /// // let's add some inspect() calls to investigate what's happening - /// let sum = a.iter() - /// .cloned() - /// .inspect(|x| println!("about to filter: {x}")) - /// .filter(|x| x % 2 == 0) - /// .inspect(|x| println!("made it through filter: {x}")) - /// .fold(0, |sum, i| sum + i); - /// - /// println!("{sum}"); - /// ``` - /// - /// This will print: - /// - /// ```text - /// 6 - /// about to filter: 1 - /// about to filter: 4 - /// made it through filter: 4 - /// about to filter: 2 - /// made it through filter: 2 - /// about to filter: 3 - /// 6 - /// ``` - /// - /// Logging errors before discarding them: - /// - /// ``` - /// let lines = ["1", "2", "a"]; - /// - /// let sum: i32 = lines - /// .iter() - /// .map(|line| line.parse::()) - /// .inspect(|num| { - /// if let Err(ref e) = *num { - /// println!("Parsing error: {e}"); - /// } - /// }) - /// .filter_map(Result::ok) - /// .sum(); - /// - /// println!("Sum: {sum}"); - /// ``` - /// - /// This will print: - /// - /// ```text - /// Parsing error: invalid digit found in string - /// Sum: 3 - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn inspect(self, f: F) -> Inspect - where - Self: Sized, - F: FnMut(&Self::Item), - { - Inspect::new(self, f) - } - - /// Borrows an iterator, rather than consuming it. - /// - /// This is useful to allow applying iterator adapters while still - /// retaining ownership of the original iterator. - /// - /// # Examples - /// - /// ``` - /// let mut words = ["hello", "world", "of", "Rust"].into_iter(); - /// - /// // Take the first two words. - /// let hello_world: Vec<_> = words.by_ref().take(2).collect(); - /// assert_eq!(hello_world, vec!["hello", "world"]); - /// - /// // Collect the rest of the words. - /// // We can only do this because we used `by_ref` earlier. - /// let of_rust: Vec<_> = words.collect(); - /// assert_eq!(of_rust, vec!["of", "Rust"]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn by_ref(&mut self) -> &mut Self - where - Self: Sized, - { - self - } - - /// Transforms an iterator into a collection. - /// - /// `collect()` can take anything iterable, and turn it into a relevant - /// collection. This is one of the more powerful methods in the standard - /// library, used in a variety of contexts. - /// - /// The most basic pattern in which `collect()` is used is to turn one - /// collection into another. You take a collection, call [`iter`] on it, - /// do a bunch of transformations, and then `collect()` at the end. - /// - /// `collect()` can also create instances of types that are not typical - /// collections. For example, a [`String`] can be built from [`char`]s, - /// and an iterator of [`Result`][`Result`] items can be collected - /// into `Result, E>`. See the examples below for more. - /// - /// Because `collect()` is so general, it can cause problems with type - /// inference. As such, `collect()` is one of the few times you'll see - /// the syntax affectionately known as the 'turbofish': `::<>`. This - /// helps the inference algorithm understand specifically which collection - /// you're trying to collect into. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// let doubled: Vec = a.iter() - /// .map(|&x| x * 2) - /// .collect(); - /// - /// assert_eq!(vec![2, 4, 6], doubled); - /// ``` - /// - /// Note that we needed the `: Vec` on the left-hand side. This is because - /// we could collect into, for example, a [`VecDeque`] instead: - /// - /// [`VecDeque`]: ../../std/collections/struct.VecDeque.html - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let a = [1, 2, 3]; - /// - /// let doubled: VecDeque = a.iter().map(|&x| x * 2).collect(); - /// - /// assert_eq!(2, doubled[0]); - /// assert_eq!(4, doubled[1]); - /// assert_eq!(6, doubled[2]); - /// ``` - /// - /// Using the 'turbofish' instead of annotating `doubled`: - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// let doubled = a.iter().map(|x| x * 2).collect::>(); - /// - /// assert_eq!(vec![2, 4, 6], doubled); - /// ``` - /// - /// Because `collect()` only cares about what you're collecting into, you can - /// still use a partial type hint, `_`, with the turbofish: - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// let doubled = a.iter().map(|x| x * 2).collect::>(); - /// - /// assert_eq!(vec![2, 4, 6], doubled); - /// ``` - /// - /// Using `collect()` to make a [`String`]: - /// - /// ``` - /// let chars = ['g', 'd', 'k', 'k', 'n']; - /// - /// let hello: String = chars.iter() - /// .map(|&x| x as u8) - /// .map(|x| (x + 1) as char) - /// .collect(); - /// - /// assert_eq!("hello", hello); - /// ``` - /// - /// If you have a list of [`Result`][`Result`]s, you can use `collect()` to - /// see if any of them failed: - /// - /// ``` - /// let results = [Ok(1), Err("nope"), Ok(3), Err("bad")]; - /// - /// let result: Result, &str> = results.iter().cloned().collect(); - /// - /// // gives us the first error - /// assert_eq!(Err("nope"), result); - /// - /// let results = [Ok(1), Ok(3)]; - /// - /// let result: Result, &str> = results.iter().cloned().collect(); - /// - /// // gives us the list of answers - /// assert_eq!(Ok(vec![1, 3]), result); - /// ``` - /// - /// [`iter`]: Iterator::next - /// [`String`]: ../../std/string/struct.String.html - /// [`char`]: type@char - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use = "if you really need to exhaust the iterator, consider `.for_each(drop)` instead"] - #[cfg_attr(not(test), rustc_diagnostic_item = "iterator_collect_fn")] - #[rustc_do_not_const_check] - fn collect>(self) -> B - where - Self: Sized, - { - FromIterator::from_iter(self) - } - - /// Fallibly transforms an iterator into a collection, short circuiting if - /// a failure is encountered. - /// - /// `try_collect()` is a variation of [`collect()`][`collect`] that allows fallible - /// conversions during collection. Its main use case is simplifying conversions from - /// iterators yielding [`Option`][`Option`] into `Option>`, or similarly for other [`Try`] - /// types (e.g. [`Result`]). - /// - /// Importantly, `try_collect()` doesn't require that the outer [`Try`] type also implements [`FromIterator`]; - /// only the inner type produced on `Try::Output` must implement it. Concretely, - /// this means that collecting into `ControlFlow<_, Vec>` is valid because `Vec` implements - /// [`FromIterator`], even though [`ControlFlow`] doesn't. - /// - /// Also, if a failure is encountered during `try_collect()`, the iterator is still valid and - /// may continue to be used, in which case it will continue iterating starting after the element that - /// triggered the failure. See the last example below for an example of how this works. - /// - /// # Examples - /// Successfully collecting an iterator of `Option` into `Option>`: - /// ``` - /// #![feature(iterator_try_collect)] - /// - /// let u = vec![Some(1), Some(2), Some(3)]; - /// let v = u.into_iter().try_collect::>(); - /// assert_eq!(v, Some(vec![1, 2, 3])); - /// ``` - /// - /// Failing to collect in the same way: - /// ``` - /// #![feature(iterator_try_collect)] - /// - /// let u = vec![Some(1), Some(2), None, Some(3)]; - /// let v = u.into_iter().try_collect::>(); - /// assert_eq!(v, None); - /// ``` - /// - /// A similar example, but with `Result`: - /// ``` - /// #![feature(iterator_try_collect)] - /// - /// let u: Vec> = vec![Ok(1), Ok(2), Ok(3)]; - /// let v = u.into_iter().try_collect::>(); - /// assert_eq!(v, Ok(vec![1, 2, 3])); - /// - /// let u = vec![Ok(1), Ok(2), Err(()), Ok(3)]; - /// let v = u.into_iter().try_collect::>(); - /// assert_eq!(v, Err(())); - /// ``` - /// - /// Finally, even [`ControlFlow`] works, despite the fact that it - /// doesn't implement [`FromIterator`]. Note also that the iterator can - /// continue to be used, even if a failure is encountered: - /// - /// ``` - /// #![feature(iterator_try_collect)] - /// - /// use core::ops::ControlFlow::{Break, Continue}; - /// - /// let u = [Continue(1), Continue(2), Break(3), Continue(4), Continue(5)]; - /// let mut it = u.into_iter(); - /// - /// let v = it.try_collect::>(); - /// assert_eq!(v, Break(3)); - /// - /// let v = it.try_collect::>(); - /// assert_eq!(v, Continue(vec![4, 5])); - /// ``` - /// - /// [`collect`]: Iterator::collect - #[inline] - #[unstable(feature = "iterator_try_collect", issue = "94047")] - #[rustc_do_not_const_check] - fn try_collect(&mut self) -> ChangeOutputType - where - Self: Sized, - ::Item: Try, - <::Item as Try>::Residual: Residual, - B: FromIterator<::Output>, - { - try_process(ByRefSized(self), |i| i.collect()) - } - - /// Collects all the items from an iterator into a collection. - /// - /// This method consumes the iterator and adds all its items to the - /// passed collection. The collection is then returned, so the call chain - /// can be continued. - /// - /// This is useful when you already have a collection and want to add - /// the iterator items to it. - /// - /// This method is a convenience method to call [Extend::extend](trait.Extend.html), - /// but instead of being called on a collection, it's called on an iterator. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(iter_collect_into)] - /// - /// let a = [1, 2, 3]; - /// let mut vec: Vec:: = vec![0, 1]; - /// - /// a.iter().map(|&x| x * 2).collect_into(&mut vec); - /// a.iter().map(|&x| x * 10).collect_into(&mut vec); - /// - /// assert_eq!(vec, vec![0, 1, 2, 4, 6, 10, 20, 30]); - /// ``` - /// - /// `Vec` can have a manual set capacity to avoid reallocating it: - /// - /// ``` - /// #![feature(iter_collect_into)] - /// - /// let a = [1, 2, 3]; - /// let mut vec: Vec:: = Vec::with_capacity(6); - /// - /// a.iter().map(|&x| x * 2).collect_into(&mut vec); - /// a.iter().map(|&x| x * 10).collect_into(&mut vec); - /// - /// assert_eq!(6, vec.capacity()); - /// assert_eq!(vec, vec![2, 4, 6, 10, 20, 30]); - /// ``` - /// - /// The returned mutable reference can be used to continue the call chain: - /// - /// ``` - /// #![feature(iter_collect_into)] - /// - /// let a = [1, 2, 3]; - /// let mut vec: Vec:: = Vec::with_capacity(6); - /// - /// let count = a.iter().collect_into(&mut vec).iter().count(); - /// - /// assert_eq!(count, vec.len()); - /// assert_eq!(vec, vec![1, 2, 3]); - /// - /// let count = a.iter().collect_into(&mut vec).iter().count(); - /// - /// assert_eq!(count, vec.len()); - /// assert_eq!(vec, vec![1, 2, 3, 1, 2, 3]); - /// ``` - #[inline] - #[unstable(feature = "iter_collect_into", reason = "new API", issue = "94780")] - #[rustc_do_not_const_check] - fn collect_into>(self, collection: &mut E) -> &mut E - where - Self: Sized, - { - collection.extend(self); - collection - } - - /// Consumes an iterator, creating two collections from it. - /// - /// The predicate passed to `partition()` can return `true`, or `false`. - /// `partition()` returns a pair, all of the elements for which it returned - /// `true`, and all of the elements for which it returned `false`. - /// - /// See also [`is_partitioned()`] and [`partition_in_place()`]. - /// - /// [`is_partitioned()`]: Iterator::is_partitioned - /// [`partition_in_place()`]: Iterator::partition_in_place - /// - /// # Examples - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// let (even, odd): (Vec<_>, Vec<_>) = a - /// .into_iter() - /// .partition(|n| n % 2 == 0); - /// - /// assert_eq!(even, vec![2]); - /// assert_eq!(odd, vec![1, 3]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn partition(self, f: F) -> (B, B) - where - Self: Sized, - B: Default + Extend, - F: FnMut(&Self::Item) -> bool, - { - #[inline] - fn extend<'a, T, B: Extend>( - mut f: impl FnMut(&T) -> bool + 'a, - left: &'a mut B, - right: &'a mut B, - ) -> impl FnMut((), T) + 'a { - move |(), x| { - if f(&x) { - left.extend_one(x); - } else { - right.extend_one(x); - } - } - } - - let mut left: B = Default::default(); - let mut right: B = Default::default(); - - self.fold((), extend(f, &mut left, &mut right)); - - (left, right) - } - - /// Reorders the elements of this iterator *in-place* according to the given predicate, - /// such that all those that return `true` precede all those that return `false`. - /// Returns the number of `true` elements found. - /// - /// The relative order of partitioned items is not maintained. - /// - /// # Current implementation - /// - /// The current algorithm tries to find the first element for which the predicate evaluates - /// to false and the last element for which it evaluates to true, and repeatedly swaps them. - /// - /// Time complexity: *O*(*n*) - /// - /// See also [`is_partitioned()`] and [`partition()`]. - /// - /// [`is_partitioned()`]: Iterator::is_partitioned - /// [`partition()`]: Iterator::partition - /// - /// # Examples - /// - /// ``` - /// #![feature(iter_partition_in_place)] - /// - /// let mut a = [1, 2, 3, 4, 5, 6, 7]; - /// - /// // Partition in-place between evens and odds - /// let i = a.iter_mut().partition_in_place(|&n| n % 2 == 0); - /// - /// assert_eq!(i, 3); - /// assert!(a[..i].iter().all(|&n| n % 2 == 0)); // evens - /// assert!(a[i..].iter().all(|&n| n % 2 == 1)); // odds - /// ``` - #[unstable(feature = "iter_partition_in_place", reason = "new API", issue = "62543")] - #[rustc_do_not_const_check] - fn partition_in_place<'a, T: 'a, P>(mut self, ref mut predicate: P) -> usize - where - Self: Sized + DoubleEndedIterator, - P: FnMut(&T) -> bool, - { - // FIXME: should we worry about the count overflowing? The only way to have more than - // `usize::MAX` mutable references is with ZSTs, which aren't useful to partition... - - // These closure "factory" functions exist to avoid genericity in `Self`. - - #[inline] - fn is_false<'a, T>( - predicate: &'a mut impl FnMut(&T) -> bool, - true_count: &'a mut usize, - ) -> impl FnMut(&&mut T) -> bool + 'a { - move |x| { - let p = predicate(&**x); - *true_count += p as usize; - !p - } - } - - #[inline] - fn is_true(predicate: &mut impl FnMut(&T) -> bool) -> impl FnMut(&&mut T) -> bool + '_ { - move |x| predicate(&**x) - } - - // Repeatedly find the first `false` and swap it with the last `true`. - let mut true_count = 0; - while let Some(head) = self.find(is_false(predicate, &mut true_count)) { - if let Some(tail) = self.rfind(is_true(predicate)) { - crate::mem::swap(head, tail); - true_count += 1; - } else { - break; - } - } - true_count - } - - /// Checks if the elements of this iterator are partitioned according to the given predicate, - /// such that all those that return `true` precede all those that return `false`. - /// - /// See also [`partition()`] and [`partition_in_place()`]. - /// - /// [`partition()`]: Iterator::partition - /// [`partition_in_place()`]: Iterator::partition_in_place - /// - /// # Examples - /// - /// ``` - /// #![feature(iter_is_partitioned)] - /// - /// assert!("Iterator".chars().is_partitioned(char::is_uppercase)); - /// assert!(!"IntoIterator".chars().is_partitioned(char::is_uppercase)); - /// ``` - #[unstable(feature = "iter_is_partitioned", reason = "new API", issue = "62544")] - #[rustc_do_not_const_check] - fn is_partitioned

(mut self, mut predicate: P) -> bool - where - Self: Sized, - P: FnMut(Self::Item) -> bool, - { - // Either all items test `true`, or the first clause stops at `false` - // and we check that there are no more `true` items after that. - self.all(&mut predicate) || !self.any(predicate) - } - - /// An iterator method that applies a function as long as it returns - /// successfully, producing a single, final value. - /// - /// `try_fold()` takes two arguments: an initial value, and a closure with - /// two arguments: an 'accumulator', and an element. The closure either - /// returns successfully, with the value that the accumulator should have - /// for the next iteration, or it returns failure, with an error value that - /// is propagated back to the caller immediately (short-circuiting). - /// - /// The initial value is the value the accumulator will have on the first - /// call. If applying the closure succeeded against every element of the - /// iterator, `try_fold()` returns the final accumulator as success. - /// - /// Folding is useful whenever you have a collection of something, and want - /// to produce a single value from it. - /// - /// # Note to Implementors - /// - /// Several of the other (forward) methods have default implementations in - /// terms of this one, so try to implement this explicitly if it can - /// do something better than the default `for` loop implementation. - /// - /// In particular, try to have this call `try_fold()` on the internal parts - /// from which this iterator is composed. If multiple calls are needed, - /// the `?` operator may be convenient for chaining the accumulator value - /// along, but beware any invariants that need to be upheld before those - /// early returns. This is a `&mut self` method, so iteration needs to be - /// resumable after hitting an error here. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// // the checked sum of all of the elements of the array - /// let sum = a.iter().try_fold(0i8, |acc, &x| acc.checked_add(x)); - /// - /// assert_eq!(sum, Some(6)); - /// ``` - /// - /// Short-circuiting: - /// - /// ``` - /// let a = [10, 20, 30, 100, 40, 50]; - /// let mut it = a.iter(); - /// - /// // This sum overflows when adding the 100 element - /// let sum = it.try_fold(0i8, |acc, &x| acc.checked_add(x)); - /// assert_eq!(sum, None); - /// - /// // Because it short-circuited, the remaining elements are still - /// // available through the iterator. - /// assert_eq!(it.len(), 2); - /// assert_eq!(it.next(), Some(&40)); - /// ``` - /// - /// While you cannot `break` from a closure, the [`ControlFlow`] type allows - /// a similar idea: - /// - /// ``` - /// use std::ops::ControlFlow; - /// - /// let triangular = (1..30).try_fold(0_i8, |prev, x| { - /// if let Some(next) = prev.checked_add(x) { - /// ControlFlow::Continue(next) - /// } else { - /// ControlFlow::Break(prev) - /// } - /// }); - /// assert_eq!(triangular, ControlFlow::Break(120)); - /// - /// let triangular = (1..30).try_fold(0_u64, |prev, x| { - /// if let Some(next) = prev.checked_add(x) { - /// ControlFlow::Continue(next) - /// } else { - /// ControlFlow::Break(prev) - /// } - /// }); - /// assert_eq!(triangular, ControlFlow::Continue(435)); - /// ``` - #[inline] - #[stable(feature = "iterator_try_fold", since = "1.27.0")] - #[rustc_do_not_const_check] - fn try_fold(&mut self, init: B, mut f: F) -> R - where - Self: Sized, - F: FnMut(B, Self::Item) -> R, - R: Try, - { - let mut accum = init; - while let Some(x) = self.next() { - accum = f(accum, x)?; - } - try { accum } - } - - /// An iterator method that applies a fallible function to each item in the - /// iterator, stopping at the first error and returning that error. - /// - /// This can also be thought of as the fallible form of [`for_each()`] - /// or as the stateless version of [`try_fold()`]. - /// - /// [`for_each()`]: Iterator::for_each - /// [`try_fold()`]: Iterator::try_fold - /// - /// # Examples - /// - /// ``` - /// use std::fs::rename; - /// use std::io::{stdout, Write}; - /// use std::path::Path; - /// - /// let data = ["no_tea.txt", "stale_bread.json", "torrential_rain.png"]; - /// - /// let res = data.iter().try_for_each(|x| writeln!(stdout(), "{x}")); - /// assert!(res.is_ok()); - /// - /// let mut it = data.iter().cloned(); - /// let res = it.try_for_each(|x| rename(x, Path::new(x).with_extension("old"))); - /// assert!(res.is_err()); - /// // It short-circuited, so the remaining items are still in the iterator: - /// assert_eq!(it.next(), Some("stale_bread.json")); - /// ``` - /// - /// The [`ControlFlow`] type can be used with this method for the situations - /// in which you'd use `break` and `continue` in a normal loop: - /// - /// ``` - /// use std::ops::ControlFlow; - /// - /// let r = (2..100).try_for_each(|x| { - /// if 323 % x == 0 { - /// return ControlFlow::Break(x) - /// } - /// - /// ControlFlow::Continue(()) - /// }); - /// assert_eq!(r, ControlFlow::Break(17)); - /// ``` - #[inline] - #[stable(feature = "iterator_try_fold", since = "1.27.0")] - #[rustc_do_not_const_check] - fn try_for_each(&mut self, f: F) -> R - where - Self: Sized, - F: FnMut(Self::Item) -> R, - R: Try, - { - #[inline] - fn call(mut f: impl FnMut(T) -> R) -> impl FnMut((), T) -> R { - move |(), x| f(x) - } - - self.try_fold((), call(f)) - } - - /// Folds every element into an accumulator by applying an operation, - /// returning the final result. - /// - /// `fold()` takes two arguments: an initial value, and a closure with two - /// arguments: an 'accumulator', and an element. The closure returns the value that - /// the accumulator should have for the next iteration. - /// - /// The initial value is the value the accumulator will have on the first - /// call. - /// - /// After applying this closure to every element of the iterator, `fold()` - /// returns the accumulator. - /// - /// This operation is sometimes called 'reduce' or 'inject'. - /// - /// Folding is useful whenever you have a collection of something, and want - /// to produce a single value from it. - /// - /// Note: `fold()`, and similar methods that traverse the entire iterator, - /// might not terminate for infinite iterators, even on traits for which a - /// result is determinable in finite time. - /// - /// Note: [`reduce()`] can be used to use the first element as the initial - /// value, if the accumulator type and item type is the same. - /// - /// Note: `fold()` combines elements in a *left-associative* fashion. For associative - /// operators like `+`, the order the elements are combined in is not important, but for non-associative - /// operators like `-` the order will affect the final result. - /// For a *right-associative* version of `fold()`, see [`DoubleEndedIterator::rfold()`]. - /// - /// # Note to Implementors - /// - /// Several of the other (forward) methods have default implementations in - /// terms of this one, so try to implement this explicitly if it can - /// do something better than the default `for` loop implementation. - /// - /// In particular, try to have this call `fold()` on the internal parts - /// from which this iterator is composed. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// // the sum of all of the elements of the array - /// let sum = a.iter().fold(0, |acc, x| acc + x); - /// - /// assert_eq!(sum, 6); - /// ``` - /// - /// Let's walk through each step of the iteration here: - /// - /// | element | acc | x | result | - /// |---------|-----|---|--------| - /// | | 0 | | | - /// | 1 | 0 | 1 | 1 | - /// | 2 | 1 | 2 | 3 | - /// | 3 | 3 | 3 | 6 | - /// - /// And so, our final result, `6`. - /// - /// This example demonstrates the left-associative nature of `fold()`: - /// it builds a string, starting with an initial value - /// and continuing with each element from the front until the back: - /// - /// ``` - /// let numbers = [1, 2, 3, 4, 5]; - /// - /// let zero = "0".to_string(); - /// - /// let result = numbers.iter().fold(zero, |acc, &x| { - /// format!("({acc} + {x})") - /// }); - /// - /// assert_eq!(result, "(((((0 + 1) + 2) + 3) + 4) + 5)"); - /// ``` - /// It's common for people who haven't used iterators a lot to - /// use a `for` loop with a list of things to build up a result. Those - /// can be turned into `fold()`s: - /// - /// [`for`]: ../../book/ch03-05-control-flow.html#looping-through-a-collection-with-for - /// - /// ``` - /// let numbers = [1, 2, 3, 4, 5]; - /// - /// let mut result = 0; - /// - /// // for loop: - /// for i in &numbers { - /// result = result + i; - /// } - /// - /// // fold: - /// let result2 = numbers.iter().fold(0, |acc, &x| acc + x); - /// - /// // they're the same - /// assert_eq!(result, result2); - /// ``` - /// - /// [`reduce()`]: Iterator::reduce - #[doc(alias = "inject", alias = "foldl")] - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn fold(mut self, init: B, mut f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - let mut accum = init; - while let Some(x) = self.next() { - accum = f(accum, x); - } - accum - } - - /// Reduces the elements to a single one, by repeatedly applying a reducing - /// operation. - /// - /// If the iterator is empty, returns [`None`]; otherwise, returns the - /// result of the reduction. - /// - /// The reducing function is a closure with two arguments: an 'accumulator', and an element. - /// For iterators with at least one element, this is the same as [`fold()`] - /// with the first element of the iterator as the initial accumulator value, folding - /// every subsequent element into it. - /// - /// [`fold()`]: Iterator::fold - /// - /// # Example - /// - /// ``` - /// let reduced: i32 = (1..10).reduce(|acc, e| acc + e).unwrap(); - /// assert_eq!(reduced, 45); - /// - /// // Which is equivalent to doing it with `fold`: - /// let folded: i32 = (1..10).fold(0, |acc, e| acc + e); - /// assert_eq!(reduced, folded); - /// ``` - #[inline] - #[stable(feature = "iterator_fold_self", since = "1.51.0")] - #[rustc_do_not_const_check] - fn reduce(mut self, f: F) -> Option - where - Self: Sized, - F: FnMut(Self::Item, Self::Item) -> Self::Item, - { - let first = self.next()?; - Some(self.fold(first, f)) - } - - /// Reduces the elements to a single one by repeatedly applying a reducing operation. If the - /// closure returns a failure, the failure is propagated back to the caller immediately. - /// - /// The return type of this method depends on the return type of the closure. If the closure - /// returns `Result`, then this function will return `Result, - /// E>`. If the closure returns `Option`, then this function will return - /// `Option>`. - /// - /// When called on an empty iterator, this function will return either `Some(None)` or - /// `Ok(None)` depending on the type of the provided closure. - /// - /// For iterators with at least one element, this is essentially the same as calling - /// [`try_fold()`] with the first element of the iterator as the initial accumulator value. - /// - /// [`try_fold()`]: Iterator::try_fold - /// - /// # Examples - /// - /// Safely calculate the sum of a series of numbers: - /// - /// ``` - /// #![feature(iterator_try_reduce)] - /// - /// let numbers: Vec = vec![10, 20, 5, 23, 0]; - /// let sum = numbers.into_iter().try_reduce(|x, y| x.checked_add(y)); - /// assert_eq!(sum, Some(Some(58))); - /// ``` - /// - /// Determine when a reduction short circuited: - /// - /// ``` - /// #![feature(iterator_try_reduce)] - /// - /// let numbers = vec![1, 2, 3, usize::MAX, 4, 5]; - /// let sum = numbers.into_iter().try_reduce(|x, y| x.checked_add(y)); - /// assert_eq!(sum, None); - /// ``` - /// - /// Determine when a reduction was not performed because there are no elements: - /// - /// ``` - /// #![feature(iterator_try_reduce)] - /// - /// let numbers: Vec = Vec::new(); - /// let sum = numbers.into_iter().try_reduce(|x, y| x.checked_add(y)); - /// assert_eq!(sum, Some(None)); - /// ``` - /// - /// Use a [`Result`] instead of an [`Option`]: - /// - /// ``` - /// #![feature(iterator_try_reduce)] - /// - /// let numbers = vec!["1", "2", "3", "4", "5"]; - /// let max: Result, ::Err> = - /// numbers.into_iter().try_reduce(|x, y| { - /// if x.parse::()? > y.parse::()? { Ok(x) } else { Ok(y) } - /// }); - /// assert_eq!(max, Ok(Some("5"))); - /// ``` - #[inline] - #[unstable(feature = "iterator_try_reduce", reason = "new API", issue = "87053")] - #[rustc_do_not_const_check] - fn try_reduce(&mut self, f: F) -> ChangeOutputType> - where - Self: Sized, - F: FnMut(Self::Item, Self::Item) -> R, - R: Try, - R::Residual: Residual>, - { - let first = match self.next() { - Some(i) => i, - None => return Try::from_output(None), - }; - - match self.try_fold(first, f).branch() { - ControlFlow::Break(r) => FromResidual::from_residual(r), - ControlFlow::Continue(i) => Try::from_output(Some(i)), - } - } - - /// Tests if every element of the iterator matches a predicate. - /// - /// `all()` takes a closure that returns `true` or `false`. It applies - /// this closure to each element of the iterator, and if they all return - /// `true`, then so does `all()`. If any of them return `false`, it - /// returns `false`. - /// - /// `all()` is short-circuiting; in other words, it will stop processing - /// as soon as it finds a `false`, given that no matter what else happens, - /// the result will also be `false`. - /// - /// An empty iterator returns `true`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// assert!(a.iter().all(|&x| x > 0)); - /// - /// assert!(!a.iter().all(|&x| x > 2)); - /// ``` - /// - /// Stopping at the first `false`: - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// let mut iter = a.iter(); - /// - /// assert!(!iter.all(|&x| x != 2)); - /// - /// // we can still use `iter`, as there are more elements. - /// assert_eq!(iter.next(), Some(&3)); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn all(&mut self, f: F) -> bool - where - Self: Sized, - F: FnMut(Self::Item) -> bool, - { - #[inline] - fn check(mut f: impl FnMut(T) -> bool) -> impl FnMut((), T) -> ControlFlow<()> { - move |(), x| { - if f(x) { ControlFlow::Continue(()) } else { ControlFlow::Break(()) } - } - } - self.try_fold((), check(f)) == ControlFlow::Continue(()) - } - - /// Tests if any element of the iterator matches a predicate. - /// - /// `any()` takes a closure that returns `true` or `false`. It applies - /// this closure to each element of the iterator, and if any of them return - /// `true`, then so does `any()`. If they all return `false`, it - /// returns `false`. - /// - /// `any()` is short-circuiting; in other words, it will stop processing - /// as soon as it finds a `true`, given that no matter what else happens, - /// the result will also be `true`. - /// - /// An empty iterator returns `false`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// assert!(a.iter().any(|&x| x > 0)); - /// - /// assert!(!a.iter().any(|&x| x > 5)); - /// ``` - /// - /// Stopping at the first `true`: - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// let mut iter = a.iter(); - /// - /// assert!(iter.any(|&x| x != 2)); - /// - /// // we can still use `iter`, as there are more elements. - /// assert_eq!(iter.next(), Some(&2)); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn any(&mut self, f: F) -> bool - where - Self: Sized, - F: FnMut(Self::Item) -> bool, - { - #[inline] - fn check(mut f: impl FnMut(T) -> bool) -> impl FnMut((), T) -> ControlFlow<()> { - move |(), x| { - if f(x) { ControlFlow::Break(()) } else { ControlFlow::Continue(()) } - } - } - - self.try_fold((), check(f)) == ControlFlow::Break(()) - } - - /// Searches for an element of an iterator that satisfies a predicate. - /// - /// `find()` takes a closure that returns `true` or `false`. It applies - /// this closure to each element of the iterator, and if any of them return - /// `true`, then `find()` returns [`Some(element)`]. If they all return - /// `false`, it returns [`None`]. - /// - /// `find()` is short-circuiting; in other words, it will stop processing - /// as soon as the closure returns `true`. - /// - /// Because `find()` takes a reference, and many iterators iterate over - /// references, this leads to a possibly confusing situation where the - /// argument is a double reference. You can see this effect in the - /// examples below, with `&&x`. - /// - /// If you need the index of the element, see [`position()`]. - /// - /// [`Some(element)`]: Some - /// [`position()`]: Iterator::position - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// assert_eq!(a.iter().find(|&&x| x == 2), Some(&2)); - /// - /// assert_eq!(a.iter().find(|&&x| x == 5), None); - /// ``` - /// - /// Stopping at the first `true`: - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// let mut iter = a.iter(); - /// - /// assert_eq!(iter.find(|&&x| x == 2), Some(&2)); - /// - /// // we can still use `iter`, as there are more elements. - /// assert_eq!(iter.next(), Some(&3)); - /// ``` - /// - /// Note that `iter.find(f)` is equivalent to `iter.filter(f).next()`. - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn find

(&mut self, predicate: P) -> Option - where - Self: Sized, - P: FnMut(&Self::Item) -> bool, - { - #[inline] - fn check(mut predicate: impl FnMut(&T) -> bool) -> impl FnMut((), T) -> ControlFlow { - move |(), x| { - if predicate(&x) { ControlFlow::Break(x) } else { ControlFlow::Continue(()) } - } - } - - self.try_fold((), check(predicate)).break_value() - } - - /// Applies function to the elements of iterator and returns - /// the first non-none result. - /// - /// `iter.find_map(f)` is equivalent to `iter.filter_map(f).next()`. - /// - /// # Examples - /// - /// ``` - /// let a = ["lol", "NaN", "2", "5"]; - /// - /// let first_number = a.iter().find_map(|s| s.parse().ok()); - /// - /// assert_eq!(first_number, Some(2)); - /// ``` - #[inline] - #[stable(feature = "iterator_find_map", since = "1.30.0")] - #[rustc_do_not_const_check] - fn find_map(&mut self, f: F) -> Option - where - Self: Sized, - F: FnMut(Self::Item) -> Option, - { - #[inline] - fn check(mut f: impl FnMut(T) -> Option) -> impl FnMut((), T) -> ControlFlow { - move |(), x| match f(x) { - Some(x) => ControlFlow::Break(x), - None => ControlFlow::Continue(()), - } - } - - self.try_fold((), check(f)).break_value() - } - - /// Applies function to the elements of iterator and returns - /// the first true result or the first error. - /// - /// The return type of this method depends on the return type of the closure. - /// If you return `Result` from the closure, you'll get a `Result, E>`. - /// If you return `Option` from the closure, you'll get an `Option>`. - /// - /// # Examples - /// - /// ``` - /// #![feature(try_find)] - /// - /// let a = ["1", "2", "lol", "NaN", "5"]; - /// - /// let is_my_num = |s: &str, search: i32| -> Result { - /// Ok(s.parse::()? == search) - /// }; - /// - /// let result = a.iter().try_find(|&&s| is_my_num(s, 2)); - /// assert_eq!(result, Ok(Some(&"2"))); - /// - /// let result = a.iter().try_find(|&&s| is_my_num(s, 5)); - /// assert!(result.is_err()); - /// ``` - /// - /// This also supports other types which implement [`Try`], not just [`Result`]. - /// - /// ``` - /// #![feature(try_find)] - /// - /// use std::num::NonZero; - /// - /// let a = [3, 5, 7, 4, 9, 0, 11u32]; - /// let result = a.iter().try_find(|&&x| NonZero::new(x).map(|y| y.is_power_of_two())); - /// assert_eq!(result, Some(Some(&4))); - /// let result = a.iter().take(3).try_find(|&&x| NonZero::new(x).map(|y| y.is_power_of_two())); - /// assert_eq!(result, Some(None)); - /// let result = a.iter().rev().try_find(|&&x| NonZero::new(x).map(|y| y.is_power_of_two())); - /// assert_eq!(result, None); - /// ``` - #[inline] - #[unstable(feature = "try_find", reason = "new API", issue = "63178")] - #[rustc_do_not_const_check] - fn try_find(&mut self, f: F) -> ChangeOutputType> - where - Self: Sized, - F: FnMut(&Self::Item) -> R, - R: Try, - R::Residual: Residual>, - { - #[inline] - fn check( - mut f: impl FnMut(&I) -> V, - ) -> impl FnMut((), I) -> ControlFlow - where - V: Try, - R: Residual>, - { - move |(), x| match f(&x).branch() { - ControlFlow::Continue(false) => ControlFlow::Continue(()), - ControlFlow::Continue(true) => ControlFlow::Break(Try::from_output(Some(x))), - ControlFlow::Break(r) => ControlFlow::Break(FromResidual::from_residual(r)), - } - } - - match self.try_fold((), check(f)) { - ControlFlow::Break(x) => x, - ControlFlow::Continue(()) => Try::from_output(None), - } - } - - /// Searches for an element in an iterator, returning its index. - /// - /// `position()` takes a closure that returns `true` or `false`. It applies - /// this closure to each element of the iterator, and if one of them - /// returns `true`, then `position()` returns [`Some(index)`]. If all of - /// them return `false`, it returns [`None`]. - /// - /// `position()` is short-circuiting; in other words, it will stop - /// processing as soon as it finds a `true`. - /// - /// # Overflow Behavior - /// - /// The method does no guarding against overflows, so if there are more - /// than [`usize::MAX`] non-matching elements, it either produces the wrong - /// result or panics. If debug assertions are enabled, a panic is - /// guaranteed. - /// - /// # Panics - /// - /// This function might panic if the iterator has more than `usize::MAX` - /// non-matching elements. - /// - /// [`Some(index)`]: Some - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// assert_eq!(a.iter().position(|&x| x == 2), Some(1)); - /// - /// assert_eq!(a.iter().position(|&x| x == 5), None); - /// ``` - /// - /// Stopping at the first `true`: - /// - /// ``` - /// let a = [1, 2, 3, 4]; - /// - /// let mut iter = a.iter(); - /// - /// assert_eq!(iter.position(|&x| x >= 2), Some(1)); - /// - /// // we can still use `iter`, as there are more elements. - /// assert_eq!(iter.next(), Some(&3)); - /// - /// // The returned index depends on iterator state - /// assert_eq!(iter.position(|&x| x == 4), Some(0)); - /// - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn position

(&mut self, predicate: P) -> Option - where - Self: Sized, - P: FnMut(Self::Item) -> bool, - { - #[inline] - fn check<'a, T>( - mut predicate: impl FnMut(T) -> bool + 'a, - acc: &'a mut usize, - ) -> impl FnMut((), T) -> ControlFlow + 'a { - #[rustc_inherit_overflow_checks] - move |_, x| { - if predicate(x) { - ControlFlow::Break(*acc) - } else { - *acc += 1; - ControlFlow::Continue(()) - } - } - } - - let mut acc = 0; - self.try_fold((), check(predicate, &mut acc)).break_value() - } - - /// Searches for an element in an iterator from the right, returning its - /// index. - /// - /// `rposition()` takes a closure that returns `true` or `false`. It applies - /// this closure to each element of the iterator, starting from the end, - /// and if one of them returns `true`, then `rposition()` returns - /// [`Some(index)`]. If all of them return `false`, it returns [`None`]. - /// - /// `rposition()` is short-circuiting; in other words, it will stop - /// processing as soon as it finds a `true`. - /// - /// [`Some(index)`]: Some - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// assert_eq!(a.iter().rposition(|&x| x == 3), Some(2)); - /// - /// assert_eq!(a.iter().rposition(|&x| x == 5), None); - /// ``` - /// - /// Stopping at the first `true`: - /// - /// ``` - /// let a = [-1, 2, 3, 4]; - /// - /// let mut iter = a.iter(); - /// - /// assert_eq!(iter.rposition(|&x| x >= 2), Some(3)); - /// - /// // we can still use `iter`, as there are more elements. - /// assert_eq!(iter.next(), Some(&-1)); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn rposition

(&mut self, predicate: P) -> Option - where - P: FnMut(Self::Item) -> bool, - Self: Sized + ExactSizeIterator + DoubleEndedIterator, - { - // No need for an overflow check here, because `ExactSizeIterator` - // implies that the number of elements fits into a `usize`. - #[inline] - fn check( - mut predicate: impl FnMut(T) -> bool, - ) -> impl FnMut(usize, T) -> ControlFlow { - move |i, x| { - let i = i - 1; - if predicate(x) { ControlFlow::Break(i) } else { ControlFlow::Continue(i) } - } - } - - let n = self.len(); - self.try_rfold(n, check(predicate)).break_value() - } - - /// Returns the maximum element of an iterator. - /// - /// If several elements are equally maximum, the last element is - /// returned. If the iterator is empty, [`None`] is returned. - /// - /// Note that [`f32`]/[`f64`] doesn't implement [`Ord`] due to NaN being - /// incomparable. You can work around this by using [`Iterator::reduce`]: - /// ``` - /// assert_eq!( - /// [2.4, f32::NAN, 1.3] - /// .into_iter() - /// .reduce(f32::max) - /// .unwrap(), - /// 2.4 - /// ); - /// ``` - /// - /// # Examples - /// - /// ``` - /// let a = [1, 2, 3]; - /// let b: Vec = Vec::new(); - /// - /// assert_eq!(a.iter().max(), Some(&3)); - /// assert_eq!(b.iter().max(), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn max(self) -> Option - where - Self: Sized, - Self::Item: Ord, - { - self.max_by(Ord::cmp) - } - - /// Returns the minimum element of an iterator. - /// - /// If several elements are equally minimum, the first element is returned. - /// If the iterator is empty, [`None`] is returned. - /// - /// Note that [`f32`]/[`f64`] doesn't implement [`Ord`] due to NaN being - /// incomparable. You can work around this by using [`Iterator::reduce`]: - /// ``` - /// assert_eq!( - /// [2.4, f32::NAN, 1.3] - /// .into_iter() - /// .reduce(f32::min) - /// .unwrap(), - /// 1.3 - /// ); - /// ``` - /// - /// # Examples - /// - /// ``` - /// let a = [1, 2, 3]; - /// let b: Vec = Vec::new(); - /// - /// assert_eq!(a.iter().min(), Some(&1)); - /// assert_eq!(b.iter().min(), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn min(self) -> Option - where - Self: Sized, - Self::Item: Ord, - { - self.min_by(Ord::cmp) - } - - /// Returns the element that gives the maximum value from the - /// specified function. - /// - /// If several elements are equally maximum, the last element is - /// returned. If the iterator is empty, [`None`] is returned. - /// - /// # Examples - /// - /// ``` - /// let a = [-3_i32, 0, 1, 5, -10]; - /// assert_eq!(*a.iter().max_by_key(|x| x.abs()).unwrap(), -10); - /// ``` - #[inline] - #[stable(feature = "iter_cmp_by_key", since = "1.6.0")] - #[rustc_do_not_const_check] - fn max_by_key(self, f: F) -> Option - where - Self: Sized, - F: FnMut(&Self::Item) -> B, - { - #[inline] - fn key(mut f: impl FnMut(&T) -> B) -> impl FnMut(T) -> (B, T) { - move |x| (f(&x), x) - } - - #[inline] - fn compare((x_p, _): &(B, T), (y_p, _): &(B, T)) -> Ordering { - x_p.cmp(y_p) - } - - let (_, x) = self.map(key(f)).max_by(compare)?; - Some(x) - } - - /// Returns the element that gives the maximum value with respect to the - /// specified comparison function. - /// - /// If several elements are equally maximum, the last element is - /// returned. If the iterator is empty, [`None`] is returned. - /// - /// # Examples - /// - /// ``` - /// let a = [-3_i32, 0, 1, 5, -10]; - /// assert_eq!(*a.iter().max_by(|x, y| x.cmp(y)).unwrap(), 5); - /// ``` - #[inline] - #[stable(feature = "iter_max_by", since = "1.15.0")] - #[rustc_do_not_const_check] - fn max_by(self, compare: F) -> Option - where - Self: Sized, - F: FnMut(&Self::Item, &Self::Item) -> Ordering, - { - #[inline] - fn fold(mut compare: impl FnMut(&T, &T) -> Ordering) -> impl FnMut(T, T) -> T { - move |x, y| cmp::max_by(x, y, &mut compare) - } - - self.reduce(fold(compare)) - } - - /// Returns the element that gives the minimum value from the - /// specified function. - /// - /// If several elements are equally minimum, the first element is - /// returned. If the iterator is empty, [`None`] is returned. - /// - /// # Examples - /// - /// ``` - /// let a = [-3_i32, 0, 1, 5, -10]; - /// assert_eq!(*a.iter().min_by_key(|x| x.abs()).unwrap(), 0); - /// ``` - #[inline] - #[stable(feature = "iter_cmp_by_key", since = "1.6.0")] - #[rustc_do_not_const_check] - fn min_by_key(self, f: F) -> Option - where - Self: Sized, - F: FnMut(&Self::Item) -> B, - { - #[inline] - fn key(mut f: impl FnMut(&T) -> B) -> impl FnMut(T) -> (B, T) { - move |x| (f(&x), x) - } - - #[inline] - fn compare((x_p, _): &(B, T), (y_p, _): &(B, T)) -> Ordering { - x_p.cmp(y_p) - } - - let (_, x) = self.map(key(f)).min_by(compare)?; - Some(x) - } - - /// Returns the element that gives the minimum value with respect to the - /// specified comparison function. - /// - /// If several elements are equally minimum, the first element is - /// returned. If the iterator is empty, [`None`] is returned. - /// - /// # Examples - /// - /// ``` - /// let a = [-3_i32, 0, 1, 5, -10]; - /// assert_eq!(*a.iter().min_by(|x, y| x.cmp(y)).unwrap(), -10); - /// ``` - #[inline] - #[stable(feature = "iter_min_by", since = "1.15.0")] - #[rustc_do_not_const_check] - fn min_by(self, compare: F) -> Option - where - Self: Sized, - F: FnMut(&Self::Item, &Self::Item) -> Ordering, - { - #[inline] - fn fold(mut compare: impl FnMut(&T, &T) -> Ordering) -> impl FnMut(T, T) -> T { - move |x, y| cmp::min_by(x, y, &mut compare) - } - - self.reduce(fold(compare)) - } - - /// Reverses an iterator's direction. - /// - /// Usually, iterators iterate from left to right. After using `rev()`, - /// an iterator will instead iterate from right to left. - /// - /// This is only possible if the iterator has an end, so `rev()` only - /// works on [`DoubleEndedIterator`]s. - /// - /// # Examples - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// let mut iter = a.iter().rev(); - /// - /// assert_eq!(iter.next(), Some(&3)); - /// assert_eq!(iter.next(), Some(&2)); - /// assert_eq!(iter.next(), Some(&1)); - /// - /// assert_eq!(iter.next(), None); - /// ``` - #[inline] - #[doc(alias = "reverse")] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn rev(self) -> Rev - where - Self: Sized + DoubleEndedIterator, - { - Rev::new(self) - } - - /// Converts an iterator of pairs into a pair of containers. - /// - /// `unzip()` consumes an entire iterator of pairs, producing two - /// collections: one from the left elements of the pairs, and one - /// from the right elements. - /// - /// This function is, in some sense, the opposite of [`zip`]. - /// - /// [`zip`]: Iterator::zip - /// - /// # Examples - /// - /// ``` - /// let a = [(1, 2), (3, 4), (5, 6)]; - /// - /// let (left, right): (Vec<_>, Vec<_>) = a.iter().cloned().unzip(); - /// - /// assert_eq!(left, [1, 3, 5]); - /// assert_eq!(right, [2, 4, 6]); - /// - /// // you can also unzip multiple nested tuples at once - /// let a = [(1, (2, 3)), (4, (5, 6))]; - /// - /// let (x, (y, z)): (Vec<_>, (Vec<_>, Vec<_>)) = a.iter().cloned().unzip(); - /// assert_eq!(x, [1, 4]); - /// assert_eq!(y, [2, 5]); - /// assert_eq!(z, [3, 6]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn unzip(self) -> (FromA, FromB) - where - FromA: Default + Extend, - FromB: Default + Extend, - Self: Sized + Iterator, - { - let mut unzipped: (FromA, FromB) = Default::default(); - unzipped.extend(self); - unzipped - } - - /// Creates an iterator which copies all of its elements. - /// - /// This is useful when you have an iterator over `&T`, but you need an - /// iterator over `T`. - /// - /// # Examples - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// let v_copied: Vec<_> = a.iter().copied().collect(); - /// - /// // copied is the same as .map(|&x| x) - /// let v_map: Vec<_> = a.iter().map(|&x| x).collect(); - /// - /// assert_eq!(v_copied, vec![1, 2, 3]); - /// assert_eq!(v_map, vec![1, 2, 3]); - /// ``` - #[stable(feature = "iter_copied", since = "1.36.0")] - #[rustc_do_not_const_check] - fn copied<'a, T: 'a>(self) -> Copied - where - Self: Sized + Iterator, - T: Copy, - { - Copied::new(self) - } - - /// Creates an iterator which [`clone`]s all of its elements. - /// - /// This is useful when you have an iterator over `&T`, but you need an - /// iterator over `T`. - /// - /// There is no guarantee whatsoever about the `clone` method actually - /// being called *or* optimized away. So code should not depend on - /// either. - /// - /// [`clone`]: Clone::clone - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// let v_cloned: Vec<_> = a.iter().cloned().collect(); - /// - /// // cloned is the same as .map(|&x| x), for integers - /// let v_map: Vec<_> = a.iter().map(|&x| x).collect(); - /// - /// assert_eq!(v_cloned, vec![1, 2, 3]); - /// assert_eq!(v_map, vec![1, 2, 3]); - /// ``` - /// - /// To get the best performance, try to clone late: - /// - /// ``` - /// let a = [vec![0_u8, 1, 2], vec![3, 4], vec![23]]; - /// // don't do this: - /// let slower: Vec<_> = a.iter().cloned().filter(|s| s.len() == 1).collect(); - /// assert_eq!(&[vec![23]], &slower[..]); - /// // instead call `cloned` late - /// let faster: Vec<_> = a.iter().filter(|s| s.len() == 1).cloned().collect(); - /// assert_eq!(&[vec![23]], &faster[..]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_do_not_const_check] - fn cloned<'a, T: 'a>(self) -> Cloned - where - Self: Sized + Iterator, - T: Clone, - { - Cloned::new(self) - } - - /// Repeats an iterator endlessly. - /// - /// Instead of stopping at [`None`], the iterator will instead start again, - /// from the beginning. After iterating again, it will start at the - /// beginning again. And again. And again. Forever. Note that in case the - /// original iterator is empty, the resulting iterator will also be empty. - /// - /// # Examples - /// - /// ``` - /// let a = [1, 2, 3]; - /// - /// let mut it = a.iter().cycle(); - /// - /// assert_eq!(it.next(), Some(&1)); - /// assert_eq!(it.next(), Some(&2)); - /// assert_eq!(it.next(), Some(&3)); - /// assert_eq!(it.next(), Some(&1)); - /// assert_eq!(it.next(), Some(&2)); - /// assert_eq!(it.next(), Some(&3)); - /// assert_eq!(it.next(), Some(&1)); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - #[rustc_do_not_const_check] - fn cycle(self) -> Cycle - where - Self: Sized + Clone, - { - Cycle::new(self) - } - - /// Returns an iterator over `N` elements of the iterator at a time. - /// - /// The chunks do not overlap. If `N` does not divide the length of the - /// iterator, then the last up to `N-1` elements will be omitted and can be - /// retrieved from the [`.into_remainder()`][ArrayChunks::into_remainder] - /// function of the iterator. - /// - /// # Panics - /// - /// Panics if `N` is 0. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(iter_array_chunks)] - /// - /// let mut iter = "lorem".chars().array_chunks(); - /// assert_eq!(iter.next(), Some(['l', 'o'])); - /// assert_eq!(iter.next(), Some(['r', 'e'])); - /// assert_eq!(iter.next(), None); - /// assert_eq!(iter.into_remainder().unwrap().as_slice(), &['m']); - /// ``` - /// - /// ``` - /// #![feature(iter_array_chunks)] - /// - /// let data = [1, 1, 2, -2, 6, 0, 3, 1]; - /// // ^-----^ ^------^ - /// for [x, y, z] in data.iter().array_chunks() { - /// assert_eq!(x + y + z, 4); - /// } - /// ``` - #[track_caller] - #[unstable(feature = "iter_array_chunks", reason = "recently added", issue = "100450")] - #[rustc_do_not_const_check] - fn array_chunks(self) -> ArrayChunks - where - Self: Sized, - { - ArrayChunks::new(self) - } - - /// Sums the elements of an iterator. - /// - /// Takes each element, adds them together, and returns the result. - /// - /// An empty iterator returns the zero value of the type. - /// - /// `sum()` can be used to sum any type implementing [`Sum`][`core::iter::Sum`], - /// including [`Option`][`Option::sum`] and [`Result`][`Result::sum`]. - /// - /// # Panics - /// - /// When calling `sum()` and a primitive integer type is being returned, this - /// method will panic if the computation overflows and debug assertions are - /// enabled. - /// - /// # Examples - /// - /// ``` - /// let a = [1, 2, 3]; - /// let sum: i32 = a.iter().sum(); - /// - /// assert_eq!(sum, 6); - /// ``` - #[stable(feature = "iter_arith", since = "1.11.0")] - #[rustc_do_not_const_check] - fn sum(self) -> S - where - Self: Sized, - S: Sum, - { - Sum::sum(self) - } - - /// Iterates over the entire iterator, multiplying all the elements - /// - /// An empty iterator returns the one value of the type. - /// - /// `product()` can be used to multiply any type implementing [`Product`][`core::iter::Product`], - /// including [`Option`][`Option::product`] and [`Result`][`Result::product`]. - /// - /// # Panics - /// - /// When calling `product()` and a primitive integer type is being returned, - /// method will panic if the computation overflows and debug assertions are - /// enabled. - /// - /// # Examples - /// - /// ``` - /// fn factorial(n: u32) -> u32 { - /// (1..=n).product() - /// } - /// assert_eq!(factorial(0), 1); - /// assert_eq!(factorial(1), 1); - /// assert_eq!(factorial(5), 120); - /// ``` - #[stable(feature = "iter_arith", since = "1.11.0")] - #[rustc_do_not_const_check] - fn product

(self) -> P - where - Self: Sized, - P: Product, - { - Product::product(self) - } - - /// [Lexicographically](Ord#lexicographical-comparison) compares the elements of this [`Iterator`] with those - /// of another. - /// - /// # Examples - /// - /// ``` - /// use std::cmp::Ordering; - /// - /// assert_eq!([1].iter().cmp([1].iter()), Ordering::Equal); - /// assert_eq!([1].iter().cmp([1, 2].iter()), Ordering::Less); - /// assert_eq!([1, 2].iter().cmp([1].iter()), Ordering::Greater); - /// ``` - #[stable(feature = "iter_order", since = "1.5.0")] - #[rustc_do_not_const_check] - fn cmp(self, other: I) -> Ordering - where - I: IntoIterator, - Self::Item: Ord, - Self: Sized, - { - self.cmp_by(other, |x, y| x.cmp(&y)) - } - - /// [Lexicographically](Ord#lexicographical-comparison) compares the elements of this [`Iterator`] with those - /// of another with respect to the specified comparison function. - /// - /// # Examples - /// - /// ``` - /// #![feature(iter_order_by)] - /// - /// use std::cmp::Ordering; - /// - /// let xs = [1, 2, 3, 4]; - /// let ys = [1, 4, 9, 16]; - /// - /// assert_eq!(xs.iter().cmp_by(&ys, |&x, &y| x.cmp(&y)), Ordering::Less); - /// assert_eq!(xs.iter().cmp_by(&ys, |&x, &y| (x * x).cmp(&y)), Ordering::Equal); - /// assert_eq!(xs.iter().cmp_by(&ys, |&x, &y| (2 * x).cmp(&y)), Ordering::Greater); - /// ``` - #[unstable(feature = "iter_order_by", issue = "64295")] - #[rustc_do_not_const_check] - fn cmp_by(self, other: I, cmp: F) -> Ordering - where - Self: Sized, - I: IntoIterator, - F: FnMut(Self::Item, I::Item) -> Ordering, - { - #[inline] - fn compare(mut cmp: F) -> impl FnMut(X, Y) -> ControlFlow - where - F: FnMut(X, Y) -> Ordering, - { - move |x, y| match cmp(x, y) { - Ordering::Equal => ControlFlow::Continue(()), - non_eq => ControlFlow::Break(non_eq), - } - } - - match iter_compare(self, other.into_iter(), compare(cmp)) { - ControlFlow::Continue(ord) => ord, - ControlFlow::Break(ord) => ord, - } - } - - /// [Lexicographically](Ord#lexicographical-comparison) compares the [`PartialOrd`] elements of - /// this [`Iterator`] with those of another. The comparison works like short-circuit - /// evaluation, returning a result without comparing the remaining elements. - /// As soon as an order can be determined, the evaluation stops and a result is returned. - /// - /// # Examples - /// - /// ``` - /// use std::cmp::Ordering; - /// - /// assert_eq!([1.].iter().partial_cmp([1.].iter()), Some(Ordering::Equal)); - /// assert_eq!([1.].iter().partial_cmp([1., 2.].iter()), Some(Ordering::Less)); - /// assert_eq!([1., 2.].iter().partial_cmp([1.].iter()), Some(Ordering::Greater)); - /// ``` - /// - /// For floating-point numbers, NaN does not have a total order and will result - /// in `None` when compared: - /// - /// ``` - /// assert_eq!([f64::NAN].iter().partial_cmp([1.].iter()), None); - /// ``` - /// - /// The results are determined by the order of evaluation. - /// - /// ``` - /// use std::cmp::Ordering; - /// - /// assert_eq!([1.0, f64::NAN].iter().partial_cmp([2.0, f64::NAN].iter()), Some(Ordering::Less)); - /// assert_eq!([2.0, f64::NAN].iter().partial_cmp([1.0, f64::NAN].iter()), Some(Ordering::Greater)); - /// assert_eq!([f64::NAN, 1.0].iter().partial_cmp([f64::NAN, 2.0].iter()), None); - /// ``` - /// - #[stable(feature = "iter_order", since = "1.5.0")] - #[rustc_do_not_const_check] - fn partial_cmp(self, other: I) -> Option - where - I: IntoIterator, - Self::Item: PartialOrd, - Self: Sized, - { - self.partial_cmp_by(other, |x, y| x.partial_cmp(&y)) - } - - /// [Lexicographically](Ord#lexicographical-comparison) compares the elements of this [`Iterator`] with those - /// of another with respect to the specified comparison function. - /// - /// # Examples - /// - /// ``` - /// #![feature(iter_order_by)] - /// - /// use std::cmp::Ordering; - /// - /// let xs = [1.0, 2.0, 3.0, 4.0]; - /// let ys = [1.0, 4.0, 9.0, 16.0]; - /// - /// assert_eq!( - /// xs.iter().partial_cmp_by(&ys, |&x, &y| x.partial_cmp(&y)), - /// Some(Ordering::Less) - /// ); - /// assert_eq!( - /// xs.iter().partial_cmp_by(&ys, |&x, &y| (x * x).partial_cmp(&y)), - /// Some(Ordering::Equal) - /// ); - /// assert_eq!( - /// xs.iter().partial_cmp_by(&ys, |&x, &y| (2.0 * x).partial_cmp(&y)), - /// Some(Ordering::Greater) - /// ); - /// ``` - #[unstable(feature = "iter_order_by", issue = "64295")] - #[rustc_do_not_const_check] - fn partial_cmp_by(self, other: I, partial_cmp: F) -> Option - where - Self: Sized, - I: IntoIterator, - F: FnMut(Self::Item, I::Item) -> Option, - { - #[inline] - fn compare(mut partial_cmp: F) -> impl FnMut(X, Y) -> ControlFlow> - where - F: FnMut(X, Y) -> Option, - { - move |x, y| match partial_cmp(x, y) { - Some(Ordering::Equal) => ControlFlow::Continue(()), - non_eq => ControlFlow::Break(non_eq), - } - } - - match iter_compare(self, other.into_iter(), compare(partial_cmp)) { - ControlFlow::Continue(ord) => Some(ord), - ControlFlow::Break(ord) => ord, - } - } - - /// Determines if the elements of this [`Iterator`] are equal to those of - /// another. - /// - /// # Examples - /// - /// ``` - /// assert_eq!([1].iter().eq([1].iter()), true); - /// assert_eq!([1].iter().eq([1, 2].iter()), false); - /// ``` - #[stable(feature = "iter_order", since = "1.5.0")] - #[rustc_do_not_const_check] - fn eq(self, other: I) -> bool - where - I: IntoIterator, - Self::Item: PartialEq, - Self: Sized, - { - self.eq_by(other, |x, y| x == y) - } - - /// Determines if the elements of this [`Iterator`] are equal to those of - /// another with respect to the specified equality function. - /// - /// # Examples - /// - /// ``` - /// #![feature(iter_order_by)] - /// - /// let xs = [1, 2, 3, 4]; - /// let ys = [1, 4, 9, 16]; - /// - /// assert!(xs.iter().eq_by(&ys, |&x, &y| x * x == y)); - /// ``` - #[unstable(feature = "iter_order_by", issue = "64295")] - #[rustc_do_not_const_check] - fn eq_by(self, other: I, eq: F) -> bool - where - Self: Sized, - I: IntoIterator, - F: FnMut(Self::Item, I::Item) -> bool, - { - #[inline] - fn compare(mut eq: F) -> impl FnMut(X, Y) -> ControlFlow<()> - where - F: FnMut(X, Y) -> bool, - { - move |x, y| { - if eq(x, y) { ControlFlow::Continue(()) } else { ControlFlow::Break(()) } - } - } - - match iter_compare(self, other.into_iter(), compare(eq)) { - ControlFlow::Continue(ord) => ord == Ordering::Equal, - ControlFlow::Break(()) => false, - } - } - - /// Determines if the elements of this [`Iterator`] are not equal to those of - /// another. - /// - /// # Examples - /// - /// ``` - /// assert_eq!([1].iter().ne([1].iter()), false); - /// assert_eq!([1].iter().ne([1, 2].iter()), true); - /// ``` - #[stable(feature = "iter_order", since = "1.5.0")] - #[rustc_do_not_const_check] - fn ne(self, other: I) -> bool - where - I: IntoIterator, - Self::Item: PartialEq, - Self: Sized, - { - !self.eq(other) - } - - /// Determines if the elements of this [`Iterator`] are [lexicographically](Ord#lexicographical-comparison) - /// less than those of another. - /// - /// # Examples - /// - /// ``` - /// assert_eq!([1].iter().lt([1].iter()), false); - /// assert_eq!([1].iter().lt([1, 2].iter()), true); - /// assert_eq!([1, 2].iter().lt([1].iter()), false); - /// assert_eq!([1, 2].iter().lt([1, 2].iter()), false); - /// ``` - #[stable(feature = "iter_order", since = "1.5.0")] - #[rustc_do_not_const_check] - fn lt(self, other: I) -> bool - where - I: IntoIterator, - Self::Item: PartialOrd, - Self: Sized, - { - self.partial_cmp(other) == Some(Ordering::Less) - } - - /// Determines if the elements of this [`Iterator`] are [lexicographically](Ord#lexicographical-comparison) - /// less or equal to those of another. - /// - /// # Examples - /// - /// ``` - /// assert_eq!([1].iter().le([1].iter()), true); - /// assert_eq!([1].iter().le([1, 2].iter()), true); - /// assert_eq!([1, 2].iter().le([1].iter()), false); - /// assert_eq!([1, 2].iter().le([1, 2].iter()), true); - /// ``` - #[stable(feature = "iter_order", since = "1.5.0")] - #[rustc_do_not_const_check] - fn le(self, other: I) -> bool - where - I: IntoIterator, - Self::Item: PartialOrd, - Self: Sized, - { - matches!(self.partial_cmp(other), Some(Ordering::Less | Ordering::Equal)) - } - - /// Determines if the elements of this [`Iterator`] are [lexicographically](Ord#lexicographical-comparison) - /// greater than those of another. - /// - /// # Examples - /// - /// ``` - /// assert_eq!([1].iter().gt([1].iter()), false); - /// assert_eq!([1].iter().gt([1, 2].iter()), false); - /// assert_eq!([1, 2].iter().gt([1].iter()), true); - /// assert_eq!([1, 2].iter().gt([1, 2].iter()), false); - /// ``` - #[stable(feature = "iter_order", since = "1.5.0")] - #[rustc_do_not_const_check] - fn gt(self, other: I) -> bool - where - I: IntoIterator, - Self::Item: PartialOrd, - Self: Sized, - { - self.partial_cmp(other) == Some(Ordering::Greater) - } - - /// Determines if the elements of this [`Iterator`] are [lexicographically](Ord#lexicographical-comparison) - /// greater than or equal to those of another. - /// - /// # Examples - /// - /// ``` - /// assert_eq!([1].iter().ge([1].iter()), true); - /// assert_eq!([1].iter().ge([1, 2].iter()), false); - /// assert_eq!([1, 2].iter().ge([1].iter()), true); - /// assert_eq!([1, 2].iter().ge([1, 2].iter()), true); - /// ``` - #[stable(feature = "iter_order", since = "1.5.0")] - #[rustc_do_not_const_check] - fn ge(self, other: I) -> bool - where - I: IntoIterator, - Self::Item: PartialOrd, - Self: Sized, - { - matches!(self.partial_cmp(other), Some(Ordering::Greater | Ordering::Equal)) - } - - /// Checks if the elements of this iterator are sorted. - /// - /// That is, for each element `a` and its following element `b`, `a <= b` must hold. If the - /// iterator yields exactly zero or one element, `true` is returned. - /// - /// Note that if `Self::Item` is only `PartialOrd`, but not `Ord`, the above definition - /// implies that this function returns `false` if any two consecutive items are not - /// comparable. - /// - /// # Examples - /// - /// ``` - /// #![feature(is_sorted)] - /// - /// assert!([1, 2, 2, 9].iter().is_sorted()); - /// assert!(![1, 3, 2, 4].iter().is_sorted()); - /// assert!([0].iter().is_sorted()); - /// assert!(std::iter::empty::().is_sorted()); - /// assert!(![0.0, 1.0, f32::NAN].iter().is_sorted()); - /// ``` - #[inline] - #[unstable(feature = "is_sorted", reason = "new API", issue = "53485")] - #[rustc_do_not_const_check] - fn is_sorted(self) -> bool - where - Self: Sized, - Self::Item: PartialOrd, - { - self.is_sorted_by(|a, b| a <= b) - } - - /// Checks if the elements of this iterator are sorted using the given comparator function. - /// - /// Instead of using `PartialOrd::partial_cmp`, this function uses the given `compare` - /// function to determine whether two elements are to be considered in sorted order. - /// - /// # Examples - /// - /// ``` - /// #![feature(is_sorted)] - /// - /// assert!([1, 2, 2, 9].iter().is_sorted_by(|a, b| a <= b)); - /// assert!(![1, 2, 2, 9].iter().is_sorted_by(|a, b| a < b)); - /// - /// assert!([0].iter().is_sorted_by(|a, b| true)); - /// assert!([0].iter().is_sorted_by(|a, b| false)); - /// - /// assert!(std::iter::empty::().is_sorted_by(|a, b| false)); - /// assert!(std::iter::empty::().is_sorted_by(|a, b| true)); - /// ``` - #[unstable(feature = "is_sorted", reason = "new API", issue = "53485")] - #[rustc_do_not_const_check] - fn is_sorted_by(mut self, compare: F) -> bool - where - Self: Sized, - F: FnMut(&Self::Item, &Self::Item) -> bool, - { - #[inline] - fn check<'a, T>( - last: &'a mut T, - mut compare: impl FnMut(&T, &T) -> bool + 'a, - ) -> impl FnMut(T) -> bool + 'a { - move |curr| { - if !compare(&last, &curr) { - return false; - } - *last = curr; - true - } - } - - let mut last = match self.next() { - Some(e) => e, - None => return true, - }; - - self.all(check(&mut last, compare)) - } - - /// Checks if the elements of this iterator are sorted using the given key extraction - /// function. - /// - /// Instead of comparing the iterator's elements directly, this function compares the keys of - /// the elements, as determined by `f`. Apart from that, it's equivalent to [`is_sorted`]; see - /// its documentation for more information. - /// - /// [`is_sorted`]: Iterator::is_sorted - /// - /// # Examples - /// - /// ``` - /// #![feature(is_sorted)] - /// - /// assert!(["c", "bb", "aaa"].iter().is_sorted_by_key(|s| s.len())); - /// assert!(![-2i32, -1, 0, 3].iter().is_sorted_by_key(|n| n.abs())); - /// ``` - #[inline] - #[unstable(feature = "is_sorted", reason = "new API", issue = "53485")] - #[rustc_do_not_const_check] - fn is_sorted_by_key(self, f: F) -> bool - where - Self: Sized, - F: FnMut(Self::Item) -> K, - K: PartialOrd, - { - self.map(f).is_sorted() - } - - /// See [TrustedRandomAccess][super::super::TrustedRandomAccess] - // The unusual name is to avoid name collisions in method resolution - // see #76479. - #[inline] - #[doc(hidden)] - #[unstable(feature = "trusted_random_access", issue = "none")] - #[rustc_do_not_const_check] - unsafe fn __iterator_get_unchecked(&mut self, _idx: usize) -> Self::Item - where - Self: TrustedRandomAccessNoCoerce, - { - unreachable!("Always specialized"); - } -} - -/// Compares two iterators element-wise using the given function. -/// -/// If `ControlFlow::Continue(())` is returned from the function, the comparison moves on to the next -/// elements of both iterators. Returning `ControlFlow::Break(x)` short-circuits the iteration and -/// returns `ControlFlow::Break(x)`. If one of the iterators runs out of elements, -/// `ControlFlow::Continue(ord)` is returned where `ord` is the result of comparing the lengths of -/// the iterators. -/// -/// Isolates the logic shared by ['cmp_by'](Iterator::cmp_by), -/// ['partial_cmp_by'](Iterator::partial_cmp_by), and ['eq_by'](Iterator::eq_by). -#[inline] -fn iter_compare(mut a: A, mut b: B, f: F) -> ControlFlow -where - A: Iterator, - B: Iterator, - F: FnMut(A::Item, B::Item) -> ControlFlow, -{ - #[inline] - fn compare<'a, B, X, T>( - b: &'a mut B, - mut f: impl FnMut(X, B::Item) -> ControlFlow + 'a, - ) -> impl FnMut(X) -> ControlFlow> + 'a - where - B: Iterator, - { - move |x| match b.next() { - None => ControlFlow::Break(ControlFlow::Continue(Ordering::Greater)), - Some(y) => f(x, y).map_break(ControlFlow::Break), - } - } - - match a.try_for_each(compare(&mut b, f)) { - ControlFlow::Continue(()) => ControlFlow::Continue(match b.next() { - None => Ordering::Equal, - Some(_) => Ordering::Less, - }), - ControlFlow::Break(x) => x, - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for &mut I { - type Item = I::Item; - #[inline] - fn next(&mut self) -> Option { - (**self).next() - } - fn size_hint(&self) -> (usize, Option) { - (**self).size_hint() - } - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - (**self).advance_by(n) - } - fn nth(&mut self, n: usize) -> Option { - (**self).nth(n) - } - fn fold(self, init: B, f: F) -> B - where - F: FnMut(B, Self::Item) -> B, - { - self.spec_fold(init, f) - } - fn try_fold(&mut self, init: B, f: F) -> R - where - F: FnMut(B, Self::Item) -> R, - R: Try, - { - self.spec_try_fold(init, f) - } -} - -/// Helper trait to specialize `fold` and `try_fold` for `&mut I where I: Sized` -trait IteratorRefSpec: Iterator { - fn spec_fold(self, init: B, f: F) -> B - where - F: FnMut(B, Self::Item) -> B; - - fn spec_try_fold(&mut self, init: B, f: F) -> R - where - F: FnMut(B, Self::Item) -> R, - R: Try; -} - -impl IteratorRefSpec for &mut I { - default fn spec_fold(self, init: B, mut f: F) -> B - where - F: FnMut(B, Self::Item) -> B, - { - let mut accum = init; - while let Some(x) = self.next() { - accum = f(accum, x); - } - accum - } - - default fn spec_try_fold(&mut self, init: B, mut f: F) -> R - where - F: FnMut(B, Self::Item) -> R, - R: Try, - { - let mut accum = init; - while let Some(x) = self.next() { - accum = f(accum, x)?; - } - try { accum } - } -} - -impl IteratorRefSpec for &mut I { - impl_fold_via_try_fold! { spec_fold -> spec_try_fold } - - fn spec_try_fold(&mut self, init: B, f: F) -> R - where - F: FnMut(B, Self::Item) -> R, - R: Try, - { - (**self).try_fold(init, f) - } -} diff --git a/library/core/src/iter/traits/marker.rs b/library/core/src/iter/traits/marker.rs deleted file mode 100644 index 2e756a6dd67c4..0000000000000 --- a/library/core/src/iter/traits/marker.rs +++ /dev/null @@ -1,116 +0,0 @@ -use crate::iter::Step; -use crate::num::NonZero; - -/// Same as FusedIterator -/// -/// # Safety -/// -/// This is used for specialization. Therefore implementations must not -/// be lifetime-dependent. -#[unstable(issue = "none", feature = "trusted_fused")] -#[doc(hidden)] -#[rustc_specialization_trait] -pub unsafe trait TrustedFused {} - -/// An iterator that always continues to yield `None` when exhausted. -/// -/// Calling next on a fused iterator that has returned `None` once is guaranteed -/// to return [`None`] again. This trait should be implemented by all iterators -/// that behave this way because it allows optimizing [`Iterator::fuse()`]. -/// -/// Note: In general, you should not use `FusedIterator` in generic bounds if -/// you need a fused iterator. Instead, you should just call [`Iterator::fuse()`] -/// on the iterator. If the iterator is already fused, the additional [`Fuse`] -/// wrapper will be a no-op with no performance penalty. -/// -/// [`Fuse`]: crate::iter::Fuse -#[stable(feature = "fused", since = "1.26.0")] -#[rustc_unsafe_specialization_marker] -// FIXME: this should be a #[marker] and have another blanket impl for T: TrustedFused -// but that ICEs iter::Fuse specializations. -#[lang = "fused_iterator"] -pub trait FusedIterator: Iterator {} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for &mut I {} - -/// An iterator that reports an accurate length using size_hint. -/// -/// The iterator reports a size hint where it is either exact -/// (lower bound is equal to upper bound), or the upper bound is [`None`]. -/// The upper bound must only be [`None`] if the actual iterator length is -/// larger than [`usize::MAX`]. In that case, the lower bound must be -/// [`usize::MAX`], resulting in an [`Iterator::size_hint()`] of -/// `(usize::MAX, None)`. -/// -/// The iterator must produce exactly the number of elements it reported -/// or diverge before reaching the end. -/// -/// # When *shouldn't* an adapter be `TrustedLen`? -/// -/// If an adapter makes an iterator *shorter* by a given amount, then it's -/// usually incorrect for that adapter to implement `TrustedLen`. The inner -/// iterator might return more than `usize::MAX` items, but there's no way to -/// know what `k` elements less than that will be, since the `size_hint` from -/// the inner iterator has already saturated and lost that information. -/// -/// This is why [`Skip`](crate::iter::Skip) isn't `TrustedLen`, even when -/// `I` implements `TrustedLen`. -/// -/// # Safety -/// -/// This trait must only be implemented when the contract is upheld. Consumers -/// of this trait must inspect [`Iterator::size_hint()`]’s upper bound. -#[unstable(feature = "trusted_len", issue = "37572")] -#[rustc_unsafe_specialization_marker] -pub unsafe trait TrustedLen: Iterator {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for &mut I {} - -/// An iterator that when yielding an item will have taken at least one element -/// from its underlying [`SourceIter`]. -/// -/// Calling any method that advances the iterator, e.g. [`next()`] or [`try_fold()`], -/// guarantees that for each step at least one value of the iterator's underlying source -/// has been moved out and the result of the iterator chain could be inserted -/// in its place, assuming structural constraints of the source allow such an insertion. -/// In other words this trait indicates that an iterator pipeline can be collected in place. -/// -/// The primary use of this trait is in-place iteration. Refer to the [`vec::in_place_collect`] -/// module documentation for more information. -/// -/// [`vec::in_place_collect`]: ../../../../alloc/vec/in_place_collect/index.html -/// [`SourceIter`]: crate::iter::SourceIter -/// [`next()`]: Iterator::next -/// [`try_fold()`]: Iterator::try_fold -#[unstable(issue = "none", feature = "inplace_iteration")] -#[doc(hidden)] -#[rustc_specialization_trait] -pub unsafe trait InPlaceIterable { - /// The product of one-to-many item expansions that happen throughout the iterator pipeline. - /// E.g. [[u8; 4]; 4].iter().flatten().flatten() would have a `EXPAND_BY` of 16. - /// This is an upper bound, i.e. the transformations will produce at most this many items per - /// input. It's meant for layout calculations. - const EXPAND_BY: Option>; - /// The product of many-to-one item reductions that happen throughout the iterator pipeline. - /// E.g. [u8].iter().array_chunks::<4>().array_chunks::<4>() would have a `MERGE_BY` of 16. - /// This is a lower bound, i.e. the transformations will consume at least this many items per - /// output. - const MERGE_BY: Option>; -} - -/// A type that upholds all invariants of [`Step`]. -/// -/// The invariants of [`Step::steps_between()`] are a superset of the invariants -/// of [`TrustedLen`]. As such, [`TrustedLen`] is implemented for all range -/// types with the same generic type argument. -/// -/// # Safety -/// -/// The implementation of [`Step`] for the given type must guarantee all -/// invariants of all methods are upheld. See the [`Step`] trait's documentation -/// for details. Consumers are free to rely on the invariants in unsafe code. -#[unstable(feature = "trusted_step", issue = "85731")] -#[rustc_specialization_trait] -pub unsafe trait TrustedStep: Step + Copy {} diff --git a/library/core/src/iter/traits/mod.rs b/library/core/src/iter/traits/mod.rs deleted file mode 100644 index d4c9cc4b16037..0000000000000 --- a/library/core/src/iter/traits/mod.rs +++ /dev/null @@ -1,26 +0,0 @@ -mod accum; -mod collect; -mod double_ended; -mod exact_size; -mod iterator; -mod marker; -mod unchecked_iterator; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::{ - accum::{Product, Sum}, - collect::{Extend, FromIterator, IntoIterator}, - double_ended::DoubleEndedIterator, - exact_size::ExactSizeIterator, - iterator::Iterator, - marker::{FusedIterator, TrustedLen}, -}; - -#[unstable(issue = "none", feature = "inplace_iteration")] -pub use self::marker::InPlaceIterable; -#[unstable(issue = "none", feature = "trusted_fused")] -pub use self::marker::TrustedFused; -#[unstable(feature = "trusted_step", issue = "85731")] -pub use self::marker::TrustedStep; - -pub(crate) use self::unchecked_iterator::UncheckedIterator; diff --git a/library/core/src/iter/traits/unchecked_iterator.rs b/library/core/src/iter/traits/unchecked_iterator.rs deleted file mode 100644 index ae4bfcad4e68f..0000000000000 --- a/library/core/src/iter/traits/unchecked_iterator.rs +++ /dev/null @@ -1,36 +0,0 @@ -use crate::iter::TrustedLen; - -/// [`TrustedLen`] cannot have methods, so this allows augmenting it. -/// -/// It currently requires `TrustedLen` because it's unclear whether it's -/// reasonably possible to depend on the `size_hint` of anything else. -pub(crate) trait UncheckedIterator: TrustedLen { - /// Gets the next item from a non-empty iterator. - /// - /// Because there's always a value to return, that means it can return - /// the `Item` type directly, without wrapping it in an `Option`. - /// - /// # Safety - /// - /// This can only be called if `size_hint().0 != 0`, guaranteeing that - /// there's at least one item available. - /// - /// Otherwise (aka when `size_hint().1 == Some(0)`), this is UB. - /// - /// # Note to Implementers - /// - /// This has a default implementation using [`Option::unwrap_unchecked`]. - /// That's probably sufficient if your `next` *always* returns `Some`, - /// such as for infinite iterators. In more complicated situations, however, - /// sometimes there can still be `insertvalue`/`assume`/`extractvalue` - /// instructions remaining in the IR from the `Option` handling, at which - /// point you might want to implement this manually instead. - #[unstable(feature = "trusted_len_next_unchecked", issue = "37572")] - #[inline] - unsafe fn next_unchecked(&mut self) -> Self::Item { - let opt = self.next(); - // SAFETY: The caller promised that we're not empty, and - // `Self: TrustedLen` so we can actually trust the `size_hint`. - unsafe { opt.unwrap_unchecked() } - } -} diff --git a/library/core/src/lib.miri.rs b/library/core/src/lib.miri.rs deleted file mode 100644 index 5c1027f20ba07..0000000000000 --- a/library/core/src/lib.miri.rs +++ /dev/null @@ -1,4 +0,0 @@ -//! Grep bootstrap for `MIRI_REPLACE_LIBRS_IF_NOT_TEST` to learn what this is about. -#![no_std] -extern crate core as realcore; -pub use realcore::*; diff --git a/library/core/src/lib.rs b/library/core/src/lib.rs deleted file mode 100644 index 7626d6d4a3cc8..0000000000000 --- a/library/core/src/lib.rs +++ /dev/null @@ -1,479 +0,0 @@ -//! # The Rust Core Library -//! -//! The Rust Core Library is the dependency-free[^free] foundation of [The -//! Rust Standard Library](../std/index.html). It is the portable glue -//! between the language and its libraries, defining the intrinsic and -//! primitive building blocks of all Rust code. It links to no -//! upstream libraries, no system libraries, and no libc. -//! -//! [^free]: Strictly speaking, there are some symbols which are needed but -//! they aren't always necessary. -//! -//! The core library is *minimal*: it isn't even aware of heap allocation, -//! nor does it provide concurrency or I/O. These things require -//! platform integration, and this library is platform-agnostic. -//! -//! # How to use the core library -//! -//! Please note that all of these details are currently not considered stable. -//! -// FIXME: Fill me in with more detail when the interface settles -//! This library is built on the assumption of a few existing symbols: -//! -//! * `memcpy`, `memmove`, `memset`, `memcmp`, `bcmp`, `strlen` - These are core memory routines -//! which are generated by Rust codegen backends. Additionally, this library can make explicit -//! calls to `strlen`. Their signatures are the same as found in C, but there are extra -//! assumptions about their semantics: For `memcpy`, `memmove`, `memset`, `memcmp`, and `bcmp`, if -//! the `n` parameter is 0, the function is assumed to not be UB, even if the pointers are NULL or -//! dangling. (Note that making extra assumptions about these functions is common among compilers: -//! [clang](https://reviews.llvm.org/D86993) and [GCC](https://gcc.gnu.org/onlinedocs/gcc/Standards.html#C-Language) do the same.) -//! These functions are often provided by the system libc, but can also be provided by the -//! [compiler-builtins crate](https://crates.io/crates/compiler_builtins). -//! Note that the library does not guarantee that it will always make these assumptions, so Rust -//! user code directly calling the C functions should follow the C specification! The advice for -//! Rust user code is to call the functions provided by this library instead (such as -//! `ptr::copy`). -//! -//! * `rust_begin_panic` - This function takes four arguments, a -//! `fmt::Arguments`, a `&'static str`, and two `u32`'s. These four arguments -//! dictate the panic message, the file at which panic was invoked, and the -//! line and column inside the file. It is up to consumers of this core -//! library to define this panic function; it is only required to never -//! return. This requires a `lang` attribute named `panic_impl`. -//! -//! * `rust_eh_personality` - is used by the failure mechanisms of the -//! compiler. This is often mapped to GCC's personality function, but crates -//! which do not trigger a panic can be assured that this function is never -//! called. The `lang` attribute is called `eh_personality`. - -// Since core defines many fundamental lang items, all tests live in a -// separate crate, libcoretest (library/core/tests), to avoid bizarre issues. -// -// Here we explicitly #[cfg]-out this whole crate when testing. If we don't do -// this, both the generated test artifact and the linked libtest (which -// transitively includes core) will both define the same set of lang items, -// and this will cause the E0152 "found duplicate lang item" error. See -// discussion in #50466 for details. -// -// This cfg won't affect doc tests. -#![cfg(not(test))] -// -#![stable(feature = "core", since = "1.6.0")] -#![doc( - html_playground_url = "https://play.rust-lang.org/", - issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/", - test(no_crate_inject, attr(deny(warnings))), - test(attr(allow(dead_code, deprecated, unused_variables, unused_mut))) -)] -#![doc(rust_logo)] -#![doc(cfg_hide( - not(test), - no_fp_fmt_parse, - target_pointer_width = "16", - target_pointer_width = "32", - target_pointer_width = "64", - target_has_atomic = "8", - target_has_atomic = "16", - target_has_atomic = "32", - target_has_atomic = "64", - target_has_atomic = "ptr", - target_has_atomic_equal_alignment = "8", - target_has_atomic_equal_alignment = "16", - target_has_atomic_equal_alignment = "32", - target_has_atomic_equal_alignment = "64", - target_has_atomic_equal_alignment = "ptr", - target_has_atomic_load_store = "8", - target_has_atomic_load_store = "16", - target_has_atomic_load_store = "32", - target_has_atomic_load_store = "64", - target_has_atomic_load_store = "ptr", -))] -#![no_core] -#![rustc_coherence_is_core] -#![rustc_preserve_ub_checks] -// -// Lints: -#![deny(rust_2021_incompatible_or_patterns)] -#![deny(unsafe_op_in_unsafe_fn)] -#![deny(fuzzy_provenance_casts)] -#![warn(deprecated_in_future)] -#![warn(missing_debug_implementations)] -#![warn(missing_docs)] -#![allow(explicit_outlives_requirements)] -#![allow(incomplete_features)] -#![warn(multiple_supertrait_upcastable)] -#![allow(internal_features)] -#![deny(ffi_unwind_calls)] -// Do not check link redundancy on bootstraping phase -#![allow(rustdoc::redundant_explicit_links)] -// -// Library features: -// tidy-alphabetical-start -#![feature(array_ptr_get)] -#![feature(asm_experimental_arch)] -#![feature(char_indices_offset)] -#![feature(const_align_of_val)] -#![feature(const_align_of_val_raw)] -#![feature(const_align_offset)] -#![feature(const_alloc_layout)] -#![feature(const_arguments_as_str)] -#![feature(const_array_from_ref)] -#![feature(const_array_into_iter_constructors)] -#![feature(const_bigint_helper_methods)] -#![feature(const_black_box)] -#![feature(const_cell_into_inner)] -#![feature(const_char_from_u32_unchecked)] -#![feature(const_eval_select)] -#![feature(const_exact_div)] -#![feature(const_float_bits_conv)] -#![feature(const_float_classify)] -#![feature(const_fmt_arguments_new)] -#![feature(const_hash)] -#![feature(const_heap)] -#![feature(const_hint_assert_unchecked)] -#![feature(const_index_range_slice_index)] -#![feature(const_int_from_str)] -#![feature(const_intrinsic_copy)] -#![feature(const_intrinsic_forget)] -#![feature(const_ipv4)] -#![feature(const_ipv6)] -#![feature(const_likely)] -#![feature(const_maybe_uninit_as_mut_ptr)] -#![feature(const_maybe_uninit_assume_init)] -#![feature(const_maybe_uninit_uninit_array)] -#![feature(const_nonnull_new)] -#![feature(const_num_midpoint)] -#![feature(const_option)] -#![feature(const_option_ext)] -#![feature(const_pin)] -#![feature(const_pointer_is_aligned)] -#![feature(const_ptr_as_ref)] -#![feature(const_ptr_is_null)] -#![feature(const_ptr_sub_ptr)] -#![feature(const_ptr_write)] -#![feature(const_raw_ptr_comparison)] -#![feature(const_replace)] -#![feature(const_size_of_val)] -#![feature(const_size_of_val_raw)] -#![feature(const_slice_from_raw_parts_mut)] -#![feature(const_slice_from_ref)] -#![feature(const_slice_index)] -#![feature(const_slice_split_at_mut)] -#![feature(const_str_from_utf8_unchecked_mut)] -#![feature(const_strict_overflow_ops)] -#![feature(const_swap)] -#![feature(const_try)] -#![feature(const_type_id)] -#![feature(const_type_name)] -#![feature(const_typed_swap)] -#![feature(const_ub_checks)] -#![feature(const_unicode_case_lookup)] -#![feature(const_unsafecell_get_mut)] -#![feature(const_waker)] -#![feature(coverage_attribute)] -#![feature(duration_consts_float)] -#![feature(internal_impls_macro)] -#![feature(ip)] -#![feature(ip_bits)] -#![feature(is_ascii_octdigit)] -#![feature(isqrt)] -#![feature(link_cfg)] -#![feature(maybe_uninit_uninit_array)] -#![feature(offset_of_enum)] -#![feature(offset_of_nested)] -#![feature(panic_internals)] -#![feature(ptr_alignment_type)] -#![feature(ptr_metadata)] -#![feature(set_ptr_value)] -#![feature(slice_ptr_get)] -#![feature(str_internals)] -#![feature(str_split_inclusive_remainder)] -#![feature(str_split_remainder)] -#![feature(strict_provenance)] -#![feature(ub_checks)] -#![feature(unchecked_shifts)] -#![feature(utf16_extra)] -#![feature(utf16_extra_const)] -#![feature(variant_count)] -// tidy-alphabetical-end -// -// Language features: -// tidy-alphabetical-start -#![feature(abi_unadjusted)] -#![feature(adt_const_params)] -#![feature(allow_internal_unsafe)] -#![feature(allow_internal_unstable)] -#![feature(asm_const)] -#![feature(auto_traits)] -#![feature(c_unwind)] -#![feature(cfg_sanitize)] -#![feature(cfg_target_has_atomic)] -#![feature(cfg_target_has_atomic_equal_alignment)] -#![feature(const_closures)] -#![feature(const_fn_floating_point_arithmetic)] -#![feature(const_for)] -#![feature(const_mut_refs)] -#![feature(const_precise_live_drops)] -#![feature(const_refs_to_cell)] -#![feature(const_trait_impl)] -#![feature(decl_macro)] -#![feature(deprecated_suggestion)] -#![feature(doc_cfg)] -#![feature(doc_cfg_hide)] -#![feature(doc_notable_trait)] -#![feature(effects)] -#![feature(extern_types)] -#![feature(f128)] -#![feature(f16)] -#![feature(freeze_impls)] -#![feature(fundamental)] -#![feature(generic_arg_infer)] -#![feature(if_let_guard)] -#![feature(intra_doc_pointers)] -#![feature(intrinsics)] -#![feature(lang_items)] -#![feature(let_chains)] -#![feature(link_llvm_intrinsics)] -#![feature(macro_metavar_expr)] -#![feature(min_exhaustive_patterns)] -#![feature(min_specialization)] -#![feature(multiple_supertrait_upcastable)] -#![feature(must_not_suspend)] -#![feature(negative_impls)] -#![feature(never_type)] -#![feature(no_core)] -#![feature(no_sanitize)] -#![feature(prelude_import)] -#![feature(repr_simd)] -#![feature(rustc_allow_const_fn_unstable)] -#![feature(rustc_attrs)] -#![feature(rustdoc_internals)] -#![feature(simd_ffi)] -#![feature(staged_api)] -#![feature(stmt_expr_attributes)] -#![feature(target_feature_11)] -#![feature(trait_alias)] -#![feature(transparent_unions)] -#![feature(try_blocks)] -#![feature(type_alias_impl_trait)] -#![feature(unboxed_closures)] -#![feature(unsized_fn_params)] -#![feature(with_negative_coherence)] -// tidy-alphabetical-end -// -// Target features: -// tidy-alphabetical-start -#![feature(arm_target_feature)] -#![feature(avx512_target_feature)] -#![feature(hexagon_target_feature)] -#![feature(loongarch_target_feature)] -#![feature(mips_target_feature)] -#![feature(powerpc_target_feature)] -#![feature(riscv_target_feature)] -#![feature(rtm_target_feature)] -#![feature(sse4a_target_feature)] -#![feature(tbm_target_feature)] -#![feature(wasm_target_feature)] -// tidy-alphabetical-end - -// allow using `core::` in intra-doc links -#[allow(unused_extern_crates)] -extern crate self as core; - -#[prelude_import] -#[allow(unused)] -use prelude::rust_2021::*; - -#[cfg(not(test))] // See #65860 -#[macro_use] -mod macros; - -// We don't export this through #[macro_export] for now, to avoid breakage. -// See https://github.com/rust-lang/rust/issues/82913 -#[cfg(not(test))] -#[unstable(feature = "assert_matches", issue = "82775")] -/// Unstable module containing the unstable `assert_matches` macro. -pub mod assert_matches { - #[unstable(feature = "assert_matches", issue = "82775")] - pub use crate::macros::{assert_matches, debug_assert_matches}; -} - -#[unstable(feature = "cfg_match", issue = "115585")] -pub use crate::macros::cfg_match; - -#[macro_use] -mod internal_macros; - -#[path = "num/shells/int_macros.rs"] -#[macro_use] -mod int_macros; - -#[rustc_diagnostic_item = "i128_legacy_mod"] -#[path = "num/shells/i128.rs"] -pub mod i128; -#[rustc_diagnostic_item = "i16_legacy_mod"] -#[path = "num/shells/i16.rs"] -pub mod i16; -#[rustc_diagnostic_item = "i32_legacy_mod"] -#[path = "num/shells/i32.rs"] -pub mod i32; -#[rustc_diagnostic_item = "i64_legacy_mod"] -#[path = "num/shells/i64.rs"] -pub mod i64; -#[rustc_diagnostic_item = "i8_legacy_mod"] -#[path = "num/shells/i8.rs"] -pub mod i8; -#[rustc_diagnostic_item = "isize_legacy_mod"] -#[path = "num/shells/isize.rs"] -pub mod isize; - -#[rustc_diagnostic_item = "u128_legacy_mod"] -#[path = "num/shells/u128.rs"] -pub mod u128; -#[rustc_diagnostic_item = "u16_legacy_mod"] -#[path = "num/shells/u16.rs"] -pub mod u16; -#[rustc_diagnostic_item = "u32_legacy_mod"] -#[path = "num/shells/u32.rs"] -pub mod u32; -#[rustc_diagnostic_item = "u64_legacy_mod"] -#[path = "num/shells/u64.rs"] -pub mod u64; -#[rustc_diagnostic_item = "u8_legacy_mod"] -#[path = "num/shells/u8.rs"] -pub mod u8; -#[rustc_diagnostic_item = "usize_legacy_mod"] -#[path = "num/shells/usize.rs"] -pub mod usize; - -#[path = "num/f128.rs"] -pub mod f128; -#[path = "num/f16.rs"] -pub mod f16; -#[path = "num/f32.rs"] -pub mod f32; -#[path = "num/f64.rs"] -pub mod f64; - -#[macro_use] -pub mod num; - -/* The core prelude, not as all-encompassing as the std prelude */ - -pub mod prelude; - -/* Core modules for ownership management */ - -pub mod hint; -pub mod intrinsics; -pub mod mem; -pub mod ptr; -#[unstable(feature = "ub_checks", issue = "none")] -pub mod ub_checks; - -/* Core language traits */ - -pub mod borrow; -pub mod clone; -pub mod cmp; -pub mod convert; -pub mod default; -pub mod error; -pub mod marker; -pub mod ops; - -/* Core types and methods on primitives */ - -pub mod any; -pub mod array; -pub mod ascii; -pub mod asserting; -#[unstable(feature = "async_iterator", issue = "79024")] -pub mod async_iter; -pub mod cell; -pub mod char; -pub mod ffi; -#[unstable(feature = "core_io_borrowed_buf", issue = "117693")] -pub mod io; -pub mod iter; -pub mod net; -pub mod option; -pub mod panic; -pub mod panicking; -#[unstable(feature = "core_pattern_types", issue = "none")] -pub mod pat; -pub mod pin; -pub mod result; -pub mod sync; - -pub mod fmt; -pub mod hash; -pub mod slice; -pub mod str; -pub mod time; - -pub mod unicode; - -/* Async */ -pub mod future; -pub mod task; - -/* Heap memory allocator trait */ -#[allow(missing_docs)] -pub mod alloc; - -// note: does not need to be public -mod bool; -mod escape; -mod tuple; -mod unit; - -#[stable(feature = "core_primitive", since = "1.43.0")] -pub mod primitive; - -#[cfg(kani)] -kani_core::kani_lib!(core); - -// Pull in the `core_arch` crate directly into core. The contents of -// `core_arch` are in a different repository: rust-lang/stdarch. -// -// `core_arch` depends on core, but the contents of this module are -// set up in such a way that directly pulling it here works such that the -// crate uses the this crate as its core. -#[path = "../../stdarch/crates/core_arch/src/mod.rs"] -#[allow( - missing_docs, - missing_debug_implementations, - dead_code, - unused_imports, - unsafe_op_in_unsafe_fn, - ambiguous_glob_reexports, - deprecated_in_future -)] -#[allow(rustdoc::bare_urls)] -mod core_arch; - -#[stable(feature = "simd_arch", since = "1.27.0")] -pub mod arch; - -// Pull in the `core_simd` crate directly into core. The contents of -// `core_simd` are in a different repository: rust-lang/portable-simd. -// -// `core_simd` depends on core, but the contents of this module are -// set up in such a way that directly pulling it here works such that the -// crate uses this crate as its core. -#[path = "../../portable-simd/crates/core_simd/src/mod.rs"] -#[allow(missing_debug_implementations, dead_code, unsafe_op_in_unsafe_fn)] -#[allow(rustdoc::bare_urls)] -#[unstable(feature = "portable_simd", issue = "86656")] -mod core_simd; - -#[unstable(feature = "portable_simd", issue = "86656")] -pub mod simd { - #![doc = include_str!("../../portable-simd/crates/core_simd/src/core_simd_docs.md")] - - #[unstable(feature = "portable_simd", issue = "86656")] - pub use crate::core_simd::simd::*; -} - -include!("primitive_docs.rs"); diff --git a/library/core/src/macros/mod.rs b/library/core/src/macros/mod.rs deleted file mode 100644 index 2ddedfa37fe27..0000000000000 --- a/library/core/src/macros/mod.rs +++ /dev/null @@ -1,1757 +0,0 @@ -#[doc = include_str!("panic.md")] -#[macro_export] -#[rustc_builtin_macro(core_panic)] -#[allow_internal_unstable(edition_panic)] -#[stable(feature = "core", since = "1.6.0")] -#[rustc_diagnostic_item = "core_panic_macro"] -macro_rules! panic { - // Expands to either `$crate::panic::panic_2015` or `$crate::panic::panic_2021` - // depending on the edition of the caller. - ($($arg:tt)*) => { - /* compiler built-in */ - }; -} - -/// Asserts that two expressions are equal to each other (using [`PartialEq`]). -/// -/// On panic, this macro will print the values of the expressions with their -/// debug representations. -/// -/// Like [`assert!`], this macro has a second form, where a custom -/// panic message can be provided. -/// -/// # Examples -/// -/// ``` -/// let a = 3; -/// let b = 1 + 2; -/// assert_eq!(a, b); -/// -/// assert_eq!(a, b, "we are testing addition with {} and {}", a, b); -/// ``` -#[macro_export] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "assert_eq_macro")] -#[allow_internal_unstable(panic_internals)] -macro_rules! assert_eq { - ($left:expr, $right:expr $(,)?) => { - match (&$left, &$right) { - (left_val, right_val) => { - if !(*left_val == *right_val) { - let kind = $crate::panicking::AssertKind::Eq; - // The reborrows below are intentional. Without them, the stack slot for the - // borrow is initialized even before the values are compared, leading to a - // noticeable slow down. - $crate::panicking::assert_failed(kind, &*left_val, &*right_val, $crate::option::Option::None); - } - } - } - }; - ($left:expr, $right:expr, $($arg:tt)+) => { - match (&$left, &$right) { - (left_val, right_val) => { - if !(*left_val == *right_val) { - let kind = $crate::panicking::AssertKind::Eq; - // The reborrows below are intentional. Without them, the stack slot for the - // borrow is initialized even before the values are compared, leading to a - // noticeable slow down. - $crate::panicking::assert_failed(kind, &*left_val, &*right_val, $crate::option::Option::Some($crate::format_args!($($arg)+))); - } - } - } - }; -} - -/// Asserts that two expressions are not equal to each other (using [`PartialEq`]). -/// -/// On panic, this macro will print the values of the expressions with their -/// debug representations. -/// -/// Like [`assert!`], this macro has a second form, where a custom -/// panic message can be provided. -/// -/// # Examples -/// -/// ``` -/// let a = 3; -/// let b = 2; -/// assert_ne!(a, b); -/// -/// assert_ne!(a, b, "we are testing that the values are not equal"); -/// ``` -#[macro_export] -#[stable(feature = "assert_ne", since = "1.13.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "assert_ne_macro")] -#[allow_internal_unstable(panic_internals)] -macro_rules! assert_ne { - ($left:expr, $right:expr $(,)?) => { - match (&$left, &$right) { - (left_val, right_val) => { - if *left_val == *right_val { - let kind = $crate::panicking::AssertKind::Ne; - // The reborrows below are intentional. Without them, the stack slot for the - // borrow is initialized even before the values are compared, leading to a - // noticeable slow down. - $crate::panicking::assert_failed(kind, &*left_val, &*right_val, $crate::option::Option::None); - } - } - } - }; - ($left:expr, $right:expr, $($arg:tt)+) => { - match (&($left), &($right)) { - (left_val, right_val) => { - if *left_val == *right_val { - let kind = $crate::panicking::AssertKind::Ne; - // The reborrows below are intentional. Without them, the stack slot for the - // borrow is initialized even before the values are compared, leading to a - // noticeable slow down. - $crate::panicking::assert_failed(kind, &*left_val, &*right_val, $crate::option::Option::Some($crate::format_args!($($arg)+))); - } - } - } - }; -} - -/// Asserts that an expression matches the provided pattern. -/// -/// This macro is generally preferable to `assert!(matches!(value, pattern))`, because it can print -/// the debug representation of the actual value shape that did not meet expectations. In contrast, -/// using [`assert!`] will only print that expectations were not met, but not why. -/// -/// The pattern syntax is exactly the same as found in a match arm and the `matches!` macro. The -/// optional if guard can be used to add additional checks that must be true for the matched value, -/// otherwise this macro will panic. -/// -/// On panic, this macro will print the value of the expression with its debug representation. -/// -/// Like [`assert!`], this macro has a second form, where a custom panic message can be provided. -/// -/// # Examples -/// -/// ``` -/// #![feature(assert_matches)] -/// -/// use std::assert_matches::assert_matches; -/// -/// let a = Some(345); -/// let b = Some(56); -/// assert_matches!(a, Some(_)); -/// assert_matches!(b, Some(_)); -/// -/// assert_matches!(a, Some(345)); -/// assert_matches!(a, Some(345) | None); -/// -/// // assert_matches!(a, None); // panics -/// // assert_matches!(b, Some(345)); // panics -/// // assert_matches!(b, Some(345) | None); // panics -/// -/// assert_matches!(a, Some(x) if x > 100); -/// // assert_matches!(a, Some(x) if x < 100); // panics -/// ``` -#[unstable(feature = "assert_matches", issue = "82775")] -#[allow_internal_unstable(panic_internals)] -#[rustc_macro_transparency = "semitransparent"] -pub macro assert_matches { - ($left:expr, $(|)? $( $pattern:pat_param )|+ $( if $guard: expr )? $(,)?) => { - match $left { - $( $pattern )|+ $( if $guard )? => {} - ref left_val => { - $crate::panicking::assert_matches_failed( - left_val, - $crate::stringify!($($pattern)|+ $(if $guard)?), - $crate::option::Option::None - ); - } - } - }, - ($left:expr, $(|)? $( $pattern:pat_param )|+ $( if $guard: expr )?, $($arg:tt)+) => { - match $left { - $( $pattern )|+ $( if $guard )? => {} - ref left_val => { - $crate::panicking::assert_matches_failed( - left_val, - $crate::stringify!($($pattern)|+ $(if $guard)?), - $crate::option::Option::Some($crate::format_args!($($arg)+)) - ); - } - } - }, -} - -/// A macro for defining `#[cfg]` match-like statements. -/// -/// It is similar to the `if/elif` C preprocessor macro by allowing definition of a cascade of -/// `#[cfg]` cases, emitting the implementation which matches first. -/// -/// This allows you to conveniently provide a long list `#[cfg]`'d blocks of code -/// without having to rewrite each clause multiple times. -/// -/// Trailing `_` wildcard match arms are **optional** and they indicate a fallback branch when -/// all previous declarations do not evaluate to true. -/// -/// # Example -/// -/// ``` -/// #![feature(cfg_match)] -/// -/// cfg_match! { -/// cfg(unix) => { -/// fn foo() { /* unix specific functionality */ } -/// } -/// cfg(target_pointer_width = "32") => { -/// fn foo() { /* non-unix, 32-bit functionality */ } -/// } -/// _ => { -/// fn foo() { /* fallback implementation */ } -/// } -/// } -/// ``` -#[unstable(feature = "cfg_match", issue = "115585")] -#[rustc_diagnostic_item = "cfg_match"] -pub macro cfg_match { - // with a final wildcard - ( - $(cfg($initial_meta:meta) => { $($initial_tokens:item)* })+ - _ => { $($extra_tokens:item)* } - ) => { - cfg_match! { - @__items (); - $((($initial_meta) ($($initial_tokens)*)),)+ - (() ($($extra_tokens)*)), - } - }, - - // without a final wildcard - ( - $(cfg($extra_meta:meta) => { $($extra_tokens:item)* })* - ) => { - cfg_match! { - @__items (); - $((($extra_meta) ($($extra_tokens)*)),)* - } - }, - - // Internal and recursive macro to emit all the items - // - // Collects all the previous cfgs in a list at the beginning, so they can be - // negated. After the semicolon is all the remaining items. - (@__items ($($_:meta,)*);) => {}, - ( - @__items ($($no:meta,)*); - (($($yes:meta)?) ($($tokens:item)*)), - $($rest:tt,)* - ) => { - // Emit all items within one block, applying an appropriate #[cfg]. The - // #[cfg] will require all `$yes` matchers specified and must also negate - // all previous matchers. - #[cfg(all( - $($yes,)? - not(any($($no),*)) - ))] - cfg_match! { @__identity $($tokens)* } - - // Recurse to emit all other items in `$rest`, and when we do so add all - // our `$yes` matchers to the list of `$no` matchers as future emissions - // will have to negate everything we just matched as well. - cfg_match! { - @__items ($($no,)* $($yes,)?); - $($rest,)* - } - }, - - // Internal macro to make __apply work out right for different match types, - // because of how macros match/expand stuff. - (@__identity $($tokens:item)*) => { - $($tokens)* - } -} - -/// Asserts that a boolean expression is `true` at runtime. -/// -/// This will invoke the [`panic!`] macro if the provided expression cannot be -/// evaluated to `true` at runtime. -/// -/// Like [`assert!`], this macro also has a second version, where a custom panic -/// message can be provided. -/// -/// # Uses -/// -/// Unlike [`assert!`], `debug_assert!` statements are only enabled in non -/// optimized builds by default. An optimized build will not execute -/// `debug_assert!` statements unless `-C debug-assertions` is passed to the -/// compiler. This makes `debug_assert!` useful for checks that are too -/// expensive to be present in a release build but may be helpful during -/// development. The result of expanding `debug_assert!` is always type checked. -/// -/// An unchecked assertion allows a program in an inconsistent state to keep -/// running, which might have unexpected consequences but does not introduce -/// unsafety as long as this only happens in safe code. The performance cost -/// of assertions, however, is not measurable in general. Replacing [`assert!`] -/// with `debug_assert!` is thus only encouraged after thorough profiling, and -/// more importantly, only in safe code! -/// -/// # Examples -/// -/// ``` -/// // the panic message for these assertions is the stringified value of the -/// // expression given. -/// debug_assert!(true); -/// -/// fn some_expensive_computation() -> bool { true } // a very simple function -/// debug_assert!(some_expensive_computation()); -/// -/// // assert with a custom message -/// let x = true; -/// debug_assert!(x, "x wasn't true!"); -/// -/// let a = 3; let b = 27; -/// debug_assert!(a + b == 30, "a = {}, b = {}", a, b); -/// ``` -#[macro_export] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_diagnostic_item = "debug_assert_macro"] -#[allow_internal_unstable(edition_panic)] -macro_rules! debug_assert { - ($($arg:tt)*) => { - if $crate::cfg!(debug_assertions) { - $crate::assert!($($arg)*); - } - }; -} - -/// Asserts that two expressions are equal to each other. -/// -/// On panic, this macro will print the values of the expressions with their -/// debug representations. -/// -/// Unlike [`assert_eq!`], `debug_assert_eq!` statements are only enabled in non -/// optimized builds by default. An optimized build will not execute -/// `debug_assert_eq!` statements unless `-C debug-assertions` is passed to the -/// compiler. This makes `debug_assert_eq!` useful for checks that are too -/// expensive to be present in a release build but may be helpful during -/// development. The result of expanding `debug_assert_eq!` is always type checked. -/// -/// # Examples -/// -/// ``` -/// let a = 3; -/// let b = 1 + 2; -/// debug_assert_eq!(a, b); -/// ``` -#[macro_export] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "debug_assert_eq_macro")] -macro_rules! debug_assert_eq { - ($($arg:tt)*) => { - if $crate::cfg!(debug_assertions) { - $crate::assert_eq!($($arg)*); - } - }; -} - -/// Asserts that two expressions are not equal to each other. -/// -/// On panic, this macro will print the values of the expressions with their -/// debug representations. -/// -/// Unlike [`assert_ne!`], `debug_assert_ne!` statements are only enabled in non -/// optimized builds by default. An optimized build will not execute -/// `debug_assert_ne!` statements unless `-C debug-assertions` is passed to the -/// compiler. This makes `debug_assert_ne!` useful for checks that are too -/// expensive to be present in a release build but may be helpful during -/// development. The result of expanding `debug_assert_ne!` is always type checked. -/// -/// # Examples -/// -/// ``` -/// let a = 3; -/// let b = 2; -/// debug_assert_ne!(a, b); -/// ``` -#[macro_export] -#[stable(feature = "assert_ne", since = "1.13.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "debug_assert_ne_macro")] -macro_rules! debug_assert_ne { - ($($arg:tt)*) => { - if $crate::cfg!(debug_assertions) { - $crate::assert_ne!($($arg)*); - } - }; -} - -/// Asserts that an expression matches the provided pattern. -/// -/// This macro is generally preferable to `debug_assert!(matches!(value, pattern))`, because it can -/// print the debug representation of the actual value shape that did not meet expectations. In -/// contrast, using [`debug_assert!`] will only print that expectations were not met, but not why. -/// -/// The pattern syntax is exactly the same as found in a match arm and the `matches!` macro. The -/// optional if guard can be used to add additional checks that must be true for the matched value, -/// otherwise this macro will panic. -/// -/// On panic, this macro will print the value of the expression with its debug representation. -/// -/// Like [`assert!`], this macro has a second form, where a custom panic message can be provided. -/// -/// Unlike [`assert_matches!`], `debug_assert_matches!` statements are only enabled in non optimized -/// builds by default. An optimized build will not execute `debug_assert_matches!` statements unless -/// `-C debug-assertions` is passed to the compiler. This makes `debug_assert_matches!` useful for -/// checks that are too expensive to be present in a release build but may be helpful during -/// development. The result of expanding `debug_assert_matches!` is always type checked. -/// -/// # Examples -/// -/// ``` -/// #![feature(assert_matches)] -/// -/// use std::assert_matches::debug_assert_matches; -/// -/// let a = Some(345); -/// let b = Some(56); -/// debug_assert_matches!(a, Some(_)); -/// debug_assert_matches!(b, Some(_)); -/// -/// debug_assert_matches!(a, Some(345)); -/// debug_assert_matches!(a, Some(345) | None); -/// -/// // debug_assert_matches!(a, None); // panics -/// // debug_assert_matches!(b, Some(345)); // panics -/// // debug_assert_matches!(b, Some(345) | None); // panics -/// -/// debug_assert_matches!(a, Some(x) if x > 100); -/// // debug_assert_matches!(a, Some(x) if x < 100); // panics -/// ``` -#[unstable(feature = "assert_matches", issue = "82775")] -#[allow_internal_unstable(assert_matches)] -#[rustc_macro_transparency = "semitransparent"] -pub macro debug_assert_matches($($arg:tt)*) { - if $crate::cfg!(debug_assertions) { - $crate::assert_matches::assert_matches!($($arg)*); - } -} - -/// Returns whether the given expression matches the provided pattern. -/// -/// The pattern syntax is exactly the same as found in a match arm. The optional if guard can be -/// used to add additional checks that must be true for the matched value, otherwise this macro will -/// return `false`. -/// -/// When testing that a value matches a pattern, it's generally preferable to use -/// [`assert_matches!`] as it will print the debug representation of the value if the assertion -/// fails. -/// -/// # Examples -/// -/// ``` -/// let foo = 'f'; -/// assert!(matches!(foo, 'A'..='Z' | 'a'..='z')); -/// -/// let bar = Some(4); -/// assert!(matches!(bar, Some(x) if x > 2)); -/// ``` -#[macro_export] -#[stable(feature = "matches_macro", since = "1.42.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "matches_macro")] -macro_rules! matches { - ($expression:expr, $pattern:pat $(if $guard:expr)? $(,)?) => { - match $expression { - $pattern $(if $guard)? => true, - _ => false - } - }; -} - -/// Unwraps a result or propagates its error. -/// -/// The [`?` operator][propagating-errors] was added to replace `try!` -/// and should be used instead. Furthermore, `try` is a reserved word -/// in Rust 2018, so if you must use it, you will need to use the -/// [raw-identifier syntax][ris]: `r#try`. -/// -/// [propagating-errors]: https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html#a-shortcut-for-propagating-errors-the--operator -/// [ris]: https://doc.rust-lang.org/nightly/rust-by-example/compatibility/raw_identifiers.html -/// -/// `try!` matches the given [`Result`]. In case of the `Ok` variant, the -/// expression has the value of the wrapped value. -/// -/// In case of the `Err` variant, it retrieves the inner error. `try!` then -/// performs conversion using `From`. This provides automatic conversion -/// between specialized errors and more general ones. The resulting -/// error is then immediately returned. -/// -/// Because of the early return, `try!` can only be used in functions that -/// return [`Result`]. -/// -/// # Examples -/// -/// ``` -/// use std::io; -/// use std::fs::File; -/// use std::io::prelude::*; -/// -/// enum MyError { -/// FileWriteError -/// } -/// -/// impl From for MyError { -/// fn from(e: io::Error) -> MyError { -/// MyError::FileWriteError -/// } -/// } -/// -/// // The preferred method of quick returning Errors -/// fn write_to_file_question() -> Result<(), MyError> { -/// let mut file = File::create("my_best_friends.txt")?; -/// file.write_all(b"This is a list of my best friends.")?; -/// Ok(()) -/// } -/// -/// // The previous method of quick returning Errors -/// fn write_to_file_using_try() -> Result<(), MyError> { -/// let mut file = r#try!(File::create("my_best_friends.txt")); -/// r#try!(file.write_all(b"This is a list of my best friends.")); -/// Ok(()) -/// } -/// -/// // This is equivalent to: -/// fn write_to_file_using_match() -> Result<(), MyError> { -/// let mut file = r#try!(File::create("my_best_friends.txt")); -/// match file.write_all(b"This is a list of my best friends.") { -/// Ok(v) => v, -/// Err(e) => return Err(From::from(e)), -/// } -/// Ok(()) -/// } -/// ``` -#[macro_export] -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "1.39.0", note = "use the `?` operator instead")] -#[doc(alias = "?")] -macro_rules! r#try { - ($expr:expr $(,)?) => { - match $expr { - $crate::result::Result::Ok(val) => val, - $crate::result::Result::Err(err) => { - return $crate::result::Result::Err($crate::convert::From::from(err)); - } - } - }; -} - -/// Writes formatted data into a buffer. -/// -/// This macro accepts a 'writer', a format string, and a list of arguments. Arguments will be -/// formatted according to the specified format string and the result will be passed to the writer. -/// The writer may be any value with a `write_fmt` method; generally this comes from an -/// implementation of either the [`fmt::Write`] or the [`io::Write`] trait. The macro -/// returns whatever the `write_fmt` method returns; commonly a [`fmt::Result`], or an -/// [`io::Result`]. -/// -/// See [`std::fmt`] for more information on the format string syntax. -/// -/// [`std::fmt`]: ../std/fmt/index.html -/// [`fmt::Write`]: crate::fmt::Write -/// [`io::Write`]: ../std/io/trait.Write.html -/// [`fmt::Result`]: crate::fmt::Result -/// [`io::Result`]: ../std/io/type.Result.html -/// -/// # Examples -/// -/// ``` -/// use std::io::Write; -/// -/// fn main() -> std::io::Result<()> { -/// let mut w = Vec::new(); -/// write!(&mut w, "test")?; -/// write!(&mut w, "formatted {}", "arguments")?; -/// -/// assert_eq!(w, b"testformatted arguments"); -/// Ok(()) -/// } -/// ``` -/// -/// A module can import both `std::fmt::Write` and `std::io::Write` and call `write!` on objects -/// implementing either, as objects do not typically implement both. However, the module must -/// avoid conflict between the trait names, such as by importing them as `_` or otherwise renaming -/// them: -/// -/// ``` -/// use std::fmt::Write as _; -/// use std::io::Write as _; -/// -/// fn main() -> Result<(), Box> { -/// let mut s = String::new(); -/// let mut v = Vec::new(); -/// -/// write!(&mut s, "{} {}", "abc", 123)?; // uses fmt::Write::write_fmt -/// write!(&mut v, "s = {:?}", s)?; // uses io::Write::write_fmt -/// assert_eq!(v, b"s = \"abc 123\""); -/// Ok(()) -/// } -/// ``` -/// -/// If you also need the trait names themselves, such as to implement one or both on your types, -/// import the containing module and then name them with a prefix: -/// -/// ``` -/// # #![allow(unused_imports)] -/// use std::fmt::{self, Write as _}; -/// use std::io::{self, Write as _}; -/// -/// struct Example; -/// -/// impl fmt::Write for Example { -/// fn write_str(&mut self, _s: &str) -> core::fmt::Result { -/// unimplemented!(); -/// } -/// } -/// ``` -/// -/// Note: This macro can be used in `no_std` setups as well. -/// In a `no_std` setup you are responsible for the implementation details of the components. -/// -/// ```no_run -/// use core::fmt::Write; -/// -/// struct Example; -/// -/// impl Write for Example { -/// fn write_str(&mut self, _s: &str) -> core::fmt::Result { -/// unimplemented!(); -/// } -/// } -/// -/// let mut m = Example{}; -/// write!(&mut m, "Hello World").expect("Not written"); -/// ``` -#[macro_export] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "write_macro")] -macro_rules! write { - ($dst:expr, $($arg:tt)*) => { - $dst.write_fmt($crate::format_args!($($arg)*)) - }; -} - -/// Write formatted data into a buffer, with a newline appended. -/// -/// On all platforms, the newline is the LINE FEED character (`\n`/`U+000A`) alone -/// (no additional CARRIAGE RETURN (`\r`/`U+000D`). -/// -/// For more information, see [`write!`]. For information on the format string syntax, see -/// [`std::fmt`]. -/// -/// [`std::fmt`]: ../std/fmt/index.html -/// -/// # Examples -/// -/// ``` -/// use std::io::{Write, Result}; -/// -/// fn main() -> Result<()> { -/// let mut w = Vec::new(); -/// writeln!(&mut w)?; -/// writeln!(&mut w, "test")?; -/// writeln!(&mut w, "formatted {}", "arguments")?; -/// -/// assert_eq!(&w[..], "\ntest\nformatted arguments\n".as_bytes()); -/// Ok(()) -/// } -/// ``` -#[macro_export] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "writeln_macro")] -#[allow_internal_unstable(format_args_nl)] -macro_rules! writeln { - ($dst:expr $(,)?) => { - $crate::write!($dst, "\n") - }; - ($dst:expr, $($arg:tt)*) => { - $dst.write_fmt($crate::format_args_nl!($($arg)*)) - }; -} - -/// Indicates unreachable code. -/// -/// This is useful any time that the compiler can't determine that some code is unreachable. For -/// example: -/// -/// * Match arms with guard conditions. -/// * Loops that dynamically terminate. -/// * Iterators that dynamically terminate. -/// -/// If the determination that the code is unreachable proves incorrect, the -/// program immediately terminates with a [`panic!`]. -/// -/// The unsafe counterpart of this macro is the [`unreachable_unchecked`] function, which -/// will cause undefined behavior if the code is reached. -/// -/// [`unreachable_unchecked`]: crate::hint::unreachable_unchecked -/// -/// # Panics -/// -/// This will always [`panic!`] because `unreachable!` is just a shorthand for `panic!` with a -/// fixed, specific message. -/// -/// Like `panic!`, this macro has a second form for displaying custom values. -/// -/// # Examples -/// -/// Match arms: -/// -/// ``` -/// # #[allow(dead_code)] -/// fn foo(x: Option) { -/// match x { -/// Some(n) if n >= 0 => println!("Some(Non-negative)"), -/// Some(n) if n < 0 => println!("Some(Negative)"), -/// Some(_) => unreachable!(), // compile error if commented out -/// None => println!("None") -/// } -/// } -/// ``` -/// -/// Iterators: -/// -/// ``` -/// # #[allow(dead_code)] -/// fn divide_by_three(x: u32) -> u32 { // one of the poorest implementations of x/3 -/// for i in 0.. { -/// if 3*i < i { panic!("u32 overflow"); } -/// if x < 3*i { return i-1; } -/// } -/// unreachable!("The loop should always return"); -/// } -/// ``` -#[macro_export] -#[rustc_builtin_macro(unreachable)] -#[allow_internal_unstable(edition_panic)] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "unreachable_macro")] -macro_rules! unreachable { - // Expands to either `$crate::panic::unreachable_2015` or `$crate::panic::unreachable_2021` - // depending on the edition of the caller. - ($($arg:tt)*) => { - /* compiler built-in */ - }; -} - -/// Indicates unimplemented code by panicking with a message of "not implemented". -/// -/// This allows your code to type-check, which is useful if you are prototyping or -/// implementing a trait that requires multiple methods which you don't plan to use all of. -/// -/// The difference between `unimplemented!` and [`todo!`] is that while `todo!` -/// conveys an intent of implementing the functionality later and the message is "not yet -/// implemented", `unimplemented!` makes no such claims. Its message is "not implemented". -/// -/// Also, some IDEs will mark `todo!`s. -/// -/// # Panics -/// -/// This will always [`panic!`] because `unimplemented!` is just a shorthand for `panic!` with a -/// fixed, specific message. -/// -/// Like `panic!`, this macro has a second form for displaying custom values. -/// -/// [`todo!`]: crate::todo -/// -/// # Examples -/// -/// Say we have a trait `Foo`: -/// -/// ``` -/// trait Foo { -/// fn bar(&self) -> u8; -/// fn baz(&self); -/// fn qux(&self) -> Result; -/// } -/// ``` -/// -/// We want to implement `Foo` for 'MyStruct', but for some reason it only makes sense -/// to implement the `bar()` function. `baz()` and `qux()` will still need to be defined -/// in our implementation of `Foo`, but we can use `unimplemented!` in their definitions -/// to allow our code to compile. -/// -/// We still want to have our program stop running if the unimplemented methods are -/// reached. -/// -/// ``` -/// # trait Foo { -/// # fn bar(&self) -> u8; -/// # fn baz(&self); -/// # fn qux(&self) -> Result; -/// # } -/// struct MyStruct; -/// -/// impl Foo for MyStruct { -/// fn bar(&self) -> u8 { -/// 1 + 1 -/// } -/// -/// fn baz(&self) { -/// // It makes no sense to `baz` a `MyStruct`, so we have no logic here -/// // at all. -/// // This will display "thread 'main' panicked at 'not implemented'". -/// unimplemented!(); -/// } -/// -/// fn qux(&self) -> Result { -/// // We have some logic here, -/// // We can add a message to unimplemented! to display our omission. -/// // This will display: -/// // "thread 'main' panicked at 'not implemented: MyStruct isn't quxable'". -/// unimplemented!("MyStruct isn't quxable"); -/// } -/// } -/// -/// fn main() { -/// let s = MyStruct; -/// s.bar(); -/// } -/// ``` -#[macro_export] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "unimplemented_macro")] -#[allow_internal_unstable(panic_internals)] -macro_rules! unimplemented { - () => { - $crate::panicking::panic("not implemented") - }; - ($($arg:tt)+) => { - $crate::panic!("not implemented: {}", $crate::format_args!($($arg)+)) - }; -} - -/// Indicates unfinished code. -/// -/// This can be useful if you are prototyping and just -/// want a placeholder to let your code pass type analysis. -/// -/// The difference between [`unimplemented!`] and `todo!` is that while `todo!` conveys -/// an intent of implementing the functionality later and the message is "not yet -/// implemented", `unimplemented!` makes no such claims. Its message is "not implemented". -/// -/// Also, some IDEs will mark `todo!`s. -/// -/// # Panics -/// -/// This will always [`panic!`] because `todo!` is just a shorthand for `panic!` with a -/// fixed, specific message. -/// -/// Like `panic!`, this macro has a second form for displaying custom values. -/// -/// # Examples -/// -/// Here's an example of some in-progress code. We have a trait `Foo`: -/// -/// ``` -/// trait Foo { -/// fn bar(&self) -> u8; -/// fn baz(&self); -/// fn qux(&self) -> Result; -/// } -/// ``` -/// -/// We want to implement `Foo` on one of our types, but we also want to work on -/// just `bar()` first. In order for our code to compile, we need to implement -/// `baz()` and `qux()`, so we can use `todo!`: -/// -/// ``` -/// # trait Foo { -/// # fn bar(&self) -> u8; -/// # fn baz(&self); -/// # fn qux(&self) -> Result; -/// # } -/// struct MyStruct; -/// -/// impl Foo for MyStruct { -/// fn bar(&self) -> u8 { -/// 1 + 1 -/// } -/// -/// fn baz(&self) { -/// // Let's not worry about implementing baz() for now -/// todo!(); -/// } -/// -/// fn qux(&self) -> Result { -/// // We can add a message to todo! to display our omission. -/// // This will display: -/// // "thread 'main' panicked at 'not yet implemented: MyStruct is not yet quxable'". -/// todo!("MyStruct is not yet quxable"); -/// } -/// } -/// -/// fn main() { -/// let s = MyStruct; -/// s.bar(); -/// -/// // We aren't even using baz() or qux(), so this is fine. -/// } -/// ``` -#[macro_export] -#[stable(feature = "todo_macro", since = "1.40.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "todo_macro")] -#[allow_internal_unstable(panic_internals)] -macro_rules! todo { - () => { - $crate::panicking::panic("not yet implemented") - }; - ($($arg:tt)+) => { - $crate::panic!("not yet implemented: {}", $crate::format_args!($($arg)+)) - }; -} - -/// Definitions of built-in macros. -/// -/// Most of the macro properties (stability, visibility, etc.) are taken from the source code here, -/// with exception of expansion functions transforming macro inputs into outputs, -/// those functions are provided by the compiler. -pub(crate) mod builtin { - - /// Causes compilation to fail with the given error message when encountered. - /// - /// This macro should be used when a crate uses a conditional compilation strategy to provide - /// better error messages for erroneous conditions. It's the compiler-level form of [`panic!`], - /// but emits an error during *compilation* rather than at *runtime*. - /// - /// # Examples - /// - /// Two such examples are macros and `#[cfg]` environments. - /// - /// Emit a better compiler error if a macro is passed invalid values. Without the final branch, - /// the compiler would still emit an error, but the error's message would not mention the two - /// valid values. - /// - /// ```compile_fail - /// macro_rules! give_me_foo_or_bar { - /// (foo) => {}; - /// (bar) => {}; - /// ($x:ident) => { - /// compile_error!("This macro only accepts `foo` or `bar`"); - /// } - /// } - /// - /// give_me_foo_or_bar!(neither); - /// // ^ will fail at compile time with message "This macro only accepts `foo` or `bar`" - /// ``` - /// - /// Emit a compiler error if one of a number of features isn't available. - /// - /// ```compile_fail - /// #[cfg(not(any(feature = "foo", feature = "bar")))] - /// compile_error!("Either feature \"foo\" or \"bar\" must be enabled for this crate."); - /// ``` - #[stable(feature = "compile_error_macro", since = "1.20.0")] - #[rustc_builtin_macro] - #[macro_export] - macro_rules! compile_error { - ($msg:expr $(,)?) => {{ /* compiler built-in */ }}; - } - - /// Constructs parameters for the other string-formatting macros. - /// - /// This macro functions by taking a formatting string literal containing - /// `{}` for each additional argument passed. `format_args!` prepares the - /// additional parameters to ensure the output can be interpreted as a string - /// and canonicalizes the arguments into a single type. Any value that implements - /// the [`Display`] trait can be passed to `format_args!`, as can any - /// [`Debug`] implementation be passed to a `{:?}` within the formatting string. - /// - /// This macro produces a value of type [`fmt::Arguments`]. This value can be - /// passed to the macros within [`std::fmt`] for performing useful redirection. - /// All other formatting macros ([`format!`], [`write!`], [`println!`], etc) are - /// proxied through this one. `format_args!`, unlike its derived macros, avoids - /// heap allocations. - /// - /// You can use the [`fmt::Arguments`] value that `format_args!` returns - /// in `Debug` and `Display` contexts as seen below. The example also shows - /// that `Debug` and `Display` format to the same thing: the interpolated - /// format string in `format_args!`. - /// - /// ```rust - /// let debug = format!("{:?}", format_args!("{} foo {:?}", 1, 2)); - /// let display = format!("{}", format_args!("{} foo {:?}", 1, 2)); - /// assert_eq!("1 foo 2", display); - /// assert_eq!(display, debug); - /// ``` - /// - /// See [the formatting documentation in `std::fmt`](../std/fmt/index.html) - /// for details of the macro argument syntax, and further information. - /// - /// [`Display`]: crate::fmt::Display - /// [`Debug`]: crate::fmt::Debug - /// [`fmt::Arguments`]: crate::fmt::Arguments - /// [`std::fmt`]: ../std/fmt/index.html - /// [`format!`]: ../std/macro.format.html - /// [`println!`]: ../std/macro.println.html - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// - /// let s = fmt::format(format_args!("hello {}", "world")); - /// assert_eq!(s, format!("hello {}", "world")); - /// ``` - /// - /// # Lifetime limitation - /// - /// Except when no formatting arguments are used, - /// the produced `fmt::Arguments` value borrows temporary values, - /// which means it can only be used within the same expression - /// and cannot be stored for later use. - /// This is a known limitation, see [#92698](https://github.com/rust-lang/rust/issues/92698). - #[stable(feature = "rust1", since = "1.0.0")] - #[cfg_attr(not(test), rustc_diagnostic_item = "format_args_macro")] - #[allow_internal_unsafe] - #[allow_internal_unstable(fmt_internals)] - #[rustc_builtin_macro] - #[macro_export] - macro_rules! format_args { - ($fmt:expr) => {{ /* compiler built-in */ }}; - ($fmt:expr, $($args:tt)*) => {{ /* compiler built-in */ }}; - } - - /// Same as [`format_args`], but can be used in some const contexts. - /// - /// This macro is used by the panic macros for the `const_panic` feature. - /// - /// This macro will be removed once `format_args` is allowed in const contexts. - #[unstable(feature = "const_format_args", issue = "none")] - #[allow_internal_unstable(fmt_internals, const_fmt_arguments_new)] - #[rustc_builtin_macro] - #[macro_export] - macro_rules! const_format_args { - ($fmt:expr) => {{ /* compiler built-in */ }}; - ($fmt:expr, $($args:tt)*) => {{ /* compiler built-in */ }}; - } - - /// Same as [`format_args`], but adds a newline in the end. - #[unstable( - feature = "format_args_nl", - issue = "none", - reason = "`format_args_nl` is only for internal \ - language use and is subject to change" - )] - #[allow_internal_unstable(fmt_internals)] - #[rustc_builtin_macro] - #[macro_export] - macro_rules! format_args_nl { - ($fmt:expr) => {{ /* compiler built-in */ }}; - ($fmt:expr, $($args:tt)*) => {{ /* compiler built-in */ }}; - } - - /// Inspects an environment variable at compile time. - /// - /// This macro will expand to the value of the named environment variable at - /// compile time, yielding an expression of type `&'static str`. Use - /// [`std::env::var`] instead if you want to read the value at runtime. - /// - /// [`std::env::var`]: ../std/env/fn.var.html - /// - /// If the environment variable is not defined, then a compilation error - /// will be emitted. To not emit a compile error, use the [`option_env!`] - /// macro instead. A compilation error will also be emitted if the - /// environment variable is not a vaild Unicode string. - /// - /// # Examples - /// - /// ``` - /// let path: &'static str = env!("PATH"); - /// println!("the $PATH variable at the time of compiling was: {path}"); - /// ``` - /// - /// You can customize the error message by passing a string as the second - /// parameter: - /// - /// ```compile_fail - /// let doc: &'static str = env!("documentation", "what's that?!"); - /// ``` - /// - /// If the `documentation` environment variable is not defined, you'll get - /// the following error: - /// - /// ```text - /// error: what's that?! - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_builtin_macro] - #[macro_export] - #[rustc_diagnostic_item = "env_macro"] // useful for external lints - macro_rules! env { - ($name:expr $(,)?) => {{ /* compiler built-in */ }}; - ($name:expr, $error_msg:expr $(,)?) => {{ /* compiler built-in */ }}; - } - - /// Optionally inspects an environment variable at compile time. - /// - /// If the named environment variable is present at compile time, this will - /// expand into an expression of type `Option<&'static str>` whose value is - /// `Some` of the value of the environment variable. If the environment - /// variable is not present, then this will expand to `None`. See - /// [`Option`][Option] for more information on this type. Use - /// [`std::env::var`] instead if you want to read the value at runtime. - /// - /// [`std::env::var`]: ../std/env/fn.var.html - /// - /// A compile time error is never emitted when using this macro regardless - /// of whether the environment variable is present or not. - /// To emit a compile error if the environment variable is not present, - /// use the [`env!`] macro instead. - /// - /// # Examples - /// - /// ``` - /// let key: Option<&'static str> = option_env!("SECRET_KEY"); - /// println!("the secret key might be: {key:?}"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_builtin_macro] - #[macro_export] - #[rustc_diagnostic_item = "option_env_macro"] // useful for external lints - macro_rules! option_env { - ($name:expr $(,)?) => {{ /* compiler built-in */ }}; - } - - /// Concatenates identifiers into one identifier. - /// - /// This macro takes any number of comma-separated identifiers, and - /// concatenates them all into one, yielding an expression which is a new - /// identifier. Note that hygiene makes it such that this macro cannot - /// capture local variables. Also, as a general rule, macros are only - /// allowed in item, statement or expression position. That means while - /// you may use this macro for referring to existing variables, functions or - /// modules etc, you cannot define a new one with it. - /// - /// # Examples - /// - /// ``` - /// #![feature(concat_idents)] - /// - /// # fn main() { - /// fn foobar() -> u32 { 23 } - /// - /// let f = concat_idents!(foo, bar); - /// println!("{}", f()); - /// - /// // fn concat_idents!(new, fun, name) { } // not usable in this way! - /// # } - /// ``` - #[unstable( - feature = "concat_idents", - issue = "29599", - reason = "`concat_idents` is not stable enough for use and is subject to change" - )] - #[rustc_builtin_macro] - #[macro_export] - macro_rules! concat_idents { - ($($e:ident),+ $(,)?) => {{ /* compiler built-in */ }}; - } - - /// Concatenates literals into a byte slice. - /// - /// This macro takes any number of comma-separated literals, and concatenates them all into - /// one, yielding an expression of type `&[u8; _]`, which represents all of the literals - /// concatenated left-to-right. The literals passed can be any combination of: - /// - /// - byte literals (`b'r'`) - /// - byte strings (`b"Rust"`) - /// - arrays of bytes/numbers (`[b'A', 66, b'C']`) - /// - /// # Examples - /// - /// ``` - /// #![feature(concat_bytes)] - /// - /// # fn main() { - /// let s: &[u8; 6] = concat_bytes!(b'A', b"BC", [68, b'E', 70]); - /// assert_eq!(s, b"ABCDEF"); - /// # } - /// ``` - #[unstable(feature = "concat_bytes", issue = "87555")] - #[rustc_builtin_macro] - #[macro_export] - macro_rules! concat_bytes { - ($($e:literal),+ $(,)?) => {{ /* compiler built-in */ }}; - } - - /// Concatenates literals into a static string slice. - /// - /// This macro takes any number of comma-separated literals, yielding an - /// expression of type `&'static str` which represents all of the literals - /// concatenated left-to-right. - /// - /// Integer and floating point literals are [stringified](core::stringify) in order to be - /// concatenated. - /// - /// # Examples - /// - /// ``` - /// let s = concat!("test", 10, 'b', true); - /// assert_eq!(s, "test10btrue"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_builtin_macro] - #[macro_export] - macro_rules! concat { - ($($e:expr),* $(,)?) => {{ /* compiler built-in */ }}; - } - - /// Expands to the line number on which it was invoked. - /// - /// With [`column!`] and [`file!`], these macros provide debugging information for - /// developers about the location within the source. - /// - /// The expanded expression has type `u32` and is 1-based, so the first line - /// in each file evaluates to 1, the second to 2, etc. This is consistent - /// with error messages by common compilers or popular editors. - /// The returned line is *not necessarily* the line of the `line!` invocation itself, - /// but rather the first macro invocation leading up to the invocation - /// of the `line!` macro. - /// - /// # Examples - /// - /// ``` - /// let current_line = line!(); - /// println!("defined on line: {current_line}"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_builtin_macro] - #[macro_export] - macro_rules! line { - () => { - /* compiler built-in */ - }; - } - - /// Expands to the column number at which it was invoked. - /// - /// With [`line!`] and [`file!`], these macros provide debugging information for - /// developers about the location within the source. - /// - /// The expanded expression has type `u32` and is 1-based, so the first column - /// in each line evaluates to 1, the second to 2, etc. This is consistent - /// with error messages by common compilers or popular editors. - /// The returned column is *not necessarily* the line of the `column!` invocation itself, - /// but rather the first macro invocation leading up to the invocation - /// of the `column!` macro. - /// - /// # Examples - /// - /// ``` - /// let current_col = column!(); - /// println!("defined on column: {current_col}"); - /// ``` - /// - /// `column!` counts Unicode code points, not bytes or graphemes. As a result, the first two - /// invocations return the same value, but the third does not. - /// - /// ``` - /// let a = ("foobar", column!()).1; - /// let b = ("人之初性本善", column!()).1; - /// let c = ("f̅o̅o̅b̅a̅r̅", column!()).1; // Uses combining overline (U+0305) - /// - /// assert_eq!(a, b); - /// assert_ne!(b, c); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_builtin_macro] - #[macro_export] - macro_rules! column { - () => { - /* compiler built-in */ - }; - } - - /// Expands to the file name in which it was invoked. - /// - /// With [`line!`] and [`column!`], these macros provide debugging information for - /// developers about the location within the source. - /// - /// The expanded expression has type `&'static str`, and the returned file - /// is not the invocation of the `file!` macro itself, but rather the - /// first macro invocation leading up to the invocation of the `file!` - /// macro. - /// - /// # Examples - /// - /// ``` - /// let this_file = file!(); - /// println!("defined in file: {this_file}"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_builtin_macro] - #[macro_export] - macro_rules! file { - () => { - /* compiler built-in */ - }; - } - - /// Stringifies its arguments. - /// - /// This macro will yield an expression of type `&'static str` which is the - /// stringification of all the tokens passed to the macro. No restrictions - /// are placed on the syntax of the macro invocation itself. - /// - /// Note that the expanded results of the input tokens may change in the - /// future. You should be careful if you rely on the output. - /// - /// # Examples - /// - /// ``` - /// let one_plus_one = stringify!(1 + 1); - /// assert_eq!(one_plus_one, "1 + 1"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_builtin_macro] - #[macro_export] - macro_rules! stringify { - ($($t:tt)*) => { - /* compiler built-in */ - }; - } - - /// Includes a UTF-8 encoded file as a string. - /// - /// The file is located relative to the current file (similarly to how - /// modules are found). The provided path is interpreted in a platform-specific - /// way at compile time. So, for instance, an invocation with a Windows path - /// containing backslashes `\` would not compile correctly on Unix. - /// - /// This macro will yield an expression of type `&'static str` which is the - /// contents of the file. - /// - /// # Examples - /// - /// Assume there are two files in the same directory with the following - /// contents: - /// - /// File 'spanish.in': - /// - /// ```text - /// adiós - /// ``` - /// - /// File 'main.rs': - /// - /// ```ignore (cannot-doctest-external-file-dependency) - /// fn main() { - /// let my_str = include_str!("spanish.in"); - /// assert_eq!(my_str, "adiós\n"); - /// print!("{my_str}"); - /// } - /// ``` - /// - /// Compiling 'main.rs' and running the resulting binary will print "adiós". - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_builtin_macro] - #[macro_export] - #[cfg_attr(not(test), rustc_diagnostic_item = "include_str_macro")] - macro_rules! include_str { - ($file:expr $(,)?) => {{ /* compiler built-in */ }}; - } - - /// Includes a file as a reference to a byte array. - /// - /// The file is located relative to the current file (similarly to how - /// modules are found). The provided path is interpreted in a platform-specific - /// way at compile time. So, for instance, an invocation with a Windows path - /// containing backslashes `\` would not compile correctly on Unix. - /// - /// This macro will yield an expression of type `&'static [u8; N]` which is - /// the contents of the file. - /// - /// # Examples - /// - /// Assume there are two files in the same directory with the following - /// contents: - /// - /// File 'spanish.in': - /// - /// ```text - /// adiós - /// ``` - /// - /// File 'main.rs': - /// - /// ```ignore (cannot-doctest-external-file-dependency) - /// fn main() { - /// let bytes = include_bytes!("spanish.in"); - /// assert_eq!(bytes, b"adi\xc3\xb3s\n"); - /// print!("{}", String::from_utf8_lossy(bytes)); - /// } - /// ``` - /// - /// Compiling 'main.rs' and running the resulting binary will print "adiós". - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_builtin_macro] - #[macro_export] - #[cfg_attr(not(test), rustc_diagnostic_item = "include_bytes_macro")] - macro_rules! include_bytes { - ($file:expr $(,)?) => {{ /* compiler built-in */ }}; - } - - /// Expands to a string that represents the current module path. - /// - /// The current module path can be thought of as the hierarchy of modules - /// leading back up to the crate root. The first component of the path - /// returned is the name of the crate currently being compiled. - /// - /// # Examples - /// - /// ``` - /// mod test { - /// pub fn foo() { - /// assert!(module_path!().ends_with("test")); - /// } - /// } - /// - /// test::foo(); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_builtin_macro] - #[macro_export] - macro_rules! module_path { - () => { - /* compiler built-in */ - }; - } - - /// Evaluates boolean combinations of configuration flags at compile-time. - /// - /// In addition to the `#[cfg]` attribute, this macro is provided to allow - /// boolean expression evaluation of configuration flags. This frequently - /// leads to less duplicated code. - /// - /// The syntax given to this macro is the same syntax as the [`cfg`] - /// attribute. - /// - /// `cfg!`, unlike `#[cfg]`, does not remove any code and only evaluates to true or false. For - /// example, all blocks in an if/else expression need to be valid when `cfg!` is used for - /// the condition, regardless of what `cfg!` is evaluating. - /// - /// [`cfg`]: ../reference/conditional-compilation.html#the-cfg-attribute - /// - /// # Examples - /// - /// ``` - /// let my_directory = if cfg!(windows) { - /// "windows-specific-directory" - /// } else { - /// "unix-directory" - /// }; - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_builtin_macro] - #[macro_export] - macro_rules! cfg { - ($($cfg:tt)*) => { - /* compiler built-in */ - }; - } - - /// Parses a file as an expression or an item according to the context. - /// - /// **Warning**: For multi-file Rust projects, the `include!` macro is probably not what you - /// are looking for. Usually, multi-file Rust projects use - /// [modules](https://doc.rust-lang.org/reference/items/modules.html). Multi-file projects and - /// modules are explained in the Rust-by-Example book - /// [here](https://doc.rust-lang.org/rust-by-example/mod/split.html) and the module system is - /// explained in the Rust Book - /// [here](https://doc.rust-lang.org/book/ch07-02-defining-modules-to-control-scope-and-privacy.html). - /// - /// The included file is placed in the surrounding code - /// [unhygienically](https://doc.rust-lang.org/reference/macros-by-example.html#hygiene). If - /// the included file is parsed as an expression and variables or functions share names across - /// both files, it could result in variables or functions being different from what the - /// included file expected. - /// - /// The included file is located relative to the current file (similarly to how modules are - /// found). The provided path is interpreted in a platform-specific way at compile time. So, - /// for instance, an invocation with a Windows path containing backslashes `\` would not - /// compile correctly on Unix. - /// - /// # Uses - /// - /// The `include!` macro is primarily used for two purposes. It is used to include - /// documentation that is written in a separate file and it is used to include [build artifacts - /// usually as a result from the `build.rs` - /// script](https://doc.rust-lang.org/cargo/reference/build-scripts.html#outputs-of-the-build-script). - /// - /// When using the `include` macro to include stretches of documentation, remember that the - /// included file still needs to be a valid Rust syntax. It is also possible to - /// use the [`include_str`] macro as `#![doc = include_str!("...")]` (at the module level) or - /// `#[doc = include_str!("...")]` (at the item level) to include documentation from a plain - /// text or markdown file. - /// - /// # Examples - /// - /// Assume there are two files in the same directory with the following contents: - /// - /// File 'monkeys.in': - /// - /// ```ignore (only-for-syntax-highlight) - /// ['🙈', '🙊', '🙉'] - /// .iter() - /// .cycle() - /// .take(6) - /// .collect::() - /// ``` - /// - /// File 'main.rs': - /// - /// ```ignore (cannot-doctest-external-file-dependency) - /// fn main() { - /// let my_string = include!("monkeys.in"); - /// assert_eq!("🙈🙊🙉🙈🙊🙉", my_string); - /// println!("{my_string}"); - /// } - /// ``` - /// - /// Compiling 'main.rs' and running the resulting binary will print - /// "🙈🙊🙉🙈🙊🙉". - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_builtin_macro] - #[macro_export] - #[rustc_diagnostic_item = "include_macro"] // useful for external lints - macro_rules! include { - ($file:expr $(,)?) => {{ /* compiler built-in */ }}; - } - - /// Asserts that a boolean expression is `true` at runtime. - /// - /// This will invoke the [`panic!`] macro if the provided expression cannot be - /// evaluated to `true` at runtime. - /// - /// # Uses - /// - /// Assertions are always checked in both debug and release builds, and cannot - /// be disabled. See [`debug_assert!`] for assertions that are not enabled in - /// release builds by default. - /// - /// Unsafe code may rely on `assert!` to enforce run-time invariants that, if - /// violated could lead to unsafety. - /// - /// Other use-cases of `assert!` include testing and enforcing run-time - /// invariants in safe code (whose violation cannot result in unsafety). - /// - /// # Custom Messages - /// - /// This macro has a second form, where a custom panic message can - /// be provided with or without arguments for formatting. See [`std::fmt`] - /// for syntax for this form. Expressions used as format arguments will only - /// be evaluated if the assertion fails. - /// - /// [`std::fmt`]: ../std/fmt/index.html - /// - /// # Examples - /// - /// ``` - /// // the panic message for these assertions is the stringified value of the - /// // expression given. - /// assert!(true); - /// - /// fn some_computation() -> bool { true } // a very simple function - /// - /// assert!(some_computation()); - /// - /// // assert with a custom message - /// let x = true; - /// assert!(x, "x wasn't true!"); - /// - /// let a = 3; let b = 27; - /// assert!(a + b == 30, "a = {}, b = {}", a, b); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_builtin_macro] - #[macro_export] - #[rustc_diagnostic_item = "assert_macro"] - #[allow_internal_unstable(panic_internals, edition_panic, generic_assert_internals)] - macro_rules! assert { - ($cond:expr $(,)?) => {{ /* compiler built-in */ }}; - ($cond:expr, $($arg:tt)+) => {{ /* compiler built-in */ }}; - } - - /// Prints passed tokens into the standard output. - #[unstable( - feature = "log_syntax", - issue = "29598", - reason = "`log_syntax!` is not stable enough for use and is subject to change" - )] - #[rustc_builtin_macro] - #[macro_export] - macro_rules! log_syntax { - ($($arg:tt)*) => { - /* compiler built-in */ - }; - } - - /// Enables or disables tracing functionality used for debugging other macros. - #[unstable( - feature = "trace_macros", - issue = "29598", - reason = "`trace_macros` is not stable enough for use and is subject to change" - )] - #[rustc_builtin_macro] - #[macro_export] - macro_rules! trace_macros { - (true) => {{ /* compiler built-in */ }}; - (false) => {{ /* compiler built-in */ }}; - } - - /// Attribute macro used to apply derive macros. - /// - /// See [the reference] for more info. - /// - /// [the reference]: ../../../reference/attributes/derive.html - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_builtin_macro] - pub macro derive($item:item) { - /* compiler built-in */ - } - - /// Attribute macro used to apply derive macros for implementing traits - /// in a const context. - /// - /// See [the reference] for more info. - /// - /// [the reference]: ../../../reference/attributes/derive.html - #[unstable(feature = "derive_const", issue = "none")] - #[rustc_builtin_macro] - pub macro derive_const($item:item) { - /* compiler built-in */ - } - - /// Attribute macro applied to a function to turn it into a unit test. - /// - /// See [the reference] for more info. - /// - /// [the reference]: ../../../reference/attributes/testing.html#the-test-attribute - #[stable(feature = "rust1", since = "1.0.0")] - #[allow_internal_unstable(test, rustc_attrs, coverage_attribute)] - #[rustc_builtin_macro] - pub macro test($item:item) { - /* compiler built-in */ - } - - /// Attribute macro applied to a function to turn it into a benchmark test. - #[unstable( - feature = "test", - issue = "50297", - soft, - reason = "`bench` is a part of custom test frameworks which are unstable" - )] - #[allow_internal_unstable(test, rustc_attrs, coverage_attribute)] - #[rustc_builtin_macro] - pub macro bench($item:item) { - /* compiler built-in */ - } - - /// An implementation detail of the `#[test]` and `#[bench]` macros. - #[unstable( - feature = "custom_test_frameworks", - issue = "50297", - reason = "custom test frameworks are an unstable feature" - )] - #[allow_internal_unstable(test, rustc_attrs)] - #[rustc_builtin_macro] - pub macro test_case($item:item) { - /* compiler built-in */ - } - - /// Attribute macro applied to a static to register it as a global allocator. - /// - /// See also [`std::alloc::GlobalAlloc`](../../../std/alloc/trait.GlobalAlloc.html). - #[stable(feature = "global_allocator", since = "1.28.0")] - #[allow_internal_unstable(rustc_attrs)] - #[rustc_builtin_macro] - pub macro global_allocator($item:item) { - /* compiler built-in */ - } - - /// Attribute macro applied to a function to register it as a handler for allocation failure. - /// - /// See also [`std::alloc::handle_alloc_error`](../../../std/alloc/fn.handle_alloc_error.html). - #[unstable(feature = "alloc_error_handler", issue = "51540")] - #[allow_internal_unstable(rustc_attrs)] - #[rustc_builtin_macro] - pub macro alloc_error_handler($item:item) { - /* compiler built-in */ - } - - /// Keeps the item it's applied to if the passed path is accessible, and removes it otherwise. - #[unstable( - feature = "cfg_accessible", - issue = "64797", - reason = "`cfg_accessible` is not fully implemented" - )] - #[rustc_builtin_macro] - pub macro cfg_accessible($item:item) { - /* compiler built-in */ - } - - /// Expands all `#[cfg]` and `#[cfg_attr]` attributes in the code fragment it's applied to. - #[unstable( - feature = "cfg_eval", - issue = "82679", - reason = "`cfg_eval` is a recently implemented feature" - )] - #[rustc_builtin_macro] - pub macro cfg_eval($($tt:tt)*) { - /* compiler built-in */ - } - - /// Unstable placeholder for type ascription. - #[allow_internal_unstable(builtin_syntax)] - #[unstable( - feature = "type_ascription", - issue = "23416", - reason = "placeholder syntax for type ascription" - )] - #[rustfmt::skip] - pub macro type_ascribe($expr:expr, $ty:ty) { - builtin # type_ascribe($expr, $ty) - } - - /// Unstable placeholder for deref patterns. - #[allow_internal_unstable(builtin_syntax)] - #[unstable( - feature = "deref_patterns", - issue = "87121", - reason = "placeholder syntax for deref patterns" - )] - pub macro deref($pat:pat) { - builtin # deref($pat) - } - - /// Derive macro for `rustc-serialize`. Should not be used in new code. - #[rustc_builtin_macro] - #[unstable( - feature = "rustc_encodable_decodable", - issue = "none", - soft, - reason = "derive macro for `rustc-serialize`; should not be used in new code" - )] - #[deprecated(since = "1.52.0", note = "rustc-serialize is deprecated and no longer supported")] - #[doc(hidden)] // While technically stable, using it is unstable, and deprecated. Hide it. - pub macro RustcDecodable($item:item) { - /* compiler built-in */ - } - - /// Derive macro for `rustc-serialize`. Should not be used in new code. - #[rustc_builtin_macro] - #[unstable( - feature = "rustc_encodable_decodable", - issue = "none", - soft, - reason = "derive macro for `rustc-serialize`; should not be used in new code" - )] - #[deprecated(since = "1.52.0", note = "rustc-serialize is deprecated and no longer supported")] - #[doc(hidden)] // While technically stable, using it is unstable, and deprecated. Hide it. - pub macro RustcEncodable($item:item) { - /* compiler built-in */ - } -} diff --git a/library/core/src/macros/panic.md b/library/core/src/macros/panic.md deleted file mode 100644 index 6bd23b3072ed9..0000000000000 --- a/library/core/src/macros/panic.md +++ /dev/null @@ -1,99 +0,0 @@ -Panics the current thread. - -This allows a program to terminate immediately and provide feedback -to the caller of the program. - -This macro is the perfect way to assert conditions in example code and in -tests. `panic!` is closely tied with the `unwrap` method of both -[`Option`][ounwrap] and [`Result`][runwrap] enums. Both implementations call -`panic!` when they are set to [`None`] or [`Err`] variants. - -When using `panic!()` you can specify a string payload that is built using -[formatting syntax]. That payload is used when injecting the panic into -the calling Rust thread, causing the thread to panic entirely. - -The behavior of the default `std` hook, i.e. the code that runs directly -after the panic is invoked, is to print the message payload to -`stderr` along with the file/line/column information of the `panic!()` -call. You can override the panic hook using [`std::panic::set_hook()`]. -Inside the hook a panic can be accessed as a `&dyn Any + Send`, -which contains either a `&str` or `String` for regular `panic!()` invocations. -(Whether a particular invocation contains the payload at type `&str` or `String` is unspecified and can change.) -To panic with a value of another other type, [`panic_any`] can be used. - -See also the macro [`compile_error!`], for raising errors during compilation. - -# When to use `panic!` vs `Result` - -The Rust language provides two complementary systems for constructing / -representing, reporting, propagating, reacting to, and discarding errors. These -responsibilities are collectively known as "error handling." `panic!` and -`Result` are similar in that they are each the primary interface of their -respective error handling systems; however, the meaning these interfaces attach -to their errors and the responsibilities they fulfill within their respective -error handling systems differ. - -The `panic!` macro is used to construct errors that represent a bug that has -been detected in your program. With `panic!` you provide a message that -describes the bug and the language then constructs an error with that message, -reports it, and propagates it for you. - -`Result` on the other hand is used to wrap other types that represent either -the successful result of some computation, `Ok(T)`, or error types that -represent an anticipated runtime failure mode of that computation, `Err(E)`. -`Result` is used alongside user defined types which represent the various -anticipated runtime failure modes that the associated computation could -encounter. `Result` must be propagated manually, often with the help of the -`?` operator and `Try` trait, and they must be reported manually, often with -the help of the `Error` trait. - -For more detailed information about error handling check out the [book] or the -[`std::result`] module docs. - -[ounwrap]: Option::unwrap -[runwrap]: Result::unwrap -[`std::panic::set_hook()`]: ../std/panic/fn.set_hook.html -[`panic_any`]: ../std/panic/fn.panic_any.html -[`Box`]: ../std/boxed/struct.Box.html -[`Any`]: crate::any::Any -[formatting syntax]: ../std/fmt/index.html -[book]: ../book/ch09-00-error-handling.html -[`std::result`]: ../std/result/index.html - -# Current implementation - -If the main thread panics it will terminate all your threads and end your -program with code `101`. - -# Editions - -Behavior of the panic macros changed over editions. - -## 2021 and later - -In Rust 2021 and later, `panic!` always requires a format string and -the applicable format arguments, and is the same in `core` and `std`. -Use [`std::panic::panic_any(x)`](../std/panic/fn.panic_any.html) to -panic with an arbitrary payload. - -## 2018 and 2015 - -In Rust Editions prior to 2021, `std::panic!(x)` with a single -argument directly uses that argument as a payload. -This is true even if the argument is a string literal. -For example, `panic!("problem: {reason}")` panics with a -payload of literally `"problem: {reason}"` (a `&'static str`). - -`core::panic!(x)` with a single argument requires that `x` be `&str`, -but otherwise behaves like `std::panic!`. In particular, the string -need not be a literal, and is not interpreted as a format string. - -# Examples - -```should_panic -# #![allow(unreachable_code)] -panic!(); -panic!("this is a terrible mistake!"); -panic!("this is a {} {message}", "fancy", message = "message"); -std::panic::panic_any(4); // panic with the value of 4 to be collected elsewhere -``` diff --git a/library/core/src/marker.rs b/library/core/src/marker.rs deleted file mode 100644 index 1d073a6d649b8..0000000000000 --- a/library/core/src/marker.rs +++ /dev/null @@ -1,1021 +0,0 @@ -//! Primitive traits and types representing basic properties of types. -//! -//! Rust types can be classified in various useful ways according to -//! their intrinsic properties. These classifications are represented -//! as traits. - -#![stable(feature = "rust1", since = "1.0.0")] - -use crate::cell::UnsafeCell; -use crate::cmp; -use crate::fmt::Debug; -use crate::hash::Hash; -use crate::hash::Hasher; - -/// Implements a given marker trait for multiple types at the same time. -/// -/// The basic syntax looks like this: -/// ```ignore private macro -/// marker_impls! { MarkerTrait for u8, i8 } -/// ``` -/// You can also implement `unsafe` traits -/// ```ignore private macro -/// marker_impls! { unsafe MarkerTrait for u8, i8 } -/// ``` -/// Add attributes to all impls: -/// ```ignore private macro -/// marker_impls! { -/// #[allow(lint)] -/// #[unstable(feature = "marker_trait", issue = "none")] -/// MarkerTrait for u8, i8 -/// } -/// ``` -/// And use generics: -/// ```ignore private macro -/// marker_impls! { -/// MarkerTrait for -/// u8, i8, -/// {T: ?Sized} *const T, -/// {T: ?Sized} *mut T, -/// {T: MarkerTrait} PhantomData, -/// u32, -/// } -/// ``` -#[unstable(feature = "internal_impls_macro", issue = "none")] -macro marker_impls { - ( $(#[$($meta:tt)*])* $Trait:ident for $({$($bounds:tt)*})? $T:ty $(, $($rest:tt)*)? ) => { - $(#[$($meta)*])* impl< $($($bounds)*)? > $Trait for $T {} - marker_impls! { $(#[$($meta)*])* $Trait for $($($rest)*)? } - }, - ( $(#[$($meta:tt)*])* $Trait:ident for ) => {}, - - ( $(#[$($meta:tt)*])* unsafe $Trait:ident for $({$($bounds:tt)*})? $T:ty $(, $($rest:tt)*)? ) => { - $(#[$($meta)*])* unsafe impl< $($($bounds)*)? > $Trait for $T {} - marker_impls! { $(#[$($meta)*])* unsafe $Trait for $($($rest)*)? } - }, - ( $(#[$($meta:tt)*])* unsafe $Trait:ident for ) => {}, -} - -/// Types that can be transferred across thread boundaries. -/// -/// This trait is automatically implemented when the compiler determines it's -/// appropriate. -/// -/// An example of a non-`Send` type is the reference-counting pointer -/// [`rc::Rc`][`Rc`]. If two threads attempt to clone [`Rc`]s that point to the same -/// reference-counted value, they might try to update the reference count at the -/// same time, which is [undefined behavior][ub] because [`Rc`] doesn't use atomic -/// operations. Its cousin [`sync::Arc`][arc] does use atomic operations (incurring -/// some overhead) and thus is `Send`. -/// -/// See [the Nomicon](../../nomicon/send-and-sync.html) and the [`Sync`] trait for more details. -/// -/// [`Rc`]: ../../std/rc/struct.Rc.html -/// [arc]: ../../std/sync/struct.Arc.html -/// [ub]: ../../reference/behavior-considered-undefined.html -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "Send")] -#[diagnostic::on_unimplemented( - message = "`{Self}` cannot be sent between threads safely", - label = "`{Self}` cannot be sent between threads safely" -)] -pub unsafe auto trait Send { - // empty. -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl !Send for *const T {} -#[stable(feature = "rust1", since = "1.0.0")] -impl !Send for *mut T {} - -// Most instances arise automatically, but this instance is needed to link up `T: Sync` with -// `&T: Send` (and it also removes the unsound default instance `T Send` -> `&T: Send` that would -// otherwise exist). -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Send for &T {} - -/// Types with a constant size known at compile time. -/// -/// All type parameters have an implicit bound of `Sized`. The special syntax -/// `?Sized` can be used to remove this bound if it's not appropriate. -/// -/// ``` -/// # #![allow(dead_code)] -/// struct Foo(T); -/// struct Bar(T); -/// -/// // struct FooUse(Foo<[i32]>); // error: Sized is not implemented for [i32] -/// struct BarUse(Bar<[i32]>); // OK -/// ``` -/// -/// The one exception is the implicit `Self` type of a trait. A trait does not -/// have an implicit `Sized` bound as this is incompatible with [trait object]s -/// where, by definition, the trait needs to work with all possible implementors, -/// and thus could be any size. -/// -/// Although Rust will let you bind `Sized` to a trait, you won't -/// be able to use it to form a trait object later: -/// -/// ``` -/// # #![allow(unused_variables)] -/// trait Foo { } -/// trait Bar: Sized { } -/// -/// struct Impl; -/// impl Foo for Impl { } -/// impl Bar for Impl { } -/// -/// let x: &dyn Foo = &Impl; // OK -/// // let y: &dyn Bar = &Impl; // error: the trait `Bar` cannot -/// // be made into an object -/// ``` -/// -/// [trait object]: ../../book/ch17-02-trait-objects.html -#[doc(alias = "?", alias = "?Sized")] -#[stable(feature = "rust1", since = "1.0.0")] -#[lang = "sized"] -#[diagnostic::on_unimplemented( - message = "the size for values of type `{Self}` cannot be known at compilation time", - label = "doesn't have a size known at compile-time" -)] -#[fundamental] // for Default, for example, which requires that `[T]: !Default` be evaluatable -#[rustc_specialization_trait] -#[rustc_deny_explicit_impl(implement_via_object = false)] -#[rustc_coinductive] -pub trait Sized { - // Empty. -} - -/// Types that can be "unsized" to a dynamically-sized type. -/// -/// For example, the sized array type `[i8; 2]` implements `Unsize<[i8]>` and -/// `Unsize`. -/// -/// All implementations of `Unsize` are provided automatically by the compiler. -/// Those implementations are: -/// -/// - Arrays `[T; N]` implement `Unsize<[T]>`. -/// - A type implements `Unsize` if all of these conditions are met: -/// - The type implements `Trait`. -/// - `Trait` is object safe. -/// - The type is sized. -/// - The type outlives `'a`. -/// - Structs `Foo<..., T1, ..., Tn, ...>` implement `Unsize>` -/// where any number of (type and const) parameters may be changed if all of these conditions -/// are met: -/// - Only the last field of `Foo` has a type involving the parameters `T1`, ..., `Tn`. -/// - All other parameters of the struct are equal. -/// - `Field: Unsize>`, where `Field<...>` stands for the actual -/// type of the struct's last field. -/// -/// `Unsize` is used along with [`ops::CoerceUnsized`] to allow -/// "user-defined" containers such as [`Rc`] to contain dynamically-sized -/// types. See the [DST coercion RFC][RFC982] and [the nomicon entry on coercion][nomicon-coerce] -/// for more details. -/// -/// [`ops::CoerceUnsized`]: crate::ops::CoerceUnsized -/// [`Rc`]: ../../std/rc/struct.Rc.html -/// [RFC982]: https://github.com/rust-lang/rfcs/blob/master/text/0982-dst-coercion.md -/// [nomicon-coerce]: ../../nomicon/coercions.html -#[unstable(feature = "unsize", issue = "18598")] -#[lang = "unsize"] -#[rustc_deny_explicit_impl(implement_via_object = false)] -pub trait Unsize { - // Empty. -} - -/// Required trait for constants used in pattern matches. -/// -/// Any type that derives `PartialEq` automatically implements this trait, -/// *regardless* of whether its type-parameters implement `PartialEq`. -/// -/// If a `const` item contains some type that does not implement this trait, -/// then that type either (1.) does not implement `PartialEq` (which means the -/// constant will not provide that comparison method, which code generation -/// assumes is available), or (2.) it implements *its own* version of -/// `PartialEq` (which we assume does not conform to a structural-equality -/// comparison). -/// -/// In either of the two scenarios above, we reject usage of such a constant in -/// a pattern match. -/// -/// See also the [structural match RFC][RFC1445], and [issue 63438] which -/// motivated migrating from an attribute-based design to this trait. -/// -/// [RFC1445]: https://github.com/rust-lang/rfcs/blob/master/text/1445-restrict-constants-in-patterns.md -/// [issue 63438]: https://github.com/rust-lang/rust/issues/63438 -#[unstable(feature = "structural_match", issue = "31434")] -#[diagnostic::on_unimplemented(message = "the type `{Self}` does not `#[derive(PartialEq)]`")] -#[lang = "structural_peq"] -pub trait StructuralPartialEq { - // Empty. -} - -marker_impls! { - #[unstable(feature = "structural_match", issue = "31434")] - StructuralPartialEq for - usize, u8, u16, u32, u64, u128, - isize, i8, i16, i32, i64, i128, - bool, - char, - str /* Technically requires `[u8]: StructuralPartialEq` */, - (), - {T, const N: usize} [T; N], - {T} [T], - {T: ?Sized} &T, -} - -/// Types whose values can be duplicated simply by copying bits. -/// -/// By default, variable bindings have 'move semantics.' In other -/// words: -/// -/// ``` -/// #[derive(Debug)] -/// struct Foo; -/// -/// let x = Foo; -/// -/// let y = x; -/// -/// // `x` has moved into `y`, and so cannot be used -/// -/// // println!("{x:?}"); // error: use of moved value -/// ``` -/// -/// However, if a type implements `Copy`, it instead has 'copy semantics': -/// -/// ``` -/// // We can derive a `Copy` implementation. `Clone` is also required, as it's -/// // a supertrait of `Copy`. -/// #[derive(Debug, Copy, Clone)] -/// struct Foo; -/// -/// let x = Foo; -/// -/// let y = x; -/// -/// // `y` is a copy of `x` -/// -/// println!("{x:?}"); // A-OK! -/// ``` -/// -/// It's important to note that in these two examples, the only difference is whether you -/// are allowed to access `x` after the assignment. Under the hood, both a copy and a move -/// can result in bits being copied in memory, although this is sometimes optimized away. -/// -/// ## How can I implement `Copy`? -/// -/// There are two ways to implement `Copy` on your type. The simplest is to use `derive`: -/// -/// ``` -/// #[derive(Copy, Clone)] -/// struct MyStruct; -/// ``` -/// -/// You can also implement `Copy` and `Clone` manually: -/// -/// ``` -/// struct MyStruct; -/// -/// impl Copy for MyStruct { } -/// -/// impl Clone for MyStruct { -/// fn clone(&self) -> MyStruct { -/// *self -/// } -/// } -/// ``` -/// -/// There is a small difference between the two: the `derive` strategy will also place a `Copy` -/// bound on type parameters, which isn't always desired. -/// -/// ## What's the difference between `Copy` and `Clone`? -/// -/// Copies happen implicitly, for example as part of an assignment `y = x`. The behavior of -/// `Copy` is not overloadable; it is always a simple bit-wise copy. -/// -/// Cloning is an explicit action, `x.clone()`. The implementation of [`Clone`] can -/// provide any type-specific behavior necessary to duplicate values safely. For example, -/// the implementation of [`Clone`] for [`String`] needs to copy the pointed-to string -/// buffer in the heap. A simple bitwise copy of [`String`] values would merely copy the -/// pointer, leading to a double free down the line. For this reason, [`String`] is [`Clone`] -/// but not `Copy`. -/// -/// [`Clone`] is a supertrait of `Copy`, so everything which is `Copy` must also implement -/// [`Clone`]. If a type is `Copy` then its [`Clone`] implementation only needs to return `*self` -/// (see the example above). -/// -/// ## When can my type be `Copy`? -/// -/// A type can implement `Copy` if all of its components implement `Copy`. For example, this -/// struct can be `Copy`: -/// -/// ``` -/// # #[allow(dead_code)] -/// #[derive(Copy, Clone)] -/// struct Point { -/// x: i32, -/// y: i32, -/// } -/// ``` -/// -/// A struct can be `Copy`, and [`i32`] is `Copy`, therefore `Point` is eligible to be `Copy`. -/// By contrast, consider -/// -/// ``` -/// # #![allow(dead_code)] -/// # struct Point; -/// struct PointList { -/// points: Vec, -/// } -/// ``` -/// -/// The struct `PointList` cannot implement `Copy`, because [`Vec`] is not `Copy`. If we -/// attempt to derive a `Copy` implementation, we'll get an error: -/// -/// ```text -/// the trait `Copy` cannot be implemented for this type; field `points` does not implement `Copy` -/// ``` -/// -/// Shared references (`&T`) are also `Copy`, so a type can be `Copy`, even when it holds -/// shared references of types `T` that are *not* `Copy`. Consider the following struct, -/// which can implement `Copy`, because it only holds a *shared reference* to our non-`Copy` -/// type `PointList` from above: -/// -/// ``` -/// # #![allow(dead_code)] -/// # struct PointList; -/// #[derive(Copy, Clone)] -/// struct PointListWrapper<'a> { -/// point_list_ref: &'a PointList, -/// } -/// ``` -/// -/// ## When *can't* my type be `Copy`? -/// -/// Some types can't be copied safely. For example, copying `&mut T` would create an aliased -/// mutable reference. Copying [`String`] would duplicate responsibility for managing the -/// [`String`]'s buffer, leading to a double free. -/// -/// Generalizing the latter case, any type implementing [`Drop`] can't be `Copy`, because it's -/// managing some resource besides its own [`size_of::`] bytes. -/// -/// If you try to implement `Copy` on a struct or enum containing non-`Copy` data, you will get -/// the error [E0204]. -/// -/// [E0204]: ../../error_codes/E0204.html -/// -/// ## When *should* my type be `Copy`? -/// -/// Generally speaking, if your type _can_ implement `Copy`, it should. Keep in mind, though, -/// that implementing `Copy` is part of the public API of your type. If the type might become -/// non-`Copy` in the future, it could be prudent to omit the `Copy` implementation now, to -/// avoid a breaking API change. -/// -/// ## Additional implementors -/// -/// In addition to the [implementors listed below][impls], -/// the following types also implement `Copy`: -/// -/// * Function item types (i.e., the distinct types defined for each function) -/// * Function pointer types (e.g., `fn() -> i32`) -/// * Closure types, if they capture no value from the environment -/// or if all such captured values implement `Copy` themselves. -/// Note that variables captured by shared reference always implement `Copy` -/// (even if the referent doesn't), -/// while variables captured by mutable reference never implement `Copy`. -/// -/// [`Vec`]: ../../std/vec/struct.Vec.html -/// [`String`]: ../../std/string/struct.String.html -/// [`size_of::`]: crate::mem::size_of -/// [impls]: #implementors -#[stable(feature = "rust1", since = "1.0.0")] -#[lang = "copy"] -// FIXME(matthewjasper) This allows copying a type that doesn't implement -// `Copy` because of unsatisfied lifetime bounds (copying `A<'_>` when only -// `A<'static>: Copy` and `A<'_>: Clone`). -// We have this attribute here for now only because there are quite a few -// existing specializations on `Copy` that already exist in the standard -// library, and there's no way to safely have this behavior right now. -#[rustc_unsafe_specialization_marker] -#[rustc_diagnostic_item = "Copy"] -pub trait Copy: Clone { - // Empty. -} - -/// Derive macro generating an impl of the trait `Copy`. -#[rustc_builtin_macro] -#[stable(feature = "builtin_macro_prelude", since = "1.38.0")] -#[allow_internal_unstable(core_intrinsics, derive_clone_copy)] -pub macro Copy($item:item) { - /* compiler built-in */ -} - -// Implementations of `Copy` for primitive types. -// -// Implementations that cannot be described in Rust -// are implemented in `traits::SelectionContext::copy_clone_conditions()` -// in `rustc_trait_selection`. -marker_impls! { - #[stable(feature = "rust1", since = "1.0.0")] - Copy for - usize, u8, u16, u32, u64, u128, - isize, i8, i16, i32, i64, i128, - f16, f32, f64, f128, - bool, char, - {T: ?Sized} *const T, - {T: ?Sized} *mut T, - -} - -#[unstable(feature = "never_type", issue = "35121")] -impl Copy for ! {} - -/// Shared references can be copied, but mutable references *cannot*! -#[stable(feature = "rust1", since = "1.0.0")] -impl Copy for &T {} - -/// Types for which it is safe to share references between threads. -/// -/// This trait is automatically implemented when the compiler determines -/// it's appropriate. -/// -/// The precise definition is: a type `T` is [`Sync`] if and only if `&T` is -/// [`Send`]. In other words, if there is no possibility of -/// [undefined behavior][ub] (including data races) when passing -/// `&T` references between threads. -/// -/// As one would expect, primitive types like [`u8`] and [`f64`] -/// are all [`Sync`], and so are simple aggregate types containing them, -/// like tuples, structs and enums. More examples of basic [`Sync`] -/// types include "immutable" types like `&T`, and those with simple -/// inherited mutability, such as [`Box`][box], [`Vec`][vec] and -/// most other collection types. (Generic parameters need to be [`Sync`] -/// for their container to be [`Sync`].) -/// -/// A somewhat surprising consequence of the definition is that `&mut T` -/// is `Sync` (if `T` is `Sync`) even though it seems like that might -/// provide unsynchronized mutation. The trick is that a mutable -/// reference behind a shared reference (that is, `& &mut T`) -/// becomes read-only, as if it were a `& &T`. Hence there is no risk -/// of a data race. -/// -/// A shorter overview of how [`Sync`] and [`Send`] relate to referencing: -/// * `&T` is [`Send`] if and only if `T` is [`Sync`] -/// * `&mut T` is [`Send`] if and only if `T` is [`Send`] -/// * `&T` and `&mut T` are [`Sync`] if and only if `T` is [`Sync`] -/// -/// Types that are not `Sync` are those that have "interior -/// mutability" in a non-thread-safe form, such as [`Cell`][cell] -/// and [`RefCell`][refcell]. These types allow for mutation of -/// their contents even through an immutable, shared reference. For -/// example the `set` method on [`Cell`][cell] takes `&self`, so it requires -/// only a shared reference [`&Cell`][cell]. The method performs no -/// synchronization, thus [`Cell`][cell] cannot be `Sync`. -/// -/// Another example of a non-`Sync` type is the reference-counting -/// pointer [`Rc`][rc]. Given any reference [`&Rc`][rc], you can clone -/// a new [`Rc`][rc], modifying the reference counts in a non-atomic way. -/// -/// For cases when one does need thread-safe interior mutability, -/// Rust provides [atomic data types], as well as explicit locking via -/// [`sync::Mutex`][mutex] and [`sync::RwLock`][rwlock]. These types -/// ensure that any mutation cannot cause data races, hence the types -/// are `Sync`. Likewise, [`sync::Arc`][arc] provides a thread-safe -/// analogue of [`Rc`][rc]. -/// -/// Any types with interior mutability must also use the -/// [`cell::UnsafeCell`][unsafecell] wrapper around the value(s) which -/// can be mutated through a shared reference. Failing to doing this is -/// [undefined behavior][ub]. For example, [`transmute`][transmute]-ing -/// from `&T` to `&mut T` is invalid. -/// -/// See [the Nomicon][nomicon-send-and-sync] for more details about `Sync`. -/// -/// [box]: ../../std/boxed/struct.Box.html -/// [vec]: ../../std/vec/struct.Vec.html -/// [cell]: crate::cell::Cell -/// [refcell]: crate::cell::RefCell -/// [rc]: ../../std/rc/struct.Rc.html -/// [arc]: ../../std/sync/struct.Arc.html -/// [atomic data types]: crate::sync::atomic -/// [mutex]: ../../std/sync/struct.Mutex.html -/// [rwlock]: ../../std/sync/struct.RwLock.html -/// [unsafecell]: crate::cell::UnsafeCell -/// [ub]: ../../reference/behavior-considered-undefined.html -/// [transmute]: crate::mem::transmute -/// [nomicon-send-and-sync]: ../../nomicon/send-and-sync.html -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "Sync")] -#[lang = "sync"] -#[rustc_on_unimplemented( - on( - _Self = "core::cell::once::OnceCell", - note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::OnceLock` instead" - ), - on( - _Self = "core::cell::Cell", - note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` or `std::sync::atomic::AtomicU8` instead", - ), - on( - _Self = "core::cell::Cell", - note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` or `std::sync::atomic::AtomicU16` instead", - ), - on( - _Self = "core::cell::Cell", - note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` or `std::sync::atomic::AtomicU32` instead", - ), - on( - _Self = "core::cell::Cell", - note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` or `std::sync::atomic::AtomicU64` instead", - ), - on( - _Self = "core::cell::Cell", - note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` or `std::sync::atomic::AtomicUsize` instead", - ), - on( - _Self = "core::cell::Cell", - note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` or `std::sync::atomic::AtomicI8` instead", - ), - on( - _Self = "core::cell::Cell", - note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` or `std::sync::atomic::AtomicI16` instead", - ), - on( - _Self = "core::cell::Cell", - note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` or `std::sync::atomic::AtomicI32` instead", - ), - on( - _Self = "core::cell::Cell", - note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` or `std::sync::atomic::AtomicI64` instead", - ), - on( - _Self = "core::cell::Cell", - note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` or `std::sync::atomic::AtomicIsize` instead", - ), - on( - _Self = "core::cell::Cell", - note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` or `std::sync::atomic::AtomicBool` instead", - ), - on( - all( - _Self = "core::cell::Cell", - not(_Self = "core::cell::Cell"), - not(_Self = "core::cell::Cell"), - not(_Self = "core::cell::Cell"), - not(_Self = "core::cell::Cell"), - not(_Self = "core::cell::Cell"), - not(_Self = "core::cell::Cell"), - not(_Self = "core::cell::Cell"), - not(_Self = "core::cell::Cell"), - not(_Self = "core::cell::Cell"), - not(_Self = "core::cell::Cell"), - not(_Self = "core::cell::Cell") - ), - note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock`", - ), - on( - _Self = "core::cell::RefCell", - note = "if you want to do aliasing and mutation between multiple threads, use `std::sync::RwLock` instead", - ), - message = "`{Self}` cannot be shared between threads safely", - label = "`{Self}` cannot be shared between threads safely" -)] -pub unsafe auto trait Sync { - // FIXME(estebank): once support to add notes in `rustc_on_unimplemented` - // lands in beta, and it has been extended to check whether a closure is - // anywhere in the requirement chain, extend it as such (#48534): - // ``` - // on( - // closure, - // note="`{Self}` cannot be shared safely, consider marking the closure `move`" - // ), - // ``` - - // Empty -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl !Sync for *const T {} -#[stable(feature = "rust1", since = "1.0.0")] -impl !Sync for *mut T {} - -/// Zero-sized type used to mark things that "act like" they own a `T`. -/// -/// Adding a `PhantomData` field to your type tells the compiler that your -/// type acts as though it stores a value of type `T`, even though it doesn't -/// really. This information is used when computing certain safety properties. -/// -/// For a more in-depth explanation of how to use `PhantomData`, please see -/// [the Nomicon](../../nomicon/phantom-data.html). -/// -/// # A ghastly note 👻👻👻 -/// -/// Though they both have scary names, `PhantomData` and 'phantom types' are -/// related, but not identical. A phantom type parameter is simply a type -/// parameter which is never used. In Rust, this often causes the compiler to -/// complain, and the solution is to add a "dummy" use by way of `PhantomData`. -/// -/// # Examples -/// -/// ## Unused lifetime parameters -/// -/// Perhaps the most common use case for `PhantomData` is a struct that has an -/// unused lifetime parameter, typically as part of some unsafe code. For -/// example, here is a struct `Slice` that has two pointers of type `*const T`, -/// presumably pointing into an array somewhere: -/// -/// ```compile_fail,E0392 -/// struct Slice<'a, T> { -/// start: *const T, -/// end: *const T, -/// } -/// ``` -/// -/// The intention is that the underlying data is only valid for the -/// lifetime `'a`, so `Slice` should not outlive `'a`. However, this -/// intent is not expressed in the code, since there are no uses of -/// the lifetime `'a` and hence it is not clear what data it applies -/// to. We can correct this by telling the compiler to act *as if* the -/// `Slice` struct contained a reference `&'a T`: -/// -/// ``` -/// use std::marker::PhantomData; -/// -/// # #[allow(dead_code)] -/// struct Slice<'a, T> { -/// start: *const T, -/// end: *const T, -/// phantom: PhantomData<&'a T>, -/// } -/// ``` -/// -/// This also in turn infers the lifetime bound `T: 'a`, indicating -/// that any references in `T` are valid over the lifetime `'a`. -/// -/// When initializing a `Slice` you simply provide the value -/// `PhantomData` for the field `phantom`: -/// -/// ``` -/// # #![allow(dead_code)] -/// # use std::marker::PhantomData; -/// # struct Slice<'a, T> { -/// # start: *const T, -/// # end: *const T, -/// # phantom: PhantomData<&'a T>, -/// # } -/// fn borrow_vec(vec: &Vec) -> Slice<'_, T> { -/// let ptr = vec.as_ptr(); -/// Slice { -/// start: ptr, -/// end: unsafe { ptr.add(vec.len()) }, -/// phantom: PhantomData, -/// } -/// } -/// ``` -/// -/// ## Unused type parameters -/// -/// It sometimes happens that you have unused type parameters which -/// indicate what type of data a struct is "tied" to, even though that -/// data is not actually found in the struct itself. Here is an -/// example where this arises with [FFI]. The foreign interface uses -/// handles of type `*mut ()` to refer to Rust values of different -/// types. We track the Rust type using a phantom type parameter on -/// the struct `ExternalResource` which wraps a handle. -/// -/// [FFI]: ../../book/ch19-01-unsafe-rust.html#using-extern-functions-to-call-external-code -/// -/// ``` -/// # #![allow(dead_code)] -/// # trait ResType { } -/// # struct ParamType; -/// # mod foreign_lib { -/// # pub fn new(_: usize) -> *mut () { 42 as *mut () } -/// # pub fn do_stuff(_: *mut (), _: usize) {} -/// # } -/// # fn convert_params(_: ParamType) -> usize { 42 } -/// use std::marker::PhantomData; -/// use std::mem; -/// -/// struct ExternalResource { -/// resource_handle: *mut (), -/// resource_type: PhantomData, -/// } -/// -/// impl ExternalResource { -/// fn new() -> Self { -/// let size_of_res = mem::size_of::(); -/// Self { -/// resource_handle: foreign_lib::new(size_of_res), -/// resource_type: PhantomData, -/// } -/// } -/// -/// fn do_stuff(&self, param: ParamType) { -/// let foreign_params = convert_params(param); -/// foreign_lib::do_stuff(self.resource_handle, foreign_params); -/// } -/// } -/// ``` -/// -/// ## Ownership and the drop check -/// -/// The exact interaction of `PhantomData` with drop check **may change in the future**. -/// -/// Currently, adding a field of type `PhantomData` indicates that your type *owns* data of type -/// `T` in very rare circumstances. This in turn has effects on the Rust compiler's [drop check] -/// analysis. For the exact rules, see the [drop check] documentation. -/// -/// ## Layout -/// -/// For all `T`, the following are guaranteed: -/// * `size_of::>() == 0` -/// * `align_of::>() == 1` -/// -/// [drop check]: Drop#drop-check -#[lang = "phantom_data"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct PhantomData; - -#[stable(feature = "rust1", since = "1.0.0")] -impl Hash for PhantomData { - #[inline] - fn hash(&self, _: &mut H) {} -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl cmp::PartialEq for PhantomData { - fn eq(&self, _other: &PhantomData) -> bool { - true - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl cmp::Eq for PhantomData {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl cmp::PartialOrd for PhantomData { - fn partial_cmp(&self, _other: &PhantomData) -> Option { - Option::Some(cmp::Ordering::Equal) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl cmp::Ord for PhantomData { - fn cmp(&self, _other: &PhantomData) -> cmp::Ordering { - cmp::Ordering::Equal - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Copy for PhantomData {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for PhantomData { - fn clone(&self) -> Self { - Self - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Default for PhantomData { - fn default() -> Self { - Self - } -} - -#[unstable(feature = "structural_match", issue = "31434")] -impl StructuralPartialEq for PhantomData {} - -/// Compiler-internal trait used to indicate the type of enum discriminants. -/// -/// This trait is automatically implemented for every type and does not add any -/// guarantees to [`mem::Discriminant`]. It is **undefined behavior** to transmute -/// between `DiscriminantKind::Discriminant` and `mem::Discriminant`. -/// -/// [`mem::Discriminant`]: crate::mem::Discriminant -#[unstable( - feature = "discriminant_kind", - issue = "none", - reason = "this trait is unlikely to ever be stabilized, use `mem::discriminant` instead" -)] -#[lang = "discriminant_kind"] -#[rustc_deny_explicit_impl(implement_via_object = false)] -pub trait DiscriminantKind { - /// The type of the discriminant, which must satisfy the trait - /// bounds required by `mem::Discriminant`. - #[lang = "discriminant_type"] - type Discriminant: Clone + Copy + Debug + Eq + PartialEq + Hash + Send + Sync + Unpin; -} - -/// Used to determine whether a type contains -/// any `UnsafeCell` internally, but not through an indirection. -/// This affects, for example, whether a `static` of that type is -/// placed in read-only static memory or writable static memory. -/// This can be used to declare that a constant with a generic type -/// will not contain interior mutability, and subsequently allow -/// placing the constant behind references. -/// -/// # Safety -/// -/// This trait is a core part of the language, it is just expressed as a trait in libcore for -/// convenience. Do *not* implement it for other types. -// FIXME: Eventually this trait should become `#[rustc_deny_explicit_impl]`. -// That requires porting the impls below to native internal impls. -#[lang = "freeze"] -#[unstable(feature = "freeze", issue = "121675")] -pub unsafe auto trait Freeze {} - -#[unstable(feature = "freeze", issue = "121675")] -impl !Freeze for UnsafeCell {} -marker_impls! { - #[unstable(feature = "freeze", issue = "121675")] - unsafe Freeze for - {T: ?Sized} PhantomData, - {T: ?Sized} *const T, - {T: ?Sized} *mut T, - {T: ?Sized} &T, - {T: ?Sized} &mut T, -} - -/// Types that do not require any pinning guarantees. -/// -/// For information on what "pinning" is, see the [`pin` module] documentation. -/// -/// Implementing the `Unpin` trait for `T` expresses the fact that `T` is pinning-agnostic: -/// it shall not expose nor rely on any pinning guarantees. This, in turn, means that a -/// `Pin`-wrapped pointer to such a type can feature a *fully unrestricted* API. -/// In other words, if `T: Unpin`, a value of type `T` will *not* be bound by the invariants -/// which pinning otherwise offers, even when "pinned" by a [`Pin`] pointing at it. -/// When a value of type `T` is pointed at by a [`Pin`], [`Pin`] will not restrict access -/// to the pointee value like it normally would, thus allowing the user to do anything that they -/// normally could with a non-[`Pin`]-wrapped `Ptr` to that value. -/// -/// The idea of this trait is to alleviate the reduced ergonomics of APIs that require the use -/// of [`Pin`] for soundness for some types, but which also want to be used by other types that -/// don't care about pinning. The prime example of such an API is [`Future::poll`]. There are many -/// [`Future`] types that don't care about pinning. These futures can implement `Unpin` and -/// therefore get around the pinning related restrictions in the API, while still allowing the -/// subset of [`Future`]s which *do* require pinning to be implemented soundly. -/// -/// For more discussion on the consequences of [`Unpin`] within the wider scope of the pinning -/// system, see the [section about `Unpin`] in the [`pin` module]. -/// -/// `Unpin` has no consequence at all for non-pinned data. In particular, [`mem::replace`] happily -/// moves `!Unpin` data, which would be immovable when pinned ([`mem::replace`] works for any -/// `&mut T`, not just when `T: Unpin`). -/// -/// *However*, you cannot use [`mem::replace`] on `!Unpin` data which is *pinned* by being wrapped -/// inside a [`Pin`] pointing at it. This is because you cannot (safely) use a -/// [`Pin`] to get an `&mut T` to its pointee value, which you would need to call -/// [`mem::replace`], and *that* is what makes this system work. -/// -/// So this, for example, can only be done on types implementing `Unpin`: -/// -/// ```rust -/// # #![allow(unused_must_use)] -/// use std::mem; -/// use std::pin::Pin; -/// -/// let mut string = "this".to_string(); -/// let mut pinned_string = Pin::new(&mut string); -/// -/// // We need a mutable reference to call `mem::replace`. -/// // We can obtain such a reference by (implicitly) invoking `Pin::deref_mut`, -/// // but that is only possible because `String` implements `Unpin`. -/// mem::replace(&mut *pinned_string, "other".to_string()); -/// ``` -/// -/// This trait is automatically implemented for almost every type. The compiler is free -/// to take the conservative stance of marking types as [`Unpin`] so long as all of the types that -/// compose its fields are also [`Unpin`]. This is because if a type implements [`Unpin`], then it -/// is unsound for that type's implementation to rely on pinning-related guarantees for soundness, -/// *even* when viewed through a "pinning" pointer! It is the responsibility of the implementor of -/// a type that relies upon pinning for soundness to ensure that type is *not* marked as [`Unpin`] -/// by adding [`PhantomPinned`] field. For more details, see the [`pin` module] docs. -/// -/// [`mem::replace`]: crate::mem::replace "mem replace" -/// [`Future`]: crate::future::Future "Future" -/// [`Future::poll`]: crate::future::Future::poll "Future poll" -/// [`Pin`]: crate::pin::Pin "Pin" -/// [`Pin`]: crate::pin::Pin "Pin" -/// [`pin` module]: crate::pin "pin module" -/// [section about `Unpin`]: crate::pin#unpin "pin module docs about unpin" -/// [`unsafe`]: ../../std/keyword.unsafe.html "keyword unsafe" -#[stable(feature = "pin", since = "1.33.0")] -#[diagnostic::on_unimplemented( - note = "consider using the `pin!` macro\nconsider using `Box::pin` if you need to access the pinned value outside of the current scope", - message = "`{Self}` cannot be unpinned" -)] -#[lang = "unpin"] -pub auto trait Unpin {} - -/// A marker type which does not implement `Unpin`. -/// -/// If a type contains a `PhantomPinned`, it will not implement `Unpin` by default. -#[stable(feature = "pin", since = "1.33.0")] -#[derive(Debug, Default, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)] -pub struct PhantomPinned; - -#[stable(feature = "pin", since = "1.33.0")] -impl !Unpin for PhantomPinned {} - -marker_impls! { - #[stable(feature = "pin", since = "1.33.0")] - Unpin for - {T: ?Sized} &T, - {T: ?Sized} &mut T, -} - -marker_impls! { - #[stable(feature = "pin_raw", since = "1.38.0")] - Unpin for - {T: ?Sized} *const T, - {T: ?Sized} *mut T, -} - -/// A marker for types that can be dropped. -/// -/// This should be used for `~const` bounds, -/// as non-const bounds will always hold for every type. -#[unstable(feature = "const_trait_impl", issue = "67792")] -#[lang = "destruct"] -#[rustc_on_unimplemented(message = "can't drop `{Self}`", append_const_msg)] -#[rustc_deny_explicit_impl(implement_via_object = false)] -#[const_trait] -pub trait Destruct {} - -/// A marker for tuple types. -/// -/// The implementation of this trait is built-in and cannot be implemented -/// for any user type. -#[unstable(feature = "tuple_trait", issue = "none")] -#[lang = "tuple_trait"] -#[diagnostic::on_unimplemented(message = "`{Self}` is not a tuple")] -#[rustc_deny_explicit_impl(implement_via_object = false)] -pub trait Tuple {} - -/// A marker for pointer-like types. -/// -/// All types that have the same size and alignment as a `usize` or -/// `*const ()` automatically implement this trait. -#[unstable(feature = "pointer_like_trait", issue = "none")] -#[lang = "pointer_like"] -#[diagnostic::on_unimplemented( - message = "`{Self}` needs to have the same ABI as a pointer", - label = "`{Self}` needs to be a pointer-like type" -)] -pub trait PointerLike {} - -/// A marker for types which can be used as types of `const` generic parameters. -/// -/// These types must have a proper equivalence relation (`Eq`) and it must be automatically -/// derived (`StructuralPartialEq`). There's a hard-coded check in the compiler ensuring -/// that all fields are also `ConstParamTy`, which implies that recursively, all fields -/// are `StructuralPartialEq`. -#[lang = "const_param_ty"] -#[unstable(feature = "adt_const_params", issue = "95174")] -#[diagnostic::on_unimplemented(message = "`{Self}` can't be used as a const parameter type")] -#[allow(multiple_supertrait_upcastable)] -pub trait ConstParamTy: StructuralPartialEq + Eq {} - -/// Derive macro generating an impl of the trait `ConstParamTy`. -#[rustc_builtin_macro] -#[unstable(feature = "adt_const_params", issue = "95174")] -pub macro ConstParamTy($item:item) { - /* compiler built-in */ -} - -// FIXME(adt_const_params): handle `ty::FnDef`/`ty::Closure` -marker_impls! { - #[unstable(feature = "adt_const_params", issue = "95174")] - ConstParamTy for - usize, u8, u16, u32, u64, u128, - isize, i8, i16, i32, i64, i128, - bool, - char, - str /* Technically requires `[u8]: ConstParamTy` */, - {T: ConstParamTy, const N: usize} [T; N], - {T: ConstParamTy} [T], - {T: ?Sized + ConstParamTy} &T, -} - -// FIXME(adt_const_params): Add to marker_impls call above once not in bootstrap -#[unstable(feature = "adt_const_params", issue = "95174")] -impl ConstParamTy for () {} - -/// A common trait implemented by all function pointers. -#[unstable( - feature = "fn_ptr_trait", - issue = "none", - reason = "internal trait for implementing various traits for all function pointers" -)] -#[lang = "fn_ptr_trait"] -#[rustc_deny_explicit_impl(implement_via_object = false)] -pub trait FnPtr: Copy + Clone { - /// Returns the address of the function pointer. - #[lang = "fn_ptr_addr"] - fn addr(self) -> *const (); -} diff --git a/library/core/src/mem/manually_drop.rs b/library/core/src/mem/manually_drop.rs deleted file mode 100644 index e0c3b9f3b51da..0000000000000 --- a/library/core/src/mem/manually_drop.rs +++ /dev/null @@ -1,166 +0,0 @@ -use crate::ops::{Deref, DerefMut, DerefPure}; -use crate::ptr; - -/// A wrapper to inhibit the compiler from automatically calling `T`’s destructor. -/// This wrapper is 0-cost. -/// -/// `ManuallyDrop` is guaranteed to have the same layout and bit validity as -/// `T`, and is subject to the same layout optimizations as `T`. As a consequence, -/// it has *no effect* on the assumptions that the compiler makes about its -/// contents. For example, initializing a `ManuallyDrop<&mut T>` with [`mem::zeroed`] -/// is undefined behavior. If you need to handle uninitialized data, use -/// [`MaybeUninit`] instead. -/// -/// Note that accessing the value inside a `ManuallyDrop` is safe. -/// This means that a `ManuallyDrop` whose content has been dropped must not -/// be exposed through a public safe API. -/// Correspondingly, `ManuallyDrop::drop` is unsafe. -/// -/// # `ManuallyDrop` and drop order. -/// -/// Rust has a well-defined [drop order] of values. To make sure that fields or -/// locals are dropped in a specific order, reorder the declarations such that -/// the implicit drop order is the correct one. -/// -/// It is possible to use `ManuallyDrop` to control the drop order, but this -/// requires unsafe code and is hard to do correctly in the presence of -/// unwinding. -/// -/// For example, if you want to make sure that a specific field is dropped after -/// the others, make it the last field of a struct: -/// -/// ``` -/// struct Context; -/// -/// struct Widget { -/// children: Vec, -/// // `context` will be dropped after `children`. -/// // Rust guarantees that fields are dropped in the order of declaration. -/// context: Context, -/// } -/// ``` -/// -/// [drop order]: https://doc.rust-lang.org/reference/destructors.html -/// [`mem::zeroed`]: crate::mem::zeroed -/// [`MaybeUninit`]: crate::mem::MaybeUninit -#[stable(feature = "manually_drop", since = "1.20.0")] -#[lang = "manually_drop"] -#[derive(Copy, Clone, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)] -#[repr(transparent)] -pub struct ManuallyDrop { - value: T, -} - -impl ManuallyDrop { - /// Wrap a value to be manually dropped. - /// - /// # Examples - /// - /// ```rust - /// use std::mem::ManuallyDrop; - /// let mut x = ManuallyDrop::new(String::from("Hello World!")); - /// x.truncate(5); // You can still safely operate on the value - /// assert_eq!(*x, "Hello"); - /// // But `Drop` will not be run here - /// ``` - #[must_use = "if you don't need the wrapper, you can use `mem::forget` instead"] - #[stable(feature = "manually_drop", since = "1.20.0")] - #[rustc_const_stable(feature = "const_manually_drop", since = "1.32.0")] - #[inline(always)] - pub const fn new(value: T) -> ManuallyDrop { - ManuallyDrop { value } - } - - /// Extracts the value from the `ManuallyDrop` container. - /// - /// This allows the value to be dropped again. - /// - /// # Examples - /// - /// ```rust - /// use std::mem::ManuallyDrop; - /// let x = ManuallyDrop::new(Box::new(())); - /// let _: Box<()> = ManuallyDrop::into_inner(x); // This drops the `Box`. - /// ``` - #[stable(feature = "manually_drop", since = "1.20.0")] - #[rustc_const_stable(feature = "const_manually_drop", since = "1.32.0")] - #[inline(always)] - pub const fn into_inner(slot: ManuallyDrop) -> T { - slot.value - } - - /// Takes the value from the `ManuallyDrop` container out. - /// - /// This method is primarily intended for moving out values in drop. - /// Instead of using [`ManuallyDrop::drop`] to manually drop the value, - /// you can use this method to take the value and use it however desired. - /// - /// Whenever possible, it is preferable to use [`into_inner`][`ManuallyDrop::into_inner`] - /// instead, which prevents duplicating the content of the `ManuallyDrop`. - /// - /// # Safety - /// - /// This function semantically moves out the contained value without preventing further usage, - /// leaving the state of this container unchanged. - /// It is your responsibility to ensure that this `ManuallyDrop` is not used again. - /// - #[must_use = "if you don't need the value, you can use `ManuallyDrop::drop` instead"] - #[stable(feature = "manually_drop_take", since = "1.42.0")] - #[inline] - pub unsafe fn take(slot: &mut ManuallyDrop) -> T { - // SAFETY: we are reading from a reference, which is guaranteed - // to be valid for reads. - unsafe { ptr::read(&slot.value) } - } -} - -impl ManuallyDrop { - /// Manually drops the contained value. This is exactly equivalent to calling - /// [`ptr::drop_in_place`] with a pointer to the contained value. As such, unless - /// the contained value is a packed struct, the destructor will be called in-place - /// without moving the value, and thus can be used to safely drop [pinned] data. - /// - /// If you have ownership of the value, you can use [`ManuallyDrop::into_inner`] instead. - /// - /// # Safety - /// - /// This function runs the destructor of the contained value. Other than changes made by - /// the destructor itself, the memory is left unchanged, and so as far as the compiler is - /// concerned still holds a bit-pattern which is valid for the type `T`. - /// - /// However, this "zombie" value should not be exposed to safe code, and this function - /// should not be called more than once. To use a value after it's been dropped, or drop - /// a value multiple times, can cause Undefined Behavior (depending on what `drop` does). - /// This is normally prevented by the type system, but users of `ManuallyDrop` must - /// uphold those guarantees without assistance from the compiler. - /// - /// [pinned]: crate::pin - #[stable(feature = "manually_drop", since = "1.20.0")] - #[inline] - pub unsafe fn drop(slot: &mut ManuallyDrop) { - // SAFETY: we are dropping the value pointed to by a mutable reference - // which is guaranteed to be valid for writes. - // It is up to the caller to make sure that `slot` isn't dropped again. - unsafe { ptr::drop_in_place(&mut slot.value) } - } -} - -#[stable(feature = "manually_drop", since = "1.20.0")] -impl Deref for ManuallyDrop { - type Target = T; - #[inline(always)] - fn deref(&self) -> &T { - &self.value - } -} - -#[stable(feature = "manually_drop", since = "1.20.0")] -impl DerefMut for ManuallyDrop { - #[inline(always)] - fn deref_mut(&mut self) -> &mut T { - &mut self.value - } -} - -#[unstable(feature = "deref_pure_trait", issue = "87121")] -unsafe impl DerefPure for ManuallyDrop {} diff --git a/library/core/src/mem/maybe_uninit.rs b/library/core/src/mem/maybe_uninit.rs deleted file mode 100644 index 026e21586d403..0000000000000 --- a/library/core/src/mem/maybe_uninit.rs +++ /dev/null @@ -1,1487 +0,0 @@ -use crate::any::type_name; -use crate::fmt; -use crate::intrinsics; -use crate::mem::{self, ManuallyDrop}; -use crate::ptr; -use crate::slice; - -/// A wrapper type to construct uninitialized instances of `T`. -/// -/// # Initialization invariant -/// -/// The compiler, in general, assumes that a variable is properly initialized -/// according to the requirements of the variable's type. For example, a variable of -/// reference type must be aligned and non-null. This is an invariant that must -/// *always* be upheld, even in unsafe code. As a consequence, zero-initializing a -/// variable of reference type causes instantaneous [undefined behavior][ub], -/// no matter whether that reference ever gets used to access memory: -/// -/// ```rust,no_run -/// # #![allow(invalid_value)] -/// use std::mem::{self, MaybeUninit}; -/// -/// let x: &i32 = unsafe { mem::zeroed() }; // undefined behavior! ⚠️ -/// // The equivalent code with `MaybeUninit<&i32>`: -/// let x: &i32 = unsafe { MaybeUninit::zeroed().assume_init() }; // undefined behavior! ⚠️ -/// ``` -/// -/// This is exploited by the compiler for various optimizations, such as eliding -/// run-time checks and optimizing `enum` layout. -/// -/// Similarly, entirely uninitialized memory may have any content, while a `bool` must -/// always be `true` or `false`. Hence, creating an uninitialized `bool` is undefined behavior: -/// -/// ```rust,no_run -/// # #![allow(invalid_value)] -/// use std::mem::{self, MaybeUninit}; -/// -/// let b: bool = unsafe { mem::uninitialized() }; // undefined behavior! ⚠️ -/// // The equivalent code with `MaybeUninit`: -/// let b: bool = unsafe { MaybeUninit::uninit().assume_init() }; // undefined behavior! ⚠️ -/// ``` -/// -/// Moreover, uninitialized memory is special in that it does not have a fixed value ("fixed" -/// meaning "it won't change without being written to"). Reading the same uninitialized byte -/// multiple times can give different results. This makes it undefined behavior to have -/// uninitialized data in a variable even if that variable has an integer type, which otherwise can -/// hold any *fixed* bit pattern: -/// -/// ```rust,no_run -/// # #![allow(invalid_value)] -/// use std::mem::{self, MaybeUninit}; -/// -/// let x: i32 = unsafe { mem::uninitialized() }; // undefined behavior! ⚠️ -/// // The equivalent code with `MaybeUninit`: -/// let x: i32 = unsafe { MaybeUninit::uninit().assume_init() }; // undefined behavior! ⚠️ -/// ``` -/// On top of that, remember that most types have additional invariants beyond merely -/// being considered initialized at the type level. For example, a `1`-initialized [`Vec`] -/// is considered initialized (under the current implementation; this does not constitute -/// a stable guarantee) because the only requirement the compiler knows about it -/// is that the data pointer must be non-null. Creating such a `Vec` does not cause -/// *immediate* undefined behavior, but will cause undefined behavior with most -/// safe operations (including dropping it). -/// -/// [`Vec`]: ../../std/vec/struct.Vec.html -/// -/// # Examples -/// -/// `MaybeUninit` serves to enable unsafe code to deal with uninitialized data. -/// It is a signal to the compiler indicating that the data here might *not* -/// be initialized: -/// -/// ```rust -/// use std::mem::MaybeUninit; -/// -/// // Create an explicitly uninitialized reference. The compiler knows that data inside -/// // a `MaybeUninit` may be invalid, and hence this is not UB: -/// let mut x = MaybeUninit::<&i32>::uninit(); -/// // Set it to a valid value. -/// x.write(&0); -/// // Extract the initialized data -- this is only allowed *after* properly -/// // initializing `x`! -/// let x = unsafe { x.assume_init() }; -/// ``` -/// -/// The compiler then knows to not make any incorrect assumptions or optimizations on this code. -/// -/// You can think of `MaybeUninit` as being a bit like `Option` but without -/// any of the run-time tracking and without any of the safety checks. -/// -/// ## out-pointers -/// -/// You can use `MaybeUninit` to implement "out-pointers": instead of returning data -/// from a function, pass it a pointer to some (uninitialized) memory to put the -/// result into. This can be useful when it is important for the caller to control -/// how the memory the result is stored in gets allocated, and you want to avoid -/// unnecessary moves. -/// -/// ``` -/// use std::mem::MaybeUninit; -/// -/// unsafe fn make_vec(out: *mut Vec) { -/// // `write` does not drop the old contents, which is important. -/// out.write(vec![1, 2, 3]); -/// } -/// -/// let mut v = MaybeUninit::uninit(); -/// unsafe { make_vec(v.as_mut_ptr()); } -/// // Now we know `v` is initialized! This also makes sure the vector gets -/// // properly dropped. -/// let v = unsafe { v.assume_init() }; -/// assert_eq!(&v, &[1, 2, 3]); -/// ``` -/// -/// ## Initializing an array element-by-element -/// -/// `MaybeUninit` can be used to initialize a large array element-by-element: -/// -/// ``` -/// use std::mem::{self, MaybeUninit}; -/// -/// let data = { -/// // Create an uninitialized array of `MaybeUninit`. The `assume_init` is -/// // safe because the type we are claiming to have initialized here is a -/// // bunch of `MaybeUninit`s, which do not require initialization. -/// let mut data: [MaybeUninit>; 1000] = unsafe { -/// MaybeUninit::uninit().assume_init() -/// }; -/// -/// // Dropping a `MaybeUninit` does nothing, so if there is a panic during this loop, -/// // we have a memory leak, but there is no memory safety issue. -/// for elem in &mut data[..] { -/// elem.write(vec![42]); -/// } -/// -/// // Everything is initialized. Transmute the array to the -/// // initialized type. -/// unsafe { mem::transmute::<_, [Vec; 1000]>(data) } -/// }; -/// -/// assert_eq!(&data[0], &[42]); -/// ``` -/// -/// You can also work with partially initialized arrays, which could -/// be found in low-level datastructures. -/// -/// ``` -/// use std::mem::MaybeUninit; -/// -/// // Create an uninitialized array of `MaybeUninit`. The `assume_init` is -/// // safe because the type we are claiming to have initialized here is a -/// // bunch of `MaybeUninit`s, which do not require initialization. -/// let mut data: [MaybeUninit; 1000] = unsafe { MaybeUninit::uninit().assume_init() }; -/// // Count the number of elements we have assigned. -/// let mut data_len: usize = 0; -/// -/// for elem in &mut data[0..500] { -/// elem.write(String::from("hello")); -/// data_len += 1; -/// } -/// -/// // For each item in the array, drop if we allocated it. -/// for elem in &mut data[0..data_len] { -/// unsafe { elem.assume_init_drop(); } -/// } -/// ``` -/// -/// ## Initializing a struct field-by-field -/// -/// You can use `MaybeUninit`, and the [`std::ptr::addr_of_mut`] macro, to initialize structs field by field: -/// -/// ```rust -/// use std::mem::MaybeUninit; -/// use std::ptr::addr_of_mut; -/// -/// #[derive(Debug, PartialEq)] -/// pub struct Foo { -/// name: String, -/// list: Vec, -/// } -/// -/// let foo = { -/// let mut uninit: MaybeUninit = MaybeUninit::uninit(); -/// let ptr = uninit.as_mut_ptr(); -/// -/// // Initializing the `name` field -/// // Using `write` instead of assignment via `=` to not call `drop` on the -/// // old, uninitialized value. -/// unsafe { addr_of_mut!((*ptr).name).write("Bob".to_string()); } -/// -/// // Initializing the `list` field -/// // If there is a panic here, then the `String` in the `name` field leaks. -/// unsafe { addr_of_mut!((*ptr).list).write(vec![0, 1, 2]); } -/// -/// // All the fields are initialized, so we call `assume_init` to get an initialized Foo. -/// unsafe { uninit.assume_init() } -/// }; -/// -/// assert_eq!( -/// foo, -/// Foo { -/// name: "Bob".to_string(), -/// list: vec![0, 1, 2] -/// } -/// ); -/// ``` -/// [`std::ptr::addr_of_mut`]: crate::ptr::addr_of_mut -/// [ub]: ../../reference/behavior-considered-undefined.html -/// -/// # Layout -/// -/// `MaybeUninit` is guaranteed to have the same size, alignment, and ABI as `T`: -/// -/// ```rust -/// use std::mem::{MaybeUninit, size_of, align_of}; -/// assert_eq!(size_of::>(), size_of::()); -/// assert_eq!(align_of::>(), align_of::()); -/// ``` -/// -/// However remember that a type *containing* a `MaybeUninit` is not necessarily the same -/// layout; Rust does not in general guarantee that the fields of a `Foo` have the same order as -/// a `Foo` even if `T` and `U` have the same size and alignment. Furthermore because any bit -/// value is valid for a `MaybeUninit` the compiler can't apply non-zero/niche-filling -/// optimizations, potentially resulting in a larger size: -/// -/// ```rust -/// # use std::mem::{MaybeUninit, size_of}; -/// assert_eq!(size_of::>(), 1); -/// assert_eq!(size_of::>>(), 2); -/// ``` -/// -/// If `T` is FFI-safe, then so is `MaybeUninit`. -/// -/// While `MaybeUninit` is `#[repr(transparent)]` (indicating it guarantees the same size, -/// alignment, and ABI as `T`), this does *not* change any of the previous caveats. `Option` and -/// `Option>` may still have different sizes, and types containing a field of type -/// `T` may be laid out (and sized) differently than if that field were `MaybeUninit`. -/// `MaybeUninit` is a union type, and `#[repr(transparent)]` on unions is unstable (see [the -/// tracking issue](https://github.com/rust-lang/rust/issues/60405)). Over time, the exact -/// guarantees of `#[repr(transparent)]` on unions may evolve, and `MaybeUninit` may or may not -/// remain `#[repr(transparent)]`. That said, `MaybeUninit` will *always* guarantee that it has -/// the same size, alignment, and ABI as `T`; it's just that the way `MaybeUninit` implements that -/// guarantee may evolve. -#[stable(feature = "maybe_uninit", since = "1.36.0")] -// Lang item so we can wrap other types in it. This is useful for coroutines. -#[lang = "maybe_uninit"] -#[derive(Copy)] -#[repr(transparent)] -pub union MaybeUninit { - uninit: (), - value: ManuallyDrop, -} - -#[stable(feature = "maybe_uninit", since = "1.36.0")] -impl Clone for MaybeUninit { - #[inline(always)] - fn clone(&self) -> Self { - // Not calling `T::clone()`, we cannot know if we are initialized enough for that. - *self - } -} - -#[stable(feature = "maybe_uninit_debug", since = "1.41.0")] -impl fmt::Debug for MaybeUninit { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.pad(type_name::()) - } -} - -impl MaybeUninit { - /// Creates a new `MaybeUninit` initialized with the given value. - /// It is safe to call [`assume_init`] on the return value of this function. - /// - /// Note that dropping a `MaybeUninit` will never call `T`'s drop code. - /// It is your responsibility to make sure `T` gets dropped if it got initialized. - /// - /// # Example - /// - /// ``` - /// use std::mem::MaybeUninit; - /// - /// let v: MaybeUninit> = MaybeUninit::new(vec![42]); - /// ``` - /// - /// [`assume_init`]: MaybeUninit::assume_init - #[stable(feature = "maybe_uninit", since = "1.36.0")] - #[rustc_const_stable(feature = "const_maybe_uninit", since = "1.36.0")] - #[must_use = "use `forget` to avoid running Drop code"] - #[inline(always)] - pub const fn new(val: T) -> MaybeUninit { - MaybeUninit { value: ManuallyDrop::new(val) } - } - - /// Creates a new `MaybeUninit` in an uninitialized state. - /// - /// Note that dropping a `MaybeUninit` will never call `T`'s drop code. - /// It is your responsibility to make sure `T` gets dropped if it got initialized. - /// - /// See the [type-level documentation][MaybeUninit] for some examples. - /// - /// # Example - /// - /// ``` - /// use std::mem::MaybeUninit; - /// - /// let v: MaybeUninit = MaybeUninit::uninit(); - /// ``` - #[stable(feature = "maybe_uninit", since = "1.36.0")] - #[rustc_const_stable(feature = "const_maybe_uninit", since = "1.36.0")] - #[must_use] - #[inline(always)] - #[rustc_diagnostic_item = "maybe_uninit_uninit"] - pub const fn uninit() -> MaybeUninit { - MaybeUninit { uninit: () } - } - - /// Create a new array of `MaybeUninit` items, in an uninitialized state. - /// - /// Note: in a future Rust version this method may become unnecessary - /// when Rust allows - /// [inline const expressions](https://github.com/rust-lang/rust/issues/76001). - /// The example below could then use `let mut buf = [const { MaybeUninit::::uninit() }; 32];`. - /// - /// # Examples - /// - /// ```no_run - /// #![feature(maybe_uninit_uninit_array, maybe_uninit_slice)] - /// - /// use std::mem::MaybeUninit; - /// - /// extern "C" { - /// fn read_into_buffer(ptr: *mut u8, max_len: usize) -> usize; - /// } - /// - /// /// Returns a (possibly smaller) slice of data that was actually read - /// fn read(buf: &mut [MaybeUninit]) -> &[u8] { - /// unsafe { - /// let len = read_into_buffer(buf.as_mut_ptr() as *mut u8, buf.len()); - /// MaybeUninit::slice_assume_init_ref(&buf[..len]) - /// } - /// } - /// - /// let mut buf: [MaybeUninit; 32] = MaybeUninit::uninit_array(); - /// let data = read(&mut buf); - /// ``` - #[unstable(feature = "maybe_uninit_uninit_array", issue = "96097")] - #[rustc_const_unstable(feature = "const_maybe_uninit_uninit_array", issue = "96097")] - #[must_use] - #[inline(always)] - pub const fn uninit_array() -> [Self; N] { - // SAFETY: An uninitialized `[MaybeUninit<_>; LEN]` is valid. - unsafe { MaybeUninit::<[MaybeUninit; N]>::uninit().assume_init() } - } - - /// Creates a new `MaybeUninit` in an uninitialized state, with the memory being - /// filled with `0` bytes. It depends on `T` whether that already makes for - /// proper initialization. For example, `MaybeUninit::zeroed()` is initialized, - /// but `MaybeUninit<&'static i32>::zeroed()` is not because references must not - /// be null. - /// - /// Note that dropping a `MaybeUninit` will never call `T`'s drop code. - /// It is your responsibility to make sure `T` gets dropped if it got initialized. - /// - /// # Example - /// - /// Correct usage of this function: initializing a struct with zero, where all - /// fields of the struct can hold the bit-pattern 0 as a valid value. - /// - /// ```rust - /// use std::mem::MaybeUninit; - /// - /// let x = MaybeUninit::<(u8, bool)>::zeroed(); - /// let x = unsafe { x.assume_init() }; - /// assert_eq!(x, (0, false)); - /// ``` - /// - /// This can be used in const contexts, such as to indicate the end of static arrays for - /// plugin registration. - /// - /// *Incorrect* usage of this function: calling `x.zeroed().assume_init()` - /// when `0` is not a valid bit-pattern for the type: - /// - /// ```rust,no_run - /// use std::mem::MaybeUninit; - /// - /// enum NotZero { One = 1, Two = 2 } - /// - /// let x = MaybeUninit::<(u8, NotZero)>::zeroed(); - /// let x = unsafe { x.assume_init() }; - /// // Inside a pair, we create a `NotZero` that does not have a valid discriminant. - /// // This is undefined behavior. ⚠️ - /// ``` - #[inline] - #[must_use] - #[rustc_diagnostic_item = "maybe_uninit_zeroed"] - #[stable(feature = "maybe_uninit", since = "1.36.0")] - // These are OK to allow since we do not leak &mut to user-visible API - #[rustc_allow_const_fn_unstable(const_mut_refs)] - #[rustc_allow_const_fn_unstable(const_ptr_write)] - #[rustc_allow_const_fn_unstable(const_maybe_uninit_as_mut_ptr)] - #[rustc_const_stable(feature = "const_maybe_uninit_zeroed", since = "1.75.0")] - pub const fn zeroed() -> MaybeUninit { - let mut u = MaybeUninit::::uninit(); - // SAFETY: `u.as_mut_ptr()` points to allocated memory. - unsafe { u.as_mut_ptr().write_bytes(0u8, 1) }; - u - } - - /// Sets the value of the `MaybeUninit`. - /// - /// This overwrites any previous value without dropping it, so be careful - /// not to use this twice unless you want to skip running the destructor. - /// For your convenience, this also returns a mutable reference to the - /// (now safely initialized) contents of `self`. - /// - /// As the content is stored inside a `MaybeUninit`, the destructor is not - /// run for the inner data if the MaybeUninit leaves scope without a call to - /// [`assume_init`], [`assume_init_drop`], or similar. Code that receives - /// the mutable reference returned by this function needs to keep this in - /// mind. The safety model of Rust regards leaks as safe, but they are - /// usually still undesirable. This being said, the mutable reference - /// behaves like any other mutable reference would, so assigning a new value - /// to it will drop the old content. - /// - /// [`assume_init`]: Self::assume_init - /// [`assume_init_drop`]: Self::assume_init_drop - /// - /// # Examples - /// - /// Correct usage of this method: - /// - /// ```rust - /// use std::mem::MaybeUninit; - /// - /// let mut x = MaybeUninit::>::uninit(); - /// - /// { - /// let hello = x.write((&b"Hello, world!").to_vec()); - /// // Setting hello does not leak prior allocations, but drops them - /// *hello = (&b"Hello").to_vec(); - /// hello[0] = 'h' as u8; - /// } - /// // x is initialized now: - /// let s = unsafe { x.assume_init() }; - /// assert_eq!(b"hello", s.as_slice()); - /// ``` - /// - /// This usage of the method causes a leak: - /// - /// ```rust - /// use std::mem::MaybeUninit; - /// - /// let mut x = MaybeUninit::::uninit(); - /// - /// x.write("Hello".to_string()); - /// // This leaks the contained string: - /// x.write("hello".to_string()); - /// // x is initialized now: - /// let s = unsafe { x.assume_init() }; - /// ``` - /// - /// This method can be used to avoid unsafe in some cases. The example below - /// shows a part of an implementation of a fixed sized arena that lends out - /// pinned references. - /// With `write`, we can avoid the need to write through a raw pointer: - /// - /// ```rust - /// use core::pin::Pin; - /// use core::mem::MaybeUninit; - /// - /// struct PinArena { - /// memory: Box<[MaybeUninit]>, - /// len: usize, - /// } - /// - /// impl PinArena { - /// pub fn capacity(&self) -> usize { - /// self.memory.len() - /// } - /// pub fn push(&mut self, val: T) -> Pin<&mut T> { - /// if self.len >= self.capacity() { - /// panic!("Attempted to push to a full pin arena!"); - /// } - /// let ref_ = self.memory[self.len].write(val); - /// self.len += 1; - /// unsafe { Pin::new_unchecked(ref_) } - /// } - /// } - /// ``` - #[stable(feature = "maybe_uninit_write", since = "1.55.0")] - #[rustc_const_unstable(feature = "const_maybe_uninit_write", issue = "63567")] - #[inline(always)] - pub const fn write(&mut self, val: T) -> &mut T { - *self = MaybeUninit::new(val); - // SAFETY: We just initialized this value. - unsafe { self.assume_init_mut() } - } - - /// Gets a pointer to the contained value. Reading from this pointer or turning it - /// into a reference is undefined behavior unless the `MaybeUninit` is initialized. - /// Writing to memory that this pointer (non-transitively) points to is undefined behavior - /// (except inside an `UnsafeCell`). - /// - /// # Examples - /// - /// Correct usage of this method: - /// - /// ```rust - /// use std::mem::MaybeUninit; - /// - /// let mut x = MaybeUninit::>::uninit(); - /// x.write(vec![0, 1, 2]); - /// // Create a reference into the `MaybeUninit`. This is okay because we initialized it. - /// let x_vec = unsafe { &*x.as_ptr() }; - /// assert_eq!(x_vec.len(), 3); - /// ``` - /// - /// *Incorrect* usage of this method: - /// - /// ```rust,no_run - /// use std::mem::MaybeUninit; - /// - /// let x = MaybeUninit::>::uninit(); - /// let x_vec = unsafe { &*x.as_ptr() }; - /// // We have created a reference to an uninitialized vector! This is undefined behavior. ⚠️ - /// ``` - /// - /// (Notice that the rules around references to uninitialized data are not finalized yet, but - /// until they are, it is advisable to avoid them.) - #[stable(feature = "maybe_uninit", since = "1.36.0")] - #[rustc_const_stable(feature = "const_maybe_uninit_as_ptr", since = "1.59.0")] - #[inline(always)] - pub const fn as_ptr(&self) -> *const T { - // `MaybeUninit` and `ManuallyDrop` are both `repr(transparent)` so we can cast the pointer. - self as *const _ as *const T - } - - /// Gets a mutable pointer to the contained value. Reading from this pointer or turning it - /// into a reference is undefined behavior unless the `MaybeUninit` is initialized. - /// - /// # Examples - /// - /// Correct usage of this method: - /// - /// ```rust - /// use std::mem::MaybeUninit; - /// - /// let mut x = MaybeUninit::>::uninit(); - /// x.write(vec![0, 1, 2]); - /// // Create a reference into the `MaybeUninit>`. - /// // This is okay because we initialized it. - /// let x_vec = unsafe { &mut *x.as_mut_ptr() }; - /// x_vec.push(3); - /// assert_eq!(x_vec.len(), 4); - /// ``` - /// - /// *Incorrect* usage of this method: - /// - /// ```rust,no_run - /// use std::mem::MaybeUninit; - /// - /// let mut x = MaybeUninit::>::uninit(); - /// let x_vec = unsafe { &mut *x.as_mut_ptr() }; - /// // We have created a reference to an uninitialized vector! This is undefined behavior. ⚠️ - /// ``` - /// - /// (Notice that the rules around references to uninitialized data are not finalized yet, but - /// until they are, it is advisable to avoid them.) - #[stable(feature = "maybe_uninit", since = "1.36.0")] - #[rustc_const_unstable(feature = "const_maybe_uninit_as_mut_ptr", issue = "75251")] - #[inline(always)] - pub const fn as_mut_ptr(&mut self) -> *mut T { - // `MaybeUninit` and `ManuallyDrop` are both `repr(transparent)` so we can cast the pointer. - self as *mut _ as *mut T - } - - /// Extracts the value from the `MaybeUninit` container. This is a great way - /// to ensure that the data will get dropped, because the resulting `T` is - /// subject to the usual drop handling. - /// - /// # Safety - /// - /// It is up to the caller to guarantee that the `MaybeUninit` really is in an initialized - /// state. Calling this when the content is not yet fully initialized causes immediate undefined - /// behavior. The [type-level documentation][inv] contains more information about - /// this initialization invariant. - /// - /// [inv]: #initialization-invariant - /// - /// On top of that, remember that most types have additional invariants beyond merely - /// being considered initialized at the type level. For example, a `1`-initialized [`Vec`] - /// is considered initialized (under the current implementation; this does not constitute - /// a stable guarantee) because the only requirement the compiler knows about it - /// is that the data pointer must be non-null. Creating such a `Vec` does not cause - /// *immediate* undefined behavior, but will cause undefined behavior with most - /// safe operations (including dropping it). - /// - /// [`Vec`]: ../../std/vec/struct.Vec.html - /// - /// # Examples - /// - /// Correct usage of this method: - /// - /// ```rust - /// use std::mem::MaybeUninit; - /// - /// let mut x = MaybeUninit::::uninit(); - /// x.write(true); - /// let x_init = unsafe { x.assume_init() }; - /// assert_eq!(x_init, true); - /// ``` - /// - /// *Incorrect* usage of this method: - /// - /// ```rust,no_run - /// use std::mem::MaybeUninit; - /// - /// let x = MaybeUninit::>::uninit(); - /// let x_init = unsafe { x.assume_init() }; - /// // `x` had not been initialized yet, so this last line caused undefined behavior. ⚠️ - /// ``` - #[stable(feature = "maybe_uninit", since = "1.36.0")] - #[rustc_const_stable(feature = "const_maybe_uninit_assume_init_by_value", since = "1.59.0")] - #[inline(always)] - #[rustc_diagnostic_item = "assume_init"] - #[track_caller] - pub const unsafe fn assume_init(self) -> T { - // SAFETY: the caller must guarantee that `self` is initialized. - // This also means that `self` must be a `value` variant. - unsafe { - intrinsics::assert_inhabited::(); - ManuallyDrop::into_inner(self.value) - } - } - - /// Reads the value from the `MaybeUninit` container. The resulting `T` is subject - /// to the usual drop handling. - /// - /// Whenever possible, it is preferable to use [`assume_init`] instead, which - /// prevents duplicating the content of the `MaybeUninit`. - /// - /// # Safety - /// - /// It is up to the caller to guarantee that the `MaybeUninit` really is in an initialized - /// state. Calling this when the content is not yet fully initialized causes undefined - /// behavior. The [type-level documentation][inv] contains more information about - /// this initialization invariant. - /// - /// Moreover, similar to the [`ptr::read`] function, this function creates a - /// bitwise copy of the contents, regardless whether the contained type - /// implements the [`Copy`] trait or not. When using multiple copies of the - /// data (by calling `assume_init_read` multiple times, or first calling - /// `assume_init_read` and then [`assume_init`]), it is your responsibility - /// to ensure that data may indeed be duplicated. - /// - /// [inv]: #initialization-invariant - /// [`assume_init`]: MaybeUninit::assume_init - /// - /// # Examples - /// - /// Correct usage of this method: - /// - /// ```rust - /// use std::mem::MaybeUninit; - /// - /// let mut x = MaybeUninit::::uninit(); - /// x.write(13); - /// let x1 = unsafe { x.assume_init_read() }; - /// // `u32` is `Copy`, so we may read multiple times. - /// let x2 = unsafe { x.assume_init_read() }; - /// assert_eq!(x1, x2); - /// - /// let mut x = MaybeUninit::>>::uninit(); - /// x.write(None); - /// let x1 = unsafe { x.assume_init_read() }; - /// // Duplicating a `None` value is okay, so we may read multiple times. - /// let x2 = unsafe { x.assume_init_read() }; - /// assert_eq!(x1, x2); - /// ``` - /// - /// *Incorrect* usage of this method: - /// - /// ```rust,no_run - /// use std::mem::MaybeUninit; - /// - /// let mut x = MaybeUninit::>>::uninit(); - /// x.write(Some(vec![0, 1, 2])); - /// let x1 = unsafe { x.assume_init_read() }; - /// let x2 = unsafe { x.assume_init_read() }; - /// // We now created two copies of the same vector, leading to a double-free ⚠️ when - /// // they both get dropped! - /// ``` - #[stable(feature = "maybe_uninit_extra", since = "1.60.0")] - #[rustc_const_stable(feature = "const_maybe_uninit_assume_init_read", since = "1.75.0")] - #[inline(always)] - #[track_caller] - pub const unsafe fn assume_init_read(&self) -> T { - // SAFETY: the caller must guarantee that `self` is initialized. - // Reading from `self.as_ptr()` is safe since `self` should be initialized. - unsafe { - intrinsics::assert_inhabited::(); - self.as_ptr().read() - } - } - - /// Drops the contained value in place. - /// - /// If you have ownership of the `MaybeUninit`, you can also use - /// [`assume_init`] as an alternative. - /// - /// # Safety - /// - /// It is up to the caller to guarantee that the `MaybeUninit` really is - /// in an initialized state. Calling this when the content is not yet fully - /// initialized causes undefined behavior. - /// - /// On top of that, all additional invariants of the type `T` must be - /// satisfied, as the `Drop` implementation of `T` (or its members) may - /// rely on this. For example, setting a [`Vec`] to an invalid but - /// non-null address makes it initialized (under the current implementation; - /// this does not constitute a stable guarantee), because the only - /// requirement the compiler knows about it is that the data pointer must be - /// non-null. Dropping such a `Vec` however will cause undefined - /// behaviour. - /// - /// [`assume_init`]: MaybeUninit::assume_init - /// [`Vec`]: ../../std/vec/struct.Vec.html - #[stable(feature = "maybe_uninit_extra", since = "1.60.0")] - pub unsafe fn assume_init_drop(&mut self) { - // SAFETY: the caller must guarantee that `self` is initialized and - // satisfies all invariants of `T`. - // Dropping the value in place is safe if that is the case. - unsafe { ptr::drop_in_place(self.as_mut_ptr()) } - } - - /// Gets a shared reference to the contained value. - /// - /// This can be useful when we want to access a `MaybeUninit` that has been - /// initialized but don't have ownership of the `MaybeUninit` (preventing the use - /// of `.assume_init()`). - /// - /// # Safety - /// - /// Calling this when the content is not yet fully initialized causes undefined - /// behavior: it is up to the caller to guarantee that the `MaybeUninit` really - /// is in an initialized state. - /// - /// # Examples - /// - /// ### Correct usage of this method: - /// - /// ```rust - /// use std::mem::MaybeUninit; - /// - /// let mut x = MaybeUninit::>::uninit(); - /// // Initialize `x`: - /// x.write(vec![1, 2, 3]); - /// // Now that our `MaybeUninit<_>` is known to be initialized, it is okay to - /// // create a shared reference to it: - /// let x: &Vec = unsafe { - /// // SAFETY: `x` has been initialized. - /// x.assume_init_ref() - /// }; - /// assert_eq!(x, &vec![1, 2, 3]); - /// ``` - /// - /// ### *Incorrect* usages of this method: - /// - /// ```rust,no_run - /// use std::mem::MaybeUninit; - /// - /// let x = MaybeUninit::>::uninit(); - /// let x_vec: &Vec = unsafe { x.assume_init_ref() }; - /// // We have created a reference to an uninitialized vector! This is undefined behavior. ⚠️ - /// ``` - /// - /// ```rust,no_run - /// use std::{cell::Cell, mem::MaybeUninit}; - /// - /// let b = MaybeUninit::>::uninit(); - /// // Initialize the `MaybeUninit` using `Cell::set`: - /// unsafe { - /// b.assume_init_ref().set(true); - /// // ^^^^^^^^^^^^^^^ - /// // Reference to an uninitialized `Cell`: UB! - /// } - /// ``` - #[stable(feature = "maybe_uninit_ref", since = "1.55.0")] - #[rustc_const_stable(feature = "const_maybe_uninit_assume_init_ref", since = "1.59.0")] - #[inline(always)] - pub const unsafe fn assume_init_ref(&self) -> &T { - // SAFETY: the caller must guarantee that `self` is initialized. - // This also means that `self` must be a `value` variant. - unsafe { - intrinsics::assert_inhabited::(); - &*self.as_ptr() - } - } - - /// Gets a mutable (unique) reference to the contained value. - /// - /// This can be useful when we want to access a `MaybeUninit` that has been - /// initialized but don't have ownership of the `MaybeUninit` (preventing the use - /// of `.assume_init()`). - /// - /// # Safety - /// - /// Calling this when the content is not yet fully initialized causes undefined - /// behavior: it is up to the caller to guarantee that the `MaybeUninit` really - /// is in an initialized state. For instance, `.assume_init_mut()` cannot be used to - /// initialize a `MaybeUninit`. - /// - /// # Examples - /// - /// ### Correct usage of this method: - /// - /// ```rust - /// # #![allow(unexpected_cfgs)] - /// use std::mem::MaybeUninit; - /// - /// # unsafe extern "C" fn initialize_buffer(buf: *mut [u8; 1024]) { *buf = [0; 1024] } - /// # #[cfg(FALSE)] - /// extern "C" { - /// /// Initializes *all* the bytes of the input buffer. - /// fn initialize_buffer(buf: *mut [u8; 1024]); - /// } - /// - /// let mut buf = MaybeUninit::<[u8; 1024]>::uninit(); - /// - /// // Initialize `buf`: - /// unsafe { initialize_buffer(buf.as_mut_ptr()); } - /// // Now we know that `buf` has been initialized, so we could `.assume_init()` it. - /// // However, using `.assume_init()` may trigger a `memcpy` of the 1024 bytes. - /// // To assert our buffer has been initialized without copying it, we upgrade - /// // the `&mut MaybeUninit<[u8; 1024]>` to a `&mut [u8; 1024]`: - /// let buf: &mut [u8; 1024] = unsafe { - /// // SAFETY: `buf` has been initialized. - /// buf.assume_init_mut() - /// }; - /// - /// // Now we can use `buf` as a normal slice: - /// buf.sort_unstable(); - /// assert!( - /// buf.windows(2).all(|pair| pair[0] <= pair[1]), - /// "buffer is sorted", - /// ); - /// ``` - /// - /// ### *Incorrect* usages of this method: - /// - /// You cannot use `.assume_init_mut()` to initialize a value: - /// - /// ```rust,no_run - /// use std::mem::MaybeUninit; - /// - /// let mut b = MaybeUninit::::uninit(); - /// unsafe { - /// *b.assume_init_mut() = true; - /// // We have created a (mutable) reference to an uninitialized `bool`! - /// // This is undefined behavior. ⚠️ - /// } - /// ``` - /// - /// For instance, you cannot [`Read`] into an uninitialized buffer: - /// - /// [`Read`]: ../../std/io/trait.Read.html - /// - /// ```rust,no_run - /// use std::{io, mem::MaybeUninit}; - /// - /// fn read_chunk (reader: &'_ mut dyn io::Read) -> io::Result<[u8; 64]> - /// { - /// let mut buffer = MaybeUninit::<[u8; 64]>::uninit(); - /// reader.read_exact(unsafe { buffer.assume_init_mut() })?; - /// // ^^^^^^^^^^^^^^^^^^^^^^^^ - /// // (mutable) reference to uninitialized memory! - /// // This is undefined behavior. - /// Ok(unsafe { buffer.assume_init() }) - /// } - /// ``` - /// - /// Nor can you use direct field access to do field-by-field gradual initialization: - /// - /// ```rust,no_run - /// use std::{mem::MaybeUninit, ptr}; - /// - /// struct Foo { - /// a: u32, - /// b: u8, - /// } - /// - /// let foo: Foo = unsafe { - /// let mut foo = MaybeUninit::::uninit(); - /// ptr::write(&mut foo.assume_init_mut().a as *mut u32, 1337); - /// // ^^^^^^^^^^^^^^^^^^^^^ - /// // (mutable) reference to uninitialized memory! - /// // This is undefined behavior. - /// ptr::write(&mut foo.assume_init_mut().b as *mut u8, 42); - /// // ^^^^^^^^^^^^^^^^^^^^^ - /// // (mutable) reference to uninitialized memory! - /// // This is undefined behavior. - /// foo.assume_init() - /// }; - /// ``` - #[stable(feature = "maybe_uninit_ref", since = "1.55.0")] - #[rustc_const_unstable(feature = "const_maybe_uninit_assume_init", issue = "none")] - #[inline(always)] - pub const unsafe fn assume_init_mut(&mut self) -> &mut T { - // SAFETY: the caller must guarantee that `self` is initialized. - // This also means that `self` must be a `value` variant. - unsafe { - intrinsics::assert_inhabited::(); - &mut *self.as_mut_ptr() - } - } - - /// Extracts the values from an array of `MaybeUninit` containers. - /// - /// # Safety - /// - /// It is up to the caller to guarantee that all elements of the array are - /// in an initialized state. - /// - /// # Examples - /// - /// ``` - /// #![feature(maybe_uninit_uninit_array)] - /// #![feature(maybe_uninit_array_assume_init)] - /// use std::mem::MaybeUninit; - /// - /// let mut array: [MaybeUninit; 3] = MaybeUninit::uninit_array(); - /// array[0].write(0); - /// array[1].write(1); - /// array[2].write(2); - /// - /// // SAFETY: Now safe as we initialised all elements - /// let array = unsafe { - /// MaybeUninit::array_assume_init(array) - /// }; - /// - /// assert_eq!(array, [0, 1, 2]); - /// ``` - #[unstable(feature = "maybe_uninit_array_assume_init", issue = "96097")] - #[rustc_const_unstable(feature = "const_maybe_uninit_array_assume_init", issue = "96097")] - #[inline(always)] - #[track_caller] - pub const unsafe fn array_assume_init(array: [Self; N]) -> [T; N] { - // SAFETY: - // * The caller guarantees that all elements of the array are initialized - // * `MaybeUninit` and T are guaranteed to have the same layout - // * `MaybeUninit` does not drop, so there are no double-frees - // And thus the conversion is safe - unsafe { - intrinsics::assert_inhabited::<[T; N]>(); - intrinsics::transmute_unchecked(array) - } - } - - /// Assuming all the elements are initialized, get a slice to them. - /// - /// # Safety - /// - /// It is up to the caller to guarantee that the `MaybeUninit` elements - /// really are in an initialized state. - /// Calling this when the content is not yet fully initialized causes undefined behavior. - /// - /// See [`assume_init_ref`] for more details and examples. - /// - /// [`assume_init_ref`]: MaybeUninit::assume_init_ref - #[unstable(feature = "maybe_uninit_slice", issue = "63569")] - #[rustc_const_unstable(feature = "maybe_uninit_slice", issue = "63569")] - #[inline(always)] - pub const unsafe fn slice_assume_init_ref(slice: &[Self]) -> &[T] { - // SAFETY: casting `slice` to a `*const [T]` is safe since the caller guarantees that - // `slice` is initialized, and `MaybeUninit` is guaranteed to have the same layout as `T`. - // The pointer obtained is valid since it refers to memory owned by `slice` which is a - // reference and thus guaranteed to be valid for reads. - unsafe { &*(slice as *const [Self] as *const [T]) } - } - - /// Assuming all the elements are initialized, get a mutable slice to them. - /// - /// # Safety - /// - /// It is up to the caller to guarantee that the `MaybeUninit` elements - /// really are in an initialized state. - /// Calling this when the content is not yet fully initialized causes undefined behavior. - /// - /// See [`assume_init_mut`] for more details and examples. - /// - /// [`assume_init_mut`]: MaybeUninit::assume_init_mut - #[unstable(feature = "maybe_uninit_slice", issue = "63569")] - #[rustc_const_unstable(feature = "const_maybe_uninit_assume_init", issue = "none")] - #[inline(always)] - pub const unsafe fn slice_assume_init_mut(slice: &mut [Self]) -> &mut [T] { - // SAFETY: similar to safety notes for `slice_get_ref`, but we have a - // mutable reference which is also guaranteed to be valid for writes. - unsafe { &mut *(slice as *mut [Self] as *mut [T]) } - } - - /// Gets a pointer to the first element of the array. - #[unstable(feature = "maybe_uninit_slice", issue = "63569")] - #[rustc_const_unstable(feature = "maybe_uninit_slice", issue = "63569")] - #[inline(always)] - pub const fn slice_as_ptr(this: &[MaybeUninit]) -> *const T { - this.as_ptr() as *const T - } - - /// Gets a mutable pointer to the first element of the array. - #[unstable(feature = "maybe_uninit_slice", issue = "63569")] - #[rustc_const_unstable(feature = "maybe_uninit_slice", issue = "63569")] - #[inline(always)] - pub const fn slice_as_mut_ptr(this: &mut [MaybeUninit]) -> *mut T { - this.as_mut_ptr() as *mut T - } - - /// Copies the elements from `src` to `this`, returning a mutable reference to the now initialized contents of `this`. - /// - /// If `T` does not implement `Copy`, use [`clone_from_slice`] - /// - /// This is similar to [`slice::copy_from_slice`]. - /// - /// # Panics - /// - /// This function will panic if the two slices have different lengths. - /// - /// # Examples - /// - /// ``` - /// #![feature(maybe_uninit_write_slice)] - /// use std::mem::MaybeUninit; - /// - /// let mut dst = [MaybeUninit::uninit(); 32]; - /// let src = [0; 32]; - /// - /// let init = MaybeUninit::copy_from_slice(&mut dst, &src); - /// - /// assert_eq!(init, src); - /// ``` - /// - /// ``` - /// #![feature(maybe_uninit_write_slice)] - /// use std::mem::MaybeUninit; - /// - /// let mut vec = Vec::with_capacity(32); - /// let src = [0; 16]; - /// - /// MaybeUninit::copy_from_slice(&mut vec.spare_capacity_mut()[..src.len()], &src); - /// - /// // SAFETY: we have just copied all the elements of len into the spare capacity - /// // the first src.len() elements of the vec are valid now. - /// unsafe { - /// vec.set_len(src.len()); - /// } - /// - /// assert_eq!(vec, src); - /// ``` - /// - /// [`clone_from_slice`]: MaybeUninit::clone_from_slice - #[unstable(feature = "maybe_uninit_write_slice", issue = "79995")] - pub fn copy_from_slice<'a>(this: &'a mut [MaybeUninit], src: &[T]) -> &'a mut [T] - where - T: Copy, - { - // SAFETY: &[T] and &[MaybeUninit] have the same layout - let uninit_src: &[MaybeUninit] = unsafe { super::transmute(src) }; - - this.copy_from_slice(uninit_src); - - // SAFETY: Valid elements have just been copied into `this` so it is initialized - unsafe { MaybeUninit::slice_assume_init_mut(this) } - } - - /// Clones the elements from `src` to `this`, returning a mutable reference to the now initialized contents of `this`. - /// Any already initialized elements will not be dropped. - /// - /// If `T` implements `Copy`, use [`copy_from_slice`] - /// - /// This is similar to [`slice::clone_from_slice`] but does not drop existing elements. - /// - /// # Panics - /// - /// This function will panic if the two slices have different lengths, or if the implementation of `Clone` panics. - /// - /// If there is a panic, the already cloned elements will be dropped. - /// - /// # Examples - /// - /// ``` - /// #![feature(maybe_uninit_write_slice)] - /// use std::mem::MaybeUninit; - /// - /// let mut dst = [MaybeUninit::uninit(), MaybeUninit::uninit(), MaybeUninit::uninit(), MaybeUninit::uninit(), MaybeUninit::uninit()]; - /// let src = ["wibbly".to_string(), "wobbly".to_string(), "timey".to_string(), "wimey".to_string(), "stuff".to_string()]; - /// - /// let init = MaybeUninit::clone_from_slice(&mut dst, &src); - /// - /// assert_eq!(init, src); - /// ``` - /// - /// ``` - /// #![feature(maybe_uninit_write_slice)] - /// use std::mem::MaybeUninit; - /// - /// let mut vec = Vec::with_capacity(32); - /// let src = ["rust", "is", "a", "pretty", "cool", "language"]; - /// - /// MaybeUninit::clone_from_slice(&mut vec.spare_capacity_mut()[..src.len()], &src); - /// - /// // SAFETY: we have just cloned all the elements of len into the spare capacity - /// // the first src.len() elements of the vec are valid now. - /// unsafe { - /// vec.set_len(src.len()); - /// } - /// - /// assert_eq!(vec, src); - /// ``` - /// - /// [`copy_from_slice`]: MaybeUninit::copy_from_slice - #[unstable(feature = "maybe_uninit_write_slice", issue = "79995")] - pub fn clone_from_slice<'a>(this: &'a mut [MaybeUninit], src: &[T]) -> &'a mut [T] - where - T: Clone, - { - // unlike copy_from_slice this does not call clone_from_slice on the slice - // this is because `MaybeUninit` does not implement Clone. - - assert_eq!(this.len(), src.len(), "destination and source slices have different lengths"); - // NOTE: We need to explicitly slice them to the same length - // for bounds checking to be elided, and the optimizer will - // generate memcpy for simple cases (for example T = u8). - let len = this.len(); - let src = &src[..len]; - - // guard is needed b/c panic might happen during a clone - let mut guard = Guard { slice: this, initialized: 0 }; - - for i in 0..len { - guard.slice[i].write(src[i].clone()); - guard.initialized += 1; - } - - super::forget(guard); - - // SAFETY: Valid elements have just been written into `this` so it is initialized - unsafe { MaybeUninit::slice_assume_init_mut(this) } - } - - /// Fills `this` with elements by cloning `value`, returning a mutable reference to the now - /// initialized contents of `this`. - /// Any previously initialized elements will not be dropped. - /// - /// This is similar to [`slice::fill`]. - /// - /// # Panics - /// - /// This function will panic if any call to `Clone` panics. - /// - /// If such a panic occurs, any elements previously initialized during this operation will be - /// dropped. - /// - /// # Examples - /// - /// Fill an uninit vec with 1. - /// ``` - /// #![feature(maybe_uninit_fill)] - /// use std::mem::MaybeUninit; - /// - /// let mut buf = vec![MaybeUninit::uninit(); 10]; - /// let initialized = MaybeUninit::fill(buf.as_mut_slice(), 1); - /// assert_eq!(initialized, &mut [1; 10]); - /// ``` - #[doc(alias = "memset")] - #[unstable(feature = "maybe_uninit_fill", issue = "117428")] - pub fn fill<'a>(this: &'a mut [MaybeUninit], value: T) -> &'a mut [T] - where - T: Clone, - { - SpecFill::spec_fill(this, value); - // SAFETY: Valid elements have just been filled into `this` so it is initialized - unsafe { MaybeUninit::slice_assume_init_mut(this) } - } - - /// Fills `this` with elements returned by calling a closure repeatedly. - /// - /// This method uses a closure to create new values. If you'd rather `Clone` a given value, use - /// [`MaybeUninit::fill`]. If you want to use the `Default` trait to generate values, you can - /// pass [`Default::default`] as the argument. - /// - /// # Panics - /// - /// This function will panic if any call to the provided closure panics. - /// - /// If such a panic occurs, any elements previously initialized during this operation will be - /// dropped. - /// - /// # Examples - /// - /// Fill an uninit vec with the default value. - /// ``` - /// #![feature(maybe_uninit_fill)] - /// use std::mem::MaybeUninit; - /// - /// let mut buf = vec![MaybeUninit::::uninit(); 10]; - /// let initialized = MaybeUninit::fill_with(buf.as_mut_slice(), Default::default); - /// assert_eq!(initialized, &mut [0; 10]); - /// ``` - #[unstable(feature = "maybe_uninit_fill", issue = "117428")] - pub fn fill_with<'a, F>(this: &'a mut [MaybeUninit], mut f: F) -> &'a mut [T] - where - F: FnMut() -> T, - { - let mut guard = Guard { slice: this, initialized: 0 }; - - for element in guard.slice.iter_mut() { - element.write(f()); - guard.initialized += 1; - } - - super::forget(guard); - - // SAFETY: Valid elements have just been written into `this` so it is initialized - unsafe { MaybeUninit::slice_assume_init_mut(this) } - } - - /// Fills `this` with elements yielded by an iterator until either all elements have been - /// initialized or the iterator is empty. - /// - /// Returns two slices. The first slice contains the initialized portion of the original slice. - /// The second slice is the still-uninitialized remainder of the original slice. - /// - /// # Panics - /// - /// This function panics if the iterator's `next` function panics. - /// - /// If such a panic occurs, any elements previously initialized during this operation will be - /// dropped. - /// - /// # Examples - /// - /// Fill an uninit vec with a cycling iterator. - /// ``` - /// #![feature(maybe_uninit_fill)] - /// use std::mem::MaybeUninit; - /// - /// let mut buf = vec![MaybeUninit::uninit(); 5]; - /// - /// let iter = [1, 2, 3].into_iter().cycle(); - /// let (initialized, remainder) = MaybeUninit::fill_from(&mut buf, iter); - /// - /// assert_eq!(initialized, &mut [1, 2, 3, 1, 2]); - /// assert_eq!(0, remainder.len()); - /// ``` - /// - /// Fill an uninit vec, but not completely. - /// ``` - /// #![feature(maybe_uninit_fill)] - /// use std::mem::MaybeUninit; - /// - /// let mut buf = vec![MaybeUninit::uninit(); 5]; - /// let iter = [1, 2]; - /// let (initialized, remainder) = MaybeUninit::fill_from(&mut buf, iter); - /// - /// assert_eq!(initialized, &mut [1, 2]); - /// assert_eq!(remainder.len(), 3); - /// ``` - #[unstable(feature = "maybe_uninit_fill", issue = "117428")] - pub fn fill_from<'a, I>( - this: &'a mut [MaybeUninit], - it: I, - ) -> (&'a mut [T], &'a mut [MaybeUninit]) - where - I: IntoIterator, - { - let iter = it.into_iter(); - let mut guard = Guard { slice: this, initialized: 0 }; - - for (element, val) in guard.slice.iter_mut().zip(iter) { - element.write(val); - guard.initialized += 1; - } - - let initialized_len = guard.initialized; - super::forget(guard); - - // SAFETY: guard.initialized <= this.len() - let (initted, remainder) = unsafe { this.split_at_mut_unchecked(initialized_len) }; - - // SAFETY: Valid elements have just been written into `init`, so that portion - // of `this` is initialized. - (unsafe { MaybeUninit::slice_assume_init_mut(initted) }, remainder) - } - - /// Returns the contents of this `MaybeUninit` as a slice of potentially uninitialized bytes. - /// - /// Note that even if the contents of a `MaybeUninit` have been initialized, the value may still - /// contain padding bytes which are left uninitialized. - /// - /// # Examples - /// - /// ``` - /// #![feature(maybe_uninit_as_bytes, maybe_uninit_slice)] - /// use std::mem::MaybeUninit; - /// - /// let val = 0x12345678_i32; - /// let uninit = MaybeUninit::new(val); - /// let uninit_bytes = uninit.as_bytes(); - /// let bytes = unsafe { MaybeUninit::slice_assume_init_ref(uninit_bytes) }; - /// assert_eq!(bytes, val.to_ne_bytes()); - /// ``` - #[unstable(feature = "maybe_uninit_as_bytes", issue = "93092")] - pub fn as_bytes(&self) -> &[MaybeUninit] { - // SAFETY: MaybeUninit is always valid, even for padding bytes - unsafe { - slice::from_raw_parts(self.as_ptr() as *const MaybeUninit, mem::size_of::()) - } - } - - /// Returns the contents of this `MaybeUninit` as a mutable slice of potentially uninitialized - /// bytes. - /// - /// Note that even if the contents of a `MaybeUninit` have been initialized, the value may still - /// contain padding bytes which are left uninitialized. - /// - /// # Examples - /// - /// ``` - /// #![feature(maybe_uninit_as_bytes)] - /// use std::mem::MaybeUninit; - /// - /// let val = 0x12345678_i32; - /// let mut uninit = MaybeUninit::new(val); - /// let uninit_bytes = uninit.as_bytes_mut(); - /// if cfg!(target_endian = "little") { - /// uninit_bytes[0].write(0xcd); - /// } else { - /// uninit_bytes[3].write(0xcd); - /// } - /// let val2 = unsafe { uninit.assume_init() }; - /// assert_eq!(val2, 0x123456cd); - /// ``` - #[unstable(feature = "maybe_uninit_as_bytes", issue = "93092")] - pub fn as_bytes_mut(&mut self) -> &mut [MaybeUninit] { - // SAFETY: MaybeUninit is always valid, even for padding bytes - unsafe { - slice::from_raw_parts_mut( - self.as_mut_ptr() as *mut MaybeUninit, - mem::size_of::(), - ) - } - } - - /// Returns the contents of this slice of `MaybeUninit` as a slice of potentially uninitialized - /// bytes. - /// - /// Note that even if the contents of a `MaybeUninit` have been initialized, the value may still - /// contain padding bytes which are left uninitialized. - /// - /// # Examples - /// - /// ``` - /// #![feature(maybe_uninit_as_bytes, maybe_uninit_write_slice, maybe_uninit_slice)] - /// use std::mem::MaybeUninit; - /// - /// let uninit = [MaybeUninit::new(0x1234u16), MaybeUninit::new(0x5678u16)]; - /// let uninit_bytes = MaybeUninit::slice_as_bytes(&uninit); - /// let bytes = unsafe { MaybeUninit::slice_assume_init_ref(&uninit_bytes) }; - /// let val1 = u16::from_ne_bytes(bytes[0..2].try_into().unwrap()); - /// let val2 = u16::from_ne_bytes(bytes[2..4].try_into().unwrap()); - /// assert_eq!(&[val1, val2], &[0x1234u16, 0x5678u16]); - /// ``` - #[unstable(feature = "maybe_uninit_as_bytes", issue = "93092")] - pub fn slice_as_bytes(this: &[MaybeUninit]) -> &[MaybeUninit] { - let bytes = mem::size_of_val(this); - // SAFETY: MaybeUninit is always valid, even for padding bytes - unsafe { slice::from_raw_parts(this.as_ptr() as *const MaybeUninit, bytes) } - } - - /// Returns the contents of this mutable slice of `MaybeUninit` as a mutable slice of - /// potentially uninitialized bytes. - /// - /// Note that even if the contents of a `MaybeUninit` have been initialized, the value may still - /// contain padding bytes which are left uninitialized. - /// - /// # Examples - /// - /// ``` - /// #![feature(maybe_uninit_as_bytes, maybe_uninit_write_slice, maybe_uninit_slice)] - /// use std::mem::MaybeUninit; - /// - /// let mut uninit = [MaybeUninit::::uninit(), MaybeUninit::::uninit()]; - /// let uninit_bytes = MaybeUninit::slice_as_bytes_mut(&mut uninit); - /// MaybeUninit::copy_from_slice(uninit_bytes, &[0x12, 0x34, 0x56, 0x78]); - /// let vals = unsafe { MaybeUninit::slice_assume_init_ref(&uninit) }; - /// if cfg!(target_endian = "little") { - /// assert_eq!(vals, &[0x3412u16, 0x7856u16]); - /// } else { - /// assert_eq!(vals, &[0x1234u16, 0x5678u16]); - /// } - /// ``` - #[unstable(feature = "maybe_uninit_as_bytes", issue = "93092")] - pub fn slice_as_bytes_mut(this: &mut [MaybeUninit]) -> &mut [MaybeUninit] { - let bytes = mem::size_of_val(this); - // SAFETY: MaybeUninit is always valid, even for padding bytes - unsafe { slice::from_raw_parts_mut(this.as_mut_ptr() as *mut MaybeUninit, bytes) } - } -} - -impl MaybeUninit<[T; N]> { - /// Transposes a `MaybeUninit<[T; N]>` into a `[MaybeUninit; N]`. - /// - /// # Examples - /// - /// ``` - /// #![feature(maybe_uninit_uninit_array_transpose)] - /// # use std::mem::MaybeUninit; - /// - /// let data: [MaybeUninit; 1000] = MaybeUninit::uninit().transpose(); - /// ``` - #[unstable(feature = "maybe_uninit_uninit_array_transpose", issue = "96097")] - #[inline] - pub const fn transpose(self) -> [MaybeUninit; N] { - // SAFETY: T and MaybeUninit have the same layout - unsafe { intrinsics::transmute_unchecked(self) } - } -} - -impl [MaybeUninit; N] { - /// Transposes a `[MaybeUninit; N]` into a `MaybeUninit<[T; N]>`. - /// - /// # Examples - /// - /// ``` - /// #![feature(maybe_uninit_uninit_array_transpose)] - /// # use std::mem::MaybeUninit; - /// - /// let data = [MaybeUninit::::uninit(); 1000]; - /// let data: MaybeUninit<[u8; 1000]> = data.transpose(); - /// ``` - #[unstable(feature = "maybe_uninit_uninit_array_transpose", issue = "96097")] - #[inline] - pub const fn transpose(self) -> MaybeUninit<[T; N]> { - // SAFETY: T and MaybeUninit have the same layout - unsafe { intrinsics::transmute_unchecked(self) } - } -} - -struct Guard<'a, T> { - slice: &'a mut [MaybeUninit], - initialized: usize, -} - -impl<'a, T> Drop for Guard<'a, T> { - fn drop(&mut self) { - let initialized_part = &mut self.slice[..self.initialized]; - // SAFETY: this raw sub-slice will contain only initialized objects. - unsafe { - crate::ptr::drop_in_place(MaybeUninit::slice_assume_init_mut(initialized_part)); - } - } -} - -trait SpecFill { - fn spec_fill(&mut self, value: T); -} - -impl SpecFill for [MaybeUninit] { - default fn spec_fill(&mut self, value: T) { - let mut guard = Guard { slice: self, initialized: 0 }; - - if let Some((last, elems)) = guard.slice.split_last_mut() { - for el in elems { - el.write(value.clone()); - guard.initialized += 1; - } - - last.write(value); - } - super::forget(guard); - } -} - -impl SpecFill for [MaybeUninit] { - fn spec_fill(&mut self, value: T) { - self.fill(MaybeUninit::new(value)); - } -} diff --git a/library/core/src/mem/mod.rs b/library/core/src/mem/mod.rs deleted file mode 100644 index cf3f819cd5c15..0000000000000 --- a/library/core/src/mem/mod.rs +++ /dev/null @@ -1,1387 +0,0 @@ -//! Basic functions for dealing with memory. -//! -//! This module contains functions for querying the size and alignment of -//! types, initializing and manipulating memory. - -#![stable(feature = "rust1", since = "1.0.0")] - -use crate::clone; -use crate::cmp; -use crate::fmt; -use crate::hash; -use crate::intrinsics; -use crate::marker::DiscriminantKind; -use crate::ptr; - -#[cfg(kani)] -use crate::kani; - -mod manually_drop; -#[stable(feature = "manually_drop", since = "1.20.0")] -pub use manually_drop::ManuallyDrop; - -mod maybe_uninit; -#[stable(feature = "maybe_uninit", since = "1.36.0")] -pub use maybe_uninit::MaybeUninit; - -mod transmutability; -#[unstable(feature = "transmutability", issue = "99571")] -pub use transmutability::{Assume, BikeshedIntrinsicFrom}; - -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(inline)] -pub use crate::intrinsics::transmute; - -/// Takes ownership and "forgets" about the value **without running its destructor**. -/// -/// Any resources the value manages, such as heap memory or a file handle, will linger -/// forever in an unreachable state. However, it does not guarantee that pointers -/// to this memory will remain valid. -/// -/// * If you want to leak memory, see [`Box::leak`]. -/// * If you want to obtain a raw pointer to the memory, see [`Box::into_raw`]. -/// * If you want to dispose of a value properly, running its destructor, see -/// [`mem::drop`]. -/// -/// # Safety -/// -/// `forget` is not marked as `unsafe`, because Rust's safety guarantees -/// do not include a guarantee that destructors will always run. For example, -/// a program can create a reference cycle using [`Rc`][rc], or call -/// [`process::exit`][exit] to exit without running destructors. Thus, allowing -/// `mem::forget` from safe code does not fundamentally change Rust's safety -/// guarantees. -/// -/// That said, leaking resources such as memory or I/O objects is usually undesirable. -/// The need comes up in some specialized use cases for FFI or unsafe code, but even -/// then, [`ManuallyDrop`] is typically preferred. -/// -/// Because forgetting a value is allowed, any `unsafe` code you write must -/// allow for this possibility. You cannot return a value and expect that the -/// caller will necessarily run the value's destructor. -/// -/// [rc]: ../../std/rc/struct.Rc.html -/// [exit]: ../../std/process/fn.exit.html -/// -/// # Examples -/// -/// The canonical safe use of `mem::forget` is to circumvent a value's destructor -/// implemented by the `Drop` trait. For example, this will leak a `File`, i.e. reclaim -/// the space taken by the variable but never close the underlying system resource: -/// -/// ```no_run -/// use std::mem; -/// use std::fs::File; -/// -/// let file = File::open("foo.txt").unwrap(); -/// mem::forget(file); -/// ``` -/// -/// This is useful when the ownership of the underlying resource was previously -/// transferred to code outside of Rust, for example by transmitting the raw -/// file descriptor to C code. -/// -/// # Relationship with `ManuallyDrop` -/// -/// While `mem::forget` can also be used to transfer *memory* ownership, doing so is error-prone. -/// [`ManuallyDrop`] should be used instead. Consider, for example, this code: -/// -/// ``` -/// use std::mem; -/// -/// let mut v = vec![65, 122]; -/// // Build a `String` using the contents of `v` -/// let s = unsafe { String::from_raw_parts(v.as_mut_ptr(), v.len(), v.capacity()) }; -/// // leak `v` because its memory is now managed by `s` -/// mem::forget(v); // ERROR - v is invalid and must not be passed to a function -/// assert_eq!(s, "Az"); -/// // `s` is implicitly dropped and its memory deallocated. -/// ``` -/// -/// There are two issues with the above example: -/// -/// * If more code were added between the construction of `String` and the invocation of -/// `mem::forget()`, a panic within it would cause a double free because the same memory -/// is handled by both `v` and `s`. -/// * After calling `v.as_mut_ptr()` and transmitting the ownership of the data to `s`, -/// the `v` value is invalid. Even when a value is just moved to `mem::forget` (which won't -/// inspect it), some types have strict requirements on their values that -/// make them invalid when dangling or no longer owned. Using invalid values in any -/// way, including passing them to or returning them from functions, constitutes -/// undefined behavior and may break the assumptions made by the compiler. -/// -/// Switching to `ManuallyDrop` avoids both issues: -/// -/// ``` -/// use std::mem::ManuallyDrop; -/// -/// let v = vec![65, 122]; -/// // Before we disassemble `v` into its raw parts, make sure it -/// // does not get dropped! -/// let mut v = ManuallyDrop::new(v); -/// // Now disassemble `v`. These operations cannot panic, so there cannot be a leak. -/// let (ptr, len, cap) = (v.as_mut_ptr(), v.len(), v.capacity()); -/// // Finally, build a `String`. -/// let s = unsafe { String::from_raw_parts(ptr, len, cap) }; -/// assert_eq!(s, "Az"); -/// // `s` is implicitly dropped and its memory deallocated. -/// ``` -/// -/// `ManuallyDrop` robustly prevents double-free because we disable `v`'s destructor -/// before doing anything else. `mem::forget()` doesn't allow this because it consumes its -/// argument, forcing us to call it only after extracting anything we need from `v`. Even -/// if a panic were introduced between construction of `ManuallyDrop` and building the -/// string (which cannot happen in the code as shown), it would result in a leak and not a -/// double free. In other words, `ManuallyDrop` errs on the side of leaking instead of -/// erring on the side of (double-)dropping. -/// -/// Also, `ManuallyDrop` prevents us from having to "touch" `v` after transferring the -/// ownership to `s` — the final step of interacting with `v` to dispose of it without -/// running its destructor is entirely avoided. -/// -/// [`Box`]: ../../std/boxed/struct.Box.html -/// [`Box::leak`]: ../../std/boxed/struct.Box.html#method.leak -/// [`Box::into_raw`]: ../../std/boxed/struct.Box.html#method.into_raw -/// [`mem::drop`]: drop -/// [ub]: ../../reference/behavior-considered-undefined.html -#[inline] -#[rustc_const_stable(feature = "const_forget", since = "1.46.0")] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "mem_forget")] -pub const fn forget(t: T) { - let _ = ManuallyDrop::new(t); -} - -/// Like [`forget`], but also accepts unsized values. -/// -/// This function is just a shim intended to be removed when the `unsized_locals` feature gets -/// stabilized. -#[inline] -#[unstable(feature = "forget_unsized", issue = "none")] -pub fn forget_unsized(t: T) { - intrinsics::forget(t) -} - -/// Returns the size of a type in bytes. -/// -/// More specifically, this is the offset in bytes between successive elements -/// in an array with that item type including alignment padding. Thus, for any -/// type `T` and length `n`, `[T; n]` has a size of `n * size_of::()`. -/// -/// In general, the size of a type is not stable across compilations, but -/// specific types such as primitives are. -/// -/// The following table gives the size for primitives. -/// -/// Type | `size_of::()` -/// ---- | --------------- -/// () | 0 -/// bool | 1 -/// u8 | 1 -/// u16 | 2 -/// u32 | 4 -/// u64 | 8 -/// u128 | 16 -/// i8 | 1 -/// i16 | 2 -/// i32 | 4 -/// i64 | 8 -/// i128 | 16 -/// f32 | 4 -/// f64 | 8 -/// char | 4 -/// -/// Furthermore, `usize` and `isize` have the same size. -/// -/// The types [`*const T`], `&T`, [`Box`], [`Option<&T>`], and `Option>` all have -/// the same size. If `T` is `Sized`, all of those types have the same size as `usize`. -/// -/// The mutability of a pointer does not change its size. As such, `&T` and `&mut T` -/// have the same size. Likewise for `*const T` and `*mut T`. -/// -/// # Size of `#[repr(C)]` items -/// -/// The `C` representation for items has a defined layout. With this layout, -/// the size of items is also stable as long as all fields have a stable size. -/// -/// ## Size of Structs -/// -/// For `struct`s, the size is determined by the following algorithm. -/// -/// For each field in the struct ordered by declaration order: -/// -/// 1. Add the size of the field. -/// 2. Round up the current size to the nearest multiple of the next field's [alignment]. -/// -/// Finally, round the size of the struct to the nearest multiple of its [alignment]. -/// The alignment of the struct is usually the largest alignment of all its -/// fields; this can be changed with the use of `repr(align(N))`. -/// -/// Unlike `C`, zero sized structs are not rounded up to one byte in size. -/// -/// ## Size of Enums -/// -/// Enums that carry no data other than the discriminant have the same size as C enums -/// on the platform they are compiled for. -/// -/// ## Size of Unions -/// -/// The size of a union is the size of its largest field. -/// -/// Unlike `C`, zero sized unions are not rounded up to one byte in size. -/// -/// # Examples -/// -/// ``` -/// use std::mem; -/// -/// // Some primitives -/// assert_eq!(4, mem::size_of::()); -/// assert_eq!(8, mem::size_of::()); -/// assert_eq!(0, mem::size_of::<()>()); -/// -/// // Some arrays -/// assert_eq!(8, mem::size_of::<[i32; 2]>()); -/// assert_eq!(12, mem::size_of::<[i32; 3]>()); -/// assert_eq!(0, mem::size_of::<[i32; 0]>()); -/// -/// -/// // Pointer size equality -/// assert_eq!(mem::size_of::<&i32>(), mem::size_of::<*const i32>()); -/// assert_eq!(mem::size_of::<&i32>(), mem::size_of::>()); -/// assert_eq!(mem::size_of::<&i32>(), mem::size_of::>()); -/// assert_eq!(mem::size_of::>(), mem::size_of::>>()); -/// ``` -/// -/// Using `#[repr(C)]`. -/// -/// ``` -/// use std::mem; -/// -/// #[repr(C)] -/// struct FieldStruct { -/// first: u8, -/// second: u16, -/// third: u8 -/// } -/// -/// // The size of the first field is 1, so add 1 to the size. Size is 1. -/// // The alignment of the second field is 2, so add 1 to the size for padding. Size is 2. -/// // The size of the second field is 2, so add 2 to the size. Size is 4. -/// // The alignment of the third field is 1, so add 0 to the size for padding. Size is 4. -/// // The size of the third field is 1, so add 1 to the size. Size is 5. -/// // Finally, the alignment of the struct is 2 (because the largest alignment amongst its -/// // fields is 2), so add 1 to the size for padding. Size is 6. -/// assert_eq!(6, mem::size_of::()); -/// -/// #[repr(C)] -/// struct TupleStruct(u8, u16, u8); -/// -/// // Tuple structs follow the same rules. -/// assert_eq!(6, mem::size_of::()); -/// -/// // Note that reordering the fields can lower the size. We can remove both padding bytes -/// // by putting `third` before `second`. -/// #[repr(C)] -/// struct FieldStructOptimized { -/// first: u8, -/// third: u8, -/// second: u16 -/// } -/// -/// assert_eq!(4, mem::size_of::()); -/// -/// // Union size is the size of the largest field. -/// #[repr(C)] -/// union ExampleUnion { -/// smaller: u8, -/// larger: u16 -/// } -/// -/// assert_eq!(2, mem::size_of::()); -/// ``` -/// -/// [alignment]: align_of -/// [`*const T`]: primitive@pointer -/// [`Box`]: ../../std/boxed/struct.Box.html -/// [`Option<&T>`]: crate::option::Option -/// -#[inline(always)] -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_promotable] -#[rustc_const_stable(feature = "const_mem_size_of", since = "1.24.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "mem_size_of")] -pub const fn size_of() -> usize { - intrinsics::size_of::() -} - -/// Returns the size of the pointed-to value in bytes. -/// -/// This is usually the same as [`size_of::()`]. However, when `T` *has* no -/// statically-known size, e.g., a slice [`[T]`][slice] or a [trait object], -/// then `size_of_val` can be used to get the dynamically-known size. -/// -/// [trait object]: ../../book/ch17-02-trait-objects.html -/// -/// # Examples -/// -/// ``` -/// use std::mem; -/// -/// assert_eq!(4, mem::size_of_val(&5i32)); -/// -/// let x: [u8; 13] = [0; 13]; -/// let y: &[u8] = &x; -/// assert_eq!(13, mem::size_of_val(y)); -/// ``` -/// -/// [`size_of::()`]: size_of -#[inline] -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_const_unstable(feature = "const_size_of_val", issue = "46571")] -#[cfg_attr(not(test), rustc_diagnostic_item = "mem_size_of_val")] -pub const fn size_of_val(val: &T) -> usize { - // SAFETY: `val` is a reference, so it's a valid raw pointer - unsafe { intrinsics::size_of_val(val) } -} - -/// Returns the size of the pointed-to value in bytes. -/// -/// This is usually the same as [`size_of::()`]. However, when `T` *has* no -/// statically-known size, e.g., a slice [`[T]`][slice] or a [trait object], -/// then `size_of_val_raw` can be used to get the dynamically-known size. -/// -/// # Safety -/// -/// This function is only safe to call if the following conditions hold: -/// -/// - If `T` is `Sized`, this function is always safe to call. -/// - If the unsized tail of `T` is: -/// - a [slice], then the length of the slice tail must be an initialized -/// integer, and the size of the *entire value* -/// (dynamic tail length + statically sized prefix) must fit in `isize`. -/// - a [trait object], then the vtable part of the pointer must point -/// to a valid vtable acquired by an unsizing coercion, and the size -/// of the *entire value* (dynamic tail length + statically sized prefix) -/// must fit in `isize`. -/// - an (unstable) [extern type], then this function is always safe to -/// call, but may panic or otherwise return the wrong value, as the -/// extern type's layout is not known. This is the same behavior as -/// [`size_of_val`] on a reference to a type with an extern type tail. -/// - otherwise, it is conservatively not allowed to call this function. -/// -/// [`size_of::()`]: size_of -/// [trait object]: ../../book/ch17-02-trait-objects.html -/// [extern type]: ../../unstable-book/language-features/extern-types.html -/// -/// # Examples -/// -/// ``` -/// #![feature(layout_for_ptr)] -/// use std::mem; -/// -/// assert_eq!(4, mem::size_of_val(&5i32)); -/// -/// let x: [u8; 13] = [0; 13]; -/// let y: &[u8] = &x; -/// assert_eq!(13, unsafe { mem::size_of_val_raw(y) }); -/// ``` -#[inline] -#[must_use] -#[unstable(feature = "layout_for_ptr", issue = "69835")] -#[rustc_const_unstable(feature = "const_size_of_val_raw", issue = "46571")] -pub const unsafe fn size_of_val_raw(val: *const T) -> usize { - // SAFETY: the caller must provide a valid raw pointer - unsafe { intrinsics::size_of_val(val) } -} - -/// Returns the [ABI]-required minimum alignment of a type in bytes. -/// -/// Every reference to a value of the type `T` must be a multiple of this number. -/// -/// This is the alignment used for struct fields. It may be smaller than the preferred alignment. -/// -/// [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface -/// -/// # Examples -/// -/// ``` -/// # #![allow(deprecated)] -/// use std::mem; -/// -/// assert_eq!(4, mem::min_align_of::()); -/// ``` -#[inline] -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(note = "use `align_of` instead", since = "1.2.0", suggestion = "align_of")] -pub fn min_align_of() -> usize { - intrinsics::min_align_of::() -} - -/// Returns the [ABI]-required minimum alignment of the type of the value that `val` points to in -/// bytes. -/// -/// Every reference to a value of the type `T` must be a multiple of this number. -/// -/// [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface -/// -/// # Examples -/// -/// ``` -/// # #![allow(deprecated)] -/// use std::mem; -/// -/// assert_eq!(4, mem::min_align_of_val(&5i32)); -/// ``` -#[inline] -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(note = "use `align_of_val` instead", since = "1.2.0", suggestion = "align_of_val")] -pub fn min_align_of_val(val: &T) -> usize { - // SAFETY: val is a reference, so it's a valid raw pointer - unsafe { intrinsics::min_align_of_val(val) } -} - -/// Returns the [ABI]-required minimum alignment of a type in bytes. -/// -/// Every reference to a value of the type `T` must be a multiple of this number. -/// -/// This is the alignment used for struct fields. It may be smaller than the preferred alignment. -/// -/// [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface -/// -/// # Examples -/// -/// ``` -/// use std::mem; -/// -/// assert_eq!(4, mem::align_of::()); -/// ``` -#[inline(always)] -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_promotable] -#[rustc_const_stable(feature = "const_align_of", since = "1.24.0")] -pub const fn align_of() -> usize { - intrinsics::min_align_of::() -} - -/// Returns the [ABI]-required minimum alignment of the type of the value that `val` points to in -/// bytes. -/// -/// Every reference to a value of the type `T` must be a multiple of this number. -/// -/// [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface -/// -/// # Examples -/// -/// ``` -/// use std::mem; -/// -/// assert_eq!(4, mem::align_of_val(&5i32)); -/// ``` -#[inline] -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_const_unstable(feature = "const_align_of_val", issue = "46571")] -#[allow(deprecated)] -pub const fn align_of_val(val: &T) -> usize { - // SAFETY: val is a reference, so it's a valid raw pointer - unsafe { intrinsics::min_align_of_val(val) } -} - -/// Returns the [ABI]-required minimum alignment of the type of the value that `val` points to in -/// bytes. -/// -/// Every reference to a value of the type `T` must be a multiple of this number. -/// -/// [ABI]: https://en.wikipedia.org/wiki/Application_binary_interface -/// -/// # Safety -/// -/// This function is only safe to call if the following conditions hold: -/// -/// - If `T` is `Sized`, this function is always safe to call. -/// - If the unsized tail of `T` is: -/// - a [slice], then the length of the slice tail must be an initialized -/// integer, and the size of the *entire value* -/// (dynamic tail length + statically sized prefix) must fit in `isize`. -/// - a [trait object], then the vtable part of the pointer must point -/// to a valid vtable acquired by an unsizing coercion, and the size -/// of the *entire value* (dynamic tail length + statically sized prefix) -/// must fit in `isize`. -/// - an (unstable) [extern type], then this function is always safe to -/// call, but may panic or otherwise return the wrong value, as the -/// extern type's layout is not known. This is the same behavior as -/// [`align_of_val`] on a reference to a type with an extern type tail. -/// - otherwise, it is conservatively not allowed to call this function. -/// -/// [trait object]: ../../book/ch17-02-trait-objects.html -/// [extern type]: ../../unstable-book/language-features/extern-types.html -/// -/// # Examples -/// -/// ``` -/// #![feature(layout_for_ptr)] -/// use std::mem; -/// -/// assert_eq!(4, unsafe { mem::align_of_val_raw(&5i32) }); -/// ``` -#[inline] -#[must_use] -#[unstable(feature = "layout_for_ptr", issue = "69835")] -#[rustc_const_unstable(feature = "const_align_of_val_raw", issue = "46571")] -pub const unsafe fn align_of_val_raw(val: *const T) -> usize { - // SAFETY: the caller must provide a valid raw pointer - unsafe { intrinsics::min_align_of_val(val) } -} - -/// Returns `true` if dropping values of type `T` matters. -/// -/// This is purely an optimization hint, and may be implemented conservatively: -/// it may return `true` for types that don't actually need to be dropped. -/// As such always returning `true` would be a valid implementation of -/// this function. However if this function actually returns `false`, then you -/// can be certain dropping `T` has no side effect. -/// -/// Low level implementations of things like collections, which need to manually -/// drop their data, should use this function to avoid unnecessarily -/// trying to drop all their contents when they are destroyed. This might not -/// make a difference in release builds (where a loop that has no side-effects -/// is easily detected and eliminated), but is often a big win for debug builds. -/// -/// Note that [`drop_in_place`] already performs this check, so if your workload -/// can be reduced to some small number of [`drop_in_place`] calls, using this is -/// unnecessary. In particular note that you can [`drop_in_place`] a slice, and that -/// will do a single needs_drop check for all the values. -/// -/// Types like Vec therefore just `drop_in_place(&mut self[..])` without using -/// `needs_drop` explicitly. Types like [`HashMap`], on the other hand, have to drop -/// values one at a time and should use this API. -/// -/// [`drop_in_place`]: crate::ptr::drop_in_place -/// [`HashMap`]: ../../std/collections/struct.HashMap.html -/// -/// # Examples -/// -/// Here's an example of how a collection might make use of `needs_drop`: -/// -/// ``` -/// use std::{mem, ptr}; -/// -/// pub struct MyCollection { -/// # data: [T; 1], -/// /* ... */ -/// } -/// # impl MyCollection { -/// # fn iter_mut(&mut self) -> &mut [T] { &mut self.data } -/// # fn free_buffer(&mut self) {} -/// # } -/// -/// impl Drop for MyCollection { -/// fn drop(&mut self) { -/// unsafe { -/// // drop the data -/// if mem::needs_drop::() { -/// for x in self.iter_mut() { -/// ptr::drop_in_place(x); -/// } -/// } -/// self.free_buffer(); -/// } -/// } -/// } -/// ``` -#[inline] -#[must_use] -#[stable(feature = "needs_drop", since = "1.21.0")] -#[rustc_const_stable(feature = "const_mem_needs_drop", since = "1.36.0")] -#[rustc_diagnostic_item = "needs_drop"] -pub const fn needs_drop() -> bool { - intrinsics::needs_drop::() -} - -/// Returns the value of type `T` represented by the all-zero byte-pattern. -/// -/// This means that, for example, the padding byte in `(u8, u16)` is not -/// necessarily zeroed. -/// -/// There is no guarantee that an all-zero byte-pattern represents a valid value -/// of some type `T`. For example, the all-zero byte-pattern is not a valid value -/// for reference types (`&T`, `&mut T`) and functions pointers. Using `zeroed` -/// on such types causes immediate [undefined behavior][ub] because [the Rust -/// compiler assumes][inv] that there always is a valid value in a variable it -/// considers initialized. -/// -/// This has the same effect as [`MaybeUninit::zeroed().assume_init()`][zeroed]. -/// It is useful for FFI sometimes, but should generally be avoided. -/// -/// [zeroed]: MaybeUninit::zeroed -/// [ub]: ../../reference/behavior-considered-undefined.html -/// [inv]: MaybeUninit#initialization-invariant -/// -/// # Examples -/// -/// Correct usage of this function: initializing an integer with zero. -/// -/// ``` -/// use std::mem; -/// -/// let x: i32 = unsafe { mem::zeroed() }; -/// assert_eq!(0, x); -/// ``` -/// -/// *Incorrect* usage of this function: initializing a reference with zero. -/// -/// ```rust,no_run -/// # #![allow(invalid_value)] -/// use std::mem; -/// -/// let _x: &i32 = unsafe { mem::zeroed() }; // Undefined behavior! -/// let _y: fn() = unsafe { mem::zeroed() }; // And again! -/// ``` -#[inline(always)] -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated_in_future)] -#[allow(deprecated)] -#[rustc_diagnostic_item = "mem_zeroed"] -#[track_caller] -#[rustc_const_stable(feature = "const_mem_zeroed", since = "1.75.0")] -pub const unsafe fn zeroed() -> T { - // SAFETY: the caller must guarantee that an all-zero value is valid for `T`. - unsafe { - intrinsics::assert_zero_valid::(); - MaybeUninit::zeroed().assume_init() - } -} - -/// Bypasses Rust's normal memory-initialization checks by pretending to -/// produce a value of type `T`, while doing nothing at all. -/// -/// **This function is deprecated.** Use [`MaybeUninit`] instead. -/// It also might be slower than using `MaybeUninit` due to mitigations that were put in place to -/// limit the potential harm caused by incorrect use of this function in legacy code. -/// -/// The reason for deprecation is that the function basically cannot be used -/// correctly: it has the same effect as [`MaybeUninit::uninit().assume_init()`][uninit]. -/// As the [`assume_init` documentation][assume_init] explains, -/// [the Rust compiler assumes][inv] that values are properly initialized. -/// -/// Truly uninitialized memory like what gets returned here -/// is special in that the compiler knows that it does not have a fixed value. -/// This makes it undefined behavior to have uninitialized data in a variable even -/// if that variable has an integer type. -/// -/// Therefore, it is immediate undefined behavior to call this function on nearly all types, -/// including integer types and arrays of integer types, and even if the result is unused. -/// -/// [uninit]: MaybeUninit::uninit -/// [assume_init]: MaybeUninit::assume_init -/// [inv]: MaybeUninit#initialization-invariant -#[inline(always)] -#[must_use] -#[deprecated(since = "1.39.0", note = "use `mem::MaybeUninit` instead")] -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated_in_future)] -#[allow(deprecated)] -#[rustc_diagnostic_item = "mem_uninitialized"] -#[track_caller] -pub unsafe fn uninitialized() -> T { - // SAFETY: the caller must guarantee that an uninitialized value is valid for `T`. - unsafe { - intrinsics::assert_mem_uninitialized_valid::(); - let mut val = MaybeUninit::::uninit(); - - // Fill memory with 0x01, as an imperfect mitigation for old code that uses this function on - // bool, nonnull, and noundef types. But don't do this if we actively want to detect UB. - if !cfg!(any(miri, sanitize = "memory")) { - val.as_mut_ptr().write_bytes(0x01, 1); - } - - val.assume_init() - } -} - -/// Swaps the values at two mutable locations, without deinitializing either one. -/// -/// * If you want to swap with a default or dummy value, see [`take`]. -/// * If you want to swap with a passed value, returning the old value, see [`replace`]. -/// -/// # Examples -/// -/// ``` -/// use std::mem; -/// -/// let mut x = 5; -/// let mut y = 42; -/// -/// mem::swap(&mut x, &mut y); -/// -/// assert_eq!(42, x); -/// assert_eq!(5, y); -/// ``` -#[inline] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_const_unstable(feature = "const_swap", issue = "83163")] -#[rustc_diagnostic_item = "mem_swap"] -#[cfg_attr(kani, crate::kani::modifies(x))] -#[cfg_attr(kani, crate::kani::modifies(y))] -pub const fn swap(x: &mut T, y: &mut T) { - // SAFETY: `&mut` guarantees these are typed readable and writable - // as well as non-overlapping. - unsafe { intrinsics::typed_swap(x, y) } -} - -/// Replaces `dest` with the default value of `T`, returning the previous `dest` value. -/// -/// * If you want to replace the values of two variables, see [`swap`]. -/// * If you want to replace with a passed value instead of the default value, see [`replace`]. -/// -/// # Examples -/// -/// A simple example: -/// -/// ``` -/// use std::mem; -/// -/// let mut v: Vec = vec![1, 2]; -/// -/// let old_v = mem::take(&mut v); -/// assert_eq!(vec![1, 2], old_v); -/// assert!(v.is_empty()); -/// ``` -/// -/// `take` allows taking ownership of a struct field by replacing it with an "empty" value. -/// Without `take` you can run into issues like these: -/// -/// ```compile_fail,E0507 -/// struct Buffer { buf: Vec } -/// -/// impl Buffer { -/// fn get_and_reset(&mut self) -> Vec { -/// // error: cannot move out of dereference of `&mut`-pointer -/// let buf = self.buf; -/// self.buf = Vec::new(); -/// buf -/// } -/// } -/// ``` -/// -/// Note that `T` does not necessarily implement [`Clone`], so it can't even clone and reset -/// `self.buf`. But `take` can be used to disassociate the original value of `self.buf` from -/// `self`, allowing it to be returned: -/// -/// ``` -/// use std::mem; -/// -/// # struct Buffer { buf: Vec } -/// impl Buffer { -/// fn get_and_reset(&mut self) -> Vec { -/// mem::take(&mut self.buf) -/// } -/// } -/// -/// let mut buffer = Buffer { buf: vec![0, 1] }; -/// assert_eq!(buffer.buf.len(), 2); -/// -/// assert_eq!(buffer.get_and_reset(), vec![0, 1]); -/// assert_eq!(buffer.buf.len(), 0); -/// ``` -#[inline] -#[stable(feature = "mem_take", since = "1.40.0")] -pub fn take(dest: &mut T) -> T { - replace(dest, T::default()) -} - -/// Moves `src` into the referenced `dest`, returning the previous `dest` value. -/// -/// Neither value is dropped. -/// -/// * If you want to replace the values of two variables, see [`swap`]. -/// * If you want to replace with a default value, see [`take`]. -/// -/// # Examples -/// -/// A simple example: -/// -/// ``` -/// use std::mem; -/// -/// let mut v: Vec = vec![1, 2]; -/// -/// let old_v = mem::replace(&mut v, vec![3, 4, 5]); -/// assert_eq!(vec![1, 2], old_v); -/// assert_eq!(vec![3, 4, 5], v); -/// ``` -/// -/// `replace` allows consumption of a struct field by replacing it with another value. -/// Without `replace` you can run into issues like these: -/// -/// ```compile_fail,E0507 -/// struct Buffer { buf: Vec } -/// -/// impl Buffer { -/// fn replace_index(&mut self, i: usize, v: T) -> T { -/// // error: cannot move out of dereference of `&mut`-pointer -/// let t = self.buf[i]; -/// self.buf[i] = v; -/// t -/// } -/// } -/// ``` -/// -/// Note that `T` does not necessarily implement [`Clone`], so we can't even clone `self.buf[i]` to -/// avoid the move. But `replace` can be used to disassociate the original value at that index from -/// `self`, allowing it to be returned: -/// -/// ``` -/// # #![allow(dead_code)] -/// use std::mem; -/// -/// # struct Buffer { buf: Vec } -/// impl Buffer { -/// fn replace_index(&mut self, i: usize, v: T) -> T { -/// mem::replace(&mut self.buf[i], v) -/// } -/// } -/// -/// let mut buffer = Buffer { buf: vec![0, 1] }; -/// assert_eq!(buffer.buf[0], 0); -/// -/// assert_eq!(buffer.replace_index(0, 2), 0); -/// assert_eq!(buffer.buf[0], 2); -/// ``` -#[inline] -#[stable(feature = "rust1", since = "1.0.0")] -#[must_use = "if you don't need the old value, you can just assign the new value directly"] -#[rustc_const_unstable(feature = "const_replace", issue = "83164")] -#[cfg_attr(not(test), rustc_diagnostic_item = "mem_replace")] -pub const fn replace(dest: &mut T, src: T) -> T { - // It may be tempting to use `swap` to avoid `unsafe` here. Don't! - // The compiler optimizes the implementation below to two `memcpy`s - // while `swap` would require at least three. See PR#83022 for details. - - // SAFETY: We read from `dest` but directly write `src` into it afterwards, - // such that the old value is not duplicated. Nothing is dropped and - // nothing here can panic. - unsafe { - let result = ptr::read(dest); - ptr::write(dest, src); - result - } -} - -/// Disposes of a value. -/// -/// This does so by calling the argument's implementation of [`Drop`][drop]. -/// -/// This effectively does nothing for types which implement `Copy`, e.g. -/// integers. Such values are copied and _then_ moved into the function, so the -/// value persists after this function call. -/// -/// This function is not magic; it is literally defined as -/// -/// ``` -/// pub fn drop(_x: T) {} -/// ``` -/// -/// Because `_x` is moved into the function, it is automatically dropped before -/// the function returns. -/// -/// [drop]: Drop -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// let v = vec![1, 2, 3]; -/// -/// drop(v); // explicitly drop the vector -/// ``` -/// -/// Since [`RefCell`] enforces the borrow rules at runtime, `drop` can -/// release a [`RefCell`] borrow: -/// -/// ``` -/// use std::cell::RefCell; -/// -/// let x = RefCell::new(1); -/// -/// let mut mutable_borrow = x.borrow_mut(); -/// *mutable_borrow = 1; -/// -/// drop(mutable_borrow); // relinquish the mutable borrow on this slot -/// -/// let borrow = x.borrow(); -/// println!("{}", *borrow); -/// ``` -/// -/// Integers and other types implementing [`Copy`] are unaffected by `drop`. -/// -/// ``` -/// # #![allow(dropping_copy_types)] -/// #[derive(Copy, Clone)] -/// struct Foo(u8); -/// -/// let x = 1; -/// let y = Foo(2); -/// drop(x); // a copy of `x` is moved and dropped -/// drop(y); // a copy of `y` is moved and dropped -/// -/// println!("x: {}, y: {}", x, y.0); // still available -/// ``` -/// -/// [`RefCell`]: crate::cell::RefCell -#[inline] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "mem_drop")] -pub fn drop(_x: T) {} - -/// Bitwise-copies a value. -/// -/// This function is not magic; it is literally defined as -/// ``` -/// pub fn copy(x: &T) -> T { *x } -/// ``` -/// -/// It is useful when you want to pass a function pointer to a combinator, rather than defining a new closure. -/// -/// Example: -/// ``` -/// #![feature(mem_copy_fn)] -/// use core::mem::copy; -/// let result_from_ffi_function: Result<(), &i32> = Err(&1); -/// let result_copied: Result<(), i32> = result_from_ffi_function.map_err(copy); -/// ``` -#[inline] -#[unstable(feature = "mem_copy_fn", issue = "98262")] -pub const fn copy(x: &T) -> T { - *x -} - -/// Interprets `src` as having type `&Dst`, and then reads `src` without moving -/// the contained value. -/// -/// This function will unsafely assume the pointer `src` is valid for [`size_of::`][size_of] -/// bytes by transmuting `&Src` to `&Dst` and then reading the `&Dst` (except that this is done -/// in a way that is correct even when `&Dst` has stricter alignment requirements than `&Src`). -/// It will also unsafely create a copy of the contained value instead of moving out of `src`. -/// -/// It is not a compile-time error if `Src` and `Dst` have different sizes, but it -/// is highly encouraged to only invoke this function where `Src` and `Dst` have the -/// same size. This function triggers [undefined behavior][ub] if `Dst` is larger than -/// `Src`. -/// -/// [ub]: ../../reference/behavior-considered-undefined.html -/// -/// # Examples -/// -/// ``` -/// use std::mem; -/// -/// #[repr(packed)] -/// struct Foo { -/// bar: u8, -/// } -/// -/// let foo_array = [10u8]; -/// -/// unsafe { -/// // Copy the data from 'foo_array' and treat it as a 'Foo' -/// let mut foo_struct: Foo = mem::transmute_copy(&foo_array); -/// assert_eq!(foo_struct.bar, 10); -/// -/// // Modify the copied data -/// foo_struct.bar = 20; -/// assert_eq!(foo_struct.bar, 20); -/// } -/// -/// // The contents of 'foo_array' should not have changed -/// assert_eq!(foo_array, [10]); -/// ``` -#[inline] -#[must_use] -#[track_caller] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_const_stable(feature = "const_transmute_copy", since = "1.74.0")] -pub const unsafe fn transmute_copy(src: &Src) -> Dst { - assert!( - size_of::() >= size_of::(), - "cannot transmute_copy if Dst is larger than Src" - ); - - // If Dst has a higher alignment requirement, src might not be suitably aligned. - if align_of::() > align_of::() { - // SAFETY: `src` is a reference which is guaranteed to be valid for reads. - // The caller must guarantee that the actual transmutation is safe. - unsafe { ptr::read_unaligned(src as *const Src as *const Dst) } - } else { - // SAFETY: `src` is a reference which is guaranteed to be valid for reads. - // We just checked that `src as *const Dst` was properly aligned. - // The caller must guarantee that the actual transmutation is safe. - unsafe { ptr::read(src as *const Src as *const Dst) } - } -} - -/// Opaque type representing the discriminant of an enum. -/// -/// See the [`discriminant`] function in this module for more information. -#[stable(feature = "discriminant_value", since = "1.21.0")] -pub struct Discriminant(::Discriminant); - -// N.B. These trait implementations cannot be derived because we don't want any bounds on T. - -#[stable(feature = "discriminant_value", since = "1.21.0")] -impl Copy for Discriminant {} - -#[stable(feature = "discriminant_value", since = "1.21.0")] -impl clone::Clone for Discriminant { - fn clone(&self) -> Self { - *self - } -} - -#[stable(feature = "discriminant_value", since = "1.21.0")] -impl cmp::PartialEq for Discriminant { - fn eq(&self, rhs: &Self) -> bool { - self.0 == rhs.0 - } -} - -#[stable(feature = "discriminant_value", since = "1.21.0")] -impl cmp::Eq for Discriminant {} - -#[stable(feature = "discriminant_value", since = "1.21.0")] -impl hash::Hash for Discriminant { - fn hash(&self, state: &mut H) { - self.0.hash(state); - } -} - -#[stable(feature = "discriminant_value", since = "1.21.0")] -impl fmt::Debug for Discriminant { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_tuple("Discriminant").field(&self.0).finish() - } -} - -/// Returns a value uniquely identifying the enum variant in `v`. -/// -/// If `T` is not an enum, calling this function will not result in undefined behavior, but the -/// return value is unspecified. -/// -/// # Stability -/// -/// The discriminant of an enum variant may change if the enum definition changes. A discriminant -/// of some variant will not change between compilations with the same compiler. See the [Reference] -/// for more information. -/// -/// [Reference]: ../../reference/items/enumerations.html#custom-discriminant-values-for-fieldless-enumerations -/// -/// The value of a [`Discriminant`] is independent of any *free lifetimes* in `T`. As such, -/// reading or writing a `Discriminant>` as a `Discriminant>` (whether via -/// [`transmute`] or otherwise) is always sound. Note that this is **not** true for other kinds -/// of generic parameters and for higher-ranked lifetimes; `Discriminant>` and -/// `Discriminant>` as well as `Discriminant Trait<'a>>>` and -/// `Discriminant>>` may be incompatible. -/// -/// # Examples -/// -/// This can be used to compare enums that carry data, while disregarding -/// the actual data: -/// -/// ``` -/// use std::mem; -/// -/// enum Foo { A(&'static str), B(i32), C(i32) } -/// -/// assert_eq!(mem::discriminant(&Foo::A("bar")), mem::discriminant(&Foo::A("baz"))); -/// assert_eq!(mem::discriminant(&Foo::B(1)), mem::discriminant(&Foo::B(2))); -/// assert_ne!(mem::discriminant(&Foo::B(3)), mem::discriminant(&Foo::C(3))); -/// ``` -/// -/// ## Accessing the numeric value of the discriminant -/// -/// Note that it is *undefined behavior* to [`transmute`] from [`Discriminant`] to a primitive! -/// -/// If an enum has only unit variants, then the numeric value of the discriminant can be accessed -/// with an [`as`] cast: -/// -/// ``` -/// enum Enum { -/// Foo, -/// Bar, -/// Baz, -/// } -/// -/// assert_eq!(0, Enum::Foo as isize); -/// assert_eq!(1, Enum::Bar as isize); -/// assert_eq!(2, Enum::Baz as isize); -/// ``` -/// -/// If an enum has opted-in to having a [primitive representation] for its discriminant, -/// then it's possible to use pointers to read the memory location storing the discriminant. -/// That **cannot** be done for enums using the [default representation], however, as it's -/// undefined what layout the discriminant has and where it's stored — it might not even be -/// stored at all! -/// -/// [`as`]: ../../std/keyword.as.html -/// [primitive representation]: ../../reference/type-layout.html#primitive-representations -/// [default representation]: ../../reference/type-layout.html#the-default-representation -/// ``` -/// #[repr(u8)] -/// enum Enum { -/// Unit, -/// Tuple(bool), -/// Struct { a: bool }, -/// } -/// -/// impl Enum { -/// fn discriminant(&self) -> u8 { -/// // SAFETY: Because `Self` is marked `repr(u8)`, its layout is a `repr(C)` `union` -/// // between `repr(C)` structs, each of which has the `u8` discriminant as its first -/// // field, so we can read the discriminant without offsetting the pointer. -/// unsafe { *<*const _>::from(self).cast::() } -/// } -/// } -/// -/// let unit_like = Enum::Unit; -/// let tuple_like = Enum::Tuple(true); -/// let struct_like = Enum::Struct { a: false }; -/// assert_eq!(0, unit_like.discriminant()); -/// assert_eq!(1, tuple_like.discriminant()); -/// assert_eq!(2, struct_like.discriminant()); -/// -/// // ⚠️ This is undefined behavior. Don't do this. ⚠️ -/// // assert_eq!(0, unsafe { std::mem::transmute::<_, u8>(std::mem::discriminant(&unit_like)) }); -/// ``` -#[stable(feature = "discriminant_value", since = "1.21.0")] -#[rustc_const_stable(feature = "const_discriminant", since = "1.75.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "mem_discriminant")] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -pub const fn discriminant(v: &T) -> Discriminant { - Discriminant(intrinsics::discriminant_value(v)) -} - -/// Returns the number of variants in the enum type `T`. -/// -/// If `T` is not an enum, calling this function will not result in undefined behavior, but the -/// return value is unspecified. Equally, if `T` is an enum with more variants than `usize::MAX` -/// the return value is unspecified. Uninhabited variants will be counted. -/// -/// Note that an enum may be expanded with additional variants in the future -/// as a non-breaking change, for example if it is marked `#[non_exhaustive]`, -/// which will change the result of this function. -/// -/// # Examples -/// -/// ``` -/// # #![feature(never_type)] -/// # #![feature(variant_count)] -/// -/// use std::mem; -/// -/// enum Void {} -/// enum Foo { A(&'static str), B(i32), C(i32) } -/// -/// assert_eq!(mem::variant_count::(), 0); -/// assert_eq!(mem::variant_count::(), 3); -/// -/// assert_eq!(mem::variant_count::>(), 2); -/// assert_eq!(mem::variant_count::>(), 2); -/// ``` -#[inline(always)] -#[must_use] -#[unstable(feature = "variant_count", issue = "73662")] -#[rustc_const_unstable(feature = "variant_count", issue = "73662")] -#[rustc_diagnostic_item = "mem_variant_count"] -pub const fn variant_count() -> usize { - intrinsics::variant_count::() -} - -/// Provides associated constants for various useful properties of types, -/// to give them a canonical form in our code and make them easier to read. -/// -/// This is here only to simplify all the ZST checks we need in the library. -/// It's not on a stabilization track right now. -#[doc(hidden)] -#[unstable(feature = "sized_type_properties", issue = "none")] -pub trait SizedTypeProperties: Sized { - /// `true` if this type requires no storage. - /// `false` if its [size](size_of) is greater than zero. - /// - /// # Examples - /// - /// ``` - /// #![feature(sized_type_properties)] - /// use core::mem::SizedTypeProperties; - /// - /// fn do_something_with() { - /// if T::IS_ZST { - /// // ... special approach ... - /// } else { - /// // ... the normal thing ... - /// } - /// } - /// - /// struct MyUnit; - /// assert!(MyUnit::IS_ZST); - /// - /// // For negative checks, consider using UFCS to emphasize the negation - /// assert!(!::IS_ZST); - /// // As it can sometimes hide in the type otherwise - /// assert!(!String::IS_ZST); - /// ``` - #[doc(hidden)] - #[unstable(feature = "sized_type_properties", issue = "none")] - const IS_ZST: bool = size_of::() == 0; -} -#[doc(hidden)] -#[unstable(feature = "sized_type_properties", issue = "none")] -impl SizedTypeProperties for T {} - -/// Expands to the offset in bytes of a field from the beginning of the given type. -/// -/// Structs, enums, unions and tuples are supported. -/// -/// Nested field accesses may be used, but not array indexes. -/// -/// Enum variants may be traversed as if they were fields. Variants themselves do -/// not have an offset. -/// -/// However, on stable only a single field name is supported, which blocks the use of -/// enum support. -/// -/// Visibility is respected - all types and fields must be visible to the call site: -/// -/// ``` -/// mod nested { -/// #[repr(C)] -/// pub struct Struct { -/// private: u8, -/// } -/// } -/// -/// // assert_eq!(mem::offset_of!(nested::Struct, private), 0); -/// // ^^^ error[E0616]: field `private` of struct `Struct` is private -/// ``` -/// -/// Note that type layout is, in general, [subject to change and -/// platform-specific](https://doc.rust-lang.org/reference/type-layout.html). If -/// layout stability is required, consider using an [explicit `repr` attribute]. -/// -/// Rust guarantees that the offset of a given field within a given type will not -/// change over the lifetime of the program. However, two different compilations of -/// the same program may result in different layouts. Also, even within a single -/// program execution, no guarantees are made about types which are *similar* but -/// not *identical*, e.g.: -/// -/// ``` -/// struct Wrapper(T, U); -/// -/// type A = Wrapper; -/// type B = Wrapper; -/// -/// // Not necessarily identical even though `u8` and `i8` have the same layout! -/// // assert_eq!(mem::offset_of!(A, 1), mem::offset_of!(B, 1)); -/// -/// #[repr(transparent)] -/// struct U8(u8); -/// -/// type C = Wrapper; -/// -/// // Not necessarily identical even though `u8` and `U8` have the same layout! -/// // assert_eq!(mem::offset_of!(A, 1), mem::offset_of!(C, 1)); -/// -/// struct Empty(core::marker::PhantomData); -/// -/// // Not necessarily identical even though `PhantomData` always has the same layout! -/// // assert_eq!(mem::offset_of!(Empty, 0), mem::offset_of!(Empty, 0)); -/// ``` -/// -/// [explicit `repr` attribute]: https://doc.rust-lang.org/reference/type-layout.html#representations -/// -/// # Examples -/// -/// ``` -/// #![feature(offset_of_enum, offset_of_nested)] -/// -/// use std::mem; -/// #[repr(C)] -/// struct FieldStruct { -/// first: u8, -/// second: u16, -/// third: u8 -/// } -/// -/// assert_eq!(mem::offset_of!(FieldStruct, first), 0); -/// assert_eq!(mem::offset_of!(FieldStruct, second), 2); -/// assert_eq!(mem::offset_of!(FieldStruct, third), 4); -/// -/// #[repr(C)] -/// struct NestedA { -/// b: NestedB -/// } -/// -/// #[repr(C)] -/// struct NestedB(u8); -/// -/// assert_eq!(mem::offset_of!(NestedA, b.0), 0); -/// -/// #[repr(u8)] -/// enum Enum { -/// A(u8, u16), -/// B { one: u8, two: u16 }, -/// } -/// -/// assert_eq!(mem::offset_of!(Enum, A.0), 1); -/// assert_eq!(mem::offset_of!(Enum, B.two), 2); -/// -/// assert_eq!(mem::offset_of!(Option<&u8>, Some.0), 0); -/// ``` -#[stable(feature = "offset_of", since = "1.77.0")] -#[allow_internal_unstable(builtin_syntax)] -pub macro offset_of($Container:ty, $($fields:expr)+ $(,)?) { - // The `{}` is for better error messages - {builtin # offset_of($Container, $($fields)+)} -} - -#[cfg(kani)] -#[unstable(feature="kani", issue="none")] -mod verify { - use super::*; - use crate::kani; - - /// Use this type to ensure that mem swap does not drop the value. - #[derive(kani::Arbitrary)] - struct CannotDrop { - inner: T, - } - - impl Drop for CannotDrop { - fn drop(&mut self) { - unreachable!("Cannot drop") - } - } - - #[kani::proof_for_contract(swap)] - pub fn check_swap_primitive() { - let mut x: u8 = kani::any(); - let mut y: u8 = kani::any(); - swap(&mut x, &mut y) - } - - #[kani::proof_for_contract(swap)] - pub fn check_swap_adt_no_drop() { - let mut x: CannotDrop = kani::any(); - let mut y: CannotDrop = kani::any(); - swap(&mut x, &mut y); - forget(x); - forget(y); - } -} diff --git a/library/core/src/mem/transmutability.rs b/library/core/src/mem/transmutability.rs deleted file mode 100644 index 827426b235839..0000000000000 --- a/library/core/src/mem/transmutability.rs +++ /dev/null @@ -1,109 +0,0 @@ -use crate::marker::ConstParamTy; - -/// Are values of a type transmutable into values of another type? -/// -/// This trait is implemented on-the-fly by the compiler for types `Src` and `Self` when the bits of -/// any value of type `Self` are safely transmutable into a value of type `Dst`, in a given `Context`, -/// notwithstanding whatever safety checks you have asked the compiler to [`Assume`] are satisfied. -#[unstable(feature = "transmutability", issue = "99571")] -#[lang = "transmute_trait"] -#[rustc_deny_explicit_impl(implement_via_object = false)] -#[rustc_coinductive] -pub unsafe trait BikeshedIntrinsicFrom -where - Src: ?Sized, -{ -} - -/// What transmutation safety conditions shall the compiler assume that *you* are checking? -#[unstable(feature = "transmutability", issue = "99571")] -#[lang = "transmute_opts"] -#[derive(PartialEq, Eq, Clone, Copy, Debug)] -pub struct Assume { - /// When `true`, the compiler assumes that *you* are ensuring (either dynamically or statically) that - /// destination referents do not have stricter alignment requirements than source referents. - pub alignment: bool, - - /// When `true`, the compiler assume that *you* are ensuring that lifetimes are not extended in a manner - /// that violates Rust's memory model. - pub lifetimes: bool, - - /// When `true`, the compiler assumes that *you* have ensured that no - /// unsoundness will arise from violating the safety invariants of the - /// destination type (and sometimes of the source type, too). - pub safety: bool, - - /// When `true`, the compiler assumes that *you* are ensuring that the source type is actually a valid - /// instance of the destination type. - pub validity: bool, -} - -#[unstable(feature = "transmutability", issue = "99571")] -impl ConstParamTy for Assume {} - -impl Assume { - /// Do not assume that *you* have ensured any safety properties are met. - #[unstable(feature = "transmutability", issue = "99571")] - pub const NOTHING: Self = - Self { alignment: false, lifetimes: false, safety: false, validity: false }; - - /// Assume only that alignment conditions are met. - #[unstable(feature = "transmutability", issue = "99571")] - pub const ALIGNMENT: Self = Self { alignment: true, ..Self::NOTHING }; - - /// Assume only that lifetime conditions are met. - #[unstable(feature = "transmutability", issue = "99571")] - pub const LIFETIMES: Self = Self { lifetimes: true, ..Self::NOTHING }; - - /// Assume only that safety conditions are met. - #[unstable(feature = "transmutability", issue = "99571")] - pub const SAFETY: Self = Self { safety: true, ..Self::NOTHING }; - - /// Assume only that dynamically-satisfiable validity conditions are met. - #[unstable(feature = "transmutability", issue = "99571")] - pub const VALIDITY: Self = Self { validity: true, ..Self::NOTHING }; - - /// Assume both `self` and `other_assumptions`. - #[unstable(feature = "transmutability", issue = "99571")] - pub const fn and(self, other_assumptions: Self) -> Self { - Self { - alignment: self.alignment || other_assumptions.alignment, - lifetimes: self.lifetimes || other_assumptions.lifetimes, - safety: self.safety || other_assumptions.safety, - validity: self.validity || other_assumptions.validity, - } - } - - /// Assume `self`, excepting `other_assumptions`. - #[unstable(feature = "transmutability", issue = "99571")] - pub const fn but_not(self, other_assumptions: Self) -> Self { - Self { - alignment: self.alignment && !other_assumptions.alignment, - lifetimes: self.lifetimes && !other_assumptions.lifetimes, - safety: self.safety && !other_assumptions.safety, - validity: self.validity && !other_assumptions.validity, - } - } -} - -// FIXME(jswrenn): This const op is not actually usable. Why? -// https://github.com/rust-lang/rust/pull/100726#issuecomment-1219928926 -#[unstable(feature = "transmutability", issue = "99571")] -impl core::ops::Add for Assume { - type Output = Assume; - - fn add(self, other_assumptions: Assume) -> Assume { - self.and(other_assumptions) - } -} - -// FIXME(jswrenn): This const op is not actually usable. Why? -// https://github.com/rust-lang/rust/pull/100726#issuecomment-1219928926 -#[unstable(feature = "transmutability", issue = "99571")] -impl core::ops::Sub for Assume { - type Output = Assume; - - fn sub(self, other_assumptions: Assume) -> Assume { - self.but_not(other_assumptions) - } -} diff --git a/library/core/src/net/display_buffer.rs b/library/core/src/net/display_buffer.rs deleted file mode 100644 index b7e778605fc0a..0000000000000 --- a/library/core/src/net/display_buffer.rs +++ /dev/null @@ -1,40 +0,0 @@ -use crate::fmt; -use crate::mem::MaybeUninit; -use crate::str; - -/// Used for slow path in `Display` implementations when alignment is required. -pub struct DisplayBuffer { - buf: [MaybeUninit; SIZE], - len: usize, -} - -impl DisplayBuffer { - #[inline] - pub const fn new() -> Self { - Self { buf: MaybeUninit::uninit_array(), len: 0 } - } - - #[inline] - pub fn as_str(&self) -> &str { - // SAFETY: `buf` is only written to by the `fmt::Write::write_str` implementation - // which writes a valid UTF-8 string to `buf` and correctly sets `len`. - unsafe { - let s = MaybeUninit::slice_assume_init_ref(&self.buf[..self.len]); - str::from_utf8_unchecked(s) - } - } -} - -impl fmt::Write for DisplayBuffer { - fn write_str(&mut self, s: &str) -> fmt::Result { - let bytes = s.as_bytes(); - - if let Some(buf) = self.buf.get_mut(self.len..(self.len + bytes.len())) { - MaybeUninit::copy_from_slice(buf, bytes); - self.len += bytes.len(); - Ok(()) - } else { - Err(fmt::Error) - } - } -} diff --git a/library/core/src/net/ip_addr.rs b/library/core/src/net/ip_addr.rs deleted file mode 100644 index 959c3289affbf..0000000000000 --- a/library/core/src/net/ip_addr.rs +++ /dev/null @@ -1,2334 +0,0 @@ -use crate::cmp::Ordering; -use crate::fmt::{self, Write}; -use crate::iter; -use crate::mem::transmute; -use crate::ops::{BitAnd, BitAndAssign, BitOr, BitOrAssign, Not}; - -use super::display_buffer::DisplayBuffer; - -/// An IP address, either IPv4 or IPv6. -/// -/// This enum can contain either an [`Ipv4Addr`] or an [`Ipv6Addr`], see their -/// respective documentation for more details. -/// -/// # Examples -/// -/// ``` -/// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr}; -/// -/// let localhost_v4 = IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)); -/// let localhost_v6 = IpAddr::V6(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1)); -/// -/// assert_eq!("127.0.0.1".parse(), Ok(localhost_v4)); -/// assert_eq!("::1".parse(), Ok(localhost_v6)); -/// -/// assert_eq!(localhost_v4.is_ipv6(), false); -/// assert_eq!(localhost_v4.is_ipv4(), true); -/// ``` -#[cfg_attr(not(test), rustc_diagnostic_item = "IpAddr")] -#[stable(feature = "ip_addr", since = "1.7.0")] -#[derive(Copy, Clone, Eq, PartialEq, Hash, PartialOrd, Ord)] -pub enum IpAddr { - /// An IPv4 address. - #[stable(feature = "ip_addr", since = "1.7.0")] - V4(#[stable(feature = "ip_addr", since = "1.7.0")] Ipv4Addr), - /// An IPv6 address. - #[stable(feature = "ip_addr", since = "1.7.0")] - V6(#[stable(feature = "ip_addr", since = "1.7.0")] Ipv6Addr), -} - -/// An IPv4 address. -/// -/// IPv4 addresses are defined as 32-bit integers in [IETF RFC 791]. -/// They are usually represented as four octets. -/// -/// See [`IpAddr`] for a type encompassing both IPv4 and IPv6 addresses. -/// -/// [IETF RFC 791]: https://tools.ietf.org/html/rfc791 -/// -/// # Textual representation -/// -/// `Ipv4Addr` provides a [`FromStr`] implementation. The four octets are in decimal -/// notation, divided by `.` (this is called "dot-decimal notation"). -/// Notably, octal numbers (which are indicated with a leading `0`) and hexadecimal numbers (which -/// are indicated with a leading `0x`) are not allowed per [IETF RFC 6943]. -/// -/// [IETF RFC 6943]: https://tools.ietf.org/html/rfc6943#section-3.1.1 -/// [`FromStr`]: crate::str::FromStr -/// -/// # Examples -/// -/// ``` -/// use std::net::Ipv4Addr; -/// -/// let localhost = Ipv4Addr::new(127, 0, 0, 1); -/// assert_eq!("127.0.0.1".parse(), Ok(localhost)); -/// assert_eq!(localhost.is_loopback(), true); -/// assert!("012.004.002.000".parse::().is_err()); // all octets are in octal -/// assert!("0000000.0.0.0".parse::().is_err()); // first octet is a zero in octal -/// assert!("0xcb.0x0.0x71.0x00".parse::().is_err()); // all octets are in hex -/// ``` -#[derive(Copy, Clone, PartialEq, Eq, Hash)] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Ipv4Addr { - octets: [u8; 4], -} - -/// An IPv6 address. -/// -/// IPv6 addresses are defined as 128-bit integers in [IETF RFC 4291]. -/// They are usually represented as eight 16-bit segments. -/// -/// [IETF RFC 4291]: https://tools.ietf.org/html/rfc4291 -/// -/// # Embedding IPv4 Addresses -/// -/// See [`IpAddr`] for a type encompassing both IPv4 and IPv6 addresses. -/// -/// To assist in the transition from IPv4 to IPv6 two types of IPv6 addresses that embed an IPv4 address were defined: -/// IPv4-compatible and IPv4-mapped addresses. Of these IPv4-compatible addresses have been officially deprecated. -/// -/// Both types of addresses are not assigned any special meaning by this implementation, -/// other than what the relevant standards prescribe. This means that an address like `::ffff:127.0.0.1`, -/// while representing an IPv4 loopback address, is not itself an IPv6 loopback address; only `::1` is. -/// To handle these so called "IPv4-in-IPv6" addresses, they have to first be converted to their canonical IPv4 address. -/// -/// ### IPv4-Compatible IPv6 Addresses -/// -/// IPv4-compatible IPv6 addresses are defined in [IETF RFC 4291 Section 2.5.5.1], and have been officially deprecated. -/// The RFC describes the format of an "IPv4-Compatible IPv6 address" as follows: -/// -/// ```text -/// | 80 bits | 16 | 32 bits | -/// +--------------------------------------+--------------------------+ -/// |0000..............................0000|0000| IPv4 address | -/// +--------------------------------------+----+---------------------+ -/// ``` -/// So `::a.b.c.d` would be an IPv4-compatible IPv6 address representing the IPv4 address `a.b.c.d`. -/// -/// To convert from an IPv4 address to an IPv4-compatible IPv6 address, use [`Ipv4Addr::to_ipv6_compatible`]. -/// Use [`Ipv6Addr::to_ipv4`] to convert an IPv4-compatible IPv6 address to the canonical IPv4 address. -/// -/// [IETF RFC 4291 Section 2.5.5.1]: https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.5.1 -/// -/// ### IPv4-Mapped IPv6 Addresses -/// -/// IPv4-mapped IPv6 addresses are defined in [IETF RFC 4291 Section 2.5.5.2]. -/// The RFC describes the format of an "IPv4-Mapped IPv6 address" as follows: -/// -/// ```text -/// | 80 bits | 16 | 32 bits | -/// +--------------------------------------+--------------------------+ -/// |0000..............................0000|FFFF| IPv4 address | -/// +--------------------------------------+----+---------------------+ -/// ``` -/// So `::ffff:a.b.c.d` would be an IPv4-mapped IPv6 address representing the IPv4 address `a.b.c.d`. -/// -/// To convert from an IPv4 address to an IPv4-mapped IPv6 address, use [`Ipv4Addr::to_ipv6_mapped`]. -/// Use [`Ipv6Addr::to_ipv4`] to convert an IPv4-mapped IPv6 address to the canonical IPv4 address. -/// Note that this will also convert the IPv6 loopback address `::1` to `0.0.0.1`. Use -/// [`Ipv6Addr::to_ipv4_mapped`] to avoid this. -/// -/// [IETF RFC 4291 Section 2.5.5.2]: https://datatracker.ietf.org/doc/html/rfc4291#section-2.5.5.2 -/// -/// # Textual representation -/// -/// `Ipv6Addr` provides a [`FromStr`] implementation. There are many ways to represent -/// an IPv6 address in text, but in general, each segments is written in hexadecimal -/// notation, and segments are separated by `:`. For more information, see -/// [IETF RFC 5952]. -/// -/// [`FromStr`]: crate::str::FromStr -/// [IETF RFC 5952]: https://tools.ietf.org/html/rfc5952 -/// -/// # Examples -/// -/// ``` -/// use std::net::Ipv6Addr; -/// -/// let localhost = Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1); -/// assert_eq!("::1".parse(), Ok(localhost)); -/// assert_eq!(localhost.is_loopback(), true); -/// ``` -#[derive(Copy, Clone, PartialEq, Eq, Hash)] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Ipv6Addr { - octets: [u8; 16], -} - -/// Scope of an [IPv6 multicast address] as defined in [IETF RFC 7346 section 2]. -/// -/// # Stability Guarantees -/// -/// Not all possible values for a multicast scope have been assigned. -/// Future RFCs may introduce new scopes, which will be added as variants to this enum; -/// because of this the enum is marked as `#[non_exhaustive]`. -/// -/// # Examples -/// ``` -/// #![feature(ip)] -/// -/// use std::net::Ipv6Addr; -/// use std::net::Ipv6MulticastScope::*; -/// -/// // An IPv6 multicast address with global scope (`ff0e::`). -/// let address = Ipv6Addr::new(0xff0e, 0, 0, 0, 0, 0, 0, 0); -/// -/// // Will print "Global scope". -/// match address.multicast_scope() { -/// Some(InterfaceLocal) => println!("Interface-Local scope"), -/// Some(LinkLocal) => println!("Link-Local scope"), -/// Some(RealmLocal) => println!("Realm-Local scope"), -/// Some(AdminLocal) => println!("Admin-Local scope"), -/// Some(SiteLocal) => println!("Site-Local scope"), -/// Some(OrganizationLocal) => println!("Organization-Local scope"), -/// Some(Global) => println!("Global scope"), -/// Some(_) => println!("Unknown scope"), -/// None => println!("Not a multicast address!") -/// } -/// -/// ``` -/// -/// [IPv6 multicast address]: Ipv6Addr -/// [IETF RFC 7346 section 2]: https://tools.ietf.org/html/rfc7346#section-2 -#[derive(Copy, PartialEq, Eq, Clone, Hash, Debug)] -#[unstable(feature = "ip", issue = "27709")] -#[non_exhaustive] -pub enum Ipv6MulticastScope { - /// Interface-Local scope. - InterfaceLocal, - /// Link-Local scope. - LinkLocal, - /// Realm-Local scope. - RealmLocal, - /// Admin-Local scope. - AdminLocal, - /// Site-Local scope. - SiteLocal, - /// Organization-Local scope. - OrganizationLocal, - /// Global scope. - Global, -} - -impl IpAddr { - /// Returns [`true`] for the special 'unspecified' address. - /// - /// See the documentation for [`Ipv4Addr::is_unspecified()`] and - /// [`Ipv6Addr::is_unspecified()`] for more details. - /// - /// # Examples - /// - /// ``` - /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr}; - /// - /// assert_eq!(IpAddr::V4(Ipv4Addr::new(0, 0, 0, 0)).is_unspecified(), true); - /// assert_eq!(IpAddr::V6(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0)).is_unspecified(), true); - /// ``` - #[rustc_const_stable(feature = "const_ip_50", since = "1.50.0")] - #[stable(feature = "ip_shared", since = "1.12.0")] - #[must_use] - #[inline] - pub const fn is_unspecified(&self) -> bool { - match self { - IpAddr::V4(ip) => ip.is_unspecified(), - IpAddr::V6(ip) => ip.is_unspecified(), - } - } - - /// Returns [`true`] if this is a loopback address. - /// - /// See the documentation for [`Ipv4Addr::is_loopback()`] and - /// [`Ipv6Addr::is_loopback()`] for more details. - /// - /// # Examples - /// - /// ``` - /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr}; - /// - /// assert_eq!(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)).is_loopback(), true); - /// assert_eq!(IpAddr::V6(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0x1)).is_loopback(), true); - /// ``` - #[rustc_const_stable(feature = "const_ip_50", since = "1.50.0")] - #[stable(feature = "ip_shared", since = "1.12.0")] - #[must_use] - #[inline] - pub const fn is_loopback(&self) -> bool { - match self { - IpAddr::V4(ip) => ip.is_loopback(), - IpAddr::V6(ip) => ip.is_loopback(), - } - } - - /// Returns [`true`] if the address appears to be globally routable. - /// - /// See the documentation for [`Ipv4Addr::is_global()`] and - /// [`Ipv6Addr::is_global()`] for more details. - /// - /// # Examples - /// - /// ``` - /// #![feature(ip)] - /// - /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr}; - /// - /// assert_eq!(IpAddr::V4(Ipv4Addr::new(80, 9, 12, 3)).is_global(), true); - /// assert_eq!(IpAddr::V6(Ipv6Addr::new(0, 0, 0x1c9, 0, 0, 0xafc8, 0, 0x1)).is_global(), true); - /// ``` - #[rustc_const_unstable(feature = "const_ip", issue = "76205")] - #[unstable(feature = "ip", issue = "27709")] - #[must_use] - #[inline] - pub const fn is_global(&self) -> bool { - match self { - IpAddr::V4(ip) => ip.is_global(), - IpAddr::V6(ip) => ip.is_global(), - } - } - - /// Returns [`true`] if this is a multicast address. - /// - /// See the documentation for [`Ipv4Addr::is_multicast()`] and - /// [`Ipv6Addr::is_multicast()`] for more details. - /// - /// # Examples - /// - /// ``` - /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr}; - /// - /// assert_eq!(IpAddr::V4(Ipv4Addr::new(224, 254, 0, 0)).is_multicast(), true); - /// assert_eq!(IpAddr::V6(Ipv6Addr::new(0xff00, 0, 0, 0, 0, 0, 0, 0)).is_multicast(), true); - /// ``` - #[rustc_const_stable(feature = "const_ip_50", since = "1.50.0")] - #[stable(feature = "ip_shared", since = "1.12.0")] - #[must_use] - #[inline] - pub const fn is_multicast(&self) -> bool { - match self { - IpAddr::V4(ip) => ip.is_multicast(), - IpAddr::V6(ip) => ip.is_multicast(), - } - } - - /// Returns [`true`] if this address is in a range designated for documentation. - /// - /// See the documentation for [`Ipv4Addr::is_documentation()`] and - /// [`Ipv6Addr::is_documentation()`] for more details. - /// - /// # Examples - /// - /// ``` - /// #![feature(ip)] - /// - /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr}; - /// - /// assert_eq!(IpAddr::V4(Ipv4Addr::new(203, 0, 113, 6)).is_documentation(), true); - /// assert_eq!( - /// IpAddr::V6(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0)).is_documentation(), - /// true - /// ); - /// ``` - #[rustc_const_unstable(feature = "const_ip", issue = "76205")] - #[unstable(feature = "ip", issue = "27709")] - #[must_use] - #[inline] - pub const fn is_documentation(&self) -> bool { - match self { - IpAddr::V4(ip) => ip.is_documentation(), - IpAddr::V6(ip) => ip.is_documentation(), - } - } - - /// Returns [`true`] if this address is in a range designated for benchmarking. - /// - /// See the documentation for [`Ipv4Addr::is_benchmarking()`] and - /// [`Ipv6Addr::is_benchmarking()`] for more details. - /// - /// # Examples - /// - /// ``` - /// #![feature(ip)] - /// - /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr}; - /// - /// assert_eq!(IpAddr::V4(Ipv4Addr::new(198, 19, 255, 255)).is_benchmarking(), true); - /// assert_eq!(IpAddr::V6(Ipv6Addr::new(0x2001, 0x2, 0, 0, 0, 0, 0, 0)).is_benchmarking(), true); - /// ``` - #[unstable(feature = "ip", issue = "27709")] - #[must_use] - #[inline] - pub const fn is_benchmarking(&self) -> bool { - match self { - IpAddr::V4(ip) => ip.is_benchmarking(), - IpAddr::V6(ip) => ip.is_benchmarking(), - } - } - - /// Returns [`true`] if this address is an [`IPv4` address], and [`false`] - /// otherwise. - /// - /// [`IPv4` address]: IpAddr::V4 - /// - /// # Examples - /// - /// ``` - /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr}; - /// - /// assert_eq!(IpAddr::V4(Ipv4Addr::new(203, 0, 113, 6)).is_ipv4(), true); - /// assert_eq!(IpAddr::V6(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0)).is_ipv4(), false); - /// ``` - #[rustc_const_stable(feature = "const_ip_50", since = "1.50.0")] - #[stable(feature = "ipaddr_checker", since = "1.16.0")] - #[must_use] - #[inline] - pub const fn is_ipv4(&self) -> bool { - matches!(self, IpAddr::V4(_)) - } - - /// Returns [`true`] if this address is an [`IPv6` address], and [`false`] - /// otherwise. - /// - /// [`IPv6` address]: IpAddr::V6 - /// - /// # Examples - /// - /// ``` - /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr}; - /// - /// assert_eq!(IpAddr::V4(Ipv4Addr::new(203, 0, 113, 6)).is_ipv6(), false); - /// assert_eq!(IpAddr::V6(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0)).is_ipv6(), true); - /// ``` - #[rustc_const_stable(feature = "const_ip_50", since = "1.50.0")] - #[stable(feature = "ipaddr_checker", since = "1.16.0")] - #[must_use] - #[inline] - pub const fn is_ipv6(&self) -> bool { - matches!(self, IpAddr::V6(_)) - } - - /// Converts this address to an `IpAddr::V4` if it is an IPv4-mapped IPv6 addresses, otherwise it - /// returns `self` as-is. - /// - /// # Examples - /// - /// ``` - /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr}; - /// - /// let localhost_v4 = Ipv4Addr::new(127, 0, 0, 1); - /// - /// assert_eq!(IpAddr::V4(localhost_v4).to_canonical(), localhost_v4); - /// assert_eq!(IpAddr::V6(localhost_v4.to_ipv6_mapped()).to_canonical(), localhost_v4); - /// assert_eq!(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)).to_canonical().is_loopback(), true); - /// assert_eq!(IpAddr::V6(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0x7f00, 0x1)).is_loopback(), false); - /// assert_eq!(IpAddr::V6(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0x7f00, 0x1)).to_canonical().is_loopback(), true); - /// ``` - #[inline] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[stable(feature = "ip_to_canonical", since = "1.75.0")] - #[rustc_const_stable(feature = "ip_to_canonical", since = "1.75.0")] - pub const fn to_canonical(&self) -> IpAddr { - match self { - IpAddr::V4(_) => *self, - IpAddr::V6(v6) => v6.to_canonical(), - } - } -} - -impl Ipv4Addr { - /// Creates a new IPv4 address from four eight-bit octets. - /// - /// The result will represent the IP address `a`.`b`.`c`.`d`. - /// - /// # Examples - /// - /// ``` - /// use std::net::Ipv4Addr; - /// - /// let addr = Ipv4Addr::new(127, 0, 0, 1); - /// ``` - #[rustc_const_stable(feature = "const_ip_32", since = "1.32.0")] - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - #[inline] - pub const fn new(a: u8, b: u8, c: u8, d: u8) -> Ipv4Addr { - Ipv4Addr { octets: [a, b, c, d] } - } - - /// The size of an IPv4 address in bits. - /// - /// # Examples - /// - /// ``` - /// #![feature(ip_bits)] - /// use std::net::Ipv4Addr; - /// - /// assert_eq!(Ipv4Addr::BITS, 32); - /// ``` - #[unstable(feature = "ip_bits", issue = "113744")] - pub const BITS: u32 = 32; - - /// Converts an IPv4 address into a `u32` representation using native byte order. - /// - /// Although IPv4 addresses are big-endian, the `u32` value will use the target platform's - /// native byte order. That is, the `u32` value is an integer representation of the IPv4 - /// address and not an integer interpretation of the IPv4 address's big-endian bitstring. This - /// means that the `u32` value masked with `0xffffff00` will set the last octet in the address - /// to 0, regardless of the target platform's endianness. - /// - /// # Examples - /// - /// ``` - /// #![feature(ip_bits)] - /// use std::net::Ipv4Addr; - /// - /// let addr = Ipv4Addr::new(0x12, 0x34, 0x56, 0x78); - /// assert_eq!(0x12345678, addr.to_bits()); - /// ``` - /// - /// ``` - /// #![feature(ip_bits)] - /// use std::net::Ipv4Addr; - /// - /// let addr = Ipv4Addr::new(0x12, 0x34, 0x56, 0x78); - /// let addr_bits = addr.to_bits() & 0xffffff00; - /// assert_eq!(Ipv4Addr::new(0x12, 0x34, 0x56, 0x00), Ipv4Addr::from_bits(addr_bits)); - /// - /// ``` - #[rustc_const_unstable(feature = "ip_bits", issue = "113744")] - #[unstable(feature = "ip_bits", issue = "113744")] - #[must_use] - #[inline] - pub const fn to_bits(self) -> u32 { - u32::from_be_bytes(self.octets) - } - - /// Converts a native byte order `u32` into an IPv4 address. - /// - /// See [`Ipv4Addr::to_bits`] for an explanation on endianness. - /// - /// # Examples - /// - /// ``` - /// #![feature(ip_bits)] - /// use std::net::Ipv4Addr; - /// - /// let addr = Ipv4Addr::from(0x12345678); - /// assert_eq!(Ipv4Addr::new(0x12, 0x34, 0x56, 0x78), addr); - /// ``` - #[rustc_const_unstable(feature = "ip_bits", issue = "113744")] - #[unstable(feature = "ip_bits", issue = "113744")] - #[must_use] - #[inline] - pub const fn from_bits(bits: u32) -> Ipv4Addr { - Ipv4Addr { octets: bits.to_be_bytes() } - } - - /// An IPv4 address with the address pointing to localhost: `127.0.0.1` - /// - /// # Examples - /// - /// ``` - /// use std::net::Ipv4Addr; - /// - /// let addr = Ipv4Addr::LOCALHOST; - /// assert_eq!(addr, Ipv4Addr::new(127, 0, 0, 1)); - /// ``` - #[stable(feature = "ip_constructors", since = "1.30.0")] - pub const LOCALHOST: Self = Ipv4Addr::new(127, 0, 0, 1); - - /// An IPv4 address representing an unspecified address: `0.0.0.0` - /// - /// This corresponds to the constant `INADDR_ANY` in other languages. - /// - /// # Examples - /// - /// ``` - /// use std::net::Ipv4Addr; - /// - /// let addr = Ipv4Addr::UNSPECIFIED; - /// assert_eq!(addr, Ipv4Addr::new(0, 0, 0, 0)); - /// ``` - #[doc(alias = "INADDR_ANY")] - #[stable(feature = "ip_constructors", since = "1.30.0")] - pub const UNSPECIFIED: Self = Ipv4Addr::new(0, 0, 0, 0); - - /// An IPv4 address representing the broadcast address: `255.255.255.255` - /// - /// # Examples - /// - /// ``` - /// use std::net::Ipv4Addr; - /// - /// let addr = Ipv4Addr::BROADCAST; - /// assert_eq!(addr, Ipv4Addr::new(255, 255, 255, 255)); - /// ``` - #[stable(feature = "ip_constructors", since = "1.30.0")] - pub const BROADCAST: Self = Ipv4Addr::new(255, 255, 255, 255); - - /// Returns the four eight-bit integers that make up this address. - /// - /// # Examples - /// - /// ``` - /// use std::net::Ipv4Addr; - /// - /// let addr = Ipv4Addr::new(127, 0, 0, 1); - /// assert_eq!(addr.octets(), [127, 0, 0, 1]); - /// ``` - #[rustc_const_stable(feature = "const_ip_50", since = "1.50.0")] - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - #[inline] - pub const fn octets(&self) -> [u8; 4] { - self.octets - } - - /// Returns [`true`] for the special 'unspecified' address (`0.0.0.0`). - /// - /// This property is defined in _UNIX Network Programming, Second Edition_, - /// W. Richard Stevens, p. 891; see also [ip7]. - /// - /// [ip7]: https://man7.org/linux/man-pages/man7/ip.7.html - /// - /// # Examples - /// - /// ``` - /// use std::net::Ipv4Addr; - /// - /// assert_eq!(Ipv4Addr::new(0, 0, 0, 0).is_unspecified(), true); - /// assert_eq!(Ipv4Addr::new(45, 22, 13, 197).is_unspecified(), false); - /// ``` - #[rustc_const_stable(feature = "const_ip_32", since = "1.32.0")] - #[stable(feature = "ip_shared", since = "1.12.0")] - #[must_use] - #[inline] - pub const fn is_unspecified(&self) -> bool { - u32::from_be_bytes(self.octets) == 0 - } - - /// Returns [`true`] if this is a loopback address (`127.0.0.0/8`). - /// - /// This property is defined by [IETF RFC 1122]. - /// - /// [IETF RFC 1122]: https://tools.ietf.org/html/rfc1122 - /// - /// # Examples - /// - /// ``` - /// use std::net::Ipv4Addr; - /// - /// assert_eq!(Ipv4Addr::new(127, 0, 0, 1).is_loopback(), true); - /// assert_eq!(Ipv4Addr::new(45, 22, 13, 197).is_loopback(), false); - /// ``` - #[rustc_const_stable(feature = "const_ip_50", since = "1.50.0")] - #[stable(since = "1.7.0", feature = "ip_17")] - #[must_use] - #[inline] - pub const fn is_loopback(&self) -> bool { - self.octets()[0] == 127 - } - - /// Returns [`true`] if this is a private address. - /// - /// The private address ranges are defined in [IETF RFC 1918] and include: - /// - /// - `10.0.0.0/8` - /// - `172.16.0.0/12` - /// - `192.168.0.0/16` - /// - /// [IETF RFC 1918]: https://tools.ietf.org/html/rfc1918 - /// - /// # Examples - /// - /// ``` - /// use std::net::Ipv4Addr; - /// - /// assert_eq!(Ipv4Addr::new(10, 0, 0, 1).is_private(), true); - /// assert_eq!(Ipv4Addr::new(10, 10, 10, 10).is_private(), true); - /// assert_eq!(Ipv4Addr::new(172, 16, 10, 10).is_private(), true); - /// assert_eq!(Ipv4Addr::new(172, 29, 45, 14).is_private(), true); - /// assert_eq!(Ipv4Addr::new(172, 32, 0, 2).is_private(), false); - /// assert_eq!(Ipv4Addr::new(192, 168, 0, 2).is_private(), true); - /// assert_eq!(Ipv4Addr::new(192, 169, 0, 2).is_private(), false); - /// ``` - #[rustc_const_stable(feature = "const_ip_50", since = "1.50.0")] - #[stable(since = "1.7.0", feature = "ip_17")] - #[must_use] - #[inline] - pub const fn is_private(&self) -> bool { - match self.octets() { - [10, ..] => true, - [172, b, ..] if b >= 16 && b <= 31 => true, - [192, 168, ..] => true, - _ => false, - } - } - - /// Returns [`true`] if the address is link-local (`169.254.0.0/16`). - /// - /// This property is defined by [IETF RFC 3927]. - /// - /// [IETF RFC 3927]: https://tools.ietf.org/html/rfc3927 - /// - /// # Examples - /// - /// ``` - /// use std::net::Ipv4Addr; - /// - /// assert_eq!(Ipv4Addr::new(169, 254, 0, 0).is_link_local(), true); - /// assert_eq!(Ipv4Addr::new(169, 254, 10, 65).is_link_local(), true); - /// assert_eq!(Ipv4Addr::new(16, 89, 10, 65).is_link_local(), false); - /// ``` - #[rustc_const_stable(feature = "const_ip_50", since = "1.50.0")] - #[stable(since = "1.7.0", feature = "ip_17")] - #[must_use] - #[inline] - pub const fn is_link_local(&self) -> bool { - matches!(self.octets(), [169, 254, ..]) - } - - /// Returns [`true`] if the address appears to be globally reachable - /// as specified by the [IANA IPv4 Special-Purpose Address Registry]. - /// Whether or not an address is practically reachable will depend on your network configuration. - /// - /// Most IPv4 addresses are globally reachable; - /// unless they are specifically defined as *not* globally reachable. - /// - /// Non-exhaustive list of notable addresses that are not globally reachable: - /// - /// - The [unspecified address] ([`is_unspecified`](Ipv4Addr::is_unspecified)) - /// - Addresses reserved for private use ([`is_private`](Ipv4Addr::is_private)) - /// - Addresses in the shared address space ([`is_shared`](Ipv4Addr::is_shared)) - /// - Loopback addresses ([`is_loopback`](Ipv4Addr::is_loopback)) - /// - Link-local addresses ([`is_link_local`](Ipv4Addr::is_link_local)) - /// - Addresses reserved for documentation ([`is_documentation`](Ipv4Addr::is_documentation)) - /// - Addresses reserved for benchmarking ([`is_benchmarking`](Ipv4Addr::is_benchmarking)) - /// - Reserved addresses ([`is_reserved`](Ipv4Addr::is_reserved)) - /// - The [broadcast address] ([`is_broadcast`](Ipv4Addr::is_broadcast)) - /// - /// For the complete overview of which addresses are globally reachable, see the table at the [IANA IPv4 Special-Purpose Address Registry]. - /// - /// [IANA IPv4 Special-Purpose Address Registry]: https://www.iana.org/assignments/iana-ipv4-special-registry/iana-ipv4-special-registry.xhtml - /// [unspecified address]: Ipv4Addr::UNSPECIFIED - /// [broadcast address]: Ipv4Addr::BROADCAST - - /// - /// # Examples - /// - /// ``` - /// #![feature(ip)] - /// - /// use std::net::Ipv4Addr; - /// - /// // Most IPv4 addresses are globally reachable: - /// assert_eq!(Ipv4Addr::new(80, 9, 12, 3).is_global(), true); - /// - /// // However some addresses have been assigned a special meaning - /// // that makes them not globally reachable. Some examples are: - /// - /// // The unspecified address (`0.0.0.0`) - /// assert_eq!(Ipv4Addr::UNSPECIFIED.is_global(), false); - /// - /// // Addresses reserved for private use (`10.0.0.0/8`, `172.16.0.0/12`, 192.168.0.0/16) - /// assert_eq!(Ipv4Addr::new(10, 254, 0, 0).is_global(), false); - /// assert_eq!(Ipv4Addr::new(192, 168, 10, 65).is_global(), false); - /// assert_eq!(Ipv4Addr::new(172, 16, 10, 65).is_global(), false); - /// - /// // Addresses in the shared address space (`100.64.0.0/10`) - /// assert_eq!(Ipv4Addr::new(100, 100, 0, 0).is_global(), false); - /// - /// // The loopback addresses (`127.0.0.0/8`) - /// assert_eq!(Ipv4Addr::LOCALHOST.is_global(), false); - /// - /// // Link-local addresses (`169.254.0.0/16`) - /// assert_eq!(Ipv4Addr::new(169, 254, 45, 1).is_global(), false); - /// - /// // Addresses reserved for documentation (`192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`) - /// assert_eq!(Ipv4Addr::new(192, 0, 2, 255).is_global(), false); - /// assert_eq!(Ipv4Addr::new(198, 51, 100, 65).is_global(), false); - /// assert_eq!(Ipv4Addr::new(203, 0, 113, 6).is_global(), false); - /// - /// // Addresses reserved for benchmarking (`198.18.0.0/15`) - /// assert_eq!(Ipv4Addr::new(198, 18, 0, 0).is_global(), false); - /// - /// // Reserved addresses (`240.0.0.0/4`) - /// assert_eq!(Ipv4Addr::new(250, 10, 20, 30).is_global(), false); - /// - /// // The broadcast address (`255.255.255.255`) - /// assert_eq!(Ipv4Addr::BROADCAST.is_global(), false); - /// - /// // For a complete overview see the IANA IPv4 Special-Purpose Address Registry. - /// ``` - #[rustc_const_unstable(feature = "const_ipv4", issue = "76205")] - #[unstable(feature = "ip", issue = "27709")] - #[must_use] - #[inline] - pub const fn is_global(&self) -> bool { - !(self.octets()[0] == 0 // "This network" - || self.is_private() - || self.is_shared() - || self.is_loopback() - || self.is_link_local() - // addresses reserved for future protocols (`192.0.0.0/24`) - // .9 and .10 are documented as globally reachable so they're excluded - || ( - self.octets()[0] == 192 && self.octets()[1] == 0 && self.octets()[2] == 0 - && self.octets()[3] != 9 && self.octets()[3] != 10 - ) - || self.is_documentation() - || self.is_benchmarking() - || self.is_reserved() - || self.is_broadcast()) - } - - /// Returns [`true`] if this address is part of the Shared Address Space defined in - /// [IETF RFC 6598] (`100.64.0.0/10`). - /// - /// [IETF RFC 6598]: https://tools.ietf.org/html/rfc6598 - /// - /// # Examples - /// - /// ``` - /// #![feature(ip)] - /// use std::net::Ipv4Addr; - /// - /// assert_eq!(Ipv4Addr::new(100, 64, 0, 0).is_shared(), true); - /// assert_eq!(Ipv4Addr::new(100, 127, 255, 255).is_shared(), true); - /// assert_eq!(Ipv4Addr::new(100, 128, 0, 0).is_shared(), false); - /// ``` - #[rustc_const_unstable(feature = "const_ipv4", issue = "76205")] - #[unstable(feature = "ip", issue = "27709")] - #[must_use] - #[inline] - pub const fn is_shared(&self) -> bool { - self.octets()[0] == 100 && (self.octets()[1] & 0b1100_0000 == 0b0100_0000) - } - - /// Returns [`true`] if this address part of the `198.18.0.0/15` range, which is reserved for - /// network devices benchmarking. This range is defined in [IETF RFC 2544] as `192.18.0.0` - /// through `198.19.255.255` but [errata 423] corrects it to `198.18.0.0/15`. - /// - /// [IETF RFC 2544]: https://tools.ietf.org/html/rfc2544 - /// [errata 423]: https://www.rfc-editor.org/errata/eid423 - /// - /// # Examples - /// - /// ``` - /// #![feature(ip)] - /// use std::net::Ipv4Addr; - /// - /// assert_eq!(Ipv4Addr::new(198, 17, 255, 255).is_benchmarking(), false); - /// assert_eq!(Ipv4Addr::new(198, 18, 0, 0).is_benchmarking(), true); - /// assert_eq!(Ipv4Addr::new(198, 19, 255, 255).is_benchmarking(), true); - /// assert_eq!(Ipv4Addr::new(198, 20, 0, 0).is_benchmarking(), false); - /// ``` - #[rustc_const_unstable(feature = "const_ipv4", issue = "76205")] - #[unstable(feature = "ip", issue = "27709")] - #[must_use] - #[inline] - pub const fn is_benchmarking(&self) -> bool { - self.octets()[0] == 198 && (self.octets()[1] & 0xfe) == 18 - } - - /// Returns [`true`] if this address is reserved by IANA for future use. [IETF RFC 1112] - /// defines the block of reserved addresses as `240.0.0.0/4`. This range normally includes the - /// broadcast address `255.255.255.255`, but this implementation explicitly excludes it, since - /// it is obviously not reserved for future use. - /// - /// [IETF RFC 1112]: https://tools.ietf.org/html/rfc1112 - /// - /// # Warning - /// - /// As IANA assigns new addresses, this method will be - /// updated. This may result in non-reserved addresses being - /// treated as reserved in code that relies on an outdated version - /// of this method. - /// - /// # Examples - /// - /// ``` - /// #![feature(ip)] - /// use std::net::Ipv4Addr; - /// - /// assert_eq!(Ipv4Addr::new(240, 0, 0, 0).is_reserved(), true); - /// assert_eq!(Ipv4Addr::new(255, 255, 255, 254).is_reserved(), true); - /// - /// assert_eq!(Ipv4Addr::new(239, 255, 255, 255).is_reserved(), false); - /// // The broadcast address is not considered as reserved for future use by this implementation - /// assert_eq!(Ipv4Addr::new(255, 255, 255, 255).is_reserved(), false); - /// ``` - #[rustc_const_unstable(feature = "const_ipv4", issue = "76205")] - #[unstable(feature = "ip", issue = "27709")] - #[must_use] - #[inline] - pub const fn is_reserved(&self) -> bool { - self.octets()[0] & 240 == 240 && !self.is_broadcast() - } - - /// Returns [`true`] if this is a multicast address (`224.0.0.0/4`). - /// - /// Multicast addresses have a most significant octet between `224` and `239`, - /// and is defined by [IETF RFC 5771]. - /// - /// [IETF RFC 5771]: https://tools.ietf.org/html/rfc5771 - /// - /// # Examples - /// - /// ``` - /// use std::net::Ipv4Addr; - /// - /// assert_eq!(Ipv4Addr::new(224, 254, 0, 0).is_multicast(), true); - /// assert_eq!(Ipv4Addr::new(236, 168, 10, 65).is_multicast(), true); - /// assert_eq!(Ipv4Addr::new(172, 16, 10, 65).is_multicast(), false); - /// ``` - #[rustc_const_stable(feature = "const_ip_50", since = "1.50.0")] - #[stable(since = "1.7.0", feature = "ip_17")] - #[must_use] - #[inline] - pub const fn is_multicast(&self) -> bool { - self.octets()[0] >= 224 && self.octets()[0] <= 239 - } - - /// Returns [`true`] if this is a broadcast address (`255.255.255.255`). - /// - /// A broadcast address has all octets set to `255` as defined in [IETF RFC 919]. - /// - /// [IETF RFC 919]: https://tools.ietf.org/html/rfc919 - /// - /// # Examples - /// - /// ``` - /// use std::net::Ipv4Addr; - /// - /// assert_eq!(Ipv4Addr::new(255, 255, 255, 255).is_broadcast(), true); - /// assert_eq!(Ipv4Addr::new(236, 168, 10, 65).is_broadcast(), false); - /// ``` - #[rustc_const_stable(feature = "const_ip_50", since = "1.50.0")] - #[stable(since = "1.7.0", feature = "ip_17")] - #[must_use] - #[inline] - pub const fn is_broadcast(&self) -> bool { - u32::from_be_bytes(self.octets()) == u32::from_be_bytes(Self::BROADCAST.octets()) - } - - /// Returns [`true`] if this address is in a range designated for documentation. - /// - /// This is defined in [IETF RFC 5737]: - /// - /// - `192.0.2.0/24` (TEST-NET-1) - /// - `198.51.100.0/24` (TEST-NET-2) - /// - `203.0.113.0/24` (TEST-NET-3) - /// - /// [IETF RFC 5737]: https://tools.ietf.org/html/rfc5737 - /// - /// # Examples - /// - /// ``` - /// use std::net::Ipv4Addr; - /// - /// assert_eq!(Ipv4Addr::new(192, 0, 2, 255).is_documentation(), true); - /// assert_eq!(Ipv4Addr::new(198, 51, 100, 65).is_documentation(), true); - /// assert_eq!(Ipv4Addr::new(203, 0, 113, 6).is_documentation(), true); - /// assert_eq!(Ipv4Addr::new(193, 34, 17, 19).is_documentation(), false); - /// ``` - #[rustc_const_stable(feature = "const_ip_50", since = "1.50.0")] - #[stable(since = "1.7.0", feature = "ip_17")] - #[must_use] - #[inline] - pub const fn is_documentation(&self) -> bool { - matches!(self.octets(), [192, 0, 2, _] | [198, 51, 100, _] | [203, 0, 113, _]) - } - - /// Converts this address to an [IPv4-compatible] [`IPv6` address]. - /// - /// `a.b.c.d` becomes `::a.b.c.d` - /// - /// Note that IPv4-compatible addresses have been officially deprecated. - /// If you don't explicitly need an IPv4-compatible address for legacy reasons, consider using `to_ipv6_mapped` instead. - /// - /// [IPv4-compatible]: Ipv6Addr#ipv4-compatible-ipv6-addresses - /// [`IPv6` address]: Ipv6Addr - /// - /// # Examples - /// - /// ``` - /// use std::net::{Ipv4Addr, Ipv6Addr}; - /// - /// assert_eq!( - /// Ipv4Addr::new(192, 0, 2, 255).to_ipv6_compatible(), - /// Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0xc000, 0x2ff) - /// ); - /// ``` - #[rustc_const_stable(feature = "const_ip_50", since = "1.50.0")] - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn to_ipv6_compatible(&self) -> Ipv6Addr { - let [a, b, c, d] = self.octets(); - Ipv6Addr { octets: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, a, b, c, d] } - } - - /// Converts this address to an [IPv4-mapped] [`IPv6` address]. - /// - /// `a.b.c.d` becomes `::ffff:a.b.c.d` - /// - /// [IPv4-mapped]: Ipv6Addr#ipv4-mapped-ipv6-addresses - /// [`IPv6` address]: Ipv6Addr - /// - /// # Examples - /// - /// ``` - /// use std::net::{Ipv4Addr, Ipv6Addr}; - /// - /// assert_eq!(Ipv4Addr::new(192, 0, 2, 255).to_ipv6_mapped(), - /// Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc000, 0x2ff)); - /// ``` - #[rustc_const_stable(feature = "const_ip_50", since = "1.50.0")] - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn to_ipv6_mapped(&self) -> Ipv6Addr { - let [a, b, c, d] = self.octets(); - Ipv6Addr { octets: [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0xFF, 0xFF, a, b, c, d] } - } -} - -#[stable(feature = "ip_addr", since = "1.7.0")] -impl fmt::Display for IpAddr { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - match self { - IpAddr::V4(ip) => ip.fmt(fmt), - IpAddr::V6(ip) => ip.fmt(fmt), - } - } -} - -#[stable(feature = "ip_addr", since = "1.7.0")] -impl fmt::Debug for IpAddr { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt(self, fmt) - } -} - -#[stable(feature = "ip_from_ip", since = "1.16.0")] -impl From for IpAddr { - /// Copies this address to a new `IpAddr::V4`. - /// - /// # Examples - /// - /// ``` - /// use std::net::{IpAddr, Ipv4Addr}; - /// - /// let addr = Ipv4Addr::new(127, 0, 0, 1); - /// - /// assert_eq!( - /// IpAddr::V4(addr), - /// IpAddr::from(addr) - /// ) - /// ``` - #[inline] - fn from(ipv4: Ipv4Addr) -> IpAddr { - IpAddr::V4(ipv4) - } -} - -#[stable(feature = "ip_from_ip", since = "1.16.0")] -impl From for IpAddr { - /// Copies this address to a new `IpAddr::V6`. - /// - /// # Examples - /// - /// ``` - /// use std::net::{IpAddr, Ipv6Addr}; - /// - /// let addr = Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff); - /// - /// assert_eq!( - /// IpAddr::V6(addr), - /// IpAddr::from(addr) - /// ); - /// ``` - #[inline] - fn from(ipv6: Ipv6Addr) -> IpAddr { - IpAddr::V6(ipv6) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for Ipv4Addr { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - let octets = self.octets(); - - // If there are no alignment requirements, write the IP address directly to `f`. - // Otherwise, write it to a local buffer and then use `f.pad`. - if fmt.precision().is_none() && fmt.width().is_none() { - write!(fmt, "{}.{}.{}.{}", octets[0], octets[1], octets[2], octets[3]) - } else { - const LONGEST_IPV4_ADDR: &str = "255.255.255.255"; - - let mut buf = DisplayBuffer::<{ LONGEST_IPV4_ADDR.len() }>::new(); - // Buffer is long enough for the longest possible IPv4 address, so this should never fail. - write!(buf, "{}.{}.{}.{}", octets[0], octets[1], octets[2], octets[3]).unwrap(); - - fmt.pad(buf.as_str()) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for Ipv4Addr { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt(self, fmt) - } -} - -#[stable(feature = "ip_cmp", since = "1.16.0")] -impl PartialEq for IpAddr { - #[inline] - fn eq(&self, other: &Ipv4Addr) -> bool { - match self { - IpAddr::V4(v4) => v4 == other, - IpAddr::V6(_) => false, - } - } -} - -#[stable(feature = "ip_cmp", since = "1.16.0")] -impl PartialEq for Ipv4Addr { - #[inline] - fn eq(&self, other: &IpAddr) -> bool { - match other { - IpAddr::V4(v4) => self == v4, - IpAddr::V6(_) => false, - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialOrd for Ipv4Addr { - #[inline] - fn partial_cmp(&self, other: &Ipv4Addr) -> Option { - Some(self.cmp(other)) - } -} - -#[stable(feature = "ip_cmp", since = "1.16.0")] -impl PartialOrd for IpAddr { - #[inline] - fn partial_cmp(&self, other: &Ipv4Addr) -> Option { - match self { - IpAddr::V4(v4) => v4.partial_cmp(other), - IpAddr::V6(_) => Some(Ordering::Greater), - } - } -} - -#[stable(feature = "ip_cmp", since = "1.16.0")] -impl PartialOrd for Ipv4Addr { - #[inline] - fn partial_cmp(&self, other: &IpAddr) -> Option { - match other { - IpAddr::V4(v4) => self.partial_cmp(v4), - IpAddr::V6(_) => Some(Ordering::Less), - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for Ipv4Addr { - #[inline] - fn cmp(&self, other: &Ipv4Addr) -> Ordering { - self.octets.cmp(&other.octets) - } -} - -#[stable(feature = "ip_u32", since = "1.1.0")] -impl From for u32 { - /// Uses [`Ipv4Addr::to_bits`] to convert an IPv4 address to a host byte order `u32`. - #[inline] - fn from(ip: Ipv4Addr) -> u32 { - ip.to_bits() - } -} - -#[stable(feature = "ip_u32", since = "1.1.0")] -impl From for Ipv4Addr { - /// Uses [`Ipv4Addr::from_bits`] to convert a host byte order `u32` into an IPv4 address. - #[inline] - fn from(ip: u32) -> Ipv4Addr { - Ipv4Addr::from_bits(ip) - } -} - -#[stable(feature = "from_slice_v4", since = "1.9.0")] -impl From<[u8; 4]> for Ipv4Addr { - /// Creates an `Ipv4Addr` from a four element byte array. - /// - /// # Examples - /// - /// ``` - /// use std::net::Ipv4Addr; - /// - /// let addr = Ipv4Addr::from([13u8, 12u8, 11u8, 10u8]); - /// assert_eq!(Ipv4Addr::new(13, 12, 11, 10), addr); - /// ``` - #[inline] - fn from(octets: [u8; 4]) -> Ipv4Addr { - Ipv4Addr { octets } - } -} - -#[stable(feature = "ip_from_slice", since = "1.17.0")] -impl From<[u8; 4]> for IpAddr { - /// Creates an `IpAddr::V4` from a four element byte array. - /// - /// # Examples - /// - /// ``` - /// use std::net::{IpAddr, Ipv4Addr}; - /// - /// let addr = IpAddr::from([13u8, 12u8, 11u8, 10u8]); - /// assert_eq!(IpAddr::V4(Ipv4Addr::new(13, 12, 11, 10)), addr); - /// ``` - #[inline] - fn from(octets: [u8; 4]) -> IpAddr { - IpAddr::V4(Ipv4Addr::from(octets)) - } -} - -impl Ipv6Addr { - /// Creates a new IPv6 address from eight 16-bit segments. - /// - /// The result will represent the IP address `a:b:c:d:e:f:g:h`. - /// - /// # Examples - /// - /// ``` - /// use std::net::Ipv6Addr; - /// - /// let addr = Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff); - /// ``` - #[rustc_const_stable(feature = "const_ip_32", since = "1.32.0")] - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - #[inline] - pub const fn new(a: u16, b: u16, c: u16, d: u16, e: u16, f: u16, g: u16, h: u16) -> Ipv6Addr { - let addr16 = [ - a.to_be(), - b.to_be(), - c.to_be(), - d.to_be(), - e.to_be(), - f.to_be(), - g.to_be(), - h.to_be(), - ]; - Ipv6Addr { - // All elements in `addr16` are big endian. - // SAFETY: `[u16; 8]` is always safe to transmute to `[u8; 16]`. - octets: unsafe { transmute::<_, [u8; 16]>(addr16) }, - } - } - - /// The size of an IPv6 address in bits. - /// - /// # Examples - /// - /// ``` - /// #![feature(ip_bits)] - /// use std::net::Ipv6Addr; - /// - /// assert_eq!(Ipv6Addr::BITS, 128); - /// ``` - #[unstable(feature = "ip_bits", issue = "113744")] - pub const BITS: u32 = 128; - - /// Converts an IPv6 address into a `u128` representation using native byte order. - /// - /// Although IPv6 addresses are big-endian, the `u128` value will use the target platform's - /// native byte order. That is, the `u128` value is an integer representation of the IPv6 - /// address and not an integer interpretation of the IPv6 address's big-endian bitstring. This - /// means that the `u128` value masked with `0xffffffffffffffffffffffffffff0000_u128` will set - /// the last segment in the address to 0, regardless of the target platform's endianness. - /// - /// # Examples - /// - /// ``` - /// #![feature(ip_bits)] - /// use std::net::Ipv6Addr; - /// - /// let addr = Ipv6Addr::new( - /// 0x1020, 0x3040, 0x5060, 0x7080, - /// 0x90A0, 0xB0C0, 0xD0E0, 0xF00D, - /// ); - /// assert_eq!(0x102030405060708090A0B0C0D0E0F00D_u128, u128::from(addr)); - /// ``` - /// - /// ``` - /// #![feature(ip_bits)] - /// use std::net::Ipv6Addr; - /// - /// let addr = Ipv6Addr::new( - /// 0x1020, 0x3040, 0x5060, 0x7080, - /// 0x90A0, 0xB0C0, 0xD0E0, 0xF00D, - /// ); - /// let addr_bits = addr.to_bits() & 0xffffffffffffffffffffffffffff0000_u128; - /// assert_eq!( - /// Ipv6Addr::new( - /// 0x1020, 0x3040, 0x5060, 0x7080, - /// 0x90A0, 0xB0C0, 0xD0E0, 0x0000, - /// ), - /// Ipv6Addr::from_bits(addr_bits)); - /// - /// ``` - #[rustc_const_unstable(feature = "ip_bits", issue = "113744")] - #[unstable(feature = "ip_bits", issue = "113744")] - #[must_use] - #[inline] - pub const fn to_bits(self) -> u128 { - u128::from_be_bytes(self.octets) - } - - /// Converts a native byte order `u128` into an IPv6 address. - /// - /// See [`Ipv6Addr::to_bits`] for an explanation on endianness. - /// - /// # Examples - /// - /// ``` - /// #![feature(ip_bits)] - /// use std::net::Ipv6Addr; - /// - /// let addr = Ipv6Addr::from(0x102030405060708090A0B0C0D0E0F00D_u128); - /// assert_eq!( - /// Ipv6Addr::new( - /// 0x1020, 0x3040, 0x5060, 0x7080, - /// 0x90A0, 0xB0C0, 0xD0E0, 0xF00D, - /// ), - /// addr); - /// ``` - #[rustc_const_unstable(feature = "ip_bits", issue = "113744")] - #[unstable(feature = "ip_bits", issue = "113744")] - #[must_use] - #[inline] - pub const fn from_bits(bits: u128) -> Ipv6Addr { - Ipv6Addr { octets: bits.to_be_bytes() } - } - - /// An IPv6 address representing localhost: `::1`. - /// - /// This corresponds to constant `IN6ADDR_LOOPBACK_INIT` or `in6addr_loopback` in other - /// languages. - /// - /// # Examples - /// - /// ``` - /// use std::net::Ipv6Addr; - /// - /// let addr = Ipv6Addr::LOCALHOST; - /// assert_eq!(addr, Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1)); - /// ``` - #[doc(alias = "IN6ADDR_LOOPBACK_INIT")] - #[doc(alias = "in6addr_loopback")] - #[stable(feature = "ip_constructors", since = "1.30.0")] - pub const LOCALHOST: Self = Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1); - - /// An IPv6 address representing the unspecified address: `::` - /// - /// This corresponds to constant `IN6ADDR_ANY_INIT` or `in6addr_any` in other languages. - /// - /// # Examples - /// - /// ``` - /// use std::net::Ipv6Addr; - /// - /// let addr = Ipv6Addr::UNSPECIFIED; - /// assert_eq!(addr, Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0)); - /// ``` - #[doc(alias = "IN6ADDR_ANY_INIT")] - #[doc(alias = "in6addr_any")] - #[stable(feature = "ip_constructors", since = "1.30.0")] - pub const UNSPECIFIED: Self = Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0); - - /// Returns the eight 16-bit segments that make up this address. - /// - /// # Examples - /// - /// ``` - /// use std::net::Ipv6Addr; - /// - /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).segments(), - /// [0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff]); - /// ``` - #[rustc_const_stable(feature = "const_ip_50", since = "1.50.0")] - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - #[inline] - pub const fn segments(&self) -> [u16; 8] { - // All elements in `self.octets` must be big endian. - // SAFETY: `[u8; 16]` is always safe to transmute to `[u16; 8]`. - let [a, b, c, d, e, f, g, h] = unsafe { transmute::<_, [u16; 8]>(self.octets) }; - // We want native endian u16 - [ - u16::from_be(a), - u16::from_be(b), - u16::from_be(c), - u16::from_be(d), - u16::from_be(e), - u16::from_be(f), - u16::from_be(g), - u16::from_be(h), - ] - } - - /// Returns [`true`] for the special 'unspecified' address (`::`). - /// - /// This property is defined in [IETF RFC 4291]. - /// - /// [IETF RFC 4291]: https://tools.ietf.org/html/rfc4291 - /// - /// # Examples - /// - /// ``` - /// use std::net::Ipv6Addr; - /// - /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_unspecified(), false); - /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0).is_unspecified(), true); - /// ``` - #[rustc_const_stable(feature = "const_ip_50", since = "1.50.0")] - #[stable(since = "1.7.0", feature = "ip_17")] - #[must_use] - #[inline] - pub const fn is_unspecified(&self) -> bool { - u128::from_be_bytes(self.octets()) == u128::from_be_bytes(Ipv6Addr::UNSPECIFIED.octets()) - } - - /// Returns [`true`] if this is the [loopback address] (`::1`), - /// as defined in [IETF RFC 4291 section 2.5.3]. - /// - /// Contrary to IPv4, in IPv6 there is only one loopback address. - /// - /// [loopback address]: Ipv6Addr::LOCALHOST - /// [IETF RFC 4291 section 2.5.3]: https://tools.ietf.org/html/rfc4291#section-2.5.3 - /// - /// # Examples - /// - /// ``` - /// use std::net::Ipv6Addr; - /// - /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_loopback(), false); - /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0x1).is_loopback(), true); - /// ``` - #[rustc_const_stable(feature = "const_ip_50", since = "1.50.0")] - #[stable(since = "1.7.0", feature = "ip_17")] - #[must_use] - #[inline] - pub const fn is_loopback(&self) -> bool { - u128::from_be_bytes(self.octets()) == u128::from_be_bytes(Ipv6Addr::LOCALHOST.octets()) - } - - /// Returns [`true`] if the address appears to be globally reachable - /// as specified by the [IANA IPv6 Special-Purpose Address Registry]. - /// Whether or not an address is practically reachable will depend on your network configuration. - /// - /// Most IPv6 addresses are globally reachable; - /// unless they are specifically defined as *not* globally reachable. - /// - /// Non-exhaustive list of notable addresses that are not globally reachable: - /// - The [unspecified address] ([`is_unspecified`](Ipv6Addr::is_unspecified)) - /// - The [loopback address] ([`is_loopback`](Ipv6Addr::is_loopback)) - /// - IPv4-mapped addresses - /// - Addresses reserved for benchmarking ([`is_benchmarking`](Ipv6Addr::is_benchmarking)) - /// - Addresses reserved for documentation ([`is_documentation`](Ipv6Addr::is_documentation)) - /// - Unique local addresses ([`is_unique_local`](Ipv6Addr::is_unique_local)) - /// - Unicast addresses with link-local scope ([`is_unicast_link_local`](Ipv6Addr::is_unicast_link_local)) - /// - /// For the complete overview of which addresses are globally reachable, see the table at the [IANA IPv6 Special-Purpose Address Registry]. - /// - /// Note that an address having global scope is not the same as being globally reachable, - /// and there is no direct relation between the two concepts: There exist addresses with global scope - /// that are not globally reachable (for example unique local addresses), - /// and addresses that are globally reachable without having global scope - /// (multicast addresses with non-global scope). - /// - /// [IANA IPv6 Special-Purpose Address Registry]: https://www.iana.org/assignments/iana-ipv6-special-registry/iana-ipv6-special-registry.xhtml - /// [unspecified address]: Ipv6Addr::UNSPECIFIED - /// [loopback address]: Ipv6Addr::LOCALHOST - /// - /// # Examples - /// - /// ``` - /// #![feature(ip)] - /// - /// use std::net::Ipv6Addr; - /// - /// // Most IPv6 addresses are globally reachable: - /// assert_eq!(Ipv6Addr::new(0x26, 0, 0x1c9, 0, 0, 0xafc8, 0x10, 0x1).is_global(), true); - /// - /// // However some addresses have been assigned a special meaning - /// // that makes them not globally reachable. Some examples are: - /// - /// // The unspecified address (`::`) - /// assert_eq!(Ipv6Addr::UNSPECIFIED.is_global(), false); - /// - /// // The loopback address (`::1`) - /// assert_eq!(Ipv6Addr::LOCALHOST.is_global(), false); - /// - /// // IPv4-mapped addresses (`::ffff:0:0/96`) - /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_global(), false); - /// - /// // Addresses reserved for benchmarking (`2001:2::/48`) - /// assert_eq!(Ipv6Addr::new(0x2001, 2, 0, 0, 0, 0, 0, 1,).is_global(), false); - /// - /// // Addresses reserved for documentation (`2001:db8::/32`) - /// assert_eq!(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1).is_global(), false); - /// - /// // Unique local addresses (`fc00::/7`) - /// assert_eq!(Ipv6Addr::new(0xfc02, 0, 0, 0, 0, 0, 0, 1).is_global(), false); - /// - /// // Unicast addresses with link-local scope (`fe80::/10`) - /// assert_eq!(Ipv6Addr::new(0xfe81, 0, 0, 0, 0, 0, 0, 1).is_global(), false); - /// - /// // For a complete overview see the IANA IPv6 Special-Purpose Address Registry. - /// ``` - #[rustc_const_unstable(feature = "const_ipv6", issue = "76205")] - #[unstable(feature = "ip", issue = "27709")] - #[must_use] - #[inline] - pub const fn is_global(&self) -> bool { - !(self.is_unspecified() - || self.is_loopback() - // IPv4-mapped Address (`::ffff:0:0/96`) - || matches!(self.segments(), [0, 0, 0, 0, 0, 0xffff, _, _]) - // IPv4-IPv6 Translat. (`64:ff9b:1::/48`) - || matches!(self.segments(), [0x64, 0xff9b, 1, _, _, _, _, _]) - // Discard-Only Address Block (`100::/64`) - || matches!(self.segments(), [0x100, 0, 0, 0, _, _, _, _]) - // IETF Protocol Assignments (`2001::/23`) - || (matches!(self.segments(), [0x2001, b, _, _, _, _, _, _] if b < 0x200) - && !( - // Port Control Protocol Anycast (`2001:1::1`) - u128::from_be_bytes(self.octets()) == 0x2001_0001_0000_0000_0000_0000_0000_0001 - // Traversal Using Relays around NAT Anycast (`2001:1::2`) - || u128::from_be_bytes(self.octets()) == 0x2001_0001_0000_0000_0000_0000_0000_0002 - // AMT (`2001:3::/32`) - || matches!(self.segments(), [0x2001, 3, _, _, _, _, _, _]) - // AS112-v6 (`2001:4:112::/48`) - || matches!(self.segments(), [0x2001, 4, 0x112, _, _, _, _, _]) - // ORCHIDv2 (`2001:20::/28`) - // Drone Remote ID Protocol Entity Tags (DETs) Prefix (`2001:30::/28`)` - || matches!(self.segments(), [0x2001, b, _, _, _, _, _, _] if b >= 0x20 && b <= 0x3F) - )) - // 6to4 (`2002::/16`) – it's not explicitly documented as globally reachable, - // IANA says N/A. - || matches!(self.segments(), [0x2002, _, _, _, _, _, _, _]) - || self.is_documentation() - || self.is_unique_local() - || self.is_unicast_link_local()) - } - - /// Returns [`true`] if this is a unique local address (`fc00::/7`). - /// - /// This property is defined in [IETF RFC 4193]. - /// - /// [IETF RFC 4193]: https://tools.ietf.org/html/rfc4193 - /// - /// # Examples - /// - /// ``` - /// #![feature(ip)] - /// - /// use std::net::Ipv6Addr; - /// - /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_unique_local(), false); - /// assert_eq!(Ipv6Addr::new(0xfc02, 0, 0, 0, 0, 0, 0, 0).is_unique_local(), true); - /// ``` - #[rustc_const_unstable(feature = "const_ipv6", issue = "76205")] - #[unstable(feature = "ip", issue = "27709")] - #[must_use] - #[inline] - pub const fn is_unique_local(&self) -> bool { - (self.segments()[0] & 0xfe00) == 0xfc00 - } - - /// Returns [`true`] if this is a unicast address, as defined by [IETF RFC 4291]. - /// Any address that is not a [multicast address] (`ff00::/8`) is unicast. - /// - /// [IETF RFC 4291]: https://tools.ietf.org/html/rfc4291 - /// [multicast address]: Ipv6Addr::is_multicast - /// - /// # Examples - /// - /// ``` - /// #![feature(ip)] - /// - /// use std::net::Ipv6Addr; - /// - /// // The unspecified and loopback addresses are unicast. - /// assert_eq!(Ipv6Addr::UNSPECIFIED.is_unicast(), true); - /// assert_eq!(Ipv6Addr::LOCALHOST.is_unicast(), true); - /// - /// // Any address that is not a multicast address (`ff00::/8`) is unicast. - /// assert_eq!(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0).is_unicast(), true); - /// assert_eq!(Ipv6Addr::new(0xff00, 0, 0, 0, 0, 0, 0, 0).is_unicast(), false); - /// ``` - #[rustc_const_unstable(feature = "const_ipv6", issue = "76205")] - #[unstable(feature = "ip", issue = "27709")] - #[must_use] - #[inline] - pub const fn is_unicast(&self) -> bool { - !self.is_multicast() - } - - /// Returns `true` if the address is a unicast address with link-local scope, - /// as defined in [RFC 4291]. - /// - /// A unicast address has link-local scope if it has the prefix `fe80::/10`, as per [RFC 4291 section 2.4]. - /// Note that this encompasses more addresses than those defined in [RFC 4291 section 2.5.6], - /// which describes "Link-Local IPv6 Unicast Addresses" as having the following stricter format: - /// - /// ```text - /// | 10 bits | 54 bits | 64 bits | - /// +----------+-------------------------+----------------------------+ - /// |1111111010| 0 | interface ID | - /// +----------+-------------------------+----------------------------+ - /// ``` - /// So while currently the only addresses with link-local scope an application will encounter are all in `fe80::/64`, - /// this might change in the future with the publication of new standards. More addresses in `fe80::/10` could be allocated, - /// and those addresses will have link-local scope. - /// - /// Also note that while [RFC 4291 section 2.5.3] mentions about the [loopback address] (`::1`) that "it is treated as having Link-Local scope", - /// this does not mean that the loopback address actually has link-local scope and this method will return `false` on it. - /// - /// [RFC 4291]: https://tools.ietf.org/html/rfc4291 - /// [RFC 4291 section 2.4]: https://tools.ietf.org/html/rfc4291#section-2.4 - /// [RFC 4291 section 2.5.3]: https://tools.ietf.org/html/rfc4291#section-2.5.3 - /// [RFC 4291 section 2.5.6]: https://tools.ietf.org/html/rfc4291#section-2.5.6 - /// [loopback address]: Ipv6Addr::LOCALHOST - /// - /// # Examples - /// - /// ``` - /// #![feature(ip)] - /// - /// use std::net::Ipv6Addr; - /// - /// // The loopback address (`::1`) does not actually have link-local scope. - /// assert_eq!(Ipv6Addr::LOCALHOST.is_unicast_link_local(), false); - /// - /// // Only addresses in `fe80::/10` have link-local scope. - /// assert_eq!(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0).is_unicast_link_local(), false); - /// assert_eq!(Ipv6Addr::new(0xfe80, 0, 0, 0, 0, 0, 0, 0).is_unicast_link_local(), true); - /// - /// // Addresses outside the stricter `fe80::/64` also have link-local scope. - /// assert_eq!(Ipv6Addr::new(0xfe80, 0, 0, 1, 0, 0, 0, 0).is_unicast_link_local(), true); - /// assert_eq!(Ipv6Addr::new(0xfe81, 0, 0, 0, 0, 0, 0, 0).is_unicast_link_local(), true); - /// ``` - #[rustc_const_unstable(feature = "const_ipv6", issue = "76205")] - #[unstable(feature = "ip", issue = "27709")] - #[must_use] - #[inline] - pub const fn is_unicast_link_local(&self) -> bool { - (self.segments()[0] & 0xffc0) == 0xfe80 - } - - /// Returns [`true`] if this is an address reserved for documentation - /// (`2001:db8::/32`). - /// - /// This property is defined in [IETF RFC 3849]. - /// - /// [IETF RFC 3849]: https://tools.ietf.org/html/rfc3849 - /// - /// # Examples - /// - /// ``` - /// #![feature(ip)] - /// - /// use std::net::Ipv6Addr; - /// - /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_documentation(), false); - /// assert_eq!(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0).is_documentation(), true); - /// ``` - #[rustc_const_unstable(feature = "const_ipv6", issue = "76205")] - #[unstable(feature = "ip", issue = "27709")] - #[must_use] - #[inline] - pub const fn is_documentation(&self) -> bool { - (self.segments()[0] == 0x2001) && (self.segments()[1] == 0xdb8) - } - - /// Returns [`true`] if this is an address reserved for benchmarking (`2001:2::/48`). - /// - /// This property is defined in [IETF RFC 5180], where it is mistakenly specified as covering the range `2001:0200::/48`. - /// This is corrected in [IETF RFC Errata 1752] to `2001:0002::/48`. - /// - /// [IETF RFC 5180]: https://tools.ietf.org/html/rfc5180 - /// [IETF RFC Errata 1752]: https://www.rfc-editor.org/errata_search.php?eid=1752 - /// - /// ``` - /// #![feature(ip)] - /// - /// use std::net::Ipv6Addr; - /// - /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc613, 0x0).is_benchmarking(), false); - /// assert_eq!(Ipv6Addr::new(0x2001, 0x2, 0, 0, 0, 0, 0, 0).is_benchmarking(), true); - /// ``` - #[unstable(feature = "ip", issue = "27709")] - #[must_use] - #[inline] - pub const fn is_benchmarking(&self) -> bool { - (self.segments()[0] == 0x2001) && (self.segments()[1] == 0x2) && (self.segments()[2] == 0) - } - - /// Returns [`true`] if the address is a globally routable unicast address. - /// - /// The following return false: - /// - /// - the loopback address - /// - the link-local addresses - /// - unique local addresses - /// - the unspecified address - /// - the address range reserved for documentation - /// - /// This method returns [`true`] for site-local addresses as per [RFC 4291 section 2.5.7] - /// - /// ```no_rust - /// The special behavior of [the site-local unicast] prefix defined in [RFC3513] must no longer - /// be supported in new implementations (i.e., new implementations must treat this prefix as - /// Global Unicast). - /// ``` - /// - /// [RFC 4291 section 2.5.7]: https://tools.ietf.org/html/rfc4291#section-2.5.7 - /// - /// # Examples - /// - /// ``` - /// #![feature(ip)] - /// - /// use std::net::Ipv6Addr; - /// - /// assert_eq!(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0).is_unicast_global(), false); - /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_unicast_global(), true); - /// ``` - #[rustc_const_unstable(feature = "const_ipv6", issue = "76205")] - #[unstable(feature = "ip", issue = "27709")] - #[must_use] - #[inline] - pub const fn is_unicast_global(&self) -> bool { - self.is_unicast() - && !self.is_loopback() - && !self.is_unicast_link_local() - && !self.is_unique_local() - && !self.is_unspecified() - && !self.is_documentation() - && !self.is_benchmarking() - } - - /// Returns the address's multicast scope if the address is multicast. - /// - /// # Examples - /// - /// ``` - /// #![feature(ip)] - /// - /// use std::net::{Ipv6Addr, Ipv6MulticastScope}; - /// - /// assert_eq!( - /// Ipv6Addr::new(0xff0e, 0, 0, 0, 0, 0, 0, 0).multicast_scope(), - /// Some(Ipv6MulticastScope::Global) - /// ); - /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).multicast_scope(), None); - /// ``` - #[rustc_const_unstable(feature = "const_ipv6", issue = "76205")] - #[unstable(feature = "ip", issue = "27709")] - #[must_use] - #[inline] - pub const fn multicast_scope(&self) -> Option { - if self.is_multicast() { - match self.segments()[0] & 0x000f { - 1 => Some(Ipv6MulticastScope::InterfaceLocal), - 2 => Some(Ipv6MulticastScope::LinkLocal), - 3 => Some(Ipv6MulticastScope::RealmLocal), - 4 => Some(Ipv6MulticastScope::AdminLocal), - 5 => Some(Ipv6MulticastScope::SiteLocal), - 8 => Some(Ipv6MulticastScope::OrganizationLocal), - 14 => Some(Ipv6MulticastScope::Global), - _ => None, - } - } else { - None - } - } - - /// Returns [`true`] if this is a multicast address (`ff00::/8`). - /// - /// This property is defined by [IETF RFC 4291]. - /// - /// [IETF RFC 4291]: https://tools.ietf.org/html/rfc4291 - /// - /// # Examples - /// - /// ``` - /// use std::net::Ipv6Addr; - /// - /// assert_eq!(Ipv6Addr::new(0xff00, 0, 0, 0, 0, 0, 0, 0).is_multicast(), true); - /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_multicast(), false); - /// ``` - #[rustc_const_stable(feature = "const_ip_50", since = "1.50.0")] - #[stable(since = "1.7.0", feature = "ip_17")] - #[must_use] - #[inline] - pub const fn is_multicast(&self) -> bool { - (self.segments()[0] & 0xff00) == 0xff00 - } - - /// Returns [`true`] if the address is an IPv4-mapped address (`::ffff:0:0/96`). - /// - /// IPv4-mapped addresses can be converted to their canonical IPv4 address with - /// [`to_ipv4_mapped`](Ipv6Addr::to_ipv4_mapped). - /// - /// # Examples - /// ``` - /// #![feature(ip)] - /// - /// use std::net::{Ipv4Addr, Ipv6Addr}; - /// - /// let ipv4_mapped = Ipv4Addr::new(192, 0, 2, 255).to_ipv6_mapped(); - /// assert_eq!(ipv4_mapped.is_ipv4_mapped(), true); - /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc000, 0x2ff).is_ipv4_mapped(), true); - /// - /// assert_eq!(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0).is_ipv4_mapped(), false); - /// ``` - #[rustc_const_unstable(feature = "const_ipv6", issue = "76205")] - #[unstable(feature = "ip", issue = "27709")] - #[must_use] - #[inline] - pub const fn is_ipv4_mapped(&self) -> bool { - matches!(self.segments(), [0, 0, 0, 0, 0, 0xffff, _, _]) - } - - /// Converts this address to an [`IPv4` address] if it's an [IPv4-mapped] address, - /// as defined in [IETF RFC 4291 section 2.5.5.2], otherwise returns [`None`]. - /// - /// `::ffff:a.b.c.d` becomes `a.b.c.d`. - /// All addresses *not* starting with `::ffff` will return `None`. - /// - /// [`IPv4` address]: Ipv4Addr - /// [IPv4-mapped]: Ipv6Addr - /// [IETF RFC 4291 section 2.5.5.2]: https://tools.ietf.org/html/rfc4291#section-2.5.5.2 - /// - /// # Examples - /// - /// ``` - /// use std::net::{Ipv4Addr, Ipv6Addr}; - /// - /// assert_eq!(Ipv6Addr::new(0xff00, 0, 0, 0, 0, 0, 0, 0).to_ipv4_mapped(), None); - /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).to_ipv4_mapped(), - /// Some(Ipv4Addr::new(192, 10, 2, 255))); - /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1).to_ipv4_mapped(), None); - /// ``` - #[inline] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[stable(feature = "ipv6_to_ipv4_mapped", since = "1.63.0")] - #[rustc_const_stable(feature = "const_ipv6_to_ipv4_mapped", since = "1.75.0")] - pub const fn to_ipv4_mapped(&self) -> Option { - match self.octets() { - [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0xff, 0xff, a, b, c, d] => { - Some(Ipv4Addr::new(a, b, c, d)) - } - _ => None, - } - } - - /// Converts this address to an [`IPv4` address] if it is either - /// an [IPv4-compatible] address as defined in [IETF RFC 4291 section 2.5.5.1], - /// or an [IPv4-mapped] address as defined in [IETF RFC 4291 section 2.5.5.2], - /// otherwise returns [`None`]. - /// - /// Note that this will return an [`IPv4` address] for the IPv6 loopback address `::1`. Use - /// [`Ipv6Addr::to_ipv4_mapped`] to avoid this. - /// - /// `::a.b.c.d` and `::ffff:a.b.c.d` become `a.b.c.d`. `::1` becomes `0.0.0.1`. - /// All addresses *not* starting with either all zeroes or `::ffff` will return `None`. - /// - /// [`IPv4` address]: Ipv4Addr - /// [IPv4-compatible]: Ipv6Addr#ipv4-compatible-ipv6-addresses - /// [IPv4-mapped]: Ipv6Addr#ipv4-mapped-ipv6-addresses - /// [IETF RFC 4291 section 2.5.5.1]: https://tools.ietf.org/html/rfc4291#section-2.5.5.1 - /// [IETF RFC 4291 section 2.5.5.2]: https://tools.ietf.org/html/rfc4291#section-2.5.5.2 - /// - /// # Examples - /// - /// ``` - /// use std::net::{Ipv4Addr, Ipv6Addr}; - /// - /// assert_eq!(Ipv6Addr::new(0xff00, 0, 0, 0, 0, 0, 0, 0).to_ipv4(), None); - /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).to_ipv4(), - /// Some(Ipv4Addr::new(192, 10, 2, 255))); - /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1).to_ipv4(), - /// Some(Ipv4Addr::new(0, 0, 0, 1))); - /// ``` - #[rustc_const_stable(feature = "const_ip_50", since = "1.50.0")] - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn to_ipv4(&self) -> Option { - if let [0, 0, 0, 0, 0, 0 | 0xffff, ab, cd] = self.segments() { - let [a, b] = ab.to_be_bytes(); - let [c, d] = cd.to_be_bytes(); - Some(Ipv4Addr::new(a, b, c, d)) - } else { - None - } - } - - /// Converts this address to an `IpAddr::V4` if it is an IPv4-mapped addresses, otherwise it - /// returns self wrapped in an `IpAddr::V6`. - /// - /// # Examples - /// - /// ``` - /// use std::net::Ipv6Addr; - /// - /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0x7f00, 0x1).is_loopback(), false); - /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0x7f00, 0x1).to_canonical().is_loopback(), true); - /// ``` - #[inline] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[stable(feature = "ip_to_canonical", since = "1.75.0")] - #[rustc_const_stable(feature = "ip_to_canonical", since = "1.75.0")] - pub const fn to_canonical(&self) -> IpAddr { - if let Some(mapped) = self.to_ipv4_mapped() { - return IpAddr::V4(mapped); - } - IpAddr::V6(*self) - } - - /// Returns the sixteen eight-bit integers the IPv6 address consists of. - /// - /// ``` - /// use std::net::Ipv6Addr; - /// - /// assert_eq!(Ipv6Addr::new(0xff00, 0, 0, 0, 0, 0, 0, 0).octets(), - /// [255, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]); - /// ``` - #[rustc_const_stable(feature = "const_ip_32", since = "1.32.0")] - #[stable(feature = "ipv6_to_octets", since = "1.12.0")] - #[must_use] - #[inline] - pub const fn octets(&self) -> [u8; 16] { - self.octets - } -} - -/// Write an Ipv6Addr, conforming to the canonical style described by -/// [RFC 5952](https://tools.ietf.org/html/rfc5952). -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for Ipv6Addr { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - // If there are no alignment requirements, write the IP address directly to `f`. - // Otherwise, write it to a local buffer and then use `f.pad`. - if f.precision().is_none() && f.width().is_none() { - let segments = self.segments(); - - if let Some(ipv4) = self.to_ipv4_mapped() { - write!(f, "::ffff:{}", ipv4) - } else { - #[derive(Copy, Clone, Default)] - struct Span { - start: usize, - len: usize, - } - - // Find the inner 0 span - let zeroes = { - let mut longest = Span::default(); - let mut current = Span::default(); - - for (i, &segment) in segments.iter().enumerate() { - if segment == 0 { - if current.len == 0 { - current.start = i; - } - - current.len += 1; - - if current.len > longest.len { - longest = current; - } - } else { - current = Span::default(); - } - } - - longest - }; - - /// Write a colon-separated part of the address - #[inline] - fn fmt_subslice(f: &mut fmt::Formatter<'_>, chunk: &[u16]) -> fmt::Result { - if let Some((first, tail)) = chunk.split_first() { - write!(f, "{:x}", first)?; - for segment in tail { - f.write_char(':')?; - write!(f, "{:x}", segment)?; - } - } - Ok(()) - } - - if zeroes.len > 1 { - fmt_subslice(f, &segments[..zeroes.start])?; - f.write_str("::")?; - fmt_subslice(f, &segments[zeroes.start + zeroes.len..]) - } else { - fmt_subslice(f, &segments) - } - } - } else { - const LONGEST_IPV6_ADDR: &str = "ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff"; - - let mut buf = DisplayBuffer::<{ LONGEST_IPV6_ADDR.len() }>::new(); - // Buffer is long enough for the longest possible IPv6 address, so this should never fail. - write!(buf, "{}", self).unwrap(); - - f.pad(buf.as_str()) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for Ipv6Addr { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt(self, fmt) - } -} - -#[stable(feature = "ip_cmp", since = "1.16.0")] -impl PartialEq for Ipv6Addr { - #[inline] - fn eq(&self, other: &IpAddr) -> bool { - match other { - IpAddr::V4(_) => false, - IpAddr::V6(v6) => self == v6, - } - } -} - -#[stable(feature = "ip_cmp", since = "1.16.0")] -impl PartialEq for IpAddr { - #[inline] - fn eq(&self, other: &Ipv6Addr) -> bool { - match self { - IpAddr::V4(_) => false, - IpAddr::V6(v6) => v6 == other, - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialOrd for Ipv6Addr { - #[inline] - fn partial_cmp(&self, other: &Ipv6Addr) -> Option { - Some(self.cmp(other)) - } -} - -#[stable(feature = "ip_cmp", since = "1.16.0")] -impl PartialOrd for IpAddr { - #[inline] - fn partial_cmp(&self, other: &Ipv6Addr) -> Option { - match self { - IpAddr::V4(_) => Some(Ordering::Less), - IpAddr::V6(v6) => v6.partial_cmp(other), - } - } -} - -#[stable(feature = "ip_cmp", since = "1.16.0")] -impl PartialOrd for Ipv6Addr { - #[inline] - fn partial_cmp(&self, other: &IpAddr) -> Option { - match other { - IpAddr::V4(_) => Some(Ordering::Greater), - IpAddr::V6(v6) => self.partial_cmp(v6), - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for Ipv6Addr { - #[inline] - fn cmp(&self, other: &Ipv6Addr) -> Ordering { - self.segments().cmp(&other.segments()) - } -} - -#[stable(feature = "i128", since = "1.26.0")] -impl From for u128 { - /// Uses [`Ipv6Addr::to_bits`] to convert an IPv6 address to a host byte order `u128`. - #[inline] - fn from(ip: Ipv6Addr) -> u128 { - ip.to_bits() - } -} -#[stable(feature = "i128", since = "1.26.0")] -impl From for Ipv6Addr { - /// Uses [`Ipv6Addr::from_bits`] to convert a host byte order `u128` to an IPv6 address. - #[inline] - fn from(ip: u128) -> Ipv6Addr { - Ipv6Addr::from_bits(ip) - } -} - -#[stable(feature = "ipv6_from_octets", since = "1.9.0")] -impl From<[u8; 16]> for Ipv6Addr { - /// Creates an `Ipv6Addr` from a sixteen element byte array. - /// - /// # Examples - /// - /// ``` - /// use std::net::Ipv6Addr; - /// - /// let addr = Ipv6Addr::from([ - /// 25u8, 24u8, 23u8, 22u8, 21u8, 20u8, 19u8, 18u8, - /// 17u8, 16u8, 15u8, 14u8, 13u8, 12u8, 11u8, 10u8, - /// ]); - /// assert_eq!( - /// Ipv6Addr::new( - /// 0x1918, 0x1716, - /// 0x1514, 0x1312, - /// 0x1110, 0x0f0e, - /// 0x0d0c, 0x0b0a - /// ), - /// addr - /// ); - /// ``` - #[inline] - fn from(octets: [u8; 16]) -> Ipv6Addr { - Ipv6Addr { octets } - } -} - -#[stable(feature = "ipv6_from_segments", since = "1.16.0")] -impl From<[u16; 8]> for Ipv6Addr { - /// Creates an `Ipv6Addr` from an eight element 16-bit array. - /// - /// # Examples - /// - /// ``` - /// use std::net::Ipv6Addr; - /// - /// let addr = Ipv6Addr::from([ - /// 525u16, 524u16, 523u16, 522u16, - /// 521u16, 520u16, 519u16, 518u16, - /// ]); - /// assert_eq!( - /// Ipv6Addr::new( - /// 0x20d, 0x20c, - /// 0x20b, 0x20a, - /// 0x209, 0x208, - /// 0x207, 0x206 - /// ), - /// addr - /// ); - /// ``` - #[inline] - fn from(segments: [u16; 8]) -> Ipv6Addr { - let [a, b, c, d, e, f, g, h] = segments; - Ipv6Addr::new(a, b, c, d, e, f, g, h) - } -} - -#[stable(feature = "ip_from_slice", since = "1.17.0")] -impl From<[u8; 16]> for IpAddr { - /// Creates an `IpAddr::V6` from a sixteen element byte array. - /// - /// # Examples - /// - /// ``` - /// use std::net::{IpAddr, Ipv6Addr}; - /// - /// let addr = IpAddr::from([ - /// 25u8, 24u8, 23u8, 22u8, 21u8, 20u8, 19u8, 18u8, - /// 17u8, 16u8, 15u8, 14u8, 13u8, 12u8, 11u8, 10u8, - /// ]); - /// assert_eq!( - /// IpAddr::V6(Ipv6Addr::new( - /// 0x1918, 0x1716, - /// 0x1514, 0x1312, - /// 0x1110, 0x0f0e, - /// 0x0d0c, 0x0b0a - /// )), - /// addr - /// ); - /// ``` - #[inline] - fn from(octets: [u8; 16]) -> IpAddr { - IpAddr::V6(Ipv6Addr::from(octets)) - } -} - -#[stable(feature = "ip_from_slice", since = "1.17.0")] -impl From<[u16; 8]> for IpAddr { - /// Creates an `IpAddr::V6` from an eight element 16-bit array. - /// - /// # Examples - /// - /// ``` - /// use std::net::{IpAddr, Ipv6Addr}; - /// - /// let addr = IpAddr::from([ - /// 525u16, 524u16, 523u16, 522u16, - /// 521u16, 520u16, 519u16, 518u16, - /// ]); - /// assert_eq!( - /// IpAddr::V6(Ipv6Addr::new( - /// 0x20d, 0x20c, - /// 0x20b, 0x20a, - /// 0x209, 0x208, - /// 0x207, 0x206 - /// )), - /// addr - /// ); - /// ``` - #[inline] - fn from(segments: [u16; 8]) -> IpAddr { - IpAddr::V6(Ipv6Addr::from(segments)) - } -} - -#[stable(feature = "ip_bitops", since = "1.75.0")] -impl Not for Ipv4Addr { - type Output = Ipv4Addr; - - #[inline] - fn not(mut self) -> Ipv4Addr { - for octet in &mut self.octets { - *octet = !*octet; - } - self - } -} - -#[stable(feature = "ip_bitops", since = "1.75.0")] -impl Not for &'_ Ipv4Addr { - type Output = Ipv4Addr; - - #[inline] - fn not(self) -> Ipv4Addr { - !*self - } -} - -#[stable(feature = "ip_bitops", since = "1.75.0")] -impl Not for Ipv6Addr { - type Output = Ipv6Addr; - - #[inline] - fn not(mut self) -> Ipv6Addr { - for octet in &mut self.octets { - *octet = !*octet; - } - self - } -} - -#[stable(feature = "ip_bitops", since = "1.75.0")] -impl Not for &'_ Ipv6Addr { - type Output = Ipv6Addr; - - #[inline] - fn not(self) -> Ipv6Addr { - !*self - } -} - -macro_rules! bitop_impls { - ($( - $(#[$attr:meta])* - impl ($BitOp:ident, $BitOpAssign:ident) for $ty:ty = ($bitop:ident, $bitop_assign:ident); - )*) => { - $( - $(#[$attr])* - impl $BitOpAssign for $ty { - fn $bitop_assign(&mut self, rhs: $ty) { - for (lhs, rhs) in iter::zip(&mut self.octets, rhs.octets) { - lhs.$bitop_assign(rhs); - } - } - } - - $(#[$attr])* - impl $BitOpAssign<&'_ $ty> for $ty { - fn $bitop_assign(&mut self, rhs: &'_ $ty) { - self.$bitop_assign(*rhs); - } - } - - $(#[$attr])* - impl $BitOp for $ty { - type Output = $ty; - - #[inline] - fn $bitop(mut self, rhs: $ty) -> $ty { - self.$bitop_assign(rhs); - self - } - } - - $(#[$attr])* - impl $BitOp<&'_ $ty> for $ty { - type Output = $ty; - - #[inline] - fn $bitop(mut self, rhs: &'_ $ty) -> $ty { - self.$bitop_assign(*rhs); - self - } - } - - $(#[$attr])* - impl $BitOp<$ty> for &'_ $ty { - type Output = $ty; - - #[inline] - fn $bitop(self, rhs: $ty) -> $ty { - let mut lhs = *self; - lhs.$bitop_assign(rhs); - lhs - } - } - - $(#[$attr])* - impl $BitOp<&'_ $ty> for &'_ $ty { - type Output = $ty; - - #[inline] - fn $bitop(self, rhs: &'_ $ty) -> $ty { - let mut lhs = *self; - lhs.$bitop_assign(*rhs); - lhs - } - } - )* - }; -} - -bitop_impls! { - #[stable(feature = "ip_bitops", since = "1.75.0")] - impl (BitAnd, BitAndAssign) for Ipv4Addr = (bitand, bitand_assign); - #[stable(feature = "ip_bitops", since = "1.75.0")] - impl (BitOr, BitOrAssign) for Ipv4Addr = (bitor, bitor_assign); - - #[stable(feature = "ip_bitops", since = "1.75.0")] - impl (BitAnd, BitAndAssign) for Ipv6Addr = (bitand, bitand_assign); - #[stable(feature = "ip_bitops", since = "1.75.0")] - impl (BitOr, BitOrAssign) for Ipv6Addr = (bitor, bitor_assign); -} diff --git a/library/core/src/net/mod.rs b/library/core/src/net/mod.rs deleted file mode 100644 index 0786165fe9e76..0000000000000 --- a/library/core/src/net/mod.rs +++ /dev/null @@ -1,24 +0,0 @@ -//! Networking primitives for IP communication. -//! -//! This module provides types for IP and socket addresses. -//! -//! # Organization -//! -//! * [`IpAddr`] represents IP addresses of either IPv4 or IPv6; [`Ipv4Addr`] and -//! [`Ipv6Addr`] are respectively IPv4 and IPv6 addresses -//! * [`SocketAddr`] represents socket addresses of either IPv4 or IPv6; [`SocketAddrV4`] -//! and [`SocketAddrV6`] are respectively IPv4 and IPv6 socket addresses - -#![stable(feature = "ip_in_core", since = "1.77.0")] - -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::ip_addr::{IpAddr, Ipv4Addr, Ipv6Addr, Ipv6MulticastScope}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::parser::AddrParseError; -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::socket_addr::{SocketAddr, SocketAddrV4, SocketAddrV6}; - -mod display_buffer; -mod ip_addr; -mod parser; -mod socket_addr; diff --git a/library/core/src/net/parser.rs b/library/core/src/net/parser.rs deleted file mode 100644 index deea821244859..0000000000000 --- a/library/core/src/net/parser.rs +++ /dev/null @@ -1,527 +0,0 @@ -//! A private parser implementation of IPv4, IPv6, and socket addresses. -//! -//! This module is "publicly exported" through the `FromStr` implementations -//! below. - -use crate::error::Error; -use crate::fmt; -use crate::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, SocketAddrV4, SocketAddrV6}; -use crate::str::FromStr; - -trait ReadNumberHelper: Sized { - const ZERO: Self; - fn checked_mul(&self, other: u32) -> Option; - fn checked_add(&self, other: u32) -> Option; -} - -macro_rules! impl_helper { - ($($t:ty)*) => ($(impl ReadNumberHelper for $t { - const ZERO: Self = 0; - #[inline] - fn checked_mul(&self, other: u32) -> Option { - Self::checked_mul(*self, other.try_into().ok()?) - } - #[inline] - fn checked_add(&self, other: u32) -> Option { - Self::checked_add(*self, other.try_into().ok()?) - } - })*) -} - -impl_helper! { u8 u16 u32 } - -struct Parser<'a> { - // Parsing as ASCII, so can use byte array. - state: &'a [u8], -} - -impl<'a> Parser<'a> { - fn new(input: &'a [u8]) -> Parser<'a> { - Parser { state: input } - } - - /// Run a parser, and restore the pre-parse state if it fails. - fn read_atomically(&mut self, inner: F) -> Option - where - F: FnOnce(&mut Parser<'_>) -> Option, - { - let state = self.state; - let result = inner(self); - if result.is_none() { - self.state = state; - } - result - } - - /// Run a parser, but fail if the entire input wasn't consumed. - /// Doesn't run atomically. - fn parse_with(&mut self, inner: F, kind: AddrKind) -> Result - where - F: FnOnce(&mut Parser<'_>) -> Option, - { - let result = inner(self); - if self.state.is_empty() { result } else { None }.ok_or(AddrParseError(kind)) - } - - /// Peek the next character from the input - fn peek_char(&self) -> Option { - self.state.first().map(|&b| char::from(b)) - } - - /// Read the next character from the input - fn read_char(&mut self) -> Option { - self.state.split_first().map(|(&b, tail)| { - self.state = tail; - char::from(b) - }) - } - - #[must_use] - /// Read the next character from the input if it matches the target. - fn read_given_char(&mut self, target: char) -> Option<()> { - self.read_atomically(|p| { - p.read_char().and_then(|c| if c == target { Some(()) } else { None }) - }) - } - - /// Helper for reading separators in an indexed loop. Reads the separator - /// character iff index > 0, then runs the parser. When used in a loop, - /// the separator character will only be read on index > 0 (see - /// read_ipv4_addr for an example) - fn read_separator(&mut self, sep: char, index: usize, inner: F) -> Option - where - F: FnOnce(&mut Parser<'_>) -> Option, - { - self.read_atomically(move |p| { - if index > 0 { - p.read_given_char(sep)?; - } - inner(p) - }) - } - - // Read a number off the front of the input in the given radix, stopping - // at the first non-digit character or eof. Fails if the number has more - // digits than max_digits or if there is no number. - // - // INVARIANT: `max_digits` must be less than the number of digits that `u32` - // can represent. - fn read_number>( - &mut self, - radix: u32, - max_digits: Option, - allow_zero_prefix: bool, - ) -> Option { - // If max_digits.is_some(), then we are parsing a `u8` or `u16` and - // don't need to use checked arithmetic since it fits within a `u32`. - if let Some(max_digits) = max_digits { - // u32::MAX = 4_294_967_295u32, which is 10 digits long. - // `max_digits` must be less than 10 to not overflow a `u32`. - debug_assert!(max_digits < 10); - - self.read_atomically(move |p| { - let mut result = 0_u32; - let mut digit_count = 0; - let has_leading_zero = p.peek_char() == Some('0'); - - while let Some(digit) = p.read_atomically(|p| p.read_char()?.to_digit(radix)) { - result *= radix; - result += digit; - digit_count += 1; - - if digit_count > max_digits { - return None; - } - } - - if digit_count == 0 { - None - } else if !allow_zero_prefix && has_leading_zero && digit_count > 1 { - None - } else { - result.try_into().ok() - } - }) - } else { - self.read_atomically(move |p| { - let mut result = T::ZERO; - let mut digit_count = 0; - let has_leading_zero = p.peek_char() == Some('0'); - - while let Some(digit) = p.read_atomically(|p| p.read_char()?.to_digit(radix)) { - result = result.checked_mul(radix)?; - result = result.checked_add(digit)?; - digit_count += 1; - } - - if digit_count == 0 { - None - } else if !allow_zero_prefix && has_leading_zero && digit_count > 1 { - None - } else { - Some(result) - } - }) - } - } - - /// Read an IPv4 address. - fn read_ipv4_addr(&mut self) -> Option { - self.read_atomically(|p| { - let mut groups = [0; 4]; - - for (i, slot) in groups.iter_mut().enumerate() { - *slot = p.read_separator('.', i, |p| { - // Disallow octal number in IP string. - // https://tools.ietf.org/html/rfc6943#section-3.1.1 - p.read_number(10, Some(3), false) - })?; - } - - Some(groups.into()) - }) - } - - /// Read an IPv6 Address. - fn read_ipv6_addr(&mut self) -> Option { - /// Read a chunk of an IPv6 address into `groups`. Returns the number - /// of groups read, along with a bool indicating if an embedded - /// trailing IPv4 address was read. Specifically, read a series of - /// colon-separated IPv6 groups (0x0000 - 0xFFFF), with an optional - /// trailing embedded IPv4 address. - fn read_groups(p: &mut Parser<'_>, groups: &mut [u16]) -> (usize, bool) { - let limit = groups.len(); - - for (i, slot) in groups.iter_mut().enumerate() { - // Try to read a trailing embedded IPv4 address. There must be - // at least two groups left. - if i < limit - 1 { - let ipv4 = p.read_separator(':', i, |p| p.read_ipv4_addr()); - - if let Some(v4_addr) = ipv4 { - let [one, two, three, four] = v4_addr.octets(); - groups[i + 0] = u16::from_be_bytes([one, two]); - groups[i + 1] = u16::from_be_bytes([three, four]); - return (i + 2, true); - } - } - - let group = p.read_separator(':', i, |p| p.read_number(16, Some(4), true)); - - match group { - Some(g) => *slot = g, - None => return (i, false), - } - } - (groups.len(), false) - } - - self.read_atomically(|p| { - // Read the front part of the address; either the whole thing, or up - // to the first :: - let mut head = [0; 8]; - let (head_size, head_ipv4) = read_groups(p, &mut head); - - if head_size == 8 { - return Some(head.into()); - } - - // IPv4 part is not allowed before `::` - if head_ipv4 { - return None; - } - - // Read `::` if previous code parsed less than 8 groups. - // `::` indicates one or more groups of 16 bits of zeros. - p.read_given_char(':')?; - p.read_given_char(':')?; - - // Read the back part of the address. The :: must contain at least one - // set of zeroes, so our max length is 7. - let mut tail = [0; 7]; - let limit = 8 - (head_size + 1); - let (tail_size, _) = read_groups(p, &mut tail[..limit]); - - // Concat the head and tail of the IP address - head[(8 - tail_size)..8].copy_from_slice(&tail[..tail_size]); - - Some(head.into()) - }) - } - - /// Read an IP Address, either IPv4 or IPv6. - fn read_ip_addr(&mut self) -> Option { - self.read_ipv4_addr().map(IpAddr::V4).or_else(move || self.read_ipv6_addr().map(IpAddr::V6)) - } - - /// Read a `:` followed by a port in base 10. - fn read_port(&mut self) -> Option { - self.read_atomically(|p| { - p.read_given_char(':')?; - p.read_number(10, None, true) - }) - } - - /// Read a `%` followed by a scope ID in base 10. - fn read_scope_id(&mut self) -> Option { - self.read_atomically(|p| { - p.read_given_char('%')?; - p.read_number(10, None, true) - }) - } - - /// Read an IPv4 address with a port. - fn read_socket_addr_v4(&mut self) -> Option { - self.read_atomically(|p| { - let ip = p.read_ipv4_addr()?; - let port = p.read_port()?; - Some(SocketAddrV4::new(ip, port)) - }) - } - - /// Read an IPv6 address with a port. - fn read_socket_addr_v6(&mut self) -> Option { - self.read_atomically(|p| { - p.read_given_char('[')?; - let ip = p.read_ipv6_addr()?; - let scope_id = p.read_scope_id().unwrap_or(0); - p.read_given_char(']')?; - - let port = p.read_port()?; - Some(SocketAddrV6::new(ip, port, 0, scope_id)) - }) - } - - /// Read an IP address with a port - fn read_socket_addr(&mut self) -> Option { - self.read_socket_addr_v4() - .map(SocketAddr::V4) - .or_else(|| self.read_socket_addr_v6().map(SocketAddr::V6)) - } -} - -impl IpAddr { - /// Parse an IP address from a slice of bytes. - /// - /// ``` - /// #![feature(addr_parse_ascii)] - /// - /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr}; - /// - /// let localhost_v4 = IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)); - /// let localhost_v6 = IpAddr::V6(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1)); - /// - /// assert_eq!(IpAddr::parse_ascii(b"127.0.0.1"), Ok(localhost_v4)); - /// assert_eq!(IpAddr::parse_ascii(b"::1"), Ok(localhost_v6)); - /// ``` - #[unstable(feature = "addr_parse_ascii", issue = "101035")] - pub fn parse_ascii(b: &[u8]) -> Result { - Parser::new(b).parse_with(|p| p.read_ip_addr(), AddrKind::Ip) - } -} - -#[stable(feature = "ip_addr", since = "1.7.0")] -impl FromStr for IpAddr { - type Err = AddrParseError; - fn from_str(s: &str) -> Result { - Self::parse_ascii(s.as_bytes()) - } -} - -impl Ipv4Addr { - /// Parse an IPv4 address from a slice of bytes. - /// - /// ``` - /// #![feature(addr_parse_ascii)] - /// - /// use std::net::Ipv4Addr; - /// - /// let localhost = Ipv4Addr::new(127, 0, 0, 1); - /// - /// assert_eq!(Ipv4Addr::parse_ascii(b"127.0.0.1"), Ok(localhost)); - /// ``` - #[unstable(feature = "addr_parse_ascii", issue = "101035")] - pub fn parse_ascii(b: &[u8]) -> Result { - // don't try to parse if too long - if b.len() > 15 { - Err(AddrParseError(AddrKind::Ipv4)) - } else { - Parser::new(b).parse_with(|p| p.read_ipv4_addr(), AddrKind::Ipv4) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl FromStr for Ipv4Addr { - type Err = AddrParseError; - fn from_str(s: &str) -> Result { - Self::parse_ascii(s.as_bytes()) - } -} - -impl Ipv6Addr { - /// Parse an IPv6 address from a slice of bytes. - /// - /// ``` - /// #![feature(addr_parse_ascii)] - /// - /// use std::net::Ipv6Addr; - /// - /// let localhost = Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1); - /// - /// assert_eq!(Ipv6Addr::parse_ascii(b"::1"), Ok(localhost)); - /// ``` - #[unstable(feature = "addr_parse_ascii", issue = "101035")] - pub fn parse_ascii(b: &[u8]) -> Result { - Parser::new(b).parse_with(|p| p.read_ipv6_addr(), AddrKind::Ipv6) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl FromStr for Ipv6Addr { - type Err = AddrParseError; - fn from_str(s: &str) -> Result { - Self::parse_ascii(s.as_bytes()) - } -} - -impl SocketAddrV4 { - /// Parse an IPv4 socket address from a slice of bytes. - /// - /// ``` - /// #![feature(addr_parse_ascii)] - /// - /// use std::net::{Ipv4Addr, SocketAddrV4}; - /// - /// let socket = SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080); - /// - /// assert_eq!(SocketAddrV4::parse_ascii(b"127.0.0.1:8080"), Ok(socket)); - /// ``` - #[unstable(feature = "addr_parse_ascii", issue = "101035")] - pub fn parse_ascii(b: &[u8]) -> Result { - Parser::new(b).parse_with(|p| p.read_socket_addr_v4(), AddrKind::SocketV4) - } -} - -#[stable(feature = "socket_addr_from_str", since = "1.5.0")] -impl FromStr for SocketAddrV4 { - type Err = AddrParseError; - fn from_str(s: &str) -> Result { - Self::parse_ascii(s.as_bytes()) - } -} - -impl SocketAddrV6 { - /// Parse an IPv6 socket address from a slice of bytes. - /// - /// ``` - /// #![feature(addr_parse_ascii)] - /// - /// use std::net::{Ipv6Addr, SocketAddrV6}; - /// - /// let socket = SocketAddrV6::new(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1), 8080, 0, 0); - /// - /// assert_eq!(SocketAddrV6::parse_ascii(b"[2001:db8::1]:8080"), Ok(socket)); - /// ``` - #[unstable(feature = "addr_parse_ascii", issue = "101035")] - pub fn parse_ascii(b: &[u8]) -> Result { - Parser::new(b).parse_with(|p| p.read_socket_addr_v6(), AddrKind::SocketV6) - } -} - -#[stable(feature = "socket_addr_from_str", since = "1.5.0")] -impl FromStr for SocketAddrV6 { - type Err = AddrParseError; - fn from_str(s: &str) -> Result { - Self::parse_ascii(s.as_bytes()) - } -} - -impl SocketAddr { - /// Parse a socket address from a slice of bytes. - /// - /// ``` - /// #![feature(addr_parse_ascii)] - /// - /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr}; - /// - /// let socket_v4 = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080); - /// let socket_v6 = SocketAddr::new(IpAddr::V6(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1)), 8080); - /// - /// assert_eq!(SocketAddr::parse_ascii(b"127.0.0.1:8080"), Ok(socket_v4)); - /// assert_eq!(SocketAddr::parse_ascii(b"[::1]:8080"), Ok(socket_v6)); - /// ``` - #[unstable(feature = "addr_parse_ascii", issue = "101035")] - pub fn parse_ascii(b: &[u8]) -> Result { - Parser::new(b).parse_with(|p| p.read_socket_addr(), AddrKind::Socket) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl FromStr for SocketAddr { - type Err = AddrParseError; - fn from_str(s: &str) -> Result { - Self::parse_ascii(s.as_bytes()) - } -} - -#[derive(Debug, Clone, PartialEq, Eq)] -enum AddrKind { - Ip, - Ipv4, - Ipv6, - Socket, - SocketV4, - SocketV6, -} - -/// An error which can be returned when parsing an IP address or a socket address. -/// -/// This error is used as the error type for the [`FromStr`] implementation for -/// [`IpAddr`], [`Ipv4Addr`], [`Ipv6Addr`], [`SocketAddr`], [`SocketAddrV4`], and -/// [`SocketAddrV6`]. -/// -/// # Potential causes -/// -/// `AddrParseError` may be thrown because the provided string does not parse as the given type, -/// often because it includes information only handled by a different address type. -/// -/// ```should_panic -/// use std::net::IpAddr; -/// let _foo: IpAddr = "127.0.0.1:8080".parse().expect("Cannot handle the socket port"); -/// ``` -/// -/// [`IpAddr`] doesn't handle the port. Use [`SocketAddr`] instead. -/// -/// ``` -/// use std::net::SocketAddr; -/// -/// // No problem, the `panic!` message has disappeared. -/// let _foo: SocketAddr = "127.0.0.1:8080".parse().expect("unreachable panic"); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct AddrParseError(AddrKind); - -#[stable(feature = "addr_parse_error_error", since = "1.4.0")] -impl fmt::Display for AddrParseError { - #[allow(deprecated, deprecated_in_future)] - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.write_str(self.description()) - } -} - -#[stable(feature = "addr_parse_error_error", since = "1.4.0")] -impl Error for AddrParseError { - #[allow(deprecated)] - fn description(&self) -> &str { - match self.0 { - AddrKind::Ip => "invalid IP address syntax", - AddrKind::Ipv4 => "invalid IPv4 address syntax", - AddrKind::Ipv6 => "invalid IPv6 address syntax", - AddrKind::Socket => "invalid socket address syntax", - AddrKind::SocketV4 => "invalid IPv4 socket address syntax", - AddrKind::SocketV6 => "invalid IPv6 socket address syntax", - } - } -} diff --git a/library/core/src/net/socket_addr.rs b/library/core/src/net/socket_addr.rs deleted file mode 100644 index c24d8f5519504..0000000000000 --- a/library/core/src/net/socket_addr.rs +++ /dev/null @@ -1,644 +0,0 @@ -use crate::fmt::{self, Write}; -use crate::net::{IpAddr, Ipv4Addr, Ipv6Addr}; - -use super::display_buffer::DisplayBuffer; - -/// An internet socket address, either IPv4 or IPv6. -/// -/// Internet socket addresses consist of an [IP address], a 16-bit port number, as well -/// as possibly some version-dependent additional information. See [`SocketAddrV4`]'s and -/// [`SocketAddrV6`]'s respective documentation for more details. -/// -/// The size of a `SocketAddr` instance may vary depending on the target operating -/// system. -/// -/// [IP address]: IpAddr -/// -/// # Examples -/// -/// ``` -/// use std::net::{IpAddr, Ipv4Addr, SocketAddr}; -/// -/// let socket = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080); -/// -/// assert_eq!("127.0.0.1:8080".parse(), Ok(socket)); -/// assert_eq!(socket.port(), 8080); -/// assert_eq!(socket.is_ipv4(), true); -/// ``` -#[derive(Copy, Clone, PartialEq, Eq, Hash, PartialOrd, Ord)] -#[stable(feature = "rust1", since = "1.0.0")] -pub enum SocketAddr { - /// An IPv4 socket address. - #[stable(feature = "rust1", since = "1.0.0")] - V4(#[stable(feature = "rust1", since = "1.0.0")] SocketAddrV4), - /// An IPv6 socket address. - #[stable(feature = "rust1", since = "1.0.0")] - V6(#[stable(feature = "rust1", since = "1.0.0")] SocketAddrV6), -} - -/// An IPv4 socket address. -/// -/// IPv4 socket addresses consist of an [`IPv4` address] and a 16-bit port number, as -/// stated in [IETF RFC 793]. -/// -/// See [`SocketAddr`] for a type encompassing both IPv4 and IPv6 socket addresses. -/// -/// The size of a `SocketAddrV4` struct may vary depending on the target operating -/// system. Do not assume that this type has the same memory layout as the underlying -/// system representation. -/// -/// [IETF RFC 793]: https://tools.ietf.org/html/rfc793 -/// [`IPv4` address]: Ipv4Addr -/// -/// # Examples -/// -/// ``` -/// use std::net::{Ipv4Addr, SocketAddrV4}; -/// -/// let socket = SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080); -/// -/// assert_eq!("127.0.0.1:8080".parse(), Ok(socket)); -/// assert_eq!(socket.ip(), &Ipv4Addr::new(127, 0, 0, 1)); -/// assert_eq!(socket.port(), 8080); -/// ``` -#[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct SocketAddrV4 { - ip: Ipv4Addr, - port: u16, -} - -/// An IPv6 socket address. -/// -/// IPv6 socket addresses consist of an [`IPv6` address], a 16-bit port number, as well -/// as fields containing the traffic class, the flow label, and a scope identifier -/// (see [IETF RFC 2553, Section 3.3] for more details). -/// -/// See [`SocketAddr`] for a type encompassing both IPv4 and IPv6 socket addresses. -/// -/// The size of a `SocketAddrV6` struct may vary depending on the target operating -/// system. Do not assume that this type has the same memory layout as the underlying -/// system representation. -/// -/// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3 -/// [`IPv6` address]: Ipv6Addr -/// -/// # Examples -/// -/// ``` -/// use std::net::{Ipv6Addr, SocketAddrV6}; -/// -/// let socket = SocketAddrV6::new(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1), 8080, 0, 0); -/// -/// assert_eq!("[2001:db8::1]:8080".parse(), Ok(socket)); -/// assert_eq!(socket.ip(), &Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1)); -/// assert_eq!(socket.port(), 8080); -/// ``` -#[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct SocketAddrV6 { - ip: Ipv6Addr, - port: u16, - flowinfo: u32, - scope_id: u32, -} - -impl SocketAddr { - /// Creates a new socket address from an [IP address] and a port number. - /// - /// [IP address]: IpAddr - /// - /// # Examples - /// - /// ``` - /// use std::net::{IpAddr, Ipv4Addr, SocketAddr}; - /// - /// let socket = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080); - /// assert_eq!(socket.ip(), IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1))); - /// assert_eq!(socket.port(), 8080); - /// ``` - #[stable(feature = "ip_addr", since = "1.7.0")] - #[must_use] - #[rustc_const_stable(feature = "const_socketaddr", since = "1.69.0")] - #[inline] - pub const fn new(ip: IpAddr, port: u16) -> SocketAddr { - match ip { - IpAddr::V4(a) => SocketAddr::V4(SocketAddrV4::new(a, port)), - IpAddr::V6(a) => SocketAddr::V6(SocketAddrV6::new(a, port, 0, 0)), - } - } - - /// Returns the IP address associated with this socket address. - /// - /// # Examples - /// - /// ``` - /// use std::net::{IpAddr, Ipv4Addr, SocketAddr}; - /// - /// let socket = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080); - /// assert_eq!(socket.ip(), IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1))); - /// ``` - #[must_use] - #[stable(feature = "ip_addr", since = "1.7.0")] - #[rustc_const_stable(feature = "const_socketaddr", since = "1.69.0")] - #[inline] - pub const fn ip(&self) -> IpAddr { - match *self { - SocketAddr::V4(ref a) => IpAddr::V4(*a.ip()), - SocketAddr::V6(ref a) => IpAddr::V6(*a.ip()), - } - } - - /// Changes the IP address associated with this socket address. - /// - /// # Examples - /// - /// ``` - /// use std::net::{IpAddr, Ipv4Addr, SocketAddr}; - /// - /// let mut socket = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080); - /// socket.set_ip(IpAddr::V4(Ipv4Addr::new(10, 10, 0, 1))); - /// assert_eq!(socket.ip(), IpAddr::V4(Ipv4Addr::new(10, 10, 0, 1))); - /// ``` - #[stable(feature = "sockaddr_setters", since = "1.9.0")] - #[inline] - pub fn set_ip(&mut self, new_ip: IpAddr) { - // `match (*self, new_ip)` would have us mutate a copy of self only to throw it away. - match (self, new_ip) { - (&mut SocketAddr::V4(ref mut a), IpAddr::V4(new_ip)) => a.set_ip(new_ip), - (&mut SocketAddr::V6(ref mut a), IpAddr::V6(new_ip)) => a.set_ip(new_ip), - (self_, new_ip) => *self_ = Self::new(new_ip, self_.port()), - } - } - - /// Returns the port number associated with this socket address. - /// - /// # Examples - /// - /// ``` - /// use std::net::{IpAddr, Ipv4Addr, SocketAddr}; - /// - /// let socket = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080); - /// assert_eq!(socket.port(), 8080); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_socketaddr", since = "1.69.0")] - #[inline] - pub const fn port(&self) -> u16 { - match *self { - SocketAddr::V4(ref a) => a.port(), - SocketAddr::V6(ref a) => a.port(), - } - } - - /// Changes the port number associated with this socket address. - /// - /// # Examples - /// - /// ``` - /// use std::net::{IpAddr, Ipv4Addr, SocketAddr}; - /// - /// let mut socket = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080); - /// socket.set_port(1025); - /// assert_eq!(socket.port(), 1025); - /// ``` - #[stable(feature = "sockaddr_setters", since = "1.9.0")] - #[inline] - pub fn set_port(&mut self, new_port: u16) { - match *self { - SocketAddr::V4(ref mut a) => a.set_port(new_port), - SocketAddr::V6(ref mut a) => a.set_port(new_port), - } - } - - /// Returns [`true`] if the [IP address] in this `SocketAddr` is an - /// [`IPv4` address], and [`false`] otherwise. - /// - /// [IP address]: IpAddr - /// [`IPv4` address]: IpAddr::V4 - /// - /// # Examples - /// - /// ``` - /// use std::net::{IpAddr, Ipv4Addr, SocketAddr}; - /// - /// let socket = SocketAddr::new(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)), 8080); - /// assert_eq!(socket.is_ipv4(), true); - /// assert_eq!(socket.is_ipv6(), false); - /// ``` - #[must_use] - #[stable(feature = "sockaddr_checker", since = "1.16.0")] - #[rustc_const_stable(feature = "const_socketaddr", since = "1.69.0")] - #[inline] - pub const fn is_ipv4(&self) -> bool { - matches!(*self, SocketAddr::V4(_)) - } - - /// Returns [`true`] if the [IP address] in this `SocketAddr` is an - /// [`IPv6` address], and [`false`] otherwise. - /// - /// [IP address]: IpAddr - /// [`IPv6` address]: IpAddr::V6 - /// - /// # Examples - /// - /// ``` - /// use std::net::{IpAddr, Ipv6Addr, SocketAddr}; - /// - /// let socket = SocketAddr::new(IpAddr::V6(Ipv6Addr::new(0, 0, 0, 0, 0, 65535, 0, 1)), 8080); - /// assert_eq!(socket.is_ipv4(), false); - /// assert_eq!(socket.is_ipv6(), true); - /// ``` - #[must_use] - #[stable(feature = "sockaddr_checker", since = "1.16.0")] - #[rustc_const_stable(feature = "const_socketaddr", since = "1.69.0")] - #[inline] - pub const fn is_ipv6(&self) -> bool { - matches!(*self, SocketAddr::V6(_)) - } -} - -impl SocketAddrV4 { - /// Creates a new socket address from an [`IPv4` address] and a port number. - /// - /// [`IPv4` address]: Ipv4Addr - /// - /// # Examples - /// - /// ``` - /// use std::net::{SocketAddrV4, Ipv4Addr}; - /// - /// let socket = SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - #[rustc_const_stable(feature = "const_socketaddr", since = "1.69.0")] - #[inline] - pub const fn new(ip: Ipv4Addr, port: u16) -> SocketAddrV4 { - SocketAddrV4 { ip, port } - } - - /// Returns the IP address associated with this socket address. - /// - /// # Examples - /// - /// ``` - /// use std::net::{SocketAddrV4, Ipv4Addr}; - /// - /// let socket = SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080); - /// assert_eq!(socket.ip(), &Ipv4Addr::new(127, 0, 0, 1)); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_socketaddr", since = "1.69.0")] - #[inline] - pub const fn ip(&self) -> &Ipv4Addr { - &self.ip - } - - /// Changes the IP address associated with this socket address. - /// - /// # Examples - /// - /// ``` - /// use std::net::{SocketAddrV4, Ipv4Addr}; - /// - /// let mut socket = SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080); - /// socket.set_ip(Ipv4Addr::new(192, 168, 0, 1)); - /// assert_eq!(socket.ip(), &Ipv4Addr::new(192, 168, 0, 1)); - /// ``` - #[stable(feature = "sockaddr_setters", since = "1.9.0")] - #[inline] - pub fn set_ip(&mut self, new_ip: Ipv4Addr) { - self.ip = new_ip; - } - - /// Returns the port number associated with this socket address. - /// - /// # Examples - /// - /// ``` - /// use std::net::{SocketAddrV4, Ipv4Addr}; - /// - /// let socket = SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080); - /// assert_eq!(socket.port(), 8080); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_socketaddr", since = "1.69.0")] - #[inline] - pub const fn port(&self) -> u16 { - self.port - } - - /// Changes the port number associated with this socket address. - /// - /// # Examples - /// - /// ``` - /// use std::net::{SocketAddrV4, Ipv4Addr}; - /// - /// let mut socket = SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080); - /// socket.set_port(4242); - /// assert_eq!(socket.port(), 4242); - /// ``` - #[stable(feature = "sockaddr_setters", since = "1.9.0")] - #[inline] - pub fn set_port(&mut self, new_port: u16) { - self.port = new_port; - } -} - -impl SocketAddrV6 { - /// Creates a new socket address from an [`IPv6` address], a 16-bit port number, - /// and the `flowinfo` and `scope_id` fields. - /// - /// For more information on the meaning and layout of the `flowinfo` and `scope_id` - /// parameters, see [IETF RFC 2553, Section 3.3]. - /// - /// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3 - /// [`IPv6` address]: Ipv6Addr - /// - /// # Examples - /// - /// ``` - /// use std::net::{SocketAddrV6, Ipv6Addr}; - /// - /// let socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 0, 0); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - #[rustc_const_stable(feature = "const_socketaddr", since = "1.69.0")] - #[inline] - pub const fn new(ip: Ipv6Addr, port: u16, flowinfo: u32, scope_id: u32) -> SocketAddrV6 { - SocketAddrV6 { ip, port, flowinfo, scope_id } - } - - /// Returns the IP address associated with this socket address. - /// - /// # Examples - /// - /// ``` - /// use std::net::{SocketAddrV6, Ipv6Addr}; - /// - /// let socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 0, 0); - /// assert_eq!(socket.ip(), &Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1)); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_socketaddr", since = "1.69.0")] - #[inline] - pub const fn ip(&self) -> &Ipv6Addr { - &self.ip - } - - /// Changes the IP address associated with this socket address. - /// - /// # Examples - /// - /// ``` - /// use std::net::{SocketAddrV6, Ipv6Addr}; - /// - /// let mut socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 0, 0); - /// socket.set_ip(Ipv6Addr::new(76, 45, 0, 0, 0, 0, 0, 0)); - /// assert_eq!(socket.ip(), &Ipv6Addr::new(76, 45, 0, 0, 0, 0, 0, 0)); - /// ``` - #[stable(feature = "sockaddr_setters", since = "1.9.0")] - #[inline] - pub fn set_ip(&mut self, new_ip: Ipv6Addr) { - self.ip = new_ip; - } - - /// Returns the port number associated with this socket address. - /// - /// # Examples - /// - /// ``` - /// use std::net::{SocketAddrV6, Ipv6Addr}; - /// - /// let socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 0, 0); - /// assert_eq!(socket.port(), 8080); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_socketaddr", since = "1.69.0")] - #[inline] - pub const fn port(&self) -> u16 { - self.port - } - - /// Changes the port number associated with this socket address. - /// - /// # Examples - /// - /// ``` - /// use std::net::{SocketAddrV6, Ipv6Addr}; - /// - /// let mut socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 0, 0); - /// socket.set_port(4242); - /// assert_eq!(socket.port(), 4242); - /// ``` - #[stable(feature = "sockaddr_setters", since = "1.9.0")] - #[inline] - pub fn set_port(&mut self, new_port: u16) { - self.port = new_port; - } - - /// Returns the flow information associated with this address. - /// - /// This information corresponds to the `sin6_flowinfo` field in C's `netinet/in.h`, - /// as specified in [IETF RFC 2553, Section 3.3]. - /// It combines information about the flow label and the traffic class as specified - /// in [IETF RFC 2460], respectively [Section 6] and [Section 7]. - /// - /// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3 - /// [IETF RFC 2460]: https://tools.ietf.org/html/rfc2460 - /// [Section 6]: https://tools.ietf.org/html/rfc2460#section-6 - /// [Section 7]: https://tools.ietf.org/html/rfc2460#section-7 - /// - /// # Examples - /// - /// ``` - /// use std::net::{SocketAddrV6, Ipv6Addr}; - /// - /// let socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 10, 0); - /// assert_eq!(socket.flowinfo(), 10); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_socketaddr", since = "1.69.0")] - #[inline] - pub const fn flowinfo(&self) -> u32 { - self.flowinfo - } - - /// Changes the flow information associated with this socket address. - /// - /// See [`SocketAddrV6::flowinfo`]'s documentation for more details. - /// - /// # Examples - /// - /// ``` - /// use std::net::{SocketAddrV6, Ipv6Addr}; - /// - /// let mut socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 10, 0); - /// socket.set_flowinfo(56); - /// assert_eq!(socket.flowinfo(), 56); - /// ``` - #[stable(feature = "sockaddr_setters", since = "1.9.0")] - #[inline] - pub fn set_flowinfo(&mut self, new_flowinfo: u32) { - self.flowinfo = new_flowinfo; - } - - /// Returns the scope ID associated with this address. - /// - /// This information corresponds to the `sin6_scope_id` field in C's `netinet/in.h`, - /// as specified in [IETF RFC 2553, Section 3.3]. - /// - /// [IETF RFC 2553, Section 3.3]: https://tools.ietf.org/html/rfc2553#section-3.3 - /// - /// # Examples - /// - /// ``` - /// use std::net::{SocketAddrV6, Ipv6Addr}; - /// - /// let socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 0, 78); - /// assert_eq!(socket.scope_id(), 78); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_socketaddr", since = "1.69.0")] - #[inline] - pub const fn scope_id(&self) -> u32 { - self.scope_id - } - - /// Changes the scope ID associated with this socket address. - /// - /// See [`SocketAddrV6::scope_id`]'s documentation for more details. - /// - /// # Examples - /// - /// ``` - /// use std::net::{SocketAddrV6, Ipv6Addr}; - /// - /// let mut socket = SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), 8080, 0, 78); - /// socket.set_scope_id(42); - /// assert_eq!(socket.scope_id(), 42); - /// ``` - #[stable(feature = "sockaddr_setters", since = "1.9.0")] - #[inline] - pub fn set_scope_id(&mut self, new_scope_id: u32) { - self.scope_id = new_scope_id; - } -} - -#[stable(feature = "ip_from_ip", since = "1.16.0")] -impl From for SocketAddr { - /// Converts a [`SocketAddrV4`] into a [`SocketAddr::V4`]. - #[inline] - fn from(sock4: SocketAddrV4) -> SocketAddr { - SocketAddr::V4(sock4) - } -} - -#[stable(feature = "ip_from_ip", since = "1.16.0")] -impl From for SocketAddr { - /// Converts a [`SocketAddrV6`] into a [`SocketAddr::V6`]. - #[inline] - fn from(sock6: SocketAddrV6) -> SocketAddr { - SocketAddr::V6(sock6) - } -} - -#[stable(feature = "addr_from_into_ip", since = "1.17.0")] -impl> From<(I, u16)> for SocketAddr { - /// Converts a tuple struct (Into<[`IpAddr`]>, `u16`) into a [`SocketAddr`]. - /// - /// This conversion creates a [`SocketAddr::V4`] for an [`IpAddr::V4`] - /// and creates a [`SocketAddr::V6`] for an [`IpAddr::V6`]. - /// - /// `u16` is treated as port of the newly created [`SocketAddr`]. - fn from(pieces: (I, u16)) -> SocketAddr { - SocketAddr::new(pieces.0.into(), pieces.1) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for SocketAddr { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - match *self { - SocketAddr::V4(ref a) => a.fmt(f), - SocketAddr::V6(ref a) => a.fmt(f), - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for SocketAddr { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt(self, fmt) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for SocketAddrV4 { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - // If there are no alignment requirements, write the socket address directly to `f`. - // Otherwise, write it to a local buffer and then use `f.pad`. - if f.precision().is_none() && f.width().is_none() { - write!(f, "{}:{}", self.ip(), self.port()) - } else { - const LONGEST_IPV4_SOCKET_ADDR: &str = "255.255.255.255:65535"; - - let mut buf = DisplayBuffer::<{ LONGEST_IPV4_SOCKET_ADDR.len() }>::new(); - // Buffer is long enough for the longest possible IPv4 socket address, so this should never fail. - write!(buf, "{}:{}", self.ip(), self.port()).unwrap(); - - f.pad(buf.as_str()) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for SocketAddrV4 { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt(self, fmt) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for SocketAddrV6 { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - // If there are no alignment requirements, write the socket address directly to `f`. - // Otherwise, write it to a local buffer and then use `f.pad`. - if f.precision().is_none() && f.width().is_none() { - match self.scope_id() { - 0 => write!(f, "[{}]:{}", self.ip(), self.port()), - scope_id => write!(f, "[{}%{}]:{}", self.ip(), scope_id, self.port()), - } - } else { - const LONGEST_IPV6_SOCKET_ADDR: &str = - "[ffff:ffff:ffff:ffff:ffff:ffff:ffff:ffff%4294967295]:65535"; - - let mut buf = DisplayBuffer::<{ LONGEST_IPV6_SOCKET_ADDR.len() }>::new(); - match self.scope_id() { - 0 => write!(buf, "[{}]:{}", self.ip(), self.port()), - scope_id => write!(buf, "[{}%{}]:{}", self.ip(), scope_id, self.port()), - } - // Buffer is long enough for the longest possible IPv6 socket address, so this should never fail. - .unwrap(); - - f.pad(buf.as_str()) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for SocketAddrV6 { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt(self, fmt) - } -} diff --git a/library/core/src/num/bignum.rs b/library/core/src/num/bignum.rs deleted file mode 100644 index d2a21b6b38260..0000000000000 --- a/library/core/src/num/bignum.rs +++ /dev/null @@ -1,434 +0,0 @@ -//! Custom arbitrary-precision number (bignum) implementation. -//! -//! This is designed to avoid the heap allocation at expense of stack memory. -//! The most used bignum type, `Big32x40`, is limited by 32 × 40 = 1,280 bits -//! and will take at most 160 bytes of stack memory. This is more than enough -//! for round-tripping all possible finite `f64` values. -//! -//! In principle it is possible to have multiple bignum types for different -//! inputs, but we don't do so to avoid the code bloat. Each bignum is still -//! tracked for the actual usages, so it normally doesn't matter. - -// This module is only for dec2flt and flt2dec, and only public because of coretests. -// It is not intended to ever be stabilized. -#![doc(hidden)] -#![unstable( - feature = "core_private_bignum", - reason = "internal routines only exposed for testing", - issue = "none" -)] -#![macro_use] - -/// Arithmetic operations required by bignums. -pub trait FullOps: Sized { - /// Returns `(carry', v')` such that `carry' * 2^W + v' = self * other + other2 + carry`, - /// where `W` is the number of bits in `Self`. - fn full_mul_add(self, other: Self, other2: Self, carry: Self) -> (Self /* carry */, Self); - - /// Returns `(quo, rem)` such that `borrow * 2^W + self = quo * other + rem` - /// and `0 <= rem < other`, where `W` is the number of bits in `Self`. - fn full_div_rem(self, other: Self, borrow: Self) - -> (Self /* quotient */, Self /* remainder */); -} - -macro_rules! impl_full_ops { - ($($ty:ty: add($addfn:path), mul/div($bigty:ident);)*) => ( - $( - impl FullOps for $ty { - fn full_mul_add(self, other: $ty, other2: $ty, carry: $ty) -> ($ty, $ty) { - // This cannot overflow; - // the output is between `0` and `2^nbits * (2^nbits - 1)`. - let v = (self as $bigty) * (other as $bigty) + (other2 as $bigty) + - (carry as $bigty); - ((v >> <$ty>::BITS) as $ty, v as $ty) - } - - fn full_div_rem(self, other: $ty, borrow: $ty) -> ($ty, $ty) { - debug_assert!(borrow < other); - // This cannot overflow; the output is between `0` and `other * (2^nbits - 1)`. - let lhs = ((borrow as $bigty) << <$ty>::BITS) | (self as $bigty); - let rhs = other as $bigty; - ((lhs / rhs) as $ty, (lhs % rhs) as $ty) - } - } - )* - ) -} - -impl_full_ops! { - u8: add(intrinsics::u8_add_with_overflow), mul/div(u16); - u16: add(intrinsics::u16_add_with_overflow), mul/div(u32); - u32: add(intrinsics::u32_add_with_overflow), mul/div(u64); - // See RFC #521 for enabling this. - // u64: add(intrinsics::u64_add_with_overflow), mul/div(u128); -} - -/// Table of powers of 5 representable in digits. Specifically, the largest {u8, u16, u32} value -/// that's a power of five, plus the corresponding exponent. Used in `mul_pow5`. -const SMALL_POW5: [(u64, usize); 3] = [(125, 3), (15625, 6), (1_220_703_125, 13)]; - -macro_rules! define_bignum { - ($name:ident: type=$ty:ty, n=$n:expr) => { - /// Stack-allocated arbitrary-precision (up to certain limit) integer. - /// - /// This is backed by a fixed-size array of given type ("digit"). - /// While the array is not very large (normally some hundred bytes), - /// copying it recklessly may result in the performance hit. - /// Thus this is intentionally not `Copy`. - /// - /// All operations available to bignums panic in the case of overflows. - /// The caller is responsible to use large enough bignum types. - pub struct $name { - /// One plus the offset to the maximum "digit" in use. - /// This does not decrease, so be aware of the computation order. - /// `base[size..]` should be zero. - size: usize, - /// Digits. `[a, b, c, ...]` represents `a + b*2^W + c*2^(2W) + ...` - /// where `W` is the number of bits in the digit type. - base: [$ty; $n], - } - - impl $name { - /// Makes a bignum from one digit. - pub fn from_small(v: $ty) -> $name { - let mut base = [0; $n]; - base[0] = v; - $name { size: 1, base } - } - - /// Makes a bignum from `u64` value. - pub fn from_u64(mut v: u64) -> $name { - let mut base = [0; $n]; - let mut sz = 0; - while v > 0 { - base[sz] = v as $ty; - v >>= <$ty>::BITS; - sz += 1; - } - $name { size: sz, base } - } - - /// Returns the internal digits as a slice `[a, b, c, ...]` such that the numeric - /// value is `a + b * 2^W + c * 2^(2W) + ...` where `W` is the number of bits in - /// the digit type. - pub fn digits(&self) -> &[$ty] { - &self.base[..self.size] - } - - /// Returns the `i`-th bit where bit 0 is the least significant one. - /// In other words, the bit with weight `2^i`. - pub fn get_bit(&self, i: usize) -> u8 { - let digitbits = <$ty>::BITS as usize; - let d = i / digitbits; - let b = i % digitbits; - ((self.base[d] >> b) & 1) as u8 - } - - /// Returns `true` if the bignum is zero. - pub fn is_zero(&self) -> bool { - self.digits().iter().all(|&v| v == 0) - } - - /// Returns the number of bits necessary to represent this value. Note that zero - /// is considered to need 0 bits. - pub fn bit_length(&self) -> usize { - let digitbits = <$ty>::BITS as usize; - let digits = self.digits(); - // Find the most significant non-zero digit. - let msd = digits.iter().rposition(|&x| x != 0); - match msd { - Some(msd) => msd * digitbits + digits[msd].ilog2() as usize + 1, - // There are no non-zero digits, i.e., the number is zero. - _ => 0, - } - } - - /// Adds `other` to itself and returns its own mutable reference. - pub fn add<'a>(&'a mut self, other: &$name) -> &'a mut $name { - use crate::cmp; - use crate::iter; - - let mut sz = cmp::max(self.size, other.size); - let mut carry = false; - for (a, b) in iter::zip(&mut self.base[..sz], &other.base[..sz]) { - let (v, c) = (*a).carrying_add(*b, carry); - *a = v; - carry = c; - } - if carry { - self.base[sz] = 1; - sz += 1; - } - self.size = sz; - self - } - - pub fn add_small(&mut self, other: $ty) -> &mut $name { - let (v, mut carry) = self.base[0].carrying_add(other, false); - self.base[0] = v; - let mut i = 1; - while carry { - let (v, c) = self.base[i].carrying_add(0, carry); - self.base[i] = v; - carry = c; - i += 1; - } - if i > self.size { - self.size = i; - } - self - } - - /// Subtracts `other` from itself and returns its own mutable reference. - pub fn sub<'a>(&'a mut self, other: &$name) -> &'a mut $name { - use crate::cmp; - use crate::iter; - - let sz = cmp::max(self.size, other.size); - let mut noborrow = true; - for (a, b) in iter::zip(&mut self.base[..sz], &other.base[..sz]) { - let (v, c) = (*a).carrying_add(!*b, noborrow); - *a = v; - noborrow = c; - } - assert!(noborrow); - self.size = sz; - self - } - - /// Multiplies itself by a digit-sized `other` and returns its own - /// mutable reference. - pub fn mul_small(&mut self, other: $ty) -> &mut $name { - let mut sz = self.size; - let mut carry = 0; - for a in &mut self.base[..sz] { - let (v, c) = (*a).carrying_mul(other, carry); - *a = v; - carry = c; - } - if carry > 0 { - self.base[sz] = carry; - sz += 1; - } - self.size = sz; - self - } - - /// Multiplies itself by `2^bits` and returns its own mutable reference. - pub fn mul_pow2(&mut self, bits: usize) -> &mut $name { - let digitbits = <$ty>::BITS as usize; - let digits = bits / digitbits; - let bits = bits % digitbits; - - assert!(digits < $n); - debug_assert!(self.base[$n - digits..].iter().all(|&v| v == 0)); - debug_assert!(bits == 0 || (self.base[$n - digits - 1] >> (digitbits - bits)) == 0); - - // shift by `digits * digitbits` bits - for i in (0..self.size).rev() { - self.base[i + digits] = self.base[i]; - } - for i in 0..digits { - self.base[i] = 0; - } - - // shift by `bits` bits - let mut sz = self.size + digits; - if bits > 0 { - let last = sz; - let overflow = self.base[last - 1] >> (digitbits - bits); - if overflow > 0 { - self.base[last] = overflow; - sz += 1; - } - for i in (digits + 1..last).rev() { - self.base[i] = - (self.base[i] << bits) | (self.base[i - 1] >> (digitbits - bits)); - } - self.base[digits] <<= bits; - // self.base[..digits] is zero, no need to shift - } - - self.size = sz; - self - } - - /// Multiplies itself by `5^e` and returns its own mutable reference. - pub fn mul_pow5(&mut self, mut e: usize) -> &mut $name { - use crate::mem; - use crate::num::bignum::SMALL_POW5; - - // There are exactly n trailing zeros on 2^n, and the only relevant digit sizes - // are consecutive powers of two, so this is well suited index for the table. - let table_index = mem::size_of::<$ty>().trailing_zeros() as usize; - let (small_power, small_e) = SMALL_POW5[table_index]; - let small_power = small_power as $ty; - - // Multiply with the largest single-digit power as long as possible ... - while e >= small_e { - self.mul_small(small_power); - e -= small_e; - } - - // ... then finish off the remainder. - let mut rest_power = 1; - for _ in 0..e { - rest_power *= 5; - } - self.mul_small(rest_power); - - self - } - - /// Multiplies itself by a number described by `other[0] + other[1] * 2^W + - /// other[2] * 2^(2W) + ...` (where `W` is the number of bits in the digit type) - /// and returns its own mutable reference. - pub fn mul_digits<'a>(&'a mut self, other: &[$ty]) -> &'a mut $name { - // the internal routine. works best when aa.len() <= bb.len(). - fn mul_inner(ret: &mut [$ty; $n], aa: &[$ty], bb: &[$ty]) -> usize { - use crate::num::bignum::FullOps; - - let mut retsz = 0; - for (i, &a) in aa.iter().enumerate() { - if a == 0 { - continue; - } - let mut sz = bb.len(); - let mut carry = 0; - for (j, &b) in bb.iter().enumerate() { - let (c, v) = a.full_mul_add(b, ret[i + j], carry); - ret[i + j] = v; - carry = c; - } - if carry > 0 { - ret[i + sz] = carry; - sz += 1; - } - if retsz < i + sz { - retsz = i + sz; - } - } - retsz - } - - let mut ret = [0; $n]; - let retsz = if self.size < other.len() { - mul_inner(&mut ret, &self.digits(), other) - } else { - mul_inner(&mut ret, other, &self.digits()) - }; - self.base = ret; - self.size = retsz; - self - } - - /// Divides itself by a digit-sized `other` and returns its own - /// mutable reference *and* the remainder. - pub fn div_rem_small(&mut self, other: $ty) -> (&mut $name, $ty) { - use crate::num::bignum::FullOps; - - assert!(other > 0); - - let sz = self.size; - let mut borrow = 0; - for a in self.base[..sz].iter_mut().rev() { - let (q, r) = (*a).full_div_rem(other, borrow); - *a = q; - borrow = r; - } - (self, borrow) - } - - /// Divide self by another bignum, overwriting `q` with the quotient and `r` with the - /// remainder. - pub fn div_rem(&self, d: &$name, q: &mut $name, r: &mut $name) { - // Stupid slow base-2 long division taken from - // https://en.wikipedia.org/wiki/Division_algorithm - // FIXME use a greater base ($ty) for the long division. - assert!(!d.is_zero()); - let digitbits = <$ty>::BITS as usize; - for digit in &mut q.base[..] { - *digit = 0; - } - for digit in &mut r.base[..] { - *digit = 0; - } - r.size = d.size; - q.size = 1; - let mut q_is_zero = true; - let end = self.bit_length(); - for i in (0..end).rev() { - r.mul_pow2(1); - r.base[0] |= self.get_bit(i) as $ty; - if &*r >= d { - r.sub(d); - // Set bit `i` of q to 1. - let digit_idx = i / digitbits; - let bit_idx = i % digitbits; - if q_is_zero { - q.size = digit_idx + 1; - q_is_zero = false; - } - q.base[digit_idx] |= 1 << bit_idx; - } - } - debug_assert!(q.base[q.size..].iter().all(|&d| d == 0)); - debug_assert!(r.base[r.size..].iter().all(|&d| d == 0)); - } - } - - impl crate::cmp::PartialEq for $name { - fn eq(&self, other: &$name) -> bool { - self.base[..] == other.base[..] - } - } - - impl crate::cmp::Eq for $name {} - - impl crate::cmp::PartialOrd for $name { - fn partial_cmp(&self, other: &$name) -> crate::option::Option { - crate::option::Option::Some(self.cmp(other)) - } - } - - impl crate::cmp::Ord for $name { - fn cmp(&self, other: &$name) -> crate::cmp::Ordering { - use crate::cmp::max; - let sz = max(self.size, other.size); - let lhs = self.base[..sz].iter().cloned().rev(); - let rhs = other.base[..sz].iter().cloned().rev(); - lhs.cmp(rhs) - } - } - - impl crate::clone::Clone for $name { - fn clone(&self) -> Self { - Self { size: self.size, base: self.base } - } - } - - impl crate::fmt::Debug for $name { - fn fmt(&self, f: &mut crate::fmt::Formatter<'_>) -> crate::fmt::Result { - let sz = if self.size < 1 { 1 } else { self.size }; - let digitlen = <$ty>::BITS as usize / 4; - - write!(f, "{:#x}", self.base[sz - 1])?; - for &v in self.base[..sz - 1].iter().rev() { - write!(f, "_{:01$x}", v, digitlen)?; - } - crate::result::Result::Ok(()) - } - } - }; -} - -/// The digit type for `Big32x40`. -pub type Digit32 = u32; - -define_bignum!(Big32x40: type=Digit32, n=40); - -// this one is used for testing only. -#[doc(hidden)] -pub mod tests { - define_bignum!(Big8x3: type=u8, n=3); -} diff --git a/library/core/src/num/dec2flt/common.rs b/library/core/src/num/dec2flt/common.rs deleted file mode 100644 index 11a626485191c..0000000000000 --- a/library/core/src/num/dec2flt/common.rs +++ /dev/null @@ -1,81 +0,0 @@ -//! Common utilities, for internal use only. - -/// Helper methods to process immutable bytes. -pub(crate) trait ByteSlice { - /// Read 8 bytes as a 64-bit integer in little-endian order. - fn read_u64(&self) -> u64; - - /// Write a 64-bit integer as 8 bytes in little-endian order. - fn write_u64(&mut self, value: u64); - - /// Calculate the offset of a slice from another. - fn offset_from(&self, other: &Self) -> isize; - - /// Iteratively parse and consume digits from bytes. - /// Returns the same bytes with consumed digits being - /// elided. - fn parse_digits(&self, func: impl FnMut(u8)) -> &Self; -} - -impl ByteSlice for [u8] { - #[inline(always)] // inlining this is crucial to remove bound checks - fn read_u64(&self) -> u64 { - let mut tmp = [0; 8]; - tmp.copy_from_slice(&self[..8]); - u64::from_le_bytes(tmp) - } - - #[inline(always)] // inlining this is crucial to remove bound checks - fn write_u64(&mut self, value: u64) { - self[..8].copy_from_slice(&value.to_le_bytes()) - } - - #[inline] - fn offset_from(&self, other: &Self) -> isize { - other.len() as isize - self.len() as isize - } - - #[inline] - fn parse_digits(&self, mut func: impl FnMut(u8)) -> &Self { - let mut s = self; - - // FIXME: Can't use s.split_first() here yet, - // see https://github.com/rust-lang/rust/issues/109328 - while let [c, s_next @ ..] = s { - let c = c.wrapping_sub(b'0'); - if c < 10 { - func(c); - s = s_next; - } else { - break; - } - } - - s - } -} - -/// Determine if 8 bytes are all decimal digits. -/// This does not care about the order in which the bytes were loaded. -pub(crate) fn is_8digits(v: u64) -> bool { - let a = v.wrapping_add(0x4646_4646_4646_4646); - let b = v.wrapping_sub(0x3030_3030_3030_3030); - (a | b) & 0x8080_8080_8080_8080 == 0 -} - -/// A custom 64-bit floating point type, representing `f * 2^e`. -/// e is biased, so it be directly shifted into the exponent bits. -#[derive(Debug, Copy, Clone, PartialEq, Eq, Default)] -pub struct BiasedFp { - /// The significant digits. - pub f: u64, - /// The biased, binary exponent. - pub e: i32, -} - -impl BiasedFp { - #[inline] - pub const fn zero_pow2(e: i32) -> Self { - Self { f: 0, e } - } -} diff --git a/library/core/src/num/dec2flt/decimal.rs b/library/core/src/num/dec2flt/decimal.rs deleted file mode 100644 index 350f64bb4f7a3..0000000000000 --- a/library/core/src/num/dec2flt/decimal.rs +++ /dev/null @@ -1,358 +0,0 @@ -//! Arbitrary-precision decimal class for fallback algorithms. -//! -//! This is only used if the fast-path (native floats) and -//! the Eisel-Lemire algorithm are unable to unambiguously -//! determine the float. -//! -//! The technique used is "Simple Decimal Conversion", developed -//! by Nigel Tao and Ken Thompson. A detailed description of the -//! algorithm can be found in "ParseNumberF64 by Simple Decimal Conversion", -//! available online: . - -use crate::num::dec2flt::common::{is_8digits, ByteSlice}; - -#[derive(Clone)] -pub struct Decimal { - /// The number of significant digits in the decimal. - pub num_digits: usize, - /// The offset of the decimal point in the significant digits. - pub decimal_point: i32, - /// If the number of significant digits stored in the decimal is truncated. - pub truncated: bool, - /// Buffer of the raw digits, in the range [0, 9]. - pub digits: [u8; Self::MAX_DIGITS], -} - -impl Default for Decimal { - fn default() -> Self { - Self { num_digits: 0, decimal_point: 0, truncated: false, digits: [0; Self::MAX_DIGITS] } - } -} - -impl Decimal { - /// The maximum number of digits required to unambiguously round a float. - /// - /// For a double-precision IEEE 754 float, this required 767 digits, - /// so we store the max digits + 1. - /// - /// We can exactly represent a float in radix `b` from radix 2 if - /// `b` is divisible by 2. This function calculates the exact number of - /// digits required to exactly represent that float. - /// - /// According to the "Handbook of Floating Point Arithmetic", - /// for IEEE754, with emin being the min exponent, p2 being the - /// precision, and b being the radix, the number of digits follows as: - /// - /// `−emin + p2 + ⌊(emin + 1) log(2, b) − log(1 − 2^(−p2), b)⌋` - /// - /// For f32, this follows as: - /// emin = -126 - /// p2 = 24 - /// - /// For f64, this follows as: - /// emin = -1022 - /// p2 = 53 - /// - /// In Python: - /// `-emin + p2 + math.floor((emin+ 1)*math.log(2, b)-math.log(1-2**(-p2), b))` - pub const MAX_DIGITS: usize = 768; - /// The max digits that can be exactly represented in a 64-bit integer. - pub const MAX_DIGITS_WITHOUT_OVERFLOW: usize = 19; - pub const DECIMAL_POINT_RANGE: i32 = 2047; - - /// Append a digit to the buffer. - pub fn try_add_digit(&mut self, digit: u8) { - if self.num_digits < Self::MAX_DIGITS { - self.digits[self.num_digits] = digit; - } - self.num_digits += 1; - } - - /// Trim trailing zeros from the buffer. - pub fn trim(&mut self) { - // All of the following calls to `Decimal::trim` can't panic because: - // - // 1. `parse_decimal` sets `num_digits` to a max of `Decimal::MAX_DIGITS`. - // 2. `right_shift` sets `num_digits` to `write_index`, which is bounded by `num_digits`. - // 3. `left_shift` `num_digits` to a max of `Decimal::MAX_DIGITS`. - // - // Trim is only called in `right_shift` and `left_shift`. - debug_assert!(self.num_digits <= Self::MAX_DIGITS); - while self.num_digits != 0 && self.digits[self.num_digits - 1] == 0 { - self.num_digits -= 1; - } - } - - pub fn round(&self) -> u64 { - if self.num_digits == 0 || self.decimal_point < 0 { - return 0; - } else if self.decimal_point > 18 { - return 0xFFFF_FFFF_FFFF_FFFF_u64; - } - let dp = self.decimal_point as usize; - let mut n = 0_u64; - for i in 0..dp { - n *= 10; - if i < self.num_digits { - n += self.digits[i] as u64; - } - } - let mut round_up = false; - if dp < self.num_digits { - round_up = self.digits[dp] >= 5; - if self.digits[dp] == 5 && dp + 1 == self.num_digits { - round_up = self.truncated || ((dp != 0) && (1 & self.digits[dp - 1] != 0)) - } - } - if round_up { - n += 1; - } - n - } - - /// Computes decimal * 2^shift. - pub fn left_shift(&mut self, shift: usize) { - if self.num_digits == 0 { - return; - } - let num_new_digits = number_of_digits_decimal_left_shift(self, shift); - let mut read_index = self.num_digits; - let mut write_index = self.num_digits + num_new_digits; - let mut n = 0_u64; - while read_index != 0 { - read_index -= 1; - write_index -= 1; - n += (self.digits[read_index] as u64) << shift; - let quotient = n / 10; - let remainder = n - (10 * quotient); - if write_index < Self::MAX_DIGITS { - self.digits[write_index] = remainder as u8; - } else if remainder > 0 { - self.truncated = true; - } - n = quotient; - } - while n > 0 { - write_index -= 1; - let quotient = n / 10; - let remainder = n - (10 * quotient); - if write_index < Self::MAX_DIGITS { - self.digits[write_index] = remainder as u8; - } else if remainder > 0 { - self.truncated = true; - } - n = quotient; - } - self.num_digits += num_new_digits; - if self.num_digits > Self::MAX_DIGITS { - self.num_digits = Self::MAX_DIGITS; - } - self.decimal_point += num_new_digits as i32; - self.trim(); - } - - /// Computes decimal * 2^-shift. - pub fn right_shift(&mut self, shift: usize) { - let mut read_index = 0; - let mut write_index = 0; - let mut n = 0_u64; - while (n >> shift) == 0 { - if read_index < self.num_digits { - n = (10 * n) + self.digits[read_index] as u64; - read_index += 1; - } else if n == 0 { - return; - } else { - while (n >> shift) == 0 { - n *= 10; - read_index += 1; - } - break; - } - } - self.decimal_point -= read_index as i32 - 1; - if self.decimal_point < -Self::DECIMAL_POINT_RANGE { - // `self = Self::Default()`, but without the overhead of clearing `digits`. - self.num_digits = 0; - self.decimal_point = 0; - self.truncated = false; - return; - } - let mask = (1_u64 << shift) - 1; - while read_index < self.num_digits { - let new_digit = (n >> shift) as u8; - n = (10 * (n & mask)) + self.digits[read_index] as u64; - read_index += 1; - self.digits[write_index] = new_digit; - write_index += 1; - } - while n > 0 { - let new_digit = (n >> shift) as u8; - n = 10 * (n & mask); - if write_index < Self::MAX_DIGITS { - self.digits[write_index] = new_digit; - write_index += 1; - } else if new_digit > 0 { - self.truncated = true; - } - } - self.num_digits = write_index; - self.trim(); - } -} - -/// Parse a big integer representation of the float as a decimal. -pub fn parse_decimal(mut s: &[u8]) -> Decimal { - let mut d = Decimal::default(); - let start = s; - - while let Some((&b'0', s_next)) = s.split_first() { - s = s_next; - } - - s = s.parse_digits(|digit| d.try_add_digit(digit)); - - if let Some((b'.', s_next)) = s.split_first() { - s = s_next; - let first = s; - // Skip leading zeros. - if d.num_digits == 0 { - while let Some((&b'0', s_next)) = s.split_first() { - s = s_next; - } - } - while s.len() >= 8 && d.num_digits + 8 < Decimal::MAX_DIGITS { - let v = s.read_u64(); - if !is_8digits(v) { - break; - } - d.digits[d.num_digits..].write_u64(v - 0x3030_3030_3030_3030); - d.num_digits += 8; - s = &s[8..]; - } - s = s.parse_digits(|digit| d.try_add_digit(digit)); - d.decimal_point = s.len() as i32 - first.len() as i32; - } - if d.num_digits != 0 { - // Ignore the trailing zeros if there are any - let mut n_trailing_zeros = 0; - for &c in start[..(start.len() - s.len())].iter().rev() { - if c == b'0' { - n_trailing_zeros += 1; - } else if c != b'.' { - break; - } - } - d.decimal_point += n_trailing_zeros as i32; - d.num_digits -= n_trailing_zeros; - d.decimal_point += d.num_digits as i32; - if d.num_digits > Decimal::MAX_DIGITS { - d.truncated = true; - d.num_digits = Decimal::MAX_DIGITS; - } - } - if let Some((&ch, s_next)) = s.split_first() { - if ch == b'e' || ch == b'E' { - s = s_next; - let mut neg_exp = false; - if let Some((&ch, s_next)) = s.split_first() { - neg_exp = ch == b'-'; - if ch == b'-' || ch == b'+' { - s = s_next; - } - } - let mut exp_num = 0_i32; - - s.parse_digits(|digit| { - if exp_num < 0x10000 { - exp_num = 10 * exp_num + digit as i32; - } - }); - - d.decimal_point += if neg_exp { -exp_num } else { exp_num }; - } - } - for i in d.num_digits..Decimal::MAX_DIGITS_WITHOUT_OVERFLOW { - d.digits[i] = 0; - } - d -} - -fn number_of_digits_decimal_left_shift(d: &Decimal, mut shift: usize) -> usize { - #[rustfmt::skip] - const TABLE: [u16; 65] = [ - 0x0000, 0x0800, 0x0801, 0x0803, 0x1006, 0x1009, 0x100D, 0x1812, 0x1817, 0x181D, 0x2024, - 0x202B, 0x2033, 0x203C, 0x2846, 0x2850, 0x285B, 0x3067, 0x3073, 0x3080, 0x388E, 0x389C, - 0x38AB, 0x38BB, 0x40CC, 0x40DD, 0x40EF, 0x4902, 0x4915, 0x4929, 0x513E, 0x5153, 0x5169, - 0x5180, 0x5998, 0x59B0, 0x59C9, 0x61E3, 0x61FD, 0x6218, 0x6A34, 0x6A50, 0x6A6D, 0x6A8B, - 0x72AA, 0x72C9, 0x72E9, 0x7B0A, 0x7B2B, 0x7B4D, 0x8370, 0x8393, 0x83B7, 0x83DC, 0x8C02, - 0x8C28, 0x8C4F, 0x9477, 0x949F, 0x94C8, 0x9CF2, 0x051C, 0x051C, 0x051C, 0x051C, - ]; - #[rustfmt::skip] - const TABLE_POW5: [u8; 0x051C] = [ - 5, 2, 5, 1, 2, 5, 6, 2, 5, 3, 1, 2, 5, 1, 5, 6, 2, 5, 7, 8, 1, 2, 5, 3, 9, 0, 6, 2, 5, 1, - 9, 5, 3, 1, 2, 5, 9, 7, 6, 5, 6, 2, 5, 4, 8, 8, 2, 8, 1, 2, 5, 2, 4, 4, 1, 4, 0, 6, 2, 5, - 1, 2, 2, 0, 7, 0, 3, 1, 2, 5, 6, 1, 0, 3, 5, 1, 5, 6, 2, 5, 3, 0, 5, 1, 7, 5, 7, 8, 1, 2, - 5, 1, 5, 2, 5, 8, 7, 8, 9, 0, 6, 2, 5, 7, 6, 2, 9, 3, 9, 4, 5, 3, 1, 2, 5, 3, 8, 1, 4, 6, - 9, 7, 2, 6, 5, 6, 2, 5, 1, 9, 0, 7, 3, 4, 8, 6, 3, 2, 8, 1, 2, 5, 9, 5, 3, 6, 7, 4, 3, 1, - 6, 4, 0, 6, 2, 5, 4, 7, 6, 8, 3, 7, 1, 5, 8, 2, 0, 3, 1, 2, 5, 2, 3, 8, 4, 1, 8, 5, 7, 9, - 1, 0, 1, 5, 6, 2, 5, 1, 1, 9, 2, 0, 9, 2, 8, 9, 5, 5, 0, 7, 8, 1, 2, 5, 5, 9, 6, 0, 4, 6, - 4, 4, 7, 7, 5, 3, 9, 0, 6, 2, 5, 2, 9, 8, 0, 2, 3, 2, 2, 3, 8, 7, 6, 9, 5, 3, 1, 2, 5, 1, - 4, 9, 0, 1, 1, 6, 1, 1, 9, 3, 8, 4, 7, 6, 5, 6, 2, 5, 7, 4, 5, 0, 5, 8, 0, 5, 9, 6, 9, 2, - 3, 8, 2, 8, 1, 2, 5, 3, 7, 2, 5, 2, 9, 0, 2, 9, 8, 4, 6, 1, 9, 1, 4, 0, 6, 2, 5, 1, 8, 6, - 2, 6, 4, 5, 1, 4, 9, 2, 3, 0, 9, 5, 7, 0, 3, 1, 2, 5, 9, 3, 1, 3, 2, 2, 5, 7, 4, 6, 1, 5, - 4, 7, 8, 5, 1, 5, 6, 2, 5, 4, 6, 5, 6, 6, 1, 2, 8, 7, 3, 0, 7, 7, 3, 9, 2, 5, 7, 8, 1, 2, - 5, 2, 3, 2, 8, 3, 0, 6, 4, 3, 6, 5, 3, 8, 6, 9, 6, 2, 8, 9, 0, 6, 2, 5, 1, 1, 6, 4, 1, 5, - 3, 2, 1, 8, 2, 6, 9, 3, 4, 8, 1, 4, 4, 5, 3, 1, 2, 5, 5, 8, 2, 0, 7, 6, 6, 0, 9, 1, 3, 4, - 6, 7, 4, 0, 7, 2, 2, 6, 5, 6, 2, 5, 2, 9, 1, 0, 3, 8, 3, 0, 4, 5, 6, 7, 3, 3, 7, 0, 3, 6, - 1, 3, 2, 8, 1, 2, 5, 1, 4, 5, 5, 1, 9, 1, 5, 2, 2, 8, 3, 6, 6, 8, 5, 1, 8, 0, 6, 6, 4, 0, - 6, 2, 5, 7, 2, 7, 5, 9, 5, 7, 6, 1, 4, 1, 8, 3, 4, 2, 5, 9, 0, 3, 3, 2, 0, 3, 1, 2, 5, 3, - 6, 3, 7, 9, 7, 8, 8, 0, 7, 0, 9, 1, 7, 1, 2, 9, 5, 1, 6, 6, 0, 1, 5, 6, 2, 5, 1, 8, 1, 8, - 9, 8, 9, 4, 0, 3, 5, 4, 5, 8, 5, 6, 4, 7, 5, 8, 3, 0, 0, 7, 8, 1, 2, 5, 9, 0, 9, 4, 9, 4, - 7, 0, 1, 7, 7, 2, 9, 2, 8, 2, 3, 7, 9, 1, 5, 0, 3, 9, 0, 6, 2, 5, 4, 5, 4, 7, 4, 7, 3, 5, - 0, 8, 8, 6, 4, 6, 4, 1, 1, 8, 9, 5, 7, 5, 1, 9, 5, 3, 1, 2, 5, 2, 2, 7, 3, 7, 3, 6, 7, 5, - 4, 4, 3, 2, 3, 2, 0, 5, 9, 4, 7, 8, 7, 5, 9, 7, 6, 5, 6, 2, 5, 1, 1, 3, 6, 8, 6, 8, 3, 7, - 7, 2, 1, 6, 1, 6, 0, 2, 9, 7, 3, 9, 3, 7, 9, 8, 8, 2, 8, 1, 2, 5, 5, 6, 8, 4, 3, 4, 1, 8, - 8, 6, 0, 8, 0, 8, 0, 1, 4, 8, 6, 9, 6, 8, 9, 9, 4, 1, 4, 0, 6, 2, 5, 2, 8, 4, 2, 1, 7, 0, - 9, 4, 3, 0, 4, 0, 4, 0, 0, 7, 4, 3, 4, 8, 4, 4, 9, 7, 0, 7, 0, 3, 1, 2, 5, 1, 4, 2, 1, 0, - 8, 5, 4, 7, 1, 5, 2, 0, 2, 0, 0, 3, 7, 1, 7, 4, 2, 2, 4, 8, 5, 3, 5, 1, 5, 6, 2, 5, 7, 1, - 0, 5, 4, 2, 7, 3, 5, 7, 6, 0, 1, 0, 0, 1, 8, 5, 8, 7, 1, 1, 2, 4, 2, 6, 7, 5, 7, 8, 1, 2, - 5, 3, 5, 5, 2, 7, 1, 3, 6, 7, 8, 8, 0, 0, 5, 0, 0, 9, 2, 9, 3, 5, 5, 6, 2, 1, 3, 3, 7, 8, - 9, 0, 6, 2, 5, 1, 7, 7, 6, 3, 5, 6, 8, 3, 9, 4, 0, 0, 2, 5, 0, 4, 6, 4, 6, 7, 7, 8, 1, 0, - 6, 6, 8, 9, 4, 5, 3, 1, 2, 5, 8, 8, 8, 1, 7, 8, 4, 1, 9, 7, 0, 0, 1, 2, 5, 2, 3, 2, 3, 3, - 8, 9, 0, 5, 3, 3, 4, 4, 7, 2, 6, 5, 6, 2, 5, 4, 4, 4, 0, 8, 9, 2, 0, 9, 8, 5, 0, 0, 6, 2, - 6, 1, 6, 1, 6, 9, 4, 5, 2, 6, 6, 7, 2, 3, 6, 3, 2, 8, 1, 2, 5, 2, 2, 2, 0, 4, 4, 6, 0, 4, - 9, 2, 5, 0, 3, 1, 3, 0, 8, 0, 8, 4, 7, 2, 6, 3, 3, 3, 6, 1, 8, 1, 6, 4, 0, 6, 2, 5, 1, 1, - 1, 0, 2, 2, 3, 0, 2, 4, 6, 2, 5, 1, 5, 6, 5, 4, 0, 4, 2, 3, 6, 3, 1, 6, 6, 8, 0, 9, 0, 8, - 2, 0, 3, 1, 2, 5, 5, 5, 5, 1, 1, 1, 5, 1, 2, 3, 1, 2, 5, 7, 8, 2, 7, 0, 2, 1, 1, 8, 1, 5, - 8, 3, 4, 0, 4, 5, 4, 1, 0, 1, 5, 6, 2, 5, 2, 7, 7, 5, 5, 5, 7, 5, 6, 1, 5, 6, 2, 8, 9, 1, - 3, 5, 1, 0, 5, 9, 0, 7, 9, 1, 7, 0, 2, 2, 7, 0, 5, 0, 7, 8, 1, 2, 5, 1, 3, 8, 7, 7, 7, 8, - 7, 8, 0, 7, 8, 1, 4, 4, 5, 6, 7, 5, 5, 2, 9, 5, 3, 9, 5, 8, 5, 1, 1, 3, 5, 2, 5, 3, 9, 0, - 6, 2, 5, 6, 9, 3, 8, 8, 9, 3, 9, 0, 3, 9, 0, 7, 2, 2, 8, 3, 7, 7, 6, 4, 7, 6, 9, 7, 9, 2, - 5, 5, 6, 7, 6, 2, 6, 9, 5, 3, 1, 2, 5, 3, 4, 6, 9, 4, 4, 6, 9, 5, 1, 9, 5, 3, 6, 1, 4, 1, - 8, 8, 8, 2, 3, 8, 4, 8, 9, 6, 2, 7, 8, 3, 8, 1, 3, 4, 7, 6, 5, 6, 2, 5, 1, 7, 3, 4, 7, 2, - 3, 4, 7, 5, 9, 7, 6, 8, 0, 7, 0, 9, 4, 4, 1, 1, 9, 2, 4, 4, 8, 1, 3, 9, 1, 9, 0, 6, 7, 3, - 8, 2, 8, 1, 2, 5, 8, 6, 7, 3, 6, 1, 7, 3, 7, 9, 8, 8, 4, 0, 3, 5, 4, 7, 2, 0, 5, 9, 6, 2, - 2, 4, 0, 6, 9, 5, 9, 5, 3, 3, 6, 9, 1, 4, 0, 6, 2, 5, - ]; - - shift &= 63; - let x_a = TABLE[shift]; - let x_b = TABLE[shift + 1]; - let num_new_digits = (x_a >> 11) as _; - let pow5_a = (0x7FF & x_a) as usize; - let pow5_b = (0x7FF & x_b) as usize; - let pow5 = &TABLE_POW5[pow5_a..]; - for (i, &p5) in pow5.iter().enumerate().take(pow5_b - pow5_a) { - if i >= d.num_digits { - return num_new_digits - 1; - } else if d.digits[i] == p5 { - continue; - } else if d.digits[i] < p5 { - return num_new_digits - 1; - } else { - return num_new_digits; - } - } - num_new_digits -} diff --git a/library/core/src/num/dec2flt/float.rs b/library/core/src/num/dec2flt/float.rs deleted file mode 100644 index 1c9d68999d6f8..0000000000000 --- a/library/core/src/num/dec2flt/float.rs +++ /dev/null @@ -1,211 +0,0 @@ -//! Helper trait for generic float types. - -use crate::fmt::{Debug, LowerExp}; -use crate::num::FpCategory; -use crate::ops::{Add, Div, Mul, Neg}; - -/// A helper trait to avoid duplicating basically all the conversion code for `f32` and `f64`. -/// -/// See the parent module's doc comment for why this is necessary. -/// -/// Should **never ever** be implemented for other types or be used outside the dec2flt module. -#[doc(hidden)] -pub trait RawFloat: - Sized - + Div - + Neg - + Mul - + Add - + LowerExp - + PartialEq - + PartialOrd - + Default - + Clone - + Copy - + Debug -{ - const INFINITY: Self; - const NEG_INFINITY: Self; - const NAN: Self; - const NEG_NAN: Self; - - /// The number of bits in the significand, *excluding* the hidden bit. - const MANTISSA_EXPLICIT_BITS: usize; - - // Round-to-even only happens for negative values of q - // when q ≥ −4 in the 64-bit case and when q ≥ −17 in - // the 32-bitcase. - // - // When q ≥ 0,we have that 5^q ≤ 2m+1. In the 64-bit case,we - // have 5^q ≤ 2m+1 ≤ 2^54 or q ≤ 23. In the 32-bit case,we have - // 5^q ≤ 2m+1 ≤ 2^25 or q ≤ 10. - // - // When q < 0, we have w ≥ (2m+1)×5^−q. We must have that w < 2^64 - // so (2m+1)×5^−q < 2^64. We have that 2m+1 > 2^53 (64-bit case) - // or 2m+1 > 2^24 (32-bit case). Hence,we must have 2^53×5^−q < 2^64 - // (64-bit) and 2^24×5^−q < 2^64 (32-bit). Hence we have 5^−q < 2^11 - // or q ≥ −4 (64-bit case) and 5^−q < 2^40 or q ≥ −17 (32-bitcase). - // - // Thus we have that we only need to round ties to even when - // we have that q ∈ [−4,23](in the 64-bit case) or q∈[−17,10] - // (in the 32-bit case). In both cases,the power of five(5^|q|) - // fits in a 64-bit word. - const MIN_EXPONENT_ROUND_TO_EVEN: i32; - const MAX_EXPONENT_ROUND_TO_EVEN: i32; - - // Minimum exponent that for a fast path case, or `-⌊(MANTISSA_EXPLICIT_BITS+1)/log2(5)⌋` - const MIN_EXPONENT_FAST_PATH: i64; - - // Maximum exponent that for a fast path case, or `⌊(MANTISSA_EXPLICIT_BITS+1)/log2(5)⌋` - const MAX_EXPONENT_FAST_PATH: i64; - - // Maximum exponent that can be represented for a disguised-fast path case. - // This is `MAX_EXPONENT_FAST_PATH + ⌊(MANTISSA_EXPLICIT_BITS+1)/log2(10)⌋` - const MAX_EXPONENT_DISGUISED_FAST_PATH: i64; - - // Minimum exponent value `-(1 << (EXP_BITS - 1)) + 1`. - const MINIMUM_EXPONENT: i32; - - // Largest exponent value `(1 << EXP_BITS) - 1`. - const INFINITE_POWER: i32; - - // Index (in bits) of the sign. - const SIGN_INDEX: usize; - - // Smallest decimal exponent for a non-zero value. - const SMALLEST_POWER_OF_TEN: i32; - - // Largest decimal exponent for a non-infinite value. - const LARGEST_POWER_OF_TEN: i32; - - // Maximum mantissa for the fast-path (`1 << 53` for f64). - const MAX_MANTISSA_FAST_PATH: u64 = 2_u64 << Self::MANTISSA_EXPLICIT_BITS; - - /// Convert integer into float through an as cast. - /// This is only called in the fast-path algorithm, and therefore - /// will not lose precision, since the value will always have - /// only if the value is <= Self::MAX_MANTISSA_FAST_PATH. - fn from_u64(v: u64) -> Self; - - /// Performs a raw transmutation from an integer. - fn from_u64_bits(v: u64) -> Self; - - /// Get a small power-of-ten for fast-path multiplication. - fn pow10_fast_path(exponent: usize) -> Self; - - /// Returns the category that this number falls into. - fn classify(self) -> FpCategory; - - /// Returns the mantissa, exponent and sign as integers. - fn integer_decode(self) -> (u64, i16, i8); -} - -impl RawFloat for f32 { - const INFINITY: Self = f32::INFINITY; - const NEG_INFINITY: Self = f32::NEG_INFINITY; - const NAN: Self = f32::NAN; - const NEG_NAN: Self = -f32::NAN; - - const MANTISSA_EXPLICIT_BITS: usize = 23; - const MIN_EXPONENT_ROUND_TO_EVEN: i32 = -17; - const MAX_EXPONENT_ROUND_TO_EVEN: i32 = 10; - const MIN_EXPONENT_FAST_PATH: i64 = -10; // assuming FLT_EVAL_METHOD = 0 - const MAX_EXPONENT_FAST_PATH: i64 = 10; - const MAX_EXPONENT_DISGUISED_FAST_PATH: i64 = 17; - const MINIMUM_EXPONENT: i32 = -127; - const INFINITE_POWER: i32 = 0xFF; - const SIGN_INDEX: usize = 31; - const SMALLEST_POWER_OF_TEN: i32 = -65; - const LARGEST_POWER_OF_TEN: i32 = 38; - - #[inline] - fn from_u64(v: u64) -> Self { - debug_assert!(v <= Self::MAX_MANTISSA_FAST_PATH); - v as _ - } - - #[inline] - fn from_u64_bits(v: u64) -> Self { - f32::from_bits((v & 0xFFFFFFFF) as u32) - } - - fn pow10_fast_path(exponent: usize) -> Self { - #[allow(clippy::use_self)] - const TABLE: [f32; 16] = - [1e0, 1e1, 1e2, 1e3, 1e4, 1e5, 1e6, 1e7, 1e8, 1e9, 1e10, 0., 0., 0., 0., 0.]; - TABLE[exponent & 15] - } - - /// Returns the mantissa, exponent and sign as integers. - fn integer_decode(self) -> (u64, i16, i8) { - let bits = self.to_bits(); - let sign: i8 = if bits >> 31 == 0 { 1 } else { -1 }; - let mut exponent: i16 = ((bits >> 23) & 0xff) as i16; - let mantissa = - if exponent == 0 { (bits & 0x7fffff) << 1 } else { (bits & 0x7fffff) | 0x800000 }; - // Exponent bias + mantissa shift - exponent -= 127 + 23; - (mantissa as u64, exponent, sign) - } - - fn classify(self) -> FpCategory { - self.classify() - } -} - -impl RawFloat for f64 { - const INFINITY: Self = f64::INFINITY; - const NEG_INFINITY: Self = f64::NEG_INFINITY; - const NAN: Self = f64::NAN; - const NEG_NAN: Self = -f64::NAN; - - const MANTISSA_EXPLICIT_BITS: usize = 52; - const MIN_EXPONENT_ROUND_TO_EVEN: i32 = -4; - const MAX_EXPONENT_ROUND_TO_EVEN: i32 = 23; - const MIN_EXPONENT_FAST_PATH: i64 = -22; // assuming FLT_EVAL_METHOD = 0 - const MAX_EXPONENT_FAST_PATH: i64 = 22; - const MAX_EXPONENT_DISGUISED_FAST_PATH: i64 = 37; - const MINIMUM_EXPONENT: i32 = -1023; - const INFINITE_POWER: i32 = 0x7FF; - const SIGN_INDEX: usize = 63; - const SMALLEST_POWER_OF_TEN: i32 = -342; - const LARGEST_POWER_OF_TEN: i32 = 308; - - #[inline] - fn from_u64(v: u64) -> Self { - debug_assert!(v <= Self::MAX_MANTISSA_FAST_PATH); - v as _ - } - - #[inline] - fn from_u64_bits(v: u64) -> Self { - f64::from_bits(v) - } - - fn pow10_fast_path(exponent: usize) -> Self { - const TABLE: [f64; 32] = [ - 1e0, 1e1, 1e2, 1e3, 1e4, 1e5, 1e6, 1e7, 1e8, 1e9, 1e10, 1e11, 1e12, 1e13, 1e14, 1e15, - 1e16, 1e17, 1e18, 1e19, 1e20, 1e21, 1e22, 0., 0., 0., 0., 0., 0., 0., 0., 0., - ]; - TABLE[exponent & 31] - } - - /// Returns the mantissa, exponent and sign as integers. - fn integer_decode(self) -> (u64, i16, i8) { - let bits = self.to_bits(); - let sign: i8 = if bits >> 63 == 0 { 1 } else { -1 }; - let mut exponent: i16 = ((bits >> 52) & 0x7ff) as i16; - let mantissa = if exponent == 0 { - (bits & 0xfffffffffffff) << 1 - } else { - (bits & 0xfffffffffffff) | 0x10000000000000 - }; - // Exponent bias + mantissa shift - exponent -= 1023 + 52; - (mantissa, exponent, sign) - } - - fn classify(self) -> FpCategory { - self.classify() - } -} diff --git a/library/core/src/num/dec2flt/fpu.rs b/library/core/src/num/dec2flt/fpu.rs deleted file mode 100644 index 8d62684f8d383..0000000000000 --- a/library/core/src/num/dec2flt/fpu.rs +++ /dev/null @@ -1,101 +0,0 @@ -//! Platform-specific, assembly instructions to avoid -//! intermediate rounding on architectures with FPUs. - -pub use fpu_precision::set_precision; - -// On x86, the x87 FPU is used for float operations if the SSE/SSE2 extensions are not available. -// The x87 FPU operates with 80 bits of precision by default, which means that operations will -// round to 80 bits causing double rounding to happen when values are eventually represented as -// 32/64 bit float values. To overcome this, the FPU control word can be set so that the -// computations are performed in the desired precision. -// -// Note that normally, it is Undefined Behavior to alter the FPU control word while Rust code runs. -// The compiler assumes that the control word is always in its default state. However, in this -// particular case the semantics with the altered control word are actually *more faithful* -// to Rust semantics than the default -- arguably it is all the code that runs *outside* of the scope -// of a `set_precision` guard that is wrong. -// In other words, we are only using this to work around . -// Sometimes killing UB with UB actually works... -// (If this is used to set 32bit precision, there is still a risk that the compiler moves some 64bit -// operation into the scope of the `set_precision` guard. So it's not like this is totally sound. -// But it's not really any less sound than the default state of 80bit precision...) -#[cfg(all(target_arch = "x86", not(target_feature = "sse2")))] -mod fpu_precision { - use core::arch::asm; - use core::mem::size_of; - - /// A structure used to preserve the original value of the FPU control word, so that it can be - /// restored when the structure is dropped. - /// - /// The x87 FPU is a 16-bits register whose fields are as follows: - /// - /// | 12-15 | 10-11 | 8-9 | 6-7 | 5 | 4 | 3 | 2 | 1 | 0 | - /// |------:|------:|----:|----:|---:|---:|---:|---:|---:|---:| - /// | | RC | PC | | PM | UM | OM | ZM | DM | IM | - /// - /// The documentation for all of the fields is available in the IA-32 Architectures Software - /// Developer's Manual (Volume 1). - /// - /// The only field which is relevant for the following code is PC, Precision Control. This - /// field determines the precision of the operations performed by the FPU. It can be set to: - /// - 0b00, single precision i.e., 32-bits - /// - 0b10, double precision i.e., 64-bits - /// - 0b11, double extended precision i.e., 80-bits (default state) - /// The 0b01 value is reserved and should not be used. - pub struct FPUControlWord(u16); - - fn set_cw(cw: u16) { - // SAFETY: the `fldcw` instruction has been audited to be able to work correctly with - // any `u16` - unsafe { - asm!( - "fldcw word ptr [{}]", - in(reg) &cw, - options(nostack), - ) - } - } - - /// Sets the precision field of the FPU to `T` and returns a `FPUControlWord`. - pub fn set_precision() -> FPUControlWord { - let mut cw = 0_u16; - - // Compute the value for the Precision Control field that is appropriate for `T`. - let cw_precision = match size_of::() { - 4 => 0x0000, // 32 bits - 8 => 0x0200, // 64 bits - _ => 0x0300, // default, 80 bits - }; - - // Get the original value of the control word to restore it later, when the - // `FPUControlWord` structure is dropped - // SAFETY: the `fnstcw` instruction has been audited to be able to work correctly with - // any `u16` - unsafe { - asm!( - "fnstcw word ptr [{}]", - in(reg) &mut cw, - options(nostack), - ) - } - - // Set the control word to the desired precision. This is achieved by masking away the old - // precision (bits 8 and 9, 0x300) and replacing it with the precision flag computed above. - set_cw((cw & 0xFCFF) | cw_precision); - - FPUControlWord(cw) - } - - impl Drop for FPUControlWord { - fn drop(&mut self) { - set_cw(self.0) - } - } -} - -// In most architectures, floating point operations have an explicit bit size, therefore the -// precision of the computation is determined on a per-operation basis. -#[cfg(any(not(target_arch = "x86"), target_feature = "sse2"))] -mod fpu_precision { - pub fn set_precision() {} -} diff --git a/library/core/src/num/dec2flt/lemire.rs b/library/core/src/num/dec2flt/lemire.rs deleted file mode 100644 index 3bc052df7a6c1..0000000000000 --- a/library/core/src/num/dec2flt/lemire.rs +++ /dev/null @@ -1,168 +0,0 @@ -//! Implementation of the Eisel-Lemire algorithm. - -use crate::num::dec2flt::common::BiasedFp; -use crate::num::dec2flt::float::RawFloat; -use crate::num::dec2flt::table::{ - LARGEST_POWER_OF_FIVE, POWER_OF_FIVE_128, SMALLEST_POWER_OF_FIVE, -}; - -/// Compute w * 10^q using an extended-precision float representation. -/// -/// Fast conversion of a the significant digits and decimal exponent -/// a float to an extended representation with a binary float. This -/// algorithm will accurately parse the vast majority of cases, -/// and uses a 128-bit representation (with a fallback 192-bit -/// representation). -/// -/// This algorithm scales the exponent by the decimal exponent -/// using pre-computed powers-of-5, and calculates if the -/// representation can be unambiguously rounded to the nearest -/// machine float. Near-halfway cases are not handled here, -/// and are represented by a negative, biased binary exponent. -/// -/// The algorithm is described in detail in "Daniel Lemire, Number Parsing -/// at a Gigabyte per Second" in section 5, "Fast Algorithm", and -/// section 6, "Exact Numbers And Ties", available online: -/// . -pub fn compute_float(q: i64, mut w: u64) -> BiasedFp { - let fp_zero = BiasedFp::zero_pow2(0); - let fp_inf = BiasedFp::zero_pow2(F::INFINITE_POWER); - let fp_error = BiasedFp::zero_pow2(-1); - - // Short-circuit if the value can only be a literal 0 or infinity. - if w == 0 || q < F::SMALLEST_POWER_OF_TEN as i64 { - return fp_zero; - } else if q > F::LARGEST_POWER_OF_TEN as i64 { - return fp_inf; - } - // Normalize our significant digits, so the most-significant bit is set. - let lz = w.leading_zeros(); - w <<= lz; - let (lo, hi) = compute_product_approx(q, w, F::MANTISSA_EXPLICIT_BITS + 3); - if lo == 0xFFFF_FFFF_FFFF_FFFF { - // If we have failed to approximate w x 5^-q with our 128-bit value. - // Since the addition of 1 could lead to an overflow which could then - // round up over the half-way point, this can lead to improper rounding - // of a float. - // - // However, this can only occur if q ∈ [-27, 55]. The upper bound of q - // is 55 because 5^55 < 2^128, however, this can only happen if 5^q > 2^64, - // since otherwise the product can be represented in 64-bits, producing - // an exact result. For negative exponents, rounding-to-even can - // only occur if 5^-q < 2^64. - // - // For detailed explanations of rounding for negative exponents, see - // . For detailed - // explanations of rounding for positive exponents, see - // . - let inside_safe_exponent = (q >= -27) && (q <= 55); - if !inside_safe_exponent { - return fp_error; - } - } - let upperbit = (hi >> 63) as i32; - let mut mantissa = hi >> (upperbit + 64 - F::MANTISSA_EXPLICIT_BITS as i32 - 3); - let mut power2 = power(q as i32) + upperbit - lz as i32 - F::MINIMUM_EXPONENT; - if power2 <= 0 { - if -power2 + 1 >= 64 { - // Have more than 64 bits below the minimum exponent, must be 0. - return fp_zero; - } - // Have a subnormal value. - mantissa >>= -power2 + 1; - mantissa += mantissa & 1; - mantissa >>= 1; - power2 = (mantissa >= (1_u64 << F::MANTISSA_EXPLICIT_BITS)) as i32; - return BiasedFp { f: mantissa, e: power2 }; - } - // Need to handle rounding ties. Normally, we need to round up, - // but if we fall right in between and we have an even basis, we - // need to round down. - // - // This will only occur if: - // 1. The lower 64 bits of the 128-bit representation is 0. - // IE, 5^q fits in single 64-bit word. - // 2. The least-significant bit prior to truncated mantissa is odd. - // 3. All the bits truncated when shifting to mantissa bits + 1 are 0. - // - // Or, we may fall between two floats: we are exactly halfway. - if lo <= 1 - && q >= F::MIN_EXPONENT_ROUND_TO_EVEN as i64 - && q <= F::MAX_EXPONENT_ROUND_TO_EVEN as i64 - && mantissa & 3 == 1 - && (mantissa << (upperbit + 64 - F::MANTISSA_EXPLICIT_BITS as i32 - 3)) == hi - { - // Zero the lowest bit, so we don't round up. - mantissa &= !1_u64; - } - // Round-to-even, then shift the significant digits into place. - mantissa += mantissa & 1; - mantissa >>= 1; - if mantissa >= (2_u64 << F::MANTISSA_EXPLICIT_BITS) { - // Rounding up overflowed, so the carry bit is set. Set the - // mantissa to 1 (only the implicit, hidden bit is set) and - // increase the exponent. - mantissa = 1_u64 << F::MANTISSA_EXPLICIT_BITS; - power2 += 1; - } - // Zero out the hidden bit. - mantissa &= !(1_u64 << F::MANTISSA_EXPLICIT_BITS); - if power2 >= F::INFINITE_POWER { - // Exponent is above largest normal value, must be infinite. - return fp_inf; - } - BiasedFp { f: mantissa, e: power2 } -} - -/// Calculate a base 2 exponent from a decimal exponent. -/// This uses a pre-computed integer approximation for -/// log2(10), where 217706 / 2^16 is accurate for the -/// entire range of non-finite decimal exponents. -#[inline] -fn power(q: i32) -> i32 { - (q.wrapping_mul(152_170 + 65536) >> 16) + 63 -} - -#[inline] -fn full_multiplication(a: u64, b: u64) -> (u64, u64) { - let r = (a as u128) * (b as u128); - (r as u64, (r >> 64) as u64) -} - -// This will compute or rather approximate w * 5**q and return a pair of 64-bit words -// approximating the result, with the "high" part corresponding to the most significant -// bits and the low part corresponding to the least significant bits. -fn compute_product_approx(q: i64, w: u64, precision: usize) -> (u64, u64) { - debug_assert!(q >= SMALLEST_POWER_OF_FIVE as i64); - debug_assert!(q <= LARGEST_POWER_OF_FIVE as i64); - debug_assert!(precision <= 64); - - let mask = if precision < 64 { - 0xFFFF_FFFF_FFFF_FFFF_u64 >> precision - } else { - 0xFFFF_FFFF_FFFF_FFFF_u64 - }; - - // 5^q < 2^64, then the multiplication always provides an exact value. - // That means whenever we need to round ties to even, we always have - // an exact value. - let index = (q - SMALLEST_POWER_OF_FIVE as i64) as usize; - let (lo5, hi5) = POWER_OF_FIVE_128[index]; - // Only need one multiplication as long as there is 1 zero but - // in the explicit mantissa bits, +1 for the hidden bit, +1 to - // determine the rounding direction, +1 for if the computed - // product has a leading zero. - let (mut first_lo, mut first_hi) = full_multiplication(w, lo5); - if first_hi & mask == mask { - // Need to do a second multiplication to get better precision - // for the lower product. This will always be exact - // where q is < 55, since 5^55 < 2^128. If this wraps, - // then we need to need to round up the hi product. - let (_, second_hi) = full_multiplication(w, hi5); - first_lo = first_lo.wrapping_add(second_hi); - if second_hi > first_lo { - first_hi += 1; - } - } - (first_lo, first_hi) -} diff --git a/library/core/src/num/dec2flt/mod.rs b/library/core/src/num/dec2flt/mod.rs deleted file mode 100644 index a4bc8b1c9b0c3..0000000000000 --- a/library/core/src/num/dec2flt/mod.rs +++ /dev/null @@ -1,276 +0,0 @@ -//! Converting decimal strings into IEEE 754 binary floating point numbers. -//! -//! # Problem statement -//! -//! We are given a decimal string such as `12.34e56`. This string consists of integral (`12`), -//! fractional (`34`), and exponent (`56`) parts. All parts are optional and interpreted as zero -//! when missing. -//! -//! We seek the IEEE 754 floating point number that is closest to the exact value of the decimal -//! string. It is well-known that many decimal strings do not have terminating representations in -//! base two, so we round to 0.5 units in the last place (in other words, as well as possible). -//! Ties, decimal values exactly half-way between two consecutive floats, are resolved with the -//! half-to-even strategy, also known as banker's rounding. -//! -//! Needless to say, this is quite hard, both in terms of implementation complexity and in terms -//! of CPU cycles taken. -//! -//! # Implementation -//! -//! First, we ignore signs. Or rather, we remove it at the very beginning of the conversion -//! process and re-apply it at the very end. This is correct in all edge cases since IEEE -//! floats are symmetric around zero, negating one simply flips the first bit. -//! -//! Then we remove the decimal point by adjusting the exponent: Conceptually, `12.34e56` turns -//! into `1234e54`, which we describe with a positive integer `f = 1234` and an integer `e = 54`. -//! The `(f, e)` representation is used by almost all code past the parsing stage. -//! -//! We then try a long chain of progressively more general and expensive special cases using -//! machine-sized integers and small, fixed-sized floating point numbers (first `f32`/`f64`, then -//! a type with 64 bit significand). The extended-precision algorithm -//! uses the Eisel-Lemire algorithm, which uses a 128-bit (or 192-bit) -//! representation that can accurately and quickly compute the vast majority -//! of floats. When all these fail, we bite the bullet and resort to using -//! a large-decimal representation, shifting the digits into range, calculating -//! the upper significant bits and exactly round to the nearest representation. -//! -//! Another aspect that needs attention is the ``RawFloat`` trait by which almost all functions -//! are parametrized. One might think that it's enough to parse to `f64` and cast the result to -//! `f32`. Unfortunately this is not the world we live in, and this has nothing to do with using -//! base two or half-to-even rounding. -//! -//! Consider for example two types `d2` and `d4` representing a decimal type with two decimal -//! digits and four decimal digits each and take "0.01499" as input. Let's use half-up rounding. -//! Going directly to two decimal digits gives `0.01`, but if we round to four digits first, -//! we get `0.0150`, which is then rounded up to `0.02`. The same principle applies to other -//! operations as well, if you want 0.5 ULP accuracy you need to do *everything* in full precision -//! and round *exactly once, at the end*, by considering all truncated bits at once. -//! -//! Primarily, this module and its children implement the algorithms described in: -//! "Number Parsing at a Gigabyte per Second", available online: -//! . -//! -//! # Other -//! -//! The conversion should *never* panic. There are assertions and explicit panics in the code, -//! but they should never be triggered and only serve as internal sanity checks. Any panics should -//! be considered a bug. -//! -//! There are unit tests but they are woefully inadequate at ensuring correctness, they only cover -//! a small percentage of possible errors. Far more extensive tests are located in the directory -//! `src/etc/test-float-parse` as a Python script. -//! -//! A note on integer overflow: Many parts of this file perform arithmetic with the decimal -//! exponent `e`. Primarily, we shift the decimal point around: Before the first decimal digit, -//! after the last decimal digit, and so on. This could overflow if done carelessly. We rely on -//! the parsing submodule to only hand out sufficiently small exponents, where "sufficient" means -//! "such that the exponent +/- the number of decimal digits fits into a 64 bit integer". -//! Larger exponents are accepted, but we don't do arithmetic with them, they are immediately -//! turned into {positive,negative} {zero,infinity}. - -#![doc(hidden)] -#![unstable( - feature = "dec2flt", - reason = "internal routines only exposed for testing", - issue = "none" -)] - -use crate::error::Error; -use crate::fmt; -use crate::str::FromStr; - -use self::common::BiasedFp; -use self::float::RawFloat; -use self::lemire::compute_float; -use self::parse::{parse_inf_nan, parse_number}; -use self::slow::parse_long_mantissa; - -mod common; -mod decimal; -mod fpu; -mod slow; -mod table; -// float is used in flt2dec, and all are used in unit tests. -pub mod float; -pub mod lemire; -pub mod number; -pub mod parse; - -macro_rules! from_str_float_impl { - ($t:ty) => { - #[stable(feature = "rust1", since = "1.0.0")] - impl FromStr for $t { - type Err = ParseFloatError; - - /// Converts a string in base 10 to a float. - /// Accepts an optional decimal exponent. - /// - /// This function accepts strings such as - /// - /// * '3.14' - /// * '-3.14' - /// * '2.5E10', or equivalently, '2.5e10' - /// * '2.5E-10' - /// * '5.' - /// * '.5', or, equivalently, '0.5' - /// * 'inf', '-inf', '+infinity', 'NaN' - /// - /// Note that alphabetical characters are not case-sensitive. - /// - /// Leading and trailing whitespace represent an error. - /// - /// # Grammar - /// - /// All strings that adhere to the following [EBNF] grammar when - /// lowercased will result in an [`Ok`] being returned: - /// - /// ```txt - /// Float ::= Sign? ( 'inf' | 'infinity' | 'nan' | Number ) - /// Number ::= ( Digit+ | - /// Digit+ '.' Digit* | - /// Digit* '.' Digit+ ) Exp? - /// Exp ::= 'e' Sign? Digit+ - /// Sign ::= [+-] - /// Digit ::= [0-9] - /// ``` - /// - /// [EBNF]: https://www.w3.org/TR/REC-xml/#sec-notation - /// - /// # Arguments - /// - /// * src - A string - /// - /// # Return value - /// - /// `Err(ParseFloatError)` if the string did not represent a valid - /// number. Otherwise, `Ok(n)` where `n` is the closest - /// representable floating-point number to the number represented - /// by `src` (following the same rules for rounding as for the - /// results of primitive operations). - // We add the `#[inline(never)]` attribute, since its content will - // be filled with that of `dec2flt`, which has #[inline(always)]. - // Since `dec2flt` is generic, a normal inline attribute on this function - // with `dec2flt` having no attributes results in heavily repeated - // generation of `dec2flt`, despite the fact only a maximum of 2 - // possible instances can ever exist. Adding #[inline(never)] avoids this. - #[inline(never)] - fn from_str(src: &str) -> Result { - dec2flt(src) - } - } - }; -} -from_str_float_impl!(f32); -from_str_float_impl!(f64); - -/// An error which can be returned when parsing a float. -/// -/// This error is used as the error type for the [`FromStr`] implementation -/// for [`f32`] and [`f64`]. -/// -/// # Example -/// -/// ``` -/// use std::str::FromStr; -/// -/// if let Err(e) = f64::from_str("a.12") { -/// println!("Failed conversion to f64: {e}"); -/// } -/// ``` -#[derive(Debug, Clone, PartialEq, Eq)] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct ParseFloatError { - kind: FloatErrorKind, -} - -#[derive(Debug, Clone, PartialEq, Eq)] -enum FloatErrorKind { - Empty, - Invalid, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Error for ParseFloatError { - #[allow(deprecated)] - fn description(&self) -> &str { - match self.kind { - FloatErrorKind::Empty => "cannot parse float from empty string", - FloatErrorKind::Invalid => "invalid float literal", - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for ParseFloatError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - #[allow(deprecated)] - self.description().fmt(f) - } -} - -#[inline] -pub(super) fn pfe_empty() -> ParseFloatError { - ParseFloatError { kind: FloatErrorKind::Empty } -} - -// Used in unit tests, keep public. -// This is much better than making FloatErrorKind and ParseFloatError::kind public. -#[inline] -pub fn pfe_invalid() -> ParseFloatError { - ParseFloatError { kind: FloatErrorKind::Invalid } -} - -/// Converts a `BiasedFp` to the closest machine float type. -fn biased_fp_to_float(x: BiasedFp) -> T { - let mut word = x.f; - word |= (x.e as u64) << T::MANTISSA_EXPLICIT_BITS; - T::from_u64_bits(word) -} - -/// Converts a decimal string into a floating point number. -#[inline(always)] // Will be inlined into a function with `#[inline(never)]`, see above -pub fn dec2flt(s: &str) -> Result { - let mut s = s.as_bytes(); - let c = if let Some(&c) = s.first() { - c - } else { - return Err(pfe_empty()); - }; - let negative = c == b'-'; - if c == b'-' || c == b'+' { - s = &s[1..]; - } - if s.is_empty() { - return Err(pfe_invalid()); - } - - let mut num = match parse_number(s) { - Some(r) => r, - None if let Some(value) = parse_inf_nan(s, negative) => return Ok(value), - None => return Err(pfe_invalid()), - }; - num.negative = negative; - if let Some(value) = num.try_fast_path::() { - return Ok(value); - } - - // If significant digits were truncated, then we can have rounding error - // only if `mantissa + 1` produces a different result. We also avoid - // redundantly using the Eisel-Lemire algorithm if it was unable to - // correctly round on the first pass. - let mut fp = compute_float::(num.exponent, num.mantissa); - if num.many_digits && fp.e >= 0 && fp != compute_float::(num.exponent, num.mantissa + 1) { - fp.e = -1; - } - // Unable to correctly round the float using the Eisel-Lemire algorithm. - // Fallback to a slower, but always correct algorithm. - if fp.e < 0 { - fp = parse_long_mantissa::(s); - } - - let mut float = biased_fp_to_float::(fp); - if num.negative { - float = -float; - } - Ok(float) -} diff --git a/library/core/src/num/dec2flt/number.rs b/library/core/src/num/dec2flt/number.rs deleted file mode 100644 index 2538991564ae4..0000000000000 --- a/library/core/src/num/dec2flt/number.rs +++ /dev/null @@ -1,88 +0,0 @@ -//! Representation of a float as the significant digits and exponent. - -use crate::num::dec2flt::float::RawFloat; -use crate::num::dec2flt::fpu::set_precision; - -#[rustfmt::skip] -const INT_POW10: [u64; 16] = [ - 1, - 10, - 100, - 1000, - 10000, - 100000, - 1000000, - 10000000, - 100000000, - 1000000000, - 10000000000, - 100000000000, - 1000000000000, - 10000000000000, - 100000000000000, - 1000000000000000, -]; - -#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] -pub struct Number { - pub exponent: i64, - pub mantissa: u64, - pub negative: bool, - pub many_digits: bool, -} - -impl Number { - /// Detect if the float can be accurately reconstructed from native floats. - #[inline] - fn is_fast_path(&self) -> bool { - F::MIN_EXPONENT_FAST_PATH <= self.exponent - && self.exponent <= F::MAX_EXPONENT_DISGUISED_FAST_PATH - && self.mantissa <= F::MAX_MANTISSA_FAST_PATH - && !self.many_digits - } - - /// The fast path algorithm using machine-sized integers and floats. - /// - /// This is extracted into a separate function so that it can be attempted before constructing - /// a Decimal. This only works if both the mantissa and the exponent - /// can be exactly represented as a machine float, since IEE-754 guarantees - /// no rounding will occur. - /// - /// There is an exception: disguised fast-path cases, where we can shift - /// powers-of-10 from the exponent to the significant digits. - pub fn try_fast_path(&self) -> Option { - // Here we need to work around . - // The fast path crucially depends on arithmetic being rounded to the correct number of bits - // without any intermediate rounding. On x86 (without SSE or SSE2) this requires the precision - // of the x87 FPU stack to be changed so that it directly rounds to 64/32 bit. - // The `set_precision` function takes care of setting the precision on architectures which - // require setting it by changing the global state (like the control word of the x87 FPU). - let _cw = set_precision::(); - - if self.is_fast_path::() { - let mut value = if self.exponent <= F::MAX_EXPONENT_FAST_PATH { - // normal fast path - let value = F::from_u64(self.mantissa); - if self.exponent < 0 { - value / F::pow10_fast_path((-self.exponent) as _) - } else { - value * F::pow10_fast_path(self.exponent as _) - } - } else { - // disguised fast path - let shift = self.exponent - F::MAX_EXPONENT_FAST_PATH; - let mantissa = self.mantissa.checked_mul(INT_POW10[shift as usize])?; - if mantissa > F::MAX_MANTISSA_FAST_PATH { - return None; - } - F::from_u64(mantissa) * F::pow10_fast_path(F::MAX_EXPONENT_FAST_PATH as _) - }; - if self.negative { - value = -value; - } - Some(value) - } else { - None - } - } -} diff --git a/library/core/src/num/dec2flt/parse.rs b/library/core/src/num/dec2flt/parse.rs deleted file mode 100644 index b0a23835c5bd4..0000000000000 --- a/library/core/src/num/dec2flt/parse.rs +++ /dev/null @@ -1,243 +0,0 @@ -//! Functions to parse floating-point numbers. - -use crate::num::dec2flt::common::{is_8digits, ByteSlice}; -use crate::num::dec2flt::float::RawFloat; -use crate::num::dec2flt::number::Number; - -const MIN_19DIGIT_INT: u64 = 100_0000_0000_0000_0000; - -/// Parse 8 digits, loaded as bytes in little-endian order. -/// -/// This uses the trick where every digit is in [0x030, 0x39], -/// and therefore can be parsed in 3 multiplications, much -/// faster than the normal 8. -/// -/// This is based off the algorithm described in "Fast numeric string to -/// int", available here: . -fn parse_8digits(mut v: u64) -> u64 { - const MASK: u64 = 0x0000_00FF_0000_00FF; - const MUL1: u64 = 0x000F_4240_0000_0064; - const MUL2: u64 = 0x0000_2710_0000_0001; - v -= 0x3030_3030_3030_3030; - v = (v * 10) + (v >> 8); // will not overflow, fits in 63 bits - let v1 = (v & MASK).wrapping_mul(MUL1); - let v2 = ((v >> 16) & MASK).wrapping_mul(MUL2); - ((v1.wrapping_add(v2) >> 32) as u32) as u64 -} - -/// Parse digits until a non-digit character is found. -fn try_parse_digits(mut s: &[u8], mut x: u64) -> (&[u8], u64) { - // may cause overflows, to be handled later - - while s.len() >= 8 { - let num = s.read_u64(); - if is_8digits(num) { - x = x.wrapping_mul(1_0000_0000).wrapping_add(parse_8digits(num)); - s = &s[8..]; - } else { - break; - } - } - - s = s.parse_digits(|digit| { - x = x.wrapping_mul(10).wrapping_add(digit as _); - }); - - (s, x) -} - -/// Parse up to 19 digits (the max that can be stored in a 64-bit integer). -fn try_parse_19digits(s_ref: &mut &[u8], x: &mut u64) { - let mut s = *s_ref; - - while *x < MIN_19DIGIT_INT { - // FIXME: Can't use s.split_first() here yet, - // see https://github.com/rust-lang/rust/issues/109328 - if let [c, s_next @ ..] = s { - let digit = c.wrapping_sub(b'0'); - - if digit < 10 { - *x = (*x * 10) + digit as u64; // no overflows here - s = s_next; - } else { - break; - } - } else { - break; - } - } - - *s_ref = s; -} - -/// Parse the scientific notation component of a float. -fn parse_scientific(s_ref: &mut &[u8]) -> Option { - let mut exponent = 0i64; - let mut negative = false; - - let mut s = *s_ref; - - if let Some((&c, s_next)) = s.split_first() { - negative = c == b'-'; - if c == b'-' || c == b'+' { - s = s_next; - } - } - - if matches!(s.first(), Some(&x) if x.is_ascii_digit()) { - *s_ref = s.parse_digits(|digit| { - // no overflows here, saturate well before overflow - if exponent < 0x10000 { - exponent = 10 * exponent + digit as i64; - } - }); - if negative { Some(-exponent) } else { Some(exponent) } - } else { - *s_ref = s; - None - } -} - -/// Parse a partial, non-special floating point number. -/// -/// This creates a representation of the float as the -/// significant digits and the decimal exponent. -fn parse_partial_number(mut s: &[u8]) -> Option<(Number, usize)> { - debug_assert!(!s.is_empty()); - - // parse initial digits before dot - let mut mantissa = 0_u64; - let start = s; - let tmp = try_parse_digits(s, mantissa); - s = tmp.0; - mantissa = tmp.1; - let mut n_digits = s.offset_from(start); - - // handle dot with the following digits - let mut n_after_dot = 0; - let mut exponent = 0_i64; - let int_end = s; - - if let Some((&b'.', s_next)) = s.split_first() { - s = s_next; - let before = s; - let tmp = try_parse_digits(s, mantissa); - s = tmp.0; - mantissa = tmp.1; - n_after_dot = s.offset_from(before); - exponent = -n_after_dot as i64; - } - - n_digits += n_after_dot; - if n_digits == 0 { - return None; - } - - // handle scientific format - let mut exp_number = 0_i64; - if let Some((&c, s_next)) = s.split_first() { - if c == b'e' || c == b'E' { - s = s_next; - // If None, we have no trailing digits after exponent, or an invalid float. - exp_number = parse_scientific(&mut s)?; - exponent += exp_number; - } - } - - let len = s.offset_from(start) as _; - - // handle uncommon case with many digits - if n_digits <= 19 { - return Some((Number { exponent, mantissa, negative: false, many_digits: false }, len)); - } - - n_digits -= 19; - let mut many_digits = false; - let mut p = start; - while let Some((&c, p_next)) = p.split_first() { - if c == b'.' || c == b'0' { - n_digits -= c.saturating_sub(b'0' - 1) as isize; - p = p_next; - } else { - break; - } - } - if n_digits > 0 { - // at this point we have more than 19 significant digits, let's try again - many_digits = true; - mantissa = 0; - let mut s = start; - try_parse_19digits(&mut s, &mut mantissa); - exponent = if mantissa >= MIN_19DIGIT_INT { - // big int - int_end.offset_from(s) - } else { - s = &s[1..]; - let before = s; - try_parse_19digits(&mut s, &mut mantissa); - -s.offset_from(before) - } as i64; - // add back the explicit part - exponent += exp_number; - } - - Some((Number { exponent, mantissa, negative: false, many_digits }, len)) -} - -/// Try to parse a non-special floating point number, -/// as well as two slices with integer and fractional parts -/// and the parsed exponent. -pub fn parse_number(s: &[u8]) -> Option { - if let Some((float, rest)) = parse_partial_number(s) { - if rest == s.len() { - return Some(float); - } - } - None -} - -/// Try to parse a special, non-finite float. -pub(crate) fn parse_inf_nan(s: &[u8], negative: bool) -> Option { - // Since a valid string has at most the length 8, we can load - // all relevant characters into a u64 and work from there. - // This also generates much better code. - - let mut register; - let len: usize; - - // All valid strings are either of length 8 or 3. - if s.len() == 8 { - register = s.read_u64(); - len = 8; - } else if s.len() == 3 { - let a = s[0] as u64; - let b = s[1] as u64; - let c = s[2] as u64; - register = (c << 16) | (b << 8) | a; - len = 3; - } else { - return None; - } - - // Clear out the bits which turn ASCII uppercase characters into - // lowercase characters. The resulting string is all uppercase. - // What happens to other characters is irrelevant. - register &= 0xDFDFDFDFDFDFDFDF; - - // u64 values corresponding to relevant cases - const INF_3: u64 = 0x464E49; // "INF" - const INF_8: u64 = 0x5954494E49464E49; // "INFINITY" - const NAN: u64 = 0x4E414E; // "NAN" - - // Match register value to constant to parse string. - // Also match on the string length to catch edge cases - // like "inf\0\0\0\0\0". - let float = match (register, len) { - (INF_3, 3) => F::INFINITY, - (INF_8, 8) => F::INFINITY, - (NAN, 3) => F::NAN, - _ => return None, - }; - - if negative { Some(-float) } else { Some(float) } -} diff --git a/library/core/src/num/dec2flt/slow.rs b/library/core/src/num/dec2flt/slow.rs deleted file mode 100644 index bf1044033e69e..0000000000000 --- a/library/core/src/num/dec2flt/slow.rs +++ /dev/null @@ -1,109 +0,0 @@ -//! Slow, fallback algorithm for cases the Eisel-Lemire algorithm cannot round. - -use crate::num::dec2flt::common::BiasedFp; -use crate::num::dec2flt::decimal::{parse_decimal, Decimal}; -use crate::num::dec2flt::float::RawFloat; - -/// Parse the significant digits and biased, binary exponent of a float. -/// -/// This is a fallback algorithm that uses a big-integer representation -/// of the float, and therefore is considerably slower than faster -/// approximations. However, it will always determine how to round -/// the significant digits to the nearest machine float, allowing -/// use to handle near half-way cases. -/// -/// Near half-way cases are halfway between two consecutive machine floats. -/// For example, the float `16777217.0` has a bitwise representation of -/// `100000000000000000000000 1`. Rounding to a single-precision float, -/// the trailing `1` is truncated. Using round-nearest, tie-even, any -/// value above `16777217.0` must be rounded up to `16777218.0`, while -/// any value before or equal to `16777217.0` must be rounded down -/// to `16777216.0`. These near-halfway conversions therefore may require -/// a large number of digits to unambiguously determine how to round. -/// -/// The algorithms described here are based on "Processing Long Numbers Quickly", -/// available here: . -pub(crate) fn parse_long_mantissa(s: &[u8]) -> BiasedFp { - const MAX_SHIFT: usize = 60; - const NUM_POWERS: usize = 19; - const POWERS: [u8; 19] = - [0, 3, 6, 9, 13, 16, 19, 23, 26, 29, 33, 36, 39, 43, 46, 49, 53, 56, 59]; - - let get_shift = |n| { - if n < NUM_POWERS { POWERS[n] as usize } else { MAX_SHIFT } - }; - - let fp_zero = BiasedFp::zero_pow2(0); - let fp_inf = BiasedFp::zero_pow2(F::INFINITE_POWER); - - let mut d = parse_decimal(s); - - // Short-circuit if the value can only be a literal 0 or infinity. - if d.num_digits == 0 || d.decimal_point < -324 { - return fp_zero; - } else if d.decimal_point >= 310 { - return fp_inf; - } - let mut exp2 = 0_i32; - // Shift right toward (1/2 ... 1]. - while d.decimal_point > 0 { - let n = d.decimal_point as usize; - let shift = get_shift(n); - d.right_shift(shift); - if d.decimal_point < -Decimal::DECIMAL_POINT_RANGE { - return fp_zero; - } - exp2 += shift as i32; - } - // Shift left toward (1/2 ... 1]. - while d.decimal_point <= 0 { - let shift = if d.decimal_point == 0 { - match d.digits[0] { - digit if digit >= 5 => break, - 0 | 1 => 2, - _ => 1, - } - } else { - get_shift((-d.decimal_point) as _) - }; - d.left_shift(shift); - if d.decimal_point > Decimal::DECIMAL_POINT_RANGE { - return fp_inf; - } - exp2 -= shift as i32; - } - // We are now in the range [1/2 ... 1] but the binary format uses [1 ... 2]. - exp2 -= 1; - while (F::MINIMUM_EXPONENT + 1) > exp2 { - let mut n = ((F::MINIMUM_EXPONENT + 1) - exp2) as usize; - if n > MAX_SHIFT { - n = MAX_SHIFT; - } - d.right_shift(n); - exp2 += n as i32; - } - if (exp2 - F::MINIMUM_EXPONENT) >= F::INFINITE_POWER { - return fp_inf; - } - // Shift the decimal to the hidden bit, and then round the value - // to get the high mantissa+1 bits. - d.left_shift(F::MANTISSA_EXPLICIT_BITS + 1); - let mut mantissa = d.round(); - if mantissa >= (1_u64 << (F::MANTISSA_EXPLICIT_BITS + 1)) { - // Rounding up overflowed to the carry bit, need to - // shift back to the hidden bit. - d.right_shift(1); - exp2 += 1; - mantissa = d.round(); - if (exp2 - F::MINIMUM_EXPONENT) >= F::INFINITE_POWER { - return fp_inf; - } - } - let mut power2 = exp2 - F::MINIMUM_EXPONENT; - if mantissa < (1_u64 << F::MANTISSA_EXPLICIT_BITS) { - power2 -= 1; - } - // Zero out all the bits above the explicit mantissa bits. - mantissa &= (1_u64 << F::MANTISSA_EXPLICIT_BITS) - 1; - BiasedFp { f: mantissa, e: power2 } -} diff --git a/library/core/src/num/dec2flt/table.rs b/library/core/src/num/dec2flt/table.rs deleted file mode 100644 index 4856074a62bd0..0000000000000 --- a/library/core/src/num/dec2flt/table.rs +++ /dev/null @@ -1,670 +0,0 @@ -//! Pre-computed tables powers-of-5 for extended-precision representations. -//! -//! These tables enable fast scaling of the significant digits -//! of a float to the decimal exponent, with minimal rounding -//! errors, in a 128 or 192-bit representation. -//! -//! DO NOT MODIFY: Generated by `src/etc/dec2flt_table.py` - -pub const SMALLEST_POWER_OF_FIVE: i32 = -342; -pub const LARGEST_POWER_OF_FIVE: i32 = 308; -pub const N_POWERS_OF_FIVE: usize = (LARGEST_POWER_OF_FIVE - SMALLEST_POWER_OF_FIVE + 1) as usize; - -// Use static to avoid long compile times: Rust compiler errors -// can have the entire table compiled multiple times, and then -// emit code multiple times, even if it's stripped out in -// the final binary. -#[rustfmt::skip] -pub static POWER_OF_FIVE_128: [(u64, u64); N_POWERS_OF_FIVE] = [ - (0xeef453d6923bd65a, 0x113faa2906a13b3f), // 5^-342 - (0x9558b4661b6565f8, 0x4ac7ca59a424c507), // 5^-341 - (0xbaaee17fa23ebf76, 0x5d79bcf00d2df649), // 5^-340 - (0xe95a99df8ace6f53, 0xf4d82c2c107973dc), // 5^-339 - (0x91d8a02bb6c10594, 0x79071b9b8a4be869), // 5^-338 - (0xb64ec836a47146f9, 0x9748e2826cdee284), // 5^-337 - (0xe3e27a444d8d98b7, 0xfd1b1b2308169b25), // 5^-336 - (0x8e6d8c6ab0787f72, 0xfe30f0f5e50e20f7), // 5^-335 - (0xb208ef855c969f4f, 0xbdbd2d335e51a935), // 5^-334 - (0xde8b2b66b3bc4723, 0xad2c788035e61382), // 5^-333 - (0x8b16fb203055ac76, 0x4c3bcb5021afcc31), // 5^-332 - (0xaddcb9e83c6b1793, 0xdf4abe242a1bbf3d), // 5^-331 - (0xd953e8624b85dd78, 0xd71d6dad34a2af0d), // 5^-330 - (0x87d4713d6f33aa6b, 0x8672648c40e5ad68), // 5^-329 - (0xa9c98d8ccb009506, 0x680efdaf511f18c2), // 5^-328 - (0xd43bf0effdc0ba48, 0x212bd1b2566def2), // 5^-327 - (0x84a57695fe98746d, 0x14bb630f7604b57), // 5^-326 - (0xa5ced43b7e3e9188, 0x419ea3bd35385e2d), // 5^-325 - (0xcf42894a5dce35ea, 0x52064cac828675b9), // 5^-324 - (0x818995ce7aa0e1b2, 0x7343efebd1940993), // 5^-323 - (0xa1ebfb4219491a1f, 0x1014ebe6c5f90bf8), // 5^-322 - (0xca66fa129f9b60a6, 0xd41a26e077774ef6), // 5^-321 - (0xfd00b897478238d0, 0x8920b098955522b4), // 5^-320 - (0x9e20735e8cb16382, 0x55b46e5f5d5535b0), // 5^-319 - (0xc5a890362fddbc62, 0xeb2189f734aa831d), // 5^-318 - (0xf712b443bbd52b7b, 0xa5e9ec7501d523e4), // 5^-317 - (0x9a6bb0aa55653b2d, 0x47b233c92125366e), // 5^-316 - (0xc1069cd4eabe89f8, 0x999ec0bb696e840a), // 5^-315 - (0xf148440a256e2c76, 0xc00670ea43ca250d), // 5^-314 - (0x96cd2a865764dbca, 0x380406926a5e5728), // 5^-313 - (0xbc807527ed3e12bc, 0xc605083704f5ecf2), // 5^-312 - (0xeba09271e88d976b, 0xf7864a44c633682e), // 5^-311 - (0x93445b8731587ea3, 0x7ab3ee6afbe0211d), // 5^-310 - (0xb8157268fdae9e4c, 0x5960ea05bad82964), // 5^-309 - (0xe61acf033d1a45df, 0x6fb92487298e33bd), // 5^-308 - (0x8fd0c16206306bab, 0xa5d3b6d479f8e056), // 5^-307 - (0xb3c4f1ba87bc8696, 0x8f48a4899877186c), // 5^-306 - (0xe0b62e2929aba83c, 0x331acdabfe94de87), // 5^-305 - (0x8c71dcd9ba0b4925, 0x9ff0c08b7f1d0b14), // 5^-304 - (0xaf8e5410288e1b6f, 0x7ecf0ae5ee44dd9), // 5^-303 - (0xdb71e91432b1a24a, 0xc9e82cd9f69d6150), // 5^-302 - (0x892731ac9faf056e, 0xbe311c083a225cd2), // 5^-301 - (0xab70fe17c79ac6ca, 0x6dbd630a48aaf406), // 5^-300 - (0xd64d3d9db981787d, 0x92cbbccdad5b108), // 5^-299 - (0x85f0468293f0eb4e, 0x25bbf56008c58ea5), // 5^-298 - (0xa76c582338ed2621, 0xaf2af2b80af6f24e), // 5^-297 - (0xd1476e2c07286faa, 0x1af5af660db4aee1), // 5^-296 - (0x82cca4db847945ca, 0x50d98d9fc890ed4d), // 5^-295 - (0xa37fce126597973c, 0xe50ff107bab528a0), // 5^-294 - (0xcc5fc196fefd7d0c, 0x1e53ed49a96272c8), // 5^-293 - (0xff77b1fcbebcdc4f, 0x25e8e89c13bb0f7a), // 5^-292 - (0x9faacf3df73609b1, 0x77b191618c54e9ac), // 5^-291 - (0xc795830d75038c1d, 0xd59df5b9ef6a2417), // 5^-290 - (0xf97ae3d0d2446f25, 0x4b0573286b44ad1d), // 5^-289 - (0x9becce62836ac577, 0x4ee367f9430aec32), // 5^-288 - (0xc2e801fb244576d5, 0x229c41f793cda73f), // 5^-287 - (0xf3a20279ed56d48a, 0x6b43527578c1110f), // 5^-286 - (0x9845418c345644d6, 0x830a13896b78aaa9), // 5^-285 - (0xbe5691ef416bd60c, 0x23cc986bc656d553), // 5^-284 - (0xedec366b11c6cb8f, 0x2cbfbe86b7ec8aa8), // 5^-283 - (0x94b3a202eb1c3f39, 0x7bf7d71432f3d6a9), // 5^-282 - (0xb9e08a83a5e34f07, 0xdaf5ccd93fb0cc53), // 5^-281 - (0xe858ad248f5c22c9, 0xd1b3400f8f9cff68), // 5^-280 - (0x91376c36d99995be, 0x23100809b9c21fa1), // 5^-279 - (0xb58547448ffffb2d, 0xabd40a0c2832a78a), // 5^-278 - (0xe2e69915b3fff9f9, 0x16c90c8f323f516c), // 5^-277 - (0x8dd01fad907ffc3b, 0xae3da7d97f6792e3), // 5^-276 - (0xb1442798f49ffb4a, 0x99cd11cfdf41779c), // 5^-275 - (0xdd95317f31c7fa1d, 0x40405643d711d583), // 5^-274 - (0x8a7d3eef7f1cfc52, 0x482835ea666b2572), // 5^-273 - (0xad1c8eab5ee43b66, 0xda3243650005eecf), // 5^-272 - (0xd863b256369d4a40, 0x90bed43e40076a82), // 5^-271 - (0x873e4f75e2224e68, 0x5a7744a6e804a291), // 5^-270 - (0xa90de3535aaae202, 0x711515d0a205cb36), // 5^-269 - (0xd3515c2831559a83, 0xd5a5b44ca873e03), // 5^-268 - (0x8412d9991ed58091, 0xe858790afe9486c2), // 5^-267 - (0xa5178fff668ae0b6, 0x626e974dbe39a872), // 5^-266 - (0xce5d73ff402d98e3, 0xfb0a3d212dc8128f), // 5^-265 - (0x80fa687f881c7f8e, 0x7ce66634bc9d0b99), // 5^-264 - (0xa139029f6a239f72, 0x1c1fffc1ebc44e80), // 5^-263 - (0xc987434744ac874e, 0xa327ffb266b56220), // 5^-262 - (0xfbe9141915d7a922, 0x4bf1ff9f0062baa8), // 5^-261 - (0x9d71ac8fada6c9b5, 0x6f773fc3603db4a9), // 5^-260 - (0xc4ce17b399107c22, 0xcb550fb4384d21d3), // 5^-259 - (0xf6019da07f549b2b, 0x7e2a53a146606a48), // 5^-258 - (0x99c102844f94e0fb, 0x2eda7444cbfc426d), // 5^-257 - (0xc0314325637a1939, 0xfa911155fefb5308), // 5^-256 - (0xf03d93eebc589f88, 0x793555ab7eba27ca), // 5^-255 - (0x96267c7535b763b5, 0x4bc1558b2f3458de), // 5^-254 - (0xbbb01b9283253ca2, 0x9eb1aaedfb016f16), // 5^-253 - (0xea9c227723ee8bcb, 0x465e15a979c1cadc), // 5^-252 - (0x92a1958a7675175f, 0xbfacd89ec191ec9), // 5^-251 - (0xb749faed14125d36, 0xcef980ec671f667b), // 5^-250 - (0xe51c79a85916f484, 0x82b7e12780e7401a), // 5^-249 - (0x8f31cc0937ae58d2, 0xd1b2ecb8b0908810), // 5^-248 - (0xb2fe3f0b8599ef07, 0x861fa7e6dcb4aa15), // 5^-247 - (0xdfbdcece67006ac9, 0x67a791e093e1d49a), // 5^-246 - (0x8bd6a141006042bd, 0xe0c8bb2c5c6d24e0), // 5^-245 - (0xaecc49914078536d, 0x58fae9f773886e18), // 5^-244 - (0xda7f5bf590966848, 0xaf39a475506a899e), // 5^-243 - (0x888f99797a5e012d, 0x6d8406c952429603), // 5^-242 - (0xaab37fd7d8f58178, 0xc8e5087ba6d33b83), // 5^-241 - (0xd5605fcdcf32e1d6, 0xfb1e4a9a90880a64), // 5^-240 - (0x855c3be0a17fcd26, 0x5cf2eea09a55067f), // 5^-239 - (0xa6b34ad8c9dfc06f, 0xf42faa48c0ea481e), // 5^-238 - (0xd0601d8efc57b08b, 0xf13b94daf124da26), // 5^-237 - (0x823c12795db6ce57, 0x76c53d08d6b70858), // 5^-236 - (0xa2cb1717b52481ed, 0x54768c4b0c64ca6e), // 5^-235 - (0xcb7ddcdda26da268, 0xa9942f5dcf7dfd09), // 5^-234 - (0xfe5d54150b090b02, 0xd3f93b35435d7c4c), // 5^-233 - (0x9efa548d26e5a6e1, 0xc47bc5014a1a6daf), // 5^-232 - (0xc6b8e9b0709f109a, 0x359ab6419ca1091b), // 5^-231 - (0xf867241c8cc6d4c0, 0xc30163d203c94b62), // 5^-230 - (0x9b407691d7fc44f8, 0x79e0de63425dcf1d), // 5^-229 - (0xc21094364dfb5636, 0x985915fc12f542e4), // 5^-228 - (0xf294b943e17a2bc4, 0x3e6f5b7b17b2939d), // 5^-227 - (0x979cf3ca6cec5b5a, 0xa705992ceecf9c42), // 5^-226 - (0xbd8430bd08277231, 0x50c6ff782a838353), // 5^-225 - (0xece53cec4a314ebd, 0xa4f8bf5635246428), // 5^-224 - (0x940f4613ae5ed136, 0x871b7795e136be99), // 5^-223 - (0xb913179899f68584, 0x28e2557b59846e3f), // 5^-222 - (0xe757dd7ec07426e5, 0x331aeada2fe589cf), // 5^-221 - (0x9096ea6f3848984f, 0x3ff0d2c85def7621), // 5^-220 - (0xb4bca50b065abe63, 0xfed077a756b53a9), // 5^-219 - (0xe1ebce4dc7f16dfb, 0xd3e8495912c62894), // 5^-218 - (0x8d3360f09cf6e4bd, 0x64712dd7abbbd95c), // 5^-217 - (0xb080392cc4349dec, 0xbd8d794d96aacfb3), // 5^-216 - (0xdca04777f541c567, 0xecf0d7a0fc5583a0), // 5^-215 - (0x89e42caaf9491b60, 0xf41686c49db57244), // 5^-214 - (0xac5d37d5b79b6239, 0x311c2875c522ced5), // 5^-213 - (0xd77485cb25823ac7, 0x7d633293366b828b), // 5^-212 - (0x86a8d39ef77164bc, 0xae5dff9c02033197), // 5^-211 - (0xa8530886b54dbdeb, 0xd9f57f830283fdfc), // 5^-210 - (0xd267caa862a12d66, 0xd072df63c324fd7b), // 5^-209 - (0x8380dea93da4bc60, 0x4247cb9e59f71e6d), // 5^-208 - (0xa46116538d0deb78, 0x52d9be85f074e608), // 5^-207 - (0xcd795be870516656, 0x67902e276c921f8b), // 5^-206 - (0x806bd9714632dff6, 0xba1cd8a3db53b6), // 5^-205 - (0xa086cfcd97bf97f3, 0x80e8a40eccd228a4), // 5^-204 - (0xc8a883c0fdaf7df0, 0x6122cd128006b2cd), // 5^-203 - (0xfad2a4b13d1b5d6c, 0x796b805720085f81), // 5^-202 - (0x9cc3a6eec6311a63, 0xcbe3303674053bb0), // 5^-201 - (0xc3f490aa77bd60fc, 0xbedbfc4411068a9c), // 5^-200 - (0xf4f1b4d515acb93b, 0xee92fb5515482d44), // 5^-199 - (0x991711052d8bf3c5, 0x751bdd152d4d1c4a), // 5^-198 - (0xbf5cd54678eef0b6, 0xd262d45a78a0635d), // 5^-197 - (0xef340a98172aace4, 0x86fb897116c87c34), // 5^-196 - (0x9580869f0e7aac0e, 0xd45d35e6ae3d4da0), // 5^-195 - (0xbae0a846d2195712, 0x8974836059cca109), // 5^-194 - (0xe998d258869facd7, 0x2bd1a438703fc94b), // 5^-193 - (0x91ff83775423cc06, 0x7b6306a34627ddcf), // 5^-192 - (0xb67f6455292cbf08, 0x1a3bc84c17b1d542), // 5^-191 - (0xe41f3d6a7377eeca, 0x20caba5f1d9e4a93), // 5^-190 - (0x8e938662882af53e, 0x547eb47b7282ee9c), // 5^-189 - (0xb23867fb2a35b28d, 0xe99e619a4f23aa43), // 5^-188 - (0xdec681f9f4c31f31, 0x6405fa00e2ec94d4), // 5^-187 - (0x8b3c113c38f9f37e, 0xde83bc408dd3dd04), // 5^-186 - (0xae0b158b4738705e, 0x9624ab50b148d445), // 5^-185 - (0xd98ddaee19068c76, 0x3badd624dd9b0957), // 5^-184 - (0x87f8a8d4cfa417c9, 0xe54ca5d70a80e5d6), // 5^-183 - (0xa9f6d30a038d1dbc, 0x5e9fcf4ccd211f4c), // 5^-182 - (0xd47487cc8470652b, 0x7647c3200069671f), // 5^-181 - (0x84c8d4dfd2c63f3b, 0x29ecd9f40041e073), // 5^-180 - (0xa5fb0a17c777cf09, 0xf468107100525890), // 5^-179 - (0xcf79cc9db955c2cc, 0x7182148d4066eeb4), // 5^-178 - (0x81ac1fe293d599bf, 0xc6f14cd848405530), // 5^-177 - (0xa21727db38cb002f, 0xb8ada00e5a506a7c), // 5^-176 - (0xca9cf1d206fdc03b, 0xa6d90811f0e4851c), // 5^-175 - (0xfd442e4688bd304a, 0x908f4a166d1da663), // 5^-174 - (0x9e4a9cec15763e2e, 0x9a598e4e043287fe), // 5^-173 - (0xc5dd44271ad3cdba, 0x40eff1e1853f29fd), // 5^-172 - (0xf7549530e188c128, 0xd12bee59e68ef47c), // 5^-171 - (0x9a94dd3e8cf578b9, 0x82bb74f8301958ce), // 5^-170 - (0xc13a148e3032d6e7, 0xe36a52363c1faf01), // 5^-169 - (0xf18899b1bc3f8ca1, 0xdc44e6c3cb279ac1), // 5^-168 - (0x96f5600f15a7b7e5, 0x29ab103a5ef8c0b9), // 5^-167 - (0xbcb2b812db11a5de, 0x7415d448f6b6f0e7), // 5^-166 - (0xebdf661791d60f56, 0x111b495b3464ad21), // 5^-165 - (0x936b9fcebb25c995, 0xcab10dd900beec34), // 5^-164 - (0xb84687c269ef3bfb, 0x3d5d514f40eea742), // 5^-163 - (0xe65829b3046b0afa, 0xcb4a5a3112a5112), // 5^-162 - (0x8ff71a0fe2c2e6dc, 0x47f0e785eaba72ab), // 5^-161 - (0xb3f4e093db73a093, 0x59ed216765690f56), // 5^-160 - (0xe0f218b8d25088b8, 0x306869c13ec3532c), // 5^-159 - (0x8c974f7383725573, 0x1e414218c73a13fb), // 5^-158 - (0xafbd2350644eeacf, 0xe5d1929ef90898fa), // 5^-157 - (0xdbac6c247d62a583, 0xdf45f746b74abf39), // 5^-156 - (0x894bc396ce5da772, 0x6b8bba8c328eb783), // 5^-155 - (0xab9eb47c81f5114f, 0x66ea92f3f326564), // 5^-154 - (0xd686619ba27255a2, 0xc80a537b0efefebd), // 5^-153 - (0x8613fd0145877585, 0xbd06742ce95f5f36), // 5^-152 - (0xa798fc4196e952e7, 0x2c48113823b73704), // 5^-151 - (0xd17f3b51fca3a7a0, 0xf75a15862ca504c5), // 5^-150 - (0x82ef85133de648c4, 0x9a984d73dbe722fb), // 5^-149 - (0xa3ab66580d5fdaf5, 0xc13e60d0d2e0ebba), // 5^-148 - (0xcc963fee10b7d1b3, 0x318df905079926a8), // 5^-147 - (0xffbbcfe994e5c61f, 0xfdf17746497f7052), // 5^-146 - (0x9fd561f1fd0f9bd3, 0xfeb6ea8bedefa633), // 5^-145 - (0xc7caba6e7c5382c8, 0xfe64a52ee96b8fc0), // 5^-144 - (0xf9bd690a1b68637b, 0x3dfdce7aa3c673b0), // 5^-143 - (0x9c1661a651213e2d, 0x6bea10ca65c084e), // 5^-142 - (0xc31bfa0fe5698db8, 0x486e494fcff30a62), // 5^-141 - (0xf3e2f893dec3f126, 0x5a89dba3c3efccfa), // 5^-140 - (0x986ddb5c6b3a76b7, 0xf89629465a75e01c), // 5^-139 - (0xbe89523386091465, 0xf6bbb397f1135823), // 5^-138 - (0xee2ba6c0678b597f, 0x746aa07ded582e2c), // 5^-137 - (0x94db483840b717ef, 0xa8c2a44eb4571cdc), // 5^-136 - (0xba121a4650e4ddeb, 0x92f34d62616ce413), // 5^-135 - (0xe896a0d7e51e1566, 0x77b020baf9c81d17), // 5^-134 - (0x915e2486ef32cd60, 0xace1474dc1d122e), // 5^-133 - (0xb5b5ada8aaff80b8, 0xd819992132456ba), // 5^-132 - (0xe3231912d5bf60e6, 0x10e1fff697ed6c69), // 5^-131 - (0x8df5efabc5979c8f, 0xca8d3ffa1ef463c1), // 5^-130 - (0xb1736b96b6fd83b3, 0xbd308ff8a6b17cb2), // 5^-129 - (0xddd0467c64bce4a0, 0xac7cb3f6d05ddbde), // 5^-128 - (0x8aa22c0dbef60ee4, 0x6bcdf07a423aa96b), // 5^-127 - (0xad4ab7112eb3929d, 0x86c16c98d2c953c6), // 5^-126 - (0xd89d64d57a607744, 0xe871c7bf077ba8b7), // 5^-125 - (0x87625f056c7c4a8b, 0x11471cd764ad4972), // 5^-124 - (0xa93af6c6c79b5d2d, 0xd598e40d3dd89bcf), // 5^-123 - (0xd389b47879823479, 0x4aff1d108d4ec2c3), // 5^-122 - (0x843610cb4bf160cb, 0xcedf722a585139ba), // 5^-121 - (0xa54394fe1eedb8fe, 0xc2974eb4ee658828), // 5^-120 - (0xce947a3da6a9273e, 0x733d226229feea32), // 5^-119 - (0x811ccc668829b887, 0x806357d5a3f525f), // 5^-118 - (0xa163ff802a3426a8, 0xca07c2dcb0cf26f7), // 5^-117 - (0xc9bcff6034c13052, 0xfc89b393dd02f0b5), // 5^-116 - (0xfc2c3f3841f17c67, 0xbbac2078d443ace2), // 5^-115 - (0x9d9ba7832936edc0, 0xd54b944b84aa4c0d), // 5^-114 - (0xc5029163f384a931, 0xa9e795e65d4df11), // 5^-113 - (0xf64335bcf065d37d, 0x4d4617b5ff4a16d5), // 5^-112 - (0x99ea0196163fa42e, 0x504bced1bf8e4e45), // 5^-111 - (0xc06481fb9bcf8d39, 0xe45ec2862f71e1d6), // 5^-110 - (0xf07da27a82c37088, 0x5d767327bb4e5a4c), // 5^-109 - (0x964e858c91ba2655, 0x3a6a07f8d510f86f), // 5^-108 - (0xbbe226efb628afea, 0x890489f70a55368b), // 5^-107 - (0xeadab0aba3b2dbe5, 0x2b45ac74ccea842e), // 5^-106 - (0x92c8ae6b464fc96f, 0x3b0b8bc90012929d), // 5^-105 - (0xb77ada0617e3bbcb, 0x9ce6ebb40173744), // 5^-104 - (0xe55990879ddcaabd, 0xcc420a6a101d0515), // 5^-103 - (0x8f57fa54c2a9eab6, 0x9fa946824a12232d), // 5^-102 - (0xb32df8e9f3546564, 0x47939822dc96abf9), // 5^-101 - (0xdff9772470297ebd, 0x59787e2b93bc56f7), // 5^-100 - (0x8bfbea76c619ef36, 0x57eb4edb3c55b65a), // 5^-99 - (0xaefae51477a06b03, 0xede622920b6b23f1), // 5^-98 - (0xdab99e59958885c4, 0xe95fab368e45eced), // 5^-97 - (0x88b402f7fd75539b, 0x11dbcb0218ebb414), // 5^-96 - (0xaae103b5fcd2a881, 0xd652bdc29f26a119), // 5^-95 - (0xd59944a37c0752a2, 0x4be76d3346f0495f), // 5^-94 - (0x857fcae62d8493a5, 0x6f70a4400c562ddb), // 5^-93 - (0xa6dfbd9fb8e5b88e, 0xcb4ccd500f6bb952), // 5^-92 - (0xd097ad07a71f26b2, 0x7e2000a41346a7a7), // 5^-91 - (0x825ecc24c873782f, 0x8ed400668c0c28c8), // 5^-90 - (0xa2f67f2dfa90563b, 0x728900802f0f32fa), // 5^-89 - (0xcbb41ef979346bca, 0x4f2b40a03ad2ffb9), // 5^-88 - (0xfea126b7d78186bc, 0xe2f610c84987bfa8), // 5^-87 - (0x9f24b832e6b0f436, 0xdd9ca7d2df4d7c9), // 5^-86 - (0xc6ede63fa05d3143, 0x91503d1c79720dbb), // 5^-85 - (0xf8a95fcf88747d94, 0x75a44c6397ce912a), // 5^-84 - (0x9b69dbe1b548ce7c, 0xc986afbe3ee11aba), // 5^-83 - (0xc24452da229b021b, 0xfbe85badce996168), // 5^-82 - (0xf2d56790ab41c2a2, 0xfae27299423fb9c3), // 5^-81 - (0x97c560ba6b0919a5, 0xdccd879fc967d41a), // 5^-80 - (0xbdb6b8e905cb600f, 0x5400e987bbc1c920), // 5^-79 - (0xed246723473e3813, 0x290123e9aab23b68), // 5^-78 - (0x9436c0760c86e30b, 0xf9a0b6720aaf6521), // 5^-77 - (0xb94470938fa89bce, 0xf808e40e8d5b3e69), // 5^-76 - (0xe7958cb87392c2c2, 0xb60b1d1230b20e04), // 5^-75 - (0x90bd77f3483bb9b9, 0xb1c6f22b5e6f48c2), // 5^-74 - (0xb4ecd5f01a4aa828, 0x1e38aeb6360b1af3), // 5^-73 - (0xe2280b6c20dd5232, 0x25c6da63c38de1b0), // 5^-72 - (0x8d590723948a535f, 0x579c487e5a38ad0e), // 5^-71 - (0xb0af48ec79ace837, 0x2d835a9df0c6d851), // 5^-70 - (0xdcdb1b2798182244, 0xf8e431456cf88e65), // 5^-69 - (0x8a08f0f8bf0f156b, 0x1b8e9ecb641b58ff), // 5^-68 - (0xac8b2d36eed2dac5, 0xe272467e3d222f3f), // 5^-67 - (0xd7adf884aa879177, 0x5b0ed81dcc6abb0f), // 5^-66 - (0x86ccbb52ea94baea, 0x98e947129fc2b4e9), // 5^-65 - (0xa87fea27a539e9a5, 0x3f2398d747b36224), // 5^-64 - (0xd29fe4b18e88640e, 0x8eec7f0d19a03aad), // 5^-63 - (0x83a3eeeef9153e89, 0x1953cf68300424ac), // 5^-62 - (0xa48ceaaab75a8e2b, 0x5fa8c3423c052dd7), // 5^-61 - (0xcdb02555653131b6, 0x3792f412cb06794d), // 5^-60 - (0x808e17555f3ebf11, 0xe2bbd88bbee40bd0), // 5^-59 - (0xa0b19d2ab70e6ed6, 0x5b6aceaeae9d0ec4), // 5^-58 - (0xc8de047564d20a8b, 0xf245825a5a445275), // 5^-57 - (0xfb158592be068d2e, 0xeed6e2f0f0d56712), // 5^-56 - (0x9ced737bb6c4183d, 0x55464dd69685606b), // 5^-55 - (0xc428d05aa4751e4c, 0xaa97e14c3c26b886), // 5^-54 - (0xf53304714d9265df, 0xd53dd99f4b3066a8), // 5^-53 - (0x993fe2c6d07b7fab, 0xe546a8038efe4029), // 5^-52 - (0xbf8fdb78849a5f96, 0xde98520472bdd033), // 5^-51 - (0xef73d256a5c0f77c, 0x963e66858f6d4440), // 5^-50 - (0x95a8637627989aad, 0xdde7001379a44aa8), // 5^-49 - (0xbb127c53b17ec159, 0x5560c018580d5d52), // 5^-48 - (0xe9d71b689dde71af, 0xaab8f01e6e10b4a6), // 5^-47 - (0x9226712162ab070d, 0xcab3961304ca70e8), // 5^-46 - (0xb6b00d69bb55c8d1, 0x3d607b97c5fd0d22), // 5^-45 - (0xe45c10c42a2b3b05, 0x8cb89a7db77c506a), // 5^-44 - (0x8eb98a7a9a5b04e3, 0x77f3608e92adb242), // 5^-43 - (0xb267ed1940f1c61c, 0x55f038b237591ed3), // 5^-42 - (0xdf01e85f912e37a3, 0x6b6c46dec52f6688), // 5^-41 - (0x8b61313bbabce2c6, 0x2323ac4b3b3da015), // 5^-40 - (0xae397d8aa96c1b77, 0xabec975e0a0d081a), // 5^-39 - (0xd9c7dced53c72255, 0x96e7bd358c904a21), // 5^-38 - (0x881cea14545c7575, 0x7e50d64177da2e54), // 5^-37 - (0xaa242499697392d2, 0xdde50bd1d5d0b9e9), // 5^-36 - (0xd4ad2dbfc3d07787, 0x955e4ec64b44e864), // 5^-35 - (0x84ec3c97da624ab4, 0xbd5af13bef0b113e), // 5^-34 - (0xa6274bbdd0fadd61, 0xecb1ad8aeacdd58e), // 5^-33 - (0xcfb11ead453994ba, 0x67de18eda5814af2), // 5^-32 - (0x81ceb32c4b43fcf4, 0x80eacf948770ced7), // 5^-31 - (0xa2425ff75e14fc31, 0xa1258379a94d028d), // 5^-30 - (0xcad2f7f5359a3b3e, 0x96ee45813a04330), // 5^-29 - (0xfd87b5f28300ca0d, 0x8bca9d6e188853fc), // 5^-28 - (0x9e74d1b791e07e48, 0x775ea264cf55347e), // 5^-27 - (0xc612062576589dda, 0x95364afe032a819e), // 5^-26 - (0xf79687aed3eec551, 0x3a83ddbd83f52205), // 5^-25 - (0x9abe14cd44753b52, 0xc4926a9672793543), // 5^-24 - (0xc16d9a0095928a27, 0x75b7053c0f178294), // 5^-23 - (0xf1c90080baf72cb1, 0x5324c68b12dd6339), // 5^-22 - (0x971da05074da7bee, 0xd3f6fc16ebca5e04), // 5^-21 - (0xbce5086492111aea, 0x88f4bb1ca6bcf585), // 5^-20 - (0xec1e4a7db69561a5, 0x2b31e9e3d06c32e6), // 5^-19 - (0x9392ee8e921d5d07, 0x3aff322e62439fd0), // 5^-18 - (0xb877aa3236a4b449, 0x9befeb9fad487c3), // 5^-17 - (0xe69594bec44de15b, 0x4c2ebe687989a9b4), // 5^-16 - (0x901d7cf73ab0acd9, 0xf9d37014bf60a11), // 5^-15 - (0xb424dc35095cd80f, 0x538484c19ef38c95), // 5^-14 - (0xe12e13424bb40e13, 0x2865a5f206b06fba), // 5^-13 - (0x8cbccc096f5088cb, 0xf93f87b7442e45d4), // 5^-12 - (0xafebff0bcb24aafe, 0xf78f69a51539d749), // 5^-11 - (0xdbe6fecebdedd5be, 0xb573440e5a884d1c), // 5^-10 - (0x89705f4136b4a597, 0x31680a88f8953031), // 5^-9 - (0xabcc77118461cefc, 0xfdc20d2b36ba7c3e), // 5^-8 - (0xd6bf94d5e57a42bc, 0x3d32907604691b4d), // 5^-7 - (0x8637bd05af6c69b5, 0xa63f9a49c2c1b110), // 5^-6 - (0xa7c5ac471b478423, 0xfcf80dc33721d54), // 5^-5 - (0xd1b71758e219652b, 0xd3c36113404ea4a9), // 5^-4 - (0x83126e978d4fdf3b, 0x645a1cac083126ea), // 5^-3 - (0xa3d70a3d70a3d70a, 0x3d70a3d70a3d70a4), // 5^-2 - (0xcccccccccccccccc, 0xcccccccccccccccd), // 5^-1 - (0x8000000000000000, 0x0), // 5^0 - (0xa000000000000000, 0x0), // 5^1 - (0xc800000000000000, 0x0), // 5^2 - (0xfa00000000000000, 0x0), // 5^3 - (0x9c40000000000000, 0x0), // 5^4 - (0xc350000000000000, 0x0), // 5^5 - (0xf424000000000000, 0x0), // 5^6 - (0x9896800000000000, 0x0), // 5^7 - (0xbebc200000000000, 0x0), // 5^8 - (0xee6b280000000000, 0x0), // 5^9 - (0x9502f90000000000, 0x0), // 5^10 - (0xba43b74000000000, 0x0), // 5^11 - (0xe8d4a51000000000, 0x0), // 5^12 - (0x9184e72a00000000, 0x0), // 5^13 - (0xb5e620f480000000, 0x0), // 5^14 - (0xe35fa931a0000000, 0x0), // 5^15 - (0x8e1bc9bf04000000, 0x0), // 5^16 - (0xb1a2bc2ec5000000, 0x0), // 5^17 - (0xde0b6b3a76400000, 0x0), // 5^18 - (0x8ac7230489e80000, 0x0), // 5^19 - (0xad78ebc5ac620000, 0x0), // 5^20 - (0xd8d726b7177a8000, 0x0), // 5^21 - (0x878678326eac9000, 0x0), // 5^22 - (0xa968163f0a57b400, 0x0), // 5^23 - (0xd3c21bcecceda100, 0x0), // 5^24 - (0x84595161401484a0, 0x0), // 5^25 - (0xa56fa5b99019a5c8, 0x0), // 5^26 - (0xcecb8f27f4200f3a, 0x0), // 5^27 - (0x813f3978f8940984, 0x4000000000000000), // 5^28 - (0xa18f07d736b90be5, 0x5000000000000000), // 5^29 - (0xc9f2c9cd04674ede, 0xa400000000000000), // 5^30 - (0xfc6f7c4045812296, 0x4d00000000000000), // 5^31 - (0x9dc5ada82b70b59d, 0xf020000000000000), // 5^32 - (0xc5371912364ce305, 0x6c28000000000000), // 5^33 - (0xf684df56c3e01bc6, 0xc732000000000000), // 5^34 - (0x9a130b963a6c115c, 0x3c7f400000000000), // 5^35 - (0xc097ce7bc90715b3, 0x4b9f100000000000), // 5^36 - (0xf0bdc21abb48db20, 0x1e86d40000000000), // 5^37 - (0x96769950b50d88f4, 0x1314448000000000), // 5^38 - (0xbc143fa4e250eb31, 0x17d955a000000000), // 5^39 - (0xeb194f8e1ae525fd, 0x5dcfab0800000000), // 5^40 - (0x92efd1b8d0cf37be, 0x5aa1cae500000000), // 5^41 - (0xb7abc627050305ad, 0xf14a3d9e40000000), // 5^42 - (0xe596b7b0c643c719, 0x6d9ccd05d0000000), // 5^43 - (0x8f7e32ce7bea5c6f, 0xe4820023a2000000), // 5^44 - (0xb35dbf821ae4f38b, 0xdda2802c8a800000), // 5^45 - (0xe0352f62a19e306e, 0xd50b2037ad200000), // 5^46 - (0x8c213d9da502de45, 0x4526f422cc340000), // 5^47 - (0xaf298d050e4395d6, 0x9670b12b7f410000), // 5^48 - (0xdaf3f04651d47b4c, 0x3c0cdd765f114000), // 5^49 - (0x88d8762bf324cd0f, 0xa5880a69fb6ac800), // 5^50 - (0xab0e93b6efee0053, 0x8eea0d047a457a00), // 5^51 - (0xd5d238a4abe98068, 0x72a4904598d6d880), // 5^52 - (0x85a36366eb71f041, 0x47a6da2b7f864750), // 5^53 - (0xa70c3c40a64e6c51, 0x999090b65f67d924), // 5^54 - (0xd0cf4b50cfe20765, 0xfff4b4e3f741cf6d), // 5^55 - (0x82818f1281ed449f, 0xbff8f10e7a8921a4), // 5^56 - (0xa321f2d7226895c7, 0xaff72d52192b6a0d), // 5^57 - (0xcbea6f8ceb02bb39, 0x9bf4f8a69f764490), // 5^58 - (0xfee50b7025c36a08, 0x2f236d04753d5b4), // 5^59 - (0x9f4f2726179a2245, 0x1d762422c946590), // 5^60 - (0xc722f0ef9d80aad6, 0x424d3ad2b7b97ef5), // 5^61 - (0xf8ebad2b84e0d58b, 0xd2e0898765a7deb2), // 5^62 - (0x9b934c3b330c8577, 0x63cc55f49f88eb2f), // 5^63 - (0xc2781f49ffcfa6d5, 0x3cbf6b71c76b25fb), // 5^64 - (0xf316271c7fc3908a, 0x8bef464e3945ef7a), // 5^65 - (0x97edd871cfda3a56, 0x97758bf0e3cbb5ac), // 5^66 - (0xbde94e8e43d0c8ec, 0x3d52eeed1cbea317), // 5^67 - (0xed63a231d4c4fb27, 0x4ca7aaa863ee4bdd), // 5^68 - (0x945e455f24fb1cf8, 0x8fe8caa93e74ef6a), // 5^69 - (0xb975d6b6ee39e436, 0xb3e2fd538e122b44), // 5^70 - (0xe7d34c64a9c85d44, 0x60dbbca87196b616), // 5^71 - (0x90e40fbeea1d3a4a, 0xbc8955e946fe31cd), // 5^72 - (0xb51d13aea4a488dd, 0x6babab6398bdbe41), // 5^73 - (0xe264589a4dcdab14, 0xc696963c7eed2dd1), // 5^74 - (0x8d7eb76070a08aec, 0xfc1e1de5cf543ca2), // 5^75 - (0xb0de65388cc8ada8, 0x3b25a55f43294bcb), // 5^76 - (0xdd15fe86affad912, 0x49ef0eb713f39ebe), // 5^77 - (0x8a2dbf142dfcc7ab, 0x6e3569326c784337), // 5^78 - (0xacb92ed9397bf996, 0x49c2c37f07965404), // 5^79 - (0xd7e77a8f87daf7fb, 0xdc33745ec97be906), // 5^80 - (0x86f0ac99b4e8dafd, 0x69a028bb3ded71a3), // 5^81 - (0xa8acd7c0222311bc, 0xc40832ea0d68ce0c), // 5^82 - (0xd2d80db02aabd62b, 0xf50a3fa490c30190), // 5^83 - (0x83c7088e1aab65db, 0x792667c6da79e0fa), // 5^84 - (0xa4b8cab1a1563f52, 0x577001b891185938), // 5^85 - (0xcde6fd5e09abcf26, 0xed4c0226b55e6f86), // 5^86 - (0x80b05e5ac60b6178, 0x544f8158315b05b4), // 5^87 - (0xa0dc75f1778e39d6, 0x696361ae3db1c721), // 5^88 - (0xc913936dd571c84c, 0x3bc3a19cd1e38e9), // 5^89 - (0xfb5878494ace3a5f, 0x4ab48a04065c723), // 5^90 - (0x9d174b2dcec0e47b, 0x62eb0d64283f9c76), // 5^91 - (0xc45d1df942711d9a, 0x3ba5d0bd324f8394), // 5^92 - (0xf5746577930d6500, 0xca8f44ec7ee36479), // 5^93 - (0x9968bf6abbe85f20, 0x7e998b13cf4e1ecb), // 5^94 - (0xbfc2ef456ae276e8, 0x9e3fedd8c321a67e), // 5^95 - (0xefb3ab16c59b14a2, 0xc5cfe94ef3ea101e), // 5^96 - (0x95d04aee3b80ece5, 0xbba1f1d158724a12), // 5^97 - (0xbb445da9ca61281f, 0x2a8a6e45ae8edc97), // 5^98 - (0xea1575143cf97226, 0xf52d09d71a3293bd), // 5^99 - (0x924d692ca61be758, 0x593c2626705f9c56), // 5^100 - (0xb6e0c377cfa2e12e, 0x6f8b2fb00c77836c), // 5^101 - (0xe498f455c38b997a, 0xb6dfb9c0f956447), // 5^102 - (0x8edf98b59a373fec, 0x4724bd4189bd5eac), // 5^103 - (0xb2977ee300c50fe7, 0x58edec91ec2cb657), // 5^104 - (0xdf3d5e9bc0f653e1, 0x2f2967b66737e3ed), // 5^105 - (0x8b865b215899f46c, 0xbd79e0d20082ee74), // 5^106 - (0xae67f1e9aec07187, 0xecd8590680a3aa11), // 5^107 - (0xda01ee641a708de9, 0xe80e6f4820cc9495), // 5^108 - (0x884134fe908658b2, 0x3109058d147fdcdd), // 5^109 - (0xaa51823e34a7eede, 0xbd4b46f0599fd415), // 5^110 - (0xd4e5e2cdc1d1ea96, 0x6c9e18ac7007c91a), // 5^111 - (0x850fadc09923329e, 0x3e2cf6bc604ddb0), // 5^112 - (0xa6539930bf6bff45, 0x84db8346b786151c), // 5^113 - (0xcfe87f7cef46ff16, 0xe612641865679a63), // 5^114 - (0x81f14fae158c5f6e, 0x4fcb7e8f3f60c07e), // 5^115 - (0xa26da3999aef7749, 0xe3be5e330f38f09d), // 5^116 - (0xcb090c8001ab551c, 0x5cadf5bfd3072cc5), // 5^117 - (0xfdcb4fa002162a63, 0x73d9732fc7c8f7f6), // 5^118 - (0x9e9f11c4014dda7e, 0x2867e7fddcdd9afa), // 5^119 - (0xc646d63501a1511d, 0xb281e1fd541501b8), // 5^120 - (0xf7d88bc24209a565, 0x1f225a7ca91a4226), // 5^121 - (0x9ae757596946075f, 0x3375788de9b06958), // 5^122 - (0xc1a12d2fc3978937, 0x52d6b1641c83ae), // 5^123 - (0xf209787bb47d6b84, 0xc0678c5dbd23a49a), // 5^124 - (0x9745eb4d50ce6332, 0xf840b7ba963646e0), // 5^125 - (0xbd176620a501fbff, 0xb650e5a93bc3d898), // 5^126 - (0xec5d3fa8ce427aff, 0xa3e51f138ab4cebe), // 5^127 - (0x93ba47c980e98cdf, 0xc66f336c36b10137), // 5^128 - (0xb8a8d9bbe123f017, 0xb80b0047445d4184), // 5^129 - (0xe6d3102ad96cec1d, 0xa60dc059157491e5), // 5^130 - (0x9043ea1ac7e41392, 0x87c89837ad68db2f), // 5^131 - (0xb454e4a179dd1877, 0x29babe4598c311fb), // 5^132 - (0xe16a1dc9d8545e94, 0xf4296dd6fef3d67a), // 5^133 - (0x8ce2529e2734bb1d, 0x1899e4a65f58660c), // 5^134 - (0xb01ae745b101e9e4, 0x5ec05dcff72e7f8f), // 5^135 - (0xdc21a1171d42645d, 0x76707543f4fa1f73), // 5^136 - (0x899504ae72497eba, 0x6a06494a791c53a8), // 5^137 - (0xabfa45da0edbde69, 0x487db9d17636892), // 5^138 - (0xd6f8d7509292d603, 0x45a9d2845d3c42b6), // 5^139 - (0x865b86925b9bc5c2, 0xb8a2392ba45a9b2), // 5^140 - (0xa7f26836f282b732, 0x8e6cac7768d7141e), // 5^141 - (0xd1ef0244af2364ff, 0x3207d795430cd926), // 5^142 - (0x8335616aed761f1f, 0x7f44e6bd49e807b8), // 5^143 - (0xa402b9c5a8d3a6e7, 0x5f16206c9c6209a6), // 5^144 - (0xcd036837130890a1, 0x36dba887c37a8c0f), // 5^145 - (0x802221226be55a64, 0xc2494954da2c9789), // 5^146 - (0xa02aa96b06deb0fd, 0xf2db9baa10b7bd6c), // 5^147 - (0xc83553c5c8965d3d, 0x6f92829494e5acc7), // 5^148 - (0xfa42a8b73abbf48c, 0xcb772339ba1f17f9), // 5^149 - (0x9c69a97284b578d7, 0xff2a760414536efb), // 5^150 - (0xc38413cf25e2d70d, 0xfef5138519684aba), // 5^151 - (0xf46518c2ef5b8cd1, 0x7eb258665fc25d69), // 5^152 - (0x98bf2f79d5993802, 0xef2f773ffbd97a61), // 5^153 - (0xbeeefb584aff8603, 0xaafb550ffacfd8fa), // 5^154 - (0xeeaaba2e5dbf6784, 0x95ba2a53f983cf38), // 5^155 - (0x952ab45cfa97a0b2, 0xdd945a747bf26183), // 5^156 - (0xba756174393d88df, 0x94f971119aeef9e4), // 5^157 - (0xe912b9d1478ceb17, 0x7a37cd5601aab85d), // 5^158 - (0x91abb422ccb812ee, 0xac62e055c10ab33a), // 5^159 - (0xb616a12b7fe617aa, 0x577b986b314d6009), // 5^160 - (0xe39c49765fdf9d94, 0xed5a7e85fda0b80b), // 5^161 - (0x8e41ade9fbebc27d, 0x14588f13be847307), // 5^162 - (0xb1d219647ae6b31c, 0x596eb2d8ae258fc8), // 5^163 - (0xde469fbd99a05fe3, 0x6fca5f8ed9aef3bb), // 5^164 - (0x8aec23d680043bee, 0x25de7bb9480d5854), // 5^165 - (0xada72ccc20054ae9, 0xaf561aa79a10ae6a), // 5^166 - (0xd910f7ff28069da4, 0x1b2ba1518094da04), // 5^167 - (0x87aa9aff79042286, 0x90fb44d2f05d0842), // 5^168 - (0xa99541bf57452b28, 0x353a1607ac744a53), // 5^169 - (0xd3fa922f2d1675f2, 0x42889b8997915ce8), // 5^170 - (0x847c9b5d7c2e09b7, 0x69956135febada11), // 5^171 - (0xa59bc234db398c25, 0x43fab9837e699095), // 5^172 - (0xcf02b2c21207ef2e, 0x94f967e45e03f4bb), // 5^173 - (0x8161afb94b44f57d, 0x1d1be0eebac278f5), // 5^174 - (0xa1ba1ba79e1632dc, 0x6462d92a69731732), // 5^175 - (0xca28a291859bbf93, 0x7d7b8f7503cfdcfe), // 5^176 - (0xfcb2cb35e702af78, 0x5cda735244c3d43e), // 5^177 - (0x9defbf01b061adab, 0x3a0888136afa64a7), // 5^178 - (0xc56baec21c7a1916, 0x88aaa1845b8fdd0), // 5^179 - (0xf6c69a72a3989f5b, 0x8aad549e57273d45), // 5^180 - (0x9a3c2087a63f6399, 0x36ac54e2f678864b), // 5^181 - (0xc0cb28a98fcf3c7f, 0x84576a1bb416a7dd), // 5^182 - (0xf0fdf2d3f3c30b9f, 0x656d44a2a11c51d5), // 5^183 - (0x969eb7c47859e743, 0x9f644ae5a4b1b325), // 5^184 - (0xbc4665b596706114, 0x873d5d9f0dde1fee), // 5^185 - (0xeb57ff22fc0c7959, 0xa90cb506d155a7ea), // 5^186 - (0x9316ff75dd87cbd8, 0x9a7f12442d588f2), // 5^187 - (0xb7dcbf5354e9bece, 0xc11ed6d538aeb2f), // 5^188 - (0xe5d3ef282a242e81, 0x8f1668c8a86da5fa), // 5^189 - (0x8fa475791a569d10, 0xf96e017d694487bc), // 5^190 - (0xb38d92d760ec4455, 0x37c981dcc395a9ac), // 5^191 - (0xe070f78d3927556a, 0x85bbe253f47b1417), // 5^192 - (0x8c469ab843b89562, 0x93956d7478ccec8e), // 5^193 - (0xaf58416654a6babb, 0x387ac8d1970027b2), // 5^194 - (0xdb2e51bfe9d0696a, 0x6997b05fcc0319e), // 5^195 - (0x88fcf317f22241e2, 0x441fece3bdf81f03), // 5^196 - (0xab3c2fddeeaad25a, 0xd527e81cad7626c3), // 5^197 - (0xd60b3bd56a5586f1, 0x8a71e223d8d3b074), // 5^198 - (0x85c7056562757456, 0xf6872d5667844e49), // 5^199 - (0xa738c6bebb12d16c, 0xb428f8ac016561db), // 5^200 - (0xd106f86e69d785c7, 0xe13336d701beba52), // 5^201 - (0x82a45b450226b39c, 0xecc0024661173473), // 5^202 - (0xa34d721642b06084, 0x27f002d7f95d0190), // 5^203 - (0xcc20ce9bd35c78a5, 0x31ec038df7b441f4), // 5^204 - (0xff290242c83396ce, 0x7e67047175a15271), // 5^205 - (0x9f79a169bd203e41, 0xf0062c6e984d386), // 5^206 - (0xc75809c42c684dd1, 0x52c07b78a3e60868), // 5^207 - (0xf92e0c3537826145, 0xa7709a56ccdf8a82), // 5^208 - (0x9bbcc7a142b17ccb, 0x88a66076400bb691), // 5^209 - (0xc2abf989935ddbfe, 0x6acff893d00ea435), // 5^210 - (0xf356f7ebf83552fe, 0x583f6b8c4124d43), // 5^211 - (0x98165af37b2153de, 0xc3727a337a8b704a), // 5^212 - (0xbe1bf1b059e9a8d6, 0x744f18c0592e4c5c), // 5^213 - (0xeda2ee1c7064130c, 0x1162def06f79df73), // 5^214 - (0x9485d4d1c63e8be7, 0x8addcb5645ac2ba8), // 5^215 - (0xb9a74a0637ce2ee1, 0x6d953e2bd7173692), // 5^216 - (0xe8111c87c5c1ba99, 0xc8fa8db6ccdd0437), // 5^217 - (0x910ab1d4db9914a0, 0x1d9c9892400a22a2), // 5^218 - (0xb54d5e4a127f59c8, 0x2503beb6d00cab4b), // 5^219 - (0xe2a0b5dc971f303a, 0x2e44ae64840fd61d), // 5^220 - (0x8da471a9de737e24, 0x5ceaecfed289e5d2), // 5^221 - (0xb10d8e1456105dad, 0x7425a83e872c5f47), // 5^222 - (0xdd50f1996b947518, 0xd12f124e28f77719), // 5^223 - (0x8a5296ffe33cc92f, 0x82bd6b70d99aaa6f), // 5^224 - (0xace73cbfdc0bfb7b, 0x636cc64d1001550b), // 5^225 - (0xd8210befd30efa5a, 0x3c47f7e05401aa4e), // 5^226 - (0x8714a775e3e95c78, 0x65acfaec34810a71), // 5^227 - (0xa8d9d1535ce3b396, 0x7f1839a741a14d0d), // 5^228 - (0xd31045a8341ca07c, 0x1ede48111209a050), // 5^229 - (0x83ea2b892091e44d, 0x934aed0aab460432), // 5^230 - (0xa4e4b66b68b65d60, 0xf81da84d5617853f), // 5^231 - (0xce1de40642e3f4b9, 0x36251260ab9d668e), // 5^232 - (0x80d2ae83e9ce78f3, 0xc1d72b7c6b426019), // 5^233 - (0xa1075a24e4421730, 0xb24cf65b8612f81f), // 5^234 - (0xc94930ae1d529cfc, 0xdee033f26797b627), // 5^235 - (0xfb9b7cd9a4a7443c, 0x169840ef017da3b1), // 5^236 - (0x9d412e0806e88aa5, 0x8e1f289560ee864e), // 5^237 - (0xc491798a08a2ad4e, 0xf1a6f2bab92a27e2), // 5^238 - (0xf5b5d7ec8acb58a2, 0xae10af696774b1db), // 5^239 - (0x9991a6f3d6bf1765, 0xacca6da1e0a8ef29), // 5^240 - (0xbff610b0cc6edd3f, 0x17fd090a58d32af3), // 5^241 - (0xeff394dcff8a948e, 0xddfc4b4cef07f5b0), // 5^242 - (0x95f83d0a1fb69cd9, 0x4abdaf101564f98e), // 5^243 - (0xbb764c4ca7a4440f, 0x9d6d1ad41abe37f1), // 5^244 - (0xea53df5fd18d5513, 0x84c86189216dc5ed), // 5^245 - (0x92746b9be2f8552c, 0x32fd3cf5b4e49bb4), // 5^246 - (0xb7118682dbb66a77, 0x3fbc8c33221dc2a1), // 5^247 - (0xe4d5e82392a40515, 0xfabaf3feaa5334a), // 5^248 - (0x8f05b1163ba6832d, 0x29cb4d87f2a7400e), // 5^249 - (0xb2c71d5bca9023f8, 0x743e20e9ef511012), // 5^250 - (0xdf78e4b2bd342cf6, 0x914da9246b255416), // 5^251 - (0x8bab8eefb6409c1a, 0x1ad089b6c2f7548e), // 5^252 - (0xae9672aba3d0c320, 0xa184ac2473b529b1), // 5^253 - (0xda3c0f568cc4f3e8, 0xc9e5d72d90a2741e), // 5^254 - (0x8865899617fb1871, 0x7e2fa67c7a658892), // 5^255 - (0xaa7eebfb9df9de8d, 0xddbb901b98feeab7), // 5^256 - (0xd51ea6fa85785631, 0x552a74227f3ea565), // 5^257 - (0x8533285c936b35de, 0xd53a88958f87275f), // 5^258 - (0xa67ff273b8460356, 0x8a892abaf368f137), // 5^259 - (0xd01fef10a657842c, 0x2d2b7569b0432d85), // 5^260 - (0x8213f56a67f6b29b, 0x9c3b29620e29fc73), // 5^261 - (0xa298f2c501f45f42, 0x8349f3ba91b47b8f), // 5^262 - (0xcb3f2f7642717713, 0x241c70a936219a73), // 5^263 - (0xfe0efb53d30dd4d7, 0xed238cd383aa0110), // 5^264 - (0x9ec95d1463e8a506, 0xf4363804324a40aa), // 5^265 - (0xc67bb4597ce2ce48, 0xb143c6053edcd0d5), // 5^266 - (0xf81aa16fdc1b81da, 0xdd94b7868e94050a), // 5^267 - (0x9b10a4e5e9913128, 0xca7cf2b4191c8326), // 5^268 - (0xc1d4ce1f63f57d72, 0xfd1c2f611f63a3f0), // 5^269 - (0xf24a01a73cf2dccf, 0xbc633b39673c8cec), // 5^270 - (0x976e41088617ca01, 0xd5be0503e085d813), // 5^271 - (0xbd49d14aa79dbc82, 0x4b2d8644d8a74e18), // 5^272 - (0xec9c459d51852ba2, 0xddf8e7d60ed1219e), // 5^273 - (0x93e1ab8252f33b45, 0xcabb90e5c942b503), // 5^274 - (0xb8da1662e7b00a17, 0x3d6a751f3b936243), // 5^275 - (0xe7109bfba19c0c9d, 0xcc512670a783ad4), // 5^276 - (0x906a617d450187e2, 0x27fb2b80668b24c5), // 5^277 - (0xb484f9dc9641e9da, 0xb1f9f660802dedf6), // 5^278 - (0xe1a63853bbd26451, 0x5e7873f8a0396973), // 5^279 - (0x8d07e33455637eb2, 0xdb0b487b6423e1e8), // 5^280 - (0xb049dc016abc5e5f, 0x91ce1a9a3d2cda62), // 5^281 - (0xdc5c5301c56b75f7, 0x7641a140cc7810fb), // 5^282 - (0x89b9b3e11b6329ba, 0xa9e904c87fcb0a9d), // 5^283 - (0xac2820d9623bf429, 0x546345fa9fbdcd44), // 5^284 - (0xd732290fbacaf133, 0xa97c177947ad4095), // 5^285 - (0x867f59a9d4bed6c0, 0x49ed8eabcccc485d), // 5^286 - (0xa81f301449ee8c70, 0x5c68f256bfff5a74), // 5^287 - (0xd226fc195c6a2f8c, 0x73832eec6fff3111), // 5^288 - (0x83585d8fd9c25db7, 0xc831fd53c5ff7eab), // 5^289 - (0xa42e74f3d032f525, 0xba3e7ca8b77f5e55), // 5^290 - (0xcd3a1230c43fb26f, 0x28ce1bd2e55f35eb), // 5^291 - (0x80444b5e7aa7cf85, 0x7980d163cf5b81b3), // 5^292 - (0xa0555e361951c366, 0xd7e105bcc332621f), // 5^293 - (0xc86ab5c39fa63440, 0x8dd9472bf3fefaa7), // 5^294 - (0xfa856334878fc150, 0xb14f98f6f0feb951), // 5^295 - (0x9c935e00d4b9d8d2, 0x6ed1bf9a569f33d3), // 5^296 - (0xc3b8358109e84f07, 0xa862f80ec4700c8), // 5^297 - (0xf4a642e14c6262c8, 0xcd27bb612758c0fa), // 5^298 - (0x98e7e9cccfbd7dbd, 0x8038d51cb897789c), // 5^299 - (0xbf21e44003acdd2c, 0xe0470a63e6bd56c3), // 5^300 - (0xeeea5d5004981478, 0x1858ccfce06cac74), // 5^301 - (0x95527a5202df0ccb, 0xf37801e0c43ebc8), // 5^302 - (0xbaa718e68396cffd, 0xd30560258f54e6ba), // 5^303 - (0xe950df20247c83fd, 0x47c6b82ef32a2069), // 5^304 - (0x91d28b7416cdd27e, 0x4cdc331d57fa5441), // 5^305 - (0xb6472e511c81471d, 0xe0133fe4adf8e952), // 5^306 - (0xe3d8f9e563a198e5, 0x58180fddd97723a6), // 5^307 - (0x8e679c2f5e44ff8f, 0x570f09eaa7ea7648), // 5^308 -]; diff --git a/library/core/src/num/diy_float.rs b/library/core/src/num/diy_float.rs deleted file mode 100644 index ce7f6475d0599..0000000000000 --- a/library/core/src/num/diy_float.rs +++ /dev/null @@ -1,81 +0,0 @@ -//! Extended precision "soft float", for internal use only. - -// This module is only for dec2flt and flt2dec, and only public because of coretests. -// It is not intended to ever be stabilized. -#![doc(hidden)] -#![unstable( - feature = "core_private_diy_float", - reason = "internal routines only exposed for testing", - issue = "none" -)] - -/// A custom 64-bit floating point type, representing `f * 2^e`. -#[derive(Copy, Clone, Debug)] -#[doc(hidden)] -pub struct Fp { - /// The integer mantissa. - pub f: u64, - /// The exponent in base 2. - pub e: i16, -} - -impl Fp { - /// Returns a correctly rounded product of itself and `other`. - pub fn mul(&self, other: &Fp) -> Fp { - const MASK: u64 = 0xffffffff; - let a = self.f >> 32; - let b = self.f & MASK; - let c = other.f >> 32; - let d = other.f & MASK; - let ac = a * c; - let bc = b * c; - let ad = a * d; - let bd = b * d; - let tmp = (bd >> 32) + (ad & MASK) + (bc & MASK) + (1 << 31) /* round */; - let f = ac + (ad >> 32) + (bc >> 32) + (tmp >> 32); - let e = self.e + other.e + 64; - Fp { f, e } - } - - /// Normalizes itself so that the resulting mantissa is at least `2^63`. - pub fn normalize(&self) -> Fp { - let mut f = self.f; - let mut e = self.e; - if f >> (64 - 32) == 0 { - f <<= 32; - e -= 32; - } - if f >> (64 - 16) == 0 { - f <<= 16; - e -= 16; - } - if f >> (64 - 8) == 0 { - f <<= 8; - e -= 8; - } - if f >> (64 - 4) == 0 { - f <<= 4; - e -= 4; - } - if f >> (64 - 2) == 0 { - f <<= 2; - e -= 2; - } - if f >> (64 - 1) == 0 { - f <<= 1; - e -= 1; - } - debug_assert!(f >= (1 << 63)); - Fp { f, e } - } - - /// Normalizes itself to have the shared exponent. - /// It can only decrease the exponent (and thus increase the mantissa). - pub fn normalize_to(&self, e: i16) -> Fp { - let edelta = self.e - e; - assert!(edelta >= 0); - let edelta = edelta as usize; - assert_eq!(self.f << edelta >> edelta, self.f); - Fp { f: self.f << edelta, e } - } -} diff --git a/library/core/src/num/error.rs b/library/core/src/num/error.rs deleted file mode 100644 index a2d7e6f7b0754..0000000000000 --- a/library/core/src/num/error.rs +++ /dev/null @@ -1,143 +0,0 @@ -//! Error types for conversion to integral types. - -use crate::convert::Infallible; -use crate::error::Error; -use crate::fmt; - -/// The error type returned when a checked integral type conversion fails. -#[stable(feature = "try_from", since = "1.34.0")] -#[derive(Debug, Copy, Clone, PartialEq, Eq)] -pub struct TryFromIntError(pub(crate) ()); - -#[stable(feature = "try_from", since = "1.34.0")] -impl fmt::Display for TryFromIntError { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - #[allow(deprecated)] - self.description().fmt(fmt) - } -} - -#[stable(feature = "try_from", since = "1.34.0")] -impl Error for TryFromIntError { - #[allow(deprecated)] - fn description(&self) -> &str { - "out of range integral type conversion attempted" - } -} - -#[stable(feature = "try_from", since = "1.34.0")] -impl From for TryFromIntError { - fn from(x: Infallible) -> TryFromIntError { - match x {} - } -} - -#[unstable(feature = "never_type", issue = "35121")] -impl From for TryFromIntError { - #[inline] - fn from(never: !) -> TryFromIntError { - // Match rather than coerce to make sure that code like - // `From for TryFromIntError` above will keep working - // when `Infallible` becomes an alias to `!`. - match never {} - } -} - -/// An error which can be returned when parsing an integer. -/// -/// This error is used as the error type for the `from_str_radix()` functions -/// on the primitive integer types, such as [`i8::from_str_radix`]. -/// -/// # Potential causes -/// -/// Among other causes, `ParseIntError` can be thrown because of leading or trailing whitespace -/// in the string e.g., when it is obtained from the standard input. -/// Using the [`str::trim()`] method ensures that no whitespace remains before parsing. -/// -/// # Example -/// -/// ``` -/// if let Err(e) = i32::from_str_radix("a12", 10) { -/// println!("Failed conversion to i32: {e}"); -/// } -/// ``` -#[derive(Debug, Clone, PartialEq, Eq)] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct ParseIntError { - pub(super) kind: IntErrorKind, -} - -/// Enum to store the various types of errors that can cause parsing an integer to fail. -/// -/// # Example -/// -/// ``` -/// # fn main() { -/// if let Err(e) = i32::from_str_radix("a12", 10) { -/// println!("Failed conversion to i32: {:?}", e.kind()); -/// } -/// # } -/// ``` -#[stable(feature = "int_error_matching", since = "1.55.0")] -#[derive(Debug, Clone, PartialEq, Eq)] -#[non_exhaustive] -pub enum IntErrorKind { - /// Value being parsed is empty. - /// - /// This variant will be constructed when parsing an empty string. - #[stable(feature = "int_error_matching", since = "1.55.0")] - Empty, - /// Contains an invalid digit in its context. - /// - /// Among other causes, this variant will be constructed when parsing a string that - /// contains a non-ASCII char. - /// - /// This variant is also constructed when a `+` or `-` is misplaced within a string - /// either on its own or in the middle of a number. - #[stable(feature = "int_error_matching", since = "1.55.0")] - InvalidDigit, - /// Integer is too large to store in target integer type. - #[stable(feature = "int_error_matching", since = "1.55.0")] - PosOverflow, - /// Integer is too small to store in target integer type. - #[stable(feature = "int_error_matching", since = "1.55.0")] - NegOverflow, - /// Value was Zero - /// - /// This variant will be emitted when the parsing string has a value of zero, which - /// would be illegal for non-zero types. - #[stable(feature = "int_error_matching", since = "1.55.0")] - Zero, -} - -impl ParseIntError { - /// Outputs the detailed cause of parsing an integer failing. - #[must_use] - #[rustc_const_unstable(feature = "const_int_from_str", issue = "59133")] - #[stable(feature = "int_error_matching", since = "1.55.0")] - pub const fn kind(&self) -> &IntErrorKind { - &self.kind - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for ParseIntError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - #[allow(deprecated)] - self.description().fmt(f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Error for ParseIntError { - #[allow(deprecated)] - fn description(&self) -> &str { - match self.kind { - IntErrorKind::Empty => "cannot parse integer from empty string", - IntErrorKind::InvalidDigit => "invalid digit found in string", - IntErrorKind::PosOverflow => "number too large to fit in target type", - IntErrorKind::NegOverflow => "number too small to fit in target type", - IntErrorKind::Zero => "number would be zero for non-zero type", - } - } -} diff --git a/library/core/src/num/f128.rs b/library/core/src/num/f128.rs deleted file mode 100644 index 9362dc8765492..0000000000000 --- a/library/core/src/num/f128.rs +++ /dev/null @@ -1,331 +0,0 @@ -//! Constants for the `f128` quadruple-precision floating point type. -//! -//! *[See also the `f128` primitive type][f128].* -//! -//! Mathematically significant numbers are provided in the `consts` sub-module. -//! -//! For the constants defined directly in this module -//! (as distinct from those defined in the `consts` sub-module), -//! new code should instead use the associated constants -//! defined directly on the `f128` type. - -#![unstable(feature = "f128", issue = "116909")] - -use crate::mem; - -/// Basic mathematical constants. -#[unstable(feature = "f128", issue = "116909")] -pub mod consts { - // FIXME: replace with mathematical constants from cmath. - - /// Archimedes' constant (π) - #[unstable(feature = "f128", issue = "116909")] - pub const PI: f128 = 3.14159265358979323846264338327950288419716939937510582097494_f128; - - /// The full circle constant (τ) - /// - /// Equal to 2π. - #[unstable(feature = "f128", issue = "116909")] - pub const TAU: f128 = 6.28318530717958647692528676655900576839433879875021164194989_f128; - - /// The golden ratio (φ) - #[unstable(feature = "f128", issue = "116909")] - // Also, #[unstable(feature = "more_float_constants", issue = "103883")] - pub const PHI: f128 = 1.61803398874989484820458683436563811772030917980576286213545_f128; - - /// The Euler-Mascheroni constant (γ) - #[unstable(feature = "f128", issue = "116909")] - // Also, #[unstable(feature = "more_float_constants", issue = "103883")] - pub const EGAMMA: f128 = 0.577215664901532860606512090082402431042159335939923598805767_f128; - - /// π/2 - #[unstable(feature = "f128", issue = "116909")] - pub const FRAC_PI_2: f128 = 1.57079632679489661923132169163975144209858469968755291048747_f128; - - /// π/3 - #[unstable(feature = "f128", issue = "116909")] - pub const FRAC_PI_3: f128 = 1.04719755119659774615421446109316762806572313312503527365831_f128; - - /// π/4 - #[unstable(feature = "f128", issue = "116909")] - pub const FRAC_PI_4: f128 = 0.785398163397448309615660845819875721049292349843776455243736_f128; - - /// π/6 - #[unstable(feature = "f128", issue = "116909")] - pub const FRAC_PI_6: f128 = 0.523598775598298873077107230546583814032861566562517636829157_f128; - - /// π/8 - #[unstable(feature = "f128", issue = "116909")] - pub const FRAC_PI_8: f128 = 0.392699081698724154807830422909937860524646174921888227621868_f128; - - /// 1/π - #[unstable(feature = "f128", issue = "116909")] - pub const FRAC_1_PI: f128 = 0.318309886183790671537767526745028724068919291480912897495335_f128; - - /// 1/sqrt(π) - #[unstable(feature = "f128", issue = "116909")] - // Also, #[unstable(feature = "more_float_constants", issue = "103883")] - pub const FRAC_1_SQRT_PI: f128 = - 0.564189583547756286948079451560772585844050629328998856844086_f128; - - /// 2/π - #[unstable(feature = "f128", issue = "116909")] - pub const FRAC_2_PI: f128 = 0.636619772367581343075535053490057448137838582961825794990669_f128; - - /// 2/sqrt(π) - #[unstable(feature = "f128", issue = "116909")] - pub const FRAC_2_SQRT_PI: f128 = - 1.12837916709551257389615890312154517168810125865799771368817_f128; - - /// sqrt(2) - #[unstable(feature = "f128", issue = "116909")] - pub const SQRT_2: f128 = 1.41421356237309504880168872420969807856967187537694807317668_f128; - - /// 1/sqrt(2) - #[unstable(feature = "f128", issue = "116909")] - pub const FRAC_1_SQRT_2: f128 = - 0.707106781186547524400844362104849039284835937688474036588340_f128; - - /// sqrt(3) - #[unstable(feature = "f128", issue = "116909")] - // Also, #[unstable(feature = "more_float_constants", issue = "103883")] - pub const SQRT_3: f128 = 1.73205080756887729352744634150587236694280525381038062805581_f128; - - /// 1/sqrt(3) - #[unstable(feature = "f128", issue = "116909")] - // Also, #[unstable(feature = "more_float_constants", issue = "103883")] - pub const FRAC_1_SQRT_3: f128 = - 0.577350269189625764509148780501957455647601751270126876018602_f128; - - /// Euler's number (e) - #[unstable(feature = "f128", issue = "116909")] - pub const E: f128 = 2.71828182845904523536028747135266249775724709369995957496697_f128; - - /// log2(10) - #[unstable(feature = "f128", issue = "116909")] - pub const LOG2_10: f128 = 3.32192809488736234787031942948939017586483139302458061205476_f128; - - /// log2(e) - #[unstable(feature = "f128", issue = "116909")] - pub const LOG2_E: f128 = 1.44269504088896340735992468100189213742664595415298593413545_f128; - - /// log10(2) - #[unstable(feature = "f128", issue = "116909")] - pub const LOG10_2: f128 = 0.301029995663981195213738894724493026768189881462108541310427_f128; - - /// log10(e) - #[unstable(feature = "f128", issue = "116909")] - pub const LOG10_E: f128 = 0.434294481903251827651128918916605082294397005803666566114454_f128; - - /// ln(2) - #[unstable(feature = "f128", issue = "116909")] - pub const LN_2: f128 = 0.693147180559945309417232121458176568075500134360255254120680_f128; - - /// ln(10) - #[unstable(feature = "f128", issue = "116909")] - pub const LN_10: f128 = 2.30258509299404568401799145468436420760110148862877297603333_f128; -} - -#[cfg(not(test))] -impl f128 { - // FIXME(f16_f128): almost all methods in this `impl` are missing examples and a const - // implementation. Add these once we can run code on all platforms and have f16/f128 in CTFE. - - /// The radix or base of the internal representation of `f128`. - #[unstable(feature = "f128", issue = "116909")] - pub const RADIX: u32 = 2; - - /// Number of significant digits in base 2. - #[unstable(feature = "f128", issue = "116909")] - pub const MANTISSA_DIGITS: u32 = 113; - - /// Approximate number of significant digits in base 10. - /// - /// This is the maximum x such that any decimal number with x - /// significant digits can be converted to `f128` and back without loss. - /// - /// Equal to floor(log10 2[`MANTISSA_DIGITS`] − 1). - /// - /// [`MANTISSA_DIGITS`]: f128::MANTISSA_DIGITS - #[unstable(feature = "f128", issue = "116909")] - pub const DIGITS: u32 = 33; - - /// [Machine epsilon] value for `f128`. - /// - /// This is the difference between `1.0` and the next larger representable number. - /// - /// Equal to 21 − [`MANTISSA_DIGITS`]. - /// - /// [Machine epsilon]: https://en.wikipedia.org/wiki/Machine_epsilon - /// [`MANTISSA_DIGITS`]: f128::MANTISSA_DIGITS - #[unstable(feature = "f128", issue = "116909")] - pub const EPSILON: f128 = 1.92592994438723585305597794258492731e-34_f128; - - /// Smallest finite `f128` value. - /// - /// Equal to −[`MAX`]. - /// - /// [`MAX`]: f128::MAX - #[unstable(feature = "f128", issue = "116909")] - pub const MIN: f128 = -1.18973149535723176508575932662800701e+4932_f128; - /// Smallest positive normal `f128` value. - /// - /// Equal to 2[`MIN_EXP`] − 1. - /// - /// [`MIN_EXP`]: f128::MIN_EXP - #[unstable(feature = "f128", issue = "116909")] - pub const MIN_POSITIVE: f128 = 3.36210314311209350626267781732175260e-4932_f128; - /// Largest finite `f128` value. - /// - /// Equal to - /// (1 − 2−[`MANTISSA_DIGITS`]) 2[`MAX_EXP`]. - /// - /// [`MANTISSA_DIGITS`]: f128::MANTISSA_DIGITS - /// [`MAX_EXP`]: f128::MAX_EXP - #[unstable(feature = "f128", issue = "116909")] - pub const MAX: f128 = 1.18973149535723176508575932662800701e+4932_f128; - - /// One greater than the minimum possible normal power of 2 exponent. - /// - /// If x = `MIN_EXP`, then normal numbers - /// ≥ 0.5 × 2x. - #[unstable(feature = "f128", issue = "116909")] - pub const MIN_EXP: i32 = -16_381; - /// Maximum possible power of 2 exponent. - /// - /// If x = `MAX_EXP`, then normal numbers - /// < 1 × 2x. - #[unstable(feature = "f128", issue = "116909")] - pub const MAX_EXP: i32 = 16_384; - - /// Minimum x for which 10x is normal. - /// - /// Equal to ceil(log10 [`MIN_POSITIVE`]). - /// - /// [`MIN_POSITIVE`]: f128::MIN_POSITIVE - #[unstable(feature = "f128", issue = "116909")] - pub const MIN_10_EXP: i32 = -4_931; - /// Maximum x for which 10x is normal. - /// - /// Equal to floor(log10 [`MAX`]). - /// - /// [`MAX`]: f128::MAX - #[unstable(feature = "f128", issue = "116909")] - pub const MAX_10_EXP: i32 = 4_932; - - /// Returns `true` if this value is NaN. - #[inline] - #[must_use] - #[unstable(feature = "f128", issue = "116909")] - #[allow(clippy::eq_op)] // > if you intended to check if the operand is NaN, use `.is_nan()` instead :) - pub const fn is_nan(self) -> bool { - self != self - } - - /// Returns `true` if `self` has a positive sign, including `+0.0`, NaNs with - /// positive sign bit and positive infinity. Note that IEEE 754 doesn't assign any - /// meaning to the sign bit in case of a NaN, and as Rust doesn't guarantee that - /// the bit pattern of NaNs are conserved over arithmetic operations, the result of - /// `is_sign_positive` on a NaN might produce an unexpected result in some cases. - /// See [explanation of NaN as a special value](f32) for more info. - /// - /// ``` - /// #![feature(f128)] - /// - /// let f = 7.0_f128; - /// let g = -7.0_f128; - /// - /// assert!(f.is_sign_positive()); - /// assert!(!g.is_sign_positive()); - /// ``` - #[inline] - #[must_use] - #[unstable(feature = "f128", issue = "116909")] - pub fn is_sign_positive(self) -> bool { - !self.is_sign_negative() - } - - /// Returns `true` if `self` has a negative sign, including `-0.0`, NaNs with - /// negative sign bit and negative infinity. Note that IEEE 754 doesn't assign any - /// meaning to the sign bit in case of a NaN, and as Rust doesn't guarantee that - /// the bit pattern of NaNs are conserved over arithmetic operations, the result of - /// `is_sign_negative` on a NaN might produce an unexpected result in some cases. - /// See [explanation of NaN as a special value](f32) for more info. - /// - /// ``` - /// #![feature(f128)] - /// - /// let f = 7.0_f128; - /// let g = -7.0_f128; - /// - /// assert!(!f.is_sign_negative()); - /// assert!(g.is_sign_negative()); - /// ``` - #[inline] - #[must_use] - #[unstable(feature = "f128", issue = "116909")] - pub fn is_sign_negative(self) -> bool { - // IEEE754 says: isSignMinus(x) is true if and only if x has negative sign. isSignMinus - // applies to zeros and NaNs as well. - // SAFETY: This is just transmuting to get the sign bit, it's fine. - (self.to_bits() & (1 << 127)) != 0 - } - - /// Raw transmutation to `u128`. - /// - /// This is currently identical to `transmute::(self)` on all platforms. - /// - /// See [`from_bits`](#method.from_bits) for some discussion of the - /// portability of this operation (there are almost no issues). - /// - /// Note that this function is distinct from `as` casting, which attempts to - /// preserve the *numeric* value, and not the bitwise value. - #[inline] - #[unstable(feature = "f128", issue = "116909")] - #[must_use = "this returns the result of the operation, without modifying the original"] - pub fn to_bits(self) -> u128 { - // SAFETY: `u128` is a plain old datatype so we can always... uh... - // ...look, just pretend you forgot what you just read. - // Stability concerns. - unsafe { mem::transmute(self) } - } - - /// Raw transmutation from `u128`. - /// - /// This is currently identical to `transmute::(v)` on all platforms. - /// It turns out this is incredibly portable, for two reasons: - /// - /// * Floats and Ints have the same endianness on all supported platforms. - /// * IEEE 754 very precisely specifies the bit layout of floats. - /// - /// However there is one caveat: prior to the 2008 version of IEEE 754, how - /// to interpret the NaN signaling bit wasn't actually specified. Most platforms - /// (notably x86 and ARM) picked the interpretation that was ultimately - /// standardized in 2008, but some didn't (notably MIPS). As a result, all - /// signaling NaNs on MIPS are quiet NaNs on x86, and vice-versa. - /// - /// Rather than trying to preserve signaling-ness cross-platform, this - /// implementation favors preserving the exact bits. This means that - /// any payloads encoded in NaNs will be preserved even if the result of - /// this method is sent over the network from an x86 machine to a MIPS one. - /// - /// If the results of this method are only manipulated by the same - /// architecture that produced them, then there is no portability concern. - /// - /// If the input isn't NaN, then there is no portability concern. - /// - /// If you don't care about signalingness (very likely), then there is no - /// portability concern. - /// - /// Note that this function is distinct from `as` casting, which attempts to - /// preserve the *numeric* value, and not the bitwise value. - #[inline] - #[must_use] - #[unstable(feature = "f128", issue = "116909")] - pub fn from_bits(v: u128) -> Self { - // SAFETY: `u128 is a plain old datatype so we can always... uh... - // ...look, just pretend you forgot what you just read. - // Stability concerns. - unsafe { mem::transmute(v) } - } -} diff --git a/library/core/src/num/f16.rs b/library/core/src/num/f16.rs deleted file mode 100644 index c4d4584544bad..0000000000000 --- a/library/core/src/num/f16.rs +++ /dev/null @@ -1,327 +0,0 @@ -//! Constants for the `f16` half-precision floating point type. -//! -//! *[See also the `f16` primitive type][f16].* -//! -//! Mathematically significant numbers are provided in the `consts` sub-module. -//! -//! For the constants defined directly in this module -//! (as distinct from those defined in the `consts` sub-module), -//! new code should instead use the associated constants -//! defined directly on the `f16` type. - -#![unstable(feature = "f16", issue = "116909")] - -use crate::mem; - -/// Basic mathematical constants. -#[unstable(feature = "f16", issue = "116909")] -pub mod consts { - // FIXME: replace with mathematical constants from cmath. - - /// Archimedes' constant (π) - #[unstable(feature = "f16", issue = "116909")] - pub const PI: f16 = 3.14159265358979323846264338327950288_f16; - - /// The full circle constant (τ) - /// - /// Equal to 2π. - #[unstable(feature = "f16", issue = "116909")] - pub const TAU: f16 = 6.28318530717958647692528676655900577_f16; - - /// The golden ratio (φ) - #[unstable(feature = "f16", issue = "116909")] - // Also, #[unstable(feature = "more_float_constants", issue = "103883")] - pub const PHI: f16 = 1.618033988749894848204586834365638118_f16; - - /// The Euler-Mascheroni constant (γ) - #[unstable(feature = "f16", issue = "116909")] - // Also, #[unstable(feature = "more_float_constants", issue = "103883")] - pub const EGAMMA: f16 = 0.577215664901532860606512090082402431_f16; - - /// π/2 - #[unstable(feature = "f16", issue = "116909")] - pub const FRAC_PI_2: f16 = 1.57079632679489661923132169163975144_f16; - - /// π/3 - #[unstable(feature = "f16", issue = "116909")] - pub const FRAC_PI_3: f16 = 1.04719755119659774615421446109316763_f16; - - /// π/4 - #[unstable(feature = "f16", issue = "116909")] - pub const FRAC_PI_4: f16 = 0.785398163397448309615660845819875721_f16; - - /// π/6 - #[unstable(feature = "f16", issue = "116909")] - pub const FRAC_PI_6: f16 = 0.52359877559829887307710723054658381_f16; - - /// π/8 - #[unstable(feature = "f16", issue = "116909")] - pub const FRAC_PI_8: f16 = 0.39269908169872415480783042290993786_f16; - - /// 1/π - #[unstable(feature = "f16", issue = "116909")] - pub const FRAC_1_PI: f16 = 0.318309886183790671537767526745028724_f16; - - /// 1/sqrt(π) - #[unstable(feature = "f16", issue = "116909")] - // Also, #[unstable(feature = "more_float_constants", issue = "103883")] - pub const FRAC_1_SQRT_PI: f16 = 0.564189583547756286948079451560772586_f16; - - /// 2/π - #[unstable(feature = "f16", issue = "116909")] - pub const FRAC_2_PI: f16 = 0.636619772367581343075535053490057448_f16; - - /// 2/sqrt(π) - #[unstable(feature = "f16", issue = "116909")] - pub const FRAC_2_SQRT_PI: f16 = 1.12837916709551257389615890312154517_f16; - - /// sqrt(2) - #[unstable(feature = "f16", issue = "116909")] - pub const SQRT_2: f16 = 1.41421356237309504880168872420969808_f16; - - /// 1/sqrt(2) - #[unstable(feature = "f16", issue = "116909")] - pub const FRAC_1_SQRT_2: f16 = 0.707106781186547524400844362104849039_f16; - - /// sqrt(3) - #[unstable(feature = "f16", issue = "116909")] - // Also, #[unstable(feature = "more_float_constants", issue = "103883")] - pub const SQRT_3: f16 = 1.732050807568877293527446341505872367_f16; - - /// 1/sqrt(3) - #[unstable(feature = "f16", issue = "116909")] - // Also, #[unstable(feature = "more_float_constants", issue = "103883")] - pub const FRAC_1_SQRT_3: f16 = 0.577350269189625764509148780501957456_f16; - - /// Euler's number (e) - #[unstable(feature = "f16", issue = "116909")] - pub const E: f16 = 2.71828182845904523536028747135266250_f16; - - /// log2(10) - #[unstable(feature = "f16", issue = "116909")] - pub const LOG2_10: f16 = 3.32192809488736234787031942948939018_f16; - - /// log2(e) - #[unstable(feature = "f16", issue = "116909")] - pub const LOG2_E: f16 = 1.44269504088896340735992468100189214_f16; - - /// log10(2) - #[unstable(feature = "f16", issue = "116909")] - pub const LOG10_2: f16 = 0.301029995663981195213738894724493027_f16; - - /// log10(e) - #[unstable(feature = "f16", issue = "116909")] - pub const LOG10_E: f16 = 0.434294481903251827651128918916605082_f16; - - /// ln(2) - #[unstable(feature = "f16", issue = "116909")] - pub const LN_2: f16 = 0.693147180559945309417232121458176568_f16; - - /// ln(10) - #[unstable(feature = "f16", issue = "116909")] - pub const LN_10: f16 = 2.30258509299404568401799145468436421_f16; -} - -#[cfg(not(test))] -impl f16 { - // FIXME(f16_f128): almost all methods in this `impl` are missing examples and a const - // implementation. Add these once we can run code on all platforms and have f16/f128 in CTFE. - - /// The radix or base of the internal representation of `f16`. - #[unstable(feature = "f16", issue = "116909")] - pub const RADIX: u32 = 2; - - /// Number of significant digits in base 2. - #[unstable(feature = "f16", issue = "116909")] - pub const MANTISSA_DIGITS: u32 = 11; - - /// Approximate number of significant digits in base 10. - /// - /// This is the maximum x such that any decimal number with x - /// significant digits can be converted to `f16` and back without loss. - /// - /// Equal to floor(log10 2[`MANTISSA_DIGITS`] − 1). - /// - /// [`MANTISSA_DIGITS`]: f16::MANTISSA_DIGITS - #[unstable(feature = "f16", issue = "116909")] - pub const DIGITS: u32 = 3; - - /// [Machine epsilon] value for `f16`. - /// - /// This is the difference between `1.0` and the next larger representable number. - /// - /// Equal to 21 − [`MANTISSA_DIGITS`]. - /// - /// [Machine epsilon]: https://en.wikipedia.org/wiki/Machine_epsilon - /// [`MANTISSA_DIGITS`]: f16::MANTISSA_DIGITS - #[unstable(feature = "f16", issue = "116909")] - pub const EPSILON: f16 = 9.7656e-4_f16; - - /// Smallest finite `f16` value. - /// - /// Equal to −[`MAX`]. - /// - /// [`MAX`]: f16::MAX - #[unstable(feature = "f16", issue = "116909")] - pub const MIN: f16 = -6.5504e+4_f16; - /// Smallest positive normal `f16` value. - /// - /// Equal to 2[`MIN_EXP`] − 1. - /// - /// [`MIN_EXP`]: f16::MIN_EXP - #[unstable(feature = "f16", issue = "116909")] - pub const MIN_POSITIVE: f16 = 6.1035e-5_f16; - /// Largest finite `f16` value. - /// - /// Equal to - /// (1 − 2−[`MANTISSA_DIGITS`]) 2[`MAX_EXP`]. - /// - /// [`MANTISSA_DIGITS`]: f16::MANTISSA_DIGITS - /// [`MAX_EXP`]: f16::MAX_EXP - #[unstable(feature = "f16", issue = "116909")] - pub const MAX: f16 = 6.5504e+4_f16; - - /// One greater than the minimum possible normal power of 2 exponent. - /// - /// If x = `MIN_EXP`, then normal numbers - /// ≥ 0.5 × 2x. - #[unstable(feature = "f16", issue = "116909")] - pub const MIN_EXP: i32 = -13; - /// Maximum possible power of 2 exponent. - /// - /// If x = `MAX_EXP`, then normal numbers - /// < 1 × 2x. - #[unstable(feature = "f16", issue = "116909")] - pub const MAX_EXP: i32 = 16; - - /// Minimum x for which 10x is normal. - /// - /// Equal to ceil(log10 [`MIN_POSITIVE`]). - /// - /// [`MIN_POSITIVE`]: f16::MIN_POSITIVE - #[unstable(feature = "f16", issue = "116909")] - pub const MIN_10_EXP: i32 = -4; - /// Maximum x for which 10x is normal. - /// - /// Equal to floor(log10 [`MAX`]). - /// - /// [`MAX`]: f16::MAX - #[unstable(feature = "f16", issue = "116909")] - pub const MAX_10_EXP: i32 = 4; - - /// Returns `true` if this value is NaN. - #[inline] - #[must_use] - #[unstable(feature = "f16", issue = "116909")] - #[allow(clippy::eq_op)] // > if you intended to check if the operand is NaN, use `.is_nan()` instead :) - pub const fn is_nan(self) -> bool { - self != self - } - - /// Returns `true` if `self` has a positive sign, including `+0.0`, NaNs with - /// positive sign bit and positive infinity. Note that IEEE 754 doesn't assign any - /// meaning to the sign bit in case of a NaN, and as Rust doesn't guarantee that - /// the bit pattern of NaNs are conserved over arithmetic operations, the result of - /// `is_sign_positive` on a NaN might produce an unexpected result in some cases. - /// See [explanation of NaN as a special value](f32) for more info. - /// - /// ``` - /// #![feature(f16)] - /// - /// let f = 7.0_f16; - /// let g = -7.0_f16; - /// - /// assert!(f.is_sign_positive()); - /// assert!(!g.is_sign_positive()); - /// ``` - #[inline] - #[must_use] - #[unstable(feature = "f16", issue = "116909")] - pub fn is_sign_positive(self) -> bool { - !self.is_sign_negative() - } - - /// Returns `true` if `self` has a negative sign, including `-0.0`, NaNs with - /// negative sign bit and negative infinity. Note that IEEE 754 doesn't assign any - /// meaning to the sign bit in case of a NaN, and as Rust doesn't guarantee that - /// the bit pattern of NaNs are conserved over arithmetic operations, the result of - /// `is_sign_negative` on a NaN might produce an unexpected result in some cases. - /// See [explanation of NaN as a special value](f32) for more info. - /// - /// ``` - /// #![feature(f16)] - /// - /// let f = 7.0_f16; - /// let g = -7.0_f16; - /// - /// assert!(!f.is_sign_negative()); - /// assert!(g.is_sign_negative()); - /// ``` - #[inline] - #[must_use] - #[unstable(feature = "f16", issue = "116909")] - pub fn is_sign_negative(self) -> bool { - // IEEE754 says: isSignMinus(x) is true if and only if x has negative sign. isSignMinus - // applies to zeros and NaNs as well. - // SAFETY: This is just transmuting to get the sign bit, it's fine. - (self.to_bits() & (1 << 15)) != 0 - } - - /// Raw transmutation to `u16`. - /// - /// This is currently identical to `transmute::(self)` on all platforms. - /// - /// See [`from_bits`](#method.from_bits) for some discussion of the - /// portability of this operation (there are almost no issues). - /// - /// Note that this function is distinct from `as` casting, which attempts to - /// preserve the *numeric* value, and not the bitwise value. - #[inline] - #[unstable(feature = "f16", issue = "116909")] - #[must_use = "this returns the result of the operation, without modifying the original"] - pub fn to_bits(self) -> u16 { - // SAFETY: `u16` is a plain old datatype so we can always... uh... - // ...look, just pretend you forgot what you just read. - // Stability concerns. - unsafe { mem::transmute(self) } - } - - /// Raw transmutation from `u16`. - /// - /// This is currently identical to `transmute::(v)` on all platforms. - /// It turns out this is incredibly portable, for two reasons: - /// - /// * Floats and Ints have the same endianness on all supported platforms. - /// * IEEE 754 very precisely specifies the bit layout of floats. - /// - /// However there is one caveat: prior to the 2008 version of IEEE 754, how - /// to interpret the NaN signaling bit wasn't actually specified. Most platforms - /// (notably x86 and ARM) picked the interpretation that was ultimately - /// standardized in 2008, but some didn't (notably MIPS). As a result, all - /// signaling NaNs on MIPS are quiet NaNs on x86, and vice-versa. - /// - /// Rather than trying to preserve signaling-ness cross-platform, this - /// implementation favors preserving the exact bits. This means that - /// any payloads encoded in NaNs will be preserved even if the result of - /// this method is sent over the network from an x86 machine to a MIPS one. - /// - /// If the results of this method are only manipulated by the same - /// architecture that produced them, then there is no portability concern. - /// - /// If the input isn't NaN, then there is no portability concern. - /// - /// If you don't care about signalingness (very likely), then there is no - /// portability concern. - /// - /// Note that this function is distinct from `as` casting, which attempts to - /// preserve the *numeric* value, and not the bitwise value. - #[inline] - #[must_use] - #[unstable(feature = "f16", issue = "116909")] - pub fn from_bits(v: u16) -> Self { - // SAFETY: `u16` is a plain old datatype so we can always... uh... - // ...look, just pretend you forgot what you just read. - // Stability concerns. - unsafe { mem::transmute(v) } - } -} diff --git a/library/core/src/num/f32.rs b/library/core/src/num/f32.rs deleted file mode 100644 index 2e715fb0bdde7..0000000000000 --- a/library/core/src/num/f32.rs +++ /dev/null @@ -1,1521 +0,0 @@ -//! Constants for the `f32` single-precision floating point type. -//! -//! *[See also the `f32` primitive type][f32].* -//! -//! Mathematically significant numbers are provided in the `consts` sub-module. -//! -//! For the constants defined directly in this module -//! (as distinct from those defined in the `consts` sub-module), -//! new code should instead use the associated constants -//! defined directly on the `f32` type. - -#![stable(feature = "rust1", since = "1.0.0")] - -use crate::convert::FloatToInt; -#[cfg(not(test))] -use crate::intrinsics; -use crate::mem; -use crate::num::FpCategory; - -/// The radix or base of the internal representation of `f32`. -/// Use [`f32::RADIX`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let r = std::f32::RADIX; -/// -/// // intended way -/// let r = f32::RADIX; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `RADIX` associated constant on `f32`")] -#[rustc_diagnostic_item = "f32_legacy_const_radix"] -pub const RADIX: u32 = f32::RADIX; - -/// Number of significant digits in base 2. -/// Use [`f32::MANTISSA_DIGITS`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let d = std::f32::MANTISSA_DIGITS; -/// -/// // intended way -/// let d = f32::MANTISSA_DIGITS; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated( - since = "TBD", - note = "replaced by the `MANTISSA_DIGITS` associated constant on `f32`" -)] -#[rustc_diagnostic_item = "f32_legacy_const_mantissa_dig"] -pub const MANTISSA_DIGITS: u32 = f32::MANTISSA_DIGITS; - -/// Approximate number of significant digits in base 10. -/// Use [`f32::DIGITS`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let d = std::f32::DIGITS; -/// -/// // intended way -/// let d = f32::DIGITS; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `DIGITS` associated constant on `f32`")] -#[rustc_diagnostic_item = "f32_legacy_const_digits"] -pub const DIGITS: u32 = f32::DIGITS; - -/// [Machine epsilon] value for `f32`. -/// Use [`f32::EPSILON`] instead. -/// -/// This is the difference between `1.0` and the next larger representable number. -/// -/// [Machine epsilon]: https://en.wikipedia.org/wiki/Machine_epsilon -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let e = std::f32::EPSILON; -/// -/// // intended way -/// let e = f32::EPSILON; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `EPSILON` associated constant on `f32`")] -#[rustc_diagnostic_item = "f32_legacy_const_epsilon"] -pub const EPSILON: f32 = f32::EPSILON; - -/// Smallest finite `f32` value. -/// Use [`f32::MIN`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let min = std::f32::MIN; -/// -/// // intended way -/// let min = f32::MIN; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `MIN` associated constant on `f32`")] -#[rustc_diagnostic_item = "f32_legacy_const_min"] -pub const MIN: f32 = f32::MIN; - -/// Smallest positive normal `f32` value. -/// Use [`f32::MIN_POSITIVE`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let min = std::f32::MIN_POSITIVE; -/// -/// // intended way -/// let min = f32::MIN_POSITIVE; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `MIN_POSITIVE` associated constant on `f32`")] -#[rustc_diagnostic_item = "f32_legacy_const_min_positive"] -pub const MIN_POSITIVE: f32 = f32::MIN_POSITIVE; - -/// Largest finite `f32` value. -/// Use [`f32::MAX`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let max = std::f32::MAX; -/// -/// // intended way -/// let max = f32::MAX; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `MAX` associated constant on `f32`")] -#[rustc_diagnostic_item = "f32_legacy_const_max"] -pub const MAX: f32 = f32::MAX; - -/// One greater than the minimum possible normal power of 2 exponent. -/// Use [`f32::MIN_EXP`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let min = std::f32::MIN_EXP; -/// -/// // intended way -/// let min = f32::MIN_EXP; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `MIN_EXP` associated constant on `f32`")] -#[rustc_diagnostic_item = "f32_legacy_const_min_exp"] -pub const MIN_EXP: i32 = f32::MIN_EXP; - -/// Maximum possible power of 2 exponent. -/// Use [`f32::MAX_EXP`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let max = std::f32::MAX_EXP; -/// -/// // intended way -/// let max = f32::MAX_EXP; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `MAX_EXP` associated constant on `f32`")] -#[rustc_diagnostic_item = "f32_legacy_const_max_exp"] -pub const MAX_EXP: i32 = f32::MAX_EXP; - -/// Minimum possible normal power of 10 exponent. -/// Use [`f32::MIN_10_EXP`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let min = std::f32::MIN_10_EXP; -/// -/// // intended way -/// let min = f32::MIN_10_EXP; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `MIN_10_EXP` associated constant on `f32`")] -#[rustc_diagnostic_item = "f32_legacy_const_min_10_exp"] -pub const MIN_10_EXP: i32 = f32::MIN_10_EXP; - -/// Maximum possible power of 10 exponent. -/// Use [`f32::MAX_10_EXP`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let max = std::f32::MAX_10_EXP; -/// -/// // intended way -/// let max = f32::MAX_10_EXP; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `MAX_10_EXP` associated constant on `f32`")] -#[rustc_diagnostic_item = "f32_legacy_const_max_10_exp"] -pub const MAX_10_EXP: i32 = f32::MAX_10_EXP; - -/// Not a Number (NaN). -/// Use [`f32::NAN`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let nan = std::f32::NAN; -/// -/// // intended way -/// let nan = f32::NAN; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `NAN` associated constant on `f32`")] -#[rustc_diagnostic_item = "f32_legacy_const_nan"] -pub const NAN: f32 = f32::NAN; - -/// Infinity (∞). -/// Use [`f32::INFINITY`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let inf = std::f32::INFINITY; -/// -/// // intended way -/// let inf = f32::INFINITY; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `INFINITY` associated constant on `f32`")] -#[rustc_diagnostic_item = "f32_legacy_const_infinity"] -pub const INFINITY: f32 = f32::INFINITY; - -/// Negative infinity (−∞). -/// Use [`f32::NEG_INFINITY`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let ninf = std::f32::NEG_INFINITY; -/// -/// // intended way -/// let ninf = f32::NEG_INFINITY; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `NEG_INFINITY` associated constant on `f32`")] -#[rustc_diagnostic_item = "f32_legacy_const_neg_infinity"] -pub const NEG_INFINITY: f32 = f32::NEG_INFINITY; - -/// Basic mathematical constants. -#[stable(feature = "rust1", since = "1.0.0")] -pub mod consts { - // FIXME: replace with mathematical constants from cmath. - - /// Archimedes' constant (π) - #[stable(feature = "rust1", since = "1.0.0")] - pub const PI: f32 = 3.14159265358979323846264338327950288_f32; - - /// The full circle constant (τ) - /// - /// Equal to 2π. - #[stable(feature = "tau_constant", since = "1.47.0")] - pub const TAU: f32 = 6.28318530717958647692528676655900577_f32; - - /// The golden ratio (φ) - #[unstable(feature = "more_float_constants", issue = "103883")] - pub const PHI: f32 = 1.618033988749894848204586834365638118_f32; - - /// The Euler-Mascheroni constant (γ) - #[unstable(feature = "more_float_constants", issue = "103883")] - pub const EGAMMA: f32 = 0.577215664901532860606512090082402431_f32; - - /// π/2 - #[stable(feature = "rust1", since = "1.0.0")] - pub const FRAC_PI_2: f32 = 1.57079632679489661923132169163975144_f32; - - /// π/3 - #[stable(feature = "rust1", since = "1.0.0")] - pub const FRAC_PI_3: f32 = 1.04719755119659774615421446109316763_f32; - - /// π/4 - #[stable(feature = "rust1", since = "1.0.0")] - pub const FRAC_PI_4: f32 = 0.785398163397448309615660845819875721_f32; - - /// π/6 - #[stable(feature = "rust1", since = "1.0.0")] - pub const FRAC_PI_6: f32 = 0.52359877559829887307710723054658381_f32; - - /// π/8 - #[stable(feature = "rust1", since = "1.0.0")] - pub const FRAC_PI_8: f32 = 0.39269908169872415480783042290993786_f32; - - /// 1/π - #[stable(feature = "rust1", since = "1.0.0")] - pub const FRAC_1_PI: f32 = 0.318309886183790671537767526745028724_f32; - - /// 1/sqrt(π) - #[unstable(feature = "more_float_constants", issue = "103883")] - pub const FRAC_1_SQRT_PI: f32 = 0.564189583547756286948079451560772586_f32; - - /// 2/π - #[stable(feature = "rust1", since = "1.0.0")] - pub const FRAC_2_PI: f32 = 0.636619772367581343075535053490057448_f32; - - /// 2/sqrt(π) - #[stable(feature = "rust1", since = "1.0.0")] - pub const FRAC_2_SQRT_PI: f32 = 1.12837916709551257389615890312154517_f32; - - /// sqrt(2) - #[stable(feature = "rust1", since = "1.0.0")] - pub const SQRT_2: f32 = 1.41421356237309504880168872420969808_f32; - - /// 1/sqrt(2) - #[stable(feature = "rust1", since = "1.0.0")] - pub const FRAC_1_SQRT_2: f32 = 0.707106781186547524400844362104849039_f32; - - /// sqrt(3) - #[unstable(feature = "more_float_constants", issue = "103883")] - pub const SQRT_3: f32 = 1.732050807568877293527446341505872367_f32; - - /// 1/sqrt(3) - #[unstable(feature = "more_float_constants", issue = "103883")] - pub const FRAC_1_SQRT_3: f32 = 0.577350269189625764509148780501957456_f32; - - /// Euler's number (e) - #[stable(feature = "rust1", since = "1.0.0")] - pub const E: f32 = 2.71828182845904523536028747135266250_f32; - - /// log2(e) - #[stable(feature = "rust1", since = "1.0.0")] - pub const LOG2_E: f32 = 1.44269504088896340735992468100189214_f32; - - /// log2(10) - #[stable(feature = "extra_log_consts", since = "1.43.0")] - pub const LOG2_10: f32 = 3.32192809488736234787031942948939018_f32; - - /// log10(e) - #[stable(feature = "rust1", since = "1.0.0")] - pub const LOG10_E: f32 = 0.434294481903251827651128918916605082_f32; - - /// log10(2) - #[stable(feature = "extra_log_consts", since = "1.43.0")] - pub const LOG10_2: f32 = 0.301029995663981195213738894724493027_f32; - - /// ln(2) - #[stable(feature = "rust1", since = "1.0.0")] - pub const LN_2: f32 = 0.693147180559945309417232121458176568_f32; - - /// ln(10) - #[stable(feature = "rust1", since = "1.0.0")] - pub const LN_10: f32 = 2.30258509299404568401799145468436421_f32; -} - -#[cfg(not(test))] -impl f32 { - /// The radix or base of the internal representation of `f32`. - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const RADIX: u32 = 2; - - /// Number of significant digits in base 2. - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const MANTISSA_DIGITS: u32 = 24; - - /// Approximate number of significant digits in base 10. - /// - /// This is the maximum x such that any decimal number with x - /// significant digits can be converted to `f32` and back without loss. - /// - /// Equal to floor(log10 2[`MANTISSA_DIGITS`] − 1). - /// - /// [`MANTISSA_DIGITS`]: f32::MANTISSA_DIGITS - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const DIGITS: u32 = 6; - - /// [Machine epsilon] value for `f32`. - /// - /// This is the difference between `1.0` and the next larger representable number. - /// - /// Equal to 21 − [`MANTISSA_DIGITS`]. - /// - /// [Machine epsilon]: https://en.wikipedia.org/wiki/Machine_epsilon - /// [`MANTISSA_DIGITS`]: f32::MANTISSA_DIGITS - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const EPSILON: f32 = 1.19209290e-07_f32; - - /// Smallest finite `f32` value. - /// - /// Equal to −[`MAX`]. - /// - /// [`MAX`]: f32::MAX - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const MIN: f32 = -3.40282347e+38_f32; - /// Smallest positive normal `f32` value. - /// - /// Equal to 2[`MIN_EXP`] − 1. - /// - /// [`MIN_EXP`]: f32::MIN_EXP - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const MIN_POSITIVE: f32 = 1.17549435e-38_f32; - /// Largest finite `f32` value. - /// - /// Equal to - /// (1 − 2−[`MANTISSA_DIGITS`]) 2[`MAX_EXP`]. - /// - /// [`MANTISSA_DIGITS`]: f32::MANTISSA_DIGITS - /// [`MAX_EXP`]: f32::MAX_EXP - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const MAX: f32 = 3.40282347e+38_f32; - - /// One greater than the minimum possible normal power of 2 exponent. - /// - /// If x = `MIN_EXP`, then normal numbers - /// ≥ 0.5 × 2x. - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const MIN_EXP: i32 = -125; - /// Maximum possible power of 2 exponent. - /// - /// If x = `MAX_EXP`, then normal numbers - /// < 1 × 2x. - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const MAX_EXP: i32 = 128; - - /// Minimum x for which 10x is normal. - /// - /// Equal to ceil(log10 [`MIN_POSITIVE`]). - /// - /// [`MIN_POSITIVE`]: f32::MIN_POSITIVE - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const MIN_10_EXP: i32 = -37; - /// Maximum x for which 10x is normal. - /// - /// Equal to floor(log10 [`MAX`]). - /// - /// [`MAX`]: f32::MAX - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const MAX_10_EXP: i32 = 38; - - /// Not a Number (NaN). - /// - /// Note that IEEE 754 doesn't define just a single NaN value; - /// a plethora of bit patterns are considered to be NaN. - /// Furthermore, the standard makes a difference - /// between a "signaling" and a "quiet" NaN, - /// and allows inspecting its "payload" (the unspecified bits in the bit pattern). - /// This constant isn't guaranteed to equal to any specific NaN bitpattern, - /// and the stability of its representation over Rust versions - /// and target platforms isn't guaranteed. - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - #[rustc_diagnostic_item = "f32_nan"] - #[allow(clippy::eq_op)] - pub const NAN: f32 = 0.0_f32 / 0.0_f32; - /// Infinity (∞). - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const INFINITY: f32 = 1.0_f32 / 0.0_f32; - /// Negative infinity (−∞). - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const NEG_INFINITY: f32 = -1.0_f32 / 0.0_f32; - - /// Returns `true` if this value is NaN. - /// - /// ``` - /// let nan = f32::NAN; - /// let f = 7.0_f32; - /// - /// assert!(nan.is_nan()); - /// assert!(!f.is_nan()); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] - #[inline] - #[allow(clippy::eq_op)] // > if you intended to check if the operand is NaN, use `.is_nan()` instead :) - pub const fn is_nan(self) -> bool { - self != self - } - - // FIXME(#50145): `abs` is publicly unavailable in core due to - // concerns about portability, so this implementation is for - // private use internally. - #[inline] - #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] - pub(crate) const fn abs_private(self) -> f32 { - // SAFETY: This transmutation is fine. Probably. For the reasons std is using it. - unsafe { mem::transmute::(mem::transmute::(self) & 0x7fff_ffff) } - } - - /// Returns `true` if this value is positive infinity or negative infinity, and - /// `false` otherwise. - /// - /// ``` - /// let f = 7.0f32; - /// let inf = f32::INFINITY; - /// let neg_inf = f32::NEG_INFINITY; - /// let nan = f32::NAN; - /// - /// assert!(!f.is_infinite()); - /// assert!(!nan.is_infinite()); - /// - /// assert!(inf.is_infinite()); - /// assert!(neg_inf.is_infinite()); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] - #[inline] - pub const fn is_infinite(self) -> bool { - // Getting clever with transmutation can result in incorrect answers on some FPUs - // FIXME: alter the Rust <-> Rust calling convention to prevent this problem. - // See https://github.com/rust-lang/rust/issues/72327 - (self == f32::INFINITY) | (self == f32::NEG_INFINITY) - } - - /// Returns `true` if this number is neither infinite nor NaN. - /// - /// ``` - /// let f = 7.0f32; - /// let inf = f32::INFINITY; - /// let neg_inf = f32::NEG_INFINITY; - /// let nan = f32::NAN; - /// - /// assert!(f.is_finite()); - /// - /// assert!(!nan.is_finite()); - /// assert!(!inf.is_finite()); - /// assert!(!neg_inf.is_finite()); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] - #[inline] - pub const fn is_finite(self) -> bool { - // There's no need to handle NaN separately: if self is NaN, - // the comparison is not true, exactly as desired. - self.abs_private() < Self::INFINITY - } - - /// Returns `true` if the number is [subnormal]. - /// - /// ``` - /// let min = f32::MIN_POSITIVE; // 1.17549435e-38f32 - /// let max = f32::MAX; - /// let lower_than_min = 1.0e-40_f32; - /// let zero = 0.0_f32; - /// - /// assert!(!min.is_subnormal()); - /// assert!(!max.is_subnormal()); - /// - /// assert!(!zero.is_subnormal()); - /// assert!(!f32::NAN.is_subnormal()); - /// assert!(!f32::INFINITY.is_subnormal()); - /// // Values between `0` and `min` are Subnormal. - /// assert!(lower_than_min.is_subnormal()); - /// ``` - /// [subnormal]: https://en.wikipedia.org/wiki/Denormal_number - #[must_use] - #[stable(feature = "is_subnormal", since = "1.53.0")] - #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] - #[inline] - pub const fn is_subnormal(self) -> bool { - matches!(self.classify(), FpCategory::Subnormal) - } - - /// Returns `true` if the number is neither zero, infinite, - /// [subnormal], or NaN. - /// - /// ``` - /// let min = f32::MIN_POSITIVE; // 1.17549435e-38f32 - /// let max = f32::MAX; - /// let lower_than_min = 1.0e-40_f32; - /// let zero = 0.0_f32; - /// - /// assert!(min.is_normal()); - /// assert!(max.is_normal()); - /// - /// assert!(!zero.is_normal()); - /// assert!(!f32::NAN.is_normal()); - /// assert!(!f32::INFINITY.is_normal()); - /// // Values between `0` and `min` are Subnormal. - /// assert!(!lower_than_min.is_normal()); - /// ``` - /// [subnormal]: https://en.wikipedia.org/wiki/Denormal_number - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] - #[inline] - pub const fn is_normal(self) -> bool { - matches!(self.classify(), FpCategory::Normal) - } - - /// Returns the floating point category of the number. If only one property - /// is going to be tested, it is generally faster to use the specific - /// predicate instead. - /// - /// ``` - /// use std::num::FpCategory; - /// - /// let num = 12.4_f32; - /// let inf = f32::INFINITY; - /// - /// assert_eq!(num.classify(), FpCategory::Normal); - /// assert_eq!(inf.classify(), FpCategory::Infinite); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] - pub const fn classify(self) -> FpCategory { - // A previous implementation tried to only use bitmask-based checks, - // using f32::to_bits to transmute the float to its bit repr and match on that. - // Unfortunately, floating point numbers can be much worse than that. - // This also needs to not result in recursive evaluations of f64::to_bits. - // - // On some processors, in some cases, LLVM will "helpfully" lower floating point ops, - // in spite of a request for them using f32 and f64, to things like x87 operations. - // These have an f64's mantissa, but can have a larger than normal exponent. - // FIXME(jubilee): Using x87 operations is never necessary in order to function - // on x86 processors for Rust-to-Rust calls, so this issue should not happen. - // Code generation should be adjusted to use non-C calling conventions, avoiding this. - // - if self.is_infinite() { - // Thus, a value may compare unequal to infinity, despite having a "full" exponent mask. - FpCategory::Infinite - } else if self.is_nan() { - // And it may not be NaN, as it can simply be an "overextended" finite value. - FpCategory::Nan - } else { - // However, std can't simply compare to zero to check for zero, either, - // as correctness requires avoiding equality tests that may be Subnormal == -0.0 - // because it may be wrong under "denormals are zero" and "flush to zero" modes. - // Most of std's targets don't use those, but they are used for thumbv7neon. - // So, this does use bitpattern matching for the rest. - - // SAFETY: f32 to u32 is fine. Usually. - // If classify has gotten this far, the value is definitely in one of these categories. - unsafe { f32::partial_classify(self) } - } - } - - // This doesn't actually return a right answer for NaN on purpose, - // seeing as how it cannot correctly discern between a floating point NaN, - // and some normal floating point numbers truncated from an x87 FPU. - // FIXME(jubilee): This probably could at least answer things correctly for Infinity, - // like the f64 version does, but I need to run more checks on how things go on x86. - // I fear losing mantissa data that would have answered that differently. - // - // # Safety - // This requires making sure you call this function for values it answers correctly on, - // otherwise it returns a wrong answer. This is not important for memory safety per se, - // but getting floats correct is important for not accidentally leaking const eval - // runtime-deviating logic which may or may not be acceptable. - #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] - const unsafe fn partial_classify(self) -> FpCategory { - const EXP_MASK: u32 = 0x7f800000; - const MAN_MASK: u32 = 0x007fffff; - - // SAFETY: The caller is not asking questions for which this will tell lies. - let b = unsafe { mem::transmute::(self) }; - match (b & MAN_MASK, b & EXP_MASK) { - (0, 0) => FpCategory::Zero, - (_, 0) => FpCategory::Subnormal, - _ => FpCategory::Normal, - } - } - - // This operates on bits, and only bits, so it can ignore concerns about weird FPUs. - // FIXME(jubilee): In a just world, this would be the entire impl for classify, - // plus a transmute. We do not live in a just world, but we can make it more so. - #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] - const fn classify_bits(b: u32) -> FpCategory { - const EXP_MASK: u32 = 0x7f800000; - const MAN_MASK: u32 = 0x007fffff; - - match (b & MAN_MASK, b & EXP_MASK) { - (0, EXP_MASK) => FpCategory::Infinite, - (_, EXP_MASK) => FpCategory::Nan, - (0, 0) => FpCategory::Zero, - (_, 0) => FpCategory::Subnormal, - _ => FpCategory::Normal, - } - } - - /// Returns `true` if `self` has a positive sign, including `+0.0`, NaNs with - /// positive sign bit and positive infinity. Note that IEEE 754 doesn't assign any - /// meaning to the sign bit in case of a NaN, and as Rust doesn't guarantee that - /// the bit pattern of NaNs are conserved over arithmetic operations, the result of - /// `is_sign_positive` on a NaN might produce an unexpected result in some cases. - /// See [explanation of NaN as a special value](f32) for more info. - /// - /// ``` - /// let f = 7.0_f32; - /// let g = -7.0_f32; - /// - /// assert!(f.is_sign_positive()); - /// assert!(!g.is_sign_positive()); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] - #[inline] - pub const fn is_sign_positive(self) -> bool { - !self.is_sign_negative() - } - - /// Returns `true` if `self` has a negative sign, including `-0.0`, NaNs with - /// negative sign bit and negative infinity. Note that IEEE 754 doesn't assign any - /// meaning to the sign bit in case of a NaN, and as Rust doesn't guarantee that - /// the bit pattern of NaNs are conserved over arithmetic operations, the result of - /// `is_sign_negative` on a NaN might produce an unexpected result in some cases. - /// See [explanation of NaN as a special value](f32) for more info. - /// - /// ``` - /// let f = 7.0f32; - /// let g = -7.0f32; - /// - /// assert!(!f.is_sign_negative()); - /// assert!(g.is_sign_negative()); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] - #[inline] - pub const fn is_sign_negative(self) -> bool { - // IEEE754 says: isSignMinus(x) is true if and only if x has negative sign. isSignMinus - // applies to zeros and NaNs as well. - // SAFETY: This is just transmuting to get the sign bit, it's fine. - unsafe { mem::transmute::(self) & 0x8000_0000 != 0 } - } - - /// Returns the least number greater than `self`. - /// - /// Let `TINY` be the smallest representable positive `f32`. Then, - /// - if `self.is_nan()`, this returns `self`; - /// - if `self` is [`NEG_INFINITY`], this returns [`MIN`]; - /// - if `self` is `-TINY`, this returns -0.0; - /// - if `self` is -0.0 or +0.0, this returns `TINY`; - /// - if `self` is [`MAX`] or [`INFINITY`], this returns [`INFINITY`]; - /// - otherwise the unique least value greater than `self` is returned. - /// - /// The identity `x.next_up() == -(-x).next_down()` holds for all non-NaN `x`. When `x` - /// is finite `x == x.next_up().next_down()` also holds. - /// - /// ```rust - /// #![feature(float_next_up_down)] - /// // f32::EPSILON is the difference between 1.0 and the next number up. - /// assert_eq!(1.0f32.next_up(), 1.0 + f32::EPSILON); - /// // But not for most numbers. - /// assert!(0.1f32.next_up() < 0.1 + f32::EPSILON); - /// assert_eq!(16777216f32.next_up(), 16777218.0); - /// ``` - /// - /// [`NEG_INFINITY`]: Self::NEG_INFINITY - /// [`INFINITY`]: Self::INFINITY - /// [`MIN`]: Self::MIN - /// [`MAX`]: Self::MAX - #[unstable(feature = "float_next_up_down", issue = "91399")] - #[rustc_const_unstable(feature = "float_next_up_down", issue = "91399")] - pub const fn next_up(self) -> Self { - // We must use strictly integer arithmetic to prevent denormals from - // flushing to zero after an arithmetic operation on some platforms. - const TINY_BITS: u32 = 0x1; // Smallest positive f32. - const CLEAR_SIGN_MASK: u32 = 0x7fff_ffff; - - let bits = self.to_bits(); - if self.is_nan() || bits == Self::INFINITY.to_bits() { - return self; - } - - let abs = bits & CLEAR_SIGN_MASK; - let next_bits = if abs == 0 { - TINY_BITS - } else if bits == abs { - bits + 1 - } else { - bits - 1 - }; - Self::from_bits(next_bits) - } - - /// Returns the greatest number less than `self`. - /// - /// Let `TINY` be the smallest representable positive `f32`. Then, - /// - if `self.is_nan()`, this returns `self`; - /// - if `self` is [`INFINITY`], this returns [`MAX`]; - /// - if `self` is `TINY`, this returns 0.0; - /// - if `self` is -0.0 or +0.0, this returns `-TINY`; - /// - if `self` is [`MIN`] or [`NEG_INFINITY`], this returns [`NEG_INFINITY`]; - /// - otherwise the unique greatest value less than `self` is returned. - /// - /// The identity `x.next_down() == -(-x).next_up()` holds for all non-NaN `x`. When `x` - /// is finite `x == x.next_down().next_up()` also holds. - /// - /// ```rust - /// #![feature(float_next_up_down)] - /// let x = 1.0f32; - /// // Clamp value into range [0, 1). - /// let clamped = x.clamp(0.0, 1.0f32.next_down()); - /// assert!(clamped < 1.0); - /// assert_eq!(clamped.next_up(), 1.0); - /// ``` - /// - /// [`NEG_INFINITY`]: Self::NEG_INFINITY - /// [`INFINITY`]: Self::INFINITY - /// [`MIN`]: Self::MIN - /// [`MAX`]: Self::MAX - #[unstable(feature = "float_next_up_down", issue = "91399")] - #[rustc_const_unstable(feature = "float_next_up_down", issue = "91399")] - pub const fn next_down(self) -> Self { - // We must use strictly integer arithmetic to prevent denormals from - // flushing to zero after an arithmetic operation on some platforms. - const NEG_TINY_BITS: u32 = 0x8000_0001; // Smallest (in magnitude) negative f32. - const CLEAR_SIGN_MASK: u32 = 0x7fff_ffff; - - let bits = self.to_bits(); - if self.is_nan() || bits == Self::NEG_INFINITY.to_bits() { - return self; - } - - let abs = bits & CLEAR_SIGN_MASK; - let next_bits = if abs == 0 { - NEG_TINY_BITS - } else if bits == abs { - bits - 1 - } else { - bits + 1 - }; - Self::from_bits(next_bits) - } - - /// Takes the reciprocal (inverse) of a number, `1/x`. - /// - /// ``` - /// let x = 2.0_f32; - /// let abs_difference = (x.recip() - (1.0 / x)).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[must_use = "this returns the result of the operation, without modifying the original"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn recip(self) -> f32 { - 1.0 / self - } - - /// Converts radians to degrees. - /// - /// ``` - /// let angle = std::f32::consts::PI; - /// - /// let abs_difference = (angle.to_degrees() - 180.0).abs(); - /// # #[cfg(any(not(target_arch = "x86"), target_feature = "sse2"))] - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[stable(feature = "f32_deg_rad_conversions", since = "1.7.0")] - #[inline] - pub fn to_degrees(self) -> f32 { - // Use a constant for better precision. - const PIS_IN_180: f32 = 57.2957795130823208767981548141051703_f32; - self * PIS_IN_180 - } - - /// Converts degrees to radians. - /// - /// ``` - /// let angle = 180.0f32; - /// - /// let abs_difference = (angle.to_radians() - std::f32::consts::PI).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[stable(feature = "f32_deg_rad_conversions", since = "1.7.0")] - #[inline] - pub fn to_radians(self) -> f32 { - let value: f32 = consts::PI; - self * (value / 180.0f32) - } - - /// Returns the maximum of the two numbers, ignoring NaN. - /// - /// If one of the arguments is NaN, then the other argument is returned. - /// This follows the IEEE 754-2008 semantics for maxNum, except for handling of signaling NaNs; - /// this function handles all NaNs the same way and avoids maxNum's problems with associativity. - /// This also matches the behavior of libm’s fmax. - /// - /// ``` - /// let x = 1.0f32; - /// let y = 2.0f32; - /// - /// assert_eq!(x.max(y), y); - /// ``` - #[must_use = "this returns the result of the comparison, without modifying either input"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn max(self, other: f32) -> f32 { - intrinsics::maxnumf32(self, other) - } - - /// Returns the minimum of the two numbers, ignoring NaN. - /// - /// If one of the arguments is NaN, then the other argument is returned. - /// This follows the IEEE 754-2008 semantics for minNum, except for handling of signaling NaNs; - /// this function handles all NaNs the same way and avoids minNum's problems with associativity. - /// This also matches the behavior of libm’s fmin. - /// - /// ``` - /// let x = 1.0f32; - /// let y = 2.0f32; - /// - /// assert_eq!(x.min(y), x); - /// ``` - #[must_use = "this returns the result of the comparison, without modifying either input"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn min(self, other: f32) -> f32 { - intrinsics::minnumf32(self, other) - } - - /// Returns the maximum of the two numbers, propagating NaN. - /// - /// This returns NaN when *either* argument is NaN, as opposed to - /// [`f32::max`] which only returns NaN when *both* arguments are NaN. - /// - /// ``` - /// #![feature(float_minimum_maximum)] - /// let x = 1.0f32; - /// let y = 2.0f32; - /// - /// assert_eq!(x.maximum(y), y); - /// assert!(x.maximum(f32::NAN).is_nan()); - /// ``` - /// - /// If one of the arguments is NaN, then NaN is returned. Otherwise this returns the greater - /// of the two numbers. For this operation, -0.0 is considered to be less than +0.0. - /// Note that this follows the semantics specified in IEEE 754-2019. - /// - /// Also note that "propagation" of NaNs here doesn't necessarily mean that the bitpattern of a NaN - /// operand is conserved; see [explanation of NaN as a special value](f32) for more info. - #[must_use = "this returns the result of the comparison, without modifying either input"] - #[unstable(feature = "float_minimum_maximum", issue = "91079")] - #[inline] - pub fn maximum(self, other: f32) -> f32 { - if self > other { - self - } else if other > self { - other - } else if self == other { - if self.is_sign_positive() && other.is_sign_negative() { self } else { other } - } else { - self + other - } - } - - /// Returns the minimum of the two numbers, propagating NaN. - /// - /// This returns NaN when *either* argument is NaN, as opposed to - /// [`f32::min`] which only returns NaN when *both* arguments are NaN. - /// - /// ``` - /// #![feature(float_minimum_maximum)] - /// let x = 1.0f32; - /// let y = 2.0f32; - /// - /// assert_eq!(x.minimum(y), x); - /// assert!(x.minimum(f32::NAN).is_nan()); - /// ``` - /// - /// If one of the arguments is NaN, then NaN is returned. Otherwise this returns the lesser - /// of the two numbers. For this operation, -0.0 is considered to be less than +0.0. - /// Note that this follows the semantics specified in IEEE 754-2019. - /// - /// Also note that "propagation" of NaNs here doesn't necessarily mean that the bitpattern of a NaN - /// operand is conserved; see [explanation of NaN as a special value](f32) for more info. - #[must_use = "this returns the result of the comparison, without modifying either input"] - #[unstable(feature = "float_minimum_maximum", issue = "91079")] - #[inline] - pub fn minimum(self, other: f32) -> f32 { - if self < other { - self - } else if other < self { - other - } else if self == other { - if self.is_sign_negative() && other.is_sign_positive() { self } else { other } - } else { - // At least one input is NaN. Use `+` to perform NaN propagation and quieting. - self + other - } - } - - /// Calculates the middle point of `self` and `rhs`. - /// - /// This returns NaN when *either* argument is NaN or if a combination of - /// +inf and -inf is provided as arguments. - /// - /// # Examples - /// - /// ``` - /// #![feature(num_midpoint)] - /// assert_eq!(1f32.midpoint(4.0), 2.5); - /// assert_eq!((-5.5f32).midpoint(8.0), 1.25); - /// ``` - #[unstable(feature = "num_midpoint", issue = "110840")] - pub fn midpoint(self, other: f32) -> f32 { - const LO: f32 = f32::MIN_POSITIVE * 2.; - const HI: f32 = f32::MAX / 2.; - - let (a, b) = (self, other); - let abs_a = a.abs_private(); - let abs_b = b.abs_private(); - - if abs_a <= HI && abs_b <= HI { - // Overflow is impossible - (a + b) / 2. - } else if abs_a < LO { - // Not safe to halve a - a + (b / 2.) - } else if abs_b < LO { - // Not safe to halve b - (a / 2.) + b - } else { - // Not safe to halve a and b - (a / 2.) + (b / 2.) - } - } - - /// Rounds toward zero and converts to any primitive integer type, - /// assuming that the value is finite and fits in that type. - /// - /// ``` - /// let value = 4.6_f32; - /// let rounded = unsafe { value.to_int_unchecked::() }; - /// assert_eq!(rounded, 4); - /// - /// let value = -128.9_f32; - /// let rounded = unsafe { value.to_int_unchecked::() }; - /// assert_eq!(rounded, i8::MIN); - /// ``` - /// - /// # Safety - /// - /// The value must: - /// - /// * Not be `NaN` - /// * Not be infinite - /// * Be representable in the return type `Int`, after truncating off its fractional part - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[stable(feature = "float_approx_unchecked_to", since = "1.44.0")] - #[inline] - pub unsafe fn to_int_unchecked(self) -> Int - where - Self: FloatToInt, - { - // SAFETY: the caller must uphold the safety contract for - // `FloatToInt::to_int_unchecked`. - unsafe { FloatToInt::::to_int_unchecked(self) } - } - - /// Raw transmutation to `u32`. - /// - /// This is currently identical to `transmute::(self)` on all platforms. - /// - /// See [`from_bits`](Self::from_bits) for some discussion of the - /// portability of this operation (there are almost no issues). - /// - /// Note that this function is distinct from `as` casting, which attempts to - /// preserve the *numeric* value, and not the bitwise value. - /// - /// # Examples - /// - /// ``` - /// assert_ne!((1f32).to_bits(), 1f32 as u32); // to_bits() is not casting! - /// assert_eq!((12.5f32).to_bits(), 0x41480000); - /// - /// ``` - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[stable(feature = "float_bits_conv", since = "1.20.0")] - #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] - #[inline] - pub const fn to_bits(self) -> u32 { - // SAFETY: `u32` is a plain old datatype so we can always transmute to it. - // ...sorta. - // - // It turns out that at runtime, it is possible for a floating point number - // to be subject to a floating point mode that alters nonzero subnormal numbers - // to zero on reads and writes, aka "denormals are zero" and "flush to zero". - // This is not a problem per se, but at least one tier2 platform for Rust - // actually exhibits this behavior by default. - // - // In addition, on x86 targets with SSE or SSE2 disabled and the x87 FPU enabled, - // i.e. not soft-float, the way Rust does parameter passing can actually alter - // a number that is "not infinity" to have the same exponent as infinity, - // in a slightly unpredictable manner. - // - // And, of course evaluating to a NaN value is fairly nondeterministic. - // More precisely: when NaN should be returned is knowable, but which NaN? - // So far that's defined by a combination of LLVM and the CPU, not Rust. - // This function, however, allows observing the bitstring of a NaN, - // thus introspection on CTFE. - // - // In order to preserve, at least for the moment, const-to-runtime equivalence, - // we reject any of these possible situations from happening. - #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] - const fn ct_f32_to_u32(ct: f32) -> u32 { - match ct.classify() { - FpCategory::Nan => { - panic!("const-eval error: cannot use f32::to_bits on a NaN") - } - FpCategory::Subnormal => { - panic!("const-eval error: cannot use f32::to_bits on a subnormal number") - } - FpCategory::Infinite | FpCategory::Normal | FpCategory::Zero => { - // SAFETY: We have a normal floating point number. Now we transmute, i.e. do a bitcopy. - unsafe { mem::transmute::(ct) } - } - } - } - - #[inline(always)] // See https://github.com/rust-lang/compiler-builtins/issues/491 - fn rt_f32_to_u32(x: f32) -> u32 { - // SAFETY: `u32` is a plain old datatype so we can always... uh... - // ...look, just pretend you forgot what you just read. - // Stability concerns. - unsafe { mem::transmute(x) } - } - intrinsics::const_eval_select((self,), ct_f32_to_u32, rt_f32_to_u32) - } - - /// Raw transmutation from `u32`. - /// - /// This is currently identical to `transmute::(v)` on all platforms. - /// It turns out this is incredibly portable, for two reasons: - /// - /// * Floats and Ints have the same endianness on all supported platforms. - /// * IEEE 754 very precisely specifies the bit layout of floats. - /// - /// However there is one caveat: prior to the 2008 version of IEEE 754, how - /// to interpret the NaN signaling bit wasn't actually specified. Most platforms - /// (notably x86 and ARM) picked the interpretation that was ultimately - /// standardized in 2008, but some didn't (notably MIPS). As a result, all - /// signaling NaNs on MIPS are quiet NaNs on x86, and vice-versa. - /// - /// Rather than trying to preserve signaling-ness cross-platform, this - /// implementation favors preserving the exact bits. This means that - /// any payloads encoded in NaNs will be preserved even if the result of - /// this method is sent over the network from an x86 machine to a MIPS one. - /// - /// If the results of this method are only manipulated by the same - /// architecture that produced them, then there is no portability concern. - /// - /// If the input isn't NaN, then there is no portability concern. - /// - /// If you don't care about signalingness (very likely), then there is no - /// portability concern. - /// - /// Note that this function is distinct from `as` casting, which attempts to - /// preserve the *numeric* value, and not the bitwise value. - /// - /// # Examples - /// - /// ``` - /// let v = f32::from_bits(0x41480000); - /// assert_eq!(v, 12.5); - /// ``` - #[stable(feature = "float_bits_conv", since = "1.20.0")] - #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] - #[must_use] - #[inline] - pub const fn from_bits(v: u32) -> Self { - // It turns out the safety issues with sNaN were overblown! Hooray! - // SAFETY: `u32` is a plain old datatype so we can always transmute from it - // ...sorta. - // - // It turns out that at runtime, it is possible for a floating point number - // to be subject to floating point modes that alter nonzero subnormal numbers - // to zero on reads and writes, aka "denormals are zero" and "flush to zero". - // This is not a problem usually, but at least one tier2 platform for Rust - // actually exhibits this behavior by default: thumbv7neon - // aka "the Neon FPU in AArch32 state" - // - // In addition, on x86 targets with SSE or SSE2 disabled and the x87 FPU enabled, - // i.e. not soft-float, the way Rust does parameter passing can actually alter - // a number that is "not infinity" to have the same exponent as infinity, - // in a slightly unpredictable manner. - // - // And, of course evaluating to a NaN value is fairly nondeterministic. - // More precisely: when NaN should be returned is knowable, but which NaN? - // So far that's defined by a combination of LLVM and the CPU, not Rust. - // This function, however, allows observing the bitstring of a NaN, - // thus introspection on CTFE. - // - // In order to preserve, at least for the moment, const-to-runtime equivalence, - // reject any of these possible situations from happening. - #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] - const fn ct_u32_to_f32(ct: u32) -> f32 { - match f32::classify_bits(ct) { - FpCategory::Subnormal => { - panic!("const-eval error: cannot use f32::from_bits on a subnormal number") - } - FpCategory::Nan => { - panic!("const-eval error: cannot use f32::from_bits on NaN") - } - FpCategory::Infinite | FpCategory::Normal | FpCategory::Zero => { - // SAFETY: It's not a frumious number - unsafe { mem::transmute::(ct) } - } - } - } - - #[inline(always)] // See https://github.com/rust-lang/compiler-builtins/issues/491 - fn rt_u32_to_f32(x: u32) -> f32 { - // SAFETY: `u32` is a plain old datatype so we can always... uh... - // ...look, just pretend you forgot what you just read. - // Stability concerns. - unsafe { mem::transmute(x) } - } - intrinsics::const_eval_select((v,), ct_u32_to_f32, rt_u32_to_f32) - } - - /// Return the memory representation of this floating point number as a byte array in - /// big-endian (network) byte order. - /// - /// See [`from_bits`](Self::from_bits) for some discussion of the - /// portability of this operation (there are almost no issues). - /// - /// # Examples - /// - /// ``` - /// let bytes = 12.5f32.to_be_bytes(); - /// assert_eq!(bytes, [0x41, 0x48, 0x00, 0x00]); - /// ``` - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[stable(feature = "float_to_from_bytes", since = "1.40.0")] - #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] - #[inline] - pub const fn to_be_bytes(self) -> [u8; 4] { - self.to_bits().to_be_bytes() - } - - /// Return the memory representation of this floating point number as a byte array in - /// little-endian byte order. - /// - /// See [`from_bits`](Self::from_bits) for some discussion of the - /// portability of this operation (there are almost no issues). - /// - /// # Examples - /// - /// ``` - /// let bytes = 12.5f32.to_le_bytes(); - /// assert_eq!(bytes, [0x00, 0x00, 0x48, 0x41]); - /// ``` - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[stable(feature = "float_to_from_bytes", since = "1.40.0")] - #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] - #[inline] - pub const fn to_le_bytes(self) -> [u8; 4] { - self.to_bits().to_le_bytes() - } - - /// Return the memory representation of this floating point number as a byte array in - /// native byte order. - /// - /// As the target platform's native endianness is used, portable code - /// should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate, instead. - /// - /// [`to_be_bytes`]: f32::to_be_bytes - /// [`to_le_bytes`]: f32::to_le_bytes - /// - /// See [`from_bits`](Self::from_bits) for some discussion of the - /// portability of this operation (there are almost no issues). - /// - /// # Examples - /// - /// ``` - /// let bytes = 12.5f32.to_ne_bytes(); - /// assert_eq!( - /// bytes, - /// if cfg!(target_endian = "big") { - /// [0x41, 0x48, 0x00, 0x00] - /// } else { - /// [0x00, 0x00, 0x48, 0x41] - /// } - /// ); - /// ``` - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[stable(feature = "float_to_from_bytes", since = "1.40.0")] - #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] - #[inline] - pub const fn to_ne_bytes(self) -> [u8; 4] { - self.to_bits().to_ne_bytes() - } - - /// Create a floating point value from its representation as a byte array in big endian. - /// - /// See [`from_bits`](Self::from_bits) for some discussion of the - /// portability of this operation (there are almost no issues). - /// - /// # Examples - /// - /// ``` - /// let value = f32::from_be_bytes([0x41, 0x48, 0x00, 0x00]); - /// assert_eq!(value, 12.5); - /// ``` - #[stable(feature = "float_to_from_bytes", since = "1.40.0")] - #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] - #[must_use] - #[inline] - pub const fn from_be_bytes(bytes: [u8; 4]) -> Self { - Self::from_bits(u32::from_be_bytes(bytes)) - } - - /// Create a floating point value from its representation as a byte array in little endian. - /// - /// See [`from_bits`](Self::from_bits) for some discussion of the - /// portability of this operation (there are almost no issues). - /// - /// # Examples - /// - /// ``` - /// let value = f32::from_le_bytes([0x00, 0x00, 0x48, 0x41]); - /// assert_eq!(value, 12.5); - /// ``` - #[stable(feature = "float_to_from_bytes", since = "1.40.0")] - #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] - #[must_use] - #[inline] - pub const fn from_le_bytes(bytes: [u8; 4]) -> Self { - Self::from_bits(u32::from_le_bytes(bytes)) - } - - /// Create a floating point value from its representation as a byte array in native endian. - /// - /// As the target platform's native endianness is used, portable code - /// likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as - /// appropriate instead. - /// - /// [`from_be_bytes`]: f32::from_be_bytes - /// [`from_le_bytes`]: f32::from_le_bytes - /// - /// See [`from_bits`](Self::from_bits) for some discussion of the - /// portability of this operation (there are almost no issues). - /// - /// # Examples - /// - /// ``` - /// let value = f32::from_ne_bytes(if cfg!(target_endian = "big") { - /// [0x41, 0x48, 0x00, 0x00] - /// } else { - /// [0x00, 0x00, 0x48, 0x41] - /// }); - /// assert_eq!(value, 12.5); - /// ``` - #[stable(feature = "float_to_from_bytes", since = "1.40.0")] - #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] - #[must_use] - #[inline] - pub const fn from_ne_bytes(bytes: [u8; 4]) -> Self { - Self::from_bits(u32::from_ne_bytes(bytes)) - } - - /// Return the ordering between `self` and `other`. - /// - /// Unlike the standard partial comparison between floating point numbers, - /// this comparison always produces an ordering in accordance to - /// the `totalOrder` predicate as defined in the IEEE 754 (2008 revision) - /// floating point standard. The values are ordered in the following sequence: - /// - /// - negative quiet NaN - /// - negative signaling NaN - /// - negative infinity - /// - negative numbers - /// - negative subnormal numbers - /// - negative zero - /// - positive zero - /// - positive subnormal numbers - /// - positive numbers - /// - positive infinity - /// - positive signaling NaN - /// - positive quiet NaN. - /// - /// The ordering established by this function does not always agree with the - /// [`PartialOrd`] and [`PartialEq`] implementations of `f32`. For example, - /// they consider negative and positive zero equal, while `total_cmp` - /// doesn't. - /// - /// The interpretation of the signaling NaN bit follows the definition in - /// the IEEE 754 standard, which may not match the interpretation by some of - /// the older, non-conformant (e.g. MIPS) hardware implementations. - /// - /// # Example - /// - /// ``` - /// struct GoodBoy { - /// name: String, - /// weight: f32, - /// } - /// - /// let mut bois = vec![ - /// GoodBoy { name: "Pucci".to_owned(), weight: 0.1 }, - /// GoodBoy { name: "Woofer".to_owned(), weight: 99.0 }, - /// GoodBoy { name: "Yapper".to_owned(), weight: 10.0 }, - /// GoodBoy { name: "Chonk".to_owned(), weight: f32::INFINITY }, - /// GoodBoy { name: "Abs. Unit".to_owned(), weight: f32::NAN }, - /// GoodBoy { name: "Floaty".to_owned(), weight: -5.0 }, - /// ]; - /// - /// bois.sort_by(|a, b| a.weight.total_cmp(&b.weight)); - /// - /// // `f32::NAN` could be positive or negative, which will affect the sort order. - /// if f32::NAN.is_sign_negative() { - /// assert!(bois.into_iter().map(|b| b.weight) - /// .zip([f32::NAN, -5.0, 0.1, 10.0, 99.0, f32::INFINITY].iter()) - /// .all(|(a, b)| a.to_bits() == b.to_bits())) - /// } else { - /// assert!(bois.into_iter().map(|b| b.weight) - /// .zip([-5.0, 0.1, 10.0, 99.0, f32::INFINITY, f32::NAN].iter()) - /// .all(|(a, b)| a.to_bits() == b.to_bits())) - /// } - /// ``` - #[stable(feature = "total_cmp", since = "1.62.0")] - #[must_use] - #[inline] - pub fn total_cmp(&self, other: &Self) -> crate::cmp::Ordering { - let mut left = self.to_bits() as i32; - let mut right = other.to_bits() as i32; - - // In case of negatives, flip all the bits except the sign - // to achieve a similar layout as two's complement integers - // - // Why does this work? IEEE 754 floats consist of three fields: - // Sign bit, exponent and mantissa. The set of exponent and mantissa - // fields as a whole have the property that their bitwise order is - // equal to the numeric magnitude where the magnitude is defined. - // The magnitude is not normally defined on NaN values, but - // IEEE 754 totalOrder defines the NaN values also to follow the - // bitwise order. This leads to order explained in the doc comment. - // However, the representation of magnitude is the same for negative - // and positive numbers – only the sign bit is different. - // To easily compare the floats as signed integers, we need to - // flip the exponent and mantissa bits in case of negative numbers. - // We effectively convert the numbers to "two's complement" form. - // - // To do the flipping, we construct a mask and XOR against it. - // We branchlessly calculate an "all-ones except for the sign bit" - // mask from negative-signed values: right shifting sign-extends - // the integer, so we "fill" the mask with sign bits, and then - // convert to unsigned to push one more zero bit. - // On positive values, the mask is all zeros, so it's a no-op. - left ^= (((left >> 31) as u32) >> 1) as i32; - right ^= (((right >> 31) as u32) >> 1) as i32; - - left.cmp(&right) - } - - /// Restrict a value to a certain interval unless it is NaN. - /// - /// Returns `max` if `self` is greater than `max`, and `min` if `self` is - /// less than `min`. Otherwise this returns `self`. - /// - /// Note that this function returns NaN if the initial value was NaN as - /// well. - /// - /// # Panics - /// - /// Panics if `min > max`, `min` is NaN, or `max` is NaN. - /// - /// # Examples - /// - /// ``` - /// assert!((-3.0f32).clamp(-2.0, 1.0) == -2.0); - /// assert!((0.0f32).clamp(-2.0, 1.0) == 0.0); - /// assert!((2.0f32).clamp(-2.0, 1.0) == 1.0); - /// assert!((f32::NAN).clamp(-2.0, 1.0).is_nan()); - /// ``` - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "clamp", since = "1.50.0")] - #[inline] - pub fn clamp(mut self, min: f32, max: f32) -> f32 { - assert!(min <= max, "min > max, or either was NaN. min = {min:?}, max = {max:?}"); - if self < min { - self = min; - } - if self > max { - self = max; - } - self - } -} diff --git a/library/core/src/num/f64.rs b/library/core/src/num/f64.rs deleted file mode 100644 index db8e1f318adba..0000000000000 --- a/library/core/src/num/f64.rs +++ /dev/null @@ -1,1518 +0,0 @@ -//! Constants for the `f64` double-precision floating point type. -//! -//! *[See also the `f64` primitive type][f64].* -//! -//! Mathematically significant numbers are provided in the `consts` sub-module. -//! -//! For the constants defined directly in this module -//! (as distinct from those defined in the `consts` sub-module), -//! new code should instead use the associated constants -//! defined directly on the `f64` type. - -#![stable(feature = "rust1", since = "1.0.0")] - -use crate::convert::FloatToInt; -#[cfg(not(test))] -use crate::intrinsics; -use crate::mem; -use crate::num::FpCategory; - -/// The radix or base of the internal representation of `f64`. -/// Use [`f64::RADIX`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let r = std::f64::RADIX; -/// -/// // intended way -/// let r = f64::RADIX; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `RADIX` associated constant on `f64`")] -#[rustc_diagnostic_item = "f64_legacy_const_radix"] -pub const RADIX: u32 = f64::RADIX; - -/// Number of significant digits in base 2. -/// Use [`f64::MANTISSA_DIGITS`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let d = std::f64::MANTISSA_DIGITS; -/// -/// // intended way -/// let d = f64::MANTISSA_DIGITS; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated( - since = "TBD", - note = "replaced by the `MANTISSA_DIGITS` associated constant on `f64`" -)] -#[rustc_diagnostic_item = "f64_legacy_const_mantissa_dig"] -pub const MANTISSA_DIGITS: u32 = f64::MANTISSA_DIGITS; - -/// Approximate number of significant digits in base 10. -/// Use [`f64::DIGITS`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let d = std::f64::DIGITS; -/// -/// // intended way -/// let d = f64::DIGITS; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `DIGITS` associated constant on `f64`")] -#[rustc_diagnostic_item = "f64_legacy_const_digits"] -pub const DIGITS: u32 = f64::DIGITS; - -/// [Machine epsilon] value for `f64`. -/// Use [`f64::EPSILON`] instead. -/// -/// This is the difference between `1.0` and the next larger representable number. -/// -/// [Machine epsilon]: https://en.wikipedia.org/wiki/Machine_epsilon -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let e = std::f64::EPSILON; -/// -/// // intended way -/// let e = f64::EPSILON; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `EPSILON` associated constant on `f64`")] -#[rustc_diagnostic_item = "f64_legacy_const_epsilon"] -pub const EPSILON: f64 = f64::EPSILON; - -/// Smallest finite `f64` value. -/// Use [`f64::MIN`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let min = std::f64::MIN; -/// -/// // intended way -/// let min = f64::MIN; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `MIN` associated constant on `f64`")] -#[rustc_diagnostic_item = "f64_legacy_const_min"] -pub const MIN: f64 = f64::MIN; - -/// Smallest positive normal `f64` value. -/// Use [`f64::MIN_POSITIVE`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let min = std::f64::MIN_POSITIVE; -/// -/// // intended way -/// let min = f64::MIN_POSITIVE; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `MIN_POSITIVE` associated constant on `f64`")] -#[rustc_diagnostic_item = "f64_legacy_const_min_positive"] -pub const MIN_POSITIVE: f64 = f64::MIN_POSITIVE; - -/// Largest finite `f64` value. -/// Use [`f64::MAX`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let max = std::f64::MAX; -/// -/// // intended way -/// let max = f64::MAX; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `MAX` associated constant on `f64`")] -#[rustc_diagnostic_item = "f64_legacy_const_max"] -pub const MAX: f64 = f64::MAX; - -/// One greater than the minimum possible normal power of 2 exponent. -/// Use [`f64::MIN_EXP`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let min = std::f64::MIN_EXP; -/// -/// // intended way -/// let min = f64::MIN_EXP; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `MIN_EXP` associated constant on `f64`")] -#[rustc_diagnostic_item = "f64_legacy_const_min_exp"] -pub const MIN_EXP: i32 = f64::MIN_EXP; - -/// Maximum possible power of 2 exponent. -/// Use [`f64::MAX_EXP`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let max = std::f64::MAX_EXP; -/// -/// // intended way -/// let max = f64::MAX_EXP; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `MAX_EXP` associated constant on `f64`")] -#[rustc_diagnostic_item = "f64_legacy_const_max_exp"] -pub const MAX_EXP: i32 = f64::MAX_EXP; - -/// Minimum possible normal power of 10 exponent. -/// Use [`f64::MIN_10_EXP`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let min = std::f64::MIN_10_EXP; -/// -/// // intended way -/// let min = f64::MIN_10_EXP; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `MIN_10_EXP` associated constant on `f64`")] -#[rustc_diagnostic_item = "f64_legacy_const_min_10_exp"] -pub const MIN_10_EXP: i32 = f64::MIN_10_EXP; - -/// Maximum possible power of 10 exponent. -/// Use [`f64::MAX_10_EXP`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let max = std::f64::MAX_10_EXP; -/// -/// // intended way -/// let max = f64::MAX_10_EXP; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `MAX_10_EXP` associated constant on `f64`")] -#[rustc_diagnostic_item = "f64_legacy_const_max_10_exp"] -pub const MAX_10_EXP: i32 = f64::MAX_10_EXP; - -/// Not a Number (NaN). -/// Use [`f64::NAN`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let nan = std::f64::NAN; -/// -/// // intended way -/// let nan = f64::NAN; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `NAN` associated constant on `f64`")] -#[rustc_diagnostic_item = "f64_legacy_const_nan"] -pub const NAN: f64 = f64::NAN; - -/// Infinity (∞). -/// Use [`f64::INFINITY`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let inf = std::f64::INFINITY; -/// -/// // intended way -/// let inf = f64::INFINITY; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `INFINITY` associated constant on `f64`")] -#[rustc_diagnostic_item = "f64_legacy_const_infinity"] -pub const INFINITY: f64 = f64::INFINITY; - -/// Negative infinity (−∞). -/// Use [`f64::NEG_INFINITY`] instead. -/// -/// # Examples -/// -/// ```rust -/// // deprecated way -/// # #[allow(deprecated, deprecated_in_future)] -/// let ninf = std::f64::NEG_INFINITY; -/// -/// // intended way -/// let ninf = f64::NEG_INFINITY; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "TBD", note = "replaced by the `NEG_INFINITY` associated constant on `f64`")] -#[rustc_diagnostic_item = "f64_legacy_const_neg_infinity"] -pub const NEG_INFINITY: f64 = f64::NEG_INFINITY; - -/// Basic mathematical constants. -#[stable(feature = "rust1", since = "1.0.0")] -pub mod consts { - // FIXME: replace with mathematical constants from cmath. - - /// Archimedes' constant (π) - #[stable(feature = "rust1", since = "1.0.0")] - pub const PI: f64 = 3.14159265358979323846264338327950288_f64; - - /// The full circle constant (τ) - /// - /// Equal to 2π. - #[stable(feature = "tau_constant", since = "1.47.0")] - pub const TAU: f64 = 6.28318530717958647692528676655900577_f64; - - /// The golden ratio (φ) - #[unstable(feature = "more_float_constants", issue = "103883")] - pub const PHI: f64 = 1.618033988749894848204586834365638118_f64; - - /// The Euler-Mascheroni constant (γ) - #[unstable(feature = "more_float_constants", issue = "103883")] - pub const EGAMMA: f64 = 0.577215664901532860606512090082402431_f64; - - /// π/2 - #[stable(feature = "rust1", since = "1.0.0")] - pub const FRAC_PI_2: f64 = 1.57079632679489661923132169163975144_f64; - - /// π/3 - #[stable(feature = "rust1", since = "1.0.0")] - pub const FRAC_PI_3: f64 = 1.04719755119659774615421446109316763_f64; - - /// π/4 - #[stable(feature = "rust1", since = "1.0.0")] - pub const FRAC_PI_4: f64 = 0.785398163397448309615660845819875721_f64; - - /// π/6 - #[stable(feature = "rust1", since = "1.0.0")] - pub const FRAC_PI_6: f64 = 0.52359877559829887307710723054658381_f64; - - /// π/8 - #[stable(feature = "rust1", since = "1.0.0")] - pub const FRAC_PI_8: f64 = 0.39269908169872415480783042290993786_f64; - - /// 1/π - #[stable(feature = "rust1", since = "1.0.0")] - pub const FRAC_1_PI: f64 = 0.318309886183790671537767526745028724_f64; - - /// 1/sqrt(π) - #[unstable(feature = "more_float_constants", issue = "103883")] - pub const FRAC_1_SQRT_PI: f64 = 0.564189583547756286948079451560772586_f64; - - /// 2/π - #[stable(feature = "rust1", since = "1.0.0")] - pub const FRAC_2_PI: f64 = 0.636619772367581343075535053490057448_f64; - - /// 2/sqrt(π) - #[stable(feature = "rust1", since = "1.0.0")] - pub const FRAC_2_SQRT_PI: f64 = 1.12837916709551257389615890312154517_f64; - - /// sqrt(2) - #[stable(feature = "rust1", since = "1.0.0")] - pub const SQRT_2: f64 = 1.41421356237309504880168872420969808_f64; - - /// 1/sqrt(2) - #[stable(feature = "rust1", since = "1.0.0")] - pub const FRAC_1_SQRT_2: f64 = 0.707106781186547524400844362104849039_f64; - - /// sqrt(3) - #[unstable(feature = "more_float_constants", issue = "103883")] - pub const SQRT_3: f64 = 1.732050807568877293527446341505872367_f64; - - /// 1/sqrt(3) - #[unstable(feature = "more_float_constants", issue = "103883")] - pub const FRAC_1_SQRT_3: f64 = 0.577350269189625764509148780501957456_f64; - - /// Euler's number (e) - #[stable(feature = "rust1", since = "1.0.0")] - pub const E: f64 = 2.71828182845904523536028747135266250_f64; - - /// log2(10) - #[stable(feature = "extra_log_consts", since = "1.43.0")] - pub const LOG2_10: f64 = 3.32192809488736234787031942948939018_f64; - - /// log2(e) - #[stable(feature = "rust1", since = "1.0.0")] - pub const LOG2_E: f64 = 1.44269504088896340735992468100189214_f64; - - /// log10(2) - #[stable(feature = "extra_log_consts", since = "1.43.0")] - pub const LOG10_2: f64 = 0.301029995663981195213738894724493027_f64; - - /// log10(e) - #[stable(feature = "rust1", since = "1.0.0")] - pub const LOG10_E: f64 = 0.434294481903251827651128918916605082_f64; - - /// ln(2) - #[stable(feature = "rust1", since = "1.0.0")] - pub const LN_2: f64 = 0.693147180559945309417232121458176568_f64; - - /// ln(10) - #[stable(feature = "rust1", since = "1.0.0")] - pub const LN_10: f64 = 2.30258509299404568401799145468436421_f64; -} - -#[cfg(not(test))] -impl f64 { - /// The radix or base of the internal representation of `f64`. - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const RADIX: u32 = 2; - - /// Number of significant digits in base 2. - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const MANTISSA_DIGITS: u32 = 53; - /// Approximate number of significant digits in base 10. - /// - /// This is the maximum x such that any decimal number with x - /// significant digits can be converted to `f64` and back without loss. - /// - /// Equal to floor(log10 2[`MANTISSA_DIGITS`] − 1). - /// - /// [`MANTISSA_DIGITS`]: f64::MANTISSA_DIGITS - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const DIGITS: u32 = 15; - - /// [Machine epsilon] value for `f64`. - /// - /// This is the difference between `1.0` and the next larger representable number. - /// - /// Equal to 21 − [`MANTISSA_DIGITS`]. - /// - /// [Machine epsilon]: https://en.wikipedia.org/wiki/Machine_epsilon - /// [`MANTISSA_DIGITS`]: f64::MANTISSA_DIGITS - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const EPSILON: f64 = 2.2204460492503131e-16_f64; - - /// Smallest finite `f64` value. - /// - /// Equal to −[`MAX`]. - /// - /// [`MAX`]: f64::MAX - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const MIN: f64 = -1.7976931348623157e+308_f64; - /// Smallest positive normal `f64` value. - /// - /// Equal to 2[`MIN_EXP`] − 1. - /// - /// [`MIN_EXP`]: f64::MIN_EXP - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const MIN_POSITIVE: f64 = 2.2250738585072014e-308_f64; - /// Largest finite `f64` value. - /// - /// Equal to - /// (1 − 2−[`MANTISSA_DIGITS`]) 2[`MAX_EXP`]. - /// - /// [`MANTISSA_DIGITS`]: f64::MANTISSA_DIGITS - /// [`MAX_EXP`]: f64::MAX_EXP - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const MAX: f64 = 1.7976931348623157e+308_f64; - - /// One greater than the minimum possible normal power of 2 exponent. - /// - /// If x = `MIN_EXP`, then normal numbers - /// ≥ 0.5 × 2x. - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const MIN_EXP: i32 = -1021; - /// Maximum possible power of 2 exponent. - /// - /// If x = `MAX_EXP`, then normal numbers - /// < 1 × 2x. - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const MAX_EXP: i32 = 1024; - - /// Minimum x for which 10x is normal. - /// - /// Equal to ceil(log10 [`MIN_POSITIVE`]). - /// - /// [`MIN_POSITIVE`]: f64::MIN_POSITIVE - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const MIN_10_EXP: i32 = -307; - /// Maximum x for which 10x is normal. - /// - /// Equal to floor(log10 [`MAX`]). - /// - /// [`MAX`]: f64::MAX - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const MAX_10_EXP: i32 = 308; - - /// Not a Number (NaN). - /// - /// Note that IEEE 754 doesn't define just a single NaN value; - /// a plethora of bit patterns are considered to be NaN. - /// Furthermore, the standard makes a difference - /// between a "signaling" and a "quiet" NaN, - /// and allows inspecting its "payload" (the unspecified bits in the bit pattern). - /// This constant isn't guaranteed to equal to any specific NaN bitpattern, - /// and the stability of its representation over Rust versions - /// and target platforms isn't guaranteed. - #[rustc_diagnostic_item = "f64_nan"] - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - #[allow(clippy::eq_op)] - pub const NAN: f64 = 0.0_f64 / 0.0_f64; - /// Infinity (∞). - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const INFINITY: f64 = 1.0_f64 / 0.0_f64; - /// Negative infinity (−∞). - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const NEG_INFINITY: f64 = -1.0_f64 / 0.0_f64; - - /// Returns `true` if this value is NaN. - /// - /// ``` - /// let nan = f64::NAN; - /// let f = 7.0_f64; - /// - /// assert!(nan.is_nan()); - /// assert!(!f.is_nan()); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] - #[inline] - #[allow(clippy::eq_op)] // > if you intended to check if the operand is NaN, use `.is_nan()` instead :) - pub const fn is_nan(self) -> bool { - self != self - } - - // FIXME(#50145): `abs` is publicly unavailable in core due to - // concerns about portability, so this implementation is for - // private use internally. - #[inline] - #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] - pub(crate) const fn abs_private(self) -> f64 { - // SAFETY: This transmutation is fine. Probably. For the reasons std is using it. - unsafe { - mem::transmute::(mem::transmute::(self) & 0x7fff_ffff_ffff_ffff) - } - } - - /// Returns `true` if this value is positive infinity or negative infinity, and - /// `false` otherwise. - /// - /// ``` - /// let f = 7.0f64; - /// let inf = f64::INFINITY; - /// let neg_inf = f64::NEG_INFINITY; - /// let nan = f64::NAN; - /// - /// assert!(!f.is_infinite()); - /// assert!(!nan.is_infinite()); - /// - /// assert!(inf.is_infinite()); - /// assert!(neg_inf.is_infinite()); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] - #[inline] - pub const fn is_infinite(self) -> bool { - // Getting clever with transmutation can result in incorrect answers on some FPUs - // FIXME: alter the Rust <-> Rust calling convention to prevent this problem. - // See https://github.com/rust-lang/rust/issues/72327 - (self == f64::INFINITY) | (self == f64::NEG_INFINITY) - } - - /// Returns `true` if this number is neither infinite nor NaN. - /// - /// ``` - /// let f = 7.0f64; - /// let inf: f64 = f64::INFINITY; - /// let neg_inf: f64 = f64::NEG_INFINITY; - /// let nan: f64 = f64::NAN; - /// - /// assert!(f.is_finite()); - /// - /// assert!(!nan.is_finite()); - /// assert!(!inf.is_finite()); - /// assert!(!neg_inf.is_finite()); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] - #[inline] - pub const fn is_finite(self) -> bool { - // There's no need to handle NaN separately: if self is NaN, - // the comparison is not true, exactly as desired. - self.abs_private() < Self::INFINITY - } - - /// Returns `true` if the number is [subnormal]. - /// - /// ``` - /// let min = f64::MIN_POSITIVE; // 2.2250738585072014e-308_f64 - /// let max = f64::MAX; - /// let lower_than_min = 1.0e-308_f64; - /// let zero = 0.0_f64; - /// - /// assert!(!min.is_subnormal()); - /// assert!(!max.is_subnormal()); - /// - /// assert!(!zero.is_subnormal()); - /// assert!(!f64::NAN.is_subnormal()); - /// assert!(!f64::INFINITY.is_subnormal()); - /// // Values between `0` and `min` are Subnormal. - /// assert!(lower_than_min.is_subnormal()); - /// ``` - /// [subnormal]: https://en.wikipedia.org/wiki/Denormal_number - #[must_use] - #[stable(feature = "is_subnormal", since = "1.53.0")] - #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] - #[inline] - pub const fn is_subnormal(self) -> bool { - matches!(self.classify(), FpCategory::Subnormal) - } - - /// Returns `true` if the number is neither zero, infinite, - /// [subnormal], or NaN. - /// - /// ``` - /// let min = f64::MIN_POSITIVE; // 2.2250738585072014e-308f64 - /// let max = f64::MAX; - /// let lower_than_min = 1.0e-308_f64; - /// let zero = 0.0f64; - /// - /// assert!(min.is_normal()); - /// assert!(max.is_normal()); - /// - /// assert!(!zero.is_normal()); - /// assert!(!f64::NAN.is_normal()); - /// assert!(!f64::INFINITY.is_normal()); - /// // Values between `0` and `min` are Subnormal. - /// assert!(!lower_than_min.is_normal()); - /// ``` - /// [subnormal]: https://en.wikipedia.org/wiki/Denormal_number - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] - #[inline] - pub const fn is_normal(self) -> bool { - matches!(self.classify(), FpCategory::Normal) - } - - /// Returns the floating point category of the number. If only one property - /// is going to be tested, it is generally faster to use the specific - /// predicate instead. - /// - /// ``` - /// use std::num::FpCategory; - /// - /// let num = 12.4_f64; - /// let inf = f64::INFINITY; - /// - /// assert_eq!(num.classify(), FpCategory::Normal); - /// assert_eq!(inf.classify(), FpCategory::Infinite); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] - pub const fn classify(self) -> FpCategory { - // A previous implementation tried to only use bitmask-based checks, - // using f64::to_bits to transmute the float to its bit repr and match on that. - // Unfortunately, floating point numbers can be much worse than that. - // This also needs to not result in recursive evaluations of f64::to_bits. - // - // On some processors, in some cases, LLVM will "helpfully" lower floating point ops, - // in spite of a request for them using f32 and f64, to things like x87 operations. - // These have an f64's mantissa, but can have a larger than normal exponent. - // FIXME(jubilee): Using x87 operations is never necessary in order to function - // on x86 processors for Rust-to-Rust calls, so this issue should not happen. - // Code generation should be adjusted to use non-C calling conventions, avoiding this. - // - // Thus, a value may compare unequal to infinity, despite having a "full" exponent mask. - // And it may not be NaN, as it can simply be an "overextended" finite value. - if self.is_nan() { - FpCategory::Nan - } else { - // However, std can't simply compare to zero to check for zero, either, - // as correctness requires avoiding equality tests that may be Subnormal == -0.0 - // because it may be wrong under "denormals are zero" and "flush to zero" modes. - // Most of std's targets don't use those, but they are used for thumbv7neon. - // So, this does use bitpattern matching for the rest. - - // SAFETY: f64 to u64 is fine. Usually. - // If control flow has gotten this far, the value is definitely in one of the categories - // that f64::partial_classify can correctly analyze. - unsafe { f64::partial_classify(self) } - } - } - - // This doesn't actually return a right answer for NaN on purpose, - // seeing as how it cannot correctly discern between a floating point NaN, - // and some normal floating point numbers truncated from an x87 FPU. - #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] - const unsafe fn partial_classify(self) -> FpCategory { - const EXP_MASK: u64 = 0x7ff0000000000000; - const MAN_MASK: u64 = 0x000fffffffffffff; - - // SAFETY: The caller is not asking questions for which this will tell lies. - let b = unsafe { mem::transmute::(self) }; - match (b & MAN_MASK, b & EXP_MASK) { - (0, EXP_MASK) => FpCategory::Infinite, - (0, 0) => FpCategory::Zero, - (_, 0) => FpCategory::Subnormal, - _ => FpCategory::Normal, - } - } - - // This operates on bits, and only bits, so it can ignore concerns about weird FPUs. - // FIXME(jubilee): In a just world, this would be the entire impl for classify, - // plus a transmute. We do not live in a just world, but we can make it more so. - #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] - const fn classify_bits(b: u64) -> FpCategory { - const EXP_MASK: u64 = 0x7ff0000000000000; - const MAN_MASK: u64 = 0x000fffffffffffff; - - match (b & MAN_MASK, b & EXP_MASK) { - (0, EXP_MASK) => FpCategory::Infinite, - (_, EXP_MASK) => FpCategory::Nan, - (0, 0) => FpCategory::Zero, - (_, 0) => FpCategory::Subnormal, - _ => FpCategory::Normal, - } - } - - /// Returns `true` if `self` has a positive sign, including `+0.0`, NaNs with - /// positive sign bit and positive infinity. Note that IEEE 754 doesn't assign any - /// meaning to the sign bit in case of a NaN, and as Rust doesn't guarantee that - /// the bit pattern of NaNs are conserved over arithmetic operations, the result of - /// `is_sign_positive` on a NaN might produce an unexpected result in some cases. - /// See [explanation of NaN as a special value](f32) for more info. - /// - /// ``` - /// let f = 7.0_f64; - /// let g = -7.0_f64; - /// - /// assert!(f.is_sign_positive()); - /// assert!(!g.is_sign_positive()); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] - #[inline] - pub const fn is_sign_positive(self) -> bool { - !self.is_sign_negative() - } - - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[deprecated(since = "1.0.0", note = "renamed to is_sign_positive")] - #[inline] - #[doc(hidden)] - pub fn is_positive(self) -> bool { - self.is_sign_positive() - } - - /// Returns `true` if `self` has a negative sign, including `-0.0`, NaNs with - /// negative sign bit and negative infinity. Note that IEEE 754 doesn't assign any - /// meaning to the sign bit in case of a NaN, and as Rust doesn't guarantee that - /// the bit pattern of NaNs are conserved over arithmetic operations, the result of - /// `is_sign_negative` on a NaN might produce an unexpected result in some cases. - /// See [explanation of NaN as a special value](f32) for more info. - /// - /// ``` - /// let f = 7.0_f64; - /// let g = -7.0_f64; - /// - /// assert!(!f.is_sign_negative()); - /// assert!(g.is_sign_negative()); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_float_classify", issue = "72505")] - #[inline] - pub const fn is_sign_negative(self) -> bool { - // IEEE754 says: isSignMinus(x) is true if and only if x has negative sign. isSignMinus - // applies to zeros and NaNs as well. - // SAFETY: This is just transmuting to get the sign bit, it's fine. - unsafe { mem::transmute::(self) & 0x8000_0000_0000_0000 != 0 } - } - - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[deprecated(since = "1.0.0", note = "renamed to is_sign_negative")] - #[inline] - #[doc(hidden)] - pub fn is_negative(self) -> bool { - self.is_sign_negative() - } - - /// Returns the least number greater than `self`. - /// - /// Let `TINY` be the smallest representable positive `f64`. Then, - /// - if `self.is_nan()`, this returns `self`; - /// - if `self` is [`NEG_INFINITY`], this returns [`MIN`]; - /// - if `self` is `-TINY`, this returns -0.0; - /// - if `self` is -0.0 or +0.0, this returns `TINY`; - /// - if `self` is [`MAX`] or [`INFINITY`], this returns [`INFINITY`]; - /// - otherwise the unique least value greater than `self` is returned. - /// - /// The identity `x.next_up() == -(-x).next_down()` holds for all non-NaN `x`. When `x` - /// is finite `x == x.next_up().next_down()` also holds. - /// - /// ```rust - /// #![feature(float_next_up_down)] - /// // f64::EPSILON is the difference between 1.0 and the next number up. - /// assert_eq!(1.0f64.next_up(), 1.0 + f64::EPSILON); - /// // But not for most numbers. - /// assert!(0.1f64.next_up() < 0.1 + f64::EPSILON); - /// assert_eq!(9007199254740992f64.next_up(), 9007199254740994.0); - /// ``` - /// - /// [`NEG_INFINITY`]: Self::NEG_INFINITY - /// [`INFINITY`]: Self::INFINITY - /// [`MIN`]: Self::MIN - /// [`MAX`]: Self::MAX - #[unstable(feature = "float_next_up_down", issue = "91399")] - #[rustc_const_unstable(feature = "float_next_up_down", issue = "91399")] - pub const fn next_up(self) -> Self { - // We must use strictly integer arithmetic to prevent denormals from - // flushing to zero after an arithmetic operation on some platforms. - const TINY_BITS: u64 = 0x1; // Smallest positive f64. - const CLEAR_SIGN_MASK: u64 = 0x7fff_ffff_ffff_ffff; - - let bits = self.to_bits(); - if self.is_nan() || bits == Self::INFINITY.to_bits() { - return self; - } - - let abs = bits & CLEAR_SIGN_MASK; - let next_bits = if abs == 0 { - TINY_BITS - } else if bits == abs { - bits + 1 - } else { - bits - 1 - }; - Self::from_bits(next_bits) - } - - /// Returns the greatest number less than `self`. - /// - /// Let `TINY` be the smallest representable positive `f64`. Then, - /// - if `self.is_nan()`, this returns `self`; - /// - if `self` is [`INFINITY`], this returns [`MAX`]; - /// - if `self` is `TINY`, this returns 0.0; - /// - if `self` is -0.0 or +0.0, this returns `-TINY`; - /// - if `self` is [`MIN`] or [`NEG_INFINITY`], this returns [`NEG_INFINITY`]; - /// - otherwise the unique greatest value less than `self` is returned. - /// - /// The identity `x.next_down() == -(-x).next_up()` holds for all non-NaN `x`. When `x` - /// is finite `x == x.next_down().next_up()` also holds. - /// - /// ```rust - /// #![feature(float_next_up_down)] - /// let x = 1.0f64; - /// // Clamp value into range [0, 1). - /// let clamped = x.clamp(0.0, 1.0f64.next_down()); - /// assert!(clamped < 1.0); - /// assert_eq!(clamped.next_up(), 1.0); - /// ``` - /// - /// [`NEG_INFINITY`]: Self::NEG_INFINITY - /// [`INFINITY`]: Self::INFINITY - /// [`MIN`]: Self::MIN - /// [`MAX`]: Self::MAX - #[unstable(feature = "float_next_up_down", issue = "91399")] - #[rustc_const_unstable(feature = "float_next_up_down", issue = "91399")] - pub const fn next_down(self) -> Self { - // We must use strictly integer arithmetic to prevent denormals from - // flushing to zero after an arithmetic operation on some platforms. - const NEG_TINY_BITS: u64 = 0x8000_0000_0000_0001; // Smallest (in magnitude) negative f64. - const CLEAR_SIGN_MASK: u64 = 0x7fff_ffff_ffff_ffff; - - let bits = self.to_bits(); - if self.is_nan() || bits == Self::NEG_INFINITY.to_bits() { - return self; - } - - let abs = bits & CLEAR_SIGN_MASK; - let next_bits = if abs == 0 { - NEG_TINY_BITS - } else if bits == abs { - bits - 1 - } else { - bits + 1 - }; - Self::from_bits(next_bits) - } - - /// Takes the reciprocal (inverse) of a number, `1/x`. - /// - /// ``` - /// let x = 2.0_f64; - /// let abs_difference = (x.recip() - (1.0 / x)).abs(); - /// - /// assert!(abs_difference < 1e-10); - /// ``` - #[must_use = "this returns the result of the operation, without modifying the original"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn recip(self) -> f64 { - 1.0 / self - } - - /// Converts radians to degrees. - /// - /// ``` - /// let angle = std::f64::consts::PI; - /// - /// let abs_difference = (angle.to_degrees() - 180.0).abs(); - /// - /// assert!(abs_difference < 1e-10); - /// ``` - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn to_degrees(self) -> f64 { - // The division here is correctly rounded with respect to the true - // value of 180/π. (This differs from f32, where a constant must be - // used to ensure a correctly rounded result.) - self * (180.0f64 / consts::PI) - } - - /// Converts degrees to radians. - /// - /// ``` - /// let angle = 180.0_f64; - /// - /// let abs_difference = (angle.to_radians() - std::f64::consts::PI).abs(); - /// - /// assert!(abs_difference < 1e-10); - /// ``` - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn to_radians(self) -> f64 { - let value: f64 = consts::PI; - self * (value / 180.0) - } - - /// Returns the maximum of the two numbers, ignoring NaN. - /// - /// If one of the arguments is NaN, then the other argument is returned. - /// This follows the IEEE 754-2008 semantics for maxNum, except for handling of signaling NaNs; - /// this function handles all NaNs the same way and avoids maxNum's problems with associativity. - /// This also matches the behavior of libm’s fmax. - /// - /// ``` - /// let x = 1.0_f64; - /// let y = 2.0_f64; - /// - /// assert_eq!(x.max(y), y); - /// ``` - #[must_use = "this returns the result of the comparison, without modifying either input"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn max(self, other: f64) -> f64 { - intrinsics::maxnumf64(self, other) - } - - /// Returns the minimum of the two numbers, ignoring NaN. - /// - /// If one of the arguments is NaN, then the other argument is returned. - /// This follows the IEEE 754-2008 semantics for minNum, except for handling of signaling NaNs; - /// this function handles all NaNs the same way and avoids minNum's problems with associativity. - /// This also matches the behavior of libm’s fmin. - /// - /// ``` - /// let x = 1.0_f64; - /// let y = 2.0_f64; - /// - /// assert_eq!(x.min(y), x); - /// ``` - #[must_use = "this returns the result of the comparison, without modifying either input"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn min(self, other: f64) -> f64 { - intrinsics::minnumf64(self, other) - } - - /// Returns the maximum of the two numbers, propagating NaN. - /// - /// This returns NaN when *either* argument is NaN, as opposed to - /// [`f64::max`] which only returns NaN when *both* arguments are NaN. - /// - /// ``` - /// #![feature(float_minimum_maximum)] - /// let x = 1.0_f64; - /// let y = 2.0_f64; - /// - /// assert_eq!(x.maximum(y), y); - /// assert!(x.maximum(f64::NAN).is_nan()); - /// ``` - /// - /// If one of the arguments is NaN, then NaN is returned. Otherwise this returns the greater - /// of the two numbers. For this operation, -0.0 is considered to be less than +0.0. - /// Note that this follows the semantics specified in IEEE 754-2019. - /// - /// Also note that "propagation" of NaNs here doesn't necessarily mean that the bitpattern of a NaN - /// operand is conserved; see [explanation of NaN as a special value](f32) for more info. - #[must_use = "this returns the result of the comparison, without modifying either input"] - #[unstable(feature = "float_minimum_maximum", issue = "91079")] - #[inline] - pub fn maximum(self, other: f64) -> f64 { - if self > other { - self - } else if other > self { - other - } else if self == other { - if self.is_sign_positive() && other.is_sign_negative() { self } else { other } - } else { - self + other - } - } - - /// Returns the minimum of the two numbers, propagating NaN. - /// - /// This returns NaN when *either* argument is NaN, as opposed to - /// [`f64::min`] which only returns NaN when *both* arguments are NaN. - /// - /// ``` - /// #![feature(float_minimum_maximum)] - /// let x = 1.0_f64; - /// let y = 2.0_f64; - /// - /// assert_eq!(x.minimum(y), x); - /// assert!(x.minimum(f64::NAN).is_nan()); - /// ``` - /// - /// If one of the arguments is NaN, then NaN is returned. Otherwise this returns the lesser - /// of the two numbers. For this operation, -0.0 is considered to be less than +0.0. - /// Note that this follows the semantics specified in IEEE 754-2019. - /// - /// Also note that "propagation" of NaNs here doesn't necessarily mean that the bitpattern of a NaN - /// operand is conserved; see [explanation of NaN as a special value](f32) for more info. - #[must_use = "this returns the result of the comparison, without modifying either input"] - #[unstable(feature = "float_minimum_maximum", issue = "91079")] - #[inline] - pub fn minimum(self, other: f64) -> f64 { - if self < other { - self - } else if other < self { - other - } else if self == other { - if self.is_sign_negative() && other.is_sign_positive() { self } else { other } - } else { - // At least one input is NaN. Use `+` to perform NaN propagation and quieting. - self + other - } - } - - /// Calculates the middle point of `self` and `rhs`. - /// - /// This returns NaN when *either* argument is NaN or if a combination of - /// +inf and -inf is provided as arguments. - /// - /// # Examples - /// - /// ``` - /// #![feature(num_midpoint)] - /// assert_eq!(1f64.midpoint(4.0), 2.5); - /// assert_eq!((-5.5f64).midpoint(8.0), 1.25); - /// ``` - #[unstable(feature = "num_midpoint", issue = "110840")] - pub fn midpoint(self, other: f64) -> f64 { - const LO: f64 = f64::MIN_POSITIVE * 2.; - const HI: f64 = f64::MAX / 2.; - - let (a, b) = (self, other); - let abs_a = a.abs_private(); - let abs_b = b.abs_private(); - - if abs_a <= HI && abs_b <= HI { - // Overflow is impossible - (a + b) / 2. - } else if abs_a < LO { - // Not safe to halve a - a + (b / 2.) - } else if abs_b < LO { - // Not safe to halve b - (a / 2.) + b - } else { - // Not safe to halve a and b - (a / 2.) + (b / 2.) - } - } - - /// Rounds toward zero and converts to any primitive integer type, - /// assuming that the value is finite and fits in that type. - /// - /// ``` - /// let value = 4.6_f64; - /// let rounded = unsafe { value.to_int_unchecked::() }; - /// assert_eq!(rounded, 4); - /// - /// let value = -128.9_f64; - /// let rounded = unsafe { value.to_int_unchecked::() }; - /// assert_eq!(rounded, i8::MIN); - /// ``` - /// - /// # Safety - /// - /// The value must: - /// - /// * Not be `NaN` - /// * Not be infinite - /// * Be representable in the return type `Int`, after truncating off its fractional part - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[stable(feature = "float_approx_unchecked_to", since = "1.44.0")] - #[inline] - pub unsafe fn to_int_unchecked(self) -> Int - where - Self: FloatToInt, - { - // SAFETY: the caller must uphold the safety contract for - // `FloatToInt::to_int_unchecked`. - unsafe { FloatToInt::::to_int_unchecked(self) } - } - - /// Raw transmutation to `u64`. - /// - /// This is currently identical to `transmute::(self)` on all platforms. - /// - /// See [`from_bits`](Self::from_bits) for some discussion of the - /// portability of this operation (there are almost no issues). - /// - /// Note that this function is distinct from `as` casting, which attempts to - /// preserve the *numeric* value, and not the bitwise value. - /// - /// # Examples - /// - /// ``` - /// assert!((1f64).to_bits() != 1f64 as u64); // to_bits() is not casting! - /// assert_eq!((12.5f64).to_bits(), 0x4029000000000000); - /// ``` - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[stable(feature = "float_bits_conv", since = "1.20.0")] - #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] - #[inline] - pub const fn to_bits(self) -> u64 { - // SAFETY: `u64` is a plain old datatype so we can always transmute to it. - // ...sorta. - // - // See the SAFETY comment in f64::from_bits for more. - #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] - const fn ct_f64_to_u64(ct: f64) -> u64 { - match ct.classify() { - FpCategory::Nan => { - panic!("const-eval error: cannot use f64::to_bits on a NaN") - } - FpCategory::Subnormal => { - panic!("const-eval error: cannot use f64::to_bits on a subnormal number") - } - FpCategory::Infinite | FpCategory::Normal | FpCategory::Zero => { - // SAFETY: We have a normal floating point number. Now we transmute, i.e. do a bitcopy. - unsafe { mem::transmute::(ct) } - } - } - } - - #[inline(always)] // See https://github.com/rust-lang/compiler-builtins/issues/491 - fn rt_f64_to_u64(rt: f64) -> u64 { - // SAFETY: `u64` is a plain old datatype so we can always... uh... - // ...look, just pretend you forgot what you just read. - // Stability concerns. - unsafe { mem::transmute::(rt) } - } - intrinsics::const_eval_select((self,), ct_f64_to_u64, rt_f64_to_u64) - } - - /// Raw transmutation from `u64`. - /// - /// This is currently identical to `transmute::(v)` on all platforms. - /// It turns out this is incredibly portable, for two reasons: - /// - /// * Floats and Ints have the same endianness on all supported platforms. - /// * IEEE 754 very precisely specifies the bit layout of floats. - /// - /// However there is one caveat: prior to the 2008 version of IEEE 754, how - /// to interpret the NaN signaling bit wasn't actually specified. Most platforms - /// (notably x86 and ARM) picked the interpretation that was ultimately - /// standardized in 2008, but some didn't (notably MIPS). As a result, all - /// signaling NaNs on MIPS are quiet NaNs on x86, and vice-versa. - /// - /// Rather than trying to preserve signaling-ness cross-platform, this - /// implementation favors preserving the exact bits. This means that - /// any payloads encoded in NaNs will be preserved even if the result of - /// this method is sent over the network from an x86 machine to a MIPS one. - /// - /// If the results of this method are only manipulated by the same - /// architecture that produced them, then there is no portability concern. - /// - /// If the input isn't NaN, then there is no portability concern. - /// - /// If you don't care about signaling-ness (very likely), then there is no - /// portability concern. - /// - /// Note that this function is distinct from `as` casting, which attempts to - /// preserve the *numeric* value, and not the bitwise value. - /// - /// # Examples - /// - /// ``` - /// let v = f64::from_bits(0x4029000000000000); - /// assert_eq!(v, 12.5); - /// ``` - #[stable(feature = "float_bits_conv", since = "1.20.0")] - #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] - #[must_use] - #[inline] - pub const fn from_bits(v: u64) -> Self { - // It turns out the safety issues with sNaN were overblown! Hooray! - // SAFETY: `u64` is a plain old datatype so we can always transmute from it - // ...sorta. - // - // It turns out that at runtime, it is possible for a floating point number - // to be subject to floating point modes that alter nonzero subnormal numbers - // to zero on reads and writes, aka "denormals are zero" and "flush to zero". - // This is not a problem usually, but at least one tier2 platform for Rust - // actually exhibits an FTZ behavior by default: thumbv7neon - // aka "the Neon FPU in AArch32 state" - // - // Even with this, not all instructions exhibit the FTZ behaviors on thumbv7neon, - // so this should load the same bits if LLVM emits the "correct" instructions, - // but LLVM sometimes makes interesting choices about float optimization, - // and other FPUs may do similar. Thus, it is wise to indulge luxuriously in caution. - // - // In addition, on x86 targets with SSE or SSE2 disabled and the x87 FPU enabled, - // i.e. not soft-float, the way Rust does parameter passing can actually alter - // a number that is "not infinity" to have the same exponent as infinity, - // in a slightly unpredictable manner. - // - // And, of course evaluating to a NaN value is fairly nondeterministic. - // More precisely: when NaN should be returned is knowable, but which NaN? - // So far that's defined by a combination of LLVM and the CPU, not Rust. - // This function, however, allows observing the bitstring of a NaN, - // thus introspection on CTFE. - // - // In order to preserve, at least for the moment, const-to-runtime equivalence, - // reject any of these possible situations from happening. - #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] - const fn ct_u64_to_f64(ct: u64) -> f64 { - match f64::classify_bits(ct) { - FpCategory::Subnormal => { - panic!("const-eval error: cannot use f64::from_bits on a subnormal number") - } - FpCategory::Nan => { - panic!("const-eval error: cannot use f64::from_bits on NaN") - } - FpCategory::Infinite | FpCategory::Normal | FpCategory::Zero => { - // SAFETY: It's not a frumious number - unsafe { mem::transmute::(ct) } - } - } - } - - #[inline(always)] // See https://github.com/rust-lang/compiler-builtins/issues/491 - fn rt_u64_to_f64(rt: u64) -> f64 { - // SAFETY: `u64` is a plain old datatype so we can always... uh... - // ...look, just pretend you forgot what you just read. - // Stability concerns. - unsafe { mem::transmute::(rt) } - } - intrinsics::const_eval_select((v,), ct_u64_to_f64, rt_u64_to_f64) - } - - /// Return the memory representation of this floating point number as a byte array in - /// big-endian (network) byte order. - /// - /// See [`from_bits`](Self::from_bits) for some discussion of the - /// portability of this operation (there are almost no issues). - /// - /// # Examples - /// - /// ``` - /// let bytes = 12.5f64.to_be_bytes(); - /// assert_eq!(bytes, [0x40, 0x29, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]); - /// ``` - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[stable(feature = "float_to_from_bytes", since = "1.40.0")] - #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] - #[inline] - pub const fn to_be_bytes(self) -> [u8; 8] { - self.to_bits().to_be_bytes() - } - - /// Return the memory representation of this floating point number as a byte array in - /// little-endian byte order. - /// - /// See [`from_bits`](Self::from_bits) for some discussion of the - /// portability of this operation (there are almost no issues). - /// - /// # Examples - /// - /// ``` - /// let bytes = 12.5f64.to_le_bytes(); - /// assert_eq!(bytes, [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x29, 0x40]); - /// ``` - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[stable(feature = "float_to_from_bytes", since = "1.40.0")] - #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] - #[inline] - pub const fn to_le_bytes(self) -> [u8; 8] { - self.to_bits().to_le_bytes() - } - - /// Return the memory representation of this floating point number as a byte array in - /// native byte order. - /// - /// As the target platform's native endianness is used, portable code - /// should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate, instead. - /// - /// [`to_be_bytes`]: f64::to_be_bytes - /// [`to_le_bytes`]: f64::to_le_bytes - /// - /// See [`from_bits`](Self::from_bits) for some discussion of the - /// portability of this operation (there are almost no issues). - /// - /// # Examples - /// - /// ``` - /// let bytes = 12.5f64.to_ne_bytes(); - /// assert_eq!( - /// bytes, - /// if cfg!(target_endian = "big") { - /// [0x40, 0x29, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00] - /// } else { - /// [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x29, 0x40] - /// } - /// ); - /// ``` - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[stable(feature = "float_to_from_bytes", since = "1.40.0")] - #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] - #[inline] - pub const fn to_ne_bytes(self) -> [u8; 8] { - self.to_bits().to_ne_bytes() - } - - /// Create a floating point value from its representation as a byte array in big endian. - /// - /// See [`from_bits`](Self::from_bits) for some discussion of the - /// portability of this operation (there are almost no issues). - /// - /// # Examples - /// - /// ``` - /// let value = f64::from_be_bytes([0x40, 0x29, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]); - /// assert_eq!(value, 12.5); - /// ``` - #[stable(feature = "float_to_from_bytes", since = "1.40.0")] - #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] - #[must_use] - #[inline] - pub const fn from_be_bytes(bytes: [u8; 8]) -> Self { - Self::from_bits(u64::from_be_bytes(bytes)) - } - - /// Create a floating point value from its representation as a byte array in little endian. - /// - /// See [`from_bits`](Self::from_bits) for some discussion of the - /// portability of this operation (there are almost no issues). - /// - /// # Examples - /// - /// ``` - /// let value = f64::from_le_bytes([0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x29, 0x40]); - /// assert_eq!(value, 12.5); - /// ``` - #[stable(feature = "float_to_from_bytes", since = "1.40.0")] - #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] - #[must_use] - #[inline] - pub const fn from_le_bytes(bytes: [u8; 8]) -> Self { - Self::from_bits(u64::from_le_bytes(bytes)) - } - - /// Create a floating point value from its representation as a byte array in native endian. - /// - /// As the target platform's native endianness is used, portable code - /// likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as - /// appropriate instead. - /// - /// [`from_be_bytes`]: f64::from_be_bytes - /// [`from_le_bytes`]: f64::from_le_bytes - /// - /// See [`from_bits`](Self::from_bits) for some discussion of the - /// portability of this operation (there are almost no issues). - /// - /// # Examples - /// - /// ``` - /// let value = f64::from_ne_bytes(if cfg!(target_endian = "big") { - /// [0x40, 0x29, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00] - /// } else { - /// [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x29, 0x40] - /// }); - /// assert_eq!(value, 12.5); - /// ``` - #[stable(feature = "float_to_from_bytes", since = "1.40.0")] - #[rustc_const_unstable(feature = "const_float_bits_conv", issue = "72447")] - #[must_use] - #[inline] - pub const fn from_ne_bytes(bytes: [u8; 8]) -> Self { - Self::from_bits(u64::from_ne_bytes(bytes)) - } - - /// Return the ordering between `self` and `other`. - /// - /// Unlike the standard partial comparison between floating point numbers, - /// this comparison always produces an ordering in accordance to - /// the `totalOrder` predicate as defined in the IEEE 754 (2008 revision) - /// floating point standard. The values are ordered in the following sequence: - /// - /// - negative quiet NaN - /// - negative signaling NaN - /// - negative infinity - /// - negative numbers - /// - negative subnormal numbers - /// - negative zero - /// - positive zero - /// - positive subnormal numbers - /// - positive numbers - /// - positive infinity - /// - positive signaling NaN - /// - positive quiet NaN. - /// - /// The ordering established by this function does not always agree with the - /// [`PartialOrd`] and [`PartialEq`] implementations of `f64`. For example, - /// they consider negative and positive zero equal, while `total_cmp` - /// doesn't. - /// - /// The interpretation of the signaling NaN bit follows the definition in - /// the IEEE 754 standard, which may not match the interpretation by some of - /// the older, non-conformant (e.g. MIPS) hardware implementations. - /// - /// # Example - /// - /// ``` - /// struct GoodBoy { - /// name: String, - /// weight: f64, - /// } - /// - /// let mut bois = vec![ - /// GoodBoy { name: "Pucci".to_owned(), weight: 0.1 }, - /// GoodBoy { name: "Woofer".to_owned(), weight: 99.0 }, - /// GoodBoy { name: "Yapper".to_owned(), weight: 10.0 }, - /// GoodBoy { name: "Chonk".to_owned(), weight: f64::INFINITY }, - /// GoodBoy { name: "Abs. Unit".to_owned(), weight: f64::NAN }, - /// GoodBoy { name: "Floaty".to_owned(), weight: -5.0 }, - /// ]; - /// - /// bois.sort_by(|a, b| a.weight.total_cmp(&b.weight)); - /// - /// // `f64::NAN` could be positive or negative, which will affect the sort order. - /// if f64::NAN.is_sign_negative() { - /// assert!(bois.into_iter().map(|b| b.weight) - /// .zip([f64::NAN, -5.0, 0.1, 10.0, 99.0, f64::INFINITY].iter()) - /// .all(|(a, b)| a.to_bits() == b.to_bits())) - /// } else { - /// assert!(bois.into_iter().map(|b| b.weight) - /// .zip([-5.0, 0.1, 10.0, 99.0, f64::INFINITY, f64::NAN].iter()) - /// .all(|(a, b)| a.to_bits() == b.to_bits())) - /// } - /// ``` - #[stable(feature = "total_cmp", since = "1.62.0")] - #[must_use] - #[inline] - pub fn total_cmp(&self, other: &Self) -> crate::cmp::Ordering { - let mut left = self.to_bits() as i64; - let mut right = other.to_bits() as i64; - - // In case of negatives, flip all the bits except the sign - // to achieve a similar layout as two's complement integers - // - // Why does this work? IEEE 754 floats consist of three fields: - // Sign bit, exponent and mantissa. The set of exponent and mantissa - // fields as a whole have the property that their bitwise order is - // equal to the numeric magnitude where the magnitude is defined. - // The magnitude is not normally defined on NaN values, but - // IEEE 754 totalOrder defines the NaN values also to follow the - // bitwise order. This leads to order explained in the doc comment. - // However, the representation of magnitude is the same for negative - // and positive numbers – only the sign bit is different. - // To easily compare the floats as signed integers, we need to - // flip the exponent and mantissa bits in case of negative numbers. - // We effectively convert the numbers to "two's complement" form. - // - // To do the flipping, we construct a mask and XOR against it. - // We branchlessly calculate an "all-ones except for the sign bit" - // mask from negative-signed values: right shifting sign-extends - // the integer, so we "fill" the mask with sign bits, and then - // convert to unsigned to push one more zero bit. - // On positive values, the mask is all zeros, so it's a no-op. - left ^= (((left >> 63) as u64) >> 1) as i64; - right ^= (((right >> 63) as u64) >> 1) as i64; - - left.cmp(&right) - } - - /// Restrict a value to a certain interval unless it is NaN. - /// - /// Returns `max` if `self` is greater than `max`, and `min` if `self` is - /// less than `min`. Otherwise this returns `self`. - /// - /// Note that this function returns NaN if the initial value was NaN as - /// well. - /// - /// # Panics - /// - /// Panics if `min > max`, `min` is NaN, or `max` is NaN. - /// - /// # Examples - /// - /// ``` - /// assert!((-3.0f64).clamp(-2.0, 1.0) == -2.0); - /// assert!((0.0f64).clamp(-2.0, 1.0) == 0.0); - /// assert!((2.0f64).clamp(-2.0, 1.0) == 1.0); - /// assert!((f64::NAN).clamp(-2.0, 1.0).is_nan()); - /// ``` - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "clamp", since = "1.50.0")] - #[inline] - pub fn clamp(mut self, min: f64, max: f64) -> f64 { - assert!(min <= max, "min > max, or either was NaN. min = {min:?}, max = {max:?}"); - if self < min { - self = min; - } - if self > max { - self = max; - } - self - } -} diff --git a/library/core/src/num/flt2dec/decoder.rs b/library/core/src/num/flt2dec/decoder.rs deleted file mode 100644 index 5763860540aa4..0000000000000 --- a/library/core/src/num/flt2dec/decoder.rs +++ /dev/null @@ -1,100 +0,0 @@ -//! Decodes a floating-point value into individual parts and error ranges. - -use crate::num::dec2flt::float::RawFloat; -use crate::num::FpCategory; - -/// Decoded unsigned finite value, such that: -/// -/// - The original value equals to `mant * 2^exp`. -/// -/// - Any number from `(mant - minus) * 2^exp` to `(mant + plus) * 2^exp` will -/// round to the original value. The range is inclusive only when -/// `inclusive` is `true`. -#[derive(Copy, Clone, Debug, PartialEq, Eq)] -pub struct Decoded { - /// The scaled mantissa. - pub mant: u64, - /// The lower error range. - pub minus: u64, - /// The upper error range. - pub plus: u64, - /// The shared exponent in base 2. - pub exp: i16, - /// True when the error range is inclusive. - /// - /// In IEEE 754, this is true when the original mantissa was even. - pub inclusive: bool, -} - -/// Decoded unsigned value. -#[derive(Copy, Clone, Debug, PartialEq, Eq)] -pub enum FullDecoded { - /// Not-a-number. - Nan, - /// Infinities, either positive or negative. - Infinite, - /// Zero, either positive or negative. - Zero, - /// Finite numbers with further decoded fields. - Finite(Decoded), -} - -/// A floating point type which can be `decode`d. -pub trait DecodableFloat: RawFloat + Copy { - /// The minimum positive normalized value. - fn min_pos_norm_value() -> Self; -} - -impl DecodableFloat for f32 { - fn min_pos_norm_value() -> Self { - f32::MIN_POSITIVE - } -} - -impl DecodableFloat for f64 { - fn min_pos_norm_value() -> Self { - f64::MIN_POSITIVE - } -} - -/// Returns a sign (true when negative) and `FullDecoded` value -/// from given floating point number. -pub fn decode(v: T) -> (/*negative?*/ bool, FullDecoded) { - let (mant, exp, sign) = v.integer_decode(); - let even = (mant & 1) == 0; - let decoded = match v.classify() { - FpCategory::Nan => FullDecoded::Nan, - FpCategory::Infinite => FullDecoded::Infinite, - FpCategory::Zero => FullDecoded::Zero, - FpCategory::Subnormal => { - // neighbors: (mant - 2, exp) -- (mant, exp) -- (mant + 2, exp) - // Float::integer_decode always preserves the exponent, - // so the mantissa is scaled for subnormals. - FullDecoded::Finite(Decoded { mant, minus: 1, plus: 1, exp, inclusive: even }) - } - FpCategory::Normal => { - let minnorm = ::min_pos_norm_value().integer_decode(); - if mant == minnorm.0 { - // neighbors: (maxmant, exp - 1) -- (minnormmant, exp) -- (minnormmant + 1, exp) - // where maxmant = minnormmant * 2 - 1 - FullDecoded::Finite(Decoded { - mant: mant << 2, - minus: 1, - plus: 2, - exp: exp - 2, - inclusive: even, - }) - } else { - // neighbors: (mant - 1, exp) -- (mant, exp) -- (mant + 1, exp) - FullDecoded::Finite(Decoded { - mant: mant << 1, - minus: 1, - plus: 1, - exp: exp - 1, - inclusive: even, - }) - } - } - }; - (sign < 0, decoded) -} diff --git a/library/core/src/num/flt2dec/estimator.rs b/library/core/src/num/flt2dec/estimator.rs deleted file mode 100644 index 50e2f70528383..0000000000000 --- a/library/core/src/num/flt2dec/estimator.rs +++ /dev/null @@ -1,14 +0,0 @@ -//! The exponent estimator. - -/// Finds `k_0` such that `10^(k_0-1) < mant * 2^exp <= 10^(k_0+1)`. -/// -/// This is used to approximate `k = ceil(log_10 (mant * 2^exp))`; -/// the true `k` is either `k_0` or `k_0+1`. -#[doc(hidden)] -pub fn estimate_scaling_factor(mant: u64, exp: i16) -> i16 { - // 2^(nbits-1) < mant <= 2^nbits if mant > 0 - let nbits = 64 - (mant - 1).leading_zeros() as i64; - // 1292913986 = floor(2^32 * log_10 2) - // therefore this always underestimates (or is exact), but not much. - (((nbits + exp as i64) * 1292913986) >> 32) as i16 -} diff --git a/library/core/src/num/flt2dec/mod.rs b/library/core/src/num/flt2dec/mod.rs deleted file mode 100644 index 1ff2e8c8228c9..0000000000000 --- a/library/core/src/num/flt2dec/mod.rs +++ /dev/null @@ -1,673 +0,0 @@ -/*! - -Floating-point number to decimal conversion routines. - -# Problem statement - -We are given the floating-point number `v = f * 2^e` with an integer `f`, -and its bounds `minus` and `plus` such that any number between `v - minus` and -`v + plus` will be rounded to `v`. For the simplicity we assume that -this range is exclusive. Then we would like to get the unique decimal -representation `V = 0.d[0..n-1] * 10^k` such that: - -- `d[0]` is non-zero. - -- It's correctly rounded when parsed back: `v - minus < V < v + plus`. - Furthermore it is shortest such one, i.e., there is no representation - with less than `n` digits that is correctly rounded. - -- It's closest to the original value: `abs(V - v) <= 10^(k-n) / 2`. Note that - there might be two representations satisfying this uniqueness requirement, - in which case some tie-breaking mechanism is used. - -We will call this mode of operation as to the *shortest* mode. This mode is used -when there is no additional constraint, and can be thought as a "natural" mode -as it matches the ordinary intuition (it at least prints `0.1f32` as "0.1"). - -We have two more modes of operation closely related to each other. In these modes -we are given either the number of significant digits `n` or the last-digit -limitation `limit` (which determines the actual `n`), and we would like to get -the representation `V = 0.d[0..n-1] * 10^k` such that: - -- `d[0]` is non-zero, unless `n` was zero in which case only `k` is returned. - -- It's closest to the original value: `abs(V - v) <= 10^(k-n) / 2`. Again, - there might be some tie-breaking mechanism. - -When `limit` is given but not `n`, we set `n` such that `k - n = limit` -so that the last digit `d[n-1]` is scaled by `10^(k-n) = 10^limit`. -If such `n` is negative, we clip it to zero so that we will only get `k`. -We are also limited by the supplied buffer. This limitation is used to print -the number up to given number of fractional digits without knowing -the correct `k` beforehand. - -We will call the mode of operation requiring `n` as to the *exact* mode, -and one requiring `limit` as to the *fixed* mode. The exact mode is a subset of -the fixed mode: the sufficiently large last-digit limitation will eventually fill -the supplied buffer and let the algorithm to return. - -# Implementation overview - -It is easy to get the floating point printing correct but slow (Russ Cox has -[demonstrated](https://research.swtch.com/ftoa) how it's easy), or incorrect but -fast (naïve division and modulo). But it is surprisingly hard to print -floating point numbers correctly *and* efficiently. - -There are two classes of algorithms widely known to be correct. - -- The "Dragon" family of algorithm is first described by Guy L. Steele Jr. and - Jon L. White. They rely on the fixed-size big integer for their correctness. - A slight improvement was found later, which is posthumously described by - Robert G. Burger and R. Kent Dybvig. David Gay's `dtoa.c` routine is - a popular implementation of this strategy. - -- The "Grisu" family of algorithm is first described by Florian Loitsch. - They use very cheap integer-only procedure to determine the close-to-correct - representation which is at least guaranteed to be shortest. The variant, - Grisu3, actively detects if the resulting representation is incorrect. - -We implement both algorithms with necessary tweaks to suit our requirements. -In particular, published literatures are short of the actual implementation -difficulties like how to avoid arithmetic overflows. Each implementation, -available in `strategy::dragon` and `strategy::grisu` respectively, -extensively describes all necessary justifications and many proofs for them. -(It is still difficult to follow though. You have been warned.) - -Both implementations expose two public functions: - -- `format_shortest(decoded, buf)`, which always needs at least - `MAX_SIG_DIGITS` digits of buffer. Implements the shortest mode. - -- `format_exact(decoded, buf, limit)`, which accepts as small as - one digit of buffer. Implements exact and fixed modes. - -They try to fill the `u8` buffer with digits and returns the number of digits -written and the exponent `k`. They are total for all finite `f32` and `f64` -inputs (Grisu internally falls back to Dragon if necessary). - -The rendered digits are formatted into the actual string form with -four functions: - -- `to_shortest_str` prints the shortest representation, which can be padded by - zeroes to make *at least* given number of fractional digits. - -- `to_shortest_exp_str` prints the shortest representation, which can be - padded by zeroes when its exponent is in the specified ranges, - or can be printed in the exponential form such as `1.23e45`. - -- `to_exact_exp_str` prints the exact representation with given number of - digits in the exponential form. - -- `to_exact_fixed_str` prints the fixed representation with *exactly* - given number of fractional digits. - -They all return a slice of preallocated `Part` array, which corresponds to -the individual part of strings: a fixed string, a part of rendered digits, -a number of zeroes or a small (`u16`) number. The caller is expected to -provide a large enough buffer and `Part` array, and to assemble the final -string from resulting `Part`s itself. - -All algorithms and formatting functions are accompanied by extensive tests -in `coretests::num::flt2dec` module. It also shows how to use individual -functions. - -*/ - -// while this is extensively documented, this is in principle private which is -// only made public for testing. do not expose us. -#![doc(hidden)] -#![unstable( - feature = "flt2dec", - reason = "internal routines only exposed for testing", - issue = "none" -)] - -pub use self::decoder::{decode, DecodableFloat, Decoded, FullDecoded}; - -use super::fmt::{Formatted, Part}; -use crate::mem::MaybeUninit; - -pub mod decoder; -pub mod estimator; - -/// Digit-generation algorithms. -pub mod strategy { - pub mod dragon; - pub mod grisu; -} - -/// The minimum size of buffer necessary for the shortest mode. -/// -/// It is a bit non-trivial to derive, but this is one plus the maximal number of -/// significant decimal digits from formatting algorithms with the shortest result. -/// The exact formula is `ceil(# bits in mantissa * log_10 2 + 1)`. -pub const MAX_SIG_DIGITS: usize = 17; - -/// When `d` contains decimal digits, increase the last digit and propagate carry. -/// Returns a next digit when it causes the length to change. -#[doc(hidden)] -pub fn round_up(d: &mut [u8]) -> Option { - match d.iter().rposition(|&c| c != b'9') { - Some(i) => { - // d[i+1..n] is all nines - d[i] += 1; - for j in i + 1..d.len() { - d[j] = b'0'; - } - None - } - None if d.len() > 0 => { - // 999..999 rounds to 1000..000 with an increased exponent - d[0] = b'1'; - for j in 1..d.len() { - d[j] = b'0'; - } - Some(b'0') - } - None => { - // an empty buffer rounds up (a bit strange but reasonable) - Some(b'1') - } - } -} - -/// Formats given decimal digits `0.<...buf...> * 10^exp` into the decimal form -/// with at least given number of fractional digits. The result is stored to -/// the supplied parts array and a slice of written parts is returned. -/// -/// `frac_digits` can be less than the number of actual fractional digits in `buf`; -/// it will be ignored and full digits will be printed. It is only used to print -/// additional zeroes after rendered digits. Thus `frac_digits` of 0 means that -/// it will only print given digits and nothing else. -fn digits_to_dec_str<'a>( - buf: &'a [u8], - exp: i16, - frac_digits: usize, - parts: &'a mut [MaybeUninit>], -) -> &'a [Part<'a>] { - assert!(!buf.is_empty()); - assert!(buf[0] > b'0'); - assert!(parts.len() >= 4); - - // if there is the restriction on the last digit position, `buf` is assumed to be - // left-padded with the virtual zeroes. the number of virtual zeroes, `nzeroes`, - // equals to `max(0, exp + frac_digits - buf.len())`, so that the position of - // the last digit `exp - buf.len() - nzeroes` is no more than `-frac_digits`: - // - // |<-virtual->| - // |<---- buf ---->| zeroes | exp - // 0. 1 2 3 4 5 6 7 8 9 _ _ _ _ _ _ x 10 - // | | | - // 10^exp 10^(exp-buf.len()) 10^(exp-buf.len()-nzeroes) - // - // `nzeroes` is individually calculated for each case in order to avoid overflow. - - if exp <= 0 { - // the decimal point is before rendered digits: [0.][000...000][1234][____] - let minus_exp = -(exp as i32) as usize; - parts[0] = MaybeUninit::new(Part::Copy(b"0.")); - parts[1] = MaybeUninit::new(Part::Zero(minus_exp)); - parts[2] = MaybeUninit::new(Part::Copy(buf)); - if frac_digits > buf.len() && frac_digits - buf.len() > minus_exp { - parts[3] = MaybeUninit::new(Part::Zero((frac_digits - buf.len()) - minus_exp)); - // SAFETY: we just initialized the elements `..4`. - unsafe { MaybeUninit::slice_assume_init_ref(&parts[..4]) } - } else { - // SAFETY: we just initialized the elements `..3`. - unsafe { MaybeUninit::slice_assume_init_ref(&parts[..3]) } - } - } else { - let exp = exp as usize; - if exp < buf.len() { - // the decimal point is inside rendered digits: [12][.][34][____] - parts[0] = MaybeUninit::new(Part::Copy(&buf[..exp])); - parts[1] = MaybeUninit::new(Part::Copy(b".")); - parts[2] = MaybeUninit::new(Part::Copy(&buf[exp..])); - if frac_digits > buf.len() - exp { - parts[3] = MaybeUninit::new(Part::Zero(frac_digits - (buf.len() - exp))); - // SAFETY: we just initialized the elements `..4`. - unsafe { MaybeUninit::slice_assume_init_ref(&parts[..4]) } - } else { - // SAFETY: we just initialized the elements `..3`. - unsafe { MaybeUninit::slice_assume_init_ref(&parts[..3]) } - } - } else { - // the decimal point is after rendered digits: [1234][____0000] or [1234][__][.][__]. - parts[0] = MaybeUninit::new(Part::Copy(buf)); - parts[1] = MaybeUninit::new(Part::Zero(exp - buf.len())); - if frac_digits > 0 { - parts[2] = MaybeUninit::new(Part::Copy(b".")); - parts[3] = MaybeUninit::new(Part::Zero(frac_digits)); - // SAFETY: we just initialized the elements `..4`. - unsafe { MaybeUninit::slice_assume_init_ref(&parts[..4]) } - } else { - // SAFETY: we just initialized the elements `..2`. - unsafe { MaybeUninit::slice_assume_init_ref(&parts[..2]) } - } - } - } -} - -/// Formats the given decimal digits `0.<...buf...> * 10^exp` into the exponential -/// form with at least the given number of significant digits. When `upper` is `true`, -/// the exponent will be prefixed by `E`; otherwise that's `e`. The result is -/// stored to the supplied parts array and a slice of written parts is returned. -/// -/// `min_digits` can be less than the number of actual significant digits in `buf`; -/// it will be ignored and full digits will be printed. It is only used to print -/// additional zeroes after rendered digits. Thus, `min_digits == 0` means that -/// it will only print the given digits and nothing else. -fn digits_to_exp_str<'a>( - buf: &'a [u8], - exp: i16, - min_ndigits: usize, - upper: bool, - parts: &'a mut [MaybeUninit>], -) -> &'a [Part<'a>] { - assert!(!buf.is_empty()); - assert!(buf[0] > b'0'); - assert!(parts.len() >= 6); - - let mut n = 0; - - parts[n] = MaybeUninit::new(Part::Copy(&buf[..1])); - n += 1; - - if buf.len() > 1 || min_ndigits > 1 { - parts[n] = MaybeUninit::new(Part::Copy(b".")); - parts[n + 1] = MaybeUninit::new(Part::Copy(&buf[1..])); - n += 2; - if min_ndigits > buf.len() { - parts[n] = MaybeUninit::new(Part::Zero(min_ndigits - buf.len())); - n += 1; - } - } - - // 0.1234 x 10^exp = 1.234 x 10^(exp-1) - let exp = exp as i32 - 1; // avoid underflow when exp is i16::MIN - if exp < 0 { - parts[n] = MaybeUninit::new(Part::Copy(if upper { b"E-" } else { b"e-" })); - parts[n + 1] = MaybeUninit::new(Part::Num(-exp as u16)); - } else { - parts[n] = MaybeUninit::new(Part::Copy(if upper { b"E" } else { b"e" })); - parts[n + 1] = MaybeUninit::new(Part::Num(exp as u16)); - } - // SAFETY: we just initialized the elements `..n + 2`. - unsafe { MaybeUninit::slice_assume_init_ref(&parts[..n + 2]) } -} - -/// Sign formatting options. -#[derive(Copy, Clone, PartialEq, Eq, Debug)] -pub enum Sign { - /// Prints `-` for any negative value. - Minus, // -inf -1 -0 0 1 inf nan - /// Prints `-` for any negative value, or `+` otherwise. - MinusPlus, // -inf -1 -0 +0 +1 +inf nan -} - -/// Returns the static byte string corresponding to the sign to be formatted. -/// It can be either `""`, `"+"` or `"-"`. -fn determine_sign(sign: Sign, decoded: &FullDecoded, negative: bool) -> &'static str { - match (*decoded, sign) { - (FullDecoded::Nan, _) => "", - (_, Sign::Minus) => { - if negative { - "-" - } else { - "" - } - } - (_, Sign::MinusPlus) => { - if negative { - "-" - } else { - "+" - } - } - } -} - -/// Formats the given floating point number into the decimal form with at least -/// given number of fractional digits. The result is stored to the supplied parts -/// array while utilizing given byte buffer as a scratch. `upper` is currently -/// unused but left for the future decision to change the case of non-finite values, -/// i.e., `inf` and `nan`. The first part to be rendered is always a `Part::Sign` -/// (which can be an empty string if no sign is rendered). -/// -/// `format_shortest` should be the underlying digit-generation function. -/// It should return the part of the buffer that it initialized. -/// You probably would want `strategy::grisu::format_shortest` for this. -/// -/// `frac_digits` can be less than the number of actual fractional digits in `v`; -/// it will be ignored and full digits will be printed. It is only used to print -/// additional zeroes after rendered digits. Thus `frac_digits` of 0 means that -/// it will only print given digits and nothing else. -/// -/// The byte buffer should be at least `MAX_SIG_DIGITS` bytes long. -/// There should be at least 4 parts available, due to the worst case like -/// `[+][0.][0000][2][0000]` with `frac_digits = 10`. -pub fn to_shortest_str<'a, T, F>( - mut format_shortest: F, - v: T, - sign: Sign, - frac_digits: usize, - buf: &'a mut [MaybeUninit], - parts: &'a mut [MaybeUninit>], -) -> Formatted<'a> -where - T: DecodableFloat, - F: FnMut(&Decoded, &'a mut [MaybeUninit]) -> (&'a [u8], i16), -{ - assert!(parts.len() >= 4); - assert!(buf.len() >= MAX_SIG_DIGITS); - - let (negative, full_decoded) = decode(v); - let sign = determine_sign(sign, &full_decoded, negative); - match full_decoded { - FullDecoded::Nan => { - parts[0] = MaybeUninit::new(Part::Copy(b"NaN")); - // SAFETY: we just initialized the elements `..1`. - Formatted { sign, parts: unsafe { MaybeUninit::slice_assume_init_ref(&parts[..1]) } } - } - FullDecoded::Infinite => { - parts[0] = MaybeUninit::new(Part::Copy(b"inf")); - // SAFETY: we just initialized the elements `..1`. - Formatted { sign, parts: unsafe { MaybeUninit::slice_assume_init_ref(&parts[..1]) } } - } - FullDecoded::Zero => { - if frac_digits > 0 { - // [0.][0000] - parts[0] = MaybeUninit::new(Part::Copy(b"0.")); - parts[1] = MaybeUninit::new(Part::Zero(frac_digits)); - Formatted { - sign, - // SAFETY: we just initialized the elements `..2`. - parts: unsafe { MaybeUninit::slice_assume_init_ref(&parts[..2]) }, - } - } else { - parts[0] = MaybeUninit::new(Part::Copy(b"0")); - Formatted { - sign, - // SAFETY: we just initialized the elements `..1`. - parts: unsafe { MaybeUninit::slice_assume_init_ref(&parts[..1]) }, - } - } - } - FullDecoded::Finite(ref decoded) => { - let (buf, exp) = format_shortest(decoded, buf); - Formatted { sign, parts: digits_to_dec_str(buf, exp, frac_digits, parts) } - } - } -} - -/// Formats the given floating point number into the decimal form or -/// the exponential form, depending on the resulting exponent. The result is -/// stored to the supplied parts array while utilizing given byte buffer -/// as a scratch. `upper` is used to determine the case of non-finite values -/// (`inf` and `nan`) or the case of the exponent prefix (`e` or `E`). -/// The first part to be rendered is always a `Part::Sign` (which can be -/// an empty string if no sign is rendered). -/// -/// `format_shortest` should be the underlying digit-generation function. -/// It should return the part of the buffer that it initialized. -/// You probably would want `strategy::grisu::format_shortest` for this. -/// -/// The `dec_bounds` is a tuple `(lo, hi)` such that the number is formatted -/// as decimal only when `10^lo <= V < 10^hi`. Note that this is the *apparent* `V` -/// instead of the actual `v`! Thus any printed exponent in the exponential form -/// cannot be in this range, avoiding any confusion. -/// -/// The byte buffer should be at least `MAX_SIG_DIGITS` bytes long. -/// There should be at least 6 parts available, due to the worst case like -/// `[+][1][.][2345][e][-][6]`. -pub fn to_shortest_exp_str<'a, T, F>( - mut format_shortest: F, - v: T, - sign: Sign, - dec_bounds: (i16, i16), - upper: bool, - buf: &'a mut [MaybeUninit], - parts: &'a mut [MaybeUninit>], -) -> Formatted<'a> -where - T: DecodableFloat, - F: FnMut(&Decoded, &'a mut [MaybeUninit]) -> (&'a [u8], i16), -{ - assert!(parts.len() >= 6); - assert!(buf.len() >= MAX_SIG_DIGITS); - assert!(dec_bounds.0 <= dec_bounds.1); - - let (negative, full_decoded) = decode(v); - let sign = determine_sign(sign, &full_decoded, negative); - match full_decoded { - FullDecoded::Nan => { - parts[0] = MaybeUninit::new(Part::Copy(b"NaN")); - // SAFETY: we just initialized the elements `..1`. - Formatted { sign, parts: unsafe { MaybeUninit::slice_assume_init_ref(&parts[..1]) } } - } - FullDecoded::Infinite => { - parts[0] = MaybeUninit::new(Part::Copy(b"inf")); - // SAFETY: we just initialized the elements `..1`. - Formatted { sign, parts: unsafe { MaybeUninit::slice_assume_init_ref(&parts[..1]) } } - } - FullDecoded::Zero => { - parts[0] = if dec_bounds.0 <= 0 && 0 < dec_bounds.1 { - MaybeUninit::new(Part::Copy(b"0")) - } else { - MaybeUninit::new(Part::Copy(if upper { b"0E0" } else { b"0e0" })) - }; - // SAFETY: we just initialized the elements `..1`. - Formatted { sign, parts: unsafe { MaybeUninit::slice_assume_init_ref(&parts[..1]) } } - } - FullDecoded::Finite(ref decoded) => { - let (buf, exp) = format_shortest(decoded, buf); - let vis_exp = exp as i32 - 1; - let parts = if dec_bounds.0 as i32 <= vis_exp && vis_exp < dec_bounds.1 as i32 { - digits_to_dec_str(buf, exp, 0, parts) - } else { - digits_to_exp_str(buf, exp, 0, upper, parts) - }; - Formatted { sign, parts } - } - } -} - -/// Returns a rather crude approximation (upper bound) for the maximum buffer size -/// calculated from the given decoded exponent. -/// -/// The exact limit is: -/// -/// - when `exp < 0`, the maximum length is `ceil(log_10 (5^-exp * (2^64 - 1)))`. -/// - when `exp >= 0`, the maximum length is `ceil(log_10 (2^exp * (2^64 - 1)))`. -/// -/// `ceil(log_10 (x^exp * (2^64 - 1)))` is less than `ceil(log_10 (2^64 - 1)) + -/// ceil(exp * log_10 x)`, which is in turn less than `20 + (1 + exp * log_10 x)`. -/// We use the facts that `log_10 2 < 5/16` and `log_10 5 < 12/16`, which is -/// enough for our purposes. -/// -/// Why do we need this? `format_exact` functions will fill the entire buffer -/// unless limited by the last digit restriction, but it is possible that -/// the number of digits requested is ridiculously large (say, 30,000 digits). -/// The vast majority of buffer will be filled with zeroes, so we don't want to -/// allocate all the buffer beforehand. Consequently, for any given arguments, -/// 826 bytes of buffer should be sufficient for `f64`. Compare this with -/// the actual number for the worst case: 770 bytes (when `exp = -1074`). -fn estimate_max_buf_len(exp: i16) -> usize { - 21 + ((if exp < 0 { -12 } else { 5 } * exp as i32) as usize >> 4) -} - -/// Formats given floating point number into the exponential form with -/// exactly given number of significant digits. The result is stored to -/// the supplied parts array while utilizing given byte buffer as a scratch. -/// `upper` is used to determine the case of the exponent prefix (`e` or `E`). -/// The first part to be rendered is always a `Part::Sign` (which can be -/// an empty string if no sign is rendered). -/// -/// `format_exact` should be the underlying digit-generation function. -/// It should return the part of the buffer that it initialized. -/// You probably would want `strategy::grisu::format_exact` for this. -/// -/// The byte buffer should be at least `ndigits` bytes long unless `ndigits` is -/// so large that only the fixed number of digits will be ever written. -/// (The tipping point for `f64` is about 800, so 1000 bytes should be enough.) -/// There should be at least 6 parts available, due to the worst case like -/// `[+][1][.][2345][e][-][6]`. -pub fn to_exact_exp_str<'a, T, F>( - mut format_exact: F, - v: T, - sign: Sign, - ndigits: usize, - upper: bool, - buf: &'a mut [MaybeUninit], - parts: &'a mut [MaybeUninit>], -) -> Formatted<'a> -where - T: DecodableFloat, - F: FnMut(&Decoded, &'a mut [MaybeUninit], i16) -> (&'a [u8], i16), -{ - assert!(parts.len() >= 6); - assert!(ndigits > 0); - - let (negative, full_decoded) = decode(v); - let sign = determine_sign(sign, &full_decoded, negative); - match full_decoded { - FullDecoded::Nan => { - parts[0] = MaybeUninit::new(Part::Copy(b"NaN")); - // SAFETY: we just initialized the elements `..1`. - Formatted { sign, parts: unsafe { MaybeUninit::slice_assume_init_ref(&parts[..1]) } } - } - FullDecoded::Infinite => { - parts[0] = MaybeUninit::new(Part::Copy(b"inf")); - // SAFETY: we just initialized the elements `..1`. - Formatted { sign, parts: unsafe { MaybeUninit::slice_assume_init_ref(&parts[..1]) } } - } - FullDecoded::Zero => { - if ndigits > 1 { - // [0.][0000][e0] - parts[0] = MaybeUninit::new(Part::Copy(b"0.")); - parts[1] = MaybeUninit::new(Part::Zero(ndigits - 1)); - parts[2] = MaybeUninit::new(Part::Copy(if upper { b"E0" } else { b"e0" })); - Formatted { - sign, - // SAFETY: we just initialized the elements `..3`. - parts: unsafe { MaybeUninit::slice_assume_init_ref(&parts[..3]) }, - } - } else { - parts[0] = MaybeUninit::new(Part::Copy(if upper { b"0E0" } else { b"0e0" })); - Formatted { - sign, - // SAFETY: we just initialized the elements `..1`. - parts: unsafe { MaybeUninit::slice_assume_init_ref(&parts[..1]) }, - } - } - } - FullDecoded::Finite(ref decoded) => { - let maxlen = estimate_max_buf_len(decoded.exp); - assert!(buf.len() >= ndigits || buf.len() >= maxlen); - - let trunc = if ndigits < maxlen { ndigits } else { maxlen }; - let (buf, exp) = format_exact(decoded, &mut buf[..trunc], i16::MIN); - Formatted { sign, parts: digits_to_exp_str(buf, exp, ndigits, upper, parts) } - } - } -} - -/// Formats given floating point number into the decimal form with exactly -/// given number of fractional digits. The result is stored to the supplied parts -/// array while utilizing given byte buffer as a scratch. `upper` is currently -/// unused but left for the future decision to change the case of non-finite values, -/// i.e., `inf` and `nan`. The first part to be rendered is always a `Part::Sign` -/// (which can be an empty string if no sign is rendered). -/// -/// `format_exact` should be the underlying digit-generation function. -/// It should return the part of the buffer that it initialized. -/// You probably would want `strategy::grisu::format_exact` for this. -/// -/// The byte buffer should be enough for the output unless `frac_digits` is -/// so large that only the fixed number of digits will be ever written. -/// (The tipping point for `f64` is about 800, and 1000 bytes should be enough.) -/// There should be at least 4 parts available, due to the worst case like -/// `[+][0.][0000][2][0000]` with `frac_digits = 10`. -pub fn to_exact_fixed_str<'a, T, F>( - mut format_exact: F, - v: T, - sign: Sign, - frac_digits: usize, - buf: &'a mut [MaybeUninit], - parts: &'a mut [MaybeUninit>], -) -> Formatted<'a> -where - T: DecodableFloat, - F: FnMut(&Decoded, &'a mut [MaybeUninit], i16) -> (&'a [u8], i16), -{ - assert!(parts.len() >= 4); - - let (negative, full_decoded) = decode(v); - let sign = determine_sign(sign, &full_decoded, negative); - match full_decoded { - FullDecoded::Nan => { - parts[0] = MaybeUninit::new(Part::Copy(b"NaN")); - // SAFETY: we just initialized the elements `..1`. - Formatted { sign, parts: unsafe { MaybeUninit::slice_assume_init_ref(&parts[..1]) } } - } - FullDecoded::Infinite => { - parts[0] = MaybeUninit::new(Part::Copy(b"inf")); - // SAFETY: we just initialized the elements `..1`. - Formatted { sign, parts: unsafe { MaybeUninit::slice_assume_init_ref(&parts[..1]) } } - } - FullDecoded::Zero => { - if frac_digits > 0 { - // [0.][0000] - parts[0] = MaybeUninit::new(Part::Copy(b"0.")); - parts[1] = MaybeUninit::new(Part::Zero(frac_digits)); - Formatted { - sign, - // SAFETY: we just initialized the elements `..2`. - parts: unsafe { MaybeUninit::slice_assume_init_ref(&parts[..2]) }, - } - } else { - parts[0] = MaybeUninit::new(Part::Copy(b"0")); - Formatted { - sign, - // SAFETY: we just initialized the elements `..1`. - parts: unsafe { MaybeUninit::slice_assume_init_ref(&parts[..1]) }, - } - } - } - FullDecoded::Finite(ref decoded) => { - let maxlen = estimate_max_buf_len(decoded.exp); - assert!(buf.len() >= maxlen); - - // it *is* possible that `frac_digits` is ridiculously large. - // `format_exact` will end rendering digits much earlier in this case, - // because we are strictly limited by `maxlen`. - let limit = if frac_digits < 0x8000 { -(frac_digits as i16) } else { i16::MIN }; - let (buf, exp) = format_exact(decoded, &mut buf[..maxlen], limit); - if exp <= limit { - // the restriction couldn't been met, so this should render like zero no matter - // `exp` was. this does not include the case that the restriction has been met - // only after the final rounding-up; it's a regular case with `exp = limit + 1`. - debug_assert_eq!(buf.len(), 0); - if frac_digits > 0 { - // [0.][0000] - parts[0] = MaybeUninit::new(Part::Copy(b"0.")); - parts[1] = MaybeUninit::new(Part::Zero(frac_digits)); - Formatted { - sign, - // SAFETY: we just initialized the elements `..2`. - parts: unsafe { MaybeUninit::slice_assume_init_ref(&parts[..2]) }, - } - } else { - parts[0] = MaybeUninit::new(Part::Copy(b"0")); - Formatted { - sign, - // SAFETY: we just initialized the elements `..1`. - parts: unsafe { MaybeUninit::slice_assume_init_ref(&parts[..1]) }, - } - } - } else { - Formatted { sign, parts: digits_to_dec_str(buf, exp, frac_digits, parts) } - } - } - } -} diff --git a/library/core/src/num/flt2dec/strategy/dragon.rs b/library/core/src/num/flt2dec/strategy/dragon.rs deleted file mode 100644 index 71b14d0ae3f4c..0000000000000 --- a/library/core/src/num/flt2dec/strategy/dragon.rs +++ /dev/null @@ -1,388 +0,0 @@ -//! Almost direct (but slightly optimized) Rust translation of Figure 3 of "Printing -//! Floating-Point Numbers Quickly and Accurately"[^1]. -//! -//! [^1]: Burger, R. G. and Dybvig, R. K. 1996. Printing floating-point numbers -//! quickly and accurately. SIGPLAN Not. 31, 5 (May. 1996), 108-116. - -use crate::cmp::Ordering; -use crate::mem::MaybeUninit; - -use crate::num::bignum::Big32x40 as Big; -use crate::num::bignum::Digit32 as Digit; -use crate::num::flt2dec::estimator::estimate_scaling_factor; -use crate::num::flt2dec::{round_up, Decoded, MAX_SIG_DIGITS}; - -static POW10: [Digit; 10] = - [1, 10, 100, 1000, 10000, 100000, 1000000, 10000000, 100000000, 1000000000]; -static TWOPOW10: [Digit; 10] = - [2, 20, 200, 2000, 20000, 200000, 2000000, 20000000, 200000000, 2000000000]; - -// precalculated arrays of `Digit`s for 10^(2^n) -static POW10TO16: [Digit; 2] = [0x6fc10000, 0x2386f2]; -static POW10TO32: [Digit; 4] = [0, 0x85acef81, 0x2d6d415b, 0x4ee]; -static POW10TO64: [Digit; 7] = [0, 0, 0xbf6a1f01, 0x6e38ed64, 0xdaa797ed, 0xe93ff9f4, 0x184f03]; -static POW10TO128: [Digit; 14] = [ - 0, 0, 0, 0, 0x2e953e01, 0x3df9909, 0xf1538fd, 0x2374e42f, 0xd3cff5ec, 0xc404dc08, 0xbccdb0da, - 0xa6337f19, 0xe91f2603, 0x24e, -]; -static POW10TO256: [Digit; 27] = [ - 0, 0, 0, 0, 0, 0, 0, 0, 0x982e7c01, 0xbed3875b, 0xd8d99f72, 0x12152f87, 0x6bde50c6, 0xcf4a6e70, - 0xd595d80f, 0x26b2716e, 0xadc666b0, 0x1d153624, 0x3c42d35a, 0x63ff540e, 0xcc5573c0, 0x65f9ef17, - 0x55bc28f2, 0x80dcc7f7, 0xf46eeddc, 0x5fdcefce, 0x553f7, -]; - -#[doc(hidden)] -pub fn mul_pow10(x: &mut Big, n: usize) -> &mut Big { - debug_assert!(n < 512); - if n & 7 != 0 { - x.mul_small(POW10[n & 7]); - } - if n & 8 != 0 { - x.mul_small(POW10[8]); - } - if n & 16 != 0 { - x.mul_digits(&POW10TO16); - } - if n & 32 != 0 { - x.mul_digits(&POW10TO32); - } - if n & 64 != 0 { - x.mul_digits(&POW10TO64); - } - if n & 128 != 0 { - x.mul_digits(&POW10TO128); - } - if n & 256 != 0 { - x.mul_digits(&POW10TO256); - } - x -} - -fn div_2pow10(x: &mut Big, mut n: usize) -> &mut Big { - let largest = POW10.len() - 1; - while n > largest { - x.div_rem_small(POW10[largest]); - n -= largest; - } - x.div_rem_small(TWOPOW10[n]); - x -} - -// only usable when `x < 16 * scale`; `scaleN` should be `scale.mul_small(N)` -fn div_rem_upto_16<'a>( - x: &'a mut Big, - scale: &Big, - scale2: &Big, - scale4: &Big, - scale8: &Big, -) -> (u8, &'a mut Big) { - let mut d = 0; - if *x >= *scale8 { - x.sub(scale8); - d += 8; - } - if *x >= *scale4 { - x.sub(scale4); - d += 4; - } - if *x >= *scale2 { - x.sub(scale2); - d += 2; - } - if *x >= *scale { - x.sub(scale); - d += 1; - } - debug_assert!(*x < *scale); - (d, x) -} - -/// The shortest mode implementation for Dragon. -pub fn format_shortest<'a>( - d: &Decoded, - buf: &'a mut [MaybeUninit], -) -> (/*digits*/ &'a [u8], /*exp*/ i16) { - // the number `v` to format is known to be: - // - equal to `mant * 2^exp`; - // - preceded by `(mant - 2 * minus) * 2^exp` in the original type; and - // - followed by `(mant + 2 * plus) * 2^exp` in the original type. - // - // obviously, `minus` and `plus` cannot be zero. (for infinities, we use out-of-range values.) - // also we assume that at least one digit is generated, i.e., `mant` cannot be zero too. - // - // this also means that any number between `low = (mant - minus) * 2^exp` and - // `high = (mant + plus) * 2^exp` will map to this exact floating point number, - // with bounds included when the original mantissa was even (i.e., `!mant_was_odd`). - - assert!(d.mant > 0); - assert!(d.minus > 0); - assert!(d.plus > 0); - assert!(d.mant.checked_add(d.plus).is_some()); - assert!(d.mant.checked_sub(d.minus).is_some()); - assert!(buf.len() >= MAX_SIG_DIGITS); - - // `a.cmp(&b) < rounding` is `if d.inclusive {a <= b} else {a < b}` - let rounding = if d.inclusive { Ordering::Greater } else { Ordering::Equal }; - - // estimate `k_0` from original inputs satisfying `10^(k_0-1) < high <= 10^(k_0+1)`. - // the tight bound `k` satisfying `10^(k-1) < high <= 10^k` is calculated later. - let mut k = estimate_scaling_factor(d.mant + d.plus, d.exp); - - // convert `{mant, plus, minus} * 2^exp` into the fractional form so that: - // - `v = mant / scale` - // - `low = (mant - minus) / scale` - // - `high = (mant + plus) / scale` - let mut mant = Big::from_u64(d.mant); - let mut minus = Big::from_u64(d.minus); - let mut plus = Big::from_u64(d.plus); - let mut scale = Big::from_small(1); - if d.exp < 0 { - scale.mul_pow2(-d.exp as usize); - } else { - mant.mul_pow2(d.exp as usize); - minus.mul_pow2(d.exp as usize); - plus.mul_pow2(d.exp as usize); - } - - // divide `mant` by `10^k`. now `scale / 10 < mant + plus <= scale * 10`. - if k >= 0 { - mul_pow10(&mut scale, k as usize); - } else { - mul_pow10(&mut mant, -k as usize); - mul_pow10(&mut minus, -k as usize); - mul_pow10(&mut plus, -k as usize); - } - - // fixup when `mant + plus > scale` (or `>=`). - // we are not actually modifying `scale`, since we can skip the initial multiplication instead. - // now `scale < mant + plus <= scale * 10` and we are ready to generate digits. - // - // note that `d[0]` *can* be zero, when `scale - plus < mant < scale`. - // in this case rounding-up condition (`up` below) will be triggered immediately. - if scale.cmp(mant.clone().add(&plus)) < rounding { - // equivalent to scaling `scale` by 10 - k += 1; - } else { - mant.mul_small(10); - minus.mul_small(10); - plus.mul_small(10); - } - - // cache `(2, 4, 8) * scale` for digit generation. - let mut scale2 = scale.clone(); - scale2.mul_pow2(1); - let mut scale4 = scale.clone(); - scale4.mul_pow2(2); - let mut scale8 = scale.clone(); - scale8.mul_pow2(3); - - let mut down; - let mut up; - let mut i = 0; - loop { - // invariants, where `d[0..n-1]` are digits generated so far: - // - `v = mant / scale * 10^(k-n-1) + d[0..n-1] * 10^(k-n)` - // - `v - low = minus / scale * 10^(k-n-1)` - // - `high - v = plus / scale * 10^(k-n-1)` - // - `(mant + plus) / scale <= 10` (thus `mant / scale < 10`) - // where `d[i..j]` is a shorthand for `d[i] * 10^(j-i) + ... + d[j-1] * 10 + d[j]`. - - // generate one digit: `d[n] = floor(mant / scale) < 10`. - let (d, _) = div_rem_upto_16(&mut mant, &scale, &scale2, &scale4, &scale8); - debug_assert!(d < 10); - buf[i] = MaybeUninit::new(b'0' + d); - i += 1; - - // this is a simplified description of the modified Dragon algorithm. - // many intermediate derivations and completeness arguments are omitted for convenience. - // - // start with modified invariants, as we've updated `n`: - // - `v = mant / scale * 10^(k-n) + d[0..n-1] * 10^(k-n)` - // - `v - low = minus / scale * 10^(k-n)` - // - `high - v = plus / scale * 10^(k-n)` - // - // assume that `d[0..n-1]` is the shortest representation between `low` and `high`, - // i.e., `d[0..n-1]` satisfies both of the following but `d[0..n-2]` doesn't: - // - `low < d[0..n-1] * 10^(k-n) < high` (bijectivity: digits round to `v`); and - // - `abs(v / 10^(k-n) - d[0..n-1]) <= 1/2` (the last digit is correct). - // - // the second condition simplifies to `2 * mant <= scale`. - // solving invariants in terms of `mant`, `low` and `high` yields - // a simpler version of the first condition: `-plus < mant < minus`. - // since `-plus < 0 <= mant`, we have the correct shortest representation - // when `mant < minus` and `2 * mant <= scale`. - // (the former becomes `mant <= minus` when the original mantissa is even.) - // - // when the second doesn't hold (`2 * mant > scale`), we need to increase the last digit. - // this is enough for restoring that condition: we already know that - // the digit generation guarantees `0 <= v / 10^(k-n) - d[0..n-1] < 1`. - // in this case, the first condition becomes `-plus < mant - scale < minus`. - // since `mant < scale` after the generation, we have `scale < mant + plus`. - // (again, this becomes `scale <= mant + plus` when the original mantissa is even.) - // - // in short: - // - stop and round `down` (keep digits as is) when `mant < minus` (or `<=`). - // - stop and round `up` (increase the last digit) when `scale < mant + plus` (or `<=`). - // - keep generating otherwise. - down = mant.cmp(&minus) < rounding; - up = scale.cmp(mant.clone().add(&plus)) < rounding; - if down || up { - break; - } // we have the shortest representation, proceed to the rounding - - // restore the invariants. - // this makes the algorithm always terminating: `minus` and `plus` always increases, - // but `mant` is clipped modulo `scale` and `scale` is fixed. - mant.mul_small(10); - minus.mul_small(10); - plus.mul_small(10); - } - - // rounding up happens when - // i) only the rounding-up condition was triggered, or - // ii) both conditions were triggered and tie breaking prefers rounding up. - if up && (!down || *mant.mul_pow2(1) >= scale) { - // if rounding up changes the length, the exponent should also change. - // it seems that this condition is very hard to satisfy (possibly impossible), - // but we are just being safe and consistent here. - // SAFETY: we initialized that memory above. - if let Some(c) = round_up(unsafe { MaybeUninit::slice_assume_init_mut(&mut buf[..i]) }) { - buf[i] = MaybeUninit::new(c); - i += 1; - k += 1; - } - } - - // SAFETY: we initialized that memory above. - (unsafe { MaybeUninit::slice_assume_init_ref(&buf[..i]) }, k) -} - -/// The exact and fixed mode implementation for Dragon. -pub fn format_exact<'a>( - d: &Decoded, - buf: &'a mut [MaybeUninit], - limit: i16, -) -> (/*digits*/ &'a [u8], /*exp*/ i16) { - assert!(d.mant > 0); - assert!(d.minus > 0); - assert!(d.plus > 0); - assert!(d.mant.checked_add(d.plus).is_some()); - assert!(d.mant.checked_sub(d.minus).is_some()); - - // estimate `k_0` from original inputs satisfying `10^(k_0-1) < v <= 10^(k_0+1)`. - let mut k = estimate_scaling_factor(d.mant, d.exp); - - // `v = mant / scale`. - let mut mant = Big::from_u64(d.mant); - let mut scale = Big::from_small(1); - if d.exp < 0 { - scale.mul_pow2(-d.exp as usize); - } else { - mant.mul_pow2(d.exp as usize); - } - - // divide `mant` by `10^k`. now `scale / 10 < mant <= scale * 10`. - if k >= 0 { - mul_pow10(&mut scale, k as usize); - } else { - mul_pow10(&mut mant, -k as usize); - } - - // fixup when `mant + plus >= scale`, where `plus / scale = 10^-buf.len() / 2`. - // in order to keep the fixed-size bignum, we actually use `mant + floor(plus) >= scale`. - // we are not actually modifying `scale`, since we can skip the initial multiplication instead. - // again with the shortest algorithm, `d[0]` can be zero but will be eventually rounded up. - if *div_2pow10(&mut scale.clone(), buf.len()).add(&mant) >= scale { - // equivalent to scaling `scale` by 10 - k += 1; - } else { - mant.mul_small(10); - } - - // if we are working with the last-digit limitation, we need to shorten the buffer - // before the actual rendering in order to avoid double rounding. - // note that we have to enlarge the buffer again when rounding up happens! - let mut len = if k < limit { - // oops, we cannot even produce *one* digit. - // this is possible when, say, we've got something like 9.5 and it's being rounded to 10. - // we return an empty buffer, with an exception of the later rounding-up case - // which occurs when `k == limit` and has to produce exactly one digit. - 0 - } else if ((k as i32 - limit as i32) as usize) < buf.len() { - (k - limit) as usize - } else { - buf.len() - }; - - if len > 0 { - // cache `(2, 4, 8) * scale` for digit generation. - // (this can be expensive, so do not calculate them when the buffer is empty.) - let mut scale2 = scale.clone(); - scale2.mul_pow2(1); - let mut scale4 = scale.clone(); - scale4.mul_pow2(2); - let mut scale8 = scale.clone(); - scale8.mul_pow2(3); - - for i in 0..len { - if mant.is_zero() { - // following digits are all zeroes, we stop here - // do *not* try to perform rounding! rather, fill remaining digits. - for c in &mut buf[i..len] { - *c = MaybeUninit::new(b'0'); - } - // SAFETY: we initialized that memory above. - return (unsafe { MaybeUninit::slice_assume_init_ref(&buf[..len]) }, k); - } - - let mut d = 0; - if mant >= scale8 { - mant.sub(&scale8); - d += 8; - } - if mant >= scale4 { - mant.sub(&scale4); - d += 4; - } - if mant >= scale2 { - mant.sub(&scale2); - d += 2; - } - if mant >= scale { - mant.sub(&scale); - d += 1; - } - debug_assert!(mant < scale); - debug_assert!(d < 10); - buf[i] = MaybeUninit::new(b'0' + d); - mant.mul_small(10); - } - } - - // rounding up if we stop in the middle of digits - // if the following digits are exactly 5000..., check the prior digit and try to - // round to even (i.e., avoid rounding up when the prior digit is even). - let order = mant.cmp(scale.mul_small(5)); - if order == Ordering::Greater - || (order == Ordering::Equal - // SAFETY: `buf[len-1]` is initialized. - && len > 0 && unsafe { buf[len - 1].assume_init() } & 1 == 1) - { - // if rounding up changes the length, the exponent should also change. - // but we've been requested a fixed number of digits, so do not alter the buffer... - // SAFETY: we initialized that memory above. - if let Some(c) = round_up(unsafe { MaybeUninit::slice_assume_init_mut(&mut buf[..len]) }) { - // ...unless we've been requested the fixed precision instead. - // we also need to check that, if the original buffer was empty, - // the additional digit can only be added when `k == limit` (edge case). - k += 1; - if k > limit && len < buf.len() { - buf[len] = MaybeUninit::new(c); - len += 1; - } - } - } - - // SAFETY: we initialized that memory above. - (unsafe { MaybeUninit::slice_assume_init_ref(&buf[..len]) }, k) -} diff --git a/library/core/src/num/flt2dec/strategy/grisu.rs b/library/core/src/num/flt2dec/strategy/grisu.rs deleted file mode 100644 index b9f0d114c6a14..0000000000000 --- a/library/core/src/num/flt2dec/strategy/grisu.rs +++ /dev/null @@ -1,776 +0,0 @@ -//! Rust adaptation of the Grisu3 algorithm described in "Printing Floating-Point Numbers Quickly -//! and Accurately with Integers"[^1]. It uses about 1KB of precomputed table, and in turn, it's -//! very quick for most inputs. -//! -//! [^1]: Florian Loitsch. 2010. Printing floating-point numbers quickly and -//! accurately with integers. SIGPLAN Not. 45, 6 (June 2010), 233-243. - -use crate::mem::MaybeUninit; -use crate::num::diy_float::Fp; -use crate::num::flt2dec::{round_up, Decoded, MAX_SIG_DIGITS}; - -// see the comments in `format_shortest_opt` for the rationale. -#[doc(hidden)] -pub const ALPHA: i16 = -60; -#[doc(hidden)] -pub const GAMMA: i16 = -32; - -/* -# the following Python code generates this table: -for i in xrange(-308, 333, 8): - if i >= 0: f = 10**i; e = 0 - else: f = 2**(80-4*i) // 10**-i; e = 4 * i - 80 - l = f.bit_length() - f = ((f << 64 >> (l-1)) + 1) >> 1; e += l - 64 - print ' (%#018x, %5d, %4d),' % (f, e, i) -*/ - -#[doc(hidden)] -pub static CACHED_POW10: [(u64, i16, i16); 81] = [ - // (f, e, k) - (0xe61acf033d1a45df, -1087, -308), - (0xab70fe17c79ac6ca, -1060, -300), - (0xff77b1fcbebcdc4f, -1034, -292), - (0xbe5691ef416bd60c, -1007, -284), - (0x8dd01fad907ffc3c, -980, -276), - (0xd3515c2831559a83, -954, -268), - (0x9d71ac8fada6c9b5, -927, -260), - (0xea9c227723ee8bcb, -901, -252), - (0xaecc49914078536d, -874, -244), - (0x823c12795db6ce57, -847, -236), - (0xc21094364dfb5637, -821, -228), - (0x9096ea6f3848984f, -794, -220), - (0xd77485cb25823ac7, -768, -212), - (0xa086cfcd97bf97f4, -741, -204), - (0xef340a98172aace5, -715, -196), - (0xb23867fb2a35b28e, -688, -188), - (0x84c8d4dfd2c63f3b, -661, -180), - (0xc5dd44271ad3cdba, -635, -172), - (0x936b9fcebb25c996, -608, -164), - (0xdbac6c247d62a584, -582, -156), - (0xa3ab66580d5fdaf6, -555, -148), - (0xf3e2f893dec3f126, -529, -140), - (0xb5b5ada8aaff80b8, -502, -132), - (0x87625f056c7c4a8b, -475, -124), - (0xc9bcff6034c13053, -449, -116), - (0x964e858c91ba2655, -422, -108), - (0xdff9772470297ebd, -396, -100), - (0xa6dfbd9fb8e5b88f, -369, -92), - (0xf8a95fcf88747d94, -343, -84), - (0xb94470938fa89bcf, -316, -76), - (0x8a08f0f8bf0f156b, -289, -68), - (0xcdb02555653131b6, -263, -60), - (0x993fe2c6d07b7fac, -236, -52), - (0xe45c10c42a2b3b06, -210, -44), - (0xaa242499697392d3, -183, -36), - (0xfd87b5f28300ca0e, -157, -28), - (0xbce5086492111aeb, -130, -20), - (0x8cbccc096f5088cc, -103, -12), - (0xd1b71758e219652c, -77, -4), - (0x9c40000000000000, -50, 4), - (0xe8d4a51000000000, -24, 12), - (0xad78ebc5ac620000, 3, 20), - (0x813f3978f8940984, 30, 28), - (0xc097ce7bc90715b3, 56, 36), - (0x8f7e32ce7bea5c70, 83, 44), - (0xd5d238a4abe98068, 109, 52), - (0x9f4f2726179a2245, 136, 60), - (0xed63a231d4c4fb27, 162, 68), - (0xb0de65388cc8ada8, 189, 76), - (0x83c7088e1aab65db, 216, 84), - (0xc45d1df942711d9a, 242, 92), - (0x924d692ca61be758, 269, 100), - (0xda01ee641a708dea, 295, 108), - (0xa26da3999aef774a, 322, 116), - (0xf209787bb47d6b85, 348, 124), - (0xb454e4a179dd1877, 375, 132), - (0x865b86925b9bc5c2, 402, 140), - (0xc83553c5c8965d3d, 428, 148), - (0x952ab45cfa97a0b3, 455, 156), - (0xde469fbd99a05fe3, 481, 164), - (0xa59bc234db398c25, 508, 172), - (0xf6c69a72a3989f5c, 534, 180), - (0xb7dcbf5354e9bece, 561, 188), - (0x88fcf317f22241e2, 588, 196), - (0xcc20ce9bd35c78a5, 614, 204), - (0x98165af37b2153df, 641, 212), - (0xe2a0b5dc971f303a, 667, 220), - (0xa8d9d1535ce3b396, 694, 228), - (0xfb9b7cd9a4a7443c, 720, 236), - (0xbb764c4ca7a44410, 747, 244), - (0x8bab8eefb6409c1a, 774, 252), - (0xd01fef10a657842c, 800, 260), - (0x9b10a4e5e9913129, 827, 268), - (0xe7109bfba19c0c9d, 853, 276), - (0xac2820d9623bf429, 880, 284), - (0x80444b5e7aa7cf85, 907, 292), - (0xbf21e44003acdd2d, 933, 300), - (0x8e679c2f5e44ff8f, 960, 308), - (0xd433179d9c8cb841, 986, 316), - (0x9e19db92b4e31ba9, 1013, 324), - (0xeb96bf6ebadf77d9, 1039, 332), -]; - -#[doc(hidden)] -pub const CACHED_POW10_FIRST_E: i16 = -1087; -#[doc(hidden)] -pub const CACHED_POW10_LAST_E: i16 = 1039; - -#[doc(hidden)] -pub fn cached_power(alpha: i16, gamma: i16) -> (i16, Fp) { - let offset = CACHED_POW10_FIRST_E as i32; - let range = (CACHED_POW10.len() as i32) - 1; - let domain = (CACHED_POW10_LAST_E - CACHED_POW10_FIRST_E) as i32; - let idx = ((gamma as i32) - offset) * range / domain; - let (f, e, k) = CACHED_POW10[idx as usize]; - debug_assert!(alpha <= e && e <= gamma); - (k, Fp { f, e }) -} - -/// Given `x > 0`, returns `(k, 10^k)` such that `10^k <= x < 10^(k+1)`. -#[doc(hidden)] -pub fn max_pow10_no_more_than(x: u32) -> (u8, u32) { - debug_assert!(x > 0); - - const X9: u32 = 10_0000_0000; - const X8: u32 = 1_0000_0000; - const X7: u32 = 1000_0000; - const X6: u32 = 100_0000; - const X5: u32 = 10_0000; - const X4: u32 = 1_0000; - const X3: u32 = 1000; - const X2: u32 = 100; - const X1: u32 = 10; - - if x < X4 { - if x < X2 { - if x < X1 { (0, 1) } else { (1, X1) } - } else { - if x < X3 { (2, X2) } else { (3, X3) } - } - } else { - if x < X6 { - if x < X5 { (4, X4) } else { (5, X5) } - } else if x < X8 { - if x < X7 { (6, X6) } else { (7, X7) } - } else { - if x < X9 { (8, X8) } else { (9, X9) } - } - } -} - -/// The shortest mode implementation for Grisu. -/// -/// It returns `None` when it would return an inexact representation otherwise. -pub fn format_shortest_opt<'a>( - d: &Decoded, - buf: &'a mut [MaybeUninit], -) -> Option<(/*digits*/ &'a [u8], /*exp*/ i16)> { - assert!(d.mant > 0); - assert!(d.minus > 0); - assert!(d.plus > 0); - assert!(d.mant.checked_add(d.plus).is_some()); - assert!(d.mant.checked_sub(d.minus).is_some()); - assert!(buf.len() >= MAX_SIG_DIGITS); - assert!(d.mant + d.plus < (1 << 61)); // we need at least three bits of additional precision - - // start with the normalized values with the shared exponent - let plus = Fp { f: d.mant + d.plus, e: d.exp }.normalize(); - let minus = Fp { f: d.mant - d.minus, e: d.exp }.normalize_to(plus.e); - let v = Fp { f: d.mant, e: d.exp }.normalize_to(plus.e); - - // find any `cached = 10^minusk` such that `ALPHA <= minusk + plus.e + 64 <= GAMMA`. - // since `plus` is normalized, this means `2^(62 + ALPHA) <= plus * cached < 2^(64 + GAMMA)`; - // given our choices of `ALPHA` and `GAMMA`, this puts `plus * cached` into `[4, 2^32)`. - // - // it is obviously desirable to maximize `GAMMA - ALPHA`, - // so that we don't need many cached powers of 10, but there are some considerations: - // - // 1. we want to keep `floor(plus * cached)` within `u32` since it needs a costly division. - // (this is not really avoidable, remainder is required for accuracy estimation.) - // 2. the remainder of `floor(plus * cached)` repeatedly gets multiplied by 10, - // and it should not overflow. - // - // the first gives `64 + GAMMA <= 32`, while the second gives `10 * 2^-ALPHA <= 2^64`; - // -60 and -32 is the maximal range with this constraint, and V8 also uses them. - let (minusk, cached) = cached_power(ALPHA - plus.e - 64, GAMMA - plus.e - 64); - - // scale fps. this gives the maximal error of 1 ulp (proved from Theorem 5.1). - let plus = plus.mul(&cached); - let minus = minus.mul(&cached); - let v = v.mul(&cached); - debug_assert_eq!(plus.e, minus.e); - debug_assert_eq!(plus.e, v.e); - - // +- actual range of minus - // | <---|---------------------- unsafe region --------------------------> | - // | | | - // | |<--->| | <--------------- safe region ---------------> | | - // | | | | | | - // |1 ulp|1 ulp| |1 ulp|1 ulp| |1 ulp|1 ulp| - // |<--->|<--->| |<--->|<--->| |<--->|<--->| - // |-----|-----|-------...-------|-----|-----|-------...-------|-----|-----| - // | minus | | v | | plus | - // minus1 minus0 v - 1 ulp v + 1 ulp plus0 plus1 - // - // above `minus`, `v` and `plus` are *quantized* approximations (error < 1 ulp). - // as we don't know the error is positive or negative, we use two approximations spaced equally - // and have the maximal error of 2 ulps. - // - // the "unsafe region" is a liberal interval which we initially generate. - // the "safe region" is a conservative interval which we only accept. - // we start with the correct repr within the unsafe region, and try to find the closest repr - // to `v` which is also within the safe region. if we can't, we give up. - let plus1 = plus.f + 1; - // let plus0 = plus.f - 1; // only for explanation - // let minus0 = minus.f + 1; // only for explanation - let minus1 = minus.f - 1; - let e = -plus.e as usize; // shared exponent - - // divide `plus1` into integral and fractional parts. - // integral parts are guaranteed to fit in u32, since cached power guarantees `plus < 2^32` - // and normalized `plus.f` is always less than `2^64 - 2^4` due to the precision requirement. - let plus1int = (plus1 >> e) as u32; - let plus1frac = plus1 & ((1 << e) - 1); - - // calculate the largest `10^max_kappa` no more than `plus1` (thus `plus1 < 10^(max_kappa+1)`). - // this is an upper bound of `kappa` below. - let (max_kappa, max_ten_kappa) = max_pow10_no_more_than(plus1int); - - let mut i = 0; - let exp = max_kappa as i16 - minusk + 1; - - // Theorem 6.2: if `k` is the greatest integer s.t. `0 <= y mod 10^k <= y - x`, - // then `V = floor(y / 10^k) * 10^k` is in `[x, y]` and one of the shortest - // representations (with the minimal number of significant digits) in that range. - // - // find the digit length `kappa` between `(minus1, plus1)` as per Theorem 6.2. - // Theorem 6.2 can be adopted to exclude `x` by requiring `y mod 10^k < y - x` instead. - // (e.g., `x` = 32000, `y` = 32777; `kappa` = 2 since `y mod 10^3 = 777 < y - x = 777`.) - // the algorithm relies on the later verification phase to exclude `y`. - let delta1 = plus1 - minus1; - // let delta1int = (delta1 >> e) as usize; // only for explanation - let delta1frac = delta1 & ((1 << e) - 1); - - // render integral parts, while checking for the accuracy at each step. - let mut ten_kappa = max_ten_kappa; // 10^kappa - let mut remainder = plus1int; // digits yet to be rendered - loop { - // we always have at least one digit to render, as `plus1 >= 10^kappa` - // invariants: - // - `delta1int <= remainder < 10^(kappa+1)` - // - `plus1int = d[0..n-1] * 10^(kappa+1) + remainder` - // (it follows that `remainder = plus1int % 10^(kappa+1)`) - - // divide `remainder` by `10^kappa`. both are scaled by `2^-e`. - let q = remainder / ten_kappa; - let r = remainder % ten_kappa; - debug_assert!(q < 10); - buf[i] = MaybeUninit::new(b'0' + q as u8); - i += 1; - - let plus1rem = ((r as u64) << e) + plus1frac; // == (plus1 % 10^kappa) * 2^e - if plus1rem < delta1 { - // `plus1 % 10^kappa < delta1 = plus1 - minus1`; we've found the correct `kappa`. - let ten_kappa = (ten_kappa as u64) << e; // scale 10^kappa back to the shared exponent - return round_and_weed( - // SAFETY: we initialized that memory above. - unsafe { MaybeUninit::slice_assume_init_mut(&mut buf[..i]) }, - exp, - plus1rem, - delta1, - plus1 - v.f, - ten_kappa, - 1, - ); - } - - // break the loop when we have rendered all integral digits. - // the exact number of digits is `max_kappa + 1` as `plus1 < 10^(max_kappa+1)`. - if i > max_kappa as usize { - debug_assert_eq!(ten_kappa, 1); - break; - } - - // restore invariants - ten_kappa /= 10; - remainder = r; - } - - // render fractional parts, while checking for the accuracy at each step. - // this time we rely on repeated multiplications, as division will lose the precision. - let mut remainder = plus1frac; - let mut threshold = delta1frac; - let mut ulp = 1; - loop { - // the next digit should be significant as we've tested that before breaking out - // invariants, where `m = max_kappa + 1` (# of digits in the integral part): - // - `remainder < 2^e` - // - `plus1frac * 10^(n-m) = d[m..n-1] * 2^e + remainder` - - remainder *= 10; // won't overflow, `2^e * 10 < 2^64` - threshold *= 10; - ulp *= 10; - - // divide `remainder` by `10^kappa`. - // both are scaled by `2^e / 10^kappa`, so the latter is implicit here. - let q = remainder >> e; - let r = remainder & ((1 << e) - 1); - debug_assert!(q < 10); - buf[i] = MaybeUninit::new(b'0' + q as u8); - i += 1; - - if r < threshold { - let ten_kappa = 1 << e; // implicit divisor - return round_and_weed( - // SAFETY: we initialized that memory above. - unsafe { MaybeUninit::slice_assume_init_mut(&mut buf[..i]) }, - exp, - r, - threshold, - (plus1 - v.f) * ulp, - ten_kappa, - ulp, - ); - } - - // restore invariants - remainder = r; - } - - // we've generated all significant digits of `plus1`, but not sure if it's the optimal one. - // for example, if `minus1` is 3.14153... and `plus1` is 3.14158..., there are 5 different - // shortest representation from 3.14154 to 3.14158 but we only have the greatest one. - // we have to successively decrease the last digit and check if this is the optimal repr. - // there are at most 9 candidates (..1 to ..9), so this is fairly quick. ("rounding" phase) - // - // the function checks if this "optimal" repr is actually within the ulp ranges, - // and also, it is possible that the "second-to-optimal" repr can actually be optimal - // due to the rounding error. in either cases this returns `None`. ("weeding" phase) - // - // all arguments here are scaled by the common (but implicit) value `k`, so that: - // - `remainder = (plus1 % 10^kappa) * k` - // - `threshold = (plus1 - minus1) * k` (and also, `remainder < threshold`) - // - `plus1v = (plus1 - v) * k` (and also, `threshold > plus1v` from prior invariants) - // - `ten_kappa = 10^kappa * k` - // - `ulp = 2^-e * k` - fn round_and_weed( - buf: &mut [u8], - exp: i16, - remainder: u64, - threshold: u64, - plus1v: u64, - ten_kappa: u64, - ulp: u64, - ) -> Option<(&[u8], i16)> { - assert!(!buf.is_empty()); - - // produce two approximations to `v` (actually `plus1 - v`) within 1.5 ulps. - // the resulting representation should be the closest representation to both. - // - // here `plus1 - v` is used since calculations are done with respect to `plus1` - // in order to avoid overflow/underflow (hence the seemingly swapped names). - let plus1v_down = plus1v + ulp; // plus1 - (v - 1 ulp) - let plus1v_up = plus1v - ulp; // plus1 - (v + 1 ulp) - - // decrease the last digit and stop at the closest representation to `v + 1 ulp`. - let mut plus1w = remainder; // plus1w(n) = plus1 - w(n) - { - let last = buf.last_mut().unwrap(); - - // we work with the approximated digits `w(n)`, which is initially equal to `plus1 - - // plus1 % 10^kappa`. after running the loop body `n` times, `w(n) = plus1 - - // plus1 % 10^kappa - n * 10^kappa`. we set `plus1w(n) = plus1 - w(n) = - // plus1 % 10^kappa + n * 10^kappa` (thus `remainder = plus1w(0)`) to simplify checks. - // note that `plus1w(n)` is always increasing. - // - // we have three conditions to terminate. any of them will make the loop unable to - // proceed, but we then have at least one valid representation known to be closest to - // `v + 1 ulp` anyway. we will denote them as TC1 through TC3 for brevity. - // - // TC1: `w(n) <= v + 1 ulp`, i.e., this is the last repr that can be the closest one. - // this is equivalent to `plus1 - w(n) = plus1w(n) >= plus1 - (v + 1 ulp) = plus1v_up`. - // combined with TC2 (which checks if `w(n+1)` is valid), this prevents the possible - // overflow on the calculation of `plus1w(n)`. - // - // TC2: `w(n+1) < minus1`, i.e., the next repr definitely does not round to `v`. - // this is equivalent to `plus1 - w(n) + 10^kappa = plus1w(n) + 10^kappa > - // plus1 - minus1 = threshold`. the left hand side can overflow, but we know - // `threshold > plus1v`, so if TC1 is false, `threshold - plus1w(n) > - // threshold - (plus1v - 1 ulp) > 1 ulp` and we can safely test if - // `threshold - plus1w(n) < 10^kappa` instead. - // - // TC3: `abs(w(n) - (v + 1 ulp)) <= abs(w(n+1) - (v + 1 ulp))`, i.e., the next repr is - // no closer to `v + 1 ulp` than the current repr. given `z(n) = plus1v_up - plus1w(n)`, - // this becomes `abs(z(n)) <= abs(z(n+1))`. again assuming that TC1 is false, we have - // `z(n) > 0`. we have two cases to consider: - // - // - when `z(n+1) >= 0`: TC3 becomes `z(n) <= z(n+1)`. as `plus1w(n)` is increasing, - // `z(n)` should be decreasing and this is clearly false. - // - when `z(n+1) < 0`: - // - TC3a: the precondition is `plus1v_up < plus1w(n) + 10^kappa`. assuming TC2 is - // false, `threshold >= plus1w(n) + 10^kappa` so it cannot overflow. - // - TC3b: TC3 becomes `z(n) <= -z(n+1)`, i.e., `plus1v_up - plus1w(n) >= - // plus1w(n+1) - plus1v_up = plus1w(n) + 10^kappa - plus1v_up`. the negated TC1 - // gives `plus1v_up > plus1w(n)`, so it cannot overflow or underflow when - // combined with TC3a. - // - // consequently, we should stop when `TC1 || TC2 || (TC3a && TC3b)`. the following is - // equal to its inverse, `!TC1 && !TC2 && (!TC3a || !TC3b)`. - while plus1w < plus1v_up - && threshold - plus1w >= ten_kappa - && (plus1w + ten_kappa < plus1v_up - || plus1v_up - plus1w >= plus1w + ten_kappa - plus1v_up) - { - *last -= 1; - debug_assert!(*last > b'0'); // the shortest repr cannot end with `0` - plus1w += ten_kappa; - } - } - - // check if this representation is also the closest representation to `v - 1 ulp`. - // - // this is simply same to the terminating conditions for `v + 1 ulp`, with all `plus1v_up` - // replaced by `plus1v_down` instead. overflow analysis equally holds. - if plus1w < plus1v_down - && threshold - plus1w >= ten_kappa - && (plus1w + ten_kappa < plus1v_down - || plus1v_down - plus1w >= plus1w + ten_kappa - plus1v_down) - { - return None; - } - - // now we have the closest representation to `v` between `plus1` and `minus1`. - // this is too liberal, though, so we reject any `w(n)` not between `plus0` and `minus0`, - // i.e., `plus1 - plus1w(n) <= minus0` or `plus1 - plus1w(n) >= plus0`. we utilize the facts - // that `threshold = plus1 - minus1` and `plus1 - plus0 = minus0 - minus1 = 2 ulp`. - if 2 * ulp <= plus1w && plus1w <= threshold - 4 * ulp { Some((buf, exp)) } else { None } - } -} - -/// The shortest mode implementation for Grisu with Dragon fallback. -/// -/// This should be used for most cases. -pub fn format_shortest<'a>( - d: &Decoded, - buf: &'a mut [MaybeUninit], -) -> (/*digits*/ &'a [u8], /*exp*/ i16) { - use crate::num::flt2dec::strategy::dragon::format_shortest as fallback; - // SAFETY: The borrow checker is not smart enough to let us use `buf` - // in the second branch, so we launder the lifetime here. But we only re-use - // `buf` if `format_shortest_opt` returned `None` so this is okay. - match format_shortest_opt(d, unsafe { &mut *(buf as *mut _) }) { - Some(ret) => ret, - None => fallback(d, buf), - } -} - -/// The exact and fixed mode implementation for Grisu. -/// -/// It returns `None` when it would return an inexact representation otherwise. -pub fn format_exact_opt<'a>( - d: &Decoded, - buf: &'a mut [MaybeUninit], - limit: i16, -) -> Option<(/*digits*/ &'a [u8], /*exp*/ i16)> { - assert!(d.mant > 0); - assert!(d.mant < (1 << 61)); // we need at least three bits of additional precision - assert!(!buf.is_empty()); - - // normalize and scale `v`. - let v = Fp { f: d.mant, e: d.exp }.normalize(); - let (minusk, cached) = cached_power(ALPHA - v.e - 64, GAMMA - v.e - 64); - let v = v.mul(&cached); - - // divide `v` into integral and fractional parts. - let e = -v.e as usize; - let vint = (v.f >> e) as u32; - let vfrac = v.f & ((1 << e) - 1); - - let requested_digits = buf.len(); - - const POW10_UP_TO_9: [u32; 10] = - [1, 10, 100, 1000, 10_000, 100_000, 1_000_000, 10_000_000, 100_000_000, 1_000_000_000]; - - // We deviate from the original algorithm here and do some early checks to determine if we can satisfy requested_digits. - // If we determine that we can't, we exit early and avoid most of the heavy lifting that the algorithm otherwise does. - // - // When vfrac is zero, we can easily determine if vint can satisfy requested digits: - // If requested_digits >= 11, vint is not able to exhaust the count by itself since 10^(11 -1) > u32 max value >= vint. - // If vint < 10^(requested_digits - 1), vint cannot exhaust the count. - // Otherwise, vint might be able to exhaust the count and we need to execute the rest of the code. - if (vfrac == 0) && ((requested_digits >= 11) || (vint < POW10_UP_TO_9[requested_digits - 1])) { - return None; - } - - // both old `v` and new `v` (scaled by `10^-k`) has an error of < 1 ulp (Theorem 5.1). - // as we don't know the error is positive or negative, we use two approximations - // spaced equally and have the maximal error of 2 ulps (same to the shortest case). - // - // the goal is to find the exactly rounded series of digits that are common to - // both `v - 1 ulp` and `v + 1 ulp`, so that we are maximally confident. - // if this is not possible, we don't know which one is the correct output for `v`, - // so we give up and fall back. - // - // `err` is defined as `1 ulp * 2^e` here (same to the ulp in `vfrac`), - // and we will scale it whenever `v` gets scaled. - let mut err = 1; - - // calculate the largest `10^max_kappa` no more than `v` (thus `v < 10^(max_kappa+1)`). - // this is an upper bound of `kappa` below. - let (max_kappa, max_ten_kappa) = max_pow10_no_more_than(vint); - - let mut i = 0; - let exp = max_kappa as i16 - minusk + 1; - - // if we are working with the last-digit limitation, we need to shorten the buffer - // before the actual rendering in order to avoid double rounding. - // note that we have to enlarge the buffer again when rounding up happens! - let len = if exp <= limit { - // oops, we cannot even produce *one* digit. - // this is possible when, say, we've got something like 9.5 and it's being rounded to 10. - // - // in principle we can immediately call `possibly_round` with an empty buffer, - // but scaling `max_ten_kappa << e` by 10 can result in overflow. - // thus we are being sloppy here and widen the error range by a factor of 10. - // this will increase the false negative rate, but only very, *very* slightly; - // it can only matter noticeably when the mantissa is bigger than 60 bits. - // - // SAFETY: `len=0`, so the obligation of having initialized this memory is trivial. - return unsafe { - possibly_round(buf, 0, exp, limit, v.f / 10, (max_ten_kappa as u64) << e, err << e) - }; - } else if ((exp as i32 - limit as i32) as usize) < buf.len() { - (exp - limit) as usize - } else { - buf.len() - }; - debug_assert!(len > 0); - - // render integral parts. - // the error is entirely fractional, so we don't need to check it in this part. - let mut kappa = max_kappa as i16; - let mut ten_kappa = max_ten_kappa; // 10^kappa - let mut remainder = vint; // digits yet to be rendered - loop { - // we always have at least one digit to render - // invariants: - // - `remainder < 10^(kappa+1)` - // - `vint = d[0..n-1] * 10^(kappa+1) + remainder` - // (it follows that `remainder = vint % 10^(kappa+1)`) - - // divide `remainder` by `10^kappa`. both are scaled by `2^-e`. - let q = remainder / ten_kappa; - let r = remainder % ten_kappa; - debug_assert!(q < 10); - buf[i] = MaybeUninit::new(b'0' + q as u8); - i += 1; - - // is the buffer full? run the rounding pass with the remainder. - if i == len { - let vrem = ((r as u64) << e) + vfrac; // == (v % 10^kappa) * 2^e - // SAFETY: we have initialized `len` many bytes. - return unsafe { - possibly_round(buf, len, exp, limit, vrem, (ten_kappa as u64) << e, err << e) - }; - } - - // break the loop when we have rendered all integral digits. - // the exact number of digits is `max_kappa + 1` as `plus1 < 10^(max_kappa+1)`. - if i > max_kappa as usize { - debug_assert_eq!(ten_kappa, 1); - debug_assert_eq!(kappa, 0); - break; - } - - // restore invariants - kappa -= 1; - ten_kappa /= 10; - remainder = r; - } - - // render fractional parts. - // - // in principle we can continue to the last available digit and check for the accuracy. - // unfortunately we are working with the finite-sized integers, so we need some criterion - // to detect the overflow. V8 uses `remainder > err`, which becomes false when - // the first `i` significant digits of `v - 1 ulp` and `v` differ. however this rejects - // too many otherwise valid input. - // - // since the later phase has a correct overflow detection, we instead use tighter criterion: - // we continue til `err` exceeds `10^kappa / 2`, so that the range between `v - 1 ulp` and - // `v + 1 ulp` definitely contains two or more rounded representations. this is same to - // the first two comparisons from `possibly_round`, for the reference. - let mut remainder = vfrac; - let maxerr = 1 << (e - 1); - while err < maxerr { - // invariants, where `m = max_kappa + 1` (# of digits in the integral part): - // - `remainder < 2^e` - // - `vfrac * 10^(n-m) = d[m..n-1] * 2^e + remainder` - // - `err = 10^(n-m)` - - remainder *= 10; // won't overflow, `2^e * 10 < 2^64` - err *= 10; // won't overflow, `err * 10 < 2^e * 5 < 2^64` - - // divide `remainder` by `10^kappa`. - // both are scaled by `2^e / 10^kappa`, so the latter is implicit here. - let q = remainder >> e; - let r = remainder & ((1 << e) - 1); - debug_assert!(q < 10); - buf[i] = MaybeUninit::new(b'0' + q as u8); - i += 1; - - // is the buffer full? run the rounding pass with the remainder. - if i == len { - // SAFETY: we have initialized `len` many bytes. - return unsafe { possibly_round(buf, len, exp, limit, r, 1 << e, err) }; - } - - // restore invariants - remainder = r; - } - - // further calculation is useless (`possibly_round` definitely fails), so we give up. - return None; - - // we've generated all requested digits of `v`, which should be also same to corresponding - // digits of `v - 1 ulp`. now we check if there is a unique representation shared by - // both `v - 1 ulp` and `v + 1 ulp`; this can be either same to generated digits, or - // to the rounded-up version of those digits. if the range contains multiple representations - // of the same length, we cannot be sure and should return `None` instead. - // - // all arguments here are scaled by the common (but implicit) value `k`, so that: - // - `remainder = (v % 10^kappa) * k` - // - `ten_kappa = 10^kappa * k` - // - `ulp = 2^-e * k` - // - // SAFETY: the first `len` bytes of `buf` must be initialized. - unsafe fn possibly_round( - buf: &mut [MaybeUninit], - mut len: usize, - mut exp: i16, - limit: i16, - remainder: u64, - ten_kappa: u64, - ulp: u64, - ) -> Option<(&[u8], i16)> { - debug_assert!(remainder < ten_kappa); - - // 10^kappa - // : : :<->: : - // : : : : : - // :|1 ulp|1 ulp| : - // :|<--->|<--->| : - // ----|-----|-----|---- - // | v | - // v - 1 ulp v + 1 ulp - // - // (for the reference, the dotted line indicates the exact value for - // possible representations in given number of digits.) - // - // error is too large that there are at least three possible representations - // between `v - 1 ulp` and `v + 1 ulp`. we cannot determine which one is correct. - if ulp >= ten_kappa { - return None; - } - - // 10^kappa - // :<------->: - // : : - // : |1 ulp|1 ulp| - // : |<--->|<--->| - // ----|-----|-----|---- - // | v | - // v - 1 ulp v + 1 ulp - // - // in fact, 1/2 ulp is enough to introduce two possible representations. - // (remember that we need a unique representation for both `v - 1 ulp` and `v + 1 ulp`.) - // this won't overflow, as `ulp < ten_kappa` from the first check. - if ten_kappa - ulp <= ulp { - return None; - } - - // remainder - // :<->| : - // : | : - // :<--------- 10^kappa ---------->: - // | : | : - // |1 ulp|1 ulp| : - // |<--->|<--->| : - // ----|-----|-----|------------------------ - // | v | - // v - 1 ulp v + 1 ulp - // - // if `v + 1 ulp` is closer to the rounded-down representation (which is already in `buf`), - // then we can safely return. note that `v - 1 ulp` *can* be less than the current - // representation, but as `1 ulp < 10^kappa / 2`, this condition is enough: - // the distance between `v - 1 ulp` and the current representation - // cannot exceed `10^kappa / 2`. - // - // the condition equals to `remainder + ulp < 10^kappa / 2`. - // since this can easily overflow, first check if `remainder < 10^kappa / 2`. - // we've already verified that `ulp < 10^kappa / 2`, so as long as - // `10^kappa` did not overflow after all, the second check is fine. - if ten_kappa - remainder > remainder && ten_kappa - 2 * remainder >= 2 * ulp { - // SAFETY: our caller initialized that memory. - return Some((unsafe { MaybeUninit::slice_assume_init_ref(&buf[..len]) }, exp)); - } - - // :<------- remainder ------>| : - // : | : - // :<--------- 10^kappa --------->: - // : | | : | - // : |1 ulp|1 ulp| - // : |<--->|<--->| - // -----------------------|-----|-----|----- - // | v | - // v - 1 ulp v + 1 ulp - // - // on the other hands, if `v - 1 ulp` is closer to the rounded-up representation, - // we should round up and return. for the same reason we don't need to check `v + 1 ulp`. - // - // the condition equals to `remainder - ulp >= 10^kappa / 2`. - // again we first check if `remainder > ulp` (note that this is not `remainder >= ulp`, - // as `10^kappa` is never zero). also note that `remainder - ulp <= 10^kappa`, - // so the second check does not overflow. - if remainder > ulp && ten_kappa - (remainder - ulp) <= remainder - ulp { - if let Some(c) = - // SAFETY: our caller must have initialized that memory. - round_up(unsafe { MaybeUninit::slice_assume_init_mut(&mut buf[..len]) }) - { - // only add an additional digit when we've been requested the fixed precision. - // we also need to check that, if the original buffer was empty, - // the additional digit can only be added when `exp == limit` (edge case). - exp += 1; - if exp > limit && len < buf.len() { - buf[len] = MaybeUninit::new(c); - len += 1; - } - } - // SAFETY: we and our caller initialized that memory. - return Some((unsafe { MaybeUninit::slice_assume_init_ref(&buf[..len]) }, exp)); - } - - // otherwise we are doomed (i.e., some values between `v - 1 ulp` and `v + 1 ulp` are - // rounding down and others are rounding up) and give up. - None - } -} - -/// The exact and fixed mode implementation for Grisu with Dragon fallback. -/// -/// This should be used for most cases. -pub fn format_exact<'a>( - d: &Decoded, - buf: &'a mut [MaybeUninit], - limit: i16, -) -> (/*digits*/ &'a [u8], /*exp*/ i16) { - use crate::num::flt2dec::strategy::dragon::format_exact as fallback; - // SAFETY: The borrow checker is not smart enough to let us use `buf` - // in the second branch, so we launder the lifetime here. But we only re-use - // `buf` if `format_exact_opt` returned `None` so this is okay. - match format_exact_opt(d, unsafe { &mut *(buf as *mut _) }, limit) { - Some(ret) => ret, - None => fallback(d, buf, limit), - } -} diff --git a/library/core/src/num/fmt.rs b/library/core/src/num/fmt.rs deleted file mode 100644 index ed61197157bf5..0000000000000 --- a/library/core/src/num/fmt.rs +++ /dev/null @@ -1,108 +0,0 @@ -//! Shared utilities used by both float and integer formatting. -#![doc(hidden)] -#![unstable( - feature = "numfmt", - reason = "internal routines only exposed for testing", - issue = "none" -)] - -/// Formatted parts. -#[derive(Copy, Clone, PartialEq, Eq, Debug)] -pub enum Part<'a> { - /// Given number of zero digits. - Zero(usize), - /// A literal number up to 5 digits. - Num(u16), - /// A verbatim copy of given bytes. - Copy(&'a [u8]), -} - -impl<'a> Part<'a> { - /// Returns the exact byte length of given part. - pub fn len(&self) -> usize { - match *self { - Part::Zero(nzeroes) => nzeroes, - Part::Num(v) => { - if v < 1_000 { - if v < 10 { - 1 - } else if v < 100 { - 2 - } else { - 3 - } - } else { - if v < 10_000 { 4 } else { 5 } - } - } - Part::Copy(buf) => buf.len(), - } - } - - /// Writes a part into the supplied buffer. - /// Returns the number of written bytes, or `None` if the buffer is not enough. - /// (It may still leave partially written bytes in the buffer; do not rely on that.) - pub fn write(&self, out: &mut [u8]) -> Option { - let len = self.len(); - if out.len() >= len { - match *self { - Part::Zero(nzeroes) => { - for c in &mut out[..nzeroes] { - *c = b'0'; - } - } - Part::Num(mut v) => { - for c in out[..len].iter_mut().rev() { - *c = b'0' + (v % 10) as u8; - v /= 10; - } - } - Part::Copy(buf) => { - out[..buf.len()].copy_from_slice(buf); - } - } - Some(len) - } else { - None - } - } -} - -/// Formatted result containing one or more parts. -/// This can be written to the byte buffer or converted to the allocated string. -#[allow(missing_debug_implementations)] -#[derive(Clone)] -pub struct Formatted<'a> { - /// A byte slice representing a sign, either `""`, `"-"` or `"+"`. - pub sign: &'static str, - /// Formatted parts to be rendered after a sign and optional zero padding. - pub parts: &'a [Part<'a>], -} - -impl<'a> Formatted<'a> { - /// Returns the exact byte length of combined formatted result. - pub fn len(&self) -> usize { - let mut len = self.sign.len(); - for part in self.parts { - len += part.len(); - } - len - } - - /// Writes all formatted parts into the supplied buffer. - /// Returns the number of written bytes, or `None` if the buffer is not enough. - /// (It may still leave partially written bytes in the buffer; do not rely on that.) - pub fn write(&self, out: &mut [u8]) -> Option { - if out.len() < self.sign.len() { - return None; - } - out[..self.sign.len()].copy_from_slice(self.sign.as_bytes()); - - let mut written = self.sign.len(); - for part in self.parts { - let len = part.write(&mut out[written..])?; - written += len; - } - Some(written) - } -} diff --git a/library/core/src/num/int_log10.rs b/library/core/src/num/int_log10.rs deleted file mode 100644 index 0ce31b40a3845..0000000000000 --- a/library/core/src/num/int_log10.rs +++ /dev/null @@ -1,148 +0,0 @@ -/// These functions compute the integer logarithm of their type, assuming -/// that someone has already checked that the value is strictly positive. - -// 0 < val <= u8::MAX -#[inline] -pub const fn u8(val: u8) -> u32 { - let val = val as u32; - - // For better performance, avoid branches by assembling the solution - // in the bits above the low 8 bits. - - // Adding c1 to val gives 10 in the top bits for val < 10, 11 for val >= 10 - const C1: u32 = 0b11_00000000 - 10; // 758 - // Adding c2 to val gives 01 in the top bits for val < 100, 10 for val >= 100 - const C2: u32 = 0b10_00000000 - 100; // 412 - - // Value of top bits: - // +c1 +c2 1&2 - // 0..=9 10 01 00 = 0 - // 10..=99 11 01 01 = 1 - // 100..=255 11 10 10 = 2 - ((val + C1) & (val + C2)) >> 8 -} - -// 0 < val < 100_000 -#[inline] -const fn less_than_5(val: u32) -> u32 { - // Similar to u8, when adding one of these constants to val, - // we get two possible bit patterns above the low 17 bits, - // depending on whether val is below or above the threshold. - const C1: u32 = 0b011_00000000000000000 - 10; // 393206 - const C2: u32 = 0b100_00000000000000000 - 100; // 524188 - const C3: u32 = 0b111_00000000000000000 - 1000; // 916504 - const C4: u32 = 0b100_00000000000000000 - 10000; // 514288 - - // Value of top bits: - // +c1 +c2 1&2 +c3 +c4 3&4 ^ - // 0..=9 010 011 010 110 011 010 000 = 0 - // 10..=99 011 011 011 110 011 010 001 = 1 - // 100..=999 011 100 000 110 011 010 010 = 2 - // 1000..=9999 011 100 000 111 011 011 011 = 3 - // 10000..=99999 011 100 000 111 100 100 100 = 4 - (((val + C1) & (val + C2)) ^ ((val + C3) & (val + C4))) >> 17 -} - -// 0 < val <= u16::MAX -#[inline] -pub const fn u16(val: u16) -> u32 { - less_than_5(val as u32) -} - -// 0 < val <= u32::MAX -#[inline] -pub const fn u32(mut val: u32) -> u32 { - let mut log = 0; - if val >= 100_000 { - val /= 100_000; - log += 5; - } - log + less_than_5(val) -} - -// 0 < val <= u64::MAX -#[inline] -pub const fn u64(mut val: u64) -> u32 { - let mut log = 0; - if val >= 10_000_000_000 { - val /= 10_000_000_000; - log += 10; - } - if val >= 100_000 { - val /= 100_000; - log += 5; - } - log + less_than_5(val as u32) -} - -// 0 < val <= u128::MAX -#[inline] -pub const fn u128(mut val: u128) -> u32 { - let mut log = 0; - if val >= 100_000_000_000_000_000_000_000_000_000_000 { - val /= 100_000_000_000_000_000_000_000_000_000_000; - log += 32; - return log + u32(val as u32); - } - if val >= 10_000_000_000_000_000 { - val /= 10_000_000_000_000_000; - log += 16; - } - log + u64(val as u64) -} - -#[cfg(target_pointer_width = "16")] -#[inline] -pub const fn usize(val: usize) -> u32 { - u16(val as _) -} - -#[cfg(target_pointer_width = "32")] -#[inline] -pub const fn usize(val: usize) -> u32 { - u32(val as _) -} - -#[cfg(target_pointer_width = "64")] -#[inline] -pub const fn usize(val: usize) -> u32 { - u64(val as _) -} - -// 0 < val <= i8::MAX -#[inline] -pub const fn i8(val: i8) -> u32 { - u8(val as u8) -} - -// 0 < val <= i16::MAX -#[inline] -pub const fn i16(val: i16) -> u32 { - u16(val as u16) -} - -// 0 < val <= i32::MAX -#[inline] -pub const fn i32(val: i32) -> u32 { - u32(val as u32) -} - -// 0 < val <= i64::MAX -#[inline] -pub const fn i64(val: i64) -> u32 { - u64(val as u64) -} - -// 0 < val <= i128::MAX -#[inline] -pub const fn i128(val: i128) -> u32 { - u128(val as u128) -} - -/// Instantiate this panic logic once, rather than for all the ilog methods -/// on every single primitive type. -#[cold] -#[track_caller] -pub const fn panic_for_nonpositive_argument() -> ! { - panic!("argument of integer logarithm must be positive") -} diff --git a/library/core/src/num/int_macros.rs b/library/core/src/num/int_macros.rs deleted file mode 100644 index 77b1039039b1d..0000000000000 --- a/library/core/src/num/int_macros.rs +++ /dev/null @@ -1,3516 +0,0 @@ -macro_rules! int_impl { - ( - Self = $SelfT:ty, - ActualT = $ActualT:ident, - UnsignedT = $UnsignedT:ty, - - // There are all for use *only* in doc comments. - // As such, they're all passed as literals -- passing them as a string - // literal is fine if they need to be multiple code tokens. - // In non-comments, use the associated constants rather than these. - BITS = $BITS:literal, - BITS_MINUS_ONE = $BITS_MINUS_ONE:literal, - Min = $Min:literal, - Max = $Max:literal, - rot = $rot:literal, - rot_op = $rot_op:literal, - rot_result = $rot_result:literal, - swap_op = $swap_op:literal, - swapped = $swapped:literal, - reversed = $reversed:literal, - le_bytes = $le_bytes:literal, - be_bytes = $be_bytes:literal, - to_xe_bytes_doc = $to_xe_bytes_doc:expr, - from_xe_bytes_doc = $from_xe_bytes_doc:expr, - bound_condition = $bound_condition:literal, - ) => { - /// The smallest value that can be represented by this integer type - #[doc = concat!("(−2", $BITS_MINUS_ONE, "", $bound_condition, ").")] - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN, ", stringify!($Min), ");")] - /// ``` - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const MIN: Self = !Self::MAX; - - /// The largest value that can be represented by this integer type - #[doc = concat!("(2", $BITS_MINUS_ONE, " − 1", $bound_condition, ").")] - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX, ", stringify!($Max), ");")] - /// ``` - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const MAX: Self = (<$UnsignedT>::MAX >> 1) as Self; - - /// The size of this integer type in bits. - /// - /// # Examples - /// - /// ``` - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::BITS, ", stringify!($BITS), ");")] - /// ``` - #[stable(feature = "int_bits_const", since = "1.53.0")] - pub const BITS: u32 = <$UnsignedT>::BITS; - - /// Returns the number of ones in the binary representation of `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = 0b100_0000", stringify!($SelfT), ";")] - /// - /// assert_eq!(n.count_ones(), 1); - /// ``` - /// - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[doc(alias = "popcount")] - #[doc(alias = "popcnt")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn count_ones(self) -> u32 { (self as $UnsignedT).count_ones() } - - /// Returns the number of zeros in the binary representation of `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.count_zeros(), 1);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn count_zeros(self) -> u32 { - (!self).count_ones() - } - - /// Returns the number of leading zeros in the binary representation of `self`. - /// - /// Depending on what you're doing with the value, you might also be interested in the - /// [`ilog2`] function which returns a consistent number, even if the type widens. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = -1", stringify!($SelfT), ";")] - /// - /// assert_eq!(n.leading_zeros(), 0); - /// ``` - #[doc = concat!("[`ilog2`]: ", stringify!($SelfT), "::ilog2")] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn leading_zeros(self) -> u32 { - (self as $UnsignedT).leading_zeros() - } - - /// Returns the number of trailing zeros in the binary representation of `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = -4", stringify!($SelfT), ";")] - /// - /// assert_eq!(n.trailing_zeros(), 2); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn trailing_zeros(self) -> u32 { - (self as $UnsignedT).trailing_zeros() - } - - /// Returns the number of leading ones in the binary representation of `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = -1", stringify!($SelfT), ";")] - /// - #[doc = concat!("assert_eq!(n.leading_ones(), ", stringify!($BITS), ");")] - /// ``` - #[stable(feature = "leading_trailing_ones", since = "1.46.0")] - #[rustc_const_stable(feature = "leading_trailing_ones", since = "1.46.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn leading_ones(self) -> u32 { - (self as $UnsignedT).leading_ones() - } - - /// Returns the number of trailing ones in the binary representation of `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = 3", stringify!($SelfT), ";")] - /// - /// assert_eq!(n.trailing_ones(), 2); - /// ``` - #[stable(feature = "leading_trailing_ones", since = "1.46.0")] - #[rustc_const_stable(feature = "leading_trailing_ones", since = "1.46.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn trailing_ones(self) -> u32 { - (self as $UnsignedT).trailing_ones() - } - - /// Shifts the bits to the left by a specified amount, `n`, - /// wrapping the truncated bits to the end of the resulting integer. - /// - /// Please note this isn't the same operation as the `<<` shifting operator! - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = ", $rot_op, stringify!($SelfT), ";")] - #[doc = concat!("let m = ", $rot_result, ";")] - /// - #[doc = concat!("assert_eq!(n.rotate_left(", $rot, "), m);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn rotate_left(self, n: u32) -> Self { - (self as $UnsignedT).rotate_left(n) as Self - } - - /// Shifts the bits to the right by a specified amount, `n`, - /// wrapping the truncated bits to the beginning of the resulting - /// integer. - /// - /// Please note this isn't the same operation as the `>>` shifting operator! - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = ", $rot_result, stringify!($SelfT), ";")] - #[doc = concat!("let m = ", $rot_op, ";")] - /// - #[doc = concat!("assert_eq!(n.rotate_right(", $rot, "), m);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn rotate_right(self, n: u32) -> Self { - (self as $UnsignedT).rotate_right(n) as Self - } - - /// Reverses the byte order of the integer. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = ", $swap_op, stringify!($SelfT), ";")] - /// - /// let m = n.swap_bytes(); - /// - #[doc = concat!("assert_eq!(m, ", $swapped, ");")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn swap_bytes(self) -> Self { - (self as $UnsignedT).swap_bytes() as Self - } - - /// Reverses the order of bits in the integer. The least significant bit becomes the most significant bit, - /// second least-significant bit becomes second most-significant bit, etc. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = ", $swap_op, stringify!($SelfT), ";")] - /// let m = n.reverse_bits(); - /// - #[doc = concat!("assert_eq!(m, ", $reversed, ");")] - #[doc = concat!("assert_eq!(0, 0", stringify!($SelfT), ".reverse_bits());")] - /// ``` - #[stable(feature = "reverse_bits", since = "1.37.0")] - #[rustc_const_stable(feature = "reverse_bits", since = "1.37.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn reverse_bits(self) -> Self { - (self as $UnsignedT).reverse_bits() as Self - } - - /// Converts an integer from big endian to the target's endianness. - /// - /// On big endian this is a no-op. On little endian the bytes are swapped. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")] - /// - /// if cfg!(target_endian = "big") { - #[doc = concat!(" assert_eq!(", stringify!($SelfT), "::from_be(n), n)")] - /// } else { - #[doc = concat!(" assert_eq!(", stringify!($SelfT), "::from_be(n), n.swap_bytes())")] - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")] - #[must_use] - #[inline] - pub const fn from_be(x: Self) -> Self { - #[cfg(target_endian = "big")] - { - x - } - #[cfg(not(target_endian = "big"))] - { - x.swap_bytes() - } - } - - /// Converts an integer from little endian to the target's endianness. - /// - /// On little endian this is a no-op. On big endian the bytes are swapped. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")] - /// - /// if cfg!(target_endian = "little") { - #[doc = concat!(" assert_eq!(", stringify!($SelfT), "::from_le(n), n)")] - /// } else { - #[doc = concat!(" assert_eq!(", stringify!($SelfT), "::from_le(n), n.swap_bytes())")] - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")] - #[must_use] - #[inline] - pub const fn from_le(x: Self) -> Self { - #[cfg(target_endian = "little")] - { - x - } - #[cfg(not(target_endian = "little"))] - { - x.swap_bytes() - } - } - - /// Converts `self` to big endian from the target's endianness. - /// - /// On big endian this is a no-op. On little endian the bytes are swapped. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")] - /// - /// if cfg!(target_endian = "big") { - /// assert_eq!(n.to_be(), n) - /// } else { - /// assert_eq!(n.to_be(), n.swap_bytes()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn to_be(self) -> Self { // or not to be? - #[cfg(target_endian = "big")] - { - self - } - #[cfg(not(target_endian = "big"))] - { - self.swap_bytes() - } - } - - /// Converts `self` to little endian from the target's endianness. - /// - /// On little endian this is a no-op. On big endian the bytes are swapped. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")] - /// - /// if cfg!(target_endian = "little") { - /// assert_eq!(n.to_le(), n) - /// } else { - /// assert_eq!(n.to_le(), n.swap_bytes()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_int_conversions", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn to_le(self) -> Self { - #[cfg(target_endian = "little")] - { - self - } - #[cfg(not(target_endian = "little"))] - { - self.swap_bytes() - } - } - - /// Checked integer addition. Computes `self + rhs`, returning `None` - /// if overflow occurred. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).checked_add(1), Some(", stringify!($SelfT), "::MAX - 1));")] - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).checked_add(3), None);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_add(self, rhs: Self) -> Option { - let (a, b) = self.overflowing_add(rhs); - if unlikely!(b) { None } else { Some(a) } - } - - /// Strict integer addition. Computes `self + rhs`, panicking - /// if overflow occurred. - /// - /// # Panics - /// - /// ## Overflow behavior - /// - /// This function will always panic on overflow, regardless of whether overflow checks are enabled. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).strict_add(1), ", stringify!($SelfT), "::MAX - 1);")] - /// ``` - /// - /// The following panics because of overflow: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = (", stringify!($SelfT), "::MAX - 2).strict_add(3);")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn strict_add(self, rhs: Self) -> Self { - let (a, b) = self.overflowing_add(rhs); - if unlikely!(b) { overflow_panic::add() } else { a } - } - - /// Unchecked integer addition. Computes `self + rhs`, assuming overflow - /// cannot occur. - /// - /// Calling `x.unchecked_add(y)` is semantically equivalent to calling - /// `x.`[`checked_add`]`(y).`[`unwrap_unchecked`]`()`. - /// - /// If you're just trying to avoid the panic in debug mode, then **do not** - /// use this. Instead, you're looking for [`wrapping_add`]. - /// - /// # Safety - /// - /// This results in undefined behavior when - #[doc = concat!("`self + rhs > ", stringify!($SelfT), "::MAX` or `self + rhs < ", stringify!($SelfT), "::MIN`,")] - /// i.e. when [`checked_add`] would return `None`. - /// - /// [`unwrap_unchecked`]: option/enum.Option.html#method.unwrap_unchecked - #[doc = concat!("[`checked_add`]: ", stringify!($SelfT), "::checked_add")] - #[doc = concat!("[`wrapping_add`]: ", stringify!($SelfT), "::wrapping_add")] - #[stable(feature = "unchecked_math", since = "1.79.0")] - #[rustc_const_stable(feature = "unchecked_math", since = "1.79.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn unchecked_add(self, rhs: Self) -> Self { - // SAFETY: the caller must uphold the safety contract for - // `unchecked_add`. - unsafe { intrinsics::unchecked_add(self, rhs) } - } - - /// Checked addition with an unsigned integer. Computes `self + rhs`, - /// returning `None` if overflow occurred. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".checked_add_unsigned(2), Some(3));")] - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).checked_add_unsigned(3), None);")] - /// ``` - #[stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_add_unsigned(self, rhs: $UnsignedT) -> Option { - let (a, b) = self.overflowing_add_unsigned(rhs); - if unlikely!(b) { None } else { Some(a) } - } - - /// Strict addition with an unsigned integer. Computes `self + rhs`, - /// panicking if overflow occurred. - /// - /// # Panics - /// - /// ## Overflow behavior - /// - /// This function will always panic on overflow, regardless of whether overflow checks are enabled. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".strict_add_unsigned(2), 3);")] - /// ``` - /// - /// The following panics because of overflow: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = (", stringify!($SelfT), "::MAX - 2).strict_add_unsigned(3);")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn strict_add_unsigned(self, rhs: $UnsignedT) -> Self { - let (a, b) = self.overflowing_add_unsigned(rhs); - if unlikely!(b) { overflow_panic::add() } else { a } - } - - /// Checked integer subtraction. Computes `self - rhs`, returning `None` if - /// overflow occurred. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 2).checked_sub(1), Some(", stringify!($SelfT), "::MIN + 1));")] - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 2).checked_sub(3), None);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_sub(self, rhs: Self) -> Option { - let (a, b) = self.overflowing_sub(rhs); - if unlikely!(b) { None } else { Some(a) } - } - - /// Strict integer subtraction. Computes `self - rhs`, panicking if - /// overflow occurred. - /// - /// # Panics - /// - /// ## Overflow behavior - /// - /// This function will always panic on overflow, regardless of whether overflow checks are enabled. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 2).strict_sub(1), ", stringify!($SelfT), "::MIN + 1);")] - /// ``` - /// - /// The following panics because of overflow: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = (", stringify!($SelfT), "::MIN + 2).strict_sub(3);")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn strict_sub(self, rhs: Self) -> Self { - let (a, b) = self.overflowing_sub(rhs); - if unlikely!(b) { overflow_panic::sub() } else { a } - } - - /// Unchecked integer subtraction. Computes `self - rhs`, assuming overflow - /// cannot occur. - /// - /// Calling `x.unchecked_sub(y)` is semantically equivalent to calling - /// `x.`[`checked_sub`]`(y).`[`unwrap_unchecked`]`()`. - /// - /// If you're just trying to avoid the panic in debug mode, then **do not** - /// use this. Instead, you're looking for [`wrapping_sub`]. - /// - /// # Safety - /// - /// This results in undefined behavior when - #[doc = concat!("`self - rhs > ", stringify!($SelfT), "::MAX` or `self - rhs < ", stringify!($SelfT), "::MIN`,")] - /// i.e. when [`checked_sub`] would return `None`. - /// - /// [`unwrap_unchecked`]: option/enum.Option.html#method.unwrap_unchecked - #[doc = concat!("[`checked_sub`]: ", stringify!($SelfT), "::checked_sub")] - #[doc = concat!("[`wrapping_sub`]: ", stringify!($SelfT), "::wrapping_sub")] - #[stable(feature = "unchecked_math", since = "1.79.0")] - #[rustc_const_stable(feature = "unchecked_math", since = "1.79.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn unchecked_sub(self, rhs: Self) -> Self { - // SAFETY: the caller must uphold the safety contract for - // `unchecked_sub`. - unsafe { intrinsics::unchecked_sub(self, rhs) } - } - - /// Checked subtraction with an unsigned integer. Computes `self - rhs`, - /// returning `None` if overflow occurred. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".checked_sub_unsigned(2), Some(-1));")] - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 2).checked_sub_unsigned(3), None);")] - /// ``` - #[stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_sub_unsigned(self, rhs: $UnsignedT) -> Option { - let (a, b) = self.overflowing_sub_unsigned(rhs); - if unlikely!(b) { None } else { Some(a) } - } - - /// Strict subtraction with an unsigned integer. Computes `self - rhs`, - /// panicking if overflow occurred. - /// - /// # Panics - /// - /// ## Overflow behavior - /// - /// This function will always panic on overflow, regardless of whether overflow checks are enabled. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".strict_sub_unsigned(2), -1);")] - /// ``` - /// - /// The following panics because of overflow: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = (", stringify!($SelfT), "::MIN + 2).strict_sub_unsigned(3);")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn strict_sub_unsigned(self, rhs: $UnsignedT) -> Self { - let (a, b) = self.overflowing_sub_unsigned(rhs); - if unlikely!(b) { overflow_panic::sub() } else { a } - } - - /// Checked integer multiplication. Computes `self * rhs`, returning `None` if - /// overflow occurred. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_mul(1), Some(", stringify!($SelfT), "::MAX));")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_mul(2), None);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_mul(self, rhs: Self) -> Option { - let (a, b) = self.overflowing_mul(rhs); - if unlikely!(b) { None } else { Some(a) } - } - - /// Strict integer multiplication. Computes `self * rhs`, panicking if - /// overflow occurred. - /// - /// # Panics - /// - /// ## Overflow behavior - /// - /// This function will always panic on overflow, regardless of whether overflow checks are enabled. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.strict_mul(1), ", stringify!($SelfT), "::MAX);")] - /// ``` - /// - /// The following panics because of overflow: - /// - /// ``` should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = ", stringify!($SelfT), "::MAX.strict_mul(2);")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn strict_mul(self, rhs: Self) -> Self { - let (a, b) = self.overflowing_mul(rhs); - if unlikely!(b) { overflow_panic::mul() } else { a } - } - - /// Unchecked integer multiplication. Computes `self * rhs`, assuming overflow - /// cannot occur. - /// - /// Calling `x.unchecked_mul(y)` is semantically equivalent to calling - /// `x.`[`checked_mul`]`(y).`[`unwrap_unchecked`]`()`. - /// - /// If you're just trying to avoid the panic in debug mode, then **do not** - /// use this. Instead, you're looking for [`wrapping_mul`]. - /// - /// # Safety - /// - /// This results in undefined behavior when - #[doc = concat!("`self * rhs > ", stringify!($SelfT), "::MAX` or `self * rhs < ", stringify!($SelfT), "::MIN`,")] - /// i.e. when [`checked_mul`] would return `None`. - /// - /// [`unwrap_unchecked`]: option/enum.Option.html#method.unwrap_unchecked - #[doc = concat!("[`checked_mul`]: ", stringify!($SelfT), "::checked_mul")] - #[doc = concat!("[`wrapping_mul`]: ", stringify!($SelfT), "::wrapping_mul")] - #[stable(feature = "unchecked_math", since = "1.79.0")] - #[rustc_const_stable(feature = "unchecked_math", since = "1.79.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn unchecked_mul(self, rhs: Self) -> Self { - // SAFETY: the caller must uphold the safety contract for - // `unchecked_mul`. - unsafe { intrinsics::unchecked_mul(self, rhs) } - } - - /// Checked integer division. Computes `self / rhs`, returning `None` if `rhs == 0` - /// or the division results in overflow. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).checked_div(-1), Some(", stringify!($Max), "));")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_div(-1), None);")] - #[doc = concat!("assert_eq!((1", stringify!($SelfT), ").checked_div(0), None);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_checked_int_div", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_div(self, rhs: Self) -> Option { - if unlikely!(rhs == 0 || ((self == Self::MIN) && (rhs == -1))) { - None - } else { - // SAFETY: div by zero and by INT_MIN have been checked above - Some(unsafe { intrinsics::unchecked_div(self, rhs) }) - } - } - - /// Strict integer division. Computes `self / rhs`, panicking - /// if overflow occurred. - /// - /// # Panics - /// - /// This function will panic if `rhs` is zero. - /// - /// ## Overflow behavior - /// - /// This function will always panic on overflow, regardless of whether overflow checks are enabled. - /// - /// The only case where such an overflow can occur is when one divides `MIN / -1` on a signed type (where - /// `MIN` is the negative minimal value for the type); this is equivalent to `-MIN`, a positive value - /// that is too large to represent in the type. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).strict_div(-1), ", stringify!($Max), ");")] - /// ``` - /// - /// The following panics because of overflow: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_div(-1);")] - /// ``` - /// - /// The following panics because of division by zero: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = (1", stringify!($SelfT), ").strict_div(0);")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn strict_div(self, rhs: Self) -> Self { - let (a, b) = self.overflowing_div(rhs); - if unlikely!(b) { overflow_panic::div() } else { a } - } - - /// Checked Euclidean division. Computes `self.div_euclid(rhs)`, - /// returning `None` if `rhs == 0` or the division results in overflow. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).checked_div_euclid(-1), Some(", stringify!($Max), "));")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_div_euclid(-1), None);")] - #[doc = concat!("assert_eq!((1", stringify!($SelfT), ").checked_div_euclid(0), None);")] - /// ``` - #[stable(feature = "euclidean_division", since = "1.38.0")] - #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_div_euclid(self, rhs: Self) -> Option { - // Using `&` helps LLVM see that it is the same check made in division. - if unlikely!(rhs == 0 || ((self == Self::MIN) & (rhs == -1))) { - None - } else { - Some(self.div_euclid(rhs)) - } - } - - /// Strict Euclidean division. Computes `self.div_euclid(rhs)`, panicking - /// if overflow occurred. - /// - /// # Panics - /// - /// This function will panic if `rhs` is zero. - /// - /// ## Overflow behavior - /// - /// This function will always panic on overflow, regardless of whether overflow checks are enabled. - /// - /// The only case where such an overflow can occur is when one divides `MIN / -1` on a signed type (where - /// `MIN` is the negative minimal value for the type); this is equivalent to `-MIN`, a positive value - /// that is too large to represent in the type. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).strict_div_euclid(-1), ", stringify!($Max), ");")] - /// ``` - /// - /// The following panics because of overflow: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_div_euclid(-1);")] - /// ``` - /// - /// The following panics because of division by zero: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = (1", stringify!($SelfT), ").strict_div_euclid(0);")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn strict_div_euclid(self, rhs: Self) -> Self { - let (a, b) = self.overflowing_div_euclid(rhs); - if unlikely!(b) { overflow_panic::div() } else { a } - } - - /// Checked integer remainder. Computes `self % rhs`, returning `None` if - /// `rhs == 0` or the division results in overflow. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem(2), Some(1));")] - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem(0), None);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_rem(-1), None);")] - /// ``` - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_checked_int_div", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_rem(self, rhs: Self) -> Option { - if unlikely!(rhs == 0 || ((self == Self::MIN) && (rhs == -1))) { - None - } else { - // SAFETY: div by zero and by INT_MIN have been checked above - Some(unsafe { intrinsics::unchecked_rem(self, rhs) }) - } - } - - /// Strict integer remainder. Computes `self % rhs`, panicking if - /// the division results in overflow. - /// - /// # Panics - /// - /// This function will panic if `rhs` is zero. - /// - /// ## Overflow behavior - /// - /// This function will always panic on overflow, regardless of whether overflow checks are enabled. - /// - /// The only case where such an overflow can occur is `x % y` for `MIN / -1` on a - /// signed type (where `MIN` is the negative minimal value), which is invalid due to implementation artifacts. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".strict_rem(2), 1);")] - /// ``` - /// - /// The following panics because of division by zero: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = 5", stringify!($SelfT), ".strict_rem(0);")] - /// ``` - /// - /// The following panics because of overflow: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_rem(-1);")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn strict_rem(self, rhs: Self) -> Self { - let (a, b) = self.overflowing_rem(rhs); - if unlikely!(b) { overflow_panic::rem() } else { a } - } - - /// Checked Euclidean remainder. Computes `self.rem_euclid(rhs)`, returning `None` - /// if `rhs == 0` or the division results in overflow. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(2), Some(1));")] - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(0), None);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_rem_euclid(-1), None);")] - /// ``` - #[stable(feature = "euclidean_division", since = "1.38.0")] - #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_rem_euclid(self, rhs: Self) -> Option { - // Using `&` helps LLVM see that it is the same check made in division. - if unlikely!(rhs == 0 || ((self == Self::MIN) & (rhs == -1))) { - None - } else { - Some(self.rem_euclid(rhs)) - } - } - - /// Strict Euclidean remainder. Computes `self.rem_euclid(rhs)`, panicking if - /// the division results in overflow. - /// - /// # Panics - /// - /// This function will panic if `rhs` is zero. - /// - /// ## Overflow behavior - /// - /// This function will always panic on overflow, regardless of whether overflow checks are enabled. - /// - /// The only case where such an overflow can occur is `x % y` for `MIN / -1` on a - /// signed type (where `MIN` is the negative minimal value), which is invalid due to implementation artifacts. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".strict_rem_euclid(2), 1);")] - /// ``` - /// - /// The following panics because of division by zero: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = 5", stringify!($SelfT), ".strict_rem_euclid(0);")] - /// ``` - /// - /// The following panics because of overflow: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_rem_euclid(-1);")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn strict_rem_euclid(self, rhs: Self) -> Self { - let (a, b) = self.overflowing_rem_euclid(rhs); - if unlikely!(b) { overflow_panic::rem() } else { a } - } - - /// Checked negation. Computes `-self`, returning `None` if `self == MIN`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_neg(), Some(-5));")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_neg(), None);")] - /// ``` - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_neg(self) -> Option { - let (a, b) = self.overflowing_neg(); - if unlikely!(b) { None } else { Some(a) } - } - - /// Unchecked negation. Computes `-self`, assuming overflow cannot occur. - /// - /// # Safety - /// - /// This results in undefined behavior when - #[doc = concat!("`self == ", stringify!($SelfT), "::MIN`,")] - /// i.e. when [`checked_neg`] would return `None`. - /// - #[doc = concat!("[`checked_neg`]: ", stringify!($SelfT), "::checked_neg")] - #[unstable( - feature = "unchecked_neg", - reason = "niche optimization path", - issue = "85122", - )] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[rustc_const_unstable(feature = "unchecked_neg", issue = "85122")] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn unchecked_neg(self) -> Self { - // SAFETY: the caller must uphold the safety contract for - // `unchecked_neg`. - unsafe { intrinsics::unchecked_sub(0, self) } - } - - /// Strict negation. Computes `-self`, panicking if `self == MIN`. - /// - /// # Panics - /// - /// ## Overflow behavior - /// - /// This function will always panic on overflow, regardless of whether overflow checks are enabled. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".strict_neg(), -5);")] - /// ``` - /// - /// The following panics because of overflow: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_neg();")] - /// - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn strict_neg(self) -> Self { - let (a, b) = self.overflowing_neg(); - if unlikely!(b) { overflow_panic::neg() } else { a } - } - - /// Checked shift left. Computes `self << rhs`, returning `None` if `rhs` is larger - /// than or equal to the number of bits in `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".checked_shl(4), Some(0x10));")] - #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".checked_shl(129), None);")] - /// ``` - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")] - // We could always go back to wrapping - #[rustc_allow_const_fn_unstable(unchecked_shifts)] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_shl(self, rhs: u32) -> Option { - // Not using overflowing_shl as that's a wrapping shift - if rhs < Self::BITS { - // SAFETY: just checked the RHS is in-range - Some(unsafe { self.unchecked_shl(rhs) }) - } else { - None - } - } - - /// Strict shift left. Computes `self << rhs`, panicking if `rhs` is larger - /// than or equal to the number of bits in `self`. - /// - /// # Panics - /// - /// ## Overflow behavior - /// - /// This function will always panic on overflow, regardless of whether overflow checks are enabled. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".strict_shl(4), 0x10);")] - /// ``` - /// - /// The following panics because of overflow: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = 0x1", stringify!($SelfT), ".strict_shl(129);")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn strict_shl(self, rhs: u32) -> Self { - let (a, b) = self.overflowing_shl(rhs); - if unlikely!(b) { overflow_panic::shl() } else { a } - } - - /// Unchecked shift left. Computes `self << rhs`, assuming that - /// `rhs` is less than the number of bits in `self`. - /// - /// # Safety - /// - /// This results in undefined behavior if `rhs` is larger than - /// or equal to the number of bits in `self`, - /// i.e. when [`checked_shl`] would return `None`. - /// - #[doc = concat!("[`checked_shl`]: ", stringify!($SelfT), "::checked_shl")] - #[unstable( - feature = "unchecked_shifts", - reason = "niche optimization path", - issue = "85122", - )] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[rustc_const_unstable(feature = "unchecked_shifts", issue = "85122")] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn unchecked_shl(self, rhs: u32) -> Self { - // SAFETY: the caller must uphold the safety contract for - // `unchecked_shl`. - unsafe { intrinsics::unchecked_shl(self, rhs) } - } - - /// Checked shift right. Computes `self >> rhs`, returning `None` if `rhs` is - /// larger than or equal to the number of bits in `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shr(4), Some(0x1));")] - #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shr(128), None);")] - /// ``` - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")] - // We could always go back to wrapping - #[rustc_allow_const_fn_unstable(unchecked_shifts)] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_shr(self, rhs: u32) -> Option { - // Not using overflowing_shr as that's a wrapping shift - if rhs < Self::BITS { - // SAFETY: just checked the RHS is in-range - Some(unsafe { self.unchecked_shr(rhs) }) - } else { - None - } - } - - /// Strict shift right. Computes `self >> rhs`, panicking `rhs` is - /// larger than or equal to the number of bits in `self`. - /// - /// # Panics - /// - /// ## Overflow behavior - /// - /// This function will always panic on overflow, regardless of whether overflow checks are enabled. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".strict_shr(4), 0x1);")] - /// ``` - /// - /// The following panics because of overflow: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = 0x10", stringify!($SelfT), ".strict_shr(128);")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn strict_shr(self, rhs: u32) -> Self { - let (a, b) = self.overflowing_shr(rhs); - if unlikely!(b) { overflow_panic::shr() } else { a } - } - - /// Unchecked shift right. Computes `self >> rhs`, assuming that - /// `rhs` is less than the number of bits in `self`. - /// - /// # Safety - /// - /// This results in undefined behavior if `rhs` is larger than - /// or equal to the number of bits in `self`, - /// i.e. when [`checked_shr`] would return `None`. - /// - #[doc = concat!("[`checked_shr`]: ", stringify!($SelfT), "::checked_shr")] - #[unstable( - feature = "unchecked_shifts", - reason = "niche optimization path", - issue = "85122", - )] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[rustc_const_unstable(feature = "unchecked_shifts", issue = "85122")] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn unchecked_shr(self, rhs: u32) -> Self { - // SAFETY: the caller must uphold the safety contract for - // `unchecked_shr`. - unsafe { intrinsics::unchecked_shr(self, rhs) } - } - - /// Checked absolute value. Computes `self.abs()`, returning `None` if - /// `self == MIN`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!((-5", stringify!($SelfT), ").checked_abs(), Some(5));")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.checked_abs(), None);")] - /// ``` - #[stable(feature = "no_panic_abs", since = "1.13.0")] - #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_abs(self) -> Option { - if self.is_negative() { - self.checked_neg() - } else { - Some(self) - } - } - - /// Strict absolute value. Computes `self.abs()`, panicking if - /// `self == MIN`. - /// - /// # Panics - /// - /// ## Overflow behavior - /// - /// This function will always panic on overflow, regardless of whether overflow checks are enabled. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!((-5", stringify!($SelfT), ").strict_abs(), 5);")] - /// ``` - /// - /// The following panics because of overflow: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = ", stringify!($SelfT), "::MIN.strict_abs();")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn strict_abs(self) -> Self { - if self.is_negative() { - self.strict_neg() - } else { - self - } - } - - /// Checked exponentiation. Computes `self.pow(exp)`, returning `None` if - /// overflow occurred. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(8", stringify!($SelfT), ".checked_pow(2), Some(64));")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_pow(2), None);")] - /// ``` - - #[stable(feature = "no_panic_pow", since = "1.34.0")] - #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_pow(self, mut exp: u32) -> Option { - if exp == 0 { - return Some(1); - } - let mut base = self; - let mut acc: Self = 1; - - while exp > 1 { - if (exp & 1) == 1 { - acc = try_opt!(acc.checked_mul(base)); - } - exp /= 2; - base = try_opt!(base.checked_mul(base)); - } - // since exp!=0, finally the exp must be 1. - // Deal with the final bit of the exponent separately, since - // squaring the base afterwards is not necessary and may cause a - // needless overflow. - acc.checked_mul(base) - } - - /// Strict exponentiation. Computes `self.pow(exp)`, panicking if - /// overflow occurred. - /// - /// # Panics - /// - /// ## Overflow behavior - /// - /// This function will always panic on overflow, regardless of whether overflow checks are enabled. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!(8", stringify!($SelfT), ".strict_pow(2), 64);")] - /// ``` - /// - /// The following panics because of overflow: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = ", stringify!($SelfT), "::MAX.strict_pow(2);")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn strict_pow(self, mut exp: u32) -> Self { - if exp == 0 { - return 1; - } - let mut base = self; - let mut acc: Self = 1; - - while exp > 1 { - if (exp & 1) == 1 { - acc = acc.strict_mul(base); - } - exp /= 2; - base = base.strict_mul(base); - } - // since exp!=0, finally the exp must be 1. - // Deal with the final bit of the exponent separately, since - // squaring the base afterwards is not necessary and may cause a - // needless overflow. - acc.strict_mul(base) - } - - /// Returns the square root of the number, rounded down. - /// - /// Returns `None` if `self` is negative. - /// - /// # Examples - /// - /// Basic usage: - /// ``` - /// #![feature(isqrt)] - #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".checked_isqrt(), Some(3));")] - /// ``` - #[unstable(feature = "isqrt", issue = "116226")] - #[rustc_const_unstable(feature = "isqrt", issue = "116226")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_isqrt(self) -> Option { - if self < 0 { - None - } else { - Some((self as $UnsignedT).isqrt() as Self) - } - } - - /// Saturating integer addition. Computes `self + rhs`, saturating at the numeric - /// bounds instead of overflowing. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_add(1), 101);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_add(100), ", stringify!($SelfT), "::MAX);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_add(-1), ", stringify!($SelfT), "::MIN);")] - /// ``` - - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn saturating_add(self, rhs: Self) -> Self { - intrinsics::saturating_add(self, rhs) - } - - /// Saturating addition with an unsigned integer. Computes `self + rhs`, - /// saturating at the numeric bounds instead of overflowing. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".saturating_add_unsigned(2), 3);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_add_unsigned(100), ", stringify!($SelfT), "::MAX);")] - /// ``` - #[stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn saturating_add_unsigned(self, rhs: $UnsignedT) -> Self { - // Overflow can only happen at the upper bound - // We cannot use `unwrap_or` here because it is not `const` - match self.checked_add_unsigned(rhs) { - Some(x) => x, - None => Self::MAX, - } - } - - /// Saturating integer subtraction. Computes `self - rhs`, saturating at the - /// numeric bounds instead of overflowing. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_sub(127), -27);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_sub(100), ", stringify!($SelfT), "::MIN);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_sub(-1), ", stringify!($SelfT), "::MAX);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn saturating_sub(self, rhs: Self) -> Self { - intrinsics::saturating_sub(self, rhs) - } - - /// Saturating subtraction with an unsigned integer. Computes `self - rhs`, - /// saturating at the numeric bounds instead of overflowing. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_sub_unsigned(127), -27);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_sub_unsigned(100), ", stringify!($SelfT), "::MIN);")] - /// ``` - #[stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn saturating_sub_unsigned(self, rhs: $UnsignedT) -> Self { - // Overflow can only happen at the lower bound - // We cannot use `unwrap_or` here because it is not `const` - match self.checked_sub_unsigned(rhs) { - Some(x) => x, - None => Self::MIN, - } - } - - /// Saturating integer negation. Computes `-self`, returning `MAX` if `self == MIN` - /// instead of overflowing. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_neg(), -100);")] - #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").saturating_neg(), 100);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_neg(), ", stringify!($SelfT), "::MAX);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_neg(), ", stringify!($SelfT), "::MIN + 1);")] - /// ``` - - #[stable(feature = "saturating_neg", since = "1.45.0")] - #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn saturating_neg(self) -> Self { - intrinsics::saturating_sub(0, self) - } - - /// Saturating absolute value. Computes `self.abs()`, returning `MAX` if `self == - /// MIN` instead of overflowing. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_abs(), 100);")] - #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").saturating_abs(), 100);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_abs(), ", stringify!($SelfT), "::MAX);")] - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 1).saturating_abs(), ", stringify!($SelfT), "::MAX);")] - /// ``` - - #[stable(feature = "saturating_neg", since = "1.45.0")] - #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn saturating_abs(self) -> Self { - if self.is_negative() { - self.saturating_neg() - } else { - self - } - } - - /// Saturating integer multiplication. Computes `self * rhs`, saturating at the - /// numeric bounds instead of overflowing. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".saturating_mul(12), 120);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_mul(10), ", stringify!($SelfT), "::MAX);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_mul(10), ", stringify!($SelfT), "::MIN);")] - /// ``` - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn saturating_mul(self, rhs: Self) -> Self { - match self.checked_mul(rhs) { - Some(x) => x, - None => if (self < 0) == (rhs < 0) { - Self::MAX - } else { - Self::MIN - } - } - } - - /// Saturating integer division. Computes `self / rhs`, saturating at the - /// numeric bounds instead of overflowing. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".saturating_div(2), 2);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_div(-1), ", stringify!($SelfT), "::MIN + 1);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_div(-1), ", stringify!($SelfT), "::MAX);")] - /// - /// ``` - #[stable(feature = "saturating_div", since = "1.58.0")] - #[rustc_const_stable(feature = "saturating_div", since = "1.58.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn saturating_div(self, rhs: Self) -> Self { - match self.overflowing_div(rhs) { - (result, false) => result, - (_result, true) => Self::MAX, // MIN / -1 is the only possible saturating overflow - } - } - - /// Saturating integer exponentiation. Computes `self.pow(exp)`, - /// saturating at the numeric bounds instead of overflowing. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!((-4", stringify!($SelfT), ").saturating_pow(3), -64);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_pow(2), ", stringify!($SelfT), "::MAX);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.saturating_pow(3), ", stringify!($SelfT), "::MIN);")] - /// ``` - #[stable(feature = "no_panic_pow", since = "1.34.0")] - #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn saturating_pow(self, exp: u32) -> Self { - match self.checked_pow(exp) { - Some(x) => x, - None if self < 0 && exp % 2 == 1 => Self::MIN, - None => Self::MAX, - } - } - - /// Wrapping (modular) addition. Computes `self + rhs`, wrapping around at the - /// boundary of the type. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_add(27), 127);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.wrapping_add(2), ", stringify!($SelfT), "::MIN + 1);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn wrapping_add(self, rhs: Self) -> Self { - intrinsics::wrapping_add(self, rhs) - } - - /// Wrapping (modular) addition with an unsigned integer. Computes - /// `self + rhs`, wrapping around at the boundary of the type. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_add_unsigned(27), 127);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.wrapping_add_unsigned(2), ", stringify!($SelfT), "::MIN + 1);")] - /// ``` - #[stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn wrapping_add_unsigned(self, rhs: $UnsignedT) -> Self { - self.wrapping_add(rhs as Self) - } - - /// Wrapping (modular) subtraction. Computes `self - rhs`, wrapping around at the - /// boundary of the type. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".wrapping_sub(127), -127);")] - #[doc = concat!("assert_eq!((-2", stringify!($SelfT), ").wrapping_sub(", stringify!($SelfT), "::MAX), ", stringify!($SelfT), "::MAX);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn wrapping_sub(self, rhs: Self) -> Self { - intrinsics::wrapping_sub(self, rhs) - } - - /// Wrapping (modular) subtraction with an unsigned integer. Computes - /// `self - rhs`, wrapping around at the boundary of the type. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".wrapping_sub_unsigned(127), -127);")] - #[doc = concat!("assert_eq!((-2", stringify!($SelfT), ").wrapping_sub_unsigned(", stringify!($UnsignedT), "::MAX), -1);")] - /// ``` - #[stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn wrapping_sub_unsigned(self, rhs: $UnsignedT) -> Self { - self.wrapping_sub(rhs as Self) - } - - /// Wrapping (modular) multiplication. Computes `self * rhs`, wrapping around at - /// the boundary of the type. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".wrapping_mul(12), 120);")] - /// assert_eq!(11i8.wrapping_mul(12), -124); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn wrapping_mul(self, rhs: Self) -> Self { - intrinsics::wrapping_mul(self, rhs) - } - - /// Wrapping (modular) division. Computes `self / rhs`, wrapping around at the - /// boundary of the type. - /// - /// The only case where such wrapping can occur is when one divides `MIN / -1` on a signed type (where - /// `MIN` is the negative minimal value for the type); this is equivalent to `-MIN`, a positive value - /// that is too large to represent in the type. In such a case, this function returns `MIN` itself. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_div(10), 10);")] - /// assert_eq!((-128i8).wrapping_div(-1), -128); - /// ``` - #[stable(feature = "num_wrapping", since = "1.2.0")] - #[rustc_const_stable(feature = "const_wrapping_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn wrapping_div(self, rhs: Self) -> Self { - self.overflowing_div(rhs).0 - } - - /// Wrapping Euclidean division. Computes `self.div_euclid(rhs)`, - /// wrapping around at the boundary of the type. - /// - /// Wrapping will only occur in `MIN / -1` on a signed type (where `MIN` is the negative minimal value - /// for the type). This is equivalent to `-MIN`, a positive value that is too large to represent in the - /// type. In this case, this method returns `MIN` itself. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_div_euclid(10), 10);")] - /// assert_eq!((-128i8).wrapping_div_euclid(-1), -128); - /// ``` - #[stable(feature = "euclidean_division", since = "1.38.0")] - #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn wrapping_div_euclid(self, rhs: Self) -> Self { - self.overflowing_div_euclid(rhs).0 - } - - /// Wrapping (modular) remainder. Computes `self % rhs`, wrapping around at the - /// boundary of the type. - /// - /// Such wrap-around never actually occurs mathematically; implementation artifacts make `x % y` - /// invalid for `MIN / -1` on a signed type (where `MIN` is the negative minimal value). In such a case, - /// this function returns `0`. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_rem(10), 0);")] - /// assert_eq!((-128i8).wrapping_rem(-1), 0); - /// ``` - #[stable(feature = "num_wrapping", since = "1.2.0")] - #[rustc_const_stable(feature = "const_wrapping_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn wrapping_rem(self, rhs: Self) -> Self { - self.overflowing_rem(rhs).0 - } - - /// Wrapping Euclidean remainder. Computes `self.rem_euclid(rhs)`, wrapping around - /// at the boundary of the type. - /// - /// Wrapping will only occur in `MIN % -1` on a signed type (where `MIN` is the negative minimal value - /// for the type). In this case, this method returns 0. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_rem_euclid(10), 0);")] - /// assert_eq!((-128i8).wrapping_rem_euclid(-1), 0); - /// ``` - #[stable(feature = "euclidean_division", since = "1.38.0")] - #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn wrapping_rem_euclid(self, rhs: Self) -> Self { - self.overflowing_rem_euclid(rhs).0 - } - - /// Wrapping (modular) negation. Computes `-self`, wrapping around at the boundary - /// of the type. - /// - /// The only case where such wrapping can occur is when one negates `MIN` on a signed type (where `MIN` - /// is the negative minimal value for the type); this is a positive value that is too large to represent - /// in the type. In such a case, this function returns `MIN` itself. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_neg(), -100);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.wrapping_neg(), ", stringify!($SelfT), "::MIN);")] - /// ``` - #[stable(feature = "num_wrapping", since = "1.2.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn wrapping_neg(self) -> Self { - (0 as $SelfT).wrapping_sub(self) - } - - /// Panic-free bitwise shift-left; yields `self << mask(rhs)`, where `mask` removes - /// any high-order bits of `rhs` that would cause the shift to exceed the bitwidth of the type. - /// - /// Note that this is *not* the same as a rotate-left; the RHS of a wrapping shift-left is restricted to - /// the range of the type, rather than the bits shifted out of the LHS being returned to the other end. - /// The primitive integer types all implement a [`rotate_left`](Self::rotate_left) function, - /// which may be what you want instead. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!((-1", stringify!($SelfT), ").wrapping_shl(7), -128);")] - #[doc = concat!("assert_eq!((-1", stringify!($SelfT), ").wrapping_shl(128), -1);")] - /// ``` - #[stable(feature = "num_wrapping", since = "1.2.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - #[rustc_allow_const_fn_unstable(unchecked_shifts)] - pub const fn wrapping_shl(self, rhs: u32) -> Self { - // SAFETY: the masking by the bitsize of the type ensures that we do not shift - // out of bounds - unsafe { - self.unchecked_shl(rhs & (Self::BITS - 1)) - } - } - - /// Panic-free bitwise shift-right; yields `self >> mask(rhs)`, where `mask` - /// removes any high-order bits of `rhs` that would cause the shift to exceed the bitwidth of the type. - /// - /// Note that this is *not* the same as a rotate-right; the RHS of a wrapping shift-right is restricted - /// to the range of the type, rather than the bits shifted out of the LHS being returned to the other - /// end. The primitive integer types all implement a [`rotate_right`](Self::rotate_right) function, - /// which may be what you want instead. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!((-128", stringify!($SelfT), ").wrapping_shr(7), -1);")] - /// assert_eq!((-128i16).wrapping_shr(64), -128); - /// ``` - #[stable(feature = "num_wrapping", since = "1.2.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - #[rustc_allow_const_fn_unstable(unchecked_shifts)] - pub const fn wrapping_shr(self, rhs: u32) -> Self { - // SAFETY: the masking by the bitsize of the type ensures that we do not shift - // out of bounds - unsafe { - self.unchecked_shr(rhs & (Self::BITS - 1)) - } - } - - /// Wrapping (modular) absolute value. Computes `self.abs()`, wrapping around at - /// the boundary of the type. - /// - /// The only case where such wrapping can occur is when one takes the absolute value of the negative - /// minimal value for the type; this is a positive value that is too large to represent in the type. In - /// such a case, this function returns `MIN` itself. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_abs(), 100);")] - #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").wrapping_abs(), 100);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.wrapping_abs(), ", stringify!($SelfT), "::MIN);")] - /// assert_eq!((-128i8).wrapping_abs() as u8, 128); - /// ``` - #[stable(feature = "no_panic_abs", since = "1.13.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[allow(unused_attributes)] - #[inline] - pub const fn wrapping_abs(self) -> Self { - if self.is_negative() { - self.wrapping_neg() - } else { - self - } - } - - /// Computes the absolute value of `self` without any wrapping - /// or panicking. - /// - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".unsigned_abs(), 100", stringify!($UnsignedT), ");")] - #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").unsigned_abs(), 100", stringify!($UnsignedT), ");")] - /// assert_eq!((-128i8).unsigned_abs(), 128u8); - /// ``` - #[stable(feature = "unsigned_abs", since = "1.51.0")] - #[rustc_const_stable(feature = "unsigned_abs", since = "1.51.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn unsigned_abs(self) -> $UnsignedT { - self.wrapping_abs() as $UnsignedT - } - - /// Wrapping (modular) exponentiation. Computes `self.pow(exp)`, - /// wrapping around at the boundary of the type. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".wrapping_pow(4), 81);")] - /// assert_eq!(3i8.wrapping_pow(5), -13); - /// assert_eq!(3i8.wrapping_pow(6), -39); - /// ``` - #[stable(feature = "no_panic_pow", since = "1.34.0")] - #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn wrapping_pow(self, mut exp: u32) -> Self { - if exp == 0 { - return 1; - } - let mut base = self; - let mut acc: Self = 1; - - while exp > 1 { - if (exp & 1) == 1 { - acc = acc.wrapping_mul(base); - } - exp /= 2; - base = base.wrapping_mul(base); - } - - // since exp!=0, finally the exp must be 1. - // Deal with the final bit of the exponent separately, since - // squaring the base afterwards is not necessary and may cause a - // needless overflow. - acc.wrapping_mul(base) - } - - /// Calculates `self` + `rhs` - /// - /// Returns a tuple of the addition along with a boolean indicating whether an arithmetic overflow would - /// occur. If an overflow would have occurred then the wrapped value is returned. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_add(2), (7, false));")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.overflowing_add(1), (", stringify!($SelfT), "::MIN, true));")] - /// ``` - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn overflowing_add(self, rhs: Self) -> (Self, bool) { - let (a, b) = intrinsics::add_with_overflow(self as $ActualT, rhs as $ActualT); - (a as Self, b) - } - - /// Calculates `self` + `rhs` + `carry` and checks for overflow. - /// - /// Performs "ternary addition" of two integer operands and a carry-in - /// bit, and returns a tuple of the sum along with a boolean indicating - /// whether an arithmetic overflow would occur. On overflow, the wrapped - /// value is returned. - /// - /// This allows chaining together multiple additions to create a wider - /// addition, and can be useful for bignum addition. This method should - /// only be used for the most significant word; for the less significant - /// words the unsigned method - #[doc = concat!("[`", stringify!($UnsignedT), "::carrying_add`]")] - /// should be used. - /// - /// The output boolean returned by this method is *not* a carry flag, - /// and should *not* be added to a more significant word. - /// - /// If the input carry is false, this method is equivalent to - /// [`overflowing_add`](Self::overflowing_add). - /// - /// # Examples - /// - /// ``` - /// #![feature(bigint_helper_methods)] - /// // Only the most significant word is signed. - /// // - #[doc = concat!("// 10 MAX (a = 10 × 2^", stringify!($BITS), " + 2^", stringify!($BITS), " - 1)")] - #[doc = concat!("// + -5 9 (b = -5 × 2^", stringify!($BITS), " + 9)")] - /// // --------- - #[doc = concat!("// 6 8 (sum = 6 × 2^", stringify!($BITS), " + 8)")] - /// - #[doc = concat!("let (a1, a0): (", stringify!($SelfT), ", ", stringify!($UnsignedT), ") = (10, ", stringify!($UnsignedT), "::MAX);")] - #[doc = concat!("let (b1, b0): (", stringify!($SelfT), ", ", stringify!($UnsignedT), ") = (-5, 9);")] - /// let carry0 = false; - /// - #[doc = concat!("// ", stringify!($UnsignedT), "::carrying_add for the less significant words")] - /// let (sum0, carry1) = a0.carrying_add(b0, carry0); - /// assert_eq!(carry1, true); - /// - #[doc = concat!("// ", stringify!($SelfT), "::carrying_add for the most significant word")] - /// let (sum1, overflow) = a1.carrying_add(b1, carry1); - /// assert_eq!(overflow, false); - /// - /// assert_eq!((sum1, sum0), (6, 8)); - /// ``` - #[unstable(feature = "bigint_helper_methods", issue = "85532")] - #[rustc_const_unstable(feature = "const_bigint_helper_methods", issue = "85532")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn carrying_add(self, rhs: Self, carry: bool) -> (Self, bool) { - // note: longer-term this should be done via an intrinsic. - // note: no intermediate overflow is required (https://github.com/rust-lang/rust/issues/85532#issuecomment-1032214946). - let (a, b) = self.overflowing_add(rhs); - let (c, d) = a.overflowing_add(carry as $SelfT); - (c, b != d) - } - - /// Calculates `self` + `rhs` with an unsigned `rhs` - /// - /// Returns a tuple of the addition along with a boolean indicating - /// whether an arithmetic overflow would occur. If an overflow would - /// have occurred then the wrapped value is returned. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".overflowing_add_unsigned(2), (3, false));")] - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN).overflowing_add_unsigned(", stringify!($UnsignedT), "::MAX), (", stringify!($SelfT), "::MAX, false));")] - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).overflowing_add_unsigned(3), (", stringify!($SelfT), "::MIN, true));")] - /// ``` - #[stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn overflowing_add_unsigned(self, rhs: $UnsignedT) -> (Self, bool) { - let rhs = rhs as Self; - let (res, overflowed) = self.overflowing_add(rhs); - (res, overflowed ^ (rhs < 0)) - } - - /// Calculates `self` - `rhs` - /// - /// Returns a tuple of the subtraction along with a boolean indicating whether an arithmetic overflow - /// would occur. If an overflow would have occurred then the wrapped value is returned. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_sub(2), (3, false));")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_sub(1), (", stringify!($SelfT), "::MAX, true));")] - /// ``` - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn overflowing_sub(self, rhs: Self) -> (Self, bool) { - let (a, b) = intrinsics::sub_with_overflow(self as $ActualT, rhs as $ActualT); - (a as Self, b) - } - - /// Calculates `self` − `rhs` − `borrow` and checks for - /// overflow. - /// - /// Performs "ternary subtraction" by subtracting both an integer - /// operand and a borrow-in bit from `self`, and returns a tuple of the - /// difference along with a boolean indicating whether an arithmetic - /// overflow would occur. On overflow, the wrapped value is returned. - /// - /// This allows chaining together multiple subtractions to create a - /// wider subtraction, and can be useful for bignum subtraction. This - /// method should only be used for the most significant word; for the - /// less significant words the unsigned method - #[doc = concat!("[`", stringify!($UnsignedT), "::borrowing_sub`]")] - /// should be used. - /// - /// The output boolean returned by this method is *not* a borrow flag, - /// and should *not* be subtracted from a more significant word. - /// - /// If the input borrow is false, this method is equivalent to - /// [`overflowing_sub`](Self::overflowing_sub). - /// - /// # Examples - /// - /// ``` - /// #![feature(bigint_helper_methods)] - /// // Only the most significant word is signed. - /// // - #[doc = concat!("// 6 8 (a = 6 × 2^", stringify!($BITS), " + 8)")] - #[doc = concat!("// - -5 9 (b = -5 × 2^", stringify!($BITS), " + 9)")] - /// // --------- - #[doc = concat!("// 10 MAX (diff = 10 × 2^", stringify!($BITS), " + 2^", stringify!($BITS), " - 1)")] - /// - #[doc = concat!("let (a1, a0): (", stringify!($SelfT), ", ", stringify!($UnsignedT), ") = (6, 8);")] - #[doc = concat!("let (b1, b0): (", stringify!($SelfT), ", ", stringify!($UnsignedT), ") = (-5, 9);")] - /// let borrow0 = false; - /// - #[doc = concat!("// ", stringify!($UnsignedT), "::borrowing_sub for the less significant words")] - /// let (diff0, borrow1) = a0.borrowing_sub(b0, borrow0); - /// assert_eq!(borrow1, true); - /// - #[doc = concat!("// ", stringify!($SelfT), "::borrowing_sub for the most significant word")] - /// let (diff1, overflow) = a1.borrowing_sub(b1, borrow1); - /// assert_eq!(overflow, false); - /// - #[doc = concat!("assert_eq!((diff1, diff0), (10, ", stringify!($UnsignedT), "::MAX));")] - /// ``` - #[unstable(feature = "bigint_helper_methods", issue = "85532")] - #[rustc_const_unstable(feature = "const_bigint_helper_methods", issue = "85532")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn borrowing_sub(self, rhs: Self, borrow: bool) -> (Self, bool) { - // note: longer-term this should be done via an intrinsic. - // note: no intermediate overflow is required (https://github.com/rust-lang/rust/issues/85532#issuecomment-1032214946). - let (a, b) = self.overflowing_sub(rhs); - let (c, d) = a.overflowing_sub(borrow as $SelfT); - (c, b != d) - } - - /// Calculates `self` - `rhs` with an unsigned `rhs` - /// - /// Returns a tuple of the subtraction along with a boolean indicating - /// whether an arithmetic overflow would occur. If an overflow would - /// have occurred then the wrapped value is returned. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".overflowing_sub_unsigned(2), (-1, false));")] - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX).overflowing_sub_unsigned(", stringify!($UnsignedT), "::MAX), (", stringify!($SelfT), "::MIN, false));")] - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN + 2).overflowing_sub_unsigned(3), (", stringify!($SelfT), "::MAX, true));")] - /// ``` - #[stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn overflowing_sub_unsigned(self, rhs: $UnsignedT) -> (Self, bool) { - let rhs = rhs as Self; - let (res, overflowed) = self.overflowing_sub(rhs); - (res, overflowed ^ (rhs < 0)) - } - - /// Calculates the multiplication of `self` and `rhs`. - /// - /// Returns a tuple of the multiplication along with a boolean indicating whether an arithmetic overflow - /// would occur. If an overflow would have occurred then the wrapped value is returned. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_mul(2), (10, false));")] - /// assert_eq!(1_000_000_000i32.overflowing_mul(10), (1410065408, true)); - /// ``` - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn overflowing_mul(self, rhs: Self) -> (Self, bool) { - let (a, b) = intrinsics::mul_with_overflow(self as $ActualT, rhs as $ActualT); - (a as Self, b) - } - - /// Calculates the divisor when `self` is divided by `rhs`. - /// - /// Returns a tuple of the divisor along with a boolean indicating whether an arithmetic overflow would - /// occur. If an overflow would occur then self is returned. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_div(2), (2, false));")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_div(-1), (", stringify!($SelfT), "::MIN, true));")] - /// ``` - #[inline] - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_overflowing_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - pub const fn overflowing_div(self, rhs: Self) -> (Self, bool) { - // Using `&` helps LLVM see that it is the same check made in division. - if unlikely!((self == Self::MIN) & (rhs == -1)) { - (self, true) - } else { - (self / rhs, false) - } - } - - /// Calculates the quotient of Euclidean division `self.div_euclid(rhs)`. - /// - /// Returns a tuple of the divisor along with a boolean indicating whether an arithmetic overflow would - /// occur. If an overflow would occur then `self` is returned. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_div_euclid(2), (2, false));")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_div_euclid(-1), (", stringify!($SelfT), "::MIN, true));")] - /// ``` - #[inline] - #[stable(feature = "euclidean_division", since = "1.38.0")] - #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - pub const fn overflowing_div_euclid(self, rhs: Self) -> (Self, bool) { - // Using `&` helps LLVM see that it is the same check made in division. - if unlikely!((self == Self::MIN) & (rhs == -1)) { - (self, true) - } else { - (self.div_euclid(rhs), false) - } - } - - /// Calculates the remainder when `self` is divided by `rhs`. - /// - /// Returns a tuple of the remainder after dividing along with a boolean indicating whether an - /// arithmetic overflow would occur. If an overflow would occur then 0 is returned. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_rem(2), (1, false));")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_rem(-1), (0, true));")] - /// ``` - #[inline] - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_overflowing_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - pub const fn overflowing_rem(self, rhs: Self) -> (Self, bool) { - if unlikely!(rhs == -1) { - (0, self == Self::MIN) - } else { - (self % rhs, false) - } - } - - - /// Overflowing Euclidean remainder. Calculates `self.rem_euclid(rhs)`. - /// - /// Returns a tuple of the remainder after dividing along with a boolean indicating whether an - /// arithmetic overflow would occur. If an overflow would occur then 0 is returned. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_rem_euclid(2), (1, false));")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_rem_euclid(-1), (0, true));")] - /// ``` - #[stable(feature = "euclidean_division", since = "1.38.0")] - #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn overflowing_rem_euclid(self, rhs: Self) -> (Self, bool) { - if unlikely!(rhs == -1) { - (0, self == Self::MIN) - } else { - (self.rem_euclid(rhs), false) - } - } - - - /// Negates self, overflowing if this is equal to the minimum value. - /// - /// Returns a tuple of the negated version of self along with a boolean indicating whether an overflow - /// happened. If `self` is the minimum value (e.g., `i32::MIN` for values of type `i32`), then the - /// minimum value will be returned again and `true` will be returned for an overflow happening. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".overflowing_neg(), (-2, false));")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.overflowing_neg(), (", stringify!($SelfT), "::MIN, true));")] - /// ``` - #[inline] - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[allow(unused_attributes)] - pub const fn overflowing_neg(self) -> (Self, bool) { - if unlikely!(self == Self::MIN) { - (Self::MIN, true) - } else { - (-self, false) - } - } - - /// Shifts self left by `rhs` bits. - /// - /// Returns a tuple of the shifted version of self along with a boolean indicating whether the shift - /// value was larger than or equal to the number of bits. If the shift value is too large, then value is - /// masked (N-1) where N is the number of bits, and this value is then used to perform the shift. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(0x1", stringify!($SelfT),".overflowing_shl(4), (0x10, false));")] - /// assert_eq!(0x1i32.overflowing_shl(36), (0x10, true)); - /// ``` - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn overflowing_shl(self, rhs: u32) -> (Self, bool) { - (self.wrapping_shl(rhs), rhs >= Self::BITS) - } - - /// Shifts self right by `rhs` bits. - /// - /// Returns a tuple of the shifted version of self along with a boolean indicating whether the shift - /// value was larger than or equal to the number of bits. If the shift value is too large, then value is - /// masked (N-1) where N is the number of bits, and this value is then used to perform the shift. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".overflowing_shr(4), (0x1, false));")] - /// assert_eq!(0x10i32.overflowing_shr(36), (0x1, true)); - /// ``` - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn overflowing_shr(self, rhs: u32) -> (Self, bool) { - (self.wrapping_shr(rhs), rhs >= Self::BITS) - } - - /// Computes the absolute value of `self`. - /// - /// Returns a tuple of the absolute version of self along with a boolean indicating whether an overflow - /// happened. If self is the minimum value - #[doc = concat!("(e.g., ", stringify!($SelfT), "::MIN for values of type ", stringify!($SelfT), "),")] - /// then the minimum value will be returned again and true will be returned - /// for an overflow happening. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".overflowing_abs(), (10, false));")] - #[doc = concat!("assert_eq!((-10", stringify!($SelfT), ").overflowing_abs(), (10, false));")] - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MIN).overflowing_abs(), (", stringify!($SelfT), "::MIN, true));")] - /// ``` - #[stable(feature = "no_panic_abs", since = "1.13.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn overflowing_abs(self) -> (Self, bool) { - (self.wrapping_abs(), self == Self::MIN) - } - - /// Raises self to the power of `exp`, using exponentiation by squaring. - /// - /// Returns a tuple of the exponentiation along with a bool indicating - /// whether an overflow happened. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".overflowing_pow(4), (81, false));")] - /// assert_eq!(3i8.overflowing_pow(5), (-13, true)); - /// ``` - #[stable(feature = "no_panic_pow", since = "1.34.0")] - #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn overflowing_pow(self, mut exp: u32) -> (Self, bool) { - if exp == 0 { - return (1,false); - } - let mut base = self; - let mut acc: Self = 1; - let mut overflown = false; - // Scratch space for storing results of overflowing_mul. - let mut r; - - while exp > 1 { - if (exp & 1) == 1 { - r = acc.overflowing_mul(base); - acc = r.0; - overflown |= r.1; - } - exp /= 2; - r = base.overflowing_mul(base); - base = r.0; - overflown |= r.1; - } - - // since exp!=0, finally the exp must be 1. - // Deal with the final bit of the exponent separately, since - // squaring the base afterwards is not necessary and may cause a - // needless overflow. - r = acc.overflowing_mul(base); - r.1 |= overflown; - r - } - - /// Raises self to the power of `exp`, using exponentiation by squaring. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let x: ", stringify!($SelfT), " = 2; // or any other integer type")] - /// - /// assert_eq!(x.pow(5), 32); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[rustc_inherit_overflow_checks] - pub const fn pow(self, mut exp: u32) -> Self { - if exp == 0 { - return 1; - } - let mut base = self; - let mut acc = 1; - - while exp > 1 { - if (exp & 1) == 1 { - acc = acc * base; - } - exp /= 2; - base = base * base; - } - - // since exp!=0, finally the exp must be 1. - // Deal with the final bit of the exponent separately, since - // squaring the base afterwards is not necessary and may cause a - // needless overflow. - acc * base - } - - /// Returns the square root of the number, rounded down. - /// - /// # Panics - /// - /// This function will panic if `self` is negative. - /// - /// # Examples - /// - /// Basic usage: - /// ``` - /// #![feature(isqrt)] - #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".isqrt(), 3);")] - /// ``` - #[unstable(feature = "isqrt", issue = "116226")] - #[rustc_const_unstable(feature = "isqrt", issue = "116226")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn isqrt(self) -> Self { - // I would like to implement it as - // ``` - // self.checked_isqrt().expect("argument of integer square root must be non-negative") - // ``` - // but `expect` is not yet stable as a `const fn`. - match self.checked_isqrt() { - Some(sqrt) => sqrt, - None => panic!("argument of integer square root must be non-negative"), - } - } - - /// Calculates the quotient of Euclidean division of `self` by `rhs`. - /// - /// This computes the integer `q` such that `self = q * rhs + r`, with - /// `r = self.rem_euclid(rhs)` and `0 <= r < abs(rhs)`. - /// - /// In other words, the result is `self / rhs` rounded to the integer `q` - /// such that `self >= q * rhs`. - /// If `self > 0`, this is equal to round towards zero (the default in Rust); - /// if `self < 0`, this is equal to round towards +/- infinity. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0 or if `self` is -1 and `rhs` is - /// `Self::MIN`. This behavior is not affected by the `overflow-checks` flag. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let a: ", stringify!($SelfT), " = 7; // or any other integer type")] - /// let b = 4; - /// - /// assert_eq!(a.div_euclid(b), 1); // 7 >= 4 * 1 - /// assert_eq!(a.div_euclid(-b), -1); // 7 >= -4 * -1 - /// assert_eq!((-a).div_euclid(b), -2); // -7 >= 4 * -2 - /// assert_eq!((-a).div_euclid(-b), 2); // -7 >= -4 * 2 - /// ``` - #[stable(feature = "euclidean_division", since = "1.38.0")] - #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn div_euclid(self, rhs: Self) -> Self { - let q = self / rhs; - if self % rhs < 0 { - return if rhs > 0 { q - 1 } else { q + 1 } - } - q - } - - - /// Calculates the least nonnegative remainder of `self (mod rhs)`. - /// - /// This is done as if by the Euclidean division algorithm -- given - /// `r = self.rem_euclid(rhs)`, `self = rhs * self.div_euclid(rhs) + r`, and - /// `0 <= r < abs(rhs)`. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0 or if `self` is -1 and `rhs` is - /// `Self::MIN`. This behavior is not affected by the `overflow-checks` flag. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let a: ", stringify!($SelfT), " = 7; // or any other integer type")] - /// let b = 4; - /// - /// assert_eq!(a.rem_euclid(b), 3); - /// assert_eq!((-a).rem_euclid(b), 1); - /// assert_eq!(a.rem_euclid(-b), 3); - /// assert_eq!((-a).rem_euclid(-b), 1); - /// ``` - #[doc(alias = "modulo", alias = "mod")] - #[stable(feature = "euclidean_division", since = "1.38.0")] - #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn rem_euclid(self, rhs: Self) -> Self { - let r = self % rhs; - if r < 0 { - // Semantically equivalent to `if rhs < 0 { r - rhs } else { r + rhs }`. - // If `rhs` is not `Self::MIN`, then `r + abs(rhs)` will not overflow - // and is clearly equivalent, because `r` is negative. - // Otherwise, `rhs` is `Self::MIN`, then we have - // `r.wrapping_add(Self::MIN.wrapping_abs())`, which evaluates - // to `r.wrapping_add(Self::MIN)`, which is equivalent to - // `r - Self::MIN`, which is what we wanted (and will not overflow - // for negative `r`). - r.wrapping_add(rhs.wrapping_abs()) - } else { - r - } - } - - /// Calculates the quotient of `self` and `rhs`, rounding the result towards negative infinity. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0 or if `self` is -1 and `rhs` is - /// `Self::MIN`. This behavior is not affected by the `overflow-checks` flag. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(int_roundings)] - #[doc = concat!("let a: ", stringify!($SelfT)," = 8;")] - /// let b = 3; - /// - /// assert_eq!(a.div_floor(b), 2); - /// assert_eq!(a.div_floor(-b), -3); - /// assert_eq!((-a).div_floor(b), -3); - /// assert_eq!((-a).div_floor(-b), 2); - /// ``` - #[unstable(feature = "int_roundings", issue = "88581")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn div_floor(self, rhs: Self) -> Self { - let d = self / rhs; - let r = self % rhs; - if (r > 0 && rhs < 0) || (r < 0 && rhs > 0) { - d - 1 - } else { - d - } - } - - /// Calculates the quotient of `self` and `rhs`, rounding the result towards positive infinity. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0 or if `self` is -1 and `rhs` is - /// `Self::MIN`. This behavior is not affected by the `overflow-checks` flag. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(int_roundings)] - #[doc = concat!("let a: ", stringify!($SelfT)," = 8;")] - /// let b = 3; - /// - /// assert_eq!(a.div_ceil(b), 3); - /// assert_eq!(a.div_ceil(-b), -2); - /// assert_eq!((-a).div_ceil(b), -2); - /// assert_eq!((-a).div_ceil(-b), 3); - /// ``` - #[unstable(feature = "int_roundings", issue = "88581")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn div_ceil(self, rhs: Self) -> Self { - let d = self / rhs; - let r = self % rhs; - if (r > 0 && rhs > 0) || (r < 0 && rhs < 0) { - d + 1 - } else { - d - } - } - - /// If `rhs` is positive, calculates the smallest value greater than or - /// equal to `self` that is a multiple of `rhs`. If `rhs` is negative, - /// calculates the largest value less than or equal to `self` that is a - /// multiple of `rhs`. - /// - /// # Panics - /// - /// This function will panic if `rhs` is zero. - /// - /// ## Overflow behavior - /// - /// On overflow, this function will panic if overflow checks are enabled (default in debug - /// mode) and wrap if overflow checks are disabled (default in release mode). - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(int_roundings)] - #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".next_multiple_of(8), 16);")] - #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".next_multiple_of(8), 24);")] - #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".next_multiple_of(-8), 16);")] - #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".next_multiple_of(-8), 16);")] - #[doc = concat!("assert_eq!((-16_", stringify!($SelfT), ").next_multiple_of(8), -16);")] - #[doc = concat!("assert_eq!((-23_", stringify!($SelfT), ").next_multiple_of(8), -16);")] - #[doc = concat!("assert_eq!((-16_", stringify!($SelfT), ").next_multiple_of(-8), -16);")] - #[doc = concat!("assert_eq!((-23_", stringify!($SelfT), ").next_multiple_of(-8), -24);")] - /// ``` - #[unstable(feature = "int_roundings", issue = "88581")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[rustc_inherit_overflow_checks] - pub const fn next_multiple_of(self, rhs: Self) -> Self { - // This would otherwise fail when calculating `r` when self == T::MIN. - if rhs == -1 { - return self; - } - - let r = self % rhs; - let m = if (r > 0 && rhs < 0) || (r < 0 && rhs > 0) { - r + rhs - } else { - r - }; - - if m == 0 { - self - } else { - self + (rhs - m) - } - } - - /// If `rhs` is positive, calculates the smallest value greater than or - /// equal to `self` that is a multiple of `rhs`. If `rhs` is negative, - /// calculates the largest value less than or equal to `self` that is a - /// multiple of `rhs`. Returns `None` if `rhs` is zero or the operation - /// would result in overflow. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(int_roundings)] - #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".checked_next_multiple_of(8), Some(16));")] - #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".checked_next_multiple_of(8), Some(24));")] - #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".checked_next_multiple_of(-8), Some(16));")] - #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".checked_next_multiple_of(-8), Some(16));")] - #[doc = concat!("assert_eq!((-16_", stringify!($SelfT), ").checked_next_multiple_of(8), Some(-16));")] - #[doc = concat!("assert_eq!((-23_", stringify!($SelfT), ").checked_next_multiple_of(8), Some(-16));")] - #[doc = concat!("assert_eq!((-16_", stringify!($SelfT), ").checked_next_multiple_of(-8), Some(-16));")] - #[doc = concat!("assert_eq!((-23_", stringify!($SelfT), ").checked_next_multiple_of(-8), Some(-24));")] - #[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".checked_next_multiple_of(0), None);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_next_multiple_of(2), None);")] - /// ``` - #[unstable(feature = "int_roundings", issue = "88581")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_next_multiple_of(self, rhs: Self) -> Option { - // This would otherwise fail when calculating `r` when self == T::MIN. - if rhs == -1 { - return Some(self); - } - - let r = try_opt!(self.checked_rem(rhs)); - let m = if (r > 0 && rhs < 0) || (r < 0 && rhs > 0) { - // r + rhs cannot overflow because they have opposite signs - r + rhs - } else { - r - }; - - if m == 0 { - Some(self) - } else { - // rhs - m cannot overflow because m has the same sign as rhs - self.checked_add(rhs - m) - } - } - - /// Calculates the middle point of `self` and `rhs`. - /// - /// `midpoint(a, b)` is `(a + b) >> 1` as if it were performed in a - /// sufficiently-large signed integral type. This implies that the result is - /// always rounded towards negative infinity and that no overflow will ever occur. - /// - /// # Examples - /// - /// ``` - /// #![feature(num_midpoint)] - #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".midpoint(4), 2);")] - #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".midpoint(-1), -1);")] - #[doc = concat!("assert_eq!((-1", stringify!($SelfT), ").midpoint(0), -1);")] - /// ``` - #[unstable(feature = "num_midpoint", issue = "110840")] - #[rustc_const_unstable(feature = "const_num_midpoint", issue = "110840")] - #[rustc_allow_const_fn_unstable(const_num_midpoint)] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn midpoint(self, rhs: Self) -> Self { - const U: $UnsignedT = <$SelfT>::MIN.unsigned_abs(); - - // Map an $SelfT to an $UnsignedT - // ex: i8 [-128; 127] to [0; 255] - const fn map(a: $SelfT) -> $UnsignedT { - (a as $UnsignedT) ^ U - } - - // Map an $UnsignedT to an $SelfT - // ex: u8 [0; 255] to [-128; 127] - const fn demap(a: $UnsignedT) -> $SelfT { - (a ^ U) as $SelfT - } - - demap(<$UnsignedT>::midpoint(map(self), map(rhs))) - } - - /// Returns the logarithm of the number with respect to an arbitrary base, - /// rounded down. - /// - /// This method might not be optimized owing to implementation details; - /// `ilog2` can produce results more efficiently for base 2, and `ilog10` - /// can produce results more efficiently for base 10. - /// - /// # Panics - /// - /// This function will panic if `self` is less than or equal to zero, - /// or if `base` is less than 2. - /// - /// # Examples - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".ilog(5), 1);")] - /// ``` - #[stable(feature = "int_log", since = "1.67.0")] - #[rustc_const_stable(feature = "int_log", since = "1.67.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn ilog(self, base: Self) -> u32 { - assert!(base >= 2, "base of integer logarithm must be at least 2"); - if let Some(log) = self.checked_ilog(base) { - log - } else { - int_log10::panic_for_nonpositive_argument() - } - } - - /// Returns the base 2 logarithm of the number, rounded down. - /// - /// # Panics - /// - /// This function will panic if `self` is less than or equal to zero. - /// - /// # Examples - /// - /// ``` - #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".ilog2(), 1);")] - /// ``` - #[stable(feature = "int_log", since = "1.67.0")] - #[rustc_const_stable(feature = "int_log", since = "1.67.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn ilog2(self) -> u32 { - if let Some(log) = self.checked_ilog2() { - log - } else { - int_log10::panic_for_nonpositive_argument() - } - } - - /// Returns the base 10 logarithm of the number, rounded down. - /// - /// # Panics - /// - /// This function will panic if `self` is less than or equal to zero. - /// - /// # Example - /// - /// ``` - #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".ilog10(), 1);")] - /// ``` - #[stable(feature = "int_log", since = "1.67.0")] - #[rustc_const_stable(feature = "int_log", since = "1.67.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn ilog10(self) -> u32 { - if let Some(log) = self.checked_ilog10() { - log - } else { - int_log10::panic_for_nonpositive_argument() - } - } - - /// Returns the logarithm of the number with respect to an arbitrary base, - /// rounded down. - /// - /// Returns `None` if the number is negative or zero, or if the base is not at least 2. - /// - /// This method might not be optimized owing to implementation details; - /// `checked_ilog2` can produce results more efficiently for base 2, and - /// `checked_ilog10` can produce results more efficiently for base 10. - /// - /// # Examples - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_ilog(5), Some(1));")] - /// ``` - #[stable(feature = "int_log", since = "1.67.0")] - #[rustc_const_stable(feature = "int_log", since = "1.67.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_ilog(self, base: Self) -> Option { - if self <= 0 || base <= 1 { - None - } else { - // Delegate to the unsigned implementation. - // The condition makes sure that both casts are exact. - (self as $UnsignedT).checked_ilog(base as $UnsignedT) - } - } - - /// Returns the base 2 logarithm of the number, rounded down. - /// - /// Returns `None` if the number is negative or zero. - /// - /// # Examples - /// - /// ``` - #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".checked_ilog2(), Some(1));")] - /// ``` - #[stable(feature = "int_log", since = "1.67.0")] - #[rustc_const_stable(feature = "int_log", since = "1.67.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_ilog2(self) -> Option { - if self <= 0 { - None - } else { - // SAFETY: We just checked that this number is positive - let log = (Self::BITS - 1) - unsafe { intrinsics::ctlz_nonzero(self) as u32 }; - Some(log) - } - } - - /// Returns the base 10 logarithm of the number, rounded down. - /// - /// Returns `None` if the number is negative or zero. - /// - /// # Example - /// - /// ``` - #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".checked_ilog10(), Some(1));")] - /// ``` - #[stable(feature = "int_log", since = "1.67.0")] - #[rustc_const_stable(feature = "int_log", since = "1.67.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_ilog10(self) -> Option { - if self > 0 { - Some(int_log10::$ActualT(self as $ActualT)) - } else { - None - } - } - - /// Computes the absolute value of `self`. - /// - /// # Overflow behavior - /// - /// The absolute value of - #[doc = concat!("`", stringify!($SelfT), "::MIN`")] - /// cannot be represented as an - #[doc = concat!("`", stringify!($SelfT), "`,")] - /// and attempting to calculate it will cause an overflow. This means - /// that code in debug mode will trigger a panic on this case and - /// optimized code will return - #[doc = concat!("`", stringify!($SelfT), "::MIN`")] - /// without a panic. If you do not want this behavior, consider - /// using [`unsigned_abs`](Self::unsigned_abs) instead. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".abs(), 10);")] - #[doc = concat!("assert_eq!((-10", stringify!($SelfT), ").abs(), 10);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[allow(unused_attributes)] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[rustc_inherit_overflow_checks] - pub const fn abs(self) -> Self { - // Note that the #[rustc_inherit_overflow_checks] and #[inline] - // above mean that the overflow semantics of the subtraction - // depend on the crate we're being called from. - if self.is_negative() { - -self - } else { - self - } - } - - /// Computes the absolute difference between `self` and `other`. - /// - /// This function always returns the correct answer without overflow or - /// panics by returning an unsigned integer. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".abs_diff(80), 20", stringify!($UnsignedT), ");")] - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".abs_diff(110), 10", stringify!($UnsignedT), ");")] - #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").abs_diff(80), 180", stringify!($UnsignedT), ");")] - #[doc = concat!("assert_eq!((-100", stringify!($SelfT), ").abs_diff(-120), 20", stringify!($UnsignedT), ");")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN.abs_diff(", stringify!($SelfT), "::MAX), ", stringify!($UnsignedT), "::MAX);")] - /// ``` - #[stable(feature = "int_abs_diff", since = "1.60.0")] - #[rustc_const_stable(feature = "int_abs_diff", since = "1.60.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn abs_diff(self, other: Self) -> $UnsignedT { - if self < other { - // Converting a non-negative x from signed to unsigned by using - // `x as U` is left unchanged, but a negative x is converted - // to value x + 2^N. Thus if `s` and `o` are binary variables - // respectively indicating whether `self` and `other` are - // negative, we are computing the mathematical value: - // - // (other + o*2^N) - (self + s*2^N) mod 2^N - // other - self + (o-s)*2^N mod 2^N - // other - self mod 2^N - // - // Finally, taking the mod 2^N of the mathematical value of - // `other - self` does not change it as it already is - // in the range [0, 2^N). - (other as $UnsignedT).wrapping_sub(self as $UnsignedT) - } else { - (self as $UnsignedT).wrapping_sub(other as $UnsignedT) - } - } - - /// Returns a number representing sign of `self`. - /// - /// - `0` if the number is zero - /// - `1` if the number is positive - /// - `-1` if the number is negative - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".signum(), 1);")] - #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".signum(), 0);")] - #[doc = concat!("assert_eq!((-10", stringify!($SelfT), ").signum(), -1);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_int_sign", since = "1.47.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn signum(self) -> Self { - // Picking the right way to phrase this is complicated - // () - // so delegate it to `Ord` which is already producing -1/0/+1 - // exactly like we need and can be the place to deal with the complexity. - - // FIXME(const-hack): replace with cmp - if self < 0 { -1 } - else if self == 0 { 0 } - else { 1 } - } - - /// Returns `true` if `self` is positive and `false` if the number is zero or - /// negative. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert!(10", stringify!($SelfT), ".is_positive());")] - #[doc = concat!("assert!(!(-10", stringify!($SelfT), ").is_positive());")] - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[inline(always)] - pub const fn is_positive(self) -> bool { self > 0 } - - /// Returns `true` if `self` is negative and `false` if the number is zero or - /// positive. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert!((-10", stringify!($SelfT), ").is_negative());")] - #[doc = concat!("assert!(!10", stringify!($SelfT), ".is_negative());")] - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_int_methods", since = "1.32.0")] - #[inline(always)] - pub const fn is_negative(self) -> bool { self < 0 } - - /// Return the memory representation of this integer as a byte array in - /// big-endian (network) byte order. - /// - #[doc = $to_xe_bytes_doc] - /// - /// # Examples - /// - /// ``` - #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_be_bytes();")] - #[doc = concat!("assert_eq!(bytes, ", $be_bytes, ");")] - /// ``` - #[stable(feature = "int_to_from_bytes", since = "1.32.0")] - #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn to_be_bytes(self) -> [u8; mem::size_of::()] { - self.to_be().to_ne_bytes() - } - - /// Return the memory representation of this integer as a byte array in - /// little-endian byte order. - /// - #[doc = $to_xe_bytes_doc] - /// - /// # Examples - /// - /// ``` - #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_le_bytes();")] - #[doc = concat!("assert_eq!(bytes, ", $le_bytes, ");")] - /// ``` - #[stable(feature = "int_to_from_bytes", since = "1.32.0")] - #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn to_le_bytes(self) -> [u8; mem::size_of::()] { - self.to_le().to_ne_bytes() - } - - /// Return the memory representation of this integer as a byte array in - /// native byte order. - /// - /// As the target platform's native endianness is used, portable code - /// should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate, - /// instead. - /// - #[doc = $to_xe_bytes_doc] - /// - /// [`to_be_bytes`]: Self::to_be_bytes - /// [`to_le_bytes`]: Self::to_le_bytes - /// - /// # Examples - /// - /// ``` - #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_ne_bytes();")] - /// assert_eq!( - /// bytes, - /// if cfg!(target_endian = "big") { - #[doc = concat!(" ", $be_bytes)] - /// } else { - #[doc = concat!(" ", $le_bytes)] - /// } - /// ); - /// ``` - #[stable(feature = "int_to_from_bytes", since = "1.32.0")] - #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")] - // SAFETY: const sound because integers are plain old datatypes so we can always - // transmute them to arrays of bytes - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn to_ne_bytes(self) -> [u8; mem::size_of::()] { - // SAFETY: integers are plain old datatypes so we can always transmute them to - // arrays of bytes - unsafe { mem::transmute(self) } - } - - /// Create an integer value from its representation as a byte array in - /// big endian. - /// - #[doc = $from_xe_bytes_doc] - /// - /// # Examples - /// - /// ``` - #[doc = concat!("let value = ", stringify!($SelfT), "::from_be_bytes(", $be_bytes, ");")] - #[doc = concat!("assert_eq!(value, ", $swap_op, ");")] - /// ``` - /// - /// When starting from a slice rather than an array, fallible conversion APIs can be used: - /// - /// ``` - #[doc = concat!("fn read_be_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")] - #[doc = concat!(" let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());")] - /// *input = rest; - #[doc = concat!(" ", stringify!($SelfT), "::from_be_bytes(int_bytes.try_into().unwrap())")] - /// } - /// ``` - #[stable(feature = "int_to_from_bytes", since = "1.32.0")] - #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")] - #[must_use] - #[inline] - pub const fn from_be_bytes(bytes: [u8; mem::size_of::()]) -> Self { - Self::from_be(Self::from_ne_bytes(bytes)) - } - - /// Create an integer value from its representation as a byte array in - /// little endian. - /// - #[doc = $from_xe_bytes_doc] - /// - /// # Examples - /// - /// ``` - #[doc = concat!("let value = ", stringify!($SelfT), "::from_le_bytes(", $le_bytes, ");")] - #[doc = concat!("assert_eq!(value, ", $swap_op, ");")] - /// ``` - /// - /// When starting from a slice rather than an array, fallible conversion APIs can be used: - /// - /// ``` - #[doc = concat!("fn read_le_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")] - #[doc = concat!(" let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());")] - /// *input = rest; - #[doc = concat!(" ", stringify!($SelfT), "::from_le_bytes(int_bytes.try_into().unwrap())")] - /// } - /// ``` - #[stable(feature = "int_to_from_bytes", since = "1.32.0")] - #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")] - #[must_use] - #[inline] - pub const fn from_le_bytes(bytes: [u8; mem::size_of::()]) -> Self { - Self::from_le(Self::from_ne_bytes(bytes)) - } - - /// Create an integer value from its memory representation as a byte - /// array in native endianness. - /// - /// As the target platform's native endianness is used, portable code - /// likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as - /// appropriate instead. - /// - /// [`from_be_bytes`]: Self::from_be_bytes - /// [`from_le_bytes`]: Self::from_le_bytes - /// - #[doc = $from_xe_bytes_doc] - /// - /// # Examples - /// - /// ``` - #[doc = concat!("let value = ", stringify!($SelfT), "::from_ne_bytes(if cfg!(target_endian = \"big\") {")] - #[doc = concat!(" ", $be_bytes)] - /// } else { - #[doc = concat!(" ", $le_bytes)] - /// }); - #[doc = concat!("assert_eq!(value, ", $swap_op, ");")] - /// ``` - /// - /// When starting from a slice rather than an array, fallible conversion APIs can be used: - /// - /// ``` - #[doc = concat!("fn read_ne_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")] - #[doc = concat!(" let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());")] - /// *input = rest; - #[doc = concat!(" ", stringify!($SelfT), "::from_ne_bytes(int_bytes.try_into().unwrap())")] - /// } - /// ``` - #[stable(feature = "int_to_from_bytes", since = "1.32.0")] - #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")] - #[must_use] - // SAFETY: const sound because integers are plain old datatypes so we can always - // transmute to them - #[inline] - pub const fn from_ne_bytes(bytes: [u8; mem::size_of::()]) -> Self { - // SAFETY: integers are plain old datatypes so we can always transmute to them - unsafe { mem::transmute(bytes) } - } - - /// New code should prefer to use - #[doc = concat!("[`", stringify!($SelfT), "::MIN", "`] instead.")] - /// - /// Returns the smallest value that can be represented by this integer type. - #[stable(feature = "rust1", since = "1.0.0")] - #[inline(always)] - #[rustc_promotable] - #[rustc_const_stable(feature = "const_min_value", since = "1.32.0")] - #[deprecated(since = "TBD", note = "replaced by the `MIN` associated constant on this type")] - #[rustc_diagnostic_item = concat!(stringify!($SelfT), "_legacy_fn_min_value")] - pub const fn min_value() -> Self { - Self::MIN - } - - /// New code should prefer to use - #[doc = concat!("[`", stringify!($SelfT), "::MAX", "`] instead.")] - /// - /// Returns the largest value that can be represented by this integer type. - #[stable(feature = "rust1", since = "1.0.0")] - #[inline(always)] - #[rustc_promotable] - #[rustc_const_stable(feature = "const_max_value", since = "1.32.0")] - #[deprecated(since = "TBD", note = "replaced by the `MAX` associated constant on this type")] - #[rustc_diagnostic_item = concat!(stringify!($SelfT), "_legacy_fn_max_value")] - pub const fn max_value() -> Self { - Self::MAX - } - } -} diff --git a/library/core/src/num/mod.rs b/library/core/src/num/mod.rs deleted file mode 100644 index 09a341e4d80ac..0000000000000 --- a/library/core/src/num/mod.rs +++ /dev/null @@ -1,1591 +0,0 @@ -//! Numeric traits and functions for the built-in numeric types. - -#![stable(feature = "rust1", since = "1.0.0")] - -use crate::ascii; -use crate::hint; -use crate::intrinsics; -use crate::mem; -use crate::str::FromStr; - -// Used because the `?` operator is not allowed in a const context. -macro_rules! try_opt { - ($e:expr) => { - match $e { - Some(x) => x, - None => return None, - } - }; -} - -#[allow_internal_unstable(const_likely)] -macro_rules! unlikely { - ($e: expr) => { - intrinsics::unlikely($e) - }; -} - -// All these modules are technically private and only exposed for coretests: -#[cfg(not(no_fp_fmt_parse))] -pub mod bignum; -#[cfg(not(no_fp_fmt_parse))] -pub mod dec2flt; -#[cfg(not(no_fp_fmt_parse))] -pub mod diy_float; -#[cfg(not(no_fp_fmt_parse))] -pub mod flt2dec; -pub mod fmt; - -#[macro_use] -mod int_macros; // import int_impl! -#[macro_use] -mod uint_macros; // import uint_impl! - -mod error; -mod int_log10; -mod nonzero; -mod overflow_panic; -mod saturating; -mod wrapping; - -#[stable(feature = "saturating_int_impl", since = "1.74.0")] -pub use saturating::Saturating; -#[stable(feature = "rust1", since = "1.0.0")] -pub use wrapping::Wrapping; - -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg(not(no_fp_fmt_parse))] -pub use dec2flt::ParseFloatError; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use error::ParseIntError; - -#[unstable( - feature = "nonzero_internals", - reason = "implementation detail which may disappear or be replaced at any time", - issue = "none" -)] -pub use nonzero::ZeroablePrimitive; - -#[stable(feature = "generic_nonzero", since = "1.79.0")] -pub use nonzero::NonZero; - -#[stable(feature = "signed_nonzero", since = "1.34.0")] -pub use nonzero::{NonZeroI128, NonZeroI16, NonZeroI32, NonZeroI64, NonZeroI8, NonZeroIsize}; - -#[stable(feature = "nonzero", since = "1.28.0")] -pub use nonzero::{NonZeroU128, NonZeroU16, NonZeroU32, NonZeroU64, NonZeroU8, NonZeroUsize}; - -#[stable(feature = "try_from", since = "1.34.0")] -pub use error::TryFromIntError; - -#[stable(feature = "int_error_matching", since = "1.55.0")] -pub use error::IntErrorKind; - -macro_rules! usize_isize_to_xe_bytes_doc { - () => { - " - -**Note**: This function returns an array of length 2, 4 or 8 bytes -depending on the target pointer size. - -" - }; -} - -macro_rules! usize_isize_from_xe_bytes_doc { - () => { - " - -**Note**: This function takes an array of length 2, 4 or 8 bytes -depending on the target pointer size. - -" - }; -} - -macro_rules! midpoint_impl { - ($SelfT:ty, unsigned) => { - /// Calculates the middle point of `self` and `rhs`. - /// - /// `midpoint(a, b)` is `(a + b) >> 1` as if it were performed in a - /// sufficiently-large signed integral type. This implies that the result is - /// always rounded towards negative infinity and that no overflow will ever occur. - /// - /// # Examples - /// - /// ``` - /// #![feature(num_midpoint)] - #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".midpoint(4), 2);")] - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".midpoint(4), 2);")] - /// ``` - #[unstable(feature = "num_midpoint", issue = "110840")] - #[rustc_const_unstable(feature = "const_num_midpoint", issue = "110840")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn midpoint(self, rhs: $SelfT) -> $SelfT { - // Use the well known branchless algorithm from Hacker's Delight to compute - // `(a + b) / 2` without overflowing: `((a ^ b) >> 1) + (a & b)`. - ((self ^ rhs) >> 1) + (self & rhs) - } - }; - ($SelfT:ty, $WideT:ty, unsigned) => { - /// Calculates the middle point of `self` and `rhs`. - /// - /// `midpoint(a, b)` is `(a + b) >> 1` as if it were performed in a - /// sufficiently-large signed integral type. This implies that the result is - /// always rounded towards negative infinity and that no overflow will ever occur. - /// - /// # Examples - /// - /// ``` - /// #![feature(num_midpoint)] - #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".midpoint(4), 2);")] - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".midpoint(4), 2);")] - /// ``` - #[unstable(feature = "num_midpoint", issue = "110840")] - #[rustc_const_unstable(feature = "const_num_midpoint", issue = "110840")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn midpoint(self, rhs: $SelfT) -> $SelfT { - ((self as $WideT + rhs as $WideT) / 2) as $SelfT - } - }; -} - -macro_rules! widening_impl { - ($SelfT:ty, $WideT:ty, $BITS:literal, unsigned) => { - /// Calculates the complete product `self * rhs` without the possibility to overflow. - /// - /// This returns the low-order (wrapping) bits and the high-order (overflow) bits - /// of the result as two separate values, in that order. - /// - /// If you also need to add a carry to the wide result, then you want - /// [`Self::carrying_mul`] instead. - /// - /// # Examples - /// - /// Basic usage: - /// - /// Please note that this example is shared between integer types. - /// Which explains why `u32` is used here. - /// - /// ``` - /// #![feature(bigint_helper_methods)] - /// assert_eq!(5u32.widening_mul(2), (10, 0)); - /// assert_eq!(1_000_000_000u32.widening_mul(10), (1410065408, 2)); - /// ``` - #[unstable(feature = "bigint_helper_methods", issue = "85532")] - #[rustc_const_unstable(feature = "const_bigint_helper_methods", issue = "85532")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn widening_mul(self, rhs: Self) -> (Self, Self) { - // note: longer-term this should be done via an intrinsic, - // but for now we can deal without an impl for u128/i128 - // SAFETY: overflow will be contained within the wider types - let wide = unsafe { (self as $WideT).unchecked_mul(rhs as $WideT) }; - (wide as $SelfT, (wide >> $BITS) as $SelfT) - } - - /// Calculates the "full multiplication" `self * rhs + carry` - /// without the possibility to overflow. - /// - /// This returns the low-order (wrapping) bits and the high-order (overflow) bits - /// of the result as two separate values, in that order. - /// - /// Performs "long multiplication" which takes in an extra amount to add, and may return an - /// additional amount of overflow. This allows for chaining together multiple - /// multiplications to create "big integers" which represent larger values. - /// - /// If you don't need the `carry`, then you can use [`Self::widening_mul`] instead. - /// - /// # Examples - /// - /// Basic usage: - /// - /// Please note that this example is shared between integer types. - /// Which explains why `u32` is used here. - /// - /// ``` - /// #![feature(bigint_helper_methods)] - /// assert_eq!(5u32.carrying_mul(2, 0), (10, 0)); - /// assert_eq!(5u32.carrying_mul(2, 10), (20, 0)); - /// assert_eq!(1_000_000_000u32.carrying_mul(10, 0), (1410065408, 2)); - /// assert_eq!(1_000_000_000u32.carrying_mul(10, 10), (1410065418, 2)); - #[doc = concat!("assert_eq!(", - stringify!($SelfT), "::MAX.carrying_mul(", stringify!($SelfT), "::MAX, ", stringify!($SelfT), "::MAX), ", - "(0, ", stringify!($SelfT), "::MAX));" - )] - /// ``` - /// - /// This is the core operation needed for scalar multiplication when - /// implementing it for wider-than-native types. - /// - /// ``` - /// #![feature(bigint_helper_methods)] - /// fn scalar_mul_eq(little_endian_digits: &mut Vec, multiplicand: u16) { - /// let mut carry = 0; - /// for d in little_endian_digits.iter_mut() { - /// (*d, carry) = d.carrying_mul(multiplicand, carry); - /// } - /// if carry != 0 { - /// little_endian_digits.push(carry); - /// } - /// } - /// - /// let mut v = vec![10, 20]; - /// scalar_mul_eq(&mut v, 3); - /// assert_eq!(v, [30, 60]); - /// - /// assert_eq!(0x87654321_u64 * 0xFEED, 0x86D3D159E38D); - /// let mut v = vec![0x4321, 0x8765]; - /// scalar_mul_eq(&mut v, 0xFEED); - /// assert_eq!(v, [0xE38D, 0xD159, 0x86D3]); - /// ``` - /// - /// If `carry` is zero, this is similar to [`overflowing_mul`](Self::overflowing_mul), - /// except that it gives the value of the overflow instead of just whether one happened: - /// - /// ``` - /// #![feature(bigint_helper_methods)] - /// let r = u8::carrying_mul(7, 13, 0); - /// assert_eq!((r.0, r.1 != 0), u8::overflowing_mul(7, 13)); - /// let r = u8::carrying_mul(13, 42, 0); - /// assert_eq!((r.0, r.1 != 0), u8::overflowing_mul(13, 42)); - /// ``` - /// - /// The value of the first field in the returned tuple matches what you'd get - /// by combining the [`wrapping_mul`](Self::wrapping_mul) and - /// [`wrapping_add`](Self::wrapping_add) methods: - /// - /// ``` - /// #![feature(bigint_helper_methods)] - /// assert_eq!( - /// 789_u16.carrying_mul(456, 123).0, - /// 789_u16.wrapping_mul(456).wrapping_add(123), - /// ); - /// ``` - #[unstable(feature = "bigint_helper_methods", issue = "85532")] - #[rustc_const_unstable(feature = "bigint_helper_methods", issue = "85532")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn carrying_mul(self, rhs: Self, carry: Self) -> (Self, Self) { - // note: longer-term this should be done via an intrinsic, - // but for now we can deal without an impl for u128/i128 - // SAFETY: overflow will be contained within the wider types - let wide = unsafe { - (self as $WideT).unchecked_mul(rhs as $WideT).unchecked_add(carry as $WideT) - }; - (wide as $SelfT, (wide >> $BITS) as $SelfT) - } - }; -} - -impl i8 { - int_impl! { - Self = i8, - ActualT = i8, - UnsignedT = u8, - BITS = 8, - BITS_MINUS_ONE = 7, - Min = -128, - Max = 127, - rot = 2, - rot_op = "-0x7e", - rot_result = "0xa", - swap_op = "0x12", - swapped = "0x12", - reversed = "0x48", - le_bytes = "[0x12]", - be_bytes = "[0x12]", - to_xe_bytes_doc = "", - from_xe_bytes_doc = "", - bound_condition = "", - } -} - -impl i16 { - int_impl! { - Self = i16, - ActualT = i16, - UnsignedT = u16, - BITS = 16, - BITS_MINUS_ONE = 15, - Min = -32768, - Max = 32767, - rot = 4, - rot_op = "-0x5ffd", - rot_result = "0x3a", - swap_op = "0x1234", - swapped = "0x3412", - reversed = "0x2c48", - le_bytes = "[0x34, 0x12]", - be_bytes = "[0x12, 0x34]", - to_xe_bytes_doc = "", - from_xe_bytes_doc = "", - bound_condition = "", - } -} - -impl i32 { - int_impl! { - Self = i32, - ActualT = i32, - UnsignedT = u32, - BITS = 32, - BITS_MINUS_ONE = 31, - Min = -2147483648, - Max = 2147483647, - rot = 8, - rot_op = "0x10000b3", - rot_result = "0xb301", - swap_op = "0x12345678", - swapped = "0x78563412", - reversed = "0x1e6a2c48", - le_bytes = "[0x78, 0x56, 0x34, 0x12]", - be_bytes = "[0x12, 0x34, 0x56, 0x78]", - to_xe_bytes_doc = "", - from_xe_bytes_doc = "", - bound_condition = "", - } -} - -impl i64 { - int_impl! { - Self = i64, - ActualT = i64, - UnsignedT = u64, - BITS = 64, - BITS_MINUS_ONE = 63, - Min = -9223372036854775808, - Max = 9223372036854775807, - rot = 12, - rot_op = "0xaa00000000006e1", - rot_result = "0x6e10aa", - swap_op = "0x1234567890123456", - swapped = "0x5634129078563412", - reversed = "0x6a2c48091e6a2c48", - le_bytes = "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]", - be_bytes = "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]", - to_xe_bytes_doc = "", - from_xe_bytes_doc = "", - bound_condition = "", - } -} - -impl i128 { - int_impl! { - Self = i128, - ActualT = i128, - UnsignedT = u128, - BITS = 128, - BITS_MINUS_ONE = 127, - Min = -170141183460469231731687303715884105728, - Max = 170141183460469231731687303715884105727, - rot = 16, - rot_op = "0x13f40000000000000000000000004f76", - rot_result = "0x4f7613f4", - swap_op = "0x12345678901234567890123456789012", - swapped = "0x12907856341290785634129078563412", - reversed = "0x48091e6a2c48091e6a2c48091e6a2c48", - le_bytes = "[0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, \ - 0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]", - be_bytes = "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, \ - 0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]", - to_xe_bytes_doc = "", - from_xe_bytes_doc = "", - bound_condition = "", - } -} - -#[cfg(target_pointer_width = "16")] -impl isize { - int_impl! { - Self = isize, - ActualT = i16, - UnsignedT = usize, - BITS = 16, - BITS_MINUS_ONE = 15, - Min = -32768, - Max = 32767, - rot = 4, - rot_op = "-0x5ffd", - rot_result = "0x3a", - swap_op = "0x1234", - swapped = "0x3412", - reversed = "0x2c48", - le_bytes = "[0x34, 0x12]", - be_bytes = "[0x12, 0x34]", - to_xe_bytes_doc = usize_isize_to_xe_bytes_doc!(), - from_xe_bytes_doc = usize_isize_from_xe_bytes_doc!(), - bound_condition = " on 16-bit targets", - } -} - -#[cfg(target_pointer_width = "32")] -impl isize { - int_impl! { - Self = isize, - ActualT = i32, - UnsignedT = usize, - BITS = 32, - BITS_MINUS_ONE = 31, - Min = -2147483648, - Max = 2147483647, - rot = 8, - rot_op = "0x10000b3", - rot_result = "0xb301", - swap_op = "0x12345678", - swapped = "0x78563412", - reversed = "0x1e6a2c48", - le_bytes = "[0x78, 0x56, 0x34, 0x12]", - be_bytes = "[0x12, 0x34, 0x56, 0x78]", - to_xe_bytes_doc = usize_isize_to_xe_bytes_doc!(), - from_xe_bytes_doc = usize_isize_from_xe_bytes_doc!(), - bound_condition = " on 32-bit targets", - } -} - -#[cfg(target_pointer_width = "64")] -impl isize { - int_impl! { - Self = isize, - ActualT = i64, - UnsignedT = usize, - BITS = 64, - BITS_MINUS_ONE = 63, - Min = -9223372036854775808, - Max = 9223372036854775807, - rot = 12, - rot_op = "0xaa00000000006e1", - rot_result = "0x6e10aa", - swap_op = "0x1234567890123456", - swapped = "0x5634129078563412", - reversed = "0x6a2c48091e6a2c48", - le_bytes = "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]", - be_bytes = "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]", - to_xe_bytes_doc = usize_isize_to_xe_bytes_doc!(), - from_xe_bytes_doc = usize_isize_from_xe_bytes_doc!(), - bound_condition = " on 64-bit targets", - } -} - -/// If the 6th bit is set ascii is lower case. -const ASCII_CASE_MASK: u8 = 0b0010_0000; - -impl u8 { - uint_impl! { - Self = u8, - ActualT = u8, - SignedT = i8, - NonZeroT = NonZero, - BITS = 8, - MAX = 255, - rot = 2, - rot_op = "0x82", - rot_result = "0xa", - swap_op = "0x12", - swapped = "0x12", - reversed = "0x48", - le_bytes = "[0x12]", - be_bytes = "[0x12]", - to_xe_bytes_doc = "", - from_xe_bytes_doc = "", - bound_condition = "", - } - widening_impl! { u8, u16, 8, unsigned } - midpoint_impl! { u8, u16, unsigned } - - /// Checks if the value is within the ASCII range. - /// - /// # Examples - /// - /// ``` - /// let ascii = 97u8; - /// let non_ascii = 150u8; - /// - /// assert!(ascii.is_ascii()); - /// assert!(!non_ascii.is_ascii()); - /// ``` - #[must_use] - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[rustc_const_stable(feature = "const_u8_is_ascii", since = "1.43.0")] - #[inline] - pub const fn is_ascii(&self) -> bool { - *self <= 127 - } - - /// If the value of this byte is within the ASCII range, returns it as an - /// [ASCII character](ascii::Char). Otherwise, returns `None`. - #[must_use] - #[unstable(feature = "ascii_char", issue = "110998")] - #[inline] - pub const fn as_ascii(&self) -> Option { - ascii::Char::from_u8(*self) - } - - /// Makes a copy of the value in its ASCII upper case equivalent. - /// - /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', - /// but non-ASCII letters are unchanged. - /// - /// To uppercase the value in-place, use [`make_ascii_uppercase`]. - /// - /// # Examples - /// - /// ``` - /// let lowercase_a = 97u8; - /// - /// assert_eq!(65, lowercase_a.to_ascii_uppercase()); - /// ``` - /// - /// [`make_ascii_uppercase`]: Self::make_ascii_uppercase - #[must_use = "to uppercase the value in-place, use `make_ascii_uppercase()`"] - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")] - #[inline] - pub const fn to_ascii_uppercase(&self) -> u8 { - // Toggle the 6th bit if this is a lowercase letter - *self ^ ((self.is_ascii_lowercase() as u8) * ASCII_CASE_MASK) - } - - /// Makes a copy of the value in its ASCII lower case equivalent. - /// - /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', - /// but non-ASCII letters are unchanged. - /// - /// To lowercase the value in-place, use [`make_ascii_lowercase`]. - /// - /// # Examples - /// - /// ``` - /// let uppercase_a = 65u8; - /// - /// assert_eq!(97, uppercase_a.to_ascii_lowercase()); - /// ``` - /// - /// [`make_ascii_lowercase`]: Self::make_ascii_lowercase - #[must_use = "to lowercase the value in-place, use `make_ascii_lowercase()`"] - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")] - #[inline] - pub const fn to_ascii_lowercase(&self) -> u8 { - // Set the 6th bit if this is an uppercase letter - *self | (self.is_ascii_uppercase() as u8 * ASCII_CASE_MASK) - } - - /// Assumes self is ascii - #[inline] - pub(crate) const fn ascii_change_case_unchecked(&self) -> u8 { - *self ^ ASCII_CASE_MASK - } - - /// Checks that two values are an ASCII case-insensitive match. - /// - /// This is equivalent to `to_ascii_lowercase(a) == to_ascii_lowercase(b)`. - /// - /// # Examples - /// - /// ``` - /// let lowercase_a = 97u8; - /// let uppercase_a = 65u8; - /// - /// assert!(lowercase_a.eq_ignore_ascii_case(&uppercase_a)); - /// ``` - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[rustc_const_stable(feature = "const_ascii_methods_on_intrinsics", since = "1.52.0")] - #[inline] - pub const fn eq_ignore_ascii_case(&self, other: &u8) -> bool { - self.to_ascii_lowercase() == other.to_ascii_lowercase() - } - - /// Converts this value to its ASCII upper case equivalent in-place. - /// - /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', - /// but non-ASCII letters are unchanged. - /// - /// To return a new uppercased value without modifying the existing one, use - /// [`to_ascii_uppercase`]. - /// - /// # Examples - /// - /// ``` - /// let mut byte = b'a'; - /// - /// byte.make_ascii_uppercase(); - /// - /// assert_eq!(b'A', byte); - /// ``` - /// - /// [`to_ascii_uppercase`]: Self::to_ascii_uppercase - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[inline] - pub fn make_ascii_uppercase(&mut self) { - *self = self.to_ascii_uppercase(); - } - - /// Converts this value to its ASCII lower case equivalent in-place. - /// - /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', - /// but non-ASCII letters are unchanged. - /// - /// To return a new lowercased value without modifying the existing one, use - /// [`to_ascii_lowercase`]. - /// - /// # Examples - /// - /// ``` - /// let mut byte = b'A'; - /// - /// byte.make_ascii_lowercase(); - /// - /// assert_eq!(b'a', byte); - /// ``` - /// - /// [`to_ascii_lowercase`]: Self::to_ascii_lowercase - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[inline] - pub fn make_ascii_lowercase(&mut self) { - *self = self.to_ascii_lowercase(); - } - - /// Checks if the value is an ASCII alphabetic character: - /// - /// - U+0041 'A' ..= U+005A 'Z', or - /// - U+0061 'a' ..= U+007A 'z'. - /// - /// # Examples - /// - /// ``` - /// let uppercase_a = b'A'; - /// let uppercase_g = b'G'; - /// let a = b'a'; - /// let g = b'g'; - /// let zero = b'0'; - /// let percent = b'%'; - /// let space = b' '; - /// let lf = b'\n'; - /// let esc = b'\x1b'; - /// - /// assert!(uppercase_a.is_ascii_alphabetic()); - /// assert!(uppercase_g.is_ascii_alphabetic()); - /// assert!(a.is_ascii_alphabetic()); - /// assert!(g.is_ascii_alphabetic()); - /// assert!(!zero.is_ascii_alphabetic()); - /// assert!(!percent.is_ascii_alphabetic()); - /// assert!(!space.is_ascii_alphabetic()); - /// assert!(!lf.is_ascii_alphabetic()); - /// assert!(!esc.is_ascii_alphabetic()); - /// ``` - #[must_use] - #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")] - #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")] - #[inline] - pub const fn is_ascii_alphabetic(&self) -> bool { - matches!(*self, b'A'..=b'Z' | b'a'..=b'z') - } - - /// Checks if the value is an ASCII uppercase character: - /// U+0041 'A' ..= U+005A 'Z'. - /// - /// # Examples - /// - /// ``` - /// let uppercase_a = b'A'; - /// let uppercase_g = b'G'; - /// let a = b'a'; - /// let g = b'g'; - /// let zero = b'0'; - /// let percent = b'%'; - /// let space = b' '; - /// let lf = b'\n'; - /// let esc = b'\x1b'; - /// - /// assert!(uppercase_a.is_ascii_uppercase()); - /// assert!(uppercase_g.is_ascii_uppercase()); - /// assert!(!a.is_ascii_uppercase()); - /// assert!(!g.is_ascii_uppercase()); - /// assert!(!zero.is_ascii_uppercase()); - /// assert!(!percent.is_ascii_uppercase()); - /// assert!(!space.is_ascii_uppercase()); - /// assert!(!lf.is_ascii_uppercase()); - /// assert!(!esc.is_ascii_uppercase()); - /// ``` - #[must_use] - #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")] - #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")] - #[inline] - pub const fn is_ascii_uppercase(&self) -> bool { - matches!(*self, b'A'..=b'Z') - } - - /// Checks if the value is an ASCII lowercase character: - /// U+0061 'a' ..= U+007A 'z'. - /// - /// # Examples - /// - /// ``` - /// let uppercase_a = b'A'; - /// let uppercase_g = b'G'; - /// let a = b'a'; - /// let g = b'g'; - /// let zero = b'0'; - /// let percent = b'%'; - /// let space = b' '; - /// let lf = b'\n'; - /// let esc = b'\x1b'; - /// - /// assert!(!uppercase_a.is_ascii_lowercase()); - /// assert!(!uppercase_g.is_ascii_lowercase()); - /// assert!(a.is_ascii_lowercase()); - /// assert!(g.is_ascii_lowercase()); - /// assert!(!zero.is_ascii_lowercase()); - /// assert!(!percent.is_ascii_lowercase()); - /// assert!(!space.is_ascii_lowercase()); - /// assert!(!lf.is_ascii_lowercase()); - /// assert!(!esc.is_ascii_lowercase()); - /// ``` - #[must_use] - #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")] - #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")] - #[inline] - pub const fn is_ascii_lowercase(&self) -> bool { - matches!(*self, b'a'..=b'z') - } - - /// Checks if the value is an ASCII alphanumeric character: - /// - /// - U+0041 'A' ..= U+005A 'Z', or - /// - U+0061 'a' ..= U+007A 'z', or - /// - U+0030 '0' ..= U+0039 '9'. - /// - /// # Examples - /// - /// ``` - /// let uppercase_a = b'A'; - /// let uppercase_g = b'G'; - /// let a = b'a'; - /// let g = b'g'; - /// let zero = b'0'; - /// let percent = b'%'; - /// let space = b' '; - /// let lf = b'\n'; - /// let esc = b'\x1b'; - /// - /// assert!(uppercase_a.is_ascii_alphanumeric()); - /// assert!(uppercase_g.is_ascii_alphanumeric()); - /// assert!(a.is_ascii_alphanumeric()); - /// assert!(g.is_ascii_alphanumeric()); - /// assert!(zero.is_ascii_alphanumeric()); - /// assert!(!percent.is_ascii_alphanumeric()); - /// assert!(!space.is_ascii_alphanumeric()); - /// assert!(!lf.is_ascii_alphanumeric()); - /// assert!(!esc.is_ascii_alphanumeric()); - /// ``` - #[must_use] - #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")] - #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")] - #[inline] - pub const fn is_ascii_alphanumeric(&self) -> bool { - matches!(*self, b'0'..=b'9') | matches!(*self, b'A'..=b'Z') | matches!(*self, b'a'..=b'z') - } - - /// Checks if the value is an ASCII decimal digit: - /// U+0030 '0' ..= U+0039 '9'. - /// - /// # Examples - /// - /// ``` - /// let uppercase_a = b'A'; - /// let uppercase_g = b'G'; - /// let a = b'a'; - /// let g = b'g'; - /// let zero = b'0'; - /// let percent = b'%'; - /// let space = b' '; - /// let lf = b'\n'; - /// let esc = b'\x1b'; - /// - /// assert!(!uppercase_a.is_ascii_digit()); - /// assert!(!uppercase_g.is_ascii_digit()); - /// assert!(!a.is_ascii_digit()); - /// assert!(!g.is_ascii_digit()); - /// assert!(zero.is_ascii_digit()); - /// assert!(!percent.is_ascii_digit()); - /// assert!(!space.is_ascii_digit()); - /// assert!(!lf.is_ascii_digit()); - /// assert!(!esc.is_ascii_digit()); - /// ``` - #[must_use] - #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")] - #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")] - #[inline] - pub const fn is_ascii_digit(&self) -> bool { - matches!(*self, b'0'..=b'9') - } - - /// Checks if the value is an ASCII octal digit: - /// U+0030 '0' ..= U+0037 '7'. - /// - /// # Examples - /// - /// ``` - /// #![feature(is_ascii_octdigit)] - /// - /// let uppercase_a = b'A'; - /// let a = b'a'; - /// let zero = b'0'; - /// let seven = b'7'; - /// let nine = b'9'; - /// let percent = b'%'; - /// let lf = b'\n'; - /// - /// assert!(!uppercase_a.is_ascii_octdigit()); - /// assert!(!a.is_ascii_octdigit()); - /// assert!(zero.is_ascii_octdigit()); - /// assert!(seven.is_ascii_octdigit()); - /// assert!(!nine.is_ascii_octdigit()); - /// assert!(!percent.is_ascii_octdigit()); - /// assert!(!lf.is_ascii_octdigit()); - /// ``` - #[must_use] - #[unstable(feature = "is_ascii_octdigit", issue = "101288")] - #[rustc_const_unstable(feature = "is_ascii_octdigit", issue = "101288")] - #[inline] - pub const fn is_ascii_octdigit(&self) -> bool { - matches!(*self, b'0'..=b'7') - } - - /// Checks if the value is an ASCII hexadecimal digit: - /// - /// - U+0030 '0' ..= U+0039 '9', or - /// - U+0041 'A' ..= U+0046 'F', or - /// - U+0061 'a' ..= U+0066 'f'. - /// - /// # Examples - /// - /// ``` - /// let uppercase_a = b'A'; - /// let uppercase_g = b'G'; - /// let a = b'a'; - /// let g = b'g'; - /// let zero = b'0'; - /// let percent = b'%'; - /// let space = b' '; - /// let lf = b'\n'; - /// let esc = b'\x1b'; - /// - /// assert!(uppercase_a.is_ascii_hexdigit()); - /// assert!(!uppercase_g.is_ascii_hexdigit()); - /// assert!(a.is_ascii_hexdigit()); - /// assert!(!g.is_ascii_hexdigit()); - /// assert!(zero.is_ascii_hexdigit()); - /// assert!(!percent.is_ascii_hexdigit()); - /// assert!(!space.is_ascii_hexdigit()); - /// assert!(!lf.is_ascii_hexdigit()); - /// assert!(!esc.is_ascii_hexdigit()); - /// ``` - #[must_use] - #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")] - #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")] - #[inline] - pub const fn is_ascii_hexdigit(&self) -> bool { - matches!(*self, b'0'..=b'9') | matches!(*self, b'A'..=b'F') | matches!(*self, b'a'..=b'f') - } - - /// Checks if the value is an ASCII punctuation character: - /// - /// - U+0021 ..= U+002F `! " # $ % & ' ( ) * + , - . /`, or - /// - U+003A ..= U+0040 `: ; < = > ? @`, or - /// - U+005B ..= U+0060 `` [ \ ] ^ _ ` ``, or - /// - U+007B ..= U+007E `{ | } ~` - /// - /// # Examples - /// - /// ``` - /// let uppercase_a = b'A'; - /// let uppercase_g = b'G'; - /// let a = b'a'; - /// let g = b'g'; - /// let zero = b'0'; - /// let percent = b'%'; - /// let space = b' '; - /// let lf = b'\n'; - /// let esc = b'\x1b'; - /// - /// assert!(!uppercase_a.is_ascii_punctuation()); - /// assert!(!uppercase_g.is_ascii_punctuation()); - /// assert!(!a.is_ascii_punctuation()); - /// assert!(!g.is_ascii_punctuation()); - /// assert!(!zero.is_ascii_punctuation()); - /// assert!(percent.is_ascii_punctuation()); - /// assert!(!space.is_ascii_punctuation()); - /// assert!(!lf.is_ascii_punctuation()); - /// assert!(!esc.is_ascii_punctuation()); - /// ``` - #[must_use] - #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")] - #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")] - #[inline] - pub const fn is_ascii_punctuation(&self) -> bool { - matches!(*self, b'!'..=b'/') - | matches!(*self, b':'..=b'@') - | matches!(*self, b'['..=b'`') - | matches!(*self, b'{'..=b'~') - } - - /// Checks if the value is an ASCII graphic character: - /// U+0021 '!' ..= U+007E '~'. - /// - /// # Examples - /// - /// ``` - /// let uppercase_a = b'A'; - /// let uppercase_g = b'G'; - /// let a = b'a'; - /// let g = b'g'; - /// let zero = b'0'; - /// let percent = b'%'; - /// let space = b' '; - /// let lf = b'\n'; - /// let esc = b'\x1b'; - /// - /// assert!(uppercase_a.is_ascii_graphic()); - /// assert!(uppercase_g.is_ascii_graphic()); - /// assert!(a.is_ascii_graphic()); - /// assert!(g.is_ascii_graphic()); - /// assert!(zero.is_ascii_graphic()); - /// assert!(percent.is_ascii_graphic()); - /// assert!(!space.is_ascii_graphic()); - /// assert!(!lf.is_ascii_graphic()); - /// assert!(!esc.is_ascii_graphic()); - /// ``` - #[must_use] - #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")] - #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")] - #[inline] - pub const fn is_ascii_graphic(&self) -> bool { - matches!(*self, b'!'..=b'~') - } - - /// Checks if the value is an ASCII whitespace character: - /// U+0020 SPACE, U+0009 HORIZONTAL TAB, U+000A LINE FEED, - /// U+000C FORM FEED, or U+000D CARRIAGE RETURN. - /// - /// Rust uses the WhatWG Infra Standard's [definition of ASCII - /// whitespace][infra-aw]. There are several other definitions in - /// wide use. For instance, [the POSIX locale][pct] includes - /// U+000B VERTICAL TAB as well as all the above characters, - /// but—from the very same specification—[the default rule for - /// "field splitting" in the Bourne shell][bfs] considers *only* - /// SPACE, HORIZONTAL TAB, and LINE FEED as whitespace. - /// - /// If you are writing a program that will process an existing - /// file format, check what that format's definition of whitespace is - /// before using this function. - /// - /// [infra-aw]: https://infra.spec.whatwg.org/#ascii-whitespace - /// [pct]: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html#tag_07_03_01 - /// [bfs]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_06_05 - /// - /// # Examples - /// - /// ``` - /// let uppercase_a = b'A'; - /// let uppercase_g = b'G'; - /// let a = b'a'; - /// let g = b'g'; - /// let zero = b'0'; - /// let percent = b'%'; - /// let space = b' '; - /// let lf = b'\n'; - /// let esc = b'\x1b'; - /// - /// assert!(!uppercase_a.is_ascii_whitespace()); - /// assert!(!uppercase_g.is_ascii_whitespace()); - /// assert!(!a.is_ascii_whitespace()); - /// assert!(!g.is_ascii_whitespace()); - /// assert!(!zero.is_ascii_whitespace()); - /// assert!(!percent.is_ascii_whitespace()); - /// assert!(space.is_ascii_whitespace()); - /// assert!(lf.is_ascii_whitespace()); - /// assert!(!esc.is_ascii_whitespace()); - /// ``` - #[must_use] - #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")] - #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")] - #[inline] - pub const fn is_ascii_whitespace(&self) -> bool { - matches!(*self, b'\t' | b'\n' | b'\x0C' | b'\r' | b' ') - } - - /// Checks if the value is an ASCII control character: - /// U+0000 NUL ..= U+001F UNIT SEPARATOR, or U+007F DELETE. - /// Note that most ASCII whitespace characters are control - /// characters, but SPACE is not. - /// - /// # Examples - /// - /// ``` - /// let uppercase_a = b'A'; - /// let uppercase_g = b'G'; - /// let a = b'a'; - /// let g = b'g'; - /// let zero = b'0'; - /// let percent = b'%'; - /// let space = b' '; - /// let lf = b'\n'; - /// let esc = b'\x1b'; - /// - /// assert!(!uppercase_a.is_ascii_control()); - /// assert!(!uppercase_g.is_ascii_control()); - /// assert!(!a.is_ascii_control()); - /// assert!(!g.is_ascii_control()); - /// assert!(!zero.is_ascii_control()); - /// assert!(!percent.is_ascii_control()); - /// assert!(!space.is_ascii_control()); - /// assert!(lf.is_ascii_control()); - /// assert!(esc.is_ascii_control()); - /// ``` - #[must_use] - #[stable(feature = "ascii_ctype_on_intrinsics", since = "1.24.0")] - #[rustc_const_stable(feature = "const_ascii_ctype_on_intrinsics", since = "1.47.0")] - #[inline] - pub const fn is_ascii_control(&self) -> bool { - matches!(*self, b'\0'..=b'\x1F' | b'\x7F') - } - - /// Returns an iterator that produces an escaped version of a `u8`, - /// treating it as an ASCII character. - /// - /// The behavior is identical to [`ascii::escape_default`]. - /// - /// # Examples - /// - /// ``` - /// - /// assert_eq!("0", b'0'.escape_ascii().to_string()); - /// assert_eq!("\\t", b'\t'.escape_ascii().to_string()); - /// assert_eq!("\\r", b'\r'.escape_ascii().to_string()); - /// assert_eq!("\\n", b'\n'.escape_ascii().to_string()); - /// assert_eq!("\\'", b'\''.escape_ascii().to_string()); - /// assert_eq!("\\\"", b'"'.escape_ascii().to_string()); - /// assert_eq!("\\\\", b'\\'.escape_ascii().to_string()); - /// assert_eq!("\\x9d", b'\x9d'.escape_ascii().to_string()); - /// ``` - #[must_use = "this returns the escaped byte as an iterator, \ - without modifying the original"] - #[stable(feature = "inherent_ascii_escape", since = "1.60.0")] - #[inline] - pub fn escape_ascii(self) -> ascii::EscapeDefault { - ascii::escape_default(self) - } - - #[inline] - pub(crate) const fn is_utf8_char_boundary(self) -> bool { - // This is bit magic equivalent to: b < 128 || b >= 192 - (self as i8) >= -0x40 - } -} - -impl u16 { - uint_impl! { - Self = u16, - ActualT = u16, - SignedT = i16, - NonZeroT = NonZero, - BITS = 16, - MAX = 65535, - rot = 4, - rot_op = "0xa003", - rot_result = "0x3a", - swap_op = "0x1234", - swapped = "0x3412", - reversed = "0x2c48", - le_bytes = "[0x34, 0x12]", - be_bytes = "[0x12, 0x34]", - to_xe_bytes_doc = "", - from_xe_bytes_doc = "", - bound_condition = "", - } - widening_impl! { u16, u32, 16, unsigned } - midpoint_impl! { u16, u32, unsigned } - - /// Checks if the value is a Unicode surrogate code point, which are disallowed values for [`char`]. - /// - /// # Examples - /// - /// ``` - /// #![feature(utf16_extra)] - /// - /// let low_non_surrogate = 0xA000u16; - /// let low_surrogate = 0xD800u16; - /// let high_surrogate = 0xDC00u16; - /// let high_non_surrogate = 0xE000u16; - /// - /// assert!(!low_non_surrogate.is_utf16_surrogate()); - /// assert!(low_surrogate.is_utf16_surrogate()); - /// assert!(high_surrogate.is_utf16_surrogate()); - /// assert!(!high_non_surrogate.is_utf16_surrogate()); - /// ``` - #[must_use] - #[unstable(feature = "utf16_extra", issue = "94919")] - #[rustc_const_unstable(feature = "utf16_extra_const", issue = "94919")] - #[inline] - pub const fn is_utf16_surrogate(self) -> bool { - matches!(self, 0xD800..=0xDFFF) - } -} - -impl u32 { - uint_impl! { - Self = u32, - ActualT = u32, - SignedT = i32, - NonZeroT = NonZero, - BITS = 32, - MAX = 4294967295, - rot = 8, - rot_op = "0x10000b3", - rot_result = "0xb301", - swap_op = "0x12345678", - swapped = "0x78563412", - reversed = "0x1e6a2c48", - le_bytes = "[0x78, 0x56, 0x34, 0x12]", - be_bytes = "[0x12, 0x34, 0x56, 0x78]", - to_xe_bytes_doc = "", - from_xe_bytes_doc = "", - bound_condition = "", - } - widening_impl! { u32, u64, 32, unsigned } - midpoint_impl! { u32, u64, unsigned } -} - -impl u64 { - uint_impl! { - Self = u64, - ActualT = u64, - SignedT = i64, - NonZeroT = NonZero, - BITS = 64, - MAX = 18446744073709551615, - rot = 12, - rot_op = "0xaa00000000006e1", - rot_result = "0x6e10aa", - swap_op = "0x1234567890123456", - swapped = "0x5634129078563412", - reversed = "0x6a2c48091e6a2c48", - le_bytes = "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]", - be_bytes = "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]", - to_xe_bytes_doc = "", - from_xe_bytes_doc = "", - bound_condition = "", - } - widening_impl! { u64, u128, 64, unsigned } - midpoint_impl! { u64, u128, unsigned } -} - -impl u128 { - uint_impl! { - Self = u128, - ActualT = u128, - SignedT = i128, - NonZeroT = NonZero, - BITS = 128, - MAX = 340282366920938463463374607431768211455, - rot = 16, - rot_op = "0x13f40000000000000000000000004f76", - rot_result = "0x4f7613f4", - swap_op = "0x12345678901234567890123456789012", - swapped = "0x12907856341290785634129078563412", - reversed = "0x48091e6a2c48091e6a2c48091e6a2c48", - le_bytes = "[0x12, 0x90, 0x78, 0x56, 0x34, 0x12, 0x90, 0x78, \ - 0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]", - be_bytes = "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56, \ - 0x78, 0x90, 0x12, 0x34, 0x56, 0x78, 0x90, 0x12]", - to_xe_bytes_doc = "", - from_xe_bytes_doc = "", - bound_condition = "", - } - midpoint_impl! { u128, unsigned } -} - -#[cfg(target_pointer_width = "16")] -impl usize { - uint_impl! { - Self = usize, - ActualT = u16, - SignedT = isize, - NonZeroT = NonZero, - BITS = 16, - MAX = 65535, - rot = 4, - rot_op = "0xa003", - rot_result = "0x3a", - swap_op = "0x1234", - swapped = "0x3412", - reversed = "0x2c48", - le_bytes = "[0x34, 0x12]", - be_bytes = "[0x12, 0x34]", - to_xe_bytes_doc = usize_isize_to_xe_bytes_doc!(), - from_xe_bytes_doc = usize_isize_from_xe_bytes_doc!(), - bound_condition = " on 16-bit targets", - } - widening_impl! { usize, u32, 16, unsigned } - midpoint_impl! { usize, u32, unsigned } -} - -#[cfg(target_pointer_width = "32")] -impl usize { - uint_impl! { - Self = usize, - ActualT = u32, - SignedT = isize, - NonZeroT = NonZero, - BITS = 32, - MAX = 4294967295, - rot = 8, - rot_op = "0x10000b3", - rot_result = "0xb301", - swap_op = "0x12345678", - swapped = "0x78563412", - reversed = "0x1e6a2c48", - le_bytes = "[0x78, 0x56, 0x34, 0x12]", - be_bytes = "[0x12, 0x34, 0x56, 0x78]", - to_xe_bytes_doc = usize_isize_to_xe_bytes_doc!(), - from_xe_bytes_doc = usize_isize_from_xe_bytes_doc!(), - bound_condition = " on 32-bit targets", - } - widening_impl! { usize, u64, 32, unsigned } - midpoint_impl! { usize, u64, unsigned } -} - -#[cfg(target_pointer_width = "64")] -impl usize { - uint_impl! { - Self = usize, - ActualT = u64, - SignedT = isize, - NonZeroT = NonZero, - BITS = 64, - MAX = 18446744073709551615, - rot = 12, - rot_op = "0xaa00000000006e1", - rot_result = "0x6e10aa", - swap_op = "0x1234567890123456", - swapped = "0x5634129078563412", - reversed = "0x6a2c48091e6a2c48", - le_bytes = "[0x56, 0x34, 0x12, 0x90, 0x78, 0x56, 0x34, 0x12]", - be_bytes = "[0x12, 0x34, 0x56, 0x78, 0x90, 0x12, 0x34, 0x56]", - to_xe_bytes_doc = usize_isize_to_xe_bytes_doc!(), - from_xe_bytes_doc = usize_isize_from_xe_bytes_doc!(), - bound_condition = " on 64-bit targets", - } - widening_impl! { usize, u128, 64, unsigned } - midpoint_impl! { usize, u128, unsigned } -} - -impl usize { - /// Returns an `usize` where every byte is equal to `x`. - #[inline] - pub(crate) const fn repeat_u8(x: u8) -> usize { - usize::from_ne_bytes([x; mem::size_of::()]) - } - - /// Returns an `usize` where every byte pair is equal to `x`. - #[inline] - pub(crate) const fn repeat_u16(x: u16) -> usize { - let mut r = 0usize; - let mut i = 0; - while i < mem::size_of::() { - // Use `wrapping_shl` to make it work on targets with 16-bit `usize` - r = r.wrapping_shl(16) | (x as usize); - i += 2; - } - r - } -} - -/// A classification of floating point numbers. -/// -/// This `enum` is used as the return type for [`f32::classify`] and [`f64::classify`]. See -/// their documentation for more. -/// -/// # Examples -/// -/// ``` -/// use std::num::FpCategory; -/// -/// let num = 12.4_f32; -/// let inf = f32::INFINITY; -/// let zero = 0f32; -/// let sub: f32 = 1.1754942e-38; -/// let nan = f32::NAN; -/// -/// assert_eq!(num.classify(), FpCategory::Normal); -/// assert_eq!(inf.classify(), FpCategory::Infinite); -/// assert_eq!(zero.classify(), FpCategory::Zero); -/// assert_eq!(sub.classify(), FpCategory::Subnormal); -/// assert_eq!(nan.classify(), FpCategory::Nan); -/// ``` -#[derive(Copy, Clone, PartialEq, Eq, Debug)] -#[stable(feature = "rust1", since = "1.0.0")] -pub enum FpCategory { - /// NaN (not a number): this value results from calculations like `(-1.0).sqrt()`. - /// - /// See [the documentation for `f32`](f32) for more information on the unusual properties - /// of NaN. - #[stable(feature = "rust1", since = "1.0.0")] - Nan, - - /// Positive or negative infinity, which often results from dividing a nonzero number - /// by zero. - #[stable(feature = "rust1", since = "1.0.0")] - Infinite, - - /// Positive or negative zero. - /// - /// See [the documentation for `f32`](f32) for more information on the signedness of zeroes. - #[stable(feature = "rust1", since = "1.0.0")] - Zero, - - /// “Subnormal” or “denormal” floating point representation (less precise, relative to - /// their magnitude, than [`Normal`]). - /// - /// Subnormal numbers are larger in magnitude than [`Zero`] but smaller in magnitude than all - /// [`Normal`] numbers. - /// - /// [`Normal`]: Self::Normal - /// [`Zero`]: Self::Zero - #[stable(feature = "rust1", since = "1.0.0")] - Subnormal, - - /// A regular floating point number, not any of the exceptional categories. - /// - /// The smallest positive normal numbers are [`f32::MIN_POSITIVE`] and [`f64::MIN_POSITIVE`], - /// and the largest positive normal numbers are [`f32::MAX`] and [`f64::MAX`]. (Unlike signed - /// integers, floating point numbers are symmetric in their range, so negating any of these - /// constants will produce their negative counterpart.) - #[stable(feature = "rust1", since = "1.0.0")] - Normal, -} - -macro_rules! from_str_radix_int_impl { - ($($t:ty)*) => {$( - #[stable(feature = "rust1", since = "1.0.0")] - impl FromStr for $t { - type Err = ParseIntError; - fn from_str(src: &str) -> Result { - <$t>::from_str_radix(src, 10) - } - } - )*} -} -from_str_radix_int_impl! { isize i8 i16 i32 i64 i128 usize u8 u16 u32 u64 u128 } - -/// Determines if a string of text of that length of that radix could be guaranteed to be -/// stored in the given type T. -/// Note that if the radix is known to the compiler, it is just the check of digits.len that -/// is done at runtime. -#[doc(hidden)] -#[inline(always)] -#[unstable(issue = "none", feature = "std_internals")] -pub const fn can_not_overflow(radix: u32, is_signed_ty: bool, digits: &[u8]) -> bool { - radix <= 16 && digits.len() <= mem::size_of::() * 2 - is_signed_ty as usize -} - -#[track_caller] -const fn from_str_radix_panic_ct(_radix: u32) -> ! { - panic!("from_str_radix_int: must lie in the range `[2, 36]`"); -} - -#[track_caller] -fn from_str_radix_panic_rt(radix: u32) -> ! { - panic!("from_str_radix_int: must lie in the range `[2, 36]` - found {}", radix); -} - -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never))] -#[cfg_attr(feature = "panic_immediate_abort", inline)] -#[cold] -#[track_caller] -const fn from_str_radix_panic(radix: u32) { - // The only difference between these two functions is their panic message. - intrinsics::const_eval_select((radix,), from_str_radix_panic_ct, from_str_radix_panic_rt); -} - -macro_rules! from_str_radix { - ($($int_ty:ty)+) => {$( - impl $int_ty { - /// Converts a string slice in a given base to an integer. - /// - /// The string is expected to be an optional `+` sign - /// followed by digits. - /// Leading and trailing whitespace represent an error. - /// Digits are a subset of these characters, depending on `radix`: - /// - /// * `0-9` - /// * `a-z` - /// * `A-Z` - /// - /// # Panics - /// - /// This function panics if `radix` is not in the range from 2 to 36. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(", stringify!($int_ty), "::from_str_radix(\"A\", 16), Ok(10));")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_int_from_str", issue = "59133")] - pub const fn from_str_radix(src: &str, radix: u32) -> Result<$int_ty, ParseIntError> { - use self::IntErrorKind::*; - use self::ParseIntError as PIE; - - if 2 > radix || radix > 36 { - from_str_radix_panic(radix); - } - - if src.is_empty() { - return Err(PIE { kind: Empty }); - } - - #[allow(unused_comparisons)] - let is_signed_ty = 0 > <$int_ty>::MIN; - - // all valid digits are ascii, so we will just iterate over the utf8 bytes - // and cast them to chars. .to_digit() will safely return None for anything - // other than a valid ascii digit for the given radix, including the first-byte - // of multi-byte sequences - let src = src.as_bytes(); - - let (is_positive, mut digits) = match src { - [b'+' | b'-'] => { - return Err(PIE { kind: InvalidDigit }); - } - [b'+', rest @ ..] => (true, rest), - [b'-', rest @ ..] if is_signed_ty => (false, rest), - _ => (true, src), - }; - - let mut result = 0; - - macro_rules! unwrap_or_PIE { - ($option:expr, $kind:ident) => { - match $option { - Some(value) => value, - None => return Err(PIE { kind: $kind }), - } - }; - } - - if can_not_overflow::<$int_ty>(radix, is_signed_ty, digits) { - // If the len of the str is short compared to the range of the type - // we are parsing into, then we can be certain that an overflow will not occur. - // This bound is when `radix.pow(digits.len()) - 1 <= T::MAX` but the condition - // above is a faster (conservative) approximation of this. - // - // Consider radix 16 as it has the highest information density per digit and will thus overflow the earliest: - // `u8::MAX` is `ff` - any str of len 2 is guaranteed to not overflow. - // `i8::MAX` is `7f` - only a str of len 1 is guaranteed to not overflow. - macro_rules! run_unchecked_loop { - ($unchecked_additive_op:tt) => {{ - while let [c, rest @ ..] = digits { - result = result * (radix as $int_ty); - let x = unwrap_or_PIE!((*c as char).to_digit(radix), InvalidDigit); - result = result $unchecked_additive_op (x as $int_ty); - digits = rest; - } - }}; - } - if is_positive { - run_unchecked_loop!(+) - } else { - run_unchecked_loop!(-) - }; - } else { - macro_rules! run_checked_loop { - ($checked_additive_op:ident, $overflow_err:ident) => {{ - while let [c, rest @ ..] = digits { - // When `radix` is passed in as a literal, rather than doing a slow `imul` - // the compiler can use shifts if `radix` can be expressed as a - // sum of powers of 2 (x*10 can be written as x*8 + x*2). - // When the compiler can't use these optimisations, - // the latency of the multiplication can be hidden by issuing it - // before the result is needed to improve performance on - // modern out-of-order CPU as multiplication here is slower - // than the other instructions, we can get the end result faster - // doing multiplication first and let the CPU spends other cycles - // doing other computation and get multiplication result later. - let mul = result.checked_mul(radix as $int_ty); - let x = unwrap_or_PIE!((*c as char).to_digit(radix), InvalidDigit) as $int_ty; - result = unwrap_or_PIE!(mul, $overflow_err); - result = unwrap_or_PIE!(<$int_ty>::$checked_additive_op(result, x), $overflow_err); - digits = rest; - } - }}; - } - if is_positive { - run_checked_loop!(checked_add, PosOverflow) - } else { - run_checked_loop!(checked_sub, NegOverflow) - }; - } - Ok(result) - } - } - )+} -} - -from_str_radix! { i8 u8 i16 u16 i32 u32 i64 u64 i128 u128 } - -// Re-use the relevant implementation of from_str_radix for isize and usize to avoid outputting two -// identical functions. -macro_rules! from_str_radix_size_impl { - ($($t:ident $size:ty),*) => {$( - impl $size { - /// Converts a string slice in a given base to an integer. - /// - /// The string is expected to be an optional `+` sign - /// followed by digits. - /// Leading and trailing whitespace represent an error. - /// Digits are a subset of these characters, depending on `radix`: - /// - /// * `0-9` - /// * `a-z` - /// * `A-Z` - /// - /// # Panics - /// - /// This function panics if `radix` is not in the range from 2 to 36. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(", stringify!($size), "::from_str_radix(\"A\", 16), Ok(10));")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_int_from_str", issue = "59133")] - pub const fn from_str_radix(src: &str, radix: u32) -> Result<$size, ParseIntError> { - match <$t>::from_str_radix(src, radix) { - Ok(x) => Ok(x as $size), - Err(e) => Err(e), - } - } - })*} -} - -#[cfg(target_pointer_width = "16")] -from_str_radix_size_impl! { i16 isize, u16 usize } -#[cfg(target_pointer_width = "32")] -from_str_radix_size_impl! { i32 isize, u32 usize } -#[cfg(target_pointer_width = "64")] -from_str_radix_size_impl! { i64 isize, u64 usize } diff --git a/library/core/src/num/nonzero.rs b/library/core/src/num/nonzero.rs deleted file mode 100644 index fcdd983343d62..0000000000000 --- a/library/core/src/num/nonzero.rs +++ /dev/null @@ -1,1700 +0,0 @@ -//! Definitions of integer that is known not to equal zero. - -use crate::cmp::Ordering; -use crate::fmt; -use crate::hash::{Hash, Hasher}; -use crate::intrinsics; -use crate::marker::{Freeze, StructuralPartialEq}; -use crate::ops::{BitOr, BitOrAssign, Div, DivAssign, Neg, Rem, RemAssign}; -use crate::panic::{RefUnwindSafe, UnwindSafe}; -use crate::ptr; -use crate::str::FromStr; -use crate::ub_checks; - -use super::{IntErrorKind, ParseIntError}; - -/// A marker trait for primitive types which can be zero. -/// -/// This is an implementation detail for [NonZero]\ which may disappear or be replaced at any time. -/// -/// # Safety -/// -/// Types implementing this trait must be primitives that are valid when zeroed. -/// -/// The associated `Self::NonZeroInner` type must have the same size+align as `Self`, -/// but with a niche and bit validity making it so the following `transmutes` are sound: -/// -/// - `Self::NonZeroInner` to `Option` -/// - `Option` to `Self` -/// -/// (And, consequently, `Self::NonZeroInner` to `Self`.) -#[unstable( - feature = "nonzero_internals", - reason = "implementation detail which may disappear or be replaced at any time", - issue = "none" -)] -#[const_trait] -pub unsafe trait ZeroablePrimitive: Sized + Copy + private::Sealed { - #[doc(hidden)] - type NonZeroInner: Sized + Copy; -} - -macro_rules! impl_zeroable_primitive { - ($($NonZeroInner:ident ( $primitive:ty )),+ $(,)?) => { - mod private { - #[unstable( - feature = "nonzero_internals", - reason = "implementation detail which may disappear or be replaced at any time", - issue = "none" - )] - #[const_trait] - pub trait Sealed {} - - $( - #[derive(Debug, Clone, Copy, PartialEq)] - #[repr(transparent)] - #[rustc_layout_scalar_valid_range_start(1)] - #[rustc_nonnull_optimization_guaranteed] - #[unstable( - feature = "nonzero_internals", - reason = "implementation detail which may disappear or be replaced at any time", - issue = "none" - )] - pub struct $NonZeroInner($primitive); - )+ - } - - $( - #[unstable( - feature = "nonzero_internals", - reason = "implementation detail which may disappear or be replaced at any time", - issue = "none" - )] - impl const private::Sealed for $primitive {} - - #[unstable( - feature = "nonzero_internals", - reason = "implementation detail which may disappear or be replaced at any time", - issue = "none" - )] - unsafe impl const ZeroablePrimitive for $primitive { - type NonZeroInner = private::$NonZeroInner; - } - )+ - }; -} - -impl_zeroable_primitive!( - NonZeroU8Inner(u8), - NonZeroU16Inner(u16), - NonZeroU32Inner(u32), - NonZeroU64Inner(u64), - NonZeroU128Inner(u128), - NonZeroUsizeInner(usize), - NonZeroI8Inner(i8), - NonZeroI16Inner(i16), - NonZeroI32Inner(i32), - NonZeroI64Inner(i64), - NonZeroI128Inner(i128), - NonZeroIsizeInner(isize), -); - -/// A value that is known not to equal zero. -/// -/// This enables some memory layout optimization. -/// For example, `Option>` is the same size as `u32`: -/// -/// ``` -/// use core::{mem::size_of, num::NonZero}; -/// -/// assert_eq!(size_of::>>(), size_of::()); -/// ``` -#[stable(feature = "generic_nonzero", since = "1.79.0")] -#[repr(transparent)] -#[rustc_nonnull_optimization_guaranteed] -#[rustc_diagnostic_item = "NonZero"] -pub struct NonZero(T::NonZeroInner); - -macro_rules! impl_nonzero_fmt { - ($Trait:ident) => { - #[stable(feature = "nonzero", since = "1.28.0")] - impl fmt::$Trait for NonZero - where - T: ZeroablePrimitive + fmt::$Trait, - { - #[inline] - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.get().fmt(f) - } - } - }; -} - -impl_nonzero_fmt!(Debug); -impl_nonzero_fmt!(Display); -impl_nonzero_fmt!(Binary); -impl_nonzero_fmt!(Octal); -impl_nonzero_fmt!(LowerHex); -impl_nonzero_fmt!(UpperHex); - -macro_rules! impl_nonzero_auto_trait { - (unsafe $Trait:ident) => { - #[stable(feature = "nonzero", since = "1.28.0")] - unsafe impl $Trait for NonZero where T: ZeroablePrimitive + $Trait {} - }; - ($Trait:ident) => { - #[stable(feature = "nonzero", since = "1.28.0")] - impl $Trait for NonZero where T: ZeroablePrimitive + $Trait {} - }; -} - -// Implement auto-traits manually based on `T` to avoid docs exposing -// the `ZeroablePrimitive::NonZeroInner` implementation detail. -impl_nonzero_auto_trait!(unsafe Freeze); -impl_nonzero_auto_trait!(RefUnwindSafe); -impl_nonzero_auto_trait!(unsafe Send); -impl_nonzero_auto_trait!(unsafe Sync); -impl_nonzero_auto_trait!(Unpin); -impl_nonzero_auto_trait!(UnwindSafe); - -#[stable(feature = "nonzero", since = "1.28.0")] -impl Clone for NonZero -where - T: ZeroablePrimitive, -{ - #[inline] - fn clone(&self) -> Self { - Self(self.0) - } -} - -#[stable(feature = "nonzero", since = "1.28.0")] -impl Copy for NonZero where T: ZeroablePrimitive {} - -#[stable(feature = "nonzero", since = "1.28.0")] -impl PartialEq for NonZero -where - T: ZeroablePrimitive + PartialEq, -{ - #[inline] - fn eq(&self, other: &Self) -> bool { - self.get() == other.get() - } - - #[inline] - fn ne(&self, other: &Self) -> bool { - self.get() != other.get() - } -} - -#[unstable(feature = "structural_match", issue = "31434")] -impl StructuralPartialEq for NonZero where T: ZeroablePrimitive + StructuralPartialEq {} - -#[stable(feature = "nonzero", since = "1.28.0")] -impl Eq for NonZero where T: ZeroablePrimitive + Eq {} - -#[stable(feature = "nonzero", since = "1.28.0")] -impl PartialOrd for NonZero -where - T: ZeroablePrimitive + PartialOrd, -{ - #[inline] - fn partial_cmp(&self, other: &Self) -> Option { - self.get().partial_cmp(&other.get()) - } - - #[inline] - fn lt(&self, other: &Self) -> bool { - self.get() < other.get() - } - - #[inline] - fn le(&self, other: &Self) -> bool { - self.get() <= other.get() - } - - #[inline] - fn gt(&self, other: &Self) -> bool { - self.get() > other.get() - } - - #[inline] - fn ge(&self, other: &Self) -> bool { - self.get() >= other.get() - } -} - -#[stable(feature = "nonzero", since = "1.28.0")] -impl Ord for NonZero -where - T: ZeroablePrimitive + Ord, -{ - #[inline] - fn cmp(&self, other: &Self) -> Ordering { - self.get().cmp(&other.get()) - } - - #[inline] - fn max(self, other: Self) -> Self { - // SAFETY: The maximum of two non-zero values is still non-zero. - unsafe { Self::new_unchecked(self.get().max(other.get())) } - } - - #[inline] - fn min(self, other: Self) -> Self { - // SAFETY: The minimum of two non-zero values is still non-zero. - unsafe { Self::new_unchecked(self.get().min(other.get())) } - } - - #[inline] - fn clamp(self, min: Self, max: Self) -> Self { - // SAFETY: A non-zero value clamped between two non-zero values is still non-zero. - unsafe { Self::new_unchecked(self.get().clamp(min.get(), max.get())) } - } -} - -#[stable(feature = "nonzero", since = "1.28.0")] -impl Hash for NonZero -where - T: ZeroablePrimitive + Hash, -{ - #[inline] - fn hash(&self, state: &mut H) - where - H: Hasher, - { - self.get().hash(state) - } -} - -#[stable(feature = "from_nonzero", since = "1.31.0")] -impl From> for T -where - T: ZeroablePrimitive, -{ - #[inline] - fn from(nonzero: NonZero) -> Self { - // Call `get` method to keep range information. - nonzero.get() - } -} - -#[stable(feature = "nonzero_bitor", since = "1.45.0")] -impl BitOr for NonZero -where - T: ZeroablePrimitive + BitOr, -{ - type Output = Self; - - #[inline] - fn bitor(self, rhs: Self) -> Self::Output { - // SAFETY: Bitwise OR of two non-zero values is still non-zero. - unsafe { Self::new_unchecked(self.get() | rhs.get()) } - } -} - -#[stable(feature = "nonzero_bitor", since = "1.45.0")] -impl BitOr for NonZero -where - T: ZeroablePrimitive + BitOr, -{ - type Output = Self; - - #[inline] - fn bitor(self, rhs: T) -> Self::Output { - // SAFETY: Bitwise OR of a non-zero value with anything is still non-zero. - unsafe { Self::new_unchecked(self.get() | rhs) } - } -} - -#[stable(feature = "nonzero_bitor", since = "1.45.0")] -impl BitOr> for T -where - T: ZeroablePrimitive + BitOr, -{ - type Output = NonZero; - - #[inline] - fn bitor(self, rhs: NonZero) -> Self::Output { - // SAFETY: Bitwise OR of anything with a non-zero value is still non-zero. - unsafe { NonZero::new_unchecked(self | rhs.get()) } - } -} - -#[stable(feature = "nonzero_bitor", since = "1.45.0")] -impl BitOrAssign for NonZero -where - T: ZeroablePrimitive, - Self: BitOr, -{ - #[inline] - fn bitor_assign(&mut self, rhs: Self) { - *self = *self | rhs; - } -} - -#[stable(feature = "nonzero_bitor", since = "1.45.0")] -impl BitOrAssign for NonZero -where - T: ZeroablePrimitive, - Self: BitOr, -{ - #[inline] - fn bitor_assign(&mut self, rhs: T) { - *self = *self | rhs; - } -} - -impl NonZero -where - T: ZeroablePrimitive, -{ - /// Creates a non-zero if the given value is not zero. - #[stable(feature = "nonzero", since = "1.28.0")] - #[rustc_const_stable(feature = "const_nonzero_int_methods", since = "1.47.0")] - #[must_use] - #[inline] - pub const fn new(n: T) -> Option { - // SAFETY: Memory layout optimization guarantees that `Option>` has - // the same layout and size as `T`, with `0` representing `None`. - unsafe { intrinsics::transmute_unchecked(n) } - } - - /// Creates a non-zero without checking whether the value is non-zero. - /// This results in undefined behaviour if the value is zero. - /// - /// # Safety - /// - /// The value must not be zero. - #[stable(feature = "nonzero", since = "1.28.0")] - #[rustc_const_stable(feature = "nonzero", since = "1.28.0")] - #[must_use] - #[inline] - pub const unsafe fn new_unchecked(n: T) -> Self { - match Self::new(n) { - Some(n) => n, - None => { - // SAFETY: The caller guarantees that `n` is non-zero, so this is unreachable. - unsafe { - ub_checks::assert_unsafe_precondition!( - check_language_ub, - "NonZero::new_unchecked requires the argument to be non-zero", - () => false, - ); - intrinsics::unreachable() - } - } - } - } - - /// Converts a reference to a non-zero mutable reference - /// if the referenced value is not zero. - #[unstable(feature = "nonzero_from_mut", issue = "106290")] - #[must_use] - #[inline] - pub fn from_mut(n: &mut T) -> Option<&mut Self> { - // SAFETY: Memory layout optimization guarantees that `Option>` has - // the same layout and size as `T`, with `0` representing `None`. - let opt_n = unsafe { &mut *(ptr::from_mut(n).cast::>()) }; - - opt_n.as_mut() - } - - /// Converts a mutable reference to a non-zero mutable reference - /// without checking whether the referenced value is non-zero. - /// This results in undefined behavior if the referenced value is zero. - /// - /// # Safety - /// - /// The referenced value must not be zero. - #[unstable(feature = "nonzero_from_mut", issue = "106290")] - #[must_use] - #[inline] - pub unsafe fn from_mut_unchecked(n: &mut T) -> &mut Self { - match Self::from_mut(n) { - Some(n) => n, - None => { - // SAFETY: The caller guarantees that `n` references a value that is non-zero, so this is unreachable. - unsafe { - ub_checks::assert_unsafe_precondition!( - check_library_ub, - "NonZero::from_mut_unchecked requires the argument to dereference as non-zero", - () => false, - ); - intrinsics::unreachable() - } - } - } - } - - /// Returns the contained value as a primitive type. - #[stable(feature = "nonzero", since = "1.28.0")] - #[rustc_const_stable(feature = "const_nonzero_get", since = "1.34.0")] - #[inline] - pub const fn get(self) -> T { - // FIXME: This can be changed to simply `self.0` once LLVM supports `!range` metadata - // for function arguments: https://github.com/llvm/llvm-project/issues/76628 - // - // Rustc can set range metadata only if it loads `self` from - // memory somewhere. If the value of `self` was from by-value argument - // of some not-inlined function, LLVM don't have range metadata - // to understand that the value cannot be zero. - // - // For now, using the transmute `assume`s the range at runtime. - // - // SAFETY: `ZeroablePrimitive` guarantees that the size and bit validity - // of `.0` is such that this transmute is sound. - unsafe { intrinsics::transmute_unchecked(self) } - } -} - -macro_rules! nonzero_integer { - ( - #[$stability:meta] - Self = $Ty:ident, - Primitive = $signedness:ident $Int:ident, - UnsignedPrimitive = $Uint:ty, - - // Used in doc comments. - leading_zeros_test = $leading_zeros_test:expr, - ) => { - /// An integer that is known not to equal zero. - /// - /// This enables some memory layout optimization. - #[doc = concat!("For example, `Option<", stringify!($Ty), ">` is the same size as `", stringify!($Int), "`:")] - /// - /// ```rust - /// use std::mem::size_of; - #[doc = concat!("assert_eq!(size_of::>(), size_of::<", stringify!($Int), ">());")] - /// ``` - /// - /// # Layout - /// - #[doc = concat!("`", stringify!($Ty), "` is guaranteed to have the same layout and bit validity as `", stringify!($Int), "`")] - /// with the exception that `0` is not a valid instance. - #[doc = concat!("`Option<", stringify!($Ty), ">` is guaranteed to be compatible with `", stringify!($Int), "`,")] - /// including in FFI. - /// - /// Thanks to the [null pointer optimization], - #[doc = concat!("`", stringify!($Ty), "` and `Option<", stringify!($Ty), ">`")] - /// are guaranteed to have the same size and alignment: - /// - /// ``` - /// # use std::mem::{size_of, align_of}; - #[doc = concat!("use std::num::", stringify!($Ty), ";")] - /// - #[doc = concat!("assert_eq!(size_of::<", stringify!($Ty), ">(), size_of::>());")] - #[doc = concat!("assert_eq!(align_of::<", stringify!($Ty), ">(), align_of::>());")] - /// ``` - /// - /// [null pointer optimization]: crate::option#representation - #[$stability] - pub type $Ty = NonZero<$Int>; - - impl NonZero<$Int> { - /// The size of this non-zero integer type in bits. - /// - #[doc = concat!("This value is equal to [`", stringify!($Int), "::BITS`].")] - /// - /// # Examples - /// - /// ``` - /// # use std::num::NonZero; - /// # - #[doc = concat!("assert_eq!(NonZero::<", stringify!($Int), ">::BITS, ", stringify!($Int), "::BITS);")] - /// ``` - #[stable(feature = "nonzero_bits", since = "1.67.0")] - pub const BITS: u32 = <$Int>::BITS; - - /// Returns the number of leading zeros in the binary representation of `self`. - /// - /// On many architectures, this function can perform better than `leading_zeros()` on the underlying integer type, as special handling of zero can be avoided. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// # use std::num::NonZero; - /// # - #[doc = concat!("let n = NonZero::<", stringify!($Int), ">::new(", $leading_zeros_test, ").unwrap();")] - /// - /// assert_eq!(n.leading_zeros(), 0); - /// ``` - #[stable(feature = "nonzero_leading_trailing_zeros", since = "1.53.0")] - #[rustc_const_stable(feature = "nonzero_leading_trailing_zeros", since = "1.53.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn leading_zeros(self) -> u32 { - // SAFETY: since `self` cannot be zero, it is safe to call `ctlz_nonzero`. - unsafe { - intrinsics::ctlz_nonzero(self.get() as $Uint) - } - } - - /// Returns the number of trailing zeros in the binary representation - /// of `self`. - /// - /// On many architectures, this function can perform better than `trailing_zeros()` on the underlying integer type, as special handling of zero can be avoided. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// # use std::num::NonZero; - /// # - #[doc = concat!("let n = NonZero::<", stringify!($Int), ">::new(0b0101000).unwrap();")] - /// - /// assert_eq!(n.trailing_zeros(), 3); - /// ``` - #[stable(feature = "nonzero_leading_trailing_zeros", since = "1.53.0")] - #[rustc_const_stable(feature = "nonzero_leading_trailing_zeros", since = "1.53.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn trailing_zeros(self) -> u32 { - // SAFETY: since `self` cannot be zero, it is safe to call `cttz_nonzero`. - unsafe { - intrinsics::cttz_nonzero(self.get() as $Uint) - } - } - - /// Returns the number of ones in the binary representation of `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(non_zero_count_ones)] - /// - /// # use std::num::NonZero; - /// # - /// # fn main() { test().unwrap(); } - /// # fn test() -> Option<()> { - #[doc = concat!("let a = NonZero::<", stringify!($Int), ">::new(0b100_0000)?;")] - #[doc = concat!("let b = NonZero::<", stringify!($Int), ">::new(0b100_0011)?;")] - /// - /// assert_eq!(a.count_ones(), NonZero::new(1)?); - /// assert_eq!(b.count_ones(), NonZero::new(3)?); - /// # Some(()) - /// # } - /// ``` - /// - #[unstable(feature = "non_zero_count_ones", issue = "120287")] - #[rustc_const_unstable(feature = "non_zero_count_ones", issue = "120287")] - #[doc(alias = "popcount")] - #[doc(alias = "popcnt")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn count_ones(self) -> NonZero { - // SAFETY: - // `self` is non-zero, which means it has at least one bit set, which means - // that the result of `count_ones` is non-zero. - unsafe { NonZero::new_unchecked(self.get().count_ones()) } - } - - nonzero_integer_signedness_dependent_methods! { - Self = $Ty, - Primitive = $signedness $Int, - UnsignedPrimitive = $Uint, - } - - /// Multiplies two non-zero integers together. - /// Checks for overflow and returns [`None`] on overflow. - /// As a consequence, the result cannot wrap to zero. - /// - /// # Examples - /// - /// ``` - /// # use std::num::NonZero; - /// # - /// # fn main() { test().unwrap(); } - /// # fn test() -> Option<()> { - #[doc = concat!("let two = NonZero::new(2", stringify!($Int), ")?;")] - #[doc = concat!("let four = NonZero::new(4", stringify!($Int), ")?;")] - #[doc = concat!("let max = NonZero::new(", stringify!($Int), "::MAX)?;")] - /// - /// assert_eq!(Some(four), two.checked_mul(two)); - /// assert_eq!(None, max.checked_mul(two)); - /// # Some(()) - /// # } - /// ``` - #[stable(feature = "nonzero_checked_ops", since = "1.64.0")] - #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_mul(self, other: Self) -> Option { - if let Some(result) = self.get().checked_mul(other.get()) { - // SAFETY: - // - `checked_mul` returns `None` on overflow - // - `self` and `other` are non-zero - // - the only way to get zero from a multiplication without overflow is for one - // of the sides to be zero - // - // So the result cannot be zero. - Some(unsafe { Self::new_unchecked(result) }) - } else { - None - } - } - - /// Multiplies two non-zero integers together. - #[doc = concat!("Return [`NonZero::<", stringify!($Int), ">::MAX`] on overflow.")] - /// - /// # Examples - /// - /// ``` - /// # use std::num::NonZero; - /// # - /// # fn main() { test().unwrap(); } - /// # fn test() -> Option<()> { - #[doc = concat!("let two = NonZero::new(2", stringify!($Int), ")?;")] - #[doc = concat!("let four = NonZero::new(4", stringify!($Int), ")?;")] - #[doc = concat!("let max = NonZero::new(", stringify!($Int), "::MAX)?;")] - /// - /// assert_eq!(four, two.saturating_mul(two)); - /// assert_eq!(max, four.saturating_mul(max)); - /// # Some(()) - /// # } - /// ``` - #[stable(feature = "nonzero_checked_ops", since = "1.64.0")] - #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn saturating_mul(self, other: Self) -> Self { - // SAFETY: - // - `saturating_mul` returns `u*::MAX`/`i*::MAX`/`i*::MIN` on overflow/underflow, - // all of which are non-zero - // - `self` and `other` are non-zero - // - the only way to get zero from a multiplication without overflow is for one - // of the sides to be zero - // - // So the result cannot be zero. - unsafe { Self::new_unchecked(self.get().saturating_mul(other.get())) } - } - - /// Multiplies two non-zero integers together, - /// assuming overflow cannot occur. - /// Overflow is unchecked, and it is undefined behaviour to overflow - /// *even if the result would wrap to a non-zero value*. - /// The behaviour is undefined as soon as - #[doc = sign_dependent_expr!{ - $signedness ? - if signed { - concat!("`self * rhs > ", stringify!($Int), "::MAX`, ", - "or `self * rhs < ", stringify!($Int), "::MIN`.") - } - if unsigned { - concat!("`self * rhs > ", stringify!($Int), "::MAX`.") - } - }] - /// - /// # Examples - /// - /// ``` - /// #![feature(nonzero_ops)] - /// - /// # use std::num::NonZero; - /// # - /// # fn main() { test().unwrap(); } - /// # fn test() -> Option<()> { - #[doc = concat!("let two = NonZero::new(2", stringify!($Int), ")?;")] - #[doc = concat!("let four = NonZero::new(4", stringify!($Int), ")?;")] - /// - /// assert_eq!(four, unsafe { two.unchecked_mul(two) }); - /// # Some(()) - /// # } - /// ``` - #[unstable(feature = "nonzero_ops", issue = "84186")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const unsafe fn unchecked_mul(self, other: Self) -> Self { - // SAFETY: The caller ensures there is no overflow. - unsafe { Self::new_unchecked(self.get().unchecked_mul(other.get())) } - } - - /// Raises non-zero value to an integer power. - /// Checks for overflow and returns [`None`] on overflow. - /// As a consequence, the result cannot wrap to zero. - /// - /// # Examples - /// - /// ``` - /// # use std::num::NonZero; - /// # - /// # fn main() { test().unwrap(); } - /// # fn test() -> Option<()> { - #[doc = concat!("let three = NonZero::new(3", stringify!($Int), ")?;")] - #[doc = concat!("let twenty_seven = NonZero::new(27", stringify!($Int), ")?;")] - #[doc = concat!("let half_max = NonZero::new(", stringify!($Int), "::MAX / 2)?;")] - /// - /// assert_eq!(Some(twenty_seven), three.checked_pow(3)); - /// assert_eq!(None, half_max.checked_pow(3)); - /// # Some(()) - /// # } - /// ``` - #[stable(feature = "nonzero_checked_ops", since = "1.64.0")] - #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_pow(self, other: u32) -> Option { - if let Some(result) = self.get().checked_pow(other) { - // SAFETY: - // - `checked_pow` returns `None` on overflow/underflow - // - `self` is non-zero - // - the only way to get zero from an exponentiation without overflow is - // for base to be zero - // - // So the result cannot be zero. - Some(unsafe { Self::new_unchecked(result) }) - } else { - None - } - } - - /// Raise non-zero value to an integer power. - #[doc = sign_dependent_expr!{ - $signedness ? - if signed { - concat!("Return [`NonZero::<", stringify!($Int), ">::MIN`] ", - "or [`NonZero::<", stringify!($Int), ">::MAX`] on overflow.") - } - if unsigned { - concat!("Return [`NonZero::<", stringify!($Int), ">::MAX`] on overflow.") - } - }] - /// - /// # Examples - /// - /// ``` - /// # use std::num::NonZero; - /// # - /// # fn main() { test().unwrap(); } - /// # fn test() -> Option<()> { - #[doc = concat!("let three = NonZero::new(3", stringify!($Int), ")?;")] - #[doc = concat!("let twenty_seven = NonZero::new(27", stringify!($Int), ")?;")] - #[doc = concat!("let max = NonZero::new(", stringify!($Int), "::MAX)?;")] - /// - /// assert_eq!(twenty_seven, three.saturating_pow(3)); - /// assert_eq!(max, max.saturating_pow(3)); - /// # Some(()) - /// # } - /// ``` - #[stable(feature = "nonzero_checked_ops", since = "1.64.0")] - #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn saturating_pow(self, other: u32) -> Self { - // SAFETY: - // - `saturating_pow` returns `u*::MAX`/`i*::MAX`/`i*::MIN` on overflow/underflow, - // all of which are non-zero - // - `self` is non-zero - // - the only way to get zero from an exponentiation without overflow is - // for base to be zero - // - // So the result cannot be zero. - unsafe { Self::new_unchecked(self.get().saturating_pow(other)) } - } - } - - #[stable(feature = "nonzero_parse", since = "1.35.0")] - impl FromStr for NonZero<$Int> { - type Err = ParseIntError; - fn from_str(src: &str) -> Result { - Self::new(<$Int>::from_str_radix(src, 10)?) - .ok_or(ParseIntError { - kind: IntErrorKind::Zero - }) - } - } - - nonzero_integer_signedness_dependent_impls!($Ty $signedness $Int); - }; - - (Self = $Ty:ident, Primitive = unsigned $Int:ident $(,)?) => { - nonzero_integer! { - #[stable(feature = "nonzero", since = "1.28.0")] - Self = $Ty, - Primitive = unsigned $Int, - UnsignedPrimitive = $Int, - leading_zeros_test = concat!(stringify!($Int), "::MAX"), - } - }; - - (Self = $Ty:ident, Primitive = signed $Int:ident, $($rest:tt)*) => { - nonzero_integer! { - #[stable(feature = "signed_nonzero", since = "1.34.0")] - Self = $Ty, - Primitive = signed $Int, - $($rest)* - leading_zeros_test = concat!("-1", stringify!($Int)), - } - }; -} - -macro_rules! nonzero_integer_signedness_dependent_impls { - // Impls for unsigned nonzero types only. - ($Ty:ident unsigned $Int:ty) => { - #[stable(feature = "nonzero_div", since = "1.51.0")] - impl Div> for $Int { - type Output = $Int; - - /// This operation rounds towards zero, truncating any fractional - /// part of the exact result, and cannot panic. - #[inline] - fn div(self, other: NonZero<$Int>) -> $Int { - // SAFETY: Division by zero is checked because `other` is non-zero, - // and MIN/-1 is checked because `self` is an unsigned int. - unsafe { intrinsics::unchecked_div(self, other.get()) } - } - } - - #[stable(feature = "nonzero_div_assign", since = "1.79.0")] - impl DivAssign> for $Int { - /// This operation rounds towards zero, truncating any fractional - /// part of the exact result, and cannot panic. - #[inline] - fn div_assign(&mut self, other: NonZero<$Int>) { - *self = *self / other; - } - } - - #[stable(feature = "nonzero_div", since = "1.51.0")] - impl Rem> for $Int { - type Output = $Int; - - /// This operation satisfies `n % d == n - (n / d) * d`, and cannot panic. - #[inline] - fn rem(self, other: NonZero<$Int>) -> $Int { - // SAFETY: Remainder by zero is checked because `other` is non-zero, - // and MIN/-1 is checked because `self` is an unsigned int. - unsafe { intrinsics::unchecked_rem(self, other.get()) } - } - } - - #[stable(feature = "nonzero_div_assign", since = "1.79.0")] - impl RemAssign> for $Int { - /// This operation satisfies `n % d == n - (n / d) * d`, and cannot panic. - #[inline] - fn rem_assign(&mut self, other: NonZero<$Int>) { - *self = *self % other; - } - } - }; - // Impls for signed nonzero types only. - ($Ty:ident signed $Int:ty) => { - #[stable(feature = "signed_nonzero_neg", since = "1.71.0")] - impl Neg for NonZero<$Int> { - type Output = Self; - - #[inline] - fn neg(self) -> Self { - // SAFETY: negation of nonzero cannot yield zero values. - unsafe { Self::new_unchecked(self.get().neg()) } - } - } - - forward_ref_unop! { impl Neg, neg for NonZero<$Int>, - #[stable(feature = "signed_nonzero_neg", since = "1.71.0")] } - }; -} - -#[rustfmt::skip] // https://github.com/rust-lang/rustfmt/issues/5974 -macro_rules! nonzero_integer_signedness_dependent_methods { - // Associated items for unsigned nonzero types only. - ( - Self = $Ty:ident, - Primitive = unsigned $Int:ident, - UnsignedPrimitive = $Uint:ty, - ) => { - /// The smallest value that can be represented by this non-zero - /// integer type, 1. - /// - /// # Examples - /// - /// ``` - /// # use std::num::NonZero; - /// # - #[doc = concat!("assert_eq!(NonZero::<", stringify!($Int), ">::MIN.get(), 1", stringify!($Int), ");")] - /// ``` - #[stable(feature = "nonzero_min_max", since = "1.70.0")] - pub const MIN: Self = Self::new(1).unwrap(); - - /// The largest value that can be represented by this non-zero - /// integer type, - #[doc = concat!("equal to [`", stringify!($Int), "::MAX`].")] - /// - /// # Examples - /// - /// ``` - /// # use std::num::NonZero; - /// # - #[doc = concat!("assert_eq!(NonZero::<", stringify!($Int), ">::MAX.get(), ", stringify!($Int), "::MAX);")] - /// ``` - #[stable(feature = "nonzero_min_max", since = "1.70.0")] - pub const MAX: Self = Self::new(<$Int>::MAX).unwrap(); - - /// Adds an unsigned integer to a non-zero value. - /// Checks for overflow and returns [`None`] on overflow. - /// As a consequence, the result cannot wrap to zero. - /// - /// - /// # Examples - /// - /// ``` - /// # use std::num::NonZero; - /// # - /// # fn main() { test().unwrap(); } - /// # fn test() -> Option<()> { - #[doc = concat!("let one = NonZero::new(1", stringify!($Int), ")?;")] - #[doc = concat!("let two = NonZero::new(2", stringify!($Int), ")?;")] - #[doc = concat!("let max = NonZero::new(", stringify!($Int), "::MAX)?;")] - /// - /// assert_eq!(Some(two), one.checked_add(1)); - /// assert_eq!(None, max.checked_add(1)); - /// # Some(()) - /// # } - /// ``` - #[stable(feature = "nonzero_checked_ops", since = "1.64.0")] - #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_add(self, other: $Int) -> Option { - if let Some(result) = self.get().checked_add(other) { - // SAFETY: - // - `checked_add` returns `None` on overflow - // - `self` is non-zero - // - the only way to get zero from an addition without overflow is for both - // sides to be zero - // - // So the result cannot be zero. - Some(unsafe { Self::new_unchecked(result) }) - } else { - None - } - } - - /// Adds an unsigned integer to a non-zero value. - #[doc = concat!("Return [`NonZero::<", stringify!($Int), ">::MAX`] on overflow.")] - /// - /// # Examples - /// - /// ``` - /// # use std::num::NonZero; - /// # - /// # fn main() { test().unwrap(); } - /// # fn test() -> Option<()> { - #[doc = concat!("let one = NonZero::new(1", stringify!($Int), ")?;")] - #[doc = concat!("let two = NonZero::new(2", stringify!($Int), ")?;")] - #[doc = concat!("let max = NonZero::new(", stringify!($Int), "::MAX)?;")] - /// - /// assert_eq!(two, one.saturating_add(1)); - /// assert_eq!(max, max.saturating_add(1)); - /// # Some(()) - /// # } - /// ``` - #[stable(feature = "nonzero_checked_ops", since = "1.64.0")] - #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn saturating_add(self, other: $Int) -> Self { - // SAFETY: - // - `saturating_add` returns `u*::MAX` on overflow, which is non-zero - // - `self` is non-zero - // - the only way to get zero from an addition without overflow is for both - // sides to be zero - // - // So the result cannot be zero. - unsafe { Self::new_unchecked(self.get().saturating_add(other)) } - } - - /// Adds an unsigned integer to a non-zero value, - /// assuming overflow cannot occur. - /// Overflow is unchecked, and it is undefined behaviour to overflow - /// *even if the result would wrap to a non-zero value*. - /// The behaviour is undefined as soon as - #[doc = concat!("`self + rhs > ", stringify!($Int), "::MAX`.")] - /// - /// # Examples - /// - /// ``` - /// #![feature(nonzero_ops)] - /// - /// # use std::num::NonZero; - /// # - /// # fn main() { test().unwrap(); } - /// # fn test() -> Option<()> { - #[doc = concat!("let one = NonZero::new(1", stringify!($Int), ")?;")] - #[doc = concat!("let two = NonZero::new(2", stringify!($Int), ")?;")] - /// - /// assert_eq!(two, unsafe { one.unchecked_add(1) }); - /// # Some(()) - /// # } - /// ``` - #[unstable(feature = "nonzero_ops", issue = "84186")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const unsafe fn unchecked_add(self, other: $Int) -> Self { - // SAFETY: The caller ensures there is no overflow. - unsafe { Self::new_unchecked(self.get().unchecked_add(other)) } - } - - /// Returns the smallest power of two greater than or equal to n. - /// Checks for overflow and returns [`None`] - /// if the next power of two is greater than the type’s maximum value. - /// As a consequence, the result cannot wrap to zero. - /// - /// # Examples - /// - /// ``` - /// # use std::num::NonZero; - /// # - /// # fn main() { test().unwrap(); } - /// # fn test() -> Option<()> { - #[doc = concat!("let two = NonZero::new(2", stringify!($Int), ")?;")] - #[doc = concat!("let three = NonZero::new(3", stringify!($Int), ")?;")] - #[doc = concat!("let four = NonZero::new(4", stringify!($Int), ")?;")] - #[doc = concat!("let max = NonZero::new(", stringify!($Int), "::MAX)?;")] - /// - /// assert_eq!(Some(two), two.checked_next_power_of_two() ); - /// assert_eq!(Some(four), three.checked_next_power_of_two() ); - /// assert_eq!(None, max.checked_next_power_of_two() ); - /// # Some(()) - /// # } - /// ``` - #[stable(feature = "nonzero_checked_ops", since = "1.64.0")] - #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_next_power_of_two(self) -> Option { - if let Some(nz) = self.get().checked_next_power_of_two() { - // SAFETY: The next power of two is positive - // and overflow is checked. - Some(unsafe { Self::new_unchecked(nz) }) - } else { - None - } - } - - /// Returns the base 2 logarithm of the number, rounded down. - /// - /// This is the same operation as - #[doc = concat!("[`", stringify!($Int), "::ilog2`],")] - /// except that it has no failure cases to worry about - /// since this value can never be zero. - /// - /// # Examples - /// - /// ``` - /// # use std::num::NonZero; - /// # - #[doc = concat!("assert_eq!(NonZero::new(7", stringify!($Int), ").unwrap().ilog2(), 2);")] - #[doc = concat!("assert_eq!(NonZero::new(8", stringify!($Int), ").unwrap().ilog2(), 3);")] - #[doc = concat!("assert_eq!(NonZero::new(9", stringify!($Int), ").unwrap().ilog2(), 3);")] - /// ``` - #[stable(feature = "int_log", since = "1.67.0")] - #[rustc_const_stable(feature = "int_log", since = "1.67.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn ilog2(self) -> u32 { - Self::BITS - 1 - self.leading_zeros() - } - - /// Returns the base 10 logarithm of the number, rounded down. - /// - /// This is the same operation as - #[doc = concat!("[`", stringify!($Int), "::ilog10`],")] - /// except that it has no failure cases to worry about - /// since this value can never be zero. - /// - /// # Examples - /// - /// ``` - /// # use std::num::NonZero; - /// # - #[doc = concat!("assert_eq!(NonZero::new(99", stringify!($Int), ").unwrap().ilog10(), 1);")] - #[doc = concat!("assert_eq!(NonZero::new(100", stringify!($Int), ").unwrap().ilog10(), 2);")] - #[doc = concat!("assert_eq!(NonZero::new(101", stringify!($Int), ").unwrap().ilog10(), 2);")] - /// ``` - #[stable(feature = "int_log", since = "1.67.0")] - #[rustc_const_stable(feature = "int_log", since = "1.67.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn ilog10(self) -> u32 { - super::int_log10::$Int(self.get()) - } - - /// Calculates the middle point of `self` and `rhs`. - /// - /// `midpoint(a, b)` is `(a + b) >> 1` as if it were performed in a - /// sufficiently-large signed integral type. This implies that the result is - /// always rounded towards negative infinity and that no overflow will ever occur. - /// - /// # Examples - /// - /// ``` - /// #![feature(num_midpoint)] - /// - /// # use std::num::NonZero; - /// # - /// # fn main() { test().unwrap(); } - /// # fn test() -> Option<()> { - #[doc = concat!("let one = NonZero::new(1", stringify!($Int), ")?;")] - #[doc = concat!("let two = NonZero::new(2", stringify!($Int), ")?;")] - #[doc = concat!("let four = NonZero::new(4", stringify!($Int), ")?;")] - /// - /// assert_eq!(one.midpoint(four), two); - /// assert_eq!(four.midpoint(one), two); - /// # Some(()) - /// # } - /// ``` - #[unstable(feature = "num_midpoint", issue = "110840")] - #[rustc_const_unstable(feature = "const_num_midpoint", issue = "110840")] - #[rustc_allow_const_fn_unstable(const_num_midpoint)] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn midpoint(self, rhs: Self) -> Self { - // SAFETY: The only way to get `0` with midpoint is to have two opposite or - // near opposite numbers: (-5, 5), (0, 1), (0, 0) which is impossible because - // of the unsignedness of this number and also because `Self` is guaranteed to - // never being 0. - unsafe { Self::new_unchecked(self.get().midpoint(rhs.get())) } - } - - /// Returns `true` if and only if `self == (1 << k)` for some `k`. - /// - /// On many architectures, this function can perform better than `is_power_of_two()` - /// on the underlying integer type, as special handling of zero can be avoided. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let eight = std::num::NonZero::new(8", stringify!($Int), ").unwrap();")] - /// assert!(eight.is_power_of_two()); - #[doc = concat!("let ten = std::num::NonZero::new(10", stringify!($Int), ").unwrap();")] - /// assert!(!ten.is_power_of_two()); - /// ``` - #[must_use] - #[stable(feature = "nonzero_is_power_of_two", since = "1.59.0")] - #[rustc_const_stable(feature = "nonzero_is_power_of_two", since = "1.59.0")] - #[inline] - pub const fn is_power_of_two(self) -> bool { - // LLVM 11 normalizes `unchecked_sub(x, 1) & x == 0` to the implementation seen here. - // On the basic x86-64 target, this saves 3 instructions for the zero check. - // On x86_64 with BMI1, being nonzero lets it codegen to `BLSR`, which saves an instruction - // compared to the `POPCNT` implementation on the underlying integer type. - - intrinsics::ctpop(self.get()) < 2 - } - }; - - // Associated items for signed nonzero types only. - ( - Self = $Ty:ident, - Primitive = signed $Int:ident, - UnsignedPrimitive = $Uint:ty, - ) => { - /// The smallest value that can be represented by this non-zero - /// integer type, - #[doc = concat!("equal to [`", stringify!($Int), "::MIN`].")] - /// - /// Note: While most integer types are defined for every whole - /// number between `MIN` and `MAX`, signed non-zero integers are - /// a special case. They have a "gap" at 0. - /// - /// # Examples - /// - /// ``` - /// # use std::num::NonZero; - /// # - #[doc = concat!("assert_eq!(NonZero::<", stringify!($Int), ">::MIN.get(), ", stringify!($Int), "::MIN);")] - /// ``` - #[stable(feature = "nonzero_min_max", since = "1.70.0")] - pub const MIN: Self = Self::new(<$Int>::MIN).unwrap(); - - /// The largest value that can be represented by this non-zero - /// integer type, - #[doc = concat!("equal to [`", stringify!($Int), "::MAX`].")] - /// - /// Note: While most integer types are defined for every whole - /// number between `MIN` and `MAX`, signed non-zero integers are - /// a special case. They have a "gap" at 0. - /// - /// # Examples - /// - /// ``` - /// # use std::num::NonZero; - /// # - #[doc = concat!("assert_eq!(NonZero::<", stringify!($Int), ">::MAX.get(), ", stringify!($Int), "::MAX);")] - /// ``` - #[stable(feature = "nonzero_min_max", since = "1.70.0")] - pub const MAX: Self = Self::new(<$Int>::MAX).unwrap(); - - /// Computes the absolute value of self. - #[doc = concat!("See [`", stringify!($Int), "::abs`]")] - /// for documentation on overflow behaviour. - /// - /// # Example - /// - /// ``` - /// # use std::num::NonZero; - /// # - /// # fn main() { test().unwrap(); } - /// # fn test() -> Option<()> { - #[doc = concat!("let pos = NonZero::new(1", stringify!($Int), ")?;")] - #[doc = concat!("let neg = NonZero::new(-1", stringify!($Int), ")?;")] - /// - /// assert_eq!(pos, pos.abs()); - /// assert_eq!(pos, neg.abs()); - /// # Some(()) - /// # } - /// ``` - #[stable(feature = "nonzero_checked_ops", since = "1.64.0")] - #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn abs(self) -> Self { - // SAFETY: This cannot overflow to zero. - unsafe { Self::new_unchecked(self.get().abs()) } - } - - /// Checked absolute value. - /// Checks for overflow and returns [`None`] if - #[doc = concat!("`self == NonZero::<", stringify!($Int), ">::MIN`.")] - /// The result cannot be zero. - /// - /// # Example - /// - /// ``` - /// # use std::num::NonZero; - /// # - /// # fn main() { test().unwrap(); } - /// # fn test() -> Option<()> { - #[doc = concat!("let pos = NonZero::new(1", stringify!($Int), ")?;")] - #[doc = concat!("let neg = NonZero::new(-1", stringify!($Int), ")?;")] - #[doc = concat!("let min = NonZero::new(", stringify!($Int), "::MIN)?;")] - /// - /// assert_eq!(Some(pos), neg.checked_abs()); - /// assert_eq!(None, min.checked_abs()); - /// # Some(()) - /// # } - /// ``` - #[stable(feature = "nonzero_checked_ops", since = "1.64.0")] - #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_abs(self) -> Option { - if let Some(nz) = self.get().checked_abs() { - // SAFETY: absolute value of nonzero cannot yield zero values. - Some(unsafe { Self::new_unchecked(nz) }) - } else { - None - } - } - - /// Computes the absolute value of self, - /// with overflow information, see - #[doc = concat!("[`", stringify!($Int), "::overflowing_abs`].")] - /// - /// # Example - /// - /// ``` - /// # use std::num::NonZero; - /// # - /// # fn main() { test().unwrap(); } - /// # fn test() -> Option<()> { - #[doc = concat!("let pos = NonZero::new(1", stringify!($Int), ")?;")] - #[doc = concat!("let neg = NonZero::new(-1", stringify!($Int), ")?;")] - #[doc = concat!("let min = NonZero::new(", stringify!($Int), "::MIN)?;")] - /// - /// assert_eq!((pos, false), pos.overflowing_abs()); - /// assert_eq!((pos, false), neg.overflowing_abs()); - /// assert_eq!((min, true), min.overflowing_abs()); - /// # Some(()) - /// # } - /// ``` - #[stable(feature = "nonzero_checked_ops", since = "1.64.0")] - #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn overflowing_abs(self) -> (Self, bool) { - let (nz, flag) = self.get().overflowing_abs(); - ( - // SAFETY: absolute value of nonzero cannot yield zero values. - unsafe { Self::new_unchecked(nz) }, - flag, - ) - } - - /// Saturating absolute value, see - #[doc = concat!("[`", stringify!($Int), "::saturating_abs`].")] - /// - /// # Example - /// - /// ``` - /// # use std::num::NonZero; - /// # - /// # fn main() { test().unwrap(); } - /// # fn test() -> Option<()> { - #[doc = concat!("let pos = NonZero::new(1", stringify!($Int), ")?;")] - #[doc = concat!("let neg = NonZero::new(-1", stringify!($Int), ")?;")] - #[doc = concat!("let min = NonZero::new(", stringify!($Int), "::MIN)?;")] - #[doc = concat!("let min_plus = NonZero::new(", stringify!($Int), "::MIN + 1)?;")] - #[doc = concat!("let max = NonZero::new(", stringify!($Int), "::MAX)?;")] - /// - /// assert_eq!(pos, pos.saturating_abs()); - /// assert_eq!(pos, neg.saturating_abs()); - /// assert_eq!(max, min.saturating_abs()); - /// assert_eq!(max, min_plus.saturating_abs()); - /// # Some(()) - /// # } - /// ``` - #[stable(feature = "nonzero_checked_ops", since = "1.64.0")] - #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn saturating_abs(self) -> Self { - // SAFETY: absolute value of nonzero cannot yield zero values. - unsafe { Self::new_unchecked(self.get().saturating_abs()) } - } - - /// Wrapping absolute value, see - #[doc = concat!("[`", stringify!($Int), "::wrapping_abs`].")] - /// - /// # Example - /// - /// ``` - /// # use std::num::NonZero; - /// # - /// # fn main() { test().unwrap(); } - /// # fn test() -> Option<()> { - #[doc = concat!("let pos = NonZero::new(1", stringify!($Int), ")?;")] - #[doc = concat!("let neg = NonZero::new(-1", stringify!($Int), ")?;")] - #[doc = concat!("let min = NonZero::new(", stringify!($Int), "::MIN)?;")] - #[doc = concat!("# let max = NonZero::new(", stringify!($Int), "::MAX)?;")] - /// - /// assert_eq!(pos, pos.wrapping_abs()); - /// assert_eq!(pos, neg.wrapping_abs()); - /// assert_eq!(min, min.wrapping_abs()); - /// assert_eq!(max, (-max).wrapping_abs()); - /// # Some(()) - /// # } - /// ``` - #[stable(feature = "nonzero_checked_ops", since = "1.64.0")] - #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn wrapping_abs(self) -> Self { - // SAFETY: absolute value of nonzero cannot yield zero values. - unsafe { Self::new_unchecked(self.get().wrapping_abs()) } - } - - /// Computes the absolute value of self - /// without any wrapping or panicking. - /// - /// # Example - /// - /// ``` - /// # use std::num::NonZero; - /// # - /// # fn main() { test().unwrap(); } - /// # fn test() -> Option<()> { - #[doc = concat!("let u_pos = NonZero::new(1", stringify!($Uint), ")?;")] - #[doc = concat!("let i_pos = NonZero::new(1", stringify!($Int), ")?;")] - #[doc = concat!("let i_neg = NonZero::new(-1", stringify!($Int), ")?;")] - #[doc = concat!("let i_min = NonZero::new(", stringify!($Int), "::MIN)?;")] - #[doc = concat!("let u_max = NonZero::new(", stringify!($Uint), "::MAX / 2 + 1)?;")] - /// - /// assert_eq!(u_pos, i_pos.unsigned_abs()); - /// assert_eq!(u_pos, i_neg.unsigned_abs()); - /// assert_eq!(u_max, i_min.unsigned_abs()); - /// # Some(()) - /// # } - /// ``` - #[stable(feature = "nonzero_checked_ops", since = "1.64.0")] - #[rustc_const_stable(feature = "const_nonzero_checked_ops", since = "1.64.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn unsigned_abs(self) -> NonZero<$Uint> { - // SAFETY: absolute value of nonzero cannot yield zero values. - unsafe { NonZero::new_unchecked(self.get().unsigned_abs()) } - } - - /// Returns `true` if `self` is positive and `false` if the - /// number is negative. - /// - /// # Example - /// - /// ``` - /// # use std::num::NonZero; - /// # - /// # fn main() { test().unwrap(); } - /// # fn test() -> Option<()> { - #[doc = concat!("let pos_five = NonZero::new(5", stringify!($Int), ")?;")] - #[doc = concat!("let neg_five = NonZero::new(-5", stringify!($Int), ")?;")] - /// - /// assert!(pos_five.is_positive()); - /// assert!(!neg_five.is_positive()); - /// # Some(()) - /// # } - /// ``` - #[must_use] - #[inline] - #[stable(feature = "nonzero_negation_ops", since = "1.71.0")] - #[rustc_const_stable(feature = "nonzero_negation_ops", since = "1.71.0")] - pub const fn is_positive(self) -> bool { - self.get().is_positive() - } - - /// Returns `true` if `self` is negative and `false` if the - /// number is positive. - /// - /// # Example - /// - /// ``` - /// # use std::num::NonZero; - /// # - /// # fn main() { test().unwrap(); } - /// # fn test() -> Option<()> { - #[doc = concat!("let pos_five = NonZero::new(5", stringify!($Int), ")?;")] - #[doc = concat!("let neg_five = NonZero::new(-5", stringify!($Int), ")?;")] - /// - /// assert!(neg_five.is_negative()); - /// assert!(!pos_five.is_negative()); - /// # Some(()) - /// # } - /// ``` - #[must_use] - #[inline] - #[stable(feature = "nonzero_negation_ops", since = "1.71.0")] - #[rustc_const_stable(feature = "nonzero_negation_ops", since = "1.71.0")] - pub const fn is_negative(self) -> bool { - self.get().is_negative() - } - - /// Checked negation. Computes `-self`, - #[doc = concat!("returning `None` if `self == NonZero::<", stringify!($Int), ">::MIN`.")] - /// - /// # Example - /// - /// ``` - /// # use std::num::NonZero; - /// # - /// # fn main() { test().unwrap(); } - /// # fn test() -> Option<()> { - #[doc = concat!("let pos_five = NonZero::new(5", stringify!($Int), ")?;")] - #[doc = concat!("let neg_five = NonZero::new(-5", stringify!($Int), ")?;")] - #[doc = concat!("let min = NonZero::new(", stringify!($Int), "::MIN)?;")] - /// - /// assert_eq!(pos_five.checked_neg(), Some(neg_five)); - /// assert_eq!(min.checked_neg(), None); - /// # Some(()) - /// # } - /// ``` - #[inline] - #[stable(feature = "nonzero_negation_ops", since = "1.71.0")] - #[rustc_const_stable(feature = "nonzero_negation_ops", since = "1.71.0")] - pub const fn checked_neg(self) -> Option { - if let Some(result) = self.get().checked_neg() { - // SAFETY: negation of nonzero cannot yield zero values. - return Some(unsafe { Self::new_unchecked(result) }); - } - None - } - - /// Negates self, overflowing if this is equal to the minimum value. - /// - #[doc = concat!("See [`", stringify!($Int), "::overflowing_neg`]")] - /// for documentation on overflow behaviour. - /// - /// # Example - /// - /// ``` - /// # use std::num::NonZero; - /// # - /// # fn main() { test().unwrap(); } - /// # fn test() -> Option<()> { - #[doc = concat!("let pos_five = NonZero::new(5", stringify!($Int), ")?;")] - #[doc = concat!("let neg_five = NonZero::new(-5", stringify!($Int), ")?;")] - #[doc = concat!("let min = NonZero::new(", stringify!($Int), "::MIN)?;")] - /// - /// assert_eq!(pos_five.overflowing_neg(), (neg_five, false)); - /// assert_eq!(min.overflowing_neg(), (min, true)); - /// # Some(()) - /// # } - /// ``` - #[inline] - #[stable(feature = "nonzero_negation_ops", since = "1.71.0")] - #[rustc_const_stable(feature = "nonzero_negation_ops", since = "1.71.0")] - pub const fn overflowing_neg(self) -> (Self, bool) { - let (result, overflow) = self.get().overflowing_neg(); - // SAFETY: negation of nonzero cannot yield zero values. - ((unsafe { Self::new_unchecked(result) }), overflow) - } - - /// Saturating negation. Computes `-self`, - #[doc = concat!("returning [`NonZero::<", stringify!($Int), ">::MAX`]")] - #[doc = concat!("if `self == NonZero::<", stringify!($Int), ">::MIN`")] - /// instead of overflowing. - /// - /// # Example - /// - /// ``` - /// # use std::num::NonZero; - /// # - /// # fn main() { test().unwrap(); } - /// # fn test() -> Option<()> { - #[doc = concat!("let pos_five = NonZero::new(5", stringify!($Int), ")?;")] - #[doc = concat!("let neg_five = NonZero::new(-5", stringify!($Int), ")?;")] - #[doc = concat!("let min = NonZero::new(", stringify!($Int), "::MIN)?;")] - #[doc = concat!("let min_plus_one = NonZero::new(", stringify!($Int), "::MIN + 1)?;")] - #[doc = concat!("let max = NonZero::new(", stringify!($Int), "::MAX)?;")] - /// - /// assert_eq!(pos_five.saturating_neg(), neg_five); - /// assert_eq!(min.saturating_neg(), max); - /// assert_eq!(max.saturating_neg(), min_plus_one); - /// # Some(()) - /// # } - /// ``` - #[inline] - #[stable(feature = "nonzero_negation_ops", since = "1.71.0")] - #[rustc_const_stable(feature = "nonzero_negation_ops", since = "1.71.0")] - pub const fn saturating_neg(self) -> Self { - if let Some(result) = self.checked_neg() { - return result; - } - Self::MAX - } - - /// Wrapping (modular) negation. Computes `-self`, wrapping around at the boundary - /// of the type. - /// - #[doc = concat!("See [`", stringify!($Int), "::wrapping_neg`]")] - /// for documentation on overflow behaviour. - /// - /// # Example - /// - /// ``` - /// # use std::num::NonZero; - /// # - /// # fn main() { test().unwrap(); } - /// # fn test() -> Option<()> { - #[doc = concat!("let pos_five = NonZero::new(5", stringify!($Int), ")?;")] - #[doc = concat!("let neg_five = NonZero::new(-5", stringify!($Int), ")?;")] - #[doc = concat!("let min = NonZero::new(", stringify!($Int), "::MIN)?;")] - /// - /// assert_eq!(pos_five.wrapping_neg(), neg_five); - /// assert_eq!(min.wrapping_neg(), min); - /// # Some(()) - /// # } - /// ``` - #[inline] - #[stable(feature = "nonzero_negation_ops", since = "1.71.0")] - #[rustc_const_stable(feature = "nonzero_negation_ops", since = "1.71.0")] - pub const fn wrapping_neg(self) -> Self { - let result = self.get().wrapping_neg(); - // SAFETY: negation of nonzero cannot yield zero values. - unsafe { Self::new_unchecked(result) } - } - }; -} - -// Use this when the generated code should differ between signed and unsigned types. -macro_rules! sign_dependent_expr { - (signed ? if signed { $signed_case:expr } if unsigned { $unsigned_case:expr } ) => { - $signed_case - }; - (unsigned ? if signed { $signed_case:expr } if unsigned { $unsigned_case:expr } ) => { - $unsigned_case - }; -} - -nonzero_integer! { - Self = NonZeroU8, - Primitive = unsigned u8, -} - -nonzero_integer! { - Self = NonZeroU16, - Primitive = unsigned u16, -} - -nonzero_integer! { - Self = NonZeroU32, - Primitive = unsigned u32, -} - -nonzero_integer! { - Self = NonZeroU64, - Primitive = unsigned u64, -} - -nonzero_integer! { - Self = NonZeroU128, - Primitive = unsigned u128, -} - -nonzero_integer! { - Self = NonZeroUsize, - Primitive = unsigned usize, -} - -nonzero_integer! { - Self = NonZeroI8, - Primitive = signed i8, - UnsignedPrimitive = u8, -} - -nonzero_integer! { - Self = NonZeroI16, - Primitive = signed i16, - UnsignedPrimitive = u16, -} - -nonzero_integer! { - Self = NonZeroI32, - Primitive = signed i32, - UnsignedPrimitive = u32, -} - -nonzero_integer! { - Self = NonZeroI64, - Primitive = signed i64, - UnsignedPrimitive = u64, -} - -nonzero_integer! { - Self = NonZeroI128, - Primitive = signed i128, - UnsignedPrimitive = u128, -} - -nonzero_integer! { - Self = NonZeroIsize, - Primitive = signed isize, - UnsignedPrimitive = usize, -} diff --git a/library/core/src/num/overflow_panic.rs b/library/core/src/num/overflow_panic.rs deleted file mode 100644 index 203037ffb43ea..0000000000000 --- a/library/core/src/num/overflow_panic.rs +++ /dev/null @@ -1,51 +0,0 @@ -//! Functions for panicking on overflow. -//! -//! In particular, these are used by the `strict_` methods on integers. - -#[cold] -#[track_caller] -pub const fn add() -> ! { - panic!("attempt to add with overflow") -} - -#[cold] -#[track_caller] -pub const fn sub() -> ! { - panic!("attempt to subtract with overflow") -} - -#[cold] -#[track_caller] -pub const fn mul() -> ! { - panic!("attempt to multiply with overflow") -} - -#[cold] -#[track_caller] -pub const fn div() -> ! { - panic!("attempt to divide with overflow") -} - -#[cold] -#[track_caller] -pub const fn rem() -> ! { - panic!("attempt to calculate the remainder with overflow") -} - -#[cold] -#[track_caller] -pub const fn neg() -> ! { - panic!("attempt to negate with overflow") -} - -#[cold] -#[track_caller] -pub const fn shr() -> ! { - panic!("attempt to shift right with overflow") -} - -#[cold] -#[track_caller] -pub const fn shl() -> ! { - panic!("attempt to shift left with overflow") -} diff --git a/library/core/src/num/saturating.rs b/library/core/src/num/saturating.rs deleted file mode 100644 index d040539ebe556..0000000000000 --- a/library/core/src/num/saturating.rs +++ /dev/null @@ -1,1077 +0,0 @@ -//! Definitions of `Saturating`. - -use crate::fmt; -use crate::ops::{Add, AddAssign, BitAnd, BitAndAssign, BitOr, BitOrAssign}; -use crate::ops::{BitXor, BitXorAssign, Div, DivAssign}; -use crate::ops::{Mul, MulAssign, Neg, Not, Rem, RemAssign}; -use crate::ops::{Sub, SubAssign}; - -/// Provides intentionally-saturating arithmetic on `T`. -/// -/// Operations like `+` on `u32` values are intended to never overflow, -/// and in some debug configurations overflow is detected and results -/// in a panic. While most arithmetic falls into this category, some -/// code explicitly expects and relies upon saturating arithmetic. -/// -/// Saturating arithmetic can be achieved either through methods like -/// `saturating_add`, or through the `Saturating` type, which says that -/// all standard arithmetic operations on the underlying value are -/// intended to have saturating semantics. -/// -/// The underlying value can be retrieved through the `.0` index of the -/// `Saturating` tuple. -/// -/// # Examples -/// -/// ``` -/// use std::num::Saturating; -/// -/// let max = Saturating(u32::MAX); -/// let one = Saturating(1u32); -/// -/// assert_eq!(u32::MAX, (max + one).0); -/// ``` -#[stable(feature = "saturating_int_impl", since = "1.74.0")] -#[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Copy, Default, Hash)] -#[repr(transparent)] -#[rustc_diagnostic_item = "Saturating"] -pub struct Saturating(#[stable(feature = "saturating_int_impl", since = "1.74.0")] pub T); - -#[stable(feature = "saturating_int_impl", since = "1.74.0")] -impl fmt::Debug for Saturating { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0.fmt(f) - } -} - -#[stable(feature = "saturating_int_impl", since = "1.74.0")] -impl fmt::Display for Saturating { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0.fmt(f) - } -} - -#[stable(feature = "saturating_int_impl", since = "1.74.0")] -impl fmt::Binary for Saturating { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0.fmt(f) - } -} - -#[stable(feature = "saturating_int_impl", since = "1.74.0")] -impl fmt::Octal for Saturating { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0.fmt(f) - } -} - -#[stable(feature = "saturating_int_impl", since = "1.74.0")] -impl fmt::LowerHex for Saturating { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0.fmt(f) - } -} - -#[stable(feature = "saturating_int_impl", since = "1.74.0")] -impl fmt::UpperHex for Saturating { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0.fmt(f) - } -} - -// FIXME the correct implementation is not clear. Waiting for a real world use case at https://github.com/rust-lang/libs-team/issues/230 -// -// #[allow(unused_macros)] -// macro_rules! sh_impl_signed { -// ($t:ident, $f:ident) => { -// // FIXME what is the correct implementation here? see discussion https://github.com/rust-lang/rust/pull/87921#discussion_r695870065 -// // -// // #[unstable(feature = "saturating_int_impl", issue = "87920")] -// // impl Shl<$f> for Saturating<$t> { -// // type Output = Saturating<$t>; -// // -// // #[inline] -// // fn shl(self, other: $f) -> Saturating<$t> { -// // if other < 0 { -// // Saturating(self.0.shr((-other & self::shift_max::$t as $f) as u32)) -// // } else { -// // Saturating(self.0.shl((other & self::shift_max::$t as $f) as u32)) -// // } -// // } -// // } -// // forward_ref_binop! { impl Shl, shl for Saturating<$t>, $f, -// // #[unstable(feature = "saturating_int_impl", issue = "87920")] } -// // -// // #[unstable(feature = "saturating_int_impl", issue = "87920")] -// // impl ShlAssign<$f> for Saturating<$t> { -// // #[inline] -// // fn shl_assign(&mut self, other: $f) { -// // *self = *self << other; -// // } -// // } -// // forward_ref_op_assign! { impl ShlAssign, shl_assign for Saturating<$t>, $f } -// -// #[unstable(feature = "saturating_int_impl", issue = "87920")] -// impl Shr<$f> for Saturating<$t> { -// type Output = Saturating<$t>; -// -// #[inline] -// fn shr(self, other: $f) -> Saturating<$t> { -// if other < 0 { -// Saturating(self.0.shl((-other & self::shift_max::$t as $f) as u32)) -// } else { -// Saturating(self.0.shr((other & self::shift_max::$t as $f) as u32)) -// } -// } -// } -// forward_ref_binop! { impl Shr, shr for Saturating<$t>, $f, -// #[unstable(feature = "saturating_int_impl", issue = "87920")] } -// -// #[unstable(feature = "saturating_int_impl", issue = "87920")] -// impl ShrAssign<$f> for Saturating<$t> { -// #[inline] -// fn shr_assign(&mut self, other: $f) { -// *self = *self >> other; -// } -// } -// forward_ref_op_assign! { impl ShrAssign, shr_assign for Saturating<$t>, $f } -// }; -// } -// -// macro_rules! sh_impl_unsigned { -// ($t:ident, $f:ident) => { -// #[unstable(feature = "saturating_int_impl", issue = "87920")] -// impl Shl<$f> for Saturating<$t> { -// type Output = Saturating<$t>; -// -// #[inline] -// fn shl(self, other: $f) -> Saturating<$t> { -// Saturating(self.0.wrapping_shl(other as u32)) -// } -// } -// forward_ref_binop! { impl Shl, shl for Saturating<$t>, $f, -// #[unstable(feature = "saturating_int_impl", issue = "87920")] } -// -// #[unstable(feature = "saturating_int_impl", issue = "87920")] -// impl ShlAssign<$f> for Saturating<$t> { -// #[inline] -// fn shl_assign(&mut self, other: $f) { -// *self = *self << other; -// } -// } -// forward_ref_op_assign! { impl ShlAssign, shl_assign for Saturating<$t>, $f } -// -// #[unstable(feature = "saturating_int_impl", issue = "87920")] -// impl Shr<$f> for Saturating<$t> { -// type Output = Saturating<$t>; -// -// #[inline] -// fn shr(self, other: $f) -> Saturating<$t> { -// Saturating(self.0.wrapping_shr(other as u32)) -// } -// } -// forward_ref_binop! { impl Shr, shr for Saturating<$t>, $f, -// #[unstable(feature = "saturating_int_impl", issue = "87920")] } -// -// #[unstable(feature = "saturating_int_impl", issue = "87920")] -// impl ShrAssign<$f> for Saturating<$t> { -// #[inline] -// fn shr_assign(&mut self, other: $f) { -// *self = *self >> other; -// } -// } -// forward_ref_op_assign! { impl ShrAssign, shr_assign for Saturating<$t>, $f } -// }; -// } -// -// // FIXME (#23545): uncomment the remaining impls -// macro_rules! sh_impl_all { -// ($($t:ident)*) => ($( -// //sh_impl_unsigned! { $t, u8 } -// //sh_impl_unsigned! { $t, u16 } -// //sh_impl_unsigned! { $t, u32 } -// //sh_impl_unsigned! { $t, u64 } -// //sh_impl_unsigned! { $t, u128 } -// sh_impl_unsigned! { $t, usize } -// -// //sh_impl_signed! { $t, i8 } -// //sh_impl_signed! { $t, i16 } -// //sh_impl_signed! { $t, i32 } -// //sh_impl_signed! { $t, i64 } -// //sh_impl_signed! { $t, i128 } -// //sh_impl_signed! { $t, isize } -// )*) -// } -// -// sh_impl_all! { u8 u16 u32 u64 u128 usize i8 i16 i32 i64 i128 isize } - -// FIXME(30524): impl Op for Saturating, impl OpAssign for Saturating -macro_rules! saturating_impl { - ($($t:ty)*) => ($( - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - impl Add for Saturating<$t> { - type Output = Saturating<$t>; - - #[inline] - fn add(self, other: Saturating<$t>) -> Saturating<$t> { - Saturating(self.0.saturating_add(other.0)) - } - } - forward_ref_binop! { impl Add, add for Saturating<$t>, Saturating<$t>, - #[stable(feature = "saturating_int_impl", since = "1.74.0")] } - - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - impl AddAssign for Saturating<$t> { - #[inline] - fn add_assign(&mut self, other: Saturating<$t>) { - *self = *self + other; - } - } - forward_ref_op_assign! { impl AddAssign, add_assign for Saturating<$t>, Saturating<$t> } - - #[stable(feature = "saturating_int_assign_impl", since = "1.74.0")] - impl AddAssign<$t> for Saturating<$t> { - #[inline] - fn add_assign(&mut self, other: $t) { - *self = *self + Saturating(other); - } - } - forward_ref_op_assign! { impl AddAssign, add_assign for Saturating<$t>, $t } - - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - impl Sub for Saturating<$t> { - type Output = Saturating<$t>; - - #[inline] - fn sub(self, other: Saturating<$t>) -> Saturating<$t> { - Saturating(self.0.saturating_sub(other.0)) - } - } - forward_ref_binop! { impl Sub, sub for Saturating<$t>, Saturating<$t>, - #[stable(feature = "saturating_int_impl", since = "1.74.0")] } - - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - impl SubAssign for Saturating<$t> { - #[inline] - fn sub_assign(&mut self, other: Saturating<$t>) { - *self = *self - other; - } - } - forward_ref_op_assign! { impl SubAssign, sub_assign for Saturating<$t>, Saturating<$t> } - - #[stable(feature = "saturating_int_assign_impl", since = "1.74.0")] - impl SubAssign<$t> for Saturating<$t> { - #[inline] - fn sub_assign(&mut self, other: $t) { - *self = *self - Saturating(other); - } - } - forward_ref_op_assign! { impl SubAssign, sub_assign for Saturating<$t>, $t } - - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - impl Mul for Saturating<$t> { - type Output = Saturating<$t>; - - #[inline] - fn mul(self, other: Saturating<$t>) -> Saturating<$t> { - Saturating(self.0.saturating_mul(other.0)) - } - } - forward_ref_binop! { impl Mul, mul for Saturating<$t>, Saturating<$t>, - #[stable(feature = "saturating_int_impl", since = "1.74.0")] } - - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - impl MulAssign for Saturating<$t> { - #[inline] - fn mul_assign(&mut self, other: Saturating<$t>) { - *self = *self * other; - } - } - forward_ref_op_assign! { impl MulAssign, mul_assign for Saturating<$t>, Saturating<$t> } - - #[stable(feature = "saturating_int_assign_impl", since = "1.74.0")] - impl MulAssign<$t> for Saturating<$t> { - #[inline] - fn mul_assign(&mut self, other: $t) { - *self = *self * Saturating(other); - } - } - forward_ref_op_assign! { impl MulAssign, mul_assign for Saturating<$t>, $t } - - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Saturating; - /// - #[doc = concat!("assert_eq!(Saturating(2", stringify!($t), "), Saturating(5", stringify!($t), ") / Saturating(2));")] - #[doc = concat!("assert_eq!(Saturating(", stringify!($t), "::MAX), Saturating(", stringify!($t), "::MAX) / Saturating(1));")] - #[doc = concat!("assert_eq!(Saturating(", stringify!($t), "::MIN), Saturating(", stringify!($t), "::MIN) / Saturating(1));")] - /// ``` - /// - /// ```should_panic - /// use std::num::Saturating; - /// - #[doc = concat!("let _ = Saturating(0", stringify!($t), ") / Saturating(0);")] - /// ``` - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - impl Div for Saturating<$t> { - type Output = Saturating<$t>; - - #[inline] - fn div(self, other: Saturating<$t>) -> Saturating<$t> { - Saturating(self.0.saturating_div(other.0)) - } - } - forward_ref_binop! { impl Div, div for Saturating<$t>, Saturating<$t>, - #[stable(feature = "saturating_int_impl", since = "1.74.0")] } - - - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - impl DivAssign for Saturating<$t> { - #[inline] - fn div_assign(&mut self, other: Saturating<$t>) { - *self = *self / other; - } - } - forward_ref_op_assign! { impl DivAssign, div_assign for Saturating<$t>, Saturating<$t> } - - #[stable(feature = "saturating_int_assign_impl", since = "1.74.0")] - impl DivAssign<$t> for Saturating<$t> { - #[inline] - fn div_assign(&mut self, other: $t) { - *self = *self / Saturating(other); - } - } - forward_ref_op_assign! { impl DivAssign, div_assign for Saturating<$t>, $t } - - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - impl Rem for Saturating<$t> { - type Output = Saturating<$t>; - - #[inline] - fn rem(self, other: Saturating<$t>) -> Saturating<$t> { - Saturating(self.0.rem(other.0)) - } - } - forward_ref_binop! { impl Rem, rem for Saturating<$t>, Saturating<$t>, - #[stable(feature = "saturating_int_impl", since = "1.74.0")] } - - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - impl RemAssign for Saturating<$t> { - #[inline] - fn rem_assign(&mut self, other: Saturating<$t>) { - *self = *self % other; - } - } - forward_ref_op_assign! { impl RemAssign, rem_assign for Saturating<$t>, Saturating<$t> } - - #[stable(feature = "saturating_int_assign_impl", since = "1.74.0")] - impl RemAssign<$t> for Saturating<$t> { - #[inline] - fn rem_assign(&mut self, other: $t) { - *self = *self % Saturating(other); - } - } - forward_ref_op_assign! { impl RemAssign, rem_assign for Saturating<$t>, $t } - - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - impl Not for Saturating<$t> { - type Output = Saturating<$t>; - - #[inline] - fn not(self) -> Saturating<$t> { - Saturating(!self.0) - } - } - forward_ref_unop! { impl Not, not for Saturating<$t>, - #[stable(feature = "saturating_int_impl", since = "1.74.0")] } - - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - impl BitXor for Saturating<$t> { - type Output = Saturating<$t>; - - #[inline] - fn bitxor(self, other: Saturating<$t>) -> Saturating<$t> { - Saturating(self.0 ^ other.0) - } - } - forward_ref_binop! { impl BitXor, bitxor for Saturating<$t>, Saturating<$t>, - #[stable(feature = "saturating_int_impl", since = "1.74.0")] } - - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - impl BitXorAssign for Saturating<$t> { - #[inline] - fn bitxor_assign(&mut self, other: Saturating<$t>) { - *self = *self ^ other; - } - } - forward_ref_op_assign! { impl BitXorAssign, bitxor_assign for Saturating<$t>, Saturating<$t> } - - #[stable(feature = "saturating_int_assign_impl", since = "1.74.0")] - impl BitXorAssign<$t> for Saturating<$t> { - #[inline] - fn bitxor_assign(&mut self, other: $t) { - *self = *self ^ Saturating(other); - } - } - forward_ref_op_assign! { impl BitXorAssign, bitxor_assign for Saturating<$t>, $t } - - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - impl BitOr for Saturating<$t> { - type Output = Saturating<$t>; - - #[inline] - fn bitor(self, other: Saturating<$t>) -> Saturating<$t> { - Saturating(self.0 | other.0) - } - } - forward_ref_binop! { impl BitOr, bitor for Saturating<$t>, Saturating<$t>, - #[stable(feature = "saturating_int_impl", since = "1.74.0")] } - - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - impl BitOrAssign for Saturating<$t> { - #[inline] - fn bitor_assign(&mut self, other: Saturating<$t>) { - *self = *self | other; - } - } - forward_ref_op_assign! { impl BitOrAssign, bitor_assign for Saturating<$t>, Saturating<$t> } - - #[stable(feature = "saturating_int_assign_impl", since = "1.74.0")] - impl BitOrAssign<$t> for Saturating<$t> { - #[inline] - fn bitor_assign(&mut self, other: $t) { - *self = *self | Saturating(other); - } - } - forward_ref_op_assign! { impl BitOrAssign, bitor_assign for Saturating<$t>, $t } - - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - impl BitAnd for Saturating<$t> { - type Output = Saturating<$t>; - - #[inline] - fn bitand(self, other: Saturating<$t>) -> Saturating<$t> { - Saturating(self.0 & other.0) - } - } - forward_ref_binop! { impl BitAnd, bitand for Saturating<$t>, Saturating<$t>, - #[stable(feature = "saturating_int_impl", since = "1.74.0")] } - - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - impl BitAndAssign for Saturating<$t> { - #[inline] - fn bitand_assign(&mut self, other: Saturating<$t>) { - *self = *self & other; - } - } - forward_ref_op_assign! { impl BitAndAssign, bitand_assign for Saturating<$t>, Saturating<$t> } - - #[stable(feature = "saturating_int_assign_impl", since = "1.74.0")] - impl BitAndAssign<$t> for Saturating<$t> { - #[inline] - fn bitand_assign(&mut self, other: $t) { - *self = *self & Saturating(other); - } - } - forward_ref_op_assign! { impl BitAndAssign, bitand_assign for Saturating<$t>, $t } - - )*) -} - -saturating_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 } - -macro_rules! saturating_int_impl { - ($($t:ty)*) => ($( - impl Saturating<$t> { - /// Returns the smallest value that can be represented by this integer type. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Saturating; - /// - #[doc = concat!("assert_eq!(>::MIN, Saturating(", stringify!($t), "::MIN));")] - /// ``` - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - pub const MIN: Self = Self(<$t>::MIN); - - /// Returns the largest value that can be represented by this integer type. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Saturating; - /// - #[doc = concat!("assert_eq!(>::MAX, Saturating(", stringify!($t), "::MAX));")] - /// ``` - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - pub const MAX: Self = Self(<$t>::MAX); - - /// Returns the size of this integer type in bits. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Saturating; - /// - #[doc = concat!("assert_eq!(>::BITS, ", stringify!($t), "::BITS);")] - /// ``` - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - pub const BITS: u32 = <$t>::BITS; - - /// Returns the number of ones in the binary representation of `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Saturating; - /// - #[doc = concat!("let n = Saturating(0b01001100", stringify!($t), ");")] - /// - /// assert_eq!(n.count_ones(), 3); - /// ``` - #[inline] - #[doc(alias = "popcount")] - #[doc(alias = "popcnt")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[rustc_const_stable(feature = "saturating_int_impl", since = "1.74.0")] - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - pub const fn count_ones(self) -> u32 { - self.0.count_ones() - } - - /// Returns the number of zeros in the binary representation of `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Saturating; - /// - #[doc = concat!("assert_eq!(Saturating(!0", stringify!($t), ").count_zeros(), 0);")] - /// ``` - #[inline] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[rustc_const_stable(feature = "saturating_int_impl", since = "1.74.0")] - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - pub const fn count_zeros(self) -> u32 { - self.0.count_zeros() - } - - /// Returns the number of trailing zeros in the binary representation of `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Saturating; - /// - #[doc = concat!("let n = Saturating(0b0101000", stringify!($t), ");")] - /// - /// assert_eq!(n.trailing_zeros(), 3); - /// ``` - #[inline] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[rustc_const_stable(feature = "saturating_int_impl", since = "1.74.0")] - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - pub const fn trailing_zeros(self) -> u32 { - self.0.trailing_zeros() - } - - /// Shifts the bits to the left by a specified amount, `n`, - /// saturating the truncated bits to the end of the resulting - /// integer. - /// - /// Please note this isn't the same operation as the `<<` shifting - /// operator! - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Saturating; - /// - /// let n: Saturating = Saturating(0x0123456789ABCDEF); - /// let m: Saturating = Saturating(-0x76543210FEDCBA99); - /// - /// assert_eq!(n.rotate_left(32), m); - /// ``` - #[inline] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[rustc_const_stable(feature = "saturating_int_impl", since = "1.74.0")] - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - pub const fn rotate_left(self, n: u32) -> Self { - Saturating(self.0.rotate_left(n)) - } - - /// Shifts the bits to the right by a specified amount, `n`, - /// saturating the truncated bits to the beginning of the resulting - /// integer. - /// - /// Please note this isn't the same operation as the `>>` shifting - /// operator! - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Saturating; - /// - /// let n: Saturating = Saturating(0x0123456789ABCDEF); - /// let m: Saturating = Saturating(-0xFEDCBA987654322); - /// - /// assert_eq!(n.rotate_right(4), m); - /// ``` - #[inline] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[rustc_const_stable(feature = "saturating_int_impl", since = "1.74.0")] - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - pub const fn rotate_right(self, n: u32) -> Self { - Saturating(self.0.rotate_right(n)) - } - - /// Reverses the byte order of the integer. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Saturating; - /// - /// let n: Saturating = Saturating(0b0000000_01010101); - /// assert_eq!(n, Saturating(85)); - /// - /// let m = n.swap_bytes(); - /// - /// assert_eq!(m, Saturating(0b01010101_00000000)); - /// assert_eq!(m, Saturating(21760)); - /// ``` - #[inline] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[rustc_const_stable(feature = "saturating_int_impl", since = "1.74.0")] - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - pub const fn swap_bytes(self) -> Self { - Saturating(self.0.swap_bytes()) - } - - /// Reverses the bit pattern of the integer. - /// - /// # Examples - /// - /// Please note that this example is shared between integer types. - /// Which explains why `i16` is used here. - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Saturating; - /// - /// let n = Saturating(0b0000000_01010101i16); - /// assert_eq!(n, Saturating(85)); - /// - /// let m = n.reverse_bits(); - /// - /// assert_eq!(m.0 as u16, 0b10101010_00000000); - /// assert_eq!(m, Saturating(-22016)); - /// ``` - #[inline] - #[rustc_const_stable(feature = "saturating_int_impl", since = "1.74.0")] - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - pub const fn reverse_bits(self) -> Self { - Saturating(self.0.reverse_bits()) - } - - /// Converts an integer from big endian to the target's endianness. - /// - /// On big endian this is a no-op. On little endian the bytes are - /// swapped. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Saturating; - /// - #[doc = concat!("let n = Saturating(0x1A", stringify!($t), ");")] - /// - /// if cfg!(target_endian = "big") { - #[doc = concat!(" assert_eq!(>::from_be(n), n)")] - /// } else { - #[doc = concat!(" assert_eq!(>::from_be(n), n.swap_bytes())")] - /// } - /// ``` - #[inline] - #[must_use] - #[rustc_const_stable(feature = "saturating_int_impl", since = "1.74.0")] - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - pub const fn from_be(x: Self) -> Self { - Saturating(<$t>::from_be(x.0)) - } - - /// Converts an integer from little endian to the target's endianness. - /// - /// On little endian this is a no-op. On big endian the bytes are - /// swapped. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Saturating; - /// - #[doc = concat!("let n = Saturating(0x1A", stringify!($t), ");")] - /// - /// if cfg!(target_endian = "little") { - #[doc = concat!(" assert_eq!(>::from_le(n), n)")] - /// } else { - #[doc = concat!(" assert_eq!(>::from_le(n), n.swap_bytes())")] - /// } - /// ``` - #[inline] - #[must_use] - #[rustc_const_stable(feature = "saturating_int_impl", since = "1.74.0")] - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - pub const fn from_le(x: Self) -> Self { - Saturating(<$t>::from_le(x.0)) - } - - /// Converts `self` to big endian from the target's endianness. - /// - /// On big endian this is a no-op. On little endian the bytes are - /// swapped. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Saturating; - /// - #[doc = concat!("let n = Saturating(0x1A", stringify!($t), ");")] - /// - /// if cfg!(target_endian = "big") { - /// assert_eq!(n.to_be(), n) - /// } else { - /// assert_eq!(n.to_be(), n.swap_bytes()) - /// } - /// ``` - #[inline] - #[rustc_const_stable(feature = "saturating_int_impl", since = "1.74.0")] - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - pub const fn to_be(self) -> Self { - Saturating(self.0.to_be()) - } - - /// Converts `self` to little endian from the target's endianness. - /// - /// On little endian this is a no-op. On big endian the bytes are - /// swapped. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Saturating; - /// - #[doc = concat!("let n = Saturating(0x1A", stringify!($t), ");")] - /// - /// if cfg!(target_endian = "little") { - /// assert_eq!(n.to_le(), n) - /// } else { - /// assert_eq!(n.to_le(), n.swap_bytes()) - /// } - /// ``` - #[inline] - #[rustc_const_stable(feature = "saturating_int_impl", since = "1.74.0")] - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - pub const fn to_le(self) -> Self { - Saturating(self.0.to_le()) - } - - /// Raises self to the power of `exp`, using exponentiation by squaring. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Saturating; - /// - #[doc = concat!("assert_eq!(Saturating(3", stringify!($t), ").pow(4), Saturating(81));")] - /// ``` - /// - /// Results that are too large are saturated: - /// - /// ``` - /// use std::num::Saturating; - /// - /// assert_eq!(Saturating(3i8).pow(5), Saturating(127)); - /// assert_eq!(Saturating(3i8).pow(6), Saturating(127)); - /// ``` - #[inline] - #[rustc_const_stable(feature = "saturating_int_impl", since = "1.74.0")] - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - pub const fn pow(self, exp: u32) -> Self { - Saturating(self.0.saturating_pow(exp)) - } - } - )*) -} - -saturating_int_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 } - -macro_rules! saturating_int_impl_signed { - ($($t:ty)*) => ($( - impl Saturating<$t> { - /// Returns the number of leading zeros in the binary representation of `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Saturating; - /// - #[doc = concat!("let n = Saturating(", stringify!($t), "::MAX >> 2);")] - /// - /// assert_eq!(n.leading_zeros(), 3); - /// ``` - #[inline] - #[rustc_const_stable(feature = "saturating_int_impl", since = "1.74.0")] - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - pub const fn leading_zeros(self) -> u32 { - self.0.leading_zeros() - } - - /// Saturating absolute value. Computes `self.abs()`, returning `MAX` if `self == MIN` - /// instead of overflowing. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Saturating; - /// - #[doc = concat!("assert_eq!(Saturating(100", stringify!($t), ").abs(), Saturating(100));")] - #[doc = concat!("assert_eq!(Saturating(-100", stringify!($t), ").abs(), Saturating(100));")] - #[doc = concat!("assert_eq!(Saturating(", stringify!($t), "::MIN).abs(), Saturating((", stringify!($t), "::MIN + 1).abs()));")] - #[doc = concat!("assert_eq!(Saturating(", stringify!($t), "::MIN).abs(), Saturating(", stringify!($t), "::MIN.saturating_abs()));")] - #[doc = concat!("assert_eq!(Saturating(", stringify!($t), "::MIN).abs(), Saturating(", stringify!($t), "::MAX));")] - /// ``` - #[inline] - #[rustc_const_stable(feature = "saturating_int_impl", since = "1.74.0")] - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - pub const fn abs(self) -> Saturating<$t> { - Saturating(self.0.saturating_abs()) - } - - /// Returns a number representing sign of `self`. - /// - /// - `0` if the number is zero - /// - `1` if the number is positive - /// - `-1` if the number is negative - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Saturating; - /// - #[doc = concat!("assert_eq!(Saturating(10", stringify!($t), ").signum(), Saturating(1));")] - #[doc = concat!("assert_eq!(Saturating(0", stringify!($t), ").signum(), Saturating(0));")] - #[doc = concat!("assert_eq!(Saturating(-10", stringify!($t), ").signum(), Saturating(-1));")] - /// ``` - #[inline] - #[rustc_const_stable(feature = "saturating_int_impl", since = "1.74.0")] - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - pub const fn signum(self) -> Saturating<$t> { - Saturating(self.0.signum()) - } - - /// Returns `true` if `self` is positive and `false` if the number is zero or - /// negative. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Saturating; - /// - #[doc = concat!("assert!(Saturating(10", stringify!($t), ").is_positive());")] - #[doc = concat!("assert!(!Saturating(-10", stringify!($t), ").is_positive());")] - /// ``` - #[must_use] - #[inline] - #[rustc_const_stable(feature = "saturating_int_impl", since = "1.74.0")] - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - pub const fn is_positive(self) -> bool { - self.0.is_positive() - } - - /// Returns `true` if `self` is negative and `false` if the number is zero or - /// positive. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Saturating; - /// - #[doc = concat!("assert!(Saturating(-10", stringify!($t), ").is_negative());")] - #[doc = concat!("assert!(!Saturating(10", stringify!($t), ").is_negative());")] - /// ``` - #[must_use] - #[inline] - #[rustc_const_stable(feature = "saturating_int_impl", since = "1.74.0")] - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - pub const fn is_negative(self) -> bool { - self.0.is_negative() - } - } - - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - impl Neg for Saturating<$t> { - type Output = Self; - #[inline] - fn neg(self) -> Self { - Saturating(self.0.saturating_neg()) - } - } - forward_ref_unop! { impl Neg, neg for Saturating<$t>, - #[stable(feature = "saturating_int_impl", since = "1.74.0")] } - )*) -} - -saturating_int_impl_signed! { isize i8 i16 i32 i64 i128 } - -macro_rules! saturating_int_impl_unsigned { - ($($t:ty)*) => ($( - impl Saturating<$t> { - /// Returns the number of leading zeros in the binary representation of `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Saturating; - /// - #[doc = concat!("let n = Saturating(", stringify!($t), "::MAX >> 2);")] - /// - /// assert_eq!(n.leading_zeros(), 2); - /// ``` - #[inline] - #[rustc_const_stable(feature = "saturating_int_impl", since = "1.74.0")] - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - pub const fn leading_zeros(self) -> u32 { - self.0.leading_zeros() - } - - /// Returns `true` if and only if `self == 2^k` for some `k`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Saturating; - /// - #[doc = concat!("assert!(Saturating(16", stringify!($t), ").is_power_of_two());")] - #[doc = concat!("assert!(!Saturating(10", stringify!($t), ").is_power_of_two());")] - /// ``` - #[must_use] - #[inline] - #[rustc_const_stable(feature = "saturating_int_impl", since = "1.74.0")] - #[stable(feature = "saturating_int_impl", since = "1.74.0")] - pub const fn is_power_of_two(self) -> bool { - self.0.is_power_of_two() - } - - } - )*) -} - -saturating_int_impl_unsigned! { usize u8 u16 u32 u64 u128 } - -// Related to potential Shl and ShlAssign implementation -// -// mod shift_max { -// #![allow(non_upper_case_globals)] -// -// #[cfg(target_pointer_width = "16")] -// mod platform { -// pub const usize: u32 = super::u16; -// pub const isize: u32 = super::i16; -// } -// -// #[cfg(target_pointer_width = "32")] -// mod platform { -// pub const usize: u32 = super::u32; -// pub const isize: u32 = super::i32; -// } -// -// #[cfg(target_pointer_width = "64")] -// mod platform { -// pub const usize: u32 = super::u64; -// pub const isize: u32 = super::i64; -// } -// -// pub const i8: u32 = (1 << 3) - 1; -// pub const i16: u32 = (1 << 4) - 1; -// pub const i32: u32 = (1 << 5) - 1; -// pub const i64: u32 = (1 << 6) - 1; -// pub const i128: u32 = (1 << 7) - 1; -// pub use self::platform::isize; -// -// pub const u8: u32 = i8; -// pub const u16: u32 = i16; -// pub const u32: u32 = i32; -// pub const u64: u32 = i64; -// pub const u128: u32 = i128; -// pub use self::platform::usize; -// } diff --git a/library/core/src/num/shells/i128.rs b/library/core/src/num/shells/i128.rs deleted file mode 100644 index b3b3d3b4875ab..0000000000000 --- a/library/core/src/num/shells/i128.rs +++ /dev/null @@ -1,11 +0,0 @@ -//! Redundant constants module for the [`i128` primitive type][i128]. -//! -//! New code should use the associated constants directly on the primitive type. - -#![stable(feature = "i128", since = "1.26.0")] -#![deprecated( - since = "TBD", - note = "all constants in this module replaced by associated constants on `i128`" -)] - -int_module! { i128, #[stable(feature = "i128", since="1.26.0")] } diff --git a/library/core/src/num/shells/i16.rs b/library/core/src/num/shells/i16.rs deleted file mode 100644 index 70a452e193983..0000000000000 --- a/library/core/src/num/shells/i16.rs +++ /dev/null @@ -1,11 +0,0 @@ -//! Redundant constants module for the [`i16` primitive type][i16]. -//! -//! New code should use the associated constants directly on the primitive type. - -#![stable(feature = "rust1", since = "1.0.0")] -#![deprecated( - since = "TBD", - note = "all constants in this module replaced by associated constants on `i16`" -)] - -int_module! { i16 } diff --git a/library/core/src/num/shells/i32.rs b/library/core/src/num/shells/i32.rs deleted file mode 100644 index c30849e2591c3..0000000000000 --- a/library/core/src/num/shells/i32.rs +++ /dev/null @@ -1,11 +0,0 @@ -//! Redundant constants module for the [`i32` primitive type][i32]. -//! -//! New code should use the associated constants directly on the primitive type. - -#![stable(feature = "rust1", since = "1.0.0")] -#![deprecated( - since = "TBD", - note = "all constants in this module replaced by associated constants on `i32`" -)] - -int_module! { i32 } diff --git a/library/core/src/num/shells/i64.rs b/library/core/src/num/shells/i64.rs deleted file mode 100644 index 77d95d712506b..0000000000000 --- a/library/core/src/num/shells/i64.rs +++ /dev/null @@ -1,11 +0,0 @@ -//! Redundant constants module for the [`i64` primitive type][i64]. -//! -//! New code should use the associated constants directly on the primitive type. - -#![stable(feature = "rust1", since = "1.0.0")] -#![deprecated( - since = "TBD", - note = "all constants in this module replaced by associated constants on `i64`" -)] - -int_module! { i64 } diff --git a/library/core/src/num/shells/i8.rs b/library/core/src/num/shells/i8.rs deleted file mode 100644 index 516ba8cdef3bf..0000000000000 --- a/library/core/src/num/shells/i8.rs +++ /dev/null @@ -1,11 +0,0 @@ -//! Redundant constants module for the [`i8` primitive type][i8]. -//! -//! New code should use the associated constants directly on the primitive type. - -#![stable(feature = "rust1", since = "1.0.0")] -#![deprecated( - since = "TBD", - note = "all constants in this module replaced by associated constants on `i8`" -)] - -int_module! { i8 } diff --git a/library/core/src/num/shells/int_macros.rs b/library/core/src/num/shells/int_macros.rs deleted file mode 100644 index 8ae9b7abae3bd..0000000000000 --- a/library/core/src/num/shells/int_macros.rs +++ /dev/null @@ -1,46 +0,0 @@ -#![doc(hidden)] - -macro_rules! int_module { - ($T:ident) => (int_module!($T, #[stable(feature = "rust1", since = "1.0.0")]);); - ($T:ident, #[$attr:meta]) => ( - #[doc = concat!( - "The smallest value that can be represented by this integer type. Use ", - "[`", stringify!($T), "::MIN", "`] instead." - )] - /// - /// # Examples - /// - /// ```rust - /// // deprecated way - #[doc = concat!("let min = std::", stringify!($T), "::MIN;")] - /// - /// // intended way - #[doc = concat!("let min = ", stringify!($T), "::MIN;")] - /// ``` - /// - #[$attr] - #[deprecated(since = "TBD", note = "replaced by the `MIN` associated constant on this type")] - #[rustc_diagnostic_item = concat!(stringify!($T), "_legacy_const_min")] - pub const MIN: $T = $T::MIN; - - #[doc = concat!( - "The largest value that can be represented by this integer type. Use ", - "[`", stringify!($T), "::MAX", "`] instead." - )] - /// - /// # Examples - /// - /// ```rust - /// // deprecated way - #[doc = concat!("let max = std::", stringify!($T), "::MAX;")] - /// - /// // intended way - #[doc = concat!("let max = ", stringify!($T), "::MAX;")] - /// ``` - /// - #[$attr] - #[deprecated(since = "TBD", note = "replaced by the `MAX` associated constant on this type")] - #[rustc_diagnostic_item = concat!(stringify!($T), "_legacy_const_max")] - pub const MAX: $T = $T::MAX; - ) -} diff --git a/library/core/src/num/shells/isize.rs b/library/core/src/num/shells/isize.rs deleted file mode 100644 index 828f7345bafbe..0000000000000 --- a/library/core/src/num/shells/isize.rs +++ /dev/null @@ -1,11 +0,0 @@ -//! Redundant constants module for the [`isize` primitive type][isize]. -//! -//! New code should use the associated constants directly on the primitive type. - -#![stable(feature = "rust1", since = "1.0.0")] -#![deprecated( - since = "TBD", - note = "all constants in this module replaced by associated constants on `isize`" -)] - -int_module! { isize } diff --git a/library/core/src/num/shells/u128.rs b/library/core/src/num/shells/u128.rs deleted file mode 100644 index b1e30e3843525..0000000000000 --- a/library/core/src/num/shells/u128.rs +++ /dev/null @@ -1,11 +0,0 @@ -//! Redundant constants module for the [`u128` primitive type][u128]. -//! -//! New code should use the associated constants directly on the primitive type. - -#![stable(feature = "i128", since = "1.26.0")] -#![deprecated( - since = "TBD", - note = "all constants in this module replaced by associated constants on `u128`" -)] - -int_module! { u128, #[stable(feature = "i128", since="1.26.0")] } diff --git a/library/core/src/num/shells/u16.rs b/library/core/src/num/shells/u16.rs deleted file mode 100644 index 7394977e5078a..0000000000000 --- a/library/core/src/num/shells/u16.rs +++ /dev/null @@ -1,11 +0,0 @@ -//! Redundant constants module for the [`u16` primitive type][u16]. -//! -//! New code should use the associated constants directly on the primitive type. - -#![stable(feature = "rust1", since = "1.0.0")] -#![deprecated( - since = "TBD", - note = "all constants in this module replaced by associated constants on `u16`" -)] - -int_module! { u16 } diff --git a/library/core/src/num/shells/u32.rs b/library/core/src/num/shells/u32.rs deleted file mode 100644 index 4c84274e752ec..0000000000000 --- a/library/core/src/num/shells/u32.rs +++ /dev/null @@ -1,11 +0,0 @@ -//! Redundant constants module for the [`u32` primitive type][u32]. -//! -//! New code should use the associated constants directly on the primitive type. - -#![stable(feature = "rust1", since = "1.0.0")] -#![deprecated( - since = "TBD", - note = "all constants in this module replaced by associated constants on `u32`" -)] - -int_module! { u32 } diff --git a/library/core/src/num/shells/u64.rs b/library/core/src/num/shells/u64.rs deleted file mode 100644 index 47a95c6820f2f..0000000000000 --- a/library/core/src/num/shells/u64.rs +++ /dev/null @@ -1,11 +0,0 @@ -//! Redundant constants module for the [`u64` primitive type][u64]. -//! -//! New code should use the associated constants directly on the primitive type. - -#![stable(feature = "rust1", since = "1.0.0")] -#![deprecated( - since = "TBD", - note = "all constants in this module replaced by associated constants on `u64`" -)] - -int_module! { u64 } diff --git a/library/core/src/num/shells/u8.rs b/library/core/src/num/shells/u8.rs deleted file mode 100644 index 360baef722869..0000000000000 --- a/library/core/src/num/shells/u8.rs +++ /dev/null @@ -1,11 +0,0 @@ -//! Redundant constants module for the [`u8` primitive type][u8]. -//! -//! New code should use the associated constants directly on the primitive type. - -#![stable(feature = "rust1", since = "1.0.0")] -#![deprecated( - since = "TBD", - note = "all constants in this module replaced by associated constants on `u8`" -)] - -int_module! { u8 } diff --git a/library/core/src/num/shells/usize.rs b/library/core/src/num/shells/usize.rs deleted file mode 100644 index 44c24dfc2cf58..0000000000000 --- a/library/core/src/num/shells/usize.rs +++ /dev/null @@ -1,11 +0,0 @@ -//! Redundant constants module for the [`usize` primitive type][usize]. -//! -//! New code should use the associated constants directly on the primitive type. - -#![stable(feature = "rust1", since = "1.0.0")] -#![deprecated( - since = "TBD", - note = "all constants in this module replaced by associated constants on `usize`" -)] - -int_module! { usize } diff --git a/library/core/src/num/uint_macros.rs b/library/core/src/num/uint_macros.rs deleted file mode 100644 index 446d0658c1262..0000000000000 --- a/library/core/src/num/uint_macros.rs +++ /dev/null @@ -1,3029 +0,0 @@ -macro_rules! uint_impl { - ( - Self = $SelfT:ty, - ActualT = $ActualT:ident, - SignedT = $SignedT:ident, - NonZeroT = $NonZeroT:ty, - - // There are all for use *only* in doc comments. - // As such, they're all passed as literals -- passing them as a string - // literal is fine if they need to be multiple code tokens. - // In non-comments, use the associated constants rather than these. - BITS = $BITS:literal, - MAX = $MaxV:literal, - rot = $rot:literal, - rot_op = $rot_op:literal, - rot_result = $rot_result:literal, - swap_op = $swap_op:literal, - swapped = $swapped:literal, - reversed = $reversed:literal, - le_bytes = $le_bytes:literal, - be_bytes = $be_bytes:literal, - to_xe_bytes_doc = $to_xe_bytes_doc:expr, - from_xe_bytes_doc = $from_xe_bytes_doc:expr, - bound_condition = $bound_condition:literal, - ) => { - /// The smallest value that can be represented by this integer type. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MIN, 0);")] - /// ``` - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const MIN: Self = 0; - - /// The largest value that can be represented by this integer type - #[doc = concat!("(2", $BITS, " − 1", $bound_condition, ").")] - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX, ", stringify!($MaxV), ");")] - /// ``` - #[stable(feature = "assoc_int_consts", since = "1.43.0")] - pub const MAX: Self = !0; - - /// The size of this integer type in bits. - /// - /// # Examples - /// - /// ``` - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::BITS, ", stringify!($BITS), ");")] - /// ``` - #[stable(feature = "int_bits_const", since = "1.53.0")] - pub const BITS: u32 = Self::MAX.count_ones(); - - /// Returns the number of ones in the binary representation of `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = 0b01001100", stringify!($SelfT), ";")] - /// - /// assert_eq!(n.count_ones(), 3); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_math", since = "1.32.0")] - #[doc(alias = "popcount")] - #[doc(alias = "popcnt")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn count_ones(self) -> u32 { - return intrinsics::ctpop(self); - } - - /// Returns the number of zeros in the binary representation of `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.count_zeros(), 0);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_math", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn count_zeros(self) -> u32 { - (!self).count_ones() - } - - /// Returns the number of leading zeros in the binary representation of `self`. - /// - /// Depending on what you're doing with the value, you might also be interested in the - /// [`ilog2`] function which returns a consistent number, even if the type widens. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = ", stringify!($SelfT), "::MAX >> 2;")] - /// - /// assert_eq!(n.leading_zeros(), 2); - /// ``` - #[doc = concat!("[`ilog2`]: ", stringify!($SelfT), "::ilog2")] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_math", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn leading_zeros(self) -> u32 { - return intrinsics::ctlz(self as $ActualT); - } - - /// Returns the number of trailing zeros in the binary representation - /// of `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = 0b0101000", stringify!($SelfT), ";")] - /// - /// assert_eq!(n.trailing_zeros(), 3); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_math", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn trailing_zeros(self) -> u32 { - return intrinsics::cttz(self); - } - - /// Returns the number of leading ones in the binary representation of `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = !(", stringify!($SelfT), "::MAX >> 2);")] - /// - /// assert_eq!(n.leading_ones(), 2); - /// ``` - #[stable(feature = "leading_trailing_ones", since = "1.46.0")] - #[rustc_const_stable(feature = "leading_trailing_ones", since = "1.46.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn leading_ones(self) -> u32 { - (!self).leading_zeros() - } - - /// Returns the number of trailing ones in the binary representation - /// of `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = 0b1010111", stringify!($SelfT), ";")] - /// - /// assert_eq!(n.trailing_ones(), 3); - /// ``` - #[stable(feature = "leading_trailing_ones", since = "1.46.0")] - #[rustc_const_stable(feature = "leading_trailing_ones", since = "1.46.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn trailing_ones(self) -> u32 { - (!self).trailing_zeros() - } - - /// Shifts the bits to the left by a specified amount, `n`, - /// wrapping the truncated bits to the end of the resulting integer. - /// - /// Please note this isn't the same operation as the `<<` shifting operator! - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = ", $rot_op, stringify!($SelfT), ";")] - #[doc = concat!("let m = ", $rot_result, ";")] - /// - #[doc = concat!("assert_eq!(n.rotate_left(", $rot, "), m);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_math", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn rotate_left(self, n: u32) -> Self { - return intrinsics::rotate_left(self, n); - } - - /// Shifts the bits to the right by a specified amount, `n`, - /// wrapping the truncated bits to the beginning of the resulting - /// integer. - /// - /// Please note this isn't the same operation as the `>>` shifting operator! - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = ", $rot_result, stringify!($SelfT), ";")] - #[doc = concat!("let m = ", $rot_op, ";")] - /// - #[doc = concat!("assert_eq!(n.rotate_right(", $rot, "), m);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_math", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn rotate_right(self, n: u32) -> Self { - return intrinsics::rotate_right(self, n); - } - - /// Reverses the byte order of the integer. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = ", $swap_op, stringify!($SelfT), ";")] - /// let m = n.swap_bytes(); - /// - #[doc = concat!("assert_eq!(m, ", $swapped, ");")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_math", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn swap_bytes(self) -> Self { - intrinsics::bswap(self as $ActualT) as Self - } - - /// Reverses the order of bits in the integer. The least significant bit becomes the most significant bit, - /// second least-significant bit becomes second most-significant bit, etc. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = ", $swap_op, stringify!($SelfT), ";")] - /// let m = n.reverse_bits(); - /// - #[doc = concat!("assert_eq!(m, ", $reversed, ");")] - #[doc = concat!("assert_eq!(0, 0", stringify!($SelfT), ".reverse_bits());")] - /// ``` - #[stable(feature = "reverse_bits", since = "1.37.0")] - #[rustc_const_stable(feature = "reverse_bits", since = "1.37.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn reverse_bits(self) -> Self { - intrinsics::bitreverse(self as $ActualT) as Self - } - - /// Converts an integer from big endian to the target's endianness. - /// - /// On big endian this is a no-op. On little endian the bytes are - /// swapped. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")] - /// - /// if cfg!(target_endian = "big") { - #[doc = concat!(" assert_eq!(", stringify!($SelfT), "::from_be(n), n)")] - /// } else { - #[doc = concat!(" assert_eq!(", stringify!($SelfT), "::from_be(n), n.swap_bytes())")] - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_math", since = "1.32.0")] - #[must_use] - #[inline(always)] - pub const fn from_be(x: Self) -> Self { - #[cfg(target_endian = "big")] - { - x - } - #[cfg(not(target_endian = "big"))] - { - x.swap_bytes() - } - } - - /// Converts an integer from little endian to the target's endianness. - /// - /// On little endian this is a no-op. On big endian the bytes are - /// swapped. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")] - /// - /// if cfg!(target_endian = "little") { - #[doc = concat!(" assert_eq!(", stringify!($SelfT), "::from_le(n), n)")] - /// } else { - #[doc = concat!(" assert_eq!(", stringify!($SelfT), "::from_le(n), n.swap_bytes())")] - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_math", since = "1.32.0")] - #[must_use] - #[inline(always)] - pub const fn from_le(x: Self) -> Self { - #[cfg(target_endian = "little")] - { - x - } - #[cfg(not(target_endian = "little"))] - { - x.swap_bytes() - } - } - - /// Converts `self` to big endian from the target's endianness. - /// - /// On big endian this is a no-op. On little endian the bytes are - /// swapped. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")] - /// - /// if cfg!(target_endian = "big") { - /// assert_eq!(n.to_be(), n) - /// } else { - /// assert_eq!(n.to_be(), n.swap_bytes()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_math", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn to_be(self) -> Self { // or not to be? - #[cfg(target_endian = "big")] - { - self - } - #[cfg(not(target_endian = "big"))] - { - self.swap_bytes() - } - } - - /// Converts `self` to little endian from the target's endianness. - /// - /// On little endian this is a no-op. On big endian the bytes are - /// swapped. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("let n = 0x1A", stringify!($SelfT), ";")] - /// - /// if cfg!(target_endian = "little") { - /// assert_eq!(n.to_le(), n) - /// } else { - /// assert_eq!(n.to_le(), n.swap_bytes()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_math", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn to_le(self) -> Self { - #[cfg(target_endian = "little")] - { - self - } - #[cfg(not(target_endian = "little"))] - { - self.swap_bytes() - } - } - - /// Checked integer addition. Computes `self + rhs`, returning `None` - /// if overflow occurred. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!( - "assert_eq!((", stringify!($SelfT), "::MAX - 2).checked_add(1), ", - "Some(", stringify!($SelfT), "::MAX - 1));" - )] - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).checked_add(3), None);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_add(self, rhs: Self) -> Option { - let (a, b) = self.overflowing_add(rhs); - if unlikely!(b) { None } else { Some(a) } - } - - /// Strict integer addition. Computes `self + rhs`, panicking - /// if overflow occurred. - /// - /// # Panics - /// - /// ## Overflow behavior - /// - /// This function will always panic on overflow, regardless of whether overflow checks are enabled. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).strict_add(1), ", stringify!($SelfT), "::MAX - 1);")] - /// ``` - /// - /// The following panics because of overflow: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = (", stringify!($SelfT), "::MAX - 2).strict_add(3);")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn strict_add(self, rhs: Self) -> Self { - let (a, b) = self.overflowing_add(rhs); - if unlikely!(b) { overflow_panic ::add()} else {a} - } - - /// Unchecked integer addition. Computes `self + rhs`, assuming overflow - /// cannot occur. - /// - /// Calling `x.unchecked_add(y)` is semantically equivalent to calling - /// `x.`[`checked_add`]`(y).`[`unwrap_unchecked`]`()`. - /// - /// If you're just trying to avoid the panic in debug mode, then **do not** - /// use this. Instead, you're looking for [`wrapping_add`]. - /// - /// # Safety - /// - /// This results in undefined behavior when - #[doc = concat!("`self + rhs > ", stringify!($SelfT), "::MAX` or `self + rhs < ", stringify!($SelfT), "::MIN`,")] - /// i.e. when [`checked_add`] would return `None`. - /// - /// [`unwrap_unchecked`]: option/enum.Option.html#method.unwrap_unchecked - #[doc = concat!("[`checked_add`]: ", stringify!($SelfT), "::checked_add")] - #[doc = concat!("[`wrapping_add`]: ", stringify!($SelfT), "::wrapping_add")] - #[stable(feature = "unchecked_math", since = "1.79.0")] - #[rustc_const_stable(feature = "unchecked_math", since = "1.79.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn unchecked_add(self, rhs: Self) -> Self { - // SAFETY: the caller must uphold the safety contract for - // `unchecked_add`. - unsafe { intrinsics::unchecked_add(self, rhs) } - } - - /// Checked addition with a signed integer. Computes `self + rhs`, - /// returning `None` if overflow occurred. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".checked_add_signed(2), Some(3));")] - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".checked_add_signed(-2), None);")] - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).checked_add_signed(3), None);")] - /// ``` - #[stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_add_signed(self, rhs: $SignedT) -> Option { - let (a, b) = self.overflowing_add_signed(rhs); - if unlikely!(b) { None } else { Some(a) } - } - - /// Strict addition with a signed integer. Computes `self + rhs`, - /// panicking if overflow occurred. - /// - /// # Panics - /// - /// ## Overflow behavior - /// - /// This function will always panic on overflow, regardless of whether overflow checks are enabled. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".strict_add_signed(2), 3);")] - /// ``` - /// - /// The following panic because of overflow: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = 1", stringify!($SelfT), ".strict_add_signed(-2);")] - /// ``` - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = (", stringify!($SelfT), "::MAX - 2).strict_add_signed(3);")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn strict_add_signed(self, rhs: $SignedT) -> Self { - let (a, b) = self.overflowing_add_signed(rhs); - if unlikely!(b) { overflow_panic ::add()} else {a} - } - - /// Checked integer subtraction. Computes `self - rhs`, returning - /// `None` if overflow occurred. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".checked_sub(1), Some(0));")] - #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".checked_sub(1), None);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_sub(self, rhs: Self) -> Option { - // Per PR#103299, there's no advantage to the `overflowing` intrinsic - // for *unsigned* subtraction and we just emit the manual check anyway. - // Thus, rather than using `overflowing_sub` that produces a wrapping - // subtraction, check it ourself so we can use an unchecked one. - - if self < rhs { - None - } else { - // SAFETY: just checked this can't overflow - Some(unsafe { intrinsics::unchecked_sub(self, rhs) }) - } - } - - /// Strict integer subtraction. Computes `self - rhs`, panicking if - /// overflow occurred. - /// - /// # Panics - /// - /// ## Overflow behavior - /// - /// This function will always panic on overflow, regardless of whether overflow checks are enabled. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".strict_sub(1), 0);")] - /// ``` - /// - /// The following panics because of overflow: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = 0", stringify!($SelfT), ".strict_sub(1);")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn strict_sub(self, rhs: Self) -> Self { - let (a, b) = self.overflowing_sub(rhs); - if unlikely!(b) { overflow_panic ::sub()} else {a} - } - - /// Unchecked integer subtraction. Computes `self - rhs`, assuming overflow - /// cannot occur. - /// - /// Calling `x.unchecked_sub(y)` is semantically equivalent to calling - /// `x.`[`checked_sub`]`(y).`[`unwrap_unchecked`]`()`. - /// - /// If you're just trying to avoid the panic in debug mode, then **do not** - /// use this. Instead, you're looking for [`wrapping_sub`]. - /// - /// If you find yourself writing code like this: - /// - /// ``` - /// # let foo = 30_u32; - /// # let bar = 20; - /// if foo >= bar { - /// // SAFETY: just checked it will not overflow - /// let diff = unsafe { foo.unchecked_sub(bar) }; - /// // ... use diff ... - /// } - /// ``` - /// - /// Consider changing it to - /// - /// ``` - /// # let foo = 30_u32; - /// # let bar = 20; - /// if let Some(diff) = foo.checked_sub(bar) { - /// // ... use diff ... - /// } - /// ``` - /// - /// As that does exactly the same thing -- including telling the optimizer - /// that the subtraction cannot overflow -- but avoids needing `unsafe`. - /// - /// # Safety - /// - /// This results in undefined behavior when - #[doc = concat!("`self - rhs > ", stringify!($SelfT), "::MAX` or `self - rhs < ", stringify!($SelfT), "::MIN`,")] - /// i.e. when [`checked_sub`] would return `None`. - /// - /// [`unwrap_unchecked`]: option/enum.Option.html#method.unwrap_unchecked - #[doc = concat!("[`checked_sub`]: ", stringify!($SelfT), "::checked_sub")] - #[doc = concat!("[`wrapping_sub`]: ", stringify!($SelfT), "::wrapping_sub")] - #[stable(feature = "unchecked_math", since = "1.79.0")] - #[rustc_const_stable(feature = "unchecked_math", since = "1.79.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn unchecked_sub(self, rhs: Self) -> Self { - // SAFETY: the caller must uphold the safety contract for - // `unchecked_sub`. - unsafe { intrinsics::unchecked_sub(self, rhs) } - } - - /// Checked integer multiplication. Computes `self * rhs`, returning - /// `None` if overflow occurred. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_mul(1), Some(5));")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_mul(2), None);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_mul(self, rhs: Self) -> Option { - let (a, b) = self.overflowing_mul(rhs); - if unlikely!(b) { None } else { Some(a) } - } - - /// Strict integer multiplication. Computes `self * rhs`, panicking if - /// overflow occurred. - /// - /// # Panics - /// - /// ## Overflow behavior - /// - /// This function will always panic on overflow, regardless of whether overflow checks are enabled. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".strict_mul(1), 5);")] - /// ``` - /// - /// The following panics because of overflow: - /// - /// ``` should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = ", stringify!($SelfT), "::MAX.strict_mul(2);")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn strict_mul(self, rhs: Self) -> Self { - let (a, b) = self.overflowing_mul(rhs); - if unlikely!(b) { overflow_panic ::mul()} else {a} - } - - /// Unchecked integer multiplication. Computes `self * rhs`, assuming overflow - /// cannot occur. - /// - /// Calling `x.unchecked_mul(y)` is semantically equivalent to calling - /// `x.`[`checked_mul`]`(y).`[`unwrap_unchecked`]`()`. - /// - /// If you're just trying to avoid the panic in debug mode, then **do not** - /// use this. Instead, you're looking for [`wrapping_mul`]. - /// - /// # Safety - /// - /// This results in undefined behavior when - #[doc = concat!("`self * rhs > ", stringify!($SelfT), "::MAX` or `self * rhs < ", stringify!($SelfT), "::MIN`,")] - /// i.e. when [`checked_mul`] would return `None`. - /// - /// [`unwrap_unchecked`]: option/enum.Option.html#method.unwrap_unchecked - #[doc = concat!("[`checked_mul`]: ", stringify!($SelfT), "::checked_mul")] - #[doc = concat!("[`wrapping_mul`]: ", stringify!($SelfT), "::wrapping_mul")] - #[stable(feature = "unchecked_math", since = "1.79.0")] - #[rustc_const_stable(feature = "unchecked_math", since = "1.79.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn unchecked_mul(self, rhs: Self) -> Self { - // SAFETY: the caller must uphold the safety contract for - // `unchecked_mul`. - unsafe { intrinsics::unchecked_mul(self, rhs) } - } - - /// Checked integer division. Computes `self / rhs`, returning `None` - /// if `rhs == 0`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(128", stringify!($SelfT), ".checked_div(2), Some(64));")] - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".checked_div(0), None);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_checked_int_div", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_div(self, rhs: Self) -> Option { - if unlikely!(rhs == 0) { - None - } else { - // SAFETY: div by zero has been checked above and unsigned types have no other - // failure modes for division - Some(unsafe { intrinsics::unchecked_div(self, rhs) }) - } - } - - /// Strict integer division. Computes `self / rhs`. - /// Strict division on unsigned types is just normal division. - /// There's no way overflow could ever happen. - /// This function exists, so that all operations - /// are accounted for in the strict operations. - /// - /// # Panics - /// - /// This function will panic if `rhs` is zero. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".strict_div(10), 10);")] - /// ``` - /// - /// The following panics because of division by zero: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = (1", stringify!($SelfT), ").strict_div(0);")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - #[track_caller] - pub const fn strict_div(self, rhs: Self) -> Self { - self / rhs - } - - /// Checked Euclidean division. Computes `self.div_euclid(rhs)`, returning `None` - /// if `rhs == 0`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(128", stringify!($SelfT), ".checked_div_euclid(2), Some(64));")] - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".checked_div_euclid(0), None);")] - /// ``` - #[stable(feature = "euclidean_division", since = "1.38.0")] - #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_div_euclid(self, rhs: Self) -> Option { - if unlikely!(rhs == 0) { - None - } else { - Some(self.div_euclid(rhs)) - } - } - - /// Strict Euclidean division. Computes `self.div_euclid(rhs)`. - /// Strict division on unsigned types is just normal division. - /// There's no way overflow could ever happen. - /// This function exists, so that all operations - /// are accounted for in the strict operations. - /// Since, for the positive integers, all common - /// definitions of division are equal, this - /// is exactly equal to `self.strict_div(rhs)`. - /// - /// # Panics - /// - /// This function will panic if `rhs` is zero. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".strict_div_euclid(10), 10);")] - /// ``` - /// The following panics because of division by zero: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = (1", stringify!($SelfT), ").strict_div_euclid(0);")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - #[track_caller] - pub const fn strict_div_euclid(self, rhs: Self) -> Self { - self / rhs - } - - /// Checked integer remainder. Computes `self % rhs`, returning `None` - /// if `rhs == 0`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem(2), Some(1));")] - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem(0), None);")] - /// ``` - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_checked_int_div", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_rem(self, rhs: Self) -> Option { - if unlikely!(rhs == 0) { - None - } else { - // SAFETY: div by zero has been checked above and unsigned types have no other - // failure modes for division - Some(unsafe { intrinsics::unchecked_rem(self, rhs) }) - } - } - - /// Strict integer remainder. Computes `self % rhs`. - /// Strict remainder calculation on unsigned types is - /// just the regular remainder calculation. - /// There's no way overflow could ever happen. - /// This function exists, so that all operations - /// are accounted for in the strict operations. - /// - /// # Panics - /// - /// This function will panic if `rhs` is zero. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".strict_rem(10), 0);")] - /// ``` - /// - /// The following panics because of division by zero: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = 5", stringify!($SelfT), ".strict_rem(0);")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - #[track_caller] - pub const fn strict_rem(self, rhs: Self) -> Self { - self % rhs - } - - /// Checked Euclidean modulo. Computes `self.rem_euclid(rhs)`, returning `None` - /// if `rhs == 0`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(2), Some(1));")] - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_rem_euclid(0), None);")] - /// ``` - #[stable(feature = "euclidean_division", since = "1.38.0")] - #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_rem_euclid(self, rhs: Self) -> Option { - if unlikely!(rhs == 0) { - None - } else { - Some(self.rem_euclid(rhs)) - } - } - - /// Strict Euclidean modulo. Computes `self.rem_euclid(rhs)`. - /// Strict modulo calculation on unsigned types is - /// just the regular remainder calculation. - /// There's no way overflow could ever happen. - /// This function exists, so that all operations - /// are accounted for in the strict operations. - /// Since, for the positive integers, all common - /// definitions of division are equal, this - /// is exactly equal to `self.strict_rem(rhs)`. - /// - /// # Panics - /// - /// This function will panic if `rhs` is zero. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".strict_rem_euclid(10), 0);")] - /// ``` - /// - /// The following panics because of division by zero: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = 5", stringify!($SelfT), ".strict_rem_euclid(0);")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - #[track_caller] - pub const fn strict_rem_euclid(self, rhs: Self) -> Self { - self % rhs - } - - /// Returns the logarithm of the number with respect to an arbitrary base, - /// rounded down. - /// - /// This method might not be optimized owing to implementation details; - /// `ilog2` can produce results more efficiently for base 2, and `ilog10` - /// can produce results more efficiently for base 10. - /// - /// # Panics - /// - /// This function will panic if `self` is zero, or if `base` is less than 2. - /// - /// # Examples - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".ilog(5), 1);")] - /// ``` - #[stable(feature = "int_log", since = "1.67.0")] - #[rustc_const_stable(feature = "int_log", since = "1.67.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn ilog(self, base: Self) -> u32 { - assert!(base >= 2, "base of integer logarithm must be at least 2"); - if let Some(log) = self.checked_ilog(base) { - log - } else { - int_log10::panic_for_nonpositive_argument() - } - } - - /// Returns the base 2 logarithm of the number, rounded down. - /// - /// # Panics - /// - /// This function will panic if `self` is zero. - /// - /// # Examples - /// - /// ``` - #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".ilog2(), 1);")] - /// ``` - #[stable(feature = "int_log", since = "1.67.0")] - #[rustc_const_stable(feature = "int_log", since = "1.67.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn ilog2(self) -> u32 { - if let Some(log) = self.checked_ilog2() { - log - } else { - int_log10::panic_for_nonpositive_argument() - } - } - - /// Returns the base 10 logarithm of the number, rounded down. - /// - /// # Panics - /// - /// This function will panic if `self` is zero. - /// - /// # Example - /// - /// ``` - #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".ilog10(), 1);")] - /// ``` - #[stable(feature = "int_log", since = "1.67.0")] - #[rustc_const_stable(feature = "int_log", since = "1.67.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn ilog10(self) -> u32 { - if let Some(log) = self.checked_ilog10() { - log - } else { - int_log10::panic_for_nonpositive_argument() - } - } - - /// Returns the logarithm of the number with respect to an arbitrary base, - /// rounded down. - /// - /// Returns `None` if the number is zero, or if the base is not at least 2. - /// - /// This method might not be optimized owing to implementation details; - /// `checked_ilog2` can produce results more efficiently for base 2, and - /// `checked_ilog10` can produce results more efficiently for base 10. - /// - /// # Examples - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".checked_ilog(5), Some(1));")] - /// ``` - #[stable(feature = "int_log", since = "1.67.0")] - #[rustc_const_stable(feature = "int_log", since = "1.67.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_ilog(self, base: Self) -> Option { - if self <= 0 || base <= 1 { - None - } else { - let mut n = 0; - let mut r = 1; - - // Optimization for 128 bit wide integers. - if Self::BITS == 128 { - // The following is a correct lower bound for ⌊log(base,self)⌋ because - // - // log(base,self) = log(2,self) / log(2,base) - // ≥ ⌊log(2,self)⌋ / (⌊log(2,base)⌋ + 1) - // - // hence - // - // ⌊log(base,self)⌋ ≥ ⌊ ⌊log(2,self)⌋ / (⌊log(2,base)⌋ + 1) ⌋ . - n = self.ilog2() / (base.ilog2() + 1); - r = base.pow(n); - } - - while r <= self / base { - n += 1; - r *= base; - } - Some(n) - } - } - - /// Returns the base 2 logarithm of the number, rounded down. - /// - /// Returns `None` if the number is zero. - /// - /// # Examples - /// - /// ``` - #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".checked_ilog2(), Some(1));")] - /// ``` - #[stable(feature = "int_log", since = "1.67.0")] - #[rustc_const_stable(feature = "int_log", since = "1.67.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_ilog2(self) -> Option { - // FIXME: Simply use `NonZero::new` once it is actually generic. - if let Some(x) = <$NonZeroT>::new(self) { - Some(x.ilog2()) - } else { - None - } - } - - /// Returns the base 10 logarithm of the number, rounded down. - /// - /// Returns `None` if the number is zero. - /// - /// # Examples - /// - /// ``` - #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".checked_ilog10(), Some(1));")] - /// ``` - #[stable(feature = "int_log", since = "1.67.0")] - #[rustc_const_stable(feature = "int_log", since = "1.67.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_ilog10(self) -> Option { - // FIXME: Simply use `NonZero::new` once it is actually generic. - if let Some(x) = <$NonZeroT>::new(self) { - Some(x.ilog10()) - } else { - None - } - } - - /// Checked negation. Computes `-self`, returning `None` unless `self == - /// 0`. - /// - /// Note that negating any positive integer will overflow. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".checked_neg(), Some(0));")] - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".checked_neg(), None);")] - /// ``` - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_neg(self) -> Option { - let (a, b) = self.overflowing_neg(); - if unlikely!(b) { None } else { Some(a) } - } - - /// Strict negation. Computes `-self`, panicking unless `self == - /// 0`. - /// - /// Note that negating any positive integer will overflow. - /// - /// # Panics - /// - /// ## Overflow behavior - /// - /// This function will always panic on overflow, regardless of whether overflow checks are enabled. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".strict_neg(), 0);")] - /// ``` - /// - /// The following panics because of overflow: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = 1", stringify!($SelfT), ".strict_neg();")] - /// - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn strict_neg(self) -> Self { - let (a, b) = self.overflowing_neg(); - if unlikely!(b) { overflow_panic::neg() } else { a } - } - - /// Checked shift left. Computes `self << rhs`, returning `None` - /// if `rhs` is larger than or equal to the number of bits in `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".checked_shl(4), Some(0x10));")] - #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shl(129), None);")] - /// ``` - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")] - // We could always go back to wrapping - #[rustc_allow_const_fn_unstable(unchecked_shifts)] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_shl(self, rhs: u32) -> Option { - // Not using overflowing_shl as that's a wrapping shift - if rhs < Self::BITS { - // SAFETY: just checked the RHS is in-range - Some(unsafe { self.unchecked_shl(rhs) }) - } else { - None - } - } - - /// Strict shift left. Computes `self << rhs`, panicking if `rhs` is larger - /// than or equal to the number of bits in `self`. - /// - /// # Panics - /// - /// ## Overflow behavior - /// - /// This function will always panic on overflow, regardless of whether overflow checks are enabled. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".strict_shl(4), 0x10);")] - /// ``` - /// - /// The following panics because of overflow: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = 0x10", stringify!($SelfT), ".strict_shl(129);")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn strict_shl(self, rhs: u32) -> Self { - let (a, b) = self.overflowing_shl(rhs); - if unlikely!(b) { overflow_panic::shl() } else { a } - } - - /// Unchecked shift left. Computes `self << rhs`, assuming that - /// `rhs` is less than the number of bits in `self`. - /// - /// # Safety - /// - /// This results in undefined behavior if `rhs` is larger than - /// or equal to the number of bits in `self`, - /// i.e. when [`checked_shl`] would return `None`. - /// - #[doc = concat!("[`checked_shl`]: ", stringify!($SelfT), "::checked_shl")] - #[unstable( - feature = "unchecked_shifts", - reason = "niche optimization path", - issue = "85122", - )] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[rustc_const_unstable(feature = "unchecked_shifts", issue = "85122")] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn unchecked_shl(self, rhs: u32) -> Self { - // SAFETY: the caller must uphold the safety contract for - // `unchecked_shl`. - unsafe { intrinsics::unchecked_shl(self, rhs) } - } - - /// Checked shift right. Computes `self >> rhs`, returning `None` - /// if `rhs` is larger than or equal to the number of bits in `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shr(4), Some(0x1));")] - #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".checked_shr(129), None);")] - /// ``` - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_checked_int_methods", since = "1.47.0")] - // We could always go back to wrapping - #[rustc_allow_const_fn_unstable(unchecked_shifts)] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_shr(self, rhs: u32) -> Option { - // Not using overflowing_shr as that's a wrapping shift - if rhs < Self::BITS { - // SAFETY: just checked the RHS is in-range - Some(unsafe { self.unchecked_shr(rhs) }) - } else { - None - } - } - - /// Strict shift right. Computes `self >> rhs`, panicking `rhs` is - /// larger than or equal to the number of bits in `self`. - /// - /// # Panics - /// - /// ## Overflow behavior - /// - /// This function will always panic on overflow, regardless of whether overflow checks are enabled. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".strict_shr(4), 0x1);")] - /// ``` - /// - /// The following panics because of overflow: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = 0x10", stringify!($SelfT), ".strict_shr(129);")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn strict_shr(self, rhs: u32) -> Self { - let (a, b) = self.overflowing_shr(rhs); - if unlikely!(b) { overflow_panic::shr() } else { a } - } - - /// Unchecked shift right. Computes `self >> rhs`, assuming that - /// `rhs` is less than the number of bits in `self`. - /// - /// # Safety - /// - /// This results in undefined behavior if `rhs` is larger than - /// or equal to the number of bits in `self`, - /// i.e. when [`checked_shr`] would return `None`. - /// - #[doc = concat!("[`checked_shr`]: ", stringify!($SelfT), "::checked_shr")] - #[unstable( - feature = "unchecked_shifts", - reason = "niche optimization path", - issue = "85122", - )] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[rustc_const_unstable(feature = "unchecked_shifts", issue = "85122")] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn unchecked_shr(self, rhs: u32) -> Self { - // SAFETY: the caller must uphold the safety contract for - // `unchecked_shr`. - unsafe { intrinsics::unchecked_shr(self, rhs) } - } - - /// Checked exponentiation. Computes `self.pow(exp)`, returning `None` if - /// overflow occurred. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".checked_pow(5), Some(32));")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_pow(2), None);")] - /// ``` - #[stable(feature = "no_panic_pow", since = "1.34.0")] - #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_pow(self, mut exp: u32) -> Option { - if exp == 0 { - return Some(1); - } - let mut base = self; - let mut acc: Self = 1; - - while exp > 1 { - if (exp & 1) == 1 { - acc = try_opt!(acc.checked_mul(base)); - } - exp /= 2; - base = try_opt!(base.checked_mul(base)); - } - - // since exp!=0, finally the exp must be 1. - // Deal with the final bit of the exponent separately, since - // squaring the base afterwards is not necessary and may cause a - // needless overflow. - - acc.checked_mul(base) - } - - /// Strict exponentiation. Computes `self.pow(exp)`, panicking if - /// overflow occurred. - /// - /// # Panics - /// - /// ## Overflow behavior - /// - /// This function will always panic on overflow, regardless of whether overflow checks are enabled. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(strict_overflow_ops)] - #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".strict_pow(5), 32);")] - /// ``` - /// - /// The following panics because of overflow: - /// - /// ```should_panic - /// #![feature(strict_overflow_ops)] - #[doc = concat!("let _ = ", stringify!($SelfT), "::MAX.strict_pow(2);")] - /// ``` - #[unstable(feature = "strict_overflow_ops", issue = "118260")] - #[rustc_const_unstable(feature = "const_strict_overflow_ops", issue = "118260")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn strict_pow(self, mut exp: u32) -> Self { - if exp == 0 { - return 1; - } - let mut base = self; - let mut acc: Self = 1; - - while exp > 1 { - if (exp & 1) == 1 { - acc = acc.strict_mul(base); - } - exp /= 2; - base = base.strict_mul(base); - } - // since exp!=0, finally the exp must be 1. - // Deal with the final bit of the exponent separately, since - // squaring the base afterwards is not necessary and may cause a - // needless overflow. - acc.strict_mul(base) - } - - /// Saturating integer addition. Computes `self + rhs`, saturating at - /// the numeric bounds instead of overflowing. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_add(1), 101);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_add(127), ", stringify!($SelfT), "::MAX);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")] - #[inline(always)] - pub const fn saturating_add(self, rhs: Self) -> Self { - intrinsics::saturating_add(self, rhs) - } - - /// Saturating addition with a signed integer. Computes `self + rhs`, - /// saturating at the numeric bounds instead of overflowing. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".saturating_add_signed(2), 3);")] - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".saturating_add_signed(-2), 0);")] - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).saturating_add_signed(4), ", stringify!($SelfT), "::MAX);")] - /// ``` - #[stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn saturating_add_signed(self, rhs: $SignedT) -> Self { - let (res, overflow) = self.overflowing_add(rhs as Self); - if overflow == (rhs < 0) { - res - } else if overflow { - Self::MAX - } else { - 0 - } - } - - /// Saturating integer subtraction. Computes `self - rhs`, saturating - /// at the numeric bounds instead of overflowing. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".saturating_sub(27), 73);")] - #[doc = concat!("assert_eq!(13", stringify!($SelfT), ".saturating_sub(127), 0);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")] - #[inline(always)] - pub const fn saturating_sub(self, rhs: Self) -> Self { - intrinsics::saturating_sub(self, rhs) - } - - /// Saturating integer multiplication. Computes `self * rhs`, - /// saturating at the numeric bounds instead of overflowing. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".saturating_mul(10), 20);")] - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX).saturating_mul(10), ", stringify!($SelfT),"::MAX);")] - /// ``` - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_saturating_int_methods", since = "1.47.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn saturating_mul(self, rhs: Self) -> Self { - match self.checked_mul(rhs) { - Some(x) => x, - None => Self::MAX, - } - } - - /// Saturating integer division. Computes `self / rhs`, saturating at the - /// numeric bounds instead of overflowing. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".saturating_div(2), 2);")] - /// - /// ``` - #[stable(feature = "saturating_div", since = "1.58.0")] - #[rustc_const_stable(feature = "saturating_div", since = "1.58.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn saturating_div(self, rhs: Self) -> Self { - // on unsigned types, there is no overflow in integer division - self.wrapping_div(rhs) - } - - /// Saturating integer exponentiation. Computes `self.pow(exp)`, - /// saturating at the numeric bounds instead of overflowing. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(4", stringify!($SelfT), ".saturating_pow(3), 64);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.saturating_pow(2), ", stringify!($SelfT), "::MAX);")] - /// ``` - #[stable(feature = "no_panic_pow", since = "1.34.0")] - #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn saturating_pow(self, exp: u32) -> Self { - match self.checked_pow(exp) { - Some(x) => x, - None => Self::MAX, - } - } - - /// Wrapping (modular) addition. Computes `self + rhs`, - /// wrapping around at the boundary of the type. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(200", stringify!($SelfT), ".wrapping_add(55), 255);")] - #[doc = concat!("assert_eq!(200", stringify!($SelfT), ".wrapping_add(", stringify!($SelfT), "::MAX), 199);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn wrapping_add(self, rhs: Self) -> Self { - intrinsics::wrapping_add(self, rhs) - } - - /// Wrapping (modular) addition with a signed integer. Computes - /// `self + rhs`, wrapping around at the boundary of the type. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".wrapping_add_signed(2), 3);")] - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".wrapping_add_signed(-2), ", stringify!($SelfT), "::MAX);")] - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).wrapping_add_signed(4), 1);")] - /// ``` - #[stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn wrapping_add_signed(self, rhs: $SignedT) -> Self { - self.wrapping_add(rhs as Self) - } - - /// Wrapping (modular) subtraction. Computes `self - rhs`, - /// wrapping around at the boundary of the type. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_sub(100), 0);")] - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_sub(", stringify!($SelfT), "::MAX), 101);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn wrapping_sub(self, rhs: Self) -> Self { - intrinsics::wrapping_sub(self, rhs) - } - - /// Wrapping (modular) multiplication. Computes `self * - /// rhs`, wrapping around at the boundary of the type. - /// - /// # Examples - /// - /// Basic usage: - /// - /// Please note that this example is shared between integer types. - /// Which explains why `u8` is used here. - /// - /// ``` - /// assert_eq!(10u8.wrapping_mul(12), 120); - /// assert_eq!(25u8.wrapping_mul(12), 44); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn wrapping_mul(self, rhs: Self) -> Self { - intrinsics::wrapping_mul(self, rhs) - } - - /// Wrapping (modular) division. Computes `self / rhs`. - /// Wrapped division on unsigned types is just normal division. - /// There's no way wrapping could ever happen. - /// This function exists, so that all operations - /// are accounted for in the wrapping operations. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_div(10), 10);")] - /// ``` - #[stable(feature = "num_wrapping", since = "1.2.0")] - #[rustc_const_stable(feature = "const_wrapping_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - #[track_caller] - pub const fn wrapping_div(self, rhs: Self) -> Self { - self / rhs - } - - /// Wrapping Euclidean division. Computes `self.div_euclid(rhs)`. - /// Wrapped division on unsigned types is just normal division. - /// There's no way wrapping could ever happen. - /// This function exists, so that all operations - /// are accounted for in the wrapping operations. - /// Since, for the positive integers, all common - /// definitions of division are equal, this - /// is exactly equal to `self.wrapping_div(rhs)`. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_div_euclid(10), 10);")] - /// ``` - #[stable(feature = "euclidean_division", since = "1.38.0")] - #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - #[track_caller] - pub const fn wrapping_div_euclid(self, rhs: Self) -> Self { - self / rhs - } - - /// Wrapping (modular) remainder. Computes `self % rhs`. - /// Wrapped remainder calculation on unsigned types is - /// just the regular remainder calculation. - /// There's no way wrapping could ever happen. - /// This function exists, so that all operations - /// are accounted for in the wrapping operations. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_rem(10), 0);")] - /// ``` - #[stable(feature = "num_wrapping", since = "1.2.0")] - #[rustc_const_stable(feature = "const_wrapping_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - #[track_caller] - pub const fn wrapping_rem(self, rhs: Self) -> Self { - self % rhs - } - - /// Wrapping Euclidean modulo. Computes `self.rem_euclid(rhs)`. - /// Wrapped modulo calculation on unsigned types is - /// just the regular remainder calculation. - /// There's no way wrapping could ever happen. - /// This function exists, so that all operations - /// are accounted for in the wrapping operations. - /// Since, for the positive integers, all common - /// definitions of division are equal, this - /// is exactly equal to `self.wrapping_rem(rhs)`. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".wrapping_rem_euclid(10), 0);")] - /// ``` - #[stable(feature = "euclidean_division", since = "1.38.0")] - #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - #[track_caller] - pub const fn wrapping_rem_euclid(self, rhs: Self) -> Self { - self % rhs - } - - /// Wrapping (modular) negation. Computes `-self`, - /// wrapping around at the boundary of the type. - /// - /// Since unsigned types do not have negative equivalents - /// all applications of this function will wrap (except for `-0`). - /// For values smaller than the corresponding signed type's maximum - /// the result is the same as casting the corresponding signed value. - /// Any larger values are equivalent to `MAX + 1 - (val - MAX - 1)` where - /// `MAX` is the corresponding signed type's maximum. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(0_", stringify!($SelfT), ".wrapping_neg(), 0);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.wrapping_neg(), 1);")] - #[doc = concat!("assert_eq!(13_", stringify!($SelfT), ".wrapping_neg(), (!13) + 1);")] - #[doc = concat!("assert_eq!(42_", stringify!($SelfT), ".wrapping_neg(), !(42 - 1));")] - /// ``` - #[stable(feature = "num_wrapping", since = "1.2.0")] - #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn wrapping_neg(self) -> Self { - (0 as $SelfT).wrapping_sub(self) - } - - /// Panic-free bitwise shift-left; yields `self << mask(rhs)`, - /// where `mask` removes any high-order bits of `rhs` that - /// would cause the shift to exceed the bitwidth of the type. - /// - /// Note that this is *not* the same as a rotate-left; the - /// RHS of a wrapping shift-left is restricted to the range - /// of the type, rather than the bits shifted out of the LHS - /// being returned to the other end. The primitive integer - /// types all implement a [`rotate_left`](Self::rotate_left) function, - /// which may be what you want instead. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".wrapping_shl(7), 128);")] - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".wrapping_shl(128), 1);")] - /// ``` - #[stable(feature = "num_wrapping", since = "1.2.0")] - #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - #[rustc_allow_const_fn_unstable(unchecked_shifts)] - pub const fn wrapping_shl(self, rhs: u32) -> Self { - // SAFETY: the masking by the bitsize of the type ensures that we do not shift - // out of bounds - unsafe { - self.unchecked_shl(rhs & (Self::BITS - 1)) - } - } - - /// Panic-free bitwise shift-right; yields `self >> mask(rhs)`, - /// where `mask` removes any high-order bits of `rhs` that - /// would cause the shift to exceed the bitwidth of the type. - /// - /// Note that this is *not* the same as a rotate-right; the - /// RHS of a wrapping shift-right is restricted to the range - /// of the type, rather than the bits shifted out of the LHS - /// being returned to the other end. The primitive integer - /// types all implement a [`rotate_right`](Self::rotate_right) function, - /// which may be what you want instead. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(128", stringify!($SelfT), ".wrapping_shr(7), 1);")] - #[doc = concat!("assert_eq!(128", stringify!($SelfT), ".wrapping_shr(128), 128);")] - /// ``` - #[stable(feature = "num_wrapping", since = "1.2.0")] - #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - #[rustc_allow_const_fn_unstable(unchecked_shifts)] - pub const fn wrapping_shr(self, rhs: u32) -> Self { - // SAFETY: the masking by the bitsize of the type ensures that we do not shift - // out of bounds - unsafe { - self.unchecked_shr(rhs & (Self::BITS - 1)) - } - } - - /// Wrapping (modular) exponentiation. Computes `self.pow(exp)`, - /// wrapping around at the boundary of the type. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".wrapping_pow(5), 243);")] - /// assert_eq!(3u8.wrapping_pow(6), 217); - /// ``` - #[stable(feature = "no_panic_pow", since = "1.34.0")] - #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn wrapping_pow(self, mut exp: u32) -> Self { - if exp == 0 { - return 1; - } - let mut base = self; - let mut acc: Self = 1; - - while exp > 1 { - if (exp & 1) == 1 { - acc = acc.wrapping_mul(base); - } - exp /= 2; - base = base.wrapping_mul(base); - } - - // since exp!=0, finally the exp must be 1. - // Deal with the final bit of the exponent separately, since - // squaring the base afterwards is not necessary and may cause a - // needless overflow. - acc.wrapping_mul(base) - } - - /// Calculates `self` + `rhs` - /// - /// Returns a tuple of the addition along with a boolean indicating - /// whether an arithmetic overflow would occur. If an overflow would - /// have occurred then the wrapped value is returned. - /// - /// # Examples - /// - /// Basic usage - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_add(2), (7, false));")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.overflowing_add(1), (0, true));")] - /// ``` - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn overflowing_add(self, rhs: Self) -> (Self, bool) { - let (a, b) = intrinsics::add_with_overflow(self as $ActualT, rhs as $ActualT); - (a as Self, b) - } - - /// Calculates `self` + `rhs` + `carry` and returns a tuple containing - /// the sum and the output carry. - /// - /// Performs "ternary addition" of two integer operands and a carry-in - /// bit, and returns an output integer and a carry-out bit. This allows - /// chaining together multiple additions to create a wider addition, and - /// can be useful for bignum addition. - /// - #[doc = concat!("This can be thought of as a ", stringify!($BITS), "-bit \"full adder\", in the electronics sense.")] - /// - /// If the input carry is false, this method is equivalent to - /// [`overflowing_add`](Self::overflowing_add), and the output carry is - /// equal to the overflow flag. Note that although carry and overflow - /// flags are similar for unsigned integers, they are different for - /// signed integers. - /// - /// # Examples - /// - /// ``` - /// #![feature(bigint_helper_methods)] - /// - #[doc = concat!("// 3 MAX (a = 3 × 2^", stringify!($BITS), " + 2^", stringify!($BITS), " - 1)")] - #[doc = concat!("// + 5 7 (b = 5 × 2^", stringify!($BITS), " + 7)")] - /// // --------- - #[doc = concat!("// 9 6 (sum = 9 × 2^", stringify!($BITS), " + 6)")] - /// - #[doc = concat!("let (a1, a0): (", stringify!($SelfT), ", ", stringify!($SelfT), ") = (3, ", stringify!($SelfT), "::MAX);")] - #[doc = concat!("let (b1, b0): (", stringify!($SelfT), ", ", stringify!($SelfT), ") = (5, 7);")] - /// let carry0 = false; - /// - /// let (sum0, carry1) = a0.carrying_add(b0, carry0); - /// assert_eq!(carry1, true); - /// let (sum1, carry2) = a1.carrying_add(b1, carry1); - /// assert_eq!(carry2, false); - /// - /// assert_eq!((sum1, sum0), (9, 6)); - /// ``` - #[unstable(feature = "bigint_helper_methods", issue = "85532")] - #[rustc_const_unstable(feature = "const_bigint_helper_methods", issue = "85532")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn carrying_add(self, rhs: Self, carry: bool) -> (Self, bool) { - // note: longer-term this should be done via an intrinsic, but this has been shown - // to generate optimal code for now, and LLVM doesn't have an equivalent intrinsic - let (a, b) = self.overflowing_add(rhs); - let (c, d) = a.overflowing_add(carry as $SelfT); - (c, b || d) - } - - /// Calculates `self` + `rhs` with a signed `rhs` - /// - /// Returns a tuple of the addition along with a boolean indicating - /// whether an arithmetic overflow would occur. If an overflow would - /// have occurred then the wrapped value is returned. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".overflowing_add_signed(2), (3, false));")] - #[doc = concat!("assert_eq!(1", stringify!($SelfT), ".overflowing_add_signed(-2), (", stringify!($SelfT), "::MAX, true));")] - #[doc = concat!("assert_eq!((", stringify!($SelfT), "::MAX - 2).overflowing_add_signed(4), (1, true));")] - /// ``` - #[stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[rustc_const_stable(feature = "mixed_integer_ops", since = "1.66.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn overflowing_add_signed(self, rhs: $SignedT) -> (Self, bool) { - let (res, overflowed) = self.overflowing_add(rhs as Self); - (res, overflowed ^ (rhs < 0)) - } - - /// Calculates `self` - `rhs` - /// - /// Returns a tuple of the subtraction along with a boolean indicating - /// whether an arithmetic overflow would occur. If an overflow would - /// have occurred then the wrapped value is returned. - /// - /// # Examples - /// - /// Basic usage - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_sub(2), (3, false));")] - #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".overflowing_sub(1), (", stringify!($SelfT), "::MAX, true));")] - /// ``` - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn overflowing_sub(self, rhs: Self) -> (Self, bool) { - let (a, b) = intrinsics::sub_with_overflow(self as $ActualT, rhs as $ActualT); - (a as Self, b) - } - - /// Calculates `self` − `rhs` − `borrow` and returns a tuple - /// containing the difference and the output borrow. - /// - /// Performs "ternary subtraction" by subtracting both an integer - /// operand and a borrow-in bit from `self`, and returns an output - /// integer and a borrow-out bit. This allows chaining together multiple - /// subtractions to create a wider subtraction, and can be useful for - /// bignum subtraction. - /// - /// # Examples - /// - /// ``` - /// #![feature(bigint_helper_methods)] - /// - #[doc = concat!("// 9 6 (a = 9 × 2^", stringify!($BITS), " + 6)")] - #[doc = concat!("// - 5 7 (b = 5 × 2^", stringify!($BITS), " + 7)")] - /// // --------- - #[doc = concat!("// 3 MAX (diff = 3 × 2^", stringify!($BITS), " + 2^", stringify!($BITS), " - 1)")] - /// - #[doc = concat!("let (a1, a0): (", stringify!($SelfT), ", ", stringify!($SelfT), ") = (9, 6);")] - #[doc = concat!("let (b1, b0): (", stringify!($SelfT), ", ", stringify!($SelfT), ") = (5, 7);")] - /// let borrow0 = false; - /// - /// let (diff0, borrow1) = a0.borrowing_sub(b0, borrow0); - /// assert_eq!(borrow1, true); - /// let (diff1, borrow2) = a1.borrowing_sub(b1, borrow1); - /// assert_eq!(borrow2, false); - /// - #[doc = concat!("assert_eq!((diff1, diff0), (3, ", stringify!($SelfT), "::MAX));")] - /// ``` - #[unstable(feature = "bigint_helper_methods", issue = "85532")] - #[rustc_const_unstable(feature = "const_bigint_helper_methods", issue = "85532")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn borrowing_sub(self, rhs: Self, borrow: bool) -> (Self, bool) { - // note: longer-term this should be done via an intrinsic, but this has been shown - // to generate optimal code for now, and LLVM doesn't have an equivalent intrinsic - let (a, b) = self.overflowing_sub(rhs); - let (c, d) = a.overflowing_sub(borrow as $SelfT); - (c, b || d) - } - - /// Computes the absolute difference between `self` and `other`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".abs_diff(80), 20", stringify!($SelfT), ");")] - #[doc = concat!("assert_eq!(100", stringify!($SelfT), ".abs_diff(110), 10", stringify!($SelfT), ");")] - /// ``` - #[stable(feature = "int_abs_diff", since = "1.60.0")] - #[rustc_const_stable(feature = "int_abs_diff", since = "1.60.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn abs_diff(self, other: Self) -> Self { - if mem::size_of::() == 1 { - // Trick LLVM into generating the psadbw instruction when SSE2 - // is available and this function is autovectorized for u8's. - (self as i32).wrapping_sub(other as i32).abs() as Self - } else { - if self < other { - other - self - } else { - self - other - } - } - } - - /// Calculates the multiplication of `self` and `rhs`. - /// - /// Returns a tuple of the multiplication along with a boolean - /// indicating whether an arithmetic overflow would occur. If an - /// overflow would have occurred then the wrapped value is returned. - /// - /// # Examples - /// - /// Basic usage: - /// - /// Please note that this example is shared between integer types. - /// Which explains why `u32` is used here. - /// - /// ``` - /// assert_eq!(5u32.overflowing_mul(2), (10, false)); - /// assert_eq!(1_000_000_000u32.overflowing_mul(10), (1410065408, true)); - /// ``` - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn overflowing_mul(self, rhs: Self) -> (Self, bool) { - let (a, b) = intrinsics::mul_with_overflow(self as $ActualT, rhs as $ActualT); - (a as Self, b) - } - - /// Calculates the divisor when `self` is divided by `rhs`. - /// - /// Returns a tuple of the divisor along with a boolean indicating - /// whether an arithmetic overflow would occur. Note that for unsigned - /// integers overflow never occurs, so the second value is always - /// `false`. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0. - /// - /// # Examples - /// - /// Basic usage - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_div(2), (2, false));")] - /// ``` - #[inline(always)] - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_overflowing_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[track_caller] - pub const fn overflowing_div(self, rhs: Self) -> (Self, bool) { - (self / rhs, false) - } - - /// Calculates the quotient of Euclidean division `self.div_euclid(rhs)`. - /// - /// Returns a tuple of the divisor along with a boolean indicating - /// whether an arithmetic overflow would occur. Note that for unsigned - /// integers overflow never occurs, so the second value is always - /// `false`. - /// Since, for the positive integers, all common - /// definitions of division are equal, this - /// is exactly equal to `self.overflowing_div(rhs)`. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0. - /// - /// # Examples - /// - /// Basic usage - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_div_euclid(2), (2, false));")] - /// ``` - #[inline(always)] - #[stable(feature = "euclidean_division", since = "1.38.0")] - #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[track_caller] - pub const fn overflowing_div_euclid(self, rhs: Self) -> (Self, bool) { - (self / rhs, false) - } - - /// Calculates the remainder when `self` is divided by `rhs`. - /// - /// Returns a tuple of the remainder after dividing along with a boolean - /// indicating whether an arithmetic overflow would occur. Note that for - /// unsigned integers overflow never occurs, so the second value is - /// always `false`. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0. - /// - /// # Examples - /// - /// Basic usage - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_rem(2), (1, false));")] - /// ``` - #[inline(always)] - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_overflowing_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[track_caller] - pub const fn overflowing_rem(self, rhs: Self) -> (Self, bool) { - (self % rhs, false) - } - - /// Calculates the remainder `self.rem_euclid(rhs)` as if by Euclidean division. - /// - /// Returns a tuple of the modulo after dividing along with a boolean - /// indicating whether an arithmetic overflow would occur. Note that for - /// unsigned integers overflow never occurs, so the second value is - /// always `false`. - /// Since, for the positive integers, all common - /// definitions of division are equal, this operation - /// is exactly equal to `self.overflowing_rem(rhs)`. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0. - /// - /// # Examples - /// - /// Basic usage - /// - /// ``` - #[doc = concat!("assert_eq!(5", stringify!($SelfT), ".overflowing_rem_euclid(2), (1, false));")] - /// ``` - #[inline(always)] - #[stable(feature = "euclidean_division", since = "1.38.0")] - #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[track_caller] - pub const fn overflowing_rem_euclid(self, rhs: Self) -> (Self, bool) { - (self % rhs, false) - } - - /// Negates self in an overflowing fashion. - /// - /// Returns `!self + 1` using wrapping operations to return the value - /// that represents the negation of this unsigned value. Note that for - /// positive unsigned values overflow always occurs, but negating 0 does - /// not overflow. - /// - /// # Examples - /// - /// Basic usage - /// - /// ``` - #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".overflowing_neg(), (0, false));")] - #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".overflowing_neg(), (-2i32 as ", stringify!($SelfT), ", true));")] - /// ``` - #[inline(always)] - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - pub const fn overflowing_neg(self) -> (Self, bool) { - ((!self).wrapping_add(1), self != 0) - } - - /// Shifts self left by `rhs` bits. - /// - /// Returns a tuple of the shifted version of self along with a boolean - /// indicating whether the shift value was larger than or equal to the - /// number of bits. If the shift value is too large, then value is - /// masked (N-1) where N is the number of bits, and this value is then - /// used to perform the shift. - /// - /// # Examples - /// - /// Basic usage - /// - /// ``` - #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".overflowing_shl(4), (0x10, false));")] - #[doc = concat!("assert_eq!(0x1", stringify!($SelfT), ".overflowing_shl(132), (0x10, true));")] - /// ``` - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn overflowing_shl(self, rhs: u32) -> (Self, bool) { - (self.wrapping_shl(rhs), rhs >= Self::BITS) - } - - /// Shifts self right by `rhs` bits. - /// - /// Returns a tuple of the shifted version of self along with a boolean - /// indicating whether the shift value was larger than or equal to the - /// number of bits. If the shift value is too large, then value is - /// masked (N-1) where N is the number of bits, and this value is then - /// used to perform the shift. - /// - /// # Examples - /// - /// Basic usage - /// - /// ``` - #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".overflowing_shr(4), (0x1, false));")] - #[doc = concat!("assert_eq!(0x10", stringify!($SelfT), ".overflowing_shr(132), (0x1, true));")] - /// ``` - #[stable(feature = "wrapping", since = "1.7.0")] - #[rustc_const_stable(feature = "const_wrapping_math", since = "1.32.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - pub const fn overflowing_shr(self, rhs: u32) -> (Self, bool) { - (self.wrapping_shr(rhs), rhs >= Self::BITS) - } - - /// Raises self to the power of `exp`, using exponentiation by squaring. - /// - /// Returns a tuple of the exponentiation along with a bool indicating - /// whether an overflow happened. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".overflowing_pow(5), (243, false));")] - /// assert_eq!(3u8.overflowing_pow(6), (217, true)); - /// ``` - #[stable(feature = "no_panic_pow", since = "1.34.0")] - #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn overflowing_pow(self, mut exp: u32) -> (Self, bool) { - if exp == 0{ - return (1,false); - } - let mut base = self; - let mut acc: Self = 1; - let mut overflown = false; - // Scratch space for storing results of overflowing_mul. - let mut r; - - while exp > 1 { - if (exp & 1) == 1 { - r = acc.overflowing_mul(base); - acc = r.0; - overflown |= r.1; - } - exp /= 2; - r = base.overflowing_mul(base); - base = r.0; - overflown |= r.1; - } - - // since exp!=0, finally the exp must be 1. - // Deal with the final bit of the exponent separately, since - // squaring the base afterwards is not necessary and may cause a - // needless overflow. - r = acc.overflowing_mul(base); - r.1 |= overflown; - - r - } - - /// Raises self to the power of `exp`, using exponentiation by squaring. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".pow(5), 32);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[rustc_inherit_overflow_checks] - pub const fn pow(self, mut exp: u32) -> Self { - if exp == 0 { - return 1; - } - let mut base = self; - let mut acc = 1; - - while exp > 1 { - if (exp & 1) == 1 { - acc = acc * base; - } - exp /= 2; - base = base * base; - } - - // since exp!=0, finally the exp must be 1. - // Deal with the final bit of the exponent separately, since - // squaring the base afterwards is not necessary and may cause a - // needless overflow. - acc * base - } - - /// Returns the square root of the number, rounded down. - /// - /// # Examples - /// - /// Basic usage: - /// ``` - /// #![feature(isqrt)] - #[doc = concat!("assert_eq!(10", stringify!($SelfT), ".isqrt(), 3);")] - /// ``` - #[unstable(feature = "isqrt", issue = "116226")] - #[rustc_const_unstable(feature = "isqrt", issue = "116226")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn isqrt(self) -> Self { - if self < 2 { - return self; - } - - // The algorithm is based on the one presented in - // - // which cites as source the following C code: - // . - - let mut op = self; - let mut res = 0; - let mut one = 1 << (self.ilog2() & !1); - - while one != 0 { - if op >= res + one { - op -= res + one; - res = (res >> 1) + one; - } else { - res >>= 1; - } - one >>= 2; - } - - // SAFETY: the result is positive and fits in an integer with half as many bits. - // Inform the optimizer about it. - unsafe { - hint::assert_unchecked(0 < res); - hint::assert_unchecked(res < 1 << (Self::BITS / 2)); - } - - res - } - - /// Performs Euclidean division. - /// - /// Since, for the positive integers, all common - /// definitions of division are equal, this - /// is exactly equal to `self / rhs`. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(7", stringify!($SelfT), ".div_euclid(4), 1); // or any other integer type")] - /// ``` - #[stable(feature = "euclidean_division", since = "1.38.0")] - #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - #[track_caller] - pub const fn div_euclid(self, rhs: Self) -> Self { - self / rhs - } - - - /// Calculates the least remainder of `self (mod rhs)`. - /// - /// Since, for the positive integers, all common - /// definitions of division are equal, this - /// is exactly equal to `self % rhs`. - /// - /// # Panics - /// - /// This function will panic if `rhs` is 0. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(7", stringify!($SelfT), ".rem_euclid(4), 3); // or any other integer type")] - /// ``` - #[doc(alias = "modulo", alias = "mod")] - #[stable(feature = "euclidean_division", since = "1.38.0")] - #[rustc_const_stable(feature = "const_euclidean_int_methods", since = "1.52.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - #[track_caller] - pub const fn rem_euclid(self, rhs: Self) -> Self { - self % rhs - } - - /// Calculates the quotient of `self` and `rhs`, rounding the result towards negative infinity. - /// - /// This is the same as performing `self / rhs` for all unsigned integers. - /// - /// # Panics - /// - /// This function will panic if `rhs` is zero. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(int_roundings)] - #[doc = concat!("assert_eq!(7_", stringify!($SelfT), ".div_floor(4), 1);")] - /// ``` - #[unstable(feature = "int_roundings", issue = "88581")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline(always)] - #[track_caller] - pub const fn div_floor(self, rhs: Self) -> Self { - self / rhs - } - - /// Calculates the quotient of `self` and `rhs`, rounding the result towards positive infinity. - /// - /// # Panics - /// - /// This function will panic if `rhs` is zero. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(7_", stringify!($SelfT), ".div_ceil(4), 2);")] - /// ``` - #[stable(feature = "int_roundings1", since = "1.73.0")] - #[rustc_const_stable(feature = "int_roundings1", since = "1.73.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[track_caller] - pub const fn div_ceil(self, rhs: Self) -> Self { - let d = self / rhs; - let r = self % rhs; - if r > 0 && rhs > 0 { - d + 1 - } else { - d - } - } - - /// Calculates the smallest value greater than or equal to `self` that - /// is a multiple of `rhs`. - /// - /// # Panics - /// - /// This function will panic if `rhs` is zero. - /// - /// ## Overflow behavior - /// - /// On overflow, this function will panic if overflow checks are enabled (default in debug - /// mode) and wrap if overflow checks are disabled (default in release mode). - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".next_multiple_of(8), 16);")] - #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".next_multiple_of(8), 24);")] - /// ``` - #[stable(feature = "int_roundings1", since = "1.73.0")] - #[rustc_const_stable(feature = "int_roundings1", since = "1.73.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[rustc_inherit_overflow_checks] - pub const fn next_multiple_of(self, rhs: Self) -> Self { - match self % rhs { - 0 => self, - r => self + (rhs - r) - } - } - - /// Calculates the smallest value greater than or equal to `self` that - /// is a multiple of `rhs`. Returns `None` if `rhs` is zero or the - /// operation would result in overflow. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(16_", stringify!($SelfT), ".checked_next_multiple_of(8), Some(16));")] - #[doc = concat!("assert_eq!(23_", stringify!($SelfT), ".checked_next_multiple_of(8), Some(24));")] - #[doc = concat!("assert_eq!(1_", stringify!($SelfT), ".checked_next_multiple_of(0), None);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_next_multiple_of(2), None);")] - /// ``` - #[stable(feature = "int_roundings1", since = "1.73.0")] - #[rustc_const_stable(feature = "int_roundings1", since = "1.73.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn checked_next_multiple_of(self, rhs: Self) -> Option { - match try_opt!(self.checked_rem(rhs)) { - 0 => Some(self), - // rhs - r cannot overflow because r is smaller than rhs - r => self.checked_add(rhs - r) - } - } - - /// Returns `true` if and only if `self == 2^k` for some `k`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert!(16", stringify!($SelfT), ".is_power_of_two());")] - #[doc = concat!("assert!(!10", stringify!($SelfT), ".is_power_of_two());")] - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_is_power_of_two", since = "1.32.0")] - #[inline(always)] - pub const fn is_power_of_two(self) -> bool { - self.count_ones() == 1 - } - - // Returns one less than next power of two. - // (For 8u8 next power of two is 8u8 and for 6u8 it is 8u8) - // - // 8u8.one_less_than_next_power_of_two() == 7 - // 6u8.one_less_than_next_power_of_two() == 7 - // - // This method cannot overflow, as in the `next_power_of_two` - // overflow cases it instead ends up returning the maximum value - // of the type, and can return 0 for 0. - #[inline] - #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] - const fn one_less_than_next_power_of_two(self) -> Self { - if self <= 1 { return 0; } - - let p = self - 1; - // SAFETY: Because `p > 0`, it cannot consist entirely of leading zeros. - // That means the shift is always in-bounds, and some processors - // (such as intel pre-haswell) have more efficient ctlz - // intrinsics when the argument is non-zero. - let z = unsafe { intrinsics::ctlz_nonzero(p) }; - <$SelfT>::MAX >> z - } - - /// Returns the smallest power of two greater than or equal to `self`. - /// - /// When return value overflows (i.e., `self > (1 << (N-1))` for type - /// `uN`), it panics in debug mode and the return value is wrapped to 0 in - /// release mode (the only situation in which method can return 0). - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".next_power_of_two(), 2);")] - #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".next_power_of_two(), 4);")] - #[doc = concat!("assert_eq!(0", stringify!($SelfT), ".next_power_of_two(), 1);")] - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[rustc_inherit_overflow_checks] - pub const fn next_power_of_two(self) -> Self { - self.one_less_than_next_power_of_two() + 1 - } - - /// Returns the smallest power of two greater than or equal to `n`. If - /// the next power of two is greater than the type's maximum value, - /// `None` is returned, otherwise the power of two is wrapped in `Some`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".checked_next_power_of_two(), Some(2));")] - #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".checked_next_power_of_two(), Some(4));")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.checked_next_power_of_two(), None);")] - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_int_pow", since = "1.50.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - pub const fn checked_next_power_of_two(self) -> Option { - self.one_less_than_next_power_of_two().checked_add(1) - } - - /// Returns the smallest power of two greater than or equal to `n`. If - /// the next power of two is greater than the type's maximum value, - /// the return value is wrapped to `0`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(wrapping_next_power_of_two)] - /// - #[doc = concat!("assert_eq!(2", stringify!($SelfT), ".wrapping_next_power_of_two(), 2);")] - #[doc = concat!("assert_eq!(3", stringify!($SelfT), ".wrapping_next_power_of_two(), 4);")] - #[doc = concat!("assert_eq!(", stringify!($SelfT), "::MAX.wrapping_next_power_of_two(), 0);")] - /// ``` - #[inline] - #[unstable(feature = "wrapping_next_power_of_two", issue = "32463", - reason = "needs decision on wrapping behaviour")] - #[rustc_const_unstable(feature = "wrapping_next_power_of_two", issue = "32463")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - pub const fn wrapping_next_power_of_two(self) -> Self { - self.one_less_than_next_power_of_two().wrapping_add(1) - } - - /// Return the memory representation of this integer as a byte array in - /// big-endian (network) byte order. - /// - #[doc = $to_xe_bytes_doc] - /// - /// # Examples - /// - /// ``` - #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_be_bytes();")] - #[doc = concat!("assert_eq!(bytes, ", $be_bytes, ");")] - /// ``` - #[stable(feature = "int_to_from_bytes", since = "1.32.0")] - #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn to_be_bytes(self) -> [u8; mem::size_of::()] { - self.to_be().to_ne_bytes() - } - - /// Return the memory representation of this integer as a byte array in - /// little-endian byte order. - /// - #[doc = $to_xe_bytes_doc] - /// - /// # Examples - /// - /// ``` - #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_le_bytes();")] - #[doc = concat!("assert_eq!(bytes, ", $le_bytes, ");")] - /// ``` - #[stable(feature = "int_to_from_bytes", since = "1.32.0")] - #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn to_le_bytes(self) -> [u8; mem::size_of::()] { - self.to_le().to_ne_bytes() - } - - /// Return the memory representation of this integer as a byte array in - /// native byte order. - /// - /// As the target platform's native endianness is used, portable code - /// should use [`to_be_bytes`] or [`to_le_bytes`], as appropriate, - /// instead. - /// - #[doc = $to_xe_bytes_doc] - /// - /// [`to_be_bytes`]: Self::to_be_bytes - /// [`to_le_bytes`]: Self::to_le_bytes - /// - /// # Examples - /// - /// ``` - #[doc = concat!("let bytes = ", $swap_op, stringify!($SelfT), ".to_ne_bytes();")] - /// assert_eq!( - /// bytes, - /// if cfg!(target_endian = "big") { - #[doc = concat!(" ", $be_bytes)] - /// } else { - #[doc = concat!(" ", $le_bytes)] - /// } - /// ); - /// ``` - #[stable(feature = "int_to_from_bytes", since = "1.32.0")] - #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - // SAFETY: const sound because integers are plain old datatypes so we can always - // transmute them to arrays of bytes - #[inline] - pub const fn to_ne_bytes(self) -> [u8; mem::size_of::()] { - // SAFETY: integers are plain old datatypes so we can always transmute them to - // arrays of bytes - unsafe { mem::transmute(self) } - } - - /// Create a native endian integer value from its representation - /// as a byte array in big endian. - /// - #[doc = $from_xe_bytes_doc] - /// - /// # Examples - /// - /// ``` - #[doc = concat!("let value = ", stringify!($SelfT), "::from_be_bytes(", $be_bytes, ");")] - #[doc = concat!("assert_eq!(value, ", $swap_op, ");")] - /// ``` - /// - /// When starting from a slice rather than an array, fallible conversion APIs can be used: - /// - /// ``` - #[doc = concat!("fn read_be_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")] - #[doc = concat!(" let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());")] - /// *input = rest; - #[doc = concat!(" ", stringify!($SelfT), "::from_be_bytes(int_bytes.try_into().unwrap())")] - /// } - /// ``` - #[stable(feature = "int_to_from_bytes", since = "1.32.0")] - #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")] - #[must_use] - #[inline] - pub const fn from_be_bytes(bytes: [u8; mem::size_of::()]) -> Self { - Self::from_be(Self::from_ne_bytes(bytes)) - } - - /// Create a native endian integer value from its representation - /// as a byte array in little endian. - /// - #[doc = $from_xe_bytes_doc] - /// - /// # Examples - /// - /// ``` - #[doc = concat!("let value = ", stringify!($SelfT), "::from_le_bytes(", $le_bytes, ");")] - #[doc = concat!("assert_eq!(value, ", $swap_op, ");")] - /// ``` - /// - /// When starting from a slice rather than an array, fallible conversion APIs can be used: - /// - /// ``` - #[doc = concat!("fn read_le_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")] - #[doc = concat!(" let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());")] - /// *input = rest; - #[doc = concat!(" ", stringify!($SelfT), "::from_le_bytes(int_bytes.try_into().unwrap())")] - /// } - /// ``` - #[stable(feature = "int_to_from_bytes", since = "1.32.0")] - #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")] - #[must_use] - #[inline] - pub const fn from_le_bytes(bytes: [u8; mem::size_of::()]) -> Self { - Self::from_le(Self::from_ne_bytes(bytes)) - } - - /// Create a native endian integer value from its memory representation - /// as a byte array in native endianness. - /// - /// As the target platform's native endianness is used, portable code - /// likely wants to use [`from_be_bytes`] or [`from_le_bytes`], as - /// appropriate instead. - /// - /// [`from_be_bytes`]: Self::from_be_bytes - /// [`from_le_bytes`]: Self::from_le_bytes - /// - #[doc = $from_xe_bytes_doc] - /// - /// # Examples - /// - /// ``` - #[doc = concat!("let value = ", stringify!($SelfT), "::from_ne_bytes(if cfg!(target_endian = \"big\") {")] - #[doc = concat!(" ", $be_bytes, "")] - /// } else { - #[doc = concat!(" ", $le_bytes, "")] - /// }); - #[doc = concat!("assert_eq!(value, ", $swap_op, ");")] - /// ``` - /// - /// When starting from a slice rather than an array, fallible conversion APIs can be used: - /// - /// ``` - #[doc = concat!("fn read_ne_", stringify!($SelfT), "(input: &mut &[u8]) -> ", stringify!($SelfT), " {")] - #[doc = concat!(" let (int_bytes, rest) = input.split_at(std::mem::size_of::<", stringify!($SelfT), ">());")] - /// *input = rest; - #[doc = concat!(" ", stringify!($SelfT), "::from_ne_bytes(int_bytes.try_into().unwrap())")] - /// } - /// ``` - #[stable(feature = "int_to_from_bytes", since = "1.32.0")] - #[rustc_const_stable(feature = "const_int_conversion", since = "1.44.0")] - #[must_use] - // SAFETY: const sound because integers are plain old datatypes so we can always - // transmute to them - #[inline] - pub const fn from_ne_bytes(bytes: [u8; mem::size_of::()]) -> Self { - // SAFETY: integers are plain old datatypes so we can always transmute to them - unsafe { mem::transmute(bytes) } - } - - /// New code should prefer to use - #[doc = concat!("[`", stringify!($SelfT), "::MIN", "`] instead.")] - /// - /// Returns the smallest value that can be represented by this integer type. - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_promotable] - #[inline(always)] - #[rustc_const_stable(feature = "const_max_value", since = "1.32.0")] - #[deprecated(since = "TBD", note = "replaced by the `MIN` associated constant on this type")] - #[rustc_diagnostic_item = concat!(stringify!($SelfT), "_legacy_fn_min_value")] - pub const fn min_value() -> Self { Self::MIN } - - /// New code should prefer to use - #[doc = concat!("[`", stringify!($SelfT), "::MAX", "`] instead.")] - /// - /// Returns the largest value that can be represented by this integer type. - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_promotable] - #[inline(always)] - #[rustc_const_stable(feature = "const_max_value", since = "1.32.0")] - #[deprecated(since = "TBD", note = "replaced by the `MAX` associated constant on this type")] - #[rustc_diagnostic_item = concat!(stringify!($SelfT), "_legacy_fn_max_value")] - pub const fn max_value() -> Self { Self::MAX } - } -} diff --git a/library/core/src/num/wrapping.rs b/library/core/src/num/wrapping.rs deleted file mode 100644 index 16f0b6d913dfb..0000000000000 --- a/library/core/src/num/wrapping.rs +++ /dev/null @@ -1,1090 +0,0 @@ -//! Definitions of `Wrapping`. - -use crate::fmt; -use crate::ops::{Add, AddAssign, BitAnd, BitAndAssign, BitOr, BitOrAssign}; -use crate::ops::{BitXor, BitXorAssign, Div, DivAssign}; -use crate::ops::{Mul, MulAssign, Neg, Not, Rem, RemAssign}; -use crate::ops::{Shl, ShlAssign, Shr, ShrAssign, Sub, SubAssign}; - -/// Provides intentionally-wrapped arithmetic on `T`. -/// -/// Operations like `+` on `u32` values are intended to never overflow, -/// and in some debug configurations overflow is detected and results -/// in a panic. While most arithmetic falls into this category, some -/// code explicitly expects and relies upon modular arithmetic (e.g., -/// hashing). -/// -/// Wrapping arithmetic can be achieved either through methods like -/// `wrapping_add`, or through the `Wrapping` type, which says that -/// all standard arithmetic operations on the underlying value are -/// intended to have wrapping semantics. -/// -/// The underlying value can be retrieved through the `.0` index of the -/// `Wrapping` tuple. -/// -/// # Examples -/// -/// ``` -/// use std::num::Wrapping; -/// -/// let zero = Wrapping(0u32); -/// let one = Wrapping(1u32); -/// -/// assert_eq!(u32::MAX, (zero - one).0); -/// ``` -/// -/// # Layout -/// -/// `Wrapping` is guaranteed to have the same layout and ABI as `T`. -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(PartialEq, Eq, PartialOrd, Ord, Clone, Copy, Default, Hash)] -#[repr(transparent)] -#[rustc_diagnostic_item = "Wrapping"] -pub struct Wrapping(#[stable(feature = "rust1", since = "1.0.0")] pub T); - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for Wrapping { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0.fmt(f) - } -} - -#[stable(feature = "wrapping_display", since = "1.10.0")] -impl fmt::Display for Wrapping { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0.fmt(f) - } -} - -#[stable(feature = "wrapping_fmt", since = "1.11.0")] -impl fmt::Binary for Wrapping { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0.fmt(f) - } -} - -#[stable(feature = "wrapping_fmt", since = "1.11.0")] -impl fmt::Octal for Wrapping { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0.fmt(f) - } -} - -#[stable(feature = "wrapping_fmt", since = "1.11.0")] -impl fmt::LowerHex for Wrapping { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0.fmt(f) - } -} - -#[stable(feature = "wrapping_fmt", since = "1.11.0")] -impl fmt::UpperHex for Wrapping { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0.fmt(f) - } -} - -#[allow(unused_macros)] -macro_rules! sh_impl_signed { - ($t:ident, $f:ident) => { - #[stable(feature = "rust1", since = "1.0.0")] - impl Shl<$f> for Wrapping<$t> { - type Output = Wrapping<$t>; - - #[inline] - fn shl(self, other: $f) -> Wrapping<$t> { - if other < 0 { - Wrapping(self.0.wrapping_shr((-other & self::shift_max::$t as $f) as u32)) - } else { - Wrapping(self.0.wrapping_shl((other & self::shift_max::$t as $f) as u32)) - } - } - } - forward_ref_binop! { impl Shl, shl for Wrapping<$t>, $f, - #[stable(feature = "wrapping_ref_ops", since = "1.39.0")] } - - #[stable(feature = "op_assign_traits", since = "1.8.0")] - impl ShlAssign<$f> for Wrapping<$t> { - #[inline] - fn shl_assign(&mut self, other: $f) { - *self = *self << other; - } - } - forward_ref_op_assign! { impl ShlAssign, shl_assign for Wrapping<$t>, $f } - - #[stable(feature = "rust1", since = "1.0.0")] - impl Shr<$f> for Wrapping<$t> { - type Output = Wrapping<$t>; - - #[inline] - fn shr(self, other: $f) -> Wrapping<$t> { - if other < 0 { - Wrapping(self.0.wrapping_shl((-other & self::shift_max::$t as $f) as u32)) - } else { - Wrapping(self.0.wrapping_shr((other & self::shift_max::$t as $f) as u32)) - } - } - } - forward_ref_binop! { impl Shr, shr for Wrapping<$t>, $f, - #[stable(feature = "wrapping_ref_ops", since = "1.39.0")] } - - #[stable(feature = "op_assign_traits", since = "1.8.0")] - impl ShrAssign<$f> for Wrapping<$t> { - #[inline] - fn shr_assign(&mut self, other: $f) { - *self = *self >> other; - } - } - forward_ref_op_assign! { impl ShrAssign, shr_assign for Wrapping<$t>, $f } - }; -} - -macro_rules! sh_impl_unsigned { - ($t:ident, $f:ident) => { - #[stable(feature = "rust1", since = "1.0.0")] - impl Shl<$f> for Wrapping<$t> { - type Output = Wrapping<$t>; - - #[inline] - fn shl(self, other: $f) -> Wrapping<$t> { - Wrapping(self.0.wrapping_shl((other & self::shift_max::$t as $f) as u32)) - } - } - forward_ref_binop! { impl Shl, shl for Wrapping<$t>, $f, - #[stable(feature = "wrapping_ref_ops", since = "1.39.0")] } - - #[stable(feature = "op_assign_traits", since = "1.8.0")] - impl ShlAssign<$f> for Wrapping<$t> { - #[inline] - fn shl_assign(&mut self, other: $f) { - *self = *self << other; - } - } - forward_ref_op_assign! { impl ShlAssign, shl_assign for Wrapping<$t>, $f } - - #[stable(feature = "rust1", since = "1.0.0")] - impl Shr<$f> for Wrapping<$t> { - type Output = Wrapping<$t>; - - #[inline] - fn shr(self, other: $f) -> Wrapping<$t> { - Wrapping(self.0.wrapping_shr((other & self::shift_max::$t as $f) as u32)) - } - } - forward_ref_binop! { impl Shr, shr for Wrapping<$t>, $f, - #[stable(feature = "wrapping_ref_ops", since = "1.39.0")] } - - #[stable(feature = "op_assign_traits", since = "1.8.0")] - impl ShrAssign<$f> for Wrapping<$t> { - #[inline] - fn shr_assign(&mut self, other: $f) { - *self = *self >> other; - } - } - forward_ref_op_assign! { impl ShrAssign, shr_assign for Wrapping<$t>, $f } - }; -} - -// FIXME (#23545): uncomment the remaining impls -macro_rules! sh_impl_all { - ($($t:ident)*) => ($( - //sh_impl_unsigned! { $t, u8 } - //sh_impl_unsigned! { $t, u16 } - //sh_impl_unsigned! { $t, u32 } - //sh_impl_unsigned! { $t, u64 } - //sh_impl_unsigned! { $t, u128 } - sh_impl_unsigned! { $t, usize } - - //sh_impl_signed! { $t, i8 } - //sh_impl_signed! { $t, i16 } - //sh_impl_signed! { $t, i32 } - //sh_impl_signed! { $t, i64 } - //sh_impl_signed! { $t, i128 } - //sh_impl_signed! { $t, isize } - )*) -} - -sh_impl_all! { u8 u16 u32 u64 u128 usize i8 i16 i32 i64 i128 isize } - -// FIXME(30524): impl Op for Wrapping, impl OpAssign for Wrapping -macro_rules! wrapping_impl { - ($($t:ty)*) => ($( - #[stable(feature = "rust1", since = "1.0.0")] - impl Add for Wrapping<$t> { - type Output = Wrapping<$t>; - - #[inline] - fn add(self, other: Wrapping<$t>) -> Wrapping<$t> { - Wrapping(self.0.wrapping_add(other.0)) - } - } - forward_ref_binop! { impl Add, add for Wrapping<$t>, Wrapping<$t>, - #[stable(feature = "wrapping_ref", since = "1.14.0")] } - - #[stable(feature = "op_assign_traits", since = "1.8.0")] - impl AddAssign for Wrapping<$t> { - #[inline] - fn add_assign(&mut self, other: Wrapping<$t>) { - *self = *self + other; - } - } - forward_ref_op_assign! { impl AddAssign, add_assign for Wrapping<$t>, Wrapping<$t> } - - #[stable(feature = "wrapping_int_assign_impl", since = "1.60.0")] - impl AddAssign<$t> for Wrapping<$t> { - #[inline] - fn add_assign(&mut self, other: $t) { - *self = *self + Wrapping(other); - } - } - forward_ref_op_assign! { impl AddAssign, add_assign for Wrapping<$t>, $t } - - #[stable(feature = "rust1", since = "1.0.0")] - impl Sub for Wrapping<$t> { - type Output = Wrapping<$t>; - - #[inline] - fn sub(self, other: Wrapping<$t>) -> Wrapping<$t> { - Wrapping(self.0.wrapping_sub(other.0)) - } - } - forward_ref_binop! { impl Sub, sub for Wrapping<$t>, Wrapping<$t>, - #[stable(feature = "wrapping_ref", since = "1.14.0")] } - - #[stable(feature = "op_assign_traits", since = "1.8.0")] - impl SubAssign for Wrapping<$t> { - #[inline] - fn sub_assign(&mut self, other: Wrapping<$t>) { - *self = *self - other; - } - } - forward_ref_op_assign! { impl SubAssign, sub_assign for Wrapping<$t>, Wrapping<$t> } - - #[stable(feature = "wrapping_int_assign_impl", since = "1.60.0")] - impl SubAssign<$t> for Wrapping<$t> { - #[inline] - fn sub_assign(&mut self, other: $t) { - *self = *self - Wrapping(other); - } - } - forward_ref_op_assign! { impl SubAssign, sub_assign for Wrapping<$t>, $t } - - #[stable(feature = "rust1", since = "1.0.0")] - impl Mul for Wrapping<$t> { - type Output = Wrapping<$t>; - - #[inline] - fn mul(self, other: Wrapping<$t>) -> Wrapping<$t> { - Wrapping(self.0.wrapping_mul(other.0)) - } - } - forward_ref_binop! { impl Mul, mul for Wrapping<$t>, Wrapping<$t>, - #[stable(feature = "wrapping_ref", since = "1.14.0")] } - - #[stable(feature = "op_assign_traits", since = "1.8.0")] - impl MulAssign for Wrapping<$t> { - #[inline] - fn mul_assign(&mut self, other: Wrapping<$t>) { - *self = *self * other; - } - } - forward_ref_op_assign! { impl MulAssign, mul_assign for Wrapping<$t>, Wrapping<$t> } - - #[stable(feature = "wrapping_int_assign_impl", since = "1.60.0")] - impl MulAssign<$t> for Wrapping<$t> { - #[inline] - fn mul_assign(&mut self, other: $t) { - *self = *self * Wrapping(other); - } - } - forward_ref_op_assign! { impl MulAssign, mul_assign for Wrapping<$t>, $t } - - #[stable(feature = "wrapping_div", since = "1.3.0")] - impl Div for Wrapping<$t> { - type Output = Wrapping<$t>; - - #[inline] - fn div(self, other: Wrapping<$t>) -> Wrapping<$t> { - Wrapping(self.0.wrapping_div(other.0)) - } - } - forward_ref_binop! { impl Div, div for Wrapping<$t>, Wrapping<$t>, - #[stable(feature = "wrapping_ref", since = "1.14.0")] } - - #[stable(feature = "op_assign_traits", since = "1.8.0")] - impl DivAssign for Wrapping<$t> { - #[inline] - fn div_assign(&mut self, other: Wrapping<$t>) { - *self = *self / other; - } - } - forward_ref_op_assign! { impl DivAssign, div_assign for Wrapping<$t>, Wrapping<$t> } - - #[stable(feature = "wrapping_int_assign_impl", since = "1.60.0")] - impl DivAssign<$t> for Wrapping<$t> { - #[inline] - fn div_assign(&mut self, other: $t) { - *self = *self / Wrapping(other); - } - } - forward_ref_op_assign! { impl DivAssign, div_assign for Wrapping<$t>, $t } - - #[stable(feature = "wrapping_impls", since = "1.7.0")] - impl Rem for Wrapping<$t> { - type Output = Wrapping<$t>; - - #[inline] - fn rem(self, other: Wrapping<$t>) -> Wrapping<$t> { - Wrapping(self.0.wrapping_rem(other.0)) - } - } - forward_ref_binop! { impl Rem, rem for Wrapping<$t>, Wrapping<$t>, - #[stable(feature = "wrapping_ref", since = "1.14.0")] } - - #[stable(feature = "op_assign_traits", since = "1.8.0")] - impl RemAssign for Wrapping<$t> { - #[inline] - fn rem_assign(&mut self, other: Wrapping<$t>) { - *self = *self % other; - } - } - forward_ref_op_assign! { impl RemAssign, rem_assign for Wrapping<$t>, Wrapping<$t> } - - #[stable(feature = "wrapping_int_assign_impl", since = "1.60.0")] - impl RemAssign<$t> for Wrapping<$t> { - #[inline] - fn rem_assign(&mut self, other: $t) { - *self = *self % Wrapping(other); - } - } - forward_ref_op_assign! { impl RemAssign, rem_assign for Wrapping<$t>, $t } - - #[stable(feature = "rust1", since = "1.0.0")] - impl Not for Wrapping<$t> { - type Output = Wrapping<$t>; - - #[inline] - fn not(self) -> Wrapping<$t> { - Wrapping(!self.0) - } - } - forward_ref_unop! { impl Not, not for Wrapping<$t>, - #[stable(feature = "wrapping_ref", since = "1.14.0")] } - - #[stable(feature = "rust1", since = "1.0.0")] - impl BitXor for Wrapping<$t> { - type Output = Wrapping<$t>; - - #[inline] - fn bitxor(self, other: Wrapping<$t>) -> Wrapping<$t> { - Wrapping(self.0 ^ other.0) - } - } - forward_ref_binop! { impl BitXor, bitxor for Wrapping<$t>, Wrapping<$t>, - #[stable(feature = "wrapping_ref", since = "1.14.0")] } - - #[stable(feature = "op_assign_traits", since = "1.8.0")] - impl BitXorAssign for Wrapping<$t> { - #[inline] - fn bitxor_assign(&mut self, other: Wrapping<$t>) { - *self = *self ^ other; - } - } - forward_ref_op_assign! { impl BitXorAssign, bitxor_assign for Wrapping<$t>, Wrapping<$t> } - - #[stable(feature = "wrapping_int_assign_impl", since = "1.60.0")] - impl BitXorAssign<$t> for Wrapping<$t> { - #[inline] - fn bitxor_assign(&mut self, other: $t) { - *self = *self ^ Wrapping(other); - } - } - forward_ref_op_assign! { impl BitXorAssign, bitxor_assign for Wrapping<$t>, $t } - - #[stable(feature = "rust1", since = "1.0.0")] - impl BitOr for Wrapping<$t> { - type Output = Wrapping<$t>; - - #[inline] - fn bitor(self, other: Wrapping<$t>) -> Wrapping<$t> { - Wrapping(self.0 | other.0) - } - } - forward_ref_binop! { impl BitOr, bitor for Wrapping<$t>, Wrapping<$t>, - #[stable(feature = "wrapping_ref", since = "1.14.0")] } - - #[stable(feature = "op_assign_traits", since = "1.8.0")] - impl BitOrAssign for Wrapping<$t> { - #[inline] - fn bitor_assign(&mut self, other: Wrapping<$t>) { - *self = *self | other; - } - } - forward_ref_op_assign! { impl BitOrAssign, bitor_assign for Wrapping<$t>, Wrapping<$t> } - - #[stable(feature = "wrapping_int_assign_impl", since = "1.60.0")] - impl BitOrAssign<$t> for Wrapping<$t> { - #[inline] - fn bitor_assign(&mut self, other: $t) { - *self = *self | Wrapping(other); - } - } - forward_ref_op_assign! { impl BitOrAssign, bitor_assign for Wrapping<$t>, $t } - - #[stable(feature = "rust1", since = "1.0.0")] - impl BitAnd for Wrapping<$t> { - type Output = Wrapping<$t>; - - #[inline] - fn bitand(self, other: Wrapping<$t>) -> Wrapping<$t> { - Wrapping(self.0 & other.0) - } - } - forward_ref_binop! { impl BitAnd, bitand for Wrapping<$t>, Wrapping<$t>, - #[stable(feature = "wrapping_ref", since = "1.14.0")] } - - #[stable(feature = "op_assign_traits", since = "1.8.0")] - impl BitAndAssign for Wrapping<$t> { - #[inline] - fn bitand_assign(&mut self, other: Wrapping<$t>) { - *self = *self & other; - } - } - forward_ref_op_assign! { impl BitAndAssign, bitand_assign for Wrapping<$t>, Wrapping<$t> } - - #[stable(feature = "wrapping_int_assign_impl", since = "1.60.0")] - impl BitAndAssign<$t> for Wrapping<$t> { - #[inline] - fn bitand_assign(&mut self, other: $t) { - *self = *self & Wrapping(other); - } - } - forward_ref_op_assign! { impl BitAndAssign, bitand_assign for Wrapping<$t>, $t } - - #[stable(feature = "wrapping_neg", since = "1.10.0")] - impl Neg for Wrapping<$t> { - type Output = Self; - #[inline] - fn neg(self) -> Self { - Wrapping(0) - self - } - } - forward_ref_unop! { impl Neg, neg for Wrapping<$t>, - #[stable(feature = "wrapping_ref", since = "1.14.0")] } - - )*) -} - -wrapping_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 } - -macro_rules! wrapping_int_impl { - ($($t:ty)*) => ($( - impl Wrapping<$t> { - /// Returns the smallest value that can be represented by this integer type. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(wrapping_int_impl)] - /// use std::num::Wrapping; - /// - #[doc = concat!("assert_eq!(>::MIN, Wrapping(", stringify!($t), "::MIN));")] - /// ``` - #[unstable(feature = "wrapping_int_impl", issue = "32463")] - pub const MIN: Self = Self(<$t>::MIN); - - /// Returns the largest value that can be represented by this integer type. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(wrapping_int_impl)] - /// use std::num::Wrapping; - /// - #[doc = concat!("assert_eq!(>::MAX, Wrapping(", stringify!($t), "::MAX));")] - /// ``` - #[unstable(feature = "wrapping_int_impl", issue = "32463")] - pub const MAX: Self = Self(<$t>::MAX); - - /// Returns the size of this integer type in bits. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(wrapping_int_impl)] - /// use std::num::Wrapping; - /// - #[doc = concat!("assert_eq!(>::BITS, ", stringify!($t), "::BITS);")] - /// ``` - #[unstable(feature = "wrapping_int_impl", issue = "32463")] - pub const BITS: u32 = <$t>::BITS; - - /// Returns the number of ones in the binary representation of `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(wrapping_int_impl)] - /// use std::num::Wrapping; - /// - #[doc = concat!("let n = Wrapping(0b01001100", stringify!($t), ");")] - /// - /// assert_eq!(n.count_ones(), 3); - /// ``` - #[inline] - #[doc(alias = "popcount")] - #[doc(alias = "popcnt")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[unstable(feature = "wrapping_int_impl", issue = "32463")] - pub const fn count_ones(self) -> u32 { - self.0.count_ones() - } - - /// Returns the number of zeros in the binary representation of `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(wrapping_int_impl)] - /// use std::num::Wrapping; - /// - #[doc = concat!("assert_eq!(Wrapping(!0", stringify!($t), ").count_zeros(), 0);")] - /// ``` - #[inline] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[unstable(feature = "wrapping_int_impl", issue = "32463")] - pub const fn count_zeros(self) -> u32 { - self.0.count_zeros() - } - - /// Returns the number of trailing zeros in the binary representation of `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(wrapping_int_impl)] - /// use std::num::Wrapping; - /// - #[doc = concat!("let n = Wrapping(0b0101000", stringify!($t), ");")] - /// - /// assert_eq!(n.trailing_zeros(), 3); - /// ``` - #[inline] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[unstable(feature = "wrapping_int_impl", issue = "32463")] - pub const fn trailing_zeros(self) -> u32 { - self.0.trailing_zeros() - } - - /// Shifts the bits to the left by a specified amount, `n`, - /// wrapping the truncated bits to the end of the resulting - /// integer. - /// - /// Please note this isn't the same operation as the `<<` shifting - /// operator! - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(wrapping_int_impl)] - /// use std::num::Wrapping; - /// - /// let n: Wrapping = Wrapping(0x0123456789ABCDEF); - /// let m: Wrapping = Wrapping(-0x76543210FEDCBA99); - /// - /// assert_eq!(n.rotate_left(32), m); - /// ``` - #[inline] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[unstable(feature = "wrapping_int_impl", issue = "32463")] - pub const fn rotate_left(self, n: u32) -> Self { - Wrapping(self.0.rotate_left(n)) - } - - /// Shifts the bits to the right by a specified amount, `n`, - /// wrapping the truncated bits to the beginning of the resulting - /// integer. - /// - /// Please note this isn't the same operation as the `>>` shifting - /// operator! - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(wrapping_int_impl)] - /// use std::num::Wrapping; - /// - /// let n: Wrapping = Wrapping(0x0123456789ABCDEF); - /// let m: Wrapping = Wrapping(-0xFEDCBA987654322); - /// - /// assert_eq!(n.rotate_right(4), m); - /// ``` - #[inline] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[unstable(feature = "wrapping_int_impl", issue = "32463")] - pub const fn rotate_right(self, n: u32) -> Self { - Wrapping(self.0.rotate_right(n)) - } - - /// Reverses the byte order of the integer. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(wrapping_int_impl)] - /// use std::num::Wrapping; - /// - /// let n: Wrapping = Wrapping(0b0000000_01010101); - /// assert_eq!(n, Wrapping(85)); - /// - /// let m = n.swap_bytes(); - /// - /// assert_eq!(m, Wrapping(0b01010101_00000000)); - /// assert_eq!(m, Wrapping(21760)); - /// ``` - #[inline] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[unstable(feature = "wrapping_int_impl", issue = "32463")] - pub const fn swap_bytes(self) -> Self { - Wrapping(self.0.swap_bytes()) - } - - /// Reverses the bit pattern of the integer. - /// - /// # Examples - /// - /// Please note that this example is shared between integer types. - /// Which explains why `i16` is used here. - /// - /// Basic usage: - /// - /// ``` - /// use std::num::Wrapping; - /// - /// let n = Wrapping(0b0000000_01010101i16); - /// assert_eq!(n, Wrapping(85)); - /// - /// let m = n.reverse_bits(); - /// - /// assert_eq!(m.0 as u16, 0b10101010_00000000); - /// assert_eq!(m, Wrapping(-22016)); - /// ``` - #[stable(feature = "reverse_bits", since = "1.37.0")] - #[rustc_const_stable(feature = "const_reverse_bits", since = "1.37.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn reverse_bits(self) -> Self { - Wrapping(self.0.reverse_bits()) - } - - /// Converts an integer from big endian to the target's endianness. - /// - /// On big endian this is a no-op. On little endian the bytes are - /// swapped. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(wrapping_int_impl)] - /// use std::num::Wrapping; - /// - #[doc = concat!("let n = Wrapping(0x1A", stringify!($t), ");")] - /// - /// if cfg!(target_endian = "big") { - #[doc = concat!(" assert_eq!(>::from_be(n), n)")] - /// } else { - #[doc = concat!(" assert_eq!(>::from_be(n), n.swap_bytes())")] - /// } - /// ``` - #[inline] - #[must_use] - #[unstable(feature = "wrapping_int_impl", issue = "32463")] - pub const fn from_be(x: Self) -> Self { - Wrapping(<$t>::from_be(x.0)) - } - - /// Converts an integer from little endian to the target's endianness. - /// - /// On little endian this is a no-op. On big endian the bytes are - /// swapped. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(wrapping_int_impl)] - /// use std::num::Wrapping; - /// - #[doc = concat!("let n = Wrapping(0x1A", stringify!($t), ");")] - /// - /// if cfg!(target_endian = "little") { - #[doc = concat!(" assert_eq!(>::from_le(n), n)")] - /// } else { - #[doc = concat!(" assert_eq!(>::from_le(n), n.swap_bytes())")] - /// } - /// ``` - #[inline] - #[must_use] - #[unstable(feature = "wrapping_int_impl", issue = "32463")] - pub const fn from_le(x: Self) -> Self { - Wrapping(<$t>::from_le(x.0)) - } - - /// Converts `self` to big endian from the target's endianness. - /// - /// On big endian this is a no-op. On little endian the bytes are - /// swapped. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(wrapping_int_impl)] - /// use std::num::Wrapping; - /// - #[doc = concat!("let n = Wrapping(0x1A", stringify!($t), ");")] - /// - /// if cfg!(target_endian = "big") { - /// assert_eq!(n.to_be(), n) - /// } else { - /// assert_eq!(n.to_be(), n.swap_bytes()) - /// } - /// ``` - #[inline] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[unstable(feature = "wrapping_int_impl", issue = "32463")] - pub const fn to_be(self) -> Self { - Wrapping(self.0.to_be()) - } - - /// Converts `self` to little endian from the target's endianness. - /// - /// On little endian this is a no-op. On big endian the bytes are - /// swapped. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(wrapping_int_impl)] - /// use std::num::Wrapping; - /// - #[doc = concat!("let n = Wrapping(0x1A", stringify!($t), ");")] - /// - /// if cfg!(target_endian = "little") { - /// assert_eq!(n.to_le(), n) - /// } else { - /// assert_eq!(n.to_le(), n.swap_bytes()) - /// } - /// ``` - #[inline] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[unstable(feature = "wrapping_int_impl", issue = "32463")] - pub const fn to_le(self) -> Self { - Wrapping(self.0.to_le()) - } - - /// Raises self to the power of `exp`, using exponentiation by squaring. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(wrapping_int_impl)] - /// use std::num::Wrapping; - /// - #[doc = concat!("assert_eq!(Wrapping(3", stringify!($t), ").pow(4), Wrapping(81));")] - /// ``` - /// - /// Results that are too large are wrapped: - /// - /// ``` - /// #![feature(wrapping_int_impl)] - /// use std::num::Wrapping; - /// - /// assert_eq!(Wrapping(3i8).pow(5), Wrapping(-13)); - /// assert_eq!(Wrapping(3i8).pow(6), Wrapping(-39)); - /// ``` - #[inline] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[unstable(feature = "wrapping_int_impl", issue = "32463")] - pub fn pow(self, exp: u32) -> Self { - Wrapping(self.0.wrapping_pow(exp)) - } - } - )*) -} - -wrapping_int_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 } - -macro_rules! wrapping_int_impl_signed { - ($($t:ty)*) => ($( - impl Wrapping<$t> { - /// Returns the number of leading zeros in the binary representation of `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(wrapping_int_impl)] - /// use std::num::Wrapping; - /// - #[doc = concat!("let n = Wrapping(", stringify!($t), "::MAX) >> 2;")] - /// - /// assert_eq!(n.leading_zeros(), 3); - /// ``` - #[inline] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[unstable(feature = "wrapping_int_impl", issue = "32463")] - pub const fn leading_zeros(self) -> u32 { - self.0.leading_zeros() - } - - /// Computes the absolute value of `self`, wrapping around at - /// the boundary of the type. - /// - /// The only case where such wrapping can occur is when one takes the absolute value of the negative - /// minimal value for the type this is a positive value that is too large to represent in the type. In - /// such a case, this function returns `MIN` itself. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(wrapping_int_impl)] - /// use std::num::Wrapping; - /// - #[doc = concat!("assert_eq!(Wrapping(100", stringify!($t), ").abs(), Wrapping(100));")] - #[doc = concat!("assert_eq!(Wrapping(-100", stringify!($t), ").abs(), Wrapping(100));")] - #[doc = concat!("assert_eq!(Wrapping(", stringify!($t), "::MIN).abs(), Wrapping(", stringify!($t), "::MIN));")] - /// assert_eq!(Wrapping(-128i8).abs().0 as u8, 128u8); - /// ``` - #[inline] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[unstable(feature = "wrapping_int_impl", issue = "32463")] - pub fn abs(self) -> Wrapping<$t> { - Wrapping(self.0.wrapping_abs()) - } - - /// Returns a number representing sign of `self`. - /// - /// - `0` if the number is zero - /// - `1` if the number is positive - /// - `-1` if the number is negative - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(wrapping_int_impl)] - /// use std::num::Wrapping; - /// - #[doc = concat!("assert_eq!(Wrapping(10", stringify!($t), ").signum(), Wrapping(1));")] - #[doc = concat!("assert_eq!(Wrapping(0", stringify!($t), ").signum(), Wrapping(0));")] - #[doc = concat!("assert_eq!(Wrapping(-10", stringify!($t), ").signum(), Wrapping(-1));")] - /// ``` - #[inline] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[unstable(feature = "wrapping_int_impl", issue = "32463")] - pub fn signum(self) -> Wrapping<$t> { - Wrapping(self.0.signum()) - } - - /// Returns `true` if `self` is positive and `false` if the number is zero or - /// negative. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(wrapping_int_impl)] - /// use std::num::Wrapping; - /// - #[doc = concat!("assert!(Wrapping(10", stringify!($t), ").is_positive());")] - #[doc = concat!("assert!(!Wrapping(-10", stringify!($t), ").is_positive());")] - /// ``` - #[must_use] - #[inline] - #[unstable(feature = "wrapping_int_impl", issue = "32463")] - pub const fn is_positive(self) -> bool { - self.0.is_positive() - } - - /// Returns `true` if `self` is negative and `false` if the number is zero or - /// positive. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(wrapping_int_impl)] - /// use std::num::Wrapping; - /// - #[doc = concat!("assert!(Wrapping(-10", stringify!($t), ").is_negative());")] - #[doc = concat!("assert!(!Wrapping(10", stringify!($t), ").is_negative());")] - /// ``` - #[must_use] - #[inline] - #[unstable(feature = "wrapping_int_impl", issue = "32463")] - pub const fn is_negative(self) -> bool { - self.0.is_negative() - } - } - )*) -} - -wrapping_int_impl_signed! { isize i8 i16 i32 i64 i128 } - -macro_rules! wrapping_int_impl_unsigned { - ($($t:ty)*) => ($( - impl Wrapping<$t> { - /// Returns the number of leading zeros in the binary representation of `self`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(wrapping_int_impl)] - /// use std::num::Wrapping; - /// - #[doc = concat!("let n = Wrapping(", stringify!($t), "::MAX) >> 2;")] - /// - /// assert_eq!(n.leading_zeros(), 2); - /// ``` - #[inline] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[unstable(feature = "wrapping_int_impl", issue = "32463")] - pub const fn leading_zeros(self) -> u32 { - self.0.leading_zeros() - } - - /// Returns `true` if and only if `self == 2^k` for some `k`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(wrapping_int_impl)] - /// use std::num::Wrapping; - /// - #[doc = concat!("assert!(Wrapping(16", stringify!($t), ").is_power_of_two());")] - #[doc = concat!("assert!(!Wrapping(10", stringify!($t), ").is_power_of_two());")] - /// ``` - #[must_use] - #[inline] - #[unstable(feature = "wrapping_int_impl", issue = "32463")] - pub fn is_power_of_two(self) -> bool { - self.0.is_power_of_two() - } - - /// Returns the smallest power of two greater than or equal to `self`. - /// - /// When return value overflows (i.e., `self > (1 << (N-1))` for type - /// `uN`), overflows to `2^N = 0`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(wrapping_next_power_of_two)] - /// use std::num::Wrapping; - /// - #[doc = concat!("assert_eq!(Wrapping(2", stringify!($t), ").next_power_of_two(), Wrapping(2));")] - #[doc = concat!("assert_eq!(Wrapping(3", stringify!($t), ").next_power_of_two(), Wrapping(4));")] - #[doc = concat!("assert_eq!(Wrapping(200_u8).next_power_of_two(), Wrapping(0));")] - /// ``` - #[inline] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[unstable(feature = "wrapping_next_power_of_two", issue = "32463", - reason = "needs decision on wrapping behaviour")] - pub fn next_power_of_two(self) -> Self { - Wrapping(self.0.wrapping_next_power_of_two()) - } - } - )*) -} - -wrapping_int_impl_unsigned! { usize u8 u16 u32 u64 u128 } - -mod shift_max { - #![allow(non_upper_case_globals)] - - #[cfg(target_pointer_width = "16")] - mod platform { - pub const usize: u32 = super::u16; - pub const isize: u32 = super::i16; - } - - #[cfg(target_pointer_width = "32")] - mod platform { - pub const usize: u32 = super::u32; - pub const isize: u32 = super::i32; - } - - #[cfg(target_pointer_width = "64")] - mod platform { - pub const usize: u32 = super::u64; - pub const isize: u32 = super::i64; - } - - pub const i8: u32 = (1 << 3) - 1; - pub const i16: u32 = (1 << 4) - 1; - pub const i32: u32 = (1 << 5) - 1; - pub const i64: u32 = (1 << 6) - 1; - pub const i128: u32 = (1 << 7) - 1; - pub use self::platform::isize; - - pub const u8: u32 = i8; - pub const u16: u32 = i16; - pub const u32: u32 = i32; - pub const u64: u32 = i64; - pub const u128: u32 = i128; - pub use self::platform::usize; -} diff --git a/library/core/src/ops/arith.rs b/library/core/src/ops/arith.rs deleted file mode 100644 index 5e77788d8ea36..0000000000000 --- a/library/core/src/ops/arith.rs +++ /dev/null @@ -1,1011 +0,0 @@ -/// The addition operator `+`. -/// -/// Note that `Rhs` is `Self` by default, but this is not mandatory. For -/// example, [`std::time::SystemTime`] implements `Add`, which permits -/// operations of the form `SystemTime = SystemTime + Duration`. -/// -/// [`std::time::SystemTime`]: ../../std/time/struct.SystemTime.html -/// -/// # Examples -/// -/// ## `Add`able points -/// -/// ``` -/// use std::ops::Add; -/// -/// #[derive(Debug, Copy, Clone, PartialEq)] -/// struct Point { -/// x: i32, -/// y: i32, -/// } -/// -/// impl Add for Point { -/// type Output = Self; -/// -/// fn add(self, other: Self) -> Self { -/// Self { -/// x: self.x + other.x, -/// y: self.y + other.y, -/// } -/// } -/// } -/// -/// assert_eq!(Point { x: 1, y: 0 } + Point { x: 2, y: 3 }, -/// Point { x: 3, y: 3 }); -/// ``` -/// -/// ## Implementing `Add` with generics -/// -/// Here is an example of the same `Point` struct implementing the `Add` trait -/// using generics. -/// -/// ``` -/// use std::ops::Add; -/// -/// #[derive(Debug, Copy, Clone, PartialEq)] -/// struct Point { -/// x: T, -/// y: T, -/// } -/// -/// // Notice that the implementation uses the associated type `Output`. -/// impl> Add for Point { -/// type Output = Self; -/// -/// fn add(self, other: Self) -> Self::Output { -/// Self { -/// x: self.x + other.x, -/// y: self.y + other.y, -/// } -/// } -/// } -/// -/// assert_eq!(Point { x: 1, y: 0 } + Point { x: 2, y: 3 }, -/// Point { x: 3, y: 3 }); -/// ``` -#[lang = "add"] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_on_unimplemented( - on(all(_Self = "{integer}", Rhs = "{float}"), message = "cannot add a float to an integer",), - on(all(_Self = "{float}", Rhs = "{integer}"), message = "cannot add an integer to a float",), - message = "cannot add `{Rhs}` to `{Self}`", - label = "no implementation for `{Self} + {Rhs}`", - append_const_msg -)] -#[doc(alias = "+")] -#[const_trait] -pub trait Add { - /// The resulting type after applying the `+` operator. - #[stable(feature = "rust1", since = "1.0.0")] - type Output; - - /// Performs the `+` operation. - /// - /// # Example - /// - /// ``` - /// assert_eq!(12 + 1, 13); - /// ``` - #[must_use = "this returns the result of the operation, without modifying the original"] - #[rustc_diagnostic_item = "add"] - #[stable(feature = "rust1", since = "1.0.0")] - fn add(self, rhs: Rhs) -> Self::Output; -} - -macro_rules! add_impl { - ($($t:ty)*) => ($( - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_ops", issue = "90080")] - impl const Add for $t { - type Output = $t; - - #[inline] - #[track_caller] - #[rustc_inherit_overflow_checks] - fn add(self, other: $t) -> $t { self + other } - } - - forward_ref_binop! { impl Add, add for $t, $t } - )*) -} - -add_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f16 f32 f64 f128 } - -/// The subtraction operator `-`. -/// -/// Note that `Rhs` is `Self` by default, but this is not mandatory. For -/// example, [`std::time::SystemTime`] implements `Sub`, which permits -/// operations of the form `SystemTime = SystemTime - Duration`. -/// -/// [`std::time::SystemTime`]: ../../std/time/struct.SystemTime.html -/// -/// # Examples -/// -/// ## `Sub`tractable points -/// -/// ``` -/// use std::ops::Sub; -/// -/// #[derive(Debug, Copy, Clone, PartialEq)] -/// struct Point { -/// x: i32, -/// y: i32, -/// } -/// -/// impl Sub for Point { -/// type Output = Self; -/// -/// fn sub(self, other: Self) -> Self::Output { -/// Self { -/// x: self.x - other.x, -/// y: self.y - other.y, -/// } -/// } -/// } -/// -/// assert_eq!(Point { x: 3, y: 3 } - Point { x: 2, y: 3 }, -/// Point { x: 1, y: 0 }); -/// ``` -/// -/// ## Implementing `Sub` with generics -/// -/// Here is an example of the same `Point` struct implementing the `Sub` trait -/// using generics. -/// -/// ``` -/// use std::ops::Sub; -/// -/// #[derive(Debug, PartialEq)] -/// struct Point { -/// x: T, -/// y: T, -/// } -/// -/// // Notice that the implementation uses the associated type `Output`. -/// impl> Sub for Point { -/// type Output = Self; -/// -/// fn sub(self, other: Self) -> Self::Output { -/// Point { -/// x: self.x - other.x, -/// y: self.y - other.y, -/// } -/// } -/// } -/// -/// assert_eq!(Point { x: 2, y: 3 } - Point { x: 1, y: 0 }, -/// Point { x: 1, y: 3 }); -/// ``` -#[lang = "sub"] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_on_unimplemented( - message = "cannot subtract `{Rhs}` from `{Self}`", - label = "no implementation for `{Self} - {Rhs}`", - append_const_msg -)] -#[doc(alias = "-")] -pub trait Sub { - /// The resulting type after applying the `-` operator. - #[stable(feature = "rust1", since = "1.0.0")] - type Output; - - /// Performs the `-` operation. - /// - /// # Example - /// - /// ``` - /// assert_eq!(12 - 1, 11); - /// ``` - #[must_use = "this returns the result of the operation, without modifying the original"] - #[rustc_diagnostic_item = "sub"] - #[stable(feature = "rust1", since = "1.0.0")] - fn sub(self, rhs: Rhs) -> Self::Output; -} - -macro_rules! sub_impl { - ($($t:ty)*) => ($( - #[stable(feature = "rust1", since = "1.0.0")] - impl Sub for $t { - type Output = $t; - - #[inline] - #[track_caller] - #[rustc_inherit_overflow_checks] - fn sub(self, other: $t) -> $t { self - other } - } - - forward_ref_binop! { impl Sub, sub for $t, $t } - )*) -} - -sub_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f16 f32 f64 f128 } - -/// The multiplication operator `*`. -/// -/// Note that `Rhs` is `Self` by default, but this is not mandatory. -/// -/// # Examples -/// -/// ## `Mul`tipliable rational numbers -/// -/// ``` -/// use std::ops::Mul; -/// -/// // By the fundamental theorem of arithmetic, rational numbers in lowest -/// // terms are unique. So, by keeping `Rational`s in reduced form, we can -/// // derive `Eq` and `PartialEq`. -/// #[derive(Debug, Eq, PartialEq)] -/// struct Rational { -/// numerator: usize, -/// denominator: usize, -/// } -/// -/// impl Rational { -/// fn new(numerator: usize, denominator: usize) -> Self { -/// if denominator == 0 { -/// panic!("Zero is an invalid denominator!"); -/// } -/// -/// // Reduce to lowest terms by dividing by the greatest common -/// // divisor. -/// let gcd = gcd(numerator, denominator); -/// Self { -/// numerator: numerator / gcd, -/// denominator: denominator / gcd, -/// } -/// } -/// } -/// -/// impl Mul for Rational { -/// // The multiplication of rational numbers is a closed operation. -/// type Output = Self; -/// -/// fn mul(self, rhs: Self) -> Self { -/// let numerator = self.numerator * rhs.numerator; -/// let denominator = self.denominator * rhs.denominator; -/// Self::new(numerator, denominator) -/// } -/// } -/// -/// // Euclid's two-thousand-year-old algorithm for finding the greatest common -/// // divisor. -/// fn gcd(x: usize, y: usize) -> usize { -/// let mut x = x; -/// let mut y = y; -/// while y != 0 { -/// let t = y; -/// y = x % y; -/// x = t; -/// } -/// x -/// } -/// -/// assert_eq!(Rational::new(1, 2), Rational::new(2, 4)); -/// assert_eq!(Rational::new(2, 3) * Rational::new(3, 4), -/// Rational::new(1, 2)); -/// ``` -/// -/// ## Multiplying vectors by scalars as in linear algebra -/// -/// ``` -/// use std::ops::Mul; -/// -/// struct Scalar { value: usize } -/// -/// #[derive(Debug, PartialEq)] -/// struct Vector { value: Vec } -/// -/// impl Mul for Vector { -/// type Output = Self; -/// -/// fn mul(self, rhs: Scalar) -> Self::Output { -/// Self { value: self.value.iter().map(|v| v * rhs.value).collect() } -/// } -/// } -/// -/// let vector = Vector { value: vec![2, 4, 6] }; -/// let scalar = Scalar { value: 3 }; -/// assert_eq!(vector * scalar, Vector { value: vec![6, 12, 18] }); -/// ``` -#[lang = "mul"] -#[stable(feature = "rust1", since = "1.0.0")] -#[diagnostic::on_unimplemented( - message = "cannot multiply `{Self}` by `{Rhs}`", - label = "no implementation for `{Self} * {Rhs}`" -)] -#[doc(alias = "*")] -pub trait Mul { - /// The resulting type after applying the `*` operator. - #[stable(feature = "rust1", since = "1.0.0")] - type Output; - - /// Performs the `*` operation. - /// - /// # Example - /// - /// ``` - /// assert_eq!(12 * 2, 24); - /// ``` - #[must_use = "this returns the result of the operation, without modifying the original"] - #[rustc_diagnostic_item = "mul"] - #[stable(feature = "rust1", since = "1.0.0")] - fn mul(self, rhs: Rhs) -> Self::Output; -} - -macro_rules! mul_impl { - ($($t:ty)*) => ($( - #[stable(feature = "rust1", since = "1.0.0")] - impl Mul for $t { - type Output = $t; - - #[inline] - #[track_caller] - #[rustc_inherit_overflow_checks] - fn mul(self, other: $t) -> $t { self * other } - } - - forward_ref_binop! { impl Mul, mul for $t, $t } - )*) -} - -mul_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f16 f32 f64 f128 } - -/// The division operator `/`. -/// -/// Note that `Rhs` is `Self` by default, but this is not mandatory. -/// -/// # Examples -/// -/// ## `Div`idable rational numbers -/// -/// ``` -/// use std::ops::Div; -/// -/// // By the fundamental theorem of arithmetic, rational numbers in lowest -/// // terms are unique. So, by keeping `Rational`s in reduced form, we can -/// // derive `Eq` and `PartialEq`. -/// #[derive(Debug, Eq, PartialEq)] -/// struct Rational { -/// numerator: usize, -/// denominator: usize, -/// } -/// -/// impl Rational { -/// fn new(numerator: usize, denominator: usize) -> Self { -/// if denominator == 0 { -/// panic!("Zero is an invalid denominator!"); -/// } -/// -/// // Reduce to lowest terms by dividing by the greatest common -/// // divisor. -/// let gcd = gcd(numerator, denominator); -/// Self { -/// numerator: numerator / gcd, -/// denominator: denominator / gcd, -/// } -/// } -/// } -/// -/// impl Div for Rational { -/// // The division of rational numbers is a closed operation. -/// type Output = Self; -/// -/// fn div(self, rhs: Self) -> Self::Output { -/// if rhs.numerator == 0 { -/// panic!("Cannot divide by zero-valued `Rational`!"); -/// } -/// -/// let numerator = self.numerator * rhs.denominator; -/// let denominator = self.denominator * rhs.numerator; -/// Self::new(numerator, denominator) -/// } -/// } -/// -/// // Euclid's two-thousand-year-old algorithm for finding the greatest common -/// // divisor. -/// fn gcd(x: usize, y: usize) -> usize { -/// let mut x = x; -/// let mut y = y; -/// while y != 0 { -/// let t = y; -/// y = x % y; -/// x = t; -/// } -/// x -/// } -/// -/// assert_eq!(Rational::new(1, 2), Rational::new(2, 4)); -/// assert_eq!(Rational::new(1, 2) / Rational::new(3, 4), -/// Rational::new(2, 3)); -/// ``` -/// -/// ## Dividing vectors by scalars as in linear algebra -/// -/// ``` -/// use std::ops::Div; -/// -/// struct Scalar { value: f32 } -/// -/// #[derive(Debug, PartialEq)] -/// struct Vector { value: Vec } -/// -/// impl Div for Vector { -/// type Output = Self; -/// -/// fn div(self, rhs: Scalar) -> Self::Output { -/// Self { value: self.value.iter().map(|v| v / rhs.value).collect() } -/// } -/// } -/// -/// let scalar = Scalar { value: 2f32 }; -/// let vector = Vector { value: vec![2f32, 4f32, 6f32] }; -/// assert_eq!(vector / scalar, Vector { value: vec![1f32, 2f32, 3f32] }); -/// ``` -#[lang = "div"] -#[stable(feature = "rust1", since = "1.0.0")] -#[diagnostic::on_unimplemented( - message = "cannot divide `{Self}` by `{Rhs}`", - label = "no implementation for `{Self} / {Rhs}`" -)] -#[doc(alias = "/")] -pub trait Div { - /// The resulting type after applying the `/` operator. - #[stable(feature = "rust1", since = "1.0.0")] - type Output; - - /// Performs the `/` operation. - /// - /// # Example - /// - /// ``` - /// assert_eq!(12 / 2, 6); - /// ``` - #[must_use = "this returns the result of the operation, without modifying the original"] - #[rustc_diagnostic_item = "div"] - #[stable(feature = "rust1", since = "1.0.0")] - fn div(self, rhs: Rhs) -> Self::Output; -} - -macro_rules! div_impl_integer { - ($(($($t:ty)*) => $panic:expr),*) => ($($( - /// This operation rounds towards zero, truncating any - /// fractional part of the exact result. - /// - /// # Panics - /// - #[doc = $panic] - #[stable(feature = "rust1", since = "1.0.0")] - impl Div for $t { - type Output = $t; - - #[inline] - #[track_caller] - fn div(self, other: $t) -> $t { self / other } - } - - forward_ref_binop! { impl Div, div for $t, $t } - )*)*) -} - -div_impl_integer! { - (usize u8 u16 u32 u64 u128) => "This operation will panic if `other == 0`.", - (isize i8 i16 i32 i64 i128) => "This operation will panic if `other == 0` or the division results in overflow." -} - -macro_rules! div_impl_float { - ($($t:ty)*) => ($( - #[stable(feature = "rust1", since = "1.0.0")] - impl Div for $t { - type Output = $t; - - #[inline] - fn div(self, other: $t) -> $t { self / other } - } - - forward_ref_binop! { impl Div, div for $t, $t } - )*) -} - -div_impl_float! { f16 f32 f64 f128 } - -/// The remainder operator `%`. -/// -/// Note that `Rhs` is `Self` by default, but this is not mandatory. -/// -/// # Examples -/// -/// This example implements `Rem` on a `SplitSlice` object. After `Rem` is -/// implemented, one can use the `%` operator to find out what the remaining -/// elements of the slice would be after splitting it into equal slices of a -/// given length. -/// -/// ``` -/// use std::ops::Rem; -/// -/// #[derive(PartialEq, Debug)] -/// struct SplitSlice<'a, T> { -/// slice: &'a [T], -/// } -/// -/// impl<'a, T> Rem for SplitSlice<'a, T> { -/// type Output = Self; -/// -/// fn rem(self, modulus: usize) -> Self::Output { -/// let len = self.slice.len(); -/// let rem = len % modulus; -/// let start = len - rem; -/// Self {slice: &self.slice[start..]} -/// } -/// } -/// -/// // If we were to divide &[0, 1, 2, 3, 4, 5, 6, 7] into slices of size 3, -/// // the remainder would be &[6, 7]. -/// assert_eq!(SplitSlice { slice: &[0, 1, 2, 3, 4, 5, 6, 7] } % 3, -/// SplitSlice { slice: &[6, 7] }); -/// ``` -#[lang = "rem"] -#[stable(feature = "rust1", since = "1.0.0")] -#[diagnostic::on_unimplemented( - message = "cannot calculate the remainder of `{Self}` divided by `{Rhs}`", - label = "no implementation for `{Self} % {Rhs}`" -)] -#[doc(alias = "%")] -pub trait Rem { - /// The resulting type after applying the `%` operator. - #[stable(feature = "rust1", since = "1.0.0")] - type Output; - - /// Performs the `%` operation. - /// - /// # Example - /// - /// ``` - /// assert_eq!(12 % 10, 2); - /// ``` - #[must_use = "this returns the result of the operation, without modifying the original"] - #[rustc_diagnostic_item = "rem"] - #[stable(feature = "rust1", since = "1.0.0")] - fn rem(self, rhs: Rhs) -> Self::Output; -} - -macro_rules! rem_impl_integer { - ($(($($t:ty)*) => $panic:expr),*) => ($($( - /// This operation satisfies `n % d == n - (n / d) * d`. The - /// result has the same sign as the left operand. - /// - /// # Panics - /// - #[doc = $panic] - #[stable(feature = "rust1", since = "1.0.0")] - impl Rem for $t { - type Output = $t; - - #[inline] - #[track_caller] - fn rem(self, other: $t) -> $t { self % other } - } - - forward_ref_binop! { impl Rem, rem for $t, $t } - )*)*) -} - -rem_impl_integer! { - (usize u8 u16 u32 u64 u128) => "This operation will panic if `other == 0`.", - (isize i8 i16 i32 i64 i128) => "This operation will panic if `other == 0` or if `self / other` results in overflow." -} - -macro_rules! rem_impl_float { - ($($t:ty)*) => ($( - - /// The remainder from the division of two floats. - /// - /// The remainder has the same sign as the dividend and is computed as: - /// `x - (x / y).trunc() * y`. - /// - /// # Examples - /// ``` - /// let x: f32 = 50.50; - /// let y: f32 = 8.125; - /// let remainder = x - (x / y).trunc() * y; - /// - /// // The answer to both operations is 1.75 - /// assert_eq!(x % y, remainder); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - impl Rem for $t { - type Output = $t; - - #[inline] - fn rem(self, other: $t) -> $t { self % other } - } - - forward_ref_binop! { impl Rem, rem for $t, $t } - )*) -} - -rem_impl_float! { f16 f32 f64 f128 } - -/// The unary negation operator `-`. -/// -/// # Examples -/// -/// An implementation of `Neg` for `Sign`, which allows the use of `-` to -/// negate its value. -/// -/// ``` -/// use std::ops::Neg; -/// -/// #[derive(Debug, PartialEq)] -/// enum Sign { -/// Negative, -/// Zero, -/// Positive, -/// } -/// -/// impl Neg for Sign { -/// type Output = Self; -/// -/// fn neg(self) -> Self::Output { -/// match self { -/// Sign::Negative => Sign::Positive, -/// Sign::Zero => Sign::Zero, -/// Sign::Positive => Sign::Negative, -/// } -/// } -/// } -/// -/// // A negative positive is a negative. -/// assert_eq!(-Sign::Positive, Sign::Negative); -/// // A double negative is a positive. -/// assert_eq!(-Sign::Negative, Sign::Positive); -/// // Zero is its own negation. -/// assert_eq!(-Sign::Zero, Sign::Zero); -/// ``` -#[lang = "neg"] -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(alias = "-")] -pub trait Neg { - /// The resulting type after applying the `-` operator. - #[stable(feature = "rust1", since = "1.0.0")] - type Output; - - /// Performs the unary `-` operation. - /// - /// # Example - /// - /// ``` - /// let x: i32 = 12; - /// assert_eq!(-x, -12); - /// ``` - #[must_use = "this returns the result of the operation, without modifying the original"] - #[rustc_diagnostic_item = "neg"] - #[stable(feature = "rust1", since = "1.0.0")] - fn neg(self) -> Self::Output; -} - -macro_rules! neg_impl { - ($($t:ty)*) => ($( - #[stable(feature = "rust1", since = "1.0.0")] - impl Neg for $t { - type Output = $t; - - #[inline] - #[rustc_inherit_overflow_checks] - fn neg(self) -> $t { -self } - } - - forward_ref_unop! { impl Neg, neg for $t } - )*) -} - -neg_impl! { isize i8 i16 i32 i64 i128 f16 f32 f64 f128 } - -/// The addition assignment operator `+=`. -/// -/// # Examples -/// -/// This example creates a `Point` struct that implements the `AddAssign` -/// trait, and then demonstrates add-assigning to a mutable `Point`. -/// -/// ``` -/// use std::ops::AddAssign; -/// -/// #[derive(Debug, Copy, Clone, PartialEq)] -/// struct Point { -/// x: i32, -/// y: i32, -/// } -/// -/// impl AddAssign for Point { -/// fn add_assign(&mut self, other: Self) { -/// *self = Self { -/// x: self.x + other.x, -/// y: self.y + other.y, -/// }; -/// } -/// } -/// -/// let mut point = Point { x: 1, y: 0 }; -/// point += Point { x: 2, y: 3 }; -/// assert_eq!(point, Point { x: 3, y: 3 }); -/// ``` -#[lang = "add_assign"] -#[stable(feature = "op_assign_traits", since = "1.8.0")] -#[diagnostic::on_unimplemented( - message = "cannot add-assign `{Rhs}` to `{Self}`", - label = "no implementation for `{Self} += {Rhs}`" -)] -#[doc(alias = "+")] -#[doc(alias = "+=")] -pub trait AddAssign { - /// Performs the `+=` operation. - /// - /// # Example - /// - /// ``` - /// let mut x: u32 = 12; - /// x += 1; - /// assert_eq!(x, 13); - /// ``` - #[stable(feature = "op_assign_traits", since = "1.8.0")] - fn add_assign(&mut self, rhs: Rhs); -} - -macro_rules! add_assign_impl { - ($($t:ty)+) => ($( - #[stable(feature = "op_assign_traits", since = "1.8.0")] - impl AddAssign for $t { - #[inline] - #[track_caller] - #[rustc_inherit_overflow_checks] - fn add_assign(&mut self, other: $t) { *self += other } - } - - forward_ref_op_assign! { impl AddAssign, add_assign for $t, $t } - )+) -} - -add_assign_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f16 f32 f64 f128 } - -/// The subtraction assignment operator `-=`. -/// -/// # Examples -/// -/// This example creates a `Point` struct that implements the `SubAssign` -/// trait, and then demonstrates sub-assigning to a mutable `Point`. -/// -/// ``` -/// use std::ops::SubAssign; -/// -/// #[derive(Debug, Copy, Clone, PartialEq)] -/// struct Point { -/// x: i32, -/// y: i32, -/// } -/// -/// impl SubAssign for Point { -/// fn sub_assign(&mut self, other: Self) { -/// *self = Self { -/// x: self.x - other.x, -/// y: self.y - other.y, -/// }; -/// } -/// } -/// -/// let mut point = Point { x: 3, y: 3 }; -/// point -= Point { x: 2, y: 3 }; -/// assert_eq!(point, Point {x: 1, y: 0}); -/// ``` -#[lang = "sub_assign"] -#[stable(feature = "op_assign_traits", since = "1.8.0")] -#[diagnostic::on_unimplemented( - message = "cannot subtract-assign `{Rhs}` from `{Self}`", - label = "no implementation for `{Self} -= {Rhs}`" -)] -#[doc(alias = "-")] -#[doc(alias = "-=")] -pub trait SubAssign { - /// Performs the `-=` operation. - /// - /// # Example - /// - /// ``` - /// let mut x: u32 = 12; - /// x -= 1; - /// assert_eq!(x, 11); - /// ``` - #[stable(feature = "op_assign_traits", since = "1.8.0")] - fn sub_assign(&mut self, rhs: Rhs); -} - -macro_rules! sub_assign_impl { - ($($t:ty)+) => ($( - #[stable(feature = "op_assign_traits", since = "1.8.0")] - impl SubAssign for $t { - #[inline] - #[track_caller] - #[rustc_inherit_overflow_checks] - fn sub_assign(&mut self, other: $t) { *self -= other } - } - - forward_ref_op_assign! { impl SubAssign, sub_assign for $t, $t } - )+) -} - -sub_assign_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f16 f32 f64 f128 } - -/// The multiplication assignment operator `*=`. -/// -/// # Examples -/// -/// ``` -/// use std::ops::MulAssign; -/// -/// #[derive(Debug, PartialEq)] -/// struct Frequency { hertz: f64 } -/// -/// impl MulAssign for Frequency { -/// fn mul_assign(&mut self, rhs: f64) { -/// self.hertz *= rhs; -/// } -/// } -/// -/// let mut frequency = Frequency { hertz: 50.0 }; -/// frequency *= 4.0; -/// assert_eq!(Frequency { hertz: 200.0 }, frequency); -/// ``` -#[lang = "mul_assign"] -#[stable(feature = "op_assign_traits", since = "1.8.0")] -#[diagnostic::on_unimplemented( - message = "cannot multiply-assign `{Self}` by `{Rhs}`", - label = "no implementation for `{Self} *= {Rhs}`" -)] -#[doc(alias = "*")] -#[doc(alias = "*=")] -pub trait MulAssign { - /// Performs the `*=` operation. - /// - /// # Example - /// - /// ``` - /// let mut x: u32 = 12; - /// x *= 2; - /// assert_eq!(x, 24); - /// ``` - #[stable(feature = "op_assign_traits", since = "1.8.0")] - fn mul_assign(&mut self, rhs: Rhs); -} - -macro_rules! mul_assign_impl { - ($($t:ty)+) => ($( - #[stable(feature = "op_assign_traits", since = "1.8.0")] - impl MulAssign for $t { - #[inline] - #[track_caller] - #[rustc_inherit_overflow_checks] - fn mul_assign(&mut self, other: $t) { *self *= other } - } - - forward_ref_op_assign! { impl MulAssign, mul_assign for $t, $t } - )+) -} - -mul_assign_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f16 f32 f64 f128 } - -/// The division assignment operator `/=`. -/// -/// # Examples -/// -/// ``` -/// use std::ops::DivAssign; -/// -/// #[derive(Debug, PartialEq)] -/// struct Frequency { hertz: f64 } -/// -/// impl DivAssign for Frequency { -/// fn div_assign(&mut self, rhs: f64) { -/// self.hertz /= rhs; -/// } -/// } -/// -/// let mut frequency = Frequency { hertz: 200.0 }; -/// frequency /= 4.0; -/// assert_eq!(Frequency { hertz: 50.0 }, frequency); -/// ``` -#[lang = "div_assign"] -#[stable(feature = "op_assign_traits", since = "1.8.0")] -#[diagnostic::on_unimplemented( - message = "cannot divide-assign `{Self}` by `{Rhs}`", - label = "no implementation for `{Self} /= {Rhs}`" -)] -#[doc(alias = "/")] -#[doc(alias = "/=")] -pub trait DivAssign { - /// Performs the `/=` operation. - /// - /// # Example - /// - /// ``` - /// let mut x: u32 = 12; - /// x /= 2; - /// assert_eq!(x, 6); - /// ``` - #[stable(feature = "op_assign_traits", since = "1.8.0")] - fn div_assign(&mut self, rhs: Rhs); -} - -macro_rules! div_assign_impl { - ($($t:ty)+) => ($( - #[stable(feature = "op_assign_traits", since = "1.8.0")] - impl DivAssign for $t { - #[inline] - #[track_caller] - fn div_assign(&mut self, other: $t) { *self /= other } - } - - forward_ref_op_assign! { impl DivAssign, div_assign for $t, $t } - )+) -} - -div_assign_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f16 f32 f64 f128 } - -/// The remainder assignment operator `%=`. -/// -/// # Examples -/// -/// ``` -/// use std::ops::RemAssign; -/// -/// struct CookieJar { cookies: u32 } -/// -/// impl RemAssign for CookieJar { -/// fn rem_assign(&mut self, piles: u32) { -/// self.cookies %= piles; -/// } -/// } -/// -/// let mut jar = CookieJar { cookies: 31 }; -/// let piles = 4; -/// -/// println!("Splitting up {} cookies into {} even piles!", jar.cookies, piles); -/// -/// jar %= piles; -/// -/// println!("{} cookies remain in the cookie jar!", jar.cookies); -/// ``` -#[lang = "rem_assign"] -#[stable(feature = "op_assign_traits", since = "1.8.0")] -#[diagnostic::on_unimplemented( - message = "cannot calculate and assign the remainder of `{Self}` divided by `{Rhs}`", - label = "no implementation for `{Self} %= {Rhs}`" -)] -#[doc(alias = "%")] -#[doc(alias = "%=")] -pub trait RemAssign { - /// Performs the `%=` operation. - /// - /// # Example - /// - /// ``` - /// let mut x: u32 = 12; - /// x %= 10; - /// assert_eq!(x, 2); - /// ``` - #[stable(feature = "op_assign_traits", since = "1.8.0")] - fn rem_assign(&mut self, rhs: Rhs); -} - -macro_rules! rem_assign_impl { - ($($t:ty)+) => ($( - #[stable(feature = "op_assign_traits", since = "1.8.0")] - impl RemAssign for $t { - #[inline] - #[track_caller] - fn rem_assign(&mut self, other: $t) { *self %= other } - } - - forward_ref_op_assign! { impl RemAssign, rem_assign for $t, $t } - )+) -} - -rem_assign_impl! { usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 f16 f32 f64 f128 } diff --git a/library/core/src/ops/async_function.rs b/library/core/src/ops/async_function.rs deleted file mode 100644 index 18bcee5a1c7e0..0000000000000 --- a/library/core/src/ops/async_function.rs +++ /dev/null @@ -1,148 +0,0 @@ -use crate::future::Future; -use crate::marker::Tuple; - -/// An async-aware version of the [`Fn`](crate::ops::Fn) trait. -/// -/// All `async fn` and functions returning futures implement this trait. -#[unstable(feature = "async_fn_traits", issue = "none")] -#[rustc_paren_sugar] -#[fundamental] -#[must_use = "async closures are lazy and do nothing unless called"] -#[lang = "async_fn"] -pub trait AsyncFn: AsyncFnMut { - /// Call the [`AsyncFn`], returning a future which may borrow from the called closure. - #[unstable(feature = "async_fn_traits", issue = "none")] - extern "rust-call" fn async_call(&self, args: Args) -> Self::CallRefFuture<'_>; -} - -/// An async-aware version of the [`FnMut`](crate::ops::FnMut) trait. -/// -/// All `async fn` and functions returning futures implement this trait. -#[unstable(feature = "async_fn_traits", issue = "none")] -#[rustc_paren_sugar] -#[fundamental] -#[must_use = "async closures are lazy and do nothing unless called"] -#[lang = "async_fn_mut"] -pub trait AsyncFnMut: AsyncFnOnce { - /// Future returned by [`AsyncFnMut::async_call_mut`] and [`AsyncFn::async_call`]. - #[unstable(feature = "async_fn_traits", issue = "none")] - type CallRefFuture<'a>: Future - where - Self: 'a; - - /// Call the [`AsyncFnMut`], returning a future which may borrow from the called closure. - #[unstable(feature = "async_fn_traits", issue = "none")] - extern "rust-call" fn async_call_mut(&mut self, args: Args) -> Self::CallRefFuture<'_>; -} - -/// An async-aware version of the [`FnOnce`](crate::ops::FnOnce) trait. -/// -/// All `async fn` and functions returning futures implement this trait. -#[unstable(feature = "async_fn_traits", issue = "none")] -#[rustc_paren_sugar] -#[fundamental] -#[must_use = "async closures are lazy and do nothing unless called"] -#[lang = "async_fn_once"] -pub trait AsyncFnOnce { - /// Future returned by [`AsyncFnOnce::async_call_once`]. - #[unstable(feature = "async_fn_traits", issue = "none")] - type CallOnceFuture: Future; - - /// Output type of the called closure's future. - #[unstable(feature = "async_fn_traits", issue = "none")] - type Output; - - /// Call the [`AsyncFnOnce`], returning a future which may move out of the called closure. - #[unstable(feature = "async_fn_traits", issue = "none")] - extern "rust-call" fn async_call_once(self, args: Args) -> Self::CallOnceFuture; -} - -mod impls { - use super::{AsyncFn, AsyncFnMut, AsyncFnOnce}; - use crate::marker::Tuple; - - #[unstable(feature = "async_fn_traits", issue = "none")] - impl AsyncFn for &F - where - F: AsyncFn, - { - extern "rust-call" fn async_call(&self, args: A) -> Self::CallRefFuture<'_> { - F::async_call(*self, args) - } - } - - #[unstable(feature = "async_fn_traits", issue = "none")] - impl AsyncFnMut for &F - where - F: AsyncFn, - { - type CallRefFuture<'a> = F::CallRefFuture<'a> where Self: 'a; - - extern "rust-call" fn async_call_mut(&mut self, args: A) -> Self::CallRefFuture<'_> { - F::async_call(*self, args) - } - } - - #[unstable(feature = "async_fn_traits", issue = "none")] - impl<'a, A: Tuple, F: ?Sized> AsyncFnOnce for &'a F - where - F: AsyncFn, - { - type Output = F::Output; - type CallOnceFuture = F::CallRefFuture<'a>; - - extern "rust-call" fn async_call_once(self, args: A) -> Self::CallOnceFuture { - F::async_call(self, args) - } - } - - #[unstable(feature = "async_fn_traits", issue = "none")] - impl AsyncFnMut for &mut F - where - F: AsyncFnMut, - { - type CallRefFuture<'a> = F::CallRefFuture<'a> where Self: 'a; - - extern "rust-call" fn async_call_mut(&mut self, args: A) -> Self::CallRefFuture<'_> { - F::async_call_mut(*self, args) - } - } - - #[unstable(feature = "async_fn_traits", issue = "none")] - impl<'a, A: Tuple, F: ?Sized> AsyncFnOnce for &'a mut F - where - F: AsyncFnMut, - { - type Output = F::Output; - type CallOnceFuture = F::CallRefFuture<'a>; - - extern "rust-call" fn async_call_once(self, args: A) -> Self::CallOnceFuture { - F::async_call_mut(self, args) - } - } -} - -mod internal_implementation_detail { - /// A helper trait that is used to enforce that the `ClosureKind` of a goal - /// is within the capabilities of a `CoroutineClosure`, and which allows us - /// to delay the projection of the tupled upvar types until after upvar - /// analysis is complete. - /// - /// The `Self` type is expected to be the `kind_ty` of the coroutine-closure, - /// and thus either `?0` or `i8`/`i16`/`i32` (see docs for `ClosureKind` - /// for an explanation of that). The `GoalKind` is also the same type, but - /// representing the kind of the trait that the closure is being called with. - #[lang = "async_fn_kind_helper"] - trait AsyncFnKindHelper { - // Projects a set of closure inputs (arguments), a region, and a set of upvars - // (by move and by ref) to the upvars that we expect the coroutine to have - // according to the `GoalKind` parameter above. - // - // The `Upvars` parameter should be the upvars of the parent coroutine-closure, - // and the `BorrowedUpvarsAsFnPtr` will be a function pointer that has the shape - // `for<'env> fn() -> (&'env T, ...)`. This allows us to represent the binder - // of the closure's self-capture, and these upvar types will be instantiated with - // the `'closure_env` region provided to the associated type. - type Upvars<'closure_env, Inputs, Upvars, BorrowedUpvarsAsFnPtr>; - } -} diff --git a/library/core/src/ops/bit.rs b/library/core/src/ops/bit.rs deleted file mode 100644 index 6984100e498e8..0000000000000 --- a/library/core/src/ops/bit.rs +++ /dev/null @@ -1,1032 +0,0 @@ -/// The unary logical negation operator `!`. -/// -/// # Examples -/// -/// An implementation of `Not` for `Answer`, which enables the use of `!` to -/// invert its value. -/// -/// ``` -/// use std::ops::Not; -/// -/// #[derive(Debug, PartialEq)] -/// enum Answer { -/// Yes, -/// No, -/// } -/// -/// impl Not for Answer { -/// type Output = Self; -/// -/// fn not(self) -> Self::Output { -/// match self { -/// Answer::Yes => Answer::No, -/// Answer::No => Answer::Yes -/// } -/// } -/// } -/// -/// assert_eq!(!Answer::Yes, Answer::No); -/// assert_eq!(!Answer::No, Answer::Yes); -/// ``` -#[lang = "not"] -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(alias = "!")] -pub trait Not { - /// The resulting type after applying the `!` operator. - #[stable(feature = "rust1", since = "1.0.0")] - type Output; - - /// Performs the unary `!` operation. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(!true, false); - /// assert_eq!(!false, true); - /// assert_eq!(!1u8, 254); - /// assert_eq!(!0u8, 255); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - fn not(self) -> Self::Output; -} - -macro_rules! not_impl { - ($($t:ty)*) => ($( - #[stable(feature = "rust1", since = "1.0.0")] - impl Not for $t { - type Output = $t; - - #[inline] - fn not(self) -> $t { !self } - } - - forward_ref_unop! { impl Not, not for $t } - )*) -} - -not_impl! { bool usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 } - -#[stable(feature = "not_never", since = "1.60.0")] -impl Not for ! { - type Output = !; - - #[inline] - fn not(self) -> ! { - match self {} - } -} - -/// The bitwise AND operator `&`. -/// -/// Note that `Rhs` is `Self` by default, but this is not mandatory. -/// -/// # Examples -/// -/// An implementation of `BitAnd` for a wrapper around `bool`. -/// -/// ``` -/// use std::ops::BitAnd; -/// -/// #[derive(Debug, PartialEq)] -/// struct Scalar(bool); -/// -/// impl BitAnd for Scalar { -/// type Output = Self; -/// -/// // rhs is the "right-hand side" of the expression `a & b` -/// fn bitand(self, rhs: Self) -> Self::Output { -/// Self(self.0 & rhs.0) -/// } -/// } -/// -/// assert_eq!(Scalar(true) & Scalar(true), Scalar(true)); -/// assert_eq!(Scalar(true) & Scalar(false), Scalar(false)); -/// assert_eq!(Scalar(false) & Scalar(true), Scalar(false)); -/// assert_eq!(Scalar(false) & Scalar(false), Scalar(false)); -/// ``` -/// -/// An implementation of `BitAnd` for a wrapper around `Vec`. -/// -/// ``` -/// use std::ops::BitAnd; -/// -/// #[derive(Debug, PartialEq)] -/// struct BooleanVector(Vec); -/// -/// impl BitAnd for BooleanVector { -/// type Output = Self; -/// -/// fn bitand(self, Self(rhs): Self) -> Self::Output { -/// let Self(lhs) = self; -/// assert_eq!(lhs.len(), rhs.len()); -/// Self( -/// lhs.iter() -/// .zip(rhs.iter()) -/// .map(|(x, y)| *x & *y) -/// .collect() -/// ) -/// } -/// } -/// -/// let bv1 = BooleanVector(vec![true, true, false, false]); -/// let bv2 = BooleanVector(vec![true, false, true, false]); -/// let expected = BooleanVector(vec![true, false, false, false]); -/// assert_eq!(bv1 & bv2, expected); -/// ``` -#[lang = "bitand"] -#[doc(alias = "&")] -#[stable(feature = "rust1", since = "1.0.0")] -#[diagnostic::on_unimplemented( - message = "no implementation for `{Self} & {Rhs}`", - label = "no implementation for `{Self} & {Rhs}`" -)] -pub trait BitAnd { - /// The resulting type after applying the `&` operator. - #[stable(feature = "rust1", since = "1.0.0")] - type Output; - - /// Performs the `&` operation. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(true & false, false); - /// assert_eq!(true & true, true); - /// assert_eq!(5u8 & 1u8, 1); - /// assert_eq!(5u8 & 2u8, 0); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - fn bitand(self, rhs: Rhs) -> Self::Output; -} - -macro_rules! bitand_impl { - ($($t:ty)*) => ($( - #[stable(feature = "rust1", since = "1.0.0")] - impl BitAnd for $t { - type Output = $t; - - #[inline] - fn bitand(self, rhs: $t) -> $t { self & rhs } - } - - forward_ref_binop! { impl BitAnd, bitand for $t, $t } - )*) -} - -bitand_impl! { bool usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 } - -/// The bitwise OR operator `|`. -/// -/// Note that `Rhs` is `Self` by default, but this is not mandatory. -/// -/// # Examples -/// -/// An implementation of `BitOr` for a wrapper around `bool`. -/// -/// ``` -/// use std::ops::BitOr; -/// -/// #[derive(Debug, PartialEq)] -/// struct Scalar(bool); -/// -/// impl BitOr for Scalar { -/// type Output = Self; -/// -/// // rhs is the "right-hand side" of the expression `a | b` -/// fn bitor(self, rhs: Self) -> Self::Output { -/// Self(self.0 | rhs.0) -/// } -/// } -/// -/// assert_eq!(Scalar(true) | Scalar(true), Scalar(true)); -/// assert_eq!(Scalar(true) | Scalar(false), Scalar(true)); -/// assert_eq!(Scalar(false) | Scalar(true), Scalar(true)); -/// assert_eq!(Scalar(false) | Scalar(false), Scalar(false)); -/// ``` -/// -/// An implementation of `BitOr` for a wrapper around `Vec`. -/// -/// ``` -/// use std::ops::BitOr; -/// -/// #[derive(Debug, PartialEq)] -/// struct BooleanVector(Vec); -/// -/// impl BitOr for BooleanVector { -/// type Output = Self; -/// -/// fn bitor(self, Self(rhs): Self) -> Self::Output { -/// let Self(lhs) = self; -/// assert_eq!(lhs.len(), rhs.len()); -/// Self( -/// lhs.iter() -/// .zip(rhs.iter()) -/// .map(|(x, y)| *x | *y) -/// .collect() -/// ) -/// } -/// } -/// -/// let bv1 = BooleanVector(vec![true, true, false, false]); -/// let bv2 = BooleanVector(vec![true, false, true, false]); -/// let expected = BooleanVector(vec![true, true, true, false]); -/// assert_eq!(bv1 | bv2, expected); -/// ``` -#[lang = "bitor"] -#[doc(alias = "|")] -#[stable(feature = "rust1", since = "1.0.0")] -#[diagnostic::on_unimplemented( - message = "no implementation for `{Self} | {Rhs}`", - label = "no implementation for `{Self} | {Rhs}`" -)] -pub trait BitOr { - /// The resulting type after applying the `|` operator. - #[stable(feature = "rust1", since = "1.0.0")] - type Output; - - /// Performs the `|` operation. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(true | false, true); - /// assert_eq!(false | false, false); - /// assert_eq!(5u8 | 1u8, 5); - /// assert_eq!(5u8 | 2u8, 7); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - fn bitor(self, rhs: Rhs) -> Self::Output; -} - -macro_rules! bitor_impl { - ($($t:ty)*) => ($( - #[stable(feature = "rust1", since = "1.0.0")] - impl BitOr for $t { - type Output = $t; - - #[inline] - fn bitor(self, rhs: $t) -> $t { self | rhs } - } - - forward_ref_binop! { impl BitOr, bitor for $t, $t } - )*) -} - -bitor_impl! { bool usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 } - -/// The bitwise XOR operator `^`. -/// -/// Note that `Rhs` is `Self` by default, but this is not mandatory. -/// -/// # Examples -/// -/// An implementation of `BitXor` that lifts `^` to a wrapper around `bool`. -/// -/// ``` -/// use std::ops::BitXor; -/// -/// #[derive(Debug, PartialEq)] -/// struct Scalar(bool); -/// -/// impl BitXor for Scalar { -/// type Output = Self; -/// -/// // rhs is the "right-hand side" of the expression `a ^ b` -/// fn bitxor(self, rhs: Self) -> Self::Output { -/// Self(self.0 ^ rhs.0) -/// } -/// } -/// -/// assert_eq!(Scalar(true) ^ Scalar(true), Scalar(false)); -/// assert_eq!(Scalar(true) ^ Scalar(false), Scalar(true)); -/// assert_eq!(Scalar(false) ^ Scalar(true), Scalar(true)); -/// assert_eq!(Scalar(false) ^ Scalar(false), Scalar(false)); -/// ``` -/// -/// An implementation of `BitXor` trait for a wrapper around `Vec`. -/// -/// ``` -/// use std::ops::BitXor; -/// -/// #[derive(Debug, PartialEq)] -/// struct BooleanVector(Vec); -/// -/// impl BitXor for BooleanVector { -/// type Output = Self; -/// -/// fn bitxor(self, Self(rhs): Self) -> Self::Output { -/// let Self(lhs) = self; -/// assert_eq!(lhs.len(), rhs.len()); -/// Self( -/// lhs.iter() -/// .zip(rhs.iter()) -/// .map(|(x, y)| *x ^ *y) -/// .collect() -/// ) -/// } -/// } -/// -/// let bv1 = BooleanVector(vec![true, true, false, false]); -/// let bv2 = BooleanVector(vec![true, false, true, false]); -/// let expected = BooleanVector(vec![false, true, true, false]); -/// assert_eq!(bv1 ^ bv2, expected); -/// ``` -#[lang = "bitxor"] -#[doc(alias = "^")] -#[stable(feature = "rust1", since = "1.0.0")] -#[diagnostic::on_unimplemented( - message = "no implementation for `{Self} ^ {Rhs}`", - label = "no implementation for `{Self} ^ {Rhs}`" -)] -pub trait BitXor { - /// The resulting type after applying the `^` operator. - #[stable(feature = "rust1", since = "1.0.0")] - type Output; - - /// Performs the `^` operation. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(true ^ false, true); - /// assert_eq!(true ^ true, false); - /// assert_eq!(5u8 ^ 1u8, 4); - /// assert_eq!(5u8 ^ 2u8, 7); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - fn bitxor(self, rhs: Rhs) -> Self::Output; -} - -macro_rules! bitxor_impl { - ($($t:ty)*) => ($( - #[stable(feature = "rust1", since = "1.0.0")] - impl BitXor for $t { - type Output = $t; - - #[inline] - fn bitxor(self, other: $t) -> $t { self ^ other } - } - - forward_ref_binop! { impl BitXor, bitxor for $t, $t } - )*) -} - -bitxor_impl! { bool usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 } - -/// The left shift operator `<<`. Note that because this trait is implemented -/// for all integer types with multiple right-hand-side types, Rust's type -/// checker has special handling for `_ << _`, setting the result type for -/// integer operations to the type of the left-hand-side operand. This means -/// that though `a << b` and `a.shl(b)` are one and the same from an evaluation -/// standpoint, they are different when it comes to type inference. -/// -/// # Examples -/// -/// An implementation of `Shl` that lifts the `<<` operation on integers to a -/// wrapper around `usize`. -/// -/// ``` -/// use std::ops::Shl; -/// -/// #[derive(PartialEq, Debug)] -/// struct Scalar(usize); -/// -/// impl Shl for Scalar { -/// type Output = Self; -/// -/// fn shl(self, Self(rhs): Self) -> Self::Output { -/// let Self(lhs) = self; -/// Self(lhs << rhs) -/// } -/// } -/// -/// assert_eq!(Scalar(4) << Scalar(2), Scalar(16)); -/// ``` -/// -/// An implementation of `Shl` that spins a vector leftward by a given amount. -/// -/// ``` -/// use std::ops::Shl; -/// -/// #[derive(PartialEq, Debug)] -/// struct SpinVector { -/// vec: Vec, -/// } -/// -/// impl Shl for SpinVector { -/// type Output = Self; -/// -/// fn shl(self, rhs: usize) -> Self::Output { -/// // Rotate the vector by `rhs` places. -/// let (a, b) = self.vec.split_at(rhs); -/// let mut spun_vector = vec![]; -/// spun_vector.extend_from_slice(b); -/// spun_vector.extend_from_slice(a); -/// Self { vec: spun_vector } -/// } -/// } -/// -/// assert_eq!(SpinVector { vec: vec![0, 1, 2, 3, 4] } << 2, -/// SpinVector { vec: vec![2, 3, 4, 0, 1] }); -/// ``` -#[lang = "shl"] -#[doc(alias = "<<")] -#[stable(feature = "rust1", since = "1.0.0")] -#[diagnostic::on_unimplemented( - message = "no implementation for `{Self} << {Rhs}`", - label = "no implementation for `{Self} << {Rhs}`" -)] -pub trait Shl { - /// The resulting type after applying the `<<` operator. - #[stable(feature = "rust1", since = "1.0.0")] - type Output; - - /// Performs the `<<` operation. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(5u8 << 1, 10); - /// assert_eq!(1u8 << 1, 2); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - fn shl(self, rhs: Rhs) -> Self::Output; -} - -macro_rules! shl_impl { - ($t:ty, $f:ty) => { - #[stable(feature = "rust1", since = "1.0.0")] - impl Shl<$f> for $t { - type Output = $t; - - #[inline] - #[rustc_inherit_overflow_checks] - fn shl(self, other: $f) -> $t { - self << other - } - } - - forward_ref_binop! { impl Shl, shl for $t, $f } - }; -} - -macro_rules! shl_impl_all { - ($($t:ty)*) => ($( - shl_impl! { $t, u8 } - shl_impl! { $t, u16 } - shl_impl! { $t, u32 } - shl_impl! { $t, u64 } - shl_impl! { $t, u128 } - shl_impl! { $t, usize } - - shl_impl! { $t, i8 } - shl_impl! { $t, i16 } - shl_impl! { $t, i32 } - shl_impl! { $t, i64 } - shl_impl! { $t, i128 } - shl_impl! { $t, isize } - )*) -} - -shl_impl_all! { u8 u16 u32 u64 u128 usize i8 i16 i32 i64 isize i128 } - -/// The right shift operator `>>`. Note that because this trait is implemented -/// for all integer types with multiple right-hand-side types, Rust's type -/// checker has special handling for `_ >> _`, setting the result type for -/// integer operations to the type of the left-hand-side operand. This means -/// that though `a >> b` and `a.shr(b)` are one and the same from an evaluation -/// standpoint, they are different when it comes to type inference. -/// -/// # Examples -/// -/// An implementation of `Shr` that lifts the `>>` operation on integers to a -/// wrapper around `usize`. -/// -/// ``` -/// use std::ops::Shr; -/// -/// #[derive(PartialEq, Debug)] -/// struct Scalar(usize); -/// -/// impl Shr for Scalar { -/// type Output = Self; -/// -/// fn shr(self, Self(rhs): Self) -> Self::Output { -/// let Self(lhs) = self; -/// Self(lhs >> rhs) -/// } -/// } -/// -/// assert_eq!(Scalar(16) >> Scalar(2), Scalar(4)); -/// ``` -/// -/// An implementation of `Shr` that spins a vector rightward by a given amount. -/// -/// ``` -/// use std::ops::Shr; -/// -/// #[derive(PartialEq, Debug)] -/// struct SpinVector { -/// vec: Vec, -/// } -/// -/// impl Shr for SpinVector { -/// type Output = Self; -/// -/// fn shr(self, rhs: usize) -> Self::Output { -/// // Rotate the vector by `rhs` places. -/// let (a, b) = self.vec.split_at(self.vec.len() - rhs); -/// let mut spun_vector = vec![]; -/// spun_vector.extend_from_slice(b); -/// spun_vector.extend_from_slice(a); -/// Self { vec: spun_vector } -/// } -/// } -/// -/// assert_eq!(SpinVector { vec: vec![0, 1, 2, 3, 4] } >> 2, -/// SpinVector { vec: vec![3, 4, 0, 1, 2] }); -/// ``` -#[lang = "shr"] -#[doc(alias = ">>")] -#[stable(feature = "rust1", since = "1.0.0")] -#[diagnostic::on_unimplemented( - message = "no implementation for `{Self} >> {Rhs}`", - label = "no implementation for `{Self} >> {Rhs}`" -)] -pub trait Shr { - /// The resulting type after applying the `>>` operator. - #[stable(feature = "rust1", since = "1.0.0")] - type Output; - - /// Performs the `>>` operation. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(5u8 >> 1, 2); - /// assert_eq!(2u8 >> 1, 1); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - fn shr(self, rhs: Rhs) -> Self::Output; -} - -macro_rules! shr_impl { - ($t:ty, $f:ty) => { - #[stable(feature = "rust1", since = "1.0.0")] - impl Shr<$f> for $t { - type Output = $t; - - #[inline] - #[rustc_inherit_overflow_checks] - fn shr(self, other: $f) -> $t { - self >> other - } - } - - forward_ref_binop! { impl Shr, shr for $t, $f } - }; -} - -macro_rules! shr_impl_all { - ($($t:ty)*) => ($( - shr_impl! { $t, u8 } - shr_impl! { $t, u16 } - shr_impl! { $t, u32 } - shr_impl! { $t, u64 } - shr_impl! { $t, u128 } - shr_impl! { $t, usize } - - shr_impl! { $t, i8 } - shr_impl! { $t, i16 } - shr_impl! { $t, i32 } - shr_impl! { $t, i64 } - shr_impl! { $t, i128 } - shr_impl! { $t, isize } - )*) -} - -shr_impl_all! { u8 u16 u32 u64 u128 usize i8 i16 i32 i64 i128 isize } - -/// The bitwise AND assignment operator `&=`. -/// -/// # Examples -/// -/// An implementation of `BitAndAssign` that lifts the `&=` operator to a -/// wrapper around `bool`. -/// -/// ``` -/// use std::ops::BitAndAssign; -/// -/// #[derive(Debug, PartialEq)] -/// struct Scalar(bool); -/// -/// impl BitAndAssign for Scalar { -/// // rhs is the "right-hand side" of the expression `a &= b` -/// fn bitand_assign(&mut self, rhs: Self) { -/// *self = Self(self.0 & rhs.0) -/// } -/// } -/// -/// let mut scalar = Scalar(true); -/// scalar &= Scalar(true); -/// assert_eq!(scalar, Scalar(true)); -/// -/// let mut scalar = Scalar(true); -/// scalar &= Scalar(false); -/// assert_eq!(scalar, Scalar(false)); -/// -/// let mut scalar = Scalar(false); -/// scalar &= Scalar(true); -/// assert_eq!(scalar, Scalar(false)); -/// -/// let mut scalar = Scalar(false); -/// scalar &= Scalar(false); -/// assert_eq!(scalar, Scalar(false)); -/// ``` -/// -/// Here, the `BitAndAssign` trait is implemented for a wrapper around -/// `Vec`. -/// -/// ``` -/// use std::ops::BitAndAssign; -/// -/// #[derive(Debug, PartialEq)] -/// struct BooleanVector(Vec); -/// -/// impl BitAndAssign for BooleanVector { -/// // `rhs` is the "right-hand side" of the expression `a &= b`. -/// fn bitand_assign(&mut self, rhs: Self) { -/// assert_eq!(self.0.len(), rhs.0.len()); -/// *self = Self( -/// self.0 -/// .iter() -/// .zip(rhs.0.iter()) -/// .map(|(x, y)| *x & *y) -/// .collect() -/// ); -/// } -/// } -/// -/// let mut bv = BooleanVector(vec![true, true, false, false]); -/// bv &= BooleanVector(vec![true, false, true, false]); -/// let expected = BooleanVector(vec![true, false, false, false]); -/// assert_eq!(bv, expected); -/// ``` -#[lang = "bitand_assign"] -#[doc(alias = "&=")] -#[stable(feature = "op_assign_traits", since = "1.8.0")] -#[diagnostic::on_unimplemented( - message = "no implementation for `{Self} &= {Rhs}`", - label = "no implementation for `{Self} &= {Rhs}`" -)] -pub trait BitAndAssign { - /// Performs the `&=` operation. - /// - /// # Examples - /// - /// ``` - /// let mut x = true; - /// x &= false; - /// assert_eq!(x, false); - /// - /// let mut x = true; - /// x &= true; - /// assert_eq!(x, true); - /// - /// let mut x: u8 = 5; - /// x &= 1; - /// assert_eq!(x, 1); - /// - /// let mut x: u8 = 5; - /// x &= 2; - /// assert_eq!(x, 0); - /// ``` - #[stable(feature = "op_assign_traits", since = "1.8.0")] - fn bitand_assign(&mut self, rhs: Rhs); -} - -macro_rules! bitand_assign_impl { - ($($t:ty)+) => ($( - #[stable(feature = "op_assign_traits", since = "1.8.0")] - impl BitAndAssign for $t { - #[inline] - fn bitand_assign(&mut self, other: $t) { *self &= other } - } - - forward_ref_op_assign! { impl BitAndAssign, bitand_assign for $t, $t } - )+) -} - -bitand_assign_impl! { bool usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 } - -/// The bitwise OR assignment operator `|=`. -/// -/// # Examples -/// -/// ``` -/// use std::ops::BitOrAssign; -/// -/// #[derive(Debug, PartialEq)] -/// struct PersonalPreferences { -/// likes_cats: bool, -/// likes_dogs: bool, -/// } -/// -/// impl BitOrAssign for PersonalPreferences { -/// fn bitor_assign(&mut self, rhs: Self) { -/// self.likes_cats |= rhs.likes_cats; -/// self.likes_dogs |= rhs.likes_dogs; -/// } -/// } -/// -/// let mut prefs = PersonalPreferences { likes_cats: true, likes_dogs: false }; -/// prefs |= PersonalPreferences { likes_cats: false, likes_dogs: true }; -/// assert_eq!(prefs, PersonalPreferences { likes_cats: true, likes_dogs: true }); -/// ``` -#[lang = "bitor_assign"] -#[doc(alias = "|=")] -#[stable(feature = "op_assign_traits", since = "1.8.0")] -#[diagnostic::on_unimplemented( - message = "no implementation for `{Self} |= {Rhs}`", - label = "no implementation for `{Self} |= {Rhs}`" -)] -pub trait BitOrAssign { - /// Performs the `|=` operation. - /// - /// # Examples - /// - /// ``` - /// let mut x = true; - /// x |= false; - /// assert_eq!(x, true); - /// - /// let mut x = false; - /// x |= false; - /// assert_eq!(x, false); - /// - /// let mut x: u8 = 5; - /// x |= 1; - /// assert_eq!(x, 5); - /// - /// let mut x: u8 = 5; - /// x |= 2; - /// assert_eq!(x, 7); - /// ``` - #[stable(feature = "op_assign_traits", since = "1.8.0")] - fn bitor_assign(&mut self, rhs: Rhs); -} - -macro_rules! bitor_assign_impl { - ($($t:ty)+) => ($( - #[stable(feature = "op_assign_traits", since = "1.8.0")] - impl BitOrAssign for $t { - #[inline] - fn bitor_assign(&mut self, other: $t) { *self |= other } - } - - forward_ref_op_assign! { impl BitOrAssign, bitor_assign for $t, $t } - )+) -} - -bitor_assign_impl! { bool usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 } - -/// The bitwise XOR assignment operator `^=`. -/// -/// # Examples -/// -/// ``` -/// use std::ops::BitXorAssign; -/// -/// #[derive(Debug, PartialEq)] -/// struct Personality { -/// has_soul: bool, -/// likes_knitting: bool, -/// } -/// -/// impl BitXorAssign for Personality { -/// fn bitxor_assign(&mut self, rhs: Self) { -/// self.has_soul ^= rhs.has_soul; -/// self.likes_knitting ^= rhs.likes_knitting; -/// } -/// } -/// -/// let mut personality = Personality { has_soul: false, likes_knitting: true }; -/// personality ^= Personality { has_soul: true, likes_knitting: true }; -/// assert_eq!(personality, Personality { has_soul: true, likes_knitting: false}); -/// ``` -#[lang = "bitxor_assign"] -#[doc(alias = "^=")] -#[stable(feature = "op_assign_traits", since = "1.8.0")] -#[diagnostic::on_unimplemented( - message = "no implementation for `{Self} ^= {Rhs}`", - label = "no implementation for `{Self} ^= {Rhs}`" -)] -pub trait BitXorAssign { - /// Performs the `^=` operation. - /// - /// # Examples - /// - /// ``` - /// let mut x = true; - /// x ^= false; - /// assert_eq!(x, true); - /// - /// let mut x = true; - /// x ^= true; - /// assert_eq!(x, false); - /// - /// let mut x: u8 = 5; - /// x ^= 1; - /// assert_eq!(x, 4); - /// - /// let mut x: u8 = 5; - /// x ^= 2; - /// assert_eq!(x, 7); - /// ``` - #[stable(feature = "op_assign_traits", since = "1.8.0")] - fn bitxor_assign(&mut self, rhs: Rhs); -} - -macro_rules! bitxor_assign_impl { - ($($t:ty)+) => ($( - #[stable(feature = "op_assign_traits", since = "1.8.0")] - impl BitXorAssign for $t { - #[inline] - fn bitxor_assign(&mut self, other: $t) { *self ^= other } - } - - forward_ref_op_assign! { impl BitXorAssign, bitxor_assign for $t, $t } - )+) -} - -bitxor_assign_impl! { bool usize u8 u16 u32 u64 u128 isize i8 i16 i32 i64 i128 } - -/// The left shift assignment operator `<<=`. -/// -/// # Examples -/// -/// An implementation of `ShlAssign` for a wrapper around `usize`. -/// -/// ``` -/// use std::ops::ShlAssign; -/// -/// #[derive(Debug, PartialEq)] -/// struct Scalar(usize); -/// -/// impl ShlAssign for Scalar { -/// fn shl_assign(&mut self, rhs: usize) { -/// self.0 <<= rhs; -/// } -/// } -/// -/// let mut scalar = Scalar(4); -/// scalar <<= 2; -/// assert_eq!(scalar, Scalar(16)); -/// ``` -#[lang = "shl_assign"] -#[doc(alias = "<<=")] -#[stable(feature = "op_assign_traits", since = "1.8.0")] -#[diagnostic::on_unimplemented( - message = "no implementation for `{Self} <<= {Rhs}`", - label = "no implementation for `{Self} <<= {Rhs}`" -)] -pub trait ShlAssign { - /// Performs the `<<=` operation. - /// - /// # Examples - /// - /// ``` - /// let mut x: u8 = 5; - /// x <<= 1; - /// assert_eq!(x, 10); - /// - /// let mut x: u8 = 1; - /// x <<= 1; - /// assert_eq!(x, 2); - /// ``` - #[stable(feature = "op_assign_traits", since = "1.8.0")] - fn shl_assign(&mut self, rhs: Rhs); -} - -macro_rules! shl_assign_impl { - ($t:ty, $f:ty) => { - #[stable(feature = "op_assign_traits", since = "1.8.0")] - impl ShlAssign<$f> for $t { - #[inline] - #[rustc_inherit_overflow_checks] - fn shl_assign(&mut self, other: $f) { - *self <<= other - } - } - - forward_ref_op_assign! { impl ShlAssign, shl_assign for $t, $f } - }; -} - -macro_rules! shl_assign_impl_all { - ($($t:ty)*) => ($( - shl_assign_impl! { $t, u8 } - shl_assign_impl! { $t, u16 } - shl_assign_impl! { $t, u32 } - shl_assign_impl! { $t, u64 } - shl_assign_impl! { $t, u128 } - shl_assign_impl! { $t, usize } - - shl_assign_impl! { $t, i8 } - shl_assign_impl! { $t, i16 } - shl_assign_impl! { $t, i32 } - shl_assign_impl! { $t, i64 } - shl_assign_impl! { $t, i128 } - shl_assign_impl! { $t, isize } - )*) -} - -shl_assign_impl_all! { u8 u16 u32 u64 u128 usize i8 i16 i32 i64 i128 isize } - -/// The right shift assignment operator `>>=`. -/// -/// # Examples -/// -/// An implementation of `ShrAssign` for a wrapper around `usize`. -/// -/// ``` -/// use std::ops::ShrAssign; -/// -/// #[derive(Debug, PartialEq)] -/// struct Scalar(usize); -/// -/// impl ShrAssign for Scalar { -/// fn shr_assign(&mut self, rhs: usize) { -/// self.0 >>= rhs; -/// } -/// } -/// -/// let mut scalar = Scalar(16); -/// scalar >>= 2; -/// assert_eq!(scalar, Scalar(4)); -/// ``` -#[lang = "shr_assign"] -#[doc(alias = ">>=")] -#[stable(feature = "op_assign_traits", since = "1.8.0")] -#[diagnostic::on_unimplemented( - message = "no implementation for `{Self} >>= {Rhs}`", - label = "no implementation for `{Self} >>= {Rhs}`" -)] -pub trait ShrAssign { - /// Performs the `>>=` operation. - /// - /// # Examples - /// - /// ``` - /// let mut x: u8 = 5; - /// x >>= 1; - /// assert_eq!(x, 2); - /// - /// let mut x: u8 = 2; - /// x >>= 1; - /// assert_eq!(x, 1); - /// ``` - #[stable(feature = "op_assign_traits", since = "1.8.0")] - fn shr_assign(&mut self, rhs: Rhs); -} - -macro_rules! shr_assign_impl { - ($t:ty, $f:ty) => { - #[stable(feature = "op_assign_traits", since = "1.8.0")] - impl ShrAssign<$f> for $t { - #[inline] - #[rustc_inherit_overflow_checks] - fn shr_assign(&mut self, other: $f) { - *self >>= other - } - } - - forward_ref_op_assign! { impl ShrAssign, shr_assign for $t, $f } - }; -} - -macro_rules! shr_assign_impl_all { - ($($t:ty)*) => ($( - shr_assign_impl! { $t, u8 } - shr_assign_impl! { $t, u16 } - shr_assign_impl! { $t, u32 } - shr_assign_impl! { $t, u64 } - shr_assign_impl! { $t, u128 } - shr_assign_impl! { $t, usize } - - shr_assign_impl! { $t, i8 } - shr_assign_impl! { $t, i16 } - shr_assign_impl! { $t, i32 } - shr_assign_impl! { $t, i64 } - shr_assign_impl! { $t, i128 } - shr_assign_impl! { $t, isize } - )*) -} - -shr_assign_impl_all! { u8 u16 u32 u64 u128 usize i8 i16 i32 i64 i128 isize } diff --git a/library/core/src/ops/control_flow.rs b/library/core/src/ops/control_flow.rs deleted file mode 100644 index e10c438ef4300..0000000000000 --- a/library/core/src/ops/control_flow.rs +++ /dev/null @@ -1,258 +0,0 @@ -use crate::{convert, ops}; - -/// Used to tell an operation whether it should exit early or go on as usual. -/// -/// This is used when exposing things (like graph traversals or visitors) where -/// you want the user to be able to choose whether to exit early. -/// Having the enum makes it clearer -- no more wondering "wait, what did `false` -/// mean again?" -- and allows including a value. -/// -/// Similar to [`Option`] and [`Result`], this enum can be used with the `?` operator -/// to return immediately if the [`Break`] variant is present or otherwise continue normally -/// with the value inside the [`Continue`] variant. -/// -/// # Examples -/// -/// Early-exiting from [`Iterator::try_for_each`]: -/// ``` -/// use std::ops::ControlFlow; -/// -/// let r = (2..100).try_for_each(|x| { -/// if 403 % x == 0 { -/// return ControlFlow::Break(x) -/// } -/// -/// ControlFlow::Continue(()) -/// }); -/// assert_eq!(r, ControlFlow::Break(13)); -/// ``` -/// -/// A basic tree traversal: -/// ``` -/// use std::ops::ControlFlow; -/// -/// pub struct TreeNode { -/// value: T, -/// left: Option>>, -/// right: Option>>, -/// } -/// -/// impl TreeNode { -/// pub fn traverse_inorder(&self, f: &mut impl FnMut(&T) -> ControlFlow) -> ControlFlow { -/// if let Some(left) = &self.left { -/// left.traverse_inorder(f)?; -/// } -/// f(&self.value)?; -/// if let Some(right) = &self.right { -/// right.traverse_inorder(f)?; -/// } -/// ControlFlow::Continue(()) -/// } -/// fn leaf(value: T) -> Option>> { -/// Some(Box::new(Self { value, left: None, right: None })) -/// } -/// } -/// -/// let node = TreeNode { -/// value: 0, -/// left: TreeNode::leaf(1), -/// right: Some(Box::new(TreeNode { -/// value: -1, -/// left: TreeNode::leaf(5), -/// right: TreeNode::leaf(2), -/// })) -/// }; -/// let mut sum = 0; -/// -/// let res = node.traverse_inorder(&mut |val| { -/// if *val < 0 { -/// ControlFlow::Break(*val) -/// } else { -/// sum += *val; -/// ControlFlow::Continue(()) -/// } -/// }); -/// assert_eq!(res, ControlFlow::Break(-1)); -/// assert_eq!(sum, 6); -/// ``` -/// -/// [`Break`]: ControlFlow::Break -/// [`Continue`]: ControlFlow::Continue -#[stable(feature = "control_flow_enum_type", since = "1.55.0")] -// ControlFlow should not implement PartialOrd or Ord, per RFC 3058: -// https://rust-lang.github.io/rfcs/3058-try-trait-v2.html#traits-for-controlflow -#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)] -pub enum ControlFlow { - /// Move on to the next phase of the operation as normal. - #[stable(feature = "control_flow_enum_type", since = "1.55.0")] - #[lang = "Continue"] - Continue(C), - /// Exit the operation without running subsequent phases. - #[stable(feature = "control_flow_enum_type", since = "1.55.0")] - #[lang = "Break"] - Break(B), - // Yes, the order of the variants doesn't match the type parameters. - // They're in this order so that `ControlFlow` <-> `Result` - // is a no-op conversion in the `Try` implementation. -} - -#[unstable(feature = "try_trait_v2", issue = "84277")] -impl ops::Try for ControlFlow { - type Output = C; - type Residual = ControlFlow; - - #[inline] - fn from_output(output: Self::Output) -> Self { - ControlFlow::Continue(output) - } - - #[inline] - fn branch(self) -> ControlFlow { - match self { - ControlFlow::Continue(c) => ControlFlow::Continue(c), - ControlFlow::Break(b) => ControlFlow::Break(ControlFlow::Break(b)), - } - } -} - -#[unstable(feature = "try_trait_v2", issue = "84277")] -impl ops::FromResidual for ControlFlow { - #[inline] - fn from_residual(residual: ControlFlow) -> Self { - match residual { - ControlFlow::Break(b) => ControlFlow::Break(b), - } - } -} - -#[unstable(feature = "try_trait_v2_residual", issue = "91285")] -impl ops::Residual for ControlFlow { - type TryType = ControlFlow; -} - -impl ControlFlow { - /// Returns `true` if this is a `Break` variant. - /// - /// # Examples - /// - /// ``` - /// use std::ops::ControlFlow; - /// - /// assert!(ControlFlow::::Break(3).is_break()); - /// assert!(!ControlFlow::::Continue(3).is_break()); - /// ``` - #[inline] - #[stable(feature = "control_flow_enum_is", since = "1.59.0")] - pub fn is_break(&self) -> bool { - matches!(*self, ControlFlow::Break(_)) - } - - /// Returns `true` if this is a `Continue` variant. - /// - /// # Examples - /// - /// ``` - /// use std::ops::ControlFlow; - /// - /// assert!(!ControlFlow::::Break(3).is_continue()); - /// assert!(ControlFlow::::Continue(3).is_continue()); - /// ``` - #[inline] - #[stable(feature = "control_flow_enum_is", since = "1.59.0")] - pub fn is_continue(&self) -> bool { - matches!(*self, ControlFlow::Continue(_)) - } - - /// Converts the `ControlFlow` into an `Option` which is `Some` if the - /// `ControlFlow` was `Break` and `None` otherwise. - /// - /// # Examples - /// - /// ``` - /// #![feature(control_flow_enum)] - /// use std::ops::ControlFlow; - /// - /// assert_eq!(ControlFlow::::Break(3).break_value(), Some(3)); - /// assert_eq!(ControlFlow::::Continue(3).break_value(), None); - /// ``` - #[inline] - #[unstable(feature = "control_flow_enum", reason = "new API", issue = "75744")] - pub fn break_value(self) -> Option { - match self { - ControlFlow::Continue(..) => None, - ControlFlow::Break(x) => Some(x), - } - } - - /// Maps `ControlFlow` to `ControlFlow` by applying a function - /// to the break value in case it exists. - #[inline] - #[unstable(feature = "control_flow_enum", reason = "new API", issue = "75744")] - pub fn map_break(self, f: F) -> ControlFlow - where - F: FnOnce(B) -> T, - { - match self { - ControlFlow::Continue(x) => ControlFlow::Continue(x), - ControlFlow::Break(x) => ControlFlow::Break(f(x)), - } - } - - /// Converts the `ControlFlow` into an `Option` which is `Some` if the - /// `ControlFlow` was `Continue` and `None` otherwise. - /// - /// # Examples - /// - /// ``` - /// #![feature(control_flow_enum)] - /// use std::ops::ControlFlow; - /// - /// assert_eq!(ControlFlow::::Break(3).continue_value(), None); - /// assert_eq!(ControlFlow::::Continue(3).continue_value(), Some(3)); - /// ``` - #[inline] - #[unstable(feature = "control_flow_enum", reason = "new API", issue = "75744")] - pub fn continue_value(self) -> Option { - match self { - ControlFlow::Continue(x) => Some(x), - ControlFlow::Break(..) => None, - } - } - - /// Maps `ControlFlow` to `ControlFlow` by applying a function - /// to the continue value in case it exists. - #[inline] - #[unstable(feature = "control_flow_enum", reason = "new API", issue = "75744")] - pub fn map_continue(self, f: F) -> ControlFlow - where - F: FnOnce(C) -> T, - { - match self { - ControlFlow::Continue(x) => ControlFlow::Continue(f(x)), - ControlFlow::Break(x) => ControlFlow::Break(x), - } - } -} - -/// These are used only as part of implementing the iterator adapters. -/// They have mediocre names and non-obvious semantics, so aren't -/// currently on a path to potential stabilization. -impl ControlFlow { - /// Create a `ControlFlow` from any type implementing `Try`. - #[inline] - pub(crate) fn from_try(r: R) -> Self { - match R::branch(r) { - ControlFlow::Continue(v) => ControlFlow::Continue(v), - ControlFlow::Break(v) => ControlFlow::Break(R::from_residual(v)), - } - } - - /// Convert a `ControlFlow` into any type implementing `Try`; - #[inline] - pub(crate) fn into_try(self) -> R { - match self { - ControlFlow::Continue(v) => R::from_output(v), - ControlFlow::Break(v) => v, - } - } -} diff --git a/library/core/src/ops/coroutine.rs b/library/core/src/ops/coroutine.rs deleted file mode 100644 index 6a6c5db1ab115..0000000000000 --- a/library/core/src/ops/coroutine.rs +++ /dev/null @@ -1,137 +0,0 @@ -use crate::pin::Pin; - -/// The result of a coroutine resumption. -/// -/// This enum is returned from the `Coroutine::resume` method and indicates the -/// possible return values of a coroutine. Currently this corresponds to either -/// a suspension point (`Yielded`) or a termination point (`Complete`). -#[derive(Clone, Copy, PartialEq, PartialOrd, Eq, Ord, Debug, Hash)] -#[lang = "coroutine_state"] -#[unstable(feature = "coroutine_trait", issue = "43122")] -pub enum CoroutineState { - /// The coroutine suspended with a value. - /// - /// This state indicates that a coroutine has been suspended, and typically - /// corresponds to a `yield` statement. The value provided in this variant - /// corresponds to the expression passed to `yield` and allows coroutines to - /// provide a value each time they yield. - Yielded(Y), - - /// The coroutine completed with a return value. - /// - /// This state indicates that a coroutine has finished execution with the - /// provided value. Once a coroutine has returned `Complete` it is - /// considered a programmer error to call `resume` again. - Complete(R), -} - -/// The trait implemented by builtin coroutine types. -/// -/// Coroutines are currently an -/// experimental language feature in Rust. Added in [RFC 2033] coroutines are -/// currently intended to primarily provide a building block for async/await -/// syntax but will likely extend to also providing an ergonomic definition for -/// iterators and other primitives. -/// -/// The syntax and semantics for coroutines is unstable and will require a -/// further RFC for stabilization. At this time, though, the syntax is -/// closure-like: -/// -/// ```rust -/// #![feature(coroutines)] -/// #![feature(coroutine_trait)] -/// #![feature(stmt_expr_attributes)] -/// -/// use std::ops::{Coroutine, CoroutineState}; -/// use std::pin::Pin; -/// -/// fn main() { -/// let mut coroutine = #[coroutine] || { -/// yield 1; -/// "foo" -/// }; -/// -/// match Pin::new(&mut coroutine).resume(()) { -/// CoroutineState::Yielded(1) => {} -/// _ => panic!("unexpected return from resume"), -/// } -/// match Pin::new(&mut coroutine).resume(()) { -/// CoroutineState::Complete("foo") => {} -/// _ => panic!("unexpected return from resume"), -/// } -/// } -/// ``` -/// -/// More documentation of coroutines can be found in the [unstable book]. -/// -/// [RFC 2033]: https://github.com/rust-lang/rfcs/pull/2033 -/// [unstable book]: ../../unstable-book/language-features/coroutines.html -#[lang = "coroutine"] -#[unstable(feature = "coroutine_trait", issue = "43122")] -#[fundamental] -pub trait Coroutine { - /// The type of value this coroutine yields. - /// - /// This associated type corresponds to the `yield` expression and the - /// values which are allowed to be returned each time a coroutine yields. - /// For example an iterator-as-a-coroutine would likely have this type as - /// `T`, the type being iterated over. - type Yield; - - /// The type of value this coroutine returns. - /// - /// This corresponds to the type returned from a coroutine either with a - /// `return` statement or implicitly as the last expression of a coroutine - /// literal. For example futures would use this as `Result` as it - /// represents a completed future. - type Return; - - /// Resumes the execution of this coroutine. - /// - /// This function will resume execution of the coroutine or start execution - /// if it hasn't already. This call will return back into the coroutine's - /// last suspension point, resuming execution from the latest `yield`. The - /// coroutine will continue executing until it either yields or returns, at - /// which point this function will return. - /// - /// # Return value - /// - /// The `CoroutineState` enum returned from this function indicates what - /// state the coroutine is in upon returning. If the `Yielded` variant is - /// returned then the coroutine has reached a suspension point and a value - /// has been yielded out. Coroutines in this state are available for - /// resumption at a later point. - /// - /// If `Complete` is returned then the coroutine has completely finished - /// with the value provided. It is invalid for the coroutine to be resumed - /// again. - /// - /// # Panics - /// - /// This function may panic if it is called after the `Complete` variant has - /// been returned previously. While coroutine literals in the language are - /// guaranteed to panic on resuming after `Complete`, this is not guaranteed - /// for all implementations of the `Coroutine` trait. - #[lang = "coroutine_resume"] - fn resume(self: Pin<&mut Self>, arg: R) -> CoroutineState; -} - -#[unstable(feature = "coroutine_trait", issue = "43122")] -impl, R> Coroutine for Pin<&mut G> { - type Yield = G::Yield; - type Return = G::Return; - - fn resume(mut self: Pin<&mut Self>, arg: R) -> CoroutineState { - G::resume((*self).as_mut(), arg) - } -} - -#[unstable(feature = "coroutine_trait", issue = "43122")] -impl + Unpin, R> Coroutine for &mut G { - type Yield = G::Yield; - type Return = G::Return; - - fn resume(mut self: Pin<&mut Self>, arg: R) -> CoroutineState { - G::resume(Pin::new(&mut *self), arg) - } -} diff --git a/library/core/src/ops/deref.rs b/library/core/src/ops/deref.rs deleted file mode 100644 index 9849410d484ca..0000000000000 --- a/library/core/src/ops/deref.rs +++ /dev/null @@ -1,311 +0,0 @@ -/// Used for immutable dereferencing operations, like `*v`. -/// -/// In addition to being used for explicit dereferencing operations with the -/// (unary) `*` operator in immutable contexts, `Deref` is also used implicitly -/// by the compiler in many circumstances. This mechanism is called -/// ["`Deref` coercion"][coercion]. In mutable contexts, [`DerefMut`] is used and -/// mutable deref coercion similarly occurs. -/// -/// **Warning:** Deref coercion is a powerful language feature which has -/// far-reaching implications for every type that implements `Deref`. The -/// compiler will silently insert calls to `Deref::deref`. For this reason, one -/// should be careful about implementing `Deref` and only do so when deref -/// coercion is desirable. See [below][implementing] for advice on when this is -/// typically desirable or undesirable. -/// -/// Types that implement `Deref` or `DerefMut` are often called "smart -/// pointers" and the mechanism of deref coercion has been specifically designed -/// to facilitate the pointer-like behaviour that name suggests. Often, the -/// purpose of a "smart pointer" type is to change the ownership semantics -/// of a contained value (for example, [`Rc`][rc] or [`Cow`][cow]) or the -/// storage semantics of a contained value (for example, [`Box`][box]). -/// -/// # Deref coercion -/// -/// If `T` implements `Deref`, and `v` is a value of type `T`, then: -/// -/// * In immutable contexts, `*v` (where `T` is neither a reference nor a raw -/// pointer) is equivalent to `*Deref::deref(&v)`. -/// * Values of type `&T` are coerced to values of type `&U` -/// * `T` implicitly implements all the methods of the type `U` which take the -/// `&self` receiver. -/// -/// For more details, visit [the chapter in *The Rust Programming Language*][book] -/// as well as the reference sections on [the dereference operator][ref-deref-op], -/// [method resolution], and [type coercions]. -/// -/// # When to implement `Deref` or `DerefMut` -/// -/// The same advice applies to both deref traits. In general, deref traits -/// **should** be implemented if: -/// -/// 1. a value of the type transparently behaves like a value of the target -/// type; -/// 1. the implementation of the deref function is cheap; and -/// 1. users of the type will not be surprised by any deref coercion behaviour. -/// -/// In general, deref traits **should not** be implemented if: -/// -/// 1. the deref implementations could fail unexpectedly; or -/// 1. the type has methods that are likely to collide with methods on the -/// target type; or -/// 1. committing to deref coercion as part of the public API is not desirable. -/// -/// Note that there's a large difference between implementing deref traits -/// generically over many target types, and doing so only for specific target -/// types. -/// -/// Generic implementations, such as for [`Box`][box] (which is generic over -/// every type and dereferences to `T`) should be careful to provide few or no -/// methods, since the target type is unknown and therefore every method could -/// collide with one on the target type, causing confusion for users. -/// `impl Box` has no methods (though several associated functions), -/// partly for this reason. -/// -/// Specific implementations, such as for [`String`][string] (whose `Deref` -/// implementation has `Target = str`) can have many methods, since avoiding -/// collision is much easier. `String` and `str` both have many methods, and -/// `String` additionally behaves as if it has every method of `str` because of -/// deref coercion. The implementing type may also be generic while the -/// implementation is still specific in this sense; for example, [`Vec`][vec] -/// dereferences to `[T]`, so methods of `T` are not applicable. -/// -/// Consider also that deref coercion means that deref traits are a much larger -/// part of a type's public API than any other trait as it is implicitly called -/// by the compiler. Therefore, it is advisable to consider whether this is -/// something you are comfortable supporting as a public API. -/// -/// The [`AsRef`] and [`Borrow`][core::borrow::Borrow] traits have very similar -/// signatures to `Deref`. It may be desirable to implement either or both of -/// these, whether in addition to or rather than deref traits. See their -/// documentation for details. -/// -/// # Fallibility -/// -/// **This trait's method should never unexpectedly fail**. Deref coercion means -/// the compiler will often insert calls to `Deref::deref` implicitly. Failure -/// during dereferencing can be extremely confusing when `Deref` is invoked -/// implicitly. In the majority of uses it should be infallible, though it may -/// be acceptable to panic if the type is misused through programmer error, for -/// example. -/// -/// However, infallibility is not enforced and therefore not guaranteed. -/// As such, `unsafe` code should not rely on infallibility in general for -/// soundness. -/// -/// [book]: ../../book/ch15-02-deref.html -/// [coercion]: #deref-coercion -/// [implementing]: #when-to-implement-deref-or-derefmut -/// [ref-deref-op]: ../../reference/expressions/operator-expr.html#the-dereference-operator -/// [method resolution]: ../../reference/expressions/method-call-expr.html -/// [type coercions]: ../../reference/type-coercions.html -/// [box]: ../../alloc/boxed/struct.Box.html -/// [string]: ../../alloc/string/struct.String.html -/// [vec]: ../../alloc/vec/struct.Vec.html -/// [rc]: ../../alloc/rc/struct.Rc.html -/// [cow]: ../../alloc/borrow/enum.Cow.html -/// -/// # Examples -/// -/// A struct with a single field which is accessible by dereferencing the -/// struct. -/// -/// ``` -/// use std::ops::Deref; -/// -/// struct DerefExample { -/// value: T -/// } -/// -/// impl Deref for DerefExample { -/// type Target = T; -/// -/// fn deref(&self) -> &Self::Target { -/// &self.value -/// } -/// } -/// -/// let x = DerefExample { value: 'a' }; -/// assert_eq!('a', *x); -/// ``` -#[lang = "deref"] -#[doc(alias = "*")] -#[doc(alias = "&*")] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_diagnostic_item = "Deref"] -pub trait Deref { - /// The resulting type after dereferencing. - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_diagnostic_item = "deref_target"] - #[lang = "deref_target"] - type Target: ?Sized; - - /// Dereferences the value. - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_diagnostic_item = "deref_method"] - fn deref(&self) -> &Self::Target; -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Deref for &T { - type Target = T; - - #[rustc_diagnostic_item = "noop_method_deref"] - fn deref(&self) -> &T { - *self - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl !DerefMut for &T {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Deref for &mut T { - type Target = T; - - fn deref(&self) -> &T { - *self - } -} - -/// Used for mutable dereferencing operations, like in `*v = 1;`. -/// -/// In addition to being used for explicit dereferencing operations with the -/// (unary) `*` operator in mutable contexts, `DerefMut` is also used implicitly -/// by the compiler in many circumstances. This mechanism is called -/// ["mutable deref coercion"][coercion]. In immutable contexts, [`Deref`] is used. -/// -/// **Warning:** Deref coercion is a powerful language feature which has -/// far-reaching implications for every type that implements `DerefMut`. The -/// compiler will silently insert calls to `DerefMut::deref_mut`. For this -/// reason, one should be careful about implementing `DerefMut` and only do so -/// when mutable deref coercion is desirable. See [the `Deref` docs][implementing] -/// for advice on when this is typically desirable or undesirable. -/// -/// Types that implement `DerefMut` or `Deref` are often called "smart -/// pointers" and the mechanism of deref coercion has been specifically designed -/// to facilitate the pointer-like behaviour that name suggests. Often, the -/// purpose of a "smart pointer" type is to change the ownership semantics -/// of a contained value (for example, [`Rc`][rc] or [`Cow`][cow]) or the -/// storage semantics of a contained value (for example, [`Box`][box]). -/// -/// # Mutable deref coercion -/// -/// If `T` implements `DerefMut`, and `v` is a value of type `T`, -/// then: -/// -/// * In mutable contexts, `*v` (where `T` is neither a reference nor a raw pointer) -/// is equivalent to `*DerefMut::deref_mut(&mut v)`. -/// * Values of type `&mut T` are coerced to values of type `&mut U` -/// * `T` implicitly implements all the (mutable) methods of the type `U`. -/// -/// For more details, visit [the chapter in *The Rust Programming Language*][book] -/// as well as the reference sections on [the dereference operator][ref-deref-op], -/// [method resolution] and [type coercions]. -/// -/// # Fallibility -/// -/// **This trait's method should never unexpectedly fail**. Deref coercion means -/// the compiler will often insert calls to `DerefMut::deref_mut` implicitly. -/// Failure during dereferencing can be extremely confusing when `DerefMut` is -/// invoked implicitly. In the majority of uses it should be infallible, though -/// it may be acceptable to panic if the type is misused through programmer -/// error, for example. -/// -/// However, infallibility is not enforced and therefore not guaranteed. -/// As such, `unsafe` code should not rely on infallibility in general for -/// soundness. -/// -/// [book]: ../../book/ch15-02-deref.html -/// [coercion]: #mutable-deref-coercion -/// [implementing]: Deref#when-to-implement-deref-or-derefmut -/// [ref-deref-op]: ../../reference/expressions/operator-expr.html#the-dereference-operator -/// [method resolution]: ../../reference/expressions/method-call-expr.html -/// [type coercions]: ../../reference/type-coercions.html -/// [box]: ../../alloc/boxed/struct.Box.html -/// [string]: ../../alloc/string/struct.String.html -/// [rc]: ../../alloc/rc/struct.Rc.html -/// [cow]: ../../alloc/borrow/enum.Cow.html -/// -/// # Examples -/// -/// A struct with a single field which is modifiable by dereferencing the -/// struct. -/// -/// ``` -/// use std::ops::{Deref, DerefMut}; -/// -/// struct DerefMutExample { -/// value: T -/// } -/// -/// impl Deref for DerefMutExample { -/// type Target = T; -/// -/// fn deref(&self) -> &Self::Target { -/// &self.value -/// } -/// } -/// -/// impl DerefMut for DerefMutExample { -/// fn deref_mut(&mut self) -> &mut Self::Target { -/// &mut self.value -/// } -/// } -/// -/// let mut x = DerefMutExample { value: 'a' }; -/// *x = 'b'; -/// assert_eq!('b', x.value); -/// ``` -#[lang = "deref_mut"] -#[doc(alias = "*")] -#[stable(feature = "rust1", since = "1.0.0")] -pub trait DerefMut: Deref { - /// Mutably dereferences the value. - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_diagnostic_item = "deref_mut_method"] - fn deref_mut(&mut self) -> &mut Self::Target; -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DerefMut for &mut T { - fn deref_mut(&mut self) -> &mut T { - *self - } -} - -/// Perma-unstable marker trait. Indicates that the type has a well-behaved [`Deref`] -/// (and, if applicable, [`DerefMut`]) implementation. This is relied on for soundness -/// of deref patterns. -/// -/// FIXME(deref_patterns): The precise semantics are undecided; the rough idea is that -/// successive calls to `deref`/`deref_mut` without intermediate mutation should be -/// idempotent, in the sense that they return the same value as far as pattern-matching -/// is concerned. Calls to `deref`/`deref_mut`` must leave the pointer itself likewise -/// unchanged. -#[unstable(feature = "deref_pure_trait", issue = "87121")] -#[lang = "deref_pure"] -pub unsafe trait DerefPure {} - -#[unstable(feature = "deref_pure_trait", issue = "87121")] -unsafe impl DerefPure for &T {} - -#[unstable(feature = "deref_pure_trait", issue = "87121")] -unsafe impl DerefPure for &mut T {} - -/// Indicates that a struct can be used as a method receiver, without the -/// `arbitrary_self_types` feature. This is implemented by stdlib pointer types like `Box`, -/// `Rc`, `&T`, and `Pin

`. -#[lang = "receiver"] -#[unstable(feature = "receiver_trait", issue = "none")] -#[doc(hidden)] -pub trait Receiver { - // Empty. -} - -#[unstable(feature = "receiver_trait", issue = "none")] -impl Receiver for &T {} - -#[unstable(feature = "receiver_trait", issue = "none")] -impl Receiver for &mut T {} diff --git a/library/core/src/ops/drop.rs b/library/core/src/ops/drop.rs deleted file mode 100644 index 36ae581e3f723..0000000000000 --- a/library/core/src/ops/drop.rs +++ /dev/null @@ -1,247 +0,0 @@ -/// Custom code within the destructor. -/// -/// When a value is no longer needed, Rust will run a "destructor" on that value. -/// The most common way that a value is no longer needed is when it goes out of -/// scope. Destructors may still run in other circumstances, but we're going to -/// focus on scope for the examples here. To learn about some of those other cases, -/// please see [the reference] section on destructors. -/// -/// [the reference]: https://doc.rust-lang.org/reference/destructors.html -/// -/// This destructor consists of two components: -/// - A call to `Drop::drop` for that value, if this special `Drop` trait is implemented for its type. -/// - The automatically generated "drop glue" which recursively calls the destructors -/// of all the fields of this value. -/// -/// As Rust automatically calls the destructors of all contained fields, -/// you don't have to implement `Drop` in most cases. But there are some cases where -/// it is useful, for example for types which directly manage a resource. -/// That resource may be memory, it may be a file descriptor, it may be a network socket. -/// Once a value of that type is no longer going to be used, it should "clean up" its -/// resource by freeing the memory or closing the file or socket. This is -/// the job of a destructor, and therefore the job of `Drop::drop`. -/// -/// ## Examples -/// -/// To see destructors in action, let's take a look at the following program: -/// -/// ```rust -/// struct HasDrop; -/// -/// impl Drop for HasDrop { -/// fn drop(&mut self) { -/// println!("Dropping HasDrop!"); -/// } -/// } -/// -/// struct HasTwoDrops { -/// one: HasDrop, -/// two: HasDrop, -/// } -/// -/// impl Drop for HasTwoDrops { -/// fn drop(&mut self) { -/// println!("Dropping HasTwoDrops!"); -/// } -/// } -/// -/// fn main() { -/// let _x = HasTwoDrops { one: HasDrop, two: HasDrop }; -/// println!("Running!"); -/// } -/// ``` -/// -/// Rust will first call `Drop::drop` for `_x` and then for both `_x.one` and `_x.two`, -/// meaning that running this will print -/// -/// ```text -/// Running! -/// Dropping HasTwoDrops! -/// Dropping HasDrop! -/// Dropping HasDrop! -/// ``` -/// -/// Even if we remove the implementation of `Drop` for `HasTwoDrop`, the destructors of its fields are still called. -/// This would result in -/// -/// ```test -/// Running! -/// Dropping HasDrop! -/// Dropping HasDrop! -/// ``` -/// -/// ## You cannot call `Drop::drop` yourself -/// -/// Because `Drop::drop` is used to clean up a value, it may be dangerous to use this value after -/// the method has been called. As `Drop::drop` does not take ownership of its input, -/// Rust prevents misuse by not allowing you to call `Drop::drop` directly. -/// -/// In other words, if you tried to explicitly call `Drop::drop` in the above example, you'd get a compiler error. -/// -/// If you'd like to explicitly call the destructor of a value, [`mem::drop`] can be used instead. -/// -/// [`mem::drop`]: drop -/// -/// ## Drop order -/// -/// Which of our two `HasDrop` drops first, though? For structs, it's the same -/// order that they're declared: first `one`, then `two`. If you'd like to try -/// this yourself, you can modify `HasDrop` above to contain some data, like an -/// integer, and then use it in the `println!` inside of `Drop`. This behavior is -/// guaranteed by the language. -/// -/// Unlike for structs, local variables are dropped in reverse order: -/// -/// ```rust -/// struct Foo; -/// -/// impl Drop for Foo { -/// fn drop(&mut self) { -/// println!("Dropping Foo!") -/// } -/// } -/// -/// struct Bar; -/// -/// impl Drop for Bar { -/// fn drop(&mut self) { -/// println!("Dropping Bar!") -/// } -/// } -/// -/// fn main() { -/// let _foo = Foo; -/// let _bar = Bar; -/// } -/// ``` -/// -/// This will print -/// -/// ```text -/// Dropping Bar! -/// Dropping Foo! -/// ``` -/// -/// Please see [the reference] for the full rules. -/// -/// [the reference]: https://doc.rust-lang.org/reference/destructors.html -/// -/// ## `Copy` and `Drop` are exclusive -/// -/// You cannot implement both [`Copy`] and `Drop` on the same type. Types that -/// are `Copy` get implicitly duplicated by the compiler, making it very -/// hard to predict when, and how often destructors will be executed. As such, -/// these types cannot have destructors. -/// -/// ## Drop check -/// -/// Dropping interacts with the borrow checker in subtle ways: when a type `T` is being implicitly -/// dropped as some variable of this type goes out of scope, the borrow checker needs to ensure that -/// calling `T`'s destructor at this moment is safe. In particular, it also needs to be safe to -/// recursively drop all the fields of `T`. For example, it is crucial that code like the following -/// is being rejected: -/// -/// ```compile_fail,E0597 -/// use std::cell::Cell; -/// -/// struct S<'a>(Cell>>, Box); -/// impl Drop for S<'_> { -/// fn drop(&mut self) { -/// if let Some(r) = self.0.get() { -/// // Print the contents of the `Box` in `r`. -/// println!("{}", r.1); -/// } -/// } -/// } -/// -/// fn main() { -/// // Set up two `S` that point to each other. -/// let s1 = S(Cell::new(None), Box::new(42)); -/// let s2 = S(Cell::new(Some(&s1)), Box::new(42)); -/// s1.0.set(Some(&s2)); -/// // Now they both get dropped. But whichever is the 2nd one -/// // to be dropped will access the `Box` in the first one, -/// // which is a use-after-free! -/// } -/// ``` -/// -/// The Nomicon discusses the need for [drop check in more detail][drop check]. -/// -/// To reject such code, the "drop check" analysis determines which types and lifetimes need to -/// still be live when `T` gets dropped. The exact details of this analysis are not yet -/// stably guaranteed and **subject to change**. Currently, the analysis works as follows: -/// - If `T` has no drop glue, then trivially nothing is required to be live. This is the case if -/// neither `T` nor any of its (recursive) fields have a destructor (`impl Drop`). [`PhantomData`] -/// and [`ManuallyDrop`] are considered to never have a destructor, no matter their field type. -/// - If `T` has drop glue, then, for all types `U` that are *owned* by any field of `T`, -/// recursively add the types and lifetimes that need to be live when `U` gets dropped. The set of -/// owned types is determined by recursively traversing `T`: -/// - Recursively descend through `PhantomData`, `Box`, tuples, and arrays (including arrays of -/// length 0). -/// - Stop at reference and raw pointer types as well as function pointers and function items; -/// they do not own anything. -/// - Stop at non-composite types (type parameters that remain generic in the current context and -/// base types such as integers and `bool`); these types are owned. -/// - When hitting an ADT with `impl Drop`, stop there; this type is owned. -/// - When hitting an ADT without `impl Drop`, recursively descend to its fields. (For an `enum`, -/// consider all fields of all variants.) -/// - Furthermore, if `T` implements `Drop`, then all generic (lifetime and type) parameters of `T` -/// must be live. -/// -/// In the above example, the last clause implies that `'a` must be live when `S<'a>` is dropped, -/// and hence the example is rejected. If we remove the `impl Drop`, the liveness requirement -/// disappears and the example is accepted. -/// -/// There exists an unstable way for a type to opt-out of the last clause; this is called "drop -/// check eyepatch" or `may_dangle`. For more details on this nightly-only feature, see the -/// [discussion in the Nomicon][nomicon]. -/// -/// [`ManuallyDrop`]: crate::mem::ManuallyDrop -/// [`PhantomData`]: crate::marker::PhantomData -/// [drop check]: ../../nomicon/dropck.html -/// [nomicon]: ../../nomicon/phantom-data.html#an-exception-the-special-case-of-the-standard-library-and-its-unstable-may_dangle -#[lang = "drop"] -#[stable(feature = "rust1", since = "1.0.0")] -// FIXME(effects) #[const_trait] -pub trait Drop { - /// Executes the destructor for this type. - /// - /// This method is called implicitly when the value goes out of scope, - /// and cannot be called explicitly (this is compiler error [E0040]). - /// However, the [`mem::drop`] function in the prelude can be - /// used to call the argument's `Drop` implementation. - /// - /// When this method has been called, `self` has not yet been deallocated. - /// That only happens after the method is over. - /// If this wasn't the case, `self` would be a dangling reference. - /// - /// # Panics - /// - /// Implementations should generally avoid [`panic!`]ing, because `drop()` may itself be called - /// during unwinding due to a panic, and if the `drop()` panics in that situation (a “double - /// panic”), this will likely abort the program. It is possible to check [`panicking()`] first, - /// which may be desirable for a `Drop` implementation that is reporting a bug of the kind - /// “you didn't finish using this before it was dropped”; but most types should simply clean up - /// their owned allocations or other resources and return normally from `drop()`, regardless of - /// what state they are in. - /// - /// Note that even if this panics, the value is considered to be dropped; - /// you must not cause `drop` to be called again. This is normally automatically - /// handled by the compiler, but when using unsafe code, can sometimes occur - /// unintentionally, particularly when using [`ptr::drop_in_place`]. - /// - /// [E0040]: ../../error_codes/E0040.html - /// [`panic!`]: crate::panic! - /// [`panicking()`]: ../../std/thread/fn.panicking.html - /// [`mem::drop`]: drop - /// [`ptr::drop_in_place`]: crate::ptr::drop_in_place - #[stable(feature = "rust1", since = "1.0.0")] - fn drop(&mut self); -} - -/// Fallback function to call surface level `Drop::drop` function -#[allow(drop_bounds)] -#[lang = "fallback_surface_drop"] -pub(crate) fn fallback_surface_drop(x: &mut T) { - ::drop(x) -} diff --git a/library/core/src/ops/function.rs b/library/core/src/ops/function.rs deleted file mode 100644 index 3a3d3fcf1da64..0000000000000 --- a/library/core/src/ops/function.rs +++ /dev/null @@ -1,308 +0,0 @@ -use crate::marker::Tuple; - -/// The version of the call operator that takes an immutable receiver. -/// -/// Instances of `Fn` can be called repeatedly without mutating state. -/// -/// *This trait (`Fn`) is not to be confused with [function pointers] -/// (`fn`).* -/// -/// `Fn` is implemented automatically by closures which only take immutable -/// references to captured variables or don't capture anything at all, as well -/// as (safe) [function pointers] (with some caveats, see their documentation -/// for more details). Additionally, for any type `F` that implements `Fn`, `&F` -/// implements `Fn`, too. -/// -/// Since both [`FnMut`] and [`FnOnce`] are supertraits of `Fn`, any -/// instance of `Fn` can be used as a parameter where a [`FnMut`] or [`FnOnce`] -/// is expected. -/// -/// Use `Fn` as a bound when you want to accept a parameter of function-like -/// type and need to call it repeatedly and without mutating state (e.g., when -/// calling it concurrently). If you do not need such strict requirements, use -/// [`FnMut`] or [`FnOnce`] as bounds. -/// -/// See the [chapter on closures in *The Rust Programming Language*][book] for -/// some more information on this topic. -/// -/// Also of note is the special syntax for `Fn` traits (e.g. -/// `Fn(usize, bool) -> usize`). Those interested in the technical details of -/// this can refer to [the relevant section in the *Rustonomicon*][nomicon]. -/// -/// [book]: ../../book/ch13-01-closures.html -/// [function pointers]: fn -/// [nomicon]: ../../nomicon/hrtb.html -/// -/// # Examples -/// -/// ## Calling a closure -/// -/// ``` -/// let square = |x| x * x; -/// assert_eq!(square(5), 25); -/// ``` -/// -/// ## Using a `Fn` parameter -/// -/// ``` -/// fn call_with_one(func: F) -> usize -/// where F: Fn(usize) -> usize { -/// func(1) -/// } -/// -/// let double = |x| x * 2; -/// assert_eq!(call_with_one(double), 2); -/// ``` -#[lang = "fn"] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_paren_sugar] -#[rustc_on_unimplemented( - on( - Args = "()", - note = "wrap the `{Self}` in a closure with no arguments: `|| {{ /* code */ }}`" - ), - on( - _Self = "unsafe fn", - note = "unsafe function cannot be called generically without an unsafe block", - // SAFETY: tidy is not smart enough to tell that the below unsafe block is a string - label = "call the function in a closure: `|| unsafe {{ /* code */ }}`" - ), - message = "expected a `{Trait}` closure, found `{Self}`", - label = "expected an `{Trait}` closure, found `{Self}`" -)] -#[fundamental] // so that regex can rely that `&str: !FnMut` -#[must_use = "closures are lazy and do nothing unless called"] -// FIXME(effects) #[const_trait] -pub trait Fn: FnMut { - /// Performs the call operation. - #[unstable(feature = "fn_traits", issue = "29625")] - extern "rust-call" fn call(&self, args: Args) -> Self::Output; -} - -/// The version of the call operator that takes a mutable receiver. -/// -/// Instances of `FnMut` can be called repeatedly and may mutate state. -/// -/// `FnMut` is implemented automatically by closures which take mutable -/// references to captured variables, as well as all types that implement -/// [`Fn`], e.g., (safe) [function pointers] (since `FnMut` is a supertrait of -/// [`Fn`]). Additionally, for any type `F` that implements `FnMut`, `&mut F` -/// implements `FnMut`, too. -/// -/// Since [`FnOnce`] is a supertrait of `FnMut`, any instance of `FnMut` can be -/// used where a [`FnOnce`] is expected, and since [`Fn`] is a subtrait of -/// `FnMut`, any instance of [`Fn`] can be used where `FnMut` is expected. -/// -/// Use `FnMut` as a bound when you want to accept a parameter of function-like -/// type and need to call it repeatedly, while allowing it to mutate state. -/// If you don't want the parameter to mutate state, use [`Fn`] as a -/// bound; if you don't need to call it repeatedly, use [`FnOnce`]. -/// -/// See the [chapter on closures in *The Rust Programming Language*][book] for -/// some more information on this topic. -/// -/// Also of note is the special syntax for `Fn` traits (e.g. -/// `Fn(usize, bool) -> usize`). Those interested in the technical details of -/// this can refer to [the relevant section in the *Rustonomicon*][nomicon]. -/// -/// [book]: ../../book/ch13-01-closures.html -/// [function pointers]: fn -/// [nomicon]: ../../nomicon/hrtb.html -/// -/// # Examples -/// -/// ## Calling a mutably capturing closure -/// -/// ``` -/// let mut x = 5; -/// { -/// let mut square_x = || x *= x; -/// square_x(); -/// } -/// assert_eq!(x, 25); -/// ``` -/// -/// ## Using a `FnMut` parameter -/// -/// ``` -/// fn do_twice(mut func: F) -/// where F: FnMut() -/// { -/// func(); -/// func(); -/// } -/// -/// let mut x: usize = 1; -/// { -/// let add_two_to_x = || x += 2; -/// do_twice(add_two_to_x); -/// } -/// -/// assert_eq!(x, 5); -/// ``` -#[lang = "fn_mut"] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_paren_sugar] -#[rustc_on_unimplemented( - on( - Args = "()", - note = "wrap the `{Self}` in a closure with no arguments: `|| {{ /* code */ }}`" - ), - on( - _Self = "unsafe fn", - note = "unsafe function cannot be called generically without an unsafe block", - // SAFETY: tidy is not smart enough to tell that the below unsafe block is a string - label = "call the function in a closure: `|| unsafe {{ /* code */ }}`" - ), - message = "expected a `{Trait}` closure, found `{Self}`", - label = "expected an `{Trait}` closure, found `{Self}`" -)] -#[fundamental] // so that regex can rely that `&str: !FnMut` -#[must_use = "closures are lazy and do nothing unless called"] -// FIXME(effects) #[const_trait] -pub trait FnMut: FnOnce { - /// Performs the call operation. - #[unstable(feature = "fn_traits", issue = "29625")] - extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output; -} - -/// The version of the call operator that takes a by-value receiver. -/// -/// Instances of `FnOnce` can be called, but might not be callable multiple -/// times. Because of this, if the only thing known about a type is that it -/// implements `FnOnce`, it can only be called once. -/// -/// `FnOnce` is implemented automatically by closures that might consume captured -/// variables, as well as all types that implement [`FnMut`], e.g., (safe) -/// [function pointers] (since `FnOnce` is a supertrait of [`FnMut`]). -/// -/// Since both [`Fn`] and [`FnMut`] are subtraits of `FnOnce`, any instance of -/// [`Fn`] or [`FnMut`] can be used where a `FnOnce` is expected. -/// -/// Use `FnOnce` as a bound when you want to accept a parameter of function-like -/// type and only need to call it once. If you need to call the parameter -/// repeatedly, use [`FnMut`] as a bound; if you also need it to not mutate -/// state, use [`Fn`]. -/// -/// See the [chapter on closures in *The Rust Programming Language*][book] for -/// some more information on this topic. -/// -/// Also of note is the special syntax for `Fn` traits (e.g. -/// `Fn(usize, bool) -> usize`). Those interested in the technical details of -/// this can refer to [the relevant section in the *Rustonomicon*][nomicon]. -/// -/// [book]: ../../book/ch13-01-closures.html -/// [function pointers]: fn -/// [nomicon]: ../../nomicon/hrtb.html -/// -/// # Examples -/// -/// ## Using a `FnOnce` parameter -/// -/// ``` -/// fn consume_with_relish(func: F) -/// where F: FnOnce() -> String -/// { -/// // `func` consumes its captured variables, so it cannot be run more -/// // than once. -/// println!("Consumed: {}", func()); -/// -/// println!("Delicious!"); -/// -/// // Attempting to invoke `func()` again will throw a `use of moved -/// // value` error for `func`. -/// } -/// -/// let x = String::from("x"); -/// let consume_and_return_x = move || x; -/// consume_with_relish(consume_and_return_x); -/// -/// // `consume_and_return_x` can no longer be invoked at this point -/// ``` -#[lang = "fn_once"] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_paren_sugar] -#[rustc_on_unimplemented( - on( - Args = "()", - note = "wrap the `{Self}` in a closure with no arguments: `|| {{ /* code */ }}`" - ), - on( - _Self = "unsafe fn", - note = "unsafe function cannot be called generically without an unsafe block", - // SAFETY: tidy is not smart enough to tell that the below unsafe block is a string - label = "call the function in a closure: `|| unsafe {{ /* code */ }}`" - ), - message = "expected a `{Trait}` closure, found `{Self}`", - label = "expected an `{Trait}` closure, found `{Self}`" -)] -#[fundamental] // so that regex can rely that `&str: !FnMut` -#[must_use = "closures are lazy and do nothing unless called"] -// FIXME(effects) #[const_trait] -pub trait FnOnce { - /// The returned type after the call operator is used. - #[lang = "fn_once_output"] - #[stable(feature = "fn_once_output", since = "1.12.0")] - type Output; - - /// Performs the call operation. - #[unstable(feature = "fn_traits", issue = "29625")] - extern "rust-call" fn call_once(self, args: Args) -> Self::Output; -} - -mod impls { - use crate::marker::Tuple; - - #[stable(feature = "rust1", since = "1.0.0")] - impl Fn for &F - where - F: Fn, - { - extern "rust-call" fn call(&self, args: A) -> F::Output { - (**self).call(args) - } - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl FnMut for &F - where - F: Fn, - { - extern "rust-call" fn call_mut(&mut self, args: A) -> F::Output { - (**self).call(args) - } - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl FnOnce for &F - where - F: Fn, - { - type Output = F::Output; - - extern "rust-call" fn call_once(self, args: A) -> F::Output { - (*self).call(args) - } - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl FnMut for &mut F - where - F: FnMut, - { - extern "rust-call" fn call_mut(&mut self, args: A) -> F::Output { - (*self).call_mut(args) - } - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl FnOnce for &mut F - where - F: FnMut, - { - type Output = F::Output; - extern "rust-call" fn call_once(self, args: A) -> F::Output { - (*self).call_mut(args) - } - } -} diff --git a/library/core/src/ops/index.rs b/library/core/src/ops/index.rs deleted file mode 100644 index 37d9a28fb99c0..0000000000000 --- a/library/core/src/ops/index.rs +++ /dev/null @@ -1,176 +0,0 @@ -/// Used for indexing operations (`container[index]`) in immutable contexts. -/// -/// `container[index]` is actually syntactic sugar for `*container.index(index)`, -/// but only when used as an immutable value. If a mutable value is requested, -/// [`IndexMut`] is used instead. This allows nice things such as -/// `let value = v[index]` if the type of `value` implements [`Copy`]. -/// -/// # Examples -/// -/// The following example implements `Index` on a read-only `NucleotideCount` -/// container, enabling individual counts to be retrieved with index syntax. -/// -/// ``` -/// use std::ops::Index; -/// -/// enum Nucleotide { -/// A, -/// C, -/// G, -/// T, -/// } -/// -/// struct NucleotideCount { -/// a: usize, -/// c: usize, -/// g: usize, -/// t: usize, -/// } -/// -/// impl Index for NucleotideCount { -/// type Output = usize; -/// -/// fn index(&self, nucleotide: Nucleotide) -> &Self::Output { -/// match nucleotide { -/// Nucleotide::A => &self.a, -/// Nucleotide::C => &self.c, -/// Nucleotide::G => &self.g, -/// Nucleotide::T => &self.t, -/// } -/// } -/// } -/// -/// let nucleotide_count = NucleotideCount {a: 14, c: 9, g: 10, t: 12}; -/// assert_eq!(nucleotide_count[Nucleotide::A], 14); -/// assert_eq!(nucleotide_count[Nucleotide::C], 9); -/// assert_eq!(nucleotide_count[Nucleotide::G], 10); -/// assert_eq!(nucleotide_count[Nucleotide::T], 12); -/// ``` -#[lang = "index"] -#[diagnostic::on_unimplemented( - message = "the type `{Self}` cannot be indexed by `{Idx}`", - label = "`{Self}` cannot be indexed by `{Idx}`" -)] -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(alias = "]")] -#[doc(alias = "[")] -#[doc(alias = "[]")] -pub trait Index { - /// The returned type after indexing. - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_diagnostic_item = "IndexOutput"] - type Output: ?Sized; - - /// Performs the indexing (`container[index]`) operation. - /// - /// # Panics - /// - /// May panic if the index is out of bounds. - #[stable(feature = "rust1", since = "1.0.0")] - #[track_caller] - fn index(&self, index: Idx) -> &Self::Output; -} - -/// Used for indexing operations (`container[index]`) in mutable contexts. -/// -/// `container[index]` is actually syntactic sugar for -/// `*container.index_mut(index)`, but only when used as a mutable value. If -/// an immutable value is requested, the [`Index`] trait is used instead. This -/// allows nice things such as `v[index] = value`. -/// -/// # Examples -/// -/// A very simple implementation of a `Balance` struct that has two sides, where -/// each can be indexed mutably and immutably. -/// -/// ``` -/// use std::ops::{Index, IndexMut}; -/// -/// #[derive(Debug)] -/// enum Side { -/// Left, -/// Right, -/// } -/// -/// #[derive(Debug, PartialEq)] -/// enum Weight { -/// Kilogram(f32), -/// Pound(f32), -/// } -/// -/// struct Balance { -/// pub left: Weight, -/// pub right: Weight, -/// } -/// -/// impl Index for Balance { -/// type Output = Weight; -/// -/// fn index(&self, index: Side) -> &Self::Output { -/// println!("Accessing {index:?}-side of balance immutably"); -/// match index { -/// Side::Left => &self.left, -/// Side::Right => &self.right, -/// } -/// } -/// } -/// -/// impl IndexMut for Balance { -/// fn index_mut(&mut self, index: Side) -> &mut Self::Output { -/// println!("Accessing {index:?}-side of balance mutably"); -/// match index { -/// Side::Left => &mut self.left, -/// Side::Right => &mut self.right, -/// } -/// } -/// } -/// -/// let mut balance = Balance { -/// right: Weight::Kilogram(2.5), -/// left: Weight::Pound(1.5), -/// }; -/// -/// // In this case, `balance[Side::Right]` is sugar for -/// // `*balance.index(Side::Right)`, since we are only *reading* -/// // `balance[Side::Right]`, not writing it. -/// assert_eq!(balance[Side::Right], Weight::Kilogram(2.5)); -/// -/// // However, in this case `balance[Side::Left]` is sugar for -/// // `*balance.index_mut(Side::Left)`, since we are writing -/// // `balance[Side::Left]`. -/// balance[Side::Left] = Weight::Kilogram(3.0); -/// ``` -#[lang = "index_mut"] -#[rustc_on_unimplemented( - on( - _Self = "&str", - note = "you can use `.chars().nth()` or `.bytes().nth()` -see chapter in The Book " - ), - on( - _Self = "str", - note = "you can use `.chars().nth()` or `.bytes().nth()` -see chapter in The Book " - ), - on( - _Self = "alloc::string::String", - note = "you can use `.chars().nth()` or `.bytes().nth()` -see chapter in The Book " - ), - message = "the type `{Self}` cannot be mutably indexed by `{Idx}`", - label = "`{Self}` cannot be mutably indexed by `{Idx}`" -)] -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(alias = "[")] -#[doc(alias = "]")] -#[doc(alias = "[]")] -pub trait IndexMut: Index { - /// Performs the mutable indexing (`container[index]`) operation. - /// - /// # Panics - /// - /// May panic if the index is out of bounds. - #[stable(feature = "rust1", since = "1.0.0")] - #[track_caller] - fn index_mut(&mut self, index: Idx) -> &mut Self::Output; -} diff --git a/library/core/src/ops/index_range.rs b/library/core/src/ops/index_range.rs deleted file mode 100644 index 65bda9177c7be..0000000000000 --- a/library/core/src/ops/index_range.rs +++ /dev/null @@ -1,169 +0,0 @@ -use crate::intrinsics::{unchecked_add, unchecked_sub}; -use crate::iter::{FusedIterator, TrustedLen}; -use crate::num::NonZero; -use crate::ub_checks; - -/// Like a `Range`, but with a safety invariant that `start <= end`. -/// -/// This means that `end - start` cannot overflow, allowing some μoptimizations. -/// -/// (Normal `Range` code needs to handle degenerate ranges like `10..0`, -/// which takes extra checks compared to only handling the canonical form.) -#[derive(Clone, Debug, PartialEq, Eq)] -pub(crate) struct IndexRange { - start: usize, - end: usize, -} - -impl IndexRange { - /// # Safety - /// - `start <= end` - #[inline] - pub const unsafe fn new_unchecked(start: usize, end: usize) -> Self { - ub_checks::assert_unsafe_precondition!( - check_library_ub, - "IndexRange::new_unchecked requires `start <= end`", - (start: usize = start, end: usize = end) => start <= end, - ); - IndexRange { start, end } - } - - #[inline] - pub const fn zero_to(end: usize) -> Self { - IndexRange { start: 0, end } - } - - #[inline] - pub const fn start(&self) -> usize { - self.start - } - - #[inline] - pub const fn end(&self) -> usize { - self.end - } - - #[inline] - pub const fn len(&self) -> usize { - // SAFETY: By invariant, this cannot wrap - unsafe { unchecked_sub(self.end, self.start) } - } - - /// # Safety - /// - Can only be called when `start < end`, aka when `len > 0`. - #[inline] - unsafe fn next_unchecked(&mut self) -> usize { - debug_assert!(self.start < self.end); - - let value = self.start; - // SAFETY: The range isn't empty, so this cannot overflow - self.start = unsafe { unchecked_add(value, 1) }; - value - } - - /// # Safety - /// - Can only be called when `start < end`, aka when `len > 0`. - #[inline] - unsafe fn next_back_unchecked(&mut self) -> usize { - debug_assert!(self.start < self.end); - - // SAFETY: The range isn't empty, so this cannot overflow - let value = unsafe { unchecked_sub(self.end, 1) }; - self.end = value; - value - } - - /// Removes the first `n` items from this range, returning them as an `IndexRange`. - /// If there are fewer than `n`, then the whole range is returned and - /// `self` is left empty. - /// - /// This is designed to help implement `Iterator::advance_by`. - #[inline] - pub fn take_prefix(&mut self, n: usize) -> Self { - let mid = if n <= self.len() { - // SAFETY: We just checked that this will be between start and end, - // and thus the addition cannot overflow. - unsafe { unchecked_add(self.start, n) } - } else { - self.end - }; - let prefix = Self { start: self.start, end: mid }; - self.start = mid; - prefix - } - - /// Removes the last `n` items from this range, returning them as an `IndexRange`. - /// If there are fewer than `n`, then the whole range is returned and - /// `self` is left empty. - /// - /// This is designed to help implement `Iterator::advance_back_by`. - #[inline] - pub fn take_suffix(&mut self, n: usize) -> Self { - let mid = if n <= self.len() { - // SAFETY: We just checked that this will be between start and end, - // and thus the addition cannot overflow. - unsafe { unchecked_sub(self.end, n) } - } else { - self.start - }; - let suffix = Self { start: mid, end: self.end }; - self.end = mid; - suffix - } -} - -impl Iterator for IndexRange { - type Item = usize; - - #[inline] - fn next(&mut self) -> Option { - if self.len() > 0 { - // SAFETY: We just checked that the range is non-empty - unsafe { Some(self.next_unchecked()) } - } else { - None - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let len = self.len(); - (len, Some(len)) - } - - #[inline] - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - let taken = self.take_prefix(n); - NonZero::new(n - taken.len()).map_or(Ok(()), Err) - } -} - -impl DoubleEndedIterator for IndexRange { - #[inline] - fn next_back(&mut self) -> Option { - if self.len() > 0 { - // SAFETY: We just checked that the range is non-empty - unsafe { Some(self.next_back_unchecked()) } - } else { - None - } - } - - #[inline] - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - let taken = self.take_suffix(n); - NonZero::new(n - taken.len()).map_or(Ok(()), Err) - } -} - -impl ExactSizeIterator for IndexRange { - #[inline] - fn len(&self) -> usize { - self.len() - } -} - -// SAFETY: Because we only deal in `usize`, our `len` is always perfect. -unsafe impl TrustedLen for IndexRange {} - -impl FusedIterator for IndexRange {} diff --git a/library/core/src/ops/mod.rs b/library/core/src/ops/mod.rs deleted file mode 100644 index 7bcfaadbe372b..0000000000000 --- a/library/core/src/ops/mod.rs +++ /dev/null @@ -1,220 +0,0 @@ -//! Overloadable operators. -//! -//! Implementing these traits allows you to overload certain operators. -//! -//! Some of these traits are imported by the prelude, so they are available in -//! every Rust program. Only operators backed by traits can be overloaded. For -//! example, the addition operator (`+`) can be overloaded through the [`Add`] -//! trait, but since the assignment operator (`=`) has no backing trait, there -//! is no way of overloading its semantics. Additionally, this module does not -//! provide any mechanism to create new operators. If traitless overloading or -//! custom operators are required, you should look toward macros to extend -//! Rust's syntax. -//! -//! Implementations of operator traits should be unsurprising in their -//! respective contexts, keeping in mind their usual meanings and -//! [operator precedence]. For example, when implementing [`Mul`], the operation -//! should have some resemblance to multiplication (and share expected -//! properties like associativity). -//! -//! Note that the `&&` and `||` operators are currently not supported for -//! overloading. Due to their short circuiting nature, they require a different -//! design from traits for other operators like [`BitAnd`]. Designs for them are -//! under discussion. -//! -//! Many of the operators take their operands by value. In non-generic -//! contexts involving built-in types, this is usually not a problem. -//! However, using these operators in generic code, requires some -//! attention if values have to be reused as opposed to letting the operators -//! consume them. One option is to occasionally use [`clone`]. -//! Another option is to rely on the types involved providing additional -//! operator implementations for references. For example, for a user-defined -//! type `T` which is supposed to support addition, it is probably a good -//! idea to have both `T` and `&T` implement the traits [`Add`][`Add`] and -//! [`Add<&T>`][`Add`] so that generic code can be written without unnecessary -//! cloning. -//! -//! # Examples -//! -//! This example creates a `Point` struct that implements [`Add`] and [`Sub`], -//! and then demonstrates adding and subtracting two `Point`s. -//! -//! ```rust -//! use std::ops::{Add, Sub}; -//! -//! #[derive(Debug, Copy, Clone, PartialEq)] -//! struct Point { -//! x: i32, -//! y: i32, -//! } -//! -//! impl Add for Point { -//! type Output = Self; -//! -//! fn add(self, other: Self) -> Self { -//! Self {x: self.x + other.x, y: self.y + other.y} -//! } -//! } -//! -//! impl Sub for Point { -//! type Output = Self; -//! -//! fn sub(self, other: Self) -> Self { -//! Self {x: self.x - other.x, y: self.y - other.y} -//! } -//! } -//! -//! assert_eq!(Point {x: 3, y: 3}, Point {x: 1, y: 0} + Point {x: 2, y: 3}); -//! assert_eq!(Point {x: -1, y: -3}, Point {x: 1, y: 0} - Point {x: 2, y: 3}); -//! ``` -//! -//! See the documentation for each trait for an example implementation. -//! -//! The [`Fn`], [`FnMut`], and [`FnOnce`] traits are implemented by types that can be -//! invoked like functions. Note that [`Fn`] takes `&self`, [`FnMut`] takes `&mut -//! self` and [`FnOnce`] takes `self`. These correspond to the three kinds of -//! methods that can be invoked on an instance: call-by-reference, -//! call-by-mutable-reference, and call-by-value. The most common use of these -//! traits is to act as bounds to higher-level functions that take functions or -//! closures as arguments. -//! -//! Taking a [`Fn`] as a parameter: -//! -//! ```rust -//! fn call_with_one(func: F) -> usize -//! where F: Fn(usize) -> usize -//! { -//! func(1) -//! } -//! -//! let double = |x| x * 2; -//! assert_eq!(call_with_one(double), 2); -//! ``` -//! -//! Taking a [`FnMut`] as a parameter: -//! -//! ```rust -//! fn do_twice(mut func: F) -//! where F: FnMut() -//! { -//! func(); -//! func(); -//! } -//! -//! let mut x: usize = 1; -//! { -//! let add_two_to_x = || x += 2; -//! do_twice(add_two_to_x); -//! } -//! -//! assert_eq!(x, 5); -//! ``` -//! -//! Taking a [`FnOnce`] as a parameter: -//! -//! ```rust -//! fn consume_with_relish(func: F) -//! where F: FnOnce() -> String -//! { -//! // `func` consumes its captured variables, so it cannot be run more -//! // than once -//! println!("Consumed: {}", func()); -//! -//! println!("Delicious!"); -//! -//! // Attempting to invoke `func()` again will throw a `use of moved -//! // value` error for `func` -//! } -//! -//! let x = String::from("x"); -//! let consume_and_return_x = move || x; -//! consume_with_relish(consume_and_return_x); -//! -//! // `consume_and_return_x` can no longer be invoked at this point -//! ``` -//! -//! [`clone`]: Clone::clone -//! [operator precedence]: ../../reference/expressions.html#expression-precedence - -#![stable(feature = "rust1", since = "1.0.0")] - -mod arith; -mod async_function; -mod bit; -mod control_flow; -mod coroutine; -mod deref; -mod drop; -mod function; -mod index; -mod index_range; -mod range; -mod try_trait; -mod unsize; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::arith::{Add, Div, Mul, Neg, Rem, Sub}; -#[stable(feature = "op_assign_traits", since = "1.8.0")] -pub use self::arith::{AddAssign, DivAssign, MulAssign, RemAssign, SubAssign}; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::bit::{BitAnd, BitOr, BitXor, Not, Shl, Shr}; -#[stable(feature = "op_assign_traits", since = "1.8.0")] -pub use self::bit::{BitAndAssign, BitOrAssign, BitXorAssign, ShlAssign, ShrAssign}; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::deref::{Deref, DerefMut}; - -#[unstable(feature = "deref_pure_trait", issue = "87121")] -pub use self::deref::DerefPure; - -#[unstable(feature = "receiver_trait", issue = "none")] -pub use self::deref::Receiver; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::drop::Drop; - -pub(crate) use self::drop::fallback_surface_drop; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::function::{Fn, FnMut, FnOnce}; - -#[unstable(feature = "async_fn_traits", issue = "none")] -pub use self::async_function::{AsyncFn, AsyncFnMut, AsyncFnOnce}; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::index::{Index, IndexMut}; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::range::{Range, RangeFrom, RangeFull, RangeTo}; - -pub(crate) use self::index_range::IndexRange; - -#[stable(feature = "inclusive_range", since = "1.26.0")] -pub use self::range::{Bound, RangeBounds, RangeInclusive, RangeToInclusive}; - -#[unstable(feature = "one_sided_range", issue = "69780")] -pub use self::range::OneSidedRange; - -#[unstable(feature = "try_trait_v2", issue = "84277")] -pub use self::try_trait::{FromResidual, Try}; - -#[unstable(feature = "try_trait_v2_yeet", issue = "96374")] -pub use self::try_trait::Yeet; - -#[unstable(feature = "try_trait_v2_residual", issue = "91285")] -pub use self::try_trait::Residual; - -pub(crate) use self::try_trait::{ChangeOutputType, NeverShortCircuit}; - -#[unstable(feature = "coroutine_trait", issue = "43122")] -pub use self::coroutine::{Coroutine, CoroutineState}; - -#[unstable(feature = "coerce_unsized", issue = "18598")] -pub use self::unsize::CoerceUnsized; - -#[unstable(feature = "dispatch_from_dyn", issue = "none")] -pub use self::unsize::DispatchFromDyn; - -#[unstable(feature = "control_flow_enum", reason = "new API", issue = "75744")] -pub use self::control_flow::ControlFlow; diff --git a/library/core/src/ops/range.rs b/library/core/src/ops/range.rs deleted file mode 100644 index 727a22e454d3d..0000000000000 --- a/library/core/src/ops/range.rs +++ /dev/null @@ -1,998 +0,0 @@ -use crate::fmt; -use crate::hash::Hash; - -/// An unbounded range (`..`). -/// -/// `RangeFull` is primarily used as a [slicing index], its shorthand is `..`. -/// It cannot serve as an [`Iterator`] because it doesn't have a starting point. -/// -/// # Examples -/// -/// The `..` syntax is a `RangeFull`: -/// -/// ``` -/// assert_eq!(.., std::ops::RangeFull); -/// ``` -/// -/// It does not have an [`IntoIterator`] implementation, so you can't use it in -/// a `for` loop directly. This won't compile: -/// -/// ```compile_fail,E0277 -/// for i in .. { -/// // ... -/// } -/// ``` -/// -/// Used as a [slicing index], `RangeFull` produces the full array as a slice. -/// -/// ``` -/// let arr = [0, 1, 2, 3, 4]; -/// assert_eq!(arr[ .. ], [0, 1, 2, 3, 4]); // This is the `RangeFull` -/// assert_eq!(arr[ .. 3], [0, 1, 2 ]); -/// assert_eq!(arr[ ..=3], [0, 1, 2, 3 ]); -/// assert_eq!(arr[1.. ], [ 1, 2, 3, 4]); -/// assert_eq!(arr[1.. 3], [ 1, 2 ]); -/// assert_eq!(arr[1..=3], [ 1, 2, 3 ]); -/// ``` -/// -/// [slicing index]: crate::slice::SliceIndex -#[lang = "RangeFull"] -#[doc(alias = "..")] -#[derive(Copy, Clone, Default, PartialEq, Eq, Hash)] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct RangeFull; - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for RangeFull { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(fmt, "..") - } -} - -/// A (half-open) range bounded inclusively below and exclusively above -/// (`start..end`). -/// -/// The range `start..end` contains all values with `start <= x < end`. -/// It is empty if `start >= end`. -/// -/// # Examples -/// -/// The `start..end` syntax is a `Range`: -/// -/// ``` -/// assert_eq!((3..5), std::ops::Range { start: 3, end: 5 }); -/// assert_eq!(3 + 4 + 5, (3..6).sum()); -/// ``` -/// -/// ``` -/// let arr = [0, 1, 2, 3, 4]; -/// assert_eq!(arr[ .. ], [0, 1, 2, 3, 4]); -/// assert_eq!(arr[ .. 3], [0, 1, 2 ]); -/// assert_eq!(arr[ ..=3], [0, 1, 2, 3 ]); -/// assert_eq!(arr[1.. ], [ 1, 2, 3, 4]); -/// assert_eq!(arr[1.. 3], [ 1, 2 ]); // This is a `Range` -/// assert_eq!(arr[1..=3], [ 1, 2, 3 ]); -/// ``` -#[lang = "Range"] -#[doc(alias = "..")] -#[derive(Clone, Default, PartialEq, Eq, Hash)] // not Copy -- see #27186 -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Range { - /// The lower bound of the range (inclusive). - #[stable(feature = "rust1", since = "1.0.0")] - pub start: Idx, - /// The upper bound of the range (exclusive). - #[stable(feature = "rust1", since = "1.0.0")] - pub end: Idx, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for Range { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - self.start.fmt(fmt)?; - write!(fmt, "..")?; - self.end.fmt(fmt)?; - Ok(()) - } -} - -impl> Range { - /// Returns `true` if `item` is contained in the range. - /// - /// # Examples - /// - /// ``` - /// assert!(!(3..5).contains(&2)); - /// assert!( (3..5).contains(&3)); - /// assert!( (3..5).contains(&4)); - /// assert!(!(3..5).contains(&5)); - /// - /// assert!(!(3..3).contains(&3)); - /// assert!(!(3..2).contains(&3)); - /// - /// assert!( (0.0..1.0).contains(&0.5)); - /// assert!(!(0.0..1.0).contains(&f32::NAN)); - /// assert!(!(0.0..f32::NAN).contains(&0.5)); - /// assert!(!(f32::NAN..1.0).contains(&0.5)); - /// ``` - #[inline] - #[stable(feature = "range_contains", since = "1.35.0")] - pub fn contains(&self, item: &U) -> bool - where - Idx: PartialOrd, - U: ?Sized + PartialOrd, - { - >::contains(self, item) - } - - /// Returns `true` if the range contains no items. - /// - /// # Examples - /// - /// ``` - /// assert!(!(3..5).is_empty()); - /// assert!( (3..3).is_empty()); - /// assert!( (3..2).is_empty()); - /// ``` - /// - /// The range is empty if either side is incomparable: - /// - /// ``` - /// assert!(!(3.0..5.0).is_empty()); - /// assert!( (3.0..f32::NAN).is_empty()); - /// assert!( (f32::NAN..5.0).is_empty()); - /// ``` - #[inline] - #[stable(feature = "range_is_empty", since = "1.47.0")] - pub fn is_empty(&self) -> bool { - !(self.start < self.end) - } -} - -/// A range only bounded inclusively below (`start..`). -/// -/// The `RangeFrom` `start..` contains all values with `x >= start`. -/// -/// *Note*: Overflow in the [`Iterator`] implementation (when the contained -/// data type reaches its numerical limit) is allowed to panic, wrap, or -/// saturate. This behavior is defined by the implementation of the [`Step`] -/// trait. For primitive integers, this follows the normal rules, and respects -/// the overflow checks profile (panic in debug, wrap in release). Note also -/// that overflow happens earlier than you might assume: the overflow happens -/// in the call to `next` that yields the maximum value, as the range must be -/// set to a state to yield the next value. -/// -/// [`Step`]: crate::iter::Step -/// -/// # Examples -/// -/// The `start..` syntax is a `RangeFrom`: -/// -/// ``` -/// assert_eq!((2..), std::ops::RangeFrom { start: 2 }); -/// assert_eq!(2 + 3 + 4, (2..).take(3).sum()); -/// ``` -/// -/// ``` -/// let arr = [0, 1, 2, 3, 4]; -/// assert_eq!(arr[ .. ], [0, 1, 2, 3, 4]); -/// assert_eq!(arr[ .. 3], [0, 1, 2 ]); -/// assert_eq!(arr[ ..=3], [0, 1, 2, 3 ]); -/// assert_eq!(arr[1.. ], [ 1, 2, 3, 4]); // This is a `RangeFrom` -/// assert_eq!(arr[1.. 3], [ 1, 2 ]); -/// assert_eq!(arr[1..=3], [ 1, 2, 3 ]); -/// ``` -#[lang = "RangeFrom"] -#[doc(alias = "..")] -#[derive(Clone, PartialEq, Eq, Hash)] // not Copy -- see #27186 -#[stable(feature = "rust1", since = "1.0.0")] -pub struct RangeFrom { - /// The lower bound of the range (inclusive). - #[stable(feature = "rust1", since = "1.0.0")] - pub start: Idx, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for RangeFrom { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - self.start.fmt(fmt)?; - write!(fmt, "..")?; - Ok(()) - } -} - -impl> RangeFrom { - /// Returns `true` if `item` is contained in the range. - /// - /// # Examples - /// - /// ``` - /// assert!(!(3..).contains(&2)); - /// assert!( (3..).contains(&3)); - /// assert!( (3..).contains(&1_000_000_000)); - /// - /// assert!( (0.0..).contains(&0.5)); - /// assert!(!(0.0..).contains(&f32::NAN)); - /// assert!(!(f32::NAN..).contains(&0.5)); - /// ``` - #[inline] - #[stable(feature = "range_contains", since = "1.35.0")] - pub fn contains(&self, item: &U) -> bool - where - Idx: PartialOrd, - U: ?Sized + PartialOrd, - { - >::contains(self, item) - } -} - -/// A range only bounded exclusively above (`..end`). -/// -/// The `RangeTo` `..end` contains all values with `x < end`. -/// It cannot serve as an [`Iterator`] because it doesn't have a starting point. -/// -/// # Examples -/// -/// The `..end` syntax is a `RangeTo`: -/// -/// ``` -/// assert_eq!((..5), std::ops::RangeTo { end: 5 }); -/// ``` -/// -/// It does not have an [`IntoIterator`] implementation, so you can't use it in -/// a `for` loop directly. This won't compile: -/// -/// ```compile_fail,E0277 -/// // error[E0277]: the trait bound `std::ops::RangeTo<{integer}>: -/// // std::iter::Iterator` is not satisfied -/// for i in ..5 { -/// // ... -/// } -/// ``` -/// -/// When used as a [slicing index], `RangeTo` produces a slice of all array -/// elements before the index indicated by `end`. -/// -/// ``` -/// let arr = [0, 1, 2, 3, 4]; -/// assert_eq!(arr[ .. ], [0, 1, 2, 3, 4]); -/// assert_eq!(arr[ .. 3], [0, 1, 2 ]); // This is a `RangeTo` -/// assert_eq!(arr[ ..=3], [0, 1, 2, 3 ]); -/// assert_eq!(arr[1.. ], [ 1, 2, 3, 4]); -/// assert_eq!(arr[1.. 3], [ 1, 2 ]); -/// assert_eq!(arr[1..=3], [ 1, 2, 3 ]); -/// ``` -/// -/// [slicing index]: crate::slice::SliceIndex -#[lang = "RangeTo"] -#[doc(alias = "..")] -#[derive(Copy, Clone, PartialEq, Eq, Hash)] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct RangeTo { - /// The upper bound of the range (exclusive). - #[stable(feature = "rust1", since = "1.0.0")] - pub end: Idx, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for RangeTo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(fmt, "..")?; - self.end.fmt(fmt)?; - Ok(()) - } -} - -impl> RangeTo { - /// Returns `true` if `item` is contained in the range. - /// - /// # Examples - /// - /// ``` - /// assert!( (..5).contains(&-1_000_000_000)); - /// assert!( (..5).contains(&4)); - /// assert!(!(..5).contains(&5)); - /// - /// assert!( (..1.0).contains(&0.5)); - /// assert!(!(..1.0).contains(&f32::NAN)); - /// assert!(!(..f32::NAN).contains(&0.5)); - /// ``` - #[inline] - #[stable(feature = "range_contains", since = "1.35.0")] - pub fn contains(&self, item: &U) -> bool - where - Idx: PartialOrd, - U: ?Sized + PartialOrd, - { - >::contains(self, item) - } -} - -/// A range bounded inclusively below and above (`start..=end`). -/// -/// The `RangeInclusive` `start..=end` contains all values with `x >= start` -/// and `x <= end`. It is empty unless `start <= end`. -/// -/// This iterator is [fused], but the specific values of `start` and `end` after -/// iteration has finished are **unspecified** other than that [`.is_empty()`] -/// will return `true` once no more values will be produced. -/// -/// [fused]: crate::iter::FusedIterator -/// [`.is_empty()`]: RangeInclusive::is_empty -/// -/// # Examples -/// -/// The `start..=end` syntax is a `RangeInclusive`: -/// -/// ``` -/// assert_eq!((3..=5), std::ops::RangeInclusive::new(3, 5)); -/// assert_eq!(3 + 4 + 5, (3..=5).sum()); -/// ``` -/// -/// ``` -/// let arr = [0, 1, 2, 3, 4]; -/// assert_eq!(arr[ .. ], [0, 1, 2, 3, 4]); -/// assert_eq!(arr[ .. 3], [0, 1, 2 ]); -/// assert_eq!(arr[ ..=3], [0, 1, 2, 3 ]); -/// assert_eq!(arr[1.. ], [ 1, 2, 3, 4]); -/// assert_eq!(arr[1.. 3], [ 1, 2 ]); -/// assert_eq!(arr[1..=3], [ 1, 2, 3 ]); // This is a `RangeInclusive` -/// ``` -#[lang = "RangeInclusive"] -#[doc(alias = "..=")] -#[derive(Clone, PartialEq, Eq, Hash)] // not Copy -- see #27186 -#[stable(feature = "inclusive_range", since = "1.26.0")] -pub struct RangeInclusive { - // Note that the fields here are not public to allow changing the - // representation in the future; in particular, while we could plausibly - // expose start/end, modifying them without changing (future/current) - // private fields may lead to incorrect behavior, so we don't want to - // support that mode. - pub(crate) start: Idx, - pub(crate) end: Idx, - - // This field is: - // - `false` upon construction - // - `false` when iteration has yielded an element and the iterator is not exhausted - // - `true` when iteration has been used to exhaust the iterator - // - // This is required to support PartialEq and Hash without a PartialOrd bound or specialization. - pub(crate) exhausted: bool, -} - -impl RangeInclusive { - /// Creates a new inclusive range. Equivalent to writing `start..=end`. - /// - /// # Examples - /// - /// ``` - /// use std::ops::RangeInclusive; - /// - /// assert_eq!(3..=5, RangeInclusive::new(3, 5)); - /// ``` - #[lang = "range_inclusive_new"] - #[stable(feature = "inclusive_range_methods", since = "1.27.0")] - #[inline] - #[rustc_promotable] - #[rustc_const_stable(feature = "const_range_new", since = "1.32.0")] - pub const fn new(start: Idx, end: Idx) -> Self { - Self { start, end, exhausted: false } - } - - /// Returns the lower bound of the range (inclusive). - /// - /// When using an inclusive range for iteration, the values of `start()` and - /// [`end()`] are unspecified after the iteration ended. To determine - /// whether the inclusive range is empty, use the [`is_empty()`] method - /// instead of comparing `start() > end()`. - /// - /// Note: the value returned by this method is unspecified after the range - /// has been iterated to exhaustion. - /// - /// [`end()`]: RangeInclusive::end - /// [`is_empty()`]: RangeInclusive::is_empty - /// - /// # Examples - /// - /// ``` - /// assert_eq!((3..=5).start(), &3); - /// ``` - #[stable(feature = "inclusive_range_methods", since = "1.27.0")] - #[rustc_const_stable(feature = "const_inclusive_range_methods", since = "1.32.0")] - #[inline] - pub const fn start(&self) -> &Idx { - &self.start - } - - /// Returns the upper bound of the range (inclusive). - /// - /// When using an inclusive range for iteration, the values of [`start()`] - /// and `end()` are unspecified after the iteration ended. To determine - /// whether the inclusive range is empty, use the [`is_empty()`] method - /// instead of comparing `start() > end()`. - /// - /// Note: the value returned by this method is unspecified after the range - /// has been iterated to exhaustion. - /// - /// [`start()`]: RangeInclusive::start - /// [`is_empty()`]: RangeInclusive::is_empty - /// - /// # Examples - /// - /// ``` - /// assert_eq!((3..=5).end(), &5); - /// ``` - #[stable(feature = "inclusive_range_methods", since = "1.27.0")] - #[rustc_const_stable(feature = "const_inclusive_range_methods", since = "1.32.0")] - #[inline] - pub const fn end(&self) -> &Idx { - &self.end - } - - /// Destructures the `RangeInclusive` into (lower bound, upper (inclusive) bound). - /// - /// Note: the value returned by this method is unspecified after the range - /// has been iterated to exhaustion. - /// - /// # Examples - /// - /// ``` - /// assert_eq!((3..=5).into_inner(), (3, 5)); - /// ``` - #[stable(feature = "inclusive_range_methods", since = "1.27.0")] - #[inline] - #[rustc_const_unstable(feature = "const_range_bounds", issue = "108082")] - pub const fn into_inner(self) -> (Idx, Idx) { - (self.start, self.end) - } -} - -impl RangeInclusive { - /// Converts to an exclusive `Range` for `SliceIndex` implementations. - /// The caller is responsible for dealing with `end == usize::MAX`. - #[inline] - pub(crate) const fn into_slice_range(self) -> Range { - // If we're not exhausted, we want to simply slice `start..end + 1`. - // If we are exhausted, then slicing with `end + 1..end + 1` gives us an - // empty range that is still subject to bounds-checks for that endpoint. - let exclusive_end = self.end + 1; - let start = if self.exhausted { exclusive_end } else { self.start }; - start..exclusive_end - } -} - -#[stable(feature = "inclusive_range", since = "1.26.0")] -impl fmt::Debug for RangeInclusive { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - self.start.fmt(fmt)?; - write!(fmt, "..=")?; - self.end.fmt(fmt)?; - if self.exhausted { - write!(fmt, " (exhausted)")?; - } - Ok(()) - } -} - -impl> RangeInclusive { - /// Returns `true` if `item` is contained in the range. - /// - /// # Examples - /// - /// ``` - /// assert!(!(3..=5).contains(&2)); - /// assert!( (3..=5).contains(&3)); - /// assert!( (3..=5).contains(&4)); - /// assert!( (3..=5).contains(&5)); - /// assert!(!(3..=5).contains(&6)); - /// - /// assert!( (3..=3).contains(&3)); - /// assert!(!(3..=2).contains(&3)); - /// - /// assert!( (0.0..=1.0).contains(&1.0)); - /// assert!(!(0.0..=1.0).contains(&f32::NAN)); - /// assert!(!(0.0..=f32::NAN).contains(&0.0)); - /// assert!(!(f32::NAN..=1.0).contains(&1.0)); - /// ``` - /// - /// This method always returns `false` after iteration has finished: - /// - /// ``` - /// let mut r = 3..=5; - /// assert!(r.contains(&3) && r.contains(&5)); - /// for _ in r.by_ref() {} - /// // Precise field values are unspecified here - /// assert!(!r.contains(&3) && !r.contains(&5)); - /// ``` - #[inline] - #[stable(feature = "range_contains", since = "1.35.0")] - pub fn contains(&self, item: &U) -> bool - where - Idx: PartialOrd, - U: ?Sized + PartialOrd, - { - >::contains(self, item) - } - - /// Returns `true` if the range contains no items. - /// - /// # Examples - /// - /// ``` - /// assert!(!(3..=5).is_empty()); - /// assert!(!(3..=3).is_empty()); - /// assert!( (3..=2).is_empty()); - /// ``` - /// - /// The range is empty if either side is incomparable: - /// - /// ``` - /// assert!(!(3.0..=5.0).is_empty()); - /// assert!( (3.0..=f32::NAN).is_empty()); - /// assert!( (f32::NAN..=5.0).is_empty()); - /// ``` - /// - /// This method returns `true` after iteration has finished: - /// - /// ``` - /// let mut r = 3..=5; - /// for _ in r.by_ref() {} - /// // Precise field values are unspecified here - /// assert!(r.is_empty()); - /// ``` - #[stable(feature = "range_is_empty", since = "1.47.0")] - #[inline] - pub fn is_empty(&self) -> bool { - self.exhausted || !(self.start <= self.end) - } -} - -/// A range only bounded inclusively above (`..=end`). -/// -/// The `RangeToInclusive` `..=end` contains all values with `x <= end`. -/// It cannot serve as an [`Iterator`] because it doesn't have a starting point. -/// -/// # Examples -/// -/// The `..=end` syntax is a `RangeToInclusive`: -/// -/// ``` -/// assert_eq!((..=5), std::ops::RangeToInclusive{ end: 5 }); -/// ``` -/// -/// It does not have an [`IntoIterator`] implementation, so you can't use it in a -/// `for` loop directly. This won't compile: -/// -/// ```compile_fail,E0277 -/// // error[E0277]: the trait bound `std::ops::RangeToInclusive<{integer}>: -/// // std::iter::Iterator` is not satisfied -/// for i in ..=5 { -/// // ... -/// } -/// ``` -/// -/// When used as a [slicing index], `RangeToInclusive` produces a slice of all -/// array elements up to and including the index indicated by `end`. -/// -/// ``` -/// let arr = [0, 1, 2, 3, 4]; -/// assert_eq!(arr[ .. ], [0, 1, 2, 3, 4]); -/// assert_eq!(arr[ .. 3], [0, 1, 2 ]); -/// assert_eq!(arr[ ..=3], [0, 1, 2, 3 ]); // This is a `RangeToInclusive` -/// assert_eq!(arr[1.. ], [ 1, 2, 3, 4]); -/// assert_eq!(arr[1.. 3], [ 1, 2 ]); -/// assert_eq!(arr[1..=3], [ 1, 2, 3 ]); -/// ``` -/// -/// [slicing index]: crate::slice::SliceIndex -#[lang = "RangeToInclusive"] -#[doc(alias = "..=")] -#[derive(Copy, Clone, PartialEq, Eq, Hash)] -#[stable(feature = "inclusive_range", since = "1.26.0")] -pub struct RangeToInclusive { - /// The upper bound of the range (inclusive) - #[stable(feature = "inclusive_range", since = "1.26.0")] - pub end: Idx, -} - -#[stable(feature = "inclusive_range", since = "1.26.0")] -impl fmt::Debug for RangeToInclusive { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(fmt, "..=")?; - self.end.fmt(fmt)?; - Ok(()) - } -} - -impl> RangeToInclusive { - /// Returns `true` if `item` is contained in the range. - /// - /// # Examples - /// - /// ``` - /// assert!( (..=5).contains(&-1_000_000_000)); - /// assert!( (..=5).contains(&5)); - /// assert!(!(..=5).contains(&6)); - /// - /// assert!( (..=1.0).contains(&1.0)); - /// assert!(!(..=1.0).contains(&f32::NAN)); - /// assert!(!(..=f32::NAN).contains(&0.5)); - /// ``` - #[inline] - #[stable(feature = "range_contains", since = "1.35.0")] - pub fn contains(&self, item: &U) -> bool - where - Idx: PartialOrd, - U: ?Sized + PartialOrd, - { - >::contains(self, item) - } -} - -// RangeToInclusive cannot impl From> -// because underflow would be possible with (..0).into() - -/// An endpoint of a range of keys. -/// -/// # Examples -/// -/// `Bound`s are range endpoints: -/// -/// ``` -/// use std::ops::Bound::*; -/// use std::ops::RangeBounds; -/// -/// assert_eq!((..100).start_bound(), Unbounded); -/// assert_eq!((1..12).start_bound(), Included(&1)); -/// assert_eq!((1..12).end_bound(), Excluded(&12)); -/// ``` -/// -/// Using a tuple of `Bound`s as an argument to [`BTreeMap::range`]. -/// Note that in most cases, it's better to use range syntax (`1..5`) instead. -/// -/// ``` -/// use std::collections::BTreeMap; -/// use std::ops::Bound::{Excluded, Included, Unbounded}; -/// -/// let mut map = BTreeMap::new(); -/// map.insert(3, "a"); -/// map.insert(5, "b"); -/// map.insert(8, "c"); -/// -/// for (key, value) in map.range((Excluded(3), Included(8))) { -/// println!("{key}: {value}"); -/// } -/// -/// assert_eq!(Some((&3, &"a")), map.range((Unbounded, Included(5))).next()); -/// ``` -/// -/// [`BTreeMap::range`]: ../../std/collections/btree_map/struct.BTreeMap.html#method.range -#[stable(feature = "collections_bound", since = "1.17.0")] -#[derive(Clone, Copy, Debug, Hash, PartialEq, Eq)] -pub enum Bound { - /// An inclusive bound. - #[stable(feature = "collections_bound", since = "1.17.0")] - Included(#[stable(feature = "collections_bound", since = "1.17.0")] T), - /// An exclusive bound. - #[stable(feature = "collections_bound", since = "1.17.0")] - Excluded(#[stable(feature = "collections_bound", since = "1.17.0")] T), - /// An infinite endpoint. Indicates that there is no bound in this direction. - #[stable(feature = "collections_bound", since = "1.17.0")] - Unbounded, -} - -impl Bound { - /// Converts from `&Bound` to `Bound<&T>`. - #[inline] - #[stable(feature = "bound_as_ref_shared", since = "1.65.0")] - pub fn as_ref(&self) -> Bound<&T> { - match *self { - Included(ref x) => Included(x), - Excluded(ref x) => Excluded(x), - Unbounded => Unbounded, - } - } - - /// Converts from `&mut Bound` to `Bound<&mut T>`. - #[inline] - #[unstable(feature = "bound_as_ref", issue = "80996")] - pub fn as_mut(&mut self) -> Bound<&mut T> { - match *self { - Included(ref mut x) => Included(x), - Excluded(ref mut x) => Excluded(x), - Unbounded => Unbounded, - } - } - - /// Maps a `Bound` to a `Bound` by applying a function to the contained value (including - /// both `Included` and `Excluded`), returning a `Bound` of the same kind. - /// - /// # Examples - /// - /// ``` - /// use std::ops::Bound::*; - /// - /// let bound_string = Included("Hello, World!"); - /// - /// assert_eq!(bound_string.map(|s| s.len()), Included(13)); - /// ``` - /// - /// ``` - /// use std::ops::Bound; - /// use Bound::*; - /// - /// let unbounded_string: Bound = Unbounded; - /// - /// assert_eq!(unbounded_string.map(|s| s.len()), Unbounded); - /// ``` - #[inline] - #[stable(feature = "bound_map", since = "1.77.0")] - pub fn map U>(self, f: F) -> Bound { - match self { - Unbounded => Unbounded, - Included(x) => Included(f(x)), - Excluded(x) => Excluded(f(x)), - } - } -} - -impl Bound<&T> { - /// Map a `Bound<&T>` to a `Bound` by cloning the contents of the bound. - /// - /// # Examples - /// - /// ``` - /// use std::ops::Bound::*; - /// use std::ops::RangeBounds; - /// - /// assert_eq!((1..12).start_bound(), Included(&1)); - /// assert_eq!((1..12).start_bound().cloned(), Included(1)); - /// ``` - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "bound_cloned", since = "1.55.0")] - pub fn cloned(self) -> Bound { - match self { - Bound::Unbounded => Bound::Unbounded, - Bound::Included(x) => Bound::Included(x.clone()), - Bound::Excluded(x) => Bound::Excluded(x.clone()), - } - } -} - -/// `RangeBounds` is implemented by Rust's built-in range types, produced -/// by range syntax like `..`, `a..`, `..b`, `..=c`, `d..e`, or `f..=g`. -#[stable(feature = "collections_range", since = "1.28.0")] -#[rustc_diagnostic_item = "RangeBounds"] -pub trait RangeBounds { - /// Start index bound. - /// - /// Returns the start value as a `Bound`. - /// - /// # Examples - /// - /// ``` - /// # fn main() { - /// use std::ops::Bound::*; - /// use std::ops::RangeBounds; - /// - /// assert_eq!((..10).start_bound(), Unbounded); - /// assert_eq!((3..10).start_bound(), Included(&3)); - /// # } - /// ``` - #[stable(feature = "collections_range", since = "1.28.0")] - fn start_bound(&self) -> Bound<&T>; - - /// End index bound. - /// - /// Returns the end value as a `Bound`. - /// - /// # Examples - /// - /// ``` - /// # fn main() { - /// use std::ops::Bound::*; - /// use std::ops::RangeBounds; - /// - /// assert_eq!((3..).end_bound(), Unbounded); - /// assert_eq!((3..10).end_bound(), Excluded(&10)); - /// # } - /// ``` - #[stable(feature = "collections_range", since = "1.28.0")] - fn end_bound(&self) -> Bound<&T>; - - /// Returns `true` if `item` is contained in the range. - /// - /// # Examples - /// - /// ``` - /// assert!( (3..5).contains(&4)); - /// assert!(!(3..5).contains(&2)); - /// - /// assert!( (0.0..1.0).contains(&0.5)); - /// assert!(!(0.0..1.0).contains(&f32::NAN)); - /// assert!(!(0.0..f32::NAN).contains(&0.5)); - /// assert!(!(f32::NAN..1.0).contains(&0.5)); - #[inline] - #[stable(feature = "range_contains", since = "1.35.0")] - fn contains(&self, item: &U) -> bool - where - T: PartialOrd, - U: ?Sized + PartialOrd, - { - (match self.start_bound() { - Included(start) => start <= item, - Excluded(start) => start < item, - Unbounded => true, - }) && (match self.end_bound() { - Included(end) => item <= end, - Excluded(end) => item < end, - Unbounded => true, - }) - } -} - -use self::Bound::{Excluded, Included, Unbounded}; - -#[stable(feature = "collections_range", since = "1.28.0")] -impl RangeBounds for RangeFull { - fn start_bound(&self) -> Bound<&T> { - Unbounded - } - fn end_bound(&self) -> Bound<&T> { - Unbounded - } -} - -#[stable(feature = "collections_range", since = "1.28.0")] -impl RangeBounds for RangeFrom { - fn start_bound(&self) -> Bound<&T> { - Included(&self.start) - } - fn end_bound(&self) -> Bound<&T> { - Unbounded - } -} - -#[stable(feature = "collections_range", since = "1.28.0")] -impl RangeBounds for RangeTo { - fn start_bound(&self) -> Bound<&T> { - Unbounded - } - fn end_bound(&self) -> Bound<&T> { - Excluded(&self.end) - } -} - -#[stable(feature = "collections_range", since = "1.28.0")] -impl RangeBounds for Range { - fn start_bound(&self) -> Bound<&T> { - Included(&self.start) - } - fn end_bound(&self) -> Bound<&T> { - Excluded(&self.end) - } -} - -#[stable(feature = "collections_range", since = "1.28.0")] -impl RangeBounds for RangeInclusive { - fn start_bound(&self) -> Bound<&T> { - Included(&self.start) - } - fn end_bound(&self) -> Bound<&T> { - if self.exhausted { - // When the iterator is exhausted, we usually have start == end, - // but we want the range to appear empty, containing nothing. - Excluded(&self.end) - } else { - Included(&self.end) - } - } -} - -#[stable(feature = "collections_range", since = "1.28.0")] -impl RangeBounds for RangeToInclusive { - fn start_bound(&self) -> Bound<&T> { - Unbounded - } - fn end_bound(&self) -> Bound<&T> { - Included(&self.end) - } -} - -#[stable(feature = "collections_range", since = "1.28.0")] -impl RangeBounds for (Bound, Bound) { - fn start_bound(&self) -> Bound<&T> { - match *self { - (Included(ref start), _) => Included(start), - (Excluded(ref start), _) => Excluded(start), - (Unbounded, _) => Unbounded, - } - } - - fn end_bound(&self) -> Bound<&T> { - match *self { - (_, Included(ref end)) => Included(end), - (_, Excluded(ref end)) => Excluded(end), - (_, Unbounded) => Unbounded, - } - } -} - -#[stable(feature = "collections_range", since = "1.28.0")] -impl<'a, T: ?Sized + 'a> RangeBounds for (Bound<&'a T>, Bound<&'a T>) { - fn start_bound(&self) -> Bound<&T> { - self.0 - } - - fn end_bound(&self) -> Bound<&T> { - self.1 - } -} - -#[stable(feature = "collections_range", since = "1.28.0")] -impl RangeBounds for RangeFrom<&T> { - fn start_bound(&self) -> Bound<&T> { - Included(self.start) - } - fn end_bound(&self) -> Bound<&T> { - Unbounded - } -} - -#[stable(feature = "collections_range", since = "1.28.0")] -impl RangeBounds for RangeTo<&T> { - fn start_bound(&self) -> Bound<&T> { - Unbounded - } - fn end_bound(&self) -> Bound<&T> { - Excluded(self.end) - } -} - -#[stable(feature = "collections_range", since = "1.28.0")] -impl RangeBounds for Range<&T> { - fn start_bound(&self) -> Bound<&T> { - Included(self.start) - } - fn end_bound(&self) -> Bound<&T> { - Excluded(self.end) - } -} - -#[stable(feature = "collections_range", since = "1.28.0")] -impl RangeBounds for RangeInclusive<&T> { - fn start_bound(&self) -> Bound<&T> { - Included(self.start) - } - fn end_bound(&self) -> Bound<&T> { - Included(self.end) - } -} - -#[stable(feature = "collections_range", since = "1.28.0")] -impl RangeBounds for RangeToInclusive<&T> { - fn start_bound(&self) -> Bound<&T> { - Unbounded - } - fn end_bound(&self) -> Bound<&T> { - Included(self.end) - } -} - -/// `OneSidedRange` is implemented for built-in range types that are unbounded -/// on one side. For example, `a..`, `..b` and `..=c` implement `OneSidedRange`, -/// but `..`, `d..e`, and `f..=g` do not. -/// -/// Types that implement `OneSidedRange` must return `Bound::Unbounded` -/// from one of `RangeBounds::start_bound` or `RangeBounds::end_bound`. -#[unstable(feature = "one_sided_range", issue = "69780")] -pub trait OneSidedRange: RangeBounds {} - -#[unstable(feature = "one_sided_range", issue = "69780")] -impl OneSidedRange for RangeTo where Self: RangeBounds {} - -#[unstable(feature = "one_sided_range", issue = "69780")] -impl OneSidedRange for RangeFrom where Self: RangeBounds {} - -#[unstable(feature = "one_sided_range", issue = "69780")] -impl OneSidedRange for RangeToInclusive where Self: RangeBounds {} diff --git a/library/core/src/ops/try_trait.rs b/library/core/src/ops/try_trait.rs deleted file mode 100644 index 483f55b207093..0000000000000 --- a/library/core/src/ops/try_trait.rs +++ /dev/null @@ -1,426 +0,0 @@ -use crate::ops::ControlFlow; - -/// The `?` operator and `try {}` blocks. -/// -/// `try_*` methods typically involve a type implementing this trait. For -/// example, the closures passed to [`Iterator::try_fold`] and -/// [`Iterator::try_for_each`] must return such a type. -/// -/// `Try` types are typically those containing two or more categories of values, -/// some subset of which are so commonly handled via early returns that it's -/// worth providing a terse (but still visible) syntax to make that easy. -/// -/// This is most often seen for error handling with [`Result`] and [`Option`]. -/// The quintessential implementation of this trait is on [`ControlFlow`]. -/// -/// # Using `Try` in Generic Code -/// -/// `Iterator::try_fold` was stabilized to call back in Rust 1.27, but -/// this trait is much newer. To illustrate the various associated types and -/// methods, let's implement our own version. -/// -/// As a reminder, an infallible version of a fold looks something like this: -/// ``` -/// fn simple_fold( -/// iter: impl Iterator, -/// mut accum: A, -/// mut f: impl FnMut(A, T) -> A, -/// ) -> A { -/// for x in iter { -/// accum = f(accum, x); -/// } -/// accum -/// } -/// ``` -/// -/// So instead of `f` returning just an `A`, we'll need it to return some other -/// type that produces an `A` in the "don't short circuit" path. Conveniently, -/// that's also the type we need to return from the function. -/// -/// Let's add a new generic parameter `R` for that type, and bound it to the -/// output type that we want: -/// ``` -/// # #![feature(try_trait_v2)] -/// # use std::ops::Try; -/// fn simple_try_fold_1>( -/// iter: impl Iterator, -/// mut accum: A, -/// mut f: impl FnMut(A, T) -> R, -/// ) -> R { -/// todo!() -/// } -/// ``` -/// -/// If we get through the entire iterator, we need to wrap up the accumulator -/// into the return type using [`Try::from_output`]: -/// ``` -/// # #![feature(try_trait_v2)] -/// # use std::ops::{ControlFlow, Try}; -/// fn simple_try_fold_2>( -/// iter: impl Iterator, -/// mut accum: A, -/// mut f: impl FnMut(A, T) -> R, -/// ) -> R { -/// for x in iter { -/// let cf = f(accum, x).branch(); -/// match cf { -/// ControlFlow::Continue(a) => accum = a, -/// ControlFlow::Break(_) => todo!(), -/// } -/// } -/// R::from_output(accum) -/// } -/// ``` -/// -/// We'll also need [`FromResidual::from_residual`] to turn the residual back -/// into the original type. But because it's a supertrait of `Try`, we don't -/// need to mention it in the bounds. All types which implement `Try` can be -/// recreated from their corresponding residual, so we'll just call it: -/// ``` -/// # #![feature(try_trait_v2)] -/// # use std::ops::{ControlFlow, Try}; -/// pub fn simple_try_fold_3>( -/// iter: impl Iterator, -/// mut accum: A, -/// mut f: impl FnMut(A, T) -> R, -/// ) -> R { -/// for x in iter { -/// let cf = f(accum, x).branch(); -/// match cf { -/// ControlFlow::Continue(a) => accum = a, -/// ControlFlow::Break(r) => return R::from_residual(r), -/// } -/// } -/// R::from_output(accum) -/// } -/// ``` -/// -/// But this "call `branch`, then `match` on it, and `return` if it was a -/// `Break`" is exactly what happens inside the `?` operator. So rather than -/// do all this manually, we can just use `?` instead: -/// ``` -/// # #![feature(try_trait_v2)] -/// # use std::ops::Try; -/// fn simple_try_fold>( -/// iter: impl Iterator, -/// mut accum: A, -/// mut f: impl FnMut(A, T) -> R, -/// ) -> R { -/// for x in iter { -/// accum = f(accum, x)?; -/// } -/// R::from_output(accum) -/// } -/// ``` -#[unstable(feature = "try_trait_v2", issue = "84277")] -#[rustc_on_unimplemented( - on( - all(from_desugaring = "TryBlock"), - message = "a `try` block must return `Result` or `Option` \ - (or another type that implements `{Try}`)", - label = "could not wrap the final value of the block as `{Self}` doesn't implement `Try`", - ), - on( - all(from_desugaring = "QuestionMark"), - message = "the `?` operator can only be applied to values that implement `{Try}`", - label = "the `?` operator cannot be applied to type `{Self}`" - ) -)] -#[doc(alias = "?")] -#[lang = "Try"] -pub trait Try: FromResidual { - /// The type of the value produced by `?` when *not* short-circuiting. - #[unstable(feature = "try_trait_v2", issue = "84277")] - type Output; - - /// The type of the value passed to [`FromResidual::from_residual`] - /// as part of `?` when short-circuiting. - /// - /// This represents the possible values of the `Self` type which are *not* - /// represented by the `Output` type. - /// - /// # Note to Implementors - /// - /// The choice of this type is critical to interconversion. - /// Unlike the `Output` type, which will often be a raw generic type, - /// this type is typically a newtype of some sort to "color" the type - /// so that it's distinguishable from the residuals of other types. - /// - /// This is why `Result::Residual` is not `E`, but `Result`. - /// That way it's distinct from `ControlFlow::Residual`, for example, - /// and thus `?` on `ControlFlow` cannot be used in a method returning `Result`. - /// - /// If you're making a generic type `Foo` that implements `Try`, - /// then typically you can use `Foo` as its `Residual` - /// type: that type will have a "hole" in the correct place, and will maintain the - /// "foo-ness" of the residual so other types need to opt-in to interconversion. - #[unstable(feature = "try_trait_v2", issue = "84277")] - type Residual; - - /// Constructs the type from its `Output` type. - /// - /// This should be implemented consistently with the `branch` method - /// such that applying the `?` operator will get back the original value: - /// `Try::from_output(x).branch() --> ControlFlow::Continue(x)`. - /// - /// # Examples - /// - /// ``` - /// #![feature(try_trait_v2)] - /// use std::ops::Try; - /// - /// assert_eq!( as Try>::from_output(3), Ok(3)); - /// assert_eq!( as Try>::from_output(4), Some(4)); - /// assert_eq!( - /// as Try>::from_output(5), - /// std::ops::ControlFlow::Continue(5), - /// ); - /// - /// # fn make_question_mark_work() -> Option<()> { - /// assert_eq!(Option::from_output(4)?, 4); - /// # None } - /// # make_question_mark_work(); - /// - /// // This is used, for example, on the accumulator in `try_fold`: - /// let r = std::iter::empty().try_fold(4, |_, ()| -> Option<_> { unreachable!() }); - /// assert_eq!(r, Some(4)); - /// ``` - #[lang = "from_output"] - #[unstable(feature = "try_trait_v2", issue = "84277")] - fn from_output(output: Self::Output) -> Self; - - /// Used in `?` to decide whether the operator should produce a value - /// (because this returned [`ControlFlow::Continue`]) - /// or propagate a value back to the caller - /// (because this returned [`ControlFlow::Break`]). - /// - /// # Examples - /// - /// ``` - /// #![feature(try_trait_v2)] - /// use std::ops::{ControlFlow, Try}; - /// - /// assert_eq!(Ok::<_, String>(3).branch(), ControlFlow::Continue(3)); - /// assert_eq!(Err::(3).branch(), ControlFlow::Break(Err(3))); - /// - /// assert_eq!(Some(3).branch(), ControlFlow::Continue(3)); - /// assert_eq!(None::.branch(), ControlFlow::Break(None)); - /// - /// assert_eq!(ControlFlow::::Continue(3).branch(), ControlFlow::Continue(3)); - /// assert_eq!( - /// ControlFlow::<_, String>::Break(3).branch(), - /// ControlFlow::Break(ControlFlow::Break(3)), - /// ); - /// ``` - #[lang = "branch"] - #[unstable(feature = "try_trait_v2", issue = "84277")] - fn branch(self) -> ControlFlow; -} - -/// Used to specify which residuals can be converted into which [`crate::ops::Try`] types. -/// -/// Every `Try` type needs to be recreatable from its own associated -/// `Residual` type, but can also have additional `FromResidual` implementations -/// to support interconversion with other `Try` types. -#[rustc_on_unimplemented( - on( - all( - from_desugaring = "QuestionMark", - _Self = "core::result::Result", - R = "core::option::Option", - ), - message = "the `?` operator can only be used on `Result`s, not `Option`s, \ - in {ItemContext} that returns `Result`", - label = "use `.ok_or(...)?` to provide an error compatible with `{Self}`", - parent_label = "this function returns a `Result`" - ), - on( - all( - from_desugaring = "QuestionMark", - _Self = "core::result::Result", - ), - // There's a special error message in the trait selection code for - // `From` in `?`, so this is not shown for result-in-result errors, - // and thus it can be phrased more strongly than `ControlFlow`'s. - message = "the `?` operator can only be used on `Result`s \ - in {ItemContext} that returns `Result`", - label = "this `?` produces `{R}`, which is incompatible with `{Self}`", - parent_label = "this function returns a `Result`" - ), - on( - all( - from_desugaring = "QuestionMark", - _Self = "core::option::Option", - R = "core::result::Result", - ), - message = "the `?` operator can only be used on `Option`s, not `Result`s, \ - in {ItemContext} that returns `Option`", - label = "use `.ok()?` if you want to discard the `{R}` error information", - parent_label = "this function returns an `Option`" - ), - on( - all( - from_desugaring = "QuestionMark", - _Self = "core::option::Option", - ), - // `Option`-in-`Option` always works, as there's only one possible - // residual, so this can also be phrased strongly. - message = "the `?` operator can only be used on `Option`s \ - in {ItemContext} that returns `Option`", - label = "this `?` produces `{R}`, which is incompatible with `{Self}`", - parent_label = "this function returns an `Option`" - ), - on( - all( - from_desugaring = "QuestionMark", - _Self = "core::ops::control_flow::ControlFlow", - R = "core::ops::control_flow::ControlFlow", - ), - message = "the `?` operator in {ItemContext} that returns `ControlFlow` \ - can only be used on other `ControlFlow`s (with the same Break type)", - label = "this `?` produces `{R}`, which is incompatible with `{Self}`", - parent_label = "this function returns a `ControlFlow`", - note = "unlike `Result`, there's no `From`-conversion performed for `ControlFlow`" - ), - on( - all( - from_desugaring = "QuestionMark", - _Self = "core::ops::control_flow::ControlFlow", - // `R` is not a `ControlFlow`, as that case was matched previously - ), - message = "the `?` operator can only be used on `ControlFlow`s \ - in {ItemContext} that returns `ControlFlow`", - label = "this `?` produces `{R}`, which is incompatible with `{Self}`", - parent_label = "this function returns a `ControlFlow`", - ), - on( - all(from_desugaring = "QuestionMark"), - message = "the `?` operator can only be used in {ItemContext} \ - that returns `Result` or `Option` \ - (or another type that implements `{FromResidual}`)", - label = "cannot use the `?` operator in {ItemContext} that returns `{Self}`", - parent_label = "this function should return `Result` or `Option` to accept `?`" - ), -)] -#[rustc_diagnostic_item = "FromResidual"] -#[unstable(feature = "try_trait_v2", issue = "84277")] -pub trait FromResidual::Residual> { - /// Constructs the type from a compatible `Residual` type. - /// - /// This should be implemented consistently with the `branch` method such - /// that applying the `?` operator will get back an equivalent residual: - /// `FromResidual::from_residual(r).branch() --> ControlFlow::Break(r)`. - /// (The residual is not mandated to be *identical* when interconversion is involved.) - /// - /// # Examples - /// - /// ``` - /// #![feature(try_trait_v2)] - /// use std::ops::{ControlFlow, FromResidual}; - /// - /// assert_eq!(Result::::from_residual(Err(3_u8)), Err(3)); - /// assert_eq!(Option::::from_residual(None), None); - /// assert_eq!( - /// ControlFlow::<_, String>::from_residual(ControlFlow::Break(5)), - /// ControlFlow::Break(5), - /// ); - /// ``` - #[lang = "from_residual"] - #[unstable(feature = "try_trait_v2", issue = "84277")] - fn from_residual(residual: R) -> Self; -} - -#[unstable( - feature = "yeet_desugar_details", - issue = "none", - reason = "just here to simplify the desugaring; will never be stabilized" -)] -#[inline] -#[track_caller] // because `Result::from_residual` has it -#[lang = "from_yeet"] -pub fn from_yeet(yeeted: Y) -> T -where - T: FromResidual>, -{ - FromResidual::from_residual(Yeet(yeeted)) -} - -/// Allows retrieving the canonical type implementing [`Try`] that has this type -/// as its residual and allows it to hold an `O` as its output. -/// -/// If you think of the `Try` trait as splitting a type into its [`Try::Output`] -/// and [`Try::Residual`] components, this allows putting them back together. -/// -/// For example, -/// `Result: Try>`, -/// and in the other direction, -/// ` as Residual>::TryType = Result`. -#[unstable(feature = "try_trait_v2_residual", issue = "91285")] -pub trait Residual { - /// The "return" type of this meta-function. - #[unstable(feature = "try_trait_v2_residual", issue = "91285")] - type TryType: Try; -} - -#[unstable(feature = "pub_crate_should_not_need_unstable_attr", issue = "none")] -pub(crate) type ChangeOutputType = <::Residual as Residual>::TryType; - -/// An adapter for implementing non-try methods via the `Try` implementation. -/// -/// Conceptually the same as `Result`, but requiring less work in trait -/// solving and inhabited-ness checking and such, by being an obvious newtype -/// and not having `From` bounds lying around. -/// -/// Not currently planned to be exposed publicly, so just `pub(crate)`. -#[repr(transparent)] -pub(crate) struct NeverShortCircuit(pub T); - -impl NeverShortCircuit { - /// Wraps a unary function to produce one that wraps the output into a `NeverShortCircuit`. - /// - /// This is useful for implementing infallible functions in terms of the `try_` ones, - /// without accidentally capturing extra generic parameters in a closure. - #[inline] - pub fn wrap_mut_1(mut f: impl FnMut(A) -> T) -> impl FnMut(A) -> NeverShortCircuit { - move |a| NeverShortCircuit(f(a)) - } - - #[inline] - pub fn wrap_mut_2(mut f: impl FnMut(A, B) -> T) -> impl FnMut(A, B) -> Self { - move |a, b| NeverShortCircuit(f(a, b)) - } -} - -pub(crate) enum NeverShortCircuitResidual {} - -impl Try for NeverShortCircuit { - type Output = T; - type Residual = NeverShortCircuitResidual; - - #[inline] - fn branch(self) -> ControlFlow { - ControlFlow::Continue(self.0) - } - - #[inline] - fn from_output(x: T) -> Self { - NeverShortCircuit(x) - } -} - -impl FromResidual for NeverShortCircuit { - #[inline] - fn from_residual(never: NeverShortCircuitResidual) -> Self { - match never {} - } -} - -impl Residual for NeverShortCircuitResidual { - type TryType = NeverShortCircuit; -} - -/// Implement `FromResidual>` on your type to enable -/// `do yeet expr` syntax in functions returning your type. -#[unstable(feature = "try_trait_v2_yeet", issue = "96374")] -#[derive(Debug)] -pub struct Yeet(pub T); diff --git a/library/core/src/ops/unsize.rs b/library/core/src/ops/unsize.rs deleted file mode 100644 index b51f12580ea4f..0000000000000 --- a/library/core/src/ops/unsize.rs +++ /dev/null @@ -1,132 +0,0 @@ -use crate::marker::Unsize; - -/// Trait that indicates that this is a pointer or a wrapper for one, -/// where unsizing can be performed on the pointee. -/// -/// See the [DST coercion RFC][dst-coerce] and [the nomicon entry on coercion][nomicon-coerce] -/// for more details. -/// -/// For builtin pointer types, pointers to `T` will coerce to pointers to `U` if `T: Unsize` -/// by converting from a thin pointer to a fat pointer. -/// -/// For custom types, the coercion here works by coercing `Foo` to `Foo` -/// provided an impl of `CoerceUnsized> for Foo` exists. -/// Such an impl can only be written if `Foo` has only a single non-phantomdata -/// field involving `T`. If the type of that field is `Bar`, an implementation -/// of `CoerceUnsized> for Bar` must exist. The coercion will work by -/// coercing the `Bar` field into `Bar` and filling in the rest of the fields -/// from `Foo` to create a `Foo`. This will effectively drill down to a pointer -/// field and coerce that. -/// -/// Generally, for smart pointers you will implement -/// `CoerceUnsized> for Ptr where T: Unsize, U: ?Sized`, with an -/// optional `?Sized` bound on `T` itself. For wrapper types that directly embed `T` -/// like `Cell` and `RefCell`, you -/// can directly implement `CoerceUnsized> for Wrap where T: CoerceUnsized`. -/// This will let coercions of types like `Cell>` work. -/// -/// [`Unsize`][unsize] is used to mark types which can be coerced to DSTs if behind -/// pointers. It is implemented automatically by the compiler. -/// -/// [dst-coerce]: https://github.com/rust-lang/rfcs/blob/master/text/0982-dst-coercion.md -/// [unsize]: crate::marker::Unsize -/// [nomicon-coerce]: ../../nomicon/coercions.html -#[unstable(feature = "coerce_unsized", issue = "18598")] -#[lang = "coerce_unsized"] -pub trait CoerceUnsized { - // Empty. -} - -// &mut T -> &mut U -#[unstable(feature = "coerce_unsized", issue = "18598")] -impl<'a, T: ?Sized + Unsize, U: ?Sized> CoerceUnsized<&'a mut U> for &'a mut T {} -// &mut T -> &U -#[unstable(feature = "coerce_unsized", issue = "18598")] -impl<'a, 'b: 'a, T: ?Sized + Unsize, U: ?Sized> CoerceUnsized<&'a U> for &'b mut T {} -// &mut T -> *mut U -#[unstable(feature = "coerce_unsized", issue = "18598")] -impl<'a, T: ?Sized + Unsize, U: ?Sized> CoerceUnsized<*mut U> for &'a mut T {} -// &mut T -> *const U -#[unstable(feature = "coerce_unsized", issue = "18598")] -impl<'a, T: ?Sized + Unsize, U: ?Sized> CoerceUnsized<*const U> for &'a mut T {} - -// &T -> &U -#[unstable(feature = "coerce_unsized", issue = "18598")] -impl<'a, 'b: 'a, T: ?Sized + Unsize, U: ?Sized> CoerceUnsized<&'a U> for &'b T {} -// &T -> *const U -#[unstable(feature = "coerce_unsized", issue = "18598")] -impl<'a, T: ?Sized + Unsize, U: ?Sized> CoerceUnsized<*const U> for &'a T {} - -// *mut T -> *mut U -#[unstable(feature = "coerce_unsized", issue = "18598")] -impl, U: ?Sized> CoerceUnsized<*mut U> for *mut T {} -// *mut T -> *const U -#[unstable(feature = "coerce_unsized", issue = "18598")] -impl, U: ?Sized> CoerceUnsized<*const U> for *mut T {} - -// *const T -> *const U -#[unstable(feature = "coerce_unsized", issue = "18598")] -impl, U: ?Sized> CoerceUnsized<*const U> for *const T {} - -/// `DispatchFromDyn` is used in the implementation of object safety checks (specifically allowing -/// arbitrary self types), to guarantee that a method's receiver type can be dispatched on. -/// -/// Note: `DispatchFromDyn` was briefly named `CoerceSized` (and had a slightly different -/// interpretation). -/// -/// Imagine we have a trait object `t` with type `&dyn Tr`, where `Tr` is some trait with a method -/// `m` defined as `fn m(&self);`. When calling `t.m()`, the receiver `t` is a wide pointer, but an -/// implementation of `m` will expect a narrow pointer as `&self` (a reference to the concrete -/// type). The compiler must generate an implicit conversion from the trait object/wide pointer to -/// the concrete reference/narrow pointer. Implementing `DispatchFromDyn` indicates that that -/// conversion is allowed and thus that the type implementing `DispatchFromDyn` is safe to use as -/// the self type in an object-safe method. (in the above example, the compiler will require -/// `DispatchFromDyn` is implemented for `&'a U`). -/// -/// `DispatchFromDyn` does not specify the conversion from wide pointer to narrow pointer; the -/// conversion is hard-wired into the compiler. For the conversion to work, the following -/// properties must hold (i.e., it is only safe to implement `DispatchFromDyn` for types which have -/// these properties, these are also checked by the compiler): -/// -/// * EITHER `Self` and `T` are either both references or both raw pointers; in either case, with -/// the same mutability. -/// * OR, all of the following hold -/// - `Self` and `T` must have the same type constructor, and only vary in a single type parameter -/// formal (the *coerced type*, e.g., `impl DispatchFromDyn> for Rc` is ok and the -/// single type parameter (instantiated with `T` or `U`) is the coerced type, -/// `impl DispatchFromDyn> for Rc` is not ok). -/// - The definition for `Self` must be a struct. -/// - The definition for `Self` must not be `#[repr(packed)]` or `#[repr(C)]`. -/// - Other than one-aligned, zero-sized fields, the definition for `Self` must have exactly one -/// field and that field's type must be the coerced type. Furthermore, `Self`'s field type must -/// implement `DispatchFromDyn` where `F` is the type of `T`'s field type. -/// -/// An example implementation of the trait: -/// -/// ``` -/// # #![feature(dispatch_from_dyn, unsize)] -/// # use std::{ops::DispatchFromDyn, marker::Unsize}; -/// # struct Rc(std::rc::Rc); -/// impl DispatchFromDyn> for Rc -/// where -/// T: Unsize, -/// {} -/// ``` -#[unstable(feature = "dispatch_from_dyn", issue = "none")] -#[lang = "dispatch_from_dyn"] -pub trait DispatchFromDyn { - // Empty. -} - -// &T -> &U -#[unstable(feature = "dispatch_from_dyn", issue = "none")] -impl<'a, T: ?Sized + Unsize, U: ?Sized> DispatchFromDyn<&'a U> for &'a T {} -// &mut T -> &mut U -#[unstable(feature = "dispatch_from_dyn", issue = "none")] -impl<'a, T: ?Sized + Unsize, U: ?Sized> DispatchFromDyn<&'a mut U> for &'a mut T {} -// *const T -> *const U -#[unstable(feature = "dispatch_from_dyn", issue = "none")] -impl, U: ?Sized> DispatchFromDyn<*const U> for *const T {} -// *mut T -> *mut U -#[unstable(feature = "dispatch_from_dyn", issue = "none")] -impl, U: ?Sized> DispatchFromDyn<*mut U> for *mut T {} diff --git a/library/core/src/option.rs b/library/core/src/option.rs deleted file mode 100644 index 1e3ed0f7c49f1..0000000000000 --- a/library/core/src/option.rs +++ /dev/null @@ -1,2518 +0,0 @@ -//! Optional values. -//! -//! Type [`Option`] represents an optional value: every [`Option`] -//! is either [`Some`] and contains a value, or [`None`], and -//! does not. [`Option`] types are very common in Rust code, as -//! they have a number of uses: -//! -//! * Initial values -//! * Return values for functions that are not defined -//! over their entire input range (partial functions) -//! * Return value for otherwise reporting simple errors, where [`None`] is -//! returned on error -//! * Optional struct fields -//! * Struct fields that can be loaned or "taken" -//! * Optional function arguments -//! * Nullable pointers -//! * Swapping things out of difficult situations -//! -//! [`Option`]s are commonly paired with pattern matching to query the presence -//! of a value and take action, always accounting for the [`None`] case. -//! -//! ``` -//! fn divide(numerator: f64, denominator: f64) -> Option { -//! if denominator == 0.0 { -//! None -//! } else { -//! Some(numerator / denominator) -//! } -//! } -//! -//! // The return value of the function is an option -//! let result = divide(2.0, 3.0); -//! -//! // Pattern match to retrieve the value -//! match result { -//! // The division was valid -//! Some(x) => println!("Result: {x}"), -//! // The division was invalid -//! None => println!("Cannot divide by 0"), -//! } -//! ``` -//! -// -// FIXME: Show how `Option` is used in practice, with lots of methods -// -//! # Options and pointers ("nullable" pointers) -//! -//! Rust's pointer types must always point to a valid location; there are -//! no "null" references. Instead, Rust has *optional* pointers, like -//! the optional owned box, [Option]<[Box\]>. -//! -//! [Box\]: ../../std/boxed/struct.Box.html -//! -//! The following example uses [`Option`] to create an optional box of -//! [`i32`]. Notice that in order to use the inner [`i32`] value, the -//! `check_optional` function first needs to use pattern matching to -//! determine whether the box has a value (i.e., it is [`Some(...)`][`Some`]) or -//! not ([`None`]). -//! -//! ``` -//! let optional = None; -//! check_optional(optional); -//! -//! let optional = Some(Box::new(9000)); -//! check_optional(optional); -//! -//! fn check_optional(optional: Option>) { -//! match optional { -//! Some(p) => println!("has value {p}"), -//! None => println!("has no value"), -//! } -//! } -//! ``` -//! -//! # The question mark operator, `?` -//! -//! Similar to the [`Result`] type, when writing code that calls many functions that return the -//! [`Option`] type, handling `Some`/`None` can be tedious. The question mark -//! operator, [`?`], hides some of the boilerplate of propagating values -//! up the call stack. -//! -//! It replaces this: -//! -//! ``` -//! # #![allow(dead_code)] -//! fn add_last_numbers(stack: &mut Vec) -> Option { -//! let a = stack.pop(); -//! let b = stack.pop(); -//! -//! match (a, b) { -//! (Some(x), Some(y)) => Some(x + y), -//! _ => None, -//! } -//! } -//! -//! ``` -//! -//! With this: -//! -//! ``` -//! # #![allow(dead_code)] -//! fn add_last_numbers(stack: &mut Vec) -> Option { -//! Some(stack.pop()? + stack.pop()?) -//! } -//! ``` -//! -//! *It's much nicer!* -//! -//! Ending the expression with [`?`] will result in the [`Some`]'s unwrapped value, unless the -//! result is [`None`], in which case [`None`] is returned early from the enclosing function. -//! -//! [`?`] can be used in functions that return [`Option`] because of the -//! early return of [`None`] that it provides. -//! -//! [`?`]: crate::ops::Try -//! [`Some`]: Some -//! [`None`]: None -//! -//! # Representation -//! -//! Rust guarantees to optimize the following types `T` such that -//! [`Option`] has the same size, alignment, and [function call ABI] as `T`. In some -//! of these cases, Rust further guarantees that -//! `transmute::<_, Option>([0u8; size_of::()])` is sound and -//! produces `Option::::None`. These cases are identified by the -//! second column: -//! -//! | `T` | `transmute::<_, Option>([0u8; size_of::()])` sound? | -//! |---------------------------------------------------------------------|----------------------------------------------------------------------| -//! | [`Box`] (specifically, only `Box`) | when `U: Sized` | -//! | `&U` | when `U: Sized` | -//! | `&mut U` | when `U: Sized` | -//! | `fn`, `extern "C" fn`[^extern_fn] | always | -//! | [`num::NonZero*`] | always | -//! | [`ptr::NonNull`] | when `U: Sized` | -//! | `#[repr(transparent)]` struct around one of the types in this list. | when it holds for the inner type | -//! -//! [^extern_fn]: this remains true for any argument/return types and any other ABI: `extern "abi" fn` (_e.g._, `extern "system" fn`) -//! -//! [`Box`]: ../../std/boxed/struct.Box.html -//! [`num::NonZero*`]: crate::num -//! [`ptr::NonNull`]: crate::ptr::NonNull -//! [function call ABI]: ../primitive.fn.html#abi-compatibility -//! -//! This is called the "null pointer optimization" or NPO. -//! -//! It is further guaranteed that, for the cases above, one can -//! [`mem::transmute`] from all valid values of `T` to `Option` and -//! from `Some::(_)` to `T` (but transmuting `None::` to `T` -//! is undefined behaviour). -//! -//! # Method overview -//! -//! In addition to working with pattern matching, [`Option`] provides a wide -//! variety of different methods. -//! -//! ## Querying the variant -//! -//! The [`is_some`] and [`is_none`] methods return [`true`] if the [`Option`] -//! is [`Some`] or [`None`], respectively. -//! -//! [`is_none`]: Option::is_none -//! [`is_some`]: Option::is_some -//! -//! ## Adapters for working with references -//! -//! * [`as_ref`] converts from [&][][Option]\ to [Option]<[&]T> -//! * [`as_mut`] converts from [&mut] [Option]\ to [Option]<[&mut] T> -//! * [`as_deref`] converts from [&][][Option]\ to -//! [Option]<[&]T::[Target]> -//! * [`as_deref_mut`] converts from [&mut] [Option]\ to -//! [Option]<[&mut] T::[Target]> -//! * [`as_pin_ref`] converts from [Pin]<[&][][Option]\> to -//! [Option]<[Pin]<[&]T>> -//! * [`as_pin_mut`] converts from [Pin]<[&mut] [Option]\> to -//! [Option]<[Pin]<[&mut] T>> -//! -//! [&]: reference "shared reference" -//! [&mut]: reference "mutable reference" -//! [Target]: Deref::Target "ops::Deref::Target" -//! [`as_deref`]: Option::as_deref -//! [`as_deref_mut`]: Option::as_deref_mut -//! [`as_mut`]: Option::as_mut -//! [`as_pin_mut`]: Option::as_pin_mut -//! [`as_pin_ref`]: Option::as_pin_ref -//! [`as_ref`]: Option::as_ref -//! -//! ## Extracting the contained value -//! -//! These methods extract the contained value in an [`Option`] when it -//! is the [`Some`] variant. If the [`Option`] is [`None`]: -//! -//! * [`expect`] panics with a provided custom message -//! * [`unwrap`] panics with a generic message -//! * [`unwrap_or`] returns the provided default value -//! * [`unwrap_or_default`] returns the default value of the type `T` -//! (which must implement the [`Default`] trait) -//! * [`unwrap_or_else`] returns the result of evaluating the provided -//! function -//! -//! [`expect`]: Option::expect -//! [`unwrap`]: Option::unwrap -//! [`unwrap_or`]: Option::unwrap_or -//! [`unwrap_or_default`]: Option::unwrap_or_default -//! [`unwrap_or_else`]: Option::unwrap_or_else -//! -//! ## Transforming contained values -//! -//! These methods transform [`Option`] to [`Result`]: -//! -//! * [`ok_or`] transforms [`Some(v)`] to [`Ok(v)`], and [`None`] to -//! [`Err(err)`] using the provided default `err` value -//! * [`ok_or_else`] transforms [`Some(v)`] to [`Ok(v)`], and [`None`] to -//! a value of [`Err`] using the provided function -//! * [`transpose`] transposes an [`Option`] of a [`Result`] into a -//! [`Result`] of an [`Option`] -//! -//! [`Err(err)`]: Err -//! [`Ok(v)`]: Ok -//! [`Some(v)`]: Some -//! [`ok_or`]: Option::ok_or -//! [`ok_or_else`]: Option::ok_or_else -//! [`transpose`]: Option::transpose -//! -//! These methods transform the [`Some`] variant: -//! -//! * [`filter`] calls the provided predicate function on the contained -//! value `t` if the [`Option`] is [`Some(t)`], and returns [`Some(t)`] -//! if the function returns `true`; otherwise, returns [`None`] -//! * [`flatten`] removes one level of nesting from an -//! [`Option>`] -//! * [`map`] transforms [`Option`] to [`Option`] by applying the -//! provided function to the contained value of [`Some`] and leaving -//! [`None`] values unchanged -//! -//! [`Some(t)`]: Some -//! [`filter`]: Option::filter -//! [`flatten`]: Option::flatten -//! [`map`]: Option::map -//! -//! These methods transform [`Option`] to a value of a possibly -//! different type `U`: -//! -//! * [`map_or`] applies the provided function to the contained value of -//! [`Some`], or returns the provided default value if the [`Option`] is -//! [`None`] -//! * [`map_or_else`] applies the provided function to the contained value -//! of [`Some`], or returns the result of evaluating the provided -//! fallback function if the [`Option`] is [`None`] -//! -//! [`map_or`]: Option::map_or -//! [`map_or_else`]: Option::map_or_else -//! -//! These methods combine the [`Some`] variants of two [`Option`] values: -//! -//! * [`zip`] returns [`Some((s, o))`] if `self` is [`Some(s)`] and the -//! provided [`Option`] value is [`Some(o)`]; otherwise, returns [`None`] -//! * [`zip_with`] calls the provided function `f` and returns -//! [`Some(f(s, o))`] if `self` is [`Some(s)`] and the provided -//! [`Option`] value is [`Some(o)`]; otherwise, returns [`None`] -//! -//! [`Some(f(s, o))`]: Some -//! [`Some(o)`]: Some -//! [`Some(s)`]: Some -//! [`Some((s, o))`]: Some -//! [`zip`]: Option::zip -//! [`zip_with`]: Option::zip_with -//! -//! ## Boolean operators -//! -//! These methods treat the [`Option`] as a boolean value, where [`Some`] -//! acts like [`true`] and [`None`] acts like [`false`]. There are two -//! categories of these methods: ones that take an [`Option`] as input, and -//! ones that take a function as input (to be lazily evaluated). -//! -//! The [`and`], [`or`], and [`xor`] methods take another [`Option`] as -//! input, and produce an [`Option`] as output. Only the [`and`] method can -//! produce an [`Option`] value having a different inner type `U` than -//! [`Option`]. -//! -//! | method | self | input | output | -//! |---------|-----------|-----------|-----------| -//! | [`and`] | `None` | (ignored) | `None` | -//! | [`and`] | `Some(x)` | `None` | `None` | -//! | [`and`] | `Some(x)` | `Some(y)` | `Some(y)` | -//! | [`or`] | `None` | `None` | `None` | -//! | [`or`] | `None` | `Some(y)` | `Some(y)` | -//! | [`or`] | `Some(x)` | (ignored) | `Some(x)` | -//! | [`xor`] | `None` | `None` | `None` | -//! | [`xor`] | `None` | `Some(y)` | `Some(y)` | -//! | [`xor`] | `Some(x)` | `None` | `Some(x)` | -//! | [`xor`] | `Some(x)` | `Some(y)` | `None` | -//! -//! [`and`]: Option::and -//! [`or`]: Option::or -//! [`xor`]: Option::xor -//! -//! The [`and_then`] and [`or_else`] methods take a function as input, and -//! only evaluate the function when they need to produce a new value. Only -//! the [`and_then`] method can produce an [`Option`] value having a -//! different inner type `U` than [`Option`]. -//! -//! | method | self | function input | function result | output | -//! |--------------|-----------|----------------|-----------------|-----------| -//! | [`and_then`] | `None` | (not provided) | (not evaluated) | `None` | -//! | [`and_then`] | `Some(x)` | `x` | `None` | `None` | -//! | [`and_then`] | `Some(x)` | `x` | `Some(y)` | `Some(y)` | -//! | [`or_else`] | `None` | (not provided) | `None` | `None` | -//! | [`or_else`] | `None` | (not provided) | `Some(y)` | `Some(y)` | -//! | [`or_else`] | `Some(x)` | (not provided) | (not evaluated) | `Some(x)` | -//! -//! [`and_then`]: Option::and_then -//! [`or_else`]: Option::or_else -//! -//! This is an example of using methods like [`and_then`] and [`or`] in a -//! pipeline of method calls. Early stages of the pipeline pass failure -//! values ([`None`]) through unchanged, and continue processing on -//! success values ([`Some`]). Toward the end, [`or`] substitutes an error -//! message if it receives [`None`]. -//! -//! ``` -//! # use std::collections::BTreeMap; -//! let mut bt = BTreeMap::new(); -//! bt.insert(20u8, "foo"); -//! bt.insert(42u8, "bar"); -//! let res = [0u8, 1, 11, 200, 22] -//! .into_iter() -//! .map(|x| { -//! // `checked_sub()` returns `None` on error -//! x.checked_sub(1) -//! // same with `checked_mul()` -//! .and_then(|x| x.checked_mul(2)) -//! // `BTreeMap::get` returns `None` on error -//! .and_then(|x| bt.get(&x)) -//! // Substitute an error message if we have `None` so far -//! .or(Some(&"error!")) -//! .copied() -//! // Won't panic because we unconditionally used `Some` above -//! .unwrap() -//! }) -//! .collect::>(); -//! assert_eq!(res, ["error!", "error!", "foo", "error!", "bar"]); -//! ``` -//! -//! ## Comparison operators -//! -//! If `T` implements [`PartialOrd`] then [`Option`] will derive its -//! [`PartialOrd`] implementation. With this order, [`None`] compares as -//! less than any [`Some`], and two [`Some`] compare the same way as their -//! contained values would in `T`. If `T` also implements -//! [`Ord`], then so does [`Option`]. -//! -//! ``` -//! assert!(None < Some(0)); -//! assert!(Some(0) < Some(1)); -//! ``` -//! -//! ## Iterating over `Option` -//! -//! An [`Option`] can be iterated over. This can be helpful if you need an -//! iterator that is conditionally empty. The iterator will either produce -//! a single value (when the [`Option`] is [`Some`]), or produce no values -//! (when the [`Option`] is [`None`]). For example, [`into_iter`] acts like -//! [`once(v)`] if the [`Option`] is [`Some(v)`], and like [`empty()`] if -//! the [`Option`] is [`None`]. -//! -//! [`Some(v)`]: Some -//! [`empty()`]: crate::iter::empty -//! [`once(v)`]: crate::iter::once -//! -//! Iterators over [`Option`] come in three types: -//! -//! * [`into_iter`] consumes the [`Option`] and produces the contained -//! value -//! * [`iter`] produces an immutable reference of type `&T` to the -//! contained value -//! * [`iter_mut`] produces a mutable reference of type `&mut T` to the -//! contained value -//! -//! [`into_iter`]: Option::into_iter -//! [`iter`]: Option::iter -//! [`iter_mut`]: Option::iter_mut -//! -//! An iterator over [`Option`] can be useful when chaining iterators, for -//! example, to conditionally insert items. (It's not always necessary to -//! explicitly call an iterator constructor: many [`Iterator`] methods that -//! accept other iterators will also accept iterable types that implement -//! [`IntoIterator`], which includes [`Option`].) -//! -//! ``` -//! let yep = Some(42); -//! let nope = None; -//! // chain() already calls into_iter(), so we don't have to do so -//! let nums: Vec = (0..4).chain(yep).chain(4..8).collect(); -//! assert_eq!(nums, [0, 1, 2, 3, 42, 4, 5, 6, 7]); -//! let nums: Vec = (0..4).chain(nope).chain(4..8).collect(); -//! assert_eq!(nums, [0, 1, 2, 3, 4, 5, 6, 7]); -//! ``` -//! -//! One reason to chain iterators in this way is that a function returning -//! `impl Iterator` must have all possible return values be of the same -//! concrete type. Chaining an iterated [`Option`] can help with that. -//! -//! ``` -//! fn make_iter(do_insert: bool) -> impl Iterator { -//! // Explicit returns to illustrate return types matching -//! match do_insert { -//! true => return (0..4).chain(Some(42)).chain(4..8), -//! false => return (0..4).chain(None).chain(4..8), -//! } -//! } -//! println!("{:?}", make_iter(true).collect::>()); -//! println!("{:?}", make_iter(false).collect::>()); -//! ``` -//! -//! If we try to do the same thing, but using [`once()`] and [`empty()`], -//! we can't return `impl Iterator` anymore because the concrete types of -//! the return values differ. -//! -//! [`empty()`]: crate::iter::empty -//! [`once()`]: crate::iter::once -//! -//! ```compile_fail,E0308 -//! # use std::iter::{empty, once}; -//! // This won't compile because all possible returns from the function -//! // must have the same concrete type. -//! fn make_iter(do_insert: bool) -> impl Iterator { -//! // Explicit returns to illustrate return types not matching -//! match do_insert { -//! true => return (0..4).chain(once(42)).chain(4..8), -//! false => return (0..4).chain(empty()).chain(4..8), -//! } -//! } -//! ``` -//! -//! ## Collecting into `Option` -//! -//! [`Option`] implements the [`FromIterator`][impl-FromIterator] trait, -//! which allows an iterator over [`Option`] values to be collected into an -//! [`Option`] of a collection of each contained value of the original -//! [`Option`] values, or [`None`] if any of the elements was [`None`]. -//! -//! [impl-FromIterator]: Option#impl-FromIterator%3COption%3CA%3E%3E-for-Option%3CV%3E -//! -//! ``` -//! let v = [Some(2), Some(4), None, Some(8)]; -//! let res: Option> = v.into_iter().collect(); -//! assert_eq!(res, None); -//! let v = [Some(2), Some(4), Some(8)]; -//! let res: Option> = v.into_iter().collect(); -//! assert_eq!(res, Some(vec![2, 4, 8])); -//! ``` -//! -//! [`Option`] also implements the [`Product`][impl-Product] and -//! [`Sum`][impl-Sum] traits, allowing an iterator over [`Option`] values -//! to provide the [`product`][Iterator::product] and -//! [`sum`][Iterator::sum] methods. -//! -//! [impl-Product]: Option#impl-Product%3COption%3CU%3E%3E-for-Option%3CT%3E -//! [impl-Sum]: Option#impl-Sum%3COption%3CU%3E%3E-for-Option%3CT%3E -//! -//! ``` -//! let v = [None, Some(1), Some(2), Some(3)]; -//! let res: Option = v.into_iter().sum(); -//! assert_eq!(res, None); -//! let v = [Some(1), Some(2), Some(21)]; -//! let res: Option = v.into_iter().product(); -//! assert_eq!(res, Some(42)); -//! ``` -//! -//! ## Modifying an [`Option`] in-place -//! -//! These methods return a mutable reference to the contained value of an -//! [`Option`]: -//! -//! * [`insert`] inserts a value, dropping any old contents -//! * [`get_or_insert`] gets the current value, inserting a provided -//! default value if it is [`None`] -//! * [`get_or_insert_default`] gets the current value, inserting the -//! default value of type `T` (which must implement [`Default`]) if it is -//! [`None`] -//! * [`get_or_insert_with`] gets the current value, inserting a default -//! computed by the provided function if it is [`None`] -//! -//! [`get_or_insert`]: Option::get_or_insert -//! [`get_or_insert_default`]: Option::get_or_insert_default -//! [`get_or_insert_with`]: Option::get_or_insert_with -//! [`insert`]: Option::insert -//! -//! These methods transfer ownership of the contained value of an -//! [`Option`]: -//! -//! * [`take`] takes ownership of the contained value of an [`Option`], if -//! any, replacing the [`Option`] with [`None`] -//! * [`replace`] takes ownership of the contained value of an [`Option`], -//! if any, replacing the [`Option`] with a [`Some`] containing the -//! provided value -//! -//! [`replace`]: Option::replace -//! [`take`]: Option::take -//! -//! # Examples -//! -//! Basic pattern matching on [`Option`]: -//! -//! ``` -//! let msg = Some("howdy"); -//! -//! // Take a reference to the contained string -//! if let Some(m) = &msg { -//! println!("{}", *m); -//! } -//! -//! // Remove the contained string, destroying the Option -//! let unwrapped_msg = msg.unwrap_or("default message"); -//! ``` -//! -//! Initialize a result to [`None`] before a loop: -//! -//! ``` -//! enum Kingdom { Plant(u32, &'static str), Animal(u32, &'static str) } -//! -//! // A list of data to search through. -//! let all_the_big_things = [ -//! Kingdom::Plant(250, "redwood"), -//! Kingdom::Plant(230, "noble fir"), -//! Kingdom::Plant(229, "sugar pine"), -//! Kingdom::Animal(25, "blue whale"), -//! Kingdom::Animal(19, "fin whale"), -//! Kingdom::Animal(15, "north pacific right whale"), -//! ]; -//! -//! // We're going to search for the name of the biggest animal, -//! // but to start with we've just got `None`. -//! let mut name_of_biggest_animal = None; -//! let mut size_of_biggest_animal = 0; -//! for big_thing in &all_the_big_things { -//! match *big_thing { -//! Kingdom::Animal(size, name) if size > size_of_biggest_animal => { -//! // Now we've found the name of some big animal -//! size_of_biggest_animal = size; -//! name_of_biggest_animal = Some(name); -//! } -//! Kingdom::Animal(..) | Kingdom::Plant(..) => () -//! } -//! } -//! -//! match name_of_biggest_animal { -//! Some(name) => println!("the biggest animal is {name}"), -//! None => println!("there are no animals :("), -//! } -//! ``` - -#![stable(feature = "rust1", since = "1.0.0")] - -use crate::iter::{self, FusedIterator, TrustedLen}; -use crate::panicking::{panic, panic_display}; -use crate::pin::Pin; -use crate::{ - cmp, convert, hint, mem, - ops::{self, ControlFlow, Deref, DerefMut}, - slice, -}; - -/// The `Option` type. See [the module level documentation](self) for more. -#[derive(Copy, Eq, Debug, Hash)] -#[rustc_diagnostic_item = "Option"] -#[lang = "Option"] -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(clippy::derived_hash_with_manual_eq)] // PartialEq is manually implemented equivalently -pub enum Option { - /// No value. - #[lang = "None"] - #[stable(feature = "rust1", since = "1.0.0")] - None, - /// Some value of type `T`. - #[lang = "Some"] - #[stable(feature = "rust1", since = "1.0.0")] - Some(#[stable(feature = "rust1", since = "1.0.0")] T), -} - -///////////////////////////////////////////////////////////////////////////// -// Type implementation -///////////////////////////////////////////////////////////////////////////// - -impl Option { - ///////////////////////////////////////////////////////////////////////// - // Querying the contained values - ///////////////////////////////////////////////////////////////////////// - - /// Returns `true` if the option is a [`Some`] value. - /// - /// # Examples - /// - /// ``` - /// let x: Option = Some(2); - /// assert_eq!(x.is_some(), true); - /// - /// let x: Option = None; - /// assert_eq!(x.is_some(), false); - /// ``` - #[must_use = "if you intended to assert that this has a value, consider `.unwrap()` instead"] - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_option_basics", since = "1.48.0")] - pub const fn is_some(&self) -> bool { - matches!(*self, Some(_)) - } - - /// Returns `true` if the option is a [`Some`] and the value inside of it matches a predicate. - /// - /// # Examples - /// - /// ``` - /// let x: Option = Some(2); - /// assert_eq!(x.is_some_and(|x| x > 1), true); - /// - /// let x: Option = Some(0); - /// assert_eq!(x.is_some_and(|x| x > 1), false); - /// - /// let x: Option = None; - /// assert_eq!(x.is_some_and(|x| x > 1), false); - /// ``` - #[must_use] - #[inline] - #[stable(feature = "is_some_and", since = "1.70.0")] - pub fn is_some_and(self, f: impl FnOnce(T) -> bool) -> bool { - match self { - None => false, - Some(x) => f(x), - } - } - - /// Returns `true` if the option is a [`None`] value. - /// - /// # Examples - /// - /// ``` - /// let x: Option = Some(2); - /// assert_eq!(x.is_none(), false); - /// - /// let x: Option = None; - /// assert_eq!(x.is_none(), true); - /// ``` - #[must_use = "if you intended to assert that this doesn't have a value, consider \ - wrapping this in an `assert!()` instead"] - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_option_basics", since = "1.48.0")] - pub const fn is_none(&self) -> bool { - !self.is_some() - } - - ///////////////////////////////////////////////////////////////////////// - // Adapter for working with references - ///////////////////////////////////////////////////////////////////////// - - /// Converts from `&Option` to `Option<&T>`. - /// - /// # Examples - /// - /// Calculates the length of an Option<[String]> as an Option<[usize]> - /// without moving the [`String`]. The [`map`] method takes the `self` argument by value, - /// consuming the original, so this technique uses `as_ref` to first take an `Option` to a - /// reference to the value inside the original. - /// - /// [`map`]: Option::map - /// [String]: ../../std/string/struct.String.html "String" - /// [`String`]: ../../std/string/struct.String.html "String" - /// - /// ``` - /// let text: Option = Some("Hello, world!".to_string()); - /// // First, cast `Option` to `Option<&String>` with `as_ref`, - /// // then consume *that* with `map`, leaving `text` on the stack. - /// let text_length: Option = text.as_ref().map(|s| s.len()); - /// println!("still can print text: {text:?}"); - /// ``` - #[inline] - #[rustc_const_stable(feature = "const_option_basics", since = "1.48.0")] - #[stable(feature = "rust1", since = "1.0.0")] - pub const fn as_ref(&self) -> Option<&T> { - match *self { - Some(ref x) => Some(x), - None => None, - } - } - - /// Converts from `&mut Option` to `Option<&mut T>`. - /// - /// # Examples - /// - /// ``` - /// let mut x = Some(2); - /// match x.as_mut() { - /// Some(v) => *v = 42, - /// None => {}, - /// } - /// assert_eq!(x, Some(42)); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_option", issue = "67441")] - pub const fn as_mut(&mut self) -> Option<&mut T> { - match *self { - Some(ref mut x) => Some(x), - None => None, - } - } - - /// Converts from [Pin]<[&]Option\> to Option<[Pin]<[&]T>>. - /// - /// [&]: reference "shared reference" - #[inline] - #[must_use] - #[stable(feature = "pin", since = "1.33.0")] - #[rustc_const_unstable(feature = "const_option_ext", issue = "91930")] - pub const fn as_pin_ref(self: Pin<&Self>) -> Option> { - match Pin::get_ref(self).as_ref() { - // SAFETY: `x` is guaranteed to be pinned because it comes from `self` - // which is pinned. - Some(x) => unsafe { Some(Pin::new_unchecked(x)) }, - None => None, - } - } - - /// Converts from [Pin]<[&mut] Option\> to Option<[Pin]<[&mut] T>>. - /// - /// [&mut]: reference "mutable reference" - #[inline] - #[must_use] - #[stable(feature = "pin", since = "1.33.0")] - #[rustc_const_unstable(feature = "const_option_ext", issue = "91930")] - pub const fn as_pin_mut(self: Pin<&mut Self>) -> Option> { - // SAFETY: `get_unchecked_mut` is never used to move the `Option` inside `self`. - // `x` is guaranteed to be pinned because it comes from `self` which is pinned. - unsafe { - match Pin::get_unchecked_mut(self).as_mut() { - Some(x) => Some(Pin::new_unchecked(x)), - None => None, - } - } - } - - /// Returns a slice of the contained value, if any. If this is `None`, an - /// empty slice is returned. This can be useful to have a single type of - /// iterator over an `Option` or slice. - /// - /// Note: Should you have an `Option<&T>` and wish to get a slice of `T`, - /// you can unpack it via `opt.map_or(&[], std::slice::from_ref)`. - /// - /// # Examples - /// - /// ```rust - /// assert_eq!( - /// [Some(1234).as_slice(), None.as_slice()], - /// [&[1234][..], &[][..]], - /// ); - /// ``` - /// - /// The inverse of this function is (discounting - /// borrowing) [`[_]::first`](slice::first): - /// - /// ```rust - /// for i in [Some(1234_u16), None] { - /// assert_eq!(i.as_ref(), i.as_slice().first()); - /// } - /// ``` - #[inline] - #[must_use] - #[stable(feature = "option_as_slice", since = "1.75.0")] - pub fn as_slice(&self) -> &[T] { - // SAFETY: When the `Option` is `Some`, we're using the actual pointer - // to the payload, with a length of 1, so this is equivalent to - // `slice::from_ref`, and thus is safe. - // When the `Option` is `None`, the length used is 0, so to be safe it - // just needs to be aligned, which it is because `&self` is aligned and - // the offset used is a multiple of alignment. - // - // In the new version, the intrinsic always returns a pointer to an - // in-bounds and correctly aligned position for a `T` (even if in the - // `None` case it's just padding). - unsafe { - slice::from_raw_parts( - (self as *const Self).byte_add(core::mem::offset_of!(Self, Some.0)).cast(), - usize::from(self.is_some()), - ) - } - } - - /// Returns a mutable slice of the contained value, if any. If this is - /// `None`, an empty slice is returned. This can be useful to have a - /// single type of iterator over an `Option` or slice. - /// - /// Note: Should you have an `Option<&mut T>` instead of a - /// `&mut Option`, which this method takes, you can obtain a mutable - /// slice via `opt.map_or(&mut [], std::slice::from_mut)`. - /// - /// # Examples - /// - /// ```rust - /// assert_eq!( - /// [Some(1234).as_mut_slice(), None.as_mut_slice()], - /// [&mut [1234][..], &mut [][..]], - /// ); - /// ``` - /// - /// The result is a mutable slice of zero or one items that points into - /// our original `Option`: - /// - /// ```rust - /// let mut x = Some(1234); - /// x.as_mut_slice()[0] += 1; - /// assert_eq!(x, Some(1235)); - /// ``` - /// - /// The inverse of this method (discounting borrowing) - /// is [`[_]::first_mut`](slice::first_mut): - /// - /// ```rust - /// assert_eq!(Some(123).as_mut_slice().first_mut(), Some(&mut 123)) - /// ``` - #[inline] - #[must_use] - #[stable(feature = "option_as_slice", since = "1.75.0")] - pub fn as_mut_slice(&mut self) -> &mut [T] { - // SAFETY: When the `Option` is `Some`, we're using the actual pointer - // to the payload, with a length of 1, so this is equivalent to - // `slice::from_mut`, and thus is safe. - // When the `Option` is `None`, the length used is 0, so to be safe it - // just needs to be aligned, which it is because `&self` is aligned and - // the offset used is a multiple of alignment. - // - // In the new version, the intrinsic creates a `*const T` from a - // mutable reference so it is safe to cast back to a mutable pointer - // here. As with `as_slice`, the intrinsic always returns a pointer to - // an in-bounds and correctly aligned position for a `T` (even if in - // the `None` case it's just padding). - unsafe { - slice::from_raw_parts_mut( - (self as *mut Self).byte_add(core::mem::offset_of!(Self, Some.0)).cast(), - usize::from(self.is_some()), - ) - } - } - - ///////////////////////////////////////////////////////////////////////// - // Getting to contained values - ///////////////////////////////////////////////////////////////////////// - - /// Returns the contained [`Some`] value, consuming the `self` value. - /// - /// # Panics - /// - /// Panics if the value is a [`None`] with a custom panic message provided by - /// `msg`. - /// - /// # Examples - /// - /// ``` - /// let x = Some("value"); - /// assert_eq!(x.expect("fruits are healthy"), "value"); - /// ``` - /// - /// ```should_panic - /// let x: Option<&str> = None; - /// x.expect("fruits are healthy"); // panics with `fruits are healthy` - /// ``` - /// - /// # Recommended Message Style - /// - /// We recommend that `expect` messages are used to describe the reason you - /// _expect_ the `Option` should be `Some`. - /// - /// ```should_panic - /// # let slice: &[u8] = &[]; - /// let item = slice.get(0) - /// .expect("slice should not be empty"); - /// ``` - /// - /// **Hint**: If you're having trouble remembering how to phrase expect - /// error messages remember to focus on the word "should" as in "env - /// variable should be set by blah" or "the given binary should be available - /// and executable by the current user". - /// - /// For more detail on expect message styles and the reasoning behind our - /// recommendation please refer to the section on ["Common Message - /// Styles"](../../std/error/index.html#common-message-styles) in the [`std::error`](../../std/error/index.html) module docs. - #[inline] - #[track_caller] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_option", issue = "67441")] - pub const fn expect(self, msg: &str) -> T { - match self { - Some(val) => val, - None => expect_failed(msg), - } - } - - /// Returns the contained [`Some`] value, consuming the `self` value. - /// - /// Because this function may panic, its use is generally discouraged. - /// Instead, prefer to use pattern matching and handle the [`None`] - /// case explicitly, or call [`unwrap_or`], [`unwrap_or_else`], or - /// [`unwrap_or_default`]. - /// - /// [`unwrap_or`]: Option::unwrap_or - /// [`unwrap_or_else`]: Option::unwrap_or_else - /// [`unwrap_or_default`]: Option::unwrap_or_default - /// - /// # Panics - /// - /// Panics if the self value equals [`None`]. - /// - /// # Examples - /// - /// ``` - /// let x = Some("air"); - /// assert_eq!(x.unwrap(), "air"); - /// ``` - /// - /// ```should_panic - /// let x: Option<&str> = None; - /// assert_eq!(x.unwrap(), "air"); // fails - /// ``` - #[inline(always)] - #[track_caller] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_option", issue = "67441")] - pub const fn unwrap(self) -> T { - match self { - Some(val) => val, - None => unwrap_failed(), - } - } - - /// Returns the contained [`Some`] value or a provided default. - /// - /// Arguments passed to `unwrap_or` are eagerly evaluated; if you are passing - /// the result of a function call, it is recommended to use [`unwrap_or_else`], - /// which is lazily evaluated. - /// - /// [`unwrap_or_else`]: Option::unwrap_or_else - /// - /// # Examples - /// - /// ``` - /// assert_eq!(Some("car").unwrap_or("bike"), "car"); - /// assert_eq!(None.unwrap_or("bike"), "bike"); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn unwrap_or(self, default: T) -> T { - match self { - Some(x) => x, - None => default, - } - } - - /// Returns the contained [`Some`] value or computes it from a closure. - /// - /// # Examples - /// - /// ``` - /// let k = 10; - /// assert_eq!(Some(4).unwrap_or_else(|| 2 * k), 4); - /// assert_eq!(None.unwrap_or_else(|| 2 * k), 20); - /// ``` - #[inline] - #[track_caller] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn unwrap_or_else(self, f: F) -> T - where - F: FnOnce() -> T, - { - match self { - Some(x) => x, - None => f(), - } - } - - /// Returns the contained [`Some`] value or a default. - /// - /// Consumes the `self` argument then, if [`Some`], returns the contained - /// value, otherwise if [`None`], returns the [default value] for that - /// type. - /// - /// # Examples - /// - /// ``` - /// let x: Option = None; - /// let y: Option = Some(12); - /// - /// assert_eq!(x.unwrap_or_default(), 0); - /// assert_eq!(y.unwrap_or_default(), 12); - /// ``` - /// - /// [default value]: Default::default - /// [`parse`]: str::parse - /// [`FromStr`]: crate::str::FromStr - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn unwrap_or_default(self) -> T - where - T: Default, - { - match self { - Some(x) => x, - None => T::default(), - } - } - - /// Returns the contained [`Some`] value, consuming the `self` value, - /// without checking that the value is not [`None`]. - /// - /// # Safety - /// - /// Calling this method on [`None`] is *[undefined behavior]*. - /// - /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html - /// - /// # Examples - /// - /// ``` - /// let x = Some("air"); - /// assert_eq!(unsafe { x.unwrap_unchecked() }, "air"); - /// ``` - /// - /// ```no_run - /// let x: Option<&str> = None; - /// assert_eq!(unsafe { x.unwrap_unchecked() }, "air"); // Undefined behavior! - /// ``` - #[inline] - #[track_caller] - #[stable(feature = "option_result_unwrap_unchecked", since = "1.58.0")] - #[rustc_const_unstable(feature = "const_option_ext", issue = "91930")] - pub const unsafe fn unwrap_unchecked(self) -> T { - match self { - Some(val) => val, - // SAFETY: the safety contract must be upheld by the caller. - None => unsafe { hint::unreachable_unchecked() }, - } - } - - ///////////////////////////////////////////////////////////////////////// - // Transforming contained values - ///////////////////////////////////////////////////////////////////////// - - /// Maps an `Option` to `Option` by applying a function to a contained value (if `Some`) or returns `None` (if `None`). - /// - /// # Examples - /// - /// Calculates the length of an Option<[String]> as an - /// Option<[usize]>, consuming the original: - /// - /// [String]: ../../std/string/struct.String.html "String" - /// ``` - /// let maybe_some_string = Some(String::from("Hello, World!")); - /// // `Option::map` takes self *by value*, consuming `maybe_some_string` - /// let maybe_some_len = maybe_some_string.map(|s| s.len()); - /// assert_eq!(maybe_some_len, Some(13)); - /// - /// let x: Option<&str> = None; - /// assert_eq!(x.map(|s| s.len()), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn map(self, f: F) -> Option - where - F: FnOnce(T) -> U, - { - match self { - Some(x) => Some(f(x)), - None => None, - } - } - - /// Calls a function with a reference to the contained value if [`Some`]. - /// - /// Returns the original option. - /// - /// # Examples - /// - /// ``` - /// let list = vec![1, 2, 3]; - /// - /// // prints "got: 2" - /// let x = list - /// .get(1) - /// .inspect(|x| println!("got: {x}")) - /// .expect("list should be long enough"); - /// - /// // prints nothing - /// list.get(5).inspect(|x| println!("got: {x}")); - /// ``` - #[inline] - #[stable(feature = "result_option_inspect", since = "1.76.0")] - pub fn inspect(self, f: F) -> Self { - if let Some(ref x) = self { - f(x); - } - - self - } - - /// Returns the provided default result (if none), - /// or applies a function to the contained value (if any). - /// - /// Arguments passed to `map_or` are eagerly evaluated; if you are passing - /// the result of a function call, it is recommended to use [`map_or_else`], - /// which is lazily evaluated. - /// - /// [`map_or_else`]: Option::map_or_else - /// - /// # Examples - /// - /// ``` - /// let x = Some("foo"); - /// assert_eq!(x.map_or(42, |v| v.len()), 3); - /// - /// let x: Option<&str> = None; - /// assert_eq!(x.map_or(42, |v| v.len()), 42); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use = "if you don't need the returned value, use `if let` instead"] - pub fn map_or(self, default: U, f: F) -> U - where - F: FnOnce(T) -> U, - { - match self { - Some(t) => f(t), - None => default, - } - } - - /// Computes a default function result (if none), or - /// applies a different function to the contained value (if any). - /// - /// # Basic examples - /// - /// ``` - /// let k = 21; - /// - /// let x = Some("foo"); - /// assert_eq!(x.map_or_else(|| 2 * k, |v| v.len()), 3); - /// - /// let x: Option<&str> = None; - /// assert_eq!(x.map_or_else(|| 2 * k, |v| v.len()), 42); - /// ``` - /// - /// # Handling a Result-based fallback - /// - /// A somewhat common occurrence when dealing with optional values - /// in combination with [`Result`] is the case where one wants to invoke - /// a fallible fallback if the option is not present. This example - /// parses a command line argument (if present), or the contents of a file to - /// an integer. However, unlike accessing the command line argument, reading - /// the file is fallible, so it must be wrapped with `Ok`. - /// - /// ```no_run - /// # fn main() -> Result<(), Box> { - /// let v: u64 = std::env::args() - /// .nth(1) - /// .map_or_else(|| std::fs::read_to_string("/etc/someconfig.conf"), Ok)? - /// .parse()?; - /// # Ok(()) - /// # } - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn map_or_else(self, default: D, f: F) -> U - where - D: FnOnce() -> U, - F: FnOnce(T) -> U, - { - match self { - Some(t) => f(t), - None => default(), - } - } - - /// Transforms the `Option` into a [`Result`], mapping [`Some(v)`] to - /// [`Ok(v)`] and [`None`] to [`Err(err)`]. - /// - /// Arguments passed to `ok_or` are eagerly evaluated; if you are passing the - /// result of a function call, it is recommended to use [`ok_or_else`], which is - /// lazily evaluated. - /// - /// [`Ok(v)`]: Ok - /// [`Err(err)`]: Err - /// [`Some(v)`]: Some - /// [`ok_or_else`]: Option::ok_or_else - /// - /// # Examples - /// - /// ``` - /// let x = Some("foo"); - /// assert_eq!(x.ok_or(0), Ok("foo")); - /// - /// let x: Option<&str> = None; - /// assert_eq!(x.ok_or(0), Err(0)); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn ok_or(self, err: E) -> Result { - match self { - Some(v) => Ok(v), - None => Err(err), - } - } - - /// Transforms the `Option` into a [`Result`], mapping [`Some(v)`] to - /// [`Ok(v)`] and [`None`] to [`Err(err())`]. - /// - /// [`Ok(v)`]: Ok - /// [`Err(err())`]: Err - /// [`Some(v)`]: Some - /// - /// # Examples - /// - /// ``` - /// let x = Some("foo"); - /// assert_eq!(x.ok_or_else(|| 0), Ok("foo")); - /// - /// let x: Option<&str> = None; - /// assert_eq!(x.ok_or_else(|| 0), Err(0)); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn ok_or_else(self, err: F) -> Result - where - F: FnOnce() -> E, - { - match self { - Some(v) => Ok(v), - None => Err(err()), - } - } - - /// Converts from `Option` (or `&Option`) to `Option<&T::Target>`. - /// - /// Leaves the original Option in-place, creating a new one with a reference - /// to the original one, additionally coercing the contents via [`Deref`]. - /// - /// # Examples - /// - /// ``` - /// let x: Option = Some("hey".to_owned()); - /// assert_eq!(x.as_deref(), Some("hey")); - /// - /// let x: Option = None; - /// assert_eq!(x.as_deref(), None); - /// ``` - #[inline] - #[stable(feature = "option_deref", since = "1.40.0")] - pub fn as_deref(&self) -> Option<&T::Target> - where - T: Deref, - { - match self.as_ref() { - Some(t) => Some(t.deref()), - None => None, - } - } - - /// Converts from `Option` (or `&mut Option`) to `Option<&mut T::Target>`. - /// - /// Leaves the original `Option` in-place, creating a new one containing a mutable reference to - /// the inner type's [`Deref::Target`] type. - /// - /// # Examples - /// - /// ``` - /// let mut x: Option = Some("hey".to_owned()); - /// assert_eq!(x.as_deref_mut().map(|x| { - /// x.make_ascii_uppercase(); - /// x - /// }), Some("HEY".to_owned().as_mut_str())); - /// ``` - #[inline] - #[stable(feature = "option_deref", since = "1.40.0")] - pub fn as_deref_mut(&mut self) -> Option<&mut T::Target> - where - T: DerefMut, - { - match self.as_mut() { - Some(t) => Some(t.deref_mut()), - None => None, - } - } - - ///////////////////////////////////////////////////////////////////////// - // Iterator constructors - ///////////////////////////////////////////////////////////////////////// - - /// Returns an iterator over the possibly contained value. - /// - /// # Examples - /// - /// ``` - /// let x = Some(4); - /// assert_eq!(x.iter().next(), Some(&4)); - /// - /// let x: Option = None; - /// assert_eq!(x.iter().next(), None); - /// ``` - #[inline] - #[rustc_const_unstable(feature = "const_option", issue = "67441")] - #[stable(feature = "rust1", since = "1.0.0")] - pub const fn iter(&self) -> Iter<'_, T> { - Iter { inner: Item { opt: self.as_ref() } } - } - - /// Returns a mutable iterator over the possibly contained value. - /// - /// # Examples - /// - /// ``` - /// let mut x = Some(4); - /// match x.iter_mut().next() { - /// Some(v) => *v = 42, - /// None => {}, - /// } - /// assert_eq!(x, Some(42)); - /// - /// let mut x: Option = None; - /// assert_eq!(x.iter_mut().next(), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn iter_mut(&mut self) -> IterMut<'_, T> { - IterMut { inner: Item { opt: self.as_mut() } } - } - - ///////////////////////////////////////////////////////////////////////// - // Boolean operations on the values, eager and lazy - ///////////////////////////////////////////////////////////////////////// - - /// Returns [`None`] if the option is [`None`], otherwise returns `optb`. - /// - /// Arguments passed to `and` are eagerly evaluated; if you are passing the - /// result of a function call, it is recommended to use [`and_then`], which is - /// lazily evaluated. - /// - /// [`and_then`]: Option::and_then - /// - /// # Examples - /// - /// ``` - /// let x = Some(2); - /// let y: Option<&str> = None; - /// assert_eq!(x.and(y), None); - /// - /// let x: Option = None; - /// let y = Some("foo"); - /// assert_eq!(x.and(y), None); - /// - /// let x = Some(2); - /// let y = Some("foo"); - /// assert_eq!(x.and(y), Some("foo")); - /// - /// let x: Option = None; - /// let y: Option<&str> = None; - /// assert_eq!(x.and(y), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn and(self, optb: Option) -> Option { - match self { - Some(_) => optb, - None => None, - } - } - - /// Returns [`None`] if the option is [`None`], otherwise calls `f` with the - /// wrapped value and returns the result. - /// - /// Some languages call this operation flatmap. - /// - /// # Examples - /// - /// ``` - /// fn sq_then_to_string(x: u32) -> Option { - /// x.checked_mul(x).map(|sq| sq.to_string()) - /// } - /// - /// assert_eq!(Some(2).and_then(sq_then_to_string), Some(4.to_string())); - /// assert_eq!(Some(1_000_000).and_then(sq_then_to_string), None); // overflowed! - /// assert_eq!(None.and_then(sq_then_to_string), None); - /// ``` - /// - /// Often used to chain fallible operations that may return [`None`]. - /// - /// ``` - /// let arr_2d = [["A0", "A1"], ["B0", "B1"]]; - /// - /// let item_0_1 = arr_2d.get(0).and_then(|row| row.get(1)); - /// assert_eq!(item_0_1, Some(&"A1")); - /// - /// let item_2_0 = arr_2d.get(2).and_then(|row| row.get(0)); - /// assert_eq!(item_2_0, None); - /// ``` - #[doc(alias = "flatmap")] - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("flat_map", "flatmap")] - pub fn and_then(self, f: F) -> Option - where - F: FnOnce(T) -> Option, - { - match self { - Some(x) => f(x), - None => None, - } - } - - /// Returns [`None`] if the option is [`None`], otherwise calls `predicate` - /// with the wrapped value and returns: - /// - /// - [`Some(t)`] if `predicate` returns `true` (where `t` is the wrapped - /// value), and - /// - [`None`] if `predicate` returns `false`. - /// - /// This function works similar to [`Iterator::filter()`]. You can imagine - /// the `Option` being an iterator over one or zero elements. `filter()` - /// lets you decide which elements to keep. - /// - /// # Examples - /// - /// ```rust - /// fn is_even(n: &i32) -> bool { - /// n % 2 == 0 - /// } - /// - /// assert_eq!(None.filter(is_even), None); - /// assert_eq!(Some(3).filter(is_even), None); - /// assert_eq!(Some(4).filter(is_even), Some(4)); - /// ``` - /// - /// [`Some(t)`]: Some - #[inline] - #[stable(feature = "option_filter", since = "1.27.0")] - pub fn filter

(self, predicate: P) -> Self - where - P: FnOnce(&T) -> bool, - { - if let Some(x) = self { - if predicate(&x) { - return Some(x); - } - } - None - } - - /// Returns the option if it contains a value, otherwise returns `optb`. - /// - /// Arguments passed to `or` are eagerly evaluated; if you are passing the - /// result of a function call, it is recommended to use [`or_else`], which is - /// lazily evaluated. - /// - /// [`or_else`]: Option::or_else - /// - /// # Examples - /// - /// ``` - /// let x = Some(2); - /// let y = None; - /// assert_eq!(x.or(y), Some(2)); - /// - /// let x = None; - /// let y = Some(100); - /// assert_eq!(x.or(y), Some(100)); - /// - /// let x = Some(2); - /// let y = Some(100); - /// assert_eq!(x.or(y), Some(2)); - /// - /// let x: Option = None; - /// let y = None; - /// assert_eq!(x.or(y), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn or(self, optb: Option) -> Option { - match self { - x @ Some(_) => x, - None => optb, - } - } - - /// Returns the option if it contains a value, otherwise calls `f` and - /// returns the result. - /// - /// # Examples - /// - /// ``` - /// fn nobody() -> Option<&'static str> { None } - /// fn vikings() -> Option<&'static str> { Some("vikings") } - /// - /// assert_eq!(Some("barbarians").or_else(vikings), Some("barbarians")); - /// assert_eq!(None.or_else(vikings), Some("vikings")); - /// assert_eq!(None.or_else(nobody), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn or_else(self, f: F) -> Option - where - F: FnOnce() -> Option, - { - match self { - x @ Some(_) => x, - None => f(), - } - } - - /// Returns [`Some`] if exactly one of `self`, `optb` is [`Some`], otherwise returns [`None`]. - /// - /// # Examples - /// - /// ``` - /// let x = Some(2); - /// let y: Option = None; - /// assert_eq!(x.xor(y), Some(2)); - /// - /// let x: Option = None; - /// let y = Some(2); - /// assert_eq!(x.xor(y), Some(2)); - /// - /// let x = Some(2); - /// let y = Some(2); - /// assert_eq!(x.xor(y), None); - /// - /// let x: Option = None; - /// let y: Option = None; - /// assert_eq!(x.xor(y), None); - /// ``` - #[inline] - #[stable(feature = "option_xor", since = "1.37.0")] - pub fn xor(self, optb: Option) -> Option { - match (self, optb) { - (a @ Some(_), None) => a, - (None, b @ Some(_)) => b, - _ => None, - } - } - - ///////////////////////////////////////////////////////////////////////// - // Entry-like operations to insert a value and return a reference - ///////////////////////////////////////////////////////////////////////// - - /// Inserts `value` into the option, then returns a mutable reference to it. - /// - /// If the option already contains a value, the old value is dropped. - /// - /// See also [`Option::get_or_insert`], which doesn't update the value if - /// the option already contains [`Some`]. - /// - /// # Example - /// - /// ``` - /// let mut opt = None; - /// let val = opt.insert(1); - /// assert_eq!(*val, 1); - /// assert_eq!(opt.unwrap(), 1); - /// let val = opt.insert(2); - /// assert_eq!(*val, 2); - /// *val = 3; - /// assert_eq!(opt.unwrap(), 3); - /// ``` - #[must_use = "if you intended to set a value, consider assignment instead"] - #[inline] - #[stable(feature = "option_insert", since = "1.53.0")] - pub fn insert(&mut self, value: T) -> &mut T { - *self = Some(value); - - // SAFETY: the code above just filled the option - unsafe { self.as_mut().unwrap_unchecked() } - } - - /// Inserts `value` into the option if it is [`None`], then - /// returns a mutable reference to the contained value. - /// - /// See also [`Option::insert`], which updates the value even if - /// the option already contains [`Some`]. - /// - /// # Examples - /// - /// ``` - /// let mut x = None; - /// - /// { - /// let y: &mut u32 = x.get_or_insert(5); - /// assert_eq!(y, &5); - /// - /// *y = 7; - /// } - /// - /// assert_eq!(x, Some(7)); - /// ``` - #[inline] - #[stable(feature = "option_entry", since = "1.20.0")] - pub fn get_or_insert(&mut self, value: T) -> &mut T { - if let None = *self { - *self = Some(value); - } - - // SAFETY: a `None` variant for `self` would have been replaced by a `Some` - // variant in the code above. - unsafe { self.as_mut().unwrap_unchecked() } - } - - /// Inserts the default value into the option if it is [`None`], then - /// returns a mutable reference to the contained value. - /// - /// # Examples - /// - /// ``` - /// #![feature(option_get_or_insert_default)] - /// - /// let mut x = None; - /// - /// { - /// let y: &mut u32 = x.get_or_insert_default(); - /// assert_eq!(y, &0); - /// - /// *y = 7; - /// } - /// - /// assert_eq!(x, Some(7)); - /// ``` - #[inline] - #[unstable(feature = "option_get_or_insert_default", issue = "82901")] - pub fn get_or_insert_default(&mut self) -> &mut T - where - T: Default, - { - self.get_or_insert_with(T::default) - } - - /// Inserts a value computed from `f` into the option if it is [`None`], - /// then returns a mutable reference to the contained value. - /// - /// # Examples - /// - /// ``` - /// let mut x = None; - /// - /// { - /// let y: &mut u32 = x.get_or_insert_with(|| 5); - /// assert_eq!(y, &5); - /// - /// *y = 7; - /// } - /// - /// assert_eq!(x, Some(7)); - /// ``` - #[inline] - #[stable(feature = "option_entry", since = "1.20.0")] - pub fn get_or_insert_with(&mut self, f: F) -> &mut T - where - F: FnOnce() -> T, - { - if let None = self { - *self = Some(f()); - } - - // SAFETY: a `None` variant for `self` would have been replaced by a `Some` - // variant in the code above. - unsafe { self.as_mut().unwrap_unchecked() } - } - - ///////////////////////////////////////////////////////////////////////// - // Misc - ///////////////////////////////////////////////////////////////////////// - - /// Takes the value out of the option, leaving a [`None`] in its place. - /// - /// # Examples - /// - /// ``` - /// let mut x = Some(2); - /// let y = x.take(); - /// assert_eq!(x, None); - /// assert_eq!(y, Some(2)); - /// - /// let mut x: Option = None; - /// let y = x.take(); - /// assert_eq!(x, None); - /// assert_eq!(y, None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_option", issue = "67441")] - pub const fn take(&mut self) -> Option { - // FIXME replace `mem::replace` by `mem::take` when the latter is const ready - mem::replace(self, None) - } - - /// Takes the value out of the option, but only if the predicate evaluates to - /// `true` on a mutable reference to the value. - /// - /// In other words, replaces `self` with `None` if the predicate returns `true`. - /// This method operates similar to [`Option::take`] but conditional. - /// - /// # Examples - /// - /// ``` - /// #![feature(option_take_if)] - /// - /// let mut x = Some(42); - /// - /// let prev = x.take_if(|v| if *v == 42 { - /// *v += 1; - /// false - /// } else { - /// false - /// }); - /// assert_eq!(x, Some(43)); - /// assert_eq!(prev, None); - /// - /// let prev = x.take_if(|v| *v == 43); - /// assert_eq!(x, None); - /// assert_eq!(prev, Some(43)); - /// ``` - #[inline] - #[unstable(feature = "option_take_if", issue = "98934")] - pub fn take_if

(&mut self, predicate: P) -> Option - where - P: FnOnce(&mut T) -> bool, - { - if self.as_mut().map_or(false, predicate) { self.take() } else { None } - } - - /// Replaces the actual value in the option by the value given in parameter, - /// returning the old value if present, - /// leaving a [`Some`] in its place without deinitializing either one. - /// - /// # Examples - /// - /// ``` - /// let mut x = Some(2); - /// let old = x.replace(5); - /// assert_eq!(x, Some(5)); - /// assert_eq!(old, Some(2)); - /// - /// let mut x = None; - /// let old = x.replace(3); - /// assert_eq!(x, Some(3)); - /// assert_eq!(old, None); - /// ``` - #[inline] - #[rustc_const_unstable(feature = "const_option", issue = "67441")] - #[stable(feature = "option_replace", since = "1.31.0")] - pub const fn replace(&mut self, value: T) -> Option { - mem::replace(self, Some(value)) - } - - /// Zips `self` with another `Option`. - /// - /// If `self` is `Some(s)` and `other` is `Some(o)`, this method returns `Some((s, o))`. - /// Otherwise, `None` is returned. - /// - /// # Examples - /// - /// ``` - /// let x = Some(1); - /// let y = Some("hi"); - /// let z = None::; - /// - /// assert_eq!(x.zip(y), Some((1, "hi"))); - /// assert_eq!(x.zip(z), None); - /// ``` - #[stable(feature = "option_zip_option", since = "1.46.0")] - pub fn zip(self, other: Option) -> Option<(T, U)> { - match (self, other) { - (Some(a), Some(b)) => Some((a, b)), - _ => None, - } - } - - /// Zips `self` and another `Option` with function `f`. - /// - /// If `self` is `Some(s)` and `other` is `Some(o)`, this method returns `Some(f(s, o))`. - /// Otherwise, `None` is returned. - /// - /// # Examples - /// - /// ``` - /// #![feature(option_zip)] - /// - /// #[derive(Debug, PartialEq)] - /// struct Point { - /// x: f64, - /// y: f64, - /// } - /// - /// impl Point { - /// fn new(x: f64, y: f64) -> Self { - /// Self { x, y } - /// } - /// } - /// - /// let x = Some(17.5); - /// let y = Some(42.7); - /// - /// assert_eq!(x.zip_with(y, Point::new), Some(Point { x: 17.5, y: 42.7 })); - /// assert_eq!(x.zip_with(None, Point::new), None); - /// ``` - #[unstable(feature = "option_zip", issue = "70086")] - pub fn zip_with(self, other: Option, f: F) -> Option - where - F: FnOnce(T, U) -> R, - { - match (self, other) { - (Some(a), Some(b)) => Some(f(a, b)), - _ => None, - } - } -} - -impl Option<(T, U)> { - /// Unzips an option containing a tuple of two options. - /// - /// If `self` is `Some((a, b))` this method returns `(Some(a), Some(b))`. - /// Otherwise, `(None, None)` is returned. - /// - /// # Examples - /// - /// ``` - /// let x = Some((1, "hi")); - /// let y = None::<(u8, u32)>; - /// - /// assert_eq!(x.unzip(), (Some(1), Some("hi"))); - /// assert_eq!(y.unzip(), (None, None)); - /// ``` - #[inline] - #[stable(feature = "unzip_option", since = "1.66.0")] - pub fn unzip(self) -> (Option, Option) { - match self { - Some((a, b)) => (Some(a), Some(b)), - None => (None, None), - } - } -} - -impl Option<&T> { - /// Maps an `Option<&T>` to an `Option` by copying the contents of the - /// option. - /// - /// # Examples - /// - /// ``` - /// let x = 12; - /// let opt_x = Some(&x); - /// assert_eq!(opt_x, Some(&12)); - /// let copied = opt_x.copied(); - /// assert_eq!(copied, Some(12)); - /// ``` - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "copied", since = "1.35.0")] - #[rustc_const_unstable(feature = "const_option", issue = "67441")] - pub const fn copied(self) -> Option - where - T: Copy, - { - // FIXME: this implementation, which sidesteps using `Option::map` since it's not const - // ready yet, should be reverted when possible to avoid code repetition - match self { - Some(&v) => Some(v), - None => None, - } - } - - /// Maps an `Option<&T>` to an `Option` by cloning the contents of the - /// option. - /// - /// # Examples - /// - /// ``` - /// let x = 12; - /// let opt_x = Some(&x); - /// assert_eq!(opt_x, Some(&12)); - /// let cloned = opt_x.cloned(); - /// assert_eq!(cloned, Some(12)); - /// ``` - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn cloned(self) -> Option - where - T: Clone, - { - match self { - Some(t) => Some(t.clone()), - None => None, - } - } -} - -impl Option<&mut T> { - /// Maps an `Option<&mut T>` to an `Option` by copying the contents of the - /// option. - /// - /// # Examples - /// - /// ``` - /// let mut x = 12; - /// let opt_x = Some(&mut x); - /// assert_eq!(opt_x, Some(&mut 12)); - /// let copied = opt_x.copied(); - /// assert_eq!(copied, Some(12)); - /// ``` - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "copied", since = "1.35.0")] - #[rustc_const_unstable(feature = "const_option_ext", issue = "91930")] - pub const fn copied(self) -> Option - where - T: Copy, - { - match self { - Some(&mut t) => Some(t), - None => None, - } - } - - /// Maps an `Option<&mut T>` to an `Option` by cloning the contents of the - /// option. - /// - /// # Examples - /// - /// ``` - /// let mut x = 12; - /// let opt_x = Some(&mut x); - /// assert_eq!(opt_x, Some(&mut 12)); - /// let cloned = opt_x.cloned(); - /// assert_eq!(cloned, Some(12)); - /// ``` - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(since = "1.26.0", feature = "option_ref_mut_cloned")] - pub fn cloned(self) -> Option - where - T: Clone, - { - match self { - Some(t) => Some(t.clone()), - None => None, - } - } -} - -impl Option> { - /// Transposes an `Option` of a [`Result`] into a [`Result`] of an `Option`. - /// - /// [`None`] will be mapped to [Ok]\([None]). - /// [Some]\([Ok]\(\_)) and [Some]\([Err]\(\_)) will be mapped to - /// [Ok]\([Some]\(\_)) and [Err]\(\_). - /// - /// # Examples - /// - /// ``` - /// #[derive(Debug, Eq, PartialEq)] - /// struct SomeErr; - /// - /// let x: Result, SomeErr> = Ok(Some(5)); - /// let y: Option> = Some(Ok(5)); - /// assert_eq!(x, y.transpose()); - /// ``` - #[inline] - #[stable(feature = "transpose_result", since = "1.33.0")] - #[rustc_const_unstable(feature = "const_option", issue = "67441")] - pub const fn transpose(self) -> Result, E> { - match self { - Some(Ok(x)) => Ok(Some(x)), - Some(Err(e)) => Err(e), - None => Ok(None), - } - } -} - -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never))] -#[cfg_attr(feature = "panic_immediate_abort", inline)] -#[cold] -#[track_caller] -const fn unwrap_failed() -> ! { - panic("called `Option::unwrap()` on a `None` value") -} - -// This is a separate function to reduce the code size of .expect() itself. -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never))] -#[cfg_attr(feature = "panic_immediate_abort", inline)] -#[cold] -#[track_caller] -#[rustc_const_unstable(feature = "const_option", issue = "67441")] -const fn expect_failed(msg: &str) -> ! { - panic_display(&msg) -} - -///////////////////////////////////////////////////////////////////////////// -// Trait implementations -///////////////////////////////////////////////////////////////////////////// - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Option -where - T: Clone, -{ - #[inline] - fn clone(&self) -> Self { - match self { - Some(x) => Some(x.clone()), - None => None, - } - } - - #[inline] - fn clone_from(&mut self, source: &Self) { - match (self, source) { - (Some(to), Some(from)) => to.clone_from(from), - (to, from) => *to = from.clone(), - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Default for Option { - /// Returns [`None`][Option::None]. - /// - /// # Examples - /// - /// ``` - /// let opt: Option = Option::default(); - /// assert!(opt.is_none()); - /// ``` - #[inline] - fn default() -> Option { - None - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl IntoIterator for Option { - type Item = T; - type IntoIter = IntoIter; - - /// Returns a consuming iterator over the possibly contained value. - /// - /// # Examples - /// - /// ``` - /// let x = Some("string"); - /// let v: Vec<&str> = x.into_iter().collect(); - /// assert_eq!(v, ["string"]); - /// - /// let x = None; - /// let v: Vec<&str> = x.into_iter().collect(); - /// assert!(v.is_empty()); - /// ``` - #[inline] - fn into_iter(self) -> IntoIter { - IntoIter { inner: Item { opt: self } } - } -} - -#[stable(since = "1.4.0", feature = "option_iter")] -impl<'a, T> IntoIterator for &'a Option { - type Item = &'a T; - type IntoIter = Iter<'a, T>; - - fn into_iter(self) -> Iter<'a, T> { - self.iter() - } -} - -#[stable(since = "1.4.0", feature = "option_iter")] -impl<'a, T> IntoIterator for &'a mut Option { - type Item = &'a mut T; - type IntoIter = IterMut<'a, T>; - - fn into_iter(self) -> IterMut<'a, T> { - self.iter_mut() - } -} - -#[stable(since = "1.12.0", feature = "option_from")] -impl From for Option { - /// Moves `val` into a new [`Some`]. - /// - /// # Examples - /// - /// ``` - /// let o: Option = Option::from(67); - /// - /// assert_eq!(Some(67), o); - /// ``` - fn from(val: T) -> Option { - Some(val) - } -} - -#[stable(feature = "option_ref_from_ref_option", since = "1.30.0")] -impl<'a, T> From<&'a Option> for Option<&'a T> { - /// Converts from `&Option` to `Option<&T>`. - /// - /// # Examples - /// - /// Converts an [Option]<[String]> into an [Option]<[usize]>, preserving - /// the original. The [`map`] method takes the `self` argument by value, consuming the original, - /// so this technique uses `from` to first take an [`Option`] to a reference - /// to the value inside the original. - /// - /// [`map`]: Option::map - /// [String]: ../../std/string/struct.String.html "String" - /// - /// ``` - /// let s: Option = Some(String::from("Hello, Rustaceans!")); - /// let o: Option = Option::from(&s).map(|ss: &String| ss.len()); - /// - /// println!("Can still print s: {s:?}"); - /// - /// assert_eq!(o, Some(18)); - /// ``` - fn from(o: &'a Option) -> Option<&'a T> { - o.as_ref() - } -} - -#[stable(feature = "option_ref_from_ref_option", since = "1.30.0")] -impl<'a, T> From<&'a mut Option> for Option<&'a mut T> { - /// Converts from `&mut Option` to `Option<&mut T>` - /// - /// # Examples - /// - /// ``` - /// let mut s = Some(String::from("Hello")); - /// let o: Option<&mut String> = Option::from(&mut s); - /// - /// match o { - /// Some(t) => *t = String::from("Hello, Rustaceans!"), - /// None => (), - /// } - /// - /// assert_eq!(s, Some(String::from("Hello, Rustaceans!"))); - /// ``` - fn from(o: &'a mut Option) -> Option<&'a mut T> { - o.as_mut() - } -} - -// Ideally, LLVM should be able to optimize our derive code to this. -// Once https://github.com/llvm/llvm-project/issues/52622 is fixed, we can -// go back to deriving `PartialEq`. -#[stable(feature = "rust1", since = "1.0.0")] -impl crate::marker::StructuralPartialEq for Option {} -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for Option { - #[inline] - fn eq(&self, other: &Self) -> bool { - // Spelling out the cases explicitly optimizes better than - // `_ => false` - match (self, other) { - (Some(l), Some(r)) => *l == *r, - (Some(_), None) => false, - (None, Some(_)) => false, - (None, None) => true, - } - } -} - -// Manually implementing here somewhat improves codegen for -// https://github.com/rust-lang/rust/issues/49892, although still -// not optimal. -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialOrd for Option { - #[inline] - fn partial_cmp(&self, other: &Self) -> Option { - match (self, other) { - (Some(l), Some(r)) => l.partial_cmp(r), - (Some(_), None) => Some(cmp::Ordering::Greater), - (None, Some(_)) => Some(cmp::Ordering::Less), - (None, None) => Some(cmp::Ordering::Equal), - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for Option { - #[inline] - fn cmp(&self, other: &Self) -> cmp::Ordering { - match (self, other) { - (Some(l), Some(r)) => l.cmp(r), - (Some(_), None) => cmp::Ordering::Greater, - (None, Some(_)) => cmp::Ordering::Less, - (None, None) => cmp::Ordering::Equal, - } - } -} - -///////////////////////////////////////////////////////////////////////////// -// The Option Iterators -///////////////////////////////////////////////////////////////////////////// - -#[derive(Clone, Debug)] -struct Item { - opt: Option, -} - -impl Iterator for Item { - type Item = A; - - #[inline] - fn next(&mut self) -> Option { - self.opt.take() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - match self.opt { - Some(_) => (1, Some(1)), - None => (0, Some(0)), - } - } -} - -impl DoubleEndedIterator for Item { - #[inline] - fn next_back(&mut self) -> Option { - self.opt.take() - } -} - -impl ExactSizeIterator for Item {} -impl FusedIterator for Item {} -unsafe impl TrustedLen for Item {} - -/// An iterator over a reference to the [`Some`] variant of an [`Option`]. -/// -/// The iterator yields one value if the [`Option`] is a [`Some`], otherwise none. -/// -/// This `struct` is created by the [`Option::iter`] function. -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Debug)] -pub struct Iter<'a, A: 'a> { - inner: Item<&'a A>, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, A> Iterator for Iter<'a, A> { - type Item = &'a A; - - #[inline] - fn next(&mut self) -> Option<&'a A> { - self.inner.next() - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, A> DoubleEndedIterator for Iter<'a, A> { - #[inline] - fn next_back(&mut self) -> Option<&'a A> { - self.inner.next_back() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Iter<'_, A> {} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Iter<'_, A> {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for Iter<'_, A> {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Iter<'_, A> { - #[inline] - fn clone(&self) -> Self { - Iter { inner: self.inner.clone() } - } -} - -/// An iterator over a mutable reference to the [`Some`] variant of an [`Option`]. -/// -/// The iterator yields one value if the [`Option`] is a [`Some`], otherwise none. -/// -/// This `struct` is created by the [`Option::iter_mut`] function. -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Debug)] -pub struct IterMut<'a, A: 'a> { - inner: Item<&'a mut A>, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, A> Iterator for IterMut<'a, A> { - type Item = &'a mut A; - - #[inline] - fn next(&mut self) -> Option<&'a mut A> { - self.inner.next() - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, A> DoubleEndedIterator for IterMut<'a, A> { - #[inline] - fn next_back(&mut self) -> Option<&'a mut A> { - self.inner.next_back() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for IterMut<'_, A> {} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for IterMut<'_, A> {} -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for IterMut<'_, A> {} - -/// An iterator over the value in [`Some`] variant of an [`Option`]. -/// -/// The iterator yields one value if the [`Option`] is a [`Some`], otherwise none. -/// -/// This `struct` is created by the [`Option::into_iter`] function. -#[derive(Clone, Debug)] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct IntoIter { - inner: Item, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for IntoIter { - type Item = A; - - #[inline] - fn next(&mut self) -> Option { - self.inner.next() - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DoubleEndedIterator for IntoIter { - #[inline] - fn next_back(&mut self) -> Option { - self.inner.next_back() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for IntoIter {} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for IntoIter {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for IntoIter {} - -///////////////////////////////////////////////////////////////////////////// -// FromIterator -///////////////////////////////////////////////////////////////////////////// - -#[stable(feature = "rust1", since = "1.0.0")] -impl> FromIterator> for Option { - /// Takes each element in the [`Iterator`]: if it is [`None`][Option::None], - /// no further elements are taken, and the [`None`][Option::None] is - /// returned. Should no [`None`][Option::None] occur, a container of type - /// `V` containing the values of each [`Option`] is returned. - /// - /// # Examples - /// - /// Here is an example which increments every integer in a vector. - /// We use the checked variant of `add` that returns `None` when the - /// calculation would result in an overflow. - /// - /// ``` - /// let items = vec![0_u16, 1, 2]; - /// - /// let res: Option> = items - /// .iter() - /// .map(|x| x.checked_add(1)) - /// .collect(); - /// - /// assert_eq!(res, Some(vec![1, 2, 3])); - /// ``` - /// - /// As you can see, this will return the expected, valid items. - /// - /// Here is another example that tries to subtract one from another list - /// of integers, this time checking for underflow: - /// - /// ``` - /// let items = vec![2_u16, 1, 0]; - /// - /// let res: Option> = items - /// .iter() - /// .map(|x| x.checked_sub(1)) - /// .collect(); - /// - /// assert_eq!(res, None); - /// ``` - /// - /// Since the last element is zero, it would underflow. Thus, the resulting - /// value is `None`. - /// - /// Here is a variation on the previous example, showing that no - /// further elements are taken from `iter` after the first `None`. - /// - /// ``` - /// let items = vec![3_u16, 2, 1, 10]; - /// - /// let mut shared = 0; - /// - /// let res: Option> = items - /// .iter() - /// .map(|x| { shared += x; x.checked_sub(2) }) - /// .collect(); - /// - /// assert_eq!(res, None); - /// assert_eq!(shared, 6); - /// ``` - /// - /// Since the third element caused an underflow, no further elements were taken, - /// so the final value of `shared` is 6 (= `3 + 2 + 1`), not 16. - #[inline] - fn from_iter>>(iter: I) -> Option { - // FIXME(#11084): This could be replaced with Iterator::scan when this - // performance bug is closed. - - iter::try_process(iter.into_iter(), |i| i.collect()) - } -} - -#[unstable(feature = "try_trait_v2", issue = "84277")] -impl ops::Try for Option { - type Output = T; - type Residual = Option; - - #[inline] - fn from_output(output: Self::Output) -> Self { - Some(output) - } - - #[inline] - fn branch(self) -> ControlFlow { - match self { - Some(v) => ControlFlow::Continue(v), - None => ControlFlow::Break(None), - } - } -} - -#[unstable(feature = "try_trait_v2", issue = "84277")] -impl ops::FromResidual for Option { - #[inline] - fn from_residual(residual: Option) -> Self { - match residual { - None => None, - } - } -} - -#[unstable(feature = "try_trait_v2_yeet", issue = "96374")] -impl ops::FromResidual> for Option { - #[inline] - fn from_residual(ops::Yeet(()): ops::Yeet<()>) -> Self { - None - } -} - -#[unstable(feature = "try_trait_v2_residual", issue = "91285")] -impl ops::Residual for Option { - type TryType = Option; -} - -impl Option> { - /// Converts from `Option>` to `Option`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let x: Option> = Some(Some(6)); - /// assert_eq!(Some(6), x.flatten()); - /// - /// let x: Option> = Some(None); - /// assert_eq!(None, x.flatten()); - /// - /// let x: Option> = None; - /// assert_eq!(None, x.flatten()); - /// ``` - /// - /// Flattening only removes one level of nesting at a time: - /// - /// ``` - /// let x: Option>> = Some(Some(Some(6))); - /// assert_eq!(Some(Some(6)), x.flatten()); - /// assert_eq!(Some(6), x.flatten().flatten()); - /// ``` - #[inline] - #[stable(feature = "option_flattening", since = "1.40.0")] - #[rustc_const_unstable(feature = "const_option", issue = "67441")] - pub const fn flatten(self) -> Option { - match self { - Some(inner) => inner, - None => None, - } - } -} diff --git a/library/core/src/panic.rs b/library/core/src/panic.rs deleted file mode 100644 index 8771f40f9b42b..0000000000000 --- a/library/core/src/panic.rs +++ /dev/null @@ -1,160 +0,0 @@ -//! Panic support in the standard library. - -#![stable(feature = "core_panic_info", since = "1.41.0")] - -mod location; -mod panic_info; -mod unwind_safe; - -use crate::any::Any; - -#[stable(feature = "panic_hooks", since = "1.10.0")] -pub use self::location::Location; -#[stable(feature = "panic_hooks", since = "1.10.0")] -pub use self::panic_info::PanicInfo; -#[stable(feature = "catch_unwind", since = "1.9.0")] -pub use self::unwind_safe::{AssertUnwindSafe, RefUnwindSafe, UnwindSafe}; - -#[doc(hidden)] -#[unstable(feature = "edition_panic", issue = "none", reason = "use panic!() instead")] -#[allow_internal_unstable(panic_internals, const_format_args)] -#[rustc_diagnostic_item = "core_panic_2015_macro"] -#[rustc_macro_transparency = "semitransparent"] -pub macro panic_2015 { - () => ( - $crate::panicking::panic("explicit panic") - ), - ($msg:literal $(,)?) => ( - $crate::panicking::panic($msg) - ), - // Use `panic_str_2015` instead of `panic_display::<&str>` for non_fmt_panic lint. - ($msg:expr $(,)?) => ({ - $crate::panicking::panic_str_2015($msg); - }), - // Special-case the single-argument case for const_panic. - ("{}", $arg:expr $(,)?) => ({ - $crate::panicking::panic_display(&$arg); - }), - ($fmt:expr, $($arg:tt)+) => ({ - // Semicolon to prevent temporaries inside the formatting machinery from - // being considered alive in the caller after the panic_fmt call. - $crate::panicking::panic_fmt($crate::const_format_args!($fmt, $($arg)+)); - }), -} - -#[doc(hidden)] -#[unstable(feature = "edition_panic", issue = "none", reason = "use panic!() instead")] -#[allow_internal_unstable(panic_internals, const_format_args)] -#[rustc_diagnostic_item = "core_panic_2021_macro"] -#[rustc_macro_transparency = "semitransparent"] -#[cfg(feature = "panic_immediate_abort")] -pub macro panic_2021 { - () => ( - $crate::panicking::panic("explicit panic") - ), - // Special-case the single-argument case for const_panic. - ("{}", $arg:expr $(,)?) => ({ - $crate::panicking::panic_display(&$arg); - }), - ($($t:tt)+) => ({ - // Semicolon to prevent temporaries inside the formatting machinery from - // being considered alive in the caller after the panic_fmt call. - $crate::panicking::panic_fmt($crate::const_format_args!($($t)+)); - }), -} - -#[doc(hidden)] -#[unstable(feature = "edition_panic", issue = "none", reason = "use panic!() instead")] -#[allow_internal_unstable( - panic_internals, - core_intrinsics, - const_dispatch, - const_eval_select, - const_format_args, - rustc_attrs -)] -#[rustc_diagnostic_item = "core_panic_2021_macro"] -#[rustc_macro_transparency = "semitransparent"] -#[cfg(not(feature = "panic_immediate_abort"))] -pub macro panic_2021 { - () => ({ - // Create a function so that the argument for `track_caller` - // can be moved inside if possible. - #[cold] - #[track_caller] - #[inline(never)] - const fn panic_cold_explicit() -> ! { - $crate::panicking::panic_explicit() - } - panic_cold_explicit(); - }), - // Special-case the single-argument case for const_panic. - ("{}", $arg:expr $(,)?) => ({ - #[cold] - #[track_caller] - #[inline(never)] - #[rustc_const_panic_str] // enforce a &&str argument in const-check and hook this by const-eval - #[rustc_do_not_const_check] // hooked by const-eval - const fn panic_cold_display(arg: &T) -> ! { - $crate::panicking::panic_display(arg) - } - panic_cold_display(&$arg); - }), - ($($t:tt)+) => ({ - // Semicolon to prevent temporaries inside the formatting machinery from - // being considered alive in the caller after the panic_fmt call. - $crate::panicking::panic_fmt($crate::const_format_args!($($t)+)); - }), -} - -#[doc(hidden)] -#[unstable(feature = "edition_panic", issue = "none", reason = "use unreachable!() instead")] -#[allow_internal_unstable(panic_internals)] -#[rustc_diagnostic_item = "unreachable_2015_macro"] -#[rustc_macro_transparency = "semitransparent"] -pub macro unreachable_2015 { - () => ( - $crate::panicking::panic("internal error: entered unreachable code") - ), - // Use of `unreachable_display` for non_fmt_panic lint. - // NOTE: the message ("internal error ...") is embedded directly in unreachable_display - ($msg:expr $(,)?) => ({ - $crate::panicking::unreachable_display(&$msg); - }), - ($fmt:expr, $($arg:tt)*) => ( - $crate::panic!($crate::concat!("internal error: entered unreachable code: ", $fmt), $($arg)*) - ), -} - -#[doc(hidden)] -#[unstable(feature = "edition_panic", issue = "none", reason = "use unreachable!() instead")] -#[allow_internal_unstable(panic_internals)] -#[rustc_macro_transparency = "semitransparent"] -pub macro unreachable_2021 { - () => ( - $crate::panicking::panic("internal error: entered unreachable code") - ), - ($($t:tt)+) => ( - $crate::panic!("internal error: entered unreachable code: {}", $crate::format_args!($($t)+)) - ), -} - -/// An internal trait used by std to pass data from std to `panic_unwind` and -/// other panic runtimes. Not intended to be stabilized any time soon, do not -/// use. -#[unstable(feature = "std_internals", issue = "none")] -#[doc(hidden)] -pub unsafe trait PanicPayload { - /// Take full ownership of the contents. - /// The return type is actually `Box`, but we cannot use `Box` in core. - /// - /// After this method got called, only some dummy default value is left in `self`. - /// Calling this method twice, or calling `get` after calling this method, is an error. - /// - /// The argument is borrowed because the panic runtime (`__rust_start_panic`) only - /// gets a borrowed `dyn PanicPayload`. - fn take_box(&mut self) -> *mut (dyn Any + Send); - - /// Just borrow the contents. - fn get(&mut self) -> &(dyn Any + Send); -} diff --git a/library/core/src/panic/location.rs b/library/core/src/panic/location.rs deleted file mode 100644 index eb27da1724ec9..0000000000000 --- a/library/core/src/panic/location.rs +++ /dev/null @@ -1,200 +0,0 @@ -use crate::fmt; - -/// A struct containing information about the location of a panic. -/// -/// This structure is created by [`PanicInfo::location()`]. -/// -/// [`PanicInfo::location()`]: crate::panic::PanicInfo::location -/// -/// # Examples -/// -/// ```should_panic -/// use std::panic; -/// -/// panic::set_hook(Box::new(|panic_info| { -/// if let Some(location) = panic_info.location() { -/// println!("panic occurred in file '{}' at line {}", location.file(), location.line()); -/// } else { -/// println!("panic occurred but can't get location information..."); -/// } -/// })); -/// -/// panic!("Normal panic"); -/// ``` -/// -/// # Comparisons -/// -/// Comparisons for equality and ordering are made in file, line, then column priority. -/// Files are compared as strings, not `Path`, which could be unexpected. -/// See [`Location::file`]'s documentation for more discussion. -#[lang = "panic_location"] -#[derive(Copy, Clone, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] -#[stable(feature = "panic_hooks", since = "1.10.0")] -pub struct Location<'a> { - file: &'a str, - line: u32, - col: u32, -} - -impl<'a> Location<'a> { - /// Returns the source location of the caller of this function. If that function's caller is - /// annotated then its call location will be returned, and so on up the stack to the first call - /// within a non-tracked function body. - /// - /// # Examples - /// - /// ``` - /// use std::panic::Location; - /// - /// /// Returns the [`Location`] at which it is called. - /// #[track_caller] - /// fn get_caller_location() -> &'static Location<'static> { - /// Location::caller() - /// } - /// - /// /// Returns a [`Location`] from within this function's definition. - /// fn get_just_one_location() -> &'static Location<'static> { - /// get_caller_location() - /// } - /// - /// let fixed_location = get_just_one_location(); - /// assert_eq!(fixed_location.file(), file!()); - /// assert_eq!(fixed_location.line(), 14); - /// assert_eq!(fixed_location.column(), 5); - /// - /// // running the same untracked function in a different location gives us the same result - /// let second_fixed_location = get_just_one_location(); - /// assert_eq!(fixed_location.file(), second_fixed_location.file()); - /// assert_eq!(fixed_location.line(), second_fixed_location.line()); - /// assert_eq!(fixed_location.column(), second_fixed_location.column()); - /// - /// let this_location = get_caller_location(); - /// assert_eq!(this_location.file(), file!()); - /// assert_eq!(this_location.line(), 28); - /// assert_eq!(this_location.column(), 21); - /// - /// // running the tracked function in a different location produces a different value - /// let another_location = get_caller_location(); - /// assert_eq!(this_location.file(), another_location.file()); - /// assert_ne!(this_location.line(), another_location.line()); - /// assert_ne!(this_location.column(), another_location.column()); - /// ``` - #[must_use] - #[stable(feature = "track_caller", since = "1.46.0")] - #[rustc_const_stable(feature = "const_caller_location", since = "1.79.0")] - #[track_caller] - #[inline] - pub const fn caller() -> &'static Location<'static> { - crate::intrinsics::caller_location() - } - - /// Returns the name of the source file from which the panic originated. - /// - /// # `&str`, not `&Path` - /// - /// The returned name refers to a source path on the compiling system, but it isn't valid to - /// represent this directly as a `&Path`. The compiled code may run on a different system with - /// a different `Path` implementation than the system providing the contents and this library - /// does not currently have a different "host path" type. - /// - /// The most surprising behavior occurs when "the same" file is reachable via multiple paths in - /// the module system (usually using the `#[path = "..."]` attribute or similar), which can - /// cause what appears to be identical code to return differing values from this function. - /// - /// # Cross-compilation - /// - /// This value is not suitable for passing to `Path::new` or similar constructors when the host - /// platform and target platform differ. - /// - /// # Examples - /// - /// ```should_panic - /// use std::panic; - /// - /// panic::set_hook(Box::new(|panic_info| { - /// if let Some(location) = panic_info.location() { - /// println!("panic occurred in file '{}'", location.file()); - /// } else { - /// println!("panic occurred but can't get location information..."); - /// } - /// })); - /// - /// panic!("Normal panic"); - /// ``` - #[must_use] - #[stable(feature = "panic_hooks", since = "1.10.0")] - #[rustc_const_stable(feature = "const_location_fields", since = "1.79.0")] - #[inline] - pub const fn file(&self) -> &str { - self.file - } - - /// Returns the line number from which the panic originated. - /// - /// # Examples - /// - /// ```should_panic - /// use std::panic; - /// - /// panic::set_hook(Box::new(|panic_info| { - /// if let Some(location) = panic_info.location() { - /// println!("panic occurred at line {}", location.line()); - /// } else { - /// println!("panic occurred but can't get location information..."); - /// } - /// })); - /// - /// panic!("Normal panic"); - /// ``` - #[must_use] - #[stable(feature = "panic_hooks", since = "1.10.0")] - #[rustc_const_stable(feature = "const_location_fields", since = "1.79.0")] - #[inline] - pub const fn line(&self) -> u32 { - self.line - } - - /// Returns the column from which the panic originated. - /// - /// # Examples - /// - /// ```should_panic - /// use std::panic; - /// - /// panic::set_hook(Box::new(|panic_info| { - /// if let Some(location) = panic_info.location() { - /// println!("panic occurred at column {}", location.column()); - /// } else { - /// println!("panic occurred but can't get location information..."); - /// } - /// })); - /// - /// panic!("Normal panic"); - /// ``` - #[must_use] - #[stable(feature = "panic_col", since = "1.25.0")] - #[rustc_const_stable(feature = "const_location_fields", since = "1.79.0")] - #[inline] - pub const fn column(&self) -> u32 { - self.col - } -} - -#[unstable( - feature = "panic_internals", - reason = "internal details of the implementation of the `panic!` and related macros", - issue = "none" -)] -impl<'a> Location<'a> { - #[doc(hidden)] - pub const fn internal_constructor(file: &'a str, line: u32, col: u32) -> Self { - Location { file, line, col } - } -} - -#[stable(feature = "panic_hook_display", since = "1.26.0")] -impl fmt::Display for Location<'_> { - fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(formatter, "{}:{}:{}", self.file, self.line, self.col) - } -} diff --git a/library/core/src/panic/panic_info.rs b/library/core/src/panic/panic_info.rs deleted file mode 100644 index 403262212580c..0000000000000 --- a/library/core/src/panic/panic_info.rs +++ /dev/null @@ -1,178 +0,0 @@ -use crate::any::Any; -use crate::fmt; -use crate::panic::Location; - -/// A struct providing information about a panic. -/// -/// `PanicInfo` structure is passed to a panic hook set by the [`set_hook`] -/// function. -/// -/// [`set_hook`]: ../../std/panic/fn.set_hook.html -/// -/// # Examples -/// -/// ```should_panic -/// use std::panic; -/// -/// panic::set_hook(Box::new(|panic_info| { -/// println!("panic occurred: {panic_info}"); -/// })); -/// -/// panic!("critical system failure"); -/// ``` -#[lang = "panic_info"] -#[stable(feature = "panic_hooks", since = "1.10.0")] -#[derive(Debug)] -pub struct PanicInfo<'a> { - payload: &'a (dyn Any + Send), - message: Option<&'a fmt::Arguments<'a>>, - location: &'a Location<'a>, - can_unwind: bool, - force_no_backtrace: bool, -} - -impl<'a> PanicInfo<'a> { - #[unstable( - feature = "panic_internals", - reason = "internal details of the implementation of the `panic!` and related macros", - issue = "none" - )] - #[doc(hidden)] - #[inline] - pub fn internal_constructor( - message: Option<&'a fmt::Arguments<'a>>, - location: &'a Location<'a>, - can_unwind: bool, - force_no_backtrace: bool, - ) -> Self { - struct NoPayload; - PanicInfo { location, message, payload: &NoPayload, can_unwind, force_no_backtrace } - } - - #[unstable( - feature = "panic_internals", - reason = "internal details of the implementation of the `panic!` and related macros", - issue = "none" - )] - #[doc(hidden)] - #[inline] - pub fn set_payload(&mut self, info: &'a (dyn Any + Send)) { - self.payload = info; - } - - /// Returns the payload associated with the panic. - /// - /// This will commonly, but not always, be a `&'static str` or [`String`]. - /// - /// [`String`]: ../../std/string/struct.String.html - /// - /// # Examples - /// - /// ```should_panic - /// use std::panic; - /// - /// panic::set_hook(Box::new(|panic_info| { - /// if let Some(s) = panic_info.payload().downcast_ref::<&str>() { - /// println!("panic occurred: {s:?}"); - /// } else { - /// println!("panic occurred"); - /// } - /// })); - /// - /// panic!("Normal panic"); - /// ``` - #[must_use] - #[stable(feature = "panic_hooks", since = "1.10.0")] - pub fn payload(&self) -> &(dyn Any + Send) { - self.payload - } - - /// If the `panic!` macro from the `core` crate (not from `std`) - /// was used with a formatting string and some additional arguments, - /// returns that message ready to be used for example with [`fmt::write`] - #[must_use] - #[unstable(feature = "panic_info_message", issue = "66745")] - pub fn message(&self) -> Option<&fmt::Arguments<'_>> { - self.message - } - - /// Returns information about the location from which the panic originated, - /// if available. - /// - /// This method will currently always return [`Some`], but this may change - /// in future versions. - /// - /// # Examples - /// - /// ```should_panic - /// use std::panic; - /// - /// panic::set_hook(Box::new(|panic_info| { - /// if let Some(location) = panic_info.location() { - /// println!("panic occurred in file '{}' at line {}", - /// location.file(), - /// location.line(), - /// ); - /// } else { - /// println!("panic occurred but can't get location information..."); - /// } - /// })); - /// - /// panic!("Normal panic"); - /// ``` - #[must_use] - #[stable(feature = "panic_hooks", since = "1.10.0")] - pub fn location(&self) -> Option<&Location<'_>> { - // NOTE: If this is changed to sometimes return None, - // deal with that case in std::panicking::default_hook and core::panicking::panic_fmt. - Some(&self.location) - } - - /// Returns whether the panic handler is allowed to unwind the stack from - /// the point where the panic occurred. - /// - /// This is true for most kinds of panics with the exception of panics - /// caused by trying to unwind out of a `Drop` implementation or a function - /// whose ABI does not support unwinding. - /// - /// It is safe for a panic handler to unwind even when this function returns - /// false, however this will simply cause the panic handler to be called - /// again. - #[must_use] - #[unstable(feature = "panic_can_unwind", issue = "92988")] - pub fn can_unwind(&self) -> bool { - self.can_unwind - } - - #[unstable( - feature = "panic_internals", - reason = "internal details of the implementation of the `panic!` and related macros", - issue = "none" - )] - #[doc(hidden)] - #[inline] - pub fn force_no_backtrace(&self) -> bool { - self.force_no_backtrace - } -} - -#[stable(feature = "panic_hook_display", since = "1.26.0")] -impl fmt::Display for PanicInfo<'_> { - fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - formatter.write_str("panicked at ")?; - self.location.fmt(formatter)?; - formatter.write_str(":")?; - if let Some(message) = self.message { - formatter.write_str("\n")?; - formatter.write_fmt(*message)?; - } else if let Some(payload) = self.payload.downcast_ref::<&'static str>() { - formatter.write_str("\n")?; - formatter.write_str(payload)?; - } - // NOTE: we cannot use downcast_ref::() here - // since String is not available in core! - // The payload is a String when `std::panic!` is called with multiple arguments, - // but in that case the message is also available. - Ok(()) - } -} diff --git a/library/core/src/panic/unwind_safe.rs b/library/core/src/panic/unwind_safe.rs deleted file mode 100644 index 37859212c0ee3..0000000000000 --- a/library/core/src/panic/unwind_safe.rs +++ /dev/null @@ -1,313 +0,0 @@ -use crate::async_iter::AsyncIterator; -use crate::cell::UnsafeCell; -use crate::fmt; -use crate::future::Future; -use crate::ops::{Deref, DerefMut}; -use crate::pin::Pin; -use crate::ptr::{NonNull, Unique}; -use crate::task::{Context, Poll}; - -/// A marker trait which represents "panic safe" types in Rust. -/// -/// This trait is implemented by default for many types and behaves similarly in -/// terms of inference of implementation to the [`Send`] and [`Sync`] traits. The -/// purpose of this trait is to encode what types are safe to cross a [`catch_unwind`] -/// boundary with no fear of unwind safety. -/// -/// [`catch_unwind`]: ../../std/panic/fn.catch_unwind.html -/// -/// ## What is unwind safety? -/// -/// In Rust a function can "return" early if it either panics or calls a -/// function which transitively panics. This sort of control flow is not always -/// anticipated, and has the possibility of causing subtle bugs through a -/// combination of two critical components: -/// -/// 1. A data structure is in a temporarily invalid state when the thread -/// panics. -/// 2. This broken invariant is then later observed. -/// -/// Typically in Rust, it is difficult to perform step (2) because catching a -/// panic involves either spawning a thread (which in turn makes it difficult -/// to later witness broken invariants) or using the `catch_unwind` function in this -/// module. Additionally, even if an invariant is witnessed, it typically isn't a -/// problem in Rust because there are no uninitialized values (like in C or C++). -/// -/// It is possible, however, for **logical** invariants to be broken in Rust, -/// which can end up causing behavioral bugs. Another key aspect of unwind safety -/// in Rust is that, in the absence of `unsafe` code, a panic cannot lead to -/// memory unsafety. -/// -/// That was a bit of a whirlwind tour of unwind safety, but for more information -/// about unwind safety and how it applies to Rust, see an [associated RFC][rfc]. -/// -/// [rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1236-stabilize-catch-panic.md -/// -/// ## What is `UnwindSafe`? -/// -/// Now that we've got an idea of what unwind safety is in Rust, it's also -/// important to understand what this trait represents. As mentioned above, one -/// way to witness broken invariants is through the `catch_unwind` function in this -/// module as it allows catching a panic and then re-using the environment of -/// the closure. -/// -/// Simply put, a type `T` implements `UnwindSafe` if it cannot easily allow -/// witnessing a broken invariant through the use of `catch_unwind` (catching a -/// panic). This trait is an auto trait, so it is automatically implemented for -/// many types, and it is also structurally composed (e.g., a struct is unwind -/// safe if all of its components are unwind safe). -/// -/// Note, however, that this is not an unsafe trait, so there is not a succinct -/// contract that this trait is providing. Instead it is intended as more of a -/// "speed bump" to alert users of `catch_unwind` that broken invariants may be -/// witnessed and may need to be accounted for. -/// -/// ## Who implements `UnwindSafe`? -/// -/// Types such as `&mut T` and `&RefCell` are examples which are **not** -/// unwind safe. The general idea is that any mutable state which can be shared -/// across `catch_unwind` is not unwind safe by default. This is because it is very -/// easy to witness a broken invariant outside of `catch_unwind` as the data is -/// simply accessed as usual. -/// -/// Types like `&Mutex`, however, are unwind safe because they implement -/// poisoning by default. They still allow witnessing a broken invariant, but -/// they already provide their own "speed bumps" to do so. -/// -/// ## When should `UnwindSafe` be used? -/// -/// It is not intended that most types or functions need to worry about this trait. -/// It is only used as a bound on the `catch_unwind` function and as mentioned -/// above, the lack of `unsafe` means it is mostly an advisory. The -/// [`AssertUnwindSafe`] wrapper struct can be used to force this trait to be -/// implemented for any closed over variables passed to `catch_unwind`. -#[stable(feature = "catch_unwind", since = "1.9.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "unwind_safe_trait")] -#[diagnostic::on_unimplemented( - message = "the type `{Self}` may not be safely transferred across an unwind boundary", - label = "`{Self}` may not be safely transferred across an unwind boundary" -)] -pub auto trait UnwindSafe {} - -/// A marker trait representing types where a shared reference is considered -/// unwind safe. -/// -/// This trait is namely not implemented by [`UnsafeCell`], the root of all -/// interior mutability. -/// -/// This is a "helper marker trait" used to provide impl blocks for the -/// [`UnwindSafe`] trait, for more information see that documentation. -#[stable(feature = "catch_unwind", since = "1.9.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "ref_unwind_safe_trait")] -#[diagnostic::on_unimplemented( - message = "the type `{Self}` may contain interior mutability and a reference may not be safely \ - transferrable across a catch_unwind boundary", - label = "`{Self}` may contain interior mutability and a reference may not be safely \ - transferrable across a catch_unwind boundary" -)] -pub auto trait RefUnwindSafe {} - -/// A simple wrapper around a type to assert that it is unwind safe. -/// -/// When using [`catch_unwind`] it may be the case that some of the closed over -/// variables are not unwind safe. For example if `&mut T` is captured the -/// compiler will generate a warning indicating that it is not unwind safe. It -/// might not be the case, however, that this is actually a problem due to the -/// specific usage of [`catch_unwind`] if unwind safety is specifically taken into -/// account. This wrapper struct is useful for a quick and lightweight -/// annotation that a variable is indeed unwind safe. -/// -/// [`catch_unwind`]: ../../std/panic/fn.catch_unwind.html -/// -/// # Examples -/// -/// One way to use `AssertUnwindSafe` is to assert that the entire closure -/// itself is unwind safe, bypassing all checks for all variables: -/// -/// ``` -/// use std::panic::{self, AssertUnwindSafe}; -/// -/// let mut variable = 4; -/// -/// // This code will not compile because the closure captures `&mut variable` -/// // which is not considered unwind safe by default. -/// -/// // panic::catch_unwind(|| { -/// // variable += 3; -/// // }); -/// -/// // This, however, will compile due to the `AssertUnwindSafe` wrapper -/// let result = panic::catch_unwind(AssertUnwindSafe(|| { -/// variable += 3; -/// })); -/// // ... -/// ``` -/// -/// Wrapping the entire closure amounts to a blanket assertion that all captured -/// variables are unwind safe. This has the downside that if new captures are -/// added in the future, they will also be considered unwind safe. Therefore, -/// you may prefer to just wrap individual captures, as shown below. This is -/// more annotation, but it ensures that if a new capture is added which is not -/// unwind safe, you will get a compilation error at that time, which will -/// allow you to consider whether that new capture in fact represent a bug or -/// not. -/// -/// ``` -/// use std::panic::{self, AssertUnwindSafe}; -/// -/// let mut variable = 4; -/// let other_capture = 3; -/// -/// let result = { -/// let mut wrapper = AssertUnwindSafe(&mut variable); -/// panic::catch_unwind(move || { -/// **wrapper += other_capture; -/// }) -/// }; -/// // ... -/// ``` -#[stable(feature = "catch_unwind", since = "1.9.0")] -pub struct AssertUnwindSafe(#[stable(feature = "catch_unwind", since = "1.9.0")] pub T); - -// Implementations of the `UnwindSafe` trait: -// -// * By default everything is unwind safe -// * pointers T contains mutability of some form are not unwind safe -// * Unique, an owning pointer, lifts an implementation -// * Types like Mutex/RwLock which are explicitly poisoned are unwind safe -// * Our custom AssertUnwindSafe wrapper is indeed unwind safe - -#[stable(feature = "catch_unwind", since = "1.9.0")] -impl !UnwindSafe for &mut T {} -#[stable(feature = "catch_unwind", since = "1.9.0")] -impl UnwindSafe for &T {} -#[stable(feature = "catch_unwind", since = "1.9.0")] -impl UnwindSafe for *const T {} -#[stable(feature = "catch_unwind", since = "1.9.0")] -impl UnwindSafe for *mut T {} -#[unstable(feature = "ptr_internals", issue = "none")] -impl UnwindSafe for Unique {} -#[stable(feature = "nonnull", since = "1.25.0")] -impl UnwindSafe for NonNull {} -#[stable(feature = "catch_unwind", since = "1.9.0")] -impl UnwindSafe for AssertUnwindSafe {} - -// Pretty simple implementations for the `RefUnwindSafe` marker trait, -// basically just saying that `UnsafeCell` is the -// only thing which doesn't implement it (which then transitively applies to -// everything else). -#[stable(feature = "catch_unwind", since = "1.9.0")] -impl !RefUnwindSafe for UnsafeCell {} -#[stable(feature = "catch_unwind", since = "1.9.0")] -impl RefUnwindSafe for AssertUnwindSafe {} - -#[cfg(target_has_atomic_load_store = "ptr")] -#[stable(feature = "unwind_safe_atomic_refs", since = "1.14.0")] -impl RefUnwindSafe for crate::sync::atomic::AtomicIsize {} -#[cfg(target_has_atomic_load_store = "8")] -#[stable(feature = "integer_atomics_stable", since = "1.34.0")] -impl RefUnwindSafe for crate::sync::atomic::AtomicI8 {} -#[cfg(target_has_atomic_load_store = "16")] -#[stable(feature = "integer_atomics_stable", since = "1.34.0")] -impl RefUnwindSafe for crate::sync::atomic::AtomicI16 {} -#[cfg(target_has_atomic_load_store = "32")] -#[stable(feature = "integer_atomics_stable", since = "1.34.0")] -impl RefUnwindSafe for crate::sync::atomic::AtomicI32 {} -#[cfg(target_has_atomic_load_store = "64")] -#[stable(feature = "integer_atomics_stable", since = "1.34.0")] -impl RefUnwindSafe for crate::sync::atomic::AtomicI64 {} -#[cfg(target_has_atomic_load_store = "128")] -#[unstable(feature = "integer_atomics", issue = "99069")] -impl RefUnwindSafe for crate::sync::atomic::AtomicI128 {} - -#[cfg(target_has_atomic_load_store = "ptr")] -#[stable(feature = "unwind_safe_atomic_refs", since = "1.14.0")] -impl RefUnwindSafe for crate::sync::atomic::AtomicUsize {} -#[cfg(target_has_atomic_load_store = "8")] -#[stable(feature = "integer_atomics_stable", since = "1.34.0")] -impl RefUnwindSafe for crate::sync::atomic::AtomicU8 {} -#[cfg(target_has_atomic_load_store = "16")] -#[stable(feature = "integer_atomics_stable", since = "1.34.0")] -impl RefUnwindSafe for crate::sync::atomic::AtomicU16 {} -#[cfg(target_has_atomic_load_store = "32")] -#[stable(feature = "integer_atomics_stable", since = "1.34.0")] -impl RefUnwindSafe for crate::sync::atomic::AtomicU32 {} -#[cfg(target_has_atomic_load_store = "64")] -#[stable(feature = "integer_atomics_stable", since = "1.34.0")] -impl RefUnwindSafe for crate::sync::atomic::AtomicU64 {} -#[cfg(target_has_atomic_load_store = "128")] -#[unstable(feature = "integer_atomics", issue = "99069")] -impl RefUnwindSafe for crate::sync::atomic::AtomicU128 {} - -#[cfg(target_has_atomic_load_store = "8")] -#[stable(feature = "unwind_safe_atomic_refs", since = "1.14.0")] -impl RefUnwindSafe for crate::sync::atomic::AtomicBool {} - -#[cfg(target_has_atomic_load_store = "ptr")] -#[stable(feature = "unwind_safe_atomic_refs", since = "1.14.0")] -impl RefUnwindSafe for crate::sync::atomic::AtomicPtr {} - -#[stable(feature = "catch_unwind", since = "1.9.0")] -impl Deref for AssertUnwindSafe { - type Target = T; - - fn deref(&self) -> &T { - &self.0 - } -} - -#[stable(feature = "catch_unwind", since = "1.9.0")] -impl DerefMut for AssertUnwindSafe { - fn deref_mut(&mut self) -> &mut T { - &mut self.0 - } -} - -#[stable(feature = "catch_unwind", since = "1.9.0")] -impl R> FnOnce<()> for AssertUnwindSafe { - type Output = R; - - #[inline] - extern "rust-call" fn call_once(self, _args: ()) -> R { - (self.0)() - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for AssertUnwindSafe { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("AssertUnwindSafe").field(&self.0).finish() - } -} - -#[stable(feature = "assertunwindsafe_default", since = "1.62.0")] -impl Default for AssertUnwindSafe { - fn default() -> Self { - Self(Default::default()) - } -} - -#[stable(feature = "futures_api", since = "1.36.0")] -impl Future for AssertUnwindSafe { - type Output = F::Output; - - fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll { - // SAFETY: pin projection. AssertUnwindSafe follows structural pinning. - let pinned_field = unsafe { Pin::map_unchecked_mut(self, |x| &mut x.0) }; - F::poll(pinned_field, cx) - } -} - -#[unstable(feature = "async_iterator", issue = "79024")] -impl AsyncIterator for AssertUnwindSafe { - type Item = S::Item; - - fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll> { - // SAFETY: pin projection. AssertUnwindSafe follows structural pinning. - unsafe { self.map_unchecked_mut(|x| &mut x.0) }.poll_next(cx) - } - - fn size_hint(&self) -> (usize, Option) { - self.0.size_hint() - } -} diff --git a/library/core/src/panicking.rs b/library/core/src/panicking.rs deleted file mode 100644 index ca06e059b75ac..0000000000000 --- a/library/core/src/panicking.rs +++ /dev/null @@ -1,414 +0,0 @@ -//! Panic support for core -//! -//! The core library cannot define panicking, but it does *declare* panicking. This -//! means that the functions inside of core are allowed to panic, but to be -//! useful an upstream crate must define panicking for core to use. The current -//! interface for panicking is: -//! -//! ``` -//! fn panic_impl(pi: &core::panic::PanicInfo<'_>) -> ! -//! # { loop {} } -//! ``` -//! -//! This definition allows for panicking with any general message, but it does not -//! allow for failing with a `Box` value. (`PanicInfo` just contains a `&(dyn Any + Send)`, -//! for which we fill in a dummy value in `PanicInfo::internal_constructor`.) -//! The reason for this is that core is not allowed to allocate. -//! -//! This module contains a few other panicking functions, but these are just the -//! necessary lang items for the compiler. All panics are funneled through this -//! one function. The actual symbol is declared through the `#[panic_handler]` attribute. - -#![allow(dead_code, missing_docs)] -#![unstable( - feature = "panic_internals", - reason = "internal details of the implementation of the `panic!` and related macros", - issue = "none" -)] - -use crate::fmt; -use crate::panic::{Location, PanicInfo}; - -#[cfg(feature = "panic_immediate_abort")] -const _: () = assert!(cfg!(panic = "abort"), "panic_immediate_abort requires -C panic=abort"); - -// First we define the two main entry points that all panics go through. -// In the end both are just convenience wrappers around `panic_impl`. - -/// The entry point for panicking with a formatted message. -/// -/// This is designed to reduce the amount of code required at the call -/// site as much as possible (so that `panic!()` has as low an impact -/// on (e.g.) the inlining of other functions as possible), by moving -/// the actual formatting into this shared place. -// If panic_immediate_abort, inline the abort call, -// otherwise avoid inlining because of it is cold path. -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)] -#[cfg_attr(feature = "panic_immediate_abort", inline)] -#[track_caller] -#[lang = "panic_fmt"] // needed for const-evaluated panics -#[rustc_do_not_const_check] // hooked by const-eval -#[rustc_const_unstable(feature = "panic_internals", issue = "none")] -pub const fn panic_fmt(fmt: fmt::Arguments<'_>) -> ! { - if cfg!(feature = "panic_immediate_abort") { - super::intrinsics::abort() - } - - // NOTE This function never crosses the FFI boundary; it's a Rust-to-Rust call - // that gets resolved to the `#[panic_handler]` function. - extern "Rust" { - #[lang = "panic_impl"] - fn panic_impl(pi: &PanicInfo<'_>) -> !; - } - - let pi = PanicInfo::internal_constructor( - Some(&fmt), - Location::caller(), - /* can_unwind */ true, - /* force_no_backtrace */ false, - ); - - // SAFETY: `panic_impl` is defined in safe Rust code and thus is safe to call. - unsafe { panic_impl(&pi) } -} - -/// Like `panic_fmt`, but for non-unwinding panics. -/// -/// Has to be a separate function so that it can carry the `rustc_nounwind` attribute. -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)] -#[cfg_attr(feature = "panic_immediate_abort", inline)] -#[track_caller] -// This attribute has the key side-effect that if the panic handler ignores `can_unwind` -// and unwinds anyway, we will hit the "unwinding out of nounwind function" guard, -// which causes a "panic in a function that cannot unwind". -#[rustc_nounwind] -#[rustc_const_unstable(feature = "panic_internals", issue = "none")] -pub const fn panic_nounwind_fmt(fmt: fmt::Arguments<'_>, force_no_backtrace: bool) -> ! { - #[inline] // this should always be inlined into `panic_nounwind_fmt` - #[track_caller] - fn runtime(fmt: fmt::Arguments<'_>, force_no_backtrace: bool) -> ! { - if cfg!(feature = "panic_immediate_abort") { - super::intrinsics::abort() - } - - // NOTE This function never crosses the FFI boundary; it's a Rust-to-Rust call - // that gets resolved to the `#[panic_handler]` function. - extern "Rust" { - #[lang = "panic_impl"] - fn panic_impl(pi: &PanicInfo<'_>) -> !; - } - - // PanicInfo with the `can_unwind` flag set to false forces an abort. - let pi = PanicInfo::internal_constructor( - Some(&fmt), - Location::caller(), - /* can_unwind */ false, - force_no_backtrace, - ); - - // SAFETY: `panic_impl` is defined in safe Rust code and thus is safe to call. - unsafe { panic_impl(&pi) } - } - - #[inline] - #[track_caller] - const fn comptime(fmt: fmt::Arguments<'_>, _force_no_backtrace: bool) -> ! { - // We don't unwind anyway at compile-time so we can call the regular `panic_fmt`. - panic_fmt(fmt); - } - - super::intrinsics::const_eval_select((fmt, force_no_backtrace), comptime, runtime); -} - -// Next we define a bunch of higher-level wrappers that all bottom out in the two core functions -// above. - -/// The underlying implementation of core's `panic!` macro when no formatting is used. -// Never inline unless panic_immediate_abort to avoid code -// bloat at the call sites as much as possible. -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)] -#[cfg_attr(feature = "panic_immediate_abort", inline)] -#[track_caller] -#[rustc_const_unstable(feature = "panic_internals", issue = "none")] -#[lang = "panic"] // used by lints and miri for panics -pub const fn panic(expr: &'static str) -> ! { - // Use Arguments::new_const instead of format_args!("{expr}") to potentially - // reduce size overhead. The format_args! macro uses str's Display trait to - // write expr, which calls Formatter::pad, which must accommodate string - // truncation and padding (even though none is used here). Using - // Arguments::new_const may allow the compiler to omit Formatter::pad from the - // output binary, saving up to a few kilobytes. - // However, this optimization only works for `'static` strings: `new_const` also makes this - // message return `Some` from `Arguments::as_str`, which means it can become part of the panic - // payload without any allocation or copying. Shorter-lived strings would become invalid as - // stack frames get popped during unwinding, and couldn't be directly referenced from the - // payload. - panic_fmt(fmt::Arguments::new_const(&[expr])); -} - -// We generate functions for usage by compiler-generated assertions. -// -// Placing these functions in libcore means that all Rust programs can generate a jump into this -// code rather than expanding to panic("...") above, which adds extra bloat to call sites (for the -// constant string argument's pointer and length). -// -// This is especially important when this code is called often (e.g., with -Coverflow-checks) for -// reducing binary size impact. -macro_rules! panic_const { - ($($lang:ident = $message:expr,)+) => { - pub mod panic_const { - use super::*; - - $( - /// This is a panic called with a message that's a result of a MIR-produced Assert. - // - // never inline unless panic_immediate_abort to avoid code - // bloat at the call sites as much as possible - #[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)] - #[cfg_attr(feature = "panic_immediate_abort", inline)] - #[track_caller] - #[rustc_const_unstable(feature = "panic_internals", issue = "none")] - #[lang = stringify!($lang)] - pub const fn $lang() -> ! { - // Use Arguments::new_const instead of format_args!("{expr}") to potentially - // reduce size overhead. The format_args! macro uses str's Display trait to - // write expr, which calls Formatter::pad, which must accommodate string - // truncation and padding (even though none is used here). Using - // Arguments::new_const may allow the compiler to omit Formatter::pad from the - // output binary, saving up to a few kilobytes. - panic_fmt(fmt::Arguments::new_const(&[$message])); - } - )+ - } - } -} - -// Unfortunately this set of strings is replicated here and in a few places in the compiler in -// slightly different forms. It's not clear if there's a good way to deduplicate without adding -// special cases to the compiler (e.g., a const generic function wouldn't have a single definition -// shared across crates, which is exactly what we want here). -panic_const! { - panic_const_add_overflow = "attempt to add with overflow", - panic_const_sub_overflow = "attempt to subtract with overflow", - panic_const_mul_overflow = "attempt to multiply with overflow", - panic_const_div_overflow = "attempt to divide with overflow", - panic_const_rem_overflow = "attempt to calculate the remainder with overflow", - panic_const_neg_overflow = "attempt to negate with overflow", - panic_const_shr_overflow = "attempt to shift right with overflow", - panic_const_shl_overflow = "attempt to shift left with overflow", - panic_const_div_by_zero = "attempt to divide by zero", - panic_const_rem_by_zero = "attempt to calculate the remainder with a divisor of zero", - panic_const_coroutine_resumed = "coroutine resumed after completion", - panic_const_async_fn_resumed = "`async fn` resumed after completion", - panic_const_async_gen_fn_resumed = "`async gen fn` resumed after completion", - panic_const_gen_fn_none = "`gen fn` should just keep returning `None` after completion", - panic_const_coroutine_resumed_panic = "coroutine resumed after panicking", - panic_const_async_fn_resumed_panic = "`async fn` resumed after panicking", - panic_const_async_gen_fn_resumed_panic = "`async gen fn` resumed after panicking", - panic_const_gen_fn_none_panic = "`gen fn` should just keep returning `None` after panicking", -} - -/// Like `panic`, but without unwinding and track_caller to reduce the impact on codesize on the caller. -/// If you want `#[track_caller]` for nicer errors, call `panic_nounwind_fmt` directly. -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)] -#[cfg_attr(feature = "panic_immediate_abort", inline)] -#[lang = "panic_nounwind"] // needed by codegen for non-unwinding panics -#[rustc_nounwind] -#[rustc_const_unstable(feature = "panic_internals", issue = "none")] -pub const fn panic_nounwind(expr: &'static str) -> ! { - panic_nounwind_fmt(fmt::Arguments::new_const(&[expr]), /* force_no_backtrace */ false); -} - -/// Like `panic_nounwind`, but also inhibits showing a backtrace. -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)] -#[cfg_attr(feature = "panic_immediate_abort", inline)] -#[rustc_nounwind] -pub fn panic_nounwind_nobacktrace(expr: &'static str) -> ! { - panic_nounwind_fmt(fmt::Arguments::new_const(&[expr]), /* force_no_backtrace */ true); -} - -#[track_caller] -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)] -#[cfg_attr(feature = "panic_immediate_abort", inline)] -#[rustc_const_unstable(feature = "panic_internals", issue = "none")] -pub const fn panic_explicit() -> ! { - panic_display(&"explicit panic"); -} - -#[inline] -#[track_caller] -#[rustc_diagnostic_item = "unreachable_display"] // needed for `non-fmt-panics` lint -pub fn unreachable_display(x: &T) -> ! { - panic_fmt(format_args!("internal error: entered unreachable code: {}", *x)); -} - -/// This exists solely for the 2015 edition `panic!` macro to trigger -/// a lint on `panic!(my_str_variable);`. -#[inline] -#[track_caller] -#[rustc_diagnostic_item = "panic_str_2015"] -#[rustc_const_unstable(feature = "panic_internals", issue = "none")] -pub const fn panic_str_2015(expr: &str) -> ! { - panic_display(&expr); -} - -#[inline] -#[track_caller] -#[rustc_do_not_const_check] // hooked by const-eval -// enforce a &&str argument in const-check and hook this by const-eval -#[rustc_const_panic_str] -#[rustc_const_unstable(feature = "panic_internals", issue = "none")] -pub const fn panic_display(x: &T) -> ! { - panic_fmt(format_args!("{}", *x)); -} - -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)] -#[cfg_attr(feature = "panic_immediate_abort", inline)] -#[track_caller] -#[lang = "panic_bounds_check"] // needed by codegen for panic on OOB array/slice access -fn panic_bounds_check(index: usize, len: usize) -> ! { - if cfg!(feature = "panic_immediate_abort") { - super::intrinsics::abort() - } - - panic!("index out of bounds: the len is {len} but the index is {index}") -} - -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)] -#[cfg_attr(feature = "panic_immediate_abort", inline)] -#[track_caller] -#[lang = "panic_misaligned_pointer_dereference"] // needed by codegen for panic on misaligned pointer deref -#[rustc_nounwind] // `CheckAlignment` MIR pass requires this function to never unwind -fn panic_misaligned_pointer_dereference(required: usize, found: usize) -> ! { - if cfg!(feature = "panic_immediate_abort") { - super::intrinsics::abort() - } - - panic_nounwind_fmt( - format_args!( - "misaligned pointer dereference: address must be a multiple of {required:#x} but is {found:#x}" - ), - /* force_no_backtrace */ false, - ) -} - -/// Panic because we cannot unwind out of a function. -/// -/// This is a separate function to avoid the codesize impact of each crate containing the string to -/// pass to `panic_nounwind`. -/// This function is called directly by the codegen backend, and must not have -/// any extra arguments (including those synthesized by track_caller). -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)] -#[cfg_attr(feature = "panic_immediate_abort", inline)] -#[lang = "panic_cannot_unwind"] // needed by codegen for panic in nounwind function -#[rustc_nounwind] -fn panic_cannot_unwind() -> ! { - // Keep the text in sync with `UnwindTerminateReason::as_str` in `rustc_middle`. - panic_nounwind("panic in a function that cannot unwind") -} - -/// Panic because we are unwinding out of a destructor during cleanup. -/// -/// This is a separate function to avoid the codesize impact of each crate containing the string to -/// pass to `panic_nounwind`. -/// This function is called directly by the codegen backend, and must not have -/// any extra arguments (including those synthesized by track_caller). -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)] -#[cfg_attr(feature = "panic_immediate_abort", inline)] -#[lang = "panic_in_cleanup"] // needed by codegen for panic in nounwind function -#[rustc_nounwind] -fn panic_in_cleanup() -> ! { - // Keep the text in sync with `UnwindTerminateReason::as_str` in `rustc_middle`. - panic_nounwind_nobacktrace("panic in a destructor during cleanup") -} - -/// This function is used instead of panic_fmt in const eval. -#[lang = "const_panic_fmt"] -#[rustc_const_unstable(feature = "panic_internals", issue = "none")] -pub const fn const_panic_fmt(fmt: fmt::Arguments<'_>) -> ! { - if let Some(msg) = fmt.as_str() { - // The panic_display function is hooked by const eval. - panic_display(&msg); - } else { - // SAFETY: This is only evaluated at compile time, which reliably - // handles this UB (in case this branch turns out to be reachable - // somehow). - unsafe { crate::hint::unreachable_unchecked() }; - } -} - -#[derive(Debug)] -#[doc(hidden)] -pub enum AssertKind { - Eq, - Ne, - Match, -} - -/// Internal function for `assert_eq!` and `assert_ne!` macros -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)] -#[cfg_attr(feature = "panic_immediate_abort", inline)] -#[track_caller] -#[doc(hidden)] -pub fn assert_failed( - kind: AssertKind, - left: &T, - right: &U, - args: Option>, -) -> ! -where - T: fmt::Debug + ?Sized, - U: fmt::Debug + ?Sized, -{ - assert_failed_inner(kind, &left, &right, args) -} - -/// Internal function for `assert_match!` -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)] -#[cfg_attr(feature = "panic_immediate_abort", inline)] -#[track_caller] -#[doc(hidden)] -pub fn assert_matches_failed( - left: &T, - right: &str, - args: Option>, -) -> ! { - // The pattern is a string so it can be displayed directly. - struct Pattern<'a>(&'a str); - impl fmt::Debug for Pattern<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str(self.0) - } - } - assert_failed_inner(AssertKind::Match, &left, &Pattern(right), args); -} - -/// Non-generic version of the above functions, to avoid code bloat. -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)] -#[cfg_attr(feature = "panic_immediate_abort", inline)] -#[track_caller] -fn assert_failed_inner( - kind: AssertKind, - left: &dyn fmt::Debug, - right: &dyn fmt::Debug, - args: Option>, -) -> ! { - let op = match kind { - AssertKind::Eq => "==", - AssertKind::Ne => "!=", - AssertKind::Match => "matches", - }; - - match args { - Some(args) => panic!( - r#"assertion `left {op} right` failed: {args} - left: {left:?} - right: {right:?}"# - ), - None => panic!( - r#"assertion `left {op} right` failed - left: {left:?} - right: {right:?}"# - ), - } -} diff --git a/library/core/src/pat.rs b/library/core/src/pat.rs deleted file mode 100644 index a10c45933428d..0000000000000 --- a/library/core/src/pat.rs +++ /dev/null @@ -1,14 +0,0 @@ -//! Helper module for exporting the `pattern_type` macro - -/// Creates a pattern type. -/// ```ignore (cannot test this from within core yet) -/// type Positive = std::pat::pattern_type!(i32 is 1..); -/// ``` -#[macro_export] -#[rustc_builtin_macro(pattern_type)] -#[unstable(feature = "core_pattern_type", issue = "none")] -macro_rules! pattern_type { - ($($arg:tt)*) => { - /* compiler built-in */ - }; -} diff --git a/library/core/src/pin.rs b/library/core/src/pin.rs deleted file mode 100644 index d8fc3b7177f38..0000000000000 --- a/library/core/src/pin.rs +++ /dev/null @@ -1,1965 +0,0 @@ -//! Types that pin data to a location in memory. -//! -//! It is sometimes useful to be able to rely upon a certain value not being able to *move*, -//! in the sense that its address in memory cannot change. This is useful especially when there -//! are one or more [*pointers*][pointer] pointing at that value. The ability to rely on this -//! guarantee that the value a [pointer] is pointing at (its **pointee**) will -//! -//! 1. Not be *moved* out of its memory location -//! 2. More generally, remain *valid* at that same memory location -//! -//! is called "pinning." We would say that a value which satisfies these guarantees has been -//! "pinned," in that it has been permanently (until the end of its lifespan) attached to its -//! location in memory, as though pinned to a pinboard. Pinning a value is an incredibly useful -//! building block for [`unsafe`] code to be able to reason about whether a raw pointer to the -//! pinned value is still valid. [As we'll see later][drop-guarantee], this is necessarily from the -//! time the value is first pinned until the end of its lifespan. This concept of "pinning" is -//! necessary to implement safe interfaces on top of things like self-referential types and -//! intrusive data structures which cannot currently be modeled in fully safe Rust using only -//! borrow-checked [references][reference]. -//! -//! "Pinning" allows us to put a *value* which exists at some location in memory into a state where -//! safe code cannot *move* that value to a different location in memory or otherwise invalidate it -//! at its current location (unless it implements [`Unpin`], which we will -//! [talk about below][self#unpin]). Anything that wants to interact with the pinned value in a way -//! that has the potential to violate these guarantees must promise that it will not actually -//! violate them, using the [`unsafe`] keyword to mark that such a promise is upheld by the user -//! and not the compiler. In this way, we can allow other [`unsafe`] code to rely on any pointers -//! that point to the pinned value to be valid to dereference while it is pinned. -//! -//! Note that as long as you don't use [`unsafe`], it's impossible to create or misuse a pinned -//! value in a way that is unsound. See the documentation of [`Pin`] for more -//! information on the practicalities of how to pin a value and how to use that pinned value from a -//! user's perspective without using [`unsafe`]. -//! -//! The rest of this documentation is intended to be the source of truth for users of [`Pin`] -//! that are implementing the [`unsafe`] pieces of an interface that relies on pinning for validity; -//! users of [`Pin`] in safe code do not need to read it in detail. -//! -//! There are several sections to this documentation: -//! -//! * [What is "*moving*"?][what-is-moving] -//! * [What is "pinning"?][what-is-pinning] -//! * [Address sensitivity, AKA "when do we need pinning?"][address-sensitive-values] -//! * [Examples of types with address-sensitive states][address-sensitive-examples] -//! * [Self-referential struct][self-ref] -//! * [Intrusive, doubly-linked list][linked-list] -//! * [Subtle details and the `Drop` guarantee][subtle-details] -//! -//! # What is "*moving*"? -//! [what-is-moving]: self#what-is-moving -//! -//! When we say a value is *moved*, we mean that the compiler copies, byte-for-byte, the -//! value from one location to another. In a purely mechanical sense, this is identical to -//! [`Copy`]ing a value from one place in memory to another. In Rust, "move" carries with it the -//! semantics of ownership transfer from one variable to another, which is the key difference -//! between a [`Copy`] and a move. For the purposes of this module's documentation, however, when -//! we write *move* in italics, we mean *specifically* that the value has *moved* in the mechanical -//! sense of being located at a new place in memory. -//! -//! All values in Rust are trivially *moveable*. This means that the address at which a value is -//! located is not necessarily stable in between borrows. The compiler is allowed to *move* a value -//! to a new address without running any code to notify that value that its address -//! has changed. Although the compiler will not insert memory *moves* where no semantic move has -//! occurred, there are many places where a value *may* be moved. For example, when doing -//! assignment or passing a value into a function. -//! -//! ``` -//! #[derive(Default)] -//! struct AddrTracker(Option); -//! -//! impl AddrTracker { -//! // If we haven't checked the addr of self yet, store the current -//! // address. If we have, confirm that the current address is the same -//! // as it was last time, or else panic. -//! fn check_for_move(&mut self) { -//! let current_addr = self as *mut Self as usize; -//! match self.0 { -//! None => self.0 = Some(current_addr), -//! Some(prev_addr) => assert_eq!(prev_addr, current_addr), -//! } -//! } -//! } -//! -//! // Create a tracker and store the initial address -//! let mut tracker = AddrTracker::default(); -//! tracker.check_for_move(); -//! -//! // Here we shadow the variable. This carries a semantic move, and may therefore also -//! // come with a mechanical memory *move* -//! let mut tracker = tracker; -//! -//! // May panic! -//! // tracker.check_for_move(); -//! ``` -//! -//! In this sense, Rust does not guarantee that `check_for_move()` will never panic, because the -//! compiler is permitted to *move* `tracker` in many situations. -//! -//! Common smart-pointer types such as [`Box`] and [`&mut T`] also allow *moving* the underlying -//! *value* they point at: you can move out of a [`Box`], or you can use [`mem::replace`] to -//! move a `T` out of a [`&mut T`]. Therefore, putting a value (such as `tracker` above) behind a -//! pointer isn't enough on its own to ensure that its address does not change. -//! -//! # What is "pinning"? -//! [what-is-pinning]: self#what-is-pinning -//! -//! We say that a value has been *pinned* when it has been put into a state where it is guaranteed -//! to remain *located at the same place in memory* from the time it is pinned until its -//! [`drop`] is called. -//! -//! ## Address-sensitive values, AKA "when we need pinning" -//! [address-sensitive-values]: self#address-sensitive-values-aka-when-we-need-pinning -//! -//! Most values in Rust are entirely okay with being *moved* around at-will. -//! Types for which it is *always* the case that *any* value of that type can be -//! *moved* at-will should implement [`Unpin`], which we will discuss more [below][self#unpin]. -//! -//! [`Pin`] is specifically targeted at allowing the implementation of *safe interfaces* around -//! types which have some state during which they become "address-sensitive." A value in such an -//! "address-sensitive" state is *not* okay with being *moved* around at-will. Such a value must -//! stay *un-moved* and valid during the address-sensitive portion of its lifespan because some -//! interface is relying on those invariants to be true in order for its implementation to be sound. -//! -//! As a motivating example of a type which may become address-sensitive, consider a type which -//! contains a pointer to another piece of its own data, *i.e.* a "self-referential" type. In order -//! for such a type to be implemented soundly, the pointer which points into `self`'s data must be -//! proven valid whenever it is accessed. But if that value is *moved*, the pointer will still -//! point to the old address where the value was located and not into the new location of `self`, -//! thus becoming invalid. A key example of such self-referential types are the state machines -//! generated by the compiler to implement [`Future`] for `async fn`s. -//! -//! Such types that have an *address-sensitive* state usually follow a lifecycle -//! that looks something like so: -//! -//! 1. A value is created which can be freely moved around. -//! * e.g. calling an async function which returns a state machine implementing [`Future`] -//! 2. An operation causes the value to depend on its own address not changing -//! * e.g. calling [`poll`] for the first time on the produced [`Future`] -//! 3. Further pieces of the safe interface of the type use internal [`unsafe`] operations which -//! assume that the address of the value is stable -//! * e.g. subsequent calls to [`poll`] -//! 4. Before the value is invalidated (e.g. deallocated), it is *dropped*, giving it a chance to -//! notify anything with pointers to itself that those pointers will be invalidated -//! * e.g. [`drop`]ping the [`Future`] [^pin-drop-future] -//! -//! There are two possible ways to ensure the invariants required for 2. and 3. above (which -//! apply to any address-sensitive type, not just self-referential types) do not get broken. -//! -//! 1. Have the value detect when it is moved and update all the pointers that point to itself. -//! 2. Guarantee that the address of the value does not change (and that memory is not re-used -//! for anything else) during the time that the pointers to it are expected to be valid to -//! dereference. -//! -//! Since, as we discussed, Rust can move values without notifying them that they have moved, the -//! first option is ruled out. -//! -//! In order to implement the second option, we must in some way enforce its key invariant, -//! *i.e.* prevent the value from being *moved* or otherwise invalidated (you may notice this -//! sounds an awful lot like the definition of *pinning* a value). There a few ways one might be -//! able to enforce this invariant in Rust: -//! -//! 1. Offer a wholly `unsafe` API to interact with the object, thus requiring every caller to -//! uphold the invariant themselves -//! 2. Store the value that must not be moved behind a carefully managed pointer internal to -//! the object -//! 3. Leverage the type system to encode and enforce this invariant by presenting a restricted -//! API surface to interact with *any* object that requires these invariants -//! -//! The first option is quite obviously undesirable, as the [`unsafe`]ty of the interface will -//! become viral throughout all code that interacts with the object. -//! -//! The second option is a viable solution to the problem for some use cases, in particular -//! for self-referential types. Under this model, any type that has an address sensitive state -//! would ultimately store its data in something like a [`Box`], carefully manage internal -//! access to that data to ensure no *moves* or other invalidation occurs, and finally -//! provide a safe interface on top. -//! -//! There are a couple of linked disadvantages to using this model. The most significant is that -//! each individual object must assume it is *on its own* to ensure -//! that its data does not become *moved* or otherwise invalidated. Since there is no shared -//! contract between values of different types, an object cannot assume that others interacting -//! with it will properly respect the invariants around interacting with its data and must -//! therefore protect it from everyone. Because of this, *composition* of address-sensitive types -//! requires at least a level of pointer indirection each time a new object is added to the mix -//! (and, practically, a heap allocation). -//! -//! Although there were other reason as well, this issue of expensive composition is the key thing -//! that drove Rust towards adopting a different model. It is particularly a problem -//! when one considers, for example, the implications of composing together the [`Future`]s which -//! will eventually make up an asynchronous task (including address-sensitive `async fn` state -//! machines). It is plausible that there could be many layers of [`Future`]s composed together, -//! including multiple layers of `async fn`s handling different parts of a task. It was deemed -//! unacceptable to force indirection and allocation for each layer of composition in this case. -//! -//! [`Pin`] is an implementation of the third option. It allows us to solve the issues -//! discussed with the second option by building a *shared contractual language* around the -//! guarantees of "pinning" data. -//! -//! [^pin-drop-future]: Futures themselves do not ever need to notify other bits of code that -//! they are being dropped, however data structures like stack-based intrusive linked lists do. -//! -//! ## Using [`Pin`] to pin values -//! -//! In order to pin a value, we wrap a *pointer to that value* (of some type `Ptr`) in a -//! [`Pin`]. [`Pin`] can wrap any pointer type, forming a promise that the **pointee** -//! will not be *moved* or [otherwise invalidated][subtle-details]. -//! -//! We call such a [`Pin`]-wrapped pointer a **pinning pointer,** (or pinning reference, or pinning -//! `Box`, etc.) because its existence is the thing that is conceptually pinning the underlying -//! pointee in place: it is the metaphorical "pin" securing the data in place on the pinboard -//! (in memory). -//! -//! Notice that the thing wrapped by [`Pin`] is not the value which we want to pin itself, but -//! rather a pointer to that value! A [`Pin`] does not pin the `Ptr`; instead, it pins the -//! pointer's ***pointee** value*. -//! -//! ### Pinning as a library contract -//! -//! Pinning does not require nor make use of any compiler "magic"[^noalias], only a specific -//! contract between the [`unsafe`] parts of a library API and its users. -//! -//! It is important to stress this point as a user of the [`unsafe`] parts of the [`Pin`] API. -//! Practically, this means that performing the mechanics of "pinning" a value by creating a -//! [`Pin`] to it *does not* actually change the way the compiler behaves towards the -//! inner value! It is possible to use incorrect [`unsafe`] code to create a [`Pin`] to a -//! value which does not actually satisfy the invariants that a pinned value must satisfy, and in -//! this way lead to undefined behavior even in (from that point) fully safe code. Similarly, using -//! [`unsafe`], one may get access to a bare [`&mut T`] from a [`Pin`] and -//! use that to invalidly *move* the pinned value out. It is the job of the user of the -//! [`unsafe`] parts of the [`Pin`] API to ensure these invariants are not violated. -//! -//! This differs from e.g. [`UnsafeCell`] which changes the semantics of a program's compiled -//! output. A [`Pin`] is a handle to a value which we have promised we will not move out of, -//! but Rust still considers all values themselves to be fundamentally moveable through, *e.g.* -//! assignment or [`mem::replace`]. -//! -//! [^noalias]: There is a bit of nuance here that is still being decided about what the aliasing -//! semantics of `Pin<&mut T>` should be, but this is true as of today. -//! -//! ### How [`Pin`] prevents misuse in safe code -//! -//! In order to accomplish the goal of pinning the pointee value, [`Pin`] restricts access to -//! the wrapped `Ptr` type in safe code. Specifically, [`Pin`] disallows the ability to access -//! the wrapped pointer in ways that would allow the user to *move* the underlying pointee value or -//! otherwise re-use that memory for something else without using [`unsafe`]. For example, a -//! [`Pin<&mut T>`] makes it impossible to obtain the wrapped [&mut] T safely because -//! through that [&mut] T it would be possible to *move* the underlying value out of -//! the pointer with [`mem::replace`], etc. -//! -//! As discussed above, this promise must be upheld manually by [`unsafe`] code which interacts -//! with the [`Pin`] so that other [`unsafe`] code can rely on the pointee value being -//! *un-moved* and valid. Interfaces that operate on values which are in an address-sensitive state -//! accept an argument like [Pin]<[&mut] T> or [Pin]<[Box]\> to -//! indicate this contract to the caller. -//! -//! [As discussed below][drop-guarantee], opting in to using pinning guarantees in the interface -//! of an address-sensitive type has consequences for the implementation of some safe traits on -//! that type as well. -//! -//! ## Interaction between [`Deref`] and [`Pin`] -//! -//! Since [`Pin`] can wrap any pointer type, it uses [`Deref`] and [`DerefMut`] in -//! order to identify the type of the pinned pointee data and provide (restricted) access to it. -//! -//! A [`Pin`] where [`Ptr: Deref`][Deref] is a "`Ptr`-style pinning pointer" to a pinned -//! [`Ptr::Target`][Target] – so, a [Pin]<[Box]\> is an owned, pinning pointer to a -//! pinned `T`, and a [Pin]<[Rc]\> is a reference-counted, pinning pointer to a -//! pinned `T`. -//! -//! [`Pin`] also uses the [`::Target`][Target] type information to modify the -//! interface it is allowed to provide for interacting with that data (for example, when a -//! pinning pointer points at pinned data which implements [`Unpin`], as -//! [discussed below][self#unpin]). -//! -//! [`Pin`] requires that implementations of [`Deref`] and [`DerefMut`] on `Ptr` return a -//! pointer to the pinned data directly and do not *move* out of the `self` parameter during their -//! implementation of [`DerefMut::deref_mut`]. It is unsound for [`unsafe`] code to wrap pointer -//! types with such "malicious" implementations of [`Deref`]; see [`Pin::new_unchecked`] for -//! details. -//! -//! ## Fixing `AddrTracker` -//! -//! The guarantee of a stable address is necessary to make our `AddrTracker` example work. When -//! `check_for_move` sees a [Pin]<&mut AddrTracker>, it can safely assume that value -//! will exist at that same address until said value goes out of scope, and thus multiple calls -//! to it *cannot* panic. -//! -//! ``` -//! use std::marker::PhantomPinned; -//! use std::pin::Pin; -//! use std::pin::pin; -//! -//! #[derive(Default)] -//! struct AddrTracker { -//! prev_addr: Option, -//! // remove auto-implemented `Unpin` bound to mark this type as having some -//! // address-sensitive state. This is essential for our expected pinning -//! // guarantees to work, and is discussed more below. -//! _pin: PhantomPinned, -//! } -//! -//! impl AddrTracker { -//! fn check_for_move(self: Pin<&mut Self>) { -//! let current_addr = &*self as *const Self as usize; -//! match self.prev_addr { -//! None => { -//! // SAFETY: we do not move out of self -//! let self_data_mut = unsafe { self.get_unchecked_mut() }; -//! self_data_mut.prev_addr = Some(current_addr); -//! }, -//! Some(prev_addr) => assert_eq!(prev_addr, current_addr), -//! } -//! } -//! } -//! -//! // 1. Create the value, not yet in an address-sensitive state -//! let tracker = AddrTracker::default(); -//! -//! // 2. Pin the value by putting it behind a pinning pointer, thus putting -//! // it into an address-sensitive state -//! let mut ptr_to_pinned_tracker: Pin<&mut AddrTracker> = pin!(tracker); -//! ptr_to_pinned_tracker.as_mut().check_for_move(); -//! -//! // Trying to access `tracker` or pass `ptr_to_pinned_tracker` to anything that requires -//! // mutable access to a non-pinned version of it will no longer compile -//! -//! // 3. We can now assume that the tracker value will never be moved, thus -//! // this will never panic! -//! ptr_to_pinned_tracker.as_mut().check_for_move(); -//! ``` -//! -//! Note that this invariant is enforced by simply making it impossible to call code that would -//! perform a move on the pinned value. This is the case since the only way to access that pinned -//! value is through the pinning [Pin]<[&mut] T>>, which in turn restricts our access. -//! -//! ## [`Unpin`] -//! -//! The vast majority of Rust types have no address-sensitive states. These types -//! implement the [`Unpin`] auto-trait, which cancels the restrictive effects of -//! [`Pin`] when the *pointee* type `T` is [`Unpin`]. When [`T: Unpin`][Unpin], -//! [Pin]<[Box]\> functions identically to a non-pinning [`Box`]; similarly, -//! [Pin]<[&mut] T> would impose no additional restrictions above a regular -//! [`&mut T`]. -//! -//! The idea of this trait is to alleviate the reduced ergonomics of APIs that require the use -//! of [`Pin`] for soundness for some types, but which also want to be used by other types that -//! don't care about pinning. The prime example of such an API is [`Future::poll`]. There are many -//! [`Future`] types that don't care about pinning. These futures can implement [`Unpin`] and -//! therefore get around the pinning related restrictions in the API, while still allowing the -//! subset of [`Future`]s which *do* require pinning to be implemented soundly. -//! -//! Note that the interaction between a [`Pin`] and [`Unpin`] is through the type of the -//! **pointee** value, [`::Target`][Target]. Whether the `Ptr` type itself -//! implements [`Unpin`] does not affect the behavior of a [`Pin`]. For example, whether or not -//! [`Box`] is [`Unpin`] has no effect on the behavior of [Pin]<[Box]\>, because -//! `T` is the type of the pointee value, not [`Box`]. So, whether `T` implements [`Unpin`] is -//! the thing that will affect the behavior of the [Pin]<[Box]\>. -//! -//! Builtin types that are [`Unpin`] include all of the primitive types, like [`bool`], [`i32`], -//! and [`f32`], references ([&]T and [&mut] T), etc., as well as many -//! core and standard library types like [`Box`], [`String`], and more. -//! These types are marked [`Unpin`] because they do not have an address-sensitive state like the -//! ones we discussed above. If they did have such a state, those parts of their interface would be -//! unsound without being expressed through pinning, and they would then need to not -//! implement [`Unpin`]. -//! -//! The compiler is free to take the conservative stance of marking types as [`Unpin`] so long as -//! all of the types that compose its fields are also [`Unpin`]. This is because if a type -//! implements [`Unpin`], then it is unsound for that type's implementation to rely on -//! pinning-related guarantees for soundness, *even* when viewed through a "pinning" pointer! It is -//! the responsibility of the implementor of a type that relies upon pinning for soundness to -//! ensure that type is *not* marked as [`Unpin`] by adding [`PhantomPinned`] field. This is -//! exactly what we did with our `AddrTracker` example above. Without doing this, you *must not* -//! rely on pinning-related guarantees to apply to your type! -//! -//! If need to truly pin a value of a foreign or built-in type that implements [`Unpin`], you'll -//! need to create your own wrapper type around the [`Unpin`] type you want to pin and then -//! opts-out of [`Unpin`] using [`PhantomPinned`]. -//! -//! Exposing access to the inner field which you want to remain pinned must then be carefully -//! considered as well! Remember, exposing a method that gives access to a -//! [Pin]<[&mut] InnerT>> where InnerT: [Unpin] would allow safe code to -//! trivially move the inner value out of that pinning pointer, which is precisely what you're -//! seeking to prevent! Exposing a field of a pinned value through a pinning pointer is called -//! "projecting" a pin, and the more general case of deciding in which cases a pin should be able -//! to be projected or not is called "structural pinning." We will go into more detail about this -//! [below][structural-pinning]. -//! -//! # Examples of address-sensitive types -//! [address-sensitive-examples]: #examples-of-address-sensitive-types -//! -//! ## A self-referential struct -//! [self-ref]: #a-self-referential-struct -//! [`Unmovable`]: #a-self-referential-struct -//! -//! Self-referential structs are the simplest kind of address-sensitive type. -//! -//! It is often useful for a struct to hold a pointer back into itself, which -//! allows the program to efficiently track subsections of the struct. -//! Below, the `slice` field is a pointer into the `data` field, which -//! we could imagine being used to track a sliding window of `data` in parser -//! code. -//! -//! As mentioned before, this pattern is also used extensively by compiler-generated -//! [`Future`]s. -//! -//! ```rust -//! use std::pin::Pin; -//! use std::marker::PhantomPinned; -//! use std::ptr::NonNull; -//! -//! /// This is a self-referential struct because `self.slice` points into `self.data`. -//! struct Unmovable { -//! /// Backing buffer. -//! data: [u8; 64], -//! /// Points at `self.data` which we know is itself non-null. Raw pointer because we can't do -//! /// this with a normal reference. -//! slice: NonNull<[u8]>, -//! /// Suppress `Unpin` so that this cannot be moved out of a `Pin` once constructed. -//! _pin: PhantomPinned, -//! } -//! -//! impl Unmovable { -//! /// Create a new `Unmovable`. -//! /// -//! /// To ensure the data doesn't move we place it on the heap behind a pinning Box. -//! /// Note that the data is pinned, but the `Pin>` which is pinning it can -//! /// itself still be moved. This is important because it means we can return the pinning -//! /// pointer from the function, which is itself a kind of move! -//! fn new() -> Pin> { -//! let res = Unmovable { -//! data: [0; 64], -//! // We only create the pointer once the data is in place -//! // otherwise it will have already moved before we even started. -//! slice: NonNull::from(&[]), -//! _pin: PhantomPinned, -//! }; -//! // First we put the data in a box, which will be its final resting place -//! let mut boxed = Box::new(res); -//! -//! // Then we make the slice field point to the proper part of that boxed data. -//! // From now on we need to make sure we don't move the boxed data. -//! boxed.slice = NonNull::from(&boxed.data); -//! -//! // To do that, we pin the data in place by pointing to it with a pinning -//! // (`Pin`-wrapped) pointer. -//! // -//! // `Box::into_pin` makes existing `Box` pin the data in-place without moving it, -//! // so we can safely do this now *after* inserting the slice pointer above, but we have -//! // to take care that we haven't performed any other semantic moves of `res` in between. -//! let pin = Box::into_pin(boxed); -//! -//! // Now we can return the pinned (through a pinning Box) data -//! pin -//! } -//! } -//! -//! let unmovable: Pin> = Unmovable::new(); -//! -//! // The inner pointee `Unmovable` struct will now never be allowed to move. -//! // Meanwhile, we are free to move the pointer around. -//! # #[allow(unused_mut)] -//! let mut still_unmoved = unmovable; -//! assert_eq!(still_unmoved.slice, NonNull::from(&still_unmoved.data)); -//! -//! // We cannot mutably dereference a `Pin` unless the pointee is `Unpin` or we use unsafe. -//! // Since our type doesn't implement `Unpin`, this will fail to compile. -//! // let mut new_unmoved = Unmovable::new(); -//! // std::mem::swap(&mut *still_unmoved, &mut *new_unmoved); -//! ``` -//! -//! ## An intrusive, doubly-linked list -//! [linked-list]: #an-intrusive-doubly-linked-list -//! -//! In an intrusive doubly-linked list, the collection itself does not own the memory in which -//! each of its elements is stored. Instead, each client is free to allocate space for elements it -//! adds to the list in whichever manner it likes, including on the stack! Elements can live on a -//! stack frame that lives shorter than the collection does provided the elements that live in a -//! given stack frame are removed from the list before going out of scope. -//! -//! To make such an intrusive data structure work, every element stores pointers to its predecessor -//! and successor within its own data, rather than having the list structure itself managing those -//! pointers. It is in this sense that the structure is "intrusive": the details of how an -//! element is stored within the larger structure "intrudes" on the implementation of the element -//! type itself! -//! -//! The full implementation details of such a data structure are outside the scope of this -//! documentation, but we will discuss how [`Pin`] can help to do so. -//! -//! Using such an intrusive pattern, elements may only be added when they are pinned. If we think -//! about the consequences of adding non-pinned values to such a list, this becomes clear: -//! -//! *Moving* or otherwise invalidating an element's data would invalidate the pointers back to it -//! which are stored in the elements ahead and behind it. Thus, in order to soundly dereference -//! the pointers stored to the next and previous elements, we must satisfy the guarantee that -//! nothing has invalidated those pointers (which point to data that we do not own). -//! -//! Moreover, the [`Drop`][Drop] implementation of each element must in some way notify its -//! predecessor and successor elements that it should be removed from the list before it is fully -//! destroyed, otherwise the pointers back to it would again become invalidated. -//! -//! Crucially, this means we have to be able to rely on [`drop`] always being called before an -//! element is invalidated. If an element could be deallocated or otherwise invalidated without -//! calling [`drop`], the pointers to it stored in its neighboring elements would -//! become invalid, which would break the data structure. -//! -//! Therefore, pinning data also comes with [the "`Drop` guarantee"][drop-guarantee]. -//! -//! # Subtle details and the `Drop` guarantee -//! [subtle-details]: self#subtle-details-and-the-drop-guarantee -//! [drop-guarantee]: self#subtle-details-and-the-drop-guarantee -//! -//! The purpose of pinning is not *just* to prevent a value from being *moved*, but more -//! generally to be able to rely on the pinned value *remaining valid **at a specific place*** in -//! memory. -//! -//! To do so, pinning a value adds an *additional* invariant that must be upheld in order for use -//! of the pinned data to be valid, on top of the ones that must be upheld for a non-pinned value -//! of the same type to be valid: -//! -//! From the moment a value is pinned by constructing a [`Pin`]ning pointer to it, that value -//! must *remain, **valid***, at that same address in memory, *until its [`drop`] handler is -//! called.* -//! -//! There is some subtlety to this which we have not yet talked about in detail. The invariant -//! described above means that, yes, -//! -//! 1. The value must not be moved out of its location in memory -//! -//! but it also implies that, -//! -//! 2. The memory location that stores the value must not get invalidated or otherwise repurposed -//! during the lifespan of the pinned value until its [`drop`] returns or panics -//! -//! This point is subtle but required for intrusive data structures to be implemented soundly. -//! -//! ## `Drop` guarantee -//! -//! There needs to be a way for a pinned value to notify any code that is relying on its pinned -//! status that it is about to be destroyed. In this way, the dependent code can remove the -//! pinned value's address from its data structures or otherwise change its behavior with the -//! knowledge that it can no longer rely on that value existing at the location it was pinned to. -//! -//! Thus, in any situation where we may want to overwrite a pinned value, that value's [`drop`] must -//! be called beforehand (unless the pinned value implements [`Unpin`], in which case we can ignore -//! all of [`Pin`]'s guarantees, as usual). -//! -//! The most common storage-reuse situations occur when a value on the stack is destroyed as part -//! of a function return and when heap storage is freed. In both cases, [`drop`] gets run for us -//! by Rust when using standard safe code. However, for manual heap allocations or otherwise -//! custom-allocated storage, [`unsafe`] code must make sure to call [`ptr::drop_in_place`] before -//! deallocating and re-using said storage. -//! -//! In addition, storage "re-use"/invalidation can happen even if no storage is (de-)allocated. -//! For example, if we had an [`Option`] which contained a `Some(v)` where `v` is pinned, then `v` -//! would be invalidated by setting that option to `None`. -//! -//! Similarly, if a [`Vec`] was used to store pinned values and [`Vec::set_len`] was used to -//! manually "kill" some elements of a vector, all of the items "killed" would become invalidated, -//! which would be *undefined behavior* if those items were pinned. -//! -//! Both of these cases are somewhat contrived, but it is crucial to remember that [`Pin`]ned data -//! *must* be [`drop`]ped before it is invalidated; not just to prevent memory leaks, but as a -//! matter of soundness. As a corollary, the following code can *never* be made safe: -//! -//! ```rust -//! # use std::mem::ManuallyDrop; -//! # use std::pin::Pin; -//! # struct Type; -//! // Pin something inside a `ManuallyDrop`. This is fine on its own. -//! let mut pin: Pin>> = Box::pin(ManuallyDrop::new(Type)); -//! -//! // However, creating a pinning mutable reference to the type *inside* -//! // the `ManuallyDrop` is not! -//! let inner: Pin<&mut Type> = unsafe { -//! Pin::map_unchecked_mut(pin.as_mut(), |x| &mut **x) -//! }; -//! ``` -//! -//! Because [`mem::ManuallyDrop`] inhibits the destructor of `Type`, it won't get run when the -//! [Box]<[ManuallyDrop]\> is dropped, thus violating the drop guarantee of the -//! [Pin]<[&mut] Type>>. -//! -//! Of course, *leaking* memory in such a way that its underlying storage will never get invalidated -//! or re-used is still fine: [`mem::forget`]ing a [`Box`] prevents its storage from ever getting -//! re-used, so the [`drop`] guarantee is still satisfied. -//! -//! # Implementing an address-sensitive type. -//! -//! This section goes into detail on important considerations for implementing your own -//! address-sensitive types, which are different from merely using [`Pin`] in a generic -//! way. -//! -//! ## Implementing [`Drop`] for types with address-sensitive states -//! [drop-impl]: self#implementing-drop-for-types-with-address-sensitive-states -//! -//! The [`drop`] function takes [`&mut self`], but this is called *even if that `self` has been -//! pinned*! Implementing [`Drop`] for a type with address-sensitive states, because if `self` was -//! indeed in an address-sensitive state before [`drop`] was called, it is as if the compiler -//! automatically called [`Pin::get_unchecked_mut`]. -//! -//! This can never cause a problem in purely safe code because creating a pinning pointer to -//! a type which has an address-sensitive (thus does not implement `Unpin`) requires `unsafe`, -//! but it is important to note that choosing to take advantage of pinning-related guarantees -//! to justify validity in the implementation of your type has consequences for that type's -//! [`Drop`][Drop] implementation as well: if an element of your type could have been pinned, -//! you must treat [`Drop`][Drop] as implicitly taking self: [Pin]<[&mut] Self>. -//! -//! You should implement [`Drop`] as follows: -//! -//! ```rust,no_run -//! # use std::pin::Pin; -//! # struct Type; -//! impl Drop for Type { -//! fn drop(&mut self) { -//! // `new_unchecked` is okay because we know this value is never used -//! // again after being dropped. -//! inner_drop(unsafe { Pin::new_unchecked(self)}); -//! fn inner_drop(this: Pin<&mut Type>) { -//! // Actual drop code goes here. -//! } -//! } -//! } -//! ``` -//! -//! The function `inner_drop` has the signature that [`drop`] *should* have in this situation. -//! This makes sure that you do not accidentally use `self`/`this` in a way that is in conflict -//! with pinning's invariants. -//! -//! Moreover, if your type is [`#[repr(packed)]`][packed], the compiler will automatically -//! move fields around to be able to drop them. It might even do -//! that for fields that happen to be sufficiently aligned. As a consequence, you cannot use -//! pinning with a [`#[repr(packed)]`][packed] type. -//! -//! ### Implementing [`Drop`] for pointer types which will be used as [`Pin`]ning pointers -//! -//! It should further be noted that creating a pinning pointer of some type `Ptr` *also* carries -//! with it implications on the way that `Ptr` type must implement [`Drop`] -//! (as well as [`Deref`] and [`DerefMut`])! When implementing a pointer type that may be used as -//! a pinning pointer, you must also take the same care described above not to *move* out of or -//! otherwise invalidate the pointee during [`Drop`], [`Deref`], or [`DerefMut`] -//! implementations. -//! -//! ## "Assigning" pinned data -//! -//! Although in general it is not valid to swap data or assign through a [`Pin`] for the same -//! reason that reusing a pinned object's memory is invalid, it is possible to do validly when -//! implemented with special care for the needs of the exact data structure which is being -//! modified. For example, the assigning function must know how to update all uses of the pinned -//! address (and any other invariants necessary to satisfy validity for that type). For -//! [`Unmovable`] (from the example above), we could write an assignment function like so: -//! -//! ``` -//! # use std::pin::Pin; -//! # use std::marker::PhantomPinned; -//! # use std::ptr::NonNull; -//! # struct Unmovable { -//! # data: [u8; 64], -//! # slice: NonNull<[u8]>, -//! # _pin: PhantomPinned, -//! # } -//! # -//! impl Unmovable { -//! // Copies the contents of `src` into `self`, fixing up the self-pointer -//! // in the process. -//! fn assign(self: Pin<&mut Self>, src: Pin<&mut Self>) { -//! unsafe { -//! let unpinned_self = Pin::into_inner_unchecked(self); -//! let unpinned_src = Pin::into_inner_unchecked(src); -//! *unpinned_self = Self { -//! data: unpinned_src.data, -//! slice: NonNull::from(&mut []), -//! _pin: PhantomPinned, -//! }; -//! -//! let data_ptr = unpinned_src.data.as_ptr() as *const u8; -//! let slice_ptr = unpinned_src.slice.as_ptr() as *const u8; -//! let offset = slice_ptr.offset_from(data_ptr) as usize; -//! let len = (*unpinned_src.slice.as_ptr()).len(); -//! -//! unpinned_self.slice = NonNull::from(&mut unpinned_self.data[offset..offset+len]); -//! } -//! } -//! } -//! ``` -//! -//! Even though we can't have the compiler do the assignment for us, it's possible to write -//! such specialized functions for types that might need it. -//! -//! Note that it _is_ possible to assign generically through a [`Pin`] by way of [`Pin::set()`]. -//! This does not violate any guarantees, since it will run [`drop`] on the pointee value before -//! assigning the new value. Thus, the [`drop`] implementation still has a chance to perform the -//! necessary notifications to dependent values before the memory location of the original pinned -//! value is overwritten. -//! -//! ## Projections and Structural Pinning -//! [structural-pinning]: self#projections-and-structural-pinning -//! -//! With ordinary structs, it is natural that we want to add *projection* methods that allow -//! borrowing one or more of the inner fields of a struct when the caller has access to a -//! borrow of the whole struct: -//! -//! ``` -//! # struct Field; -//! struct Struct { -//! field: Field, -//! // ... -//! } -//! -//! impl Struct { -//! fn field(&mut self) -> &mut Field { &mut self.field } -//! } -//! ``` -//! -//! When working with address-sensitive types, it's not obvious what the signature of these -//! functions should be. If `field` takes self: [Pin]<[&mut Struct][&mut]>, should it -//! return [`&mut Field`] or [Pin]<[`&mut Field`]>? This question also arises with -//! `enum`s and wrapper types like [`Vec`], [`Box`], and [`RefCell`]. (This question -//! applies just as well to shared references, but we'll examine the more common case of mutable -//! references for illustration) -//! -//! It turns out that it's up to the author of `Struct` to decide which type the "projection" -//! should produce. The choice must be *consistent* though: if a pin is projected to a field -//! in one place, then it should very likely not be exposed elsewhere without projecting the -//! pin. -//! -//! As the author of a data structure, you get to decide for each field whether pinning -//! "propagates" to this field or not. Pinning that propagates is also called "structural", -//! because it follows the structure of the type. -//! -//! This choice depends on what guarantees you need from the field for your [`unsafe`] code to work. -//! If the field is itself address-sensitive, or participates in the parent struct's address -//! sensitivity, it will need to be structurally pinned. -//! -//! A useful test is if [`unsafe`] code that consumes [Pin]\<[&mut Struct][&mut]> -//! also needs to take note of the address of the field itself, it may be evidence that that field -//! is structurally pinned. Unfortunately, there are no hard-and-fast rules. -//! -//! ### Choosing pinning *not to be* structural for `field`... -//! -//! While counter-intuitive, it's often the easier choice: if you do not expose a -//! [Pin]<[&mut] Field>, you do not need to be careful about other code -//! moving out of that field, you just have to ensure is that you never create pinning -//! reference to that field. This does of course also mean that if you decide a field does not -//! have structural pinning, you must not write [`unsafe`] code that assumes (invalidly) that the -//! field *is* structurally pinned! -//! -//! Fields without structural pinning may have a projection method that turns -//! [Pin]<[&mut] Struct> into [`&mut Field`]: -//! -//! ```rust,no_run -//! # use std::pin::Pin; -//! # type Field = i32; -//! # struct Struct { field: Field } -//! impl Struct { -//! fn field(self: Pin<&mut Self>) -> &mut Field { -//! // This is okay because `field` is never considered pinned, therefore we do not -//! // need to uphold any pinning guarantees for this field in particular. Of course, -//! // we must not elsewhere assume this field *is* pinned if we choose to expose -//! // such a method! -//! unsafe { &mut self.get_unchecked_mut().field } -//! } -//! } -//! ``` -//! -//! You may also in this situation impl [Unpin] for Struct {} *even if* the type of -//! `field` is not [`Unpin`]. Since we have explicitly chosen not to care about pinning guarantees -//! for `field`, the way `field`'s type interacts with pinning is no longer relevant in the -//! context of its use in `Struct`. -//! -//! ### Choosing pinning *to be* structural for `field`... -//! -//! The other option is to decide that pinning is "structural" for `field`, -//! meaning that if the struct is pinned then so is the field. -//! -//! This allows writing a projection that creates a [Pin]<[`&mut Field`]>, thus -//! witnessing that the field is pinned: -//! -//! ```rust,no_run -//! # use std::pin::Pin; -//! # type Field = i32; -//! # struct Struct { field: Field } -//! impl Struct { -//! fn field(self: Pin<&mut Self>) -> Pin<&mut Field> { -//! // This is okay because `field` is pinned when `self` is. -//! unsafe { self.map_unchecked_mut(|s| &mut s.field) } -//! } -//! } -//! ``` -//! -//! Structural pinning comes with a few extra requirements: -//! -//! 1. *Structural [`Unpin`].* A struct can be [`Unpin`] only if all of its -//! structurally-pinned fields are, too. This is [`Unpin`]'s behavior by default. -//! However, as a libray author, it is your responsibility not to write something like -//! impl\ [Unpin] for Struct\ {} and then offer a method that provides -//! structural pinning to an inner field of `T`, which may not be [`Unpin`]! (Adding *any* -//! projection operation requires unsafe code, so the fact that [`Unpin`] is a safe trait does -//! not break the principle that you only have to worry about any of this if you use -//! [`unsafe`]) -//! -//! 2. *Pinned Destruction.* As discussed [above][drop-impl], [`drop`] takes -//! [`&mut self`], but the struct (and hence its fields) might have been pinned -//! before. The destructor must be written as if its argument was -//! self: [Pin]\<[`&mut Self`]>, instead. -//! -//! As a consequence, the struct *must not* be [`#[repr(packed)]`][packed]. -//! -//! 3. *Structural Notice of Destruction.* You must uphold the -//! [`Drop` guarantee][drop-guarantee]: once your struct is pinned, the struct's storage cannot -//! be re-used without calling the structurally-pinned fields' destructors, as well. -//! -//! This can be tricky, as witnessed by [`VecDeque`]: the destructor of [`VecDeque`] -//! can fail to call [`drop`] on all elements if one of the destructors panics. This violates -//! the [`Drop` guarantee][drop-guarantee], because it can lead to elements being deallocated -//! without their destructor being called. -//! -//! [`VecDeque`] has no pinning projections, so its destructor is sound. If it wanted -//! to provide such structural pinning, its destructor would need to abort the process if any -//! of the destructors panicked. -//! -//! 4. You must not offer any other operations that could lead to data being *moved* out of -//! the structural fields when your type is pinned. For example, if the struct contains an -//! [`Option`] and there is a [`take`][Option::take]-like operation with type -//! fn([Pin]<[&mut Struct\][&mut]>) -> [`Option`], -//! then that operation can be used to move a `T` out of a pinned `Struct` – which -//! means pinning cannot be structural for the field holding this data. -//! -//! For a more complex example of moving data out of a pinned type, -//! imagine if [`RefCell`] had a method -//! fn get_pin_mut(self: [Pin]<[`&mut Self`]>) -> [Pin]<[`&mut T`]>. -//! Then we could do the following: -//! ```compile_fail -//! # use std::cell::RefCell; -//! # use std::pin::Pin; -//! fn exploit_ref_cell(rc: Pin<&mut RefCell>) { -//! // Here we get pinned access to the `T`. -//! let _: Pin<&mut T> = rc.as_mut().get_pin_mut(); -//! -//! // And here we have `&mut T` to the same data. -//! let shared: &RefCell = rc.into_ref().get_ref(); -//! let borrow = shared.borrow_mut(); -//! let content = &mut *borrow; -//! } -//! ``` -//! This is catastrophic: it means we can first pin the content of the -//! [`RefCell`] (using [RefCell]::get_pin_mut) and then move that -//! content using the mutable reference we got later. -//! -//! ### Structural Pinning examples -//! -//! For a type like [`Vec`], both possibilities (structural pinning or not) make -//! sense. A [`Vec`] with structural pinning could have `get_pin`/`get_pin_mut` -//! methods to get pinning references to elements. However, it could *not* allow calling -//! [`pop`][Vec::pop] on a pinned [`Vec`] because that would move the (structurally -//! pinned) contents! Nor could it allow [`push`][Vec::push], which might reallocate and thus also -//! move the contents. -//! -//! A [`Vec`] without structural pinning could -//! impl\ [Unpin] for [`Vec`], because the contents are never pinned -//! and the [`Vec`] itself is fine with being moved as well. -//! At that point pinning just has no effect on the vector at all. -//! -//! In the standard library, pointer types generally do not have structural pinning, -//! and thus they do not offer pinning projections. This is why [`Box`]: [Unpin] -//! holds for all `T`. It makes sense to do this for pointer types, because moving the -//! [`Box`] does not actually move the `T`: the [`Box`] can be freely -//! movable (aka [`Unpin`]) even if the `T` is not. In fact, even [Pin]<[`Box`]> and -//! [Pin]<[`&mut T`]> are always [`Unpin`] themselves, for the same reason: -//! their contents (the `T`) are pinned, but the pointers themselves can be moved without moving -//! the pinned data. For both [`Box`] and [Pin]<[`Box`]>, -//! whether the content is pinned is entirely independent of whether the -//! pointer is pinned, meaning pinning is *not* structural. -//! -//! When implementing a [`Future`] combinator, you will usually need structural pinning -//! for the nested futures, as you need to get pinning ([`Pin`]-wrapped) references to them to -//! call [`poll`]. But if your combinator contains any other data that does not need to be pinned, -//! you can make those fields not structural and hence freely access them with a -//! mutable reference even when you just have [Pin]<[`&mut Self`]> -//! (such as in your own [`poll`] implementation). -//! -//! [`&mut T`]: &mut -//! [`&mut self`]: &mut -//! [`&mut Self`]: &mut -//! [`&mut Field`]: &mut -//! [Deref]: crate::ops::Deref "ops::Deref" -//! [`Deref`]: crate::ops::Deref "ops::Deref" -//! [Target]: crate::ops::Deref::Target "ops::Deref::Target" -//! [`DerefMut`]: crate::ops::DerefMut "ops::DerefMut" -//! [`mem::swap`]: crate::mem::swap "mem::swap" -//! [`mem::forget`]: crate::mem::forget "mem::forget" -//! [ManuallyDrop]: crate::mem::ManuallyDrop "ManuallyDrop" -//! [RefCell]: crate::cell::RefCell "cell::RefCell" -//! [`drop`]: Drop::drop -//! [`ptr::write`]: crate::ptr::write "ptr::write" -//! [`Future`]: crate::future::Future "future::Future" -//! [drop-impl]: #drop-implementation -//! [drop-guarantee]: #drop-guarantee -//! [`poll`]: crate::future::Future::poll "future::Future::poll" -//! [&]: reference "shared reference" -//! [&mut]: reference "mutable reference" -//! [`unsafe`]: ../../std/keyword.unsafe.html "keyword unsafe" -//! [packed]: https://doc.rust-lang.org/nomicon/other-reprs.html#reprpacked -//! [`std::alloc`]: ../../std/alloc/index.html -//! [`Box`]: ../../std/boxed/struct.Box.html -//! [Box]: ../../std/boxed/struct.Box.html "Box" -//! [`Box`]: ../../std/boxed/struct.Box.html "Box" -//! [`Rc`]: ../../std/rc/struct.Rc.html -//! [Rc]: ../../std/rc/struct.Rc.html "rc::Rc" -//! [`Vec`]: ../../std/vec/struct.Vec.html -//! [Vec]: ../../std/vec/struct.Vec.html "Vec" -//! [`Vec`]: ../../std/vec/struct.Vec.html "Vec" -//! [`Vec::set_len`]: ../../std/vec/struct.Vec.html#method.set_len "Vec::set_len" -//! [Vec::pop]: ../../std/vec/struct.Vec.html#method.pop "Vec::pop" -//! [Vec::push]: ../../std/vec/struct.Vec.html#method.push "Vec::push" -//! [`Vec::set_len`]: ../../std/vec/struct.Vec.html#method.set_len -//! [`VecDeque`]: ../../std/collections/struct.VecDeque.html -//! [VecDeque]: ../../std/collections/struct.VecDeque.html "collections::VecDeque" -//! [`String`]: ../../std/string/struct.String.html "String" - -#![stable(feature = "pin", since = "1.33.0")] - -use crate::cmp; -use crate::fmt; -use crate::hash::{Hash, Hasher}; -use crate::ops::{CoerceUnsized, Deref, DerefMut, DerefPure, DispatchFromDyn, Receiver}; - -#[allow(unused_imports)] -use crate::{ - cell::{RefCell, UnsafeCell}, - future::Future, - marker::PhantomPinned, - mem, ptr, -}; - -/// A pointer which pins its pointee in place. -/// -/// [`Pin`] is a wrapper around some kind of pointer `Ptr` which makes that pointer "pin" its -/// pointee value in place, thus preventing the value referenced by that pointer from being moved -/// or otherwise invalidated at that place in memory unless it implements [`Unpin`]. -/// -/// *See the [`pin` module] documentation for a more thorough exploration of pinning.* -/// -/// ## Pinning values with [`Pin`] -/// -/// In order to pin a value, we wrap a *pointer to that value* (of some type `Ptr`) in a -/// [`Pin`]. [`Pin`] can wrap any pointer type, forming a promise that the **pointee** -/// will not be *moved* or [otherwise invalidated][subtle-details]. If the pointee value's type -/// implements [`Unpin`], we are free to disregard these requirements entirely and can wrap any -/// pointer to that value in [`Pin`] directly via [`Pin::new`]. If the pointee value's type does -/// not implement [`Unpin`], then Rust will not let us use the [`Pin::new`] function directly and -/// we'll need to construct a [`Pin`]-wrapped pointer in one of the more specialized manners -/// discussed below. -/// -/// We call such a [`Pin`]-wrapped pointer a **pinning pointer** (or pinning ref, or pinning -/// [`Box`], etc.) because its existence is the thing that is pinning the underlying pointee in -/// place: it is the metaphorical "pin" securing the data in place on the pinboard (in memory). -/// -/// It is important to stress that the thing in the [`Pin`] is not the value which we want to pin -/// itself, but rather a pointer to that value! A [`Pin`] does not pin the `Ptr` but rather -/// the pointer's ***pointee** value*. -/// -/// The most common set of types which require pinning related guarantees for soundness are the -/// compiler-generated state machines that implement [`Future`] for the return value of -/// `async fn`s. These compiler-generated [`Future`]s may contain self-referential pointers, one -/// of the most common use cases for [`Pin`]. More details on this point are provided in the -/// [`pin` module] docs, but suffice it to say they require the guarantees provided by pinning to -/// be implemented soundly. -/// -/// This requirement for the implementation of `async fn`s means that the [`Future`] trait -/// requires all calls to [`poll`] to use a self: [Pin]\<&mut Self> parameter instead -/// of the usual `&mut self`. Therefore, when manually polling a future, you will need to pin it -/// first. -/// -/// You may notice that `async fn`-sourced [`Future`]s are only a small percentage of all -/// [`Future`]s that exist, yet we had to modify the signature of [`poll`] for all [`Future`]s -/// to accommodate them. This is unfortunate, but there is a way that the language attempts to -/// alleviate the extra friction that this API choice incurs: the [`Unpin`] trait. -/// -/// The vast majority of Rust types have no reason to ever care about being pinned. These -/// types implement the [`Unpin`] trait, which entirely opts all values of that type out of -/// pinning-related guarantees. For values of these types, pinning a value by pointing to it with a -/// [`Pin`] will have no actual effect. -/// -/// The reason this distinction exists is exactly to allow APIs like [`Future::poll`] to take a -/// [`Pin`] as an argument for all types while only forcing [`Future`] types that actually -/// care about pinning guarantees pay the ergonomics cost. For the majority of [`Future`] types -/// that don't have a reason to care about being pinned and therefore implement [`Unpin`], the -/// [Pin]\<&mut Self> will act exactly like a regular `&mut Self`, allowing direct -/// access to the underlying value. Only types that *don't* implement [`Unpin`] will be restricted. -/// -/// ### Pinning a value of a type that implements [`Unpin`] -/// -/// If the type of the value you need to "pin" implements [`Unpin`], you can trivially wrap any -/// pointer to that value in a [`Pin`] by calling [`Pin::new`]. -/// -/// ``` -/// use std::pin::Pin; -/// -/// // Create a value of a type that implements `Unpin` -/// let mut unpin_future = std::future::ready(5); -/// -/// // Pin it by creating a pinning mutable reference to it (ready to be `poll`ed!) -/// let my_pinned_unpin_future: Pin<&mut _> = Pin::new(&mut unpin_future); -/// ``` -/// -/// ### Pinning a value inside a [`Box`] -/// -/// The simplest and most flexible way to pin a value that does not implement [`Unpin`] is to put -/// that value inside a [`Box`] and then turn that [`Box`] into a "pinning [`Box`]" by wrapping it -/// in a [`Pin`]. You can do both of these in a single step using [`Box::pin`]. Let's see an -/// example of using this flow to pin a [`Future`] returned from calling an `async fn`, a common -/// use case as described above. -/// -/// ``` -/// use std::pin::Pin; -/// -/// async fn add_one(x: u32) -> u32 { -/// x + 1 -/// } -/// -/// // Call the async function to get a future back -/// let fut = add_one(42); -/// -/// // Pin the future inside a pinning box -/// let pinned_fut: Pin> = Box::pin(fut); -/// ``` -/// -/// If you have a value which is already boxed, for example a [`Box`][Box], you can pin -/// that value in-place at its current memory address using [`Box::into_pin`]. -/// -/// ``` -/// use std::pin::Pin; -/// use std::future::Future; -/// -/// async fn add_one(x: u32) -> u32 { -/// x + 1 -/// } -/// -/// fn boxed_add_one(x: u32) -> Box> { -/// Box::new(add_one(x)) -/// } -/// -/// let boxed_fut = boxed_add_one(42); -/// -/// // Pin the future inside the existing box -/// let pinned_fut: Pin> = Box::into_pin(boxed_fut); -/// ``` -/// -/// There are similar pinning methods offered on the other standard library smart pointer types -/// as well, like [`Rc`] and [`Arc`]. -/// -/// ### Pinning a value on the stack using [`pin!`] -/// -/// There are some situations where it is desirable or even required (for example, in a `#[no_std]` -/// context where you don't have access to the standard library or allocation in general) to -/// pin a value which does not implement [`Unpin`] to its location on the stack. Doing so is -/// possible using the [`pin!`] macro. See its documentation for more. -/// -/// ## Layout and ABI -/// -/// [`Pin`] is guaranteed to have the same memory layout and ABI[^noalias] as `Ptr`. -/// -/// [^noalias]: There is a bit of nuance here that is still being decided about whether the -/// aliasing semantics of `Pin<&mut T>` should be different than `&mut T`, but this is true as of -/// today. -/// -/// [`pin!`]: crate::pin::pin "pin!" -/// [`Future`]: crate::future::Future "Future" -/// [`poll`]: crate::future::Future::poll "Future::poll" -/// [`Future::poll`]: crate::future::Future::poll "Future::poll" -/// [`pin` module]: self "pin module" -/// [`Rc`]: ../../std/rc/struct.Rc.html "Rc" -/// [`Arc`]: ../../std/sync/struct.Arc.html "Arc" -/// [Box]: ../../std/boxed/struct.Box.html "Box" -/// [`Box`]: ../../std/boxed/struct.Box.html "Box" -/// [`Box::pin`]: ../../std/boxed/struct.Box.html#method.pin "Box::pin" -/// [`Box::into_pin`]: ../../std/boxed/struct.Box.html#method.into_pin "Box::into_pin" -/// [subtle-details]: self#subtle-details-and-the-drop-guarantee "pin subtle details" -/// [`unsafe`]: ../../std/keyword.unsafe.html "keyword unsafe" -// -// Note: the `Clone` derive below causes unsoundness as it's possible to implement -// `Clone` for mutable references. -// See for more details. -#[stable(feature = "pin", since = "1.33.0")] -#[lang = "pin"] -#[fundamental] -#[repr(transparent)] -#[derive(Copy, Clone)] -pub struct Pin { - // FIXME(#93176): this field is made `#[unstable] #[doc(hidden)] pub` to: - // - deter downstream users from accessing it (which would be unsound!), - // - let the `pin!` macro access it (such a macro requires using struct - // literal syntax in order to benefit from lifetime extension). - // - // However, if the `Deref` impl exposes a field with the same name as this - // field, then the two will collide, resulting in a confusing error when the - // user attempts to access the field through a `Pin`. Therefore, the - // name `__pointer` is designed to be unlikely to collide with any other - // field. Long-term, macro hygiene is expected to offer a more robust - // alternative, alongside `unsafe` fields. - #[unstable(feature = "unsafe_pin_internals", issue = "none")] - #[doc(hidden)] - pub __pointer: Ptr, -} - -// The following implementations aren't derived in order to avoid soundness -// issues. `&self.__pointer` should not be accessible to untrusted trait -// implementations. -// -// See for more details. - -#[stable(feature = "pin_trait_impls", since = "1.41.0")] -impl PartialEq> for Pin -where - Ptr::Target: PartialEq, -{ - fn eq(&self, other: &Pin) -> bool { - Ptr::Target::eq(self, other) - } - - fn ne(&self, other: &Pin) -> bool { - Ptr::Target::ne(self, other) - } -} - -#[stable(feature = "pin_trait_impls", since = "1.41.0")] -impl> Eq for Pin {} - -#[stable(feature = "pin_trait_impls", since = "1.41.0")] -impl PartialOrd> for Pin -where - Ptr::Target: PartialOrd, -{ - fn partial_cmp(&self, other: &Pin) -> Option { - Ptr::Target::partial_cmp(self, other) - } - - fn lt(&self, other: &Pin) -> bool { - Ptr::Target::lt(self, other) - } - - fn le(&self, other: &Pin) -> bool { - Ptr::Target::le(self, other) - } - - fn gt(&self, other: &Pin) -> bool { - Ptr::Target::gt(self, other) - } - - fn ge(&self, other: &Pin) -> bool { - Ptr::Target::ge(self, other) - } -} - -#[stable(feature = "pin_trait_impls", since = "1.41.0")] -impl> Ord for Pin { - fn cmp(&self, other: &Self) -> cmp::Ordering { - Ptr::Target::cmp(self, other) - } -} - -#[stable(feature = "pin_trait_impls", since = "1.41.0")] -impl> Hash for Pin { - fn hash(&self, state: &mut H) { - Ptr::Target::hash(self, state); - } -} - -impl> Pin { - /// Construct a new `Pin` around a pointer to some data of a type that - /// implements [`Unpin`]. - /// - /// Unlike `Pin::new_unchecked`, this method is safe because the pointer - /// `Ptr` dereferences to an [`Unpin`] type, which cancels the pinning guarantees. - /// - /// # Examples - /// - /// ``` - /// use std::pin::Pin; - /// - /// let mut val: u8 = 5; - /// - /// // Since `val` doesn't care about being moved, we can safely create a "facade" `Pin` - /// // which will allow `val` to participate in `Pin`-bound apis without checking that - /// // pinning guarantees are actually upheld. - /// let mut pinned: Pin<&mut u8> = Pin::new(&mut val); - /// ``` - #[inline(always)] - #[rustc_const_unstable(feature = "const_pin", issue = "76654")] - #[stable(feature = "pin", since = "1.33.0")] - pub const fn new(pointer: Ptr) -> Pin { - // SAFETY: the value pointed to is `Unpin`, and so has no requirements - // around pinning. - unsafe { Pin::new_unchecked(pointer) } - } - - /// Unwraps this `Pin`, returning the underlying pointer. - /// - /// Doing this operation safely requires that the data pointed at by this pinning pointer - /// implements [`Unpin`] so that we can ignore the pinning invariants when unwrapping it. - /// - /// # Examples - /// - /// ``` - /// use std::pin::Pin; - /// - /// let mut val: u8 = 5; - /// let pinned: Pin<&mut u8> = Pin::new(&mut val); - /// - /// // Unwrap the pin to get the underlying mutable reference to the value. We can do - /// // this because `val` doesn't care about being moved, so the `Pin` was just - /// // a "facade" anyway. - /// let r = Pin::into_inner(pinned); - /// assert_eq!(*r, 5); - /// ``` - #[inline(always)] - #[rustc_const_unstable(feature = "const_pin", issue = "76654")] - #[stable(feature = "pin_into_inner", since = "1.39.0")] - pub const fn into_inner(pin: Pin) -> Ptr { - pin.__pointer - } -} - -impl Pin { - /// Construct a new `Pin` around a reference to some data of a type that - /// may or may not implement [`Unpin`]. - /// - /// If `pointer` dereferences to an [`Unpin`] type, [`Pin::new`] should be used - /// instead. - /// - /// # Safety - /// - /// This constructor is unsafe because we cannot guarantee that the data - /// pointed to by `pointer` is pinned. At its core, pinning a value means making the - /// guarantee that the value's data will not be moved nor have its storage invalidated until - /// it gets dropped. For a more thorough explanation of pinning, see the [`pin` module docs]. - /// - /// If the caller that is constructing this `Pin` does not ensure that the data `Ptr` - /// points to is pinned, that is a violation of the API contract and may lead to undefined - /// behavior in later (even safe) operations. - /// - /// By using this method, you are also making a promise about the [`Deref`] and - /// [`DerefMut`] implementations of `Ptr`, if they exist. Most importantly, they - /// must not move out of their `self` arguments: `Pin::as_mut` and `Pin::as_ref` - /// will call `DerefMut::deref_mut` and `Deref::deref` *on the pointer type `Ptr`* - /// and expect these methods to uphold the pinning invariants. - /// Moreover, by calling this method you promise that the reference `Ptr` - /// dereferences to will not be moved out of again; in particular, it - /// must not be possible to obtain a `&mut Ptr::Target` and then - /// move out of that reference (using, for example [`mem::swap`]). - /// - /// For example, calling `Pin::new_unchecked` on an `&'a mut T` is unsafe because - /// while you are able to pin it for the given lifetime `'a`, you have no control - /// over whether it is kept pinned once `'a` ends, and therefore cannot uphold the - /// guarantee that a value, once pinned, remains pinned until it is dropped: - /// - /// ``` - /// use std::mem; - /// use std::pin::Pin; - /// - /// fn move_pinned_ref(mut a: T, mut b: T) { - /// unsafe { - /// let p: Pin<&mut T> = Pin::new_unchecked(&mut a); - /// // This should mean the pointee `a` can never move again. - /// } - /// mem::swap(&mut a, &mut b); // Potential UB down the road ⚠️ - /// // The address of `a` changed to `b`'s stack slot, so `a` got moved even - /// // though we have previously pinned it! We have violated the pinning API contract. - /// } - /// ``` - /// A value, once pinned, must remain pinned until it is dropped (unless its type implements - /// `Unpin`). Because `Pin<&mut T>` does not own the value, dropping the `Pin` will not drop - /// the value and will not end the pinning contract. So moving the value after dropping the - /// `Pin<&mut T>` is still a violation of the API contract. - /// - /// Similarly, calling `Pin::new_unchecked` on an `Rc` is unsafe because there could be - /// aliases to the same data that are not subject to the pinning restrictions: - /// ``` - /// use std::rc::Rc; - /// use std::pin::Pin; - /// - /// fn move_pinned_rc(mut x: Rc) { - /// // This should mean the pointee can never move again. - /// let pin = unsafe { Pin::new_unchecked(Rc::clone(&x)) }; - /// { - /// let p: Pin<&T> = pin.as_ref(); - /// // ... - /// } - /// drop(pin); - /// - /// let content = Rc::get_mut(&mut x).unwrap(); // Potential UB down the road ⚠️ - /// // Now, if `x` was the only reference, we have a mutable reference to - /// // data that we pinned above, which we could use to move it as we have - /// // seen in the previous example. We have violated the pinning API contract. - /// } - /// ``` - /// - /// ## Pinning of closure captures - /// - /// Particular care is required when using `Pin::new_unchecked` in a closure: - /// `Pin::new_unchecked(&mut var)` where `var` is a by-value (moved) closure capture - /// implicitly makes the promise that the closure itself is pinned, and that *all* uses - /// of this closure capture respect that pinning. - /// ``` - /// use std::pin::Pin; - /// use std::task::Context; - /// use std::future::Future; - /// - /// fn move_pinned_closure(mut x: impl Future, cx: &mut Context<'_>) { - /// // Create a closure that moves `x`, and then internally uses it in a pinned way. - /// let mut closure = move || unsafe { - /// let _ignore = Pin::new_unchecked(&mut x).poll(cx); - /// }; - /// // Call the closure, so the future can assume it has been pinned. - /// closure(); - /// // Move the closure somewhere else. This also moves `x`! - /// let mut moved = closure; - /// // Calling it again means we polled the future from two different locations, - /// // violating the pinning API contract. - /// moved(); // Potential UB ⚠️ - /// } - /// ``` - /// When passing a closure to another API, it might be moving the closure any time, so - /// `Pin::new_unchecked` on closure captures may only be used if the API explicitly documents - /// that the closure is pinned. - /// - /// The better alternative is to avoid all that trouble and do the pinning in the outer function - /// instead (here using the [`pin!`][crate::pin::pin] macro): - /// ``` - /// use std::pin::pin; - /// use std::task::Context; - /// use std::future::Future; - /// - /// fn move_pinned_closure(mut x: impl Future, cx: &mut Context<'_>) { - /// let mut x = pin!(x); - /// // Create a closure that captures `x: Pin<&mut _>`, which is safe to move. - /// let mut closure = move || { - /// let _ignore = x.as_mut().poll(cx); - /// }; - /// // Call the closure, so the future can assume it has been pinned. - /// closure(); - /// // Move the closure somewhere else. - /// let mut moved = closure; - /// // Calling it again here is fine (except that we might be polling a future that already - /// // returned `Poll::Ready`, but that is a separate problem). - /// moved(); - /// } - /// ``` - /// - /// [`mem::swap`]: crate::mem::swap - /// [`pin` module docs]: self - #[lang = "new_unchecked"] - #[inline(always)] - #[rustc_const_unstable(feature = "const_pin", issue = "76654")] - #[stable(feature = "pin", since = "1.33.0")] - pub const unsafe fn new_unchecked(pointer: Ptr) -> Pin { - Pin { __pointer: pointer } - } - - /// Gets a shared reference to the pinned value this [`Pin`] points to. - /// - /// This is a generic method to go from `&Pin>` to `Pin<&T>`. - /// It is safe because, as part of the contract of `Pin::new_unchecked`, - /// the pointee cannot move after `Pin>` got created. - /// "Malicious" implementations of `Pointer::Deref` are likewise - /// ruled out by the contract of `Pin::new_unchecked`. - #[stable(feature = "pin", since = "1.33.0")] - #[inline(always)] - pub fn as_ref(&self) -> Pin<&Ptr::Target> { - // SAFETY: see documentation on this function - unsafe { Pin::new_unchecked(&*self.__pointer) } - } - - /// Unwraps this `Pin`, returning the underlying `Ptr`. - /// - /// # Safety - /// - /// This function is unsafe. You must guarantee that you will continue to - /// treat the pointer `Ptr` as pinned after you call this function, so that - /// the invariants on the `Pin` type can be upheld. If the code using the - /// resulting `Ptr` does not continue to maintain the pinning invariants that - /// is a violation of the API contract and may lead to undefined behavior in - /// later (safe) operations. - /// - /// Note that you must be able to guarantee that the data pointed to by `Ptr` - /// will be treated as pinned all the way until its `drop` handler is complete! - /// - /// *For more information, see the [`pin` module docs][self]* - /// - /// If the underlying data is [`Unpin`], [`Pin::into_inner`] should be used - /// instead. - #[inline(always)] - #[rustc_const_unstable(feature = "const_pin", issue = "76654")] - #[stable(feature = "pin_into_inner", since = "1.39.0")] - pub const unsafe fn into_inner_unchecked(pin: Pin) -> Ptr { - pin.__pointer - } -} - -impl Pin { - /// Gets a mutable reference to the pinned value this `Pin` points to. - /// - /// This is a generic method to go from `&mut Pin>` to `Pin<&mut T>`. - /// It is safe because, as part of the contract of `Pin::new_unchecked`, - /// the pointee cannot move after `Pin>` got created. - /// "Malicious" implementations of `Pointer::DerefMut` are likewise - /// ruled out by the contract of `Pin::new_unchecked`. - /// - /// This method is useful when doing multiple calls to functions that consume the - /// pinning pointer. - /// - /// # Example - /// - /// ``` - /// use std::pin::Pin; - /// - /// # struct Type {} - /// impl Type { - /// fn method(self: Pin<&mut Self>) { - /// // do something - /// } - /// - /// fn call_method_twice(mut self: Pin<&mut Self>) { - /// // `method` consumes `self`, so reborrow the `Pin<&mut Self>` via `as_mut`. - /// self.as_mut().method(); - /// self.as_mut().method(); - /// } - /// } - /// ``` - #[stable(feature = "pin", since = "1.33.0")] - #[inline(always)] - pub fn as_mut(&mut self) -> Pin<&mut Ptr::Target> { - // SAFETY: see documentation on this function - unsafe { Pin::new_unchecked(&mut *self.__pointer) } - } - - /// Assigns a new value to the memory location pointed to by the `Pin`. - /// - /// This overwrites pinned data, but that is okay: the original pinned value's destructor gets - /// run before being overwritten and the new value is also a valid value of the same type, so - /// no pinning invariant is violated. See [the `pin` module documentation][subtle-details] - /// for more information on how this upholds the pinning invariants. - /// - /// # Example - /// - /// ``` - /// use std::pin::Pin; - /// - /// let mut val: u8 = 5; - /// let mut pinned: Pin<&mut u8> = Pin::new(&mut val); - /// println!("{}", pinned); // 5 - /// pinned.set(10); - /// println!("{}", pinned); // 10 - /// ``` - /// - /// [subtle-details]: self#subtle-details-and-the-drop-guarantee - #[stable(feature = "pin", since = "1.33.0")] - #[inline(always)] - pub fn set(&mut self, value: Ptr::Target) - where - Ptr::Target: Sized, - { - *(self.__pointer) = value; - } -} - -impl<'a, T: ?Sized> Pin<&'a T> { - /// Constructs a new pin by mapping the interior value. - /// - /// For example, if you wanted to get a `Pin` of a field of something, - /// you could use this to get access to that field in one line of code. - /// However, there are several gotchas with these "pinning projections"; - /// see the [`pin` module] documentation for further details on that topic. - /// - /// # Safety - /// - /// This function is unsafe. You must guarantee that the data you return - /// will not move so long as the argument value does not move (for example, - /// because it is one of the fields of that value), and also that you do - /// not move out of the argument you receive to the interior function. - /// - /// [`pin` module]: self#projections-and-structural-pinning - #[stable(feature = "pin", since = "1.33.0")] - pub unsafe fn map_unchecked(self, func: F) -> Pin<&'a U> - where - U: ?Sized, - F: FnOnce(&T) -> &U, - { - let pointer = &*self.__pointer; - let new_pointer = func(pointer); - - // SAFETY: the safety contract for `new_unchecked` must be - // upheld by the caller. - unsafe { Pin::new_unchecked(new_pointer) } - } - - /// Gets a shared reference out of a pin. - /// - /// This is safe because it is not possible to move out of a shared reference. - /// It may seem like there is an issue here with interior mutability: in fact, - /// it *is* possible to move a `T` out of a `&RefCell`. However, this is - /// not a problem as long as there does not also exist a `Pin<&T>` pointing - /// to the inner `T` inside the `RefCell`, and `RefCell` does not let you get a - /// `Pin<&T>` pointer to its contents. See the discussion on ["pinning projections"] - /// for further details. - /// - /// Note: `Pin` also implements `Deref` to the target, which can be used - /// to access the inner value. However, `Deref` only provides a reference - /// that lives for as long as the borrow of the `Pin`, not the lifetime of - /// the reference contained in the `Pin`. This method allows turning the `Pin` into a reference - /// with the same lifetime as the reference it wraps. - /// - /// ["pinning projections"]: self#projections-and-structural-pinning - #[inline(always)] - #[must_use] - #[rustc_const_unstable(feature = "const_pin", issue = "76654")] - #[stable(feature = "pin", since = "1.33.0")] - pub const fn get_ref(self) -> &'a T { - self.__pointer - } -} - -impl<'a, T: ?Sized> Pin<&'a mut T> { - /// Converts this `Pin<&mut T>` into a `Pin<&T>` with the same lifetime. - #[inline(always)] - #[must_use = "`self` will be dropped if the result is not used"] - #[rustc_const_unstable(feature = "const_pin", issue = "76654")] - #[stable(feature = "pin", since = "1.33.0")] - pub const fn into_ref(self) -> Pin<&'a T> { - Pin { __pointer: self.__pointer } - } - - /// Gets a mutable reference to the data inside of this `Pin`. - /// - /// This requires that the data inside this `Pin` is `Unpin`. - /// - /// Note: `Pin` also implements `DerefMut` to the data, which can be used - /// to access the inner value. However, `DerefMut` only provides a reference - /// that lives for as long as the borrow of the `Pin`, not the lifetime of - /// the `Pin` itself. This method allows turning the `Pin` into a reference - /// with the same lifetime as the original `Pin`. - #[inline(always)] - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "pin", since = "1.33.0")] - #[rustc_const_unstable(feature = "const_pin", issue = "76654")] - pub const fn get_mut(self) -> &'a mut T - where - T: Unpin, - { - self.__pointer - } - - /// Gets a mutable reference to the data inside of this `Pin`. - /// - /// # Safety - /// - /// This function is unsafe. You must guarantee that you will never move - /// the data out of the mutable reference you receive when you call this - /// function, so that the invariants on the `Pin` type can be upheld. - /// - /// If the underlying data is `Unpin`, `Pin::get_mut` should be used - /// instead. - #[inline(always)] - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "pin", since = "1.33.0")] - #[rustc_const_unstable(feature = "const_pin", issue = "76654")] - pub const unsafe fn get_unchecked_mut(self) -> &'a mut T { - self.__pointer - } - - /// Construct a new pin by mapping the interior value. - /// - /// For example, if you wanted to get a `Pin` of a field of something, - /// you could use this to get access to that field in one line of code. - /// However, there are several gotchas with these "pinning projections"; - /// see the [`pin` module] documentation for further details on that topic. - /// - /// # Safety - /// - /// This function is unsafe. You must guarantee that the data you return - /// will not move so long as the argument value does not move (for example, - /// because it is one of the fields of that value), and also that you do - /// not move out of the argument you receive to the interior function. - /// - /// [`pin` module]: self#projections-and-structural-pinning - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "pin", since = "1.33.0")] - pub unsafe fn map_unchecked_mut(self, func: F) -> Pin<&'a mut U> - where - U: ?Sized, - F: FnOnce(&mut T) -> &mut U, - { - // SAFETY: the caller is responsible for not moving the - // value out of this reference. - let pointer = unsafe { Pin::get_unchecked_mut(self) }; - let new_pointer = func(pointer); - // SAFETY: as the value of `this` is guaranteed to not have - // been moved out, this call to `new_unchecked` is safe. - unsafe { Pin::new_unchecked(new_pointer) } - } -} - -impl Pin<&'static T> { - /// Get a pinning reference from a `&'static` reference. - /// - /// This is safe because `T` is borrowed immutably for the `'static` lifetime, which - /// never ends. - #[stable(feature = "pin_static_ref", since = "1.61.0")] - #[rustc_const_unstable(feature = "const_pin", issue = "76654")] - pub const fn static_ref(r: &'static T) -> Pin<&'static T> { - // SAFETY: The 'static borrow guarantees the data will not be - // moved/invalidated until it gets dropped (which is never). - unsafe { Pin::new_unchecked(r) } - } -} - -impl<'a, Ptr: DerefMut> Pin<&'a mut Pin> { - /// Gets `Pin<&mut T>` to the underlying pinned value from this nested `Pin`-pointer. - /// - /// This is a generic method to go from `Pin<&mut Pin>>` to `Pin<&mut T>`. It is - /// safe because the existence of a `Pin>` ensures that the pointee, `T`, cannot - /// move in the future, and this method does not enable the pointee to move. "Malicious" - /// implementations of `Ptr::DerefMut` are likewise ruled out by the contract of - /// `Pin::new_unchecked`. - #[unstable(feature = "pin_deref_mut", issue = "86918")] - #[must_use = "`self` will be dropped if the result is not used"] - #[inline(always)] - pub fn as_deref_mut(self) -> Pin<&'a mut Ptr::Target> { - // SAFETY: What we're asserting here is that going from - // - // Pin<&mut Pin> - // - // to - // - // Pin<&mut Ptr::Target> - // - // is safe. - // - // We need to ensure that two things hold for that to be the case: - // - // 1) Once we give out a `Pin<&mut Ptr::Target>`, an `&mut Ptr::Target` will not be given out. - // 2) By giving out a `Pin<&mut Ptr::Target>`, we do not risk of violating - // `Pin<&mut Pin>` - // - // The existence of `Pin` is sufficient to guarantee #1: since we already have a - // `Pin`, it must already uphold the pinning guarantees, which must mean that - // `Pin<&mut Ptr::Target>` does as well, since `Pin::as_mut` is safe. We do not have to rely - // on the fact that `Ptr` is _also_ pinned. - // - // For #2, we need to ensure that code given a `Pin<&mut Ptr::Target>` cannot cause the - // `Pin` to move? That is not possible, since `Pin<&mut Ptr::Target>` no longer retains - // any access to the `Ptr` itself, much less the `Pin`. - unsafe { self.get_unchecked_mut() }.as_mut() - } -} - -impl Pin<&'static mut T> { - /// Get a pinning mutable reference from a static mutable reference. - /// - /// This is safe because `T` is borrowed for the `'static` lifetime, which - /// never ends. - #[stable(feature = "pin_static_ref", since = "1.61.0")] - #[rustc_const_unstable(feature = "const_pin", issue = "76654")] - pub const fn static_mut(r: &'static mut T) -> Pin<&'static mut T> { - // SAFETY: The 'static borrow guarantees the data will not be - // moved/invalidated until it gets dropped (which is never). - unsafe { Pin::new_unchecked(r) } - } -} - -#[stable(feature = "pin", since = "1.33.0")] -impl Deref for Pin { - type Target = Ptr::Target; - fn deref(&self) -> &Ptr::Target { - Pin::get_ref(Pin::as_ref(self)) - } -} - -#[stable(feature = "pin", since = "1.33.0")] -impl> DerefMut for Pin { - fn deref_mut(&mut self) -> &mut Ptr::Target { - Pin::get_mut(Pin::as_mut(self)) - } -} - -#[unstable(feature = "deref_pure_trait", issue = "87121")] -unsafe impl DerefPure for Pin {} - -#[unstable(feature = "receiver_trait", issue = "none")] -impl Receiver for Pin {} - -#[stable(feature = "pin", since = "1.33.0")] -impl fmt::Debug for Pin { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&self.__pointer, f) - } -} - -#[stable(feature = "pin", since = "1.33.0")] -impl fmt::Display for Pin { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt(&self.__pointer, f) - } -} - -#[stable(feature = "pin", since = "1.33.0")] -impl fmt::Pointer for Pin { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Pointer::fmt(&self.__pointer, f) - } -} - -// Note: this means that any impl of `CoerceUnsized` that allows coercing from -// a type that impls `Deref` to a type that impls -// `Deref` is unsound. Any such impl would probably be unsound -// for other reasons, though, so we just need to take care not to allow such -// impls to land in std. -#[stable(feature = "pin", since = "1.33.0")] -impl CoerceUnsized> for Pin where Ptr: CoerceUnsized {} - -#[stable(feature = "pin", since = "1.33.0")] -impl DispatchFromDyn> for Pin where Ptr: DispatchFromDyn {} - -/// Constructs a [Pin]<[&mut] T>, by pinning a `value: T` locally. -/// -/// Unlike [`Box::pin`], this does not create a new heap allocation. As explained -/// below, the element might still end up on the heap however. -/// -/// The local pinning performed by this macro is usually dubbed "stack"-pinning. -/// Outside of `async` contexts locals do indeed get stored on the stack. In -/// `async` functions or blocks however, any locals crossing an `.await` point -/// are part of the state captured by the `Future`, and will use the storage of -/// those. That storage can either be on the heap or on the stack. Therefore, -/// local pinning is a more accurate term. -/// -/// If the type of the given value does not implement [`Unpin`], then this macro -/// pins the value in memory in a way that prevents moves. On the other hand, -/// if the type does implement [`Unpin`], [Pin]<[&mut] T> behaves -/// like [&mut] T, and operations such as -/// [`mem::replace()`][crate::mem::replace] or [`mem::take()`](crate::mem::take) -/// will allow moves of the value. -/// See [the `Unpin` section of the `pin` module][self#unpin] for details. -/// -/// ## Examples -/// -/// ### Basic usage -/// -/// ```rust -/// # use core::marker::PhantomPinned as Foo; -/// use core::pin::{pin, Pin}; -/// -/// fn stuff(foo: Pin<&mut Foo>) { -/// // … -/// # let _ = foo; -/// } -/// -/// let pinned_foo = pin!(Foo { /* … */ }); -/// stuff(pinned_foo); -/// // or, directly: -/// stuff(pin!(Foo { /* … */ })); -/// ``` -/// -/// ### Manually polling a `Future` (without `Unpin` bounds) -/// -/// ```rust -/// use std::{ -/// future::Future, -/// pin::pin, -/// task::{Context, Poll}, -/// thread, -/// }; -/// # use std::{sync::Arc, task::Wake, thread::Thread}; -/// -/// # /// A waker that wakes up the current thread when called. -/// # struct ThreadWaker(Thread); -/// # -/// # impl Wake for ThreadWaker { -/// # fn wake(self: Arc) { -/// # self.0.unpark(); -/// # } -/// # } -/// # -/// /// Runs a future to completion. -/// fn block_on(fut: Fut) -> Fut::Output { -/// let waker_that_unparks_thread = // … -/// # Arc::new(ThreadWaker(thread::current())).into(); -/// let mut cx = Context::from_waker(&waker_that_unparks_thread); -/// // Pin the future so it can be polled. -/// let mut pinned_fut = pin!(fut); -/// loop { -/// match pinned_fut.as_mut().poll(&mut cx) { -/// Poll::Pending => thread::park(), -/// Poll::Ready(res) => return res, -/// } -/// } -/// } -/// # -/// # assert_eq!(42, block_on(async { 42 })); -/// ``` -/// -/// ### With `Coroutine`s -/// -/// ```rust -/// #![feature(coroutines)] -/// #![feature(coroutine_trait)] -/// use core::{ -/// ops::{Coroutine, CoroutineState}, -/// pin::pin, -/// }; -/// -/// fn coroutine_fn() -> impl Coroutine /* not Unpin */ { -/// // Allow coroutine to be self-referential (not `Unpin`) -/// // vvvvvv so that locals can cross yield points. -/// #[coroutine] static || { -/// let foo = String::from("foo"); -/// let foo_ref = &foo; // ------+ -/// yield 0; // | <- crosses yield point! -/// println!("{foo_ref}"); // <--+ -/// yield foo.len(); -/// } -/// } -/// -/// fn main() { -/// let mut coroutine = pin!(coroutine_fn()); -/// match coroutine.as_mut().resume(()) { -/// CoroutineState::Yielded(0) => {}, -/// _ => unreachable!(), -/// } -/// match coroutine.as_mut().resume(()) { -/// CoroutineState::Yielded(3) => {}, -/// _ => unreachable!(), -/// } -/// match coroutine.resume(()) { -/// CoroutineState::Yielded(_) => unreachable!(), -/// CoroutineState::Complete(()) => {}, -/// } -/// } -/// ``` -/// -/// ## Remarks -/// -/// Precisely because a value is pinned to local storage, the resulting [Pin]<[&mut] T> -/// reference ends up borrowing a local tied to that block: it can't escape it. -/// -/// The following, for instance, fails to compile: -/// -/// ```rust,compile_fail -/// use core::pin::{pin, Pin}; -/// # use core::{marker::PhantomPinned as Foo, mem::drop as stuff}; -/// -/// let x: Pin<&mut Foo> = { -/// let x: Pin<&mut Foo> = pin!(Foo { /* … */ }); -/// x -/// }; // <- Foo is dropped -/// stuff(x); // Error: use of dropped value -/// ``` -/// -///

Error message -/// -/// ```console -/// error[E0716]: temporary value dropped while borrowed -/// --> src/main.rs:9:28 -/// | -/// 8 | let x: Pin<&mut Foo> = { -/// | - borrow later stored here -/// 9 | let x: Pin<&mut Foo> = pin!(Foo { /* … */ }); -/// | ^^^^^^^^^^^^^^^^^^^^^ creates a temporary value which is freed while still in use -/// 10 | x -/// 11 | }; // <- Foo is dropped -/// | - temporary value is freed at the end of this statement -/// | -/// = note: consider using a `let` binding to create a longer lived value -/// ``` -/// -///
-/// -/// This makes [`pin!`] **unsuitable to pin values when intending to _return_ them**. Instead, the -/// value is expected to be passed around _unpinned_ until the point where it is to be consumed, -/// where it is then useful and even sensible to pin the value locally using [`pin!`]. -/// -/// If you really need to return a pinned value, consider using [`Box::pin`] instead. -/// -/// On the other hand, local pinning using [`pin!`] is likely to be cheaper than -/// pinning into a fresh heap allocation using [`Box::pin`]. Moreover, by virtue of not -/// requiring an allocator, [`pin!`] is the main non-`unsafe` `#![no_std]`-compatible [`Pin`] -/// constructor. -/// -/// [`Box::pin`]: ../../std/boxed/struct.Box.html#method.pin -#[stable(feature = "pin_macro", since = "1.68.0")] -#[rustc_macro_transparency = "semitransparent"] -#[allow_internal_unstable(unsafe_pin_internals)] -pub macro pin($value:expr $(,)?) { - // This is `Pin::new_unchecked(&mut { $value })`, so, for starters, let's - // review such a hypothetical macro (that any user-code could define): - // - // ```rust - // macro_rules! pin {( $value:expr ) => ( - // match &mut { $value } { at_value => unsafe { // Do not wrap `$value` in an `unsafe` block. - // $crate::pin::Pin::<&mut _>::new_unchecked(at_value) - // }} - // )} - // ``` - // - // Safety: - // - `type P = &mut _`. There are thus no pathological `Deref{,Mut}` impls - // that would break `Pin`'s invariants. - // - `{ $value }` is braced, making it a _block expression_, thus **moving** - // the given `$value`, and making it _become an **anonymous** temporary_. - // By virtue of being anonymous, it can no longer be accessed, thus - // preventing any attempts to `mem::replace` it or `mem::forget` it, _etc._ - // - // This gives us a `pin!` definition that is sound, and which works, but only - // in certain scenarios: - // - If the `pin!(value)` expression is _directly_ fed to a function call: - // `let poll = pin!(fut).poll(cx);` - // - If the `pin!(value)` expression is part of a scrutinee: - // ```rust - // match pin!(fut) { pinned_fut => { - // pinned_fut.as_mut().poll(...); - // pinned_fut.as_mut().poll(...); - // }} // <- `fut` is dropped here. - // ``` - // Alas, it doesn't work for the more straight-forward use-case: `let` bindings. - // ```rust - // let pinned_fut = pin!(fut); // <- temporary value is freed at the end of this statement - // pinned_fut.poll(...) // error[E0716]: temporary value dropped while borrowed - // // note: consider using a `let` binding to create a longer lived value - // ``` - // - Issues such as this one are the ones motivating https://github.com/rust-lang/rfcs/pull/66 - // - // This makes such a macro incredibly unergonomic in practice, and the reason most macros - // out there had to take the path of being a statement/binding macro (_e.g._, `pin!(future);`) - // instead of featuring the more intuitive ergonomics of an expression macro. - // - // Luckily, there is a way to avoid the problem. Indeed, the problem stems from the fact that a - // temporary is dropped at the end of its enclosing statement when it is part of the parameters - // given to function call, which has precisely been the case with our `Pin::new_unchecked()`! - // For instance, - // ```rust - // let p = Pin::new_unchecked(&mut ); - // ``` - // becomes: - // ```rust - // let p = { let mut anon = ; &mut anon }; - // ``` - // - // However, when using a literal braced struct to construct the value, references to temporaries - // can then be taken. This makes Rust change the lifespan of such temporaries so that they are, - // instead, dropped _at the end of the enscoping block_. - // For instance, - // ```rust - // let p = Pin { __pointer: &mut }; - // ``` - // becomes: - // ```rust - // let mut anon = ; - // let p = Pin { __pointer: &mut anon }; - // ``` - // which is *exactly* what we want. - // - // See https://doc.rust-lang.org/1.58.1/reference/destructors.html#temporary-lifetime-extension - // for more info. - $crate::pin::Pin::<&mut _> { __pointer: &mut { $value } } -} diff --git a/library/core/src/prelude/common.rs b/library/core/src/prelude/common.rs deleted file mode 100644 index afc6817aa1d24..0000000000000 --- a/library/core/src/prelude/common.rs +++ /dev/null @@ -1,105 +0,0 @@ -//! Items common to the prelude of all editions. -//! -//! See the [module-level documentation](super) for more. - -// Re-exported core operators -#[stable(feature = "core_prelude", since = "1.4.0")] -#[doc(no_inline)] -pub use crate::marker::{Copy, Send, Sized, Sync, Unpin}; -#[stable(feature = "core_prelude", since = "1.4.0")] -#[doc(no_inline)] -pub use crate::ops::{Drop, Fn, FnMut, FnOnce}; - -// Re-exported functions -#[stable(feature = "core_prelude", since = "1.4.0")] -#[doc(no_inline)] -pub use crate::mem::drop; - -// Re-exported types and traits -#[stable(feature = "core_prelude", since = "1.4.0")] -#[doc(no_inline)] -pub use crate::clone::Clone; -#[stable(feature = "core_prelude", since = "1.4.0")] -#[doc(no_inline)] -pub use crate::cmp::{Eq, Ord, PartialEq, PartialOrd}; -#[stable(feature = "core_prelude", since = "1.4.0")] -#[doc(no_inline)] -pub use crate::convert::{AsMut, AsRef, From, Into}; -#[stable(feature = "core_prelude", since = "1.4.0")] -#[doc(no_inline)] -pub use crate::default::Default; -#[stable(feature = "core_prelude", since = "1.4.0")] -#[doc(no_inline)] -pub use crate::iter::{DoubleEndedIterator, ExactSizeIterator}; -#[stable(feature = "core_prelude", since = "1.4.0")] -#[doc(no_inline)] -pub use crate::iter::{Extend, IntoIterator, Iterator}; -#[stable(feature = "core_prelude", since = "1.4.0")] -#[doc(no_inline)] -pub use crate::option::Option::{self, None, Some}; -#[stable(feature = "core_prelude", since = "1.4.0")] -#[doc(no_inline)] -pub use crate::result::Result::{self, Err, Ok}; - -// Re-exported built-in macros -#[stable(feature = "builtin_macro_prelude", since = "1.38.0")] -#[doc(no_inline)] -pub use crate::fmt::macros::Debug; -#[stable(feature = "builtin_macro_prelude", since = "1.38.0")] -#[doc(no_inline)] -pub use crate::hash::macros::Hash; - -#[stable(feature = "builtin_macro_prelude", since = "1.38.0")] -#[allow(deprecated)] -#[doc(no_inline)] -pub use crate::{ - assert, cfg, column, compile_error, concat, concat_idents, env, file, format_args, - format_args_nl, include, include_bytes, include_str, line, log_syntax, module_path, option_env, - stringify, trace_macros, -}; - -#[unstable( - feature = "concat_bytes", - issue = "87555", - reason = "`concat_bytes` is not stable enough for use and is subject to change" -)] -#[doc(no_inline)] -pub use crate::concat_bytes; - -// Do not `doc(no_inline)` so that they become doc items on their own -// (no public module for them to be re-exported from). -#[stable(feature = "builtin_macro_prelude", since = "1.38.0")] -pub use crate::macros::builtin::{ - alloc_error_handler, bench, derive, global_allocator, test, test_case, -}; - -#[unstable(feature = "derive_const", issue = "none")] -pub use crate::macros::builtin::derive_const; - -#[unstable( - feature = "cfg_accessible", - issue = "64797", - reason = "`cfg_accessible` is not fully implemented" -)] -pub use crate::macros::builtin::cfg_accessible; - -#[unstable( - feature = "cfg_eval", - issue = "82679", - reason = "`cfg_eval` is a recently implemented feature" -)] -pub use crate::macros::builtin::cfg_eval; - -#[unstable( - feature = "type_ascription", - issue = "23416", - reason = "placeholder syntax for type ascription" -)] -pub use crate::macros::builtin::type_ascribe; - -#[unstable( - feature = "deref_patterns", - issue = "87121", - reason = "placeholder syntax for deref patterns" -)] -pub use crate::macros::builtin::deref; diff --git a/library/core/src/prelude/mod.rs b/library/core/src/prelude/mod.rs deleted file mode 100644 index ca33ef160e88b..0000000000000 --- a/library/core/src/prelude/mod.rs +++ /dev/null @@ -1,87 +0,0 @@ -//! The core prelude -//! -//! This module is intended for users of core which do not link to std as well. -//! This module is imported by default when `#![no_std]` is used in the same -//! manner as the standard library's prelude. - -#![stable(feature = "core_prelude", since = "1.4.0")] - -mod common; - -/// The first version of the prelude of The Rust Standard Library. -/// -/// See the [module-level documentation](self) for more. -#[stable(feature = "rust1", since = "1.0.0")] -pub mod v1 { - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::common::*; - - // Do not `doc(inline)` these `doc(hidden)` items. - #[unstable( - feature = "rustc_encodable_decodable", - issue = "none", - soft, - reason = "derive macro for `rustc-serialize`; should not be used in new code" - )] - #[allow(deprecated)] - pub use crate::macros::builtin::{RustcDecodable, RustcEncodable}; -} - -/// The 2015 version of the core prelude. -/// -/// See the [module-level documentation](self) for more. -#[stable(feature = "prelude_2015", since = "1.55.0")] -pub mod rust_2015 { - #[stable(feature = "prelude_2015", since = "1.55.0")] - #[doc(no_inline)] - pub use super::v1::*; -} - -/// The 2018 version of the core prelude. -/// -/// See the [module-level documentation](self) for more. -#[stable(feature = "prelude_2018", since = "1.55.0")] -pub mod rust_2018 { - #[stable(feature = "prelude_2018", since = "1.55.0")] - #[doc(no_inline)] - pub use super::v1::*; -} - -/// The 2021 version of the core prelude. -/// -/// See the [module-level documentation](self) for more. -#[stable(feature = "prelude_2021", since = "1.55.0")] -pub mod rust_2021 { - #[stable(feature = "prelude_2021", since = "1.55.0")] - #[doc(no_inline)] - pub use super::v1::*; - - #[stable(feature = "prelude_2021", since = "1.55.0")] - #[doc(no_inline)] - pub use crate::iter::FromIterator; - - #[stable(feature = "prelude_2021", since = "1.55.0")] - #[doc(no_inline)] - pub use crate::convert::{TryFrom, TryInto}; -} - -/// The 2024 version of the core prelude. -/// -/// See the [module-level documentation](self) for more. -#[unstable(feature = "prelude_2024", issue = "121042")] -pub mod rust_2024 { - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::common::*; - - #[stable(feature = "prelude_2021", since = "1.55.0")] - #[doc(no_inline)] - pub use crate::iter::FromIterator; - - #[stable(feature = "prelude_2021", since = "1.55.0")] - #[doc(no_inline)] - pub use crate::convert::{TryFrom, TryInto}; - - #[unstable(feature = "prelude_2024", issue = "121042")] - #[doc(no_inline)] - pub use crate::future::{Future, IntoFuture}; -} diff --git a/library/core/src/primitive.rs b/library/core/src/primitive.rs deleted file mode 100644 index e20b2c5c9382a..0000000000000 --- a/library/core/src/primitive.rs +++ /dev/null @@ -1,67 +0,0 @@ -//! This module reexports the primitive types to allow usage that is not -//! possibly shadowed by other declared types. -//! -//! This is normally only useful in macro generated code. -//! -//! An example of this is when generating a new struct and an impl for it: -//! -//! ```rust,compile_fail -//! pub struct bool; -//! -//! impl QueryId for bool { -//! const SOME_PROPERTY: bool = true; -//! } -//! -//! # trait QueryId { const SOME_PROPERTY: core::primitive::bool; } -//! ``` -//! -//! Note that the `SOME_PROPERTY` associated constant would not compile, as its -//! type `bool` refers to the struct, rather than to the primitive bool type. -//! -//! A correct implementation could look like: -//! -//! ```rust -//! # #[allow(non_camel_case_types)] -//! pub struct bool; -//! -//! impl QueryId for bool { -//! const SOME_PROPERTY: core::primitive::bool = true; -//! } -//! -//! # trait QueryId { const SOME_PROPERTY: core::primitive::bool; } -//! ``` - -#[stable(feature = "core_primitive", since = "1.43.0")] -pub use bool; -#[stable(feature = "core_primitive", since = "1.43.0")] -pub use char; -#[stable(feature = "core_primitive", since = "1.43.0")] -pub use f32; -#[stable(feature = "core_primitive", since = "1.43.0")] -pub use f64; -#[stable(feature = "core_primitive", since = "1.43.0")] -pub use i128; -#[stable(feature = "core_primitive", since = "1.43.0")] -pub use i16; -#[stable(feature = "core_primitive", since = "1.43.0")] -pub use i32; -#[stable(feature = "core_primitive", since = "1.43.0")] -pub use i64; -#[stable(feature = "core_primitive", since = "1.43.0")] -pub use i8; -#[stable(feature = "core_primitive", since = "1.43.0")] -pub use isize; -#[stable(feature = "core_primitive", since = "1.43.0")] -pub use str; -#[stable(feature = "core_primitive", since = "1.43.0")] -pub use u128; -#[stable(feature = "core_primitive", since = "1.43.0")] -pub use u16; -#[stable(feature = "core_primitive", since = "1.43.0")] -pub use u32; -#[stable(feature = "core_primitive", since = "1.43.0")] -pub use u64; -#[stable(feature = "core_primitive", since = "1.43.0")] -pub use u8; -#[stable(feature = "core_primitive", since = "1.43.0")] -pub use usize; diff --git a/library/core/src/primitive_docs.rs b/library/core/src/primitive_docs.rs deleted file mode 100644 index 5989bcbcc5201..0000000000000 --- a/library/core/src/primitive_docs.rs +++ /dev/null @@ -1,1777 +0,0 @@ -#[rustc_doc_primitive = "bool"] -#[doc(alias = "true")] -#[doc(alias = "false")] -/// The boolean type. -/// -/// The `bool` represents a value, which could only be either [`true`] or [`false`]. If you cast -/// a `bool` into an integer, [`true`] will be 1 and [`false`] will be 0. -/// -/// # Basic usage -/// -/// `bool` implements various traits, such as [`BitAnd`], [`BitOr`], [`Not`], etc., -/// which allow us to perform boolean operations using `&`, `|` and `!`. -/// -/// [`if`] requires a `bool` value as its conditional. [`assert!`], which is an -/// important macro in testing, checks whether an expression is [`true`] and panics -/// if it isn't. -/// -/// ``` -/// let bool_val = true & false | false; -/// assert!(!bool_val); -/// ``` -/// -/// [`true`]: ../std/keyword.true.html -/// [`false`]: ../std/keyword.false.html -/// [`BitAnd`]: ops::BitAnd -/// [`BitOr`]: ops::BitOr -/// [`Not`]: ops::Not -/// [`if`]: ../std/keyword.if.html -/// -/// # Examples -/// -/// A trivial example of the usage of `bool`: -/// -/// ``` -/// let praise_the_borrow_checker = true; -/// -/// // using the `if` conditional -/// if praise_the_borrow_checker { -/// println!("oh, yeah!"); -/// } else { -/// println!("what?!!"); -/// } -/// -/// // ... or, a match pattern -/// match praise_the_borrow_checker { -/// true => println!("keep praising!"), -/// false => println!("you should praise!"), -/// } -/// ``` -/// -/// Also, since `bool` implements the [`Copy`] trait, we don't -/// have to worry about the move semantics (just like the integer and float primitives). -/// -/// Now an example of `bool` cast to integer type: -/// -/// ``` -/// assert_eq!(true as i32, 1); -/// assert_eq!(false as i32, 0); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_bool {} - -#[rustc_doc_primitive = "never"] -#[doc(alias = "!")] -// -/// The `!` type, also called "never". -/// -/// `!` represents the type of computations which never resolve to any value at all. For example, -/// the [`exit`] function `fn exit(code: i32) -> !` exits the process without ever returning, and -/// so returns `!`. -/// -/// `break`, `continue` and `return` expressions also have type `!`. For example we are allowed to -/// write: -/// -/// ``` -/// #![feature(never_type)] -/// # fn foo() -> u32 { -/// let x: ! = { -/// return 123 -/// }; -/// # } -/// ``` -/// -/// Although the `let` is pointless here, it illustrates the meaning of `!`. Since `x` is never -/// assigned a value (because `return` returns from the entire function), `x` can be given type -/// `!`. We could also replace `return 123` with a `panic!` or a never-ending `loop` and this code -/// would still be valid. -/// -/// A more realistic usage of `!` is in this code: -/// -/// ``` -/// # fn get_a_number() -> Option { None } -/// # loop { -/// let num: u32 = match get_a_number() { -/// Some(num) => num, -/// None => break, -/// }; -/// # } -/// ``` -/// -/// Both match arms must produce values of type [`u32`], but since `break` never produces a value -/// at all we know it can never produce a value which isn't a [`u32`]. This illustrates another -/// behaviour of the `!` type - expressions with type `!` will coerce into any other type. -/// -/// [`u32`]: prim@u32 -/// [`exit`]: ../std/process/fn.exit.html -/// -/// # `!` and generics -/// -/// ## Infallible errors -/// -/// The main place you'll see `!` used explicitly is in generic code. Consider the [`FromStr`] -/// trait: -/// -/// ``` -/// trait FromStr: Sized { -/// type Err; -/// fn from_str(s: &str) -> Result; -/// } -/// ``` -/// -/// When implementing this trait for [`String`] we need to pick a type for [`Err`]. And since -/// converting a string into a string will never result in an error, the appropriate type is `!`. -/// (Currently the type actually used is an enum with no variants, though this is only because `!` -/// was added to Rust at a later date and it may change in the future.) With an [`Err`] type of -/// `!`, if we have to call [`String::from_str`] for some reason the result will be a -/// [`Result`] which we can unpack like this: -/// -/// ``` -/// #![feature(exhaustive_patterns)] -/// use std::str::FromStr; -/// let Ok(s) = String::from_str("hello"); -/// ``` -/// -/// Since the [`Err`] variant contains a `!`, it can never occur. If the `exhaustive_patterns` -/// feature is present this means we can exhaustively match on [`Result`] by just taking the -/// [`Ok`] variant. This illustrates another behaviour of `!` - it can be used to "delete" certain -/// enum variants from generic types like `Result`. -/// -/// ## Infinite loops -/// -/// While [`Result`] is very useful for removing errors, `!` can also be used to remove -/// successes as well. If we think of [`Result`] as "if this function returns, it has not -/// errored," we get a very intuitive idea of [`Result`] as well: if the function returns, it -/// *has* errored. -/// -/// For example, consider the case of a simple web server, which can be simplified to: -/// -/// ```ignore (hypothetical-example) -/// loop { -/// let (client, request) = get_request().expect("disconnected"); -/// let response = request.process(); -/// response.send(client); -/// } -/// ``` -/// -/// Currently, this isn't ideal, because we simply panic whenever we fail to get a new connection. -/// Instead, we'd like to keep track of this error, like this: -/// -/// ```ignore (hypothetical-example) -/// loop { -/// match get_request() { -/// Err(err) => break err, -/// Ok((client, request)) => { -/// let response = request.process(); -/// response.send(client); -/// }, -/// } -/// } -/// ``` -/// -/// Now, when the server disconnects, we exit the loop with an error instead of panicking. While it -/// might be intuitive to simply return the error, we might want to wrap it in a [`Result`] -/// instead: -/// -/// ```ignore (hypothetical-example) -/// fn server_loop() -> Result { -/// loop { -/// let (client, request) = get_request()?; -/// let response = request.process(); -/// response.send(client); -/// } -/// } -/// ``` -/// -/// Now, we can use `?` instead of `match`, and the return type makes a lot more sense: if the loop -/// ever stops, it means that an error occurred. We don't even have to wrap the loop in an `Ok` -/// because `!` coerces to `Result` automatically. -/// -/// [`String::from_str`]: str::FromStr::from_str -/// [`String`]: ../std/string/struct.String.html -/// [`FromStr`]: str::FromStr -/// -/// # `!` and traits -/// -/// When writing your own traits, `!` should have an `impl` whenever there is an obvious `impl` -/// which doesn't `panic!`. The reason is that functions returning an `impl Trait` where `!` -/// does not have an `impl` of `Trait` cannot diverge as their only possible code path. In other -/// words, they can't return `!` from every code path. As an example, this code doesn't compile: -/// -/// ```compile_fail -/// use std::ops::Add; -/// -/// fn foo() -> impl Add { -/// unimplemented!() -/// } -/// ``` -/// -/// But this code does: -/// -/// ``` -/// use std::ops::Add; -/// -/// fn foo() -> impl Add { -/// if true { -/// unimplemented!() -/// } else { -/// 0 -/// } -/// } -/// ``` -/// -/// The reason is that, in the first example, there are many possible types that `!` could coerce -/// to, because many types implement `Add`. However, in the second example, -/// the `else` branch returns a `0`, which the compiler infers from the return type to be of type -/// `u32`. Since `u32` is a concrete type, `!` can and will be coerced to it. See issue [#36375] -/// for more information on this quirk of `!`. -/// -/// [#36375]: https://github.com/rust-lang/rust/issues/36375 -/// -/// As it turns out, though, most traits can have an `impl` for `!`. Take [`Debug`] -/// for example: -/// -/// ``` -/// #![feature(never_type)] -/// # use std::fmt; -/// # trait Debug { -/// # fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result; -/// # } -/// impl Debug for ! { -/// fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { -/// *self -/// } -/// } -/// ``` -/// -/// Once again we're using `!`'s ability to coerce into any other type, in this case -/// [`fmt::Result`]. Since this method takes a `&!` as an argument we know that it can never be -/// called (because there is no value of type `!` for it to be called with). Writing `*self` -/// essentially tells the compiler "We know that this code can never be run, so just treat the -/// entire function body as having type [`fmt::Result`]". This pattern can be used a lot when -/// implementing traits for `!`. Generally, any trait which only has methods which take a `self` -/// parameter should have such an impl. -/// -/// On the other hand, one trait which would not be appropriate to implement is [`Default`]: -/// -/// ``` -/// trait Default { -/// fn default() -> Self; -/// } -/// ``` -/// -/// Since `!` has no values, it has no default value either. It's true that we could write an -/// `impl` for this which simply panics, but the same is true for any type (we could `impl -/// Default` for (eg.) [`File`] by just making [`default()`] panic.) -/// -/// [`File`]: ../std/fs/struct.File.html -/// [`Debug`]: fmt::Debug -/// [`default()`]: Default::default -/// -/// # Never type fallback -/// -/// When the compiler sees a value of type `!` in a [coercion site], it implicitly inserts a -/// coercion to allow the type checker to infer any type: -/// -/// ```rust,ignore (illustrative-and-has-placeholders) -/// // this -/// let x: u8 = panic!(); -/// -/// // is (essentially) turned by the compiler into -/// let x: u8 = absurd(panic!()); -/// -/// // where absurd is a function with the following signature -/// // (it's sound, because `!` always marks unreachable code): -/// fn absurd(_: !) -> T { ... } -// FIXME: use `core::convert::absurd` here instead, once it's merged -/// ``` -/// -/// This can lead to compilation errors if the type cannot be inferred: -/// -/// ```compile_fail -/// // this -/// { panic!() }; -/// -/// // gets turned into this -/// { absurd(panic!()) }; // error: can't infer the type of `absurd` -/// ``` -/// -/// To prevent such errors, the compiler remembers where it inserted `absurd` calls, and -/// if it can't infer the type, it uses the fallback type instead: -/// ```rust, ignore -/// type Fallback = /* An arbitrarily selected type! */; -/// { absurd::(panic!()) } -/// ``` -/// -/// This is what is known as "never type fallback". -/// -/// Historically, the fallback type was [`()`], causing confusing behavior where `!` spontaneously -/// coerced to `()`, even when it would not infer `()` without the fallback. There are plans to -/// change it in the [2024 edition] (and possibly in all editions on a later date); see -/// [Tracking Issue for making `!` fall back to `!`][fallback-ti]. -/// -/// [coercion site]: -/// [`()`]: prim@unit -/// [fallback-ti]: -/// [2024 edition]: -/// -#[unstable(feature = "never_type", issue = "35121")] -mod prim_never {} - -#[rustc_doc_primitive = "char"] -#[allow(rustdoc::invalid_rust_codeblocks)] -/// A character type. -/// -/// The `char` type represents a single character. More specifically, since -/// 'character' isn't a well-defined concept in Unicode, `char` is a '[Unicode -/// scalar value]'. -/// -/// This documentation describes a number of methods and trait implementations on the -/// `char` type. For technical reasons, there is additional, separate -/// documentation in [the `std::char` module](char/index.html) as well. -/// -/// # Validity and Layout -/// -/// A `char` is a '[Unicode scalar value]', which is any '[Unicode code point]' -/// other than a [surrogate code point]. This has a fixed numerical definition: -/// code points are in the range 0 to 0x10FFFF, inclusive. -/// Surrogate code points, used by UTF-16, are in the range 0xD800 to 0xDFFF. -/// -/// No `char` may be constructed, whether as a literal or at runtime, that is not a -/// Unicode scalar value. Violating this rule causes undefined behavior. -/// -/// ```compile_fail -/// // Each of these is a compiler error -/// ['\u{D800}', '\u{DFFF}', '\u{110000}']; -/// ``` -/// -/// ```should_panic -/// // Panics; from_u32 returns None. -/// char::from_u32(0xDE01).unwrap(); -/// ``` -/// -/// ```no_run -/// // Undefined behaviour -/// let _ = unsafe { char::from_u32_unchecked(0x110000) }; -/// ``` -/// -/// Unicode scalar values are also the exact set of values that may be encoded in UTF-8. Because -/// `char` values are Unicode scalar values and functions may assume [incoming `str` values are -/// valid UTF-8](primitive.str.html#invariant), it is safe to store any `char` in a `str` or read -/// any character from a `str` as a `char`. -/// -/// The gap in valid `char` values is understood by the compiler, so in the -/// below example the two ranges are understood to cover the whole range of -/// possible `char` values and there is no error for a [non-exhaustive match]. -/// -/// ``` -/// let c: char = 'a'; -/// match c { -/// '\0' ..= '\u{D7FF}' => false, -/// '\u{E000}' ..= '\u{10FFFF}' => true, -/// }; -/// ``` -/// -/// All Unicode scalar values are valid `char` values, but not all of them represent a real -/// character. Many Unicode scalar values are not currently assigned to a character, but may be in -/// the future ("reserved"); some will never be a character ("noncharacters"); and some may be given -/// different meanings by different users ("private use"). -/// -/// `char` is guaranteed to have the same size, alignment, and function call ABI as `u32` on all -/// platforms. -/// ``` -/// use std::alloc::Layout; -/// assert_eq!(Layout::new::(), Layout::new::()); -/// ``` -/// -/// [Unicode code point]: https://www.unicode.org/glossary/#code_point -/// [Unicode scalar value]: https://www.unicode.org/glossary/#unicode_scalar_value -/// [non-exhaustive match]: ../book/ch06-02-match.html#matches-are-exhaustive -/// [surrogate code point]: https://www.unicode.org/glossary/#surrogate_code_point -/// -/// # Representation -/// -/// `char` is always four bytes in size. This is a different representation than -/// a given character would have as part of a [`String`]. For example: -/// -/// ``` -/// let v = vec!['h', 'e', 'l', 'l', 'o']; -/// -/// // five elements times four bytes for each element -/// assert_eq!(20, v.len() * std::mem::size_of::()); -/// -/// let s = String::from("hello"); -/// -/// // five elements times one byte per element -/// assert_eq!(5, s.len() * std::mem::size_of::()); -/// ``` -/// -/// [`String`]: ../std/string/struct.String.html -/// -/// As always, remember that a human intuition for 'character' might not map to -/// Unicode's definitions. For example, despite looking similar, the 'é' -/// character is one Unicode code point while 'é' is two Unicode code points: -/// -/// ``` -/// let mut chars = "é".chars(); -/// // U+00e9: 'latin small letter e with acute' -/// assert_eq!(Some('\u{00e9}'), chars.next()); -/// assert_eq!(None, chars.next()); -/// -/// let mut chars = "é".chars(); -/// // U+0065: 'latin small letter e' -/// assert_eq!(Some('\u{0065}'), chars.next()); -/// // U+0301: 'combining acute accent' -/// assert_eq!(Some('\u{0301}'), chars.next()); -/// assert_eq!(None, chars.next()); -/// ``` -/// -/// This means that the contents of the first string above _will_ fit into a -/// `char` while the contents of the second string _will not_. Trying to create -/// a `char` literal with the contents of the second string gives an error: -/// -/// ```text -/// error: character literal may only contain one codepoint: 'é' -/// let c = 'é'; -/// ^^^ -/// ``` -/// -/// Another implication of the 4-byte fixed size of a `char` is that -/// per-`char` processing can end up using a lot more memory: -/// -/// ``` -/// let s = String::from("love: ❤️"); -/// let v: Vec = s.chars().collect(); -/// -/// assert_eq!(12, std::mem::size_of_val(&s[..])); -/// assert_eq!(32, std::mem::size_of_val(&v[..])); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_char {} - -#[rustc_doc_primitive = "unit"] -#[doc(alias = "(")] -#[doc(alias = ")")] -#[doc(alias = "()")] -// -/// The `()` type, also called "unit". -/// -/// The `()` type has exactly one value `()`, and is used when there -/// is no other meaningful value that could be returned. `()` is most -/// commonly seen implicitly: functions without a `-> ...` implicitly -/// have return type `()`, that is, these are equivalent: -/// -/// ```rust -/// fn long() -> () {} -/// -/// fn short() {} -/// ``` -/// -/// The semicolon `;` can be used to discard the result of an -/// expression at the end of a block, making the expression (and thus -/// the block) evaluate to `()`. For example, -/// -/// ```rust -/// fn returns_i64() -> i64 { -/// 1i64 -/// } -/// fn returns_unit() { -/// 1i64; -/// } -/// -/// let is_i64 = { -/// returns_i64() -/// }; -/// let is_unit = { -/// returns_i64(); -/// }; -/// ``` -/// -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_unit {} - -// Required to make auto trait impls render. -// See src/librustdoc/passes/collect_trait_impls.rs:collect_trait_impls -#[doc(hidden)] -impl () {} - -#[rustc_doc_primitive = "pointer"] -#[doc(alias = "ptr")] -#[doc(alias = "*")] -#[doc(alias = "*const")] -#[doc(alias = "*mut")] -// -/// Raw, unsafe pointers, `*const T`, and `*mut T`. -/// -/// *[See also the `std::ptr` module](ptr).* -/// -/// Working with raw pointers in Rust is uncommon, typically limited to a few patterns. -/// Raw pointers can be unaligned or [`null`]. However, when a raw pointer is -/// dereferenced (using the `*` operator), it must be non-null and aligned. -/// -/// Storing through a raw pointer using `*ptr = data` calls `drop` on the old value, so -/// [`write`] must be used if the type has drop glue and memory is not already -/// initialized - otherwise `drop` would be called on the uninitialized memory. -/// -/// Use the [`null`] and [`null_mut`] functions to create null pointers, and the -/// [`is_null`] method of the `*const T` and `*mut T` types to check for null. -/// The `*const T` and `*mut T` types also define the [`offset`] method, for -/// pointer math. -/// -/// # Common ways to create raw pointers -/// -/// ## 1. Coerce a reference (`&T`) or mutable reference (`&mut T`). -/// -/// ``` -/// let my_num: i32 = 10; -/// let my_num_ptr: *const i32 = &my_num; -/// let mut my_speed: i32 = 88; -/// let my_speed_ptr: *mut i32 = &mut my_speed; -/// ``` -/// -/// To get a pointer to a boxed value, dereference the box: -/// -/// ``` -/// let my_num: Box = Box::new(10); -/// let my_num_ptr: *const i32 = &*my_num; -/// let mut my_speed: Box = Box::new(88); -/// let my_speed_ptr: *mut i32 = &mut *my_speed; -/// ``` -/// -/// This does not take ownership of the original allocation -/// and requires no resource management later, -/// but you must not use the pointer after its lifetime. -/// -/// ## 2. Consume a box (`Box`). -/// -/// The [`into_raw`] function consumes a box and returns -/// the raw pointer. It doesn't destroy `T` or deallocate any memory. -/// -/// ``` -/// let my_speed: Box = Box::new(88); -/// let my_speed: *mut i32 = Box::into_raw(my_speed); -/// -/// // By taking ownership of the original `Box` though -/// // we are obligated to put it together later to be destroyed. -/// unsafe { -/// drop(Box::from_raw(my_speed)); -/// } -/// ``` -/// -/// Note that here the call to [`drop`] is for clarity - it indicates -/// that we are done with the given value and it should be destroyed. -/// -/// ## 3. Create it using `ptr::addr_of!` -/// -/// Instead of coercing a reference to a raw pointer, you can use the macros -/// [`ptr::addr_of!`] (for `*const T`) and [`ptr::addr_of_mut!`] (for `*mut T`). -/// These macros allow you to create raw pointers to fields to which you cannot -/// create a reference (without causing undefined behaviour), such as an -/// unaligned field. This might be necessary if packed structs or uninitialized -/// memory is involved. -/// -/// ``` -/// #[derive(Debug, Default, Copy, Clone)] -/// #[repr(C, packed)] -/// struct S { -/// aligned: u8, -/// unaligned: u32, -/// } -/// let s = S::default(); -/// let p = std::ptr::addr_of!(s.unaligned); // not allowed with coercion -/// ``` -/// -/// ## 4. Get it from C. -/// -/// ``` -/// # mod libc { -/// # pub unsafe fn malloc(_size: usize) -> *mut core::ffi::c_void { core::ptr::NonNull::dangling().as_ptr() } -/// # pub unsafe fn free(_ptr: *mut core::ffi::c_void) {} -/// # } -/// # #[cfg(any())] -/// #[allow(unused_extern_crates)] -/// extern crate libc; -/// -/// use std::mem; -/// -/// unsafe { -/// let my_num: *mut i32 = libc::malloc(mem::size_of::()) as *mut i32; -/// if my_num.is_null() { -/// panic!("failed to allocate memory"); -/// } -/// libc::free(my_num as *mut core::ffi::c_void); -/// } -/// ``` -/// -/// Usually you wouldn't literally use `malloc` and `free` from Rust, -/// but C APIs hand out a lot of pointers generally, so are a common source -/// of raw pointers in Rust. -/// -/// [`null`]: ptr::null -/// [`null_mut`]: ptr::null_mut -/// [`is_null`]: pointer::is_null -/// [`offset`]: pointer::offset -/// [`into_raw`]: ../std/boxed/struct.Box.html#method.into_raw -/// [`write`]: ptr::write -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_pointer {} - -#[rustc_doc_primitive = "array"] -#[doc(alias = "[]")] -#[doc(alias = "[T;N]")] // unfortunately, rustdoc doesn't have fuzzy search for aliases -#[doc(alias = "[T; N]")] -/// A fixed-size array, denoted `[T; N]`, for the element type, `T`, and the -/// non-negative compile-time constant size, `N`. -/// -/// There are two syntactic forms for creating an array: -/// -/// * A list with each element, i.e., `[x, y, z]`. -/// * A repeat expression `[expr; N]` where `N` is how many times to repeat `expr` in the array. `expr` must either be: -/// -/// * A value of a type implementing the [`Copy`] trait -/// * A `const` value -/// -/// Note that `[expr; 0]` is allowed, and produces an empty array. -/// This will still evaluate `expr`, however, and immediately drop the resulting value, so -/// be mindful of side effects. -/// -/// Arrays of *any* size implement the following traits if the element type allows it: -/// -/// - [`Copy`] -/// - [`Clone`] -/// - [`Debug`] -/// - [`IntoIterator`] (implemented for `[T; N]`, `&[T; N]` and `&mut [T; N]`) -/// - [`PartialEq`], [`PartialOrd`], [`Eq`], [`Ord`] -/// - [`Hash`] -/// - [`AsRef`], [`AsMut`] -/// - [`Borrow`], [`BorrowMut`] -/// -/// Arrays of sizes from 0 to 32 (inclusive) implement the [`Default`] trait -/// if the element type allows it. As a stopgap, trait implementations are -/// statically generated up to size 32. -/// -/// Arrays of sizes from 1 to 12 (inclusive) implement [`From`], where `Tuple` -/// is a homogeneous [prim@tuple] of appropriate length. -/// -/// Arrays coerce to [slices (`[T]`)][slice], so a slice method may be called on -/// an array. Indeed, this provides most of the API for working with arrays. -/// -/// Slices have a dynamic size and do not coerce to arrays. Instead, use -/// `slice.try_into().unwrap()` or `::try_from(slice).unwrap()`. -/// -/// Array's `try_from(slice)` implementations (and the corresponding `slice.try_into()` -/// array implementations) succeed if the input slice length is the same as the result -/// array length. They optimize especially well when the optimizer can easily determine -/// the slice length, e.g. `<[u8; 4]>::try_from(&slice[4..8]).unwrap()`. Array implements -/// [TryFrom](crate::convert::TryFrom) returning: -/// -/// - `[T; N]` copies from the slice's elements -/// - `&[T; N]` references the original slice's elements -/// - `&mut [T; N]` references the original slice's elements -/// -/// You can move elements out of an array with a [slice pattern]. If you want -/// one element, see [`mem::replace`]. -/// -/// # Examples -/// -/// ``` -/// let mut array: [i32; 3] = [0; 3]; -/// -/// array[1] = 1; -/// array[2] = 2; -/// -/// assert_eq!([1, 2], &array[1..]); -/// -/// // This loop prints: 0 1 2 -/// for x in array { -/// print!("{x} "); -/// } -/// ``` -/// -/// You can also iterate over reference to the array's elements: -/// -/// ``` -/// let array: [i32; 3] = [0; 3]; -/// -/// for x in &array { } -/// ``` -/// -/// You can use `::try_from(slice)` or `slice.try_into()` to get an array from -/// a slice: -/// -/// ``` -/// let bytes: [u8; 3] = [1, 0, 2]; -/// assert_eq!(1, u16::from_le_bytes(<[u8; 2]>::try_from(&bytes[0..2]).unwrap())); -/// assert_eq!(512, u16::from_le_bytes(bytes[1..3].try_into().unwrap())); -/// ``` -/// -/// You can use a [slice pattern] to move elements out of an array: -/// -/// ``` -/// fn move_away(_: String) { /* Do interesting things. */ } -/// -/// let [john, roa] = ["John".to_string(), "Roa".to_string()]; -/// move_away(john); -/// move_away(roa); -/// ``` -/// -/// Arrays can be created from homogeneous tuples of appropriate length: -/// -/// ``` -/// let tuple: (u32, u32, u32) = (1, 2, 3); -/// let array: [u32; 3] = tuple.into(); -/// ``` -/// -/// # Editions -/// -/// Prior to Rust 1.53, arrays did not implement [`IntoIterator`] by value, so the method call -/// `array.into_iter()` auto-referenced into a [slice iterator](slice::iter). Right now, the old -/// behavior is preserved in the 2015 and 2018 editions of Rust for compatibility, ignoring -/// [`IntoIterator`] by value. In the future, the behavior on the 2015 and 2018 edition -/// might be made consistent to the behavior of later editions. -/// -/// ```rust,edition2018 -/// // Rust 2015 and 2018: -/// -/// # #![allow(array_into_iter)] // override our `deny(warnings)` -/// let array: [i32; 3] = [0; 3]; -/// -/// // This creates a slice iterator, producing references to each value. -/// for item in array.into_iter().enumerate() { -/// let (i, x): (usize, &i32) = item; -/// println!("array[{i}] = {x}"); -/// } -/// -/// // The `array_into_iter` lint suggests this change for future compatibility: -/// for item in array.iter().enumerate() { -/// let (i, x): (usize, &i32) = item; -/// println!("array[{i}] = {x}"); -/// } -/// -/// // You can explicitly iterate an array by value using `IntoIterator::into_iter` -/// for item in IntoIterator::into_iter(array).enumerate() { -/// let (i, x): (usize, i32) = item; -/// println!("array[{i}] = {x}"); -/// } -/// ``` -/// -/// Starting in the 2021 edition, `array.into_iter()` uses `IntoIterator` normally to iterate -/// by value, and `iter()` should be used to iterate by reference like previous editions. -/// -/// ```rust,edition2021 -/// // Rust 2021: -/// -/// let array: [i32; 3] = [0; 3]; -/// -/// // This iterates by reference: -/// for item in array.iter().enumerate() { -/// let (i, x): (usize, &i32) = item; -/// println!("array[{i}] = {x}"); -/// } -/// -/// // This iterates by value: -/// for item in array.into_iter().enumerate() { -/// let (i, x): (usize, i32) = item; -/// println!("array[{i}] = {x}"); -/// } -/// ``` -/// -/// Future language versions might start treating the `array.into_iter()` -/// syntax on editions 2015 and 2018 the same as on edition 2021. So code using -/// those older editions should still be written with this change in mind, to -/// prevent breakage in the future. The safest way to accomplish this is to -/// avoid the `into_iter` syntax on those editions. If an edition update is not -/// viable/desired, there are multiple alternatives: -/// * use `iter`, equivalent to the old behavior, creating references -/// * use [`IntoIterator::into_iter`], equivalent to the post-2021 behavior (Rust 1.53+) -/// * replace `for ... in array.into_iter() {` with `for ... in array {`, -/// equivalent to the post-2021 behavior (Rust 1.53+) -/// -/// ```rust,edition2018 -/// // Rust 2015 and 2018: -/// -/// let array: [i32; 3] = [0; 3]; -/// -/// // This iterates by reference: -/// for item in array.iter() { -/// let x: &i32 = item; -/// println!("{x}"); -/// } -/// -/// // This iterates by value: -/// for item in IntoIterator::into_iter(array) { -/// let x: i32 = item; -/// println!("{x}"); -/// } -/// -/// // This iterates by value: -/// for item in array { -/// let x: i32 = item; -/// println!("{x}"); -/// } -/// -/// // IntoIter can also start a chain. -/// // This iterates by value: -/// for item in IntoIterator::into_iter(array).enumerate() { -/// let (i, x): (usize, i32) = item; -/// println!("array[{i}] = {x}"); -/// } -/// ``` -/// -/// [slice]: prim@slice -/// [`Debug`]: fmt::Debug -/// [`Hash`]: hash::Hash -/// [`Borrow`]: borrow::Borrow -/// [`BorrowMut`]: borrow::BorrowMut -/// [slice pattern]: ../reference/patterns.html#slice-patterns -/// [`From`]: convert::From -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_array {} - -#[rustc_doc_primitive = "slice"] -#[doc(alias = "[")] -#[doc(alias = "]")] -#[doc(alias = "[]")] -/// A dynamically-sized view into a contiguous sequence, `[T]`. Contiguous here -/// means that elements are laid out so that every element is the same -/// distance from its neighbors. -/// -/// *[See also the `std::slice` module](crate::slice).* -/// -/// Slices are a view into a block of memory represented as a pointer and a -/// length. -/// -/// ``` -/// // slicing a Vec -/// let vec = vec![1, 2, 3]; -/// let int_slice = &vec[..]; -/// // coercing an array to a slice -/// let str_slice: &[&str] = &["one", "two", "three"]; -/// ``` -/// -/// Slices are either mutable or shared. The shared slice type is `&[T]`, -/// while the mutable slice type is `&mut [T]`, where `T` represents the element -/// type. For example, you can mutate the block of memory that a mutable slice -/// points to: -/// -/// ``` -/// let mut x = [1, 2, 3]; -/// let x = &mut x[..]; // Take a full slice of `x`. -/// x[1] = 7; -/// assert_eq!(x, &[1, 7, 3]); -/// ``` -/// -/// As slices store the length of the sequence they refer to, they have twice -/// the size of pointers to [`Sized`](marker/trait.Sized.html) types. -/// Also see the reference on -/// [dynamically sized types](../reference/dynamically-sized-types.html). -/// -/// ``` -/// # use std::rc::Rc; -/// let pointer_size = std::mem::size_of::<&u8>(); -/// assert_eq!(2 * pointer_size, std::mem::size_of::<&[u8]>()); -/// assert_eq!(2 * pointer_size, std::mem::size_of::<*const [u8]>()); -/// assert_eq!(2 * pointer_size, std::mem::size_of::>()); -/// assert_eq!(2 * pointer_size, std::mem::size_of::>()); -/// ``` -/// -/// ## Trait Implementations -/// -/// Some traits are implemented for slices if the element type implements -/// that trait. This includes [`Eq`], [`Hash`] and [`Ord`]. -/// -/// ## Iteration -/// -/// The slices implement `IntoIterator`. The iterator yields references to the -/// slice elements. -/// -/// ``` -/// let numbers: &[i32] = &[0, 1, 2]; -/// for n in numbers { -/// println!("{n} is a number!"); -/// } -/// ``` -/// -/// The mutable slice yields mutable references to the elements: -/// -/// ``` -/// let mut scores: &mut [i32] = &mut [7, 8, 9]; -/// for score in scores { -/// *score += 1; -/// } -/// ``` -/// -/// This iterator yields mutable references to the slice's elements, so while -/// the element type of the slice is `i32`, the element type of the iterator is -/// `&mut i32`. -/// -/// * [`.iter`] and [`.iter_mut`] are the explicit methods to return the default -/// iterators. -/// * Further methods that return iterators are [`.split`], [`.splitn`], -/// [`.chunks`], [`.windows`] and more. -/// -/// [`Hash`]: core::hash::Hash -/// [`.iter`]: slice::iter -/// [`.iter_mut`]: slice::iter_mut -/// [`.split`]: slice::split -/// [`.splitn`]: slice::splitn -/// [`.chunks`]: slice::chunks -/// [`.windows`]: slice::windows -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_slice {} - -#[rustc_doc_primitive = "str"] -/// String slices. -/// -/// *[See also the `std::str` module](crate::str).* -/// -/// The `str` type, also called a 'string slice', is the most primitive string -/// type. It is usually seen in its borrowed form, `&str`. It is also the type -/// of string literals, `&'static str`. -/// -/// # Basic Usage -/// -/// String literals are string slices: -/// -/// ``` -/// let hello_world = "Hello, World!"; -/// ``` -/// -/// Here we have declared a string slice initialized with a string literal. -/// String literals have a static lifetime, which means the string `hello_world` -/// is guaranteed to be valid for the duration of the entire program. -/// We can explicitly specify `hello_world`'s lifetime as well: -/// -/// ``` -/// let hello_world: &'static str = "Hello, world!"; -/// ``` -/// -/// # Representation -/// -/// A `&str` is made up of two components: a pointer to some bytes, and a -/// length. You can look at these with the [`as_ptr`] and [`len`] methods: -/// -/// ``` -/// use std::slice; -/// use std::str; -/// -/// let story = "Once upon a time..."; -/// -/// let ptr = story.as_ptr(); -/// let len = story.len(); -/// -/// // story has nineteen bytes -/// assert_eq!(19, len); -/// -/// // We can re-build a str out of ptr and len. This is all unsafe because -/// // we are responsible for making sure the two components are valid: -/// let s = unsafe { -/// // First, we build a &[u8]... -/// let slice = slice::from_raw_parts(ptr, len); -/// -/// // ... and then convert that slice into a string slice -/// str::from_utf8(slice) -/// }; -/// -/// assert_eq!(s, Ok(story)); -/// ``` -/// -/// [`as_ptr`]: str::as_ptr -/// [`len`]: str::len -/// -/// Note: This example shows the internals of `&str`. `unsafe` should not be -/// used to get a string slice under normal circumstances. Use `as_str` -/// instead. -/// -/// # Invariant -/// -/// Rust libraries may assume that string slices are always valid UTF-8. -/// -/// Constructing a non-UTF-8 string slice is not immediate undefined behavior, but any function -/// called on a string slice may assume that it is valid UTF-8, which means that a non-UTF-8 string -/// slice can lead to undefined behavior down the road. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_str {} - -#[rustc_doc_primitive = "tuple"] -#[doc(alias = "(")] -#[doc(alias = ")")] -#[doc(alias = "()")] -// -/// A finite heterogeneous sequence, `(T, U, ..)`. -/// -/// Let's cover each of those in turn: -/// -/// Tuples are *finite*. In other words, a tuple has a length. Here's a tuple -/// of length `3`: -/// -/// ``` -/// ("hello", 5, 'c'); -/// ``` -/// -/// 'Length' is also sometimes called 'arity' here; each tuple of a different -/// length is a different, distinct type. -/// -/// Tuples are *heterogeneous*. This means that each element of the tuple can -/// have a different type. In that tuple above, it has the type: -/// -/// ``` -/// # let _: -/// (&'static str, i32, char) -/// # = ("hello", 5, 'c'); -/// ``` -/// -/// Tuples are a *sequence*. This means that they can be accessed by position; -/// this is called 'tuple indexing', and it looks like this: -/// -/// ```rust -/// let tuple = ("hello", 5, 'c'); -/// -/// assert_eq!(tuple.0, "hello"); -/// assert_eq!(tuple.1, 5); -/// assert_eq!(tuple.2, 'c'); -/// ``` -/// -/// The sequential nature of the tuple applies to its implementations of various -/// traits. For example, in [`PartialOrd`] and [`Ord`], the elements are compared -/// sequentially until the first non-equal set is found. -/// -/// For more about tuples, see [the book](../book/ch03-02-data-types.html#the-tuple-type). -/// -// Hardcoded anchor in src/librustdoc/html/format.rs -// linked to as `#trait-implementations-1` -/// # Trait implementations -/// -/// In this documentation the shorthand `(T₁, T₂, …, Tₙ)` is used to represent tuples of varying -/// length. When that is used, any trait bound expressed on `T` applies to each element of the -/// tuple independently. Note that this is a convenience notation to avoid repetitive -/// documentation, not valid Rust syntax. -/// -/// Due to a temporary restriction in Rust’s type system, the following traits are only -/// implemented on tuples of arity 12 or less. In the future, this may change: -/// -/// * [`PartialEq`] -/// * [`Eq`] -/// * [`PartialOrd`] -/// * [`Ord`] -/// * [`Debug`] -/// * [`Default`] -/// * [`Hash`] -/// * [`From<[T; N]>`][from] -/// -/// [from]: convert::From -/// [`Debug`]: fmt::Debug -/// [`Hash`]: hash::Hash -/// -/// The following traits are implemented for tuples of any length. These traits have -/// implementations that are automatically generated by the compiler, so are not limited by -/// missing language features. -/// -/// * [`Clone`] -/// * [`Copy`] -/// * [`Send`] -/// * [`Sync`] -/// * [`Unpin`] -/// * [`UnwindSafe`] -/// * [`RefUnwindSafe`] -/// -/// [`UnwindSafe`]: panic::UnwindSafe -/// [`RefUnwindSafe`]: panic::RefUnwindSafe -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// let tuple = ("hello", 5, 'c'); -/// -/// assert_eq!(tuple.0, "hello"); -/// ``` -/// -/// Tuples are often used as a return type when you want to return more than -/// one value: -/// -/// ``` -/// fn calculate_point() -> (i32, i32) { -/// // Don't do a calculation, that's not the point of the example -/// (4, 5) -/// } -/// -/// let point = calculate_point(); -/// -/// assert_eq!(point.0, 4); -/// assert_eq!(point.1, 5); -/// -/// // Combining this with patterns can be nicer. -/// -/// let (x, y) = calculate_point(); -/// -/// assert_eq!(x, 4); -/// assert_eq!(y, 5); -/// ``` -/// -/// Homogeneous tuples can be created from arrays of appropriate length: -/// -/// ``` -/// let array: [u32; 3] = [1, 2, 3]; -/// let tuple: (u32, u32, u32) = array.into(); -/// ``` -/// -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_tuple {} - -// Required to make auto trait impls render. -// See src/librustdoc/passes/collect_trait_impls.rs:collect_trait_impls -#[doc(hidden)] -impl (T,) {} - -#[rustc_doc_primitive = "f16"] -#[doc(alias = "half")] -/// A 16-bit floating point type (specifically, the "binary16" type defined in IEEE 754-2008). -/// -/// This type is very similar to [`prim@f32`] but has decreased precision because it uses half as many -/// bits. Please see [the documentation for [`prim@f32`] or [Wikipedia on -/// half-precision values][wikipedia] for more information. -/// -/// Note that most common platforms will not support `f16` in hardware without enabling extra target -/// features, with the notable exception of Apple Silicon (also known as M1, M2, etc.) processors. -/// Hardware support on x86-64 requires the avx512fp16 feature, while RISC-V requires Zhf. -/// Usually the fallback implementation will be to use `f32` hardware if it exists, and convert -/// between `f16` and `f32` when performing math. -/// -/// *[See also the `std::f16::consts` module](crate::f16::consts).* -/// -/// [wikipedia]: https://en.wikipedia.org/wiki/Half-precision_floating-point_format -#[unstable(feature = "f16", issue = "116909")] -mod prim_f16 {} - -#[rustc_doc_primitive = "f32"] -#[doc(alias = "single")] -/// A 32-bit floating point type (specifically, the "binary32" type defined in IEEE 754-2008). -/// -/// This type can represent a wide range of decimal numbers, like `3.5`, `27`, -/// `-113.75`, `0.0078125`, `34359738368`, `0`, `-1`. So unlike integer types -/// (such as `i32`), floating point types can represent non-integer numbers, -/// too. -/// -/// However, being able to represent this wide range of numbers comes at the -/// cost of precision: floats can only represent some of the real numbers and -/// calculation with floats round to a nearby representable number. For example, -/// `5.0` and `1.0` can be exactly represented as `f32`, but `1.0 / 5.0` results -/// in `0.20000000298023223876953125` since `0.2` cannot be exactly represented -/// as `f32`. Note, however, that printing floats with `println` and friends will -/// often discard insignificant digits: `println!("{}", 1.0f32 / 5.0f32)` will -/// print `0.2`. -/// -/// Additionally, `f32` can represent some special values: -/// -/// - −0.0: IEEE 754 floating point numbers have a bit that indicates their sign, so −0.0 is a -/// possible value. For comparison −0.0 = +0.0, but floating point operations can carry -/// the sign bit through arithmetic operations. This means −0.0 × +0.0 produces −0.0 and -/// a negative number rounded to a value smaller than a float can represent also produces −0.0. -/// - [∞](#associatedconstant.INFINITY) and -/// [−∞](#associatedconstant.NEG_INFINITY): these result from calculations -/// like `1.0 / 0.0`. -/// - [NaN (not a number)](#associatedconstant.NAN): this value results from -/// calculations like `(-1.0).sqrt()`. NaN has some potentially unexpected -/// behavior: -/// - It is not equal to any float, including itself! This is the reason `f32` -/// doesn't implement the `Eq` trait. -/// - It is also neither smaller nor greater than any float, making it -/// impossible to sort by the default comparison operation, which is the -/// reason `f32` doesn't implement the `Ord` trait. -/// - It is also considered *infectious* as almost all calculations where one -/// of the operands is NaN will also result in NaN. The explanations on this -/// page only explicitly document behavior on NaN operands if this default -/// is deviated from. -/// - Lastly, there are multiple bit patterns that are considered NaN. -/// Rust does not currently guarantee that the bit patterns of NaN are -/// preserved over arithmetic operations, and they are not guaranteed to be -/// portable or even fully deterministic! This means that there may be some -/// surprising results upon inspecting the bit patterns, -/// as the same calculations might produce NaNs with different bit patterns. -/// -/// When a primitive operation (addition, subtraction, multiplication, or -/// division) is performed on this type, the result is rounded according to the -/// roundTiesToEven direction defined in IEEE 754-2008. That means: -/// -/// - The result is the representable value closest to the true value, if there -/// is a unique closest representable value. -/// - If the true value is exactly half-way between two representable values, -/// the result is the one with an even least-significant binary digit. -/// - If the true value's magnitude is ≥ `f32::MAX` + 2(`f32::MAX_EXP` − -/// `f32::MANTISSA_DIGITS` − 1), the result is ∞ or −∞ (preserving the -/// true value's sign). -/// - If the result of a sum exactly equals zero, the outcome is +0.0 unless -/// both arguments were negative, then it is -0.0. Subtraction `a - b` is -/// regarded as a sum `a + (-b)`. -/// -/// For more information on floating point numbers, see [Wikipedia][wikipedia]. -/// -/// *[See also the `std::f32::consts` module](crate::f32::consts).* -/// -/// [wikipedia]: https://en.wikipedia.org/wiki/Single-precision_floating-point_format -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_f32 {} - -#[rustc_doc_primitive = "f64"] -#[doc(alias = "double")] -/// A 64-bit floating point type (specifically, the "binary64" type defined in IEEE 754-2008). -/// -/// This type is very similar to [`f32`], but has increased -/// precision by using twice as many bits. Please see [the documentation for -/// `f32`][`f32`] or [Wikipedia on double precision -/// values][wikipedia] for more information. -/// -/// *[See also the `std::f64::consts` module](crate::f64::consts).* -/// -/// [`f32`]: prim@f32 -/// [wikipedia]: https://en.wikipedia.org/wiki/Double-precision_floating-point_format -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_f64 {} - -#[rustc_doc_primitive = "f128"] -#[doc(alias = "quad")] -/// A 128-bit floating point type (specifically, the "binary128" type defined in IEEE 754-2008). -/// -/// This type is very similar to [`prim@f32`] and [`prim@f64`], but has increased precision by using twice -/// as many bits as `f64`. Please see [the documentation for [`prim@f32`] or [Wikipedia on -/// quad-precision values][wikipedia] for more information. -/// -/// Note that no platforms have hardware support for `f128` without enabling target specific features, -/// as for all instruction set architectures `f128` is considered an optional feature. -/// Only Power ISA ("PowerPC") and RISCV specify it, and only certain microarchitectures -/// actually implement it. For x86-64 and AArch64, ISA support is not even specified, -/// so it will always be a software implementation significantly slower than `f64`. -/// -/// *[See also the `std::f128::consts` module](crate::f128::consts).* -/// -/// [wikipedia]: https://en.wikipedia.org/wiki/Quadruple-precision_floating-point_format -#[unstable(feature = "f128", issue = "116909")] -mod prim_f128 {} - -#[rustc_doc_primitive = "i8"] -// -/// The 8-bit signed integer type. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_i8 {} - -#[rustc_doc_primitive = "i16"] -// -/// The 16-bit signed integer type. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_i16 {} - -#[rustc_doc_primitive = "i32"] -// -/// The 32-bit signed integer type. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_i32 {} - -#[rustc_doc_primitive = "i64"] -// -/// The 64-bit signed integer type. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_i64 {} - -#[rustc_doc_primitive = "i128"] -// -/// The 128-bit signed integer type. -#[stable(feature = "i128", since = "1.26.0")] -mod prim_i128 {} - -#[rustc_doc_primitive = "u8"] -// -/// The 8-bit unsigned integer type. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_u8 {} - -#[rustc_doc_primitive = "u16"] -// -/// The 16-bit unsigned integer type. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_u16 {} - -#[rustc_doc_primitive = "u32"] -// -/// The 32-bit unsigned integer type. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_u32 {} - -#[rustc_doc_primitive = "u64"] -// -/// The 64-bit unsigned integer type. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_u64 {} - -#[rustc_doc_primitive = "u128"] -// -/// The 128-bit unsigned integer type. -#[stable(feature = "i128", since = "1.26.0")] -mod prim_u128 {} - -#[rustc_doc_primitive = "isize"] -// -/// The pointer-sized signed integer type. -/// -/// The size of this primitive is how many bytes it takes to reference any -/// location in memory. For example, on a 32 bit target, this is 4 bytes -/// and on a 64 bit target, this is 8 bytes. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_isize {} - -#[rustc_doc_primitive = "usize"] -// -/// The pointer-sized unsigned integer type. -/// -/// The size of this primitive is how many bytes it takes to reference any -/// location in memory. For example, on a 32 bit target, this is 4 bytes -/// and on a 64 bit target, this is 8 bytes. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_usize {} - -#[rustc_doc_primitive = "reference"] -#[doc(alias = "&")] -#[doc(alias = "&mut")] -// -/// References, `&T` and `&mut T`. -/// -/// A reference represents a borrow of some owned value. You can get one by using the `&` or `&mut` -/// operators on a value, or by using a [`ref`](../std/keyword.ref.html) or -/// [ref](../std/keyword.ref.html) [mut](../std/keyword.mut.html) pattern. -/// -/// For those familiar with pointers, a reference is just a pointer that is assumed to be -/// aligned, not null, and pointing to memory containing a valid value of `T` - for example, -/// &[bool] can only point to an allocation containing the integer values `1` -/// ([`true`](../std/keyword.true.html)) or `0` ([`false`](../std/keyword.false.html)), but -/// creating a &[bool] that points to an allocation containing -/// the value `3` causes undefined behaviour. -/// In fact, [Option]\<&T> has the same memory representation as a -/// nullable but aligned pointer, and can be passed across FFI boundaries as such. -/// -/// In most cases, references can be used much like the original value. Field access, method -/// calling, and indexing work the same (save for mutability rules, of course). In addition, the -/// comparison operators transparently defer to the referent's implementation, allowing references -/// to be compared the same as owned values. -/// -/// References have a lifetime attached to them, which represents the scope for which the borrow is -/// valid. A lifetime is said to "outlive" another one if its representative scope is as long or -/// longer than the other. The `'static` lifetime is the longest lifetime, which represents the -/// total life of the program. For example, string literals have a `'static` lifetime because the -/// text data is embedded into the binary of the program, rather than in an allocation that needs -/// to be dynamically managed. -/// -/// `&mut T` references can be freely coerced into `&T` references with the same referent type, and -/// references with longer lifetimes can be freely coerced into references with shorter ones. -/// -/// Reference equality by address, instead of comparing the values pointed to, is accomplished via -/// implicit reference-pointer coercion and raw pointer equality via [`ptr::eq`], while -/// [`PartialEq`] compares values. -/// -/// ``` -/// use std::ptr; -/// -/// let five = 5; -/// let other_five = 5; -/// let five_ref = &five; -/// let same_five_ref = &five; -/// let other_five_ref = &other_five; -/// -/// assert!(five_ref == same_five_ref); -/// assert!(five_ref == other_five_ref); -/// -/// assert!(ptr::eq(five_ref, same_five_ref)); -/// assert!(!ptr::eq(five_ref, other_five_ref)); -/// ``` -/// -/// For more information on how to use references, see [the book's section on "References and -/// Borrowing"][book-refs]. -/// -/// [book-refs]: ../book/ch04-02-references-and-borrowing.html -/// -/// # Trait implementations -/// -/// The following traits are implemented for all `&T`, regardless of the type of its referent: -/// -/// * [`Copy`] -/// * [`Clone`] \(Note that this will not defer to `T`'s `Clone` implementation if it exists!) -/// * [`Deref`] -/// * [`Borrow`] -/// * [`fmt::Pointer`] -/// -/// [`Deref`]: ops::Deref -/// [`Borrow`]: borrow::Borrow -/// -/// `&mut T` references get all of the above except `Copy` and `Clone` (to prevent creating -/// multiple simultaneous mutable borrows), plus the following, regardless of the type of its -/// referent: -/// -/// * [`DerefMut`] -/// * [`BorrowMut`] -/// -/// [`DerefMut`]: ops::DerefMut -/// [`BorrowMut`]: borrow::BorrowMut -/// [bool]: prim@bool -/// -/// The following traits are implemented on `&T` references if the underlying `T` also implements -/// that trait: -/// -/// * All the traits in [`std::fmt`] except [`fmt::Pointer`] (which is implemented regardless of the type of its referent) and [`fmt::Write`] -/// * [`PartialOrd`] -/// * [`Ord`] -/// * [`PartialEq`] -/// * [`Eq`] -/// * [`AsRef`] -/// * [`Fn`] \(in addition, `&T` references get [`FnMut`] and [`FnOnce`] if `T: Fn`) -/// * [`Hash`] -/// * [`ToSocketAddrs`] -/// * [`Sync`] -/// -/// [`std::fmt`]: fmt -/// [`Hash`]: hash::Hash -/// [`ToSocketAddrs`]: ../std/net/trait.ToSocketAddrs.html -/// -/// `&mut T` references get all of the above except `ToSocketAddrs`, plus the following, if `T` -/// implements that trait: -/// -/// * [`AsMut`] -/// * [`FnMut`] \(in addition, `&mut T` references get [`FnOnce`] if `T: FnMut`) -/// * [`fmt::Write`] -/// * [`Iterator`] -/// * [`DoubleEndedIterator`] -/// * [`ExactSizeIterator`] -/// * [`FusedIterator`] -/// * [`TrustedLen`] -/// * [`Send`] -/// * [`io::Write`] -/// * [`Read`] -/// * [`Seek`] -/// * [`BufRead`] -/// -/// [`FusedIterator`]: iter::FusedIterator -/// [`TrustedLen`]: iter::TrustedLen -/// [`Seek`]: ../std/io/trait.Seek.html -/// [`BufRead`]: ../std/io/trait.BufRead.html -/// [`Read`]: ../std/io/trait.Read.html -/// [`io::Write`]: ../std/io/trait.Write.html -/// -/// In addition, `&T` references implement [`Send`] if and only if `T` implements [`Sync`]. -/// -/// Note that due to method call deref coercion, simply calling a trait method will act like they -/// work on references as well as they do on owned values! The implementations described here are -/// meant for generic contexts, where the final type `T` is a type parameter or otherwise not -/// locally known. -/// -/// # Safety -/// -/// For all types, `T: ?Sized`, and for all `t: &T` or `t: &mut T`, when such values cross an API -/// boundary, the following invariants must generally be upheld: -/// -/// * `t` is non-null -/// * `t` is aligned to `align_of_val(t)` -/// * if `size_of_val(t) > 0`, then `t` is dereferenceable for `size_of_val(t)` many bytes -/// -/// If `t` points at address `a`, being "dereferenceable" for N bytes means that the memory range -/// `[a, a + N)` is all contained within a single [allocated object]. -/// -/// For instance, this means that unsafe code in a safe function may assume these invariants are -/// ensured of arguments passed by the caller, and it may assume that these invariants are ensured -/// of return values from any safe functions it calls. -/// -/// For the other direction, things are more complicated: when unsafe code passes arguments -/// to safe functions or returns values from safe functions, they generally must *at least* -/// not violate these invariants. The full requirements are stronger, as the reference generally -/// must point to data that is safe to use at type `T`. -/// -/// It is not decided yet whether unsafe code may violate these invariants temporarily on internal -/// data. As a consequence, unsafe code which violates these invariants temporarily on internal data -/// may be unsound or become unsound in future versions of Rust depending on how this question is -/// decided. -/// -/// [allocated object]: ptr#allocated-object -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_ref {} - -#[rustc_doc_primitive = "fn"] -// -/// Function pointers, like `fn(usize) -> bool`. -/// -/// *See also the traits [`Fn`], [`FnMut`], and [`FnOnce`].* -/// -/// Function pointers are pointers that point to *code*, not data. They can be called -/// just like functions. Like references, function pointers are, among other things, assumed to -/// not be null, so if you want to pass a function pointer over FFI and be able to accommodate null -/// pointers, make your type [`Option`](core::option#options-and-pointers-nullable-pointers) -/// with your required signature. -/// -/// ### Safety -/// -/// Plain function pointers are obtained by casting either plain functions, or closures that don't -/// capture an environment: -/// -/// ``` -/// fn add_one(x: usize) -> usize { -/// x + 1 -/// } -/// -/// let ptr: fn(usize) -> usize = add_one; -/// assert_eq!(ptr(5), 6); -/// -/// let clos: fn(usize) -> usize = |x| x + 5; -/// assert_eq!(clos(5), 10); -/// ``` -/// -/// In addition to varying based on their signature, function pointers come in two flavors: safe -/// and unsafe. Plain `fn()` function pointers can only point to safe functions, -/// while `unsafe fn()` function pointers can point to safe or unsafe functions. -/// -/// ``` -/// fn add_one(x: usize) -> usize { -/// x + 1 -/// } -/// -/// unsafe fn add_one_unsafely(x: usize) -> usize { -/// x + 1 -/// } -/// -/// let safe_ptr: fn(usize) -> usize = add_one; -/// -/// //ERROR: mismatched types: expected normal fn, found unsafe fn -/// //let bad_ptr: fn(usize) -> usize = add_one_unsafely; -/// -/// let unsafe_ptr: unsafe fn(usize) -> usize = add_one_unsafely; -/// let really_safe_ptr: unsafe fn(usize) -> usize = add_one; -/// ``` -/// -/// ### ABI -/// -/// On top of that, function pointers can vary based on what ABI they use. This -/// is achieved by adding the `extern` keyword before the type, followed by the -/// ABI in question. The default ABI is "Rust", i.e., `fn()` is the exact same -/// type as `extern "Rust" fn()`. A pointer to a function with C ABI would have -/// type `extern "C" fn()`. -/// -/// `extern "ABI" { ... }` blocks declare functions with ABI "ABI". The default -/// here is "C", i.e., functions declared in an `extern {...}` block have "C" -/// ABI. -/// -/// For more information and a list of supported ABIs, see [the nomicon's -/// section on foreign calling conventions][nomicon-abi]. -/// -/// [nomicon-abi]: ../nomicon/ffi.html#foreign-calling-conventions -/// -/// ### Variadic functions -/// -/// Extern function declarations with the "C" or "cdecl" ABIs can also be *variadic*, allowing them -/// to be called with a variable number of arguments. Normal Rust functions, even those with an -/// `extern "ABI"`, cannot be variadic. For more information, see [the nomicon's section on -/// variadic functions][nomicon-variadic]. -/// -/// [nomicon-variadic]: ../nomicon/ffi.html#variadic-functions -/// -/// ### Creating function pointers -/// -/// When `bar` is the name of a function, then the expression `bar` is *not* a -/// function pointer. Rather, it denotes a value of an unnameable type that -/// uniquely identifies the function `bar`. The value is zero-sized because the -/// type already identifies the function. This has the advantage that "calling" -/// the value (it implements the `Fn*` traits) does not require dynamic -/// dispatch. -/// -/// This zero-sized type *coerces* to a regular function pointer. For example: -/// -/// ```rust -/// use std::mem; -/// -/// fn bar(x: i32) {} -/// -/// let not_bar_ptr = bar; // `not_bar_ptr` is zero-sized, uniquely identifying `bar` -/// assert_eq!(mem::size_of_val(¬_bar_ptr), 0); -/// -/// let bar_ptr: fn(i32) = not_bar_ptr; // force coercion to function pointer -/// assert_eq!(mem::size_of_val(&bar_ptr), mem::size_of::()); -/// -/// let footgun = &bar; // this is a shared reference to the zero-sized type identifying `bar` -/// ``` -/// -/// The last line shows that `&bar` is not a function pointer either. Rather, it -/// is a reference to the function-specific ZST. `&bar` is basically never what you -/// want when `bar` is a function. -/// -/// ### Casting to and from integers -/// -/// You can cast function pointers directly to integers: -/// -/// ```rust -/// let fnptr: fn(i32) -> i32 = |x| x+2; -/// let fnptr_addr = fnptr as usize; -/// ``` -/// -/// However, a direct cast back is not possible. You need to use `transmute`: -/// -/// ```rust -/// # #[cfg(not(miri))] { // FIXME: use strict provenance APIs once they are stable, then remove this `cfg` -/// # let fnptr: fn(i32) -> i32 = |x| x+2; -/// # let fnptr_addr = fnptr as usize; -/// let fnptr = fnptr_addr as *const (); -/// let fnptr: fn(i32) -> i32 = unsafe { std::mem::transmute(fnptr) }; -/// assert_eq!(fnptr(40), 42); -/// # } -/// ``` -/// -/// Crucially, we `as`-cast to a raw pointer before `transmute`ing to a function pointer. -/// This avoids an integer-to-pointer `transmute`, which can be problematic. -/// Transmuting between raw pointers and function pointers (i.e., two pointer types) is fine. -/// -/// Note that all of this is not portable to platforms where function pointers and data pointers -/// have different sizes. -/// -/// ### ABI compatibility -/// -/// Generally, when a function is declared with one signature and called via a function pointer with -/// a different signature, the two signatures must be *ABI-compatible* or else calling the function -/// via that function pointer is Undefined Behavior. ABI compatibility is a lot stricter than merely -/// having the same memory layout; for example, even if `i32` and `f32` have the same size and -/// alignment, they might be passed in different registers and hence not be ABI-compatible. -/// -/// ABI compatibility as a concern only arises in code that alters the type of function pointers, -/// code that imports functions via `extern` blocks, and in code that combines `#[target_feature]` -/// with `extern fn`. Altering the type of function pointers is wildly unsafe (as in, a lot more -/// unsafe than even [`transmute_copy`][mem::transmute_copy]), and should only occur in the most -/// exceptional circumstances. Most Rust code just imports functions via `use`. `#[target_feature]` -/// is also used rarely. So, most likely you do not have to worry about ABI compatibility. -/// -/// But assuming such circumstances, what are the rules? For this section, we are only considering -/// the ABI of direct Rust-to-Rust calls, not linking in general -- once functions are imported via -/// `extern` blocks, there are more things to consider that we do not go into here. -/// -/// For two signatures to be considered *ABI-compatible*, they must use a compatible ABI string, -/// must take the same number of arguments, the individual argument types and the return types must -/// be ABI-compatible, and the target feature requirements must be met (see the subsection below for -/// the last point). The ABI string is declared via `extern "ABI" fn(...) -> ...`; note that -/// `fn name(...) -> ...` implicitly uses the `"Rust"` ABI string and `extern fn name(...) -> ...` -/// implicitly uses the `"C"` ABI string. -/// -/// The ABI strings are guaranteed to be compatible if they are the same, or if the caller ABI -/// string is `$X-unwind` and the callee ABI string is `$X`, where `$X` is one of the following: -/// "C", "aapcs", "fastcall", "stdcall", "system", "sysv64", "thiscall", "vectorcall", "win64". -/// -/// The following types are guaranteed to be ABI-compatible: -/// -/// - `*const T`, `*mut T`, `&T`, `&mut T`, `Box` (specifically, only `Box`), and -/// `NonNull` are all ABI-compatible with each other for all `T`. They are also ABI-compatible -/// with each other for _different_ `T` if they have the same metadata type (`::Metadata`). -/// - `usize` is ABI-compatible with the `uN` integer type of the same size, and likewise `isize` is -/// ABI-compatible with the `iN` integer type of the same size. -/// - `char` is ABI-compatible with `u32`. -/// - Any two `fn` (function pointer) types are ABI-compatible with each other if they have the same -/// ABI string or the ABI string only differs in a trailing `-unwind`, independent of the rest of -/// their signature. (This means you can pass `fn()` to a function expecting `fn(i32)`, and the -/// call will be valid ABI-wise. The callee receives the result of transmuting the function pointer -/// from `fn()` to `fn(i32)`; that transmutation is itself a well-defined operation, it's just -/// almost certainly UB to later call that function pointer.) -/// - Any two types with size 0 and alignment 1 are ABI-compatible. -/// - A `repr(transparent)` type `T` is ABI-compatible with its unique non-trivial field, i.e., the -/// unique field that doesn't have size 0 and alignment 1 (if there is such a field). -/// - `i32` is ABI-compatible with `NonZero`, and similar for all other integer types. -/// - If `T` is guaranteed to be subject to the [null pointer -/// optimization](option/index.html#representation), then `T` and `Option` are ABI-compatible. -/// -/// Furthermore, ABI compatibility satisfies the following general properties: -/// -/// - Every type is ABI-compatible with itself. -/// - If `T1` and `T2` are ABI-compatible and `T2` and `T3` are ABI-compatible, then so are `T1` and -/// `T3` (i.e., ABI-compatibility is transitive). -/// - If `T1` and `T2` are ABI-compatible, then so are `T2` and `T1` (i.e., ABI-compatibility is -/// symmetric). -/// -/// More signatures can be ABI-compatible on specific targets, but that should not be relied upon -/// since it is not portable and not a stable guarantee. -/// -/// Noteworthy cases of types *not* being ABI-compatible in general are: -/// * `bool` vs `u8`, `i32` vs `u32`, `char` vs `i32`: on some targets, the calling conventions for -/// these types differ in terms of what they guarantee for the remaining bits in the register that -/// are not used by the value. -/// * `i32` vs `f32` are not compatible either, as has already been mentioned above. -/// * `struct Foo(u32)` and `u32` are not compatible (without `repr(transparent)`) since structs are -/// aggregate types and often passed in a different way than primitives like `i32`. -/// -/// Note that these rules describe when two completely known types are ABI-compatible. When -/// considering ABI compatibility of a type declared in another crate (including the standard -/// library), consider that any type that has a private field or the `#[non_exhaustive]` attribute -/// may change its layout as a non-breaking update unless documented otherwise -- so for instance, -/// even if such a type is a 1-ZST or `repr(transparent)` right now, this might change with any -/// library version bump. -/// -/// If the declared signature and the signature of the function pointer are ABI-compatible, then the -/// function call behaves as if every argument was [`transmute`d][mem::transmute] from the -/// type in the function pointer to the type at the function declaration, and the return value is -/// [`transmute`d][mem::transmute] from the type in the declaration to the type in the -/// pointer. All the usual caveats and concerns around transmutation apply; for instance, if the -/// function expects a `NonZero` and the function pointer uses the ABI-compatible type -/// `Option>`, and the value used for the argument is `None`, then this call is Undefined -/// Behavior since transmuting `None::>` to `NonZero` violates the non-zero -/// requirement. -/// -/// #### Requirements concerning target features -/// -/// Under some conditions, the signature used by the caller and the callee can be ABI-incompatible -/// even if the exact same ABI string and types are being used. As an example, the -/// `std::arch::x86_64::__m256` type has a different `extern "C"` ABI when the `avx` feature is -/// enabled vs when it is not enabled. -/// -/// Therefore, to ensure ABI compatibility when code using different target features is combined -/// (such as via `#[target_feature]`), we further require that one of the following conditions is -/// met: -/// -/// - The function uses the `"Rust"` ABI string (which is the default without `extern`). -/// - Caller and callee are using the exact same set of target features. For the callee we consider -/// the features enabled (via `#[target_feature]` and `-C target-feature`/`-C target-cpu`) at the -/// declaration site; for the caller we consider the features enabled at the call site. -/// - Neither any argument nor the return value involves a SIMD type (`#[repr(simd)]`) that is not -/// behind a pointer indirection (i.e., `*mut __m256` is fine, but `(i32, __m256)` is not). -/// -/// ### Trait implementations -/// -/// In this documentation the shorthand `fn(T₁, T₂, …, Tₙ)` is used to represent non-variadic -/// function pointers of varying length. Note that this is a convenience notation to avoid -/// repetitive documentation, not valid Rust syntax. -/// -/// The following traits are implemented for function pointers with any number of arguments and -/// any ABI. -/// -/// * [`PartialEq`] -/// * [`Eq`] -/// * [`PartialOrd`] -/// * [`Ord`] -/// * [`Hash`] -/// * [`Pointer`] -/// * [`Debug`] -/// * [`Clone`] -/// * [`Copy`] -/// * [`Send`] -/// * [`Sync`] -/// * [`Unpin`] -/// * [`UnwindSafe`] -/// * [`RefUnwindSafe`] -/// -/// Note that while this type implements `PartialEq`, comparing function pointers is unreliable: -/// pointers to the same function can compare inequal (because functions are duplicated in multiple -/// codegen units), and pointers to *different* functions can compare equal (since identical -/// functions can be deduplicated within a codegen unit). -/// -/// [`Hash`]: hash::Hash -/// [`Pointer`]: fmt::Pointer -/// [`UnwindSafe`]: panic::UnwindSafe -/// [`RefUnwindSafe`]: panic::RefUnwindSafe -/// -/// In addition, all *safe* function pointers implement [`Fn`], [`FnMut`], and [`FnOnce`], because -/// these traits are specially known to the compiler. -#[stable(feature = "rust1", since = "1.0.0")] -mod prim_fn {} - -// Required to make auto trait impls render. -// See src/librustdoc/passes/collect_trait_impls.rs:collect_trait_impls -#[doc(hidden)] -impl fn(T) -> Ret {} diff --git a/library/core/src/ptr/alignment.rs b/library/core/src/ptr/alignment.rs deleted file mode 100644 index e5f5bf6a50313..0000000000000 --- a/library/core/src/ptr/alignment.rs +++ /dev/null @@ -1,372 +0,0 @@ -use safety::requires; -use crate::num::NonZero; -#[cfg(debug_assertions)] -use crate::ub_checks::assert_unsafe_precondition; -use crate::{cmp, fmt, hash, mem, num}; - -#[cfg(kani)] -use crate::kani; - -/// A type storing a `usize` which is a power of two, and thus -/// represents a possible alignment in the Rust abstract machine. -/// -/// Note that particularly large alignments, while representable in this type, -/// are likely not to be supported by actual allocators and linkers. -#[unstable(feature = "ptr_alignment_type", issue = "102070")] -#[derive(Copy, Clone, PartialEq, Eq)] -#[repr(transparent)] -pub struct Alignment(AlignmentEnum); - -// Alignment is `repr(usize)`, but via extra steps. -const _: () = assert!(mem::size_of::() == mem::size_of::()); -const _: () = assert!(mem::align_of::() == mem::align_of::()); - -fn _alignment_can_be_structurally_matched(a: Alignment) -> bool { - matches!(a, Alignment::MIN) -} - -impl Alignment { - /// The smallest possible alignment, 1. - /// - /// All addresses are always aligned at least this much. - /// - /// # Examples - /// - /// ``` - /// #![feature(ptr_alignment_type)] - /// use std::ptr::Alignment; - /// - /// assert_eq!(Alignment::MIN.as_usize(), 1); - /// ``` - #[unstable(feature = "ptr_alignment_type", issue = "102070")] - pub const MIN: Self = Self(AlignmentEnum::_Align1Shl0); - - /// Returns the alignment for a type. - /// - /// This provides the same numerical value as [`mem::align_of`], - /// but in an `Alignment` instead of a `usize`. - #[unstable(feature = "ptr_alignment_type", issue = "102070")] - #[rustc_const_unstable(feature = "ptr_alignment_type", issue = "102070")] - #[inline] - pub const fn of() -> Self { - // SAFETY: rustc ensures that type alignment is always a power of two. - unsafe { Alignment::new_unchecked(mem::align_of::()) } - } - - /// Creates an `Alignment` from a `usize`, or returns `None` if it's - /// not a power of two. - /// - /// Note that `0` is not a power of two, nor a valid alignment. - #[unstable(feature = "ptr_alignment_type", issue = "102070")] - #[rustc_const_unstable(feature = "ptr_alignment_type", issue = "102070")] - #[inline] - pub const fn new(align: usize) -> Option { - if align.is_power_of_two() { - // SAFETY: Just checked it only has one bit set - Some(unsafe { Self::new_unchecked(align) }) - } else { - None - } - } - - /// Creates an `Alignment` from a power-of-two `usize`. - /// - /// # Safety - /// - /// `align` must be a power of two. - /// - /// Equivalently, it must be `1 << exp` for some `exp` in `0..usize::BITS`. - /// It must *not* be zero. - #[unstable(feature = "ptr_alignment_type", issue = "102070")] - #[rustc_const_unstable(feature = "ptr_alignment_type", issue = "102070")] - #[inline] - #[requires(align > 0)] - #[requires((align & (align - 1)) == 0)] - pub const unsafe fn new_unchecked(align: usize) -> Self { - #[cfg(debug_assertions)] - assert_unsafe_precondition!( - check_language_ub, - "Alignment::new_unchecked requires a power of two", - (align: usize = align) => align.is_power_of_two() - ); - - // SAFETY: By precondition, this must be a power of two, and - // our variants encompass all possible powers of two. - unsafe { mem::transmute::(align) } - } - - /// Returns the alignment as a [`usize`]. - #[unstable(feature = "ptr_alignment_type", issue = "102070")] - #[rustc_const_unstable(feature = "ptr_alignment_type", issue = "102070")] - #[inline] - pub const fn as_usize(self) -> usize { - self.0 as usize - } - - /// Returns the alignment as a [NonZero]<[usize]>. - #[unstable(feature = "ptr_alignment_type", issue = "102070")] - #[rustc_const_unstable(feature = "ptr_alignment_type", issue = "102070")] - #[inline] - pub const fn as_nonzero(self) -> NonZero { - // SAFETY: All the discriminants are non-zero. - unsafe { NonZero::new_unchecked(self.as_usize()) } - } - - /// Returns the base-2 logarithm of the alignment. - /// - /// This is always exact, as `self` represents a power of two. - /// - /// # Examples - /// - /// ``` - /// #![feature(ptr_alignment_type)] - /// use std::ptr::Alignment; - /// - /// assert_eq!(Alignment::of::().log2(), 0); - /// assert_eq!(Alignment::new(1024).unwrap().log2(), 10); - /// ``` - #[unstable(feature = "ptr_alignment_type", issue = "102070")] - #[rustc_const_unstable(feature = "ptr_alignment_type", issue = "102070")] - #[inline] - pub const fn log2(self) -> u32 { - self.as_nonzero().trailing_zeros() - } - - /// Returns a bit mask that can be used to match this alignment. - /// - /// This is equivalent to `!(self.as_usize() - 1)`. - /// - /// # Examples - /// - /// ``` - /// #![feature(ptr_alignment_type)] - /// #![feature(ptr_mask)] - /// use std::ptr::{Alignment, NonNull}; - /// - /// #[repr(align(1))] struct Align1(u8); - /// #[repr(align(2))] struct Align2(u16); - /// #[repr(align(4))] struct Align4(u32); - /// let one = >::dangling().as_ptr(); - /// let two = >::dangling().as_ptr(); - /// let four = >::dangling().as_ptr(); - /// - /// assert_eq!(four.mask(Alignment::of::().mask()), four); - /// assert_eq!(four.mask(Alignment::of::().mask()), four); - /// assert_eq!(four.mask(Alignment::of::().mask()), four); - /// assert_ne!(one.mask(Alignment::of::().mask()), one); - /// ``` - #[unstable(feature = "ptr_alignment_type", issue = "102070")] - #[rustc_const_unstable(feature = "ptr_alignment_type", issue = "102070")] - #[inline] - pub const fn mask(self) -> usize { - // SAFETY: The alignment is always nonzero, and therefore decrementing won't overflow. - !(unsafe { self.as_usize().unchecked_sub(1) }) - } -} - -#[unstable(feature = "ptr_alignment_type", issue = "102070")] -impl fmt::Debug for Alignment { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "{:?} (1 << {:?})", self.as_nonzero(), self.log2()) - } -} - -#[unstable(feature = "ptr_alignment_type", issue = "102070")] -impl TryFrom> for Alignment { - type Error = num::TryFromIntError; - - #[inline] - fn try_from(align: NonZero) -> Result { - align.get().try_into() - } -} - -#[unstable(feature = "ptr_alignment_type", issue = "102070")] -impl TryFrom for Alignment { - type Error = num::TryFromIntError; - - #[inline] - fn try_from(align: usize) -> Result { - Self::new(align).ok_or(num::TryFromIntError(())) - } -} - -#[unstable(feature = "ptr_alignment_type", issue = "102070")] -impl From for NonZero { - #[inline] - fn from(align: Alignment) -> NonZero { - align.as_nonzero() - } -} - -#[unstable(feature = "ptr_alignment_type", issue = "102070")] -impl From for usize { - #[inline] - fn from(align: Alignment) -> usize { - align.as_usize() - } -} - -#[rustc_const_unstable(feature = "const_alloc_layout", issue = "67521")] -#[unstable(feature = "ptr_alignment_type", issue = "102070")] -impl cmp::Ord for Alignment { - #[inline] - fn cmp(&self, other: &Self) -> cmp::Ordering { - self.as_nonzero().get().cmp(&other.as_nonzero().get()) - } -} - -#[rustc_const_unstable(feature = "const_alloc_layout", issue = "67521")] -#[unstable(feature = "ptr_alignment_type", issue = "102070")] -impl cmp::PartialOrd for Alignment { - #[inline] - fn partial_cmp(&self, other: &Self) -> Option { - Some(self.cmp(other)) - } -} - -#[unstable(feature = "ptr_alignment_type", issue = "102070")] -impl hash::Hash for Alignment { - #[inline] - fn hash(&self, state: &mut H) { - self.as_nonzero().hash(state) - } -} - -/// Returns [`Alignment::MIN`], which is valid for any type. -#[unstable(feature = "ptr_alignment_type", issue = "102070")] -impl Default for Alignment { - fn default() -> Alignment { - Alignment::MIN - } -} - -#[cfg(target_pointer_width = "16")] -#[derive(Copy, Clone, PartialEq, Eq)] -#[repr(u16)] -enum AlignmentEnum { - _Align1Shl0 = 1 << 0, - _Align1Shl1 = 1 << 1, - _Align1Shl2 = 1 << 2, - _Align1Shl3 = 1 << 3, - _Align1Shl4 = 1 << 4, - _Align1Shl5 = 1 << 5, - _Align1Shl6 = 1 << 6, - _Align1Shl7 = 1 << 7, - _Align1Shl8 = 1 << 8, - _Align1Shl9 = 1 << 9, - _Align1Shl10 = 1 << 10, - _Align1Shl11 = 1 << 11, - _Align1Shl12 = 1 << 12, - _Align1Shl13 = 1 << 13, - _Align1Shl14 = 1 << 14, - _Align1Shl15 = 1 << 15, -} - -#[cfg(target_pointer_width = "32")] -#[derive(Copy, Clone, PartialEq, Eq)] -#[repr(u32)] -enum AlignmentEnum { - _Align1Shl0 = 1 << 0, - _Align1Shl1 = 1 << 1, - _Align1Shl2 = 1 << 2, - _Align1Shl3 = 1 << 3, - _Align1Shl4 = 1 << 4, - _Align1Shl5 = 1 << 5, - _Align1Shl6 = 1 << 6, - _Align1Shl7 = 1 << 7, - _Align1Shl8 = 1 << 8, - _Align1Shl9 = 1 << 9, - _Align1Shl10 = 1 << 10, - _Align1Shl11 = 1 << 11, - _Align1Shl12 = 1 << 12, - _Align1Shl13 = 1 << 13, - _Align1Shl14 = 1 << 14, - _Align1Shl15 = 1 << 15, - _Align1Shl16 = 1 << 16, - _Align1Shl17 = 1 << 17, - _Align1Shl18 = 1 << 18, - _Align1Shl19 = 1 << 19, - _Align1Shl20 = 1 << 20, - _Align1Shl21 = 1 << 21, - _Align1Shl22 = 1 << 22, - _Align1Shl23 = 1 << 23, - _Align1Shl24 = 1 << 24, - _Align1Shl25 = 1 << 25, - _Align1Shl26 = 1 << 26, - _Align1Shl27 = 1 << 27, - _Align1Shl28 = 1 << 28, - _Align1Shl29 = 1 << 29, - _Align1Shl30 = 1 << 30, - _Align1Shl31 = 1 << 31, -} - -#[cfg(target_pointer_width = "64")] -#[derive(Copy, Clone, PartialEq, Eq)] -#[repr(u64)] -enum AlignmentEnum { - _Align1Shl0 = 1 << 0, - _Align1Shl1 = 1 << 1, - _Align1Shl2 = 1 << 2, - _Align1Shl3 = 1 << 3, - _Align1Shl4 = 1 << 4, - _Align1Shl5 = 1 << 5, - _Align1Shl6 = 1 << 6, - _Align1Shl7 = 1 << 7, - _Align1Shl8 = 1 << 8, - _Align1Shl9 = 1 << 9, - _Align1Shl10 = 1 << 10, - _Align1Shl11 = 1 << 11, - _Align1Shl12 = 1 << 12, - _Align1Shl13 = 1 << 13, - _Align1Shl14 = 1 << 14, - _Align1Shl15 = 1 << 15, - _Align1Shl16 = 1 << 16, - _Align1Shl17 = 1 << 17, - _Align1Shl18 = 1 << 18, - _Align1Shl19 = 1 << 19, - _Align1Shl20 = 1 << 20, - _Align1Shl21 = 1 << 21, - _Align1Shl22 = 1 << 22, - _Align1Shl23 = 1 << 23, - _Align1Shl24 = 1 << 24, - _Align1Shl25 = 1 << 25, - _Align1Shl26 = 1 << 26, - _Align1Shl27 = 1 << 27, - _Align1Shl28 = 1 << 28, - _Align1Shl29 = 1 << 29, - _Align1Shl30 = 1 << 30, - _Align1Shl31 = 1 << 31, - _Align1Shl32 = 1 << 32, - _Align1Shl33 = 1 << 33, - _Align1Shl34 = 1 << 34, - _Align1Shl35 = 1 << 35, - _Align1Shl36 = 1 << 36, - _Align1Shl37 = 1 << 37, - _Align1Shl38 = 1 << 38, - _Align1Shl39 = 1 << 39, - _Align1Shl40 = 1 << 40, - _Align1Shl41 = 1 << 41, - _Align1Shl42 = 1 << 42, - _Align1Shl43 = 1 << 43, - _Align1Shl44 = 1 << 44, - _Align1Shl45 = 1 << 45, - _Align1Shl46 = 1 << 46, - _Align1Shl47 = 1 << 47, - _Align1Shl48 = 1 << 48, - _Align1Shl49 = 1 << 49, - _Align1Shl50 = 1 << 50, - _Align1Shl51 = 1 << 51, - _Align1Shl52 = 1 << 52, - _Align1Shl53 = 1 << 53, - _Align1Shl54 = 1 << 54, - _Align1Shl55 = 1 << 55, - _Align1Shl56 = 1 << 56, - _Align1Shl57 = 1 << 57, - _Align1Shl58 = 1 << 58, - _Align1Shl59 = 1 << 59, - _Align1Shl60 = 1 << 60, - _Align1Shl61 = 1 << 61, - _Align1Shl62 = 1 << 62, - _Align1Shl63 = 1 << 63, -} diff --git a/library/core/src/ptr/const_ptr.rs b/library/core/src/ptr/const_ptr.rs deleted file mode 100644 index c8065b2e70906..0000000000000 --- a/library/core/src/ptr/const_ptr.rs +++ /dev/null @@ -1,1930 +0,0 @@ -use super::*; -use crate::cmp::Ordering::{Equal, Greater, Less}; -use crate::intrinsics::const_eval_select; -use crate::mem::SizedTypeProperties; -use crate::slice::{self, SliceIndex}; - -impl *const T { - /// Returns `true` if the pointer is null. - /// - /// Note that unsized types have many possible null pointers, as only the - /// raw data pointer is considered, not their length, vtable, etc. - /// Therefore, two pointers that are null may still not compare equal to - /// each other. - /// - /// ## Behavior during const evaluation - /// - /// When this function is used during const evaluation, it may return `false` for pointers - /// that turn out to be null at runtime. Specifically, when a pointer to some memory - /// is offset beyond its bounds in such a way that the resulting pointer is null, - /// the function will still return `false`. There is no way for CTFE to know - /// the absolute position of that memory, so we cannot tell if the pointer is - /// null or not. - /// - /// # Examples - /// - /// ``` - /// let s: &str = "Follow the rabbit"; - /// let ptr: *const u8 = s.as_ptr(); - /// assert!(!ptr.is_null()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_ptr_is_null", issue = "74939")] - #[rustc_diagnostic_item = "ptr_const_is_null"] - #[inline] - pub const fn is_null(self) -> bool { - #[inline] - fn runtime_impl(ptr: *const u8) -> bool { - ptr.addr() == 0 - } - - #[inline] - const fn const_impl(ptr: *const u8) -> bool { - // Compare via a cast to a thin pointer, so fat pointers are only - // considering their "data" part for null-ness. - match (ptr).guaranteed_eq(null_mut()) { - None => false, - Some(res) => res, - } - } - - #[allow(unused_unsafe)] - const_eval_select((self as *const u8,), const_impl, runtime_impl) - } - - /// Casts to a pointer of another type. - #[stable(feature = "ptr_cast", since = "1.38.0")] - #[rustc_const_stable(feature = "const_ptr_cast", since = "1.38.0")] - #[rustc_diagnostic_item = "const_ptr_cast"] - #[inline(always)] - pub const fn cast(self) -> *const U { - self as _ - } - - /// Use the pointer value in a new pointer of another type. - /// - /// In case `meta` is a (fat) pointer to an unsized type, this operation - /// will ignore the pointer part, whereas for (thin) pointers to sized - /// types, this has the same effect as a simple cast. - /// - /// The resulting pointer will have provenance of `self`, i.e., for a fat - /// pointer, this operation is semantically the same as creating a new - /// fat pointer with the data pointer value of `self` but the metadata of - /// `meta`. - /// - /// # Examples - /// - /// This function is primarily useful for allowing byte-wise pointer - /// arithmetic on potentially fat pointers: - /// - /// ``` - /// #![feature(set_ptr_value)] - /// # use core::fmt::Debug; - /// let arr: [i32; 3] = [1, 2, 3]; - /// let mut ptr = arr.as_ptr() as *const dyn Debug; - /// let thin = ptr as *const u8; - /// unsafe { - /// ptr = thin.add(8).with_metadata_of(ptr); - /// # assert_eq!(*(ptr as *const i32), 3); - /// println!("{:?}", &*ptr); // will print "3" - /// } - /// ``` - #[unstable(feature = "set_ptr_value", issue = "75091")] - #[rustc_const_unstable(feature = "set_ptr_value", issue = "75091")] - #[must_use = "returns a new pointer rather than modifying its argument"] - #[inline] - pub const fn with_metadata_of(self, meta: *const U) -> *const U - where - U: ?Sized, - { - from_raw_parts::(self as *const (), metadata(meta)) - } - - /// Changes constness without changing the type. - /// - /// This is a bit safer than `as` because it wouldn't silently change the type if the code is - /// refactored. - #[stable(feature = "ptr_const_cast", since = "1.65.0")] - #[rustc_const_stable(feature = "ptr_const_cast", since = "1.65.0")] - #[rustc_diagnostic_item = "ptr_cast_mut"] - #[inline(always)] - pub const fn cast_mut(self) -> *mut T { - self as _ - } - - /// Casts a pointer to its raw bits. - /// - /// This is equivalent to `as usize`, but is more specific to enhance readability. - /// The inverse method is [`from_bits`](#method.from_bits). - /// - /// In particular, `*p as usize` and `p as usize` will both compile for - /// pointers to numeric types but do very different things, so using this - /// helps emphasize that reading the bits was intentional. - /// - /// # Examples - /// - /// ``` - /// #![feature(ptr_to_from_bits)] - /// # #[cfg(not(miri))] { // doctest does not work with strict provenance - /// let array = [13, 42]; - /// let p0: *const i32 = &array[0]; - /// assert_eq!(<*const _>::from_bits(p0.to_bits()), p0); - /// let p1: *const i32 = &array[1]; - /// assert_eq!(p1.to_bits() - p0.to_bits(), 4); - /// # } - /// ``` - #[unstable(feature = "ptr_to_from_bits", issue = "91126")] - #[deprecated( - since = "1.67.0", - note = "replaced by the `expose_provenance` method, or update your code \ - to follow the strict provenance rules using its APIs" - )] - #[inline(always)] - pub fn to_bits(self) -> usize - where - T: Sized, - { - self as usize - } - - /// Creates a pointer from its raw bits. - /// - /// This is equivalent to `as *const T`, but is more specific to enhance readability. - /// The inverse method is [`to_bits`](#method.to_bits). - /// - /// # Examples - /// - /// ``` - /// #![feature(ptr_to_from_bits)] - /// # #[cfg(not(miri))] { // doctest does not work with strict provenance - /// use std::ptr::NonNull; - /// let dangling: *const u8 = NonNull::dangling().as_ptr(); - /// assert_eq!(<*const u8>::from_bits(1), dangling); - /// # } - /// ``` - #[unstable(feature = "ptr_to_from_bits", issue = "91126")] - #[deprecated( - since = "1.67.0", - note = "replaced by the `ptr::with_exposed_provenance` function, or update \ - your code to follow the strict provenance rules using its APIs" - )] - #[allow(fuzzy_provenance_casts)] // this is an unstable and semi-deprecated cast function - #[inline(always)] - pub fn from_bits(bits: usize) -> Self - where - T: Sized, - { - bits as Self - } - - /// Gets the "address" portion of the pointer. - /// - /// This is similar to `self as usize`, which semantically discards *provenance* and - /// *address-space* information. However, unlike `self as usize`, casting the returned address - /// back to a pointer yields a [pointer without provenance][without_provenance], which is undefined behavior to dereference. To - /// properly restore the lost information and obtain a dereferenceable pointer, use - /// [`with_addr`][pointer::with_addr] or [`map_addr`][pointer::map_addr]. - /// - /// If using those APIs is not possible because there is no way to preserve a pointer with the - /// required provenance, then Strict Provenance might not be for you. Use pointer-integer casts - /// or [`expose_provenance`][pointer::expose_provenance] and [`with_exposed_provenance`][with_exposed_provenance] - /// instead. However, note that this makes your code less portable and less amenable to tools - /// that check for compliance with the Rust memory model. - /// - /// On most platforms this will produce a value with the same bytes as the original - /// pointer, because all the bytes are dedicated to describing the address. - /// Platforms which need to store additional information in the pointer may - /// perform a change of representation to produce a value containing only the address - /// portion of the pointer. What that means is up to the platform to define. - /// - /// This API and its claimed semantics are part of the Strict Provenance experiment, and as such - /// might change in the future (including possibly weakening this so it becomes wholly - /// equivalent to `self as usize`). See the [module documentation][crate::ptr] for details. - #[must_use] - #[inline(always)] - #[unstable(feature = "strict_provenance", issue = "95228")] - pub fn addr(self) -> usize { - // FIXME(strict_provenance_magic): I am magic and should be a compiler intrinsic. - // SAFETY: Pointer-to-integer transmutes are valid (if you are okay with losing the - // provenance). - unsafe { mem::transmute(self.cast::<()>()) } - } - - /// Exposes the "provenance" part of the pointer for future use in - /// [`with_exposed_provenance`][] and returns the "address" portion. - /// - /// This is equivalent to `self as usize`, which semantically discards *provenance* and - /// *address-space* information. Furthermore, this (like the `as` cast) has the implicit - /// side-effect of marking the provenance as 'exposed', so on platforms that support it you can - /// later call [`with_exposed_provenance`][] to reconstitute the original pointer including its - /// provenance. (Reconstructing address space information, if required, is your responsibility.) - /// - /// Using this method means that code is *not* following [Strict - /// Provenance][super#strict-provenance] rules. Supporting - /// [`with_exposed_provenance`][] complicates specification and reasoning and may not be supported by - /// tools that help you to stay conformant with the Rust memory model, so it is recommended to - /// use [`addr`][pointer::addr] wherever possible. - /// - /// On most platforms this will produce a value with the same bytes as the original pointer, - /// because all the bytes are dedicated to describing the address. Platforms which need to store - /// additional information in the pointer may not support this operation, since the 'expose' - /// side-effect which is required for [`with_exposed_provenance`][] to work is typically not - /// available. - /// - /// It is unclear whether this method can be given a satisfying unambiguous specification. This - /// API and its claimed semantics are part of [Exposed Provenance][super#exposed-provenance]. - /// - /// [`with_exposed_provenance`]: with_exposed_provenance - #[must_use] - #[inline(always)] - #[unstable(feature = "exposed_provenance", issue = "95228")] - pub fn expose_provenance(self) -> usize { - // FIXME(strict_provenance_magic): I am magic and should be a compiler intrinsic. - self.cast::<()>() as usize - } - - /// Creates a new pointer with the given address. - /// - /// This performs the same operation as an `addr as ptr` cast, but copies - /// the *address-space* and *provenance* of `self` to the new pointer. - /// This allows us to dynamically preserve and propagate this important - /// information in a way that is otherwise impossible with a unary cast. - /// - /// This is equivalent to using [`wrapping_offset`][pointer::wrapping_offset] to offset - /// `self` to the given address, and therefore has all the same capabilities and restrictions. - /// - /// This API and its claimed semantics are part of the Strict Provenance experiment, - /// see the [module documentation][crate::ptr] for details. - #[must_use] - #[inline] - #[unstable(feature = "strict_provenance", issue = "95228")] - pub fn with_addr(self, addr: usize) -> Self { - // FIXME(strict_provenance_magic): I am magic and should be a compiler intrinsic. - // - // In the mean-time, this operation is defined to be "as if" it was - // a wrapping_offset, so we can emulate it as such. This should properly - // restore pointer provenance even under today's compiler. - let self_addr = self.addr() as isize; - let dest_addr = addr as isize; - let offset = dest_addr.wrapping_sub(self_addr); - - // This is the canonical desugaring of this operation - self.wrapping_byte_offset(offset) - } - - /// Creates a new pointer by mapping `self`'s address to a new one. - /// - /// This is a convenience for [`with_addr`][pointer::with_addr], see that method for details. - /// - /// This API and its claimed semantics are part of the Strict Provenance experiment, - /// see the [module documentation][crate::ptr] for details. - #[must_use] - #[inline] - #[unstable(feature = "strict_provenance", issue = "95228")] - pub fn map_addr(self, f: impl FnOnce(usize) -> usize) -> Self { - self.with_addr(f(self.addr())) - } - - /// Decompose a (possibly wide) pointer into its data pointer and metadata components. - /// - /// The pointer can be later reconstructed with [`from_raw_parts`]. - #[unstable(feature = "ptr_metadata", issue = "81513")] - #[rustc_const_unstable(feature = "ptr_metadata", issue = "81513")] - #[inline] - pub const fn to_raw_parts(self) -> (*const (), ::Metadata) { - (self.cast(), metadata(self)) - } - - /// Returns `None` if the pointer is null, or else returns a shared reference to - /// the value wrapped in `Some`. If the value may be uninitialized, [`as_uninit_ref`] - /// must be used instead. - /// - /// [`as_uninit_ref`]: #method.as_uninit_ref - /// - /// # Safety - /// - /// When calling this method, you have to ensure that *either* the pointer is null *or* - /// all of the following is true: - /// - /// * The pointer must be properly aligned. - /// - /// * It must be "dereferenceable" in the sense defined in [the module documentation]. - /// - /// * The pointer must point to an initialized instance of `T`. - /// - /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is - /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. - /// In particular, while this reference exists, the memory the pointer points to must - /// not get mutated (except inside `UnsafeCell`). - /// - /// This applies even if the result of this method is unused! - /// (The part about being initialized is not yet fully decided, but until - /// it is, the only safe approach is to ensure that they are indeed initialized.) - /// - /// [the module documentation]: crate::ptr#safety - /// - /// # Examples - /// - /// ``` - /// let ptr: *const u8 = &10u8 as *const u8; - /// - /// unsafe { - /// if let Some(val_back) = ptr.as_ref() { - /// println!("We got back the value: {val_back}!"); - /// } - /// } - /// ``` - /// - /// # Null-unchecked version - /// - /// If you are sure the pointer can never be null and are looking for some kind of - /// `as_ref_unchecked` that returns the `&T` instead of `Option<&T>`, know that you can - /// dereference the pointer directly. - /// - /// ``` - /// let ptr: *const u8 = &10u8 as *const u8; - /// - /// unsafe { - /// let val_back = &*ptr; - /// println!("We got back the value: {val_back}!"); - /// } - /// ``` - #[stable(feature = "ptr_as_ref", since = "1.9.0")] - #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")] - #[inline] - pub const unsafe fn as_ref<'a>(self) -> Option<&'a T> { - // SAFETY: the caller must guarantee that `self` is valid - // for a reference if it isn't null. - if self.is_null() { None } else { unsafe { Some(&*self) } } - } - - /// Returns a shared reference to the value behind the pointer. - /// If the pointer may be null or the value may be uninitialized, [`as_uninit_ref`] must be used instead. - /// If the pointer may be null, but the value is known to have been initialized, [`as_ref`] must be used instead. - /// - /// [`as_ref`]: #method.as_ref - /// [`as_uninit_ref`]: #method.as_uninit_ref - /// - /// # Safety - /// - /// When calling this method, you have to ensure that all of the following is true: - /// - /// * The pointer must be properly aligned. - /// - /// * It must be "dereferenceable" in the sense defined in [the module documentation]. - /// - /// * The pointer must point to an initialized instance of `T`. - /// - /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is - /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. - /// In particular, while this reference exists, the memory the pointer points to must - /// not get mutated (except inside `UnsafeCell`). - /// - /// This applies even if the result of this method is unused! - /// (The part about being initialized is not yet fully decided, but until - /// it is, the only safe approach is to ensure that they are indeed initialized.) - /// - /// [the module documentation]: crate::ptr#safety - /// - /// # Examples - /// - /// ``` - /// #![feature(ptr_as_ref_unchecked)] - /// let ptr: *const u8 = &10u8 as *const u8; - /// - /// unsafe { - /// println!("We got back the value: {}!", ptr.as_ref_unchecked()); - /// } - /// ``` - // FIXME: mention it in the docs for `as_ref` and `as_uninit_ref` once stabilized. - #[unstable(feature = "ptr_as_ref_unchecked", issue = "122034")] - #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")] - #[inline] - #[must_use] - pub const unsafe fn as_ref_unchecked<'a>(self) -> &'a T { - // SAFETY: the caller must guarantee that `self` is valid for a reference - unsafe { &*self } - } - - /// Returns `None` if the pointer is null, or else returns a shared reference to - /// the value wrapped in `Some`. In contrast to [`as_ref`], this does not require - /// that the value has to be initialized. - /// - /// [`as_ref`]: #method.as_ref - /// - /// # Safety - /// - /// When calling this method, you have to ensure that *either* the pointer is null *or* - /// all of the following is true: - /// - /// * The pointer must be properly aligned. - /// - /// * It must be "dereferenceable" in the sense defined in [the module documentation]. - /// - /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is - /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. - /// In particular, while this reference exists, the memory the pointer points to must - /// not get mutated (except inside `UnsafeCell`). - /// - /// This applies even if the result of this method is unused! - /// - /// [the module documentation]: crate::ptr#safety - /// - /// # Examples - /// - /// ``` - /// #![feature(ptr_as_uninit)] - /// - /// let ptr: *const u8 = &10u8 as *const u8; - /// - /// unsafe { - /// if let Some(val_back) = ptr.as_uninit_ref() { - /// println!("We got back the value: {}!", val_back.assume_init()); - /// } - /// } - /// ``` - #[inline] - #[unstable(feature = "ptr_as_uninit", issue = "75402")] - #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")] - pub const unsafe fn as_uninit_ref<'a>(self) -> Option<&'a MaybeUninit> - where - T: Sized, - { - // SAFETY: the caller must guarantee that `self` meets all the - // requirements for a reference. - if self.is_null() { None } else { Some(unsafe { &*(self as *const MaybeUninit) }) } - } - - /// Calculates the offset from a pointer. - /// - /// `count` is in units of T; e.g., a `count` of 3 represents a pointer - /// offset of `3 * size_of::()` bytes. - /// - /// # Safety - /// - /// If any of the following conditions are violated, the result is Undefined - /// Behavior: - /// - /// * If the computed offset, **in bytes**, is non-zero, then both the starting and resulting - /// pointer must be either in bounds or at the end of the same [allocated object]. - /// (If it is zero, then the function is always well-defined.) - /// - /// * The computed offset, **in bytes**, cannot overflow an `isize`. - /// - /// * The offset being in bounds cannot rely on "wrapping around" the address - /// space. That is, the infinite-precision sum, **in bytes** must fit in a usize. - /// - /// The compiler and standard library generally tries to ensure allocations - /// never reach a size where an offset is a concern. For instance, `Vec` - /// and `Box` ensure they never allocate more than `isize::MAX` bytes, so - /// `vec.as_ptr().add(vec.len())` is always safe. - /// - /// Most platforms fundamentally can't even construct such an allocation. - /// For instance, no known 64-bit platform can ever serve a request - /// for 263 bytes due to page-table limitations or splitting the address space. - /// However, some 32-bit and 16-bit platforms may successfully serve a request for - /// more than `isize::MAX` bytes with things like Physical Address - /// Extension. As such, memory acquired directly from allocators or memory - /// mapped files *may* be too large to handle with this function. - /// - /// Consider using [`wrapping_offset`] instead if these constraints are - /// difficult to satisfy. The only advantage of this method is that it - /// enables more aggressive compiler optimizations. - /// - /// [`wrapping_offset`]: #method.wrapping_offset - /// [allocated object]: crate::ptr#allocated-object - /// - /// # Examples - /// - /// ``` - /// let s: &str = "123"; - /// let ptr: *const u8 = s.as_ptr(); - /// - /// unsafe { - /// println!("{}", *ptr.offset(1) as char); - /// println!("{}", *ptr.offset(2) as char); - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use = "returns a new pointer rather than modifying its argument"] - #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn offset(self, count: isize) -> *const T - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `offset`. - unsafe { intrinsics::offset(self, count) } - } - - /// Calculates the offset from a pointer in bytes. - /// - /// `count` is in units of **bytes**. - /// - /// This is purely a convenience for casting to a `u8` pointer and - /// using [offset][pointer::offset] on it. See that method for documentation - /// and safety requirements. - /// - /// For non-`Sized` pointees this operation changes only the data pointer, - /// leaving the metadata untouched. - #[must_use] - #[inline(always)] - #[stable(feature = "pointer_byte_offsets", since = "1.75.0")] - #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")] - #[rustc_allow_const_fn_unstable(set_ptr_value)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn byte_offset(self, count: isize) -> Self { - // SAFETY: the caller must uphold the safety contract for `offset`. - unsafe { self.cast::().offset(count).with_metadata_of(self) } - } - - /// Calculates the offset from a pointer using wrapping arithmetic. - /// - /// `count` is in units of T; e.g., a `count` of 3 represents a pointer - /// offset of `3 * size_of::()` bytes. - /// - /// # Safety - /// - /// This operation itself is always safe, but using the resulting pointer is not. - /// - /// The resulting pointer "remembers" the [allocated object] that `self` points to; it must not - /// be used to read or write other allocated objects. - /// - /// In other words, `let z = x.wrapping_offset((y as isize) - (x as isize))` does *not* make `z` - /// the same as `y` even if we assume `T` has size `1` and there is no overflow: `z` is still - /// attached to the object `x` is attached to, and dereferencing it is Undefined Behavior unless - /// `x` and `y` point into the same allocated object. - /// - /// Compared to [`offset`], this method basically delays the requirement of staying within the - /// same allocated object: [`offset`] is immediate Undefined Behavior when crossing object - /// boundaries; `wrapping_offset` produces a pointer but still leads to Undefined Behavior if a - /// pointer is dereferenced when it is out-of-bounds of the object it is attached to. [`offset`] - /// can be optimized better and is thus preferable in performance-sensitive code. - /// - /// The delayed check only considers the value of the pointer that was dereferenced, not the - /// intermediate values used during the computation of the final result. For example, - /// `x.wrapping_offset(o).wrapping_offset(o.wrapping_neg())` is always the same as `x`. In other - /// words, leaving the allocated object and then re-entering it later is permitted. - /// - /// [`offset`]: #method.offset - /// [allocated object]: crate::ptr#allocated-object - /// - /// # Examples - /// - /// ``` - /// // Iterate using a raw pointer in increments of two elements - /// let data = [1u8, 2, 3, 4, 5]; - /// let mut ptr: *const u8 = data.as_ptr(); - /// let step = 2; - /// let end_rounded_up = ptr.wrapping_offset(6); - /// - /// // This loop prints "1, 3, 5, " - /// while ptr != end_rounded_up { - /// unsafe { - /// print!("{}, ", *ptr); - /// } - /// ptr = ptr.wrapping_offset(step); - /// } - /// ``` - #[stable(feature = "ptr_wrapping_offset", since = "1.16.0")] - #[must_use = "returns a new pointer rather than modifying its argument"] - #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")] - #[inline(always)] - pub const fn wrapping_offset(self, count: isize) -> *const T - where - T: Sized, - { - // SAFETY: the `arith_offset` intrinsic has no prerequisites to be called. - unsafe { intrinsics::arith_offset(self, count) } - } - - /// Calculates the offset from a pointer in bytes using wrapping arithmetic. - /// - /// `count` is in units of **bytes**. - /// - /// This is purely a convenience for casting to a `u8` pointer and - /// using [wrapping_offset][pointer::wrapping_offset] on it. See that method - /// for documentation. - /// - /// For non-`Sized` pointees this operation changes only the data pointer, - /// leaving the metadata untouched. - #[must_use] - #[inline(always)] - #[stable(feature = "pointer_byte_offsets", since = "1.75.0")] - #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")] - #[rustc_allow_const_fn_unstable(set_ptr_value)] - pub const fn wrapping_byte_offset(self, count: isize) -> Self { - self.cast::().wrapping_offset(count).with_metadata_of(self) - } - - /// Masks out bits of the pointer according to a mask. - /// - /// This is convenience for `ptr.map_addr(|a| a & mask)`. - /// - /// For non-`Sized` pointees this operation changes only the data pointer, - /// leaving the metadata untouched. - /// - /// ## Examples - /// - /// ``` - /// #![feature(ptr_mask, strict_provenance)] - /// let v = 17_u32; - /// let ptr: *const u32 = &v; - /// - /// // `u32` is 4 bytes aligned, - /// // which means that lower 2 bits are always 0. - /// let tag_mask = 0b11; - /// let ptr_mask = !tag_mask; - /// - /// // We can store something in these lower bits - /// let tagged_ptr = ptr.map_addr(|a| a | 0b10); - /// - /// // Get the "tag" back - /// let tag = tagged_ptr.addr() & tag_mask; - /// assert_eq!(tag, 0b10); - /// - /// // Note that `tagged_ptr` is unaligned, it's UB to read from it. - /// // To get original pointer `mask` can be used: - /// let masked_ptr = tagged_ptr.mask(ptr_mask); - /// assert_eq!(unsafe { *masked_ptr }, 17); - /// ``` - #[unstable(feature = "ptr_mask", issue = "98290")] - #[must_use = "returns a new pointer rather than modifying its argument"] - #[inline(always)] - pub fn mask(self, mask: usize) -> *const T { - intrinsics::ptr_mask(self.cast::<()>(), mask).with_metadata_of(self) - } - - /// Calculates the distance between two pointers. The returned value is in - /// units of T: the distance in bytes divided by `mem::size_of::()`. - /// - /// This is equivalent to `(self as isize - origin as isize) / (mem::size_of::() as isize)`, - /// except that it has a lot more opportunities for UB, in exchange for the compiler - /// better understanding what you are doing. - /// - /// The primary motivation of this method is for computing the `len` of an array/slice - /// of `T` that you are currently representing as a "start" and "end" pointer - /// (and "end" is "one past the end" of the array). - /// In that case, `end.offset_from(start)` gets you the length of the array. - /// - /// All of the following safety requirements are trivially satisfied for this usecase. - /// - /// [`offset`]: #method.offset - /// - /// # Safety - /// - /// If any of the following conditions are violated, the result is Undefined - /// Behavior: - /// - /// * `self` and `origin` must either - /// - /// * both be *derived from* a pointer to the same [allocated object], and the memory range between - /// the two pointers must be either empty or in bounds of that object. (See below for an example.) - /// * or both be derived from an integer literal/constant, and point to the same address. - /// - /// * The distance between the pointers, in bytes, must be an exact multiple - /// of the size of `T`. - /// - /// * The distance between the pointers, **in bytes**, cannot overflow an `isize`. - /// - /// * The distance being in bounds cannot rely on "wrapping around" the address space. - /// - /// Rust types are never larger than `isize::MAX` and Rust allocations never wrap around the - /// address space, so two pointers within some value of any Rust type `T` will always satisfy - /// the last two conditions. The standard library also generally ensures that allocations - /// never reach a size where an offset is a concern. For instance, `Vec` and `Box` ensure they - /// never allocate more than `isize::MAX` bytes, so `ptr_into_vec.offset_from(vec.as_ptr())` - /// always satisfies the last two conditions. - /// - /// Most platforms fundamentally can't even construct such a large allocation. - /// For instance, no known 64-bit platform can ever serve a request - /// for 263 bytes due to page-table limitations or splitting the address space. - /// However, some 32-bit and 16-bit platforms may successfully serve a request for - /// more than `isize::MAX` bytes with things like Physical Address - /// Extension. As such, memory acquired directly from allocators or memory - /// mapped files *may* be too large to handle with this function. - /// (Note that [`offset`] and [`add`] also have a similar limitation and hence cannot be used on - /// such large allocations either.) - /// - /// The requirement for pointers to be derived from the same allocated object is primarily - /// needed for `const`-compatibility: the distance between pointers into *different* allocated - /// objects is not known at compile-time. However, the requirement also exists at - /// runtime and may be exploited by optimizations. If you wish to compute the difference between - /// pointers that are not guaranteed to be from the same allocation, use `(self as isize - - /// origin as isize) / mem::size_of::()`. - // FIXME: recommend `addr()` instead of `as usize` once that is stable. - /// - /// [`add`]: #method.add - /// [allocated object]: crate::ptr#allocated-object - /// - /// # Panics - /// - /// This function panics if `T` is a Zero-Sized Type ("ZST"). - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let a = [0; 5]; - /// let ptr1: *const i32 = &a[1]; - /// let ptr2: *const i32 = &a[3]; - /// unsafe { - /// assert_eq!(ptr2.offset_from(ptr1), 2); - /// assert_eq!(ptr1.offset_from(ptr2), -2); - /// assert_eq!(ptr1.offset(2), ptr2); - /// assert_eq!(ptr2.offset(-2), ptr1); - /// } - /// ``` - /// - /// *Incorrect* usage: - /// - /// ```rust,no_run - /// let ptr1 = Box::into_raw(Box::new(0u8)) as *const u8; - /// let ptr2 = Box::into_raw(Box::new(1u8)) as *const u8; - /// let diff = (ptr2 as isize).wrapping_sub(ptr1 as isize); - /// // Make ptr2_other an "alias" of ptr2, but derived from ptr1. - /// let ptr2_other = (ptr1 as *const u8).wrapping_offset(diff); - /// assert_eq!(ptr2 as usize, ptr2_other as usize); - /// // Since ptr2_other and ptr2 are derived from pointers to different objects, - /// // computing their offset is undefined behavior, even though - /// // they point to the same address! - /// unsafe { - /// let zero = ptr2_other.offset_from(ptr2); // Undefined Behavior - /// } - /// ``` - #[stable(feature = "ptr_offset_from", since = "1.47.0")] - #[rustc_const_stable(feature = "const_ptr_offset_from", since = "1.65.0")] - #[inline] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn offset_from(self, origin: *const T) -> isize - where - T: Sized, - { - let pointee_size = mem::size_of::(); - assert!(0 < pointee_size && pointee_size <= isize::MAX as usize); - // SAFETY: the caller must uphold the safety contract for `ptr_offset_from`. - unsafe { intrinsics::ptr_offset_from(self, origin) } - } - - /// Calculates the distance between two pointers. The returned value is in - /// units of **bytes**. - /// - /// This is purely a convenience for casting to a `u8` pointer and - /// using [`offset_from`][pointer::offset_from] on it. See that method for - /// documentation and safety requirements. - /// - /// For non-`Sized` pointees this operation considers only the data pointers, - /// ignoring the metadata. - #[inline(always)] - #[stable(feature = "pointer_byte_offsets", since = "1.75.0")] - #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")] - #[rustc_allow_const_fn_unstable(set_ptr_value)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn byte_offset_from(self, origin: *const U) -> isize { - // SAFETY: the caller must uphold the safety contract for `offset_from`. - unsafe { self.cast::().offset_from(origin.cast::()) } - } - - /// Calculates the distance between two pointers, *where it's known that - /// `self` is equal to or greater than `origin`*. The returned value is in - /// units of T: the distance in bytes is divided by `mem::size_of::()`. - /// - /// This computes the same value that [`offset_from`](#method.offset_from) - /// would compute, but with the added precondition that the offset is - /// guaranteed to be non-negative. This method is equivalent to - /// `usize::try_from(self.offset_from(origin)).unwrap_unchecked()`, - /// but it provides slightly more information to the optimizer, which can - /// sometimes allow it to optimize slightly better with some backends. - /// - /// This method can be though of as recovering the `count` that was passed - /// to [`add`](#method.add) (or, with the parameters in the other order, - /// to [`sub`](#method.sub)). The following are all equivalent, assuming - /// that their safety preconditions are met: - /// ```rust - /// # #![feature(ptr_sub_ptr)] - /// # unsafe fn blah(ptr: *const i32, origin: *const i32, count: usize) -> bool { - /// ptr.sub_ptr(origin) == count - /// # && - /// origin.add(count) == ptr - /// # && - /// ptr.sub(count) == origin - /// # } - /// ``` - /// - /// # Safety - /// - /// - The distance between the pointers must be non-negative (`self >= origin`) - /// - /// - *All* the safety conditions of [`offset_from`](#method.offset_from) - /// apply to this method as well; see it for the full details. - /// - /// Importantly, despite the return type of this method being able to represent - /// a larger offset, it's still *not permitted* to pass pointers which differ - /// by more than `isize::MAX` *bytes*. As such, the result of this method will - /// always be less than or equal to `isize::MAX as usize`. - /// - /// # Panics - /// - /// This function panics if `T` is a Zero-Sized Type ("ZST"). - /// - /// # Examples - /// - /// ``` - /// #![feature(ptr_sub_ptr)] - /// - /// let a = [0; 5]; - /// let ptr1: *const i32 = &a[1]; - /// let ptr2: *const i32 = &a[3]; - /// unsafe { - /// assert_eq!(ptr2.sub_ptr(ptr1), 2); - /// assert_eq!(ptr1.add(2), ptr2); - /// assert_eq!(ptr2.sub(2), ptr1); - /// assert_eq!(ptr2.sub_ptr(ptr2), 0); - /// } - /// - /// // This would be incorrect, as the pointers are not correctly ordered: - /// // ptr1.sub_ptr(ptr2) - /// ``` - #[unstable(feature = "ptr_sub_ptr", issue = "95892")] - #[rustc_const_unstable(feature = "const_ptr_sub_ptr", issue = "95892")] - #[inline] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn sub_ptr(self, origin: *const T) -> usize - where - T: Sized, - { - const fn runtime_ptr_ge(this: *const (), origin: *const ()) -> bool { - fn runtime(this: *const (), origin: *const ()) -> bool { - this >= origin - } - const fn comptime(_: *const (), _: *const ()) -> bool { - true - } - - #[allow(unused_unsafe)] - intrinsics::const_eval_select((this, origin), comptime, runtime) - } - - ub_checks::assert_unsafe_precondition!( - check_language_ub, - "ptr::sub_ptr requires `self >= origin`", - ( - this: *const () = self as *const (), - origin: *const () = origin as *const (), - ) => runtime_ptr_ge(this, origin) - ); - - let pointee_size = mem::size_of::(); - assert!(0 < pointee_size && pointee_size <= isize::MAX as usize); - // SAFETY: the caller must uphold the safety contract for `ptr_offset_from_unsigned`. - unsafe { intrinsics::ptr_offset_from_unsigned(self, origin) } - } - - /// Returns whether two pointers are guaranteed to be equal. - /// - /// At runtime this function behaves like `Some(self == other)`. - /// However, in some contexts (e.g., compile-time evaluation), - /// it is not always possible to determine equality of two pointers, so this function may - /// spuriously return `None` for pointers that later actually turn out to have its equality known. - /// But when it returns `Some`, the pointers' equality is guaranteed to be known. - /// - /// The return value may change from `Some` to `None` and vice versa depending on the compiler - /// version and unsafe code must not - /// rely on the result of this function for soundness. It is suggested to only use this function - /// for performance optimizations where spurious `None` return values by this function do not - /// affect the outcome, but just the performance. - /// The consequences of using this method to make runtime and compile-time code behave - /// differently have not been explored. This method should not be used to introduce such - /// differences, and it should also not be stabilized before we have a better understanding - /// of this issue. - #[unstable(feature = "const_raw_ptr_comparison", issue = "53020")] - #[rustc_const_unstable(feature = "const_raw_ptr_comparison", issue = "53020")] - #[inline] - pub const fn guaranteed_eq(self, other: *const T) -> Option - where - T: Sized, - { - match intrinsics::ptr_guaranteed_cmp(self, other) { - 2 => None, - other => Some(other == 1), - } - } - - /// Returns whether two pointers are guaranteed to be inequal. - /// - /// At runtime this function behaves like `Some(self != other)`. - /// However, in some contexts (e.g., compile-time evaluation), - /// it is not always possible to determine inequality of two pointers, so this function may - /// spuriously return `None` for pointers that later actually turn out to have its inequality known. - /// But when it returns `Some`, the pointers' inequality is guaranteed to be known. - /// - /// The return value may change from `Some` to `None` and vice versa depending on the compiler - /// version and unsafe code must not - /// rely on the result of this function for soundness. It is suggested to only use this function - /// for performance optimizations where spurious `None` return values by this function do not - /// affect the outcome, but just the performance. - /// The consequences of using this method to make runtime and compile-time code behave - /// differently have not been explored. This method should not be used to introduce such - /// differences, and it should also not be stabilized before we have a better understanding - /// of this issue. - #[unstable(feature = "const_raw_ptr_comparison", issue = "53020")] - #[rustc_const_unstable(feature = "const_raw_ptr_comparison", issue = "53020")] - #[inline] - pub const fn guaranteed_ne(self, other: *const T) -> Option - where - T: Sized, - { - match self.guaranteed_eq(other) { - None => None, - Some(eq) => Some(!eq), - } - } - - /// Calculates the offset from a pointer (convenience for `.offset(count as isize)`). - /// - /// `count` is in units of T; e.g., a `count` of 3 represents a pointer - /// offset of `3 * size_of::()` bytes. - /// - /// # Safety - /// - /// If any of the following conditions are violated, the result is Undefined - /// Behavior: - /// - /// * If the computed offset, **in bytes**, is non-zero, then both the starting and resulting - /// pointer must be either in bounds or at the end of the same [allocated object]. - /// (If it is zero, then the function is always well-defined.) - /// - /// * The computed offset, **in bytes**, cannot overflow an `isize`. - /// - /// * The offset being in bounds cannot rely on "wrapping around" the address - /// space. That is, the infinite-precision sum must fit in a `usize`. - /// - /// The compiler and standard library generally tries to ensure allocations - /// never reach a size where an offset is a concern. For instance, `Vec` - /// and `Box` ensure they never allocate more than `isize::MAX` bytes, so - /// `vec.as_ptr().add(vec.len())` is always safe. - /// - /// Most platforms fundamentally can't even construct such an allocation. - /// For instance, no known 64-bit platform can ever serve a request - /// for 263 bytes due to page-table limitations or splitting the address space. - /// However, some 32-bit and 16-bit platforms may successfully serve a request for - /// more than `isize::MAX` bytes with things like Physical Address - /// Extension. As such, memory acquired directly from allocators or memory - /// mapped files *may* be too large to handle with this function. - /// - /// Consider using [`wrapping_add`] instead if these constraints are - /// difficult to satisfy. The only advantage of this method is that it - /// enables more aggressive compiler optimizations. - /// - /// [`wrapping_add`]: #method.wrapping_add - /// [allocated object]: crate::ptr#allocated-object - /// - /// # Examples - /// - /// ``` - /// let s: &str = "123"; - /// let ptr: *const u8 = s.as_ptr(); - /// - /// unsafe { - /// println!("{}", *ptr.add(1) as char); - /// println!("{}", *ptr.add(2) as char); - /// } - /// ``` - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[must_use = "returns a new pointer rather than modifying its argument"] - #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn add(self, count: usize) -> Self - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `offset`. - unsafe { intrinsics::offset(self, count) } - } - - /// Calculates the offset from a pointer in bytes (convenience for `.byte_offset(count as isize)`). - /// - /// `count` is in units of bytes. - /// - /// This is purely a convenience for casting to a `u8` pointer and - /// using [add][pointer::add] on it. See that method for documentation - /// and safety requirements. - /// - /// For non-`Sized` pointees this operation changes only the data pointer, - /// leaving the metadata untouched. - #[must_use] - #[inline(always)] - #[stable(feature = "pointer_byte_offsets", since = "1.75.0")] - #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")] - #[rustc_allow_const_fn_unstable(set_ptr_value)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn byte_add(self, count: usize) -> Self { - // SAFETY: the caller must uphold the safety contract for `add`. - unsafe { self.cast::().add(count).with_metadata_of(self) } - } - - /// Calculates the offset from a pointer (convenience for - /// `.offset((count as isize).wrapping_neg())`). - /// - /// `count` is in units of T; e.g., a `count` of 3 represents a pointer - /// offset of `3 * size_of::()` bytes. - /// - /// # Safety - /// - /// If any of the following conditions are violated, the result is Undefined - /// Behavior: - /// - /// * If the computed offset, **in bytes**, is non-zero, then both the starting and resulting - /// pointer must be either in bounds or at the end of the same [allocated object]. - /// (If it is zero, then the function is always well-defined.) - /// - /// * The computed offset cannot exceed `isize::MAX` **bytes**. - /// - /// * The offset being in bounds cannot rely on "wrapping around" the address - /// space. That is, the infinite-precision sum must fit in a usize. - /// - /// The compiler and standard library generally tries to ensure allocations - /// never reach a size where an offset is a concern. For instance, `Vec` - /// and `Box` ensure they never allocate more than `isize::MAX` bytes, so - /// `vec.as_ptr().add(vec.len()).sub(vec.len())` is always safe. - /// - /// Most platforms fundamentally can't even construct such an allocation. - /// For instance, no known 64-bit platform can ever serve a request - /// for 263 bytes due to page-table limitations or splitting the address space. - /// However, some 32-bit and 16-bit platforms may successfully serve a request for - /// more than `isize::MAX` bytes with things like Physical Address - /// Extension. As such, memory acquired directly from allocators or memory - /// mapped files *may* be too large to handle with this function. - /// - /// Consider using [`wrapping_sub`] instead if these constraints are - /// difficult to satisfy. The only advantage of this method is that it - /// enables more aggressive compiler optimizations. - /// - /// [`wrapping_sub`]: #method.wrapping_sub - /// [allocated object]: crate::ptr#allocated-object - /// - /// # Examples - /// - /// ``` - /// let s: &str = "123"; - /// - /// unsafe { - /// let end: *const u8 = s.as_ptr().add(3); - /// println!("{}", *end.sub(1) as char); - /// println!("{}", *end.sub(2) as char); - /// } - /// ``` - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[must_use = "returns a new pointer rather than modifying its argument"] - #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn sub(self, count: usize) -> Self - where - T: Sized, - { - if T::IS_ZST { - // Pointer arithmetic does nothing when the pointee is a ZST. - self - } else { - // SAFETY: the caller must uphold the safety contract for `offset`. - // Because the pointee is *not* a ZST, that means that `count` is - // at most `isize::MAX`, and thus the negation cannot overflow. - unsafe { self.offset(intrinsics::unchecked_sub(0, count as isize)) } - } - } - - /// Calculates the offset from a pointer in bytes (convenience for - /// `.byte_offset((count as isize).wrapping_neg())`). - /// - /// `count` is in units of bytes. - /// - /// This is purely a convenience for casting to a `u8` pointer and - /// using [sub][pointer::sub] on it. See that method for documentation - /// and safety requirements. - /// - /// For non-`Sized` pointees this operation changes only the data pointer, - /// leaving the metadata untouched. - #[must_use] - #[inline(always)] - #[stable(feature = "pointer_byte_offsets", since = "1.75.0")] - #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")] - #[rustc_allow_const_fn_unstable(set_ptr_value)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn byte_sub(self, count: usize) -> Self { - // SAFETY: the caller must uphold the safety contract for `sub`. - unsafe { self.cast::().sub(count).with_metadata_of(self) } - } - - /// Calculates the offset from a pointer using wrapping arithmetic. - /// (convenience for `.wrapping_offset(count as isize)`) - /// - /// `count` is in units of T; e.g., a `count` of 3 represents a pointer - /// offset of `3 * size_of::()` bytes. - /// - /// # Safety - /// - /// This operation itself is always safe, but using the resulting pointer is not. - /// - /// The resulting pointer "remembers" the [allocated object] that `self` points to; it must not - /// be used to read or write other allocated objects. - /// - /// In other words, `let z = x.wrapping_add((y as usize) - (x as usize))` does *not* make `z` - /// the same as `y` even if we assume `T` has size `1` and there is no overflow: `z` is still - /// attached to the object `x` is attached to, and dereferencing it is Undefined Behavior unless - /// `x` and `y` point into the same allocated object. - /// - /// Compared to [`add`], this method basically delays the requirement of staying within the - /// same allocated object: [`add`] is immediate Undefined Behavior when crossing object - /// boundaries; `wrapping_add` produces a pointer but still leads to Undefined Behavior if a - /// pointer is dereferenced when it is out-of-bounds of the object it is attached to. [`add`] - /// can be optimized better and is thus preferable in performance-sensitive code. - /// - /// The delayed check only considers the value of the pointer that was dereferenced, not the - /// intermediate values used during the computation of the final result. For example, - /// `x.wrapping_add(o).wrapping_sub(o)` is always the same as `x`. In other words, leaving the - /// allocated object and then re-entering it later is permitted. - /// - /// [`add`]: #method.add - /// [allocated object]: crate::ptr#allocated-object - /// - /// # Examples - /// - /// ``` - /// // Iterate using a raw pointer in increments of two elements - /// let data = [1u8, 2, 3, 4, 5]; - /// let mut ptr: *const u8 = data.as_ptr(); - /// let step = 2; - /// let end_rounded_up = ptr.wrapping_add(6); - /// - /// // This loop prints "1, 3, 5, " - /// while ptr != end_rounded_up { - /// unsafe { - /// print!("{}, ", *ptr); - /// } - /// ptr = ptr.wrapping_add(step); - /// } - /// ``` - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[must_use = "returns a new pointer rather than modifying its argument"] - #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")] - #[inline(always)] - pub const fn wrapping_add(self, count: usize) -> Self - where - T: Sized, - { - self.wrapping_offset(count as isize) - } - - /// Calculates the offset from a pointer in bytes using wrapping arithmetic. - /// (convenience for `.wrapping_byte_offset(count as isize)`) - /// - /// `count` is in units of bytes. - /// - /// This is purely a convenience for casting to a `u8` pointer and - /// using [wrapping_add][pointer::wrapping_add] on it. See that method for documentation. - /// - /// For non-`Sized` pointees this operation changes only the data pointer, - /// leaving the metadata untouched. - #[must_use] - #[inline(always)] - #[stable(feature = "pointer_byte_offsets", since = "1.75.0")] - #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")] - #[rustc_allow_const_fn_unstable(set_ptr_value)] - pub const fn wrapping_byte_add(self, count: usize) -> Self { - self.cast::().wrapping_add(count).with_metadata_of(self) - } - - /// Calculates the offset from a pointer using wrapping arithmetic. - /// (convenience for `.wrapping_offset((count as isize).wrapping_neg())`) - /// - /// `count` is in units of T; e.g., a `count` of 3 represents a pointer - /// offset of `3 * size_of::()` bytes. - /// - /// # Safety - /// - /// This operation itself is always safe, but using the resulting pointer is not. - /// - /// The resulting pointer "remembers" the [allocated object] that `self` points to; it must not - /// be used to read or write other allocated objects. - /// - /// In other words, `let z = x.wrapping_sub((x as usize) - (y as usize))` does *not* make `z` - /// the same as `y` even if we assume `T` has size `1` and there is no overflow: `z` is still - /// attached to the object `x` is attached to, and dereferencing it is Undefined Behavior unless - /// `x` and `y` point into the same allocated object. - /// - /// Compared to [`sub`], this method basically delays the requirement of staying within the - /// same allocated object: [`sub`] is immediate Undefined Behavior when crossing object - /// boundaries; `wrapping_sub` produces a pointer but still leads to Undefined Behavior if a - /// pointer is dereferenced when it is out-of-bounds of the object it is attached to. [`sub`] - /// can be optimized better and is thus preferable in performance-sensitive code. - /// - /// The delayed check only considers the value of the pointer that was dereferenced, not the - /// intermediate values used during the computation of the final result. For example, - /// `x.wrapping_add(o).wrapping_sub(o)` is always the same as `x`. In other words, leaving the - /// allocated object and then re-entering it later is permitted. - /// - /// [`sub`]: #method.sub - /// [allocated object]: crate::ptr#allocated-object - /// - /// # Examples - /// - /// ``` - /// // Iterate using a raw pointer in increments of two elements (backwards) - /// let data = [1u8, 2, 3, 4, 5]; - /// let mut ptr: *const u8 = data.as_ptr(); - /// let start_rounded_down = ptr.wrapping_sub(2); - /// ptr = ptr.wrapping_add(4); - /// let step = 2; - /// // This loop prints "5, 3, 1, " - /// while ptr != start_rounded_down { - /// unsafe { - /// print!("{}, ", *ptr); - /// } - /// ptr = ptr.wrapping_sub(step); - /// } - /// ``` - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[must_use = "returns a new pointer rather than modifying its argument"] - #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")] - #[inline(always)] - pub const fn wrapping_sub(self, count: usize) -> Self - where - T: Sized, - { - self.wrapping_offset((count as isize).wrapping_neg()) - } - - /// Calculates the offset from a pointer in bytes using wrapping arithmetic. - /// (convenience for `.wrapping_offset((count as isize).wrapping_neg())`) - /// - /// `count` is in units of bytes. - /// - /// This is purely a convenience for casting to a `u8` pointer and - /// using [wrapping_sub][pointer::wrapping_sub] on it. See that method for documentation. - /// - /// For non-`Sized` pointees this operation changes only the data pointer, - /// leaving the metadata untouched. - #[must_use] - #[inline(always)] - #[stable(feature = "pointer_byte_offsets", since = "1.75.0")] - #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")] - #[rustc_allow_const_fn_unstable(set_ptr_value)] - pub const fn wrapping_byte_sub(self, count: usize) -> Self { - self.cast::().wrapping_sub(count).with_metadata_of(self) - } - - /// Reads the value from `self` without moving it. This leaves the - /// memory in `self` unchanged. - /// - /// See [`ptr::read`] for safety concerns and examples. - /// - /// [`ptr::read`]: crate::ptr::read() - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[rustc_const_stable(feature = "const_ptr_read", since = "1.71.0")] - #[inline] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn read(self) -> T - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `read`. - unsafe { read(self) } - } - - /// Performs a volatile read of the value from `self` without moving it. This - /// leaves the memory in `self` unchanged. - /// - /// Volatile operations are intended to act on I/O memory, and are guaranteed - /// to not be elided or reordered by the compiler across other volatile - /// operations. - /// - /// See [`ptr::read_volatile`] for safety concerns and examples. - /// - /// [`ptr::read_volatile`]: crate::ptr::read_volatile() - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[inline] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub unsafe fn read_volatile(self) -> T - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `read_volatile`. - unsafe { read_volatile(self) } - } - - /// Reads the value from `self` without moving it. This leaves the - /// memory in `self` unchanged. - /// - /// Unlike `read`, the pointer may be unaligned. - /// - /// See [`ptr::read_unaligned`] for safety concerns and examples. - /// - /// [`ptr::read_unaligned`]: crate::ptr::read_unaligned() - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[rustc_const_stable(feature = "const_ptr_read", since = "1.71.0")] - #[inline] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn read_unaligned(self) -> T - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `read_unaligned`. - unsafe { read_unaligned(self) } - } - - /// Copies `count * size_of` bytes from `self` to `dest`. The source - /// and destination may overlap. - /// - /// NOTE: this has the *same* argument order as [`ptr::copy`]. - /// - /// See [`ptr::copy`] for safety concerns and examples. - /// - /// [`ptr::copy`]: crate::ptr::copy() - #[rustc_const_unstable(feature = "const_intrinsic_copy", issue = "80697")] - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[inline] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn copy_to(self, dest: *mut T, count: usize) - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `copy`. - unsafe { copy(self, dest, count) } - } - - /// Copies `count * size_of` bytes from `self` to `dest`. The source - /// and destination may *not* overlap. - /// - /// NOTE: this has the *same* argument order as [`ptr::copy_nonoverlapping`]. - /// - /// See [`ptr::copy_nonoverlapping`] for safety concerns and examples. - /// - /// [`ptr::copy_nonoverlapping`]: crate::ptr::copy_nonoverlapping() - #[rustc_const_unstable(feature = "const_intrinsic_copy", issue = "80697")] - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[inline] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn copy_to_nonoverlapping(self, dest: *mut T, count: usize) - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `copy_nonoverlapping`. - unsafe { copy_nonoverlapping(self, dest, count) } - } - - /// Computes the offset that needs to be applied to the pointer in order to make it aligned to - /// `align`. - /// - /// If it is not possible to align the pointer, the implementation returns - /// `usize::MAX`. - /// - /// The offset is expressed in number of `T` elements, and not bytes. The value returned can be - /// used with the `wrapping_add` method. - /// - /// There are no guarantees whatsoever that offsetting the pointer will not overflow or go - /// beyond the allocation that the pointer points into. It is up to the caller to ensure that - /// the returned offset is correct in all terms other than alignment. - /// - /// When this is called during compile-time evaluation (which is unstable), the implementation - /// may return `usize::MAX` in cases where that can never happen at runtime. This is because the - /// actual alignment of pointers is not known yet during compile-time, so an offset with - /// guaranteed alignment can sometimes not be computed. For example, a buffer declared as `[u8; - /// N]` might be allocated at an odd or an even address, but at compile-time this is not yet - /// known, so the execution has to be correct for either choice. It is therefore impossible to - /// find an offset that is guaranteed to be 2-aligned. (This behavior is subject to change, as usual - /// for unstable APIs.) - /// - /// # Panics - /// - /// The function panics if `align` is not a power-of-two. - /// - /// # Examples - /// - /// Accessing adjacent `u8` as `u16` - /// - /// ``` - /// use std::mem::align_of; - /// - /// # unsafe { - /// let x = [5_u8, 6, 7, 8, 9]; - /// let ptr = x.as_ptr(); - /// let offset = ptr.align_offset(align_of::()); - /// - /// if offset < x.len() - 1 { - /// let u16_ptr = ptr.add(offset).cast::(); - /// assert!(*u16_ptr == u16::from_ne_bytes([5, 6]) || *u16_ptr == u16::from_ne_bytes([6, 7])); - /// } else { - /// // while the pointer can be aligned via `offset`, it would point - /// // outside the allocation - /// } - /// # } - /// ``` - #[must_use] - #[inline] - #[stable(feature = "align_offset", since = "1.36.0")] - #[rustc_const_unstable(feature = "const_align_offset", issue = "90962")] - pub const fn align_offset(self, align: usize) -> usize - where - T: Sized, - { - if !align.is_power_of_two() { - panic!("align_offset: align is not a power-of-two"); - } - - // SAFETY: `align` has been checked to be a power of 2 above - let ret = unsafe { align_offset(self, align) }; - - // Inform Miri that we want to consider the resulting pointer to be suitably aligned. - #[cfg(miri)] - if ret != usize::MAX { - intrinsics::miri_promise_symbolic_alignment(self.wrapping_add(ret).cast(), align); - } - - ret - } - - /// Returns whether the pointer is properly aligned for `T`. - /// - /// # Examples - /// - /// ``` - /// // On some platforms, the alignment of i32 is less than 4. - /// #[repr(align(4))] - /// struct AlignedI32(i32); - /// - /// let data = AlignedI32(42); - /// let ptr = &data as *const AlignedI32; - /// - /// assert!(ptr.is_aligned()); - /// assert!(!ptr.wrapping_byte_add(1).is_aligned()); - /// ``` - /// - /// # At compiletime - /// **Note: Alignment at compiletime is experimental and subject to change. See the - /// [tracking issue] for details.** - /// - /// At compiletime, the compiler may not know where a value will end up in memory. - /// Calling this function on a pointer created from a reference at compiletime will only - /// return `true` if the pointer is guaranteed to be aligned. This means that the pointer - /// is never aligned if cast to a type with a stricter alignment than the reference's - /// underlying allocation. - /// - /// ``` - /// #![feature(const_pointer_is_aligned)] - /// - /// // On some platforms, the alignment of primitives is less than their size. - /// #[repr(align(4))] - /// struct AlignedI32(i32); - /// #[repr(align(8))] - /// struct AlignedI64(i64); - /// - /// const _: () = { - /// let data = AlignedI32(42); - /// let ptr = &data as *const AlignedI32; - /// assert!(ptr.is_aligned()); - /// - /// // At runtime either `ptr1` or `ptr2` would be aligned, but at compiletime neither is aligned. - /// let ptr1 = ptr.cast::(); - /// let ptr2 = ptr.wrapping_add(1).cast::(); - /// assert!(!ptr1.is_aligned()); - /// assert!(!ptr2.is_aligned()); - /// }; - /// ``` - /// - /// Due to this behavior, it is possible that a runtime pointer derived from a compiletime - /// pointer is aligned, even if the compiletime pointer wasn't aligned. - /// - /// ``` - /// #![feature(const_pointer_is_aligned)] - /// - /// // On some platforms, the alignment of primitives is less than their size. - /// #[repr(align(4))] - /// struct AlignedI32(i32); - /// #[repr(align(8))] - /// struct AlignedI64(i64); - /// - /// // At compiletime, neither `COMPTIME_PTR` nor `COMPTIME_PTR + 1` is aligned. - /// const COMPTIME_PTR: *const AlignedI32 = &AlignedI32(42); - /// const _: () = assert!(!COMPTIME_PTR.cast::().is_aligned()); - /// const _: () = assert!(!COMPTIME_PTR.wrapping_add(1).cast::().is_aligned()); - /// - /// // At runtime, either `runtime_ptr` or `runtime_ptr + 1` is aligned. - /// let runtime_ptr = COMPTIME_PTR; - /// assert_ne!( - /// runtime_ptr.cast::().is_aligned(), - /// runtime_ptr.wrapping_add(1).cast::().is_aligned(), - /// ); - /// ``` - /// - /// If a pointer is created from a fixed address, this function behaves the same during - /// runtime and compiletime. - /// - /// ``` - /// #![feature(const_pointer_is_aligned)] - /// - /// // On some platforms, the alignment of primitives is less than their size. - /// #[repr(align(4))] - /// struct AlignedI32(i32); - /// #[repr(align(8))] - /// struct AlignedI64(i64); - /// - /// const _: () = { - /// let ptr = 40 as *const AlignedI32; - /// assert!(ptr.is_aligned()); - /// - /// // For pointers with a known address, runtime and compiletime behavior are identical. - /// let ptr1 = ptr.cast::(); - /// let ptr2 = ptr.wrapping_add(1).cast::(); - /// assert!(ptr1.is_aligned()); - /// assert!(!ptr2.is_aligned()); - /// }; - /// ``` - /// - /// [tracking issue]: https://github.com/rust-lang/rust/issues/104203 - #[must_use] - #[inline] - #[stable(feature = "pointer_is_aligned", since = "1.79.0")] - #[rustc_const_unstable(feature = "const_pointer_is_aligned", issue = "104203")] - pub const fn is_aligned(self) -> bool - where - T: Sized, - { - self.is_aligned_to(mem::align_of::()) - } - - /// Returns whether the pointer is aligned to `align`. - /// - /// For non-`Sized` pointees this operation considers only the data pointer, - /// ignoring the metadata. - /// - /// # Panics - /// - /// The function panics if `align` is not a power-of-two (this includes 0). - /// - /// # Examples - /// - /// ``` - /// #![feature(pointer_is_aligned_to)] - /// - /// // On some platforms, the alignment of i32 is less than 4. - /// #[repr(align(4))] - /// struct AlignedI32(i32); - /// - /// let data = AlignedI32(42); - /// let ptr = &data as *const AlignedI32; - /// - /// assert!(ptr.is_aligned_to(1)); - /// assert!(ptr.is_aligned_to(2)); - /// assert!(ptr.is_aligned_to(4)); - /// - /// assert!(ptr.wrapping_byte_add(2).is_aligned_to(2)); - /// assert!(!ptr.wrapping_byte_add(2).is_aligned_to(4)); - /// - /// assert_ne!(ptr.is_aligned_to(8), ptr.wrapping_add(1).is_aligned_to(8)); - /// ``` - /// - /// # At compiletime - /// **Note: Alignment at compiletime is experimental and subject to change. See the - /// [tracking issue] for details.** - /// - /// At compiletime, the compiler may not know where a value will end up in memory. - /// Calling this function on a pointer created from a reference at compiletime will only - /// return `true` if the pointer is guaranteed to be aligned. This means that the pointer - /// cannot be stricter aligned than the reference's underlying allocation. - /// - /// ``` - /// #![feature(pointer_is_aligned_to)] - /// #![feature(const_pointer_is_aligned)] - /// - /// // On some platforms, the alignment of i32 is less than 4. - /// #[repr(align(4))] - /// struct AlignedI32(i32); - /// - /// const _: () = { - /// let data = AlignedI32(42); - /// let ptr = &data as *const AlignedI32; - /// - /// assert!(ptr.is_aligned_to(1)); - /// assert!(ptr.is_aligned_to(2)); - /// assert!(ptr.is_aligned_to(4)); - /// - /// // At compiletime, we know for sure that the pointer isn't aligned to 8. - /// assert!(!ptr.is_aligned_to(8)); - /// assert!(!ptr.wrapping_add(1).is_aligned_to(8)); - /// }; - /// ``` - /// - /// Due to this behavior, it is possible that a runtime pointer derived from a compiletime - /// pointer is aligned, even if the compiletime pointer wasn't aligned. - /// - /// ``` - /// #![feature(pointer_is_aligned_to)] - /// #![feature(const_pointer_is_aligned)] - /// - /// // On some platforms, the alignment of i32 is less than 4. - /// #[repr(align(4))] - /// struct AlignedI32(i32); - /// - /// // At compiletime, neither `COMPTIME_PTR` nor `COMPTIME_PTR + 1` is aligned. - /// const COMPTIME_PTR: *const AlignedI32 = &AlignedI32(42); - /// const _: () = assert!(!COMPTIME_PTR.is_aligned_to(8)); - /// const _: () = assert!(!COMPTIME_PTR.wrapping_add(1).is_aligned_to(8)); - /// - /// // At runtime, either `runtime_ptr` or `runtime_ptr + 1` is aligned. - /// let runtime_ptr = COMPTIME_PTR; - /// assert_ne!( - /// runtime_ptr.is_aligned_to(8), - /// runtime_ptr.wrapping_add(1).is_aligned_to(8), - /// ); - /// ``` - /// - /// If a pointer is created from a fixed address, this function behaves the same during - /// runtime and compiletime. - /// - /// ``` - /// #![feature(pointer_is_aligned_to)] - /// #![feature(const_pointer_is_aligned)] - /// - /// const _: () = { - /// let ptr = 40 as *const u8; - /// assert!(ptr.is_aligned_to(1)); - /// assert!(ptr.is_aligned_to(2)); - /// assert!(ptr.is_aligned_to(4)); - /// assert!(ptr.is_aligned_to(8)); - /// assert!(!ptr.is_aligned_to(16)); - /// }; - /// ``` - /// - /// [tracking issue]: https://github.com/rust-lang/rust/issues/104203 - #[must_use] - #[inline] - #[unstable(feature = "pointer_is_aligned_to", issue = "96284")] - #[rustc_const_unstable(feature = "const_pointer_is_aligned", issue = "104203")] - pub const fn is_aligned_to(self, align: usize) -> bool { - if !align.is_power_of_two() { - panic!("is_aligned_to: align is not a power-of-two"); - } - - #[inline] - fn runtime_impl(ptr: *const (), align: usize) -> bool { - ptr.addr() & (align - 1) == 0 - } - - #[inline] - const fn const_impl(ptr: *const (), align: usize) -> bool { - // We can't use the address of `self` in a `const fn`, so we use `align_offset` instead. - ptr.align_offset(align) == 0 - } - - // The cast to `()` is used to - // 1. deal with fat pointers; and - // 2. ensure that `align_offset` (in `const_impl`) doesn't actually try to compute an offset. - const_eval_select((self.cast::<()>(), align), const_impl, runtime_impl) - } -} - -impl *const [T] { - /// Returns the length of a raw slice. - /// - /// The returned value is the number of **elements**, not the number of bytes. - /// - /// This function is safe, even when the raw slice cannot be cast to a slice - /// reference because the pointer is null or unaligned. - /// - /// # Examples - /// - /// ```rust - /// use std::ptr; - /// - /// let slice: *const [i8] = ptr::slice_from_raw_parts(ptr::null(), 3); - /// assert_eq!(slice.len(), 3); - /// ``` - #[inline] - #[stable(feature = "slice_ptr_len", since = "1.79.0")] - #[rustc_const_stable(feature = "const_slice_ptr_len", since = "1.79.0")] - #[rustc_allow_const_fn_unstable(ptr_metadata)] - pub const fn len(self) -> usize { - metadata(self) - } - - /// Returns `true` if the raw slice has a length of 0. - /// - /// # Examples - /// - /// ``` - /// use std::ptr; - /// - /// let slice: *const [i8] = ptr::slice_from_raw_parts(ptr::null(), 3); - /// assert!(!slice.is_empty()); - /// ``` - #[inline(always)] - #[stable(feature = "slice_ptr_len", since = "1.79.0")] - #[rustc_const_stable(feature = "const_slice_ptr_len", since = "1.79.0")] - pub const fn is_empty(self) -> bool { - self.len() == 0 - } - - /// Returns a raw pointer to the slice's buffer. - /// - /// This is equivalent to casting `self` to `*const T`, but more type-safe. - /// - /// # Examples - /// - /// ```rust - /// #![feature(slice_ptr_get)] - /// use std::ptr; - /// - /// let slice: *const [i8] = ptr::slice_from_raw_parts(ptr::null(), 3); - /// assert_eq!(slice.as_ptr(), ptr::null()); - /// ``` - #[inline] - #[unstable(feature = "slice_ptr_get", issue = "74265")] - #[rustc_const_unstable(feature = "slice_ptr_get", issue = "74265")] - pub const fn as_ptr(self) -> *const T { - self as *const T - } - - /// Returns a raw pointer to an element or subslice, without doing bounds - /// checking. - /// - /// Calling this method with an out-of-bounds index or when `self` is not dereferenceable - /// is *[undefined behavior]* even if the resulting pointer is not used. - /// - /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html - /// - /// # Examples - /// - /// ``` - /// #![feature(slice_ptr_get)] - /// - /// let x = &[1, 2, 4] as *const [i32]; - /// - /// unsafe { - /// assert_eq!(x.get_unchecked(1), x.as_ptr().add(1)); - /// } - /// ``` - #[unstable(feature = "slice_ptr_get", issue = "74265")] - #[inline] - pub unsafe fn get_unchecked(self, index: I) -> *const I::Output - where - I: SliceIndex<[T]>, - { - // SAFETY: the caller ensures that `self` is dereferenceable and `index` in-bounds. - unsafe { index.get_unchecked(self) } - } - - /// Returns `None` if the pointer is null, or else returns a shared slice to - /// the value wrapped in `Some`. In contrast to [`as_ref`], this does not require - /// that the value has to be initialized. - /// - /// [`as_ref`]: #method.as_ref - /// - /// # Safety - /// - /// When calling this method, you have to ensure that *either* the pointer is null *or* - /// all of the following is true: - /// - /// * The pointer must be [valid] for reads for `ptr.len() * mem::size_of::()` many bytes, - /// and it must be properly aligned. This means in particular: - /// - /// * The entire memory range of this slice must be contained within a single [allocated object]! - /// Slices can never span across multiple allocated objects. - /// - /// * The pointer must be aligned even for zero-length slices. One - /// reason for this is that enum layout optimizations may rely on references - /// (including slices of any length) being aligned and non-null to distinguish - /// them from other data. You can obtain a pointer that is usable as `data` - /// for zero-length slices using [`NonNull::dangling()`]. - /// - /// * The total size `ptr.len() * mem::size_of::()` of the slice must be no larger than `isize::MAX`. - /// See the safety documentation of [`pointer::offset`]. - /// - /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is - /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. - /// In particular, while this reference exists, the memory the pointer points to must - /// not get mutated (except inside `UnsafeCell`). - /// - /// This applies even if the result of this method is unused! - /// - /// See also [`slice::from_raw_parts`][]. - /// - /// [valid]: crate::ptr#safety - /// [allocated object]: crate::ptr#allocated-object - #[inline] - #[unstable(feature = "ptr_as_uninit", issue = "75402")] - #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")] - pub const unsafe fn as_uninit_slice<'a>(self) -> Option<&'a [MaybeUninit]> { - if self.is_null() { - None - } else { - // SAFETY: the caller must uphold the safety contract for `as_uninit_slice`. - Some(unsafe { slice::from_raw_parts(self as *const MaybeUninit, self.len()) }) - } - } -} - -impl *const [T; N] { - /// Returns a raw pointer to the array's buffer. - /// - /// This is equivalent to casting `self` to `*const T`, but more type-safe. - /// - /// # Examples - /// - /// ```rust - /// #![feature(array_ptr_get)] - /// use std::ptr; - /// - /// let arr: *const [i8; 3] = ptr::null(); - /// assert_eq!(arr.as_ptr(), ptr::null()); - /// ``` - #[inline] - #[unstable(feature = "array_ptr_get", issue = "119834")] - #[rustc_const_unstable(feature = "array_ptr_get", issue = "119834")] - pub const fn as_ptr(self) -> *const T { - self as *const T - } - - /// Returns a raw pointer to a slice containing the entire array. - /// - /// # Examples - /// - /// ``` - /// #![feature(array_ptr_get)] - /// - /// let arr: *const [i32; 3] = &[1, 2, 4] as *const [i32; 3]; - /// let slice: *const [i32] = arr.as_slice(); - /// assert_eq!(slice.len(), 3); - /// ``` - #[inline] - #[unstable(feature = "array_ptr_get", issue = "119834")] - #[rustc_const_unstable(feature = "array_ptr_get", issue = "119834")] - pub const fn as_slice(self) -> *const [T] { - self - } -} - -// Equality for pointers -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for *const T { - #[inline] - #[allow(ambiguous_wide_pointer_comparisons)] - fn eq(&self, other: &*const T) -> bool { - *self == *other - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Eq for *const T {} - -// Comparison for pointers -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for *const T { - #[inline] - #[allow(ambiguous_wide_pointer_comparisons)] - fn cmp(&self, other: &*const T) -> Ordering { - if self < other { - Less - } else if self == other { - Equal - } else { - Greater - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialOrd for *const T { - #[inline] - #[allow(ambiguous_wide_pointer_comparisons)] - fn partial_cmp(&self, other: &*const T) -> Option { - Some(self.cmp(other)) - } - - #[inline] - #[allow(ambiguous_wide_pointer_comparisons)] - fn lt(&self, other: &*const T) -> bool { - *self < *other - } - - #[inline] - #[allow(ambiguous_wide_pointer_comparisons)] - fn le(&self, other: &*const T) -> bool { - *self <= *other - } - - #[inline] - #[allow(ambiguous_wide_pointer_comparisons)] - fn gt(&self, other: &*const T) -> bool { - *self > *other - } - - #[inline] - #[allow(ambiguous_wide_pointer_comparisons)] - fn ge(&self, other: &*const T) -> bool { - *self >= *other - } -} diff --git a/library/core/src/ptr/metadata.rs b/library/core/src/ptr/metadata.rs deleted file mode 100644 index e501970b580de..0000000000000 --- a/library/core/src/ptr/metadata.rs +++ /dev/null @@ -1,286 +0,0 @@ -#![unstable(feature = "ptr_metadata", issue = "81513")] - -use crate::fmt; -use crate::hash::{Hash, Hasher}; -use crate::intrinsics::aggregate_raw_ptr; -use crate::marker::Freeze; - -/// Provides the pointer metadata type of any pointed-to type. -/// -/// # Pointer metadata -/// -/// Raw pointer types and reference types in Rust can be thought of as made of two parts: -/// a data pointer that contains the memory address of the value, and some metadata. -/// -/// For statically-sized types (that implement the `Sized` traits) -/// as well as for `extern` types, -/// pointers are said to be “thin”: metadata is zero-sized and its type is `()`. -/// -/// Pointers to [dynamically-sized types][dst] are said to be “wide” or “fat”, -/// they have non-zero-sized metadata: -/// -/// * For structs whose last field is a DST, metadata is the metadata for the last field -/// * For the `str` type, metadata is the length in bytes as `usize` -/// * For slice types like `[T]`, metadata is the length in items as `usize` -/// * For trait objects like `dyn SomeTrait`, metadata is [`DynMetadata`][DynMetadata] -/// (e.g. `DynMetadata`) -/// -/// In the future, the Rust language may gain new kinds of types -/// that have different pointer metadata. -/// -/// [dst]: https://doc.rust-lang.org/nomicon/exotic-sizes.html#dynamically-sized-types-dsts -/// -/// -/// # The `Pointee` trait -/// -/// The point of this trait is its `Metadata` associated type, -/// which is `()` or `usize` or `DynMetadata<_>` as described above. -/// It is automatically implemented for every type. -/// It can be assumed to be implemented in a generic context, even without a corresponding bound. -/// -/// -/// # Usage -/// -/// Raw pointers can be decomposed into the data pointer and metadata components -/// with their [`to_raw_parts`] method. -/// -/// Alternatively, metadata alone can be extracted with the [`metadata`] function. -/// A reference can be passed to [`metadata`] and implicitly coerced. -/// -/// A (possibly-wide) pointer can be put back together from its data pointer and metadata -/// with [`from_raw_parts`] or [`from_raw_parts_mut`]. -/// -/// [`to_raw_parts`]: *const::to_raw_parts -#[lang = "pointee_trait"] -#[rustc_deny_explicit_impl(implement_via_object = false)] -pub trait Pointee { - /// The type for metadata in pointers and references to `Self`. - #[lang = "metadata_type"] - // NOTE: Keep trait bounds in `static_assert_expected_bounds_for_metadata` - // in `library/core/src/ptr/metadata.rs` - // in sync with those here: - type Metadata: fmt::Debug + Copy + Send + Sync + Ord + Hash + Unpin + Freeze; -} - -/// Pointers to types implementing this trait alias are “thin”. -/// -/// This includes statically-`Sized` types and `extern` types. -/// -/// # Example -/// -/// ```rust -/// #![feature(ptr_metadata)] -/// -/// fn this_never_panics() { -/// assert_eq!(std::mem::size_of::<&T>(), std::mem::size_of::()) -/// } -/// ``` -#[unstable(feature = "ptr_metadata", issue = "81513")] -// NOTE: don’t stabilize this before trait aliases are stable in the language? -pub trait Thin = Pointee; - -/// Extract the metadata component of a pointer. -/// -/// Values of type `*mut T`, `&T`, or `&mut T` can be passed directly to this function -/// as they implicitly coerce to `*const T`. -/// -/// # Example -/// -/// ``` -/// #![feature(ptr_metadata)] -/// -/// assert_eq!(std::ptr::metadata("foo"), 3_usize); -/// ``` -#[rustc_const_unstable(feature = "ptr_metadata", issue = "81513")] -#[inline] -pub const fn metadata(ptr: *const T) -> ::Metadata { - // SAFETY: Accessing the value from the `PtrRepr` union is safe since *const T - // and PtrComponents have the same memory layouts. Only std can make this - // guarantee. - unsafe { PtrRepr { const_ptr: ptr }.components.metadata } -} - -/// Forms a (possibly-wide) raw pointer from a data pointer and metadata. -/// -/// This function is safe but the returned pointer is not necessarily safe to dereference. -/// For slices, see the documentation of [`slice::from_raw_parts`] for safety requirements. -/// For trait objects, the metadata must come from a pointer to the same underlying erased type. -/// -/// [`slice::from_raw_parts`]: crate::slice::from_raw_parts -#[unstable(feature = "ptr_metadata", issue = "81513")] -#[rustc_const_unstable(feature = "ptr_metadata", issue = "81513")] -#[inline] -pub const fn from_raw_parts( - data_pointer: *const (), - metadata: ::Metadata, -) -> *const T { - aggregate_raw_ptr(data_pointer, metadata) -} - -/// Performs the same functionality as [`from_raw_parts`], except that a -/// raw `*mut` pointer is returned, as opposed to a raw `*const` pointer. -/// -/// See the documentation of [`from_raw_parts`] for more details. -#[unstable(feature = "ptr_metadata", issue = "81513")] -#[rustc_const_unstable(feature = "ptr_metadata", issue = "81513")] -#[inline] -pub const fn from_raw_parts_mut( - data_pointer: *mut (), - metadata: ::Metadata, -) -> *mut T { - aggregate_raw_ptr(data_pointer, metadata) -} - -#[repr(C)] -union PtrRepr { - const_ptr: *const T, - mut_ptr: *mut T, - components: PtrComponents, -} - -#[repr(C)] -struct PtrComponents { - data_pointer: *const (), - metadata: ::Metadata, -} - -// Manual impl needed to avoid `T: Copy` bound. -impl Copy for PtrComponents {} - -// Manual impl needed to avoid `T: Clone` bound. -impl Clone for PtrComponents { - fn clone(&self) -> Self { - *self - } -} - -/// The metadata for a `Dyn = dyn SomeTrait` trait object type. -/// -/// It is a pointer to a vtable (virtual call table) -/// that represents all the necessary information -/// to manipulate the concrete type stored inside a trait object. -/// The vtable notably contains: -/// -/// * type size -/// * type alignment -/// * a pointer to the type’s `drop_in_place` impl (may be a no-op for plain-old-data) -/// * pointers to all the methods for the type’s implementation of the trait -/// -/// Note that the first three are special because they’re necessary to allocate, drop, -/// and deallocate any trait object. -/// -/// It is possible to name this struct with a type parameter that is not a `dyn` trait object -/// (for example `DynMetadata`) but not to obtain a meaningful value of that struct. -/// -/// Note that while this type implements `PartialEq`, comparing vtable pointers is unreliable: -/// pointers to vtables of the same type for the same trait can compare inequal (because vtables are -/// duplicated in multiple codegen units), and pointers to vtables of *different* types/traits can -/// compare equal (since identical vtables can be deduplicated within a codegen unit). -#[lang = "dyn_metadata"] -pub struct DynMetadata { - _vtable_ptr: &'static VTable, - _phantom: crate::marker::PhantomData, -} - -extern "C" { - /// Opaque type for accessing vtables. - /// - /// Private implementation detail of `DynMetadata::size_of` etc. - /// There is conceptually not actually any Abstract Machine memory behind this pointer. - type VTable; -} - -impl DynMetadata { - /// One of the things that rustc_middle does with this being a lang item is - /// give it `FieldsShape::Primitive`, which means that as far as codegen can - /// tell, it *is* a reference, and thus doesn't have any fields. - /// That means we can't use field access, and have to transmute it instead. - #[inline] - fn vtable_ptr(self) -> *const VTable { - // SAFETY: this layout assumption is hard-coded into the compiler. - // If it's somehow not a size match, the transmute will error. - unsafe { crate::mem::transmute::(self) } - } - - /// Returns the size of the type associated with this vtable. - #[inline] - pub fn size_of(self) -> usize { - // Note that "size stored in vtable" is *not* the same as "result of size_of_val_raw". - // Consider a reference like `&(i32, dyn Send)`: the vtable will only store the size of the - // `Send` part! - // SAFETY: DynMetadata always contains a valid vtable pointer - return unsafe { - crate::intrinsics::vtable_size(self.vtable_ptr() as *const ()) - }; - } - - /// Returns the alignment of the type associated with this vtable. - #[inline] - pub fn align_of(self) -> usize { - // SAFETY: DynMetadata always contains a valid vtable pointer - return unsafe { - crate::intrinsics::vtable_align(self.vtable_ptr() as *const ()) - }; - } - - /// Returns the size and alignment together as a `Layout` - #[inline] - pub fn layout(self) -> crate::alloc::Layout { - // SAFETY: the compiler emitted this vtable for a concrete Rust type which - // is known to have a valid layout. Same rationale as in `Layout::for_value`. - unsafe { crate::alloc::Layout::from_size_align_unchecked(self.size_of(), self.align_of()) } - } -} - -unsafe impl Send for DynMetadata {} -unsafe impl Sync for DynMetadata {} - -impl fmt::Debug for DynMetadata { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("DynMetadata").field(&self.vtable_ptr()).finish() - } -} - -// Manual impls needed to avoid `Dyn: $Trait` bounds. - -impl Unpin for DynMetadata {} - -impl Copy for DynMetadata {} - -impl Clone for DynMetadata { - #[inline] - fn clone(&self) -> Self { - *self - } -} - -impl Eq for DynMetadata {} - -impl PartialEq for DynMetadata { - #[inline] - fn eq(&self, other: &Self) -> bool { - crate::ptr::eq::(self.vtable_ptr(), other.vtable_ptr()) - } -} - -impl Ord for DynMetadata { - #[inline] - #[allow(ambiguous_wide_pointer_comparisons)] - fn cmp(&self, other: &Self) -> crate::cmp::Ordering { - <*const VTable>::cmp(&self.vtable_ptr(), &other.vtable_ptr()) - } -} - -impl PartialOrd for DynMetadata { - #[inline] - fn partial_cmp(&self, other: &Self) -> Option { - Some(self.cmp(other)) - } -} - -impl Hash for DynMetadata { - #[inline] - fn hash(&self, hasher: &mut H) { - crate::ptr::hash::(self.vtable_ptr(), hasher) - } -} diff --git a/library/core/src/ptr/mod.rs b/library/core/src/ptr/mod.rs deleted file mode 100644 index 61d101c766f49..0000000000000 --- a/library/core/src/ptr/mod.rs +++ /dev/null @@ -1,2313 +0,0 @@ -//! Manually manage memory through raw pointers. -//! -//! *[See also the pointer primitive types](pointer).* -//! -//! # Safety -//! -//! Many functions in this module take raw pointers as arguments and read from or write to them. For -//! this to be safe, these pointers must be *valid* for the given access. Whether a pointer is valid -//! depends on the operation it is used for (read or write), and the extent of the memory that is -//! accessed (i.e., how many bytes are read/written) -- it makes no sense to ask "is this pointer -//! valid"; one has to ask "is this pointer valid for a given access". Most functions use `*mut T` -//! and `*const T` to access only a single value, in which case the documentation omits the size and -//! implicitly assumes it to be `size_of::()` bytes. -//! -//! The precise rules for validity are not determined yet. The guarantees that are -//! provided at this point are very minimal: -//! -//! * For operations of [size zero][zst], *every* pointer is valid, including the [null] pointer. -//! The following points are only concerned with non-zero-sized accesses. -//! * A [null] pointer is *never* valid. -//! * For a pointer to be valid, it is necessary, but not always sufficient, that the pointer -//! be *dereferenceable*: the memory range of the given size starting at the pointer must all be -//! within the bounds of a single allocated object. Note that in Rust, -//! every (stack-allocated) variable is considered a separate allocated object. -//! * All accesses performed by functions in this module are *non-atomic* in the sense -//! of [atomic operations] used to synchronize between threads. This means it is -//! undefined behavior to perform two concurrent accesses to the same location from different -//! threads unless both accesses only read from memory. Notice that this explicitly -//! includes [`read_volatile`] and [`write_volatile`]: Volatile accesses cannot -//! be used for inter-thread synchronization. -//! * The result of casting a reference to a pointer is valid for as long as the -//! underlying object is live and no reference (just raw pointers) is used to -//! access the same memory. That is, reference and pointer accesses cannot be -//! interleaved. -//! -//! These axioms, along with careful use of [`offset`] for pointer arithmetic, -//! are enough to correctly implement many useful things in unsafe code. Stronger guarantees -//! will be provided eventually, as the [aliasing] rules are being determined. For more -//! information, see the [book] as well as the section in the reference devoted -//! to [undefined behavior][ub]. -//! -//! We say that a pointer is "dangling" if it is not valid for any non-zero-sized accesses. This -//! means out-of-bounds pointers, pointers to freed memory, null pointers, and pointers created with -//! [`NonNull::dangling`] are all dangling. -//! -//! ## Alignment -//! -//! Valid raw pointers as defined above are not necessarily properly aligned (where -//! "proper" alignment is defined by the pointee type, i.e., `*const T` must be -//! aligned to `mem::align_of::()`). However, most functions require their -//! arguments to be properly aligned, and will explicitly state -//! this requirement in their documentation. Notable exceptions to this are -//! [`read_unaligned`] and [`write_unaligned`]. -//! -//! When a function requires proper alignment, it does so even if the access -//! has size 0, i.e., even if memory is not actually touched. Consider using -//! [`NonNull::dangling`] in such cases. -//! -//! ## Allocated object -//! -//! An *allocated object* is a subset of program memory which is addressable -//! from Rust, and within which pointer arithmetic is possible. Examples of -//! allocated objects include heap allocations, stack-allocated variables, -//! statics, and consts. The safety preconditions of some Rust operations - -//! such as `offset` and field projections (`expr.field`) - are defined in -//! terms of the allocated objects on which they operate. -//! -//! An allocated object has a base address, a size, and a set of memory -//! addresses. It is possible for an allocated object to have zero size, but -//! such an allocated object will still have a base address. The base address -//! of an allocated object is not necessarily unique. While it is currently the -//! case that an allocated object always has a set of memory addresses which is -//! fully contiguous (i.e., has no "holes"), there is no guarantee that this -//! will not change in the future. -//! -//! For any allocated object with `base` address, `size`, and a set of -//! `addresses`, the following are guaranteed: -//! - For all addresses `a` in `addresses`, `a` is in the range `base .. (base + -//! size)` (note that this requires `a < base + size`, not `a <= base + size`) -//! - `base` is not equal to [`null()`] (i.e., the address with the numerical -//! value 0) -//! - `base + size <= usize::MAX` -//! - `size <= isize::MAX` -//! -//! As a consequence of these guarantees, given any address `a` within the set -//! of addresses of an allocated object: -//! - It is guaranteed that `a - base` does not overflow `isize` -//! - It is guaranteed that `a - base` is non-negative -//! - It is guaranteed that, given `o = a - base` (i.e., the offset of `a` within -//! the allocated object), `base + o` will not wrap around the address space (in -//! other words, will not overflow `usize`) -//! -//! [`null()`]: null -//! -//! # Strict Provenance -//! -//! **The following text is non-normative, insufficiently formal, and is an extremely strict -//! interpretation of provenance. It's ok if your code doesn't strictly conform to it.** -//! -//! [Strict Provenance][] is an experimental set of APIs that help tools that try -//! to validate the memory-safety of your program's execution. Notably this includes [Miri][] -//! and [CHERI][], which can detect when you access out of bounds memory or otherwise violate -//! Rust's memory model. -//! -//! Provenance must exist in some form for any programming -//! language compiled for modern computer architectures, but specifying a model for provenance -//! in a way that is useful to both compilers and programmers is an ongoing challenge. -//! The [Strict Provenance][] experiment seeks to explore the question: *what if we just said you -//! couldn't do all the nasty operations that make provenance so messy?* -//! -//! What APIs would have to be removed? What APIs would have to be added? How much would code -//! have to change, and is it worse or better now? Would any patterns become truly inexpressible? -//! Could we carve out special exceptions for those patterns? Should we? -//! -//! A secondary goal of this project is to see if we can disambiguate the many functions of -//! pointer<->integer casts enough for the definition of `usize` to be loosened so that it -//! isn't *pointer*-sized but address-space/offset/allocation-sized (we'll probably continue -//! to conflate these notions). This would potentially make it possible to more efficiently -//! target platforms where pointers are larger than offsets, such as CHERI and maybe some -//! segmented architectures. -//! -//! ## Provenance -//! -//! **This section is *non-normative* and is part of the [Strict Provenance][] experiment.** -//! -//! Pointers are not *simply* an "integer" or "address". For instance, it's uncontroversial -//! to say that a Use After Free is clearly Undefined Behaviour, even if you "get lucky" -//! and the freed memory gets reallocated before your read/write (in fact this is the -//! worst-case scenario, UAFs would be much less concerning if this didn't happen!). -//! To rationalize this claim, pointers need to somehow be *more* than just their addresses: -//! they must have provenance. -//! -//! When an allocation is created, that allocation has a unique Original Pointer. For alloc -//! APIs this is literally the pointer the call returns, and for local variables and statics, -//! this is the name of the variable/static. This is mildly overloading the term "pointer" -//! for the sake of brevity/exposition. -//! -//! The Original Pointer for an allocation is guaranteed to have unique access to the entire -//! allocation and *only* that allocation. In this sense, an allocation can be thought of -//! as a "sandbox" that cannot be broken into or out of. *Provenance* is the permission -//! to access an allocation's sandbox and has both a *spatial* and *temporal* component: -//! -//! * Spatial: A range of bytes that the pointer is allowed to access. -//! * Temporal: The lifetime (of the allocation) that access to these bytes is tied to. -//! -//! Spatial provenance makes sure you don't go beyond your sandbox, while temporal provenance -//! makes sure that you can't "get lucky" after your permission to access some memory -//! has been revoked (either through deallocations or borrows expiring). -//! -//! Provenance is implicitly shared with all pointers transitively derived from -//! The Original Pointer through operations like [`offset`], borrowing, and pointer casts. -//! Some operations may *shrink* the derived provenance, limiting how much memory it can -//! access or how long it's valid for (i.e. borrowing a subfield and subslicing). -//! -//! Shrinking provenance cannot be undone: even if you "know" there is a larger allocation, you -//! can't derive a pointer with a larger provenance. Similarly, you cannot "recombine" -//! two contiguous provenances back into one (i.e. with a `fn merge(&[T], &[T]) -> &[T]`). -//! -//! A reference to a value always has provenance over exactly the memory that field occupies. -//! A reference to a slice always has provenance over exactly the range that slice describes. -//! -//! If an allocation is deallocated, all pointers with provenance to that allocation become -//! invalidated, and effectively lose their provenance. -//! -//! The strict provenance experiment is mostly only interested in exploring stricter *spatial* -//! provenance. In this sense it can be thought of as a subset of the more ambitious and -//! formal [Stacked Borrows][] research project, which is what tools like [Miri][] are based on. -//! In particular, Stacked Borrows is necessary to properly describe what borrows are allowed -//! to do and when they become invalidated. This necessarily involves much more complex -//! *temporal* reasoning than simply identifying allocations. Adjusting APIs and code -//! for the strict provenance experiment will also greatly help Stacked Borrows. -//! -//! -//! ## Pointer Vs Addresses -//! -//! **This section is *non-normative* and is part of the [Strict Provenance][] experiment.** -//! -//! One of the largest historical issues with trying to define provenance is that programmers -//! freely convert between pointers and integers. Once you allow for this, it generally becomes -//! impossible to accurately track and preserve provenance information, and you need to appeal -//! to very complex and unreliable heuristics. But of course, converting between pointers and -//! integers is very useful, so what can we do? -//! -//! Also did you know WASM is actually a "Harvard Architecture"? As in function pointers are -//! handled completely differently from data pointers? And we kind of just shipped Rust on WASM -//! without really addressing the fact that we let you freely convert between function pointers -//! and data pointers, because it mostly Just Works? Let's just put that on the "pointer casts -//! are dubious" pile. -//! -//! Strict Provenance attempts to square these circles by decoupling Rust's traditional conflation -//! of pointers and `usize` (and `isize`), and defining a pointer to semantically contain the -//! following information: -//! -//! * The **address-space** it is part of (e.g. "data" vs "code" in WASM). -//! * The **address** it points to, which can be represented by a `usize`. -//! * The **provenance** it has, defining the memory it has permission to access. -//! Provenance can be absent, in which case the pointer does not have permission to access any memory. -//! -//! Under Strict Provenance, a usize *cannot* accurately represent a pointer, and converting from -//! a pointer to a usize is generally an operation which *only* extracts the address. It is -//! therefore *impossible* to construct a valid pointer from a usize because there is no way -//! to restore the address-space and provenance. In other words, pointer-integer-pointer -//! roundtrips are not possible (in the sense that the resulting pointer is not dereferenceable). -//! -//! The key insight to making this model *at all* viable is the [`with_addr`][] method: -//! -//! ```text -//! /// Creates a new pointer with the given address. -//! /// -//! /// This performs the same operation as an `addr as ptr` cast, but copies -//! /// the *address-space* and *provenance* of `self` to the new pointer. -//! /// This allows us to dynamically preserve and propagate this important -//! /// information in a way that is otherwise impossible with a unary cast. -//! /// -//! /// This is equivalent to using `wrapping_offset` to offset `self` to the -//! /// given address, and therefore has all the same capabilities and restrictions. -//! pub fn with_addr(self, addr: usize) -> Self; -//! ``` -//! -//! So you're still able to drop down to the address representation and do whatever -//! clever bit tricks you want *as long as* you're able to keep around a pointer -//! into the allocation you care about that can "reconstitute" the other parts of the pointer. -//! Usually this is very easy, because you only are taking a pointer, messing with the address, -//! and then immediately converting back to a pointer. To make this use case more ergonomic, -//! we provide the [`map_addr`][] method. -//! -//! To help make it clear that code is "following" Strict Provenance semantics, we also provide an -//! [`addr`][] method which promises that the returned address is not part of a -//! pointer-usize-pointer roundtrip. In the future we may provide a lint for pointer<->integer -//! casts to help you audit if your code conforms to strict provenance. -//! -//! -//! ## Using Strict Provenance -//! -//! Most code needs no changes to conform to strict provenance, as the only really concerning -//! operation that *wasn't* obviously already Undefined Behaviour is casts from usize to a -//! pointer. For code which *does* cast a usize to a pointer, the scope of the change depends -//! on exactly what you're doing. -//! -//! In general you just need to make sure that if you want to convert a usize address to a -//! pointer and then use that pointer to read/write memory, you need to keep around a pointer -//! that has sufficient provenance to perform that read/write itself. In this way all of your -//! casts from an address to a pointer are essentially just applying offsets/indexing. -//! -//! This is generally trivial to do for simple cases like tagged pointers *as long as you -//! represent the tagged pointer as an actual pointer and not a usize*. For instance: -//! -//! ``` -//! #![feature(strict_provenance)] -//! -//! unsafe { -//! // A flag we want to pack into our pointer -//! static HAS_DATA: usize = 0x1; -//! static FLAG_MASK: usize = !HAS_DATA; -//! -//! // Our value, which must have enough alignment to have spare least-significant-bits. -//! let my_precious_data: u32 = 17; -//! assert!(core::mem::align_of::() > 1); -//! -//! // Create a tagged pointer -//! let ptr = &my_precious_data as *const u32; -//! let tagged = ptr.map_addr(|addr| addr | HAS_DATA); -//! -//! // Check the flag: -//! if tagged.addr() & HAS_DATA != 0 { -//! // Untag and read the pointer -//! let data = *tagged.map_addr(|addr| addr & FLAG_MASK); -//! assert_eq!(data, 17); -//! } else { -//! unreachable!() -//! } -//! } -//! ``` -//! -//! (Yes, if you've been using AtomicUsize for pointers in concurrent datastructures, you should -//! be using AtomicPtr instead. If that messes up the way you atomically manipulate pointers, -//! we would like to know why, and what needs to be done to fix it.) -//! -//! Something more complicated and just generally *evil* like an XOR-List requires more significant -//! changes like allocating all nodes in a pre-allocated Vec or Arena and using a pointer -//! to the whole allocation to reconstitute the XORed addresses. -//! -//! Situations where a valid pointer *must* be created from just an address, such as baremetal code -//! accessing a memory-mapped interface at a fixed address, are an open question on how to support. -//! These situations *will* still be allowed, but we might require some kind of "I know what I'm -//! doing" annotation to explain the situation to the compiler. It's also possible they need no -//! special attention at all, because they're generally accessing memory outside the scope of -//! "the abstract machine", or already using "I know what I'm doing" annotations like "volatile". -//! -//! Under [Strict Provenance] it is Undefined Behaviour to: -//! -//! * Access memory through a pointer that does not have provenance over that memory. -//! -//! * [`offset`] a pointer to or from an address it doesn't have provenance over. -//! This means it's always UB to offset a pointer derived from something deallocated, -//! even if the offset is 0. Note that a pointer "one past the end" of its provenance -//! is not actually outside its provenance, it just has 0 bytes it can load/store. -//! -//! But it *is* still sound to: -//! -//! * Create a pointer without provenance from just an address (see [`ptr::dangling`][]). Such a -//! pointer cannot be used for memory accesses (except for zero-sized accesses). This can still be -//! useful for sentinel values like `null` *or* to represent a tagged pointer that will never be -//! dereferenceable. In general, it is always sound for an integer to pretend to be a pointer "for -//! fun" as long as you don't use operations on it which require it to be valid (non-zero-sized -//! offset, read, write, etc). -//! -//! * Forge an allocation of size zero at any sufficiently aligned non-null address. -//! i.e. the usual "ZSTs are fake, do what you want" rules apply *but* this only applies -//! for actual forgery (integers cast to pointers). If you borrow some struct's field -//! that *happens* to be zero-sized, the resulting pointer will have provenance tied to -//! that allocation and it will still get invalidated if the allocation gets deallocated. -//! In the future we may introduce an API to make such a forged allocation explicit. -//! -//! * [`wrapping_offset`][] a pointer outside its provenance. This includes pointers -//! which have "no" provenance. Unfortunately there may be practical limits on this for a -//! particular platform, and it's an open question as to how to specify this (if at all). -//! Notably, [CHERI][] relies on a compression scheme that can't handle a -//! pointer getting offset "too far" out of bounds. If this happens, the address -//! returned by `addr` will be the value you expect, but the provenance will get invalidated -//! and using it to read/write will fault. The details of this are architecture-specific -//! and based on alignment, but the buffer on either side of the pointer's range is pretty -//! generous (think kilobytes, not bytes). -//! -//! * Compare arbitrary pointers by address. Addresses *are* just integers and so there is -//! always a coherent answer, even if the pointers are dangling or from different -//! address-spaces/provenances. Of course, comparing addresses from different address-spaces -//! is generally going to be *meaningless*, but so is comparing Kilograms to Meters, and Rust -//! doesn't prevent that either. Similarly, if you get "lucky" and notice that a pointer -//! one-past-the-end is the "same" address as the start of an unrelated allocation, anything -//! you do with that fact is *probably* going to be gibberish. The scope of that gibberish -//! is kept under control by the fact that the two pointers *still* aren't allowed to access -//! the other's allocation (bytes), because they still have different provenance. -//! -//! * Perform pointer tagging tricks. This falls out of [`wrapping_offset`] but is worth -//! mentioning in more detail because of the limitations of [CHERI][]. Low-bit tagging -//! is very robust, and often doesn't even go out of bounds because types ensure -//! size >= align (and over-aligning actually gives CHERI more flexibility). Anything -//! more complex than this rapidly enters "extremely platform-specific" territory as -//! certain things may or may not be allowed based on specific supported operations. -//! For instance, ARM explicitly supports high-bit tagging, and so CHERI on ARM inherits -//! that and should support it. -//! -//! ## Exposed Provenance -//! -//! **This section is *non-normative* and is an extension to the [Strict Provenance] experiment.** -//! -//! As discussed above, pointer-usize-pointer roundtrips are not possible under [Strict Provenance]. -//! This is by design: the goal of Strict Provenance is to provide a clear specification that we are -//! confident can be formalized unambiguously and can be subject to precise formal reasoning. -//! -//! However, there exist situations where pointer-usize-pointer roundtrips cannot be avoided, or -//! where avoiding them would require major refactoring. Legacy platform APIs also regularly assume -//! that `usize` can capture all the information that makes up a pointer. The goal of Strict -//! Provenance is not to rule out such code; the goal is to put all the *other* pointer-manipulating -//! code onto a more solid foundation. Strict Provenance is about improving the situation where -//! possible (all the code that can be written with Strict Provenance) without making things worse -//! for situations where Strict Provenance is insufficient. -//! -//! For these situations, there is a highly experimental extension to Strict Provenance called -//! *Exposed Provenance*. This extension permits pointer-usize-pointer roundtrips. However, its -//! semantics are on much less solid footing than Strict Provenance, and at this point it is not yet -//! clear where a satisfying unambiguous semantics can be defined for Exposed Provenance. -//! Furthermore, Exposed Provenance will not work (well) with tools like [Miri] and [CHERI]. -//! -//! Exposed Provenance is provided by the [`expose_provenance`] and [`with_exposed_provenance`] methods, -//! which are meant to replace `as` casts between pointers and integers. [`expose_provenance`] is a lot like -//! [`addr`], but additionally adds the provenance of the pointer to a global list of 'exposed' -//! provenances. (This list is purely conceptual, it exists for the purpose of specifying Rust but -//! is not materialized in actual executions, except in tools like [Miri].) [`with_exposed_provenance`] -//! can be used to construct a pointer with one of these previously 'exposed' provenances. -//! [`with_exposed_provenance`] takes only `addr: usize` as arguments, so unlike in [`with_addr`] there is -//! no indication of what the correct provenance for the returned pointer is -- and that is exactly -//! what makes pointer-usize-pointer roundtrips so tricky to rigorously specify! There is no -//! algorithm that decides which provenance will be used. You can think of this as "guessing" the -//! right provenance, and the guess will be "maximally in your favor", in the sense that if there is -//! any way to avoid undefined behavior, then that is the guess that will be taken. However, if -//! there is *no* previously 'exposed' provenance that justifies the way the returned pointer will -//! be used, the program has undefined behavior. -//! -//! Using [`expose_provenance`] or [`with_exposed_provenance`] (or the `as` casts) means that code is -//! *not* following Strict Provenance rules. The goal of the Strict Provenance experiment is to -//! determine how far one can get in Rust without the use of [`expose_provenance`] and -//! [`with_exposed_provenance`], and to encourage code to be written with Strict Provenance APIs only. -//! Maximizing the amount of such code is a major win for avoiding specification complexity and to -//! facilitate adoption of tools like [CHERI] and [Miri] that can be a big help in increasing the -//! confidence in (unsafe) Rust code. -//! -//! [aliasing]: ../../nomicon/aliasing.html -//! [book]: ../../book/ch19-01-unsafe-rust.html#dereferencing-a-raw-pointer -//! [ub]: ../../reference/behavior-considered-undefined.html -//! [zst]: ../../nomicon/exotic-sizes.html#zero-sized-types-zsts -//! [atomic operations]: crate::sync::atomic -//! [`offset`]: pointer::offset -//! [`wrapping_offset`]: pointer::wrapping_offset -//! [`with_addr`]: pointer::with_addr -//! [`map_addr`]: pointer::map_addr -//! [`addr`]: pointer::addr -//! [`ptr::dangling`]: core::ptr::dangling -//! [`expose_provenance`]: pointer::expose_provenance -//! [`with_exposed_provenance`]: with_exposed_provenance -//! [Miri]: https://github.com/rust-lang/miri -//! [CHERI]: https://www.cl.cam.ac.uk/research/security/ctsrd/cheri/ -//! [Strict Provenance]: https://github.com/rust-lang/rust/issues/95228 -//! [Stacked Borrows]: https://plv.mpi-sws.org/rustbelt/stacked-borrows/ - -#![stable(feature = "rust1", since = "1.0.0")] -// There are many unsafe functions taking pointers that don't dereference them. -#![allow(clippy::not_unsafe_ptr_arg_deref)] - -use crate::cmp::Ordering; -use crate::fmt; -use crate::hash; -use crate::intrinsics; -use crate::marker::FnPtr; -use crate::ub_checks; - -use crate::mem::{self, align_of, size_of, MaybeUninit}; -#[cfg(kani)] -use crate::kani; - -mod alignment; -#[unstable(feature = "ptr_alignment_type", issue = "102070")] -pub use alignment::Alignment; - -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(inline)] -pub use crate::intrinsics::copy_nonoverlapping; - -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(inline)] -pub use crate::intrinsics::copy; - -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(inline)] -pub use crate::intrinsics::write_bytes; - -mod metadata; -#[unstable(feature = "ptr_metadata", issue = "81513")] -pub use metadata::{from_raw_parts, from_raw_parts_mut, metadata, DynMetadata, Pointee, Thin}; - -mod non_null; -#[stable(feature = "nonnull", since = "1.25.0")] -pub use non_null::NonNull; - -mod unique; -#[unstable(feature = "ptr_internals", issue = "none")] -pub use unique::Unique; - -mod const_ptr; -mod mut_ptr; - -/// Executes the destructor (if any) of the pointed-to value. -/// -/// This is semantically equivalent to calling [`ptr::read`] and discarding -/// the result, but has the following advantages: -/// -/// * It is *required* to use `drop_in_place` to drop unsized types like -/// trait objects, because they can't be read out onto the stack and -/// dropped normally. -/// -/// * It is friendlier to the optimizer to do this over [`ptr::read`] when -/// dropping manually allocated memory (e.g., in the implementations of -/// `Box`/`Rc`/`Vec`), as the compiler doesn't need to prove that it's -/// sound to elide the copy. -/// -/// * It can be used to drop [pinned] data when `T` is not `repr(packed)` -/// (pinned data must not be moved before it is dropped). -/// -/// Unaligned values cannot be dropped in place, they must be copied to an aligned -/// location first using [`ptr::read_unaligned`]. For packed structs, this move is -/// done automatically by the compiler. This means the fields of packed structs -/// are not dropped in-place. -/// -/// [`ptr::read`]: self::read -/// [`ptr::read_unaligned`]: self::read_unaligned -/// [pinned]: crate::pin -/// -/// # Safety -/// -/// Behavior is undefined if any of the following conditions are violated: -/// -/// * `to_drop` must be [valid] for both reads and writes. -/// -/// * `to_drop` must be properly aligned, even if `T` has size 0. -/// -/// * `to_drop` must be nonnull, even if `T` has size 0. -/// -/// * The value `to_drop` points to must be valid for dropping, which may mean -/// it must uphold additional invariants. These invariants depend on the type -/// of the value being dropped. For instance, when dropping a Box, the box's -/// pointer to the heap must be valid. -/// -/// * While `drop_in_place` is executing, the only way to access parts of -/// `to_drop` is through the `&mut self` references supplied to the -/// `Drop::drop` methods that `drop_in_place` invokes. -/// -/// Additionally, if `T` is not [`Copy`], using the pointed-to value after -/// calling `drop_in_place` can cause undefined behavior. Note that `*to_drop = -/// foo` counts as a use because it will cause the value to be dropped -/// again. [`write()`] can be used to overwrite data without causing it to be -/// dropped. -/// -/// [valid]: self#safety -/// -/// # Examples -/// -/// Manually remove the last item from a vector: -/// -/// ``` -/// use std::ptr; -/// use std::rc::Rc; -/// -/// let last = Rc::new(1); -/// let weak = Rc::downgrade(&last); -/// -/// let mut v = vec![Rc::new(0), last]; -/// -/// unsafe { -/// // Get a raw pointer to the last element in `v`. -/// let ptr = &mut v[1] as *mut _; -/// // Shorten `v` to prevent the last item from being dropped. We do that first, -/// // to prevent issues if the `drop_in_place` below panics. -/// v.set_len(1); -/// // Without a call `drop_in_place`, the last item would never be dropped, -/// // and the memory it manages would be leaked. -/// ptr::drop_in_place(ptr); -/// } -/// -/// assert_eq!(v, &[0.into()]); -/// -/// // Ensure that the last item was dropped. -/// assert!(weak.upgrade().is_none()); -/// ``` -#[stable(feature = "drop_in_place", since = "1.8.0")] -#[lang = "drop_in_place"] -#[allow(unconditional_recursion)] -#[rustc_diagnostic_item = "ptr_drop_in_place"] -pub unsafe fn drop_in_place(to_drop: *mut T) { - // Code here does not matter - this is replaced by the - // real drop glue by the compiler. - - // SAFETY: see comment above - unsafe { drop_in_place(to_drop) } -} - -/// Creates a null raw pointer. -/// -/// This function is equivalent to zero-initializing the pointer: -/// `MaybeUninit::<*const T>::zeroed().assume_init()`. -/// The resulting pointer has the address 0. -/// -/// # Examples -/// -/// ``` -/// use std::ptr; -/// -/// let p: *const i32 = ptr::null(); -/// assert!(p.is_null()); -/// assert_eq!(p as usize, 0); // this pointer has the address 0 -/// ``` -#[inline(always)] -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_promotable] -#[rustc_const_stable(feature = "const_ptr_null", since = "1.24.0")] -#[rustc_allow_const_fn_unstable(ptr_metadata)] -#[rustc_diagnostic_item = "ptr_null"] -pub const fn null() -> *const T { - from_raw_parts(without_provenance(0), ()) -} - -/// Creates a null mutable raw pointer. -/// -/// This function is equivalent to zero-initializing the pointer: -/// `MaybeUninit::<*mut T>::zeroed().assume_init()`. -/// The resulting pointer has the address 0. -/// -/// # Examples -/// -/// ``` -/// use std::ptr; -/// -/// let p: *mut i32 = ptr::null_mut(); -/// assert!(p.is_null()); -/// assert_eq!(p as usize, 0); // this pointer has the address 0 -/// ``` -#[inline(always)] -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_promotable] -#[rustc_const_stable(feature = "const_ptr_null", since = "1.24.0")] -#[rustc_allow_const_fn_unstable(ptr_metadata)] -#[rustc_diagnostic_item = "ptr_null_mut"] -pub const fn null_mut() -> *mut T { - from_raw_parts_mut(without_provenance_mut(0), ()) -} - -/// Creates a pointer with the given address and no provenance. -/// -/// This is equivalent to `ptr::null().with_addr(addr)`. -/// -/// Without provenance, this pointer is not associated with any actual allocation. Such a -/// no-provenance pointer may be used for zero-sized memory accesses (if suitably aligned), but -/// non-zero-sized memory accesses with a no-provenance pointer are UB. No-provenance pointers are -/// little more than a usize address in disguise. -/// -/// This is different from `addr as *const T`, which creates a pointer that picks up a previously -/// exposed provenance. See [`with_exposed_provenance`] for more details on that operation. -/// -/// This API and its claimed semantics are part of the Strict Provenance experiment, -/// see the [module documentation][crate::ptr] for details. -#[inline(always)] -#[must_use] -#[rustc_const_stable(feature = "stable_things_using_strict_provenance", since = "1.61.0")] -#[unstable(feature = "strict_provenance", issue = "95228")] -pub const fn without_provenance(addr: usize) -> *const T { - // FIXME(strict_provenance_magic): I am magic and should be a compiler intrinsic. - // We use transmute rather than a cast so tools like Miri can tell that this - // is *not* the same as with_exposed_provenance. - // SAFETY: every valid integer is also a valid pointer (as long as you don't dereference that - // pointer). - unsafe { mem::transmute(addr) } -} - -/// Creates a new pointer that is dangling, but well-aligned. -/// -/// This is useful for initializing types which lazily allocate, like -/// `Vec::new` does. -/// -/// Note that the pointer value may potentially represent a valid pointer to -/// a `T`, which means this must not be used as a "not yet initialized" -/// sentinel value. Types that lazily allocate must track initialization by -/// some other means. -#[inline(always)] -#[must_use] -#[rustc_const_stable(feature = "stable_things_using_strict_provenance", since = "1.61.0")] -#[unstable(feature = "strict_provenance", issue = "95228")] -pub const fn dangling() -> *const T { - without_provenance(mem::align_of::()) -} - -/// Creates a pointer with the given address and no provenance. -/// -/// This is equivalent to `ptr::null_mut().with_addr(addr)`. -/// -/// Without provenance, this pointer is not associated with any actual allocation. Such a -/// no-provenance pointer may be used for zero-sized memory accesses (if suitably aligned), but -/// non-zero-sized memory accesses with a no-provenance pointer are UB. No-provenance pointers are -/// little more than a usize address in disguise. -/// -/// This is different from `addr as *mut T`, which creates a pointer that picks up a previously -/// exposed provenance. See [`with_exposed_provenance_mut`] for more details on that operation. -/// -/// This API and its claimed semantics are part of the Strict Provenance experiment, -/// see the [module documentation][crate::ptr] for details. -#[inline(always)] -#[must_use] -#[rustc_const_stable(feature = "stable_things_using_strict_provenance", since = "1.61.0")] -#[unstable(feature = "strict_provenance", issue = "95228")] -pub const fn without_provenance_mut(addr: usize) -> *mut T { - // FIXME(strict_provenance_magic): I am magic and should be a compiler intrinsic. - // We use transmute rather than a cast so tools like Miri can tell that this - // is *not* the same as with_exposed_provenance. - // SAFETY: every valid integer is also a valid pointer (as long as you don't dereference that - // pointer). - unsafe { mem::transmute(addr) } -} - -/// Creates a new pointer that is dangling, but well-aligned. -/// -/// This is useful for initializing types which lazily allocate, like -/// `Vec::new` does. -/// -/// Note that the pointer value may potentially represent a valid pointer to -/// a `T`, which means this must not be used as a "not yet initialized" -/// sentinel value. Types that lazily allocate must track initialization by -/// some other means. -#[inline(always)] -#[must_use] -#[rustc_const_stable(feature = "stable_things_using_strict_provenance", since = "1.61.0")] -#[unstable(feature = "strict_provenance", issue = "95228")] -pub const fn dangling_mut() -> *mut T { - without_provenance_mut(mem::align_of::()) -} - -/// Convert an address back to a pointer, picking up a previously 'exposed' provenance. -/// -/// This is a more rigorously specified alternative to `addr as *const T`. The provenance of the -/// returned pointer is that of *any* pointer that was previously exposed by passing it to -/// [`expose_provenance`][pointer::expose_provenance], or a `ptr as usize` cast. In addition, memory which is -/// outside the control of the Rust abstract machine (MMIO registers, for example) is always -/// considered to be exposed, so long as this memory is disjoint from memory that will be used by -/// the abstract machine such as the stack, heap, and statics. -/// -/// If there is no 'exposed' provenance that justifies the way this pointer will be used, -/// the program has undefined behavior. In particular, the aliasing rules still apply: pointers -/// and references that have been invalidated due to aliasing accesses cannot be used any more, -/// even if they have been exposed! -/// -/// Note that there is no algorithm that decides which provenance will be used. You can think of this -/// as "guessing" the right provenance, and the guess will be "maximally in your favor", in the sense -/// that if there is any way to avoid undefined behavior (while upholding all aliasing requirements), -/// then that is the guess that will be taken. -/// -/// On platforms with multiple address spaces, it is your responsibility to ensure that the -/// address makes sense in the address space that this pointer will be used with. -/// -/// Using this function means that code is *not* following [Strict -/// Provenance][self#strict-provenance] rules. "Guessing" a -/// suitable provenance complicates specification and reasoning and may not be supported by -/// tools that help you to stay conformant with the Rust memory model, so it is recommended to -/// use [`with_addr`][pointer::with_addr] wherever possible. -/// -/// On most platforms this will produce a value with the same bytes as the address. Platforms -/// which need to store additional information in a pointer may not support this operation, -/// since it is generally not possible to actually *compute* which provenance the returned -/// pointer has to pick up. -/// -/// It is unclear whether this function can be given a satisfying unambiguous specification. This -/// API and its claimed semantics are part of [Exposed Provenance][self#exposed-provenance]. -#[must_use] -#[inline(always)] -#[unstable(feature = "exposed_provenance", issue = "95228")] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -#[allow(fuzzy_provenance_casts)] // this *is* the explicit provenance API one should use instead -pub fn with_exposed_provenance(addr: usize) -> *const T -where - T: Sized, -{ - // FIXME(strict_provenance_magic): I am magic and should be a compiler intrinsic. - addr as *const T -} - -/// Convert an address back to a mutable pointer, picking up a previously 'exposed' provenance. -/// -/// This is a more rigorously specified alternative to `addr as *mut T`. The provenance of the -/// returned pointer is that of *any* pointer that was previously passed to -/// [`expose_provenance`][pointer::expose_provenance] or a `ptr as usize` cast. If there is no previously -/// 'exposed' provenance that justifies the way this pointer will be used, the program has undefined -/// behavior. Note that there is no algorithm that decides which provenance will be used. You can -/// think of this as "guessing" the right provenance, and the guess will be "maximally in your -/// favor", in the sense that if there is any way to avoid undefined behavior, then that is the -/// guess that will be taken. -/// -/// On platforms with multiple address spaces, it is your responsibility to ensure that the -/// address makes sense in the address space that this pointer will be used with. -/// -/// Using this function means that code is *not* following [Strict -/// Provenance][self#strict-provenance] rules. "Guessing" a -/// suitable provenance complicates specification and reasoning and may not be supported by -/// tools that help you to stay conformant with the Rust memory model, so it is recommended to -/// use [`with_addr`][pointer::with_addr] wherever possible. -/// -/// On most platforms this will produce a value with the same bytes as the address. Platforms -/// which need to store additional information in a pointer may not support this operation, -/// since it is generally not possible to actually *compute* which provenance the returned -/// pointer has to pick up. -/// -/// It is unclear whether this function can be given a satisfying unambiguous specification. This -/// API and its claimed semantics are part of [Exposed Provenance][self#exposed-provenance]. -#[must_use] -#[inline(always)] -#[unstable(feature = "exposed_provenance", issue = "95228")] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -#[allow(fuzzy_provenance_casts)] // this *is* the explicit provenance API one should use instead -pub fn with_exposed_provenance_mut(addr: usize) -> *mut T -where - T: Sized, -{ - // FIXME(strict_provenance_magic): I am magic and should be a compiler intrinsic. - addr as *mut T -} - -/// Convert a reference to a raw pointer. -/// -/// This is equivalent to `r as *const T`, but is a bit safer since it will never silently change -/// type or mutability, in particular if the code is refactored. -#[inline(always)] -#[must_use] -#[stable(feature = "ptr_from_ref", since = "1.76.0")] -#[rustc_const_stable(feature = "ptr_from_ref", since = "1.76.0")] -#[rustc_never_returns_null_ptr] -#[rustc_diagnostic_item = "ptr_from_ref"] -pub const fn from_ref(r: &T) -> *const T { - r -} - -/// Convert a mutable reference to a raw pointer. -/// -/// This is equivalent to `r as *mut T`, but is a bit safer since it will never silently change -/// type or mutability, in particular if the code is refactored. -#[inline(always)] -#[must_use] -#[stable(feature = "ptr_from_ref", since = "1.76.0")] -#[rustc_const_stable(feature = "ptr_from_ref", since = "1.76.0")] -#[rustc_allow_const_fn_unstable(const_mut_refs)] -#[rustc_never_returns_null_ptr] -pub const fn from_mut(r: &mut T) -> *mut T { - r -} - -/// Forms a raw slice from a pointer and a length. -/// -/// The `len` argument is the number of **elements**, not the number of bytes. -/// -/// This function is safe, but actually using the return value is unsafe. -/// See the documentation of [`slice::from_raw_parts`] for slice safety requirements. -/// -/// [`slice::from_raw_parts`]: crate::slice::from_raw_parts -/// -/// # Examples -/// -/// ```rust -/// use std::ptr; -/// -/// // create a slice pointer when starting out with a pointer to the first element -/// let x = [5, 6, 7]; -/// let raw_pointer = x.as_ptr(); -/// let slice = ptr::slice_from_raw_parts(raw_pointer, 3); -/// assert_eq!(unsafe { &*slice }[2], 7); -/// ``` -/// -/// You must ensure that the pointer is valid and not null before dereferencing -/// the raw slice. A slice reference must never have a null pointer, even if it's empty. -/// -/// ```rust,should_panic -/// use std::ptr; -/// let danger: *const [u8] = ptr::slice_from_raw_parts(ptr::null(), 0); -/// unsafe { -/// danger.as_ref().expect("references must not be null"); -/// } -/// ``` -#[inline] -#[stable(feature = "slice_from_raw_parts", since = "1.42.0")] -#[rustc_const_stable(feature = "const_slice_from_raw_parts", since = "1.64.0")] -#[rustc_allow_const_fn_unstable(ptr_metadata)] -#[rustc_diagnostic_item = "ptr_slice_from_raw_parts"] -pub const fn slice_from_raw_parts(data: *const T, len: usize) -> *const [T] { - intrinsics::aggregate_raw_ptr(data, len) -} - -/// Forms a raw mutable slice from a pointer and a length. -/// -/// The `len` argument is the number of **elements**, not the number of bytes. -/// -/// Performs the same functionality as [`slice_from_raw_parts`], except that a -/// raw mutable slice is returned, as opposed to a raw immutable slice. -/// -/// This function is safe, but actually using the return value is unsafe. -/// See the documentation of [`slice::from_raw_parts_mut`] for slice safety requirements. -/// -/// [`slice::from_raw_parts_mut`]: crate::slice::from_raw_parts_mut -/// -/// # Examples -/// -/// ```rust -/// use std::ptr; -/// -/// let x = &mut [5, 6, 7]; -/// let raw_pointer = x.as_mut_ptr(); -/// let slice = ptr::slice_from_raw_parts_mut(raw_pointer, 3); -/// -/// unsafe { -/// (*slice)[2] = 99; // assign a value at an index in the slice -/// }; -/// -/// assert_eq!(unsafe { &*slice }[2], 99); -/// ``` -/// -/// You must ensure that the pointer is valid and not null before dereferencing -/// the raw slice. A slice reference must never have a null pointer, even if it's empty. -/// -/// ```rust,should_panic -/// use std::ptr; -/// let danger: *mut [u8] = ptr::slice_from_raw_parts_mut(ptr::null_mut(), 0); -/// unsafe { -/// danger.as_mut().expect("references must not be null"); -/// } -/// ``` -#[inline] -#[stable(feature = "slice_from_raw_parts", since = "1.42.0")] -#[rustc_const_unstable(feature = "const_slice_from_raw_parts_mut", issue = "67456")] -#[rustc_diagnostic_item = "ptr_slice_from_raw_parts_mut"] -pub const fn slice_from_raw_parts_mut(data: *mut T, len: usize) -> *mut [T] { - intrinsics::aggregate_raw_ptr(data, len) -} - -/// Swaps the values at two mutable locations of the same type, without -/// deinitializing either. -/// -/// But for the following exceptions, this function is semantically -/// equivalent to [`mem::swap`]: -/// -/// * It operates on raw pointers instead of references. When references are -/// available, [`mem::swap`] should be preferred. -/// -/// * The two pointed-to values may overlap. If the values do overlap, then the -/// overlapping region of memory from `x` will be used. This is demonstrated -/// in the second example below. -/// -/// * The operation is "untyped" in the sense that data may be uninitialized or otherwise violate -/// the requirements of `T`. The initialization state is preserved exactly. -/// -/// # Safety -/// -/// Behavior is undefined if any of the following conditions are violated: -/// -/// * Both `x` and `y` must be [valid] for both reads and writes. They must remain valid even when the -/// other pointer is written. (This means if the memory ranges overlap, the two pointers must not -/// be subject to aliasing restrictions relative to each other.) -/// -/// * Both `x` and `y` must be properly aligned. -/// -/// Note that even if `T` has size `0`, the pointers must be non-null and properly aligned. -/// -/// [valid]: self#safety -/// -/// # Examples -/// -/// Swapping two non-overlapping regions: -/// -/// ``` -/// use std::ptr; -/// -/// let mut array = [0, 1, 2, 3]; -/// -/// let (x, y) = array.split_at_mut(2); -/// let x = x.as_mut_ptr().cast::<[u32; 2]>(); // this is `array[0..2]` -/// let y = y.as_mut_ptr().cast::<[u32; 2]>(); // this is `array[2..4]` -/// -/// unsafe { -/// ptr::swap(x, y); -/// assert_eq!([2, 3, 0, 1], array); -/// } -/// ``` -/// -/// Swapping two overlapping regions: -/// -/// ``` -/// use std::ptr; -/// -/// let mut array: [i32; 4] = [0, 1, 2, 3]; -/// -/// let array_ptr: *mut i32 = array.as_mut_ptr(); -/// -/// let x = array_ptr as *mut [i32; 3]; // this is `array[0..3]` -/// let y = unsafe { array_ptr.add(1) } as *mut [i32; 3]; // this is `array[1..4]` -/// -/// unsafe { -/// ptr::swap(x, y); -/// // The indices `1..3` of the slice overlap between `x` and `y`. -/// // Reasonable results would be for to them be `[2, 3]`, so that indices `0..3` are -/// // `[1, 2, 3]` (matching `y` before the `swap`); or for them to be `[0, 1]` -/// // so that indices `1..4` are `[0, 1, 2]` (matching `x` before the `swap`). -/// // This implementation is defined to make the latter choice. -/// assert_eq!([1, 0, 1, 2], array); -/// } -/// ``` -#[inline] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_const_unstable(feature = "const_swap", issue = "83163")] -#[rustc_diagnostic_item = "ptr_swap"] -pub const unsafe fn swap(x: *mut T, y: *mut T) { - // Give ourselves some scratch space to work with. - // We do not have to worry about drops: `MaybeUninit` does nothing when dropped. - let mut tmp = MaybeUninit::::uninit(); - - // Perform the swap - // SAFETY: the caller must guarantee that `x` and `y` are - // valid for writes and properly aligned. `tmp` cannot be - // overlapping either `x` or `y` because `tmp` was just allocated - // on the stack as a separate allocated object. - unsafe { - copy_nonoverlapping(x, tmp.as_mut_ptr(), 1); - copy(y, x, 1); // `x` and `y` may overlap - copy_nonoverlapping(tmp.as_ptr(), y, 1); - } -} - -/// Swaps `count * size_of::()` bytes between the two regions of memory -/// beginning at `x` and `y`. The two regions must *not* overlap. -/// -/// The operation is "untyped" in the sense that data may be uninitialized or otherwise violate the -/// requirements of `T`. The initialization state is preserved exactly. -/// -/// # Safety -/// -/// Behavior is undefined if any of the following conditions are violated: -/// -/// * Both `x` and `y` must be [valid] for both reads and writes of `count * -/// size_of::()` bytes. -/// -/// * Both `x` and `y` must be properly aligned. -/// -/// * The region of memory beginning at `x` with a size of `count * -/// size_of::()` bytes must *not* overlap with the region of memory -/// beginning at `y` with the same size. -/// -/// Note that even if the effectively copied size (`count * size_of::()`) is `0`, -/// the pointers must be non-null and properly aligned. -/// -/// [valid]: self#safety -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// use std::ptr; -/// -/// let mut x = [1, 2, 3, 4]; -/// let mut y = [7, 8, 9]; -/// -/// unsafe { -/// ptr::swap_nonoverlapping(x.as_mut_ptr(), y.as_mut_ptr(), 2); -/// } -/// -/// assert_eq!(x, [7, 8, 3, 4]); -/// assert_eq!(y, [1, 2, 9]); -/// ``` -#[inline] -#[stable(feature = "swap_nonoverlapping", since = "1.27.0")] -#[rustc_const_unstable(feature = "const_swap", issue = "83163")] -#[rustc_diagnostic_item = "ptr_swap_nonoverlapping"] -pub const unsafe fn swap_nonoverlapping(x: *mut T, y: *mut T, count: usize) { - #[allow(unused)] - macro_rules! attempt_swap_as_chunks { - ($ChunkTy:ty) => { - if mem::align_of::() >= mem::align_of::<$ChunkTy>() - && mem::size_of::() % mem::size_of::<$ChunkTy>() == 0 - { - let x: *mut $ChunkTy = x.cast(); - let y: *mut $ChunkTy = y.cast(); - let count = count * (mem::size_of::() / mem::size_of::<$ChunkTy>()); - // SAFETY: these are the same bytes that the caller promised were - // ok, just typed as `MaybeUninit`s instead of as `T`s. - // The `if` condition above ensures that we're not violating - // alignment requirements, and that the division is exact so - // that we don't lose any bytes off the end. - return unsafe { swap_nonoverlapping_simple_untyped(x, y, count) }; - } - }; - } - - ub_checks::assert_unsafe_precondition!( - check_language_ub, - "ptr::swap_nonoverlapping requires that both pointer arguments are aligned and non-null \ - and the specified memory ranges do not overlap", - ( - x: *mut () = x as *mut (), - y: *mut () = y as *mut (), - size: usize = size_of::(), - align: usize = align_of::(), - count: usize = count, - ) => - ub_checks::is_aligned_and_not_null(x, align) - && ub_checks::is_aligned_and_not_null(y, align) - && ub_checks::is_nonoverlapping(x, y, size, count) - ); - - // Split up the slice into small power-of-two-sized chunks that LLVM is able - // to vectorize (unless it's a special type with more-than-pointer alignment, - // because we don't want to pessimize things like slices of SIMD vectors.) - if mem::align_of::() <= mem::size_of::() - && (!mem::size_of::().is_power_of_two() - || mem::size_of::() > mem::size_of::() * 2) - { - attempt_swap_as_chunks!(usize); - attempt_swap_as_chunks!(u8); - } - - // SAFETY: Same preconditions as this function - unsafe { swap_nonoverlapping_simple_untyped(x, y, count) } -} - -/// Same behaviour and safety conditions as [`swap_nonoverlapping`] -/// -/// LLVM can vectorize this (at least it can for the power-of-two-sized types -/// `swap_nonoverlapping` tries to use) so no need to manually SIMD it. -#[inline] -#[rustc_const_unstable(feature = "const_swap", issue = "83163")] -const unsafe fn swap_nonoverlapping_simple_untyped(x: *mut T, y: *mut T, count: usize) { - let x = x.cast::>(); - let y = y.cast::>(); - let mut i = 0; - while i < count { - // SAFETY: By precondition, `i` is in-bounds because it's below `n` - let x = unsafe { x.add(i) }; - // SAFETY: By precondition, `i` is in-bounds because it's below `n` - // and it's distinct from `x` since the ranges are non-overlapping - let y = unsafe { y.add(i) }; - - // If we end up here, it's because we're using a simple type -- like - // a small power-of-two-sized thing -- or a special type with particularly - // large alignment, particularly SIMD types. - // Thus we're fine just reading-and-writing it, as either it's small - // and that works well anyway or it's special and the type's author - // presumably wanted things to be done in the larger chunk. - - // SAFETY: we're only ever given pointers that are valid to read/write, - // including being aligned, and nothing here panics so it's drop-safe. - unsafe { - let a: MaybeUninit = read(x); - let b: MaybeUninit = read(y); - write(x, b); - write(y, a); - } - - i += 1; - } -} - -/// Moves `src` into the pointed `dst`, returning the previous `dst` value. -/// -/// Neither value is dropped. -/// -/// This function is semantically equivalent to [`mem::replace`] except that it -/// operates on raw pointers instead of references. When references are -/// available, [`mem::replace`] should be preferred. -/// -/// # Safety -/// -/// Behavior is undefined if any of the following conditions are violated: -/// -/// * `dst` must be [valid] for both reads and writes. -/// -/// * `dst` must be properly aligned. -/// -/// * `dst` must point to a properly initialized value of type `T`. -/// -/// Note that even if `T` has size `0`, the pointer must be non-null and properly aligned. -/// -/// [valid]: self#safety -/// -/// # Examples -/// -/// ``` -/// use std::ptr; -/// -/// let mut rust = vec!['b', 'u', 's', 't']; -/// -/// // `mem::replace` would have the same effect without requiring the unsafe -/// // block. -/// let b = unsafe { -/// ptr::replace(&mut rust[0], 'r') -/// }; -/// -/// assert_eq!(b, 'b'); -/// assert_eq!(rust, &['r', 'u', 's', 't']); -/// ``` -#[inline] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_const_unstable(feature = "const_replace", issue = "83164")] -#[rustc_diagnostic_item = "ptr_replace"] -pub const unsafe fn replace(dst: *mut T, src: T) -> T { - // SAFETY: the caller must guarantee that `dst` is valid to be - // cast to a mutable reference (valid for writes, aligned, initialized), - // and cannot overlap `src` since `dst` must point to a distinct - // allocated object. - unsafe { - ub_checks::assert_unsafe_precondition!( - check_language_ub, - "ptr::replace requires that the pointer argument is aligned and non-null", - ( - addr: *const () = dst as *const (), - align: usize = align_of::(), - ) => ub_checks::is_aligned_and_not_null(addr, align) - ); - mem::replace(&mut *dst, src) - } -} - -/// Reads the value from `src` without moving it. This leaves the -/// memory in `src` unchanged. -/// -/// # Safety -/// -/// Behavior is undefined if any of the following conditions are violated: -/// -/// * `src` must be [valid] for reads. -/// -/// * `src` must be properly aligned. Use [`read_unaligned`] if this is not the -/// case. -/// -/// * `src` must point to a properly initialized value of type `T`. -/// -/// Note that even if `T` has size `0`, the pointer must be non-null and properly aligned. -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// let x = 12; -/// let y = &x as *const i32; -/// -/// unsafe { -/// assert_eq!(std::ptr::read(y), 12); -/// } -/// ``` -/// -/// Manually implement [`mem::swap`]: -/// -/// ``` -/// use std::ptr; -/// -/// fn swap(a: &mut T, b: &mut T) { -/// unsafe { -/// // Create a bitwise copy of the value at `a` in `tmp`. -/// let tmp = ptr::read(a); -/// -/// // Exiting at this point (either by explicitly returning or by -/// // calling a function which panics) would cause the value in `tmp` to -/// // be dropped while the same value is still referenced by `a`. This -/// // could trigger undefined behavior if `T` is not `Copy`. -/// -/// // Create a bitwise copy of the value at `b` in `a`. -/// // This is safe because mutable references cannot alias. -/// ptr::copy_nonoverlapping(b, a, 1); -/// -/// // As above, exiting here could trigger undefined behavior because -/// // the same value is referenced by `a` and `b`. -/// -/// // Move `tmp` into `b`. -/// ptr::write(b, tmp); -/// -/// // `tmp` has been moved (`write` takes ownership of its second argument), -/// // so nothing is dropped implicitly here. -/// } -/// } -/// -/// let mut foo = "foo".to_owned(); -/// let mut bar = "bar".to_owned(); -/// -/// swap(&mut foo, &mut bar); -/// -/// assert_eq!(foo, "bar"); -/// assert_eq!(bar, "foo"); -/// ``` -/// -/// ## Ownership of the Returned Value -/// -/// `read` creates a bitwise copy of `T`, regardless of whether `T` is [`Copy`]. -/// If `T` is not [`Copy`], using both the returned value and the value at -/// `*src` can violate memory safety. Note that assigning to `*src` counts as a -/// use because it will attempt to drop the value at `*src`. -/// -/// [`write()`] can be used to overwrite data without causing it to be dropped. -/// -/// ``` -/// use std::ptr; -/// -/// let mut s = String::from("foo"); -/// unsafe { -/// // `s2` now points to the same underlying memory as `s`. -/// let mut s2: String = ptr::read(&s); -/// -/// assert_eq!(s2, "foo"); -/// -/// // Assigning to `s2` causes its original value to be dropped. Beyond -/// // this point, `s` must no longer be used, as the underlying memory has -/// // been freed. -/// s2 = String::default(); -/// assert_eq!(s2, ""); -/// -/// // Assigning to `s` would cause the old value to be dropped again, -/// // resulting in undefined behavior. -/// // s = String::from("bar"); // ERROR -/// -/// // `ptr::write` can be used to overwrite a value without dropping it. -/// ptr::write(&mut s, String::from("bar")); -/// } -/// -/// assert_eq!(s, "bar"); -/// ``` -/// -/// [valid]: self#safety -#[inline] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_const_stable(feature = "const_ptr_read", since = "1.71.0")] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -#[rustc_diagnostic_item = "ptr_read"] -pub const unsafe fn read(src: *const T) -> T { - // It would be semantically correct to implement this via `copy_nonoverlapping` - // and `MaybeUninit`, as was done before PR #109035. Calling `assume_init` - // provides enough information to know that this is a typed operation. - - // However, as of March 2023 the compiler was not capable of taking advantage - // of that information. Thus the implementation here switched to an intrinsic, - // which lowers to `_0 = *src` in MIR, to address a few issues: - // - // - Using `MaybeUninit::assume_init` after a `copy_nonoverlapping` was not - // turning the untyped copy into a typed load. As such, the generated - // `load` in LLVM didn't get various metadata, such as `!range` (#73258), - // `!nonnull`, and `!noundef`, resulting in poorer optimization. - // - Going through the extra local resulted in multiple extra copies, even - // in optimized MIR. (Ignoring StorageLive/Dead, the intrinsic is one - // MIR statement, while the previous implementation was eight.) LLVM - // could sometimes optimize them away, but because `read` is at the core - // of so many things, not having them in the first place improves what we - // hand off to the backend. For example, `mem::replace::` previously - // emitted 4 `alloca` and 6 `memcpy`s, but is now 1 `alloc` and 3 `memcpy`s. - // - In general, this approach keeps us from getting any more bugs (like - // #106369) that boil down to "`read(p)` is worse than `*p`", as this - // makes them look identical to the backend (or other MIR consumers). - // - // Future enhancements to MIR optimizations might well allow this to return - // to the previous implementation, rather than using an intrinsic. - - // SAFETY: the caller must guarantee that `src` is valid for reads. - unsafe { - #[cfg(debug_assertions)] // Too expensive to always enable (for now?) - ub_checks::assert_unsafe_precondition!( - check_language_ub, - "ptr::read requires that the pointer argument is aligned and non-null", - ( - addr: *const () = src as *const (), - align: usize = align_of::(), - ) => ub_checks::is_aligned_and_not_null(addr, align) - ); - crate::intrinsics::read_via_copy(src) - } -} - -/// Reads the value from `src` without moving it. This leaves the -/// memory in `src` unchanged. -/// -/// Unlike [`read`], `read_unaligned` works with unaligned pointers. -/// -/// # Safety -/// -/// Behavior is undefined if any of the following conditions are violated: -/// -/// * `src` must be [valid] for reads. -/// -/// * `src` must point to a properly initialized value of type `T`. -/// -/// Like [`read`], `read_unaligned` creates a bitwise copy of `T`, regardless of -/// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the returned -/// value and the value at `*src` can [violate memory safety][read-ownership]. -/// -/// Note that even if `T` has size `0`, the pointer must be non-null. -/// -/// [read-ownership]: read#ownership-of-the-returned-value -/// [valid]: self#safety -/// -/// ## On `packed` structs -/// -/// Attempting to create a raw pointer to an `unaligned` struct field with -/// an expression such as `&packed.unaligned as *const FieldType` creates an -/// intermediate unaligned reference before converting that to a raw pointer. -/// That this reference is temporary and immediately cast is inconsequential -/// as the compiler always expects references to be properly aligned. -/// As a result, using `&packed.unaligned as *const FieldType` causes immediate -/// *undefined behavior* in your program. -/// -/// Instead you must use the [`ptr::addr_of!`](addr_of) macro to -/// create the pointer. You may use that returned pointer together with this -/// function. -/// -/// An example of what not to do and how this relates to `read_unaligned` is: -/// -/// ``` -/// #[repr(packed, C)] -/// struct Packed { -/// _padding: u8, -/// unaligned: u32, -/// } -/// -/// let packed = Packed { -/// _padding: 0x00, -/// unaligned: 0x01020304, -/// }; -/// -/// // Take the address of a 32-bit integer which is not aligned. -/// // In contrast to `&packed.unaligned as *const _`, this has no undefined behavior. -/// let unaligned = std::ptr::addr_of!(packed.unaligned); -/// -/// let v = unsafe { std::ptr::read_unaligned(unaligned) }; -/// assert_eq!(v, 0x01020304); -/// ``` -/// -/// Accessing unaligned fields directly with e.g. `packed.unaligned` is safe however. -/// -/// # Examples -/// -/// Read a usize value from a byte buffer: -/// -/// ``` -/// use std::mem; -/// -/// fn read_usize(x: &[u8]) -> usize { -/// assert!(x.len() >= mem::size_of::()); -/// -/// let ptr = x.as_ptr() as *const usize; -/// -/// unsafe { ptr.read_unaligned() } -/// } -/// ``` -#[inline] -#[stable(feature = "ptr_unaligned", since = "1.17.0")] -#[rustc_const_stable(feature = "const_ptr_read", since = "1.71.0")] -#[rustc_allow_const_fn_unstable( - const_mut_refs, - const_maybe_uninit_as_mut_ptr, - const_intrinsic_copy -)] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -#[rustc_diagnostic_item = "ptr_read_unaligned"] -pub const unsafe fn read_unaligned(src: *const T) -> T { - let mut tmp = MaybeUninit::::uninit(); - // SAFETY: the caller must guarantee that `src` is valid for reads. - // `src` cannot overlap `tmp` because `tmp` was just allocated on - // the stack as a separate allocated object. - // - // Also, since we just wrote a valid value into `tmp`, it is guaranteed - // to be properly initialized. - unsafe { - copy_nonoverlapping(src as *const u8, tmp.as_mut_ptr() as *mut u8, mem::size_of::()); - tmp.assume_init() - } -} - -/// Overwrites a memory location with the given value without reading or -/// dropping the old value. -/// -/// `write` does not drop the contents of `dst`. This is safe, but it could leak -/// allocations or resources, so care should be taken not to overwrite an object -/// that should be dropped. -/// -/// Additionally, it does not drop `src`. Semantically, `src` is moved into the -/// location pointed to by `dst`. -/// -/// This is appropriate for initializing uninitialized memory, or overwriting -/// memory that has previously been [`read`] from. -/// -/// # Safety -/// -/// Behavior is undefined if any of the following conditions are violated: -/// -/// * `dst` must be [valid] for writes. -/// -/// * `dst` must be properly aligned. Use [`write_unaligned`] if this is not the -/// case. -/// -/// Note that even if `T` has size `0`, the pointer must be non-null and properly aligned. -/// -/// [valid]: self#safety -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// let mut x = 0; -/// let y = &mut x as *mut i32; -/// let z = 12; -/// -/// unsafe { -/// std::ptr::write(y, z); -/// assert_eq!(std::ptr::read(y), 12); -/// } -/// ``` -/// -/// Manually implement [`mem::swap`]: -/// -/// ``` -/// use std::ptr; -/// -/// fn swap(a: &mut T, b: &mut T) { -/// unsafe { -/// // Create a bitwise copy of the value at `a` in `tmp`. -/// let tmp = ptr::read(a); -/// -/// // Exiting at this point (either by explicitly returning or by -/// // calling a function which panics) would cause the value in `tmp` to -/// // be dropped while the same value is still referenced by `a`. This -/// // could trigger undefined behavior if `T` is not `Copy`. -/// -/// // Create a bitwise copy of the value at `b` in `a`. -/// // This is safe because mutable references cannot alias. -/// ptr::copy_nonoverlapping(b, a, 1); -/// -/// // As above, exiting here could trigger undefined behavior because -/// // the same value is referenced by `a` and `b`. -/// -/// // Move `tmp` into `b`. -/// ptr::write(b, tmp); -/// -/// // `tmp` has been moved (`write` takes ownership of its second argument), -/// // so nothing is dropped implicitly here. -/// } -/// } -/// -/// let mut foo = "foo".to_owned(); -/// let mut bar = "bar".to_owned(); -/// -/// swap(&mut foo, &mut bar); -/// -/// assert_eq!(foo, "bar"); -/// assert_eq!(bar, "foo"); -/// ``` -#[inline] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_const_unstable(feature = "const_ptr_write", issue = "86302")] -#[rustc_diagnostic_item = "ptr_write"] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -pub const unsafe fn write(dst: *mut T, src: T) { - // Semantically, it would be fine for this to be implemented as a - // `copy_nonoverlapping` and appropriate drop suppression of `src`. - - // However, implementing via that currently produces more MIR than is ideal. - // Using an intrinsic keeps it down to just the simple `*dst = move src` in - // MIR (11 statements shorter, at the time of writing), and also allows - // `src` to stay an SSA value in codegen_ssa, rather than a memory one. - - // SAFETY: the caller must guarantee that `dst` is valid for writes. - // `dst` cannot overlap `src` because the caller has mutable access - // to `dst` while `src` is owned by this function. - unsafe { - #[cfg(debug_assertions)] // Too expensive to always enable (for now?) - ub_checks::assert_unsafe_precondition!( - check_language_ub, - "ptr::write requires that the pointer argument is aligned and non-null", - ( - addr: *mut () = dst as *mut (), - align: usize = align_of::(), - ) => ub_checks::is_aligned_and_not_null(addr, align) - ); - intrinsics::write_via_move(dst, src) - } -} - -/// Overwrites a memory location with the given value without reading or -/// dropping the old value. -/// -/// Unlike [`write()`], the pointer may be unaligned. -/// -/// `write_unaligned` does not drop the contents of `dst`. This is safe, but it -/// could leak allocations or resources, so care should be taken not to overwrite -/// an object that should be dropped. -/// -/// Additionally, it does not drop `src`. Semantically, `src` is moved into the -/// location pointed to by `dst`. -/// -/// This is appropriate for initializing uninitialized memory, or overwriting -/// memory that has previously been read with [`read_unaligned`]. -/// -/// # Safety -/// -/// Behavior is undefined if any of the following conditions are violated: -/// -/// * `dst` must be [valid] for writes. -/// -/// Note that even if `T` has size `0`, the pointer must be non-null. -/// -/// [valid]: self#safety -/// -/// ## On `packed` structs -/// -/// Attempting to create a raw pointer to an `unaligned` struct field with -/// an expression such as `&packed.unaligned as *const FieldType` creates an -/// intermediate unaligned reference before converting that to a raw pointer. -/// That this reference is temporary and immediately cast is inconsequential -/// as the compiler always expects references to be properly aligned. -/// As a result, using `&packed.unaligned as *const FieldType` causes immediate -/// *undefined behavior* in your program. -/// -/// Instead you must use the [`ptr::addr_of_mut!`](addr_of_mut) -/// macro to create the pointer. You may use that returned pointer together with -/// this function. -/// -/// An example of how to do it and how this relates to `write_unaligned` is: -/// -/// ``` -/// #[repr(packed, C)] -/// struct Packed { -/// _padding: u8, -/// unaligned: u32, -/// } -/// -/// let mut packed: Packed = unsafe { std::mem::zeroed() }; -/// -/// // Take the address of a 32-bit integer which is not aligned. -/// // In contrast to `&packed.unaligned as *mut _`, this has no undefined behavior. -/// let unaligned = std::ptr::addr_of_mut!(packed.unaligned); -/// -/// unsafe { std::ptr::write_unaligned(unaligned, 42) }; -/// -/// assert_eq!({packed.unaligned}, 42); // `{...}` forces copying the field instead of creating a reference. -/// ``` -/// -/// Accessing unaligned fields directly with e.g. `packed.unaligned` is safe however -/// (as can be seen in the `assert_eq!` above). -/// -/// # Examples -/// -/// Write a usize value to a byte buffer: -/// -/// ``` -/// use std::mem; -/// -/// fn write_usize(x: &mut [u8], val: usize) { -/// assert!(x.len() >= mem::size_of::()); -/// -/// let ptr = x.as_mut_ptr() as *mut usize; -/// -/// unsafe { ptr.write_unaligned(val) } -/// } -/// ``` -#[inline] -#[stable(feature = "ptr_unaligned", since = "1.17.0")] -#[rustc_const_unstable(feature = "const_ptr_write", issue = "86302")] -#[rustc_diagnostic_item = "ptr_write_unaligned"] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -pub const unsafe fn write_unaligned(dst: *mut T, src: T) { - // SAFETY: the caller must guarantee that `dst` is valid for writes. - // `dst` cannot overlap `src` because the caller has mutable access - // to `dst` while `src` is owned by this function. - unsafe { - copy_nonoverlapping(addr_of!(src) as *const u8, dst as *mut u8, mem::size_of::()); - // We are calling the intrinsic directly to avoid function calls in the generated code. - intrinsics::forget(src); - } -} - -/// Performs a volatile read of the value from `src` without moving it. This -/// leaves the memory in `src` unchanged. -/// -/// Volatile operations are intended to act on I/O memory, and are guaranteed -/// to not be elided or reordered by the compiler across other volatile -/// operations. -/// -/// # Notes -/// -/// Rust does not currently have a rigorously and formally defined memory model, -/// so the precise semantics of what "volatile" means here is subject to change -/// over time. That being said, the semantics will almost always end up pretty -/// similar to [C11's definition of volatile][c11]. -/// -/// The compiler shouldn't change the relative order or number of volatile -/// memory operations. However, volatile memory operations on zero-sized types -/// (e.g., if a zero-sized type is passed to `read_volatile`) are noops -/// and may be ignored. -/// -/// [c11]: http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf -/// -/// # Safety -/// -/// Behavior is undefined if any of the following conditions are violated: -/// -/// * `src` must be [valid] for reads. -/// -/// * `src` must be properly aligned. -/// -/// * `src` must point to a properly initialized value of type `T`. -/// -/// Like [`read`], `read_volatile` creates a bitwise copy of `T`, regardless of -/// whether `T` is [`Copy`]. If `T` is not [`Copy`], using both the returned -/// value and the value at `*src` can [violate memory safety][read-ownership]. -/// However, storing non-[`Copy`] types in volatile memory is almost certainly -/// incorrect. -/// -/// Note that even if `T` has size `0`, the pointer must be non-null and properly aligned. -/// -/// [valid]: self#safety -/// [read-ownership]: read#ownership-of-the-returned-value -/// -/// Just like in C, whether an operation is volatile has no bearing whatsoever -/// on questions involving concurrent access from multiple threads. Volatile -/// accesses behave exactly like non-atomic accesses in that regard. In particular, -/// a race between a `read_volatile` and any write operation to the same location -/// is undefined behavior. -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// let x = 12; -/// let y = &x as *const i32; -/// -/// unsafe { -/// assert_eq!(std::ptr::read_volatile(y), 12); -/// } -/// ``` -#[inline] -#[stable(feature = "volatile", since = "1.9.0")] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -#[rustc_diagnostic_item = "ptr_read_volatile"] -#[safety::requires(ub_checks::can_dereference(src))] -pub unsafe fn read_volatile(src: *const T) -> T { - // SAFETY: the caller must uphold the safety contract for `volatile_load`. - unsafe { - ub_checks::assert_unsafe_precondition!( - check_language_ub, - "ptr::read_volatile requires that the pointer argument is aligned and non-null", - ( - addr: *const () = src as *const (), - align: usize = align_of::(), - ) => ub_checks::is_aligned_and_not_null(addr, align) - ); - intrinsics::volatile_load(src) - } -} - -/// Performs a volatile write of a memory location with the given value without -/// reading or dropping the old value. -/// -/// Volatile operations are intended to act on I/O memory, and are guaranteed -/// to not be elided or reordered by the compiler across other volatile -/// operations. -/// -/// `write_volatile` does not drop the contents of `dst`. This is safe, but it -/// could leak allocations or resources, so care should be taken not to overwrite -/// an object that should be dropped. -/// -/// Additionally, it does not drop `src`. Semantically, `src` is moved into the -/// location pointed to by `dst`. -/// -/// # Notes -/// -/// Rust does not currently have a rigorously and formally defined memory model, -/// so the precise semantics of what "volatile" means here is subject to change -/// over time. That being said, the semantics will almost always end up pretty -/// similar to [C11's definition of volatile][c11]. -/// -/// The compiler shouldn't change the relative order or number of volatile -/// memory operations. However, volatile memory operations on zero-sized types -/// (e.g., if a zero-sized type is passed to `write_volatile`) are noops -/// and may be ignored. -/// -/// [c11]: http://www.open-std.org/jtc1/sc22/wg14/www/docs/n1570.pdf -/// -/// # Safety -/// -/// Behavior is undefined if any of the following conditions are violated: -/// -/// * `dst` must be [valid] for writes. -/// -/// * `dst` must be properly aligned. -/// -/// Note that even if `T` has size `0`, the pointer must be non-null and properly aligned. -/// -/// [valid]: self#safety -/// -/// Just like in C, whether an operation is volatile has no bearing whatsoever -/// on questions involving concurrent access from multiple threads. Volatile -/// accesses behave exactly like non-atomic accesses in that regard. In particular, -/// a race between a `write_volatile` and any other operation (reading or writing) -/// on the same location is undefined behavior. -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// let mut x = 0; -/// let y = &mut x as *mut i32; -/// let z = 12; -/// -/// unsafe { -/// std::ptr::write_volatile(y, z); -/// assert_eq!(std::ptr::read_volatile(y), 12); -/// } -/// ``` -#[inline] -#[stable(feature = "volatile", since = "1.9.0")] -#[rustc_diagnostic_item = "ptr_write_volatile"] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -#[safety::requires(ub_checks::can_write(dst))] -pub unsafe fn write_volatile(dst: *mut T, src: T) { - // SAFETY: the caller must uphold the safety contract for `volatile_store`. - unsafe { - ub_checks::assert_unsafe_precondition!( - check_language_ub, - "ptr::write_volatile requires that the pointer argument is aligned and non-null", - ( - addr: *mut () = dst as *mut (), - align: usize = align_of::(), - ) => ub_checks::is_aligned_and_not_null(addr, align) - ); - intrinsics::volatile_store(dst, src); - } -} - -/// Align pointer `p`. -/// -/// Calculate offset (in terms of elements of `size_of::()` stride) that has to be applied -/// to pointer `p` so that pointer `p` would get aligned to `a`. -/// -/// # Safety -/// `a` must be a power of two. -/// -/// # Notes -/// This implementation has been carefully tailored to not panic. It is UB for this to panic. -/// The only real change that can be made here is change of `INV_TABLE_MOD_16` and associated -/// constants. -/// -/// If we ever decide to make it possible to call the intrinsic with `a` that is not a -/// power-of-two, it will probably be more prudent to just change to a naive implementation rather -/// than trying to adapt this to accommodate that change. -/// -/// Any questions go to @nagisa. -#[lang = "align_offset"] -pub(crate) const unsafe fn align_offset(p: *const T, a: usize) -> usize { - // FIXME(#75598): Direct use of these intrinsics improves codegen significantly at opt-level <= - // 1, where the method versions of these operations are not inlined. - use intrinsics::{ - assume, cttz_nonzero, exact_div, mul_with_overflow, unchecked_rem, unchecked_sub, - wrapping_add, wrapping_mul, wrapping_sub, - }; - use intrinsics::{unchecked_shl, unchecked_shr}; - - /// Calculate multiplicative modular inverse of `x` modulo `m`. - /// - /// This implementation is tailored for `align_offset` and has following preconditions: - /// - /// * `m` is a power-of-two; - /// * `x < m`; (if `x ≥ m`, pass in `x % m` instead) - /// - /// Implementation of this function shall not panic. Ever. - #[inline] - const unsafe fn mod_inv(x: usize, m: usize) -> usize { - /// Multiplicative modular inverse table modulo 2⁴ = 16. - /// - /// Note, that this table does not contain values where inverse does not exist (i.e., for - /// `0⁻¹ mod 16`, `2⁻¹ mod 16`, etc.) - const INV_TABLE_MOD_16: [u8; 8] = [1, 11, 13, 7, 9, 3, 5, 15]; - /// Modulo for which the `INV_TABLE_MOD_16` is intended. - const INV_TABLE_MOD: usize = 16; - - // SAFETY: `m` is required to be a power-of-two, hence non-zero. - let m_minus_one = unsafe { unchecked_sub(m, 1) }; - let mut inverse = INV_TABLE_MOD_16[(x & (INV_TABLE_MOD - 1)) >> 1] as usize; - let mut mod_gate = INV_TABLE_MOD; - // We iterate "up" using the following formula: - // - // $$ xy ≡ 1 (mod 2ⁿ) → xy (2 - xy) ≡ 1 (mod 2²ⁿ) $$ - // - // This application needs to be applied at least until `2²ⁿ ≥ m`, at which point we can - // finally reduce the computation to our desired `m` by taking `inverse mod m`. - // - // This computation is `O(log log m)`, which is to say, that on 64-bit machines this loop - // will always finish in at most 4 iterations. - loop { - // y = y * (2 - xy) mod n - // - // Note, that we use wrapping operations here intentionally – the original formula - // uses e.g., subtraction `mod n`. It is entirely fine to do them `mod - // usize::MAX` instead, because we take the result `mod n` at the end - // anyway. - if mod_gate >= m { - break; - } - inverse = wrapping_mul(inverse, wrapping_sub(2usize, wrapping_mul(x, inverse))); - let (new_gate, overflow) = mul_with_overflow(mod_gate, mod_gate); - if overflow { - break; - } - mod_gate = new_gate; - } - inverse & m_minus_one - } - - let stride = mem::size_of::(); - - // SAFETY: This is just an inlined `p.addr()` (which is not - // a `const fn` so we cannot call it). - // During const eval, we hook this function to ensure that the pointer never - // has provenance, making this sound. - let addr: usize = unsafe { mem::transmute(p) }; - - // SAFETY: `a` is a power-of-two, therefore non-zero. - let a_minus_one = unsafe { unchecked_sub(a, 1) }; - - if stride == 0 { - // SPECIAL_CASE: handle 0-sized types. No matter how many times we step, the address will - // stay the same, so no offset will be able to align the pointer unless it is already - // aligned. This branch _will_ be optimized out as `stride` is known at compile-time. - let p_mod_a = addr & a_minus_one; - return if p_mod_a == 0 { 0 } else { usize::MAX }; - } - - // SAFETY: `stride == 0` case has been handled by the special case above. - let a_mod_stride = unsafe { unchecked_rem(a, stride) }; - if a_mod_stride == 0 { - // SPECIAL_CASE: In cases where the `a` is divisible by `stride`, byte offset to align a - // pointer can be computed more simply through `-p (mod a)`. In the off-chance the byte - // offset is not a multiple of `stride`, the input pointer was misaligned and no pointer - // offset will be able to produce a `p` aligned to the specified `a`. - // - // The naive `-p (mod a)` equation inhibits LLVM's ability to select instructions - // like `lea`. We compute `(round_up_to_next_alignment(p, a) - p)` instead. This - // redistributes operations around the load-bearing, but pessimizing `and` instruction - // sufficiently for LLVM to be able to utilize the various optimizations it knows about. - // - // LLVM handles the branch here particularly nicely. If this branch needs to be evaluated - // at runtime, it will produce a mask `if addr_mod_stride == 0 { 0 } else { usize::MAX }` - // in a branch-free way and then bitwise-OR it with whatever result the `-p mod a` - // computation produces. - - let aligned_address = wrapping_add(addr, a_minus_one) & wrapping_sub(0, a); - let byte_offset = wrapping_sub(aligned_address, addr); - // FIXME: Remove the assume after - // SAFETY: Masking by `-a` can only affect the low bits, and thus cannot have reduced - // the value by more than `a-1`, so even though the intermediate values might have - // wrapped, the byte_offset is always in `[0, a)`. - unsafe { assume(byte_offset < a) }; - - // SAFETY: `stride == 0` case has been handled by the special case above. - let addr_mod_stride = unsafe { unchecked_rem(addr, stride) }; - - return if addr_mod_stride == 0 { - // SAFETY: `stride` is non-zero. This is guaranteed to divide exactly as well, because - // addr has been verified to be aligned to the original type’s alignment requirements. - unsafe { exact_div(byte_offset, stride) } - } else { - usize::MAX - }; - } - - // GENERAL_CASE: From here on we’re handling the very general case where `addr` may be - // misaligned, there isn’t an obvious relationship between `stride` and `a` that we can take an - // advantage of, etc. This case produces machine code that isn’t particularly high quality, - // compared to the special cases above. The code produced here is still within the realm of - // miracles, given the situations this case has to deal with. - - // SAFETY: a is power-of-two hence non-zero. stride == 0 case is handled above. - // FIXME(const-hack) replace with min - let gcdpow = unsafe { - let x = cttz_nonzero(stride); - let y = cttz_nonzero(a); - if x < y { x } else { y } - }; - // SAFETY: gcdpow has an upper-bound that’s at most the number of bits in a usize. - let gcd = unsafe { unchecked_shl(1usize, gcdpow) }; - // SAFETY: gcd is always greater or equal to 1. - if addr & unsafe { unchecked_sub(gcd, 1) } == 0 { - // This branch solves for the following linear congruence equation: - // - // ` p + so = 0 mod a ` - // - // `p` here is the pointer value, `s` - stride of `T`, `o` offset in `T`s, and `a` - the - // requested alignment. - // - // With `g = gcd(a, s)`, and the above condition asserting that `p` is also divisible by - // `g`, we can denote `a' = a/g`, `s' = s/g`, `p' = p/g`, then this becomes equivalent to: - // - // ` p' + s'o = 0 mod a' ` - // ` o = (a' - (p' mod a')) * (s'^-1 mod a') ` - // - // The first term is "the relative alignment of `p` to `a`" (divided by the `g`), the - // second term is "how does incrementing `p` by `s` bytes change the relative alignment of - // `p`" (again divided by `g`). Division by `g` is necessary to make the inverse well - // formed if `a` and `s` are not co-prime. - // - // Furthermore, the result produced by this solution is not "minimal", so it is necessary - // to take the result `o mod lcm(s, a)`. This `lcm(s, a)` is the same as `a'`. - - // SAFETY: `gcdpow` has an upper-bound not greater than the number of trailing 0-bits in - // `a`. - let a2 = unsafe { unchecked_shr(a, gcdpow) }; - // SAFETY: `a2` is non-zero. Shifting `a` by `gcdpow` cannot shift out any of the set bits - // in `a` (of which it has exactly one). - let a2minus1 = unsafe { unchecked_sub(a2, 1) }; - // SAFETY: `gcdpow` has an upper-bound not greater than the number of trailing 0-bits in - // `a`. - let s2 = unsafe { unchecked_shr(stride & a_minus_one, gcdpow) }; - // SAFETY: `gcdpow` has an upper-bound not greater than the number of trailing 0-bits in - // `a`. Furthermore, the subtraction cannot overflow, because `a2 = a >> gcdpow` will - // always be strictly greater than `(p % a) >> gcdpow`. - let minusp2 = unsafe { unchecked_sub(a2, unchecked_shr(addr & a_minus_one, gcdpow)) }; - // SAFETY: `a2` is a power-of-two, as proven above. `s2` is strictly less than `a2` - // because `(s % a) >> gcdpow` is strictly less than `a >> gcdpow`. - return wrapping_mul(minusp2, unsafe { mod_inv(s2, a2) }) & a2minus1; - } - - // Cannot be aligned at all. - usize::MAX -} - -/// Compares raw pointers for equality. -/// -/// This is the same as using the `==` operator, but less generic: -/// the arguments have to be `*const T` raw pointers, -/// not anything that implements `PartialEq`. -/// -/// This can be used to compare `&T` references (which coerce to `*const T` implicitly) -/// by their address rather than comparing the values they point to -/// (which is what the `PartialEq for &T` implementation does). -/// -/// When comparing wide pointers, both the address and the metadata are tested for equality. -/// However, note that comparing trait object pointers (`*const dyn Trait`) is unreliable: pointers -/// to values of the same underlying type can compare inequal (because vtables are duplicated in -/// multiple codegen units), and pointers to values of *different* underlying type can compare equal -/// (since identical vtables can be deduplicated within a codegen unit). -/// -/// # Examples -/// -/// ``` -/// use std::ptr; -/// -/// let five = 5; -/// let other_five = 5; -/// let five_ref = &five; -/// let same_five_ref = &five; -/// let other_five_ref = &other_five; -/// -/// assert!(five_ref == same_five_ref); -/// assert!(ptr::eq(five_ref, same_five_ref)); -/// -/// assert!(five_ref == other_five_ref); -/// assert!(!ptr::eq(five_ref, other_five_ref)); -/// ``` -/// -/// Slices are also compared by their length (fat pointers): -/// -/// ``` -/// let a = [1, 2, 3]; -/// assert!(std::ptr::eq(&a[..3], &a[..3])); -/// assert!(!std::ptr::eq(&a[..2], &a[..3])); -/// assert!(!std::ptr::eq(&a[0..2], &a[1..3])); -/// ``` -#[stable(feature = "ptr_eq", since = "1.17.0")] -#[inline(always)] -#[must_use = "pointer comparison produces a value"] -#[rustc_diagnostic_item = "ptr_eq"] -#[allow(ambiguous_wide_pointer_comparisons)] // it's actually clear here -pub fn eq(a: *const T, b: *const T) -> bool { - a == b -} - -/// Compares the *addresses* of the two pointers for equality, -/// ignoring any metadata in fat pointers. -/// -/// If the arguments are thin pointers of the same type, -/// then this is the same as [`eq`]. -/// -/// # Examples -/// -/// ``` -/// use std::ptr; -/// -/// let whole: &[i32; 3] = &[1, 2, 3]; -/// let first: &i32 = &whole[0]; -/// -/// assert!(ptr::addr_eq(whole, first)); -/// assert!(!ptr::eq::(whole, first)); -/// ``` -#[stable(feature = "ptr_addr_eq", since = "1.76.0")] -#[inline(always)] -#[must_use = "pointer comparison produces a value"] -pub fn addr_eq(p: *const T, q: *const U) -> bool { - (p as *const ()) == (q as *const ()) -} - -/// Hash a raw pointer. -/// -/// This can be used to hash a `&T` reference (which coerces to `*const T` implicitly) -/// by its address rather than the value it points to -/// (which is what the `Hash for &T` implementation does). -/// -/// # Examples -/// -/// ``` -/// use std::hash::{DefaultHasher, Hash, Hasher}; -/// use std::ptr; -/// -/// let five = 5; -/// let five_ref = &five; -/// -/// let mut hasher = DefaultHasher::new(); -/// ptr::hash(five_ref, &mut hasher); -/// let actual = hasher.finish(); -/// -/// let mut hasher = DefaultHasher::new(); -/// (five_ref as *const i32).hash(&mut hasher); -/// let expected = hasher.finish(); -/// -/// assert_eq!(actual, expected); -/// ``` -#[stable(feature = "ptr_hash", since = "1.35.0")] -pub fn hash(hashee: *const T, into: &mut S) { - use crate::hash::Hash; - hashee.hash(into); -} - -#[stable(feature = "fnptr_impls", since = "1.4.0")] -impl PartialEq for F { - #[inline] - fn eq(&self, other: &Self) -> bool { - self.addr() == other.addr() - } -} -#[stable(feature = "fnptr_impls", since = "1.4.0")] -impl Eq for F {} - -#[stable(feature = "fnptr_impls", since = "1.4.0")] -impl PartialOrd for F { - #[inline] - fn partial_cmp(&self, other: &Self) -> Option { - self.addr().partial_cmp(&other.addr()) - } -} -#[stable(feature = "fnptr_impls", since = "1.4.0")] -impl Ord for F { - #[inline] - fn cmp(&self, other: &Self) -> Ordering { - self.addr().cmp(&other.addr()) - } -} - -#[stable(feature = "fnptr_impls", since = "1.4.0")] -impl hash::Hash for F { - fn hash(&self, state: &mut HH) { - state.write_usize(self.addr() as _) - } -} - -#[stable(feature = "fnptr_impls", since = "1.4.0")] -impl fmt::Pointer for F { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::pointer_fmt_inner(self.addr() as _, f) - } -} - -#[stable(feature = "fnptr_impls", since = "1.4.0")] -impl fmt::Debug for F { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::pointer_fmt_inner(self.addr() as _, f) - } -} - -/// Create a `const` raw pointer to a place, without creating an intermediate reference. -/// -/// Creating a reference with `&`/`&mut` is only allowed if the pointer is properly aligned -/// and points to initialized data. For cases where those requirements do not hold, -/// raw pointers should be used instead. However, `&expr as *const _` creates a reference -/// before casting it to a raw pointer, and that reference is subject to the same rules -/// as all other references. This macro can create a raw pointer *without* creating -/// a reference first. -/// -/// See [`addr_of_mut`] for how to create a pointer to uninitialized data. -/// Doing that with `addr_of` would not make much sense since one could only -/// read the data, and that would be Undefined Behavior. -/// -/// # Safety -/// -/// The `expr` in `addr_of!(expr)` is evaluated as a place expression, but never loads from the -/// place or requires the place to be dereferenceable. This means that `addr_of!((*ptr).field)` -/// still requires the projection to `field` to be in-bounds, using the same rules as [`offset`]. -/// However, `addr_of!(*ptr)` is defined behavior even if `ptr` is null, dangling, or misaligned. -/// -/// Note that `Deref`/`Index` coercions (and their mutable counterparts) are applied inside -/// `addr_of!` like everywhere else, in which case a reference is created to call `Deref::deref` or -/// `Index::index`, respectively. The statements above only apply when no such coercions are -/// applied. -/// -/// [`offset`]: pointer::offset -/// -/// # Example -/// -/// **Correct usage: Creating a pointer to unaligned data** -/// -/// ``` -/// use std::ptr; -/// -/// #[repr(packed)] -/// struct Packed { -/// f1: u8, -/// f2: u16, -/// } -/// -/// let packed = Packed { f1: 1, f2: 2 }; -/// // `&packed.f2` would create an unaligned reference, and thus be Undefined Behavior! -/// let raw_f2 = ptr::addr_of!(packed.f2); -/// assert_eq!(unsafe { raw_f2.read_unaligned() }, 2); -/// ``` -/// -/// **Incorrect usage: Out-of-bounds fields projection** -/// -/// ```rust,no_run -/// use std::ptr; -/// -/// #[repr(C)] -/// struct MyStruct { -/// field1: i32, -/// field2: i32, -/// } -/// -/// let ptr: *const MyStruct = ptr::null(); -/// let fieldptr = unsafe { ptr::addr_of!((*ptr).field2) }; // Undefined Behavior ⚠️ -/// ``` -/// -/// The field projection `.field2` would offset the pointer by 4 bytes, -/// but the pointer is not in-bounds of an allocation for 4 bytes, -/// so this offset is Undefined Behavior. -/// See the [`offset`] docs for a full list of requirements for inbounds pointer arithmetic; the -/// same requirements apply to field projections, even inside `addr_of!`. (In particular, it makes -/// no difference whether the pointer is null or dangling.) -#[stable(feature = "raw_ref_macros", since = "1.51.0")] -#[rustc_macro_transparency = "semitransparent"] -#[allow_internal_unstable(raw_ref_op)] -pub macro addr_of($place:expr) { - &raw const $place -} - -/// Create a `mut` raw pointer to a place, without creating an intermediate reference. -/// -/// Creating a reference with `&`/`&mut` is only allowed if the pointer is properly aligned -/// and points to initialized data. For cases where those requirements do not hold, -/// raw pointers should be used instead. However, `&mut expr as *mut _` creates a reference -/// before casting it to a raw pointer, and that reference is subject to the same rules -/// as all other references. This macro can create a raw pointer *without* creating -/// a reference first. -/// -/// # Safety -/// -/// The `expr` in `addr_of_mut!(expr)` is evaluated as a place expression, but never loads from the -/// place or requires the place to be dereferenceable. This means that `addr_of_mut!((*ptr).field)` -/// still requires the projection to `field` to be in-bounds, using the same rules as [`offset`]. -/// However, `addr_of_mut!(*ptr)` is defined behavior even if `ptr` is null, dangling, or misaligned. -/// -/// Note that `Deref`/`Index` coercions (and their mutable counterparts) are applied inside -/// `addr_of_mut!` like everywhere else, in which case a reference is created to call `Deref::deref` -/// or `Index::index`, respectively. The statements above only apply when no such coercions are -/// applied. -/// -/// [`offset`]: pointer::offset -/// -/// # Examples -/// -/// **Correct usage: Creating a pointer to unaligned data** -/// -/// ``` -/// use std::ptr; -/// -/// #[repr(packed)] -/// struct Packed { -/// f1: u8, -/// f2: u16, -/// } -/// -/// let mut packed = Packed { f1: 1, f2: 2 }; -/// // `&mut packed.f2` would create an unaligned reference, and thus be Undefined Behavior! -/// let raw_f2 = ptr::addr_of_mut!(packed.f2); -/// unsafe { raw_f2.write_unaligned(42); } -/// assert_eq!({packed.f2}, 42); // `{...}` forces copying the field instead of creating a reference. -/// ``` -/// -/// **Correct usage: Creating a pointer to uninitialized data** -/// -/// ```rust -/// use std::{ptr, mem::MaybeUninit}; -/// -/// struct Demo { -/// field: bool, -/// } -/// -/// let mut uninit = MaybeUninit::::uninit(); -/// // `&uninit.as_mut().field` would create a reference to an uninitialized `bool`, -/// // and thus be Undefined Behavior! -/// let f1_ptr = unsafe { ptr::addr_of_mut!((*uninit.as_mut_ptr()).field) }; -/// unsafe { f1_ptr.write(true); } -/// let init = unsafe { uninit.assume_init() }; -/// ``` -/// -/// **Incorrect usage: Out-of-bounds fields projection** -/// -/// ```rust,no_run -/// use std::ptr; -/// -/// #[repr(C)] -/// struct MyStruct { -/// field1: i32, -/// field2: i32, -/// } -/// -/// let ptr: *mut MyStruct = ptr::null_mut(); -/// let fieldptr = unsafe { ptr::addr_of_mut!((*ptr).field2) }; // Undefined Behavior ⚠️ -/// ``` -/// -/// The field projection `.field2` would offset the pointer by 4 bytes, -/// but the pointer is not in-bounds of an allocation for 4 bytes, -/// so this offset is Undefined Behavior. -/// See the [`offset`] docs for a full list of requirements for inbounds pointer arithmetic; the -/// same requirements apply to field projections, even inside `addr_of_mut!`. (In particular, it -/// makes no difference whether the pointer is null or dangling.) -#[stable(feature = "raw_ref_macros", since = "1.51.0")] -#[rustc_macro_transparency = "semitransparent"] -#[allow_internal_unstable(raw_ref_op)] -pub macro addr_of_mut($place:expr) { - &raw mut $place -} - -#[cfg(kani)] -#[unstable(feature="kani", issue="none")] -mod verify { - use crate::fmt::Debug; - use super::*; - use crate::kani; - - #[kani::proof_for_contract(read_volatile)] - pub fn check_read_u128() { - let val = kani::any::(); - let ptr = &val as *const _; - let copy = unsafe { read_volatile(ptr) }; - assert_eq!(val, copy); - } -} - diff --git a/library/core/src/ptr/mut_ptr.rs b/library/core/src/ptr/mut_ptr.rs deleted file mode 100644 index c53953400addd..0000000000000 --- a/library/core/src/ptr/mut_ptr.rs +++ /dev/null @@ -1,2403 +0,0 @@ -use super::*; -use crate::cmp::Ordering::{Equal, Greater, Less}; -use crate::intrinsics::const_eval_select; -use crate::mem::SizedTypeProperties; -use crate::slice::{self, SliceIndex}; - -impl *mut T { - /// Returns `true` if the pointer is null. - /// - /// Note that unsized types have many possible null pointers, as only the - /// raw data pointer is considered, not their length, vtable, etc. - /// Therefore, two pointers that are null may still not compare equal to - /// each other. - /// - /// ## Behavior during const evaluation - /// - /// When this function is used during const evaluation, it may return `false` for pointers - /// that turn out to be null at runtime. Specifically, when a pointer to some memory - /// is offset beyond its bounds in such a way that the resulting pointer is null, - /// the function will still return `false`. There is no way for CTFE to know - /// the absolute position of that memory, so we cannot tell if the pointer is - /// null or not. - /// - /// # Examples - /// - /// ``` - /// let mut s = [1, 2, 3]; - /// let ptr: *mut u32 = s.as_mut_ptr(); - /// assert!(!ptr.is_null()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_ptr_is_null", issue = "74939")] - #[rustc_diagnostic_item = "ptr_is_null"] - #[inline] - pub const fn is_null(self) -> bool { - #[inline] - fn runtime_impl(ptr: *mut u8) -> bool { - ptr.addr() == 0 - } - - #[inline] - const fn const_impl(ptr: *mut u8) -> bool { - // Compare via a cast to a thin pointer, so fat pointers are only - // considering their "data" part for null-ness. - match (ptr).guaranteed_eq(null_mut()) { - None => false, - Some(res) => res, - } - } - - const_eval_select((self as *mut u8,), const_impl, runtime_impl) - } - - /// Casts to a pointer of another type. - #[stable(feature = "ptr_cast", since = "1.38.0")] - #[rustc_const_stable(feature = "const_ptr_cast", since = "1.38.0")] - #[rustc_diagnostic_item = "ptr_cast"] - #[inline(always)] - pub const fn cast(self) -> *mut U { - self as _ - } - - /// Use the pointer value in a new pointer of another type. - /// - /// In case `meta` is a (fat) pointer to an unsized type, this operation - /// will ignore the pointer part, whereas for (thin) pointers to sized - /// types, this has the same effect as a simple cast. - /// - /// The resulting pointer will have provenance of `self`, i.e., for a fat - /// pointer, this operation is semantically the same as creating a new - /// fat pointer with the data pointer value of `self` but the metadata of - /// `meta`. - /// - /// # Examples - /// - /// This function is primarily useful for allowing byte-wise pointer - /// arithmetic on potentially fat pointers: - /// - /// ``` - /// #![feature(set_ptr_value)] - /// # use core::fmt::Debug; - /// let mut arr: [i32; 3] = [1, 2, 3]; - /// let mut ptr = arr.as_mut_ptr() as *mut dyn Debug; - /// let thin = ptr as *mut u8; - /// unsafe { - /// ptr = thin.add(8).with_metadata_of(ptr); - /// # assert_eq!(*(ptr as *mut i32), 3); - /// println!("{:?}", &*ptr); // will print "3" - /// } - /// ``` - #[unstable(feature = "set_ptr_value", issue = "75091")] - #[rustc_const_unstable(feature = "set_ptr_value", issue = "75091")] - #[must_use = "returns a new pointer rather than modifying its argument"] - #[inline] - pub const fn with_metadata_of(self, meta: *const U) -> *mut U - where - U: ?Sized, - { - from_raw_parts_mut::(self as *mut (), metadata(meta)) - } - - /// Changes constness without changing the type. - /// - /// This is a bit safer than `as` because it wouldn't silently change the type if the code is - /// refactored. - /// - /// While not strictly required (`*mut T` coerces to `*const T`), this is provided for symmetry - /// with [`cast_mut`] on `*const T` and may have documentation value if used instead of implicit - /// coercion. - /// - /// [`cast_mut`]: pointer::cast_mut - #[stable(feature = "ptr_const_cast", since = "1.65.0")] - #[rustc_const_stable(feature = "ptr_const_cast", since = "1.65.0")] - #[rustc_diagnostic_item = "ptr_cast_const"] - #[inline(always)] - pub const fn cast_const(self) -> *const T { - self as _ - } - - /// Casts a pointer to its raw bits. - /// - /// This is equivalent to `as usize`, but is more specific to enhance readability. - /// The inverse method is [`from_bits`](pointer#method.from_bits-1). - /// - /// In particular, `*p as usize` and `p as usize` will both compile for - /// pointers to numeric types but do very different things, so using this - /// helps emphasize that reading the bits was intentional. - /// - /// # Examples - /// - /// ``` - /// #![feature(ptr_to_from_bits)] - /// # #[cfg(not(miri))] { // doctest does not work with strict provenance - /// let mut array = [13, 42]; - /// let mut it = array.iter_mut(); - /// let p0: *mut i32 = it.next().unwrap(); - /// assert_eq!(<*mut _>::from_bits(p0.to_bits()), p0); - /// let p1: *mut i32 = it.next().unwrap(); - /// assert_eq!(p1.to_bits() - p0.to_bits(), 4); - /// } - /// ``` - #[unstable(feature = "ptr_to_from_bits", issue = "91126")] - #[deprecated( - since = "1.67.0", - note = "replaced by the `expose_provenance` method, or update your code \ - to follow the strict provenance rules using its APIs" - )] - #[inline(always)] - pub fn to_bits(self) -> usize - where - T: Sized, - { - self as usize - } - - /// Creates a pointer from its raw bits. - /// - /// This is equivalent to `as *mut T`, but is more specific to enhance readability. - /// The inverse method is [`to_bits`](pointer#method.to_bits-1). - /// - /// # Examples - /// - /// ``` - /// #![feature(ptr_to_from_bits)] - /// # #[cfg(not(miri))] { // doctest does not work with strict provenance - /// use std::ptr::NonNull; - /// let dangling: *mut u8 = NonNull::dangling().as_ptr(); - /// assert_eq!(<*mut u8>::from_bits(1), dangling); - /// } - /// ``` - #[unstable(feature = "ptr_to_from_bits", issue = "91126")] - #[deprecated( - since = "1.67.0", - note = "replaced by the `ptr::with_exposed_provenance_mut` function, or \ - update your code to follow the strict provenance rules using its APIs" - )] - #[allow(fuzzy_provenance_casts)] // this is an unstable and semi-deprecated cast function - #[inline(always)] - pub fn from_bits(bits: usize) -> Self - where - T: Sized, - { - bits as Self - } - - /// Gets the "address" portion of the pointer. - /// - /// This is similar to `self as usize`, which semantically discards *provenance* and - /// *address-space* information. However, unlike `self as usize`, casting the returned address - /// back to a pointer yields a [pointer without provenance][without_provenance_mut], which is undefined - /// behavior to dereference. To properly restore the lost information and obtain a - /// dereferenceable pointer, use [`with_addr`][pointer::with_addr] or - /// [`map_addr`][pointer::map_addr]. - /// - /// If using those APIs is not possible because there is no way to preserve a pointer with the - /// required provenance, then Strict Provenance might not be for you. Use pointer-integer casts - /// or [`expose_provenance`][pointer::expose_provenance] and [`with_exposed_provenance`][with_exposed_provenance] - /// instead. However, note that this makes your code less portable and less amenable to tools - /// that check for compliance with the Rust memory model. - /// - /// On most platforms this will produce a value with the same bytes as the original - /// pointer, because all the bytes are dedicated to describing the address. - /// Platforms which need to store additional information in the pointer may - /// perform a change of representation to produce a value containing only the address - /// portion of the pointer. What that means is up to the platform to define. - /// - /// This API and its claimed semantics are part of the Strict Provenance experiment, and as such - /// might change in the future (including possibly weakening this so it becomes wholly - /// equivalent to `self as usize`). See the [module documentation][crate::ptr] for details. - #[must_use] - #[inline(always)] - #[unstable(feature = "strict_provenance", issue = "95228")] - pub fn addr(self) -> usize { - // FIXME(strict_provenance_magic): I am magic and should be a compiler intrinsic. - // SAFETY: Pointer-to-integer transmutes are valid (if you are okay with losing the - // provenance). - unsafe { mem::transmute(self.cast::<()>()) } - } - - /// Exposes the "provenance" part of the pointer for future use in - /// [`with_exposed_provenance`][] and returns the "address" portion. - /// - /// This is equivalent to `self as usize`, which semantically discards *provenance* and - /// *address-space* information. Furthermore, this (like the `as` cast) has the implicit - /// side-effect of marking the provenance as 'exposed', so on platforms that support it you can - /// later call [`with_exposed_provenance_mut`][] to reconstitute the original pointer including its - /// provenance. (Reconstructing address space information, if required, is your responsibility.) - /// - /// Using this method means that code is *not* following [Strict - /// Provenance][super#strict-provenance] rules. Supporting - /// [`with_exposed_provenance_mut`][] complicates specification and reasoning and may not be supported - /// by tools that help you to stay conformant with the Rust memory model, so it is recommended - /// to use [`addr`][pointer::addr] wherever possible. - /// - /// On most platforms this will produce a value with the same bytes as the original pointer, - /// because all the bytes are dedicated to describing the address. Platforms which need to store - /// additional information in the pointer may not support this operation, since the 'expose' - /// side-effect which is required for [`with_exposed_provenance_mut`][] to work is typically not - /// available. - /// - /// It is unclear whether this method can be given a satisfying unambiguous specification. This - /// API and its claimed semantics are part of [Exposed Provenance][super#exposed-provenance]. - /// - /// [`with_exposed_provenance_mut`]: with_exposed_provenance_mut - #[inline(always)] - #[unstable(feature = "exposed_provenance", issue = "95228")] - pub fn expose_provenance(self) -> usize { - // FIXME(strict_provenance_magic): I am magic and should be a compiler intrinsic. - self.cast::<()>() as usize - } - - /// Creates a new pointer with the given address. - /// - /// This performs the same operation as an `addr as ptr` cast, but copies - /// the *address-space* and *provenance* of `self` to the new pointer. - /// This allows us to dynamically preserve and propagate this important - /// information in a way that is otherwise impossible with a unary cast. - /// - /// This is equivalent to using [`wrapping_offset`][pointer::wrapping_offset] to offset - /// `self` to the given address, and therefore has all the same capabilities and restrictions. - /// - /// This API and its claimed semantics are an extension to the Strict Provenance experiment, - /// see the [module documentation][crate::ptr] for details. - #[must_use] - #[inline] - #[unstable(feature = "strict_provenance", issue = "95228")] - pub fn with_addr(self, addr: usize) -> Self { - // FIXME(strict_provenance_magic): I am magic and should be a compiler intrinsic. - // - // In the mean-time, this operation is defined to be "as if" it was - // a wrapping_offset, so we can emulate it as such. This should properly - // restore pointer provenance even under today's compiler. - let self_addr = self.addr() as isize; - let dest_addr = addr as isize; - let offset = dest_addr.wrapping_sub(self_addr); - - // This is the canonical desugaring of this operation - self.wrapping_byte_offset(offset) - } - - /// Creates a new pointer by mapping `self`'s address to a new one. - /// - /// This is a convenience for [`with_addr`][pointer::with_addr], see that method for details. - /// - /// This API and its claimed semantics are part of the Strict Provenance experiment, - /// see the [module documentation][crate::ptr] for details. - #[must_use] - #[inline] - #[unstable(feature = "strict_provenance", issue = "95228")] - pub fn map_addr(self, f: impl FnOnce(usize) -> usize) -> Self { - self.with_addr(f(self.addr())) - } - - /// Decompose a (possibly wide) pointer into its data pointer and metadata components. - /// - /// The pointer can be later reconstructed with [`from_raw_parts_mut`]. - #[unstable(feature = "ptr_metadata", issue = "81513")] - #[rustc_const_unstable(feature = "ptr_metadata", issue = "81513")] - #[inline] - pub const fn to_raw_parts(self) -> (*mut (), ::Metadata) { - (self.cast(), super::metadata(self)) - } - - /// Returns `None` if the pointer is null, or else returns a shared reference to - /// the value wrapped in `Some`. If the value may be uninitialized, [`as_uninit_ref`] - /// must be used instead. - /// - /// For the mutable counterpart see [`as_mut`]. - /// - /// [`as_uninit_ref`]: pointer#method.as_uninit_ref-1 - /// [`as_mut`]: #method.as_mut - /// - /// # Safety - /// - /// When calling this method, you have to ensure that *either* the pointer is null *or* - /// all of the following is true: - /// - /// * The pointer must be properly aligned. - /// - /// * It must be "dereferenceable" in the sense defined in [the module documentation]. - /// - /// * The pointer must point to an initialized instance of `T`. - /// - /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is - /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. - /// In particular, while this reference exists, the memory the pointer points to must - /// not get mutated (except inside `UnsafeCell`). - /// - /// This applies even if the result of this method is unused! - /// (The part about being initialized is not yet fully decided, but until - /// it is, the only safe approach is to ensure that they are indeed initialized.) - /// - /// [the module documentation]: crate::ptr#safety - /// - /// # Examples - /// - /// ``` - /// let ptr: *mut u8 = &mut 10u8 as *mut u8; - /// - /// unsafe { - /// if let Some(val_back) = ptr.as_ref() { - /// println!("We got back the value: {val_back}!"); - /// } - /// } - /// ``` - /// - /// # Null-unchecked version - /// - /// If you are sure the pointer can never be null and are looking for some kind of - /// `as_ref_unchecked` that returns the `&T` instead of `Option<&T>`, know that you can - /// dereference the pointer directly. - /// - /// ``` - /// let ptr: *mut u8 = &mut 10u8 as *mut u8; - /// - /// unsafe { - /// let val_back = &*ptr; - /// println!("We got back the value: {val_back}!"); - /// } - /// ``` - #[stable(feature = "ptr_as_ref", since = "1.9.0")] - #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")] - #[inline] - pub const unsafe fn as_ref<'a>(self) -> Option<&'a T> { - // SAFETY: the caller must guarantee that `self` is valid for a - // reference if it isn't null. - if self.is_null() { None } else { unsafe { Some(&*self) } } - } - - /// Returns a shared reference to the value behind the pointer. - /// If the pointer may be null or the value may be uninitialized, [`as_uninit_ref`] must be used instead. - /// If the pointer may be null, but the value is known to have been initialized, [`as_ref`] must be used instead. - /// - /// For the mutable counterpart see [`as_mut_unchecked`]. - /// - /// [`as_ref`]: #method.as_ref - /// [`as_uninit_ref`]: #method.as_uninit_ref - /// [`as_mut_unchecked`]: #method.as_mut_unchecked - /// - /// # Safety - /// - /// When calling this method, you have to ensure that all of the following is true: - /// - /// * The pointer must be properly aligned. - /// - /// * It must be "dereferenceable" in the sense defined in [the module documentation]. - /// - /// * The pointer must point to an initialized instance of `T`. - /// - /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is - /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. - /// In particular, while this reference exists, the memory the pointer points to must - /// not get mutated (except inside `UnsafeCell`). - /// - /// This applies even if the result of this method is unused! - /// (The part about being initialized is not yet fully decided, but until - /// it is, the only safe approach is to ensure that they are indeed initialized.) - /// - /// [the module documentation]: crate::ptr#safety - /// - /// # Examples - /// - /// ``` - /// #![feature(ptr_as_ref_unchecked)] - /// let ptr: *mut u8 = &mut 10u8 as *mut u8; - /// - /// unsafe { - /// println!("We got back the value: {}!", ptr.as_ref_unchecked()); - /// } - /// ``` - // FIXME: mention it in the docs for `as_ref` and `as_uninit_ref` once stabilized. - #[unstable(feature = "ptr_as_ref_unchecked", issue = "122034")] - #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")] - #[inline] - #[must_use] - pub const unsafe fn as_ref_unchecked<'a>(self) -> &'a T { - // SAFETY: the caller must guarantee that `self` is valid for a reference - unsafe { &*self } - } - - /// Returns `None` if the pointer is null, or else returns a shared reference to - /// the value wrapped in `Some`. In contrast to [`as_ref`], this does not require - /// that the value has to be initialized. - /// - /// For the mutable counterpart see [`as_uninit_mut`]. - /// - /// [`as_ref`]: pointer#method.as_ref-1 - /// [`as_uninit_mut`]: #method.as_uninit_mut - /// - /// # Safety - /// - /// When calling this method, you have to ensure that *either* the pointer is null *or* - /// all of the following is true: - /// - /// * The pointer must be properly aligned. - /// - /// * It must be "dereferenceable" in the sense defined in [the module documentation]. - /// - /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is - /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. - /// In particular, while this reference exists, the memory the pointer points to must - /// not get mutated (except inside `UnsafeCell`). - /// - /// This applies even if the result of this method is unused! - /// - /// [the module documentation]: crate::ptr#safety - /// - /// # Examples - /// - /// ``` - /// #![feature(ptr_as_uninit)] - /// - /// let ptr: *mut u8 = &mut 10u8 as *mut u8; - /// - /// unsafe { - /// if let Some(val_back) = ptr.as_uninit_ref() { - /// println!("We got back the value: {}!", val_back.assume_init()); - /// } - /// } - /// ``` - #[inline] - #[unstable(feature = "ptr_as_uninit", issue = "75402")] - #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")] - pub const unsafe fn as_uninit_ref<'a>(self) -> Option<&'a MaybeUninit> - where - T: Sized, - { - // SAFETY: the caller must guarantee that `self` meets all the - // requirements for a reference. - if self.is_null() { None } else { Some(unsafe { &*(self as *const MaybeUninit) }) } - } - - /// Calculates the offset from a pointer. - /// - /// `count` is in units of T; e.g., a `count` of 3 represents a pointer - /// offset of `3 * size_of::()` bytes. - /// - /// # Safety - /// - /// If any of the following conditions are violated, the result is Undefined - /// Behavior: - /// - /// * If the computed offset, **in bytes**, is non-zero, then both the starting and resulting - /// pointer must be either in bounds or at the end of the same [allocated object]. - /// (If it is zero, then the function is always well-defined.) - /// - /// * The computed offset, **in bytes**, cannot overflow an `isize`. - /// - /// * The offset being in bounds cannot rely on "wrapping around" the address - /// space. That is, the infinite-precision sum, **in bytes** must fit in a usize. - /// - /// The compiler and standard library generally tries to ensure allocations - /// never reach a size where an offset is a concern. For instance, `Vec` - /// and `Box` ensure they never allocate more than `isize::MAX` bytes, so - /// `vec.as_ptr().add(vec.len())` is always safe. - /// - /// Most platforms fundamentally can't even construct such an allocation. - /// For instance, no known 64-bit platform can ever serve a request - /// for 263 bytes due to page-table limitations or splitting the address space. - /// However, some 32-bit and 16-bit platforms may successfully serve a request for - /// more than `isize::MAX` bytes with things like Physical Address - /// Extension. As such, memory acquired directly from allocators or memory - /// mapped files *may* be too large to handle with this function. - /// - /// Consider using [`wrapping_offset`] instead if these constraints are - /// difficult to satisfy. The only advantage of this method is that it - /// enables more aggressive compiler optimizations. - /// - /// [`wrapping_offset`]: #method.wrapping_offset - /// [allocated object]: crate::ptr#allocated-object - /// - /// # Examples - /// - /// ``` - /// let mut s = [1, 2, 3]; - /// let ptr: *mut u32 = s.as_mut_ptr(); - /// - /// unsafe { - /// assert_eq!(2, *ptr.offset(1)); - /// assert_eq!(3, *ptr.offset(2)); - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use = "returns a new pointer rather than modifying its argument"] - #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn offset(self, count: isize) -> *mut T - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `offset`. - // The obtained pointer is valid for writes since the caller must - // guarantee that it points to the same allocated object as `self`. - unsafe { intrinsics::offset(self, count) } - } - - /// Calculates the offset from a pointer in bytes. - /// - /// `count` is in units of **bytes**. - /// - /// This is purely a convenience for casting to a `u8` pointer and - /// using [offset][pointer::offset] on it. See that method for documentation - /// and safety requirements. - /// - /// For non-`Sized` pointees this operation changes only the data pointer, - /// leaving the metadata untouched. - #[must_use] - #[inline(always)] - #[stable(feature = "pointer_byte_offsets", since = "1.75.0")] - #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")] - #[rustc_allow_const_fn_unstable(set_ptr_value)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn byte_offset(self, count: isize) -> Self { - // SAFETY: the caller must uphold the safety contract for `offset`. - unsafe { self.cast::().offset(count).with_metadata_of(self) } - } - - /// Calculates the offset from a pointer using wrapping arithmetic. - /// `count` is in units of T; e.g., a `count` of 3 represents a pointer - /// offset of `3 * size_of::()` bytes. - /// - /// # Safety - /// - /// This operation itself is always safe, but using the resulting pointer is not. - /// - /// The resulting pointer "remembers" the [allocated object] that `self` points to; it must not - /// be used to read or write other allocated objects. - /// - /// In other words, `let z = x.wrapping_offset((y as isize) - (x as isize))` does *not* make `z` - /// the same as `y` even if we assume `T` has size `1` and there is no overflow: `z` is still - /// attached to the object `x` is attached to, and dereferencing it is Undefined Behavior unless - /// `x` and `y` point into the same allocated object. - /// - /// Compared to [`offset`], this method basically delays the requirement of staying within the - /// same allocated object: [`offset`] is immediate Undefined Behavior when crossing object - /// boundaries; `wrapping_offset` produces a pointer but still leads to Undefined Behavior if a - /// pointer is dereferenced when it is out-of-bounds of the object it is attached to. [`offset`] - /// can be optimized better and is thus preferable in performance-sensitive code. - /// - /// The delayed check only considers the value of the pointer that was dereferenced, not the - /// intermediate values used during the computation of the final result. For example, - /// `x.wrapping_offset(o).wrapping_offset(o.wrapping_neg())` is always the same as `x`. In other - /// words, leaving the allocated object and then re-entering it later is permitted. - /// - /// [`offset`]: #method.offset - /// [allocated object]: crate::ptr#allocated-object - /// - /// # Examples - /// - /// ``` - /// // Iterate using a raw pointer in increments of two elements - /// let mut data = [1u8, 2, 3, 4, 5]; - /// let mut ptr: *mut u8 = data.as_mut_ptr(); - /// let step = 2; - /// let end_rounded_up = ptr.wrapping_offset(6); - /// - /// while ptr != end_rounded_up { - /// unsafe { - /// *ptr = 0; - /// } - /// ptr = ptr.wrapping_offset(step); - /// } - /// assert_eq!(&data, &[0, 2, 0, 4, 0]); - /// ``` - #[stable(feature = "ptr_wrapping_offset", since = "1.16.0")] - #[must_use = "returns a new pointer rather than modifying its argument"] - #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")] - #[inline(always)] - pub const fn wrapping_offset(self, count: isize) -> *mut T - where - T: Sized, - { - // SAFETY: the `arith_offset` intrinsic has no prerequisites to be called. - unsafe { intrinsics::arith_offset(self, count) as *mut T } - } - - /// Calculates the offset from a pointer in bytes using wrapping arithmetic. - /// - /// `count` is in units of **bytes**. - /// - /// This is purely a convenience for casting to a `u8` pointer and - /// using [wrapping_offset][pointer::wrapping_offset] on it. See that method - /// for documentation. - /// - /// For non-`Sized` pointees this operation changes only the data pointer, - /// leaving the metadata untouched. - #[must_use] - #[inline(always)] - #[stable(feature = "pointer_byte_offsets", since = "1.75.0")] - #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")] - #[rustc_allow_const_fn_unstable(set_ptr_value)] - pub const fn wrapping_byte_offset(self, count: isize) -> Self { - self.cast::().wrapping_offset(count).with_metadata_of(self) - } - - /// Masks out bits of the pointer according to a mask. - /// - /// This is convenience for `ptr.map_addr(|a| a & mask)`. - /// - /// For non-`Sized` pointees this operation changes only the data pointer, - /// leaving the metadata untouched. - /// - /// ## Examples - /// - /// ``` - /// #![feature(ptr_mask, strict_provenance)] - /// let mut v = 17_u32; - /// let ptr: *mut u32 = &mut v; - /// - /// // `u32` is 4 bytes aligned, - /// // which means that lower 2 bits are always 0. - /// let tag_mask = 0b11; - /// let ptr_mask = !tag_mask; - /// - /// // We can store something in these lower bits - /// let tagged_ptr = ptr.map_addr(|a| a | 0b10); - /// - /// // Get the "tag" back - /// let tag = tagged_ptr.addr() & tag_mask; - /// assert_eq!(tag, 0b10); - /// - /// // Note that `tagged_ptr` is unaligned, it's UB to read from/write to it. - /// // To get original pointer `mask` can be used: - /// let masked_ptr = tagged_ptr.mask(ptr_mask); - /// assert_eq!(unsafe { *masked_ptr }, 17); - /// - /// unsafe { *masked_ptr = 0 }; - /// assert_eq!(v, 0); - /// ``` - #[unstable(feature = "ptr_mask", issue = "98290")] - #[must_use = "returns a new pointer rather than modifying its argument"] - #[inline(always)] - pub fn mask(self, mask: usize) -> *mut T { - intrinsics::ptr_mask(self.cast::<()>(), mask).cast_mut().with_metadata_of(self) - } - - /// Returns `None` if the pointer is null, or else returns a unique reference to - /// the value wrapped in `Some`. If the value may be uninitialized, [`as_uninit_mut`] - /// must be used instead. - /// - /// For the shared counterpart see [`as_ref`]. - /// - /// [`as_uninit_mut`]: #method.as_uninit_mut - /// [`as_ref`]: pointer#method.as_ref-1 - /// - /// # Safety - /// - /// When calling this method, you have to ensure that *either* the pointer is null *or* - /// all of the following is true: - /// - /// * The pointer must be properly aligned. - /// - /// * It must be "dereferenceable" in the sense defined in [the module documentation]. - /// - /// * The pointer must point to an initialized instance of `T`. - /// - /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is - /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. - /// In particular, while this reference exists, the memory the pointer points to must - /// not get accessed (read or written) through any other pointer. - /// - /// This applies even if the result of this method is unused! - /// (The part about being initialized is not yet fully decided, but until - /// it is, the only safe approach is to ensure that they are indeed initialized.) - /// - /// [the module documentation]: crate::ptr#safety - /// - /// # Examples - /// - /// ``` - /// let mut s = [1, 2, 3]; - /// let ptr: *mut u32 = s.as_mut_ptr(); - /// let first_value = unsafe { ptr.as_mut().unwrap() }; - /// *first_value = 4; - /// # assert_eq!(s, [4, 2, 3]); - /// println!("{s:?}"); // It'll print: "[4, 2, 3]". - /// ``` - /// - /// # Null-unchecked version - /// - /// If you are sure the pointer can never be null and are looking for some kind of - /// `as_mut_unchecked` that returns the `&mut T` instead of `Option<&mut T>`, know that - /// you can dereference the pointer directly. - /// - /// ``` - /// let mut s = [1, 2, 3]; - /// let ptr: *mut u32 = s.as_mut_ptr(); - /// let first_value = unsafe { &mut *ptr }; - /// *first_value = 4; - /// # assert_eq!(s, [4, 2, 3]); - /// println!("{s:?}"); // It'll print: "[4, 2, 3]". - /// ``` - #[stable(feature = "ptr_as_ref", since = "1.9.0")] - #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")] - #[inline] - pub const unsafe fn as_mut<'a>(self) -> Option<&'a mut T> { - // SAFETY: the caller must guarantee that `self` is be valid for - // a mutable reference if it isn't null. - if self.is_null() { None } else { unsafe { Some(&mut *self) } } - } - - /// Returns a unique reference to the value behind the pointer. - /// If the pointer may be null or the value may be uninitialized, [`as_uninit_mut`] must be used instead. - /// If the pointer may be null, but the value is known to have been initialized, [`as_mut`] must be used instead. - /// - /// For the shared counterpart see [`as_ref_unchecked`]. - /// - /// [`as_mut`]: #method.as_mut - /// [`as_uninit_mut`]: #method.as_uninit_mut - /// [`as_ref_unchecked`]: #method.as_mut_unchecked - /// - /// # Safety - /// - /// When calling this method, you have to ensure that all of the following is true: - /// - /// * The pointer must be properly aligned. - /// - /// * It must be "dereferenceable" in the sense defined in [the module documentation]. - /// - /// * The pointer must point to an initialized instance of `T`. - /// - /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is - /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. - /// In particular, while this reference exists, the memory the pointer points to must - /// not get mutated (except inside `UnsafeCell`). - /// - /// This applies even if the result of this method is unused! - /// (The part about being initialized is not yet fully decided, but until - /// it is, the only safe approach is to ensure that they are indeed initialized.) - /// - /// [the module documentation]: crate::ptr#safety - /// - /// # Examples - /// - /// ``` - /// #![feature(ptr_as_ref_unchecked)] - /// let mut s = [1, 2, 3]; - /// let ptr: *mut u32 = s.as_mut_ptr(); - /// let first_value = unsafe { ptr.as_mut_unchecked() }; - /// *first_value = 4; - /// # assert_eq!(s, [4, 2, 3]); - /// println!("{s:?}"); // It'll print: "[4, 2, 3]". - /// ``` - // FIXME: mention it in the docs for `as_mut` and `as_uninit_mut` once stabilized. - #[unstable(feature = "ptr_as_ref_unchecked", issue = "122034")] - #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")] - #[inline] - #[must_use] - pub const unsafe fn as_mut_unchecked<'a>(self) -> &'a mut T { - // SAFETY: the caller must guarantee that `self` is valid for a reference - unsafe { &mut *self } - } - - /// Returns `None` if the pointer is null, or else returns a unique reference to - /// the value wrapped in `Some`. In contrast to [`as_mut`], this does not require - /// that the value has to be initialized. - /// - /// For the shared counterpart see [`as_uninit_ref`]. - /// - /// [`as_mut`]: #method.as_mut - /// [`as_uninit_ref`]: pointer#method.as_uninit_ref-1 - /// - /// # Safety - /// - /// When calling this method, you have to ensure that *either* the pointer is null *or* - /// all of the following is true: - /// - /// * The pointer must be properly aligned. - /// - /// * It must be "dereferenceable" in the sense defined in [the module documentation]. - /// - /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is - /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. - /// In particular, while this reference exists, the memory the pointer points to must - /// not get accessed (read or written) through any other pointer. - /// - /// This applies even if the result of this method is unused! - /// - /// [the module documentation]: crate::ptr#safety - #[inline] - #[unstable(feature = "ptr_as_uninit", issue = "75402")] - #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")] - pub const unsafe fn as_uninit_mut<'a>(self) -> Option<&'a mut MaybeUninit> - where - T: Sized, - { - // SAFETY: the caller must guarantee that `self` meets all the - // requirements for a reference. - if self.is_null() { None } else { Some(unsafe { &mut *(self as *mut MaybeUninit) }) } - } - - /// Returns whether two pointers are guaranteed to be equal. - /// - /// At runtime this function behaves like `Some(self == other)`. - /// However, in some contexts (e.g., compile-time evaluation), - /// it is not always possible to determine equality of two pointers, so this function may - /// spuriously return `None` for pointers that later actually turn out to have its equality known. - /// But when it returns `Some`, the pointers' equality is guaranteed to be known. - /// - /// The return value may change from `Some` to `None` and vice versa depending on the compiler - /// version and unsafe code must not - /// rely on the result of this function for soundness. It is suggested to only use this function - /// for performance optimizations where spurious `None` return values by this function do not - /// affect the outcome, but just the performance. - /// The consequences of using this method to make runtime and compile-time code behave - /// differently have not been explored. This method should not be used to introduce such - /// differences, and it should also not be stabilized before we have a better understanding - /// of this issue. - #[unstable(feature = "const_raw_ptr_comparison", issue = "53020")] - #[rustc_const_unstable(feature = "const_raw_ptr_comparison", issue = "53020")] - #[inline] - pub const fn guaranteed_eq(self, other: *mut T) -> Option - where - T: Sized, - { - (self as *const T).guaranteed_eq(other as _) - } - - /// Returns whether two pointers are guaranteed to be inequal. - /// - /// At runtime this function behaves like `Some(self != other)`. - /// However, in some contexts (e.g., compile-time evaluation), - /// it is not always possible to determine inequality of two pointers, so this function may - /// spuriously return `None` for pointers that later actually turn out to have its inequality known. - /// But when it returns `Some`, the pointers' inequality is guaranteed to be known. - /// - /// The return value may change from `Some` to `None` and vice versa depending on the compiler - /// version and unsafe code must not - /// rely on the result of this function for soundness. It is suggested to only use this function - /// for performance optimizations where spurious `None` return values by this function do not - /// affect the outcome, but just the performance. - /// The consequences of using this method to make runtime and compile-time code behave - /// differently have not been explored. This method should not be used to introduce such - /// differences, and it should also not be stabilized before we have a better understanding - /// of this issue. - #[unstable(feature = "const_raw_ptr_comparison", issue = "53020")] - #[rustc_const_unstable(feature = "const_raw_ptr_comparison", issue = "53020")] - #[inline] - pub const fn guaranteed_ne(self, other: *mut T) -> Option - where - T: Sized, - { - (self as *const T).guaranteed_ne(other as _) - } - - /// Calculates the distance between two pointers. The returned value is in - /// units of T: the distance in bytes divided by `mem::size_of::()`. - /// - /// This is equivalent to `(self as isize - origin as isize) / (mem::size_of::() as isize)`, - /// except that it has a lot more opportunities for UB, in exchange for the compiler - /// better understanding what you are doing. - /// - /// The primary motivation of this method is for computing the `len` of an array/slice - /// of `T` that you are currently representing as a "start" and "end" pointer - /// (and "end" is "one past the end" of the array). - /// In that case, `end.offset_from(start)` gets you the length of the array. - /// - /// All of the following safety requirements are trivially satisfied for this usecase. - /// - /// [`offset`]: pointer#method.offset-1 - /// - /// # Safety - /// - /// If any of the following conditions are violated, the result is Undefined - /// Behavior: - /// - /// * `self` and `origin` must either - /// - /// * both be *derived from* a pointer to the same [allocated object], and the memory range between - /// the two pointers must be either empty or in bounds of that object. (See below for an example.) - /// * or both be derived from an integer literal/constant, and point to the same address. - /// - /// * The distance between the pointers, in bytes, must be an exact multiple - /// of the size of `T`. - /// - /// * The distance between the pointers, **in bytes**, cannot overflow an `isize`. - /// - /// * The distance being in bounds cannot rely on "wrapping around" the address space. - /// - /// Rust types are never larger than `isize::MAX` and Rust allocations never wrap around the - /// address space, so two pointers within some value of any Rust type `T` will always satisfy - /// the last two conditions. The standard library also generally ensures that allocations - /// never reach a size where an offset is a concern. For instance, `Vec` and `Box` ensure they - /// never allocate more than `isize::MAX` bytes, so `ptr_into_vec.offset_from(vec.as_ptr())` - /// always satisfies the last two conditions. - /// - /// Most platforms fundamentally can't even construct such a large allocation. - /// For instance, no known 64-bit platform can ever serve a request - /// for 263 bytes due to page-table limitations or splitting the address space. - /// However, some 32-bit and 16-bit platforms may successfully serve a request for - /// more than `isize::MAX` bytes with things like Physical Address - /// Extension. As such, memory acquired directly from allocators or memory - /// mapped files *may* be too large to handle with this function. - /// (Note that [`offset`] and [`add`] also have a similar limitation and hence cannot be used on - /// such large allocations either.) - /// - /// The requirement for pointers to be derived from the same allocated object is primarily - /// needed for `const`-compatibility: the distance between pointers into *different* allocated - /// objects is not known at compile-time. However, the requirement also exists at - /// runtime and may be exploited by optimizations. If you wish to compute the difference between - /// pointers that are not guaranteed to be from the same allocation, use `(self as isize - - /// origin as isize) / mem::size_of::()`. - // FIXME: recommend `addr()` instead of `as usize` once that is stable. - /// - /// [`add`]: #method.add - /// [allocated object]: crate::ptr#allocated-object - /// - /// # Panics - /// - /// This function panics if `T` is a Zero-Sized Type ("ZST"). - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let mut a = [0; 5]; - /// let ptr1: *mut i32 = &mut a[1]; - /// let ptr2: *mut i32 = &mut a[3]; - /// unsafe { - /// assert_eq!(ptr2.offset_from(ptr1), 2); - /// assert_eq!(ptr1.offset_from(ptr2), -2); - /// assert_eq!(ptr1.offset(2), ptr2); - /// assert_eq!(ptr2.offset(-2), ptr1); - /// } - /// ``` - /// - /// *Incorrect* usage: - /// - /// ```rust,no_run - /// let ptr1 = Box::into_raw(Box::new(0u8)); - /// let ptr2 = Box::into_raw(Box::new(1u8)); - /// let diff = (ptr2 as isize).wrapping_sub(ptr1 as isize); - /// // Make ptr2_other an "alias" of ptr2, but derived from ptr1. - /// let ptr2_other = (ptr1 as *mut u8).wrapping_offset(diff); - /// assert_eq!(ptr2 as usize, ptr2_other as usize); - /// // Since ptr2_other and ptr2 are derived from pointers to different objects, - /// // computing their offset is undefined behavior, even though - /// // they point to the same address! - /// unsafe { - /// let zero = ptr2_other.offset_from(ptr2); // Undefined Behavior - /// } - /// ``` - #[stable(feature = "ptr_offset_from", since = "1.47.0")] - #[rustc_const_stable(feature = "const_ptr_offset_from", since = "1.65.0")] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn offset_from(self, origin: *const T) -> isize - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `offset_from`. - unsafe { (self as *const T).offset_from(origin) } - } - - /// Calculates the distance between two pointers. The returned value is in - /// units of **bytes**. - /// - /// This is purely a convenience for casting to a `u8` pointer and - /// using [`offset_from`][pointer::offset_from] on it. See that method for - /// documentation and safety requirements. - /// - /// For non-`Sized` pointees this operation considers only the data pointers, - /// ignoring the metadata. - #[inline(always)] - #[stable(feature = "pointer_byte_offsets", since = "1.75.0")] - #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")] - #[rustc_allow_const_fn_unstable(set_ptr_value)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn byte_offset_from(self, origin: *const U) -> isize { - // SAFETY: the caller must uphold the safety contract for `offset_from`. - unsafe { self.cast::().offset_from(origin.cast::()) } - } - - /// Calculates the distance between two pointers, *where it's known that - /// `self` is equal to or greater than `origin`*. The returned value is in - /// units of T: the distance in bytes is divided by `mem::size_of::()`. - /// - /// This computes the same value that [`offset_from`](#method.offset_from) - /// would compute, but with the added precondition that the offset is - /// guaranteed to be non-negative. This method is equivalent to - /// `usize::try_from(self.offset_from(origin)).unwrap_unchecked()`, - /// but it provides slightly more information to the optimizer, which can - /// sometimes allow it to optimize slightly better with some backends. - /// - /// This method can be though of as recovering the `count` that was passed - /// to [`add`](#method.add) (or, with the parameters in the other order, - /// to [`sub`](#method.sub)). The following are all equivalent, assuming - /// that their safety preconditions are met: - /// ```rust - /// # #![feature(ptr_sub_ptr)] - /// # unsafe fn blah(ptr: *mut i32, origin: *mut i32, count: usize) -> bool { - /// ptr.sub_ptr(origin) == count - /// # && - /// origin.add(count) == ptr - /// # && - /// ptr.sub(count) == origin - /// # } - /// ``` - /// - /// # Safety - /// - /// - The distance between the pointers must be non-negative (`self >= origin`) - /// - /// - *All* the safety conditions of [`offset_from`](#method.offset_from) - /// apply to this method as well; see it for the full details. - /// - /// Importantly, despite the return type of this method being able to represent - /// a larger offset, it's still *not permitted* to pass pointers which differ - /// by more than `isize::MAX` *bytes*. As such, the result of this method will - /// always be less than or equal to `isize::MAX as usize`. - /// - /// # Panics - /// - /// This function panics if `T` is a Zero-Sized Type ("ZST"). - /// - /// # Examples - /// - /// ``` - /// #![feature(ptr_sub_ptr)] - /// - /// let mut a = [0; 5]; - /// let p: *mut i32 = a.as_mut_ptr(); - /// unsafe { - /// let ptr1: *mut i32 = p.add(1); - /// let ptr2: *mut i32 = p.add(3); - /// - /// assert_eq!(ptr2.sub_ptr(ptr1), 2); - /// assert_eq!(ptr1.add(2), ptr2); - /// assert_eq!(ptr2.sub(2), ptr1); - /// assert_eq!(ptr2.sub_ptr(ptr2), 0); - /// } - /// - /// // This would be incorrect, as the pointers are not correctly ordered: - /// // ptr1.offset_from(ptr2) - #[unstable(feature = "ptr_sub_ptr", issue = "95892")] - #[rustc_const_unstable(feature = "const_ptr_sub_ptr", issue = "95892")] - #[inline] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn sub_ptr(self, origin: *const T) -> usize - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `sub_ptr`. - unsafe { (self as *const T).sub_ptr(origin) } - } - - /// Calculates the offset from a pointer (convenience for `.offset(count as isize)`). - /// - /// `count` is in units of T; e.g., a `count` of 3 represents a pointer - /// offset of `3 * size_of::()` bytes. - /// - /// # Safety - /// - /// If any of the following conditions are violated, the result is Undefined - /// Behavior: - /// - /// * If the computed offset, **in bytes**, is non-zero, then both the starting and resulting - /// pointer must be either in bounds or at the end of the same [allocated object]. - /// (If it is zero, then the function is always well-defined.) - /// - /// * The computed offset, **in bytes**, cannot overflow an `isize`. - /// - /// * The offset being in bounds cannot rely on "wrapping around" the address - /// space. That is, the infinite-precision sum must fit in a `usize`. - /// - /// The compiler and standard library generally tries to ensure allocations - /// never reach a size where an offset is a concern. For instance, `Vec` - /// and `Box` ensure they never allocate more than `isize::MAX` bytes, so - /// `vec.as_ptr().add(vec.len())` is always safe. - /// - /// Most platforms fundamentally can't even construct such an allocation. - /// For instance, no known 64-bit platform can ever serve a request - /// for 263 bytes due to page-table limitations or splitting the address space. - /// However, some 32-bit and 16-bit platforms may successfully serve a request for - /// more than `isize::MAX` bytes with things like Physical Address - /// Extension. As such, memory acquired directly from allocators or memory - /// mapped files *may* be too large to handle with this function. - /// - /// Consider using [`wrapping_add`] instead if these constraints are - /// difficult to satisfy. The only advantage of this method is that it - /// enables more aggressive compiler optimizations. - /// - /// [`wrapping_add`]: #method.wrapping_add - /// [allocated object]: crate::ptr#allocated-object - /// - /// # Examples - /// - /// ``` - /// let s: &str = "123"; - /// let ptr: *const u8 = s.as_ptr(); - /// - /// unsafe { - /// assert_eq!('2', *ptr.add(1) as char); - /// assert_eq!('3', *ptr.add(2) as char); - /// } - /// ``` - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[must_use = "returns a new pointer rather than modifying its argument"] - #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn add(self, count: usize) -> Self - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `offset`. - unsafe { intrinsics::offset(self, count) } - } - - /// Calculates the offset from a pointer in bytes (convenience for `.byte_offset(count as isize)`). - /// - /// `count` is in units of bytes. - /// - /// This is purely a convenience for casting to a `u8` pointer and - /// using [add][pointer::add] on it. See that method for documentation - /// and safety requirements. - /// - /// For non-`Sized` pointees this operation changes only the data pointer, - /// leaving the metadata untouched. - #[must_use] - #[inline(always)] - #[stable(feature = "pointer_byte_offsets", since = "1.75.0")] - #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")] - #[rustc_allow_const_fn_unstable(set_ptr_value)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn byte_add(self, count: usize) -> Self { - // SAFETY: the caller must uphold the safety contract for `add`. - unsafe { self.cast::().add(count).with_metadata_of(self) } - } - - /// Calculates the offset from a pointer (convenience for - /// `.offset((count as isize).wrapping_neg())`). - /// - /// `count` is in units of T; e.g., a `count` of 3 represents a pointer - /// offset of `3 * size_of::()` bytes. - /// - /// # Safety - /// - /// If any of the following conditions are violated, the result is Undefined - /// Behavior: - /// - /// * If the computed offset, **in bytes**, is non-zero, then both the starting and resulting - /// pointer must be either in bounds or at the end of the same [allocated object]. - /// (If it is zero, then the function is always well-defined.) - /// - /// * The computed offset cannot exceed `isize::MAX` **bytes**. - /// - /// * The offset being in bounds cannot rely on "wrapping around" the address - /// space. That is, the infinite-precision sum must fit in a usize. - /// - /// The compiler and standard library generally tries to ensure allocations - /// never reach a size where an offset is a concern. For instance, `Vec` - /// and `Box` ensure they never allocate more than `isize::MAX` bytes, so - /// `vec.as_ptr().add(vec.len()).sub(vec.len())` is always safe. - /// - /// Most platforms fundamentally can't even construct such an allocation. - /// For instance, no known 64-bit platform can ever serve a request - /// for 263 bytes due to page-table limitations or splitting the address space. - /// However, some 32-bit and 16-bit platforms may successfully serve a request for - /// more than `isize::MAX` bytes with things like Physical Address - /// Extension. As such, memory acquired directly from allocators or memory - /// mapped files *may* be too large to handle with this function. - /// - /// Consider using [`wrapping_sub`] instead if these constraints are - /// difficult to satisfy. The only advantage of this method is that it - /// enables more aggressive compiler optimizations. - /// - /// [`wrapping_sub`]: #method.wrapping_sub - /// [allocated object]: crate::ptr#allocated-object - /// - /// # Examples - /// - /// ``` - /// let s: &str = "123"; - /// - /// unsafe { - /// let end: *const u8 = s.as_ptr().add(3); - /// assert_eq!('3', *end.sub(1) as char); - /// assert_eq!('2', *end.sub(2) as char); - /// } - /// ``` - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[must_use = "returns a new pointer rather than modifying its argument"] - #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn sub(self, count: usize) -> Self - where - T: Sized, - { - if T::IS_ZST { - // Pointer arithmetic does nothing when the pointee is a ZST. - self - } else { - // SAFETY: the caller must uphold the safety contract for `offset`. - // Because the pointee is *not* a ZST, that means that `count` is - // at most `isize::MAX`, and thus the negation cannot overflow. - unsafe { self.offset(intrinsics::unchecked_sub(0, count as isize)) } - } - } - - /// Calculates the offset from a pointer in bytes (convenience for - /// `.byte_offset((count as isize).wrapping_neg())`). - /// - /// `count` is in units of bytes. - /// - /// This is purely a convenience for casting to a `u8` pointer and - /// using [sub][pointer::sub] on it. See that method for documentation - /// and safety requirements. - /// - /// For non-`Sized` pointees this operation changes only the data pointer, - /// leaving the metadata untouched. - #[must_use] - #[inline(always)] - #[stable(feature = "pointer_byte_offsets", since = "1.75.0")] - #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")] - #[rustc_allow_const_fn_unstable(set_ptr_value)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn byte_sub(self, count: usize) -> Self { - // SAFETY: the caller must uphold the safety contract for `sub`. - unsafe { self.cast::().sub(count).with_metadata_of(self) } - } - - /// Calculates the offset from a pointer using wrapping arithmetic. - /// (convenience for `.wrapping_offset(count as isize)`) - /// - /// `count` is in units of T; e.g., a `count` of 3 represents a pointer - /// offset of `3 * size_of::()` bytes. - /// - /// # Safety - /// - /// This operation itself is always safe, but using the resulting pointer is not. - /// - /// The resulting pointer "remembers" the [allocated object] that `self` points to; it must not - /// be used to read or write other allocated objects. - /// - /// In other words, `let z = x.wrapping_add((y as usize) - (x as usize))` does *not* make `z` - /// the same as `y` even if we assume `T` has size `1` and there is no overflow: `z` is still - /// attached to the object `x` is attached to, and dereferencing it is Undefined Behavior unless - /// `x` and `y` point into the same allocated object. - /// - /// Compared to [`add`], this method basically delays the requirement of staying within the - /// same allocated object: [`add`] is immediate Undefined Behavior when crossing object - /// boundaries; `wrapping_add` produces a pointer but still leads to Undefined Behavior if a - /// pointer is dereferenced when it is out-of-bounds of the object it is attached to. [`add`] - /// can be optimized better and is thus preferable in performance-sensitive code. - /// - /// The delayed check only considers the value of the pointer that was dereferenced, not the - /// intermediate values used during the computation of the final result. For example, - /// `x.wrapping_add(o).wrapping_sub(o)` is always the same as `x`. In other words, leaving the - /// allocated object and then re-entering it later is permitted. - /// - /// [`add`]: #method.add - /// [allocated object]: crate::ptr#allocated-object - /// - /// # Examples - /// - /// ``` - /// // Iterate using a raw pointer in increments of two elements - /// let data = [1u8, 2, 3, 4, 5]; - /// let mut ptr: *const u8 = data.as_ptr(); - /// let step = 2; - /// let end_rounded_up = ptr.wrapping_add(6); - /// - /// // This loop prints "1, 3, 5, " - /// while ptr != end_rounded_up { - /// unsafe { - /// print!("{}, ", *ptr); - /// } - /// ptr = ptr.wrapping_add(step); - /// } - /// ``` - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[must_use = "returns a new pointer rather than modifying its argument"] - #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")] - #[inline(always)] - pub const fn wrapping_add(self, count: usize) -> Self - where - T: Sized, - { - self.wrapping_offset(count as isize) - } - - /// Calculates the offset from a pointer in bytes using wrapping arithmetic. - /// (convenience for `.wrapping_byte_offset(count as isize)`) - /// - /// `count` is in units of bytes. - /// - /// This is purely a convenience for casting to a `u8` pointer and - /// using [wrapping_add][pointer::wrapping_add] on it. See that method for documentation. - /// - /// For non-`Sized` pointees this operation changes only the data pointer, - /// leaving the metadata untouched. - #[must_use] - #[inline(always)] - #[stable(feature = "pointer_byte_offsets", since = "1.75.0")] - #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")] - #[rustc_allow_const_fn_unstable(set_ptr_value)] - pub const fn wrapping_byte_add(self, count: usize) -> Self { - self.cast::().wrapping_add(count).with_metadata_of(self) - } - - /// Calculates the offset from a pointer using wrapping arithmetic. - /// (convenience for `.wrapping_offset((count as isize).wrapping_neg())`) - /// - /// `count` is in units of T; e.g., a `count` of 3 represents a pointer - /// offset of `3 * size_of::()` bytes. - /// - /// # Safety - /// - /// This operation itself is always safe, but using the resulting pointer is not. - /// - /// The resulting pointer "remembers" the [allocated object] that `self` points to; it must not - /// be used to read or write other allocated objects. - /// - /// In other words, `let z = x.wrapping_sub((x as usize) - (y as usize))` does *not* make `z` - /// the same as `y` even if we assume `T` has size `1` and there is no overflow: `z` is still - /// attached to the object `x` is attached to, and dereferencing it is Undefined Behavior unless - /// `x` and `y` point into the same allocated object. - /// - /// Compared to [`sub`], this method basically delays the requirement of staying within the - /// same allocated object: [`sub`] is immediate Undefined Behavior when crossing object - /// boundaries; `wrapping_sub` produces a pointer but still leads to Undefined Behavior if a - /// pointer is dereferenced when it is out-of-bounds of the object it is attached to. [`sub`] - /// can be optimized better and is thus preferable in performance-sensitive code. - /// - /// The delayed check only considers the value of the pointer that was dereferenced, not the - /// intermediate values used during the computation of the final result. For example, - /// `x.wrapping_add(o).wrapping_sub(o)` is always the same as `x`. In other words, leaving the - /// allocated object and then re-entering it later is permitted. - /// - /// [`sub`]: #method.sub - /// [allocated object]: crate::ptr#allocated-object - /// - /// # Examples - /// - /// ``` - /// // Iterate using a raw pointer in increments of two elements (backwards) - /// let data = [1u8, 2, 3, 4, 5]; - /// let mut ptr: *const u8 = data.as_ptr(); - /// let start_rounded_down = ptr.wrapping_sub(2); - /// ptr = ptr.wrapping_add(4); - /// let step = 2; - /// // This loop prints "5, 3, 1, " - /// while ptr != start_rounded_down { - /// unsafe { - /// print!("{}, ", *ptr); - /// } - /// ptr = ptr.wrapping_sub(step); - /// } - /// ``` - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[must_use = "returns a new pointer rather than modifying its argument"] - #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")] - #[inline(always)] - pub const fn wrapping_sub(self, count: usize) -> Self - where - T: Sized, - { - self.wrapping_offset((count as isize).wrapping_neg()) - } - - /// Calculates the offset from a pointer in bytes using wrapping arithmetic. - /// (convenience for `.wrapping_offset((count as isize).wrapping_neg())`) - /// - /// `count` is in units of bytes. - /// - /// This is purely a convenience for casting to a `u8` pointer and - /// using [wrapping_sub][pointer::wrapping_sub] on it. See that method for documentation. - /// - /// For non-`Sized` pointees this operation changes only the data pointer, - /// leaving the metadata untouched. - #[must_use] - #[inline(always)] - #[stable(feature = "pointer_byte_offsets", since = "1.75.0")] - #[rustc_const_stable(feature = "const_pointer_byte_offsets", since = "1.75.0")] - #[rustc_allow_const_fn_unstable(set_ptr_value)] - pub const fn wrapping_byte_sub(self, count: usize) -> Self { - self.cast::().wrapping_sub(count).with_metadata_of(self) - } - - /// Reads the value from `self` without moving it. This leaves the - /// memory in `self` unchanged. - /// - /// See [`ptr::read`] for safety concerns and examples. - /// - /// [`ptr::read`]: crate::ptr::read() - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[rustc_const_stable(feature = "const_ptr_read", since = "1.71.0")] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn read(self) -> T - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for ``. - unsafe { read(self) } - } - - /// Performs a volatile read of the value from `self` without moving it. This - /// leaves the memory in `self` unchanged. - /// - /// Volatile operations are intended to act on I/O memory, and are guaranteed - /// to not be elided or reordered by the compiler across other volatile - /// operations. - /// - /// See [`ptr::read_volatile`] for safety concerns and examples. - /// - /// [`ptr::read_volatile`]: crate::ptr::read_volatile() - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub unsafe fn read_volatile(self) -> T - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `read_volatile`. - unsafe { read_volatile(self) } - } - - /// Reads the value from `self` without moving it. This leaves the - /// memory in `self` unchanged. - /// - /// Unlike `read`, the pointer may be unaligned. - /// - /// See [`ptr::read_unaligned`] for safety concerns and examples. - /// - /// [`ptr::read_unaligned`]: crate::ptr::read_unaligned() - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[rustc_const_stable(feature = "const_ptr_read", since = "1.71.0")] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn read_unaligned(self) -> T - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `read_unaligned`. - unsafe { read_unaligned(self) } - } - - /// Copies `count * size_of` bytes from `self` to `dest`. The source - /// and destination may overlap. - /// - /// NOTE: this has the *same* argument order as [`ptr::copy`]. - /// - /// See [`ptr::copy`] for safety concerns and examples. - /// - /// [`ptr::copy`]: crate::ptr::copy() - #[rustc_const_unstable(feature = "const_intrinsic_copy", issue = "80697")] - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn copy_to(self, dest: *mut T, count: usize) - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `copy`. - unsafe { copy(self, dest, count) } - } - - /// Copies `count * size_of` bytes from `self` to `dest`. The source - /// and destination may *not* overlap. - /// - /// NOTE: this has the *same* argument order as [`ptr::copy_nonoverlapping`]. - /// - /// See [`ptr::copy_nonoverlapping`] for safety concerns and examples. - /// - /// [`ptr::copy_nonoverlapping`]: crate::ptr::copy_nonoverlapping() - #[rustc_const_unstable(feature = "const_intrinsic_copy", issue = "80697")] - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn copy_to_nonoverlapping(self, dest: *mut T, count: usize) - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `copy_nonoverlapping`. - unsafe { copy_nonoverlapping(self, dest, count) } - } - - /// Copies `count * size_of` bytes from `src` to `self`. The source - /// and destination may overlap. - /// - /// NOTE: this has the *opposite* argument order of [`ptr::copy`]. - /// - /// See [`ptr::copy`] for safety concerns and examples. - /// - /// [`ptr::copy`]: crate::ptr::copy() - #[rustc_const_unstable(feature = "const_intrinsic_copy", issue = "80697")] - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn copy_from(self, src: *const T, count: usize) - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `copy`. - unsafe { copy(src, self, count) } - } - - /// Copies `count * size_of` bytes from `src` to `self`. The source - /// and destination may *not* overlap. - /// - /// NOTE: this has the *opposite* argument order of [`ptr::copy_nonoverlapping`]. - /// - /// See [`ptr::copy_nonoverlapping`] for safety concerns and examples. - /// - /// [`ptr::copy_nonoverlapping`]: crate::ptr::copy_nonoverlapping() - #[rustc_const_unstable(feature = "const_intrinsic_copy", issue = "80697")] - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn copy_from_nonoverlapping(self, src: *const T, count: usize) - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `copy_nonoverlapping`. - unsafe { copy_nonoverlapping(src, self, count) } - } - - /// Executes the destructor (if any) of the pointed-to value. - /// - /// See [`ptr::drop_in_place`] for safety concerns and examples. - /// - /// [`ptr::drop_in_place`]: crate::ptr::drop_in_place() - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[inline(always)] - pub unsafe fn drop_in_place(self) { - // SAFETY: the caller must uphold the safety contract for `drop_in_place`. - unsafe { drop_in_place(self) } - } - - /// Overwrites a memory location with the given value without reading or - /// dropping the old value. - /// - /// See [`ptr::write`] for safety concerns and examples. - /// - /// [`ptr::write`]: crate::ptr::write() - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[rustc_const_unstable(feature = "const_ptr_write", issue = "86302")] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn write(self, val: T) - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `write`. - unsafe { write(self, val) } - } - - /// Invokes memset on the specified pointer, setting `count * size_of::()` - /// bytes of memory starting at `self` to `val`. - /// - /// See [`ptr::write_bytes`] for safety concerns and examples. - /// - /// [`ptr::write_bytes`]: crate::ptr::write_bytes() - #[doc(alias = "memset")] - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[rustc_const_unstable(feature = "const_ptr_write", issue = "86302")] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn write_bytes(self, val: u8, count: usize) - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `write_bytes`. - unsafe { write_bytes(self, val, count) } - } - - /// Performs a volatile write of a memory location with the given value without - /// reading or dropping the old value. - /// - /// Volatile operations are intended to act on I/O memory, and are guaranteed - /// to not be elided or reordered by the compiler across other volatile - /// operations. - /// - /// See [`ptr::write_volatile`] for safety concerns and examples. - /// - /// [`ptr::write_volatile`]: crate::ptr::write_volatile() - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub unsafe fn write_volatile(self, val: T) - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `write_volatile`. - unsafe { write_volatile(self, val) } - } - - /// Overwrites a memory location with the given value without reading or - /// dropping the old value. - /// - /// Unlike `write`, the pointer may be unaligned. - /// - /// See [`ptr::write_unaligned`] for safety concerns and examples. - /// - /// [`ptr::write_unaligned`]: crate::ptr::write_unaligned() - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[rustc_const_unstable(feature = "const_ptr_write", issue = "86302")] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub const unsafe fn write_unaligned(self, val: T) - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `write_unaligned`. - unsafe { write_unaligned(self, val) } - } - - /// Replaces the value at `self` with `src`, returning the old - /// value, without dropping either. - /// - /// See [`ptr::replace`] for safety concerns and examples. - /// - /// [`ptr::replace`]: crate::ptr::replace() - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[inline(always)] - pub unsafe fn replace(self, src: T) -> T - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `replace`. - unsafe { replace(self, src) } - } - - /// Swaps the values at two mutable locations of the same type, without - /// deinitializing either. They may overlap, unlike `mem::swap` which is - /// otherwise equivalent. - /// - /// See [`ptr::swap`] for safety concerns and examples. - /// - /// [`ptr::swap`]: crate::ptr::swap() - #[stable(feature = "pointer_methods", since = "1.26.0")] - #[rustc_const_unstable(feature = "const_swap", issue = "83163")] - #[inline(always)] - pub const unsafe fn swap(self, with: *mut T) - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `swap`. - unsafe { swap(self, with) } - } - - /// Computes the offset that needs to be applied to the pointer in order to make it aligned to - /// `align`. - /// - /// If it is not possible to align the pointer, the implementation returns - /// `usize::MAX`. - /// - /// The offset is expressed in number of `T` elements, and not bytes. The value returned can be - /// used with the `wrapping_add` method. - /// - /// There are no guarantees whatsoever that offsetting the pointer will not overflow or go - /// beyond the allocation that the pointer points into. It is up to the caller to ensure that - /// the returned offset is correct in all terms other than alignment. - /// - /// When this is called during compile-time evaluation (which is unstable), the implementation - /// may return `usize::MAX` in cases where that can never happen at runtime. This is because the - /// actual alignment of pointers is not known yet during compile-time, so an offset with - /// guaranteed alignment can sometimes not be computed. For example, a buffer declared as `[u8; - /// N]` might be allocated at an odd or an even address, but at compile-time this is not yet - /// known, so the execution has to be correct for either choice. It is therefore impossible to - /// find an offset that is guaranteed to be 2-aligned. (This behavior is subject to change, as usual - /// for unstable APIs.) - /// - /// # Panics - /// - /// The function panics if `align` is not a power-of-two. - /// - /// # Examples - /// - /// Accessing adjacent `u8` as `u16` - /// - /// ``` - /// use std::mem::align_of; - /// - /// # unsafe { - /// let mut x = [5_u8, 6, 7, 8, 9]; - /// let ptr = x.as_mut_ptr(); - /// let offset = ptr.align_offset(align_of::()); - /// - /// if offset < x.len() - 1 { - /// let u16_ptr = ptr.add(offset).cast::(); - /// *u16_ptr = 0; - /// - /// assert!(x == [0, 0, 7, 8, 9] || x == [5, 0, 0, 8, 9]); - /// } else { - /// // while the pointer can be aligned via `offset`, it would point - /// // outside the allocation - /// } - /// # } - /// ``` - #[must_use] - #[inline] - #[stable(feature = "align_offset", since = "1.36.0")] - #[rustc_const_unstable(feature = "const_align_offset", issue = "90962")] - pub const fn align_offset(self, align: usize) -> usize - where - T: Sized, - { - if !align.is_power_of_two() { - panic!("align_offset: align is not a power-of-two"); - } - - // SAFETY: `align` has been checked to be a power of 2 above - let ret = unsafe { align_offset(self, align) }; - - // Inform Miri that we want to consider the resulting pointer to be suitably aligned. - #[cfg(miri)] - if ret != usize::MAX { - intrinsics::miri_promise_symbolic_alignment( - self.wrapping_add(ret).cast_const().cast(), - align, - ); - } - - ret - } - - /// Returns whether the pointer is properly aligned for `T`. - /// - /// # Examples - /// - /// ``` - /// // On some platforms, the alignment of i32 is less than 4. - /// #[repr(align(4))] - /// struct AlignedI32(i32); - /// - /// let mut data = AlignedI32(42); - /// let ptr = &mut data as *mut AlignedI32; - /// - /// assert!(ptr.is_aligned()); - /// assert!(!ptr.wrapping_byte_add(1).is_aligned()); - /// ``` - /// - /// # At compiletime - /// **Note: Alignment at compiletime is experimental and subject to change. See the - /// [tracking issue] for details.** - /// - /// At compiletime, the compiler may not know where a value will end up in memory. - /// Calling this function on a pointer created from a reference at compiletime will only - /// return `true` if the pointer is guaranteed to be aligned. This means that the pointer - /// is never aligned if cast to a type with a stricter alignment than the reference's - /// underlying allocation. - /// - /// ``` - /// #![feature(const_pointer_is_aligned)] - /// #![feature(const_mut_refs)] - /// - /// // On some platforms, the alignment of primitives is less than their size. - /// #[repr(align(4))] - /// struct AlignedI32(i32); - /// #[repr(align(8))] - /// struct AlignedI64(i64); - /// - /// const _: () = { - /// let mut data = AlignedI32(42); - /// let ptr = &mut data as *mut AlignedI32; - /// assert!(ptr.is_aligned()); - /// - /// // At runtime either `ptr1` or `ptr2` would be aligned, but at compiletime neither is aligned. - /// let ptr1 = ptr.cast::(); - /// let ptr2 = ptr.wrapping_add(1).cast::(); - /// assert!(!ptr1.is_aligned()); - /// assert!(!ptr2.is_aligned()); - /// }; - /// ``` - /// - /// Due to this behavior, it is possible that a runtime pointer derived from a compiletime - /// pointer is aligned, even if the compiletime pointer wasn't aligned. - /// - /// ``` - /// #![feature(const_pointer_is_aligned)] - /// - /// // On some platforms, the alignment of primitives is less than their size. - /// #[repr(align(4))] - /// struct AlignedI32(i32); - /// #[repr(align(8))] - /// struct AlignedI64(i64); - /// - /// // At compiletime, neither `COMPTIME_PTR` nor `COMPTIME_PTR + 1` is aligned. - /// // Also, note that mutable references are not allowed in the final value of constants. - /// const COMPTIME_PTR: *mut AlignedI32 = (&AlignedI32(42) as *const AlignedI32).cast_mut(); - /// const _: () = assert!(!COMPTIME_PTR.cast::().is_aligned()); - /// const _: () = assert!(!COMPTIME_PTR.wrapping_add(1).cast::().is_aligned()); - /// - /// // At runtime, either `runtime_ptr` or `runtime_ptr + 1` is aligned. - /// let runtime_ptr = COMPTIME_PTR; - /// assert_ne!( - /// runtime_ptr.cast::().is_aligned(), - /// runtime_ptr.wrapping_add(1).cast::().is_aligned(), - /// ); - /// ``` - /// - /// If a pointer is created from a fixed address, this function behaves the same during - /// runtime and compiletime. - /// - /// ``` - /// #![feature(const_pointer_is_aligned)] - /// - /// // On some platforms, the alignment of primitives is less than their size. - /// #[repr(align(4))] - /// struct AlignedI32(i32); - /// #[repr(align(8))] - /// struct AlignedI64(i64); - /// - /// const _: () = { - /// let ptr = 40 as *mut AlignedI32; - /// assert!(ptr.is_aligned()); - /// - /// // For pointers with a known address, runtime and compiletime behavior are identical. - /// let ptr1 = ptr.cast::(); - /// let ptr2 = ptr.wrapping_add(1).cast::(); - /// assert!(ptr1.is_aligned()); - /// assert!(!ptr2.is_aligned()); - /// }; - /// ``` - /// - /// [tracking issue]: https://github.com/rust-lang/rust/issues/104203 - #[must_use] - #[inline] - #[stable(feature = "pointer_is_aligned", since = "1.79.0")] - #[rustc_const_unstable(feature = "const_pointer_is_aligned", issue = "104203")] - pub const fn is_aligned(self) -> bool - where - T: Sized, - { - self.is_aligned_to(mem::align_of::()) - } - - /// Returns whether the pointer is aligned to `align`. - /// - /// For non-`Sized` pointees this operation considers only the data pointer, - /// ignoring the metadata. - /// - /// # Panics - /// - /// The function panics if `align` is not a power-of-two (this includes 0). - /// - /// # Examples - /// - /// ``` - /// #![feature(pointer_is_aligned_to)] - /// - /// // On some platforms, the alignment of i32 is less than 4. - /// #[repr(align(4))] - /// struct AlignedI32(i32); - /// - /// let mut data = AlignedI32(42); - /// let ptr = &mut data as *mut AlignedI32; - /// - /// assert!(ptr.is_aligned_to(1)); - /// assert!(ptr.is_aligned_to(2)); - /// assert!(ptr.is_aligned_to(4)); - /// - /// assert!(ptr.wrapping_byte_add(2).is_aligned_to(2)); - /// assert!(!ptr.wrapping_byte_add(2).is_aligned_to(4)); - /// - /// assert_ne!(ptr.is_aligned_to(8), ptr.wrapping_add(1).is_aligned_to(8)); - /// ``` - /// - /// # At compiletime - /// **Note: Alignment at compiletime is experimental and subject to change. See the - /// [tracking issue] for details.** - /// - /// At compiletime, the compiler may not know where a value will end up in memory. - /// Calling this function on a pointer created from a reference at compiletime will only - /// return `true` if the pointer is guaranteed to be aligned. This means that the pointer - /// cannot be stricter aligned than the reference's underlying allocation. - /// - /// ``` - /// #![feature(pointer_is_aligned_to)] - /// #![feature(const_pointer_is_aligned)] - /// #![feature(const_mut_refs)] - /// - /// // On some platforms, the alignment of i32 is less than 4. - /// #[repr(align(4))] - /// struct AlignedI32(i32); - /// - /// const _: () = { - /// let mut data = AlignedI32(42); - /// let ptr = &mut data as *mut AlignedI32; - /// - /// assert!(ptr.is_aligned_to(1)); - /// assert!(ptr.is_aligned_to(2)); - /// assert!(ptr.is_aligned_to(4)); - /// - /// // At compiletime, we know for sure that the pointer isn't aligned to 8. - /// assert!(!ptr.is_aligned_to(8)); - /// assert!(!ptr.wrapping_add(1).is_aligned_to(8)); - /// }; - /// ``` - /// - /// Due to this behavior, it is possible that a runtime pointer derived from a compiletime - /// pointer is aligned, even if the compiletime pointer wasn't aligned. - /// - /// ``` - /// #![feature(pointer_is_aligned_to)] - /// #![feature(const_pointer_is_aligned)] - /// - /// // On some platforms, the alignment of i32 is less than 4. - /// #[repr(align(4))] - /// struct AlignedI32(i32); - /// - /// // At compiletime, neither `COMPTIME_PTR` nor `COMPTIME_PTR + 1` is aligned. - /// // Also, note that mutable references are not allowed in the final value of constants. - /// const COMPTIME_PTR: *mut AlignedI32 = (&AlignedI32(42) as *const AlignedI32).cast_mut(); - /// const _: () = assert!(!COMPTIME_PTR.is_aligned_to(8)); - /// const _: () = assert!(!COMPTIME_PTR.wrapping_add(1).is_aligned_to(8)); - /// - /// // At runtime, either `runtime_ptr` or `runtime_ptr + 1` is aligned. - /// let runtime_ptr = COMPTIME_PTR; - /// assert_ne!( - /// runtime_ptr.is_aligned_to(8), - /// runtime_ptr.wrapping_add(1).is_aligned_to(8), - /// ); - /// ``` - /// - /// If a pointer is created from a fixed address, this function behaves the same during - /// runtime and compiletime. - /// - /// ``` - /// #![feature(pointer_is_aligned_to)] - /// #![feature(const_pointer_is_aligned)] - /// - /// const _: () = { - /// let ptr = 40 as *mut u8; - /// assert!(ptr.is_aligned_to(1)); - /// assert!(ptr.is_aligned_to(2)); - /// assert!(ptr.is_aligned_to(4)); - /// assert!(ptr.is_aligned_to(8)); - /// assert!(!ptr.is_aligned_to(16)); - /// }; - /// ``` - /// - /// [tracking issue]: https://github.com/rust-lang/rust/issues/104203 - #[must_use] - #[inline] - #[unstable(feature = "pointer_is_aligned_to", issue = "96284")] - #[rustc_const_unstable(feature = "const_pointer_is_aligned", issue = "104203")] - pub const fn is_aligned_to(self, align: usize) -> bool { - if !align.is_power_of_two() { - panic!("is_aligned_to: align is not a power-of-two"); - } - - #[inline] - fn runtime_impl(ptr: *mut (), align: usize) -> bool { - ptr.addr() & (align - 1) == 0 - } - - #[inline] - const fn const_impl(ptr: *mut (), align: usize) -> bool { - // We can't use the address of `self` in a `const fn`, so we use `align_offset` instead. - ptr.align_offset(align) == 0 - } - - // The cast to `()` is used to - // 1. deal with fat pointers; and - // 2. ensure that `align_offset` (in `const_impl`) doesn't actually try to compute an offset. - const_eval_select((self.cast::<()>(), align), const_impl, runtime_impl) - } -} - -impl *mut [T] { - /// Returns the length of a raw slice. - /// - /// The returned value is the number of **elements**, not the number of bytes. - /// - /// This function is safe, even when the raw slice cannot be cast to a slice - /// reference because the pointer is null or unaligned. - /// - /// # Examples - /// - /// ```rust - /// use std::ptr; - /// - /// let slice: *mut [i8] = ptr::slice_from_raw_parts_mut(ptr::null_mut(), 3); - /// assert_eq!(slice.len(), 3); - /// ``` - #[inline(always)] - #[stable(feature = "slice_ptr_len", since = "1.79.0")] - #[rustc_const_stable(feature = "const_slice_ptr_len", since = "1.79.0")] - #[rustc_allow_const_fn_unstable(ptr_metadata)] - pub const fn len(self) -> usize { - metadata(self) - } - - /// Returns `true` if the raw slice has a length of 0. - /// - /// # Examples - /// - /// ``` - /// use std::ptr; - /// - /// let slice: *mut [i8] = ptr::slice_from_raw_parts_mut(ptr::null_mut(), 3); - /// assert!(!slice.is_empty()); - /// ``` - #[inline(always)] - #[stable(feature = "slice_ptr_len", since = "1.79.0")] - #[rustc_const_stable(feature = "const_slice_ptr_len", since = "1.79.0")] - pub const fn is_empty(self) -> bool { - self.len() == 0 - } - - /// Divides one mutable raw slice into two at an index. - /// - /// The first will contain all indices from `[0, mid)` (excluding - /// the index `mid` itself) and the second will contain all - /// indices from `[mid, len)` (excluding the index `len` itself). - /// - /// # Panics - /// - /// Panics if `mid > len`. - /// - /// # Safety - /// - /// `mid` must be [in-bounds] of the underlying [allocated object]. - /// Which means `self` must be dereferenceable and span a single allocation - /// that is at least `mid * size_of::()` bytes long. Not upholding these - /// requirements is *[undefined behavior]* even if the resulting pointers are not used. - /// - /// Since `len` being in-bounds it is not a safety invariant of `*mut [T]` the - /// safety requirements of this method are the same as for [`split_at_mut_unchecked`]. - /// The explicit bounds check is only as useful as `len` is correct. - /// - /// [`split_at_mut_unchecked`]: #method.split_at_mut_unchecked - /// [in-bounds]: #method.add - /// [allocated object]: crate::ptr#allocated-object - /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html - /// - /// # Examples - /// - /// ``` - /// #![feature(raw_slice_split)] - /// #![feature(slice_ptr_get)] - /// - /// let mut v = [1, 0, 3, 0, 5, 6]; - /// let ptr = &mut v as *mut [_]; - /// unsafe { - /// let (left, right) = ptr.split_at_mut(2); - /// assert_eq!(&*left, [1, 0]); - /// assert_eq!(&*right, [3, 0, 5, 6]); - /// } - /// ``` - #[inline(always)] - #[track_caller] - #[unstable(feature = "raw_slice_split", issue = "95595")] - pub unsafe fn split_at_mut(self, mid: usize) -> (*mut [T], *mut [T]) { - assert!(mid <= self.len()); - // SAFETY: The assert above is only a safety-net as long as `self.len()` is correct - // The actual safety requirements of this function are the same as for `split_at_mut_unchecked` - unsafe { self.split_at_mut_unchecked(mid) } - } - - /// Divides one mutable raw slice into two at an index, without doing bounds checking. - /// - /// The first will contain all indices from `[0, mid)` (excluding - /// the index `mid` itself) and the second will contain all - /// indices from `[mid, len)` (excluding the index `len` itself). - /// - /// # Safety - /// - /// `mid` must be [in-bounds] of the underlying [allocated object]. - /// Which means `self` must be dereferenceable and span a single allocation - /// that is at least `mid * size_of::()` bytes long. Not upholding these - /// requirements is *[undefined behavior]* even if the resulting pointers are not used. - /// - /// [in-bounds]: #method.add - /// [out-of-bounds index]: #method.add - /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html - /// - /// # Examples - /// - /// ``` - /// #![feature(raw_slice_split)] - /// - /// let mut v = [1, 0, 3, 0, 5, 6]; - /// // scoped to restrict the lifetime of the borrows - /// unsafe { - /// let ptr = &mut v as *mut [_]; - /// let (left, right) = ptr.split_at_mut_unchecked(2); - /// assert_eq!(&*left, [1, 0]); - /// assert_eq!(&*right, [3, 0, 5, 6]); - /// (&mut *left)[1] = 2; - /// (&mut *right)[1] = 4; - /// } - /// assert_eq!(v, [1, 2, 3, 4, 5, 6]); - /// ``` - #[inline(always)] - #[unstable(feature = "raw_slice_split", issue = "95595")] - pub unsafe fn split_at_mut_unchecked(self, mid: usize) -> (*mut [T], *mut [T]) { - let len = self.len(); - let ptr = self.as_mut_ptr(); - - // SAFETY: Caller must pass a valid pointer and an index that is in-bounds. - let tail = unsafe { ptr.add(mid) }; - ( - crate::ptr::slice_from_raw_parts_mut(ptr, mid), - crate::ptr::slice_from_raw_parts_mut(tail, len - mid), - ) - } - - /// Returns a raw pointer to the slice's buffer. - /// - /// This is equivalent to casting `self` to `*mut T`, but more type-safe. - /// - /// # Examples - /// - /// ```rust - /// #![feature(slice_ptr_get)] - /// use std::ptr; - /// - /// let slice: *mut [i8] = ptr::slice_from_raw_parts_mut(ptr::null_mut(), 3); - /// assert_eq!(slice.as_mut_ptr(), ptr::null_mut()); - /// ``` - #[inline(always)] - #[unstable(feature = "slice_ptr_get", issue = "74265")] - #[rustc_const_unstable(feature = "slice_ptr_get", issue = "74265")] - pub const fn as_mut_ptr(self) -> *mut T { - self as *mut T - } - - /// Returns a raw pointer to an element or subslice, without doing bounds - /// checking. - /// - /// Calling this method with an [out-of-bounds index] or when `self` is not dereferenceable - /// is *[undefined behavior]* even if the resulting pointer is not used. - /// - /// [out-of-bounds index]: #method.add - /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html - /// - /// # Examples - /// - /// ``` - /// #![feature(slice_ptr_get)] - /// - /// let x = &mut [1, 2, 4] as *mut [i32]; - /// - /// unsafe { - /// assert_eq!(x.get_unchecked_mut(1), x.as_mut_ptr().add(1)); - /// } - /// ``` - #[unstable(feature = "slice_ptr_get", issue = "74265")] - #[inline(always)] - pub unsafe fn get_unchecked_mut(self, index: I) -> *mut I::Output - where - I: SliceIndex<[T]>, - { - // SAFETY: the caller ensures that `self` is dereferenceable and `index` in-bounds. - unsafe { index.get_unchecked_mut(self) } - } - - /// Returns `None` if the pointer is null, or else returns a shared slice to - /// the value wrapped in `Some`. In contrast to [`as_ref`], this does not require - /// that the value has to be initialized. - /// - /// For the mutable counterpart see [`as_uninit_slice_mut`]. - /// - /// [`as_ref`]: pointer#method.as_ref-1 - /// [`as_uninit_slice_mut`]: #method.as_uninit_slice_mut - /// - /// # Safety - /// - /// When calling this method, you have to ensure that *either* the pointer is null *or* - /// all of the following is true: - /// - /// * The pointer must be [valid] for reads for `ptr.len() * mem::size_of::()` many bytes, - /// and it must be properly aligned. This means in particular: - /// - /// * The entire memory range of this slice must be contained within a single [allocated object]! - /// Slices can never span across multiple allocated objects. - /// - /// * The pointer must be aligned even for zero-length slices. One - /// reason for this is that enum layout optimizations may rely on references - /// (including slices of any length) being aligned and non-null to distinguish - /// them from other data. You can obtain a pointer that is usable as `data` - /// for zero-length slices using [`NonNull::dangling()`]. - /// - /// * The total size `ptr.len() * mem::size_of::()` of the slice must be no larger than `isize::MAX`. - /// See the safety documentation of [`pointer::offset`]. - /// - /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is - /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. - /// In particular, while this reference exists, the memory the pointer points to must - /// not get mutated (except inside `UnsafeCell`). - /// - /// This applies even if the result of this method is unused! - /// - /// See also [`slice::from_raw_parts`][]. - /// - /// [valid]: crate::ptr#safety - /// [allocated object]: crate::ptr#allocated-object - #[inline] - #[unstable(feature = "ptr_as_uninit", issue = "75402")] - #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")] - pub const unsafe fn as_uninit_slice<'a>(self) -> Option<&'a [MaybeUninit]> { - if self.is_null() { - None - } else { - // SAFETY: the caller must uphold the safety contract for `as_uninit_slice`. - Some(unsafe { slice::from_raw_parts(self as *const MaybeUninit, self.len()) }) - } - } - - /// Returns `None` if the pointer is null, or else returns a unique slice to - /// the value wrapped in `Some`. In contrast to [`as_mut`], this does not require - /// that the value has to be initialized. - /// - /// For the shared counterpart see [`as_uninit_slice`]. - /// - /// [`as_mut`]: #method.as_mut - /// [`as_uninit_slice`]: #method.as_uninit_slice-1 - /// - /// # Safety - /// - /// When calling this method, you have to ensure that *either* the pointer is null *or* - /// all of the following is true: - /// - /// * The pointer must be [valid] for reads and writes for `ptr.len() * mem::size_of::()` - /// many bytes, and it must be properly aligned. This means in particular: - /// - /// * The entire memory range of this slice must be contained within a single [allocated object]! - /// Slices can never span across multiple allocated objects. - /// - /// * The pointer must be aligned even for zero-length slices. One - /// reason for this is that enum layout optimizations may rely on references - /// (including slices of any length) being aligned and non-null to distinguish - /// them from other data. You can obtain a pointer that is usable as `data` - /// for zero-length slices using [`NonNull::dangling()`]. - /// - /// * The total size `ptr.len() * mem::size_of::()` of the slice must be no larger than `isize::MAX`. - /// See the safety documentation of [`pointer::offset`]. - /// - /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is - /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. - /// In particular, while this reference exists, the memory the pointer points to must - /// not get accessed (read or written) through any other pointer. - /// - /// This applies even if the result of this method is unused! - /// - /// See also [`slice::from_raw_parts_mut`][]. - /// - /// [valid]: crate::ptr#safety - /// [allocated object]: crate::ptr#allocated-object - #[inline] - #[unstable(feature = "ptr_as_uninit", issue = "75402")] - #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")] - pub const unsafe fn as_uninit_slice_mut<'a>(self) -> Option<&'a mut [MaybeUninit]> { - if self.is_null() { - None - } else { - // SAFETY: the caller must uphold the safety contract for `as_uninit_slice_mut`. - Some(unsafe { slice::from_raw_parts_mut(self as *mut MaybeUninit, self.len()) }) - } - } -} - -impl *mut [T; N] { - /// Returns a raw pointer to the array's buffer. - /// - /// This is equivalent to casting `self` to `*mut T`, but more type-safe. - /// - /// # Examples - /// - /// ```rust - /// #![feature(array_ptr_get)] - /// use std::ptr; - /// - /// let arr: *mut [i8; 3] = ptr::null_mut(); - /// assert_eq!(arr.as_mut_ptr(), ptr::null_mut()); - /// ``` - #[inline] - #[unstable(feature = "array_ptr_get", issue = "119834")] - #[rustc_const_unstable(feature = "array_ptr_get", issue = "119834")] - pub const fn as_mut_ptr(self) -> *mut T { - self as *mut T - } - - /// Returns a raw pointer to a mutable slice containing the entire array. - /// - /// # Examples - /// - /// ``` - /// #![feature(array_ptr_get)] - /// - /// let mut arr = [1, 2, 5]; - /// let ptr: *mut [i32; 3] = &mut arr; - /// unsafe { - /// (&mut *ptr.as_mut_slice())[..2].copy_from_slice(&[3, 4]); - /// } - /// assert_eq!(arr, [3, 4, 5]); - /// ``` - #[inline] - #[unstable(feature = "array_ptr_get", issue = "119834")] - #[rustc_const_unstable(feature = "array_ptr_get", issue = "119834")] - pub const fn as_mut_slice(self) -> *mut [T] { - self - } -} - -// Equality for pointers -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for *mut T { - #[inline(always)] - #[allow(ambiguous_wide_pointer_comparisons)] - fn eq(&self, other: &*mut T) -> bool { - *self == *other - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Eq for *mut T {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for *mut T { - #[inline] - #[allow(ambiguous_wide_pointer_comparisons)] - fn cmp(&self, other: &*mut T) -> Ordering { - if self < other { - Less - } else if self == other { - Equal - } else { - Greater - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialOrd for *mut T { - #[inline(always)] - #[allow(ambiguous_wide_pointer_comparisons)] - fn partial_cmp(&self, other: &*mut T) -> Option { - Some(self.cmp(other)) - } - - #[inline(always)] - #[allow(ambiguous_wide_pointer_comparisons)] - fn lt(&self, other: &*mut T) -> bool { - *self < *other - } - - #[inline(always)] - #[allow(ambiguous_wide_pointer_comparisons)] - fn le(&self, other: &*mut T) -> bool { - *self <= *other - } - - #[inline(always)] - #[allow(ambiguous_wide_pointer_comparisons)] - fn gt(&self, other: &*mut T) -> bool { - *self > *other - } - - #[inline(always)] - #[allow(ambiguous_wide_pointer_comparisons)] - fn ge(&self, other: &*mut T) -> bool { - *self >= *other - } -} diff --git a/library/core/src/ptr/non_null.rs b/library/core/src/ptr/non_null.rs deleted file mode 100644 index 617890cf083b1..0000000000000 --- a/library/core/src/ptr/non_null.rs +++ /dev/null @@ -1,1855 +0,0 @@ -use crate::cmp::Ordering; -use crate::fmt; -use crate::hash; -use crate::intrinsics; -use crate::marker::Unsize; -use crate::mem::{MaybeUninit, SizedTypeProperties}; -use crate::num::NonZero; -use crate::ops::{CoerceUnsized, DispatchFromDyn}; -use crate::ptr; -use crate::ptr::Unique; -use crate::slice::{self, SliceIndex}; -use crate::ub_checks::assert_unsafe_precondition; - -/// `*mut T` but non-zero and [covariant]. -/// -/// This is often the correct thing to use when building data structures using -/// raw pointers, but is ultimately more dangerous to use because of its additional -/// properties. If you're not sure if you should use `NonNull`, just use `*mut T`! -/// -/// Unlike `*mut T`, the pointer must always be non-null, even if the pointer -/// is never dereferenced. This is so that enums may use this forbidden value -/// as a discriminant -- `Option>` has the same size as `*mut T`. -/// However the pointer may still dangle if it isn't dereferenced. -/// -/// Unlike `*mut T`, `NonNull` was chosen to be covariant over `T`. This makes it -/// possible to use `NonNull` when building covariant types, but introduces the -/// risk of unsoundness if used in a type that shouldn't actually be covariant. -/// (The opposite choice was made for `*mut T` even though technically the unsoundness -/// could only be caused by calling unsafe functions.) -/// -/// Covariance is correct for most safe abstractions, such as `Box`, `Rc`, `Arc`, `Vec`, -/// and `LinkedList`. This is the case because they provide a public API that follows the -/// normal shared XOR mutable rules of Rust. -/// -/// If your type cannot safely be covariant, you must ensure it contains some -/// additional field to provide invariance. Often this field will be a [`PhantomData`] -/// type like `PhantomData>` or `PhantomData<&'a mut T>`. -/// -/// Notice that `NonNull` has a `From` instance for `&T`. However, this does -/// not change the fact that mutating through a (pointer derived from a) shared -/// reference is undefined behavior unless the mutation happens inside an -/// [`UnsafeCell`]. The same goes for creating a mutable reference from a shared -/// reference. When using this `From` instance without an `UnsafeCell`, -/// it is your responsibility to ensure that `as_mut` is never called, and `as_ptr` -/// is never used for mutation. -/// -/// # Representation -/// -/// Thanks to the [null pointer optimization], -/// `NonNull` and `Option>` -/// are guaranteed to have the same size and alignment: -/// -/// ``` -/// # use std::mem::{size_of, align_of}; -/// use std::ptr::NonNull; -/// -/// assert_eq!(size_of::>(), size_of::>>()); -/// assert_eq!(align_of::>(), align_of::>>()); -/// -/// assert_eq!(size_of::>(), size_of::>>()); -/// assert_eq!(align_of::>(), align_of::>>()); -/// ``` -/// -/// [covariant]: https://doc.rust-lang.org/reference/subtyping.html -/// [`PhantomData`]: crate::marker::PhantomData -/// [`UnsafeCell`]: crate::cell::UnsafeCell -/// [null pointer optimization]: crate::option#representation -#[stable(feature = "nonnull", since = "1.25.0")] -#[repr(transparent)] -#[rustc_layout_scalar_valid_range_start(1)] -#[rustc_nonnull_optimization_guaranteed] -#[rustc_diagnostic_item = "NonNull"] -pub struct NonNull { - pointer: *const T, -} - -/// `NonNull` pointers are not `Send` because the data they reference may be aliased. -// N.B., this impl is unnecessary, but should provide better error messages. -#[stable(feature = "nonnull", since = "1.25.0")] -impl !Send for NonNull {} - -/// `NonNull` pointers are not `Sync` because the data they reference may be aliased. -// N.B., this impl is unnecessary, but should provide better error messages. -#[stable(feature = "nonnull", since = "1.25.0")] -impl !Sync for NonNull {} - -impl NonNull { - /// Creates a new `NonNull` that is dangling, but well-aligned. - /// - /// This is useful for initializing types which lazily allocate, like - /// `Vec::new` does. - /// - /// Note that the pointer value may potentially represent a valid pointer to - /// a `T`, which means this must not be used as a "not yet initialized" - /// sentinel value. Types that lazily allocate must track initialization by - /// some other means. - /// - /// # Examples - /// - /// ``` - /// use std::ptr::NonNull; - /// - /// let ptr = NonNull::::dangling(); - /// // Important: don't try to access the value of `ptr` without - /// // initializing it first! The pointer is not null but isn't valid either! - /// ``` - #[stable(feature = "nonnull", since = "1.25.0")] - #[rustc_const_stable(feature = "const_nonnull_dangling", since = "1.36.0")] - #[must_use] - #[inline] - pub const fn dangling() -> Self { - // SAFETY: mem::align_of() returns a non-zero usize which is then casted - // to a *mut T. Therefore, `ptr` is not null and the conditions for - // calling new_unchecked() are respected. - unsafe { - let ptr = crate::ptr::dangling_mut::(); - NonNull::new_unchecked(ptr) - } - } - - /// Returns a shared references to the value. In contrast to [`as_ref`], this does not require - /// that the value has to be initialized. - /// - /// For the mutable counterpart see [`as_uninit_mut`]. - /// - /// [`as_ref`]: NonNull::as_ref - /// [`as_uninit_mut`]: NonNull::as_uninit_mut - /// - /// # Safety - /// - /// When calling this method, you have to ensure that all of the following is true: - /// - /// * The pointer must be properly aligned. - /// - /// * It must be "dereferenceable" in the sense defined in [the module documentation]. - /// - /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is - /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. - /// In particular, while this reference exists, the memory the pointer points to must - /// not get mutated (except inside `UnsafeCell`). - /// - /// This applies even if the result of this method is unused! - /// - /// [the module documentation]: crate::ptr#safety - #[inline] - #[must_use] - #[unstable(feature = "ptr_as_uninit", issue = "75402")] - #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")] - pub const unsafe fn as_uninit_ref<'a>(self) -> &'a MaybeUninit { - // SAFETY: the caller must guarantee that `self` meets all the - // requirements for a reference. - unsafe { &*self.cast().as_ptr() } - } - - /// Returns a unique references to the value. In contrast to [`as_mut`], this does not require - /// that the value has to be initialized. - /// - /// For the shared counterpart see [`as_uninit_ref`]. - /// - /// [`as_mut`]: NonNull::as_mut - /// [`as_uninit_ref`]: NonNull::as_uninit_ref - /// - /// # Safety - /// - /// When calling this method, you have to ensure that all of the following is true: - /// - /// * The pointer must be properly aligned. - /// - /// * It must be "dereferenceable" in the sense defined in [the module documentation]. - /// - /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is - /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. - /// In particular, while this reference exists, the memory the pointer points to must - /// not get accessed (read or written) through any other pointer. - /// - /// This applies even if the result of this method is unused! - /// - /// [the module documentation]: crate::ptr#safety - #[inline] - #[must_use] - #[unstable(feature = "ptr_as_uninit", issue = "75402")] - #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")] - pub const unsafe fn as_uninit_mut<'a>(self) -> &'a mut MaybeUninit { - // SAFETY: the caller must guarantee that `self` meets all the - // requirements for a reference. - unsafe { &mut *self.cast().as_ptr() } - } -} - -impl NonNull { - /// Creates a new `NonNull`. - /// - /// # Safety - /// - /// `ptr` must be non-null. - /// - /// # Examples - /// - /// ``` - /// use std::ptr::NonNull; - /// - /// let mut x = 0u32; - /// let ptr = unsafe { NonNull::new_unchecked(&mut x as *mut _) }; - /// ``` - /// - /// *Incorrect* usage of this function: - /// - /// ```rust,no_run - /// use std::ptr::NonNull; - /// - /// // NEVER DO THAT!!! This is undefined behavior. ⚠️ - /// let ptr = unsafe { NonNull::::new_unchecked(std::ptr::null_mut()) }; - /// ``` - #[stable(feature = "nonnull", since = "1.25.0")] - #[rustc_const_stable(feature = "const_nonnull_new_unchecked", since = "1.25.0")] - #[inline] - pub const unsafe fn new_unchecked(ptr: *mut T) -> Self { - // SAFETY: the caller must guarantee that `ptr` is non-null. - unsafe { - assert_unsafe_precondition!( - check_language_ub, - "NonNull::new_unchecked requires that the pointer is non-null", - (ptr: *mut () = ptr as *mut ()) => !ptr.is_null() - ); - NonNull { pointer: ptr as _ } - } - } - - /// Creates a new `NonNull` if `ptr` is non-null. - /// - /// # Examples - /// - /// ``` - /// use std::ptr::NonNull; - /// - /// let mut x = 0u32; - /// let ptr = NonNull::::new(&mut x as *mut _).expect("ptr is null!"); - /// - /// if let Some(ptr) = NonNull::::new(std::ptr::null_mut()) { - /// unreachable!(); - /// } - /// ``` - #[stable(feature = "nonnull", since = "1.25.0")] - #[rustc_const_unstable(feature = "const_nonnull_new", issue = "93235")] - #[inline] - pub const fn new(ptr: *mut T) -> Option { - if !ptr.is_null() { - // SAFETY: The pointer is already checked and is not null - Some(unsafe { Self::new_unchecked(ptr) }) - } else { - None - } - } - - /// Performs the same functionality as [`std::ptr::from_raw_parts`], except that a - /// `NonNull` pointer is returned, as opposed to a raw `*const` pointer. - /// - /// See the documentation of [`std::ptr::from_raw_parts`] for more details. - /// - /// [`std::ptr::from_raw_parts`]: crate::ptr::from_raw_parts - #[unstable(feature = "ptr_metadata", issue = "81513")] - #[rustc_const_unstable(feature = "ptr_metadata", issue = "81513")] - #[inline] - pub const fn from_raw_parts( - data_pointer: NonNull<()>, - metadata: ::Metadata, - ) -> NonNull { - // SAFETY: The result of `ptr::from::raw_parts_mut` is non-null because `data_pointer` is. - unsafe { - NonNull::new_unchecked(super::from_raw_parts_mut(data_pointer.as_ptr(), metadata)) - } - } - - /// Decompose a (possibly wide) pointer into its data pointer and metadata components. - /// - /// The pointer can be later reconstructed with [`NonNull::from_raw_parts`]. - #[unstable(feature = "ptr_metadata", issue = "81513")] - #[rustc_const_unstable(feature = "ptr_metadata", issue = "81513")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn to_raw_parts(self) -> (NonNull<()>, ::Metadata) { - (self.cast(), super::metadata(self.as_ptr())) - } - - /// Gets the "address" portion of the pointer. - /// - /// For more details see the equivalent method on a raw pointer, [`pointer::addr`]. - /// - /// This API and its claimed semantics are part of the Strict Provenance experiment, - /// see the [`ptr` module documentation][crate::ptr]. - #[must_use] - #[inline] - #[unstable(feature = "strict_provenance", issue = "95228")] - pub fn addr(self) -> NonZero { - // SAFETY: The pointer is guaranteed by the type to be non-null, - // meaning that the address will be non-zero. - unsafe { NonZero::new_unchecked(self.pointer.addr()) } - } - - /// Creates a new pointer with the given address. - /// - /// For more details see the equivalent method on a raw pointer, [`pointer::with_addr`]. - /// - /// This API and its claimed semantics are part of the Strict Provenance experiment, - /// see the [`ptr` module documentation][crate::ptr]. - #[must_use] - #[inline] - #[unstable(feature = "strict_provenance", issue = "95228")] - pub fn with_addr(self, addr: NonZero) -> Self { - // SAFETY: The result of `ptr::from::with_addr` is non-null because `addr` is guaranteed to be non-zero. - unsafe { NonNull::new_unchecked(self.pointer.with_addr(addr.get()) as *mut _) } - } - - /// Creates a new pointer by mapping `self`'s address to a new one. - /// - /// For more details see the equivalent method on a raw pointer, [`pointer::map_addr`]. - /// - /// This API and its claimed semantics are part of the Strict Provenance experiment, - /// see the [`ptr` module documentation][crate::ptr]. - #[must_use] - #[inline] - #[unstable(feature = "strict_provenance", issue = "95228")] - pub fn map_addr(self, f: impl FnOnce(NonZero) -> NonZero) -> Self { - self.with_addr(f(self.addr())) - } - - /// Acquires the underlying `*mut` pointer. - /// - /// # Examples - /// - /// ``` - /// use std::ptr::NonNull; - /// - /// let mut x = 0u32; - /// let ptr = NonNull::new(&mut x).expect("ptr is null!"); - /// - /// let x_value = unsafe { *ptr.as_ptr() }; - /// assert_eq!(x_value, 0); - /// - /// unsafe { *ptr.as_ptr() += 2; } - /// let x_value = unsafe { *ptr.as_ptr() }; - /// assert_eq!(x_value, 2); - /// ``` - #[stable(feature = "nonnull", since = "1.25.0")] - #[rustc_const_stable(feature = "const_nonnull_as_ptr", since = "1.32.0")] - #[rustc_never_returns_null_ptr] - #[must_use] - #[inline(always)] - pub const fn as_ptr(self) -> *mut T { - self.pointer as *mut T - } - - /// Returns a shared reference to the value. If the value may be uninitialized, [`as_uninit_ref`] - /// must be used instead. - /// - /// For the mutable counterpart see [`as_mut`]. - /// - /// [`as_uninit_ref`]: NonNull::as_uninit_ref - /// [`as_mut`]: NonNull::as_mut - /// - /// # Safety - /// - /// When calling this method, you have to ensure that all of the following is true: - /// - /// * The pointer must be properly aligned. - /// - /// * It must be "dereferenceable" in the sense defined in [the module documentation]. - /// - /// * The pointer must point to an initialized instance of `T`. - /// - /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is - /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. - /// In particular, while this reference exists, the memory the pointer points to must - /// not get mutated (except inside `UnsafeCell`). - /// - /// This applies even if the result of this method is unused! - /// (The part about being initialized is not yet fully decided, but until - /// it is, the only safe approach is to ensure that they are indeed initialized.) - /// - /// # Examples - /// - /// ``` - /// use std::ptr::NonNull; - /// - /// let mut x = 0u32; - /// let ptr = NonNull::new(&mut x as *mut _).expect("ptr is null!"); - /// - /// let ref_x = unsafe { ptr.as_ref() }; - /// println!("{ref_x}"); - /// ``` - /// - /// [the module documentation]: crate::ptr#safety - #[stable(feature = "nonnull", since = "1.25.0")] - #[rustc_const_stable(feature = "const_nonnull_as_ref", since = "1.73.0")] - #[must_use] - #[inline(always)] - pub const unsafe fn as_ref<'a>(&self) -> &'a T { - // SAFETY: the caller must guarantee that `self` meets all the - // requirements for a reference. - // `cast_const` avoids a mutable raw pointer deref. - unsafe { &*self.as_ptr().cast_const() } - } - - /// Returns a unique reference to the value. If the value may be uninitialized, [`as_uninit_mut`] - /// must be used instead. - /// - /// For the shared counterpart see [`as_ref`]. - /// - /// [`as_uninit_mut`]: NonNull::as_uninit_mut - /// [`as_ref`]: NonNull::as_ref - /// - /// # Safety - /// - /// When calling this method, you have to ensure that all of the following is true: - /// - /// * The pointer must be properly aligned. - /// - /// * It must be "dereferenceable" in the sense defined in [the module documentation]. - /// - /// * The pointer must point to an initialized instance of `T`. - /// - /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is - /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. - /// In particular, while this reference exists, the memory the pointer points to must - /// not get accessed (read or written) through any other pointer. - /// - /// This applies even if the result of this method is unused! - /// (The part about being initialized is not yet fully decided, but until - /// it is, the only safe approach is to ensure that they are indeed initialized.) - /// # Examples - /// - /// ``` - /// use std::ptr::NonNull; - /// - /// let mut x = 0u32; - /// let mut ptr = NonNull::new(&mut x).expect("null pointer"); - /// - /// let x_ref = unsafe { ptr.as_mut() }; - /// assert_eq!(*x_ref, 0); - /// *x_ref += 2; - /// assert_eq!(*x_ref, 2); - /// ``` - /// - /// [the module documentation]: crate::ptr#safety - #[stable(feature = "nonnull", since = "1.25.0")] - #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")] - #[must_use] - #[inline(always)] - pub const unsafe fn as_mut<'a>(&mut self) -> &'a mut T { - // SAFETY: the caller must guarantee that `self` meets all the - // requirements for a mutable reference. - unsafe { &mut *self.as_ptr() } - } - - /// Casts to a pointer of another type. - /// - /// # Examples - /// - /// ``` - /// use std::ptr::NonNull; - /// - /// let mut x = 0u32; - /// let ptr = NonNull::new(&mut x as *mut _).expect("null pointer"); - /// - /// let casted_ptr = ptr.cast::(); - /// let raw_ptr: *mut i8 = casted_ptr.as_ptr(); - /// ``` - #[stable(feature = "nonnull_cast", since = "1.27.0")] - #[rustc_const_stable(feature = "const_nonnull_cast", since = "1.36.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn cast(self) -> NonNull { - // SAFETY: `self` is a `NonNull` pointer which is necessarily non-null - unsafe { NonNull { pointer: self.as_ptr() as *mut U } } - } - - /// Calculates the offset from a pointer. - /// - /// `count` is in units of T; e.g., a `count` of 3 represents a pointer - /// offset of `3 * size_of::()` bytes. - /// - /// # Safety - /// - /// If any of the following conditions are violated, the result is Undefined - /// Behavior: - /// - /// * Both the starting and resulting pointer must be either in bounds or one - /// byte past the end of the same [allocated object]. - /// - /// * The computed offset, **in bytes**, cannot overflow an `isize`. - /// - /// * The offset being in bounds cannot rely on "wrapping around" the address - /// space. That is, the infinite-precision sum, **in bytes** must fit in a usize. - /// - /// The compiler and standard library generally tries to ensure allocations - /// never reach a size where an offset is a concern. For instance, `Vec` - /// and `Box` ensure they never allocate more than `isize::MAX` bytes, so - /// `vec.as_ptr().add(vec.len())` is always safe. - /// - /// Most platforms fundamentally can't even construct such an allocation. - /// For instance, no known 64-bit platform can ever serve a request - /// for 263 bytes due to page-table limitations or splitting the address space. - /// However, some 32-bit and 16-bit platforms may successfully serve a request for - /// more than `isize::MAX` bytes with things like Physical Address - /// Extension. As such, memory acquired directly from allocators or memory - /// mapped files *may* be too large to handle with this function. - /// - /// [allocated object]: crate::ptr#allocated-object - /// - /// # Examples - /// - /// ``` - /// use std::ptr::NonNull; - /// - /// let mut s = [1, 2, 3]; - /// let ptr: NonNull = NonNull::new(s.as_mut_ptr()).unwrap(); - /// - /// unsafe { - /// println!("{}", ptr.offset(1).read()); - /// println!("{}", ptr.offset(2).read()); - /// } - /// ``` - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - #[must_use = "returns a new pointer rather than modifying its argument"] - #[stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - pub const unsafe fn offset(self, count: isize) -> Self - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `offset`. - // Additionally safety contract of `offset` guarantees that the resulting pointer is - // pointing to an allocation, there can't be an allocation at null, thus it's safe to - // construct `NonNull`. - unsafe { NonNull { pointer: intrinsics::offset(self.pointer, count) } } - } - - /// Calculates the offset from a pointer in bytes. - /// - /// `count` is in units of **bytes**. - /// - /// This is purely a convenience for casting to a `u8` pointer and - /// using [offset][pointer::offset] on it. See that method for documentation - /// and safety requirements. - /// - /// For non-`Sized` pointees this operation changes only the data pointer, - /// leaving the metadata untouched. - #[must_use] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - #[stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - pub const unsafe fn byte_offset(self, count: isize) -> Self { - // SAFETY: the caller must uphold the safety contract for `offset` and `byte_offset` has - // the same safety contract. - // Additionally safety contract of `offset` guarantees that the resulting pointer is - // pointing to an allocation, there can't be an allocation at null, thus it's safe to - // construct `NonNull`. - unsafe { NonNull { pointer: self.pointer.byte_offset(count) } } - } - - /// Calculates the offset from a pointer (convenience for `.offset(count as isize)`). - /// - /// `count` is in units of T; e.g., a `count` of 3 represents a pointer - /// offset of `3 * size_of::()` bytes. - /// - /// # Safety - /// - /// If any of the following conditions are violated, the result is Undefined - /// Behavior: - /// - /// * Both the starting and resulting pointer must be either in bounds or one - /// byte past the end of the same [allocated object]. - /// - /// * The computed offset, **in bytes**, cannot overflow an `isize`. - /// - /// * The offset being in bounds cannot rely on "wrapping around" the address - /// space. That is, the infinite-precision sum must fit in a `usize`. - /// - /// The compiler and standard library generally tries to ensure allocations - /// never reach a size where an offset is a concern. For instance, `Vec` - /// and `Box` ensure they never allocate more than `isize::MAX` bytes, so - /// `vec.as_ptr().add(vec.len())` is always safe. - /// - /// Most platforms fundamentally can't even construct such an allocation. - /// For instance, no known 64-bit platform can ever serve a request - /// for 263 bytes due to page-table limitations or splitting the address space. - /// However, some 32-bit and 16-bit platforms may successfully serve a request for - /// more than `isize::MAX` bytes with things like Physical Address - /// Extension. As such, memory acquired directly from allocators or memory - /// mapped files *may* be too large to handle with this function. - /// - /// [allocated object]: crate::ptr#allocated-object - /// - /// # Examples - /// - /// ``` - /// use std::ptr::NonNull; - /// - /// let s: &str = "123"; - /// let ptr: NonNull = NonNull::new(s.as_ptr().cast_mut()).unwrap(); - /// - /// unsafe { - /// println!("{}", ptr.add(1).read() as char); - /// println!("{}", ptr.add(2).read() as char); - /// } - /// ``` - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - #[must_use = "returns a new pointer rather than modifying its argument"] - #[stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - pub const unsafe fn add(self, count: usize) -> Self - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `offset`. - // Additionally safety contract of `offset` guarantees that the resulting pointer is - // pointing to an allocation, there can't be an allocation at null, thus it's safe to - // construct `NonNull`. - unsafe { NonNull { pointer: intrinsics::offset(self.pointer, count) } } - } - - /// Calculates the offset from a pointer in bytes (convenience for `.byte_offset(count as isize)`). - /// - /// `count` is in units of bytes. - /// - /// This is purely a convenience for casting to a `u8` pointer and - /// using [`add`][NonNull::add] on it. See that method for documentation - /// and safety requirements. - /// - /// For non-`Sized` pointees this operation changes only the data pointer, - /// leaving the metadata untouched. - #[must_use] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - #[rustc_allow_const_fn_unstable(set_ptr_value)] - #[stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - pub const unsafe fn byte_add(self, count: usize) -> Self { - // SAFETY: the caller must uphold the safety contract for `add` and `byte_add` has the same - // safety contract. - // Additionally safety contract of `add` guarantees that the resulting pointer is pointing - // to an allocation, there can't be an allocation at null, thus it's safe to construct - // `NonNull`. - unsafe { NonNull { pointer: self.pointer.byte_add(count) } } - } - - /// Calculates the offset from a pointer (convenience for - /// `.offset((count as isize).wrapping_neg())`). - /// - /// `count` is in units of T; e.g., a `count` of 3 represents a pointer - /// offset of `3 * size_of::()` bytes. - /// - /// # Safety - /// - /// If any of the following conditions are violated, the result is Undefined - /// Behavior: - /// - /// * Both the starting and resulting pointer must be either in bounds or one - /// byte past the end of the same [allocated object]. - /// - /// * The computed offset cannot exceed `isize::MAX` **bytes**. - /// - /// * The offset being in bounds cannot rely on "wrapping around" the address - /// space. That is, the infinite-precision sum must fit in a usize. - /// - /// The compiler and standard library generally tries to ensure allocations - /// never reach a size where an offset is a concern. For instance, `Vec` - /// and `Box` ensure they never allocate more than `isize::MAX` bytes, so - /// `vec.as_ptr().add(vec.len()).sub(vec.len())` is always safe. - /// - /// Most platforms fundamentally can't even construct such an allocation. - /// For instance, no known 64-bit platform can ever serve a request - /// for 263 bytes due to page-table limitations or splitting the address space. - /// However, some 32-bit and 16-bit platforms may successfully serve a request for - /// more than `isize::MAX` bytes with things like Physical Address - /// Extension. As such, memory acquired directly from allocators or memory - /// mapped files *may* be too large to handle with this function. - /// - /// [allocated object]: crate::ptr#allocated-object - /// - /// # Examples - /// - /// ``` - /// use std::ptr::NonNull; - /// - /// let s: &str = "123"; - /// - /// unsafe { - /// let end: NonNull = NonNull::new(s.as_ptr().cast_mut()).unwrap().add(3); - /// println!("{}", end.sub(1).read() as char); - /// println!("{}", end.sub(2).read() as char); - /// } - /// ``` - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - #[must_use = "returns a new pointer rather than modifying its argument"] - #[stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - pub const unsafe fn sub(self, count: usize) -> Self - where - T: Sized, - { - if T::IS_ZST { - // Pointer arithmetic does nothing when the pointee is a ZST. - self - } else { - // SAFETY: the caller must uphold the safety contract for `offset`. - // Because the pointee is *not* a ZST, that means that `count` is - // at most `isize::MAX`, and thus the negation cannot overflow. - unsafe { self.offset(intrinsics::unchecked_sub(0, count as isize)) } - } - } - - /// Calculates the offset from a pointer in bytes (convenience for - /// `.byte_offset((count as isize).wrapping_neg())`). - /// - /// `count` is in units of bytes. - /// - /// This is purely a convenience for casting to a `u8` pointer and - /// using [`sub`][NonNull::sub] on it. See that method for documentation - /// and safety requirements. - /// - /// For non-`Sized` pointees this operation changes only the data pointer, - /// leaving the metadata untouched. - #[must_use] - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - #[rustc_allow_const_fn_unstable(set_ptr_value)] - #[stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - pub const unsafe fn byte_sub(self, count: usize) -> Self { - // SAFETY: the caller must uphold the safety contract for `sub` and `byte_sub` has the same - // safety contract. - // Additionally safety contract of `sub` guarantees that the resulting pointer is pointing - // to an allocation, there can't be an allocation at null, thus it's safe to construct - // `NonNull`. - unsafe { NonNull { pointer: self.pointer.byte_sub(count) } } - } - - /// Calculates the distance between two pointers. The returned value is in - /// units of T: the distance in bytes divided by `mem::size_of::()`. - /// - /// This is equivalent to `(self as isize - origin as isize) / (mem::size_of::() as isize)`, - /// except that it has a lot more opportunities for UB, in exchange for the compiler - /// better understanding what you are doing. - /// - /// The primary motivation of this method is for computing the `len` of an array/slice - /// of `T` that you are currently representing as a "start" and "end" pointer - /// (and "end" is "one past the end" of the array). - /// In that case, `end.offset_from(start)` gets you the length of the array. - /// - /// All of the following safety requirements are trivially satisfied for this usecase. - /// - /// [`offset`]: #method.offset - /// - /// # Safety - /// - /// If any of the following conditions are violated, the result is Undefined - /// Behavior: - /// - /// * Both `self` and `origin` must be either in bounds or one - /// byte past the end of the same [allocated object]. - /// - /// * Both pointers must be *derived from* a pointer to the same object. - /// (See below for an example.) - /// - /// * The distance between the pointers, in bytes, must be an exact multiple - /// of the size of `T`. - /// - /// * The distance between the pointers, **in bytes**, cannot overflow an `isize`. - /// - /// * The distance being in bounds cannot rely on "wrapping around" the address space. - /// - /// Rust types are never larger than `isize::MAX` and Rust allocations never wrap around the - /// address space, so two pointers within some value of any Rust type `T` will always satisfy - /// the last two conditions. The standard library also generally ensures that allocations - /// never reach a size where an offset is a concern. For instance, `Vec` and `Box` ensure they - /// never allocate more than `isize::MAX` bytes, so `ptr_into_vec.offset_from(vec.as_ptr())` - /// always satisfies the last two conditions. - /// - /// Most platforms fundamentally can't even construct such a large allocation. - /// For instance, no known 64-bit platform can ever serve a request - /// for 263 bytes due to page-table limitations or splitting the address space. - /// However, some 32-bit and 16-bit platforms may successfully serve a request for - /// more than `isize::MAX` bytes with things like Physical Address - /// Extension. As such, memory acquired directly from allocators or memory - /// mapped files *may* be too large to handle with this function. - /// (Note that [`offset`] and [`add`] also have a similar limitation and hence cannot be used on - /// such large allocations either.) - /// - /// The requirement for pointers to be derived from the same allocated object is primarily - /// needed for `const`-compatibility: the distance between pointers into *different* allocated - /// objects is not known at compile-time. However, the requirement also exists at - /// runtime and may be exploited by optimizations. If you wish to compute the difference between - /// pointers that are not guaranteed to be from the same allocation, use `(self as isize - - /// origin as isize) / mem::size_of::()`. - // FIXME: recommend `addr()` instead of `as usize` once that is stable. - /// - /// [`add`]: #method.add - /// [allocated object]: crate::ptr#allocated-object - /// - /// # Panics - /// - /// This function panics if `T` is a Zero-Sized Type ("ZST"). - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::ptr::NonNull; - /// - /// let a = [0; 5]; - /// let ptr1: NonNull = NonNull::from(&a[1]); - /// let ptr2: NonNull = NonNull::from(&a[3]); - /// unsafe { - /// assert_eq!(ptr2.offset_from(ptr1), 2); - /// assert_eq!(ptr1.offset_from(ptr2), -2); - /// assert_eq!(ptr1.offset(2), ptr2); - /// assert_eq!(ptr2.offset(-2), ptr1); - /// } - /// ``` - /// - /// *Incorrect* usage: - /// - /// ```rust,no_run - /// #![feature(strict_provenance)] - /// use std::ptr::NonNull; - /// - /// let ptr1 = NonNull::new(Box::into_raw(Box::new(0u8))).unwrap(); - /// let ptr2 = NonNull::new(Box::into_raw(Box::new(1u8))).unwrap(); - /// let diff = (ptr2.addr().get() as isize).wrapping_sub(ptr1.addr().get() as isize); - /// // Make ptr2_other an "alias" of ptr2, but derived from ptr1. - /// let ptr2_other = NonNull::new(ptr1.as_ptr().wrapping_byte_offset(diff)).unwrap(); - /// assert_eq!(ptr2.addr(), ptr2_other.addr()); - /// // Since ptr2_other and ptr2 are derived from pointers to different objects, - /// // computing their offset is undefined behavior, even though - /// // they point to the same address! - /// - /// let zero = unsafe { ptr2_other.offset_from(ptr2) }; // Undefined Behavior - /// ``` - #[inline] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - #[stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - pub const unsafe fn offset_from(self, origin: NonNull) -> isize - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `offset_from`. - unsafe { self.pointer.offset_from(origin.pointer) } - } - - /// Calculates the distance between two pointers. The returned value is in - /// units of **bytes**. - /// - /// This is purely a convenience for casting to a `u8` pointer and - /// using [`offset_from`][NonNull::offset_from] on it. See that method for - /// documentation and safety requirements. - /// - /// For non-`Sized` pointees this operation considers only the data pointers, - /// ignoring the metadata. - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - #[stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - pub const unsafe fn byte_offset_from(self, origin: NonNull) -> isize { - // SAFETY: the caller must uphold the safety contract for `byte_offset_from`. - unsafe { self.pointer.byte_offset_from(origin.pointer) } - } - - // N.B. `wrapping_offset``, `wrapping_add`, etc are not implemented because they can wrap to null - - /// Calculates the distance between two pointers, *where it's known that - /// `self` is equal to or greater than `origin`*. The returned value is in - /// units of T: the distance in bytes is divided by `mem::size_of::()`. - /// - /// This computes the same value that [`offset_from`](#method.offset_from) - /// would compute, but with the added precondition that the offset is - /// guaranteed to be non-negative. This method is equivalent to - /// `usize::try_from(self.offset_from(origin)).unwrap_unchecked()`, - /// but it provides slightly more information to the optimizer, which can - /// sometimes allow it to optimize slightly better with some backends. - /// - /// This method can be though of as recovering the `count` that was passed - /// to [`add`](#method.add) (or, with the parameters in the other order, - /// to [`sub`](#method.sub)). The following are all equivalent, assuming - /// that their safety preconditions are met: - /// ```rust - /// # #![feature(ptr_sub_ptr)] - /// # unsafe fn blah(ptr: std::ptr::NonNull, origin: std::ptr::NonNull, count: usize) -> bool { - /// ptr.sub_ptr(origin) == count - /// # && - /// origin.add(count) == ptr - /// # && - /// ptr.sub(count) == origin - /// # } - /// ``` - /// - /// # Safety - /// - /// - The distance between the pointers must be non-negative (`self >= origin`) - /// - /// - *All* the safety conditions of [`offset_from`](#method.offset_from) - /// apply to this method as well; see it for the full details. - /// - /// Importantly, despite the return type of this method being able to represent - /// a larger offset, it's still *not permitted* to pass pointers which differ - /// by more than `isize::MAX` *bytes*. As such, the result of this method will - /// always be less than or equal to `isize::MAX as usize`. - /// - /// # Panics - /// - /// This function panics if `T` is a Zero-Sized Type ("ZST"). - /// - /// # Examples - /// - /// ``` - /// #![feature(ptr_sub_ptr)] - /// use std::ptr::NonNull; - /// - /// let a = [0; 5]; - /// let ptr1: NonNull = NonNull::from(&a[1]); - /// let ptr2: NonNull = NonNull::from(&a[3]); - /// unsafe { - /// assert_eq!(ptr2.sub_ptr(ptr1), 2); - /// assert_eq!(ptr1.add(2), ptr2); - /// assert_eq!(ptr2.sub(2), ptr1); - /// assert_eq!(ptr2.sub_ptr(ptr2), 0); - /// } - /// - /// // This would be incorrect, as the pointers are not correctly ordered: - /// // ptr1.sub_ptr(ptr2) - /// ``` - #[inline] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - #[unstable(feature = "ptr_sub_ptr", issue = "95892")] - #[rustc_const_unstable(feature = "const_ptr_sub_ptr", issue = "95892")] - pub const unsafe fn sub_ptr(self, subtracted: NonNull) -> usize - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `sub_ptr`. - unsafe { self.pointer.sub_ptr(subtracted.pointer) } - } - - /// Reads the value from `self` without moving it. This leaves the - /// memory in `self` unchanged. - /// - /// See [`ptr::read`] for safety concerns and examples. - /// - /// [`ptr::read`]: crate::ptr::read() - #[inline] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - #[stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - pub const unsafe fn read(self) -> T - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `read`. - unsafe { ptr::read(self.pointer) } - } - - /// Performs a volatile read of the value from `self` without moving it. This - /// leaves the memory in `self` unchanged. - /// - /// Volatile operations are intended to act on I/O memory, and are guaranteed - /// to not be elided or reordered by the compiler across other volatile - /// operations. - /// - /// See [`ptr::read_volatile`] for safety concerns and examples. - /// - /// [`ptr::read_volatile`]: crate::ptr::read_volatile() - #[inline] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - #[stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - pub unsafe fn read_volatile(self) -> T - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `read_volatile`. - unsafe { ptr::read_volatile(self.pointer) } - } - - /// Reads the value from `self` without moving it. This leaves the - /// memory in `self` unchanged. - /// - /// Unlike `read`, the pointer may be unaligned. - /// - /// See [`ptr::read_unaligned`] for safety concerns and examples. - /// - /// [`ptr::read_unaligned`]: crate::ptr::read_unaligned() - #[inline] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - #[stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - pub const unsafe fn read_unaligned(self) -> T - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `read_unaligned`. - unsafe { ptr::read_unaligned(self.pointer) } - } - - /// Copies `count * size_of` bytes from `self` to `dest`. The source - /// and destination may overlap. - /// - /// NOTE: this has the *same* argument order as [`ptr::copy`]. - /// - /// See [`ptr::copy`] for safety concerns and examples. - /// - /// [`ptr::copy`]: crate::ptr::copy() - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - #[stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_unstable(feature = "const_intrinsic_copy", issue = "80697")] - pub const unsafe fn copy_to(self, dest: NonNull, count: usize) - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `copy`. - unsafe { ptr::copy(self.pointer, dest.as_ptr(), count) } - } - - /// Copies `count * size_of` bytes from `self` to `dest`. The source - /// and destination may *not* overlap. - /// - /// NOTE: this has the *same* argument order as [`ptr::copy_nonoverlapping`]. - /// - /// See [`ptr::copy_nonoverlapping`] for safety concerns and examples. - /// - /// [`ptr::copy_nonoverlapping`]: crate::ptr::copy_nonoverlapping() - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - #[stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_unstable(feature = "const_intrinsic_copy", issue = "80697")] - pub const unsafe fn copy_to_nonoverlapping(self, dest: NonNull, count: usize) - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `copy_nonoverlapping`. - unsafe { ptr::copy_nonoverlapping(self.pointer, dest.as_ptr(), count) } - } - - /// Copies `count * size_of` bytes from `src` to `self`. The source - /// and destination may overlap. - /// - /// NOTE: this has the *opposite* argument order of [`ptr::copy`]. - /// - /// See [`ptr::copy`] for safety concerns and examples. - /// - /// [`ptr::copy`]: crate::ptr::copy() - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - #[stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_unstable(feature = "const_intrinsic_copy", issue = "80697")] - pub const unsafe fn copy_from(self, src: NonNull, count: usize) - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `copy`. - unsafe { ptr::copy(src.pointer, self.as_ptr(), count) } - } - - /// Copies `count * size_of` bytes from `src` to `self`. The source - /// and destination may *not* overlap. - /// - /// NOTE: this has the *opposite* argument order of [`ptr::copy_nonoverlapping`]. - /// - /// See [`ptr::copy_nonoverlapping`] for safety concerns and examples. - /// - /// [`ptr::copy_nonoverlapping`]: crate::ptr::copy_nonoverlapping() - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - #[stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_unstable(feature = "const_intrinsic_copy", issue = "80697")] - pub const unsafe fn copy_from_nonoverlapping(self, src: NonNull, count: usize) - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `copy_nonoverlapping`. - unsafe { ptr::copy_nonoverlapping(src.pointer, self.as_ptr(), count) } - } - - /// Executes the destructor (if any) of the pointed-to value. - /// - /// See [`ptr::drop_in_place`] for safety concerns and examples. - /// - /// [`ptr::drop_in_place`]: crate::ptr::drop_in_place() - #[inline(always)] - #[stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - pub unsafe fn drop_in_place(self) { - // SAFETY: the caller must uphold the safety contract for `drop_in_place`. - unsafe { ptr::drop_in_place(self.as_ptr()) } - } - - /// Overwrites a memory location with the given value without reading or - /// dropping the old value. - /// - /// See [`ptr::write`] for safety concerns and examples. - /// - /// [`ptr::write`]: crate::ptr::write() - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - #[stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_unstable(feature = "const_ptr_write", issue = "86302")] - pub const unsafe fn write(self, val: T) - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `write`. - unsafe { ptr::write(self.as_ptr(), val) } - } - - /// Invokes memset on the specified pointer, setting `count * size_of::()` - /// bytes of memory starting at `self` to `val`. - /// - /// See [`ptr::write_bytes`] for safety concerns and examples. - /// - /// [`ptr::write_bytes`]: crate::ptr::write_bytes() - #[inline(always)] - #[doc(alias = "memset")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - #[stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_unstable(feature = "const_ptr_write", issue = "86302")] - pub const unsafe fn write_bytes(self, val: u8, count: usize) - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `write_bytes`. - unsafe { ptr::write_bytes(self.as_ptr(), val, count) } - } - - /// Performs a volatile write of a memory location with the given value without - /// reading or dropping the old value. - /// - /// Volatile operations are intended to act on I/O memory, and are guaranteed - /// to not be elided or reordered by the compiler across other volatile - /// operations. - /// - /// See [`ptr::write_volatile`] for safety concerns and examples. - /// - /// [`ptr::write_volatile`]: crate::ptr::write_volatile() - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - #[stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - pub unsafe fn write_volatile(self, val: T) - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `write_volatile`. - unsafe { ptr::write_volatile(self.as_ptr(), val) } - } - - /// Overwrites a memory location with the given value without reading or - /// dropping the old value. - /// - /// Unlike `write`, the pointer may be unaligned. - /// - /// See [`ptr::write_unaligned`] for safety concerns and examples. - /// - /// [`ptr::write_unaligned`]: crate::ptr::write_unaligned() - #[inline(always)] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - #[stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_unstable(feature = "const_ptr_write", issue = "86302")] - pub const unsafe fn write_unaligned(self, val: T) - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `write_unaligned`. - unsafe { ptr::write_unaligned(self.as_ptr(), val) } - } - - /// Replaces the value at `self` with `src`, returning the old - /// value, without dropping either. - /// - /// See [`ptr::replace`] for safety concerns and examples. - /// - /// [`ptr::replace`]: crate::ptr::replace() - #[inline(always)] - #[stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - pub unsafe fn replace(self, src: T) -> T - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `replace`. - unsafe { ptr::replace(self.as_ptr(), src) } - } - - /// Swaps the values at two mutable locations of the same type, without - /// deinitializing either. They may overlap, unlike `mem::swap` which is - /// otherwise equivalent. - /// - /// See [`ptr::swap`] for safety concerns and examples. - /// - /// [`ptr::swap`]: crate::ptr::swap() - #[inline(always)] - #[stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_unstable(feature = "const_swap", issue = "83163")] - pub const unsafe fn swap(self, with: NonNull) - where - T: Sized, - { - // SAFETY: the caller must uphold the safety contract for `swap`. - unsafe { ptr::swap(self.as_ptr(), with.as_ptr()) } - } - - /// Computes the offset that needs to be applied to the pointer in order to make it aligned to - /// `align`. - /// - /// If it is not possible to align the pointer, the implementation returns - /// `usize::MAX`. It is permissible for the implementation to *always* - /// return `usize::MAX`. Only your algorithm's performance can depend - /// on getting a usable offset here, not its correctness. - /// - /// The offset is expressed in number of `T` elements, and not bytes. - /// - /// There are no guarantees whatsoever that offsetting the pointer will not overflow or go - /// beyond the allocation that the pointer points into. It is up to the caller to ensure that - /// the returned offset is correct in all terms other than alignment. - /// - /// # Panics - /// - /// The function panics if `align` is not a power-of-two. - /// - /// # Examples - /// - /// Accessing adjacent `u8` as `u16` - /// - /// ``` - /// use std::mem::align_of; - /// use std::ptr::NonNull; - /// - /// # unsafe { - /// let x = [5_u8, 6, 7, 8, 9]; - /// let ptr = NonNull::new(x.as_ptr() as *mut u8).unwrap(); - /// let offset = ptr.align_offset(align_of::()); - /// - /// if offset < x.len() - 1 { - /// let u16_ptr = ptr.add(offset).cast::(); - /// assert!(u16_ptr.read() == u16::from_ne_bytes([5, 6]) || u16_ptr.read() == u16::from_ne_bytes([6, 7])); - /// } else { - /// // while the pointer can be aligned via `offset`, it would point - /// // outside the allocation - /// } - /// # } - /// ``` - #[inline] - #[must_use] - #[stable(feature = "non_null_convenience", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_unstable(feature = "const_align_offset", issue = "90962")] - pub const fn align_offset(self, align: usize) -> usize - where - T: Sized, - { - if !align.is_power_of_two() { - panic!("align_offset: align is not a power-of-two"); - } - - { - // SAFETY: `align` has been checked to be a power of 2 above. - unsafe { ptr::align_offset(self.pointer, align) } - } - } - - /// Returns whether the pointer is properly aligned for `T`. - /// - /// # Examples - /// - /// ``` - /// use std::ptr::NonNull; - /// - /// // On some platforms, the alignment of i32 is less than 4. - /// #[repr(align(4))] - /// struct AlignedI32(i32); - /// - /// let data = AlignedI32(42); - /// let ptr = NonNull::::from(&data); - /// - /// assert!(ptr.is_aligned()); - /// assert!(!NonNull::new(ptr.as_ptr().wrapping_byte_add(1)).unwrap().is_aligned()); - /// ``` - /// - /// # At compiletime - /// **Note: Alignment at compiletime is experimental and subject to change. See the - /// [tracking issue] for details.** - /// - /// At compiletime, the compiler may not know where a value will end up in memory. - /// Calling this function on a pointer created from a reference at compiletime will only - /// return `true` if the pointer is guaranteed to be aligned. This means that the pointer - /// is never aligned if cast to a type with a stricter alignment than the reference's - /// underlying allocation. - /// - /// ``` - /// #![feature(const_nonnull_new)] - /// #![feature(const_option)] - /// #![feature(const_pointer_is_aligned)] - /// use std::ptr::NonNull; - /// - /// // On some platforms, the alignment of primitives is less than their size. - /// #[repr(align(4))] - /// struct AlignedI32(i32); - /// #[repr(align(8))] - /// struct AlignedI64(i64); - /// - /// const _: () = { - /// let data = [AlignedI32(42), AlignedI32(42)]; - /// let ptr = NonNull::::new(&data[0] as *const _ as *mut _).unwrap(); - /// assert!(ptr.is_aligned()); - /// - /// // At runtime either `ptr1` or `ptr2` would be aligned, but at compiletime neither is aligned. - /// let ptr1 = ptr.cast::(); - /// let ptr2 = unsafe { ptr.add(1).cast::() }; - /// assert!(!ptr1.is_aligned()); - /// assert!(!ptr2.is_aligned()); - /// }; - /// ``` - /// - /// Due to this behavior, it is possible that a runtime pointer derived from a compiletime - /// pointer is aligned, even if the compiletime pointer wasn't aligned. - /// - /// ``` - /// #![feature(const_pointer_is_aligned)] - /// - /// // On some platforms, the alignment of primitives is less than their size. - /// #[repr(align(4))] - /// struct AlignedI32(i32); - /// #[repr(align(8))] - /// struct AlignedI64(i64); - /// - /// // At compiletime, neither `COMPTIME_PTR` nor `COMPTIME_PTR + 1` is aligned. - /// const COMPTIME_PTR: *const AlignedI32 = &AlignedI32(42); - /// const _: () = assert!(!COMPTIME_PTR.cast::().is_aligned()); - /// const _: () = assert!(!COMPTIME_PTR.wrapping_add(1).cast::().is_aligned()); - /// - /// // At runtime, either `runtime_ptr` or `runtime_ptr + 1` is aligned. - /// let runtime_ptr = COMPTIME_PTR; - /// assert_ne!( - /// runtime_ptr.cast::().is_aligned(), - /// runtime_ptr.wrapping_add(1).cast::().is_aligned(), - /// ); - /// ``` - /// - /// If a pointer is created from a fixed address, this function behaves the same during - /// runtime and compiletime. - /// - /// ``` - /// #![feature(const_pointer_is_aligned)] - /// #![feature(const_option)] - /// #![feature(const_nonnull_new)] - /// use std::ptr::NonNull; - /// - /// // On some platforms, the alignment of primitives is less than their size. - /// #[repr(align(4))] - /// struct AlignedI32(i32); - /// #[repr(align(8))] - /// struct AlignedI64(i64); - /// - /// const _: () = { - /// let ptr = NonNull::new(40 as *mut AlignedI32).unwrap(); - /// assert!(ptr.is_aligned()); - /// - /// // For pointers with a known address, runtime and compiletime behavior are identical. - /// let ptr1 = ptr.cast::(); - /// let ptr2 = NonNull::new(ptr.as_ptr().wrapping_add(1)).unwrap().cast::(); - /// assert!(ptr1.is_aligned()); - /// assert!(!ptr2.is_aligned()); - /// }; - /// ``` - /// - /// [tracking issue]: https://github.com/rust-lang/rust/issues/104203 - #[inline] - #[must_use] - #[stable(feature = "pointer_is_aligned", since = "1.79.0")] - #[rustc_const_unstable(feature = "const_pointer_is_aligned", issue = "104203")] - pub const fn is_aligned(self) -> bool - where - T: Sized, - { - self.pointer.is_aligned() - } - - /// Returns whether the pointer is aligned to `align`. - /// - /// For non-`Sized` pointees this operation considers only the data pointer, - /// ignoring the metadata. - /// - /// # Panics - /// - /// The function panics if `align` is not a power-of-two (this includes 0). - /// - /// # Examples - /// - /// ``` - /// #![feature(pointer_is_aligned_to)] - /// - /// // On some platforms, the alignment of i32 is less than 4. - /// #[repr(align(4))] - /// struct AlignedI32(i32); - /// - /// let data = AlignedI32(42); - /// let ptr = &data as *const AlignedI32; - /// - /// assert!(ptr.is_aligned_to(1)); - /// assert!(ptr.is_aligned_to(2)); - /// assert!(ptr.is_aligned_to(4)); - /// - /// assert!(ptr.wrapping_byte_add(2).is_aligned_to(2)); - /// assert!(!ptr.wrapping_byte_add(2).is_aligned_to(4)); - /// - /// assert_ne!(ptr.is_aligned_to(8), ptr.wrapping_add(1).is_aligned_to(8)); - /// ``` - /// - /// # At compiletime - /// **Note: Alignment at compiletime is experimental and subject to change. See the - /// [tracking issue] for details.** - /// - /// At compiletime, the compiler may not know where a value will end up in memory. - /// Calling this function on a pointer created from a reference at compiletime will only - /// return `true` if the pointer is guaranteed to be aligned. This means that the pointer - /// cannot be stricter aligned than the reference's underlying allocation. - /// - /// ``` - /// #![feature(pointer_is_aligned_to)] - /// #![feature(const_pointer_is_aligned)] - /// - /// // On some platforms, the alignment of i32 is less than 4. - /// #[repr(align(4))] - /// struct AlignedI32(i32); - /// - /// const _: () = { - /// let data = AlignedI32(42); - /// let ptr = &data as *const AlignedI32; - /// - /// assert!(ptr.is_aligned_to(1)); - /// assert!(ptr.is_aligned_to(2)); - /// assert!(ptr.is_aligned_to(4)); - /// - /// // At compiletime, we know for sure that the pointer isn't aligned to 8. - /// assert!(!ptr.is_aligned_to(8)); - /// assert!(!ptr.wrapping_add(1).is_aligned_to(8)); - /// }; - /// ``` - /// - /// Due to this behavior, it is possible that a runtime pointer derived from a compiletime - /// pointer is aligned, even if the compiletime pointer wasn't aligned. - /// - /// ``` - /// #![feature(pointer_is_aligned_to)] - /// #![feature(const_pointer_is_aligned)] - /// - /// // On some platforms, the alignment of i32 is less than 4. - /// #[repr(align(4))] - /// struct AlignedI32(i32); - /// - /// // At compiletime, neither `COMPTIME_PTR` nor `COMPTIME_PTR + 1` is aligned. - /// const COMPTIME_PTR: *const AlignedI32 = &AlignedI32(42); - /// const _: () = assert!(!COMPTIME_PTR.is_aligned_to(8)); - /// const _: () = assert!(!COMPTIME_PTR.wrapping_add(1).is_aligned_to(8)); - /// - /// // At runtime, either `runtime_ptr` or `runtime_ptr + 1` is aligned. - /// let runtime_ptr = COMPTIME_PTR; - /// assert_ne!( - /// runtime_ptr.is_aligned_to(8), - /// runtime_ptr.wrapping_add(1).is_aligned_to(8), - /// ); - /// ``` - /// - /// If a pointer is created from a fixed address, this function behaves the same during - /// runtime and compiletime. - /// - /// ``` - /// #![feature(pointer_is_aligned_to)] - /// #![feature(const_pointer_is_aligned)] - /// - /// const _: () = { - /// let ptr = 40 as *const u8; - /// assert!(ptr.is_aligned_to(1)); - /// assert!(ptr.is_aligned_to(2)); - /// assert!(ptr.is_aligned_to(4)); - /// assert!(ptr.is_aligned_to(8)); - /// assert!(!ptr.is_aligned_to(16)); - /// }; - /// ``` - /// - /// [tracking issue]: https://github.com/rust-lang/rust/issues/104203 - #[inline] - #[must_use] - #[unstable(feature = "pointer_is_aligned_to", issue = "96284")] - #[rustc_const_unstable(feature = "const_pointer_is_aligned", issue = "104203")] - pub const fn is_aligned_to(self, align: usize) -> bool { - self.pointer.is_aligned_to(align) - } -} - -impl NonNull<[T]> { - /// Creates a non-null raw slice from a thin pointer and a length. - /// - /// The `len` argument is the number of **elements**, not the number of bytes. - /// - /// This function is safe, but dereferencing the return value is unsafe. - /// See the documentation of [`slice::from_raw_parts`] for slice safety requirements. - /// - /// # Examples - /// - /// ```rust - /// use std::ptr::NonNull; - /// - /// // create a slice pointer when starting out with a pointer to the first element - /// let mut x = [5, 6, 7]; - /// let nonnull_pointer = NonNull::new(x.as_mut_ptr()).unwrap(); - /// let slice = NonNull::slice_from_raw_parts(nonnull_pointer, 3); - /// assert_eq!(unsafe { slice.as_ref()[2] }, 7); - /// ``` - /// - /// (Note that this example artificially demonstrates a use of this method, - /// but `let slice = NonNull::from(&x[..]);` would be a better way to write code like this.) - #[stable(feature = "nonnull_slice_from_raw_parts", since = "1.70.0")] - #[rustc_const_unstable(feature = "const_slice_from_raw_parts_mut", issue = "67456")] - #[must_use] - #[inline] - pub const fn slice_from_raw_parts(data: NonNull, len: usize) -> Self { - // SAFETY: `data` is a `NonNull` pointer which is necessarily non-null - unsafe { Self::new_unchecked(super::slice_from_raw_parts_mut(data.as_ptr(), len)) } - } - - /// Returns the length of a non-null raw slice. - /// - /// The returned value is the number of **elements**, not the number of bytes. - /// - /// This function is safe, even when the non-null raw slice cannot be dereferenced to a slice - /// because the pointer does not have a valid address. - /// - /// # Examples - /// - /// ```rust - /// use std::ptr::NonNull; - /// - /// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3); - /// assert_eq!(slice.len(), 3); - /// ``` - #[stable(feature = "slice_ptr_len_nonnull", since = "1.63.0")] - #[rustc_const_stable(feature = "const_slice_ptr_len_nonnull", since = "1.63.0")] - #[must_use] - #[inline] - pub const fn len(self) -> usize { - self.as_ptr().len() - } - - /// Returns `true` if the non-null raw slice has a length of 0. - /// - /// # Examples - /// - /// ```rust - /// use std::ptr::NonNull; - /// - /// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3); - /// assert!(!slice.is_empty()); - /// ``` - #[stable(feature = "slice_ptr_is_empty_nonnull", since = "1.79.0")] - #[rustc_const_stable(feature = "const_slice_ptr_is_empty_nonnull", since = "1.79.0")] - #[must_use] - #[inline] - pub const fn is_empty(self) -> bool { - self.len() == 0 - } - - /// Returns a non-null pointer to the slice's buffer. - /// - /// # Examples - /// - /// ```rust - /// #![feature(slice_ptr_get)] - /// use std::ptr::NonNull; - /// - /// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3); - /// assert_eq!(slice.as_non_null_ptr(), NonNull::::dangling()); - /// ``` - #[inline] - #[must_use] - #[unstable(feature = "slice_ptr_get", issue = "74265")] - #[rustc_const_unstable(feature = "slice_ptr_get", issue = "74265")] - pub const fn as_non_null_ptr(self) -> NonNull { - self.cast() - } - - /// Returns a raw pointer to the slice's buffer. - /// - /// # Examples - /// - /// ```rust - /// #![feature(slice_ptr_get)] - /// use std::ptr::NonNull; - /// - /// let slice: NonNull<[i8]> = NonNull::slice_from_raw_parts(NonNull::dangling(), 3); - /// assert_eq!(slice.as_mut_ptr(), NonNull::::dangling().as_ptr()); - /// ``` - #[inline] - #[must_use] - #[unstable(feature = "slice_ptr_get", issue = "74265")] - #[rustc_const_unstable(feature = "slice_ptr_get", issue = "74265")] - #[rustc_never_returns_null_ptr] - pub const fn as_mut_ptr(self) -> *mut T { - self.as_non_null_ptr().as_ptr() - } - - /// Returns a shared reference to a slice of possibly uninitialized values. In contrast to - /// [`as_ref`], this does not require that the value has to be initialized. - /// - /// For the mutable counterpart see [`as_uninit_slice_mut`]. - /// - /// [`as_ref`]: NonNull::as_ref - /// [`as_uninit_slice_mut`]: NonNull::as_uninit_slice_mut - /// - /// # Safety - /// - /// When calling this method, you have to ensure that all of the following is true: - /// - /// * The pointer must be [valid] for reads for `ptr.len() * mem::size_of::()` many bytes, - /// and it must be properly aligned. This means in particular: - /// - /// * The entire memory range of this slice must be contained within a single allocated object! - /// Slices can never span across multiple allocated objects. - /// - /// * The pointer must be aligned even for zero-length slices. One - /// reason for this is that enum layout optimizations may rely on references - /// (including slices of any length) being aligned and non-null to distinguish - /// them from other data. You can obtain a pointer that is usable as `data` - /// for zero-length slices using [`NonNull::dangling()`]. - /// - /// * The total size `ptr.len() * mem::size_of::()` of the slice must be no larger than `isize::MAX`. - /// See the safety documentation of [`pointer::offset`]. - /// - /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is - /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. - /// In particular, while this reference exists, the memory the pointer points to must - /// not get mutated (except inside `UnsafeCell`). - /// - /// This applies even if the result of this method is unused! - /// - /// See also [`slice::from_raw_parts`]. - /// - /// [valid]: crate::ptr#safety - #[inline] - #[must_use] - #[unstable(feature = "ptr_as_uninit", issue = "75402")] - #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")] - pub const unsafe fn as_uninit_slice<'a>(self) -> &'a [MaybeUninit] { - // SAFETY: the caller must uphold the safety contract for `as_uninit_slice`. - unsafe { slice::from_raw_parts(self.cast().as_ptr(), self.len()) } - } - - /// Returns a unique reference to a slice of possibly uninitialized values. In contrast to - /// [`as_mut`], this does not require that the value has to be initialized. - /// - /// For the shared counterpart see [`as_uninit_slice`]. - /// - /// [`as_mut`]: NonNull::as_mut - /// [`as_uninit_slice`]: NonNull::as_uninit_slice - /// - /// # Safety - /// - /// When calling this method, you have to ensure that all of the following is true: - /// - /// * The pointer must be [valid] for reads and writes for `ptr.len() * mem::size_of::()` - /// many bytes, and it must be properly aligned. This means in particular: - /// - /// * The entire memory range of this slice must be contained within a single allocated object! - /// Slices can never span across multiple allocated objects. - /// - /// * The pointer must be aligned even for zero-length slices. One - /// reason for this is that enum layout optimizations may rely on references - /// (including slices of any length) being aligned and non-null to distinguish - /// them from other data. You can obtain a pointer that is usable as `data` - /// for zero-length slices using [`NonNull::dangling()`]. - /// - /// * The total size `ptr.len() * mem::size_of::()` of the slice must be no larger than `isize::MAX`. - /// See the safety documentation of [`pointer::offset`]. - /// - /// * You must enforce Rust's aliasing rules, since the returned lifetime `'a` is - /// arbitrarily chosen and does not necessarily reflect the actual lifetime of the data. - /// In particular, while this reference exists, the memory the pointer points to must - /// not get accessed (read or written) through any other pointer. - /// - /// This applies even if the result of this method is unused! - /// - /// See also [`slice::from_raw_parts_mut`]. - /// - /// [valid]: crate::ptr#safety - /// - /// # Examples - /// - /// ```rust - /// #![feature(allocator_api, ptr_as_uninit)] - /// - /// use std::alloc::{Allocator, Layout, Global}; - /// use std::mem::MaybeUninit; - /// use std::ptr::NonNull; - /// - /// let memory: NonNull<[u8]> = Global.allocate(Layout::new::<[u8; 32]>())?; - /// // This is safe as `memory` is valid for reads and writes for `memory.len()` many bytes. - /// // Note that calling `memory.as_mut()` is not allowed here as the content may be uninitialized. - /// # #[allow(unused_variables)] - /// let slice: &mut [MaybeUninit] = unsafe { memory.as_uninit_slice_mut() }; - /// # Ok::<_, std::alloc::AllocError>(()) - /// ``` - #[inline] - #[must_use] - #[unstable(feature = "ptr_as_uninit", issue = "75402")] - #[rustc_const_unstable(feature = "const_ptr_as_ref", issue = "91822")] - pub const unsafe fn as_uninit_slice_mut<'a>(self) -> &'a mut [MaybeUninit] { - // SAFETY: the caller must uphold the safety contract for `as_uninit_slice_mut`. - unsafe { slice::from_raw_parts_mut(self.cast().as_ptr(), self.len()) } - } - - /// Returns a raw pointer to an element or subslice, without doing bounds - /// checking. - /// - /// Calling this method with an out-of-bounds index or when `self` is not dereferenceable - /// is *[undefined behavior]* even if the resulting pointer is not used. - /// - /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html - /// - /// # Examples - /// - /// ``` - /// #![feature(slice_ptr_get)] - /// use std::ptr::NonNull; - /// - /// let x = &mut [1, 2, 4]; - /// let x = NonNull::slice_from_raw_parts(NonNull::new(x.as_mut_ptr()).unwrap(), x.len()); - /// - /// unsafe { - /// assert_eq!(x.get_unchecked_mut(1).as_ptr(), x.as_non_null_ptr().as_ptr().add(1)); - /// } - /// ``` - #[unstable(feature = "slice_ptr_get", issue = "74265")] - #[inline] - pub unsafe fn get_unchecked_mut(self, index: I) -> NonNull - where - I: SliceIndex<[T]>, - { - // SAFETY: the caller ensures that `self` is dereferenceable and `index` in-bounds. - // As a consequence, the resulting pointer cannot be null. - unsafe { NonNull::new_unchecked(self.as_ptr().get_unchecked_mut(index)) } - } -} - -#[stable(feature = "nonnull", since = "1.25.0")] -impl Clone for NonNull { - #[inline(always)] - fn clone(&self) -> Self { - *self - } -} - -#[stable(feature = "nonnull", since = "1.25.0")] -impl Copy for NonNull {} - -#[unstable(feature = "coerce_unsized", issue = "18598")] -impl CoerceUnsized> for NonNull where T: Unsize {} - -#[unstable(feature = "dispatch_from_dyn", issue = "none")] -impl DispatchFromDyn> for NonNull where T: Unsize {} - -#[stable(feature = "nonnull", since = "1.25.0")] -impl fmt::Debug for NonNull { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Pointer::fmt(&self.as_ptr(), f) - } -} - -#[stable(feature = "nonnull", since = "1.25.0")] -impl fmt::Pointer for NonNull { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Pointer::fmt(&self.as_ptr(), f) - } -} - -#[stable(feature = "nonnull", since = "1.25.0")] -impl Eq for NonNull {} - -#[stable(feature = "nonnull", since = "1.25.0")] -impl PartialEq for NonNull { - #[inline] - #[allow(ambiguous_wide_pointer_comparisons)] - fn eq(&self, other: &Self) -> bool { - self.as_ptr() == other.as_ptr() - } -} - -#[stable(feature = "nonnull", since = "1.25.0")] -impl Ord for NonNull { - #[inline] - #[allow(ambiguous_wide_pointer_comparisons)] - fn cmp(&self, other: &Self) -> Ordering { - self.as_ptr().cmp(&other.as_ptr()) - } -} - -#[stable(feature = "nonnull", since = "1.25.0")] -impl PartialOrd for NonNull { - #[inline] - #[allow(ambiguous_wide_pointer_comparisons)] - fn partial_cmp(&self, other: &Self) -> Option { - self.as_ptr().partial_cmp(&other.as_ptr()) - } -} - -#[stable(feature = "nonnull", since = "1.25.0")] -impl hash::Hash for NonNull { - #[inline] - fn hash(&self, state: &mut H) { - self.as_ptr().hash(state) - } -} - -#[unstable(feature = "ptr_internals", issue = "none")] -impl From> for NonNull { - #[inline] - fn from(unique: Unique) -> Self { - unique.as_non_null_ptr() - } -} - -#[stable(feature = "nonnull", since = "1.25.0")] -impl From<&mut T> for NonNull { - /// Converts a `&mut T` to a `NonNull`. - /// - /// This conversion is safe and infallible since references cannot be null. - #[inline] - fn from(reference: &mut T) -> Self { - // SAFETY: A mutable reference cannot be null. - unsafe { NonNull { pointer: reference as *mut T } } - } -} - -#[stable(feature = "nonnull", since = "1.25.0")] -impl From<&T> for NonNull { - /// Converts a `&T` to a `NonNull`. - /// - /// This conversion is safe and infallible since references cannot be null. - #[inline] - fn from(reference: &T) -> Self { - // SAFETY: A reference cannot be null. - unsafe { NonNull { pointer: reference as *const T } } - } -} diff --git a/library/core/src/ptr/unique.rs b/library/core/src/ptr/unique.rs deleted file mode 100644 index b74d691e45427..0000000000000 --- a/library/core/src/ptr/unique.rs +++ /dev/null @@ -1,203 +0,0 @@ -use crate::fmt; -use crate::marker::{PhantomData, Unsize}; -use crate::ops::{CoerceUnsized, DispatchFromDyn}; -use crate::ptr::NonNull; - -/// A wrapper around a raw non-null `*mut T` that indicates that the possessor -/// of this wrapper owns the referent. Useful for building abstractions like -/// `Box`, `Vec`, `String`, and `HashMap`. -/// -/// Unlike `*mut T`, `Unique` behaves "as if" it were an instance of `T`. -/// It implements `Send`/`Sync` if `T` is `Send`/`Sync`. It also implies -/// the kind of strong aliasing guarantees an instance of `T` can expect: -/// the referent of the pointer should not be modified without a unique path to -/// its owning Unique. -/// -/// If you're uncertain of whether it's correct to use `Unique` for your purposes, -/// consider using `NonNull`, which has weaker semantics. -/// -/// Unlike `*mut T`, the pointer must always be non-null, even if the pointer -/// is never dereferenced. This is so that enums may use this forbidden value -/// as a discriminant -- `Option>` has the same size as `Unique`. -/// However the pointer may still dangle if it isn't dereferenced. -/// -/// Unlike `*mut T`, `Unique` is covariant over `T`. This should always be correct -/// for any type which upholds Unique's aliasing requirements. -#[unstable( - feature = "ptr_internals", - issue = "none", - reason = "use `NonNull` instead and consider `PhantomData` \ - (if you also use `#[may_dangle]`), `Send`, and/or `Sync`" -)] -#[doc(hidden)] -#[repr(transparent)] -// Lang item used experimentally by Miri to define the semantics of `Unique`. -#[lang = "ptr_unique"] -pub struct Unique { - pointer: NonNull, - // NOTE: this marker has no consequences for variance, but is necessary - // for dropck to understand that we logically own a `T`. - // - // For details, see: - // https://github.com/rust-lang/rfcs/blob/master/text/0769-sound-generic-drop.md#phantom-data - _marker: PhantomData, -} - -/// `Unique` pointers are `Send` if `T` is `Send` because the data they -/// reference is unaliased. Note that this aliasing invariant is -/// unenforced by the type system; the abstraction using the -/// `Unique` must enforce it. -#[unstable(feature = "ptr_internals", issue = "none")] -unsafe impl Send for Unique {} - -/// `Unique` pointers are `Sync` if `T` is `Sync` because the data they -/// reference is unaliased. Note that this aliasing invariant is -/// unenforced by the type system; the abstraction using the -/// `Unique` must enforce it. -#[unstable(feature = "ptr_internals", issue = "none")] -unsafe impl Sync for Unique {} - -#[unstable(feature = "ptr_internals", issue = "none")] -impl Unique { - /// Creates a new `Unique` that is dangling, but well-aligned. - /// - /// This is useful for initializing types which lazily allocate, like - /// `Vec::new` does. - /// - /// Note that the pointer value may potentially represent a valid pointer to - /// a `T`, which means this must not be used as a "not yet initialized" - /// sentinel value. Types that lazily allocate must track initialization by - /// some other means. - #[must_use] - #[inline] - pub const fn dangling() -> Self { - // FIXME(const-hack) replace with `From` - Unique { pointer: NonNull::dangling(), _marker: PhantomData } - } -} - -#[unstable(feature = "ptr_internals", issue = "none")] -impl Unique { - /// Creates a new `Unique`. - /// - /// # Safety - /// - /// `ptr` must be non-null. - #[inline] - pub const unsafe fn new_unchecked(ptr: *mut T) -> Self { - // SAFETY: the caller must guarantee that `ptr` is non-null. - unsafe { Unique { pointer: NonNull::new_unchecked(ptr), _marker: PhantomData } } - } - - /// Creates a new `Unique` if `ptr` is non-null. - #[inline] - pub const fn new(ptr: *mut T) -> Option { - if let Some(pointer) = NonNull::new(ptr) { - Some(Unique { pointer, _marker: PhantomData }) - } else { - None - } - } - - /// Acquires the underlying `*mut` pointer. - #[must_use = "`self` will be dropped if the result is not used"] - #[inline] - pub const fn as_ptr(self) -> *mut T { - self.pointer.as_ptr() - } - - /// Acquires the underlying `*mut` pointer. - #[must_use = "`self` will be dropped if the result is not used"] - #[inline] - pub const fn as_non_null_ptr(self) -> NonNull { - self.pointer - } - - /// Dereferences the content. - /// - /// The resulting lifetime is bound to self so this behaves "as if" - /// it were actually an instance of T that is getting borrowed. If a longer - /// (unbound) lifetime is needed, use `&*my_ptr.as_ptr()`. - #[must_use] - #[inline] - pub const unsafe fn as_ref(&self) -> &T { - // SAFETY: the caller must guarantee that `self` meets all the - // requirements for a reference. - unsafe { self.pointer.as_ref() } - } - - /// Mutably dereferences the content. - /// - /// The resulting lifetime is bound to self so this behaves "as if" - /// it were actually an instance of T that is getting borrowed. If a longer - /// (unbound) lifetime is needed, use `&mut *my_ptr.as_ptr()`. - #[must_use] - #[inline] - pub const unsafe fn as_mut(&mut self) -> &mut T { - // SAFETY: the caller must guarantee that `self` meets all the - // requirements for a mutable reference. - unsafe { self.pointer.as_mut() } - } - - /// Casts to a pointer of another type. - #[must_use = "`self` will be dropped if the result is not used"] - #[inline] - pub const fn cast(self) -> Unique { - // FIXME(const-hack): replace with `From` - // SAFETY: is `NonNull` - Unique { pointer: self.pointer.cast(), _marker: PhantomData } - } -} - -#[unstable(feature = "ptr_internals", issue = "none")] -impl Clone for Unique { - #[inline] - fn clone(&self) -> Self { - *self - } -} - -#[unstable(feature = "ptr_internals", issue = "none")] -impl Copy for Unique {} - -#[unstable(feature = "ptr_internals", issue = "none")] -impl CoerceUnsized> for Unique where T: Unsize {} - -#[unstable(feature = "ptr_internals", issue = "none")] -impl DispatchFromDyn> for Unique where T: Unsize {} - -#[unstable(feature = "ptr_internals", issue = "none")] -impl fmt::Debug for Unique { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Pointer::fmt(&self.as_ptr(), f) - } -} - -#[unstable(feature = "ptr_internals", issue = "none")] -impl fmt::Pointer for Unique { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Pointer::fmt(&self.as_ptr(), f) - } -} - -#[unstable(feature = "ptr_internals", issue = "none")] -impl From<&mut T> for Unique { - /// Converts a `&mut T` to a `Unique`. - /// - /// This conversion is infallible since references cannot be null. - #[inline] - fn from(reference: &mut T) -> Self { - Self::from(NonNull::from(reference)) - } -} - -#[unstable(feature = "ptr_internals", issue = "none")] -impl From> for Unique { - /// Converts a `NonNull` to a `Unique`. - /// - /// This conversion is infallible since `NonNull` cannot be null. - #[inline] - fn from(pointer: NonNull) -> Self { - Unique { pointer, _marker: PhantomData } - } -} diff --git a/library/core/src/result.rs b/library/core/src/result.rs deleted file mode 100644 index 4c6dc4bba4377..0000000000000 --- a/library/core/src/result.rs +++ /dev/null @@ -1,1984 +0,0 @@ -//! Error handling with the `Result` type. -//! -//! [`Result`][`Result`] is the type used for returning and propagating -//! errors. It is an enum with the variants, [`Ok(T)`], representing -//! success and containing a value, and [`Err(E)`], representing error -//! and containing an error value. -//! -//! ``` -//! # #[allow(dead_code)] -//! enum Result { -//! Ok(T), -//! Err(E), -//! } -//! ``` -//! -//! Functions return [`Result`] whenever errors are expected and -//! recoverable. In the `std` crate, [`Result`] is most prominently used -//! for [I/O](../../std/io/index.html). -//! -//! A simple function returning [`Result`] might be -//! defined and used like so: -//! -//! ``` -//! #[derive(Debug)] -//! enum Version { Version1, Version2 } -//! -//! fn parse_version(header: &[u8]) -> Result { -//! match header.get(0) { -//! None => Err("invalid header length"), -//! Some(&1) => Ok(Version::Version1), -//! Some(&2) => Ok(Version::Version2), -//! Some(_) => Err("invalid version"), -//! } -//! } -//! -//! let version = parse_version(&[1, 2, 3, 4]); -//! match version { -//! Ok(v) => println!("working with version: {v:?}"), -//! Err(e) => println!("error parsing header: {e:?}"), -//! } -//! ``` -//! -//! Pattern matching on [`Result`]s is clear and straightforward for -//! simple cases, but [`Result`] comes with some convenience methods -//! that make working with it more succinct. -//! -//! ``` -//! // The `is_ok` and `is_err` methods do what they say. -//! let good_result: Result = Ok(10); -//! let bad_result: Result = Err(10); -//! assert!(good_result.is_ok() && !good_result.is_err()); -//! assert!(bad_result.is_err() && !bad_result.is_ok()); -//! -//! // `map` and `map_err` consume the `Result` and produce another. -//! let good_result: Result = good_result.map(|i| i + 1); -//! let bad_result: Result = bad_result.map_err(|i| i - 1); -//! assert_eq!(good_result, Ok(11)); -//! assert_eq!(bad_result, Err(9)); -//! -//! // Use `and_then` to continue the computation. -//! let good_result: Result = good_result.and_then(|i| Ok(i == 11)); -//! assert_eq!(good_result, Ok(true)); -//! -//! // Use `or_else` to handle the error. -//! let bad_result: Result = bad_result.or_else(|i| Ok(i + 20)); -//! assert_eq!(bad_result, Ok(29)); -//! -//! // Consume the result and return the contents with `unwrap`. -//! let final_awesome_result = good_result.unwrap(); -//! assert!(final_awesome_result) -//! ``` -//! -//! # Results must be used -//! -//! A common problem with using return values to indicate errors is -//! that it is easy to ignore the return value, thus failing to handle -//! the error. [`Result`] is annotated with the `#[must_use]` attribute, -//! which will cause the compiler to issue a warning when a Result -//! value is ignored. This makes [`Result`] especially useful with -//! functions that may encounter errors but don't otherwise return a -//! useful value. -//! -//! Consider the [`write_all`] method defined for I/O types -//! by the [`Write`] trait: -//! -//! ``` -//! use std::io; -//! -//! trait Write { -//! fn write_all(&mut self, bytes: &[u8]) -> Result<(), io::Error>; -//! } -//! ``` -//! -//! *Note: The actual definition of [`Write`] uses [`io::Result`], which -//! is just a synonym for [Result].* -//! -//! This method doesn't produce a value, but the write may -//! fail. It's crucial to handle the error case, and *not* write -//! something like this: -//! -//! ```no_run -//! # #![allow(unused_must_use)] // \o/ -//! use std::fs::File; -//! use std::io::prelude::*; -//! -//! let mut file = File::create("valuable_data.txt").unwrap(); -//! // If `write_all` errors, then we'll never know, because the return -//! // value is ignored. -//! file.write_all(b"important message"); -//! ``` -//! -//! If you *do* write that in Rust, the compiler will give you a -//! warning (by default, controlled by the `unused_must_use` lint). -//! -//! You might instead, if you don't want to handle the error, simply -//! assert success with [`expect`]. This will panic if the -//! write fails, providing a marginally useful message indicating why: -//! -//! ```no_run -//! use std::fs::File; -//! use std::io::prelude::*; -//! -//! let mut file = File::create("valuable_data.txt").unwrap(); -//! file.write_all(b"important message").expect("failed to write message"); -//! ``` -//! -//! You might also simply assert success: -//! -//! ```no_run -//! # use std::fs::File; -//! # use std::io::prelude::*; -//! # let mut file = File::create("valuable_data.txt").unwrap(); -//! assert!(file.write_all(b"important message").is_ok()); -//! ``` -//! -//! Or propagate the error up the call stack with [`?`]: -//! -//! ``` -//! # use std::fs::File; -//! # use std::io::prelude::*; -//! # use std::io; -//! # #[allow(dead_code)] -//! fn write_message() -> io::Result<()> { -//! let mut file = File::create("valuable_data.txt")?; -//! file.write_all(b"important message")?; -//! Ok(()) -//! } -//! ``` -//! -//! # The question mark operator, `?` -//! -//! When writing code that calls many functions that return the -//! [`Result`] type, the error handling can be tedious. The question mark -//! operator, [`?`], hides some of the boilerplate of propagating errors -//! up the call stack. -//! -//! It replaces this: -//! -//! ``` -//! # #![allow(dead_code)] -//! use std::fs::File; -//! use std::io::prelude::*; -//! use std::io; -//! -//! struct Info { -//! name: String, -//! age: i32, -//! rating: i32, -//! } -//! -//! fn write_info(info: &Info) -> io::Result<()> { -//! // Early return on error -//! let mut file = match File::create("my_best_friends.txt") { -//! Err(e) => return Err(e), -//! Ok(f) => f, -//! }; -//! if let Err(e) = file.write_all(format!("name: {}\n", info.name).as_bytes()) { -//! return Err(e) -//! } -//! if let Err(e) = file.write_all(format!("age: {}\n", info.age).as_bytes()) { -//! return Err(e) -//! } -//! if let Err(e) = file.write_all(format!("rating: {}\n", info.rating).as_bytes()) { -//! return Err(e) -//! } -//! Ok(()) -//! } -//! ``` -//! -//! With this: -//! -//! ``` -//! # #![allow(dead_code)] -//! use std::fs::File; -//! use std::io::prelude::*; -//! use std::io; -//! -//! struct Info { -//! name: String, -//! age: i32, -//! rating: i32, -//! } -//! -//! fn write_info(info: &Info) -> io::Result<()> { -//! let mut file = File::create("my_best_friends.txt")?; -//! // Early return on error -//! file.write_all(format!("name: {}\n", info.name).as_bytes())?; -//! file.write_all(format!("age: {}\n", info.age).as_bytes())?; -//! file.write_all(format!("rating: {}\n", info.rating).as_bytes())?; -//! Ok(()) -//! } -//! ``` -//! -//! *It's much nicer!* -//! -//! Ending the expression with [`?`] will result in the [`Ok`]'s unwrapped value, unless the result -//! is [`Err`], in which case [`Err`] is returned early from the enclosing function. -//! -//! [`?`] can be used in functions that return [`Result`] because of the -//! early return of [`Err`] that it provides. -//! -//! [`expect`]: Result::expect -//! [`Write`]: ../../std/io/trait.Write.html "io::Write" -//! [`write_all`]: ../../std/io/trait.Write.html#method.write_all "io::Write::write_all" -//! [`io::Result`]: ../../std/io/type.Result.html "io::Result" -//! [`?`]: crate::ops::Try -//! [`Ok(T)`]: Ok -//! [`Err(E)`]: Err -//! [io::Error]: ../../std/io/struct.Error.html "io::Error" -//! -//! # Method overview -//! -//! In addition to working with pattern matching, [`Result`] provides a -//! wide variety of different methods. -//! -//! ## Querying the variant -//! -//! The [`is_ok`] and [`is_err`] methods return [`true`] if the [`Result`] -//! is [`Ok`] or [`Err`], respectively. -//! -//! [`is_err`]: Result::is_err -//! [`is_ok`]: Result::is_ok -//! -//! ## Adapters for working with references -//! -//! * [`as_ref`] converts from `&Result` to `Result<&T, &E>` -//! * [`as_mut`] converts from `&mut Result` to `Result<&mut T, &mut E>` -//! * [`as_deref`] converts from `&Result` to `Result<&T::Target, &E>` -//! * [`as_deref_mut`] converts from `&mut Result` to -//! `Result<&mut T::Target, &mut E>` -//! -//! [`as_deref`]: Result::as_deref -//! [`as_deref_mut`]: Result::as_deref_mut -//! [`as_mut`]: Result::as_mut -//! [`as_ref`]: Result::as_ref -//! -//! ## Extracting contained values -//! -//! These methods extract the contained value in a [`Result`] when it -//! is the [`Ok`] variant. If the [`Result`] is [`Err`]: -//! -//! * [`expect`] panics with a provided custom message -//! * [`unwrap`] panics with a generic message -//! * [`unwrap_or`] returns the provided default value -//! * [`unwrap_or_default`] returns the default value of the type `T` -//! (which must implement the [`Default`] trait) -//! * [`unwrap_or_else`] returns the result of evaluating the provided -//! function -//! -//! The panicking methods [`expect`] and [`unwrap`] require `E` to -//! implement the [`Debug`] trait. -//! -//! [`Debug`]: crate::fmt::Debug -//! [`expect`]: Result::expect -//! [`unwrap`]: Result::unwrap -//! [`unwrap_or`]: Result::unwrap_or -//! [`unwrap_or_default`]: Result::unwrap_or_default -//! [`unwrap_or_else`]: Result::unwrap_or_else -//! -//! These methods extract the contained value in a [`Result`] when it -//! is the [`Err`] variant. They require `T` to implement the [`Debug`] -//! trait. If the [`Result`] is [`Ok`]: -//! -//! * [`expect_err`] panics with a provided custom message -//! * [`unwrap_err`] panics with a generic message -//! -//! [`Debug`]: crate::fmt::Debug -//! [`expect_err`]: Result::expect_err -//! [`unwrap_err`]: Result::unwrap_err -//! -//! ## Transforming contained values -//! -//! These methods transform [`Result`] to [`Option`]: -//! -//! * [`err`][Result::err] transforms [`Result`] into [`Option`], -//! mapping [`Err(e)`] to [`Some(e)`] and [`Ok(v)`] to [`None`] -//! * [`ok`][Result::ok] transforms [`Result`] into [`Option`], -//! mapping [`Ok(v)`] to [`Some(v)`] and [`Err(e)`] to [`None`] -//! * [`transpose`] transposes a [`Result`] of an [`Option`] into an -//! [`Option`] of a [`Result`] -//! -// Do NOT add link reference definitions for `err` or `ok`, because they -// will generate numerous incorrect URLs for `Err` and `Ok` elsewhere, due -// to case folding. -//! -//! [`Err(e)`]: Err -//! [`Ok(v)`]: Ok -//! [`Some(e)`]: Option::Some -//! [`Some(v)`]: Option::Some -//! [`transpose`]: Result::transpose -//! -//! This method transforms the contained value of the [`Ok`] variant: -//! -//! * [`map`] transforms [`Result`] into [`Result`] by applying -//! the provided function to the contained value of [`Ok`] and leaving -//! [`Err`] values unchanged -//! -//! [`map`]: Result::map -//! -//! This method transforms the contained value of the [`Err`] variant: -//! -//! * [`map_err`] transforms [`Result`] into [`Result`] by -//! applying the provided function to the contained value of [`Err`] and -//! leaving [`Ok`] values unchanged -//! -//! [`map_err`]: Result::map_err -//! -//! These methods transform a [`Result`] into a value of a possibly -//! different type `U`: -//! -//! * [`map_or`] applies the provided function to the contained value of -//! [`Ok`], or returns the provided default value if the [`Result`] is -//! [`Err`] -//! * [`map_or_else`] applies the provided function to the contained value -//! of [`Ok`], or applies the provided default fallback function to the -//! contained value of [`Err`] -//! -//! [`map_or`]: Result::map_or -//! [`map_or_else`]: Result::map_or_else -//! -//! ## Boolean operators -//! -//! These methods treat the [`Result`] as a boolean value, where [`Ok`] -//! acts like [`true`] and [`Err`] acts like [`false`]. There are two -//! categories of these methods: ones that take a [`Result`] as input, and -//! ones that take a function as input (to be lazily evaluated). -//! -//! The [`and`] and [`or`] methods take another [`Result`] as input, and -//! produce a [`Result`] as output. The [`and`] method can produce a -//! [`Result`] value having a different inner type `U` than -//! [`Result`]. The [`or`] method can produce a [`Result`] -//! value having a different error type `F` than [`Result`]. -//! -//! | method | self | input | output | -//! |---------|----------|-----------|----------| -//! | [`and`] | `Err(e)` | (ignored) | `Err(e)` | -//! | [`and`] | `Ok(x)` | `Err(d)` | `Err(d)` | -//! | [`and`] | `Ok(x)` | `Ok(y)` | `Ok(y)` | -//! | [`or`] | `Err(e)` | `Err(d)` | `Err(d)` | -//! | [`or`] | `Err(e)` | `Ok(y)` | `Ok(y)` | -//! | [`or`] | `Ok(x)` | (ignored) | `Ok(x)` | -//! -//! [`and`]: Result::and -//! [`or`]: Result::or -//! -//! The [`and_then`] and [`or_else`] methods take a function as input, and -//! only evaluate the function when they need to produce a new value. The -//! [`and_then`] method can produce a [`Result`] value having a -//! different inner type `U` than [`Result`]. The [`or_else`] method -//! can produce a [`Result`] value having a different error type `F` -//! than [`Result`]. -//! -//! | method | self | function input | function result | output | -//! |--------------|----------|----------------|-----------------|----------| -//! | [`and_then`] | `Err(e)` | (not provided) | (not evaluated) | `Err(e)` | -//! | [`and_then`] | `Ok(x)` | `x` | `Err(d)` | `Err(d)` | -//! | [`and_then`] | `Ok(x)` | `x` | `Ok(y)` | `Ok(y)` | -//! | [`or_else`] | `Err(e)` | `e` | `Err(d)` | `Err(d)` | -//! | [`or_else`] | `Err(e)` | `e` | `Ok(y)` | `Ok(y)` | -//! | [`or_else`] | `Ok(x)` | (not provided) | (not evaluated) | `Ok(x)` | -//! -//! [`and_then`]: Result::and_then -//! [`or_else`]: Result::or_else -//! -//! ## Comparison operators -//! -//! If `T` and `E` both implement [`PartialOrd`] then [`Result`] will -//! derive its [`PartialOrd`] implementation. With this order, an [`Ok`] -//! compares as less than any [`Err`], while two [`Ok`] or two [`Err`] -//! compare as their contained values would in `T` or `E` respectively. If `T` -//! and `E` both also implement [`Ord`], then so does [`Result`]. -//! -//! ``` -//! assert!(Ok(1) < Err(0)); -//! let x: Result = Ok(0); -//! let y = Ok(1); -//! assert!(x < y); -//! let x: Result<(), i32> = Err(0); -//! let y = Err(1); -//! assert!(x < y); -//! ``` -//! -//! ## Iterating over `Result` -//! -//! A [`Result`] can be iterated over. This can be helpful if you need an -//! iterator that is conditionally empty. The iterator will either produce -//! a single value (when the [`Result`] is [`Ok`]), or produce no values -//! (when the [`Result`] is [`Err`]). For example, [`into_iter`] acts like -//! [`once(v)`] if the [`Result`] is [`Ok(v)`], and like [`empty()`] if the -//! [`Result`] is [`Err`]. -//! -//! [`Ok(v)`]: Ok -//! [`empty()`]: crate::iter::empty -//! [`once(v)`]: crate::iter::once -//! -//! Iterators over [`Result`] come in three types: -//! -//! * [`into_iter`] consumes the [`Result`] and produces the contained -//! value -//! * [`iter`] produces an immutable reference of type `&T` to the -//! contained value -//! * [`iter_mut`] produces a mutable reference of type `&mut T` to the -//! contained value -//! -//! See [Iterating over `Option`] for examples of how this can be useful. -//! -//! [Iterating over `Option`]: crate::option#iterating-over-option -//! [`into_iter`]: Result::into_iter -//! [`iter`]: Result::iter -//! [`iter_mut`]: Result::iter_mut -//! -//! You might want to use an iterator chain to do multiple instances of an -//! operation that can fail, but would like to ignore failures while -//! continuing to process the successful results. In this example, we take -//! advantage of the iterable nature of [`Result`] to select only the -//! [`Ok`] values using [`flatten`][Iterator::flatten]. -//! -//! ``` -//! # use std::str::FromStr; -//! let mut results = vec![]; -//! let mut errs = vec![]; -//! let nums: Vec<_> = ["17", "not a number", "99", "-27", "768"] -//! .into_iter() -//! .map(u8::from_str) -//! // Save clones of the raw `Result` values to inspect -//! .inspect(|x| results.push(x.clone())) -//! // Challenge: explain how this captures only the `Err` values -//! .inspect(|x| errs.extend(x.clone().err())) -//! .flatten() -//! .collect(); -//! assert_eq!(errs.len(), 3); -//! assert_eq!(nums, [17, 99]); -//! println!("results {results:?}"); -//! println!("errs {errs:?}"); -//! println!("nums {nums:?}"); -//! ``` -//! -//! ## Collecting into `Result` -//! -//! [`Result`] implements the [`FromIterator`][impl-FromIterator] trait, -//! which allows an iterator over [`Result`] values to be collected into a -//! [`Result`] of a collection of each contained value of the original -//! [`Result`] values, or [`Err`] if any of the elements was [`Err`]. -//! -//! [impl-FromIterator]: Result#impl-FromIterator%3CResult%3CA,+E%3E%3E-for-Result%3CV,+E%3E -//! -//! ``` -//! let v = [Ok(2), Ok(4), Err("err!"), Ok(8)]; -//! let res: Result, &str> = v.into_iter().collect(); -//! assert_eq!(res, Err("err!")); -//! let v = [Ok(2), Ok(4), Ok(8)]; -//! let res: Result, &str> = v.into_iter().collect(); -//! assert_eq!(res, Ok(vec![2, 4, 8])); -//! ``` -//! -//! [`Result`] also implements the [`Product`][impl-Product] and -//! [`Sum`][impl-Sum] traits, allowing an iterator over [`Result`] values -//! to provide the [`product`][Iterator::product] and -//! [`sum`][Iterator::sum] methods. -//! -//! [impl-Product]: Result#impl-Product%3CResult%3CU,+E%3E%3E-for-Result%3CT,+E%3E -//! [impl-Sum]: Result#impl-Sum%3CResult%3CU,+E%3E%3E-for-Result%3CT,+E%3E -//! -//! ``` -//! let v = [Err("error!"), Ok(1), Ok(2), Ok(3), Err("foo")]; -//! let res: Result = v.into_iter().sum(); -//! assert_eq!(res, Err("error!")); -//! let v = [Ok(1), Ok(2), Ok(21)]; -//! let res: Result = v.into_iter().product(); -//! assert_eq!(res, Ok(42)); -//! ``` - -#![stable(feature = "rust1", since = "1.0.0")] - -use crate::iter::{self, FusedIterator, TrustedLen}; -use crate::ops::{self, ControlFlow, Deref, DerefMut}; -use crate::{convert, fmt, hint}; - -/// `Result` is a type that represents either success ([`Ok`]) or failure ([`Err`]). -/// -/// See the [module documentation](self) for details. -#[derive(Copy, PartialEq, PartialOrd, Eq, Ord, Debug, Hash)] -#[must_use = "this `Result` may be an `Err` variant, which should be handled"] -#[rustc_diagnostic_item = "Result"] -#[stable(feature = "rust1", since = "1.0.0")] -pub enum Result { - /// Contains the success value - #[lang = "Ok"] - #[stable(feature = "rust1", since = "1.0.0")] - Ok(#[stable(feature = "rust1", since = "1.0.0")] T), - - /// Contains the error value - #[lang = "Err"] - #[stable(feature = "rust1", since = "1.0.0")] - Err(#[stable(feature = "rust1", since = "1.0.0")] E), -} - -///////////////////////////////////////////////////////////////////////////// -// Type implementation -///////////////////////////////////////////////////////////////////////////// - -impl Result { - ///////////////////////////////////////////////////////////////////////// - // Querying the contained values - ///////////////////////////////////////////////////////////////////////// - - /// Returns `true` if the result is [`Ok`]. - /// - /// # Examples - /// - /// ``` - /// let x: Result = Ok(-3); - /// assert_eq!(x.is_ok(), true); - /// - /// let x: Result = Err("Some error message"); - /// assert_eq!(x.is_ok(), false); - /// ``` - #[must_use = "if you intended to assert that this is ok, consider `.unwrap()` instead"] - #[rustc_const_stable(feature = "const_result_basics", since = "1.48.0")] - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub const fn is_ok(&self) -> bool { - matches!(*self, Ok(_)) - } - - /// Returns `true` if the result is [`Ok`] and the value inside of it matches a predicate. - /// - /// # Examples - /// - /// ``` - /// let x: Result = Ok(2); - /// assert_eq!(x.is_ok_and(|x| x > 1), true); - /// - /// let x: Result = Ok(0); - /// assert_eq!(x.is_ok_and(|x| x > 1), false); - /// - /// let x: Result = Err("hey"); - /// assert_eq!(x.is_ok_and(|x| x > 1), false); - /// ``` - #[must_use] - #[inline] - #[stable(feature = "is_some_and", since = "1.70.0")] - pub fn is_ok_and(self, f: impl FnOnce(T) -> bool) -> bool { - match self { - Err(_) => false, - Ok(x) => f(x), - } - } - - /// Returns `true` if the result is [`Err`]. - /// - /// # Examples - /// - /// ``` - /// let x: Result = Ok(-3); - /// assert_eq!(x.is_err(), false); - /// - /// let x: Result = Err("Some error message"); - /// assert_eq!(x.is_err(), true); - /// ``` - #[must_use = "if you intended to assert that this is err, consider `.unwrap_err()` instead"] - #[rustc_const_stable(feature = "const_result_basics", since = "1.48.0")] - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub const fn is_err(&self) -> bool { - !self.is_ok() - } - - /// Returns `true` if the result is [`Err`] and the value inside of it matches a predicate. - /// - /// # Examples - /// - /// ``` - /// use std::io::{Error, ErrorKind}; - /// - /// let x: Result = Err(Error::new(ErrorKind::NotFound, "!")); - /// assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), true); - /// - /// let x: Result = Err(Error::new(ErrorKind::PermissionDenied, "!")); - /// assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false); - /// - /// let x: Result = Ok(123); - /// assert_eq!(x.is_err_and(|x| x.kind() == ErrorKind::NotFound), false); - /// ``` - #[must_use] - #[inline] - #[stable(feature = "is_some_and", since = "1.70.0")] - pub fn is_err_and(self, f: impl FnOnce(E) -> bool) -> bool { - match self { - Ok(_) => false, - Err(e) => f(e), - } - } - - ///////////////////////////////////////////////////////////////////////// - // Adapter for each variant - ///////////////////////////////////////////////////////////////////////// - - /// Converts from `Result` to [`Option`]. - /// - /// Converts `self` into an [`Option`], consuming `self`, - /// and discarding the error, if any. - /// - /// # Examples - /// - /// ``` - /// let x: Result = Ok(2); - /// assert_eq!(x.ok(), Some(2)); - /// - /// let x: Result = Err("Nothing here"); - /// assert_eq!(x.ok(), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn ok(self) -> Option { - match self { - Ok(x) => Some(x), - Err(_) => None, - } - } - - /// Converts from `Result` to [`Option`]. - /// - /// Converts `self` into an [`Option`], consuming `self`, - /// and discarding the success value, if any. - /// - /// # Examples - /// - /// ``` - /// let x: Result = Ok(2); - /// assert_eq!(x.err(), None); - /// - /// let x: Result = Err("Nothing here"); - /// assert_eq!(x.err(), Some("Nothing here")); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn err(self) -> Option { - match self { - Ok(_) => None, - Err(x) => Some(x), - } - } - - ///////////////////////////////////////////////////////////////////////// - // Adapter for working with references - ///////////////////////////////////////////////////////////////////////// - - /// Converts from `&Result` to `Result<&T, &E>`. - /// - /// Produces a new `Result`, containing a reference - /// into the original, leaving the original in place. - /// - /// # Examples - /// - /// ``` - /// let x: Result = Ok(2); - /// assert_eq!(x.as_ref(), Ok(&2)); - /// - /// let x: Result = Err("Error"); - /// assert_eq!(x.as_ref(), Err(&"Error")); - /// ``` - #[inline] - #[rustc_const_stable(feature = "const_result_basics", since = "1.48.0")] - #[stable(feature = "rust1", since = "1.0.0")] - pub const fn as_ref(&self) -> Result<&T, &E> { - match *self { - Ok(ref x) => Ok(x), - Err(ref x) => Err(x), - } - } - - /// Converts from `&mut Result` to `Result<&mut T, &mut E>`. - /// - /// # Examples - /// - /// ``` - /// fn mutate(r: &mut Result) { - /// match r.as_mut() { - /// Ok(v) => *v = 42, - /// Err(e) => *e = 0, - /// } - /// } - /// - /// let mut x: Result = Ok(2); - /// mutate(&mut x); - /// assert_eq!(x.unwrap(), 42); - /// - /// let mut x: Result = Err(13); - /// mutate(&mut x); - /// assert_eq!(x.unwrap_err(), 0); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_result", issue = "82814")] - pub const fn as_mut(&mut self) -> Result<&mut T, &mut E> { - match *self { - Ok(ref mut x) => Ok(x), - Err(ref mut x) => Err(x), - } - } - - ///////////////////////////////////////////////////////////////////////// - // Transforming contained values - ///////////////////////////////////////////////////////////////////////// - - /// Maps a `Result` to `Result` by applying a function to a - /// contained [`Ok`] value, leaving an [`Err`] value untouched. - /// - /// This function can be used to compose the results of two functions. - /// - /// # Examples - /// - /// Print the numbers on each line of a string multiplied by two. - /// - /// ``` - /// let line = "1\n2\n3\n4\n"; - /// - /// for num in line.lines() { - /// match num.parse::().map(|i| i * 2) { - /// Ok(n) => println!("{n}"), - /// Err(..) => {} - /// } - /// } - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn map U>(self, op: F) -> Result { - match self { - Ok(t) => Ok(op(t)), - Err(e) => Err(e), - } - } - - /// Returns the provided default (if [`Err`]), or - /// applies a function to the contained value (if [`Ok`]). - /// - /// Arguments passed to `map_or` are eagerly evaluated; if you are passing - /// the result of a function call, it is recommended to use [`map_or_else`], - /// which is lazily evaluated. - /// - /// [`map_or_else`]: Result::map_or_else - /// - /// # Examples - /// - /// ``` - /// let x: Result<_, &str> = Ok("foo"); - /// assert_eq!(x.map_or(42, |v| v.len()), 3); - /// - /// let x: Result<&str, _> = Err("bar"); - /// assert_eq!(x.map_or(42, |v| v.len()), 42); - /// ``` - #[inline] - #[stable(feature = "result_map_or", since = "1.41.0")] - #[must_use = "if you don't need the returned value, use `if let` instead"] - pub fn map_or U>(self, default: U, f: F) -> U { - match self { - Ok(t) => f(t), - Err(_) => default, - } - } - - /// Maps a `Result` to `U` by applying fallback function `default` to - /// a contained [`Err`] value, or function `f` to a contained [`Ok`] value. - /// - /// This function can be used to unpack a successful result - /// while handling an error. - /// - /// - /// # Examples - /// - /// ``` - /// let k = 21; - /// - /// let x : Result<_, &str> = Ok("foo"); - /// assert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 3); - /// - /// let x : Result<&str, _> = Err("bar"); - /// assert_eq!(x.map_or_else(|e| k * 2, |v| v.len()), 42); - /// ``` - #[inline] - #[stable(feature = "result_map_or_else", since = "1.41.0")] - pub fn map_or_else U, F: FnOnce(T) -> U>(self, default: D, f: F) -> U { - match self { - Ok(t) => f(t), - Err(e) => default(e), - } - } - - /// Maps a `Result` to `Result` by applying a function to a - /// contained [`Err`] value, leaving an [`Ok`] value untouched. - /// - /// This function can be used to pass through a successful result while handling - /// an error. - /// - /// - /// # Examples - /// - /// ``` - /// fn stringify(x: u32) -> String { format!("error code: {x}") } - /// - /// let x: Result = Ok(2); - /// assert_eq!(x.map_err(stringify), Ok(2)); - /// - /// let x: Result = Err(13); - /// assert_eq!(x.map_err(stringify), Err("error code: 13".to_string())); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn map_err F>(self, op: O) -> Result { - match self { - Ok(t) => Ok(t), - Err(e) => Err(op(e)), - } - } - - /// Calls a function with a reference to the contained value if [`Ok`]. - /// - /// Returns the original result. - /// - /// # Examples - /// - /// ``` - /// let x: u8 = "4" - /// .parse::() - /// .inspect(|x| println!("original: {x}")) - /// .map(|x| x.pow(3)) - /// .expect("failed to parse number"); - /// ``` - #[inline] - #[stable(feature = "result_option_inspect", since = "1.76.0")] - pub fn inspect(self, f: F) -> Self { - if let Ok(ref t) = self { - f(t); - } - - self - } - - /// Calls a function with a reference to the contained value if [`Err`]. - /// - /// Returns the original result. - /// - /// # Examples - /// - /// ``` - /// use std::{fs, io}; - /// - /// fn read() -> io::Result { - /// fs::read_to_string("address.txt") - /// .inspect_err(|e| eprintln!("failed to read file: {e}")) - /// } - /// ``` - #[inline] - #[stable(feature = "result_option_inspect", since = "1.76.0")] - pub fn inspect_err(self, f: F) -> Self { - if let Err(ref e) = self { - f(e); - } - - self - } - - /// Converts from `Result` (or `&Result`) to `Result<&::Target, &E>`. - /// - /// Coerces the [`Ok`] variant of the original [`Result`] via [`Deref`](crate::ops::Deref) - /// and returns the new [`Result`]. - /// - /// # Examples - /// - /// ``` - /// let x: Result = Ok("hello".to_string()); - /// let y: Result<&str, &u32> = Ok("hello"); - /// assert_eq!(x.as_deref(), y); - /// - /// let x: Result = Err(42); - /// let y: Result<&str, &u32> = Err(&42); - /// assert_eq!(x.as_deref(), y); - /// ``` - #[inline] - #[stable(feature = "inner_deref", since = "1.47.0")] - pub fn as_deref(&self) -> Result<&T::Target, &E> - where - T: Deref, - { - self.as_ref().map(|t| t.deref()) - } - - /// Converts from `Result` (or `&mut Result`) to `Result<&mut ::Target, &mut E>`. - /// - /// Coerces the [`Ok`] variant of the original [`Result`] via [`DerefMut`](crate::ops::DerefMut) - /// and returns the new [`Result`]. - /// - /// # Examples - /// - /// ``` - /// let mut s = "HELLO".to_string(); - /// let mut x: Result = Ok("hello".to_string()); - /// let y: Result<&mut str, &mut u32> = Ok(&mut s); - /// assert_eq!(x.as_deref_mut().map(|x| { x.make_ascii_uppercase(); x }), y); - /// - /// let mut i = 42; - /// let mut x: Result = Err(42); - /// let y: Result<&mut str, &mut u32> = Err(&mut i); - /// assert_eq!(x.as_deref_mut().map(|x| { x.make_ascii_uppercase(); x }), y); - /// ``` - #[inline] - #[stable(feature = "inner_deref", since = "1.47.0")] - pub fn as_deref_mut(&mut self) -> Result<&mut T::Target, &mut E> - where - T: DerefMut, - { - self.as_mut().map(|t| t.deref_mut()) - } - - ///////////////////////////////////////////////////////////////////////// - // Iterator constructors - ///////////////////////////////////////////////////////////////////////// - - /// Returns an iterator over the possibly contained value. - /// - /// The iterator yields one value if the result is [`Result::Ok`], otherwise none. - /// - /// # Examples - /// - /// ``` - /// let x: Result = Ok(7); - /// assert_eq!(x.iter().next(), Some(&7)); - /// - /// let x: Result = Err("nothing!"); - /// assert_eq!(x.iter().next(), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn iter(&self) -> Iter<'_, T> { - Iter { inner: self.as_ref().ok() } - } - - /// Returns a mutable iterator over the possibly contained value. - /// - /// The iterator yields one value if the result is [`Result::Ok`], otherwise none. - /// - /// # Examples - /// - /// ``` - /// let mut x: Result = Ok(7); - /// match x.iter_mut().next() { - /// Some(v) => *v = 40, - /// None => {}, - /// } - /// assert_eq!(x, Ok(40)); - /// - /// let mut x: Result = Err("nothing!"); - /// assert_eq!(x.iter_mut().next(), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn iter_mut(&mut self) -> IterMut<'_, T> { - IterMut { inner: self.as_mut().ok() } - } - - ///////////////////////////////////////////////////////////////////////// - // Extract a value - ///////////////////////////////////////////////////////////////////////// - - /// Returns the contained [`Ok`] value, consuming the `self` value. - /// - /// Because this function may panic, its use is generally discouraged. - /// Instead, prefer to use pattern matching and handle the [`Err`] - /// case explicitly, or call [`unwrap_or`], [`unwrap_or_else`], or - /// [`unwrap_or_default`]. - /// - /// [`unwrap_or`]: Result::unwrap_or - /// [`unwrap_or_else`]: Result::unwrap_or_else - /// [`unwrap_or_default`]: Result::unwrap_or_default - /// - /// # Panics - /// - /// Panics if the value is an [`Err`], with a panic message including the - /// passed message, and the content of the [`Err`]. - /// - /// - /// # Examples - /// - /// ```should_panic - /// let x: Result = Err("emergency failure"); - /// x.expect("Testing expect"); // panics with `Testing expect: emergency failure` - /// ``` - /// - /// # Recommended Message Style - /// - /// We recommend that `expect` messages are used to describe the reason you - /// _expect_ the `Result` should be `Ok`. - /// - /// ```should_panic - /// let path = std::env::var("IMPORTANT_PATH") - /// .expect("env variable `IMPORTANT_PATH` should be set by `wrapper_script.sh`"); - /// ``` - /// - /// **Hint**: If you're having trouble remembering how to phrase expect - /// error messages remember to focus on the word "should" as in "env - /// variable should be set by blah" or "the given binary should be available - /// and executable by the current user". - /// - /// For more detail on expect message styles and the reasoning behind our recommendation please - /// refer to the section on ["Common Message - /// Styles"](../../std/error/index.html#common-message-styles) in the - /// [`std::error`](../../std/error/index.html) module docs. - #[inline] - #[track_caller] - #[stable(feature = "result_expect", since = "1.4.0")] - pub fn expect(self, msg: &str) -> T - where - E: fmt::Debug, - { - match self { - Ok(t) => t, - Err(e) => unwrap_failed(msg, &e), - } - } - - /// Returns the contained [`Ok`] value, consuming the `self` value. - /// - /// Because this function may panic, its use is generally discouraged. - /// Instead, prefer to use pattern matching and handle the [`Err`] - /// case explicitly, or call [`unwrap_or`], [`unwrap_or_else`], or - /// [`unwrap_or_default`]. - /// - /// [`unwrap_or`]: Result::unwrap_or - /// [`unwrap_or_else`]: Result::unwrap_or_else - /// [`unwrap_or_default`]: Result::unwrap_or_default - /// - /// # Panics - /// - /// Panics if the value is an [`Err`], with a panic message provided by the - /// [`Err`]'s value. - /// - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let x: Result = Ok(2); - /// assert_eq!(x.unwrap(), 2); - /// ``` - /// - /// ```should_panic - /// let x: Result = Err("emergency failure"); - /// x.unwrap(); // panics with `emergency failure` - /// ``` - #[inline(always)] - #[track_caller] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn unwrap(self) -> T - where - E: fmt::Debug, - { - match self { - Ok(t) => t, - Err(e) => unwrap_failed("called `Result::unwrap()` on an `Err` value", &e), - } - } - - /// Returns the contained [`Ok`] value or a default - /// - /// Consumes the `self` argument then, if [`Ok`], returns the contained - /// value, otherwise if [`Err`], returns the default value for that - /// type. - /// - /// # Examples - /// - /// Converts a string to an integer, turning poorly-formed strings - /// into 0 (the default value for integers). [`parse`] converts - /// a string to any other type that implements [`FromStr`], returning an - /// [`Err`] on error. - /// - /// ``` - /// let good_year_from_input = "1909"; - /// let bad_year_from_input = "190blarg"; - /// let good_year = good_year_from_input.parse().unwrap_or_default(); - /// let bad_year = bad_year_from_input.parse().unwrap_or_default(); - /// - /// assert_eq!(1909, good_year); - /// assert_eq!(0, bad_year); - /// ``` - /// - /// [`parse`]: str::parse - /// [`FromStr`]: crate::str::FromStr - #[inline] - #[stable(feature = "result_unwrap_or_default", since = "1.16.0")] - pub fn unwrap_or_default(self) -> T - where - T: Default, - { - match self { - Ok(x) => x, - Err(_) => Default::default(), - } - } - - /// Returns the contained [`Err`] value, consuming the `self` value. - /// - /// # Panics - /// - /// Panics if the value is an [`Ok`], with a panic message including the - /// passed message, and the content of the [`Ok`]. - /// - /// - /// # Examples - /// - /// ```should_panic - /// let x: Result = Ok(10); - /// x.expect_err("Testing expect_err"); // panics with `Testing expect_err: 10` - /// ``` - #[inline] - #[track_caller] - #[stable(feature = "result_expect_err", since = "1.17.0")] - pub fn expect_err(self, msg: &str) -> E - where - T: fmt::Debug, - { - match self { - Ok(t) => unwrap_failed(msg, &t), - Err(e) => e, - } - } - - /// Returns the contained [`Err`] value, consuming the `self` value. - /// - /// # Panics - /// - /// Panics if the value is an [`Ok`], with a custom panic message provided - /// by the [`Ok`]'s value. - /// - /// # Examples - /// - /// ```should_panic - /// let x: Result = Ok(2); - /// x.unwrap_err(); // panics with `2` - /// ``` - /// - /// ``` - /// let x: Result = Err("emergency failure"); - /// assert_eq!(x.unwrap_err(), "emergency failure"); - /// ``` - #[inline] - #[track_caller] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn unwrap_err(self) -> E - where - T: fmt::Debug, - { - match self { - Ok(t) => unwrap_failed("called `Result::unwrap_err()` on an `Ok` value", &t), - Err(e) => e, - } - } - - /// Returns the contained [`Ok`] value, but never panics. - /// - /// Unlike [`unwrap`], this method is known to never panic on the - /// result types it is implemented for. Therefore, it can be used - /// instead of `unwrap` as a maintainability safeguard that will fail - /// to compile if the error type of the `Result` is later changed - /// to an error that can actually occur. - /// - /// [`unwrap`]: Result::unwrap - /// - /// # Examples - /// - /// ``` - /// # #![feature(never_type)] - /// # #![feature(unwrap_infallible)] - /// - /// fn only_good_news() -> Result { - /// Ok("this is fine".into()) - /// } - /// - /// let s: String = only_good_news().into_ok(); - /// println!("{s}"); - /// ``` - #[unstable(feature = "unwrap_infallible", reason = "newly added", issue = "61695")] - #[inline] - pub fn into_ok(self) -> T - where - E: Into, - { - match self { - Ok(x) => x, - Err(e) => e.into(), - } - } - - /// Returns the contained [`Err`] value, but never panics. - /// - /// Unlike [`unwrap_err`], this method is known to never panic on the - /// result types it is implemented for. Therefore, it can be used - /// instead of `unwrap_err` as a maintainability safeguard that will fail - /// to compile if the ok type of the `Result` is later changed - /// to a type that can actually occur. - /// - /// [`unwrap_err`]: Result::unwrap_err - /// - /// # Examples - /// - /// ``` - /// # #![feature(never_type)] - /// # #![feature(unwrap_infallible)] - /// - /// fn only_bad_news() -> Result { - /// Err("Oops, it failed".into()) - /// } - /// - /// let error: String = only_bad_news().into_err(); - /// println!("{error}"); - /// ``` - #[unstable(feature = "unwrap_infallible", reason = "newly added", issue = "61695")] - #[inline] - pub fn into_err(self) -> E - where - T: Into, - { - match self { - Ok(x) => x.into(), - Err(e) => e, - } - } - - //////////////////////////////////////////////////////////////////////// - // Boolean operations on the values, eager and lazy - ///////////////////////////////////////////////////////////////////////// - - /// Returns `res` if the result is [`Ok`], otherwise returns the [`Err`] value of `self`. - /// - /// Arguments passed to `and` are eagerly evaluated; if you are passing the - /// result of a function call, it is recommended to use [`and_then`], which is - /// lazily evaluated. - /// - /// [`and_then`]: Result::and_then - /// - /// # Examples - /// - /// ``` - /// let x: Result = Ok(2); - /// let y: Result<&str, &str> = Err("late error"); - /// assert_eq!(x.and(y), Err("late error")); - /// - /// let x: Result = Err("early error"); - /// let y: Result<&str, &str> = Ok("foo"); - /// assert_eq!(x.and(y), Err("early error")); - /// - /// let x: Result = Err("not a 2"); - /// let y: Result<&str, &str> = Err("late error"); - /// assert_eq!(x.and(y), Err("not a 2")); - /// - /// let x: Result = Ok(2); - /// let y: Result<&str, &str> = Ok("different result type"); - /// assert_eq!(x.and(y), Ok("different result type")); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn and(self, res: Result) -> Result { - match self { - Ok(_) => res, - Err(e) => Err(e), - } - } - - /// Calls `op` if the result is [`Ok`], otherwise returns the [`Err`] value of `self`. - /// - /// - /// This function can be used for control flow based on `Result` values. - /// - /// # Examples - /// - /// ``` - /// fn sq_then_to_string(x: u32) -> Result { - /// x.checked_mul(x).map(|sq| sq.to_string()).ok_or("overflowed") - /// } - /// - /// assert_eq!(Ok(2).and_then(sq_then_to_string), Ok(4.to_string())); - /// assert_eq!(Ok(1_000_000).and_then(sq_then_to_string), Err("overflowed")); - /// assert_eq!(Err("not a number").and_then(sq_then_to_string), Err("not a number")); - /// ``` - /// - /// Often used to chain fallible operations that may return [`Err`]. - /// - /// ``` - /// use std::{io::ErrorKind, path::Path}; - /// - /// // Note: on Windows "/" maps to "C:\" - /// let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified()); - /// assert!(root_modified_time.is_ok()); - /// - /// let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified()); - /// assert!(should_fail.is_err()); - /// assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("flat_map", "flatmap")] - pub fn and_then Result>(self, op: F) -> Result { - match self { - Ok(t) => op(t), - Err(e) => Err(e), - } - } - - /// Returns `res` if the result is [`Err`], otherwise returns the [`Ok`] value of `self`. - /// - /// Arguments passed to `or` are eagerly evaluated; if you are passing the - /// result of a function call, it is recommended to use [`or_else`], which is - /// lazily evaluated. - /// - /// [`or_else`]: Result::or_else - /// - /// # Examples - /// - /// ``` - /// let x: Result = Ok(2); - /// let y: Result = Err("late error"); - /// assert_eq!(x.or(y), Ok(2)); - /// - /// let x: Result = Err("early error"); - /// let y: Result = Ok(2); - /// assert_eq!(x.or(y), Ok(2)); - /// - /// let x: Result = Err("not a 2"); - /// let y: Result = Err("late error"); - /// assert_eq!(x.or(y), Err("late error")); - /// - /// let x: Result = Ok(2); - /// let y: Result = Ok(100); - /// assert_eq!(x.or(y), Ok(2)); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn or(self, res: Result) -> Result { - match self { - Ok(v) => Ok(v), - Err(_) => res, - } - } - - /// Calls `op` if the result is [`Err`], otherwise returns the [`Ok`] value of `self`. - /// - /// This function can be used for control flow based on result values. - /// - /// - /// # Examples - /// - /// ``` - /// fn sq(x: u32) -> Result { Ok(x * x) } - /// fn err(x: u32) -> Result { Err(x) } - /// - /// assert_eq!(Ok(2).or_else(sq).or_else(sq), Ok(2)); - /// assert_eq!(Ok(2).or_else(err).or_else(sq), Ok(2)); - /// assert_eq!(Err(3).or_else(sq).or_else(err), Ok(9)); - /// assert_eq!(Err(3).or_else(err).or_else(err), Err(3)); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn or_else Result>(self, op: O) -> Result { - match self { - Ok(t) => Ok(t), - Err(e) => op(e), - } - } - - /// Returns the contained [`Ok`] value or a provided default. - /// - /// Arguments passed to `unwrap_or` are eagerly evaluated; if you are passing - /// the result of a function call, it is recommended to use [`unwrap_or_else`], - /// which is lazily evaluated. - /// - /// [`unwrap_or_else`]: Result::unwrap_or_else - /// - /// # Examples - /// - /// ``` - /// let default = 2; - /// let x: Result = Ok(9); - /// assert_eq!(x.unwrap_or(default), 9); - /// - /// let x: Result = Err("error"); - /// assert_eq!(x.unwrap_or(default), default); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn unwrap_or(self, default: T) -> T { - match self { - Ok(t) => t, - Err(_) => default, - } - } - - /// Returns the contained [`Ok`] value or computes it from a closure. - /// - /// - /// # Examples - /// - /// ``` - /// fn count(x: &str) -> usize { x.len() } - /// - /// assert_eq!(Ok(2).unwrap_or_else(count), 2); - /// assert_eq!(Err("foo").unwrap_or_else(count), 3); - /// ``` - #[inline] - #[track_caller] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn unwrap_or_else T>(self, op: F) -> T { - match self { - Ok(t) => t, - Err(e) => op(e), - } - } - - /// Returns the contained [`Ok`] value, consuming the `self` value, - /// without checking that the value is not an [`Err`]. - /// - /// # Safety - /// - /// Calling this method on an [`Err`] is *[undefined behavior]*. - /// - /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html - /// - /// # Examples - /// - /// ``` - /// let x: Result = Ok(2); - /// assert_eq!(unsafe { x.unwrap_unchecked() }, 2); - /// ``` - /// - /// ```no_run - /// let x: Result = Err("emergency failure"); - /// unsafe { x.unwrap_unchecked(); } // Undefined behavior! - /// ``` - #[inline] - #[track_caller] - #[stable(feature = "option_result_unwrap_unchecked", since = "1.58.0")] - pub unsafe fn unwrap_unchecked(self) -> T { - debug_assert!(self.is_ok()); - match self { - Ok(t) => t, - // SAFETY: the safety contract must be upheld by the caller. - Err(_) => unsafe { hint::unreachable_unchecked() }, - } - } - - /// Returns the contained [`Err`] value, consuming the `self` value, - /// without checking that the value is not an [`Ok`]. - /// - /// # Safety - /// - /// Calling this method on an [`Ok`] is *[undefined behavior]*. - /// - /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html - /// - /// # Examples - /// - /// ```no_run - /// let x: Result = Ok(2); - /// unsafe { x.unwrap_err_unchecked() }; // Undefined behavior! - /// ``` - /// - /// ``` - /// let x: Result = Err("emergency failure"); - /// assert_eq!(unsafe { x.unwrap_err_unchecked() }, "emergency failure"); - /// ``` - #[inline] - #[track_caller] - #[stable(feature = "option_result_unwrap_unchecked", since = "1.58.0")] - pub unsafe fn unwrap_err_unchecked(self) -> E { - debug_assert!(self.is_err()); - match self { - // SAFETY: the safety contract must be upheld by the caller. - Ok(_) => unsafe { hint::unreachable_unchecked() }, - Err(e) => e, - } - } -} - -impl Result<&T, E> { - /// Maps a `Result<&T, E>` to a `Result` by copying the contents of the - /// `Ok` part. - /// - /// # Examples - /// - /// ``` - /// let val = 12; - /// let x: Result<&i32, i32> = Ok(&val); - /// assert_eq!(x, Ok(&12)); - /// let copied = x.copied(); - /// assert_eq!(copied, Ok(12)); - /// ``` - #[inline] - #[stable(feature = "result_copied", since = "1.59.0")] - pub fn copied(self) -> Result - where - T: Copy, - { - self.map(|&t| t) - } - - /// Maps a `Result<&T, E>` to a `Result` by cloning the contents of the - /// `Ok` part. - /// - /// # Examples - /// - /// ``` - /// let val = 12; - /// let x: Result<&i32, i32> = Ok(&val); - /// assert_eq!(x, Ok(&12)); - /// let cloned = x.cloned(); - /// assert_eq!(cloned, Ok(12)); - /// ``` - #[inline] - #[stable(feature = "result_cloned", since = "1.59.0")] - pub fn cloned(self) -> Result - where - T: Clone, - { - self.map(|t| t.clone()) - } -} - -impl Result<&mut T, E> { - /// Maps a `Result<&mut T, E>` to a `Result` by copying the contents of the - /// `Ok` part. - /// - /// # Examples - /// - /// ``` - /// let mut val = 12; - /// let x: Result<&mut i32, i32> = Ok(&mut val); - /// assert_eq!(x, Ok(&mut 12)); - /// let copied = x.copied(); - /// assert_eq!(copied, Ok(12)); - /// ``` - #[inline] - #[stable(feature = "result_copied", since = "1.59.0")] - pub fn copied(self) -> Result - where - T: Copy, - { - self.map(|&mut t| t) - } - - /// Maps a `Result<&mut T, E>` to a `Result` by cloning the contents of the - /// `Ok` part. - /// - /// # Examples - /// - /// ``` - /// let mut val = 12; - /// let x: Result<&mut i32, i32> = Ok(&mut val); - /// assert_eq!(x, Ok(&mut 12)); - /// let cloned = x.cloned(); - /// assert_eq!(cloned, Ok(12)); - /// ``` - #[inline] - #[stable(feature = "result_cloned", since = "1.59.0")] - pub fn cloned(self) -> Result - where - T: Clone, - { - self.map(|t| t.clone()) - } -} - -impl Result, E> { - /// Transposes a `Result` of an `Option` into an `Option` of a `Result`. - /// - /// `Ok(None)` will be mapped to `None`. - /// `Ok(Some(_))` and `Err(_)` will be mapped to `Some(Ok(_))` and `Some(Err(_))`. - /// - /// # Examples - /// - /// ``` - /// #[derive(Debug, Eq, PartialEq)] - /// struct SomeErr; - /// - /// let x: Result, SomeErr> = Ok(Some(5)); - /// let y: Option> = Some(Ok(5)); - /// assert_eq!(x.transpose(), y); - /// ``` - #[inline] - #[stable(feature = "transpose_result", since = "1.33.0")] - #[rustc_const_unstable(feature = "const_result", issue = "82814")] - pub const fn transpose(self) -> Option> { - match self { - Ok(Some(x)) => Some(Ok(x)), - Ok(None) => None, - Err(e) => Some(Err(e)), - } - } -} - -impl Result, E> { - /// Converts from `Result, E>` to `Result` - /// - /// # Examples - /// - /// ``` - /// #![feature(result_flattening)] - /// let x: Result, u32> = Ok(Ok("hello")); - /// assert_eq!(Ok("hello"), x.flatten()); - /// - /// let x: Result, u32> = Ok(Err(6)); - /// assert_eq!(Err(6), x.flatten()); - /// - /// let x: Result, u32> = Err(6); - /// assert_eq!(Err(6), x.flatten()); - /// ``` - /// - /// Flattening only removes one level of nesting at a time: - /// - /// ``` - /// #![feature(result_flattening)] - /// let x: Result, u32>, u32> = Ok(Ok(Ok("hello"))); - /// assert_eq!(Ok(Ok("hello")), x.flatten()); - /// assert_eq!(Ok("hello"), x.flatten().flatten()); - /// ``` - #[inline] - #[unstable(feature = "result_flattening", issue = "70142")] - pub fn flatten(self) -> Result { - self.and_then(convert::identity) - } -} - -// This is a separate function to reduce the code size of the methods -#[cfg(not(feature = "panic_immediate_abort"))] -#[inline(never)] -#[cold] -#[track_caller] -fn unwrap_failed(msg: &str, error: &dyn fmt::Debug) -> ! { - panic!("{msg}: {error:?}") -} - -// This is a separate function to avoid constructing a `dyn Debug` -// that gets immediately thrown away, since vtables don't get cleaned up -// by dead code elimination if a trait object is constructed even if it goes -// unused -#[cfg(feature = "panic_immediate_abort")] -#[inline] -#[cold] -#[track_caller] -fn unwrap_failed(_msg: &str, _error: &T) -> ! { - panic!() -} - -///////////////////////////////////////////////////////////////////////////// -// Trait implementations -///////////////////////////////////////////////////////////////////////////// - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Result -where - T: Clone, - E: Clone, -{ - #[inline] - fn clone(&self) -> Self { - match self { - Ok(x) => Ok(x.clone()), - Err(x) => Err(x.clone()), - } - } - - #[inline] - fn clone_from(&mut self, source: &Self) { - match (self, source) { - (Ok(to), Ok(from)) => to.clone_from(from), - (Err(to), Err(from)) => to.clone_from(from), - (to, from) => *to = from.clone(), - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl IntoIterator for Result { - type Item = T; - type IntoIter = IntoIter; - - /// Returns a consuming iterator over the possibly contained value. - /// - /// The iterator yields one value if the result is [`Result::Ok`], otherwise none. - /// - /// # Examples - /// - /// ``` - /// let x: Result = Ok(5); - /// let v: Vec = x.into_iter().collect(); - /// assert_eq!(v, [5]); - /// - /// let x: Result = Err("nothing!"); - /// let v: Vec = x.into_iter().collect(); - /// assert_eq!(v, []); - /// ``` - #[inline] - fn into_iter(self) -> IntoIter { - IntoIter { inner: self.ok() } - } -} - -#[stable(since = "1.4.0", feature = "result_iter")] -impl<'a, T, E> IntoIterator for &'a Result { - type Item = &'a T; - type IntoIter = Iter<'a, T>; - - fn into_iter(self) -> Iter<'a, T> { - self.iter() - } -} - -#[stable(since = "1.4.0", feature = "result_iter")] -impl<'a, T, E> IntoIterator for &'a mut Result { - type Item = &'a mut T; - type IntoIter = IterMut<'a, T>; - - fn into_iter(self) -> IterMut<'a, T> { - self.iter_mut() - } -} - -///////////////////////////////////////////////////////////////////////////// -// The Result Iterators -///////////////////////////////////////////////////////////////////////////// - -/// An iterator over a reference to the [`Ok`] variant of a [`Result`]. -/// -/// The iterator yields one value if the result is [`Ok`], otherwise none. -/// -/// Created by [`Result::iter`]. -#[derive(Debug)] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Iter<'a, T: 'a> { - inner: Option<&'a T>, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> Iterator for Iter<'a, T> { - type Item = &'a T; - - #[inline] - fn next(&mut self) -> Option<&'a T> { - self.inner.take() - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - let n = if self.inner.is_some() { 1 } else { 0 }; - (n, Some(n)) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> DoubleEndedIterator for Iter<'a, T> { - #[inline] - fn next_back(&mut self) -> Option<&'a T> { - self.inner.take() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Iter<'_, T> {} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Iter<'_, T> {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for Iter<'_, A> {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Iter<'_, T> { - #[inline] - fn clone(&self) -> Self { - Iter { inner: self.inner } - } -} - -/// An iterator over a mutable reference to the [`Ok`] variant of a [`Result`]. -/// -/// Created by [`Result::iter_mut`]. -#[derive(Debug)] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct IterMut<'a, T: 'a> { - inner: Option<&'a mut T>, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> Iterator for IterMut<'a, T> { - type Item = &'a mut T; - - #[inline] - fn next(&mut self) -> Option<&'a mut T> { - self.inner.take() - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - let n = if self.inner.is_some() { 1 } else { 0 }; - (n, Some(n)) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> DoubleEndedIterator for IterMut<'a, T> { - #[inline] - fn next_back(&mut self) -> Option<&'a mut T> { - self.inner.take() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for IterMut<'_, T> {} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for IterMut<'_, T> {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for IterMut<'_, A> {} - -/// An iterator over the value in a [`Ok`] variant of a [`Result`]. -/// -/// The iterator yields one value if the result is [`Ok`], otherwise none. -/// -/// This struct is created by the [`into_iter`] method on -/// [`Result`] (provided by the [`IntoIterator`] trait). -/// -/// [`into_iter`]: IntoIterator::into_iter -#[derive(Clone, Debug)] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct IntoIter { - inner: Option, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for IntoIter { - type Item = T; - - #[inline] - fn next(&mut self) -> Option { - self.inner.take() - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - let n = if self.inner.is_some() { 1 } else { 0 }; - (n, Some(n)) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DoubleEndedIterator for IntoIter { - #[inline] - fn next_back(&mut self) -> Option { - self.inner.take() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for IntoIter {} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for IntoIter {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for IntoIter {} - -///////////////////////////////////////////////////////////////////////////// -// FromIterator -///////////////////////////////////////////////////////////////////////////// - -#[stable(feature = "rust1", since = "1.0.0")] -impl> FromIterator> for Result { - /// Takes each element in the `Iterator`: if it is an `Err`, no further - /// elements are taken, and the `Err` is returned. Should no `Err` occur, a - /// container with the values of each `Result` is returned. - /// - /// Here is an example which increments every integer in a vector, - /// checking for overflow: - /// - /// ``` - /// let v = vec![1, 2]; - /// let res: Result, &'static str> = v.iter().map(|x: &u32| - /// x.checked_add(1).ok_or("Overflow!") - /// ).collect(); - /// assert_eq!(res, Ok(vec![2, 3])); - /// ``` - /// - /// Here is another example that tries to subtract one from another list - /// of integers, this time checking for underflow: - /// - /// ``` - /// let v = vec![1, 2, 0]; - /// let res: Result, &'static str> = v.iter().map(|x: &u32| - /// x.checked_sub(1).ok_or("Underflow!") - /// ).collect(); - /// assert_eq!(res, Err("Underflow!")); - /// ``` - /// - /// Here is a variation on the previous example, showing that no - /// further elements are taken from `iter` after the first `Err`. - /// - /// ``` - /// let v = vec![3, 2, 1, 10]; - /// let mut shared = 0; - /// let res: Result, &'static str> = v.iter().map(|x: &u32| { - /// shared += x; - /// x.checked_sub(2).ok_or("Underflow!") - /// }).collect(); - /// assert_eq!(res, Err("Underflow!")); - /// assert_eq!(shared, 6); - /// ``` - /// - /// Since the third element caused an underflow, no further elements were taken, - /// so the final value of `shared` is 6 (= `3 + 2 + 1`), not 16. - #[inline] - fn from_iter>>(iter: I) -> Result { - iter::try_process(iter.into_iter(), |i| i.collect()) - } -} - -#[unstable(feature = "try_trait_v2", issue = "84277")] -impl ops::Try for Result { - type Output = T; - type Residual = Result; - - #[inline] - fn from_output(output: Self::Output) -> Self { - Ok(output) - } - - #[inline] - fn branch(self) -> ControlFlow { - match self { - Ok(v) => ControlFlow::Continue(v), - Err(e) => ControlFlow::Break(Err(e)), - } - } -} - -#[unstable(feature = "try_trait_v2", issue = "84277")] -impl> ops::FromResidual> for Result { - #[inline] - #[track_caller] - fn from_residual(residual: Result) -> Self { - match residual { - Err(e) => Err(From::from(e)), - } - } -} - -#[unstable(feature = "try_trait_v2_yeet", issue = "96374")] -impl> ops::FromResidual> for Result { - #[inline] - fn from_residual(ops::Yeet(e): ops::Yeet) -> Self { - Err(From::from(e)) - } -} - -#[unstable(feature = "try_trait_v2_residual", issue = "91285")] -impl ops::Residual for Result { - type TryType = Result; -} diff --git a/library/core/src/slice/ascii.rs b/library/core/src/slice/ascii.rs deleted file mode 100644 index 19c91ba2eb988..0000000000000 --- a/library/core/src/slice/ascii.rs +++ /dev/null @@ -1,419 +0,0 @@ -//! Operations on ASCII `[u8]`. - -use crate::ascii; -use crate::fmt::{self, Write}; -use crate::iter; -use crate::mem; -use crate::ops; -use core::ascii::EscapeDefault; - -#[cfg(not(test))] -impl [u8] { - /// Checks if all bytes in this slice are within the ASCII range. - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[rustc_const_stable(feature = "const_slice_is_ascii", since = "1.74.0")] - #[must_use] - #[inline] - pub const fn is_ascii(&self) -> bool { - is_ascii(self) - } - - /// If this slice [`is_ascii`](Self::is_ascii), returns it as a slice of - /// [ASCII characters](`ascii::Char`), otherwise returns `None`. - #[unstable(feature = "ascii_char", issue = "110998")] - #[must_use] - #[inline] - pub const fn as_ascii(&self) -> Option<&[ascii::Char]> { - if self.is_ascii() { - // SAFETY: Just checked that it's ASCII - Some(unsafe { self.as_ascii_unchecked() }) - } else { - None - } - } - - /// Converts this slice of bytes into a slice of ASCII characters, - /// without checking whether they're valid. - /// - /// # Safety - /// - /// Every byte in the slice must be in `0..=127`, or else this is UB. - #[unstable(feature = "ascii_char", issue = "110998")] - #[must_use] - #[inline] - pub const unsafe fn as_ascii_unchecked(&self) -> &[ascii::Char] { - let byte_ptr: *const [u8] = self; - let ascii_ptr = byte_ptr as *const [ascii::Char]; - // SAFETY: The caller promised all the bytes are ASCII - unsafe { &*ascii_ptr } - } - - /// Checks that two slices are an ASCII case-insensitive match. - /// - /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`, - /// but without allocating and copying temporaries. - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[must_use] - #[inline] - pub fn eq_ignore_ascii_case(&self, other: &[u8]) -> bool { - self.len() == other.len() && iter::zip(self, other).all(|(a, b)| a.eq_ignore_ascii_case(b)) - } - - /// Converts this slice to its ASCII upper case equivalent in-place. - /// - /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', - /// but non-ASCII letters are unchanged. - /// - /// To return a new uppercased value without modifying the existing one, use - /// [`to_ascii_uppercase`]. - /// - /// [`to_ascii_uppercase`]: #method.to_ascii_uppercase - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[inline] - pub fn make_ascii_uppercase(&mut self) { - for byte in self { - byte.make_ascii_uppercase(); - } - } - - /// Converts this slice to its ASCII lower case equivalent in-place. - /// - /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', - /// but non-ASCII letters are unchanged. - /// - /// To return a new lowercased value without modifying the existing one, use - /// [`to_ascii_lowercase`]. - /// - /// [`to_ascii_lowercase`]: #method.to_ascii_lowercase - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[inline] - pub fn make_ascii_lowercase(&mut self) { - for byte in self { - byte.make_ascii_lowercase(); - } - } - - /// Returns an iterator that produces an escaped version of this slice, - /// treating it as an ASCII string. - /// - /// # Examples - /// - /// ``` - /// - /// let s = b"0\t\r\n'\"\\\x9d"; - /// let escaped = s.escape_ascii().to_string(); - /// assert_eq!(escaped, "0\\t\\r\\n\\'\\\"\\\\\\x9d"); - /// ``` - #[must_use = "this returns the escaped bytes as an iterator, \ - without modifying the original"] - #[stable(feature = "inherent_ascii_escape", since = "1.60.0")] - pub fn escape_ascii(&self) -> EscapeAscii<'_> { - EscapeAscii { inner: self.iter().flat_map(|byte| byte.escape_ascii()) } - } - - /// Returns a byte slice with leading ASCII whitespace bytes removed. - /// - /// 'Whitespace' refers to the definition used by - /// [`u8::is_ascii_whitespace`]. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(b" \t hello world\n".trim_ascii_start(), b"hello world\n"); - /// assert_eq!(b" ".trim_ascii_start(), b""); - /// assert_eq!(b"".trim_ascii_start(), b""); - /// ``` - #[stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] - #[inline] - pub const fn trim_ascii_start(&self) -> &[u8] { - let mut bytes = self; - // Note: A pattern matching based approach (instead of indexing) allows - // making the function const. - while let [first, rest @ ..] = bytes { - if first.is_ascii_whitespace() { - bytes = rest; - } else { - break; - } - } - bytes - } - - /// Returns a byte slice with trailing ASCII whitespace bytes removed. - /// - /// 'Whitespace' refers to the definition used by - /// [`u8::is_ascii_whitespace`]. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(b"\r hello world\n ".trim_ascii_end(), b"\r hello world"); - /// assert_eq!(b" ".trim_ascii_end(), b""); - /// assert_eq!(b"".trim_ascii_end(), b""); - /// ``` - #[stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] - #[inline] - pub const fn trim_ascii_end(&self) -> &[u8] { - let mut bytes = self; - // Note: A pattern matching based approach (instead of indexing) allows - // making the function const. - while let [rest @ .., last] = bytes { - if last.is_ascii_whitespace() { - bytes = rest; - } else { - break; - } - } - bytes - } - - /// Returns a byte slice with leading and trailing ASCII whitespace bytes - /// removed. - /// - /// 'Whitespace' refers to the definition used by - /// [`u8::is_ascii_whitespace`]. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(b"\r hello world\n ".trim_ascii(), b"hello world"); - /// assert_eq!(b" ".trim_ascii(), b""); - /// assert_eq!(b"".trim_ascii(), b""); - /// ``` - #[stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] - #[inline] - pub const fn trim_ascii(&self) -> &[u8] { - self.trim_ascii_start().trim_ascii_end() - } -} - -type EscapeByte = impl (Fn(&u8) -> ascii::EscapeDefault) + Copy; - -/// An iterator over the escaped version of a byte slice. -/// -/// This `struct` is created by the [`slice::escape_ascii`] method. See its -/// documentation for more information. -#[stable(feature = "inherent_ascii_escape", since = "1.60.0")] -#[derive(Clone)] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct EscapeAscii<'a> { - inner: iter::FlatMap, ascii::EscapeDefault, EscapeByte>, -} - -#[stable(feature = "inherent_ascii_escape", since = "1.60.0")] -impl<'a> iter::Iterator for EscapeAscii<'a> { - type Item = u8; - #[inline] - fn next(&mut self) -> Option { - self.inner.next() - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } - #[inline] - fn try_fold(&mut self, init: Acc, fold: Fold) -> R - where - Fold: FnMut(Acc, Self::Item) -> R, - R: ops::Try, - { - self.inner.try_fold(init, fold) - } - #[inline] - fn fold(self, init: Acc, fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - self.inner.fold(init, fold) - } - #[inline] - fn last(mut self) -> Option { - self.next_back() - } -} - -#[stable(feature = "inherent_ascii_escape", since = "1.60.0")] -impl<'a> iter::DoubleEndedIterator for EscapeAscii<'a> { - fn next_back(&mut self) -> Option { - self.inner.next_back() - } -} -#[stable(feature = "inherent_ascii_escape", since = "1.60.0")] -impl<'a> iter::FusedIterator for EscapeAscii<'a> {} -#[stable(feature = "inherent_ascii_escape", since = "1.60.0")] -impl<'a> fmt::Display for EscapeAscii<'a> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - // disassemble iterator, including front/back parts of flatmap in case it has been partially consumed - let (front, slice, back) = self.clone().inner.into_parts(); - let front = front.unwrap_or(EscapeDefault::empty()); - let mut bytes = slice.unwrap_or_default().as_slice(); - let back = back.unwrap_or(EscapeDefault::empty()); - - // usually empty, so the formatter won't have to do any work - for byte in front { - f.write_char(byte as char)?; - } - - fn needs_escape(b: u8) -> bool { - b > 0x7E || b < 0x20 || b == b'\\' || b == b'\'' || b == b'"' - } - - while bytes.len() > 0 { - // fast path for the printable, non-escaped subset of ascii - let prefix = bytes.iter().take_while(|&&b| !needs_escape(b)).count(); - // SAFETY: prefix length was derived by counting bytes in the same splice, so it's in-bounds - let (prefix, remainder) = unsafe { bytes.split_at_unchecked(prefix) }; - // SAFETY: prefix is a valid utf8 sequence, as it's a subset of ASCII - let prefix = unsafe { crate::str::from_utf8_unchecked(prefix) }; - - f.write_str(prefix)?; // the fast part - - bytes = remainder; - - if let Some(&b) = bytes.first() { - // guaranteed to be non-empty, better to write it as a str - f.write_str(ascii::escape_default(b).as_str())?; - bytes = &bytes[1..]; - } - } - - // also usually empty - for byte in back { - f.write_char(byte as char)?; - } - Ok(()) - } -} -#[stable(feature = "inherent_ascii_escape", since = "1.60.0")] -impl<'a> fmt::Debug for EscapeAscii<'a> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("EscapeAscii").finish_non_exhaustive() - } -} - -/// Returns `true` if any byte in the word `v` is nonascii (>= 128). Snarfed -/// from `../str/mod.rs`, which does something similar for utf8 validation. -#[inline] -const fn contains_nonascii(v: usize) -> bool { - const NONASCII_MASK: usize = usize::repeat_u8(0x80); - (NONASCII_MASK & v) != 0 -} - -/// ASCII test *without* the chunk-at-a-time optimizations. -/// -/// This is carefully structured to produce nice small code -- it's smaller in -/// `-O` than what the "obvious" ways produces under `-C opt-level=s`. If you -/// touch it, be sure to run (and update if needed) the assembly test. -#[unstable(feature = "str_internals", issue = "none")] -#[doc(hidden)] -#[inline] -pub const fn is_ascii_simple(mut bytes: &[u8]) -> bool { - while let [rest @ .., last] = bytes { - if !last.is_ascii() { - break; - } - bytes = rest; - } - bytes.is_empty() -} - -/// Optimized ASCII test that will use usize-at-a-time operations instead of -/// byte-at-a-time operations (when possible). -/// -/// The algorithm we use here is pretty simple. If `s` is too short, we just -/// check each byte and be done with it. Otherwise: -/// -/// - Read the first word with an unaligned load. -/// - Align the pointer, read subsequent words until end with aligned loads. -/// - Read the last `usize` from `s` with an unaligned load. -/// -/// If any of these loads produces something for which `contains_nonascii` -/// (above) returns true, then we know the answer is false. -#[inline] -const fn is_ascii(s: &[u8]) -> bool { - const USIZE_SIZE: usize = mem::size_of::(); - - let len = s.len(); - let align_offset = s.as_ptr().align_offset(USIZE_SIZE); - - // If we wouldn't gain anything from the word-at-a-time implementation, fall - // back to a scalar loop. - // - // We also do this for architectures where `size_of::()` isn't - // sufficient alignment for `usize`, because it's a weird edge case. - if len < USIZE_SIZE || len < align_offset || USIZE_SIZE < mem::align_of::() { - return is_ascii_simple(s); - } - - // We always read the first word unaligned, which means `align_offset` is - // 0, we'd read the same value again for the aligned read. - let offset_to_aligned = if align_offset == 0 { USIZE_SIZE } else { align_offset }; - - let start = s.as_ptr(); - // SAFETY: We verify `len < USIZE_SIZE` above. - let first_word = unsafe { (start as *const usize).read_unaligned() }; - - if contains_nonascii(first_word) { - return false; - } - // We checked this above, somewhat implicitly. Note that `offset_to_aligned` - // is either `align_offset` or `USIZE_SIZE`, both of are explicitly checked - // above. - debug_assert!(offset_to_aligned <= len); - - // SAFETY: word_ptr is the (properly aligned) usize ptr we use to read the - // middle chunk of the slice. - let mut word_ptr = unsafe { start.add(offset_to_aligned) as *const usize }; - - // `byte_pos` is the byte index of `word_ptr`, used for loop end checks. - let mut byte_pos = offset_to_aligned; - - // Paranoia check about alignment, since we're about to do a bunch of - // unaligned loads. In practice this should be impossible barring a bug in - // `align_offset` though. - // While this method is allowed to spuriously fail in CTFE, if it doesn't - // have alignment information it should have given a `usize::MAX` for - // `align_offset` earlier, sending things through the scalar path instead of - // this one, so this check should pass if it's reachable. - debug_assert!(word_ptr.is_aligned_to(mem::align_of::())); - - // Read subsequent words until the last aligned word, excluding the last - // aligned word by itself to be done in tail check later, to ensure that - // tail is always one `usize` at most to extra branch `byte_pos == len`. - while byte_pos < len - USIZE_SIZE { - // Sanity check that the read is in bounds - debug_assert!(byte_pos + USIZE_SIZE <= len); - // And that our assumptions about `byte_pos` hold. - debug_assert!(matches!( - word_ptr.cast::().guaranteed_eq(start.wrapping_add(byte_pos)), - // These are from the same allocation, so will hopefully always be - // known to match even in CTFE, but if it refuses to compare them - // that's ok since it's just a debug check anyway. - None | Some(true), - )); - - // SAFETY: We know `word_ptr` is properly aligned (because of - // `align_offset`), and we know that we have enough bytes between `word_ptr` and the end - let word = unsafe { word_ptr.read() }; - if contains_nonascii(word) { - return false; - } - - byte_pos += USIZE_SIZE; - // SAFETY: We know that `byte_pos <= len - USIZE_SIZE`, which means that - // after this `add`, `word_ptr` will be at most one-past-the-end. - word_ptr = unsafe { word_ptr.add(1) }; - } - - // Sanity check to ensure there really is only one `usize` left. This should - // be guaranteed by our loop condition. - debug_assert!(byte_pos <= len && len - byte_pos <= USIZE_SIZE); - - // SAFETY: This relies on `len >= USIZE_SIZE`, which we check at the start. - let last_word = unsafe { (start.add(len - USIZE_SIZE) as *const usize).read_unaligned() }; - - !contains_nonascii(last_word) -} diff --git a/library/core/src/slice/cmp.rs b/library/core/src/slice/cmp.rs deleted file mode 100644 index 5bee4d551352e..0000000000000 --- a/library/core/src/slice/cmp.rs +++ /dev/null @@ -1,238 +0,0 @@ -//! Comparison traits for `[T]`. - -use crate::cmp::{self, BytewiseEq, Ordering}; -use crate::intrinsics::compare_bytes; -use crate::mem; - -use super::from_raw_parts; -use super::memchr; - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq<[U]> for [T] -where - T: PartialEq, -{ - fn eq(&self, other: &[U]) -> bool { - SlicePartialEq::equal(self, other) - } - - fn ne(&self, other: &[U]) -> bool { - SlicePartialEq::not_equal(self, other) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Eq for [T] {} - -/// Implements comparison of slices [lexicographically](Ord#lexicographical-comparison). -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for [T] { - fn cmp(&self, other: &[T]) -> Ordering { - SliceOrd::compare(self, other) - } -} - -/// Implements comparison of slices [lexicographically](Ord#lexicographical-comparison). -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialOrd for [T] { - fn partial_cmp(&self, other: &[T]) -> Option { - SlicePartialOrd::partial_compare(self, other) - } -} - -#[doc(hidden)] -// intermediate trait for specialization of slice's PartialEq -trait SlicePartialEq { - fn equal(&self, other: &[B]) -> bool; - - fn not_equal(&self, other: &[B]) -> bool { - !self.equal(other) - } -} - -// Generic slice equality -impl SlicePartialEq for [A] -where - A: PartialEq, -{ - default fn equal(&self, other: &[B]) -> bool { - if self.len() != other.len() { - return false; - } - - // Implemented as explicit indexing rather - // than zipped iterators for performance reasons. - // See PR https://github.com/rust-lang/rust/pull/116846 - for idx in 0..self.len() { - // bound checks are optimized away - if self[idx] != other[idx] { - return false; - } - } - - true - } -} - -// When each element can be compared byte-wise, we can compare all the bytes -// from the whole size in one call to the intrinsics. -impl SlicePartialEq for [A] -where - A: BytewiseEq, -{ - fn equal(&self, other: &[B]) -> bool { - if self.len() != other.len() { - return false; - } - - // SAFETY: `self` and `other` are references and are thus guaranteed to be valid. - // The two slices have been checked to have the same size above. - unsafe { - let size = mem::size_of_val(self); - compare_bytes(self.as_ptr() as *const u8, other.as_ptr() as *const u8, size) == 0 - } - } -} - -#[doc(hidden)] -// intermediate trait for specialization of slice's PartialOrd -trait SlicePartialOrd: Sized { - fn partial_compare(left: &[Self], right: &[Self]) -> Option; -} - -impl SlicePartialOrd for A { - default fn partial_compare(left: &[A], right: &[A]) -> Option { - let l = cmp::min(left.len(), right.len()); - - // Slice to the loop iteration range to enable bound check - // elimination in the compiler - let lhs = &left[..l]; - let rhs = &right[..l]; - - for i in 0..l { - match lhs[i].partial_cmp(&rhs[i]) { - Some(Ordering::Equal) => (), - non_eq => return non_eq, - } - } - - left.len().partial_cmp(&right.len()) - } -} - -// This is the impl that we would like to have. Unfortunately it's not sound. -// See `partial_ord_slice.rs`. -/* -impl SlicePartialOrd for A -where - A: Ord, -{ - default fn partial_compare(left: &[A], right: &[A]) -> Option { - Some(SliceOrd::compare(left, right)) - } -} -*/ - -impl SlicePartialOrd for A { - fn partial_compare(left: &[A], right: &[A]) -> Option { - Some(SliceOrd::compare(left, right)) - } -} - -#[rustc_specialization_trait] -trait AlwaysApplicableOrd: SliceOrd + Ord {} - -macro_rules! always_applicable_ord { - ($([$($p:tt)*] $t:ty,)*) => { - $(impl<$($p)*> AlwaysApplicableOrd for $t {})* - } -} - -always_applicable_ord! { - [] u8, [] u16, [] u32, [] u64, [] u128, [] usize, - [] i8, [] i16, [] i32, [] i64, [] i128, [] isize, - [] bool, [] char, - [T: ?Sized] *const T, [T: ?Sized] *mut T, - [T: AlwaysApplicableOrd] &T, - [T: AlwaysApplicableOrd] &mut T, - [T: AlwaysApplicableOrd] Option, -} - -#[doc(hidden)] -// intermediate trait for specialization of slice's Ord -trait SliceOrd: Sized { - fn compare(left: &[Self], right: &[Self]) -> Ordering; -} - -impl SliceOrd for A { - default fn compare(left: &[Self], right: &[Self]) -> Ordering { - let l = cmp::min(left.len(), right.len()); - - // Slice to the loop iteration range to enable bound check - // elimination in the compiler - let lhs = &left[..l]; - let rhs = &right[..l]; - - for i in 0..l { - match lhs[i].cmp(&rhs[i]) { - Ordering::Equal => (), - non_eq => return non_eq, - } - } - - left.len().cmp(&right.len()) - } -} - -// `compare_bytes` compares a sequence of unsigned bytes lexicographically. -// this matches the order we want for [u8], but no others (not even [i8]). -impl SliceOrd for u8 { - #[inline] - fn compare(left: &[Self], right: &[Self]) -> Ordering { - // Since the length of a slice is always less than or equal to isize::MAX, this never underflows. - let diff = left.len() as isize - right.len() as isize; - // This comparison gets optimized away (on x86_64 and ARM) because the subtraction updates flags. - let len = if left.len() < right.len() { left.len() } else { right.len() }; - // SAFETY: `left` and `right` are references and are thus guaranteed to be valid. - // We use the minimum of both lengths which guarantees that both regions are - // valid for reads in that interval. - let mut order = unsafe { compare_bytes(left.as_ptr(), right.as_ptr(), len) as isize }; - if order == 0 { - order = diff; - } - order.cmp(&0) - } -} - -pub(super) trait SliceContains: Sized { - fn slice_contains(&self, x: &[Self]) -> bool; -} - -impl SliceContains for T -where - T: PartialEq, -{ - default fn slice_contains(&self, x: &[Self]) -> bool { - x.iter().any(|y| *y == *self) - } -} - -impl SliceContains for u8 { - #[inline] - fn slice_contains(&self, x: &[Self]) -> bool { - memchr::memchr(*self, x).is_some() - } -} - -impl SliceContains for i8 { - #[inline] - fn slice_contains(&self, x: &[Self]) -> bool { - let byte = *self as u8; - // SAFETY: `i8` and `u8` have the same memory layout, thus casting `x.as_ptr()` - // as `*const u8` is safe. The `x.as_ptr()` comes from a reference and is thus guaranteed - // to be valid for reads for the length of the slice `x.len()`, which cannot be larger - // than `isize::MAX`. The returned slice is never mutated. - let bytes: &[u8] = unsafe { from_raw_parts(x.as_ptr() as *const u8, x.len()) }; - memchr::memchr(byte, bytes).is_some() - } -} diff --git a/library/core/src/slice/index.rs b/library/core/src/slice/index.rs deleted file mode 100644 index 8d7b6165510a8..0000000000000 --- a/library/core/src/slice/index.rs +++ /dev/null @@ -1,889 +0,0 @@ -//! Indexing implementations for `[T]`. - -use crate::intrinsics::const_eval_select; -use crate::intrinsics::unchecked_sub; -use crate::ops; -use crate::ptr; -use crate::ub_checks::assert_unsafe_precondition; - -#[stable(feature = "rust1", since = "1.0.0")] -impl ops::Index for [T] -where - I: SliceIndex<[T]>, -{ - type Output = I::Output; - - #[inline(always)] - fn index(&self, index: I) -> &I::Output { - index.index(self) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ops::IndexMut for [T] -where - I: SliceIndex<[T]>, -{ - #[inline(always)] - fn index_mut(&mut self, index: I) -> &mut I::Output { - index.index_mut(self) - } -} - -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)] -#[cfg_attr(feature = "panic_immediate_abort", inline)] -#[track_caller] -#[rustc_const_unstable(feature = "const_slice_index", issue = "none")] -const fn slice_start_index_len_fail(index: usize, len: usize) -> ! { - const_eval_select((index, len), slice_start_index_len_fail_ct, slice_start_index_len_fail_rt) -} - -// FIXME const-hack -#[inline] -#[track_caller] -fn slice_start_index_len_fail_rt(index: usize, len: usize) -> ! { - panic!("range start index {index} out of range for slice of length {len}"); -} - -#[inline] -#[track_caller] -const fn slice_start_index_len_fail_ct(_: usize, _: usize) -> ! { - panic!("slice start index is out of range for slice"); -} - -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)] -#[cfg_attr(feature = "panic_immediate_abort", inline)] -#[track_caller] -#[rustc_const_unstable(feature = "const_slice_index", issue = "none")] -const fn slice_end_index_len_fail(index: usize, len: usize) -> ! { - const_eval_select((index, len), slice_end_index_len_fail_ct, slice_end_index_len_fail_rt) -} - -// FIXME const-hack -#[inline] -#[track_caller] -fn slice_end_index_len_fail_rt(index: usize, len: usize) -> ! { - panic!("range end index {index} out of range for slice of length {len}"); -} - -#[inline] -#[track_caller] -const fn slice_end_index_len_fail_ct(_: usize, _: usize) -> ! { - panic!("slice end index is out of range for slice"); -} - -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)] -#[cfg_attr(feature = "panic_immediate_abort", inline)] -#[track_caller] -#[rustc_const_unstable(feature = "const_slice_index", issue = "none")] -const fn slice_index_order_fail(index: usize, end: usize) -> ! { - const_eval_select((index, end), slice_index_order_fail_ct, slice_index_order_fail_rt) -} - -// FIXME const-hack -#[inline] -#[track_caller] -fn slice_index_order_fail_rt(index: usize, end: usize) -> ! { - panic!("slice index starts at {index} but ends at {end}"); -} - -#[inline] -#[track_caller] -const fn slice_index_order_fail_ct(_: usize, _: usize) -> ! { - panic!("slice index start is larger than end"); -} - -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)] -#[cfg_attr(feature = "panic_immediate_abort", inline)] -#[track_caller] -const fn slice_start_index_overflow_fail() -> ! { - panic!("attempted to index slice from after maximum usize"); -} - -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)] -#[cfg_attr(feature = "panic_immediate_abort", inline)] -#[track_caller] -const fn slice_end_index_overflow_fail() -> ! { - panic!("attempted to index slice up to maximum usize"); -} - -mod private_slice_index { - use super::ops; - #[stable(feature = "slice_get_slice", since = "1.28.0")] - pub trait Sealed {} - - #[stable(feature = "slice_get_slice", since = "1.28.0")] - impl Sealed for usize {} - #[stable(feature = "slice_get_slice", since = "1.28.0")] - impl Sealed for ops::Range {} - #[stable(feature = "slice_get_slice", since = "1.28.0")] - impl Sealed for ops::RangeTo {} - #[stable(feature = "slice_get_slice", since = "1.28.0")] - impl Sealed for ops::RangeFrom {} - #[stable(feature = "slice_get_slice", since = "1.28.0")] - impl Sealed for ops::RangeFull {} - #[stable(feature = "slice_get_slice", since = "1.28.0")] - impl Sealed for ops::RangeInclusive {} - #[stable(feature = "slice_get_slice", since = "1.28.0")] - impl Sealed for ops::RangeToInclusive {} - #[stable(feature = "slice_index_with_ops_bound_pair", since = "1.53.0")] - impl Sealed for (ops::Bound, ops::Bound) {} - - impl Sealed for ops::IndexRange {} -} - -/// A helper trait used for indexing operations. -/// -/// Implementations of this trait have to promise that if the argument -/// to `get_unchecked(_mut)` is a safe reference, then so is the result. -#[stable(feature = "slice_get_slice", since = "1.28.0")] -#[rustc_diagnostic_item = "SliceIndex"] -#[rustc_on_unimplemented( - on(T = "str", label = "string indices are ranges of `usize`",), - on( - all(any(T = "str", T = "&str", T = "alloc::string::String"), _Self = "{integer}"), - note = "you can use `.chars().nth()` or `.bytes().nth()`\n\ - for more information, see chapter 8 in The Book: \ - " - ), - message = "the type `{T}` cannot be indexed by `{Self}`", - label = "slice indices are of type `usize` or ranges of `usize`" -)] -pub unsafe trait SliceIndex: private_slice_index::Sealed { - /// The output type returned by methods. - #[stable(feature = "slice_get_slice", since = "1.28.0")] - type Output: ?Sized; - - /// Returns a shared reference to the output at this location, if in - /// bounds. - #[unstable(feature = "slice_index_methods", issue = "none")] - fn get(self, slice: &T) -> Option<&Self::Output>; - - /// Returns a mutable reference to the output at this location, if in - /// bounds. - #[unstable(feature = "slice_index_methods", issue = "none")] - fn get_mut(self, slice: &mut T) -> Option<&mut Self::Output>; - - /// Returns a pointer to the output at this location, without - /// performing any bounds checking. - /// Calling this method with an out-of-bounds index or a dangling `slice` pointer - /// is *[undefined behavior]* even if the resulting pointer is not used. - /// - /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html - #[unstable(feature = "slice_index_methods", issue = "none")] - unsafe fn get_unchecked(self, slice: *const T) -> *const Self::Output; - - /// Returns a mutable pointer to the output at this location, without - /// performing any bounds checking. - /// Calling this method with an out-of-bounds index or a dangling `slice` pointer - /// is *[undefined behavior]* even if the resulting pointer is not used. - /// - /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html - #[unstable(feature = "slice_index_methods", issue = "none")] - unsafe fn get_unchecked_mut(self, slice: *mut T) -> *mut Self::Output; - - /// Returns a shared reference to the output at this location, panicking - /// if out of bounds. - #[unstable(feature = "slice_index_methods", issue = "none")] - #[track_caller] - fn index(self, slice: &T) -> &Self::Output; - - /// Returns a mutable reference to the output at this location, panicking - /// if out of bounds. - #[unstable(feature = "slice_index_methods", issue = "none")] - #[track_caller] - fn index_mut(self, slice: &mut T) -> &mut Self::Output; -} - -/// The methods `index` and `index_mut` panic if the index is out of bounds. -#[stable(feature = "slice_get_slice_impls", since = "1.15.0")] -#[rustc_const_unstable(feature = "const_slice_index", issue = "none")] -unsafe impl SliceIndex<[T]> for usize { - type Output = T; - - #[inline] - fn get(self, slice: &[T]) -> Option<&T> { - // SAFETY: `self` is checked to be in bounds. - if self < slice.len() { unsafe { Some(&*self.get_unchecked(slice)) } } else { None } - } - - #[inline] - fn get_mut(self, slice: &mut [T]) -> Option<&mut T> { - // SAFETY: `self` is checked to be in bounds. - if self < slice.len() { unsafe { Some(&mut *self.get_unchecked_mut(slice)) } } else { None } - } - - #[inline] - unsafe fn get_unchecked(self, slice: *const [T]) -> *const T { - assert_unsafe_precondition!( - check_language_ub, - "slice::get_unchecked requires that the index is within the slice", - (this: usize = self, len: usize = slice.len()) => this < len - ); - // SAFETY: the caller guarantees that `slice` is not dangling, so it - // cannot be longer than `isize::MAX`. They also guarantee that - // `self` is in bounds of `slice` so `self` cannot overflow an `isize`, - // so the call to `add` is safe. - unsafe { - // Use intrinsics::assume instead of hint::assert_unchecked so that we don't check the - // precondition of this function twice. - crate::intrinsics::assume(self < slice.len()); - slice.as_ptr().add(self) - } - } - - #[inline] - unsafe fn get_unchecked_mut(self, slice: *mut [T]) -> *mut T { - assert_unsafe_precondition!( - check_library_ub, - "slice::get_unchecked_mut requires that the index is within the slice", - (this: usize = self, len: usize = slice.len()) => this < len - ); - // SAFETY: see comments for `get_unchecked` above. - unsafe { slice.as_mut_ptr().add(self) } - } - - #[inline] - fn index(self, slice: &[T]) -> &T { - // N.B., use intrinsic indexing - &(*slice)[self] - } - - #[inline] - fn index_mut(self, slice: &mut [T]) -> &mut T { - // N.B., use intrinsic indexing - &mut (*slice)[self] - } -} - -/// Because `IndexRange` guarantees `start <= end`, fewer checks are needed here -/// than there are for a general `Range` (which might be `100..3`). -#[rustc_const_unstable(feature = "const_index_range_slice_index", issue = "none")] -unsafe impl SliceIndex<[T]> for ops::IndexRange { - type Output = [T]; - - #[inline] - fn get(self, slice: &[T]) -> Option<&[T]> { - if self.end() <= slice.len() { - // SAFETY: `self` is checked to be valid and in bounds above. - unsafe { Some(&*self.get_unchecked(slice)) } - } else { - None - } - } - - #[inline] - fn get_mut(self, slice: &mut [T]) -> Option<&mut [T]> { - if self.end() <= slice.len() { - // SAFETY: `self` is checked to be valid and in bounds above. - unsafe { Some(&mut *self.get_unchecked_mut(slice)) } - } else { - None - } - } - - #[inline] - unsafe fn get_unchecked(self, slice: *const [T]) -> *const [T] { - assert_unsafe_precondition!( - check_library_ub, - "slice::get_unchecked requires that the index is within the slice", - (end: usize = self.end(), len: usize = slice.len()) => end <= len - ); - // SAFETY: the caller guarantees that `slice` is not dangling, so it - // cannot be longer than `isize::MAX`. They also guarantee that - // `self` is in bounds of `slice` so `self` cannot overflow an `isize`, - // so the call to `add` is safe. - unsafe { ptr::slice_from_raw_parts(slice.as_ptr().add(self.start()), self.len()) } - } - - #[inline] - unsafe fn get_unchecked_mut(self, slice: *mut [T]) -> *mut [T] { - assert_unsafe_precondition!( - check_library_ub, - "slice::get_unchecked_mut requires that the index is within the slice", - (end: usize = self.end(), len: usize = slice.len()) => end <= len - ); - - // SAFETY: see comments for `get_unchecked` above. - unsafe { ptr::slice_from_raw_parts_mut(slice.as_mut_ptr().add(self.start()), self.len()) } - } - - #[inline] - fn index(self, slice: &[T]) -> &[T] { - if self.end() <= slice.len() { - // SAFETY: `self` is checked to be valid and in bounds above. - unsafe { &*self.get_unchecked(slice) } - } else { - slice_end_index_len_fail(self.end(), slice.len()) - } - } - - #[inline] - fn index_mut(self, slice: &mut [T]) -> &mut [T] { - if self.end() <= slice.len() { - // SAFETY: `self` is checked to be valid and in bounds above. - unsafe { &mut *self.get_unchecked_mut(slice) } - } else { - slice_end_index_len_fail(self.end(), slice.len()) - } - } -} - -/// The methods `index` and `index_mut` panic if: -/// - the start of the range is greater than the end of the range or -/// - the end of the range is out of bounds. -#[stable(feature = "slice_get_slice_impls", since = "1.15.0")] -#[rustc_const_unstable(feature = "const_slice_index", issue = "none")] -unsafe impl SliceIndex<[T]> for ops::Range { - type Output = [T]; - - #[inline] - fn get(self, slice: &[T]) -> Option<&[T]> { - if self.start > self.end || self.end > slice.len() { - None - } else { - // SAFETY: `self` is checked to be valid and in bounds above. - unsafe { Some(&*self.get_unchecked(slice)) } - } - } - - #[inline] - fn get_mut(self, slice: &mut [T]) -> Option<&mut [T]> { - if self.start > self.end || self.end > slice.len() { - None - } else { - // SAFETY: `self` is checked to be valid and in bounds above. - unsafe { Some(&mut *self.get_unchecked_mut(slice)) } - } - } - - #[inline] - unsafe fn get_unchecked(self, slice: *const [T]) -> *const [T] { - assert_unsafe_precondition!( - check_library_ub, - "slice::get_unchecked requires that the range is within the slice", - ( - start: usize = self.start, - end: usize = self.end, - len: usize = slice.len() - ) => end >= start && end <= len - ); - - // SAFETY: the caller guarantees that `slice` is not dangling, so it - // cannot be longer than `isize::MAX`. They also guarantee that - // `self` is in bounds of `slice` so `self` cannot overflow an `isize`, - // so the call to `add` is safe and the length calculation cannot overflow. - unsafe { - let new_len = unchecked_sub(self.end, self.start); - ptr::slice_from_raw_parts(slice.as_ptr().add(self.start), new_len) - } - } - - #[inline] - unsafe fn get_unchecked_mut(self, slice: *mut [T]) -> *mut [T] { - assert_unsafe_precondition!( - check_library_ub, - "slice::get_unchecked_mut requires that the range is within the slice", - ( - start: usize = self.start, - end: usize = self.end, - len: usize = slice.len() - ) => end >= start && end <= len - ); - // SAFETY: see comments for `get_unchecked` above. - unsafe { - let new_len = unchecked_sub(self.end, self.start); - ptr::slice_from_raw_parts_mut(slice.as_mut_ptr().add(self.start), new_len) - } - } - - #[inline(always)] - fn index(self, slice: &[T]) -> &[T] { - if self.start > self.end { - slice_index_order_fail(self.start, self.end); - } else if self.end > slice.len() { - slice_end_index_len_fail(self.end, slice.len()); - } - // SAFETY: `self` is checked to be valid and in bounds above. - unsafe { &*self.get_unchecked(slice) } - } - - #[inline] - fn index_mut(self, slice: &mut [T]) -> &mut [T] { - if self.start > self.end { - slice_index_order_fail(self.start, self.end); - } else if self.end > slice.len() { - slice_end_index_len_fail(self.end, slice.len()); - } - // SAFETY: `self` is checked to be valid and in bounds above. - unsafe { &mut *self.get_unchecked_mut(slice) } - } -} - -/// The methods `index` and `index_mut` panic if the end of the range is out of bounds. -#[stable(feature = "slice_get_slice_impls", since = "1.15.0")] -#[rustc_const_unstable(feature = "const_slice_index", issue = "none")] -unsafe impl SliceIndex<[T]> for ops::RangeTo { - type Output = [T]; - - #[inline] - fn get(self, slice: &[T]) -> Option<&[T]> { - (0..self.end).get(slice) - } - - #[inline] - fn get_mut(self, slice: &mut [T]) -> Option<&mut [T]> { - (0..self.end).get_mut(slice) - } - - #[inline] - unsafe fn get_unchecked(self, slice: *const [T]) -> *const [T] { - // SAFETY: the caller has to uphold the safety contract for `get_unchecked`. - unsafe { (0..self.end).get_unchecked(slice) } - } - - #[inline] - unsafe fn get_unchecked_mut(self, slice: *mut [T]) -> *mut [T] { - // SAFETY: the caller has to uphold the safety contract for `get_unchecked_mut`. - unsafe { (0..self.end).get_unchecked_mut(slice) } - } - - #[inline(always)] - fn index(self, slice: &[T]) -> &[T] { - (0..self.end).index(slice) - } - - #[inline] - fn index_mut(self, slice: &mut [T]) -> &mut [T] { - (0..self.end).index_mut(slice) - } -} - -/// The methods `index` and `index_mut` panic if the start of the range is out of bounds. -#[stable(feature = "slice_get_slice_impls", since = "1.15.0")] -#[rustc_const_unstable(feature = "const_slice_index", issue = "none")] -unsafe impl SliceIndex<[T]> for ops::RangeFrom { - type Output = [T]; - - #[inline] - fn get(self, slice: &[T]) -> Option<&[T]> { - (self.start..slice.len()).get(slice) - } - - #[inline] - fn get_mut(self, slice: &mut [T]) -> Option<&mut [T]> { - (self.start..slice.len()).get_mut(slice) - } - - #[inline] - unsafe fn get_unchecked(self, slice: *const [T]) -> *const [T] { - // SAFETY: the caller has to uphold the safety contract for `get_unchecked`. - unsafe { (self.start..slice.len()).get_unchecked(slice) } - } - - #[inline] - unsafe fn get_unchecked_mut(self, slice: *mut [T]) -> *mut [T] { - // SAFETY: the caller has to uphold the safety contract for `get_unchecked_mut`. - unsafe { (self.start..slice.len()).get_unchecked_mut(slice) } - } - - #[inline] - fn index(self, slice: &[T]) -> &[T] { - if self.start > slice.len() { - slice_start_index_len_fail(self.start, slice.len()); - } - // SAFETY: `self` is checked to be valid and in bounds above. - unsafe { &*self.get_unchecked(slice) } - } - - #[inline] - fn index_mut(self, slice: &mut [T]) -> &mut [T] { - if self.start > slice.len() { - slice_start_index_len_fail(self.start, slice.len()); - } - // SAFETY: `self` is checked to be valid and in bounds above. - unsafe { &mut *self.get_unchecked_mut(slice) } - } -} - -#[stable(feature = "slice_get_slice_impls", since = "1.15.0")] -#[rustc_const_unstable(feature = "const_slice_index", issue = "none")] -unsafe impl SliceIndex<[T]> for ops::RangeFull { - type Output = [T]; - - #[inline] - fn get(self, slice: &[T]) -> Option<&[T]> { - Some(slice) - } - - #[inline] - fn get_mut(self, slice: &mut [T]) -> Option<&mut [T]> { - Some(slice) - } - - #[inline] - unsafe fn get_unchecked(self, slice: *const [T]) -> *const [T] { - slice - } - - #[inline] - unsafe fn get_unchecked_mut(self, slice: *mut [T]) -> *mut [T] { - slice - } - - #[inline] - fn index(self, slice: &[T]) -> &[T] { - slice - } - - #[inline] - fn index_mut(self, slice: &mut [T]) -> &mut [T] { - slice - } -} - -/// The methods `index` and `index_mut` panic if: -/// - the end of the range is `usize::MAX` or -/// - the start of the range is greater than the end of the range or -/// - the end of the range is out of bounds. -#[stable(feature = "inclusive_range", since = "1.26.0")] -#[rustc_const_unstable(feature = "const_slice_index", issue = "none")] -unsafe impl SliceIndex<[T]> for ops::RangeInclusive { - type Output = [T]; - - #[inline] - fn get(self, slice: &[T]) -> Option<&[T]> { - if *self.end() == usize::MAX { None } else { self.into_slice_range().get(slice) } - } - - #[inline] - fn get_mut(self, slice: &mut [T]) -> Option<&mut [T]> { - if *self.end() == usize::MAX { None } else { self.into_slice_range().get_mut(slice) } - } - - #[inline] - unsafe fn get_unchecked(self, slice: *const [T]) -> *const [T] { - // SAFETY: the caller has to uphold the safety contract for `get_unchecked`. - unsafe { self.into_slice_range().get_unchecked(slice) } - } - - #[inline] - unsafe fn get_unchecked_mut(self, slice: *mut [T]) -> *mut [T] { - // SAFETY: the caller has to uphold the safety contract for `get_unchecked_mut`. - unsafe { self.into_slice_range().get_unchecked_mut(slice) } - } - - #[inline] - fn index(self, slice: &[T]) -> &[T] { - if *self.end() == usize::MAX { - slice_end_index_overflow_fail(); - } - self.into_slice_range().index(slice) - } - - #[inline] - fn index_mut(self, slice: &mut [T]) -> &mut [T] { - if *self.end() == usize::MAX { - slice_end_index_overflow_fail(); - } - self.into_slice_range().index_mut(slice) - } -} - -/// The methods `index` and `index_mut` panic if the end of the range is out of bounds. -#[stable(feature = "inclusive_range", since = "1.26.0")] -#[rustc_const_unstable(feature = "const_slice_index", issue = "none")] -unsafe impl SliceIndex<[T]> for ops::RangeToInclusive { - type Output = [T]; - - #[inline] - fn get(self, slice: &[T]) -> Option<&[T]> { - (0..=self.end).get(slice) - } - - #[inline] - fn get_mut(self, slice: &mut [T]) -> Option<&mut [T]> { - (0..=self.end).get_mut(slice) - } - - #[inline] - unsafe fn get_unchecked(self, slice: *const [T]) -> *const [T] { - // SAFETY: the caller has to uphold the safety contract for `get_unchecked`. - unsafe { (0..=self.end).get_unchecked(slice) } - } - - #[inline] - unsafe fn get_unchecked_mut(self, slice: *mut [T]) -> *mut [T] { - // SAFETY: the caller has to uphold the safety contract for `get_unchecked_mut`. - unsafe { (0..=self.end).get_unchecked_mut(slice) } - } - - #[inline] - fn index(self, slice: &[T]) -> &[T] { - (0..=self.end).index(slice) - } - - #[inline] - fn index_mut(self, slice: &mut [T]) -> &mut [T] { - (0..=self.end).index_mut(slice) - } -} - -/// Performs bounds-checking of a range. -/// -/// This method is similar to [`Index::index`] for slices, but it returns a -/// [`Range`] equivalent to `range`. You can use this method to turn any range -/// into `start` and `end` values. -/// -/// `bounds` is the range of the slice to use for bounds-checking. It should -/// be a [`RangeTo`] range that ends at the length of the slice. -/// -/// The returned [`Range`] is safe to pass to [`slice::get_unchecked`] and -/// [`slice::get_unchecked_mut`] for slices with the given range. -/// -/// [`Range`]: ops::Range -/// [`RangeTo`]: ops::RangeTo -/// [`slice::get_unchecked`]: slice::get_unchecked -/// [`slice::get_unchecked_mut`]: slice::get_unchecked_mut -/// -/// # Panics -/// -/// Panics if `range` would be out of bounds. -/// -/// # Examples -/// -/// ``` -/// #![feature(slice_range)] -/// -/// use std::slice; -/// -/// let v = [10, 40, 30]; -/// assert_eq!(1..2, slice::range(1..2, ..v.len())); -/// assert_eq!(0..2, slice::range(..2, ..v.len())); -/// assert_eq!(1..3, slice::range(1.., ..v.len())); -/// ``` -/// -/// Panics when [`Index::index`] would panic: -/// -/// ```should_panic -/// #![feature(slice_range)] -/// -/// use std::slice; -/// -/// let _ = slice::range(2..1, ..3); -/// ``` -/// -/// ```should_panic -/// #![feature(slice_range)] -/// -/// use std::slice; -/// -/// let _ = slice::range(1..4, ..3); -/// ``` -/// -/// ```should_panic -/// #![feature(slice_range)] -/// -/// use std::slice; -/// -/// let _ = slice::range(1..=usize::MAX, ..3); -/// ``` -/// -/// [`Index::index`]: ops::Index::index -#[track_caller] -#[unstable(feature = "slice_range", issue = "76393")] -#[must_use] -pub fn range(range: R, bounds: ops::RangeTo) -> ops::Range -where - R: ops::RangeBounds, -{ - let len = bounds.end; - - let start = match range.start_bound() { - ops::Bound::Included(&start) => start, - ops::Bound::Excluded(start) => { - start.checked_add(1).unwrap_or_else(|| slice_start_index_overflow_fail()) - } - ops::Bound::Unbounded => 0, - }; - - let end = match range.end_bound() { - ops::Bound::Included(end) => { - end.checked_add(1).unwrap_or_else(|| slice_end_index_overflow_fail()) - } - ops::Bound::Excluded(&end) => end, - ops::Bound::Unbounded => len, - }; - - if start > end { - slice_index_order_fail(start, end); - } - if end > len { - slice_end_index_len_fail(end, len); - } - - ops::Range { start, end } -} - -/// Performs bounds-checking of a range without panicking. -/// -/// This is a version of [`range`] that returns [`None`] instead of panicking. -/// -/// # Examples -/// -/// ``` -/// #![feature(slice_range)] -/// -/// use std::slice; -/// -/// let v = [10, 40, 30]; -/// assert_eq!(Some(1..2), slice::try_range(1..2, ..v.len())); -/// assert_eq!(Some(0..2), slice::try_range(..2, ..v.len())); -/// assert_eq!(Some(1..3), slice::try_range(1.., ..v.len())); -/// ``` -/// -/// Returns [`None`] when [`Index::index`] would panic: -/// -/// ``` -/// #![feature(slice_range)] -/// -/// use std::slice; -/// -/// assert_eq!(None, slice::try_range(2..1, ..3)); -/// assert_eq!(None, slice::try_range(1..4, ..3)); -/// assert_eq!(None, slice::try_range(1..=usize::MAX, ..3)); -/// ``` -/// -/// [`Index::index`]: ops::Index::index -#[unstable(feature = "slice_range", issue = "76393")] -#[must_use] -pub fn try_range(range: R, bounds: ops::RangeTo) -> Option> -where - R: ops::RangeBounds, -{ - let len = bounds.end; - - let start = match range.start_bound() { - ops::Bound::Included(&start) => start, - ops::Bound::Excluded(start) => start.checked_add(1)?, - ops::Bound::Unbounded => 0, - }; - - let end = match range.end_bound() { - ops::Bound::Included(end) => end.checked_add(1)?, - ops::Bound::Excluded(&end) => end, - ops::Bound::Unbounded => len, - }; - - if start > end || end > len { None } else { Some(ops::Range { start, end }) } -} - -/// Convert pair of `ops::Bound`s into `ops::Range` without performing any bounds checking and (in debug) overflow checking -pub(crate) fn into_range_unchecked( - len: usize, - (start, end): (ops::Bound, ops::Bound), -) -> ops::Range { - use ops::Bound; - let start = match start { - Bound::Included(i) => i, - Bound::Excluded(i) => i + 1, - Bound::Unbounded => 0, - }; - let end = match end { - Bound::Included(i) => i + 1, - Bound::Excluded(i) => i, - Bound::Unbounded => len, - }; - start..end -} - -/// Convert pair of `ops::Bound`s into `ops::Range`. -/// Returns `None` on overflowing indices. -pub(crate) fn into_range( - len: usize, - (start, end): (ops::Bound, ops::Bound), -) -> Option> { - use ops::Bound; - let start = match start { - Bound::Included(start) => start, - Bound::Excluded(start) => start.checked_add(1)?, - Bound::Unbounded => 0, - }; - - let end = match end { - Bound::Included(end) => end.checked_add(1)?, - Bound::Excluded(end) => end, - Bound::Unbounded => len, - }; - - // Don't bother with checking `start < end` and `end <= len` - // since these checks are handled by `Range` impls - - Some(start..end) -} - -/// Convert pair of `ops::Bound`s into `ops::Range`. -/// Panics on overflowing indices. -pub(crate) fn into_slice_range( - len: usize, - (start, end): (ops::Bound, ops::Bound), -) -> ops::Range { - use ops::Bound; - let start = match start { - Bound::Included(start) => start, - Bound::Excluded(start) => { - start.checked_add(1).unwrap_or_else(|| slice_start_index_overflow_fail()) - } - Bound::Unbounded => 0, - }; - - let end = match end { - Bound::Included(end) => { - end.checked_add(1).unwrap_or_else(|| slice_end_index_overflow_fail()) - } - Bound::Excluded(end) => end, - Bound::Unbounded => len, - }; - - // Don't bother with checking `start < end` and `end <= len` - // since these checks are handled by `Range` impls - - start..end -} - -#[stable(feature = "slice_index_with_ops_bound_pair", since = "1.53.0")] -unsafe impl SliceIndex<[T]> for (ops::Bound, ops::Bound) { - type Output = [T]; - - #[inline] - fn get(self, slice: &[T]) -> Option<&Self::Output> { - into_range(slice.len(), self)?.get(slice) - } - - #[inline] - fn get_mut(self, slice: &mut [T]) -> Option<&mut Self::Output> { - into_range(slice.len(), self)?.get_mut(slice) - } - - #[inline] - unsafe fn get_unchecked(self, slice: *const [T]) -> *const Self::Output { - // SAFETY: the caller has to uphold the safety contract for `get_unchecked`. - unsafe { into_range_unchecked(slice.len(), self).get_unchecked(slice) } - } - - #[inline] - unsafe fn get_unchecked_mut(self, slice: *mut [T]) -> *mut Self::Output { - // SAFETY: the caller has to uphold the safety contract for `get_unchecked_mut`. - unsafe { into_range_unchecked(slice.len(), self).get_unchecked_mut(slice) } - } - - #[inline] - fn index(self, slice: &[T]) -> &Self::Output { - into_slice_range(slice.len(), self).index(slice) - } - - #[inline] - fn index_mut(self, slice: &mut [T]) -> &mut Self::Output { - into_slice_range(slice.len(), self).index_mut(slice) - } -} diff --git a/library/core/src/slice/iter.rs b/library/core/src/slice/iter.rs deleted file mode 100644 index 96fc87ab2e9ec..0000000000000 --- a/library/core/src/slice/iter.rs +++ /dev/null @@ -1,3428 +0,0 @@ -//! Definitions of a bunch of iterators for `[T]`. - -#[macro_use] // import iterator! and forward_iterator! -mod macros; - -use crate::cmp; -use crate::fmt; -use crate::hint::assert_unchecked; -use crate::iter::{ - FusedIterator, TrustedLen, TrustedRandomAccess, TrustedRandomAccessNoCoerce, UncheckedIterator, -}; -use crate::marker::PhantomData; -use crate::mem::{self, SizedTypeProperties}; -use crate::num::NonZero; -use crate::ptr::{self, without_provenance, without_provenance_mut, NonNull}; - -use super::{from_raw_parts, from_raw_parts_mut}; - -#[stable(feature = "boxed_slice_into_iter", since = "CURRENT_RUSTC_VERSION")] -impl !Iterator for [T] {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> IntoIterator for &'a [T] { - type Item = &'a T; - type IntoIter = Iter<'a, T>; - - fn into_iter(self) -> Iter<'a, T> { - self.iter() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> IntoIterator for &'a mut [T] { - type Item = &'a mut T; - type IntoIter = IterMut<'a, T>; - - fn into_iter(self) -> IterMut<'a, T> { - self.iter_mut() - } -} - -/// Immutable slice iterator -/// -/// This struct is created by the [`iter`] method on [slices]. -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// // First, we declare a type which has `iter` method to get the `Iter` struct (`&[usize]` here): -/// let slice = &[1, 2, 3]; -/// -/// // Then, we iterate over it: -/// for element in slice.iter() { -/// println!("{element}"); -/// } -/// ``` -/// -/// [`iter`]: slice::iter -/// [slices]: slice -#[stable(feature = "rust1", since = "1.0.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[rustc_diagnostic_item = "SliceIter"] -pub struct Iter<'a, T: 'a> { - /// The pointer to the next element to return, or the past-the-end location - /// if the iterator is empty. - /// - /// This address will be used for all ZST elements, never changed. - ptr: NonNull, - /// For non-ZSTs, the non-null pointer to the past-the-end element. - /// - /// For ZSTs, this is `ptr::dangling(len)`. - end_or_len: *const T, - _marker: PhantomData<&'a T>, -} - -#[stable(feature = "core_impl_debug", since = "1.9.0")] -impl fmt::Debug for Iter<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("Iter").field(&self.as_slice()).finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Sync for Iter<'_, T> {} -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Send for Iter<'_, T> {} - -impl<'a, T> Iter<'a, T> { - #[inline] - pub(super) fn new(slice: &'a [T]) -> Self { - let len = slice.len(); - let ptr: NonNull = NonNull::from(slice).cast(); - // SAFETY: Similar to `IterMut::new`. - unsafe { - let end_or_len = - if T::IS_ZST { without_provenance(len) } else { ptr.as_ptr().add(len) }; - - Self { ptr, end_or_len, _marker: PhantomData } - } - } - - /// Views the underlying data as a subslice of the original data. - /// - /// This has the same lifetime as the original slice, and so the - /// iterator can continue to be used while this exists. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// // First, we declare a type which has the `iter` method to get the `Iter` - /// // struct (`&[usize]` here): - /// let slice = &[1, 2, 3]; - /// - /// // Then, we get the iterator: - /// let mut iter = slice.iter(); - /// // So if we print what `as_slice` method returns here, we have "[1, 2, 3]": - /// println!("{:?}", iter.as_slice()); - /// - /// // Next, we move to the second element of the slice: - /// iter.next(); - /// // Now `as_slice` returns "[2, 3]": - /// println!("{:?}", iter.as_slice()); - /// ``` - #[must_use] - #[stable(feature = "iter_to_slice", since = "1.4.0")] - #[inline] - pub fn as_slice(&self) -> &'a [T] { - self.make_slice() - } -} - -iterator! {struct Iter -> *const T, &'a T, const, {/* no mut */}, as_ref, { - fn is_sorted_by(self, mut compare: F) -> bool - where - Self: Sized, - F: FnMut(&Self::Item, &Self::Item) -> bool, - { - self.as_slice().is_sorted_by(|a, b| compare(&a, &b)) - } -}} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Iter<'_, T> { - #[inline] - fn clone(&self) -> Self { - Iter { ptr: self.ptr, end_or_len: self.end_or_len, _marker: self._marker } - } -} - -#[stable(feature = "slice_iter_as_ref", since = "1.13.0")] -impl AsRef<[T]> for Iter<'_, T> { - #[inline] - fn as_ref(&self) -> &[T] { - self.as_slice() - } -} - -/// Mutable slice iterator. -/// -/// This struct is created by the [`iter_mut`] method on [slices]. -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// // First, we declare a type which has `iter_mut` method to get the `IterMut` -/// // struct (`&[usize]` here): -/// let mut slice = &mut [1, 2, 3]; -/// -/// // Then, we iterate over it and increment each element value: -/// for element in slice.iter_mut() { -/// *element += 1; -/// } -/// -/// // We now have "[2, 3, 4]": -/// println!("{slice:?}"); -/// ``` -/// -/// [`iter_mut`]: slice::iter_mut -/// [slices]: slice -#[stable(feature = "rust1", since = "1.0.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct IterMut<'a, T: 'a> { - /// The pointer to the next element to return, or the past-the-end location - /// if the iterator is empty. - /// - /// This address will be used for all ZST elements, never changed. - ptr: NonNull, - /// For non-ZSTs, the non-null pointer to the past-the-end element. - /// - /// For ZSTs, this is `ptr::without_provenance_mut(len)`. - end_or_len: *mut T, - _marker: PhantomData<&'a mut T>, -} - -#[stable(feature = "core_impl_debug", since = "1.9.0")] -impl fmt::Debug for IterMut<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("IterMut").field(&self.make_slice()).finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Sync for IterMut<'_, T> {} -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Send for IterMut<'_, T> {} - -impl<'a, T> IterMut<'a, T> { - #[inline] - pub(super) fn new(slice: &'a mut [T]) -> Self { - let len = slice.len(); - let ptr: NonNull = NonNull::from(slice).cast(); - // SAFETY: There are several things here: - // - // `ptr` has been obtained by `slice.as_ptr()` where `slice` is a valid - // reference thus it is non-NUL and safe to use and pass to - // `NonNull::new_unchecked` . - // - // Adding `slice.len()` to the starting pointer gives a pointer - // at the end of `slice`. `end` will never be dereferenced, only checked - // for direct pointer equality with `ptr` to check if the iterator is - // done. - // - // In the case of a ZST, the end pointer is just the length. It's never - // used as a pointer at all, and thus it's fine to have no provenance. - // - // See the `next_unchecked!` and `is_empty!` macros as well as the - // `post_inc_start` method for more information. - unsafe { - let end_or_len = - if T::IS_ZST { without_provenance_mut(len) } else { ptr.as_ptr().add(len) }; - - Self { ptr, end_or_len, _marker: PhantomData } - } - } - - /// Views the underlying data as a subslice of the original data. - /// - /// To avoid creating `&mut` references that alias, this is forced - /// to consume the iterator. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// // First, we declare a type which has `iter_mut` method to get the `IterMut` - /// // struct (`&[usize]` here): - /// let mut slice = &mut [1, 2, 3]; - /// - /// { - /// // Then, we get the iterator: - /// let mut iter = slice.iter_mut(); - /// // We move to next element: - /// iter.next(); - /// // So if we print what `into_slice` method returns here, we have "[2, 3]": - /// println!("{:?}", iter.into_slice()); - /// } - /// - /// // Now let's modify a value of the slice: - /// { - /// // First we get back the iterator: - /// let mut iter = slice.iter_mut(); - /// // We change the value of the first element of the slice returned by the `next` method: - /// *iter.next().unwrap() += 1; - /// } - /// // Now slice is "[2, 2, 3]": - /// println!("{slice:?}"); - /// ``` - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "iter_to_slice", since = "1.4.0")] - pub fn into_slice(self) -> &'a mut [T] { - // SAFETY: the iterator was created from a mutable slice with pointer - // `self.ptr` and length `len!(self)`. This guarantees that all the prerequisites - // for `from_raw_parts_mut` are fulfilled. - unsafe { from_raw_parts_mut(self.ptr.as_ptr(), len!(self)) } - } - - /// Views the underlying data as a subslice of the original data. - /// - /// To avoid creating `&mut [T]` references that alias, the returned slice - /// borrows its lifetime from the iterator the method is applied on. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let mut slice: &mut [usize] = &mut [1, 2, 3]; - /// - /// // First, we get the iterator: - /// let mut iter = slice.iter_mut(); - /// // So if we check what the `as_slice` method returns here, we have "[1, 2, 3]": - /// assert_eq!(iter.as_slice(), &[1, 2, 3]); - /// - /// // Next, we move to the second element of the slice: - /// iter.next(); - /// // Now `as_slice` returns "[2, 3]": - /// assert_eq!(iter.as_slice(), &[2, 3]); - /// ``` - #[must_use] - #[stable(feature = "slice_iter_mut_as_slice", since = "1.53.0")] - #[inline] - pub fn as_slice(&self) -> &[T] { - self.make_slice() - } - - /// Views the underlying data as a mutable subslice of the original data. - /// - /// To avoid creating `&mut [T]` references that alias, the returned slice - /// borrows its lifetime from the iterator the method is applied on. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(slice_iter_mut_as_mut_slice)] - /// - /// let mut slice: &mut [usize] = &mut [1, 2, 3]; - /// - /// // First, we get the iterator: - /// let mut iter = slice.iter_mut(); - /// // Then, we get a mutable slice from it: - /// let mut_slice = iter.as_mut_slice(); - /// // So if we check what the `as_mut_slice` method returned, we have "[1, 2, 3]": - /// assert_eq!(mut_slice, &mut [1, 2, 3]); - /// - /// // We can use it to mutate the slice: - /// mut_slice[0] = 4; - /// mut_slice[2] = 5; - /// - /// // Next, we can move to the second element of the slice, checking that - /// // it yields the value we just wrote: - /// assert_eq!(iter.next(), Some(&mut 4)); - /// // Now `as_mut_slice` returns "[2, 5]": - /// assert_eq!(iter.as_mut_slice(), &mut [2, 5]); - /// ``` - #[must_use] - // FIXME: Uncomment the `AsMut<[T]>` impl when this gets stabilized. - #[unstable(feature = "slice_iter_mut_as_mut_slice", issue = "93079")] - pub fn as_mut_slice(&mut self) -> &mut [T] { - // SAFETY: the iterator was created from a mutable slice with pointer - // `self.ptr` and length `len!(self)`. This guarantees that all the prerequisites - // for `from_raw_parts_mut` are fulfilled. - unsafe { from_raw_parts_mut(self.ptr.as_ptr(), len!(self)) } - } -} - -#[stable(feature = "slice_iter_mut_as_slice", since = "1.53.0")] -impl AsRef<[T]> for IterMut<'_, T> { - #[inline] - fn as_ref(&self) -> &[T] { - self.as_slice() - } -} - -// #[stable(feature = "slice_iter_mut_as_mut_slice", since = "FIXME")] -// impl AsMut<[T]> for IterMut<'_, T> { -// fn as_mut(&mut self) -> &mut [T] { -// self.as_mut_slice() -// } -// } - -iterator! {struct IterMut -> *mut T, &'a mut T, mut, {mut}, as_mut, {}} - -/// An internal abstraction over the splitting iterators, so that -/// splitn, splitn_mut etc can be implemented once. -#[doc(hidden)] -pub(super) trait SplitIter: DoubleEndedIterator { - /// Marks the underlying iterator as complete, extracting the remaining - /// portion of the slice. - fn finish(&mut self) -> Option; -} - -/// An iterator over subslices separated by elements that match a predicate -/// function. -/// -/// This struct is created by the [`split`] method on [slices]. -/// -/// # Example -/// -/// ``` -/// let slice = [10, 40, 33, 20]; -/// let mut iter = slice.split(|num| num % 3 == 0); -/// ``` -/// -/// [`split`]: slice::split -/// [slices]: slice -#[stable(feature = "rust1", since = "1.0.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct Split<'a, T: 'a, P> -where - P: FnMut(&T) -> bool, -{ - // Used for `SplitWhitespace` and `SplitAsciiWhitespace` `as_str` methods - pub(crate) v: &'a [T], - pred: P, - // Used for `SplitAsciiWhitespace` `as_str` method - pub(crate) finished: bool, -} - -impl<'a, T: 'a, P: FnMut(&T) -> bool> Split<'a, T, P> { - #[inline] - pub(super) fn new(slice: &'a [T], pred: P) -> Self { - Self { v: slice, pred, finished: false } - } - /// Returns a slice which contains items not yet handled by split. - /// # Example - /// - /// ``` - /// #![feature(split_as_slice)] - /// let slice = [1,2,3,4,5]; - /// let mut split = slice.split(|v| v % 2 == 0); - /// assert!(split.next().is_some()); - /// assert_eq!(split.as_slice(), &[3,4,5]); - /// ``` - #[unstable(feature = "split_as_slice", issue = "96137")] - pub fn as_slice(&self) -> &'a [T] { - if self.finished { &[] } else { &self.v } - } -} - -#[stable(feature = "core_impl_debug", since = "1.9.0")] -impl fmt::Debug for Split<'_, T, P> -where - P: FnMut(&T) -> bool, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Split").field("v", &self.v).field("finished", &self.finished).finish() - } -} - -// FIXME(#26925) Remove in favor of `#[derive(Clone)]` -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Split<'_, T, P> -where - P: Clone + FnMut(&T) -> bool, -{ - fn clone(&self) -> Self { - Split { v: self.v, pred: self.pred.clone(), finished: self.finished } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T, P> Iterator for Split<'a, T, P> -where - P: FnMut(&T) -> bool, -{ - type Item = &'a [T]; - - #[inline] - fn next(&mut self) -> Option<&'a [T]> { - if self.finished { - return None; - } - - match self.v.iter().position(|x| (self.pred)(x)) { - None => self.finish(), - Some(idx) => { - let (left, right) = - // SAFETY: if v.iter().position returns Some(idx), that - // idx is definitely a valid index for v - unsafe { (self.v.get_unchecked(..idx), self.v.get_unchecked(idx + 1..)) }; - let ret = Some(left); - self.v = right; - ret - } - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - if self.finished { - (0, Some(0)) - } else { - // If the predicate doesn't match anything, we yield one slice. - // If it matches every element, we yield `len() + 1` empty slices. - (1, Some(self.v.len() + 1)) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T, P> DoubleEndedIterator for Split<'a, T, P> -where - P: FnMut(&T) -> bool, -{ - #[inline] - fn next_back(&mut self) -> Option<&'a [T]> { - if self.finished { - return None; - } - - match self.v.iter().rposition(|x| (self.pred)(x)) { - None => self.finish(), - Some(idx) => { - let (left, right) = - // SAFETY: if v.iter().rposition returns Some(idx), then - // idx is definitely a valid index for v - unsafe { (self.v.get_unchecked(..idx), self.v.get_unchecked(idx + 1..)) }; - let ret = Some(right); - self.v = left; - ret - } - } - } -} - -impl<'a, T, P> SplitIter for Split<'a, T, P> -where - P: FnMut(&T) -> bool, -{ - #[inline] - fn finish(&mut self) -> Option<&'a [T]> { - if self.finished { - None - } else { - self.finished = true; - Some(self.v) - } - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Split<'_, T, P> where P: FnMut(&T) -> bool {} - -/// An iterator over subslices separated by elements that match a predicate -/// function. Unlike `Split`, it contains the matched part as a terminator -/// of the subslice. -/// -/// This struct is created by the [`split_inclusive`] method on [slices]. -/// -/// # Example -/// -/// ``` -/// let slice = [10, 40, 33, 20]; -/// let mut iter = slice.split_inclusive(|num| num % 3 == 0); -/// ``` -/// -/// [`split_inclusive`]: slice::split_inclusive -/// [slices]: slice -#[stable(feature = "split_inclusive", since = "1.51.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct SplitInclusive<'a, T: 'a, P> -where - P: FnMut(&T) -> bool, -{ - v: &'a [T], - pred: P, - finished: bool, -} - -impl<'a, T: 'a, P: FnMut(&T) -> bool> SplitInclusive<'a, T, P> { - #[inline] - pub(super) fn new(slice: &'a [T], pred: P) -> Self { - let finished = slice.is_empty(); - Self { v: slice, pred, finished } - } -} - -#[stable(feature = "split_inclusive", since = "1.51.0")] -impl fmt::Debug for SplitInclusive<'_, T, P> -where - P: FnMut(&T) -> bool, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("SplitInclusive") - .field("v", &self.v) - .field("finished", &self.finished) - .finish() - } -} - -// FIXME(#26925) Remove in favor of `#[derive(Clone)]` -#[stable(feature = "split_inclusive", since = "1.51.0")] -impl Clone for SplitInclusive<'_, T, P> -where - P: Clone + FnMut(&T) -> bool, -{ - fn clone(&self) -> Self { - SplitInclusive { v: self.v, pred: self.pred.clone(), finished: self.finished } - } -} - -#[stable(feature = "split_inclusive", since = "1.51.0")] -impl<'a, T, P> Iterator for SplitInclusive<'a, T, P> -where - P: FnMut(&T) -> bool, -{ - type Item = &'a [T]; - - #[inline] - fn next(&mut self) -> Option<&'a [T]> { - if self.finished { - return None; - } - - let idx = - self.v.iter().position(|x| (self.pred)(x)).map(|idx| idx + 1).unwrap_or(self.v.len()); - if idx == self.v.len() { - self.finished = true; - } - let ret = Some(&self.v[..idx]); - self.v = &self.v[idx..]; - ret - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - if self.finished { - (0, Some(0)) - } else { - // If the predicate doesn't match anything, we yield one slice. - // If it matches every element, we yield `len()` one-element slices, - // or a single empty slice. - (1, Some(cmp::max(1, self.v.len()))) - } - } -} - -#[stable(feature = "split_inclusive", since = "1.51.0")] -impl<'a, T, P> DoubleEndedIterator for SplitInclusive<'a, T, P> -where - P: FnMut(&T) -> bool, -{ - #[inline] - fn next_back(&mut self) -> Option<&'a [T]> { - if self.finished { - return None; - } - - // The last index of self.v is already checked and found to match - // by the last iteration, so we start searching a new match - // one index to the left. - let remainder = if self.v.is_empty() { &[] } else { &self.v[..(self.v.len() - 1)] }; - let idx = remainder.iter().rposition(|x| (self.pred)(x)).map(|idx| idx + 1).unwrap_or(0); - if idx == 0 { - self.finished = true; - } - let ret = Some(&self.v[idx..]); - self.v = &self.v[..idx]; - ret - } -} - -#[stable(feature = "split_inclusive", since = "1.51.0")] -impl FusedIterator for SplitInclusive<'_, T, P> where P: FnMut(&T) -> bool {} - -/// An iterator over the mutable subslices of the vector which are separated -/// by elements that match `pred`. -/// -/// This struct is created by the [`split_mut`] method on [slices]. -/// -/// # Example -/// -/// ``` -/// let mut v = [10, 40, 30, 20, 60, 50]; -/// let iter = v.split_mut(|num| *num % 3 == 0); -/// ``` -/// -/// [`split_mut`]: slice::split_mut -/// [slices]: slice -#[stable(feature = "rust1", since = "1.0.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct SplitMut<'a, T: 'a, P> -where - P: FnMut(&T) -> bool, -{ - v: &'a mut [T], - pred: P, - finished: bool, -} - -impl<'a, T: 'a, P: FnMut(&T) -> bool> SplitMut<'a, T, P> { - #[inline] - pub(super) fn new(slice: &'a mut [T], pred: P) -> Self { - Self { v: slice, pred, finished: false } - } -} - -#[stable(feature = "core_impl_debug", since = "1.9.0")] -impl fmt::Debug for SplitMut<'_, T, P> -where - P: FnMut(&T) -> bool, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("SplitMut").field("v", &self.v).field("finished", &self.finished).finish() - } -} - -impl<'a, T, P> SplitIter for SplitMut<'a, T, P> -where - P: FnMut(&T) -> bool, -{ - #[inline] - fn finish(&mut self) -> Option<&'a mut [T]> { - if self.finished { - None - } else { - self.finished = true; - Some(mem::take(&mut self.v)) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T, P> Iterator for SplitMut<'a, T, P> -where - P: FnMut(&T) -> bool, -{ - type Item = &'a mut [T]; - - #[inline] - fn next(&mut self) -> Option<&'a mut [T]> { - if self.finished { - return None; - } - - match self.v.iter().position(|x| (self.pred)(x)) { - None => self.finish(), - Some(idx) => { - let tmp = mem::take(&mut self.v); - // idx is the index of the element we are splitting on. We want to set self to the - // region after idx, and return the subslice before and not including idx. - // So first we split after idx - let (head, tail) = tmp.split_at_mut(idx + 1); - self.v = tail; - // Then return the subslice up to but not including the found element - Some(&mut head[..idx]) - } - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - if self.finished { - (0, Some(0)) - } else { - // If the predicate doesn't match anything, we yield one slice. - // If it matches every element, we yield `len() + 1` empty slices. - (1, Some(self.v.len() + 1)) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T, P> DoubleEndedIterator for SplitMut<'a, T, P> -where - P: FnMut(&T) -> bool, -{ - #[inline] - fn next_back(&mut self) -> Option<&'a mut [T]> { - if self.finished { - return None; - } - - let idx_opt = { - // work around borrowck limitations - let pred = &mut self.pred; - self.v.iter().rposition(|x| (*pred)(x)) - }; - match idx_opt { - None => self.finish(), - Some(idx) => { - let tmp = mem::take(&mut self.v); - let (head, tail) = tmp.split_at_mut(idx); - self.v = head; - Some(&mut tail[1..]) - } - } - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for SplitMut<'_, T, P> where P: FnMut(&T) -> bool {} - -/// An iterator over the mutable subslices of the vector which are separated -/// by elements that match `pred`. Unlike `SplitMut`, it contains the matched -/// parts in the ends of the subslices. -/// -/// This struct is created by the [`split_inclusive_mut`] method on [slices]. -/// -/// # Example -/// -/// ``` -/// let mut v = [10, 40, 30, 20, 60, 50]; -/// let iter = v.split_inclusive_mut(|num| *num % 3 == 0); -/// ``` -/// -/// [`split_inclusive_mut`]: slice::split_inclusive_mut -/// [slices]: slice -#[stable(feature = "split_inclusive", since = "1.51.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct SplitInclusiveMut<'a, T: 'a, P> -where - P: FnMut(&T) -> bool, -{ - v: &'a mut [T], - pred: P, - finished: bool, -} - -impl<'a, T: 'a, P: FnMut(&T) -> bool> SplitInclusiveMut<'a, T, P> { - #[inline] - pub(super) fn new(slice: &'a mut [T], pred: P) -> Self { - let finished = slice.is_empty(); - Self { v: slice, pred, finished } - } -} - -#[stable(feature = "split_inclusive", since = "1.51.0")] -impl fmt::Debug for SplitInclusiveMut<'_, T, P> -where - P: FnMut(&T) -> bool, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("SplitInclusiveMut") - .field("v", &self.v) - .field("finished", &self.finished) - .finish() - } -} - -#[stable(feature = "split_inclusive", since = "1.51.0")] -impl<'a, T, P> Iterator for SplitInclusiveMut<'a, T, P> -where - P: FnMut(&T) -> bool, -{ - type Item = &'a mut [T]; - - #[inline] - fn next(&mut self) -> Option<&'a mut [T]> { - if self.finished { - return None; - } - - let idx_opt = { - // work around borrowck limitations - let pred = &mut self.pred; - self.v.iter().position(|x| (*pred)(x)) - }; - let idx = idx_opt.map(|idx| idx + 1).unwrap_or(self.v.len()); - if idx == self.v.len() { - self.finished = true; - } - let tmp = mem::take(&mut self.v); - let (head, tail) = tmp.split_at_mut(idx); - self.v = tail; - Some(head) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - if self.finished { - (0, Some(0)) - } else { - // If the predicate doesn't match anything, we yield one slice. - // If it matches every element, we yield `len()` one-element slices, - // or a single empty slice. - (1, Some(cmp::max(1, self.v.len()))) - } - } -} - -#[stable(feature = "split_inclusive", since = "1.51.0")] -impl<'a, T, P> DoubleEndedIterator for SplitInclusiveMut<'a, T, P> -where - P: FnMut(&T) -> bool, -{ - #[inline] - fn next_back(&mut self) -> Option<&'a mut [T]> { - if self.finished { - return None; - } - - let idx_opt = if self.v.is_empty() { - None - } else { - // work around borrowck limitations - let pred = &mut self.pred; - - // The last index of self.v is already checked and found to match - // by the last iteration, so we start searching a new match - // one index to the left. - let remainder = &self.v[..(self.v.len() - 1)]; - remainder.iter().rposition(|x| (*pred)(x)) - }; - let idx = idx_opt.map(|idx| idx + 1).unwrap_or(0); - if idx == 0 { - self.finished = true; - } - let tmp = mem::take(&mut self.v); - let (head, tail) = tmp.split_at_mut(idx); - self.v = head; - Some(tail) - } -} - -#[stable(feature = "split_inclusive", since = "1.51.0")] -impl FusedIterator for SplitInclusiveMut<'_, T, P> where P: FnMut(&T) -> bool {} - -/// An iterator over subslices separated by elements that match a predicate -/// function, starting from the end of the slice. -/// -/// This struct is created by the [`rsplit`] method on [slices]. -/// -/// # Example -/// -/// ``` -/// let slice = [11, 22, 33, 0, 44, 55]; -/// let iter = slice.rsplit(|num| *num == 0); -/// ``` -/// -/// [`rsplit`]: slice::rsplit -/// [slices]: slice -#[stable(feature = "slice_rsplit", since = "1.27.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct RSplit<'a, T: 'a, P> -where - P: FnMut(&T) -> bool, -{ - inner: Split<'a, T, P>, -} - -impl<'a, T: 'a, P: FnMut(&T) -> bool> RSplit<'a, T, P> { - #[inline] - pub(super) fn new(slice: &'a [T], pred: P) -> Self { - Self { inner: Split::new(slice, pred) } - } -} - -#[stable(feature = "slice_rsplit", since = "1.27.0")] -impl fmt::Debug for RSplit<'_, T, P> -where - P: FnMut(&T) -> bool, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("RSplit") - .field("v", &self.inner.v) - .field("finished", &self.inner.finished) - .finish() - } -} - -// FIXME(#26925) Remove in favor of `#[derive(Clone)]` -#[stable(feature = "slice_rsplit", since = "1.27.0")] -impl Clone for RSplit<'_, T, P> -where - P: Clone + FnMut(&T) -> bool, -{ - fn clone(&self) -> Self { - RSplit { inner: self.inner.clone() } - } -} - -#[stable(feature = "slice_rsplit", since = "1.27.0")] -impl<'a, T, P> Iterator for RSplit<'a, T, P> -where - P: FnMut(&T) -> bool, -{ - type Item = &'a [T]; - - #[inline] - fn next(&mut self) -> Option<&'a [T]> { - self.inner.next_back() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } -} - -#[stable(feature = "slice_rsplit", since = "1.27.0")] -impl<'a, T, P> DoubleEndedIterator for RSplit<'a, T, P> -where - P: FnMut(&T) -> bool, -{ - #[inline] - fn next_back(&mut self) -> Option<&'a [T]> { - self.inner.next() - } -} - -#[stable(feature = "slice_rsplit", since = "1.27.0")] -impl<'a, T, P> SplitIter for RSplit<'a, T, P> -where - P: FnMut(&T) -> bool, -{ - #[inline] - fn finish(&mut self) -> Option<&'a [T]> { - self.inner.finish() - } -} - -#[stable(feature = "slice_rsplit", since = "1.27.0")] -impl FusedIterator for RSplit<'_, T, P> where P: FnMut(&T) -> bool {} - -/// An iterator over the subslices of the vector which are separated -/// by elements that match `pred`, starting from the end of the slice. -/// -/// This struct is created by the [`rsplit_mut`] method on [slices]. -/// -/// # Example -/// -/// ``` -/// let mut slice = [11, 22, 33, 0, 44, 55]; -/// let iter = slice.rsplit_mut(|num| *num == 0); -/// ``` -/// -/// [`rsplit_mut`]: slice::rsplit_mut -/// [slices]: slice -#[stable(feature = "slice_rsplit", since = "1.27.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct RSplitMut<'a, T: 'a, P> -where - P: FnMut(&T) -> bool, -{ - inner: SplitMut<'a, T, P>, -} - -impl<'a, T: 'a, P: FnMut(&T) -> bool> RSplitMut<'a, T, P> { - #[inline] - pub(super) fn new(slice: &'a mut [T], pred: P) -> Self { - Self { inner: SplitMut::new(slice, pred) } - } -} - -#[stable(feature = "slice_rsplit", since = "1.27.0")] -impl fmt::Debug for RSplitMut<'_, T, P> -where - P: FnMut(&T) -> bool, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("RSplitMut") - .field("v", &self.inner.v) - .field("finished", &self.inner.finished) - .finish() - } -} - -#[stable(feature = "slice_rsplit", since = "1.27.0")] -impl<'a, T, P> SplitIter for RSplitMut<'a, T, P> -where - P: FnMut(&T) -> bool, -{ - #[inline] - fn finish(&mut self) -> Option<&'a mut [T]> { - self.inner.finish() - } -} - -#[stable(feature = "slice_rsplit", since = "1.27.0")] -impl<'a, T, P> Iterator for RSplitMut<'a, T, P> -where - P: FnMut(&T) -> bool, -{ - type Item = &'a mut [T]; - - #[inline] - fn next(&mut self) -> Option<&'a mut [T]> { - self.inner.next_back() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } -} - -#[stable(feature = "slice_rsplit", since = "1.27.0")] -impl<'a, T, P> DoubleEndedIterator for RSplitMut<'a, T, P> -where - P: FnMut(&T) -> bool, -{ - #[inline] - fn next_back(&mut self) -> Option<&'a mut [T]> { - self.inner.next() - } -} - -#[stable(feature = "slice_rsplit", since = "1.27.0")] -impl FusedIterator for RSplitMut<'_, T, P> where P: FnMut(&T) -> bool {} - -/// An private iterator over subslices separated by elements that -/// match a predicate function, splitting at most a fixed number of -/// times. -#[derive(Debug)] -struct GenericSplitN { - iter: I, - count: usize, -} - -impl> Iterator for GenericSplitN { - type Item = T; - - #[inline] - fn next(&mut self) -> Option { - match self.count { - 0 => None, - 1 => { - self.count -= 1; - self.iter.finish() - } - _ => { - self.count -= 1; - self.iter.next() - } - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let (lower, upper_opt) = self.iter.size_hint(); - ( - cmp::min(self.count, lower), - Some(upper_opt.map_or(self.count, |upper| cmp::min(self.count, upper))), - ) - } -} - -/// An iterator over subslices separated by elements that match a predicate -/// function, limited to a given number of splits. -/// -/// This struct is created by the [`splitn`] method on [slices]. -/// -/// # Example -/// -/// ``` -/// let slice = [10, 40, 30, 20, 60, 50]; -/// let iter = slice.splitn(2, |num| *num % 3 == 0); -/// ``` -/// -/// [`splitn`]: slice::splitn -/// [slices]: slice -#[stable(feature = "rust1", since = "1.0.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct SplitN<'a, T: 'a, P> -where - P: FnMut(&T) -> bool, -{ - inner: GenericSplitN>, -} - -impl<'a, T: 'a, P: FnMut(&T) -> bool> SplitN<'a, T, P> { - #[inline] - pub(super) fn new(s: Split<'a, T, P>, n: usize) -> Self { - Self { inner: GenericSplitN { iter: s, count: n } } - } -} - -#[stable(feature = "core_impl_debug", since = "1.9.0")] -impl fmt::Debug for SplitN<'_, T, P> -where - P: FnMut(&T) -> bool, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("SplitN").field("inner", &self.inner).finish() - } -} - -/// An iterator over subslices separated by elements that match a -/// predicate function, limited to a given number of splits, starting -/// from the end of the slice. -/// -/// This struct is created by the [`rsplitn`] method on [slices]. -/// -/// # Example -/// -/// ``` -/// let slice = [10, 40, 30, 20, 60, 50]; -/// let iter = slice.rsplitn(2, |num| *num % 3 == 0); -/// ``` -/// -/// [`rsplitn`]: slice::rsplitn -/// [slices]: slice -#[stable(feature = "rust1", since = "1.0.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct RSplitN<'a, T: 'a, P> -where - P: FnMut(&T) -> bool, -{ - inner: GenericSplitN>, -} - -impl<'a, T: 'a, P: FnMut(&T) -> bool> RSplitN<'a, T, P> { - #[inline] - pub(super) fn new(s: RSplit<'a, T, P>, n: usize) -> Self { - Self { inner: GenericSplitN { iter: s, count: n } } - } -} - -#[stable(feature = "core_impl_debug", since = "1.9.0")] -impl fmt::Debug for RSplitN<'_, T, P> -where - P: FnMut(&T) -> bool, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("RSplitN").field("inner", &self.inner).finish() - } -} - -/// An iterator over subslices separated by elements that match a predicate -/// function, limited to a given number of splits. -/// -/// This struct is created by the [`splitn_mut`] method on [slices]. -/// -/// # Example -/// -/// ``` -/// let mut slice = [10, 40, 30, 20, 60, 50]; -/// let iter = slice.splitn_mut(2, |num| *num % 3 == 0); -/// ``` -/// -/// [`splitn_mut`]: slice::splitn_mut -/// [slices]: slice -#[stable(feature = "rust1", since = "1.0.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct SplitNMut<'a, T: 'a, P> -where - P: FnMut(&T) -> bool, -{ - inner: GenericSplitN>, -} - -impl<'a, T: 'a, P: FnMut(&T) -> bool> SplitNMut<'a, T, P> { - #[inline] - pub(super) fn new(s: SplitMut<'a, T, P>, n: usize) -> Self { - Self { inner: GenericSplitN { iter: s, count: n } } - } -} - -#[stable(feature = "core_impl_debug", since = "1.9.0")] -impl fmt::Debug for SplitNMut<'_, T, P> -where - P: FnMut(&T) -> bool, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("SplitNMut").field("inner", &self.inner).finish() - } -} - -/// An iterator over subslices separated by elements that match a -/// predicate function, limited to a given number of splits, starting -/// from the end of the slice. -/// -/// This struct is created by the [`rsplitn_mut`] method on [slices]. -/// -/// # Example -/// -/// ``` -/// let mut slice = [10, 40, 30, 20, 60, 50]; -/// let iter = slice.rsplitn_mut(2, |num| *num % 3 == 0); -/// ``` -/// -/// [`rsplitn_mut`]: slice::rsplitn_mut -/// [slices]: slice -#[stable(feature = "rust1", since = "1.0.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct RSplitNMut<'a, T: 'a, P> -where - P: FnMut(&T) -> bool, -{ - inner: GenericSplitN>, -} - -impl<'a, T: 'a, P: FnMut(&T) -> bool> RSplitNMut<'a, T, P> { - #[inline] - pub(super) fn new(s: RSplitMut<'a, T, P>, n: usize) -> Self { - Self { inner: GenericSplitN { iter: s, count: n } } - } -} - -#[stable(feature = "core_impl_debug", since = "1.9.0")] -impl fmt::Debug for RSplitNMut<'_, T, P> -where - P: FnMut(&T) -> bool, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("RSplitNMut").field("inner", &self.inner).finish() - } -} - -forward_iterator! { SplitN: T, &'a [T] } -forward_iterator! { RSplitN: T, &'a [T] } -forward_iterator! { SplitNMut: T, &'a mut [T] } -forward_iterator! { RSplitNMut: T, &'a mut [T] } - -/// An iterator over overlapping subslices of length `size`. -/// -/// This struct is created by the [`windows`] method on [slices]. -/// -/// # Example -/// -/// ``` -/// let slice = ['r', 'u', 's', 't']; -/// let iter = slice.windows(2); -/// ``` -/// -/// [`windows`]: slice::windows -/// [slices]: slice -#[derive(Debug)] -#[stable(feature = "rust1", since = "1.0.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct Windows<'a, T: 'a> { - v: &'a [T], - size: NonZero, -} - -impl<'a, T: 'a> Windows<'a, T> { - #[inline] - pub(super) fn new(slice: &'a [T], size: NonZero) -> Self { - Self { v: slice, size } - } -} - -// FIXME(#26925) Remove in favor of `#[derive(Clone)]` -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Windows<'_, T> { - fn clone(&self) -> Self { - Windows { v: self.v, size: self.size } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> Iterator for Windows<'a, T> { - type Item = &'a [T]; - - #[inline] - fn next(&mut self) -> Option<&'a [T]> { - if self.size.get() > self.v.len() { - None - } else { - let ret = Some(&self.v[..self.size.get()]); - self.v = &self.v[1..]; - ret - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - if self.size.get() > self.v.len() { - (0, Some(0)) - } else { - let size = self.v.len() - self.size.get() + 1; - (size, Some(size)) - } - } - - #[inline] - fn count(self) -> usize { - self.len() - } - - #[inline] - fn nth(&mut self, n: usize) -> Option { - let (end, overflow) = self.size.get().overflowing_add(n); - if end > self.v.len() || overflow { - self.v = &[]; - None - } else { - let nth = &self.v[n..end]; - self.v = &self.v[n + 1..]; - Some(nth) - } - } - - #[inline] - fn last(self) -> Option { - if self.size.get() > self.v.len() { - None - } else { - let start = self.v.len() - self.size.get(); - Some(&self.v[start..]) - } - } - - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item { - // SAFETY: since the caller guarantees that `i` is in bounds, - // which means that `i` cannot overflow an `isize`, and the - // slice created by `from_raw_parts` is a subslice of `self.v` - // thus is guaranteed to be valid for the lifetime `'a` of `self.v`. - unsafe { from_raw_parts(self.v.as_ptr().add(idx), self.size.get()) } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> DoubleEndedIterator for Windows<'a, T> { - #[inline] - fn next_back(&mut self) -> Option<&'a [T]> { - if self.size.get() > self.v.len() { - None - } else { - let ret = Some(&self.v[self.v.len() - self.size.get()..]); - self.v = &self.v[..self.v.len() - 1]; - ret - } - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option { - let (end, overflow) = self.v.len().overflowing_sub(n); - if end < self.size.get() || overflow { - self.v = &[]; - None - } else { - let ret = &self.v[end - self.size.get()..end]; - self.v = &self.v[..end - 1]; - Some(ret) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Windows<'_, T> {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for Windows<'_, T> {} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Windows<'_, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl<'a, T> TrustedRandomAccess for Windows<'a, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl<'a, T> TrustedRandomAccessNoCoerce for Windows<'a, T> { - const MAY_HAVE_SIDE_EFFECT: bool = false; -} - -/// An iterator over a slice in (non-overlapping) chunks (`chunk_size` elements at a -/// time), starting at the beginning of the slice. -/// -/// When the slice len is not evenly divided by the chunk size, the last slice -/// of the iteration will be the remainder. -/// -/// This struct is created by the [`chunks`] method on [slices]. -/// -/// # Example -/// -/// ``` -/// let slice = ['l', 'o', 'r', 'e', 'm']; -/// let iter = slice.chunks(2); -/// ``` -/// -/// [`chunks`]: slice::chunks -/// [slices]: slice -#[derive(Debug)] -#[stable(feature = "rust1", since = "1.0.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct Chunks<'a, T: 'a> { - v: &'a [T], - chunk_size: usize, -} - -impl<'a, T: 'a> Chunks<'a, T> { - #[inline] - pub(super) fn new(slice: &'a [T], size: usize) -> Self { - Self { v: slice, chunk_size: size } - } -} - -// FIXME(#26925) Remove in favor of `#[derive(Clone)]` -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Chunks<'_, T> { - fn clone(&self) -> Self { - Chunks { v: self.v, chunk_size: self.chunk_size } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> Iterator for Chunks<'a, T> { - type Item = &'a [T]; - - #[inline] - fn next(&mut self) -> Option<&'a [T]> { - if self.v.is_empty() { - None - } else { - let chunksz = cmp::min(self.v.len(), self.chunk_size); - let (fst, snd) = self.v.split_at(chunksz); - self.v = snd; - Some(fst) - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - if self.v.is_empty() { - (0, Some(0)) - } else { - let n = self.v.len() / self.chunk_size; - let rem = self.v.len() % self.chunk_size; - let n = if rem > 0 { n + 1 } else { n }; - (n, Some(n)) - } - } - - #[inline] - fn count(self) -> usize { - self.len() - } - - #[inline] - fn nth(&mut self, n: usize) -> Option { - let (start, overflow) = n.overflowing_mul(self.chunk_size); - if start >= self.v.len() || overflow { - self.v = &[]; - None - } else { - let end = match start.checked_add(self.chunk_size) { - Some(sum) => cmp::min(self.v.len(), sum), - None => self.v.len(), - }; - let nth = &self.v[start..end]; - self.v = &self.v[end..]; - Some(nth) - } - } - - #[inline] - fn last(self) -> Option { - if self.v.is_empty() { - None - } else { - let start = (self.v.len() - 1) / self.chunk_size * self.chunk_size; - Some(&self.v[start..]) - } - } - - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item { - let start = idx * self.chunk_size; - // SAFETY: the caller guarantees that `i` is in bounds, - // which means that `start` must be in bounds of the - // underlying `self.v` slice, and we made sure that `len` - // is also in bounds of `self.v`. Thus, `start` cannot overflow - // an `isize`, and the slice constructed by `from_raw_parts` - // is a subslice of `self.v` which is guaranteed to be valid - // for the lifetime `'a` of `self.v`. - unsafe { - let len = cmp::min(self.v.len().unchecked_sub(start), self.chunk_size); - from_raw_parts(self.v.as_ptr().add(start), len) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> DoubleEndedIterator for Chunks<'a, T> { - #[inline] - fn next_back(&mut self) -> Option<&'a [T]> { - if self.v.is_empty() { - None - } else { - let remainder = self.v.len() % self.chunk_size; - let chunksz = if remainder != 0 { remainder } else { self.chunk_size }; - // SAFETY: split_at_unchecked requires the argument be less than or - // equal to the length. This is guaranteed, but subtle: `chunksz` - // will always either be `self.v.len() % self.chunk_size`, which - // will always evaluate to strictly less than `self.v.len()` (or - // panic, in the case that `self.chunk_size` is zero), or it can be - // `self.chunk_size`, in the case that the length is exactly - // divisible by the chunk size. - // - // While it seems like using `self.chunk_size` in this case could - // lead to a value greater than `self.v.len()`, it cannot: if - // `self.chunk_size` were greater than `self.v.len()`, then - // `self.v.len() % self.chunk_size` would return nonzero (note that - // in this branch of the `if`, we already know that `self.v` is - // non-empty). - let (fst, snd) = unsafe { self.v.split_at_unchecked(self.v.len() - chunksz) }; - self.v = fst; - Some(snd) - } - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option { - let len = self.len(); - if n >= len { - self.v = &[]; - None - } else { - let start = (len - 1 - n) * self.chunk_size; - let end = match start.checked_add(self.chunk_size) { - Some(res) => cmp::min(self.v.len(), res), - None => self.v.len(), - }; - let nth_back = &self.v[start..end]; - self.v = &self.v[..start]; - Some(nth_back) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Chunks<'_, T> {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for Chunks<'_, T> {} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Chunks<'_, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl<'a, T> TrustedRandomAccess for Chunks<'a, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl<'a, T> TrustedRandomAccessNoCoerce for Chunks<'a, T> { - const MAY_HAVE_SIDE_EFFECT: bool = false; -} - -/// An iterator over a slice in (non-overlapping) mutable chunks (`chunk_size` -/// elements at a time), starting at the beginning of the slice. -/// -/// When the slice len is not evenly divided by the chunk size, the last slice -/// of the iteration will be the remainder. -/// -/// This struct is created by the [`chunks_mut`] method on [slices]. -/// -/// # Example -/// -/// ``` -/// let mut slice = ['l', 'o', 'r', 'e', 'm']; -/// let iter = slice.chunks_mut(2); -/// ``` -/// -/// [`chunks_mut`]: slice::chunks_mut -/// [slices]: slice -#[derive(Debug)] -#[stable(feature = "rust1", since = "1.0.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct ChunksMut<'a, T: 'a> { - /// # Safety - /// This slice pointer must point at a valid region of `T` with at least length `v.len()`. Normally, - /// those requirements would mean that we could instead use a `&mut [T]` here, but we cannot - /// because `__iterator_get_unchecked` needs to return `&mut [T]`, which guarantees certain aliasing - /// properties that we cannot uphold if we hold on to the full original `&mut [T]`. Wrapping a raw - /// slice instead lets us hand out non-overlapping `&mut [T]` subslices of the slice we wrap. - v: *mut [T], - chunk_size: usize, - _marker: PhantomData<&'a mut T>, -} - -impl<'a, T: 'a> ChunksMut<'a, T> { - #[inline] - pub(super) fn new(slice: &'a mut [T], size: usize) -> Self { - Self { v: slice, chunk_size: size, _marker: PhantomData } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> Iterator for ChunksMut<'a, T> { - type Item = &'a mut [T]; - - #[inline] - fn next(&mut self) -> Option<&'a mut [T]> { - if self.v.is_empty() { - None - } else { - let sz = cmp::min(self.v.len(), self.chunk_size); - // SAFETY: The self.v contract ensures that any split_at_mut is valid. - let (head, tail) = unsafe { self.v.split_at_mut(sz) }; - self.v = tail; - // SAFETY: Nothing else points to or will point to the contents of this slice. - Some(unsafe { &mut *head }) - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - if self.v.is_empty() { - (0, Some(0)) - } else { - let n = self.v.len() / self.chunk_size; - let rem = self.v.len() % self.chunk_size; - let n = if rem > 0 { n + 1 } else { n }; - (n, Some(n)) - } - } - - #[inline] - fn count(self) -> usize { - self.len() - } - - #[inline] - fn nth(&mut self, n: usize) -> Option<&'a mut [T]> { - let (start, overflow) = n.overflowing_mul(self.chunk_size); - if start >= self.v.len() || overflow { - self.v = &mut []; - None - } else { - let end = match start.checked_add(self.chunk_size) { - Some(sum) => cmp::min(self.v.len(), sum), - None => self.v.len(), - }; - // SAFETY: The self.v contract ensures that any split_at_mut is valid. - let (head, tail) = unsafe { self.v.split_at_mut(end) }; - // SAFETY: The self.v contract ensures that any split_at_mut is valid. - let (_, nth) = unsafe { head.split_at_mut(start) }; - self.v = tail; - // SAFETY: Nothing else points to or will point to the contents of this slice. - Some(unsafe { &mut *nth }) - } - } - - #[inline] - fn last(self) -> Option { - if self.v.is_empty() { - None - } else { - let start = (self.v.len() - 1) / self.chunk_size * self.chunk_size; - // SAFETY: Nothing else points to or will point to the contents of this slice. - Some(unsafe { &mut *self.v.get_unchecked_mut(start..) }) - } - } - - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item { - let start = idx * self.chunk_size; - // SAFETY: see comments for `Chunks::__iterator_get_unchecked` and `self.v`. - // - // Also note that the caller also guarantees that we're never called - // with the same index again, and that no other methods that will - // access this subslice are called, so it is valid for the returned - // slice to be mutable. - unsafe { - let len = cmp::min(self.v.len().unchecked_sub(start), self.chunk_size); - from_raw_parts_mut(self.v.as_mut_ptr().add(start), len) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> DoubleEndedIterator for ChunksMut<'a, T> { - #[inline] - fn next_back(&mut self) -> Option<&'a mut [T]> { - if self.v.is_empty() { - None - } else { - let remainder = self.v.len() % self.chunk_size; - let sz = if remainder != 0 { remainder } else { self.chunk_size }; - let len = self.v.len(); - // SAFETY: Similar to `Chunks::next_back` - let (head, tail) = unsafe { self.v.split_at_mut_unchecked(len - sz) }; - self.v = head; - // SAFETY: Nothing else points to or will point to the contents of this slice. - Some(unsafe { &mut *tail }) - } - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option { - let len = self.len(); - if n >= len { - self.v = &mut []; - None - } else { - let start = (len - 1 - n) * self.chunk_size; - let end = match start.checked_add(self.chunk_size) { - Some(res) => cmp::min(self.v.len(), res), - None => self.v.len(), - }; - // SAFETY: The self.v contract ensures that any split_at_mut is valid. - let (temp, _tail) = unsafe { self.v.split_at_mut(end) }; - // SAFETY: The self.v contract ensures that any split_at_mut is valid. - let (head, nth_back) = unsafe { temp.split_at_mut(start) }; - self.v = head; - // SAFETY: Nothing else points to or will point to the contents of this slice. - Some(unsafe { &mut *nth_back }) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for ChunksMut<'_, T> {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for ChunksMut<'_, T> {} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for ChunksMut<'_, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl<'a, T> TrustedRandomAccess for ChunksMut<'a, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl<'a, T> TrustedRandomAccessNoCoerce for ChunksMut<'a, T> { - const MAY_HAVE_SIDE_EFFECT: bool = false; -} - -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Send for ChunksMut<'_, T> where T: Send {} - -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Sync for ChunksMut<'_, T> where T: Sync {} - -/// An iterator over a slice in (non-overlapping) chunks (`chunk_size` elements at a -/// time), starting at the beginning of the slice. -/// -/// When the slice len is not evenly divided by the chunk size, the last -/// up to `chunk_size-1` elements will be omitted but can be retrieved from -/// the [`remainder`] function from the iterator. -/// -/// This struct is created by the [`chunks_exact`] method on [slices]. -/// -/// # Example -/// -/// ``` -/// let slice = ['l', 'o', 'r', 'e', 'm']; -/// let iter = slice.chunks_exact(2); -/// ``` -/// -/// [`chunks_exact`]: slice::chunks_exact -/// [`remainder`]: ChunksExact::remainder -/// [slices]: slice -#[derive(Debug)] -#[stable(feature = "chunks_exact", since = "1.31.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct ChunksExact<'a, T: 'a> { - v: &'a [T], - rem: &'a [T], - chunk_size: usize, -} - -impl<'a, T> ChunksExact<'a, T> { - #[inline] - pub(super) fn new(slice: &'a [T], chunk_size: usize) -> Self { - let rem = slice.len() % chunk_size; - let fst_len = slice.len() - rem; - // SAFETY: 0 <= fst_len <= slice.len() by construction above - let (fst, snd) = unsafe { slice.split_at_unchecked(fst_len) }; - Self { v: fst, rem: snd, chunk_size } - } - - /// Returns the remainder of the original slice that is not going to be - /// returned by the iterator. The returned slice has at most `chunk_size-1` - /// elements. - /// - /// # Example - /// - /// ``` - /// let slice = ['l', 'o', 'r', 'e', 'm']; - /// let mut iter = slice.chunks_exact(2); - /// assert_eq!(iter.remainder(), &['m'][..]); - /// assert_eq!(iter.next(), Some(&['l', 'o'][..])); - /// assert_eq!(iter.remainder(), &['m'][..]); - /// assert_eq!(iter.next(), Some(&['r', 'e'][..])); - /// assert_eq!(iter.remainder(), &['m'][..]); - /// assert_eq!(iter.next(), None); - /// assert_eq!(iter.remainder(), &['m'][..]); - /// ``` - #[must_use] - #[stable(feature = "chunks_exact", since = "1.31.0")] - pub fn remainder(&self) -> &'a [T] { - self.rem - } -} - -// FIXME(#26925) Remove in favor of `#[derive(Clone)]` -#[stable(feature = "chunks_exact", since = "1.31.0")] -impl Clone for ChunksExact<'_, T> { - fn clone(&self) -> Self { - ChunksExact { v: self.v, rem: self.rem, chunk_size: self.chunk_size } - } -} - -#[stable(feature = "chunks_exact", since = "1.31.0")] -impl<'a, T> Iterator for ChunksExact<'a, T> { - type Item = &'a [T]; - - #[inline] - fn next(&mut self) -> Option<&'a [T]> { - if self.v.len() < self.chunk_size { - None - } else { - let (fst, snd) = self.v.split_at(self.chunk_size); - self.v = snd; - Some(fst) - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let n = self.v.len() / self.chunk_size; - (n, Some(n)) - } - - #[inline] - fn count(self) -> usize { - self.len() - } - - #[inline] - fn nth(&mut self, n: usize) -> Option { - let (start, overflow) = n.overflowing_mul(self.chunk_size); - if start >= self.v.len() || overflow { - self.v = &[]; - None - } else { - let (_, snd) = self.v.split_at(start); - self.v = snd; - self.next() - } - } - - #[inline] - fn last(mut self) -> Option { - self.next_back() - } - - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item { - let start = idx * self.chunk_size; - // SAFETY: mostly identical to `Chunks::__iterator_get_unchecked`. - unsafe { from_raw_parts(self.v.as_ptr().add(start), self.chunk_size) } - } -} - -#[stable(feature = "chunks_exact", since = "1.31.0")] -impl<'a, T> DoubleEndedIterator for ChunksExact<'a, T> { - #[inline] - fn next_back(&mut self) -> Option<&'a [T]> { - if self.v.len() < self.chunk_size { - None - } else { - let (fst, snd) = self.v.split_at(self.v.len() - self.chunk_size); - self.v = fst; - Some(snd) - } - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option { - let len = self.len(); - if n >= len { - self.v = &[]; - None - } else { - let start = (len - 1 - n) * self.chunk_size; - let end = start + self.chunk_size; - let nth_back = &self.v[start..end]; - self.v = &self.v[..start]; - Some(nth_back) - } - } -} - -#[stable(feature = "chunks_exact", since = "1.31.0")] -impl ExactSizeIterator for ChunksExact<'_, T> { - fn is_empty(&self) -> bool { - self.v.is_empty() - } -} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for ChunksExact<'_, T> {} - -#[stable(feature = "chunks_exact", since = "1.31.0")] -impl FusedIterator for ChunksExact<'_, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl<'a, T> TrustedRandomAccess for ChunksExact<'a, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl<'a, T> TrustedRandomAccessNoCoerce for ChunksExact<'a, T> { - const MAY_HAVE_SIDE_EFFECT: bool = false; -} - -/// An iterator over a slice in (non-overlapping) mutable chunks (`chunk_size` -/// elements at a time), starting at the beginning of the slice. -/// -/// When the slice len is not evenly divided by the chunk size, the last up to -/// `chunk_size-1` elements will be omitted but can be retrieved from the -/// [`into_remainder`] function from the iterator. -/// -/// This struct is created by the [`chunks_exact_mut`] method on [slices]. -/// -/// # Example -/// -/// ``` -/// let mut slice = ['l', 'o', 'r', 'e', 'm']; -/// let iter = slice.chunks_exact_mut(2); -/// ``` -/// -/// [`chunks_exact_mut`]: slice::chunks_exact_mut -/// [`into_remainder`]: ChunksExactMut::into_remainder -/// [slices]: slice -#[derive(Debug)] -#[stable(feature = "chunks_exact", since = "1.31.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct ChunksExactMut<'a, T: 'a> { - /// # Safety - /// This slice pointer must point at a valid region of `T` with at least length `v.len()`. Normally, - /// those requirements would mean that we could instead use a `&mut [T]` here, but we cannot - /// because `__iterator_get_unchecked` needs to return `&mut [T]`, which guarantees certain aliasing - /// properties that we cannot uphold if we hold on to the full original `&mut [T]`. Wrapping a raw - /// slice instead lets us hand out non-overlapping `&mut [T]` subslices of the slice we wrap. - v: *mut [T], - rem: &'a mut [T], // The iterator never yields from here, so this can be unique - chunk_size: usize, - _marker: PhantomData<&'a mut T>, -} - -impl<'a, T> ChunksExactMut<'a, T> { - #[inline] - pub(super) fn new(slice: &'a mut [T], chunk_size: usize) -> Self { - let rem = slice.len() % chunk_size; - let fst_len = slice.len() - rem; - // SAFETY: 0 <= fst_len <= slice.len() by construction above - let (fst, snd) = unsafe { slice.split_at_mut_unchecked(fst_len) }; - Self { v: fst, rem: snd, chunk_size, _marker: PhantomData } - } - - /// Returns the remainder of the original slice that is not going to be - /// returned by the iterator. The returned slice has at most `chunk_size-1` - /// elements. - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "chunks_exact", since = "1.31.0")] - pub fn into_remainder(self) -> &'a mut [T] { - self.rem - } -} - -#[stable(feature = "chunks_exact", since = "1.31.0")] -impl<'a, T> Iterator for ChunksExactMut<'a, T> { - type Item = &'a mut [T]; - - #[inline] - fn next(&mut self) -> Option<&'a mut [T]> { - if self.v.len() < self.chunk_size { - None - } else { - // SAFETY: self.chunk_size is inbounds because we compared above against self.v.len() - let (head, tail) = unsafe { self.v.split_at_mut(self.chunk_size) }; - self.v = tail; - // SAFETY: Nothing else points to or will point to the contents of this slice. - Some(unsafe { &mut *head }) - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let n = self.v.len() / self.chunk_size; - (n, Some(n)) - } - - #[inline] - fn count(self) -> usize { - self.len() - } - - #[inline] - fn nth(&mut self, n: usize) -> Option<&'a mut [T]> { - let (start, overflow) = n.overflowing_mul(self.chunk_size); - if start >= self.v.len() || overflow { - self.v = &mut []; - None - } else { - // SAFETY: The self.v contract ensures that any split_at_mut is valid. - let (_, snd) = unsafe { self.v.split_at_mut(start) }; - self.v = snd; - self.next() - } - } - - #[inline] - fn last(mut self) -> Option { - self.next_back() - } - - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item { - let start = idx * self.chunk_size; - // SAFETY: see comments for `Chunks::__iterator_get_unchecked` and `self.v`. - unsafe { from_raw_parts_mut(self.v.as_mut_ptr().add(start), self.chunk_size) } - } -} - -#[stable(feature = "chunks_exact", since = "1.31.0")] -impl<'a, T> DoubleEndedIterator for ChunksExactMut<'a, T> { - #[inline] - fn next_back(&mut self) -> Option<&'a mut [T]> { - if self.v.len() < self.chunk_size { - None - } else { - // SAFETY: This subtraction is inbounds because of the check above - let (head, tail) = unsafe { self.v.split_at_mut(self.v.len() - self.chunk_size) }; - self.v = head; - // SAFETY: Nothing else points to or will point to the contents of this slice. - Some(unsafe { &mut *tail }) - } - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option { - let len = self.len(); - if n >= len { - self.v = &mut []; - None - } else { - let start = (len - 1 - n) * self.chunk_size; - let end = start + self.chunk_size; - // SAFETY: The self.v contract ensures that any split_at_mut is valid. - let (temp, _tail) = unsafe { mem::replace(&mut self.v, &mut []).split_at_mut(end) }; - // SAFETY: The self.v contract ensures that any split_at_mut is valid. - let (head, nth_back) = unsafe { temp.split_at_mut(start) }; - self.v = head; - // SAFETY: Nothing else points to or will point to the contents of this slice. - Some(unsafe { &mut *nth_back }) - } - } -} - -#[stable(feature = "chunks_exact", since = "1.31.0")] -impl ExactSizeIterator for ChunksExactMut<'_, T> { - fn is_empty(&self) -> bool { - self.v.is_empty() - } -} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for ChunksExactMut<'_, T> {} - -#[stable(feature = "chunks_exact", since = "1.31.0")] -impl FusedIterator for ChunksExactMut<'_, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl<'a, T> TrustedRandomAccess for ChunksExactMut<'a, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl<'a, T> TrustedRandomAccessNoCoerce for ChunksExactMut<'a, T> { - const MAY_HAVE_SIDE_EFFECT: bool = false; -} - -#[stable(feature = "chunks_exact", since = "1.31.0")] -unsafe impl Send for ChunksExactMut<'_, T> where T: Send {} - -#[stable(feature = "chunks_exact", since = "1.31.0")] -unsafe impl Sync for ChunksExactMut<'_, T> where T: Sync {} - -/// A windowed iterator over a slice in overlapping chunks (`N` elements at a -/// time), starting at the beginning of the slice -/// -/// This struct is created by the [`array_windows`] method on [slices]. -/// -/// # Example -/// -/// ``` -/// #![feature(array_windows)] -/// -/// let slice = [0, 1, 2, 3]; -/// let iter = slice.array_windows::<2>(); -/// ``` -/// -/// [`array_windows`]: slice::array_windows -/// [slices]: slice -#[derive(Debug, Clone, Copy)] -#[unstable(feature = "array_windows", issue = "75027")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct ArrayWindows<'a, T: 'a, const N: usize> { - slice_head: *const T, - num: usize, - marker: PhantomData<&'a [T; N]>, -} - -impl<'a, T: 'a, const N: usize> ArrayWindows<'a, T, N> { - #[inline] - pub(super) fn new(slice: &'a [T]) -> Self { - let num_windows = slice.len().saturating_sub(N - 1); - Self { slice_head: slice.as_ptr(), num: num_windows, marker: PhantomData } - } -} - -#[unstable(feature = "array_windows", issue = "75027")] -impl<'a, T, const N: usize> Iterator for ArrayWindows<'a, T, N> { - type Item = &'a [T; N]; - - #[inline] - fn next(&mut self) -> Option { - if self.num == 0 { - return None; - } - // SAFETY: - // This is safe because it's indexing into a slice guaranteed to be length > N. - let ret = unsafe { &*self.slice_head.cast::<[T; N]>() }; - // SAFETY: Guaranteed that there are at least 1 item remaining otherwise - // earlier branch would've been hit - self.slice_head = unsafe { self.slice_head.add(1) }; - - self.num -= 1; - Some(ret) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - (self.num, Some(self.num)) - } - - #[inline] - fn count(self) -> usize { - self.num - } - - #[inline] - fn nth(&mut self, n: usize) -> Option { - if self.num <= n { - self.num = 0; - return None; - } - // SAFETY: - // This is safe because it's indexing into a slice guaranteed to be length > N. - let ret = unsafe { &*self.slice_head.add(n).cast::<[T; N]>() }; - // SAFETY: Guaranteed that there are at least n items remaining - self.slice_head = unsafe { self.slice_head.add(n + 1) }; - - self.num -= n + 1; - Some(ret) - } - - #[inline] - fn last(mut self) -> Option { - self.nth(self.num.checked_sub(1)?) - } -} - -#[unstable(feature = "array_windows", issue = "75027")] -impl<'a, T, const N: usize> DoubleEndedIterator for ArrayWindows<'a, T, N> { - #[inline] - fn next_back(&mut self) -> Option<&'a [T; N]> { - if self.num == 0 { - return None; - } - // SAFETY: Guaranteed that there are n items remaining, n-1 for 0-indexing. - let ret = unsafe { &*self.slice_head.add(self.num - 1).cast::<[T; N]>() }; - self.num -= 1; - Some(ret) - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option<&'a [T; N]> { - if self.num <= n { - self.num = 0; - return None; - } - // SAFETY: Guaranteed that there are n items remaining, n-1 for 0-indexing. - let ret = unsafe { &*self.slice_head.add(self.num - (n + 1)).cast::<[T; N]>() }; - self.num -= n + 1; - Some(ret) - } -} - -#[unstable(feature = "array_windows", issue = "75027")] -impl ExactSizeIterator for ArrayWindows<'_, T, N> { - fn is_empty(&self) -> bool { - self.num == 0 - } -} - -/// An iterator over a slice in (non-overlapping) chunks (`N` elements at a -/// time), starting at the beginning of the slice. -/// -/// When the slice len is not evenly divided by the chunk size, the last -/// up to `N-1` elements will be omitted but can be retrieved from -/// the [`remainder`] function from the iterator. -/// -/// This struct is created by the [`array_chunks`] method on [slices]. -/// -/// # Example -/// -/// ``` -/// #![feature(array_chunks)] -/// -/// let slice = ['l', 'o', 'r', 'e', 'm']; -/// let iter = slice.array_chunks::<2>(); -/// ``` -/// -/// [`array_chunks`]: slice::array_chunks -/// [`remainder`]: ArrayChunks::remainder -/// [slices]: slice -#[derive(Debug)] -#[unstable(feature = "array_chunks", issue = "74985")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct ArrayChunks<'a, T: 'a, const N: usize> { - iter: Iter<'a, [T; N]>, - rem: &'a [T], -} - -impl<'a, T, const N: usize> ArrayChunks<'a, T, N> { - #[inline] - pub(super) fn new(slice: &'a [T]) -> Self { - let (array_slice, rem) = slice.as_chunks(); - Self { iter: array_slice.iter(), rem } - } - - /// Returns the remainder of the original slice that is not going to be - /// returned by the iterator. The returned slice has at most `N-1` - /// elements. - #[must_use] - #[unstable(feature = "array_chunks", issue = "74985")] - pub fn remainder(&self) -> &'a [T] { - self.rem - } -} - -// FIXME(#26925) Remove in favor of `#[derive(Clone)]` -#[unstable(feature = "array_chunks", issue = "74985")] -impl Clone for ArrayChunks<'_, T, N> { - fn clone(&self) -> Self { - ArrayChunks { iter: self.iter.clone(), rem: self.rem } - } -} - -#[unstable(feature = "array_chunks", issue = "74985")] -impl<'a, T, const N: usize> Iterator for ArrayChunks<'a, T, N> { - type Item = &'a [T; N]; - - #[inline] - fn next(&mut self) -> Option<&'a [T; N]> { - self.iter.next() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } - - #[inline] - fn count(self) -> usize { - self.iter.count() - } - - #[inline] - fn nth(&mut self, n: usize) -> Option { - self.iter.nth(n) - } - - #[inline] - fn last(self) -> Option { - self.iter.last() - } - - unsafe fn __iterator_get_unchecked(&mut self, i: usize) -> &'a [T; N] { - // SAFETY: The safety guarantees of `__iterator_get_unchecked` are - // transferred to the caller. - unsafe { self.iter.__iterator_get_unchecked(i) } - } -} - -#[unstable(feature = "array_chunks", issue = "74985")] -impl<'a, T, const N: usize> DoubleEndedIterator for ArrayChunks<'a, T, N> { - #[inline] - fn next_back(&mut self) -> Option<&'a [T; N]> { - self.iter.next_back() - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option { - self.iter.nth_back(n) - } -} - -#[unstable(feature = "array_chunks", issue = "74985")] -impl ExactSizeIterator for ArrayChunks<'_, T, N> { - fn is_empty(&self) -> bool { - self.iter.is_empty() - } -} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for ArrayChunks<'_, T, N> {} - -#[unstable(feature = "array_chunks", issue = "74985")] -impl FusedIterator for ArrayChunks<'_, T, N> {} - -#[doc(hidden)] -#[unstable(feature = "array_chunks", issue = "74985")] -unsafe impl<'a, T, const N: usize> TrustedRandomAccess for ArrayChunks<'a, T, N> {} - -#[doc(hidden)] -#[unstable(feature = "array_chunks", issue = "74985")] -unsafe impl<'a, T, const N: usize> TrustedRandomAccessNoCoerce for ArrayChunks<'a, T, N> { - const MAY_HAVE_SIDE_EFFECT: bool = false; -} - -/// An iterator over a slice in (non-overlapping) mutable chunks (`N` elements -/// at a time), starting at the beginning of the slice. -/// -/// When the slice len is not evenly divided by the chunk size, the last -/// up to `N-1` elements will be omitted but can be retrieved from -/// the [`into_remainder`] function from the iterator. -/// -/// This struct is created by the [`array_chunks_mut`] method on [slices]. -/// -/// # Example -/// -/// ``` -/// #![feature(array_chunks)] -/// -/// let mut slice = ['l', 'o', 'r', 'e', 'm']; -/// let iter = slice.array_chunks_mut::<2>(); -/// ``` -/// -/// [`array_chunks_mut`]: slice::array_chunks_mut -/// [`into_remainder`]: ../../std/slice/struct.ArrayChunksMut.html#method.into_remainder -/// [slices]: slice -#[derive(Debug)] -#[unstable(feature = "array_chunks", issue = "74985")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct ArrayChunksMut<'a, T: 'a, const N: usize> { - iter: IterMut<'a, [T; N]>, - rem: &'a mut [T], -} - -impl<'a, T, const N: usize> ArrayChunksMut<'a, T, N> { - #[inline] - pub(super) fn new(slice: &'a mut [T]) -> Self { - let (array_slice, rem) = slice.as_chunks_mut(); - Self { iter: array_slice.iter_mut(), rem } - } - - /// Returns the remainder of the original slice that is not going to be - /// returned by the iterator. The returned slice has at most `N-1` - /// elements. - #[must_use = "`self` will be dropped if the result is not used"] - #[unstable(feature = "array_chunks", issue = "74985")] - pub fn into_remainder(self) -> &'a mut [T] { - self.rem - } -} - -#[unstable(feature = "array_chunks", issue = "74985")] -impl<'a, T, const N: usize> Iterator for ArrayChunksMut<'a, T, N> { - type Item = &'a mut [T; N]; - - #[inline] - fn next(&mut self) -> Option<&'a mut [T; N]> { - self.iter.next() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } - - #[inline] - fn count(self) -> usize { - self.iter.count() - } - - #[inline] - fn nth(&mut self, n: usize) -> Option { - self.iter.nth(n) - } - - #[inline] - fn last(self) -> Option { - self.iter.last() - } - - unsafe fn __iterator_get_unchecked(&mut self, i: usize) -> &'a mut [T; N] { - // SAFETY: The safety guarantees of `__iterator_get_unchecked` are transferred to - // the caller. - unsafe { self.iter.__iterator_get_unchecked(i) } - } -} - -#[unstable(feature = "array_chunks", issue = "74985")] -impl<'a, T, const N: usize> DoubleEndedIterator for ArrayChunksMut<'a, T, N> { - #[inline] - fn next_back(&mut self) -> Option<&'a mut [T; N]> { - self.iter.next_back() - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option { - self.iter.nth_back(n) - } -} - -#[unstable(feature = "array_chunks", issue = "74985")] -impl ExactSizeIterator for ArrayChunksMut<'_, T, N> { - fn is_empty(&self) -> bool { - self.iter.is_empty() - } -} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for ArrayChunksMut<'_, T, N> {} - -#[unstable(feature = "array_chunks", issue = "74985")] -impl FusedIterator for ArrayChunksMut<'_, T, N> {} - -#[doc(hidden)] -#[unstable(feature = "array_chunks", issue = "74985")] -unsafe impl<'a, T, const N: usize> TrustedRandomAccess for ArrayChunksMut<'a, T, N> {} - -#[doc(hidden)] -#[unstable(feature = "array_chunks", issue = "74985")] -unsafe impl<'a, T, const N: usize> TrustedRandomAccessNoCoerce for ArrayChunksMut<'a, T, N> { - const MAY_HAVE_SIDE_EFFECT: bool = false; -} - -/// An iterator over a slice in (non-overlapping) chunks (`chunk_size` elements at a -/// time), starting at the end of the slice. -/// -/// When the slice len is not evenly divided by the chunk size, the last slice -/// of the iteration will be the remainder. -/// -/// This struct is created by the [`rchunks`] method on [slices]. -/// -/// # Example -/// -/// ``` -/// let slice = ['l', 'o', 'r', 'e', 'm']; -/// let iter = slice.rchunks(2); -/// ``` -/// -/// [`rchunks`]: slice::rchunks -/// [slices]: slice -#[derive(Debug)] -#[stable(feature = "rchunks", since = "1.31.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct RChunks<'a, T: 'a> { - v: &'a [T], - chunk_size: usize, -} - -impl<'a, T: 'a> RChunks<'a, T> { - #[inline] - pub(super) fn new(slice: &'a [T], size: usize) -> Self { - Self { v: slice, chunk_size: size } - } -} - -// FIXME(#26925) Remove in favor of `#[derive(Clone)]` -#[stable(feature = "rchunks", since = "1.31.0")] -impl Clone for RChunks<'_, T> { - fn clone(&self) -> Self { - RChunks { v: self.v, chunk_size: self.chunk_size } - } -} - -#[stable(feature = "rchunks", since = "1.31.0")] -impl<'a, T> Iterator for RChunks<'a, T> { - type Item = &'a [T]; - - #[inline] - fn next(&mut self) -> Option<&'a [T]> { - if self.v.is_empty() { - None - } else { - let len = self.v.len(); - let chunksz = cmp::min(len, self.chunk_size); - // SAFETY: split_at_unchecked just requires the argument be less - // than the length. This could only happen if the expression `len - - // chunksz` overflows. This could only happen if `chunksz > len`, - // which is impossible as we initialize it as the `min` of `len` and - // `self.chunk_size`. - let (fst, snd) = unsafe { self.v.split_at_unchecked(len - chunksz) }; - self.v = fst; - Some(snd) - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - if self.v.is_empty() { - (0, Some(0)) - } else { - let n = self.v.len() / self.chunk_size; - let rem = self.v.len() % self.chunk_size; - let n = if rem > 0 { n + 1 } else { n }; - (n, Some(n)) - } - } - - #[inline] - fn count(self) -> usize { - self.len() - } - - #[inline] - fn nth(&mut self, n: usize) -> Option { - let (end, overflow) = n.overflowing_mul(self.chunk_size); - if end >= self.v.len() || overflow { - self.v = &[]; - None - } else { - // Can't underflow because of the check above - let end = self.v.len() - end; - let start = match end.checked_sub(self.chunk_size) { - Some(sum) => sum, - None => 0, - }; - let nth = &self.v[start..end]; - self.v = &self.v[0..start]; - Some(nth) - } - } - - #[inline] - fn last(self) -> Option { - if self.v.is_empty() { - None - } else { - let rem = self.v.len() % self.chunk_size; - let end = if rem == 0 { self.chunk_size } else { rem }; - Some(&self.v[0..end]) - } - } - - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item { - let end = self.v.len() - idx * self.chunk_size; - let start = match end.checked_sub(self.chunk_size) { - None => 0, - Some(start) => start, - }; - // SAFETY: mostly identical to `Chunks::__iterator_get_unchecked`. - unsafe { from_raw_parts(self.v.as_ptr().add(start), end - start) } - } -} - -#[stable(feature = "rchunks", since = "1.31.0")] -impl<'a, T> DoubleEndedIterator for RChunks<'a, T> { - #[inline] - fn next_back(&mut self) -> Option<&'a [T]> { - if self.v.is_empty() { - None - } else { - let remainder = self.v.len() % self.chunk_size; - let chunksz = if remainder != 0 { remainder } else { self.chunk_size }; - // SAFETY: similar to Chunks::next_back - let (fst, snd) = unsafe { self.v.split_at_unchecked(chunksz) }; - self.v = snd; - Some(fst) - } - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option { - let len = self.len(); - if n >= len { - self.v = &[]; - None - } else { - // can't underflow because `n < len` - let offset_from_end = (len - 1 - n) * self.chunk_size; - let end = self.v.len() - offset_from_end; - let start = end.saturating_sub(self.chunk_size); - let nth_back = &self.v[start..end]; - self.v = &self.v[end..]; - Some(nth_back) - } - } -} - -#[stable(feature = "rchunks", since = "1.31.0")] -impl ExactSizeIterator for RChunks<'_, T> {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for RChunks<'_, T> {} - -#[stable(feature = "rchunks", since = "1.31.0")] -impl FusedIterator for RChunks<'_, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl<'a, T> TrustedRandomAccess for RChunks<'a, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl<'a, T> TrustedRandomAccessNoCoerce for RChunks<'a, T> { - const MAY_HAVE_SIDE_EFFECT: bool = false; -} - -/// An iterator over a slice in (non-overlapping) mutable chunks (`chunk_size` -/// elements at a time), starting at the end of the slice. -/// -/// When the slice len is not evenly divided by the chunk size, the last slice -/// of the iteration will be the remainder. -/// -/// This struct is created by the [`rchunks_mut`] method on [slices]. -/// -/// # Example -/// -/// ``` -/// let mut slice = ['l', 'o', 'r', 'e', 'm']; -/// let iter = slice.rchunks_mut(2); -/// ``` -/// -/// [`rchunks_mut`]: slice::rchunks_mut -/// [slices]: slice -#[derive(Debug)] -#[stable(feature = "rchunks", since = "1.31.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct RChunksMut<'a, T: 'a> { - /// # Safety - /// This slice pointer must point at a valid region of `T` with at least length `v.len()`. Normally, - /// those requirements would mean that we could instead use a `&mut [T]` here, but we cannot - /// because `__iterator_get_unchecked` needs to return `&mut [T]`, which guarantees certain aliasing - /// properties that we cannot uphold if we hold on to the full original `&mut [T]`. Wrapping a raw - /// slice instead lets us hand out non-overlapping `&mut [T]` subslices of the slice we wrap. - v: *mut [T], - chunk_size: usize, - _marker: PhantomData<&'a mut T>, -} - -impl<'a, T: 'a> RChunksMut<'a, T> { - #[inline] - pub(super) fn new(slice: &'a mut [T], size: usize) -> Self { - Self { v: slice, chunk_size: size, _marker: PhantomData } - } -} - -#[stable(feature = "rchunks", since = "1.31.0")] -impl<'a, T> Iterator for RChunksMut<'a, T> { - type Item = &'a mut [T]; - - #[inline] - fn next(&mut self) -> Option<&'a mut [T]> { - if self.v.is_empty() { - None - } else { - let sz = cmp::min(self.v.len(), self.chunk_size); - let len = self.v.len(); - // SAFETY: split_at_mut_unchecked just requires the argument be less - // than the length. This could only happen if the expression - // `len - sz` overflows. This could only happen if `sz > - // len`, which is impossible as we initialize it as the `min` of - // `self.v.len()` (e.g. `len`) and `self.chunk_size`. - let (head, tail) = unsafe { self.v.split_at_mut_unchecked(len - sz) }; - self.v = head; - // SAFETY: Nothing else points to or will point to the contents of this slice. - Some(unsafe { &mut *tail }) - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - if self.v.is_empty() { - (0, Some(0)) - } else { - let n = self.v.len() / self.chunk_size; - let rem = self.v.len() % self.chunk_size; - let n = if rem > 0 { n + 1 } else { n }; - (n, Some(n)) - } - } - - #[inline] - fn count(self) -> usize { - self.len() - } - - #[inline] - fn nth(&mut self, n: usize) -> Option<&'a mut [T]> { - let (end, overflow) = n.overflowing_mul(self.chunk_size); - if end >= self.v.len() || overflow { - self.v = &mut []; - None - } else { - // Can't underflow because of the check above - let end = self.v.len() - end; - let start = match end.checked_sub(self.chunk_size) { - Some(sum) => sum, - None => 0, - }; - // SAFETY: This type ensures that self.v is a valid pointer with a correct len. - // Therefore the bounds check in split_at_mut guarantees the split point is inbounds. - let (head, tail) = unsafe { self.v.split_at_mut(start) }; - // SAFETY: This type ensures that self.v is a valid pointer with a correct len. - // Therefore the bounds check in split_at_mut guarantees the split point is inbounds. - let (nth, _) = unsafe { tail.split_at_mut(end - start) }; - self.v = head; - // SAFETY: Nothing else points to or will point to the contents of this slice. - Some(unsafe { &mut *nth }) - } - } - - #[inline] - fn last(self) -> Option { - if self.v.is_empty() { - None - } else { - let rem = self.v.len() % self.chunk_size; - let end = if rem == 0 { self.chunk_size } else { rem }; - // SAFETY: Nothing else points to or will point to the contents of this slice. - Some(unsafe { &mut *self.v.get_unchecked_mut(0..end) }) - } - } - - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item { - let end = self.v.len() - idx * self.chunk_size; - let start = match end.checked_sub(self.chunk_size) { - None => 0, - Some(start) => start, - }; - // SAFETY: see comments for `RChunks::__iterator_get_unchecked` and - // `ChunksMut::__iterator_get_unchecked`, `self.v`. - unsafe { from_raw_parts_mut(self.v.as_mut_ptr().add(start), end - start) } - } -} - -#[stable(feature = "rchunks", since = "1.31.0")] -impl<'a, T> DoubleEndedIterator for RChunksMut<'a, T> { - #[inline] - fn next_back(&mut self) -> Option<&'a mut [T]> { - if self.v.is_empty() { - None - } else { - let remainder = self.v.len() % self.chunk_size; - let sz = if remainder != 0 { remainder } else { self.chunk_size }; - // SAFETY: Similar to `Chunks::next_back` - let (head, tail) = unsafe { self.v.split_at_mut_unchecked(sz) }; - self.v = tail; - // SAFETY: Nothing else points to or will point to the contents of this slice. - Some(unsafe { &mut *head }) - } - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option { - let len = self.len(); - if n >= len { - self.v = &mut []; - None - } else { - // can't underflow because `n < len` - let offset_from_end = (len - 1 - n) * self.chunk_size; - let end = self.v.len() - offset_from_end; - let start = end.saturating_sub(self.chunk_size); - // SAFETY: The self.v contract ensures that any split_at_mut is valid. - let (tmp, tail) = unsafe { self.v.split_at_mut(end) }; - // SAFETY: The self.v contract ensures that any split_at_mut is valid. - let (_, nth_back) = unsafe { tmp.split_at_mut(start) }; - self.v = tail; - // SAFETY: Nothing else points to or will point to the contents of this slice. - Some(unsafe { &mut *nth_back }) - } - } -} - -#[stable(feature = "rchunks", since = "1.31.0")] -impl ExactSizeIterator for RChunksMut<'_, T> {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for RChunksMut<'_, T> {} - -#[stable(feature = "rchunks", since = "1.31.0")] -impl FusedIterator for RChunksMut<'_, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl<'a, T> TrustedRandomAccess for RChunksMut<'a, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl<'a, T> TrustedRandomAccessNoCoerce for RChunksMut<'a, T> { - const MAY_HAVE_SIDE_EFFECT: bool = false; -} - -#[stable(feature = "rchunks", since = "1.31.0")] -unsafe impl Send for RChunksMut<'_, T> where T: Send {} - -#[stable(feature = "rchunks", since = "1.31.0")] -unsafe impl Sync for RChunksMut<'_, T> where T: Sync {} - -/// An iterator over a slice in (non-overlapping) chunks (`chunk_size` elements at a -/// time), starting at the end of the slice. -/// -/// When the slice len is not evenly divided by the chunk size, the last -/// up to `chunk_size-1` elements will be omitted but can be retrieved from -/// the [`remainder`] function from the iterator. -/// -/// This struct is created by the [`rchunks_exact`] method on [slices]. -/// -/// # Example -/// -/// ``` -/// let slice = ['l', 'o', 'r', 'e', 'm']; -/// let iter = slice.rchunks_exact(2); -/// ``` -/// -/// [`rchunks_exact`]: slice::rchunks_exact -/// [`remainder`]: RChunksExact::remainder -/// [slices]: slice -#[derive(Debug)] -#[stable(feature = "rchunks", since = "1.31.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct RChunksExact<'a, T: 'a> { - v: &'a [T], - rem: &'a [T], - chunk_size: usize, -} - -impl<'a, T> RChunksExact<'a, T> { - #[inline] - pub(super) fn new(slice: &'a [T], chunk_size: usize) -> Self { - let rem = slice.len() % chunk_size; - // SAFETY: 0 <= rem <= slice.len() by construction above - let (fst, snd) = unsafe { slice.split_at_unchecked(rem) }; - Self { v: snd, rem: fst, chunk_size } - } - - /// Returns the remainder of the original slice that is not going to be - /// returned by the iterator. The returned slice has at most `chunk_size-1` - /// elements. - /// - /// # Example - /// - /// ``` - /// let slice = ['l', 'o', 'r', 'e', 'm']; - /// let mut iter = slice.rchunks_exact(2); - /// assert_eq!(iter.remainder(), &['l'][..]); - /// assert_eq!(iter.next(), Some(&['e', 'm'][..])); - /// assert_eq!(iter.remainder(), &['l'][..]); - /// assert_eq!(iter.next(), Some(&['o', 'r'][..])); - /// assert_eq!(iter.remainder(), &['l'][..]); - /// assert_eq!(iter.next(), None); - /// assert_eq!(iter.remainder(), &['l'][..]); - /// ``` - #[must_use] - #[stable(feature = "rchunks", since = "1.31.0")] - pub fn remainder(&self) -> &'a [T] { - self.rem - } -} - -// FIXME(#26925) Remove in favor of `#[derive(Clone)]` -#[stable(feature = "rchunks", since = "1.31.0")] -impl<'a, T> Clone for RChunksExact<'a, T> { - fn clone(&self) -> RChunksExact<'a, T> { - RChunksExact { v: self.v, rem: self.rem, chunk_size: self.chunk_size } - } -} - -#[stable(feature = "rchunks", since = "1.31.0")] -impl<'a, T> Iterator for RChunksExact<'a, T> { - type Item = &'a [T]; - - #[inline] - fn next(&mut self) -> Option<&'a [T]> { - if self.v.len() < self.chunk_size { - None - } else { - let (fst, snd) = self.v.split_at(self.v.len() - self.chunk_size); - self.v = fst; - Some(snd) - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let n = self.v.len() / self.chunk_size; - (n, Some(n)) - } - - #[inline] - fn count(self) -> usize { - self.len() - } - - #[inline] - fn nth(&mut self, n: usize) -> Option { - let (end, overflow) = n.overflowing_mul(self.chunk_size); - if end >= self.v.len() || overflow { - self.v = &[]; - None - } else { - let (fst, _) = self.v.split_at(self.v.len() - end); - self.v = fst; - self.next() - } - } - - #[inline] - fn last(mut self) -> Option { - self.next_back() - } - - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item { - let end = self.v.len() - idx * self.chunk_size; - let start = end - self.chunk_size; - // SAFETY: mostly identical to `Chunks::__iterator_get_unchecked`. - unsafe { from_raw_parts(self.v.as_ptr().add(start), self.chunk_size) } - } -} - -#[stable(feature = "rchunks", since = "1.31.0")] -impl<'a, T> DoubleEndedIterator for RChunksExact<'a, T> { - #[inline] - fn next_back(&mut self) -> Option<&'a [T]> { - if self.v.len() < self.chunk_size { - None - } else { - let (fst, snd) = self.v.split_at(self.chunk_size); - self.v = snd; - Some(fst) - } - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option { - let len = self.len(); - if n >= len { - self.v = &[]; - None - } else { - // now that we know that `n` corresponds to a chunk, - // none of these operations can underflow/overflow - let offset = (len - n) * self.chunk_size; - let start = self.v.len() - offset; - let end = start + self.chunk_size; - let nth_back = &self.v[start..end]; - self.v = &self.v[end..]; - Some(nth_back) - } - } -} - -#[stable(feature = "rchunks", since = "1.31.0")] -impl<'a, T> ExactSizeIterator for RChunksExact<'a, T> { - fn is_empty(&self) -> bool { - self.v.is_empty() - } -} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for RChunksExact<'_, T> {} - -#[stable(feature = "rchunks", since = "1.31.0")] -impl FusedIterator for RChunksExact<'_, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl<'a, T> TrustedRandomAccess for RChunksExact<'a, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl<'a, T> TrustedRandomAccessNoCoerce for RChunksExact<'a, T> { - const MAY_HAVE_SIDE_EFFECT: bool = false; -} - -/// An iterator over a slice in (non-overlapping) mutable chunks (`chunk_size` -/// elements at a time), starting at the end of the slice. -/// -/// When the slice len is not evenly divided by the chunk size, the last up to -/// `chunk_size-1` elements will be omitted but can be retrieved from the -/// [`into_remainder`] function from the iterator. -/// -/// This struct is created by the [`rchunks_exact_mut`] method on [slices]. -/// -/// # Example -/// -/// ``` -/// let mut slice = ['l', 'o', 'r', 'e', 'm']; -/// let iter = slice.rchunks_exact_mut(2); -/// ``` -/// -/// [`rchunks_exact_mut`]: slice::rchunks_exact_mut -/// [`into_remainder`]: RChunksExactMut::into_remainder -/// [slices]: slice -#[derive(Debug)] -#[stable(feature = "rchunks", since = "1.31.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct RChunksExactMut<'a, T: 'a> { - /// # Safety - /// This slice pointer must point at a valid region of `T` with at least length `v.len()`. Normally, - /// those requirements would mean that we could instead use a `&mut [T]` here, but we cannot - /// because `__iterator_get_unchecked` needs to return `&mut [T]`, which guarantees certain aliasing - /// properties that we cannot uphold if we hold on to the full original `&mut [T]`. Wrapping a raw - /// slice instead lets us hand out non-overlapping `&mut [T]` subslices of the slice we wrap. - v: *mut [T], - rem: &'a mut [T], - chunk_size: usize, -} - -impl<'a, T> RChunksExactMut<'a, T> { - #[inline] - pub(super) fn new(slice: &'a mut [T], chunk_size: usize) -> Self { - let rem = slice.len() % chunk_size; - // SAFETY: 0 <= rem <= slice.len() by construction above - let (fst, snd) = unsafe { slice.split_at_mut_unchecked(rem) }; - Self { v: snd, rem: fst, chunk_size } - } - - /// Returns the remainder of the original slice that is not going to be - /// returned by the iterator. The returned slice has at most `chunk_size-1` - /// elements. - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "rchunks", since = "1.31.0")] - pub fn into_remainder(self) -> &'a mut [T] { - self.rem - } -} - -#[stable(feature = "rchunks", since = "1.31.0")] -impl<'a, T> Iterator for RChunksExactMut<'a, T> { - type Item = &'a mut [T]; - - #[inline] - fn next(&mut self) -> Option<&'a mut [T]> { - if self.v.len() < self.chunk_size { - None - } else { - let len = self.v.len(); - // SAFETY: The self.v contract ensures that any split_at_mut is valid. - let (head, tail) = unsafe { self.v.split_at_mut(len - self.chunk_size) }; - self.v = head; - // SAFETY: Nothing else points to or will point to the contents of this slice. - Some(unsafe { &mut *tail }) - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let n = self.v.len() / self.chunk_size; - (n, Some(n)) - } - - #[inline] - fn count(self) -> usize { - self.len() - } - - #[inline] - fn nth(&mut self, n: usize) -> Option<&'a mut [T]> { - let (end, overflow) = n.overflowing_mul(self.chunk_size); - if end >= self.v.len() || overflow { - self.v = &mut []; - None - } else { - let len = self.v.len(); - // SAFETY: The self.v contract ensures that any split_at_mut is valid. - let (fst, _) = unsafe { self.v.split_at_mut(len - end) }; - self.v = fst; - self.next() - } - } - - #[inline] - fn last(mut self) -> Option { - self.next_back() - } - - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item { - let end = self.v.len() - idx * self.chunk_size; - let start = end - self.chunk_size; - // SAFETY: see comments for `RChunksMut::__iterator_get_unchecked` and `self.v`. - unsafe { from_raw_parts_mut(self.v.as_mut_ptr().add(start), self.chunk_size) } - } -} - -#[stable(feature = "rchunks", since = "1.31.0")] -impl<'a, T> DoubleEndedIterator for RChunksExactMut<'a, T> { - #[inline] - fn next_back(&mut self) -> Option<&'a mut [T]> { - if self.v.len() < self.chunk_size { - None - } else { - // SAFETY: The self.v contract ensures that any split_at_mut is valid. - let (head, tail) = unsafe { self.v.split_at_mut(self.chunk_size) }; - self.v = tail; - // SAFETY: Nothing else points to or will point to the contents of this slice. - Some(unsafe { &mut *head }) - } - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option { - let len = self.len(); - if n >= len { - self.v = &mut []; - None - } else { - // now that we know that `n` corresponds to a chunk, - // none of these operations can underflow/overflow - let offset = (len - n) * self.chunk_size; - let start = self.v.len() - offset; - let end = start + self.chunk_size; - // SAFETY: The self.v contract ensures that any split_at_mut is valid. - let (tmp, tail) = unsafe { self.v.split_at_mut(end) }; - // SAFETY: The self.v contract ensures that any split_at_mut is valid. - let (_, nth_back) = unsafe { tmp.split_at_mut(start) }; - self.v = tail; - // SAFETY: Nothing else points to or will point to the contents of this slice. - Some(unsafe { &mut *nth_back }) - } - } -} - -#[stable(feature = "rchunks", since = "1.31.0")] -impl ExactSizeIterator for RChunksExactMut<'_, T> { - fn is_empty(&self) -> bool { - self.v.is_empty() - } -} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for RChunksExactMut<'_, T> {} - -#[stable(feature = "rchunks", since = "1.31.0")] -impl FusedIterator for RChunksExactMut<'_, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl<'a, T> TrustedRandomAccess for RChunksExactMut<'a, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl<'a, T> TrustedRandomAccessNoCoerce for RChunksExactMut<'a, T> { - const MAY_HAVE_SIDE_EFFECT: bool = false; -} - -#[stable(feature = "rchunks", since = "1.31.0")] -unsafe impl Send for RChunksExactMut<'_, T> where T: Send {} - -#[stable(feature = "rchunks", since = "1.31.0")] -unsafe impl Sync for RChunksExactMut<'_, T> where T: Sync {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl<'a, T> TrustedRandomAccess for Iter<'a, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl<'a, T> TrustedRandomAccessNoCoerce for Iter<'a, T> { - const MAY_HAVE_SIDE_EFFECT: bool = false; -} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl<'a, T> TrustedRandomAccess for IterMut<'a, T> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl<'a, T> TrustedRandomAccessNoCoerce for IterMut<'a, T> { - const MAY_HAVE_SIDE_EFFECT: bool = false; -} - -/// An iterator over slice in (non-overlapping) chunks separated by a predicate. -/// -/// This struct is created by the [`chunk_by`] method on [slices]. -/// -/// [`chunk_by`]: slice::chunk_by -/// [slices]: slice -#[stable(feature = "slice_group_by", since = "1.77.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct ChunkBy<'a, T: 'a, P> { - slice: &'a [T], - predicate: P, -} - -#[stable(feature = "slice_group_by", since = "1.77.0")] -impl<'a, T: 'a, P> ChunkBy<'a, T, P> { - pub(super) fn new(slice: &'a [T], predicate: P) -> Self { - ChunkBy { slice, predicate } - } -} - -#[stable(feature = "slice_group_by", since = "1.77.0")] -impl<'a, T: 'a, P> Iterator for ChunkBy<'a, T, P> -where - P: FnMut(&T, &T) -> bool, -{ - type Item = &'a [T]; - - #[inline] - fn next(&mut self) -> Option { - if self.slice.is_empty() { - None - } else { - let mut len = 1; - let mut iter = self.slice.windows(2); - while let Some([l, r]) = iter.next() { - if (self.predicate)(l, r) { len += 1 } else { break } - } - let (head, tail) = self.slice.split_at(len); - self.slice = tail; - Some(head) - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - if self.slice.is_empty() { (0, Some(0)) } else { (1, Some(self.slice.len())) } - } - - #[inline] - fn last(mut self) -> Option { - self.next_back() - } -} - -#[stable(feature = "slice_group_by", since = "1.77.0")] -impl<'a, T: 'a, P> DoubleEndedIterator for ChunkBy<'a, T, P> -where - P: FnMut(&T, &T) -> bool, -{ - #[inline] - fn next_back(&mut self) -> Option { - if self.slice.is_empty() { - None - } else { - let mut len = 1; - let mut iter = self.slice.windows(2); - while let Some([l, r]) = iter.next_back() { - if (self.predicate)(l, r) { len += 1 } else { break } - } - let (head, tail) = self.slice.split_at(self.slice.len() - len); - self.slice = head; - Some(tail) - } - } -} - -#[stable(feature = "slice_group_by", since = "1.77.0")] -impl<'a, T: 'a, P> FusedIterator for ChunkBy<'a, T, P> where P: FnMut(&T, &T) -> bool {} - -#[stable(feature = "slice_group_by", since = "1.77.0")] -impl<'a, T: 'a + fmt::Debug, P> fmt::Debug for ChunkBy<'a, T, P> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("ChunkBy").field("slice", &self.slice).finish() - } -} - -/// An iterator over slice in (non-overlapping) mutable chunks separated -/// by a predicate. -/// -/// This struct is created by the [`chunk_by_mut`] method on [slices]. -/// -/// [`chunk_by_mut`]: slice::chunk_by_mut -/// [slices]: slice -#[stable(feature = "slice_group_by", since = "1.77.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct ChunkByMut<'a, T: 'a, P> { - slice: &'a mut [T], - predicate: P, -} - -#[stable(feature = "slice_group_by", since = "1.77.0")] -impl<'a, T: 'a, P> ChunkByMut<'a, T, P> { - pub(super) fn new(slice: &'a mut [T], predicate: P) -> Self { - ChunkByMut { slice, predicate } - } -} - -#[stable(feature = "slice_group_by", since = "1.77.0")] -impl<'a, T: 'a, P> Iterator for ChunkByMut<'a, T, P> -where - P: FnMut(&T, &T) -> bool, -{ - type Item = &'a mut [T]; - - #[inline] - fn next(&mut self) -> Option { - if self.slice.is_empty() { - None - } else { - let mut len = 1; - let mut iter = self.slice.windows(2); - while let Some([l, r]) = iter.next() { - if (self.predicate)(l, r) { len += 1 } else { break } - } - let slice = mem::take(&mut self.slice); - let (head, tail) = slice.split_at_mut(len); - self.slice = tail; - Some(head) - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - if self.slice.is_empty() { (0, Some(0)) } else { (1, Some(self.slice.len())) } - } - - #[inline] - fn last(mut self) -> Option { - self.next_back() - } -} - -#[stable(feature = "slice_group_by", since = "1.77.0")] -impl<'a, T: 'a, P> DoubleEndedIterator for ChunkByMut<'a, T, P> -where - P: FnMut(&T, &T) -> bool, -{ - #[inline] - fn next_back(&mut self) -> Option { - if self.slice.is_empty() { - None - } else { - let mut len = 1; - let mut iter = self.slice.windows(2); - while let Some([l, r]) = iter.next_back() { - if (self.predicate)(l, r) { len += 1 } else { break } - } - let slice = mem::take(&mut self.slice); - let (head, tail) = slice.split_at_mut(slice.len() - len); - self.slice = head; - Some(tail) - } - } -} - -#[stable(feature = "slice_group_by", since = "1.77.0")] -impl<'a, T: 'a, P> FusedIterator for ChunkByMut<'a, T, P> where P: FnMut(&T, &T) -> bool {} - -#[stable(feature = "slice_group_by", since = "1.77.0")] -impl<'a, T: 'a + fmt::Debug, P> fmt::Debug for ChunkByMut<'a, T, P> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("ChunkByMut").field("slice", &self.slice).finish() - } -} diff --git a/library/core/src/slice/iter/macros.rs b/library/core/src/slice/iter/macros.rs deleted file mode 100644 index 0b8ff5cc01242..0000000000000 --- a/library/core/src/slice/iter/macros.rs +++ /dev/null @@ -1,485 +0,0 @@ -//! Macros used by iterators of slice. - -/// Convenience & performance macro for consuming the `end_or_len` field, by -/// giving a `(&mut) usize` or `(&mut) NonNull` depending whether `T` is -/// or is not a ZST respectively. -/// -/// Internally, this reads the `end` through a pointer-to-`NonNull` so that -/// it'll get the appropriate non-null metadata in the backend without needing -/// to call `assume` manually. -macro_rules! if_zst { - (mut $this:ident, $len:ident => $zst_body:expr, $end:ident => $other_body:expr,) => {{ - #![allow(unused_unsafe)] // we're sometimes used within an unsafe block - - if T::IS_ZST { - // SAFETY: for ZSTs, the pointer is storing a provenance-free length, - // so consuming and updating it as a `usize` is fine. - let $len = unsafe { &mut *ptr::addr_of_mut!($this.end_or_len).cast::() }; - $zst_body - } else { - // SAFETY: for non-ZSTs, the type invariant ensures it cannot be null - let $end = unsafe { &mut *ptr::addr_of_mut!($this.end_or_len).cast::>() }; - $other_body - } - }}; - ($this:ident, $len:ident => $zst_body:expr, $end:ident => $other_body:expr,) => {{ - #![allow(unused_unsafe)] // we're sometimes used within an unsafe block - - if T::IS_ZST { - let $len = $this.end_or_len.addr(); - $zst_body - } else { - // SAFETY: for non-ZSTs, the type invariant ensures it cannot be null - let $end = unsafe { *ptr::addr_of!($this.end_or_len).cast::>() }; - $other_body - } - }}; -} - -// Inlining is_empty and len makes a huge performance difference -macro_rules! is_empty { - ($self: ident) => { - if_zst!($self, - len => len == 0, - end => $self.ptr == end, - ) - }; -} - -macro_rules! len { - ($self: ident) => {{ - if_zst!($self, - len => len, - end => { - // To get rid of some bounds checks (see `position`), we use ptr_sub instead of - // offset_from (Tested by `codegen/slice-position-bounds-check`.) - // SAFETY: by the type invariant pointers are aligned and `start <= end` - unsafe { end.sub_ptr($self.ptr) } - }, - ) - }}; -} - -// The shared definition of the `Iter` and `IterMut` iterators -macro_rules! iterator { - ( - struct $name:ident -> $ptr:ty, - $elem:ty, - $raw_mut:tt, - {$( $mut_:tt )?}, - $into_ref:ident, - {$($extra:tt)*} - ) => { - impl<'a, T> $name<'a, T> { - /// Returns the last element and moves the end of the iterator backwards by 1. - /// - /// # Safety - /// - /// The iterator must not be empty - #[inline] - unsafe fn next_back_unchecked(&mut self) -> $elem { - // SAFETY: the caller promised it's not empty, so - // the offsetting is in-bounds and there's an element to return. - unsafe { self.pre_dec_end(1).$into_ref() } - } - - // Helper function for creating a slice from the iterator. - #[inline(always)] - fn make_slice(&self) -> &'a [T] { - // SAFETY: the iterator was created from a slice with pointer - // `self.ptr` and length `len!(self)`. This guarantees that all - // the prerequisites for `from_raw_parts` are fulfilled. - unsafe { from_raw_parts(self.ptr.as_ptr(), len!(self)) } - } - - // Helper function for moving the start of the iterator forwards by `offset` elements, - // returning the old start. - // Unsafe because the offset must not exceed `self.len()`. - #[inline(always)] - unsafe fn post_inc_start(&mut self, offset: usize) -> NonNull { - let old = self.ptr; - - // SAFETY: the caller guarantees that `offset` doesn't exceed `self.len()`, - // so this new pointer is inside `self` and thus guaranteed to be non-null. - unsafe { - if_zst!(mut self, - len => *len = len.unchecked_sub(offset), - _end => self.ptr = self.ptr.add(offset), - ); - } - old - } - - // Helper function for moving the end of the iterator backwards by `offset` elements, - // returning the new end. - // Unsafe because the offset must not exceed `self.len()`. - #[inline(always)] - unsafe fn pre_dec_end(&mut self, offset: usize) -> NonNull { - if_zst!(mut self, - // SAFETY: By our precondition, `offset` can be at most the - // current length, so the subtraction can never overflow. - len => unsafe { - *len = len.unchecked_sub(offset); - self.ptr - }, - // SAFETY: the caller guarantees that `offset` doesn't exceed `self.len()`, - // which is guaranteed to not overflow an `isize`. Also, the resulting pointer - // is in bounds of `slice`, which fulfills the other requirements for `offset`. - end => unsafe { - *end = end.sub(offset); - *end - }, - ) - } - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl ExactSizeIterator for $name<'_, T> { - #[inline(always)] - fn len(&self) -> usize { - len!(self) - } - - #[inline(always)] - fn is_empty(&self) -> bool { - is_empty!(self) - } - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl<'a, T> Iterator for $name<'a, T> { - type Item = $elem; - - #[inline] - fn next(&mut self) -> Option<$elem> { - // could be implemented with slices, but this avoids bounds checks - - // SAFETY: The call to `next_unchecked` is - // safe since we check if the iterator is empty first. - unsafe { - if is_empty!(self) { - None - } else { - Some(self.next_unchecked()) - } - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let exact = len!(self); - (exact, Some(exact)) - } - - #[inline] - fn count(self) -> usize { - len!(self) - } - - #[inline] - fn nth(&mut self, n: usize) -> Option<$elem> { - if n >= len!(self) { - // This iterator is now empty. - if_zst!(mut self, - len => *len = 0, - end => self.ptr = *end, - ); - return None; - } - // SAFETY: We are in bounds. `post_inc_start` does the right thing even for ZSTs. - unsafe { - self.post_inc_start(n); - Some(self.next_unchecked()) - } - } - - #[inline] - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - let advance = cmp::min(len!(self), n); - // SAFETY: By construction, `advance` does not exceed `self.len()`. - unsafe { self.post_inc_start(advance) }; - NonZero::new(n - advance).map_or(Ok(()), Err) - } - - #[inline] - fn last(mut self) -> Option<$elem> { - self.next_back() - } - - #[inline] - fn fold(self, init: B, mut f: F) -> B - where - F: FnMut(B, Self::Item) -> B, - { - // this implementation consists of the following optimizations compared to the - // default implementation: - // - do-while loop, as is llvm's preferred loop shape, - // see https://releases.llvm.org/16.0.0/docs/LoopTerminology.html#more-canonical-loops - // - bumps an index instead of a pointer since the latter case inhibits - // some optimizations, see #111603 - // - avoids Option wrapping/matching - if is_empty!(self) { - return init; - } - let mut acc = init; - let mut i = 0; - let len = len!(self); - loop { - // SAFETY: the loop iterates `i in 0..len`, which always is in bounds of - // the slice allocation - acc = f(acc, unsafe { & $( $mut_ )? *self.ptr.add(i).as_ptr() }); - // SAFETY: `i` can't overflow since it'll only reach usize::MAX if the - // slice had that length, in which case we'll break out of the loop - // after the increment - i = unsafe { i.unchecked_add(1) }; - if i == len { - break; - } - } - acc - } - - // We override the default implementation, which uses `try_fold`, - // because this simple implementation generates less LLVM IR and is - // faster to compile. - #[inline] - fn for_each(mut self, mut f: F) - where - Self: Sized, - F: FnMut(Self::Item), - { - while let Some(x) = self.next() { - f(x); - } - } - - // We override the default implementation, which uses `try_fold`, - // because this simple implementation generates less LLVM IR and is - // faster to compile. - #[inline] - fn all(&mut self, mut f: F) -> bool - where - Self: Sized, - F: FnMut(Self::Item) -> bool, - { - while let Some(x) = self.next() { - if !f(x) { - return false; - } - } - true - } - - // We override the default implementation, which uses `try_fold`, - // because this simple implementation generates less LLVM IR and is - // faster to compile. - #[inline] - fn any(&mut self, mut f: F) -> bool - where - Self: Sized, - F: FnMut(Self::Item) -> bool, - { - while let Some(x) = self.next() { - if f(x) { - return true; - } - } - false - } - - // We override the default implementation, which uses `try_fold`, - // because this simple implementation generates less LLVM IR and is - // faster to compile. - #[inline] - fn find

(&mut self, mut predicate: P) -> Option - where - Self: Sized, - P: FnMut(&Self::Item) -> bool, - { - while let Some(x) = self.next() { - if predicate(&x) { - return Some(x); - } - } - None - } - - // We override the default implementation, which uses `try_fold`, - // because this simple implementation generates less LLVM IR and is - // faster to compile. - #[inline] - fn find_map(&mut self, mut f: F) -> Option - where - Self: Sized, - F: FnMut(Self::Item) -> Option, - { - while let Some(x) = self.next() { - if let Some(y) = f(x) { - return Some(y); - } - } - None - } - - // We override the default implementation, which uses `try_fold`, - // because this simple implementation generates less LLVM IR and is - // faster to compile. Also, the `assume` avoids a bounds check. - #[inline] - #[rustc_inherit_overflow_checks] - fn position

(&mut self, mut predicate: P) -> Option where - Self: Sized, - P: FnMut(Self::Item) -> bool, - { - let n = len!(self); - let mut i = 0; - while let Some(x) = self.next() { - if predicate(x) { - // SAFETY: we are guaranteed to be in bounds by the loop invariant: - // when `i >= n`, `self.next()` returns `None` and the loop breaks. - unsafe { assert_unchecked(i < n) }; - return Some(i); - } - i += 1; - } - None - } - - // We override the default implementation, which uses `try_fold`, - // because this simple implementation generates less LLVM IR and is - // faster to compile. Also, the `assume` avoids a bounds check. - #[inline] - fn rposition

(&mut self, mut predicate: P) -> Option where - P: FnMut(Self::Item) -> bool, - Self: Sized + ExactSizeIterator + DoubleEndedIterator - { - let n = len!(self); - let mut i = n; - while let Some(x) = self.next_back() { - i -= 1; - if predicate(x) { - // SAFETY: `i` must be lower than `n` since it starts at `n` - // and is only decreasing. - unsafe { assert_unchecked(i < n) }; - return Some(i); - } - } - None - } - - #[inline] - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item { - // SAFETY: the caller must guarantee that `i` is in bounds of - // the underlying slice, so `i` cannot overflow an `isize`, and - // the returned references is guaranteed to refer to an element - // of the slice and thus guaranteed to be valid. - // - // Also note that the caller also guarantees that we're never - // called with the same index again, and that no other methods - // that will access this subslice are called, so it is valid - // for the returned reference to be mutable in the case of - // `IterMut` - unsafe { & $( $mut_ )? * self.ptr.as_ptr().add(idx) } - } - - $($extra)* - } - - #[stable(feature = "rust1", since = "1.0.0")] - impl<'a, T> DoubleEndedIterator for $name<'a, T> { - #[inline] - fn next_back(&mut self) -> Option<$elem> { - // could be implemented with slices, but this avoids bounds checks - - // SAFETY: The call to `next_back_unchecked` - // is safe since we check if the iterator is empty first. - unsafe { - if is_empty!(self) { - None - } else { - Some(self.next_back_unchecked()) - } - } - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option<$elem> { - if n >= len!(self) { - // This iterator is now empty. - if_zst!(mut self, - len => *len = 0, - end => *end = self.ptr, - ); - return None; - } - // SAFETY: We are in bounds. `pre_dec_end` does the right thing even for ZSTs. - unsafe { - self.pre_dec_end(n); - Some(self.next_back_unchecked()) - } - } - - #[inline] - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - let advance = cmp::min(len!(self), n); - // SAFETY: By construction, `advance` does not exceed `self.len()`. - unsafe { self.pre_dec_end(advance) }; - NonZero::new(n - advance).map_or(Ok(()), Err) - } - } - - #[stable(feature = "fused", since = "1.26.0")] - impl FusedIterator for $name<'_, T> {} - - #[unstable(feature = "trusted_len", issue = "37572")] - unsafe impl TrustedLen for $name<'_, T> {} - - impl<'a, T> UncheckedIterator for $name<'a, T> { - #[inline] - unsafe fn next_unchecked(&mut self) -> $elem { - // SAFETY: The caller promised there's at least one more item. - unsafe { - self.post_inc_start(1).$into_ref() - } - } - } - - #[stable(feature = "default_iters", since = "1.70.0")] - impl Default for $name<'_, T> { - /// Creates an empty slice iterator. - /// - /// ``` - #[doc = concat!("# use core::slice::", stringify!($name), ";")] - #[doc = concat!("let iter: ", stringify!($name<'_, u8>), " = Default::default();")] - /// assert_eq!(iter.len(), 0); - /// ``` - fn default() -> Self { - (& $( $mut_ )? []).into_iter() - } - } - } -} - -macro_rules! forward_iterator { - ($name:ident: $elem:ident, $iter_of:ty) => { - #[stable(feature = "rust1", since = "1.0.0")] - impl<'a, $elem, P> Iterator for $name<'a, $elem, P> - where - P: FnMut(&T) -> bool, - { - type Item = $iter_of; - - #[inline] - fn next(&mut self) -> Option<$iter_of> { - self.inner.next() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } - } - - #[stable(feature = "fused", since = "1.26.0")] - impl<'a, $elem, P> FusedIterator for $name<'a, $elem, P> where P: FnMut(&T) -> bool {} - }; -} diff --git a/library/core/src/slice/memchr.rs b/library/core/src/slice/memchr.rs deleted file mode 100644 index da7ceb2dd0a0d..0000000000000 --- a/library/core/src/slice/memchr.rs +++ /dev/null @@ -1,160 +0,0 @@ -// Original implementation taken from rust-memchr. -// Copyright 2015 Andrew Gallant, bluss and Nicolas Koch - -use crate::mem; - -const LO_USIZE: usize = usize::repeat_u8(0x01); -const HI_USIZE: usize = usize::repeat_u8(0x80); -const USIZE_BYTES: usize = mem::size_of::(); - -/// Returns `true` if `x` contains any zero byte. -/// -/// From *Matters Computational*, J. Arndt: -/// -/// "The idea is to subtract one from each of the bytes and then look for -/// bytes where the borrow propagated all the way to the most significant -/// bit." -#[inline] -#[rustc_const_stable(feature = "const_memchr", since = "1.65.0")] -const fn contains_zero_byte(x: usize) -> bool { - x.wrapping_sub(LO_USIZE) & !x & HI_USIZE != 0 -} - -/// Returns the first index matching the byte `x` in `text`. -#[inline] -#[must_use] -#[rustc_const_stable(feature = "const_memchr", since = "1.65.0")] -pub const fn memchr(x: u8, text: &[u8]) -> Option { - // Fast path for small slices. - if text.len() < 2 * USIZE_BYTES { - return memchr_naive(x, text); - } - - memchr_aligned(x, text) -} - -#[inline] -#[rustc_const_stable(feature = "const_memchr", since = "1.65.0")] -const fn memchr_naive(x: u8, text: &[u8]) -> Option { - let mut i = 0; - - // FIXME(const-hack): Replace with `text.iter().pos(|c| *c == x)`. - while i < text.len() { - if text[i] == x { - return Some(i); - } - - i += 1; - } - - None -} - -#[rustc_allow_const_fn_unstable(const_cmp)] -#[rustc_allow_const_fn_unstable(const_slice_index)] -#[rustc_allow_const_fn_unstable(const_align_offset)] -#[rustc_const_stable(feature = "const_memchr", since = "1.65.0")] -const fn memchr_aligned(x: u8, text: &[u8]) -> Option { - // Scan for a single byte value by reading two `usize` words at a time. - // - // Split `text` in three parts - // - unaligned initial part, before the first word aligned address in text - // - body, scan by 2 words at a time - // - the last remaining part, < 2 word size - - // search up to an aligned boundary - let len = text.len(); - let ptr = text.as_ptr(); - let mut offset = ptr.align_offset(USIZE_BYTES); - - if offset > 0 { - // FIXME(const-hack, fee1-dead): replace with min - offset = if offset < len { offset } else { len }; - // FIXME(const-hack, fee1-dead): replace with range slicing - // SAFETY: offset is within bounds - let slice = unsafe { super::from_raw_parts(text.as_ptr(), offset) }; - if let Some(index) = memchr_naive(x, slice) { - return Some(index); - } - } - - // search the body of the text - let repeated_x = usize::repeat_u8(x); - while offset <= len - 2 * USIZE_BYTES { - // SAFETY: the while's predicate guarantees a distance of at least 2 * usize_bytes - // between the offset and the end of the slice. - unsafe { - let u = *(ptr.add(offset) as *const usize); - let v = *(ptr.add(offset + USIZE_BYTES) as *const usize); - - // break if there is a matching byte - let zu = contains_zero_byte(u ^ repeated_x); - let zv = contains_zero_byte(v ^ repeated_x); - if zu || zv { - break; - } - } - offset += USIZE_BYTES * 2; - } - - // Find the byte after the point the body loop stopped. - // FIXME(const-hack): Use `?` instead. - // FIXME(const-hack, fee1-dead): use range slicing - // SAFETY: offset is within bounds - let slice = unsafe { super::from_raw_parts(text.as_ptr().add(offset), text.len() - offset) }; - if let Some(i) = memchr_naive(x, slice) { Some(offset + i) } else { None } -} - -/// Returns the last index matching the byte `x` in `text`. -#[must_use] -pub fn memrchr(x: u8, text: &[u8]) -> Option { - // Scan for a single byte value by reading two `usize` words at a time. - // - // Split `text` in three parts: - // - unaligned tail, after the last word aligned address in text, - // - body, scanned by 2 words at a time, - // - the first remaining bytes, < 2 word size. - let len = text.len(); - let ptr = text.as_ptr(); - type Chunk = usize; - - let (min_aligned_offset, max_aligned_offset) = { - // We call this just to obtain the length of the prefix and suffix. - // In the middle we always process two chunks at once. - // SAFETY: transmuting `[u8]` to `[usize]` is safe except for size differences - // which are handled by `align_to`. - let (prefix, _, suffix) = unsafe { text.align_to::<(Chunk, Chunk)>() }; - (prefix.len(), len - suffix.len()) - }; - - let mut offset = max_aligned_offset; - if let Some(index) = text[offset..].iter().rposition(|elt| *elt == x) { - return Some(offset + index); - } - - // Search the body of the text, make sure we don't cross min_aligned_offset. - // offset is always aligned, so just testing `>` is sufficient and avoids possible - // overflow. - let repeated_x = usize::repeat_u8(x); - let chunk_bytes = mem::size_of::(); - - while offset > min_aligned_offset { - // SAFETY: offset starts at len - suffix.len(), as long as it is greater than - // min_aligned_offset (prefix.len()) the remaining distance is at least 2 * chunk_bytes. - unsafe { - let u = *(ptr.add(offset - 2 * chunk_bytes) as *const Chunk); - let v = *(ptr.add(offset - chunk_bytes) as *const Chunk); - - // Break if there is a matching byte. - let zu = contains_zero_byte(u ^ repeated_x); - let zv = contains_zero_byte(v ^ repeated_x); - if zu || zv { - break; - } - } - offset -= 2 * chunk_bytes; - } - - // Find the byte before the point the body loop stopped. - text[..offset].iter().rposition(|elt| *elt == x) -} diff --git a/library/core/src/slice/mod.rs b/library/core/src/slice/mod.rs deleted file mode 100644 index f82f965e67cf4..0000000000000 --- a/library/core/src/slice/mod.rs +++ /dev/null @@ -1,4790 +0,0 @@ -//! Slice management and manipulation. -//! -//! For more details see [`std::slice`]. -//! -//! [`std::slice`]: ../../std/slice/index.html - -#![stable(feature = "rust1", since = "1.0.0")] - -use crate::cmp::Ordering::{self, Equal, Greater, Less}; -use crate::fmt; -use crate::hint; -use crate::intrinsics::{exact_div, unchecked_sub}; -use crate::mem::{self, SizedTypeProperties}; -use crate::num::NonZero; -use crate::ops::{Bound, OneSidedRange, Range, RangeBounds}; -use crate::ptr; -use crate::simd::{self, Simd}; -use crate::slice; -use crate::ub_checks::assert_unsafe_precondition; - -#[unstable( - feature = "slice_internals", - issue = "none", - reason = "exposed from core to be reused in std; use the memchr crate" -)] -/// Pure Rust memchr implementation, taken from rust-memchr -pub mod memchr; - -#[unstable( - feature = "slice_internals", - issue = "none", - reason = "exposed from core to be reused in std;" -)] -pub mod sort; - -mod ascii; -mod cmp; -pub(crate) mod index; -mod iter; -mod raw; -mod rotate; -mod select; -mod specialize; - -#[unstable(feature = "str_internals", issue = "none")] -#[doc(hidden)] -pub use ascii::is_ascii_simple; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use iter::{Chunks, ChunksMut, Windows}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use iter::{Iter, IterMut}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use iter::{RSplitN, RSplitNMut, Split, SplitMut, SplitN, SplitNMut}; - -#[stable(feature = "slice_rsplit", since = "1.27.0")] -pub use iter::{RSplit, RSplitMut}; - -#[stable(feature = "chunks_exact", since = "1.31.0")] -pub use iter::{ChunksExact, ChunksExactMut}; - -#[stable(feature = "rchunks", since = "1.31.0")] -pub use iter::{RChunks, RChunksExact, RChunksExactMut, RChunksMut}; - -#[unstable(feature = "array_chunks", issue = "74985")] -pub use iter::{ArrayChunks, ArrayChunksMut}; - -#[unstable(feature = "array_windows", issue = "75027")] -pub use iter::ArrayWindows; - -#[stable(feature = "slice_group_by", since = "1.77.0")] -pub use iter::{ChunkBy, ChunkByMut}; - -#[stable(feature = "split_inclusive", since = "1.51.0")] -pub use iter::{SplitInclusive, SplitInclusiveMut}; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use raw::{from_raw_parts, from_raw_parts_mut}; - -#[stable(feature = "from_ref", since = "1.28.0")] -pub use raw::{from_mut, from_ref}; - -#[unstable(feature = "slice_from_ptr_range", issue = "89792")] -pub use raw::{from_mut_ptr_range, from_ptr_range}; - -// This function is public only because there is no other way to unit test heapsort. -#[unstable(feature = "sort_internals", reason = "internal to sort module", issue = "none")] -pub use sort::heapsort; - -#[stable(feature = "slice_get_slice", since = "1.28.0")] -pub use index::SliceIndex; - -#[unstable(feature = "slice_range", issue = "76393")] -pub use index::{range, try_range}; - -#[stable(feature = "inherent_ascii_escape", since = "1.60.0")] -pub use ascii::EscapeAscii; - -/// Calculates the direction and split point of a one-sided range. -/// -/// This is a helper function for `take` and `take_mut` that returns -/// the direction of the split (front or back) as well as the index at -/// which to split. Returns `None` if the split index would overflow. -#[inline] -fn split_point_of(range: impl OneSidedRange) -> Option<(Direction, usize)> { - use Bound::*; - - Some(match (range.start_bound(), range.end_bound()) { - (Unbounded, Excluded(i)) => (Direction::Front, *i), - (Unbounded, Included(i)) => (Direction::Front, i.checked_add(1)?), - (Excluded(i), Unbounded) => (Direction::Back, i.checked_add(1)?), - (Included(i), Unbounded) => (Direction::Back, *i), - _ => unreachable!(), - }) -} - -enum Direction { - Front, - Back, -} - -#[cfg(not(test))] -impl [T] { - /// Returns the number of elements in the slice. - /// - /// # Examples - /// - /// ``` - /// let a = [1, 2, 3]; - /// assert_eq!(a.len(), 3); - /// ``` - #[lang = "slice_len_fn"] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_slice_len", since = "1.39.0")] - #[rustc_allow_const_fn_unstable(ptr_metadata)] - #[inline] - #[must_use] - pub const fn len(&self) -> usize { - ptr::metadata(self) - } - - /// Returns `true` if the slice has a length of 0. - /// - /// # Examples - /// - /// ``` - /// let a = [1, 2, 3]; - /// assert!(!a.is_empty()); - /// - /// let b: &[i32] = &[]; - /// assert!(b.is_empty()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_slice_is_empty", since = "1.39.0")] - #[inline] - #[must_use] - pub const fn is_empty(&self) -> bool { - self.len() == 0 - } - - /// Returns the first element of the slice, or `None` if it is empty. - /// - /// # Examples - /// - /// ``` - /// let v = [10, 40, 30]; - /// assert_eq!(Some(&10), v.first()); - /// - /// let w: &[i32] = &[]; - /// assert_eq!(None, w.first()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_slice_first_last_not_mut", since = "1.56.0")] - #[inline] - #[must_use] - pub const fn first(&self) -> Option<&T> { - if let [first, ..] = self { Some(first) } else { None } - } - - /// Returns a mutable pointer to the first element of the slice, or `None` if it is empty. - /// - /// # Examples - /// - /// ``` - /// let x = &mut [0, 1, 2]; - /// - /// if let Some(first) = x.first_mut() { - /// *first = 5; - /// } - /// assert_eq!(x, &[5, 1, 2]); - /// - /// let y: &mut [i32] = &mut []; - /// assert_eq!(None, y.first_mut()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_slice_first_last", issue = "83570")] - #[inline] - #[must_use] - pub const fn first_mut(&mut self) -> Option<&mut T> { - if let [first, ..] = self { Some(first) } else { None } - } - - /// Returns the first and all the rest of the elements of the slice, or `None` if it is empty. - /// - /// # Examples - /// - /// ``` - /// let x = &[0, 1, 2]; - /// - /// if let Some((first, elements)) = x.split_first() { - /// assert_eq!(first, &0); - /// assert_eq!(elements, &[1, 2]); - /// } - /// ``` - #[stable(feature = "slice_splits", since = "1.5.0")] - #[rustc_const_stable(feature = "const_slice_first_last_not_mut", since = "1.56.0")] - #[inline] - #[must_use] - pub const fn split_first(&self) -> Option<(&T, &[T])> { - if let [first, tail @ ..] = self { Some((first, tail)) } else { None } - } - - /// Returns the first and all the rest of the elements of the slice, or `None` if it is empty. - /// - /// # Examples - /// - /// ``` - /// let x = &mut [0, 1, 2]; - /// - /// if let Some((first, elements)) = x.split_first_mut() { - /// *first = 3; - /// elements[0] = 4; - /// elements[1] = 5; - /// } - /// assert_eq!(x, &[3, 4, 5]); - /// ``` - #[stable(feature = "slice_splits", since = "1.5.0")] - #[rustc_const_unstable(feature = "const_slice_first_last", issue = "83570")] - #[inline] - #[must_use] - pub const fn split_first_mut(&mut self) -> Option<(&mut T, &mut [T])> { - if let [first, tail @ ..] = self { Some((first, tail)) } else { None } - } - - /// Returns the last and all the rest of the elements of the slice, or `None` if it is empty. - /// - /// # Examples - /// - /// ``` - /// let x = &[0, 1, 2]; - /// - /// if let Some((last, elements)) = x.split_last() { - /// assert_eq!(last, &2); - /// assert_eq!(elements, &[0, 1]); - /// } - /// ``` - #[stable(feature = "slice_splits", since = "1.5.0")] - #[rustc_const_stable(feature = "const_slice_first_last_not_mut", since = "1.56.0")] - #[inline] - #[must_use] - pub const fn split_last(&self) -> Option<(&T, &[T])> { - if let [init @ .., last] = self { Some((last, init)) } else { None } - } - - /// Returns the last and all the rest of the elements of the slice, or `None` if it is empty. - /// - /// # Examples - /// - /// ``` - /// let x = &mut [0, 1, 2]; - /// - /// if let Some((last, elements)) = x.split_last_mut() { - /// *last = 3; - /// elements[0] = 4; - /// elements[1] = 5; - /// } - /// assert_eq!(x, &[4, 5, 3]); - /// ``` - #[stable(feature = "slice_splits", since = "1.5.0")] - #[rustc_const_unstable(feature = "const_slice_first_last", issue = "83570")] - #[inline] - #[must_use] - pub const fn split_last_mut(&mut self) -> Option<(&mut T, &mut [T])> { - if let [init @ .., last] = self { Some((last, init)) } else { None } - } - - /// Returns the last element of the slice, or `None` if it is empty. - /// - /// # Examples - /// - /// ``` - /// let v = [10, 40, 30]; - /// assert_eq!(Some(&30), v.last()); - /// - /// let w: &[i32] = &[]; - /// assert_eq!(None, w.last()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_slice_first_last_not_mut", since = "1.56.0")] - #[inline] - #[must_use] - pub const fn last(&self) -> Option<&T> { - if let [.., last] = self { Some(last) } else { None } - } - - /// Returns a mutable reference to the last item in the slice, or `None` if it is empty. - /// - /// # Examples - /// - /// ``` - /// let x = &mut [0, 1, 2]; - /// - /// if let Some(last) = x.last_mut() { - /// *last = 10; - /// } - /// assert_eq!(x, &[0, 1, 10]); - /// - /// let y: &mut [i32] = &mut []; - /// assert_eq!(None, y.last_mut()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_slice_first_last", issue = "83570")] - #[inline] - #[must_use] - pub const fn last_mut(&mut self) -> Option<&mut T> { - if let [.., last] = self { Some(last) } else { None } - } - - /// Return an array reference to the first `N` items in the slice. - /// - /// If the slice is not at least `N` in length, this will return `None`. - /// - /// # Examples - /// - /// ``` - /// let u = [10, 40, 30]; - /// assert_eq!(Some(&[10, 40]), u.first_chunk::<2>()); - /// - /// let v: &[i32] = &[10]; - /// assert_eq!(None, v.first_chunk::<2>()); - /// - /// let w: &[i32] = &[]; - /// assert_eq!(Some(&[]), w.first_chunk::<0>()); - /// ``` - #[inline] - #[stable(feature = "slice_first_last_chunk", since = "1.77.0")] - #[rustc_const_stable(feature = "slice_first_last_chunk", since = "1.77.0")] - pub const fn first_chunk(&self) -> Option<&[T; N]> { - if self.len() < N { - None - } else { - // SAFETY: We explicitly check for the correct number of elements, - // and do not let the reference outlive the slice. - Some(unsafe { &*(self.as_ptr().cast::<[T; N]>()) }) - } - } - - /// Return a mutable array reference to the first `N` items in the slice. - /// - /// If the slice is not at least `N` in length, this will return `None`. - /// - /// # Examples - /// - /// ``` - /// let x = &mut [0, 1, 2]; - /// - /// if let Some(first) = x.first_chunk_mut::<2>() { - /// first[0] = 5; - /// first[1] = 4; - /// } - /// assert_eq!(x, &[5, 4, 2]); - /// - /// assert_eq!(None, x.first_chunk_mut::<4>()); - /// ``` - #[inline] - #[stable(feature = "slice_first_last_chunk", since = "1.77.0")] - #[rustc_const_unstable(feature = "const_slice_first_last_chunk", issue = "111774")] - pub const fn first_chunk_mut(&mut self) -> Option<&mut [T; N]> { - if self.len() < N { - None - } else { - // SAFETY: We explicitly check for the correct number of elements, - // do not let the reference outlive the slice, - // and require exclusive access to the entire slice to mutate the chunk. - Some(unsafe { &mut *(self.as_mut_ptr().cast::<[T; N]>()) }) - } - } - - /// Return an array reference to the first `N` items in the slice and the remaining slice. - /// - /// If the slice is not at least `N` in length, this will return `None`. - /// - /// # Examples - /// - /// ``` - /// let x = &[0, 1, 2]; - /// - /// if let Some((first, elements)) = x.split_first_chunk::<2>() { - /// assert_eq!(first, &[0, 1]); - /// assert_eq!(elements, &[2]); - /// } - /// - /// assert_eq!(None, x.split_first_chunk::<4>()); - /// ``` - #[inline] - #[stable(feature = "slice_first_last_chunk", since = "1.77.0")] - #[rustc_const_stable(feature = "slice_first_last_chunk", since = "1.77.0")] - pub const fn split_first_chunk(&self) -> Option<(&[T; N], &[T])> { - if self.len() < N { - None - } else { - // SAFETY: We manually verified the bounds of the split. - let (first, tail) = unsafe { self.split_at_unchecked(N) }; - - // SAFETY: We explicitly check for the correct number of elements, - // and do not let the references outlive the slice. - Some((unsafe { &*(first.as_ptr().cast::<[T; N]>()) }, tail)) - } - } - - /// Return a mutable array reference to the first `N` items in the slice and the remaining - /// slice. - /// - /// If the slice is not at least `N` in length, this will return `None`. - /// - /// # Examples - /// - /// ``` - /// let x = &mut [0, 1, 2]; - /// - /// if let Some((first, elements)) = x.split_first_chunk_mut::<2>() { - /// first[0] = 3; - /// first[1] = 4; - /// elements[0] = 5; - /// } - /// assert_eq!(x, &[3, 4, 5]); - /// - /// assert_eq!(None, x.split_first_chunk_mut::<4>()); - /// ``` - #[inline] - #[stable(feature = "slice_first_last_chunk", since = "1.77.0")] - #[rustc_const_unstable(feature = "const_slice_first_last_chunk", issue = "111774")] - pub const fn split_first_chunk_mut( - &mut self, - ) -> Option<(&mut [T; N], &mut [T])> { - if self.len() < N { - None - } else { - // SAFETY: We manually verified the bounds of the split. - let (first, tail) = unsafe { self.split_at_mut_unchecked(N) }; - - // SAFETY: We explicitly check for the correct number of elements, - // do not let the reference outlive the slice, - // and enforce exclusive mutability of the chunk by the split. - Some((unsafe { &mut *(first.as_mut_ptr().cast::<[T; N]>()) }, tail)) - } - } - - /// Return an array reference to the last `N` items in the slice and the remaining slice. - /// - /// If the slice is not at least `N` in length, this will return `None`. - /// - /// # Examples - /// - /// ``` - /// let x = &[0, 1, 2]; - /// - /// if let Some((elements, last)) = x.split_last_chunk::<2>() { - /// assert_eq!(elements, &[0]); - /// assert_eq!(last, &[1, 2]); - /// } - /// - /// assert_eq!(None, x.split_last_chunk::<4>()); - /// ``` - #[inline] - #[stable(feature = "slice_first_last_chunk", since = "1.77.0")] - #[rustc_const_stable(feature = "slice_first_last_chunk", since = "1.77.0")] - pub const fn split_last_chunk(&self) -> Option<(&[T], &[T; N])> { - if self.len() < N { - None - } else { - // SAFETY: We manually verified the bounds of the split. - let (init, last) = unsafe { self.split_at_unchecked(self.len() - N) }; - - // SAFETY: We explicitly check for the correct number of elements, - // and do not let the references outlive the slice. - Some((init, unsafe { &*(last.as_ptr().cast::<[T; N]>()) })) - } - } - - /// Return a mutable array reference to the last `N` items in the slice and the remaining - /// slice. - /// - /// If the slice is not at least `N` in length, this will return `None`. - /// - /// # Examples - /// - /// ``` - /// let x = &mut [0, 1, 2]; - /// - /// if let Some((elements, last)) = x.split_last_chunk_mut::<2>() { - /// last[0] = 3; - /// last[1] = 4; - /// elements[0] = 5; - /// } - /// assert_eq!(x, &[5, 3, 4]); - /// - /// assert_eq!(None, x.split_last_chunk_mut::<4>()); - /// ``` - #[inline] - #[stable(feature = "slice_first_last_chunk", since = "1.77.0")] - #[rustc_const_unstable(feature = "const_slice_first_last_chunk", issue = "111774")] - pub const fn split_last_chunk_mut( - &mut self, - ) -> Option<(&mut [T], &mut [T; N])> { - if self.len() < N { - None - } else { - // SAFETY: We manually verified the bounds of the split. - let (init, last) = unsafe { self.split_at_mut_unchecked(self.len() - N) }; - - // SAFETY: We explicitly check for the correct number of elements, - // do not let the reference outlive the slice, - // and enforce exclusive mutability of the chunk by the split. - Some((init, unsafe { &mut *(last.as_mut_ptr().cast::<[T; N]>()) })) - } - } - - /// Return an array reference to the last `N` items in the slice. - /// - /// If the slice is not at least `N` in length, this will return `None`. - /// - /// # Examples - /// - /// ``` - /// let u = [10, 40, 30]; - /// assert_eq!(Some(&[40, 30]), u.last_chunk::<2>()); - /// - /// let v: &[i32] = &[10]; - /// assert_eq!(None, v.last_chunk::<2>()); - /// - /// let w: &[i32] = &[]; - /// assert_eq!(Some(&[]), w.last_chunk::<0>()); - /// ``` - #[inline] - #[stable(feature = "slice_first_last_chunk", since = "1.77.0")] - #[rustc_const_stable(feature = "slice_first_last_chunk", since = "1.77.0")] - pub const fn last_chunk(&self) -> Option<&[T; N]> { - if self.len() < N { - None - } else { - // SAFETY: We manually verified the bounds of the slice. - // FIXME: Without const traits, we need this instead of `get_unchecked`. - let last = unsafe { self.split_at_unchecked(self.len() - N).1 }; - - // SAFETY: We explicitly check for the correct number of elements, - // and do not let the references outlive the slice. - Some(unsafe { &*(last.as_ptr().cast::<[T; N]>()) }) - } - } - - /// Return a mutable array reference to the last `N` items in the slice. - /// - /// If the slice is not at least `N` in length, this will return `None`. - /// - /// # Examples - /// - /// ``` - /// let x = &mut [0, 1, 2]; - /// - /// if let Some(last) = x.last_chunk_mut::<2>() { - /// last[0] = 10; - /// last[1] = 20; - /// } - /// assert_eq!(x, &[0, 10, 20]); - /// - /// assert_eq!(None, x.last_chunk_mut::<4>()); - /// ``` - #[inline] - #[stable(feature = "slice_first_last_chunk", since = "1.77.0")] - #[rustc_const_unstable(feature = "const_slice_first_last_chunk", issue = "111774")] - pub const fn last_chunk_mut(&mut self) -> Option<&mut [T; N]> { - if self.len() < N { - None - } else { - // SAFETY: We manually verified the bounds of the slice. - // FIXME: Without const traits, we need this instead of `get_unchecked`. - let last = unsafe { self.split_at_mut_unchecked(self.len() - N).1 }; - - // SAFETY: We explicitly check for the correct number of elements, - // do not let the reference outlive the slice, - // and require exclusive access to the entire slice to mutate the chunk. - Some(unsafe { &mut *(last.as_mut_ptr().cast::<[T; N]>()) }) - } - } - - /// Returns a reference to an element or subslice depending on the type of - /// index. - /// - /// - If given a position, returns a reference to the element at that - /// position or `None` if out of bounds. - /// - If given a range, returns the subslice corresponding to that range, - /// or `None` if out of bounds. - /// - /// # Examples - /// - /// ``` - /// let v = [10, 40, 30]; - /// assert_eq!(Some(&40), v.get(1)); - /// assert_eq!(Some(&[10, 40][..]), v.get(0..2)); - /// assert_eq!(None, v.get(3)); - /// assert_eq!(None, v.get(0..4)); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - #[must_use] - pub fn get(&self, index: I) -> Option<&I::Output> - where - I: SliceIndex, - { - index.get(self) - } - - /// Returns a mutable reference to an element or subslice depending on the - /// type of index (see [`get`]) or `None` if the index is out of bounds. - /// - /// [`get`]: slice::get - /// - /// # Examples - /// - /// ``` - /// let x = &mut [0, 1, 2]; - /// - /// if let Some(elem) = x.get_mut(1) { - /// *elem = 42; - /// } - /// assert_eq!(x, &[0, 42, 2]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - #[must_use] - pub fn get_mut(&mut self, index: I) -> Option<&mut I::Output> - where - I: SliceIndex, - { - index.get_mut(self) - } - - /// Returns a reference to an element or subslice, without doing bounds - /// checking. - /// - /// For a safe alternative see [`get`]. - /// - /// # Safety - /// - /// Calling this method with an out-of-bounds index is *[undefined behavior]* - /// even if the resulting reference is not used. - /// - /// You can think of this like `.get(index).unwrap_unchecked()`. It's UB - /// to call `.get_unchecked(len)`, even if you immediately convert to a - /// pointer. And it's UB to call `.get_unchecked(..len + 1)`, - /// `.get_unchecked(..=len)`, or similar. - /// - /// [`get`]: slice::get - /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html - /// - /// # Examples - /// - /// ``` - /// let x = &[1, 2, 4]; - /// - /// unsafe { - /// assert_eq!(x.get_unchecked(1), &2); - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - #[must_use] - pub unsafe fn get_unchecked(&self, index: I) -> &I::Output - where - I: SliceIndex, - { - // SAFETY: the caller must uphold most of the safety requirements for `get_unchecked`; - // the slice is dereferenceable because `self` is a safe reference. - // The returned pointer is safe because impls of `SliceIndex` have to guarantee that it is. - unsafe { &*index.get_unchecked(self) } - } - - /// Returns a mutable reference to an element or subslice, without doing - /// bounds checking. - /// - /// For a safe alternative see [`get_mut`]. - /// - /// # Safety - /// - /// Calling this method with an out-of-bounds index is *[undefined behavior]* - /// even if the resulting reference is not used. - /// - /// You can think of this like `.get_mut(index).unwrap_unchecked()`. It's - /// UB to call `.get_unchecked_mut(len)`, even if you immediately convert - /// to a pointer. And it's UB to call `.get_unchecked_mut(..len + 1)`, - /// `.get_unchecked_mut(..=len)`, or similar. - /// - /// [`get_mut`]: slice::get_mut - /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html - /// - /// # Examples - /// - /// ``` - /// let x = &mut [1, 2, 4]; - /// - /// unsafe { - /// let elem = x.get_unchecked_mut(1); - /// *elem = 13; - /// } - /// assert_eq!(x, &[1, 13, 4]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - #[must_use] - pub unsafe fn get_unchecked_mut(&mut self, index: I) -> &mut I::Output - where - I: SliceIndex, - { - // SAFETY: the caller must uphold the safety requirements for `get_unchecked_mut`; - // the slice is dereferenceable because `self` is a safe reference. - // The returned pointer is safe because impls of `SliceIndex` have to guarantee that it is. - unsafe { &mut *index.get_unchecked_mut(self) } - } - - /// Returns a raw pointer to the slice's buffer. - /// - /// The caller must ensure that the slice outlives the pointer this - /// function returns, or else it will end up pointing to garbage. - /// - /// The caller must also ensure that the memory the pointer (non-transitively) points to - /// is never written to (except inside an `UnsafeCell`) using this pointer or any pointer - /// derived from it. If you need to mutate the contents of the slice, use [`as_mut_ptr`]. - /// - /// Modifying the container referenced by this slice may cause its buffer - /// to be reallocated, which would also make any pointers to it invalid. - /// - /// # Examples - /// - /// ``` - /// let x = &[1, 2, 4]; - /// let x_ptr = x.as_ptr(); - /// - /// unsafe { - /// for i in 0..x.len() { - /// assert_eq!(x.get_unchecked(i), &*x_ptr.add(i)); - /// } - /// } - /// ``` - /// - /// [`as_mut_ptr`]: slice::as_mut_ptr - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_slice_as_ptr", since = "1.32.0")] - #[rustc_never_returns_null_ptr] - #[inline(always)] - #[must_use] - pub const fn as_ptr(&self) -> *const T { - self as *const [T] as *const T - } - - /// Returns an unsafe mutable pointer to the slice's buffer. - /// - /// The caller must ensure that the slice outlives the pointer this - /// function returns, or else it will end up pointing to garbage. - /// - /// Modifying the container referenced by this slice may cause its buffer - /// to be reallocated, which would also make any pointers to it invalid. - /// - /// # Examples - /// - /// ``` - /// let x = &mut [1, 2, 4]; - /// let x_ptr = x.as_mut_ptr(); - /// - /// unsafe { - /// for i in 0..x.len() { - /// *x_ptr.add(i) += 2; - /// } - /// } - /// assert_eq!(x, &[3, 4, 6]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")] - #[rustc_allow_const_fn_unstable(const_mut_refs)] - #[rustc_never_returns_null_ptr] - #[inline(always)] - #[must_use] - pub const fn as_mut_ptr(&mut self) -> *mut T { - self as *mut [T] as *mut T - } - - /// Returns the two raw pointers spanning the slice. - /// - /// The returned range is half-open, which means that the end pointer - /// points *one past* the last element of the slice. This way, an empty - /// slice is represented by two equal pointers, and the difference between - /// the two pointers represents the size of the slice. - /// - /// See [`as_ptr`] for warnings on using these pointers. The end pointer - /// requires extra caution, as it does not point to a valid element in the - /// slice. - /// - /// This function is useful for interacting with foreign interfaces which - /// use two pointers to refer to a range of elements in memory, as is - /// common in C++. - /// - /// It can also be useful to check if a pointer to an element refers to an - /// element of this slice: - /// - /// ``` - /// let a = [1, 2, 3]; - /// let x = &a[1] as *const _; - /// let y = &5 as *const _; - /// - /// assert!(a.as_ptr_range().contains(&x)); - /// assert!(!a.as_ptr_range().contains(&y)); - /// ``` - /// - /// [`as_ptr`]: slice::as_ptr - #[stable(feature = "slice_ptr_range", since = "1.48.0")] - #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")] - #[inline] - #[must_use] - pub const fn as_ptr_range(&self) -> Range<*const T> { - let start = self.as_ptr(); - // SAFETY: The `add` here is safe, because: - // - // - Both pointers are part of the same object, as pointing directly - // past the object also counts. - // - // - The size of the slice is never larger than isize::MAX bytes, as - // noted here: - // - https://github.com/rust-lang/unsafe-code-guidelines/issues/102#issuecomment-473340447 - // - https://doc.rust-lang.org/reference/behavior-considered-undefined.html - // - https://doc.rust-lang.org/core/slice/fn.from_raw_parts.html#safety - // (This doesn't seem normative yet, but the very same assumption is - // made in many places, including the Index implementation of slices.) - // - // - There is no wrapping around involved, as slices do not wrap past - // the end of the address space. - // - // See the documentation of pointer::add. - let end = unsafe { start.add(self.len()) }; - start..end - } - - /// Returns the two unsafe mutable pointers spanning the slice. - /// - /// The returned range is half-open, which means that the end pointer - /// points *one past* the last element of the slice. This way, an empty - /// slice is represented by two equal pointers, and the difference between - /// the two pointers represents the size of the slice. - /// - /// See [`as_mut_ptr`] for warnings on using these pointers. The end - /// pointer requires extra caution, as it does not point to a valid element - /// in the slice. - /// - /// This function is useful for interacting with foreign interfaces which - /// use two pointers to refer to a range of elements in memory, as is - /// common in C++. - /// - /// [`as_mut_ptr`]: slice::as_mut_ptr - #[stable(feature = "slice_ptr_range", since = "1.48.0")] - #[rustc_const_stable(feature = "const_ptr_offset", since = "1.61.0")] - #[rustc_allow_const_fn_unstable(const_mut_refs)] - #[inline] - #[must_use] - pub const fn as_mut_ptr_range(&mut self) -> Range<*mut T> { - let start = self.as_mut_ptr(); - // SAFETY: See as_ptr_range() above for why `add` here is safe. - let end = unsafe { start.add(self.len()) }; - start..end - } - - /// Swaps two elements in the slice. - /// - /// If `a` equals to `b`, it's guaranteed that elements won't change value. - /// - /// # Arguments - /// - /// * a - The index of the first element - /// * b - The index of the second element - /// - /// # Panics - /// - /// Panics if `a` or `b` are out of bounds. - /// - /// # Examples - /// - /// ``` - /// let mut v = ["a", "b", "c", "d", "e"]; - /// v.swap(2, 4); - /// assert!(v == ["a", "b", "e", "d", "c"]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_swap", issue = "83163")] - #[inline] - #[track_caller] - pub const fn swap(&mut self, a: usize, b: usize) { - // FIXME: use swap_unchecked here (https://github.com/rust-lang/rust/pull/88540#issuecomment-944344343) - // Can't take two mutable loans from one vector, so instead use raw pointers. - let pa = ptr::addr_of_mut!(self[a]); - let pb = ptr::addr_of_mut!(self[b]); - // SAFETY: `pa` and `pb` have been created from safe mutable references and refer - // to elements in the slice and therefore are guaranteed to be valid and aligned. - // Note that accessing the elements behind `a` and `b` is checked and will - // panic when out of bounds. - unsafe { - ptr::swap(pa, pb); - } - } - - /// Swaps two elements in the slice, without doing bounds checking. - /// - /// For a safe alternative see [`swap`]. - /// - /// # Arguments - /// - /// * a - The index of the first element - /// * b - The index of the second element - /// - /// # Safety - /// - /// Calling this method with an out-of-bounds index is *[undefined behavior]*. - /// The caller has to ensure that `a < self.len()` and `b < self.len()`. - /// - /// # Examples - /// - /// ``` - /// #![feature(slice_swap_unchecked)] - /// - /// let mut v = ["a", "b", "c", "d"]; - /// // SAFETY: we know that 1 and 3 are both indices of the slice - /// unsafe { v.swap_unchecked(1, 3) }; - /// assert!(v == ["a", "d", "c", "b"]); - /// ``` - /// - /// [`swap`]: slice::swap - /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html - #[unstable(feature = "slice_swap_unchecked", issue = "88539")] - #[rustc_const_unstable(feature = "const_swap", issue = "83163")] - pub const unsafe fn swap_unchecked(&mut self, a: usize, b: usize) { - assert_unsafe_precondition!( - check_library_ub, - "slice::swap_unchecked requires that the indices are within the slice", - ( - len: usize = self.len(), - a: usize = a, - b: usize = b, - ) => a < len && b < len, - ); - - let ptr = self.as_mut_ptr(); - // SAFETY: caller has to guarantee that `a < self.len()` and `b < self.len()` - unsafe { - ptr::swap(ptr.add(a), ptr.add(b)); - } - } - - /// Reverses the order of elements in the slice, in place. - /// - /// # Examples - /// - /// ``` - /// let mut v = [1, 2, 3]; - /// v.reverse(); - /// assert!(v == [3, 2, 1]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn reverse(&mut self) { - let half_len = self.len() / 2; - let Range { start, end } = self.as_mut_ptr_range(); - - // These slices will skip the middle item for an odd length, - // since that one doesn't need to move. - let (front_half, back_half) = - // SAFETY: Both are subparts of the original slice, so the memory - // range is valid, and they don't overlap because they're each only - // half (or less) of the original slice. - unsafe { - ( - slice::from_raw_parts_mut(start, half_len), - slice::from_raw_parts_mut(end.sub(half_len), half_len), - ) - }; - - // Introducing a function boundary here means that the two halves - // get `noalias` markers, allowing better optimization as LLVM - // knows that they're disjoint, unlike in the original slice. - revswap(front_half, back_half, half_len); - - #[inline] - fn revswap(a: &mut [T], b: &mut [T], n: usize) { - debug_assert!(a.len() == n); - debug_assert!(b.len() == n); - - // Because this function is first compiled in isolation, - // this check tells LLVM that the indexing below is - // in-bounds. Then after inlining -- once the actual - // lengths of the slices are known -- it's removed. - let (a, b) = (&mut a[..n], &mut b[..n]); - - let mut i = 0; - while i < n { - mem::swap(&mut a[i], &mut b[n - 1 - i]); - i += 1; - } - } - } - - /// Returns an iterator over the slice. - /// - /// The iterator yields all items from start to end. - /// - /// # Examples - /// - /// ``` - /// let x = &[1, 2, 4]; - /// let mut iterator = x.iter(); - /// - /// assert_eq!(iterator.next(), Some(&1)); - /// assert_eq!(iterator.next(), Some(&2)); - /// assert_eq!(iterator.next(), Some(&4)); - /// assert_eq!(iterator.next(), None); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn iter(&self) -> Iter<'_, T> { - Iter::new(self) - } - - /// Returns an iterator that allows modifying each value. - /// - /// The iterator yields all items from start to end. - /// - /// # Examples - /// - /// ``` - /// let x = &mut [1, 2, 4]; - /// for elem in x.iter_mut() { - /// *elem += 2; - /// } - /// assert_eq!(x, &[3, 4, 6]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn iter_mut(&mut self) -> IterMut<'_, T> { - IterMut::new(self) - } - - /// Returns an iterator over all contiguous windows of length - /// `size`. The windows overlap. If the slice is shorter than - /// `size`, the iterator returns no values. - /// - /// # Panics - /// - /// Panics if `size` is 0. - /// - /// # Examples - /// - /// ``` - /// let slice = ['l', 'o', 'r', 'e', 'm']; - /// let mut iter = slice.windows(3); - /// assert_eq!(iter.next().unwrap(), &['l', 'o', 'r']); - /// assert_eq!(iter.next().unwrap(), &['o', 'r', 'e']); - /// assert_eq!(iter.next().unwrap(), &['r', 'e', 'm']); - /// assert!(iter.next().is_none()); - /// ``` - /// - /// If the slice is shorter than `size`: - /// - /// ``` - /// let slice = ['f', 'o', 'o']; - /// let mut iter = slice.windows(4); - /// assert!(iter.next().is_none()); - /// ``` - /// - /// There's no `windows_mut`, as that existing would let safe code violate the - /// "only one `&mut` at a time to the same thing" rule. However, you can sometimes - /// use [`Cell::as_slice_of_cells`](crate::cell::Cell::as_slice_of_cells) in - /// conjunction with `windows` to accomplish something similar: - /// ``` - /// use std::cell::Cell; - /// - /// let mut array = ['R', 'u', 's', 't', ' ', '2', '0', '1', '5']; - /// let slice = &mut array[..]; - /// let slice_of_cells: &[Cell] = Cell::from_mut(slice).as_slice_of_cells(); - /// for w in slice_of_cells.windows(3) { - /// Cell::swap(&w[0], &w[2]); - /// } - /// assert_eq!(array, ['s', 't', ' ', '2', '0', '1', '5', 'u', 'R']); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - #[track_caller] - pub fn windows(&self, size: usize) -> Windows<'_, T> { - let size = NonZero::new(size).expect("window size must be non-zero"); - Windows::new(self, size) - } - - /// Returns an iterator over `chunk_size` elements of the slice at a time, starting at the - /// beginning of the slice. - /// - /// The chunks are slices and do not overlap. If `chunk_size` does not divide the length of the - /// slice, then the last chunk will not have length `chunk_size`. - /// - /// See [`chunks_exact`] for a variant of this iterator that returns chunks of always exactly - /// `chunk_size` elements, and [`rchunks`] for the same iterator but starting at the end of the - /// slice. - /// - /// # Panics - /// - /// Panics if `chunk_size` is 0. - /// - /// # Examples - /// - /// ``` - /// let slice = ['l', 'o', 'r', 'e', 'm']; - /// let mut iter = slice.chunks(2); - /// assert_eq!(iter.next().unwrap(), &['l', 'o']); - /// assert_eq!(iter.next().unwrap(), &['r', 'e']); - /// assert_eq!(iter.next().unwrap(), &['m']); - /// assert!(iter.next().is_none()); - /// ``` - /// - /// [`chunks_exact`]: slice::chunks_exact - /// [`rchunks`]: slice::rchunks - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - #[track_caller] - pub fn chunks(&self, chunk_size: usize) -> Chunks<'_, T> { - assert!(chunk_size != 0, "chunk size must be non-zero"); - Chunks::new(self, chunk_size) - } - - /// Returns an iterator over `chunk_size` elements of the slice at a time, starting at the - /// beginning of the slice. - /// - /// The chunks are mutable slices, and do not overlap. If `chunk_size` does not divide the - /// length of the slice, then the last chunk will not have length `chunk_size`. - /// - /// See [`chunks_exact_mut`] for a variant of this iterator that returns chunks of always - /// exactly `chunk_size` elements, and [`rchunks_mut`] for the same iterator but starting at - /// the end of the slice. - /// - /// # Panics - /// - /// Panics if `chunk_size` is 0. - /// - /// # Examples - /// - /// ``` - /// let v = &mut [0, 0, 0, 0, 0]; - /// let mut count = 1; - /// - /// for chunk in v.chunks_mut(2) { - /// for elem in chunk.iter_mut() { - /// *elem += count; - /// } - /// count += 1; - /// } - /// assert_eq!(v, &[1, 1, 2, 2, 3]); - /// ``` - /// - /// [`chunks_exact_mut`]: slice::chunks_exact_mut - /// [`rchunks_mut`]: slice::rchunks_mut - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - #[track_caller] - pub fn chunks_mut(&mut self, chunk_size: usize) -> ChunksMut<'_, T> { - assert!(chunk_size != 0, "chunk size must be non-zero"); - ChunksMut::new(self, chunk_size) - } - - /// Returns an iterator over `chunk_size` elements of the slice at a time, starting at the - /// beginning of the slice. - /// - /// The chunks are slices and do not overlap. If `chunk_size` does not divide the length of the - /// slice, then the last up to `chunk_size-1` elements will be omitted and can be retrieved - /// from the `remainder` function of the iterator. - /// - /// Due to each chunk having exactly `chunk_size` elements, the compiler can often optimize the - /// resulting code better than in the case of [`chunks`]. - /// - /// See [`chunks`] for a variant of this iterator that also returns the remainder as a smaller - /// chunk, and [`rchunks_exact`] for the same iterator but starting at the end of the slice. - /// - /// # Panics - /// - /// Panics if `chunk_size` is 0. - /// - /// # Examples - /// - /// ``` - /// let slice = ['l', 'o', 'r', 'e', 'm']; - /// let mut iter = slice.chunks_exact(2); - /// assert_eq!(iter.next().unwrap(), &['l', 'o']); - /// assert_eq!(iter.next().unwrap(), &['r', 'e']); - /// assert!(iter.next().is_none()); - /// assert_eq!(iter.remainder(), &['m']); - /// ``` - /// - /// [`chunks`]: slice::chunks - /// [`rchunks_exact`]: slice::rchunks_exact - #[stable(feature = "chunks_exact", since = "1.31.0")] - #[inline] - #[track_caller] - pub fn chunks_exact(&self, chunk_size: usize) -> ChunksExact<'_, T> { - assert!(chunk_size != 0, "chunk size must be non-zero"); - ChunksExact::new(self, chunk_size) - } - - /// Returns an iterator over `chunk_size` elements of the slice at a time, starting at the - /// beginning of the slice. - /// - /// The chunks are mutable slices, and do not overlap. If `chunk_size` does not divide the - /// length of the slice, then the last up to `chunk_size-1` elements will be omitted and can be - /// retrieved from the `into_remainder` function of the iterator. - /// - /// Due to each chunk having exactly `chunk_size` elements, the compiler can often optimize the - /// resulting code better than in the case of [`chunks_mut`]. - /// - /// See [`chunks_mut`] for a variant of this iterator that also returns the remainder as a - /// smaller chunk, and [`rchunks_exact_mut`] for the same iterator but starting at the end of - /// the slice. - /// - /// # Panics - /// - /// Panics if `chunk_size` is 0. - /// - /// # Examples - /// - /// ``` - /// let v = &mut [0, 0, 0, 0, 0]; - /// let mut count = 1; - /// - /// for chunk in v.chunks_exact_mut(2) { - /// for elem in chunk.iter_mut() { - /// *elem += count; - /// } - /// count += 1; - /// } - /// assert_eq!(v, &[1, 1, 2, 2, 0]); - /// ``` - /// - /// [`chunks_mut`]: slice::chunks_mut - /// [`rchunks_exact_mut`]: slice::rchunks_exact_mut - #[stable(feature = "chunks_exact", since = "1.31.0")] - #[inline] - #[track_caller] - pub fn chunks_exact_mut(&mut self, chunk_size: usize) -> ChunksExactMut<'_, T> { - assert!(chunk_size != 0, "chunk size must be non-zero"); - ChunksExactMut::new(self, chunk_size) - } - - /// Splits the slice into a slice of `N`-element arrays, - /// assuming that there's no remainder. - /// - /// # Safety - /// - /// This may only be called when - /// - The slice splits exactly into `N`-element chunks (aka `self.len() % N == 0`). - /// - `N != 0`. - /// - /// # Examples - /// - /// ``` - /// #![feature(slice_as_chunks)] - /// let slice: &[char] = &['l', 'o', 'r', 'e', 'm', '!']; - /// let chunks: &[[char; 1]] = - /// // SAFETY: 1-element chunks never have remainder - /// unsafe { slice.as_chunks_unchecked() }; - /// assert_eq!(chunks, &[['l'], ['o'], ['r'], ['e'], ['m'], ['!']]); - /// let chunks: &[[char; 3]] = - /// // SAFETY: The slice length (6) is a multiple of 3 - /// unsafe { slice.as_chunks_unchecked() }; - /// assert_eq!(chunks, &[['l', 'o', 'r'], ['e', 'm', '!']]); - /// - /// // These would be unsound: - /// // let chunks: &[[_; 5]] = slice.as_chunks_unchecked() // The slice length is not a multiple of 5 - /// // let chunks: &[[_; 0]] = slice.as_chunks_unchecked() // Zero-length chunks are never allowed - /// ``` - #[unstable(feature = "slice_as_chunks", issue = "74985")] - #[inline] - #[must_use] - pub const unsafe fn as_chunks_unchecked(&self) -> &[[T; N]] { - assert_unsafe_precondition!( - check_language_ub, - "slice::as_chunks_unchecked requires `N != 0` and the slice to split exactly into `N`-element chunks", - (n: usize = N, len: usize = self.len()) => n != 0 && len % n == 0, - ); - // SAFETY: Caller must guarantee that `N` is nonzero and exactly divides the slice length - let new_len = unsafe { exact_div(self.len(), N) }; - // SAFETY: We cast a slice of `new_len * N` elements into - // a slice of `new_len` many `N` elements chunks. - unsafe { from_raw_parts(self.as_ptr().cast(), new_len) } - } - - /// Splits the slice into a slice of `N`-element arrays, - /// starting at the beginning of the slice, - /// and a remainder slice with length strictly less than `N`. - /// - /// # Panics - /// - /// Panics if `N` is 0. This check will most probably get changed to a compile time - /// error before this method gets stabilized. - /// - /// # Examples - /// - /// ``` - /// #![feature(slice_as_chunks)] - /// let slice = ['l', 'o', 'r', 'e', 'm']; - /// let (chunks, remainder) = slice.as_chunks(); - /// assert_eq!(chunks, &[['l', 'o'], ['r', 'e']]); - /// assert_eq!(remainder, &['m']); - /// ``` - /// - /// If you expect the slice to be an exact multiple, you can combine - /// `let`-`else` with an empty slice pattern: - /// ``` - /// #![feature(slice_as_chunks)] - /// let slice = ['R', 'u', 's', 't']; - /// let (chunks, []) = slice.as_chunks::<2>() else { - /// panic!("slice didn't have even length") - /// }; - /// assert_eq!(chunks, &[['R', 'u'], ['s', 't']]); - /// ``` - #[unstable(feature = "slice_as_chunks", issue = "74985")] - #[inline] - #[track_caller] - #[must_use] - pub const fn as_chunks(&self) -> (&[[T; N]], &[T]) { - assert!(N != 0, "chunk size must be non-zero"); - let len_rounded_down = self.len() / N * N; - // SAFETY: The rounded-down value is always the same or smaller than the - // original length, and thus must be in-bounds of the slice. - let (multiple_of_n, remainder) = unsafe { self.split_at_unchecked(len_rounded_down) }; - // SAFETY: We already panicked for zero, and ensured by construction - // that the length of the subslice is a multiple of N. - let array_slice = unsafe { multiple_of_n.as_chunks_unchecked() }; - (array_slice, remainder) - } - - /// Splits the slice into a slice of `N`-element arrays, - /// starting at the end of the slice, - /// and a remainder slice with length strictly less than `N`. - /// - /// # Panics - /// - /// Panics if `N` is 0. This check will most probably get changed to a compile time - /// error before this method gets stabilized. - /// - /// # Examples - /// - /// ``` - /// #![feature(slice_as_chunks)] - /// let slice = ['l', 'o', 'r', 'e', 'm']; - /// let (remainder, chunks) = slice.as_rchunks(); - /// assert_eq!(remainder, &['l']); - /// assert_eq!(chunks, &[['o', 'r'], ['e', 'm']]); - /// ``` - #[unstable(feature = "slice_as_chunks", issue = "74985")] - #[inline] - #[track_caller] - #[must_use] - pub const fn as_rchunks(&self) -> (&[T], &[[T; N]]) { - assert!(N != 0, "chunk size must be non-zero"); - let len = self.len() / N; - let (remainder, multiple_of_n) = self.split_at(self.len() - len * N); - // SAFETY: We already panicked for zero, and ensured by construction - // that the length of the subslice is a multiple of N. - let array_slice = unsafe { multiple_of_n.as_chunks_unchecked() }; - (remainder, array_slice) - } - - /// Returns an iterator over `N` elements of the slice at a time, starting at the - /// beginning of the slice. - /// - /// The chunks are array references and do not overlap. If `N` does not divide the - /// length of the slice, then the last up to `N-1` elements will be omitted and can be - /// retrieved from the `remainder` function of the iterator. - /// - /// This method is the const generic equivalent of [`chunks_exact`]. - /// - /// # Panics - /// - /// Panics if `N` is 0. This check will most probably get changed to a compile time - /// error before this method gets stabilized. - /// - /// # Examples - /// - /// ``` - /// #![feature(array_chunks)] - /// let slice = ['l', 'o', 'r', 'e', 'm']; - /// let mut iter = slice.array_chunks(); - /// assert_eq!(iter.next().unwrap(), &['l', 'o']); - /// assert_eq!(iter.next().unwrap(), &['r', 'e']); - /// assert!(iter.next().is_none()); - /// assert_eq!(iter.remainder(), &['m']); - /// ``` - /// - /// [`chunks_exact`]: slice::chunks_exact - #[unstable(feature = "array_chunks", issue = "74985")] - #[inline] - #[track_caller] - pub fn array_chunks(&self) -> ArrayChunks<'_, T, N> { - assert!(N != 0, "chunk size must be non-zero"); - ArrayChunks::new(self) - } - - /// Splits the slice into a slice of `N`-element arrays, - /// assuming that there's no remainder. - /// - /// # Safety - /// - /// This may only be called when - /// - The slice splits exactly into `N`-element chunks (aka `self.len() % N == 0`). - /// - `N != 0`. - /// - /// # Examples - /// - /// ``` - /// #![feature(slice_as_chunks)] - /// let slice: &mut [char] = &mut ['l', 'o', 'r', 'e', 'm', '!']; - /// let chunks: &mut [[char; 1]] = - /// // SAFETY: 1-element chunks never have remainder - /// unsafe { slice.as_chunks_unchecked_mut() }; - /// chunks[0] = ['L']; - /// assert_eq!(chunks, &[['L'], ['o'], ['r'], ['e'], ['m'], ['!']]); - /// let chunks: &mut [[char; 3]] = - /// // SAFETY: The slice length (6) is a multiple of 3 - /// unsafe { slice.as_chunks_unchecked_mut() }; - /// chunks[1] = ['a', 'x', '?']; - /// assert_eq!(slice, &['L', 'o', 'r', 'a', 'x', '?']); - /// - /// // These would be unsound: - /// // let chunks: &[[_; 5]] = slice.as_chunks_unchecked_mut() // The slice length is not a multiple of 5 - /// // let chunks: &[[_; 0]] = slice.as_chunks_unchecked_mut() // Zero-length chunks are never allowed - /// ``` - #[unstable(feature = "slice_as_chunks", issue = "74985")] - #[inline] - #[must_use] - pub const unsafe fn as_chunks_unchecked_mut(&mut self) -> &mut [[T; N]] { - assert_unsafe_precondition!( - check_language_ub, - "slice::as_chunks_unchecked requires `N != 0` and the slice to split exactly into `N`-element chunks", - (n: usize = N, len: usize = self.len()) => n != 0 && len % n == 0 - ); - // SAFETY: Caller must guarantee that `N` is nonzero and exactly divides the slice length - let new_len = unsafe { exact_div(self.len(), N) }; - // SAFETY: We cast a slice of `new_len * N` elements into - // a slice of `new_len` many `N` elements chunks. - unsafe { from_raw_parts_mut(self.as_mut_ptr().cast(), new_len) } - } - - /// Splits the slice into a slice of `N`-element arrays, - /// starting at the beginning of the slice, - /// and a remainder slice with length strictly less than `N`. - /// - /// # Panics - /// - /// Panics if `N` is 0. This check will most probably get changed to a compile time - /// error before this method gets stabilized. - /// - /// # Examples - /// - /// ``` - /// #![feature(slice_as_chunks)] - /// let v = &mut [0, 0, 0, 0, 0]; - /// let mut count = 1; - /// - /// let (chunks, remainder) = v.as_chunks_mut(); - /// remainder[0] = 9; - /// for chunk in chunks { - /// *chunk = [count; 2]; - /// count += 1; - /// } - /// assert_eq!(v, &[1, 1, 2, 2, 9]); - /// ``` - #[unstable(feature = "slice_as_chunks", issue = "74985")] - #[inline] - #[track_caller] - #[must_use] - pub const fn as_chunks_mut(&mut self) -> (&mut [[T; N]], &mut [T]) { - assert!(N != 0, "chunk size must be non-zero"); - let len_rounded_down = self.len() / N * N; - // SAFETY: The rounded-down value is always the same or smaller than the - // original length, and thus must be in-bounds of the slice. - let (multiple_of_n, remainder) = unsafe { self.split_at_mut_unchecked(len_rounded_down) }; - // SAFETY: We already panicked for zero, and ensured by construction - // that the length of the subslice is a multiple of N. - let array_slice = unsafe { multiple_of_n.as_chunks_unchecked_mut() }; - (array_slice, remainder) - } - - /// Splits the slice into a slice of `N`-element arrays, - /// starting at the end of the slice, - /// and a remainder slice with length strictly less than `N`. - /// - /// # Panics - /// - /// Panics if `N` is 0. This check will most probably get changed to a compile time - /// error before this method gets stabilized. - /// - /// # Examples - /// - /// ``` - /// #![feature(slice_as_chunks)] - /// let v = &mut [0, 0, 0, 0, 0]; - /// let mut count = 1; - /// - /// let (remainder, chunks) = v.as_rchunks_mut(); - /// remainder[0] = 9; - /// for chunk in chunks { - /// *chunk = [count; 2]; - /// count += 1; - /// } - /// assert_eq!(v, &[9, 1, 1, 2, 2]); - /// ``` - #[unstable(feature = "slice_as_chunks", issue = "74985")] - #[inline] - #[track_caller] - #[must_use] - pub const fn as_rchunks_mut(&mut self) -> (&mut [T], &mut [[T; N]]) { - assert!(N != 0, "chunk size must be non-zero"); - let len = self.len() / N; - let (remainder, multiple_of_n) = self.split_at_mut(self.len() - len * N); - // SAFETY: We already panicked for zero, and ensured by construction - // that the length of the subslice is a multiple of N. - let array_slice = unsafe { multiple_of_n.as_chunks_unchecked_mut() }; - (remainder, array_slice) - } - - /// Returns an iterator over `N` elements of the slice at a time, starting at the - /// beginning of the slice. - /// - /// The chunks are mutable array references and do not overlap. If `N` does not divide - /// the length of the slice, then the last up to `N-1` elements will be omitted and - /// can be retrieved from the `into_remainder` function of the iterator. - /// - /// This method is the const generic equivalent of [`chunks_exact_mut`]. - /// - /// # Panics - /// - /// Panics if `N` is 0. This check will most probably get changed to a compile time - /// error before this method gets stabilized. - /// - /// # Examples - /// - /// ``` - /// #![feature(array_chunks)] - /// let v = &mut [0, 0, 0, 0, 0]; - /// let mut count = 1; - /// - /// for chunk in v.array_chunks_mut() { - /// *chunk = [count; 2]; - /// count += 1; - /// } - /// assert_eq!(v, &[1, 1, 2, 2, 0]); - /// ``` - /// - /// [`chunks_exact_mut`]: slice::chunks_exact_mut - #[unstable(feature = "array_chunks", issue = "74985")] - #[inline] - #[track_caller] - pub fn array_chunks_mut(&mut self) -> ArrayChunksMut<'_, T, N> { - assert!(N != 0, "chunk size must be non-zero"); - ArrayChunksMut::new(self) - } - - /// Returns an iterator over overlapping windows of `N` elements of a slice, - /// starting at the beginning of the slice. - /// - /// This is the const generic equivalent of [`windows`]. - /// - /// If `N` is greater than the size of the slice, it will return no windows. - /// - /// # Panics - /// - /// Panics if `N` is 0. This check will most probably get changed to a compile time - /// error before this method gets stabilized. - /// - /// # Examples - /// - /// ``` - /// #![feature(array_windows)] - /// let slice = [0, 1, 2, 3]; - /// let mut iter = slice.array_windows(); - /// assert_eq!(iter.next().unwrap(), &[0, 1]); - /// assert_eq!(iter.next().unwrap(), &[1, 2]); - /// assert_eq!(iter.next().unwrap(), &[2, 3]); - /// assert!(iter.next().is_none()); - /// ``` - /// - /// [`windows`]: slice::windows - #[unstable(feature = "array_windows", issue = "75027")] - #[inline] - #[track_caller] - pub fn array_windows(&self) -> ArrayWindows<'_, T, N> { - assert!(N != 0, "window size must be non-zero"); - ArrayWindows::new(self) - } - - /// Returns an iterator over `chunk_size` elements of the slice at a time, starting at the end - /// of the slice. - /// - /// The chunks are slices and do not overlap. If `chunk_size` does not divide the length of the - /// slice, then the last chunk will not have length `chunk_size`. - /// - /// See [`rchunks_exact`] for a variant of this iterator that returns chunks of always exactly - /// `chunk_size` elements, and [`chunks`] for the same iterator but starting at the beginning - /// of the slice. - /// - /// # Panics - /// - /// Panics if `chunk_size` is 0. - /// - /// # Examples - /// - /// ``` - /// let slice = ['l', 'o', 'r', 'e', 'm']; - /// let mut iter = slice.rchunks(2); - /// assert_eq!(iter.next().unwrap(), &['e', 'm']); - /// assert_eq!(iter.next().unwrap(), &['o', 'r']); - /// assert_eq!(iter.next().unwrap(), &['l']); - /// assert!(iter.next().is_none()); - /// ``` - /// - /// [`rchunks_exact`]: slice::rchunks_exact - /// [`chunks`]: slice::chunks - #[stable(feature = "rchunks", since = "1.31.0")] - #[inline] - #[track_caller] - pub fn rchunks(&self, chunk_size: usize) -> RChunks<'_, T> { - assert!(chunk_size != 0, "chunk size must be non-zero"); - RChunks::new(self, chunk_size) - } - - /// Returns an iterator over `chunk_size` elements of the slice at a time, starting at the end - /// of the slice. - /// - /// The chunks are mutable slices, and do not overlap. If `chunk_size` does not divide the - /// length of the slice, then the last chunk will not have length `chunk_size`. - /// - /// See [`rchunks_exact_mut`] for a variant of this iterator that returns chunks of always - /// exactly `chunk_size` elements, and [`chunks_mut`] for the same iterator but starting at the - /// beginning of the slice. - /// - /// # Panics - /// - /// Panics if `chunk_size` is 0. - /// - /// # Examples - /// - /// ``` - /// let v = &mut [0, 0, 0, 0, 0]; - /// let mut count = 1; - /// - /// for chunk in v.rchunks_mut(2) { - /// for elem in chunk.iter_mut() { - /// *elem += count; - /// } - /// count += 1; - /// } - /// assert_eq!(v, &[3, 2, 2, 1, 1]); - /// ``` - /// - /// [`rchunks_exact_mut`]: slice::rchunks_exact_mut - /// [`chunks_mut`]: slice::chunks_mut - #[stable(feature = "rchunks", since = "1.31.0")] - #[inline] - #[track_caller] - pub fn rchunks_mut(&mut self, chunk_size: usize) -> RChunksMut<'_, T> { - assert!(chunk_size != 0, "chunk size must be non-zero"); - RChunksMut::new(self, chunk_size) - } - - /// Returns an iterator over `chunk_size` elements of the slice at a time, starting at the - /// end of the slice. - /// - /// The chunks are slices and do not overlap. If `chunk_size` does not divide the length of the - /// slice, then the last up to `chunk_size-1` elements will be omitted and can be retrieved - /// from the `remainder` function of the iterator. - /// - /// Due to each chunk having exactly `chunk_size` elements, the compiler can often optimize the - /// resulting code better than in the case of [`rchunks`]. - /// - /// See [`rchunks`] for a variant of this iterator that also returns the remainder as a smaller - /// chunk, and [`chunks_exact`] for the same iterator but starting at the beginning of the - /// slice. - /// - /// # Panics - /// - /// Panics if `chunk_size` is 0. - /// - /// # Examples - /// - /// ``` - /// let slice = ['l', 'o', 'r', 'e', 'm']; - /// let mut iter = slice.rchunks_exact(2); - /// assert_eq!(iter.next().unwrap(), &['e', 'm']); - /// assert_eq!(iter.next().unwrap(), &['o', 'r']); - /// assert!(iter.next().is_none()); - /// assert_eq!(iter.remainder(), &['l']); - /// ``` - /// - /// [`chunks`]: slice::chunks - /// [`rchunks`]: slice::rchunks - /// [`chunks_exact`]: slice::chunks_exact - #[stable(feature = "rchunks", since = "1.31.0")] - #[inline] - #[track_caller] - pub fn rchunks_exact(&self, chunk_size: usize) -> RChunksExact<'_, T> { - assert!(chunk_size != 0, "chunk size must be non-zero"); - RChunksExact::new(self, chunk_size) - } - - /// Returns an iterator over `chunk_size` elements of the slice at a time, starting at the end - /// of the slice. - /// - /// The chunks are mutable slices, and do not overlap. If `chunk_size` does not divide the - /// length of the slice, then the last up to `chunk_size-1` elements will be omitted and can be - /// retrieved from the `into_remainder` function of the iterator. - /// - /// Due to each chunk having exactly `chunk_size` elements, the compiler can often optimize the - /// resulting code better than in the case of [`chunks_mut`]. - /// - /// See [`rchunks_mut`] for a variant of this iterator that also returns the remainder as a - /// smaller chunk, and [`chunks_exact_mut`] for the same iterator but starting at the beginning - /// of the slice. - /// - /// # Panics - /// - /// Panics if `chunk_size` is 0. - /// - /// # Examples - /// - /// ``` - /// let v = &mut [0, 0, 0, 0, 0]; - /// let mut count = 1; - /// - /// for chunk in v.rchunks_exact_mut(2) { - /// for elem in chunk.iter_mut() { - /// *elem += count; - /// } - /// count += 1; - /// } - /// assert_eq!(v, &[0, 2, 2, 1, 1]); - /// ``` - /// - /// [`chunks_mut`]: slice::chunks_mut - /// [`rchunks_mut`]: slice::rchunks_mut - /// [`chunks_exact_mut`]: slice::chunks_exact_mut - #[stable(feature = "rchunks", since = "1.31.0")] - #[inline] - #[track_caller] - pub fn rchunks_exact_mut(&mut self, chunk_size: usize) -> RChunksExactMut<'_, T> { - assert!(chunk_size != 0, "chunk size must be non-zero"); - RChunksExactMut::new(self, chunk_size) - } - - /// Returns an iterator over the slice producing non-overlapping runs - /// of elements using the predicate to separate them. - /// - /// The predicate is called for every pair of consecutive elements, - /// meaning that it is called on `slice[0]` and `slice[1]`, - /// followed by `slice[1]` and `slice[2]`, and so on. - /// - /// # Examples - /// - /// ``` - /// let slice = &[1, 1, 1, 3, 3, 2, 2, 2]; - /// - /// let mut iter = slice.chunk_by(|a, b| a == b); - /// - /// assert_eq!(iter.next(), Some(&[1, 1, 1][..])); - /// assert_eq!(iter.next(), Some(&[3, 3][..])); - /// assert_eq!(iter.next(), Some(&[2, 2, 2][..])); - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// This method can be used to extract the sorted subslices: - /// - /// ``` - /// let slice = &[1, 1, 2, 3, 2, 3, 2, 3, 4]; - /// - /// let mut iter = slice.chunk_by(|a, b| a <= b); - /// - /// assert_eq!(iter.next(), Some(&[1, 1, 2, 3][..])); - /// assert_eq!(iter.next(), Some(&[2, 3][..])); - /// assert_eq!(iter.next(), Some(&[2, 3, 4][..])); - /// assert_eq!(iter.next(), None); - /// ``` - #[stable(feature = "slice_group_by", since = "1.77.0")] - #[inline] - pub fn chunk_by(&self, pred: F) -> ChunkBy<'_, T, F> - where - F: FnMut(&T, &T) -> bool, - { - ChunkBy::new(self, pred) - } - - /// Returns an iterator over the slice producing non-overlapping mutable - /// runs of elements using the predicate to separate them. - /// - /// The predicate is called for every pair of consecutive elements, - /// meaning that it is called on `slice[0]` and `slice[1]`, - /// followed by `slice[1]` and `slice[2]`, and so on. - /// - /// # Examples - /// - /// ``` - /// let slice = &mut [1, 1, 1, 3, 3, 2, 2, 2]; - /// - /// let mut iter = slice.chunk_by_mut(|a, b| a == b); - /// - /// assert_eq!(iter.next(), Some(&mut [1, 1, 1][..])); - /// assert_eq!(iter.next(), Some(&mut [3, 3][..])); - /// assert_eq!(iter.next(), Some(&mut [2, 2, 2][..])); - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// This method can be used to extract the sorted subslices: - /// - /// ``` - /// let slice = &mut [1, 1, 2, 3, 2, 3, 2, 3, 4]; - /// - /// let mut iter = slice.chunk_by_mut(|a, b| a <= b); - /// - /// assert_eq!(iter.next(), Some(&mut [1, 1, 2, 3][..])); - /// assert_eq!(iter.next(), Some(&mut [2, 3][..])); - /// assert_eq!(iter.next(), Some(&mut [2, 3, 4][..])); - /// assert_eq!(iter.next(), None); - /// ``` - #[stable(feature = "slice_group_by", since = "1.77.0")] - #[inline] - pub fn chunk_by_mut(&mut self, pred: F) -> ChunkByMut<'_, T, F> - where - F: FnMut(&T, &T) -> bool, - { - ChunkByMut::new(self, pred) - } - - /// Divides one slice into two at an index. - /// - /// The first will contain all indices from `[0, mid)` (excluding - /// the index `mid` itself) and the second will contain all - /// indices from `[mid, len)` (excluding the index `len` itself). - /// - /// # Panics - /// - /// Panics if `mid > len`. For a non-panicking alternative see - /// [`split_at_checked`](slice::split_at_checked). - /// - /// # Examples - /// - /// ``` - /// let v = [1, 2, 3, 4, 5, 6]; - /// - /// { - /// let (left, right) = v.split_at(0); - /// assert_eq!(left, []); - /// assert_eq!(right, [1, 2, 3, 4, 5, 6]); - /// } - /// - /// { - /// let (left, right) = v.split_at(2); - /// assert_eq!(left, [1, 2]); - /// assert_eq!(right, [3, 4, 5, 6]); - /// } - /// - /// { - /// let (left, right) = v.split_at(6); - /// assert_eq!(left, [1, 2, 3, 4, 5, 6]); - /// assert_eq!(right, []); - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_slice_split_at_not_mut", since = "1.71.0")] - #[rustc_allow_const_fn_unstable(split_at_checked)] - #[inline] - #[track_caller] - #[must_use] - pub const fn split_at(&self, mid: usize) -> (&[T], &[T]) { - match self.split_at_checked(mid) { - Some(pair) => pair, - None => panic!("mid > len"), - } - } - - /// Divides one mutable slice into two at an index. - /// - /// The first will contain all indices from `[0, mid)` (excluding - /// the index `mid` itself) and the second will contain all - /// indices from `[mid, len)` (excluding the index `len` itself). - /// - /// # Panics - /// - /// Panics if `mid > len`. For a non-panicking alternative see - /// [`split_at_mut_checked`](slice::split_at_mut_checked). - /// - /// # Examples - /// - /// ``` - /// let mut v = [1, 0, 3, 0, 5, 6]; - /// let (left, right) = v.split_at_mut(2); - /// assert_eq!(left, [1, 0]); - /// assert_eq!(right, [3, 0, 5, 6]); - /// left[1] = 2; - /// right[1] = 4; - /// assert_eq!(v, [1, 2, 3, 4, 5, 6]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - #[track_caller] - #[must_use] - #[rustc_const_unstable(feature = "const_slice_split_at_mut", issue = "101804")] - pub const fn split_at_mut(&mut self, mid: usize) -> (&mut [T], &mut [T]) { - match self.split_at_mut_checked(mid) { - Some(pair) => pair, - None => panic!("mid > len"), - } - } - - /// Divides one slice into two at an index, without doing bounds checking. - /// - /// The first will contain all indices from `[0, mid)` (excluding - /// the index `mid` itself) and the second will contain all - /// indices from `[mid, len)` (excluding the index `len` itself). - /// - /// For a safe alternative see [`split_at`]. - /// - /// # Safety - /// - /// Calling this method with an out-of-bounds index is *[undefined behavior]* - /// even if the resulting reference is not used. The caller has to ensure that - /// `0 <= mid <= self.len()`. - /// - /// [`split_at`]: slice::split_at - /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html - /// - /// # Examples - /// - /// ``` - /// let v = [1, 2, 3, 4, 5, 6]; - /// - /// unsafe { - /// let (left, right) = v.split_at_unchecked(0); - /// assert_eq!(left, []); - /// assert_eq!(right, [1, 2, 3, 4, 5, 6]); - /// } - /// - /// unsafe { - /// let (left, right) = v.split_at_unchecked(2); - /// assert_eq!(left, [1, 2]); - /// assert_eq!(right, [3, 4, 5, 6]); - /// } - /// - /// unsafe { - /// let (left, right) = v.split_at_unchecked(6); - /// assert_eq!(left, [1, 2, 3, 4, 5, 6]); - /// assert_eq!(right, []); - /// } - /// ``` - #[stable(feature = "slice_split_at_unchecked", since = "1.79.0")] - #[rustc_const_stable(feature = "const_slice_split_at_unchecked", since = "1.77.0")] - #[inline] - #[must_use] - pub const unsafe fn split_at_unchecked(&self, mid: usize) -> (&[T], &[T]) { - // HACK: the const function `from_raw_parts` is used to make this - // function const; previously the implementation used - // `(self.get_unchecked(..mid), self.get_unchecked(mid..))` - - let len = self.len(); - let ptr = self.as_ptr(); - - assert_unsafe_precondition!( - check_library_ub, - "slice::split_at_unchecked requires the index to be within the slice", - (mid: usize = mid, len: usize = len) => mid <= len, - ); - - // SAFETY: Caller has to check that `0 <= mid <= self.len()` - unsafe { (from_raw_parts(ptr, mid), from_raw_parts(ptr.add(mid), unchecked_sub(len, mid))) } - } - - /// Divides one mutable slice into two at an index, without doing bounds checking. - /// - /// The first will contain all indices from `[0, mid)` (excluding - /// the index `mid` itself) and the second will contain all - /// indices from `[mid, len)` (excluding the index `len` itself). - /// - /// For a safe alternative see [`split_at_mut`]. - /// - /// # Safety - /// - /// Calling this method with an out-of-bounds index is *[undefined behavior]* - /// even if the resulting reference is not used. The caller has to ensure that - /// `0 <= mid <= self.len()`. - /// - /// [`split_at_mut`]: slice::split_at_mut - /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html - /// - /// # Examples - /// - /// ``` - /// let mut v = [1, 0, 3, 0, 5, 6]; - /// // scoped to restrict the lifetime of the borrows - /// unsafe { - /// let (left, right) = v.split_at_mut_unchecked(2); - /// assert_eq!(left, [1, 0]); - /// assert_eq!(right, [3, 0, 5, 6]); - /// left[1] = 2; - /// right[1] = 4; - /// } - /// assert_eq!(v, [1, 2, 3, 4, 5, 6]); - /// ``` - #[stable(feature = "slice_split_at_unchecked", since = "1.79.0")] - #[rustc_const_unstable(feature = "const_slice_split_at_mut", issue = "101804")] - #[inline] - #[must_use] - pub const unsafe fn split_at_mut_unchecked(&mut self, mid: usize) -> (&mut [T], &mut [T]) { - let len = self.len(); - let ptr = self.as_mut_ptr(); - - assert_unsafe_precondition!( - check_library_ub, - "slice::split_at_mut_unchecked requires the index to be within the slice", - (mid: usize = mid, len: usize = len) => mid <= len, - ); - - // SAFETY: Caller has to check that `0 <= mid <= self.len()`. - // - // `[ptr; mid]` and `[mid; len]` are not overlapping, so returning a mutable reference - // is fine. - unsafe { - ( - from_raw_parts_mut(ptr, mid), - from_raw_parts_mut(ptr.add(mid), unchecked_sub(len, mid)), - ) - } - } - - /// Divides one slice into two at an index, returning `None` if the slice is - /// too short. - /// - /// If `mid ≤ len` returns a pair of slices where the first will contain all - /// indices from `[0, mid)` (excluding the index `mid` itself) and the - /// second will contain all indices from `[mid, len)` (excluding the index - /// `len` itself). - /// - /// Otherwise, if `mid > len`, returns `None`. - /// - /// # Examples - /// - /// ``` - /// let v = [1, -2, 3, -4, 5, -6]; - /// - /// { - /// let (left, right) = v.split_at_checked(0).unwrap(); - /// assert_eq!(left, []); - /// assert_eq!(right, [1, -2, 3, -4, 5, -6]); - /// } - /// - /// { - /// let (left, right) = v.split_at_checked(2).unwrap(); - /// assert_eq!(left, [1, -2]); - /// assert_eq!(right, [3, -4, 5, -6]); - /// } - /// - /// { - /// let (left, right) = v.split_at_checked(6).unwrap(); - /// assert_eq!(left, [1, -2, 3, -4, 5, -6]); - /// assert_eq!(right, []); - /// } - /// - /// assert_eq!(None, v.split_at_checked(7)); - /// ``` - #[stable(feature = "split_at_checked", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_stable(feature = "split_at_checked", since = "CURRENT_RUSTC_VERSION")] - #[inline] - #[must_use] - pub const fn split_at_checked(&self, mid: usize) -> Option<(&[T], &[T])> { - if mid <= self.len() { - // SAFETY: `[ptr; mid]` and `[mid; len]` are inside `self`, which - // fulfills the requirements of `split_at_unchecked`. - Some(unsafe { self.split_at_unchecked(mid) }) - } else { - None - } - } - - /// Divides one mutable slice into two at an index, returning `None` if the - /// slice is too short. - /// - /// If `mid ≤ len` returns a pair of slices where the first will contain all - /// indices from `[0, mid)` (excluding the index `mid` itself) and the - /// second will contain all indices from `[mid, len)` (excluding the index - /// `len` itself). - /// - /// Otherwise, if `mid > len`, returns `None`. - /// - /// # Examples - /// - /// ``` - /// let mut v = [1, 0, 3, 0, 5, 6]; - /// - /// if let Some((left, right)) = v.split_at_mut_checked(2) { - /// assert_eq!(left, [1, 0]); - /// assert_eq!(right, [3, 0, 5, 6]); - /// left[1] = 2; - /// right[1] = 4; - /// } - /// assert_eq!(v, [1, 2, 3, 4, 5, 6]); - /// - /// assert_eq!(None, v.split_at_mut_checked(7)); - /// ``` - #[stable(feature = "split_at_checked", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_unstable(feature = "const_slice_split_at_mut", issue = "101804")] - #[inline] - #[must_use] - pub const fn split_at_mut_checked(&mut self, mid: usize) -> Option<(&mut [T], &mut [T])> { - if mid <= self.len() { - // SAFETY: `[ptr; mid]` and `[mid; len]` are inside `self`, which - // fulfills the requirements of `split_at_unchecked`. - Some(unsafe { self.split_at_mut_unchecked(mid) }) - } else { - None - } - } - - /// Returns an iterator over subslices separated by elements that match - /// `pred`. The matched element is not contained in the subslices. - /// - /// # Examples - /// - /// ``` - /// let slice = [10, 40, 33, 20]; - /// let mut iter = slice.split(|num| num % 3 == 0); - /// - /// assert_eq!(iter.next().unwrap(), &[10, 40]); - /// assert_eq!(iter.next().unwrap(), &[20]); - /// assert!(iter.next().is_none()); - /// ``` - /// - /// If the first element is matched, an empty slice will be the first item - /// returned by the iterator. Similarly, if the last element in the slice - /// is matched, an empty slice will be the last item returned by the - /// iterator: - /// - /// ``` - /// let slice = [10, 40, 33]; - /// let mut iter = slice.split(|num| num % 3 == 0); - /// - /// assert_eq!(iter.next().unwrap(), &[10, 40]); - /// assert_eq!(iter.next().unwrap(), &[]); - /// assert!(iter.next().is_none()); - /// ``` - /// - /// If two matched elements are directly adjacent, an empty slice will be - /// present between them: - /// - /// ``` - /// let slice = [10, 6, 33, 20]; - /// let mut iter = slice.split(|num| num % 3 == 0); - /// - /// assert_eq!(iter.next().unwrap(), &[10]); - /// assert_eq!(iter.next().unwrap(), &[]); - /// assert_eq!(iter.next().unwrap(), &[20]); - /// assert!(iter.next().is_none()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn split(&self, pred: F) -> Split<'_, T, F> - where - F: FnMut(&T) -> bool, - { - Split::new(self, pred) - } - - /// Returns an iterator over mutable subslices separated by elements that - /// match `pred`. The matched element is not contained in the subslices. - /// - /// # Examples - /// - /// ``` - /// let mut v = [10, 40, 30, 20, 60, 50]; - /// - /// for group in v.split_mut(|num| *num % 3 == 0) { - /// group[0] = 1; - /// } - /// assert_eq!(v, [1, 40, 30, 1, 60, 1]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn split_mut(&mut self, pred: F) -> SplitMut<'_, T, F> - where - F: FnMut(&T) -> bool, - { - SplitMut::new(self, pred) - } - - /// Returns an iterator over subslices separated by elements that match - /// `pred`. The matched element is contained in the end of the previous - /// subslice as a terminator. - /// - /// # Examples - /// - /// ``` - /// let slice = [10, 40, 33, 20]; - /// let mut iter = slice.split_inclusive(|num| num % 3 == 0); - /// - /// assert_eq!(iter.next().unwrap(), &[10, 40, 33]); - /// assert_eq!(iter.next().unwrap(), &[20]); - /// assert!(iter.next().is_none()); - /// ``` - /// - /// If the last element of the slice is matched, - /// that element will be considered the terminator of the preceding slice. - /// That slice will be the last item returned by the iterator. - /// - /// ``` - /// let slice = [3, 10, 40, 33]; - /// let mut iter = slice.split_inclusive(|num| num % 3 == 0); - /// - /// assert_eq!(iter.next().unwrap(), &[3]); - /// assert_eq!(iter.next().unwrap(), &[10, 40, 33]); - /// assert!(iter.next().is_none()); - /// ``` - #[stable(feature = "split_inclusive", since = "1.51.0")] - #[inline] - pub fn split_inclusive(&self, pred: F) -> SplitInclusive<'_, T, F> - where - F: FnMut(&T) -> bool, - { - SplitInclusive::new(self, pred) - } - - /// Returns an iterator over mutable subslices separated by elements that - /// match `pred`. The matched element is contained in the previous - /// subslice as a terminator. - /// - /// # Examples - /// - /// ``` - /// let mut v = [10, 40, 30, 20, 60, 50]; - /// - /// for group in v.split_inclusive_mut(|num| *num % 3 == 0) { - /// let terminator_idx = group.len()-1; - /// group[terminator_idx] = 1; - /// } - /// assert_eq!(v, [10, 40, 1, 20, 1, 1]); - /// ``` - #[stable(feature = "split_inclusive", since = "1.51.0")] - #[inline] - pub fn split_inclusive_mut(&mut self, pred: F) -> SplitInclusiveMut<'_, T, F> - where - F: FnMut(&T) -> bool, - { - SplitInclusiveMut::new(self, pred) - } - - /// Returns an iterator over subslices separated by elements that match - /// `pred`, starting at the end of the slice and working backwards. - /// The matched element is not contained in the subslices. - /// - /// # Examples - /// - /// ``` - /// let slice = [11, 22, 33, 0, 44, 55]; - /// let mut iter = slice.rsplit(|num| *num == 0); - /// - /// assert_eq!(iter.next().unwrap(), &[44, 55]); - /// assert_eq!(iter.next().unwrap(), &[11, 22, 33]); - /// assert_eq!(iter.next(), None); - /// ``` - /// - /// As with `split()`, if the first or last element is matched, an empty - /// slice will be the first (or last) item returned by the iterator. - /// - /// ``` - /// let v = &[0, 1, 1, 2, 3, 5, 8]; - /// let mut it = v.rsplit(|n| *n % 2 == 0); - /// assert_eq!(it.next().unwrap(), &[]); - /// assert_eq!(it.next().unwrap(), &[3, 5]); - /// assert_eq!(it.next().unwrap(), &[1, 1]); - /// assert_eq!(it.next().unwrap(), &[]); - /// assert_eq!(it.next(), None); - /// ``` - #[stable(feature = "slice_rsplit", since = "1.27.0")] - #[inline] - pub fn rsplit(&self, pred: F) -> RSplit<'_, T, F> - where - F: FnMut(&T) -> bool, - { - RSplit::new(self, pred) - } - - /// Returns an iterator over mutable subslices separated by elements that - /// match `pred`, starting at the end of the slice and working - /// backwards. The matched element is not contained in the subslices. - /// - /// # Examples - /// - /// ``` - /// let mut v = [100, 400, 300, 200, 600, 500]; - /// - /// let mut count = 0; - /// for group in v.rsplit_mut(|num| *num % 3 == 0) { - /// count += 1; - /// group[0] = count; - /// } - /// assert_eq!(v, [3, 400, 300, 2, 600, 1]); - /// ``` - /// - #[stable(feature = "slice_rsplit", since = "1.27.0")] - #[inline] - pub fn rsplit_mut(&mut self, pred: F) -> RSplitMut<'_, T, F> - where - F: FnMut(&T) -> bool, - { - RSplitMut::new(self, pred) - } - - /// Returns an iterator over subslices separated by elements that match - /// `pred`, limited to returning at most `n` items. The matched element is - /// not contained in the subslices. - /// - /// The last element returned, if any, will contain the remainder of the - /// slice. - /// - /// # Examples - /// - /// Print the slice split once by numbers divisible by 3 (i.e., `[10, 40]`, - /// `[20, 60, 50]`): - /// - /// ``` - /// let v = [10, 40, 30, 20, 60, 50]; - /// - /// for group in v.splitn(2, |num| *num % 3 == 0) { - /// println!("{group:?}"); - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn splitn(&self, n: usize, pred: F) -> SplitN<'_, T, F> - where - F: FnMut(&T) -> bool, - { - SplitN::new(self.split(pred), n) - } - - /// Returns an iterator over mutable subslices separated by elements that match - /// `pred`, limited to returning at most `n` items. The matched element is - /// not contained in the subslices. - /// - /// The last element returned, if any, will contain the remainder of the - /// slice. - /// - /// # Examples - /// - /// ``` - /// let mut v = [10, 40, 30, 20, 60, 50]; - /// - /// for group in v.splitn_mut(2, |num| *num % 3 == 0) { - /// group[0] = 1; - /// } - /// assert_eq!(v, [1, 40, 30, 1, 60, 50]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn splitn_mut(&mut self, n: usize, pred: F) -> SplitNMut<'_, T, F> - where - F: FnMut(&T) -> bool, - { - SplitNMut::new(self.split_mut(pred), n) - } - - /// Returns an iterator over subslices separated by elements that match - /// `pred` limited to returning at most `n` items. This starts at the end of - /// the slice and works backwards. The matched element is not contained in - /// the subslices. - /// - /// The last element returned, if any, will contain the remainder of the - /// slice. - /// - /// # Examples - /// - /// Print the slice split once, starting from the end, by numbers divisible - /// by 3 (i.e., `[50]`, `[10, 40, 30, 20]`): - /// - /// ``` - /// let v = [10, 40, 30, 20, 60, 50]; - /// - /// for group in v.rsplitn(2, |num| *num % 3 == 0) { - /// println!("{group:?}"); - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn rsplitn(&self, n: usize, pred: F) -> RSplitN<'_, T, F> - where - F: FnMut(&T) -> bool, - { - RSplitN::new(self.rsplit(pred), n) - } - - /// Returns an iterator over subslices separated by elements that match - /// `pred` limited to returning at most `n` items. This starts at the end of - /// the slice and works backwards. The matched element is not contained in - /// the subslices. - /// - /// The last element returned, if any, will contain the remainder of the - /// slice. - /// - /// # Examples - /// - /// ``` - /// let mut s = [10, 40, 30, 20, 60, 50]; - /// - /// for group in s.rsplitn_mut(2, |num| *num % 3 == 0) { - /// group[0] = 1; - /// } - /// assert_eq!(s, [1, 40, 30, 20, 60, 1]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn rsplitn_mut(&mut self, n: usize, pred: F) -> RSplitNMut<'_, T, F> - where - F: FnMut(&T) -> bool, - { - RSplitNMut::new(self.rsplit_mut(pred), n) - } - - /// Splits the slice on the first element that matches the specified - /// predicate. - /// - /// If any matching elements are present in the slice, returns the prefix - /// before the match and suffix after. The matching element itself is not - /// included. If no elements match, returns `None`. - /// - /// # Examples - /// - /// ``` - /// #![feature(slice_split_once)] - /// let s = [1, 2, 3, 2, 4]; - /// assert_eq!(s.split_once(|&x| x == 2), Some(( - /// &[1][..], - /// &[3, 2, 4][..] - /// ))); - /// assert_eq!(s.split_once(|&x| x == 0), None); - /// ``` - #[unstable(feature = "slice_split_once", reason = "newly added", issue = "112811")] - #[inline] - pub fn split_once(&self, pred: F) -> Option<(&[T], &[T])> - where - F: FnMut(&T) -> bool, - { - let index = self.iter().position(pred)?; - Some((&self[..index], &self[index + 1..])) - } - - /// Splits the slice on the last element that matches the specified - /// predicate. - /// - /// If any matching elements are present in the slice, returns the prefix - /// before the match and suffix after. The matching element itself is not - /// included. If no elements match, returns `None`. - /// - /// # Examples - /// - /// ``` - /// #![feature(slice_split_once)] - /// let s = [1, 2, 3, 2, 4]; - /// assert_eq!(s.rsplit_once(|&x| x == 2), Some(( - /// &[1, 2, 3][..], - /// &[4][..] - /// ))); - /// assert_eq!(s.rsplit_once(|&x| x == 0), None); - /// ``` - #[unstable(feature = "slice_split_once", reason = "newly added", issue = "112811")] - #[inline] - pub fn rsplit_once(&self, pred: F) -> Option<(&[T], &[T])> - where - F: FnMut(&T) -> bool, - { - let index = self.iter().rposition(pred)?; - Some((&self[..index], &self[index + 1..])) - } - - /// Returns `true` if the slice contains an element with the given value. - /// - /// This operation is *O*(*n*). - /// - /// Note that if you have a sorted slice, [`binary_search`] may be faster. - /// - /// [`binary_search`]: slice::binary_search - /// - /// # Examples - /// - /// ``` - /// let v = [10, 40, 30]; - /// assert!(v.contains(&30)); - /// assert!(!v.contains(&50)); - /// ``` - /// - /// If you do not have a `&T`, but some other value that you can compare - /// with one (for example, `String` implements `PartialEq`), you can - /// use `iter().any`: - /// - /// ``` - /// let v = [String::from("hello"), String::from("world")]; // slice of `String` - /// assert!(v.iter().any(|e| e == "hello")); // search with `&str` - /// assert!(!v.iter().any(|e| e == "hi")); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - #[must_use] - pub fn contains(&self, x: &T) -> bool - where - T: PartialEq, - { - cmp::SliceContains::slice_contains(x, self) - } - - /// Returns `true` if `needle` is a prefix of the slice or equal to the slice. - /// - /// # Examples - /// - /// ``` - /// let v = [10, 40, 30]; - /// assert!(v.starts_with(&[10])); - /// assert!(v.starts_with(&[10, 40])); - /// assert!(v.starts_with(&v)); - /// assert!(!v.starts_with(&[50])); - /// assert!(!v.starts_with(&[10, 50])); - /// ``` - /// - /// Always returns `true` if `needle` is an empty slice: - /// - /// ``` - /// let v = &[10, 40, 30]; - /// assert!(v.starts_with(&[])); - /// let v: &[u8] = &[]; - /// assert!(v.starts_with(&[])); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - pub fn starts_with(&self, needle: &[T]) -> bool - where - T: PartialEq, - { - let n = needle.len(); - self.len() >= n && needle == &self[..n] - } - - /// Returns `true` if `needle` is a suffix of the slice or equal to the slice. - /// - /// # Examples - /// - /// ``` - /// let v = [10, 40, 30]; - /// assert!(v.ends_with(&[30])); - /// assert!(v.ends_with(&[40, 30])); - /// assert!(v.ends_with(&v)); - /// assert!(!v.ends_with(&[50])); - /// assert!(!v.ends_with(&[50, 30])); - /// ``` - /// - /// Always returns `true` if `needle` is an empty slice: - /// - /// ``` - /// let v = &[10, 40, 30]; - /// assert!(v.ends_with(&[])); - /// let v: &[u8] = &[]; - /// assert!(v.ends_with(&[])); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - pub fn ends_with(&self, needle: &[T]) -> bool - where - T: PartialEq, - { - let (m, n) = (self.len(), needle.len()); - m >= n && needle == &self[m - n..] - } - - /// Returns a subslice with the prefix removed. - /// - /// If the slice starts with `prefix`, returns the subslice after the prefix, wrapped in `Some`. - /// If `prefix` is empty, simply returns the original slice. If `prefix` is equal to the - /// original slice, returns an empty slice. - /// - /// If the slice does not start with `prefix`, returns `None`. - /// - /// # Examples - /// - /// ``` - /// let v = &[10, 40, 30]; - /// assert_eq!(v.strip_prefix(&[10]), Some(&[40, 30][..])); - /// assert_eq!(v.strip_prefix(&[10, 40]), Some(&[30][..])); - /// assert_eq!(v.strip_prefix(&[10, 40, 30]), Some(&[][..])); - /// assert_eq!(v.strip_prefix(&[50]), None); - /// assert_eq!(v.strip_prefix(&[10, 50]), None); - /// - /// let prefix : &str = "he"; - /// assert_eq!(b"hello".strip_prefix(prefix.as_bytes()), - /// Some(b"llo".as_ref())); - /// ``` - #[must_use = "returns the subslice without modifying the original"] - #[stable(feature = "slice_strip", since = "1.51.0")] - pub fn strip_prefix + ?Sized>(&self, prefix: &P) -> Option<&[T]> - where - T: PartialEq, - { - // This function will need rewriting if and when SlicePattern becomes more sophisticated. - let prefix = prefix.as_slice(); - let n = prefix.len(); - if n <= self.len() { - let (head, tail) = self.split_at(n); - if head == prefix { - return Some(tail); - } - } - None - } - - /// Returns a subslice with the suffix removed. - /// - /// If the slice ends with `suffix`, returns the subslice before the suffix, wrapped in `Some`. - /// If `suffix` is empty, simply returns the original slice. If `suffix` is equal to the - /// original slice, returns an empty slice. - /// - /// If the slice does not end with `suffix`, returns `None`. - /// - /// # Examples - /// - /// ``` - /// let v = &[10, 40, 30]; - /// assert_eq!(v.strip_suffix(&[30]), Some(&[10, 40][..])); - /// assert_eq!(v.strip_suffix(&[40, 30]), Some(&[10][..])); - /// assert_eq!(v.strip_suffix(&[10, 40, 30]), Some(&[][..])); - /// assert_eq!(v.strip_suffix(&[50]), None); - /// assert_eq!(v.strip_suffix(&[50, 30]), None); - /// ``` - #[must_use = "returns the subslice without modifying the original"] - #[stable(feature = "slice_strip", since = "1.51.0")] - pub fn strip_suffix + ?Sized>(&self, suffix: &P) -> Option<&[T]> - where - T: PartialEq, - { - // This function will need rewriting if and when SlicePattern becomes more sophisticated. - let suffix = suffix.as_slice(); - let (len, n) = (self.len(), suffix.len()); - if n <= len { - let (head, tail) = self.split_at(len - n); - if tail == suffix { - return Some(head); - } - } - None - } - - /// Binary searches this slice for a given element. - /// If the slice is not sorted, the returned result is unspecified and - /// meaningless. - /// - /// If the value is found then [`Result::Ok`] is returned, containing the - /// index of the matching element. If there are multiple matches, then any - /// one of the matches could be returned. The index is chosen - /// deterministically, but is subject to change in future versions of Rust. - /// If the value is not found then [`Result::Err`] is returned, containing - /// the index where a matching element could be inserted while maintaining - /// sorted order. - /// - /// See also [`binary_search_by`], [`binary_search_by_key`], and [`partition_point`]. - /// - /// [`binary_search_by`]: slice::binary_search_by - /// [`binary_search_by_key`]: slice::binary_search_by_key - /// [`partition_point`]: slice::partition_point - /// - /// # Examples - /// - /// Looks up a series of four elements. The first is found, with a - /// uniquely determined position; the second and third are not - /// found; the fourth could match any position in `[1, 4]`. - /// - /// ``` - /// let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]; - /// - /// assert_eq!(s.binary_search(&13), Ok(9)); - /// assert_eq!(s.binary_search(&4), Err(7)); - /// assert_eq!(s.binary_search(&100), Err(13)); - /// let r = s.binary_search(&1); - /// assert!(match r { Ok(1..=4) => true, _ => false, }); - /// ``` - /// - /// If you want to find that whole *range* of matching items, rather than - /// an arbitrary matching one, that can be done using [`partition_point`]: - /// ``` - /// let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]; - /// - /// let low = s.partition_point(|x| x < &1); - /// assert_eq!(low, 1); - /// let high = s.partition_point(|x| x <= &1); - /// assert_eq!(high, 5); - /// let r = s.binary_search(&1); - /// assert!((low..high).contains(&r.unwrap())); - /// - /// assert!(s[..low].iter().all(|&x| x < 1)); - /// assert!(s[low..high].iter().all(|&x| x == 1)); - /// assert!(s[high..].iter().all(|&x| x > 1)); - /// - /// // For something not found, the "range" of equal items is empty - /// assert_eq!(s.partition_point(|x| x < &11), 9); - /// assert_eq!(s.partition_point(|x| x <= &11), 9); - /// assert_eq!(s.binary_search(&11), Err(9)); - /// ``` - /// - /// If you want to insert an item to a sorted vector, while maintaining - /// sort order, consider using [`partition_point`]: - /// - /// ``` - /// let mut s = vec![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]; - /// let num = 42; - /// let idx = s.partition_point(|&x| x <= num); - /// // If `num` is unique, `s.partition_point(|&x| x < num)` (with `<`) is equivalent to - /// // `s.binary_search(&num).unwrap_or_else(|x| x)`, but using `<=` will allow `insert` - /// // to shift less elements. - /// s.insert(idx, num); - /// assert_eq!(s, [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 42, 55]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn binary_search(&self, x: &T) -> Result - where - T: Ord, - { - self.binary_search_by(|p| p.cmp(x)) - } - - /// Binary searches this slice with a comparator function. - /// - /// The comparator function should return an order code that indicates - /// whether its argument is `Less`, `Equal` or `Greater` the desired - /// target. - /// If the slice is not sorted or if the comparator function does not - /// implement an order consistent with the sort order of the underlying - /// slice, the returned result is unspecified and meaningless. - /// - /// If the value is found then [`Result::Ok`] is returned, containing the - /// index of the matching element. If there are multiple matches, then any - /// one of the matches could be returned. The index is chosen - /// deterministically, but is subject to change in future versions of Rust. - /// If the value is not found then [`Result::Err`] is returned, containing - /// the index where a matching element could be inserted while maintaining - /// sorted order. - /// - /// See also [`binary_search`], [`binary_search_by_key`], and [`partition_point`]. - /// - /// [`binary_search`]: slice::binary_search - /// [`binary_search_by_key`]: slice::binary_search_by_key - /// [`partition_point`]: slice::partition_point - /// - /// # Examples - /// - /// Looks up a series of four elements. The first is found, with a - /// uniquely determined position; the second and third are not - /// found; the fourth could match any position in `[1, 4]`. - /// - /// ``` - /// let s = [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]; - /// - /// let seek = 13; - /// assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Ok(9)); - /// let seek = 4; - /// assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Err(7)); - /// let seek = 100; - /// assert_eq!(s.binary_search_by(|probe| probe.cmp(&seek)), Err(13)); - /// let seek = 1; - /// let r = s.binary_search_by(|probe| probe.cmp(&seek)); - /// assert!(match r { Ok(1..=4) => true, _ => false, }); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn binary_search_by<'a, F>(&'a self, mut f: F) -> Result - where - F: FnMut(&'a T) -> Ordering, - { - // INVARIANTS: - // - 0 <= left <= left + size = right <= self.len() - // - f returns Less for everything in self[..left] - // - f returns Greater for everything in self[right..] - let mut size = self.len(); - let mut left = 0; - let mut right = size; - while left < right { - let mid = left + size / 2; - - // SAFETY: the while condition means `size` is strictly positive, so - // `size/2 < size`. Thus `left + size/2 < left + size`, which - // coupled with the `left + size <= self.len()` invariant means - // we have `left + size/2 < self.len()`, and this is in-bounds. - let cmp = f(unsafe { self.get_unchecked(mid) }); - - // This control flow produces conditional moves, which results in - // fewer branches and instructions than if/else or matching on - // cmp::Ordering. - // This is x86 asm for u8: https://rust.godbolt.org/z/698eYffTx. - left = if cmp == Less { mid + 1 } else { left }; - right = if cmp == Greater { mid } else { right }; - if cmp == Equal { - // SAFETY: same as the `get_unchecked` above - unsafe { hint::assert_unchecked(mid < self.len()) }; - return Ok(mid); - } - - size = right - left; - } - - // SAFETY: directly true from the overall invariant. - // Note that this is `<=`, unlike the assume in the `Ok` path. - unsafe { hint::assert_unchecked(left <= self.len()) }; - Err(left) - } - - /// Binary searches this slice with a key extraction function. - /// - /// Assumes that the slice is sorted by the key, for instance with - /// [`sort_by_key`] using the same key extraction function. - /// If the slice is not sorted by the key, the returned result is - /// unspecified and meaningless. - /// - /// If the value is found then [`Result::Ok`] is returned, containing the - /// index of the matching element. If there are multiple matches, then any - /// one of the matches could be returned. The index is chosen - /// deterministically, but is subject to change in future versions of Rust. - /// If the value is not found then [`Result::Err`] is returned, containing - /// the index where a matching element could be inserted while maintaining - /// sorted order. - /// - /// See also [`binary_search`], [`binary_search_by`], and [`partition_point`]. - /// - /// [`sort_by_key`]: slice::sort_by_key - /// [`binary_search`]: slice::binary_search - /// [`binary_search_by`]: slice::binary_search_by - /// [`partition_point`]: slice::partition_point - /// - /// # Examples - /// - /// Looks up a series of four elements in a slice of pairs sorted by - /// their second elements. The first is found, with a uniquely - /// determined position; the second and third are not found; the - /// fourth could match any position in `[1, 4]`. - /// - /// ``` - /// let s = [(0, 0), (2, 1), (4, 1), (5, 1), (3, 1), - /// (1, 2), (2, 3), (4, 5), (5, 8), (3, 13), - /// (1, 21), (2, 34), (4, 55)]; - /// - /// assert_eq!(s.binary_search_by_key(&13, |&(a, b)| b), Ok(9)); - /// assert_eq!(s.binary_search_by_key(&4, |&(a, b)| b), Err(7)); - /// assert_eq!(s.binary_search_by_key(&100, |&(a, b)| b), Err(13)); - /// let r = s.binary_search_by_key(&1, |&(a, b)| b); - /// assert!(match r { Ok(1..=4) => true, _ => false, }); - /// ``` - // Lint rustdoc::broken_intra_doc_links is allowed as `slice::sort_by_key` is - // in crate `alloc`, and as such doesn't exists yet when building `core`: #74481. - // This breaks links when slice is displayed in core, but changing it to use relative links - // would break when the item is re-exported. So allow the core links to be broken for now. - #[allow(rustdoc::broken_intra_doc_links)] - #[stable(feature = "slice_binary_search_by_key", since = "1.10.0")] - #[inline] - pub fn binary_search_by_key<'a, B, F>(&'a self, b: &B, mut f: F) -> Result - where - F: FnMut(&'a T) -> B, - B: Ord, - { - self.binary_search_by(|k| f(k).cmp(b)) - } - - /// Sorts the slice, but might not preserve the order of equal elements. - /// - /// This sort is unstable (i.e., may reorder equal elements), in-place - /// (i.e., does not allocate), and *O*(*n* \* log(*n*)) worst-case. - /// - /// # Current implementation - /// - /// The current algorithm is based on [pattern-defeating quicksort][pdqsort] by Orson Peters, - /// which combines the fast average case of randomized quicksort with the fast worst case of - /// heapsort, while achieving linear time on slices with certain patterns. It uses some - /// randomization to avoid degenerate cases, but with a fixed seed to always provide - /// deterministic behavior. - /// - /// It is typically faster than stable sorting, except in a few special cases, e.g., when the - /// slice consists of several concatenated sorted sequences. - /// - /// # Examples - /// - /// ``` - /// let mut v = [-5, 4, 1, -3, 2]; - /// - /// v.sort_unstable(); - /// assert!(v == [-5, -3, 1, 2, 4]); - /// ``` - /// - /// [pdqsort]: https://github.com/orlp/pdqsort - #[stable(feature = "sort_unstable", since = "1.20.0")] - #[inline] - pub fn sort_unstable(&mut self) - where - T: Ord, - { - sort::quicksort(self, T::lt); - } - - /// Sorts the slice with a comparator function, but might not preserve the order of equal - /// elements. - /// - /// This sort is unstable (i.e., may reorder equal elements), in-place - /// (i.e., does not allocate), and *O*(*n* \* log(*n*)) worst-case. - /// - /// The comparator function must define a total ordering for the elements in the slice. If - /// the ordering is not total, the order of the elements is unspecified. An order is a - /// total order if it is (for all `a`, `b` and `c`): - /// - /// * total and antisymmetric: exactly one of `a < b`, `a == b` or `a > b` is true, and - /// * transitive, `a < b` and `b < c` implies `a < c`. The same must hold for both `==` and `>`. - /// - /// For example, while [`f64`] doesn't implement [`Ord`] because `NaN != NaN`, we can use - /// `partial_cmp` as our sort function when we know the slice doesn't contain a `NaN`. - /// - /// ``` - /// let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0]; - /// floats.sort_unstable_by(|a, b| a.partial_cmp(b).unwrap()); - /// assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]); - /// ``` - /// - /// # Current implementation - /// - /// The current algorithm is based on [pattern-defeating quicksort][pdqsort] by Orson Peters, - /// which combines the fast average case of randomized quicksort with the fast worst case of - /// heapsort, while achieving linear time on slices with certain patterns. It uses some - /// randomization to avoid degenerate cases, but with a fixed seed to always provide - /// deterministic behavior. - /// - /// It is typically faster than stable sorting, except in a few special cases, e.g., when the - /// slice consists of several concatenated sorted sequences. - /// - /// # Examples - /// - /// ``` - /// let mut v = [5, 4, 1, 3, 2]; - /// v.sort_unstable_by(|a, b| a.cmp(b)); - /// assert!(v == [1, 2, 3, 4, 5]); - /// - /// // reverse sorting - /// v.sort_unstable_by(|a, b| b.cmp(a)); - /// assert!(v == [5, 4, 3, 2, 1]); - /// ``` - /// - /// [pdqsort]: https://github.com/orlp/pdqsort - #[stable(feature = "sort_unstable", since = "1.20.0")] - #[inline] - pub fn sort_unstable_by(&mut self, mut compare: F) - where - F: FnMut(&T, &T) -> Ordering, - { - sort::quicksort(self, |a, b| compare(a, b) == Ordering::Less); - } - - /// Sorts the slice with a key extraction function, but might not preserve the order of equal - /// elements. - /// - /// This sort is unstable (i.e., may reorder equal elements), in-place - /// (i.e., does not allocate), and *O*(*m* \* *n* \* log(*n*)) worst-case, where the key function is - /// *O*(*m*). - /// - /// # Current implementation - /// - /// The current algorithm is based on [pattern-defeating quicksort][pdqsort] by Orson Peters, - /// which combines the fast average case of randomized quicksort with the fast worst case of - /// heapsort, while achieving linear time on slices with certain patterns. It uses some - /// randomization to avoid degenerate cases, but with a fixed seed to always provide - /// deterministic behavior. - /// - /// Due to its key calling strategy, [`sort_unstable_by_key`](#method.sort_unstable_by_key) - /// is likely to be slower than [`sort_by_cached_key`](#method.sort_by_cached_key) in - /// cases where the key function is expensive. - /// - /// # Examples - /// - /// ``` - /// let mut v = [-5i32, 4, 1, -3, 2]; - /// - /// v.sort_unstable_by_key(|k| k.abs()); - /// assert!(v == [1, 2, -3, 4, -5]); - /// ``` - /// - /// [pdqsort]: https://github.com/orlp/pdqsort - #[stable(feature = "sort_unstable", since = "1.20.0")] - #[inline] - pub fn sort_unstable_by_key(&mut self, mut f: F) - where - F: FnMut(&T) -> K, - K: Ord, - { - sort::quicksort(self, |a, b| f(a).lt(&f(b))); - } - - /// Reorder the slice such that the element at `index` after the reordering is at its final sorted position. - /// - /// This reordering has the additional property that any value at position `i < index` will be - /// less than or equal to any value at a position `j > index`. Additionally, this reordering is - /// unstable (i.e. any number of equal elements may end up at position `index`), in-place - /// (i.e. does not allocate), and runs in *O*(*n*) time. - /// This function is also known as "kth element" in other libraries. - /// - /// It returns a triplet of the following from the reordered slice: - /// the subslice prior to `index`, the element at `index`, and the subslice after `index`; - /// accordingly, the values in those two subslices will respectively all be less-than-or-equal-to - /// and greater-than-or-equal-to the value of the element at `index`. - /// - /// # Current implementation - /// - /// The current algorithm is an introselect implementation based on Pattern Defeating Quicksort, which is also - /// the basis for [`sort_unstable`]. The fallback algorithm is Median of Medians using Tukey's Ninther for - /// pivot selection, which guarantees linear runtime for all inputs. - /// - /// [`sort_unstable`]: slice::sort_unstable - /// - /// # Panics - /// - /// Panics when `index >= len()`, meaning it always panics on empty slices. - /// - /// # Examples - /// - /// ``` - /// let mut v = [-5i32, 4, 2, -3, 1]; - /// - /// // Find the items less than or equal to the median, the median, and greater than or equal to - /// // the median. - /// let (lesser, median, greater) = v.select_nth_unstable(2); - /// - /// assert!(lesser == [-3, -5] || lesser == [-5, -3]); - /// assert_eq!(median, &mut 1); - /// assert!(greater == [4, 2] || greater == [2, 4]); - /// - /// // We are only guaranteed the slice will be one of the following, based on the way we sort - /// // about the specified index. - /// assert!(v == [-3, -5, 1, 2, 4] || - /// v == [-5, -3, 1, 2, 4] || - /// v == [-3, -5, 1, 4, 2] || - /// v == [-5, -3, 1, 4, 2]); - /// ``` - #[stable(feature = "slice_select_nth_unstable", since = "1.49.0")] - #[inline] - pub fn select_nth_unstable(&mut self, index: usize) -> (&mut [T], &mut T, &mut [T]) - where - T: Ord, - { - select::partition_at_index(self, index, T::lt) - } - - /// Reorder the slice with a comparator function such that the element at `index` after the reordering is at - /// its final sorted position. - /// - /// This reordering has the additional property that any value at position `i < index` will be - /// less than or equal to any value at a position `j > index` using the comparator function. - /// Additionally, this reordering is unstable (i.e. any number of equal elements may end up at - /// position `index`), in-place (i.e. does not allocate), and runs in *O*(*n*) time. - /// This function is also known as "kth element" in other libraries. - /// - /// It returns a triplet of the following from - /// the slice reordered according to the provided comparator function: the subslice prior to - /// `index`, the element at `index`, and the subslice after `index`; accordingly, the values in - /// those two subslices will respectively all be less-than-or-equal-to and greater-than-or-equal-to - /// the value of the element at `index`. - /// - /// # Current implementation - /// - /// The current algorithm is an introselect implementation based on Pattern Defeating Quicksort, which is also - /// the basis for [`sort_unstable`]. The fallback algorithm is Median of Medians using Tukey's Ninther for - /// pivot selection, which guarantees linear runtime for all inputs. - /// - /// [`sort_unstable`]: slice::sort_unstable - /// - /// # Panics - /// - /// Panics when `index >= len()`, meaning it always panics on empty slices. - /// - /// # Examples - /// - /// ``` - /// let mut v = [-5i32, 4, 2, -3, 1]; - /// - /// // Find the items less than or equal to the median, the median, and greater than or equal to - /// // the median as if the slice were sorted in descending order. - /// let (lesser, median, greater) = v.select_nth_unstable_by(2, |a, b| b.cmp(a)); - /// - /// assert!(lesser == [4, 2] || lesser == [2, 4]); - /// assert_eq!(median, &mut 1); - /// assert!(greater == [-3, -5] || greater == [-5, -3]); - /// - /// // We are only guaranteed the slice will be one of the following, based on the way we sort - /// // about the specified index. - /// assert!(v == [2, 4, 1, -5, -3] || - /// v == [2, 4, 1, -3, -5] || - /// v == [4, 2, 1, -5, -3] || - /// v == [4, 2, 1, -3, -5]); - /// ``` - #[stable(feature = "slice_select_nth_unstable", since = "1.49.0")] - #[inline] - pub fn select_nth_unstable_by( - &mut self, - index: usize, - mut compare: F, - ) -> (&mut [T], &mut T, &mut [T]) - where - F: FnMut(&T, &T) -> Ordering, - { - select::partition_at_index(self, index, |a: &T, b: &T| compare(a, b) == Less) - } - - /// Reorder the slice with a key extraction function such that the element at `index` after the reordering is - /// at its final sorted position. - /// - /// This reordering has the additional property that any value at position `i < index` will be - /// less than or equal to any value at a position `j > index` using the key extraction function. - /// Additionally, this reordering is unstable (i.e. any number of equal elements may end up at - /// position `index`), in-place (i.e. does not allocate), and runs in *O*(*n*) time. - /// This function is also known as "kth element" in other libraries. - /// - /// It returns a triplet of the following from - /// the slice reordered according to the provided key extraction function: the subslice prior to - /// `index`, the element at `index`, and the subslice after `index`; accordingly, the values in - /// those two subslices will respectively all be less-than-or-equal-to and greater-than-or-equal-to - /// the value of the element at `index`. - /// - /// # Current implementation - /// - /// The current algorithm is an introselect implementation based on Pattern Defeating Quicksort, which is also - /// the basis for [`sort_unstable`]. The fallback algorithm is Median of Medians using Tukey's Ninther for - /// pivot selection, which guarantees linear runtime for all inputs. - /// - /// [`sort_unstable`]: slice::sort_unstable - /// - /// # Panics - /// - /// Panics when `index >= len()`, meaning it always panics on empty slices. - /// - /// # Examples - /// - /// ``` - /// let mut v = [-5i32, 4, 1, -3, 2]; - /// - /// // Find the items less than or equal to the median, the median, and greater than or equal to - /// // the median as if the slice were sorted according to absolute value. - /// let (lesser, median, greater) = v.select_nth_unstable_by_key(2, |a| a.abs()); - /// - /// assert!(lesser == [1, 2] || lesser == [2, 1]); - /// assert_eq!(median, &mut -3); - /// assert!(greater == [4, -5] || greater == [-5, 4]); - /// - /// // We are only guaranteed the slice will be one of the following, based on the way we sort - /// // about the specified index. - /// assert!(v == [1, 2, -3, 4, -5] || - /// v == [1, 2, -3, -5, 4] || - /// v == [2, 1, -3, 4, -5] || - /// v == [2, 1, -3, -5, 4]); - /// ``` - #[stable(feature = "slice_select_nth_unstable", since = "1.49.0")] - #[inline] - pub fn select_nth_unstable_by_key( - &mut self, - index: usize, - mut f: F, - ) -> (&mut [T], &mut T, &mut [T]) - where - F: FnMut(&T) -> K, - K: Ord, - { - select::partition_at_index(self, index, |a: &T, b: &T| f(a).lt(&f(b))) - } - - /// Moves all consecutive repeated elements to the end of the slice according to the - /// [`PartialEq`] trait implementation. - /// - /// Returns two slices. The first contains no consecutive repeated elements. - /// The second contains all the duplicates in no specified order. - /// - /// If the slice is sorted, the first returned slice contains no duplicates. - /// - /// # Examples - /// - /// ``` - /// #![feature(slice_partition_dedup)] - /// - /// let mut slice = [1, 2, 2, 3, 3, 2, 1, 1]; - /// - /// let (dedup, duplicates) = slice.partition_dedup(); - /// - /// assert_eq!(dedup, [1, 2, 3, 2, 1]); - /// assert_eq!(duplicates, [2, 3, 1]); - /// ``` - #[unstable(feature = "slice_partition_dedup", issue = "54279")] - #[inline] - pub fn partition_dedup(&mut self) -> (&mut [T], &mut [T]) - where - T: PartialEq, - { - self.partition_dedup_by(|a, b| a == b) - } - - /// Moves all but the first of consecutive elements to the end of the slice satisfying - /// a given equality relation. - /// - /// Returns two slices. The first contains no consecutive repeated elements. - /// The second contains all the duplicates in no specified order. - /// - /// The `same_bucket` function is passed references to two elements from the slice and - /// must determine if the elements compare equal. The elements are passed in opposite order - /// from their order in the slice, so if `same_bucket(a, b)` returns `true`, `a` is moved - /// at the end of the slice. - /// - /// If the slice is sorted, the first returned slice contains no duplicates. - /// - /// # Examples - /// - /// ``` - /// #![feature(slice_partition_dedup)] - /// - /// let mut slice = ["foo", "Foo", "BAZ", "Bar", "bar", "baz", "BAZ"]; - /// - /// let (dedup, duplicates) = slice.partition_dedup_by(|a, b| a.eq_ignore_ascii_case(b)); - /// - /// assert_eq!(dedup, ["foo", "BAZ", "Bar", "baz"]); - /// assert_eq!(duplicates, ["bar", "Foo", "BAZ"]); - /// ``` - #[unstable(feature = "slice_partition_dedup", issue = "54279")] - #[inline] - pub fn partition_dedup_by(&mut self, mut same_bucket: F) -> (&mut [T], &mut [T]) - where - F: FnMut(&mut T, &mut T) -> bool, - { - // Although we have a mutable reference to `self`, we cannot make - // *arbitrary* changes. The `same_bucket` calls could panic, so we - // must ensure that the slice is in a valid state at all times. - // - // The way that we handle this is by using swaps; we iterate - // over all the elements, swapping as we go so that at the end - // the elements we wish to keep are in the front, and those we - // wish to reject are at the back. We can then split the slice. - // This operation is still `O(n)`. - // - // Example: We start in this state, where `r` represents "next - // read" and `w` represents "next_write". - // - // r - // +---+---+---+---+---+---+ - // | 0 | 1 | 1 | 2 | 3 | 3 | - // +---+---+---+---+---+---+ - // w - // - // Comparing self[r] against self[w-1], this is not a duplicate, so - // we swap self[r] and self[w] (no effect as r==w) and then increment both - // r and w, leaving us with: - // - // r - // +---+---+---+---+---+---+ - // | 0 | 1 | 1 | 2 | 3 | 3 | - // +---+---+---+---+---+---+ - // w - // - // Comparing self[r] against self[w-1], this value is a duplicate, - // so we increment `r` but leave everything else unchanged: - // - // r - // +---+---+---+---+---+---+ - // | 0 | 1 | 1 | 2 | 3 | 3 | - // +---+---+---+---+---+---+ - // w - // - // Comparing self[r] against self[w-1], this is not a duplicate, - // so swap self[r] and self[w] and advance r and w: - // - // r - // +---+---+---+---+---+---+ - // | 0 | 1 | 2 | 1 | 3 | 3 | - // +---+---+---+---+---+---+ - // w - // - // Not a duplicate, repeat: - // - // r - // +---+---+---+---+---+---+ - // | 0 | 1 | 2 | 3 | 1 | 3 | - // +---+---+---+---+---+---+ - // w - // - // Duplicate, advance r. End of slice. Split at w. - - let len = self.len(); - if len <= 1 { - return (self, &mut []); - } - - let ptr = self.as_mut_ptr(); - let mut next_read: usize = 1; - let mut next_write: usize = 1; - - // SAFETY: the `while` condition guarantees `next_read` and `next_write` - // are less than `len`, thus are inside `self`. `prev_ptr_write` points to - // one element before `ptr_write`, but `next_write` starts at 1, so - // `prev_ptr_write` is never less than 0 and is inside the slice. - // This fulfils the requirements for dereferencing `ptr_read`, `prev_ptr_write` - // and `ptr_write`, and for using `ptr.add(next_read)`, `ptr.add(next_write - 1)` - // and `prev_ptr_write.offset(1)`. - // - // `next_write` is also incremented at most once per loop at most meaning - // no element is skipped when it may need to be swapped. - // - // `ptr_read` and `prev_ptr_write` never point to the same element. This - // is required for `&mut *ptr_read`, `&mut *prev_ptr_write` to be safe. - // The explanation is simply that `next_read >= next_write` is always true, - // thus `next_read > next_write - 1` is too. - unsafe { - // Avoid bounds checks by using raw pointers. - while next_read < len { - let ptr_read = ptr.add(next_read); - let prev_ptr_write = ptr.add(next_write - 1); - if !same_bucket(&mut *ptr_read, &mut *prev_ptr_write) { - if next_read != next_write { - let ptr_write = prev_ptr_write.add(1); - mem::swap(&mut *ptr_read, &mut *ptr_write); - } - next_write += 1; - } - next_read += 1; - } - } - - self.split_at_mut(next_write) - } - - /// Moves all but the first of consecutive elements to the end of the slice that resolve - /// to the same key. - /// - /// Returns two slices. The first contains no consecutive repeated elements. - /// The second contains all the duplicates in no specified order. - /// - /// If the slice is sorted, the first returned slice contains no duplicates. - /// - /// # Examples - /// - /// ``` - /// #![feature(slice_partition_dedup)] - /// - /// let mut slice = [10, 20, 21, 30, 30, 20, 11, 13]; - /// - /// let (dedup, duplicates) = slice.partition_dedup_by_key(|i| *i / 10); - /// - /// assert_eq!(dedup, [10, 20, 30, 20, 11]); - /// assert_eq!(duplicates, [21, 30, 13]); - /// ``` - #[unstable(feature = "slice_partition_dedup", issue = "54279")] - #[inline] - pub fn partition_dedup_by_key(&mut self, mut key: F) -> (&mut [T], &mut [T]) - where - F: FnMut(&mut T) -> K, - K: PartialEq, - { - self.partition_dedup_by(|a, b| key(a) == key(b)) - } - - /// Rotates the slice in-place such that the first `mid` elements of the - /// slice move to the end while the last `self.len() - mid` elements move to - /// the front. After calling `rotate_left`, the element previously at index - /// `mid` will become the first element in the slice. - /// - /// # Panics - /// - /// This function will panic if `mid` is greater than the length of the - /// slice. Note that `mid == self.len()` does _not_ panic and is a no-op - /// rotation. - /// - /// # Complexity - /// - /// Takes linear (in `self.len()`) time. - /// - /// # Examples - /// - /// ``` - /// let mut a = ['a', 'b', 'c', 'd', 'e', 'f']; - /// a.rotate_left(2); - /// assert_eq!(a, ['c', 'd', 'e', 'f', 'a', 'b']); - /// ``` - /// - /// Rotating a subslice: - /// - /// ``` - /// let mut a = ['a', 'b', 'c', 'd', 'e', 'f']; - /// a[1..5].rotate_left(1); - /// assert_eq!(a, ['a', 'c', 'd', 'e', 'b', 'f']); - /// ``` - #[stable(feature = "slice_rotate", since = "1.26.0")] - pub fn rotate_left(&mut self, mid: usize) { - assert!(mid <= self.len()); - let k = self.len() - mid; - let p = self.as_mut_ptr(); - - // SAFETY: The range `[p.add(mid) - mid, p.add(mid) + k)` is trivially - // valid for reading and writing, as required by `ptr_rotate`. - unsafe { - rotate::ptr_rotate(mid, p.add(mid), k); - } - } - - /// Rotates the slice in-place such that the first `self.len() - k` - /// elements of the slice move to the end while the last `k` elements move - /// to the front. After calling `rotate_right`, the element previously at - /// index `self.len() - k` will become the first element in the slice. - /// - /// # Panics - /// - /// This function will panic if `k` is greater than the length of the - /// slice. Note that `k == self.len()` does _not_ panic and is a no-op - /// rotation. - /// - /// # Complexity - /// - /// Takes linear (in `self.len()`) time. - /// - /// # Examples - /// - /// ``` - /// let mut a = ['a', 'b', 'c', 'd', 'e', 'f']; - /// a.rotate_right(2); - /// assert_eq!(a, ['e', 'f', 'a', 'b', 'c', 'd']); - /// ``` - /// - /// Rotating a subslice: - /// - /// ``` - /// let mut a = ['a', 'b', 'c', 'd', 'e', 'f']; - /// a[1..5].rotate_right(1); - /// assert_eq!(a, ['a', 'e', 'b', 'c', 'd', 'f']); - /// ``` - #[stable(feature = "slice_rotate", since = "1.26.0")] - pub fn rotate_right(&mut self, k: usize) { - assert!(k <= self.len()); - let mid = self.len() - k; - let p = self.as_mut_ptr(); - - // SAFETY: The range `[p.add(mid) - mid, p.add(mid) + k)` is trivially - // valid for reading and writing, as required by `ptr_rotate`. - unsafe { - rotate::ptr_rotate(mid, p.add(mid), k); - } - } - - /// Fills `self` with elements by cloning `value`. - /// - /// # Examples - /// - /// ``` - /// let mut buf = vec![0; 10]; - /// buf.fill(1); - /// assert_eq!(buf, vec![1; 10]); - /// ``` - #[doc(alias = "memset")] - #[stable(feature = "slice_fill", since = "1.50.0")] - pub fn fill(&mut self, value: T) - where - T: Clone, - { - specialize::SpecFill::spec_fill(self, value); - } - - /// Fills `self` with elements returned by calling a closure repeatedly. - /// - /// This method uses a closure to create new values. If you'd rather - /// [`Clone`] a given value, use [`fill`]. If you want to use the [`Default`] - /// trait to generate values, you can pass [`Default::default`] as the - /// argument. - /// - /// [`fill`]: slice::fill - /// - /// # Examples - /// - /// ``` - /// let mut buf = vec![1; 10]; - /// buf.fill_with(Default::default); - /// assert_eq!(buf, vec![0; 10]); - /// ``` - #[stable(feature = "slice_fill_with", since = "1.51.0")] - pub fn fill_with(&mut self, mut f: F) - where - F: FnMut() -> T, - { - for el in self { - *el = f(); - } - } - - /// Copies the elements from `src` into `self`. - /// - /// The length of `src` must be the same as `self`. - /// - /// # Panics - /// - /// This function will panic if the two slices have different lengths. - /// - /// # Examples - /// - /// Cloning two elements from a slice into another: - /// - /// ``` - /// let src = [1, 2, 3, 4]; - /// let mut dst = [0, 0]; - /// - /// // Because the slices have to be the same length, - /// // we slice the source slice from four elements - /// // to two. It will panic if we don't do this. - /// dst.clone_from_slice(&src[2..]); - /// - /// assert_eq!(src, [1, 2, 3, 4]); - /// assert_eq!(dst, [3, 4]); - /// ``` - /// - /// Rust enforces that there can only be one mutable reference with no - /// immutable references to a particular piece of data in a particular - /// scope. Because of this, attempting to use `clone_from_slice` on a - /// single slice will result in a compile failure: - /// - /// ```compile_fail - /// let mut slice = [1, 2, 3, 4, 5]; - /// - /// slice[..2].clone_from_slice(&slice[3..]); // compile fail! - /// ``` - /// - /// To work around this, we can use [`split_at_mut`] to create two distinct - /// sub-slices from a slice: - /// - /// ``` - /// let mut slice = [1, 2, 3, 4, 5]; - /// - /// { - /// let (left, right) = slice.split_at_mut(2); - /// left.clone_from_slice(&right[1..]); - /// } - /// - /// assert_eq!(slice, [4, 5, 3, 4, 5]); - /// ``` - /// - /// [`copy_from_slice`]: slice::copy_from_slice - /// [`split_at_mut`]: slice::split_at_mut - #[stable(feature = "clone_from_slice", since = "1.7.0")] - #[track_caller] - pub fn clone_from_slice(&mut self, src: &[T]) - where - T: Clone, - { - self.spec_clone_from(src); - } - - /// Copies all elements from `src` into `self`, using a memcpy. - /// - /// The length of `src` must be the same as `self`. - /// - /// If `T` does not implement `Copy`, use [`clone_from_slice`]. - /// - /// # Panics - /// - /// This function will panic if the two slices have different lengths. - /// - /// # Examples - /// - /// Copying two elements from a slice into another: - /// - /// ``` - /// let src = [1, 2, 3, 4]; - /// let mut dst = [0, 0]; - /// - /// // Because the slices have to be the same length, - /// // we slice the source slice from four elements - /// // to two. It will panic if we don't do this. - /// dst.copy_from_slice(&src[2..]); - /// - /// assert_eq!(src, [1, 2, 3, 4]); - /// assert_eq!(dst, [3, 4]); - /// ``` - /// - /// Rust enforces that there can only be one mutable reference with no - /// immutable references to a particular piece of data in a particular - /// scope. Because of this, attempting to use `copy_from_slice` on a - /// single slice will result in a compile failure: - /// - /// ```compile_fail - /// let mut slice = [1, 2, 3, 4, 5]; - /// - /// slice[..2].copy_from_slice(&slice[3..]); // compile fail! - /// ``` - /// - /// To work around this, we can use [`split_at_mut`] to create two distinct - /// sub-slices from a slice: - /// - /// ``` - /// let mut slice = [1, 2, 3, 4, 5]; - /// - /// { - /// let (left, right) = slice.split_at_mut(2); - /// left.copy_from_slice(&right[1..]); - /// } - /// - /// assert_eq!(slice, [4, 5, 3, 4, 5]); - /// ``` - /// - /// [`clone_from_slice`]: slice::clone_from_slice - /// [`split_at_mut`]: slice::split_at_mut - #[doc(alias = "memcpy")] - #[stable(feature = "copy_from_slice", since = "1.9.0")] - #[track_caller] - pub fn copy_from_slice(&mut self, src: &[T]) - where - T: Copy, - { - // The panic code path was put into a cold function to not bloat the - // call site. - #[inline(never)] - #[cold] - #[track_caller] - fn len_mismatch_fail(dst_len: usize, src_len: usize) -> ! { - panic!( - "source slice length ({}) does not match destination slice length ({})", - src_len, dst_len, - ); - } - - if self.len() != src.len() { - len_mismatch_fail(self.len(), src.len()); - } - - // SAFETY: `self` is valid for `self.len()` elements by definition, and `src` was - // checked to have the same length. The slices cannot overlap because - // mutable references are exclusive. - unsafe { - ptr::copy_nonoverlapping(src.as_ptr(), self.as_mut_ptr(), self.len()); - } - } - - /// Copies elements from one part of the slice to another part of itself, - /// using a memmove. - /// - /// `src` is the range within `self` to copy from. `dest` is the starting - /// index of the range within `self` to copy to, which will have the same - /// length as `src`. The two ranges may overlap. The ends of the two ranges - /// must be less than or equal to `self.len()`. - /// - /// # Panics - /// - /// This function will panic if either range exceeds the end of the slice, - /// or if the end of `src` is before the start. - /// - /// # Examples - /// - /// Copying four bytes within a slice: - /// - /// ``` - /// let mut bytes = *b"Hello, World!"; - /// - /// bytes.copy_within(1..5, 8); - /// - /// assert_eq!(&bytes, b"Hello, Wello!"); - /// ``` - #[stable(feature = "copy_within", since = "1.37.0")] - #[track_caller] - pub fn copy_within>(&mut self, src: R, dest: usize) - where - T: Copy, - { - let Range { start: src_start, end: src_end } = slice::range(src, ..self.len()); - let count = src_end - src_start; - assert!(dest <= self.len() - count, "dest is out of bounds"); - // SAFETY: the conditions for `ptr::copy` have all been checked above, - // as have those for `ptr::add`. - unsafe { - // Derive both `src_ptr` and `dest_ptr` from the same loan - let ptr = self.as_mut_ptr(); - let src_ptr = ptr.add(src_start); - let dest_ptr = ptr.add(dest); - ptr::copy(src_ptr, dest_ptr, count); - } - } - - /// Swaps all elements in `self` with those in `other`. - /// - /// The length of `other` must be the same as `self`. - /// - /// # Panics - /// - /// This function will panic if the two slices have different lengths. - /// - /// # Example - /// - /// Swapping two elements across slices: - /// - /// ``` - /// let mut slice1 = [0, 0]; - /// let mut slice2 = [1, 2, 3, 4]; - /// - /// slice1.swap_with_slice(&mut slice2[2..]); - /// - /// assert_eq!(slice1, [3, 4]); - /// assert_eq!(slice2, [1, 2, 0, 0]); - /// ``` - /// - /// Rust enforces that there can only be one mutable reference to a - /// particular piece of data in a particular scope. Because of this, - /// attempting to use `swap_with_slice` on a single slice will result in - /// a compile failure: - /// - /// ```compile_fail - /// let mut slice = [1, 2, 3, 4, 5]; - /// slice[..2].swap_with_slice(&mut slice[3..]); // compile fail! - /// ``` - /// - /// To work around this, we can use [`split_at_mut`] to create two distinct - /// mutable sub-slices from a slice: - /// - /// ``` - /// let mut slice = [1, 2, 3, 4, 5]; - /// - /// { - /// let (left, right) = slice.split_at_mut(2); - /// left.swap_with_slice(&mut right[1..]); - /// } - /// - /// assert_eq!(slice, [4, 5, 3, 1, 2]); - /// ``` - /// - /// [`split_at_mut`]: slice::split_at_mut - #[stable(feature = "swap_with_slice", since = "1.27.0")] - #[track_caller] - pub fn swap_with_slice(&mut self, other: &mut [T]) { - assert!(self.len() == other.len(), "destination and source slices have different lengths"); - // SAFETY: `self` is valid for `self.len()` elements by definition, and `src` was - // checked to have the same length. The slices cannot overlap because - // mutable references are exclusive. - unsafe { - ptr::swap_nonoverlapping(self.as_mut_ptr(), other.as_mut_ptr(), self.len()); - } - } - - /// Function to calculate lengths of the middle and trailing slice for `align_to{,_mut}`. - fn align_to_offsets(&self) -> (usize, usize) { - // What we gonna do about `rest` is figure out what multiple of `U`s we can put in a - // lowest number of `T`s. And how many `T`s we need for each such "multiple". - // - // Consider for example T=u8 U=u16. Then we can put 1 U in 2 Ts. Simple. Now, consider - // for example a case where size_of:: = 16, size_of:: = 24. We can put 2 Us in - // place of every 3 Ts in the `rest` slice. A bit more complicated. - // - // Formula to calculate this is: - // - // Us = lcm(size_of::, size_of::) / size_of:: - // Ts = lcm(size_of::, size_of::) / size_of:: - // - // Expanded and simplified: - // - // Us = size_of:: / gcd(size_of::, size_of::) - // Ts = size_of:: / gcd(size_of::, size_of::) - // - // Luckily since all this is constant-evaluated... performance here matters not! - const fn gcd(a: usize, b: usize) -> usize { - if b == 0 { a } else { gcd(b, a % b) } - } - - // Explicitly wrap the function call in a const block so it gets - // constant-evaluated even in debug mode. - let gcd: usize = const { gcd(mem::size_of::(), mem::size_of::()) }; - let ts: usize = mem::size_of::() / gcd; - let us: usize = mem::size_of::() / gcd; - - // Armed with this knowledge, we can find how many `U`s we can fit! - let us_len = self.len() / ts * us; - // And how many `T`s will be in the trailing slice! - let ts_len = self.len() % ts; - (us_len, ts_len) - } - - /// Transmute the slice to a slice of another type, ensuring alignment of the types is - /// maintained. - /// - /// This method splits the slice into three distinct slices: prefix, correctly aligned middle - /// slice of a new type, and the suffix slice. The middle part will be as big as possible under - /// the given alignment constraint and element size. - /// - /// This method has no purpose when either input element `T` or output element `U` are - /// zero-sized and will return the original slice without splitting anything. - /// - /// # Safety - /// - /// This method is essentially a `transmute` with respect to the elements in the returned - /// middle slice, so all the usual caveats pertaining to `transmute::` also apply here. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// unsafe { - /// let bytes: [u8; 7] = [1, 2, 3, 4, 5, 6, 7]; - /// let (prefix, shorts, suffix) = bytes.align_to::(); - /// // less_efficient_algorithm_for_bytes(prefix); - /// // more_efficient_algorithm_for_aligned_shorts(shorts); - /// // less_efficient_algorithm_for_bytes(suffix); - /// } - /// ``` - #[stable(feature = "slice_align_to", since = "1.30.0")] - #[must_use] - pub unsafe fn align_to(&self) -> (&[T], &[U], &[T]) { - // Note that most of this function will be constant-evaluated, - if U::IS_ZST || T::IS_ZST { - // handle ZSTs specially, which is – don't handle them at all. - return (self, &[], &[]); - } - - // First, find at what point do we split between the first and 2nd slice. Easy with - // ptr.align_offset. - let ptr = self.as_ptr(); - // SAFETY: See the `align_to_mut` method for the detailed safety comment. - let offset = unsafe { crate::ptr::align_offset(ptr, mem::align_of::()) }; - if offset > self.len() { - (self, &[], &[]) - } else { - let (left, rest) = self.split_at(offset); - let (us_len, ts_len) = rest.align_to_offsets::(); - // Inform Miri that we want to consider the "middle" pointer to be suitably aligned. - #[cfg(miri)] - crate::intrinsics::miri_promise_symbolic_alignment( - rest.as_ptr().cast(), - mem::align_of::(), - ); - // SAFETY: now `rest` is definitely aligned, so `from_raw_parts` below is okay, - // since the caller guarantees that we can transmute `T` to `U` safely. - unsafe { - ( - left, - from_raw_parts(rest.as_ptr() as *const U, us_len), - from_raw_parts(rest.as_ptr().add(rest.len() - ts_len), ts_len), - ) - } - } - } - - /// Transmute the mutable slice to a mutable slice of another type, ensuring alignment of the - /// types is maintained. - /// - /// This method splits the slice into three distinct slices: prefix, correctly aligned middle - /// slice of a new type, and the suffix slice. The middle part will be as big as possible under - /// the given alignment constraint and element size. - /// - /// This method has no purpose when either input element `T` or output element `U` are - /// zero-sized and will return the original slice without splitting anything. - /// - /// # Safety - /// - /// This method is essentially a `transmute` with respect to the elements in the returned - /// middle slice, so all the usual caveats pertaining to `transmute::` also apply here. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// unsafe { - /// let mut bytes: [u8; 7] = [1, 2, 3, 4, 5, 6, 7]; - /// let (prefix, shorts, suffix) = bytes.align_to_mut::(); - /// // less_efficient_algorithm_for_bytes(prefix); - /// // more_efficient_algorithm_for_aligned_shorts(shorts); - /// // less_efficient_algorithm_for_bytes(suffix); - /// } - /// ``` - #[stable(feature = "slice_align_to", since = "1.30.0")] - #[must_use] - pub unsafe fn align_to_mut(&mut self) -> (&mut [T], &mut [U], &mut [T]) { - // Note that most of this function will be constant-evaluated, - if U::IS_ZST || T::IS_ZST { - // handle ZSTs specially, which is – don't handle them at all. - return (self, &mut [], &mut []); - } - - // First, find at what point do we split between the first and 2nd slice. Easy with - // ptr.align_offset. - let ptr = self.as_ptr(); - // SAFETY: Here we are ensuring we will use aligned pointers for U for the - // rest of the method. This is done by passing a pointer to &[T] with an - // alignment targeted for U. - // `crate::ptr::align_offset` is called with a correctly aligned and - // valid pointer `ptr` (it comes from a reference to `self`) and with - // a size that is a power of two (since it comes from the alignment for U), - // satisfying its safety constraints. - let offset = unsafe { crate::ptr::align_offset(ptr, mem::align_of::()) }; - if offset > self.len() { - (self, &mut [], &mut []) - } else { - let (left, rest) = self.split_at_mut(offset); - let (us_len, ts_len) = rest.align_to_offsets::(); - let rest_len = rest.len(); - let mut_ptr = rest.as_mut_ptr(); - // Inform Miri that we want to consider the "middle" pointer to be suitably aligned. - #[cfg(miri)] - crate::intrinsics::miri_promise_symbolic_alignment( - mut_ptr.cast() as *const (), - mem::align_of::(), - ); - // We can't use `rest` again after this, that would invalidate its alias `mut_ptr`! - // SAFETY: see comments for `align_to`. - unsafe { - ( - left, - from_raw_parts_mut(mut_ptr as *mut U, us_len), - from_raw_parts_mut(mut_ptr.add(rest_len - ts_len), ts_len), - ) - } - } - } - - /// Split a slice into a prefix, a middle of aligned SIMD types, and a suffix. - /// - /// This is a safe wrapper around [`slice::align_to`], so has the same weak - /// postconditions as that method. You're only assured that - /// `self.len() == prefix.len() + middle.len() * LANES + suffix.len()`. - /// - /// Notably, all of the following are possible: - /// - `prefix.len() >= LANES`. - /// - `middle.is_empty()` despite `self.len() >= 3 * LANES`. - /// - `suffix.len() >= LANES`. - /// - /// That said, this is a safe method, so if you're only writing safe code, - /// then this can at most cause incorrect logic, not unsoundness. - /// - /// # Panics - /// - /// This will panic if the size of the SIMD type is different from - /// `LANES` times that of the scalar. - /// - /// At the time of writing, the trait restrictions on `Simd` keeps - /// that from ever happening, as only power-of-two numbers of lanes are - /// supported. It's possible that, in the future, those restrictions might - /// be lifted in a way that would make it possible to see panics from this - /// method for something like `LANES == 3`. - /// - /// # Examples - /// - /// ``` - /// #![feature(portable_simd)] - /// use core::simd::prelude::*; - /// - /// let short = &[1, 2, 3]; - /// let (prefix, middle, suffix) = short.as_simd::<4>(); - /// assert_eq!(middle, []); // Not enough elements for anything in the middle - /// - /// // They might be split in any possible way between prefix and suffix - /// let it = prefix.iter().chain(suffix).copied(); - /// assert_eq!(it.collect::>(), vec![1, 2, 3]); - /// - /// fn basic_simd_sum(x: &[f32]) -> f32 { - /// use std::ops::Add; - /// let (prefix, middle, suffix) = x.as_simd(); - /// let sums = f32x4::from_array([ - /// prefix.iter().copied().sum(), - /// 0.0, - /// 0.0, - /// suffix.iter().copied().sum(), - /// ]); - /// let sums = middle.iter().copied().fold(sums, f32x4::add); - /// sums.reduce_sum() - /// } - /// - /// let numbers: Vec = (1..101).map(|x| x as _).collect(); - /// assert_eq!(basic_simd_sum(&numbers[1..99]), 4949.0); - /// ``` - #[unstable(feature = "portable_simd", issue = "86656")] - #[must_use] - pub fn as_simd(&self) -> (&[T], &[Simd], &[T]) - where - Simd: AsRef<[T; LANES]>, - T: simd::SimdElement, - simd::LaneCount: simd::SupportedLaneCount, - { - // These are expected to always match, as vector types are laid out like - // arrays per , but we - // might as well double-check since it'll optimize away anyhow. - assert_eq!(mem::size_of::>(), mem::size_of::<[T; LANES]>()); - - // SAFETY: The simd types have the same layout as arrays, just with - // potentially-higher alignment, so the de-facto transmutes are sound. - unsafe { self.align_to() } - } - - /// Split a mutable slice into a mutable prefix, a middle of aligned SIMD types, - /// and a mutable suffix. - /// - /// This is a safe wrapper around [`slice::align_to_mut`], so has the same weak - /// postconditions as that method. You're only assured that - /// `self.len() == prefix.len() + middle.len() * LANES + suffix.len()`. - /// - /// Notably, all of the following are possible: - /// - `prefix.len() >= LANES`. - /// - `middle.is_empty()` despite `self.len() >= 3 * LANES`. - /// - `suffix.len() >= LANES`. - /// - /// That said, this is a safe method, so if you're only writing safe code, - /// then this can at most cause incorrect logic, not unsoundness. - /// - /// This is the mutable version of [`slice::as_simd`]; see that for examples. - /// - /// # Panics - /// - /// This will panic if the size of the SIMD type is different from - /// `LANES` times that of the scalar. - /// - /// At the time of writing, the trait restrictions on `Simd` keeps - /// that from ever happening, as only power-of-two numbers of lanes are - /// supported. It's possible that, in the future, those restrictions might - /// be lifted in a way that would make it possible to see panics from this - /// method for something like `LANES == 3`. - #[unstable(feature = "portable_simd", issue = "86656")] - #[must_use] - pub fn as_simd_mut(&mut self) -> (&mut [T], &mut [Simd], &mut [T]) - where - Simd: AsMut<[T; LANES]>, - T: simd::SimdElement, - simd::LaneCount: simd::SupportedLaneCount, - { - // These are expected to always match, as vector types are laid out like - // arrays per , but we - // might as well double-check since it'll optimize away anyhow. - assert_eq!(mem::size_of::>(), mem::size_of::<[T; LANES]>()); - - // SAFETY: The simd types have the same layout as arrays, just with - // potentially-higher alignment, so the de-facto transmutes are sound. - unsafe { self.align_to_mut() } - } - - /// Checks if the elements of this slice are sorted. - /// - /// That is, for each element `a` and its following element `b`, `a <= b` must hold. If the - /// slice yields exactly zero or one element, `true` is returned. - /// - /// Note that if `Self::Item` is only `PartialOrd`, but not `Ord`, the above definition - /// implies that this function returns `false` if any two consecutive items are not - /// comparable. - /// - /// # Examples - /// - /// ``` - /// #![feature(is_sorted)] - /// let empty: [i32; 0] = []; - /// - /// assert!([1, 2, 2, 9].is_sorted()); - /// assert!(![1, 3, 2, 4].is_sorted()); - /// assert!([0].is_sorted()); - /// assert!(empty.is_sorted()); - /// assert!(![0.0, 1.0, f32::NAN].is_sorted()); - /// ``` - #[inline] - #[unstable(feature = "is_sorted", reason = "new API", issue = "53485")] - #[must_use] - pub fn is_sorted(&self) -> bool - where - T: PartialOrd, - { - self.is_sorted_by(|a, b| a <= b) - } - - /// Checks if the elements of this slice are sorted using the given comparator function. - /// - /// Instead of using `PartialOrd::partial_cmp`, this function uses the given `compare` - /// function to determine whether two elements are to be considered in sorted order. - /// - /// # Examples - /// - /// ``` - /// #![feature(is_sorted)] - /// - /// assert!([1, 2, 2, 9].is_sorted_by(|a, b| a <= b)); - /// assert!(![1, 2, 2, 9].is_sorted_by(|a, b| a < b)); - /// - /// assert!([0].is_sorted_by(|a, b| true)); - /// assert!([0].is_sorted_by(|a, b| false)); - /// - /// let empty: [i32; 0] = []; - /// assert!(empty.is_sorted_by(|a, b| false)); - /// assert!(empty.is_sorted_by(|a, b| true)); - /// ``` - #[unstable(feature = "is_sorted", reason = "new API", issue = "53485")] - #[must_use] - pub fn is_sorted_by<'a, F>(&'a self, mut compare: F) -> bool - where - F: FnMut(&'a T, &'a T) -> bool, - { - self.array_windows().all(|[a, b]| compare(a, b)) - } - - /// Checks if the elements of this slice are sorted using the given key extraction function. - /// - /// Instead of comparing the slice's elements directly, this function compares the keys of the - /// elements, as determined by `f`. Apart from that, it's equivalent to [`is_sorted`]; see its - /// documentation for more information. - /// - /// [`is_sorted`]: slice::is_sorted - /// - /// # Examples - /// - /// ``` - /// #![feature(is_sorted)] - /// - /// assert!(["c", "bb", "aaa"].is_sorted_by_key(|s| s.len())); - /// assert!(![-2i32, -1, 0, 3].is_sorted_by_key(|n| n.abs())); - /// ``` - #[inline] - #[unstable(feature = "is_sorted", reason = "new API", issue = "53485")] - #[must_use] - pub fn is_sorted_by_key<'a, F, K>(&'a self, f: F) -> bool - where - F: FnMut(&'a T) -> K, - K: PartialOrd, - { - self.iter().is_sorted_by_key(f) - } - - /// Returns the index of the partition point according to the given predicate - /// (the index of the first element of the second partition). - /// - /// The slice is assumed to be partitioned according to the given predicate. - /// This means that all elements for which the predicate returns true are at the start of the slice - /// and all elements for which the predicate returns false are at the end. - /// For example, `[7, 15, 3, 5, 4, 12, 6]` is partitioned under the predicate `x % 2 != 0` - /// (all odd numbers are at the start, all even at the end). - /// - /// If this slice is not partitioned, the returned result is unspecified and meaningless, - /// as this method performs a kind of binary search. - /// - /// See also [`binary_search`], [`binary_search_by`], and [`binary_search_by_key`]. - /// - /// [`binary_search`]: slice::binary_search - /// [`binary_search_by`]: slice::binary_search_by - /// [`binary_search_by_key`]: slice::binary_search_by_key - /// - /// # Examples - /// - /// ``` - /// let v = [1, 2, 3, 3, 5, 6, 7]; - /// let i = v.partition_point(|&x| x < 5); - /// - /// assert_eq!(i, 4); - /// assert!(v[..i].iter().all(|&x| x < 5)); - /// assert!(v[i..].iter().all(|&x| !(x < 5))); - /// ``` - /// - /// If all elements of the slice match the predicate, including if the slice - /// is empty, then the length of the slice will be returned: - /// - /// ``` - /// let a = [2, 4, 8]; - /// assert_eq!(a.partition_point(|x| x < &100), a.len()); - /// let a: [i32; 0] = []; - /// assert_eq!(a.partition_point(|x| x < &100), 0); - /// ``` - /// - /// If you want to insert an item to a sorted vector, while maintaining - /// sort order: - /// - /// ``` - /// let mut s = vec![0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55]; - /// let num = 42; - /// let idx = s.partition_point(|&x| x <= num); - /// s.insert(idx, num); - /// assert_eq!(s, [0, 1, 1, 1, 1, 2, 3, 5, 8, 13, 21, 34, 42, 55]); - /// ``` - #[stable(feature = "partition_point", since = "1.52.0")] - #[must_use] - pub fn partition_point

(&self, mut pred: P) -> usize - where - P: FnMut(&T) -> bool, - { - self.binary_search_by(|x| if pred(x) { Less } else { Greater }).unwrap_or_else(|i| i) - } - - /// Removes the subslice corresponding to the given range - /// and returns a reference to it. - /// - /// Returns `None` and does not modify the slice if the given - /// range is out of bounds. - /// - /// Note that this method only accepts one-sided ranges such as - /// `2..` or `..6`, but not `2..6`. - /// - /// # Examples - /// - /// Taking the first three elements of a slice: - /// - /// ``` - /// #![feature(slice_take)] - /// - /// let mut slice: &[_] = &['a', 'b', 'c', 'd']; - /// let mut first_three = slice.take(..3).unwrap(); - /// - /// assert_eq!(slice, &['d']); - /// assert_eq!(first_three, &['a', 'b', 'c']); - /// ``` - /// - /// Taking the last two elements of a slice: - /// - /// ``` - /// #![feature(slice_take)] - /// - /// let mut slice: &[_] = &['a', 'b', 'c', 'd']; - /// let mut tail = slice.take(2..).unwrap(); - /// - /// assert_eq!(slice, &['a', 'b']); - /// assert_eq!(tail, &['c', 'd']); - /// ``` - /// - /// Getting `None` when `range` is out of bounds: - /// - /// ``` - /// #![feature(slice_take)] - /// - /// let mut slice: &[_] = &['a', 'b', 'c', 'd']; - /// - /// assert_eq!(None, slice.take(5..)); - /// assert_eq!(None, slice.take(..5)); - /// assert_eq!(None, slice.take(..=4)); - /// let expected: &[char] = &['a', 'b', 'c', 'd']; - /// assert_eq!(Some(expected), slice.take(..4)); - /// ``` - #[inline] - #[must_use = "method does not modify the slice if the range is out of bounds"] - #[unstable(feature = "slice_take", issue = "62280")] - pub fn take<'a, R: OneSidedRange>(self: &mut &'a Self, range: R) -> Option<&'a Self> { - let (direction, split_index) = split_point_of(range)?; - if split_index > self.len() { - return None; - } - let (front, back) = self.split_at(split_index); - match direction { - Direction::Front => { - *self = back; - Some(front) - } - Direction::Back => { - *self = front; - Some(back) - } - } - } - - /// Removes the subslice corresponding to the given range - /// and returns a mutable reference to it. - /// - /// Returns `None` and does not modify the slice if the given - /// range is out of bounds. - /// - /// Note that this method only accepts one-sided ranges such as - /// `2..` or `..6`, but not `2..6`. - /// - /// # Examples - /// - /// Taking the first three elements of a slice: - /// - /// ``` - /// #![feature(slice_take)] - /// - /// let mut slice: &mut [_] = &mut ['a', 'b', 'c', 'd']; - /// let mut first_three = slice.take_mut(..3).unwrap(); - /// - /// assert_eq!(slice, &mut ['d']); - /// assert_eq!(first_three, &mut ['a', 'b', 'c']); - /// ``` - /// - /// Taking the last two elements of a slice: - /// - /// ``` - /// #![feature(slice_take)] - /// - /// let mut slice: &mut [_] = &mut ['a', 'b', 'c', 'd']; - /// let mut tail = slice.take_mut(2..).unwrap(); - /// - /// assert_eq!(slice, &mut ['a', 'b']); - /// assert_eq!(tail, &mut ['c', 'd']); - /// ``` - /// - /// Getting `None` when `range` is out of bounds: - /// - /// ``` - /// #![feature(slice_take)] - /// - /// let mut slice: &mut [_] = &mut ['a', 'b', 'c', 'd']; - /// - /// assert_eq!(None, slice.take_mut(5..)); - /// assert_eq!(None, slice.take_mut(..5)); - /// assert_eq!(None, slice.take_mut(..=4)); - /// let expected: &mut [_] = &mut ['a', 'b', 'c', 'd']; - /// assert_eq!(Some(expected), slice.take_mut(..4)); - /// ``` - #[inline] - #[must_use = "method does not modify the slice if the range is out of bounds"] - #[unstable(feature = "slice_take", issue = "62280")] - pub fn take_mut<'a, R: OneSidedRange>( - self: &mut &'a mut Self, - range: R, - ) -> Option<&'a mut Self> { - let (direction, split_index) = split_point_of(range)?; - if split_index > self.len() { - return None; - } - let (front, back) = mem::take(self).split_at_mut(split_index); - match direction { - Direction::Front => { - *self = back; - Some(front) - } - Direction::Back => { - *self = front; - Some(back) - } - } - } - - /// Removes the first element of the slice and returns a reference - /// to it. - /// - /// Returns `None` if the slice is empty. - /// - /// # Examples - /// - /// ``` - /// #![feature(slice_take)] - /// - /// let mut slice: &[_] = &['a', 'b', 'c']; - /// let first = slice.take_first().unwrap(); - /// - /// assert_eq!(slice, &['b', 'c']); - /// assert_eq!(first, &'a'); - /// ``` - #[inline] - #[unstable(feature = "slice_take", issue = "62280")] - pub fn take_first<'a>(self: &mut &'a Self) -> Option<&'a T> { - let (first, rem) = self.split_first()?; - *self = rem; - Some(first) - } - - /// Removes the first element of the slice and returns a mutable - /// reference to it. - /// - /// Returns `None` if the slice is empty. - /// - /// # Examples - /// - /// ``` - /// #![feature(slice_take)] - /// - /// let mut slice: &mut [_] = &mut ['a', 'b', 'c']; - /// let first = slice.take_first_mut().unwrap(); - /// *first = 'd'; - /// - /// assert_eq!(slice, &['b', 'c']); - /// assert_eq!(first, &'d'); - /// ``` - #[inline] - #[unstable(feature = "slice_take", issue = "62280")] - pub fn take_first_mut<'a>(self: &mut &'a mut Self) -> Option<&'a mut T> { - let (first, rem) = mem::take(self).split_first_mut()?; - *self = rem; - Some(first) - } - - /// Removes the last element of the slice and returns a reference - /// to it. - /// - /// Returns `None` if the slice is empty. - /// - /// # Examples - /// - /// ``` - /// #![feature(slice_take)] - /// - /// let mut slice: &[_] = &['a', 'b', 'c']; - /// let last = slice.take_last().unwrap(); - /// - /// assert_eq!(slice, &['a', 'b']); - /// assert_eq!(last, &'c'); - /// ``` - #[inline] - #[unstable(feature = "slice_take", issue = "62280")] - pub fn take_last<'a>(self: &mut &'a Self) -> Option<&'a T> { - let (last, rem) = self.split_last()?; - *self = rem; - Some(last) - } - - /// Removes the last element of the slice and returns a mutable - /// reference to it. - /// - /// Returns `None` if the slice is empty. - /// - /// # Examples - /// - /// ``` - /// #![feature(slice_take)] - /// - /// let mut slice: &mut [_] = &mut ['a', 'b', 'c']; - /// let last = slice.take_last_mut().unwrap(); - /// *last = 'd'; - /// - /// assert_eq!(slice, &['a', 'b']); - /// assert_eq!(last, &'d'); - /// ``` - #[inline] - #[unstable(feature = "slice_take", issue = "62280")] - pub fn take_last_mut<'a>(self: &mut &'a mut Self) -> Option<&'a mut T> { - let (last, rem) = mem::take(self).split_last_mut()?; - *self = rem; - Some(last) - } - - /// Returns mutable references to many indices at once, without doing any checks. - /// - /// For a safe alternative see [`get_many_mut`]. - /// - /// # Safety - /// - /// Calling this method with overlapping or out-of-bounds indices is *[undefined behavior]* - /// even if the resulting references are not used. - /// - /// # Examples - /// - /// ``` - /// #![feature(get_many_mut)] - /// - /// let x = &mut [1, 2, 4]; - /// - /// unsafe { - /// let [a, b] = x.get_many_unchecked_mut([0, 2]); - /// *a *= 10; - /// *b *= 100; - /// } - /// assert_eq!(x, &[10, 2, 400]); - /// ``` - /// - /// [`get_many_mut`]: slice::get_many_mut - /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html - #[unstable(feature = "get_many_mut", issue = "104642")] - #[inline] - pub unsafe fn get_many_unchecked_mut( - &mut self, - indices: [usize; N], - ) -> [&mut T; N] { - // NB: This implementation is written as it is because any variation of - // `indices.map(|i| self.get_unchecked_mut(i))` would make miri unhappy, - // or generate worse code otherwise. This is also why we need to go - // through a raw pointer here. - let slice: *mut [T] = self; - let mut arr: mem::MaybeUninit<[&mut T; N]> = mem::MaybeUninit::uninit(); - let arr_ptr = arr.as_mut_ptr(); - - // SAFETY: We expect `indices` to contain disjunct values that are - // in bounds of `self`. - unsafe { - for i in 0..N { - let idx = *indices.get_unchecked(i); - *(*arr_ptr).get_unchecked_mut(i) = &mut *slice.get_unchecked_mut(idx); - } - arr.assume_init() - } - } - - /// Returns mutable references to many indices at once. - /// - /// Returns an error if any index is out-of-bounds, or if the same index was - /// passed more than once. - /// - /// # Examples - /// - /// ``` - /// #![feature(get_many_mut)] - /// - /// let v = &mut [1, 2, 3]; - /// if let Ok([a, b]) = v.get_many_mut([0, 2]) { - /// *a = 413; - /// *b = 612; - /// } - /// assert_eq!(v, &[413, 2, 612]); - /// ``` - #[unstable(feature = "get_many_mut", issue = "104642")] - #[inline] - pub fn get_many_mut( - &mut self, - indices: [usize; N], - ) -> Result<[&mut T; N], GetManyMutError> { - if !get_many_check_valid(&indices, self.len()) { - return Err(GetManyMutError { _private: () }); - } - // SAFETY: The `get_many_check_valid()` call checked that all indices - // are disjunct and in bounds. - unsafe { Ok(self.get_many_unchecked_mut(indices)) } - } -} - -impl [[T; N]] { - /// Takes a `&[[T; N]]`, and flattens it to a `&[T]`. - /// - /// # Panics - /// - /// This panics if the length of the resulting slice would overflow a `usize`. - /// - /// This is only possible when flattening a slice of arrays of zero-sized - /// types, and thus tends to be irrelevant in practice. If - /// `size_of::() > 0`, this will never panic. - /// - /// # Examples - /// - /// ``` - /// #![feature(slice_flatten)] - /// - /// assert_eq!([[1, 2, 3], [4, 5, 6]].as_flattened(), &[1, 2, 3, 4, 5, 6]); - /// - /// assert_eq!( - /// [[1, 2, 3], [4, 5, 6]].as_flattened(), - /// [[1, 2], [3, 4], [5, 6]].as_flattened(), - /// ); - /// - /// let slice_of_empty_arrays: &[[i32; 0]] = &[[], [], [], [], []]; - /// assert!(slice_of_empty_arrays.as_flattened().is_empty()); - /// - /// let empty_slice_of_arrays: &[[u32; 10]] = &[]; - /// assert!(empty_slice_of_arrays.as_flattened().is_empty()); - /// ``` - #[unstable(feature = "slice_flatten", issue = "95629")] - pub const fn as_flattened(&self) -> &[T] { - let len = if T::IS_ZST { - self.len().checked_mul(N).expect("slice len overflow") - } else { - // SAFETY: `self.len() * N` cannot overflow because `self` is - // already in the address space. - unsafe { self.len().unchecked_mul(N) } - }; - // SAFETY: `[T]` is layout-identical to `[T; N]` - unsafe { from_raw_parts(self.as_ptr().cast(), len) } - } - - /// Takes a `&mut [[T; N]]`, and flattens it to a `&mut [T]`. - /// - /// # Panics - /// - /// This panics if the length of the resulting slice would overflow a `usize`. - /// - /// This is only possible when flattening a slice of arrays of zero-sized - /// types, and thus tends to be irrelevant in practice. If - /// `size_of::() > 0`, this will never panic. - /// - /// # Examples - /// - /// ``` - /// #![feature(slice_flatten)] - /// - /// fn add_5_to_all(slice: &mut [i32]) { - /// for i in slice { - /// *i += 5; - /// } - /// } - /// - /// let mut array = [[1, 2, 3], [4, 5, 6], [7, 8, 9]]; - /// add_5_to_all(array.as_flattened_mut()); - /// assert_eq!(array, [[6, 7, 8], [9, 10, 11], [12, 13, 14]]); - /// ``` - #[unstable(feature = "slice_flatten", issue = "95629")] - pub fn as_flattened_mut(&mut self) -> &mut [T] { - let len = if T::IS_ZST { - self.len().checked_mul(N).expect("slice len overflow") - } else { - // SAFETY: `self.len() * N` cannot overflow because `self` is - // already in the address space. - unsafe { self.len().unchecked_mul(N) } - }; - // SAFETY: `[T]` is layout-identical to `[T; N]` - unsafe { from_raw_parts_mut(self.as_mut_ptr().cast(), len) } - } -} - -#[cfg(not(test))] -impl [f32] { - /// Sorts the slice of floats. - /// - /// This sort is in-place (i.e. does not allocate), *O*(*n* \* log(*n*)) worst-case, and uses - /// the ordering defined by [`f32::total_cmp`]. - /// - /// # Current implementation - /// - /// This uses the same sorting algorithm as [`sort_unstable_by`](slice::sort_unstable_by). - /// - /// # Examples - /// - /// ``` - /// #![feature(sort_floats)] - /// let mut v = [2.6, -5e-8, f32::NAN, 8.29, f32::INFINITY, -1.0, 0.0, -f32::INFINITY, -0.0]; - /// - /// v.sort_floats(); - /// let sorted = [-f32::INFINITY, -1.0, -5e-8, -0.0, 0.0, 2.6, 8.29, f32::INFINITY, f32::NAN]; - /// assert_eq!(&v[..8], &sorted[..8]); - /// assert!(v[8].is_nan()); - /// ``` - #[unstable(feature = "sort_floats", issue = "93396")] - #[inline] - pub fn sort_floats(&mut self) { - self.sort_unstable_by(f32::total_cmp); - } -} - -#[cfg(not(test))] -impl [f64] { - /// Sorts the slice of floats. - /// - /// This sort is in-place (i.e. does not allocate), *O*(*n* \* log(*n*)) worst-case, and uses - /// the ordering defined by [`f64::total_cmp`]. - /// - /// # Current implementation - /// - /// This uses the same sorting algorithm as [`sort_unstable_by`](slice::sort_unstable_by). - /// - /// # Examples - /// - /// ``` - /// #![feature(sort_floats)] - /// let mut v = [2.6, -5e-8, f64::NAN, 8.29, f64::INFINITY, -1.0, 0.0, -f64::INFINITY, -0.0]; - /// - /// v.sort_floats(); - /// let sorted = [-f64::INFINITY, -1.0, -5e-8, -0.0, 0.0, 2.6, 8.29, f64::INFINITY, f64::NAN]; - /// assert_eq!(&v[..8], &sorted[..8]); - /// assert!(v[8].is_nan()); - /// ``` - #[unstable(feature = "sort_floats", issue = "93396")] - #[inline] - pub fn sort_floats(&mut self) { - self.sort_unstable_by(f64::total_cmp); - } -} - -trait CloneFromSpec { - fn spec_clone_from(&mut self, src: &[T]); -} - -impl CloneFromSpec for [T] -where - T: Clone, -{ - #[track_caller] - default fn spec_clone_from(&mut self, src: &[T]) { - assert!(self.len() == src.len(), "destination and source slices have different lengths"); - // NOTE: We need to explicitly slice them to the same length - // to make it easier for the optimizer to elide bounds checking. - // But since it can't be relied on we also have an explicit specialization for T: Copy. - let len = self.len(); - let src = &src[..len]; - for i in 0..len { - self[i].clone_from(&src[i]); - } - } -} - -impl CloneFromSpec for [T] -where - T: Copy, -{ - #[track_caller] - fn spec_clone_from(&mut self, src: &[T]) { - self.copy_from_slice(src); - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Default for &[T] { - /// Creates an empty slice. - fn default() -> Self { - &[] - } -} - -#[stable(feature = "mut_slice_default", since = "1.5.0")] -impl Default for &mut [T] { - /// Creates a mutable empty slice. - fn default() -> Self { - &mut [] - } -} - -#[unstable(feature = "slice_pattern", reason = "stopgap trait for slice patterns", issue = "56345")] -/// Patterns in slices - currently, only used by `strip_prefix` and `strip_suffix`. At a future -/// point, we hope to generalise `core::str::Pattern` (which at the time of writing is limited to -/// `str`) to slices, and then this trait will be replaced or abolished. -pub trait SlicePattern { - /// The element type of the slice being matched on. - type Item; - - /// Currently, the consumers of `SlicePattern` need a slice. - fn as_slice(&self) -> &[Self::Item]; -} - -#[stable(feature = "slice_strip", since = "1.51.0")] -impl SlicePattern for [T] { - type Item = T; - - #[inline] - fn as_slice(&self) -> &[Self::Item] { - self - } -} - -#[stable(feature = "slice_strip", since = "1.51.0")] -impl SlicePattern for [T; N] { - type Item = T; - - #[inline] - fn as_slice(&self) -> &[Self::Item] { - self - } -} - -/// This checks every index against each other, and against `len`. -/// -/// This will do `binomial(N + 1, 2) = N * (N + 1) / 2 = 0, 1, 3, 6, 10, ..` -/// comparison operations. -fn get_many_check_valid(indices: &[usize; N], len: usize) -> bool { - // NB: The optimizer should inline the loops into a sequence - // of instructions without additional branching. - let mut valid = true; - for (i, &idx) in indices.iter().enumerate() { - valid &= idx < len; - for &idx2 in &indices[..i] { - valid &= idx != idx2; - } - } - valid -} - -/// The error type returned by [`get_many_mut`][`slice::get_many_mut`]. -/// -/// It indicates one of two possible errors: -/// - An index is out-of-bounds. -/// - The same index appeared multiple times in the array. -/// -/// # Examples -/// -/// ``` -/// #![feature(get_many_mut)] -/// -/// let v = &mut [1, 2, 3]; -/// assert!(v.get_many_mut([0, 999]).is_err()); -/// assert!(v.get_many_mut([1, 1]).is_err()); -/// ``` -#[unstable(feature = "get_many_mut", issue = "104642")] -// NB: The N here is there to be forward-compatible with adding more details -// to the error type at a later point -pub struct GetManyMutError { - _private: (), -} - -#[unstable(feature = "get_many_mut", issue = "104642")] -impl fmt::Debug for GetManyMutError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("GetManyMutError").finish_non_exhaustive() - } -} - -#[unstable(feature = "get_many_mut", issue = "104642")] -impl fmt::Display for GetManyMutError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt("an index is out of bounds or appeared multiple times in the array", f) - } -} diff --git a/library/core/src/slice/raw.rs b/library/core/src/slice/raw.rs deleted file mode 100644 index 29a12f106c5ed..0000000000000 --- a/library/core/src/slice/raw.rs +++ /dev/null @@ -1,316 +0,0 @@ -//! Free functions to create `&[T]` and `&mut [T]`. - -use crate::array; -use crate::mem::{align_of, size_of}; -use crate::ops::Range; -use crate::ptr; -use crate::ub_checks; - -/// Forms a slice from a pointer and a length. -/// -/// The `len` argument is the number of **elements**, not the number of bytes. -/// -/// # Safety -/// -/// Behavior is undefined if any of the following conditions are violated: -/// -/// * `data` must be [valid] for reads for `len * mem::size_of::()` many bytes, -/// and it must be properly aligned. This means in particular: -/// -/// * The entire memory range of this slice must be contained within a single allocated object! -/// Slices can never span across multiple allocated objects. See [below](#incorrect-usage) -/// for an example incorrectly not taking this into account. -/// * `data` must be non-null and aligned even for zero-length slices. One -/// reason for this is that enum layout optimizations may rely on references -/// (including slices of any length) being aligned and non-null to distinguish -/// them from other data. You can obtain a pointer that is usable as `data` -/// for zero-length slices using [`NonNull::dangling()`]. -/// -/// * `data` must point to `len` consecutive properly initialized values of type `T`. -/// -/// * The memory referenced by the returned slice must not be mutated for the duration -/// of lifetime `'a`, except inside an `UnsafeCell`. -/// -/// * The total size `len * mem::size_of::()` of the slice must be no larger than `isize::MAX`, -/// and adding that size to `data` must not "wrap around" the address space. -/// See the safety documentation of [`pointer::offset`]. -/// -/// # Caveat -/// -/// The lifetime for the returned slice is inferred from its usage. To -/// prevent accidental misuse, it's suggested to tie the lifetime to whichever -/// source lifetime is safe in the context, such as by providing a helper -/// function taking the lifetime of a host value for the slice, or by explicit -/// annotation. -/// -/// # Examples -/// -/// ``` -/// use std::slice; -/// -/// // manifest a slice for a single element -/// let x = 42; -/// let ptr = &x as *const _; -/// let slice = unsafe { slice::from_raw_parts(ptr, 1) }; -/// assert_eq!(slice[0], 42); -/// ``` -/// -/// ### Incorrect usage -/// -/// The following `join_slices` function is **unsound** ⚠️ -/// -/// ```rust,no_run -/// use std::slice; -/// -/// fn join_slices<'a, T>(fst: &'a [T], snd: &'a [T]) -> &'a [T] { -/// let fst_end = fst.as_ptr().wrapping_add(fst.len()); -/// let snd_start = snd.as_ptr(); -/// assert_eq!(fst_end, snd_start, "Slices must be contiguous!"); -/// unsafe { -/// // The assertion above ensures `fst` and `snd` are contiguous, but they might -/// // still be contained within _different allocated objects_, in which case -/// // creating this slice is undefined behavior. -/// slice::from_raw_parts(fst.as_ptr(), fst.len() + snd.len()) -/// } -/// } -/// -/// fn main() { -/// // `a` and `b` are different allocated objects... -/// let a = 42; -/// let b = 27; -/// // ... which may nevertheless be laid out contiguously in memory: | a | b | -/// let _ = join_slices(slice::from_ref(&a), slice::from_ref(&b)); // UB -/// } -/// ``` -/// -/// [valid]: ptr#safety -/// [`NonNull::dangling()`]: ptr::NonNull::dangling -#[inline] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_const_stable(feature = "const_slice_from_raw_parts", since = "1.64.0")] -#[must_use] -#[rustc_diagnostic_item = "slice_from_raw_parts"] -pub const unsafe fn from_raw_parts<'a, T>(data: *const T, len: usize) -> &'a [T] { - // SAFETY: the caller must uphold the safety contract for `from_raw_parts`. - unsafe { - ub_checks::assert_unsafe_precondition!( - check_language_ub, - "slice::from_raw_parts requires the pointer to be aligned and non-null, and the total size of the slice not to exceed `isize::MAX`", - ( - data: *mut () = data as *mut (), - size: usize = size_of::(), - align: usize = align_of::(), - len: usize = len, - ) => - ub_checks::is_aligned_and_not_null(data, align) - && ub_checks::is_valid_allocation_size(size, len) - ); - &*ptr::slice_from_raw_parts(data, len) - } -} - -/// Performs the same functionality as [`from_raw_parts`], except that a -/// mutable slice is returned. -/// -/// # Safety -/// -/// Behavior is undefined if any of the following conditions are violated: -/// -/// * `data` must be [valid] for both reads and writes for `len * mem::size_of::()` many bytes, -/// and it must be properly aligned. This means in particular: -/// -/// * The entire memory range of this slice must be contained within a single allocated object! -/// Slices can never span across multiple allocated objects. -/// * `data` must be non-null and aligned even for zero-length slices. One -/// reason for this is that enum layout optimizations may rely on references -/// (including slices of any length) being aligned and non-null to distinguish -/// them from other data. You can obtain a pointer that is usable as `data` -/// for zero-length slices using [`NonNull::dangling()`]. -/// -/// * `data` must point to `len` consecutive properly initialized values of type `T`. -/// -/// * The memory referenced by the returned slice must not be accessed through any other pointer -/// (not derived from the return value) for the duration of lifetime `'a`. -/// Both read and write accesses are forbidden. -/// -/// * The total size `len * mem::size_of::()` of the slice must be no larger than `isize::MAX`, -/// and adding that size to `data` must not "wrap around" the address space. -/// See the safety documentation of [`pointer::offset`]. -/// -/// [valid]: ptr#safety -/// [`NonNull::dangling()`]: ptr::NonNull::dangling -#[inline] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_const_unstable(feature = "const_slice_from_raw_parts_mut", issue = "67456")] -#[must_use] -#[rustc_diagnostic_item = "slice_from_raw_parts_mut"] -pub const unsafe fn from_raw_parts_mut<'a, T>(data: *mut T, len: usize) -> &'a mut [T] { - // SAFETY: the caller must uphold the safety contract for `from_raw_parts_mut`. - unsafe { - ub_checks::assert_unsafe_precondition!( - check_language_ub, - "slice::from_raw_parts_mut requires the pointer to be aligned and non-null, and the total size of the slice not to exceed `isize::MAX`", - ( - data: *mut () = data as *mut (), - size: usize = size_of::(), - align: usize = align_of::(), - len: usize = len, - ) => - ub_checks::is_aligned_and_not_null(data, align) - && ub_checks::is_valid_allocation_size(size, len) - ); - &mut *ptr::slice_from_raw_parts_mut(data, len) - } -} - -/// Converts a reference to T into a slice of length 1 (without copying). -#[stable(feature = "from_ref", since = "1.28.0")] -#[rustc_const_stable(feature = "const_slice_from_ref_shared", since = "1.63.0")] -#[must_use] -pub const fn from_ref(s: &T) -> &[T] { - array::from_ref(s) -} - -/// Converts a reference to T into a slice of length 1 (without copying). -#[stable(feature = "from_ref", since = "1.28.0")] -#[rustc_const_unstable(feature = "const_slice_from_ref", issue = "90206")] -#[must_use] -pub const fn from_mut(s: &mut T) -> &mut [T] { - array::from_mut(s) -} - -/// Forms a slice from a pointer range. -/// -/// This function is useful for interacting with foreign interfaces which -/// use two pointers to refer to a range of elements in memory, as is -/// common in C++. -/// -/// # Safety -/// -/// Behavior is undefined if any of the following conditions are violated: -/// -/// * The `start` pointer of the range must be a [valid] and properly aligned pointer -/// to the first element of a slice. -/// -/// * The `end` pointer must be a [valid] and properly aligned pointer to *one past* -/// the last element, such that the offset from the end to the start pointer is -/// the length of the slice. -/// -/// * The entire memory range of this slice must be contained within a single allocated object! -/// Slices can never span across multiple allocated objects. -/// -/// * The range must contain `N` consecutive properly initialized values of type `T`. -/// -/// * The memory referenced by the returned slice must not be mutated for the duration -/// of lifetime `'a`, except inside an `UnsafeCell`. -/// -/// * The total length of the range must be no larger than `isize::MAX`, -/// and adding that size to `data` must not "wrap around" the address space. -/// See the safety documentation of [`pointer::offset`]. -/// -/// Note that a range created from [`slice::as_ptr_range`] fulfills these requirements. -/// -/// # Panics -/// -/// This function panics if `T` is a Zero-Sized Type (“ZST”). -/// -/// # Caveat -/// -/// The lifetime for the returned slice is inferred from its usage. To -/// prevent accidental misuse, it's suggested to tie the lifetime to whichever -/// source lifetime is safe in the context, such as by providing a helper -/// function taking the lifetime of a host value for the slice, or by explicit -/// annotation. -/// -/// # Examples -/// -/// ``` -/// #![feature(slice_from_ptr_range)] -/// -/// use core::slice; -/// -/// let x = [1, 2, 3]; -/// let range = x.as_ptr_range(); -/// -/// unsafe { -/// assert_eq!(slice::from_ptr_range(range), &x); -/// } -/// ``` -/// -/// [valid]: ptr#safety -#[unstable(feature = "slice_from_ptr_range", issue = "89792")] -#[rustc_const_unstable(feature = "const_slice_from_ptr_range", issue = "89792")] -pub const unsafe fn from_ptr_range<'a, T>(range: Range<*const T>) -> &'a [T] { - // SAFETY: the caller must uphold the safety contract for `from_ptr_range`. - unsafe { from_raw_parts(range.start, range.end.sub_ptr(range.start)) } -} - -/// Forms a mutable slice from a pointer range. -/// -/// This is the same functionality as [`from_ptr_range`], except that a -/// mutable slice is returned. -/// -/// This function is useful for interacting with foreign interfaces which -/// use two pointers to refer to a range of elements in memory, as is -/// common in C++. -/// -/// # Safety -/// -/// Behavior is undefined if any of the following conditions are violated: -/// -/// * The `start` pointer of the range must be a [valid] and properly aligned pointer -/// to the first element of a slice. -/// -/// * The `end` pointer must be a [valid] and properly aligned pointer to *one past* -/// the last element, such that the offset from the end to the start pointer is -/// the length of the slice. -/// -/// * The entire memory range of this slice must be contained within a single allocated object! -/// Slices can never span across multiple allocated objects. -/// -/// * The range must contain `N` consecutive properly initialized values of type `T`. -/// -/// * The memory referenced by the returned slice must not be accessed through any other pointer -/// (not derived from the return value) for the duration of lifetime `'a`. -/// Both read and write accesses are forbidden. -/// -/// * The total length of the range must be no larger than `isize::MAX`, -/// and adding that size to `data` must not "wrap around" the address space. -/// See the safety documentation of [`pointer::offset`]. -/// -/// Note that a range created from [`slice::as_mut_ptr_range`] fulfills these requirements. -/// -/// # Panics -/// -/// This function panics if `T` is a Zero-Sized Type (“ZST”). -/// -/// # Caveat -/// -/// The lifetime for the returned slice is inferred from its usage. To -/// prevent accidental misuse, it's suggested to tie the lifetime to whichever -/// source lifetime is safe in the context, such as by providing a helper -/// function taking the lifetime of a host value for the slice, or by explicit -/// annotation. -/// -/// # Examples -/// -/// ``` -/// #![feature(slice_from_ptr_range)] -/// -/// use core::slice; -/// -/// let mut x = [1, 2, 3]; -/// let range = x.as_mut_ptr_range(); -/// -/// unsafe { -/// assert_eq!(slice::from_mut_ptr_range(range), &mut [1, 2, 3]); -/// } -/// ``` -/// -/// [valid]: ptr#safety -#[unstable(feature = "slice_from_ptr_range", issue = "89792")] -#[rustc_const_unstable(feature = "const_slice_from_mut_ptr_range", issue = "89792")] -pub const unsafe fn from_mut_ptr_range<'a, T>(range: Range<*mut T>) -> &'a mut [T] { - // SAFETY: the caller must uphold the safety contract for `from_mut_ptr_range`. - unsafe { from_raw_parts_mut(range.start, range.end.sub_ptr(range.start)) } -} diff --git a/library/core/src/slice/rotate.rs b/library/core/src/slice/rotate.rs deleted file mode 100644 index fa8c238f8e7a2..0000000000000 --- a/library/core/src/slice/rotate.rs +++ /dev/null @@ -1,234 +0,0 @@ -use crate::cmp; -use crate::mem::{self, MaybeUninit, SizedTypeProperties}; -use crate::ptr; - -/// Rotates the range `[mid-left, mid+right)` such that the element at `mid` becomes the first -/// element. Equivalently, rotates the range `left` elements to the left or `right` elements to the -/// right. -/// -/// # Safety -/// -/// The specified range must be valid for reading and writing. -/// -/// # Algorithm -/// -/// Algorithm 1 is used for small values of `left + right` or for large `T`. The elements are moved -/// into their final positions one at a time starting at `mid - left` and advancing by `right` steps -/// modulo `left + right`, such that only one temporary is needed. Eventually, we arrive back at -/// `mid - left`. However, if `gcd(left + right, right)` is not 1, the above steps skipped over -/// elements. For example: -/// ```text -/// left = 10, right = 6 -/// the `^` indicates an element in its final place -/// 6 7 8 9 10 11 12 13 14 15 . 0 1 2 3 4 5 -/// after using one step of the above algorithm (The X will be overwritten at the end of the round, -/// and 12 is stored in a temporary): -/// X 7 8 9 10 11 6 13 14 15 . 0 1 2 3 4 5 -/// ^ -/// after using another step (now 2 is in the temporary): -/// X 7 8 9 10 11 6 13 14 15 . 0 1 12 3 4 5 -/// ^ ^ -/// after the third step (the steps wrap around, and 8 is in the temporary): -/// X 7 2 9 10 11 6 13 14 15 . 0 1 12 3 4 5 -/// ^ ^ ^ -/// after 7 more steps, the round ends with the temporary 0 getting put in the X: -/// 0 7 2 9 4 11 6 13 8 15 . 10 1 12 3 14 5 -/// ^ ^ ^ ^ ^ ^ ^ ^ -/// ``` -/// Fortunately, the number of skipped over elements between finalized elements is always equal, so -/// we can just offset our starting position and do more rounds (the total number of rounds is the -/// `gcd(left + right, right)` value). The end result is that all elements are finalized once and -/// only once. -/// -/// Algorithm 2 is used if `left + right` is large but `min(left, right)` is small enough to -/// fit onto a stack buffer. The `min(left, right)` elements are copied onto the buffer, `memmove` -/// is applied to the others, and the ones on the buffer are moved back into the hole on the -/// opposite side of where they originated. -/// -/// Algorithms that can be vectorized outperform the above once `left + right` becomes large enough. -/// Algorithm 1 can be vectorized by chunking and performing many rounds at once, but there are too -/// few rounds on average until `left + right` is enormous, and the worst case of a single -/// round is always there. Instead, algorithm 3 utilizes repeated swapping of -/// `min(left, right)` elements until a smaller rotate problem is left. -/// -/// ```text -/// left = 11, right = 4 -/// [4 5 6 7 8 9 10 11 12 13 14 . 0 1 2 3] -/// ^ ^ ^ ^ ^ ^ ^ ^ swapping the right most elements with elements to the left -/// [4 5 6 7 8 9 10 . 0 1 2 3] 11 12 13 14 -/// ^ ^ ^ ^ ^ ^ ^ ^ swapping these -/// [4 5 6 . 0 1 2 3] 7 8 9 10 11 12 13 14 -/// we cannot swap any more, but a smaller rotation problem is left to solve -/// ``` -/// when `left < right` the swapping happens from the left instead. -pub unsafe fn ptr_rotate(mut left: usize, mut mid: *mut T, mut right: usize) { - type BufType = [usize; 32]; - if T::IS_ZST { - return; - } - loop { - // N.B. the below algorithms can fail if these cases are not checked - if (right == 0) || (left == 0) { - return; - } - if (left + right < 24) || (mem::size_of::() > mem::size_of::<[usize; 4]>()) { - // Algorithm 1 - // Microbenchmarks indicate that the average performance for random shifts is better all - // the way until about `left + right == 32`, but the worst case performance breaks even - // around 16. 24 was chosen as middle ground. If the size of `T` is larger than 4 - // `usize`s, this algorithm also outperforms other algorithms. - // SAFETY: callers must ensure `mid - left` is valid for reading and writing. - let x = unsafe { mid.sub(left) }; - // beginning of first round - // SAFETY: see previous comment. - let mut tmp: T = unsafe { x.read() }; - let mut i = right; - // `gcd` can be found before hand by calculating `gcd(left + right, right)`, - // but it is faster to do one loop which calculates the gcd as a side effect, then - // doing the rest of the chunk - let mut gcd = right; - // benchmarks reveal that it is faster to swap temporaries all the way through instead - // of reading one temporary once, copying backwards, and then writing that temporary at - // the very end. This is possibly due to the fact that swapping or replacing temporaries - // uses only one memory address in the loop instead of needing to manage two. - loop { - // [long-safety-expl] - // SAFETY: callers must ensure `[left, left+mid+right)` are all valid for reading and - // writing. - // - // - `i` start with `right` so `mid-left <= x+i = x+right = mid-left+right < mid+right` - // - `i <= left+right-1` is always true - // - if `i < left`, `right` is added so `i < left+right` and on the next - // iteration `left` is removed from `i` so it doesn't go further - // - if `i >= left`, `left` is removed immediately and so it doesn't go further. - // - overflows cannot happen for `i` since the function's safety contract ask for - // `mid+right-1 = x+left+right` to be valid for writing - // - underflows cannot happen because `i` must be bigger or equal to `left` for - // a subtraction of `left` to happen. - // - // So `x+i` is valid for reading and writing if the caller respected the contract - tmp = unsafe { x.add(i).replace(tmp) }; - // instead of incrementing `i` and then checking if it is outside the bounds, we - // check if `i` will go outside the bounds on the next increment. This prevents - // any wrapping of pointers or `usize`. - if i >= left { - i -= left; - if i == 0 { - // end of first round - // SAFETY: tmp has been read from a valid source and x is valid for writing - // according to the caller. - unsafe { x.write(tmp) }; - break; - } - // this conditional must be here if `left + right >= 15` - if i < gcd { - gcd = i; - } - } else { - i += right; - } - } - // finish the chunk with more rounds - for start in 1..gcd { - // SAFETY: `gcd` is at most equal to `right` so all values in `1..gcd` are valid for - // reading and writing as per the function's safety contract, see [long-safety-expl] - // above - tmp = unsafe { x.add(start).read() }; - // [safety-expl-addition] - // - // Here `start < gcd` so `start < right` so `i < right+right`: `right` being the - // greatest common divisor of `(left+right, right)` means that `left = right` so - // `i < left+right` so `x+i = mid-left+i` is always valid for reading and writing - // according to the function's safety contract. - i = start + right; - loop { - // SAFETY: see [long-safety-expl] and [safety-expl-addition] - tmp = unsafe { x.add(i).replace(tmp) }; - if i >= left { - i -= left; - if i == start { - // SAFETY: see [long-safety-expl] and [safety-expl-addition] - unsafe { x.add(start).write(tmp) }; - break; - } - } else { - i += right; - } - } - } - return; - // `T` is not a zero-sized type, so it's okay to divide by its size. - } else if cmp::min(left, right) <= mem::size_of::() / mem::size_of::() { - // Algorithm 2 - // The `[T; 0]` here is to ensure this is appropriately aligned for T - let mut rawarray = MaybeUninit::<(BufType, [T; 0])>::uninit(); - let buf = rawarray.as_mut_ptr() as *mut T; - // SAFETY: `mid-left <= mid-left+right < mid+right` - let dim = unsafe { mid.sub(left).add(right) }; - if left <= right { - // SAFETY: - // - // 1) The `else if` condition about the sizes ensures `[mid-left; left]` will fit in - // `buf` without overflow and `buf` was created just above and so cannot be - // overlapped with any value of `[mid-left; left]` - // 2) [mid-left, mid+right) are all valid for reading and writing and we don't care - // about overlaps here. - // 3) The `if` condition about `left <= right` ensures writing `left` elements to - // `dim = mid-left+right` is valid because: - // - `buf` is valid and `left` elements were written in it in 1) - // - `dim+left = mid-left+right+left = mid+right` and we write `[dim, dim+left)` - unsafe { - // 1) - ptr::copy_nonoverlapping(mid.sub(left), buf, left); - // 2) - ptr::copy(mid, mid.sub(left), right); - // 3) - ptr::copy_nonoverlapping(buf, dim, left); - } - } else { - // SAFETY: same reasoning as above but with `left` and `right` reversed - unsafe { - ptr::copy_nonoverlapping(mid, buf, right); - ptr::copy(mid.sub(left), dim, left); - ptr::copy_nonoverlapping(buf, mid.sub(left), right); - } - } - return; - } else if left >= right { - // Algorithm 3 - // There is an alternate way of swapping that involves finding where the last swap - // of this algorithm would be, and swapping using that last chunk instead of swapping - // adjacent chunks like this algorithm is doing, but this way is still faster. - loop { - // SAFETY: - // `left >= right` so `[mid-right, mid+right)` is valid for reading and writing - // Subtracting `right` from `mid` each turn is counterbalanced by the addition and - // check after it. - unsafe { - ptr::swap_nonoverlapping(mid.sub(right), mid, right); - mid = mid.sub(right); - } - left -= right; - if left < right { - break; - } - } - } else { - // Algorithm 3, `left < right` - loop { - // SAFETY: `[mid-left, mid+left)` is valid for reading and writing because - // `left < right` so `mid+left < mid+right`. - // Adding `left` to `mid` each turn is counterbalanced by the subtraction and check - // after it. - unsafe { - ptr::swap_nonoverlapping(mid.sub(left), mid, left); - mid = mid.add(left); - } - right -= left; - if right < left { - break; - } - } - } - } -} diff --git a/library/core/src/slice/select.rs b/library/core/src/slice/select.rs deleted file mode 100644 index ffc193578e075..0000000000000 --- a/library/core/src/slice/select.rs +++ /dev/null @@ -1,302 +0,0 @@ -//! Slice selection -//! -//! This module contains the implementation for `slice::select_nth_unstable`. -//! It uses an introselect algorithm based on Orson Peters' pattern-defeating quicksort, -//! published at: -//! -//! The fallback algorithm used for introselect is Median of Medians using Tukey's Ninther -//! for pivot selection. Using this as a fallback ensures O(n) worst case running time with -//! better performance than one would get using heapsort as fallback. - -use crate::cmp; -use crate::mem::{self, SizedTypeProperties}; -use crate::slice::sort::{ - break_patterns, choose_pivot, insertion_sort_shift_left, partition, partition_equal, -}; - -// For slices of up to this length it's probably faster to simply sort them. -// Defined at the module scope because it's used in multiple functions. -const MAX_INSERTION: usize = 10; - -fn partition_at_index_loop<'a, T, F>( - mut v: &'a mut [T], - mut index: usize, - is_less: &mut F, - mut pred: Option<&'a T>, -) where - F: FnMut(&T, &T) -> bool, -{ - // Limit the amount of iterations and fall back to fast deterministic selection - // to ensure O(n) worst case running time. This limit needs to be constant, because - // using `ilog2(len)` like in `sort` would result in O(n log n) time complexity. - // The exact value of the limit is chosen somewhat arbitrarily, but for most inputs bad pivot - // selections should be relatively rare, so the limit usually shouldn't be reached - // anyways. - let mut limit = 16; - - // True if the last partitioning was reasonably balanced. - let mut was_balanced = true; - - loop { - if v.len() <= MAX_INSERTION { - if v.len() > 1 { - insertion_sort_shift_left(v, 1, is_less); - } - return; - } - - if limit == 0 { - median_of_medians(v, is_less, index); - return; - } - - // If the last partitioning was imbalanced, try breaking patterns in the slice by shuffling - // some elements around. Hopefully we'll choose a better pivot this time. - if !was_balanced { - break_patterns(v); - limit -= 1; - } - - // Choose a pivot - let (pivot, _) = choose_pivot(v, is_less); - - // If the chosen pivot is equal to the predecessor, then it's the smallest element in the - // slice. Partition the slice into elements equal to and elements greater than the pivot. - // This case is usually hit when the slice contains many duplicate elements. - if let Some(p) = pred { - if !is_less(p, &v[pivot]) { - let mid = partition_equal(v, pivot, is_less); - - // If we've passed our index, then we're good. - if mid > index { - return; - } - - // Otherwise, continue sorting elements greater than the pivot. - v = &mut v[mid..]; - index = index - mid; - pred = None; - continue; - } - } - - let (mid, _) = partition(v, pivot, is_less); - was_balanced = cmp::min(mid, v.len() - mid) >= v.len() / 8; - - // Split the slice into `left`, `pivot`, and `right`. - let (left, right) = v.split_at_mut(mid); - let (pivot, right) = right.split_at_mut(1); - let pivot = &pivot[0]; - - if mid < index { - v = right; - index = index - mid - 1; - pred = Some(pivot); - } else if mid > index { - v = left; - } else { - // If mid == index, then we're done, since partition() guaranteed that all elements - // after mid are greater than or equal to mid. - return; - } - } -} - -/// Helper function that returns the index of the minimum element in the slice using the given -/// comparator function -fn min_index bool>(slice: &[T], is_less: &mut F) -> Option { - slice - .iter() - .enumerate() - .reduce(|acc, t| if is_less(t.1, acc.1) { t } else { acc }) - .map(|(i, _)| i) -} - -/// Helper function that returns the index of the maximum element in the slice using the given -/// comparator function -fn max_index bool>(slice: &[T], is_less: &mut F) -> Option { - slice - .iter() - .enumerate() - .reduce(|acc, t| if is_less(acc.1, t.1) { t } else { acc }) - .map(|(i, _)| i) -} - -/// Reorder the slice such that the element at `index` is at its final sorted position. -pub fn partition_at_index( - v: &mut [T], - index: usize, - mut is_less: F, -) -> (&mut [T], &mut T, &mut [T]) -where - F: FnMut(&T, &T) -> bool, -{ - if index >= v.len() { - panic!("partition_at_index index {} greater than length of slice {}", index, v.len()); - } - - if T::IS_ZST { - // Sorting has no meaningful behavior on zero-sized types. Do nothing. - } else if index == v.len() - 1 { - // Find max element and place it in the last position of the array. We're free to use - // `unwrap()` here because we know v must not be empty. - let max_idx = max_index(v, &mut is_less).unwrap(); - v.swap(max_idx, index); - } else if index == 0 { - // Find min element and place it in the first position of the array. We're free to use - // `unwrap()` here because we know v must not be empty. - let min_idx = min_index(v, &mut is_less).unwrap(); - v.swap(min_idx, index); - } else { - partition_at_index_loop(v, index, &mut is_less, None); - } - - let (left, right) = v.split_at_mut(index); - let (pivot, right) = right.split_at_mut(1); - let pivot = &mut pivot[0]; - (left, pivot, right) -} - -/// Selection algorithm to select the k-th element from the slice in guaranteed O(n) time. -/// This is essentially a quickselect that uses Tukey's Ninther for pivot selection -fn median_of_medians bool>(mut v: &mut [T], is_less: &mut F, mut k: usize) { - // Since this function isn't public, it should never be called with an out-of-bounds index. - debug_assert!(k < v.len()); - - // If T is as ZST, `partition_at_index` will already return early. - debug_assert!(!T::IS_ZST); - - // We now know that `k < v.len() <= isize::MAX` - loop { - if v.len() <= MAX_INSERTION { - if v.len() > 1 { - insertion_sort_shift_left(v, 1, is_less); - } - return; - } - - // `median_of_{minima,maxima}` can't handle the extreme cases of the first/last element, - // so we catch them here and just do a linear search. - if k == v.len() - 1 { - // Find max element and place it in the last position of the array. We're free to use - // `unwrap()` here because we know v must not be empty. - let max_idx = max_index(v, is_less).unwrap(); - v.swap(max_idx, k); - return; - } else if k == 0 { - // Find min element and place it in the first position of the array. We're free to use - // `unwrap()` here because we know v must not be empty. - let min_idx = min_index(v, is_less).unwrap(); - v.swap(min_idx, k); - return; - } - - let p = median_of_ninthers(v, is_less); - - if p == k { - return; - } else if p > k { - v = &mut v[..p]; - } else { - // Since `p < k < v.len()`, `p + 1` doesn't overflow and is - // a valid index into the slice. - v = &mut v[p + 1..]; - k -= p + 1; - } - } -} - -// Optimized for when `k` lies somewhere in the middle of the slice. Selects a pivot -// as close as possible to the median of the slice. For more details on how the algorithm -// operates, refer to the paper . -fn median_of_ninthers bool>(v: &mut [T], is_less: &mut F) -> usize { - // use `saturating_mul` so the multiplication doesn't overflow on 16-bit platforms. - let frac = if v.len() <= 1024 { - v.len() / 12 - } else if v.len() <= 128_usize.saturating_mul(1024) { - v.len() / 64 - } else { - v.len() / 1024 - }; - - let pivot = frac / 2; - let lo = v.len() / 2 - pivot; - let hi = frac + lo; - let gap = (v.len() - 9 * frac) / 4; - let mut a = lo - 4 * frac - gap; - let mut b = hi + gap; - for i in lo..hi { - ninther(v, is_less, a, i - frac, b, a + 1, i, b + 1, a + 2, i + frac, b + 2); - a += 3; - b += 3; - } - - median_of_medians(&mut v[lo..lo + frac], is_less, pivot); - partition(v, lo + pivot, is_less).0 -} - -/// Moves around the 9 elements at the indices a..i, such that -/// `v[d]` contains the median of the 9 elements and the other -/// elements are partitioned around it. -fn ninther bool>( - v: &mut [T], - is_less: &mut F, - a: usize, - mut b: usize, - c: usize, - mut d: usize, - e: usize, - mut f: usize, - g: usize, - mut h: usize, - i: usize, -) { - b = median_idx(v, is_less, a, b, c); - h = median_idx(v, is_less, g, h, i); - if is_less(&v[h], &v[b]) { - mem::swap(&mut b, &mut h); - } - if is_less(&v[f], &v[d]) { - mem::swap(&mut d, &mut f); - } - if is_less(&v[e], &v[d]) { - // do nothing - } else if is_less(&v[f], &v[e]) { - d = f; - } else { - if is_less(&v[e], &v[b]) { - v.swap(e, b); - } else if is_less(&v[h], &v[e]) { - v.swap(e, h); - } - return; - } - if is_less(&v[d], &v[b]) { - d = b; - } else if is_less(&v[h], &v[d]) { - d = h; - } - - v.swap(d, e); -} - -/// returns the index pointing to the median of the 3 -/// elements `v[a]`, `v[b]` and `v[c]` -fn median_idx bool>( - v: &[T], - is_less: &mut F, - mut a: usize, - b: usize, - mut c: usize, -) -> usize { - if is_less(&v[c], &v[a]) { - mem::swap(&mut a, &mut c); - } - if is_less(&v[c], &v[b]) { - return c; - } - if is_less(&v[b], &v[a]) { - return a; - } - b -} diff --git a/library/core/src/slice/sort.rs b/library/core/src/slice/sort.rs deleted file mode 100644 index 993a608f42b60..0000000000000 --- a/library/core/src/slice/sort.rs +++ /dev/null @@ -1,1383 +0,0 @@ -//! Slice sorting -//! -//! This module contains a sorting algorithm based on Orson Peters' pattern-defeating quicksort, -//! published at: -//! -//! Unstable sorting is compatible with core because it doesn't allocate memory, unlike our -//! stable sorting implementation. -//! -//! In addition it also contains the core logic of the stable sort used by `slice::sort` based on -//! TimSort. - -use crate::cmp; -use crate::mem::{self, MaybeUninit, SizedTypeProperties}; -use crate::ptr; - -// When dropped, copies from `src` into `dest`. -struct InsertionHole { - src: *const T, - dest: *mut T, -} - -impl Drop for InsertionHole { - fn drop(&mut self) { - // SAFETY: This is a helper class. Please refer to its usage for correctness. Namely, one - // must be sure that `src` and `dst` does not overlap as required by - // `ptr::copy_nonoverlapping` and are both valid for writes. - unsafe { - ptr::copy_nonoverlapping(self.src, self.dest, 1); - } - } -} - -/// Inserts `v[v.len() - 1]` into pre-sorted sequence `v[..v.len() - 1]` so that whole `v[..]` -/// becomes sorted. -unsafe fn insert_tail(v: &mut [T], is_less: &mut F) -where - F: FnMut(&T, &T) -> bool, -{ - debug_assert!(v.len() >= 2); - - let arr_ptr = v.as_mut_ptr(); - let i = v.len() - 1; - - // SAFETY: caller must ensure v is at least len 2. - unsafe { - // See insert_head which talks about why this approach is beneficial. - let i_ptr = arr_ptr.add(i); - - // It's important that we use i_ptr here. If this check is positive and we continue, - // We want to make sure that no other copy of the value was seen by is_less. - // Otherwise we would have to copy it back. - if is_less(&*i_ptr, &*i_ptr.sub(1)) { - // It's important, that we use tmp for comparison from now on. As it is the value that - // will be copied back. And notionally we could have created a divergence if we copy - // back the wrong value. - let tmp = mem::ManuallyDrop::new(ptr::read(i_ptr)); - // Intermediate state of the insertion process is always tracked by `hole`, which - // serves two purposes: - // 1. Protects integrity of `v` from panics in `is_less`. - // 2. Fills the remaining hole in `v` in the end. - // - // Panic safety: - // - // If `is_less` panics at any point during the process, `hole` will get dropped and - // fill the hole in `v` with `tmp`, thus ensuring that `v` still holds every object it - // initially held exactly once. - let mut hole = InsertionHole { src: &*tmp, dest: i_ptr.sub(1) }; - ptr::copy_nonoverlapping(hole.dest, i_ptr, 1); - - // SAFETY: We know i is at least 1. - for j in (0..(i - 1)).rev() { - let j_ptr = arr_ptr.add(j); - if !is_less(&*tmp, &*j_ptr) { - break; - } - - ptr::copy_nonoverlapping(j_ptr, hole.dest, 1); - hole.dest = j_ptr; - } - // `hole` gets dropped and thus copies `tmp` into the remaining hole in `v`. - } - } -} - -/// Inserts `v[0]` into pre-sorted sequence `v[1..]` so that whole `v[..]` becomes sorted. -/// -/// This is the integral subroutine of insertion sort. -unsafe fn insert_head(v: &mut [T], is_less: &mut F) -where - F: FnMut(&T, &T) -> bool, -{ - debug_assert!(v.len() >= 2); - - // SAFETY: caller must ensure v is at least len 2. - unsafe { - if is_less(v.get_unchecked(1), v.get_unchecked(0)) { - let arr_ptr = v.as_mut_ptr(); - - // There are three ways to implement insertion here: - // - // 1. Swap adjacent elements until the first one gets to its final destination. - // However, this way we copy data around more than is necessary. If elements are big - // structures (costly to copy), this method will be slow. - // - // 2. Iterate until the right place for the first element is found. Then shift the - // elements succeeding it to make room for it and finally place it into the - // remaining hole. This is a good method. - // - // 3. Copy the first element into a temporary variable. Iterate until the right place - // for it is found. As we go along, copy every traversed element into the slot - // preceding it. Finally, copy data from the temporary variable into the remaining - // hole. This method is very good. Benchmarks demonstrated slightly better - // performance than with the 2nd method. - // - // All methods were benchmarked, and the 3rd showed best results. So we chose that one. - let tmp = mem::ManuallyDrop::new(ptr::read(arr_ptr)); - - // Intermediate state of the insertion process is always tracked by `hole`, which - // serves two purposes: - // 1. Protects integrity of `v` from panics in `is_less`. - // 2. Fills the remaining hole in `v` in the end. - // - // Panic safety: - // - // If `is_less` panics at any point during the process, `hole` will get dropped and - // fill the hole in `v` with `tmp`, thus ensuring that `v` still holds every object it - // initially held exactly once. - let mut hole = InsertionHole { src: &*tmp, dest: arr_ptr.add(1) }; - ptr::copy_nonoverlapping(arr_ptr.add(1), arr_ptr.add(0), 1); - - for i in 2..v.len() { - if !is_less(&v.get_unchecked(i), &*tmp) { - break; - } - ptr::copy_nonoverlapping(arr_ptr.add(i), arr_ptr.add(i - 1), 1); - hole.dest = arr_ptr.add(i); - } - // `hole` gets dropped and thus copies `tmp` into the remaining hole in `v`. - } - } -} - -/// Sort `v` assuming `v[..offset]` is already sorted. -/// -/// Never inline this function to avoid code bloat. It still optimizes nicely and has practically no -/// performance impact. Even improving performance in some cases. -#[inline(never)] -pub(super) fn insertion_sort_shift_left(v: &mut [T], offset: usize, is_less: &mut F) -where - F: FnMut(&T, &T) -> bool, -{ - let len = v.len(); - - // Using assert here improves performance. - assert!(offset != 0 && offset <= len); - - // Shift each element of the unsorted region v[i..] as far left as is needed to make v sorted. - for i in offset..len { - // SAFETY: we tested that `offset` must be at least 1, so this loop is only entered if len - // >= 2. The range is exclusive and we know `i` must be at least 1 so this slice has at - // >least len 2. - unsafe { - insert_tail(&mut v[..=i], is_less); - } - } -} - -/// Sort `v` assuming `v[offset..]` is already sorted. -/// -/// Never inline this function to avoid code bloat. It still optimizes nicely and has practically no -/// performance impact. Even improving performance in some cases. -#[inline(never)] -fn insertion_sort_shift_right(v: &mut [T], offset: usize, is_less: &mut F) -where - F: FnMut(&T, &T) -> bool, -{ - let len = v.len(); - - // Using assert here improves performance. - assert!(offset != 0 && offset <= len && len >= 2); - - // Shift each element of the unsorted region v[..i] as far left as is needed to make v sorted. - for i in (0..offset).rev() { - // SAFETY: we tested that `offset` must be at least 1, so this loop is only entered if len - // >= 2.We ensured that the slice length is always at least 2 long. We know that start_found - // will be at least one less than end, and the range is exclusive. Which gives us i always - // <= (end - 2). - unsafe { - insert_head(&mut v[i..len], is_less); - } - } -} - -/// Partially sorts a slice by shifting several out-of-order elements around. -/// -/// Returns `true` if the slice is sorted at the end. This function is *O*(*n*) worst-case. -#[cold] -fn partial_insertion_sort(v: &mut [T], is_less: &mut F) -> bool -where - F: FnMut(&T, &T) -> bool, -{ - // Maximum number of adjacent out-of-order pairs that will get shifted. - const MAX_STEPS: usize = 5; - // If the slice is shorter than this, don't shift any elements. - const SHORTEST_SHIFTING: usize = 50; - - let len = v.len(); - let mut i = 1; - - for _ in 0..MAX_STEPS { - // SAFETY: We already explicitly did the bound checking with `i < len`. - // All our subsequent indexing is only in the range `0 <= index < len` - unsafe { - // Find the next pair of adjacent out-of-order elements. - while i < len && !is_less(v.get_unchecked(i), v.get_unchecked(i - 1)) { - i += 1; - } - } - - // Are we done? - if i == len { - return true; - } - - // Don't shift elements on short arrays, that has a performance cost. - if len < SHORTEST_SHIFTING { - return false; - } - - // Swap the found pair of elements. This puts them in correct order. - v.swap(i - 1, i); - - if i >= 2 { - // Shift the smaller element to the left. - insertion_sort_shift_left(&mut v[..i], i - 1, is_less); - - // Shift the greater element to the right. - insertion_sort_shift_right(&mut v[..i], 1, is_less); - } - } - - // Didn't manage to sort the slice in the limited number of steps. - false -} - -/// Sorts `v` using heapsort, which guarantees *O*(*n* \* log(*n*)) worst-case. -#[cold] -#[unstable(feature = "sort_internals", reason = "internal to sort module", issue = "none")] -pub fn heapsort(v: &mut [T], mut is_less: F) -where - F: FnMut(&T, &T) -> bool, -{ - // This binary heap respects the invariant `parent >= child`. - let mut sift_down = |v: &mut [T], mut node| { - loop { - // Children of `node`. - let mut child = 2 * node + 1; - if child >= v.len() { - break; - } - - // Choose the greater child. - if child + 1 < v.len() { - // We need a branch to be sure not to out-of-bounds index, - // but it's highly predictable. The comparison, however, - // is better done branchless, especially for primitives. - child += is_less(&v[child], &v[child + 1]) as usize; - } - - // Stop if the invariant holds at `node`. - if !is_less(&v[node], &v[child]) { - break; - } - - // Swap `node` with the greater child, move one step down, and continue sifting. - v.swap(node, child); - node = child; - } - }; - - // Build the heap in linear time. - for i in (0..v.len() / 2).rev() { - sift_down(v, i); - } - - // Pop maximal elements from the heap. - for i in (1..v.len()).rev() { - v.swap(0, i); - sift_down(&mut v[..i], 0); - } -} - -/// Partitions `v` into elements smaller than `pivot`, followed by elements greater than or equal -/// to `pivot`. -/// -/// Returns the number of elements smaller than `pivot`. -/// -/// Partitioning is performed block-by-block in order to minimize the cost of branching operations. -/// This idea is presented in the [BlockQuicksort][pdf] paper. -/// -/// [pdf]: https://drops.dagstuhl.de/opus/volltexte/2016/6389/pdf/LIPIcs-ESA-2016-38.pdf -fn partition_in_blocks(v: &mut [T], pivot: &T, is_less: &mut F) -> usize -where - F: FnMut(&T, &T) -> bool, -{ - // Number of elements in a typical block. - const BLOCK: usize = 128; - - // The partitioning algorithm repeats the following steps until completion: - // - // 1. Trace a block from the left side to identify elements greater than or equal to the pivot. - // 2. Trace a block from the right side to identify elements smaller than the pivot. - // 3. Exchange the identified elements between the left and right side. - // - // We keep the following variables for a block of elements: - // - // 1. `block` - Number of elements in the block. - // 2. `start` - Start pointer into the `offsets` array. - // 3. `end` - End pointer into the `offsets` array. - // 4. `offsets` - Indices of out-of-order elements within the block. - - // The current block on the left side (from `l` to `l.add(block_l)`). - let mut l = v.as_mut_ptr(); - let mut block_l = BLOCK; - let mut start_l = ptr::null_mut(); - let mut end_l = ptr::null_mut(); - let mut offsets_l = [MaybeUninit::::uninit(); BLOCK]; - - // The current block on the right side (from `r.sub(block_r)` to `r`). - // SAFETY: The documentation for .add() specifically mention that `vec.as_ptr().add(vec.len())` is always safe - let mut r = unsafe { l.add(v.len()) }; - let mut block_r = BLOCK; - let mut start_r = ptr::null_mut(); - let mut end_r = ptr::null_mut(); - let mut offsets_r = [MaybeUninit::::uninit(); BLOCK]; - - // FIXME: When we get VLAs, try creating one array of length `min(v.len(), 2 * BLOCK)` rather - // than two fixed-size arrays of length `BLOCK`. VLAs might be more cache-efficient. - - // Returns the number of elements between pointers `l` (inclusive) and `r` (exclusive). - fn width(l: *mut T, r: *mut T) -> usize { - assert!(mem::size_of::() > 0); - // FIXME: this should *likely* use `offset_from`, but more - // investigation is needed (including running tests in miri). - (r.addr() - l.addr()) / mem::size_of::() - } - - loop { - // We are done with partitioning block-by-block when `l` and `r` get very close. Then we do - // some patch-up work in order to partition the remaining elements in between. - let is_done = width(l, r) <= 2 * BLOCK; - - if is_done { - // Number of remaining elements (still not compared to the pivot). - let mut rem = width(l, r); - if start_l < end_l || start_r < end_r { - rem -= BLOCK; - } - - // Adjust block sizes so that the left and right block don't overlap, but get perfectly - // aligned to cover the whole remaining gap. - if start_l < end_l { - block_r = rem; - } else if start_r < end_r { - block_l = rem; - } else { - // There were the same number of elements to switch on both blocks during the last - // iteration, so there are no remaining elements on either block. Cover the remaining - // items with roughly equally-sized blocks. - block_l = rem / 2; - block_r = rem - block_l; - } - debug_assert!(block_l <= BLOCK && block_r <= BLOCK); - debug_assert!(width(l, r) == block_l + block_r); - } - - if start_l == end_l { - // Trace `block_l` elements from the left side. - start_l = MaybeUninit::slice_as_mut_ptr(&mut offsets_l); - end_l = start_l; - let mut elem = l; - - for i in 0..block_l { - // SAFETY: The unsafety operations below involve the usage of the `offset`. - // According to the conditions required by the function, we satisfy them because: - // 1. `offsets_l` is stack-allocated, and thus considered separate allocated object. - // 2. The function `is_less` returns a `bool`. - // Casting a `bool` will never overflow `isize`. - // 3. We have guaranteed that `block_l` will be `<= BLOCK`. - // Plus, `end_l` was initially set to the begin pointer of `offsets_` which was declared on the stack. - // Thus, we know that even in the worst case (all invocations of `is_less` returns false) we will only be at most 1 byte pass the end. - // Another unsafety operation here is dereferencing `elem`. - // However, `elem` was initially the begin pointer to the slice which is always valid. - unsafe { - // Branchless comparison. - *end_l = i as u8; - end_l = end_l.add(!is_less(&*elem, pivot) as usize); - elem = elem.add(1); - } - } - } - - if start_r == end_r { - // Trace `block_r` elements from the right side. - start_r = MaybeUninit::slice_as_mut_ptr(&mut offsets_r); - end_r = start_r; - let mut elem = r; - - for i in 0..block_r { - // SAFETY: The unsafety operations below involve the usage of the `offset`. - // According to the conditions required by the function, we satisfy them because: - // 1. `offsets_r` is stack-allocated, and thus considered separate allocated object. - // 2. The function `is_less` returns a `bool`. - // Casting a `bool` will never overflow `isize`. - // 3. We have guaranteed that `block_r` will be `<= BLOCK`. - // Plus, `end_r` was initially set to the begin pointer of `offsets_` which was declared on the stack. - // Thus, we know that even in the worst case (all invocations of `is_less` returns true) we will only be at most 1 byte pass the end. - // Another unsafety operation here is dereferencing `elem`. - // However, `elem` was initially `1 * sizeof(T)` past the end and we decrement it by `1 * sizeof(T)` before accessing it. - // Plus, `block_r` was asserted to be less than `BLOCK` and `elem` will therefore at most be pointing to the beginning of the slice. - unsafe { - // Branchless comparison. - elem = elem.sub(1); - *end_r = i as u8; - end_r = end_r.add(is_less(&*elem, pivot) as usize); - } - } - } - - // Number of out-of-order elements to swap between the left and right side. - let count = cmp::min(width(start_l, end_l), width(start_r, end_r)); - - if count > 0 { - macro_rules! left { - () => { - l.add(usize::from(*start_l)) - }; - } - macro_rules! right { - () => { - r.sub(usize::from(*start_r) + 1) - }; - } - - // Instead of swapping one pair at the time, it is more efficient to perform a cyclic - // permutation. This is not strictly equivalent to swapping, but produces a similar - // result using fewer memory operations. - - // SAFETY: The use of `ptr::read` is valid because there is at least one element in - // both `offsets_l` and `offsets_r`, so `left!` is a valid pointer to read from. - // - // The uses of `left!` involve calls to `offset` on `l`, which points to the - // beginning of `v`. All the offsets pointed-to by `start_l` are at most `block_l`, so - // these `offset` calls are safe as all reads are within the block. The same argument - // applies for the uses of `right!`. - // - // The calls to `start_l.offset` are valid because there are at most `count-1` of them, - // plus the final one at the end of the unsafe block, where `count` is the minimum number - // of collected offsets in `offsets_l` and `offsets_r`, so there is no risk of there not - // being enough elements. The same reasoning applies to the calls to `start_r.offset`. - // - // The calls to `copy_nonoverlapping` are safe because `left!` and `right!` are guaranteed - // not to overlap, and are valid because of the reasoning above. - unsafe { - let tmp = ptr::read(left!()); - ptr::copy_nonoverlapping(right!(), left!(), 1); - - for _ in 1..count { - start_l = start_l.add(1); - ptr::copy_nonoverlapping(left!(), right!(), 1); - start_r = start_r.add(1); - ptr::copy_nonoverlapping(right!(), left!(), 1); - } - - ptr::copy_nonoverlapping(&tmp, right!(), 1); - mem::forget(tmp); - start_l = start_l.add(1); - start_r = start_r.add(1); - } - } - - if start_l == end_l { - // All out-of-order elements in the left block were moved. Move to the next block. - - // block-width-guarantee - // SAFETY: if `!is_done` then the slice width is guaranteed to be at least `2*BLOCK` wide. There - // are at most `BLOCK` elements in `offsets_l` because of its size, so the `offset` operation is - // safe. Otherwise, the debug assertions in the `is_done` case guarantee that - // `width(l, r) == block_l + block_r`, namely, that the block sizes have been adjusted to account - // for the smaller number of remaining elements. - l = unsafe { l.add(block_l) }; - } - - if start_r == end_r { - // All out-of-order elements in the right block were moved. Move to the previous block. - - // SAFETY: Same argument as [block-width-guarantee]. Either this is a full block `2*BLOCK`-wide, - // or `block_r` has been adjusted for the last handful of elements. - r = unsafe { r.sub(block_r) }; - } - - if is_done { - break; - } - } - - // All that remains now is at most one block (either the left or the right) with out-of-order - // elements that need to be moved. Such remaining elements can be simply shifted to the end - // within their block. - - if start_l < end_l { - // The left block remains. - // Move its remaining out-of-order elements to the far right. - debug_assert_eq!(width(l, r), block_l); - while start_l < end_l { - // remaining-elements-safety - // SAFETY: while the loop condition holds there are still elements in `offsets_l`, so it - // is safe to point `end_l` to the previous element. - // - // The `ptr::swap` is safe if both its arguments are valid for reads and writes: - // - Per the debug assert above, the distance between `l` and `r` is `block_l` - // elements, so there can be at most `block_l` remaining offsets between `start_l` - // and `end_l`. This means `r` will be moved at most `block_l` steps back, which - // makes the `r.offset` calls valid (at that point `l == r`). - // - `offsets_l` contains valid offsets into `v` collected during the partitioning of - // the last block, so the `l.offset` calls are valid. - unsafe { - end_l = end_l.sub(1); - ptr::swap(l.add(usize::from(*end_l)), r.sub(1)); - r = r.sub(1); - } - } - width(v.as_mut_ptr(), r) - } else if start_r < end_r { - // The right block remains. - // Move its remaining out-of-order elements to the far left. - debug_assert_eq!(width(l, r), block_r); - while start_r < end_r { - // SAFETY: See the reasoning in [remaining-elements-safety]. - unsafe { - end_r = end_r.sub(1); - ptr::swap(l, r.sub(usize::from(*end_r) + 1)); - l = l.add(1); - } - } - width(v.as_mut_ptr(), l) - } else { - // Nothing else to do, we're done. - width(v.as_mut_ptr(), l) - } -} - -/// Partitions `v` into elements smaller than `v[pivot]`, followed by elements greater than or -/// equal to `v[pivot]`. -/// -/// Returns a tuple of: -/// -/// 1. Number of elements smaller than `v[pivot]`. -/// 2. True if `v` was already partitioned. -pub(super) fn partition(v: &mut [T], pivot: usize, is_less: &mut F) -> (usize, bool) -where - F: FnMut(&T, &T) -> bool, -{ - let (mid, was_partitioned) = { - // Place the pivot at the beginning of slice. - v.swap(0, pivot); - let (pivot, v) = v.split_at_mut(1); - let pivot = &mut pivot[0]; - - // Read the pivot into a stack-allocated variable for efficiency. If a following comparison - // operation panics, the pivot will be automatically written back into the slice. - - // SAFETY: `pivot` is a reference to the first element of `v`, so `ptr::read` is safe. - let tmp = mem::ManuallyDrop::new(unsafe { ptr::read(pivot) }); - let _pivot_guard = InsertionHole { src: &*tmp, dest: pivot }; - let pivot = &*tmp; - - // Find the first pair of out-of-order elements. - let mut l = 0; - let mut r = v.len(); - - // SAFETY: The unsafety below involves indexing an array. - // For the first one: We already do the bounds checking here with `l < r`. - // For the second one: We initially have `l == 0` and `r == v.len()` and we checked that `l < r` at every indexing operation. - // From here we know that `r` must be at least `r == l` which was shown to be valid from the first one. - unsafe { - // Find the first element greater than or equal to the pivot. - while l < r && is_less(v.get_unchecked(l), pivot) { - l += 1; - } - - // Find the last element smaller that the pivot. - while l < r && !is_less(v.get_unchecked(r - 1), pivot) { - r -= 1; - } - } - - (l + partition_in_blocks(&mut v[l..r], pivot, is_less), l >= r) - - // `_pivot_guard` goes out of scope and writes the pivot (which is a stack-allocated - // variable) back into the slice where it originally was. This step is critical in ensuring - // safety! - }; - - // Place the pivot between the two partitions. - v.swap(0, mid); - - (mid, was_partitioned) -} - -/// Partitions `v` into elements equal to `v[pivot]` followed by elements greater than `v[pivot]`. -/// -/// Returns the number of elements equal to the pivot. It is assumed that `v` does not contain -/// elements smaller than the pivot. -pub(super) fn partition_equal(v: &mut [T], pivot: usize, is_less: &mut F) -> usize -where - F: FnMut(&T, &T) -> bool, -{ - // Place the pivot at the beginning of slice. - v.swap(0, pivot); - let (pivot, v) = v.split_at_mut(1); - let pivot = &mut pivot[0]; - - // Read the pivot into a stack-allocated variable for efficiency. If a following comparison - // operation panics, the pivot will be automatically written back into the slice. - // SAFETY: The pointer here is valid because it is obtained from a reference to a slice. - let tmp = mem::ManuallyDrop::new(unsafe { ptr::read(pivot) }); - let _pivot_guard = InsertionHole { src: &*tmp, dest: pivot }; - let pivot = &*tmp; - - let len = v.len(); - if len == 0 { - return 0; - } - - // Now partition the slice. - let mut l = 0; - let mut r = len; - loop { - // SAFETY: The unsafety below involves indexing an array. - // For the first one: We already do the bounds checking here with `l < r`. - // For the second one: We initially have `l == 0` and `r == v.len()` and we checked that `l < r` at every indexing operation. - // From here we know that `r` must be at least `r == l` which was shown to be valid from the first one. - unsafe { - // Find the first element greater than the pivot. - while l < r && !is_less(pivot, v.get_unchecked(l)) { - l += 1; - } - - // Find the last element equal to the pivot. - loop { - r -= 1; - if l >= r || !is_less(pivot, v.get_unchecked(r)) { - break; - } - } - - // Are we done? - if l >= r { - break; - } - - // Swap the found pair of out-of-order elements. - let ptr = v.as_mut_ptr(); - ptr::swap(ptr.add(l), ptr.add(r)); - l += 1; - } - } - - // We found `l` elements equal to the pivot. Add 1 to account for the pivot itself. - l + 1 - - // `_pivot_guard` goes out of scope and writes the pivot (which is a stack-allocated variable) - // back into the slice where it originally was. This step is critical in ensuring safety! -} - -/// Scatters some elements around in an attempt to break patterns that might cause imbalanced -/// partitions in quicksort. -#[cold] -pub(super) fn break_patterns(v: &mut [T]) { - let len = v.len(); - if len >= 8 { - let mut seed = len; - let mut gen_usize = || { - // Pseudorandom number generator from the "Xorshift RNGs" paper by George Marsaglia. - if usize::BITS <= 32 { - let mut r = seed as u32; - r ^= r << 13; - r ^= r >> 17; - r ^= r << 5; - seed = r as usize; - seed - } else { - let mut r = seed as u64; - r ^= r << 13; - r ^= r >> 7; - r ^= r << 17; - seed = r as usize; - seed - } - }; - - // Take random numbers modulo this number. - // The number fits into `usize` because `len` is not greater than `isize::MAX`. - let modulus = len.next_power_of_two(); - - // Some pivot candidates will be in the nearby of this index. Let's randomize them. - let pos = len / 4 * 2; - - for i in 0..3 { - // Generate a random number modulo `len`. However, in order to avoid costly operations - // we first take it modulo a power of two, and then decrease by `len` until it fits - // into the range `[0, len - 1]`. - let mut other = gen_usize() & (modulus - 1); - - // `other` is guaranteed to be less than `2 * len`. - if other >= len { - other -= len; - } - - v.swap(pos - 1 + i, other); - } - } -} - -/// Chooses a pivot in `v` and returns the index and `true` if the slice is likely already sorted. -/// -/// Elements in `v` might be reordered in the process. -pub(super) fn choose_pivot(v: &mut [T], is_less: &mut F) -> (usize, bool) -where - F: FnMut(&T, &T) -> bool, -{ - // Minimum length to choose the median-of-medians method. - // Shorter slices use the simple median-of-three method. - const SHORTEST_MEDIAN_OF_MEDIANS: usize = 50; - // Maximum number of swaps that can be performed in this function. - const MAX_SWAPS: usize = 4 * 3; - - let len = v.len(); - - // Three indices near which we are going to choose a pivot. - let mut a = len / 4 * 1; - let mut b = len / 4 * 2; - let mut c = len / 4 * 3; - - // Counts the total number of swaps we are about to perform while sorting indices. - let mut swaps = 0; - - if len >= 8 { - // Swaps indices so that `v[a] <= v[b]`. - // SAFETY: `len >= 8` so there are at least two elements in the neighborhoods of - // `a`, `b` and `c`. This means the three calls to `sort_adjacent` result in - // corresponding calls to `sort3` with valid 3-item neighborhoods around each - // pointer, which in turn means the calls to `sort2` are done with valid - // references. Thus the `v.get_unchecked` calls are safe, as is the `ptr::swap` - // call. - let mut sort2 = |a: &mut usize, b: &mut usize| unsafe { - if is_less(v.get_unchecked(*b), v.get_unchecked(*a)) { - ptr::swap(a, b); - swaps += 1; - } - }; - - // Swaps indices so that `v[a] <= v[b] <= v[c]`. - let mut sort3 = |a: &mut usize, b: &mut usize, c: &mut usize| { - sort2(a, b); - sort2(b, c); - sort2(a, b); - }; - - if len >= SHORTEST_MEDIAN_OF_MEDIANS { - // Finds the median of `v[a - 1], v[a], v[a + 1]` and stores the index into `a`. - let mut sort_adjacent = |a: &mut usize| { - let tmp = *a; - sort3(&mut (tmp - 1), a, &mut (tmp + 1)); - }; - - // Find medians in the neighborhoods of `a`, `b`, and `c`. - sort_adjacent(&mut a); - sort_adjacent(&mut b); - sort_adjacent(&mut c); - } - - // Find the median among `a`, `b`, and `c`. - sort3(&mut a, &mut b, &mut c); - } - - if swaps < MAX_SWAPS { - (b, swaps == 0) - } else { - // The maximum number of swaps was performed. Chances are the slice is descending or mostly - // descending, so reversing will probably help sort it faster. - v.reverse(); - (len - 1 - b, true) - } -} - -/// Sorts `v` recursively. -/// -/// If the slice had a predecessor in the original array, it is specified as `pred`. -/// -/// `limit` is the number of allowed imbalanced partitions before switching to `heapsort`. If zero, -/// this function will immediately switch to heapsort. -fn recurse<'a, T, F>(mut v: &'a mut [T], is_less: &mut F, mut pred: Option<&'a T>, mut limit: u32) -where - F: FnMut(&T, &T) -> bool, -{ - // Slices of up to this length get sorted using insertion sort. - const MAX_INSERTION: usize = 20; - - // True if the last partitioning was reasonably balanced. - let mut was_balanced = true; - // True if the last partitioning didn't shuffle elements (the slice was already partitioned). - let mut was_partitioned = true; - - loop { - let len = v.len(); - - // Very short slices get sorted using insertion sort. - if len <= MAX_INSERTION { - if len >= 2 { - insertion_sort_shift_left(v, 1, is_less); - } - return; - } - - // If too many bad pivot choices were made, simply fall back to heapsort in order to - // guarantee `O(n * log(n))` worst-case. - if limit == 0 { - heapsort(v, is_less); - return; - } - - // If the last partitioning was imbalanced, try breaking patterns in the slice by shuffling - // some elements around. Hopefully we'll choose a better pivot this time. - if !was_balanced { - break_patterns(v); - limit -= 1; - } - - // Choose a pivot and try guessing whether the slice is already sorted. - let (pivot, likely_sorted) = choose_pivot(v, is_less); - - // If the last partitioning was decently balanced and didn't shuffle elements, and if pivot - // selection predicts the slice is likely already sorted... - if was_balanced && was_partitioned && likely_sorted { - // Try identifying several out-of-order elements and shifting them to correct - // positions. If the slice ends up being completely sorted, we're done. - if partial_insertion_sort(v, is_less) { - return; - } - } - - // If the chosen pivot is equal to the predecessor, then it's the smallest element in the - // slice. Partition the slice into elements equal to and elements greater than the pivot. - // This case is usually hit when the slice contains many duplicate elements. - if let Some(p) = pred { - if !is_less(p, &v[pivot]) { - let mid = partition_equal(v, pivot, is_less); - - // Continue sorting elements greater than the pivot. - v = &mut v[mid..]; - continue; - } - } - - // Partition the slice. - let (mid, was_p) = partition(v, pivot, is_less); - was_balanced = cmp::min(mid, len - mid) >= len / 8; - was_partitioned = was_p; - - // Split the slice into `left`, `pivot`, and `right`. - let (left, right) = v.split_at_mut(mid); - let (pivot, right) = right.split_at_mut(1); - let pivot = &pivot[0]; - - // Recurse into the shorter side only in order to minimize the total number of recursive - // calls and consume less stack space. Then just continue with the longer side (this is - // akin to tail recursion). - if left.len() < right.len() { - recurse(left, is_less, pred, limit); - v = right; - pred = Some(pivot); - } else { - recurse(right, is_less, Some(pivot), limit); - v = left; - } - } -} - -/// Sorts `v` using pattern-defeating quicksort, which is *O*(*n* \* log(*n*)) worst-case. -pub fn quicksort(v: &mut [T], mut is_less: F) -where - F: FnMut(&T, &T) -> bool, -{ - // Sorting has no meaningful behavior on zero-sized types. - if T::IS_ZST { - return; - } - - // Limit the number of imbalanced partitions to `floor(log2(len)) + 1`. - let limit = usize::BITS - v.len().leading_zeros(); - - recurse(v, &mut is_less, None, limit); -} - -/// Merges non-decreasing runs `v[..mid]` and `v[mid..]` using `buf` as temporary storage, and -/// stores the result into `v[..]`. -/// -/// # Safety -/// -/// The two slices must be non-empty and `mid` must be in bounds. Buffer `buf` must be long enough -/// to hold a copy of the shorter slice. Also, `T` must not be a zero-sized type. -unsafe fn merge(v: &mut [T], mid: usize, buf: *mut T, is_less: &mut F) -where - F: FnMut(&T, &T) -> bool, -{ - let len = v.len(); - let v = v.as_mut_ptr(); - - // SAFETY: mid and len must be in-bounds of v. - let (v_mid, v_end) = unsafe { (v.add(mid), v.add(len)) }; - - // The merge process first copies the shorter run into `buf`. Then it traces the newly copied - // run and the longer run forwards (or backwards), comparing their next unconsumed elements and - // copying the lesser (or greater) one into `v`. - // - // As soon as the shorter run is fully consumed, the process is done. If the longer run gets - // consumed first, then we must copy whatever is left of the shorter run into the remaining - // hole in `v`. - // - // Intermediate state of the process is always tracked by `hole`, which serves two purposes: - // 1. Protects integrity of `v` from panics in `is_less`. - // 2. Fills the remaining hole in `v` if the longer run gets consumed first. - // - // Panic safety: - // - // If `is_less` panics at any point during the process, `hole` will get dropped and fill the - // hole in `v` with the unconsumed range in `buf`, thus ensuring that `v` still holds every - // object it initially held exactly once. - let mut hole; - - if mid <= len - mid { - // The left run is shorter. - - // SAFETY: buf must have enough capacity for `v[..mid]`. - unsafe { - ptr::copy_nonoverlapping(v, buf, mid); - hole = MergeHole { start: buf, end: buf.add(mid), dest: v }; - } - - // Initially, these pointers point to the beginnings of their arrays. - let left = &mut hole.start; - let mut right = v_mid; - let out = &mut hole.dest; - - while *left < hole.end && right < v_end { - // Consume the lesser side. - // If equal, prefer the left run to maintain stability. - - // SAFETY: left and right must be valid and part of v same for out. - unsafe { - let is_l = is_less(&*right, &**left); - let to_copy = if is_l { right } else { *left }; - ptr::copy_nonoverlapping(to_copy, *out, 1); - *out = out.add(1); - right = right.add(is_l as usize); - *left = left.add(!is_l as usize); - } - } - } else { - // The right run is shorter. - - // SAFETY: buf must have enough capacity for `v[mid..]`. - unsafe { - ptr::copy_nonoverlapping(v_mid, buf, len - mid); - hole = MergeHole { start: buf, end: buf.add(len - mid), dest: v_mid }; - } - - // Initially, these pointers point past the ends of their arrays. - let left = &mut hole.dest; - let right = &mut hole.end; - let mut out = v_end; - - while v < *left && buf < *right { - // Consume the greater side. - // If equal, prefer the right run to maintain stability. - - // SAFETY: left and right must be valid and part of v same for out. - unsafe { - let is_l = is_less(&*right.sub(1), &*left.sub(1)); - *left = left.sub(is_l as usize); - *right = right.sub(!is_l as usize); - let to_copy = if is_l { *left } else { *right }; - out = out.sub(1); - ptr::copy_nonoverlapping(to_copy, out, 1); - } - } - } - // Finally, `hole` gets dropped. If the shorter run was not fully consumed, whatever remains of - // it will now be copied into the hole in `v`. - - // When dropped, copies the range `start..end` into `dest..`. - struct MergeHole { - start: *mut T, - end: *mut T, - dest: *mut T, - } - - impl Drop for MergeHole { - fn drop(&mut self) { - // SAFETY: `T` is not a zero-sized type, and these are pointers into a slice's elements. - unsafe { - let len = self.end.sub_ptr(self.start); - ptr::copy_nonoverlapping(self.start, self.dest, len); - } - } - } -} - -/// This merge sort borrows some (but not all) ideas from TimSort, which used to be described in -/// detail [here](https://github.com/python/cpython/blob/main/Objects/listsort.txt). However Python -/// has switched to a Powersort based implementation. -/// -/// The algorithm identifies strictly descending and non-descending subsequences, which are called -/// natural runs. There is a stack of pending runs yet to be merged. Each newly found run is pushed -/// onto the stack, and then some pairs of adjacent runs are merged until these two invariants are -/// satisfied: -/// -/// 1. for every `i` in `1..runs.len()`: `runs[i - 1].len > runs[i].len` -/// 2. for every `i` in `2..runs.len()`: `runs[i - 2].len > runs[i - 1].len + runs[i].len` -/// -/// The invariants ensure that the total running time is *O*(*n* \* log(*n*)) worst-case. -pub fn merge_sort( - v: &mut [T], - is_less: &mut CmpF, - elem_alloc_fn: ElemAllocF, - elem_dealloc_fn: ElemDeallocF, - run_alloc_fn: RunAllocF, - run_dealloc_fn: RunDeallocF, -) where - CmpF: FnMut(&T, &T) -> bool, - ElemAllocF: Fn(usize) -> *mut T, - ElemDeallocF: Fn(*mut T, usize), - RunAllocF: Fn(usize) -> *mut TimSortRun, - RunDeallocF: Fn(*mut TimSortRun, usize), -{ - // Slices of up to this length get sorted using insertion sort. - const MAX_INSERTION: usize = 20; - - // The caller should have already checked that. - debug_assert!(!T::IS_ZST); - - let len = v.len(); - - // Short arrays get sorted in-place via insertion sort to avoid allocations. - if len <= MAX_INSERTION { - if len >= 2 { - insertion_sort_shift_left(v, 1, is_less); - } - return; - } - - // Allocate a buffer to use as scratch memory. We keep the length 0 so we can keep in it - // shallow copies of the contents of `v` without risking the dtors running on copies if - // `is_less` panics. When merging two sorted runs, this buffer holds a copy of the shorter run, - // which will always have length at most `len / 2`. - let buf = BufGuard::new(len / 2, elem_alloc_fn, elem_dealloc_fn); - let buf_ptr = buf.buf_ptr.as_ptr(); - - let mut runs = RunVec::new(run_alloc_fn, run_dealloc_fn); - - let mut end = 0; - let mut start = 0; - - // Scan forward. Memory pre-fetching prefers forward scanning vs backwards scanning, and the - // code-gen is usually better. For the most sensitive types such as integers, these are merged - // bidirectionally at once. So there is no benefit in scanning backwards. - while end < len { - let (streak_end, was_reversed) = find_streak(&v[start..], is_less); - end += streak_end; - if was_reversed { - v[start..end].reverse(); - } - - // Insert some more elements into the run if it's too short. Insertion sort is faster than - // merge sort on short sequences, so this significantly improves performance. - end = provide_sorted_batch(v, start, end, is_less); - - // Push this run onto the stack. - runs.push(TimSortRun { start, len: end - start }); - start = end; - - // Merge some pairs of adjacent runs to satisfy the invariants. - while let Some(r) = collapse(runs.as_slice(), len) { - let left = runs[r]; - let right = runs[r + 1]; - let merge_slice = &mut v[left.start..right.start + right.len]; - // SAFETY: `buf_ptr` must hold enough capacity for the shorter of the two sides, and - // neither side may be on length 0. - unsafe { - merge(merge_slice, left.len, buf_ptr, is_less); - } - runs[r + 1] = TimSortRun { start: left.start, len: left.len + right.len }; - runs.remove(r); - } - } - - // Finally, exactly one run must remain in the stack. - debug_assert!(runs.len() == 1 && runs[0].start == 0 && runs[0].len == len); - - // Examines the stack of runs and identifies the next pair of runs to merge. More specifically, - // if `Some(r)` is returned, that means `runs[r]` and `runs[r + 1]` must be merged next. If the - // algorithm should continue building a new run instead, `None` is returned. - // - // TimSort is infamous for its buggy implementations, as described here: - // http://envisage-project.eu/timsort-specification-and-verification/ - // - // The gist of the story is: we must enforce the invariants on the top four runs on the stack. - // Enforcing them on just top three is not sufficient to ensure that the invariants will still - // hold for *all* runs in the stack. - // - // This function correctly checks invariants for the top four runs. Additionally, if the top - // run starts at index 0, it will always demand a merge operation until the stack is fully - // collapsed, in order to complete the sort. - #[inline] - fn collapse(runs: &[TimSortRun], stop: usize) -> Option { - let n = runs.len(); - if n >= 2 - && (runs[n - 1].start + runs[n - 1].len == stop - || runs[n - 2].len <= runs[n - 1].len - || (n >= 3 && runs[n - 3].len <= runs[n - 2].len + runs[n - 1].len) - || (n >= 4 && runs[n - 4].len <= runs[n - 3].len + runs[n - 2].len)) - { - if n >= 3 && runs[n - 3].len < runs[n - 1].len { Some(n - 3) } else { Some(n - 2) } - } else { - None - } - } - - // Extremely basic versions of Vec. - // Their use is super limited and by having the code here, it allows reuse between the sort - // implementations. - struct BufGuard - where - ElemDeallocF: Fn(*mut T, usize), - { - buf_ptr: ptr::NonNull, - capacity: usize, - elem_dealloc_fn: ElemDeallocF, - } - - impl BufGuard - where - ElemDeallocF: Fn(*mut T, usize), - { - fn new( - len: usize, - elem_alloc_fn: ElemAllocF, - elem_dealloc_fn: ElemDeallocF, - ) -> Self - where - ElemAllocF: Fn(usize) -> *mut T, - { - Self { - buf_ptr: ptr::NonNull::new(elem_alloc_fn(len)).unwrap(), - capacity: len, - elem_dealloc_fn, - } - } - } - - impl Drop for BufGuard - where - ElemDeallocF: Fn(*mut T, usize), - { - fn drop(&mut self) { - (self.elem_dealloc_fn)(self.buf_ptr.as_ptr(), self.capacity); - } - } - - struct RunVec - where - RunAllocF: Fn(usize) -> *mut TimSortRun, - RunDeallocF: Fn(*mut TimSortRun, usize), - { - buf_ptr: ptr::NonNull, - capacity: usize, - len: usize, - run_alloc_fn: RunAllocF, - run_dealloc_fn: RunDeallocF, - } - - impl RunVec - where - RunAllocF: Fn(usize) -> *mut TimSortRun, - RunDeallocF: Fn(*mut TimSortRun, usize), - { - fn new(run_alloc_fn: RunAllocF, run_dealloc_fn: RunDeallocF) -> Self { - // Most slices can be sorted with at most 16 runs in-flight. - const START_RUN_CAPACITY: usize = 16; - - Self { - buf_ptr: ptr::NonNull::new(run_alloc_fn(START_RUN_CAPACITY)).unwrap(), - capacity: START_RUN_CAPACITY, - len: 0, - run_alloc_fn, - run_dealloc_fn, - } - } - - fn push(&mut self, val: TimSortRun) { - if self.len == self.capacity { - let old_capacity = self.capacity; - let old_buf_ptr = self.buf_ptr.as_ptr(); - - self.capacity = self.capacity * 2; - self.buf_ptr = ptr::NonNull::new((self.run_alloc_fn)(self.capacity)).unwrap(); - - // SAFETY: buf_ptr new and old were correctly allocated and old_buf_ptr has - // old_capacity valid elements. - unsafe { - ptr::copy_nonoverlapping(old_buf_ptr, self.buf_ptr.as_ptr(), old_capacity); - } - - (self.run_dealloc_fn)(old_buf_ptr, old_capacity); - } - - // SAFETY: The invariant was just checked. - unsafe { - self.buf_ptr.as_ptr().add(self.len).write(val); - } - self.len += 1; - } - - fn remove(&mut self, index: usize) { - if index >= self.len { - panic!("Index out of bounds"); - } - - // SAFETY: buf_ptr needs to be valid and len invariant upheld. - unsafe { - // the place we are taking from. - let ptr = self.buf_ptr.as_ptr().add(index); - - // Shift everything down to fill in that spot. - ptr::copy(ptr.add(1), ptr, self.len - index - 1); - } - self.len -= 1; - } - - fn as_slice(&self) -> &[TimSortRun] { - // SAFETY: Safe as long as buf_ptr is valid and len invariant was upheld. - unsafe { &*ptr::slice_from_raw_parts(self.buf_ptr.as_ptr(), self.len) } - } - - fn len(&self) -> usize { - self.len - } - } - - impl core::ops::Index for RunVec - where - RunAllocF: Fn(usize) -> *mut TimSortRun, - RunDeallocF: Fn(*mut TimSortRun, usize), - { - type Output = TimSortRun; - - fn index(&self, index: usize) -> &Self::Output { - if index < self.len { - // SAFETY: buf_ptr and len invariant must be upheld. - unsafe { - return &*(self.buf_ptr.as_ptr().add(index)); - } - } - - panic!("Index out of bounds"); - } - } - - impl core::ops::IndexMut for RunVec - where - RunAllocF: Fn(usize) -> *mut TimSortRun, - RunDeallocF: Fn(*mut TimSortRun, usize), - { - fn index_mut(&mut self, index: usize) -> &mut Self::Output { - if index < self.len { - // SAFETY: buf_ptr and len invariant must be upheld. - unsafe { - return &mut *(self.buf_ptr.as_ptr().add(index)); - } - } - - panic!("Index out of bounds"); - } - } - - impl Drop for RunVec - where - RunAllocF: Fn(usize) -> *mut TimSortRun, - RunDeallocF: Fn(*mut TimSortRun, usize), - { - fn drop(&mut self) { - // As long as TimSortRun is Copy we don't need to drop them individually but just the - // whole allocation. - (self.run_dealloc_fn)(self.buf_ptr.as_ptr(), self.capacity); - } - } -} - -/// Internal type used by merge_sort. -#[derive(Clone, Copy, Debug)] -pub struct TimSortRun { - len: usize, - start: usize, -} - -/// Takes a range as denoted by start and end, that is already sorted and extends it to the right if -/// necessary with sorts optimized for smaller ranges such as insertion sort. -fn provide_sorted_batch(v: &mut [T], start: usize, mut end: usize, is_less: &mut F) -> usize -where - F: FnMut(&T, &T) -> bool, -{ - let len = v.len(); - assert!(end >= start && end <= len); - - // This value is a balance between least comparisons and best performance, as - // influenced by for example cache locality. - const MIN_INSERTION_RUN: usize = 10; - - // Insert some more elements into the run if it's too short. Insertion sort is faster than - // merge sort on short sequences, so this significantly improves performance. - let start_end_diff = end - start; - - if start_end_diff < MIN_INSERTION_RUN && end < len { - // v[start_found..end] are elements that are already sorted in the input. We want to extend - // the sorted region to the left, so we push up MIN_INSERTION_RUN - 1 to the right. Which is - // more efficient that trying to push those already sorted elements to the left. - end = cmp::min(start + MIN_INSERTION_RUN, len); - let presorted_start = cmp::max(start_end_diff, 1); - - insertion_sort_shift_left(&mut v[start..end], presorted_start, is_less); - } - - end -} - -/// Finds a streak of presorted elements starting at the beginning of the slice. Returns the first -/// value that is not part of said streak, and a bool denoting whether the streak was reversed. -/// Streaks can be increasing or decreasing. -fn find_streak(v: &[T], is_less: &mut F) -> (usize, bool) -where - F: FnMut(&T, &T) -> bool, -{ - let len = v.len(); - - if len < 2 { - return (len, false); - } - - let mut end = 2; - - // SAFETY: See below specific. - unsafe { - // SAFETY: We checked that len >= 2, so 0 and 1 are valid indices. - let assume_reverse = is_less(v.get_unchecked(1), v.get_unchecked(0)); - - // SAFETY: We know end >= 2 and check end < len. - // From that follows that accessing v at end and end - 1 is safe. - if assume_reverse { - while end < len && is_less(v.get_unchecked(end), v.get_unchecked(end - 1)) { - end += 1; - } - - (end, true) - } else { - while end < len && !is_less(v.get_unchecked(end), v.get_unchecked(end - 1)) { - end += 1; - } - (end, false) - } - } -} diff --git a/library/core/src/slice/specialize.rs b/library/core/src/slice/specialize.rs deleted file mode 100644 index 80eb590587f99..0000000000000 --- a/library/core/src/slice/specialize.rs +++ /dev/null @@ -1,23 +0,0 @@ -pub(super) trait SpecFill { - fn spec_fill(&mut self, value: T); -} - -impl SpecFill for [T] { - default fn spec_fill(&mut self, value: T) { - if let Some((last, elems)) = self.split_last_mut() { - for el in elems { - el.clone_from(&value); - } - - *last = value - } - } -} - -impl SpecFill for [T] { - fn spec_fill(&mut self, value: T) { - for item in self.iter_mut() { - *item = value; - } - } -} diff --git a/library/core/src/str/converts.rs b/library/core/src/str/converts.rs deleted file mode 100644 index b6ffb0a608d05..0000000000000 --- a/library/core/src/str/converts.rs +++ /dev/null @@ -1,245 +0,0 @@ -//! Ways to create a `str` from bytes slice. - -use crate::{mem, ptr}; - -use super::validations::run_utf8_validation; -use super::Utf8Error; - -/// Converts a slice of bytes to a string slice. -/// -/// A string slice ([`&str`]) is made of bytes ([`u8`]), and a byte slice -/// ([`&[u8]`][byteslice]) is made of bytes, so this function converts between -/// the two. Not all byte slices are valid string slices, however: [`&str`] requires -/// that it is valid UTF-8. `from_utf8()` checks to ensure that the bytes are valid -/// UTF-8, and then does the conversion. -/// -/// [`&str`]: str -/// [byteslice]: slice -/// -/// If you are sure that the byte slice is valid UTF-8, and you don't want to -/// incur the overhead of the validity check, there is an unsafe version of -/// this function, [`from_utf8_unchecked`], which has the same -/// behavior but skips the check. -/// -/// If you need a `String` instead of a `&str`, consider -/// [`String::from_utf8`][string]. -/// -/// [string]: ../../std/string/struct.String.html#method.from_utf8 -/// -/// Because you can stack-allocate a `[u8; N]`, and you can take a -/// [`&[u8]`][byteslice] of it, this function is one way to have a -/// stack-allocated string. There is an example of this in the -/// examples section below. -/// -/// [byteslice]: slice -/// -/// # Errors -/// -/// Returns `Err` if the slice is not UTF-8 with a description as to why the -/// provided slice is not UTF-8. -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// use std::str; -/// -/// // some bytes, in a vector -/// let sparkle_heart = vec![240, 159, 146, 150]; -/// -/// // We know these bytes are valid, so just use `unwrap()`. -/// let sparkle_heart = str::from_utf8(&sparkle_heart).unwrap(); -/// -/// assert_eq!("💖", sparkle_heart); -/// ``` -/// -/// Incorrect bytes: -/// -/// ``` -/// use std::str; -/// -/// // some invalid bytes, in a vector -/// let sparkle_heart = vec![0, 159, 146, 150]; -/// -/// assert!(str::from_utf8(&sparkle_heart).is_err()); -/// ``` -/// -/// See the docs for [`Utf8Error`] for more details on the kinds of -/// errors that can be returned. -/// -/// A "stack allocated string": -/// -/// ``` -/// use std::str; -/// -/// // some bytes, in a stack-allocated array -/// let sparkle_heart = [240, 159, 146, 150]; -/// -/// // We know these bytes are valid, so just use `unwrap()`. -/// let sparkle_heart: &str = str::from_utf8(&sparkle_heart).unwrap(); -/// -/// assert_eq!("💖", sparkle_heart); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_const_stable(feature = "const_str_from_utf8_shared", since = "1.63.0")] -#[rustc_allow_const_fn_unstable(str_internals)] -#[rustc_diagnostic_item = "str_from_utf8"] -pub const fn from_utf8(v: &[u8]) -> Result<&str, Utf8Error> { - // FIXME: This should use `?` again, once it's `const` - match run_utf8_validation(v) { - Ok(_) => { - // SAFETY: validation succeeded. - Ok(unsafe { from_utf8_unchecked(v) }) - } - Err(err) => Err(err), - } -} - -/// Converts a mutable slice of bytes to a mutable string slice. -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// use std::str; -/// -/// // "Hello, Rust!" as a mutable vector -/// let mut hellorust = vec![72, 101, 108, 108, 111, 44, 32, 82, 117, 115, 116, 33]; -/// -/// // As we know these bytes are valid, we can use `unwrap()` -/// let outstr = str::from_utf8_mut(&mut hellorust).unwrap(); -/// -/// assert_eq!("Hello, Rust!", outstr); -/// ``` -/// -/// Incorrect bytes: -/// -/// ``` -/// use std::str; -/// -/// // Some invalid bytes in a mutable vector -/// let mut invalid = vec![128, 223]; -/// -/// assert!(str::from_utf8_mut(&mut invalid).is_err()); -/// ``` -/// See the docs for [`Utf8Error`] for more details on the kinds of -/// errors that can be returned. -#[stable(feature = "str_mut_extras", since = "1.20.0")] -#[rustc_const_unstable(feature = "const_str_from_utf8", issue = "91006")] -#[rustc_diagnostic_item = "str_from_utf8_mut"] -pub const fn from_utf8_mut(v: &mut [u8]) -> Result<&mut str, Utf8Error> { - // This should use `?` again, once it's `const` - match run_utf8_validation(v) { - Ok(_) => { - // SAFETY: validation succeeded. - Ok(unsafe { from_utf8_unchecked_mut(v) }) - } - Err(err) => Err(err), - } -} - -/// Converts a slice of bytes to a string slice without checking -/// that the string contains valid UTF-8. -/// -/// See the safe version, [`from_utf8`], for more information. -/// -/// # Safety -/// -/// The bytes passed in must be valid UTF-8. -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// use std::str; -/// -/// // some bytes, in a vector -/// let sparkle_heart = vec![240, 159, 146, 150]; -/// -/// let sparkle_heart = unsafe { -/// str::from_utf8_unchecked(&sparkle_heart) -/// }; -/// -/// assert_eq!("💖", sparkle_heart); -/// ``` -#[inline] -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_const_stable(feature = "const_str_from_utf8_unchecked", since = "1.55.0")] -#[rustc_diagnostic_item = "str_from_utf8_unchecked"] -pub const unsafe fn from_utf8_unchecked(v: &[u8]) -> &str { - // SAFETY: the caller must guarantee that the bytes `v` are valid UTF-8. - // Also relies on `&str` and `&[u8]` having the same layout. - unsafe { mem::transmute(v) } -} - -/// Converts a slice of bytes to a string slice without checking -/// that the string contains valid UTF-8; mutable version. -/// -/// See the immutable version, [`from_utf8_unchecked()`] for more information. -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// use std::str; -/// -/// let mut heart = vec![240, 159, 146, 150]; -/// let heart = unsafe { str::from_utf8_unchecked_mut(&mut heart) }; -/// -/// assert_eq!("💖", heart); -/// ``` -#[inline] -#[must_use] -#[stable(feature = "str_mut_extras", since = "1.20.0")] -#[rustc_const_unstable(feature = "const_str_from_utf8_unchecked_mut", issue = "91005")] -#[rustc_diagnostic_item = "str_from_utf8_unchecked_mut"] -pub const unsafe fn from_utf8_unchecked_mut(v: &mut [u8]) -> &mut str { - // SAFETY: the caller must guarantee that the bytes `v` - // are valid UTF-8, thus the cast to `*mut str` is safe. - // Also, the pointer dereference is safe because that pointer - // comes from a reference which is guaranteed to be valid for writes. - unsafe { &mut *(v as *mut [u8] as *mut str) } -} - -/// Creates an `&str` from a pointer and a length. -/// -/// The pointed-to bytes must be valid UTF-8. -/// If this might not be the case, use `str::from_utf8(slice::from_raw_parts(ptr, len))`, -/// which will return an `Err` if the data isn't valid UTF-8. -/// -/// This function is the `str` equivalent of [`slice::from_raw_parts`](crate::slice::from_raw_parts). -/// See that function's documentation for safety concerns and examples. -/// -/// The mutable version of this function is [`from_raw_parts_mut`]. -#[inline] -#[must_use] -#[unstable(feature = "str_from_raw_parts", issue = "119206")] -#[rustc_const_unstable(feature = "str_from_raw_parts", issue = "119206")] -pub const unsafe fn from_raw_parts<'a>(ptr: *const u8, len: usize) -> &'a str { - // SAFETY: the caller must uphold the safety contract for `from_raw_parts`. - unsafe { &*ptr::from_raw_parts(ptr.cast(), len) } -} - -/// Creates an `&mut str` from a pointer and a length. -/// -/// The pointed-to bytes must be valid UTF-8. -/// If this might not be the case, use `str::from_utf8_mut(slice::from_raw_parts_mut(ptr, len))`, -/// which will return an `Err` if the data isn't valid UTF-8. -/// -/// This function is the `str` equivalent of [`slice::from_raw_parts_mut`](crate::slice::from_raw_parts_mut). -/// See that function's documentation for safety concerns and examples. -/// -/// The immutable version of this function is [`from_raw_parts`]. -#[inline] -#[must_use] -#[unstable(feature = "str_from_raw_parts", issue = "119206")] -#[rustc_const_unstable(feature = "const_str_from_raw_parts_mut", issue = "119206")] -pub const unsafe fn from_raw_parts_mut<'a>(ptr: *mut u8, len: usize) -> &'a mut str { - // SAFETY: the caller must uphold the safety contract for `from_raw_parts_mut`. - unsafe { &mut *ptr::from_raw_parts_mut(ptr.cast(), len) } -} diff --git a/library/core/src/str/count.rs b/library/core/src/str/count.rs deleted file mode 100644 index 28567a7e753aa..0000000000000 --- a/library/core/src/str/count.rs +++ /dev/null @@ -1,136 +0,0 @@ -//! Code for efficiently counting the number of `char`s in a UTF-8 encoded -//! string. -//! -//! Broadly, UTF-8 encodes `char`s as a "leading" byte which begins the `char`, -//! followed by some number (possibly 0) of continuation bytes. -//! -//! The leading byte can have a number of bit-patterns (with the specific -//! pattern indicating how many continuation bytes follow), but the continuation -//! bytes are always in the format `0b10XX_XXXX` (where the `X`s can take any -//! value). That is, the most significant bit is set, and the second most -//! significant bit is unset. -//! -//! To count the number of characters, we can just count the number of bytes in -//! the string which are not continuation bytes, which can be done many bytes at -//! a time fairly easily. -//! -//! Note: Because the term "leading byte" can sometimes be ambiguous (for -//! example, it could also refer to the first byte of a slice), we'll often use -//! the term "non-continuation byte" to refer to these bytes in the code. -use core::intrinsics::unlikely; - -const USIZE_SIZE: usize = core::mem::size_of::(); -const UNROLL_INNER: usize = 4; - -#[inline] -pub(super) fn count_chars(s: &str) -> usize { - if s.len() < USIZE_SIZE * UNROLL_INNER { - // Avoid entering the optimized implementation for strings where the - // difference is not likely to matter, or where it might even be slower. - // That said, a ton of thought was not spent on the particular threshold - // here, beyond "this value seems to make sense". - char_count_general_case(s.as_bytes()) - } else { - do_count_chars(s) - } -} - -fn do_count_chars(s: &str) -> usize { - // For correctness, `CHUNK_SIZE` must be: - // - // - Less than or equal to 255, otherwise we'll overflow bytes in `counts`. - // - A multiple of `UNROLL_INNER`, otherwise our `break` inside the - // `body.chunks(CHUNK_SIZE)` loop is incorrect. - // - // For performance, `CHUNK_SIZE` should be: - // - Relatively cheap to `/` against (so some simple sum of powers of two). - // - Large enough to avoid paying for the cost of the `sum_bytes_in_usize` - // too often. - const CHUNK_SIZE: usize = 192; - - // Check the properties of `CHUNK_SIZE` and `UNROLL_INNER` that are required - // for correctness. - const _: () = assert!(CHUNK_SIZE < 256); - const _: () = assert!(CHUNK_SIZE % UNROLL_INNER == 0); - - // SAFETY: transmuting `[u8]` to `[usize]` is safe except for size - // differences which are handled by `align_to`. - let (head, body, tail) = unsafe { s.as_bytes().align_to::() }; - - // This should be quite rare, and basically exists to handle the degenerate - // cases where align_to fails (as well as miri under symbolic alignment - // mode). - // - // The `unlikely` helps discourage LLVM from inlining the body, which is - // nice, as we would rather not mark the `char_count_general_case` function - // as cold. - if unlikely(body.is_empty() || head.len() > USIZE_SIZE || tail.len() > USIZE_SIZE) { - return char_count_general_case(s.as_bytes()); - } - - let mut total = char_count_general_case(head) + char_count_general_case(tail); - // Split `body` into `CHUNK_SIZE` chunks to reduce the frequency with which - // we call `sum_bytes_in_usize`. - for chunk in body.chunks(CHUNK_SIZE) { - // We accumulate intermediate sums in `counts`, where each byte contains - // a subset of the sum of this chunk, like a `[u8; size_of::()]`. - let mut counts = 0; - - let (unrolled_chunks, remainder) = chunk.as_chunks::(); - for unrolled in unrolled_chunks { - for &word in unrolled { - // Because `CHUNK_SIZE` is < 256, this addition can't cause the - // count in any of the bytes to overflow into a subsequent byte. - counts += contains_non_continuation_byte(word); - } - } - - // Sum the values in `counts` (which, again, is conceptually a `[u8; - // size_of::()]`), and accumulate the result into `total`. - total += sum_bytes_in_usize(counts); - - // If there's any data in `remainder`, then handle it. This will only - // happen for the last `chunk` in `body.chunks()` (because `CHUNK_SIZE` - // is divisible by `UNROLL_INNER`), so we explicitly break at the end - // (which seems to help LLVM out). - if !remainder.is_empty() { - // Accumulate all the data in the remainder. - let mut counts = 0; - for &word in remainder { - counts += contains_non_continuation_byte(word); - } - total += sum_bytes_in_usize(counts); - break; - } - } - total -} - -// Checks each byte of `w` to see if it contains the first byte in a UTF-8 -// sequence. Bytes in `w` which are continuation bytes are left as `0x00` (e.g. -// false), and bytes which are non-continuation bytes are left as `0x01` (e.g. -// true) -#[inline] -fn contains_non_continuation_byte(w: usize) -> usize { - const LSB: usize = usize::repeat_u8(0x01); - ((!w >> 7) | (w >> 6)) & LSB -} - -// Morally equivalent to `values.to_ne_bytes().into_iter().sum::()`, but -// more efficient. -#[inline] -fn sum_bytes_in_usize(values: usize) -> usize { - const LSB_SHORTS: usize = usize::repeat_u16(0x0001); - const SKIP_BYTES: usize = usize::repeat_u16(0x00ff); - - let pair_sum: usize = (values & SKIP_BYTES) + ((values >> 8) & SKIP_BYTES); - pair_sum.wrapping_mul(LSB_SHORTS) >> ((USIZE_SIZE - 2) * 8) -} - -// This is the most direct implementation of the concept of "count the number of -// bytes in the string which are not continuation bytes", and is used for the -// head and tail of the input string (the first and last item in the tuple -// returned by `slice::align_to`). -fn char_count_general_case(s: &[u8]) -> usize { - s.iter().filter(|&&byte| !super::validations::utf8_is_cont_byte(byte)).count() -} diff --git a/library/core/src/str/error.rs b/library/core/src/str/error.rs deleted file mode 100644 index a11b5add42ebf..0000000000000 --- a/library/core/src/str/error.rs +++ /dev/null @@ -1,155 +0,0 @@ -//! Defines utf8 error type. - -use crate::error::Error; -use crate::fmt; - -/// Errors which can occur when attempting to interpret a sequence of [`u8`] -/// as a string. -/// -/// As such, the `from_utf8` family of functions and methods for both [`String`]s -/// and [`&str`]s make use of this error, for example. -/// -/// [`String`]: ../../std/string/struct.String.html#method.from_utf8 -/// [`&str`]: super::from_utf8 -/// -/// # Examples -/// -/// This error type’s methods can be used to create functionality -/// similar to `String::from_utf8_lossy` without allocating heap memory: -/// -/// ``` -/// fn from_utf8_lossy(mut input: &[u8], mut push: F) where F: FnMut(&str) { -/// loop { -/// match std::str::from_utf8(input) { -/// Ok(valid) => { -/// push(valid); -/// break -/// } -/// Err(error) => { -/// let (valid, after_valid) = input.split_at(error.valid_up_to()); -/// unsafe { -/// push(std::str::from_utf8_unchecked(valid)) -/// } -/// push("\u{FFFD}"); -/// -/// if let Some(invalid_sequence_length) = error.error_len() { -/// input = &after_valid[invalid_sequence_length..] -/// } else { -/// break -/// } -/// } -/// } -/// } -/// } -/// ``` -#[derive(Copy, Eq, PartialEq, Clone, Debug)] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Utf8Error { - pub(super) valid_up_to: usize, - pub(super) error_len: Option, -} - -impl Utf8Error { - /// Returns the index in the given string up to which valid UTF-8 was - /// verified. - /// - /// It is the maximum index such that `from_utf8(&input[..index])` - /// would return `Ok(_)`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::str; - /// - /// // some invalid bytes, in a vector - /// let sparkle_heart = vec![0, 159, 146, 150]; - /// - /// // std::str::from_utf8 returns a Utf8Error - /// let error = str::from_utf8(&sparkle_heart).unwrap_err(); - /// - /// // the second byte is invalid here - /// assert_eq!(1, error.valid_up_to()); - /// ``` - #[stable(feature = "utf8_error", since = "1.5.0")] - #[rustc_const_stable(feature = "const_str_from_utf8_shared", since = "1.63.0")] - #[must_use] - #[inline] - pub const fn valid_up_to(&self) -> usize { - self.valid_up_to - } - - /// Provides more information about the failure: - /// - /// * `None`: the end of the input was reached unexpectedly. - /// `self.valid_up_to()` is 1 to 3 bytes from the end of the input. - /// If a byte stream (such as a file or a network socket) is being decoded incrementally, - /// this could be a valid `char` whose UTF-8 byte sequence is spanning multiple chunks. - /// - /// * `Some(len)`: an unexpected byte was encountered. - /// The length provided is that of the invalid byte sequence - /// that starts at the index given by `valid_up_to()`. - /// Decoding should resume after that sequence - /// (after inserting a [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD]) in case of - /// lossy decoding. - /// - /// [U+FFFD]: ../../std/char/constant.REPLACEMENT_CHARACTER.html - #[stable(feature = "utf8_error_error_len", since = "1.20.0")] - #[rustc_const_stable(feature = "const_str_from_utf8_shared", since = "1.63.0")] - #[must_use] - #[inline] - pub const fn error_len(&self) -> Option { - // FIXME: This should become `map` again, once it's `const` - match self.error_len { - Some(len) => Some(len as usize), - None => None, - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for Utf8Error { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - if let Some(error_len) = self.error_len { - write!( - f, - "invalid utf-8 sequence of {} bytes from index {}", - error_len, self.valid_up_to - ) - } else { - write!(f, "incomplete utf-8 byte sequence from index {}", self.valid_up_to) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Error for Utf8Error { - #[allow(deprecated)] - fn description(&self) -> &str { - "invalid utf-8: corrupt contents" - } -} - -/// An error returned when parsing a `bool` using [`from_str`] fails -/// -/// [`from_str`]: super::FromStr::from_str -#[derive(Debug, Clone, PartialEq, Eq)] -#[non_exhaustive] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct ParseBoolError; - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for ParseBoolError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - "provided string was not `true` or `false`".fmt(f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Error for ParseBoolError { - #[allow(deprecated)] - fn description(&self) -> &str { - "failed to parse bool" - } -} diff --git a/library/core/src/str/iter.rs b/library/core/src/str/iter.rs deleted file mode 100644 index d61f04102e5e5..0000000000000 --- a/library/core/src/str/iter.rs +++ /dev/null @@ -1,1604 +0,0 @@ -//! Iterators for `str` methods. - -use crate::char as char_mod; -use crate::fmt::{self, Write}; -use crate::iter::{Chain, FlatMap, Flatten}; -use crate::iter::{Copied, Filter, FusedIterator, Map, TrustedLen}; -use crate::iter::{TrustedRandomAccess, TrustedRandomAccessNoCoerce}; -use crate::num::NonZero; -use crate::ops::Try; -use crate::option; -use crate::slice::{self, Split as SliceSplit}; - -use super::from_utf8_unchecked; -use super::pattern::Pattern; -use super::pattern::{DoubleEndedSearcher, ReverseSearcher, Searcher}; -use super::validations::{next_code_point, next_code_point_reverse}; -use super::LinesMap; -use super::{BytesIsNotEmpty, UnsafeBytesToStr}; -use super::{CharEscapeDebugContinue, CharEscapeDefault, CharEscapeUnicode}; -use super::{IsAsciiWhitespace, IsNotEmpty, IsWhitespace}; - -/// An iterator over the [`char`]s of a string slice. -/// -/// -/// This struct is created by the [`chars`] method on [`str`]. -/// See its documentation for more. -/// -/// [`char`]: prim@char -/// [`chars`]: str::chars -#[derive(Clone)] -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Chars<'a> { - pub(super) iter: slice::Iter<'a, u8>, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a> Iterator for Chars<'a> { - type Item = char; - - #[inline] - fn next(&mut self) -> Option { - // SAFETY: `str` invariant says `self.iter` is a valid UTF-8 string and - // the resulting `ch` is a valid Unicode Scalar Value. - unsafe { next_code_point(&mut self.iter).map(|ch| char::from_u32_unchecked(ch)) } - } - - #[inline] - fn count(self) -> usize { - super::count::count_chars(self.as_str()) - } - - #[inline] - fn advance_by(&mut self, mut remainder: usize) -> Result<(), NonZero> { - const CHUNK_SIZE: usize = 32; - - if remainder >= CHUNK_SIZE { - let mut chunks = self.iter.as_slice().array_chunks::(); - let mut bytes_skipped: usize = 0; - - while remainder > CHUNK_SIZE - && let Some(chunk) = chunks.next() - { - bytes_skipped += CHUNK_SIZE; - - let mut start_bytes = [false; CHUNK_SIZE]; - - for i in 0..CHUNK_SIZE { - start_bytes[i] = !super::validations::utf8_is_cont_byte(chunk[i]); - } - - remainder -= start_bytes.into_iter().map(|i| i as u8).sum::() as usize; - } - - // SAFETY: The amount of bytes exists since we just iterated over them, - // so advance_by will succeed. - unsafe { self.iter.advance_by(bytes_skipped).unwrap_unchecked() }; - - // skip trailing continuation bytes - while self.iter.len() > 0 { - let b = self.iter.as_slice()[0]; - if !super::validations::utf8_is_cont_byte(b) { - break; - } - // SAFETY: We just peeked at the byte, therefore it exists - unsafe { self.iter.advance_by(1).unwrap_unchecked() }; - } - } - - while (remainder > 0) && (self.iter.len() > 0) { - remainder -= 1; - let b = self.iter.as_slice()[0]; - let slurp = super::validations::utf8_char_width(b); - // SAFETY: utf8 validity requires that the string must contain - // the continuation bytes (if any) - unsafe { self.iter.advance_by(slurp).unwrap_unchecked() }; - } - - NonZero::new(remainder).map_or(Ok(()), Err) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let len = self.iter.len(); - // `(len + 3)` can't overflow, because we know that the `slice::Iter` - // belongs to a slice in memory which has a maximum length of - // `isize::MAX` (that's well below `usize::MAX`). - ((len + 3) / 4, Some(len)) - } - - #[inline] - fn last(mut self) -> Option { - // No need to go through the entire string. - self.next_back() - } -} - -#[stable(feature = "chars_debug_impl", since = "1.38.0")] -impl fmt::Debug for Chars<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "Chars(")?; - f.debug_list().entries(self.clone()).finish()?; - write!(f, ")")?; - Ok(()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a> DoubleEndedIterator for Chars<'a> { - #[inline] - fn next_back(&mut self) -> Option { - // SAFETY: `str` invariant says `self.iter` is a valid UTF-8 string and - // the resulting `ch` is a valid Unicode Scalar Value. - unsafe { next_code_point_reverse(&mut self.iter).map(|ch| char::from_u32_unchecked(ch)) } - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Chars<'_> {} - -impl<'a> Chars<'a> { - /// Views the underlying data as a subslice of the original data. - /// - /// This has the same lifetime as the original slice, and so the - /// iterator can continue to be used while this exists. - /// - /// # Examples - /// - /// ``` - /// let mut chars = "abc".chars(); - /// - /// assert_eq!(chars.as_str(), "abc"); - /// chars.next(); - /// assert_eq!(chars.as_str(), "bc"); - /// chars.next(); - /// chars.next(); - /// assert_eq!(chars.as_str(), ""); - /// ``` - #[stable(feature = "iter_to_slice", since = "1.4.0")] - #[must_use] - #[inline] - pub fn as_str(&self) -> &'a str { - // SAFETY: `Chars` is only made from a str, which guarantees the iter is valid UTF-8. - unsafe { from_utf8_unchecked(self.iter.as_slice()) } - } -} - -/// An iterator over the [`char`]s of a string slice, and their positions. -/// -/// This struct is created by the [`char_indices`] method on [`str`]. -/// See its documentation for more. -/// -/// [`char`]: prim@char -/// [`char_indices`]: str::char_indices -#[derive(Clone, Debug)] -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct CharIndices<'a> { - pub(super) front_offset: usize, - pub(super) iter: Chars<'a>, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a> Iterator for CharIndices<'a> { - type Item = (usize, char); - - #[inline] - fn next(&mut self) -> Option<(usize, char)> { - let pre_len = self.iter.iter.len(); - match self.iter.next() { - None => None, - Some(ch) => { - let index = self.front_offset; - let len = self.iter.iter.len(); - self.front_offset += pre_len - len; - Some((index, ch)) - } - } - } - - #[inline] - fn count(self) -> usize { - self.iter.count() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } - - #[inline] - fn last(mut self) -> Option<(usize, char)> { - // No need to go through the entire string. - self.next_back() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a> DoubleEndedIterator for CharIndices<'a> { - #[inline] - fn next_back(&mut self) -> Option<(usize, char)> { - self.iter.next_back().map(|ch| { - let index = self.front_offset + self.iter.iter.len(); - (index, ch) - }) - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for CharIndices<'_> {} - -impl<'a> CharIndices<'a> { - /// Views the underlying data as a subslice of the original data. - /// - /// This has the same lifetime as the original slice, and so the - /// iterator can continue to be used while this exists. - #[stable(feature = "iter_to_slice", since = "1.4.0")] - #[must_use] - #[inline] - pub fn as_str(&self) -> &'a str { - self.iter.as_str() - } - - /// Returns the byte position of the next character, or the length - /// of the underlying string if there are no more characters. - /// - /// # Examples - /// - /// ``` - /// #![feature(char_indices_offset)] - /// let mut chars = "a楽".char_indices(); - /// - /// assert_eq!(chars.offset(), 0); - /// assert_eq!(chars.next(), Some((0, 'a'))); - /// - /// assert_eq!(chars.offset(), 1); - /// assert_eq!(chars.next(), Some((1, '楽'))); - /// - /// assert_eq!(chars.offset(), 4); - /// assert_eq!(chars.next(), None); - /// ``` - #[inline] - #[must_use] - #[unstable(feature = "char_indices_offset", issue = "83871")] - pub fn offset(&self) -> usize { - self.front_offset - } -} - -/// An iterator over the bytes of a string slice. -/// -/// This struct is created by the [`bytes`] method on [`str`]. -/// See its documentation for more. -/// -/// [`bytes`]: str::bytes -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Clone, Debug)] -pub struct Bytes<'a>(pub(super) Copied>); - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for Bytes<'_> { - type Item = u8; - - #[inline] - fn next(&mut self) -> Option { - self.0.next() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.0.size_hint() - } - - #[inline] - fn count(self) -> usize { - self.0.count() - } - - #[inline] - fn last(self) -> Option { - self.0.last() - } - - #[inline] - fn nth(&mut self, n: usize) -> Option { - self.0.nth(n) - } - - #[inline] - fn all(&mut self, f: F) -> bool - where - F: FnMut(Self::Item) -> bool, - { - self.0.all(f) - } - - #[inline] - fn any(&mut self, f: F) -> bool - where - F: FnMut(Self::Item) -> bool, - { - self.0.any(f) - } - - #[inline] - fn find

(&mut self, predicate: P) -> Option - where - P: FnMut(&Self::Item) -> bool, - { - self.0.find(predicate) - } - - #[inline] - fn position

(&mut self, predicate: P) -> Option - where - P: FnMut(Self::Item) -> bool, - { - self.0.position(predicate) - } - - #[inline] - fn rposition

(&mut self, predicate: P) -> Option - where - P: FnMut(Self::Item) -> bool, - { - self.0.rposition(predicate) - } - - #[inline] - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> u8 { - // SAFETY: the caller must uphold the safety contract - // for `Iterator::__iterator_get_unchecked`. - unsafe { self.0.__iterator_get_unchecked(idx) } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DoubleEndedIterator for Bytes<'_> { - #[inline] - fn next_back(&mut self) -> Option { - self.0.next_back() - } - - #[inline] - fn nth_back(&mut self, n: usize) -> Option { - self.0.nth_back(n) - } - - #[inline] - fn rfind

(&mut self, predicate: P) -> Option - where - P: FnMut(&Self::Item) -> bool, - { - self.0.rfind(predicate) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Bytes<'_> { - #[inline] - fn len(&self) -> usize { - self.0.len() - } - - #[inline] - fn is_empty(&self) -> bool { - self.0.is_empty() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Bytes<'_> {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for Bytes<'_> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl TrustedRandomAccess for Bytes<'_> {} - -#[doc(hidden)] -#[unstable(feature = "trusted_random_access", issue = "none")] -unsafe impl TrustedRandomAccessNoCoerce for Bytes<'_> { - const MAY_HAVE_SIDE_EFFECT: bool = false; -} - -/// This macro generates a Clone impl for string pattern API -/// wrapper types of the form X<'a, P> -macro_rules! derive_pattern_clone { - (clone $t:ident with |$s:ident| $e:expr) => { - impl<'a, P> Clone for $t<'a, P> - where - P: Pattern<'a, Searcher: Clone>, - { - fn clone(&self) -> Self { - let $s = self; - $e - } - } - }; -} - -/// This macro generates two public iterator structs -/// wrapping a private internal one that makes use of the `Pattern` API. -/// -/// For all patterns `P: Pattern<'a>` the following items will be -/// generated (generics omitted): -/// -/// struct $forward_iterator($internal_iterator); -/// struct $reverse_iterator($internal_iterator); -/// -/// impl Iterator for $forward_iterator -/// { /* internal ends up calling Searcher::next_match() */ } -/// -/// impl DoubleEndedIterator for $forward_iterator -/// where P::Searcher: DoubleEndedSearcher -/// { /* internal ends up calling Searcher::next_match_back() */ } -/// -/// impl Iterator for $reverse_iterator -/// where P::Searcher: ReverseSearcher -/// { /* internal ends up calling Searcher::next_match_back() */ } -/// -/// impl DoubleEndedIterator for $reverse_iterator -/// where P::Searcher: DoubleEndedSearcher -/// { /* internal ends up calling Searcher::next_match() */ } -/// -/// The internal one is defined outside the macro, and has almost the same -/// semantic as a DoubleEndedIterator by delegating to `pattern::Searcher` and -/// `pattern::ReverseSearcher` for both forward and reverse iteration. -/// -/// "Almost", because a `Searcher` and a `ReverseSearcher` for a given -/// `Pattern` might not return the same elements, so actually implementing -/// `DoubleEndedIterator` for it would be incorrect. -/// (See the docs in `str::pattern` for more details) -/// -/// However, the internal struct still represents a single ended iterator from -/// either end, and depending on pattern is also a valid double ended iterator, -/// so the two wrapper structs implement `Iterator` -/// and `DoubleEndedIterator` depending on the concrete pattern type, leading -/// to the complex impls seen above. -macro_rules! generate_pattern_iterators { - { - // Forward iterator - forward: - $(#[$forward_iterator_attribute:meta])* - struct $forward_iterator:ident; - - // Reverse iterator - reverse: - $(#[$reverse_iterator_attribute:meta])* - struct $reverse_iterator:ident; - - // Stability of all generated items - stability: - $(#[$common_stability_attribute:meta])* - - // Internal almost-iterator that is being delegated to - internal: - $internal_iterator:ident yielding ($iterty:ty); - - // Kind of delegation - either single ended or double ended - delegate $($t:tt)* - } => { - $(#[$forward_iterator_attribute])* - $(#[$common_stability_attribute])* - pub struct $forward_iterator<'a, P: Pattern<'a>>(pub(super) $internal_iterator<'a, P>); - - $(#[$common_stability_attribute])* - impl<'a, P> fmt::Debug for $forward_iterator<'a, P> - where - P: Pattern<'a, Searcher: fmt::Debug>, - { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple(stringify!($forward_iterator)) - .field(&self.0) - .finish() - } - } - - $(#[$common_stability_attribute])* - impl<'a, P: Pattern<'a>> Iterator for $forward_iterator<'a, P> { - type Item = $iterty; - - #[inline] - fn next(&mut self) -> Option<$iterty> { - self.0.next() - } - } - - $(#[$common_stability_attribute])* - impl<'a, P> Clone for $forward_iterator<'a, P> - where - P: Pattern<'a, Searcher: Clone>, - { - fn clone(&self) -> Self { - $forward_iterator(self.0.clone()) - } - } - - $(#[$reverse_iterator_attribute])* - $(#[$common_stability_attribute])* - pub struct $reverse_iterator<'a, P: Pattern<'a>>(pub(super) $internal_iterator<'a, P>); - - $(#[$common_stability_attribute])* - impl<'a, P> fmt::Debug for $reverse_iterator<'a, P> - where - P: Pattern<'a, Searcher: fmt::Debug>, - { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple(stringify!($reverse_iterator)) - .field(&self.0) - .finish() - } - } - - $(#[$common_stability_attribute])* - impl<'a, P> Iterator for $reverse_iterator<'a, P> - where - P: Pattern<'a, Searcher: ReverseSearcher<'a>>, - { - type Item = $iterty; - - #[inline] - fn next(&mut self) -> Option<$iterty> { - self.0.next_back() - } - } - - $(#[$common_stability_attribute])* - impl<'a, P> Clone for $reverse_iterator<'a, P> - where - P: Pattern<'a, Searcher: Clone>, - { - fn clone(&self) -> Self { - $reverse_iterator(self.0.clone()) - } - } - - #[stable(feature = "fused", since = "1.26.0")] - impl<'a, P: Pattern<'a>> FusedIterator for $forward_iterator<'a, P> {} - - #[stable(feature = "fused", since = "1.26.0")] - impl<'a, P> FusedIterator for $reverse_iterator<'a, P> - where - P: Pattern<'a, Searcher: ReverseSearcher<'a>>, - {} - - generate_pattern_iterators!($($t)* with $(#[$common_stability_attribute])*, - $forward_iterator, - $reverse_iterator, $iterty); - }; - { - double ended; with $(#[$common_stability_attribute:meta])*, - $forward_iterator:ident, - $reverse_iterator:ident, $iterty:ty - } => { - $(#[$common_stability_attribute])* - impl<'a, P> DoubleEndedIterator for $forward_iterator<'a, P> - where - P: Pattern<'a, Searcher: DoubleEndedSearcher<'a>>, - { - #[inline] - fn next_back(&mut self) -> Option<$iterty> { - self.0.next_back() - } - } - - $(#[$common_stability_attribute])* - impl<'a, P> DoubleEndedIterator for $reverse_iterator<'a, P> - where - P: Pattern<'a, Searcher: DoubleEndedSearcher<'a>>, - { - #[inline] - fn next_back(&mut self) -> Option<$iterty> { - self.0.next() - } - } - }; - { - single ended; with $(#[$common_stability_attribute:meta])*, - $forward_iterator:ident, - $reverse_iterator:ident, $iterty:ty - } => {} -} - -derive_pattern_clone! { - clone SplitInternal - with |s| SplitInternal { matcher: s.matcher.clone(), ..*s } -} - -pub(super) struct SplitInternal<'a, P: Pattern<'a>> { - pub(super) start: usize, - pub(super) end: usize, - pub(super) matcher: P::Searcher, - pub(super) allow_trailing_empty: bool, - pub(super) finished: bool, -} - -impl<'a, P> fmt::Debug for SplitInternal<'a, P> -where - P: Pattern<'a, Searcher: fmt::Debug>, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("SplitInternal") - .field("start", &self.start) - .field("end", &self.end) - .field("matcher", &self.matcher) - .field("allow_trailing_empty", &self.allow_trailing_empty) - .field("finished", &self.finished) - .finish() - } -} - -impl<'a, P: Pattern<'a>> SplitInternal<'a, P> { - #[inline] - fn get_end(&mut self) -> Option<&'a str> { - if !self.finished { - self.finished = true; - - if self.allow_trailing_empty || self.end - self.start > 0 { - // SAFETY: `self.start` and `self.end` always lie on unicode boundaries. - let string = unsafe { self.matcher.haystack().get_unchecked(self.start..self.end) }; - return Some(string); - } - } - - None - } - - #[inline] - fn next(&mut self) -> Option<&'a str> { - if self.finished { - return None; - } - - let haystack = self.matcher.haystack(); - match self.matcher.next_match() { - // SAFETY: `Searcher` guarantees that `a` and `b` lie on unicode boundaries. - Some((a, b)) => unsafe { - let elt = haystack.get_unchecked(self.start..a); - self.start = b; - Some(elt) - }, - None => self.get_end(), - } - } - - #[inline] - fn next_inclusive(&mut self) -> Option<&'a str> { - if self.finished { - return None; - } - - let haystack = self.matcher.haystack(); - match self.matcher.next_match() { - // SAFETY: `Searcher` guarantees that `b` lies on unicode boundary, - // and self.start is either the start of the original string, - // or `b` was assigned to it, so it also lies on unicode boundary. - Some((_, b)) => unsafe { - let elt = haystack.get_unchecked(self.start..b); - self.start = b; - Some(elt) - }, - None => self.get_end(), - } - } - - #[inline] - fn next_back(&mut self) -> Option<&'a str> - where - P::Searcher: ReverseSearcher<'a>, - { - if self.finished { - return None; - } - - if !self.allow_trailing_empty { - self.allow_trailing_empty = true; - match self.next_back() { - Some(elt) if !elt.is_empty() => return Some(elt), - _ => { - if self.finished { - return None; - } - } - } - } - - let haystack = self.matcher.haystack(); - match self.matcher.next_match_back() { - // SAFETY: `Searcher` guarantees that `a` and `b` lie on unicode boundaries. - Some((a, b)) => unsafe { - let elt = haystack.get_unchecked(b..self.end); - self.end = a; - Some(elt) - }, - // SAFETY: `self.start` and `self.end` always lie on unicode boundaries. - None => unsafe { - self.finished = true; - Some(haystack.get_unchecked(self.start..self.end)) - }, - } - } - - #[inline] - fn next_back_inclusive(&mut self) -> Option<&'a str> - where - P::Searcher: ReverseSearcher<'a>, - { - if self.finished { - return None; - } - - if !self.allow_trailing_empty { - self.allow_trailing_empty = true; - match self.next_back_inclusive() { - Some(elt) if !elt.is_empty() => return Some(elt), - _ => { - if self.finished { - return None; - } - } - } - } - - let haystack = self.matcher.haystack(); - match self.matcher.next_match_back() { - // SAFETY: `Searcher` guarantees that `b` lies on unicode boundary, - // and self.end is either the end of the original string, - // or `b` was assigned to it, so it also lies on unicode boundary. - Some((_, b)) => unsafe { - let elt = haystack.get_unchecked(b..self.end); - self.end = b; - Some(elt) - }, - // SAFETY: self.start is either the start of the original string, - // or start of a substring that represents the part of the string that hasn't - // iterated yet. Either way, it is guaranteed to lie on unicode boundary. - // self.end is either the end of the original string, - // or `b` was assigned to it, so it also lies on unicode boundary. - None => unsafe { - self.finished = true; - Some(haystack.get_unchecked(self.start..self.end)) - }, - } - } - - #[inline] - fn remainder(&self) -> Option<&'a str> { - // `Self::get_end` doesn't change `self.start` - if self.finished { - return None; - } - - // SAFETY: `self.start` and `self.end` always lie on unicode boundaries. - Some(unsafe { self.matcher.haystack().get_unchecked(self.start..self.end) }) - } -} - -generate_pattern_iterators! { - forward: - /// Created with the method [`split`]. - /// - /// [`split`]: str::split - struct Split; - reverse: - /// Created with the method [`rsplit`]. - /// - /// [`rsplit`]: str::rsplit - struct RSplit; - stability: - #[stable(feature = "rust1", since = "1.0.0")] - internal: - SplitInternal yielding (&'a str); - delegate double ended; -} - -impl<'a, P: Pattern<'a>> Split<'a, P> { - /// Returns remainder of the split string. - /// - /// If the iterator is empty, returns `None`. - /// - /// # Examples - /// - /// ``` - /// #![feature(str_split_remainder)] - /// let mut split = "Mary had a little lamb".split(' '); - /// assert_eq!(split.remainder(), Some("Mary had a little lamb")); - /// split.next(); - /// assert_eq!(split.remainder(), Some("had a little lamb")); - /// split.by_ref().for_each(drop); - /// assert_eq!(split.remainder(), None); - /// ``` - #[inline] - #[unstable(feature = "str_split_remainder", issue = "77998")] - pub fn remainder(&self) -> Option<&'a str> { - self.0.remainder() - } -} - -impl<'a, P: Pattern<'a>> RSplit<'a, P> { - /// Returns remainder of the split string. - /// - /// If the iterator is empty, returns `None`. - /// - /// # Examples - /// - /// ``` - /// #![feature(str_split_remainder)] - /// let mut split = "Mary had a little lamb".rsplit(' '); - /// assert_eq!(split.remainder(), Some("Mary had a little lamb")); - /// split.next(); - /// assert_eq!(split.remainder(), Some("Mary had a little")); - /// split.by_ref().for_each(drop); - /// assert_eq!(split.remainder(), None); - /// ``` - #[inline] - #[unstable(feature = "str_split_remainder", issue = "77998")] - pub fn remainder(&self) -> Option<&'a str> { - self.0.remainder() - } -} - -generate_pattern_iterators! { - forward: - /// Created with the method [`split_terminator`]. - /// - /// [`split_terminator`]: str::split_terminator - struct SplitTerminator; - reverse: - /// Created with the method [`rsplit_terminator`]. - /// - /// [`rsplit_terminator`]: str::rsplit_terminator - struct RSplitTerminator; - stability: - #[stable(feature = "rust1", since = "1.0.0")] - internal: - SplitInternal yielding (&'a str); - delegate double ended; -} - -impl<'a, P: Pattern<'a>> SplitTerminator<'a, P> { - /// Returns remainder of the split string. - /// - /// If the iterator is empty, returns `None`. - /// - /// # Examples - /// - /// ``` - /// #![feature(str_split_remainder)] - /// let mut split = "A..B..".split_terminator('.'); - /// assert_eq!(split.remainder(), Some("A..B..")); - /// split.next(); - /// assert_eq!(split.remainder(), Some(".B..")); - /// split.by_ref().for_each(drop); - /// assert_eq!(split.remainder(), None); - /// ``` - #[inline] - #[unstable(feature = "str_split_remainder", issue = "77998")] - pub fn remainder(&self) -> Option<&'a str> { - self.0.remainder() - } -} - -impl<'a, P: Pattern<'a>> RSplitTerminator<'a, P> { - /// Returns remainder of the split string. - /// - /// If the iterator is empty, returns `None`. - /// - /// # Examples - /// - /// ``` - /// #![feature(str_split_remainder)] - /// let mut split = "A..B..".rsplit_terminator('.'); - /// assert_eq!(split.remainder(), Some("A..B..")); - /// split.next(); - /// assert_eq!(split.remainder(), Some("A..B")); - /// split.by_ref().for_each(drop); - /// assert_eq!(split.remainder(), None); - /// ``` - #[inline] - #[unstable(feature = "str_split_remainder", issue = "77998")] - pub fn remainder(&self) -> Option<&'a str> { - self.0.remainder() - } -} - -derive_pattern_clone! { - clone SplitNInternal - with |s| SplitNInternal { iter: s.iter.clone(), ..*s } -} - -pub(super) struct SplitNInternal<'a, P: Pattern<'a>> { - pub(super) iter: SplitInternal<'a, P>, - /// The number of splits remaining - pub(super) count: usize, -} - -impl<'a, P> fmt::Debug for SplitNInternal<'a, P> -where - P: Pattern<'a, Searcher: fmt::Debug>, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("SplitNInternal") - .field("iter", &self.iter) - .field("count", &self.count) - .finish() - } -} - -impl<'a, P: Pattern<'a>> SplitNInternal<'a, P> { - #[inline] - fn next(&mut self) -> Option<&'a str> { - match self.count { - 0 => None, - 1 => { - self.count = 0; - self.iter.get_end() - } - _ => { - self.count -= 1; - self.iter.next() - } - } - } - - #[inline] - fn next_back(&mut self) -> Option<&'a str> - where - P::Searcher: ReverseSearcher<'a>, - { - match self.count { - 0 => None, - 1 => { - self.count = 0; - self.iter.get_end() - } - _ => { - self.count -= 1; - self.iter.next_back() - } - } - } - - #[inline] - fn remainder(&self) -> Option<&'a str> { - self.iter.remainder() - } -} - -generate_pattern_iterators! { - forward: - /// Created with the method [`splitn`]. - /// - /// [`splitn`]: str::splitn - struct SplitN; - reverse: - /// Created with the method [`rsplitn`]. - /// - /// [`rsplitn`]: str::rsplitn - struct RSplitN; - stability: - #[stable(feature = "rust1", since = "1.0.0")] - internal: - SplitNInternal yielding (&'a str); - delegate single ended; -} - -impl<'a, P: Pattern<'a>> SplitN<'a, P> { - /// Returns remainder of the split string. - /// - /// If the iterator is empty, returns `None`. - /// - /// # Examples - /// - /// ``` - /// #![feature(str_split_remainder)] - /// let mut split = "Mary had a little lamb".splitn(3, ' '); - /// assert_eq!(split.remainder(), Some("Mary had a little lamb")); - /// split.next(); - /// assert_eq!(split.remainder(), Some("had a little lamb")); - /// split.by_ref().for_each(drop); - /// assert_eq!(split.remainder(), None); - /// ``` - #[inline] - #[unstable(feature = "str_split_remainder", issue = "77998")] - pub fn remainder(&self) -> Option<&'a str> { - self.0.remainder() - } -} - -impl<'a, P: Pattern<'a>> RSplitN<'a, P> { - /// Returns remainder of the split string. - /// - /// If the iterator is empty, returns `None`. - /// - /// # Examples - /// - /// ``` - /// #![feature(str_split_remainder)] - /// let mut split = "Mary had a little lamb".rsplitn(3, ' '); - /// assert_eq!(split.remainder(), Some("Mary had a little lamb")); - /// split.next(); - /// assert_eq!(split.remainder(), Some("Mary had a little")); - /// split.by_ref().for_each(drop); - /// assert_eq!(split.remainder(), None); - /// ``` - #[inline] - #[unstable(feature = "str_split_remainder", issue = "77998")] - pub fn remainder(&self) -> Option<&'a str> { - self.0.remainder() - } -} - -derive_pattern_clone! { - clone MatchIndicesInternal - with |s| MatchIndicesInternal(s.0.clone()) -} - -pub(super) struct MatchIndicesInternal<'a, P: Pattern<'a>>(pub(super) P::Searcher); - -impl<'a, P> fmt::Debug for MatchIndicesInternal<'a, P> -where - P: Pattern<'a, Searcher: fmt::Debug>, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("MatchIndicesInternal").field(&self.0).finish() - } -} - -impl<'a, P: Pattern<'a>> MatchIndicesInternal<'a, P> { - #[inline] - fn next(&mut self) -> Option<(usize, &'a str)> { - self.0 - .next_match() - // SAFETY: `Searcher` guarantees that `start` and `end` lie on unicode boundaries. - .map(|(start, end)| unsafe { (start, self.0.haystack().get_unchecked(start..end)) }) - } - - #[inline] - fn next_back(&mut self) -> Option<(usize, &'a str)> - where - P::Searcher: ReverseSearcher<'a>, - { - self.0 - .next_match_back() - // SAFETY: `Searcher` guarantees that `start` and `end` lie on unicode boundaries. - .map(|(start, end)| unsafe { (start, self.0.haystack().get_unchecked(start..end)) }) - } -} - -generate_pattern_iterators! { - forward: - /// Created with the method [`match_indices`]. - /// - /// [`match_indices`]: str::match_indices - struct MatchIndices; - reverse: - /// Created with the method [`rmatch_indices`]. - /// - /// [`rmatch_indices`]: str::rmatch_indices - struct RMatchIndices; - stability: - #[stable(feature = "str_match_indices", since = "1.5.0")] - internal: - MatchIndicesInternal yielding ((usize, &'a str)); - delegate double ended; -} - -derive_pattern_clone! { - clone MatchesInternal - with |s| MatchesInternal(s.0.clone()) -} - -pub(super) struct MatchesInternal<'a, P: Pattern<'a>>(pub(super) P::Searcher); - -impl<'a, P> fmt::Debug for MatchesInternal<'a, P> -where - P: Pattern<'a, Searcher: fmt::Debug>, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("MatchesInternal").field(&self.0).finish() - } -} - -impl<'a, P: Pattern<'a>> MatchesInternal<'a, P> { - #[inline] - fn next(&mut self) -> Option<&'a str> { - // SAFETY: `Searcher` guarantees that `start` and `end` lie on unicode boundaries. - self.0.next_match().map(|(a, b)| unsafe { - // Indices are known to be on utf8 boundaries - self.0.haystack().get_unchecked(a..b) - }) - } - - #[inline] - fn next_back(&mut self) -> Option<&'a str> - where - P::Searcher: ReverseSearcher<'a>, - { - // SAFETY: `Searcher` guarantees that `start` and `end` lie on unicode boundaries. - self.0.next_match_back().map(|(a, b)| unsafe { - // Indices are known to be on utf8 boundaries - self.0.haystack().get_unchecked(a..b) - }) - } -} - -generate_pattern_iterators! { - forward: - /// Created with the method [`matches`]. - /// - /// [`matches`]: str::matches - struct Matches; - reverse: - /// Created with the method [`rmatches`]. - /// - /// [`rmatches`]: str::rmatches - struct RMatches; - stability: - #[stable(feature = "str_matches", since = "1.2.0")] - internal: - MatchesInternal yielding (&'a str); - delegate double ended; -} - -/// An iterator over the lines of a string, as string slices. -/// -/// This struct is created with the [`lines`] method on [`str`]. -/// See its documentation for more. -/// -/// [`lines`]: str::lines -#[stable(feature = "rust1", since = "1.0.0")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[derive(Clone, Debug)] -pub struct Lines<'a>(pub(super) Map, LinesMap>); - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a> Iterator for Lines<'a> { - type Item = &'a str; - - #[inline] - fn next(&mut self) -> Option<&'a str> { - self.0.next() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.0.size_hint() - } - - #[inline] - fn last(mut self) -> Option<&'a str> { - self.next_back() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a> DoubleEndedIterator for Lines<'a> { - #[inline] - fn next_back(&mut self) -> Option<&'a str> { - self.0.next_back() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Lines<'_> {} - -impl<'a> Lines<'a> { - /// Returns the remaining lines of the split string. - /// - /// # Examples - /// - /// ``` - /// #![feature(str_lines_remainder)] - /// - /// let mut lines = "a\nb\nc\nd".lines(); - /// assert_eq!(lines.remainder(), Some("a\nb\nc\nd")); - /// - /// lines.next(); - /// assert_eq!(lines.remainder(), Some("b\nc\nd")); - /// - /// lines.by_ref().for_each(drop); - /// assert_eq!(lines.remainder(), None); - /// ``` - #[inline] - #[must_use] - #[unstable(feature = "str_lines_remainder", issue = "77998")] - pub fn remainder(&self) -> Option<&'a str> { - self.0.iter.remainder() - } -} - -/// Created with the method [`lines_any`]. -/// -/// [`lines_any`]: str::lines_any -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "1.4.0", note = "use lines()/Lines instead now")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[derive(Clone, Debug)] -#[allow(deprecated)] -pub struct LinesAny<'a>(pub(super) Lines<'a>); - -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated)] -impl<'a> Iterator for LinesAny<'a> { - type Item = &'a str; - - #[inline] - fn next(&mut self) -> Option<&'a str> { - self.0.next() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.0.size_hint() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated)] -impl<'a> DoubleEndedIterator for LinesAny<'a> { - #[inline] - fn next_back(&mut self) -> Option<&'a str> { - self.0.next_back() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -#[allow(deprecated)] -impl FusedIterator for LinesAny<'_> {} - -/// An iterator over the non-whitespace substrings of a string, -/// separated by any amount of whitespace. -/// -/// This struct is created by the [`split_whitespace`] method on [`str`]. -/// See its documentation for more. -/// -/// [`split_whitespace`]: str::split_whitespace -#[stable(feature = "split_whitespace", since = "1.1.0")] -#[derive(Clone, Debug)] -pub struct SplitWhitespace<'a> { - pub(super) inner: Filter, IsNotEmpty>, -} - -/// An iterator over the non-ASCII-whitespace substrings of a string, -/// separated by any amount of ASCII whitespace. -/// -/// This struct is created by the [`split_ascii_whitespace`] method on [`str`]. -/// See its documentation for more. -/// -/// [`split_ascii_whitespace`]: str::split_ascii_whitespace -#[stable(feature = "split_ascii_whitespace", since = "1.34.0")] -#[derive(Clone, Debug)] -pub struct SplitAsciiWhitespace<'a> { - pub(super) inner: Map< - Filter, BytesIsNotEmpty<'a>>, - UnsafeBytesToStr<'a>, - >, -} - -/// An iterator over the substrings of a string, -/// terminated by a substring matching to a predicate function -/// Unlike `Split`, it contains the matched part as a terminator -/// of the subslice. -/// -/// This struct is created by the [`split_inclusive`] method on [`str`]. -/// See its documentation for more. -/// -/// [`split_inclusive`]: str::split_inclusive -#[stable(feature = "split_inclusive", since = "1.51.0")] -pub struct SplitInclusive<'a, P: Pattern<'a>>(pub(super) SplitInternal<'a, P>); - -#[stable(feature = "split_whitespace", since = "1.1.0")] -impl<'a> Iterator for SplitWhitespace<'a> { - type Item = &'a str; - - #[inline] - fn next(&mut self) -> Option<&'a str> { - self.inner.next() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } - - #[inline] - fn last(mut self) -> Option<&'a str> { - self.next_back() - } -} - -#[stable(feature = "split_whitespace", since = "1.1.0")] -impl<'a> DoubleEndedIterator for SplitWhitespace<'a> { - #[inline] - fn next_back(&mut self) -> Option<&'a str> { - self.inner.next_back() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for SplitWhitespace<'_> {} - -impl<'a> SplitWhitespace<'a> { - /// Returns remainder of the split string - /// - /// # Examples - /// - /// ``` - /// #![feature(str_split_whitespace_remainder)] - /// - /// let mut split = "Mary had a little lamb".split_whitespace(); - /// assert_eq!(split.remainder(), Some("Mary had a little lamb")); - /// - /// split.next(); - /// assert_eq!(split.remainder(), Some("had a little lamb")); - /// - /// split.by_ref().for_each(drop); - /// assert_eq!(split.remainder(), None); - /// ``` - #[inline] - #[must_use] - #[unstable(feature = "str_split_whitespace_remainder", issue = "77998")] - pub fn remainder(&self) -> Option<&'a str> { - self.inner.iter.remainder() - } -} - -#[stable(feature = "split_ascii_whitespace", since = "1.34.0")] -impl<'a> Iterator for SplitAsciiWhitespace<'a> { - type Item = &'a str; - - #[inline] - fn next(&mut self) -> Option<&'a str> { - self.inner.next() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } - - #[inline] - fn last(mut self) -> Option<&'a str> { - self.next_back() - } -} - -#[stable(feature = "split_ascii_whitespace", since = "1.34.0")] -impl<'a> DoubleEndedIterator for SplitAsciiWhitespace<'a> { - #[inline] - fn next_back(&mut self) -> Option<&'a str> { - self.inner.next_back() - } -} - -#[stable(feature = "split_ascii_whitespace", since = "1.34.0")] -impl FusedIterator for SplitAsciiWhitespace<'_> {} - -impl<'a> SplitAsciiWhitespace<'a> { - /// Returns remainder of the split string. - /// - /// If the iterator is empty, returns `None`. - /// - /// # Examples - /// - /// ``` - /// #![feature(str_split_whitespace_remainder)] - /// - /// let mut split = "Mary had a little lamb".split_ascii_whitespace(); - /// assert_eq!(split.remainder(), Some("Mary had a little lamb")); - /// - /// split.next(); - /// assert_eq!(split.remainder(), Some("had a little lamb")); - /// - /// split.by_ref().for_each(drop); - /// assert_eq!(split.remainder(), None); - /// ``` - #[inline] - #[must_use] - #[unstable(feature = "str_split_whitespace_remainder", issue = "77998")] - pub fn remainder(&self) -> Option<&'a str> { - if self.inner.iter.iter.finished { - return None; - } - - // SAFETY: Slice is created from str. - Some(unsafe { crate::str::from_utf8_unchecked(&self.inner.iter.iter.v) }) - } -} - -#[stable(feature = "split_inclusive", since = "1.51.0")] -impl<'a, P: Pattern<'a>> Iterator for SplitInclusive<'a, P> { - type Item = &'a str; - - #[inline] - fn next(&mut self) -> Option<&'a str> { - self.0.next_inclusive() - } -} - -#[stable(feature = "split_inclusive", since = "1.51.0")] -impl<'a, P: Pattern<'a, Searcher: fmt::Debug>> fmt::Debug for SplitInclusive<'a, P> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("SplitInclusive").field("0", &self.0).finish() - } -} - -// FIXME(#26925) Remove in favor of `#[derive(Clone)]` -#[stable(feature = "split_inclusive", since = "1.51.0")] -impl<'a, P: Pattern<'a, Searcher: Clone>> Clone for SplitInclusive<'a, P> { - fn clone(&self) -> Self { - SplitInclusive(self.0.clone()) - } -} - -#[stable(feature = "split_inclusive", since = "1.51.0")] -impl<'a, P: Pattern<'a, Searcher: DoubleEndedSearcher<'a>>> DoubleEndedIterator - for SplitInclusive<'a, P> -{ - #[inline] - fn next_back(&mut self) -> Option<&'a str> { - self.0.next_back_inclusive() - } -} - -#[stable(feature = "split_inclusive", since = "1.51.0")] -impl<'a, P: Pattern<'a>> FusedIterator for SplitInclusive<'a, P> {} - -impl<'a, P: Pattern<'a>> SplitInclusive<'a, P> { - /// Returns remainder of the split string. - /// - /// If the iterator is empty, returns `None`. - /// - /// # Examples - /// - /// ``` - /// #![feature(str_split_inclusive_remainder)] - /// let mut split = "Mary had a little lamb".split_inclusive(' '); - /// assert_eq!(split.remainder(), Some("Mary had a little lamb")); - /// split.next(); - /// assert_eq!(split.remainder(), Some("had a little lamb")); - /// split.by_ref().for_each(drop); - /// assert_eq!(split.remainder(), None); - /// ``` - #[inline] - #[unstable(feature = "str_split_inclusive_remainder", issue = "77998")] - pub fn remainder(&self) -> Option<&'a str> { - self.0.remainder() - } -} - -/// An iterator of [`u16`] over the string encoded as UTF-16. -/// -/// This struct is created by the [`encode_utf16`] method on [`str`]. -/// See its documentation for more. -/// -/// [`encode_utf16`]: str::encode_utf16 -#[derive(Clone)] -#[stable(feature = "encode_utf16", since = "1.8.0")] -pub struct EncodeUtf16<'a> { - pub(super) chars: Chars<'a>, - pub(super) extra: u16, -} - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl fmt::Debug for EncodeUtf16<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("EncodeUtf16").finish_non_exhaustive() - } -} - -#[stable(feature = "encode_utf16", since = "1.8.0")] -impl<'a> Iterator for EncodeUtf16<'a> { - type Item = u16; - - #[inline] - fn next(&mut self) -> Option { - if self.extra != 0 { - let tmp = self.extra; - self.extra = 0; - return Some(tmp); - } - - let mut buf = [0; 2]; - self.chars.next().map(|ch| { - let n = ch.encode_utf16(&mut buf).len(); - if n == 2 { - self.extra = buf[1]; - } - buf[0] - }) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let len = self.chars.iter.len(); - // The highest bytes:code units ratio occurs for 3-byte sequences, - // since a 4-byte sequence results in 2 code units. The lower bound - // is therefore determined by assuming the remaining bytes contain as - // many 3-byte sequences as possible. The highest bytes:code units - // ratio is for 1-byte sequences, so use this for the upper bound. - // `(len + 2)` can't overflow, because we know that the `slice::Iter` - // belongs to a slice in memory which has a maximum length of - // `isize::MAX` (that's well below `usize::MAX`) - if self.extra == 0 { - ((len + 2) / 3, Some(len)) - } else { - // We're in the middle of a surrogate pair, so add the remaining - // surrogate to the bounds. - ((len + 2) / 3 + 1, Some(len + 1)) - } - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for EncodeUtf16<'_> {} - -/// The return type of [`str::escape_debug`]. -#[stable(feature = "str_escape", since = "1.34.0")] -#[derive(Clone, Debug)] -pub struct EscapeDebug<'a> { - pub(super) inner: Chain< - Flatten>, - FlatMap, char_mod::EscapeDebug, CharEscapeDebugContinue>, - >, -} - -/// The return type of [`str::escape_default`]. -#[stable(feature = "str_escape", since = "1.34.0")] -#[derive(Clone, Debug)] -pub struct EscapeDefault<'a> { - pub(super) inner: FlatMap, char_mod::EscapeDefault, CharEscapeDefault>, -} - -/// The return type of [`str::escape_unicode`]. -#[stable(feature = "str_escape", since = "1.34.0")] -#[derive(Clone, Debug)] -pub struct EscapeUnicode<'a> { - pub(super) inner: FlatMap, char_mod::EscapeUnicode, CharEscapeUnicode>, -} - -macro_rules! escape_types_impls { - ($( $Name: ident ),+) => {$( - #[stable(feature = "str_escape", since = "1.34.0")] - impl<'a> fmt::Display for $Name<'a> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.clone().try_for_each(|c| f.write_char(c)) - } - } - - #[stable(feature = "str_escape", since = "1.34.0")] - impl<'a> Iterator for $Name<'a> { - type Item = char; - - #[inline] - fn next(&mut self) -> Option { self.inner.next() } - - #[inline] - fn size_hint(&self) -> (usize, Option) { self.inner.size_hint() } - - #[inline] - fn try_fold(&mut self, init: Acc, fold: Fold) -> R where - Self: Sized, Fold: FnMut(Acc, Self::Item) -> R, R: Try - { - self.inner.try_fold(init, fold) - } - - #[inline] - fn fold(self, init: Acc, fold: Fold) -> Acc - where Fold: FnMut(Acc, Self::Item) -> Acc, - { - self.inner.fold(init, fold) - } - } - - #[stable(feature = "str_escape", since = "1.34.0")] - impl<'a> FusedIterator for $Name<'a> {} - )+} -} - -escape_types_impls!(EscapeDebug, EscapeDefault, EscapeUnicode); diff --git a/library/core/src/str/lossy.rs b/library/core/src/str/lossy.rs deleted file mode 100644 index 51a0777c2d613..0000000000000 --- a/library/core/src/str/lossy.rs +++ /dev/null @@ -1,296 +0,0 @@ -use crate::fmt; -use crate::fmt::Formatter; -use crate::fmt::Write; -use crate::iter::FusedIterator; - -use super::from_utf8_unchecked; -use super::validations::utf8_char_width; - -impl [u8] { - /// Creates an iterator over the contiguous valid UTF-8 ranges of this - /// slice, and the non-UTF-8 fragments in between. - /// - /// # Examples - /// - /// This function formats arbitrary but mostly-UTF-8 bytes into Rust source - /// code in the form of a C-string literal (`c"..."`). - /// - /// ``` - /// use std::fmt::Write as _; - /// - /// pub fn cstr_literal(bytes: &[u8]) -> String { - /// let mut repr = String::new(); - /// repr.push_str("c\""); - /// for chunk in bytes.utf8_chunks() { - /// for ch in chunk.valid().chars() { - /// // Escapes \0, \t, \r, \n, \\, \', \", and uses \u{...} for non-printable characters. - /// write!(repr, "{}", ch.escape_debug()).unwrap(); - /// } - /// for byte in chunk.invalid() { - /// write!(repr, "\\x{:02X}", byte).unwrap(); - /// } - /// } - /// repr.push('"'); - /// repr - /// } - /// - /// fn main() { - /// let lit = cstr_literal(b"\xferris the \xf0\x9f\xa6\x80\x07"); - /// let expected = stringify!(c"\xFErris the 🦀\u{7}"); - /// assert_eq!(lit, expected); - /// } - /// ``` - #[stable(feature = "utf8_chunks", since = "1.79.0")] - pub fn utf8_chunks(&self) -> Utf8Chunks<'_> { - Utf8Chunks { source: self } - } -} - -/// An item returned by the [`Utf8Chunks`] iterator. -/// -/// A `Utf8Chunk` stores a sequence of [`u8`] up to the first broken character -/// when decoding a UTF-8 string. -/// -/// # Examples -/// -/// ``` -/// // An invalid UTF-8 string -/// let bytes = b"foo\xF1\x80bar"; -/// -/// // Decode the first `Utf8Chunk` -/// let chunk = bytes.utf8_chunks().next().unwrap(); -/// -/// // The first three characters are valid UTF-8 -/// assert_eq!("foo", chunk.valid()); -/// -/// // The fourth character is broken -/// assert_eq!(b"\xF1\x80", chunk.invalid()); -/// ``` -#[stable(feature = "utf8_chunks", since = "1.79.0")] -#[derive(Clone, Debug, PartialEq, Eq)] -pub struct Utf8Chunk<'a> { - valid: &'a str, - invalid: &'a [u8], -} - -impl<'a> Utf8Chunk<'a> { - /// Returns the next validated UTF-8 substring. - /// - /// This substring can be empty at the start of the string or between - /// broken UTF-8 characters. - #[must_use] - #[stable(feature = "utf8_chunks", since = "1.79.0")] - pub fn valid(&self) -> &'a str { - self.valid - } - - /// Returns the invalid sequence that caused a failure. - /// - /// The returned slice will have a maximum length of 3 and starts after the - /// substring given by [`valid`]. Decoding will resume after this sequence. - /// - /// If empty, this is the last chunk in the string. If non-empty, an - /// unexpected byte was encountered or the end of the input was reached - /// unexpectedly. - /// - /// Lossy decoding would replace this sequence with [`U+FFFD REPLACEMENT - /// CHARACTER`]. - /// - /// [`valid`]: Self::valid - /// [`U+FFFD REPLACEMENT CHARACTER`]: crate::char::REPLACEMENT_CHARACTER - #[must_use] - #[stable(feature = "utf8_chunks", since = "1.79.0")] - pub fn invalid(&self) -> &'a [u8] { - self.invalid - } -} - -#[must_use] -#[unstable(feature = "str_internals", issue = "none")] -pub struct Debug<'a>(&'a [u8]); - -#[unstable(feature = "str_internals", issue = "none")] -impl fmt::Debug for Debug<'_> { - fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { - f.write_char('"')?; - - for chunk in self.0.utf8_chunks() { - // Valid part. - // Here we partially parse UTF-8 again which is suboptimal. - { - let valid = chunk.valid(); - let mut from = 0; - for (i, c) in valid.char_indices() { - let esc = c.escape_debug(); - // If char needs escaping, flush backlog so far and write, else skip - if esc.len() != 1 { - f.write_str(&valid[from..i])?; - for c in esc { - f.write_char(c)?; - } - from = i + c.len_utf8(); - } - } - f.write_str(&valid[from..])?; - } - - // Broken parts of string as hex escape. - for &b in chunk.invalid() { - write!(f, "\\x{:02X}", b)?; - } - } - - f.write_char('"') - } -} - -/// An iterator used to decode a slice of mostly UTF-8 bytes to string slices -/// ([`&str`]) and byte slices ([`&[u8]`][byteslice]). -/// -/// If you want a simple conversion from UTF-8 byte slices to string slices, -/// [`from_utf8`] is easier to use. -/// -/// [byteslice]: slice -/// [`from_utf8`]: super::from_utf8 -/// -/// # Examples -/// -/// This can be used to create functionality similar to -/// [`String::from_utf8_lossy`] without allocating heap memory: -/// -/// ``` -/// fn from_utf8_lossy(input: &[u8], mut push: F) where F: FnMut(&str) { -/// for chunk in input.utf8_chunks() { -/// push(chunk.valid()); -/// -/// if !chunk.invalid().is_empty() { -/// push("\u{FFFD}"); -/// } -/// } -/// } -/// ``` -/// -/// [`String::from_utf8_lossy`]: ../../std/string/struct.String.html#method.from_utf8_lossy -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "utf8_chunks", since = "1.79.0")] -#[derive(Clone)] -pub struct Utf8Chunks<'a> { - source: &'a [u8], -} - -impl<'a> Utf8Chunks<'a> { - #[doc(hidden)] - #[unstable(feature = "str_internals", issue = "none")] - pub fn debug(&self) -> Debug<'_> { - Debug(self.source) - } -} - -#[stable(feature = "utf8_chunks", since = "1.79.0")] -impl<'a> Iterator for Utf8Chunks<'a> { - type Item = Utf8Chunk<'a>; - - fn next(&mut self) -> Option> { - if self.source.is_empty() { - return None; - } - - const TAG_CONT_U8: u8 = 128; - fn safe_get(xs: &[u8], i: usize) -> u8 { - *xs.get(i).unwrap_or(&0) - } - - let mut i = 0; - let mut valid_up_to = 0; - while i < self.source.len() { - // SAFETY: `i < self.source.len()` per previous line. - // For some reason the following are both significantly slower: - // while let Some(&byte) = self.source.get(i) { - // while let Some(byte) = self.source.get(i).copied() { - let byte = unsafe { *self.source.get_unchecked(i) }; - i += 1; - - if byte < 128 { - // This could be a `1 => ...` case in the match below, but for - // the common case of all-ASCII inputs, we bypass loading the - // sizeable UTF8_CHAR_WIDTH table into cache. - } else { - let w = utf8_char_width(byte); - - match w { - 2 => { - if safe_get(self.source, i) & 192 != TAG_CONT_U8 { - break; - } - i += 1; - } - 3 => { - match (byte, safe_get(self.source, i)) { - (0xE0, 0xA0..=0xBF) => (), - (0xE1..=0xEC, 0x80..=0xBF) => (), - (0xED, 0x80..=0x9F) => (), - (0xEE..=0xEF, 0x80..=0xBF) => (), - _ => break, - } - i += 1; - if safe_get(self.source, i) & 192 != TAG_CONT_U8 { - break; - } - i += 1; - } - 4 => { - match (byte, safe_get(self.source, i)) { - (0xF0, 0x90..=0xBF) => (), - (0xF1..=0xF3, 0x80..=0xBF) => (), - (0xF4, 0x80..=0x8F) => (), - _ => break, - } - i += 1; - if safe_get(self.source, i) & 192 != TAG_CONT_U8 { - break; - } - i += 1; - if safe_get(self.source, i) & 192 != TAG_CONT_U8 { - break; - } - i += 1; - } - _ => break, - } - } - - valid_up_to = i; - } - - // SAFETY: `i <= self.source.len()` because it is only ever incremented - // via `i += 1` and in between every single one of those increments, `i` - // is compared against `self.source.len()`. That happens either - // literally by `i < self.source.len()` in the while-loop's condition, - // or indirectly by `safe_get(self.source, i) & 192 != TAG_CONT_U8`. The - // loop is terminated as soon as the latest `i += 1` has made `i` no - // longer less than `self.source.len()`, which means it'll be at most - // equal to `self.source.len()`. - let (inspected, remaining) = unsafe { self.source.split_at_unchecked(i) }; - self.source = remaining; - - // SAFETY: `valid_up_to <= i` because it is only ever assigned via - // `valid_up_to = i` and `i` only increases. - let (valid, invalid) = unsafe { inspected.split_at_unchecked(valid_up_to) }; - - Some(Utf8Chunk { - // SAFETY: All bytes up to `valid_up_to` are valid UTF-8. - valid: unsafe { from_utf8_unchecked(valid) }, - invalid, - }) - } -} - -#[stable(feature = "utf8_chunks", since = "1.79.0")] -impl FusedIterator for Utf8Chunks<'_> {} - -#[stable(feature = "utf8_chunks", since = "1.79.0")] -impl fmt::Debug for Utf8Chunks<'_> { - fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result { - f.debug_struct("Utf8Chunks").field("source", &self.debug()).finish() - } -} diff --git a/library/core/src/str/mod.rs b/library/core/src/str/mod.rs deleted file mode 100644 index edda4d1b68703..0000000000000 --- a/library/core/src/str/mod.rs +++ /dev/null @@ -1,2779 +0,0 @@ -//! String manipulation. -//! -//! For more details, see the [`std::str`] module. -//! -//! [`std::str`]: ../../std/str/index.html - -#![stable(feature = "rust1", since = "1.0.0")] - -mod converts; -mod count; -mod error; -mod iter; -mod traits; -mod validations; - -use self::pattern::Pattern; -use self::pattern::{DoubleEndedSearcher, ReverseSearcher, Searcher}; - -use crate::ascii; -use crate::char::{self, EscapeDebugExtArgs}; -use crate::mem; -use crate::slice::{self, SliceIndex}; - -pub mod pattern; - -mod lossy; -#[stable(feature = "utf8_chunks", since = "1.79.0")] -pub use lossy::{Utf8Chunk, Utf8Chunks}; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use converts::{from_utf8, from_utf8_unchecked}; - -#[stable(feature = "str_mut_extras", since = "1.20.0")] -pub use converts::{from_utf8_mut, from_utf8_unchecked_mut}; - -#[unstable(feature = "str_from_raw_parts", issue = "119206")] -pub use converts::{from_raw_parts, from_raw_parts_mut}; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use error::{ParseBoolError, Utf8Error}; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use traits::FromStr; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use iter::{Bytes, CharIndices, Chars, Lines, SplitWhitespace}; - -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated)] -pub use iter::LinesAny; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use iter::{RSplit, RSplitTerminator, Split, SplitTerminator}; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use iter::{RSplitN, SplitN}; - -#[stable(feature = "str_matches", since = "1.2.0")] -pub use iter::{Matches, RMatches}; - -#[stable(feature = "str_match_indices", since = "1.5.0")] -pub use iter::{MatchIndices, RMatchIndices}; - -#[stable(feature = "encode_utf16", since = "1.8.0")] -pub use iter::EncodeUtf16; - -#[stable(feature = "str_escape", since = "1.34.0")] -pub use iter::{EscapeDebug, EscapeDefault, EscapeUnicode}; - -#[stable(feature = "split_ascii_whitespace", since = "1.34.0")] -pub use iter::SplitAsciiWhitespace; - -#[stable(feature = "split_inclusive", since = "1.51.0")] -pub use iter::SplitInclusive; - -#[unstable(feature = "str_internals", issue = "none")] -pub use validations::{next_code_point, utf8_char_width}; - -use iter::MatchIndicesInternal; -use iter::SplitInternal; -use iter::{MatchesInternal, SplitNInternal}; - -#[inline(never)] -#[cold] -#[track_caller] -#[rustc_allow_const_fn_unstable(const_eval_select)] -#[cfg(not(feature = "panic_immediate_abort"))] -const fn slice_error_fail(s: &str, begin: usize, end: usize) -> ! { - crate::intrinsics::const_eval_select((s, begin, end), slice_error_fail_ct, slice_error_fail_rt) -} - -#[cfg(feature = "panic_immediate_abort")] -const fn slice_error_fail(s: &str, begin: usize, end: usize) -> ! { - slice_error_fail_ct(s, begin, end) -} - -#[track_caller] -const fn slice_error_fail_ct(_: &str, _: usize, _: usize) -> ! { - panic!("failed to slice string"); -} - -#[track_caller] -fn slice_error_fail_rt(s: &str, begin: usize, end: usize) -> ! { - const MAX_DISPLAY_LENGTH: usize = 256; - let trunc_len = s.floor_char_boundary(MAX_DISPLAY_LENGTH); - let s_trunc = &s[..trunc_len]; - let ellipsis = if trunc_len < s.len() { "[...]" } else { "" }; - - // 1. out of bounds - if begin > s.len() || end > s.len() { - let oob_index = if begin > s.len() { begin } else { end }; - panic!("byte index {oob_index} is out of bounds of `{s_trunc}`{ellipsis}"); - } - - // 2. begin <= end - assert!( - begin <= end, - "begin <= end ({} <= {}) when slicing `{}`{}", - begin, - end, - s_trunc, - ellipsis - ); - - // 3. character boundary - let index = if !s.is_char_boundary(begin) { begin } else { end }; - // find the character - let char_start = s.floor_char_boundary(index); - // `char_start` must be less than len and a char boundary - let ch = s[char_start..].chars().next().unwrap(); - let char_range = char_start..char_start + ch.len_utf8(); - panic!( - "byte index {} is not a char boundary; it is inside {:?} (bytes {:?}) of `{}`{}", - index, ch, char_range, s_trunc, ellipsis - ); -} - -#[cfg(not(test))] -impl str { - /// Returns the length of `self`. - /// - /// This length is in bytes, not [`char`]s or graphemes. In other words, - /// it might not be what a human considers the length of the string. - /// - /// [`char`]: prim@char - /// - /// # Examples - /// - /// ``` - /// let len = "foo".len(); - /// assert_eq!(3, len); - /// - /// assert_eq!("ƒoo".len(), 4); // fancy f! - /// assert_eq!("ƒoo".chars().count(), 3); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_str_len", since = "1.39.0")] - #[must_use] - #[inline] - pub const fn len(&self) -> usize { - self.as_bytes().len() - } - - /// Returns `true` if `self` has a length of zero bytes. - /// - /// # Examples - /// - /// ``` - /// let s = ""; - /// assert!(s.is_empty()); - /// - /// let s = "not empty"; - /// assert!(!s.is_empty()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_str_is_empty", since = "1.39.0")] - #[must_use] - #[inline] - pub const fn is_empty(&self) -> bool { - self.len() == 0 - } - - /// Checks that `index`-th byte is the first byte in a UTF-8 code point - /// sequence or the end of the string. - /// - /// The start and end of the string (when `index == self.len()`) are - /// considered to be boundaries. - /// - /// Returns `false` if `index` is greater than `self.len()`. - /// - /// # Examples - /// - /// ``` - /// let s = "Löwe 老虎 Léopard"; - /// assert!(s.is_char_boundary(0)); - /// // start of `老` - /// assert!(s.is_char_boundary(6)); - /// assert!(s.is_char_boundary(s.len())); - /// - /// // second byte of `ö` - /// assert!(!s.is_char_boundary(2)); - /// - /// // third byte of `老` - /// assert!(!s.is_char_boundary(8)); - /// ``` - #[must_use] - #[stable(feature = "is_char_boundary", since = "1.9.0")] - #[inline] - pub fn is_char_boundary(&self, index: usize) -> bool { - // 0 is always ok. - // Test for 0 explicitly so that it can optimize out the check - // easily and skip reading string data for that case. - // Note that optimizing `self.get(..index)` relies on this. - if index == 0 { - return true; - } - - match self.as_bytes().get(index) { - // For `None` we have two options: - // - // - index == self.len() - // Empty strings are valid, so return true - // - index > self.len() - // In this case return false - // - // The check is placed exactly here, because it improves generated - // code on higher opt-levels. See PR #84751 for more details. - None => index == self.len(), - - Some(&b) => b.is_utf8_char_boundary(), - } - } - - /// Finds the closest `x` not exceeding `index` where `is_char_boundary(x)` is `true`. - /// - /// This method can help you truncate a string so that it's still valid UTF-8, but doesn't - /// exceed a given number of bytes. Note that this is done purely at the character level - /// and can still visually split graphemes, even though the underlying characters aren't - /// split. For example, the emoji 🧑‍🔬 (scientist) could be split so that the string only - /// includes 🧑 (person) instead. - /// - /// # Examples - /// - /// ``` - /// #![feature(round_char_boundary)] - /// let s = "❤️🧡💛💚💙💜"; - /// assert_eq!(s.len(), 26); - /// assert!(!s.is_char_boundary(13)); - /// - /// let closest = s.floor_char_boundary(13); - /// assert_eq!(closest, 10); - /// assert_eq!(&s[..closest], "❤️🧡"); - /// ``` - #[unstable(feature = "round_char_boundary", issue = "93743")] - #[inline] - pub fn floor_char_boundary(&self, index: usize) -> usize { - if index >= self.len() { - self.len() - } else { - let lower_bound = index.saturating_sub(3); - let new_index = self.as_bytes()[lower_bound..=index] - .iter() - .rposition(|b| b.is_utf8_char_boundary()); - - // SAFETY: we know that the character boundary will be within four bytes - unsafe { lower_bound + new_index.unwrap_unchecked() } - } - } - - /// Finds the closest `x` not below `index` where `is_char_boundary(x)` is `true`. - /// - /// If `index` is greater than the length of the string, this returns the length of the string. - /// - /// This method is the natural complement to [`floor_char_boundary`]. See that method - /// for more details. - /// - /// [`floor_char_boundary`]: str::floor_char_boundary - /// - /// - /// # Examples - /// - /// ``` - /// #![feature(round_char_boundary)] - /// let s = "❤️🧡💛💚💙💜"; - /// assert_eq!(s.len(), 26); - /// assert!(!s.is_char_boundary(13)); - /// - /// let closest = s.ceil_char_boundary(13); - /// assert_eq!(closest, 14); - /// assert_eq!(&s[..closest], "❤️🧡💛"); - /// ``` - #[unstable(feature = "round_char_boundary", issue = "93743")] - #[inline] - pub fn ceil_char_boundary(&self, index: usize) -> usize { - if index > self.len() { - self.len() - } else { - let upper_bound = Ord::min(index + 4, self.len()); - self.as_bytes()[index..upper_bound] - .iter() - .position(|b| b.is_utf8_char_boundary()) - .map_or(upper_bound, |pos| pos + index) - } - } - - /// Converts a string slice to a byte slice. To convert the byte slice back - /// into a string slice, use the [`from_utf8`] function. - /// - /// # Examples - /// - /// ``` - /// let bytes = "bors".as_bytes(); - /// assert_eq!(b"bors", bytes); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "str_as_bytes", since = "1.39.0")] - #[must_use] - #[inline(always)] - #[allow(unused_attributes)] - pub const fn as_bytes(&self) -> &[u8] { - // SAFETY: const sound because we transmute two types with the same layout - unsafe { mem::transmute(self) } - } - - /// Converts a mutable string slice to a mutable byte slice. - /// - /// # Safety - /// - /// The caller must ensure that the content of the slice is valid UTF-8 - /// before the borrow ends and the underlying `str` is used. - /// - /// Use of a `str` whose contents are not valid UTF-8 is undefined behavior. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let mut s = String::from("Hello"); - /// let bytes = unsafe { s.as_bytes_mut() }; - /// - /// assert_eq!(b"Hello", bytes); - /// ``` - /// - /// Mutability: - /// - /// ``` - /// let mut s = String::from("🗻∈🌏"); - /// - /// unsafe { - /// let bytes = s.as_bytes_mut(); - /// - /// bytes[0] = 0xF0; - /// bytes[1] = 0x9F; - /// bytes[2] = 0x8D; - /// bytes[3] = 0x94; - /// } - /// - /// assert_eq!("🍔∈🌏", s); - /// ``` - #[stable(feature = "str_mut_extras", since = "1.20.0")] - #[must_use] - #[inline(always)] - pub unsafe fn as_bytes_mut(&mut self) -> &mut [u8] { - // SAFETY: the cast from `&str` to `&[u8]` is safe since `str` - // has the same layout as `&[u8]` (only std can make this guarantee). - // The pointer dereference is safe since it comes from a mutable reference which - // is guaranteed to be valid for writes. - unsafe { &mut *(self as *mut str as *mut [u8]) } - } - - /// Converts a string slice to a raw pointer. - /// - /// As string slices are a slice of bytes, the raw pointer points to a - /// [`u8`]. This pointer will be pointing to the first byte of the string - /// slice. - /// - /// The caller must ensure that the returned pointer is never written to. - /// If you need to mutate the contents of the string slice, use [`as_mut_ptr`]. - /// - /// [`as_mut_ptr`]: str::as_mut_ptr - /// - /// # Examples - /// - /// ``` - /// let s = "Hello"; - /// let ptr = s.as_ptr(); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "rustc_str_as_ptr", since = "1.32.0")] - #[rustc_never_returns_null_ptr] - #[must_use] - #[inline(always)] - pub const fn as_ptr(&self) -> *const u8 { - self as *const str as *const u8 - } - - /// Converts a mutable string slice to a raw pointer. - /// - /// As string slices are a slice of bytes, the raw pointer points to a - /// [`u8`]. This pointer will be pointing to the first byte of the string - /// slice. - /// - /// It is your responsibility to make sure that the string slice only gets - /// modified in a way that it remains valid UTF-8. - #[stable(feature = "str_as_mut_ptr", since = "1.36.0")] - #[rustc_never_returns_null_ptr] - #[must_use] - #[inline(always)] - pub fn as_mut_ptr(&mut self) -> *mut u8 { - self as *mut str as *mut u8 - } - - /// Returns a subslice of `str`. - /// - /// This is the non-panicking alternative to indexing the `str`. Returns - /// [`None`] whenever equivalent indexing operation would panic. - /// - /// # Examples - /// - /// ``` - /// let v = String::from("🗻∈🌏"); - /// - /// assert_eq!(Some("🗻"), v.get(0..4)); - /// - /// // indices not on UTF-8 sequence boundaries - /// assert!(v.get(1..).is_none()); - /// assert!(v.get(..8).is_none()); - /// - /// // out of bounds - /// assert!(v.get(..42).is_none()); - /// ``` - #[stable(feature = "str_checked_slicing", since = "1.20.0")] - #[inline] - pub fn get>(&self, i: I) -> Option<&I::Output> { - i.get(self) - } - - /// Returns a mutable subslice of `str`. - /// - /// This is the non-panicking alternative to indexing the `str`. Returns - /// [`None`] whenever equivalent indexing operation would panic. - /// - /// # Examples - /// - /// ``` - /// let mut v = String::from("hello"); - /// // correct length - /// assert!(v.get_mut(0..5).is_some()); - /// // out of bounds - /// assert!(v.get_mut(..42).is_none()); - /// assert_eq!(Some("he"), v.get_mut(0..2).map(|v| &*v)); - /// - /// assert_eq!("hello", v); - /// { - /// let s = v.get_mut(0..2); - /// let s = s.map(|s| { - /// s.make_ascii_uppercase(); - /// &*s - /// }); - /// assert_eq!(Some("HE"), s); - /// } - /// assert_eq!("HEllo", v); - /// ``` - #[stable(feature = "str_checked_slicing", since = "1.20.0")] - #[inline] - pub fn get_mut>(&mut self, i: I) -> Option<&mut I::Output> { - i.get_mut(self) - } - - /// Returns an unchecked subslice of `str`. - /// - /// This is the unchecked alternative to indexing the `str`. - /// - /// # Safety - /// - /// Callers of this function are responsible that these preconditions are - /// satisfied: - /// - /// * The starting index must not exceed the ending index; - /// * Indexes must be within bounds of the original slice; - /// * Indexes must lie on UTF-8 sequence boundaries. - /// - /// Failing that, the returned string slice may reference invalid memory or - /// violate the invariants communicated by the `str` type. - /// - /// # Examples - /// - /// ``` - /// let v = "🗻∈🌏"; - /// unsafe { - /// assert_eq!("🗻", v.get_unchecked(0..4)); - /// assert_eq!("∈", v.get_unchecked(4..7)); - /// assert_eq!("🌏", v.get_unchecked(7..11)); - /// } - /// ``` - #[stable(feature = "str_checked_slicing", since = "1.20.0")] - #[inline] - pub unsafe fn get_unchecked>(&self, i: I) -> &I::Output { - // SAFETY: the caller must uphold the safety contract for `get_unchecked`; - // the slice is dereferenceable because `self` is a safe reference. - // The returned pointer is safe because impls of `SliceIndex` have to guarantee that it is. - unsafe { &*i.get_unchecked(self) } - } - - /// Returns a mutable, unchecked subslice of `str`. - /// - /// This is the unchecked alternative to indexing the `str`. - /// - /// # Safety - /// - /// Callers of this function are responsible that these preconditions are - /// satisfied: - /// - /// * The starting index must not exceed the ending index; - /// * Indexes must be within bounds of the original slice; - /// * Indexes must lie on UTF-8 sequence boundaries. - /// - /// Failing that, the returned string slice may reference invalid memory or - /// violate the invariants communicated by the `str` type. - /// - /// # Examples - /// - /// ``` - /// let mut v = String::from("🗻∈🌏"); - /// unsafe { - /// assert_eq!("🗻", v.get_unchecked_mut(0..4)); - /// assert_eq!("∈", v.get_unchecked_mut(4..7)); - /// assert_eq!("🌏", v.get_unchecked_mut(7..11)); - /// } - /// ``` - #[stable(feature = "str_checked_slicing", since = "1.20.0")] - #[inline] - pub unsafe fn get_unchecked_mut>(&mut self, i: I) -> &mut I::Output { - // SAFETY: the caller must uphold the safety contract for `get_unchecked_mut`; - // the slice is dereferenceable because `self` is a safe reference. - // The returned pointer is safe because impls of `SliceIndex` have to guarantee that it is. - unsafe { &mut *i.get_unchecked_mut(self) } - } - - /// Creates a string slice from another string slice, bypassing safety - /// checks. - /// - /// This is generally not recommended, use with caution! For a safe - /// alternative see [`str`] and [`Index`]. - /// - /// [`Index`]: crate::ops::Index - /// - /// This new slice goes from `begin` to `end`, including `begin` but - /// excluding `end`. - /// - /// To get a mutable string slice instead, see the - /// [`slice_mut_unchecked`] method. - /// - /// [`slice_mut_unchecked`]: str::slice_mut_unchecked - /// - /// # Safety - /// - /// Callers of this function are responsible that three preconditions are - /// satisfied: - /// - /// * `begin` must not exceed `end`. - /// * `begin` and `end` must be byte positions within the string slice. - /// * `begin` and `end` must lie on UTF-8 sequence boundaries. - /// - /// # Examples - /// - /// ``` - /// let s = "Löwe 老虎 Léopard"; - /// - /// unsafe { - /// assert_eq!("Löwe 老虎 Léopard", s.slice_unchecked(0, 21)); - /// } - /// - /// let s = "Hello, world!"; - /// - /// unsafe { - /// assert_eq!("world", s.slice_unchecked(7, 12)); - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[deprecated(since = "1.29.0", note = "use `get_unchecked(begin..end)` instead")] - #[must_use] - #[inline] - pub unsafe fn slice_unchecked(&self, begin: usize, end: usize) -> &str { - // SAFETY: the caller must uphold the safety contract for `get_unchecked`; - // the slice is dereferenceable because `self` is a safe reference. - // The returned pointer is safe because impls of `SliceIndex` have to guarantee that it is. - unsafe { &*(begin..end).get_unchecked(self) } - } - - /// Creates a string slice from another string slice, bypassing safety - /// checks. - /// This is generally not recommended, use with caution! For a safe - /// alternative see [`str`] and [`IndexMut`]. - /// - /// [`IndexMut`]: crate::ops::IndexMut - /// - /// This new slice goes from `begin` to `end`, including `begin` but - /// excluding `end`. - /// - /// To get an immutable string slice instead, see the - /// [`slice_unchecked`] method. - /// - /// [`slice_unchecked`]: str::slice_unchecked - /// - /// # Safety - /// - /// Callers of this function are responsible that three preconditions are - /// satisfied: - /// - /// * `begin` must not exceed `end`. - /// * `begin` and `end` must be byte positions within the string slice. - /// * `begin` and `end` must lie on UTF-8 sequence boundaries. - #[stable(feature = "str_slice_mut", since = "1.5.0")] - #[deprecated(since = "1.29.0", note = "use `get_unchecked_mut(begin..end)` instead")] - #[inline] - pub unsafe fn slice_mut_unchecked(&mut self, begin: usize, end: usize) -> &mut str { - // SAFETY: the caller must uphold the safety contract for `get_unchecked_mut`; - // the slice is dereferenceable because `self` is a safe reference. - // The returned pointer is safe because impls of `SliceIndex` have to guarantee that it is. - unsafe { &mut *(begin..end).get_unchecked_mut(self) } - } - - /// Divide one string slice into two at an index. - /// - /// The argument, `mid`, should be a byte offset from the start of the - /// string. It must also be on the boundary of a UTF-8 code point. - /// - /// The two slices returned go from the start of the string slice to `mid`, - /// and from `mid` to the end of the string slice. - /// - /// To get mutable string slices instead, see the [`split_at_mut`] - /// method. - /// - /// [`split_at_mut`]: str::split_at_mut - /// - /// # Panics - /// - /// Panics if `mid` is not on a UTF-8 code point boundary, or if it is past - /// the end of the last code point of the string slice. For a non-panicking - /// alternative see [`split_at_checked`](str::split_at_checked). - /// - /// # Examples - /// - /// ``` - /// let s = "Per Martin-Löf"; - /// - /// let (first, last) = s.split_at(3); - /// - /// assert_eq!("Per", first); - /// assert_eq!(" Martin-Löf", last); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "str_split_at", since = "1.4.0")] - pub fn split_at(&self, mid: usize) -> (&str, &str) { - match self.split_at_checked(mid) { - None => slice_error_fail(self, 0, mid), - Some(pair) => pair, - } - } - - /// Divide one mutable string slice into two at an index. - /// - /// The argument, `mid`, should be a byte offset from the start of the - /// string. It must also be on the boundary of a UTF-8 code point. - /// - /// The two slices returned go from the start of the string slice to `mid`, - /// and from `mid` to the end of the string slice. - /// - /// To get immutable string slices instead, see the [`split_at`] method. - /// - /// [`split_at`]: str::split_at - /// - /// # Panics - /// - /// Panics if `mid` is not on a UTF-8 code point boundary, or if it is past - /// the end of the last code point of the string slice. For a non-panicking - /// alternative see [`split_at_mut_checked`](str::split_at_mut_checked). - /// - /// # Examples - /// - /// ``` - /// let mut s = "Per Martin-Löf".to_string(); - /// { - /// let (first, last) = s.split_at_mut(3); - /// first.make_ascii_uppercase(); - /// assert_eq!("PER", first); - /// assert_eq!(" Martin-Löf", last); - /// } - /// assert_eq!("PER Martin-Löf", s); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "str_split_at", since = "1.4.0")] - pub fn split_at_mut(&mut self, mid: usize) -> (&mut str, &mut str) { - // is_char_boundary checks that the index is in [0, .len()] - if self.is_char_boundary(mid) { - // SAFETY: just checked that `mid` is on a char boundary. - unsafe { self.split_at_mut_unchecked(mid) } - } else { - slice_error_fail(self, 0, mid) - } - } - - /// Divide one string slice into two at an index. - /// - /// The argument, `mid`, should be a valid byte offset from the start of the - /// string. It must also be on the boundary of a UTF-8 code point. The - /// method returns `None` if that’s not the case. - /// - /// The two slices returned go from the start of the string slice to `mid`, - /// and from `mid` to the end of the string slice. - /// - /// To get mutable string slices instead, see the [`split_at_mut_checked`] - /// method. - /// - /// [`split_at_mut_checked`]: str::split_at_mut_checked - /// - /// # Examples - /// - /// ``` - /// let s = "Per Martin-Löf"; - /// - /// let (first, last) = s.split_at_checked(3).unwrap(); - /// assert_eq!("Per", first); - /// assert_eq!(" Martin-Löf", last); - /// - /// assert_eq!(None, s.split_at_checked(13)); // Inside “ö” - /// assert_eq!(None, s.split_at_checked(16)); // Beyond the string length - /// ``` - #[inline] - #[must_use] - #[stable(feature = "split_at_checked", since = "CURRENT_RUSTC_VERSION")] - pub fn split_at_checked(&self, mid: usize) -> Option<(&str, &str)> { - // is_char_boundary checks that the index is in [0, .len()] - if self.is_char_boundary(mid) { - // SAFETY: just checked that `mid` is on a char boundary. - Some(unsafe { (self.get_unchecked(0..mid), self.get_unchecked(mid..self.len())) }) - } else { - None - } - } - - /// Divide one mutable string slice into two at an index. - /// - /// The argument, `mid`, should be a valid byte offset from the start of the - /// string. It must also be on the boundary of a UTF-8 code point. The - /// method returns `None` if that’s not the case. - /// - /// The two slices returned go from the start of the string slice to `mid`, - /// and from `mid` to the end of the string slice. - /// - /// To get immutable string slices instead, see the [`split_at_checked`] method. - /// - /// [`split_at_checked`]: str::split_at_checked - /// - /// # Examples - /// - /// ``` - /// let mut s = "Per Martin-Löf".to_string(); - /// if let Some((first, last)) = s.split_at_mut_checked(3) { - /// first.make_ascii_uppercase(); - /// assert_eq!("PER", first); - /// assert_eq!(" Martin-Löf", last); - /// } - /// assert_eq!("PER Martin-Löf", s); - /// - /// assert_eq!(None, s.split_at_mut_checked(13)); // Inside “ö” - /// assert_eq!(None, s.split_at_mut_checked(16)); // Beyond the string length - /// ``` - #[inline] - #[must_use] - #[stable(feature = "split_at_checked", since = "CURRENT_RUSTC_VERSION")] - pub fn split_at_mut_checked(&mut self, mid: usize) -> Option<(&mut str, &mut str)> { - // is_char_boundary checks that the index is in [0, .len()] - if self.is_char_boundary(mid) { - // SAFETY: just checked that `mid` is on a char boundary. - Some(unsafe { self.split_at_mut_unchecked(mid) }) - } else { - None - } - } - - /// Divide one string slice into two at an index. - /// - /// # Safety - /// - /// The caller must ensure that `mid` is a valid byte offset from the start - /// of the string and falls on the boundary of a UTF-8 code point. - unsafe fn split_at_mut_unchecked(&mut self, mid: usize) -> (&mut str, &mut str) { - let len = self.len(); - let ptr = self.as_mut_ptr(); - // SAFETY: caller guarantees `mid` is on a char boundary. - unsafe { - ( - from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr, mid)), - from_utf8_unchecked_mut(slice::from_raw_parts_mut(ptr.add(mid), len - mid)), - ) - } - } - - /// Returns an iterator over the [`char`]s of a string slice. - /// - /// As a string slice consists of valid UTF-8, we can iterate through a - /// string slice by [`char`]. This method returns such an iterator. - /// - /// It's important to remember that [`char`] represents a Unicode Scalar - /// Value, and might not match your idea of what a 'character' is. Iteration - /// over grapheme clusters may be what you actually want. This functionality - /// is not provided by Rust's standard library, check crates.io instead. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let word = "goodbye"; - /// - /// let count = word.chars().count(); - /// assert_eq!(7, count); - /// - /// let mut chars = word.chars(); - /// - /// assert_eq!(Some('g'), chars.next()); - /// assert_eq!(Some('o'), chars.next()); - /// assert_eq!(Some('o'), chars.next()); - /// assert_eq!(Some('d'), chars.next()); - /// assert_eq!(Some('b'), chars.next()); - /// assert_eq!(Some('y'), chars.next()); - /// assert_eq!(Some('e'), chars.next()); - /// - /// assert_eq!(None, chars.next()); - /// ``` - /// - /// Remember, [`char`]s might not match your intuition about characters: - /// - /// [`char`]: prim@char - /// - /// ``` - /// let y = "y̆"; - /// - /// let mut chars = y.chars(); - /// - /// assert_eq!(Some('y'), chars.next()); // not 'y̆' - /// assert_eq!(Some('\u{0306}'), chars.next()); - /// - /// assert_eq!(None, chars.next()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn chars(&self) -> Chars<'_> { - Chars { iter: self.as_bytes().iter() } - } - - /// Returns an iterator over the [`char`]s of a string slice, and their - /// positions. - /// - /// As a string slice consists of valid UTF-8, we can iterate through a - /// string slice by [`char`]. This method returns an iterator of both - /// these [`char`]s, as well as their byte positions. - /// - /// The iterator yields tuples. The position is first, the [`char`] is - /// second. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let word = "goodbye"; - /// - /// let count = word.char_indices().count(); - /// assert_eq!(7, count); - /// - /// let mut char_indices = word.char_indices(); - /// - /// assert_eq!(Some((0, 'g')), char_indices.next()); - /// assert_eq!(Some((1, 'o')), char_indices.next()); - /// assert_eq!(Some((2, 'o')), char_indices.next()); - /// assert_eq!(Some((3, 'd')), char_indices.next()); - /// assert_eq!(Some((4, 'b')), char_indices.next()); - /// assert_eq!(Some((5, 'y')), char_indices.next()); - /// assert_eq!(Some((6, 'e')), char_indices.next()); - /// - /// assert_eq!(None, char_indices.next()); - /// ``` - /// - /// Remember, [`char`]s might not match your intuition about characters: - /// - /// [`char`]: prim@char - /// - /// ``` - /// let yes = "y̆es"; - /// - /// let mut char_indices = yes.char_indices(); - /// - /// assert_eq!(Some((0, 'y')), char_indices.next()); // not (0, 'y̆') - /// assert_eq!(Some((1, '\u{0306}')), char_indices.next()); - /// - /// // note the 3 here - the previous character took up two bytes - /// assert_eq!(Some((3, 'e')), char_indices.next()); - /// assert_eq!(Some((4, 's')), char_indices.next()); - /// - /// assert_eq!(None, char_indices.next()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn char_indices(&self) -> CharIndices<'_> { - CharIndices { front_offset: 0, iter: self.chars() } - } - - /// An iterator over the bytes of a string slice. - /// - /// As a string slice consists of a sequence of bytes, we can iterate - /// through a string slice by byte. This method returns such an iterator. - /// - /// # Examples - /// - /// ``` - /// let mut bytes = "bors".bytes(); - /// - /// assert_eq!(Some(b'b'), bytes.next()); - /// assert_eq!(Some(b'o'), bytes.next()); - /// assert_eq!(Some(b'r'), bytes.next()); - /// assert_eq!(Some(b's'), bytes.next()); - /// - /// assert_eq!(None, bytes.next()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn bytes(&self) -> Bytes<'_> { - Bytes(self.as_bytes().iter().copied()) - } - - /// Splits a string slice by whitespace. - /// - /// The iterator returned will return string slices that are sub-slices of - /// the original string slice, separated by any amount of whitespace. - /// - /// 'Whitespace' is defined according to the terms of the Unicode Derived - /// Core Property `White_Space`. If you only want to split on ASCII whitespace - /// instead, use [`split_ascii_whitespace`]. - /// - /// [`split_ascii_whitespace`]: str::split_ascii_whitespace - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let mut iter = "A few words".split_whitespace(); - /// - /// assert_eq!(Some("A"), iter.next()); - /// assert_eq!(Some("few"), iter.next()); - /// assert_eq!(Some("words"), iter.next()); - /// - /// assert_eq!(None, iter.next()); - /// ``` - /// - /// All kinds of whitespace are considered: - /// - /// ``` - /// let mut iter = " Mary had\ta\u{2009}little \n\t lamb".split_whitespace(); - /// assert_eq!(Some("Mary"), iter.next()); - /// assert_eq!(Some("had"), iter.next()); - /// assert_eq!(Some("a"), iter.next()); - /// assert_eq!(Some("little"), iter.next()); - /// assert_eq!(Some("lamb"), iter.next()); - /// - /// assert_eq!(None, iter.next()); - /// ``` - /// - /// If the string is empty or all whitespace, the iterator yields no string slices: - /// ``` - /// assert_eq!("".split_whitespace().next(), None); - /// assert_eq!(" ".split_whitespace().next(), None); - /// ``` - #[must_use = "this returns the split string as an iterator, \ - without modifying the original"] - #[stable(feature = "split_whitespace", since = "1.1.0")] - #[cfg_attr(not(test), rustc_diagnostic_item = "str_split_whitespace")] - #[inline] - pub fn split_whitespace(&self) -> SplitWhitespace<'_> { - SplitWhitespace { inner: self.split(char::is_whitespace).filter(|s| !s.is_empty()) } - } - - /// Splits a string slice by ASCII whitespace. - /// - /// The iterator returned will return string slices that are sub-slices of - /// the original string slice, separated by any amount of ASCII whitespace. - /// - /// To split by Unicode `Whitespace` instead, use [`split_whitespace`]. - /// - /// [`split_whitespace`]: str::split_whitespace - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let mut iter = "A few words".split_ascii_whitespace(); - /// - /// assert_eq!(Some("A"), iter.next()); - /// assert_eq!(Some("few"), iter.next()); - /// assert_eq!(Some("words"), iter.next()); - /// - /// assert_eq!(None, iter.next()); - /// ``` - /// - /// All kinds of ASCII whitespace are considered: - /// - /// ``` - /// let mut iter = " Mary had\ta little \n\t lamb".split_ascii_whitespace(); - /// assert_eq!(Some("Mary"), iter.next()); - /// assert_eq!(Some("had"), iter.next()); - /// assert_eq!(Some("a"), iter.next()); - /// assert_eq!(Some("little"), iter.next()); - /// assert_eq!(Some("lamb"), iter.next()); - /// - /// assert_eq!(None, iter.next()); - /// ``` - /// - /// If the string is empty or all ASCII whitespace, the iterator yields no string slices: - /// ``` - /// assert_eq!("".split_ascii_whitespace().next(), None); - /// assert_eq!(" ".split_ascii_whitespace().next(), None); - /// ``` - #[must_use = "this returns the split string as an iterator, \ - without modifying the original"] - #[stable(feature = "split_ascii_whitespace", since = "1.34.0")] - #[inline] - pub fn split_ascii_whitespace(&self) -> SplitAsciiWhitespace<'_> { - let inner = self - .as_bytes() - .split(u8::is_ascii_whitespace) - .filter(|s| !s.is_empty()) - // SAFETY: the byte slice came from a string and was only split - // along character boundaries, so the resulting slices are strings. - .map(|bytes| unsafe { from_utf8_unchecked(bytes) }); - SplitAsciiWhitespace { inner } - } - - /// An iterator over the lines of a string, as string slices. - /// - /// Lines are split at line endings that are either newlines (`\n`) or - /// sequences of a carriage return followed by a line feed (`\r\n`). - /// - /// Line terminators are not included in the lines returned by the iterator. - /// - /// Note that any carriage return (`\r`) not immediately followed by a - /// line feed (`\n`) does not split a line. These carriage returns are - /// thereby included in the produced lines. - /// - /// The final line ending is optional. A string that ends with a final line - /// ending will return the same lines as an otherwise identical string - /// without a final line ending. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let text = "foo\r\nbar\n\nbaz\r"; - /// let mut lines = text.lines(); - /// - /// assert_eq!(Some("foo"), lines.next()); - /// assert_eq!(Some("bar"), lines.next()); - /// assert_eq!(Some(""), lines.next()); - /// // Trailing carriage return is included in the last line - /// assert_eq!(Some("baz\r"), lines.next()); - /// - /// assert_eq!(None, lines.next()); - /// ``` - /// - /// The final line does not require any ending: - /// - /// ``` - /// let text = "foo\nbar\n\r\nbaz"; - /// let mut lines = text.lines(); - /// - /// assert_eq!(Some("foo"), lines.next()); - /// assert_eq!(Some("bar"), lines.next()); - /// assert_eq!(Some(""), lines.next()); - /// assert_eq!(Some("baz"), lines.next()); - /// - /// assert_eq!(None, lines.next()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn lines(&self) -> Lines<'_> { - Lines(self.split_inclusive('\n').map(|line| { - let Some(line) = line.strip_suffix('\n') else { return line }; - let Some(line) = line.strip_suffix('\r') else { return line }; - line - })) - } - - /// An iterator over the lines of a string. - #[stable(feature = "rust1", since = "1.0.0")] - #[deprecated(since = "1.4.0", note = "use lines() instead now", suggestion = "lines")] - #[inline] - #[allow(deprecated)] - pub fn lines_any(&self) -> LinesAny<'_> { - LinesAny(self.lines()) - } - - /// Returns an iterator of `u16` over the string encoded as UTF-16. - /// - /// # Examples - /// - /// ``` - /// let text = "Zażółć gęślą jaźń"; - /// - /// let utf8_len = text.len(); - /// let utf16_len = text.encode_utf16().count(); - /// - /// assert!(utf16_len <= utf8_len); - /// ``` - #[must_use = "this returns the encoded string as an iterator, \ - without modifying the original"] - #[stable(feature = "encode_utf16", since = "1.8.0")] - pub fn encode_utf16(&self) -> EncodeUtf16<'_> { - EncodeUtf16 { chars: self.chars(), extra: 0 } - } - - /// Returns `true` if the given pattern matches a sub-slice of - /// this string slice. - /// - /// Returns `false` if it does not. - /// - /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a - /// function or closure that determines if a character matches. - /// - /// [`char`]: prim@char - /// [pattern]: self::pattern - /// - /// # Examples - /// - /// ``` - /// let bananas = "bananas"; - /// - /// assert!(bananas.contains("nana")); - /// assert!(!bananas.contains("apples")); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn contains<'a, P: Pattern<'a>>(&'a self, pat: P) -> bool { - pat.is_contained_in(self) - } - - /// Returns `true` if the given pattern matches a prefix of this - /// string slice. - /// - /// Returns `false` if it does not. - /// - /// The [pattern] can be a `&str`, in which case this function will return true if - /// the `&str` is a prefix of this string slice. - /// - /// The [pattern] can also be a [`char`], a slice of [`char`]s, or a - /// function or closure that determines if a character matches. - /// These will only be checked against the first character of this string slice. - /// Look at the second example below regarding behavior for slices of [`char`]s. - /// - /// [`char`]: prim@char - /// [pattern]: self::pattern - /// - /// # Examples - /// - /// ``` - /// let bananas = "bananas"; - /// - /// assert!(bananas.starts_with("bana")); - /// assert!(!bananas.starts_with("nana")); - /// ``` - /// - /// ``` - /// let bananas = "bananas"; - /// - /// // Note that both of these assert successfully. - /// assert!(bananas.starts_with(&['b', 'a', 'n', 'a'])); - /// assert!(bananas.starts_with(&['a', 'b', 'c', 'd'])); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn starts_with<'a, P: Pattern<'a>>(&'a self, pat: P) -> bool { - pat.is_prefix_of(self) - } - - /// Returns `true` if the given pattern matches a suffix of this - /// string slice. - /// - /// Returns `false` if it does not. - /// - /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a - /// function or closure that determines if a character matches. - /// - /// [`char`]: prim@char - /// [pattern]: self::pattern - /// - /// # Examples - /// - /// ``` - /// let bananas = "bananas"; - /// - /// assert!(bananas.ends_with("anas")); - /// assert!(!bananas.ends_with("nana")); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn ends_with<'a, P>(&'a self, pat: P) -> bool - where - P: Pattern<'a, Searcher: ReverseSearcher<'a>>, - { - pat.is_suffix_of(self) - } - - /// Returns the byte index of the first character of this string slice that - /// matches the pattern. - /// - /// Returns [`None`] if the pattern doesn't match. - /// - /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a - /// function or closure that determines if a character matches. - /// - /// [`char`]: prim@char - /// [pattern]: self::pattern - /// - /// # Examples - /// - /// Simple patterns: - /// - /// ``` - /// let s = "Löwe 老虎 Léopard Gepardi"; - /// - /// assert_eq!(s.find('L'), Some(0)); - /// assert_eq!(s.find('é'), Some(14)); - /// assert_eq!(s.find("pard"), Some(17)); - /// ``` - /// - /// More complex patterns using point-free style and closures: - /// - /// ``` - /// let s = "Löwe 老虎 Léopard"; - /// - /// assert_eq!(s.find(char::is_whitespace), Some(5)); - /// assert_eq!(s.find(char::is_lowercase), Some(1)); - /// assert_eq!(s.find(|c: char| c.is_whitespace() || c.is_lowercase()), Some(1)); - /// assert_eq!(s.find(|c: char| (c < 'o') && (c > 'a')), Some(4)); - /// ``` - /// - /// Not finding the pattern: - /// - /// ``` - /// let s = "Löwe 老虎 Léopard"; - /// let x: &[_] = &['1', '2']; - /// - /// assert_eq!(s.find(x), None); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn find<'a, P: Pattern<'a>>(&'a self, pat: P) -> Option { - pat.into_searcher(self).next_match().map(|(i, _)| i) - } - - /// Returns the byte index for the first character of the last match of the pattern in - /// this string slice. - /// - /// Returns [`None`] if the pattern doesn't match. - /// - /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a - /// function or closure that determines if a character matches. - /// - /// [`char`]: prim@char - /// [pattern]: self::pattern - /// - /// # Examples - /// - /// Simple patterns: - /// - /// ``` - /// let s = "Löwe 老虎 Léopard Gepardi"; - /// - /// assert_eq!(s.rfind('L'), Some(13)); - /// assert_eq!(s.rfind('é'), Some(14)); - /// assert_eq!(s.rfind("pard"), Some(24)); - /// ``` - /// - /// More complex patterns with closures: - /// - /// ``` - /// let s = "Löwe 老虎 Léopard"; - /// - /// assert_eq!(s.rfind(char::is_whitespace), Some(12)); - /// assert_eq!(s.rfind(char::is_lowercase), Some(20)); - /// ``` - /// - /// Not finding the pattern: - /// - /// ``` - /// let s = "Löwe 老虎 Léopard"; - /// let x: &[_] = &['1', '2']; - /// - /// assert_eq!(s.rfind(x), None); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn rfind<'a, P>(&'a self, pat: P) -> Option - where - P: Pattern<'a, Searcher: ReverseSearcher<'a>>, - { - pat.into_searcher(self).next_match_back().map(|(i, _)| i) - } - - /// An iterator over substrings of this string slice, separated by - /// characters matched by a pattern. - /// - /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a - /// function or closure that determines if a character matches. - /// - /// [`char`]: prim@char - /// [pattern]: self::pattern - /// - /// # Iterator behavior - /// - /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern - /// allows a reverse search and forward/reverse search yields the same - /// elements. This is true for, e.g., [`char`], but not for `&str`. - /// - /// If the pattern allows a reverse search but its results might differ - /// from a forward search, the [`rsplit`] method can be used. - /// - /// [`rsplit`]: str::rsplit - /// - /// # Examples - /// - /// Simple patterns: - /// - /// ``` - /// let v: Vec<&str> = "Mary had a little lamb".split(' ').collect(); - /// assert_eq!(v, ["Mary", "had", "a", "little", "lamb"]); - /// - /// let v: Vec<&str> = "".split('X').collect(); - /// assert_eq!(v, [""]); - /// - /// let v: Vec<&str> = "lionXXtigerXleopard".split('X').collect(); - /// assert_eq!(v, ["lion", "", "tiger", "leopard"]); - /// - /// let v: Vec<&str> = "lion::tiger::leopard".split("::").collect(); - /// assert_eq!(v, ["lion", "tiger", "leopard"]); - /// - /// let v: Vec<&str> = "abc1def2ghi".split(char::is_numeric).collect(); - /// assert_eq!(v, ["abc", "def", "ghi"]); - /// - /// let v: Vec<&str> = "lionXtigerXleopard".split(char::is_uppercase).collect(); - /// assert_eq!(v, ["lion", "tiger", "leopard"]); - /// ``` - /// - /// If the pattern is a slice of chars, split on each occurrence of any of the characters: - /// - /// ``` - /// let v: Vec<&str> = "2020-11-03 23:59".split(&['-', ' ', ':', '@'][..]).collect(); - /// assert_eq!(v, ["2020", "11", "03", "23", "59"]); - /// ``` - /// - /// A more complex pattern, using a closure: - /// - /// ``` - /// let v: Vec<&str> = "abc1defXghi".split(|c| c == '1' || c == 'X').collect(); - /// assert_eq!(v, ["abc", "def", "ghi"]); - /// ``` - /// - /// If a string contains multiple contiguous separators, you will end up - /// with empty strings in the output: - /// - /// ``` - /// let x = "||||a||b|c".to_string(); - /// let d: Vec<_> = x.split('|').collect(); - /// - /// assert_eq!(d, &["", "", "", "", "a", "", "b", "c"]); - /// ``` - /// - /// Contiguous separators are separated by the empty string. - /// - /// ``` - /// let x = "(///)".to_string(); - /// let d: Vec<_> = x.split('/').collect(); - /// - /// assert_eq!(d, &["(", "", "", ")"]); - /// ``` - /// - /// Separators at the start or end of a string are neighbored - /// by empty strings. - /// - /// ``` - /// let d: Vec<_> = "010".split("0").collect(); - /// assert_eq!(d, &["", "1", ""]); - /// ``` - /// - /// When the empty string is used as a separator, it separates - /// every character in the string, along with the beginning - /// and end of the string. - /// - /// ``` - /// let f: Vec<_> = "rust".split("").collect(); - /// assert_eq!(f, &["", "r", "u", "s", "t", ""]); - /// ``` - /// - /// Contiguous separators can lead to possibly surprising behavior - /// when whitespace is used as the separator. This code is correct: - /// - /// ``` - /// let x = " a b c".to_string(); - /// let d: Vec<_> = x.split(' ').collect(); - /// - /// assert_eq!(d, &["", "", "", "", "a", "", "b", "c"]); - /// ``` - /// - /// It does _not_ give you: - /// - /// ```,ignore - /// assert_eq!(d, &["a", "b", "c"]); - /// ``` - /// - /// Use [`split_whitespace`] for this behavior. - /// - /// [`split_whitespace`]: str::split_whitespace - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn split<'a, P: Pattern<'a>>(&'a self, pat: P) -> Split<'a, P> { - Split(SplitInternal { - start: 0, - end: self.len(), - matcher: pat.into_searcher(self), - allow_trailing_empty: true, - finished: false, - }) - } - - /// An iterator over substrings of this string slice, separated by - /// characters matched by a pattern. Differs from the iterator produced by - /// `split` in that `split_inclusive` leaves the matched part as the - /// terminator of the substring. - /// - /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a - /// function or closure that determines if a character matches. - /// - /// [`char`]: prim@char - /// [pattern]: self::pattern - /// - /// # Examples - /// - /// ``` - /// let v: Vec<&str> = "Mary had a little lamb\nlittle lamb\nlittle lamb." - /// .split_inclusive('\n').collect(); - /// assert_eq!(v, ["Mary had a little lamb\n", "little lamb\n", "little lamb."]); - /// ``` - /// - /// If the last element of the string is matched, - /// that element will be considered the terminator of the preceding substring. - /// That substring will be the last item returned by the iterator. - /// - /// ``` - /// let v: Vec<&str> = "Mary had a little lamb\nlittle lamb\nlittle lamb.\n" - /// .split_inclusive('\n').collect(); - /// assert_eq!(v, ["Mary had a little lamb\n", "little lamb\n", "little lamb.\n"]); - /// ``` - #[stable(feature = "split_inclusive", since = "1.51.0")] - #[inline] - pub fn split_inclusive<'a, P: Pattern<'a>>(&'a self, pat: P) -> SplitInclusive<'a, P> { - SplitInclusive(SplitInternal { - start: 0, - end: self.len(), - matcher: pat.into_searcher(self), - allow_trailing_empty: false, - finished: false, - }) - } - - /// An iterator over substrings of the given string slice, separated by - /// characters matched by a pattern and yielded in reverse order. - /// - /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a - /// function or closure that determines if a character matches. - /// - /// [`char`]: prim@char - /// [pattern]: self::pattern - /// - /// # Iterator behavior - /// - /// The returned iterator requires that the pattern supports a reverse - /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse - /// search yields the same elements. - /// - /// For iterating from the front, the [`split`] method can be used. - /// - /// [`split`]: str::split - /// - /// # Examples - /// - /// Simple patterns: - /// - /// ``` - /// let v: Vec<&str> = "Mary had a little lamb".rsplit(' ').collect(); - /// assert_eq!(v, ["lamb", "little", "a", "had", "Mary"]); - /// - /// let v: Vec<&str> = "".rsplit('X').collect(); - /// assert_eq!(v, [""]); - /// - /// let v: Vec<&str> = "lionXXtigerXleopard".rsplit('X').collect(); - /// assert_eq!(v, ["leopard", "tiger", "", "lion"]); - /// - /// let v: Vec<&str> = "lion::tiger::leopard".rsplit("::").collect(); - /// assert_eq!(v, ["leopard", "tiger", "lion"]); - /// ``` - /// - /// A more complex pattern, using a closure: - /// - /// ``` - /// let v: Vec<&str> = "abc1defXghi".rsplit(|c| c == '1' || c == 'X').collect(); - /// assert_eq!(v, ["ghi", "def", "abc"]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn rsplit<'a, P>(&'a self, pat: P) -> RSplit<'a, P> - where - P: Pattern<'a, Searcher: ReverseSearcher<'a>>, - { - RSplit(self.split(pat).0) - } - - /// An iterator over substrings of the given string slice, separated by - /// characters matched by a pattern. - /// - /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a - /// function or closure that determines if a character matches. - /// - /// [`char`]: prim@char - /// [pattern]: self::pattern - /// - /// Equivalent to [`split`], except that the trailing substring - /// is skipped if empty. - /// - /// [`split`]: str::split - /// - /// This method can be used for string data that is _terminated_, - /// rather than _separated_ by a pattern. - /// - /// # Iterator behavior - /// - /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern - /// allows a reverse search and forward/reverse search yields the same - /// elements. This is true for, e.g., [`char`], but not for `&str`. - /// - /// If the pattern allows a reverse search but its results might differ - /// from a forward search, the [`rsplit_terminator`] method can be used. - /// - /// [`rsplit_terminator`]: str::rsplit_terminator - /// - /// # Examples - /// - /// ``` - /// let v: Vec<&str> = "A.B.".split_terminator('.').collect(); - /// assert_eq!(v, ["A", "B"]); - /// - /// let v: Vec<&str> = "A..B..".split_terminator(".").collect(); - /// assert_eq!(v, ["A", "", "B", ""]); - /// - /// let v: Vec<&str> = "A.B:C.D".split_terminator(&['.', ':'][..]).collect(); - /// assert_eq!(v, ["A", "B", "C", "D"]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn split_terminator<'a, P: Pattern<'a>>(&'a self, pat: P) -> SplitTerminator<'a, P> { - SplitTerminator(SplitInternal { allow_trailing_empty: false, ..self.split(pat).0 }) - } - - /// An iterator over substrings of `self`, separated by characters - /// matched by a pattern and yielded in reverse order. - /// - /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a - /// function or closure that determines if a character matches. - /// - /// [`char`]: prim@char - /// [pattern]: self::pattern - /// - /// Equivalent to [`split`], except that the trailing substring is - /// skipped if empty. - /// - /// [`split`]: str::split - /// - /// This method can be used for string data that is _terminated_, - /// rather than _separated_ by a pattern. - /// - /// # Iterator behavior - /// - /// The returned iterator requires that the pattern supports a - /// reverse search, and it will be double ended if a forward/reverse - /// search yields the same elements. - /// - /// For iterating from the front, the [`split_terminator`] method can be - /// used. - /// - /// [`split_terminator`]: str::split_terminator - /// - /// # Examples - /// - /// ``` - /// let v: Vec<&str> = "A.B.".rsplit_terminator('.').collect(); - /// assert_eq!(v, ["B", "A"]); - /// - /// let v: Vec<&str> = "A..B..".rsplit_terminator(".").collect(); - /// assert_eq!(v, ["", "B", "", "A"]); - /// - /// let v: Vec<&str> = "A.B:C.D".rsplit_terminator(&['.', ':'][..]).collect(); - /// assert_eq!(v, ["D", "C", "B", "A"]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn rsplit_terminator<'a, P>(&'a self, pat: P) -> RSplitTerminator<'a, P> - where - P: Pattern<'a, Searcher: ReverseSearcher<'a>>, - { - RSplitTerminator(self.split_terminator(pat).0) - } - - /// An iterator over substrings of the given string slice, separated by a - /// pattern, restricted to returning at most `n` items. - /// - /// If `n` substrings are returned, the last substring (the `n`th substring) - /// will contain the remainder of the string. - /// - /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a - /// function or closure that determines if a character matches. - /// - /// [`char`]: prim@char - /// [pattern]: self::pattern - /// - /// # Iterator behavior - /// - /// The returned iterator will not be double ended, because it is - /// not efficient to support. - /// - /// If the pattern allows a reverse search, the [`rsplitn`] method can be - /// used. - /// - /// [`rsplitn`]: str::rsplitn - /// - /// # Examples - /// - /// Simple patterns: - /// - /// ``` - /// let v: Vec<&str> = "Mary had a little lambda".splitn(3, ' ').collect(); - /// assert_eq!(v, ["Mary", "had", "a little lambda"]); - /// - /// let v: Vec<&str> = "lionXXtigerXleopard".splitn(3, "X").collect(); - /// assert_eq!(v, ["lion", "", "tigerXleopard"]); - /// - /// let v: Vec<&str> = "abcXdef".splitn(1, 'X').collect(); - /// assert_eq!(v, ["abcXdef"]); - /// - /// let v: Vec<&str> = "".splitn(1, 'X').collect(); - /// assert_eq!(v, [""]); - /// ``` - /// - /// A more complex pattern, using a closure: - /// - /// ``` - /// let v: Vec<&str> = "abc1defXghi".splitn(2, |c| c == '1' || c == 'X').collect(); - /// assert_eq!(v, ["abc", "defXghi"]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn splitn<'a, P: Pattern<'a>>(&'a self, n: usize, pat: P) -> SplitN<'a, P> { - SplitN(SplitNInternal { iter: self.split(pat).0, count: n }) - } - - /// An iterator over substrings of this string slice, separated by a - /// pattern, starting from the end of the string, restricted to returning - /// at most `n` items. - /// - /// If `n` substrings are returned, the last substring (the `n`th substring) - /// will contain the remainder of the string. - /// - /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a - /// function or closure that determines if a character matches. - /// - /// [`char`]: prim@char - /// [pattern]: self::pattern - /// - /// # Iterator behavior - /// - /// The returned iterator will not be double ended, because it is not - /// efficient to support. - /// - /// For splitting from the front, the [`splitn`] method can be used. - /// - /// [`splitn`]: str::splitn - /// - /// # Examples - /// - /// Simple patterns: - /// - /// ``` - /// let v: Vec<&str> = "Mary had a little lamb".rsplitn(3, ' ').collect(); - /// assert_eq!(v, ["lamb", "little", "Mary had a"]); - /// - /// let v: Vec<&str> = "lionXXtigerXleopard".rsplitn(3, 'X').collect(); - /// assert_eq!(v, ["leopard", "tiger", "lionX"]); - /// - /// let v: Vec<&str> = "lion::tiger::leopard".rsplitn(2, "::").collect(); - /// assert_eq!(v, ["leopard", "lion::tiger"]); - /// ``` - /// - /// A more complex pattern, using a closure: - /// - /// ``` - /// let v: Vec<&str> = "abc1defXghi".rsplitn(2, |c| c == '1' || c == 'X').collect(); - /// assert_eq!(v, ["ghi", "abc1def"]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn rsplitn<'a, P>(&'a self, n: usize, pat: P) -> RSplitN<'a, P> - where - P: Pattern<'a, Searcher: ReverseSearcher<'a>>, - { - RSplitN(self.splitn(n, pat).0) - } - - /// Splits the string on the first occurrence of the specified delimiter and - /// returns prefix before delimiter and suffix after delimiter. - /// - /// # Examples - /// - /// ``` - /// assert_eq!("cfg".split_once('='), None); - /// assert_eq!("cfg=".split_once('='), Some(("cfg", ""))); - /// assert_eq!("cfg=foo".split_once('='), Some(("cfg", "foo"))); - /// assert_eq!("cfg=foo=bar".split_once('='), Some(("cfg", "foo=bar"))); - /// ``` - #[stable(feature = "str_split_once", since = "1.52.0")] - #[inline] - pub fn split_once<'a, P: Pattern<'a>>(&'a self, delimiter: P) -> Option<(&'a str, &'a str)> { - let (start, end) = delimiter.into_searcher(self).next_match()?; - // SAFETY: `Searcher` is known to return valid indices. - unsafe { Some((self.get_unchecked(..start), self.get_unchecked(end..))) } - } - - /// Splits the string on the last occurrence of the specified delimiter and - /// returns prefix before delimiter and suffix after delimiter. - /// - /// # Examples - /// - /// ``` - /// assert_eq!("cfg".rsplit_once('='), None); - /// assert_eq!("cfg=foo".rsplit_once('='), Some(("cfg", "foo"))); - /// assert_eq!("cfg=foo=bar".rsplit_once('='), Some(("cfg=foo", "bar"))); - /// ``` - #[stable(feature = "str_split_once", since = "1.52.0")] - #[inline] - pub fn rsplit_once<'a, P>(&'a self, delimiter: P) -> Option<(&'a str, &'a str)> - where - P: Pattern<'a, Searcher: ReverseSearcher<'a>>, - { - let (start, end) = delimiter.into_searcher(self).next_match_back()?; - // SAFETY: `Searcher` is known to return valid indices. - unsafe { Some((self.get_unchecked(..start), self.get_unchecked(end..))) } - } - - /// An iterator over the disjoint matches of a pattern within the given string - /// slice. - /// - /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a - /// function or closure that determines if a character matches. - /// - /// [`char`]: prim@char - /// [pattern]: self::pattern - /// - /// # Iterator behavior - /// - /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern - /// allows a reverse search and forward/reverse search yields the same - /// elements. This is true for, e.g., [`char`], but not for `&str`. - /// - /// If the pattern allows a reverse search but its results might differ - /// from a forward search, the [`rmatches`] method can be used. - /// - /// [`rmatches`]: str::rmatches - /// - /// # Examples - /// - /// ``` - /// let v: Vec<&str> = "abcXXXabcYYYabc".matches("abc").collect(); - /// assert_eq!(v, ["abc", "abc", "abc"]); - /// - /// let v: Vec<&str> = "1abc2abc3".matches(char::is_numeric).collect(); - /// assert_eq!(v, ["1", "2", "3"]); - /// ``` - #[stable(feature = "str_matches", since = "1.2.0")] - #[inline] - pub fn matches<'a, P: Pattern<'a>>(&'a self, pat: P) -> Matches<'a, P> { - Matches(MatchesInternal(pat.into_searcher(self))) - } - - /// An iterator over the disjoint matches of a pattern within this string slice, - /// yielded in reverse order. - /// - /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a - /// function or closure that determines if a character matches. - /// - /// [`char`]: prim@char - /// [pattern]: self::pattern - /// - /// # Iterator behavior - /// - /// The returned iterator requires that the pattern supports a reverse - /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse - /// search yields the same elements. - /// - /// For iterating from the front, the [`matches`] method can be used. - /// - /// [`matches`]: str::matches - /// - /// # Examples - /// - /// ``` - /// let v: Vec<&str> = "abcXXXabcYYYabc".rmatches("abc").collect(); - /// assert_eq!(v, ["abc", "abc", "abc"]); - /// - /// let v: Vec<&str> = "1abc2abc3".rmatches(char::is_numeric).collect(); - /// assert_eq!(v, ["3", "2", "1"]); - /// ``` - #[stable(feature = "str_matches", since = "1.2.0")] - #[inline] - pub fn rmatches<'a, P>(&'a self, pat: P) -> RMatches<'a, P> - where - P: Pattern<'a, Searcher: ReverseSearcher<'a>>, - { - RMatches(self.matches(pat).0) - } - - /// An iterator over the disjoint matches of a pattern within this string - /// slice as well as the index that the match starts at. - /// - /// For matches of `pat` within `self` that overlap, only the indices - /// corresponding to the first match are returned. - /// - /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a - /// function or closure that determines if a character matches. - /// - /// [`char`]: prim@char - /// [pattern]: self::pattern - /// - /// # Iterator behavior - /// - /// The returned iterator will be a [`DoubleEndedIterator`] if the pattern - /// allows a reverse search and forward/reverse search yields the same - /// elements. This is true for, e.g., [`char`], but not for `&str`. - /// - /// If the pattern allows a reverse search but its results might differ - /// from a forward search, the [`rmatch_indices`] method can be used. - /// - /// [`rmatch_indices`]: str::rmatch_indices - /// - /// # Examples - /// - /// ``` - /// let v: Vec<_> = "abcXXXabcYYYabc".match_indices("abc").collect(); - /// assert_eq!(v, [(0, "abc"), (6, "abc"), (12, "abc")]); - /// - /// let v: Vec<_> = "1abcabc2".match_indices("abc").collect(); - /// assert_eq!(v, [(1, "abc"), (4, "abc")]); - /// - /// let v: Vec<_> = "ababa".match_indices("aba").collect(); - /// assert_eq!(v, [(0, "aba")]); // only the first `aba` - /// ``` - #[stable(feature = "str_match_indices", since = "1.5.0")] - #[inline] - pub fn match_indices<'a, P: Pattern<'a>>(&'a self, pat: P) -> MatchIndices<'a, P> { - MatchIndices(MatchIndicesInternal(pat.into_searcher(self))) - } - - /// An iterator over the disjoint matches of a pattern within `self`, - /// yielded in reverse order along with the index of the match. - /// - /// For matches of `pat` within `self` that overlap, only the indices - /// corresponding to the last match are returned. - /// - /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a - /// function or closure that determines if a character matches. - /// - /// [`char`]: prim@char - /// [pattern]: self::pattern - /// - /// # Iterator behavior - /// - /// The returned iterator requires that the pattern supports a reverse - /// search, and it will be a [`DoubleEndedIterator`] if a forward/reverse - /// search yields the same elements. - /// - /// For iterating from the front, the [`match_indices`] method can be used. - /// - /// [`match_indices`]: str::match_indices - /// - /// # Examples - /// - /// ``` - /// let v: Vec<_> = "abcXXXabcYYYabc".rmatch_indices("abc").collect(); - /// assert_eq!(v, [(12, "abc"), (6, "abc"), (0, "abc")]); - /// - /// let v: Vec<_> = "1abcabc2".rmatch_indices("abc").collect(); - /// assert_eq!(v, [(4, "abc"), (1, "abc")]); - /// - /// let v: Vec<_> = "ababa".rmatch_indices("aba").collect(); - /// assert_eq!(v, [(2, "aba")]); // only the last `aba` - /// ``` - #[stable(feature = "str_match_indices", since = "1.5.0")] - #[inline] - pub fn rmatch_indices<'a, P>(&'a self, pat: P) -> RMatchIndices<'a, P> - where - P: Pattern<'a, Searcher: ReverseSearcher<'a>>, - { - RMatchIndices(self.match_indices(pat).0) - } - - /// Returns a string slice with leading and trailing whitespace removed. - /// - /// 'Whitespace' is defined according to the terms of the Unicode Derived - /// Core Property `White_Space`, which includes newlines. - /// - /// # Examples - /// - /// ``` - /// let s = "\n Hello\tworld\t\n"; - /// - /// assert_eq!("Hello\tworld", s.trim()); - /// ``` - #[inline] - #[must_use = "this returns the trimmed string as a slice, \ - without modifying the original"] - #[stable(feature = "rust1", since = "1.0.0")] - #[cfg_attr(not(test), rustc_diagnostic_item = "str_trim")] - pub fn trim(&self) -> &str { - self.trim_matches(|c: char| c.is_whitespace()) - } - - /// Returns a string slice with leading whitespace removed. - /// - /// 'Whitespace' is defined according to the terms of the Unicode Derived - /// Core Property `White_Space`, which includes newlines. - /// - /// # Text directionality - /// - /// A string is a sequence of bytes. `start` in this context means the first - /// position of that byte string; for a left-to-right language like English or - /// Russian, this will be left side, and for right-to-left languages like - /// Arabic or Hebrew, this will be the right side. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let s = "\n Hello\tworld\t\n"; - /// assert_eq!("Hello\tworld\t\n", s.trim_start()); - /// ``` - /// - /// Directionality: - /// - /// ``` - /// let s = " English "; - /// assert!(Some('E') == s.trim_start().chars().next()); - /// - /// let s = " עברית "; - /// assert!(Some('ע') == s.trim_start().chars().next()); - /// ``` - #[inline] - #[must_use = "this returns the trimmed string as a new slice, \ - without modifying the original"] - #[stable(feature = "trim_direction", since = "1.30.0")] - #[cfg_attr(not(test), rustc_diagnostic_item = "str_trim_start")] - pub fn trim_start(&self) -> &str { - self.trim_start_matches(|c: char| c.is_whitespace()) - } - - /// Returns a string slice with trailing whitespace removed. - /// - /// 'Whitespace' is defined according to the terms of the Unicode Derived - /// Core Property `White_Space`, which includes newlines. - /// - /// # Text directionality - /// - /// A string is a sequence of bytes. `end` in this context means the last - /// position of that byte string; for a left-to-right language like English or - /// Russian, this will be right side, and for right-to-left languages like - /// Arabic or Hebrew, this will be the left side. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let s = "\n Hello\tworld\t\n"; - /// assert_eq!("\n Hello\tworld", s.trim_end()); - /// ``` - /// - /// Directionality: - /// - /// ``` - /// let s = " English "; - /// assert!(Some('h') == s.trim_end().chars().rev().next()); - /// - /// let s = " עברית "; - /// assert!(Some('ת') == s.trim_end().chars().rev().next()); - /// ``` - #[inline] - #[must_use = "this returns the trimmed string as a new slice, \ - without modifying the original"] - #[stable(feature = "trim_direction", since = "1.30.0")] - #[cfg_attr(not(test), rustc_diagnostic_item = "str_trim_end")] - pub fn trim_end(&self) -> &str { - self.trim_end_matches(|c: char| c.is_whitespace()) - } - - /// Returns a string slice with leading whitespace removed. - /// - /// 'Whitespace' is defined according to the terms of the Unicode Derived - /// Core Property `White_Space`. - /// - /// # Text directionality - /// - /// A string is a sequence of bytes. 'Left' in this context means the first - /// position of that byte string; for a language like Arabic or Hebrew - /// which are 'right to left' rather than 'left to right', this will be - /// the _right_ side, not the left. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let s = " Hello\tworld\t"; - /// - /// assert_eq!("Hello\tworld\t", s.trim_left()); - /// ``` - /// - /// Directionality: - /// - /// ``` - /// let s = " English"; - /// assert!(Some('E') == s.trim_left().chars().next()); - /// - /// let s = " עברית"; - /// assert!(Some('ע') == s.trim_left().chars().next()); - /// ``` - #[must_use = "this returns the trimmed string as a new slice, \ - without modifying the original"] - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[deprecated(since = "1.33.0", note = "superseded by `trim_start`", suggestion = "trim_start")] - pub fn trim_left(&self) -> &str { - self.trim_start() - } - - /// Returns a string slice with trailing whitespace removed. - /// - /// 'Whitespace' is defined according to the terms of the Unicode Derived - /// Core Property `White_Space`. - /// - /// # Text directionality - /// - /// A string is a sequence of bytes. 'Right' in this context means the last - /// position of that byte string; for a language like Arabic or Hebrew - /// which are 'right to left' rather than 'left to right', this will be - /// the _left_ side, not the right. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let s = " Hello\tworld\t"; - /// - /// assert_eq!(" Hello\tworld", s.trim_right()); - /// ``` - /// - /// Directionality: - /// - /// ``` - /// let s = "English "; - /// assert!(Some('h') == s.trim_right().chars().rev().next()); - /// - /// let s = "עברית "; - /// assert!(Some('ת') == s.trim_right().chars().rev().next()); - /// ``` - #[must_use = "this returns the trimmed string as a new slice, \ - without modifying the original"] - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[deprecated(since = "1.33.0", note = "superseded by `trim_end`", suggestion = "trim_end")] - pub fn trim_right(&self) -> &str { - self.trim_end() - } - - /// Returns a string slice with all prefixes and suffixes that match a - /// pattern repeatedly removed. - /// - /// The [pattern] can be a [`char`], a slice of [`char`]s, or a function - /// or closure that determines if a character matches. - /// - /// [`char`]: prim@char - /// [pattern]: self::pattern - /// - /// # Examples - /// - /// Simple patterns: - /// - /// ``` - /// assert_eq!("11foo1bar11".trim_matches('1'), "foo1bar"); - /// assert_eq!("123foo1bar123".trim_matches(char::is_numeric), "foo1bar"); - /// - /// let x: &[_] = &['1', '2']; - /// assert_eq!("12foo1bar12".trim_matches(x), "foo1bar"); - /// ``` - /// - /// A more complex pattern, using a closure: - /// - /// ``` - /// assert_eq!("1foo1barXX".trim_matches(|c| c == '1' || c == 'X'), "foo1bar"); - /// ``` - #[must_use = "this returns the trimmed string as a new slice, \ - without modifying the original"] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn trim_matches<'a, P>(&'a self, pat: P) -> &'a str - where - P: Pattern<'a, Searcher: DoubleEndedSearcher<'a>>, - { - let mut i = 0; - let mut j = 0; - let mut matcher = pat.into_searcher(self); - if let Some((a, b)) = matcher.next_reject() { - i = a; - j = b; // Remember earliest known match, correct it below if - // last match is different - } - if let Some((_, b)) = matcher.next_reject_back() { - j = b; - } - // SAFETY: `Searcher` is known to return valid indices. - unsafe { self.get_unchecked(i..j) } - } - - /// Returns a string slice with all prefixes that match a pattern - /// repeatedly removed. - /// - /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a - /// function or closure that determines if a character matches. - /// - /// [`char`]: prim@char - /// [pattern]: self::pattern - /// - /// # Text directionality - /// - /// A string is a sequence of bytes. `start` in this context means the first - /// position of that byte string; for a left-to-right language like English or - /// Russian, this will be left side, and for right-to-left languages like - /// Arabic or Hebrew, this will be the right side. - /// - /// # Examples - /// - /// ``` - /// assert_eq!("11foo1bar11".trim_start_matches('1'), "foo1bar11"); - /// assert_eq!("123foo1bar123".trim_start_matches(char::is_numeric), "foo1bar123"); - /// - /// let x: &[_] = &['1', '2']; - /// assert_eq!("12foo1bar12".trim_start_matches(x), "foo1bar12"); - /// ``` - #[must_use = "this returns the trimmed string as a new slice, \ - without modifying the original"] - #[stable(feature = "trim_direction", since = "1.30.0")] - pub fn trim_start_matches<'a, P: Pattern<'a>>(&'a self, pat: P) -> &'a str { - let mut i = self.len(); - let mut matcher = pat.into_searcher(self); - if let Some((a, _)) = matcher.next_reject() { - i = a; - } - // SAFETY: `Searcher` is known to return valid indices. - unsafe { self.get_unchecked(i..self.len()) } - } - - /// Returns a string slice with the prefix removed. - /// - /// If the string starts with the pattern `prefix`, returns the substring after the prefix, - /// wrapped in `Some`. Unlike `trim_start_matches`, this method removes the prefix exactly once. - /// - /// If the string does not start with `prefix`, returns `None`. - /// - /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a - /// function or closure that determines if a character matches. - /// - /// [`char`]: prim@char - /// [pattern]: self::pattern - /// - /// # Examples - /// - /// ``` - /// assert_eq!("foo:bar".strip_prefix("foo:"), Some("bar")); - /// assert_eq!("foo:bar".strip_prefix("bar"), None); - /// assert_eq!("foofoo".strip_prefix("foo"), Some("foo")); - /// ``` - #[must_use = "this returns the remaining substring as a new slice, \ - without modifying the original"] - #[stable(feature = "str_strip", since = "1.45.0")] - pub fn strip_prefix<'a, P: Pattern<'a>>(&'a self, prefix: P) -> Option<&'a str> { - prefix.strip_prefix_of(self) - } - - /// Returns a string slice with the suffix removed. - /// - /// If the string ends with the pattern `suffix`, returns the substring before the suffix, - /// wrapped in `Some`. Unlike `trim_end_matches`, this method removes the suffix exactly once. - /// - /// If the string does not end with `suffix`, returns `None`. - /// - /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a - /// function or closure that determines if a character matches. - /// - /// [`char`]: prim@char - /// [pattern]: self::pattern - /// - /// # Examples - /// - /// ``` - /// assert_eq!("bar:foo".strip_suffix(":foo"), Some("bar")); - /// assert_eq!("bar:foo".strip_suffix("bar"), None); - /// assert_eq!("foofoo".strip_suffix("foo"), Some("foo")); - /// ``` - #[must_use = "this returns the remaining substring as a new slice, \ - without modifying the original"] - #[stable(feature = "str_strip", since = "1.45.0")] - pub fn strip_suffix<'a, P>(&'a self, suffix: P) -> Option<&'a str> - where - P: Pattern<'a>, -

>::Searcher: ReverseSearcher<'a>, - { - suffix.strip_suffix_of(self) - } - - /// Returns a string slice with all suffixes that match a pattern - /// repeatedly removed. - /// - /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a - /// function or closure that determines if a character matches. - /// - /// [`char`]: prim@char - /// [pattern]: self::pattern - /// - /// # Text directionality - /// - /// A string is a sequence of bytes. `end` in this context means the last - /// position of that byte string; for a left-to-right language like English or - /// Russian, this will be right side, and for right-to-left languages like - /// Arabic or Hebrew, this will be the left side. - /// - /// # Examples - /// - /// Simple patterns: - /// - /// ``` - /// assert_eq!("11foo1bar11".trim_end_matches('1'), "11foo1bar"); - /// assert_eq!("123foo1bar123".trim_end_matches(char::is_numeric), "123foo1bar"); - /// - /// let x: &[_] = &['1', '2']; - /// assert_eq!("12foo1bar12".trim_end_matches(x), "12foo1bar"); - /// ``` - /// - /// A more complex pattern, using a closure: - /// - /// ``` - /// assert_eq!("1fooX".trim_end_matches(|c| c == '1' || c == 'X'), "1foo"); - /// ``` - #[must_use = "this returns the trimmed string as a new slice, \ - without modifying the original"] - #[stable(feature = "trim_direction", since = "1.30.0")] - pub fn trim_end_matches<'a, P>(&'a self, pat: P) -> &'a str - where - P: Pattern<'a, Searcher: ReverseSearcher<'a>>, - { - let mut j = 0; - let mut matcher = pat.into_searcher(self); - if let Some((_, b)) = matcher.next_reject_back() { - j = b; - } - // SAFETY: `Searcher` is known to return valid indices. - unsafe { self.get_unchecked(0..j) } - } - - /// Returns a string slice with all prefixes that match a pattern - /// repeatedly removed. - /// - /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a - /// function or closure that determines if a character matches. - /// - /// [`char`]: prim@char - /// [pattern]: self::pattern - /// - /// # Text directionality - /// - /// A string is a sequence of bytes. 'Left' in this context means the first - /// position of that byte string; for a language like Arabic or Hebrew - /// which are 'right to left' rather than 'left to right', this will be - /// the _right_ side, not the left. - /// - /// # Examples - /// - /// ``` - /// assert_eq!("11foo1bar11".trim_left_matches('1'), "foo1bar11"); - /// assert_eq!("123foo1bar123".trim_left_matches(char::is_numeric), "foo1bar123"); - /// - /// let x: &[_] = &['1', '2']; - /// assert_eq!("12foo1bar12".trim_left_matches(x), "foo1bar12"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[deprecated( - since = "1.33.0", - note = "superseded by `trim_start_matches`", - suggestion = "trim_start_matches" - )] - pub fn trim_left_matches<'a, P: Pattern<'a>>(&'a self, pat: P) -> &'a str { - self.trim_start_matches(pat) - } - - /// Returns a string slice with all suffixes that match a pattern - /// repeatedly removed. - /// - /// The [pattern] can be a `&str`, [`char`], a slice of [`char`]s, or a - /// function or closure that determines if a character matches. - /// - /// [`char`]: prim@char - /// [pattern]: self::pattern - /// - /// # Text directionality - /// - /// A string is a sequence of bytes. 'Right' in this context means the last - /// position of that byte string; for a language like Arabic or Hebrew - /// which are 'right to left' rather than 'left to right', this will be - /// the _left_ side, not the right. - /// - /// # Examples - /// - /// Simple patterns: - /// - /// ``` - /// assert_eq!("11foo1bar11".trim_right_matches('1'), "11foo1bar"); - /// assert_eq!("123foo1bar123".trim_right_matches(char::is_numeric), "123foo1bar"); - /// - /// let x: &[_] = &['1', '2']; - /// assert_eq!("12foo1bar12".trim_right_matches(x), "12foo1bar"); - /// ``` - /// - /// A more complex pattern, using a closure: - /// - /// ``` - /// assert_eq!("1fooX".trim_right_matches(|c| c == '1' || c == 'X'), "1foo"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[deprecated( - since = "1.33.0", - note = "superseded by `trim_end_matches`", - suggestion = "trim_end_matches" - )] - pub fn trim_right_matches<'a, P>(&'a self, pat: P) -> &'a str - where - P: Pattern<'a, Searcher: ReverseSearcher<'a>>, - { - self.trim_end_matches(pat) - } - - /// Parses this string slice into another type. - /// - /// Because `parse` is so general, it can cause problems with type - /// inference. As such, `parse` is one of the few times you'll see - /// the syntax affectionately known as the 'turbofish': `::<>`. This - /// helps the inference algorithm understand specifically which type - /// you're trying to parse into. - /// - /// `parse` can parse into any type that implements the [`FromStr`] trait. - - /// - /// # Errors - /// - /// Will return [`Err`] if it's not possible to parse this string slice into - /// the desired type. - /// - /// [`Err`]: FromStr::Err - /// - /// # Examples - /// - /// Basic usage - /// - /// ``` - /// let four: u32 = "4".parse().unwrap(); - /// - /// assert_eq!(4, four); - /// ``` - /// - /// Using the 'turbofish' instead of annotating `four`: - /// - /// ``` - /// let four = "4".parse::(); - /// - /// assert_eq!(Ok(4), four); - /// ``` - /// - /// Failing to parse: - /// - /// ``` - /// let nope = "j".parse::(); - /// - /// assert!(nope.is_err()); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn parse(&self) -> Result { - FromStr::from_str(self) - } - - /// Checks if all characters in this string are within the ASCII range. - /// - /// # Examples - /// - /// ``` - /// let ascii = "hello!\n"; - /// let non_ascii = "Grüße, Jürgen ❤"; - /// - /// assert!(ascii.is_ascii()); - /// assert!(!non_ascii.is_ascii()); - /// ``` - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[rustc_const_stable(feature = "const_slice_is_ascii", since = "1.74.0")] - #[must_use] - #[inline] - pub const fn is_ascii(&self) -> bool { - // We can treat each byte as character here: all multibyte characters - // start with a byte that is not in the ASCII range, so we will stop - // there already. - self.as_bytes().is_ascii() - } - - /// If this string slice [`is_ascii`](Self::is_ascii), returns it as a slice - /// of [ASCII characters](`ascii::Char`), otherwise returns `None`. - #[unstable(feature = "ascii_char", issue = "110998")] - #[must_use] - #[inline] - pub const fn as_ascii(&self) -> Option<&[ascii::Char]> { - // Like in `is_ascii`, we can work on the bytes directly. - self.as_bytes().as_ascii() - } - - /// Checks that two strings are an ASCII case-insensitive match. - /// - /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`, - /// but without allocating and copying temporaries. - /// - /// # Examples - /// - /// ``` - /// assert!("Ferris".eq_ignore_ascii_case("FERRIS")); - /// assert!("Ferrös".eq_ignore_ascii_case("FERRöS")); - /// assert!(!"Ferrös".eq_ignore_ascii_case("FERRÖS")); - /// ``` - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[must_use] - #[inline] - pub fn eq_ignore_ascii_case(&self, other: &str) -> bool { - self.as_bytes().eq_ignore_ascii_case(other.as_bytes()) - } - - /// Converts this string to its ASCII upper case equivalent in-place. - /// - /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', - /// but non-ASCII letters are unchanged. - /// - /// To return a new uppercased value without modifying the existing one, use - /// [`to_ascii_uppercase()`]. - /// - /// [`to_ascii_uppercase()`]: #method.to_ascii_uppercase - /// - /// # Examples - /// - /// ``` - /// let mut s = String::from("Grüße, Jürgen ❤"); - /// - /// s.make_ascii_uppercase(); - /// - /// assert_eq!("GRüßE, JüRGEN ❤", s); - /// ``` - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[inline] - pub fn make_ascii_uppercase(&mut self) { - // SAFETY: changing ASCII letters only does not invalidate UTF-8. - let me = unsafe { self.as_bytes_mut() }; - me.make_ascii_uppercase() - } - - /// Converts this string to its ASCII lower case equivalent in-place. - /// - /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', - /// but non-ASCII letters are unchanged. - /// - /// To return a new lowercased value without modifying the existing one, use - /// [`to_ascii_lowercase()`]. - /// - /// [`to_ascii_lowercase()`]: #method.to_ascii_lowercase - /// - /// # Examples - /// - /// ``` - /// let mut s = String::from("GRÜßE, JÜRGEN ❤"); - /// - /// s.make_ascii_lowercase(); - /// - /// assert_eq!("grÜße, jÜrgen ❤", s); - /// ``` - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[inline] - pub fn make_ascii_lowercase(&mut self) { - // SAFETY: changing ASCII letters only does not invalidate UTF-8. - let me = unsafe { self.as_bytes_mut() }; - me.make_ascii_lowercase() - } - - /// Returns a string slice with leading ASCII whitespace removed. - /// - /// 'Whitespace' refers to the definition used by - /// [`u8::is_ascii_whitespace`]. - /// - /// [`u8::is_ascii_whitespace`]: u8::is_ascii_whitespace - /// - /// # Examples - /// - /// ``` - /// assert_eq!(" \t \u{3000}hello world\n".trim_ascii_start(), "\u{3000}hello world\n"); - /// assert_eq!(" ".trim_ascii_start(), ""); - /// assert_eq!("".trim_ascii_start(), ""); - /// ``` - #[must_use = "this returns the trimmed string as a new slice, \ - without modifying the original"] - #[stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] - #[inline] - pub const fn trim_ascii_start(&self) -> &str { - // SAFETY: Removing ASCII characters from a `&str` does not invalidate - // UTF-8. - unsafe { core::str::from_utf8_unchecked(self.as_bytes().trim_ascii_start()) } - } - - /// Returns a string slice with trailing ASCII whitespace removed. - /// - /// 'Whitespace' refers to the definition used by - /// [`u8::is_ascii_whitespace`]. - /// - /// [`u8::is_ascii_whitespace`]: u8::is_ascii_whitespace - /// - /// # Examples - /// - /// ``` - /// assert_eq!("\r hello world\u{3000}\n ".trim_ascii_end(), "\r hello world\u{3000}"); - /// assert_eq!(" ".trim_ascii_end(), ""); - /// assert_eq!("".trim_ascii_end(), ""); - /// ``` - #[must_use = "this returns the trimmed string as a new slice, \ - without modifying the original"] - #[stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] - #[inline] - pub const fn trim_ascii_end(&self) -> &str { - // SAFETY: Removing ASCII characters from a `&str` does not invalidate - // UTF-8. - unsafe { core::str::from_utf8_unchecked(self.as_bytes().trim_ascii_end()) } - } - - /// Returns a string slice with leading and trailing ASCII whitespace - /// removed. - /// - /// 'Whitespace' refers to the definition used by - /// [`u8::is_ascii_whitespace`]. - /// - /// [`u8::is_ascii_whitespace`]: u8::is_ascii_whitespace - /// - /// # Examples - /// - /// ``` - /// assert_eq!("\r hello world\n ".trim_ascii(), "hello world"); - /// assert_eq!(" ".trim_ascii(), ""); - /// assert_eq!("".trim_ascii(), ""); - /// ``` - #[must_use = "this returns the trimmed string as a new slice, \ - without modifying the original"] - #[stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] - #[rustc_const_stable(feature = "byte_slice_trim_ascii", since = "CURRENT_RUSTC_VERSION")] - #[inline] - pub const fn trim_ascii(&self) -> &str { - // SAFETY: Removing ASCII characters from a `&str` does not invalidate - // UTF-8. - unsafe { core::str::from_utf8_unchecked(self.as_bytes().trim_ascii()) } - } - - /// Return an iterator that escapes each char in `self` with [`char::escape_debug`]. - /// - /// Note: only extended grapheme codepoints that begin the string will be - /// escaped. - /// - /// # Examples - /// - /// As an iterator: - /// - /// ``` - /// for c in "❤\n!".escape_debug() { - /// print!("{c}"); - /// } - /// println!(); - /// ``` - /// - /// Using `println!` directly: - /// - /// ``` - /// println!("{}", "❤\n!".escape_debug()); - /// ``` - /// - /// - /// Both are equivalent to: - /// - /// ``` - /// println!("❤\\n!"); - /// ``` - /// - /// Using `to_string`: - /// - /// ``` - /// assert_eq!("❤\n!".escape_debug().to_string(), "❤\\n!"); - /// ``` - #[must_use = "this returns the escaped string as an iterator, \ - without modifying the original"] - #[stable(feature = "str_escape", since = "1.34.0")] - pub fn escape_debug(&self) -> EscapeDebug<'_> { - let mut chars = self.chars(); - let first = chars - .next() - .map(|first| first.escape_debug_ext(EscapeDebugExtArgs::ESCAPE_ALL)) - .into_iter() - .flatten(); - let inner = first.chain(chars.flat_map(|c| { - c.escape_debug_ext(EscapeDebugExtArgs { - escape_grapheme_extended: false, - escape_single_quote: true, - escape_double_quote: true, - }) - })); - EscapeDebug { inner } - } - - /// Return an iterator that escapes each char in `self` with [`char::escape_default`]. - /// - /// # Examples - /// - /// As an iterator: - /// - /// ``` - /// for c in "❤\n!".escape_default() { - /// print!("{c}"); - /// } - /// println!(); - /// ``` - /// - /// Using `println!` directly: - /// - /// ``` - /// println!("{}", "❤\n!".escape_default()); - /// ``` - /// - /// - /// Both are equivalent to: - /// - /// ``` - /// println!("\\u{{2764}}\\n!"); - /// ``` - /// - /// Using `to_string`: - /// - /// ``` - /// assert_eq!("❤\n!".escape_default().to_string(), "\\u{2764}\\n!"); - /// ``` - #[must_use = "this returns the escaped string as an iterator, \ - without modifying the original"] - #[stable(feature = "str_escape", since = "1.34.0")] - pub fn escape_default(&self) -> EscapeDefault<'_> { - EscapeDefault { inner: self.chars().flat_map(char::escape_default) } - } - - /// Return an iterator that escapes each char in `self` with [`char::escape_unicode`]. - /// - /// # Examples - /// - /// As an iterator: - /// - /// ``` - /// for c in "❤\n!".escape_unicode() { - /// print!("{c}"); - /// } - /// println!(); - /// ``` - /// - /// Using `println!` directly: - /// - /// ``` - /// println!("{}", "❤\n!".escape_unicode()); - /// ``` - /// - /// - /// Both are equivalent to: - /// - /// ``` - /// println!("\\u{{2764}}\\u{{a}}\\u{{21}}"); - /// ``` - /// - /// Using `to_string`: - /// - /// ``` - /// assert_eq!("❤\n!".escape_unicode().to_string(), "\\u{2764}\\u{a}\\u{21}"); - /// ``` - #[must_use = "this returns the escaped string as an iterator, \ - without modifying the original"] - #[stable(feature = "str_escape", since = "1.34.0")] - pub fn escape_unicode(&self) -> EscapeUnicode<'_> { - EscapeUnicode { inner: self.chars().flat_map(char::escape_unicode) } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef<[u8]> for str { - #[inline] - fn as_ref(&self) -> &[u8] { - self.as_bytes() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Default for &str { - /// Creates an empty str - #[inline] - fn default() -> Self { - "" - } -} - -#[stable(feature = "default_mut_str", since = "1.28.0")] -impl Default for &mut str { - /// Creates an empty mutable str - #[inline] - fn default() -> Self { - // SAFETY: The empty string is valid UTF-8. - unsafe { from_utf8_unchecked_mut(&mut []) } - } -} - -type LinesMap = impl (Fn(&str) -> &str) + Copy; -type CharEscapeDebugContinue = impl (FnMut(char) -> char::EscapeDebug) + Copy; -type CharEscapeUnicode = impl (Fn(char) -> char::EscapeUnicode) + Copy; -type CharEscapeDefault = impl (Fn(char) -> char::EscapeDefault) + Copy; -type IsWhitespace = impl (Fn(char) -> bool) + Copy; -type IsAsciiWhitespace = impl (Fn(&u8) -> bool) + Copy; -type IsNotEmpty = impl (Fn(&&str) -> bool) + Copy; -type BytesIsNotEmpty<'a> = impl (FnMut(&&'a [u8]) -> bool) + Copy; -type UnsafeBytesToStr<'a> = impl (FnMut(&'a [u8]) -> &'a str) + Copy; - -// This is required to make `impl From<&str> for Box` and `impl From for Box` not overlap. -#[stable(feature = "rust1", since = "1.0.0")] -impl !crate::error::Error for &str {} diff --git a/library/core/src/str/pattern.rs b/library/core/src/str/pattern.rs deleted file mode 100644 index cc66da25795dd..0000000000000 --- a/library/core/src/str/pattern.rs +++ /dev/null @@ -1,1938 +0,0 @@ -//! The string Pattern API. -//! -//! The Pattern API provides a generic mechanism for using different pattern -//! types when searching through a string. -//! -//! For more details, see the traits [`Pattern`], [`Searcher`], -//! [`ReverseSearcher`], and [`DoubleEndedSearcher`]. -//! -//! Although this API is unstable, it is exposed via stable APIs on the -//! [`str`] type. -//! -//! # Examples -//! -//! [`Pattern`] is [implemented][pattern-impls] in the stable API for -//! [`&str`][`str`], [`char`], slices of [`char`], and functions and closures -//! implementing `FnMut(char) -> bool`. -//! -//! ``` -//! let s = "Can you find a needle in a haystack?"; -//! -//! // &str pattern -//! assert_eq!(s.find("you"), Some(4)); -//! // char pattern -//! assert_eq!(s.find('n'), Some(2)); -//! // array of chars pattern -//! assert_eq!(s.find(&['a', 'e', 'i', 'o', 'u']), Some(1)); -//! // slice of chars pattern -//! assert_eq!(s.find(&['a', 'e', 'i', 'o', 'u'][..]), Some(1)); -//! // closure pattern -//! assert_eq!(s.find(|c: char| c.is_ascii_punctuation()), Some(35)); -//! ``` -//! -//! [pattern-impls]: Pattern#implementors - -#![unstable( - feature = "pattern", - reason = "API not fully fleshed out and ready to be stabilized", - issue = "27721" -)] - -use crate::cmp; -use crate::cmp::Ordering; -use crate::convert::TryInto as _; -use crate::fmt; -use crate::slice::memchr; - -// Pattern - -/// A string pattern. -/// -/// A `Pattern<'a>` expresses that the implementing type -/// can be used as a string pattern for searching in a [`&'a str`][str]. -/// -/// For example, both `'a'` and `"aa"` are patterns that -/// would match at index `1` in the string `"baaaab"`. -/// -/// The trait itself acts as a builder for an associated -/// [`Searcher`] type, which does the actual work of finding -/// occurrences of the pattern in a string. -/// -/// Depending on the type of the pattern, the behaviour of methods like -/// [`str::find`] and [`str::contains`] can change. The table below describes -/// some of those behaviours. -/// -/// | Pattern type | Match condition | -/// |--------------------------|-------------------------------------------| -/// | `&str` | is substring | -/// | `char` | is contained in string | -/// | `&[char]` | any char in slice is contained in string | -/// | `F: FnMut(char) -> bool` | `F` returns `true` for a char in string | -/// | `&&str` | is substring | -/// | `&String` | is substring | -/// -/// # Examples -/// -/// ``` -/// // &str -/// assert_eq!("abaaa".find("ba"), Some(1)); -/// assert_eq!("abaaa".find("bac"), None); -/// -/// // char -/// assert_eq!("abaaa".find('a'), Some(0)); -/// assert_eq!("abaaa".find('b'), Some(1)); -/// assert_eq!("abaaa".find('c'), None); -/// -/// // &[char; N] -/// assert_eq!("ab".find(&['b', 'a']), Some(0)); -/// assert_eq!("abaaa".find(&['a', 'z']), Some(0)); -/// assert_eq!("abaaa".find(&['c', 'd']), None); -/// -/// // &[char] -/// assert_eq!("ab".find(&['b', 'a'][..]), Some(0)); -/// assert_eq!("abaaa".find(&['a', 'z'][..]), Some(0)); -/// assert_eq!("abaaa".find(&['c', 'd'][..]), None); -/// -/// // FnMut(char) -> bool -/// assert_eq!("abcdef_z".find(|ch| ch > 'd' && ch < 'y'), Some(4)); -/// assert_eq!("abcddd_z".find(|ch| ch > 'd' && ch < 'y'), None); -/// ``` -pub trait Pattern<'a>: Sized { - /// Associated searcher for this pattern - type Searcher: Searcher<'a>; - - /// Constructs the associated searcher from - /// `self` and the `haystack` to search in. - fn into_searcher(self, haystack: &'a str) -> Self::Searcher; - - /// Checks whether the pattern matches anywhere in the haystack - #[inline] - fn is_contained_in(self, haystack: &'a str) -> bool { - self.into_searcher(haystack).next_match().is_some() - } - - /// Checks whether the pattern matches at the front of the haystack - #[inline] - fn is_prefix_of(self, haystack: &'a str) -> bool { - matches!(self.into_searcher(haystack).next(), SearchStep::Match(0, _)) - } - - /// Checks whether the pattern matches at the back of the haystack - #[inline] - fn is_suffix_of(self, haystack: &'a str) -> bool - where - Self::Searcher: ReverseSearcher<'a>, - { - matches!(self.into_searcher(haystack).next_back(), SearchStep::Match(_, j) if haystack.len() == j) - } - - /// Removes the pattern from the front of haystack, if it matches. - #[inline] - fn strip_prefix_of(self, haystack: &'a str) -> Option<&'a str> { - if let SearchStep::Match(start, len) = self.into_searcher(haystack).next() { - debug_assert_eq!( - start, 0, - "The first search step from Searcher \ - must include the first character" - ); - // SAFETY: `Searcher` is known to return valid indices. - unsafe { Some(haystack.get_unchecked(len..)) } - } else { - None - } - } - - /// Removes the pattern from the back of haystack, if it matches. - #[inline] - fn strip_suffix_of(self, haystack: &'a str) -> Option<&'a str> - where - Self::Searcher: ReverseSearcher<'a>, - { - if let SearchStep::Match(start, end) = self.into_searcher(haystack).next_back() { - debug_assert_eq!( - end, - haystack.len(), - "The first search step from ReverseSearcher \ - must include the last character" - ); - // SAFETY: `Searcher` is known to return valid indices. - unsafe { Some(haystack.get_unchecked(..start)) } - } else { - None - } - } -} - -// Searcher - -/// Result of calling [`Searcher::next()`] or [`ReverseSearcher::next_back()`]. -#[derive(Copy, Clone, Eq, PartialEq, Debug)] -pub enum SearchStep { - /// Expresses that a match of the pattern has been found at - /// `haystack[a..b]`. - Match(usize, usize), - /// Expresses that `haystack[a..b]` has been rejected as a possible match - /// of the pattern. - /// - /// Note that there might be more than one `Reject` between two `Match`es, - /// there is no requirement for them to be combined into one. - Reject(usize, usize), - /// Expresses that every byte of the haystack has been visited, ending - /// the iteration. - Done, -} - -/// A searcher for a string pattern. -/// -/// This trait provides methods for searching for non-overlapping -/// matches of a pattern starting from the front (left) of a string. -/// -/// It will be implemented by associated `Searcher` -/// types of the [`Pattern`] trait. -/// -/// The trait is marked unsafe because the indices returned by the -/// [`next()`][Searcher::next] methods are required to lie on valid utf8 -/// boundaries in the haystack. This enables consumers of this trait to -/// slice the haystack without additional runtime checks. -pub unsafe trait Searcher<'a> { - /// Getter for the underlying string to be searched in - /// - /// Will always return the same [`&str`][str]. - fn haystack(&self) -> &'a str; - - /// Performs the next search step starting from the front. - /// - /// - Returns [`Match(a, b)`][SearchStep::Match] if `haystack[a..b]` matches - /// the pattern. - /// - Returns [`Reject(a, b)`][SearchStep::Reject] if `haystack[a..b]` can - /// not match the pattern, even partially. - /// - Returns [`Done`][SearchStep::Done] if every byte of the haystack has - /// been visited. - /// - /// The stream of [`Match`][SearchStep::Match] and - /// [`Reject`][SearchStep::Reject] values up to a [`Done`][SearchStep::Done] - /// will contain index ranges that are adjacent, non-overlapping, - /// covering the whole haystack, and laying on utf8 boundaries. - /// - /// A [`Match`][SearchStep::Match] result needs to contain the whole matched - /// pattern, however [`Reject`][SearchStep::Reject] results may be split up - /// into arbitrary many adjacent fragments. Both ranges may have zero length. - /// - /// As an example, the pattern `"aaa"` and the haystack `"cbaaaaab"` - /// might produce the stream - /// `[Reject(0, 1), Reject(1, 2), Match(2, 5), Reject(5, 8)]` - fn next(&mut self) -> SearchStep; - - /// Finds the next [`Match`][SearchStep::Match] result. See [`next()`][Searcher::next]. - /// - /// Unlike [`next()`][Searcher::next], there is no guarantee that the returned ranges - /// of this and [`next_reject`][Searcher::next_reject] will overlap. This will return - /// `(start_match, end_match)`, where start_match is the index of where - /// the match begins, and end_match is the index after the end of the match. - #[inline] - fn next_match(&mut self) -> Option<(usize, usize)> { - loop { - match self.next() { - SearchStep::Match(a, b) => return Some((a, b)), - SearchStep::Done => return None, - _ => continue, - } - } - } - - /// Finds the next [`Reject`][SearchStep::Reject] result. See [`next()`][Searcher::next] - /// and [`next_match()`][Searcher::next_match]. - /// - /// Unlike [`next()`][Searcher::next], there is no guarantee that the returned ranges - /// of this and [`next_match`][Searcher::next_match] will overlap. - #[inline] - fn next_reject(&mut self) -> Option<(usize, usize)> { - loop { - match self.next() { - SearchStep::Reject(a, b) => return Some((a, b)), - SearchStep::Done => return None, - _ => continue, - } - } - } -} - -/// A reverse searcher for a string pattern. -/// -/// This trait provides methods for searching for non-overlapping -/// matches of a pattern starting from the back (right) of a string. -/// -/// It will be implemented by associated [`Searcher`] -/// types of the [`Pattern`] trait if the pattern supports searching -/// for it from the back. -/// -/// The index ranges returned by this trait are not required -/// to exactly match those of the forward search in reverse. -/// -/// For the reason why this trait is marked unsafe, see the -/// parent trait [`Searcher`]. -pub unsafe trait ReverseSearcher<'a>: Searcher<'a> { - /// Performs the next search step starting from the back. - /// - /// - Returns [`Match(a, b)`][SearchStep::Match] if `haystack[a..b]` - /// matches the pattern. - /// - Returns [`Reject(a, b)`][SearchStep::Reject] if `haystack[a..b]` - /// can not match the pattern, even partially. - /// - Returns [`Done`][SearchStep::Done] if every byte of the haystack - /// has been visited - /// - /// The stream of [`Match`][SearchStep::Match] and - /// [`Reject`][SearchStep::Reject] values up to a [`Done`][SearchStep::Done] - /// will contain index ranges that are adjacent, non-overlapping, - /// covering the whole haystack, and laying on utf8 boundaries. - /// - /// A [`Match`][SearchStep::Match] result needs to contain the whole matched - /// pattern, however [`Reject`][SearchStep::Reject] results may be split up - /// into arbitrary many adjacent fragments. Both ranges may have zero length. - /// - /// As an example, the pattern `"aaa"` and the haystack `"cbaaaaab"` - /// might produce the stream - /// `[Reject(7, 8), Match(4, 7), Reject(1, 4), Reject(0, 1)]`. - fn next_back(&mut self) -> SearchStep; - - /// Finds the next [`Match`][SearchStep::Match] result. - /// See [`next_back()`][ReverseSearcher::next_back]. - #[inline] - fn next_match_back(&mut self) -> Option<(usize, usize)> { - loop { - match self.next_back() { - SearchStep::Match(a, b) => return Some((a, b)), - SearchStep::Done => return None, - _ => continue, - } - } - } - - /// Finds the next [`Reject`][SearchStep::Reject] result. - /// See [`next_back()`][ReverseSearcher::next_back]. - #[inline] - fn next_reject_back(&mut self) -> Option<(usize, usize)> { - loop { - match self.next_back() { - SearchStep::Reject(a, b) => return Some((a, b)), - SearchStep::Done => return None, - _ => continue, - } - } - } -} - -/// A marker trait to express that a [`ReverseSearcher`] -/// can be used for a [`DoubleEndedIterator`] implementation. -/// -/// For this, the impl of [`Searcher`] and [`ReverseSearcher`] need -/// to follow these conditions: -/// -/// - All results of `next()` need to be identical -/// to the results of `next_back()` in reverse order. -/// - `next()` and `next_back()` need to behave as -/// the two ends of a range of values, that is they -/// can not "walk past each other". -/// -/// # Examples -/// -/// `char::Searcher` is a `DoubleEndedSearcher` because searching for a -/// [`char`] only requires looking at one at a time, which behaves the same -/// from both ends. -/// -/// `(&str)::Searcher` is not a `DoubleEndedSearcher` because -/// the pattern `"aa"` in the haystack `"aaa"` matches as either -/// `"[aa]a"` or `"a[aa]"`, depending from which side it is searched. -pub trait DoubleEndedSearcher<'a>: ReverseSearcher<'a> {} - -///////////////////////////////////////////////////////////////////////////// -// Impl for char -///////////////////////////////////////////////////////////////////////////// - -/// Associated type for `>::Searcher`. -#[derive(Clone, Debug)] -pub struct CharSearcher<'a> { - haystack: &'a str, - // safety invariant: `finger`/`finger_back` must be a valid utf8 byte index of `haystack` - // This invariant can be broken *within* next_match and next_match_back, however - // they must exit with fingers on valid code point boundaries. - /// `finger` is the current byte index of the forward search. - /// Imagine that it exists before the byte at its index, i.e. - /// `haystack[finger]` is the first byte of the slice we must inspect during - /// forward searching - finger: usize, - /// `finger_back` is the current byte index of the reverse search. - /// Imagine that it exists after the byte at its index, i.e. - /// haystack[finger_back - 1] is the last byte of the slice we must inspect during - /// forward searching (and thus the first byte to be inspected when calling next_back()). - finger_back: usize, - /// The character being searched for - needle: char, - - // safety invariant: `utf8_size` must be less than 5 - /// The number of bytes `needle` takes up when encoded in utf8. - utf8_size: u8, - /// A utf8 encoded copy of the `needle` - utf8_encoded: [u8; 4], -} - -impl CharSearcher<'_> { - fn utf8_size(&self) -> usize { - self.utf8_size.into() - } -} - -unsafe impl<'a> Searcher<'a> for CharSearcher<'a> { - #[inline] - fn haystack(&self) -> &'a str { - self.haystack - } - #[inline] - fn next(&mut self) -> SearchStep { - let old_finger = self.finger; - // SAFETY: 1-4 guarantee safety of `get_unchecked` - // 1. `self.finger` and `self.finger_back` are kept on unicode boundaries - // (this is invariant) - // 2. `self.finger >= 0` since it starts at 0 and only increases - // 3. `self.finger < self.finger_back` because otherwise the char `iter` - // would return `SearchStep::Done` - // 4. `self.finger` comes before the end of the haystack because `self.finger_back` - // starts at the end and only decreases - let slice = unsafe { self.haystack.get_unchecked(old_finger..self.finger_back) }; - let mut iter = slice.chars(); - let old_len = iter.iter.len(); - if let Some(ch) = iter.next() { - // add byte offset of current character - // without re-encoding as utf-8 - self.finger += old_len - iter.iter.len(); - if ch == self.needle { - SearchStep::Match(old_finger, self.finger) - } else { - SearchStep::Reject(old_finger, self.finger) - } - } else { - SearchStep::Done - } - } - #[inline] - fn next_match(&mut self) -> Option<(usize, usize)> { - loop { - // get the haystack after the last character found - let bytes = self.haystack.as_bytes().get(self.finger..self.finger_back)?; - // the last byte of the utf8 encoded needle - // SAFETY: we have an invariant that `utf8_size < 5` - let last_byte = unsafe { *self.utf8_encoded.get_unchecked(self.utf8_size() - 1) }; - if let Some(index) = memchr::memchr(last_byte, bytes) { - // The new finger is the index of the byte we found, - // plus one, since we memchr'd for the last byte of the character. - // - // Note that this doesn't always give us a finger on a UTF8 boundary. - // If we *didn't* find our character - // we may have indexed to the non-last byte of a 3-byte or 4-byte character. - // We can't just skip to the next valid starting byte because a character like - // ꁁ (U+A041 YI SYLLABLE PA), utf-8 `EA 81 81` will have us always find - // the second byte when searching for the third. - // - // However, this is totally okay. While we have the invariant that - // self.finger is on a UTF8 boundary, this invariant is not relied upon - // within this method (it is relied upon in CharSearcher::next()). - // - // We only exit this method when we reach the end of the string, or if we - // find something. When we find something the `finger` will be set - // to a UTF8 boundary. - self.finger += index + 1; - if self.finger >= self.utf8_size() { - let found_char = self.finger - self.utf8_size(); - if let Some(slice) = self.haystack.as_bytes().get(found_char..self.finger) { - if slice == &self.utf8_encoded[0..self.utf8_size()] { - return Some((found_char, self.finger)); - } - } - } - } else { - // found nothing, exit - self.finger = self.finger_back; - return None; - } - } - } - - // let next_reject use the default implementation from the Searcher trait -} - -unsafe impl<'a> ReverseSearcher<'a> for CharSearcher<'a> { - #[inline] - fn next_back(&mut self) -> SearchStep { - let old_finger = self.finger_back; - // SAFETY: see the comment for next() above - let slice = unsafe { self.haystack.get_unchecked(self.finger..old_finger) }; - let mut iter = slice.chars(); - let old_len = iter.iter.len(); - if let Some(ch) = iter.next_back() { - // subtract byte offset of current character - // without re-encoding as utf-8 - self.finger_back -= old_len - iter.iter.len(); - if ch == self.needle { - SearchStep::Match(self.finger_back, old_finger) - } else { - SearchStep::Reject(self.finger_back, old_finger) - } - } else { - SearchStep::Done - } - } - #[inline] - fn next_match_back(&mut self) -> Option<(usize, usize)> { - let haystack = self.haystack.as_bytes(); - loop { - // get the haystack up to but not including the last character searched - let bytes = haystack.get(self.finger..self.finger_back)?; - // the last byte of the utf8 encoded needle - // SAFETY: we have an invariant that `utf8_size < 5` - let last_byte = unsafe { *self.utf8_encoded.get_unchecked(self.utf8_size() - 1) }; - if let Some(index) = memchr::memrchr(last_byte, bytes) { - // we searched a slice that was offset by self.finger, - // add self.finger to recoup the original index - let index = self.finger + index; - // memrchr will return the index of the byte we wish to - // find. In case of an ASCII character, this is indeed - // were we wish our new finger to be ("after" the found - // char in the paradigm of reverse iteration). For - // multibyte chars we need to skip down by the number of more - // bytes they have than ASCII - let shift = self.utf8_size() - 1; - if index >= shift { - let found_char = index - shift; - if let Some(slice) = haystack.get(found_char..(found_char + self.utf8_size())) { - if slice == &self.utf8_encoded[0..self.utf8_size()] { - // move finger to before the character found (i.e., at its start index) - self.finger_back = found_char; - return Some((self.finger_back, self.finger_back + self.utf8_size())); - } - } - } - // We can't use finger_back = index - size + 1 here. If we found the last char - // of a different-sized character (or the middle byte of a different character) - // we need to bump the finger_back down to `index`. This similarly makes - // `finger_back` have the potential to no longer be on a boundary, - // but this is OK since we only exit this function on a boundary - // or when the haystack has been searched completely. - // - // Unlike next_match this does not - // have the problem of repeated bytes in utf-8 because - // we're searching for the last byte, and we can only have - // found the last byte when searching in reverse. - self.finger_back = index; - } else { - self.finger_back = self.finger; - // found nothing, exit - return None; - } - } - } - - // let next_reject_back use the default implementation from the Searcher trait -} - -impl<'a> DoubleEndedSearcher<'a> for CharSearcher<'a> {} - -/// Searches for chars that are equal to a given [`char`]. -/// -/// # Examples -/// -/// ``` -/// assert_eq!("Hello world".find('o'), Some(4)); -/// ``` -impl<'a> Pattern<'a> for char { - type Searcher = CharSearcher<'a>; - - #[inline] - fn into_searcher(self, haystack: &'a str) -> Self::Searcher { - let mut utf8_encoded = [0; 4]; - let utf8_size = self - .encode_utf8(&mut utf8_encoded) - .len() - .try_into() - .expect("char len should be less than 255"); - - CharSearcher { - haystack, - finger: 0, - finger_back: haystack.len(), - needle: self, - utf8_size, - utf8_encoded, - } - } - - #[inline] - fn is_contained_in(self, haystack: &'a str) -> bool { - if (self as u32) < 128 { - haystack.as_bytes().contains(&(self as u8)) - } else { - let mut buffer = [0u8; 4]; - self.encode_utf8(&mut buffer).is_contained_in(haystack) - } - } - - #[inline] - fn is_prefix_of(self, haystack: &'a str) -> bool { - self.encode_utf8(&mut [0u8; 4]).is_prefix_of(haystack) - } - - #[inline] - fn strip_prefix_of(self, haystack: &'a str) -> Option<&'a str> { - self.encode_utf8(&mut [0u8; 4]).strip_prefix_of(haystack) - } - - #[inline] - fn is_suffix_of(self, haystack: &'a str) -> bool - where - Self::Searcher: ReverseSearcher<'a>, - { - self.encode_utf8(&mut [0u8; 4]).is_suffix_of(haystack) - } - - #[inline] - fn strip_suffix_of(self, haystack: &'a str) -> Option<&'a str> - where - Self::Searcher: ReverseSearcher<'a>, - { - self.encode_utf8(&mut [0u8; 4]).strip_suffix_of(haystack) - } -} - -///////////////////////////////////////////////////////////////////////////// -// Impl for a MultiCharEq wrapper -///////////////////////////////////////////////////////////////////////////// - -#[doc(hidden)] -trait MultiCharEq { - fn matches(&mut self, c: char) -> bool; -} - -impl MultiCharEq for F -where - F: FnMut(char) -> bool, -{ - #[inline] - fn matches(&mut self, c: char) -> bool { - (*self)(c) - } -} - -impl MultiCharEq for [char; N] { - #[inline] - fn matches(&mut self, c: char) -> bool { - self.iter().any(|&m| m == c) - } -} - -impl MultiCharEq for &[char; N] { - #[inline] - fn matches(&mut self, c: char) -> bool { - self.iter().any(|&m| m == c) - } -} - -impl MultiCharEq for &[char] { - #[inline] - fn matches(&mut self, c: char) -> bool { - self.iter().any(|&m| m == c) - } -} - -struct MultiCharEqPattern(C); - -#[derive(Clone, Debug)] -struct MultiCharEqSearcher<'a, C: MultiCharEq> { - char_eq: C, - haystack: &'a str, - char_indices: super::CharIndices<'a>, -} - -impl<'a, C: MultiCharEq> Pattern<'a> for MultiCharEqPattern { - type Searcher = MultiCharEqSearcher<'a, C>; - - #[inline] - fn into_searcher(self, haystack: &'a str) -> MultiCharEqSearcher<'a, C> { - MultiCharEqSearcher { haystack, char_eq: self.0, char_indices: haystack.char_indices() } - } -} - -unsafe impl<'a, C: MultiCharEq> Searcher<'a> for MultiCharEqSearcher<'a, C> { - #[inline] - fn haystack(&self) -> &'a str { - self.haystack - } - - #[inline] - fn next(&mut self) -> SearchStep { - let s = &mut self.char_indices; - // Compare lengths of the internal byte slice iterator - // to find length of current char - let pre_len = s.iter.iter.len(); - if let Some((i, c)) = s.next() { - let len = s.iter.iter.len(); - let char_len = pre_len - len; - if self.char_eq.matches(c) { - return SearchStep::Match(i, i + char_len); - } else { - return SearchStep::Reject(i, i + char_len); - } - } - SearchStep::Done - } -} - -unsafe impl<'a, C: MultiCharEq> ReverseSearcher<'a> for MultiCharEqSearcher<'a, C> { - #[inline] - fn next_back(&mut self) -> SearchStep { - let s = &mut self.char_indices; - // Compare lengths of the internal byte slice iterator - // to find length of current char - let pre_len = s.iter.iter.len(); - if let Some((i, c)) = s.next_back() { - let len = s.iter.iter.len(); - let char_len = pre_len - len; - if self.char_eq.matches(c) { - return SearchStep::Match(i, i + char_len); - } else { - return SearchStep::Reject(i, i + char_len); - } - } - SearchStep::Done - } -} - -impl<'a, C: MultiCharEq> DoubleEndedSearcher<'a> for MultiCharEqSearcher<'a, C> {} - -///////////////////////////////////////////////////////////////////////////// - -macro_rules! pattern_methods { - ($t:ty, $pmap:expr, $smap:expr) => { - type Searcher = $t; - - #[inline] - fn into_searcher(self, haystack: &'a str) -> $t { - ($smap)(($pmap)(self).into_searcher(haystack)) - } - - #[inline] - fn is_contained_in(self, haystack: &'a str) -> bool { - ($pmap)(self).is_contained_in(haystack) - } - - #[inline] - fn is_prefix_of(self, haystack: &'a str) -> bool { - ($pmap)(self).is_prefix_of(haystack) - } - - #[inline] - fn strip_prefix_of(self, haystack: &'a str) -> Option<&'a str> { - ($pmap)(self).strip_prefix_of(haystack) - } - - #[inline] - fn is_suffix_of(self, haystack: &'a str) -> bool - where - $t: ReverseSearcher<'a>, - { - ($pmap)(self).is_suffix_of(haystack) - } - - #[inline] - fn strip_suffix_of(self, haystack: &'a str) -> Option<&'a str> - where - $t: ReverseSearcher<'a>, - { - ($pmap)(self).strip_suffix_of(haystack) - } - }; -} - -macro_rules! searcher_methods { - (forward) => { - #[inline] - fn haystack(&self) -> &'a str { - self.0.haystack() - } - #[inline] - fn next(&mut self) -> SearchStep { - self.0.next() - } - #[inline] - fn next_match(&mut self) -> Option<(usize, usize)> { - self.0.next_match() - } - #[inline] - fn next_reject(&mut self) -> Option<(usize, usize)> { - self.0.next_reject() - } - }; - (reverse) => { - #[inline] - fn next_back(&mut self) -> SearchStep { - self.0.next_back() - } - #[inline] - fn next_match_back(&mut self) -> Option<(usize, usize)> { - self.0.next_match_back() - } - #[inline] - fn next_reject_back(&mut self) -> Option<(usize, usize)> { - self.0.next_reject_back() - } - }; -} - -/// Associated type for `<[char; N] as Pattern<'a>>::Searcher`. -#[derive(Clone, Debug)] -pub struct CharArraySearcher<'a, const N: usize>( - as Pattern<'a>>::Searcher, -); - -/// Associated type for `<&[char; N] as Pattern<'a>>::Searcher`. -#[derive(Clone, Debug)] -pub struct CharArrayRefSearcher<'a, 'b, const N: usize>( - as Pattern<'a>>::Searcher, -); - -/// Searches for chars that are equal to any of the [`char`]s in the array. -/// -/// # Examples -/// -/// ``` -/// assert_eq!("Hello world".find(['o', 'l']), Some(2)); -/// assert_eq!("Hello world".find(['h', 'w']), Some(6)); -/// ``` -impl<'a, const N: usize> Pattern<'a> for [char; N] { - pattern_methods!(CharArraySearcher<'a, N>, MultiCharEqPattern, CharArraySearcher); -} - -unsafe impl<'a, const N: usize> Searcher<'a> for CharArraySearcher<'a, N> { - searcher_methods!(forward); -} - -unsafe impl<'a, const N: usize> ReverseSearcher<'a> for CharArraySearcher<'a, N> { - searcher_methods!(reverse); -} - -impl<'a, const N: usize> DoubleEndedSearcher<'a> for CharArraySearcher<'a, N> {} - -/// Searches for chars that are equal to any of the [`char`]s in the array. -/// -/// # Examples -/// -/// ``` -/// assert_eq!("Hello world".find(&['o', 'l']), Some(2)); -/// assert_eq!("Hello world".find(&['h', 'w']), Some(6)); -/// ``` -impl<'a, 'b, const N: usize> Pattern<'a> for &'b [char; N] { - pattern_methods!(CharArrayRefSearcher<'a, 'b, N>, MultiCharEqPattern, CharArrayRefSearcher); -} - -unsafe impl<'a, 'b, const N: usize> Searcher<'a> for CharArrayRefSearcher<'a, 'b, N> { - searcher_methods!(forward); -} - -unsafe impl<'a, 'b, const N: usize> ReverseSearcher<'a> for CharArrayRefSearcher<'a, 'b, N> { - searcher_methods!(reverse); -} - -impl<'a, 'b, const N: usize> DoubleEndedSearcher<'a> for CharArrayRefSearcher<'a, 'b, N> {} - -///////////////////////////////////////////////////////////////////////////// -// Impl for &[char] -///////////////////////////////////////////////////////////////////////////// - -// Todo: Change / Remove due to ambiguity in meaning. - -/// Associated type for `<&[char] as Pattern<'a>>::Searcher`. -#[derive(Clone, Debug)] -pub struct CharSliceSearcher<'a, 'b>( as Pattern<'a>>::Searcher); - -unsafe impl<'a, 'b> Searcher<'a> for CharSliceSearcher<'a, 'b> { - searcher_methods!(forward); -} - -unsafe impl<'a, 'b> ReverseSearcher<'a> for CharSliceSearcher<'a, 'b> { - searcher_methods!(reverse); -} - -impl<'a, 'b> DoubleEndedSearcher<'a> for CharSliceSearcher<'a, 'b> {} - -/// Searches for chars that are equal to any of the [`char`]s in the slice. -/// -/// # Examples -/// -/// ``` -/// assert_eq!("Hello world".find(&['l', 'l'] as &[_]), Some(2)); -/// assert_eq!("Hello world".find(&['l', 'l'][..]), Some(2)); -/// ``` -impl<'a, 'b> Pattern<'a> for &'b [char] { - pattern_methods!(CharSliceSearcher<'a, 'b>, MultiCharEqPattern, CharSliceSearcher); -} - -///////////////////////////////////////////////////////////////////////////// -// Impl for F: FnMut(char) -> bool -///////////////////////////////////////////////////////////////////////////// - -/// Associated type for `>::Searcher`. -#[derive(Clone)] -pub struct CharPredicateSearcher<'a, F>( as Pattern<'a>>::Searcher) -where - F: FnMut(char) -> bool; - -impl fmt::Debug for CharPredicateSearcher<'_, F> -where - F: FnMut(char) -> bool, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("CharPredicateSearcher") - .field("haystack", &self.0.haystack) - .field("char_indices", &self.0.char_indices) - .finish() - } -} -unsafe impl<'a, F> Searcher<'a> for CharPredicateSearcher<'a, F> -where - F: FnMut(char) -> bool, -{ - searcher_methods!(forward); -} - -unsafe impl<'a, F> ReverseSearcher<'a> for CharPredicateSearcher<'a, F> -where - F: FnMut(char) -> bool, -{ - searcher_methods!(reverse); -} - -impl<'a, F> DoubleEndedSearcher<'a> for CharPredicateSearcher<'a, F> where F: FnMut(char) -> bool {} - -/// Searches for [`char`]s that match the given predicate. -/// -/// # Examples -/// -/// ``` -/// assert_eq!("Hello world".find(char::is_uppercase), Some(0)); -/// assert_eq!("Hello world".find(|c| "aeiou".contains(c)), Some(1)); -/// ``` -impl<'a, F> Pattern<'a> for F -where - F: FnMut(char) -> bool, -{ - pattern_methods!(CharPredicateSearcher<'a, F>, MultiCharEqPattern, CharPredicateSearcher); -} - -///////////////////////////////////////////////////////////////////////////// -// Impl for &&str -///////////////////////////////////////////////////////////////////////////// - -/// Delegates to the `&str` impl. -impl<'a, 'b, 'c> Pattern<'a> for &'c &'b str { - pattern_methods!(StrSearcher<'a, 'b>, |&s| s, |s| s); -} - -///////////////////////////////////////////////////////////////////////////// -// Impl for &str -///////////////////////////////////////////////////////////////////////////// - -/// Non-allocating substring search. -/// -/// Will handle the pattern `""` as returning empty matches at each character -/// boundary. -/// -/// # Examples -/// -/// ``` -/// assert_eq!("Hello world".find("world"), Some(6)); -/// ``` -impl<'a, 'b> Pattern<'a> for &'b str { - type Searcher = StrSearcher<'a, 'b>; - - #[inline] - fn into_searcher(self, haystack: &'a str) -> StrSearcher<'a, 'b> { - StrSearcher::new(haystack, self) - } - - /// Checks whether the pattern matches at the front of the haystack. - #[inline] - fn is_prefix_of(self, haystack: &'a str) -> bool { - haystack.as_bytes().starts_with(self.as_bytes()) - } - - /// Checks whether the pattern matches anywhere in the haystack - #[inline] - fn is_contained_in(self, haystack: &'a str) -> bool { - if self.len() == 0 { - return true; - } - - match self.len().cmp(&haystack.len()) { - Ordering::Less => { - if self.len() == 1 { - return haystack.as_bytes().contains(&self.as_bytes()[0]); - } - - #[cfg(all(target_arch = "x86_64", target_feature = "sse2"))] - if self.len() <= 32 { - if let Some(result) = simd_contains(self, haystack) { - return result; - } - } - - self.into_searcher(haystack).next_match().is_some() - } - _ => self == haystack, - } - } - - /// Removes the pattern from the front of haystack, if it matches. - #[inline] - fn strip_prefix_of(self, haystack: &'a str) -> Option<&'a str> { - if self.is_prefix_of(haystack) { - // SAFETY: prefix was just verified to exist. - unsafe { Some(haystack.get_unchecked(self.as_bytes().len()..)) } - } else { - None - } - } - - /// Checks whether the pattern matches at the back of the haystack. - #[inline] - fn is_suffix_of(self, haystack: &'a str) -> bool { - haystack.as_bytes().ends_with(self.as_bytes()) - } - - /// Removes the pattern from the back of haystack, if it matches. - #[inline] - fn strip_suffix_of(self, haystack: &'a str) -> Option<&'a str> { - if self.is_suffix_of(haystack) { - let i = haystack.len() - self.as_bytes().len(); - // SAFETY: suffix was just verified to exist. - unsafe { Some(haystack.get_unchecked(..i)) } - } else { - None - } - } -} - -///////////////////////////////////////////////////////////////////////////// -// Two Way substring searcher -///////////////////////////////////////////////////////////////////////////// - -#[derive(Clone, Debug)] -/// Associated type for `<&str as Pattern<'a>>::Searcher`. -pub struct StrSearcher<'a, 'b> { - haystack: &'a str, - needle: &'b str, - - searcher: StrSearcherImpl, -} - -#[derive(Clone, Debug)] -enum StrSearcherImpl { - Empty(EmptyNeedle), - TwoWay(TwoWaySearcher), -} - -#[derive(Clone, Debug)] -struct EmptyNeedle { - position: usize, - end: usize, - is_match_fw: bool, - is_match_bw: bool, - // Needed in case of an empty haystack, see #85462 - is_finished: bool, -} - -impl<'a, 'b> StrSearcher<'a, 'b> { - fn new(haystack: &'a str, needle: &'b str) -> StrSearcher<'a, 'b> { - if needle.is_empty() { - StrSearcher { - haystack, - needle, - searcher: StrSearcherImpl::Empty(EmptyNeedle { - position: 0, - end: haystack.len(), - is_match_fw: true, - is_match_bw: true, - is_finished: false, - }), - } - } else { - StrSearcher { - haystack, - needle, - searcher: StrSearcherImpl::TwoWay(TwoWaySearcher::new( - needle.as_bytes(), - haystack.len(), - )), - } - } - } -} - -unsafe impl<'a, 'b> Searcher<'a> for StrSearcher<'a, 'b> { - #[inline] - fn haystack(&self) -> &'a str { - self.haystack - } - - #[inline] - fn next(&mut self) -> SearchStep { - match self.searcher { - StrSearcherImpl::Empty(ref mut searcher) => { - if searcher.is_finished { - return SearchStep::Done; - } - // empty needle rejects every char and matches every empty string between them - let is_match = searcher.is_match_fw; - searcher.is_match_fw = !searcher.is_match_fw; - let pos = searcher.position; - match self.haystack[pos..].chars().next() { - _ if is_match => SearchStep::Match(pos, pos), - None => { - searcher.is_finished = true; - SearchStep::Done - } - Some(ch) => { - searcher.position += ch.len_utf8(); - SearchStep::Reject(pos, searcher.position) - } - } - } - StrSearcherImpl::TwoWay(ref mut searcher) => { - // TwoWaySearcher produces valid *Match* indices that split at char boundaries - // as long as it does correct matching and that haystack and needle are - // valid UTF-8 - // *Rejects* from the algorithm can fall on any indices, but we will walk them - // manually to the next character boundary, so that they are utf-8 safe. - if searcher.position == self.haystack.len() { - return SearchStep::Done; - } - let is_long = searcher.memory == usize::MAX; - match searcher.next::( - self.haystack.as_bytes(), - self.needle.as_bytes(), - is_long, - ) { - SearchStep::Reject(a, mut b) => { - // skip to next char boundary - while !self.haystack.is_char_boundary(b) { - b += 1; - } - searcher.position = cmp::max(b, searcher.position); - SearchStep::Reject(a, b) - } - otherwise => otherwise, - } - } - } - } - - #[inline] - fn next_match(&mut self) -> Option<(usize, usize)> { - match self.searcher { - StrSearcherImpl::Empty(..) => loop { - match self.next() { - SearchStep::Match(a, b) => return Some((a, b)), - SearchStep::Done => return None, - SearchStep::Reject(..) => {} - } - }, - StrSearcherImpl::TwoWay(ref mut searcher) => { - let is_long = searcher.memory == usize::MAX; - // write out `true` and `false` cases to encourage the compiler - // to specialize the two cases separately. - if is_long { - searcher.next::( - self.haystack.as_bytes(), - self.needle.as_bytes(), - true, - ) - } else { - searcher.next::( - self.haystack.as_bytes(), - self.needle.as_bytes(), - false, - ) - } - } - } - } -} - -unsafe impl<'a, 'b> ReverseSearcher<'a> for StrSearcher<'a, 'b> { - #[inline] - fn next_back(&mut self) -> SearchStep { - match self.searcher { - StrSearcherImpl::Empty(ref mut searcher) => { - if searcher.is_finished { - return SearchStep::Done; - } - let is_match = searcher.is_match_bw; - searcher.is_match_bw = !searcher.is_match_bw; - let end = searcher.end; - match self.haystack[..end].chars().next_back() { - _ if is_match => SearchStep::Match(end, end), - None => { - searcher.is_finished = true; - SearchStep::Done - } - Some(ch) => { - searcher.end -= ch.len_utf8(); - SearchStep::Reject(searcher.end, end) - } - } - } - StrSearcherImpl::TwoWay(ref mut searcher) => { - if searcher.end == 0 { - return SearchStep::Done; - } - let is_long = searcher.memory == usize::MAX; - match searcher.next_back::( - self.haystack.as_bytes(), - self.needle.as_bytes(), - is_long, - ) { - SearchStep::Reject(mut a, b) => { - // skip to next char boundary - while !self.haystack.is_char_boundary(a) { - a -= 1; - } - searcher.end = cmp::min(a, searcher.end); - SearchStep::Reject(a, b) - } - otherwise => otherwise, - } - } - } - } - - #[inline] - fn next_match_back(&mut self) -> Option<(usize, usize)> { - match self.searcher { - StrSearcherImpl::Empty(..) => loop { - match self.next_back() { - SearchStep::Match(a, b) => return Some((a, b)), - SearchStep::Done => return None, - SearchStep::Reject(..) => {} - } - }, - StrSearcherImpl::TwoWay(ref mut searcher) => { - let is_long = searcher.memory == usize::MAX; - // write out `true` and `false`, like `next_match` - if is_long { - searcher.next_back::( - self.haystack.as_bytes(), - self.needle.as_bytes(), - true, - ) - } else { - searcher.next_back::( - self.haystack.as_bytes(), - self.needle.as_bytes(), - false, - ) - } - } - } - } -} - -/// The internal state of the two-way substring search algorithm. -#[derive(Clone, Debug)] -struct TwoWaySearcher { - // constants - /// critical factorization index - crit_pos: usize, - /// critical factorization index for reversed needle - crit_pos_back: usize, - period: usize, - /// `byteset` is an extension (not part of the two way algorithm); - /// it's a 64-bit "fingerprint" where each set bit `j` corresponds - /// to a (byte & 63) == j present in the needle. - byteset: u64, - - // variables - position: usize, - end: usize, - /// index into needle before which we have already matched - memory: usize, - /// index into needle after which we have already matched - memory_back: usize, -} - -/* - This is the Two-Way search algorithm, which was introduced in the paper: - Crochemore, M., Perrin, D., 1991, Two-way string-matching, Journal of the ACM 38(3):651-675. - - Here's some background information. - - A *word* is a string of symbols. The *length* of a word should be a familiar - notion, and here we denote it for any word x by |x|. - (We also allow for the possibility of the *empty word*, a word of length zero). - - If x is any non-empty word, then an integer p with 0 < p <= |x| is said to be a - *period* for x iff for all i with 0 <= i <= |x| - p - 1, we have x[i] == x[i+p]. - For example, both 1 and 2 are periods for the string "aa". As another example, - the only period of the string "abcd" is 4. - - We denote by period(x) the *smallest* period of x (provided that x is non-empty). - This is always well-defined since every non-empty word x has at least one period, - |x|. We sometimes call this *the period* of x. - - If u, v and x are words such that x = uv, where uv is the concatenation of u and - v, then we say that (u, v) is a *factorization* of x. - - Let (u, v) be a factorization for a word x. Then if w is a non-empty word such - that both of the following hold - - - either w is a suffix of u or u is a suffix of w - - either w is a prefix of v or v is a prefix of w - - then w is said to be a *repetition* for the factorization (u, v). - - Just to unpack this, there are four possibilities here. Let w = "abc". Then we - might have: - - - w is a suffix of u and w is a prefix of v. ex: ("lolabc", "abcde") - - w is a suffix of u and v is a prefix of w. ex: ("lolabc", "ab") - - u is a suffix of w and w is a prefix of v. ex: ("bc", "abchi") - - u is a suffix of w and v is a prefix of w. ex: ("bc", "a") - - Note that the word vu is a repetition for any factorization (u,v) of x = uv, - so every factorization has at least one repetition. - - If x is a string and (u, v) is a factorization for x, then a *local period* for - (u, v) is an integer r such that there is some word w such that |w| = r and w is - a repetition for (u, v). - - We denote by local_period(u, v) the smallest local period of (u, v). We sometimes - call this *the local period* of (u, v). Provided that x = uv is non-empty, this - is well-defined (because each non-empty word has at least one factorization, as - noted above). - - It can be proven that the following is an equivalent definition of a local period - for a factorization (u, v): any positive integer r such that x[i] == x[i+r] for - all i such that |u| - r <= i <= |u| - 1 and such that both x[i] and x[i+r] are - defined. (i.e., i > 0 and i + r < |x|). - - Using the above reformulation, it is easy to prove that - - 1 <= local_period(u, v) <= period(uv) - - A factorization (u, v) of x such that local_period(u,v) = period(x) is called a - *critical factorization*. - - The algorithm hinges on the following theorem, which is stated without proof: - - **Critical Factorization Theorem** Any word x has at least one critical - factorization (u, v) such that |u| < period(x). - - The purpose of maximal_suffix is to find such a critical factorization. - - If the period is short, compute another factorization x = u' v' to use - for reverse search, chosen instead so that |v'| < period(x). - -*/ -impl TwoWaySearcher { - fn new(needle: &[u8], end: usize) -> TwoWaySearcher { - let (crit_pos_false, period_false) = TwoWaySearcher::maximal_suffix(needle, false); - let (crit_pos_true, period_true) = TwoWaySearcher::maximal_suffix(needle, true); - - let (crit_pos, period) = if crit_pos_false > crit_pos_true { - (crit_pos_false, period_false) - } else { - (crit_pos_true, period_true) - }; - - // A particularly readable explanation of what's going on here can be found - // in Crochemore and Rytter's book "Text Algorithms", ch 13. Specifically - // see the code for "Algorithm CP" on p. 323. - // - // What's going on is we have some critical factorization (u, v) of the - // needle, and we want to determine whether u is a suffix of - // &v[..period]. If it is, we use "Algorithm CP1". Otherwise we use - // "Algorithm CP2", which is optimized for when the period of the needle - // is large. - if needle[..crit_pos] == needle[period..period + crit_pos] { - // short period case -- the period is exact - // compute a separate critical factorization for the reversed needle - // x = u' v' where |v'| < period(x). - // - // This is sped up by the period being known already. - // Note that a case like x = "acba" may be factored exactly forwards - // (crit_pos = 1, period = 3) while being factored with approximate - // period in reverse (crit_pos = 2, period = 2). We use the given - // reverse factorization but keep the exact period. - let crit_pos_back = needle.len() - - cmp::max( - TwoWaySearcher::reverse_maximal_suffix(needle, period, false), - TwoWaySearcher::reverse_maximal_suffix(needle, period, true), - ); - - TwoWaySearcher { - crit_pos, - crit_pos_back, - period, - byteset: Self::byteset_create(&needle[..period]), - - position: 0, - end, - memory: 0, - memory_back: needle.len(), - } - } else { - // long period case -- we have an approximation to the actual period, - // and don't use memorization. - // - // Approximate the period by lower bound max(|u|, |v|) + 1. - // The critical factorization is efficient to use for both forward and - // reverse search. - - TwoWaySearcher { - crit_pos, - crit_pos_back: crit_pos, - period: cmp::max(crit_pos, needle.len() - crit_pos) + 1, - byteset: Self::byteset_create(needle), - - position: 0, - end, - memory: usize::MAX, // Dummy value to signify that the period is long - memory_back: usize::MAX, - } - } - } - - #[inline] - fn byteset_create(bytes: &[u8]) -> u64 { - bytes.iter().fold(0, |a, &b| (1 << (b & 0x3f)) | a) - } - - #[inline] - fn byteset_contains(&self, byte: u8) -> bool { - (self.byteset >> ((byte & 0x3f) as usize)) & 1 != 0 - } - - // One of the main ideas of Two-Way is that we factorize the needle into - // two halves, (u, v), and begin trying to find v in the haystack by scanning - // left to right. If v matches, we try to match u by scanning right to left. - // How far we can jump when we encounter a mismatch is all based on the fact - // that (u, v) is a critical factorization for the needle. - #[inline] - fn next(&mut self, haystack: &[u8], needle: &[u8], long_period: bool) -> S::Output - where - S: TwoWayStrategy, - { - // `next()` uses `self.position` as its cursor - let old_pos = self.position; - let needle_last = needle.len() - 1; - 'search: loop { - // Check that we have room to search in - // position + needle_last can not overflow if we assume slices - // are bounded by isize's range. - let tail_byte = match haystack.get(self.position + needle_last) { - Some(&b) => b, - None => { - self.position = haystack.len(); - return S::rejecting(old_pos, self.position); - } - }; - - if S::use_early_reject() && old_pos != self.position { - return S::rejecting(old_pos, self.position); - } - - // Quickly skip by large portions unrelated to our substring - if !self.byteset_contains(tail_byte) { - self.position += needle.len(); - if !long_period { - self.memory = 0; - } - continue 'search; - } - - // See if the right part of the needle matches - let start = - if long_period { self.crit_pos } else { cmp::max(self.crit_pos, self.memory) }; - for i in start..needle.len() { - if needle[i] != haystack[self.position + i] { - self.position += i - self.crit_pos + 1; - if !long_period { - self.memory = 0; - } - continue 'search; - } - } - - // See if the left part of the needle matches - let start = if long_period { 0 } else { self.memory }; - for i in (start..self.crit_pos).rev() { - if needle[i] != haystack[self.position + i] { - self.position += self.period; - if !long_period { - self.memory = needle.len() - self.period; - } - continue 'search; - } - } - - // We have found a match! - let match_pos = self.position; - - // Note: add self.period instead of needle.len() to have overlapping matches - self.position += needle.len(); - if !long_period { - self.memory = 0; // set to needle.len() - self.period for overlapping matches - } - - return S::matching(match_pos, match_pos + needle.len()); - } - } - - // Follows the ideas in `next()`. - // - // The definitions are symmetrical, with period(x) = period(reverse(x)) - // and local_period(u, v) = local_period(reverse(v), reverse(u)), so if (u, v) - // is a critical factorization, so is (reverse(v), reverse(u)). - // - // For the reverse case we have computed a critical factorization x = u' v' - // (field `crit_pos_back`). We need |u| < period(x) for the forward case and - // thus |v'| < period(x) for the reverse. - // - // To search in reverse through the haystack, we search forward through - // a reversed haystack with a reversed needle, matching first u' and then v'. - #[inline] - fn next_back(&mut self, haystack: &[u8], needle: &[u8], long_period: bool) -> S::Output - where - S: TwoWayStrategy, - { - // `next_back()` uses `self.end` as its cursor -- so that `next()` and `next_back()` - // are independent. - let old_end = self.end; - 'search: loop { - // Check that we have room to search in - // end - needle.len() will wrap around when there is no more room, - // but due to slice length limits it can never wrap all the way back - // into the length of haystack. - let front_byte = match haystack.get(self.end.wrapping_sub(needle.len())) { - Some(&b) => b, - None => { - self.end = 0; - return S::rejecting(0, old_end); - } - }; - - if S::use_early_reject() && old_end != self.end { - return S::rejecting(self.end, old_end); - } - - // Quickly skip by large portions unrelated to our substring - if !self.byteset_contains(front_byte) { - self.end -= needle.len(); - if !long_period { - self.memory_back = needle.len(); - } - continue 'search; - } - - // See if the left part of the needle matches - let crit = if long_period { - self.crit_pos_back - } else { - cmp::min(self.crit_pos_back, self.memory_back) - }; - for i in (0..crit).rev() { - if needle[i] != haystack[self.end - needle.len() + i] { - self.end -= self.crit_pos_back - i; - if !long_period { - self.memory_back = needle.len(); - } - continue 'search; - } - } - - // See if the right part of the needle matches - let needle_end = if long_period { needle.len() } else { self.memory_back }; - for i in self.crit_pos_back..needle_end { - if needle[i] != haystack[self.end - needle.len() + i] { - self.end -= self.period; - if !long_period { - self.memory_back = self.period; - } - continue 'search; - } - } - - // We have found a match! - let match_pos = self.end - needle.len(); - // Note: sub self.period instead of needle.len() to have overlapping matches - self.end -= needle.len(); - if !long_period { - self.memory_back = needle.len(); - } - - return S::matching(match_pos, match_pos + needle.len()); - } - } - - // Compute the maximal suffix of `arr`. - // - // The maximal suffix is a possible critical factorization (u, v) of `arr`. - // - // Returns (`i`, `p`) where `i` is the starting index of v and `p` is the - // period of v. - // - // `order_greater` determines if lexical order is `<` or `>`. Both - // orders must be computed -- the ordering with the largest `i` gives - // a critical factorization. - // - // For long period cases, the resulting period is not exact (it is too short). - #[inline] - fn maximal_suffix(arr: &[u8], order_greater: bool) -> (usize, usize) { - let mut left = 0; // Corresponds to i in the paper - let mut right = 1; // Corresponds to j in the paper - let mut offset = 0; // Corresponds to k in the paper, but starting at 0 - // to match 0-based indexing. - let mut period = 1; // Corresponds to p in the paper - - while let Some(&a) = arr.get(right + offset) { - // `left` will be inbounds when `right` is. - let b = arr[left + offset]; - if (a < b && !order_greater) || (a > b && order_greater) { - // Suffix is smaller, period is entire prefix so far. - right += offset + 1; - offset = 0; - period = right - left; - } else if a == b { - // Advance through repetition of the current period. - if offset + 1 == period { - right += offset + 1; - offset = 0; - } else { - offset += 1; - } - } else { - // Suffix is larger, start over from current location. - left = right; - right += 1; - offset = 0; - period = 1; - } - } - (left, period) - } - - // Compute the maximal suffix of the reverse of `arr`. - // - // The maximal suffix is a possible critical factorization (u', v') of `arr`. - // - // Returns `i` where `i` is the starting index of v', from the back; - // returns immediately when a period of `known_period` is reached. - // - // `order_greater` determines if lexical order is `<` or `>`. Both - // orders must be computed -- the ordering with the largest `i` gives - // a critical factorization. - // - // For long period cases, the resulting period is not exact (it is too short). - fn reverse_maximal_suffix(arr: &[u8], known_period: usize, order_greater: bool) -> usize { - let mut left = 0; // Corresponds to i in the paper - let mut right = 1; // Corresponds to j in the paper - let mut offset = 0; // Corresponds to k in the paper, but starting at 0 - // to match 0-based indexing. - let mut period = 1; // Corresponds to p in the paper - let n = arr.len(); - - while right + offset < n { - let a = arr[n - (1 + right + offset)]; - let b = arr[n - (1 + left + offset)]; - if (a < b && !order_greater) || (a > b && order_greater) { - // Suffix is smaller, period is entire prefix so far. - right += offset + 1; - offset = 0; - period = right - left; - } else if a == b { - // Advance through repetition of the current period. - if offset + 1 == period { - right += offset + 1; - offset = 0; - } else { - offset += 1; - } - } else { - // Suffix is larger, start over from current location. - left = right; - right += 1; - offset = 0; - period = 1; - } - if period == known_period { - break; - } - } - debug_assert!(period <= known_period); - left - } -} - -// TwoWayStrategy allows the algorithm to either skip non-matches as quickly -// as possible, or to work in a mode where it emits Rejects relatively quickly. -trait TwoWayStrategy { - type Output; - fn use_early_reject() -> bool; - fn rejecting(a: usize, b: usize) -> Self::Output; - fn matching(a: usize, b: usize) -> Self::Output; -} - -/// Skip to match intervals as quickly as possible -enum MatchOnly {} - -impl TwoWayStrategy for MatchOnly { - type Output = Option<(usize, usize)>; - - #[inline] - fn use_early_reject() -> bool { - false - } - #[inline] - fn rejecting(_a: usize, _b: usize) -> Self::Output { - None - } - #[inline] - fn matching(a: usize, b: usize) -> Self::Output { - Some((a, b)) - } -} - -/// Emit Rejects regularly -enum RejectAndMatch {} - -impl TwoWayStrategy for RejectAndMatch { - type Output = SearchStep; - - #[inline] - fn use_early_reject() -> bool { - true - } - #[inline] - fn rejecting(a: usize, b: usize) -> Self::Output { - SearchStep::Reject(a, b) - } - #[inline] - fn matching(a: usize, b: usize) -> Self::Output { - SearchStep::Match(a, b) - } -} - -/// SIMD search for short needles based on -/// Wojciech Muła's "SIMD-friendly algorithms for substring searching"[0] -/// -/// It skips ahead by the vector width on each iteration (rather than the needle length as two-way -/// does) by probing the first and last byte of the needle for the whole vector width -/// and only doing full needle comparisons when the vectorized probe indicated potential matches. -/// -/// Since the x86_64 baseline only offers SSE2 we only use u8x16 here. -/// If we ever ship std with for x86-64-v3 or adapt this for other platforms then wider vectors -/// should be evaluated. -/// -/// For haystacks smaller than vector-size + needle length it falls back to -/// a naive O(n*m) search so this implementation should not be called on larger needles. -/// -/// [0]: http://0x80.pl/articles/simd-strfind.html#sse-avx2 -#[cfg(all(target_arch = "x86_64", target_feature = "sse2"))] -#[inline] -fn simd_contains(needle: &str, haystack: &str) -> Option { - let needle = needle.as_bytes(); - let haystack = haystack.as_bytes(); - - debug_assert!(needle.len() > 1); - - use crate::ops::BitAnd; - use crate::simd::cmp::SimdPartialEq; - use crate::simd::mask8x16 as Mask; - use crate::simd::u8x16 as Block; - - let first_probe = needle[0]; - let last_byte_offset = needle.len() - 1; - - // the offset used for the 2nd vector - let second_probe_offset = if needle.len() == 2 { - // never bail out on len=2 needles because the probes will fully cover them and have - // no degenerate cases. - 1 - } else { - // try a few bytes in case first and last byte of the needle are the same - let Some(second_probe_offset) = - (needle.len().saturating_sub(4)..needle.len()).rfind(|&idx| needle[idx] != first_probe) - else { - // fall back to other search methods if we can't find any different bytes - // since we could otherwise hit some degenerate cases - return None; - }; - second_probe_offset - }; - - // do a naive search if the haystack is too small to fit - if haystack.len() < Block::LEN + last_byte_offset { - return Some(haystack.windows(needle.len()).any(|c| c == needle)); - } - - let first_probe: Block = Block::splat(first_probe); - let second_probe: Block = Block::splat(needle[second_probe_offset]); - // first byte are already checked by the outer loop. to verify a match only the - // remainder has to be compared. - let trimmed_needle = &needle[1..]; - - // this #[cold] is load-bearing, benchmark before removing it... - let check_mask = #[cold] - |idx, mask: u16, skip: bool| -> bool { - if skip { - return false; - } - - // and so is this. optimizations are weird. - let mut mask = mask; - - while mask != 0 { - let trailing = mask.trailing_zeros(); - let offset = idx + trailing as usize + 1; - // SAFETY: mask is between 0 and 15 trailing zeroes, we skip one additional byte that was already compared - // and then take trimmed_needle.len() bytes. This is within the bounds defined by the outer loop - unsafe { - let sub = haystack.get_unchecked(offset..).get_unchecked(..trimmed_needle.len()); - if small_slice_eq(sub, trimmed_needle) { - return true; - } - } - mask &= !(1 << trailing); - } - return false; - }; - - let test_chunk = |idx| -> u16 { - // SAFETY: this requires at least LANES bytes being readable at idx - // that is ensured by the loop ranges (see comments below) - let a: Block = unsafe { haystack.as_ptr().add(idx).cast::().read_unaligned() }; - // SAFETY: this requires LANES + block_offset bytes being readable at idx - let b: Block = unsafe { - haystack.as_ptr().add(idx).add(second_probe_offset).cast::().read_unaligned() - }; - let eq_first: Mask = a.simd_eq(first_probe); - let eq_last: Mask = b.simd_eq(second_probe); - let both = eq_first.bitand(eq_last); - let mask = both.to_bitmask() as u16; - - return mask; - }; - - let mut i = 0; - let mut result = false; - // The loop condition must ensure that there's enough headroom to read LANE bytes, - // and not only at the current index but also at the index shifted by block_offset - const UNROLL: usize = 4; - while i + last_byte_offset + UNROLL * Block::LEN < haystack.len() && !result { - let mut masks = [0u16; UNROLL]; - for j in 0..UNROLL { - masks[j] = test_chunk(i + j * Block::LEN); - } - for j in 0..UNROLL { - let mask = masks[j]; - if mask != 0 { - result |= check_mask(i + j * Block::LEN, mask, result); - } - } - i += UNROLL * Block::LEN; - } - while i + last_byte_offset + Block::LEN < haystack.len() && !result { - let mask = test_chunk(i); - if mask != 0 { - result |= check_mask(i, mask, result); - } - i += Block::LEN; - } - - // Process the tail that didn't fit into LANES-sized steps. - // This simply repeats the same procedure but as right-aligned chunk instead - // of a left-aligned one. The last byte must be exactly flush with the string end so - // we don't miss a single byte or read out of bounds. - let i = haystack.len() - last_byte_offset - Block::LEN; - let mask = test_chunk(i); - if mask != 0 { - result |= check_mask(i, mask, result); - } - - Some(result) -} - -/// Compares short slices for equality. -/// -/// It avoids a call to libc's memcmp which is faster on long slices -/// due to SIMD optimizations but it incurs a function call overhead. -/// -/// # Safety -/// -/// Both slices must have the same length. -#[cfg(all(target_arch = "x86_64", target_feature = "sse2"))] // only called on x86 -#[inline] -unsafe fn small_slice_eq(x: &[u8], y: &[u8]) -> bool { - debug_assert_eq!(x.len(), y.len()); - // This function is adapted from - // https://github.com/BurntSushi/memchr/blob/8037d11b4357b0f07be2bb66dc2659d9cf28ad32/src/memmem/util.rs#L32 - - // If we don't have enough bytes to do 4-byte at a time loads, then - // fall back to the naive slow version. - // - // Potential alternative: We could do a copy_nonoverlapping combined with a mask instead - // of a loop. Benchmark it. - if x.len() < 4 { - for (&b1, &b2) in x.iter().zip(y) { - if b1 != b2 { - return false; - } - } - return true; - } - // When we have 4 or more bytes to compare, then proceed in chunks of 4 at - // a time using unaligned loads. - // - // Also, why do 4 byte loads instead of, say, 8 byte loads? The reason is - // that this particular version of memcmp is likely to be called with tiny - // needles. That means that if we do 8 byte loads, then a higher proportion - // of memcmp calls will use the slower variant above. With that said, this - // is a hypothesis and is only loosely supported by benchmarks. There's - // likely some improvement that could be made here. The main thing here - // though is to optimize for latency, not throughput. - - // SAFETY: Via the conditional above, we know that both `px` and `py` - // have the same length, so `px < pxend` implies that `py < pyend`. - // Thus, dereferencing both `px` and `py` in the loop below is safe. - // - // Moreover, we set `pxend` and `pyend` to be 4 bytes before the actual - // end of `px` and `py`. Thus, the final dereference outside of the - // loop is guaranteed to be valid. (The final comparison will overlap with - // the last comparison done in the loop for lengths that aren't multiples - // of four.) - // - // Finally, we needn't worry about alignment here, since we do unaligned - // loads. - unsafe { - let (mut px, mut py) = (x.as_ptr(), y.as_ptr()); - let (pxend, pyend) = (px.add(x.len() - 4), py.add(y.len() - 4)); - while px < pxend { - let vx = (px as *const u32).read_unaligned(); - let vy = (py as *const u32).read_unaligned(); - if vx != vy { - return false; - } - px = px.add(4); - py = py.add(4); - } - let vx = (pxend as *const u32).read_unaligned(); - let vy = (pyend as *const u32).read_unaligned(); - vx == vy - } -} diff --git a/library/core/src/str/traits.rs b/library/core/src/str/traits.rs deleted file mode 100644 index ba2d6f644962e..0000000000000 --- a/library/core/src/str/traits.rs +++ /dev/null @@ -1,674 +0,0 @@ -//! Trait implementations for `str`. - -use crate::cmp::Ordering; -use crate::intrinsics::unchecked_sub; -use crate::ops; -use crate::ptr; -use crate::slice::SliceIndex; -use crate::ub_checks::assert_unsafe_precondition; - -use super::ParseBoolError; - -/// Implements ordering of strings. -/// -/// Strings are ordered [lexicographically](Ord#lexicographical-comparison) by their byte values. This orders Unicode code -/// points based on their positions in the code charts. This is not necessarily the same as -/// "alphabetical" order, which varies by language and locale. Sorting strings according to -/// culturally-accepted standards requires locale-specific data that is outside the scope of -/// the `str` type. -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for str { - #[inline] - fn cmp(&self, other: &str) -> Ordering { - self.as_bytes().cmp(other.as_bytes()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for str { - #[inline] - fn eq(&self, other: &str) -> bool { - self.as_bytes() == other.as_bytes() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Eq for str {} - -/// Implements comparison operations on strings. -/// -/// Strings are compared [lexicographically](Ord#lexicographical-comparison) by their byte values. This compares Unicode code -/// points based on their positions in the code charts. This is not necessarily the same as -/// "alphabetical" order, which varies by language and locale. Comparing strings according to -/// culturally-accepted standards requires locale-specific data that is outside the scope of -/// the `str` type. -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialOrd for str { - #[inline] - fn partial_cmp(&self, other: &str) -> Option { - Some(self.cmp(other)) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ops::Index for str -where - I: SliceIndex, -{ - type Output = I::Output; - - #[inline] - fn index(&self, index: I) -> &I::Output { - index.index(self) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ops::IndexMut for str -where - I: SliceIndex, -{ - #[inline] - fn index_mut(&mut self, index: I) -> &mut I::Output { - index.index_mut(self) - } -} - -#[inline(never)] -#[cold] -#[track_caller] -const fn str_index_overflow_fail() -> ! { - panic!("attempted to index str up to maximum usize"); -} - -/// Implements substring slicing with syntax `&self[..]` or `&mut self[..]`. -/// -/// Returns a slice of the whole string, i.e., returns `&self` or `&mut -/// self`. Equivalent to `&self[0 .. len]` or `&mut self[0 .. len]`. Unlike -/// other indexing operations, this can never panic. -/// -/// This operation is *O*(1). -/// -/// Prior to 1.20.0, these indexing operations were still supported by -/// direct implementation of `Index` and `IndexMut`. -/// -/// Equivalent to `&self[0 .. len]` or `&mut self[0 .. len]`. -#[stable(feature = "str_checked_slicing", since = "1.20.0")] -#[rustc_const_unstable(feature = "const_slice_index", issue = "none")] -unsafe impl SliceIndex for ops::RangeFull { - type Output = str; - #[inline] - fn get(self, slice: &str) -> Option<&Self::Output> { - Some(slice) - } - #[inline] - fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> { - Some(slice) - } - #[inline] - unsafe fn get_unchecked(self, slice: *const str) -> *const Self::Output { - slice - } - #[inline] - unsafe fn get_unchecked_mut(self, slice: *mut str) -> *mut Self::Output { - slice - } - #[inline] - fn index(self, slice: &str) -> &Self::Output { - slice - } - #[inline] - fn index_mut(self, slice: &mut str) -> &mut Self::Output { - slice - } -} - -/// Implements substring slicing with syntax `&self[begin .. end]` or `&mut -/// self[begin .. end]`. -/// -/// Returns a slice of the given string from the byte range -/// [`begin`, `end`). -/// -/// This operation is *O*(1). -/// -/// Prior to 1.20.0, these indexing operations were still supported by -/// direct implementation of `Index` and `IndexMut`. -/// -/// # Panics -/// -/// Panics if `begin` or `end` does not point to the starting byte offset of -/// a character (as defined by `is_char_boundary`), if `begin > end`, or if -/// `end > len`. -/// -/// # Examples -/// -/// ``` -/// let s = "Löwe 老虎 Léopard"; -/// assert_eq!(&s[0 .. 1], "L"); -/// -/// assert_eq!(&s[1 .. 9], "öwe 老"); -/// -/// // these will panic: -/// // byte 2 lies within `ö`: -/// // &s[2 ..3]; -/// -/// // byte 8 lies within `老` -/// // &s[1 .. 8]; -/// -/// // byte 100 is outside the string -/// // &s[3 .. 100]; -/// ``` -#[stable(feature = "str_checked_slicing", since = "1.20.0")] -#[rustc_const_unstable(feature = "const_slice_index", issue = "none")] -unsafe impl SliceIndex for ops::Range { - type Output = str; - #[inline] - fn get(self, slice: &str) -> Option<&Self::Output> { - if self.start <= self.end - && slice.is_char_boundary(self.start) - && slice.is_char_boundary(self.end) - { - // SAFETY: just checked that `start` and `end` are on a char boundary, - // and we are passing in a safe reference, so the return value will also be one. - // We also checked char boundaries, so this is valid UTF-8. - Some(unsafe { &*self.get_unchecked(slice) }) - } else { - None - } - } - #[inline] - fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> { - if self.start <= self.end - && slice.is_char_boundary(self.start) - && slice.is_char_boundary(self.end) - { - // SAFETY: just checked that `start` and `end` are on a char boundary. - // We know the pointer is unique because we got it from `slice`. - Some(unsafe { &mut *self.get_unchecked_mut(slice) }) - } else { - None - } - } - #[inline] - unsafe fn get_unchecked(self, slice: *const str) -> *const Self::Output { - let slice = slice as *const [u8]; - - assert_unsafe_precondition!( - // We'd like to check that the bounds are on char boundaries, - // but there's not really a way to do so without reading - // behind the pointer, which has aliasing implications. - // It's also not possible to move this check up to - // `str::get_unchecked` without adding a special function - // to `SliceIndex` just for this. - check_library_ub, - "str::get_unchecked requires that the range is within the string slice", - ( - start: usize = self.start, - end: usize = self.end, - len: usize = slice.len() - ) => end >= start && end <= len, - ); - - // SAFETY: the caller guarantees that `self` is in bounds of `slice` - // which satisfies all the conditions for `add`. - unsafe { - let new_len = unchecked_sub(self.end, self.start); - ptr::slice_from_raw_parts(slice.as_ptr().add(self.start), new_len) as *const str - } - } - #[inline] - unsafe fn get_unchecked_mut(self, slice: *mut str) -> *mut Self::Output { - let slice = slice as *mut [u8]; - - assert_unsafe_precondition!( - check_library_ub, - "str::get_unchecked_mut requires that the range is within the string slice", - ( - start: usize = self.start, - end: usize = self.end, - len: usize = slice.len() - ) => end >= start && end <= len, - ); - - // SAFETY: see comments for `get_unchecked`. - unsafe { - let new_len = unchecked_sub(self.end, self.start); - ptr::slice_from_raw_parts_mut(slice.as_mut_ptr().add(self.start), new_len) as *mut str - } - } - #[inline] - fn index(self, slice: &str) -> &Self::Output { - let (start, end) = (self.start, self.end); - match self.get(slice) { - Some(s) => s, - None => super::slice_error_fail(slice, start, end), - } - } - #[inline] - fn index_mut(self, slice: &mut str) -> &mut Self::Output { - // is_char_boundary checks that the index is in [0, .len()] - // cannot reuse `get` as above, because of NLL trouble - if self.start <= self.end - && slice.is_char_boundary(self.start) - && slice.is_char_boundary(self.end) - { - // SAFETY: just checked that `start` and `end` are on a char boundary, - // and we are passing in a safe reference, so the return value will also be one. - unsafe { &mut *self.get_unchecked_mut(slice) } - } else { - super::slice_error_fail(slice, self.start, self.end) - } - } -} - -/// Implements substring slicing for arbitrary bounds. -/// -/// Returns a slice of the given string bounded by the byte indices -/// provided by each bound. -/// -/// This operation is *O*(1). -/// -/// # Panics -/// -/// Panics if `begin` or `end` (if it exists and once adjusted for -/// inclusion/exclusion) does not point to the starting byte offset of -/// a character (as defined by `is_char_boundary`), if `begin > end`, or if -/// `end > len`. -#[stable(feature = "slice_index_str_with_ops_bound_pair", since = "1.73.0")] -unsafe impl SliceIndex for (ops::Bound, ops::Bound) { - type Output = str; - - #[inline] - fn get(self, slice: &str) -> Option<&str> { - crate::slice::index::into_range(slice.len(), self)?.get(slice) - } - - #[inline] - fn get_mut(self, slice: &mut str) -> Option<&mut str> { - crate::slice::index::into_range(slice.len(), self)?.get_mut(slice) - } - - #[inline] - unsafe fn get_unchecked(self, slice: *const str) -> *const str { - let len = (slice as *const [u8]).len(); - // SAFETY: the caller has to uphold the safety contract for `get_unchecked`. - unsafe { crate::slice::index::into_range_unchecked(len, self).get_unchecked(slice) } - } - - #[inline] - unsafe fn get_unchecked_mut(self, slice: *mut str) -> *mut str { - let len = (slice as *mut [u8]).len(); - // SAFETY: the caller has to uphold the safety contract for `get_unchecked_mut`. - unsafe { crate::slice::index::into_range_unchecked(len, self).get_unchecked_mut(slice) } - } - - #[inline] - fn index(self, slice: &str) -> &str { - crate::slice::index::into_slice_range(slice.len(), self).index(slice) - } - - #[inline] - fn index_mut(self, slice: &mut str) -> &mut str { - crate::slice::index::into_slice_range(slice.len(), self).index_mut(slice) - } -} - -/// Implements substring slicing with syntax `&self[.. end]` or `&mut -/// self[.. end]`. -/// -/// Returns a slice of the given string from the byte range \[0, `end`). -/// Equivalent to `&self[0 .. end]` or `&mut self[0 .. end]`. -/// -/// This operation is *O*(1). -/// -/// Prior to 1.20.0, these indexing operations were still supported by -/// direct implementation of `Index` and `IndexMut`. -/// -/// # Panics -/// -/// Panics if `end` does not point to the starting byte offset of a -/// character (as defined by `is_char_boundary`), or if `end > len`. -#[stable(feature = "str_checked_slicing", since = "1.20.0")] -#[rustc_const_unstable(feature = "const_slice_index", issue = "none")] -unsafe impl SliceIndex for ops::RangeTo { - type Output = str; - #[inline] - fn get(self, slice: &str) -> Option<&Self::Output> { - if slice.is_char_boundary(self.end) { - // SAFETY: just checked that `end` is on a char boundary, - // and we are passing in a safe reference, so the return value will also be one. - Some(unsafe { &*self.get_unchecked(slice) }) - } else { - None - } - } - #[inline] - fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> { - if slice.is_char_boundary(self.end) { - // SAFETY: just checked that `end` is on a char boundary, - // and we are passing in a safe reference, so the return value will also be one. - Some(unsafe { &mut *self.get_unchecked_mut(slice) }) - } else { - None - } - } - #[inline] - unsafe fn get_unchecked(self, slice: *const str) -> *const Self::Output { - // SAFETY: the caller has to uphold the safety contract for `get_unchecked`. - unsafe { (0..self.end).get_unchecked(slice) } - } - #[inline] - unsafe fn get_unchecked_mut(self, slice: *mut str) -> *mut Self::Output { - // SAFETY: the caller has to uphold the safety contract for `get_unchecked_mut`. - unsafe { (0..self.end).get_unchecked_mut(slice) } - } - #[inline] - fn index(self, slice: &str) -> &Self::Output { - let end = self.end; - match self.get(slice) { - Some(s) => s, - None => super::slice_error_fail(slice, 0, end), - } - } - #[inline] - fn index_mut(self, slice: &mut str) -> &mut Self::Output { - if slice.is_char_boundary(self.end) { - // SAFETY: just checked that `end` is on a char boundary, - // and we are passing in a safe reference, so the return value will also be one. - unsafe { &mut *self.get_unchecked_mut(slice) } - } else { - super::slice_error_fail(slice, 0, self.end) - } - } -} - -/// Implements substring slicing with syntax `&self[begin ..]` or `&mut -/// self[begin ..]`. -/// -/// Returns a slice of the given string from the byte range \[`begin`, `len`). -/// Equivalent to `&self[begin .. len]` or `&mut self[begin .. len]`. -/// -/// This operation is *O*(1). -/// -/// Prior to 1.20.0, these indexing operations were still supported by -/// direct implementation of `Index` and `IndexMut`. -/// -/// # Panics -/// -/// Panics if `begin` does not point to the starting byte offset of -/// a character (as defined by `is_char_boundary`), or if `begin > len`. -#[stable(feature = "str_checked_slicing", since = "1.20.0")] -#[rustc_const_unstable(feature = "const_slice_index", issue = "none")] -unsafe impl SliceIndex for ops::RangeFrom { - type Output = str; - #[inline] - fn get(self, slice: &str) -> Option<&Self::Output> { - if slice.is_char_boundary(self.start) { - // SAFETY: just checked that `start` is on a char boundary, - // and we are passing in a safe reference, so the return value will also be one. - Some(unsafe { &*self.get_unchecked(slice) }) - } else { - None - } - } - #[inline] - fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> { - if slice.is_char_boundary(self.start) { - // SAFETY: just checked that `start` is on a char boundary, - // and we are passing in a safe reference, so the return value will also be one. - Some(unsafe { &mut *self.get_unchecked_mut(slice) }) - } else { - None - } - } - #[inline] - unsafe fn get_unchecked(self, slice: *const str) -> *const Self::Output { - let len = (slice as *const [u8]).len(); - // SAFETY: the caller has to uphold the safety contract for `get_unchecked`. - unsafe { (self.start..len).get_unchecked(slice) } - } - #[inline] - unsafe fn get_unchecked_mut(self, slice: *mut str) -> *mut Self::Output { - let len = (slice as *mut [u8]).len(); - // SAFETY: the caller has to uphold the safety contract for `get_unchecked_mut`. - unsafe { (self.start..len).get_unchecked_mut(slice) } - } - #[inline] - fn index(self, slice: &str) -> &Self::Output { - let (start, end) = (self.start, slice.len()); - match self.get(slice) { - Some(s) => s, - None => super::slice_error_fail(slice, start, end), - } - } - #[inline] - fn index_mut(self, slice: &mut str) -> &mut Self::Output { - if slice.is_char_boundary(self.start) { - // SAFETY: just checked that `start` is on a char boundary, - // and we are passing in a safe reference, so the return value will also be one. - unsafe { &mut *self.get_unchecked_mut(slice) } - } else { - super::slice_error_fail(slice, self.start, slice.len()) - } - } -} - -/// Implements substring slicing with syntax `&self[begin ..= end]` or `&mut -/// self[begin ..= end]`. -/// -/// Returns a slice of the given string from the byte range -/// [`begin`, `end`]. Equivalent to `&self [begin .. end + 1]` or `&mut -/// self[begin .. end + 1]`, except if `end` has the maximum value for -/// `usize`. -/// -/// This operation is *O*(1). -/// -/// # Panics -/// -/// Panics if `begin` does not point to the starting byte offset of -/// a character (as defined by `is_char_boundary`), if `end` does not point -/// to the ending byte offset of a character (`end + 1` is either a starting -/// byte offset or equal to `len`), if `begin > end`, or if `end >= len`. -#[stable(feature = "inclusive_range", since = "1.26.0")] -#[rustc_const_unstable(feature = "const_slice_index", issue = "none")] -unsafe impl SliceIndex for ops::RangeInclusive { - type Output = str; - #[inline] - fn get(self, slice: &str) -> Option<&Self::Output> { - if *self.end() == usize::MAX { None } else { self.into_slice_range().get(slice) } - } - #[inline] - fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> { - if *self.end() == usize::MAX { None } else { self.into_slice_range().get_mut(slice) } - } - #[inline] - unsafe fn get_unchecked(self, slice: *const str) -> *const Self::Output { - // SAFETY: the caller must uphold the safety contract for `get_unchecked`. - unsafe { self.into_slice_range().get_unchecked(slice) } - } - #[inline] - unsafe fn get_unchecked_mut(self, slice: *mut str) -> *mut Self::Output { - // SAFETY: the caller must uphold the safety contract for `get_unchecked_mut`. - unsafe { self.into_slice_range().get_unchecked_mut(slice) } - } - #[inline] - fn index(self, slice: &str) -> &Self::Output { - if *self.end() == usize::MAX { - str_index_overflow_fail(); - } - self.into_slice_range().index(slice) - } - #[inline] - fn index_mut(self, slice: &mut str) -> &mut Self::Output { - if *self.end() == usize::MAX { - str_index_overflow_fail(); - } - self.into_slice_range().index_mut(slice) - } -} - -/// Implements substring slicing with syntax `&self[..= end]` or `&mut -/// self[..= end]`. -/// -/// Returns a slice of the given string from the byte range \[0, `end`\]. -/// Equivalent to `&self [0 .. end + 1]`, except if `end` has the maximum -/// value for `usize`. -/// -/// This operation is *O*(1). -/// -/// # Panics -/// -/// Panics if `end` does not point to the ending byte offset of a character -/// (`end + 1` is either a starting byte offset as defined by -/// `is_char_boundary`, or equal to `len`), or if `end >= len`. -#[stable(feature = "inclusive_range", since = "1.26.0")] -#[rustc_const_unstable(feature = "const_slice_index", issue = "none")] -unsafe impl SliceIndex for ops::RangeToInclusive { - type Output = str; - #[inline] - fn get(self, slice: &str) -> Option<&Self::Output> { - (0..=self.end).get(slice) - } - #[inline] - fn get_mut(self, slice: &mut str) -> Option<&mut Self::Output> { - (0..=self.end).get_mut(slice) - } - #[inline] - unsafe fn get_unchecked(self, slice: *const str) -> *const Self::Output { - // SAFETY: the caller must uphold the safety contract for `get_unchecked`. - unsafe { (0..=self.end).get_unchecked(slice) } - } - #[inline] - unsafe fn get_unchecked_mut(self, slice: *mut str) -> *mut Self::Output { - // SAFETY: the caller must uphold the safety contract for `get_unchecked_mut`. - unsafe { (0..=self.end).get_unchecked_mut(slice) } - } - #[inline] - fn index(self, slice: &str) -> &Self::Output { - (0..=self.end).index(slice) - } - #[inline] - fn index_mut(self, slice: &mut str) -> &mut Self::Output { - (0..=self.end).index_mut(slice) - } -} - -/// Parse a value from a string -/// -/// `FromStr`'s [`from_str`] method is often used implicitly, through -/// [`str`]'s [`parse`] method. See [`parse`]'s documentation for examples. -/// -/// [`from_str`]: FromStr::from_str -/// [`parse`]: str::parse -/// -/// `FromStr` does not have a lifetime parameter, and so you can only parse types -/// that do not contain a lifetime parameter themselves. In other words, you can -/// parse an `i32` with `FromStr`, but not a `&i32`. You can parse a struct that -/// contains an `i32`, but not one that contains an `&i32`. -/// -/// # Examples -/// -/// Basic implementation of `FromStr` on an example `Point` type: -/// -/// ``` -/// use std::str::FromStr; -/// -/// #[derive(Debug, PartialEq)] -/// struct Point { -/// x: i32, -/// y: i32 -/// } -/// -/// #[derive(Debug, PartialEq, Eq)] -/// struct ParsePointError; -/// -/// impl FromStr for Point { -/// type Err = ParsePointError; -/// -/// fn from_str(s: &str) -> Result { -/// let (x, y) = s -/// .strip_prefix('(') -/// .and_then(|s| s.strip_suffix(')')) -/// .and_then(|s| s.split_once(',')) -/// .ok_or(ParsePointError)?; -/// -/// let x_fromstr = x.parse::().map_err(|_| ParsePointError)?; -/// let y_fromstr = y.parse::().map_err(|_| ParsePointError)?; -/// -/// Ok(Point { x: x_fromstr, y: y_fromstr }) -/// } -/// } -/// -/// let expected = Ok(Point { x: 1, y: 2 }); -/// // Explicit call -/// assert_eq!(Point::from_str("(1,2)"), expected); -/// // Implicit calls, through parse -/// assert_eq!("(1,2)".parse(), expected); -/// assert_eq!("(1,2)".parse::(), expected); -/// // Invalid input string -/// assert!(Point::from_str("(1 2)").is_err()); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub trait FromStr: Sized { - /// The associated error which can be returned from parsing. - #[stable(feature = "rust1", since = "1.0.0")] - type Err; - - /// Parses a string `s` to return a value of this type. - /// - /// If parsing succeeds, return the value inside [`Ok`], otherwise - /// when the string is ill-formatted return an error specific to the - /// inside [`Err`]. The error type is specific to the implementation of the trait. - /// - /// # Examples - /// - /// Basic usage with [`i32`], a type that implements `FromStr`: - /// - /// ``` - /// use std::str::FromStr; - /// - /// let s = "5"; - /// let x = i32::from_str(s).unwrap(); - /// - /// assert_eq!(5, x); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_diagnostic_item = "from_str_method"] - fn from_str(s: &str) -> Result; -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl FromStr for bool { - type Err = ParseBoolError; - - /// Parse a `bool` from a string. - /// - /// The only accepted values are `"true"` and `"false"`. Any other input - /// will return an error. - /// - /// # Examples - /// - /// ``` - /// use std::str::FromStr; - /// - /// assert_eq!(FromStr::from_str("true"), Ok(true)); - /// assert_eq!(FromStr::from_str("false"), Ok(false)); - /// assert!(::from_str("not even a boolean").is_err()); - /// ``` - /// - /// Note, in many cases, the `.parse()` method on `str` is more proper. - /// - /// ``` - /// assert_eq!("true".parse(), Ok(true)); - /// assert_eq!("false".parse(), Ok(false)); - /// assert!("not even a boolean".parse::().is_err()); - /// ``` - #[inline] - fn from_str(s: &str) -> Result { - match s { - "true" => Ok(true), - "false" => Ok(false), - _ => Err(ParseBoolError), - } - } -} diff --git a/library/core/src/str/validations.rs b/library/core/src/str/validations.rs deleted file mode 100644 index a11d7fee8af0c..0000000000000 --- a/library/core/src/str/validations.rs +++ /dev/null @@ -1,274 +0,0 @@ -//! Operations related to UTF-8 validation. - -use crate::mem; - -use super::Utf8Error; - -/// Returns the initial codepoint accumulator for the first byte. -/// The first byte is special, only want bottom 5 bits for width 2, 4 bits -/// for width 3, and 3 bits for width 4. -#[inline] -const fn utf8_first_byte(byte: u8, width: u32) -> u32 { - (byte & (0x7F >> width)) as u32 -} - -/// Returns the value of `ch` updated with continuation byte `byte`. -#[inline] -const fn utf8_acc_cont_byte(ch: u32, byte: u8) -> u32 { - (ch << 6) | (byte & CONT_MASK) as u32 -} - -/// Checks whether the byte is a UTF-8 continuation byte (i.e., starts with the -/// bits `10`). -#[inline] -pub(super) const fn utf8_is_cont_byte(byte: u8) -> bool { - (byte as i8) < -64 -} - -/// Reads the next code point out of a byte iterator (assuming a -/// UTF-8-like encoding). -/// -/// # Safety -/// -/// `bytes` must produce a valid UTF-8-like (UTF-8 or WTF-8) string -#[unstable(feature = "str_internals", issue = "none")] -#[inline] -pub unsafe fn next_code_point<'a, I: Iterator>(bytes: &mut I) -> Option { - // Decode UTF-8 - let x = *bytes.next()?; - if x < 128 { - return Some(x as u32); - } - - // Multibyte case follows - // Decode from a byte combination out of: [[[x y] z] w] - // NOTE: Performance is sensitive to the exact formulation here - let init = utf8_first_byte(x, 2); - // SAFETY: `bytes` produces an UTF-8-like string, - // so the iterator must produce a value here. - let y = unsafe { *bytes.next().unwrap_unchecked() }; - let mut ch = utf8_acc_cont_byte(init, y); - if x >= 0xE0 { - // [[x y z] w] case - // 5th bit in 0xE0 .. 0xEF is always clear, so `init` is still valid - // SAFETY: `bytes` produces an UTF-8-like string, - // so the iterator must produce a value here. - let z = unsafe { *bytes.next().unwrap_unchecked() }; - let y_z = utf8_acc_cont_byte((y & CONT_MASK) as u32, z); - ch = init << 12 | y_z; - if x >= 0xF0 { - // [x y z w] case - // use only the lower 3 bits of `init` - // SAFETY: `bytes` produces an UTF-8-like string, - // so the iterator must produce a value here. - let w = unsafe { *bytes.next().unwrap_unchecked() }; - ch = (init & 7) << 18 | utf8_acc_cont_byte(y_z, w); - } - } - - Some(ch) -} - -/// Reads the last code point out of a byte iterator (assuming a -/// UTF-8-like encoding). -/// -/// # Safety -/// -/// `bytes` must produce a valid UTF-8-like (UTF-8 or WTF-8) string -#[inline] -pub(super) unsafe fn next_code_point_reverse<'a, I>(bytes: &mut I) -> Option -where - I: DoubleEndedIterator, -{ - // Decode UTF-8 - let w = match *bytes.next_back()? { - next_byte if next_byte < 128 => return Some(next_byte as u32), - back_byte => back_byte, - }; - - // Multibyte case follows - // Decode from a byte combination out of: [x [y [z w]]] - let mut ch; - // SAFETY: `bytes` produces an UTF-8-like string, - // so the iterator must produce a value here. - let z = unsafe { *bytes.next_back().unwrap_unchecked() }; - ch = utf8_first_byte(z, 2); - if utf8_is_cont_byte(z) { - // SAFETY: `bytes` produces an UTF-8-like string, - // so the iterator must produce a value here. - let y = unsafe { *bytes.next_back().unwrap_unchecked() }; - ch = utf8_first_byte(y, 3); - if utf8_is_cont_byte(y) { - // SAFETY: `bytes` produces an UTF-8-like string, - // so the iterator must produce a value here. - let x = unsafe { *bytes.next_back().unwrap_unchecked() }; - ch = utf8_first_byte(x, 4); - ch = utf8_acc_cont_byte(ch, y); - } - ch = utf8_acc_cont_byte(ch, z); - } - ch = utf8_acc_cont_byte(ch, w); - - Some(ch) -} - -const NONASCII_MASK: usize = usize::repeat_u8(0x80); - -/// Returns `true` if any byte in the word `x` is nonascii (>= 128). -#[inline] -const fn contains_nonascii(x: usize) -> bool { - (x & NONASCII_MASK) != 0 -} - -/// Walks through `v` checking that it's a valid UTF-8 sequence, -/// returning `Ok(())` in that case, or, if it is invalid, `Err(err)`. -#[inline(always)] -#[rustc_const_unstable(feature = "str_internals", issue = "none")] -pub(super) const fn run_utf8_validation(v: &[u8]) -> Result<(), Utf8Error> { - let mut index = 0; - let len = v.len(); - - let usize_bytes = mem::size_of::(); - let ascii_block_size = 2 * usize_bytes; - let blocks_end = if len >= ascii_block_size { len - ascii_block_size + 1 } else { 0 }; - let align = v.as_ptr().align_offset(usize_bytes); - - while index < len { - let old_offset = index; - macro_rules! err { - ($error_len: expr) => { - return Err(Utf8Error { valid_up_to: old_offset, error_len: $error_len }) - }; - } - - macro_rules! next { - () => {{ - index += 1; - // we needed data, but there was none: error! - if index >= len { - err!(None) - } - v[index] - }}; - } - - let first = v[index]; - if first >= 128 { - let w = utf8_char_width(first); - // 2-byte encoding is for codepoints \u{0080} to \u{07ff} - // first C2 80 last DF BF - // 3-byte encoding is for codepoints \u{0800} to \u{ffff} - // first E0 A0 80 last EF BF BF - // excluding surrogates codepoints \u{d800} to \u{dfff} - // ED A0 80 to ED BF BF - // 4-byte encoding is for codepoints \u{10000} to \u{10ffff} - // first F0 90 80 80 last F4 8F BF BF - // - // Use the UTF-8 syntax from the RFC - // - // https://tools.ietf.org/html/rfc3629 - // UTF8-1 = %x00-7F - // UTF8-2 = %xC2-DF UTF8-tail - // UTF8-3 = %xE0 %xA0-BF UTF8-tail / %xE1-EC 2( UTF8-tail ) / - // %xED %x80-9F UTF8-tail / %xEE-EF 2( UTF8-tail ) - // UTF8-4 = %xF0 %x90-BF 2( UTF8-tail ) / %xF1-F3 3( UTF8-tail ) / - // %xF4 %x80-8F 2( UTF8-tail ) - match w { - 2 => { - if next!() as i8 >= -64 { - err!(Some(1)) - } - } - 3 => { - match (first, next!()) { - (0xE0, 0xA0..=0xBF) - | (0xE1..=0xEC, 0x80..=0xBF) - | (0xED, 0x80..=0x9F) - | (0xEE..=0xEF, 0x80..=0xBF) => {} - _ => err!(Some(1)), - } - if next!() as i8 >= -64 { - err!(Some(2)) - } - } - 4 => { - match (first, next!()) { - (0xF0, 0x90..=0xBF) | (0xF1..=0xF3, 0x80..=0xBF) | (0xF4, 0x80..=0x8F) => {} - _ => err!(Some(1)), - } - if next!() as i8 >= -64 { - err!(Some(2)) - } - if next!() as i8 >= -64 { - err!(Some(3)) - } - } - _ => err!(Some(1)), - } - index += 1; - } else { - // Ascii case, try to skip forward quickly. - // When the pointer is aligned, read 2 words of data per iteration - // until we find a word containing a non-ascii byte. - if align != usize::MAX && align.wrapping_sub(index) % usize_bytes == 0 { - let ptr = v.as_ptr(); - while index < blocks_end { - // SAFETY: since `align - index` and `ascii_block_size` are - // multiples of `usize_bytes`, `block = ptr.add(index)` is - // always aligned with a `usize` so it's safe to dereference - // both `block` and `block.add(1)`. - unsafe { - let block = ptr.add(index) as *const usize; - // break if there is a nonascii byte - let zu = contains_nonascii(*block); - let zv = contains_nonascii(*block.add(1)); - if zu || zv { - break; - } - } - index += ascii_block_size; - } - // step from the point where the wordwise loop stopped - while index < len && v[index] < 128 { - index += 1; - } - } else { - index += 1; - } - } - } - - Ok(()) -} - -// https://tools.ietf.org/html/rfc3629 -const UTF8_CHAR_WIDTH: &[u8; 256] = &[ - // 1 2 3 4 5 6 7 8 9 A B C D E F - 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, // 0 - 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, // 1 - 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, // 2 - 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, // 3 - 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, // 4 - 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, // 5 - 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, // 6 - 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, // 7 - 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 8 - 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // 9 - 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // A - 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // B - 0, 0, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, // C - 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, 2, // D - 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, 3, // E - 4, 4, 4, 4, 4, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, // F -]; - -/// Given a first byte, determines how many bytes are in this UTF-8 character. -#[unstable(feature = "str_internals", issue = "none")] -#[must_use] -#[inline] -pub const fn utf8_char_width(b: u8) -> usize { - UTF8_CHAR_WIDTH[b as usize] as usize -} - -/// Mask of the value bits of a continuation byte. -const CONT_MASK: u8 = 0b0011_1111; diff --git a/library/core/src/sync/atomic.rs b/library/core/src/sync/atomic.rs deleted file mode 100644 index 232ec589093d3..0000000000000 --- a/library/core/src/sync/atomic.rs +++ /dev/null @@ -1,3770 +0,0 @@ -//! Atomic types -//! -//! Atomic types provide primitive shared-memory communication between -//! threads, and are the building blocks of other concurrent -//! types. -//! -//! This module defines atomic versions of a select number of primitive -//! types, including [`AtomicBool`], [`AtomicIsize`], [`AtomicUsize`], -//! [`AtomicI8`], [`AtomicU16`], etc. -//! Atomic types present operations that, when used correctly, synchronize -//! updates between threads. -//! -//! Atomic variables are safe to share between threads (they implement [`Sync`]) -//! but they do not themselves provide the mechanism for sharing and follow the -//! [threading model](../../../std/thread/index.html#the-threading-model) of Rust. -//! The most common way to share an atomic variable is to put it into an [`Arc`][arc] (an -//! atomically-reference-counted shared pointer). -//! -//! [arc]: ../../../std/sync/struct.Arc.html -//! -//! Atomic types may be stored in static variables, initialized using -//! the constant initializers like [`AtomicBool::new`]. Atomic statics -//! are often used for lazy global initialization. -//! -//! ## Memory model for atomic accesses -//! -//! Rust atomics currently follow the same rules as [C++20 atomics][cpp], specifically `atomic_ref`. -//! Basically, creating a *shared reference* to one of the Rust atomic types corresponds to creating -//! an `atomic_ref` in C++; the `atomic_ref` is destroyed when the lifetime of the shared reference -//! ends. A Rust atomic type that is exclusively owned or behind a mutable reference does *not* -//! correspond to an “atomic object” in C++, since the underlying primitive can be mutably accessed, -//! for example with `get_mut`, to perform non-atomic operations. -//! -//! [cpp]: https://en.cppreference.com/w/cpp/atomic -//! -//! Each method takes an [`Ordering`] which represents the strength of -//! the memory barrier for that operation. These orderings are the -//! same as the [C++20 atomic orderings][1]. For more information see the [nomicon][2]. -//! -//! [1]: https://en.cppreference.com/w/cpp/atomic/memory_order -//! [2]: ../../../nomicon/atomics.html -//! -//! Since C++ does not support mixing atomic and non-atomic accesses, or non-synchronized -//! different-sized accesses to the same data, Rust does not support those operations either. -//! Note that both of those restrictions only apply if the accesses are non-synchronized. -//! -//! ```rust,no_run undefined_behavior -//! use std::sync::atomic::{AtomicU16, AtomicU8, Ordering}; -//! use std::mem::transmute; -//! use std::thread; -//! -//! let atomic = AtomicU16::new(0); -//! -//! thread::scope(|s| { -//! // This is UB: mixing atomic and non-atomic accesses -//! s.spawn(|| atomic.store(1, Ordering::Relaxed)); -//! s.spawn(|| unsafe { atomic.as_ptr().write(2) }); -//! }); -//! -//! thread::scope(|s| { -//! // This is UB: even reads are not allowed to be mixed -//! s.spawn(|| atomic.load(Ordering::Relaxed)); -//! s.spawn(|| unsafe { atomic.as_ptr().read() }); -//! }); -//! -//! thread::scope(|s| { -//! // This is fine, `join` synchronizes the code in a way such that atomic -//! // and non-atomic accesses can't happen "at the same time" -//! let handle = s.spawn(|| atomic.store(1, Ordering::Relaxed)); -//! handle.join().unwrap(); -//! s.spawn(|| unsafe { atomic.as_ptr().write(2) }); -//! }); -//! -//! thread::scope(|s| { -//! // This is UB: using different-sized atomic accesses to the same data -//! s.spawn(|| atomic.store(1, Ordering::Relaxed)); -//! s.spawn(|| unsafe { -//! let differently_sized = transmute::<&AtomicU16, &AtomicU8>(&atomic); -//! differently_sized.store(2, Ordering::Relaxed); -//! }); -//! }); -//! -//! thread::scope(|s| { -//! // This is fine, `join` synchronizes the code in a way such that -//! // differently-sized accesses can't happen "at the same time" -//! let handle = s.spawn(|| atomic.store(1, Ordering::Relaxed)); -//! handle.join().unwrap(); -//! s.spawn(|| unsafe { -//! let differently_sized = transmute::<&AtomicU16, &AtomicU8>(&atomic); -//! differently_sized.store(2, Ordering::Relaxed); -//! }); -//! }); -//! ``` -//! -//! # Portability -//! -//! All atomic types in this module are guaranteed to be [lock-free] if they're -//! available. This means they don't internally acquire a global mutex. Atomic -//! types and operations are not guaranteed to be wait-free. This means that -//! operations like `fetch_or` may be implemented with a compare-and-swap loop. -//! -//! Atomic operations may be implemented at the instruction layer with -//! larger-size atomics. For example some platforms use 4-byte atomic -//! instructions to implement `AtomicI8`. Note that this emulation should not -//! have an impact on correctness of code, it's just something to be aware of. -//! -//! The atomic types in this module might not be available on all platforms. The -//! atomic types here are all widely available, however, and can generally be -//! relied upon existing. Some notable exceptions are: -//! -//! * PowerPC and MIPS platforms with 32-bit pointers do not have `AtomicU64` or -//! `AtomicI64` types. -//! * ARM platforms like `armv5te` that aren't for Linux only provide `load` -//! and `store` operations, and do not support Compare and Swap (CAS) -//! operations, such as `swap`, `fetch_add`, etc. Additionally on Linux, -//! these CAS operations are implemented via [operating system support], which -//! may come with a performance penalty. -//! * ARM targets with `thumbv6m` only provide `load` and `store` operations, -//! and do not support Compare and Swap (CAS) operations, such as `swap`, -//! `fetch_add`, etc. -//! -//! [operating system support]: https://www.kernel.org/doc/Documentation/arm/kernel_user_helpers.txt -//! -//! Note that future platforms may be added that also do not have support for -//! some atomic operations. Maximally portable code will want to be careful -//! about which atomic types are used. `AtomicUsize` and `AtomicIsize` are -//! generally the most portable, but even then they're not available everywhere. -//! For reference, the `std` library requires `AtomicBool`s and pointer-sized atomics, although -//! `core` does not. -//! -//! The `#[cfg(target_has_atomic)]` attribute can be used to conditionally -//! compile based on the target's supported bit widths. It is a key-value -//! option set for each supported size, with values "8", "16", "32", "64", -//! "128", and "ptr" for pointer-sized atomics. -//! -//! [lock-free]: https://en.wikipedia.org/wiki/Non-blocking_algorithm -//! -//! # Atomic accesses to read-only memory -//! -//! In general, *all* atomic accesses on read-only memory are Undefined Behavior. For instance, attempting -//! to do a `compare_exchange` that will definitely fail (making it conceptually a read-only -//! operation) can still cause a segmentation fault if the underlying memory page is mapped read-only. Since -//! atomic `load`s might be implemented using compare-exchange operations, even a `load` can fault -//! on read-only memory. -//! -//! For the purpose of this section, "read-only memory" is defined as memory that is read-only in -//! the underlying target, i.e., the pages are mapped with a read-only flag and any attempt to write -//! will cause a page fault. In particular, an `&u128` reference that points to memory that is -//! read-write mapped is *not* considered to point to "read-only memory". In Rust, almost all memory -//! is read-write; the only exceptions are memory created by `const` items or `static` items without -//! interior mutability, and memory that was specifically marked as read-only by the operating -//! system via platform-specific APIs. -//! -//! As an exception from the general rule stated above, "sufficiently small" atomic loads with -//! `Ordering::Relaxed` are implemented in a way that works on read-only memory, and are hence not -//! Undefined Behavior. The exact size limit for what makes a load "sufficiently small" varies -//! depending on the target: -//! -//! | `target_arch` | Size limit | -//! |---------------|---------| -//! | `x86`, `arm`, `mips`, `mips32r6`, `powerpc`, `riscv32`, `sparc`, `hexagon` | 4 bytes | -//! | `x86_64`, `aarch64`, `loongarch64`, `mips64`, `mips64r6`, `powerpc64`, `riscv64`, `sparc64`, `s390x` | 8 bytes | -//! -//! Atomics loads that are larger than this limit as well as atomic loads with ordering other -//! than `Relaxed`, as well as *all* atomic loads on targets not listed in the table, might still be -//! read-only under certain conditions, but that is not a stable guarantee and should not be relied -//! upon. -//! -//! If you need to do an acquire load on read-only memory, you can do a relaxed load followed by an -//! acquire fence instead. -//! -//! # Examples -//! -//! A simple spinlock: -//! -//! ``` -//! use std::sync::Arc; -//! use std::sync::atomic::{AtomicUsize, Ordering}; -//! use std::{hint, thread}; -//! -//! fn main() { -//! let spinlock = Arc::new(AtomicUsize::new(1)); -//! -//! let spinlock_clone = Arc::clone(&spinlock); -//! -//! let thread = thread::spawn(move|| { -//! spinlock_clone.store(0, Ordering::Release); -//! }); -//! -//! // Wait for the other thread to release the lock -//! while spinlock.load(Ordering::Acquire) != 0 { -//! hint::spin_loop(); -//! } -//! -//! if let Err(panic) = thread.join() { -//! println!("Thread had an error: {panic:?}"); -//! } -//! } -//! ``` -//! -//! Keep a global count of live threads: -//! -//! ``` -//! use std::sync::atomic::{AtomicUsize, Ordering}; -//! -//! static GLOBAL_THREAD_COUNT: AtomicUsize = AtomicUsize::new(0); -//! -//! // Note that Relaxed ordering doesn't synchronize anything -//! // except the global thread counter itself. -//! let old_thread_count = GLOBAL_THREAD_COUNT.fetch_add(1, Ordering::Relaxed); -//! // Note that this number may not be true at the moment of printing -//! // because some other thread may have changed static value already. -//! println!("live threads: {}", old_thread_count + 1); -//! ``` - -#![stable(feature = "rust1", since = "1.0.0")] -#![cfg_attr(not(target_has_atomic_load_store = "8"), allow(dead_code))] -#![cfg_attr(not(target_has_atomic_load_store = "8"), allow(unused_imports))] -#![rustc_diagnostic_item = "atomic_mod"] -// Clippy complains about the pattern of "safe function calling unsafe function taking pointers". -// This happens with AtomicPtr intrinsics but is fine, as the pointers clippy is concerned about -// are just normal values that get loaded/stored, but not dereferenced. -#![allow(clippy::not_unsafe_ptr_arg_deref)] - -use self::Ordering::*; - -use crate::cell::UnsafeCell; -use crate::fmt; -use crate::intrinsics; - -use crate::hint::spin_loop; - -// Some architectures don't have byte-sized atomics, which results in LLVM -// emulating them using a LL/SC loop. However for AtomicBool we can take -// advantage of the fact that it only ever contains 0 or 1 and use atomic OR/AND -// instead, which LLVM can emulate using a larger atomic OR/AND operation. -// -// This list should only contain architectures which have word-sized atomic-or/ -// atomic-and instructions but don't natively support byte-sized atomics. -#[cfg(target_has_atomic = "8")] -const EMULATE_ATOMIC_BOOL: bool = - cfg!(any(target_arch = "riscv32", target_arch = "riscv64", target_arch = "loongarch64")); - -/// A boolean type which can be safely shared between threads. -/// -/// This type has the same size, alignment, and bit validity as a [`bool`]. -/// -/// **Note**: This type is only available on platforms that support atomic -/// loads and stores of `u8`. -#[cfg(target_has_atomic_load_store = "8")] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_diagnostic_item = "AtomicBool"] -#[repr(C, align(1))] -pub struct AtomicBool { - v: UnsafeCell, -} - -#[cfg(target_has_atomic_load_store = "8")] -#[stable(feature = "rust1", since = "1.0.0")] -impl Default for AtomicBool { - /// Creates an `AtomicBool` initialized to `false`. - #[inline] - fn default() -> Self { - Self::new(false) - } -} - -// Send is implicitly implemented for AtomicBool. -#[cfg(target_has_atomic_load_store = "8")] -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Sync for AtomicBool {} - -/// A raw pointer type which can be safely shared between threads. -/// -/// This type has the same size and bit validity as a `*mut T`. -/// -/// **Note**: This type is only available on platforms that support atomic -/// loads and stores of pointers. Its size depends on the target pointer's size. -#[cfg(target_has_atomic_load_store = "ptr")] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "AtomicPtr")] -#[cfg_attr(target_pointer_width = "16", repr(C, align(2)))] -#[cfg_attr(target_pointer_width = "32", repr(C, align(4)))] -#[cfg_attr(target_pointer_width = "64", repr(C, align(8)))] -pub struct AtomicPtr { - p: UnsafeCell<*mut T>, -} - -#[cfg(target_has_atomic_load_store = "ptr")] -#[stable(feature = "rust1", since = "1.0.0")] -impl Default for AtomicPtr { - /// Creates a null `AtomicPtr`. - fn default() -> AtomicPtr { - AtomicPtr::new(crate::ptr::null_mut()) - } -} - -#[cfg(target_has_atomic_load_store = "ptr")] -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Send for AtomicPtr {} -#[cfg(target_has_atomic_load_store = "ptr")] -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Sync for AtomicPtr {} - -/// Atomic memory orderings -/// -/// Memory orderings specify the way atomic operations synchronize memory. -/// In its weakest [`Ordering::Relaxed`], only the memory directly touched by the -/// operation is synchronized. On the other hand, a store-load pair of [`Ordering::SeqCst`] -/// operations synchronize other memory while additionally preserving a total order of such -/// operations across all threads. -/// -/// Rust's memory orderings are [the same as those of -/// C++20](https://en.cppreference.com/w/cpp/atomic/memory_order). -/// -/// For more information see the [nomicon]. -/// -/// [nomicon]: ../../../nomicon/atomics.html -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Copy, Clone, Debug, Eq, PartialEq, Hash)] -#[non_exhaustive] -#[rustc_diagnostic_item = "Ordering"] -pub enum Ordering { - /// No ordering constraints, only atomic operations. - /// - /// Corresponds to [`memory_order_relaxed`] in C++20. - /// - /// [`memory_order_relaxed`]: https://en.cppreference.com/w/cpp/atomic/memory_order#Relaxed_ordering - #[stable(feature = "rust1", since = "1.0.0")] - Relaxed, - /// When coupled with a store, all previous operations become ordered - /// before any load of this value with [`Acquire`] (or stronger) ordering. - /// In particular, all previous writes become visible to all threads - /// that perform an [`Acquire`] (or stronger) load of this value. - /// - /// Notice that using this ordering for an operation that combines loads - /// and stores leads to a [`Relaxed`] load operation! - /// - /// This ordering is only applicable for operations that can perform a store. - /// - /// Corresponds to [`memory_order_release`] in C++20. - /// - /// [`memory_order_release`]: https://en.cppreference.com/w/cpp/atomic/memory_order#Release-Acquire_ordering - #[stable(feature = "rust1", since = "1.0.0")] - Release, - /// When coupled with a load, if the loaded value was written by a store operation with - /// [`Release`] (or stronger) ordering, then all subsequent operations - /// become ordered after that store. In particular, all subsequent loads will see data - /// written before the store. - /// - /// Notice that using this ordering for an operation that combines loads - /// and stores leads to a [`Relaxed`] store operation! - /// - /// This ordering is only applicable for operations that can perform a load. - /// - /// Corresponds to [`memory_order_acquire`] in C++20. - /// - /// [`memory_order_acquire`]: https://en.cppreference.com/w/cpp/atomic/memory_order#Release-Acquire_ordering - #[stable(feature = "rust1", since = "1.0.0")] - Acquire, - /// Has the effects of both [`Acquire`] and [`Release`] together: - /// For loads it uses [`Acquire`] ordering. For stores it uses the [`Release`] ordering. - /// - /// Notice that in the case of `compare_and_swap`, it is possible that the operation ends up - /// not performing any store and hence it has just [`Acquire`] ordering. However, - /// `AcqRel` will never perform [`Relaxed`] accesses. - /// - /// This ordering is only applicable for operations that combine both loads and stores. - /// - /// Corresponds to [`memory_order_acq_rel`] in C++20. - /// - /// [`memory_order_acq_rel`]: https://en.cppreference.com/w/cpp/atomic/memory_order#Release-Acquire_ordering - #[stable(feature = "rust1", since = "1.0.0")] - AcqRel, - /// Like [`Acquire`]/[`Release`]/[`AcqRel`] (for load, store, and load-with-store - /// operations, respectively) with the additional guarantee that all threads see all - /// sequentially consistent operations in the same order. - /// - /// Corresponds to [`memory_order_seq_cst`] in C++20. - /// - /// [`memory_order_seq_cst`]: https://en.cppreference.com/w/cpp/atomic/memory_order#Sequentially-consistent_ordering - #[stable(feature = "rust1", since = "1.0.0")] - SeqCst, -} - -/// An [`AtomicBool`] initialized to `false`. -#[cfg(target_has_atomic_load_store = "8")] -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated( - since = "1.34.0", - note = "the `new` function is now preferred", - suggestion = "AtomicBool::new(false)" -)] -pub const ATOMIC_BOOL_INIT: AtomicBool = AtomicBool::new(false); - -#[cfg(target_has_atomic_load_store = "8")] -impl AtomicBool { - /// Creates a new `AtomicBool`. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::AtomicBool; - /// - /// let atomic_true = AtomicBool::new(true); - /// let atomic_false = AtomicBool::new(false); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_atomic_new", since = "1.24.0")] - #[must_use] - pub const fn new(v: bool) -> AtomicBool { - AtomicBool { v: UnsafeCell::new(v as u8) } - } - - /// Creates a new `AtomicBool` from a pointer. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::{self, AtomicBool}; - /// - /// // Get a pointer to an allocated value - /// let ptr: *mut bool = Box::into_raw(Box::new(false)); - /// - /// assert!(ptr.cast::().is_aligned()); - /// - /// { - /// // Create an atomic view of the allocated value - /// let atomic = unsafe { AtomicBool::from_ptr(ptr) }; - /// - /// // Use `atomic` for atomic operations, possibly share it with other threads - /// atomic.store(true, atomic::Ordering::Relaxed); - /// } - /// - /// // It's ok to non-atomically access the value behind `ptr`, - /// // since the reference to the atomic ended its lifetime in the block above - /// assert_eq!(unsafe { *ptr }, true); - /// - /// // Deallocate the value - /// unsafe { drop(Box::from_raw(ptr)) } - /// ``` - /// - /// # Safety - /// - /// * `ptr` must be aligned to `align_of::()` (note that on some platforms this can - /// be bigger than `align_of::()`). - /// * `ptr` must be [valid] for both reads and writes for the whole lifetime `'a`. - /// * You must adhere to the [Memory model for atomic accesses]. In particular, it is not - /// allowed to mix atomic and non-atomic accesses, or atomic accesses of different sizes, - /// without synchronization. - /// - /// [valid]: crate::ptr#safety - /// [Memory model for atomic accesses]: self#memory-model-for-atomic-accesses - #[stable(feature = "atomic_from_ptr", since = "1.75.0")] - #[rustc_const_unstable(feature = "const_atomic_from_ptr", issue = "108652")] - pub const unsafe fn from_ptr<'a>(ptr: *mut bool) -> &'a AtomicBool { - // SAFETY: guaranteed by the caller - unsafe { &*ptr.cast() } - } - - /// Returns a mutable reference to the underlying [`bool`]. - /// - /// This is safe because the mutable reference guarantees that no other threads are - /// concurrently accessing the atomic data. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::{AtomicBool, Ordering}; - /// - /// let mut some_bool = AtomicBool::new(true); - /// assert_eq!(*some_bool.get_mut(), true); - /// *some_bool.get_mut() = false; - /// assert_eq!(some_bool.load(Ordering::SeqCst), false); - /// ``` - #[inline] - #[stable(feature = "atomic_access", since = "1.15.0")] - pub fn get_mut(&mut self) -> &mut bool { - // SAFETY: the mutable reference guarantees unique ownership. - unsafe { &mut *(self.v.get() as *mut bool) } - } - - /// Get atomic access to a `&mut bool`. - /// - /// # Examples - /// - /// ``` - /// #![feature(atomic_from_mut)] - /// use std::sync::atomic::{AtomicBool, Ordering}; - /// - /// let mut some_bool = true; - /// let a = AtomicBool::from_mut(&mut some_bool); - /// a.store(false, Ordering::Relaxed); - /// assert_eq!(some_bool, false); - /// ``` - #[inline] - #[cfg(target_has_atomic_equal_alignment = "8")] - #[unstable(feature = "atomic_from_mut", issue = "76314")] - pub fn from_mut(v: &mut bool) -> &mut Self { - // SAFETY: the mutable reference guarantees unique ownership, and - // alignment of both `bool` and `Self` is 1. - unsafe { &mut *(v as *mut bool as *mut Self) } - } - - /// Get non-atomic access to a `&mut [AtomicBool]` slice. - /// - /// This is safe because the mutable reference guarantees that no other threads are - /// concurrently accessing the atomic data. - /// - /// # Examples - /// - /// ``` - /// #![feature(atomic_from_mut)] - /// use std::sync::atomic::{AtomicBool, Ordering}; - /// - /// let mut some_bools = [const { AtomicBool::new(false) }; 10]; - /// - /// let view: &mut [bool] = AtomicBool::get_mut_slice(&mut some_bools); - /// assert_eq!(view, [false; 10]); - /// view[..5].copy_from_slice(&[true; 5]); - /// - /// std::thread::scope(|s| { - /// for t in &some_bools[..5] { - /// s.spawn(move || assert_eq!(t.load(Ordering::Relaxed), true)); - /// } - /// - /// for f in &some_bools[5..] { - /// s.spawn(move || assert_eq!(f.load(Ordering::Relaxed), false)); - /// } - /// }); - /// ``` - #[inline] - #[unstable(feature = "atomic_from_mut", issue = "76314")] - pub fn get_mut_slice(this: &mut [Self]) -> &mut [bool] { - // SAFETY: the mutable reference guarantees unique ownership. - unsafe { &mut *(this as *mut [Self] as *mut [bool]) } - } - - /// Get atomic access to a `&mut [bool]` slice. - /// - /// # Examples - /// - /// ``` - /// #![feature(atomic_from_mut)] - /// use std::sync::atomic::{AtomicBool, Ordering}; - /// - /// let mut some_bools = [false; 10]; - /// let a = &*AtomicBool::from_mut_slice(&mut some_bools); - /// std::thread::scope(|s| { - /// for i in 0..a.len() { - /// s.spawn(move || a[i].store(true, Ordering::Relaxed)); - /// } - /// }); - /// assert_eq!(some_bools, [true; 10]); - /// ``` - #[inline] - #[cfg(target_has_atomic_equal_alignment = "8")] - #[unstable(feature = "atomic_from_mut", issue = "76314")] - pub fn from_mut_slice(v: &mut [bool]) -> &mut [Self] { - // SAFETY: the mutable reference guarantees unique ownership, and - // alignment of both `bool` and `Self` is 1. - unsafe { &mut *(v as *mut [bool] as *mut [Self]) } - } - - /// Consumes the atomic and returns the contained value. - /// - /// This is safe because passing `self` by value guarantees that no other threads are - /// concurrently accessing the atomic data. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::AtomicBool; - /// - /// let some_bool = AtomicBool::new(true); - /// assert_eq!(some_bool.into_inner(), true); - /// ``` - #[inline] - #[stable(feature = "atomic_access", since = "1.15.0")] - #[rustc_const_stable(feature = "const_atomic_into_inner", since = "1.79.0")] - pub const fn into_inner(self) -> bool { - self.v.primitive_into_inner() != 0 - } - - /// Loads a value from the bool. - /// - /// `load` takes an [`Ordering`] argument which describes the memory ordering - /// of this operation. Possible values are [`SeqCst`], [`Acquire`] and [`Relaxed`]. - /// - /// # Panics - /// - /// Panics if `order` is [`Release`] or [`AcqRel`]. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::{AtomicBool, Ordering}; - /// - /// let some_bool = AtomicBool::new(true); - /// - /// assert_eq!(some_bool.load(Ordering::Relaxed), true); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn load(&self, order: Ordering) -> bool { - // SAFETY: any data races are prevented by atomic intrinsics and the raw - // pointer passed in is valid because we got it from a reference. - unsafe { atomic_load(self.v.get(), order) != 0 } - } - - /// Stores a value into the bool. - /// - /// `store` takes an [`Ordering`] argument which describes the memory ordering - /// of this operation. Possible values are [`SeqCst`], [`Release`] and [`Relaxed`]. - /// - /// # Panics - /// - /// Panics if `order` is [`Acquire`] or [`AcqRel`]. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::{AtomicBool, Ordering}; - /// - /// let some_bool = AtomicBool::new(true); - /// - /// some_bool.store(false, Ordering::Relaxed); - /// assert_eq!(some_bool.load(Ordering::Relaxed), false); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn store(&self, val: bool, order: Ordering) { - // SAFETY: any data races are prevented by atomic intrinsics and the raw - // pointer passed in is valid because we got it from a reference. - unsafe { - atomic_store(self.v.get(), val as u8, order); - } - } - - /// Stores a value into the bool, returning the previous value. - /// - /// `swap` takes an [`Ordering`] argument which describes the memory ordering - /// of this operation. All ordering modes are possible. Note that using - /// [`Acquire`] makes the store part of this operation [`Relaxed`], and - /// using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note:** This method is only available on platforms that support atomic - /// operations on `u8`. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::{AtomicBool, Ordering}; - /// - /// let some_bool = AtomicBool::new(true); - /// - /// assert_eq!(some_bool.swap(false, Ordering::Relaxed), true); - /// assert_eq!(some_bool.load(Ordering::Relaxed), false); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[cfg(target_has_atomic = "8")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn swap(&self, val: bool, order: Ordering) -> bool { - if EMULATE_ATOMIC_BOOL { - if val { self.fetch_or(true, order) } else { self.fetch_and(false, order) } - } else { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { atomic_swap(self.v.get(), val as u8, order) != 0 } - } - } - - /// Stores a value into the [`bool`] if the current value is the same as the `current` value. - /// - /// The return value is always the previous value. If it is equal to `current`, then the value - /// was updated. - /// - /// `compare_and_swap` also takes an [`Ordering`] argument which describes the memory - /// ordering of this operation. Notice that even when using [`AcqRel`], the operation - /// might fail and hence just perform an `Acquire` load, but not have `Release` semantics. - /// Using [`Acquire`] makes the store part of this operation [`Relaxed`] if it - /// happens, and using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note:** This method is only available on platforms that support atomic - /// operations on `u8`. - /// - /// # Migrating to `compare_exchange` and `compare_exchange_weak` - /// - /// `compare_and_swap` is equivalent to `compare_exchange` with the following mapping for - /// memory orderings: - /// - /// Original | Success | Failure - /// -------- | ------- | ------- - /// Relaxed | Relaxed | Relaxed - /// Acquire | Acquire | Acquire - /// Release | Release | Relaxed - /// AcqRel | AcqRel | Acquire - /// SeqCst | SeqCst | SeqCst - /// - /// `compare_exchange_weak` is allowed to fail spuriously even when the comparison succeeds, - /// which allows the compiler to generate better assembly code when the compare and swap - /// is used in a loop. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::{AtomicBool, Ordering}; - /// - /// let some_bool = AtomicBool::new(true); - /// - /// assert_eq!(some_bool.compare_and_swap(true, false, Ordering::Relaxed), true); - /// assert_eq!(some_bool.load(Ordering::Relaxed), false); - /// - /// assert_eq!(some_bool.compare_and_swap(true, true, Ordering::Relaxed), false); - /// assert_eq!(some_bool.load(Ordering::Relaxed), false); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[deprecated( - since = "1.50.0", - note = "Use `compare_exchange` or `compare_exchange_weak` instead" - )] - #[cfg(target_has_atomic = "8")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn compare_and_swap(&self, current: bool, new: bool, order: Ordering) -> bool { - match self.compare_exchange(current, new, order, strongest_failure_ordering(order)) { - Ok(x) => x, - Err(x) => x, - } - } - - /// Stores a value into the [`bool`] if the current value is the same as the `current` value. - /// - /// The return value is a result indicating whether the new value was written and containing - /// the previous value. On success this value is guaranteed to be equal to `current`. - /// - /// `compare_exchange` takes two [`Ordering`] arguments to describe the memory - /// ordering of this operation. `success` describes the required ordering for the - /// read-modify-write operation that takes place if the comparison with `current` succeeds. - /// `failure` describes the required ordering for the load operation that takes place when - /// the comparison fails. Using [`Acquire`] as success ordering makes the store part - /// of this operation [`Relaxed`], and using [`Release`] makes the successful load - /// [`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`]. - /// - /// **Note:** This method is only available on platforms that support atomic - /// operations on `u8`. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::{AtomicBool, Ordering}; - /// - /// let some_bool = AtomicBool::new(true); - /// - /// assert_eq!(some_bool.compare_exchange(true, - /// false, - /// Ordering::Acquire, - /// Ordering::Relaxed), - /// Ok(true)); - /// assert_eq!(some_bool.load(Ordering::Relaxed), false); - /// - /// assert_eq!(some_bool.compare_exchange(true, true, - /// Ordering::SeqCst, - /// Ordering::Acquire), - /// Err(false)); - /// assert_eq!(some_bool.load(Ordering::Relaxed), false); - /// ``` - #[inline] - #[stable(feature = "extended_compare_and_swap", since = "1.10.0")] - #[doc(alias = "compare_and_swap")] - #[cfg(target_has_atomic = "8")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn compare_exchange( - &self, - current: bool, - new: bool, - success: Ordering, - failure: Ordering, - ) -> Result { - if EMULATE_ATOMIC_BOOL { - // Pick the strongest ordering from success and failure. - let order = match (success, failure) { - (SeqCst, _) => SeqCst, - (_, SeqCst) => SeqCst, - (AcqRel, _) => AcqRel, - (_, AcqRel) => { - panic!("there is no such thing as an acquire-release failure ordering") - } - (Release, Acquire) => AcqRel, - (Acquire, _) => Acquire, - (_, Acquire) => Acquire, - (Release, Relaxed) => Release, - (_, Release) => panic!("there is no such thing as a release failure ordering"), - (Relaxed, Relaxed) => Relaxed, - }; - let old = if current == new { - // This is a no-op, but we still need to perform the operation - // for memory ordering reasons. - self.fetch_or(false, order) - } else { - // This sets the value to the new one and returns the old one. - self.swap(new, order) - }; - if old == current { Ok(old) } else { Err(old) } - } else { - // SAFETY: data races are prevented by atomic intrinsics. - match unsafe { - atomic_compare_exchange(self.v.get(), current as u8, new as u8, success, failure) - } { - Ok(x) => Ok(x != 0), - Err(x) => Err(x != 0), - } - } - } - - /// Stores a value into the [`bool`] if the current value is the same as the `current` value. - /// - /// Unlike [`AtomicBool::compare_exchange`], this function is allowed to spuriously fail even when the - /// comparison succeeds, which can result in more efficient code on some platforms. The - /// return value is a result indicating whether the new value was written and containing the - /// previous value. - /// - /// `compare_exchange_weak` takes two [`Ordering`] arguments to describe the memory - /// ordering of this operation. `success` describes the required ordering for the - /// read-modify-write operation that takes place if the comparison with `current` succeeds. - /// `failure` describes the required ordering for the load operation that takes place when - /// the comparison fails. Using [`Acquire`] as success ordering makes the store part - /// of this operation [`Relaxed`], and using [`Release`] makes the successful load - /// [`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`]. - /// - /// **Note:** This method is only available on platforms that support atomic - /// operations on `u8`. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::{AtomicBool, Ordering}; - /// - /// let val = AtomicBool::new(false); - /// - /// let new = true; - /// let mut old = val.load(Ordering::Relaxed); - /// loop { - /// match val.compare_exchange_weak(old, new, Ordering::SeqCst, Ordering::Relaxed) { - /// Ok(_) => break, - /// Err(x) => old = x, - /// } - /// } - /// ``` - #[inline] - #[stable(feature = "extended_compare_and_swap", since = "1.10.0")] - #[doc(alias = "compare_and_swap")] - #[cfg(target_has_atomic = "8")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn compare_exchange_weak( - &self, - current: bool, - new: bool, - success: Ordering, - failure: Ordering, - ) -> Result { - if EMULATE_ATOMIC_BOOL { - return self.compare_exchange(current, new, success, failure); - } - - // SAFETY: data races are prevented by atomic intrinsics. - match unsafe { - atomic_compare_exchange_weak(self.v.get(), current as u8, new as u8, success, failure) - } { - Ok(x) => Ok(x != 0), - Err(x) => Err(x != 0), - } - } - - /// Logical "and" with a boolean value. - /// - /// Performs a logical "and" operation on the current value and the argument `val`, and sets - /// the new value to the result. - /// - /// Returns the previous value. - /// - /// `fetch_and` takes an [`Ordering`] argument which describes the memory ordering - /// of this operation. All ordering modes are possible. Note that using - /// [`Acquire`] makes the store part of this operation [`Relaxed`], and - /// using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note:** This method is only available on platforms that support atomic - /// operations on `u8`. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::{AtomicBool, Ordering}; - /// - /// let foo = AtomicBool::new(true); - /// assert_eq!(foo.fetch_and(false, Ordering::SeqCst), true); - /// assert_eq!(foo.load(Ordering::SeqCst), false); - /// - /// let foo = AtomicBool::new(true); - /// assert_eq!(foo.fetch_and(true, Ordering::SeqCst), true); - /// assert_eq!(foo.load(Ordering::SeqCst), true); - /// - /// let foo = AtomicBool::new(false); - /// assert_eq!(foo.fetch_and(false, Ordering::SeqCst), false); - /// assert_eq!(foo.load(Ordering::SeqCst), false); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[cfg(target_has_atomic = "8")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn fetch_and(&self, val: bool, order: Ordering) -> bool { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { atomic_and(self.v.get(), val as u8, order) != 0 } - } - - /// Logical "nand" with a boolean value. - /// - /// Performs a logical "nand" operation on the current value and the argument `val`, and sets - /// the new value to the result. - /// - /// Returns the previous value. - /// - /// `fetch_nand` takes an [`Ordering`] argument which describes the memory ordering - /// of this operation. All ordering modes are possible. Note that using - /// [`Acquire`] makes the store part of this operation [`Relaxed`], and - /// using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note:** This method is only available on platforms that support atomic - /// operations on `u8`. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::{AtomicBool, Ordering}; - /// - /// let foo = AtomicBool::new(true); - /// assert_eq!(foo.fetch_nand(false, Ordering::SeqCst), true); - /// assert_eq!(foo.load(Ordering::SeqCst), true); - /// - /// let foo = AtomicBool::new(true); - /// assert_eq!(foo.fetch_nand(true, Ordering::SeqCst), true); - /// assert_eq!(foo.load(Ordering::SeqCst) as usize, 0); - /// assert_eq!(foo.load(Ordering::SeqCst), false); - /// - /// let foo = AtomicBool::new(false); - /// assert_eq!(foo.fetch_nand(false, Ordering::SeqCst), false); - /// assert_eq!(foo.load(Ordering::SeqCst), true); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[cfg(target_has_atomic = "8")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn fetch_nand(&self, val: bool, order: Ordering) -> bool { - // We can't use atomic_nand here because it can result in a bool with - // an invalid value. This happens because the atomic operation is done - // with an 8-bit integer internally, which would set the upper 7 bits. - // So we just use fetch_xor or swap instead. - if val { - // !(x & true) == !x - // We must invert the bool. - self.fetch_xor(true, order) - } else { - // !(x & false) == true - // We must set the bool to true. - self.swap(true, order) - } - } - - /// Logical "or" with a boolean value. - /// - /// Performs a logical "or" operation on the current value and the argument `val`, and sets the - /// new value to the result. - /// - /// Returns the previous value. - /// - /// `fetch_or` takes an [`Ordering`] argument which describes the memory ordering - /// of this operation. All ordering modes are possible. Note that using - /// [`Acquire`] makes the store part of this operation [`Relaxed`], and - /// using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note:** This method is only available on platforms that support atomic - /// operations on `u8`. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::{AtomicBool, Ordering}; - /// - /// let foo = AtomicBool::new(true); - /// assert_eq!(foo.fetch_or(false, Ordering::SeqCst), true); - /// assert_eq!(foo.load(Ordering::SeqCst), true); - /// - /// let foo = AtomicBool::new(true); - /// assert_eq!(foo.fetch_or(true, Ordering::SeqCst), true); - /// assert_eq!(foo.load(Ordering::SeqCst), true); - /// - /// let foo = AtomicBool::new(false); - /// assert_eq!(foo.fetch_or(false, Ordering::SeqCst), false); - /// assert_eq!(foo.load(Ordering::SeqCst), false); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[cfg(target_has_atomic = "8")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn fetch_or(&self, val: bool, order: Ordering) -> bool { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { atomic_or(self.v.get(), val as u8, order) != 0 } - } - - /// Logical "xor" with a boolean value. - /// - /// Performs a logical "xor" operation on the current value and the argument `val`, and sets - /// the new value to the result. - /// - /// Returns the previous value. - /// - /// `fetch_xor` takes an [`Ordering`] argument which describes the memory ordering - /// of this operation. All ordering modes are possible. Note that using - /// [`Acquire`] makes the store part of this operation [`Relaxed`], and - /// using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note:** This method is only available on platforms that support atomic - /// operations on `u8`. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::{AtomicBool, Ordering}; - /// - /// let foo = AtomicBool::new(true); - /// assert_eq!(foo.fetch_xor(false, Ordering::SeqCst), true); - /// assert_eq!(foo.load(Ordering::SeqCst), true); - /// - /// let foo = AtomicBool::new(true); - /// assert_eq!(foo.fetch_xor(true, Ordering::SeqCst), true); - /// assert_eq!(foo.load(Ordering::SeqCst), false); - /// - /// let foo = AtomicBool::new(false); - /// assert_eq!(foo.fetch_xor(false, Ordering::SeqCst), false); - /// assert_eq!(foo.load(Ordering::SeqCst), false); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[cfg(target_has_atomic = "8")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn fetch_xor(&self, val: bool, order: Ordering) -> bool { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { atomic_xor(self.v.get(), val as u8, order) != 0 } - } - - /// Logical "not" with a boolean value. - /// - /// Performs a logical "not" operation on the current value, and sets - /// the new value to the result. - /// - /// Returns the previous value. - /// - /// `fetch_not` takes an [`Ordering`] argument which describes the memory ordering - /// of this operation. All ordering modes are possible. Note that using - /// [`Acquire`] makes the store part of this operation [`Relaxed`], and - /// using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note:** This method is only available on platforms that support atomic - /// operations on `u8`. - /// - /// # Examples - /// - /// ``` - /// #![feature(atomic_bool_fetch_not)] - /// use std::sync::atomic::{AtomicBool, Ordering}; - /// - /// let foo = AtomicBool::new(true); - /// assert_eq!(foo.fetch_not(Ordering::SeqCst), true); - /// assert_eq!(foo.load(Ordering::SeqCst), false); - /// - /// let foo = AtomicBool::new(false); - /// assert_eq!(foo.fetch_not(Ordering::SeqCst), false); - /// assert_eq!(foo.load(Ordering::SeqCst), true); - /// ``` - #[inline] - #[unstable(feature = "atomic_bool_fetch_not", issue = "98485")] - #[cfg(target_has_atomic = "8")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn fetch_not(&self, order: Ordering) -> bool { - self.fetch_xor(true, order) - } - - /// Returns a mutable pointer to the underlying [`bool`]. - /// - /// Doing non-atomic reads and writes on the resulting boolean can be a data race. - /// This method is mostly useful for FFI, where the function signature may use - /// `*mut bool` instead of `&AtomicBool`. - /// - /// Returning an `*mut` pointer from a shared reference to this atomic is safe because the - /// atomic types work with interior mutability. All modifications of an atomic change the value - /// through a shared reference, and can do so safely as long as they use atomic operations. Any - /// use of the returned raw pointer requires an `unsafe` block and still has to uphold the same - /// restriction: operations on it must be atomic. - /// - /// # Examples - /// - /// ```ignore (extern-declaration) - /// # fn main() { - /// use std::sync::atomic::AtomicBool; - /// - /// extern "C" { - /// fn my_atomic_op(arg: *mut bool); - /// } - /// - /// let mut atomic = AtomicBool::new(true); - /// unsafe { - /// my_atomic_op(atomic.as_ptr()); - /// } - /// # } - /// ``` - #[inline] - #[stable(feature = "atomic_as_ptr", since = "1.70.0")] - #[rustc_const_stable(feature = "atomic_as_ptr", since = "1.70.0")] - #[rustc_never_returns_null_ptr] - pub const fn as_ptr(&self) -> *mut bool { - self.v.get().cast() - } - - /// Fetches the value, and applies a function to it that returns an optional - /// new value. Returns a `Result` of `Ok(previous_value)` if the function - /// returned `Some(_)`, else `Err(previous_value)`. - /// - /// Note: This may call the function multiple times if the value has been - /// changed from other threads in the meantime, as long as the function - /// returns `Some(_)`, but the function will have been applied only once to - /// the stored value. - /// - /// `fetch_update` takes two [`Ordering`] arguments to describe the memory - /// ordering of this operation. The first describes the required ordering for - /// when the operation finally succeeds while the second describes the - /// required ordering for loads. These correspond to the success and failure - /// orderings of [`AtomicBool::compare_exchange`] respectively. - /// - /// Using [`Acquire`] as success ordering makes the store part of this - /// operation [`Relaxed`], and using [`Release`] makes the final successful - /// load [`Relaxed`]. The (failed) load ordering can only be [`SeqCst`], - /// [`Acquire`] or [`Relaxed`]. - /// - /// **Note:** This method is only available on platforms that support atomic - /// operations on `u8`. - /// - /// # Considerations - /// - /// This method is not magic; it is not provided by the hardware. - /// It is implemented in terms of [`AtomicBool::compare_exchange_weak`], and suffers from the same drawbacks. - /// In particular, this method will not circumvent the [ABA Problem]. - /// - /// [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem - /// - /// # Examples - /// - /// ```rust - /// use std::sync::atomic::{AtomicBool, Ordering}; - /// - /// let x = AtomicBool::new(false); - /// assert_eq!(x.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |_| None), Err(false)); - /// assert_eq!(x.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |x| Some(!x)), Ok(false)); - /// assert_eq!(x.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |x| Some(!x)), Ok(true)); - /// assert_eq!(x.load(Ordering::SeqCst), false); - /// ``` - #[inline] - #[stable(feature = "atomic_fetch_update", since = "1.53.0")] - #[cfg(target_has_atomic = "8")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn fetch_update( - &self, - set_order: Ordering, - fetch_order: Ordering, - mut f: F, - ) -> Result - where - F: FnMut(bool) -> Option, - { - let mut prev = self.load(fetch_order); - while let Some(next) = f(prev) { - match self.compare_exchange_weak(prev, next, set_order, fetch_order) { - x @ Ok(_) => return x, - Err(next_prev) => prev = next_prev, - } - } - Err(prev) - } -} - -#[cfg(target_has_atomic_load_store = "ptr")] -impl AtomicPtr { - /// Creates a new `AtomicPtr`. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::AtomicPtr; - /// - /// let ptr = &mut 5; - /// let atomic_ptr = AtomicPtr::new(ptr); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_atomic_new", since = "1.24.0")] - pub const fn new(p: *mut T) -> AtomicPtr { - AtomicPtr { p: UnsafeCell::new(p) } - } - - /// Creates a new `AtomicPtr` from a pointer. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::{self, AtomicPtr}; - /// - /// // Get a pointer to an allocated value - /// let ptr: *mut *mut u8 = Box::into_raw(Box::new(std::ptr::null_mut())); - /// - /// assert!(ptr.cast::>().is_aligned()); - /// - /// { - /// // Create an atomic view of the allocated value - /// let atomic = unsafe { AtomicPtr::from_ptr(ptr) }; - /// - /// // Use `atomic` for atomic operations, possibly share it with other threads - /// atomic.store(std::ptr::NonNull::dangling().as_ptr(), atomic::Ordering::Relaxed); - /// } - /// - /// // It's ok to non-atomically access the value behind `ptr`, - /// // since the reference to the atomic ended its lifetime in the block above - /// assert!(!unsafe { *ptr }.is_null()); - /// - /// // Deallocate the value - /// unsafe { drop(Box::from_raw(ptr)) } - /// ``` - /// - /// # Safety - /// - /// * `ptr` must be aligned to `align_of::>()` (note that on some platforms this - /// can be bigger than `align_of::<*mut T>()`). - /// * `ptr` must be [valid] for both reads and writes for the whole lifetime `'a`. - /// * You must adhere to the [Memory model for atomic accesses]. In particular, it is not - /// allowed to mix atomic and non-atomic accesses, or atomic accesses of different sizes, - /// without synchronization. - /// - /// [valid]: crate::ptr#safety - /// [Memory model for atomic accesses]: self#memory-model-for-atomic-accesses - #[stable(feature = "atomic_from_ptr", since = "1.75.0")] - #[rustc_const_unstable(feature = "const_atomic_from_ptr", issue = "108652")] - pub const unsafe fn from_ptr<'a>(ptr: *mut *mut T) -> &'a AtomicPtr { - // SAFETY: guaranteed by the caller - unsafe { &*ptr.cast() } - } - - /// Returns a mutable reference to the underlying pointer. - /// - /// This is safe because the mutable reference guarantees that no other threads are - /// concurrently accessing the atomic data. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::{AtomicPtr, Ordering}; - /// - /// let mut data = 10; - /// let mut atomic_ptr = AtomicPtr::new(&mut data); - /// let mut other_data = 5; - /// *atomic_ptr.get_mut() = &mut other_data; - /// assert_eq!(unsafe { *atomic_ptr.load(Ordering::SeqCst) }, 5); - /// ``` - #[inline] - #[stable(feature = "atomic_access", since = "1.15.0")] - pub fn get_mut(&mut self) -> &mut *mut T { - self.p.get_mut() - } - - /// Get atomic access to a pointer. - /// - /// # Examples - /// - /// ``` - /// #![feature(atomic_from_mut)] - /// use std::sync::atomic::{AtomicPtr, Ordering}; - /// - /// let mut data = 123; - /// let mut some_ptr = &mut data as *mut i32; - /// let a = AtomicPtr::from_mut(&mut some_ptr); - /// let mut other_data = 456; - /// a.store(&mut other_data, Ordering::Relaxed); - /// assert_eq!(unsafe { *some_ptr }, 456); - /// ``` - #[inline] - #[cfg(target_has_atomic_equal_alignment = "ptr")] - #[unstable(feature = "atomic_from_mut", issue = "76314")] - pub fn from_mut(v: &mut *mut T) -> &mut Self { - use crate::mem::align_of; - let [] = [(); align_of::>() - align_of::<*mut ()>()]; - // SAFETY: - // - the mutable reference guarantees unique ownership. - // - the alignment of `*mut T` and `Self` is the same on all platforms - // supported by rust, as verified above. - unsafe { &mut *(v as *mut *mut T as *mut Self) } - } - - /// Get non-atomic access to a `&mut [AtomicPtr]` slice. - /// - /// This is safe because the mutable reference guarantees that no other threads are - /// concurrently accessing the atomic data. - /// - /// # Examples - /// - /// ``` - /// #![feature(atomic_from_mut)] - /// use std::ptr::null_mut; - /// use std::sync::atomic::{AtomicPtr, Ordering}; - /// - /// let mut some_ptrs = [const { AtomicPtr::new(null_mut::()) }; 10]; - /// - /// let view: &mut [*mut String] = AtomicPtr::get_mut_slice(&mut some_ptrs); - /// assert_eq!(view, [null_mut::(); 10]); - /// view - /// .iter_mut() - /// .enumerate() - /// .for_each(|(i, ptr)| *ptr = Box::into_raw(Box::new(format!("iteration#{i}")))); - /// - /// std::thread::scope(|s| { - /// for ptr in &some_ptrs { - /// s.spawn(move || { - /// let ptr = ptr.load(Ordering::Relaxed); - /// assert!(!ptr.is_null()); - /// - /// let name = unsafe { Box::from_raw(ptr) }; - /// println!("Hello, {name}!"); - /// }); - /// } - /// }); - /// ``` - #[inline] - #[unstable(feature = "atomic_from_mut", issue = "76314")] - pub fn get_mut_slice(this: &mut [Self]) -> &mut [*mut T] { - // SAFETY: the mutable reference guarantees unique ownership. - unsafe { &mut *(this as *mut [Self] as *mut [*mut T]) } - } - - /// Get atomic access to a slice of pointers. - /// - /// # Examples - /// - /// ``` - /// #![feature(atomic_from_mut)] - /// use std::ptr::null_mut; - /// use std::sync::atomic::{AtomicPtr, Ordering}; - /// - /// let mut some_ptrs = [null_mut::(); 10]; - /// let a = &*AtomicPtr::from_mut_slice(&mut some_ptrs); - /// std::thread::scope(|s| { - /// for i in 0..a.len() { - /// s.spawn(move || { - /// let name = Box::new(format!("thread{i}")); - /// a[i].store(Box::into_raw(name), Ordering::Relaxed); - /// }); - /// } - /// }); - /// for p in some_ptrs { - /// assert!(!p.is_null()); - /// let name = unsafe { Box::from_raw(p) }; - /// println!("Hello, {name}!"); - /// } - /// ``` - #[inline] - #[cfg(target_has_atomic_equal_alignment = "ptr")] - #[unstable(feature = "atomic_from_mut", issue = "76314")] - pub fn from_mut_slice(v: &mut [*mut T]) -> &mut [Self] { - // SAFETY: - // - the mutable reference guarantees unique ownership. - // - the alignment of `*mut T` and `Self` is the same on all platforms - // supported by rust, as verified above. - unsafe { &mut *(v as *mut [*mut T] as *mut [Self]) } - } - - /// Consumes the atomic and returns the contained value. - /// - /// This is safe because passing `self` by value guarantees that no other threads are - /// concurrently accessing the atomic data. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::AtomicPtr; - /// - /// let mut data = 5; - /// let atomic_ptr = AtomicPtr::new(&mut data); - /// assert_eq!(unsafe { *atomic_ptr.into_inner() }, 5); - /// ``` - #[inline] - #[stable(feature = "atomic_access", since = "1.15.0")] - #[rustc_const_stable(feature = "const_atomic_into_inner", since = "1.79.0")] - pub const fn into_inner(self) -> *mut T { - self.p.primitive_into_inner() - } - - /// Loads a value from the pointer. - /// - /// `load` takes an [`Ordering`] argument which describes the memory ordering - /// of this operation. Possible values are [`SeqCst`], [`Acquire`] and [`Relaxed`]. - /// - /// # Panics - /// - /// Panics if `order` is [`Release`] or [`AcqRel`]. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::{AtomicPtr, Ordering}; - /// - /// let ptr = &mut 5; - /// let some_ptr = AtomicPtr::new(ptr); - /// - /// let value = some_ptr.load(Ordering::Relaxed); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn load(&self, order: Ordering) -> *mut T { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { atomic_load(self.p.get(), order) } - } - - /// Stores a value into the pointer. - /// - /// `store` takes an [`Ordering`] argument which describes the memory ordering - /// of this operation. Possible values are [`SeqCst`], [`Release`] and [`Relaxed`]. - /// - /// # Panics - /// - /// Panics if `order` is [`Acquire`] or [`AcqRel`]. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::{AtomicPtr, Ordering}; - /// - /// let ptr = &mut 5; - /// let some_ptr = AtomicPtr::new(ptr); - /// - /// let other_ptr = &mut 10; - /// - /// some_ptr.store(other_ptr, Ordering::Relaxed); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn store(&self, ptr: *mut T, order: Ordering) { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { - atomic_store(self.p.get(), ptr, order); - } - } - - /// Stores a value into the pointer, returning the previous value. - /// - /// `swap` takes an [`Ordering`] argument which describes the memory ordering - /// of this operation. All ordering modes are possible. Note that using - /// [`Acquire`] makes the store part of this operation [`Relaxed`], and - /// using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note:** This method is only available on platforms that support atomic - /// operations on pointers. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::{AtomicPtr, Ordering}; - /// - /// let ptr = &mut 5; - /// let some_ptr = AtomicPtr::new(ptr); - /// - /// let other_ptr = &mut 10; - /// - /// let value = some_ptr.swap(other_ptr, Ordering::Relaxed); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[cfg(target_has_atomic = "ptr")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn swap(&self, ptr: *mut T, order: Ordering) -> *mut T { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { atomic_swap(self.p.get(), ptr, order) } - } - - /// Stores a value into the pointer if the current value is the same as the `current` value. - /// - /// The return value is always the previous value. If it is equal to `current`, then the value - /// was updated. - /// - /// `compare_and_swap` also takes an [`Ordering`] argument which describes the memory - /// ordering of this operation. Notice that even when using [`AcqRel`], the operation - /// might fail and hence just perform an `Acquire` load, but not have `Release` semantics. - /// Using [`Acquire`] makes the store part of this operation [`Relaxed`] if it - /// happens, and using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note:** This method is only available on platforms that support atomic - /// operations on pointers. - /// - /// # Migrating to `compare_exchange` and `compare_exchange_weak` - /// - /// `compare_and_swap` is equivalent to `compare_exchange` with the following mapping for - /// memory orderings: - /// - /// Original | Success | Failure - /// -------- | ------- | ------- - /// Relaxed | Relaxed | Relaxed - /// Acquire | Acquire | Acquire - /// Release | Release | Relaxed - /// AcqRel | AcqRel | Acquire - /// SeqCst | SeqCst | SeqCst - /// - /// `compare_exchange_weak` is allowed to fail spuriously even when the comparison succeeds, - /// which allows the compiler to generate better assembly code when the compare and swap - /// is used in a loop. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::{AtomicPtr, Ordering}; - /// - /// let ptr = &mut 5; - /// let some_ptr = AtomicPtr::new(ptr); - /// - /// let other_ptr = &mut 10; - /// - /// let value = some_ptr.compare_and_swap(ptr, other_ptr, Ordering::Relaxed); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[deprecated( - since = "1.50.0", - note = "Use `compare_exchange` or `compare_exchange_weak` instead" - )] - #[cfg(target_has_atomic = "ptr")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn compare_and_swap(&self, current: *mut T, new: *mut T, order: Ordering) -> *mut T { - match self.compare_exchange(current, new, order, strongest_failure_ordering(order)) { - Ok(x) => x, - Err(x) => x, - } - } - - /// Stores a value into the pointer if the current value is the same as the `current` value. - /// - /// The return value is a result indicating whether the new value was written and containing - /// the previous value. On success this value is guaranteed to be equal to `current`. - /// - /// `compare_exchange` takes two [`Ordering`] arguments to describe the memory - /// ordering of this operation. `success` describes the required ordering for the - /// read-modify-write operation that takes place if the comparison with `current` succeeds. - /// `failure` describes the required ordering for the load operation that takes place when - /// the comparison fails. Using [`Acquire`] as success ordering makes the store part - /// of this operation [`Relaxed`], and using [`Release`] makes the successful load - /// [`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`]. - /// - /// **Note:** This method is only available on platforms that support atomic - /// operations on pointers. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::{AtomicPtr, Ordering}; - /// - /// let ptr = &mut 5; - /// let some_ptr = AtomicPtr::new(ptr); - /// - /// let other_ptr = &mut 10; - /// - /// let value = some_ptr.compare_exchange(ptr, other_ptr, - /// Ordering::SeqCst, Ordering::Relaxed); - /// ``` - #[inline] - #[stable(feature = "extended_compare_and_swap", since = "1.10.0")] - #[cfg(target_has_atomic = "ptr")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn compare_exchange( - &self, - current: *mut T, - new: *mut T, - success: Ordering, - failure: Ordering, - ) -> Result<*mut T, *mut T> { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { atomic_compare_exchange(self.p.get(), current, new, success, failure) } - } - - /// Stores a value into the pointer if the current value is the same as the `current` value. - /// - /// Unlike [`AtomicPtr::compare_exchange`], this function is allowed to spuriously fail even when the - /// comparison succeeds, which can result in more efficient code on some platforms. The - /// return value is a result indicating whether the new value was written and containing the - /// previous value. - /// - /// `compare_exchange_weak` takes two [`Ordering`] arguments to describe the memory - /// ordering of this operation. `success` describes the required ordering for the - /// read-modify-write operation that takes place if the comparison with `current` succeeds. - /// `failure` describes the required ordering for the load operation that takes place when - /// the comparison fails. Using [`Acquire`] as success ordering makes the store part - /// of this operation [`Relaxed`], and using [`Release`] makes the successful load - /// [`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`]. - /// - /// **Note:** This method is only available on platforms that support atomic - /// operations on pointers. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::{AtomicPtr, Ordering}; - /// - /// let some_ptr = AtomicPtr::new(&mut 5); - /// - /// let new = &mut 10; - /// let mut old = some_ptr.load(Ordering::Relaxed); - /// loop { - /// match some_ptr.compare_exchange_weak(old, new, Ordering::SeqCst, Ordering::Relaxed) { - /// Ok(_) => break, - /// Err(x) => old = x, - /// } - /// } - /// ``` - #[inline] - #[stable(feature = "extended_compare_and_swap", since = "1.10.0")] - #[cfg(target_has_atomic = "ptr")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn compare_exchange_weak( - &self, - current: *mut T, - new: *mut T, - success: Ordering, - failure: Ordering, - ) -> Result<*mut T, *mut T> { - // SAFETY: This intrinsic is unsafe because it operates on a raw pointer - // but we know for sure that the pointer is valid (we just got it from - // an `UnsafeCell` that we have by reference) and the atomic operation - // itself allows us to safely mutate the `UnsafeCell` contents. - unsafe { atomic_compare_exchange_weak(self.p.get(), current, new, success, failure) } - } - - /// Fetches the value, and applies a function to it that returns an optional - /// new value. Returns a `Result` of `Ok(previous_value)` if the function - /// returned `Some(_)`, else `Err(previous_value)`. - /// - /// Note: This may call the function multiple times if the value has been - /// changed from other threads in the meantime, as long as the function - /// returns `Some(_)`, but the function will have been applied only once to - /// the stored value. - /// - /// `fetch_update` takes two [`Ordering`] arguments to describe the memory - /// ordering of this operation. The first describes the required ordering for - /// when the operation finally succeeds while the second describes the - /// required ordering for loads. These correspond to the success and failure - /// orderings of [`AtomicPtr::compare_exchange`] respectively. - /// - /// Using [`Acquire`] as success ordering makes the store part of this - /// operation [`Relaxed`], and using [`Release`] makes the final successful - /// load [`Relaxed`]. The (failed) load ordering can only be [`SeqCst`], - /// [`Acquire`] or [`Relaxed`]. - /// - /// **Note:** This method is only available on platforms that support atomic - /// operations on pointers. - /// - /// # Considerations - /// - /// This method is not magic; it is not provided by the hardware. - /// It is implemented in terms of [`AtomicPtr::compare_exchange_weak`], and suffers from the same drawbacks. - /// In particular, this method will not circumvent the [ABA Problem]. - /// - /// [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem - /// - /// # Examples - /// - /// ```rust - /// use std::sync::atomic::{AtomicPtr, Ordering}; - /// - /// let ptr: *mut _ = &mut 5; - /// let some_ptr = AtomicPtr::new(ptr); - /// - /// let new: *mut _ = &mut 10; - /// assert_eq!(some_ptr.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |_| None), Err(ptr)); - /// let result = some_ptr.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |x| { - /// if x == ptr { - /// Some(new) - /// } else { - /// None - /// } - /// }); - /// assert_eq!(result, Ok(ptr)); - /// assert_eq!(some_ptr.load(Ordering::SeqCst), new); - /// ``` - #[inline] - #[stable(feature = "atomic_fetch_update", since = "1.53.0")] - #[cfg(target_has_atomic = "ptr")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn fetch_update( - &self, - set_order: Ordering, - fetch_order: Ordering, - mut f: F, - ) -> Result<*mut T, *mut T> - where - F: FnMut(*mut T) -> Option<*mut T>, - { - let mut prev = self.load(fetch_order); - while let Some(next) = f(prev) { - match self.compare_exchange_weak(prev, next, set_order, fetch_order) { - x @ Ok(_) => return x, - Err(next_prev) => prev = next_prev, - } - } - Err(prev) - } - - /// Offsets the pointer's address by adding `val` (in units of `T`), - /// returning the previous pointer. - /// - /// This is equivalent to using [`wrapping_add`] to atomically perform the - /// equivalent of `ptr = ptr.wrapping_add(val);`. - /// - /// This method operates in units of `T`, which means that it cannot be used - /// to offset the pointer by an amount which is not a multiple of - /// `size_of::()`. This can sometimes be inconvenient, as you may want to - /// work with a deliberately misaligned pointer. In such cases, you may use - /// the [`fetch_byte_add`](Self::fetch_byte_add) method instead. - /// - /// `fetch_ptr_add` takes an [`Ordering`] argument which describes the - /// memory ordering of this operation. All ordering modes are possible. Note - /// that using [`Acquire`] makes the store part of this operation - /// [`Relaxed`], and using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note**: This method is only available on platforms that support atomic - /// operations on [`AtomicPtr`]. - /// - /// [`wrapping_add`]: pointer::wrapping_add - /// - /// # Examples - /// - /// ``` - /// #![feature(strict_provenance_atomic_ptr, strict_provenance)] - /// use core::sync::atomic::{AtomicPtr, Ordering}; - /// - /// let atom = AtomicPtr::::new(core::ptr::null_mut()); - /// assert_eq!(atom.fetch_ptr_add(1, Ordering::Relaxed).addr(), 0); - /// // Note: units of `size_of::()`. - /// assert_eq!(atom.load(Ordering::Relaxed).addr(), 8); - /// ``` - #[inline] - #[cfg(target_has_atomic = "ptr")] - #[unstable(feature = "strict_provenance_atomic_ptr", issue = "99108")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn fetch_ptr_add(&self, val: usize, order: Ordering) -> *mut T { - self.fetch_byte_add(val.wrapping_mul(core::mem::size_of::()), order) - } - - /// Offsets the pointer's address by subtracting `val` (in units of `T`), - /// returning the previous pointer. - /// - /// This is equivalent to using [`wrapping_sub`] to atomically perform the - /// equivalent of `ptr = ptr.wrapping_sub(val);`. - /// - /// This method operates in units of `T`, which means that it cannot be used - /// to offset the pointer by an amount which is not a multiple of - /// `size_of::()`. This can sometimes be inconvenient, as you may want to - /// work with a deliberately misaligned pointer. In such cases, you may use - /// the [`fetch_byte_sub`](Self::fetch_byte_sub) method instead. - /// - /// `fetch_ptr_sub` takes an [`Ordering`] argument which describes the memory - /// ordering of this operation. All ordering modes are possible. Note that - /// using [`Acquire`] makes the store part of this operation [`Relaxed`], - /// and using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note**: This method is only available on platforms that support atomic - /// operations on [`AtomicPtr`]. - /// - /// [`wrapping_sub`]: pointer::wrapping_sub - /// - /// # Examples - /// - /// ``` - /// #![feature(strict_provenance_atomic_ptr)] - /// use core::sync::atomic::{AtomicPtr, Ordering}; - /// - /// let array = [1i32, 2i32]; - /// let atom = AtomicPtr::new(array.as_ptr().wrapping_add(1) as *mut _); - /// - /// assert!(core::ptr::eq( - /// atom.fetch_ptr_sub(1, Ordering::Relaxed), - /// &array[1], - /// )); - /// assert!(core::ptr::eq(atom.load(Ordering::Relaxed), &array[0])); - /// ``` - #[inline] - #[cfg(target_has_atomic = "ptr")] - #[unstable(feature = "strict_provenance_atomic_ptr", issue = "99108")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn fetch_ptr_sub(&self, val: usize, order: Ordering) -> *mut T { - self.fetch_byte_sub(val.wrapping_mul(core::mem::size_of::()), order) - } - - /// Offsets the pointer's address by adding `val` *bytes*, returning the - /// previous pointer. - /// - /// This is equivalent to using [`wrapping_byte_add`] to atomically - /// perform `ptr = ptr.wrapping_byte_add(val)`. - /// - /// `fetch_byte_add` takes an [`Ordering`] argument which describes the - /// memory ordering of this operation. All ordering modes are possible. Note - /// that using [`Acquire`] makes the store part of this operation - /// [`Relaxed`], and using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note**: This method is only available on platforms that support atomic - /// operations on [`AtomicPtr`]. - /// - /// [`wrapping_byte_add`]: pointer::wrapping_byte_add - /// - /// # Examples - /// - /// ``` - /// #![feature(strict_provenance_atomic_ptr, strict_provenance)] - /// use core::sync::atomic::{AtomicPtr, Ordering}; - /// - /// let atom = AtomicPtr::::new(core::ptr::null_mut()); - /// assert_eq!(atom.fetch_byte_add(1, Ordering::Relaxed).addr(), 0); - /// // Note: in units of bytes, not `size_of::()`. - /// assert_eq!(atom.load(Ordering::Relaxed).addr(), 1); - /// ``` - #[inline] - #[cfg(target_has_atomic = "ptr")] - #[unstable(feature = "strict_provenance_atomic_ptr", issue = "99108")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn fetch_byte_add(&self, val: usize, order: Ordering) -> *mut T { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { atomic_add(self.p.get(), core::ptr::without_provenance_mut(val), order).cast() } - } - - /// Offsets the pointer's address by subtracting `val` *bytes*, returning the - /// previous pointer. - /// - /// This is equivalent to using [`wrapping_byte_sub`] to atomically - /// perform `ptr = ptr.wrapping_byte_sub(val)`. - /// - /// `fetch_byte_sub` takes an [`Ordering`] argument which describes the - /// memory ordering of this operation. All ordering modes are possible. Note - /// that using [`Acquire`] makes the store part of this operation - /// [`Relaxed`], and using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note**: This method is only available on platforms that support atomic - /// operations on [`AtomicPtr`]. - /// - /// [`wrapping_byte_sub`]: pointer::wrapping_byte_sub - /// - /// # Examples - /// - /// ``` - /// #![feature(strict_provenance_atomic_ptr, strict_provenance)] - /// use core::sync::atomic::{AtomicPtr, Ordering}; - /// - /// let atom = AtomicPtr::::new(core::ptr::without_provenance_mut(1)); - /// assert_eq!(atom.fetch_byte_sub(1, Ordering::Relaxed).addr(), 1); - /// assert_eq!(atom.load(Ordering::Relaxed).addr(), 0); - /// ``` - #[inline] - #[cfg(target_has_atomic = "ptr")] - #[unstable(feature = "strict_provenance_atomic_ptr", issue = "99108")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn fetch_byte_sub(&self, val: usize, order: Ordering) -> *mut T { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { atomic_sub(self.p.get(), core::ptr::without_provenance_mut(val), order).cast() } - } - - /// Performs a bitwise "or" operation on the address of the current pointer, - /// and the argument `val`, and stores a pointer with provenance of the - /// current pointer and the resulting address. - /// - /// This is equivalent to using [`map_addr`] to atomically perform - /// `ptr = ptr.map_addr(|a| a | val)`. This can be used in tagged - /// pointer schemes to atomically set tag bits. - /// - /// **Caveat**: This operation returns the previous value. To compute the - /// stored value without losing provenance, you may use [`map_addr`]. For - /// example: `a.fetch_or(val).map_addr(|a| a | val)`. - /// - /// `fetch_or` takes an [`Ordering`] argument which describes the memory - /// ordering of this operation. All ordering modes are possible. Note that - /// using [`Acquire`] makes the store part of this operation [`Relaxed`], - /// and using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note**: This method is only available on platforms that support atomic - /// operations on [`AtomicPtr`]. - /// - /// This API and its claimed semantics are part of the Strict Provenance - /// experiment, see the [module documentation for `ptr`][crate::ptr] for - /// details. - /// - /// [`map_addr`]: pointer::map_addr - /// - /// # Examples - /// - /// ``` - /// #![feature(strict_provenance_atomic_ptr, strict_provenance)] - /// use core::sync::atomic::{AtomicPtr, Ordering}; - /// - /// let pointer = &mut 3i64 as *mut i64; - /// - /// let atom = AtomicPtr::::new(pointer); - /// // Tag the bottom bit of the pointer. - /// assert_eq!(atom.fetch_or(1, Ordering::Relaxed).addr() & 1, 0); - /// // Extract and untag. - /// let tagged = atom.load(Ordering::Relaxed); - /// assert_eq!(tagged.addr() & 1, 1); - /// assert_eq!(tagged.map_addr(|p| p & !1), pointer); - /// ``` - #[inline] - #[cfg(target_has_atomic = "ptr")] - #[unstable(feature = "strict_provenance_atomic_ptr", issue = "99108")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn fetch_or(&self, val: usize, order: Ordering) -> *mut T { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { atomic_or(self.p.get(), core::ptr::without_provenance_mut(val), order).cast() } - } - - /// Performs a bitwise "and" operation on the address of the current - /// pointer, and the argument `val`, and stores a pointer with provenance of - /// the current pointer and the resulting address. - /// - /// This is equivalent to using [`map_addr`] to atomically perform - /// `ptr = ptr.map_addr(|a| a & val)`. This can be used in tagged - /// pointer schemes to atomically unset tag bits. - /// - /// **Caveat**: This operation returns the previous value. To compute the - /// stored value without losing provenance, you may use [`map_addr`]. For - /// example: `a.fetch_and(val).map_addr(|a| a & val)`. - /// - /// `fetch_and` takes an [`Ordering`] argument which describes the memory - /// ordering of this operation. All ordering modes are possible. Note that - /// using [`Acquire`] makes the store part of this operation [`Relaxed`], - /// and using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note**: This method is only available on platforms that support atomic - /// operations on [`AtomicPtr`]. - /// - /// This API and its claimed semantics are part of the Strict Provenance - /// experiment, see the [module documentation for `ptr`][crate::ptr] for - /// details. - /// - /// [`map_addr`]: pointer::map_addr - /// - /// # Examples - /// - /// ``` - /// #![feature(strict_provenance_atomic_ptr, strict_provenance)] - /// use core::sync::atomic::{AtomicPtr, Ordering}; - /// - /// let pointer = &mut 3i64 as *mut i64; - /// // A tagged pointer - /// let atom = AtomicPtr::::new(pointer.map_addr(|a| a | 1)); - /// assert_eq!(atom.fetch_or(1, Ordering::Relaxed).addr() & 1, 1); - /// // Untag, and extract the previously tagged pointer. - /// let untagged = atom.fetch_and(!1, Ordering::Relaxed) - /// .map_addr(|a| a & !1); - /// assert_eq!(untagged, pointer); - /// ``` - #[inline] - #[cfg(target_has_atomic = "ptr")] - #[unstable(feature = "strict_provenance_atomic_ptr", issue = "99108")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn fetch_and(&self, val: usize, order: Ordering) -> *mut T { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { atomic_and(self.p.get(), core::ptr::without_provenance_mut(val), order).cast() } - } - - /// Performs a bitwise "xor" operation on the address of the current - /// pointer, and the argument `val`, and stores a pointer with provenance of - /// the current pointer and the resulting address. - /// - /// This is equivalent to using [`map_addr`] to atomically perform - /// `ptr = ptr.map_addr(|a| a ^ val)`. This can be used in tagged - /// pointer schemes to atomically toggle tag bits. - /// - /// **Caveat**: This operation returns the previous value. To compute the - /// stored value without losing provenance, you may use [`map_addr`]. For - /// example: `a.fetch_xor(val).map_addr(|a| a ^ val)`. - /// - /// `fetch_xor` takes an [`Ordering`] argument which describes the memory - /// ordering of this operation. All ordering modes are possible. Note that - /// using [`Acquire`] makes the store part of this operation [`Relaxed`], - /// and using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note**: This method is only available on platforms that support atomic - /// operations on [`AtomicPtr`]. - /// - /// This API and its claimed semantics are part of the Strict Provenance - /// experiment, see the [module documentation for `ptr`][crate::ptr] for - /// details. - /// - /// [`map_addr`]: pointer::map_addr - /// - /// # Examples - /// - /// ``` - /// #![feature(strict_provenance_atomic_ptr, strict_provenance)] - /// use core::sync::atomic::{AtomicPtr, Ordering}; - /// - /// let pointer = &mut 3i64 as *mut i64; - /// let atom = AtomicPtr::::new(pointer); - /// - /// // Toggle a tag bit on the pointer. - /// atom.fetch_xor(1, Ordering::Relaxed); - /// assert_eq!(atom.load(Ordering::Relaxed).addr() & 1, 1); - /// ``` - #[inline] - #[cfg(target_has_atomic = "ptr")] - #[unstable(feature = "strict_provenance_atomic_ptr", issue = "99108")] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn fetch_xor(&self, val: usize, order: Ordering) -> *mut T { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { atomic_xor(self.p.get(), core::ptr::without_provenance_mut(val), order).cast() } - } - - /// Returns a mutable pointer to the underlying pointer. - /// - /// Doing non-atomic reads and writes on the resulting pointer can be a data race. - /// This method is mostly useful for FFI, where the function signature may use - /// `*mut *mut T` instead of `&AtomicPtr`. - /// - /// Returning an `*mut` pointer from a shared reference to this atomic is safe because the - /// atomic types work with interior mutability. All modifications of an atomic change the value - /// through a shared reference, and can do so safely as long as they use atomic operations. Any - /// use of the returned raw pointer requires an `unsafe` block and still has to uphold the same - /// restriction: operations on it must be atomic. - /// - /// # Examples - /// - /// ```ignore (extern-declaration) - /// use std::sync::atomic::AtomicPtr; - /// - /// extern "C" { - /// fn my_atomic_op(arg: *mut *mut u32); - /// } - /// - /// let mut value = 17; - /// let atomic = AtomicPtr::new(&mut value); - /// - /// // SAFETY: Safe as long as `my_atomic_op` is atomic. - /// unsafe { - /// my_atomic_op(atomic.as_ptr()); - /// } - /// ``` - #[inline] - #[stable(feature = "atomic_as_ptr", since = "1.70.0")] - #[rustc_const_stable(feature = "atomic_as_ptr", since = "1.70.0")] - #[rustc_never_returns_null_ptr] - pub const fn as_ptr(&self) -> *mut *mut T { - self.p.get() - } -} - -#[cfg(target_has_atomic_load_store = "8")] -#[stable(feature = "atomic_bool_from", since = "1.24.0")] -impl From for AtomicBool { - /// Converts a `bool` into an `AtomicBool`. - /// - /// # Examples - /// - /// ``` - /// use std::sync::atomic::AtomicBool; - /// let atomic_bool = AtomicBool::from(true); - /// assert_eq!(format!("{atomic_bool:?}"), "true") - /// ``` - #[inline] - fn from(b: bool) -> Self { - Self::new(b) - } -} - -#[cfg(target_has_atomic_load_store = "ptr")] -#[stable(feature = "atomic_from", since = "1.23.0")] -impl From<*mut T> for AtomicPtr { - /// Converts a `*mut T` into an `AtomicPtr`. - #[inline] - fn from(p: *mut T) -> Self { - Self::new(p) - } -} - -#[allow(unused_macros)] // This macro ends up being unused on some architectures. -macro_rules! if_not_8_bit { - (u8, $($tt:tt)*) => { "" }; - (i8, $($tt:tt)*) => { "" }; - ($_:ident, $($tt:tt)*) => { $($tt)* }; -} - -#[cfg(target_has_atomic_load_store)] -macro_rules! atomic_int { - ($cfg_cas:meta, - $cfg_align:meta, - $stable:meta, - $stable_cxchg:meta, - $stable_debug:meta, - $stable_access:meta, - $stable_from:meta, - $stable_nand:meta, - $const_stable:meta, - $diagnostic_item:meta, - $s_int_type:literal, - $extra_feature:expr, - $min_fn:ident, $max_fn:ident, - $align:expr, - $int_type:ident $atomic_type:ident) => { - /// An integer type which can be safely shared between threads. - /// - /// This type has the same size and bit validity as the underlying - /// integer type, [` - #[doc = $s_int_type] - /// `]. - #[doc = if_not_8_bit! { - $int_type, - concat!( - "However, the alignment of this type is always equal to its ", - "size, even on targets where [`", $s_int_type, "`] has a ", - "lesser alignment." - ) - }] - /// For more about the differences between atomic types and - /// non-atomic types as well as information about the portability of - /// this type, please see the [module-level documentation]. - /// - /// **Note:** This type is only available on platforms that support - /// atomic loads and stores of [` - #[doc = $s_int_type] - /// `]. - /// - /// [module-level documentation]: crate::sync::atomic - #[$stable] - #[$diagnostic_item] - #[repr(C, align($align))] - pub struct $atomic_type { - v: UnsafeCell<$int_type>, - } - - #[$stable] - impl Default for $atomic_type { - #[inline] - fn default() -> Self { - Self::new(Default::default()) - } - } - - #[$stable_from] - impl From<$int_type> for $atomic_type { - #[doc = concat!("Converts an `", stringify!($int_type), "` into an `", stringify!($atomic_type), "`.")] - #[inline] - fn from(v: $int_type) -> Self { Self::new(v) } - } - - #[$stable_debug] - impl fmt::Debug for $atomic_type { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&self.load(Ordering::Relaxed), f) - } - } - - // Send is implicitly implemented. - #[$stable] - unsafe impl Sync for $atomic_type {} - - impl $atomic_type { - /// Creates a new atomic integer. - /// - /// # Examples - /// - /// ``` - #[doc = concat!($extra_feature, "use std::sync::atomic::", stringify!($atomic_type), ";")] - /// - #[doc = concat!("let atomic_forty_two = ", stringify!($atomic_type), "::new(42);")] - /// ``` - #[inline] - #[$stable] - #[$const_stable] - #[must_use] - pub const fn new(v: $int_type) -> Self { - Self {v: UnsafeCell::new(v)} - } - - /// Creates a new reference to an atomic integer from a pointer. - /// - /// # Examples - /// - /// ``` - #[doc = concat!($extra_feature, "use std::sync::atomic::{self, ", stringify!($atomic_type), "};")] - /// - /// // Get a pointer to an allocated value - #[doc = concat!("let ptr: *mut ", stringify!($int_type), " = Box::into_raw(Box::new(0));")] - /// - #[doc = concat!("assert!(ptr.cast::<", stringify!($atomic_type), ">().is_aligned());")] - /// - /// { - /// // Create an atomic view of the allocated value - // SAFETY: this is a doc comment, tidy, it can't hurt you (also guaranteed by the construction of `ptr` and the assert above) - #[doc = concat!(" let atomic = unsafe {", stringify!($atomic_type), "::from_ptr(ptr) };")] - /// - /// // Use `atomic` for atomic operations, possibly share it with other threads - /// atomic.store(1, atomic::Ordering::Relaxed); - /// } - /// - /// // It's ok to non-atomically access the value behind `ptr`, - /// // since the reference to the atomic ended its lifetime in the block above - /// assert_eq!(unsafe { *ptr }, 1); - /// - /// // Deallocate the value - /// unsafe { drop(Box::from_raw(ptr)) } - /// ``` - /// - /// # Safety - /// - #[doc = concat!(" * `ptr` must be aligned to \ - `align_of::<", stringify!($atomic_type), ">()` (note that on some platforms this \ - can be bigger than `align_of::<", stringify!($int_type), ">()`).")] - /// * `ptr` must be [valid] for both reads and writes for the whole lifetime `'a`. - /// * You must adhere to the [Memory model for atomic accesses]. In particular, it is not - /// allowed to mix atomic and non-atomic accesses, or atomic accesses of different sizes, - /// without synchronization. - /// - /// [valid]: crate::ptr#safety - /// [Memory model for atomic accesses]: self#memory-model-for-atomic-accesses - #[stable(feature = "atomic_from_ptr", since = "1.75.0")] - #[rustc_const_unstable(feature = "const_atomic_from_ptr", issue = "108652")] - pub const unsafe fn from_ptr<'a>(ptr: *mut $int_type) -> &'a $atomic_type { - // SAFETY: guaranteed by the caller - unsafe { &*ptr.cast() } - } - - - /// Returns a mutable reference to the underlying integer. - /// - /// This is safe because the mutable reference guarantees that no other threads are - /// concurrently accessing the atomic data. - /// - /// # Examples - /// - /// ``` - #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")] - /// - #[doc = concat!("let mut some_var = ", stringify!($atomic_type), "::new(10);")] - /// assert_eq!(*some_var.get_mut(), 10); - /// *some_var.get_mut() = 5; - /// assert_eq!(some_var.load(Ordering::SeqCst), 5); - /// ``` - #[inline] - #[$stable_access] - pub fn get_mut(&mut self) -> &mut $int_type { - self.v.get_mut() - } - - #[doc = concat!("Get atomic access to a `&mut ", stringify!($int_type), "`.")] - /// - #[doc = if_not_8_bit! { - $int_type, - concat!( - "**Note:** This function is only available on targets where `", - stringify!($int_type), "` has an alignment of ", $align, " bytes." - ) - }] - /// - /// # Examples - /// - /// ``` - /// #![feature(atomic_from_mut)] - #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")] - /// - /// let mut some_int = 123; - #[doc = concat!("let a = ", stringify!($atomic_type), "::from_mut(&mut some_int);")] - /// a.store(100, Ordering::Relaxed); - /// assert_eq!(some_int, 100); - /// ``` - /// - #[inline] - #[$cfg_align] - #[unstable(feature = "atomic_from_mut", issue = "76314")] - pub fn from_mut(v: &mut $int_type) -> &mut Self { - use crate::mem::align_of; - let [] = [(); align_of::() - align_of::<$int_type>()]; - // SAFETY: - // - the mutable reference guarantees unique ownership. - // - the alignment of `$int_type` and `Self` is the - // same, as promised by $cfg_align and verified above. - unsafe { &mut *(v as *mut $int_type as *mut Self) } - } - - #[doc = concat!("Get non-atomic access to a `&mut [", stringify!($atomic_type), "]` slice")] - /// - /// This is safe because the mutable reference guarantees that no other threads are - /// concurrently accessing the atomic data. - /// - /// # Examples - /// - /// ``` - /// #![feature(atomic_from_mut)] - #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")] - /// - #[doc = concat!("let mut some_ints = [const { ", stringify!($atomic_type), "::new(0) }; 10];")] - /// - #[doc = concat!("let view: &mut [", stringify!($int_type), "] = ", stringify!($atomic_type), "::get_mut_slice(&mut some_ints);")] - /// assert_eq!(view, [0; 10]); - /// view - /// .iter_mut() - /// .enumerate() - /// .for_each(|(idx, int)| *int = idx as _); - /// - /// std::thread::scope(|s| { - /// some_ints - /// .iter() - /// .enumerate() - /// .for_each(|(idx, int)| { - /// s.spawn(move || assert_eq!(int.load(Ordering::Relaxed), idx as _)); - /// }) - /// }); - /// ``` - #[inline] - #[unstable(feature = "atomic_from_mut", issue = "76314")] - pub fn get_mut_slice(this: &mut [Self]) -> &mut [$int_type] { - // SAFETY: the mutable reference guarantees unique ownership. - unsafe { &mut *(this as *mut [Self] as *mut [$int_type]) } - } - - #[doc = concat!("Get atomic access to a `&mut [", stringify!($int_type), "]` slice.")] - /// - /// # Examples - /// - /// ``` - /// #![feature(atomic_from_mut)] - #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")] - /// - /// let mut some_ints = [0; 10]; - #[doc = concat!("let a = &*", stringify!($atomic_type), "::from_mut_slice(&mut some_ints);")] - /// std::thread::scope(|s| { - /// for i in 0..a.len() { - /// s.spawn(move || a[i].store(i as _, Ordering::Relaxed)); - /// } - /// }); - /// for (i, n) in some_ints.into_iter().enumerate() { - /// assert_eq!(i, n as usize); - /// } - /// ``` - #[inline] - #[$cfg_align] - #[unstable(feature = "atomic_from_mut", issue = "76314")] - pub fn from_mut_slice(v: &mut [$int_type]) -> &mut [Self] { - use crate::mem::align_of; - let [] = [(); align_of::() - align_of::<$int_type>()]; - // SAFETY: - // - the mutable reference guarantees unique ownership. - // - the alignment of `$int_type` and `Self` is the - // same, as promised by $cfg_align and verified above. - unsafe { &mut *(v as *mut [$int_type] as *mut [Self]) } - } - - /// Consumes the atomic and returns the contained value. - /// - /// This is safe because passing `self` by value guarantees that no other threads are - /// concurrently accessing the atomic data. - /// - /// # Examples - /// - /// ``` - #[doc = concat!($extra_feature, "use std::sync::atomic::", stringify!($atomic_type), ";")] - /// - #[doc = concat!("let some_var = ", stringify!($atomic_type), "::new(5);")] - /// assert_eq!(some_var.into_inner(), 5); - /// ``` - #[inline] - #[$stable_access] - #[rustc_const_stable(feature = "const_atomic_into_inner", since = "1.79.0")] - pub const fn into_inner(self) -> $int_type { - self.v.primitive_into_inner() - } - - /// Loads a value from the atomic integer. - /// - /// `load` takes an [`Ordering`] argument which describes the memory ordering of this operation. - /// Possible values are [`SeqCst`], [`Acquire`] and [`Relaxed`]. - /// - /// # Panics - /// - /// Panics if `order` is [`Release`] or [`AcqRel`]. - /// - /// # Examples - /// - /// ``` - #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")] - /// - #[doc = concat!("let some_var = ", stringify!($atomic_type), "::new(5);")] - /// - /// assert_eq!(some_var.load(Ordering::Relaxed), 5); - /// ``` - #[inline] - #[$stable] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn load(&self, order: Ordering) -> $int_type { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { atomic_load(self.v.get(), order) } - } - - /// Stores a value into the atomic integer. - /// - /// `store` takes an [`Ordering`] argument which describes the memory ordering of this operation. - /// Possible values are [`SeqCst`], [`Release`] and [`Relaxed`]. - /// - /// # Panics - /// - /// Panics if `order` is [`Acquire`] or [`AcqRel`]. - /// - /// # Examples - /// - /// ``` - #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")] - /// - #[doc = concat!("let some_var = ", stringify!($atomic_type), "::new(5);")] - /// - /// some_var.store(10, Ordering::Relaxed); - /// assert_eq!(some_var.load(Ordering::Relaxed), 10); - /// ``` - #[inline] - #[$stable] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn store(&self, val: $int_type, order: Ordering) { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { atomic_store(self.v.get(), val, order); } - } - - /// Stores a value into the atomic integer, returning the previous value. - /// - /// `swap` takes an [`Ordering`] argument which describes the memory ordering - /// of this operation. All ordering modes are possible. Note that using - /// [`Acquire`] makes the store part of this operation [`Relaxed`], and - /// using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note**: This method is only available on platforms that support atomic operations on - #[doc = concat!("[`", $s_int_type, "`].")] - /// - /// # Examples - /// - /// ``` - #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")] - /// - #[doc = concat!("let some_var = ", stringify!($atomic_type), "::new(5);")] - /// - /// assert_eq!(some_var.swap(10, Ordering::Relaxed), 5); - /// ``` - #[inline] - #[$stable] - #[$cfg_cas] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn swap(&self, val: $int_type, order: Ordering) -> $int_type { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { atomic_swap(self.v.get(), val, order) } - } - - /// Stores a value into the atomic integer if the current value is the same as - /// the `current` value. - /// - /// The return value is always the previous value. If it is equal to `current`, then the - /// value was updated. - /// - /// `compare_and_swap` also takes an [`Ordering`] argument which describes the memory - /// ordering of this operation. Notice that even when using [`AcqRel`], the operation - /// might fail and hence just perform an `Acquire` load, but not have `Release` semantics. - /// Using [`Acquire`] makes the store part of this operation [`Relaxed`] if it - /// happens, and using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note**: This method is only available on platforms that support atomic operations on - #[doc = concat!("[`", $s_int_type, "`].")] - /// - /// # Migrating to `compare_exchange` and `compare_exchange_weak` - /// - /// `compare_and_swap` is equivalent to `compare_exchange` with the following mapping for - /// memory orderings: - /// - /// Original | Success | Failure - /// -------- | ------- | ------- - /// Relaxed | Relaxed | Relaxed - /// Acquire | Acquire | Acquire - /// Release | Release | Relaxed - /// AcqRel | AcqRel | Acquire - /// SeqCst | SeqCst | SeqCst - /// - /// `compare_exchange_weak` is allowed to fail spuriously even when the comparison succeeds, - /// which allows the compiler to generate better assembly code when the compare and swap - /// is used in a loop. - /// - /// # Examples - /// - /// ``` - #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")] - /// - #[doc = concat!("let some_var = ", stringify!($atomic_type), "::new(5);")] - /// - /// assert_eq!(some_var.compare_and_swap(5, 10, Ordering::Relaxed), 5); - /// assert_eq!(some_var.load(Ordering::Relaxed), 10); - /// - /// assert_eq!(some_var.compare_and_swap(6, 12, Ordering::Relaxed), 10); - /// assert_eq!(some_var.load(Ordering::Relaxed), 10); - /// ``` - #[inline] - #[$stable] - #[deprecated( - since = "1.50.0", - note = "Use `compare_exchange` or `compare_exchange_weak` instead") - ] - #[$cfg_cas] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn compare_and_swap(&self, - current: $int_type, - new: $int_type, - order: Ordering) -> $int_type { - match self.compare_exchange(current, - new, - order, - strongest_failure_ordering(order)) { - Ok(x) => x, - Err(x) => x, - } - } - - /// Stores a value into the atomic integer if the current value is the same as - /// the `current` value. - /// - /// The return value is a result indicating whether the new value was written and - /// containing the previous value. On success this value is guaranteed to be equal to - /// `current`. - /// - /// `compare_exchange` takes two [`Ordering`] arguments to describe the memory - /// ordering of this operation. `success` describes the required ordering for the - /// read-modify-write operation that takes place if the comparison with `current` succeeds. - /// `failure` describes the required ordering for the load operation that takes place when - /// the comparison fails. Using [`Acquire`] as success ordering makes the store part - /// of this operation [`Relaxed`], and using [`Release`] makes the successful load - /// [`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`]. - /// - /// **Note**: This method is only available on platforms that support atomic operations on - #[doc = concat!("[`", $s_int_type, "`].")] - /// - /// # Examples - /// - /// ``` - #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")] - /// - #[doc = concat!("let some_var = ", stringify!($atomic_type), "::new(5);")] - /// - /// assert_eq!(some_var.compare_exchange(5, 10, - /// Ordering::Acquire, - /// Ordering::Relaxed), - /// Ok(5)); - /// assert_eq!(some_var.load(Ordering::Relaxed), 10); - /// - /// assert_eq!(some_var.compare_exchange(6, 12, - /// Ordering::SeqCst, - /// Ordering::Acquire), - /// Err(10)); - /// assert_eq!(some_var.load(Ordering::Relaxed), 10); - /// ``` - #[inline] - #[$stable_cxchg] - #[$cfg_cas] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn compare_exchange(&self, - current: $int_type, - new: $int_type, - success: Ordering, - failure: Ordering) -> Result<$int_type, $int_type> { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { atomic_compare_exchange(self.v.get(), current, new, success, failure) } - } - - /// Stores a value into the atomic integer if the current value is the same as - /// the `current` value. - /// - #[doc = concat!("Unlike [`", stringify!($atomic_type), "::compare_exchange`],")] - /// this function is allowed to spuriously fail even - /// when the comparison succeeds, which can result in more efficient code on some - /// platforms. The return value is a result indicating whether the new value was - /// written and containing the previous value. - /// - /// `compare_exchange_weak` takes two [`Ordering`] arguments to describe the memory - /// ordering of this operation. `success` describes the required ordering for the - /// read-modify-write operation that takes place if the comparison with `current` succeeds. - /// `failure` describes the required ordering for the load operation that takes place when - /// the comparison fails. Using [`Acquire`] as success ordering makes the store part - /// of this operation [`Relaxed`], and using [`Release`] makes the successful load - /// [`Relaxed`]. The failure ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`]. - /// - /// **Note**: This method is only available on platforms that support atomic operations on - #[doc = concat!("[`", $s_int_type, "`].")] - /// - /// # Examples - /// - /// ``` - #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")] - /// - #[doc = concat!("let val = ", stringify!($atomic_type), "::new(4);")] - /// - /// let mut old = val.load(Ordering::Relaxed); - /// loop { - /// let new = old * 2; - /// match val.compare_exchange_weak(old, new, Ordering::SeqCst, Ordering::Relaxed) { - /// Ok(_) => break, - /// Err(x) => old = x, - /// } - /// } - /// ``` - #[inline] - #[$stable_cxchg] - #[$cfg_cas] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn compare_exchange_weak(&self, - current: $int_type, - new: $int_type, - success: Ordering, - failure: Ordering) -> Result<$int_type, $int_type> { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { - atomic_compare_exchange_weak(self.v.get(), current, new, success, failure) - } - } - - /// Adds to the current value, returning the previous value. - /// - /// This operation wraps around on overflow. - /// - /// `fetch_add` takes an [`Ordering`] argument which describes the memory ordering - /// of this operation. All ordering modes are possible. Note that using - /// [`Acquire`] makes the store part of this operation [`Relaxed`], and - /// using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note**: This method is only available on platforms that support atomic operations on - #[doc = concat!("[`", $s_int_type, "`].")] - /// - /// # Examples - /// - /// ``` - #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")] - /// - #[doc = concat!("let foo = ", stringify!($atomic_type), "::new(0);")] - /// assert_eq!(foo.fetch_add(10, Ordering::SeqCst), 0); - /// assert_eq!(foo.load(Ordering::SeqCst), 10); - /// ``` - #[inline] - #[$stable] - #[$cfg_cas] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn fetch_add(&self, val: $int_type, order: Ordering) -> $int_type { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { atomic_add(self.v.get(), val, order) } - } - - /// Subtracts from the current value, returning the previous value. - /// - /// This operation wraps around on overflow. - /// - /// `fetch_sub` takes an [`Ordering`] argument which describes the memory ordering - /// of this operation. All ordering modes are possible. Note that using - /// [`Acquire`] makes the store part of this operation [`Relaxed`], and - /// using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note**: This method is only available on platforms that support atomic operations on - #[doc = concat!("[`", $s_int_type, "`].")] - /// - /// # Examples - /// - /// ``` - #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")] - /// - #[doc = concat!("let foo = ", stringify!($atomic_type), "::new(20);")] - /// assert_eq!(foo.fetch_sub(10, Ordering::SeqCst), 20); - /// assert_eq!(foo.load(Ordering::SeqCst), 10); - /// ``` - #[inline] - #[$stable] - #[$cfg_cas] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn fetch_sub(&self, val: $int_type, order: Ordering) -> $int_type { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { atomic_sub(self.v.get(), val, order) } - } - - /// Bitwise "and" with the current value. - /// - /// Performs a bitwise "and" operation on the current value and the argument `val`, and - /// sets the new value to the result. - /// - /// Returns the previous value. - /// - /// `fetch_and` takes an [`Ordering`] argument which describes the memory ordering - /// of this operation. All ordering modes are possible. Note that using - /// [`Acquire`] makes the store part of this operation [`Relaxed`], and - /// using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note**: This method is only available on platforms that support atomic operations on - #[doc = concat!("[`", $s_int_type, "`].")] - /// - /// # Examples - /// - /// ``` - #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")] - /// - #[doc = concat!("let foo = ", stringify!($atomic_type), "::new(0b101101);")] - /// assert_eq!(foo.fetch_and(0b110011, Ordering::SeqCst), 0b101101); - /// assert_eq!(foo.load(Ordering::SeqCst), 0b100001); - /// ``` - #[inline] - #[$stable] - #[$cfg_cas] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn fetch_and(&self, val: $int_type, order: Ordering) -> $int_type { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { atomic_and(self.v.get(), val, order) } - } - - /// Bitwise "nand" with the current value. - /// - /// Performs a bitwise "nand" operation on the current value and the argument `val`, and - /// sets the new value to the result. - /// - /// Returns the previous value. - /// - /// `fetch_nand` takes an [`Ordering`] argument which describes the memory ordering - /// of this operation. All ordering modes are possible. Note that using - /// [`Acquire`] makes the store part of this operation [`Relaxed`], and - /// using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note**: This method is only available on platforms that support atomic operations on - #[doc = concat!("[`", $s_int_type, "`].")] - /// - /// # Examples - /// - /// ``` - #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")] - /// - #[doc = concat!("let foo = ", stringify!($atomic_type), "::new(0x13);")] - /// assert_eq!(foo.fetch_nand(0x31, Ordering::SeqCst), 0x13); - /// assert_eq!(foo.load(Ordering::SeqCst), !(0x13 & 0x31)); - /// ``` - #[inline] - #[$stable_nand] - #[$cfg_cas] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn fetch_nand(&self, val: $int_type, order: Ordering) -> $int_type { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { atomic_nand(self.v.get(), val, order) } - } - - /// Bitwise "or" with the current value. - /// - /// Performs a bitwise "or" operation on the current value and the argument `val`, and - /// sets the new value to the result. - /// - /// Returns the previous value. - /// - /// `fetch_or` takes an [`Ordering`] argument which describes the memory ordering - /// of this operation. All ordering modes are possible. Note that using - /// [`Acquire`] makes the store part of this operation [`Relaxed`], and - /// using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note**: This method is only available on platforms that support atomic operations on - #[doc = concat!("[`", $s_int_type, "`].")] - /// - /// # Examples - /// - /// ``` - #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")] - /// - #[doc = concat!("let foo = ", stringify!($atomic_type), "::new(0b101101);")] - /// assert_eq!(foo.fetch_or(0b110011, Ordering::SeqCst), 0b101101); - /// assert_eq!(foo.load(Ordering::SeqCst), 0b111111); - /// ``` - #[inline] - #[$stable] - #[$cfg_cas] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn fetch_or(&self, val: $int_type, order: Ordering) -> $int_type { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { atomic_or(self.v.get(), val, order) } - } - - /// Bitwise "xor" with the current value. - /// - /// Performs a bitwise "xor" operation on the current value and the argument `val`, and - /// sets the new value to the result. - /// - /// Returns the previous value. - /// - /// `fetch_xor` takes an [`Ordering`] argument which describes the memory ordering - /// of this operation. All ordering modes are possible. Note that using - /// [`Acquire`] makes the store part of this operation [`Relaxed`], and - /// using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note**: This method is only available on platforms that support atomic operations on - #[doc = concat!("[`", $s_int_type, "`].")] - /// - /// # Examples - /// - /// ``` - #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")] - /// - #[doc = concat!("let foo = ", stringify!($atomic_type), "::new(0b101101);")] - /// assert_eq!(foo.fetch_xor(0b110011, Ordering::SeqCst), 0b101101); - /// assert_eq!(foo.load(Ordering::SeqCst), 0b011110); - /// ``` - #[inline] - #[$stable] - #[$cfg_cas] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn fetch_xor(&self, val: $int_type, order: Ordering) -> $int_type { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { atomic_xor(self.v.get(), val, order) } - } - - /// Fetches the value, and applies a function to it that returns an optional - /// new value. Returns a `Result` of `Ok(previous_value)` if the function returned `Some(_)`, else - /// `Err(previous_value)`. - /// - /// Note: This may call the function multiple times if the value has been changed from other threads in - /// the meantime, as long as the function returns `Some(_)`, but the function will have been applied - /// only once to the stored value. - /// - /// `fetch_update` takes two [`Ordering`] arguments to describe the memory ordering of this operation. - /// The first describes the required ordering for when the operation finally succeeds while the second - /// describes the required ordering for loads. These correspond to the success and failure orderings of - #[doc = concat!("[`", stringify!($atomic_type), "::compare_exchange`]")] - /// respectively. - /// - /// Using [`Acquire`] as success ordering makes the store part - /// of this operation [`Relaxed`], and using [`Release`] makes the final successful load - /// [`Relaxed`]. The (failed) load ordering can only be [`SeqCst`], [`Acquire`] or [`Relaxed`]. - /// - /// **Note**: This method is only available on platforms that support atomic operations on - #[doc = concat!("[`", $s_int_type, "`].")] - /// - /// # Considerations - /// - /// This method is not magic; it is not provided by the hardware. - /// It is implemented in terms of - #[doc = concat!("[`", stringify!($atomic_type), "::compare_exchange_weak`],")] - /// and suffers from the same drawbacks. - /// In particular, this method will not circumvent the [ABA Problem]. - /// - /// [ABA Problem]: https://en.wikipedia.org/wiki/ABA_problem - /// - /// # Examples - /// - /// ```rust - #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")] - /// - #[doc = concat!("let x = ", stringify!($atomic_type), "::new(7);")] - /// assert_eq!(x.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |_| None), Err(7)); - /// assert_eq!(x.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |x| Some(x + 1)), Ok(7)); - /// assert_eq!(x.fetch_update(Ordering::SeqCst, Ordering::SeqCst, |x| Some(x + 1)), Ok(8)); - /// assert_eq!(x.load(Ordering::SeqCst), 9); - /// ``` - #[inline] - #[stable(feature = "no_more_cas", since = "1.45.0")] - #[$cfg_cas] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn fetch_update(&self, - set_order: Ordering, - fetch_order: Ordering, - mut f: F) -> Result<$int_type, $int_type> - where F: FnMut($int_type) -> Option<$int_type> { - let mut prev = self.load(fetch_order); - while let Some(next) = f(prev) { - match self.compare_exchange_weak(prev, next, set_order, fetch_order) { - x @ Ok(_) => return x, - Err(next_prev) => prev = next_prev - } - } - Err(prev) - } - - /// Maximum with the current value. - /// - /// Finds the maximum of the current value and the argument `val`, and - /// sets the new value to the result. - /// - /// Returns the previous value. - /// - /// `fetch_max` takes an [`Ordering`] argument which describes the memory ordering - /// of this operation. All ordering modes are possible. Note that using - /// [`Acquire`] makes the store part of this operation [`Relaxed`], and - /// using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note**: This method is only available on platforms that support atomic operations on - #[doc = concat!("[`", $s_int_type, "`].")] - /// - /// # Examples - /// - /// ``` - #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")] - /// - #[doc = concat!("let foo = ", stringify!($atomic_type), "::new(23);")] - /// assert_eq!(foo.fetch_max(42, Ordering::SeqCst), 23); - /// assert_eq!(foo.load(Ordering::SeqCst), 42); - /// ``` - /// - /// If you want to obtain the maximum value in one step, you can use the following: - /// - /// ``` - #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")] - /// - #[doc = concat!("let foo = ", stringify!($atomic_type), "::new(23);")] - /// let bar = 42; - /// let max_foo = foo.fetch_max(bar, Ordering::SeqCst).max(bar); - /// assert!(max_foo == 42); - /// ``` - #[inline] - #[stable(feature = "atomic_min_max", since = "1.45.0")] - #[$cfg_cas] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn fetch_max(&self, val: $int_type, order: Ordering) -> $int_type { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { $max_fn(self.v.get(), val, order) } - } - - /// Minimum with the current value. - /// - /// Finds the minimum of the current value and the argument `val`, and - /// sets the new value to the result. - /// - /// Returns the previous value. - /// - /// `fetch_min` takes an [`Ordering`] argument which describes the memory ordering - /// of this operation. All ordering modes are possible. Note that using - /// [`Acquire`] makes the store part of this operation [`Relaxed`], and - /// using [`Release`] makes the load part [`Relaxed`]. - /// - /// **Note**: This method is only available on platforms that support atomic operations on - #[doc = concat!("[`", $s_int_type, "`].")] - /// - /// # Examples - /// - /// ``` - #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")] - /// - #[doc = concat!("let foo = ", stringify!($atomic_type), "::new(23);")] - /// assert_eq!(foo.fetch_min(42, Ordering::Relaxed), 23); - /// assert_eq!(foo.load(Ordering::Relaxed), 23); - /// assert_eq!(foo.fetch_min(22, Ordering::Relaxed), 23); - /// assert_eq!(foo.load(Ordering::Relaxed), 22); - /// ``` - /// - /// If you want to obtain the minimum value in one step, you can use the following: - /// - /// ``` - #[doc = concat!($extra_feature, "use std::sync::atomic::{", stringify!($atomic_type), ", Ordering};")] - /// - #[doc = concat!("let foo = ", stringify!($atomic_type), "::new(23);")] - /// let bar = 12; - /// let min_foo = foo.fetch_min(bar, Ordering::SeqCst).min(bar); - /// assert_eq!(min_foo, 12); - /// ``` - #[inline] - #[stable(feature = "atomic_min_max", since = "1.45.0")] - #[$cfg_cas] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub fn fetch_min(&self, val: $int_type, order: Ordering) -> $int_type { - // SAFETY: data races are prevented by atomic intrinsics. - unsafe { $min_fn(self.v.get(), val, order) } - } - - /// Returns a mutable pointer to the underlying integer. - /// - /// Doing non-atomic reads and writes on the resulting integer can be a data race. - /// This method is mostly useful for FFI, where the function signature may use - #[doc = concat!("`*mut ", stringify!($int_type), "` instead of `&", stringify!($atomic_type), "`.")] - /// - /// Returning an `*mut` pointer from a shared reference to this atomic is safe because the - /// atomic types work with interior mutability. All modifications of an atomic change the value - /// through a shared reference, and can do so safely as long as they use atomic operations. Any - /// use of the returned raw pointer requires an `unsafe` block and still has to uphold the same - /// restriction: operations on it must be atomic. - /// - /// # Examples - /// - /// ```ignore (extern-declaration) - /// # fn main() { - #[doc = concat!($extra_feature, "use std::sync::atomic::", stringify!($atomic_type), ";")] - /// - /// extern "C" { - #[doc = concat!(" fn my_atomic_op(arg: *mut ", stringify!($int_type), ");")] - /// } - /// - #[doc = concat!("let atomic = ", stringify!($atomic_type), "::new(1);")] - /// - /// // SAFETY: Safe as long as `my_atomic_op` is atomic. - /// unsafe { - /// my_atomic_op(atomic.as_ptr()); - /// } - /// # } - /// ``` - #[inline] - #[stable(feature = "atomic_as_ptr", since = "1.70.0")] - #[rustc_const_stable(feature = "atomic_as_ptr", since = "1.70.0")] - #[rustc_never_returns_null_ptr] - pub const fn as_ptr(&self) -> *mut $int_type { - self.v.get() - } - } - } -} - -#[cfg(target_has_atomic_load_store = "8")] -atomic_int! { - cfg(target_has_atomic = "8"), - cfg(target_has_atomic_equal_alignment = "8"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - rustc_const_stable(feature = "const_integer_atomics", since = "1.34.0"), - cfg_attr(not(test), rustc_diagnostic_item = "AtomicI8"), - "i8", - "", - atomic_min, atomic_max, - 1, - i8 AtomicI8 -} -#[cfg(target_has_atomic_load_store = "8")] -atomic_int! { - cfg(target_has_atomic = "8"), - cfg(target_has_atomic_equal_alignment = "8"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - rustc_const_stable(feature = "const_integer_atomics", since = "1.34.0"), - cfg_attr(not(test), rustc_diagnostic_item = "AtomicU8"), - "u8", - "", - atomic_umin, atomic_umax, - 1, - u8 AtomicU8 -} -#[cfg(target_has_atomic_load_store = "16")] -atomic_int! { - cfg(target_has_atomic = "16"), - cfg(target_has_atomic_equal_alignment = "16"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - rustc_const_stable(feature = "const_integer_atomics", since = "1.34.0"), - cfg_attr(not(test), rustc_diagnostic_item = "AtomicI16"), - "i16", - "", - atomic_min, atomic_max, - 2, - i16 AtomicI16 -} -#[cfg(target_has_atomic_load_store = "16")] -atomic_int! { - cfg(target_has_atomic = "16"), - cfg(target_has_atomic_equal_alignment = "16"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - rustc_const_stable(feature = "const_integer_atomics", since = "1.34.0"), - cfg_attr(not(test), rustc_diagnostic_item = "AtomicU16"), - "u16", - "", - atomic_umin, atomic_umax, - 2, - u16 AtomicU16 -} -#[cfg(target_has_atomic_load_store = "32")] -atomic_int! { - cfg(target_has_atomic = "32"), - cfg(target_has_atomic_equal_alignment = "32"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - rustc_const_stable(feature = "const_integer_atomics", since = "1.34.0"), - cfg_attr(not(test), rustc_diagnostic_item = "AtomicI32"), - "i32", - "", - atomic_min, atomic_max, - 4, - i32 AtomicI32 -} -#[cfg(target_has_atomic_load_store = "32")] -atomic_int! { - cfg(target_has_atomic = "32"), - cfg(target_has_atomic_equal_alignment = "32"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - rustc_const_stable(feature = "const_integer_atomics", since = "1.34.0"), - cfg_attr(not(test), rustc_diagnostic_item = "AtomicU32"), - "u32", - "", - atomic_umin, atomic_umax, - 4, - u32 AtomicU32 -} -#[cfg(target_has_atomic_load_store = "64")] -atomic_int! { - cfg(target_has_atomic = "64"), - cfg(target_has_atomic_equal_alignment = "64"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - rustc_const_stable(feature = "const_integer_atomics", since = "1.34.0"), - cfg_attr(not(test), rustc_diagnostic_item = "AtomicI64"), - "i64", - "", - atomic_min, atomic_max, - 8, - i64 AtomicI64 -} -#[cfg(target_has_atomic_load_store = "64")] -atomic_int! { - cfg(target_has_atomic = "64"), - cfg(target_has_atomic_equal_alignment = "64"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - stable(feature = "integer_atomics_stable", since = "1.34.0"), - rustc_const_stable(feature = "const_integer_atomics", since = "1.34.0"), - cfg_attr(not(test), rustc_diagnostic_item = "AtomicU64"), - "u64", - "", - atomic_umin, atomic_umax, - 8, - u64 AtomicU64 -} -#[cfg(target_has_atomic_load_store = "128")] -atomic_int! { - cfg(target_has_atomic = "128"), - cfg(target_has_atomic_equal_alignment = "128"), - unstable(feature = "integer_atomics", issue = "99069"), - unstable(feature = "integer_atomics", issue = "99069"), - unstable(feature = "integer_atomics", issue = "99069"), - unstable(feature = "integer_atomics", issue = "99069"), - unstable(feature = "integer_atomics", issue = "99069"), - unstable(feature = "integer_atomics", issue = "99069"), - rustc_const_stable(feature = "const_integer_atomics", since = "1.34.0"), - cfg_attr(not(test), rustc_diagnostic_item = "AtomicI128"), - "i128", - "#![feature(integer_atomics)]\n\n", - atomic_min, atomic_max, - 16, - i128 AtomicI128 -} -#[cfg(target_has_atomic_load_store = "128")] -atomic_int! { - cfg(target_has_atomic = "128"), - cfg(target_has_atomic_equal_alignment = "128"), - unstable(feature = "integer_atomics", issue = "99069"), - unstable(feature = "integer_atomics", issue = "99069"), - unstable(feature = "integer_atomics", issue = "99069"), - unstable(feature = "integer_atomics", issue = "99069"), - unstable(feature = "integer_atomics", issue = "99069"), - unstable(feature = "integer_atomics", issue = "99069"), - rustc_const_stable(feature = "const_integer_atomics", since = "1.34.0"), - cfg_attr(not(test), rustc_diagnostic_item = "AtomicU128"), - "u128", - "#![feature(integer_atomics)]\n\n", - atomic_umin, atomic_umax, - 16, - u128 AtomicU128 -} - -#[cfg(target_has_atomic_load_store = "ptr")] -macro_rules! atomic_int_ptr_sized { - ( $($target_pointer_width:literal $align:literal)* ) => { $( - #[cfg(target_pointer_width = $target_pointer_width)] - atomic_int! { - cfg(target_has_atomic = "ptr"), - cfg(target_has_atomic_equal_alignment = "ptr"), - stable(feature = "rust1", since = "1.0.0"), - stable(feature = "extended_compare_and_swap", since = "1.10.0"), - stable(feature = "atomic_debug", since = "1.3.0"), - stable(feature = "atomic_access", since = "1.15.0"), - stable(feature = "atomic_from", since = "1.23.0"), - stable(feature = "atomic_nand", since = "1.27.0"), - rustc_const_stable(feature = "const_ptr_sized_atomics", since = "1.24.0"), - cfg_attr(not(test), rustc_diagnostic_item = "AtomicIsize"), - "isize", - "", - atomic_min, atomic_max, - $align, - isize AtomicIsize - } - #[cfg(target_pointer_width = $target_pointer_width)] - atomic_int! { - cfg(target_has_atomic = "ptr"), - cfg(target_has_atomic_equal_alignment = "ptr"), - stable(feature = "rust1", since = "1.0.0"), - stable(feature = "extended_compare_and_swap", since = "1.10.0"), - stable(feature = "atomic_debug", since = "1.3.0"), - stable(feature = "atomic_access", since = "1.15.0"), - stable(feature = "atomic_from", since = "1.23.0"), - stable(feature = "atomic_nand", since = "1.27.0"), - rustc_const_stable(feature = "const_ptr_sized_atomics", since = "1.24.0"), - cfg_attr(not(test), rustc_diagnostic_item = "AtomicUsize"), - "usize", - "", - atomic_umin, atomic_umax, - $align, - usize AtomicUsize - } - - /// An [`AtomicIsize`] initialized to `0`. - #[cfg(target_pointer_width = $target_pointer_width)] - #[stable(feature = "rust1", since = "1.0.0")] - #[deprecated( - since = "1.34.0", - note = "the `new` function is now preferred", - suggestion = "AtomicIsize::new(0)", - )] - pub const ATOMIC_ISIZE_INIT: AtomicIsize = AtomicIsize::new(0); - - /// An [`AtomicUsize`] initialized to `0`. - #[cfg(target_pointer_width = $target_pointer_width)] - #[stable(feature = "rust1", since = "1.0.0")] - #[deprecated( - since = "1.34.0", - note = "the `new` function is now preferred", - suggestion = "AtomicUsize::new(0)", - )] - pub const ATOMIC_USIZE_INIT: AtomicUsize = AtomicUsize::new(0); - )* }; -} - -#[cfg(target_has_atomic_load_store = "ptr")] -atomic_int_ptr_sized! { - "16" 2 - "32" 4 - "64" 8 -} - -#[inline] -#[cfg(target_has_atomic)] -fn strongest_failure_ordering(order: Ordering) -> Ordering { - match order { - Release => Relaxed, - Relaxed => Relaxed, - SeqCst => SeqCst, - Acquire => Acquire, - AcqRel => Acquire, - } -} - -#[inline] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -unsafe fn atomic_store(dst: *mut T, val: T, order: Ordering) { - // SAFETY: the caller must uphold the safety contract for `atomic_store`. - unsafe { - match order { - Relaxed => intrinsics::atomic_store_relaxed(dst, val), - Release => intrinsics::atomic_store_release(dst, val), - SeqCst => intrinsics::atomic_store_seqcst(dst, val), - Acquire => panic!("there is no such thing as an acquire store"), - AcqRel => panic!("there is no such thing as an acquire-release store"), - } - } -} - -#[inline] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -unsafe fn atomic_load(dst: *const T, order: Ordering) -> T { - // SAFETY: the caller must uphold the safety contract for `atomic_load`. - unsafe { - match order { - Relaxed => intrinsics::atomic_load_relaxed(dst), - Acquire => intrinsics::atomic_load_acquire(dst), - SeqCst => intrinsics::atomic_load_seqcst(dst), - Release => panic!("there is no such thing as a release load"), - AcqRel => panic!("there is no such thing as an acquire-release load"), - } - } -} - -#[inline] -#[cfg(target_has_atomic)] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -unsafe fn atomic_swap(dst: *mut T, val: T, order: Ordering) -> T { - // SAFETY: the caller must uphold the safety contract for `atomic_swap`. - unsafe { - match order { - Relaxed => intrinsics::atomic_xchg_relaxed(dst, val), - Acquire => intrinsics::atomic_xchg_acquire(dst, val), - Release => intrinsics::atomic_xchg_release(dst, val), - AcqRel => intrinsics::atomic_xchg_acqrel(dst, val), - SeqCst => intrinsics::atomic_xchg_seqcst(dst, val), - } - } -} - -/// Returns the previous value (like __sync_fetch_and_add). -#[inline] -#[cfg(target_has_atomic)] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -unsafe fn atomic_add(dst: *mut T, val: T, order: Ordering) -> T { - // SAFETY: the caller must uphold the safety contract for `atomic_add`. - unsafe { - match order { - Relaxed => intrinsics::atomic_xadd_relaxed(dst, val), - Acquire => intrinsics::atomic_xadd_acquire(dst, val), - Release => intrinsics::atomic_xadd_release(dst, val), - AcqRel => intrinsics::atomic_xadd_acqrel(dst, val), - SeqCst => intrinsics::atomic_xadd_seqcst(dst, val), - } - } -} - -/// Returns the previous value (like __sync_fetch_and_sub). -#[inline] -#[cfg(target_has_atomic)] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -unsafe fn atomic_sub(dst: *mut T, val: T, order: Ordering) -> T { - // SAFETY: the caller must uphold the safety contract for `atomic_sub`. - unsafe { - match order { - Relaxed => intrinsics::atomic_xsub_relaxed(dst, val), - Acquire => intrinsics::atomic_xsub_acquire(dst, val), - Release => intrinsics::atomic_xsub_release(dst, val), - AcqRel => intrinsics::atomic_xsub_acqrel(dst, val), - SeqCst => intrinsics::atomic_xsub_seqcst(dst, val), - } - } -} - -#[inline] -#[cfg(target_has_atomic)] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -unsafe fn atomic_compare_exchange( - dst: *mut T, - old: T, - new: T, - success: Ordering, - failure: Ordering, -) -> Result { - // SAFETY: the caller must uphold the safety contract for `atomic_compare_exchange`. - let (val, ok) = unsafe { - match (success, failure) { - (Relaxed, Relaxed) => intrinsics::atomic_cxchg_relaxed_relaxed(dst, old, new), - (Relaxed, Acquire) => intrinsics::atomic_cxchg_relaxed_acquire(dst, old, new), - (Relaxed, SeqCst) => intrinsics::atomic_cxchg_relaxed_seqcst(dst, old, new), - (Acquire, Relaxed) => intrinsics::atomic_cxchg_acquire_relaxed(dst, old, new), - (Acquire, Acquire) => intrinsics::atomic_cxchg_acquire_acquire(dst, old, new), - (Acquire, SeqCst) => intrinsics::atomic_cxchg_acquire_seqcst(dst, old, new), - (Release, Relaxed) => intrinsics::atomic_cxchg_release_relaxed(dst, old, new), - (Release, Acquire) => intrinsics::atomic_cxchg_release_acquire(dst, old, new), - (Release, SeqCst) => intrinsics::atomic_cxchg_release_seqcst(dst, old, new), - (AcqRel, Relaxed) => intrinsics::atomic_cxchg_acqrel_relaxed(dst, old, new), - (AcqRel, Acquire) => intrinsics::atomic_cxchg_acqrel_acquire(dst, old, new), - (AcqRel, SeqCst) => intrinsics::atomic_cxchg_acqrel_seqcst(dst, old, new), - (SeqCst, Relaxed) => intrinsics::atomic_cxchg_seqcst_relaxed(dst, old, new), - (SeqCst, Acquire) => intrinsics::atomic_cxchg_seqcst_acquire(dst, old, new), - (SeqCst, SeqCst) => intrinsics::atomic_cxchg_seqcst_seqcst(dst, old, new), - (_, AcqRel) => panic!("there is no such thing as an acquire-release failure ordering"), - (_, Release) => panic!("there is no such thing as a release failure ordering"), - } - }; - if ok { Ok(val) } else { Err(val) } -} - -#[inline] -#[cfg(target_has_atomic)] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -unsafe fn atomic_compare_exchange_weak( - dst: *mut T, - old: T, - new: T, - success: Ordering, - failure: Ordering, -) -> Result { - // SAFETY: the caller must uphold the safety contract for `atomic_compare_exchange_weak`. - let (val, ok) = unsafe { - match (success, failure) { - (Relaxed, Relaxed) => intrinsics::atomic_cxchgweak_relaxed_relaxed(dst, old, new), - (Relaxed, Acquire) => intrinsics::atomic_cxchgweak_relaxed_acquire(dst, old, new), - (Relaxed, SeqCst) => intrinsics::atomic_cxchgweak_relaxed_seqcst(dst, old, new), - (Acquire, Relaxed) => intrinsics::atomic_cxchgweak_acquire_relaxed(dst, old, new), - (Acquire, Acquire) => intrinsics::atomic_cxchgweak_acquire_acquire(dst, old, new), - (Acquire, SeqCst) => intrinsics::atomic_cxchgweak_acquire_seqcst(dst, old, new), - (Release, Relaxed) => intrinsics::atomic_cxchgweak_release_relaxed(dst, old, new), - (Release, Acquire) => intrinsics::atomic_cxchgweak_release_acquire(dst, old, new), - (Release, SeqCst) => intrinsics::atomic_cxchgweak_release_seqcst(dst, old, new), - (AcqRel, Relaxed) => intrinsics::atomic_cxchgweak_acqrel_relaxed(dst, old, new), - (AcqRel, Acquire) => intrinsics::atomic_cxchgweak_acqrel_acquire(dst, old, new), - (AcqRel, SeqCst) => intrinsics::atomic_cxchgweak_acqrel_seqcst(dst, old, new), - (SeqCst, Relaxed) => intrinsics::atomic_cxchgweak_seqcst_relaxed(dst, old, new), - (SeqCst, Acquire) => intrinsics::atomic_cxchgweak_seqcst_acquire(dst, old, new), - (SeqCst, SeqCst) => intrinsics::atomic_cxchgweak_seqcst_seqcst(dst, old, new), - (_, AcqRel) => panic!("there is no such thing as an acquire-release failure ordering"), - (_, Release) => panic!("there is no such thing as a release failure ordering"), - } - }; - if ok { Ok(val) } else { Err(val) } -} - -#[inline] -#[cfg(target_has_atomic)] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -unsafe fn atomic_and(dst: *mut T, val: T, order: Ordering) -> T { - // SAFETY: the caller must uphold the safety contract for `atomic_and` - unsafe { - match order { - Relaxed => intrinsics::atomic_and_relaxed(dst, val), - Acquire => intrinsics::atomic_and_acquire(dst, val), - Release => intrinsics::atomic_and_release(dst, val), - AcqRel => intrinsics::atomic_and_acqrel(dst, val), - SeqCst => intrinsics::atomic_and_seqcst(dst, val), - } - } -} - -#[inline] -#[cfg(target_has_atomic)] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -unsafe fn atomic_nand(dst: *mut T, val: T, order: Ordering) -> T { - // SAFETY: the caller must uphold the safety contract for `atomic_nand` - unsafe { - match order { - Relaxed => intrinsics::atomic_nand_relaxed(dst, val), - Acquire => intrinsics::atomic_nand_acquire(dst, val), - Release => intrinsics::atomic_nand_release(dst, val), - AcqRel => intrinsics::atomic_nand_acqrel(dst, val), - SeqCst => intrinsics::atomic_nand_seqcst(dst, val), - } - } -} - -#[inline] -#[cfg(target_has_atomic)] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -unsafe fn atomic_or(dst: *mut T, val: T, order: Ordering) -> T { - // SAFETY: the caller must uphold the safety contract for `atomic_or` - unsafe { - match order { - SeqCst => intrinsics::atomic_or_seqcst(dst, val), - Acquire => intrinsics::atomic_or_acquire(dst, val), - Release => intrinsics::atomic_or_release(dst, val), - AcqRel => intrinsics::atomic_or_acqrel(dst, val), - Relaxed => intrinsics::atomic_or_relaxed(dst, val), - } - } -} - -#[inline] -#[cfg(target_has_atomic)] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -unsafe fn atomic_xor(dst: *mut T, val: T, order: Ordering) -> T { - // SAFETY: the caller must uphold the safety contract for `atomic_xor` - unsafe { - match order { - SeqCst => intrinsics::atomic_xor_seqcst(dst, val), - Acquire => intrinsics::atomic_xor_acquire(dst, val), - Release => intrinsics::atomic_xor_release(dst, val), - AcqRel => intrinsics::atomic_xor_acqrel(dst, val), - Relaxed => intrinsics::atomic_xor_relaxed(dst, val), - } - } -} - -/// returns the max value (signed comparison) -#[inline] -#[cfg(target_has_atomic)] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -unsafe fn atomic_max(dst: *mut T, val: T, order: Ordering) -> T { - // SAFETY: the caller must uphold the safety contract for `atomic_max` - unsafe { - match order { - Relaxed => intrinsics::atomic_max_relaxed(dst, val), - Acquire => intrinsics::atomic_max_acquire(dst, val), - Release => intrinsics::atomic_max_release(dst, val), - AcqRel => intrinsics::atomic_max_acqrel(dst, val), - SeqCst => intrinsics::atomic_max_seqcst(dst, val), - } - } -} - -/// returns the min value (signed comparison) -#[inline] -#[cfg(target_has_atomic)] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -unsafe fn atomic_min(dst: *mut T, val: T, order: Ordering) -> T { - // SAFETY: the caller must uphold the safety contract for `atomic_min` - unsafe { - match order { - Relaxed => intrinsics::atomic_min_relaxed(dst, val), - Acquire => intrinsics::atomic_min_acquire(dst, val), - Release => intrinsics::atomic_min_release(dst, val), - AcqRel => intrinsics::atomic_min_acqrel(dst, val), - SeqCst => intrinsics::atomic_min_seqcst(dst, val), - } - } -} - -/// returns the max value (unsigned comparison) -#[inline] -#[cfg(target_has_atomic)] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -unsafe fn atomic_umax(dst: *mut T, val: T, order: Ordering) -> T { - // SAFETY: the caller must uphold the safety contract for `atomic_umax` - unsafe { - match order { - Relaxed => intrinsics::atomic_umax_relaxed(dst, val), - Acquire => intrinsics::atomic_umax_acquire(dst, val), - Release => intrinsics::atomic_umax_release(dst, val), - AcqRel => intrinsics::atomic_umax_acqrel(dst, val), - SeqCst => intrinsics::atomic_umax_seqcst(dst, val), - } - } -} - -/// returns the min value (unsigned comparison) -#[inline] -#[cfg(target_has_atomic)] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -unsafe fn atomic_umin(dst: *mut T, val: T, order: Ordering) -> T { - // SAFETY: the caller must uphold the safety contract for `atomic_umin` - unsafe { - match order { - Relaxed => intrinsics::atomic_umin_relaxed(dst, val), - Acquire => intrinsics::atomic_umin_acquire(dst, val), - Release => intrinsics::atomic_umin_release(dst, val), - AcqRel => intrinsics::atomic_umin_acqrel(dst, val), - SeqCst => intrinsics::atomic_umin_seqcst(dst, val), - } - } -} - -/// An atomic fence. -/// -/// Depending on the specified order, a fence prevents the compiler and CPU from -/// reordering certain types of memory operations around it. -/// That creates synchronizes-with relationships between it and atomic operations -/// or fences in other threads. -/// -/// A fence 'A' which has (at least) [`Release`] ordering semantics, synchronizes -/// with a fence 'B' with (at least) [`Acquire`] semantics, if and only if there -/// exist operations X and Y, both operating on some atomic object 'M' such -/// that A is sequenced before X, Y is sequenced before B and Y observes -/// the change to M. This provides a happens-before dependence between A and B. -/// -/// ```text -/// Thread 1 Thread 2 -/// -/// fence(Release); A -------------- -/// x.store(3, Relaxed); X --------- | -/// | | -/// | | -/// -------------> Y if x.load(Relaxed) == 3 { -/// |-------> B fence(Acquire); -/// ... -/// } -/// ``` -/// -/// Atomic operations with [`Release`] or [`Acquire`] semantics can also synchronize -/// with a fence. -/// -/// A fence which has [`SeqCst`] ordering, in addition to having both [`Acquire`] -/// and [`Release`] semantics, participates in the global program order of the -/// other [`SeqCst`] operations and/or fences. -/// -/// Accepts [`Acquire`], [`Release`], [`AcqRel`] and [`SeqCst`] orderings. -/// -/// # Panics -/// -/// Panics if `order` is [`Relaxed`]. -/// -/// # Examples -/// -/// ``` -/// use std::sync::atomic::AtomicBool; -/// use std::sync::atomic::fence; -/// use std::sync::atomic::Ordering; -/// -/// // A mutual exclusion primitive based on spinlock. -/// pub struct Mutex { -/// flag: AtomicBool, -/// } -/// -/// impl Mutex { -/// pub fn new() -> Mutex { -/// Mutex { -/// flag: AtomicBool::new(false), -/// } -/// } -/// -/// pub fn lock(&self) { -/// // Wait until the old value is `false`. -/// while self -/// .flag -/// .compare_exchange_weak(false, true, Ordering::Relaxed, Ordering::Relaxed) -/// .is_err() -/// {} -/// // This fence synchronizes-with store in `unlock`. -/// fence(Ordering::Acquire); -/// } -/// -/// pub fn unlock(&self) { -/// self.flag.store(false, Ordering::Release); -/// } -/// } -/// ``` -#[inline] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_diagnostic_item = "fence"] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -pub fn fence(order: Ordering) { - // SAFETY: using an atomic fence is safe. - unsafe { - match order { - Acquire => intrinsics::atomic_fence_acquire(), - Release => intrinsics::atomic_fence_release(), - AcqRel => intrinsics::atomic_fence_acqrel(), - SeqCst => intrinsics::atomic_fence_seqcst(), - Relaxed => panic!("there is no such thing as a relaxed fence"), - } - } -} - -/// A compiler memory fence. -/// -/// `compiler_fence` does not emit any machine code, but restricts the kinds -/// of memory re-ordering the compiler is allowed to do. Specifically, depending on -/// the given [`Ordering`] semantics, the compiler may be disallowed from moving reads -/// or writes from before or after the call to the other side of the call to -/// `compiler_fence`. Note that it does **not** prevent the *hardware* -/// from doing such re-ordering. This is not a problem in a single-threaded, -/// execution context, but when other threads may modify memory at the same -/// time, stronger synchronization primitives such as [`fence`] are required. -/// -/// The re-ordering prevented by the different ordering semantics are: -/// -/// - with [`SeqCst`], no re-ordering of reads and writes across this point is allowed. -/// - with [`Release`], preceding reads and writes cannot be moved past subsequent writes. -/// - with [`Acquire`], subsequent reads and writes cannot be moved ahead of preceding reads. -/// - with [`AcqRel`], both of the above rules are enforced. -/// -/// `compiler_fence` is generally only useful for preventing a thread from -/// racing *with itself*. That is, if a given thread is executing one piece -/// of code, and is then interrupted, and starts executing code elsewhere -/// (while still in the same thread, and conceptually still on the same -/// core). In traditional programs, this can only occur when a signal -/// handler is registered. In more low-level code, such situations can also -/// arise when handling interrupts, when implementing green threads with -/// pre-emption, etc. Curious readers are encouraged to read the Linux kernel's -/// discussion of [memory barriers]. -/// -/// # Panics -/// -/// Panics if `order` is [`Relaxed`]. -/// -/// # Examples -/// -/// Without `compiler_fence`, the `assert_eq!` in following code -/// is *not* guaranteed to succeed, despite everything happening in a single thread. -/// To see why, remember that the compiler is free to swap the stores to -/// `IMPORTANT_VARIABLE` and `IS_READY` since they are both -/// `Ordering::Relaxed`. If it does, and the signal handler is invoked right -/// after `IS_READY` is updated, then the signal handler will see -/// `IS_READY=1`, but `IMPORTANT_VARIABLE=0`. -/// Using a `compiler_fence` remedies this situation. -/// -/// ``` -/// use std::sync::atomic::{AtomicBool, AtomicUsize}; -/// use std::sync::atomic::Ordering; -/// use std::sync::atomic::compiler_fence; -/// -/// static IMPORTANT_VARIABLE: AtomicUsize = AtomicUsize::new(0); -/// static IS_READY: AtomicBool = AtomicBool::new(false); -/// -/// fn main() { -/// IMPORTANT_VARIABLE.store(42, Ordering::Relaxed); -/// // prevent earlier writes from being moved beyond this point -/// compiler_fence(Ordering::Release); -/// IS_READY.store(true, Ordering::Relaxed); -/// } -/// -/// fn signal_handler() { -/// if IS_READY.load(Ordering::Relaxed) { -/// assert_eq!(IMPORTANT_VARIABLE.load(Ordering::Relaxed), 42); -/// } -/// } -/// ``` -/// -/// [memory barriers]: https://www.kernel.org/doc/Documentation/memory-barriers.txt -#[inline] -#[stable(feature = "compiler_fences", since = "1.21.0")] -#[rustc_diagnostic_item = "compiler_fence"] -#[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces -pub fn compiler_fence(order: Ordering) { - // SAFETY: using an atomic fence is safe. - unsafe { - match order { - Acquire => intrinsics::atomic_singlethreadfence_acquire(), - Release => intrinsics::atomic_singlethreadfence_release(), - AcqRel => intrinsics::atomic_singlethreadfence_acqrel(), - SeqCst => intrinsics::atomic_singlethreadfence_seqcst(), - Relaxed => panic!("there is no such thing as a relaxed compiler fence"), - } - } -} - -#[cfg(target_has_atomic_load_store = "8")] -#[stable(feature = "atomic_debug", since = "1.3.0")] -impl fmt::Debug for AtomicBool { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&self.load(Ordering::Relaxed), f) - } -} - -#[cfg(target_has_atomic_load_store = "ptr")] -#[stable(feature = "atomic_debug", since = "1.3.0")] -impl fmt::Debug for AtomicPtr { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&self.load(Ordering::Relaxed), f) - } -} - -#[cfg(target_has_atomic_load_store = "ptr")] -#[stable(feature = "atomic_pointer", since = "1.24.0")] -impl fmt::Pointer for AtomicPtr { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Pointer::fmt(&self.load(Ordering::SeqCst), f) - } -} - -/// Signals the processor that it is inside a busy-wait spin-loop ("spin lock"). -/// -/// This function is deprecated in favor of [`hint::spin_loop`]. -/// -/// [`hint::spin_loop`]: crate::hint::spin_loop -#[inline] -#[stable(feature = "spin_loop_hint", since = "1.24.0")] -#[deprecated(since = "1.51.0", note = "use hint::spin_loop instead")] -pub fn spin_loop_hint() { - spin_loop() -} diff --git a/library/core/src/sync/exclusive.rs b/library/core/src/sync/exclusive.rs deleted file mode 100644 index e8170c13ed263..0000000000000 --- a/library/core/src/sync/exclusive.rs +++ /dev/null @@ -1,221 +0,0 @@ -//! Defines [`Exclusive`]. - -use core::fmt; -use core::future::Future; -use core::marker::Tuple; -use core::ops::{Coroutine, CoroutineState}; -use core::pin::Pin; -use core::task::{Context, Poll}; - -/// `Exclusive` provides only _mutable_ access, also referred to as _exclusive_ -/// access to the underlying value. It provides no _immutable_, or _shared_ -/// access to the underlying value. -/// -/// While this may seem not very useful, it allows `Exclusive` to _unconditionally_ -/// implement [`Sync`]. Indeed, the safety requirements of `Sync` state that for `Exclusive` -/// to be `Sync`, it must be sound to _share_ across threads, that is, it must be sound -/// for `&Exclusive` to cross thread boundaries. By design, a `&Exclusive` has no API -/// whatsoever, making it useless, thus harmless, thus memory safe. -/// -/// Certain constructs like [`Future`]s can only be used with _exclusive_ access, -/// and are often `Send` but not `Sync`, so `Exclusive` can be used as hint to the -/// Rust compiler that something is `Sync` in practice. -/// -/// ## Examples -/// Using a non-`Sync` future prevents the wrapping struct from being `Sync` -/// ```compile_fail -/// use core::cell::Cell; -/// -/// async fn other() {} -/// fn assert_sync(t: T) {} -/// struct State { -/// future: F -/// } -/// -/// assert_sync(State { -/// future: async { -/// let cell = Cell::new(1); -/// let cell_ref = &cell; -/// other().await; -/// let value = cell_ref.get(); -/// } -/// }); -/// ``` -/// -/// `Exclusive` ensures the struct is `Sync` without stripping the future of its -/// functionality. -/// ``` -/// #![feature(exclusive_wrapper)] -/// use core::cell::Cell; -/// use core::sync::Exclusive; -/// -/// async fn other() {} -/// fn assert_sync(t: T) {} -/// struct State { -/// future: Exclusive -/// } -/// -/// assert_sync(State { -/// future: Exclusive::new(async { -/// let cell = Cell::new(1); -/// let cell_ref = &cell; -/// other().await; -/// let value = cell_ref.get(); -/// }) -/// }); -/// ``` -/// -/// ## Parallels with a mutex -/// In some sense, `Exclusive` can be thought of as a _compile-time_ version of -/// a mutex, as the borrow-checker guarantees that only one `&mut` can exist -/// for any value. This is a parallel with the fact that -/// `&` and `&mut` references together can be thought of as a _compile-time_ -/// version of a read-write lock. -#[unstable(feature = "exclusive_wrapper", issue = "98407")] -#[doc(alias = "SyncWrapper")] -#[doc(alias = "SyncCell")] -#[doc(alias = "Unique")] -// `Exclusive` can't have `PartialOrd`, `Clone`, etc. impls as they would -// use `&` access to the inner value, violating the `Sync` impl's safety -// requirements. -#[derive(Default)] -#[repr(transparent)] -pub struct Exclusive { - inner: T, -} - -// See `Exclusive`'s docs for justification. -#[unstable(feature = "exclusive_wrapper", issue = "98407")] -unsafe impl Sync for Exclusive {} - -#[unstable(feature = "exclusive_wrapper", issue = "98407")] -impl fmt::Debug for Exclusive { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> Result<(), fmt::Error> { - f.debug_struct("Exclusive").finish_non_exhaustive() - } -} - -impl Exclusive { - /// Wrap a value in an `Exclusive` - #[unstable(feature = "exclusive_wrapper", issue = "98407")] - #[must_use] - #[inline] - pub const fn new(t: T) -> Self { - Self { inner: t } - } - - /// Unwrap the value contained in the `Exclusive` - #[unstable(feature = "exclusive_wrapper", issue = "98407")] - #[must_use] - #[inline] - pub const fn into_inner(self) -> T { - self.inner - } -} - -impl Exclusive { - /// Get exclusive access to the underlying value. - #[unstable(feature = "exclusive_wrapper", issue = "98407")] - #[must_use] - #[inline] - pub const fn get_mut(&mut self) -> &mut T { - &mut self.inner - } - - /// Get pinned exclusive access to the underlying value. - /// - /// `Exclusive` is considered to _structurally pin_ the underlying - /// value, which means _unpinned_ `Exclusive`s can produce _unpinned_ - /// access to the underlying value, but _pinned_ `Exclusive`s only - /// produce _pinned_ access to the underlying value. - #[unstable(feature = "exclusive_wrapper", issue = "98407")] - #[must_use] - #[inline] - pub const fn get_pin_mut(self: Pin<&mut Self>) -> Pin<&mut T> { - // SAFETY: `Exclusive` can only produce `&mut T` if itself is unpinned - // `Pin::map_unchecked_mut` is not const, so we do this conversion manually - unsafe { Pin::new_unchecked(&mut self.get_unchecked_mut().inner) } - } - - /// Build a _mutable_ reference to an `Exclusive` from - /// a _mutable_ reference to a `T`. This allows you to skip - /// building an `Exclusive` with [`Exclusive::new`]. - #[unstable(feature = "exclusive_wrapper", issue = "98407")] - #[must_use] - #[inline] - pub const fn from_mut(r: &'_ mut T) -> &'_ mut Exclusive { - // SAFETY: repr is ≥ C, so refs have the same layout; and `Exclusive` properties are `&mut`-agnostic - unsafe { &mut *(r as *mut T as *mut Exclusive) } - } - - /// Build a _pinned mutable_ reference to an `Exclusive` from - /// a _pinned mutable_ reference to a `T`. This allows you to skip - /// building an `Exclusive` with [`Exclusive::new`]. - #[unstable(feature = "exclusive_wrapper", issue = "98407")] - #[must_use] - #[inline] - pub const fn from_pin_mut(r: Pin<&'_ mut T>) -> Pin<&'_ mut Exclusive> { - // SAFETY: `Exclusive` can only produce `&mut T` if itself is unpinned - // `Pin::map_unchecked_mut` is not const, so we do this conversion manually - unsafe { Pin::new_unchecked(Self::from_mut(r.get_unchecked_mut())) } - } -} - -#[unstable(feature = "exclusive_wrapper", issue = "98407")] -impl From for Exclusive { - #[inline] - fn from(t: T) -> Self { - Self::new(t) - } -} - -#[unstable(feature = "exclusive_wrapper", issue = "98407")] -impl FnOnce for Exclusive -where - F: FnOnce, - Args: Tuple, -{ - type Output = F::Output; - - extern "rust-call" fn call_once(self, args: Args) -> Self::Output { - self.into_inner().call_once(args) - } -} - -#[unstable(feature = "exclusive_wrapper", issue = "98407")] -impl FnMut for Exclusive -where - F: FnMut, - Args: Tuple, -{ - extern "rust-call" fn call_mut(&mut self, args: Args) -> Self::Output { - self.get_mut().call_mut(args) - } -} - -#[unstable(feature = "exclusive_wrapper", issue = "98407")] -impl Future for Exclusive -where - T: Future + ?Sized, -{ - type Output = T::Output; - - #[inline] - fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll { - self.get_pin_mut().poll(cx) - } -} - -#[unstable(feature = "coroutine_trait", issue = "43122")] // also #98407 -impl Coroutine for Exclusive -where - G: Coroutine + ?Sized, -{ - type Yield = G::Yield; - type Return = G::Return; - - #[inline] - fn resume(self: Pin<&mut Self>, arg: R) -> CoroutineState { - G::resume(self.get_pin_mut(), arg) - } -} diff --git a/library/core/src/sync/mod.rs b/library/core/src/sync/mod.rs deleted file mode 100644 index 4365e4cb250ca..0000000000000 --- a/library/core/src/sync/mod.rs +++ /dev/null @@ -1,8 +0,0 @@ -//! Synchronization primitives - -#![stable(feature = "rust1", since = "1.0.0")] - -pub mod atomic; -mod exclusive; -#[unstable(feature = "exclusive_wrapper", issue = "98407")] -pub use exclusive::Exclusive; diff --git a/library/core/src/task/mod.rs b/library/core/src/task/mod.rs deleted file mode 100644 index f1a789e32a7a7..0000000000000 --- a/library/core/src/task/mod.rs +++ /dev/null @@ -1,15 +0,0 @@ -#![stable(feature = "futures_api", since = "1.36.0")] - -//! Types and Traits for working with asynchronous tasks. - -mod poll; -#[stable(feature = "futures_api", since = "1.36.0")] -pub use self::poll::Poll; - -mod wake; -#[stable(feature = "futures_api", since = "1.36.0")] -pub use self::wake::{Context, ContextBuilder, LocalWaker, RawWaker, RawWakerVTable, Waker}; - -mod ready; -#[stable(feature = "ready_macro", since = "1.64.0")] -pub use ready::ready; diff --git a/library/core/src/task/poll.rs b/library/core/src/task/poll.rs deleted file mode 100644 index bfa1cf096e237..0000000000000 --- a/library/core/src/task/poll.rs +++ /dev/null @@ -1,291 +0,0 @@ -#![stable(feature = "futures_api", since = "1.36.0")] - -use crate::convert; -use crate::ops::{self, ControlFlow}; - -/// Indicates whether a value is available or if the current task has been -/// scheduled to receive a wakeup instead. -#[must_use = "this `Poll` may be a `Pending` variant, which should be handled"] -#[derive(Copy, Clone, Debug, Eq, PartialEq, Ord, PartialOrd, Hash)] -#[lang = "Poll"] -#[stable(feature = "futures_api", since = "1.36.0")] -pub enum Poll { - /// Represents that a value is immediately ready. - #[lang = "Ready"] - #[stable(feature = "futures_api", since = "1.36.0")] - Ready(#[stable(feature = "futures_api", since = "1.36.0")] T), - - /// Represents that a value is not ready yet. - /// - /// When a function returns `Pending`, the function *must* also - /// ensure that the current task is scheduled to be awoken when - /// progress can be made. - #[lang = "Pending"] - #[stable(feature = "futures_api", since = "1.36.0")] - Pending, -} - -impl Poll { - /// Maps a `Poll` to `Poll` by applying a function to a contained value. - /// - /// # Examples - /// - /// Converts a Poll<[String]> into a Poll<[usize]>, consuming - /// the original: - /// - /// [String]: ../../std/string/struct.String.html "String" - /// ``` - /// # use core::task::Poll; - /// let poll_some_string = Poll::Ready(String::from("Hello, World!")); - /// // `Poll::map` takes self *by value*, consuming `poll_some_string` - /// let poll_some_len = poll_some_string.map(|s| s.len()); - /// - /// assert_eq!(poll_some_len, Poll::Ready(13)); - /// ``` - #[stable(feature = "futures_api", since = "1.36.0")] - #[inline] - pub fn map(self, f: F) -> Poll - where - F: FnOnce(T) -> U, - { - match self { - Poll::Ready(t) => Poll::Ready(f(t)), - Poll::Pending => Poll::Pending, - } - } - - /// Returns `true` if the poll is a [`Poll::Ready`] value. - /// - /// # Examples - /// - /// ``` - /// # use core::task::Poll; - /// let x: Poll = Poll::Ready(2); - /// assert_eq!(x.is_ready(), true); - /// - /// let x: Poll = Poll::Pending; - /// assert_eq!(x.is_ready(), false); - /// ``` - #[inline] - #[rustc_const_stable(feature = "const_poll", since = "1.49.0")] - #[stable(feature = "futures_api", since = "1.36.0")] - pub const fn is_ready(&self) -> bool { - matches!(*self, Poll::Ready(_)) - } - - /// Returns `true` if the poll is a [`Pending`] value. - /// - /// [`Pending`]: Poll::Pending - /// - /// # Examples - /// - /// ``` - /// # use core::task::Poll; - /// let x: Poll = Poll::Ready(2); - /// assert_eq!(x.is_pending(), false); - /// - /// let x: Poll = Poll::Pending; - /// assert_eq!(x.is_pending(), true); - /// ``` - #[inline] - #[rustc_const_stable(feature = "const_poll", since = "1.49.0")] - #[stable(feature = "futures_api", since = "1.36.0")] - pub const fn is_pending(&self) -> bool { - !self.is_ready() - } -} - -impl Poll> { - /// Maps a `Poll>` to `Poll>` by applying a - /// function to a contained `Poll::Ready(Ok)` value, leaving all other - /// variants untouched. - /// - /// This function can be used to compose the results of two functions. - /// - /// # Examples - /// - /// ``` - /// # use core::task::Poll; - /// let res: Poll> = Poll::Ready("12".parse()); - /// let squared = res.map_ok(|n| n * n); - /// assert_eq!(squared, Poll::Ready(Ok(144))); - /// ``` - #[stable(feature = "futures_api", since = "1.36.0")] - #[inline] - pub fn map_ok(self, f: F) -> Poll> - where - F: FnOnce(T) -> U, - { - match self { - Poll::Ready(Ok(t)) => Poll::Ready(Ok(f(t))), - Poll::Ready(Err(e)) => Poll::Ready(Err(e)), - Poll::Pending => Poll::Pending, - } - } - - /// Maps a `Poll::Ready>` to `Poll::Ready>` by - /// applying a function to a contained `Poll::Ready(Err)` value, leaving all other - /// variants untouched. - /// - /// This function can be used to pass through a successful result while handling - /// an error. - /// - /// # Examples - /// - /// ``` - /// # use core::task::Poll; - /// let res: Poll> = Poll::Ready("oops".parse()); - /// let res = res.map_err(|_| 0_u8); - /// assert_eq!(res, Poll::Ready(Err(0))); - /// ``` - #[stable(feature = "futures_api", since = "1.36.0")] - #[inline] - pub fn map_err(self, f: F) -> Poll> - where - F: FnOnce(E) -> U, - { - match self { - Poll::Ready(Ok(t)) => Poll::Ready(Ok(t)), - Poll::Ready(Err(e)) => Poll::Ready(Err(f(e))), - Poll::Pending => Poll::Pending, - } - } -} - -impl Poll>> { - /// Maps a `Poll>>` to `Poll>>` by - /// applying a function to a contained `Poll::Ready(Some(Ok))` value, - /// leaving all other variants untouched. - /// - /// This function can be used to compose the results of two functions. - /// - /// # Examples - /// - /// ``` - /// # use core::task::Poll; - /// let res: Poll>> = Poll::Ready(Some("12".parse())); - /// let squared = res.map_ok(|n| n * n); - /// assert_eq!(squared, Poll::Ready(Some(Ok(144)))); - /// ``` - #[stable(feature = "poll_map", since = "1.51.0")] - #[inline] - pub fn map_ok(self, f: F) -> Poll>> - where - F: FnOnce(T) -> U, - { - match self { - Poll::Ready(Some(Ok(t))) => Poll::Ready(Some(Ok(f(t)))), - Poll::Ready(Some(Err(e))) => Poll::Ready(Some(Err(e))), - Poll::Ready(None) => Poll::Ready(None), - Poll::Pending => Poll::Pending, - } - } - - /// Maps a `Poll::Ready>>` to - /// `Poll::Ready>>` by applying a function to a - /// contained `Poll::Ready(Some(Err))` value, leaving all other variants - /// untouched. - /// - /// This function can be used to pass through a successful result while handling - /// an error. - /// - /// # Examples - /// - /// ``` - /// # use core::task::Poll; - /// let res: Poll>> = Poll::Ready(Some("oops".parse())); - /// let res = res.map_err(|_| 0_u8); - /// assert_eq!(res, Poll::Ready(Some(Err(0)))); - /// ``` - #[stable(feature = "poll_map", since = "1.51.0")] - #[inline] - pub fn map_err(self, f: F) -> Poll>> - where - F: FnOnce(E) -> U, - { - match self { - Poll::Ready(Some(Ok(t))) => Poll::Ready(Some(Ok(t))), - Poll::Ready(Some(Err(e))) => Poll::Ready(Some(Err(f(e)))), - Poll::Ready(None) => Poll::Ready(None), - Poll::Pending => Poll::Pending, - } - } -} - -#[stable(feature = "futures_api", since = "1.36.0")] -impl From for Poll { - /// Moves the value into a [`Poll::Ready`] to make a `Poll`. - /// - /// # Example - /// - /// ``` - /// # use core::task::Poll; - /// assert_eq!(Poll::from(true), Poll::Ready(true)); - /// ``` - fn from(t: T) -> Poll { - Poll::Ready(t) - } -} - -#[unstable(feature = "try_trait_v2", issue = "84277")] -impl ops::Try for Poll> { - type Output = Poll; - type Residual = Result; - - #[inline] - fn from_output(c: Self::Output) -> Self { - c.map(Ok) - } - - #[inline] - fn branch(self) -> ControlFlow { - match self { - Poll::Ready(Ok(x)) => ControlFlow::Continue(Poll::Ready(x)), - Poll::Ready(Err(e)) => ControlFlow::Break(Err(e)), - Poll::Pending => ControlFlow::Continue(Poll::Pending), - } - } -} - -#[unstable(feature = "try_trait_v2", issue = "84277")] -impl> ops::FromResidual> for Poll> { - #[inline] - fn from_residual(x: Result) -> Self { - match x { - Err(e) => Poll::Ready(Err(From::from(e))), - } - } -} - -#[unstable(feature = "try_trait_v2", issue = "84277")] -impl ops::Try for Poll>> { - type Output = Poll>; - type Residual = Result; - - #[inline] - fn from_output(c: Self::Output) -> Self { - c.map(|x| x.map(Ok)) - } - - #[inline] - fn branch(self) -> ControlFlow { - match self { - Poll::Ready(Some(Ok(x))) => ControlFlow::Continue(Poll::Ready(Some(x))), - Poll::Ready(Some(Err(e))) => ControlFlow::Break(Err(e)), - Poll::Ready(None) => ControlFlow::Continue(Poll::Ready(None)), - Poll::Pending => ControlFlow::Continue(Poll::Pending), - } - } -} - -#[unstable(feature = "try_trait_v2", issue = "84277")] -impl> ops::FromResidual> - for Poll>> -{ - #[inline] - fn from_residual(x: Result) -> Self { - match x { - Err(e) => Poll::Ready(Some(Err(From::from(e)))), - } - } -} diff --git a/library/core/src/task/ready.rs b/library/core/src/task/ready.rs deleted file mode 100644 index 495d72fd14be2..0000000000000 --- a/library/core/src/task/ready.rs +++ /dev/null @@ -1,57 +0,0 @@ -/// Extracts the successful type of a [`Poll`]. -/// -/// This macro bakes in propagation of [`Pending`] signals by returning early. -/// -/// [`Poll`]: crate::task::Poll -/// [`Pending`]: crate::task::Poll::Pending -/// -/// # Examples -/// -/// ``` -/// use std::task::{ready, Context, Poll}; -/// use std::future::{self, Future}; -/// use std::pin::Pin; -/// -/// pub fn do_poll(cx: &mut Context<'_>) -> Poll<()> { -/// let mut fut = future::ready(42); -/// let fut = Pin::new(&mut fut); -/// -/// let num = ready!(fut.poll(cx)); -/// # let _ = num; -/// // ... use num -/// -/// Poll::Ready(()) -/// } -/// ``` -/// -/// The `ready!` call expands to: -/// -/// ``` -/// # use std::task::{Context, Poll}; -/// # use std::future::{self, Future}; -/// # use std::pin::Pin; -/// # -/// # pub fn do_poll(cx: &mut Context<'_>) -> Poll<()> { -/// # let mut fut = future::ready(42); -/// # let fut = Pin::new(&mut fut); -/// # -/// let num = match fut.poll(cx) { -/// Poll::Ready(t) => t, -/// Poll::Pending => return Poll::Pending, -/// }; -/// # let _ = num; // to silence unused warning -/// # // ... use num -/// # -/// # Poll::Ready(()) -/// # } -/// ``` -#[stable(feature = "ready_macro", since = "1.64.0")] -#[rustc_macro_transparency = "semitransparent"] -pub macro ready($e:expr) { - match $e { - $crate::task::Poll::Ready(t) => t, - $crate::task::Poll::Pending => { - return $crate::task::Poll::Pending; - } - } -} diff --git a/library/core/src/task/wake.rs b/library/core/src/task/wake.rs deleted file mode 100644 index 3d21b09fa8a02..0000000000000 --- a/library/core/src/task/wake.rs +++ /dev/null @@ -1,876 +0,0 @@ -#![stable(feature = "futures_api", since = "1.36.0")] - -use crate::mem::transmute; - -use crate::any::Any; -use crate::fmt; -use crate::marker::PhantomData; -use crate::panic::AssertUnwindSafe; -use crate::ptr; - -/// A `RawWaker` allows the implementor of a task executor to create a [`Waker`] -/// or a [`LocalWaker`] which provides customized wakeup behavior. -/// -/// It consists of a data pointer and a [virtual function pointer table (vtable)][vtable] -/// that customizes the behavior of the `RawWaker`. -/// -/// `RawWaker`s are unsafe to use. -/// Implementing the [`Wake`] trait is a safe alternative that requires memory allocation. -/// -/// [vtable]: https://en.wikipedia.org/wiki/Virtual_method_table -/// [`Wake`]: ../../alloc/task/trait.Wake.html -#[derive(PartialEq, Debug)] -#[stable(feature = "futures_api", since = "1.36.0")] -pub struct RawWaker { - /// A data pointer, which can be used to store arbitrary data as required - /// by the executor. This could be e.g. a type-erased pointer to an `Arc` - /// that is associated with the task. - /// The value of this field gets passed to all functions that are part of - /// the vtable as the first parameter. - data: *const (), - /// Virtual function pointer table that customizes the behavior of this waker. - vtable: &'static RawWakerVTable, -} - -impl RawWaker { - /// Creates a new `RawWaker` from the provided `data` pointer and `vtable`. - /// - /// The `data` pointer can be used to store arbitrary data as required - /// by the executor. This could be e.g. a type-erased pointer to an `Arc` - /// that is associated with the task. - /// The value of this pointer will get passed to all functions that are part - /// of the `vtable` as the first parameter. - /// - /// It is important to consider that the `data` pointer must point to a - /// thread safe type such as an `[Arc]` - /// when used to construct a [`Waker`]. This restriction is lifted when - /// constructing a [`LocalWaker`], which allows using types that do not implement - /// [Send] + [Sync] like `[Rc]`. - /// - /// The `vtable` customizes the behavior of a `Waker` which gets created - /// from a `RawWaker`. For each operation on the `Waker`, the associated - /// function in the `vtable` of the underlying `RawWaker` will be called. - /// - /// [`Arc`]: std::sync::Arc - /// [`Rc`]: std::rc::Rc - #[inline] - #[rustc_promotable] - #[stable(feature = "futures_api", since = "1.36.0")] - #[rustc_const_stable(feature = "futures_api", since = "1.36.0")] - #[must_use] - pub const fn new(data: *const (), vtable: &'static RawWakerVTable) -> RawWaker { - RawWaker { data, vtable } - } - - /// Get the `data` pointer used to create this `RawWaker`. - #[inline] - #[must_use] - #[unstable(feature = "waker_getters", issue = "96992")] - pub fn data(&self) -> *const () { - self.data - } - - /// Get the `vtable` pointer used to create this `RawWaker`. - #[inline] - #[must_use] - #[unstable(feature = "waker_getters", issue = "96992")] - pub fn vtable(&self) -> &'static RawWakerVTable { - self.vtable - } - - #[unstable(feature = "noop_waker", issue = "98286")] - const NOOP: RawWaker = { - const VTABLE: RawWakerVTable = RawWakerVTable::new( - // Cloning just returns a new no-op raw waker - |_| RawWaker::NOOP, - // `wake` does nothing - |_| {}, - // `wake_by_ref` does nothing - |_| {}, - // Dropping does nothing as we don't allocate anything - |_| {}, - ); - RawWaker::new(ptr::null(), &VTABLE) - }; -} - -/// A virtual function pointer table (vtable) that specifies the behavior -/// of a [`RawWaker`]. -/// -/// The pointer passed to all functions inside the vtable is the `data` pointer -/// from the enclosing [`RawWaker`] object. -/// -/// The functions inside this struct are only intended to be called on the `data` -/// pointer of a properly constructed [`RawWaker`] object from inside the -/// [`RawWaker`] implementation. Calling one of the contained functions using -/// any other `data` pointer will cause undefined behavior. -/// -/// Note that while this type implements `PartialEq`, comparing function pointers, and hence -/// comparing structs like this that contain function pointers, is unreliable: pointers to the same -/// function can compare inequal (because functions are duplicated in multiple codegen units), and -/// pointers to *different* functions can compare equal (since identical functions can be -/// deduplicated within a codegen unit). -/// -/// # Thread safety -/// If the [`RawWaker`] will be used to construct a [`Waker`] then -/// these functions must all be thread-safe (even though [`RawWaker`] is -/// \![Send] + \![Sync]). This is because [`Waker`] is [Send] + [Sync], -/// and it may be moved to arbitrary threads or invoked by `&` reference. For example, -/// this means that if the `clone` and `drop` functions manage a reference count, -/// they must do so atomically. -/// -/// However, if the [`RawWaker`] will be used to construct a [`LocalWaker`] instead, then -/// these functions don't need to be thread safe. This means that \![Send] + \![Sync] -/// data can be stored in the data pointer, and reference counting does not need any atomic -/// synchronization. This is because [`LocalWaker`] is not thread safe itself, so it cannot -/// be sent across threads. -#[stable(feature = "futures_api", since = "1.36.0")] -#[derive(PartialEq, Copy, Clone, Debug)] -pub struct RawWakerVTable { - /// This function will be called when the [`RawWaker`] gets cloned, e.g. when - /// the [`Waker`] in which the [`RawWaker`] is stored gets cloned. - /// - /// The implementation of this function must retain all resources that are - /// required for this additional instance of a [`RawWaker`] and associated - /// task. Calling `wake` on the resulting [`RawWaker`] should result in a wakeup - /// of the same task that would have been awoken by the original [`RawWaker`]. - clone: unsafe fn(*const ()) -> RawWaker, - - /// This function will be called when `wake` is called on the [`Waker`]. - /// It must wake up the task associated with this [`RawWaker`]. - /// - /// The implementation of this function must make sure to release any - /// resources that are associated with this instance of a [`RawWaker`] and - /// associated task. - wake: unsafe fn(*const ()), - - /// This function will be called when `wake_by_ref` is called on the [`Waker`]. - /// It must wake up the task associated with this [`RawWaker`]. - /// - /// This function is similar to `wake`, but must not consume the provided data - /// pointer. - wake_by_ref: unsafe fn(*const ()), - - /// This function gets called when a [`Waker`] gets dropped. - /// - /// The implementation of this function must make sure to release any - /// resources that are associated with this instance of a [`RawWaker`] and - /// associated task. - drop: unsafe fn(*const ()), -} - -impl RawWakerVTable { - /// Creates a new `RawWakerVTable` from the provided `clone`, `wake`, - /// `wake_by_ref`, and `drop` functions. - /// - /// If the [`RawWaker`] will be used to construct a [`Waker`] then - /// these functions must all be thread-safe (even though [`RawWaker`] is - /// \![Send] + \![Sync]). This is because [`Waker`] is [Send] + [Sync], - /// and it may be moved to arbitrary threads or invoked by `&` reference. For example, - /// this means that if the `clone` and `drop` functions manage a reference count, - /// they must do so atomically. - /// - /// However, if the [`RawWaker`] will be used to construct a [`LocalWaker`] instead, then - /// these functions don't need to be thread safe. This means that \![Send] + \![Sync] - /// data can be stored in the data pointer, and reference counting does not need any atomic - /// synchronization. This is because [`LocalWaker`] is not thread safe itself, so it cannot - /// be sent across threads. - /// # `clone` - /// - /// This function will be called when the [`RawWaker`] gets cloned, e.g. when - /// the [`Waker`]/[`LocalWaker`] in which the [`RawWaker`] is stored gets cloned. - /// - /// The implementation of this function must retain all resources that are - /// required for this additional instance of a [`RawWaker`] and associated - /// task. Calling `wake` on the resulting [`RawWaker`] should result in a wakeup - /// of the same task that would have been awoken by the original [`RawWaker`]. - /// - /// # `wake` - /// - /// This function will be called when `wake` is called on the [`Waker`]. - /// It must wake up the task associated with this [`RawWaker`]. - /// - /// The implementation of this function must make sure to release any - /// resources that are associated with this instance of a [`RawWaker`] and - /// associated task. - /// - /// # `wake_by_ref` - /// - /// This function will be called when `wake_by_ref` is called on the [`Waker`]. - /// It must wake up the task associated with this [`RawWaker`]. - /// - /// This function is similar to `wake`, but must not consume the provided data - /// pointer. - /// - /// # `drop` - /// - /// This function gets called when a [`Waker`]/[`LocalWaker`] gets dropped. - /// - /// The implementation of this function must make sure to release any - /// resources that are associated with this instance of a [`RawWaker`] and - /// associated task. - #[rustc_promotable] - #[stable(feature = "futures_api", since = "1.36.0")] - #[rustc_const_stable(feature = "futures_api", since = "1.36.0")] - pub const fn new( - clone: unsafe fn(*const ()) -> RawWaker, - wake: unsafe fn(*const ()), - wake_by_ref: unsafe fn(*const ()), - drop: unsafe fn(*const ()), - ) -> Self { - Self { clone, wake, wake_by_ref, drop } - } -} - -#[derive(Debug)] -enum ExtData<'a> { - Some(&'a mut dyn Any), - None(()), -} - -/// The context of an asynchronous task. -/// -/// Currently, `Context` only serves to provide access to a [`&Waker`](Waker) -/// which can be used to wake the current task. -#[stable(feature = "futures_api", since = "1.36.0")] -#[lang = "Context"] -pub struct Context<'a> { - waker: &'a Waker, - local_waker: &'a LocalWaker, - ext: AssertUnwindSafe>, - // Ensure we future-proof against variance changes by forcing - // the lifetime to be invariant (argument-position lifetimes - // are contravariant while return-position lifetimes are - // covariant). - _marker: PhantomData &'a ()>, - // Ensure `Context` is `!Send` and `!Sync` in order to allow - // for future `!Send` and / or `!Sync` fields. - _marker2: PhantomData<*mut ()>, -} - -impl<'a> Context<'a> { - /// Create a new `Context` from a [`&Waker`](Waker). - #[stable(feature = "futures_api", since = "1.36.0")] - #[rustc_const_unstable(feature = "const_waker", issue = "102012")] - #[must_use] - #[inline] - pub const fn from_waker(waker: &'a Waker) -> Self { - ContextBuilder::from_waker(waker).build() - } - - /// Returns a reference to the [`Waker`] for the current task. - #[inline] - #[must_use] - #[stable(feature = "futures_api", since = "1.36.0")] - #[rustc_const_unstable(feature = "const_waker", issue = "102012")] - pub const fn waker(&self) -> &'a Waker { - &self.waker - } - - /// Returns a reference to the [`LocalWaker`] for the current task. - #[inline] - #[unstable(feature = "local_waker", issue = "118959")] - #[rustc_const_unstable(feature = "const_waker", issue = "102012")] - pub const fn local_waker(&self) -> &'a LocalWaker { - &self.local_waker - } - - /// Returns a reference to the extension data for the current task. - #[inline] - #[unstable(feature = "context_ext", issue = "123392")] - #[rustc_const_unstable(feature = "const_waker", issue = "102012")] - pub const fn ext(&mut self) -> &mut dyn Any { - // FIXME: this field makes Context extra-weird about unwind safety - // can we justify AssertUnwindSafe if we stabilize this? do we care? - match &mut *self.ext { - ExtData::Some(data) => *data, - ExtData::None(unit) => unit, - } - } -} - -#[stable(feature = "futures_api", since = "1.36.0")] -impl fmt::Debug for Context<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Context").field("waker", &self.waker).finish() - } -} - -/// A Builder used to construct a `Context` instance -/// with support for `LocalWaker`. -/// -/// # Examples -/// ``` -/// #![feature(local_waker)] -/// #![feature(noop_waker)] -/// use std::task::{ContextBuilder, LocalWaker, Waker, Poll}; -/// use std::future::Future; -/// -/// let local_waker = LocalWaker::noop(); -/// let waker = Waker::noop(); -/// -/// let mut cx = ContextBuilder::from_waker(&waker) -/// .local_waker(&local_waker) -/// .build(); -/// -/// let mut future = std::pin::pin!(async { 20 }); -/// let poll = future.as_mut().poll(&mut cx); -/// assert_eq!(poll, Poll::Ready(20)); -/// -/// ``` -#[unstable(feature = "local_waker", issue = "118959")] -#[derive(Debug)] -pub struct ContextBuilder<'a> { - waker: &'a Waker, - local_waker: &'a LocalWaker, - ext: ExtData<'a>, - // Ensure we future-proof against variance changes by forcing - // the lifetime to be invariant (argument-position lifetimes - // are contravariant while return-position lifetimes are - // covariant). - _marker: PhantomData &'a ()>, - // Ensure `Context` is `!Send` and `!Sync` in order to allow - // for future `!Send` and / or `!Sync` fields. - _marker2: PhantomData<*mut ()>, -} - -impl<'a> ContextBuilder<'a> { - /// Create a ContextBuilder from a Waker. - #[inline] - #[rustc_const_unstable(feature = "const_waker", issue = "102012")] - #[unstable(feature = "local_waker", issue = "118959")] - pub const fn from_waker(waker: &'a Waker) -> Self { - // SAFETY: LocalWaker is just Waker without thread safety - let local_waker = unsafe { transmute(waker) }; - Self { - waker: waker, - local_waker, - ext: ExtData::None(()), - _marker: PhantomData, - _marker2: PhantomData, - } - } - - /// Create a ContextBuilder from an existing Context. - #[inline] - #[rustc_const_unstable(feature = "const_waker", issue = "102012")] - #[unstable(feature = "context_ext", issue = "123392")] - pub const fn from(cx: &'a mut Context<'_>) -> Self { - let ext = match &mut *cx.ext { - ExtData::Some(ext) => ExtData::Some(*ext), - ExtData::None(()) => ExtData::None(()), - }; - Self { - waker: cx.waker, - local_waker: cx.local_waker, - ext, - _marker: PhantomData, - _marker2: PhantomData, - } - } - - /// This method is used to set the value for the waker on `Context`. - #[inline] - #[unstable(feature = "context_ext", issue = "123392")] - #[rustc_const_unstable(feature = "const_waker", issue = "102012")] - pub const fn waker(self, waker: &'a Waker) -> Self { - Self { waker, ..self } - } - - /// This method is used to set the value for the local waker on `Context`. - #[inline] - #[unstable(feature = "local_waker", issue = "118959")] - #[rustc_const_unstable(feature = "const_waker", issue = "102012")] - pub const fn local_waker(self, local_waker: &'a LocalWaker) -> Self { - Self { local_waker, ..self } - } - - /// This method is used to set the value for the extension data on `Context`. - #[inline] - #[unstable(feature = "context_ext", issue = "123392")] - #[rustc_const_unstable(feature = "const_waker", issue = "102012")] - pub const fn ext(self, data: &'a mut dyn Any) -> Self { - Self { ext: ExtData::Some(data), ..self } - } - - /// Builds the `Context`. - #[inline] - #[unstable(feature = "local_waker", issue = "118959")] - #[rustc_const_unstable(feature = "const_waker", issue = "102012")] - pub const fn build(self) -> Context<'a> { - let ContextBuilder { waker, local_waker, ext, _marker, _marker2 } = self; - Context { waker, local_waker, ext: AssertUnwindSafe(ext), _marker, _marker2 } - } -} - -/// A `Waker` is a handle for waking up a task by notifying its executor that it -/// is ready to be run. -/// -/// This handle encapsulates a [`RawWaker`] instance, which defines the -/// executor-specific wakeup behavior. -/// -/// The typical life of a `Waker` is that it is constructed by an executor, wrapped in a -/// [`Context`], then passed to [`Future::poll()`]. Then, if the future chooses to return -/// [`Poll::Pending`], it must also store the waker somehow and call [`Waker::wake()`] when -/// the future should be polled again. -/// -/// Implements [`Clone`], [`Send`], and [`Sync`]; therefore, a waker may be invoked -/// from any thread, including ones not in any way managed by the executor. For example, -/// this might be done to wake a future when a blocking function call completes on another -/// thread. -/// -/// Note that it is preferable to use `waker.clone_from(&new_waker)` instead -/// of `*waker = new_waker.clone()`, as the former will avoid cloning the waker -/// unnecessarily if the two wakers [wake the same task](Self::will_wake). -/// -/// Constructing a `Waker` from a [`RawWaker`] is unsafe. -/// Implementing the [`Wake`] trait is a safe alternative that requires memory allocation. -/// -/// [`Future::poll()`]: core::future::Future::poll -/// [`Poll::Pending`]: core::task::Poll::Pending -/// [`Wake`]: ../../alloc/task/trait.Wake.html -#[cfg_attr(not(doc), repr(transparent))] // work around https://github.com/rust-lang/rust/issues/66401 -#[stable(feature = "futures_api", since = "1.36.0")] -pub struct Waker { - waker: RawWaker, -} - -#[stable(feature = "futures_api", since = "1.36.0")] -impl Unpin for Waker {} -#[stable(feature = "futures_api", since = "1.36.0")] -unsafe impl Send for Waker {} -#[stable(feature = "futures_api", since = "1.36.0")] -unsafe impl Sync for Waker {} - -impl Waker { - /// Wake up the task associated with this `Waker`. - /// - /// As long as the executor keeps running and the task is not finished, it is - /// guaranteed that each invocation of [`wake()`](Self::wake) (or - /// [`wake_by_ref()`](Self::wake_by_ref)) will be followed by at least one - /// [`poll()`] of the task to which this `Waker` belongs. This makes - /// it possible to temporarily yield to other tasks while running potentially - /// unbounded processing loops. - /// - /// Note that the above implies that multiple wake-ups may be coalesced into a - /// single [`poll()`] invocation by the runtime. - /// - /// Also note that yielding to competing tasks is not guaranteed: it is the - /// executor’s choice which task to run and the executor may choose to run the - /// current task again. - /// - /// [`poll()`]: crate::future::Future::poll - #[inline] - #[stable(feature = "futures_api", since = "1.36.0")] - pub fn wake(self) { - // The actual wakeup call is delegated through a virtual function call - // to the implementation which is defined by the executor. - let wake = self.waker.vtable.wake; - let data = self.waker.data; - - // Don't call `drop` -- the waker will be consumed by `wake`. - crate::mem::forget(self); - - // SAFETY: This is safe because `Waker::from_raw` is the only way - // to initialize `wake` and `data` requiring the user to acknowledge - // that the contract of `RawWaker` is upheld. - unsafe { (wake)(data) }; - } - - /// Wake up the task associated with this `Waker` without consuming the `Waker`. - /// - /// This is similar to [`wake()`](Self::wake), but may be slightly less efficient in - /// the case where an owned `Waker` is available. This method should be preferred to - /// calling `waker.clone().wake()`. - #[inline] - #[stable(feature = "futures_api", since = "1.36.0")] - pub fn wake_by_ref(&self) { - // The actual wakeup call is delegated through a virtual function call - // to the implementation which is defined by the executor. - - // SAFETY: see `wake` - unsafe { (self.waker.vtable.wake_by_ref)(self.waker.data) } - } - - /// Returns `true` if this `Waker` and another `Waker` would awake the same task. - /// - /// This function works on a best-effort basis, and may return false even - /// when the `Waker`s would awaken the same task. However, if this function - /// returns `true`, it is guaranteed that the `Waker`s will awaken the same task. - /// - /// This function is primarily used for optimization purposes — for example, - /// this type's [`clone_from`](Self::clone_from) implementation uses it to - /// avoid cloning the waker when they would wake the same task anyway. - #[inline] - #[must_use] - #[stable(feature = "futures_api", since = "1.36.0")] - pub fn will_wake(&self, other: &Waker) -> bool { - let RawWaker { data: a_data, vtable: a_vtable } = self.waker; - let RawWaker { data: b_data, vtable: b_vtable } = other.waker; - a_data == b_data && ptr::eq(a_vtable, b_vtable) - } - - /// Creates a new `Waker` from [`RawWaker`]. - /// - /// # Safety - /// - /// The behavior of the returned `Waker` is undefined if the contract defined - /// in [`RawWaker`]'s and [`RawWakerVTable`]'s documentation is not upheld. - /// - /// (Authors wishing to avoid unsafe code may implement the [`Wake`] trait instead, at the - /// cost of a required heap allocation.) - /// - /// [`Wake`]: ../../alloc/task/trait.Wake.html - #[inline] - #[must_use] - #[stable(feature = "futures_api", since = "1.36.0")] - #[rustc_const_unstable(feature = "const_waker", issue = "102012")] - pub const unsafe fn from_raw(waker: RawWaker) -> Waker { - Waker { waker } - } - - /// Returns a reference to a `Waker` that does nothing when used. - /// - /// This is mostly useful for writing tests that need a [`Context`] to poll - /// some futures, but are not expecting those futures to wake the waker or - /// do not need to do anything specific if it happens. - /// - /// If an owned `Waker` is needed, `clone()` this one. - /// - /// # Examples - /// - /// ``` - /// #![feature(noop_waker)] - /// - /// use std::future::Future; - /// use std::task; - /// - /// let mut cx = task::Context::from_waker(task::Waker::noop()); - /// - /// let mut future = Box::pin(async { 10 }); - /// assert_eq!(future.as_mut().poll(&mut cx), task::Poll::Ready(10)); - /// ``` - #[inline] - #[must_use] - #[unstable(feature = "noop_waker", issue = "98286")] - pub const fn noop() -> &'static Waker { - const WAKER: &Waker = &Waker { waker: RawWaker::NOOP }; - WAKER - } - - /// Get a reference to the underlying [`RawWaker`]. - #[inline] - #[must_use] - #[unstable(feature = "waker_getters", issue = "96992")] - pub fn as_raw(&self) -> &RawWaker { - &self.waker - } -} - -#[stable(feature = "futures_api", since = "1.36.0")] -impl Clone for Waker { - #[inline] - fn clone(&self) -> Self { - Waker { - // SAFETY: This is safe because `Waker::from_raw` is the only way - // to initialize `clone` and `data` requiring the user to acknowledge - // that the contract of [`RawWaker`] is upheld. - waker: unsafe { (self.waker.vtable.clone)(self.waker.data) }, - } - } - - /// Assigns a clone of `source` to `self`, unless [`self.will_wake(source)`][Waker::will_wake] anyway. - /// - /// This method is preferred over simply assigning `source.clone()` to `self`, - /// as it avoids cloning the waker if `self` is already the same waker. - /// - /// # Examples - /// - /// ``` - /// use std::future::Future; - /// use std::pin::Pin; - /// use std::sync::{Arc, Mutex}; - /// use std::task::{Context, Poll, Waker}; - /// - /// struct Waiter { - /// shared: Arc>, - /// } - /// - /// struct Shared { - /// waker: Waker, - /// // ... - /// } - /// - /// impl Future for Waiter { - /// type Output = (); - /// fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> { - /// let mut shared = self.shared.lock().unwrap(); - /// - /// // update the waker - /// shared.waker.clone_from(cx.waker()); - /// - /// // readiness logic ... - /// # Poll::Ready(()) - /// } - /// } - /// - /// ``` - #[inline] - fn clone_from(&mut self, source: &Self) { - if !self.will_wake(source) { - *self = source.clone(); - } - } -} - -#[stable(feature = "futures_api", since = "1.36.0")] -impl Drop for Waker { - #[inline] - fn drop(&mut self) { - // SAFETY: This is safe because `Waker::from_raw` is the only way - // to initialize `drop` and `data` requiring the user to acknowledge - // that the contract of `RawWaker` is upheld. - unsafe { (self.waker.vtable.drop)(self.waker.data) } - } -} - -#[stable(feature = "futures_api", since = "1.36.0")] -impl fmt::Debug for Waker { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let vtable_ptr = self.waker.vtable as *const RawWakerVTable; - f.debug_struct("Waker") - .field("data", &self.waker.data) - .field("vtable", &vtable_ptr) - .finish() - } -} - -/// A `LocalWaker` is analogous to a [`Waker`], but it does not implement [`Send`] or [`Sync`]. -/// -/// This handle encapsulates a [`RawWaker`] instance, which defines the -/// executor-specific wakeup behavior. -/// -/// Local wakers can be requested from a `Context` with the [`local_waker`] method. -/// -/// The typical life of a `LocalWaker` is that it is constructed by an executor, wrapped in a -/// [`Context`] using [`ContextBuilder`], then passed to [`Future::poll()`]. Then, if the future chooses to return -/// [`Poll::Pending`], it must also store the waker somehow and call [`LocalWaker::wake()`] when -/// the future should be polled again. -/// -/// Implements [`Clone`], but neither [`Send`] nor [`Sync`]; therefore, a local waker may -/// not be moved to other threads. In general, when deciding to use wakers or local wakers, -/// local wakers are preferable unless the waker needs to be sent across threads. This is because -/// wakers can incur in additional cost related to memory synchronization. -/// -/// Note that it is preferable to use `local_waker.clone_from(&new_waker)` instead -/// of `*local_waker = new_waker.clone()`, as the former will avoid cloning the waker -/// unnecessarily if the two wakers [wake the same task](Self::will_wake). -/// -/// # Examples -/// Usage of a local waker to implement a future analogous to `std::thread::yield_now()`. -/// ``` -/// #![feature(local_waker)] -/// use std::future::{Future, poll_fn}; -/// use std::task::Poll; -/// -/// // a future that returns pending once. -/// fn yield_now() -> impl Future + Unpin { -/// let mut yielded = false; -/// poll_fn(move |cx| { -/// if !yielded { -/// yielded = true; -/// cx.local_waker().wake_by_ref(); -/// return Poll::Pending; -/// } -/// return Poll::Ready(()) -/// }) -/// } -/// -/// # async fn __() { -/// yield_now().await; -/// # } -/// ``` -/// -/// [`Future::poll()`]: core::future::Future::poll -/// [`Poll::Pending`]: core::task::Poll::Pending -/// [`local_waker`]: core::task::Context::local_waker -#[unstable(feature = "local_waker", issue = "118959")] -#[cfg_attr(not(doc), repr(transparent))] // work around https://github.com/rust-lang/rust/issues/66401 -pub struct LocalWaker { - waker: RawWaker, -} - -#[unstable(feature = "local_waker", issue = "118959")] -impl Unpin for LocalWaker {} - -impl LocalWaker { - /// Wake up the task associated with this `LocalWaker`. - /// - /// As long as the executor keeps running and the task is not finished, it is - /// guaranteed that each invocation of [`wake()`](Self::wake) (or - /// [`wake_by_ref()`](Self::wake_by_ref)) will be followed by at least one - /// [`poll()`] of the task to which this `LocalWaker` belongs. This makes - /// it possible to temporarily yield to other tasks while running potentially - /// unbounded processing loops. - /// - /// Note that the above implies that multiple wake-ups may be coalesced into a - /// single [`poll()`] invocation by the runtime. - /// - /// Also note that yielding to competing tasks is not guaranteed: it is the - /// executor’s choice which task to run and the executor may choose to run the - /// current task again. - /// - /// [`poll()`]: crate::future::Future::poll - #[inline] - #[unstable(feature = "local_waker", issue = "118959")] - pub fn wake(self) { - // The actual wakeup call is delegated through a virtual function call - // to the implementation which is defined by the executor. - let wake = self.waker.vtable.wake; - let data = self.waker.data; - - // Don't call `drop` -- the waker will be consumed by `wake`. - crate::mem::forget(self); - - // SAFETY: This is safe because `Waker::from_raw` is the only way - // to initialize `wake` and `data` requiring the user to acknowledge - // that the contract of `RawWaker` is upheld. - unsafe { (wake)(data) }; - } - - /// Wake up the task associated with this `LocalWaker` without consuming the `LocalWaker`. - /// - /// This is similar to [`wake()`](Self::wake), but may be slightly less efficient in - /// the case where an owned `Waker` is available. This method should be preferred to - /// calling `waker.clone().wake()`. - #[inline] - #[unstable(feature = "local_waker", issue = "118959")] - pub fn wake_by_ref(&self) { - // The actual wakeup call is delegated through a virtual function call - // to the implementation which is defined by the executor. - - // SAFETY: see `wake` - unsafe { (self.waker.vtable.wake_by_ref)(self.waker.data) } - } - - /// Returns `true` if this `LocalWaker` and another `LocalWaker` would awake the same task. - /// - /// This function works on a best-effort basis, and may return false even - /// when the `Waker`s would awaken the same task. However, if this function - /// returns `true`, it is guaranteed that the `Waker`s will awaken the same task. - /// - /// This function is primarily used for optimization purposes — for example, - /// this type's [`clone_from`](Self::clone_from) implementation uses it to - /// avoid cloning the waker when they would wake the same task anyway. - #[inline] - #[must_use] - #[unstable(feature = "local_waker", issue = "118959")] - pub fn will_wake(&self, other: &LocalWaker) -> bool { - self.waker == other.waker - } - - /// Creates a new `LocalWaker` from [`RawWaker`]. - /// - /// The behavior of the returned `LocalWaker` is undefined if the contract defined - /// in [`RawWaker`]'s and [`RawWakerVTable`]'s documentation is not upheld. - /// Therefore this method is unsafe. - #[inline] - #[must_use] - #[unstable(feature = "local_waker", issue = "118959")] - #[rustc_const_unstable(feature = "const_waker", issue = "102012")] - pub const unsafe fn from_raw(waker: RawWaker) -> LocalWaker { - Self { waker } - } - - /// Creates a new `LocalWaker` that does nothing when `wake` is called. - /// - /// This is mostly useful for writing tests that need a [`Context`] to poll - /// some futures, but are not expecting those futures to wake the waker or - /// do not need to do anything specific if it happens. - /// - /// # Examples - /// - /// ``` - /// #![feature(local_waker)] - /// #![feature(noop_waker)] - /// - /// use std::future::Future; - /// use std::task::{ContextBuilder, LocalWaker, Waker, Poll}; - /// - /// let mut cx = ContextBuilder::from_waker(Waker::noop()) - /// .local_waker(LocalWaker::noop()) - /// .build(); - /// - /// let mut future = Box::pin(async { 10 }); - /// assert_eq!(future.as_mut().poll(&mut cx), Poll::Ready(10)); - /// ``` - #[inline] - #[must_use] - #[unstable(feature = "noop_waker", issue = "98286")] - pub const fn noop() -> &'static LocalWaker { - const WAKER: &LocalWaker = &LocalWaker { waker: RawWaker::NOOP }; - WAKER - } - - /// Get a reference to the underlying [`RawWaker`]. - #[inline] - #[must_use] - #[unstable(feature = "waker_getters", issue = "96992")] - pub fn as_raw(&self) -> &RawWaker { - &self.waker - } -} -#[unstable(feature = "local_waker", issue = "118959")] -impl Clone for LocalWaker { - #[inline] - fn clone(&self) -> Self { - LocalWaker { - // SAFETY: This is safe because `Waker::from_raw` is the only way - // to initialize `clone` and `data` requiring the user to acknowledge - // that the contract of [`RawWaker`] is upheld. - waker: unsafe { (self.waker.vtable.clone)(self.waker.data) }, - } - } - - #[inline] - fn clone_from(&mut self, source: &Self) { - if !self.will_wake(source) { - *self = source.clone(); - } - } -} - -#[unstable(feature = "local_waker", issue = "118959")] -impl AsRef for Waker { - fn as_ref(&self) -> &LocalWaker { - // SAFETY: LocalWaker is just Waker without thread safety - unsafe { transmute(self) } - } -} - -#[unstable(feature = "local_waker", issue = "118959")] -impl Drop for LocalWaker { - #[inline] - fn drop(&mut self) { - // SAFETY: This is safe because `LocalWaker::from_raw` is the only way - // to initialize `drop` and `data` requiring the user to acknowledge - // that the contract of `RawWaker` is upheld. - unsafe { (self.waker.vtable.drop)(self.waker.data) } - } -} - -#[unstable(feature = "local_waker", issue = "118959")] -impl fmt::Debug for LocalWaker { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let vtable_ptr = self.waker.vtable as *const RawWakerVTable; - f.debug_struct("LocalWaker") - .field("data", &self.waker.data) - .field("vtable", &vtable_ptr) - .finish() - } -} - -#[unstable(feature = "local_waker", issue = "118959")] -impl !Send for LocalWaker {} -#[unstable(feature = "local_waker", issue = "118959")] -impl !Sync for LocalWaker {} diff --git a/library/core/src/time.rs b/library/core/src/time.rs deleted file mode 100644 index 88fe29c999749..0000000000000 --- a/library/core/src/time.rs +++ /dev/null @@ -1,1710 +0,0 @@ -#![stable(feature = "duration_core", since = "1.25.0")] - -//! Temporal quantification. -//! -//! # Examples: -//! -//! There are multiple ways to create a new [`Duration`]: -//! -//! ``` -//! # use std::time::Duration; -//! let five_seconds = Duration::from_secs(5); -//! assert_eq!(five_seconds, Duration::from_millis(5_000)); -//! assert_eq!(five_seconds, Duration::from_micros(5_000_000)); -//! assert_eq!(five_seconds, Duration::from_nanos(5_000_000_000)); -//! -//! let ten_seconds = Duration::from_secs(10); -//! let seven_nanos = Duration::from_nanos(7); -//! let total = ten_seconds + seven_nanos; -//! assert_eq!(total, Duration::new(10, 7)); -//! ``` - -use crate::fmt; -use crate::iter::Sum; -use crate::ops::{Add, AddAssign, Div, DivAssign, Mul, MulAssign, Sub, SubAssign}; - -const NANOS_PER_SEC: u32 = 1_000_000_000; -const NANOS_PER_MILLI: u32 = 1_000_000; -const NANOS_PER_MICRO: u32 = 1_000; -const MILLIS_PER_SEC: u64 = 1_000; -const MICROS_PER_SEC: u64 = 1_000_000; -#[unstable(feature = "duration_units", issue = "120301")] -const SECS_PER_MINUTE: u64 = 60; -#[unstable(feature = "duration_units", issue = "120301")] -const MINS_PER_HOUR: u64 = 60; -#[unstable(feature = "duration_units", issue = "120301")] -const HOURS_PER_DAY: u64 = 24; -#[unstable(feature = "duration_units", issue = "120301")] -const DAYS_PER_WEEK: u64 = 7; - -#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)] -#[repr(transparent)] -#[rustc_layout_scalar_valid_range_start(0)] -#[rustc_layout_scalar_valid_range_end(999_999_999)] -struct Nanoseconds(u32); - -impl Nanoseconds { - // SAFETY: 0 is within the valid range - const ZERO: Self = unsafe { Nanoseconds(0) }; -} - -impl Default for Nanoseconds { - #[inline] - fn default() -> Self { - Self::ZERO - } -} - -/// A `Duration` type to represent a span of time, typically used for system -/// timeouts. -/// -/// Each `Duration` is composed of a whole number of seconds and a fractional part -/// represented in nanoseconds. If the underlying system does not support -/// nanosecond-level precision, APIs binding a system timeout will typically round up -/// the number of nanoseconds. -/// -/// [`Duration`]s implement many common traits, including [`Add`], [`Sub`], and other -/// [`ops`] traits. It implements [`Default`] by returning a zero-length `Duration`. -/// -/// [`ops`]: crate::ops -/// -/// # Examples -/// -/// ``` -/// use std::time::Duration; -/// -/// let five_seconds = Duration::new(5, 0); -/// let five_seconds_and_five_nanos = five_seconds + Duration::new(0, 5); -/// -/// assert_eq!(five_seconds_and_five_nanos.as_secs(), 5); -/// assert_eq!(five_seconds_and_five_nanos.subsec_nanos(), 5); -/// -/// let ten_millis = Duration::from_millis(10); -/// ``` -/// -/// # Formatting `Duration` values -/// -/// `Duration` intentionally does not have a `Display` impl, as there are a -/// variety of ways to format spans of time for human readability. `Duration` -/// provides a `Debug` impl that shows the full precision of the value. -/// -/// The `Debug` output uses the non-ASCII "µs" suffix for microseconds. If your -/// program output may appear in contexts that cannot rely on full Unicode -/// compatibility, you may wish to format `Duration` objects yourself or use a -/// crate to do so. -#[stable(feature = "duration", since = "1.3.0")] -#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash, Default)] -#[cfg_attr(not(test), rustc_diagnostic_item = "Duration")] -pub struct Duration { - secs: u64, - nanos: Nanoseconds, // Always 0 <= nanos < NANOS_PER_SEC -} - -impl Duration { - /// The duration of one second. - /// - /// # Examples - /// - /// ``` - /// #![feature(duration_constants)] - /// use std::time::Duration; - /// - /// assert_eq!(Duration::SECOND, Duration::from_secs(1)); - /// ``` - #[unstable(feature = "duration_constants", issue = "57391")] - pub const SECOND: Duration = Duration::from_secs(1); - - /// The duration of one millisecond. - /// - /// # Examples - /// - /// ``` - /// #![feature(duration_constants)] - /// use std::time::Duration; - /// - /// assert_eq!(Duration::MILLISECOND, Duration::from_millis(1)); - /// ``` - #[unstable(feature = "duration_constants", issue = "57391")] - pub const MILLISECOND: Duration = Duration::from_millis(1); - - /// The duration of one microsecond. - /// - /// # Examples - /// - /// ``` - /// #![feature(duration_constants)] - /// use std::time::Duration; - /// - /// assert_eq!(Duration::MICROSECOND, Duration::from_micros(1)); - /// ``` - #[unstable(feature = "duration_constants", issue = "57391")] - pub const MICROSECOND: Duration = Duration::from_micros(1); - - /// The duration of one nanosecond. - /// - /// # Examples - /// - /// ``` - /// #![feature(duration_constants)] - /// use std::time::Duration; - /// - /// assert_eq!(Duration::NANOSECOND, Duration::from_nanos(1)); - /// ``` - #[unstable(feature = "duration_constants", issue = "57391")] - pub const NANOSECOND: Duration = Duration::from_nanos(1); - - /// A duration of zero time. - /// - /// # Examples - /// - /// ``` - /// use std::time::Duration; - /// - /// let duration = Duration::ZERO; - /// assert!(duration.is_zero()); - /// assert_eq!(duration.as_nanos(), 0); - /// ``` - #[stable(feature = "duration_zero", since = "1.53.0")] - pub const ZERO: Duration = Duration::from_nanos(0); - - /// The maximum duration. - /// - /// May vary by platform as necessary. Must be able to contain the difference between - /// two instances of [`Instant`] or two instances of [`SystemTime`]. - /// This constraint gives it a value of about 584,942,417,355 years in practice, - /// which is currently used on all platforms. - /// - /// # Examples - /// - /// ``` - /// use std::time::Duration; - /// - /// assert_eq!(Duration::MAX, Duration::new(u64::MAX, 1_000_000_000 - 1)); - /// ``` - /// [`Instant`]: ../../std/time/struct.Instant.html - /// [`SystemTime`]: ../../std/time/struct.SystemTime.html - #[stable(feature = "duration_saturating_ops", since = "1.53.0")] - pub const MAX: Duration = Duration::new(u64::MAX, NANOS_PER_SEC - 1); - - /// Creates a new `Duration` from the specified number of whole seconds and - /// additional nanoseconds. - /// - /// If the number of nanoseconds is greater than 1 billion (the number of - /// nanoseconds in a second), then it will carry over into the seconds provided. - /// - /// # Panics - /// - /// This constructor will panic if the carry from the nanoseconds overflows - /// the seconds counter. - /// - /// # Examples - /// - /// ``` - /// use std::time::Duration; - /// - /// let five_seconds = Duration::new(5, 0); - /// ``` - #[stable(feature = "duration", since = "1.3.0")] - #[inline] - #[must_use] - #[rustc_const_stable(feature = "duration_consts_2", since = "1.58.0")] - pub const fn new(secs: u64, nanos: u32) -> Duration { - if nanos < NANOS_PER_SEC { - // SAFETY: nanos < NANOS_PER_SEC, therefore nanos is within the valid range - Duration { secs, nanos: unsafe { Nanoseconds(nanos) } } - } else { - let secs = match secs.checked_add((nanos / NANOS_PER_SEC) as u64) { - Some(secs) => secs, - None => panic!("overflow in Duration::new"), - }; - let nanos = nanos % NANOS_PER_SEC; - // SAFETY: nanos % NANOS_PER_SEC < NANOS_PER_SEC, therefore nanos is within the valid range - Duration { secs, nanos: unsafe { Nanoseconds(nanos) } } - } - } - - /// Creates a new `Duration` from the specified number of whole seconds. - /// - /// # Examples - /// - /// ``` - /// use std::time::Duration; - /// - /// let duration = Duration::from_secs(5); - /// - /// assert_eq!(5, duration.as_secs()); - /// assert_eq!(0, duration.subsec_nanos()); - /// ``` - #[stable(feature = "duration", since = "1.3.0")] - #[must_use] - #[inline] - #[rustc_const_stable(feature = "duration_consts", since = "1.32.0")] - pub const fn from_secs(secs: u64) -> Duration { - Duration { secs, nanos: Nanoseconds::ZERO } - } - - /// Creates a new `Duration` from the specified number of milliseconds. - /// - /// # Examples - /// - /// ``` - /// use std::time::Duration; - /// - /// let duration = Duration::from_millis(2569); - /// - /// assert_eq!(2, duration.as_secs()); - /// assert_eq!(569_000_000, duration.subsec_nanos()); - /// ``` - #[stable(feature = "duration", since = "1.3.0")] - #[must_use] - #[inline] - #[rustc_const_stable(feature = "duration_consts", since = "1.32.0")] - pub const fn from_millis(millis: u64) -> Duration { - let secs = millis / MILLIS_PER_SEC; - let subsec_millis = (millis % MILLIS_PER_SEC) as u32; - // SAFETY: (x % 1_000) * 1_000_000 < 1_000_000_000 - // => x % 1_000 < 1_000 - let subsec_nanos = unsafe { Nanoseconds(subsec_millis * NANOS_PER_MILLI) }; - - Duration { secs, nanos: subsec_nanos } - } - - /// Creates a new `Duration` from the specified number of microseconds. - /// - /// # Examples - /// - /// ``` - /// use std::time::Duration; - /// - /// let duration = Duration::from_micros(1_000_002); - /// - /// assert_eq!(1, duration.as_secs()); - /// assert_eq!(2000, duration.subsec_nanos()); - /// ``` - #[stable(feature = "duration_from_micros", since = "1.27.0")] - #[must_use] - #[inline] - #[rustc_const_stable(feature = "duration_consts", since = "1.32.0")] - pub const fn from_micros(micros: u64) -> Duration { - let secs = micros / MICROS_PER_SEC; - let subsec_micros = (micros % MICROS_PER_SEC) as u32; - // SAFETY: (x % 1_000_000) * 1_000 < 1_000_000_000 - // => x % 1_000_000 < 1_000_000 - let subsec_nanos = unsafe { Nanoseconds(subsec_micros * NANOS_PER_MICRO) }; - - Duration { secs, nanos: subsec_nanos } - } - - /// Creates a new `Duration` from the specified number of nanoseconds. - /// - /// Note: Using this on the return value of `as_nanos()` might cause unexpected behavior: - /// `as_nanos()` returns a u128, and can return values that do not fit in u64, e.g. 585 years. - /// Instead, consider using the pattern `Duration::new(d.as_secs(), d.subsec_nanos())` - /// if you cannot copy/clone the Duration directly. - /// - /// # Examples - /// - /// ``` - /// use std::time::Duration; - /// - /// let duration = Duration::from_nanos(1_000_000_123); - /// - /// assert_eq!(1, duration.as_secs()); - /// assert_eq!(123, duration.subsec_nanos()); - /// ``` - #[stable(feature = "duration_extras", since = "1.27.0")] - #[must_use] - #[inline] - #[rustc_const_stable(feature = "duration_consts", since = "1.32.0")] - pub const fn from_nanos(nanos: u64) -> Duration { - const NANOS_PER_SEC: u64 = self::NANOS_PER_SEC as u64; - let secs = nanos / NANOS_PER_SEC; - let subsec_nanos = (nanos % NANOS_PER_SEC) as u32; - // SAFETY: x % 1_000_000_000 < 1_000_000_000 - let subsec_nanos = unsafe { Nanoseconds(subsec_nanos) }; - - Duration { secs, nanos: subsec_nanos } - } - - /// Creates a new `Duration` from the specified number of weeks. - /// - /// # Panics - /// - /// Panics if the given number of weeks overflows the `Duration` size. - /// - /// # Examples - /// - /// ``` - /// #![feature(duration_constructors)] - /// use std::time::Duration; - /// - /// let duration = Duration::from_weeks(4); - /// - /// assert_eq!(4 * 7 * 24 * 60 * 60, duration.as_secs()); - /// assert_eq!(0, duration.subsec_nanos()); - /// ``` - #[unstable(feature = "duration_constructors", issue = "120301")] - #[must_use] - #[inline] - pub const fn from_weeks(weeks: u64) -> Duration { - if weeks > u64::MAX / (SECS_PER_MINUTE * MINS_PER_HOUR * HOURS_PER_DAY * DAYS_PER_WEEK) { - panic!("overflow in Duration::from_days"); - } - - Duration::from_secs(weeks * MINS_PER_HOUR * SECS_PER_MINUTE * HOURS_PER_DAY * DAYS_PER_WEEK) - } - - /// Creates a new `Duration` from the specified number of days. - /// - /// # Panics - /// - /// Panics if the given number of days overflows the `Duration` size. - /// - /// # Examples - /// - /// ``` - /// #![feature(duration_constructors)] - /// use std::time::Duration; - /// - /// let duration = Duration::from_days(7); - /// - /// assert_eq!(7 * 24 * 60 * 60, duration.as_secs()); - /// assert_eq!(0, duration.subsec_nanos()); - /// ``` - #[unstable(feature = "duration_constructors", issue = "120301")] - #[must_use] - #[inline] - pub const fn from_days(days: u64) -> Duration { - if days > u64::MAX / (SECS_PER_MINUTE * MINS_PER_HOUR * HOURS_PER_DAY) { - panic!("overflow in Duration::from_days"); - } - - Duration::from_secs(days * MINS_PER_HOUR * SECS_PER_MINUTE * HOURS_PER_DAY) - } - - /// Creates a new `Duration` from the specified number of hours. - /// - /// # Panics - /// - /// Panics if the given number of hours overflows the `Duration` size. - /// - /// # Examples - /// - /// ``` - /// #![feature(duration_constructors)] - /// use std::time::Duration; - /// - /// let duration = Duration::from_hours(6); - /// - /// assert_eq!(6 * 60 * 60, duration.as_secs()); - /// assert_eq!(0, duration.subsec_nanos()); - /// ``` - #[unstable(feature = "duration_constructors", issue = "120301")] - #[must_use] - #[inline] - pub const fn from_hours(hours: u64) -> Duration { - if hours > u64::MAX / (SECS_PER_MINUTE * MINS_PER_HOUR) { - panic!("overflow in Duration::from_hours"); - } - - Duration::from_secs(hours * MINS_PER_HOUR * SECS_PER_MINUTE) - } - - /// Creates a new `Duration` from the specified number of minutes. - /// - /// # Panics - /// - /// Panics if the given number of minutes overflows the `Duration` size. - /// - /// # Examples - /// - /// ``` - /// #![feature(duration_constructors)] - /// use std::time::Duration; - /// - /// let duration = Duration::from_mins(10); - /// - /// assert_eq!(10 * 60, duration.as_secs()); - /// assert_eq!(0, duration.subsec_nanos()); - /// ``` - #[unstable(feature = "duration_constructors", issue = "120301")] - #[must_use] - #[inline] - pub const fn from_mins(mins: u64) -> Duration { - if mins > u64::MAX / SECS_PER_MINUTE { - panic!("overflow in Duration::from_mins"); - } - - Duration::from_secs(mins * SECS_PER_MINUTE) - } - - /// Returns true if this `Duration` spans no time. - /// - /// # Examples - /// - /// ``` - /// use std::time::Duration; - /// - /// assert!(Duration::ZERO.is_zero()); - /// assert!(Duration::new(0, 0).is_zero()); - /// assert!(Duration::from_nanos(0).is_zero()); - /// assert!(Duration::from_secs(0).is_zero()); - /// - /// assert!(!Duration::new(1, 1).is_zero()); - /// assert!(!Duration::from_nanos(1).is_zero()); - /// assert!(!Duration::from_secs(1).is_zero()); - /// ``` - #[must_use] - #[stable(feature = "duration_zero", since = "1.53.0")] - #[rustc_const_stable(feature = "duration_zero", since = "1.53.0")] - #[inline] - pub const fn is_zero(&self) -> bool { - self.secs == 0 && self.nanos.0 == 0 - } - - /// Returns the number of _whole_ seconds contained by this `Duration`. - /// - /// The returned value does not include the fractional (nanosecond) part of the - /// duration, which can be obtained using [`subsec_nanos`]. - /// - /// # Examples - /// - /// ``` - /// use std::time::Duration; - /// - /// let duration = Duration::new(5, 730023852); - /// assert_eq!(duration.as_secs(), 5); - /// ``` - /// - /// To determine the total number of seconds represented by the `Duration` - /// including the fractional part, use [`as_secs_f64`] or [`as_secs_f32`] - /// - /// [`as_secs_f64`]: Duration::as_secs_f64 - /// [`as_secs_f32`]: Duration::as_secs_f32 - /// [`subsec_nanos`]: Duration::subsec_nanos - #[stable(feature = "duration", since = "1.3.0")] - #[rustc_const_stable(feature = "duration_consts", since = "1.32.0")] - #[must_use] - #[inline] - pub const fn as_secs(&self) -> u64 { - self.secs - } - - /// Returns the fractional part of this `Duration`, in whole milliseconds. - /// - /// This method does **not** return the length of the duration when - /// represented by milliseconds. The returned number always represents a - /// fractional portion of a second (i.e., it is less than one thousand). - /// - /// # Examples - /// - /// ``` - /// use std::time::Duration; - /// - /// let duration = Duration::from_millis(5432); - /// assert_eq!(duration.as_secs(), 5); - /// assert_eq!(duration.subsec_millis(), 432); - /// ``` - #[stable(feature = "duration_extras", since = "1.27.0")] - #[rustc_const_stable(feature = "duration_consts", since = "1.32.0")] - #[must_use] - #[inline] - pub const fn subsec_millis(&self) -> u32 { - self.nanos.0 / NANOS_PER_MILLI - } - - /// Returns the fractional part of this `Duration`, in whole microseconds. - /// - /// This method does **not** return the length of the duration when - /// represented by microseconds. The returned number always represents a - /// fractional portion of a second (i.e., it is less than one million). - /// - /// # Examples - /// - /// ``` - /// use std::time::Duration; - /// - /// let duration = Duration::from_micros(1_234_567); - /// assert_eq!(duration.as_secs(), 1); - /// assert_eq!(duration.subsec_micros(), 234_567); - /// ``` - #[stable(feature = "duration_extras", since = "1.27.0")] - #[rustc_const_stable(feature = "duration_consts", since = "1.32.0")] - #[must_use] - #[inline] - pub const fn subsec_micros(&self) -> u32 { - self.nanos.0 / NANOS_PER_MICRO - } - - /// Returns the fractional part of this `Duration`, in nanoseconds. - /// - /// This method does **not** return the length of the duration when - /// represented by nanoseconds. The returned number always represents a - /// fractional portion of a second (i.e., it is less than one billion). - /// - /// # Examples - /// - /// ``` - /// use std::time::Duration; - /// - /// let duration = Duration::from_millis(5010); - /// assert_eq!(duration.as_secs(), 5); - /// assert_eq!(duration.subsec_nanos(), 10_000_000); - /// ``` - #[stable(feature = "duration", since = "1.3.0")] - #[rustc_const_stable(feature = "duration_consts", since = "1.32.0")] - #[must_use] - #[inline] - pub const fn subsec_nanos(&self) -> u32 { - self.nanos.0 - } - - /// Returns the total number of whole milliseconds contained by this `Duration`. - /// - /// # Examples - /// - /// ``` - /// use std::time::Duration; - /// - /// let duration = Duration::new(5, 730023852); - /// assert_eq!(duration.as_millis(), 5730); - /// ``` - #[stable(feature = "duration_as_u128", since = "1.33.0")] - #[rustc_const_stable(feature = "duration_as_u128", since = "1.33.0")] - #[must_use] - #[inline] - pub const fn as_millis(&self) -> u128 { - self.secs as u128 * MILLIS_PER_SEC as u128 + (self.nanos.0 / NANOS_PER_MILLI) as u128 - } - - /// Returns the total number of whole microseconds contained by this `Duration`. - /// - /// # Examples - /// - /// ``` - /// use std::time::Duration; - /// - /// let duration = Duration::new(5, 730023852); - /// assert_eq!(duration.as_micros(), 5730023); - /// ``` - #[stable(feature = "duration_as_u128", since = "1.33.0")] - #[rustc_const_stable(feature = "duration_as_u128", since = "1.33.0")] - #[must_use] - #[inline] - pub const fn as_micros(&self) -> u128 { - self.secs as u128 * MICROS_PER_SEC as u128 + (self.nanos.0 / NANOS_PER_MICRO) as u128 - } - - /// Returns the total number of nanoseconds contained by this `Duration`. - /// - /// # Examples - /// - /// ``` - /// use std::time::Duration; - /// - /// let duration = Duration::new(5, 730023852); - /// assert_eq!(duration.as_nanos(), 5730023852); - /// ``` - #[stable(feature = "duration_as_u128", since = "1.33.0")] - #[rustc_const_stable(feature = "duration_as_u128", since = "1.33.0")] - #[must_use] - #[inline] - pub const fn as_nanos(&self) -> u128 { - self.secs as u128 * NANOS_PER_SEC as u128 + self.nanos.0 as u128 - } - - /// Computes the absolute difference between `self` and `other`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(duration_abs_diff)] - /// use std::time::Duration; - /// - /// assert_eq!(Duration::new(100, 0).abs_diff(Duration::new(80, 0)), Duration::new(20, 0)); - /// assert_eq!(Duration::new(100, 400_000_000).abs_diff(Duration::new(110, 0)), Duration::new(9, 600_000_000)); - /// ``` - #[unstable(feature = "duration_abs_diff", issue = "117618")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub const fn abs_diff(self, other: Duration) -> Duration { - if let Some(res) = self.checked_sub(other) { res } else { other.checked_sub(self).unwrap() } - } - - /// Checked `Duration` addition. Computes `self + other`, returning [`None`] - /// if overflow occurred. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::time::Duration; - /// - /// assert_eq!(Duration::new(0, 0).checked_add(Duration::new(0, 1)), Some(Duration::new(0, 1))); - /// assert_eq!(Duration::new(1, 0).checked_add(Duration::new(u64::MAX, 0)), None); - /// ``` - #[stable(feature = "duration_checked_ops", since = "1.16.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[rustc_const_stable(feature = "duration_consts_2", since = "1.58.0")] - pub const fn checked_add(self, rhs: Duration) -> Option { - if let Some(mut secs) = self.secs.checked_add(rhs.secs) { - let mut nanos = self.nanos.0 + rhs.nanos.0; - if nanos >= NANOS_PER_SEC { - nanos -= NANOS_PER_SEC; - if let Some(new_secs) = secs.checked_add(1) { - secs = new_secs; - } else { - return None; - } - } - debug_assert!(nanos < NANOS_PER_SEC); - Some(Duration::new(secs, nanos)) - } else { - None - } - } - - /// Saturating `Duration` addition. Computes `self + other`, returning [`Duration::MAX`] - /// if overflow occurred. - /// - /// # Examples - /// - /// ``` - /// #![feature(duration_constants)] - /// use std::time::Duration; - /// - /// assert_eq!(Duration::new(0, 0).saturating_add(Duration::new(0, 1)), Duration::new(0, 1)); - /// assert_eq!(Duration::new(1, 0).saturating_add(Duration::new(u64::MAX, 0)), Duration::MAX); - /// ``` - #[stable(feature = "duration_saturating_ops", since = "1.53.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[rustc_const_stable(feature = "duration_consts_2", since = "1.58.0")] - pub const fn saturating_add(self, rhs: Duration) -> Duration { - match self.checked_add(rhs) { - Some(res) => res, - None => Duration::MAX, - } - } - - /// Checked `Duration` subtraction. Computes `self - other`, returning [`None`] - /// if the result would be negative or if overflow occurred. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::time::Duration; - /// - /// assert_eq!(Duration::new(0, 1).checked_sub(Duration::new(0, 0)), Some(Duration::new(0, 1))); - /// assert_eq!(Duration::new(0, 0).checked_sub(Duration::new(0, 1)), None); - /// ``` - #[stable(feature = "duration_checked_ops", since = "1.16.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[rustc_const_stable(feature = "duration_consts_2", since = "1.58.0")] - pub const fn checked_sub(self, rhs: Duration) -> Option { - if let Some(mut secs) = self.secs.checked_sub(rhs.secs) { - let nanos = if self.nanos.0 >= rhs.nanos.0 { - self.nanos.0 - rhs.nanos.0 - } else if let Some(sub_secs) = secs.checked_sub(1) { - secs = sub_secs; - self.nanos.0 + NANOS_PER_SEC - rhs.nanos.0 - } else { - return None; - }; - debug_assert!(nanos < NANOS_PER_SEC); - Some(Duration::new(secs, nanos)) - } else { - None - } - } - - /// Saturating `Duration` subtraction. Computes `self - other`, returning [`Duration::ZERO`] - /// if the result would be negative or if overflow occurred. - /// - /// # Examples - /// - /// ``` - /// use std::time::Duration; - /// - /// assert_eq!(Duration::new(0, 1).saturating_sub(Duration::new(0, 0)), Duration::new(0, 1)); - /// assert_eq!(Duration::new(0, 0).saturating_sub(Duration::new(0, 1)), Duration::ZERO); - /// ``` - #[stable(feature = "duration_saturating_ops", since = "1.53.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[rustc_const_stable(feature = "duration_consts_2", since = "1.58.0")] - pub const fn saturating_sub(self, rhs: Duration) -> Duration { - match self.checked_sub(rhs) { - Some(res) => res, - None => Duration::ZERO, - } - } - - /// Checked `Duration` multiplication. Computes `self * other`, returning - /// [`None`] if overflow occurred. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::time::Duration; - /// - /// assert_eq!(Duration::new(0, 500_000_001).checked_mul(2), Some(Duration::new(1, 2))); - /// assert_eq!(Duration::new(u64::MAX - 1, 0).checked_mul(2), None); - /// ``` - #[stable(feature = "duration_checked_ops", since = "1.16.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[rustc_const_stable(feature = "duration_consts_2", since = "1.58.0")] - pub const fn checked_mul(self, rhs: u32) -> Option { - // Multiply nanoseconds as u64, because it cannot overflow that way. - let total_nanos = self.nanos.0 as u64 * rhs as u64; - let extra_secs = total_nanos / (NANOS_PER_SEC as u64); - let nanos = (total_nanos % (NANOS_PER_SEC as u64)) as u32; - if let Some(s) = self.secs.checked_mul(rhs as u64) { - if let Some(secs) = s.checked_add(extra_secs) { - debug_assert!(nanos < NANOS_PER_SEC); - return Some(Duration::new(secs, nanos)); - } - } - None - } - - /// Saturating `Duration` multiplication. Computes `self * other`, returning - /// [`Duration::MAX`] if overflow occurred. - /// - /// # Examples - /// - /// ``` - /// #![feature(duration_constants)] - /// use std::time::Duration; - /// - /// assert_eq!(Duration::new(0, 500_000_001).saturating_mul(2), Duration::new(1, 2)); - /// assert_eq!(Duration::new(u64::MAX - 1, 0).saturating_mul(2), Duration::MAX); - /// ``` - #[stable(feature = "duration_saturating_ops", since = "1.53.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[rustc_const_stable(feature = "duration_consts_2", since = "1.58.0")] - pub const fn saturating_mul(self, rhs: u32) -> Duration { - match self.checked_mul(rhs) { - Some(res) => res, - None => Duration::MAX, - } - } - - /// Checked `Duration` division. Computes `self / other`, returning [`None`] - /// if `other == 0`. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::time::Duration; - /// - /// assert_eq!(Duration::new(2, 0).checked_div(2), Some(Duration::new(1, 0))); - /// assert_eq!(Duration::new(1, 0).checked_div(2), Some(Duration::new(0, 500_000_000))); - /// assert_eq!(Duration::new(2, 0).checked_div(0), None); - /// ``` - #[stable(feature = "duration_checked_ops", since = "1.16.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[rustc_const_stable(feature = "duration_consts_2", since = "1.58.0")] - pub const fn checked_div(self, rhs: u32) -> Option { - if rhs != 0 { - let (secs, extra_secs) = (self.secs / (rhs as u64), self.secs % (rhs as u64)); - let (mut nanos, extra_nanos) = (self.nanos.0 / rhs, self.nanos.0 % rhs); - nanos += - ((extra_secs * (NANOS_PER_SEC as u64) + extra_nanos as u64) / (rhs as u64)) as u32; - debug_assert!(nanos < NANOS_PER_SEC); - Some(Duration::new(secs, nanos)) - } else { - None - } - } - - /// Returns the number of seconds contained by this `Duration` as `f64`. - /// - /// The returned value does include the fractional (nanosecond) part of the duration. - /// - /// # Examples - /// ``` - /// use std::time::Duration; - /// - /// let dur = Duration::new(2, 700_000_000); - /// assert_eq!(dur.as_secs_f64(), 2.7); - /// ``` - #[stable(feature = "duration_float", since = "1.38.0")] - #[must_use] - #[inline] - #[rustc_const_unstable(feature = "duration_consts_float", issue = "72440")] - pub const fn as_secs_f64(&self) -> f64 { - (self.secs as f64) + (self.nanos.0 as f64) / (NANOS_PER_SEC as f64) - } - - /// Returns the number of seconds contained by this `Duration` as `f32`. - /// - /// The returned value does include the fractional (nanosecond) part of the duration. - /// - /// # Examples - /// ``` - /// use std::time::Duration; - /// - /// let dur = Duration::new(2, 700_000_000); - /// assert_eq!(dur.as_secs_f32(), 2.7); - /// ``` - #[stable(feature = "duration_float", since = "1.38.0")] - #[must_use] - #[inline] - #[rustc_const_unstable(feature = "duration_consts_float", issue = "72440")] - pub const fn as_secs_f32(&self) -> f32 { - (self.secs as f32) + (self.nanos.0 as f32) / (NANOS_PER_SEC as f32) - } - - /// Returns the number of milliseconds contained by this `Duration` as `f64`. - /// - /// The returned value does include the fractional (nanosecond) part of the duration. - /// - /// # Examples - /// ``` - /// #![feature(duration_millis_float)] - /// use std::time::Duration; - /// - /// let dur = Duration::new(2, 345_678_000); - /// assert_eq!(dur.as_millis_f64(), 2345.678); - /// ``` - #[unstable(feature = "duration_millis_float", issue = "122451")] - #[must_use] - #[inline] - #[rustc_const_unstable(feature = "duration_consts_float", issue = "72440")] - pub const fn as_millis_f64(&self) -> f64 { - (self.secs as f64) * (MILLIS_PER_SEC as f64) - + (self.nanos.0 as f64) / (NANOS_PER_MILLI as f64) - } - - /// Returns the number of milliseconds contained by this `Duration` as `f32`. - /// - /// The returned value does include the fractional (nanosecond) part of the duration. - /// - /// # Examples - /// ``` - /// #![feature(duration_millis_float)] - /// use std::time::Duration; - /// - /// let dur = Duration::new(2, 345_678_000); - /// assert_eq!(dur.as_millis_f32(), 2345.678); - /// ``` - #[unstable(feature = "duration_millis_float", issue = "122451")] - #[must_use] - #[inline] - #[rustc_const_unstable(feature = "duration_consts_float", issue = "72440")] - pub const fn as_millis_f32(&self) -> f32 { - (self.secs as f32) * (MILLIS_PER_SEC as f32) - + (self.nanos.0 as f32) / (NANOS_PER_MILLI as f32) - } - - /// Creates a new `Duration` from the specified number of seconds represented - /// as `f64`. - /// - /// # Panics - /// This constructor will panic if `secs` is negative, overflows `Duration` or not finite. - /// - /// # Examples - /// ``` - /// use std::time::Duration; - /// - /// let res = Duration::from_secs_f64(0.0); - /// assert_eq!(res, Duration::new(0, 0)); - /// let res = Duration::from_secs_f64(1e-20); - /// assert_eq!(res, Duration::new(0, 0)); - /// let res = Duration::from_secs_f64(4.2e-7); - /// assert_eq!(res, Duration::new(0, 420)); - /// let res = Duration::from_secs_f64(2.7); - /// assert_eq!(res, Duration::new(2, 700_000_000)); - /// let res = Duration::from_secs_f64(3e10); - /// assert_eq!(res, Duration::new(30_000_000_000, 0)); - /// // subnormal float - /// let res = Duration::from_secs_f64(f64::from_bits(1)); - /// assert_eq!(res, Duration::new(0, 0)); - /// // conversion uses rounding - /// let res = Duration::from_secs_f64(0.999e-9); - /// assert_eq!(res, Duration::new(0, 1)); - /// ``` - #[stable(feature = "duration_float", since = "1.38.0")] - #[must_use] - #[inline] - pub fn from_secs_f64(secs: f64) -> Duration { - match Duration::try_from_secs_f64(secs) { - Ok(v) => v, - Err(e) => panic!("{}", e.description()), - } - } - - /// Creates a new `Duration` from the specified number of seconds represented - /// as `f32`. - /// - /// # Panics - /// This constructor will panic if `secs` is negative, overflows `Duration` or not finite. - /// - /// # Examples - /// ``` - /// use std::time::Duration; - /// - /// let res = Duration::from_secs_f32(0.0); - /// assert_eq!(res, Duration::new(0, 0)); - /// let res = Duration::from_secs_f32(1e-20); - /// assert_eq!(res, Duration::new(0, 0)); - /// let res = Duration::from_secs_f32(4.2e-7); - /// assert_eq!(res, Duration::new(0, 420)); - /// let res = Duration::from_secs_f32(2.7); - /// assert_eq!(res, Duration::new(2, 700_000_048)); - /// let res = Duration::from_secs_f32(3e10); - /// assert_eq!(res, Duration::new(30_000_001_024, 0)); - /// // subnormal float - /// let res = Duration::from_secs_f32(f32::from_bits(1)); - /// assert_eq!(res, Duration::new(0, 0)); - /// // conversion uses rounding - /// let res = Duration::from_secs_f32(0.999e-9); - /// assert_eq!(res, Duration::new(0, 1)); - /// ``` - #[stable(feature = "duration_float", since = "1.38.0")] - #[must_use] - #[inline] - pub fn from_secs_f32(secs: f32) -> Duration { - match Duration::try_from_secs_f32(secs) { - Ok(v) => v, - Err(e) => panic!("{}", e.description()), - } - } - - /// Multiplies `Duration` by `f64`. - /// - /// # Panics - /// This method will panic if result is negative, overflows `Duration` or not finite. - /// - /// # Examples - /// ``` - /// use std::time::Duration; - /// - /// let dur = Duration::new(2, 700_000_000); - /// assert_eq!(dur.mul_f64(3.14), Duration::new(8, 478_000_000)); - /// assert_eq!(dur.mul_f64(3.14e5), Duration::new(847_800, 0)); - /// ``` - #[stable(feature = "duration_float", since = "1.38.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub fn mul_f64(self, rhs: f64) -> Duration { - Duration::from_secs_f64(rhs * self.as_secs_f64()) - } - - /// Multiplies `Duration` by `f32`. - /// - /// # Panics - /// This method will panic if result is negative, overflows `Duration` or not finite. - /// - /// # Examples - /// ``` - /// use std::time::Duration; - /// - /// let dur = Duration::new(2, 700_000_000); - /// assert_eq!(dur.mul_f32(3.14), Duration::new(8, 478_000_641)); - /// assert_eq!(dur.mul_f32(3.14e5), Duration::new(847800, 0)); - /// ``` - #[stable(feature = "duration_float", since = "1.38.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub fn mul_f32(self, rhs: f32) -> Duration { - Duration::from_secs_f32(rhs * self.as_secs_f32()) - } - - /// Divide `Duration` by `f64`. - /// - /// # Panics - /// This method will panic if result is negative, overflows `Duration` or not finite. - /// - /// # Examples - /// ``` - /// use std::time::Duration; - /// - /// let dur = Duration::new(2, 700_000_000); - /// assert_eq!(dur.div_f64(3.14), Duration::new(0, 859_872_611)); - /// assert_eq!(dur.div_f64(3.14e5), Duration::new(0, 8_599)); - /// ``` - #[stable(feature = "duration_float", since = "1.38.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub fn div_f64(self, rhs: f64) -> Duration { - Duration::from_secs_f64(self.as_secs_f64() / rhs) - } - - /// Divide `Duration` by `f32`. - /// - /// # Panics - /// This method will panic if result is negative, overflows `Duration` or not finite. - /// - /// # Examples - /// ``` - /// use std::time::Duration; - /// - /// let dur = Duration::new(2, 700_000_000); - /// // note that due to rounding errors result is slightly - /// // different from 0.859_872_611 - /// assert_eq!(dur.div_f32(3.14), Duration::new(0, 859_872_580)); - /// assert_eq!(dur.div_f32(3.14e5), Duration::new(0, 8_599)); - /// ``` - #[stable(feature = "duration_float", since = "1.38.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub fn div_f32(self, rhs: f32) -> Duration { - Duration::from_secs_f32(self.as_secs_f32() / rhs) - } - - /// Divide `Duration` by `Duration` and return `f64`. - /// - /// # Examples - /// ``` - /// #![feature(div_duration)] - /// use std::time::Duration; - /// - /// let dur1 = Duration::new(2, 700_000_000); - /// let dur2 = Duration::new(5, 400_000_000); - /// assert_eq!(dur1.div_duration_f64(dur2), 0.5); - /// ``` - #[unstable(feature = "div_duration", issue = "63139")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[rustc_const_unstable(feature = "duration_consts_float", issue = "72440")] - pub const fn div_duration_f64(self, rhs: Duration) -> f64 { - self.as_secs_f64() / rhs.as_secs_f64() - } - - /// Divide `Duration` by `Duration` and return `f32`. - /// - /// # Examples - /// ``` - /// #![feature(div_duration)] - /// use std::time::Duration; - /// - /// let dur1 = Duration::new(2, 700_000_000); - /// let dur2 = Duration::new(5, 400_000_000); - /// assert_eq!(dur1.div_duration_f32(dur2), 0.5); - /// ``` - #[unstable(feature = "div_duration", issue = "63139")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - #[rustc_const_unstable(feature = "duration_consts_float", issue = "72440")] - pub const fn div_duration_f32(self, rhs: Duration) -> f32 { - self.as_secs_f32() / rhs.as_secs_f32() - } -} - -#[stable(feature = "duration", since = "1.3.0")] -impl Add for Duration { - type Output = Duration; - - #[inline] - fn add(self, rhs: Duration) -> Duration { - self.checked_add(rhs).expect("overflow when adding durations") - } -} - -#[stable(feature = "time_augmented_assignment", since = "1.9.0")] -impl AddAssign for Duration { - #[inline] - fn add_assign(&mut self, rhs: Duration) { - *self = *self + rhs; - } -} - -#[stable(feature = "duration", since = "1.3.0")] -impl Sub for Duration { - type Output = Duration; - - #[inline] - fn sub(self, rhs: Duration) -> Duration { - self.checked_sub(rhs).expect("overflow when subtracting durations") - } -} - -#[stable(feature = "time_augmented_assignment", since = "1.9.0")] -impl SubAssign for Duration { - #[inline] - fn sub_assign(&mut self, rhs: Duration) { - *self = *self - rhs; - } -} - -#[stable(feature = "duration", since = "1.3.0")] -impl Mul for Duration { - type Output = Duration; - - #[inline] - fn mul(self, rhs: u32) -> Duration { - self.checked_mul(rhs).expect("overflow when multiplying duration by scalar") - } -} - -#[stable(feature = "symmetric_u32_duration_mul", since = "1.31.0")] -impl Mul for u32 { - type Output = Duration; - - #[inline] - fn mul(self, rhs: Duration) -> Duration { - rhs * self - } -} - -#[stable(feature = "time_augmented_assignment", since = "1.9.0")] -impl MulAssign for Duration { - #[inline] - fn mul_assign(&mut self, rhs: u32) { - *self = *self * rhs; - } -} - -#[stable(feature = "duration", since = "1.3.0")] -impl Div for Duration { - type Output = Duration; - - #[inline] - fn div(self, rhs: u32) -> Duration { - self.checked_div(rhs).expect("divide by zero error when dividing duration by scalar") - } -} - -#[stable(feature = "time_augmented_assignment", since = "1.9.0")] -impl DivAssign for Duration { - #[inline] - fn div_assign(&mut self, rhs: u32) { - *self = *self / rhs; - } -} - -macro_rules! sum_durations { - ($iter:expr) => {{ - let mut total_secs: u64 = 0; - let mut total_nanos: u64 = 0; - - for entry in $iter { - total_secs = - total_secs.checked_add(entry.secs).expect("overflow in iter::sum over durations"); - total_nanos = match total_nanos.checked_add(entry.nanos.0 as u64) { - Some(n) => n, - None => { - total_secs = total_secs - .checked_add(total_nanos / NANOS_PER_SEC as u64) - .expect("overflow in iter::sum over durations"); - (total_nanos % NANOS_PER_SEC as u64) + entry.nanos.0 as u64 - } - }; - } - total_secs = total_secs - .checked_add(total_nanos / NANOS_PER_SEC as u64) - .expect("overflow in iter::sum over durations"); - total_nanos = total_nanos % NANOS_PER_SEC as u64; - Duration::new(total_secs, total_nanos as u32) - }}; -} - -#[stable(feature = "duration_sum", since = "1.16.0")] -impl Sum for Duration { - fn sum>(iter: I) -> Duration { - sum_durations!(iter) - } -} - -#[stable(feature = "duration_sum", since = "1.16.0")] -impl<'a> Sum<&'a Duration> for Duration { - fn sum>(iter: I) -> Duration { - sum_durations!(iter) - } -} - -#[stable(feature = "duration_debug_impl", since = "1.27.0")] -impl fmt::Debug for Duration { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - /// Formats a floating point number in decimal notation. - /// - /// The number is given as the `integer_part` and a fractional part. - /// The value of the fractional part is `fractional_part / divisor`. So - /// `integer_part` = 3, `fractional_part` = 12 and `divisor` = 100 - /// represents the number `3.012`. Trailing zeros are omitted. - /// - /// `divisor` must not be above 100_000_000. It also should be a power - /// of 10, everything else doesn't make sense. `fractional_part` has - /// to be less than `10 * divisor`! - /// - /// A prefix and postfix may be added. The whole thing is padded - /// to the formatter's `width`, if specified. - fn fmt_decimal( - f: &mut fmt::Formatter<'_>, - integer_part: u64, - mut fractional_part: u32, - mut divisor: u32, - prefix: &str, - postfix: &str, - ) -> fmt::Result { - // Encode the fractional part into a temporary buffer. The buffer - // only need to hold 9 elements, because `fractional_part` has to - // be smaller than 10^9. The buffer is prefilled with '0' digits - // to simplify the code below. - let mut buf = [b'0'; 9]; - - // The next digit is written at this position - let mut pos = 0; - - // We keep writing digits into the buffer while there are non-zero - // digits left and we haven't written enough digits yet. - while fractional_part > 0 && pos < f.precision().unwrap_or(9) { - // Write new digit into the buffer - buf[pos] = b'0' + (fractional_part / divisor) as u8; - - fractional_part %= divisor; - divisor /= 10; - pos += 1; - } - - // If a precision < 9 was specified, there may be some non-zero - // digits left that weren't written into the buffer. In that case we - // need to perform rounding to match the semantics of printing - // normal floating point numbers. However, we only need to do work - // when rounding up. This happens if the first digit of the - // remaining ones is >= 5. - let integer_part = if fractional_part > 0 && fractional_part >= divisor * 5 { - // Round up the number contained in the buffer. We go through - // the buffer backwards and keep track of the carry. - let mut rev_pos = pos; - let mut carry = true; - while carry && rev_pos > 0 { - rev_pos -= 1; - - // If the digit in the buffer is not '9', we just need to - // increment it and can stop then (since we don't have a - // carry anymore). Otherwise, we set it to '0' (overflow) - // and continue. - if buf[rev_pos] < b'9' { - buf[rev_pos] += 1; - carry = false; - } else { - buf[rev_pos] = b'0'; - } - } - - // If we still have the carry bit set, that means that we set - // the whole buffer to '0's and need to increment the integer - // part. - if carry { - // If `integer_part == u64::MAX` and precision < 9, any - // carry of the overflow during rounding of the - // `fractional_part` into the `integer_part` will cause the - // `integer_part` itself to overflow. Avoid this by using an - // `Option`, with `None` representing `u64::MAX + 1`. - integer_part.checked_add(1) - } else { - Some(integer_part) - } - } else { - Some(integer_part) - }; - - // Determine the end of the buffer: if precision is set, we just - // use as many digits from the buffer (capped to 9). If it isn't - // set, we only use all digits up to the last non-zero one. - let end = f.precision().map(|p| crate::cmp::min(p, 9)).unwrap_or(pos); - - // This closure emits the formatted duration without emitting any - // padding (padding is calculated below). - let emit_without_padding = |f: &mut fmt::Formatter<'_>| { - if let Some(integer_part) = integer_part { - write!(f, "{}{}", prefix, integer_part)?; - } else { - // u64::MAX + 1 == 18446744073709551616 - write!(f, "{}18446744073709551616", prefix)?; - } - - // Write the decimal point and the fractional part (if any). - if end > 0 { - // SAFETY: We are only writing ASCII digits into the buffer and - // it was initialized with '0's, so it contains valid UTF8. - let s = unsafe { crate::str::from_utf8_unchecked(&buf[..end]) }; - - // If the user request a precision > 9, we pad '0's at the end. - let w = f.precision().unwrap_or(pos); - write!(f, ".{:0 { - // No `width` specified. There's no need to calculate the - // length of the output in this case, just emit it. - emit_without_padding(f) - } - Some(requested_w) => { - // A `width` was specified. Calculate the actual width of - // the output in order to calculate the required padding. - // It consists of 4 parts: - // 1. The prefix: is either "+" or "", so we can just use len(). - // 2. The postfix: can be "µs" so we have to count UTF8 characters. - let mut actual_w = prefix.len() + postfix.chars().count(); - // 3. The integer part: - if let Some(integer_part) = integer_part { - if let Some(log) = integer_part.checked_ilog10() { - // integer_part is > 0, so has length log10(x)+1 - actual_w += 1 + log as usize; - } else { - // integer_part is 0, so has length 1. - actual_w += 1; - } - } else { - // integer_part is u64::MAX + 1, so has length 20 - actual_w += 20; - } - // 4. The fractional part (if any): - if end > 0 { - let frac_part_w = f.precision().unwrap_or(pos); - actual_w += 1 + frac_part_w; - } - - if requested_w <= actual_w { - // Output is already longer than `width`, so don't pad. - emit_without_padding(f) - } else { - // We need to add padding. Use the `Formatter::padding` helper function. - let default_align = fmt::Alignment::Left; - let post_padding = f.padding(requested_w - actual_w, default_align)?; - emit_without_padding(f)?; - post_padding.write(f) - } - } - } - } - - // Print leading '+' sign if requested - let prefix = if f.sign_plus() { "+" } else { "" }; - - if self.secs > 0 { - fmt_decimal(f, self.secs, self.nanos.0, NANOS_PER_SEC / 10, prefix, "s") - } else if self.nanos.0 >= NANOS_PER_MILLI { - fmt_decimal( - f, - (self.nanos.0 / NANOS_PER_MILLI) as u64, - self.nanos.0 % NANOS_PER_MILLI, - NANOS_PER_MILLI / 10, - prefix, - "ms", - ) - } else if self.nanos.0 >= NANOS_PER_MICRO { - fmt_decimal( - f, - (self.nanos.0 / NANOS_PER_MICRO) as u64, - self.nanos.0 % NANOS_PER_MICRO, - NANOS_PER_MICRO / 10, - prefix, - "µs", - ) - } else { - fmt_decimal(f, self.nanos.0 as u64, 0, 1, prefix, "ns") - } - } -} - -/// An error which can be returned when converting a floating-point value of seconds -/// into a [`Duration`]. -/// -/// This error is used as the error type for [`Duration::try_from_secs_f32`] and -/// [`Duration::try_from_secs_f64`]. -/// -/// # Example -/// -/// ``` -/// use std::time::Duration; -/// -/// if let Err(e) = Duration::try_from_secs_f32(-1.0) { -/// println!("Failed conversion to Duration: {e}"); -/// } -/// ``` -#[derive(Debug, Clone, PartialEq, Eq)] -#[stable(feature = "duration_checked_float", since = "1.66.0")] -pub struct TryFromFloatSecsError { - kind: TryFromFloatSecsErrorKind, -} - -impl TryFromFloatSecsError { - const fn description(&self) -> &'static str { - match self.kind { - TryFromFloatSecsErrorKind::Negative => { - "cannot convert float seconds to Duration: value is negative" - } - TryFromFloatSecsErrorKind::OverflowOrNan => { - "cannot convert float seconds to Duration: value is either too big or NaN" - } - } - } -} - -#[stable(feature = "duration_checked_float", since = "1.66.0")] -impl fmt::Display for TryFromFloatSecsError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.description().fmt(f) - } -} - -#[derive(Debug, Clone, PartialEq, Eq)] -enum TryFromFloatSecsErrorKind { - // Value is negative. - Negative, - // Value is either too big to be represented as `Duration` or `NaN`. - OverflowOrNan, -} - -macro_rules! try_from_secs { - ( - secs = $secs: expr, - mantissa_bits = $mant_bits: literal, - exponent_bits = $exp_bits: literal, - offset = $offset: literal, - bits_ty = $bits_ty:ty, - double_ty = $double_ty:ty, - ) => {{ - const MIN_EXP: i16 = 1 - (1i16 << $exp_bits) / 2; - const MANT_MASK: $bits_ty = (1 << $mant_bits) - 1; - const EXP_MASK: $bits_ty = (1 << $exp_bits) - 1; - - if $secs < 0.0 { - return Err(TryFromFloatSecsError { kind: TryFromFloatSecsErrorKind::Negative }); - } - - let bits = $secs.to_bits(); - let mant = (bits & MANT_MASK) | (MANT_MASK + 1); - let exp = ((bits >> $mant_bits) & EXP_MASK) as i16 + MIN_EXP; - - let (secs, nanos) = if exp < -31 { - // the input represents less than 1ns and can not be rounded to it - (0u64, 0u32) - } else if exp < 0 { - // the input is less than 1 second - let t = <$double_ty>::from(mant) << ($offset + exp); - let nanos_offset = $mant_bits + $offset; - let nanos_tmp = u128::from(NANOS_PER_SEC) * u128::from(t); - let nanos = (nanos_tmp >> nanos_offset) as u32; - - let rem_mask = (1 << nanos_offset) - 1; - let rem_msb_mask = 1 << (nanos_offset - 1); - let rem = nanos_tmp & rem_mask; - let is_tie = rem == rem_msb_mask; - let is_even = (nanos & 1) == 0; - let rem_msb = nanos_tmp & rem_msb_mask == 0; - let add_ns = !(rem_msb || (is_even && is_tie)); - - // f32 does not have enough precision to trigger the second branch - // since it can not represent numbers between 0.999_999_940_395 and 1.0. - let nanos = nanos + add_ns as u32; - if ($mant_bits == 23) || (nanos != NANOS_PER_SEC) { (0, nanos) } else { (1, 0) } - } else if exp < $mant_bits { - let secs = u64::from(mant >> ($mant_bits - exp)); - let t = <$double_ty>::from((mant << exp) & MANT_MASK); - let nanos_offset = $mant_bits; - let nanos_tmp = <$double_ty>::from(NANOS_PER_SEC) * t; - let nanos = (nanos_tmp >> nanos_offset) as u32; - - let rem_mask = (1 << nanos_offset) - 1; - let rem_msb_mask = 1 << (nanos_offset - 1); - let rem = nanos_tmp & rem_mask; - let is_tie = rem == rem_msb_mask; - let is_even = (nanos & 1) == 0; - let rem_msb = nanos_tmp & rem_msb_mask == 0; - let add_ns = !(rem_msb || (is_even && is_tie)); - - // f32 does not have enough precision to trigger the second branch. - // For example, it can not represent numbers between 1.999_999_880... - // and 2.0. Bigger values result in even smaller precision of the - // fractional part. - let nanos = nanos + add_ns as u32; - if ($mant_bits == 23) || (nanos != NANOS_PER_SEC) { - (secs, nanos) - } else { - (secs + 1, 0) - } - } else if exp < 64 { - // the input has no fractional part - let secs = u64::from(mant) << (exp - $mant_bits); - (secs, 0) - } else { - return Err(TryFromFloatSecsError { kind: TryFromFloatSecsErrorKind::OverflowOrNan }); - }; - - Ok(Duration::new(secs, nanos)) - }}; -} - -impl Duration { - /// The checked version of [`from_secs_f32`]. - /// - /// [`from_secs_f32`]: Duration::from_secs_f32 - /// - /// This constructor will return an `Err` if `secs` is negative, overflows `Duration` or not finite. - /// - /// # Examples - /// ``` - /// use std::time::Duration; - /// - /// let res = Duration::try_from_secs_f32(0.0); - /// assert_eq!(res, Ok(Duration::new(0, 0))); - /// let res = Duration::try_from_secs_f32(1e-20); - /// assert_eq!(res, Ok(Duration::new(0, 0))); - /// let res = Duration::try_from_secs_f32(4.2e-7); - /// assert_eq!(res, Ok(Duration::new(0, 420))); - /// let res = Duration::try_from_secs_f32(2.7); - /// assert_eq!(res, Ok(Duration::new(2, 700_000_048))); - /// let res = Duration::try_from_secs_f32(3e10); - /// assert_eq!(res, Ok(Duration::new(30_000_001_024, 0))); - /// // subnormal float: - /// let res = Duration::try_from_secs_f32(f32::from_bits(1)); - /// assert_eq!(res, Ok(Duration::new(0, 0))); - /// - /// let res = Duration::try_from_secs_f32(-5.0); - /// assert!(res.is_err()); - /// let res = Duration::try_from_secs_f32(f32::NAN); - /// assert!(res.is_err()); - /// let res = Duration::try_from_secs_f32(2e19); - /// assert!(res.is_err()); - /// - /// // the conversion uses rounding with tie resolution to even - /// let res = Duration::try_from_secs_f32(0.999e-9); - /// assert_eq!(res, Ok(Duration::new(0, 1))); - /// - /// // this float represents exactly 976562.5e-9 - /// let val = f32::from_bits(0x3A80_0000); - /// let res = Duration::try_from_secs_f32(val); - /// assert_eq!(res, Ok(Duration::new(0, 976_562))); - /// - /// // this float represents exactly 2929687.5e-9 - /// let val = f32::from_bits(0x3B40_0000); - /// let res = Duration::try_from_secs_f32(val); - /// assert_eq!(res, Ok(Duration::new(0, 2_929_688))); - /// - /// // this float represents exactly 1.000_976_562_5 - /// let val = f32::from_bits(0x3F802000); - /// let res = Duration::try_from_secs_f32(val); - /// assert_eq!(res, Ok(Duration::new(1, 976_562))); - /// - /// // this float represents exactly 1.002_929_687_5 - /// let val = f32::from_bits(0x3F806000); - /// let res = Duration::try_from_secs_f32(val); - /// assert_eq!(res, Ok(Duration::new(1, 2_929_688))); - /// ``` - #[stable(feature = "duration_checked_float", since = "1.66.0")] - #[inline] - pub fn try_from_secs_f32(secs: f32) -> Result { - try_from_secs!( - secs = secs, - mantissa_bits = 23, - exponent_bits = 8, - offset = 41, - bits_ty = u32, - double_ty = u64, - ) - } - - /// The checked version of [`from_secs_f64`]. - /// - /// [`from_secs_f64`]: Duration::from_secs_f64 - /// - /// This constructor will return an `Err` if `secs` is negative, overflows `Duration` or not finite. - /// - /// # Examples - /// ``` - /// use std::time::Duration; - /// - /// let res = Duration::try_from_secs_f64(0.0); - /// assert_eq!(res, Ok(Duration::new(0, 0))); - /// let res = Duration::try_from_secs_f64(1e-20); - /// assert_eq!(res, Ok(Duration::new(0, 0))); - /// let res = Duration::try_from_secs_f64(4.2e-7); - /// assert_eq!(res, Ok(Duration::new(0, 420))); - /// let res = Duration::try_from_secs_f64(2.7); - /// assert_eq!(res, Ok(Duration::new(2, 700_000_000))); - /// let res = Duration::try_from_secs_f64(3e10); - /// assert_eq!(res, Ok(Duration::new(30_000_000_000, 0))); - /// // subnormal float - /// let res = Duration::try_from_secs_f64(f64::from_bits(1)); - /// assert_eq!(res, Ok(Duration::new(0, 0))); - /// - /// let res = Duration::try_from_secs_f64(-5.0); - /// assert!(res.is_err()); - /// let res = Duration::try_from_secs_f64(f64::NAN); - /// assert!(res.is_err()); - /// let res = Duration::try_from_secs_f64(2e19); - /// assert!(res.is_err()); - /// - /// // the conversion uses rounding with tie resolution to even - /// let res = Duration::try_from_secs_f64(0.999e-9); - /// assert_eq!(res, Ok(Duration::new(0, 1))); - /// let res = Duration::try_from_secs_f64(0.999_999_999_499); - /// assert_eq!(res, Ok(Duration::new(0, 999_999_999))); - /// let res = Duration::try_from_secs_f64(0.999_999_999_501); - /// assert_eq!(res, Ok(Duration::new(1, 0))); - /// let res = Duration::try_from_secs_f64(42.999_999_999_499); - /// assert_eq!(res, Ok(Duration::new(42, 999_999_999))); - /// let res = Duration::try_from_secs_f64(42.999_999_999_501); - /// assert_eq!(res, Ok(Duration::new(43, 0))); - /// - /// // this float represents exactly 976562.5e-9 - /// let val = f64::from_bits(0x3F50_0000_0000_0000); - /// let res = Duration::try_from_secs_f64(val); - /// assert_eq!(res, Ok(Duration::new(0, 976_562))); - /// - /// // this float represents exactly 2929687.5e-9 - /// let val = f64::from_bits(0x3F68_0000_0000_0000); - /// let res = Duration::try_from_secs_f64(val); - /// assert_eq!(res, Ok(Duration::new(0, 2_929_688))); - /// - /// // this float represents exactly 1.000_976_562_5 - /// let val = f64::from_bits(0x3FF0_0400_0000_0000); - /// let res = Duration::try_from_secs_f64(val); - /// assert_eq!(res, Ok(Duration::new(1, 976_562))); - /// - /// // this float represents exactly 1.002_929_687_5 - /// let val = f64::from_bits(0x3_FF00_C000_0000_000); - /// let res = Duration::try_from_secs_f64(val); - /// assert_eq!(res, Ok(Duration::new(1, 2_929_688))); - /// ``` - #[stable(feature = "duration_checked_float", since = "1.66.0")] - #[inline] - pub fn try_from_secs_f64(secs: f64) -> Result { - try_from_secs!( - secs = secs, - mantissa_bits = 52, - exponent_bits = 11, - offset = 44, - bits_ty = u64, - double_ty = u128, - ) - } -} diff --git a/library/core/src/tuple.rs b/library/core/src/tuple.rs deleted file mode 100644 index 8e961d8adc372..0000000000000 --- a/library/core/src/tuple.rs +++ /dev/null @@ -1,201 +0,0 @@ -// See core/src/primitive_docs.rs for documentation. - -use crate::cmp::Ordering::{self, *}; -use crate::marker::ConstParamTy; -use crate::marker::StructuralPartialEq; - -// Recursive macro for implementing n-ary tuple functions and operations -// -// Also provides implementations for tuples with lesser arity. For example, tuple_impls!(A B C) -// will implement everything for (A, B, C), (A, B) and (A,). -macro_rules! tuple_impls { - // Stopping criteria (1-ary tuple) - ($T:ident) => { - tuple_impls!(@impl $T); - }; - // Running criteria (n-ary tuple, with n >= 2) - ($T:ident $( $U:ident )+) => { - tuple_impls!($( $U )+); - tuple_impls!(@impl $T $( $U )+); - }; - // "Private" internal implementation - (@impl $( $T:ident )+) => { - maybe_tuple_doc! { - $($T)+ @ - #[stable(feature = "rust1", since = "1.0.0")] - impl<$($T: PartialEq),+> PartialEq for ($($T,)+) - where - last_type!($($T,)+): ?Sized - { - #[inline] - fn eq(&self, other: &($($T,)+)) -> bool { - $( ${ignore($T)} self.${index()} == other.${index()} )&&+ - } - #[inline] - fn ne(&self, other: &($($T,)+)) -> bool { - $( ${ignore($T)} self.${index()} != other.${index()} )||+ - } - } - } - - maybe_tuple_doc! { - $($T)+ @ - #[stable(feature = "rust1", since = "1.0.0")] - impl<$($T: Eq),+> Eq for ($($T,)+) - where - last_type!($($T,)+): ?Sized - {} - } - - maybe_tuple_doc! { - $($T)+ @ - #[unstable(feature = "structural_match", issue = "31434")] - impl<$($T: ConstParamTy),+> ConstParamTy for ($($T,)+) - {} - } - - maybe_tuple_doc! { - $($T)+ @ - #[unstable(feature = "structural_match", issue = "31434")] - impl<$($T),+> StructuralPartialEq for ($($T,)+) - {} - } - - maybe_tuple_doc! { - $($T)+ @ - #[stable(feature = "rust1", since = "1.0.0")] - impl<$($T: PartialOrd),+> PartialOrd for ($($T,)+) - where - last_type!($($T,)+): ?Sized - { - #[inline] - fn partial_cmp(&self, other: &($($T,)+)) -> Option { - lexical_partial_cmp!($( ${ignore($T)} self.${index()}, other.${index()} ),+) - } - #[inline] - fn lt(&self, other: &($($T,)+)) -> bool { - lexical_ord!(lt, Less, $( ${ignore($T)} self.${index()}, other.${index()} ),+) - } - #[inline] - fn le(&self, other: &($($T,)+)) -> bool { - lexical_ord!(le, Less, $( ${ignore($T)} self.${index()}, other.${index()} ),+) - } - #[inline] - fn ge(&self, other: &($($T,)+)) -> bool { - lexical_ord!(ge, Greater, $( ${ignore($T)} self.${index()}, other.${index()} ),+) - } - #[inline] - fn gt(&self, other: &($($T,)+)) -> bool { - lexical_ord!(gt, Greater, $( ${ignore($T)} self.${index()}, other.${index()} ),+) - } - } - } - - maybe_tuple_doc! { - $($T)+ @ - #[stable(feature = "rust1", since = "1.0.0")] - impl<$($T: Ord),+> Ord for ($($T,)+) - where - last_type!($($T,)+): ?Sized - { - #[inline] - fn cmp(&self, other: &($($T,)+)) -> Ordering { - lexical_cmp!($( ${ignore($T)} self.${index()}, other.${index()} ),+) - } - } - } - - maybe_tuple_doc! { - $($T)+ @ - #[stable(feature = "rust1", since = "1.0.0")] - impl<$($T: Default),+> Default for ($($T,)+) { - #[inline] - fn default() -> ($($T,)+) { - ($({ let x: $T = Default::default(); x},)+) - } - } - } - - #[stable(feature = "array_tuple_conv", since = "1.71.0")] - impl From<[T; ${count($T)}]> for ($(${ignore($T)} T,)+) { - #[inline] - #[allow(non_snake_case)] - fn from(array: [T; ${count($T)}]) -> Self { - let [$($T,)+] = array; - ($($T,)+) - } - } - - #[stable(feature = "array_tuple_conv", since = "1.71.0")] - impl From<($(${ignore($T)} T,)+)> for [T; ${count($T)}] { - #[inline] - #[allow(non_snake_case)] - fn from(tuple: ($(${ignore($T)} T,)+)) -> Self { - let ($($T,)+) = tuple; - [$($T,)+] - } - } - } -} - -// If this is a unary tuple, it adds a doc comment. -// Otherwise, it hides the docs entirely. -macro_rules! maybe_tuple_doc { - ($a:ident @ #[$meta:meta] $item:item) => { - #[doc(fake_variadic)] - #[doc = "This trait is implemented for tuples up to twelve items long."] - #[$meta] - $item - }; - ($a:ident $($rest_a:ident)+ @ #[$meta:meta] $item:item) => { - #[doc(hidden)] - #[$meta] - $item - }; -} - -// Constructs an expression that performs a lexical ordering using method `$rel`. -// The values are interleaved, so the macro invocation for -// `(a1, a2, a3) < (b1, b2, b3)` would be `lexical_ord!(lt, opt_is_lt, a1, b1, -// a2, b2, a3, b3)` (and similarly for `lexical_cmp`) -// -// `$ne_rel` is only used to determine the result after checking that they're -// not equal, so `lt` and `le` can both just use `Less`. -macro_rules! lexical_ord { - ($rel: ident, $ne_rel: ident, $a:expr, $b:expr, $($rest_a:expr, $rest_b:expr),+) => {{ - let c = PartialOrd::partial_cmp(&$a, &$b); - if c != Some(Equal) { c == Some($ne_rel) } - else { lexical_ord!($rel, $ne_rel, $($rest_a, $rest_b),+) } - }}; - ($rel: ident, $ne_rel: ident, $a:expr, $b:expr) => { - // Use the specific method for the last element - PartialOrd::$rel(&$a, &$b) - }; -} - -macro_rules! lexical_partial_cmp { - ($a:expr, $b:expr, $($rest_a:expr, $rest_b:expr),+) => { - match ($a).partial_cmp(&$b) { - Some(Equal) => lexical_partial_cmp!($($rest_a, $rest_b),+), - ordering => ordering - } - }; - ($a:expr, $b:expr) => { ($a).partial_cmp(&$b) }; -} - -macro_rules! lexical_cmp { - ($a:expr, $b:expr, $($rest_a:expr, $rest_b:expr),+) => { - match ($a).cmp(&$b) { - Equal => lexical_cmp!($($rest_a, $rest_b),+), - ordering => ordering - } - }; - ($a:expr, $b:expr) => { ($a).cmp(&$b) }; -} - -macro_rules! last_type { - ($a:ident,) => { $a }; - ($a:ident, $($rest_a:ident,)+) => { last_type!($($rest_a,)+) }; -} - -tuple_impls!(E D C B A Z Y X W V U T); diff --git a/library/core/src/ub_checks.rs b/library/core/src/ub_checks.rs deleted file mode 100644 index b864b63c5c661..0000000000000 --- a/library/core/src/ub_checks.rs +++ /dev/null @@ -1,210 +0,0 @@ -//! Provides the [`assert_unsafe_precondition`] macro as well as some utility functions that cover -//! common preconditions. - -use crate::intrinsics::{self, const_eval_select}; - -/// Check that the preconditions of an unsafe function are followed. The check is enabled at -/// runtime if debug assertions are enabled when the caller is monomorphized. In const-eval/Miri -/// checks implemented with this macro for language UB are always ignored. -/// -/// This macro should be called as -/// `assert_unsafe_precondition!(check_{library,lang}_ub, "message", (ident: type = expr, ident: type = expr) => check_expr)` -/// where each `expr` will be evaluated and passed in as function argument `ident: type`. Then all -/// those arguments are passed to a function with the body `check_expr`. -/// Pick `check_language_ub` when this is guarding a violation of language UB, i.e., immediate UB -/// according to the Rust Abstract Machine. Pick `check_library_ub` when this is guarding a violation -/// of a documented library precondition that does not *immediately* lead to language UB. -/// -/// If `check_library_ub` is used but the check is actually guarding language UB, the check will -/// slow down const-eval/Miri and we'll get the panic message instead of the interpreter's nice -/// diagnostic, but our ability to detect UB is unchanged. -/// But if `check_language_ub` is used when the check is actually for library UB, the check is -/// omitted in const-eval/Miri and thus if we eventually execute language UB which relies on the -/// library UB, the backtrace Miri reports may be far removed from original cause. -/// -/// These checks are behind a condition which is evaluated at codegen time, not expansion time like -/// [`debug_assert`]. This means that a standard library built with optimizations and debug -/// assertions disabled will have these checks optimized out of its monomorphizations, but if a -/// caller of the standard library has debug assertions enabled and monomorphizes an expansion of -/// this macro, that monomorphization will contain the check. -/// -/// Since these checks cannot be optimized out in MIR, some care must be taken in both call and -/// implementation to mitigate their compile-time overhead. Calls to this macro always expand to -/// this structure: -/// ```ignore (pseudocode) -/// if ::core::intrinsics::check_language_ub() { -/// precondition_check(args) -/// } -/// ``` -/// where `precondition_check` is monomorphic with the attributes `#[rustc_nounwind]`, `#[inline]` and -/// `#[rustc_no_mir_inline]`. This combination of attributes ensures that the actual check logic is -/// compiled only once and generates a minimal amount of IR because the check cannot be inlined in -/// MIR, but *can* be inlined and fully optimized by a codegen backend. -/// -/// Callers should avoid introducing any other `let` bindings or any code outside this macro in -/// order to call it. Since the precompiled standard library is built with full debuginfo and these -/// variables cannot be optimized out in MIR, an innocent-looking `let` can produce enough -/// debuginfo to have a measurable compile-time impact on debug builds. -#[allow_internal_unstable(const_ub_checks)] // permit this to be called in stably-const fn -#[macro_export] -#[unstable(feature = "ub_checks", issue = "none")] -macro_rules! assert_unsafe_precondition { - ($kind:ident, $message:expr, ($($name:ident:$ty:ty = $arg:expr),*$(,)?) => $e:expr $(,)?) => { - { - // This check is inlineable, but not by the MIR inliner. - // The reason for this is that the MIR inliner is in an exceptionally bad position - // to think about whether or not to inline this. In MIR, this call is gated behind `debug_assertions`, - // which will codegen to `false` in release builds. Inlining the check would be wasted work in that case and - // would be bad for compile times. - // - // LLVM on the other hand sees the constant branch, so if it's `false`, it can immediately delete it without - // inlining the check. If it's `true`, it can inline it and get significantly better performance. - #[rustc_no_mir_inline] - #[inline] - #[rustc_nounwind] - #[rustc_const_unstable(feature = "const_ub_checks", issue = "none")] - const fn precondition_check($($name:$ty),*) { - if !$e { - ::core::panicking::panic_nounwind( - concat!("unsafe precondition(s) violated: ", $message) - ); - } - } - - if ::core::ub_checks::$kind() { - precondition_check($($arg,)*); - } - } - }; -} -#[unstable(feature = "ub_checks", issue = "none")] -pub use assert_unsafe_precondition; - -/// Checking library UB is always enabled when UB-checking is done -/// (and we use a reexport so that there is no unnecessary wrapper function). -#[unstable(feature = "ub_checks", issue = "none")] -pub use intrinsics::ub_checks as check_library_ub; - -/// Determines whether we should check for language UB. -/// -/// The intention is to not do that when running in the interpreter, as that one has its own -/// language UB checks which generally produce better errors. -#[rustc_const_unstable(feature = "const_ub_checks", issue = "none")] -#[inline] -pub(crate) const fn check_language_ub() -> bool { - #[inline] - fn runtime() -> bool { - // Disable UB checks in Miri. - !cfg!(miri) - } - - #[inline] - const fn comptime() -> bool { - // Always disable UB checks. - false - } - - // Only used for UB checks so we may const_eval_select. - intrinsics::ub_checks() && const_eval_select((), comptime, runtime) -} - -/// Checks whether `ptr` is properly aligned with respect to -/// `align_of::()`. -/// -/// In `const` this is approximate and can fail spuriously. It is primarily intended -/// for `assert_unsafe_precondition!` with `check_language_ub`, in which case the -/// check is anyway not executed in `const`. -#[inline] -pub(crate) const fn is_aligned_and_not_null(ptr: *const (), align: usize) -> bool { - !ptr.is_null() && ptr.is_aligned_to(align) -} - -#[inline] -pub(crate) const fn is_valid_allocation_size(size: usize, len: usize) -> bool { - let max_len = if size == 0 { usize::MAX } else { isize::MAX as usize / size }; - len <= max_len -} - -/// Checks whether the regions of memory starting at `src` and `dst` of size -/// `count * size` do *not* overlap. -/// -/// Note that in const-eval this function just returns `true` and therefore must -/// only be used with `assert_unsafe_precondition!`, similar to `is_aligned_and_not_null`. -#[inline] -pub(crate) const fn is_nonoverlapping( - src: *const (), - dst: *const (), - size: usize, - count: usize, -) -> bool { - #[inline] - fn runtime(src: *const (), dst: *const (), size: usize, count: usize) -> bool { - let src_usize = src.addr(); - let dst_usize = dst.addr(); - let Some(size) = size.checked_mul(count) else { - crate::panicking::panic_nounwind( - "is_nonoverlapping: `size_of::() * count` overflows a usize", - ) - }; - let diff = src_usize.abs_diff(dst_usize); - // If the absolute distance between the ptrs is at least as big as the size of the buffer, - // they do not overlap. - diff >= size - } - - #[inline] - const fn comptime(_: *const (), _: *const (), _: usize, _: usize) -> bool { - true - } - - // This is just for safety checks so we can const_eval_select. - const_eval_select((src, dst, size, count), comptime, runtime) -} - -pub use predicates::*; - -/// Provide a few predicates to be used in safety contracts. -/// -/// At runtime, they are no-op, and always return true. -#[cfg(not(kani))] -mod predicates { - /// Checks if a pointer can be dereferenced, ensuring: - /// * `src` is valid for reads (see [`crate::ptr`] documentation). - /// * `src` is properly aligned (use `read_unaligned` if not). - /// * `src` points to a properly initialized value of type `T`. - /// - /// [`crate::ptr`]: https://doc.rust-lang.org/std/ptr/index.html - pub fn can_dereference(src: *const T) -> bool { - let _ = src; - true - } - - /// Check if a pointer can be written to: - /// * `dst` must be valid for writes. - /// * `dst` must be properly aligned. Use `write_unaligned` if this is not the - /// case. - pub fn can_write(dst: *mut T) -> bool { - let _ = dst; - true - } - - /// Check if a pointer can be the target of unaligned reads. - /// * `src` must be valid for reads. - /// * `src` must point to a properly initialized value of type `T`. - pub fn can_read_unaligned(src: *const T) -> bool { - let _ = src; - true - } - - /// Check if a pointer can be the target of unaligned writes. - /// * `dst` must be valid for writes. - pub fn can_write_unaligned(dst: *mut T) -> bool { - let _ = dst; - true - } -} - -#[cfg(kani)] -mod predicates { - pub use crate::kani::mem::{can_dereference, can_write, can_read_unaligned, can_write_unaligned}; -} diff --git a/library/core/src/unicode/mod.rs b/library/core/src/unicode/mod.rs deleted file mode 100644 index e1faa407d54c5..0000000000000 --- a/library/core/src/unicode/mod.rs +++ /dev/null @@ -1,31 +0,0 @@ -#![unstable(feature = "unicode_internals", issue = "none")] -#![allow(missing_docs)] - -pub(crate) mod printable; -mod unicode_data; - -/// The version of [Unicode](https://www.unicode.org/) that the Unicode parts of -/// `char` and `str` methods are based on. -/// -/// New versions of Unicode are released regularly and subsequently all methods -/// in the standard library depending on Unicode are updated. Therefore the -/// behavior of some `char` and `str` methods and the value of this constant -/// changes over time. This is *not* considered to be a breaking change. -/// -/// The version numbering scheme is explained in -/// [Unicode 11.0 or later, Section 3.1 Versions of the Unicode Standard](https://www.unicode.org/versions/Unicode11.0.0/ch03.pdf#page=4). -#[stable(feature = "unicode_version", since = "1.45.0")] -pub const UNICODE_VERSION: (u8, u8, u8) = unicode_data::UNICODE_VERSION; - -// For use in alloc, not re-exported in std. -pub use unicode_data::{ - case_ignorable::lookup as Case_Ignorable, cased::lookup as Cased, conversions, -}; - -pub(crate) use unicode_data::alphabetic::lookup as Alphabetic; -pub(crate) use unicode_data::cc::lookup as Cc; -pub(crate) use unicode_data::grapheme_extend::lookup as Grapheme_Extend; -pub(crate) use unicode_data::lowercase::lookup as Lowercase; -pub(crate) use unicode_data::n::lookup as N; -pub(crate) use unicode_data::uppercase::lookup as Uppercase; -pub(crate) use unicode_data::white_space::lookup as White_Space; diff --git a/library/core/src/unicode/printable.py b/library/core/src/unicode/printable.py deleted file mode 100755 index 4d39ace066c46..0000000000000 --- a/library/core/src/unicode/printable.py +++ /dev/null @@ -1,243 +0,0 @@ -#!/usr/bin/env python - -# This script uses the following Unicode tables: -# - UnicodeData.txt - - -from collections import namedtuple -import csv -import os -import subprocess - -NUM_CODEPOINTS=0x110000 - -def to_ranges(iter): - current = None - for i in iter: - if current is None or i != current[1] or i in (0x10000, 0x20000): - if current is not None: - yield tuple(current) - current = [i, i + 1] - else: - current[1] += 1 - if current is not None: - yield tuple(current) - -def get_escaped(codepoints): - for c in codepoints: - if (c.class_ or "Cn") in "Cc Cf Cs Co Cn Zl Zp Zs".split() and c.value != ord(' '): - yield c.value - -def get_file(f): - try: - return open(os.path.basename(f)) - except FileNotFoundError: - subprocess.run(["curl", "-O", f], check=True) - return open(os.path.basename(f)) - -Codepoint = namedtuple('Codepoint', 'value class_') - -def get_codepoints(f): - r = csv.reader(f, delimiter=";") - prev_codepoint = 0 - class_first = None - for row in r: - codepoint = int(row[0], 16) - name = row[1] - class_ = row[2] - - if class_first is not None: - if not name.endswith("Last>"): - raise ValueError("Missing Last after First") - - for c in range(prev_codepoint + 1, codepoint): - yield Codepoint(c, class_first) - - class_first = None - if name.endswith("First>"): - class_first = class_ - - yield Codepoint(codepoint, class_) - prev_codepoint = codepoint - - if class_first is not None: - raise ValueError("Missing Last after First") - - for c in range(prev_codepoint + 1, NUM_CODEPOINTS): - yield Codepoint(c, None) - -def compress_singletons(singletons): - uppers = [] # (upper, # items in lowers) - lowers = [] - - for i in singletons: - upper = i >> 8 - lower = i & 0xff - if len(uppers) == 0 or uppers[-1][0] != upper: - uppers.append((upper, 1)) - else: - upper, count = uppers[-1] - uppers[-1] = upper, count + 1 - lowers.append(lower) - - return uppers, lowers - -def compress_normal(normal): - # lengths 0x00..0x7f are encoded as 00, 01, ..., 7e, 7f - # lengths 0x80..0x7fff are encoded as 80 80, 80 81, ..., ff fe, ff ff - compressed = [] # [truelen, (truelenaux), falselen, (falselenaux)] - - prev_start = 0 - for start, count in normal: - truelen = start - prev_start - falselen = count - prev_start = start + count - - assert truelen < 0x8000 and falselen < 0x8000 - entry = [] - if truelen > 0x7f: - entry.append(0x80 | (truelen >> 8)) - entry.append(truelen & 0xff) - else: - entry.append(truelen & 0x7f) - if falselen > 0x7f: - entry.append(0x80 | (falselen >> 8)) - entry.append(falselen & 0xff) - else: - entry.append(falselen & 0x7f) - - compressed.append(entry) - - return compressed - -def print_singletons(uppers, lowers, uppersname, lowersname): - print("#[rustfmt::skip]") - print("const {}: &[(u8, u8)] = &[".format(uppersname)) - for u, c in uppers: - print(" ({:#04x}, {}),".format(u, c)) - print("];") - print("#[rustfmt::skip]") - print("const {}: &[u8] = &[".format(lowersname)) - for i in range(0, len(lowers), 8): - print(" {}".format(" ".join("{:#04x},".format(x) for x in lowers[i:i+8]))) - print("];") - -def print_normal(normal, normalname): - print("#[rustfmt::skip]") - print("const {}: &[u8] = &[".format(normalname)) - for v in normal: - print(" {}".format(" ".join("{:#04x},".format(i) for i in v))) - print("];") - -def main(): - file = get_file("https://www.unicode.org/Public/UNIDATA/UnicodeData.txt") - - codepoints = get_codepoints(file) - - CUTOFF=0x10000 - singletons0 = [] - singletons1 = [] - normal0 = [] - normal1 = [] - extra = [] - - for a, b in to_ranges(get_escaped(codepoints)): - if a > 2 * CUTOFF: - extra.append((a, b - a)) - elif a == b - 1: - if a & CUTOFF: - singletons1.append(a & ~CUTOFF) - else: - singletons0.append(a) - elif a == b - 2: - if a & CUTOFF: - singletons1.append(a & ~CUTOFF) - singletons1.append((a + 1) & ~CUTOFF) - else: - singletons0.append(a) - singletons0.append(a + 1) - else: - if a >= 2 * CUTOFF: - extra.append((a, b - a)) - elif a & CUTOFF: - normal1.append((a & ~CUTOFF, b - a)) - else: - normal0.append((a, b - a)) - - singletons0u, singletons0l = compress_singletons(singletons0) - singletons1u, singletons1l = compress_singletons(singletons1) - normal0 = compress_normal(normal0) - normal1 = compress_normal(normal1) - - print("""\ -// NOTE: The following code was generated by "library/core/src/unicode/printable.py", -// do not edit directly! - -fn check(x: u16, singletonuppers: &[(u8, u8)], singletonlowers: &[u8], normal: &[u8]) -> bool { - let xupper = (x >> 8) as u8; - let mut lowerstart = 0; - for &(upper, lowercount) in singletonuppers { - let lowerend = lowerstart + lowercount as usize; - if xupper == upper { - for &lower in &singletonlowers[lowerstart..lowerend] { - if lower == x as u8 { - return false; - } - } - } else if xupper < upper { - break; - } - lowerstart = lowerend; - } - - let mut x = x as i32; - let mut normal = normal.iter().cloned(); - let mut current = true; - while let Some(v) = normal.next() { - let len = if v & 0x80 != 0 { - ((v & 0x7f) as i32) << 8 | normal.next().unwrap() as i32 - } else { - v as i32 - }; - x -= len; - if x < 0 { - break; - } - current = !current; - } - current -} - -pub(crate) fn is_printable(x: char) -> bool { - let x = x as u32; - let lower = x as u16; - - if x < 32 { - // ASCII fast path - false - } else if x < 127 { - // ASCII fast path - true - } else if x < 0x10000 { - check(lower, SINGLETONS0U, SINGLETONS0L, NORMAL0) - } else if x < 0x20000 { - check(lower, SINGLETONS1U, SINGLETONS1L, NORMAL1) - } else {\ -""") - for a, b in extra: - print(" if 0x{:x} <= x && x < 0x{:x} {{".format(a, a + b)) - print(" return false;") - print(" }") - print("""\ - true - } -}\ -""") - print() - print_singletons(singletons0u, singletons0l, 'SINGLETONS0U', 'SINGLETONS0L') - print_singletons(singletons1u, singletons1l, 'SINGLETONS1U', 'SINGLETONS1L') - print_normal(normal0, 'NORMAL0') - print_normal(normal1, 'NORMAL1') - -if __name__ == '__main__': - main() diff --git a/library/core/src/unicode/printable.rs b/library/core/src/unicode/printable.rs deleted file mode 100644 index 33c3ef8083de5..0000000000000 --- a/library/core/src/unicode/printable.rs +++ /dev/null @@ -1,588 +0,0 @@ -// NOTE: The following code was generated by "library/core/src/unicode/printable.py", -// do not edit directly! - -fn check(x: u16, singletonuppers: &[(u8, u8)], singletonlowers: &[u8], normal: &[u8]) -> bool { - let xupper = (x >> 8) as u8; - let mut lowerstart = 0; - for &(upper, lowercount) in singletonuppers { - let lowerend = lowerstart + lowercount as usize; - if xupper == upper { - for &lower in &singletonlowers[lowerstart..lowerend] { - if lower == x as u8 { - return false; - } - } - } else if xupper < upper { - break; - } - lowerstart = lowerend; - } - - let mut x = x as i32; - let mut normal = normal.iter().cloned(); - let mut current = true; - while let Some(v) = normal.next() { - let len = if v & 0x80 != 0 { - ((v & 0x7f) as i32) << 8 | normal.next().unwrap() as i32 - } else { - v as i32 - }; - x -= len; - if x < 0 { - break; - } - current = !current; - } - current -} - -pub(crate) fn is_printable(x: char) -> bool { - let x = x as u32; - let lower = x as u16; - - if x < 32 { - // ASCII fast path - false - } else if x < 127 { - // ASCII fast path - true - } else if x < 0x10000 { - check(lower, SINGLETONS0U, SINGLETONS0L, NORMAL0) - } else if x < 0x20000 { - check(lower, SINGLETONS1U, SINGLETONS1L, NORMAL1) - } else { - if 0x2a6e0 <= x && x < 0x2a700 { - return false; - } - if 0x2b73a <= x && x < 0x2b740 { - return false; - } - if 0x2b81e <= x && x < 0x2b820 { - return false; - } - if 0x2cea2 <= x && x < 0x2ceb0 { - return false; - } - if 0x2ebe1 <= x && x < 0x2ebf0 { - return false; - } - if 0x2ee5e <= x && x < 0x2f800 { - return false; - } - if 0x2fa1e <= x && x < 0x30000 { - return false; - } - if 0x3134b <= x && x < 0x31350 { - return false; - } - if 0x323b0 <= x && x < 0xe0100 { - return false; - } - if 0xe01f0 <= x && x < 0x110000 { - return false; - } - true - } -} - -#[rustfmt::skip] -const SINGLETONS0U: &[(u8, u8)] = &[ - (0x00, 1), - (0x03, 5), - (0x05, 6), - (0x06, 2), - (0x07, 6), - (0x08, 7), - (0x09, 17), - (0x0a, 28), - (0x0b, 25), - (0x0c, 26), - (0x0d, 16), - (0x0e, 12), - (0x0f, 4), - (0x10, 3), - (0x12, 18), - (0x13, 9), - (0x16, 1), - (0x17, 4), - (0x18, 1), - (0x19, 3), - (0x1a, 7), - (0x1b, 1), - (0x1c, 2), - (0x1f, 22), - (0x20, 3), - (0x2b, 3), - (0x2d, 11), - (0x2e, 1), - (0x30, 4), - (0x31, 2), - (0x32, 1), - (0xa7, 2), - (0xa9, 2), - (0xaa, 4), - (0xab, 8), - (0xfa, 2), - (0xfb, 5), - (0xfd, 2), - (0xfe, 3), - (0xff, 9), -]; -#[rustfmt::skip] -const SINGLETONS0L: &[u8] = &[ - 0xad, 0x78, 0x79, 0x8b, 0x8d, 0xa2, 0x30, 0x57, - 0x58, 0x8b, 0x8c, 0x90, 0x1c, 0xdd, 0x0e, 0x0f, - 0x4b, 0x4c, 0xfb, 0xfc, 0x2e, 0x2f, 0x3f, 0x5c, - 0x5d, 0x5f, 0xe2, 0x84, 0x8d, 0x8e, 0x91, 0x92, - 0xa9, 0xb1, 0xba, 0xbb, 0xc5, 0xc6, 0xc9, 0xca, - 0xde, 0xe4, 0xe5, 0xff, 0x00, 0x04, 0x11, 0x12, - 0x29, 0x31, 0x34, 0x37, 0x3a, 0x3b, 0x3d, 0x49, - 0x4a, 0x5d, 0x84, 0x8e, 0x92, 0xa9, 0xb1, 0xb4, - 0xba, 0xbb, 0xc6, 0xca, 0xce, 0xcf, 0xe4, 0xe5, - 0x00, 0x04, 0x0d, 0x0e, 0x11, 0x12, 0x29, 0x31, - 0x34, 0x3a, 0x3b, 0x45, 0x46, 0x49, 0x4a, 0x5e, - 0x64, 0x65, 0x84, 0x91, 0x9b, 0x9d, 0xc9, 0xce, - 0xcf, 0x0d, 0x11, 0x29, 0x3a, 0x3b, 0x45, 0x49, - 0x57, 0x5b, 0x5c, 0x5e, 0x5f, 0x64, 0x65, 0x8d, - 0x91, 0xa9, 0xb4, 0xba, 0xbb, 0xc5, 0xc9, 0xdf, - 0xe4, 0xe5, 0xf0, 0x0d, 0x11, 0x45, 0x49, 0x64, - 0x65, 0x80, 0x84, 0xb2, 0xbc, 0xbe, 0xbf, 0xd5, - 0xd7, 0xf0, 0xf1, 0x83, 0x85, 0x8b, 0xa4, 0xa6, - 0xbe, 0xbf, 0xc5, 0xc7, 0xcf, 0xda, 0xdb, 0x48, - 0x98, 0xbd, 0xcd, 0xc6, 0xce, 0xcf, 0x49, 0x4e, - 0x4f, 0x57, 0x59, 0x5e, 0x5f, 0x89, 0x8e, 0x8f, - 0xb1, 0xb6, 0xb7, 0xbf, 0xc1, 0xc6, 0xc7, 0xd7, - 0x11, 0x16, 0x17, 0x5b, 0x5c, 0xf6, 0xf7, 0xfe, - 0xff, 0x80, 0x6d, 0x71, 0xde, 0xdf, 0x0e, 0x1f, - 0x6e, 0x6f, 0x1c, 0x1d, 0x5f, 0x7d, 0x7e, 0xae, - 0xaf, 0x7f, 0xbb, 0xbc, 0x16, 0x17, 0x1e, 0x1f, - 0x46, 0x47, 0x4e, 0x4f, 0x58, 0x5a, 0x5c, 0x5e, - 0x7e, 0x7f, 0xb5, 0xc5, 0xd4, 0xd5, 0xdc, 0xf0, - 0xf1, 0xf5, 0x72, 0x73, 0x8f, 0x74, 0x75, 0x96, - 0x26, 0x2e, 0x2f, 0xa7, 0xaf, 0xb7, 0xbf, 0xc7, - 0xcf, 0xd7, 0xdf, 0x9a, 0x00, 0x40, 0x97, 0x98, - 0x30, 0x8f, 0x1f, 0xd2, 0xd4, 0xce, 0xff, 0x4e, - 0x4f, 0x5a, 0x5b, 0x07, 0x08, 0x0f, 0x10, 0x27, - 0x2f, 0xee, 0xef, 0x6e, 0x6f, 0x37, 0x3d, 0x3f, - 0x42, 0x45, 0x90, 0x91, 0x53, 0x67, 0x75, 0xc8, - 0xc9, 0xd0, 0xd1, 0xd8, 0xd9, 0xe7, 0xfe, 0xff, -]; -#[rustfmt::skip] -const SINGLETONS1U: &[(u8, u8)] = &[ - (0x00, 6), - (0x01, 1), - (0x03, 1), - (0x04, 2), - (0x05, 7), - (0x07, 2), - (0x08, 8), - (0x09, 2), - (0x0a, 5), - (0x0b, 2), - (0x0e, 4), - (0x10, 1), - (0x11, 2), - (0x12, 5), - (0x13, 17), - (0x14, 1), - (0x15, 2), - (0x17, 2), - (0x19, 13), - (0x1c, 5), - (0x1d, 8), - (0x1f, 1), - (0x24, 1), - (0x6a, 4), - (0x6b, 2), - (0xaf, 3), - (0xb1, 2), - (0xbc, 2), - (0xcf, 2), - (0xd1, 2), - (0xd4, 12), - (0xd5, 9), - (0xd6, 2), - (0xd7, 2), - (0xda, 1), - (0xe0, 5), - (0xe1, 2), - (0xe7, 4), - (0xe8, 2), - (0xee, 32), - (0xf0, 4), - (0xf8, 2), - (0xfa, 3), - (0xfb, 1), -]; -#[rustfmt::skip] -const SINGLETONS1L: &[u8] = &[ - 0x0c, 0x27, 0x3b, 0x3e, 0x4e, 0x4f, 0x8f, 0x9e, - 0x9e, 0x9f, 0x7b, 0x8b, 0x93, 0x96, 0xa2, 0xb2, - 0xba, 0x86, 0xb1, 0x06, 0x07, 0x09, 0x36, 0x3d, - 0x3e, 0x56, 0xf3, 0xd0, 0xd1, 0x04, 0x14, 0x18, - 0x36, 0x37, 0x56, 0x57, 0x7f, 0xaa, 0xae, 0xaf, - 0xbd, 0x35, 0xe0, 0x12, 0x87, 0x89, 0x8e, 0x9e, - 0x04, 0x0d, 0x0e, 0x11, 0x12, 0x29, 0x31, 0x34, - 0x3a, 0x45, 0x46, 0x49, 0x4a, 0x4e, 0x4f, 0x64, - 0x65, 0x5c, 0xb6, 0xb7, 0x1b, 0x1c, 0x07, 0x08, - 0x0a, 0x0b, 0x14, 0x17, 0x36, 0x39, 0x3a, 0xa8, - 0xa9, 0xd8, 0xd9, 0x09, 0x37, 0x90, 0x91, 0xa8, - 0x07, 0x0a, 0x3b, 0x3e, 0x66, 0x69, 0x8f, 0x92, - 0x11, 0x6f, 0x5f, 0xbf, 0xee, 0xef, 0x5a, 0x62, - 0xf4, 0xfc, 0xff, 0x53, 0x54, 0x9a, 0x9b, 0x2e, - 0x2f, 0x27, 0x28, 0x55, 0x9d, 0xa0, 0xa1, 0xa3, - 0xa4, 0xa7, 0xa8, 0xad, 0xba, 0xbc, 0xc4, 0x06, - 0x0b, 0x0c, 0x15, 0x1d, 0x3a, 0x3f, 0x45, 0x51, - 0xa6, 0xa7, 0xcc, 0xcd, 0xa0, 0x07, 0x19, 0x1a, - 0x22, 0x25, 0x3e, 0x3f, 0xe7, 0xec, 0xef, 0xff, - 0xc5, 0xc6, 0x04, 0x20, 0x23, 0x25, 0x26, 0x28, - 0x33, 0x38, 0x3a, 0x48, 0x4a, 0x4c, 0x50, 0x53, - 0x55, 0x56, 0x58, 0x5a, 0x5c, 0x5e, 0x60, 0x63, - 0x65, 0x66, 0x6b, 0x73, 0x78, 0x7d, 0x7f, 0x8a, - 0xa4, 0xaa, 0xaf, 0xb0, 0xc0, 0xd0, 0xae, 0xaf, - 0x6e, 0x6f, 0xbe, 0x93, -]; -#[rustfmt::skip] -const NORMAL0: &[u8] = &[ - 0x00, 0x20, - 0x5f, 0x22, - 0x82, 0xdf, 0x04, - 0x82, 0x44, 0x08, - 0x1b, 0x04, - 0x06, 0x11, - 0x81, 0xac, 0x0e, - 0x80, 0xab, 0x05, - 0x1f, 0x09, - 0x81, 0x1b, 0x03, - 0x19, 0x08, - 0x01, 0x04, - 0x2f, 0x04, - 0x34, 0x04, - 0x07, 0x03, - 0x01, 0x07, - 0x06, 0x07, - 0x11, 0x0a, - 0x50, 0x0f, - 0x12, 0x07, - 0x55, 0x07, - 0x03, 0x04, - 0x1c, 0x0a, - 0x09, 0x03, - 0x08, 0x03, - 0x07, 0x03, - 0x02, 0x03, - 0x03, 0x03, - 0x0c, 0x04, - 0x05, 0x03, - 0x0b, 0x06, - 0x01, 0x0e, - 0x15, 0x05, - 0x4e, 0x07, - 0x1b, 0x07, - 0x57, 0x07, - 0x02, 0x06, - 0x17, 0x0c, - 0x50, 0x04, - 0x43, 0x03, - 0x2d, 0x03, - 0x01, 0x04, - 0x11, 0x06, - 0x0f, 0x0c, - 0x3a, 0x04, - 0x1d, 0x25, - 0x5f, 0x20, - 0x6d, 0x04, - 0x6a, 0x25, - 0x80, 0xc8, 0x05, - 0x82, 0xb0, 0x03, - 0x1a, 0x06, - 0x82, 0xfd, 0x03, - 0x59, 0x07, - 0x16, 0x09, - 0x18, 0x09, - 0x14, 0x0c, - 0x14, 0x0c, - 0x6a, 0x06, - 0x0a, 0x06, - 0x1a, 0x06, - 0x59, 0x07, - 0x2b, 0x05, - 0x46, 0x0a, - 0x2c, 0x04, - 0x0c, 0x04, - 0x01, 0x03, - 0x31, 0x0b, - 0x2c, 0x04, - 0x1a, 0x06, - 0x0b, 0x03, - 0x80, 0xac, 0x06, - 0x0a, 0x06, - 0x2f, 0x31, - 0x4d, 0x03, - 0x80, 0xa4, 0x08, - 0x3c, 0x03, - 0x0f, 0x03, - 0x3c, 0x07, - 0x38, 0x08, - 0x2b, 0x05, - 0x82, 0xff, 0x11, - 0x18, 0x08, - 0x2f, 0x11, - 0x2d, 0x03, - 0x21, 0x0f, - 0x21, 0x0f, - 0x80, 0x8c, 0x04, - 0x82, 0x97, 0x19, - 0x0b, 0x15, - 0x88, 0x94, 0x05, - 0x2f, 0x05, - 0x3b, 0x07, - 0x02, 0x0e, - 0x18, 0x09, - 0x80, 0xbe, 0x22, - 0x74, 0x0c, - 0x80, 0xd6, 0x1a, - 0x81, 0x10, 0x05, - 0x80, 0xdf, 0x0b, - 0xf2, 0x9e, 0x03, - 0x37, 0x09, - 0x81, 0x5c, 0x14, - 0x80, 0xb8, 0x08, - 0x80, 0xcb, 0x05, - 0x0a, 0x18, - 0x3b, 0x03, - 0x0a, 0x06, - 0x38, 0x08, - 0x46, 0x08, - 0x0c, 0x06, - 0x74, 0x0b, - 0x1e, 0x03, - 0x5a, 0x04, - 0x59, 0x09, - 0x80, 0x83, 0x18, - 0x1c, 0x0a, - 0x16, 0x09, - 0x4c, 0x04, - 0x80, 0x8a, 0x06, - 0xab, 0xa4, 0x0c, - 0x17, 0x04, - 0x31, 0xa1, 0x04, - 0x81, 0xda, 0x26, - 0x07, 0x0c, - 0x05, 0x05, - 0x80, 0xa6, 0x10, - 0x81, 0xf5, 0x07, - 0x01, 0x20, - 0x2a, 0x06, - 0x4c, 0x04, - 0x80, 0x8d, 0x04, - 0x80, 0xbe, 0x03, - 0x1b, 0x03, - 0x0f, 0x0d, -]; -#[rustfmt::skip] -const NORMAL1: &[u8] = &[ - 0x5e, 0x22, - 0x7b, 0x05, - 0x03, 0x04, - 0x2d, 0x03, - 0x66, 0x03, - 0x01, 0x2f, - 0x2e, 0x80, 0x82, - 0x1d, 0x03, - 0x31, 0x0f, - 0x1c, 0x04, - 0x24, 0x09, - 0x1e, 0x05, - 0x2b, 0x05, - 0x44, 0x04, - 0x0e, 0x2a, - 0x80, 0xaa, 0x06, - 0x24, 0x04, - 0x24, 0x04, - 0x28, 0x08, - 0x34, 0x0b, - 0x4e, 0x43, - 0x81, 0x37, 0x09, - 0x16, 0x0a, - 0x08, 0x18, - 0x3b, 0x45, - 0x39, 0x03, - 0x63, 0x08, - 0x09, 0x30, - 0x16, 0x05, - 0x21, 0x03, - 0x1b, 0x05, - 0x01, 0x40, - 0x38, 0x04, - 0x4b, 0x05, - 0x2f, 0x04, - 0x0a, 0x07, - 0x09, 0x07, - 0x40, 0x20, - 0x27, 0x04, - 0x0c, 0x09, - 0x36, 0x03, - 0x3a, 0x05, - 0x1a, 0x07, - 0x04, 0x0c, - 0x07, 0x50, - 0x49, 0x37, - 0x33, 0x0d, - 0x33, 0x07, - 0x2e, 0x08, - 0x0a, 0x81, 0x26, - 0x52, 0x4b, - 0x2b, 0x08, - 0x2a, 0x16, - 0x1a, 0x26, - 0x1c, 0x14, - 0x17, 0x09, - 0x4e, 0x04, - 0x24, 0x09, - 0x44, 0x0d, - 0x19, 0x07, - 0x0a, 0x06, - 0x48, 0x08, - 0x27, 0x09, - 0x75, 0x0b, - 0x42, 0x3e, - 0x2a, 0x06, - 0x3b, 0x05, - 0x0a, 0x06, - 0x51, 0x06, - 0x01, 0x05, - 0x10, 0x03, - 0x05, 0x80, 0x8b, - 0x62, 0x1e, - 0x48, 0x08, - 0x0a, 0x80, 0xa6, - 0x5e, 0x22, - 0x45, 0x0b, - 0x0a, 0x06, - 0x0d, 0x13, - 0x3a, 0x06, - 0x0a, 0x36, - 0x2c, 0x04, - 0x17, 0x80, 0xb9, - 0x3c, 0x64, - 0x53, 0x0c, - 0x48, 0x09, - 0x0a, 0x46, - 0x45, 0x1b, - 0x48, 0x08, - 0x53, 0x0d, - 0x49, 0x07, - 0x0a, 0x80, 0xf6, - 0x46, 0x0a, - 0x1d, 0x03, - 0x47, 0x49, - 0x37, 0x03, - 0x0e, 0x08, - 0x0a, 0x06, - 0x39, 0x07, - 0x0a, 0x81, 0x36, - 0x19, 0x07, - 0x3b, 0x03, - 0x1c, 0x56, - 0x01, 0x0f, - 0x32, 0x0d, - 0x83, 0x9b, 0x66, - 0x75, 0x0b, - 0x80, 0xc4, 0x8a, 0x4c, - 0x63, 0x0d, - 0x84, 0x30, 0x10, - 0x16, 0x8f, 0xaa, - 0x82, 0x47, 0xa1, 0xb9, - 0x82, 0x39, 0x07, - 0x2a, 0x04, - 0x5c, 0x06, - 0x26, 0x0a, - 0x46, 0x0a, - 0x28, 0x05, - 0x13, 0x82, 0xb0, - 0x5b, 0x65, - 0x4b, 0x04, - 0x39, 0x07, - 0x11, 0x40, - 0x05, 0x0b, - 0x02, 0x0e, - 0x97, 0xf8, 0x08, - 0x84, 0xd6, 0x2a, - 0x09, 0xa2, 0xe7, - 0x81, 0x33, 0x0f, - 0x01, 0x1d, - 0x06, 0x0e, - 0x04, 0x08, - 0x81, 0x8c, 0x89, 0x04, - 0x6b, 0x05, - 0x0d, 0x03, - 0x09, 0x07, - 0x10, 0x92, 0x60, - 0x47, 0x09, - 0x74, 0x3c, - 0x80, 0xf6, 0x0a, - 0x73, 0x08, - 0x70, 0x15, - 0x46, 0x7a, - 0x14, 0x0c, - 0x14, 0x0c, - 0x57, 0x09, - 0x19, 0x80, 0x87, - 0x81, 0x47, 0x03, - 0x85, 0x42, 0x0f, - 0x15, 0x84, 0x50, - 0x1f, 0x06, - 0x06, 0x80, 0xd5, - 0x2b, 0x05, - 0x3e, 0x21, - 0x01, 0x70, - 0x2d, 0x03, - 0x1a, 0x04, - 0x02, 0x81, 0x40, - 0x1f, 0x11, - 0x3a, 0x05, - 0x01, 0x81, 0xd0, - 0x2a, 0x82, 0xe6, - 0x80, 0xf7, 0x29, - 0x4c, 0x04, - 0x0a, 0x04, - 0x02, 0x83, 0x11, - 0x44, 0x4c, - 0x3d, 0x80, 0xc2, - 0x3c, 0x06, - 0x01, 0x04, - 0x55, 0x05, - 0x1b, 0x34, - 0x02, 0x81, 0x0e, - 0x2c, 0x04, - 0x64, 0x0c, - 0x56, 0x0a, - 0x80, 0xae, 0x38, - 0x1d, 0x0d, - 0x2c, 0x04, - 0x09, 0x07, - 0x02, 0x0e, - 0x06, 0x80, 0x9a, - 0x83, 0xd8, 0x04, - 0x11, 0x03, - 0x0d, 0x03, - 0x77, 0x04, - 0x5f, 0x06, - 0x0c, 0x04, - 0x01, 0x0f, - 0x0c, 0x04, - 0x38, 0x08, - 0x0a, 0x06, - 0x28, 0x08, - 0x22, 0x4e, - 0x81, 0x54, 0x0c, - 0x1d, 0x03, - 0x09, 0x07, - 0x36, 0x08, - 0x0e, 0x04, - 0x09, 0x07, - 0x09, 0x07, - 0x80, 0xcb, 0x25, - 0x0a, 0x84, 0x06, -]; diff --git a/library/core/src/unicode/unicode_data.rs b/library/core/src/unicode/unicode_data.rs deleted file mode 100644 index 1b3d6729663b5..0000000000000 --- a/library/core/src/unicode/unicode_data.rs +++ /dev/null @@ -1,1387 +0,0 @@ -///! This file is generated by src/tools/unicode-table-generator; do not edit manually! - -#[rustc_const_unstable(feature = "const_unicode_case_lookup", issue = "101400")] -#[inline(always)] -const fn bitset_search< - const N: usize, - const CHUNK_SIZE: usize, - const N1: usize, - const CANONICAL: usize, - const CANONICALIZED: usize, ->( - needle: u32, - chunk_idx_map: &[u8; N], - bitset_chunk_idx: &[[u8; CHUNK_SIZE]; N1], - bitset_canonical: &[u64; CANONICAL], - bitset_canonicalized: &[(u8, u8); CANONICALIZED], -) -> bool { - let bucket_idx = (needle / 64) as usize; - let chunk_map_idx = bucket_idx / CHUNK_SIZE; - let chunk_piece = bucket_idx % CHUNK_SIZE; - // FIXME: const-hack: Revert to `slice::get` after `const_slice_index` - // feature stabilizes. - let chunk_idx = if chunk_map_idx < chunk_idx_map.len() { - chunk_idx_map[chunk_map_idx] - } else { - return false; - }; - let idx = bitset_chunk_idx[chunk_idx as usize][chunk_piece] as usize; - // FIXME: const-hack: Revert to `slice::get` after `const_slice_index` - // feature stabilizes. - let word = if idx < bitset_canonical.len() { - bitset_canonical[idx] - } else { - let (real_idx, mapping) = bitset_canonicalized[idx - bitset_canonical.len()]; - let mut word = bitset_canonical[real_idx as usize]; - let should_invert = mapping & (1 << 6) != 0; - if should_invert { - word = !word; - } - // Lower 6 bits - let quantity = mapping & ((1 << 6) - 1); - if mapping & (1 << 7) != 0 { - // shift - word >>= quantity as u64; - } else { - word = word.rotate_left(quantity as u32); - } - word - }; - (word & (1 << (needle % 64) as u64)) != 0 -} - -fn decode_prefix_sum(short_offset_run_header: u32) -> u32 { - short_offset_run_header & ((1 << 21) - 1) -} - -fn decode_length(short_offset_run_header: u32) -> usize { - (short_offset_run_header >> 21) as usize -} - -#[inline(always)] -fn skip_search( - needle: u32, - short_offset_runs: &[u32; SOR], - offsets: &[u8; OFFSETS], -) -> bool { - // Note that this *cannot* be past the end of the array, as the last - // element is greater than std::char::MAX (the largest possible needle). - // - // So, we cannot have found it (i.e. Ok(idx) + 1 != length) and the correct - // location cannot be past it, so Err(idx) != length either. - // - // This means that we can avoid bounds checking for the accesses below, too. - let last_idx = - match short_offset_runs.binary_search_by_key(&(needle << 11), |header| header << 11) { - Ok(idx) => idx + 1, - Err(idx) => idx, - }; - - let mut offset_idx = decode_length(short_offset_runs[last_idx]); - let length = if let Some(next) = short_offset_runs.get(last_idx + 1) { - decode_length(*next) - offset_idx - } else { - offsets.len() - offset_idx - }; - let prev = - last_idx.checked_sub(1).map(|prev| decode_prefix_sum(short_offset_runs[prev])).unwrap_or(0); - - let total = needle - prev; - let mut prefix_sum = 0; - for _ in 0..(length - 1) { - let offset = offsets[offset_idx]; - prefix_sum += offset as u32; - if prefix_sum > total { - break; - } - offset_idx += 1; - } - offset_idx % 2 == 1 -} - -pub const UNICODE_VERSION: (u8, u8, u8) = (15, 1, 0); - -#[rustfmt::skip] -pub mod alphabetic { - static SHORT_OFFSET_RUNS: [u32; 54] = [ - 706, 33559113, 872420973, 952114966, 1161831606, 1310731264, 1314926597, 1394619392, - 1444957632, 1447077005, 1451271693, 1459672996, 1648425216, 1658911342, 1661009214, - 1707147904, 1793132343, 1887506048, 2040601600, 2392923872, 2481005466, 2504077200, - 2514564144, 2520859648, 2527151687, 2529257472, 2531355193, 2533453376, 2564917240, - 2596375766, 2600579056, 2606870819, 2621551356, 2642525184, 2644628480, 2665600678, - 2743197440, 2791432848, 2841765072, 2850154464, 2854350336, 2887905584, 3026321408, - 3038947040, 3041048378, 3045248674, 3053644769, 3057839710, 3062036480, 3064134174, - 3066232832, 3068334923, 3070436272, 3075744688, - ]; - static OFFSETS: [u8; 1467] = [ - 65, 26, 6, 26, 47, 1, 10, 1, 4, 1, 5, 23, 1, 31, 1, 0, 4, 12, 14, 5, 7, 1, 1, 1, 86, 1, 42, - 5, 1, 2, 2, 4, 1, 1, 6, 1, 1, 3, 1, 1, 1, 20, 1, 83, 1, 139, 8, 166, 1, 38, 2, 1, 6, 41, 39, - 14, 1, 1, 1, 2, 1, 2, 1, 1, 8, 27, 4, 4, 29, 11, 5, 56, 1, 7, 14, 102, 1, 8, 4, 8, 4, 3, 10, - 3, 2, 1, 16, 48, 13, 101, 24, 33, 9, 2, 4, 1, 5, 24, 2, 19, 19, 25, 7, 11, 5, 24, 1, 6, 17, - 42, 10, 12, 3, 7, 6, 76, 1, 16, 1, 3, 4, 15, 13, 19, 1, 8, 2, 2, 2, 22, 1, 7, 1, 1, 3, 4, 3, - 8, 2, 2, 2, 2, 1, 1, 8, 1, 4, 2, 1, 5, 12, 2, 10, 1, 4, 3, 1, 6, 4, 2, 2, 22, 1, 7, 1, 2, 1, - 2, 1, 2, 4, 5, 4, 2, 2, 2, 4, 1, 7, 4, 1, 1, 17, 6, 11, 3, 1, 9, 1, 3, 1, 22, 1, 7, 1, 2, 1, - 5, 3, 9, 1, 3, 1, 2, 3, 1, 15, 4, 21, 4, 4, 3, 1, 8, 2, 2, 2, 22, 1, 7, 1, 2, 1, 5, 3, 8, 2, - 2, 2, 2, 9, 2, 4, 2, 1, 5, 13, 1, 16, 2, 1, 6, 3, 3, 1, 4, 3, 2, 1, 1, 1, 2, 3, 2, 3, 3, 3, - 12, 4, 5, 3, 3, 1, 3, 3, 1, 6, 1, 40, 13, 1, 3, 1, 23, 1, 16, 3, 8, 1, 3, 1, 3, 8, 2, 1, 3, - 2, 1, 2, 4, 28, 4, 1, 8, 1, 3, 1, 23, 1, 10, 1, 5, 3, 8, 1, 3, 1, 3, 8, 2, 6, 2, 1, 4, 13, - 3, 12, 13, 1, 3, 1, 41, 2, 8, 1, 3, 1, 3, 1, 1, 5, 4, 7, 5, 22, 6, 1, 3, 1, 18, 3, 24, 1, 9, - 1, 1, 2, 7, 8, 6, 1, 1, 1, 8, 18, 2, 13, 58, 5, 7, 6, 1, 51, 2, 1, 1, 1, 5, 1, 24, 1, 1, 1, - 19, 1, 3, 2, 5, 1, 1, 6, 1, 14, 4, 32, 1, 63, 8, 1, 36, 4, 19, 4, 16, 1, 36, 67, 55, 1, 1, - 2, 5, 16, 64, 10, 4, 2, 38, 1, 1, 5, 1, 2, 43, 1, 0, 1, 4, 2, 7, 1, 1, 1, 4, 2, 41, 1, 4, 2, - 33, 1, 4, 2, 7, 1, 1, 1, 4, 2, 15, 1, 57, 1, 4, 2, 67, 37, 16, 16, 86, 2, 6, 3, 0, 2, 17, 1, - 26, 5, 75, 3, 11, 7, 20, 11, 21, 12, 20, 12, 13, 1, 3, 1, 2, 12, 52, 2, 19, 14, 1, 4, 1, 67, - 89, 7, 43, 5, 70, 10, 31, 1, 12, 4, 9, 23, 30, 2, 5, 11, 44, 4, 26, 54, 28, 4, 63, 2, 20, - 50, 1, 23, 2, 11, 3, 49, 52, 1, 15, 1, 8, 51, 42, 2, 4, 10, 44, 1, 11, 14, 55, 22, 3, 10, - 36, 2, 9, 7, 43, 2, 3, 41, 4, 1, 6, 1, 2, 3, 1, 5, 192, 39, 14, 11, 0, 2, 6, 2, 38, 2, 6, 2, - 8, 1, 1, 1, 1, 1, 1, 1, 31, 2, 53, 1, 7, 1, 1, 3, 3, 1, 7, 3, 4, 2, 6, 4, 13, 5, 3, 1, 7, - 116, 1, 13, 1, 16, 13, 101, 1, 4, 1, 2, 10, 1, 1, 3, 5, 6, 1, 1, 1, 1, 1, 1, 4, 1, 11, 2, 4, - 5, 5, 4, 1, 17, 41, 0, 52, 0, 229, 6, 4, 3, 2, 12, 38, 1, 1, 5, 1, 2, 56, 7, 1, 16, 23, 9, - 7, 1, 7, 1, 7, 1, 7, 1, 7, 1, 7, 1, 7, 1, 7, 1, 32, 47, 1, 0, 3, 25, 9, 7, 5, 2, 5, 4, 86, - 6, 3, 1, 90, 1, 4, 5, 43, 1, 94, 17, 32, 48, 16, 0, 0, 64, 0, 67, 46, 2, 0, 3, 16, 10, 2, - 20, 47, 5, 8, 3, 113, 39, 9, 2, 103, 2, 64, 5, 2, 1, 1, 1, 5, 24, 20, 1, 33, 24, 52, 12, 68, - 1, 1, 44, 6, 3, 1, 1, 3, 10, 33, 5, 35, 13, 29, 3, 51, 1, 12, 15, 1, 16, 16, 10, 5, 1, 55, - 9, 14, 18, 23, 3, 69, 1, 1, 1, 1, 24, 3, 2, 16, 2, 4, 11, 6, 2, 6, 2, 6, 9, 7, 1, 7, 1, 43, - 1, 14, 6, 123, 21, 0, 12, 23, 4, 49, 0, 0, 2, 106, 38, 7, 12, 5, 5, 12, 1, 13, 1, 5, 1, 1, - 1, 2, 1, 2, 1, 108, 33, 0, 18, 64, 2, 54, 40, 12, 116, 5, 1, 135, 36, 26, 6, 26, 11, 89, 3, - 6, 2, 6, 2, 6, 2, 3, 35, 12, 1, 26, 1, 19, 1, 2, 1, 15, 2, 14, 34, 123, 69, 53, 0, 29, 3, - 49, 47, 32, 13, 30, 5, 43, 5, 30, 2, 36, 4, 8, 1, 5, 42, 158, 18, 36, 4, 36, 4, 40, 8, 52, - 12, 11, 1, 15, 1, 7, 1, 2, 1, 11, 1, 15, 1, 7, 1, 2, 67, 0, 9, 22, 10, 8, 24, 6, 1, 42, 1, - 9, 69, 6, 2, 1, 1, 44, 1, 2, 3, 1, 2, 23, 10, 23, 9, 31, 65, 19, 1, 2, 10, 22, 10, 26, 70, - 56, 6, 2, 64, 4, 1, 2, 5, 8, 1, 3, 1, 29, 42, 29, 3, 29, 35, 8, 1, 28, 27, 54, 10, 22, 10, - 19, 13, 18, 110, 73, 55, 51, 13, 51, 13, 40, 0, 42, 1, 2, 3, 2, 78, 29, 10, 1, 8, 22, 42, - 18, 46, 21, 27, 23, 9, 70, 43, 5, 10, 57, 9, 1, 13, 25, 23, 51, 17, 4, 8, 35, 3, 1, 9, 64, - 1, 4, 9, 2, 10, 1, 1, 1, 35, 18, 1, 34, 2, 1, 6, 4, 62, 7, 1, 1, 1, 4, 1, 15, 1, 10, 7, 57, - 23, 4, 1, 8, 2, 2, 2, 22, 1, 7, 1, 2, 1, 5, 3, 8, 2, 2, 2, 2, 3, 1, 6, 1, 5, 7, 156, 66, 1, - 3, 1, 4, 20, 3, 30, 66, 2, 2, 1, 1, 184, 54, 2, 7, 25, 6, 34, 63, 1, 1, 3, 1, 59, 54, 2, 1, - 71, 27, 2, 14, 21, 7, 185, 57, 103, 64, 31, 8, 2, 1, 2, 8, 1, 2, 1, 30, 1, 2, 2, 2, 2, 4, - 93, 8, 2, 46, 2, 6, 1, 1, 1, 2, 27, 51, 2, 10, 17, 72, 5, 1, 18, 73, 0, 9, 1, 45, 1, 7, 1, - 1, 49, 30, 2, 22, 1, 14, 73, 7, 1, 2, 1, 44, 3, 1, 1, 2, 1, 3, 1, 1, 2, 2, 24, 6, 1, 2, 1, - 37, 1, 2, 1, 4, 1, 1, 0, 23, 9, 17, 1, 41, 3, 3, 111, 1, 79, 0, 102, 111, 17, 196, 0, 97, - 15, 0, 17, 6, 0, 0, 0, 0, 7, 31, 17, 79, 17, 30, 18, 48, 16, 4, 31, 21, 5, 19, 0, 64, 128, - 75, 4, 57, 7, 17, 64, 2, 1, 1, 12, 2, 14, 0, 8, 0, 42, 9, 0, 4, 1, 7, 1, 2, 1, 0, 15, 1, 29, - 3, 2, 1, 14, 4, 8, 0, 0, 107, 5, 13, 3, 9, 7, 10, 4, 1, 0, 85, 1, 71, 1, 2, 2, 1, 2, 2, 2, - 4, 1, 12, 1, 1, 1, 7, 1, 65, 1, 4, 2, 8, 1, 7, 1, 28, 1, 4, 1, 5, 1, 1, 3, 7, 1, 0, 2, 25, - 1, 25, 1, 31, 1, 25, 1, 31, 1, 25, 1, 31, 1, 25, 1, 31, 1, 25, 1, 8, 0, 31, 6, 6, 213, 7, 1, - 17, 2, 7, 1, 2, 1, 5, 5, 62, 33, 1, 112, 45, 10, 7, 16, 1, 0, 30, 18, 44, 0, 28, 0, 7, 1, 4, - 1, 2, 1, 15, 1, 197, 59, 68, 3, 1, 3, 1, 0, 4, 1, 27, 1, 2, 1, 1, 2, 1, 1, 10, 1, 4, 1, 1, - 1, 1, 6, 1, 4, 1, 1, 1, 1, 1, 1, 3, 1, 2, 1, 1, 2, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 1, 1, 2, - 4, 1, 7, 1, 4, 1, 4, 1, 1, 1, 10, 1, 17, 5, 3, 1, 5, 1, 17, 0, 26, 6, 26, 6, 26, 0, 0, 32, - 0, 6, 222, 2, 0, 14, 0, 15, 0, 0, 0, 0, 0, 5, 0, 0, - ]; - pub fn lookup(c: char) -> bool { - super::skip_search( - c as u32, - &SHORT_OFFSET_RUNS, - &OFFSETS, - ) - } -} - -#[rustfmt::skip] -pub mod case_ignorable { - static SHORT_OFFSET_RUNS: [u32; 35] = [ - 688, 44045149, 572528402, 576724925, 807414908, 878718981, 903913493, 929080568, 933275148, - 937491230, 1138818560, 1147208189, 1210124160, 1222707713, 1235291428, 1260457643, - 1264654383, 1499535675, 1507925040, 1566646003, 1629566000, 1650551536, 1658941263, - 1671540720, 1688321181, 1700908800, 1709298023, 1717688832, 1738661888, 1763828398, - 1797383403, 1805773008, 1809970171, 1819148289, 1824457200, - ]; - static OFFSETS: [u8; 875] = [ - 39, 1, 6, 1, 11, 1, 35, 1, 1, 1, 71, 1, 4, 1, 1, 1, 4, 1, 2, 2, 0, 192, 4, 2, 4, 1, 9, 2, - 1, 1, 251, 7, 207, 1, 5, 1, 49, 45, 1, 1, 1, 2, 1, 2, 1, 1, 44, 1, 11, 6, 10, 11, 1, 1, 35, - 1, 10, 21, 16, 1, 101, 8, 1, 10, 1, 4, 33, 1, 1, 1, 30, 27, 91, 11, 58, 11, 4, 1, 2, 1, 24, - 24, 43, 3, 44, 1, 7, 2, 6, 8, 41, 58, 55, 1, 1, 1, 4, 8, 4, 1, 3, 7, 10, 2, 13, 1, 15, 1, - 58, 1, 4, 4, 8, 1, 20, 2, 26, 1, 2, 2, 57, 1, 4, 2, 4, 2, 2, 3, 3, 1, 30, 2, 3, 1, 11, 2, - 57, 1, 4, 5, 1, 2, 4, 1, 20, 2, 22, 6, 1, 1, 58, 1, 2, 1, 1, 4, 8, 1, 7, 2, 11, 2, 30, 1, - 61, 1, 12, 1, 50, 1, 3, 1, 55, 1, 1, 3, 5, 3, 1, 4, 7, 2, 11, 2, 29, 1, 58, 1, 2, 1, 6, 1, - 5, 2, 20, 2, 28, 2, 57, 2, 4, 4, 8, 1, 20, 2, 29, 1, 72, 1, 7, 3, 1, 1, 90, 1, 2, 7, 11, 9, - 98, 1, 2, 9, 9, 1, 1, 7, 73, 2, 27, 1, 1, 1, 1, 1, 55, 14, 1, 5, 1, 2, 5, 11, 1, 36, 9, 1, - 102, 4, 1, 6, 1, 2, 2, 2, 25, 2, 4, 3, 16, 4, 13, 1, 2, 2, 6, 1, 15, 1, 94, 1, 0, 3, 0, 3, - 29, 2, 30, 2, 30, 2, 64, 2, 1, 7, 8, 1, 2, 11, 3, 1, 5, 1, 45, 5, 51, 1, 65, 2, 34, 1, 118, - 3, 4, 2, 9, 1, 6, 3, 219, 2, 2, 1, 58, 1, 1, 7, 1, 1, 1, 1, 2, 8, 6, 10, 2, 1, 39, 1, 8, 31, - 49, 4, 48, 1, 1, 5, 1, 1, 5, 1, 40, 9, 12, 2, 32, 4, 2, 2, 1, 3, 56, 1, 1, 2, 3, 1, 1, 3, - 58, 8, 2, 2, 64, 6, 82, 3, 1, 13, 1, 7, 4, 1, 6, 1, 3, 2, 50, 63, 13, 1, 34, 101, 0, 1, 1, - 3, 11, 3, 13, 3, 13, 3, 13, 2, 12, 5, 8, 2, 10, 1, 2, 1, 2, 5, 49, 5, 1, 10, 1, 1, 13, 1, - 16, 13, 51, 33, 0, 2, 113, 3, 125, 1, 15, 1, 96, 32, 47, 1, 0, 1, 36, 4, 3, 5, 5, 1, 93, 6, - 93, 3, 0, 1, 0, 6, 0, 1, 98, 4, 1, 10, 1, 1, 28, 4, 80, 2, 14, 34, 78, 1, 23, 3, 103, 3, 3, - 2, 8, 1, 3, 1, 4, 1, 25, 2, 5, 1, 151, 2, 26, 18, 13, 1, 38, 8, 25, 11, 46, 3, 48, 1, 2, 4, - 2, 2, 17, 1, 21, 2, 66, 6, 2, 2, 2, 2, 12, 1, 8, 1, 35, 1, 11, 1, 51, 1, 1, 3, 2, 2, 5, 2, - 1, 1, 27, 1, 14, 2, 5, 2, 1, 1, 100, 5, 9, 3, 121, 1, 2, 1, 4, 1, 0, 1, 147, 17, 0, 16, 3, - 1, 12, 16, 34, 1, 2, 1, 169, 1, 7, 1, 6, 1, 11, 1, 35, 1, 1, 1, 47, 1, 45, 2, 67, 1, 21, 3, - 0, 1, 226, 1, 149, 5, 0, 6, 1, 42, 1, 9, 0, 3, 1, 2, 5, 4, 40, 3, 4, 1, 165, 2, 0, 4, 0, 2, - 80, 3, 70, 11, 49, 4, 123, 1, 54, 15, 41, 1, 2, 2, 10, 3, 49, 4, 2, 2, 2, 1, 4, 1, 10, 1, - 50, 3, 36, 5, 1, 8, 62, 1, 12, 2, 52, 9, 10, 4, 2, 1, 95, 3, 2, 1, 1, 2, 6, 1, 2, 1, 157, 1, - 3, 8, 21, 2, 57, 2, 3, 1, 37, 7, 3, 5, 195, 8, 2, 3, 1, 1, 23, 1, 84, 6, 1, 1, 4, 2, 1, 2, - 238, 4, 6, 2, 1, 2, 27, 2, 85, 8, 2, 1, 1, 2, 106, 1, 1, 1, 2, 6, 1, 1, 101, 3, 2, 4, 1, 5, - 0, 9, 1, 2, 0, 2, 1, 1, 4, 1, 144, 4, 2, 2, 4, 1, 32, 10, 40, 6, 2, 4, 8, 1, 9, 6, 2, 3, 46, - 13, 1, 2, 0, 7, 1, 6, 1, 1, 82, 22, 2, 7, 1, 2, 1, 2, 122, 6, 3, 1, 1, 2, 1, 7, 1, 1, 72, 2, - 3, 1, 1, 1, 0, 2, 11, 2, 52, 5, 5, 1, 1, 1, 0, 17, 6, 15, 0, 5, 59, 7, 9, 4, 0, 1, 63, 17, - 64, 2, 1, 2, 0, 4, 1, 7, 1, 2, 0, 2, 1, 4, 0, 46, 2, 23, 0, 3, 9, 16, 2, 7, 30, 4, 148, 3, - 0, 55, 4, 50, 8, 1, 14, 1, 22, 5, 1, 15, 0, 7, 1, 17, 2, 7, 1, 2, 1, 5, 5, 62, 33, 1, 160, - 14, 0, 1, 61, 4, 0, 5, 0, 7, 109, 8, 0, 5, 0, 1, 30, 96, 128, 240, 0, - ]; - pub fn lookup(c: char) -> bool { - super::skip_search( - c as u32, - &SHORT_OFFSET_RUNS, - &OFFSETS, - ) - } -} - -#[rustfmt::skip] -pub mod cased { - static SHORT_OFFSET_RUNS: [u32; 22] = [ - 4256, 115348384, 136322176, 144711446, 163587254, 320875520, 325101120, 350268208, - 392231680, 404815649, 413205504, 421595008, 467733632, 484513952, 492924480, 497144832, - 501339814, 578936576, 627171376, 639756544, 643952944, 649261450, - ]; - static OFFSETS: [u8; 315] = [ - 65, 26, 6, 26, 47, 1, 10, 1, 4, 1, 5, 23, 1, 31, 1, 195, 1, 4, 4, 208, 1, 36, 7, 2, 30, 5, - 96, 1, 42, 4, 2, 2, 2, 4, 1, 1, 6, 1, 1, 3, 1, 1, 1, 20, 1, 83, 1, 139, 8, 166, 1, 38, 9, - 41, 0, 38, 1, 1, 5, 1, 2, 43, 1, 4, 0, 86, 2, 6, 0, 9, 7, 43, 2, 3, 64, 192, 64, 0, 2, 6, 2, - 38, 2, 6, 2, 8, 1, 1, 1, 1, 1, 1, 1, 31, 2, 53, 1, 7, 1, 1, 3, 3, 1, 7, 3, 4, 2, 6, 4, 13, - 5, 3, 1, 7, 116, 1, 13, 1, 16, 13, 101, 1, 4, 1, 2, 10, 1, 1, 3, 5, 6, 1, 1, 1, 1, 1, 1, 4, - 1, 6, 4, 1, 2, 4, 5, 5, 4, 1, 17, 32, 3, 2, 0, 52, 0, 229, 6, 4, 3, 2, 12, 38, 1, 1, 5, 1, - 0, 46, 18, 30, 132, 102, 3, 4, 1, 59, 5, 2, 1, 1, 1, 5, 24, 5, 1, 3, 0, 43, 1, 14, 6, 80, 0, - 7, 12, 5, 0, 26, 6, 26, 0, 80, 96, 36, 4, 36, 116, 11, 1, 15, 1, 7, 1, 2, 1, 11, 1, 15, 1, - 7, 1, 2, 0, 1, 2, 3, 1, 42, 1, 9, 0, 51, 13, 51, 0, 64, 0, 64, 0, 85, 1, 71, 1, 2, 2, 1, 2, - 2, 2, 4, 1, 12, 1, 1, 1, 7, 1, 65, 1, 4, 2, 8, 1, 7, 1, 28, 1, 4, 1, 5, 1, 1, 3, 7, 1, 0, 2, - 25, 1, 25, 1, 31, 1, 25, 1, 31, 1, 25, 1, 31, 1, 25, 1, 31, 1, 25, 1, 8, 0, 10, 1, 20, 6, 6, - 0, 62, 0, 68, 0, 26, 6, 26, 6, 26, 0, - ]; - pub fn lookup(c: char) -> bool { - super::skip_search( - c as u32, - &SHORT_OFFSET_RUNS, - &OFFSETS, - ) - } -} - -#[rustfmt::skip] -pub mod cc { - static SHORT_OFFSET_RUNS: [u32; 1] = [ - 1114272, - ]; - static OFFSETS: [u8; 5] = [ - 0, 32, 95, 33, 0, - ]; - pub fn lookup(c: char) -> bool { - super::skip_search( - c as u32, - &SHORT_OFFSET_RUNS, - &OFFSETS, - ) - } -} - -#[rustfmt::skip] -pub mod grapheme_extend { - static SHORT_OFFSET_RUNS: [u32; 33] = [ - 768, 2098307, 6292881, 10490717, 522196754, 526393356, 731917551, 740306986, 752920175, - 761309186, 778107678, 908131840, 912326558, 920715773, 924912129, 937495844, 962662059, - 966858799, 1214323760, 1285627635, 1348547648, 1369533168, 1377922895, 1386331293, - 1398918912, 1403113829, 1411504640, 1440866304, 1466032814, 1495393516, 1503783120, - 1508769824, 1518273008, - ]; - static OFFSETS: [u8; 727] = [ - 0, 112, 0, 7, 0, 45, 1, 1, 1, 2, 1, 2, 1, 1, 72, 11, 48, 21, 16, 1, 101, 7, 2, 6, 2, 2, 1, - 4, 35, 1, 30, 27, 91, 11, 58, 9, 9, 1, 24, 4, 1, 9, 1, 3, 1, 5, 43, 3, 60, 8, 42, 24, 1, 32, - 55, 1, 1, 1, 4, 8, 4, 1, 3, 7, 10, 2, 29, 1, 58, 1, 1, 1, 2, 4, 8, 1, 9, 1, 10, 2, 26, 1, 2, - 2, 57, 1, 4, 2, 4, 2, 2, 3, 3, 1, 30, 2, 3, 1, 11, 2, 57, 1, 4, 5, 1, 2, 4, 1, 20, 2, 22, 6, - 1, 1, 58, 1, 1, 2, 1, 4, 8, 1, 7, 3, 10, 2, 30, 1, 59, 1, 1, 1, 12, 1, 9, 1, 40, 1, 3, 1, - 55, 1, 1, 3, 5, 3, 1, 4, 7, 2, 11, 2, 29, 1, 58, 1, 2, 1, 2, 1, 3, 1, 5, 2, 7, 2, 11, 2, 28, - 2, 57, 2, 1, 1, 2, 4, 8, 1, 9, 1, 10, 2, 29, 1, 72, 1, 4, 1, 2, 3, 1, 1, 8, 1, 81, 1, 2, 7, - 12, 8, 98, 1, 2, 9, 11, 7, 73, 2, 27, 1, 1, 1, 1, 1, 55, 14, 1, 5, 1, 2, 5, 11, 1, 36, 9, 1, - 102, 4, 1, 6, 1, 2, 2, 2, 25, 2, 4, 3, 16, 4, 13, 1, 2, 2, 6, 1, 15, 1, 0, 3, 0, 3, 29, 2, - 30, 2, 30, 2, 64, 2, 1, 7, 8, 1, 2, 11, 9, 1, 45, 3, 1, 1, 117, 2, 34, 1, 118, 3, 4, 2, 9, - 1, 6, 3, 219, 2, 2, 1, 58, 1, 1, 7, 1, 1, 1, 1, 2, 8, 6, 10, 2, 1, 48, 31, 49, 4, 48, 7, 1, - 1, 5, 1, 40, 9, 12, 2, 32, 4, 2, 2, 1, 3, 56, 1, 1, 2, 3, 1, 1, 3, 58, 8, 2, 2, 152, 3, 1, - 13, 1, 7, 4, 1, 6, 1, 3, 2, 198, 64, 0, 1, 195, 33, 0, 3, 141, 1, 96, 32, 0, 6, 105, 2, 0, - 4, 1, 10, 32, 2, 80, 2, 0, 1, 3, 1, 4, 1, 25, 2, 5, 1, 151, 2, 26, 18, 13, 1, 38, 8, 25, 11, - 46, 3, 48, 1, 2, 4, 2, 2, 39, 1, 67, 6, 2, 2, 2, 2, 12, 1, 8, 1, 47, 1, 51, 1, 1, 3, 2, 2, - 5, 2, 1, 1, 42, 2, 8, 1, 238, 1, 2, 1, 4, 1, 0, 1, 0, 16, 16, 16, 0, 2, 0, 1, 226, 1, 149, - 5, 0, 3, 1, 2, 5, 4, 40, 3, 4, 1, 165, 2, 0, 4, 0, 2, 80, 3, 70, 11, 49, 4, 123, 1, 54, 15, - 41, 1, 2, 2, 10, 3, 49, 4, 2, 2, 7, 1, 61, 3, 36, 5, 1, 8, 62, 1, 12, 2, 52, 9, 10, 4, 2, 1, - 95, 3, 2, 1, 1, 2, 6, 1, 2, 1, 157, 1, 3, 8, 21, 2, 57, 2, 1, 1, 1, 1, 22, 1, 14, 7, 3, 5, - 195, 8, 2, 3, 1, 1, 23, 1, 81, 1, 2, 6, 1, 1, 2, 1, 1, 2, 1, 2, 235, 1, 2, 4, 6, 2, 1, 2, - 27, 2, 85, 8, 2, 1, 1, 2, 106, 1, 1, 1, 2, 6, 1, 1, 101, 3, 2, 4, 1, 5, 0, 9, 1, 2, 245, 1, - 10, 2, 1, 1, 4, 1, 144, 4, 2, 2, 4, 1, 32, 10, 40, 6, 2, 4, 8, 1, 9, 6, 2, 3, 46, 13, 1, 2, - 0, 7, 1, 6, 1, 1, 82, 22, 2, 7, 1, 2, 1, 2, 122, 6, 3, 1, 1, 2, 1, 7, 1, 1, 72, 2, 3, 1, 1, - 1, 0, 2, 11, 2, 52, 5, 5, 1, 1, 1, 0, 1, 6, 15, 0, 5, 59, 7, 0, 1, 63, 4, 81, 1, 0, 2, 0, - 46, 2, 23, 0, 1, 1, 3, 4, 5, 8, 8, 2, 7, 30, 4, 148, 3, 0, 55, 4, 50, 8, 1, 14, 1, 22, 5, 1, - 15, 0, 7, 1, 17, 2, 7, 1, 2, 1, 5, 100, 1, 160, 7, 0, 1, 61, 4, 0, 4, 0, 7, 109, 7, 0, 96, - 128, 240, 0, - ]; - #[inline] - pub fn lookup(c: char) -> bool { - (c as u32) >= 0x300 && lookup_slow(c) - } - fn lookup_slow(c: char) -> bool { - super::skip_search( - c as u32, - &SHORT_OFFSET_RUNS, - &OFFSETS, - ) - } -} - -#[rustfmt::skip] -pub mod lowercase { - const BITSET_CHUNKS_MAP: &'static [u8; 123] = &[ - 14, 17, 0, 0, 9, 0, 0, 12, 13, 10, 0, 16, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, - 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 6, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, - 0, 0, 0, 4, 1, 0, 15, 0, 8, 0, 0, 11, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, - 0, 0, 5, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 19, 0, - 3, 18, 0, 7, - ]; - const BITSET_INDEX_CHUNKS: &'static [[u8; 16]; 20] = &[ - [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 59, 0, 0], - [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 16, 14, 55, 0], - [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 40, 0, 0, 0], - [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 44, 0, 0, 0], - [0, 0, 0, 0, 0, 0, 0, 0, 0, 9, 0, 0, 0, 0, 0, 0], - [0, 0, 0, 0, 0, 0, 0, 0, 0, 65, 43, 0, 51, 47, 49, 33], - [0, 0, 0, 0, 10, 56, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - [0, 0, 0, 3, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - [0, 0, 0, 19, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 27], - [0, 0, 0, 60, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - [0, 0, 0, 69, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - [0, 0, 57, 0, 55, 55, 55, 0, 22, 22, 67, 22, 36, 25, 24, 37], - [0, 5, 68, 0, 29, 15, 73, 0, 0, 0, 0, 0, 0, 0, 0, 0], - [0, 64, 34, 17, 23, 52, 53, 48, 46, 8, 35, 42, 0, 28, 13, 31], - [11, 58, 0, 6, 0, 0, 30, 0, 0, 0, 0, 0, 0, 0, 32, 0], - [16, 26, 22, 38, 39, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - [16, 50, 2, 21, 66, 9, 57, 0, 0, 0, 0, 0, 0, 0, 0, 0], - [16, 70, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - [63, 41, 54, 12, 75, 61, 18, 1, 7, 62, 74, 20, 71, 72, 4, 45], - ]; - const BITSET_CANONICAL: &'static [u64; 55] = &[ - 0b0000000000000000000000000000000000000000000000000000000000000000, - 0b1111111111111111110000000000000000000000000011111111111111111111, - 0b1010101010101010101010101010101010101010101010101010100000000010, - 0b0000000000000111111111111111111111111111111111111111111111111111, - 0b1111111111111111111111000000000000000000000000001111110111111111, - 0b1000000000000010000000000000000000000000000000000000000000000000, - 0b0000111111111111111111111111111111111111000000000000000000000000, - 0b0000111111111111111111111111110000000000000000000000000011111111, - 0b1111111111111111111111111111111111111111111111111010101010000101, - 0b1111111111111111111111111111111100000000000000000000000000000000, - 0b1111111111111111111111111111110000000000000000000000000000000000, - 0b1111111111111111111111110000000000000000000000000000000000000000, - 0b1111111111111111111111000000000000000000000000001111111111101111, - 0b1111111111111111111100000000000000000000000000010000000000000000, - 0b1111111111111111000000111111111111110111111111111111111111111111, - 0b1111111111111111000000000000000000000000000000000100001111000000, - 0b1111111111111111000000000000000000000000000000000000000000000000, - 0b1111111101111111111111111111111110000000000000000000000000000000, - 0b1111110000000000000000000000000011111111111111111111111111000000, - 0b1111011111111111111111111111111111111111111111110000000000000000, - 0b1111000000000000000000000000001111110111111111111111111111111100, - 0b1010101010101010101010101010101010101010101010101101010101010100, - 0b1010101010101010101010101010101010101010101010101010101010101010, - 0b0101010110101010101010101010101010101010101010101010101010101010, - 0b0100000011011111000000001111111100000000111111110000000011111111, - 0b0011111111111111000000001111111100000000111111110000000000111111, - 0b0011111111011010000101010110001011111111111111111111111111111111, - 0b0011111100000000000000000000000000000000000000000000000000000000, - 0b0011110010001010000000000000000000000000000000000000000000100000, - 0b0011001000010000100000000000000000000000000010001100010000000000, - 0b0001101111111011111111111111101111111111100000000000000000000000, - 0b0001100100101111101010101010101010101010111000110111111111111111, - 0b0000011111111101111111111111111111111111111111111111111110111001, - 0b0000011101011100000000000000000000000010101010100000010100001010, - 0b0000010000100000000001000000000000000000000000000000000000000000, - 0b0000000111111111111111111111111111111111111011111111111111111111, - 0b0000000011111111000000001111111100000000001111110000000011111111, - 0b0000000011011100000000001111111100000000110011110000000011011100, - 0b0000000000001000010100000001101010101010101010101010101010101010, - 0b0000000000000000001000001011111111111111111111111111111111111111, - 0b0000000000000000000001111110000001111111111111111111101111111111, - 0b0000000000000000000000001111111111111111110111111100000000000000, - 0b0000000000000000000000000001111100000000000000000000000000000011, - 0b0000000000000000000000000000000000111010101010101010101010101010, - 0b0000000000000000000000000000000000000000111110000000000001111111, - 0b0000000000000000000000000000000000000000000000000000101111110111, - 0b1001001111111010101010101010101010101010101010101010101010101010, - 0b1001010111111111101010101010101010101010101010101010101010101010, - 0b1010101000101001101010101010101010110101010101010101001001000000, - 0b1010101010100000100000101010101010101010101110100101000010101010, - 0b1010101010101010101010101010101011111111111111111111111111111111, - 0b1010101010101011101010101010100000000000000000000000000000000000, - 0b1101010010101010101010101010101010101010101010101010101101010101, - 0b1110011001010001001011010010101001001110001001000011000100101001, - 0b1110101111000000000000000000000000001111111111111111111111111100, - ]; - const BITSET_MAPPING: &'static [(u8, u8); 21] = &[ - (0, 64), (1, 188), (1, 183), (1, 176), (1, 109), (1, 124), (1, 126), (1, 66), (1, 70), - (1, 77), (2, 146), (2, 144), (2, 83), (3, 93), (3, 147), (3, 133), (4, 12), (4, 6), - (5, 187), (6, 78), (7, 132), - ]; - - #[rustc_const_unstable(feature = "const_unicode_case_lookup", issue = "101400")] - pub const fn lookup(c: char) -> bool { - super::bitset_search( - c as u32, - &BITSET_CHUNKS_MAP, - &BITSET_INDEX_CHUNKS, - &BITSET_CANONICAL, - &BITSET_MAPPING, - ) - } -} - -#[rustfmt::skip] -pub mod n { - static SHORT_OFFSET_RUNS: [u32; 39] = [ - 1632, 18876774, 31461440, 102765417, 111154926, 115349830, 132128880, 165684320, 186656630, - 195046653, 199241735, 203436434, 216049184, 241215536, 249605104, 274792208, 278987015, - 283181793, 295766104, 320933114, 383848032, 392238160, 434181712, 442570976, 455154768, - 463544144, 476128256, 484534880, 488730240, 505533120, 509728718, 522314048, 526508784, - 530703600, 534898887, 539094129, 547483904, 568458224, 573766650, - ]; - static OFFSETS: [u8; 275] = [ - 48, 10, 120, 2, 5, 1, 2, 3, 0, 10, 134, 10, 198, 10, 0, 10, 118, 10, 4, 6, 108, 10, 118, - 10, 118, 10, 2, 6, 110, 13, 115, 10, 8, 7, 103, 10, 104, 7, 7, 19, 109, 10, 96, 10, 118, 10, - 70, 20, 0, 10, 70, 10, 0, 20, 0, 3, 239, 10, 6, 10, 22, 10, 0, 10, 128, 11, 165, 10, 6, 10, - 182, 10, 86, 10, 134, 10, 6, 10, 0, 1, 3, 6, 6, 10, 198, 51, 2, 5, 0, 60, 78, 22, 0, 30, 0, - 1, 0, 1, 25, 9, 14, 3, 0, 4, 138, 10, 30, 8, 1, 15, 32, 10, 39, 15, 0, 10, 188, 10, 0, 6, - 154, 10, 38, 10, 198, 10, 22, 10, 86, 10, 0, 10, 0, 10, 0, 45, 12, 57, 17, 2, 0, 27, 36, 4, - 29, 1, 8, 1, 134, 5, 202, 10, 0, 8, 25, 7, 39, 9, 75, 5, 22, 6, 160, 2, 2, 16, 2, 46, 64, 9, - 52, 2, 30, 3, 75, 5, 104, 8, 24, 8, 41, 7, 0, 6, 48, 10, 0, 31, 158, 10, 42, 4, 112, 7, 134, - 30, 128, 10, 60, 10, 144, 10, 7, 20, 251, 10, 0, 10, 118, 10, 0, 10, 102, 10, 102, 12, 0, - 19, 93, 10, 0, 29, 227, 10, 70, 10, 0, 10, 102, 21, 0, 111, 0, 10, 86, 10, 134, 10, 1, 7, 0, - 23, 0, 20, 12, 20, 108, 25, 0, 50, 0, 10, 0, 10, 0, 10, 0, 9, 128, 10, 0, 59, 1, 3, 1, 4, - 76, 45, 1, 15, 0, 13, 0, 10, 0, - ]; - pub fn lookup(c: char) -> bool { - super::skip_search( - c as u32, - &SHORT_OFFSET_RUNS, - &OFFSETS, - ) - } -} - -#[rustfmt::skip] -pub mod uppercase { - const BITSET_CHUNKS_MAP: &'static [u8; 125] = &[ - 12, 15, 6, 6, 0, 6, 6, 2, 4, 11, 6, 16, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, - 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 8, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, - 6, 6, 6, 5, 6, 14, 6, 10, 6, 6, 1, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, - 6, 7, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 6, 13, 6, 6, - 6, 6, 9, 6, 3, - ]; - const BITSET_INDEX_CHUNKS: &'static [[u8; 16]; 17] = &[ - [43, 43, 5, 34, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43, 5, 1], - [43, 43, 5, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43], - [43, 43, 39, 43, 43, 43, 43, 43, 17, 17, 62, 17, 42, 29, 24, 23], - [43, 43, 43, 43, 9, 8, 44, 43, 43, 43, 43, 43, 43, 43, 43, 43], - [43, 43, 43, 43, 36, 28, 66, 43, 43, 43, 43, 43, 43, 43, 43, 43], - [43, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43, 0, 43, 43, 43], - [43, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43], - [43, 43, 43, 43, 43, 43, 43, 43, 43, 54, 43, 43, 43, 43, 43, 43], - [43, 43, 43, 43, 43, 43, 43, 43, 43, 61, 60, 43, 20, 14, 16, 4], - [43, 43, 43, 43, 55, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43], - [43, 43, 58, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43], - [43, 43, 59, 45, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43], - [43, 48, 43, 31, 35, 21, 22, 15, 13, 33, 43, 43, 43, 11, 30, 38], - [51, 53, 26, 49, 12, 7, 25, 50, 40, 52, 6, 3, 65, 64, 63, 67], - [56, 43, 9, 46, 43, 41, 32, 43, 43, 43, 43, 43, 43, 43, 43, 43], - [57, 19, 2, 18, 10, 47, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43], - [57, 37, 17, 27, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43, 43], - ]; - const BITSET_CANONICAL: &'static [u64; 43] = &[ - 0b0000011111111111111111111111111000000000000000000000000000000000, - 0b0000000000111111111111111111111111111111111111111111111111111111, - 0b0101010101010101010101010101010101010101010101010101010000000001, - 0b0000011111111111111111111111110000000000000000000000000000000001, - 0b0000000000100000000000000000000000000001010000010000001011110101, - 0b1111111111111111111111111111111100000000000000000000000000000000, - 0b1111111111111111111111110000000000000000000000000000001111111111, - 0b1111111111111111111100000000000000000000000000011111110001011111, - 0b1111111111111111000000111111111111111111111111110000001111111111, - 0b1111111111111111000000000000000000000000000000000000000000000000, - 0b1111111111111110010101010101010101010101010101010101010101010101, - 0b1000000001000101000000000000000000000000000000000000000000000000, - 0b0111101100000000000000000000000000011111110111111110011110110000, - 0b0110110000000101010101010101010101010101010101010101010101010101, - 0b0110101000000000010101010101010101010101010101010101010101010101, - 0b0101010111010010010101010101010101001010101010101010010010010000, - 0b0101010101011111011111010101010101010101010001010010100001010101, - 0b0101010101010101010101010101010101010101010101010101010101010101, - 0b0101010101010101010101010101010101010101010101010010101010101011, - 0b0101010101010101010101010101010100000000000000000000000000000000, - 0b0101010101010100010101010101010000000000000000000000000000000000, - 0b0010101101010101010101010101010101010101010101010101010010101010, - 0b0001000110101110110100101101010110110001110110111100111011010110, - 0b0000111100000000000111110000000000001111000000000000111100000000, - 0b0000111100000000000000000000000000000000000000000000000000000000, - 0b0000001111111111111111111111111100000000000000000000000000111111, - 0b0000000000111111110111100110010011010000000000000000000000000011, - 0b0000000000000100001010000000010101010101010101010101010101010101, - 0b0000000000000000111111111111111100000000000000000000000000100000, - 0b0000000000000000111111110000000010101010000000000011111100000000, - 0b0000000000000000000011111111101111111111111111101101011101000000, - 0b0000000000000000000000000000000001111111011111111111111111111111, - 0b0000000000000000000000000000000000000000001101111111011111111111, - 0b0000000000000000000000000000000000000000000000000101010101111010, - 0b0000000000000000000000000000000000000000000000000010000010111111, - 0b1010101001010101010101010101010101010101010101010101010101010101, - 0b1100000000001111001111010101000000111110001001110011100010000100, - 0b1100000000100101111010101001110100000000000000000000000000000000, - 0b1110011010010000010101010101010101010101000111001000000000000000, - 0b1110011111111111111111111111111111111111111111110000000000000000, - 0b1111000000000000000000000000001111111111111111111111111100000000, - 0b1111011111111111000000000000000000000000000000000000000000000000, - 0b1111111100000000111111110000000000111111000000001111111100000000, - ]; - const BITSET_MAPPING: &'static [(u8, u8); 25] = &[ - (0, 187), (0, 177), (0, 171), (0, 167), (0, 164), (0, 32), (0, 47), (0, 51), (0, 121), - (0, 117), (0, 109), (1, 150), (1, 148), (1, 142), (1, 134), (1, 131), (1, 64), (2, 164), - (2, 146), (2, 20), (3, 146), (3, 140), (3, 134), (4, 178), (4, 171), - ]; - - #[rustc_const_unstable(feature = "const_unicode_case_lookup", issue = "101400")] - pub const fn lookup(c: char) -> bool { - super::bitset_search( - c as u32, - &BITSET_CHUNKS_MAP, - &BITSET_INDEX_CHUNKS, - &BITSET_CANONICAL, - &BITSET_MAPPING, - ) - } -} - -#[rustfmt::skip] -pub mod white_space { - static WHITESPACE_MAP: [u8; 256] = [ - 2, 2, 2, 2, 2, 2, 2, 2, 2, 3, 3, 1, 1, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, - 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 2, 2, 0, 0, 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, - 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, - 0, 0, 0, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, - 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, - 0, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, - 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, - 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, - 0, 0, 0, 0, 0, 0, 0, 0, 0, - ]; - #[inline] - pub fn lookup(c: char) -> bool { - match c as u32 >> 8 { - 0 => WHITESPACE_MAP[c as usize & 0xff] & 1 != 0, - 22 => c as u32 == 0x1680, - 32 => WHITESPACE_MAP[c as usize & 0xff] & 2 != 0, - 48 => c as u32 == 0x3000, - _ => false, - } - } -} - -#[rustfmt::skip] -pub mod conversions { - const INDEX_MASK: u32 = 0x400000; - - pub fn to_lower(c: char) -> [char; 3] { - if c.is_ascii() { - [(c as u8).to_ascii_lowercase() as char, '\0', '\0'] - } else { - LOWERCASE_TABLE - .binary_search_by(|&(key, _)| key.cmp(&c)) - .map(|i| { - let u = LOWERCASE_TABLE[i].1; - char::from_u32(u).map(|c| [c, '\0', '\0']).unwrap_or_else(|| { - // SAFETY: Index comes from statically generated table - unsafe { *LOWERCASE_TABLE_MULTI.get_unchecked((u & (INDEX_MASK - 1)) as usize) } - }) - }) - .unwrap_or([c, '\0', '\0']) - } - } - - pub fn to_upper(c: char) -> [char; 3] { - if c.is_ascii() { - [(c as u8).to_ascii_uppercase() as char, '\0', '\0'] - } else { - UPPERCASE_TABLE - .binary_search_by(|&(key, _)| key.cmp(&c)) - .map(|i| { - let u = UPPERCASE_TABLE[i].1; - char::from_u32(u).map(|c| [c, '\0', '\0']).unwrap_or_else(|| { - // SAFETY: Index comes from statically generated table - unsafe { *UPPERCASE_TABLE_MULTI.get_unchecked((u & (INDEX_MASK - 1)) as usize) } - }) - }) - .unwrap_or([c, '\0', '\0']) - } - } - - static LOWERCASE_TABLE: &[(char, u32)] = &[ - ('\u{c0}', 224), ('\u{c1}', 225), ('\u{c2}', 226), ('\u{c3}', 227), ('\u{c4}', 228), - ('\u{c5}', 229), ('\u{c6}', 230), ('\u{c7}', 231), ('\u{c8}', 232), ('\u{c9}', 233), - ('\u{ca}', 234), ('\u{cb}', 235), ('\u{cc}', 236), ('\u{cd}', 237), ('\u{ce}', 238), - ('\u{cf}', 239), ('\u{d0}', 240), ('\u{d1}', 241), ('\u{d2}', 242), ('\u{d3}', 243), - ('\u{d4}', 244), ('\u{d5}', 245), ('\u{d6}', 246), ('\u{d8}', 248), ('\u{d9}', 249), - ('\u{da}', 250), ('\u{db}', 251), ('\u{dc}', 252), ('\u{dd}', 253), ('\u{de}', 254), - ('\u{100}', 257), ('\u{102}', 259), ('\u{104}', 261), ('\u{106}', 263), ('\u{108}', 265), - ('\u{10a}', 267), ('\u{10c}', 269), ('\u{10e}', 271), ('\u{110}', 273), ('\u{112}', 275), - ('\u{114}', 277), ('\u{116}', 279), ('\u{118}', 281), ('\u{11a}', 283), ('\u{11c}', 285), - ('\u{11e}', 287), ('\u{120}', 289), ('\u{122}', 291), ('\u{124}', 293), ('\u{126}', 295), - ('\u{128}', 297), ('\u{12a}', 299), ('\u{12c}', 301), ('\u{12e}', 303), - ('\u{130}', 4194304), ('\u{132}', 307), ('\u{134}', 309), ('\u{136}', 311), - ('\u{139}', 314), ('\u{13b}', 316), ('\u{13d}', 318), ('\u{13f}', 320), ('\u{141}', 322), - ('\u{143}', 324), ('\u{145}', 326), ('\u{147}', 328), ('\u{14a}', 331), ('\u{14c}', 333), - ('\u{14e}', 335), ('\u{150}', 337), ('\u{152}', 339), ('\u{154}', 341), ('\u{156}', 343), - ('\u{158}', 345), ('\u{15a}', 347), ('\u{15c}', 349), ('\u{15e}', 351), ('\u{160}', 353), - ('\u{162}', 355), ('\u{164}', 357), ('\u{166}', 359), ('\u{168}', 361), ('\u{16a}', 363), - ('\u{16c}', 365), ('\u{16e}', 367), ('\u{170}', 369), ('\u{172}', 371), ('\u{174}', 373), - ('\u{176}', 375), ('\u{178}', 255), ('\u{179}', 378), ('\u{17b}', 380), ('\u{17d}', 382), - ('\u{181}', 595), ('\u{182}', 387), ('\u{184}', 389), ('\u{186}', 596), ('\u{187}', 392), - ('\u{189}', 598), ('\u{18a}', 599), ('\u{18b}', 396), ('\u{18e}', 477), ('\u{18f}', 601), - ('\u{190}', 603), ('\u{191}', 402), ('\u{193}', 608), ('\u{194}', 611), ('\u{196}', 617), - ('\u{197}', 616), ('\u{198}', 409), ('\u{19c}', 623), ('\u{19d}', 626), ('\u{19f}', 629), - ('\u{1a0}', 417), ('\u{1a2}', 419), ('\u{1a4}', 421), ('\u{1a6}', 640), ('\u{1a7}', 424), - ('\u{1a9}', 643), ('\u{1ac}', 429), ('\u{1ae}', 648), ('\u{1af}', 432), ('\u{1b1}', 650), - ('\u{1b2}', 651), ('\u{1b3}', 436), ('\u{1b5}', 438), ('\u{1b7}', 658), ('\u{1b8}', 441), - ('\u{1bc}', 445), ('\u{1c4}', 454), ('\u{1c5}', 454), ('\u{1c7}', 457), ('\u{1c8}', 457), - ('\u{1ca}', 460), ('\u{1cb}', 460), ('\u{1cd}', 462), ('\u{1cf}', 464), ('\u{1d1}', 466), - ('\u{1d3}', 468), ('\u{1d5}', 470), ('\u{1d7}', 472), ('\u{1d9}', 474), ('\u{1db}', 476), - ('\u{1de}', 479), ('\u{1e0}', 481), ('\u{1e2}', 483), ('\u{1e4}', 485), ('\u{1e6}', 487), - ('\u{1e8}', 489), ('\u{1ea}', 491), ('\u{1ec}', 493), ('\u{1ee}', 495), ('\u{1f1}', 499), - ('\u{1f2}', 499), ('\u{1f4}', 501), ('\u{1f6}', 405), ('\u{1f7}', 447), ('\u{1f8}', 505), - ('\u{1fa}', 507), ('\u{1fc}', 509), ('\u{1fe}', 511), ('\u{200}', 513), ('\u{202}', 515), - ('\u{204}', 517), ('\u{206}', 519), ('\u{208}', 521), ('\u{20a}', 523), ('\u{20c}', 525), - ('\u{20e}', 527), ('\u{210}', 529), ('\u{212}', 531), ('\u{214}', 533), ('\u{216}', 535), - ('\u{218}', 537), ('\u{21a}', 539), ('\u{21c}', 541), ('\u{21e}', 543), ('\u{220}', 414), - ('\u{222}', 547), ('\u{224}', 549), ('\u{226}', 551), ('\u{228}', 553), ('\u{22a}', 555), - ('\u{22c}', 557), ('\u{22e}', 559), ('\u{230}', 561), ('\u{232}', 563), ('\u{23a}', 11365), - ('\u{23b}', 572), ('\u{23d}', 410), ('\u{23e}', 11366), ('\u{241}', 578), ('\u{243}', 384), - ('\u{244}', 649), ('\u{245}', 652), ('\u{246}', 583), ('\u{248}', 585), ('\u{24a}', 587), - ('\u{24c}', 589), ('\u{24e}', 591), ('\u{370}', 881), ('\u{372}', 883), ('\u{376}', 887), - ('\u{37f}', 1011), ('\u{386}', 940), ('\u{388}', 941), ('\u{389}', 942), ('\u{38a}', 943), - ('\u{38c}', 972), ('\u{38e}', 973), ('\u{38f}', 974), ('\u{391}', 945), ('\u{392}', 946), - ('\u{393}', 947), ('\u{394}', 948), ('\u{395}', 949), ('\u{396}', 950), ('\u{397}', 951), - ('\u{398}', 952), ('\u{399}', 953), ('\u{39a}', 954), ('\u{39b}', 955), ('\u{39c}', 956), - ('\u{39d}', 957), ('\u{39e}', 958), ('\u{39f}', 959), ('\u{3a0}', 960), ('\u{3a1}', 961), - ('\u{3a3}', 963), ('\u{3a4}', 964), ('\u{3a5}', 965), ('\u{3a6}', 966), ('\u{3a7}', 967), - ('\u{3a8}', 968), ('\u{3a9}', 969), ('\u{3aa}', 970), ('\u{3ab}', 971), ('\u{3cf}', 983), - ('\u{3d8}', 985), ('\u{3da}', 987), ('\u{3dc}', 989), ('\u{3de}', 991), ('\u{3e0}', 993), - ('\u{3e2}', 995), ('\u{3e4}', 997), ('\u{3e6}', 999), ('\u{3e8}', 1001), ('\u{3ea}', 1003), - ('\u{3ec}', 1005), ('\u{3ee}', 1007), ('\u{3f4}', 952), ('\u{3f7}', 1016), - ('\u{3f9}', 1010), ('\u{3fa}', 1019), ('\u{3fd}', 891), ('\u{3fe}', 892), ('\u{3ff}', 893), - ('\u{400}', 1104), ('\u{401}', 1105), ('\u{402}', 1106), ('\u{403}', 1107), - ('\u{404}', 1108), ('\u{405}', 1109), ('\u{406}', 1110), ('\u{407}', 1111), - ('\u{408}', 1112), ('\u{409}', 1113), ('\u{40a}', 1114), ('\u{40b}', 1115), - ('\u{40c}', 1116), ('\u{40d}', 1117), ('\u{40e}', 1118), ('\u{40f}', 1119), - ('\u{410}', 1072), ('\u{411}', 1073), ('\u{412}', 1074), ('\u{413}', 1075), - ('\u{414}', 1076), ('\u{415}', 1077), ('\u{416}', 1078), ('\u{417}', 1079), - ('\u{418}', 1080), ('\u{419}', 1081), ('\u{41a}', 1082), ('\u{41b}', 1083), - ('\u{41c}', 1084), ('\u{41d}', 1085), ('\u{41e}', 1086), ('\u{41f}', 1087), - ('\u{420}', 1088), ('\u{421}', 1089), ('\u{422}', 1090), ('\u{423}', 1091), - ('\u{424}', 1092), ('\u{425}', 1093), ('\u{426}', 1094), ('\u{427}', 1095), - ('\u{428}', 1096), ('\u{429}', 1097), ('\u{42a}', 1098), ('\u{42b}', 1099), - ('\u{42c}', 1100), ('\u{42d}', 1101), ('\u{42e}', 1102), ('\u{42f}', 1103), - ('\u{460}', 1121), ('\u{462}', 1123), ('\u{464}', 1125), ('\u{466}', 1127), - ('\u{468}', 1129), ('\u{46a}', 1131), ('\u{46c}', 1133), ('\u{46e}', 1135), - ('\u{470}', 1137), ('\u{472}', 1139), ('\u{474}', 1141), ('\u{476}', 1143), - ('\u{478}', 1145), ('\u{47a}', 1147), ('\u{47c}', 1149), ('\u{47e}', 1151), - ('\u{480}', 1153), ('\u{48a}', 1163), ('\u{48c}', 1165), ('\u{48e}', 1167), - ('\u{490}', 1169), ('\u{492}', 1171), ('\u{494}', 1173), ('\u{496}', 1175), - ('\u{498}', 1177), ('\u{49a}', 1179), ('\u{49c}', 1181), ('\u{49e}', 1183), - ('\u{4a0}', 1185), ('\u{4a2}', 1187), ('\u{4a4}', 1189), ('\u{4a6}', 1191), - ('\u{4a8}', 1193), ('\u{4aa}', 1195), ('\u{4ac}', 1197), ('\u{4ae}', 1199), - ('\u{4b0}', 1201), ('\u{4b2}', 1203), ('\u{4b4}', 1205), ('\u{4b6}', 1207), - ('\u{4b8}', 1209), ('\u{4ba}', 1211), ('\u{4bc}', 1213), ('\u{4be}', 1215), - ('\u{4c0}', 1231), ('\u{4c1}', 1218), ('\u{4c3}', 1220), ('\u{4c5}', 1222), - ('\u{4c7}', 1224), ('\u{4c9}', 1226), ('\u{4cb}', 1228), ('\u{4cd}', 1230), - ('\u{4d0}', 1233), ('\u{4d2}', 1235), ('\u{4d4}', 1237), ('\u{4d6}', 1239), - ('\u{4d8}', 1241), ('\u{4da}', 1243), ('\u{4dc}', 1245), ('\u{4de}', 1247), - ('\u{4e0}', 1249), ('\u{4e2}', 1251), ('\u{4e4}', 1253), ('\u{4e6}', 1255), - ('\u{4e8}', 1257), ('\u{4ea}', 1259), ('\u{4ec}', 1261), ('\u{4ee}', 1263), - ('\u{4f0}', 1265), ('\u{4f2}', 1267), ('\u{4f4}', 1269), ('\u{4f6}', 1271), - ('\u{4f8}', 1273), ('\u{4fa}', 1275), ('\u{4fc}', 1277), ('\u{4fe}', 1279), - ('\u{500}', 1281), ('\u{502}', 1283), ('\u{504}', 1285), ('\u{506}', 1287), - ('\u{508}', 1289), ('\u{50a}', 1291), ('\u{50c}', 1293), ('\u{50e}', 1295), - ('\u{510}', 1297), ('\u{512}', 1299), ('\u{514}', 1301), ('\u{516}', 1303), - ('\u{518}', 1305), ('\u{51a}', 1307), ('\u{51c}', 1309), ('\u{51e}', 1311), - ('\u{520}', 1313), ('\u{522}', 1315), ('\u{524}', 1317), ('\u{526}', 1319), - ('\u{528}', 1321), ('\u{52a}', 1323), ('\u{52c}', 1325), ('\u{52e}', 1327), - ('\u{531}', 1377), ('\u{532}', 1378), ('\u{533}', 1379), ('\u{534}', 1380), - ('\u{535}', 1381), ('\u{536}', 1382), ('\u{537}', 1383), ('\u{538}', 1384), - ('\u{539}', 1385), ('\u{53a}', 1386), ('\u{53b}', 1387), ('\u{53c}', 1388), - ('\u{53d}', 1389), ('\u{53e}', 1390), ('\u{53f}', 1391), ('\u{540}', 1392), - ('\u{541}', 1393), ('\u{542}', 1394), ('\u{543}', 1395), ('\u{544}', 1396), - ('\u{545}', 1397), ('\u{546}', 1398), ('\u{547}', 1399), ('\u{548}', 1400), - ('\u{549}', 1401), ('\u{54a}', 1402), ('\u{54b}', 1403), ('\u{54c}', 1404), - ('\u{54d}', 1405), ('\u{54e}', 1406), ('\u{54f}', 1407), ('\u{550}', 1408), - ('\u{551}', 1409), ('\u{552}', 1410), ('\u{553}', 1411), ('\u{554}', 1412), - ('\u{555}', 1413), ('\u{556}', 1414), ('\u{10a0}', 11520), ('\u{10a1}', 11521), - ('\u{10a2}', 11522), ('\u{10a3}', 11523), ('\u{10a4}', 11524), ('\u{10a5}', 11525), - ('\u{10a6}', 11526), ('\u{10a7}', 11527), ('\u{10a8}', 11528), ('\u{10a9}', 11529), - ('\u{10aa}', 11530), ('\u{10ab}', 11531), ('\u{10ac}', 11532), ('\u{10ad}', 11533), - ('\u{10ae}', 11534), ('\u{10af}', 11535), ('\u{10b0}', 11536), ('\u{10b1}', 11537), - ('\u{10b2}', 11538), ('\u{10b3}', 11539), ('\u{10b4}', 11540), ('\u{10b5}', 11541), - ('\u{10b6}', 11542), ('\u{10b7}', 11543), ('\u{10b8}', 11544), ('\u{10b9}', 11545), - ('\u{10ba}', 11546), ('\u{10bb}', 11547), ('\u{10bc}', 11548), ('\u{10bd}', 11549), - ('\u{10be}', 11550), ('\u{10bf}', 11551), ('\u{10c0}', 11552), ('\u{10c1}', 11553), - ('\u{10c2}', 11554), ('\u{10c3}', 11555), ('\u{10c4}', 11556), ('\u{10c5}', 11557), - ('\u{10c7}', 11559), ('\u{10cd}', 11565), ('\u{13a0}', 43888), ('\u{13a1}', 43889), - ('\u{13a2}', 43890), ('\u{13a3}', 43891), ('\u{13a4}', 43892), ('\u{13a5}', 43893), - ('\u{13a6}', 43894), ('\u{13a7}', 43895), ('\u{13a8}', 43896), ('\u{13a9}', 43897), - ('\u{13aa}', 43898), ('\u{13ab}', 43899), ('\u{13ac}', 43900), ('\u{13ad}', 43901), - ('\u{13ae}', 43902), ('\u{13af}', 43903), ('\u{13b0}', 43904), ('\u{13b1}', 43905), - ('\u{13b2}', 43906), ('\u{13b3}', 43907), ('\u{13b4}', 43908), ('\u{13b5}', 43909), - ('\u{13b6}', 43910), ('\u{13b7}', 43911), ('\u{13b8}', 43912), ('\u{13b9}', 43913), - ('\u{13ba}', 43914), ('\u{13bb}', 43915), ('\u{13bc}', 43916), ('\u{13bd}', 43917), - ('\u{13be}', 43918), ('\u{13bf}', 43919), ('\u{13c0}', 43920), ('\u{13c1}', 43921), - ('\u{13c2}', 43922), ('\u{13c3}', 43923), ('\u{13c4}', 43924), ('\u{13c5}', 43925), - ('\u{13c6}', 43926), ('\u{13c7}', 43927), ('\u{13c8}', 43928), ('\u{13c9}', 43929), - ('\u{13ca}', 43930), ('\u{13cb}', 43931), ('\u{13cc}', 43932), ('\u{13cd}', 43933), - ('\u{13ce}', 43934), ('\u{13cf}', 43935), ('\u{13d0}', 43936), ('\u{13d1}', 43937), - ('\u{13d2}', 43938), ('\u{13d3}', 43939), ('\u{13d4}', 43940), ('\u{13d5}', 43941), - ('\u{13d6}', 43942), ('\u{13d7}', 43943), ('\u{13d8}', 43944), ('\u{13d9}', 43945), - ('\u{13da}', 43946), ('\u{13db}', 43947), ('\u{13dc}', 43948), ('\u{13dd}', 43949), - ('\u{13de}', 43950), ('\u{13df}', 43951), ('\u{13e0}', 43952), ('\u{13e1}', 43953), - ('\u{13e2}', 43954), ('\u{13e3}', 43955), ('\u{13e4}', 43956), ('\u{13e5}', 43957), - ('\u{13e6}', 43958), ('\u{13e7}', 43959), ('\u{13e8}', 43960), ('\u{13e9}', 43961), - ('\u{13ea}', 43962), ('\u{13eb}', 43963), ('\u{13ec}', 43964), ('\u{13ed}', 43965), - ('\u{13ee}', 43966), ('\u{13ef}', 43967), ('\u{13f0}', 5112), ('\u{13f1}', 5113), - ('\u{13f2}', 5114), ('\u{13f3}', 5115), ('\u{13f4}', 5116), ('\u{13f5}', 5117), - ('\u{1c90}', 4304), ('\u{1c91}', 4305), ('\u{1c92}', 4306), ('\u{1c93}', 4307), - ('\u{1c94}', 4308), ('\u{1c95}', 4309), ('\u{1c96}', 4310), ('\u{1c97}', 4311), - ('\u{1c98}', 4312), ('\u{1c99}', 4313), ('\u{1c9a}', 4314), ('\u{1c9b}', 4315), - ('\u{1c9c}', 4316), ('\u{1c9d}', 4317), ('\u{1c9e}', 4318), ('\u{1c9f}', 4319), - ('\u{1ca0}', 4320), ('\u{1ca1}', 4321), ('\u{1ca2}', 4322), ('\u{1ca3}', 4323), - ('\u{1ca4}', 4324), ('\u{1ca5}', 4325), ('\u{1ca6}', 4326), ('\u{1ca7}', 4327), - ('\u{1ca8}', 4328), ('\u{1ca9}', 4329), ('\u{1caa}', 4330), ('\u{1cab}', 4331), - ('\u{1cac}', 4332), ('\u{1cad}', 4333), ('\u{1cae}', 4334), ('\u{1caf}', 4335), - ('\u{1cb0}', 4336), ('\u{1cb1}', 4337), ('\u{1cb2}', 4338), ('\u{1cb3}', 4339), - ('\u{1cb4}', 4340), ('\u{1cb5}', 4341), ('\u{1cb6}', 4342), ('\u{1cb7}', 4343), - ('\u{1cb8}', 4344), ('\u{1cb9}', 4345), ('\u{1cba}', 4346), ('\u{1cbd}', 4349), - ('\u{1cbe}', 4350), ('\u{1cbf}', 4351), ('\u{1e00}', 7681), ('\u{1e02}', 7683), - ('\u{1e04}', 7685), ('\u{1e06}', 7687), ('\u{1e08}', 7689), ('\u{1e0a}', 7691), - ('\u{1e0c}', 7693), ('\u{1e0e}', 7695), ('\u{1e10}', 7697), ('\u{1e12}', 7699), - ('\u{1e14}', 7701), ('\u{1e16}', 7703), ('\u{1e18}', 7705), ('\u{1e1a}', 7707), - ('\u{1e1c}', 7709), ('\u{1e1e}', 7711), ('\u{1e20}', 7713), ('\u{1e22}', 7715), - ('\u{1e24}', 7717), ('\u{1e26}', 7719), ('\u{1e28}', 7721), ('\u{1e2a}', 7723), - ('\u{1e2c}', 7725), ('\u{1e2e}', 7727), ('\u{1e30}', 7729), ('\u{1e32}', 7731), - ('\u{1e34}', 7733), ('\u{1e36}', 7735), ('\u{1e38}', 7737), ('\u{1e3a}', 7739), - ('\u{1e3c}', 7741), ('\u{1e3e}', 7743), ('\u{1e40}', 7745), ('\u{1e42}', 7747), - ('\u{1e44}', 7749), ('\u{1e46}', 7751), ('\u{1e48}', 7753), ('\u{1e4a}', 7755), - ('\u{1e4c}', 7757), ('\u{1e4e}', 7759), ('\u{1e50}', 7761), ('\u{1e52}', 7763), - ('\u{1e54}', 7765), ('\u{1e56}', 7767), ('\u{1e58}', 7769), ('\u{1e5a}', 7771), - ('\u{1e5c}', 7773), ('\u{1e5e}', 7775), ('\u{1e60}', 7777), ('\u{1e62}', 7779), - ('\u{1e64}', 7781), ('\u{1e66}', 7783), ('\u{1e68}', 7785), ('\u{1e6a}', 7787), - ('\u{1e6c}', 7789), ('\u{1e6e}', 7791), ('\u{1e70}', 7793), ('\u{1e72}', 7795), - ('\u{1e74}', 7797), ('\u{1e76}', 7799), ('\u{1e78}', 7801), ('\u{1e7a}', 7803), - ('\u{1e7c}', 7805), ('\u{1e7e}', 7807), ('\u{1e80}', 7809), ('\u{1e82}', 7811), - ('\u{1e84}', 7813), ('\u{1e86}', 7815), ('\u{1e88}', 7817), ('\u{1e8a}', 7819), - ('\u{1e8c}', 7821), ('\u{1e8e}', 7823), ('\u{1e90}', 7825), ('\u{1e92}', 7827), - ('\u{1e94}', 7829), ('\u{1e9e}', 223), ('\u{1ea0}', 7841), ('\u{1ea2}', 7843), - ('\u{1ea4}', 7845), ('\u{1ea6}', 7847), ('\u{1ea8}', 7849), ('\u{1eaa}', 7851), - ('\u{1eac}', 7853), ('\u{1eae}', 7855), ('\u{1eb0}', 7857), ('\u{1eb2}', 7859), - ('\u{1eb4}', 7861), ('\u{1eb6}', 7863), ('\u{1eb8}', 7865), ('\u{1eba}', 7867), - ('\u{1ebc}', 7869), ('\u{1ebe}', 7871), ('\u{1ec0}', 7873), ('\u{1ec2}', 7875), - ('\u{1ec4}', 7877), ('\u{1ec6}', 7879), ('\u{1ec8}', 7881), ('\u{1eca}', 7883), - ('\u{1ecc}', 7885), ('\u{1ece}', 7887), ('\u{1ed0}', 7889), ('\u{1ed2}', 7891), - ('\u{1ed4}', 7893), ('\u{1ed6}', 7895), ('\u{1ed8}', 7897), ('\u{1eda}', 7899), - ('\u{1edc}', 7901), ('\u{1ede}', 7903), ('\u{1ee0}', 7905), ('\u{1ee2}', 7907), - ('\u{1ee4}', 7909), ('\u{1ee6}', 7911), ('\u{1ee8}', 7913), ('\u{1eea}', 7915), - ('\u{1eec}', 7917), ('\u{1eee}', 7919), ('\u{1ef0}', 7921), ('\u{1ef2}', 7923), - ('\u{1ef4}', 7925), ('\u{1ef6}', 7927), ('\u{1ef8}', 7929), ('\u{1efa}', 7931), - ('\u{1efc}', 7933), ('\u{1efe}', 7935), ('\u{1f08}', 7936), ('\u{1f09}', 7937), - ('\u{1f0a}', 7938), ('\u{1f0b}', 7939), ('\u{1f0c}', 7940), ('\u{1f0d}', 7941), - ('\u{1f0e}', 7942), ('\u{1f0f}', 7943), ('\u{1f18}', 7952), ('\u{1f19}', 7953), - ('\u{1f1a}', 7954), ('\u{1f1b}', 7955), ('\u{1f1c}', 7956), ('\u{1f1d}', 7957), - ('\u{1f28}', 7968), ('\u{1f29}', 7969), ('\u{1f2a}', 7970), ('\u{1f2b}', 7971), - ('\u{1f2c}', 7972), ('\u{1f2d}', 7973), ('\u{1f2e}', 7974), ('\u{1f2f}', 7975), - ('\u{1f38}', 7984), ('\u{1f39}', 7985), ('\u{1f3a}', 7986), ('\u{1f3b}', 7987), - ('\u{1f3c}', 7988), ('\u{1f3d}', 7989), ('\u{1f3e}', 7990), ('\u{1f3f}', 7991), - ('\u{1f48}', 8000), ('\u{1f49}', 8001), ('\u{1f4a}', 8002), ('\u{1f4b}', 8003), - ('\u{1f4c}', 8004), ('\u{1f4d}', 8005), ('\u{1f59}', 8017), ('\u{1f5b}', 8019), - ('\u{1f5d}', 8021), ('\u{1f5f}', 8023), ('\u{1f68}', 8032), ('\u{1f69}', 8033), - ('\u{1f6a}', 8034), ('\u{1f6b}', 8035), ('\u{1f6c}', 8036), ('\u{1f6d}', 8037), - ('\u{1f6e}', 8038), ('\u{1f6f}', 8039), ('\u{1f88}', 8064), ('\u{1f89}', 8065), - ('\u{1f8a}', 8066), ('\u{1f8b}', 8067), ('\u{1f8c}', 8068), ('\u{1f8d}', 8069), - ('\u{1f8e}', 8070), ('\u{1f8f}', 8071), ('\u{1f98}', 8080), ('\u{1f99}', 8081), - ('\u{1f9a}', 8082), ('\u{1f9b}', 8083), ('\u{1f9c}', 8084), ('\u{1f9d}', 8085), - ('\u{1f9e}', 8086), ('\u{1f9f}', 8087), ('\u{1fa8}', 8096), ('\u{1fa9}', 8097), - ('\u{1faa}', 8098), ('\u{1fab}', 8099), ('\u{1fac}', 8100), ('\u{1fad}', 8101), - ('\u{1fae}', 8102), ('\u{1faf}', 8103), ('\u{1fb8}', 8112), ('\u{1fb9}', 8113), - ('\u{1fba}', 8048), ('\u{1fbb}', 8049), ('\u{1fbc}', 8115), ('\u{1fc8}', 8050), - ('\u{1fc9}', 8051), ('\u{1fca}', 8052), ('\u{1fcb}', 8053), ('\u{1fcc}', 8131), - ('\u{1fd8}', 8144), ('\u{1fd9}', 8145), ('\u{1fda}', 8054), ('\u{1fdb}', 8055), - ('\u{1fe8}', 8160), ('\u{1fe9}', 8161), ('\u{1fea}', 8058), ('\u{1feb}', 8059), - ('\u{1fec}', 8165), ('\u{1ff8}', 8056), ('\u{1ff9}', 8057), ('\u{1ffa}', 8060), - ('\u{1ffb}', 8061), ('\u{1ffc}', 8179), ('\u{2126}', 969), ('\u{212a}', 107), - ('\u{212b}', 229), ('\u{2132}', 8526), ('\u{2160}', 8560), ('\u{2161}', 8561), - ('\u{2162}', 8562), ('\u{2163}', 8563), ('\u{2164}', 8564), ('\u{2165}', 8565), - ('\u{2166}', 8566), ('\u{2167}', 8567), ('\u{2168}', 8568), ('\u{2169}', 8569), - ('\u{216a}', 8570), ('\u{216b}', 8571), ('\u{216c}', 8572), ('\u{216d}', 8573), - ('\u{216e}', 8574), ('\u{216f}', 8575), ('\u{2183}', 8580), ('\u{24b6}', 9424), - ('\u{24b7}', 9425), ('\u{24b8}', 9426), ('\u{24b9}', 9427), ('\u{24ba}', 9428), - ('\u{24bb}', 9429), ('\u{24bc}', 9430), ('\u{24bd}', 9431), ('\u{24be}', 9432), - ('\u{24bf}', 9433), ('\u{24c0}', 9434), ('\u{24c1}', 9435), ('\u{24c2}', 9436), - ('\u{24c3}', 9437), ('\u{24c4}', 9438), ('\u{24c5}', 9439), ('\u{24c6}', 9440), - ('\u{24c7}', 9441), ('\u{24c8}', 9442), ('\u{24c9}', 9443), ('\u{24ca}', 9444), - ('\u{24cb}', 9445), ('\u{24cc}', 9446), ('\u{24cd}', 9447), ('\u{24ce}', 9448), - ('\u{24cf}', 9449), ('\u{2c00}', 11312), ('\u{2c01}', 11313), ('\u{2c02}', 11314), - ('\u{2c03}', 11315), ('\u{2c04}', 11316), ('\u{2c05}', 11317), ('\u{2c06}', 11318), - ('\u{2c07}', 11319), ('\u{2c08}', 11320), ('\u{2c09}', 11321), ('\u{2c0a}', 11322), - ('\u{2c0b}', 11323), ('\u{2c0c}', 11324), ('\u{2c0d}', 11325), ('\u{2c0e}', 11326), - ('\u{2c0f}', 11327), ('\u{2c10}', 11328), ('\u{2c11}', 11329), ('\u{2c12}', 11330), - ('\u{2c13}', 11331), ('\u{2c14}', 11332), ('\u{2c15}', 11333), ('\u{2c16}', 11334), - ('\u{2c17}', 11335), ('\u{2c18}', 11336), ('\u{2c19}', 11337), ('\u{2c1a}', 11338), - ('\u{2c1b}', 11339), ('\u{2c1c}', 11340), ('\u{2c1d}', 11341), ('\u{2c1e}', 11342), - ('\u{2c1f}', 11343), ('\u{2c20}', 11344), ('\u{2c21}', 11345), ('\u{2c22}', 11346), - ('\u{2c23}', 11347), ('\u{2c24}', 11348), ('\u{2c25}', 11349), ('\u{2c26}', 11350), - ('\u{2c27}', 11351), ('\u{2c28}', 11352), ('\u{2c29}', 11353), ('\u{2c2a}', 11354), - ('\u{2c2b}', 11355), ('\u{2c2c}', 11356), ('\u{2c2d}', 11357), ('\u{2c2e}', 11358), - ('\u{2c2f}', 11359), ('\u{2c60}', 11361), ('\u{2c62}', 619), ('\u{2c63}', 7549), - ('\u{2c64}', 637), ('\u{2c67}', 11368), ('\u{2c69}', 11370), ('\u{2c6b}', 11372), - ('\u{2c6d}', 593), ('\u{2c6e}', 625), ('\u{2c6f}', 592), ('\u{2c70}', 594), - ('\u{2c72}', 11379), ('\u{2c75}', 11382), ('\u{2c7e}', 575), ('\u{2c7f}', 576), - ('\u{2c80}', 11393), ('\u{2c82}', 11395), ('\u{2c84}', 11397), ('\u{2c86}', 11399), - ('\u{2c88}', 11401), ('\u{2c8a}', 11403), ('\u{2c8c}', 11405), ('\u{2c8e}', 11407), - ('\u{2c90}', 11409), ('\u{2c92}', 11411), ('\u{2c94}', 11413), ('\u{2c96}', 11415), - ('\u{2c98}', 11417), ('\u{2c9a}', 11419), ('\u{2c9c}', 11421), ('\u{2c9e}', 11423), - ('\u{2ca0}', 11425), ('\u{2ca2}', 11427), ('\u{2ca4}', 11429), ('\u{2ca6}', 11431), - ('\u{2ca8}', 11433), ('\u{2caa}', 11435), ('\u{2cac}', 11437), ('\u{2cae}', 11439), - ('\u{2cb0}', 11441), ('\u{2cb2}', 11443), ('\u{2cb4}', 11445), ('\u{2cb6}', 11447), - ('\u{2cb8}', 11449), ('\u{2cba}', 11451), ('\u{2cbc}', 11453), ('\u{2cbe}', 11455), - ('\u{2cc0}', 11457), ('\u{2cc2}', 11459), ('\u{2cc4}', 11461), ('\u{2cc6}', 11463), - ('\u{2cc8}', 11465), ('\u{2cca}', 11467), ('\u{2ccc}', 11469), ('\u{2cce}', 11471), - ('\u{2cd0}', 11473), ('\u{2cd2}', 11475), ('\u{2cd4}', 11477), ('\u{2cd6}', 11479), - ('\u{2cd8}', 11481), ('\u{2cda}', 11483), ('\u{2cdc}', 11485), ('\u{2cde}', 11487), - ('\u{2ce0}', 11489), ('\u{2ce2}', 11491), ('\u{2ceb}', 11500), ('\u{2ced}', 11502), - ('\u{2cf2}', 11507), ('\u{a640}', 42561), ('\u{a642}', 42563), ('\u{a644}', 42565), - ('\u{a646}', 42567), ('\u{a648}', 42569), ('\u{a64a}', 42571), ('\u{a64c}', 42573), - ('\u{a64e}', 42575), ('\u{a650}', 42577), ('\u{a652}', 42579), ('\u{a654}', 42581), - ('\u{a656}', 42583), ('\u{a658}', 42585), ('\u{a65a}', 42587), ('\u{a65c}', 42589), - ('\u{a65e}', 42591), ('\u{a660}', 42593), ('\u{a662}', 42595), ('\u{a664}', 42597), - ('\u{a666}', 42599), ('\u{a668}', 42601), ('\u{a66a}', 42603), ('\u{a66c}', 42605), - ('\u{a680}', 42625), ('\u{a682}', 42627), ('\u{a684}', 42629), ('\u{a686}', 42631), - ('\u{a688}', 42633), ('\u{a68a}', 42635), ('\u{a68c}', 42637), ('\u{a68e}', 42639), - ('\u{a690}', 42641), ('\u{a692}', 42643), ('\u{a694}', 42645), ('\u{a696}', 42647), - ('\u{a698}', 42649), ('\u{a69a}', 42651), ('\u{a722}', 42787), ('\u{a724}', 42789), - ('\u{a726}', 42791), ('\u{a728}', 42793), ('\u{a72a}', 42795), ('\u{a72c}', 42797), - ('\u{a72e}', 42799), ('\u{a732}', 42803), ('\u{a734}', 42805), ('\u{a736}', 42807), - ('\u{a738}', 42809), ('\u{a73a}', 42811), ('\u{a73c}', 42813), ('\u{a73e}', 42815), - ('\u{a740}', 42817), ('\u{a742}', 42819), ('\u{a744}', 42821), ('\u{a746}', 42823), - ('\u{a748}', 42825), ('\u{a74a}', 42827), ('\u{a74c}', 42829), ('\u{a74e}', 42831), - ('\u{a750}', 42833), ('\u{a752}', 42835), ('\u{a754}', 42837), ('\u{a756}', 42839), - ('\u{a758}', 42841), ('\u{a75a}', 42843), ('\u{a75c}', 42845), ('\u{a75e}', 42847), - ('\u{a760}', 42849), ('\u{a762}', 42851), ('\u{a764}', 42853), ('\u{a766}', 42855), - ('\u{a768}', 42857), ('\u{a76a}', 42859), ('\u{a76c}', 42861), ('\u{a76e}', 42863), - ('\u{a779}', 42874), ('\u{a77b}', 42876), ('\u{a77d}', 7545), ('\u{a77e}', 42879), - ('\u{a780}', 42881), ('\u{a782}', 42883), ('\u{a784}', 42885), ('\u{a786}', 42887), - ('\u{a78b}', 42892), ('\u{a78d}', 613), ('\u{a790}', 42897), ('\u{a792}', 42899), - ('\u{a796}', 42903), ('\u{a798}', 42905), ('\u{a79a}', 42907), ('\u{a79c}', 42909), - ('\u{a79e}', 42911), ('\u{a7a0}', 42913), ('\u{a7a2}', 42915), ('\u{a7a4}', 42917), - ('\u{a7a6}', 42919), ('\u{a7a8}', 42921), ('\u{a7aa}', 614), ('\u{a7ab}', 604), - ('\u{a7ac}', 609), ('\u{a7ad}', 620), ('\u{a7ae}', 618), ('\u{a7b0}', 670), - ('\u{a7b1}', 647), ('\u{a7b2}', 669), ('\u{a7b3}', 43859), ('\u{a7b4}', 42933), - ('\u{a7b6}', 42935), ('\u{a7b8}', 42937), ('\u{a7ba}', 42939), ('\u{a7bc}', 42941), - ('\u{a7be}', 42943), ('\u{a7c0}', 42945), ('\u{a7c2}', 42947), ('\u{a7c4}', 42900), - ('\u{a7c5}', 642), ('\u{a7c6}', 7566), ('\u{a7c7}', 42952), ('\u{a7c9}', 42954), - ('\u{a7d0}', 42961), ('\u{a7d6}', 42967), ('\u{a7d8}', 42969), ('\u{a7f5}', 42998), - ('\u{ff21}', 65345), ('\u{ff22}', 65346), ('\u{ff23}', 65347), ('\u{ff24}', 65348), - ('\u{ff25}', 65349), ('\u{ff26}', 65350), ('\u{ff27}', 65351), ('\u{ff28}', 65352), - ('\u{ff29}', 65353), ('\u{ff2a}', 65354), ('\u{ff2b}', 65355), ('\u{ff2c}', 65356), - ('\u{ff2d}', 65357), ('\u{ff2e}', 65358), ('\u{ff2f}', 65359), ('\u{ff30}', 65360), - ('\u{ff31}', 65361), ('\u{ff32}', 65362), ('\u{ff33}', 65363), ('\u{ff34}', 65364), - ('\u{ff35}', 65365), ('\u{ff36}', 65366), ('\u{ff37}', 65367), ('\u{ff38}', 65368), - ('\u{ff39}', 65369), ('\u{ff3a}', 65370), ('\u{10400}', 66600), ('\u{10401}', 66601), - ('\u{10402}', 66602), ('\u{10403}', 66603), ('\u{10404}', 66604), ('\u{10405}', 66605), - ('\u{10406}', 66606), ('\u{10407}', 66607), ('\u{10408}', 66608), ('\u{10409}', 66609), - ('\u{1040a}', 66610), ('\u{1040b}', 66611), ('\u{1040c}', 66612), ('\u{1040d}', 66613), - ('\u{1040e}', 66614), ('\u{1040f}', 66615), ('\u{10410}', 66616), ('\u{10411}', 66617), - ('\u{10412}', 66618), ('\u{10413}', 66619), ('\u{10414}', 66620), ('\u{10415}', 66621), - ('\u{10416}', 66622), ('\u{10417}', 66623), ('\u{10418}', 66624), ('\u{10419}', 66625), - ('\u{1041a}', 66626), ('\u{1041b}', 66627), ('\u{1041c}', 66628), ('\u{1041d}', 66629), - ('\u{1041e}', 66630), ('\u{1041f}', 66631), ('\u{10420}', 66632), ('\u{10421}', 66633), - ('\u{10422}', 66634), ('\u{10423}', 66635), ('\u{10424}', 66636), ('\u{10425}', 66637), - ('\u{10426}', 66638), ('\u{10427}', 66639), ('\u{104b0}', 66776), ('\u{104b1}', 66777), - ('\u{104b2}', 66778), ('\u{104b3}', 66779), ('\u{104b4}', 66780), ('\u{104b5}', 66781), - ('\u{104b6}', 66782), ('\u{104b7}', 66783), ('\u{104b8}', 66784), ('\u{104b9}', 66785), - ('\u{104ba}', 66786), ('\u{104bb}', 66787), ('\u{104bc}', 66788), ('\u{104bd}', 66789), - ('\u{104be}', 66790), ('\u{104bf}', 66791), ('\u{104c0}', 66792), ('\u{104c1}', 66793), - ('\u{104c2}', 66794), ('\u{104c3}', 66795), ('\u{104c4}', 66796), ('\u{104c5}', 66797), - ('\u{104c6}', 66798), ('\u{104c7}', 66799), ('\u{104c8}', 66800), ('\u{104c9}', 66801), - ('\u{104ca}', 66802), ('\u{104cb}', 66803), ('\u{104cc}', 66804), ('\u{104cd}', 66805), - ('\u{104ce}', 66806), ('\u{104cf}', 66807), ('\u{104d0}', 66808), ('\u{104d1}', 66809), - ('\u{104d2}', 66810), ('\u{104d3}', 66811), ('\u{10570}', 66967), ('\u{10571}', 66968), - ('\u{10572}', 66969), ('\u{10573}', 66970), ('\u{10574}', 66971), ('\u{10575}', 66972), - ('\u{10576}', 66973), ('\u{10577}', 66974), ('\u{10578}', 66975), ('\u{10579}', 66976), - ('\u{1057a}', 66977), ('\u{1057c}', 66979), ('\u{1057d}', 66980), ('\u{1057e}', 66981), - ('\u{1057f}', 66982), ('\u{10580}', 66983), ('\u{10581}', 66984), ('\u{10582}', 66985), - ('\u{10583}', 66986), ('\u{10584}', 66987), ('\u{10585}', 66988), ('\u{10586}', 66989), - ('\u{10587}', 66990), ('\u{10588}', 66991), ('\u{10589}', 66992), ('\u{1058a}', 66993), - ('\u{1058c}', 66995), ('\u{1058d}', 66996), ('\u{1058e}', 66997), ('\u{1058f}', 66998), - ('\u{10590}', 66999), ('\u{10591}', 67000), ('\u{10592}', 67001), ('\u{10594}', 67003), - ('\u{10595}', 67004), ('\u{10c80}', 68800), ('\u{10c81}', 68801), ('\u{10c82}', 68802), - ('\u{10c83}', 68803), ('\u{10c84}', 68804), ('\u{10c85}', 68805), ('\u{10c86}', 68806), - ('\u{10c87}', 68807), ('\u{10c88}', 68808), ('\u{10c89}', 68809), ('\u{10c8a}', 68810), - ('\u{10c8b}', 68811), ('\u{10c8c}', 68812), ('\u{10c8d}', 68813), ('\u{10c8e}', 68814), - ('\u{10c8f}', 68815), ('\u{10c90}', 68816), ('\u{10c91}', 68817), ('\u{10c92}', 68818), - ('\u{10c93}', 68819), ('\u{10c94}', 68820), ('\u{10c95}', 68821), ('\u{10c96}', 68822), - ('\u{10c97}', 68823), ('\u{10c98}', 68824), ('\u{10c99}', 68825), ('\u{10c9a}', 68826), - ('\u{10c9b}', 68827), ('\u{10c9c}', 68828), ('\u{10c9d}', 68829), ('\u{10c9e}', 68830), - ('\u{10c9f}', 68831), ('\u{10ca0}', 68832), ('\u{10ca1}', 68833), ('\u{10ca2}', 68834), - ('\u{10ca3}', 68835), ('\u{10ca4}', 68836), ('\u{10ca5}', 68837), ('\u{10ca6}', 68838), - ('\u{10ca7}', 68839), ('\u{10ca8}', 68840), ('\u{10ca9}', 68841), ('\u{10caa}', 68842), - ('\u{10cab}', 68843), ('\u{10cac}', 68844), ('\u{10cad}', 68845), ('\u{10cae}', 68846), - ('\u{10caf}', 68847), ('\u{10cb0}', 68848), ('\u{10cb1}', 68849), ('\u{10cb2}', 68850), - ('\u{118a0}', 71872), ('\u{118a1}', 71873), ('\u{118a2}', 71874), ('\u{118a3}', 71875), - ('\u{118a4}', 71876), ('\u{118a5}', 71877), ('\u{118a6}', 71878), ('\u{118a7}', 71879), - ('\u{118a8}', 71880), ('\u{118a9}', 71881), ('\u{118aa}', 71882), ('\u{118ab}', 71883), - ('\u{118ac}', 71884), ('\u{118ad}', 71885), ('\u{118ae}', 71886), ('\u{118af}', 71887), - ('\u{118b0}', 71888), ('\u{118b1}', 71889), ('\u{118b2}', 71890), ('\u{118b3}', 71891), - ('\u{118b4}', 71892), ('\u{118b5}', 71893), ('\u{118b6}', 71894), ('\u{118b7}', 71895), - ('\u{118b8}', 71896), ('\u{118b9}', 71897), ('\u{118ba}', 71898), ('\u{118bb}', 71899), - ('\u{118bc}', 71900), ('\u{118bd}', 71901), ('\u{118be}', 71902), ('\u{118bf}', 71903), - ('\u{16e40}', 93792), ('\u{16e41}', 93793), ('\u{16e42}', 93794), ('\u{16e43}', 93795), - ('\u{16e44}', 93796), ('\u{16e45}', 93797), ('\u{16e46}', 93798), ('\u{16e47}', 93799), - ('\u{16e48}', 93800), ('\u{16e49}', 93801), ('\u{16e4a}', 93802), ('\u{16e4b}', 93803), - ('\u{16e4c}', 93804), ('\u{16e4d}', 93805), ('\u{16e4e}', 93806), ('\u{16e4f}', 93807), - ('\u{16e50}', 93808), ('\u{16e51}', 93809), ('\u{16e52}', 93810), ('\u{16e53}', 93811), - ('\u{16e54}', 93812), ('\u{16e55}', 93813), ('\u{16e56}', 93814), ('\u{16e57}', 93815), - ('\u{16e58}', 93816), ('\u{16e59}', 93817), ('\u{16e5a}', 93818), ('\u{16e5b}', 93819), - ('\u{16e5c}', 93820), ('\u{16e5d}', 93821), ('\u{16e5e}', 93822), ('\u{16e5f}', 93823), - ('\u{1e900}', 125218), ('\u{1e901}', 125219), ('\u{1e902}', 125220), ('\u{1e903}', 125221), - ('\u{1e904}', 125222), ('\u{1e905}', 125223), ('\u{1e906}', 125224), ('\u{1e907}', 125225), - ('\u{1e908}', 125226), ('\u{1e909}', 125227), ('\u{1e90a}', 125228), ('\u{1e90b}', 125229), - ('\u{1e90c}', 125230), ('\u{1e90d}', 125231), ('\u{1e90e}', 125232), ('\u{1e90f}', 125233), - ('\u{1e910}', 125234), ('\u{1e911}', 125235), ('\u{1e912}', 125236), ('\u{1e913}', 125237), - ('\u{1e914}', 125238), ('\u{1e915}', 125239), ('\u{1e916}', 125240), ('\u{1e917}', 125241), - ('\u{1e918}', 125242), ('\u{1e919}', 125243), ('\u{1e91a}', 125244), ('\u{1e91b}', 125245), - ('\u{1e91c}', 125246), ('\u{1e91d}', 125247), ('\u{1e91e}', 125248), ('\u{1e91f}', 125249), - ('\u{1e920}', 125250), ('\u{1e921}', 125251), - ]; - - static LOWERCASE_TABLE_MULTI: &[[char; 3]] = &[ - ['i', '\u{307}', '\u{0}'], - ]; - - static UPPERCASE_TABLE: &[(char, u32)] = &[ - ('\u{b5}', 924), ('\u{df}', 4194304), ('\u{e0}', 192), ('\u{e1}', 193), ('\u{e2}', 194), - ('\u{e3}', 195), ('\u{e4}', 196), ('\u{e5}', 197), ('\u{e6}', 198), ('\u{e7}', 199), - ('\u{e8}', 200), ('\u{e9}', 201), ('\u{ea}', 202), ('\u{eb}', 203), ('\u{ec}', 204), - ('\u{ed}', 205), ('\u{ee}', 206), ('\u{ef}', 207), ('\u{f0}', 208), ('\u{f1}', 209), - ('\u{f2}', 210), ('\u{f3}', 211), ('\u{f4}', 212), ('\u{f5}', 213), ('\u{f6}', 214), - ('\u{f8}', 216), ('\u{f9}', 217), ('\u{fa}', 218), ('\u{fb}', 219), ('\u{fc}', 220), - ('\u{fd}', 221), ('\u{fe}', 222), ('\u{ff}', 376), ('\u{101}', 256), ('\u{103}', 258), - ('\u{105}', 260), ('\u{107}', 262), ('\u{109}', 264), ('\u{10b}', 266), ('\u{10d}', 268), - ('\u{10f}', 270), ('\u{111}', 272), ('\u{113}', 274), ('\u{115}', 276), ('\u{117}', 278), - ('\u{119}', 280), ('\u{11b}', 282), ('\u{11d}', 284), ('\u{11f}', 286), ('\u{121}', 288), - ('\u{123}', 290), ('\u{125}', 292), ('\u{127}', 294), ('\u{129}', 296), ('\u{12b}', 298), - ('\u{12d}', 300), ('\u{12f}', 302), ('\u{131}', 73), ('\u{133}', 306), ('\u{135}', 308), - ('\u{137}', 310), ('\u{13a}', 313), ('\u{13c}', 315), ('\u{13e}', 317), ('\u{140}', 319), - ('\u{142}', 321), ('\u{144}', 323), ('\u{146}', 325), ('\u{148}', 327), - ('\u{149}', 4194305), ('\u{14b}', 330), ('\u{14d}', 332), ('\u{14f}', 334), - ('\u{151}', 336), ('\u{153}', 338), ('\u{155}', 340), ('\u{157}', 342), ('\u{159}', 344), - ('\u{15b}', 346), ('\u{15d}', 348), ('\u{15f}', 350), ('\u{161}', 352), ('\u{163}', 354), - ('\u{165}', 356), ('\u{167}', 358), ('\u{169}', 360), ('\u{16b}', 362), ('\u{16d}', 364), - ('\u{16f}', 366), ('\u{171}', 368), ('\u{173}', 370), ('\u{175}', 372), ('\u{177}', 374), - ('\u{17a}', 377), ('\u{17c}', 379), ('\u{17e}', 381), ('\u{17f}', 83), ('\u{180}', 579), - ('\u{183}', 386), ('\u{185}', 388), ('\u{188}', 391), ('\u{18c}', 395), ('\u{192}', 401), - ('\u{195}', 502), ('\u{199}', 408), ('\u{19a}', 573), ('\u{19e}', 544), ('\u{1a1}', 416), - ('\u{1a3}', 418), ('\u{1a5}', 420), ('\u{1a8}', 423), ('\u{1ad}', 428), ('\u{1b0}', 431), - ('\u{1b4}', 435), ('\u{1b6}', 437), ('\u{1b9}', 440), ('\u{1bd}', 444), ('\u{1bf}', 503), - ('\u{1c5}', 452), ('\u{1c6}', 452), ('\u{1c8}', 455), ('\u{1c9}', 455), ('\u{1cb}', 458), - ('\u{1cc}', 458), ('\u{1ce}', 461), ('\u{1d0}', 463), ('\u{1d2}', 465), ('\u{1d4}', 467), - ('\u{1d6}', 469), ('\u{1d8}', 471), ('\u{1da}', 473), ('\u{1dc}', 475), ('\u{1dd}', 398), - ('\u{1df}', 478), ('\u{1e1}', 480), ('\u{1e3}', 482), ('\u{1e5}', 484), ('\u{1e7}', 486), - ('\u{1e9}', 488), ('\u{1eb}', 490), ('\u{1ed}', 492), ('\u{1ef}', 494), - ('\u{1f0}', 4194306), ('\u{1f2}', 497), ('\u{1f3}', 497), ('\u{1f5}', 500), - ('\u{1f9}', 504), ('\u{1fb}', 506), ('\u{1fd}', 508), ('\u{1ff}', 510), ('\u{201}', 512), - ('\u{203}', 514), ('\u{205}', 516), ('\u{207}', 518), ('\u{209}', 520), ('\u{20b}', 522), - ('\u{20d}', 524), ('\u{20f}', 526), ('\u{211}', 528), ('\u{213}', 530), ('\u{215}', 532), - ('\u{217}', 534), ('\u{219}', 536), ('\u{21b}', 538), ('\u{21d}', 540), ('\u{21f}', 542), - ('\u{223}', 546), ('\u{225}', 548), ('\u{227}', 550), ('\u{229}', 552), ('\u{22b}', 554), - ('\u{22d}', 556), ('\u{22f}', 558), ('\u{231}', 560), ('\u{233}', 562), ('\u{23c}', 571), - ('\u{23f}', 11390), ('\u{240}', 11391), ('\u{242}', 577), ('\u{247}', 582), - ('\u{249}', 584), ('\u{24b}', 586), ('\u{24d}', 588), ('\u{24f}', 590), ('\u{250}', 11375), - ('\u{251}', 11373), ('\u{252}', 11376), ('\u{253}', 385), ('\u{254}', 390), - ('\u{256}', 393), ('\u{257}', 394), ('\u{259}', 399), ('\u{25b}', 400), ('\u{25c}', 42923), - ('\u{260}', 403), ('\u{261}', 42924), ('\u{263}', 404), ('\u{265}', 42893), - ('\u{266}', 42922), ('\u{268}', 407), ('\u{269}', 406), ('\u{26a}', 42926), - ('\u{26b}', 11362), ('\u{26c}', 42925), ('\u{26f}', 412), ('\u{271}', 11374), - ('\u{272}', 413), ('\u{275}', 415), ('\u{27d}', 11364), ('\u{280}', 422), - ('\u{282}', 42949), ('\u{283}', 425), ('\u{287}', 42929), ('\u{288}', 430), - ('\u{289}', 580), ('\u{28a}', 433), ('\u{28b}', 434), ('\u{28c}', 581), ('\u{292}', 439), - ('\u{29d}', 42930), ('\u{29e}', 42928), ('\u{345}', 921), ('\u{371}', 880), - ('\u{373}', 882), ('\u{377}', 886), ('\u{37b}', 1021), ('\u{37c}', 1022), ('\u{37d}', 1023), - ('\u{390}', 4194307), ('\u{3ac}', 902), ('\u{3ad}', 904), ('\u{3ae}', 905), - ('\u{3af}', 906), ('\u{3b0}', 4194308), ('\u{3b1}', 913), ('\u{3b2}', 914), - ('\u{3b3}', 915), ('\u{3b4}', 916), ('\u{3b5}', 917), ('\u{3b6}', 918), ('\u{3b7}', 919), - ('\u{3b8}', 920), ('\u{3b9}', 921), ('\u{3ba}', 922), ('\u{3bb}', 923), ('\u{3bc}', 924), - ('\u{3bd}', 925), ('\u{3be}', 926), ('\u{3bf}', 927), ('\u{3c0}', 928), ('\u{3c1}', 929), - ('\u{3c2}', 931), ('\u{3c3}', 931), ('\u{3c4}', 932), ('\u{3c5}', 933), ('\u{3c6}', 934), - ('\u{3c7}', 935), ('\u{3c8}', 936), ('\u{3c9}', 937), ('\u{3ca}', 938), ('\u{3cb}', 939), - ('\u{3cc}', 908), ('\u{3cd}', 910), ('\u{3ce}', 911), ('\u{3d0}', 914), ('\u{3d1}', 920), - ('\u{3d5}', 934), ('\u{3d6}', 928), ('\u{3d7}', 975), ('\u{3d9}', 984), ('\u{3db}', 986), - ('\u{3dd}', 988), ('\u{3df}', 990), ('\u{3e1}', 992), ('\u{3e3}', 994), ('\u{3e5}', 996), - ('\u{3e7}', 998), ('\u{3e9}', 1000), ('\u{3eb}', 1002), ('\u{3ed}', 1004), - ('\u{3ef}', 1006), ('\u{3f0}', 922), ('\u{3f1}', 929), ('\u{3f2}', 1017), ('\u{3f3}', 895), - ('\u{3f5}', 917), ('\u{3f8}', 1015), ('\u{3fb}', 1018), ('\u{430}', 1040), - ('\u{431}', 1041), ('\u{432}', 1042), ('\u{433}', 1043), ('\u{434}', 1044), - ('\u{435}', 1045), ('\u{436}', 1046), ('\u{437}', 1047), ('\u{438}', 1048), - ('\u{439}', 1049), ('\u{43a}', 1050), ('\u{43b}', 1051), ('\u{43c}', 1052), - ('\u{43d}', 1053), ('\u{43e}', 1054), ('\u{43f}', 1055), ('\u{440}', 1056), - ('\u{441}', 1057), ('\u{442}', 1058), ('\u{443}', 1059), ('\u{444}', 1060), - ('\u{445}', 1061), ('\u{446}', 1062), ('\u{447}', 1063), ('\u{448}', 1064), - ('\u{449}', 1065), ('\u{44a}', 1066), ('\u{44b}', 1067), ('\u{44c}', 1068), - ('\u{44d}', 1069), ('\u{44e}', 1070), ('\u{44f}', 1071), ('\u{450}', 1024), - ('\u{451}', 1025), ('\u{452}', 1026), ('\u{453}', 1027), ('\u{454}', 1028), - ('\u{455}', 1029), ('\u{456}', 1030), ('\u{457}', 1031), ('\u{458}', 1032), - ('\u{459}', 1033), ('\u{45a}', 1034), ('\u{45b}', 1035), ('\u{45c}', 1036), - ('\u{45d}', 1037), ('\u{45e}', 1038), ('\u{45f}', 1039), ('\u{461}', 1120), - ('\u{463}', 1122), ('\u{465}', 1124), ('\u{467}', 1126), ('\u{469}', 1128), - ('\u{46b}', 1130), ('\u{46d}', 1132), ('\u{46f}', 1134), ('\u{471}', 1136), - ('\u{473}', 1138), ('\u{475}', 1140), ('\u{477}', 1142), ('\u{479}', 1144), - ('\u{47b}', 1146), ('\u{47d}', 1148), ('\u{47f}', 1150), ('\u{481}', 1152), - ('\u{48b}', 1162), ('\u{48d}', 1164), ('\u{48f}', 1166), ('\u{491}', 1168), - ('\u{493}', 1170), ('\u{495}', 1172), ('\u{497}', 1174), ('\u{499}', 1176), - ('\u{49b}', 1178), ('\u{49d}', 1180), ('\u{49f}', 1182), ('\u{4a1}', 1184), - ('\u{4a3}', 1186), ('\u{4a5}', 1188), ('\u{4a7}', 1190), ('\u{4a9}', 1192), - ('\u{4ab}', 1194), ('\u{4ad}', 1196), ('\u{4af}', 1198), ('\u{4b1}', 1200), - ('\u{4b3}', 1202), ('\u{4b5}', 1204), ('\u{4b7}', 1206), ('\u{4b9}', 1208), - ('\u{4bb}', 1210), ('\u{4bd}', 1212), ('\u{4bf}', 1214), ('\u{4c2}', 1217), - ('\u{4c4}', 1219), ('\u{4c6}', 1221), ('\u{4c8}', 1223), ('\u{4ca}', 1225), - ('\u{4cc}', 1227), ('\u{4ce}', 1229), ('\u{4cf}', 1216), ('\u{4d1}', 1232), - ('\u{4d3}', 1234), ('\u{4d5}', 1236), ('\u{4d7}', 1238), ('\u{4d9}', 1240), - ('\u{4db}', 1242), ('\u{4dd}', 1244), ('\u{4df}', 1246), ('\u{4e1}', 1248), - ('\u{4e3}', 1250), ('\u{4e5}', 1252), ('\u{4e7}', 1254), ('\u{4e9}', 1256), - ('\u{4eb}', 1258), ('\u{4ed}', 1260), ('\u{4ef}', 1262), ('\u{4f1}', 1264), - ('\u{4f3}', 1266), ('\u{4f5}', 1268), ('\u{4f7}', 1270), ('\u{4f9}', 1272), - ('\u{4fb}', 1274), ('\u{4fd}', 1276), ('\u{4ff}', 1278), ('\u{501}', 1280), - ('\u{503}', 1282), ('\u{505}', 1284), ('\u{507}', 1286), ('\u{509}', 1288), - ('\u{50b}', 1290), ('\u{50d}', 1292), ('\u{50f}', 1294), ('\u{511}', 1296), - ('\u{513}', 1298), ('\u{515}', 1300), ('\u{517}', 1302), ('\u{519}', 1304), - ('\u{51b}', 1306), ('\u{51d}', 1308), ('\u{51f}', 1310), ('\u{521}', 1312), - ('\u{523}', 1314), ('\u{525}', 1316), ('\u{527}', 1318), ('\u{529}', 1320), - ('\u{52b}', 1322), ('\u{52d}', 1324), ('\u{52f}', 1326), ('\u{561}', 1329), - ('\u{562}', 1330), ('\u{563}', 1331), ('\u{564}', 1332), ('\u{565}', 1333), - ('\u{566}', 1334), ('\u{567}', 1335), ('\u{568}', 1336), ('\u{569}', 1337), - ('\u{56a}', 1338), ('\u{56b}', 1339), ('\u{56c}', 1340), ('\u{56d}', 1341), - ('\u{56e}', 1342), ('\u{56f}', 1343), ('\u{570}', 1344), ('\u{571}', 1345), - ('\u{572}', 1346), ('\u{573}', 1347), ('\u{574}', 1348), ('\u{575}', 1349), - ('\u{576}', 1350), ('\u{577}', 1351), ('\u{578}', 1352), ('\u{579}', 1353), - ('\u{57a}', 1354), ('\u{57b}', 1355), ('\u{57c}', 1356), ('\u{57d}', 1357), - ('\u{57e}', 1358), ('\u{57f}', 1359), ('\u{580}', 1360), ('\u{581}', 1361), - ('\u{582}', 1362), ('\u{583}', 1363), ('\u{584}', 1364), ('\u{585}', 1365), - ('\u{586}', 1366), ('\u{587}', 4194309), ('\u{10d0}', 7312), ('\u{10d1}', 7313), - ('\u{10d2}', 7314), ('\u{10d3}', 7315), ('\u{10d4}', 7316), ('\u{10d5}', 7317), - ('\u{10d6}', 7318), ('\u{10d7}', 7319), ('\u{10d8}', 7320), ('\u{10d9}', 7321), - ('\u{10da}', 7322), ('\u{10db}', 7323), ('\u{10dc}', 7324), ('\u{10dd}', 7325), - ('\u{10de}', 7326), ('\u{10df}', 7327), ('\u{10e0}', 7328), ('\u{10e1}', 7329), - ('\u{10e2}', 7330), ('\u{10e3}', 7331), ('\u{10e4}', 7332), ('\u{10e5}', 7333), - ('\u{10e6}', 7334), ('\u{10e7}', 7335), ('\u{10e8}', 7336), ('\u{10e9}', 7337), - ('\u{10ea}', 7338), ('\u{10eb}', 7339), ('\u{10ec}', 7340), ('\u{10ed}', 7341), - ('\u{10ee}', 7342), ('\u{10ef}', 7343), ('\u{10f0}', 7344), ('\u{10f1}', 7345), - ('\u{10f2}', 7346), ('\u{10f3}', 7347), ('\u{10f4}', 7348), ('\u{10f5}', 7349), - ('\u{10f6}', 7350), ('\u{10f7}', 7351), ('\u{10f8}', 7352), ('\u{10f9}', 7353), - ('\u{10fa}', 7354), ('\u{10fd}', 7357), ('\u{10fe}', 7358), ('\u{10ff}', 7359), - ('\u{13f8}', 5104), ('\u{13f9}', 5105), ('\u{13fa}', 5106), ('\u{13fb}', 5107), - ('\u{13fc}', 5108), ('\u{13fd}', 5109), ('\u{1c80}', 1042), ('\u{1c81}', 1044), - ('\u{1c82}', 1054), ('\u{1c83}', 1057), ('\u{1c84}', 1058), ('\u{1c85}', 1058), - ('\u{1c86}', 1066), ('\u{1c87}', 1122), ('\u{1c88}', 42570), ('\u{1d79}', 42877), - ('\u{1d7d}', 11363), ('\u{1d8e}', 42950), ('\u{1e01}', 7680), ('\u{1e03}', 7682), - ('\u{1e05}', 7684), ('\u{1e07}', 7686), ('\u{1e09}', 7688), ('\u{1e0b}', 7690), - ('\u{1e0d}', 7692), ('\u{1e0f}', 7694), ('\u{1e11}', 7696), ('\u{1e13}', 7698), - ('\u{1e15}', 7700), ('\u{1e17}', 7702), ('\u{1e19}', 7704), ('\u{1e1b}', 7706), - ('\u{1e1d}', 7708), ('\u{1e1f}', 7710), ('\u{1e21}', 7712), ('\u{1e23}', 7714), - ('\u{1e25}', 7716), ('\u{1e27}', 7718), ('\u{1e29}', 7720), ('\u{1e2b}', 7722), - ('\u{1e2d}', 7724), ('\u{1e2f}', 7726), ('\u{1e31}', 7728), ('\u{1e33}', 7730), - ('\u{1e35}', 7732), ('\u{1e37}', 7734), ('\u{1e39}', 7736), ('\u{1e3b}', 7738), - ('\u{1e3d}', 7740), ('\u{1e3f}', 7742), ('\u{1e41}', 7744), ('\u{1e43}', 7746), - ('\u{1e45}', 7748), ('\u{1e47}', 7750), ('\u{1e49}', 7752), ('\u{1e4b}', 7754), - ('\u{1e4d}', 7756), ('\u{1e4f}', 7758), ('\u{1e51}', 7760), ('\u{1e53}', 7762), - ('\u{1e55}', 7764), ('\u{1e57}', 7766), ('\u{1e59}', 7768), ('\u{1e5b}', 7770), - ('\u{1e5d}', 7772), ('\u{1e5f}', 7774), ('\u{1e61}', 7776), ('\u{1e63}', 7778), - ('\u{1e65}', 7780), ('\u{1e67}', 7782), ('\u{1e69}', 7784), ('\u{1e6b}', 7786), - ('\u{1e6d}', 7788), ('\u{1e6f}', 7790), ('\u{1e71}', 7792), ('\u{1e73}', 7794), - ('\u{1e75}', 7796), ('\u{1e77}', 7798), ('\u{1e79}', 7800), ('\u{1e7b}', 7802), - ('\u{1e7d}', 7804), ('\u{1e7f}', 7806), ('\u{1e81}', 7808), ('\u{1e83}', 7810), - ('\u{1e85}', 7812), ('\u{1e87}', 7814), ('\u{1e89}', 7816), ('\u{1e8b}', 7818), - ('\u{1e8d}', 7820), ('\u{1e8f}', 7822), ('\u{1e91}', 7824), ('\u{1e93}', 7826), - ('\u{1e95}', 7828), ('\u{1e96}', 4194310), ('\u{1e97}', 4194311), ('\u{1e98}', 4194312), - ('\u{1e99}', 4194313), ('\u{1e9a}', 4194314), ('\u{1e9b}', 7776), ('\u{1ea1}', 7840), - ('\u{1ea3}', 7842), ('\u{1ea5}', 7844), ('\u{1ea7}', 7846), ('\u{1ea9}', 7848), - ('\u{1eab}', 7850), ('\u{1ead}', 7852), ('\u{1eaf}', 7854), ('\u{1eb1}', 7856), - ('\u{1eb3}', 7858), ('\u{1eb5}', 7860), ('\u{1eb7}', 7862), ('\u{1eb9}', 7864), - ('\u{1ebb}', 7866), ('\u{1ebd}', 7868), ('\u{1ebf}', 7870), ('\u{1ec1}', 7872), - ('\u{1ec3}', 7874), ('\u{1ec5}', 7876), ('\u{1ec7}', 7878), ('\u{1ec9}', 7880), - ('\u{1ecb}', 7882), ('\u{1ecd}', 7884), ('\u{1ecf}', 7886), ('\u{1ed1}', 7888), - ('\u{1ed3}', 7890), ('\u{1ed5}', 7892), ('\u{1ed7}', 7894), ('\u{1ed9}', 7896), - ('\u{1edb}', 7898), ('\u{1edd}', 7900), ('\u{1edf}', 7902), ('\u{1ee1}', 7904), - ('\u{1ee3}', 7906), ('\u{1ee5}', 7908), ('\u{1ee7}', 7910), ('\u{1ee9}', 7912), - ('\u{1eeb}', 7914), ('\u{1eed}', 7916), ('\u{1eef}', 7918), ('\u{1ef1}', 7920), - ('\u{1ef3}', 7922), ('\u{1ef5}', 7924), ('\u{1ef7}', 7926), ('\u{1ef9}', 7928), - ('\u{1efb}', 7930), ('\u{1efd}', 7932), ('\u{1eff}', 7934), ('\u{1f00}', 7944), - ('\u{1f01}', 7945), ('\u{1f02}', 7946), ('\u{1f03}', 7947), ('\u{1f04}', 7948), - ('\u{1f05}', 7949), ('\u{1f06}', 7950), ('\u{1f07}', 7951), ('\u{1f10}', 7960), - ('\u{1f11}', 7961), ('\u{1f12}', 7962), ('\u{1f13}', 7963), ('\u{1f14}', 7964), - ('\u{1f15}', 7965), ('\u{1f20}', 7976), ('\u{1f21}', 7977), ('\u{1f22}', 7978), - ('\u{1f23}', 7979), ('\u{1f24}', 7980), ('\u{1f25}', 7981), ('\u{1f26}', 7982), - ('\u{1f27}', 7983), ('\u{1f30}', 7992), ('\u{1f31}', 7993), ('\u{1f32}', 7994), - ('\u{1f33}', 7995), ('\u{1f34}', 7996), ('\u{1f35}', 7997), ('\u{1f36}', 7998), - ('\u{1f37}', 7999), ('\u{1f40}', 8008), ('\u{1f41}', 8009), ('\u{1f42}', 8010), - ('\u{1f43}', 8011), ('\u{1f44}', 8012), ('\u{1f45}', 8013), ('\u{1f50}', 4194315), - ('\u{1f51}', 8025), ('\u{1f52}', 4194316), ('\u{1f53}', 8027), ('\u{1f54}', 4194317), - ('\u{1f55}', 8029), ('\u{1f56}', 4194318), ('\u{1f57}', 8031), ('\u{1f60}', 8040), - ('\u{1f61}', 8041), ('\u{1f62}', 8042), ('\u{1f63}', 8043), ('\u{1f64}', 8044), - ('\u{1f65}', 8045), ('\u{1f66}', 8046), ('\u{1f67}', 8047), ('\u{1f70}', 8122), - ('\u{1f71}', 8123), ('\u{1f72}', 8136), ('\u{1f73}', 8137), ('\u{1f74}', 8138), - ('\u{1f75}', 8139), ('\u{1f76}', 8154), ('\u{1f77}', 8155), ('\u{1f78}', 8184), - ('\u{1f79}', 8185), ('\u{1f7a}', 8170), ('\u{1f7b}', 8171), ('\u{1f7c}', 8186), - ('\u{1f7d}', 8187), ('\u{1f80}', 4194319), ('\u{1f81}', 4194320), ('\u{1f82}', 4194321), - ('\u{1f83}', 4194322), ('\u{1f84}', 4194323), ('\u{1f85}', 4194324), ('\u{1f86}', 4194325), - ('\u{1f87}', 4194326), ('\u{1f88}', 4194327), ('\u{1f89}', 4194328), ('\u{1f8a}', 4194329), - ('\u{1f8b}', 4194330), ('\u{1f8c}', 4194331), ('\u{1f8d}', 4194332), ('\u{1f8e}', 4194333), - ('\u{1f8f}', 4194334), ('\u{1f90}', 4194335), ('\u{1f91}', 4194336), ('\u{1f92}', 4194337), - ('\u{1f93}', 4194338), ('\u{1f94}', 4194339), ('\u{1f95}', 4194340), ('\u{1f96}', 4194341), - ('\u{1f97}', 4194342), ('\u{1f98}', 4194343), ('\u{1f99}', 4194344), ('\u{1f9a}', 4194345), - ('\u{1f9b}', 4194346), ('\u{1f9c}', 4194347), ('\u{1f9d}', 4194348), ('\u{1f9e}', 4194349), - ('\u{1f9f}', 4194350), ('\u{1fa0}', 4194351), ('\u{1fa1}', 4194352), ('\u{1fa2}', 4194353), - ('\u{1fa3}', 4194354), ('\u{1fa4}', 4194355), ('\u{1fa5}', 4194356), ('\u{1fa6}', 4194357), - ('\u{1fa7}', 4194358), ('\u{1fa8}', 4194359), ('\u{1fa9}', 4194360), ('\u{1faa}', 4194361), - ('\u{1fab}', 4194362), ('\u{1fac}', 4194363), ('\u{1fad}', 4194364), ('\u{1fae}', 4194365), - ('\u{1faf}', 4194366), ('\u{1fb0}', 8120), ('\u{1fb1}', 8121), ('\u{1fb2}', 4194367), - ('\u{1fb3}', 4194368), ('\u{1fb4}', 4194369), ('\u{1fb6}', 4194370), ('\u{1fb7}', 4194371), - ('\u{1fbc}', 4194372), ('\u{1fbe}', 921), ('\u{1fc2}', 4194373), ('\u{1fc3}', 4194374), - ('\u{1fc4}', 4194375), ('\u{1fc6}', 4194376), ('\u{1fc7}', 4194377), ('\u{1fcc}', 4194378), - ('\u{1fd0}', 8152), ('\u{1fd1}', 8153), ('\u{1fd2}', 4194379), ('\u{1fd3}', 4194380), - ('\u{1fd6}', 4194381), ('\u{1fd7}', 4194382), ('\u{1fe0}', 8168), ('\u{1fe1}', 8169), - ('\u{1fe2}', 4194383), ('\u{1fe3}', 4194384), ('\u{1fe4}', 4194385), ('\u{1fe5}', 8172), - ('\u{1fe6}', 4194386), ('\u{1fe7}', 4194387), ('\u{1ff2}', 4194388), ('\u{1ff3}', 4194389), - ('\u{1ff4}', 4194390), ('\u{1ff6}', 4194391), ('\u{1ff7}', 4194392), ('\u{1ffc}', 4194393), - ('\u{214e}', 8498), ('\u{2170}', 8544), ('\u{2171}', 8545), ('\u{2172}', 8546), - ('\u{2173}', 8547), ('\u{2174}', 8548), ('\u{2175}', 8549), ('\u{2176}', 8550), - ('\u{2177}', 8551), ('\u{2178}', 8552), ('\u{2179}', 8553), ('\u{217a}', 8554), - ('\u{217b}', 8555), ('\u{217c}', 8556), ('\u{217d}', 8557), ('\u{217e}', 8558), - ('\u{217f}', 8559), ('\u{2184}', 8579), ('\u{24d0}', 9398), ('\u{24d1}', 9399), - ('\u{24d2}', 9400), ('\u{24d3}', 9401), ('\u{24d4}', 9402), ('\u{24d5}', 9403), - ('\u{24d6}', 9404), ('\u{24d7}', 9405), ('\u{24d8}', 9406), ('\u{24d9}', 9407), - ('\u{24da}', 9408), ('\u{24db}', 9409), ('\u{24dc}', 9410), ('\u{24dd}', 9411), - ('\u{24de}', 9412), ('\u{24df}', 9413), ('\u{24e0}', 9414), ('\u{24e1}', 9415), - ('\u{24e2}', 9416), ('\u{24e3}', 9417), ('\u{24e4}', 9418), ('\u{24e5}', 9419), - ('\u{24e6}', 9420), ('\u{24e7}', 9421), ('\u{24e8}', 9422), ('\u{24e9}', 9423), - ('\u{2c30}', 11264), ('\u{2c31}', 11265), ('\u{2c32}', 11266), ('\u{2c33}', 11267), - ('\u{2c34}', 11268), ('\u{2c35}', 11269), ('\u{2c36}', 11270), ('\u{2c37}', 11271), - ('\u{2c38}', 11272), ('\u{2c39}', 11273), ('\u{2c3a}', 11274), ('\u{2c3b}', 11275), - ('\u{2c3c}', 11276), ('\u{2c3d}', 11277), ('\u{2c3e}', 11278), ('\u{2c3f}', 11279), - ('\u{2c40}', 11280), ('\u{2c41}', 11281), ('\u{2c42}', 11282), ('\u{2c43}', 11283), - ('\u{2c44}', 11284), ('\u{2c45}', 11285), ('\u{2c46}', 11286), ('\u{2c47}', 11287), - ('\u{2c48}', 11288), ('\u{2c49}', 11289), ('\u{2c4a}', 11290), ('\u{2c4b}', 11291), - ('\u{2c4c}', 11292), ('\u{2c4d}', 11293), ('\u{2c4e}', 11294), ('\u{2c4f}', 11295), - ('\u{2c50}', 11296), ('\u{2c51}', 11297), ('\u{2c52}', 11298), ('\u{2c53}', 11299), - ('\u{2c54}', 11300), ('\u{2c55}', 11301), ('\u{2c56}', 11302), ('\u{2c57}', 11303), - ('\u{2c58}', 11304), ('\u{2c59}', 11305), ('\u{2c5a}', 11306), ('\u{2c5b}', 11307), - ('\u{2c5c}', 11308), ('\u{2c5d}', 11309), ('\u{2c5e}', 11310), ('\u{2c5f}', 11311), - ('\u{2c61}', 11360), ('\u{2c65}', 570), ('\u{2c66}', 574), ('\u{2c68}', 11367), - ('\u{2c6a}', 11369), ('\u{2c6c}', 11371), ('\u{2c73}', 11378), ('\u{2c76}', 11381), - ('\u{2c81}', 11392), ('\u{2c83}', 11394), ('\u{2c85}', 11396), ('\u{2c87}', 11398), - ('\u{2c89}', 11400), ('\u{2c8b}', 11402), ('\u{2c8d}', 11404), ('\u{2c8f}', 11406), - ('\u{2c91}', 11408), ('\u{2c93}', 11410), ('\u{2c95}', 11412), ('\u{2c97}', 11414), - ('\u{2c99}', 11416), ('\u{2c9b}', 11418), ('\u{2c9d}', 11420), ('\u{2c9f}', 11422), - ('\u{2ca1}', 11424), ('\u{2ca3}', 11426), ('\u{2ca5}', 11428), ('\u{2ca7}', 11430), - ('\u{2ca9}', 11432), ('\u{2cab}', 11434), ('\u{2cad}', 11436), ('\u{2caf}', 11438), - ('\u{2cb1}', 11440), ('\u{2cb3}', 11442), ('\u{2cb5}', 11444), ('\u{2cb7}', 11446), - ('\u{2cb9}', 11448), ('\u{2cbb}', 11450), ('\u{2cbd}', 11452), ('\u{2cbf}', 11454), - ('\u{2cc1}', 11456), ('\u{2cc3}', 11458), ('\u{2cc5}', 11460), ('\u{2cc7}', 11462), - ('\u{2cc9}', 11464), ('\u{2ccb}', 11466), ('\u{2ccd}', 11468), ('\u{2ccf}', 11470), - ('\u{2cd1}', 11472), ('\u{2cd3}', 11474), ('\u{2cd5}', 11476), ('\u{2cd7}', 11478), - ('\u{2cd9}', 11480), ('\u{2cdb}', 11482), ('\u{2cdd}', 11484), ('\u{2cdf}', 11486), - ('\u{2ce1}', 11488), ('\u{2ce3}', 11490), ('\u{2cec}', 11499), ('\u{2cee}', 11501), - ('\u{2cf3}', 11506), ('\u{2d00}', 4256), ('\u{2d01}', 4257), ('\u{2d02}', 4258), - ('\u{2d03}', 4259), ('\u{2d04}', 4260), ('\u{2d05}', 4261), ('\u{2d06}', 4262), - ('\u{2d07}', 4263), ('\u{2d08}', 4264), ('\u{2d09}', 4265), ('\u{2d0a}', 4266), - ('\u{2d0b}', 4267), ('\u{2d0c}', 4268), ('\u{2d0d}', 4269), ('\u{2d0e}', 4270), - ('\u{2d0f}', 4271), ('\u{2d10}', 4272), ('\u{2d11}', 4273), ('\u{2d12}', 4274), - ('\u{2d13}', 4275), ('\u{2d14}', 4276), ('\u{2d15}', 4277), ('\u{2d16}', 4278), - ('\u{2d17}', 4279), ('\u{2d18}', 4280), ('\u{2d19}', 4281), ('\u{2d1a}', 4282), - ('\u{2d1b}', 4283), ('\u{2d1c}', 4284), ('\u{2d1d}', 4285), ('\u{2d1e}', 4286), - ('\u{2d1f}', 4287), ('\u{2d20}', 4288), ('\u{2d21}', 4289), ('\u{2d22}', 4290), - ('\u{2d23}', 4291), ('\u{2d24}', 4292), ('\u{2d25}', 4293), ('\u{2d27}', 4295), - ('\u{2d2d}', 4301), ('\u{a641}', 42560), ('\u{a643}', 42562), ('\u{a645}', 42564), - ('\u{a647}', 42566), ('\u{a649}', 42568), ('\u{a64b}', 42570), ('\u{a64d}', 42572), - ('\u{a64f}', 42574), ('\u{a651}', 42576), ('\u{a653}', 42578), ('\u{a655}', 42580), - ('\u{a657}', 42582), ('\u{a659}', 42584), ('\u{a65b}', 42586), ('\u{a65d}', 42588), - ('\u{a65f}', 42590), ('\u{a661}', 42592), ('\u{a663}', 42594), ('\u{a665}', 42596), - ('\u{a667}', 42598), ('\u{a669}', 42600), ('\u{a66b}', 42602), ('\u{a66d}', 42604), - ('\u{a681}', 42624), ('\u{a683}', 42626), ('\u{a685}', 42628), ('\u{a687}', 42630), - ('\u{a689}', 42632), ('\u{a68b}', 42634), ('\u{a68d}', 42636), ('\u{a68f}', 42638), - ('\u{a691}', 42640), ('\u{a693}', 42642), ('\u{a695}', 42644), ('\u{a697}', 42646), - ('\u{a699}', 42648), ('\u{a69b}', 42650), ('\u{a723}', 42786), ('\u{a725}', 42788), - ('\u{a727}', 42790), ('\u{a729}', 42792), ('\u{a72b}', 42794), ('\u{a72d}', 42796), - ('\u{a72f}', 42798), ('\u{a733}', 42802), ('\u{a735}', 42804), ('\u{a737}', 42806), - ('\u{a739}', 42808), ('\u{a73b}', 42810), ('\u{a73d}', 42812), ('\u{a73f}', 42814), - ('\u{a741}', 42816), ('\u{a743}', 42818), ('\u{a745}', 42820), ('\u{a747}', 42822), - ('\u{a749}', 42824), ('\u{a74b}', 42826), ('\u{a74d}', 42828), ('\u{a74f}', 42830), - ('\u{a751}', 42832), ('\u{a753}', 42834), ('\u{a755}', 42836), ('\u{a757}', 42838), - ('\u{a759}', 42840), ('\u{a75b}', 42842), ('\u{a75d}', 42844), ('\u{a75f}', 42846), - ('\u{a761}', 42848), ('\u{a763}', 42850), ('\u{a765}', 42852), ('\u{a767}', 42854), - ('\u{a769}', 42856), ('\u{a76b}', 42858), ('\u{a76d}', 42860), ('\u{a76f}', 42862), - ('\u{a77a}', 42873), ('\u{a77c}', 42875), ('\u{a77f}', 42878), ('\u{a781}', 42880), - ('\u{a783}', 42882), ('\u{a785}', 42884), ('\u{a787}', 42886), ('\u{a78c}', 42891), - ('\u{a791}', 42896), ('\u{a793}', 42898), ('\u{a794}', 42948), ('\u{a797}', 42902), - ('\u{a799}', 42904), ('\u{a79b}', 42906), ('\u{a79d}', 42908), ('\u{a79f}', 42910), - ('\u{a7a1}', 42912), ('\u{a7a3}', 42914), ('\u{a7a5}', 42916), ('\u{a7a7}', 42918), - ('\u{a7a9}', 42920), ('\u{a7b5}', 42932), ('\u{a7b7}', 42934), ('\u{a7b9}', 42936), - ('\u{a7bb}', 42938), ('\u{a7bd}', 42940), ('\u{a7bf}', 42942), ('\u{a7c1}', 42944), - ('\u{a7c3}', 42946), ('\u{a7c8}', 42951), ('\u{a7ca}', 42953), ('\u{a7d1}', 42960), - ('\u{a7d7}', 42966), ('\u{a7d9}', 42968), ('\u{a7f6}', 42997), ('\u{ab53}', 42931), - ('\u{ab70}', 5024), ('\u{ab71}', 5025), ('\u{ab72}', 5026), ('\u{ab73}', 5027), - ('\u{ab74}', 5028), ('\u{ab75}', 5029), ('\u{ab76}', 5030), ('\u{ab77}', 5031), - ('\u{ab78}', 5032), ('\u{ab79}', 5033), ('\u{ab7a}', 5034), ('\u{ab7b}', 5035), - ('\u{ab7c}', 5036), ('\u{ab7d}', 5037), ('\u{ab7e}', 5038), ('\u{ab7f}', 5039), - ('\u{ab80}', 5040), ('\u{ab81}', 5041), ('\u{ab82}', 5042), ('\u{ab83}', 5043), - ('\u{ab84}', 5044), ('\u{ab85}', 5045), ('\u{ab86}', 5046), ('\u{ab87}', 5047), - ('\u{ab88}', 5048), ('\u{ab89}', 5049), ('\u{ab8a}', 5050), ('\u{ab8b}', 5051), - ('\u{ab8c}', 5052), ('\u{ab8d}', 5053), ('\u{ab8e}', 5054), ('\u{ab8f}', 5055), - ('\u{ab90}', 5056), ('\u{ab91}', 5057), ('\u{ab92}', 5058), ('\u{ab93}', 5059), - ('\u{ab94}', 5060), ('\u{ab95}', 5061), ('\u{ab96}', 5062), ('\u{ab97}', 5063), - ('\u{ab98}', 5064), ('\u{ab99}', 5065), ('\u{ab9a}', 5066), ('\u{ab9b}', 5067), - ('\u{ab9c}', 5068), ('\u{ab9d}', 5069), ('\u{ab9e}', 5070), ('\u{ab9f}', 5071), - ('\u{aba0}', 5072), ('\u{aba1}', 5073), ('\u{aba2}', 5074), ('\u{aba3}', 5075), - ('\u{aba4}', 5076), ('\u{aba5}', 5077), ('\u{aba6}', 5078), ('\u{aba7}', 5079), - ('\u{aba8}', 5080), ('\u{aba9}', 5081), ('\u{abaa}', 5082), ('\u{abab}', 5083), - ('\u{abac}', 5084), ('\u{abad}', 5085), ('\u{abae}', 5086), ('\u{abaf}', 5087), - ('\u{abb0}', 5088), ('\u{abb1}', 5089), ('\u{abb2}', 5090), ('\u{abb3}', 5091), - ('\u{abb4}', 5092), ('\u{abb5}', 5093), ('\u{abb6}', 5094), ('\u{abb7}', 5095), - ('\u{abb8}', 5096), ('\u{abb9}', 5097), ('\u{abba}', 5098), ('\u{abbb}', 5099), - ('\u{abbc}', 5100), ('\u{abbd}', 5101), ('\u{abbe}', 5102), ('\u{abbf}', 5103), - ('\u{fb00}', 4194394), ('\u{fb01}', 4194395), ('\u{fb02}', 4194396), ('\u{fb03}', 4194397), - ('\u{fb04}', 4194398), ('\u{fb05}', 4194399), ('\u{fb06}', 4194400), ('\u{fb13}', 4194401), - ('\u{fb14}', 4194402), ('\u{fb15}', 4194403), ('\u{fb16}', 4194404), ('\u{fb17}', 4194405), - ('\u{ff41}', 65313), ('\u{ff42}', 65314), ('\u{ff43}', 65315), ('\u{ff44}', 65316), - ('\u{ff45}', 65317), ('\u{ff46}', 65318), ('\u{ff47}', 65319), ('\u{ff48}', 65320), - ('\u{ff49}', 65321), ('\u{ff4a}', 65322), ('\u{ff4b}', 65323), ('\u{ff4c}', 65324), - ('\u{ff4d}', 65325), ('\u{ff4e}', 65326), ('\u{ff4f}', 65327), ('\u{ff50}', 65328), - ('\u{ff51}', 65329), ('\u{ff52}', 65330), ('\u{ff53}', 65331), ('\u{ff54}', 65332), - ('\u{ff55}', 65333), ('\u{ff56}', 65334), ('\u{ff57}', 65335), ('\u{ff58}', 65336), - ('\u{ff59}', 65337), ('\u{ff5a}', 65338), ('\u{10428}', 66560), ('\u{10429}', 66561), - ('\u{1042a}', 66562), ('\u{1042b}', 66563), ('\u{1042c}', 66564), ('\u{1042d}', 66565), - ('\u{1042e}', 66566), ('\u{1042f}', 66567), ('\u{10430}', 66568), ('\u{10431}', 66569), - ('\u{10432}', 66570), ('\u{10433}', 66571), ('\u{10434}', 66572), ('\u{10435}', 66573), - ('\u{10436}', 66574), ('\u{10437}', 66575), ('\u{10438}', 66576), ('\u{10439}', 66577), - ('\u{1043a}', 66578), ('\u{1043b}', 66579), ('\u{1043c}', 66580), ('\u{1043d}', 66581), - ('\u{1043e}', 66582), ('\u{1043f}', 66583), ('\u{10440}', 66584), ('\u{10441}', 66585), - ('\u{10442}', 66586), ('\u{10443}', 66587), ('\u{10444}', 66588), ('\u{10445}', 66589), - ('\u{10446}', 66590), ('\u{10447}', 66591), ('\u{10448}', 66592), ('\u{10449}', 66593), - ('\u{1044a}', 66594), ('\u{1044b}', 66595), ('\u{1044c}', 66596), ('\u{1044d}', 66597), - ('\u{1044e}', 66598), ('\u{1044f}', 66599), ('\u{104d8}', 66736), ('\u{104d9}', 66737), - ('\u{104da}', 66738), ('\u{104db}', 66739), ('\u{104dc}', 66740), ('\u{104dd}', 66741), - ('\u{104de}', 66742), ('\u{104df}', 66743), ('\u{104e0}', 66744), ('\u{104e1}', 66745), - ('\u{104e2}', 66746), ('\u{104e3}', 66747), ('\u{104e4}', 66748), ('\u{104e5}', 66749), - ('\u{104e6}', 66750), ('\u{104e7}', 66751), ('\u{104e8}', 66752), ('\u{104e9}', 66753), - ('\u{104ea}', 66754), ('\u{104eb}', 66755), ('\u{104ec}', 66756), ('\u{104ed}', 66757), - ('\u{104ee}', 66758), ('\u{104ef}', 66759), ('\u{104f0}', 66760), ('\u{104f1}', 66761), - ('\u{104f2}', 66762), ('\u{104f3}', 66763), ('\u{104f4}', 66764), ('\u{104f5}', 66765), - ('\u{104f6}', 66766), ('\u{104f7}', 66767), ('\u{104f8}', 66768), ('\u{104f9}', 66769), - ('\u{104fa}', 66770), ('\u{104fb}', 66771), ('\u{10597}', 66928), ('\u{10598}', 66929), - ('\u{10599}', 66930), ('\u{1059a}', 66931), ('\u{1059b}', 66932), ('\u{1059c}', 66933), - ('\u{1059d}', 66934), ('\u{1059e}', 66935), ('\u{1059f}', 66936), ('\u{105a0}', 66937), - ('\u{105a1}', 66938), ('\u{105a3}', 66940), ('\u{105a4}', 66941), ('\u{105a5}', 66942), - ('\u{105a6}', 66943), ('\u{105a7}', 66944), ('\u{105a8}', 66945), ('\u{105a9}', 66946), - ('\u{105aa}', 66947), ('\u{105ab}', 66948), ('\u{105ac}', 66949), ('\u{105ad}', 66950), - ('\u{105ae}', 66951), ('\u{105af}', 66952), ('\u{105b0}', 66953), ('\u{105b1}', 66954), - ('\u{105b3}', 66956), ('\u{105b4}', 66957), ('\u{105b5}', 66958), ('\u{105b6}', 66959), - ('\u{105b7}', 66960), ('\u{105b8}', 66961), ('\u{105b9}', 66962), ('\u{105bb}', 66964), - ('\u{105bc}', 66965), ('\u{10cc0}', 68736), ('\u{10cc1}', 68737), ('\u{10cc2}', 68738), - ('\u{10cc3}', 68739), ('\u{10cc4}', 68740), ('\u{10cc5}', 68741), ('\u{10cc6}', 68742), - ('\u{10cc7}', 68743), ('\u{10cc8}', 68744), ('\u{10cc9}', 68745), ('\u{10cca}', 68746), - ('\u{10ccb}', 68747), ('\u{10ccc}', 68748), ('\u{10ccd}', 68749), ('\u{10cce}', 68750), - ('\u{10ccf}', 68751), ('\u{10cd0}', 68752), ('\u{10cd1}', 68753), ('\u{10cd2}', 68754), - ('\u{10cd3}', 68755), ('\u{10cd4}', 68756), ('\u{10cd5}', 68757), ('\u{10cd6}', 68758), - ('\u{10cd7}', 68759), ('\u{10cd8}', 68760), ('\u{10cd9}', 68761), ('\u{10cda}', 68762), - ('\u{10cdb}', 68763), ('\u{10cdc}', 68764), ('\u{10cdd}', 68765), ('\u{10cde}', 68766), - ('\u{10cdf}', 68767), ('\u{10ce0}', 68768), ('\u{10ce1}', 68769), ('\u{10ce2}', 68770), - ('\u{10ce3}', 68771), ('\u{10ce4}', 68772), ('\u{10ce5}', 68773), ('\u{10ce6}', 68774), - ('\u{10ce7}', 68775), ('\u{10ce8}', 68776), ('\u{10ce9}', 68777), ('\u{10cea}', 68778), - ('\u{10ceb}', 68779), ('\u{10cec}', 68780), ('\u{10ced}', 68781), ('\u{10cee}', 68782), - ('\u{10cef}', 68783), ('\u{10cf0}', 68784), ('\u{10cf1}', 68785), ('\u{10cf2}', 68786), - ('\u{118c0}', 71840), ('\u{118c1}', 71841), ('\u{118c2}', 71842), ('\u{118c3}', 71843), - ('\u{118c4}', 71844), ('\u{118c5}', 71845), ('\u{118c6}', 71846), ('\u{118c7}', 71847), - ('\u{118c8}', 71848), ('\u{118c9}', 71849), ('\u{118ca}', 71850), ('\u{118cb}', 71851), - ('\u{118cc}', 71852), ('\u{118cd}', 71853), ('\u{118ce}', 71854), ('\u{118cf}', 71855), - ('\u{118d0}', 71856), ('\u{118d1}', 71857), ('\u{118d2}', 71858), ('\u{118d3}', 71859), - ('\u{118d4}', 71860), ('\u{118d5}', 71861), ('\u{118d6}', 71862), ('\u{118d7}', 71863), - ('\u{118d8}', 71864), ('\u{118d9}', 71865), ('\u{118da}', 71866), ('\u{118db}', 71867), - ('\u{118dc}', 71868), ('\u{118dd}', 71869), ('\u{118de}', 71870), ('\u{118df}', 71871), - ('\u{16e60}', 93760), ('\u{16e61}', 93761), ('\u{16e62}', 93762), ('\u{16e63}', 93763), - ('\u{16e64}', 93764), ('\u{16e65}', 93765), ('\u{16e66}', 93766), ('\u{16e67}', 93767), - ('\u{16e68}', 93768), ('\u{16e69}', 93769), ('\u{16e6a}', 93770), ('\u{16e6b}', 93771), - ('\u{16e6c}', 93772), ('\u{16e6d}', 93773), ('\u{16e6e}', 93774), ('\u{16e6f}', 93775), - ('\u{16e70}', 93776), ('\u{16e71}', 93777), ('\u{16e72}', 93778), ('\u{16e73}', 93779), - ('\u{16e74}', 93780), ('\u{16e75}', 93781), ('\u{16e76}', 93782), ('\u{16e77}', 93783), - ('\u{16e78}', 93784), ('\u{16e79}', 93785), ('\u{16e7a}', 93786), ('\u{16e7b}', 93787), - ('\u{16e7c}', 93788), ('\u{16e7d}', 93789), ('\u{16e7e}', 93790), ('\u{16e7f}', 93791), - ('\u{1e922}', 125184), ('\u{1e923}', 125185), ('\u{1e924}', 125186), ('\u{1e925}', 125187), - ('\u{1e926}', 125188), ('\u{1e927}', 125189), ('\u{1e928}', 125190), ('\u{1e929}', 125191), - ('\u{1e92a}', 125192), ('\u{1e92b}', 125193), ('\u{1e92c}', 125194), ('\u{1e92d}', 125195), - ('\u{1e92e}', 125196), ('\u{1e92f}', 125197), ('\u{1e930}', 125198), ('\u{1e931}', 125199), - ('\u{1e932}', 125200), ('\u{1e933}', 125201), ('\u{1e934}', 125202), ('\u{1e935}', 125203), - ('\u{1e936}', 125204), ('\u{1e937}', 125205), ('\u{1e938}', 125206), ('\u{1e939}', 125207), - ('\u{1e93a}', 125208), ('\u{1e93b}', 125209), ('\u{1e93c}', 125210), ('\u{1e93d}', 125211), - ('\u{1e93e}', 125212), ('\u{1e93f}', 125213), ('\u{1e940}', 125214), ('\u{1e941}', 125215), - ('\u{1e942}', 125216), ('\u{1e943}', 125217), - ]; - - static UPPERCASE_TABLE_MULTI: &[[char; 3]] = &[ - ['S', 'S', '\u{0}'], ['\u{2bc}', 'N', '\u{0}'], ['J', '\u{30c}', '\u{0}'], - ['\u{399}', '\u{308}', '\u{301}'], ['\u{3a5}', '\u{308}', '\u{301}'], - ['\u{535}', '\u{552}', '\u{0}'], ['H', '\u{331}', '\u{0}'], ['T', '\u{308}', '\u{0}'], - ['W', '\u{30a}', '\u{0}'], ['Y', '\u{30a}', '\u{0}'], ['A', '\u{2be}', '\u{0}'], - ['\u{3a5}', '\u{313}', '\u{0}'], ['\u{3a5}', '\u{313}', '\u{300}'], - ['\u{3a5}', '\u{313}', '\u{301}'], ['\u{3a5}', '\u{313}', '\u{342}'], - ['\u{1f08}', '\u{399}', '\u{0}'], ['\u{1f09}', '\u{399}', '\u{0}'], - ['\u{1f0a}', '\u{399}', '\u{0}'], ['\u{1f0b}', '\u{399}', '\u{0}'], - ['\u{1f0c}', '\u{399}', '\u{0}'], ['\u{1f0d}', '\u{399}', '\u{0}'], - ['\u{1f0e}', '\u{399}', '\u{0}'], ['\u{1f0f}', '\u{399}', '\u{0}'], - ['\u{1f08}', '\u{399}', '\u{0}'], ['\u{1f09}', '\u{399}', '\u{0}'], - ['\u{1f0a}', '\u{399}', '\u{0}'], ['\u{1f0b}', '\u{399}', '\u{0}'], - ['\u{1f0c}', '\u{399}', '\u{0}'], ['\u{1f0d}', '\u{399}', '\u{0}'], - ['\u{1f0e}', '\u{399}', '\u{0}'], ['\u{1f0f}', '\u{399}', '\u{0}'], - ['\u{1f28}', '\u{399}', '\u{0}'], ['\u{1f29}', '\u{399}', '\u{0}'], - ['\u{1f2a}', '\u{399}', '\u{0}'], ['\u{1f2b}', '\u{399}', '\u{0}'], - ['\u{1f2c}', '\u{399}', '\u{0}'], ['\u{1f2d}', '\u{399}', '\u{0}'], - ['\u{1f2e}', '\u{399}', '\u{0}'], ['\u{1f2f}', '\u{399}', '\u{0}'], - ['\u{1f28}', '\u{399}', '\u{0}'], ['\u{1f29}', '\u{399}', '\u{0}'], - ['\u{1f2a}', '\u{399}', '\u{0}'], ['\u{1f2b}', '\u{399}', '\u{0}'], - ['\u{1f2c}', '\u{399}', '\u{0}'], ['\u{1f2d}', '\u{399}', '\u{0}'], - ['\u{1f2e}', '\u{399}', '\u{0}'], ['\u{1f2f}', '\u{399}', '\u{0}'], - ['\u{1f68}', '\u{399}', '\u{0}'], ['\u{1f69}', '\u{399}', '\u{0}'], - ['\u{1f6a}', '\u{399}', '\u{0}'], ['\u{1f6b}', '\u{399}', '\u{0}'], - ['\u{1f6c}', '\u{399}', '\u{0}'], ['\u{1f6d}', '\u{399}', '\u{0}'], - ['\u{1f6e}', '\u{399}', '\u{0}'], ['\u{1f6f}', '\u{399}', '\u{0}'], - ['\u{1f68}', '\u{399}', '\u{0}'], ['\u{1f69}', '\u{399}', '\u{0}'], - ['\u{1f6a}', '\u{399}', '\u{0}'], ['\u{1f6b}', '\u{399}', '\u{0}'], - ['\u{1f6c}', '\u{399}', '\u{0}'], ['\u{1f6d}', '\u{399}', '\u{0}'], - ['\u{1f6e}', '\u{399}', '\u{0}'], ['\u{1f6f}', '\u{399}', '\u{0}'], - ['\u{1fba}', '\u{399}', '\u{0}'], ['\u{391}', '\u{399}', '\u{0}'], - ['\u{386}', '\u{399}', '\u{0}'], ['\u{391}', '\u{342}', '\u{0}'], - ['\u{391}', '\u{342}', '\u{399}'], ['\u{391}', '\u{399}', '\u{0}'], - ['\u{1fca}', '\u{399}', '\u{0}'], ['\u{397}', '\u{399}', '\u{0}'], - ['\u{389}', '\u{399}', '\u{0}'], ['\u{397}', '\u{342}', '\u{0}'], - ['\u{397}', '\u{342}', '\u{399}'], ['\u{397}', '\u{399}', '\u{0}'], - ['\u{399}', '\u{308}', '\u{300}'], ['\u{399}', '\u{308}', '\u{301}'], - ['\u{399}', '\u{342}', '\u{0}'], ['\u{399}', '\u{308}', '\u{342}'], - ['\u{3a5}', '\u{308}', '\u{300}'], ['\u{3a5}', '\u{308}', '\u{301}'], - ['\u{3a1}', '\u{313}', '\u{0}'], ['\u{3a5}', '\u{342}', '\u{0}'], - ['\u{3a5}', '\u{308}', '\u{342}'], ['\u{1ffa}', '\u{399}', '\u{0}'], - ['\u{3a9}', '\u{399}', '\u{0}'], ['\u{38f}', '\u{399}', '\u{0}'], - ['\u{3a9}', '\u{342}', '\u{0}'], ['\u{3a9}', '\u{342}', '\u{399}'], - ['\u{3a9}', '\u{399}', '\u{0}'], ['F', 'F', '\u{0}'], ['F', 'I', '\u{0}'], - ['F', 'L', '\u{0}'], ['F', 'F', 'I'], ['F', 'F', 'L'], ['S', 'T', '\u{0}'], - ['S', 'T', '\u{0}'], ['\u{544}', '\u{546}', '\u{0}'], ['\u{544}', '\u{535}', '\u{0}'], - ['\u{544}', '\u{53b}', '\u{0}'], ['\u{54e}', '\u{546}', '\u{0}'], - ['\u{544}', '\u{53d}', '\u{0}'], - ]; -} diff --git a/library/core/src/unit.rs b/library/core/src/unit.rs deleted file mode 100644 index d656005f3d42d..0000000000000 --- a/library/core/src/unit.rs +++ /dev/null @@ -1,19 +0,0 @@ -/// Collapses all unit items from an iterator into one. -/// -/// This is more useful when combined with higher-level abstractions, like -/// collecting to a `Result<(), E>` where you only care about errors: -/// -/// ``` -/// use std::io::*; -/// let data = vec![1, 2, 3, 4, 5]; -/// let res: Result<()> = data.iter() -/// .map(|x| writeln!(stdout(), "{x}")) -/// .collect(); -/// assert!(res.is_ok()); -/// ``` -#[stable(feature = "unit_from_iter", since = "1.23.0")] -impl FromIterator<()> for () { - fn from_iter>(iter: I) -> Self { - iter.into_iter().for_each(|()| {}) - } -} diff --git a/library/core/tests/alloc.rs b/library/core/tests/alloc.rs deleted file mode 100644 index b88f1821cd77c..0000000000000 --- a/library/core/tests/alloc.rs +++ /dev/null @@ -1,75 +0,0 @@ -use core::alloc::Layout; -use core::mem::size_of; -use core::ptr::{self, NonNull}; - -#[test] -fn const_unchecked_layout() { - const SIZE: usize = 0x2000; - const ALIGN: usize = 0x1000; - const LAYOUT: Layout = unsafe { Layout::from_size_align_unchecked(SIZE, ALIGN) }; - const DANGLING: NonNull = LAYOUT.dangling(); - assert_eq!(LAYOUT.size(), SIZE); - assert_eq!(LAYOUT.align(), ALIGN); - assert_eq!(Some(DANGLING), NonNull::new(ptr::without_provenance_mut(ALIGN))); -} - -#[test] -fn layout_round_up_to_align_edge_cases() { - const MAX_SIZE: usize = isize::MAX as usize; - - for shift in 0..usize::BITS { - let align = 1_usize << shift; - let edge = (MAX_SIZE + 1) - align; - let low = edge.saturating_sub(10); - let high = edge.saturating_add(10); - assert!(Layout::from_size_align(low, align).is_ok()); - assert!(Layout::from_size_align(high, align).is_err()); - for size in low..=high { - assert_eq!( - Layout::from_size_align(size, align).is_ok(), - size.next_multiple_of(align) <= MAX_SIZE, - ); - } - } -} - -#[test] -fn layout_array_edge_cases() { - for_type::(); - for_type::<[i32; 0b10101]>(); - for_type::<[u8; 0b1010101]>(); - - // Make sure ZSTs don't lead to divide-by-zero - assert_eq!(Layout::array::<()>(usize::MAX).unwrap(), Layout::from_size_align(0, 1).unwrap()); - - fn for_type() { - const MAX_SIZE: usize = isize::MAX as usize; - - let edge = (MAX_SIZE + 1) / size_of::(); - let low = edge.saturating_sub(10); - let high = edge.saturating_add(10); - assert!(Layout::array::(low).is_ok()); - assert!(Layout::array::(high).is_err()); - for n in low..=high { - assert_eq!(Layout::array::(n).is_ok(), n * size_of::() <= MAX_SIZE); - } - } -} - -#[test] -fn layout_debug_shows_log2_of_alignment() { - // `Debug` is not stable, but here's what it does right now - let layout = Layout::from_size_align(24576, 8192).unwrap(); - let s = format!("{:?}", layout); - assert_eq!(s, "Layout { size: 24576, align: 8192 (1 << 13) }"); -} - -// Running this normally doesn't do much, but it's also run in Miri, which -// will double-check that these are allowed by the validity invariants. -#[test] -fn layout_accepts_all_valid_alignments() { - for align in 0..usize::BITS { - let layout = Layout::from_size_align(0, 1_usize << align).unwrap(); - assert_eq!(layout.align(), 1_usize << align); - } -} diff --git a/library/core/tests/any.rs b/library/core/tests/any.rs deleted file mode 100644 index 25002617d0bbd..0000000000000 --- a/library/core/tests/any.rs +++ /dev/null @@ -1,149 +0,0 @@ -use core::any::*; - -#[derive(PartialEq, Debug)] -struct Test; - -static TEST: &'static str = "Test"; - -#[test] -fn any_referenced() { - let (a, b, c) = (&5 as &dyn Any, &TEST as &dyn Any, &Test as &dyn Any); - - assert!(a.is::()); - assert!(!b.is::()); - assert!(!c.is::()); - - assert!(!a.is::<&'static str>()); - assert!(b.is::<&'static str>()); - assert!(!c.is::<&'static str>()); - - assert!(!a.is::()); - assert!(!b.is::()); - assert!(c.is::()); -} - -#[test] -fn any_owning() { - let (a, b, c) = ( - Box::new(5_usize) as Box, - Box::new(TEST) as Box, - Box::new(Test) as Box, - ); - - assert!(a.is::()); - assert!(!b.is::()); - assert!(!c.is::()); - - assert!(!a.is::<&'static str>()); - assert!(b.is::<&'static str>()); - assert!(!c.is::<&'static str>()); - - assert!(!a.is::()); - assert!(!b.is::()); - assert!(c.is::()); -} - -#[test] -fn any_downcast_ref() { - let a = &5_usize as &dyn Any; - - match a.downcast_ref::() { - Some(&5) => {} - x => panic!("Unexpected value {x:?}"), - } - - match a.downcast_ref::() { - None => {} - x => panic!("Unexpected value {x:?}"), - } -} - -#[test] -fn any_downcast_mut() { - let mut a = 5_usize; - let mut b: Box<_> = Box::new(7_usize); - - let a_r = &mut a as &mut dyn Any; - let tmp: &mut usize = &mut *b; - let b_r = tmp as &mut dyn Any; - - match a_r.downcast_mut::() { - Some(x) => { - assert_eq!(*x, 5); - *x = 612; - } - x => panic!("Unexpected value {x:?}"), - } - - match b_r.downcast_mut::() { - Some(x) => { - assert_eq!(*x, 7); - *x = 413; - } - x => panic!("Unexpected value {x:?}"), - } - - match a_r.downcast_mut::() { - None => (), - x => panic!("Unexpected value {x:?}"), - } - - match b_r.downcast_mut::() { - None => (), - x => panic!("Unexpected value {x:?}"), - } - - match a_r.downcast_mut::() { - Some(&mut 612) => {} - x => panic!("Unexpected value {x:?}"), - } - - match b_r.downcast_mut::() { - Some(&mut 413) => {} - x => panic!("Unexpected value {x:?}"), - } -} - -#[test] -fn any_fixed_vec() { - let test = [0_usize; 8]; - let test = &test as &dyn Any; - assert!(test.is::<[usize; 8]>()); - assert!(!test.is::<[usize; 10]>()); -} - -#[test] -fn any_unsized() { - fn is_any() {} - is_any::<[i32]>(); -} - -#[test] -fn distinct_type_names() { - // https://github.com/rust-lang/rust/issues/84666 - - struct Velocity(#[allow(dead_code)] f32, #[allow(dead_code)] f32); - - fn type_name_of_val(_: T) -> &'static str { - type_name::() - } - - assert_ne!(type_name_of_val(Velocity), type_name_of_val(Velocity(0.0, -9.8)),); -} - -#[test] -fn dyn_type_name() { - trait Foo { - type Bar; - } - - assert_eq!( - "dyn core::ops::function::Fn(i32, i32) -> i32", - std::any::type_name:: i32>() - ); - assert_eq!( - "dyn coretests::any::dyn_type_name::Foo \ - + core::marker::Send + core::marker::Sync", - std::any::type_name:: + Send + Sync>() - ); -} diff --git a/library/core/tests/array.rs b/library/core/tests/array.rs deleted file mode 100644 index e7773d138c255..0000000000000 --- a/library/core/tests/array.rs +++ /dev/null @@ -1,718 +0,0 @@ -use core::num::NonZero; -use core::sync::atomic::{AtomicUsize, Ordering}; -use core::{array, assert_eq}; - -#[test] -fn array_from_ref() { - let value: String = "Hello World!".into(); - let arr: &[String; 1] = array::from_ref(&value); - assert_eq!(&[value.clone()], arr); - - const VALUE: &&str = &"Hello World!"; - const ARR: &[&str; 1] = array::from_ref(VALUE); - assert_eq!(&[*VALUE], ARR); - assert!(core::ptr::eq(VALUE, &ARR[0])); -} - -#[test] -fn array_from_mut() { - let mut value: String = "Hello World".into(); - let arr: &mut [String; 1] = array::from_mut(&mut value); - arr[0].push_str("!"); - assert_eq!(&value, "Hello World!"); -} - -#[test] -fn array_try_from() { - macro_rules! test { - ($($N:expr)+) => { - $({ - type Array = [u8; $N]; - let mut array: Array = [0; $N]; - let slice: &[u8] = &array[..]; - - let result = <&Array>::try_from(slice); - assert_eq!(&array, result.unwrap()); - - let result = ::try_from(slice); - assert_eq!(&array, &result.unwrap()); - - let mut_slice: &mut [u8] = &mut array[..]; - let result = <&mut Array>::try_from(mut_slice); - assert_eq!(&[0; $N], result.unwrap()); - - let mut_slice: &mut [u8] = &mut array[..]; - let result = ::try_from(mut_slice); - assert_eq!(&array, &result.unwrap()); - })+ - } - } - test! { - 0 1 2 3 4 5 6 7 8 9 - 10 11 12 13 14 15 16 17 18 19 - 20 21 22 23 24 25 26 27 28 29 - 30 31 32 - } -} - -#[test] -fn iterator_collect() { - let arr = [0, 1, 2, 5, 9]; - let v: Vec<_> = IntoIterator::into_iter(arr.clone()).collect(); - assert_eq!(&arr[..], &v[..]); -} - -#[test] -fn iterator_rev_collect() { - let arr = [0, 1, 2, 5, 9]; - let v: Vec<_> = IntoIterator::into_iter(arr.clone()).rev().collect(); - assert_eq!(&v[..], &[9, 5, 2, 1, 0]); -} - -#[test] -fn iterator_nth() { - let v = [0, 1, 2, 3, 4]; - for i in 0..v.len() { - assert_eq!(IntoIterator::into_iter(v.clone()).nth(i).unwrap(), v[i]); - } - assert_eq!(IntoIterator::into_iter(v.clone()).nth(v.len()), None); - - let mut iter = IntoIterator::into_iter(v); - assert_eq!(iter.nth(2).unwrap(), v[2]); - assert_eq!(iter.nth(1).unwrap(), v[4]); -} - -#[test] -fn iterator_last() { - let v = [0, 1, 2, 3, 4]; - assert_eq!(IntoIterator::into_iter(v).last().unwrap(), 4); - assert_eq!(IntoIterator::into_iter([0]).last().unwrap(), 0); - - let mut it = IntoIterator::into_iter([0, 9, 2, 4]); - assert_eq!(it.next_back(), Some(4)); - assert_eq!(it.last(), Some(2)); -} - -#[test] -fn iterator_clone() { - let mut it = IntoIterator::into_iter([0, 2, 4, 6, 8]); - assert_eq!(it.next(), Some(0)); - assert_eq!(it.next_back(), Some(8)); - let mut clone = it.clone(); - assert_eq!(it.next_back(), Some(6)); - assert_eq!(clone.next_back(), Some(6)); - assert_eq!(it.next_back(), Some(4)); - assert_eq!(clone.next_back(), Some(4)); - assert_eq!(it.next(), Some(2)); - assert_eq!(clone.next(), Some(2)); -} - -#[test] -fn iterator_fused() { - let mut it = IntoIterator::into_iter([0, 9, 2]); - assert_eq!(it.next(), Some(0)); - assert_eq!(it.next(), Some(9)); - assert_eq!(it.next(), Some(2)); - assert_eq!(it.next(), None); - assert_eq!(it.next(), None); - assert_eq!(it.next(), None); - assert_eq!(it.next(), None); - assert_eq!(it.next(), None); -} - -#[test] -fn iterator_len() { - let mut it = IntoIterator::into_iter([0, 1, 2, 5, 9]); - assert_eq!(it.size_hint(), (5, Some(5))); - assert_eq!(it.len(), 5); - assert_eq!(it.is_empty(), false); - - assert_eq!(it.next(), Some(0)); - assert_eq!(it.size_hint(), (4, Some(4))); - assert_eq!(it.len(), 4); - assert_eq!(it.is_empty(), false); - - assert_eq!(it.next_back(), Some(9)); - assert_eq!(it.size_hint(), (3, Some(3))); - assert_eq!(it.len(), 3); - assert_eq!(it.is_empty(), false); - - // Empty - let it = IntoIterator::into_iter([] as [String; 0]); - assert_eq!(it.size_hint(), (0, Some(0))); - assert_eq!(it.len(), 0); - assert_eq!(it.is_empty(), true); -} - -#[test] -fn iterator_count() { - let v = [0, 1, 2, 3, 4]; - assert_eq!(IntoIterator::into_iter(v.clone()).count(), 5); - - let mut iter2 = IntoIterator::into_iter(v); - iter2.next(); - iter2.next(); - assert_eq!(iter2.count(), 3); -} - -#[test] -fn iterator_flat_map() { - assert!((0..5).flat_map(|i| IntoIterator::into_iter([2 * i, 2 * i + 1])).eq(0..10)); -} - -#[test] -fn iterator_debug() { - let arr = [0, 1, 2, 5, 9]; - assert_eq!(format!("{:?}", IntoIterator::into_iter(arr)), "IntoIter([0, 1, 2, 5, 9])",); -} - -#[test] -fn iterator_drops() { - use core::cell::Cell; - - // This test makes sure the correct number of elements are dropped. The `R` - // type is just a reference to a `Cell` that is incremented when an `R` is - // dropped. - - #[derive(Clone)] - struct Foo<'a>(&'a Cell); - - impl Drop for Foo<'_> { - fn drop(&mut self) { - self.0.set(self.0.get() + 1); - } - } - - fn five(i: &Cell) -> [Foo<'_>; 5] { - // This is somewhat verbose because `Foo` does not implement `Copy` - // since it implements `Drop`. Consequently, we cannot write - // `[Foo(i); 5]`. - [Foo(i), Foo(i), Foo(i), Foo(i), Foo(i)] - } - - // Simple: drop new iterator. - let i = Cell::new(0); - { - IntoIterator::into_iter(five(&i)); - } - assert_eq!(i.get(), 5); - - // Call `next()` once. - let i = Cell::new(0); - { - let mut iter = IntoIterator::into_iter(five(&i)); - let _x = iter.next(); - assert_eq!(i.get(), 0); - assert_eq!(iter.count(), 4); - assert_eq!(i.get(), 4); - } - assert_eq!(i.get(), 5); - - // Check `clone` and calling `next`/`next_back`. - let i = Cell::new(0); - { - let mut iter = IntoIterator::into_iter(five(&i)); - iter.next(); - assert_eq!(i.get(), 1); - iter.next_back(); - assert_eq!(i.get(), 2); - - let mut clone = iter.clone(); - assert_eq!(i.get(), 2); - - iter.next(); - assert_eq!(i.get(), 3); - - clone.next(); - assert_eq!(i.get(), 4); - - assert_eq!(clone.count(), 2); - assert_eq!(i.get(), 6); - } - assert_eq!(i.get(), 8); - - // Check via `nth`. - let i = Cell::new(0); - { - let mut iter = IntoIterator::into_iter(five(&i)); - let _x = iter.nth(2); - assert_eq!(i.get(), 2); - let _y = iter.last(); - assert_eq!(i.get(), 3); - } - assert_eq!(i.get(), 5); - - // Check every element. - let i = Cell::new(0); - for (index, _x) in IntoIterator::into_iter(five(&i)).enumerate() { - assert_eq!(i.get(), index); - } - assert_eq!(i.get(), 5); - - let i = Cell::new(0); - for (index, _x) in IntoIterator::into_iter(five(&i)).rev().enumerate() { - assert_eq!(i.get(), index); - } - assert_eq!(i.get(), 5); -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn array_default_impl_avoids_leaks_on_panic() { - use core::sync::atomic::{AtomicUsize, Ordering::Relaxed}; - static COUNTER: AtomicUsize = AtomicUsize::new(0); - #[derive(Debug)] - struct Bomb(#[allow(dead_code)] usize); - - impl Default for Bomb { - fn default() -> Bomb { - if COUNTER.load(Relaxed) == 3 { - panic!("bomb limit exceeded"); - } - - COUNTER.fetch_add(1, Relaxed); - Bomb(COUNTER.load(Relaxed)) - } - } - - impl Drop for Bomb { - fn drop(&mut self) { - COUNTER.fetch_sub(1, Relaxed); - } - } - - let res = std::panic::catch_unwind(|| <[Bomb; 5]>::default()); - let panic_msg = match res { - Ok(_) => unreachable!(), - Err(p) => p.downcast::<&'static str>().unwrap(), - }; - assert_eq!(*panic_msg, "bomb limit exceeded"); - // check that all bombs are successfully dropped - assert_eq!(COUNTER.load(Relaxed), 0); -} - -#[test] -fn empty_array_is_always_default() { - struct DoesNotImplDefault; - - let _arr = <[DoesNotImplDefault; 0]>::default(); -} - -#[test] -fn array_map() { - let a = [1, 2, 3]; - let b = a.map(|v| v + 1); - assert_eq!(b, [2, 3, 4]); - - let a = [1u8, 2, 3]; - let b = a.map(|v| v as u64); - assert_eq!(b, [1, 2, 3]); -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn array_map_drop_safety() { - static DROPPED: AtomicUsize = AtomicUsize::new(0); - struct DropCounter; - impl Drop for DropCounter { - fn drop(&mut self) { - DROPPED.fetch_add(1, Ordering::SeqCst); - } - } - - let num_to_create = 5; - let success = std::panic::catch_unwind(|| { - let items = [0; 10]; - let mut nth = 0; - items.map(|_| { - assert!(nth < num_to_create); - nth += 1; - DropCounter - }); - }); - assert!(success.is_err()); - assert_eq!(DROPPED.load(Ordering::SeqCst), num_to_create); -} - -#[test] -fn cell_allows_array_cycle() { - use core::cell::Cell; - - #[derive(Debug)] - struct B<'a> { - a: [Cell>>; 2], - } - - impl<'a> B<'a> { - fn new() -> B<'a> { - B { a: [Cell::new(None), Cell::new(None)] } - } - } - - let b1 = B::new(); - let b2 = B::new(); - let b3 = B::new(); - - b1.a[0].set(Some(&b2)); - b1.a[1].set(Some(&b3)); - - b2.a[0].set(Some(&b2)); - b2.a[1].set(Some(&b3)); - - b3.a[0].set(Some(&b1)); - b3.a[1].set(Some(&b2)); -} - -#[test] -fn array_from_fn() { - let array = core::array::from_fn(|idx| idx); - assert_eq!(array, [0, 1, 2, 3, 4]); -} - -#[test] -fn array_try_from_fn() { - #[derive(Debug, PartialEq)] - enum SomeError { - Foo, - } - - let array = core::array::try_from_fn(|i| Ok::<_, SomeError>(i)); - assert_eq!(array, Ok([0, 1, 2, 3, 4])); - - let another_array = core::array::try_from_fn::, 2, _>(|_| Err(SomeError::Foo)); - assert_eq!(another_array, Err(SomeError::Foo)); -} - -#[cfg(not(panic = "abort"))] -#[test] -fn array_try_from_fn_drops_inserted_elements_on_err() { - static DROP_COUNTER: AtomicUsize = AtomicUsize::new(0); - - struct CountDrop; - impl Drop for CountDrop { - fn drop(&mut self) { - DROP_COUNTER.fetch_add(1, Ordering::SeqCst); - } - } - - let _ = catch_unwind_silent(move || { - let _: Result<[CountDrop; 4], ()> = core::array::try_from_fn(|idx| { - if idx == 2 { - return Err(()); - } - Ok(CountDrop) - }); - }); - - assert_eq!(DROP_COUNTER.load(Ordering::SeqCst), 2); -} - -#[cfg(not(panic = "abort"))] -#[test] -fn array_try_from_fn_drops_inserted_elements_on_panic() { - static DROP_COUNTER: AtomicUsize = AtomicUsize::new(0); - - struct CountDrop; - impl Drop for CountDrop { - fn drop(&mut self) { - DROP_COUNTER.fetch_add(1, Ordering::SeqCst); - } - } - - let _ = catch_unwind_silent(move || { - let _: Result<[CountDrop; 4], ()> = core::array::try_from_fn(|idx| { - if idx == 2 { - panic!("peek a boo"); - } - Ok(CountDrop) - }); - }); - - assert_eq!(DROP_COUNTER.load(Ordering::SeqCst), 2); -} - -#[cfg(not(panic = "abort"))] -// https://stackoverflow.com/a/59211505 -fn catch_unwind_silent(f: F) -> std::thread::Result -where - F: FnOnce() -> R + core::panic::UnwindSafe, -{ - let prev_hook = std::panic::take_hook(); - std::panic::set_hook(Box::new(|_| {})); - let result = std::panic::catch_unwind(f); - std::panic::set_hook(prev_hook); - result -} - -#[test] -fn array_split_array_mut() { - let mut v = [1, 2, 3, 4, 5, 6]; - - { - let (left, right) = v.split_array_mut::<0>(); - assert_eq!(left, &mut []); - assert_eq!(right, &mut [1, 2, 3, 4, 5, 6]); - } - - { - let (left, right) = v.split_array_mut::<6>(); - assert_eq!(left, &mut [1, 2, 3, 4, 5, 6]); - assert_eq!(right, &mut []); - } -} - -#[test] -fn array_rsplit_array_mut() { - let mut v = [1, 2, 3, 4, 5, 6]; - - { - let (left, right) = v.rsplit_array_mut::<0>(); - assert_eq!(left, &mut [1, 2, 3, 4, 5, 6]); - assert_eq!(right, &mut []); - } - - { - let (left, right) = v.rsplit_array_mut::<6>(); - assert_eq!(left, &mut []); - assert_eq!(right, &mut [1, 2, 3, 4, 5, 6]); - } -} - -#[should_panic] -#[test] -fn array_split_array_ref_out_of_bounds() { - let v = [1, 2, 3, 4, 5, 6]; - - v.split_array_ref::<7>(); -} - -#[should_panic] -#[test] -fn array_split_array_mut_out_of_bounds() { - let mut v = [1, 2, 3, 4, 5, 6]; - - v.split_array_mut::<7>(); -} - -#[should_panic] -#[test] -fn array_rsplit_array_ref_out_of_bounds() { - let v = [1, 2, 3, 4, 5, 6]; - - v.rsplit_array_ref::<7>(); -} - -#[should_panic] -#[test] -fn array_rsplit_array_mut_out_of_bounds() { - let mut v = [1, 2, 3, 4, 5, 6]; - - v.rsplit_array_mut::<7>(); -} - -#[test] -fn array_intoiter_advance_by() { - use std::cell::Cell; - struct DropCounter<'a>(usize, &'a Cell); - impl Drop for DropCounter<'_> { - fn drop(&mut self) { - let x = self.1.get(); - self.1.set(x + 1); - } - } - - let counter = Cell::new(0); - let a: [_; 100] = std::array::from_fn(|i| DropCounter(i, &counter)); - let mut it = IntoIterator::into_iter(a); - - let r = it.advance_by(1); - assert_eq!(r, Ok(())); - assert_eq!(it.len(), 99); - assert_eq!(counter.get(), 1); - - let r = it.advance_by(0); - assert_eq!(r, Ok(())); - assert_eq!(it.len(), 99); - assert_eq!(counter.get(), 1); - - let r = it.advance_by(11); - assert_eq!(r, Ok(())); - assert_eq!(it.len(), 88); - assert_eq!(counter.get(), 12); - - let x = it.next(); - assert_eq!(x.as_ref().map(|x| x.0), Some(12)); - assert_eq!(it.len(), 87); - assert_eq!(counter.get(), 12); - drop(x); - assert_eq!(counter.get(), 13); - - let r = it.advance_by(123456); - assert_eq!(r, Err(NonZero::new(123456 - 87).unwrap())); - assert_eq!(it.len(), 0); - assert_eq!(counter.get(), 100); - - let r = it.advance_by(0); - assert_eq!(r, Ok(())); - assert_eq!(it.len(), 0); - assert_eq!(counter.get(), 100); - - let r = it.advance_by(10); - assert_eq!(r, Err(NonZero::new(10).unwrap())); - assert_eq!(it.len(), 0); - assert_eq!(counter.get(), 100); -} - -#[test] -fn array_intoiter_advance_back_by() { - use std::cell::Cell; - struct DropCounter<'a>(usize, &'a Cell); - impl Drop for DropCounter<'_> { - fn drop(&mut self) { - let x = self.1.get(); - self.1.set(x + 1); - } - } - - let counter = Cell::new(0); - let a: [_; 100] = std::array::from_fn(|i| DropCounter(i, &counter)); - let mut it = IntoIterator::into_iter(a); - - let r = it.advance_back_by(1); - assert_eq!(r, Ok(())); - assert_eq!(it.len(), 99); - assert_eq!(counter.get(), 1); - - let r = it.advance_back_by(0); - assert_eq!(r, Ok(())); - assert_eq!(it.len(), 99); - assert_eq!(counter.get(), 1); - - let r = it.advance_back_by(11); - assert_eq!(r, Ok(())); - assert_eq!(it.len(), 88); - assert_eq!(counter.get(), 12); - - let x = it.next_back(); - assert_eq!(x.as_ref().map(|x| x.0), Some(87)); - assert_eq!(it.len(), 87); - assert_eq!(counter.get(), 12); - drop(x); - assert_eq!(counter.get(), 13); - - let r = it.advance_back_by(123456); - assert_eq!(r, Err(NonZero::new(123456 - 87).unwrap())); - assert_eq!(it.len(), 0); - assert_eq!(counter.get(), 100); - - let r = it.advance_back_by(0); - assert_eq!(r, Ok(())); - assert_eq!(it.len(), 0); - assert_eq!(counter.get(), 100); - - let r = it.advance_back_by(10); - assert_eq!(r, Err(NonZero::new(10).unwrap())); - assert_eq!(it.len(), 0); - assert_eq!(counter.get(), 100); -} - -#[test] -fn array_mixed_equality_integers() { - let array3: [i32; 3] = [1, 2, 3]; - let array3b: [i32; 3] = [3, 2, 1]; - let array4: [i32; 4] = [1, 2, 3, 4]; - - let slice3: &[i32] = &{ array3 }; - let slice3b: &[i32] = &{ array3b }; - let slice4: &[i32] = &{ array4 }; - assert!(array3 == slice3); - assert!(array3 != slice3b); - assert!(array3 != slice4); - assert!(slice3 == array3); - assert!(slice3b != array3); - assert!(slice4 != array3); - - let mut3: &mut [i32] = &mut { array3 }; - let mut3b: &mut [i32] = &mut { array3b }; - let mut4: &mut [i32] = &mut { array4 }; - assert!(array3 == mut3); - assert!(array3 != mut3b); - assert!(array3 != mut4); - assert!(mut3 == array3); - assert!(mut3b != array3); - assert!(mut4 != array3); -} - -#[test] -fn array_mixed_equality_nans() { - let array3: [f32; 3] = [1.0, std::f32::NAN, 3.0]; - - let slice3: &[f32] = &{ array3 }; - assert!(!(array3 == slice3)); - assert!(array3 != slice3); - assert!(!(slice3 == array3)); - assert!(slice3 != array3); - - let mut3: &mut [f32] = &mut { array3 }; - assert!(!(array3 == mut3)); - assert!(array3 != mut3); - assert!(!(mut3 == array3)); - assert!(mut3 != array3); -} - -#[test] -fn array_into_iter_fold() { - // Strings to help Miri catch if we double-free or something - let a = ["Aa".to_string(), "Bb".to_string(), "Cc".to_string()]; - let mut s = "s".to_string(); - a.into_iter().for_each(|b| s += &b); - assert_eq!(s, "sAaBbCc"); - - let a = [1, 2, 3, 4, 5, 6]; - let mut it = a.into_iter(); - assert_eq!(it.advance_by(1), Ok(())); - assert_eq!(it.advance_back_by(2), Ok(())); - let s = it.fold(10, |a, b| 10 * a + b); - assert_eq!(s, 10234); -} - -#[test] -fn array_into_iter_rfold() { - // Strings to help Miri catch if we double-free or something - let a = ["Aa".to_string(), "Bb".to_string(), "Cc".to_string()]; - let mut s = "s".to_string(); - a.into_iter().rev().for_each(|b| s += &b); - assert_eq!(s, "sCcBbAa"); - - let a = [1, 2, 3, 4, 5, 6]; - let mut it = a.into_iter(); - assert_eq!(it.advance_by(1), Ok(())); - assert_eq!(it.advance_back_by(2), Ok(())); - let s = it.rfold(10, |a, b| 10 * a + b); - assert_eq!(s, 10432); -} - -#[cfg(not(panic = "abort"))] -#[test] -fn array_map_drops_unmapped_elements_on_panic() { - struct DropCounter<'a>(usize, &'a AtomicUsize); - impl Drop for DropCounter<'_> { - fn drop(&mut self) { - self.1.fetch_add(1, Ordering::SeqCst); - } - } - - const MAX: usize = 11; - for panic_after in 0..MAX { - let counter = AtomicUsize::new(0); - let a = array::from_fn::<_, 11, _>(|i| DropCounter(i, &counter)); - let success = std::panic::catch_unwind(|| { - let _ = a.map(|x| { - assert!(x.0 < panic_after); - assert_eq!(counter.load(Ordering::SeqCst), x.0); - }); - }); - assert!(success.is_err()); - assert_eq!(counter.load(Ordering::SeqCst), MAX); - } -} diff --git a/library/core/tests/ascii.rs b/library/core/tests/ascii.rs deleted file mode 100644 index 3d3f8ac10c603..0000000000000 --- a/library/core/tests/ascii.rs +++ /dev/null @@ -1,491 +0,0 @@ -use core::char::from_u32; - -#[test] -fn test_is_ascii() { - assert!(b"".is_ascii()); - assert!(b"banana\0\x7F".is_ascii()); - assert!(b"banana\0\x7F".iter().all(|b| b.is_ascii())); - assert!(!b"Vi\xe1\xbb\x87t Nam".is_ascii()); - assert!(!b"Vi\xe1\xbb\x87t Nam".iter().all(|b| b.is_ascii())); - assert!(!b"\xe1\xbb\x87".iter().any(|b| b.is_ascii())); - - assert!("".is_ascii()); - assert!("banana\0\u{7F}".is_ascii()); - assert!("banana\0\u{7F}".chars().all(|c| c.is_ascii())); - assert!(!"ประเทศไทย中华Việt Nam".chars().all(|c| c.is_ascii())); - assert!(!"ประเทศไทย中华ệ ".chars().any(|c| c.is_ascii())); -} - -#[test] -fn test_to_ascii_uppercase() { - assert_eq!("url()URL()uRl()ürl".to_ascii_uppercase(), "URL()URL()URL()üRL"); - assert_eq!("hıKß".to_ascii_uppercase(), "HıKß"); - - for i in 0..501 { - let upper = - if 'a' as u32 <= i && i <= 'z' as u32 { i + 'A' as u32 - 'a' as u32 } else { i }; - assert_eq!( - (from_u32(i).unwrap()).to_string().to_ascii_uppercase(), - (from_u32(upper).unwrap()).to_string() - ); - } -} - -#[test] -fn test_to_ascii_lowercase() { - assert_eq!("url()URL()uRl()Ürl".to_ascii_lowercase(), "url()url()url()Ürl"); - // Dotted capital I, Kelvin sign, Sharp S. - assert_eq!("HİKß".to_ascii_lowercase(), "hİKß"); - - for i in 0..501 { - let lower = - if 'A' as u32 <= i && i <= 'Z' as u32 { i + 'a' as u32 - 'A' as u32 } else { i }; - assert_eq!( - (from_u32(i).unwrap()).to_string().to_ascii_lowercase(), - (from_u32(lower).unwrap()).to_string() - ); - } -} - -#[test] -fn test_make_ascii_lower_case() { - macro_rules! test { - ($from: expr, $to: expr) => {{ - let mut x = $from; - x.make_ascii_lowercase(); - assert_eq!(x, $to); - }}; - } - test!(b'A', b'a'); - test!(b'a', b'a'); - test!(b'!', b'!'); - test!('A', 'a'); - test!('À', 'À'); - test!('a', 'a'); - test!('!', '!'); - test!(b"H\xc3\x89".to_vec(), b"h\xc3\x89"); - test!("HİKß".to_string(), "hİKß"); -} - -#[test] -fn test_make_ascii_upper_case() { - macro_rules! test { - ($from: expr, $to: expr) => {{ - let mut x = $from; - x.make_ascii_uppercase(); - assert_eq!(x, $to); - }}; - } - test!(b'a', b'A'); - test!(b'A', b'A'); - test!(b'!', b'!'); - test!('a', 'A'); - test!('à', 'à'); - test!('A', 'A'); - test!('!', '!'); - test!(b"h\xc3\xa9".to_vec(), b"H\xc3\xa9"); - test!("hıKß".to_string(), "HıKß"); - - let mut x = "Hello".to_string(); - x[..3].make_ascii_uppercase(); // Test IndexMut on String. - assert_eq!(x, "HELlo") -} - -#[test] -fn test_eq_ignore_ascii_case() { - assert!("url()URL()uRl()Ürl".eq_ignore_ascii_case("url()url()url()Ürl")); - assert!(!"Ürl".eq_ignore_ascii_case("ürl")); - // Dotted capital I, Kelvin sign, Sharp S. - assert!("HİKß".eq_ignore_ascii_case("hİKß")); - assert!(!"İ".eq_ignore_ascii_case("i")); - assert!(!"K".eq_ignore_ascii_case("k")); - assert!(!"ß".eq_ignore_ascii_case("s")); - - for i in 0..501 { - let lower = - if 'A' as u32 <= i && i <= 'Z' as u32 { i + 'a' as u32 - 'A' as u32 } else { i }; - assert!( - (from_u32(i).unwrap()) - .to_string() - .eq_ignore_ascii_case(&from_u32(lower).unwrap().to_string()) - ); - } -} - -#[test] -fn inference_works() { - let x = "a".to_string(); - let _ = x.eq_ignore_ascii_case("A"); -} - -// Shorthands used by the is_ascii_* tests. -macro_rules! assert_all { - ($what:ident, $($str:tt),+) => {{ - $( - for b in $str.chars() { - if !b.$what() { - panic!("expected {}({}) but it isn't", - stringify!($what), b); - } - } - for b in $str.as_bytes().iter() { - if !b.$what() { - panic!("expected {}(0x{:02x})) but it isn't", - stringify!($what), b); - } - } - )+ - }}; - ($what:ident, $($str:tt),+,) => (assert_all!($what,$($str),+)) -} -macro_rules! assert_none { - ($what:ident, $($str:tt),+) => {{ - $( - for b in $str.chars() { - if b.$what() { - panic!("expected not-{}({}) but it is", - stringify!($what), b); - } - } - for b in $str.as_bytes().iter() { - if b.$what() { - panic!("expected not-{}(0x{:02x})) but it is", - stringify!($what), b); - } - } - )+ - }}; - ($what:ident, $($str:tt),+,) => (assert_none!($what,$($str),+)) -} - -#[test] -fn test_is_ascii_alphabetic() { - assert_all!( - is_ascii_alphabetic, - "", - "abcdefghijklmnopqrstuvwxyz", - "ABCDEFGHIJKLMNOQPRSTUVWXYZ", - ); - assert_none!( - is_ascii_alphabetic, - "0123456789", - "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~", - " \t\n\x0c\r", - "\x00\x01\x02\x03\x04\x05\x06\x07", - "\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f", - "\x10\x11\x12\x13\x14\x15\x16\x17", - "\x18\x19\x1a\x1b\x1c\x1d\x1e\x1f", - "\x7f", - ); -} - -#[test] -fn test_is_ascii_uppercase() { - assert_all!(is_ascii_uppercase, "", "ABCDEFGHIJKLMNOQPRSTUVWXYZ",); - assert_none!( - is_ascii_uppercase, - "abcdefghijklmnopqrstuvwxyz", - "0123456789", - "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~", - " \t\n\x0c\r", - "\x00\x01\x02\x03\x04\x05\x06\x07", - "\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f", - "\x10\x11\x12\x13\x14\x15\x16\x17", - "\x18\x19\x1a\x1b\x1c\x1d\x1e\x1f", - "\x7f", - ); -} - -#[test] -fn test_is_ascii_lowercase() { - assert_all!(is_ascii_lowercase, "abcdefghijklmnopqrstuvwxyz",); - assert_none!( - is_ascii_lowercase, - "ABCDEFGHIJKLMNOQPRSTUVWXYZ", - "0123456789", - "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~", - " \t\n\x0c\r", - "\x00\x01\x02\x03\x04\x05\x06\x07", - "\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f", - "\x10\x11\x12\x13\x14\x15\x16\x17", - "\x18\x19\x1a\x1b\x1c\x1d\x1e\x1f", - "\x7f", - ); -} - -#[test] -fn test_is_ascii_alphanumeric() { - assert_all!( - is_ascii_alphanumeric, - "", - "abcdefghijklmnopqrstuvwxyz", - "ABCDEFGHIJKLMNOQPRSTUVWXYZ", - "0123456789", - ); - assert_none!( - is_ascii_alphanumeric, - "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~", - " \t\n\x0c\r", - "\x00\x01\x02\x03\x04\x05\x06\x07", - "\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f", - "\x10\x11\x12\x13\x14\x15\x16\x17", - "\x18\x19\x1a\x1b\x1c\x1d\x1e\x1f", - "\x7f", - ); -} - -#[test] -fn test_is_ascii_digit() { - assert_all!(is_ascii_digit, "", "0123456789",); - assert_none!( - is_ascii_digit, - "abcdefghijklmnopqrstuvwxyz", - "ABCDEFGHIJKLMNOQPRSTUVWXYZ", - "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~", - " \t\n\x0c\r", - "\x00\x01\x02\x03\x04\x05\x06\x07", - "\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f", - "\x10\x11\x12\x13\x14\x15\x16\x17", - "\x18\x19\x1a\x1b\x1c\x1d\x1e\x1f", - "\x7f", - ); -} - -#[test] -fn test_is_ascii_octdigit() { - assert_all!(is_ascii_octdigit, "", "01234567"); - assert_none!( - is_ascii_octdigit, - "abcdefghijklmnopqrstuvwxyz", - "ABCDEFGHIJKLMNOQPRSTUVWXYZ", - "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~", - " \t\n\x0c\r", - "\x00\x01\x02\x03\x04\x05\x06\x07", - "\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f", - "\x10\x11\x12\x13\x14\x15\x16\x17", - "\x18\x19\x1a\x1b\x1c\x1d\x1e\x1f", - "\x7f", - ); -} - -#[test] -fn test_is_ascii_hexdigit() { - assert_all!(is_ascii_hexdigit, "", "0123456789", "abcdefABCDEF",); - assert_none!( - is_ascii_hexdigit, - "ghijklmnopqrstuvwxyz", - "GHIJKLMNOQPRSTUVWXYZ", - "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~", - " \t\n\x0c\r", - "\x00\x01\x02\x03\x04\x05\x06\x07", - "\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f", - "\x10\x11\x12\x13\x14\x15\x16\x17", - "\x18\x19\x1a\x1b\x1c\x1d\x1e\x1f", - "\x7f", - ); -} - -#[test] -fn test_is_ascii_punctuation() { - assert_all!(is_ascii_punctuation, "", "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~",); - assert_none!( - is_ascii_punctuation, - "abcdefghijklmnopqrstuvwxyz", - "ABCDEFGHIJKLMNOQPRSTUVWXYZ", - "0123456789", - " \t\n\x0c\r", - "\x00\x01\x02\x03\x04\x05\x06\x07", - "\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f", - "\x10\x11\x12\x13\x14\x15\x16\x17", - "\x18\x19\x1a\x1b\x1c\x1d\x1e\x1f", - "\x7f", - ); -} - -#[test] -fn test_is_ascii_graphic() { - assert_all!( - is_ascii_graphic, - "", - "abcdefghijklmnopqrstuvwxyz", - "ABCDEFGHIJKLMNOQPRSTUVWXYZ", - "0123456789", - "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~", - ); - assert_none!( - is_ascii_graphic, - " \t\n\x0c\r", - "\x00\x01\x02\x03\x04\x05\x06\x07", - "\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f", - "\x10\x11\x12\x13\x14\x15\x16\x17", - "\x18\x19\x1a\x1b\x1c\x1d\x1e\x1f", - "\x7f", - ); -} - -#[test] -fn test_is_ascii_whitespace() { - assert_all!(is_ascii_whitespace, "", " \t\n\x0c\r",); - assert_none!( - is_ascii_whitespace, - "abcdefghijklmnopqrstuvwxyz", - "ABCDEFGHIJKLMNOQPRSTUVWXYZ", - "0123456789", - "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~", - "\x00\x01\x02\x03\x04\x05\x06\x07", - "\x08\x0b\x0e\x0f", - "\x10\x11\x12\x13\x14\x15\x16\x17", - "\x18\x19\x1a\x1b\x1c\x1d\x1e\x1f", - "\x7f", - ); -} - -#[test] -fn test_is_ascii_control() { - assert_all!( - is_ascii_control, - "", - "\x00\x01\x02\x03\x04\x05\x06\x07", - "\x08\x09\x0a\x0b\x0c\x0d\x0e\x0f", - "\x10\x11\x12\x13\x14\x15\x16\x17", - "\x18\x19\x1a\x1b\x1c\x1d\x1e\x1f", - "\x7f", - ); - assert_none!( - is_ascii_control, - "abcdefghijklmnopqrstuvwxyz", - "ABCDEFGHIJKLMNOQPRSTUVWXYZ", - "0123456789", - "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~", - " ", - ); -} - -// `is_ascii` does a good amount of pointer manipulation and has -// alignment-dependent computation. This is all sanity-checked via -// `debug_assert!`s, so we test various sizes/alignments thoroughly versus an -// "obviously correct" baseline function. -#[test] -fn test_is_ascii_align_size_thoroughly() { - // The "obviously-correct" baseline mentioned above. - fn is_ascii_baseline(s: &[u8]) -> bool { - s.iter().all(|b| b.is_ascii()) - } - - // Helper to repeat `l` copies of `b0` followed by `l` copies of `b1`. - fn repeat_concat(b0: u8, b1: u8, l: usize) -> Vec { - use core::iter::repeat; - repeat(b0).take(l).chain(repeat(b1).take(l)).collect() - } - - // Miri is too slow - let iter = if cfg!(miri) { 0..20 } else { 0..100 }; - - for i in iter { - #[cfg(not(miri))] - let cases = &[ - b"a".repeat(i), - b"\0".repeat(i), - b"\x7f".repeat(i), - b"\x80".repeat(i), - b"\xff".repeat(i), - repeat_concat(b'a', 0x80u8, i), - repeat_concat(0x80u8, b'a', i), - ]; - - #[cfg(miri)] - let cases = &[b"a".repeat(i), b"\x80".repeat(i), repeat_concat(b'a', 0x80u8, i)]; - - for case in cases { - for pos in 0..=case.len() { - // Potentially misaligned head - let prefix = &case[pos..]; - assert_eq!(is_ascii_baseline(prefix), prefix.is_ascii(),); - - // Potentially misaligned tail - let suffix = &case[..case.len() - pos]; - - assert_eq!(is_ascii_baseline(suffix), suffix.is_ascii(),); - - // Both head and tail are potentially misaligned - let mid = &case[(pos / 2)..(case.len() - (pos / 2))]; - assert_eq!(is_ascii_baseline(mid), mid.is_ascii(),); - } - } - } -} - -#[test] -fn ascii_const() { - // test that the `is_ascii` methods of `char` and `u8` are usable in a const context - - const CHAR_IS_ASCII: bool = 'a'.is_ascii(); - assert!(CHAR_IS_ASCII); - - const BYTE_IS_ASCII: bool = 97u8.is_ascii(); - assert!(BYTE_IS_ASCII); -} - -#[test] -fn ascii_ctype_const() { - macro_rules! suite { - ( $( $fn:ident => [$a:ident, $A:ident, $nine:ident, $dot:ident, $space:ident]; )* ) => { - $( - mod $fn { - const CHAR_A_LOWER: bool = 'a'.$fn(); - const CHAR_A_UPPER: bool = 'A'.$fn(); - const CHAR_NINE: bool = '9'.$fn(); - const CHAR_DOT: bool = '.'.$fn(); - const CHAR_SPACE: bool = ' '.$fn(); - - const U8_A_LOWER: bool = b'a'.$fn(); - const U8_A_UPPER: bool = b'A'.$fn(); - const U8_NINE: bool = b'9'.$fn(); - const U8_DOT: bool = b'.'.$fn(); - const U8_SPACE: bool = b' '.$fn(); - - pub fn run() { - assert_eq!(CHAR_A_LOWER, $a); - assert_eq!(CHAR_A_UPPER, $A); - assert_eq!(CHAR_NINE, $nine); - assert_eq!(CHAR_DOT, $dot); - assert_eq!(CHAR_SPACE, $space); - - assert_eq!(U8_A_LOWER, $a); - assert_eq!(U8_A_UPPER, $A); - assert_eq!(U8_NINE, $nine); - assert_eq!(U8_DOT, $dot); - assert_eq!(U8_SPACE, $space); - } - } - )* - - $( $fn::run(); )* - } - } - - suite! { - // 'a' 'A' '9' '.' ' ' - is_ascii_alphabetic => [true, true, false, false, false]; - is_ascii_uppercase => [false, true, false, false, false]; - is_ascii_lowercase => [true, false, false, false, false]; - is_ascii_alphanumeric => [true, true, true, false, false]; - is_ascii_digit => [false, false, true, false, false]; - is_ascii_octdigit => [false, false, false, false, false]; - is_ascii_hexdigit => [true, true, true, false, false]; - is_ascii_punctuation => [false, false, false, true, false]; - is_ascii_graphic => [true, true, true, true, false]; - is_ascii_whitespace => [false, false, false, false, true]; - is_ascii_control => [false, false, false, false, false]; - } -} - -#[test] -fn test_ascii_display() { - assert_eq!(b"foo'bar".escape_ascii().to_string(), r#"foo\'bar"#); - assert_eq!(b"\0\xff".escape_ascii().to_string(), r#"\x00\xff"#); - let mut it = b"\0fastpath\xffremainder\xff".escape_ascii(); - let _ = it.advance_by(4); - let _ = it.advance_back_by(4); - assert_eq!(it.to_string(), r#"fastpath\xffremainder"#); -} diff --git a/library/core/tests/asserting.rs b/library/core/tests/asserting.rs deleted file mode 100644 index 1d9670886eb3d..0000000000000 --- a/library/core/tests/asserting.rs +++ /dev/null @@ -1,37 +0,0 @@ -use core::asserting::{Capture, TryCaptureGeneric, TryCapturePrintable, Wrapper}; - -macro_rules! test { - ($test_name:ident, $elem:expr, $captured_elem:expr, $output:literal) => { - #[test] - fn $test_name() { - let elem = $elem; - let mut capture = Capture::new(); - assert!(capture.elem == None); - (&Wrapper(&elem)).try_capture(&mut capture); - assert!(capture.elem == $captured_elem); - assert_eq!(format!("{:?}", capture), $output); - } - }; -} - -#[derive(Debug, PartialEq)] -struct NoCopy; - -#[derive(PartialEq)] -struct NoCopyNoDebug; - -#[derive(Clone, Copy, PartialEq)] -struct NoDebug; - -test!( - capture_with_non_copyable_and_non_debuggable_elem_has_correct_params, - NoCopyNoDebug, - None, - "N/A" -); - -test!(capture_with_non_copyable_elem_has_correct_params, NoCopy, None, "N/A"); - -test!(capture_with_non_debuggable_elem_has_correct_params, NoDebug, None, "N/A"); - -test!(capture_with_copyable_and_debuggable_elem_has_correct_params, 1i32, Some(1i32), "1"); diff --git a/library/core/tests/async_iter/mod.rs b/library/core/tests/async_iter/mod.rs deleted file mode 100644 index 4f425d7286d09..0000000000000 --- a/library/core/tests/async_iter/mod.rs +++ /dev/null @@ -1,16 +0,0 @@ -use core::async_iter::{self, AsyncIterator, IntoAsyncIterator}; -use core::pin::pin; -use core::task::Poll; - -#[test] -fn into_async_iter() { - let async_iter = async_iter::from_iter(0..3); - let mut async_iter = pin!(async_iter.into_async_iter()); - - let mut cx = &mut core::task::Context::from_waker(core::task::Waker::noop()); - - assert_eq!(async_iter.as_mut().poll_next(&mut cx), Poll::Ready(Some(0))); - assert_eq!(async_iter.as_mut().poll_next(&mut cx), Poll::Ready(Some(1))); - assert_eq!(async_iter.as_mut().poll_next(&mut cx), Poll::Ready(Some(2))); - assert_eq!(async_iter.as_mut().poll_next(&mut cx), Poll::Ready(None)); -} diff --git a/library/core/tests/atomic.rs b/library/core/tests/atomic.rs deleted file mode 100644 index 0d1c72a689291..0000000000000 --- a/library/core/tests/atomic.rs +++ /dev/null @@ -1,316 +0,0 @@ -use core::sync::atomic::Ordering::SeqCst; -use core::sync::atomic::*; - -#[test] -fn bool_() { - let a = AtomicBool::new(false); - assert_eq!(a.compare_exchange(false, true, SeqCst, SeqCst), Ok(false)); - assert_eq!(a.compare_exchange(false, true, SeqCst, SeqCst), Err(true)); - - a.store(false, SeqCst); - assert_eq!(a.compare_exchange(false, true, SeqCst, SeqCst), Ok(false)); -} - -#[test] -fn bool_and() { - let a = AtomicBool::new(true); - assert_eq!(a.fetch_and(false, SeqCst), true); - assert_eq!(a.load(SeqCst), false); -} - -#[test] -fn bool_nand() { - let a = AtomicBool::new(false); - assert_eq!(a.fetch_nand(false, SeqCst), false); - assert_eq!(a.load(SeqCst), true); - assert_eq!(a.fetch_nand(false, SeqCst), true); - assert_eq!(a.load(SeqCst), true); - assert_eq!(a.fetch_nand(true, SeqCst), true); - assert_eq!(a.load(SeqCst), false); - assert_eq!(a.fetch_nand(true, SeqCst), false); - assert_eq!(a.load(SeqCst), true); -} - -#[test] -fn uint_and() { - let x = AtomicUsize::new(0xf731); - assert_eq!(x.fetch_and(0x137f, SeqCst), 0xf731); - assert_eq!(x.load(SeqCst), 0xf731 & 0x137f); -} - -#[test] -fn uint_nand() { - let x = AtomicUsize::new(0xf731); - assert_eq!(x.fetch_nand(0x137f, SeqCst), 0xf731); - assert_eq!(x.load(SeqCst), !(0xf731 & 0x137f)); -} - -#[test] -fn uint_or() { - let x = AtomicUsize::new(0xf731); - assert_eq!(x.fetch_or(0x137f, SeqCst), 0xf731); - assert_eq!(x.load(SeqCst), 0xf731 | 0x137f); -} - -#[test] -fn uint_xor() { - let x = AtomicUsize::new(0xf731); - assert_eq!(x.fetch_xor(0x137f, SeqCst), 0xf731); - assert_eq!(x.load(SeqCst), 0xf731 ^ 0x137f); -} - -#[test] -#[cfg(any(not(target_arch = "arm"), target_os = "linux"))] // Missing intrinsic in compiler-builtins -fn uint_min() { - let x = AtomicUsize::new(0xf731); - assert_eq!(x.fetch_min(0x137f, SeqCst), 0xf731); - assert_eq!(x.load(SeqCst), 0x137f); - assert_eq!(x.fetch_min(0xf731, SeqCst), 0x137f); - assert_eq!(x.load(SeqCst), 0x137f); -} - -#[test] -#[cfg(any(not(target_arch = "arm"), target_os = "linux"))] // Missing intrinsic in compiler-builtins -fn uint_max() { - let x = AtomicUsize::new(0x137f); - assert_eq!(x.fetch_max(0xf731, SeqCst), 0x137f); - assert_eq!(x.load(SeqCst), 0xf731); - assert_eq!(x.fetch_max(0x137f, SeqCst), 0xf731); - assert_eq!(x.load(SeqCst), 0xf731); -} - -#[test] -fn int_and() { - let x = AtomicIsize::new(0xf731); - assert_eq!(x.fetch_and(0x137f, SeqCst), 0xf731); - assert_eq!(x.load(SeqCst), 0xf731 & 0x137f); -} - -#[test] -fn int_nand() { - let x = AtomicIsize::new(0xf731); - assert_eq!(x.fetch_nand(0x137f, SeqCst), 0xf731); - assert_eq!(x.load(SeqCst), !(0xf731 & 0x137f)); -} - -#[test] -fn int_or() { - let x = AtomicIsize::new(0xf731); - assert_eq!(x.fetch_or(0x137f, SeqCst), 0xf731); - assert_eq!(x.load(SeqCst), 0xf731 | 0x137f); -} - -#[test] -fn int_xor() { - let x = AtomicIsize::new(0xf731); - assert_eq!(x.fetch_xor(0x137f, SeqCst), 0xf731); - assert_eq!(x.load(SeqCst), 0xf731 ^ 0x137f); -} - -#[test] -#[cfg(any(not(target_arch = "arm"), target_os = "linux"))] // Missing intrinsic in compiler-builtins -fn int_min() { - let x = AtomicIsize::new(0xf731); - assert_eq!(x.fetch_min(0x137f, SeqCst), 0xf731); - assert_eq!(x.load(SeqCst), 0x137f); - assert_eq!(x.fetch_min(0xf731, SeqCst), 0x137f); - assert_eq!(x.load(SeqCst), 0x137f); -} - -#[test] -#[cfg(any(not(target_arch = "arm"), target_os = "linux"))] // Missing intrinsic in compiler-builtins -fn int_max() { - let x = AtomicIsize::new(0x137f); - assert_eq!(x.fetch_max(0xf731, SeqCst), 0x137f); - assert_eq!(x.load(SeqCst), 0xf731); - assert_eq!(x.fetch_max(0x137f, SeqCst), 0xf731); - assert_eq!(x.load(SeqCst), 0xf731); -} - -#[test] -#[cfg(any(not(target_arch = "arm"), target_os = "linux"))] // Missing intrinsic in compiler-builtins -fn ptr_add_null() { - let atom = AtomicPtr::::new(core::ptr::null_mut()); - assert_eq!(atom.fetch_ptr_add(1, SeqCst).addr(), 0); - assert_eq!(atom.load(SeqCst).addr(), 8); - - assert_eq!(atom.fetch_byte_add(1, SeqCst).addr(), 8); - assert_eq!(atom.load(SeqCst).addr(), 9); - - assert_eq!(atom.fetch_ptr_sub(1, SeqCst).addr(), 9); - assert_eq!(atom.load(SeqCst).addr(), 1); - - assert_eq!(atom.fetch_byte_sub(1, SeqCst).addr(), 1); - assert_eq!(atom.load(SeqCst).addr(), 0); -} - -#[test] -#[cfg(any(not(target_arch = "arm"), target_os = "linux"))] // Missing intrinsic in compiler-builtins -fn ptr_add_data() { - let num = 0i64; - let n = &num as *const i64 as *mut _; - let atom = AtomicPtr::::new(n); - assert_eq!(atom.fetch_ptr_add(1, SeqCst), n); - assert_eq!(atom.load(SeqCst), n.wrapping_add(1)); - - assert_eq!(atom.fetch_ptr_sub(1, SeqCst), n.wrapping_add(1)); - assert_eq!(atom.load(SeqCst), n); - let bytes_from_n = |b| n.wrapping_byte_add(b); - - assert_eq!(atom.fetch_byte_add(1, SeqCst), n); - assert_eq!(atom.load(SeqCst), bytes_from_n(1)); - - assert_eq!(atom.fetch_byte_add(5, SeqCst), bytes_from_n(1)); - assert_eq!(atom.load(SeqCst), bytes_from_n(6)); - - assert_eq!(atom.fetch_byte_sub(1, SeqCst), bytes_from_n(6)); - assert_eq!(atom.load(SeqCst), bytes_from_n(5)); - - assert_eq!(atom.fetch_byte_sub(5, SeqCst), bytes_from_n(5)); - assert_eq!(atom.load(SeqCst), n); -} - -#[test] -#[cfg(any(not(target_arch = "arm"), target_os = "linux"))] // Missing intrinsic in compiler-builtins -fn ptr_bitops() { - let atom = AtomicPtr::::new(core::ptr::null_mut()); - assert_eq!(atom.fetch_or(0b0111, SeqCst).addr(), 0); - assert_eq!(atom.load(SeqCst).addr(), 0b0111); - - assert_eq!(atom.fetch_and(0b1101, SeqCst).addr(), 0b0111); - assert_eq!(atom.load(SeqCst).addr(), 0b0101); - - assert_eq!(atom.fetch_xor(0b1111, SeqCst).addr(), 0b0101); - assert_eq!(atom.load(SeqCst).addr(), 0b1010); -} - -#[test] -#[cfg(any(not(target_arch = "arm"), target_os = "linux"))] // Missing intrinsic in compiler-builtins -fn ptr_bitops_tagging() { - #[repr(align(16))] - struct Tagme(#[allow(dead_code)] u128); - - let tagme = Tagme(1000); - let ptr = &tagme as *const Tagme as *mut Tagme; - let atom: AtomicPtr = AtomicPtr::new(ptr); - - const MASK_TAG: usize = 0b1111; - const MASK_PTR: usize = !MASK_TAG; - - assert_eq!(ptr.addr() & MASK_TAG, 0); - - assert_eq!(atom.fetch_or(0b0111, SeqCst), ptr); - assert_eq!(atom.load(SeqCst), ptr.map_addr(|a| a | 0b111)); - - assert_eq!(atom.fetch_and(MASK_PTR | 0b0010, SeqCst), ptr.map_addr(|a| a | 0b111)); - assert_eq!(atom.load(SeqCst), ptr.map_addr(|a| a | 0b0010)); - - assert_eq!(atom.fetch_xor(0b1011, SeqCst), ptr.map_addr(|a| a | 0b0010)); - assert_eq!(atom.load(SeqCst), ptr.map_addr(|a| a | 0b1001)); - - assert_eq!(atom.fetch_and(MASK_PTR, SeqCst), ptr.map_addr(|a| a | 0b1001)); - assert_eq!(atom.load(SeqCst), ptr); -} - -static S_FALSE: AtomicBool = AtomicBool::new(false); -static S_TRUE: AtomicBool = AtomicBool::new(true); -static S_INT: AtomicIsize = AtomicIsize::new(0); -static S_UINT: AtomicUsize = AtomicUsize::new(0); - -#[test] -fn static_init() { - // Note that we're not really testing the mutability here but it's important - // on Android at the moment (#49775) - assert!(!S_FALSE.swap(true, SeqCst)); - assert!(S_TRUE.swap(false, SeqCst)); - assert!(S_INT.fetch_add(1, SeqCst) == 0); - assert!(S_UINT.fetch_add(1, SeqCst) == 0); -} - -#[test] -fn atomic_access_bool() { - static mut ATOMIC: AtomicBool = AtomicBool::new(false); - - unsafe { - assert_eq!(*ATOMIC.get_mut(), false); - ATOMIC.store(true, SeqCst); - assert_eq!(*ATOMIC.get_mut(), true); - ATOMIC.fetch_or(false, SeqCst); - assert_eq!(*ATOMIC.get_mut(), true); - ATOMIC.fetch_and(false, SeqCst); - assert_eq!(*ATOMIC.get_mut(), false); - ATOMIC.fetch_nand(true, SeqCst); - assert_eq!(*ATOMIC.get_mut(), true); - ATOMIC.fetch_xor(true, SeqCst); - assert_eq!(*ATOMIC.get_mut(), false); - } -} - -#[test] -fn atomic_alignment() { - use std::mem::{align_of, size_of}; - - #[cfg(target_has_atomic = "8")] - assert_eq!(align_of::(), size_of::()); - #[cfg(target_has_atomic = "ptr")] - assert_eq!(align_of::>(), size_of::>()); - #[cfg(target_has_atomic = "8")] - assert_eq!(align_of::(), size_of::()); - #[cfg(target_has_atomic = "8")] - assert_eq!(align_of::(), size_of::()); - #[cfg(target_has_atomic = "16")] - assert_eq!(align_of::(), size_of::()); - #[cfg(target_has_atomic = "16")] - assert_eq!(align_of::(), size_of::()); - #[cfg(target_has_atomic = "32")] - assert_eq!(align_of::(), size_of::()); - #[cfg(target_has_atomic = "32")] - assert_eq!(align_of::(), size_of::()); - #[cfg(target_has_atomic = "64")] - assert_eq!(align_of::(), size_of::()); - #[cfg(target_has_atomic = "64")] - assert_eq!(align_of::(), size_of::()); - #[cfg(target_has_atomic = "128")] - assert_eq!(align_of::(), size_of::()); - #[cfg(target_has_atomic = "128")] - assert_eq!(align_of::(), size_of::()); - #[cfg(target_has_atomic = "ptr")] - assert_eq!(align_of::(), size_of::()); - #[cfg(target_has_atomic = "ptr")] - assert_eq!(align_of::(), size_of::()); -} - -#[test] -fn atomic_compare_exchange() { - use Ordering::*; - - static ATOMIC: AtomicIsize = AtomicIsize::new(0); - - ATOMIC.compare_exchange(0, 1, Relaxed, Relaxed).ok(); - ATOMIC.compare_exchange(0, 1, Acquire, Relaxed).ok(); - ATOMIC.compare_exchange(0, 1, Release, Relaxed).ok(); - ATOMIC.compare_exchange(0, 1, AcqRel, Relaxed).ok(); - ATOMIC.compare_exchange(0, 1, SeqCst, Relaxed).ok(); - ATOMIC.compare_exchange(0, 1, Acquire, Acquire).ok(); - ATOMIC.compare_exchange(0, 1, AcqRel, Acquire).ok(); - ATOMIC.compare_exchange(0, 1, SeqCst, Acquire).ok(); - ATOMIC.compare_exchange(0, 1, SeqCst, SeqCst).ok(); - ATOMIC.compare_exchange_weak(0, 1, Relaxed, Relaxed).ok(); - ATOMIC.compare_exchange_weak(0, 1, Acquire, Relaxed).ok(); - ATOMIC.compare_exchange_weak(0, 1, Release, Relaxed).ok(); - ATOMIC.compare_exchange_weak(0, 1, AcqRel, Relaxed).ok(); - ATOMIC.compare_exchange_weak(0, 1, SeqCst, Relaxed).ok(); - ATOMIC.compare_exchange_weak(0, 1, Acquire, Acquire).ok(); - ATOMIC.compare_exchange_weak(0, 1, AcqRel, Acquire).ok(); - ATOMIC.compare_exchange_weak(0, 1, SeqCst, Acquire).ok(); - ATOMIC.compare_exchange_weak(0, 1, SeqCst, SeqCst).ok(); -} - -/* FIXME(#110395) -#[test] -fn atomic_const_from() { - const _ATOMIC_U8: AtomicU8 = AtomicU8::from(1); - const _ATOMIC_BOOL: AtomicBool = AtomicBool::from(true); - const _ATOMIC_PTR: AtomicPtr = AtomicPtr::from(core::ptr::null_mut()); -} -*/ diff --git a/library/core/tests/bool.rs b/library/core/tests/bool.rs deleted file mode 100644 index 47f6459915b3e..0000000000000 --- a/library/core/tests/bool.rs +++ /dev/null @@ -1,107 +0,0 @@ -use core::cmp::Ordering::{Equal, Greater, Less}; -use core::ops::{BitAnd, BitOr, BitXor}; - -#[test] -fn test_bool() { - assert_eq!(false.eq(&true), false); - assert_eq!(false == false, true); - assert_eq!(false != true, true); - assert_eq!(false.ne(&false), false); - - assert_eq!(false.bitand(false), false); - assert_eq!(true.bitand(false), false); - assert_eq!(false.bitand(true), false); - assert_eq!(true.bitand(true), true); - - assert_eq!(false & false, false); - assert_eq!(true & false, false); - assert_eq!(false & true, false); - assert_eq!(true & true, true); - - assert_eq!(false.bitor(false), false); - assert_eq!(true.bitor(false), true); - assert_eq!(false.bitor(true), true); - assert_eq!(true.bitor(true), true); - - assert_eq!(false | false, false); - assert_eq!(true | false, true); - assert_eq!(false | true, true); - assert_eq!(true | true, true); - - assert_eq!(false.bitxor(false), false); - assert_eq!(true.bitxor(false), true); - assert_eq!(false.bitxor(true), true); - assert_eq!(true.bitxor(true), false); - - assert_eq!(false ^ false, false); - assert_eq!(true ^ false, true); - assert_eq!(false ^ true, true); - assert_eq!(true ^ true, false); - - assert_eq!(!true, false); - assert_eq!(!false, true); - - let s = false.to_string(); - assert_eq!(s, "false"); - let s = true.to_string(); - assert_eq!(s, "true"); - - assert!(true > false); - assert!(!(false > true)); - - assert!(false < true); - assert!(!(true < false)); - - assert!(false <= false); - assert!(false >= false); - assert!(true <= true); - assert!(true >= true); - - assert!(false <= true); - assert!(!(false >= true)); - assert!(true >= false); - assert!(!(true <= false)); - - assert_eq!(true.cmp(&true), Equal); - assert_eq!(false.cmp(&false), Equal); - assert_eq!(true.cmp(&false), Greater); - assert_eq!(false.cmp(&true), Less); -} - -#[test] -pub fn test_bool_not() { - if !false { - assert!((true)); - } else { - assert!((false)); - } - if !true { - assert!((false)); - } else { - assert!((true)); - } -} - -#[test] -fn test_bool_to_option() { - assert_eq!(false.then_some(0), None); - assert_eq!(true.then_some(0), Some(0)); - assert_eq!(false.then(|| 0), None); - assert_eq!(true.then(|| 0), Some(0)); - - /* FIXME(#110395) - const fn zero() -> i32 { - 0 - } - - const A: Option = false.then_some(0); - const B: Option = true.then_some(0); - const C: Option = false.then(zero); - const D: Option = true.then(zero); - - assert_eq!(A, None); - assert_eq!(B, Some(0)); - assert_eq!(C, None); - assert_eq!(D, Some(0)); - */ -} diff --git a/library/core/tests/cell.rs b/library/core/tests/cell.rs deleted file mode 100644 index d6a401c2b4d98..0000000000000 --- a/library/core/tests/cell.rs +++ /dev/null @@ -1,479 +0,0 @@ -use core::cell::*; - -#[test] -fn smoketest_unsafe_cell() { - let mut x = UnsafeCell::new(10); - let ref_mut = &mut x; - unsafe { - // The asserts are repeated in order to ensure that `get()` - // is non-mutating. - assert_eq!(*ref_mut.get(), 10); - assert_eq!(*ref_mut.get(), 10); - *ref_mut.get_mut() += 5; - assert_eq!(*ref_mut.get(), 15); - assert_eq!(*ref_mut.get(), 15); - assert_eq!(x.into_inner(), 15); - } -} - -#[test] -fn unsafe_cell_raw_get() { - let x = UnsafeCell::new(10); - let ptr = &x as *const UnsafeCell; - unsafe { - // The asserts are repeated in order to ensure that `raw_get()` - // is non-mutating. - assert_eq!(*UnsafeCell::raw_get(ptr), 10); - assert_eq!(*UnsafeCell::raw_get(ptr), 10); - *UnsafeCell::raw_get(ptr) += 5; - assert_eq!(*UnsafeCell::raw_get(ptr), 15); - assert_eq!(*UnsafeCell::raw_get(ptr), 15); - assert_eq!(x.into_inner(), 15); - } -} - -#[test] -fn smoketest_cell() { - let x = Cell::new(10); - assert_eq!(x, Cell::new(10)); - assert_eq!(x.get(), 10); - x.set(20); - assert_eq!(x, Cell::new(20)); - assert_eq!(x.get(), 20); - - let y = Cell::new((30, 40)); - assert_eq!(y, Cell::new((30, 40))); - assert_eq!(y.get(), (30, 40)); -} - -#[test] -fn cell_update() { - let x = Cell::new(10); - - assert_eq!(x.update(|x| x + 5), 15); - assert_eq!(x.get(), 15); - - assert_eq!(x.update(|x| x / 3), 5); - assert_eq!(x.get(), 5); -} - -#[test] -fn cell_has_sensible_show() { - let x = Cell::new("foo bar"); - assert!(format!("{x:?}").contains(x.get())); - - x.set("baz qux"); - assert!(format!("{x:?}").contains(x.get())); -} - -#[test] -fn ref_and_refmut_have_sensible_show() { - let refcell = RefCell::new("foo"); - - let refcell_refmut = refcell.borrow_mut(); - assert_eq!(format!("{refcell_refmut}"), "foo"); // Display - assert!(format!("{refcell_refmut:?}").contains("foo")); // Debug - drop(refcell_refmut); - - let refcell_ref = refcell.borrow(); - assert_eq!(format!("{refcell_ref}"), "foo"); // Display - assert!(format!("{refcell_ref:?}").contains("foo")); // Debug - drop(refcell_ref); -} - -#[test] -fn double_imm_borrow() { - let x = RefCell::new(0); - let _b1 = x.borrow(); - x.borrow(); -} - -#[test] -fn no_mut_then_imm_borrow() { - let x = RefCell::new(0); - let _b1 = x.borrow_mut(); - assert!(x.try_borrow().is_err()); -} - -#[test] -fn no_imm_then_borrow_mut() { - let x = RefCell::new(0); - let _b1 = x.borrow(); - assert!(x.try_borrow_mut().is_err()); -} - -#[test] -fn no_double_borrow_mut() { - let x = RefCell::new(0); - assert!(x.try_borrow().is_ok()); - let _b1 = x.borrow_mut(); - assert!(x.try_borrow().is_err()); -} - -#[test] -fn imm_release_borrow_mut() { - let x = RefCell::new(0); - { - let _b1 = x.borrow(); - } - x.borrow_mut(); -} - -#[test] -fn mut_release_borrow_mut() { - let x = RefCell::new(0); - { - let _b1 = x.borrow_mut(); - } - x.borrow(); -} - -#[test] -fn double_borrow_single_release_no_borrow_mut() { - let x = RefCell::new(0); - let _b1 = x.borrow(); - { - let _b2 = x.borrow(); - } - assert!(x.try_borrow().is_ok()); - assert!(x.try_borrow_mut().is_err()); -} - -#[test] -#[should_panic] -fn discard_doesnt_unborrow() { - let x = RefCell::new(0); - let _b = x.borrow(); - let _ = _b; - let _b = x.borrow_mut(); -} - -#[test] -fn ref_clone_updates_flag() { - let x = RefCell::new(0); - { - let b1 = x.borrow(); - assert!(x.try_borrow().is_ok()); - assert!(x.try_borrow_mut().is_err()); - { - let _b2 = Ref::clone(&b1); - assert!(x.try_borrow().is_ok()); - assert!(x.try_borrow_mut().is_err()); - } - assert!(x.try_borrow().is_ok()); - assert!(x.try_borrow_mut().is_err()); - } - assert!(x.try_borrow().is_ok()); - assert!(x.try_borrow_mut().is_ok()); -} - -#[test] -fn ref_map_does_not_update_flag() { - let x = RefCell::new(Some(5)); - { - let b1: Ref<'_, Option> = x.borrow(); - assert!(x.try_borrow().is_ok()); - assert!(x.try_borrow_mut().is_err()); - { - let b2: Ref<'_, u32> = Ref::map(b1, |o| o.as_ref().unwrap()); - assert_eq!(*b2, 5); - assert!(x.try_borrow().is_ok()); - assert!(x.try_borrow_mut().is_err()); - } - assert!(x.try_borrow().is_ok()); - assert!(x.try_borrow_mut().is_ok()); - } - assert!(x.try_borrow().is_ok()); - assert!(x.try_borrow_mut().is_ok()); -} - -#[test] -fn ref_map_split_updates_flag() { - let x = RefCell::new([1, 2]); - { - let b1 = x.borrow(); - assert!(x.try_borrow().is_ok()); - assert!(x.try_borrow_mut().is_err()); - { - let (_b2, _b3) = Ref::map_split(b1, |slc| slc.split_at(1)); - assert!(x.try_borrow().is_ok()); - assert!(x.try_borrow_mut().is_err()); - } - assert!(x.try_borrow().is_ok()); - assert!(x.try_borrow_mut().is_ok()); - } - assert!(x.try_borrow().is_ok()); - assert!(x.try_borrow_mut().is_ok()); - - { - let b1 = x.borrow_mut(); - assert!(x.try_borrow().is_err()); - assert!(x.try_borrow_mut().is_err()); - { - let (_b2, _b3) = RefMut::map_split(b1, |slc| slc.split_at_mut(1)); - assert!(x.try_borrow().is_err()); - assert!(x.try_borrow_mut().is_err()); - drop(_b2); - assert!(x.try_borrow().is_err()); - assert!(x.try_borrow_mut().is_err()); - } - assert!(x.try_borrow().is_ok()); - assert!(x.try_borrow_mut().is_ok()); - } - assert!(x.try_borrow().is_ok()); - assert!(x.try_borrow_mut().is_ok()); -} - -#[test] -fn ref_map_split() { - let x = RefCell::new([1, 2]); - let (b1, b2) = Ref::map_split(x.borrow(), |slc| slc.split_at(1)); - assert_eq!(*b1, [1]); - assert_eq!(*b2, [2]); -} - -#[test] -fn ref_mut_map_split() { - let x = RefCell::new([1, 2]); - { - let (mut b1, mut b2) = RefMut::map_split(x.borrow_mut(), |slc| slc.split_at_mut(1)); - assert_eq!(*b1, [1]); - assert_eq!(*b2, [2]); - b1[0] = 2; - b2[0] = 1; - } - assert_eq!(*x.borrow(), [2, 1]); -} - -#[test] -fn ref_map_accessor() { - struct X(RefCell<(u32, char)>); - impl X { - fn accessor(&self) -> Ref<'_, u32> { - Ref::map(self.0.borrow(), |tuple| &tuple.0) - } - } - let x = X(RefCell::new((7, 'z'))); - let d: Ref<'_, u32> = x.accessor(); - assert_eq!(*d, 7); -} - -#[test] -fn ref_mut_map_accessor() { - struct X(RefCell<(u32, char)>); - impl X { - fn accessor(&self) -> RefMut<'_, u32> { - RefMut::map(self.0.borrow_mut(), |tuple| &mut tuple.0) - } - } - let x = X(RefCell::new((7, 'z'))); - { - let mut d: RefMut<'_, u32> = x.accessor(); - assert_eq!(*d, 7); - *d += 1; - } - assert_eq!(*x.0.borrow(), (8, 'z')); -} - -#[test] -fn as_ptr() { - let c1: Cell = Cell::new(0); - c1.set(1); - assert_eq!(1, unsafe { *c1.as_ptr() }); - - let c2: Cell = Cell::new(0); - unsafe { - *c2.as_ptr() = 1; - } - assert_eq!(1, c2.get()); - - let r1: RefCell = RefCell::new(0); - *r1.borrow_mut() = 1; - assert_eq!(1, unsafe { *r1.as_ptr() }); - - let r2: RefCell = RefCell::new(0); - unsafe { - *r2.as_ptr() = 1; - } - assert_eq!(1, *r2.borrow()); -} - -#[test] -fn cell_default() { - let cell: Cell = Default::default(); - assert_eq!(0, cell.get()); -} - -#[test] -fn cell_set() { - let cell = Cell::new(10); - cell.set(20); - assert_eq!(20, cell.get()); - - let cell = Cell::new("Hello".to_owned()); - cell.set("World".to_owned()); - assert_eq!("World".to_owned(), cell.into_inner()); -} - -#[test] -fn cell_replace() { - let cell = Cell::new(10); - assert_eq!(10, cell.replace(20)); - assert_eq!(20, cell.get()); - - let cell = Cell::new("Hello".to_owned()); - assert_eq!("Hello".to_owned(), cell.replace("World".to_owned())); - assert_eq!("World".to_owned(), cell.into_inner()); -} - -#[test] -fn cell_into_inner() { - let cell = Cell::new(10); - assert_eq!(10, cell.into_inner()); - - let cell = Cell::new("Hello world".to_owned()); - assert_eq!("Hello world".to_owned(), cell.into_inner()); -} - -#[test] -fn cell_exterior() { - #[derive(Copy, Clone)] - #[allow(dead_code)] - struct Point { - x: isize, - y: isize, - z: isize, - } - - fn f(p: &Cell) { - assert_eq!(p.get().z, 12); - p.set(Point { x: 10, y: 11, z: 13 }); - assert_eq!(p.get().z, 13); - } - - let a = Point { x: 10, y: 11, z: 12 }; - let b = &Cell::new(a); - assert_eq!(b.get().z, 12); - f(b); - assert_eq!(a.z, 12); - assert_eq!(b.get().z, 13); -} - -#[test] -fn cell_does_not_clone() { - #[derive(Copy)] - #[allow(dead_code)] - struct Foo { - x: isize, - } - - impl Clone for Foo { - fn clone(&self) -> Foo { - // Using Cell in any way should never cause clone() to be - // invoked -- after all, that would permit evil user code to - // abuse `Cell` and trigger crashes. - - panic!(); - } - } - - let x = Cell::new(Foo { x: 22 }); - let _y = x.get(); - let _z = x.clone(); -} - -#[test] -fn refcell_default() { - let cell: RefCell = Default::default(); - assert_eq!(0, *cell.borrow()); -} - -#[test] -fn unsafe_cell_unsized() { - let cell: &UnsafeCell<[i32]> = &UnsafeCell::new([1, 2, 3]); - { - let val: &mut [i32] = unsafe { &mut *cell.get() }; - val[0] = 4; - val[2] = 5; - } - let comp: &mut [i32] = &mut [4, 2, 5]; - assert_eq!(unsafe { &mut *cell.get() }, comp); -} - -#[test] -fn refcell_unsized() { - let cell: &RefCell<[i32]> = &RefCell::new([1, 2, 3]); - { - let b = &mut *cell.borrow_mut(); - b[0] = 4; - b[2] = 5; - } - let comp: &mut [i32] = &mut [4, 2, 5]; - assert_eq!(&*cell.borrow(), comp); -} - -#[test] -fn refcell_ref_coercion() { - let cell: RefCell<[i32; 3]> = RefCell::new([1, 2, 3]); - { - let mut cellref: RefMut<'_, [i32; 3]> = cell.borrow_mut(); - cellref[0] = 4; - let mut coerced: RefMut<'_, [i32]> = cellref; - coerced[2] = 5; - } - { - let comp: &mut [i32] = &mut [4, 2, 5]; - let cellref: Ref<'_, [i32; 3]> = cell.borrow(); - assert_eq!(&*cellref, comp); - let coerced: Ref<'_, [i32]> = cellref; - assert_eq!(&*coerced, comp); - } -} - -#[test] -#[should_panic] -fn refcell_swap_borrows() { - let x = RefCell::new(0); - let _b = x.borrow(); - let y = RefCell::new(1); - x.swap(&y); -} - -#[test] -#[should_panic] -fn refcell_replace_borrows() { - let x = RefCell::new(0); - let _b = x.borrow(); - x.replace(1); -} - -#[test] -fn refcell_format() { - let name = RefCell::new("rust"); - let what = RefCell::new("rocks"); - let msg = format!("{name} {}", &*what.borrow(), name = &*name.borrow()); - assert_eq!(msg, "rust rocks".to_string()); -} - -#[allow(dead_code)] -fn const_cells() { - const UNSAFE_CELL: UnsafeCell = UnsafeCell::new(3); - const _: i32 = UNSAFE_CELL.into_inner(); - - const REF_CELL: RefCell = RefCell::new(3); - const _: i32 = REF_CELL.into_inner(); - - const CELL: Cell = Cell::new(3); - const _: i32 = CELL.into_inner(); - - /* FIXME(#110395) - const UNSAFE_CELL_FROM: UnsafeCell = UnsafeCell::from(3); - const _: i32 = UNSAFE_CELL.into_inner(); - - const REF_CELL_FROM: RefCell = RefCell::from(3); - const _: i32 = REF_CELL.into_inner(); - - const CELL_FROM: Cell = Cell::from(3); - const _: i32 = CELL.into_inner(); - */ -} diff --git a/library/core/tests/char.rs b/library/core/tests/char.rs deleted file mode 100644 index 6422387e9560b..0000000000000 --- a/library/core/tests/char.rs +++ /dev/null @@ -1,420 +0,0 @@ -use std::str::FromStr; -use std::{char, str}; - -#[test] -fn test_convert() { - assert_eq!(u32::from('a'), 0x61); - assert_eq!(u64::from('b'), 0x62); - assert_eq!(u128::from('c'), 0x63); - assert_eq!(char::from(b'\0'), '\0'); - assert_eq!(char::from(b'a'), 'a'); - assert_eq!(char::from(b'\xFF'), '\u{FF}'); - assert_eq!(char::try_from(0_u32), Ok('\0')); - assert_eq!(char::try_from(0x61_u32), Ok('a')); - assert_eq!(char::try_from(0xD7FF_u32), Ok('\u{D7FF}')); - assert!(char::try_from(0xD800_u32).is_err()); - assert!(char::try_from(0xDFFF_u32).is_err()); - assert_eq!(char::try_from(0xE000_u32), Ok('\u{E000}')); - assert_eq!(char::try_from(0x10FFFF_u32), Ok('\u{10FFFF}')); - assert!(char::try_from(0x110000_u32).is_err()); - assert!(char::try_from(0xFFFF_FFFF_u32).is_err()); -} - -/* FIXME(#110395) -#[test] -const fn test_convert_const() { - assert!(u32::from('a') == 0x61); - assert!(u64::from('b') == 0x62); - assert!(u128::from('c') == 0x63); - assert!(char::from(b'\0') == '\0'); - assert!(char::from(b'a') == 'a'); - assert!(char::from(b'\xFF') == '\u{FF}'); -} -*/ - -#[test] -fn test_from_str() { - assert_eq!(char::from_str("a").unwrap(), 'a'); - assert_eq!(char::from_str("\0").unwrap(), '\0'); - assert_eq!(char::from_str("\u{D7FF}").unwrap(), '\u{d7FF}'); - assert!(char::from_str("").is_err()); - assert!(char::from_str("abc").is_err()); -} - -#[test] -fn test_is_lowercase() { - assert!('a'.is_lowercase()); - assert!('ö'.is_lowercase()); - assert!('ß'.is_lowercase()); - assert!(!'Ü'.is_lowercase()); - assert!(!'P'.is_lowercase()); -} - -#[test] -fn test_is_uppercase() { - assert!(!'h'.is_uppercase()); - assert!(!'ä'.is_uppercase()); - assert!(!'ß'.is_uppercase()); - assert!('Ö'.is_uppercase()); - assert!('T'.is_uppercase()); -} - -#[test] -fn test_is_whitespace() { - assert!(' '.is_whitespace()); - assert!('\u{2007}'.is_whitespace()); - assert!('\t'.is_whitespace()); - assert!('\n'.is_whitespace()); - assert!(!'a'.is_whitespace()); - assert!(!'_'.is_whitespace()); - assert!(!'\u{0}'.is_whitespace()); -} - -#[test] -fn test_to_digit() { - assert_eq!('0'.to_digit(10), Some(0)); - assert_eq!('1'.to_digit(2), Some(1)); - assert_eq!('2'.to_digit(3), Some(2)); - assert_eq!('9'.to_digit(10), Some(9)); - assert_eq!('a'.to_digit(16), Some(10)); - assert_eq!('A'.to_digit(16), Some(10)); - assert_eq!('b'.to_digit(16), Some(11)); - assert_eq!('B'.to_digit(16), Some(11)); - assert_eq!('A'.to_digit(36), Some(10)); - assert_eq!('z'.to_digit(36), Some(35)); - assert_eq!('Z'.to_digit(36), Some(35)); - assert_eq!('['.to_digit(36), None); - assert_eq!('`'.to_digit(36), None); - assert_eq!('{'.to_digit(36), None); - assert_eq!('$'.to_digit(36), None); - assert_eq!('@'.to_digit(16), None); - assert_eq!('G'.to_digit(16), None); - assert_eq!('g'.to_digit(16), None); - assert_eq!(' '.to_digit(10), None); - assert_eq!('/'.to_digit(10), None); - assert_eq!(':'.to_digit(10), None); - assert_eq!(':'.to_digit(11), None); -} - -#[test] -fn test_to_lowercase() { - fn lower(c: char) -> String { - let to_lowercase = c.to_lowercase(); - assert_eq!(to_lowercase.len(), to_lowercase.count()); - let iter: String = c.to_lowercase().collect(); - let disp: String = c.to_lowercase().to_string(); - assert_eq!(iter, disp); - let iter_rev: String = c.to_lowercase().rev().collect(); - let disp_rev: String = disp.chars().rev().collect(); - assert_eq!(iter_rev, disp_rev); - iter - } - assert_eq!(lower('A'), "a"); - assert_eq!(lower('Ö'), "ö"); - assert_eq!(lower('ß'), "ß"); - assert_eq!(lower('Ü'), "ü"); - assert_eq!(lower('💩'), "💩"); - assert_eq!(lower('Σ'), "σ"); - assert_eq!(lower('Τ'), "τ"); - assert_eq!(lower('Ι'), "ι"); - assert_eq!(lower('Γ'), "γ"); - assert_eq!(lower('Μ'), "μ"); - assert_eq!(lower('Α'), "α"); - assert_eq!(lower('Σ'), "σ"); - assert_eq!(lower('Dž'), "dž"); - assert_eq!(lower('fi'), "fi"); - assert_eq!(lower('İ'), "i\u{307}"); -} - -#[test] -fn test_to_uppercase() { - fn upper(c: char) -> String { - let to_uppercase = c.to_uppercase(); - assert_eq!(to_uppercase.len(), to_uppercase.count()); - let iter: String = c.to_uppercase().collect(); - let disp: String = c.to_uppercase().to_string(); - assert_eq!(iter, disp); - let iter_rev: String = c.to_uppercase().rev().collect(); - let disp_rev: String = disp.chars().rev().collect(); - assert_eq!(iter_rev, disp_rev); - iter - } - assert_eq!(upper('a'), "A"); - assert_eq!(upper('ö'), "Ö"); - assert_eq!(upper('ß'), "SS"); // not ẞ: Latin capital letter sharp s - assert_eq!(upper('ü'), "Ü"); - assert_eq!(upper('💩'), "💩"); - - assert_eq!(upper('σ'), "Σ"); - assert_eq!(upper('τ'), "Τ"); - assert_eq!(upper('ι'), "Ι"); - assert_eq!(upper('γ'), "Γ"); - assert_eq!(upper('μ'), "Μ"); - assert_eq!(upper('α'), "Α"); - assert_eq!(upper('ς'), "Σ"); - assert_eq!(upper('Dž'), "DŽ"); - assert_eq!(upper('fi'), "FI"); - assert_eq!(upper('ᾀ'), "ἈΙ"); -} - -#[test] -fn test_is_control() { - assert!('\u{0}'.is_control()); - assert!('\u{3}'.is_control()); - assert!('\u{6}'.is_control()); - assert!('\u{9}'.is_control()); - assert!('\u{7f}'.is_control()); - assert!('\u{92}'.is_control()); - assert!(!'\u{20}'.is_control()); - assert!(!'\u{55}'.is_control()); - assert!(!'\u{68}'.is_control()); -} - -#[test] -fn test_is_numeric() { - assert!('2'.is_numeric()); - assert!('7'.is_numeric()); - assert!('¾'.is_numeric()); - assert!(!'c'.is_numeric()); - assert!(!'i'.is_numeric()); - assert!(!'z'.is_numeric()); - assert!(!'Q'.is_numeric()); -} - -#[test] -fn test_escape_debug() { - fn string(c: char) -> String { - let iter: String = c.escape_debug().collect(); - let disp: String = c.escape_debug().to_string(); - assert_eq!(iter, disp); - iter - } - assert_eq!(string('\n'), "\\n"); - assert_eq!(string('\r'), "\\r"); - assert_eq!(string('\''), "\\'"); - assert_eq!(string('"'), "\\\""); - assert_eq!(string(' '), " "); - assert_eq!(string('a'), "a"); - assert_eq!(string('~'), "~"); - assert_eq!(string('é'), "é"); - assert_eq!(string('文'), "文"); - assert_eq!(string('\x00'), "\\0"); - assert_eq!(string('\x1f'), "\\u{1f}"); - assert_eq!(string('\x7f'), "\\u{7f}"); - assert_eq!(string('\u{80}'), "\\u{80}"); - assert_eq!(string('\u{ff}'), "\u{ff}"); - assert_eq!(string('\u{11b}'), "\u{11b}"); - assert_eq!(string('\u{1d4b6}'), "\u{1d4b6}"); - assert_eq!(string('\u{301}'), "\\u{301}"); // combining character - assert_eq!(string('\u{200b}'), "\\u{200b}"); // zero width space - assert_eq!(string('\u{e000}'), "\\u{e000}"); // private use 1 - assert_eq!(string('\u{100000}'), "\\u{100000}"); // private use 2 -} - -#[test] -fn test_escape_default() { - fn string(c: char) -> String { - let iter: String = c.escape_default().collect(); - let disp: String = c.escape_default().to_string(); - assert_eq!(iter, disp); - iter - } - assert_eq!(string('\n'), "\\n"); - assert_eq!(string('\r'), "\\r"); - assert_eq!(string('\''), "\\'"); - assert_eq!(string('"'), "\\\""); - assert_eq!(string(' '), " "); - assert_eq!(string('a'), "a"); - assert_eq!(string('~'), "~"); - assert_eq!(string('é'), "\\u{e9}"); - assert_eq!(string('\x00'), "\\u{0}"); - assert_eq!(string('\x1f'), "\\u{1f}"); - assert_eq!(string('\x7f'), "\\u{7f}"); - assert_eq!(string('\u{80}'), "\\u{80}"); - assert_eq!(string('\u{ff}'), "\\u{ff}"); - assert_eq!(string('\u{11b}'), "\\u{11b}"); - assert_eq!(string('\u{1d4b6}'), "\\u{1d4b6}"); - assert_eq!(string('\u{200b}'), "\\u{200b}"); // zero width space - assert_eq!(string('\u{e000}'), "\\u{e000}"); // private use 1 - assert_eq!(string('\u{100000}'), "\\u{100000}"); // private use 2 -} - -#[test] -fn test_escape_unicode() { - fn string(c: char) -> String { - let iter: String = c.escape_unicode().collect(); - let disp: String = c.escape_unicode().to_string(); - assert_eq!(iter, disp); - iter - } - - assert_eq!(string('\x00'), "\\u{0}"); - assert_eq!(string('\n'), "\\u{a}"); - assert_eq!(string(' '), "\\u{20}"); - assert_eq!(string('a'), "\\u{61}"); - assert_eq!(string('\u{11b}'), "\\u{11b}"); - assert_eq!(string('\u{1d4b6}'), "\\u{1d4b6}"); -} - -#[test] -fn test_encode_utf8() { - fn check(input: char, expect: &[u8]) { - let mut buf = [0; 4]; - let ptr = buf.as_ptr(); - let s = input.encode_utf8(&mut buf); - assert_eq!(s.as_ptr() as usize, ptr as usize); - assert!(str::from_utf8(s.as_bytes()).is_ok()); - assert_eq!(s.as_bytes(), expect); - } - - check('x', &[0x78]); - check('\u{e9}', &[0xc3, 0xa9]); - check('\u{a66e}', &[0xea, 0x99, 0xae]); - check('\u{1f4a9}', &[0xf0, 0x9f, 0x92, 0xa9]); -} - -#[test] -fn test_encode_utf16() { - fn check(input: char, expect: &[u16]) { - let mut buf = [0; 2]; - let ptr = buf.as_mut_ptr(); - let b = input.encode_utf16(&mut buf); - assert_eq!(b.as_mut_ptr() as usize, ptr as usize); - assert_eq!(b, expect); - } - - check('x', &[0x0078]); - check('\u{e9}', &[0x00e9]); - check('\u{a66e}', &[0xa66e]); - check('\u{1f4a9}', &[0xd83d, 0xdca9]); -} - -#[test] -fn test_len_utf16() { - assert!('x'.len_utf16() == 1); - assert!('\u{e9}'.len_utf16() == 1); - assert!('\u{a66e}'.len_utf16() == 1); - assert!('\u{1f4a9}'.len_utf16() == 2); -} - -#[test] -fn test_decode_utf16() { - fn check(s: &[u16], expected: &[Result]) { - let v = char::decode_utf16(s.iter().cloned()) - .map(|r| r.map_err(|e| e.unpaired_surrogate())) - .collect::>(); - assert_eq!(v, expected); - } - check(&[0xD800, 0x41, 0x42], &[Err(0xD800), Ok('A'), Ok('B')]); - check(&[0xD800, 0], &[Err(0xD800), Ok('\0')]); - check(&[0xD800], &[Err(0xD800)]); - check(&[0xD840, 0xDC00], &[Ok('\u{20000}')]); - check(&[0xD840, 0xD840, 0xDC00], &[Err(0xD840), Ok('\u{20000}')]); - check(&[0xDC00, 0xD840], &[Err(0xDC00), Err(0xD840)]); -} - -#[test] -fn test_decode_utf16_size_hint() { - fn check(s: &[u16]) { - let mut iter = char::decode_utf16(s.iter().cloned()); - - loop { - let count = iter.clone().count(); - let (lower, upper) = iter.size_hint(); - - assert!( - lower <= count && count <= upper.unwrap(), - "lower = {lower}, count = {count}, upper = {upper:?}" - ); - - if let None = iter.next() { - break; - } - } - } - - check(&[0xD800, 0xD800, 0xDC00]); - check(&[0xD800, 0xD800, 0x0]); - check(&[0xD800, 0x41, 0x42]); - check(&[0xD800, 0]); - check(&[0xD834, 0x006d]); -} - -#[test] -fn ed_iterator_specializations() { - // Check counting - assert_eq!('\n'.escape_default().count(), 2); - assert_eq!('c'.escape_default().count(), 1); - assert_eq!(' '.escape_default().count(), 1); - assert_eq!('\\'.escape_default().count(), 2); - assert_eq!('\''.escape_default().count(), 2); - - // Check nth - - // Check that OoB is handled correctly - assert_eq!('\n'.escape_default().nth(2), None); - assert_eq!('c'.escape_default().nth(1), None); - assert_eq!(' '.escape_default().nth(1), None); - assert_eq!('\\'.escape_default().nth(2), None); - assert_eq!('\''.escape_default().nth(2), None); - - // Check the first char - assert_eq!('\n'.escape_default().nth(0), Some('\\')); - assert_eq!('c'.escape_default().nth(0), Some('c')); - assert_eq!(' '.escape_default().nth(0), Some(' ')); - assert_eq!('\\'.escape_default().nth(0), Some('\\')); - assert_eq!('\''.escape_default().nth(0), Some('\\')); - - // Check the second char - assert_eq!('\n'.escape_default().nth(1), Some('n')); - assert_eq!('\\'.escape_default().nth(1), Some('\\')); - assert_eq!('\''.escape_default().nth(1), Some('\'')); - - // Check the last char - assert_eq!('\n'.escape_default().last(), Some('n')); - assert_eq!('c'.escape_default().last(), Some('c')); - assert_eq!(' '.escape_default().last(), Some(' ')); - assert_eq!('\\'.escape_default().last(), Some('\\')); - assert_eq!('\''.escape_default().last(), Some('\'')); -} - -#[test] -fn eu_iterator_specializations() { - fn check(c: char) { - let len = c.escape_unicode().count(); - - // Check OoB - assert_eq!(c.escape_unicode().nth(len), None); - - // For all possible in-bound offsets - let mut iter = c.escape_unicode(); - for offset in 0..len { - // Check last - assert_eq!(iter.clone().last(), Some('}')); - - // Check len - assert_eq!(iter.len(), len - offset); - - // Check size_hint (= len in ExactSizeIterator) - assert_eq!(iter.size_hint(), (iter.len(), Some(iter.len()))); - - // Check counting - assert_eq!(iter.clone().count(), len - offset); - - // Check nth - assert_eq!(c.escape_unicode().nth(offset), iter.next()); - } - - // Check post-last - assert_eq!(iter.clone().last(), None); - assert_eq!(iter.clone().count(), 0); - } - - check('\u{0}'); - check('\u{1}'); - check('\u{12}'); - check('\u{123}'); - check('\u{1234}'); - check('\u{12340}'); - check('\u{10FFFF}'); -} diff --git a/library/core/tests/clone.rs b/library/core/tests/clone.rs deleted file mode 100644 index 64193e1155890..0000000000000 --- a/library/core/tests/clone.rs +++ /dev/null @@ -1,16 +0,0 @@ -#[test] -#[allow(suspicious_double_ref_op)] -fn test_borrowed_clone() { - let x = 5; - let y: &i32 = &x; - let z: &i32 = (&y).clone(); - assert_eq!(*z, 5); -} - -#[test] -fn test_clone_from() { - let a = Box::new(5); - let mut b = Box::new(10); - b.clone_from(&a); - assert_eq!(*b, 5); -} diff --git a/library/core/tests/cmp.rs b/library/core/tests/cmp.rs deleted file mode 100644 index 72fdd490da152..0000000000000 --- a/library/core/tests/cmp.rs +++ /dev/null @@ -1,252 +0,0 @@ -use core::cmp::{ - self, - Ordering::{self, *}, -}; - -#[test] -fn test_int_totalord() { - assert_eq!(5.cmp(&10), Less); - assert_eq!(10.cmp(&5), Greater); - assert_eq!(5.cmp(&5), Equal); - assert_eq!((-5).cmp(&12), Less); - assert_eq!(12.cmp(&-5), Greater); -} - -#[test] -fn test_bool_totalord() { - assert_eq!(true.cmp(&false), Greater); - assert_eq!(false.cmp(&true), Less); - assert_eq!(true.cmp(&true), Equal); - assert_eq!(false.cmp(&false), Equal); -} - -#[test] -fn test_mut_int_totalord() { - assert_eq!((&mut 5).cmp(&&mut 10), Less); - assert_eq!((&mut 10).cmp(&&mut 5), Greater); - assert_eq!((&mut 5).cmp(&&mut 5), Equal); - assert_eq!((&mut -5).cmp(&&mut 12), Less); - assert_eq!((&mut 12).cmp(&&mut -5), Greater); -} - -#[test] -fn test_ord_max_min() { - assert_eq!(1.max(2), 2); - assert_eq!(2.max(1), 2); - assert_eq!(1.min(2), 1); - assert_eq!(2.min(1), 1); - assert_eq!(1.max(1), 1); - assert_eq!(1.min(1), 1); -} - -#[test] -fn test_ord_min_max_by() { - let f = |x: &i32, y: &i32| x.abs().cmp(&y.abs()); - assert_eq!(cmp::min_by(1, -1, f), 1); - assert_eq!(cmp::min_by(1, -2, f), 1); - assert_eq!(cmp::min_by(2, -1, f), -1); - assert_eq!(cmp::max_by(1, -1, f), -1); - assert_eq!(cmp::max_by(1, -2, f), -2); - assert_eq!(cmp::max_by(2, -1, f), 2); -} - -#[test] -fn test_ord_min_max_by_key() { - let f = |x: &i32| x.abs(); - assert_eq!(cmp::min_by_key(1, -1, f), 1); - assert_eq!(cmp::min_by_key(1, -2, f), 1); - assert_eq!(cmp::min_by_key(2, -1, f), -1); - assert_eq!(cmp::max_by_key(1, -1, f), -1); - assert_eq!(cmp::max_by_key(1, -2, f), -2); - assert_eq!(cmp::max_by_key(2, -1, f), 2); -} - -#[test] -fn test_ordering_reverse() { - assert_eq!(Less.reverse(), Greater); - assert_eq!(Equal.reverse(), Equal); - assert_eq!(Greater.reverse(), Less); -} - -#[test] -fn test_ordering_order() { - assert!(Less < Equal); - assert_eq!(Greater.cmp(&Less), Greater); -} - -#[test] -fn test_ordering_then() { - assert_eq!(Equal.then(Less), Less); - assert_eq!(Equal.then(Equal), Equal); - assert_eq!(Equal.then(Greater), Greater); - assert_eq!(Less.then(Less), Less); - assert_eq!(Less.then(Equal), Less); - assert_eq!(Less.then(Greater), Less); - assert_eq!(Greater.then(Less), Greater); - assert_eq!(Greater.then(Equal), Greater); - assert_eq!(Greater.then(Greater), Greater); -} - -#[test] -fn test_ordering_then_with() { - assert_eq!(Equal.then_with(|| Less), Less); - assert_eq!(Equal.then_with(|| Equal), Equal); - assert_eq!(Equal.then_with(|| Greater), Greater); - assert_eq!(Less.then_with(|| Less), Less); - assert_eq!(Less.then_with(|| Equal), Less); - assert_eq!(Less.then_with(|| Greater), Less); - assert_eq!(Greater.then_with(|| Less), Greater); - assert_eq!(Greater.then_with(|| Equal), Greater); - assert_eq!(Greater.then_with(|| Greater), Greater); -} - -#[test] -fn test_user_defined_eq() { - // Our type. - struct SketchyNum { - num: isize, - } - - // Our implementation of `PartialEq` to support `==` and `!=`. - impl PartialEq for SketchyNum { - // Our custom eq allows numbers which are near each other to be equal! :D - fn eq(&self, other: &SketchyNum) -> bool { - (self.num - other.num).abs() < 5 - } - } - - // Now these binary operators will work when applied! - assert!(SketchyNum { num: 37 } == SketchyNum { num: 34 }); - assert!(SketchyNum { num: 25 } != SketchyNum { num: 57 }); -} - -#[test] -fn ordering_const() { - // test that the methods of `Ordering` are usable in a const context - - const ORDERING: Ordering = Greater; - - const REVERSE: Ordering = ORDERING.reverse(); - assert_eq!(REVERSE, Less); - - const THEN: Ordering = Equal.then(ORDERING); - assert_eq!(THEN, Greater); -} - -#[test] -fn ordering_structural_eq() { - // test that consts of type `Ordering` are usable in patterns - - const ORDERING: Ordering = Greater; - - const REVERSE: Ordering = ORDERING.reverse(); - match Ordering::Less { - REVERSE => {} - _ => unreachable!(), - }; -} - -#[test] -fn cmp_default() { - // Test default methods in PartialOrd and PartialEq - - #[derive(Debug)] - struct Fool(bool); - - impl PartialEq for Fool { - fn eq(&self, other: &Fool) -> bool { - let Fool(this) = *self; - let Fool(other) = *other; - this != other - } - } - - struct Int(isize); - - impl PartialEq for Int { - fn eq(&self, other: &Int) -> bool { - let Int(this) = *self; - let Int(other) = *other; - this == other - } - } - - impl PartialOrd for Int { - fn partial_cmp(&self, other: &Int) -> Option { - let Int(this) = *self; - let Int(other) = *other; - this.partial_cmp(&other) - } - } - - struct RevInt(isize); - - impl PartialEq for RevInt { - fn eq(&self, other: &RevInt) -> bool { - let RevInt(this) = *self; - let RevInt(other) = *other; - this == other - } - } - - impl PartialOrd for RevInt { - fn partial_cmp(&self, other: &RevInt) -> Option { - let RevInt(this) = *self; - let RevInt(other) = *other; - other.partial_cmp(&this) - } - } - - assert!(Int(2) > Int(1)); - assert!(Int(2) >= Int(1)); - assert!(Int(1) >= Int(1)); - assert!(Int(1) < Int(2)); - assert!(Int(1) <= Int(2)); - assert!(Int(1) <= Int(1)); - - assert!(RevInt(2) < RevInt(1)); - assert!(RevInt(2) <= RevInt(1)); - assert!(RevInt(1) <= RevInt(1)); - assert!(RevInt(1) > RevInt(2)); - assert!(RevInt(1) >= RevInt(2)); - assert!(RevInt(1) >= RevInt(1)); - - assert_eq!(Fool(true), Fool(false)); - assert!(Fool(true) != Fool(true)); - assert!(Fool(false) != Fool(false)); - assert_eq!(Fool(false), Fool(true)); -} - -/* FIXME(#110395) -mod const_cmp { - use super::*; - - struct S(i32); - - impl PartialEq for S { - fn eq(&self, other: &Self) -> bool { - self.0 == other.0 - } - } - - impl PartialOrd for S { - fn partial_cmp(&self, other: &Self) -> Option { - let ret = match (self.0, other.0) { - (a, b) if a > b => Ordering::Greater, - (a, b) if a < b => Ordering::Less, - _ => Ordering::Equal, - }; - - Some(ret) - } - } - - const _: () = assert!(S(1) == S(1)); - const _: () = assert!(S(0) != S(1)); - - const _: () = assert!(S(1) <= S(1)); - const _: () = assert!(S(1) >= S(1)); - const _: () = assert!(S(0) < S(1)); - const _: () = assert!(S(1) > S(0)); -} -*/ diff --git a/library/core/tests/const_ptr.rs b/library/core/tests/const_ptr.rs deleted file mode 100644 index d874f08317f61..0000000000000 --- a/library/core/tests/const_ptr.rs +++ /dev/null @@ -1,101 +0,0 @@ -// Aligned to two bytes -const DATA: [u16; 2] = [u16::from_ne_bytes([0x01, 0x23]), u16::from_ne_bytes([0x45, 0x67])]; - -const fn unaligned_ptr() -> *const u16 { - // Since DATA.as_ptr() is aligned to two bytes, adding 1 byte to that produces an unaligned *const u16 - unsafe { DATA.as_ptr().byte_add(1) } -} - -#[test] -fn read() { - use core::ptr; - - const FOO: i32 = unsafe { ptr::read(&42 as *const i32) }; - assert_eq!(FOO, 42); - - const ALIGNED: i32 = unsafe { ptr::read_unaligned(&42 as *const i32) }; - assert_eq!(ALIGNED, 42); - - const UNALIGNED_PTR: *const u16 = unaligned_ptr(); - - const UNALIGNED: u16 = unsafe { ptr::read_unaligned(UNALIGNED_PTR) }; - assert_eq!(UNALIGNED, u16::from_ne_bytes([0x23, 0x45])); -} - -#[test] -fn const_ptr_read() { - const FOO: i32 = unsafe { (&42 as *const i32).read() }; - assert_eq!(FOO, 42); - - const ALIGNED: i32 = unsafe { (&42 as *const i32).read_unaligned() }; - assert_eq!(ALIGNED, 42); - - const UNALIGNED_PTR: *const u16 = unaligned_ptr(); - - const UNALIGNED: u16 = unsafe { UNALIGNED_PTR.read_unaligned() }; - assert_eq!(UNALIGNED, u16::from_ne_bytes([0x23, 0x45])); -} - -#[test] -fn mut_ptr_read() { - const FOO: i32 = unsafe { (&42 as *const i32 as *mut i32).read() }; - assert_eq!(FOO, 42); - - const ALIGNED: i32 = unsafe { (&42 as *const i32 as *mut i32).read_unaligned() }; - assert_eq!(ALIGNED, 42); - - const UNALIGNED_PTR: *mut u16 = unaligned_ptr() as *mut u16; - - const UNALIGNED: u16 = unsafe { UNALIGNED_PTR.read_unaligned() }; - assert_eq!(UNALIGNED, u16::from_ne_bytes([0x23, 0x45])); -} - -#[test] -fn write() { - use core::ptr; - - const fn write_aligned() -> i32 { - let mut res = 0; - unsafe { - ptr::write(&mut res as *mut _, 42); - } - res - } - const ALIGNED: i32 = write_aligned(); - assert_eq!(ALIGNED, 42); - - const fn write_unaligned() -> [u16; 2] { - let mut two_aligned = [0u16; 2]; - unsafe { - let unaligned_ptr = two_aligned.as_mut_ptr().byte_add(1); - ptr::write_unaligned(unaligned_ptr, u16::from_ne_bytes([0x23, 0x45])); - } - two_aligned - } - const UNALIGNED: [u16; 2] = write_unaligned(); - assert_eq!(UNALIGNED, [u16::from_ne_bytes([0x00, 0x23]), u16::from_ne_bytes([0x45, 0x00])]); -} - -#[test] -fn mut_ptr_write() { - const fn aligned() -> i32 { - let mut res = 0; - unsafe { - (&mut res as *mut i32).write(42); - } - res - } - const ALIGNED: i32 = aligned(); - assert_eq!(ALIGNED, 42); - - const fn write_unaligned() -> [u16; 2] { - let mut two_aligned = [0u16; 2]; - unsafe { - let unaligned_ptr = two_aligned.as_mut_ptr().byte_add(1); - unaligned_ptr.write_unaligned(u16::from_ne_bytes([0x23, 0x45])); - } - two_aligned - } - const UNALIGNED: [u16; 2] = write_unaligned(); - assert_eq!(UNALIGNED, [u16::from_ne_bytes([0x00, 0x23]), u16::from_ne_bytes([0x45, 0x00])]); -} diff --git a/library/core/tests/convert.rs b/library/core/tests/convert.rs deleted file mode 100644 index f76dd277884e2..0000000000000 --- a/library/core/tests/convert.rs +++ /dev/null @@ -1,18 +0,0 @@ -/* FIXME(#110395) -#[test] -fn convert() { - const fn from(x: i32) -> i32 { - i32::from(x) - } - - const FOO: i32 = from(42); - assert_eq!(FOO, 42); - - const fn into(x: Vec) -> Vec { - x.into() - } - - const BAR: Vec = into(Vec::new()); - assert_eq!(BAR, Vec::::new()); -} -*/ diff --git a/library/core/tests/error.rs b/library/core/tests/error.rs deleted file mode 100644 index 5e20c34ca6ced..0000000000000 --- a/library/core/tests/error.rs +++ /dev/null @@ -1,66 +0,0 @@ -use core::error::{request_ref, request_value, Request}; - -// Test the `Request` API. -#[derive(Debug)] -struct SomeConcreteType { - some_string: String, -} - -impl std::fmt::Display for SomeConcreteType { - fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { - write!(f, "A") - } -} - -impl std::error::Error for SomeConcreteType { - fn provide<'a>(&'a self, request: &mut Request<'a>) { - request - .provide_ref::(&self.some_string) - .provide_ref::(&self.some_string) - .provide_value_with::(|| "bye".to_owned()); - } -} - -// Test the Error.provide and request mechanisms with a by-reference trait object. -#[test] -fn test_error_generic_member_access() { - let obj = &SomeConcreteType { some_string: "hello".to_owned() }; - - assert_eq!(request_ref::(&*obj).unwrap(), "hello"); - assert_eq!(request_value::(&*obj).unwrap(), "bye"); - assert_eq!(request_value::(&obj), None); -} - -// Test the Error.provide and request mechanisms with a by-reference trait object. -#[test] -fn test_request_constructor() { - let obj: &dyn std::error::Error = &SomeConcreteType { some_string: "hello".to_owned() }; - - assert_eq!(request_ref::(&*obj).unwrap(), "hello"); - assert_eq!(request_value::(&*obj).unwrap(), "bye"); - assert_eq!(request_value::(&obj), None); -} - -// Test the Error.provide and request mechanisms with a boxed trait object. -#[test] -fn test_error_generic_member_access_boxed() { - let obj: Box = - Box::new(SomeConcreteType { some_string: "hello".to_owned() }); - - assert_eq!(request_ref::(&*obj).unwrap(), "hello"); - assert_eq!(request_value::(&*obj).unwrap(), "bye"); - - // NOTE: Box only implements Error when E: Error + Sized, which means we can't pass a - // Box to request_value. - //assert_eq!(request_value::(&obj).unwrap(), "bye"); -} - -// Test the Error.provide and request mechanisms with a concrete object. -#[test] -fn test_error_generic_member_access_concrete() { - let obj = SomeConcreteType { some_string: "hello".to_owned() }; - - assert_eq!(request_ref::(&obj).unwrap(), "hello"); - assert_eq!(request_value::(&obj).unwrap(), "bye"); - assert_eq!(request_value::(&obj), None); -} diff --git a/library/core/tests/fmt/builders.rs b/library/core/tests/fmt/builders.rs deleted file mode 100644 index 487ce46be28d7..0000000000000 --- a/library/core/tests/fmt/builders.rs +++ /dev/null @@ -1,726 +0,0 @@ -mod debug_struct { - use std::fmt; - - #[test] - fn test_empty() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_struct("Foo").finish() - } - } - - assert_eq!("Foo", format!("{Foo:?}")); - assert_eq!("Foo", format!("{Foo:#?}")); - } - - #[test] - fn test_single() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_struct("Foo").field("bar", &true).finish() - } - } - - assert_eq!("Foo { bar: true }", format!("{Foo:?}")); - assert_eq!( - "Foo { - bar: true, -}", - format!("{Foo:#?}") - ); - } - - #[test] - fn test_multiple() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_struct("Foo") - .field("bar", &true) - .field("baz", &format_args!("{}/{}", 10, 20)) - .finish() - } - } - - assert_eq!("Foo { bar: true, baz: 10/20 }", format!("{Foo:?}")); - assert_eq!( - "Foo { - bar: true, - baz: 10/20, -}", - format!("{Foo:#?}") - ); - } - - #[test] - fn test_nested() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_struct("Foo") - .field("bar", &true) - .field("baz", &format_args!("{}/{}", 10, 20)) - .finish() - } - } - - struct Bar; - - impl fmt::Debug for Bar { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_struct("Bar").field("foo", &Foo).field("hello", &"world").finish() - } - } - - assert_eq!( - "Bar { foo: Foo { bar: true, baz: 10/20 }, hello: \"world\" }", - format!("{Bar:?}") - ); - assert_eq!( - "Bar { - foo: Foo { - bar: true, - baz: 10/20, - }, - hello: \"world\", -}", - format!("{Bar:#?}") - ); - } - - #[test] - fn test_only_non_exhaustive() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_struct("Foo").finish_non_exhaustive() - } - } - - assert_eq!("Foo { .. }", format!("{Foo:?}")); - assert_eq!("Foo { .. }", format!("{Foo:#?}")); - } - - #[test] - fn test_multiple_and_non_exhaustive() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_struct("Foo") - .field("bar", &true) - .field("baz", &format_args!("{}/{}", 10, 20)) - .finish_non_exhaustive() - } - } - - assert_eq!("Foo { bar: true, baz: 10/20, .. }", format!("{Foo:?}")); - assert_eq!( - "Foo { - bar: true, - baz: 10/20, - .. -}", - format!("{Foo:#?}") - ); - } - - #[test] - fn test_nested_non_exhaustive() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_struct("Foo") - .field("bar", &true) - .field("baz", &format_args!("{}/{}", 10, 20)) - .finish_non_exhaustive() - } - } - - struct Bar; - - impl fmt::Debug for Bar { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_struct("Bar") - .field("foo", &Foo) - .field("hello", &"world") - .finish_non_exhaustive() - } - } - - assert_eq!( - "Bar { foo: Foo { bar: true, baz: 10/20, .. }, hello: \"world\", .. }", - format!("{Bar:?}") - ); - assert_eq!( - "Bar { - foo: Foo { - bar: true, - baz: 10/20, - .. - }, - hello: \"world\", - .. -}", - format!("{Bar:#?}") - ); - } -} - -mod debug_tuple { - use std::fmt; - - #[test] - fn test_empty() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_tuple("Foo").finish() - } - } - - assert_eq!("Foo", format!("{Foo:?}")); - assert_eq!("Foo", format!("{Foo:#?}")); - } - - #[test] - fn test_single() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_tuple("Foo").field(&true).finish() - } - } - - assert_eq!("Foo(true)", format!("{Foo:?}")); - assert_eq!( - "Foo( - true, -)", - format!("{Foo:#?}") - ); - } - - #[test] - fn test_multiple() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_tuple("Foo").field(&true).field(&format_args!("{}/{}", 10, 20)).finish() - } - } - - assert_eq!("Foo(true, 10/20)", format!("{Foo:?}")); - assert_eq!( - "Foo( - true, - 10/20, -)", - format!("{Foo:#?}") - ); - } - - #[test] - fn test_nested() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_tuple("Foo").field(&true).field(&format_args!("{}/{}", 10, 20)).finish() - } - } - - struct Bar; - - impl fmt::Debug for Bar { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_tuple("Bar").field(&Foo).field(&"world").finish() - } - } - - assert_eq!("Bar(Foo(true, 10/20), \"world\")", format!("{Bar:?}")); - assert_eq!( - "Bar( - Foo( - true, - 10/20, - ), - \"world\", -)", - format!("{Bar:#?}") - ); - } -} - -mod debug_map { - use std::fmt; - - #[test] - fn test_empty() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_map().finish() - } - } - - assert_eq!("{}", format!("{Foo:?}")); - assert_eq!("{}", format!("{Foo:#?}")); - } - - #[test] - fn test_single() { - struct Entry; - - impl fmt::Debug for Entry { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_map().entry(&"bar", &true).finish() - } - } - - struct KeyValue; - - impl fmt::Debug for KeyValue { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_map().key(&"bar").value(&true).finish() - } - } - - assert_eq!(format!("{Entry:?}"), format!("{KeyValue:?}")); - assert_eq!(format!("{Entry:#?}"), format!("{KeyValue:#?}")); - - assert_eq!("{\"bar\": true}", format!("{Entry:?}")); - assert_eq!( - "{ - \"bar\": true, -}", - format!("{Entry:#?}") - ); - } - - #[test] - fn test_multiple() { - struct Entry; - - impl fmt::Debug for Entry { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_map() - .entry(&"bar", &true) - .entry(&10, &format_args!("{}/{}", 10, 20)) - .finish() - } - } - - struct KeyValue; - - impl fmt::Debug for KeyValue { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_map() - .key(&"bar") - .value(&true) - .key(&10) - .value(&format_args!("{}/{}", 10, 20)) - .finish() - } - } - - assert_eq!(format!("{Entry:?}"), format!("{KeyValue:?}")); - assert_eq!(format!("{Entry:#?}"), format!("{KeyValue:#?}")); - - assert_eq!("{\"bar\": true, 10: 10/20}", format!("{Entry:?}")); - assert_eq!( - "{ - \"bar\": true, - 10: 10/20, -}", - format!("{Entry:#?}") - ); - } - - #[test] - fn test_nested() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_map() - .entry(&"bar", &true) - .entry(&10, &format_args!("{}/{}", 10, 20)) - .finish() - } - } - - struct Bar; - - impl fmt::Debug for Bar { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_map().entry(&"foo", &Foo).entry(&Foo, &"world").finish() - } - } - - assert_eq!( - "{\"foo\": {\"bar\": true, 10: 10/20}, \ - {\"bar\": true, 10: 10/20}: \"world\"}", - format!("{Bar:?}") - ); - assert_eq!( - "{ - \"foo\": { - \"bar\": true, - 10: 10/20, - }, - { - \"bar\": true, - 10: 10/20, - }: \"world\", -}", - format!("{Bar:#?}") - ); - } - - #[test] - fn test_entry_err() { - // Ensure errors in a map entry don't trigger panics (#65231) - use std::fmt::Write; - - struct ErrorFmt; - - impl fmt::Debug for ErrorFmt { - fn fmt(&self, _: &mut fmt::Formatter<'_>) -> fmt::Result { - Err(fmt::Error) - } - } - - struct KeyValue(usize, K, V); - - impl fmt::Debug for KeyValue - where - K: fmt::Debug, - V: fmt::Debug, - { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - let mut map = fmt.debug_map(); - - for _ in 0..self.0 { - map.entry(&self.1, &self.2); - } - - map.finish() - } - } - - let mut buf = String::new(); - - assert!(write!(&mut buf, "{:?}", KeyValue(1, ErrorFmt, "bar")).is_err()); - assert!(write!(&mut buf, "{:?}", KeyValue(1, "foo", ErrorFmt)).is_err()); - - assert!(write!(&mut buf, "{:?}", KeyValue(2, ErrorFmt, "bar")).is_err()); - assert!(write!(&mut buf, "{:?}", KeyValue(2, "foo", ErrorFmt)).is_err()); - } - - #[test] - #[should_panic] - fn test_invalid_key_when_entry_is_incomplete() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_map().key(&"bar").key(&"invalid").finish() - } - } - - format!("{Foo:?}"); - } - - #[test] - #[should_panic] - fn test_invalid_finish_incomplete_entry() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_map().key(&"bar").finish() - } - } - - format!("{Foo:?}"); - } - - #[test] - #[should_panic] - fn test_invalid_value_before_key() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_map().value(&"invalid").key(&"bar").finish() - } - } - - format!("{Foo:?}"); - } -} - -mod debug_set { - use std::fmt; - - #[test] - fn test_empty() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_set().finish() - } - } - - assert_eq!("{}", format!("{Foo:?}")); - assert_eq!("{}", format!("{Foo:#?}")); - } - - #[test] - fn test_single() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_set().entry(&true).finish() - } - } - - assert_eq!("{true}", format!("{Foo:?}")); - assert_eq!( - "{ - true, -}", - format!("{Foo:#?}") - ); - } - - #[test] - fn test_multiple() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_set().entry(&true).entry(&format_args!("{}/{}", 10, 20)).finish() - } - } - - assert_eq!("{true, 10/20}", format!("{Foo:?}")); - assert_eq!( - "{ - true, - 10/20, -}", - format!("{Foo:#?}") - ); - } - - #[test] - fn test_nested() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_set().entry(&true).entry(&format_args!("{}/{}", 10, 20)).finish() - } - } - - struct Bar; - - impl fmt::Debug for Bar { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_set().entry(&Foo).entry(&"world").finish() - } - } - - assert_eq!("{{true, 10/20}, \"world\"}", format!("{Bar:?}")); - assert_eq!( - "{ - { - true, - 10/20, - }, - \"world\", -}", - format!("{Bar:#?}") - ); - } -} - -mod debug_list { - use std::fmt; - - #[test] - fn test_empty() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_list().finish() - } - } - - assert_eq!("[]", format!("{Foo:?}")); - assert_eq!("[]", format!("{Foo:#?}")); - } - - #[test] - fn test_single() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_list().entry(&true).finish() - } - } - - assert_eq!("[true]", format!("{Foo:?}")); - assert_eq!( - "[ - true, -]", - format!("{Foo:#?}") - ); - } - - #[test] - fn test_multiple() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_list().entry(&true).entry(&format_args!("{}/{}", 10, 20)).finish() - } - } - - assert_eq!("[true, 10/20]", format!("{Foo:?}")); - assert_eq!( - "[ - true, - 10/20, -]", - format!("{Foo:#?}") - ); - } - - #[test] - fn test_nested() { - struct Foo; - - impl fmt::Debug for Foo { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_list().entry(&true).entry(&format_args!("{}/{}", 10, 20)).finish() - } - } - - struct Bar; - - impl fmt::Debug for Bar { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_list().entry(&Foo).entry(&"world").finish() - } - } - - assert_eq!("[[true, 10/20], \"world\"]", format!("{Bar:?}")); - assert_eq!( - "[ - [ - true, - 10/20, - ], - \"world\", -]", - format!("{Bar:#?}") - ); - } -} - -#[test] -fn test_formatting_parameters_are_forwarded() { - use std::collections::{BTreeMap, BTreeSet}; - #[derive(Debug)] - #[allow(dead_code)] - struct Foo { - bar: u32, - baz: u32, - } - let struct_ = Foo { bar: 1024, baz: 7 }; - let tuple = (1024, 7); - let list = [1024, 7]; - let mut map = BTreeMap::new(); - map.insert("bar", 1024); - map.insert("baz", 7); - let mut set = BTreeSet::new(); - set.insert(1024); - set.insert(7); - - assert_eq!(format!("{struct_:03?}"), "Foo { bar: 1024, baz: 007 }"); - assert_eq!(format!("{tuple:03?}"), "(1024, 007)"); - assert_eq!(format!("{list:03?}"), "[1024, 007]"); - assert_eq!(format!("{map:03?}"), r#"{"bar": 1024, "baz": 007}"#); - assert_eq!(format!("{set:03?}"), "{007, 1024}"); - assert_eq!( - format!("{struct_:#03?}"), - " -Foo { - bar: 1024, - baz: 007, -} - " - .trim() - ); - assert_eq!( - format!("{tuple:#03?}"), - " -( - 1024, - 007, -) - " - .trim() - ); - assert_eq!( - format!("{list:#03?}"), - " -[ - 1024, - 007, -] - " - .trim() - ); - assert_eq!( - format!("{map:#03?}"), - r#" -{ - "bar": 1024, - "baz": 007, -} - "# - .trim() - ); - assert_eq!( - format!("{set:#03?}"), - " -{ - 007, - 1024, -} - " - .trim() - ); -} diff --git a/library/core/tests/fmt/float.rs b/library/core/tests/fmt/float.rs deleted file mode 100644 index 003782f34dc93..0000000000000 --- a/library/core/tests/fmt/float.rs +++ /dev/null @@ -1,175 +0,0 @@ -#[test] -fn test_format_f64() { - assert_eq!("1", format!("{:.0}", 1.0f64)); - assert_eq!("9", format!("{:.0}", 9.4f64)); - assert_eq!("10", format!("{:.0}", 9.9f64)); - assert_eq!("9.8", format!("{:.1}", 9.849f64)); - assert_eq!("9.9", format!("{:.1}", 9.851f64)); - assert_eq!("0", format!("{:.0}", 0.5f64)); - assert_eq!("1.23456789e6", format!("{:e}", 1234567.89f64)); - assert_eq!("1.23456789e3", format!("{:e}", 1234.56789f64)); - assert_eq!("1.23456789E6", format!("{:E}", 1234567.89f64)); - assert_eq!("1.23456789E3", format!("{:E}", 1234.56789f64)); - assert_eq!("0.0", format!("{:?}", 0.0f64)); - assert_eq!("1.01", format!("{:?}", 1.01f64)); - - let high_cutoff = 1e16_f64; - assert_eq!("1e16", format!("{:?}", high_cutoff)); - assert_eq!("-1e16", format!("{:?}", -high_cutoff)); - assert!(!is_exponential(&format!("{:?}", high_cutoff * (1.0 - 2.0 * f64::EPSILON)))); - assert_eq!("-3.0", format!("{:?}", -3f64)); - assert_eq!("0.0001", format!("{:?}", 0.0001f64)); - assert_eq!("9e-5", format!("{:?}", 0.00009f64)); - assert_eq!("1234567.9", format!("{:.1?}", 1234567.89f64)); - assert_eq!("1234.6", format!("{:.1?}", 1234.56789f64)); -} - -#[test] -fn test_format_f64_rounds_ties_to_even() { - assert_eq!("0", format!("{:.0}", 0.5f64)); - assert_eq!("2", format!("{:.0}", 1.5f64)); - assert_eq!("2", format!("{:.0}", 2.5f64)); - assert_eq!("4", format!("{:.0}", 3.5f64)); - assert_eq!("4", format!("{:.0}", 4.5f64)); - assert_eq!("6", format!("{:.0}", 5.5f64)); - assert_eq!("128", format!("{:.0}", 127.5f64)); - assert_eq!("128", format!("{:.0}", 128.5f64)); - assert_eq!("0.2", format!("{:.1}", 0.25f64)); - assert_eq!("0.8", format!("{:.1}", 0.75f64)); - assert_eq!("0.12", format!("{:.2}", 0.125f64)); - assert_eq!("0.88", format!("{:.2}", 0.875f64)); - assert_eq!("0.062", format!("{:.3}", 0.062f64)); - assert_eq!("-0", format!("{:.0}", -0.5f64)); - assert_eq!("-2", format!("{:.0}", -1.5f64)); - assert_eq!("-2", format!("{:.0}", -2.5f64)); - assert_eq!("-4", format!("{:.0}", -3.5f64)); - assert_eq!("-4", format!("{:.0}", -4.5f64)); - assert_eq!("-6", format!("{:.0}", -5.5f64)); - assert_eq!("-128", format!("{:.0}", -127.5f64)); - assert_eq!("-128", format!("{:.0}", -128.5f64)); - assert_eq!("-0.2", format!("{:.1}", -0.25f64)); - assert_eq!("-0.8", format!("{:.1}", -0.75f64)); - assert_eq!("-0.12", format!("{:.2}", -0.125f64)); - assert_eq!("-0.88", format!("{:.2}", -0.875f64)); - assert_eq!("-0.062", format!("{:.3}", -0.062f64)); - - assert_eq!("2e0", format!("{:.0e}", 1.5f64)); - assert_eq!("2e0", format!("{:.0e}", 2.5f64)); - assert_eq!("4e0", format!("{:.0e}", 3.5f64)); - assert_eq!("4e0", format!("{:.0e}", 4.5f64)); - assert_eq!("6e0", format!("{:.0e}", 5.5f64)); - assert_eq!("1.28e2", format!("{:.2e}", 127.5f64)); - assert_eq!("1.28e2", format!("{:.2e}", 128.5f64)); - assert_eq!("-2e0", format!("{:.0e}", -1.5f64)); - assert_eq!("-2e0", format!("{:.0e}", -2.5f64)); - assert_eq!("-4e0", format!("{:.0e}", -3.5f64)); - assert_eq!("-4e0", format!("{:.0e}", -4.5f64)); - assert_eq!("-6e0", format!("{:.0e}", -5.5f64)); - assert_eq!("-1.28e2", format!("{:.2e}", -127.5f64)); - assert_eq!("-1.28e2", format!("{:.2e}", -128.5f64)); - - assert_eq!("2E0", format!("{:.0E}", 1.5f64)); - assert_eq!("2E0", format!("{:.0E}", 2.5f64)); - assert_eq!("4E0", format!("{:.0E}", 3.5f64)); - assert_eq!("4E0", format!("{:.0E}", 4.5f64)); - assert_eq!("6E0", format!("{:.0E}", 5.5f64)); - assert_eq!("1.28E2", format!("{:.2E}", 127.5f64)); - assert_eq!("1.28E2", format!("{:.2E}", 128.5f64)); - assert_eq!("-2E0", format!("{:.0E}", -1.5f64)); - assert_eq!("-2E0", format!("{:.0E}", -2.5f64)); - assert_eq!("-4E0", format!("{:.0E}", -3.5f64)); - assert_eq!("-4E0", format!("{:.0E}", -4.5f64)); - assert_eq!("-6E0", format!("{:.0E}", -5.5f64)); - assert_eq!("-1.28E2", format!("{:.2E}", -127.5f64)); - assert_eq!("-1.28E2", format!("{:.2E}", -128.5f64)); -} - -#[test] -fn test_format_f32() { - assert_eq!("1", format!("{:.0}", 1.0f32)); - assert_eq!("9", format!("{:.0}", 9.4f32)); - assert_eq!("10", format!("{:.0}", 9.9f32)); - assert_eq!("9.8", format!("{:.1}", 9.849f32)); - assert_eq!("9.9", format!("{:.1}", 9.851f32)); - assert_eq!("0", format!("{:.0}", 0.5f32)); - assert_eq!("1.2345679e6", format!("{:e}", 1234567.89f32)); - assert_eq!("1.2345679e3", format!("{:e}", 1234.56789f32)); - assert_eq!("1.2345679E6", format!("{:E}", 1234567.89f32)); - assert_eq!("1.2345679E3", format!("{:E}", 1234.56789f32)); - assert_eq!("0.0", format!("{:?}", 0.0f32)); - assert_eq!("1.01", format!("{:?}", 1.01f32)); - - let high_cutoff = 1e16_f32; - assert_eq!("1e16", format!("{:?}", high_cutoff)); - assert_eq!("-1e16", format!("{:?}", -high_cutoff)); - assert!(!is_exponential(&format!("{:?}", high_cutoff * (1.0 - 2.0 * f32::EPSILON)))); - assert_eq!("-3.0", format!("{:?}", -3f32)); - assert_eq!("0.0001", format!("{:?}", 0.0001f32)); - assert_eq!("9e-5", format!("{:?}", 0.00009f32)); - assert_eq!("1234567.9", format!("{:.1?}", 1234567.89f32)); - assert_eq!("1234.6", format!("{:.1?}", 1234.56789f32)); -} - -#[test] -fn test_format_f32_rounds_ties_to_even() { - assert_eq!("0", format!("{:.0}", 0.5f32)); - assert_eq!("2", format!("{:.0}", 1.5f32)); - assert_eq!("2", format!("{:.0}", 2.5f32)); - assert_eq!("4", format!("{:.0}", 3.5f32)); - assert_eq!("4", format!("{:.0}", 4.5f32)); - assert_eq!("6", format!("{:.0}", 5.5f32)); - assert_eq!("128", format!("{:.0}", 127.5f32)); - assert_eq!("128", format!("{:.0}", 128.5f32)); - assert_eq!("0.2", format!("{:.1}", 0.25f32)); - assert_eq!("0.8", format!("{:.1}", 0.75f32)); - assert_eq!("0.12", format!("{:.2}", 0.125f32)); - assert_eq!("0.88", format!("{:.2}", 0.875f32)); - assert_eq!("0.062", format!("{:.3}", 0.062f32)); - assert_eq!("-0", format!("{:.0}", -0.5f32)); - assert_eq!("-2", format!("{:.0}", -1.5f32)); - assert_eq!("-2", format!("{:.0}", -2.5f32)); - assert_eq!("-4", format!("{:.0}", -3.5f32)); - assert_eq!("-4", format!("{:.0}", -4.5f32)); - assert_eq!("-6", format!("{:.0}", -5.5f32)); - assert_eq!("-128", format!("{:.0}", -127.5f32)); - assert_eq!("-128", format!("{:.0}", -128.5f32)); - assert_eq!("-0.2", format!("{:.1}", -0.25f32)); - assert_eq!("-0.8", format!("{:.1}", -0.75f32)); - assert_eq!("-0.12", format!("{:.2}", -0.125f32)); - assert_eq!("-0.88", format!("{:.2}", -0.875f32)); - assert_eq!("-0.062", format!("{:.3}", -0.062f32)); - - assert_eq!("2e0", format!("{:.0e}", 1.5f32)); - assert_eq!("2e0", format!("{:.0e}", 2.5f32)); - assert_eq!("4e0", format!("{:.0e}", 3.5f32)); - assert_eq!("4e0", format!("{:.0e}", 4.5f32)); - assert_eq!("6e0", format!("{:.0e}", 5.5f32)); - assert_eq!("1.28e2", format!("{:.2e}", 127.5f32)); - assert_eq!("1.28e2", format!("{:.2e}", 128.5f32)); - assert_eq!("-2e0", format!("{:.0e}", -1.5f32)); - assert_eq!("-2e0", format!("{:.0e}", -2.5f32)); - assert_eq!("-4e0", format!("{:.0e}", -3.5f32)); - assert_eq!("-4e0", format!("{:.0e}", -4.5f32)); - assert_eq!("-6e0", format!("{:.0e}", -5.5f32)); - assert_eq!("-1.28e2", format!("{:.2e}", -127.5f32)); - assert_eq!("-1.28e2", format!("{:.2e}", -128.5f32)); - - assert_eq!("2E0", format!("{:.0E}", 1.5f32)); - assert_eq!("2E0", format!("{:.0E}", 2.5f32)); - assert_eq!("4E0", format!("{:.0E}", 3.5f32)); - assert_eq!("4E0", format!("{:.0E}", 4.5f32)); - assert_eq!("6E0", format!("{:.0E}", 5.5f32)); - assert_eq!("1.28E2", format!("{:.2E}", 127.5f32)); - assert_eq!("1.28E2", format!("{:.2E}", 128.5f32)); - assert_eq!("-2E0", format!("{:.0E}", -1.5f32)); - assert_eq!("-2E0", format!("{:.0E}", -2.5f32)); - assert_eq!("-4E0", format!("{:.0E}", -3.5f32)); - assert_eq!("-4E0", format!("{:.0E}", -4.5f32)); - assert_eq!("-6E0", format!("{:.0E}", -5.5f32)); - assert_eq!("-1.28E2", format!("{:.2E}", -127.5f32)); - assert_eq!("-1.28E2", format!("{:.2E}", -128.5f32)); -} - -fn is_exponential(s: &str) -> bool { - s.contains("e") || s.contains("E") -} diff --git a/library/core/tests/fmt/mod.rs b/library/core/tests/fmt/mod.rs deleted file mode 100644 index 704d246139947..0000000000000 --- a/library/core/tests/fmt/mod.rs +++ /dev/null @@ -1,45 +0,0 @@ -mod builders; -mod float; -mod num; - -#[test] -fn test_format_flags() { - // No residual flags left by pointer formatting - let p = "".as_ptr(); - assert_eq!(format!("{:p} {:x}", p, 16), format!("{p:p} 10")); - - assert_eq!(format!("{: >3}", 'a'), " a"); -} - -#[test] -fn test_pointer_formats_data_pointer() { - let b: &[u8] = b""; - let s: &str = ""; - assert_eq!(format!("{s:p}"), format!("{:p}", s.as_ptr())); - assert_eq!(format!("{b:p}"), format!("{:p}", b.as_ptr())); -} - -#[test] -fn test_estimated_capacity() { - assert_eq!(format_args!("").estimated_capacity(), 0); - assert_eq!(format_args!("{}", { "" }).estimated_capacity(), 0); - assert_eq!(format_args!("Hello").estimated_capacity(), 5); - assert_eq!(format_args!("Hello, {}!", { "" }).estimated_capacity(), 16); - assert_eq!(format_args!("{}, hello!", { "World" }).estimated_capacity(), 0); - assert_eq!(format_args!("{}. 16-bytes piece", { "World" }).estimated_capacity(), 32); -} - -#[test] -fn pad_integral_resets() { - struct Bar; - - impl core::fmt::Display for Bar { - fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { - "1".fmt(f)?; - f.pad_integral(true, "", "5")?; - "1".fmt(f) - } - } - - assert_eq!(format!("{Bar:<03}"), "1 0051 "); -} diff --git a/library/core/tests/fmt/num.rs b/library/core/tests/fmt/num.rs deleted file mode 100644 index bc387a46ea7dd..0000000000000 --- a/library/core/tests/fmt/num.rs +++ /dev/null @@ -1,240 +0,0 @@ -#[test] -fn test_format_int() { - // Formatting integers should select the right implementation based off - // the type of the argument. Also, hex/octal/binary should be defined - // for integers, but they shouldn't emit the negative sign. - assert_eq!(format!("{}", 1isize), "1"); - assert_eq!(format!("{}", 1i8), "1"); - assert_eq!(format!("{}", 1i16), "1"); - assert_eq!(format!("{}", 1i32), "1"); - assert_eq!(format!("{}", 1i64), "1"); - assert_eq!(format!("{}", -1isize), "-1"); - assert_eq!(format!("{}", -1i8), "-1"); - assert_eq!(format!("{}", -1i16), "-1"); - assert_eq!(format!("{}", -1i32), "-1"); - assert_eq!(format!("{}", -1i64), "-1"); - assert_eq!(format!("{:?}", 1isize), "1"); - assert_eq!(format!("{:?}", 1i8), "1"); - assert_eq!(format!("{:?}", 1i16), "1"); - assert_eq!(format!("{:?}", 1i32), "1"); - assert_eq!(format!("{:?}", 1i64), "1"); - assert_eq!(format!("{:b}", 1isize), "1"); - assert_eq!(format!("{:b}", 1i8), "1"); - assert_eq!(format!("{:b}", 1i16), "1"); - assert_eq!(format!("{:b}", 1i32), "1"); - assert_eq!(format!("{:b}", 1i64), "1"); - assert_eq!(format!("{:x}", 1isize), "1"); - assert_eq!(format!("{:x}", 1i8), "1"); - assert_eq!(format!("{:x}", 1i16), "1"); - assert_eq!(format!("{:x}", 1i32), "1"); - assert_eq!(format!("{:x}", 1i64), "1"); - assert_eq!(format!("{:X}", 1isize), "1"); - assert_eq!(format!("{:X}", 1i8), "1"); - assert_eq!(format!("{:X}", 1i16), "1"); - assert_eq!(format!("{:X}", 1i32), "1"); - assert_eq!(format!("{:X}", 1i64), "1"); - assert_eq!(format!("{:o}", 1isize), "1"); - assert_eq!(format!("{:o}", 1i8), "1"); - assert_eq!(format!("{:o}", 1i16), "1"); - assert_eq!(format!("{:o}", 1i32), "1"); - assert_eq!(format!("{:o}", 1i64), "1"); - assert_eq!(format!("{:e}", 1isize), "1e0"); - assert_eq!(format!("{:e}", 1i8), "1e0"); - assert_eq!(format!("{:e}", 1i16), "1e0"); - assert_eq!(format!("{:e}", 1i32), "1e0"); - assert_eq!(format!("{:e}", 1i64), "1e0"); - assert_eq!(format!("{:E}", 1isize), "1E0"); - assert_eq!(format!("{:E}", 1i8), "1E0"); - assert_eq!(format!("{:E}", 1i16), "1E0"); - assert_eq!(format!("{:E}", 1i32), "1E0"); - assert_eq!(format!("{:E}", 1i64), "1E0"); - - assert_eq!(format!("{}", 1usize), "1"); - assert_eq!(format!("{}", 1u8), "1"); - assert_eq!(format!("{}", 1u16), "1"); - assert_eq!(format!("{}", 1u32), "1"); - assert_eq!(format!("{}", 1u64), "1"); - assert_eq!(format!("{:?}", 1usize), "1"); - assert_eq!(format!("{:?}", 1u8), "1"); - assert_eq!(format!("{:?}", 1u16), "1"); - assert_eq!(format!("{:?}", 1u32), "1"); - assert_eq!(format!("{:?}", 1u64), "1"); - assert_eq!(format!("{:b}", 1usize), "1"); - assert_eq!(format!("{:b}", 1u8), "1"); - assert_eq!(format!("{:b}", 1u16), "1"); - assert_eq!(format!("{:b}", 1u32), "1"); - assert_eq!(format!("{:b}", 1u64), "1"); - assert_eq!(format!("{:x}", 1usize), "1"); - assert_eq!(format!("{:x}", 1u8), "1"); - assert_eq!(format!("{:x}", 1u16), "1"); - assert_eq!(format!("{:x}", 1u32), "1"); - assert_eq!(format!("{:x}", 1u64), "1"); - assert_eq!(format!("{:X}", 1usize), "1"); - assert_eq!(format!("{:X}", 1u8), "1"); - assert_eq!(format!("{:X}", 1u16), "1"); - assert_eq!(format!("{:X}", 1u32), "1"); - assert_eq!(format!("{:X}", 1u64), "1"); - assert_eq!(format!("{:o}", 1usize), "1"); - assert_eq!(format!("{:o}", 1u8), "1"); - assert_eq!(format!("{:o}", 1u16), "1"); - assert_eq!(format!("{:o}", 1u32), "1"); - assert_eq!(format!("{:o}", 1u64), "1"); - assert_eq!(format!("{:e}", 1u8), "1e0"); - assert_eq!(format!("{:e}", 1u16), "1e0"); - assert_eq!(format!("{:e}", 1u32), "1e0"); - assert_eq!(format!("{:e}", 1u64), "1e0"); - assert_eq!(format!("{:E}", 1u8), "1E0"); - assert_eq!(format!("{:E}", 1u16), "1E0"); - assert_eq!(format!("{:E}", 1u32), "1E0"); - assert_eq!(format!("{:E}", 1u64), "1E0"); - - // Test a larger number - assert_eq!(format!("{:b}", 55), "110111"); - assert_eq!(format!("{:o}", 55), "67"); - assert_eq!(format!("{}", 55), "55"); - assert_eq!(format!("{:x}", 55), "37"); - assert_eq!(format!("{:X}", 55), "37"); - assert_eq!(format!("{:e}", 55), "5.5e1"); - assert_eq!(format!("{:E}", 55), "5.5E1"); - assert_eq!(format!("{:e}", 10000000000u64), "1e10"); - assert_eq!(format!("{:E}", 10000000000u64), "1E10"); - assert_eq!(format!("{:e}", 10000000001u64), "1.0000000001e10"); - assert_eq!(format!("{:E}", 10000000001u64), "1.0000000001E10"); -} - -#[test] -fn test_format_int_exp_limits() { - assert_eq!(format!("{:e}", i8::MIN), "-1.28e2"); - assert_eq!(format!("{:e}", i8::MAX), "1.27e2"); - assert_eq!(format!("{:e}", i16::MIN), "-3.2768e4"); - assert_eq!(format!("{:e}", i16::MAX), "3.2767e4"); - assert_eq!(format!("{:e}", i32::MIN), "-2.147483648e9"); - assert_eq!(format!("{:e}", i32::MAX), "2.147483647e9"); - assert_eq!(format!("{:e}", i64::MIN), "-9.223372036854775808e18"); - assert_eq!(format!("{:e}", i64::MAX), "9.223372036854775807e18"); - assert_eq!(format!("{:e}", i128::MIN), "-1.70141183460469231731687303715884105728e38"); - assert_eq!(format!("{:e}", i128::MAX), "1.70141183460469231731687303715884105727e38"); - - assert_eq!(format!("{:e}", u8::MAX), "2.55e2"); - assert_eq!(format!("{:e}", u16::MAX), "6.5535e4"); - assert_eq!(format!("{:e}", u32::MAX), "4.294967295e9"); - assert_eq!(format!("{:e}", u64::MAX), "1.8446744073709551615e19"); - assert_eq!(format!("{:e}", u128::MAX), "3.40282366920938463463374607431768211455e38"); -} - -#[test] -fn test_format_int_exp_precision() { - //test that float and integer match - let big_int: u32 = 314_159_265; - assert_eq!(format!("{big_int:.1e}"), format!("{:.1e}", f64::from(big_int))); - - // test adding precision - assert_eq!(format!("{:.10e}", i8::MIN), "-1.2800000000e2"); - assert_eq!(format!("{:.10e}", i16::MIN), "-3.2768000000e4"); - assert_eq!(format!("{:.10e}", i32::MIN), "-2.1474836480e9"); - assert_eq!(format!("{:.20e}", i64::MIN), "-9.22337203685477580800e18"); - assert_eq!(format!("{:.40e}", i128::MIN), "-1.7014118346046923173168730371588410572800e38"); - - // test rounding - assert_eq!(format!("{:.1e}", i8::MIN), "-1.3e2"); - assert_eq!(format!("{:.1e}", i16::MIN), "-3.3e4"); - assert_eq!(format!("{:.1e}", i32::MIN), "-2.1e9"); - assert_eq!(format!("{:.1e}", i64::MIN), "-9.2e18"); - assert_eq!(format!("{:.1e}", i128::MIN), "-1.7e38"); - - // test huge precision - assert_eq!(format!("{:.1000e}", 1), format!("1.{}e0", "0".repeat(1000))); - //test zero precision - assert_eq!(format!("{:.0e}", 1), format!("1e0",)); - assert_eq!(format!("{:.0e}", 35), format!("4e1",)); - - // test padding with precision (and sign) - assert_eq!(format!("{:+10.3e}", 1), " +1.000e0"); - - // test precision remains correct when rounding to next power - #[cfg(miri)] // can't cover all of `i16` in Miri - let range = [i16::MIN, -1, 1, i16::MAX]; - #[cfg(not(miri))] - let range = i16::MIN..=i16::MAX; - for i in range { - for p in 0..=5 { - assert_eq!( - format!("{i:.p$e}"), - format!("{:.p$e}", f32::from(i)), - "integer {i} at precision {p}" - ); - } - } -} - -#[test] -fn test_format_int_zero() { - assert_eq!(format!("{}", 0), "0"); - assert_eq!(format!("{:?}", 0), "0"); - assert_eq!(format!("{:b}", 0), "0"); - assert_eq!(format!("{:o}", 0), "0"); - assert_eq!(format!("{:x}", 0), "0"); - assert_eq!(format!("{:X}", 0), "0"); - assert_eq!(format!("{:e}", 0), "0e0"); - assert_eq!(format!("{:E}", 0), "0E0"); - - assert_eq!(format!("{}", 0u32), "0"); - assert_eq!(format!("{:?}", 0u32), "0"); - assert_eq!(format!("{:b}", 0u32), "0"); - assert_eq!(format!("{:o}", 0u32), "0"); - assert_eq!(format!("{:x}", 0u32), "0"); - assert_eq!(format!("{:X}", 0u32), "0"); - assert_eq!(format!("{:e}", 0u32), "0e0"); - assert_eq!(format!("{:E}", 0u32), "0E0"); -} - -#[test] -fn test_format_int_flags() { - assert_eq!(format!("{:3}", 1), " 1"); - assert_eq!(format!("{:>3}", 1), " 1"); - assert_eq!(format!("{:>+3}", 1), " +1"); - assert_eq!(format!("{:<3}", 1), "1 "); - assert_eq!(format!("{:#}", 1), "1"); - assert_eq!(format!("{:#x}", 10), "0xa"); - assert_eq!(format!("{:#X}", 10), "0xA"); - assert_eq!(format!("{:#5x}", 10), " 0xa"); - assert_eq!(format!("{:#o}", 10), "0o12"); - assert_eq!(format!("{:08x}", 10), "0000000a"); - assert_eq!(format!("{:8x}", 10), " a"); - assert_eq!(format!("{:<8x}", 10), "a "); - assert_eq!(format!("{:>8x}", 10), " a"); - assert_eq!(format!("{:#08x}", 10), "0x00000a"); - assert_eq!(format!("{:08}", -10), "-0000010"); - assert_eq!(format!("{:x}", !0u8), "ff"); - assert_eq!(format!("{:X}", !0u8), "FF"); - assert_eq!(format!("{:b}", !0u8), "11111111"); - assert_eq!(format!("{:o}", !0u8), "377"); - assert_eq!(format!("{:#x}", !0u8), "0xff"); - assert_eq!(format!("{:#X}", !0u8), "0xFF"); - assert_eq!(format!("{:#b}", !0u8), "0b11111111"); - assert_eq!(format!("{:#o}", !0u8), "0o377"); -} - -#[test] -fn test_format_int_sign_padding() { - assert_eq!(format!("{:+5}", 1), " +1"); - assert_eq!(format!("{:+5}", -1), " -1"); - assert_eq!(format!("{:05}", 1), "00001"); - assert_eq!(format!("{:05}", -1), "-0001"); - assert_eq!(format!("{:+05}", 1), "+0001"); - assert_eq!(format!("{:+05}", -1), "-0001"); -} - -#[test] -fn test_format_int_twos_complement() { - assert_eq!(format!("{}", i8::MIN), "-128"); - assert_eq!(format!("{}", i16::MIN), "-32768"); - assert_eq!(format!("{}", i32::MIN), "-2147483648"); - assert_eq!(format!("{}", i64::MIN), "-9223372036854775808"); -} - -#[test] -fn test_format_debug_hex() { - assert_eq!(format!("{:02x?}", b"Foo\0"), "[46, 6f, 6f, 00]"); - assert_eq!(format!("{:02X?}", b"Foo\0"), "[46, 6F, 6F, 00]"); -} diff --git a/library/core/tests/future.rs b/library/core/tests/future.rs deleted file mode 100644 index db417256dd01e..0000000000000 --- a/library/core/tests/future.rs +++ /dev/null @@ -1,127 +0,0 @@ -use std::future::{join, Future}; -use std::pin::Pin; -use std::sync::Arc; -use std::task::{Context, Poll, Wake}; -use std::thread; - -struct PollN { - val: usize, - polled: usize, - num: usize, -} - -impl Future for PollN { - type Output = usize; - - fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll { - self.polled += 1; - - if self.polled == self.num { - return Poll::Ready(self.val); - } - - cx.waker().wake_by_ref(); - Poll::Pending - } -} - -fn poll_n(val: usize, num: usize) -> PollN { - PollN { val, num, polled: 0 } -} - -#[test] -fn test_join() { - block_on(async move { - let x = join!(async { 0 }).await; - assert_eq!(x, 0); - - let x = join!(async { 0 }, async { 1 }).await; - assert_eq!(x, (0, 1)); - - let x = join!(async { 0 }, async { 1 }, async { 2 }).await; - assert_eq!(x, (0, 1, 2)); - - let x = join!( - poll_n(0, 1), - poll_n(1, 5), - poll_n(2, 2), - poll_n(3, 1), - poll_n(4, 2), - poll_n(5, 3), - poll_n(6, 4), - poll_n(7, 1) - ) - .await; - assert_eq!(x, (0, 1, 2, 3, 4, 5, 6, 7)); - - let y = String::new(); - let x = join!(async { - println!("{}", &y); - 1 - }) - .await; - assert_eq!(x, 1); - }); -} - -/// Tests that `join!(…)` behaves "like a function": evaluating its arguments -/// before applying any of its own logic. -/// -/// _e.g._, `join!(async_fn(&borrowed), …)` does not consume `borrowed`; -/// and `join!(opt_fut?, …)` does let that `?` refer to the callsite scope. -mod test_join_function_like_value_arg_semantics { - use super::*; - - async fn async_fn(_: impl Sized) {} - - // no need to _run_ this test, just to compile it. - fn _join_does_not_unnecessarily_move_mentioned_bindings() { - let not_copy = vec![()]; - let _ = join!(async_fn(¬_copy)); // should not move `not_copy` - let _ = ¬_copy; // OK - } - - #[test] - fn join_lets_control_flow_effects_such_as_try_flow_through() { - let maybe_fut = None; - if false { - *&mut { maybe_fut } = Some(async {}); - loop {} - } - assert!(Option::is_none(&try { join!(maybe_fut?, async { unreachable!() }) })); - } - - #[test] - fn join_is_able_to_handle_temporaries() { - let _ = join!(async_fn(&String::from("temporary"))); - let () = block_on(join!(async_fn(&String::from("temporary")))); - } -} - -fn block_on(fut: impl Future) { - struct Waker; - impl Wake for Waker { - fn wake(self: Arc) { - thread::current().unpark() - } - } - - let waker = Arc::new(Waker).into(); - let mut cx = Context::from_waker(&waker); - let mut fut = Box::pin(fut); - - loop { - match fut.as_mut().poll(&mut cx) { - Poll::Ready(_) => break, - Poll::Pending => thread::park(), - } - } -} - -// just tests by whether or not this compiles -fn _pending_impl_all_auto_traits() { - use std::panic::{RefUnwindSafe, UnwindSafe}; - fn all_auto_traits() {} - - all_auto_traits::>(); -} diff --git a/library/core/tests/hash/mod.rs b/library/core/tests/hash/mod.rs deleted file mode 100644 index bdd1c2579ded8..0000000000000 --- a/library/core/tests/hash/mod.rs +++ /dev/null @@ -1,182 +0,0 @@ -mod sip; - -use std::hash::{BuildHasher, Hash, Hasher}; -use std::ptr; -use std::rc::Rc; - -struct MyHasher { - hash: u64, -} - -impl Default for MyHasher { - fn default() -> MyHasher { - MyHasher { hash: 0 } - } -} - -impl Hasher for MyHasher { - fn write(&mut self, buf: &[u8]) { - // FIXME(const_trait_impl): change to for loop - let mut i = 0; - while i < buf.len() { - self.hash += buf[i] as u64; - i += 1; - } - } - fn write_str(&mut self, s: &str) { - self.write(s.as_bytes()); - self.write_u8(0xFF); - } - fn finish(&self) -> u64 { - self.hash - } -} - -#[test] -fn test_writer_hasher() { - // FIXME(#110395) - /* const */ - fn hash(t: &T) -> u64 { - let mut s = MyHasher { hash: 0 }; - t.hash(&mut s); - s.finish() - } - - /* const { - // FIXME(fee1-dead): assert_eq - assert!(hash(&()) == 0); - assert!(hash(&5_u8) == 5); - assert!(hash(&5_u16) == 5); - assert!(hash(&5_u32) == 5); - - assert!(hash(&'a') == 97); - - let s: &str = "a"; - assert!(hash(&s) == 97 + 0xFF); - }; */ - - assert_eq!(hash(&()), 0); - - assert_eq!(hash(&5_u8), 5); - assert_eq!(hash(&5_u16), 5); - assert_eq!(hash(&5_u32), 5); - assert_eq!(hash(&5_u64), 5); - assert_eq!(hash(&5_usize), 5); - - assert_eq!(hash(&5_i8), 5); - assert_eq!(hash(&5_i16), 5); - assert_eq!(hash(&5_i32), 5); - assert_eq!(hash(&5_i64), 5); - assert_eq!(hash(&5_isize), 5); - - assert_eq!(hash(&false), 0); - assert_eq!(hash(&true), 1); - - assert_eq!(hash(&'a'), 97); - - let s: &str = "a"; - assert_eq!(hash(&s), 97 + 0xFF); - let s: Box = String::from("a").into_boxed_str(); - assert_eq!(hash(&s), 97 + 0xFF); - let s: Rc<&str> = Rc::new("a"); - assert_eq!(hash(&s), 97 + 0xFF); - let cs: &[u8] = &[1, 2, 3]; - assert_eq!(hash(&cs), 9); - let cs: Box<[u8]> = Box::new([1, 2, 3]); - assert_eq!(hash(&cs), 9); - let cs: Rc<[u8]> = Rc::new([1, 2, 3]); - assert_eq!(hash(&cs), 9); - - let ptr = ptr::without_provenance::(5_usize); - assert_eq!(hash(&ptr), 5); - - let ptr = ptr::without_provenance_mut::(5_usize); - assert_eq!(hash(&ptr), 5); - - if cfg!(miri) { - // Miri cannot hash pointers - return; - } - - let cs: &mut [u8] = &mut [1, 2, 3]; - let ptr = cs.as_ptr(); - let slice_ptr = cs as *const [u8]; - assert_eq!(hash(&slice_ptr), hash(&ptr) + cs.len() as u64); - - let slice_ptr = cs as *mut [u8]; - assert_eq!(hash(&slice_ptr), hash(&ptr) + cs.len() as u64); -} - -struct Custom { - hash: u64, -} -struct CustomHasher { - output: u64, -} - -impl Hasher for CustomHasher { - fn finish(&self) -> u64 { - self.output - } - fn write(&mut self, _: &[u8]) { - panic!() - } - fn write_u64(&mut self, data: u64) { - self.output = data; - } -} - -impl Default for CustomHasher { - fn default() -> CustomHasher { - CustomHasher { output: 0 } - } -} - -impl Hash for Custom { - fn hash(&self, state: &mut H) { - state.write_u64(self.hash); - } -} - -#[test] -fn test_custom_state() { - // FIXME(#110395) - /* const */ - fn hash(t: &T) -> u64 { - let mut c = CustomHasher { output: 0 }; - t.hash(&mut c); - c.finish() - } - - assert_eq!(hash(&Custom { hash: 5 }), 5); - - // const { assert!(hash(&Custom { hash: 6 }) == 6) }; -} - -// FIXME: Instantiated functions with i128 in the signature is not supported in Emscripten. -// See https://github.com/kripken/emscripten-fastcomp/issues/169 -#[cfg(not(target_os = "emscripten"))] -#[test] -fn test_indirect_hasher() { - let mut hasher = MyHasher { hash: 0 }; - { - let mut indirect_hasher: &mut dyn Hasher = &mut hasher; - 5u32.hash(&mut indirect_hasher); - } - assert_eq!(hasher.hash, 5); -} - -#[test] -fn test_build_hasher_object_safe() { - use std::hash::{DefaultHasher, RandomState}; - - let _: &dyn BuildHasher = &RandomState::new(); -} - -// just tests by whether or not this compiles -fn _build_hasher_default_impl_all_auto_traits() { - use std::panic::{RefUnwindSafe, UnwindSafe}; - fn all_auto_traits() {} - - all_auto_traits::>(); -} diff --git a/library/core/tests/hash/sip.rs b/library/core/tests/hash/sip.rs deleted file mode 100644 index 0a67c485c98bb..0000000000000 --- a/library/core/tests/hash/sip.rs +++ /dev/null @@ -1,324 +0,0 @@ -#![allow(deprecated)] - -use core::hash::{Hash, Hasher}; -use core::hash::{SipHasher, SipHasher13}; -use core::{mem, slice}; - -// Hash just the bytes of the slice, without length prefix -struct Bytes<'a>(&'a [u8]); - -impl<'a> Hash for Bytes<'a> { - fn hash(&self, state: &mut H) { - let Bytes(v) = *self; - state.write(v); - } -} - -fn hash_with(mut st: H, x: &T) -> u64 { - x.hash(&mut st); - st.finish() -} - -fn hash(x: &T) -> u64 { - hash_with(SipHasher::new(), x) -} - -/* FIXME(#110395) -#[test] -const fn test_const_sip() { - let val1 = 0x45; - let val2 = 0xfeed; - - const fn const_hash(x: &T) -> u64 { - let mut st = SipHasher::new(); - x.hash(&mut st); - st.finish() - } - - assert!(const_hash(&(val1)) != const_hash(&(val2))); -} -*/ - -#[test] -#[allow(unused_must_use)] -fn test_siphash_1_3() { - let vecs: [[u8; 8]; 64] = [ - [0xdc, 0xc4, 0x0f, 0x05, 0x58, 0x01, 0xac, 0xab], - [0x93, 0xca, 0x57, 0x7d, 0xf3, 0x9b, 0xf4, 0xc9], - [0x4d, 0xd4, 0xc7, 0x4d, 0x02, 0x9b, 0xcb, 0x82], - [0xfb, 0xf7, 0xdd, 0xe7, 0xb8, 0x0a, 0xf8, 0x8b], - [0x28, 0x83, 0xd3, 0x88, 0x60, 0x57, 0x75, 0xcf], - [0x67, 0x3b, 0x53, 0x49, 0x2f, 0xd5, 0xf9, 0xde], - [0xa7, 0x22, 0x9f, 0xc5, 0x50, 0x2b, 0x0d, 0xc5], - [0x40, 0x11, 0xb1, 0x9b, 0x98, 0x7d, 0x92, 0xd3], - [0x8e, 0x9a, 0x29, 0x8d, 0x11, 0x95, 0x90, 0x36], - [0xe4, 0x3d, 0x06, 0x6c, 0xb3, 0x8e, 0xa4, 0x25], - [0x7f, 0x09, 0xff, 0x92, 0xee, 0x85, 0xde, 0x79], - [0x52, 0xc3, 0x4d, 0xf9, 0xc1, 0x18, 0xc1, 0x70], - [0xa2, 0xd9, 0xb4, 0x57, 0xb1, 0x84, 0xa3, 0x78], - [0xa7, 0xff, 0x29, 0x12, 0x0c, 0x76, 0x6f, 0x30], - [0x34, 0x5d, 0xf9, 0xc0, 0x11, 0xa1, 0x5a, 0x60], - [0x56, 0x99, 0x51, 0x2a, 0x6d, 0xd8, 0x20, 0xd3], - [0x66, 0x8b, 0x90, 0x7d, 0x1a, 0xdd, 0x4f, 0xcc], - [0x0c, 0xd8, 0xdb, 0x63, 0x90, 0x68, 0xf2, 0x9c], - [0x3e, 0xe6, 0x73, 0xb4, 0x9c, 0x38, 0xfc, 0x8f], - [0x1c, 0x7d, 0x29, 0x8d, 0xe5, 0x9d, 0x1f, 0xf2], - [0x40, 0xe0, 0xcc, 0xa6, 0x46, 0x2f, 0xdc, 0xc0], - [0x44, 0xf8, 0x45, 0x2b, 0xfe, 0xab, 0x92, 0xb9], - [0x2e, 0x87, 0x20, 0xa3, 0x9b, 0x7b, 0xfe, 0x7f], - [0x23, 0xc1, 0xe6, 0xda, 0x7f, 0x0e, 0x5a, 0x52], - [0x8c, 0x9c, 0x34, 0x67, 0xb2, 0xae, 0x64, 0xf4], - [0x79, 0x09, 0x5b, 0x70, 0x28, 0x59, 0xcd, 0x45], - [0xa5, 0x13, 0x99, 0xca, 0xe3, 0x35, 0x3e, 0x3a], - [0x35, 0x3b, 0xde, 0x4a, 0x4e, 0xc7, 0x1d, 0xa9], - [0x0d, 0xd0, 0x6c, 0xef, 0x02, 0xed, 0x0b, 0xfb], - [0xf4, 0xe1, 0xb1, 0x4a, 0xb4, 0x3c, 0xd9, 0x88], - [0x63, 0xe6, 0xc5, 0x43, 0xd6, 0x11, 0x0f, 0x54], - [0xbc, 0xd1, 0x21, 0x8c, 0x1f, 0xdd, 0x70, 0x23], - [0x0d, 0xb6, 0xa7, 0x16, 0x6c, 0x7b, 0x15, 0x81], - [0xbf, 0xf9, 0x8f, 0x7a, 0xe5, 0xb9, 0x54, 0x4d], - [0x3e, 0x75, 0x2a, 0x1f, 0x78, 0x12, 0x9f, 0x75], - [0x91, 0x6b, 0x18, 0xbf, 0xbe, 0xa3, 0xa1, 0xce], - [0x06, 0x62, 0xa2, 0xad, 0xd3, 0x08, 0xf5, 0x2c], - [0x57, 0x30, 0xc3, 0xa3, 0x2d, 0x1c, 0x10, 0xb6], - [0xa1, 0x36, 0x3a, 0xae, 0x96, 0x74, 0xf4, 0xb3], - [0x92, 0x83, 0x10, 0x7b, 0x54, 0x57, 0x6b, 0x62], - [0x31, 0x15, 0xe4, 0x99, 0x32, 0x36, 0xd2, 0xc1], - [0x44, 0xd9, 0x1a, 0x3f, 0x92, 0xc1, 0x7c, 0x66], - [0x25, 0x88, 0x13, 0xc8, 0xfe, 0x4f, 0x70, 0x65], - [0xa6, 0x49, 0x89, 0xc2, 0xd1, 0x80, 0xf2, 0x24], - [0x6b, 0x87, 0xf8, 0xfa, 0xed, 0x1c, 0xca, 0xc2], - [0x96, 0x21, 0x04, 0x9f, 0xfc, 0x4b, 0x16, 0xc2], - [0x23, 0xd6, 0xb1, 0x68, 0x93, 0x9c, 0x6e, 0xa1], - [0xfd, 0x14, 0x51, 0x8b, 0x9c, 0x16, 0xfb, 0x49], - [0x46, 0x4c, 0x07, 0xdf, 0xf8, 0x43, 0x31, 0x9f], - [0xb3, 0x86, 0xcc, 0x12, 0x24, 0xaf, 0xfd, 0xc6], - [0x8f, 0x09, 0x52, 0x0a, 0xd1, 0x49, 0xaf, 0x7e], - [0x9a, 0x2f, 0x29, 0x9d, 0x55, 0x13, 0xf3, 0x1c], - [0x12, 0x1f, 0xf4, 0xa2, 0xdd, 0x30, 0x4a, 0xc4], - [0xd0, 0x1e, 0xa7, 0x43, 0x89, 0xe9, 0xfa, 0x36], - [0xe6, 0xbc, 0xf0, 0x73, 0x4c, 0xb3, 0x8f, 0x31], - [0x80, 0xe9, 0xa7, 0x70, 0x36, 0xbf, 0x7a, 0xa2], - [0x75, 0x6d, 0x3c, 0x24, 0xdb, 0xc0, 0xbc, 0xb4], - [0x13, 0x15, 0xb7, 0xfd, 0x52, 0xd8, 0xf8, 0x23], - [0x08, 0x8a, 0x7d, 0xa6, 0x4d, 0x5f, 0x03, 0x8f], - [0x48, 0xf1, 0xe8, 0xb7, 0xe5, 0xd0, 0x9c, 0xd8], - [0xee, 0x44, 0xa6, 0xf7, 0xbc, 0xe6, 0xf4, 0xf6], - [0xf2, 0x37, 0x18, 0x0f, 0xd8, 0x9a, 0xc5, 0xae], - [0xe0, 0x94, 0x66, 0x4b, 0x15, 0xf6, 0xb2, 0xc3], - [0xa8, 0xb3, 0xbb, 0xb7, 0x62, 0x90, 0x19, 0x9d], - ]; - - let k0 = 0x_07_06_05_04_03_02_01_00; - let k1 = 0x_0f_0e_0d_0c_0b_0a_09_08; - let mut buf = Vec::new(); - let mut t = 0; - let mut state_inc = SipHasher13::new_with_keys(k0, k1); - - while t < 64 { - let vec = u64::from_le_bytes(vecs[t]); - let out = hash_with(SipHasher13::new_with_keys(k0, k1), &Bytes(&buf)); - assert_eq!(vec, out); - - let full = hash_with(SipHasher13::new_with_keys(k0, k1), &Bytes(&buf)); - let i = state_inc.finish(); - - assert_eq!(full, i); - assert_eq!(full, vec); - - buf.push(t as u8); - Hasher::write(&mut state_inc, &[t as u8]); - - t += 1; - } -} - -#[test] -#[allow(unused_must_use)] -fn test_siphash_2_4() { - let vecs: [[u8; 8]; 64] = [ - [0x31, 0x0e, 0x0e, 0xdd, 0x47, 0xdb, 0x6f, 0x72], - [0xfd, 0x67, 0xdc, 0x93, 0xc5, 0x39, 0xf8, 0x74], - [0x5a, 0x4f, 0xa9, 0xd9, 0x09, 0x80, 0x6c, 0x0d], - [0x2d, 0x7e, 0xfb, 0xd7, 0x96, 0x66, 0x67, 0x85], - [0xb7, 0x87, 0x71, 0x27, 0xe0, 0x94, 0x27, 0xcf], - [0x8d, 0xa6, 0x99, 0xcd, 0x64, 0x55, 0x76, 0x18], - [0xce, 0xe3, 0xfe, 0x58, 0x6e, 0x46, 0xc9, 0xcb], - [0x37, 0xd1, 0x01, 0x8b, 0xf5, 0x00, 0x02, 0xab], - [0x62, 0x24, 0x93, 0x9a, 0x79, 0xf5, 0xf5, 0x93], - [0xb0, 0xe4, 0xa9, 0x0b, 0xdf, 0x82, 0x00, 0x9e], - [0xf3, 0xb9, 0xdd, 0x94, 0xc5, 0xbb, 0x5d, 0x7a], - [0xa7, 0xad, 0x6b, 0x22, 0x46, 0x2f, 0xb3, 0xf4], - [0xfb, 0xe5, 0x0e, 0x86, 0xbc, 0x8f, 0x1e, 0x75], - [0x90, 0x3d, 0x84, 0xc0, 0x27, 0x56, 0xea, 0x14], - [0xee, 0xf2, 0x7a, 0x8e, 0x90, 0xca, 0x23, 0xf7], - [0xe5, 0x45, 0xbe, 0x49, 0x61, 0xca, 0x29, 0xa1], - [0xdb, 0x9b, 0xc2, 0x57, 0x7f, 0xcc, 0x2a, 0x3f], - [0x94, 0x47, 0xbe, 0x2c, 0xf5, 0xe9, 0x9a, 0x69], - [0x9c, 0xd3, 0x8d, 0x96, 0xf0, 0xb3, 0xc1, 0x4b], - [0xbd, 0x61, 0x79, 0xa7, 0x1d, 0xc9, 0x6d, 0xbb], - [0x98, 0xee, 0xa2, 0x1a, 0xf2, 0x5c, 0xd6, 0xbe], - [0xc7, 0x67, 0x3b, 0x2e, 0xb0, 0xcb, 0xf2, 0xd0], - [0x88, 0x3e, 0xa3, 0xe3, 0x95, 0x67, 0x53, 0x93], - [0xc8, 0xce, 0x5c, 0xcd, 0x8c, 0x03, 0x0c, 0xa8], - [0x94, 0xaf, 0x49, 0xf6, 0xc6, 0x50, 0xad, 0xb8], - [0xea, 0xb8, 0x85, 0x8a, 0xde, 0x92, 0xe1, 0xbc], - [0xf3, 0x15, 0xbb, 0x5b, 0xb8, 0x35, 0xd8, 0x17], - [0xad, 0xcf, 0x6b, 0x07, 0x63, 0x61, 0x2e, 0x2f], - [0xa5, 0xc9, 0x1d, 0xa7, 0xac, 0xaa, 0x4d, 0xde], - [0x71, 0x65, 0x95, 0x87, 0x66, 0x50, 0xa2, 0xa6], - [0x28, 0xef, 0x49, 0x5c, 0x53, 0xa3, 0x87, 0xad], - [0x42, 0xc3, 0x41, 0xd8, 0xfa, 0x92, 0xd8, 0x32], - [0xce, 0x7c, 0xf2, 0x72, 0x2f, 0x51, 0x27, 0x71], - [0xe3, 0x78, 0x59, 0xf9, 0x46, 0x23, 0xf3, 0xa7], - [0x38, 0x12, 0x05, 0xbb, 0x1a, 0xb0, 0xe0, 0x12], - [0xae, 0x97, 0xa1, 0x0f, 0xd4, 0x34, 0xe0, 0x15], - [0xb4, 0xa3, 0x15, 0x08, 0xbe, 0xff, 0x4d, 0x31], - [0x81, 0x39, 0x62, 0x29, 0xf0, 0x90, 0x79, 0x02], - [0x4d, 0x0c, 0xf4, 0x9e, 0xe5, 0xd4, 0xdc, 0xca], - [0x5c, 0x73, 0x33, 0x6a, 0x76, 0xd8, 0xbf, 0x9a], - [0xd0, 0xa7, 0x04, 0x53, 0x6b, 0xa9, 0x3e, 0x0e], - [0x92, 0x59, 0x58, 0xfc, 0xd6, 0x42, 0x0c, 0xad], - [0xa9, 0x15, 0xc2, 0x9b, 0xc8, 0x06, 0x73, 0x18], - [0x95, 0x2b, 0x79, 0xf3, 0xbc, 0x0a, 0xa6, 0xd4], - [0xf2, 0x1d, 0xf2, 0xe4, 0x1d, 0x45, 0x35, 0xf9], - [0x87, 0x57, 0x75, 0x19, 0x04, 0x8f, 0x53, 0xa9], - [0x10, 0xa5, 0x6c, 0xf5, 0xdf, 0xcd, 0x9a, 0xdb], - [0xeb, 0x75, 0x09, 0x5c, 0xcd, 0x98, 0x6c, 0xd0], - [0x51, 0xa9, 0xcb, 0x9e, 0xcb, 0xa3, 0x12, 0xe6], - [0x96, 0xaf, 0xad, 0xfc, 0x2c, 0xe6, 0x66, 0xc7], - [0x72, 0xfe, 0x52, 0x97, 0x5a, 0x43, 0x64, 0xee], - [0x5a, 0x16, 0x45, 0xb2, 0x76, 0xd5, 0x92, 0xa1], - [0xb2, 0x74, 0xcb, 0x8e, 0xbf, 0x87, 0x87, 0x0a], - [0x6f, 0x9b, 0xb4, 0x20, 0x3d, 0xe7, 0xb3, 0x81], - [0xea, 0xec, 0xb2, 0xa3, 0x0b, 0x22, 0xa8, 0x7f], - [0x99, 0x24, 0xa4, 0x3c, 0xc1, 0x31, 0x57, 0x24], - [0xbd, 0x83, 0x8d, 0x3a, 0xaf, 0xbf, 0x8d, 0xb7], - [0x0b, 0x1a, 0x2a, 0x32, 0x65, 0xd5, 0x1a, 0xea], - [0x13, 0x50, 0x79, 0xa3, 0x23, 0x1c, 0xe6, 0x60], - [0x93, 0x2b, 0x28, 0x46, 0xe4, 0xd7, 0x06, 0x66], - [0xe1, 0x91, 0x5f, 0x5c, 0xb1, 0xec, 0xa4, 0x6c], - [0xf3, 0x25, 0x96, 0x5c, 0xa1, 0x6d, 0x62, 0x9f], - [0x57, 0x5f, 0xf2, 0x8e, 0x60, 0x38, 0x1b, 0xe5], - [0x72, 0x45, 0x06, 0xeb, 0x4c, 0x32, 0x8a, 0x95], - ]; - - let k0 = 0x_07_06_05_04_03_02_01_00; - let k1 = 0x_0f_0e_0d_0c_0b_0a_09_08; - let mut buf = Vec::new(); - let mut t = 0; - let mut state_inc = SipHasher::new_with_keys(k0, k1); - - while t < 64 { - let vec = u64::from_le_bytes(vecs[t]); - let out = hash_with(SipHasher::new_with_keys(k0, k1), &Bytes(&buf)); - assert_eq!(vec, out); - - let full = hash_with(SipHasher::new_with_keys(k0, k1), &Bytes(&buf)); - let i = state_inc.finish(); - - assert_eq!(full, i); - assert_eq!(full, vec); - - buf.push(t as u8); - Hasher::write(&mut state_inc, &[t as u8]); - - t += 1; - } -} - -#[test] -#[cfg(target_pointer_width = "32")] -fn test_hash_usize() { - let val = 0xdeadbeef_deadbeef_u64; - assert_ne!(hash(&(val as u64)), hash(&(val as usize))); - assert_eq!(hash(&(val as u32)), hash(&(val as usize))); -} - -#[test] -#[cfg(target_pointer_width = "64")] -fn test_hash_usize() { - let val = 0xdeadbeef_deadbeef_u64; - assert_eq!(hash(&(val as u64)), hash(&(val as usize))); - assert_ne!(hash(&(val as u32)), hash(&(val as usize))); -} - -#[test] -fn test_hash_idempotent() { - let val64 = 0xdeadbeef_deadbeef_u64; - assert_eq!(hash(&val64), hash(&val64)); - let val32 = 0xdeadbeef_u32; - assert_eq!(hash(&val32), hash(&val32)); -} - -#[test] -fn test_hash_no_bytes_dropped_64() { - let val = 0xdeadbeef_deadbeef_u64; - - assert_ne!(hash(&val), hash(&zero_byte(val, 0))); - assert_ne!(hash(&val), hash(&zero_byte(val, 1))); - assert_ne!(hash(&val), hash(&zero_byte(val, 2))); - assert_ne!(hash(&val), hash(&zero_byte(val, 3))); - assert_ne!(hash(&val), hash(&zero_byte(val, 4))); - assert_ne!(hash(&val), hash(&zero_byte(val, 5))); - assert_ne!(hash(&val), hash(&zero_byte(val, 6))); - assert_ne!(hash(&val), hash(&zero_byte(val, 7))); - - fn zero_byte(val: u64, byte: usize) -> u64 { - assert!(byte < 8); - val & !(0xff << (byte * 8)) - } -} - -#[test] -fn test_hash_no_bytes_dropped_32() { - let val = 0xdeadbeef_u32; - - assert_ne!(hash(&val), hash(&zero_byte(val, 0))); - assert_ne!(hash(&val), hash(&zero_byte(val, 1))); - assert_ne!(hash(&val), hash(&zero_byte(val, 2))); - assert_ne!(hash(&val), hash(&zero_byte(val, 3))); - - fn zero_byte(val: u32, byte: usize) -> u32 { - assert!(byte < 4); - val & !(0xff << (byte * 8)) - } -} - -#[test] -fn test_hash_no_concat_alias() { - let s = ("aa", "bb"); - let t = ("aabb", ""); - let u = ("a", "abb"); - - assert_ne!(s, t); - assert_ne!(t, u); - assert_ne!(hash(&s), hash(&t)); - assert_ne!(hash(&s), hash(&u)); - - let u = [1, 0, 0, 0]; - let v = (&u[..1], &u[1..3], &u[3..]); - let w = (&u[..], &u[4..4], &u[4..4]); - - assert_ne!(v, w); - assert_ne!(hash(&v), hash(&w)); -} - -#[test] -fn test_write_short_works() { - let test_usize = 0xd0c0b0a0usize; - let mut h1 = SipHasher::new(); - h1.write_usize(test_usize); - h1.write(b"bytes"); - h1.write(b"string"); - h1.write_u8(0xFFu8); - h1.write_u8(0x01u8); - let mut h2 = SipHasher::new(); - h2.write(unsafe { - slice::from_raw_parts(&test_usize as *const _ as *const u8, mem::size_of::()) - }); - h2.write(b"bytes"); - h2.write(b"string"); - h2.write(&[0xFFu8, 0x01u8]); - assert_eq!(h1.finish(), h2.finish()); -} diff --git a/library/core/tests/intrinsics.rs b/library/core/tests/intrinsics.rs deleted file mode 100644 index 8b731cf5b25d1..0000000000000 --- a/library/core/tests/intrinsics.rs +++ /dev/null @@ -1,127 +0,0 @@ -use core::any::TypeId; -use core::intrinsics::assume; - -#[test] -fn test_typeid_sized_types() { - struct X; - struct Y(#[allow(dead_code)] u32); - - assert_eq!(TypeId::of::(), TypeId::of::()); - assert_eq!(TypeId::of::(), TypeId::of::()); - assert!(TypeId::of::() != TypeId::of::()); -} - -#[test] -fn test_typeid_unsized_types() { - trait Z {} - struct X(#[allow(dead_code)] str); - struct Y(#[allow(dead_code)] dyn Z + 'static); - - assert_eq!(TypeId::of::(), TypeId::of::()); - assert_eq!(TypeId::of::(), TypeId::of::()); - assert!(TypeId::of::() != TypeId::of::()); -} - -// Check that `const_assume` feature allow `assume` intrinsic -// to be used in const contexts. -#[test] -fn test_assume_can_be_in_const_contexts() { - const unsafe fn foo(x: usize, y: usize) -> usize { - // SAFETY: the entire function is not safe, - // but it is just an example not used elsewhere. - unsafe { assume(y != 0) }; - x / y - } - let rs = unsafe { foo(42, 97) }; - assert_eq!(rs, 0); -} - -#[test] -const fn test_write_bytes_in_const_contexts() { - use core::intrinsics::write_bytes; - - const TEST: [u32; 3] = { - let mut arr = [1u32, 2, 3]; - unsafe { - write_bytes(arr.as_mut_ptr(), 0, 2); - } - arr - }; - - assert!(TEST[0] == 0); - assert!(TEST[1] == 0); - assert!(TEST[2] == 3); - - const TEST2: [u32; 3] = { - let mut arr = [1u32, 2, 3]; - unsafe { - write_bytes(arr.as_mut_ptr(), 1, 2); - } - arr - }; - - assert!(TEST2[0] == 16843009); - assert!(TEST2[1] == 16843009); - assert!(TEST2[2] == 3); -} - -#[test] -fn test_hints_in_const_contexts() { - use core::intrinsics::{likely, unlikely}; - - // In const contexts, they just return their argument. - const { - assert!(true == likely(true)); - assert!(false == likely(false)); - assert!(true == unlikely(true)); - assert!(false == unlikely(false)); - assert!(42u32 == core::intrinsics::black_box(42u32)); - assert!(42u32 == core::hint::black_box(42u32)); - } -} - -#[test] -fn test_const_allocate_at_runtime() { - use core::intrinsics::const_allocate; - unsafe { - assert!(const_allocate(4, 4).is_null()); - } -} - -#[test] -fn test_const_deallocate_at_runtime() { - use core::intrinsics::const_deallocate; - const X: &u32 = &42u32; - let x = &0u32; - unsafe { - const_deallocate(X as *const _ as *mut u8, 4, 4); // nop - const_deallocate(x as *const _ as *mut u8, 4, 4); // nop - const_deallocate(core::ptr::null_mut(), 1, 1); // nop - } -} - -#[test] -fn test_three_way_compare_in_const_contexts() { - use core::cmp::Ordering::{self, *}; - use core::intrinsics::three_way_compare; - - const UNSIGNED_LESS: Ordering = three_way_compare(123_u16, 456); - const UNSIGNED_EQUAL: Ordering = three_way_compare(456_u16, 456); - const UNSIGNED_GREATER: Ordering = three_way_compare(789_u16, 456); - const CHAR_LESS: Ordering = three_way_compare('A', 'B'); - const CHAR_EQUAL: Ordering = three_way_compare('B', 'B'); - const CHAR_GREATER: Ordering = three_way_compare('C', 'B'); - const SIGNED_LESS: Ordering = three_way_compare(123_i64, 456); - const SIGNED_EQUAL: Ordering = three_way_compare(456_i64, 456); - const SIGNED_GREATER: Ordering = three_way_compare(789_i64, 456); - - assert_eq!(UNSIGNED_LESS, Less); - assert_eq!(UNSIGNED_EQUAL, Equal); - assert_eq!(UNSIGNED_GREATER, Greater); - assert_eq!(CHAR_LESS, Less); - assert_eq!(CHAR_EQUAL, Equal); - assert_eq!(CHAR_GREATER, Greater); - assert_eq!(SIGNED_LESS, Less); - assert_eq!(SIGNED_EQUAL, Equal); - assert_eq!(SIGNED_GREATER, Greater); -} diff --git a/library/core/tests/io/borrowed_buf.rs b/library/core/tests/io/borrowed_buf.rs deleted file mode 100644 index a5dd4e525777a..0000000000000 --- a/library/core/tests/io/borrowed_buf.rs +++ /dev/null @@ -1,167 +0,0 @@ -use core::io::BorrowedBuf; -use core::mem::MaybeUninit; - -/// Test that BorrowedBuf has the correct numbers when created with new -#[test] -fn new() { - let buf: &mut [_] = &mut [0; 16]; - let mut rbuf: BorrowedBuf<'_> = buf.into(); - - assert_eq!(rbuf.filled().len(), 0); - assert_eq!(rbuf.init_len(), 16); - assert_eq!(rbuf.capacity(), 16); - assert_eq!(rbuf.unfilled().capacity(), 16); -} - -/// Test that BorrowedBuf has the correct numbers when created with uninit -#[test] -fn uninit() { - let buf: &mut [_] = &mut [MaybeUninit::uninit(); 16]; - let mut rbuf: BorrowedBuf<'_> = buf.into(); - - assert_eq!(rbuf.filled().len(), 0); - assert_eq!(rbuf.init_len(), 0); - assert_eq!(rbuf.capacity(), 16); - assert_eq!(rbuf.unfilled().capacity(), 16); -} - -#[test] -fn initialize_unfilled() { - let buf: &mut [_] = &mut [MaybeUninit::uninit(); 16]; - let mut rbuf: BorrowedBuf<'_> = buf.into(); - - rbuf.unfilled().ensure_init(); - - assert_eq!(rbuf.init_len(), 16); -} - -#[test] -fn advance_filled() { - let buf: &mut [_] = &mut [0; 16]; - let mut rbuf: BorrowedBuf<'_> = buf.into(); - - rbuf.unfilled().advance(1); - - assert_eq!(rbuf.filled().len(), 1); - assert_eq!(rbuf.unfilled().capacity(), 15); -} - -#[test] -fn clear() { - let buf: &mut [_] = &mut [255; 16]; - let mut rbuf: BorrowedBuf<'_> = buf.into(); - - rbuf.unfilled().advance(16); - - assert_eq!(rbuf.filled().len(), 16); - assert_eq!(rbuf.unfilled().capacity(), 0); - - rbuf.clear(); - - assert_eq!(rbuf.filled().len(), 0); - assert_eq!(rbuf.unfilled().capacity(), 16); - - assert_eq!(rbuf.unfilled().init_ref(), [255; 16]); -} - -#[test] -fn set_init() { - let buf: &mut [_] = &mut [MaybeUninit::uninit(); 16]; - let mut rbuf: BorrowedBuf<'_> = buf.into(); - - unsafe { - rbuf.set_init(8); - } - - assert_eq!(rbuf.init_len(), 8); - - rbuf.unfilled().advance(4); - - unsafe { - rbuf.set_init(2); - } - - assert_eq!(rbuf.init_len(), 8); - - unsafe { - rbuf.set_init(8); - } - - assert_eq!(rbuf.init_len(), 8); -} - -#[test] -fn append() { - let buf: &mut [_] = &mut [MaybeUninit::new(255); 16]; - let mut rbuf: BorrowedBuf<'_> = buf.into(); - - rbuf.unfilled().append(&[0; 8]); - - assert_eq!(rbuf.init_len(), 8); - assert_eq!(rbuf.filled().len(), 8); - assert_eq!(rbuf.filled(), [0; 8]); - - rbuf.clear(); - - rbuf.unfilled().append(&[1; 16]); - - assert_eq!(rbuf.init_len(), 16); - assert_eq!(rbuf.filled().len(), 16); - assert_eq!(rbuf.filled(), [1; 16]); -} - -#[test] -fn reborrow_written() { - let buf: &mut [_] = &mut [MaybeUninit::new(0); 32]; - let mut buf: BorrowedBuf<'_> = buf.into(); - - let mut cursor = buf.unfilled(); - cursor.append(&[1; 16]); - - let mut cursor2 = cursor.reborrow(); - cursor2.append(&[2; 16]); - - assert_eq!(cursor2.written(), 32); - assert_eq!(cursor.written(), 32); - - assert_eq!(buf.unfilled().written(), 0); - assert_eq!(buf.init_len(), 32); - assert_eq!(buf.filled().len(), 32); - let filled = buf.filled(); - assert_eq!(&filled[..16], [1; 16]); - assert_eq!(&filled[16..], [2; 16]); -} - -#[test] -fn cursor_set_init() { - let buf: &mut [_] = &mut [MaybeUninit::uninit(); 16]; - let mut rbuf: BorrowedBuf<'_> = buf.into(); - - unsafe { - rbuf.unfilled().set_init(8); - } - - assert_eq!(rbuf.init_len(), 8); - assert_eq!(rbuf.unfilled().init_ref().len(), 8); - assert_eq!(rbuf.unfilled().init_mut().len(), 8); - assert_eq!(rbuf.unfilled().uninit_mut().len(), 8); - assert_eq!(unsafe { rbuf.unfilled().as_mut() }.len(), 16); - - rbuf.unfilled().advance(4); - - unsafe { - rbuf.unfilled().set_init(2); - } - - assert_eq!(rbuf.init_len(), 8); - - unsafe { - rbuf.unfilled().set_init(8); - } - - assert_eq!(rbuf.init_len(), 12); - assert_eq!(rbuf.unfilled().init_ref().len(), 8); - assert_eq!(rbuf.unfilled().init_mut().len(), 8); - assert_eq!(rbuf.unfilled().uninit_mut().len(), 4); - assert_eq!(unsafe { rbuf.unfilled().as_mut() }.len(), 12); -} diff --git a/library/core/tests/io/mod.rs b/library/core/tests/io/mod.rs deleted file mode 100644 index a24893a525a9d..0000000000000 --- a/library/core/tests/io/mod.rs +++ /dev/null @@ -1 +0,0 @@ -mod borrowed_buf; diff --git a/library/core/tests/iter/adapters/array_chunks.rs b/library/core/tests/iter/adapters/array_chunks.rs deleted file mode 100644 index fb19a519f63b5..0000000000000 --- a/library/core/tests/iter/adapters/array_chunks.rs +++ /dev/null @@ -1,179 +0,0 @@ -use core::iter::{self}; - -use super::*; - -#[test] -fn test_iterator_array_chunks_infer() { - let xs = [1, 1, 2, -2, 6, 0, 3, 1]; - for [a, b, c] in xs.iter().copied().array_chunks() { - assert_eq!(a + b + c, 4); - } -} - -#[test] -fn test_iterator_array_chunks_clone_and_drop() { - let count = Cell::new(0); - let mut it = (0..5).map(|_| CountDrop::new(&count)).array_chunks::<3>(); - assert_eq!(it.by_ref().count(), 1); - assert_eq!(count.get(), 3); - let mut it2 = it.clone(); - assert_eq!(count.get(), 3); - assert_eq!(it.into_remainder().unwrap().len(), 2); - assert_eq!(count.get(), 5); - assert!(it2.next().is_none()); - assert_eq!(it2.into_remainder().unwrap().len(), 2); - assert_eq!(count.get(), 7); -} - -#[test] -fn test_iterator_array_chunks_remainder() { - let mut it = (0..11).array_chunks::<4>(); - assert_eq!(it.next(), Some([0, 1, 2, 3])); - assert_eq!(it.next(), Some([4, 5, 6, 7])); - assert_eq!(it.next(), None); - assert_eq!(it.into_remainder().unwrap().as_slice(), &[8, 9, 10]); -} - -#[test] -fn test_iterator_array_chunks_size_hint() { - let it = (0..6).array_chunks::<1>(); - assert_eq!(it.size_hint(), (6, Some(6))); - - let it = (0..6).array_chunks::<3>(); - assert_eq!(it.size_hint(), (2, Some(2))); - - let it = (0..6).array_chunks::<5>(); - assert_eq!(it.size_hint(), (1, Some(1))); - - let it = (0..6).array_chunks::<7>(); - assert_eq!(it.size_hint(), (0, Some(0))); - - let it = (1..).array_chunks::<2>(); - assert_eq!(it.size_hint(), (usize::MAX / 2, None)); - - let it = (1..).filter(|x| x % 2 != 0).array_chunks::<2>(); - assert_eq!(it.size_hint(), (0, None)); -} - -#[test] -fn test_iterator_array_chunks_count() { - let it = (0..6).array_chunks::<1>(); - assert_eq!(it.count(), 6); - - let it = (0..6).array_chunks::<3>(); - assert_eq!(it.count(), 2); - - let it = (0..6).array_chunks::<5>(); - assert_eq!(it.count(), 1); - - let it = (0..6).array_chunks::<7>(); - assert_eq!(it.count(), 0); - - let it = (0..6).filter(|x| x % 2 == 0).array_chunks::<2>(); - assert_eq!(it.count(), 1); - - let it = iter::empty::().array_chunks::<2>(); - assert_eq!(it.count(), 0); - - let it = [(); usize::MAX].iter().array_chunks::<2>(); - assert_eq!(it.count(), usize::MAX / 2); -} - -#[test] -fn test_iterator_array_chunks_next_and_next_back() { - let mut it = (0..11).array_chunks::<3>(); - assert_eq!(it.next(), Some([0, 1, 2])); - assert_eq!(it.next_back(), Some([6, 7, 8])); - assert_eq!(it.next(), Some([3, 4, 5])); - assert_eq!(it.next_back(), None); - assert_eq!(it.next(), None); - assert_eq!(it.next_back(), None); - assert_eq!(it.next(), None); - assert_eq!(it.into_remainder().unwrap().as_slice(), &[9, 10]); -} - -#[test] -fn test_iterator_array_chunks_rev_remainder() { - let mut it = (0..11).array_chunks::<4>(); - { - let mut it = it.by_ref().rev(); - assert_eq!(it.next(), Some([4, 5, 6, 7])); - assert_eq!(it.next(), Some([0, 1, 2, 3])); - assert_eq!(it.next(), None); - assert_eq!(it.next(), None); - } - assert_eq!(it.into_remainder().unwrap().as_slice(), &[8, 9, 10]); -} - -#[test] -fn test_iterator_array_chunks_try_fold() { - let count = Cell::new(0); - let mut it = (0..10).map(|_| CountDrop::new(&count)).array_chunks::<3>(); - let result: Result<_, ()> = it.by_ref().try_fold(0, |acc, _item| Ok(acc + 1)); - assert_eq!(result, Ok(3)); - assert_eq!(count.get(), 9); - drop(it); - assert_eq!(count.get(), 10); - - let count = Cell::new(0); - let mut it = (0..10).map(|_| CountDrop::new(&count)).array_chunks::<3>(); - let result = it.by_ref().try_fold(0, |acc, _item| if acc < 2 { Ok(acc + 1) } else { Err(acc) }); - assert_eq!(result, Err(2)); - assert_eq!(count.get(), 9); - drop(it); - assert_eq!(count.get(), 9); -} - -#[test] -fn test_iterator_array_chunks_fold() { - let result = (1..11).array_chunks::<3>().fold(0, |acc, [a, b, c]| { - assert_eq!(acc + 1, a); - assert_eq!(acc + 2, b); - assert_eq!(acc + 3, c); - acc + 3 - }); - assert_eq!(result, 9); - - let count = Cell::new(0); - let result = - (0..10).map(|_| CountDrop::new(&count)).array_chunks::<3>().fold(0, |acc, _item| acc + 1); - assert_eq!(result, 3); - // fold impls may or may not process the remainder - assert!(count.get() <= 10 && count.get() >= 9); -} - -#[test] -fn test_iterator_array_chunks_try_rfold() { - let count = Cell::new(0); - let mut it = (0..10).map(|_| CountDrop::new(&count)).array_chunks::<3>(); - let result: Result<_, ()> = it.try_rfold(0, |acc, _item| Ok(acc + 1)); - assert_eq!(result, Ok(3)); - assert_eq!(count.get(), 9); - drop(it); - assert_eq!(count.get(), 10); - - let count = Cell::new(0); - let mut it = (0..10).map(|_| CountDrop::new(&count)).array_chunks::<3>(); - let result = it.try_rfold(0, |acc, _item| if acc < 2 { Ok(acc + 1) } else { Err(acc) }); - assert_eq!(result, Err(2)); - assert_eq!(count.get(), 9); - drop(it); - assert_eq!(count.get(), 10); -} - -#[test] -fn test_iterator_array_chunks_rfold() { - let result = (1..11).array_chunks::<3>().rfold(0, |acc, [a, b, c]| { - assert_eq!(10 - (acc + 1), c); - assert_eq!(10 - (acc + 2), b); - assert_eq!(10 - (acc + 3), a); - acc + 3 - }); - assert_eq!(result, 9); - - let count = Cell::new(0); - let result = - (0..10).map(|_| CountDrop::new(&count)).array_chunks::<3>().rfold(0, |acc, _item| acc + 1); - assert_eq!(result, 3); - assert_eq!(count.get(), 10); -} diff --git a/library/core/tests/iter/adapters/by_ref_sized.rs b/library/core/tests/iter/adapters/by_ref_sized.rs deleted file mode 100644 index a9c066f0e8cb1..0000000000000 --- a/library/core/tests/iter/adapters/by_ref_sized.rs +++ /dev/null @@ -1,20 +0,0 @@ -use core::iter::*; - -#[test] -fn test_iterator_by_ref_sized() { - let a = ['a', 'b', 'c', 'd']; - - let mut s = String::from("Z"); - let mut it = a.iter().copied(); - ByRefSized(&mut it).take(2).for_each(|x| s.push(x)); - assert_eq!(s, "Zab"); - ByRefSized(&mut it).fold((), |(), x| s.push(x)); - assert_eq!(s, "Zabcd"); - - let mut s = String::from("Z"); - let mut it = a.iter().copied(); - ByRefSized(&mut it).rev().take(2).for_each(|x| s.push(x)); - assert_eq!(s, "Zdc"); - ByRefSized(&mut it).rfold((), |(), x| s.push(x)); - assert_eq!(s, "Zdcba"); -} diff --git a/library/core/tests/iter/adapters/chain.rs b/library/core/tests/iter/adapters/chain.rs deleted file mode 100644 index b2429588de12b..0000000000000 --- a/library/core/tests/iter/adapters/chain.rs +++ /dev/null @@ -1,284 +0,0 @@ -use super::*; -use core::iter::*; -use core::num::NonZero; - -#[test] -fn test_iterator_chain() { - let xs = [0, 1, 2, 3, 4, 5]; - let ys = [30, 40, 50, 60]; - let expected = [0, 1, 2, 3, 4, 5, 30, 40, 50, 60]; - let it = xs.iter().chain(&ys); - let mut i = 0; - for &x in it { - assert_eq!(x, expected[i]); - i += 1; - } - assert_eq!(i, expected.len()); - - let ys = (30..).step_by(10).take(4); - let it = xs.iter().cloned().chain(ys); - let mut i = 0; - for x in it { - assert_eq!(x, expected[i]); - i += 1; - } - assert_eq!(i, expected.len()); -} - -#[test] -fn test_iterator_chain_advance_by() { - fn test_chain(xs: &[i32], ys: &[i32]) { - let len = xs.len() + ys.len(); - - for i in 0..xs.len() { - let mut iter = Unfuse::new(xs).chain(Unfuse::new(ys)); - assert_eq!(iter.advance_by(i), Ok(())); - assert_eq!(iter.next(), Some(&xs[i])); - assert_eq!(iter.advance_by(100), Err(NonZero::new(100 - (len - i - 1)).unwrap())); - assert_eq!(iter.advance_by(0), Ok(())); - } - - for i in 0..ys.len() { - let mut iter = Unfuse::new(xs).chain(Unfuse::new(ys)); - assert_eq!(iter.advance_by(xs.len() + i), Ok(())); - assert_eq!(iter.next(), Some(&ys[i])); - assert_eq!(iter.advance_by(100), Err(NonZero::new(100 - (ys.len() - i - 1)).unwrap())); - assert_eq!(iter.advance_by(0), Ok(())); - } - - let mut iter = xs.iter().chain(ys); - assert_eq!(iter.advance_by(len), Ok(())); - assert_eq!(iter.next(), None); - assert_eq!(iter.advance_by(0), Ok(())); - - let mut iter = xs.iter().chain(ys); - assert_eq!(iter.advance_by(len + 1), Err(NonZero::new(1).unwrap())); - assert_eq!(iter.advance_by(0), Ok(())); - } - - test_chain(&[], &[]); - test_chain(&[], &[0, 1, 2, 3, 4, 5]); - test_chain(&[0, 1, 2, 3, 4, 5], &[]); - test_chain(&[0, 1, 2, 3, 4, 5], &[30, 40, 50, 60]); -} - -#[test] -fn test_iterator_chain_advance_back_by() { - fn test_chain(xs: &[i32], ys: &[i32]) { - let len = xs.len() + ys.len(); - - for i in 0..ys.len() { - let mut iter = Unfuse::new(xs).chain(Unfuse::new(ys)); - assert_eq!(iter.advance_back_by(i), Ok(())); - assert_eq!(iter.next_back(), Some(&ys[ys.len() - i - 1])); - assert_eq!(iter.advance_back_by(100), Err(NonZero::new(100 - (len - i - 1)).unwrap())); - assert_eq!(iter.advance_back_by(0), Ok(())); - } - - for i in 0..xs.len() { - let mut iter = Unfuse::new(xs).chain(Unfuse::new(ys)); - assert_eq!(iter.advance_back_by(ys.len() + i), Ok(())); - assert_eq!(iter.next_back(), Some(&xs[xs.len() - i - 1])); - assert_eq!( - iter.advance_back_by(100), - Err(NonZero::new(100 - (xs.len() - i - 1)).unwrap()) - ); - assert_eq!(iter.advance_back_by(0), Ok(())); - } - - let mut iter = xs.iter().chain(ys); - assert_eq!(iter.advance_back_by(len), Ok(())); - assert_eq!(iter.next_back(), None); - assert_eq!(iter.advance_back_by(0), Ok(())); - - let mut iter = xs.iter().chain(ys); - assert_eq!(iter.advance_back_by(len + 1), Err(NonZero::new(1).unwrap())); - assert_eq!(iter.advance_back_by(0), Ok(())); - } - - test_chain(&[], &[]); - test_chain(&[], &[0, 1, 2, 3, 4, 5]); - test_chain(&[0, 1, 2, 3, 4, 5], &[]); - test_chain(&[0, 1, 2, 3, 4, 5], &[30, 40, 50, 60]); -} - -#[test] -fn test_iterator_chain_nth() { - let xs = [0, 1, 2, 3, 4, 5]; - let ys = [30, 40, 50, 60]; - let zs = []; - let expected = [0, 1, 2, 3, 4, 5, 30, 40, 50, 60]; - for (i, x) in expected.iter().enumerate() { - assert_eq!(Some(x), xs.iter().chain(&ys).nth(i)); - } - assert_eq!(zs.iter().chain(&xs).nth(0), Some(&0)); - - let mut it = xs.iter().chain(&zs); - assert_eq!(it.nth(5), Some(&5)); - assert_eq!(it.next(), None); -} - -#[test] -fn test_iterator_chain_nth_back() { - let xs = [0, 1, 2, 3, 4, 5]; - let ys = [30, 40, 50, 60]; - let zs = []; - let expected = [0, 1, 2, 3, 4, 5, 30, 40, 50, 60]; - for (i, x) in expected.iter().rev().enumerate() { - assert_eq!(Some(x), xs.iter().chain(&ys).nth_back(i)); - } - assert_eq!(zs.iter().chain(&xs).nth_back(0), Some(&5)); - - let mut it = xs.iter().chain(&zs); - assert_eq!(it.nth_back(5), Some(&0)); - assert_eq!(it.next(), None); -} - -#[test] -fn test_iterator_chain_last() { - let xs = [0, 1, 2, 3, 4, 5]; - let ys = [30, 40, 50, 60]; - let zs = []; - assert_eq!(xs.iter().chain(&ys).last(), Some(&60)); - assert_eq!(zs.iter().chain(&ys).last(), Some(&60)); - assert_eq!(ys.iter().chain(&zs).last(), Some(&60)); - assert_eq!(zs.iter().chain(&zs).last(), None); -} - -#[test] -fn test_iterator_chain_count() { - let xs = [0, 1, 2, 3, 4, 5]; - let ys = [30, 40, 50, 60]; - let zs = []; - assert_eq!(xs.iter().chain(&ys).count(), 10); - assert_eq!(zs.iter().chain(&ys).count(), 4); -} - -#[test] -fn test_iterator_chain_find() { - let xs = [0, 1, 2, 3, 4, 5]; - let ys = [30, 40, 50, 60]; - let mut iter = xs.iter().chain(&ys); - assert_eq!(iter.find(|&&i| i == 4), Some(&4)); - assert_eq!(iter.next(), Some(&5)); - assert_eq!(iter.find(|&&i| i == 40), Some(&40)); - assert_eq!(iter.next(), Some(&50)); - assert_eq!(iter.find(|&&i| i == 100), None); - assert_eq!(iter.next(), None); -} - -#[test] -fn test_iterator_chain_size_hint() { - // this chains an iterator of length 0 with an iterator of length 1, - // so after calling `.next()` once, the iterator is empty and the - // state is `ChainState::Back`. `.size_hint()` should now disregard - // the size hint of the left iterator - let mut iter = Toggle { is_empty: true }.chain(once(())); - assert_eq!(iter.next(), Some(())); - assert_eq!(iter.size_hint(), (0, Some(0))); - - let mut iter = once(()).chain(Toggle { is_empty: true }); - assert_eq!(iter.next_back(), Some(())); - assert_eq!(iter.size_hint(), (0, Some(0))); -} - -#[test] -fn test_iterator_chain_unfused() { - // Chain shouldn't be fused in its second iterator, depending on direction - let mut iter = NonFused::new(empty()).chain(Toggle { is_empty: true }); - assert!(iter.next().is_none()); - assert!(iter.next().is_some()); - assert!(iter.next().is_none()); - - let mut iter = Toggle { is_empty: true }.chain(NonFused::new(empty())); - assert!(iter.next_back().is_none()); - assert!(iter.next_back().is_some()); - assert!(iter.next_back().is_none()); -} - -#[test] -fn test_chain_fold() { - let xs = [1, 2, 3]; - let ys = [1, 2, 0]; - - let mut iter = xs.iter().chain(&ys); - iter.next(); - let mut result = Vec::new(); - iter.fold((), |(), &elt| result.push(elt)); - assert_eq!(&[2, 3, 1, 2, 0], &result[..]); -} - -#[test] -fn test_chain_try_folds() { - let c = || (0..10).chain(10..20); - - let f = &|acc, x| i32::checked_add(2 * acc, x); - assert_eq!(c().try_fold(7, f), (0..20).try_fold(7, f)); - assert_eq!(c().try_rfold(7, f), (0..20).rev().try_fold(7, f)); - - let mut iter = c(); - assert_eq!(iter.position(|x| x == 5), Some(5)); - assert_eq!(iter.next(), Some(6), "stopped in front, state Both"); - assert_eq!(iter.position(|x| x == 13), Some(6)); - assert_eq!(iter.next(), Some(14), "stopped in back, state Back"); - assert_eq!(iter.try_fold(0, |acc, x| Some(acc + x)), Some((15..20).sum())); - - let mut iter = c().rev(); // use rev to access try_rfold - assert_eq!(iter.position(|x| x == 15), Some(4)); - assert_eq!(iter.next(), Some(14), "stopped in back, state Both"); - assert_eq!(iter.position(|x| x == 5), Some(8)); - assert_eq!(iter.next(), Some(4), "stopped in front, state Front"); - assert_eq!(iter.try_fold(0, |acc, x| Some(acc + x)), Some((0..4).sum())); - - let mut iter = c(); - iter.by_ref().rev().nth(14); // skip the last 15, ending in state Front - assert_eq!(iter.try_fold(7, f), (0..5).try_fold(7, f)); - - let mut iter = c(); - iter.nth(14); // skip the first 15, ending in state Back - assert_eq!(iter.try_rfold(7, f), (15..20).try_rfold(7, f)); -} - -#[test] -fn test_double_ended_chain() { - let xs = [1, 2, 3, 4, 5]; - let ys = [7, 9, 11]; - let mut it = xs.iter().chain(&ys).rev(); - assert_eq!(it.next().unwrap(), &11); - assert_eq!(it.next().unwrap(), &9); - assert_eq!(it.next_back().unwrap(), &1); - assert_eq!(it.next_back().unwrap(), &2); - assert_eq!(it.next_back().unwrap(), &3); - assert_eq!(it.next_back().unwrap(), &4); - assert_eq!(it.next_back().unwrap(), &5); - assert_eq!(it.next_back().unwrap(), &7); - assert_eq!(it.next_back(), None); - - // test that .chain() is well behaved with an unfused iterator - struct CrazyIterator(bool); - impl CrazyIterator { - fn new() -> CrazyIterator { - CrazyIterator(false) - } - } - impl Iterator for CrazyIterator { - type Item = i32; - fn next(&mut self) -> Option { - if self.0 { - Some(99) - } else { - self.0 = true; - None - } - } - } - - impl DoubleEndedIterator for CrazyIterator { - fn next_back(&mut self) -> Option { - self.next() - } - } - - assert_eq!(CrazyIterator::new().chain(0..10).rev().last(), Some(0)); - assert!((0..10).chain(CrazyIterator::new()).rev().any(|i| i == 0)); -} diff --git a/library/core/tests/iter/adapters/cloned.rs b/library/core/tests/iter/adapters/cloned.rs deleted file mode 100644 index 78babb7feab18..0000000000000 --- a/library/core/tests/iter/adapters/cloned.rs +++ /dev/null @@ -1,52 +0,0 @@ -use core::iter::*; - -#[test] -fn test_cloned() { - let xs = [2, 4, 6, 8]; - - let mut it = xs.iter().cloned(); - assert_eq!(it.len(), 4); - assert_eq!(it.next(), Some(2)); - assert_eq!(it.len(), 3); - assert_eq!(it.next(), Some(4)); - assert_eq!(it.len(), 2); - assert_eq!(it.next_back(), Some(8)); - assert_eq!(it.len(), 1); - assert_eq!(it.next_back(), Some(6)); - assert_eq!(it.len(), 0); - assert_eq!(it.next_back(), None); -} - -#[test] -fn test_cloned_side_effects() { - let mut count = 0; - { - let iter = [1, 2, 3] - .iter() - .map(|x| { - count += 1; - x - }) - .cloned() - .zip(&[1]); - for _ in iter {} - } - assert_eq!(count, 2); -} - -#[test] -fn test_cloned_try_folds() { - let a = [1, 2, 3, 4, 5, 6, 7, 8, 9]; - let f = &|acc, x| i32::checked_add(2 * acc, x); - let f_ref = &|acc, &x| i32::checked_add(2 * acc, x); - assert_eq!(a.iter().cloned().try_fold(7, f), a.iter().try_fold(7, f_ref)); - assert_eq!(a.iter().cloned().try_rfold(7, f), a.iter().try_rfold(7, f_ref)); - - let a = [10, 20, 30, 40, 100, 60, 70, 80, 90]; - let mut iter = a.iter().cloned(); - assert_eq!(iter.try_fold(0_i8, |acc, x| acc.checked_add(x)), None); - assert_eq!(iter.next(), Some(60)); - let mut iter = a.iter().cloned(); - assert_eq!(iter.try_rfold(0_i8, |acc, x| acc.checked_add(x)), None); - assert_eq!(iter.next_back(), Some(70)); -} diff --git a/library/core/tests/iter/adapters/copied.rs b/library/core/tests/iter/adapters/copied.rs deleted file mode 100644 index b12f2035dc133..0000000000000 --- a/library/core/tests/iter/adapters/copied.rs +++ /dev/null @@ -1,18 +0,0 @@ -use core::iter::*; - -#[test] -fn test_copied() { - let xs = [2, 4, 6, 8]; - - let mut it = xs.iter().copied(); - assert_eq!(it.len(), 4); - assert_eq!(it.next(), Some(2)); - assert_eq!(it.len(), 3); - assert_eq!(it.next(), Some(4)); - assert_eq!(it.len(), 2); - assert_eq!(it.next_back(), Some(8)); - assert_eq!(it.len(), 1); - assert_eq!(it.next_back(), Some(6)); - assert_eq!(it.len(), 0); - assert_eq!(it.next_back(), None); -} diff --git a/library/core/tests/iter/adapters/cycle.rs b/library/core/tests/iter/adapters/cycle.rs deleted file mode 100644 index 8831c09b48b3f..0000000000000 --- a/library/core/tests/iter/adapters/cycle.rs +++ /dev/null @@ -1,31 +0,0 @@ -use core::iter::*; - -#[test] -fn test_cycle() { - let cycle_len = 3; - let it = (0..).step_by(1).take(cycle_len).cycle(); - assert_eq!(it.size_hint(), (usize::MAX, None)); - for (i, x) in it.take(100).enumerate() { - assert_eq!(i % cycle_len, x); - } - - let mut it = (0..).step_by(1).take(0).cycle(); - assert_eq!(it.size_hint(), (0, Some(0))); - assert_eq!(it.next(), None); - - assert_eq!(empty::().cycle().fold(0, |acc, x| acc + x), 0); - - assert_eq!(once(1).cycle().skip(1).take(4).fold(0, |acc, x| acc + x), 4); - - assert_eq!((0..10).cycle().take(5).sum::(), 10); - assert_eq!((0..10).cycle().take(15).sum::(), 55); - assert_eq!((0..10).cycle().take(25).sum::(), 100); - - let mut iter = (0..10).cycle(); - iter.nth(14); - assert_eq!(iter.take(8).sum::(), 38); - - let mut iter = (0..10).cycle(); - iter.nth(9); - assert_eq!(iter.take(3).sum::(), 3); -} diff --git a/library/core/tests/iter/adapters/enumerate.rs b/library/core/tests/iter/adapters/enumerate.rs deleted file mode 100644 index b57d51c077e9b..0000000000000 --- a/library/core/tests/iter/adapters/enumerate.rs +++ /dev/null @@ -1,122 +0,0 @@ -use core::iter::*; -use core::num::NonZero; - -#[test] -fn test_iterator_enumerate() { - let xs = [0, 1, 2, 3, 4, 5]; - let it = xs.iter().enumerate(); - for (i, &x) in it { - assert_eq!(i, x); - } -} - -#[test] -fn test_iterator_enumerate_nth() { - let xs = [0, 1, 2, 3, 4, 5]; - for (i, &x) in xs.iter().enumerate() { - assert_eq!(i, x); - } - - let mut it = xs.iter().enumerate(); - while let Some((i, &x)) = it.nth(0) { - assert_eq!(i, x); - } - - let mut it = xs.iter().enumerate(); - while let Some((i, &x)) = it.nth(1) { - assert_eq!(i, x); - } - - let (i, &x) = xs.iter().enumerate().nth(3).unwrap(); - assert_eq!(i, x); - assert_eq!(i, 3); -} - -#[test] -fn test_iterator_enumerate_nth_back() { - let xs = [0, 1, 2, 3, 4, 5]; - let mut it = xs.iter().enumerate(); - while let Some((i, &x)) = it.nth_back(0) { - assert_eq!(i, x); - } - - let mut it = xs.iter().enumerate(); - while let Some((i, &x)) = it.nth_back(1) { - assert_eq!(i, x); - } - - let (i, &x) = xs.iter().enumerate().nth_back(3).unwrap(); - assert_eq!(i, x); - assert_eq!(i, 2); -} - -#[test] -fn test_iterator_enumerate_count() { - let xs = [0, 1, 2, 3, 4, 5]; - assert_eq!(xs.iter().enumerate().count(), 6); -} - -#[test] -fn test_iterator_enumerate_advance_by() { - let xs = [0, 1, 2, 3, 4, 5]; - let mut it = xs.iter().enumerate(); - assert_eq!(it.advance_by(0), Ok(())); - assert_eq!(it.next(), Some((0, &0))); - assert_eq!(it.advance_by(1), Ok(())); - assert_eq!(it.next(), Some((2, &2))); - assert_eq!(it.advance_by(2), Ok(())); - assert_eq!(it.next(), Some((5, &5))); - assert_eq!(it.advance_by(1), Err(NonZero::new(1).unwrap())); - assert_eq!(it.next(), None); -} - -#[test] -fn test_iterator_enumerate_fold() { - let xs = [0, 1, 2, 3, 4, 5]; - let mut it = xs.iter().enumerate(); - // steal a couple to get an interesting offset - assert_eq!(it.next(), Some((0, &0))); - assert_eq!(it.next(), Some((1, &1))); - let i = it.fold(2, |i, (j, &x)| { - assert_eq!(i, j); - assert_eq!(x, xs[j]); - i + 1 - }); - assert_eq!(i, xs.len()); - - let mut it = xs.iter().enumerate(); - assert_eq!(it.next(), Some((0, &0))); - let i = it.rfold(xs.len() - 1, |i, (j, &x)| { - assert_eq!(i, j); - assert_eq!(x, xs[j]); - i - 1 - }); - assert_eq!(i, 0); -} - -#[test] -fn test_enumerate_try_folds() { - let f = &|acc, (i, x)| usize::checked_add(2 * acc, x / (i + 1) + i); - assert_eq!((9..18).enumerate().try_fold(7, f), (0..9).map(|i| (i, i + 9)).try_fold(7, f)); - assert_eq!((9..18).enumerate().try_rfold(7, f), (0..9).map(|i| (i, i + 9)).try_rfold(7, f)); - - let mut iter = (100..200).enumerate(); - let f = &|acc, (i, x)| u8::checked_add(acc, u8::checked_div(x, i as u8 + 1)?); - assert_eq!(iter.try_fold(0, f), None); - assert_eq!(iter.next(), Some((7, 107))); - assert_eq!(iter.try_rfold(0, f), None); - assert_eq!(iter.next_back(), Some((11, 111))); -} - -#[test] -fn test_double_ended_enumerate() { - let xs = [1, 2, 3, 4, 5, 6]; - let mut it = xs.iter().cloned().enumerate(); - assert_eq!(it.next(), Some((0, 1))); - assert_eq!(it.next(), Some((1, 2))); - assert_eq!(it.next_back(), Some((5, 6))); - assert_eq!(it.next_back(), Some((4, 5))); - assert_eq!(it.next_back(), Some((3, 4))); - assert_eq!(it.next_back(), Some((2, 3))); - assert_eq!(it.next(), None); -} diff --git a/library/core/tests/iter/adapters/filter.rs b/library/core/tests/iter/adapters/filter.rs deleted file mode 100644 index a2050d89d8564..0000000000000 --- a/library/core/tests/iter/adapters/filter.rs +++ /dev/null @@ -1,52 +0,0 @@ -use core::iter::*; - -#[test] -fn test_iterator_filter_count() { - let xs = [0, 1, 2, 3, 4, 5, 6, 7, 8]; - assert_eq!(xs.iter().filter(|&&x| x % 2 == 0).count(), 5); -} - -#[test] -fn test_iterator_filter_fold() { - let xs = [0, 1, 2, 3, 4, 5, 6, 7, 8]; - let ys = [0, 2, 4, 6, 8]; - let it = xs.iter().filter(|&&x| x % 2 == 0); - let i = it.fold(0, |i, &x| { - assert_eq!(x, ys[i]); - i + 1 - }); - assert_eq!(i, ys.len()); - - let it = xs.iter().filter(|&&x| x % 2 == 0); - let i = it.rfold(ys.len(), |i, &x| { - assert_eq!(x, ys[i - 1]); - i - 1 - }); - assert_eq!(i, 0); -} - -#[test] -fn test_filter_try_folds() { - fn p(&x: &i32) -> bool { - 0 <= x && x < 10 - } - let f = &|acc, x| i32::checked_add(2 * acc, x); - assert_eq!((-10..20).filter(p).try_fold(7, f), (0..10).try_fold(7, f)); - assert_eq!((-10..20).filter(p).try_rfold(7, f), (0..10).try_rfold(7, f)); - - let mut iter = (0..40).filter(|&x| x % 2 == 1); - assert_eq!(iter.try_fold(0, i8::checked_add), None); - assert_eq!(iter.next(), Some(25)); - assert_eq!(iter.try_rfold(0, i8::checked_add), None); - assert_eq!(iter.next_back(), Some(31)); -} - -#[test] -fn test_double_ended_filter() { - let xs = [1, 2, 3, 4, 5, 6]; - let mut it = xs.iter().filter(|&x| *x & 1 == 0); - assert_eq!(it.next_back().unwrap(), &6); - assert_eq!(it.next_back().unwrap(), &4); - assert_eq!(it.next().unwrap(), &2); - assert_eq!(it.next_back(), None); -} diff --git a/library/core/tests/iter/adapters/filter_map.rs b/library/core/tests/iter/adapters/filter_map.rs deleted file mode 100644 index 46738eda63f3d..0000000000000 --- a/library/core/tests/iter/adapters/filter_map.rs +++ /dev/null @@ -1,50 +0,0 @@ -use core::iter::*; - -#[test] -fn test_filter_map() { - let it = (0..).step_by(1).take(10).filter_map(|x| if x % 2 == 0 { Some(x * x) } else { None }); - assert_eq!(it.collect::>(), [0 * 0, 2 * 2, 4 * 4, 6 * 6, 8 * 8]); -} - -#[test] -fn test_filter_map_fold() { - let xs = [0, 1, 2, 3, 4, 5, 6, 7, 8]; - let ys = [0 * 0, 2 * 2, 4 * 4, 6 * 6, 8 * 8]; - let it = xs.iter().filter_map(|&x| if x % 2 == 0 { Some(x * x) } else { None }); - let i = it.fold(0, |i, x| { - assert_eq!(x, ys[i]); - i + 1 - }); - assert_eq!(i, ys.len()); - - let it = xs.iter().filter_map(|&x| if x % 2 == 0 { Some(x * x) } else { None }); - let i = it.rfold(ys.len(), |i, x| { - assert_eq!(x, ys[i - 1]); - i - 1 - }); - assert_eq!(i, 0); -} - -#[test] -fn test_filter_map_try_folds() { - let mp = &|x| if 0 <= x && x < 10 { Some(x * 2) } else { None }; - let f = &|acc, x| i32::checked_add(2 * acc, x); - assert_eq!((-9..20).filter_map(mp).try_fold(7, f), (0..10).map(|x| 2 * x).try_fold(7, f)); - assert_eq!((-9..20).filter_map(mp).try_rfold(7, f), (0..10).map(|x| 2 * x).try_rfold(7, f)); - - let mut iter = (0..40).filter_map(|x| if x % 2 == 1 { None } else { Some(x * 2 + 10) }); - assert_eq!(iter.try_fold(0, i8::checked_add), None); - assert_eq!(iter.next(), Some(38)); - assert_eq!(iter.try_rfold(0, i8::checked_add), None); - assert_eq!(iter.next_back(), Some(78)); -} - -#[test] -fn test_double_ended_filter_map() { - let xs = [1, 2, 3, 4, 5, 6]; - let mut it = xs.iter().filter_map(|&x| if x & 1 == 0 { Some(x * 2) } else { None }); - assert_eq!(it.next_back().unwrap(), 12); - assert_eq!(it.next_back().unwrap(), 8); - assert_eq!(it.next().unwrap(), 4); - assert_eq!(it.next_back(), None); -} diff --git a/library/core/tests/iter/adapters/flat_map.rs b/library/core/tests/iter/adapters/flat_map.rs deleted file mode 100644 index ee945e69801b8..0000000000000 --- a/library/core/tests/iter/adapters/flat_map.rs +++ /dev/null @@ -1,74 +0,0 @@ -use core::iter::*; - -#[test] -fn test_iterator_flat_map() { - let xs = [0, 3, 6]; - let ys = [0, 1, 2, 3, 4, 5, 6, 7, 8]; - let it = xs.iter().flat_map(|&x| (x..).step_by(1).take(3)); - let mut i = 0; - for x in it { - assert_eq!(x, ys[i]); - i += 1; - } - assert_eq!(i, ys.len()); -} - -/// Tests `FlatMap::fold` with items already picked off the front and back, -/// to make sure all parts of the `FlatMap` are folded correctly. -#[test] -fn test_iterator_flat_map_fold() { - let xs = [0, 3, 6]; - let ys = [1, 2, 3, 4, 5, 6, 7]; - let mut it = xs.iter().flat_map(|&x| x..x + 3); - assert_eq!(it.next(), Some(0)); - assert_eq!(it.next_back(), Some(8)); - let i = it.fold(0, |i, x| { - assert_eq!(x, ys[i]); - i + 1 - }); - assert_eq!(i, ys.len()); - - let mut it = xs.iter().flat_map(|&x| x..x + 3); - assert_eq!(it.next(), Some(0)); - assert_eq!(it.next_back(), Some(8)); - let i = it.rfold(ys.len(), |i, x| { - assert_eq!(x, ys[i - 1]); - i - 1 - }); - assert_eq!(i, 0); -} - -#[test] -fn test_flat_map_try_folds() { - let f = &|acc, x| i32::checked_add(acc * 2 / 3, x); - let mr = &|x| (5 * x)..(5 * x + 5); - assert_eq!((0..10).flat_map(mr).try_fold(7, f), (0..50).try_fold(7, f)); - assert_eq!((0..10).flat_map(mr).try_rfold(7, f), (0..50).try_rfold(7, f)); - let mut iter = (0..10).flat_map(mr); - iter.next(); - iter.next_back(); // have front and back iters in progress - assert_eq!(iter.try_rfold(7, f), (1..49).try_rfold(7, f)); - - let mut iter = (0..10).flat_map(|x| (4 * x)..(4 * x + 4)); - assert_eq!(iter.try_fold(0, i8::checked_add), None); - assert_eq!(iter.next(), Some(17)); - assert_eq!(iter.try_rfold(0, i8::checked_add), None); - assert_eq!(iter.next_back(), Some(35)); -} - -#[test] -fn test_double_ended_flat_map() { - let u = [0, 1]; - let v = [5, 6, 7, 8]; - let mut it = u.iter().flat_map(|x| &v[*x..v.len()]); - assert_eq!(it.next_back().unwrap(), &8); - assert_eq!(it.next().unwrap(), &5); - assert_eq!(it.next_back().unwrap(), &7); - assert_eq!(it.next_back().unwrap(), &6); - assert_eq!(it.next_back().unwrap(), &8); - assert_eq!(it.next().unwrap(), &6); - assert_eq!(it.next_back().unwrap(), &7); - assert_eq!(it.next_back(), None); - assert_eq!(it.next(), None); - assert_eq!(it.next_back(), None); -} diff --git a/library/core/tests/iter/adapters/flatten.rs b/library/core/tests/iter/adapters/flatten.rs deleted file mode 100644 index 1f953f2aa0110..0000000000000 --- a/library/core/tests/iter/adapters/flatten.rs +++ /dev/null @@ -1,280 +0,0 @@ -use super::*; -use core::assert_eq; -use core::iter::*; -use core::num::NonZero; - -#[test] -fn test_iterator_flatten() { - let xs = [0, 3, 6]; - let ys = [0, 1, 2, 3, 4, 5, 6, 7, 8]; - let it = xs.iter().map(|&x| (x..).step_by(1).take(3)).flatten(); - let mut i = 0; - for x in it { - assert_eq!(x, ys[i]); - i += 1; - } - assert_eq!(i, ys.len()); -} - -/// Tests `Flatten::fold` with items already picked off the front and back, -/// to make sure all parts of the `Flatten` are folded correctly. -#[test] -fn test_iterator_flatten_fold() { - let xs = [0, 3, 6]; - let ys = [1, 2, 3, 4, 5, 6, 7]; - let mut it = xs.iter().map(|&x| x..x + 3).flatten(); - assert_eq!(it.next(), Some(0)); - assert_eq!(it.next_back(), Some(8)); - let i = it.fold(0, |i, x| { - assert_eq!(x, ys[i]); - i + 1 - }); - assert_eq!(i, ys.len()); - - let mut it = xs.iter().map(|&x| x..x + 3).flatten(); - assert_eq!(it.next(), Some(0)); - assert_eq!(it.next_back(), Some(8)); - let i = it.rfold(ys.len(), |i, x| { - assert_eq!(x, ys[i - 1]); - i - 1 - }); - assert_eq!(i, 0); -} - -#[test] -fn test_flatten_try_folds() { - let f = &|acc, x| i32::checked_add(acc * 2 / 3, x); - let mr = &|x| (5 * x)..(5 * x + 5); - assert_eq!((0..10).map(mr).flatten().try_fold(7, f), (0..50).try_fold(7, f)); - assert_eq!((0..10).map(mr).flatten().try_rfold(7, f), (0..50).try_rfold(7, f)); - let mut iter = (0..10).map(mr).flatten(); - iter.next(); - iter.next_back(); // have front and back iters in progress - assert_eq!(iter.try_rfold(7, f), (1..49).try_rfold(7, f)); - - let mut iter = (0..10).map(|x| (4 * x)..(4 * x + 4)).flatten(); - assert_eq!(iter.try_fold(0, i8::checked_add), None); - assert_eq!(iter.next(), Some(17)); - assert_eq!(iter.try_rfold(0, i8::checked_add), None); - assert_eq!(iter.next_back(), Some(35)); -} - -#[test] -fn test_flatten_advance_by() { - let mut it = once(0..10).chain(once(10..30)).chain(once(30..40)).flatten(); - - assert_eq!(it.advance_by(5), Ok(())); - assert_eq!(it.next(), Some(5)); - assert_eq!(it.advance_by(9), Ok(())); - assert_eq!(it.next(), Some(15)); - assert_eq!(it.advance_back_by(4), Ok(())); - assert_eq!(it.next_back(), Some(35)); - assert_eq!(it.advance_back_by(9), Ok(())); - assert_eq!(it.next_back(), Some(25)); - - assert_eq!(it.advance_by(usize::MAX), Err(NonZero::new(usize::MAX - 9).unwrap())); - assert_eq!(it.advance_back_by(usize::MAX), Err(NonZero::new(usize::MAX).unwrap())); - assert_eq!(it.advance_by(0), Ok(())); - assert_eq!(it.advance_back_by(0), Ok(())); - assert_eq!(it.size_hint(), (0, Some(0))); -} - -#[test] -fn test_flatten_non_fused_outer() { - let mut iter = NonFused::new(once(0..2)).flatten(); - - assert_eq!(iter.next_back(), Some(1)); - assert_eq!(iter.next(), Some(0)); - assert_eq!(iter.next(), None); - assert_eq!(iter.next(), None); - - let mut iter = NonFused::new(once(0..2)).flatten(); - - assert_eq!(iter.next(), Some(0)); - assert_eq!(iter.next_back(), Some(1)); - assert_eq!(iter.next_back(), None); - assert_eq!(iter.next_back(), None); -} - -#[test] -fn test_flatten_non_fused_inner() { - let mut iter = once(0..1).chain(once(1..3)).flat_map(NonFused::new); - - assert_eq!(iter.next_back(), Some(2)); - assert_eq!(iter.next(), Some(0)); - assert_eq!(iter.next(), Some(1)); - assert_eq!(iter.next(), None); - assert_eq!(iter.next(), None); - - let mut iter = once(0..1).chain(once(1..3)).flat_map(NonFused::new); - - assert_eq!(iter.next(), Some(0)); - assert_eq!(iter.next_back(), Some(2)); - assert_eq!(iter.next_back(), Some(1)); - assert_eq!(iter.next_back(), None); - assert_eq!(iter.next_back(), None); -} - -#[test] -fn test_double_ended_flatten() { - let u = [0, 1]; - let v = [5, 6, 7, 8]; - let mut it = u.iter().map(|x| &v[*x..v.len()]).flatten(); - assert_eq!(it.next_back().unwrap(), &8); - assert_eq!(it.next().unwrap(), &5); - assert_eq!(it.next_back().unwrap(), &7); - assert_eq!(it.next_back().unwrap(), &6); - assert_eq!(it.next_back().unwrap(), &8); - assert_eq!(it.next().unwrap(), &6); - assert_eq!(it.next_back().unwrap(), &7); - assert_eq!(it.next_back(), None); - assert_eq!(it.next(), None); - assert_eq!(it.next_back(), None); -} - -#[test] -fn test_trusted_len_flatten() { - fn assert_trusted_len(_: &T) {} - let mut iter = IntoIterator::into_iter([[0; 3]; 4]).flatten(); - assert_trusted_len(&iter); - - assert_eq!(iter.size_hint(), (12, Some(12))); - iter.next(); - assert_eq!(iter.size_hint(), (11, Some(11))); - iter.next_back(); - assert_eq!(iter.size_hint(), (10, Some(10))); - - let iter = IntoIterator::into_iter([[(); usize::MAX]; 1]).flatten(); - assert_eq!(iter.size_hint(), (usize::MAX, Some(usize::MAX))); - - let iter = IntoIterator::into_iter([[(); usize::MAX]; 2]).flatten(); - assert_eq!(iter.size_hint(), (usize::MAX, None)); - - let mut a = [(); 10]; - let mut b = [(); 10]; - - let iter = IntoIterator::into_iter([&mut a, &mut b]).flatten(); - assert_trusted_len(&iter); - assert_eq!(iter.size_hint(), (20, Some(20))); - core::mem::drop(iter); - - let iter = IntoIterator::into_iter([&a, &b]).flatten(); - assert_trusted_len(&iter); - assert_eq!(iter.size_hint(), (20, Some(20))); - - let iter = [(), (), ()].iter().flat_map(|_| [(); 1000]); - assert_trusted_len(&iter); - assert_eq!(iter.size_hint(), (3000, Some(3000))); - - let iter = [(), ()].iter().flat_map(|_| &a); - assert_trusted_len(&iter); - assert_eq!(iter.size_hint(), (20, Some(20))); -} - -#[test] -fn test_flatten_count() { - let mut it = once(0..10).chain(once(10..30)).chain(once(30..40)).flatten(); - - assert_eq!(it.clone().count(), 40); - assert_eq!(it.advance_by(5), Ok(())); - assert_eq!(it.clone().count(), 35); - assert_eq!(it.advance_back_by(5), Ok(())); - assert_eq!(it.clone().count(), 30); - assert_eq!(it.advance_by(10), Ok(())); - assert_eq!(it.clone().count(), 20); - assert_eq!(it.advance_back_by(8), Ok(())); - assert_eq!(it.clone().count(), 12); - assert_eq!(it.advance_by(4), Ok(())); - assert_eq!(it.clone().count(), 8); - assert_eq!(it.advance_back_by(5), Ok(())); - assert_eq!(it.clone().count(), 3); - assert_eq!(it.advance_by(3), Ok(())); - assert_eq!(it.clone().count(), 0); -} - -#[test] -fn test_flatten_last() { - let mut it = once(0..10).chain(once(10..30)).chain(once(30..40)).flatten(); - - assert_eq!(it.clone().last(), Some(39)); - assert_eq!(it.advance_by(5), Ok(())); // 5..40 - assert_eq!(it.clone().last(), Some(39)); - assert_eq!(it.advance_back_by(5), Ok(())); // 5..35 - assert_eq!(it.clone().last(), Some(34)); - assert_eq!(it.advance_by(10), Ok(())); // 15..35 - assert_eq!(it.clone().last(), Some(34)); - assert_eq!(it.advance_back_by(8), Ok(())); // 15..27 - assert_eq!(it.clone().last(), Some(26)); - assert_eq!(it.advance_by(4), Ok(())); // 19..27 - assert_eq!(it.clone().last(), Some(26)); - assert_eq!(it.advance_back_by(5), Ok(())); // 19..22 - assert_eq!(it.clone().last(), Some(21)); - assert_eq!(it.advance_by(3), Ok(())); // 22..22 - assert_eq!(it.clone().last(), None); -} - -#[test] -fn test_flatten_one_shot() { - // This could be `filter_map`, but people often do flatten options. - let mut it = (0i8..10).flat_map(|i| NonZero::new(i % 7)); - assert_eq!(it.size_hint(), (0, Some(10))); - assert_eq!(it.clone().count(), 8); - assert_eq!(it.clone().last(), NonZero::new(2)); - - // sum -> fold - let sum: i8 = it.clone().map(|n| n.get()).sum(); - assert_eq!(sum, 24); - - // the product overflows at 6, remaining are 7,8,9 -> 1,2 - let one = NonZero::new(1i8).unwrap(); - let product = it.try_fold(one, |acc, x| acc.checked_mul(x)); - assert_eq!(product, None); - assert_eq!(it.size_hint(), (0, Some(3))); - assert_eq!(it.clone().count(), 2); - - assert_eq!(it.advance_by(0), Ok(())); - assert_eq!(it.clone().next(), NonZero::new(1)); - assert_eq!(it.advance_by(1), Ok(())); - assert_eq!(it.clone().next(), NonZero::new(2)); - assert_eq!(it.advance_by(100), Err(NonZero::new(99).unwrap())); - assert_eq!(it.next(), None); -} - -#[test] -fn test_flatten_one_shot_rev() { - let mut it = (0i8..10).flat_map(|i| NonZero::new(i % 7)).rev(); - assert_eq!(it.size_hint(), (0, Some(10))); - assert_eq!(it.clone().count(), 8); - assert_eq!(it.clone().last(), NonZero::new(1)); - - // sum -> Rev fold -> rfold - let sum: i8 = it.clone().map(|n| n.get()).sum(); - assert_eq!(sum, 24); - - // Rev try_fold -> try_rfold - // the product overflows at 4, remaining are 3,2,1,0 -> 3,2,1 - let one = NonZero::new(1i8).unwrap(); - let product = it.try_fold(one, |acc, x| acc.checked_mul(x)); - assert_eq!(product, None); - assert_eq!(it.size_hint(), (0, Some(4))); - assert_eq!(it.clone().count(), 3); - - // Rev advance_by -> advance_back_by - assert_eq!(it.advance_by(0), Ok(())); - assert_eq!(it.clone().next(), NonZero::new(3)); - assert_eq!(it.advance_by(1), Ok(())); - assert_eq!(it.clone().next(), NonZero::new(2)); - assert_eq!(it.advance_by(100), Err(NonZero::new(98).unwrap())); - assert_eq!(it.next(), None); -} - -#[test] -fn test_flatten_one_shot_arrays() { - let it = (0..10).flat_map(|i| [i]); - assert_eq!(it.size_hint(), (10, Some(10))); - assert_eq!(it.sum::(), 45); - - let mut it = (0..10).flat_map(|_| -> [i32; 0] { [] }); - assert_eq!(it.size_hint(), (0, Some(0))); - assert_eq!(it.next(), None); -} diff --git a/library/core/tests/iter/adapters/fuse.rs b/library/core/tests/iter/adapters/fuse.rs deleted file mode 100644 index f41b379b3ac7f..0000000000000 --- a/library/core/tests/iter/adapters/fuse.rs +++ /dev/null @@ -1,75 +0,0 @@ -use core::iter::*; - -#[test] -fn test_fuse_nth() { - let xs = [0, 1, 2]; - let mut it = xs.iter(); - - assert_eq!(it.len(), 3); - assert_eq!(it.nth(2), Some(&2)); - assert_eq!(it.len(), 0); - assert_eq!(it.nth(2), None); - assert_eq!(it.len(), 0); -} - -#[test] -fn test_fuse_last() { - let xs = [0, 1, 2]; - let it = xs.iter(); - - assert_eq!(it.len(), 3); - assert_eq!(it.last(), Some(&2)); -} - -#[test] -fn test_fuse_count() { - let xs = [0, 1, 2]; - let it = xs.iter(); - - assert_eq!(it.len(), 3); - assert_eq!(it.count(), 3); - // Can't check len now because count consumes. -} - -#[test] -fn test_fuse_fold() { - let xs = [0, 1, 2]; - let it = xs.iter(); // `FusedIterator` - let i = it.fuse().fold(0, |i, &x| { - assert_eq!(x, xs[i]); - i + 1 - }); - assert_eq!(i, xs.len()); - - let it = xs.iter(); // `FusedIterator` - let i = it.fuse().rfold(xs.len(), |i, &x| { - assert_eq!(x, xs[i - 1]); - i - 1 - }); - assert_eq!(i, 0); - - let it = xs.iter().scan((), |_, &x| Some(x)); // `!FusedIterator` - let i = it.fuse().fold(0, |i, x| { - assert_eq!(x, xs[i]); - i + 1 - }); - assert_eq!(i, xs.len()); -} - -#[test] -fn test_fuse() { - let mut it = 0..3; - assert_eq!(it.len(), 3); - assert_eq!(it.next(), Some(0)); - assert_eq!(it.len(), 2); - assert_eq!(it.next(), Some(1)); - assert_eq!(it.len(), 1); - assert_eq!(it.next(), Some(2)); - assert_eq!(it.len(), 0); - assert_eq!(it.next(), None); - assert_eq!(it.len(), 0); - assert_eq!(it.next(), None); - assert_eq!(it.len(), 0); - assert_eq!(it.next(), None); - assert_eq!(it.len(), 0); -} diff --git a/library/core/tests/iter/adapters/inspect.rs b/library/core/tests/iter/adapters/inspect.rs deleted file mode 100644 index 939e3a28a7204..0000000000000 --- a/library/core/tests/iter/adapters/inspect.rs +++ /dev/null @@ -1,38 +0,0 @@ -use core::iter::*; - -#[test] -fn test_inspect() { - let xs = [1, 2, 3, 4]; - let mut n = 0; - - let ys = xs.iter().cloned().inspect(|_| n += 1).collect::>(); - - assert_eq!(n, xs.len()); - assert_eq!(&xs[..], &ys[..]); -} - -#[test] -fn test_inspect_fold() { - let xs = [1, 2, 3, 4]; - let mut n = 0; - { - let it = xs.iter().inspect(|_| n += 1); - let i = it.fold(0, |i, &x| { - assert_eq!(x, xs[i]); - i + 1 - }); - assert_eq!(i, xs.len()); - } - assert_eq!(n, xs.len()); - - let mut n = 0; - { - let it = xs.iter().inspect(|_| n += 1); - let i = it.rfold(xs.len(), |i, &x| { - assert_eq!(x, xs[i - 1]); - i - 1 - }); - assert_eq!(i, 0); - } - assert_eq!(n, xs.len()); -} diff --git a/library/core/tests/iter/adapters/intersperse.rs b/library/core/tests/iter/adapters/intersperse.rs deleted file mode 100644 index 72ae59b6b2f5f..0000000000000 --- a/library/core/tests/iter/adapters/intersperse.rs +++ /dev/null @@ -1,154 +0,0 @@ -use core::iter::*; - -#[test] -fn test_intersperse() { - let v = std::iter::empty().intersperse(0u32).collect::>(); - assert_eq!(v, vec![]); - - let v = std::iter::once(1).intersperse(0).collect::>(); - assert_eq!(v, vec![1]); - - let xs = ["a", "", "b", "c"]; - let v: Vec<&str> = xs.iter().map(|x| *x).intersperse(", ").collect(); - let text: String = v.concat(); - assert_eq!(text, "a, , b, c".to_string()); - - let ys = [0, 1, 2, 3]; - let mut it = ys[..0].iter().map(|x| *x).intersperse(1); - assert!(it.next() == None); -} - -#[test] -fn test_intersperse_size_hint() { - let iter = std::iter::empty::().intersperse(0); - assert_eq!(iter.size_hint(), (0, Some(0))); - - let xs = ["a", "", "b", "c"]; - let mut iter = xs.iter().map(|x| *x).intersperse(", "); - assert_eq!(iter.size_hint(), (7, Some(7))); - - assert_eq!(iter.next(), Some("a")); - assert_eq!(iter.size_hint(), (6, Some(6))); - assert_eq!(iter.next(), Some(", ")); - assert_eq!(iter.size_hint(), (5, Some(5))); - - assert_eq!([].iter().intersperse(&()).size_hint(), (0, Some(0))); -} - -#[test] -fn test_fold_specialization_intersperse() { - let mut iter = (1..2).intersperse(0); - iter.clone().for_each(|x| assert_eq!(Some(x), iter.next())); - - let mut iter = (1..3).intersperse(0); - iter.clone().for_each(|x| assert_eq!(Some(x), iter.next())); - - let mut iter = (1..4).intersperse(0); - iter.clone().for_each(|x| assert_eq!(Some(x), iter.next())); -} - -#[test] -fn test_try_fold_specialization_intersperse_ok() { - let mut iter = (1..2).intersperse(0); - iter.clone().try_for_each(|x| { - assert_eq!(Some(x), iter.next()); - Some(()) - }); - - let mut iter = (1..3).intersperse(0); - iter.clone().try_for_each(|x| { - assert_eq!(Some(x), iter.next()); - Some(()) - }); - - let mut iter = (1..4).intersperse(0); - iter.clone().try_for_each(|x| { - assert_eq!(Some(x), iter.next()); - Some(()) - }); -} - -#[test] -fn test_intersperse_with() { - #[derive(PartialEq, Debug)] - struct NotClone { - u: u32, - } - let r = [NotClone { u: 0 }, NotClone { u: 1 }] - .into_iter() - .intersperse_with(|| NotClone { u: 2 }) - .collect::>(); - assert_eq!(r, vec![NotClone { u: 0 }, NotClone { u: 2 }, NotClone { u: 1 }]); - - let mut ctr = 100; - let separator = || { - ctr *= 2; - ctr - }; - let r = (0..3).intersperse_with(separator).collect::>(); - assert_eq!(r, vec![0, 200, 1, 400, 2]); -} - -#[test] -fn test_intersperse_fold() { - let v = (1..4).intersperse(9).fold(Vec::new(), |mut acc, x| { - acc.push(x); - acc - }); - assert_eq!(v.as_slice(), [1, 9, 2, 9, 3]); - - let mut iter = (1..4).intersperse(9); - assert_eq!(iter.next(), Some(1)); - let v = iter.fold(Vec::new(), |mut acc, x| { - acc.push(x); - acc - }); - assert_eq!(v.as_slice(), [9, 2, 9, 3]); - - struct NoneAtStart(i32); // Produces: None, Some(2), Some(3), None, ... - impl Iterator for NoneAtStart { - type Item = i32; - fn next(&mut self) -> Option { - self.0 += 1; - Some(self.0).filter(|i| i % 3 != 1) - } - } - - let v = NoneAtStart(0).intersperse(1000).fold(0, |a, b| a + b); - assert_eq!(v, 0); -} - -#[test] -fn test_intersperse_collect_string() { - let contents = [1, 2, 3]; - - let contents_string = contents - .into_iter() - .map(|id| id.to_string()) - .intersperse(", ".to_owned()) - .collect::(); - assert_eq!(contents_string, "1, 2, 3"); -} - -#[test] -fn test_try_fold_specialization_intersperse_err() { - let orig_iter = ["a", "b"].iter().copied().intersperse("-"); - - // Abort after the first item. - let mut iter = orig_iter.clone(); - iter.try_for_each(|_| None::<()>); - assert_eq!(iter.next(), Some("-")); - assert_eq!(iter.next(), Some("b")); - assert_eq!(iter.next(), None); - - // Abort after the second item. - let mut iter = orig_iter.clone(); - iter.try_for_each(|item| if item == "-" { None } else { Some(()) }); - assert_eq!(iter.next(), Some("b")); - assert_eq!(iter.next(), None); - - // Abort after the third item. - let mut iter = orig_iter.clone(); - iter.try_for_each(|item| if item == "b" { None } else { Some(()) }); - assert_eq!(iter.next(), None); -} diff --git a/library/core/tests/iter/adapters/map.rs b/library/core/tests/iter/adapters/map.rs deleted file mode 100644 index 77ce3819b322e..0000000000000 --- a/library/core/tests/iter/adapters/map.rs +++ /dev/null @@ -1,27 +0,0 @@ -use core::iter::*; - -#[test] -fn test_map_try_folds() { - let f = &|acc, x| i32::checked_add(2 * acc, x); - assert_eq!((0..10).map(|x| x + 3).try_fold(7, f), (3..13).try_fold(7, f)); - assert_eq!((0..10).map(|x| x + 3).try_rfold(7, f), (3..13).try_rfold(7, f)); - - let mut iter = (0..40).map(|x| x + 10); - assert_eq!(iter.try_fold(0, i8::checked_add), None); - assert_eq!(iter.next(), Some(20)); - assert_eq!(iter.try_rfold(0, i8::checked_add), None); - assert_eq!(iter.next_back(), Some(46)); -} - -#[test] -fn test_double_ended_map() { - let xs = [1, 2, 3, 4, 5, 6]; - let mut it = xs.iter().map(|&x| x * -1); - assert_eq!(it.next(), Some(-1)); - assert_eq!(it.next(), Some(-2)); - assert_eq!(it.next_back(), Some(-6)); - assert_eq!(it.next_back(), Some(-5)); - assert_eq!(it.next(), Some(-3)); - assert_eq!(it.next_back(), Some(-4)); - assert_eq!(it.next(), None); -} diff --git a/library/core/tests/iter/adapters/map_windows.rs b/library/core/tests/iter/adapters/map_windows.rs deleted file mode 100644 index 7fb2408f8acb7..0000000000000 --- a/library/core/tests/iter/adapters/map_windows.rs +++ /dev/null @@ -1,283 +0,0 @@ -use std::sync::atomic::{AtomicUsize, Ordering::SeqCst}; - -#[cfg(not(panic = "abort"))] -mod drop_checks { - //! These tests mainly make sure the elements are correctly dropped. - use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering::SeqCst}; - - #[derive(Debug)] - struct DropInfo { - dropped_twice: AtomicBool, - alive_count: AtomicUsize, - } - - impl DropInfo { - const fn new() -> Self { - Self { dropped_twice: AtomicBool::new(false), alive_count: AtomicUsize::new(0) } - } - - #[track_caller] - fn check(&self) { - assert!(!self.dropped_twice.load(SeqCst), "a value was dropped twice"); - assert_eq!(self.alive_count.load(SeqCst), 0); - } - } - - #[derive(Debug)] - struct DropCheck<'a> { - info: &'a DropInfo, - was_dropped: bool, - } - - impl<'a> DropCheck<'a> { - fn new(info: &'a DropInfo) -> Self { - info.alive_count.fetch_add(1, SeqCst); - - Self { info, was_dropped: false } - } - } - - impl Drop for DropCheck<'_> { - fn drop(&mut self) { - if self.was_dropped { - self.info.dropped_twice.store(true, SeqCst); - } - self.was_dropped = true; - - self.info.alive_count.fetch_sub(1, SeqCst); - } - } - - fn iter(info: &DropInfo, len: usize, panic_at: usize) -> impl Iterator> { - (0..len).map(move |i| { - if i == panic_at { - panic!("intended panic"); - } - DropCheck::new(info) - }) - } - - #[track_caller] - fn check(len: usize, panic_at: usize) { - check_drops(|info| { - iter(info, len, panic_at).map_windows(|_: &[_; N]| {}).last(); - }); - } - - #[track_caller] - fn check_drops(f: impl FnOnce(&DropInfo)) { - let info = DropInfo::new(); - let _ = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| { - f(&info); - })); - info.check(); - } - - #[test] - fn no_iter_panic_n1() { - check::<1>(0, 100); - check::<1>(1, 100); - check::<1>(2, 100); - check::<1>(13, 100); - } - - #[test] - fn no_iter_panic_n2() { - check::<2>(0, 100); - check::<2>(1, 100); - check::<2>(2, 100); - check::<2>(3, 100); - check::<2>(13, 100); - } - - #[test] - fn no_iter_panic_n5() { - check::<5>(0, 100); - check::<5>(1, 100); - check::<5>(2, 100); - check::<5>(13, 100); - check::<5>(30, 100); - } - - #[test] - fn panic_in_first_batch() { - check::<1>(7, 0); - - check::<2>(7, 0); - check::<2>(7, 1); - - check::<3>(7, 0); - check::<3>(7, 1); - check::<3>(7, 2); - } - - #[test] - fn panic_in_middle() { - check::<1>(7, 1); - check::<1>(7, 5); - check::<1>(7, 6); - - check::<2>(7, 2); - check::<2>(7, 5); - check::<2>(7, 6); - - check::<5>(13, 5); - check::<5>(13, 8); - check::<5>(13, 12); - } - - #[test] - fn len_equals_n() { - check::<1>(1, 100); - check::<1>(1, 0); - - check::<2>(2, 100); - check::<2>(2, 0); - check::<2>(2, 1); - - check::<5>(5, 100); - check::<5>(5, 0); - check::<5>(5, 1); - check::<5>(5, 4); - } -} - -#[test] -fn output_n1() { - assert_eq!("".chars().map_windows(|[c]| *c).collect::>(), vec![]); - assert_eq!("x".chars().map_windows(|[c]| *c).collect::>(), vec!['x']); - assert_eq!("abcd".chars().map_windows(|[c]| *c).collect::>(), vec!['a', 'b', 'c', 'd']); -} - -#[test] -fn output_n2() { - assert_eq!( - "".chars().map_windows(|a: &[_; 2]| *a).collect::>(), - >::new(), - ); - assert_eq!("ab".chars().map_windows(|a: &[_; 2]| *a).collect::>(), vec![['a', 'b']]); - assert_eq!( - "abcd".chars().map_windows(|a: &[_; 2]| *a).collect::>(), - vec![['a', 'b'], ['b', 'c'], ['c', 'd']], - ); -} - -#[test] -fn test_case_from_pr_82413_comment() { - for () in std::iter::repeat("0".to_owned()).map_windows(|_: &[_; 3]| {}).take(4) {} -} - -#[test] -#[should_panic = "array in `Iterator::map_windows` must contain more than 0 elements"] -fn check_zero_window() { - let _ = std::iter::repeat(0).map_windows(|_: &[_; 0]| ()); -} - -#[test] -fn test_zero_sized_type() { - #[derive(Copy, Clone, Debug, Eq, PartialEq)] - struct Data; - let data: Vec<_> = - std::iter::repeat(Data).take(10).map_windows(|arr: &[Data; 5]| *arr).collect(); - assert_eq!(data, [[Data; 5]; 6]); -} - -#[test] -#[should_panic = "array size of `Iterator::map_windows` is too large"] -fn test_too_large_array_size() { - let _ = std::iter::repeat(()).map_windows(|arr: &[(); usize::MAX]| *arr); -} - -#[test] -fn test_laziness() { - let counter = AtomicUsize::new(0); - let mut iter = (0..5) - .inspect(|_| { - counter.fetch_add(1, SeqCst); - }) - .map_windows(|arr: &[i32; 2]| *arr); - assert_eq!(counter.load(SeqCst), 0); - - assert_eq!(iter.next(), Some([0, 1])); - // The first iteration consumes N items (N = 2). - assert_eq!(counter.load(SeqCst), 2); - - assert_eq!(iter.next(), Some([1, 2])); - assert_eq!(counter.load(SeqCst), 3); - - assert_eq!(iter.next(), Some([2, 3])); - assert_eq!(counter.load(SeqCst), 4); - - assert_eq!(iter.next(), Some([3, 4])); - assert_eq!(counter.load(SeqCst), 5); - - assert_eq!(iter.next(), None); - assert_eq!(counter.load(SeqCst), 5); -} - -#[test] -fn test_size_hint() { - struct SizeHintCheckHelper((usize, Option)); - - impl Iterator for SizeHintCheckHelper { - type Item = i32; - - fn next(&mut self) -> Option { - let (ref mut lo, ref mut hi) = self.0; - let next = (*hi != Some(0)).then_some(0); - *lo = lo.saturating_sub(1); - if let Some(hi) = hi { - *hi = hi.saturating_sub(1); - } - next - } - - fn size_hint(&self) -> (usize, Option) { - self.0 - } - } - - fn check_size_hint( - size_hint: (usize, Option), - mut mapped_size_hint: (usize, Option), - ) { - let mut iter = SizeHintCheckHelper(size_hint); - let mut mapped_iter = iter.by_ref().map_windows(|_: &[_; N]| ()); - while mapped_iter.size_hint().0 > 0 { - assert_eq!(mapped_iter.size_hint(), mapped_size_hint); - assert!(mapped_iter.next().is_some()); - mapped_size_hint.0 -= 1; - mapped_size_hint.1 = mapped_size_hint.1.map(|hi| hi.saturating_sub(1)); - } - } - - check_size_hint::<1>((0, None), (0, None)); - check_size_hint::<1>((0, Some(0)), (0, Some(0))); - check_size_hint::<1>((0, Some(2)), (0, Some(2))); - check_size_hint::<1>((1, None), (1, None)); - check_size_hint::<1>((1, Some(1)), (1, Some(1))); - check_size_hint::<1>((1, Some(4)), (1, Some(4))); - check_size_hint::<1>((5, None), (5, None)); - check_size_hint::<1>((5, Some(5)), (5, Some(5))); - check_size_hint::<1>((5, Some(10)), (5, Some(10))); - - check_size_hint::<2>((0, None), (0, None)); - check_size_hint::<2>((0, Some(0)), (0, Some(0))); - check_size_hint::<2>((0, Some(2)), (0, Some(1))); - check_size_hint::<2>((1, None), (0, None)); - check_size_hint::<2>((1, Some(1)), (0, Some(0))); - check_size_hint::<2>((1, Some(4)), (0, Some(3))); - check_size_hint::<2>((5, None), (4, None)); - check_size_hint::<2>((5, Some(5)), (4, Some(4))); - check_size_hint::<2>((5, Some(10)), (4, Some(9))); - - check_size_hint::<5>((0, None), (0, None)); - check_size_hint::<5>((0, Some(0)), (0, Some(0))); - check_size_hint::<5>((0, Some(2)), (0, Some(0))); - check_size_hint::<5>((1, None), (0, None)); - check_size_hint::<5>((1, Some(1)), (0, Some(0))); - check_size_hint::<5>((1, Some(4)), (0, Some(0))); - check_size_hint::<5>((5, None), (1, None)); - check_size_hint::<5>((5, Some(5)), (1, Some(1))); - check_size_hint::<5>((5, Some(10)), (1, Some(6))); -} diff --git a/library/core/tests/iter/adapters/mod.rs b/library/core/tests/iter/adapters/mod.rs deleted file mode 100644 index dedb4c0a9dd5f..0000000000000 --- a/library/core/tests/iter/adapters/mod.rs +++ /dev/null @@ -1,210 +0,0 @@ -mod array_chunks; -mod by_ref_sized; -mod chain; -mod cloned; -mod copied; -mod cycle; -mod enumerate; -mod filter; -mod filter_map; -mod flat_map; -mod flatten; -mod fuse; -mod inspect; -mod intersperse; -mod map; -mod map_windows; -mod peekable; -mod scan; -mod skip; -mod skip_while; -mod step_by; -mod take; -mod take_while; -mod zip; - -use core::cell::Cell; - -/// An iterator that panics whenever `next` or `next_back` is called -/// after `None` has already been returned. This does not violate -/// `Iterator`'s contract. Used to test that iterator adapters don't -/// poll their inner iterators after exhausting them. -pub struct NonFused { - iter: I, - done: bool, -} - -impl NonFused { - pub fn new(iter: I) -> Self { - Self { iter, done: false } - } -} - -impl Iterator for NonFused -where - I: Iterator, -{ - type Item = I::Item; - - fn next(&mut self) -> Option { - assert!(!self.done, "this iterator has already returned None"); - self.iter.next().or_else(|| { - self.done = true; - None - }) - } -} - -impl DoubleEndedIterator for NonFused -where - I: DoubleEndedIterator, -{ - fn next_back(&mut self) -> Option { - assert!(!self.done, "this iterator has already returned None"); - self.iter.next_back().or_else(|| { - self.done = true; - None - }) - } -} - -/// An iterator wrapper that panics whenever `next` or `next_back` is called -/// after `None` has been returned. -pub struct Unfuse { - iter: I, - exhausted: bool, -} - -impl Unfuse { - pub fn new(iter: T) -> Self - where - T: IntoIterator, - { - Self { iter: iter.into_iter(), exhausted: false } - } -} - -impl Iterator for Unfuse -where - I: Iterator, -{ - type Item = I::Item; - - fn next(&mut self) -> Option { - assert!(!self.exhausted); - let next = self.iter.next(); - self.exhausted = next.is_none(); - next - } -} - -impl DoubleEndedIterator for Unfuse -where - I: DoubleEndedIterator, -{ - fn next_back(&mut self) -> Option { - assert!(!self.exhausted); - let next = self.iter.next_back(); - self.exhausted = next.is_none(); - next - } -} - -pub struct Toggle { - is_empty: bool, -} - -impl Iterator for Toggle { - type Item = (); - - // alternates between `None` and `Some(())` - fn next(&mut self) -> Option { - if self.is_empty { - self.is_empty = false; - None - } else { - self.is_empty = true; - Some(()) - } - } - - fn size_hint(&self) -> (usize, Option) { - if self.is_empty { (0, Some(0)) } else { (1, Some(1)) } - } -} - -impl DoubleEndedIterator for Toggle { - fn next_back(&mut self) -> Option { - self.next() - } -} - -/// This is an iterator that follows the Iterator contract, -/// but it is not fused. After having returned None once, it will start -/// producing elements if .next() is called again. -pub struct CycleIter<'a, T> { - index: usize, - data: &'a [T], -} - -impl<'a, T> CycleIter<'a, T> { - pub fn new(data: &'a [T]) -> Self { - Self { index: 0, data } - } -} - -impl<'a, T> Iterator for CycleIter<'a, T> { - type Item = &'a T; - fn next(&mut self) -> Option { - let elt = self.data.get(self.index); - self.index += 1; - self.index %= 1 + self.data.len(); - elt - } -} - -#[derive(Debug)] -struct CountClone(Cell); - -impl CountClone { - pub fn new() -> Self { - Self(Cell::new(0)) - } -} - -impl PartialEq for CountClone { - fn eq(&self, rhs: &i32) -> bool { - self.0.get() == *rhs - } -} - -impl Clone for CountClone { - fn clone(&self) -> Self { - let ret = CountClone(self.0.clone()); - let n = self.0.get(); - self.0.set(n + 1); - ret - } -} - -#[derive(Debug, Clone)] -struct CountDrop<'a> { - dropped: bool, - count: &'a Cell, -} - -impl<'a> CountDrop<'a> { - pub fn new(count: &'a Cell) -> Self { - Self { dropped: false, count } - } -} - -impl Drop for CountDrop<'_> { - fn drop(&mut self) { - if self.dropped { - panic!("double drop"); - } - self.dropped = true; - self.count.set(self.count.get() + 1); - } -} diff --git a/library/core/tests/iter/adapters/peekable.rs b/library/core/tests/iter/adapters/peekable.rs deleted file mode 100644 index c1a1c29b609b7..0000000000000 --- a/library/core/tests/iter/adapters/peekable.rs +++ /dev/null @@ -1,272 +0,0 @@ -use super::*; -use core::iter::*; - -#[test] -fn test_iterator_peekable() { - let xs = vec![0, 1, 2, 3, 4, 5]; - - let mut it = xs.iter().cloned().peekable(); - assert_eq!(it.len(), 6); - assert_eq!(it.peek().unwrap(), &0); - assert_eq!(it.len(), 6); - assert_eq!(it.next().unwrap(), 0); - assert_eq!(it.len(), 5); - assert_eq!(it.next().unwrap(), 1); - assert_eq!(it.len(), 4); - assert_eq!(it.next().unwrap(), 2); - assert_eq!(it.len(), 3); - assert_eq!(it.peek().unwrap(), &3); - assert_eq!(it.len(), 3); - assert_eq!(it.peek().unwrap(), &3); - assert_eq!(it.len(), 3); - assert_eq!(it.next().unwrap(), 3); - assert_eq!(it.len(), 2); - assert_eq!(it.next().unwrap(), 4); - assert_eq!(it.len(), 1); - assert_eq!(it.peek().unwrap(), &5); - assert_eq!(it.len(), 1); - assert_eq!(it.next().unwrap(), 5); - assert_eq!(it.len(), 0); - assert!(it.peek().is_none()); - assert_eq!(it.len(), 0); - assert!(it.next().is_none()); - assert_eq!(it.len(), 0); - - let mut it = xs.iter().cloned().peekable(); - assert_eq!(it.len(), 6); - assert_eq!(it.peek().unwrap(), &0); - assert_eq!(it.len(), 6); - assert_eq!(it.next_back().unwrap(), 5); - assert_eq!(it.len(), 5); - assert_eq!(it.next_back().unwrap(), 4); - assert_eq!(it.len(), 4); - assert_eq!(it.next_back().unwrap(), 3); - assert_eq!(it.len(), 3); - assert_eq!(it.peek().unwrap(), &0); - assert_eq!(it.len(), 3); - assert_eq!(it.peek().unwrap(), &0); - assert_eq!(it.len(), 3); - assert_eq!(it.next_back().unwrap(), 2); - assert_eq!(it.len(), 2); - assert_eq!(it.next_back().unwrap(), 1); - assert_eq!(it.len(), 1); - assert_eq!(it.peek().unwrap(), &0); - assert_eq!(it.len(), 1); - assert_eq!(it.next_back().unwrap(), 0); - assert_eq!(it.len(), 0); - assert!(it.peek().is_none()); - assert_eq!(it.len(), 0); - assert!(it.next_back().is_none()); - assert_eq!(it.len(), 0); -} - -#[test] -fn test_iterator_peekable_count() { - let xs = [0, 1, 2, 3, 4, 5]; - let ys = [10]; - let zs: [i32; 0] = []; - - assert_eq!(xs.iter().peekable().count(), 6); - - let mut it = xs.iter().peekable(); - assert_eq!(it.peek(), Some(&&0)); - assert_eq!(it.count(), 6); - - assert_eq!(ys.iter().peekable().count(), 1); - - let mut it = ys.iter().peekable(); - assert_eq!(it.peek(), Some(&&10)); - assert_eq!(it.count(), 1); - - assert_eq!(zs.iter().peekable().count(), 0); - - let mut it = zs.iter().peekable(); - assert_eq!(it.peek(), None); -} - -#[test] -fn test_iterator_peekable_nth() { - let xs = [0, 1, 2, 3, 4, 5]; - let mut it = xs.iter().peekable(); - - assert_eq!(it.peek(), Some(&&0)); - assert_eq!(it.nth(0), Some(&0)); - assert_eq!(it.peek(), Some(&&1)); - assert_eq!(it.nth(1), Some(&2)); - assert_eq!(it.peek(), Some(&&3)); - assert_eq!(it.nth(2), Some(&5)); - assert_eq!(it.next(), None); -} - -#[test] -fn test_iterator_peekable_last() { - let xs = [0, 1, 2, 3, 4, 5]; - let ys = [0]; - - let mut it = xs.iter().peekable(); - assert_eq!(it.peek(), Some(&&0)); - assert_eq!(it.last(), Some(&5)); - - let mut it = ys.iter().peekable(); - assert_eq!(it.peek(), Some(&&0)); - assert_eq!(it.last(), Some(&0)); - - let mut it = ys.iter().peekable(); - assert_eq!(it.next(), Some(&0)); - assert_eq!(it.peek(), None); - assert_eq!(it.last(), None); -} - -#[test] -fn test_iterator_peekable_fold() { - let xs = [0, 1, 2, 3, 4, 5]; - let mut it = xs.iter().peekable(); - assert_eq!(it.peek(), Some(&&0)); - let i = it.fold(0, |i, &x| { - assert_eq!(x, xs[i]); - i + 1 - }); - assert_eq!(i, xs.len()); -} - -#[test] -fn test_iterator_peekable_rfold() { - let xs = [0, 1, 2, 3, 4, 5]; - let mut it = xs.iter().peekable(); - assert_eq!(it.peek(), Some(&&0)); - let i = it.rfold(0, |i, &x| { - assert_eq!(x, xs[xs.len() - 1 - i]); - i + 1 - }); - assert_eq!(i, xs.len()); -} - -#[test] -fn test_iterator_peekable_next_if_eq() { - // first, try on references - let xs = ["Heart", "of", "Gold"]; - let mut it = xs.into_iter().peekable(); - // try before `peek()` - assert_eq!(it.next_if_eq(&"trillian"), None); - assert_eq!(it.next_if_eq(&"Heart"), Some("Heart")); - // try after peek() - assert_eq!(it.peek(), Some(&"of")); - assert_eq!(it.next_if_eq(&"of"), Some("of")); - assert_eq!(it.next_if_eq(&"zaphod"), None); - // make sure `next()` still behaves - assert_eq!(it.next(), Some("Gold")); - - // make sure comparison works for owned values - let xs = [String::from("Ludicrous"), "speed".into()]; - let mut it = xs.into_iter().peekable(); - // make sure basic functionality works - assert_eq!(it.next_if_eq("Ludicrous"), Some("Ludicrous".into())); - assert_eq!(it.next_if_eq("speed"), Some("speed".into())); - assert_eq!(it.next_if_eq(""), None); -} - -#[test] -fn test_iterator_peekable_mut() { - let mut it = [1, 2, 3].into_iter().peekable(); - if let Some(p) = it.peek_mut() { - if *p == 1 { - *p = 5; - } - } - assert_eq!(it.collect::>(), vec![5, 2, 3]); -} - -#[test] -fn test_iterator_peekable_remember_peek_none_1() { - // Check that the loop using .peek() terminates - let data = [1, 2, 3]; - let mut iter = CycleIter::new(&data).peekable(); - - let mut n = 0; - while let Some(_) = iter.next() { - let is_the_last = iter.peek().is_none(); - assert_eq!(is_the_last, n == data.len() - 1); - n += 1; - if n > data.len() { - break; - } - } - assert_eq!(n, data.len()); -} - -#[test] -fn test_iterator_peekable_remember_peek_none_2() { - let data = [0]; - let mut iter = CycleIter::new(&data).peekable(); - iter.next(); - assert_eq!(iter.peek(), None); - assert_eq!(iter.last(), None); -} - -#[test] -fn test_iterator_peekable_remember_peek_none_3() { - let data = [0]; - let mut iter = CycleIter::new(&data).peekable(); - iter.peek(); - assert_eq!(iter.nth(0), Some(&0)); - - let mut iter = CycleIter::new(&data).peekable(); - iter.next(); - assert_eq!(iter.peek(), None); - assert_eq!(iter.nth(0), None); -} - -#[test] -fn test_peek_try_folds() { - let f = &|acc, x| i32::checked_add(2 * acc, x); - - assert_eq!((1..20).peekable().try_fold(7, f), (1..20).try_fold(7, f)); - assert_eq!((1..20).peekable().try_rfold(7, f), (1..20).try_rfold(7, f)); - - let mut iter = (1..20).peekable(); - assert_eq!(iter.peek(), Some(&1)); - assert_eq!(iter.try_fold(7, f), (1..20).try_fold(7, f)); - - let mut iter = (1..20).peekable(); - assert_eq!(iter.peek(), Some(&1)); - assert_eq!(iter.try_rfold(7, f), (1..20).try_rfold(7, f)); - - let mut iter = [100, 20, 30, 40, 50, 60, 70].iter().cloned().peekable(); - assert_eq!(iter.peek(), Some(&100)); - assert_eq!(iter.try_fold(0, i8::checked_add), None); - assert_eq!(iter.peek(), Some(&40)); - - let mut iter = [100, 20, 30, 40, 50, 60, 70].iter().cloned().peekable(); - assert_eq!(iter.peek(), Some(&100)); - assert_eq!(iter.try_rfold(0, i8::checked_add), None); - assert_eq!(iter.peek(), Some(&100)); - assert_eq!(iter.next_back(), Some(50)); - - let mut iter = (2..5).peekable(); - assert_eq!(iter.peek(), Some(&2)); - assert_eq!(iter.try_for_each(Err), Err(2)); - assert_eq!(iter.peek(), Some(&3)); - assert_eq!(iter.try_for_each(Err), Err(3)); - assert_eq!(iter.peek(), Some(&4)); - assert_eq!(iter.try_for_each(Err), Err(4)); - assert_eq!(iter.peek(), None); - assert_eq!(iter.try_for_each(Err), Ok(())); - - let mut iter = (2..5).peekable(); - assert_eq!(iter.peek(), Some(&2)); - assert_eq!(iter.try_rfold((), |(), x| Err(x)), Err(4)); - assert_eq!(iter.peek(), Some(&2)); - assert_eq!(iter.try_rfold((), |(), x| Err(x)), Err(3)); - assert_eq!(iter.peek(), Some(&2)); - assert_eq!(iter.try_rfold((), |(), x| Err(x)), Err(2)); - assert_eq!(iter.peek(), None); - assert_eq!(iter.try_rfold((), |(), x| Err(x)), Ok(())); -} - -#[test] -fn test_peekable_non_fused() { - let mut iter = NonFused::new(empty::()).peekable(); - - assert_eq!(iter.peek(), None); - assert_eq!(iter.next_back(), None); -} diff --git a/library/core/tests/iter/adapters/scan.rs b/library/core/tests/iter/adapters/scan.rs deleted file mode 100644 index 1d28ca6b7fdc5..0000000000000 --- a/library/core/tests/iter/adapters/scan.rs +++ /dev/null @@ -1,20 +0,0 @@ -use core::iter::*; - -#[test] -fn test_iterator_scan() { - // test the type inference - fn add(old: &mut isize, new: &usize) -> Option { - *old += *new as isize; - Some(*old as f64) - } - let xs = [0, 1, 2, 3, 4]; - let ys = [0f64, 1.0, 3.0, 6.0, 10.0]; - - let it = xs.iter().scan(0, add); - let mut i = 0; - for x in it { - assert_eq!(x, ys[i]); - i += 1; - } - assert_eq!(i, ys.len()); -} diff --git a/library/core/tests/iter/adapters/skip.rs b/library/core/tests/iter/adapters/skip.rs deleted file mode 100644 index 8d5d06ad9fb3a..0000000000000 --- a/library/core/tests/iter/adapters/skip.rs +++ /dev/null @@ -1,238 +0,0 @@ -use core::iter::*; -use core::num::NonZero; - -use super::Unfuse; - -#[test] -fn test_iterator_skip() { - let xs = [0, 1, 2, 3, 5, 13, 15, 16, 17, 19, 20, 30]; - let ys = [13, 15, 16, 17, 19, 20, 30]; - let mut it = xs.iter().skip(5); - let mut i = 0; - while let Some(&x) = it.next() { - assert_eq!(x, ys[i]); - i += 1; - assert_eq!(it.len(), xs.len() - 5 - i); - } - assert_eq!(i, ys.len()); - assert_eq!(it.len(), 0); -} - -#[test] -fn test_iterator_skip_doubleended() { - let xs = [0, 1, 2, 3, 5, 13, 15, 16, 17, 19, 20, 30]; - let mut it = xs.iter().rev().skip(5); - assert_eq!(it.next(), Some(&15)); - assert_eq!(it.by_ref().rev().next(), Some(&0)); - assert_eq!(it.next(), Some(&13)); - assert_eq!(it.by_ref().rev().next(), Some(&1)); - assert_eq!(it.next(), Some(&5)); - assert_eq!(it.by_ref().rev().next(), Some(&2)); - assert_eq!(it.next(), Some(&3)); - assert_eq!(it.next(), None); - let mut it = xs.iter().rev().skip(5).rev(); - assert_eq!(it.next(), Some(&0)); - assert_eq!(it.rev().next(), Some(&15)); - let mut it_base = xs.iter(); - { - let mut it = it_base.by_ref().skip(5).rev(); - assert_eq!(it.next(), Some(&30)); - assert_eq!(it.next(), Some(&20)); - assert_eq!(it.next(), Some(&19)); - assert_eq!(it.next(), Some(&17)); - assert_eq!(it.next(), Some(&16)); - assert_eq!(it.next(), Some(&15)); - assert_eq!(it.next(), Some(&13)); - assert_eq!(it.next(), None); - } - // make sure the skipped parts have not been consumed - assert_eq!(it_base.next(), Some(&0)); - assert_eq!(it_base.next(), Some(&1)); - assert_eq!(it_base.next(), Some(&2)); - assert_eq!(it_base.next(), Some(&3)); - assert_eq!(it_base.next(), Some(&5)); - assert_eq!(it_base.next(), None); - let it = xs.iter().skip(5).rev(); - assert_eq!(it.last(), Some(&13)); -} - -#[test] -fn test_iterator_skip_nth() { - let xs = [0, 1, 2, 3, 5, 13, 15, 16, 17, 19, 20, 30]; - - let mut it = xs.iter().skip(0); - assert_eq!(it.nth(0), Some(&0)); - assert_eq!(it.nth(1), Some(&2)); - - let mut it = xs.iter().skip(5); - assert_eq!(it.nth(0), Some(&13)); - assert_eq!(it.nth(1), Some(&16)); - - let mut it = xs.iter().skip(12); - assert_eq!(it.nth(0), None); -} - -#[test] -fn test_skip_advance_by() { - assert_eq!((0..0).skip(10).advance_by(0), Ok(())); - assert_eq!((0..0).skip(10).advance_by(1), Err(NonZero::new(1).unwrap())); - assert_eq!( - (0u128..(usize::MAX as u128) + 1).skip(usize::MAX - 10).advance_by(usize::MAX - 5), - Err(NonZero::new(usize::MAX - 16).unwrap()) - ); - assert_eq!((0u128..u128::MAX).skip(usize::MAX - 10).advance_by(20), Ok(())); - - assert_eq!((0..2).skip(1).advance_back_by(10), Err(NonZero::new(9).unwrap())); - assert_eq!((0..0).skip(1).advance_back_by(0), Ok(())); -} - -#[test] -fn test_iterator_skip_count() { - let xs = [0, 1, 2, 3, 5, 13, 15, 16, 17, 19, 20, 30]; - - assert_eq!(xs.iter().skip(0).count(), 12); - assert_eq!(xs.iter().skip(1).count(), 11); - assert_eq!(xs.iter().skip(11).count(), 1); - assert_eq!(xs.iter().skip(12).count(), 0); - assert_eq!(xs.iter().skip(13).count(), 0); -} - -#[test] -fn test_iterator_skip_last() { - let xs = [0, 1, 2, 3, 5, 13, 15, 16, 17, 19, 20, 30]; - - assert_eq!(xs.iter().skip(0).last(), Some(&30)); - assert_eq!(xs.iter().skip(1).last(), Some(&30)); - assert_eq!(xs.iter().skip(11).last(), Some(&30)); - assert_eq!(xs.iter().skip(12).last(), None); - assert_eq!(xs.iter().skip(13).last(), None); - - let mut it = xs.iter().skip(5); - assert_eq!(it.next(), Some(&13)); - assert_eq!(it.last(), Some(&30)); -} - -#[test] -fn test_iterator_skip_fold() { - let xs = [0, 1, 2, 3, 5, 13, 15, 16, 17, 19, 20, 30]; - let ys = [13, 15, 16, 17, 19, 20, 30]; - - let it = xs.iter().skip(5); - let i = it.fold(0, |i, &x| { - assert_eq!(x, ys[i]); - i + 1 - }); - assert_eq!(i, ys.len()); - - let mut it = xs.iter().skip(5); - assert_eq!(it.next(), Some(&ys[0])); // process skips before folding - let i = it.fold(1, |i, &x| { - assert_eq!(x, ys[i]); - i + 1 - }); - assert_eq!(i, ys.len()); - - let it = xs.iter().skip(5); - let i = it.rfold(ys.len(), |i, &x| { - let i = i - 1; - assert_eq!(x, ys[i]); - i - }); - assert_eq!(i, 0); - - let mut it = xs.iter().skip(5); - assert_eq!(it.next(), Some(&ys[0])); // process skips before folding - let i = it.rfold(ys.len(), |i, &x| { - let i = i - 1; - assert_eq!(x, ys[i]); - i - }); - assert_eq!(i, 1); -} - -#[test] -fn test_skip_try_folds() { - let f = &|acc, x| i32::checked_add(2 * acc, x); - assert_eq!((1..20).skip(9).try_fold(7, f), (10..20).try_fold(7, f)); - assert_eq!((1..20).skip(9).try_rfold(7, f), (10..20).try_rfold(7, f)); - - let mut iter = (0..30).skip(10); - assert_eq!(iter.try_fold(0, i8::checked_add), None); - assert_eq!(iter.next(), Some(20)); - assert_eq!(iter.try_rfold(0, i8::checked_add), None); - assert_eq!(iter.next_back(), Some(24)); -} - -#[test] -fn test_skip_nth_back() { - let xs = [0, 1, 2, 3, 4, 5]; - let mut it = xs.iter().skip(2); - assert_eq!(it.nth_back(0), Some(&5)); - assert_eq!(it.nth_back(1), Some(&3)); - assert_eq!(it.nth_back(0), Some(&2)); - assert_eq!(it.nth_back(0), None); - - let ys = [2, 3, 4, 5]; - let mut ity = ys.iter(); - let mut it = xs.iter().skip(2); - assert_eq!(it.nth_back(1), ity.nth_back(1)); - assert_eq!(it.clone().nth(0), ity.clone().nth(0)); - assert_eq!(it.nth_back(0), ity.nth_back(0)); - assert_eq!(it.clone().nth(0), ity.clone().nth(0)); - assert_eq!(it.nth_back(0), ity.nth_back(0)); - assert_eq!(it.clone().nth(0), ity.clone().nth(0)); - assert_eq!(it.nth_back(0), ity.nth_back(0)); - assert_eq!(it.clone().nth(0), ity.clone().nth(0)); - - let mut it = xs.iter().skip(2); - assert_eq!(it.nth_back(4), None); - assert_eq!(it.nth_back(0), None); - - let mut it = xs.iter(); - it.by_ref().skip(2).nth_back(3); - assert_eq!(it.next_back(), Some(&1)); - - let mut it = xs.iter(); - it.by_ref().skip(2).nth_back(10); - assert_eq!(it.next_back(), Some(&1)); -} - -#[test] -fn test_skip_non_fused() { - let non_fused = Unfuse::new(0..10); - - // `Skip` would previously exhaust the iterator in this `next` call and then erroneously try to - // advance it further. `Unfuse` tests that this doesn't happen by panicking in that scenario. - let _ = non_fused.skip(20).next(); -} - -#[test] -fn test_skip_non_fused_nth_overflow() { - let non_fused = Unfuse::new(0..10); - - // Ensures that calling skip and `nth` where the sum would overflow does not fail for non-fused - // iterators. - let _ = non_fused.skip(20).nth(usize::MAX); -} - -#[test] -fn test_skip_overflow_wrapping() { - // Test to ensure even on overflowing on `skip+nth` the correct amount of elements are yielded. - struct WrappingIterator(usize); - - impl Iterator for WrappingIterator { - type Item = usize; - - fn next(&mut self) -> core::option::Option { - ::nth(self, 0) - } - - fn nth(&mut self, nth: usize) -> core::option::Option { - self.0 = self.0.wrapping_add(nth.wrapping_add(1)); - Some(self.0) - } - } - - let wrap = WrappingIterator(0); - assert_eq!(wrap.skip(20).nth(usize::MAX), Some(20)); -} diff --git a/library/core/tests/iter/adapters/skip_while.rs b/library/core/tests/iter/adapters/skip_while.rs deleted file mode 100644 index 929d4f6e64fd0..0000000000000 --- a/library/core/tests/iter/adapters/skip_while.rs +++ /dev/null @@ -1,50 +0,0 @@ -use core::iter::*; - -#[test] -fn test_iterator_skip_while() { - let xs = [0, 1, 2, 3, 5, 13, 15, 16, 17, 19]; - let ys = [15, 16, 17, 19]; - let it = xs.iter().skip_while(|&x| *x < 15); - let mut i = 0; - for x in it { - assert_eq!(*x, ys[i]); - i += 1; - } - assert_eq!(i, ys.len()); -} - -#[test] -fn test_iterator_skip_while_fold() { - let xs = [0, 1, 2, 3, 5, 13, 15, 16, 17, 19]; - let ys = [15, 16, 17, 19]; - let it = xs.iter().skip_while(|&x| *x < 15); - let i = it.fold(0, |i, &x| { - assert_eq!(x, ys[i]); - i + 1 - }); - assert_eq!(i, ys.len()); - - let mut it = xs.iter().skip_while(|&x| *x < 15); - assert_eq!(it.next(), Some(&ys[0])); // process skips before folding - let i = it.fold(1, |i, &x| { - assert_eq!(x, ys[i]); - i + 1 - }); - assert_eq!(i, ys.len()); -} - -#[test] -fn test_skip_while_try_fold() { - let f = &|acc, x| i32::checked_add(2 * acc, x); - fn p(&x: &i32) -> bool { - (x % 10) <= 5 - } - assert_eq!((1..20).skip_while(p).try_fold(7, f), (6..20).try_fold(7, f)); - let mut iter = (1..20).skip_while(p); - assert_eq!(iter.nth(5), Some(11)); - assert_eq!(iter.try_fold(7, f), (12..20).try_fold(7, f)); - - let mut iter = (0..50).skip_while(|&x| (x % 20) < 15); - assert_eq!(iter.try_fold(0, i8::checked_add), None); - assert_eq!(iter.next(), Some(23)); -} diff --git a/library/core/tests/iter/adapters/step_by.rs b/library/core/tests/iter/adapters/step_by.rs deleted file mode 100644 index 6f3300e7a8820..0000000000000 --- a/library/core/tests/iter/adapters/step_by.rs +++ /dev/null @@ -1,301 +0,0 @@ -use core::iter::*; - -#[test] -fn test_iterator_step_by() { - // Identity - let mut it = (0..).step_by(1).take(3); - assert_eq!(it.next(), Some(0)); - assert_eq!(it.next(), Some(1)); - assert_eq!(it.next(), Some(2)); - assert_eq!(it.next(), None); - - let mut it = (0..).step_by(3).take(4); - assert_eq!(it.next(), Some(0)); - assert_eq!(it.next(), Some(3)); - assert_eq!(it.next(), Some(6)); - assert_eq!(it.next(), Some(9)); - assert_eq!(it.next(), None); - - let mut it = (0..3).step_by(1); - assert_eq!(it.next_back(), Some(2)); - assert_eq!(it.next_back(), Some(1)); - assert_eq!(it.next_back(), Some(0)); - assert_eq!(it.next_back(), None); - - let mut it = (0..11).step_by(3); - assert_eq!(it.next_back(), Some(9)); - assert_eq!(it.next_back(), Some(6)); - assert_eq!(it.next_back(), Some(3)); - assert_eq!(it.next_back(), Some(0)); - assert_eq!(it.next_back(), None); -} - -#[test] -fn test_iterator_step_by_nth() { - let mut it = (0..16).step_by(5); - assert_eq!(it.nth(0), Some(0)); - assert_eq!(it.nth(0), Some(5)); - assert_eq!(it.nth(0), Some(10)); - assert_eq!(it.nth(0), Some(15)); - assert_eq!(it.nth(0), None); - - let it = (0..18).step_by(5); - assert_eq!(it.clone().nth(0), Some(0)); - assert_eq!(it.clone().nth(1), Some(5)); - assert_eq!(it.clone().nth(2), Some(10)); - assert_eq!(it.clone().nth(3), Some(15)); - assert_eq!(it.clone().nth(4), None); - assert_eq!(it.clone().nth(42), None); -} - -#[test] -#[allow(non_local_definitions)] -fn test_iterator_step_by_nth_overflow() { - #[cfg(target_pointer_width = "16")] - type Bigger = u32; - #[cfg(target_pointer_width = "32")] - type Bigger = u64; - #[cfg(target_pointer_width = "64")] - type Bigger = u128; - - #[derive(Clone)] - struct Test(Bigger); - impl Iterator for &mut Test { - type Item = i32; - fn next(&mut self) -> Option { - Some(21) - } - fn nth(&mut self, n: usize) -> Option { - self.0 += n as Bigger + 1; - Some(42) - } - } - - let mut it = Test(0); - let root = usize::MAX >> (usize::BITS / 2); - let n = root + 20; - (&mut it).step_by(n).nth(n); - assert_eq!(it.0, n as Bigger * n as Bigger); - - // large step - let mut it = Test(0); - (&mut it).step_by(usize::MAX).nth(5); - assert_eq!(it.0, (usize::MAX as Bigger) * 5); - - // n + 1 overflows - let mut it = Test(0); - (&mut it).step_by(2).nth(usize::MAX); - assert_eq!(it.0, (usize::MAX as Bigger) * 2); - - // n + 1 overflows - let mut it = Test(0); - (&mut it).step_by(1).nth(usize::MAX); - assert_eq!(it.0, (usize::MAX as Bigger) * 1); -} - -#[test] -fn test_iterator_step_by_nth_try_fold() { - let mut it = (0..).step_by(10); - assert_eq!(it.try_fold(0, i8::checked_add), None); - assert_eq!(it.next(), Some(60)); - assert_eq!(it.try_fold(0, i8::checked_add), None); - assert_eq!(it.next(), Some(90)); - - let mut it = (100..).step_by(10); - assert_eq!(it.try_fold(50, i8::checked_add), None); - assert_eq!(it.next(), Some(110)); - - let mut it = (100..=100).step_by(10); - assert_eq!(it.next(), Some(100)); - assert_eq!(it.try_fold(0, i8::checked_add), Some(0)); -} - -#[test] -fn test_iterator_step_by_nth_back() { - let mut it = (0..16).step_by(5); - assert_eq!(it.nth_back(0), Some(15)); - assert_eq!(it.nth_back(0), Some(10)); - assert_eq!(it.nth_back(0), Some(5)); - assert_eq!(it.nth_back(0), Some(0)); - assert_eq!(it.nth_back(0), None); - - let mut it = (0..16).step_by(5); - assert_eq!(it.next(), Some(0)); // to set `first_take` to `false` - assert_eq!(it.nth_back(0), Some(15)); - assert_eq!(it.nth_back(0), Some(10)); - assert_eq!(it.nth_back(0), Some(5)); - assert_eq!(it.nth_back(0), None); - - let it = || (0..18).step_by(5); - assert_eq!(it().nth_back(0), Some(15)); - assert_eq!(it().nth_back(1), Some(10)); - assert_eq!(it().nth_back(2), Some(5)); - assert_eq!(it().nth_back(3), Some(0)); - assert_eq!(it().nth_back(4), None); - assert_eq!(it().nth_back(42), None); -} - -#[test] -fn test_iterator_step_by_nth_try_rfold() { - let mut it = (0..100).step_by(10); - assert_eq!(it.try_rfold(0, i8::checked_add), None); - assert_eq!(it.next_back(), Some(70)); - assert_eq!(it.next(), Some(0)); - assert_eq!(it.try_rfold(0, i8::checked_add), None); - assert_eq!(it.next_back(), Some(30)); - - let mut it = (0..100).step_by(10); - assert_eq!(it.try_rfold(50, i8::checked_add), None); - assert_eq!(it.next_back(), Some(80)); - - let mut it = (100..=100).step_by(10); - assert_eq!(it.next_back(), Some(100)); - assert_eq!(it.try_fold(0, i8::checked_add), Some(0)); -} - -#[test] -#[should_panic] -fn test_iterator_step_by_zero() { - let mut it = (0..).step_by(0); - it.next(); -} - -#[test] -fn test_iterator_step_by_size_hint() { - struct StubSizeHint(usize, Option); - impl Iterator for StubSizeHint { - type Item = (); - fn next(&mut self) -> Option<()> { - self.0 -= 1; - if let Some(ref mut upper) = self.1 { - *upper -= 1; - } - Some(()) - } - fn size_hint(&self) -> (usize, Option) { - (self.0, self.1) - } - } - - // The two checks in each case are needed because the logic - // is different before the first call to `next()`. - - let mut it = StubSizeHint(10, Some(10)).step_by(1); - assert_eq!(it.size_hint(), (10, Some(10))); - it.next(); - assert_eq!(it.size_hint(), (9, Some(9))); - - // exact multiple - let mut it = StubSizeHint(10, Some(10)).step_by(3); - assert_eq!(it.size_hint(), (4, Some(4))); - it.next(); - assert_eq!(it.size_hint(), (3, Some(3))); - - // larger base range, but not enough to get another element - let mut it = StubSizeHint(12, Some(12)).step_by(3); - assert_eq!(it.size_hint(), (4, Some(4))); - it.next(); - assert_eq!(it.size_hint(), (3, Some(3))); - - // smaller base range, so fewer resulting elements - let mut it = StubSizeHint(9, Some(9)).step_by(3); - assert_eq!(it.size_hint(), (3, Some(3))); - it.next(); - assert_eq!(it.size_hint(), (2, Some(2))); - - // infinite upper bound - let mut it = StubSizeHint(usize::MAX, None).step_by(1); - assert_eq!(it.size_hint(), (usize::MAX, None)); - it.next(); - assert_eq!(it.size_hint(), (usize::MAX - 1, None)); - - // still infinite with larger step - let mut it = StubSizeHint(7, None).step_by(3); - assert_eq!(it.size_hint(), (3, None)); - it.next(); - assert_eq!(it.size_hint(), (2, None)); - - // propagates ExactSizeIterator - let a = [1, 2, 3, 4, 5]; - let it = a.iter().step_by(2); - assert_eq!(it.len(), 3); - - // Cannot be TrustedLen as a step greater than one makes an iterator - // with (usize::MAX, None) no longer meet the safety requirements. - // Exception: The inner iterator is known to have a len() <= usize::MAX - trait TrustedLenCheck { - fn test(self) -> bool; - } - impl TrustedLenCheck for T { - default fn test(self) -> bool { - false - } - } - impl TrustedLenCheck for T { - fn test(self) -> bool { - true - } - } - assert!(TrustedLenCheck::test(a.iter())); - assert!(TrustedLenCheck::test(a.iter().step_by(1))); - assert!(TrustedLenCheck::test(a.iter().chain(a.iter()))); - assert!(!TrustedLenCheck::test(a.iter().chain(a.iter()).step_by(1))); -} - -#[test] -fn test_step_by_skip() { - assert_eq!((0..640).step_by(128).skip(1).collect::>(), [128, 256, 384, 512]); - assert_eq!((0..=50).step_by(10).nth(3), Some(30)); - assert_eq!((200..=255u8).step_by(10).nth(3), Some(230)); -} - -struct DeOpt(I); - -impl Iterator for DeOpt { - type Item = I::Item; - - fn next(&mut self) -> core::option::Option { - self.0.next() - } -} - -impl DoubleEndedIterator for DeOpt { - fn next_back(&mut self) -> core::option::Option { - self.0.next_back() - } -} - -#[test] -fn test_step_by_fold_range_specialization() { - macro_rules! t { - ($range:expr, $var: ident, $body:tt) => {{ - // run the same tests for the non-optimized version - let mut $var = DeOpt($range); - $body - } - { - let mut $var = $range; - $body - }}; - } - - t!((1usize..5).step_by(1), r, { - assert_eq!(r.next_back(), Some(4)); - assert_eq!(r.sum::(), 6); - }); - - t!((0usize..4).step_by(2), r, { - assert_eq!(r.next(), Some(0)); - assert_eq!(r.sum::(), 2); - }); - - t!((0usize..5).step_by(2), r, { - assert_eq!(r.next(), Some(0)); - assert_eq!(r.sum::(), 6); - }); - - t!((usize::MAX - 6..usize::MAX).step_by(5), r, { - assert_eq!(r.next(), Some(usize::MAX - 6)); - assert_eq!(r.sum::(), usize::MAX - 1); - }); -} diff --git a/library/core/tests/iter/adapters/take.rs b/library/core/tests/iter/adapters/take.rs deleted file mode 100644 index 39afa2cbfcaf2..0000000000000 --- a/library/core/tests/iter/adapters/take.rs +++ /dev/null @@ -1,172 +0,0 @@ -use core::iter::*; -use core::num::NonZero; - -#[test] -fn test_iterator_take() { - let xs = [0, 1, 2, 3, 5, 13, 15, 16, 17, 19]; - let ys = [0, 1, 2, 3, 5]; - - let mut it = xs.iter().take(ys.len()); - let mut i = 0; - assert_eq!(it.len(), ys.len()); - while let Some(&x) = it.next() { - assert_eq!(x, ys[i]); - i += 1; - assert_eq!(it.len(), ys.len() - i); - } - assert_eq!(i, ys.len()); - assert_eq!(it.len(), 0); - - let mut it = xs.iter().take(ys.len()); - let mut i = 0; - assert_eq!(it.len(), ys.len()); - while let Some(&x) = it.next_back() { - i += 1; - assert_eq!(x, ys[ys.len() - i]); - assert_eq!(it.len(), ys.len() - i); - } - assert_eq!(i, ys.len()); - assert_eq!(it.len(), 0); -} - -#[test] -fn test_iterator_take_nth() { - let xs = [0, 1, 2, 4, 5]; - let mut it = xs.iter(); - { - let mut take = it.by_ref().take(3); - let mut i = 0; - while let Some(&x) = take.nth(0) { - assert_eq!(x, i); - i += 1; - } - } - assert_eq!(it.nth(1), Some(&5)); - assert_eq!(it.nth(0), None); - - let xs = [0, 1, 2, 3, 4]; - let mut it = xs.iter().take(7); - let mut i = 1; - while let Some(&x) = it.nth(1) { - assert_eq!(x, i); - i += 2; - } -} - -#[test] -fn test_iterator_take_nth_back() { - let xs = [0, 1, 2, 4, 5]; - let mut it = xs.iter(); - { - let mut take = it.by_ref().take(3); - let mut i = 0; - while let Some(&x) = take.nth_back(0) { - i += 1; - assert_eq!(x, 3 - i); - } - } - assert_eq!(it.nth_back(0), None); - - let xs = [0, 1, 2, 3, 4]; - let mut it = xs.iter().take(7); - assert_eq!(it.nth_back(1), Some(&3)); - assert_eq!(it.nth_back(1), Some(&1)); - assert_eq!(it.nth_back(1), None); -} - -#[test] -fn test_take_advance_by() { - let mut take = (0..10).take(3); - assert_eq!(take.advance_by(2), Ok(())); - assert_eq!(take.next(), Some(2)); - assert_eq!(take.advance_by(1), Err(NonZero::new(1).unwrap())); - - assert_eq!((0..0).take(10).advance_by(0), Ok(())); - assert_eq!((0..0).take(10).advance_by(1), Err(NonZero::new(1).unwrap())); - assert_eq!((0..10).take(4).advance_by(5), Err(NonZero::new(1).unwrap())); - - let mut take = (0..10).take(3); - assert_eq!(take.advance_back_by(2), Ok(())); - assert_eq!(take.next(), Some(0)); - assert_eq!(take.advance_back_by(1), Err(NonZero::new(1).unwrap())); - - assert_eq!((0..2).take(1).advance_back_by(10), Err(NonZero::new(9).unwrap())); - assert_eq!((0..0).take(1).advance_back_by(1), Err(NonZero::new(1).unwrap())); - assert_eq!((0..0).take(1).advance_back_by(0), Ok(())); - assert_eq!( - (0..usize::MAX).take(100).advance_back_by(usize::MAX), - Err(NonZero::new(usize::MAX - 100).unwrap()) - ); -} - -#[test] -fn test_iterator_take_short() { - let xs = [0, 1, 2, 3]; - - let mut it = xs.iter().take(5); - let mut i = 0; - assert_eq!(it.len(), xs.len()); - while let Some(&x) = it.next() { - assert_eq!(x, xs[i]); - i += 1; - assert_eq!(it.len(), xs.len() - i); - } - assert_eq!(i, xs.len()); - assert_eq!(it.len(), 0); - - let mut it = xs.iter().take(5); - let mut i = 0; - assert_eq!(it.len(), xs.len()); - while let Some(&x) = it.next_back() { - i += 1; - assert_eq!(x, xs[xs.len() - i]); - assert_eq!(it.len(), xs.len() - i); - } - assert_eq!(i, xs.len()); - assert_eq!(it.len(), 0); -} - -#[test] -fn test_take_try_folds() { - let f = &|acc, x| i32::checked_add(2 * acc, x); - assert_eq!((10..30).take(10).try_fold(7, f), (10..20).try_fold(7, f)); - assert_eq!((10..30).take(10).try_rfold(7, f), (10..20).try_rfold(7, f)); - - let mut iter = (10..30).take(20); - assert_eq!(iter.try_fold(0, i8::checked_add), None); - assert_eq!(iter.next(), Some(20)); - assert_eq!(iter.try_rfold(0, i8::checked_add), None); - assert_eq!(iter.next_back(), Some(24)); - - let mut iter = (2..20).take(3); - assert_eq!(iter.try_for_each(Err), Err(2)); - assert_eq!(iter.try_for_each(Err), Err(3)); - assert_eq!(iter.try_for_each(Err), Err(4)); - assert_eq!(iter.try_for_each(Err), Ok(())); - - let mut iter = (2..20).take(3).rev(); - assert_eq!(iter.try_for_each(Err), Err(4)); - assert_eq!(iter.try_for_each(Err), Err(3)); - assert_eq!(iter.try_for_each(Err), Err(2)); - assert_eq!(iter.try_for_each(Err), Ok(())); -} - -#[test] -fn test_byref_take_consumed_items() { - let mut inner = 10..90; - - let mut count = 0; - inner.by_ref().take(0).for_each(|_| count += 1); - assert_eq!(count, 0); - assert_eq!(inner, 10..90); - - let mut count = 0; - inner.by_ref().take(10).for_each(|_| count += 1); - assert_eq!(count, 10); - assert_eq!(inner, 20..90); - - let mut count = 0; - inner.by_ref().take(100).for_each(|_| count += 1); - assert_eq!(count, 70); - assert_eq!(inner, 90..90); -} diff --git a/library/core/tests/iter/adapters/take_while.rs b/library/core/tests/iter/adapters/take_while.rs deleted file mode 100644 index 6f1ebab29b31c..0000000000000 --- a/library/core/tests/iter/adapters/take_while.rs +++ /dev/null @@ -1,29 +0,0 @@ -use core::iter::*; - -#[test] -fn test_iterator_take_while() { - let xs = [0, 1, 2, 3, 5, 13, 15, 16, 17, 19]; - let ys = [0, 1, 2, 3, 5, 13]; - let it = xs.iter().take_while(|&x| *x < 15); - let mut i = 0; - for x in it { - assert_eq!(*x, ys[i]); - i += 1; - } - assert_eq!(i, ys.len()); -} - -#[test] -fn test_take_while_folds() { - let f = &|acc, x| i32::checked_add(2 * acc, x); - assert_eq!((1..20).take_while(|&x| x != 10).try_fold(7, f), (1..10).try_fold(7, f)); - let mut iter = (1..20).take_while(|&x| x != 10); - assert_eq!(iter.try_fold(0, |x, y| Some(x + y)), Some((1..10).sum())); - assert_eq!(iter.next(), None, "flag should be set"); - let iter = (1..20).take_while(|&x| x != 10); - assert_eq!(iter.fold(0, |x, y| x + y), (1..10).sum()); - - let mut iter = (10..50).take_while(|&x| x != 40); - assert_eq!(iter.try_fold(0, i8::checked_add), None); - assert_eq!(iter.next(), Some(20)); -} diff --git a/library/core/tests/iter/adapters/zip.rs b/library/core/tests/iter/adapters/zip.rs deleted file mode 100644 index ba54de5822bf7..0000000000000 --- a/library/core/tests/iter/adapters/zip.rs +++ /dev/null @@ -1,319 +0,0 @@ -use super::*; -use core::iter::*; - -#[test] -fn test_zip_nth() { - let xs = [0, 1, 2, 4, 5]; - let ys = [10, 11, 12]; - - let mut it = xs.iter().zip(&ys); - assert_eq!(it.nth(0), Some((&0, &10))); - assert_eq!(it.nth(1), Some((&2, &12))); - assert_eq!(it.nth(0), None); - - let mut it = xs.iter().zip(&ys); - assert_eq!(it.nth(3), None); - - let mut it = ys.iter().zip(&xs); - assert_eq!(it.nth(3), None); -} - -#[test] -fn test_zip_nth_side_effects() { - let mut a = Vec::new(); - let mut b = Vec::new(); - let value = [1, 2, 3, 4, 5, 6] - .iter() - .cloned() - .map(|n| { - a.push(n); - n * 10 - }) - .zip([2, 3, 4, 5, 6, 7, 8].iter().cloned().map(|n| { - b.push(n * 100); - n * 1000 - })) - .skip(1) - .nth(3); - assert_eq!(value, Some((50, 6000))); - assert_eq!(a, vec![1, 2, 3, 4, 5]); - assert_eq!(b, vec![200, 300, 400, 500, 600]); -} - -#[test] -fn test_zip_next_back_side_effects() { - let mut a = Vec::new(); - let mut b = Vec::new(); - let mut iter = [1, 2, 3, 4, 5, 6] - .iter() - .cloned() - .map(|n| { - a.push(n); - n * 10 - }) - .zip([2, 3, 4, 5, 6, 7, 8].iter().cloned().map(|n| { - b.push(n * 100); - n * 1000 - })); - - // The second iterator is one item longer, so `next_back` is called on it - // one more time. - assert_eq!(iter.next_back(), Some((60, 7000))); - assert_eq!(iter.next_back(), Some((50, 6000))); - assert_eq!(iter.next_back(), Some((40, 5000))); - assert_eq!(iter.next_back(), Some((30, 4000))); - assert_eq!(a, vec![6, 5, 4, 3]); - assert_eq!(b, vec![800, 700, 600, 500, 400]); -} - -#[test] -fn test_zip_nth_back_side_effects() { - let mut a = Vec::new(); - let mut b = Vec::new(); - let value = [1, 2, 3, 4, 5, 6] - .iter() - .cloned() - .map(|n| { - a.push(n); - n * 10 - }) - .zip([2, 3, 4, 5, 6, 7, 8].iter().cloned().map(|n| { - b.push(n * 100); - n * 1000 - })) - .nth_back(3); - assert_eq!(value, Some((30, 4000))); - assert_eq!(a, vec![6, 5, 4, 3]); - assert_eq!(b, vec![800, 700, 600, 500, 400]); -} - -#[test] -fn test_zip_next_back_side_effects_exhausted() { - let mut a = Vec::new(); - let mut b = Vec::new(); - let mut iter = [1, 2, 3, 4, 5, 6] - .iter() - .cloned() - .map(|n| { - a.push(n); - n * 10 - }) - .zip([2, 3, 4].iter().cloned().map(|n| { - b.push(n * 100); - n * 1000 - })); - - iter.next(); - iter.next(); - iter.next(); - iter.next(); - assert_eq!(iter.next_back(), None); - assert_eq!(a, vec![1, 2, 3, 4, 6, 5]); - assert_eq!(b, vec![200, 300, 400]); -} - -#[test] -fn test_zip_cloned_sideffectful() { - let xs = [CountClone::new(), CountClone::new(), CountClone::new(), CountClone::new()]; - let ys = [CountClone::new(), CountClone::new()]; - - for _ in xs.iter().cloned().zip(ys.iter().cloned()) {} - - assert_eq!(&xs, &[1, 1, 1, 0][..]); - assert_eq!(&ys, &[1, 1][..]); - - let xs = [CountClone::new(), CountClone::new()]; - let ys = [CountClone::new(), CountClone::new(), CountClone::new(), CountClone::new()]; - - for _ in xs.iter().cloned().zip(ys.iter().cloned()) {} - - assert_eq!(&xs, &[1, 1][..]); - assert_eq!(&ys, &[1, 1, 0, 0][..]); -} - -#[test] -fn test_zip_map_sideffectful() { - let mut xs = [0; 6]; - let mut ys = [0; 4]; - - for _ in xs.iter_mut().map(|x| *x += 1).zip(ys.iter_mut().map(|y| *y += 1)) {} - - assert_eq!(&xs, &[1, 1, 1, 1, 1, 0]); - assert_eq!(&ys, &[1, 1, 1, 1]); - - let mut xs = [0; 4]; - let mut ys = [0; 6]; - - for _ in xs.iter_mut().map(|x| *x += 1).zip(ys.iter_mut().map(|y| *y += 1)) {} - - assert_eq!(&xs, &[1, 1, 1, 1]); - assert_eq!(&ys, &[1, 1, 1, 1, 0, 0]); -} - -#[test] -fn test_zip_map_rev_sideffectful() { - let mut xs = [0; 6]; - let mut ys = [0; 4]; - - { - let mut it = xs.iter_mut().map(|x| *x += 1).zip(ys.iter_mut().map(|y| *y += 1)); - it.next_back(); - } - assert_eq!(&xs, &[0, 0, 0, 1, 1, 1]); - assert_eq!(&ys, &[0, 0, 0, 1]); - - let mut xs = [0; 6]; - let mut ys = [0; 4]; - - { - let mut it = xs.iter_mut().map(|x| *x += 1).zip(ys.iter_mut().map(|y| *y += 1)); - (&mut it).take(5).count(); - it.next_back(); - } - assert_eq!(&xs, &[1, 1, 1, 1, 1, 1]); - assert_eq!(&ys, &[1, 1, 1, 1]); -} - -#[test] -fn test_zip_nested_sideffectful() { - let mut xs = [0; 6]; - let ys = [0; 4]; - - { - // test that it has the side effect nested inside enumerate - let it = xs.iter_mut().map(|x| *x = 1).enumerate().zip(&ys); - it.count(); - } - let length_aware = &xs == &[1, 1, 1, 1, 0, 0]; - let probe_first = &xs == &[1, 1, 1, 1, 1, 0]; - - // either implementation is valid according to zip documentation - assert!(length_aware || probe_first); -} - -#[test] -fn test_zip_nth_back_side_effects_exhausted() { - let mut a = Vec::new(); - let mut b = Vec::new(); - let mut iter = [1, 2, 3, 4, 5, 6] - .iter() - .cloned() - .map(|n| { - a.push(n); - n * 10 - }) - .zip([2, 3, 4].iter().cloned().map(|n| { - b.push(n * 100); - n * 1000 - })); - - iter.next(); - iter.next(); - iter.next(); - iter.next(); - assert_eq!(iter.nth_back(0), None); - assert_eq!(a, vec![1, 2, 3, 4, 6, 5]); - assert_eq!(b, vec![200, 300, 400]); -} - -#[test] -fn test_zip_trusted_random_access_composition() { - let a = [0, 1, 2, 3, 4]; - let b = a; - let c = a; - - let a = a.iter().copied(); - let b = b.iter().copied(); - let mut c = c.iter().copied(); - c.next(); - - let mut z1 = a.zip(b); - assert_eq!(z1.next().unwrap(), (0, 0)); - - let mut z2 = z1.zip(c); - fn assert_trusted_random_access(_a: &T) {} - assert_trusted_random_access(&z2); - assert_eq!(z2.next().unwrap(), ((1, 1), 1)); -} - -#[test] -#[cfg(panic = "unwind")] -fn test_zip_trusted_random_access_next_back_drop() { - use std::panic::catch_unwind; - use std::panic::AssertUnwindSafe; - - let mut counter = 0; - - let it = [42].iter().map(|e| { - let c = counter; - counter += 1; - if c == 0 { - panic!("bomb"); - } - - e - }); - let it2 = [(); 0].iter(); - let mut zip = it.zip(it2); - catch_unwind(AssertUnwindSafe(|| { - zip.next_back(); - })) - .unwrap_err(); - assert!(zip.next().is_none()); - assert_eq!(counter, 1); -} - -#[test] -fn test_double_ended_zip() { - let xs = [1, 2, 3, 4, 5, 6]; - let ys = [1, 2, 3, 7]; - let mut it = xs.iter().cloned().zip(ys); - assert_eq!(it.next(), Some((1, 1))); - assert_eq!(it.next(), Some((2, 2))); - assert_eq!(it.next_back(), Some((4, 7))); - assert_eq!(it.next_back(), Some((3, 3))); - assert_eq!(it.next(), None); -} - -#[test] -fn test_issue_82282() { - fn overflowed_zip(arr: &[i32]) -> impl Iterator { - static UNIT_EMPTY_ARR: [(); 0] = []; - - let mapped = arr.into_iter().map(|i| *i); - let mut zipped = mapped.zip(UNIT_EMPTY_ARR.iter()); - zipped.next(); - zipped - } - - let arr = [1, 2, 3]; - let zip = overflowed_zip(&arr).zip(overflowed_zip(&arr)); - - assert_eq!(zip.size_hint(), (0, Some(0))); - for _ in zip { - panic!(); - } -} - -#[test] -fn test_issue_82291() { - use std::cell::Cell; - - let mut v1 = [()]; - let v2 = [()]; - - let called = Cell::new(0); - - let mut zip = v1 - .iter_mut() - .map(|r| { - called.set(called.get() + 1); - r - }) - .zip(&v2); - - zip.next_back(); - assert_eq!(called.get(), 1); - zip.next(); - assert_eq!(called.get(), 1); -} diff --git a/library/core/tests/iter/mod.rs b/library/core/tests/iter/mod.rs deleted file mode 100644 index 5b2769d04698d..0000000000000 --- a/library/core/tests/iter/mod.rs +++ /dev/null @@ -1,101 +0,0 @@ -//! Note -//! ---- -//! You're probably viewing this file because you're adding a test (or you might -//! just be browsing, in that case, hey there!). -//! -//! The iter test suite is split into two big modules, and some miscellaneous -//! smaller modules. The two big modules are `adapters` and `traits`. -//! -//! `adapters` are for methods on `Iterator` that adapt the data inside the -//! iterator, whether it be by emitting another iterator or returning an item -//! from inside the iterator after executing a closure on each item. -//! -//! `traits` are for trait's that extend an `Iterator` (and the `Iterator` -//! trait itself, mostly containing miscellaneous methods). For the most part, -//! if a test in `traits` uses a specific adapter, then it should be moved to -//! that adapter's test file in `adapters`. - -mod adapters; -mod range; -mod sources; -mod traits; - -use core::cell::Cell; -use core::iter::*; - -pub fn is_trusted_len(_: I) {} - -#[test] -fn test_multi_iter() { - let xs = [1, 2, 3, 4]; - let ys = [4, 3, 2, 1]; - assert!(xs.iter().eq(ys.iter().rev())); - assert!(xs.iter().lt(xs.iter().skip(2))); -} - -#[test] -fn test_counter_from_iter() { - let it = (0..).step_by(5).take(10); - let xs: Vec = FromIterator::from_iter(it); - assert_eq!(xs, [0, 5, 10, 15, 20, 25, 30, 35, 40, 45]); -} - -#[test] -fn test_functor_laws() { - // identity: - fn identity(x: T) -> T { - x - } - assert_eq!((0..10).map(identity).sum::(), (0..10).sum()); - - // composition: - fn f(x: usize) -> usize { - x + 3 - } - fn g(x: usize) -> usize { - x * 2 - } - fn h(x: usize) -> usize { - g(f(x)) - } - assert_eq!((0..10).map(f).map(g).sum::(), (0..10).map(h).sum()); -} - -#[test] -fn test_monad_laws_left_identity() { - fn f(x: usize) -> impl Iterator { - (0..10).map(move |y| x * y) - } - assert_eq!(once(42).flat_map(f.clone()).sum::(), f(42).sum()); -} - -#[test] -fn test_monad_laws_right_identity() { - assert_eq!((0..10).flat_map(|x| once(x)).sum::(), (0..10).sum()); -} - -#[test] -fn test_monad_laws_associativity() { - fn f(x: usize) -> impl Iterator { - 0..x - } - fn g(x: usize) -> impl Iterator { - (0..x).rev() - } - assert_eq!( - (0..10).flat_map(f).flat_map(g).sum::(), - (0..10).flat_map(|x| f(x).flat_map(g)).sum::() - ); -} - -#[test] -pub fn extend_for_unit() { - let mut x = 0; - { - let iter = (0..5).map(|_| { - x += 1; - }); - ().extend(iter); - } - assert_eq!(x, 5); -} diff --git a/library/core/tests/iter/range.rs b/library/core/tests/iter/range.rs deleted file mode 100644 index e31db0732e094..0000000000000 --- a/library/core/tests/iter/range.rs +++ /dev/null @@ -1,503 +0,0 @@ -use super::*; -use core::ascii::Char as AsciiChar; -use core::num::NonZero; - -#[test] -fn test_range() { - assert_eq!((0..5).collect::>(), [0, 1, 2, 3, 4]); - assert_eq!((-10..-1).collect::>(), [-10, -9, -8, -7, -6, -5, -4, -3, -2]); - assert_eq!((0..5).rev().collect::>(), [4, 3, 2, 1, 0]); - assert_eq!((200..-5).count(), 0); - assert_eq!((200..-5).rev().count(), 0); - assert_eq!((200..200).count(), 0); - assert_eq!((200..200).rev().count(), 0); - - assert_eq!((0..100).size_hint(), (100, Some(100))); - // this test is only meaningful when sizeof usize < sizeof u64 - assert_eq!((usize::MAX - 1..usize::MAX).size_hint(), (1, Some(1))); - assert_eq!((-10..-1).size_hint(), (9, Some(9))); - assert_eq!((-1..-10).size_hint(), (0, Some(0))); - - assert_eq!((-70..58).size_hint(), (128, Some(128))); - assert_eq!((-128..127).size_hint(), (255, Some(255))); - assert_eq!( - (-2..isize::MAX).size_hint(), - (isize::MAX as usize + 2, Some(isize::MAX as usize + 2)) - ); -} - -#[test] -fn test_char_range() { - // Miri is too slow - let from = if cfg!(miri) { char::from_u32(0xD800 - 10).unwrap() } else { '\0' }; - let to = if cfg!(miri) { char::from_u32(0xDFFF + 10).unwrap() } else { char::MAX }; - assert!((from..=to).eq((from as u32..=to as u32).filter_map(char::from_u32))); - assert!((from..=to).rev().eq((from as u32..=to as u32).filter_map(char::from_u32).rev())); - - assert_eq!(('\u{D7FF}'..='\u{E000}').count(), 2); - assert_eq!(('\u{D7FF}'..='\u{E000}').size_hint(), (2, Some(2))); - assert_eq!(('\u{D7FF}'..'\u{E000}').count(), 1); - assert_eq!(('\u{D7FF}'..'\u{E000}').size_hint(), (1, Some(1))); -} - -#[test] -fn test_ascii_char_range() { - let from = AsciiChar::Null; - let to = AsciiChar::Delete; - assert!((from..=to).eq((from as u8..=to as u8).filter_map(AsciiChar::from_u8))); - assert!((from..=to).rev().eq((from as u8..=to as u8).filter_map(AsciiChar::from_u8).rev())); - - assert_eq!((AsciiChar::CapitalA..=AsciiChar::CapitalZ).count(), 26); - assert_eq!((AsciiChar::CapitalA..=AsciiChar::CapitalZ).size_hint(), (26, Some(26))); - assert_eq!((AsciiChar::SmallA..=AsciiChar::SmallZ).count(), 26); - assert_eq!((AsciiChar::SmallA..=AsciiChar::SmallZ).size_hint(), (26, Some(26))); - assert_eq!((AsciiChar::Digit0..=AsciiChar::Digit9).count(), 10); - assert_eq!((AsciiChar::Digit0..=AsciiChar::Digit9).size_hint(), (10, Some(10))); -} - -#[test] -fn test_range_exhaustion() { - let mut r = 10..10; - assert!(r.is_empty()); - assert_eq!(r.next(), None); - assert_eq!(r.next_back(), None); - assert_eq!(r, 10..10); - - let mut r = 10..12; - assert_eq!(r.next(), Some(10)); - assert_eq!(r.next(), Some(11)); - assert!(r.is_empty()); - assert_eq!(r, 12..12); - assert_eq!(r.next(), None); - - let mut r = 10..12; - assert_eq!(r.next_back(), Some(11)); - assert_eq!(r.next_back(), Some(10)); - assert!(r.is_empty()); - assert_eq!(r, 10..10); - assert_eq!(r.next_back(), None); - - let mut r = 100..10; - assert!(r.is_empty()); - assert_eq!(r.next(), None); - assert_eq!(r.next_back(), None); - assert_eq!(r, 100..10); -} - -#[test] -fn test_range_inclusive_exhaustion() { - let mut r = 10..=10; - assert_eq!(r.next(), Some(10)); - assert!(r.is_empty()); - assert_eq!(r.next(), None); - assert_eq!(r.next(), None); - - assert_eq!(*r.start(), 10); - assert_eq!(*r.end(), 10); - assert_ne!(r, 10..=10); - - let mut r = 10..=10; - assert_eq!(r.next_back(), Some(10)); - assert!(r.is_empty()); - assert_eq!(r.next_back(), None); - - assert_eq!(*r.start(), 10); - assert_eq!(*r.end(), 10); - assert_ne!(r, 10..=10); - - let mut r = 10..=12; - assert_eq!(r.next(), Some(10)); - assert_eq!(r.next(), Some(11)); - assert_eq!(r.next(), Some(12)); - assert!(r.is_empty()); - assert_eq!(r.next(), None); - - let mut r = 10..=12; - assert_eq!(r.next_back(), Some(12)); - assert_eq!(r.next_back(), Some(11)); - assert_eq!(r.next_back(), Some(10)); - assert!(r.is_empty()); - assert_eq!(r.next_back(), None); - - let mut r = 10..=12; - assert_eq!(r.nth(2), Some(12)); - assert!(r.is_empty()); - assert_eq!(r.next(), None); - - let mut r = 10..=12; - assert_eq!(r.nth(5), None); - assert!(r.is_empty()); - assert_eq!(r.next(), None); - - let mut r = 100..=10; - assert_eq!(r.next(), None); - assert!(r.is_empty()); - assert_eq!(r.next(), None); - assert_eq!(r.next(), None); - assert_eq!(r, 100..=10); - - let mut r = 100..=10; - assert_eq!(r.next_back(), None); - assert!(r.is_empty()); - assert_eq!(r.next_back(), None); - assert_eq!(r.next_back(), None); - assert_eq!(r, 100..=10); -} - -#[test] -fn test_range_nth() { - assert_eq!((10..15).nth(0), Some(10)); - assert_eq!((10..15).nth(1), Some(11)); - assert_eq!((10..15).nth(4), Some(14)); - assert_eq!((10..15).nth(5), None); - - let mut r = 10..20; - assert_eq!(r.nth(2), Some(12)); - assert_eq!(r, 13..20); - assert_eq!(r.nth(2), Some(15)); - assert_eq!(r, 16..20); - assert_eq!(r.nth(10), None); - assert_eq!(r, 20..20); -} - -#[test] -fn test_range_nth_back() { - assert_eq!((10..15).nth_back(0), Some(14)); - assert_eq!((10..15).nth_back(1), Some(13)); - assert_eq!((10..15).nth_back(4), Some(10)); - assert_eq!((10..15).nth_back(5), None); - assert_eq!((-120..80_i8).nth_back(199), Some(-120)); - - let mut r = 10..20; - assert_eq!(r.nth_back(2), Some(17)); - assert_eq!(r, 10..17); - assert_eq!(r.nth_back(2), Some(14)); - assert_eq!(r, 10..14); - assert_eq!(r.nth_back(10), None); - assert_eq!(r, 10..10); -} - -#[test] -fn test_range_from_nth() { - assert_eq!((10..).nth(0), Some(10)); - assert_eq!((10..).nth(1), Some(11)); - assert_eq!((10..).nth(4), Some(14)); - - let mut r = 10..; - assert_eq!(r.nth(2), Some(12)); - assert_eq!(r, 13..); - assert_eq!(r.nth(2), Some(15)); - assert_eq!(r, 16..); - assert_eq!(r.nth(10), Some(26)); - assert_eq!(r, 27..); - - assert_eq!((0..).size_hint(), (usize::MAX, None)); -} - -#[test] -fn test_range_from_take() { - let mut it = (0..).take(3); - assert_eq!(it.next(), Some(0)); - assert_eq!(it.next(), Some(1)); - assert_eq!(it.next(), Some(2)); - assert_eq!(it.next(), None); - is_trusted_len((0..).take(3)); - assert_eq!((0..).take(3).size_hint(), (3, Some(3))); - assert_eq!((0..).take(0).size_hint(), (0, Some(0))); - assert_eq!((0..).take(usize::MAX).size_hint(), (usize::MAX, Some(usize::MAX))); -} - -#[test] -fn test_range_from_take_collect() { - let v: Vec<_> = (0..).take(3).collect(); - assert_eq!(v, vec![0, 1, 2]); -} - -#[test] -fn test_range_inclusive_nth() { - assert_eq!((10..=15).nth(0), Some(10)); - assert_eq!((10..=15).nth(1), Some(11)); - assert_eq!((10..=15).nth(5), Some(15)); - assert_eq!((10..=15).nth(6), None); - - let mut exhausted_via_next = 10_u8..=20; - while exhausted_via_next.next().is_some() {} - - let mut r = 10_u8..=20; - assert_eq!(r.nth(2), Some(12)); - assert_eq!(r, 13..=20); - assert_eq!(r.nth(2), Some(15)); - assert_eq!(r, 16..=20); - assert_eq!(r.is_empty(), false); - assert_eq!(ExactSizeIterator::is_empty(&r), false); - assert_eq!(r.nth(10), None); - assert_eq!(r.is_empty(), true); - assert_eq!(r, exhausted_via_next); - assert_eq!(ExactSizeIterator::is_empty(&r), true); -} - -#[test] -fn test_range_inclusive_nth_back() { - assert_eq!((10..=15).nth_back(0), Some(15)); - assert_eq!((10..=15).nth_back(1), Some(14)); - assert_eq!((10..=15).nth_back(5), Some(10)); - assert_eq!((10..=15).nth_back(6), None); - assert_eq!((-120..=80_i8).nth_back(200), Some(-120)); - - let mut exhausted_via_next_back = 10_u8..=20; - while exhausted_via_next_back.next_back().is_some() {} - - let mut r = 10_u8..=20; - assert_eq!(r.nth_back(2), Some(18)); - assert_eq!(r, 10..=17); - assert_eq!(r.nth_back(2), Some(15)); - assert_eq!(r, 10..=14); - assert_eq!(r.is_empty(), false); - assert_eq!(ExactSizeIterator::is_empty(&r), false); - assert_eq!(r.nth_back(10), None); - assert_eq!(r.is_empty(), true); - assert_eq!(r, exhausted_via_next_back); - assert_eq!(ExactSizeIterator::is_empty(&r), true); -} - -#[test] -fn test_range_len() { - assert_eq!((0..10_u8).len(), 10); - assert_eq!((9..10_u8).len(), 1); - assert_eq!((10..10_u8).len(), 0); - assert_eq!((11..10_u8).len(), 0); - assert_eq!((100..10_u8).len(), 0); -} - -#[test] -fn test_range_inclusive_len() { - assert_eq!((0..=10_u8).len(), 11); - assert_eq!((9..=10_u8).len(), 2); - assert_eq!((10..=10_u8).len(), 1); - assert_eq!((11..=10_u8).len(), 0); - assert_eq!((100..=10_u8).len(), 0); -} - -#[test] -fn test_range_step() { - #![allow(deprecated)] - - assert_eq!((0..20).step_by(5).collect::>(), [0, 5, 10, 15]); - assert_eq!((1..21).rev().step_by(5).collect::>(), [20, 15, 10, 5]); - assert_eq!((1..21).rev().step_by(6).collect::>(), [20, 14, 8, 2]); - assert_eq!((200..255).step_by(50).collect::>(), [200, 250]); - assert_eq!((200..-5).step_by(1).collect::>(), []); - assert_eq!((200..200).step_by(1).collect::>(), []); - - assert_eq!((0..20).step_by(1).size_hint(), (20, Some(20))); - assert_eq!((0..20).step_by(21).size_hint(), (1, Some(1))); - assert_eq!((0..20).step_by(5).size_hint(), (4, Some(4))); - assert_eq!((1..21).rev().step_by(5).size_hint(), (4, Some(4))); - assert_eq!((1..21).rev().step_by(6).size_hint(), (4, Some(4))); - assert_eq!((20..-5).step_by(1).size_hint(), (0, Some(0))); - assert_eq!((20..20).step_by(1).size_hint(), (0, Some(0))); - assert_eq!((i8::MIN..i8::MAX).step_by(-(i8::MIN as i32) as usize).size_hint(), (2, Some(2))); - assert_eq!((i16::MIN..i16::MAX).step_by(i16::MAX as usize).size_hint(), (3, Some(3))); - assert_eq!((isize::MIN..isize::MAX).step_by(1).size_hint(), (usize::MAX, Some(usize::MAX))); -} - -#[test] -fn test_range_advance_by() { - let mut r = 0..usize::MAX; - assert_eq!(Ok(()), r.advance_by(0)); - assert_eq!(Ok(()), r.advance_back_by(0)); - - assert_eq!(r.len(), usize::MAX); - - assert_eq!(Ok(()), r.advance_by(1)); - assert_eq!(Ok(()), r.advance_back_by(1)); - - assert_eq!((r.start, r.end), (1, usize::MAX - 1)); - - assert_eq!(Err(NonZero::new(2).unwrap()), r.advance_by(usize::MAX)); - - assert_eq!(Ok(()), r.advance_by(0)); - assert_eq!(Ok(()), r.advance_back_by(0)); - - let mut r = 0u128..u128::MAX; - - assert_eq!(Ok(()), r.advance_by(usize::MAX)); - assert_eq!(Ok(()), r.advance_back_by(usize::MAX)); - - assert_eq!((r.start, r.end), (0u128 + usize::MAX as u128, u128::MAX - usize::MAX as u128)); - - // issue 122420, Step::forward_unchecked was unsound for signed integers - let mut r = -128i8..127; - assert_eq!(Ok(()), r.advance_by(200)); - assert_eq!(r.next(), Some(72)); -} - -#[test] -fn test_range_inclusive_step() { - assert_eq!((0..=50).step_by(10).collect::>(), [0, 10, 20, 30, 40, 50]); - assert_eq!((0..=5).step_by(1).collect::>(), [0, 1, 2, 3, 4, 5]); - assert_eq!((200..=255u8).step_by(10).collect::>(), [200, 210, 220, 230, 240, 250]); - assert_eq!((250..=255u8).step_by(1).collect::>(), [250, 251, 252, 253, 254, 255]); -} - -#[test] -fn test_range_last_max() { - assert_eq!((0..20).last(), Some(19)); - assert_eq!((-20..0).last(), Some(-1)); - assert_eq!((5..5).last(), None); - - assert_eq!((0..20).max(), Some(19)); - assert_eq!((-20..0).max(), Some(-1)); - assert_eq!((5..5).max(), None); -} - -#[test] -fn test_range_inclusive_last_max() { - assert_eq!((0..=20).last(), Some(20)); - assert_eq!((-20..=0).last(), Some(0)); - assert_eq!((5..=5).last(), Some(5)); - let mut r = 10..=10; - r.next(); - assert_eq!(r.last(), None); - - assert_eq!((0..=20).max(), Some(20)); - assert_eq!((-20..=0).max(), Some(0)); - assert_eq!((5..=5).max(), Some(5)); - let mut r = 10..=10; - r.next(); - assert_eq!(r.max(), None); -} - -#[test] -fn test_range_min() { - assert_eq!((0..20).min(), Some(0)); - assert_eq!((-20..0).min(), Some(-20)); - assert_eq!((5..5).min(), None); -} - -#[test] -fn test_range_inclusive_min() { - assert_eq!((0..=20).min(), Some(0)); - assert_eq!((-20..=0).min(), Some(-20)); - assert_eq!((5..=5).min(), Some(5)); - let mut r = 10..=10; - r.next(); - assert_eq!(r.min(), None); -} - -#[test] -fn test_range_inclusive_folds() { - assert_eq!((1..=10).sum::(), 55); - assert_eq!((1..=10).rev().sum::(), 55); - - let mut it = 44..=50; - assert_eq!(it.try_fold(0, i8::checked_add), None); - assert_eq!(it, 47..=50); - assert_eq!(it.try_fold(0, i8::checked_add), None); - assert_eq!(it, 50..=50); - assert_eq!(it.try_fold(0, i8::checked_add), Some(50)); - assert!(it.is_empty()); - assert_eq!(it.try_fold(0, i8::checked_add), Some(0)); - assert!(it.is_empty()); - - let mut it = 40..=47; - assert_eq!(it.try_rfold(0, i8::checked_add), None); - assert_eq!(it, 40..=44); - assert_eq!(it.try_rfold(0, i8::checked_add), None); - assert_eq!(it, 40..=41); - assert_eq!(it.try_rfold(0, i8::checked_add), Some(81)); - assert!(it.is_empty()); - assert_eq!(it.try_rfold(0, i8::checked_add), Some(0)); - assert!(it.is_empty()); - - let mut it = 10..=20; - assert_eq!(it.try_fold(0, |a, b| Some(a + b)), Some(165)); - assert!(it.is_empty()); - assert_eq!(it.try_fold(0, |a, b| Some(a + b)), Some(0)); - assert!(it.is_empty()); - - let mut it = 10..=20; - assert_eq!(it.try_rfold(0, |a, b| Some(a + b)), Some(165)); - assert!(it.is_empty()); - assert_eq!(it.try_rfold(0, |a, b| Some(a + b)), Some(0)); - assert!(it.is_empty()); -} - -#[test] -fn test_range_size_hint() { - assert_eq!((0..0usize).size_hint(), (0, Some(0))); - assert_eq!((0..100usize).size_hint(), (100, Some(100))); - assert_eq!((0..usize::MAX).size_hint(), (usize::MAX, Some(usize::MAX))); - - let umax = u128::try_from(usize::MAX).unwrap(); - assert_eq!((0..0u128).size_hint(), (0, Some(0))); - assert_eq!((0..100u128).size_hint(), (100, Some(100))); - assert_eq!((0..umax).size_hint(), (usize::MAX, Some(usize::MAX))); - assert_eq!((0..umax + 1).size_hint(), (usize::MAX, None)); - - assert_eq!((0..0isize).size_hint(), (0, Some(0))); - assert_eq!((-100..100isize).size_hint(), (200, Some(200))); - assert_eq!((isize::MIN..isize::MAX).size_hint(), (usize::MAX, Some(usize::MAX))); - - let imin = i128::try_from(isize::MIN).unwrap(); - let imax = i128::try_from(isize::MAX).unwrap(); - assert_eq!((0..0i128).size_hint(), (0, Some(0))); - assert_eq!((-100..100i128).size_hint(), (200, Some(200))); - assert_eq!((imin..imax).size_hint(), (usize::MAX, Some(usize::MAX))); - assert_eq!((imin..imax + 1).size_hint(), (usize::MAX, None)); -} - -#[test] -fn test_range_inclusive_size_hint() { - assert_eq!((1..=0usize).size_hint(), (0, Some(0))); - assert_eq!((0..=0usize).size_hint(), (1, Some(1))); - assert_eq!((0..=100usize).size_hint(), (101, Some(101))); - assert_eq!((0..=usize::MAX - 1).size_hint(), (usize::MAX, Some(usize::MAX))); - assert_eq!((0..=usize::MAX).size_hint(), (usize::MAX, None)); - - let umax = u128::try_from(usize::MAX).unwrap(); - assert_eq!((1..=0u128).size_hint(), (0, Some(0))); - assert_eq!((0..=0u128).size_hint(), (1, Some(1))); - assert_eq!((0..=100u128).size_hint(), (101, Some(101))); - assert_eq!((0..=umax - 1).size_hint(), (usize::MAX, Some(usize::MAX))); - assert_eq!((0..=umax).size_hint(), (usize::MAX, None)); - assert_eq!((0..=umax + 1).size_hint(), (usize::MAX, None)); - - assert_eq!((0..=-1isize).size_hint(), (0, Some(0))); - assert_eq!((0..=0isize).size_hint(), (1, Some(1))); - assert_eq!((-100..=100isize).size_hint(), (201, Some(201))); - assert_eq!((isize::MIN..=isize::MAX - 1).size_hint(), (usize::MAX, Some(usize::MAX))); - assert_eq!((isize::MIN..=isize::MAX).size_hint(), (usize::MAX, None)); - - let imin = i128::try_from(isize::MIN).unwrap(); - let imax = i128::try_from(isize::MAX).unwrap(); - assert_eq!((0..=-1i128).size_hint(), (0, Some(0))); - assert_eq!((0..=0i128).size_hint(), (1, Some(1))); - assert_eq!((-100..=100i128).size_hint(), (201, Some(201))); - assert_eq!((imin..=imax - 1).size_hint(), (usize::MAX, Some(usize::MAX))); - assert_eq!((imin..=imax).size_hint(), (usize::MAX, None)); - assert_eq!((imin..=imax + 1).size_hint(), (usize::MAX, None)); -} - -#[test] -fn test_range_trusted_random_access() { - let mut range = 0..10; - unsafe { - assert_eq!(range.next(), Some(0)); - assert_eq!(range.__iterator_get_unchecked(0), 1); - assert_eq!(range.__iterator_get_unchecked(1), 2); - } -} - -#[test] -fn test_double_ended_range() { - assert_eq!((11..14).rev().collect::>(), [13, 12, 11]); - for _ in (10..0).rev() { - panic!("unreachable"); - } - - assert_eq!((11..14).rev().collect::>(), [13, 12, 11]); - for _ in (10..0).rev() { - panic!("unreachable"); - } -} diff --git a/library/core/tests/iter/sources.rs b/library/core/tests/iter/sources.rs deleted file mode 100644 index a15f3a5148f0a..0000000000000 --- a/library/core/tests/iter/sources.rs +++ /dev/null @@ -1,157 +0,0 @@ -use super::*; -use core::iter::*; - -#[test] -fn test_repeat() { - let mut it = repeat(42); - assert_eq!(it.next(), Some(42)); - assert_eq!(it.next(), Some(42)); - assert_eq!(it.next(), Some(42)); - assert_eq!(repeat(42).size_hint(), (usize::MAX, None)); -} - -#[test] -fn test_repeat_take() { - let mut it = repeat(42).take(3); - assert_eq!(it.next(), Some(42)); - assert_eq!(it.next(), Some(42)); - assert_eq!(it.next(), Some(42)); - assert_eq!(it.next(), None); - is_trusted_len(repeat(42).take(3)); - assert_eq!(repeat(42).take(3).size_hint(), (3, Some(3))); - assert_eq!(repeat(42).take(0).size_hint(), (0, Some(0))); - assert_eq!(repeat(42).take(usize::MAX).size_hint(), (usize::MAX, Some(usize::MAX))); -} - -#[test] -fn test_repeat_take_collect() { - let v: Vec<_> = repeat(42).take(3).collect(); - assert_eq!(v, vec![42, 42, 42]); -} - -#[test] -fn test_repeat_with() { - #[derive(PartialEq, Debug)] - struct NotClone(usize); - let mut it = repeat_with(|| NotClone(42)); - assert_eq!(it.next(), Some(NotClone(42))); - assert_eq!(it.next(), Some(NotClone(42))); - assert_eq!(it.next(), Some(NotClone(42))); - assert_eq!(repeat_with(|| NotClone(42)).size_hint(), (usize::MAX, None)); -} - -#[test] -fn test_repeat_with_take() { - let mut it = repeat_with(|| 42).take(3); - assert_eq!(it.next(), Some(42)); - assert_eq!(it.next(), Some(42)); - assert_eq!(it.next(), Some(42)); - assert_eq!(it.next(), None); - is_trusted_len(repeat_with(|| 42).take(3)); - assert_eq!(repeat_with(|| 42).take(3).size_hint(), (3, Some(3))); - assert_eq!(repeat_with(|| 42).take(0).size_hint(), (0, Some(0))); - assert_eq!(repeat_with(|| 42).take(usize::MAX).size_hint(), (usize::MAX, Some(usize::MAX))); -} - -#[test] -fn test_repeat_with_take_collect() { - let mut curr = 1; - let v: Vec<_> = repeat_with(|| { - let tmp = curr; - curr *= 2; - tmp - }) - .take(5) - .collect(); - assert_eq!(v, vec![1, 2, 4, 8, 16]); -} - -#[test] -fn test_successors() { - let mut powers_of_10 = successors(Some(1_u16), |n| n.checked_mul(10)); - assert_eq!(powers_of_10.by_ref().collect::>(), &[1, 10, 100, 1_000, 10_000]); - assert_eq!(powers_of_10.next(), None); - - let mut empty = successors(None::, |_| unimplemented!()); - assert_eq!(empty.next(), None); - assert_eq!(empty.next(), None); -} - -#[test] -fn test_once() { - let mut it = once(42); - assert_eq!(it.next(), Some(42)); - assert_eq!(it.next(), None); -} - -#[test] -fn test_once_with() { - let count = Cell::new(0); - let mut it = once_with(|| { - count.set(count.get() + 1); - 42 - }); - - assert_eq!(count.get(), 0); - assert_eq!(it.next(), Some(42)); - assert_eq!(count.get(), 1); - assert_eq!(it.next(), None); - assert_eq!(count.get(), 1); - assert_eq!(it.next(), None); - assert_eq!(count.get(), 1); -} - -#[test] -fn test_empty() { - let mut it = empty::(); - assert_eq!(it.next(), None); -} - -#[test] -fn test_repeat_n_drop() { - #[derive(Clone, Debug)] - struct DropCounter<'a>(&'a Cell); - impl Drop for DropCounter<'_> { - fn drop(&mut self) { - self.0.set(self.0.get() + 1); - } - } - - // `repeat_n(x, 0)` drops `x` immediately - let count = Cell::new(0); - let item = DropCounter(&count); - let mut it = repeat_n(item, 0); - assert_eq!(count.get(), 1); - assert!(it.next().is_none()); - assert_eq!(count.get(), 1); - drop(it); - assert_eq!(count.get(), 1); - - // Dropping the iterator needs to drop the item if it's non-empty - let count = Cell::new(0); - let item = DropCounter(&count); - let it = repeat_n(item, 3); - assert_eq!(count.get(), 0); - drop(it); - assert_eq!(count.get(), 1); - - // Dropping the iterator doesn't drop the item if it was exhausted - let count = Cell::new(0); - let item = DropCounter(&count); - let mut it = repeat_n(item, 3); - assert_eq!(count.get(), 0); - let x0 = it.next().unwrap(); - assert_eq!(count.get(), 0); - let x1 = it.next().unwrap(); - assert_eq!(count.get(), 0); - let x2 = it.next().unwrap(); - assert_eq!(count.get(), 0); - assert!(it.next().is_none()); - assert_eq!(count.get(), 0); - assert!(it.next().is_none()); - assert_eq!(count.get(), 0); - drop(it); - assert_eq!(count.get(), 0); - drop((x0, x1, x2)); - assert_eq!(count.get(), 3); -} diff --git a/library/core/tests/iter/traits/accum.rs b/library/core/tests/iter/traits/accum.rs deleted file mode 100644 index f3eeb31fe5803..0000000000000 --- a/library/core/tests/iter/traits/accum.rs +++ /dev/null @@ -1,66 +0,0 @@ -use core::iter::*; - -#[test] -fn test_iterator_sum() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; - assert_eq!(v[..4].iter().cloned().sum::(), 6); - assert_eq!(v.iter().cloned().sum::(), 55); - assert_eq!(v[..0].iter().cloned().sum::(), 0); -} - -#[test] -fn test_iterator_sum_result() { - let v: &[Result] = &[Ok(1), Ok(2), Ok(3), Ok(4)]; - assert_eq!(v.iter().cloned().sum::>(), Ok(10)); - let v: &[Result] = &[Ok(1), Err(()), Ok(3), Ok(4)]; - assert_eq!(v.iter().cloned().sum::>(), Err(())); - - #[derive(PartialEq, Debug)] - struct S(Result); - - impl Sum> for S { - fn sum>>(mut iter: I) -> Self { - // takes the sum by repeatedly calling `next` on `iter`, - // thus testing that repeated calls to `ResultShunt::try_fold` - // produce the expected results - Self(iter.by_ref().sum()) - } - } - - let v: &[Result] = &[Ok(1), Ok(2), Ok(3), Ok(4)]; - assert_eq!(v.iter().cloned().sum::(), S(Ok(10))); - let v: &[Result] = &[Ok(1), Err(()), Ok(3), Ok(4)]; - assert_eq!(v.iter().cloned().sum::(), S(Err(()))); -} - -#[test] -fn test_iterator_sum_option() { - let v: &[Option] = &[Some(1), Some(2), Some(3), Some(4)]; - assert_eq!(v.iter().cloned().sum::>(), Some(10)); - let v: &[Option] = &[Some(1), None, Some(3), Some(4)]; - assert_eq!(v.iter().cloned().sum::>(), None); -} - -#[test] -fn test_iterator_product() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; - assert_eq!(v[..4].iter().cloned().product::(), 0); - assert_eq!(v[1..5].iter().cloned().product::(), 24); - assert_eq!(v[..0].iter().cloned().product::(), 1); -} - -#[test] -fn test_iterator_product_result() { - let v: &[Result] = &[Ok(1), Ok(2), Ok(3), Ok(4)]; - assert_eq!(v.iter().cloned().product::>(), Ok(24)); - let v: &[Result] = &[Ok(1), Err(()), Ok(3), Ok(4)]; - assert_eq!(v.iter().cloned().product::>(), Err(())); -} - -#[test] -fn test_iterator_product_option() { - let v: &[Option] = &[Some(1), Some(2), Some(3), Some(4)]; - assert_eq!(v.iter().cloned().product::>(), Some(24)); - let v: &[Option] = &[Some(1), None, Some(3), Some(4)]; - assert_eq!(v.iter().cloned().product::>(), None); -} diff --git a/library/core/tests/iter/traits/double_ended.rs b/library/core/tests/iter/traits/double_ended.rs deleted file mode 100644 index 00ef4a6e6a987..0000000000000 --- a/library/core/tests/iter/traits/double_ended.rs +++ /dev/null @@ -1,91 +0,0 @@ -//! Note -//! ---- -//! You're probably viewing this file because you're adding a test (or you might -//! just be browsing, in that case, hey there!). -//! -//! If you've made a test that happens to use one of DoubleEnded's methods, but -//! it tests another adapter or trait, you should *add it to the adapter or -//! trait's test file*. -//! -//! Some examples would be `adapters::cloned::test_cloned_try_folds` or -//! `adapters::flat_map::test_double_ended_flat_map`, which use `try_fold` and -//! `next_back`, but test their own adapter. - -#[test] -fn test_iterator_rev_nth_back() { - let v: &[_] = &[0, 1, 2, 3, 4]; - for i in 0..v.len() { - assert_eq!(v.iter().rev().nth_back(i).unwrap(), &v[i]); - } - assert_eq!(v.iter().rev().nth_back(v.len()), None); -} - -#[test] -fn test_iterator_rev_nth() { - let v: &[_] = &[0, 1, 2, 3, 4]; - for i in 0..v.len() { - assert_eq!(v.iter().rev().nth(i).unwrap(), &v[v.len() - 1 - i]); - } - assert_eq!(v.iter().rev().nth(v.len()), None); -} - -#[test] -fn test_rev() { - let xs = [2, 4, 6, 8, 10, 12, 14, 16]; - let mut it = xs.iter(); - it.next(); - it.next(); - assert!(it.rev().cloned().collect::>() == vec![16, 14, 12, 10, 8, 6]); -} - -#[test] -fn test_rev_try_folds() { - let f = &|acc, x| i32::checked_add(2 * acc, x); - assert_eq!((1..10).rev().try_fold(7, f), (1..10).try_rfold(7, f)); - assert_eq!((1..10).rev().try_rfold(7, f), (1..10).try_fold(7, f)); - - let a = [10, 20, 30, 40, 100, 60, 70, 80, 90]; - let mut iter = a.iter().rev(); - assert_eq!(iter.try_fold(0_i8, |acc, &x| acc.checked_add(x)), None); - assert_eq!(iter.next(), Some(&70)); - let mut iter = a.iter().rev(); - assert_eq!(iter.try_rfold(0_i8, |acc, &x| acc.checked_add(x)), None); - assert_eq!(iter.next_back(), Some(&60)); -} - -#[test] -fn test_rposition() { - fn f(xy: &(isize, char)) -> bool { - let (_x, y) = *xy; - y == 'b' - } - fn g(xy: &(isize, char)) -> bool { - let (_x, y) = *xy; - y == 'd' - } - let v = [(0, 'a'), (1, 'b'), (2, 'c'), (3, 'b')]; - - assert_eq!(v.iter().rposition(f), Some(3)); - assert!(v.iter().rposition(g).is_none()); -} - -#[test] -fn test_rev_rposition() { - let v = [0, 0, 1, 1]; - assert_eq!(v.iter().rev().rposition(|&x| x == 1), Some(1)); -} - -#[test] -#[should_panic] -fn test_rposition_panic() { - let u = (Box::new(0), Box::new(0)); - let v: [(Box<_>, Box<_>); 4] = [u.clone(), u.clone(), u.clone(), u]; - let mut i = 0; - v.iter().rposition(|_elt| { - if i == 2 { - panic!() - } - i += 1; - false - }); -} diff --git a/library/core/tests/iter/traits/iterator.rs b/library/core/tests/iter/traits/iterator.rs deleted file mode 100644 index 93ef9c0812b16..0000000000000 --- a/library/core/tests/iter/traits/iterator.rs +++ /dev/null @@ -1,626 +0,0 @@ -use core::num::NonZero; - -/// A wrapper struct that implements `Eq` and `Ord` based on the wrapped -/// integer modulo 3. Used to test that `Iterator::max` and `Iterator::min` -/// return the correct element if some of them are equal. -#[derive(Debug)] -struct Mod3(i32); - -impl PartialEq for Mod3 { - fn eq(&self, other: &Self) -> bool { - self.0 % 3 == other.0 % 3 - } -} - -impl Eq for Mod3 {} - -impl PartialOrd for Mod3 { - fn partial_cmp(&self, other: &Self) -> Option { - Some(self.cmp(other)) - } -} - -impl Ord for Mod3 { - fn cmp(&self, other: &Self) -> core::cmp::Ordering { - (self.0 % 3).cmp(&(other.0 % 3)) - } -} - -#[test] -fn test_lt() { - let empty: [isize; 0] = []; - let xs = [1, 2, 3]; - let ys = [1, 2, 0]; - - assert!(!xs.iter().lt(ys.iter())); - assert!(!xs.iter().le(ys.iter())); - assert!(xs.iter().gt(ys.iter())); - assert!(xs.iter().ge(ys.iter())); - - assert!(ys.iter().lt(xs.iter())); - assert!(ys.iter().le(xs.iter())); - assert!(!ys.iter().gt(xs.iter())); - assert!(!ys.iter().ge(xs.iter())); - - assert!(empty.iter().lt(xs.iter())); - assert!(empty.iter().le(xs.iter())); - assert!(!empty.iter().gt(xs.iter())); - assert!(!empty.iter().ge(xs.iter())); - - // Sequence with NaN - let u = [1.0f64, 2.0]; - let v = [0.0f64 / 0.0, 3.0]; - - assert!(!u.iter().lt(v.iter())); - assert!(!u.iter().le(v.iter())); - assert!(!u.iter().gt(v.iter())); - assert!(!u.iter().ge(v.iter())); - - let a = [0.0f64 / 0.0]; - let b = [1.0f64]; - let c = [2.0f64]; - - assert!(a.iter().lt(b.iter()) == (a[0] < b[0])); - assert!(a.iter().le(b.iter()) == (a[0] <= b[0])); - assert!(a.iter().gt(b.iter()) == (a[0] > b[0])); - assert!(a.iter().ge(b.iter()) == (a[0] >= b[0])); - - assert!(c.iter().lt(b.iter()) == (c[0] < b[0])); - assert!(c.iter().le(b.iter()) == (c[0] <= b[0])); - assert!(c.iter().gt(b.iter()) == (c[0] > b[0])); - assert!(c.iter().ge(b.iter()) == (c[0] >= b[0])); -} - -#[test] -fn test_cmp_by() { - use core::cmp::Ordering; - - let f = |x: i32, y: i32| (x * x).cmp(&y); - let xs = || [1, 2, 3, 4].iter().copied(); - let ys = || [1, 4, 16].iter().copied(); - - assert_eq!(xs().cmp_by(ys(), f), Ordering::Less); - assert_eq!(ys().cmp_by(xs(), f), Ordering::Greater); - assert_eq!(xs().cmp_by(xs().map(|x| x * x), f), Ordering::Equal); - assert_eq!(xs().rev().cmp_by(ys().rev(), f), Ordering::Greater); - assert_eq!(xs().cmp_by(ys().rev(), f), Ordering::Less); - assert_eq!(xs().cmp_by(ys().take(2), f), Ordering::Greater); -} - -#[test] -fn test_partial_cmp_by() { - use core::cmp::Ordering; - - let f = |x: i32, y: i32| (x * x).partial_cmp(&y); - let xs = || [1, 2, 3, 4].iter().copied(); - let ys = || [1, 4, 16].iter().copied(); - - assert_eq!(xs().partial_cmp_by(ys(), f), Some(Ordering::Less)); - assert_eq!(ys().partial_cmp_by(xs(), f), Some(Ordering::Greater)); - assert_eq!(xs().partial_cmp_by(xs().map(|x| x * x), f), Some(Ordering::Equal)); - assert_eq!(xs().rev().partial_cmp_by(ys().rev(), f), Some(Ordering::Greater)); - assert_eq!(xs().partial_cmp_by(xs().rev(), f), Some(Ordering::Less)); - assert_eq!(xs().partial_cmp_by(ys().take(2), f), Some(Ordering::Greater)); - - let f = |x: f64, y: f64| (x * x).partial_cmp(&y); - let xs = || [1.0, 2.0, 3.0, 4.0].iter().copied(); - let ys = || [1.0, 4.0, f64::NAN, 16.0].iter().copied(); - - assert_eq!(xs().partial_cmp_by(ys(), f), None); - assert_eq!(ys().partial_cmp_by(xs(), f), Some(Ordering::Greater)); -} - -#[test] -fn test_eq_by() { - let f = |x: i32, y: i32| x * x == y; - let xs = || [1, 2, 3, 4].iter().copied(); - let ys = || [1, 4, 9, 16].iter().copied(); - - assert!(xs().eq_by(ys(), f)); - assert!(!ys().eq_by(xs(), f)); - assert!(!xs().eq_by(xs(), f)); - assert!(!ys().eq_by(ys(), f)); - - assert!(!xs().take(3).eq_by(ys(), f)); - assert!(!xs().eq_by(ys().take(3), f)); - assert!(xs().take(3).eq_by(ys().take(3), f)); -} - -#[test] -fn test_iterator_nth() { - let v: &[_] = &[0, 1, 2, 3, 4]; - for i in 0..v.len() { - assert_eq!(v.iter().nth(i).unwrap(), &v[i]); - } - assert_eq!(v.iter().nth(v.len()), None); -} - -#[test] -fn test_iterator_nth_back() { - let v: &[_] = &[0, 1, 2, 3, 4]; - for i in 0..v.len() { - assert_eq!(v.iter().nth_back(i).unwrap(), &v[v.len() - 1 - i]); - } - assert_eq!(v.iter().nth_back(v.len()), None); -} - -#[test] -fn test_iterator_advance_by() { - let v: &[_] = &[0, 1, 2, 3, 4]; - - for i in 0..v.len() { - let mut iter = v.iter(); - assert_eq!(iter.advance_by(i), Ok(())); - assert_eq!(iter.next().unwrap(), &v[i]); - assert_eq!(iter.advance_by(100), Err(NonZero::new(100 - (v.len() - 1 - i)).unwrap())); - } - - assert_eq!(v.iter().advance_by(v.len()), Ok(())); - assert_eq!(v.iter().advance_by(100), Err(NonZero::new(100 - v.len()).unwrap())); -} - -#[test] -fn test_iterator_advance_back_by() { - let v: &[_] = &[0, 1, 2, 3, 4]; - - for i in 0..v.len() { - let mut iter = v.iter(); - assert_eq!(iter.advance_back_by(i), Ok(())); - assert_eq!(iter.next_back().unwrap(), &v[v.len() - 1 - i]); - assert_eq!(iter.advance_back_by(100), Err(NonZero::new(100 - (v.len() - 1 - i)).unwrap())); - } - - assert_eq!(v.iter().advance_back_by(v.len()), Ok(())); - assert_eq!(v.iter().advance_back_by(100), Err(NonZero::new(100 - v.len()).unwrap())); -} - -#[test] -fn test_iterator_rev_advance_back_by() { - let v: &[_] = &[0, 1, 2, 3, 4]; - - for i in 0..v.len() { - let mut iter = v.iter().rev(); - assert_eq!(iter.advance_back_by(i), Ok(())); - assert_eq!(iter.next_back().unwrap(), &v[i]); - assert_eq!(iter.advance_back_by(100), Err(NonZero::new(100 - (v.len() - 1 - i)).unwrap())); - } - - assert_eq!(v.iter().rev().advance_back_by(v.len()), Ok(())); - assert_eq!(v.iter().rev().advance_back_by(100), Err(NonZero::new(100 - v.len()).unwrap())); -} - -#[test] -fn test_iterator_last() { - let v: &[_] = &[0, 1, 2, 3, 4]; - assert_eq!(v.iter().last().unwrap(), &4); - assert_eq!(v[..1].iter().last().unwrap(), &0); -} - -#[test] -fn test_iterator_max() { - let v: &[_] = &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; - assert_eq!(v[..4].iter().cloned().max(), Some(3)); - assert_eq!(v.iter().cloned().max(), Some(10)); - assert_eq!(v[..0].iter().cloned().max(), None); - assert_eq!(v.iter().cloned().map(Mod3).max().map(|x| x.0), Some(8)); -} - -#[test] -fn test_iterator_min() { - let v: &[_] = &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; - assert_eq!(v[..4].iter().cloned().min(), Some(0)); - assert_eq!(v.iter().cloned().min(), Some(0)); - assert_eq!(v[..0].iter().cloned().min(), None); - assert_eq!(v.iter().cloned().map(Mod3).min().map(|x| x.0), Some(0)); -} - -#[test] -fn test_iterator_size_hint() { - let c = (0..).step_by(1); - let v: &[_] = &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]; - let v2 = &[10, 11, 12]; - let vi = v.iter(); - - assert_eq!((0..).size_hint(), (usize::MAX, None)); - assert_eq!(c.size_hint(), (usize::MAX, None)); - assert_eq!(vi.clone().size_hint(), (10, Some(10))); - - assert_eq!(c.clone().take(5).size_hint(), (5, Some(5))); - assert_eq!(c.clone().skip(5).size_hint().1, None); - assert_eq!(c.clone().take_while(|_| false).size_hint(), (0, None)); - assert_eq!(c.clone().map_while(|_| None::<()>).size_hint(), (0, None)); - assert_eq!(c.clone().skip_while(|_| false).size_hint(), (0, None)); - assert_eq!(c.clone().enumerate().size_hint(), (usize::MAX, None)); - assert_eq!(c.clone().chain(vi.clone().cloned()).size_hint(), (usize::MAX, None)); - assert_eq!(c.clone().zip(vi.clone()).size_hint(), (10, Some(10))); - assert_eq!(c.clone().scan(0, |_, _| Some(0)).size_hint(), (0, None)); - assert_eq!(c.clone().filter(|_| false).size_hint(), (0, None)); - assert_eq!(c.clone().map(|_| 0).size_hint(), (usize::MAX, None)); - assert_eq!(c.filter_map(|_| Some(0)).size_hint(), (0, None)); - - assert_eq!(vi.clone().take(5).size_hint(), (5, Some(5))); - assert_eq!(vi.clone().take(12).size_hint(), (10, Some(10))); - assert_eq!(vi.clone().skip(3).size_hint(), (7, Some(7))); - assert_eq!(vi.clone().skip(12).size_hint(), (0, Some(0))); - assert_eq!(vi.clone().take_while(|_| false).size_hint(), (0, Some(10))); - assert_eq!(vi.clone().map_while(|_| None::<()>).size_hint(), (0, Some(10))); - assert_eq!(vi.clone().skip_while(|_| false).size_hint(), (0, Some(10))); - assert_eq!(vi.clone().enumerate().size_hint(), (10, Some(10))); - assert_eq!(vi.clone().chain(v2).size_hint(), (13, Some(13))); - assert_eq!(vi.clone().zip(v2).size_hint(), (3, Some(3))); - assert_eq!(vi.clone().scan(0, |_, _| Some(0)).size_hint(), (0, Some(10))); - assert_eq!(vi.clone().filter(|_| false).size_hint(), (0, Some(10))); - assert_eq!(vi.clone().map(|&i| i + 1).size_hint(), (10, Some(10))); - assert_eq!(vi.filter_map(|_| Some(0)).size_hint(), (0, Some(10))); -} - -#[test] -fn test_all() { - let v: Box<[isize]> = Box::new([1, 2, 3, 4, 5]); - assert!(v.iter().all(|&x| x < 10)); - assert!(!v.iter().all(|&x| x % 2 == 0)); - assert!(!v.iter().all(|&x| x > 100)); - assert!(v[..0].iter().all(|_| panic!())); -} - -#[test] -fn test_any() { - let v: Box<[isize]> = Box::new([1, 2, 3, 4, 5]); - assert!(v.iter().any(|&x| x < 10)); - assert!(v.iter().any(|&x| x % 2 == 0)); - assert!(!v.iter().any(|&x| x > 100)); - assert!(!v[..0].iter().any(|_| panic!())); -} - -#[test] -fn test_find() { - let v: &[isize] = &[1, 3, 9, 27, 103, 14, 11]; - assert_eq!(*v.iter().find(|&&x| x & 1 == 0).unwrap(), 14); - assert_eq!(*v.iter().find(|&&x| x % 3 == 0).unwrap(), 3); - assert!(v.iter().find(|&&x| x % 12 == 0).is_none()); -} - -#[test] -fn test_try_find() { - let xs: &[isize] = &[]; - assert_eq!(xs.iter().try_find(testfn), Ok(None)); - let xs: &[isize] = &[1, 2, 3, 4]; - assert_eq!(xs.iter().try_find(testfn), Ok(Some(&2))); - let xs: &[isize] = &[1, 3, 4]; - assert_eq!(xs.iter().try_find(testfn), Err(())); - - let xs: &[isize] = &[1, 2, 3, 4, 5, 6, 7]; - let mut iter = xs.iter(); - assert_eq!(iter.try_find(testfn), Ok(Some(&2))); - assert_eq!(iter.try_find(testfn), Err(())); - assert_eq!(iter.next(), Some(&5)); - - fn testfn(x: &&isize) -> Result { - if **x == 2 { - return Ok(true); - } - if **x == 4 { - return Err(()); - } - Ok(false) - } -} - -#[test] -fn test_try_find_api_usability() -> Result<(), Box> { - let a = ["1", "2"]; - - let is_my_num = |s: &str, search: i32| -> Result { - Ok(s.parse::()? == search) - }; - - let val = a.iter().try_find(|&&s| is_my_num(s, 2))?; - assert_eq!(val, Some(&"2")); - - Ok(()) -} - -#[test] -fn test_position() { - let v = &[1, 3, 9, 27, 103, 14, 11]; - assert_eq!(v.iter().position(|x| *x & 1 == 0).unwrap(), 5); - assert_eq!(v.iter().position(|x| *x % 3 == 0).unwrap(), 1); - assert!(v.iter().position(|x| *x % 12 == 0).is_none()); -} - -#[test] -fn test_count() { - let xs = &[1, 2, 2, 1, 5, 9, 0, 2]; - assert_eq!(xs.iter().filter(|x| **x == 2).count(), 3); - assert_eq!(xs.iter().filter(|x| **x == 5).count(), 1); - assert_eq!(xs.iter().filter(|x| **x == 95).count(), 0); -} - -#[test] -fn test_max_by_key() { - let xs: &[isize] = &[-3, 0, 1, 5, -10]; - assert_eq!(*xs.iter().max_by_key(|x| x.abs()).unwrap(), -10); -} - -#[test] -fn test_max_by() { - let xs: &[isize] = &[-3, 0, 1, 5, -10]; - assert_eq!(*xs.iter().max_by(|x, y| x.abs().cmp(&y.abs())).unwrap(), -10); -} - -#[test] -fn test_min_by_key() { - let xs: &[isize] = &[-3, 0, 1, 5, -10]; - assert_eq!(*xs.iter().min_by_key(|x| x.abs()).unwrap(), 0); -} - -#[test] -fn test_min_by() { - let xs: &[isize] = &[-3, 0, 1, 5, -10]; - assert_eq!(*xs.iter().min_by(|x, y| x.abs().cmp(&y.abs())).unwrap(), 0); -} - -#[test] -fn test_by_ref() { - let mut xs = 0..10; - // sum the first five values - let partial_sum = xs.by_ref().take(5).fold(0, |a, b| a + b); - assert_eq!(partial_sum, 10); - assert_eq!(xs.next(), Some(5)); -} - -#[test] -fn test_is_sorted() { - // Tests on integers - assert!([1, 2, 2, 9].iter().is_sorted()); - assert!(![1, 3, 2].iter().is_sorted()); - assert!([0].iter().is_sorted()); - assert!([0, 0].iter().is_sorted()); - assert!(core::iter::empty::().is_sorted()); - - // Tests on floats - assert!([1.0f32, 2.0, 2.0, 9.0].iter().is_sorted()); - assert!(![1.0f32, 3.0f32, 2.0f32].iter().is_sorted()); - assert!([0.0f32].iter().is_sorted()); - assert!([0.0f32, 0.0f32].iter().is_sorted()); - // Test cases with NaNs - assert!([f32::NAN].iter().is_sorted()); - assert!(![f32::NAN, f32::NAN].iter().is_sorted()); - assert!(![0.0, 1.0, f32::NAN].iter().is_sorted()); - // Tests from - assert!(![f32::NAN, f32::NAN, f32::NAN].iter().is_sorted()); - assert!(![1.0, f32::NAN, 2.0].iter().is_sorted()); - assert!(![2.0, f32::NAN, 1.0].iter().is_sorted()); - assert!(![2.0, f32::NAN, 1.0, 7.0].iter().is_sorted()); - assert!(![2.0, f32::NAN, 1.0, 0.0].iter().is_sorted()); - assert!(![-f32::NAN, -1.0, 0.0, 1.0, f32::NAN].iter().is_sorted()); - assert!(![f32::NAN, -f32::NAN, -1.0, 0.0, 1.0].iter().is_sorted()); - assert!(![1.0, f32::NAN, -f32::NAN, -1.0, 0.0].iter().is_sorted()); - assert!(![0.0, 1.0, f32::NAN, -f32::NAN, -1.0].iter().is_sorted()); - assert!(![-1.0, 0.0, 1.0, f32::NAN, -f32::NAN].iter().is_sorted()); - - // Tests for is_sorted_by - assert!(![6, 2, 8, 5, 1, -60, 1337].iter().is_sorted()); - assert!([6, 2, 8, 5, 1, -60, 1337].iter().is_sorted_by(|_, _| true)); - - // Tests for is_sorted_by_key - assert!([-2, -1, 0, 3].iter().is_sorted()); - assert!(![-2i32, -1, 0, 3].iter().is_sorted_by_key(|n| n.abs())); - assert!(!["c", "bb", "aaa"].iter().is_sorted()); - assert!(["c", "bb", "aaa"].iter().is_sorted_by_key(|s| s.len())); -} - -#[test] -fn test_partition() { - fn check(xs: &mut [i32], ref p: impl Fn(&i32) -> bool, expected: usize) { - let i = xs.iter_mut().partition_in_place(p); - assert_eq!(expected, i); - assert!(xs[..i].iter().all(p)); - assert!(!xs[i..].iter().any(p)); - assert!(xs.iter().is_partitioned(p)); - if i == 0 || i == xs.len() { - assert!(xs.iter().rev().is_partitioned(p)); - } else { - assert!(!xs.iter().rev().is_partitioned(p)); - } - } - - check(&mut [], |_| true, 0); - check(&mut [], |_| false, 0); - - check(&mut [0], |_| true, 1); - check(&mut [0], |_| false, 0); - - check(&mut [-1, 1], |&x| x > 0, 1); - check(&mut [-1, 1], |&x| x < 0, 1); - - let ref mut xs = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9]; - check(xs, |_| true, 10); - check(xs, |_| false, 0); - check(xs, |&x| x % 2 == 0, 5); // evens - check(xs, |&x| x % 2 == 1, 5); // odds - check(xs, |&x| x % 3 == 0, 4); // multiple of 3 - check(xs, |&x| x % 4 == 0, 3); // multiple of 4 - check(xs, |&x| x % 5 == 0, 2); // multiple of 5 - check(xs, |&x| x < 3, 3); // small - check(xs, |&x| x > 6, 3); // large -} - -#[test] -fn test_iterator_rev_advance_by() { - let v: &[_] = &[0, 1, 2, 3, 4]; - - for i in 0..v.len() { - let mut iter = v.iter().rev(); - assert_eq!(iter.advance_by(i), Ok(())); - assert_eq!(iter.next().unwrap(), &v[v.len() - 1 - i]); - assert_eq!(iter.advance_by(100), Err(NonZero::new(100 - (v.len() - 1 - i)).unwrap())); - } - - assert_eq!(v.iter().rev().advance_by(v.len()), Ok(())); - assert_eq!(v.iter().rev().advance_by(100), Err(NonZero::new(100 - v.len()).unwrap())); -} - -#[test] -fn test_find_map() { - let xs: &[isize] = &[]; - assert_eq!(xs.iter().find_map(half_if_even), None); - let xs: &[isize] = &[3, 5]; - assert_eq!(xs.iter().find_map(half_if_even), None); - let xs: &[isize] = &[4, 5]; - assert_eq!(xs.iter().find_map(half_if_even), Some(2)); - let xs: &[isize] = &[3, 6]; - assert_eq!(xs.iter().find_map(half_if_even), Some(3)); - - let xs: &[isize] = &[1, 2, 3, 4, 5, 6, 7]; - let mut iter = xs.iter(); - assert_eq!(iter.find_map(half_if_even), Some(1)); - assert_eq!(iter.find_map(half_if_even), Some(2)); - assert_eq!(iter.find_map(half_if_even), Some(3)); - assert_eq!(iter.next(), Some(&7)); - - fn half_if_even(x: &isize) -> Option { - if x % 2 == 0 { Some(x / 2) } else { None } - } -} - -#[test] -fn test_try_reduce() { - let v = [1usize, 2, 3, 4, 5]; - let sum = v.into_iter().try_reduce(|x, y| x.checked_add(y)); - assert_eq!(sum, Some(Some(15))); - - let v = [1, 2, 3, 4, 5, usize::MAX]; - let sum = v.into_iter().try_reduce(|x, y| x.checked_add(y)); - assert_eq!(sum, None); - - let v: [usize; 0] = []; - let sum = v.into_iter().try_reduce(|x, y| x.checked_add(y)); - assert_eq!(sum, Some(None)); - - let v = ["1", "2", "3", "4", "5"]; - let max = v.into_iter().try_reduce(|x, y| { - if x.parse::().ok()? > y.parse::().ok()? { Some(x) } else { Some(y) } - }); - assert_eq!(max, Some(Some("5"))); - - let v = ["1", "2", "3", "4", "5"]; - let max: Result, ::Err> = - v.into_iter().try_reduce(|x, y| { - if x.parse::()? > y.parse::()? { Ok(x) } else { Ok(y) } - }); - assert_eq!(max, Ok(Some("5"))); -} - -#[test] -fn test_iterator_len() { - let v: &[_] = &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; - assert_eq!(v[..4].iter().count(), 4); - assert_eq!(v[..10].iter().count(), 10); - assert_eq!(v[..0].iter().count(), 0); -} - -#[test] -fn test_collect() { - let a = vec![1, 2, 3, 4, 5]; - let b: Vec = a.iter().cloned().collect(); - assert!(a == b); -} - -#[test] -fn test_try_collect() { - use core::ops::ControlFlow::{Break, Continue}; - - let u = vec![Some(1), Some(2), Some(3)]; - let v = u.into_iter().try_collect::>(); - assert_eq!(v, Some(vec![1, 2, 3])); - - let u = vec![Some(1), Some(2), None, Some(3)]; - let mut it = u.into_iter(); - let v = it.try_collect::>(); - assert_eq!(v, None); - let v = it.try_collect::>(); - assert_eq!(v, Some(vec![3])); - - let u: Vec> = vec![Ok(1), Ok(2), Ok(3)]; - let v = u.into_iter().try_collect::>(); - assert_eq!(v, Ok(vec![1, 2, 3])); - - let u = vec![Ok(1), Ok(2), Err(()), Ok(3)]; - let v = u.into_iter().try_collect::>(); - assert_eq!(v, Err(())); - - let numbers = vec![1, 2, 3, 4, 5]; - let all_positive = numbers - .iter() - .cloned() - .map(|n| if n > 0 { Some(n) } else { None }) - .try_collect::>(); - assert_eq!(all_positive, Some(numbers)); - - let numbers = vec![-2, -1, 0, 1, 2]; - let all_positive = - numbers.into_iter().map(|n| if n > 0 { Some(n) } else { None }).try_collect::>(); - assert_eq!(all_positive, None); - - let u = [Continue(1), Continue(2), Break(3), Continue(4), Continue(5)]; - let mut it = u.into_iter(); - - let v = it.try_collect::>(); - assert_eq!(v, Break(3)); - - let v = it.try_collect::>(); - assert_eq!(v, Continue(vec![4, 5])); -} - -#[test] -fn test_collect_into() { - let a = vec![1, 2, 3, 4, 5]; - let mut b = Vec::new(); - a.iter().cloned().collect_into(&mut b); - assert!(a == b); -} - -#[test] -fn iter_try_collect_uses_try_fold_not_next() { - // This makes sure it picks up optimizations, and doesn't use the `&mut I` impl. - struct PanicOnNext(I); - impl Iterator for PanicOnNext { - type Item = I::Item; - fn next(&mut self) -> Option { - panic!("Iterator::next should not be called!") - } - fn try_fold(&mut self, init: B, f: F) -> R - where - Self: Sized, - F: FnMut(B, Self::Item) -> R, - R: std::ops::Try, - { - self.0.try_fold(init, f) - } - } - - let it = (0..10).map(Some); - let _ = PanicOnNext(it).try_collect::>(); - // validation is just that it didn't panic. -} - -#[test] -fn test_next_chunk() { - let mut it = 0..12; - assert_eq!(it.next_chunk().unwrap(), [0, 1, 2, 3]); - assert_eq!(it.next_chunk().unwrap(), []); - assert_eq!(it.next_chunk().unwrap(), [4, 5, 6, 7, 8, 9]); - assert_eq!(it.next_chunk::<4>().unwrap_err().as_slice(), &[10, 11]); - - let mut it = std::iter::repeat_with(|| panic!()); - assert_eq!(it.next_chunk::<0>().unwrap(), []); -} - -// just tests by whether or not this compiles -fn _empty_impl_all_auto_traits() { - use std::panic::{RefUnwindSafe, UnwindSafe}; - fn all_auto_traits() {} - - all_auto_traits::>(); -} diff --git a/library/core/tests/iter/traits/mod.rs b/library/core/tests/iter/traits/mod.rs deleted file mode 100644 index 80619f53f25f9..0000000000000 --- a/library/core/tests/iter/traits/mod.rs +++ /dev/null @@ -1,4 +0,0 @@ -mod accum; -mod double_ended; -mod iterator; -mod step; diff --git a/library/core/tests/iter/traits/step.rs b/library/core/tests/iter/traits/step.rs deleted file mode 100644 index 3d82a40cd2941..0000000000000 --- a/library/core/tests/iter/traits/step.rs +++ /dev/null @@ -1,89 +0,0 @@ -use core::iter::*; - -#[test] -fn test_steps_between() { - assert_eq!(Step::steps_between(&20_u8, &200_u8), Some(180_usize)); - assert_eq!(Step::steps_between(&-20_i8, &80_i8), Some(100_usize)); - assert_eq!(Step::steps_between(&-120_i8, &80_i8), Some(200_usize)); - assert_eq!(Step::steps_between(&20_u32, &4_000_100_u32), Some(4_000_080_usize)); - assert_eq!(Step::steps_between(&-20_i32, &80_i32), Some(100_usize)); - assert_eq!(Step::steps_between(&-2_000_030_i32, &2_000_050_i32), Some(4_000_080_usize)); - - // Skip u64/i64 to avoid differences with 32-bit vs 64-bit platforms - - assert_eq!(Step::steps_between(&20_u128, &200_u128), Some(180_usize)); - assert_eq!(Step::steps_between(&-20_i128, &80_i128), Some(100_usize)); - if cfg!(target_pointer_width = "64") { - assert_eq!(Step::steps_between(&10_u128, &0x1_0000_0000_0000_0009_u128), Some(usize::MAX)); - } - assert_eq!(Step::steps_between(&10_u128, &0x1_0000_0000_0000_000a_u128), None); - assert_eq!(Step::steps_between(&10_i128, &0x1_0000_0000_0000_000a_i128), None); - assert_eq!( - Step::steps_between(&-0x1_0000_0000_0000_0000_i128, &0x1_0000_0000_0000_0000_i128,), - None, - ); -} - -#[test] -fn test_step_forward() { - assert_eq!(Step::forward_checked(55_u8, 200_usize), Some(255_u8)); - assert_eq!(Step::forward_checked(252_u8, 200_usize), None); - assert_eq!(Step::forward_checked(0_u8, 256_usize), None); - assert_eq!(Step::forward_checked(-110_i8, 200_usize), Some(90_i8)); - assert_eq!(Step::forward_checked(-110_i8, 248_usize), None); - assert_eq!(Step::forward_checked(-126_i8, 256_usize), None); - - assert_eq!(Step::forward_checked(35_u16, 100_usize), Some(135_u16)); - assert_eq!(Step::forward_checked(35_u16, 65500_usize), Some(u16::MAX)); - assert_eq!(Step::forward_checked(36_u16, 65500_usize), None); - assert_eq!(Step::forward_checked(-110_i16, 200_usize), Some(90_i16)); - assert_eq!(Step::forward_checked(-20_030_i16, 50_050_usize), Some(30_020_i16)); - assert_eq!(Step::forward_checked(-10_i16, 40_000_usize), None); - assert_eq!(Step::forward_checked(-10_i16, 70_000_usize), None); - - assert_eq!(Step::forward_checked(10_u128, 70_000_usize), Some(70_010_u128)); - assert_eq!(Step::forward_checked(10_i128, 70_030_usize), Some(70_040_i128)); - assert_eq!( - Step::forward_checked(0xffff_ffff_ffff_ffff__ffff_ffff_ffff_ff00_u128, 0xff_usize), - Some(u128::MAX), - ); - assert_eq!( - Step::forward_checked(0xffff_ffff_ffff_ffff__ffff_ffff_ffff_ff00_u128, 0x100_usize), - None - ); - assert_eq!( - Step::forward_checked(0x7fff_ffff_ffff_ffff__ffff_ffff_ffff_ff00_i128, 0xff_usize), - Some(i128::MAX), - ); - assert_eq!( - Step::forward_checked(0x7fff_ffff_ffff_ffff__ffff_ffff_ffff_ff00_i128, 0x100_usize), - None - ); -} - -#[test] -fn test_step_backward() { - assert_eq!(Step::backward_checked(255_u8, 200_usize), Some(55_u8)); - assert_eq!(Step::backward_checked(100_u8, 200_usize), None); - assert_eq!(Step::backward_checked(255_u8, 256_usize), None); - assert_eq!(Step::backward_checked(90_i8, 200_usize), Some(-110_i8)); - assert_eq!(Step::backward_checked(110_i8, 248_usize), None); - assert_eq!(Step::backward_checked(127_i8, 256_usize), None); - - assert_eq!(Step::backward_checked(135_u16, 100_usize), Some(35_u16)); - assert_eq!(Step::backward_checked(u16::MAX, 65500_usize), Some(35_u16)); - assert_eq!(Step::backward_checked(10_u16, 11_usize), None); - assert_eq!(Step::backward_checked(90_i16, 200_usize), Some(-110_i16)); - assert_eq!(Step::backward_checked(30_020_i16, 50_050_usize), Some(-20_030_i16)); - assert_eq!(Step::backward_checked(-10_i16, 40_000_usize), None); - assert_eq!(Step::backward_checked(-10_i16, 70_000_usize), None); - - assert_eq!(Step::backward_checked(70_010_u128, 70_000_usize), Some(10_u128)); - assert_eq!(Step::backward_checked(70_020_i128, 70_030_usize), Some(-10_i128)); - assert_eq!(Step::backward_checked(10_u128, 7_usize), Some(3_u128)); - assert_eq!(Step::backward_checked(10_u128, 11_usize), None); - assert_eq!( - Step::backward_checked(-0x7fff_ffff_ffff_ffff__ffff_ffff_ffff_ff00_i128, 0x100_usize), - Some(i128::MIN) - ); -} diff --git a/library/core/tests/lazy.rs b/library/core/tests/lazy.rs deleted file mode 100644 index 7f7f1f0058801..0000000000000 --- a/library/core/tests/lazy.rs +++ /dev/null @@ -1,146 +0,0 @@ -use core::{ - cell::{Cell, LazyCell, OnceCell}, - sync::atomic::{AtomicUsize, Ordering::SeqCst}, -}; - -#[test] -fn once_cell() { - let c = OnceCell::new(); - assert!(c.get().is_none()); - c.get_or_init(|| 92); - assert_eq!(c.get(), Some(&92)); - - c.get_or_init(|| panic!("Kaboom!")); - assert_eq!(c.get(), Some(&92)); -} - -#[test] -fn once_cell_get_mut() { - let mut c = OnceCell::new(); - assert!(c.get_mut().is_none()); - c.set(90).unwrap(); - *c.get_mut().unwrap() += 2; - assert_eq!(c.get_mut(), Some(&mut 92)); -} - -#[test] -fn once_cell_drop() { - static DROP_CNT: AtomicUsize = AtomicUsize::new(0); - struct Dropper; - impl Drop for Dropper { - fn drop(&mut self) { - DROP_CNT.fetch_add(1, SeqCst); - } - } - - let x = OnceCell::new(); - x.get_or_init(|| Dropper); - assert_eq!(DROP_CNT.load(SeqCst), 0); - drop(x); - assert_eq!(DROP_CNT.load(SeqCst), 1); -} - -#[test] -fn unsync_once_cell_drop_empty() { - let x = OnceCell::<&'static str>::new(); - drop(x); -} - -/* FIXME(#110395) -#[test] -const fn once_cell_const() { - let _once_cell: OnceCell = OnceCell::new(); - let _once_cell: OnceCell = OnceCell::from(32); -} -*/ - -#[test] -fn clone() { - let s = OnceCell::new(); - let c = s.clone(); - assert!(c.get().is_none()); - - s.set("hello").unwrap(); - let c = s.clone(); - assert_eq!(c.get().map(|c| *c), Some("hello")); -} - -#[test] -fn from_impl() { - assert_eq!(OnceCell::from("value").get(), Some(&"value")); - assert_ne!(OnceCell::from("foo").get(), Some(&"bar")); -} - -#[test] -fn partialeq_impl() { - assert!(OnceCell::from("value") == OnceCell::from("value")); - assert!(OnceCell::from("foo") != OnceCell::from("bar")); - - assert!(OnceCell::<&'static str>::new() == OnceCell::new()); - assert!(OnceCell::<&'static str>::new() != OnceCell::from("value")); -} - -#[test] -fn into_inner() { - let cell: OnceCell<&'static str> = OnceCell::new(); - assert_eq!(cell.into_inner(), None); - let cell = OnceCell::new(); - cell.set("hello").unwrap(); - assert_eq!(cell.into_inner(), Some("hello")); -} - -#[test] -fn lazy_new() { - let called = Cell::new(0); - let x = LazyCell::new(|| { - called.set(called.get() + 1); - 92 - }); - - assert_eq!(called.get(), 0); - - let y = *x - 30; - assert_eq!(y, 62); - assert_eq!(called.get(), 1); - - let y = *x - 30; - assert_eq!(y, 62); - assert_eq!(called.get(), 1); -} - -// Check that we can infer `T` from closure's type. -#[test] -fn lazy_type_inference() { - let _ = LazyCell::new(|| ()); -} - -#[test] -fn aliasing_in_get() { - let x = OnceCell::new(); - x.set(42).unwrap(); - let at_x = x.get().unwrap(); // --- (shared) borrow of inner `Option` --+ - let _ = x.set(27); // <-- temporary (unique) borrow of inner `Option` | - println!("{at_x}"); // <------- up until here ---------------------------+ -} - -#[test] -#[should_panic(expected = "reentrant init")] -fn reentrant_init() { - let x: OnceCell> = OnceCell::new(); - let dangling_ref: Cell> = Cell::new(None); - x.get_or_init(|| { - let r = x.get_or_init(|| Box::new(92)); - dangling_ref.set(Some(r)); - Box::new(62) - }); - eprintln!("use after free: {:?}", dangling_ref.get().unwrap()); -} - -#[test] -fn dropck() { - let cell = OnceCell::new(); - { - let s = String::new(); - cell.set(&s).unwrap(); - } -} diff --git a/library/core/tests/lib.rs b/library/core/tests/lib.rs deleted file mode 100644 index 797108a8425de..0000000000000 --- a/library/core/tests/lib.rs +++ /dev/null @@ -1,183 +0,0 @@ -#![feature(alloc_layout_extra)] -#![feature(array_chunks)] -#![feature(array_ptr_get)] -#![feature(array_windows)] -#![feature(ascii_char)] -#![feature(ascii_char_variants)] -#![feature(async_iter_from_iter)] -#![feature(async_iterator)] -#![feature(bigint_helper_methods)] -#![feature(cell_update)] -#![feature(const_align_offset)] -#![feature(const_align_of_val_raw)] -#![feature(const_black_box)] -#![feature(const_cell_into_inner)] -#![feature(const_hash)] -#![feature(const_heap)] -#![feature(const_intrinsic_copy)] -#![feature(const_int_from_str)] -#![feature(const_maybe_uninit_as_mut_ptr)] -#![feature(const_nonnull_new)] -#![feature(const_pointer_is_aligned)] -#![feature(const_ptr_as_ref)] -#![feature(const_ptr_write)] -#![feature(const_three_way_compare)] -#![feature(const_trait_impl)] -#![feature(const_likely)] -#![feature(core_intrinsics)] -#![feature(core_io_borrowed_buf)] -#![feature(core_private_bignum)] -#![feature(core_private_diy_float)] -#![feature(dec2flt)] -#![feature(div_duration)] -#![feature(duration_abs_diff)] -#![feature(duration_consts_float)] -#![feature(duration_constants)] -#![feature(duration_constructors)] -#![feature(exact_size_is_empty)] -#![feature(extern_types)] -#![feature(freeze)] -#![feature(flt2dec)] -#![feature(fmt_internals)] -#![feature(float_minimum_maximum)] -#![feature(future_join)] -#![feature(generic_assert_internals)] -#![feature(array_try_from_fn)] -#![feature(hasher_prefixfree_extras)] -#![feature(hashmap_internals)] -#![feature(try_find)] -#![feature(is_sorted)] -#![feature(layout_for_ptr)] -#![feature(pattern)] -#![feature(sort_internals)] -#![feature(slice_take)] -#![feature(slice_from_ptr_range)] -#![feature(slice_split_once)] -#![feature(split_as_slice)] -#![feature(maybe_uninit_fill)] -#![feature(maybe_uninit_uninit_array)] -#![feature(maybe_uninit_write_slice)] -#![feature(maybe_uninit_uninit_array_transpose)] -#![feature(min_specialization)] -#![feature(noop_waker)] -#![feature(numfmt)] -#![feature(num_midpoint)] -#![feature(offset_of_nested)] -#![feature(isqrt)] -#![feature(step_trait)] -#![feature(str_internals)] -#![feature(std_internals)] -#![feature(test)] -#![feature(trusted_len)] -#![feature(try_blocks)] -#![feature(try_trait_v2)] -#![feature(slice_internals)] -#![feature(slice_partition_dedup)] -#![feature(ip)] -#![feature(iter_advance_by)] -#![feature(iter_array_chunks)] -#![feature(iter_collect_into)] -#![feature(iter_partition_in_place)] -#![feature(iter_intersperse)] -#![feature(iter_is_partitioned)] -#![feature(iter_next_chunk)] -#![feature(iter_order_by)] -#![feature(iter_repeat_n)] -#![feature(iterator_try_collect)] -#![feature(iterator_try_reduce)] -#![feature(const_ip)] -#![feature(const_ipv4)] -#![feature(const_ipv6)] -#![feature(const_mut_refs)] -#![feature(const_pin)] -#![feature(const_waker)] -#![feature(never_type)] -#![feature(unwrap_infallible)] -#![feature(pointer_is_aligned_to)] -#![feature(portable_simd)] -#![feature(ptr_metadata)] -#![feature(lazy_cell)] -#![feature(unsized_tuple_coercion)] -#![feature(const_option)] -#![feature(const_option_ext)] -#![feature(const_result)] -#![cfg_attr(target_has_atomic = "128", feature(integer_atomics))] -#![cfg_attr(test, feature(cfg_match))] -#![feature(int_roundings)] -#![feature(split_array)] -#![feature(strict_provenance)] -#![feature(strict_provenance_atomic_ptr)] -#![feature(trusted_random_access)] -#![feature(unsize)] -#![feature(const_array_from_ref)] -#![feature(const_slice_from_ref)] -#![feature(waker_getters)] -#![feature(slice_flatten)] -#![feature(error_generic_member_access)] -#![feature(error_in_core)] -#![feature(trait_upcasting)] -#![feature(is_ascii_octdigit)] -#![feature(get_many_mut)] -#![feature(iter_map_windows)] -#![allow(internal_features)] -#![deny(unsafe_op_in_unsafe_fn)] -#![deny(fuzzy_provenance_casts)] - -mod alloc; -mod any; -mod array; -mod ascii; -mod asserting; -mod async_iter; -mod atomic; -mod bool; -mod cell; -mod char; -mod clone; -mod cmp; -mod const_ptr; -mod convert; -mod fmt; -mod future; -mod hash; -mod intrinsics; -mod io; -mod iter; -mod lazy; -#[cfg(test)] -mod macros; -mod manually_drop; -mod mem; -mod net; -mod nonzero; -mod num; -mod ops; -mod option; -mod panic; -mod pattern; -mod pin; -mod pin_macro; -mod ptr; -mod result; -mod simd; -mod slice; -mod str; -mod str_lossy; -mod task; -mod time; -mod tuple; -mod unicode; -mod waker; - -/// Copied from `std::test_helpers::test_rng`, see that function for rationale. -#[track_caller] -#[allow(dead_code)] // Not used in all configurations. -pub(crate) fn test_rng() -> rand_xorshift::XorShiftRng { - use core::hash::{BuildHasher, Hash, Hasher}; - let mut hasher = std::hash::RandomState::new().build_hasher(); - core::panic::Location::caller().hash(&mut hasher); - let hc64 = hasher.finish(); - let seed_vec = hc64.to_le_bytes().into_iter().chain(0u8..8).collect::>(); - let seed: [u8; 16] = seed_vec.as_slice().try_into().unwrap(); - rand::SeedableRng::from_seed(seed) -} diff --git a/library/core/tests/macros.rs b/library/core/tests/macros.rs deleted file mode 100644 index 09994fbcbdb78..0000000000000 --- a/library/core/tests/macros.rs +++ /dev/null @@ -1,175 +0,0 @@ -#[allow(dead_code)] -trait Trait { - fn blah(&self); -} - -#[allow(dead_code)] -struct Struct; - -impl Trait for Struct { - cfg_match! { - cfg(feature = "blah") => { - fn blah(&self) { - unimplemented!(); - } - } - _ => { - fn blah(&self) { - unimplemented!(); - } - } - } -} - -#[test] -fn assert_eq_trailing_comma() { - assert_eq!(1, 1,); -} - -#[test] -fn assert_escape() { - assert!(r#"☃\backslash"#.contains("\\")); -} - -#[test] -fn assert_ne_trailing_comma() { - assert_ne!(1, 2,); -} - -#[rustfmt::skip] -#[test] -fn matches_leading_pipe() { - matches!(1, | 1 | 2 | 3); -} - -#[test] -fn cfg_match_basic() { - cfg_match! { - cfg(target_pointer_width = "64") => { fn f0_() -> bool { true }} - } - - cfg_match! { - cfg(unix) => { fn f1_() -> bool { true }} - cfg(any(target_os = "macos", target_os = "linux")) => { fn f1_() -> bool { false }} - } - - cfg_match! { - cfg(target_pointer_width = "32") => { fn f2_() -> bool { false }} - cfg(target_pointer_width = "64") => { fn f2_() -> bool { true }} - } - - cfg_match! { - cfg(target_pointer_width = "16") => { fn f3_() -> i32 { 1 }} - _ => { fn f3_() -> i32 { 2 }} - } - - #[cfg(target_pointer_width = "64")] - assert!(f0_()); - - #[cfg(unix)] - assert!(f1_()); - - #[cfg(target_pointer_width = "32")] - assert!(!f2_()); - #[cfg(target_pointer_width = "64")] - assert!(f2_()); - - #[cfg(not(target_pointer_width = "16"))] - assert_eq!(f3_(), 2); -} - -#[test] -fn cfg_match_debug_assertions() { - cfg_match! { - cfg(debug_assertions) => { - assert!(cfg!(debug_assertions)); - assert_eq!(4, 2+2); - } - _ => { - assert!(cfg!(not(debug_assertions))); - assert_eq!(10, 5+5); - } - } -} - -#[cfg(target_pointer_width = "64")] -#[test] -fn cfg_match_no_duplication_on_64() { - cfg_match! { - cfg(windows) => { - fn foo() {} - } - cfg(unix) => { - fn foo() {} - } - cfg(target_pointer_width = "64") => { - fn foo() {} - } - } - foo(); -} - -#[test] -fn cfg_match_options() { - cfg_match! { - cfg(test) => { - use core::option::Option as Option2; - fn works1() -> Option2 { Some(1) } - } - _ => { fn works1() -> Option { None } } - } - - cfg_match! { - cfg(feature = "foo") => { fn works2() -> bool { false } } - cfg(test) => { fn works2() -> bool { true } } - _ => { fn works2() -> bool { false } } - } - - cfg_match! { - cfg(feature = "foo") => { fn works3() -> bool { false } } - _ => { fn works3() -> bool { true } } - } - - cfg_match! { - cfg(test) => { - use core::option::Option as Option3; - fn works4() -> Option3 { Some(1) } - } - } - - cfg_match! { - cfg(feature = "foo") => { fn works5() -> bool { false } } - cfg(test) => { fn works5() -> bool { true } } - } - - assert!(works1().is_some()); - assert!(works2()); - assert!(works3()); - assert!(works4().is_some()); - assert!(works5()); -} - -#[test] -fn cfg_match_two_functions() { - cfg_match! { - cfg(target_pointer_width = "64") => { - fn foo1() {} - fn bar1() {} - } - _ => { - fn foo2() {} - fn bar2() {} - } - } - - #[cfg(target_pointer_width = "64")] - { - foo1(); - bar1(); - } - #[cfg(not(target_pointer_width = "64"))] - { - foo2(); - bar2(); - } -} diff --git a/library/core/tests/manually_drop.rs b/library/core/tests/manually_drop.rs deleted file mode 100644 index bbf444471ad2a..0000000000000 --- a/library/core/tests/manually_drop.rs +++ /dev/null @@ -1,29 +0,0 @@ -#![allow(undropped_manually_drops)] - -use core::mem::ManuallyDrop; - -#[test] -fn smoke() { - #[derive(Clone)] - struct TypeWithDrop; - impl Drop for TypeWithDrop { - fn drop(&mut self) { - unreachable!("Should not get dropped"); - } - } - - let x = ManuallyDrop::new(TypeWithDrop); - drop(x); - - // also test unsizing - let x: Box> = - Box::new(ManuallyDrop::new([TypeWithDrop, TypeWithDrop])); - drop(x); - - // test clone and clone_from implementations - let mut x = ManuallyDrop::new(TypeWithDrop); - let y = x.clone(); - x.clone_from(&y); - drop(x); - drop(y); -} diff --git a/library/core/tests/mem.rs b/library/core/tests/mem.rs deleted file mode 100644 index e388800f400df..0000000000000 --- a/library/core/tests/mem.rs +++ /dev/null @@ -1,793 +0,0 @@ -use core::mem::*; -use core::ptr; - -#[cfg(panic = "unwind")] -use std::rc::Rc; - -#[test] -fn size_of_basic() { - assert_eq!(size_of::(), 1); - assert_eq!(size_of::(), 2); - assert_eq!(size_of::(), 4); - assert_eq!(size_of::(), 8); -} - -#[test] -#[cfg(target_pointer_width = "16")] -fn size_of_16() { - assert_eq!(size_of::(), 2); - assert_eq!(size_of::<*const usize>(), 2); -} - -#[test] -#[cfg(target_pointer_width = "32")] -fn size_of_32() { - assert_eq!(size_of::(), 4); - assert_eq!(size_of::<*const usize>(), 4); -} - -#[test] -#[cfg(target_pointer_width = "64")] -fn size_of_64() { - assert_eq!(size_of::(), 8); - assert_eq!(size_of::<*const usize>(), 8); -} - -#[test] -fn size_of_val_basic() { - assert_eq!(size_of_val(&1u8), 1); - assert_eq!(size_of_val(&1u16), 2); - assert_eq!(size_of_val(&1u32), 4); - assert_eq!(size_of_val(&1u64), 8); -} - -#[test] -fn align_of_basic() { - assert_eq!(align_of::(), 1); - assert_eq!(align_of::(), 2); - assert_eq!(align_of::(), 4); -} - -#[test] -#[cfg(target_pointer_width = "16")] -fn align_of_16() { - assert_eq!(align_of::(), 2); - assert_eq!(align_of::<*const usize>(), 2); -} - -#[test] -#[cfg(target_pointer_width = "32")] -fn align_of_32() { - assert_eq!(align_of::(), 4); - assert_eq!(align_of::<*const usize>(), 4); -} - -#[test] -#[cfg(target_pointer_width = "64")] -fn align_of_64() { - assert_eq!(align_of::(), 8); - assert_eq!(align_of::<*const usize>(), 8); -} - -#[test] -fn align_of_val_basic() { - assert_eq!(align_of_val(&1u8), 1); - assert_eq!(align_of_val(&1u16), 2); - assert_eq!(align_of_val(&1u32), 4); -} - -#[test] -fn align_of_val_raw_packed() { - #[repr(C, packed)] - struct B { - f: [u32], - } - let storage = [0u8; 4]; - let b: *const B = ptr::from_raw_parts(storage.as_ptr().cast(), 1); - assert_eq!(unsafe { align_of_val_raw(b) }, 1); - - const ALIGN_OF_VAL_RAW: usize = { - let storage = [0u8; 4]; - let b: *const B = ptr::from_raw_parts(storage.as_ptr().cast(), 1); - unsafe { align_of_val_raw(b) } - }; - assert_eq!(ALIGN_OF_VAL_RAW, 1); -} - -#[test] -fn test_swap() { - let mut x = 31337; - let mut y = 42; - swap(&mut x, &mut y); - assert_eq!(x, 42); - assert_eq!(y, 31337); -} - -#[test] -fn test_replace() { - let mut x = Some("test".to_string()); - let y = replace(&mut x, None); - assert!(x.is_none()); - assert!(y.is_some()); -} - -#[test] -fn test_transmute_copy() { - assert_eq!(1, unsafe { transmute_copy(&1) }); -} - -#[test] -fn test_transmute_copy_shrink() { - assert_eq!(0_u8, unsafe { transmute_copy(&0_u64) }); -} - -#[test] -fn test_transmute_copy_unaligned() { - #[repr(C)] - #[derive(Default)] - struct Unaligned { - a: u8, - b: [u8; 8], - } - - let u = Unaligned::default(); - assert_eq!(0_u64, unsafe { transmute_copy(&u.b) }); -} - -#[test] -#[cfg(panic = "unwind")] -fn test_transmute_copy_grow_panics() { - use std::panic; - - let err = panic::catch_unwind(panic::AssertUnwindSafe(|| unsafe { - let _unused: u64 = transmute_copy(&1_u8); - })); - - match err { - Ok(_) => unreachable!(), - Err(payload) => { - payload - .downcast::<&'static str>() - .and_then(|s| { - if *s == "cannot transmute_copy if Dst is larger than Src" { - Ok(s) - } else { - Err(s) - } - }) - .unwrap_or_else(|p| panic::resume_unwind(p)); - } - } -} - -#[test] -#[allow(dead_code)] -fn test_discriminant_send_sync() { - enum Regular { - A, - B(i32), - } - enum NotSendSync { - A(*const i32), - } - - fn is_send_sync() {} - - is_send_sync::>(); - is_send_sync::>(); -} - -#[test] -fn assume_init_good() { - const TRUE: bool = unsafe { MaybeUninit::::new(true).assume_init() }; - - assert!(TRUE); -} - -#[test] -fn uninit_array_assume_init() { - let mut array = [MaybeUninit::::uninit(); 5]; - array[0].write(3); - array[1].write(1); - array[2].write(4); - array[3].write(1); - array[4].write(5); - - let array = unsafe { array.transpose().assume_init() }; - - assert_eq!(array, [3, 1, 4, 1, 5]); - - let [] = unsafe { [MaybeUninit::::uninit(); 0].transpose().assume_init() }; -} - -#[test] -fn uninit_write_slice() { - let mut dst = [MaybeUninit::new(255); 64]; - let src = [0; 64]; - - assert_eq!(MaybeUninit::copy_from_slice(&mut dst, &src), &src); -} - -#[test] -#[should_panic(expected = "source slice length (32) does not match destination slice length (64)")] -fn uninit_write_slice_panic_lt() { - let mut dst = [MaybeUninit::uninit(); 64]; - let src = [0; 32]; - - MaybeUninit::copy_from_slice(&mut dst, &src); -} - -#[test] -#[should_panic(expected = "source slice length (128) does not match destination slice length (64)")] -fn uninit_write_slice_panic_gt() { - let mut dst = [MaybeUninit::uninit(); 64]; - let src = [0; 128]; - - MaybeUninit::copy_from_slice(&mut dst, &src); -} - -#[test] -fn uninit_clone_from_slice() { - let mut dst = [MaybeUninit::new(255); 64]; - let src = [0; 64]; - - assert_eq!(MaybeUninit::clone_from_slice(&mut dst, &src), &src); -} - -#[test] -#[should_panic(expected = "destination and source slices have different lengths")] -fn uninit_write_slice_cloned_panic_lt() { - let mut dst = [MaybeUninit::uninit(); 64]; - let src = [0; 32]; - - MaybeUninit::clone_from_slice(&mut dst, &src); -} - -#[test] -#[should_panic(expected = "destination and source slices have different lengths")] -fn uninit_write_slice_cloned_panic_gt() { - let mut dst = [MaybeUninit::uninit(); 64]; - let src = [0; 128]; - - MaybeUninit::clone_from_slice(&mut dst, &src); -} - -#[test] -#[cfg(panic = "unwind")] -fn uninit_write_slice_cloned_mid_panic() { - use std::panic; - - enum IncrementOrPanic { - Increment(Rc<()>), - ExpectedPanic, - UnexpectedPanic, - } - - impl Clone for IncrementOrPanic { - fn clone(&self) -> Self { - match self { - Self::Increment(rc) => Self::Increment(rc.clone()), - Self::ExpectedPanic => panic!("expected panic on clone"), - Self::UnexpectedPanic => panic!("unexpected panic on clone"), - } - } - } - - let rc = Rc::new(()); - - let mut dst = [ - MaybeUninit::uninit(), - MaybeUninit::uninit(), - MaybeUninit::uninit(), - MaybeUninit::uninit(), - ]; - - let src = [ - IncrementOrPanic::Increment(rc.clone()), - IncrementOrPanic::Increment(rc.clone()), - IncrementOrPanic::ExpectedPanic, - IncrementOrPanic::UnexpectedPanic, - ]; - - let err = panic::catch_unwind(panic::AssertUnwindSafe(|| { - MaybeUninit::clone_from_slice(&mut dst, &src); - })); - - drop(src); - - match err { - Ok(_) => unreachable!(), - Err(payload) => { - payload - .downcast::<&'static str>() - .and_then(|s| if *s == "expected panic on clone" { Ok(s) } else { Err(s) }) - .unwrap_or_else(|p| panic::resume_unwind(p)); - - assert_eq!(Rc::strong_count(&rc), 1) - } - } -} - -#[derive(Clone)] -struct Bomb; - -impl Drop for Bomb { - fn drop(&mut self) { - panic!("dropped a bomb! kaboom!") - } -} - -#[test] -fn uninit_write_slice_cloned_no_drop() { - let mut dst = [MaybeUninit::uninit()]; - let src = [Bomb]; - - MaybeUninit::clone_from_slice(&mut dst, &src); - - forget(src); -} - -#[test] -fn uninit_fill() { - let mut dst = [MaybeUninit::new(255); 64]; - let expect = [0; 64]; - - assert_eq!(MaybeUninit::fill(&mut dst, 0), &expect); -} - -#[cfg(panic = "unwind")] -struct CloneUntilPanic { - limit: usize, - rc: Rc<()>, -} - -#[cfg(panic = "unwind")] -impl Clone for CloneUntilPanic { - fn clone(&self) -> Self { - if Rc::strong_count(&self.rc) >= self.limit { - panic!("expected panic on clone"); - } - Self { limit: self.limit, rc: self.rc.clone() } - } -} - -#[test] -#[cfg(panic = "unwind")] -fn uninit_fill_clone_panic_drop() { - use std::panic; - - let rc = Rc::new(()); - - let mut dst = [MaybeUninit::uninit(), MaybeUninit::uninit(), MaybeUninit::uninit()]; - - let src = CloneUntilPanic { limit: 3, rc: rc.clone() }; - let err = panic::catch_unwind(panic::AssertUnwindSafe(|| { - MaybeUninit::fill(&mut dst, src); - })); - - match err { - Ok(_) => unreachable!(), - Err(payload) => { - payload - .downcast::<&'static str>() - .and_then(|s| if *s == "expected panic on clone" { Ok(s) } else { Err(s) }) - .unwrap_or_else(|p| panic::resume_unwind(p)); - assert_eq!(Rc::strong_count(&rc), 1) - } - } -} - -#[test] -#[cfg(panic = "unwind")] -fn uninit_fill_clone_no_drop_clones() { - let mut dst = [MaybeUninit::uninit(), MaybeUninit::uninit(), MaybeUninit::uninit()]; - - MaybeUninit::fill(&mut dst, Bomb); -} - -#[test] -fn uninit_fill_with() { - let mut dst = [MaybeUninit::new(255); 64]; - let expect = [0; 64]; - - assert_eq!(MaybeUninit::fill_with(&mut dst, || 0), &expect); -} - -#[test] -#[cfg(panic = "unwind")] -fn uninit_fill_with_mid_panic() { - use std::panic; - - let rc = Rc::new(()); - - let mut dst = [MaybeUninit::uninit(), MaybeUninit::uninit(), MaybeUninit::uninit()]; - - let src = CloneUntilPanic { limit: 3, rc: rc.clone() }; - let err = panic::catch_unwind(panic::AssertUnwindSafe(|| { - MaybeUninit::fill_with(&mut dst, || src.clone()); - })); - - drop(src); - - match err { - Ok(_) => unreachable!(), - Err(payload) => { - payload - .downcast::<&'static str>() - .and_then(|s| if *s == "expected panic on clone" { Ok(s) } else { Err(s) }) - .unwrap_or_else(|p| panic::resume_unwind(p)); - - assert_eq!(Rc::strong_count(&rc), 1) - } - } -} - -#[test] -#[cfg(panic = "unwind")] -fn uninit_fill_with_no_drop() { - let mut dst = [MaybeUninit::uninit()]; - let src = Bomb; - - MaybeUninit::fill_with(&mut dst, || src.clone()); - - forget(src); -} - -#[test] -fn uninit_fill_from() { - let mut dst = [MaybeUninit::new(255); 64]; - let src = [0; 64]; - - let (initted, remainder) = MaybeUninit::fill_from(&mut dst, src.into_iter()); - assert_eq!(initted, &src); - assert_eq!(remainder.len(), 0); -} - -#[test] -fn uninit_fill_from_partial() { - let mut dst = [MaybeUninit::new(255); 64]; - let src = [0; 48]; - - let (initted, remainder) = MaybeUninit::fill_from(&mut dst, src.into_iter()); - assert_eq!(initted, &src); - assert_eq!(remainder.len(), 16); -} - -#[test] -fn uninit_over_fill() { - let mut dst = [MaybeUninit::new(255); 64]; - let src = [0; 72]; - - let (initted, remainder) = MaybeUninit::fill_from(&mut dst, src.into_iter()); - assert_eq!(initted, &src[0..64]); - assert_eq!(remainder.len(), 0); -} - -#[test] -fn uninit_empty_fill() { - let mut dst = [MaybeUninit::new(255); 64]; - let src = [0; 0]; - - let (initted, remainder) = MaybeUninit::fill_from(&mut dst, src.into_iter()); - assert_eq!(initted, &src[0..0]); - assert_eq!(remainder.len(), 64); -} - -#[test] -#[cfg(panic = "unwind")] -fn uninit_fill_from_mid_panic() { - use std::panic; - - struct IterUntilPanic { - limit: usize, - rc: Rc<()>, - } - - impl Iterator for IterUntilPanic { - type Item = Rc<()>; - fn next(&mut self) -> Option { - if Rc::strong_count(&self.rc) >= self.limit { - panic!("expected panic on next"); - } - Some(self.rc.clone()) - } - } - - let rc = Rc::new(()); - - let mut dst = [ - MaybeUninit::uninit(), - MaybeUninit::uninit(), - MaybeUninit::uninit(), - MaybeUninit::uninit(), - ]; - - let src = IterUntilPanic { limit: 3, rc: rc.clone() }; - - let err = panic::catch_unwind(panic::AssertUnwindSafe(|| { - MaybeUninit::fill_from(&mut dst, src); - })); - - match err { - Ok(_) => unreachable!(), - Err(payload) => { - payload - .downcast::<&'static str>() - .and_then(|s| if *s == "expected panic on next" { Ok(s) } else { Err(s) }) - .unwrap_or_else(|p| panic::resume_unwind(p)); - - assert_eq!(Rc::strong_count(&rc), 1) - } - } -} - -#[test] -#[cfg(panic = "unwind")] -fn uninit_fill_from_no_drop() { - let mut dst = [MaybeUninit::uninit()]; - let src = [Bomb]; - - MaybeUninit::fill_from(&mut dst, src.iter()); - - forget(src); -} - -#[test] -fn uninit_const_assume_init_read() { - const FOO: u32 = unsafe { MaybeUninit::new(42).assume_init_read() }; - assert_eq!(FOO, 42); -} - -#[test] -fn const_maybe_uninit() { - use std::ptr; - - #[derive(Debug, PartialEq)] - struct Foo { - x: u8, - y: u8, - } - - const FIELD_BY_FIELD: Foo = unsafe { - let mut val = MaybeUninit::uninit(); - init_y(&mut val); // order shouldn't matter - init_x(&mut val); - val.assume_init() - }; - - const fn init_x(foo: &mut MaybeUninit) { - unsafe { - *ptr::addr_of_mut!((*foo.as_mut_ptr()).x) = 1; - } - } - - const fn init_y(foo: &mut MaybeUninit) { - unsafe { - *ptr::addr_of_mut!((*foo.as_mut_ptr()).y) = 2; - } - } - - assert_eq!(FIELD_BY_FIELD, Foo { x: 1, y: 2 }); -} - -#[test] -fn offset_of() { - #[repr(C)] - struct Foo { - x: u8, - y: u16, - z: Bar, - } - - #[repr(C)] - struct Bar(u8, u8); - - assert_eq!(offset_of!(Foo, x), 0); - assert_eq!(offset_of!(Foo, y), 2); - assert_eq!(offset_of!(Foo, z.0), 4); - assert_eq!(offset_of!(Foo, z.1), 5); - - // Layout of tuples is unstable - assert!(offset_of!((u8, u16), 0) <= size_of::<(u8, u16)>() - 1); - assert!(offset_of!((u8, u16), 1) <= size_of::<(u8, u16)>() - 2); - - #[repr(C)] - struct Generic { - x: u8, - y: u32, - z: T, - } - - trait Trait {} - - // Ensure that this type of generics works - fn offs_of_z() -> usize { - offset_of!(Generic, z) - } - - assert_eq!(offset_of!(Generic, z), 8); - assert_eq!(offs_of_z::(), 8); - - // Ensure that it works with the implicit lifetime in `Box`. - assert_eq!(offset_of!(Generic>, z), 8); -} - -#[test] -fn offset_of_union() { - #[repr(C)] - union Foo { - x: u8, - y: u16, - z: Bar, - } - - #[repr(C)] - #[derive(Copy, Clone)] - struct Bar(u8, u8); - - assert_eq!(offset_of!(Foo, x), 0); - assert_eq!(offset_of!(Foo, y), 0); - assert_eq!(offset_of!(Foo, z.0), 0); - assert_eq!(offset_of!(Foo, z.1), 1); -} - -#[test] -fn offset_of_dst() { - #[repr(C)] - struct Alpha { - x: u8, - y: u16, - z: [u8], - } - - trait Trait {} - - #[repr(C)] - struct Beta { - x: u8, - y: u16, - z: dyn Trait, - } - - extern "C" { - type Extern; - } - - #[repr(C)] - struct Gamma { - x: u8, - y: u16, - z: Extern, - } - - assert_eq!(offset_of!(Alpha, x), 0); - assert_eq!(offset_of!(Alpha, y), 2); - - assert_eq!(offset_of!(Beta, x), 0); - assert_eq!(offset_of!(Beta, y), 2); - - assert_eq!(offset_of!(Gamma, x), 0); - assert_eq!(offset_of!(Gamma, y), 2); -} - -#[test] -fn offset_of_packed() { - #[repr(C, packed)] - struct Foo { - x: u8, - y: u16, - } - - assert_eq!(offset_of!(Foo, x), 0); - assert_eq!(offset_of!(Foo, y), 1); -} - -#[test] -fn offset_of_projection() { - #[repr(C)] - struct Foo { - x: u8, - y: u16, - } - - trait Projector { - type Type; - } - - impl Projector for () { - type Type = Foo; - } - - assert_eq!(offset_of!(<() as Projector>::Type, x), 0); - assert_eq!(offset_of!(<() as Projector>::Type, y), 2); -} - -#[test] -fn offset_of_alias() { - #[repr(C)] - struct Foo { - x: u8, - y: u16, - } - - type Bar = Foo; - - assert_eq!(offset_of!(Bar, x), 0); - assert_eq!(offset_of!(Bar, y), 2); -} - -#[test] -fn const_offset_of() { - #[repr(C)] - struct Foo { - x: u8, - y: u16, - } - - const X_OFFSET: usize = offset_of!(Foo, x); - const Y_OFFSET: usize = offset_of!(Foo, y); - - assert_eq!(X_OFFSET, 0); - assert_eq!(Y_OFFSET, 2); -} - -#[test] -fn offset_of_without_const_promotion() { - #[repr(C)] - struct Foo { - x: u8, - y: u16, - _scp: SuppressConstPromotion, - } - - // Normally, offset_of is always const promoted. - // The generic parameter prevents this from happening. - // This is needed to test the codegen impl of offset_of - fn inner() { - assert_eq!(offset_of!(Foo, x), 0); - assert_eq!(offset_of!(Foo, y), 2); - } - - inner::<()>(); -} - -#[test] -fn offset_of_addr() { - #[repr(C)] - struct Foo { - x: u8, - y: u16, - z: Bar, - } - - #[repr(C)] - struct Bar(u8, u8); - - let base = Foo { x: 0, y: 0, z: Bar(0, 0) }; - - assert_eq!(ptr::addr_of!(base).addr() + offset_of!(Foo, x), ptr::addr_of!(base.x).addr()); - assert_eq!(ptr::addr_of!(base).addr() + offset_of!(Foo, y), ptr::addr_of!(base.y).addr()); - assert_eq!(ptr::addr_of!(base).addr() + offset_of!(Foo, z.0), ptr::addr_of!(base.z.0).addr()); - assert_eq!(ptr::addr_of!(base).addr() + offset_of!(Foo, z.1), ptr::addr_of!(base.z.1).addr()); -} - -#[test] -fn const_maybe_uninit_zeroed() { - // Sanity check for `MaybeUninit::zeroed` in a realistic const situation (plugin array term) - #[repr(C)] - struct Foo { - a: Option<&'static str>, - b: Bar, - c: f32, - d: *const u8, - } - #[repr(C)] - struct Bar(usize); - struct FooPtr(*const Foo); - unsafe impl Sync for FooPtr {} - - static UNINIT: FooPtr = FooPtr([unsafe { MaybeUninit::zeroed().assume_init() }].as_ptr()); - const SIZE: usize = size_of::(); - - assert_eq!(unsafe { (*UNINIT.0.cast::<[[u8; SIZE]; 1]>())[0] }, [0u8; SIZE]); -} diff --git a/library/core/tests/net/ip_addr.rs b/library/core/tests/net/ip_addr.rs deleted file mode 100644 index f9b351ef1980b..0000000000000 --- a/library/core/tests/net/ip_addr.rs +++ /dev/null @@ -1,1059 +0,0 @@ -use super::{sa4, sa6}; -use core::net::{ - IpAddr, Ipv4Addr, Ipv6Addr, Ipv6MulticastScope, SocketAddr, SocketAddrV4, SocketAddrV6, -}; -use core::str::FromStr; - -#[test] -fn test_from_str_ipv4() { - assert_eq!(Ok(Ipv4Addr::new(127, 0, 0, 1)), "127.0.0.1".parse()); - assert_eq!(Ok(Ipv4Addr::new(255, 255, 255, 255)), "255.255.255.255".parse()); - assert_eq!(Ok(Ipv4Addr::new(0, 0, 0, 0)), "0.0.0.0".parse()); - - // out of range - let none: Option = "256.0.0.1".parse().ok(); - assert_eq!(None, none); - // too short - let none: Option = "255.0.0".parse().ok(); - assert_eq!(None, none); - // too long - let none: Option = "255.0.0.1.2".parse().ok(); - assert_eq!(None, none); - // no number between dots - let none: Option = "255.0..1".parse().ok(); - assert_eq!(None, none); - // octal - let none: Option = "255.0.0.01".parse().ok(); - assert_eq!(None, none); - // octal zero - let none: Option = "255.0.0.00".parse().ok(); - assert_eq!(None, none); - let none: Option = "255.0.00.0".parse().ok(); - assert_eq!(None, none); -} - -#[test] -fn test_from_str_ipv6() { - assert_eq!(Ok(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0)), "0:0:0:0:0:0:0:0".parse()); - assert_eq!(Ok(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1)), "0:0:0:0:0:0:0:1".parse()); - - assert_eq!(Ok(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1)), "::1".parse()); - assert_eq!(Ok(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0)), "::".parse()); - - assert_eq!(Ok(Ipv6Addr::new(0x2a02, 0x6b8, 0, 0, 0, 0, 0x11, 0x11)), "2a02:6b8::11:11".parse()); - - // too long group - let none: Option = "::00000".parse().ok(); - assert_eq!(None, none); - // too short - let none: Option = "1:2:3:4:5:6:7".parse().ok(); - assert_eq!(None, none); - // too long - let none: Option = "1:2:3:4:5:6:7:8:9".parse().ok(); - assert_eq!(None, none); - // triple colon - let none: Option = "1:2:::6:7:8".parse().ok(); - assert_eq!(None, none); - // two double colons - let none: Option = "1:2::6::8".parse().ok(); - assert_eq!(None, none); - // `::` indicating zero groups of zeros - let none: Option = "1:2:3:4::5:6:7:8".parse().ok(); - assert_eq!(None, none); -} - -#[test] -fn test_from_str_ipv4_in_ipv6() { - assert_eq!(Ok(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 49152, 545)), "::192.0.2.33".parse()); - assert_eq!(Ok(Ipv6Addr::new(0, 0, 0, 0, 0, 0xFFFF, 49152, 545)), "::FFFF:192.0.2.33".parse()); - assert_eq!( - Ok(Ipv6Addr::new(0x64, 0xff9b, 0, 0, 0, 0, 49152, 545)), - "64:ff9b::192.0.2.33".parse() - ); - assert_eq!( - Ok(Ipv6Addr::new(0x2001, 0xdb8, 0x122, 0xc000, 0x2, 0x2100, 49152, 545)), - "2001:db8:122:c000:2:2100:192.0.2.33".parse() - ); - - // colon after v4 - let none: Option = "::127.0.0.1:".parse().ok(); - assert_eq!(None, none); - // not enough groups - let none: Option = "1:2:3:4:5:127.0.0.1".parse().ok(); - assert_eq!(None, none); - // too many groups - let none: Option = "1:2:3:4:5:6:7:127.0.0.1".parse().ok(); - assert_eq!(None, none); -} - -#[test] -fn test_from_str_socket_addr() { - assert_eq!(Ok(sa4(Ipv4Addr::new(77, 88, 21, 11), 80)), "77.88.21.11:80".parse()); - assert_eq!(Ok(SocketAddrV4::new(Ipv4Addr::new(77, 88, 21, 11), 80)), "77.88.21.11:80".parse()); - assert_eq!( - Ok(sa6(Ipv6Addr::new(0x2a02, 0x6b8, 0, 1, 0, 0, 0, 1), 53)), - "[2a02:6b8:0:1::1]:53".parse() - ); - assert_eq!( - Ok(SocketAddrV6::new(Ipv6Addr::new(0x2a02, 0x6b8, 0, 1, 0, 0, 0, 1), 53, 0, 0)), - "[2a02:6b8:0:1::1]:53".parse() - ); - assert_eq!(Ok(sa6(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0x7F00, 1), 22)), "[::127.0.0.1]:22".parse()); - assert_eq!( - Ok(SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0x7F00, 1), 22, 0, 0)), - "[::127.0.0.1]:22".parse() - ); - - // without port - let none: Option = "127.0.0.1".parse().ok(); - assert_eq!(None, none); - // without port - let none: Option = "127.0.0.1:".parse().ok(); - assert_eq!(None, none); - // wrong brackets around v4 - let none: Option = "[127.0.0.1]:22".parse().ok(); - assert_eq!(None, none); - // port out of range - let none: Option = "127.0.0.1:123456".parse().ok(); - assert_eq!(None, none); -} - -#[test] -fn ipv4_addr_to_string() { - assert_eq!(Ipv4Addr::new(127, 0, 0, 1).to_string(), "127.0.0.1"); - // Short address - assert_eq!(Ipv4Addr::new(1, 1, 1, 1).to_string(), "1.1.1.1"); - // Long address - assert_eq!(Ipv4Addr::new(127, 127, 127, 127).to_string(), "127.127.127.127"); - - // Test padding - assert_eq!(format!("{:16}", Ipv4Addr::new(1, 1, 1, 1)), "1.1.1.1 "); - assert_eq!(format!("{:>16}", Ipv4Addr::new(1, 1, 1, 1)), " 1.1.1.1"); -} - -#[test] -fn ipv6_addr_to_string() { - // ipv4-mapped address - let a1 = Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc000, 0x280); - assert_eq!(a1.to_string(), "::ffff:192.0.2.128"); - - // ipv4-compatible address - let a1 = Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0xc000, 0x280); - assert_eq!(a1.to_string(), "::c000:280"); - - // v6 address with no zero segments - assert_eq!(Ipv6Addr::new(8, 9, 10, 11, 12, 13, 14, 15).to_string(), "8:9:a:b:c:d:e:f"); - - // longest possible IPv6 length - assert_eq!( - Ipv6Addr::new(0x1111, 0x2222, 0x3333, 0x4444, 0x5555, 0x6666, 0x7777, 0x8888).to_string(), - "1111:2222:3333:4444:5555:6666:7777:8888" - ); - // padding - assert_eq!(format!("{:20}", Ipv6Addr::new(1, 2, 3, 4, 5, 6, 7, 8)), "1:2:3:4:5:6:7:8 "); - assert_eq!(format!("{:>20}", Ipv6Addr::new(1, 2, 3, 4, 5, 6, 7, 8)), " 1:2:3:4:5:6:7:8"); - - // reduce a single run of zeros - assert_eq!( - "ae::ffff:102:304", - Ipv6Addr::new(0xae, 0, 0, 0, 0, 0xffff, 0x0102, 0x0304).to_string() - ); - - // don't reduce just a single zero segment - assert_eq!("1:2:3:4:5:6:0:8", Ipv6Addr::new(1, 2, 3, 4, 5, 6, 0, 8).to_string()); - - // 'any' address - assert_eq!("::", Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0).to_string()); - - // loopback address - assert_eq!("::1", Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1).to_string()); - - // ends in zeros - assert_eq!("1::", Ipv6Addr::new(1, 0, 0, 0, 0, 0, 0, 0).to_string()); - - // two runs of zeros, second one is longer - assert_eq!("1:0:0:4::8", Ipv6Addr::new(1, 0, 0, 4, 0, 0, 0, 8).to_string()); - - // two runs of zeros, equal length - assert_eq!("1::4:5:0:0:8", Ipv6Addr::new(1, 0, 0, 4, 5, 0, 0, 8).to_string()); - - // don't prefix `0x` to each segment in `dbg!`. - assert_eq!("1::4:5:0:0:8", &format!("{:#?}", Ipv6Addr::new(1, 0, 0, 4, 5, 0, 0, 8))); -} - -#[test] -fn ipv4_to_ipv6() { - assert_eq!( - Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0x1234, 0x5678), - Ipv4Addr::new(0x12, 0x34, 0x56, 0x78).to_ipv6_mapped() - ); - assert_eq!( - Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0x1234, 0x5678), - Ipv4Addr::new(0x12, 0x34, 0x56, 0x78).to_ipv6_compatible() - ); -} - -#[test] -fn ipv6_to_ipv4_mapped() { - assert_eq!( - Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0x1234, 0x5678).to_ipv4_mapped(), - Some(Ipv4Addr::new(0x12, 0x34, 0x56, 0x78)) - ); - assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0x1234, 0x5678).to_ipv4_mapped(), None); -} - -#[test] -fn ipv6_to_ipv4() { - assert_eq!( - Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0x1234, 0x5678).to_ipv4(), - Some(Ipv4Addr::new(0x12, 0x34, 0x56, 0x78)) - ); - assert_eq!( - Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0x1234, 0x5678).to_ipv4(), - Some(Ipv4Addr::new(0x12, 0x34, 0x56, 0x78)) - ); - assert_eq!(Ipv6Addr::new(0, 0, 1, 0, 0, 0, 0x1234, 0x5678).to_ipv4(), None); -} - -#[test] -fn ip_properties() { - macro_rules! ip { - ($s:expr) => { - IpAddr::from_str($s).unwrap() - }; - } - - macro_rules! check { - ($s:expr) => { - check!($s, 0); - }; - - ($s:expr, $mask:expr) => {{ - let unspec: u8 = 1 << 0; - let loopback: u8 = 1 << 1; - let global: u8 = 1 << 2; - let multicast: u8 = 1 << 3; - let doc: u8 = 1 << 4; - let benchmarking: u8 = 1 << 5; - - if ($mask & unspec) == unspec { - assert!(ip!($s).is_unspecified()); - } else { - assert!(!ip!($s).is_unspecified()); - } - - if ($mask & loopback) == loopback { - assert!(ip!($s).is_loopback()); - } else { - assert!(!ip!($s).is_loopback()); - } - - if ($mask & global) == global { - assert!(ip!($s).is_global()); - } else { - assert!(!ip!($s).is_global()); - } - - if ($mask & multicast) == multicast { - assert!(ip!($s).is_multicast()); - } else { - assert!(!ip!($s).is_multicast()); - } - - if ($mask & doc) == doc { - assert!(ip!($s).is_documentation()); - } else { - assert!(!ip!($s).is_documentation()); - } - - if ($mask & benchmarking) == benchmarking { - assert!(ip!($s).is_benchmarking()); - } else { - assert!(!ip!($s).is_benchmarking()); - } - }}; - } - - let unspec: u8 = 1 << 0; - let loopback: u8 = 1 << 1; - let global: u8 = 1 << 2; - let multicast: u8 = 1 << 3; - let doc: u8 = 1 << 4; - let benchmarking: u8 = 1 << 5; - - check!("0.0.0.0", unspec); - check!("0.0.0.1"); - check!("0.1.0.0"); - check!("10.9.8.7"); - check!("127.1.2.3", loopback); - check!("172.31.254.253"); - check!("169.254.253.242"); - check!("192.0.2.183", doc); - check!("192.1.2.183", global); - check!("192.168.254.253"); - check!("198.51.100.0", doc); - check!("203.0.113.0", doc); - check!("203.2.113.0", global); - check!("224.0.0.0", global | multicast); - check!("239.255.255.255", global | multicast); - check!("255.255.255.255"); - // make sure benchmarking addresses are not global - check!("198.18.0.0", benchmarking); - check!("198.18.54.2", benchmarking); - check!("198.19.255.255", benchmarking); - // make sure addresses reserved for protocol assignment are not global - check!("192.0.0.0"); - check!("192.0.0.255"); - check!("192.0.0.100"); - // make sure reserved addresses are not global - check!("240.0.0.0"); - check!("251.54.1.76"); - check!("254.255.255.255"); - // make sure shared addresses are not global - check!("100.64.0.0"); - check!("100.127.255.255"); - check!("100.100.100.0"); - - check!("::", unspec); - check!("::1", loopback); - check!("::2", global); - check!("1::", global); - check!("fc00::"); - check!("fdff:ffff::"); - check!("fe80:ffff::"); - check!("febf:ffff::"); - check!("fec0::", global); - check!("ff01::", global | multicast); - check!("ff02::", global | multicast); - check!("ff03::", global | multicast); - check!("ff04::", global | multicast); - check!("ff05::", global | multicast); - check!("ff08::", global | multicast); - check!("ff0e::", global | multicast); - check!("2001:db8:85a3::8a2e:370:7334", doc); - check!("2001:2::ac32:23ff:21", benchmarking); - check!("102:304:506:708:90a:b0c:d0e:f10", global); -} - -#[test] -fn ipv4_properties() { - macro_rules! ip { - ($s:expr) => { - Ipv4Addr::from_str($s).unwrap() - }; - } - - macro_rules! check { - ($s:expr) => { - check!($s, 0); - }; - - ($s:expr, $mask:expr) => {{ - let unspec: u16 = 1 << 0; - let loopback: u16 = 1 << 1; - let private: u16 = 1 << 2; - let link_local: u16 = 1 << 3; - let global: u16 = 1 << 4; - let multicast: u16 = 1 << 5; - let broadcast: u16 = 1 << 6; - let documentation: u16 = 1 << 7; - let benchmarking: u16 = 1 << 8; - let reserved: u16 = 1 << 10; - let shared: u16 = 1 << 11; - - if ($mask & unspec) == unspec { - assert!(ip!($s).is_unspecified()); - } else { - assert!(!ip!($s).is_unspecified()); - } - - if ($mask & loopback) == loopback { - assert!(ip!($s).is_loopback()); - } else { - assert!(!ip!($s).is_loopback()); - } - - if ($mask & private) == private { - assert!(ip!($s).is_private()); - } else { - assert!(!ip!($s).is_private()); - } - - if ($mask & link_local) == link_local { - assert!(ip!($s).is_link_local()); - } else { - assert!(!ip!($s).is_link_local()); - } - - if ($mask & global) == global { - assert!(ip!($s).is_global()); - } else { - assert!(!ip!($s).is_global()); - } - - if ($mask & multicast) == multicast { - assert!(ip!($s).is_multicast()); - } else { - assert!(!ip!($s).is_multicast()); - } - - if ($mask & broadcast) == broadcast { - assert!(ip!($s).is_broadcast()); - } else { - assert!(!ip!($s).is_broadcast()); - } - - if ($mask & documentation) == documentation { - assert!(ip!($s).is_documentation()); - } else { - assert!(!ip!($s).is_documentation()); - } - - if ($mask & benchmarking) == benchmarking { - assert!(ip!($s).is_benchmarking()); - } else { - assert!(!ip!($s).is_benchmarking()); - } - - if ($mask & reserved) == reserved { - assert!(ip!($s).is_reserved()); - } else { - assert!(!ip!($s).is_reserved()); - } - - if ($mask & shared) == shared { - assert!(ip!($s).is_shared()); - } else { - assert!(!ip!($s).is_shared()); - } - }}; - } - - let unspec: u16 = 1 << 0; - let loopback: u16 = 1 << 1; - let private: u16 = 1 << 2; - let link_local: u16 = 1 << 3; - let global: u16 = 1 << 4; - let multicast: u16 = 1 << 5; - let broadcast: u16 = 1 << 6; - let documentation: u16 = 1 << 7; - let benchmarking: u16 = 1 << 8; - let reserved: u16 = 1 << 10; - let shared: u16 = 1 << 11; - - check!("0.0.0.0", unspec); - check!("0.0.0.1"); - check!("0.1.0.0"); - check!("10.9.8.7", private); - check!("127.1.2.3", loopback); - check!("172.31.254.253", private); - check!("169.254.253.242", link_local); - check!("192.0.2.183", documentation); - check!("192.1.2.183", global); - check!("192.168.254.253", private); - check!("198.51.100.0", documentation); - check!("203.0.113.0", documentation); - check!("203.2.113.0", global); - check!("224.0.0.0", global | multicast); - check!("239.255.255.255", global | multicast); - check!("255.255.255.255", broadcast); - check!("198.18.0.0", benchmarking); - check!("198.18.54.2", benchmarking); - check!("198.19.255.255", benchmarking); - check!("192.0.0.0"); - check!("192.0.0.8"); - check!("192.0.0.9", global); - check!("192.0.0.10", global); - check!("192.0.0.11"); - check!("192.0.0.255"); - check!("192.0.0.100"); - check!("240.0.0.0", reserved); - check!("251.54.1.76", reserved); - check!("254.255.255.255", reserved); - check!("100.64.0.0", shared); - check!("100.127.255.255", shared); - check!("100.100.100.0", shared); -} - -#[test] -fn ipv6_properties() { - macro_rules! ip { - ($s:expr) => { - Ipv6Addr::from_str($s).unwrap() - }; - } - - macro_rules! check { - ($s:expr, &[$($octet:expr),*]) => { - check!($s, &[$($octet),*], 0); - }; - - ($s:expr, &[$($octet:expr),*], $mask:expr) => { - assert_eq!($s, ip!($s).to_string()); - let octets = &[$($octet),*]; - assert_eq!(&ip!($s).octets(), octets); - assert_eq!(Ipv6Addr::from(*octets), ip!($s)); - - let unspecified: u32 = 1 << 0; - let loopback: u32 = 1 << 1; - let unique_local: u32 = 1 << 2; - let global: u32 = 1 << 3; - let unicast_link_local: u32 = 1 << 4; - let unicast_global: u32 = 1 << 7; - let documentation: u32 = 1 << 8; - let benchmarking: u32 = 1 << 16; - let multicast_interface_local: u32 = 1 << 9; - let multicast_link_local: u32 = 1 << 10; - let multicast_realm_local: u32 = 1 << 11; - let multicast_admin_local: u32 = 1 << 12; - let multicast_site_local: u32 = 1 << 13; - let multicast_organization_local: u32 = 1 << 14; - let multicast_global: u32 = 1 << 15; - let multicast: u32 = multicast_interface_local - | multicast_admin_local - | multicast_global - | multicast_link_local - | multicast_realm_local - | multicast_site_local - | multicast_organization_local; - let ipv4_mapped: u32 = 1 << 17; - - if ($mask & unspecified) == unspecified { - assert!(ip!($s).is_unspecified()); - } else { - assert!(!ip!($s).is_unspecified()); - } - if ($mask & loopback) == loopback { - assert!(ip!($s).is_loopback()); - } else { - assert!(!ip!($s).is_loopback()); - } - if ($mask & unique_local) == unique_local { - assert!(ip!($s).is_unique_local()); - } else { - assert!(!ip!($s).is_unique_local()); - } - if ($mask & global) == global { - assert!(ip!($s).is_global()); - } else { - assert!(!ip!($s).is_global()); - } - if ($mask & unicast_link_local) == unicast_link_local { - assert!(ip!($s).is_unicast_link_local()); - } else { - assert!(!ip!($s).is_unicast_link_local()); - } - if ($mask & unicast_global) == unicast_global { - assert!(ip!($s).is_unicast_global()); - } else { - assert!(!ip!($s).is_unicast_global()); - } - if ($mask & documentation) == documentation { - assert!(ip!($s).is_documentation()); - } else { - assert!(!ip!($s).is_documentation()); - } - if ($mask & benchmarking) == benchmarking { - assert!(ip!($s).is_benchmarking()); - } else { - assert!(!ip!($s).is_benchmarking()); - } - if ($mask & multicast) != 0 { - assert!(ip!($s).multicast_scope().is_some()); - assert!(ip!($s).is_multicast()); - } else { - assert!(ip!($s).multicast_scope().is_none()); - assert!(!ip!($s).is_multicast()); - } - if ($mask & multicast_interface_local) == multicast_interface_local { - assert_eq!(ip!($s).multicast_scope().unwrap(), - Ipv6MulticastScope::InterfaceLocal); - } - if ($mask & multicast_link_local) == multicast_link_local { - assert_eq!(ip!($s).multicast_scope().unwrap(), - Ipv6MulticastScope::LinkLocal); - } - if ($mask & multicast_realm_local) == multicast_realm_local { - assert_eq!(ip!($s).multicast_scope().unwrap(), - Ipv6MulticastScope::RealmLocal); - } - if ($mask & multicast_admin_local) == multicast_admin_local { - assert_eq!(ip!($s).multicast_scope().unwrap(), - Ipv6MulticastScope::AdminLocal); - } - if ($mask & multicast_site_local) == multicast_site_local { - assert_eq!(ip!($s).multicast_scope().unwrap(), - Ipv6MulticastScope::SiteLocal); - } - if ($mask & multicast_organization_local) == multicast_organization_local { - assert_eq!(ip!($s).multicast_scope().unwrap(), - Ipv6MulticastScope::OrganizationLocal); - } - if ($mask & multicast_global) == multicast_global { - assert_eq!(ip!($s).multicast_scope().unwrap(), - Ipv6MulticastScope::Global); - } - if ($mask & ipv4_mapped) == ipv4_mapped { - assert!(ip!($s).is_ipv4_mapped()); - } else { - assert!(!ip!($s).is_ipv4_mapped()); - } - } - } - - let unspecified: u32 = 1 << 0; - let loopback: u32 = 1 << 1; - let unique_local: u32 = 1 << 2; - let global: u32 = 1 << 3; - let unicast_link_local: u32 = 1 << 4; - let unicast_global: u32 = 1 << 7; - let documentation: u32 = 1 << 8; - let benchmarking: u32 = 1 << 16; - let multicast_interface_local: u32 = 1 << 9; - let multicast_link_local: u32 = 1 << 10; - let multicast_realm_local: u32 = 1 << 11; - let multicast_admin_local: u32 = 1 << 12; - let multicast_site_local: u32 = 1 << 13; - let multicast_organization_local: u32 = 1 << 14; - let multicast_global: u32 = 1 << 15; - let ipv4_mapped: u32 = 1 << 17; - - check!("::", &[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], unspecified); - - check!("::1", &[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1], loopback); - - check!("::2", &[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2], global | unicast_global); - - check!("1::", &[0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], global | unicast_global); - - check!( - "::ffff:127.0.0.1", - &[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0xff, 0xff, 0x7f, 0, 0, 1], - unicast_global | ipv4_mapped - ); - - check!( - "64:ff9b:1::", - &[0, 0x64, 0xff, 0x9b, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - unicast_global - ); - - check!("100::", &[0x01, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], unicast_global); - - check!("2001::", &[0x20, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], unicast_global); - - check!( - "2001:1::1", - &[0x20, 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1], - global | unicast_global - ); - - check!( - "2001:1::2", - &[0x20, 1, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 2], - global | unicast_global - ); - - check!( - "2001:3::", - &[0x20, 1, 0, 3, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - global | unicast_global - ); - - check!( - "2001:4:112::", - &[0x20, 1, 0, 4, 1, 0x12, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - global | unicast_global - ); - - check!( - "2001:20::", - &[0x20, 1, 0, 0x20, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - global | unicast_global - ); - check!( - "2001:30::", - &[0x20, 1, 0, 0x30, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - global | unicast_global - ); - check!("2001:40::", &[0x20, 1, 0, 0x40, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], unicast_global); - - check!( - "2001:200::", - &[0x20, 1, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - global | unicast_global - ); - - check!("2002::", &[0x20, 0x02, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], unicast_global); - - check!("fc00::", &[0xfc, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], unique_local); - - check!( - "fdff:ffff::", - &[0xfd, 0xff, 0xff, 0xff, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - unique_local - ); - - check!( - "fe80:ffff::", - &[0xfe, 0x80, 0xff, 0xff, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - unicast_link_local - ); - - check!("fe80::", &[0xfe, 0x80, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], unicast_link_local); - - check!( - "febf:ffff::", - &[0xfe, 0xbf, 0xff, 0xff, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - unicast_link_local - ); - - check!("febf::", &[0xfe, 0xbf, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], unicast_link_local); - - check!( - "febf:ffff:ffff:ffff:ffff:ffff:ffff:ffff", - &[ - 0xfe, 0xbf, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, - 0xff, 0xff - ], - unicast_link_local - ); - - check!( - "fe80::ffff:ffff:ffff:ffff", - &[ - 0xfe, 0x80, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xff, 0xff, 0xff, 0xff, 0xff, 0xff, - 0xff, 0xff - ], - unicast_link_local - ); - - check!( - "fe80:0:0:1::", - &[0xfe, 0x80, 0, 0, 0, 0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0], - unicast_link_local - ); - - check!( - "fec0::", - &[0xfe, 0xc0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - unicast_global | global - ); - - check!( - "ff01::", - &[0xff, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - multicast_interface_local | global - ); - - check!( - "ff02::", - &[0xff, 2, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - multicast_link_local | global - ); - - check!( - "ff03::", - &[0xff, 3, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - multicast_realm_local | global - ); - - check!( - "ff04::", - &[0xff, 4, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - multicast_admin_local | global - ); - - check!( - "ff05::", - &[0xff, 5, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - multicast_site_local | global - ); - - check!( - "ff08::", - &[0xff, 8, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - multicast_organization_local | global - ); - - check!( - "ff0e::", - &[0xff, 0xe, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0], - multicast_global | global - ); - - check!( - "2001:db8:85a3::8a2e:370:7334", - &[0x20, 1, 0xd, 0xb8, 0x85, 0xa3, 0, 0, 0, 0, 0x8a, 0x2e, 3, 0x70, 0x73, 0x34], - documentation - ); - - check!( - "2001:2::ac32:23ff:21", - &[0x20, 1, 0, 2, 0, 0, 0, 0, 0, 0, 0xac, 0x32, 0x23, 0xff, 0, 0x21], - benchmarking - ); - - check!( - "102:304:506:708:90a:b0c:d0e:f10", - &[1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16], - global | unicast_global - ); -} - -#[test] -fn test_ipv4_to_int() { - let a = Ipv4Addr::new(0x11, 0x22, 0x33, 0x44); - assert_eq!(u32::from(a), 0x11223344); -} - -#[test] -fn test_int_to_ipv4() { - let a = Ipv4Addr::new(0x11, 0x22, 0x33, 0x44); - assert_eq!(Ipv4Addr::from(0x11223344), a); -} - -#[test] -fn test_ipv6_to_int() { - let a = Ipv6Addr::new(0x1122, 0x3344, 0x5566, 0x7788, 0x99aa, 0xbbcc, 0xddee, 0xff11); - assert_eq!(u128::from(a), 0x112233445566778899aabbccddeeff11u128); -} - -#[test] -fn test_int_to_ipv6() { - let a = Ipv6Addr::new(0x1122, 0x3344, 0x5566, 0x7788, 0x99aa, 0xbbcc, 0xddee, 0xff11); - assert_eq!(Ipv6Addr::from(0x112233445566778899aabbccddeeff11u128), a); -} - -#[test] -fn ipv4_from_constructors() { - assert_eq!(Ipv4Addr::LOCALHOST, Ipv4Addr::new(127, 0, 0, 1)); - assert!(Ipv4Addr::LOCALHOST.is_loopback()); - assert_eq!(Ipv4Addr::UNSPECIFIED, Ipv4Addr::new(0, 0, 0, 0)); - assert!(Ipv4Addr::UNSPECIFIED.is_unspecified()); - assert_eq!(Ipv4Addr::BROADCAST, Ipv4Addr::new(255, 255, 255, 255)); - assert!(Ipv4Addr::BROADCAST.is_broadcast()); -} - -#[test] -fn ipv6_from_constructors() { - assert_eq!(Ipv6Addr::LOCALHOST, Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1)); - assert!(Ipv6Addr::LOCALHOST.is_loopback()); - assert_eq!(Ipv6Addr::UNSPECIFIED, Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0)); - assert!(Ipv6Addr::UNSPECIFIED.is_unspecified()); -} - -#[test] -fn ipv4_from_octets() { - assert_eq!(Ipv4Addr::from([127, 0, 0, 1]), Ipv4Addr::new(127, 0, 0, 1)) -} - -#[test] -fn ipv6_from_segments() { - let from_u16s = - Ipv6Addr::from([0x0011, 0x2233, 0x4455, 0x6677, 0x8899, 0xaabb, 0xccdd, 0xeeff]); - let new = Ipv6Addr::new(0x0011, 0x2233, 0x4455, 0x6677, 0x8899, 0xaabb, 0xccdd, 0xeeff); - assert_eq!(new, from_u16s); -} - -#[test] -fn ipv6_from_octets() { - let from_u16s = - Ipv6Addr::from([0x0011, 0x2233, 0x4455, 0x6677, 0x8899, 0xaabb, 0xccdd, 0xeeff]); - let from_u8s = Ipv6Addr::from([ - 0x00, 0x11, 0x22, 0x33, 0x44, 0x55, 0x66, 0x77, 0x88, 0x99, 0xaa, 0xbb, 0xcc, 0xdd, 0xee, - 0xff, - ]); - assert_eq!(from_u16s, from_u8s); -} - -#[test] -fn cmp() { - let v41 = Ipv4Addr::new(100, 64, 3, 3); - let v42 = Ipv4Addr::new(192, 0, 2, 2); - let v61 = "2001:db8:f00::1002".parse::().unwrap(); - let v62 = "2001:db8:f00::2001".parse::().unwrap(); - assert!(v41 < v42); - assert!(v61 < v62); - - assert_eq!(v41, IpAddr::V4(v41)); - assert_eq!(v61, IpAddr::V6(v61)); - assert!(v41 != IpAddr::V4(v42)); - assert!(v61 != IpAddr::V6(v62)); - - assert!(v41 < IpAddr::V4(v42)); - assert!(v61 < IpAddr::V6(v62)); - assert!(IpAddr::V4(v41) < v42); - assert!(IpAddr::V6(v61) < v62); - - assert!(v41 < IpAddr::V6(v61)); - assert!(IpAddr::V4(v41) < v61); -} - -#[test] -fn is_v4() { - let ip = IpAddr::V4(Ipv4Addr::new(100, 64, 3, 3)); - assert!(ip.is_ipv4()); - assert!(!ip.is_ipv6()); -} - -#[test] -fn is_v6() { - let ip = IpAddr::V6(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0x1234, 0x5678)); - assert!(!ip.is_ipv4()); - assert!(ip.is_ipv6()); -} - -#[test] -fn ipv4_const() { - // test that the methods of `Ipv4Addr` are usable in a const context - - const IP_ADDRESS: Ipv4Addr = Ipv4Addr::new(127, 0, 0, 1); - assert_eq!(IP_ADDRESS, Ipv4Addr::LOCALHOST); - - const OCTETS: [u8; 4] = IP_ADDRESS.octets(); - assert_eq!(OCTETS, [127, 0, 0, 1]); - - const IS_UNSPECIFIED: bool = IP_ADDRESS.is_unspecified(); - assert!(!IS_UNSPECIFIED); - - const IS_LOOPBACK: bool = IP_ADDRESS.is_loopback(); - assert!(IS_LOOPBACK); - - const IS_PRIVATE: bool = IP_ADDRESS.is_private(); - assert!(!IS_PRIVATE); - - const IS_LINK_LOCAL: bool = IP_ADDRESS.is_link_local(); - assert!(!IS_LINK_LOCAL); - - const IS_GLOBAL: bool = IP_ADDRESS.is_global(); - assert!(!IS_GLOBAL); - - const IS_SHARED: bool = IP_ADDRESS.is_shared(); - assert!(!IS_SHARED); - - const IS_BENCHMARKING: bool = IP_ADDRESS.is_benchmarking(); - assert!(!IS_BENCHMARKING); - - const IS_RESERVED: bool = IP_ADDRESS.is_reserved(); - assert!(!IS_RESERVED); - - const IS_MULTICAST: bool = IP_ADDRESS.is_multicast(); - assert!(!IS_MULTICAST); - - const IS_BROADCAST: bool = IP_ADDRESS.is_broadcast(); - assert!(!IS_BROADCAST); - - const IS_DOCUMENTATION: bool = IP_ADDRESS.is_documentation(); - assert!(!IS_DOCUMENTATION); - - const IP_V6_COMPATIBLE: Ipv6Addr = IP_ADDRESS.to_ipv6_compatible(); - assert_eq!( - IP_V6_COMPATIBLE, - Ipv6Addr::from([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 127, 0, 0, 1]) - ); - - const IP_V6_MAPPED: Ipv6Addr = IP_ADDRESS.to_ipv6_mapped(); - assert_eq!( - IP_V6_MAPPED, - Ipv6Addr::from([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 255, 255, 127, 0, 0, 1]) - ); -} - -#[test] -fn ipv6_const() { - // test that the methods of `Ipv6Addr` are usable in a const context - - const IP_ADDRESS: Ipv6Addr = Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1); - assert_eq!(IP_ADDRESS, Ipv6Addr::LOCALHOST); - - const SEGMENTS: [u16; 8] = IP_ADDRESS.segments(); - assert_eq!(SEGMENTS, [0, 0, 0, 0, 0, 0, 0, 1]); - - const OCTETS: [u8; 16] = IP_ADDRESS.octets(); - assert_eq!(OCTETS, [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1]); - - const IS_UNSPECIFIED: bool = IP_ADDRESS.is_unspecified(); - assert!(!IS_UNSPECIFIED); - - const IS_LOOPBACK: bool = IP_ADDRESS.is_loopback(); - assert!(IS_LOOPBACK); - - const IS_GLOBAL: bool = IP_ADDRESS.is_global(); - assert!(!IS_GLOBAL); - - const IS_UNIQUE_LOCAL: bool = IP_ADDRESS.is_unique_local(); - assert!(!IS_UNIQUE_LOCAL); - - const IS_UNICAST_LINK_LOCAL: bool = IP_ADDRESS.is_unicast_link_local(); - assert!(!IS_UNICAST_LINK_LOCAL); - - const IS_DOCUMENTATION: bool = IP_ADDRESS.is_documentation(); - assert!(!IS_DOCUMENTATION); - - const IS_BENCHMARKING: bool = IP_ADDRESS.is_benchmarking(); - assert!(!IS_BENCHMARKING); - - const IS_UNICAST_GLOBAL: bool = IP_ADDRESS.is_unicast_global(); - assert!(!IS_UNICAST_GLOBAL); - - const MULTICAST_SCOPE: Option = IP_ADDRESS.multicast_scope(); - assert_eq!(MULTICAST_SCOPE, None); - - const IS_MULTICAST: bool = IP_ADDRESS.is_multicast(); - assert!(!IS_MULTICAST); - - const IS_IPV4_MAPPED: bool = IP_ADDRESS.is_ipv4_mapped(); - assert!(!IS_IPV4_MAPPED); - - const IP_V4: Option = IP_ADDRESS.to_ipv4(); - assert_eq!(IP_V4.unwrap(), Ipv4Addr::new(0, 0, 0, 1)); -} - -#[test] -fn ip_const() { - // test that the methods of `IpAddr` are usable in a const context - - const IP_ADDRESS: IpAddr = IpAddr::V4(Ipv4Addr::LOCALHOST); - - const IS_UNSPECIFIED: bool = IP_ADDRESS.is_unspecified(); - assert!(!IS_UNSPECIFIED); - - const IS_LOOPBACK: bool = IP_ADDRESS.is_loopback(); - assert!(IS_LOOPBACK); - - const IS_GLOBAL: bool = IP_ADDRESS.is_global(); - assert!(!IS_GLOBAL); - - const IS_MULTICAST: bool = IP_ADDRESS.is_multicast(); - assert!(!IS_MULTICAST); - - const IS_IP_V4: bool = IP_ADDRESS.is_ipv4(); - assert!(IS_IP_V4); - - const IS_IP_V6: bool = IP_ADDRESS.is_ipv6(); - assert!(!IS_IP_V6); -} - -#[test] -fn structural_match() { - // test that all IP types can be structurally matched upon - - const IPV4: Ipv4Addr = Ipv4Addr::LOCALHOST; - match IPV4 { - Ipv4Addr::LOCALHOST => {} - _ => unreachable!(), - } - - const IPV6: Ipv6Addr = Ipv6Addr::LOCALHOST; - match IPV6 { - Ipv6Addr::LOCALHOST => {} - _ => unreachable!(), - } - - const IP: IpAddr = IpAddr::V4(Ipv4Addr::LOCALHOST); - match IP { - IpAddr::V4(Ipv4Addr::LOCALHOST) => {} - _ => unreachable!(), - } -} diff --git a/library/core/tests/net/mod.rs b/library/core/tests/net/mod.rs deleted file mode 100644 index 8f17bbe5548ac..0000000000000 --- a/library/core/tests/net/mod.rs +++ /dev/null @@ -1,13 +0,0 @@ -use core::net::{Ipv4Addr, Ipv6Addr, SocketAddr, SocketAddrV4, SocketAddrV6}; - -mod ip_addr; -mod parser; -mod socket_addr; - -pub fn sa4(a: Ipv4Addr, p: u16) -> SocketAddr { - SocketAddr::V4(SocketAddrV4::new(a, p)) -} - -pub fn sa6(a: Ipv6Addr, p: u16) -> SocketAddr { - SocketAddr::V6(SocketAddrV6::new(a, p, 0, 0)) -} diff --git a/library/core/tests/net/parser.rs b/library/core/tests/net/parser.rs deleted file mode 100644 index 36b87d7c1f5e0..0000000000000 --- a/library/core/tests/net/parser.rs +++ /dev/null @@ -1,149 +0,0 @@ -// FIXME: These tests are all excellent candidates for AFL fuzz testing -use core::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, SocketAddrV4, SocketAddrV6}; -use core::str::FromStr; - -const PORT: u16 = 8080; -const SCOPE_ID: u32 = 1337; - -const IPV4: Ipv4Addr = Ipv4Addr::new(192, 168, 0, 1); -const IPV4_STR: &str = "192.168.0.1"; -const IPV4_STR_PORT: &str = "192.168.0.1:8080"; -const IPV4_STR_WITH_OCTAL: &str = "0127.0.0.1"; -const IPV4_STR_WITH_HEX: &str = "0x10.0.0.1"; - -const IPV6: Ipv6Addr = Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0xc0a8, 0x1); -const IPV6_STR_FULL: &str = "2001:db8:0:0:0:0:c0a8:1"; -const IPV6_STR_COMPRESS: &str = "2001:db8::c0a8:1"; -const IPV6_STR_V4: &str = "2001:db8::192.168.0.1"; -const IPV6_STR_V4_WITH_OCTAL: &str = "2001:db8::0127.0.0.1"; -const IPV6_STR_V4_WITH_HEX: &str = "2001:db8::0x10.0.0.1"; -const IPV6_STR_PORT: &str = "[2001:db8::c0a8:1]:8080"; -const IPV6_STR_PORT_SCOPE_ID: &str = "[2001:db8::c0a8:1%1337]:8080"; - -#[test] -fn parse_ipv4() { - let result: Ipv4Addr = IPV4_STR.parse().unwrap(); - assert_eq!(result, IPV4); - - assert!(Ipv4Addr::from_str(IPV4_STR_PORT).is_err()); - assert!(Ipv4Addr::from_str(IPV4_STR_WITH_OCTAL).is_err()); - assert!(Ipv4Addr::from_str(IPV4_STR_WITH_HEX).is_err()); - assert!(Ipv4Addr::from_str(IPV6_STR_FULL).is_err()); - assert!(Ipv4Addr::from_str(IPV6_STR_COMPRESS).is_err()); - assert!(Ipv4Addr::from_str(IPV6_STR_V4).is_err()); - assert!(Ipv4Addr::from_str(IPV6_STR_PORT).is_err()); -} - -#[test] -fn parse_ipv6() { - let result: Ipv6Addr = IPV6_STR_FULL.parse().unwrap(); - assert_eq!(result, IPV6); - - let result: Ipv6Addr = IPV6_STR_COMPRESS.parse().unwrap(); - assert_eq!(result, IPV6); - - let result: Ipv6Addr = IPV6_STR_V4.parse().unwrap(); - assert_eq!(result, IPV6); - - assert!(Ipv6Addr::from_str(IPV6_STR_V4_WITH_OCTAL).is_err()); - assert!(Ipv6Addr::from_str(IPV6_STR_V4_WITH_HEX).is_err()); - assert!(Ipv6Addr::from_str(IPV4_STR).is_err()); - assert!(Ipv6Addr::from_str(IPV4_STR_PORT).is_err()); - assert!(Ipv6Addr::from_str(IPV6_STR_PORT).is_err()); -} - -#[test] -fn parse_ip() { - let result: IpAddr = IPV4_STR.parse().unwrap(); - assert_eq!(result, IpAddr::from(IPV4)); - - let result: IpAddr = IPV6_STR_FULL.parse().unwrap(); - assert_eq!(result, IpAddr::from(IPV6)); - - let result: IpAddr = IPV6_STR_COMPRESS.parse().unwrap(); - assert_eq!(result, IpAddr::from(IPV6)); - - let result: IpAddr = IPV6_STR_V4.parse().unwrap(); - assert_eq!(result, IpAddr::from(IPV6)); - - assert!(IpAddr::from_str(IPV4_STR_PORT).is_err()); - assert!(IpAddr::from_str(IPV6_STR_PORT).is_err()); -} - -#[test] -fn parse_socket_v4() { - let result: SocketAddrV4 = IPV4_STR_PORT.parse().unwrap(); - assert_eq!(result, SocketAddrV4::new(IPV4, PORT)); - - assert!(SocketAddrV4::from_str(IPV4_STR).is_err()); - assert!(SocketAddrV4::from_str(IPV6_STR_FULL).is_err()); - assert!(SocketAddrV4::from_str(IPV6_STR_COMPRESS).is_err()); - assert!(SocketAddrV4::from_str(IPV6_STR_V4).is_err()); - assert!(SocketAddrV4::from_str(IPV6_STR_PORT).is_err()); -} - -#[test] -fn parse_socket_v6() { - assert_eq!(IPV6_STR_PORT.parse(), Ok(SocketAddrV6::new(IPV6, PORT, 0, 0))); - assert_eq!(IPV6_STR_PORT_SCOPE_ID.parse(), Ok(SocketAddrV6::new(IPV6, PORT, 0, SCOPE_ID))); - - assert!(SocketAddrV6::from_str(IPV4_STR).is_err()); - assert!(SocketAddrV6::from_str(IPV4_STR_PORT).is_err()); - assert!(SocketAddrV6::from_str(IPV6_STR_FULL).is_err()); - assert!(SocketAddrV6::from_str(IPV6_STR_COMPRESS).is_err()); - assert!(SocketAddrV6::from_str(IPV6_STR_V4).is_err()); -} - -#[test] -fn parse_socket() { - let result: SocketAddr = IPV4_STR_PORT.parse().unwrap(); - assert_eq!(result, SocketAddr::from((IPV4, PORT))); - - let result: SocketAddr = IPV6_STR_PORT.parse().unwrap(); - assert_eq!(result, SocketAddr::from((IPV6, PORT))); - - assert!(SocketAddr::from_str(IPV4_STR).is_err()); - assert!(SocketAddr::from_str(IPV6_STR_FULL).is_err()); - assert!(SocketAddr::from_str(IPV6_STR_COMPRESS).is_err()); - assert!(SocketAddr::from_str(IPV6_STR_V4).is_err()); -} - -#[test] -fn ipv6_corner_cases() { - let result: Ipv6Addr = "1::".parse().unwrap(); - assert_eq!(result, Ipv6Addr::new(1, 0, 0, 0, 0, 0, 0, 0)); - - let result: Ipv6Addr = "1:1::".parse().unwrap(); - assert_eq!(result, Ipv6Addr::new(1, 1, 0, 0, 0, 0, 0, 0)); - - let result: Ipv6Addr = "::1".parse().unwrap(); - assert_eq!(result, Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1)); - - let result: Ipv6Addr = "::1:1".parse().unwrap(); - assert_eq!(result, Ipv6Addr::new(0, 0, 0, 0, 0, 0, 1, 1)); - - let result: Ipv6Addr = "::".parse().unwrap(); - assert_eq!(result, Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0)); - - let result: Ipv6Addr = "::192.168.0.1".parse().unwrap(); - assert_eq!(result, Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0xc0a8, 0x1)); - - let result: Ipv6Addr = "::1:192.168.0.1".parse().unwrap(); - assert_eq!(result, Ipv6Addr::new(0, 0, 0, 0, 0, 1, 0xc0a8, 0x1)); - - let result: Ipv6Addr = "1:1:1:1:1:1:192.168.0.1".parse().unwrap(); - assert_eq!(result, Ipv6Addr::new(1, 1, 1, 1, 1, 1, 0xc0a8, 0x1)); -} - -// Things that might not seem like failures but are -#[test] -fn ipv6_corner_failures() { - // No IP address before the :: - assert!(Ipv6Addr::from_str("1:192.168.0.1::").is_err()); - - // :: must have at least 1 set of zeroes - assert!(Ipv6Addr::from_str("1:1:1:1::1:1:1:1").is_err()); - - // Need brackets for a port - assert!(SocketAddrV6::from_str("1:1:1:1:1:1:1:1:8080").is_err()); -} diff --git a/library/core/tests/net/socket_addr.rs b/library/core/tests/net/socket_addr.rs deleted file mode 100644 index 3d013d37e04ad..0000000000000 --- a/library/core/tests/net/socket_addr.rs +++ /dev/null @@ -1,244 +0,0 @@ -use core::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, SocketAddrV4, SocketAddrV6}; - -#[test] -fn ipv4_socket_addr_to_string() { - // Shortest possible IPv4 length. - assert_eq!(SocketAddrV4::new(Ipv4Addr::new(0, 0, 0, 0), 0).to_string(), "0.0.0.0:0"); - - // Longest possible IPv4 length. - assert_eq!( - SocketAddrV4::new(Ipv4Addr::new(255, 255, 255, 255), u16::MAX).to_string(), - "255.255.255.255:65535" - ); - - // Test padding. - assert_eq!( - &format!("{:16}", SocketAddrV4::new(Ipv4Addr::new(1, 1, 1, 1), 53)), - "1.1.1.1:53 " - ); - assert_eq!( - &format!("{:>16}", SocketAddrV4::new(Ipv4Addr::new(1, 1, 1, 1), 53)), - " 1.1.1.1:53" - ); -} - -#[test] -fn ipv6_socket_addr_to_string() { - // IPv4-mapped address. - assert_eq!( - SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc000, 0x280), 8080, 0, 0) - .to_string(), - "[::ffff:192.0.2.128]:8080" - ); - - // IPv4-compatible address. - assert_eq!( - SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0xc000, 0x280), 8080, 0, 0).to_string(), - "[::c000:280]:8080" - ); - - // IPv6 address with no zero segments. - assert_eq!( - SocketAddrV6::new(Ipv6Addr::new(8, 9, 10, 11, 12, 13, 14, 15), 80, 0, 0).to_string(), - "[8:9:a:b:c:d:e:f]:80" - ); - - // Shortest possible IPv6 length. - assert_eq!(SocketAddrV6::new(Ipv6Addr::UNSPECIFIED, 0, 0, 0).to_string(), "[::]:0"); - - // Longest possible IPv6 length. - assert_eq!( - SocketAddrV6::new( - Ipv6Addr::new(0x1111, 0x2222, 0x3333, 0x4444, 0x5555, 0x6666, 0x7777, 0x8888), - u16::MAX, - u32::MAX, - u32::MAX, - ) - .to_string(), - "[1111:2222:3333:4444:5555:6666:7777:8888%4294967295]:65535" - ); - - // Test padding. - assert_eq!( - &format!("{:22}", SocketAddrV6::new(Ipv6Addr::new(1, 2, 3, 4, 5, 6, 7, 8), 9, 0, 0)), - "[1:2:3:4:5:6:7:8]:9 " - ); - assert_eq!( - &format!("{:>22}", SocketAddrV6::new(Ipv6Addr::new(1, 2, 3, 4, 5, 6, 7, 8), 9, 0, 0)), - " [1:2:3:4:5:6:7:8]:9" - ); -} - -#[test] -fn set_ip() { - fn ip4(low: u8) -> Ipv4Addr { - Ipv4Addr::new(77, 88, 21, low) - } - fn ip6(low: u16) -> Ipv6Addr { - Ipv6Addr::new(0x2a02, 0x6b8, 0, 1, 0, 0, 0, low) - } - - let mut v4 = SocketAddrV4::new(ip4(11), 80); - assert_eq!(v4.ip(), &ip4(11)); - v4.set_ip(ip4(12)); - assert_eq!(v4.ip(), &ip4(12)); - - let mut addr = SocketAddr::V4(v4); - assert_eq!(addr.ip(), IpAddr::V4(ip4(12))); - addr.set_ip(IpAddr::V4(ip4(13))); - assert_eq!(addr.ip(), IpAddr::V4(ip4(13))); - addr.set_ip(IpAddr::V6(ip6(14))); - assert_eq!(addr.ip(), IpAddr::V6(ip6(14))); - - let mut v6 = SocketAddrV6::new(ip6(1), 80, 0, 0); - assert_eq!(v6.ip(), &ip6(1)); - v6.set_ip(ip6(2)); - assert_eq!(v6.ip(), &ip6(2)); - - let mut addr = SocketAddr::V6(v6); - assert_eq!(addr.ip(), IpAddr::V6(ip6(2))); - addr.set_ip(IpAddr::V6(ip6(3))); - assert_eq!(addr.ip(), IpAddr::V6(ip6(3))); - addr.set_ip(IpAddr::V4(ip4(4))); - assert_eq!(addr.ip(), IpAddr::V4(ip4(4))); -} - -#[test] -fn set_port() { - let mut v4 = SocketAddrV4::new(Ipv4Addr::new(77, 88, 21, 11), 80); - assert_eq!(v4.port(), 80); - v4.set_port(443); - assert_eq!(v4.port(), 443); - - let mut addr = SocketAddr::V4(v4); - assert_eq!(addr.port(), 443); - addr.set_port(8080); - assert_eq!(addr.port(), 8080); - - let mut v6 = SocketAddrV6::new(Ipv6Addr::new(0x2a02, 0x6b8, 0, 1, 0, 0, 0, 1), 80, 0, 0); - assert_eq!(v6.port(), 80); - v6.set_port(443); - assert_eq!(v6.port(), 443); - - let mut addr = SocketAddr::V6(v6); - assert_eq!(addr.port(), 443); - addr.set_port(8080); - assert_eq!(addr.port(), 8080); -} - -#[test] -fn set_flowinfo() { - let mut v6 = SocketAddrV6::new(Ipv6Addr::new(0x2a02, 0x6b8, 0, 1, 0, 0, 0, 1), 80, 10, 0); - assert_eq!(v6.flowinfo(), 10); - v6.set_flowinfo(20); - assert_eq!(v6.flowinfo(), 20); -} - -#[test] -fn set_scope_id() { - let mut v6 = SocketAddrV6::new(Ipv6Addr::new(0x2a02, 0x6b8, 0, 1, 0, 0, 0, 1), 80, 0, 10); - assert_eq!(v6.scope_id(), 10); - v6.set_scope_id(20); - assert_eq!(v6.scope_id(), 20); -} - -#[test] -fn is_v4() { - let v4 = SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(77, 88, 21, 11), 80)); - assert!(v4.is_ipv4()); - assert!(!v4.is_ipv6()); -} - -#[test] -fn is_v6() { - let v6 = SocketAddr::V6(SocketAddrV6::new( - Ipv6Addr::new(0x2a02, 0x6b8, 0, 1, 0, 0, 0, 1), - 80, - 10, - 0, - )); - assert!(!v6.is_ipv4()); - assert!(v6.is_ipv6()); -} - -#[test] -fn socket_v4_to_str() { - let socket = SocketAddrV4::new(Ipv4Addr::new(192, 168, 0, 1), 8080); - - assert_eq!(format!("{socket}"), "192.168.0.1:8080"); - assert_eq!(format!("{socket:<20}"), "192.168.0.1:8080 "); - assert_eq!(format!("{socket:>20}"), " 192.168.0.1:8080"); - assert_eq!(format!("{socket:^20}"), " 192.168.0.1:8080 "); - assert_eq!(format!("{socket:.10}"), "192.168.0."); -} - -#[test] -fn socket_v6_to_str() { - let mut socket = SocketAddrV6::new(Ipv6Addr::new(0x2a02, 0x6b8, 0, 1, 0, 0, 0, 1), 53, 0, 0); - - assert_eq!(format!("{socket}"), "[2a02:6b8:0:1::1]:53"); - assert_eq!(format!("{socket:<24}"), "[2a02:6b8:0:1::1]:53 "); - assert_eq!(format!("{socket:>24}"), " [2a02:6b8:0:1::1]:53"); - assert_eq!(format!("{socket:^24}"), " [2a02:6b8:0:1::1]:53 "); - assert_eq!(format!("{socket:.15}"), "[2a02:6b8:0:1::"); - - socket.set_scope_id(5); - - assert_eq!(format!("{socket}"), "[2a02:6b8:0:1::1%5]:53"); - assert_eq!(format!("{socket:<24}"), "[2a02:6b8:0:1::1%5]:53 "); - assert_eq!(format!("{socket:>24}"), " [2a02:6b8:0:1::1%5]:53"); - assert_eq!(format!("{socket:^24}"), " [2a02:6b8:0:1::1%5]:53 "); - assert_eq!(format!("{socket:.18}"), "[2a02:6b8:0:1::1%5"); -} - -#[test] -fn compare() { - let v4_1 = "224.120.45.1:23456".parse::().unwrap(); - let v4_2 = "224.210.103.5:12345".parse::().unwrap(); - let v4_3 = "224.210.103.5:23456".parse::().unwrap(); - let v6_1 = "[2001:db8:f00::1002]:23456".parse::().unwrap(); - let v6_2 = "[2001:db8:f00::2001]:12345".parse::().unwrap(); - let v6_3 = "[2001:db8:f00::2001]:23456".parse::().unwrap(); - let v6_4 = "[2001:db8:f00::2001%42]:23456".parse::().unwrap(); - let mut v6_5 = "[2001:db8:f00::2001]:23456".parse::().unwrap(); - v6_5.set_flowinfo(17); - - // equality - assert_eq!(v4_1, v4_1); - assert_eq!(v6_1, v6_1); - assert_eq!(SocketAddr::V4(v4_1), SocketAddr::V4(v4_1)); - assert_eq!(SocketAddr::V6(v6_1), SocketAddr::V6(v6_1)); - assert!(v4_1 != v4_2); - assert!(v6_1 != v6_2); - assert!(v6_3 != v6_4); - assert!(v6_3 != v6_5); - - // compare different addresses - assert!(v4_1 < v4_2); - assert!(v6_1 < v6_2); - assert!(v4_2 > v4_1); - assert!(v6_2 > v6_1); - - // compare the same address with different ports - assert!(v4_2 < v4_3); - assert!(v6_2 < v6_3); - assert!(v4_3 > v4_2); - assert!(v6_3 > v6_2); - - // compare different addresses with the same port - assert!(v4_1 < v4_3); - assert!(v6_1 < v6_3); - assert!(v4_3 > v4_1); - assert!(v6_3 > v6_1); - - // compare the same address with different scope_id - assert!(v6_3 < v6_4); - - // compare the same address with different flowinfo - assert!(v6_3 < v6_5); - - // compare with an inferred right-hand side - assert_eq!(v4_1, "224.120.45.1:23456".parse().unwrap()); - assert_eq!(v6_1, "[2001:db8:f00::1002]:23456".parse().unwrap()); - assert_eq!(SocketAddr::V4(v4_1), "224.120.45.1:23456".parse().unwrap()); -} diff --git a/library/core/tests/nonzero.rs b/library/core/tests/nonzero.rs deleted file mode 100644 index d728513a4e297..0000000000000 --- a/library/core/tests/nonzero.rs +++ /dev/null @@ -1,356 +0,0 @@ -use core::num::{IntErrorKind, NonZero}; -use core::option::Option::None; -use std::mem::size_of; - -#[test] -fn test_create_nonzero_instance() { - let _a = unsafe { NonZero::new_unchecked(21) }; -} - -#[test] -fn test_size_nonzero_in_option() { - assert_eq!(size_of::>(), size_of::>>()); - assert_eq!(size_of::>(), size_of::>>()); -} - -#[test] -fn test_match_on_nonzero_option() { - let a = Some(unsafe { NonZero::::new_unchecked(42) }); - match a { - Some(val) => assert_eq!(val.get(), 42), - None => panic!("unexpected None while matching on Some(NonZero(_))"), - } - - match unsafe { Some(NonZero::::new_unchecked(43)) } { - Some(val) => assert_eq!(val.get(), 43), - None => panic!("unexpected None while matching on Some(NonZero(_))"), - } -} - -#[test] -fn test_match_option_empty_vec() { - let a: Option> = Some(vec![]); - match a { - None => panic!("unexpected None while matching on Some(vec![])"), - _ => {} - } -} - -#[test] -fn test_match_option_vec() { - let a = Some(vec![1, 2, 3, 4]); - match a { - Some(v) => assert_eq!(v, [1, 2, 3, 4]), - None => panic!("unexpected None while matching on Some(vec![1, 2, 3, 4])"), - } -} - -#[test] -fn test_match_option_rc() { - use std::rc::Rc; - - let five = Rc::new(5); - match Some(five) { - Some(r) => assert_eq!(*r, 5), - None => panic!("unexpected None while matching on Some(Rc::new(5))"), - } -} - -#[test] -fn test_match_option_arc() { - use std::sync::Arc; - - let five = Arc::new(5); - match Some(five) { - Some(a) => assert_eq!(*a, 5), - None => panic!("unexpected None while matching on Some(Arc::new(5))"), - } -} - -#[test] -fn test_match_option_empty_string() { - let a = Some(String::new()); - match a { - None => panic!("unexpected None while matching on Some(String::new())"), - _ => {} - } -} - -#[test] -fn test_match_option_string() { - let five = "Five".to_string(); - match Some(five) { - Some(s) => assert_eq!(s, "Five"), - None => panic!("{}", "unexpected None while matching on Some(String { ... })"), - } -} - -mod atom { - use core::num::NonZero; - - #[derive(PartialEq, Eq)] - pub struct Atom { - index: NonZero, // private - } - - pub const FOO_ATOM: Atom = Atom { index: unsafe { NonZero::new_unchecked(7) } }; -} - -macro_rules! atom { - ("foo") => { - atom::FOO_ATOM - }; -} - -#[test] -fn test_match_nonzero_const_pattern() { - match atom!("foo") { - // Using as a pattern is supported by the compiler: - atom!("foo") => {} - _ => panic!("Expected the const item as a pattern to match."), - } -} - -#[test] -fn test_from_nonzero() { - let nz = NonZero::new(1).unwrap(); - let num: u32 = nz.into(); - assert_eq!(num, 1u32); -} - -#[test] -fn test_from_signed_nonzero() { - let nz = NonZero::new(1).unwrap(); - let num: i32 = nz.into(); - assert_eq!(num, 1i32); -} - -#[test] -fn test_from_str() { - assert_eq!("123".parse::>(), Ok(NonZero::new(123).unwrap())); - assert_eq!( - "0".parse::>().err().map(|e| e.kind().clone()), - Some(IntErrorKind::Zero) - ); - assert_eq!( - "-1".parse::>().err().map(|e| e.kind().clone()), - Some(IntErrorKind::InvalidDigit) - ); - assert_eq!( - "-129".parse::>().err().map(|e| e.kind().clone()), - Some(IntErrorKind::NegOverflow) - ); - assert_eq!( - "257".parse::>().err().map(|e| e.kind().clone()), - Some(IntErrorKind::PosOverflow) - ); -} - -#[test] -fn test_nonzero_bitor() { - let nz_alt = NonZero::new(0b1010_1010).unwrap(); - let nz_low = NonZero::new(0b0000_1111).unwrap(); - - let both_nz: NonZero = nz_alt | nz_low; - assert_eq!(both_nz.get(), 0b1010_1111); - - let rhs_int: NonZero = nz_low | 0b1100_0000u8; - assert_eq!(rhs_int.get(), 0b1100_1111); - - let rhs_zero: NonZero = nz_alt | 0u8; - assert_eq!(rhs_zero.get(), 0b1010_1010); - - let lhs_int: NonZero = 0b0110_0110u8 | nz_alt; - assert_eq!(lhs_int.get(), 0b1110_1110); - - let lhs_zero: NonZero = 0u8 | nz_low; - assert_eq!(lhs_zero.get(), 0b0000_1111); -} - -#[test] -fn test_nonzero_bitor_assign() { - let mut target = NonZero::::new(0b1010_1010).unwrap(); - - target |= NonZero::new(0b0000_1111).unwrap(); - assert_eq!(target.get(), 0b1010_1111); - - target |= 0b0001_0000; - assert_eq!(target.get(), 0b1011_1111); - - target |= 0; - assert_eq!(target.get(), 0b1011_1111); -} - -#[test] -fn test_nonzero_from_int_on_success() { - assert_eq!(NonZero::::try_from(5), Ok(NonZero::new(5).unwrap())); - assert_eq!(NonZero::::try_from(5), Ok(NonZero::new(5).unwrap())); - - assert_eq!(NonZero::::try_from(-5), Ok(NonZero::new(-5).unwrap())); - assert_eq!(NonZero::::try_from(-5), Ok(NonZero::new(-5).unwrap())); -} - -#[test] -fn test_nonzero_from_int_on_err() { - assert!(NonZero::::try_from(0).is_err()); - assert!(NonZero::::try_from(0).is_err()); - - assert!(NonZero::::try_from(0).is_err()); - assert!(NonZero::::try_from(0).is_err()); -} - -#[test] -fn nonzero_const() { - // test that the methods of `NonZeroX>` are usable in a const context - // Note: only tests NonZero - - const NONZERO_U8: NonZero = unsafe { NonZero::new_unchecked(5) }; - - const GET: u8 = NONZERO_U8.get(); - assert_eq!(GET, 5); - - const ZERO: Option> = NonZero::new(0); - assert!(ZERO.is_none()); - - const ONE: Option> = NonZero::new(1); - assert!(ONE.is_some()); - - /* FIXME(#110395) - const FROM_NONZERO_U8: u8 = u8::from(NONZERO_U8); - assert_eq!(FROM_NONZERO_U8, 5); - - const NONZERO_CONVERT: NonZero = NonZero::::from(NONZERO_U8); - assert_eq!(NONZERO_CONVERT.get(), 5); - */ -} - -#[test] -fn nonzero_leading_zeros() { - assert_eq!(NonZero::::new(1).unwrap().leading_zeros(), 7); - assert_eq!(NonZero::::new(1).unwrap().leading_zeros(), 7); - assert_eq!(NonZero::::new(1).unwrap().leading_zeros(), 15); - assert_eq!(NonZero::::new(1).unwrap().leading_zeros(), 15); - assert_eq!(NonZero::::new(1).unwrap().leading_zeros(), 31); - assert_eq!(NonZero::::new(1).unwrap().leading_zeros(), 31); - assert_eq!(NonZero::::new(1).unwrap().leading_zeros(), 63); - assert_eq!(NonZero::::new(1).unwrap().leading_zeros(), 63); - assert_eq!(NonZero::::new(1).unwrap().leading_zeros(), 127); - assert_eq!(NonZero::::new(1).unwrap().leading_zeros(), 127); - assert_eq!(NonZero::::new(1).unwrap().leading_zeros(), usize::BITS - 1); - assert_eq!(NonZero::::new(1).unwrap().leading_zeros(), usize::BITS - 1); - - assert_eq!(NonZero::::new(u8::MAX >> 2).unwrap().leading_zeros(), 2); - assert_eq!(NonZero::::new((u8::MAX >> 2) as i8).unwrap().leading_zeros(), 2); - assert_eq!(NonZero::::new(u16::MAX >> 2).unwrap().leading_zeros(), 2); - assert_eq!(NonZero::::new((u16::MAX >> 2) as i16).unwrap().leading_zeros(), 2); - assert_eq!(NonZero::::new(u32::MAX >> 2).unwrap().leading_zeros(), 2); - assert_eq!(NonZero::::new((u32::MAX >> 2) as i32).unwrap().leading_zeros(), 2); - assert_eq!(NonZero::::new(u64::MAX >> 2).unwrap().leading_zeros(), 2); - assert_eq!(NonZero::::new((u64::MAX >> 2) as i64).unwrap().leading_zeros(), 2); - assert_eq!(NonZero::::new(u128::MAX >> 2).unwrap().leading_zeros(), 2); - assert_eq!(NonZero::::new((u128::MAX >> 2) as i128).unwrap().leading_zeros(), 2); - assert_eq!(NonZero::::new(usize::MAX >> 2).unwrap().leading_zeros(), 2); - assert_eq!(NonZero::::new((usize::MAX >> 2) as isize).unwrap().leading_zeros(), 2); - - assert_eq!(NonZero::::new(u8::MAX).unwrap().leading_zeros(), 0); - assert_eq!(NonZero::::new(-1i8).unwrap().leading_zeros(), 0); - assert_eq!(NonZero::::new(u16::MAX).unwrap().leading_zeros(), 0); - assert_eq!(NonZero::::new(-1i16).unwrap().leading_zeros(), 0); - assert_eq!(NonZero::::new(u32::MAX).unwrap().leading_zeros(), 0); - assert_eq!(NonZero::::new(-1i32).unwrap().leading_zeros(), 0); - assert_eq!(NonZero::::new(u64::MAX).unwrap().leading_zeros(), 0); - assert_eq!(NonZero::::new(-1i64).unwrap().leading_zeros(), 0); - assert_eq!(NonZero::::new(u128::MAX).unwrap().leading_zeros(), 0); - assert_eq!(NonZero::::new(-1i128).unwrap().leading_zeros(), 0); - assert_eq!(NonZero::::new(usize::MAX).unwrap().leading_zeros(), 0); - assert_eq!(NonZero::::new(-1isize).unwrap().leading_zeros(), 0); - - const LEADING_ZEROS: u32 = NonZero::::new(1).unwrap().leading_zeros(); - assert_eq!(LEADING_ZEROS, 15); -} - -#[test] -fn nonzero_trailing_zeros() { - assert_eq!(NonZero::::new(1).unwrap().trailing_zeros(), 0); - assert_eq!(NonZero::::new(1).unwrap().trailing_zeros(), 0); - assert_eq!(NonZero::::new(1).unwrap().trailing_zeros(), 0); - assert_eq!(NonZero::::new(1).unwrap().trailing_zeros(), 0); - assert_eq!(NonZero::::new(1).unwrap().trailing_zeros(), 0); - assert_eq!(NonZero::::new(1).unwrap().trailing_zeros(), 0); - assert_eq!(NonZero::::new(1).unwrap().trailing_zeros(), 0); - assert_eq!(NonZero::::new(1).unwrap().trailing_zeros(), 0); - assert_eq!(NonZero::::new(1).unwrap().trailing_zeros(), 0); - assert_eq!(NonZero::::new(1).unwrap().trailing_zeros(), 0); - assert_eq!(NonZero::::new(1).unwrap().trailing_zeros(), 0); - assert_eq!(NonZero::::new(1).unwrap().trailing_zeros(), 0); - - assert_eq!(NonZero::::new(1 << 2).unwrap().trailing_zeros(), 2); - assert_eq!(NonZero::::new(1 << 2).unwrap().trailing_zeros(), 2); - assert_eq!(NonZero::::new(1 << 2).unwrap().trailing_zeros(), 2); - assert_eq!(NonZero::::new(1 << 2).unwrap().trailing_zeros(), 2); - assert_eq!(NonZero::::new(1 << 2).unwrap().trailing_zeros(), 2); - assert_eq!(NonZero::::new(1 << 2).unwrap().trailing_zeros(), 2); - assert_eq!(NonZero::::new(1 << 2).unwrap().trailing_zeros(), 2); - assert_eq!(NonZero::::new(1 << 2).unwrap().trailing_zeros(), 2); - assert_eq!(NonZero::::new(1 << 2).unwrap().trailing_zeros(), 2); - assert_eq!(NonZero::::new(1 << 2).unwrap().trailing_zeros(), 2); - assert_eq!(NonZero::::new(1 << 2).unwrap().trailing_zeros(), 2); - assert_eq!(NonZero::::new(1 << 2).unwrap().trailing_zeros(), 2); - - assert_eq!(NonZero::::new(1 << 7).unwrap().trailing_zeros(), 7); - assert_eq!(NonZero::::new(1 << 7).unwrap().trailing_zeros(), 7); - assert_eq!(NonZero::::new(1 << 15).unwrap().trailing_zeros(), 15); - assert_eq!(NonZero::::new(1 << 15).unwrap().trailing_zeros(), 15); - assert_eq!(NonZero::::new(1 << 31).unwrap().trailing_zeros(), 31); - assert_eq!(NonZero::::new(1 << 31).unwrap().trailing_zeros(), 31); - assert_eq!(NonZero::::new(1 << 63).unwrap().trailing_zeros(), 63); - assert_eq!(NonZero::::new(1 << 63).unwrap().trailing_zeros(), 63); - assert_eq!(NonZero::::new(1 << 127).unwrap().trailing_zeros(), 127); - assert_eq!(NonZero::::new(1 << 127).unwrap().trailing_zeros(), 127); - - assert_eq!( - NonZero::::new(1 << (usize::BITS - 1)).unwrap().trailing_zeros(), - usize::BITS - 1 - ); - assert_eq!( - NonZero::::new(1 << (usize::BITS - 1)).unwrap().trailing_zeros(), - usize::BITS - 1 - ); - - const TRAILING_ZEROS: u32 = NonZero::::new(1 << 2).unwrap().trailing_zeros(); - assert_eq!(TRAILING_ZEROS, 2); -} - -#[test] -fn test_nonzero_uint_div() { - let nz = NonZero::new(1).unwrap(); - - let x: u32 = 42u32 / nz; - assert_eq!(x, 42u32); -} - -#[test] -fn test_nonzero_uint_rem() { - let nz = NonZero::new(10).unwrap(); - - let x: u32 = 42u32 % nz; - assert_eq!(x, 2u32); -} - -#[test] -fn test_signed_nonzero_neg() { - assert_eq!((-NonZero::::new(1).unwrap()).get(), -1); - assert_eq!((-NonZero::::new(-1).unwrap()).get(), 1); - - assert_eq!((-NonZero::::new(1).unwrap()).get(), -1); - assert_eq!((-NonZero::::new(-1).unwrap()).get(), 1); - - assert_eq!((-NonZero::::new(1).unwrap()).get(), -1); - assert_eq!((-NonZero::::new(-1).unwrap()).get(), 1); - - assert_eq!((-NonZero::::new(1).unwrap()).get(), -1); - assert_eq!((-NonZero::::new(-1).unwrap()).get(), 1); - - assert_eq!((-NonZero::::new(1).unwrap()).get(), -1); - assert_eq!((-NonZero::::new(-1).unwrap()).get(), 1); -} diff --git a/library/core/tests/num/bignum.rs b/library/core/tests/num/bignum.rs deleted file mode 100644 index 416e7cea7a67b..0000000000000 --- a/library/core/tests/num/bignum.rs +++ /dev/null @@ -1,276 +0,0 @@ -use core::num::bignum::tests::Big8x3 as Big; -use core::num::bignum::Big32x40; - -#[test] -#[should_panic] -fn test_from_u64_overflow() { - Big::from_u64(0x1000000); -} - -#[test] -fn test_add() { - assert_eq!(*Big::from_small(3).add(&Big::from_small(4)), Big::from_small(7)); - assert_eq!(*Big::from_small(3).add(&Big::from_small(0)), Big::from_small(3)); - assert_eq!(*Big::from_small(0).add(&Big::from_small(3)), Big::from_small(3)); - assert_eq!(*Big::from_small(3).add(&Big::from_u64(0xfffe)), Big::from_u64(0x10001)); - assert_eq!(*Big::from_u64(0xfedc).add(&Big::from_u64(0x789)), Big::from_u64(0x10665)); - assert_eq!(*Big::from_u64(0x789).add(&Big::from_u64(0xfedc)), Big::from_u64(0x10665)); -} - -#[test] -#[should_panic] -fn test_add_overflow_1() { - Big::from_small(1).add(&Big::from_u64(0xffffff)); -} - -#[test] -#[should_panic] -fn test_add_overflow_2() { - Big::from_u64(0xffffff).add(&Big::from_small(1)); -} - -#[test] -fn test_add_small() { - assert_eq!(*Big::from_small(3).add_small(4), Big::from_small(7)); - assert_eq!(*Big::from_small(3).add_small(0), Big::from_small(3)); - assert_eq!(*Big::from_small(0).add_small(3), Big::from_small(3)); - assert_eq!(*Big::from_small(7).add_small(250), Big::from_u64(257)); - assert_eq!(*Big::from_u64(0x7fff).add_small(1), Big::from_u64(0x8000)); - assert_eq!(*Big::from_u64(0x2ffe).add_small(0x35), Big::from_u64(0x3033)); - assert_eq!(*Big::from_small(0xdc).add_small(0x89), Big::from_u64(0x165)); -} - -#[test] -#[should_panic] -fn test_add_small_overflow() { - Big::from_u64(0xffffff).add_small(1); -} - -#[test] -fn test_sub() { - assert_eq!(*Big::from_small(7).sub(&Big::from_small(4)), Big::from_small(3)); - assert_eq!(*Big::from_u64(0x10665).sub(&Big::from_u64(0x789)), Big::from_u64(0xfedc)); - assert_eq!(*Big::from_u64(0x10665).sub(&Big::from_u64(0xfedc)), Big::from_u64(0x789)); - assert_eq!(*Big::from_u64(0x10665).sub(&Big::from_u64(0x10664)), Big::from_small(1)); - assert_eq!(*Big::from_u64(0x10665).sub(&Big::from_u64(0x10665)), Big::from_small(0)); -} - -#[test] -#[should_panic] -fn test_sub_underflow_1() { - Big::from_u64(0x10665).sub(&Big::from_u64(0x10666)); -} - -#[test] -#[should_panic] -fn test_sub_underflow_2() { - Big::from_small(0).sub(&Big::from_u64(0x123456)); -} - -#[test] -fn test_mul_small() { - assert_eq!(*Big::from_small(7).mul_small(5), Big::from_small(35)); - assert_eq!(*Big::from_small(0xff).mul_small(0xff), Big::from_u64(0xfe01)); - assert_eq!(*Big::from_u64(0xffffff / 13).mul_small(13), Big::from_u64(0xffffff)); -} - -#[test] -#[should_panic] -fn test_mul_small_overflow() { - Big::from_u64(0x800000).mul_small(2); -} - -#[test] -fn test_mul_pow2() { - assert_eq!(*Big::from_small(0x7).mul_pow2(4), Big::from_small(0x70)); - assert_eq!(*Big::from_small(0xff).mul_pow2(1), Big::from_u64(0x1fe)); - assert_eq!(*Big::from_small(0xff).mul_pow2(12), Big::from_u64(0xff000)); - assert_eq!(*Big::from_small(0x1).mul_pow2(23), Big::from_u64(0x800000)); - assert_eq!(*Big::from_u64(0x123).mul_pow2(0), Big::from_u64(0x123)); - assert_eq!(*Big::from_u64(0x123).mul_pow2(7), Big::from_u64(0x9180)); - assert_eq!(*Big::from_u64(0x123).mul_pow2(15), Big::from_u64(0x918000)); - assert_eq!(*Big::from_small(0).mul_pow2(23), Big::from_small(0)); -} - -#[test] -#[should_panic] -fn test_mul_pow2_overflow_1() { - Big::from_u64(0x1).mul_pow2(24); -} - -#[test] -#[should_panic] -fn test_mul_pow2_overflow_2() { - Big::from_u64(0x123).mul_pow2(16); -} - -#[test] -fn test_mul_pow5() { - assert_eq!(*Big::from_small(42).mul_pow5(0), Big::from_small(42)); - assert_eq!(*Big::from_small(1).mul_pow5(2), Big::from_small(25)); - assert_eq!(*Big::from_small(1).mul_pow5(4), Big::from_u64(25 * 25)); - assert_eq!(*Big::from_small(4).mul_pow5(3), Big::from_u64(500)); - assert_eq!(*Big::from_small(140).mul_pow5(2), Big::from_u64(25 * 140)); - assert_eq!(*Big::from_small(25).mul_pow5(1), Big::from_small(125)); - assert_eq!(*Big::from_small(125).mul_pow5(7), Big::from_u64(9765625)); - assert_eq!(*Big::from_small(0).mul_pow5(127), Big::from_small(0)); -} - -#[test] -#[should_panic] -fn test_mul_pow5_overflow_1() { - Big::from_small(1).mul_pow5(12); -} - -#[test] -#[should_panic] -fn test_mul_pow5_overflow_2() { - Big::from_small(230).mul_pow5(8); -} - -#[test] -fn test_mul_digits() { - assert_eq!(*Big::from_small(3).mul_digits(&[5]), Big::from_small(15)); - assert_eq!(*Big::from_small(0xff).mul_digits(&[0xff]), Big::from_u64(0xfe01)); - assert_eq!(*Big::from_u64(0x123).mul_digits(&[0x56, 0x4]), Big::from_u64(0x4edc2)); - assert_eq!(*Big::from_u64(0x12345).mul_digits(&[0x67]), Big::from_u64(0x7530c3)); - assert_eq!(*Big::from_small(0x12).mul_digits(&[0x67, 0x45, 0x3]), Big::from_u64(0x3ae13e)); - assert_eq!(*Big::from_u64(0xffffff / 13).mul_digits(&[13]), Big::from_u64(0xffffff)); - assert_eq!(*Big::from_small(13).mul_digits(&[0x3b, 0xb1, 0x13]), Big::from_u64(0xffffff)); -} - -#[test] -#[should_panic] -fn test_mul_digits_overflow_1() { - Big::from_u64(0x800000).mul_digits(&[2]); -} - -#[test] -#[should_panic] -fn test_mul_digits_overflow_2() { - Big::from_u64(0x1000).mul_digits(&[0, 0x10]); -} - -#[test] -fn test_div_rem_small() { - let as_val = |(q, r): (&mut Big, u8)| (q.clone(), r); - assert_eq!(as_val(Big::from_small(0xff).div_rem_small(15)), (Big::from_small(17), 0)); - assert_eq!(as_val(Big::from_small(0xff).div_rem_small(16)), (Big::from_small(15), 15)); - assert_eq!(as_val(Big::from_small(3).div_rem_small(40)), (Big::from_small(0), 3)); - assert_eq!( - as_val(Big::from_u64(0xffffff).div_rem_small(123)), - (Big::from_u64(0xffffff / 123), (0xffffffu64 % 123) as u8) - ); - assert_eq!( - as_val(Big::from_u64(0x10000).div_rem_small(123)), - (Big::from_u64(0x10000 / 123), (0x10000u64 % 123) as u8) - ); -} - -#[test] -fn test_div_rem() { - fn div_rem(n: u64, d: u64) -> (Big, Big) { - let mut q = Big::from_small(42); - let mut r = Big::from_small(42); - Big::from_u64(n).div_rem(&Big::from_u64(d), &mut q, &mut r); - (q, r) - } - assert_eq!(div_rem(1, 1), (Big::from_small(1), Big::from_small(0))); - assert_eq!(div_rem(4, 3), (Big::from_small(1), Big::from_small(1))); - assert_eq!(div_rem(1, 7), (Big::from_small(0), Big::from_small(1))); - assert_eq!(div_rem(45, 9), (Big::from_small(5), Big::from_small(0))); - assert_eq!(div_rem(103, 9), (Big::from_small(11), Big::from_small(4))); - assert_eq!(div_rem(123456, 77), (Big::from_u64(1603), Big::from_small(25))); - assert_eq!(div_rem(0xffff, 1), (Big::from_u64(0xffff), Big::from_small(0))); - assert_eq!(div_rem(0xeeee, 0xffff), (Big::from_small(0), Big::from_u64(0xeeee))); - assert_eq!(div_rem(2_000_000, 2), (Big::from_u64(1_000_000), Big::from_u64(0))); -} - -#[test] -fn test_is_zero() { - assert!(Big::from_small(0).is_zero()); - assert!(!Big::from_small(3).is_zero()); - assert!(!Big::from_u64(0x123).is_zero()); - assert!(!Big::from_u64(0xffffff).sub(&Big::from_u64(0xfffffe)).is_zero()); - assert!(Big::from_u64(0xffffff).sub(&Big::from_u64(0xffffff)).is_zero()); -} - -#[test] -fn test_get_bit() { - let x = Big::from_small(0b1101); - assert_eq!(x.get_bit(0), 1); - assert_eq!(x.get_bit(1), 0); - assert_eq!(x.get_bit(2), 1); - assert_eq!(x.get_bit(3), 1); - let y = Big::from_u64(1 << 15); - assert_eq!(y.get_bit(14), 0); - assert_eq!(y.get_bit(15), 1); - assert_eq!(y.get_bit(16), 0); -} - -#[test] -#[should_panic] -fn test_get_bit_out_of_range() { - Big::from_small(42).get_bit(24); -} - -#[test] -fn test_bit_length() { - for i in 0..8 * 3 { - // 010000...000 - assert_eq!(Big::from_small(1).mul_pow2(i).bit_length(), i + 1); - } - for i in 1..8 * 3 - 1 { - // 010000...001 - assert_eq!(Big::from_small(1).mul_pow2(i).add(&Big::from_small(1)).bit_length(), i + 1); - // 110000...000 - assert_eq!(Big::from_small(3).mul_pow2(i).bit_length(), i + 2); - } - assert_eq!(Big::from_small(0).bit_length(), 0); - assert_eq!(Big::from_small(1).bit_length(), 1); - assert_eq!(Big::from_small(5).bit_length(), 3); - assert_eq!(Big::from_small(0x18).bit_length(), 5); - assert_eq!(Big::from_u64(0x4073).bit_length(), 15); - assert_eq!(Big::from_u64(0xffffff).bit_length(), 24); -} - -#[test] -fn test_bit_length_32x40() { - for i in 0..32 * 40 { - // 010000...000 - assert_eq!(Big32x40::from_small(1).mul_pow2(i).bit_length(), i + 1); - } - for i in 1..32 * 40 - 1 { - // 010000...001 - assert_eq!( - Big32x40::from_small(1).mul_pow2(i).add(&Big32x40::from_small(1)).bit_length(), - i + 1 - ); - // 110000...000 - assert_eq!(Big32x40::from_small(3).mul_pow2(i).bit_length(), i + 2); - } - assert_eq!(Big32x40::from_small(0).bit_length(), 0); - assert_eq!(Big32x40::from_small(1).bit_length(), 1); - assert_eq!(Big32x40::from_small(5).bit_length(), 3); - assert_eq!(Big32x40::from_small(0x18).bit_length(), 5); - assert_eq!(Big32x40::from_u64(0x4073).bit_length(), 15); - assert_eq!(Big32x40::from_u64(0xffffff).bit_length(), 24); - assert_eq!(Big32x40::from_u64(0xffffffffffffffff).bit_length(), 64); -} - -#[test] -fn test_ord() { - assert!(Big::from_u64(0) < Big::from_u64(0xffffff)); - assert!(Big::from_u64(0x102) < Big::from_u64(0x201)); -} - -#[test] -fn test_fmt() { - assert_eq!(format!("{:?}", Big::from_u64(0)), "0x0"); - assert_eq!(format!("{:?}", Big::from_u64(0x1)), "0x1"); - assert_eq!(format!("{:?}", Big::from_u64(0x12)), "0x12"); - assert_eq!(format!("{:?}", Big::from_u64(0x123)), "0x1_23"); - assert_eq!(format!("{:?}", Big::from_u64(0x1234)), "0x12_34"); - assert_eq!(format!("{:?}", Big::from_u64(0x12345)), "0x1_23_45"); - assert_eq!(format!("{:?}", Big::from_u64(0x123456)), "0x12_34_56"); -} diff --git a/library/core/tests/num/const_from.rs b/library/core/tests/num/const_from.rs deleted file mode 100644 index fa58e77187915..0000000000000 --- a/library/core/tests/num/const_from.rs +++ /dev/null @@ -1,27 +0,0 @@ -/* FIXME(#110395) -#[test] -fn from() { - use core::convert::TryFrom; - use core::num::TryFromIntError; - - // From - const FROM: i64 = i64::from(1i32); - assert_eq!(FROM, 1i64); - - // From int to float - const FROM_F64: f64 = f64::from(42u8); - assert_eq!(FROM_F64, 42f64); - - // Upper bounded - const U8_FROM_U16: Result = u8::try_from(1u16); - assert_eq!(U8_FROM_U16, Ok(1u8)); - - // Both bounded - const I8_FROM_I16: Result = i8::try_from(1i16); - assert_eq!(I8_FROM_I16, Ok(1i8)); - - // Lower bounded - const I16_FROM_U16: Result = i16::try_from(1u16); - assert_eq!(I16_FROM_U16, Ok(1i16)); -} -*/ diff --git a/library/core/tests/num/dec2flt/float.rs b/library/core/tests/num/dec2flt/float.rs deleted file mode 100644 index 7a9587a18d030..0000000000000 --- a/library/core/tests/num/dec2flt/float.rs +++ /dev/null @@ -1,33 +0,0 @@ -use core::num::dec2flt::float::RawFloat; - -#[test] -fn test_f32_integer_decode() { - assert_eq!(3.14159265359f32.integer_decode(), (13176795, -22, 1)); - assert_eq!((-8573.5918555f32).integer_decode(), (8779358, -10, -1)); - assert_eq!(2f32.powf(100.0).integer_decode(), (8388608, 77, 1)); - assert_eq!(0f32.integer_decode(), (0, -150, 1)); - assert_eq!((-0f32).integer_decode(), (0, -150, -1)); - assert_eq!(f32::INFINITY.integer_decode(), (8388608, 105, 1)); - assert_eq!(f32::NEG_INFINITY.integer_decode(), (8388608, 105, -1)); - - // Ignore the "sign" (quiet / signalling flag) of NAN. - // It can vary between runtime operations and LLVM folding. - let (nan_m, nan_e, _nan_s) = f32::NAN.integer_decode(); - assert_eq!((nan_m, nan_e), (12582912, 105)); -} - -#[test] -fn test_f64_integer_decode() { - assert_eq!(3.14159265359f64.integer_decode(), (7074237752028906, -51, 1)); - assert_eq!((-8573.5918555f64).integer_decode(), (4713381968463931, -39, -1)); - assert_eq!(2f64.powf(100.0).integer_decode(), (4503599627370496, 48, 1)); - assert_eq!(0f64.integer_decode(), (0, -1075, 1)); - assert_eq!((-0f64).integer_decode(), (0, -1075, -1)); - assert_eq!(f64::INFINITY.integer_decode(), (4503599627370496, 972, 1)); - assert_eq!(f64::NEG_INFINITY.integer_decode(), (4503599627370496, 972, -1)); - - // Ignore the "sign" (quiet / signalling flag) of NAN. - // It can vary between runtime operations and LLVM folding. - let (nan_m, nan_e, _nan_s) = f64::NAN.integer_decode(); - assert_eq!((nan_m, nan_e), (6755399441055744, 972)); -} diff --git a/library/core/tests/num/dec2flt/lemire.rs b/library/core/tests/num/dec2flt/lemire.rs deleted file mode 100644 index f71bbb7c7a318..0000000000000 --- a/library/core/tests/num/dec2flt/lemire.rs +++ /dev/null @@ -1,53 +0,0 @@ -use core::num::dec2flt::lemire::compute_float; - -fn compute_float32(q: i64, w: u64) -> (i32, u64) { - let fp = compute_float::(q, w); - (fp.e, fp.f) -} - -fn compute_float64(q: i64, w: u64) -> (i32, u64) { - let fp = compute_float::(q, w); - (fp.e, fp.f) -} - -#[test] -fn compute_float_f32_rounding() { - // These test near-halfway cases for single-precision floats. - assert_eq!(compute_float32(0, 16777216), (151, 0)); - assert_eq!(compute_float32(0, 16777217), (151, 0)); - assert_eq!(compute_float32(0, 16777218), (151, 1)); - assert_eq!(compute_float32(0, 16777219), (151, 2)); - assert_eq!(compute_float32(0, 16777220), (151, 2)); - - // These are examples of the above tests, with - // digits from the exponent shifted to the mantissa. - assert_eq!(compute_float32(-10, 167772160000000000), (151, 0)); - assert_eq!(compute_float32(-10, 167772170000000000), (151, 0)); - assert_eq!(compute_float32(-10, 167772180000000000), (151, 1)); - // Let's check the lines to see if anything is different in table... - assert_eq!(compute_float32(-10, 167772190000000000), (151, 2)); - assert_eq!(compute_float32(-10, 167772200000000000), (151, 2)); -} - -#[test] -fn compute_float_f64_rounding() { - // These test near-halfway cases for double-precision floats. - assert_eq!(compute_float64(0, 9007199254740992), (1076, 0)); - assert_eq!(compute_float64(0, 9007199254740993), (1076, 0)); - assert_eq!(compute_float64(0, 9007199254740994), (1076, 1)); - assert_eq!(compute_float64(0, 9007199254740995), (1076, 2)); - assert_eq!(compute_float64(0, 9007199254740996), (1076, 2)); - assert_eq!(compute_float64(0, 18014398509481984), (1077, 0)); - assert_eq!(compute_float64(0, 18014398509481986), (1077, 0)); - assert_eq!(compute_float64(0, 18014398509481988), (1077, 1)); - assert_eq!(compute_float64(0, 18014398509481990), (1077, 2)); - assert_eq!(compute_float64(0, 18014398509481992), (1077, 2)); - - // These are examples of the above tests, with - // digits from the exponent shifted to the mantissa. - assert_eq!(compute_float64(-3, 9007199254740992000), (1076, 0)); - assert_eq!(compute_float64(-3, 9007199254740993000), (1076, 0)); - assert_eq!(compute_float64(-3, 9007199254740994000), (1076, 1)); - assert_eq!(compute_float64(-3, 9007199254740995000), (1076, 2)); - assert_eq!(compute_float64(-3, 9007199254740996000), (1076, 2)); -} diff --git a/library/core/tests/num/dec2flt/mod.rs b/library/core/tests/num/dec2flt/mod.rs deleted file mode 100644 index 874e0ec7093c7..0000000000000 --- a/library/core/tests/num/dec2flt/mod.rs +++ /dev/null @@ -1,129 +0,0 @@ -#![allow(overflowing_literals)] - -mod float; -mod lemire; -mod parse; - -// Take a float literal, turn it into a string in various ways (that are all trusted -// to be correct) and see if those strings are parsed back to the value of the literal. -// Requires a *polymorphic literal*, i.e., one that can serve as f64 as well as f32. -macro_rules! test_literal { - ($x: expr) => {{ - let x32: f32 = $x; - let x64: f64 = $x; - let inputs = &[stringify!($x).into(), format!("{:?}", x64), format!("{:e}", x64)]; - for input in inputs { - assert_eq!(input.parse(), Ok(x64)); - assert_eq!(input.parse(), Ok(x32)); - let neg_input = format!("-{input}"); - assert_eq!(neg_input.parse(), Ok(-x64)); - assert_eq!(neg_input.parse(), Ok(-x32)); - } - }}; -} - -#[test] -fn ordinary() { - test_literal!(1.0); - test_literal!(3e-5); - test_literal!(0.1); - test_literal!(12345.); - test_literal!(0.9999999); - test_literal!(2.2250738585072014e-308); -} - -#[test] -fn special_code_paths() { - test_literal!(36893488147419103229.0); // 2^65 - 3, triggers half-to-even with even significand - test_literal!(101e-33); // Triggers the tricky underflow case in AlgorithmM (for f32) - test_literal!(1e23); // Triggers AlgorithmR - test_literal!(2075e23); // Triggers another path through AlgorithmR - test_literal!(8713e-23); // ... and yet another. -} - -#[test] -fn large() { - test_literal!(1e300); - test_literal!(123456789.34567e250); - test_literal!(943794359898089732078308743689303290943794359843568973207830874368930329.); -} - -#[test] -fn subnormals() { - test_literal!(5e-324); - test_literal!(91e-324); - test_literal!(1e-322); - test_literal!(13245643e-320); - test_literal!(2.22507385851e-308); - test_literal!(2.1e-308); - test_literal!(4.9406564584124654e-324); -} - -#[test] -fn infinity() { - test_literal!(1e400); - test_literal!(1e309); - test_literal!(2e308); - test_literal!(1.7976931348624e308); -} - -#[test] -fn zero() { - test_literal!(0.0); - test_literal!(1e-325); - test_literal!(1e-326); - test_literal!(1e-500); -} - -#[test] -fn fast_path_correct() { - // This number triggers the fast path and is handled incorrectly when compiling on - // x86 without SSE2 (i.e., using the x87 FPU stack). - test_literal!(1.448997445238699); -} - -#[test] -fn lonely_dot() { - assert!(".".parse::().is_err()); - assert!(".".parse::().is_err()); -} - -#[test] -fn exponentiated_dot() { - assert!(".e0".parse::().is_err()); - assert!(".e0".parse::().is_err()); -} - -#[test] -fn lonely_sign() { - assert!("+".parse::().is_err()); - assert!("-".parse::().is_err()); -} - -#[test] -fn whitespace() { - assert!(" 1.0".parse::().is_err()); - assert!("1.0 ".parse::().is_err()); -} - -#[test] -fn nan() { - assert!("NaN".parse::().unwrap().is_nan()); - assert!("NaN".parse::().unwrap().is_nan()); -} - -#[test] -fn inf() { - assert_eq!("inf".parse(), Ok(f64::INFINITY)); - assert_eq!("-inf".parse(), Ok(f64::NEG_INFINITY)); - assert_eq!("inf".parse(), Ok(f32::INFINITY)); - assert_eq!("-inf".parse(), Ok(f32::NEG_INFINITY)); -} - -#[test] -fn massive_exponent() { - let max = i64::MAX; - assert_eq!(format!("1e{max}000").parse(), Ok(f64::INFINITY)); - assert_eq!(format!("1e-{max}000").parse(), Ok(0.0)); - assert_eq!(format!("1e{max}000").parse(), Ok(f64::INFINITY)); -} diff --git a/library/core/tests/num/dec2flt/parse.rs b/library/core/tests/num/dec2flt/parse.rs deleted file mode 100644 index 4a5d24ba7d5fa..0000000000000 --- a/library/core/tests/num/dec2flt/parse.rs +++ /dev/null @@ -1,177 +0,0 @@ -use core::num::dec2flt::number::Number; -use core::num::dec2flt::parse::parse_number; -use core::num::dec2flt::{dec2flt, pfe_invalid}; - -fn new_number(e: i64, m: u64) -> Number { - Number { exponent: e, mantissa: m, negative: false, many_digits: false } -} - -#[test] -fn missing_pieces() { - let permutations = &[".e", "1e", "e4", "e", ".12e", "321.e", "32.12e+", "12.32e-"]; - for &s in permutations { - assert_eq!(dec2flt::(s), Err(pfe_invalid())); - } -} - -#[test] -fn invalid_chars() { - let invalid = "r,?(&input) == error, "did not reject invalid {:?}", input); - } - } - } -} - -fn parse_positive(s: &[u8]) -> Option { - parse_number(s) -} - -#[test] -fn valid() { - assert_eq!(parse_positive(b"123.456e789"), Some(new_number(786, 123456))); - assert_eq!(parse_positive(b"123.456e+789"), Some(new_number(786, 123456))); - assert_eq!(parse_positive(b"123.456e-789"), Some(new_number(-792, 123456))); - assert_eq!(parse_positive(b".050"), Some(new_number(-3, 50))); - assert_eq!(parse_positive(b"999"), Some(new_number(0, 999))); - assert_eq!(parse_positive(b"1.e300"), Some(new_number(300, 1))); - assert_eq!(parse_positive(b".1e300"), Some(new_number(299, 1))); - assert_eq!(parse_positive(b"101e-33"), Some(new_number(-33, 101))); - let zeros = "0".repeat(25); - let s = format!("1.5e{zeros}"); - assert_eq!(parse_positive(s.as_bytes()), Some(new_number(-1, 15))); -} - -macro_rules! assert_float_result_bits_eq { - ($bits:literal, $ty:ty, $str:literal) => {{ - let p = dec2flt::<$ty>($str); - assert_eq!(p.map(|x| x.to_bits()), Ok($bits)); - }}; -} - -#[test] -fn issue31109() { - // Regression test for #31109. - // Ensure the test produces a valid float with the expected bit pattern. - assert_float_result_bits_eq!( - 0x3fd5555555555555, - f64, - "0.3333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333333" - ); -} - -#[test] -fn issue31407() { - // Regression test for #31407. - // Ensure the test produces a valid float with the expected bit pattern. - assert_float_result_bits_eq!( - 0x1752a64e34ba0d3, - f64, - "1234567890123456789012345678901234567890e-340" - ); - assert_float_result_bits_eq!( - 0xfffffffffffff, - f64, - "2.225073858507201136057409796709131975934819546351645648023426109724822222021076945516529523908135087914149158913039621106870086438694594645527657207407820621743379988141063267329253552286881372149012981122451451889849057222307285255133155755015914397476397983411801999323962548289017107081850690630666655994938275772572015763062690663332647565300009245888316433037779791869612049497390377829704905051080609940730262937128958950003583799967207254304360284078895771796150945516748243471030702609144621572289880258182545180325707018860872113128079512233426288368622321503775666622503982534335974568884423900265498198385487948292206894721689831099698365846814022854243330660339850886445804001034933970427567186443383770486037861622771738545623065874679014086723327636718749999999999999999999999999999999999999e-308" - ); - assert_float_result_bits_eq!( - 0x10000000000000, - f64, - "2.22507385850720113605740979670913197593481954635164564802342610972482222202107694551652952390813508791414915891303962110687008643869459464552765720740782062174337998814106326732925355228688137214901298112245145188984905722230728525513315575501591439747639798341180199932396254828901710708185069063066665599493827577257201576306269066333264756530000924588831643303777979186961204949739037782970490505108060994073026293712895895000358379996720725430436028407889577179615094551674824347103070260914462157228988025818254518032570701886087211312807951223342628836862232150377566662250398253433597456888442390026549819838548794829220689472168983109969836584681402285424333066033985088644580400103493397042756718644338377048603786162277173854562306587467901408672332763671875e-308" - ); - assert_float_result_bits_eq!( - 0x10000000000000, - f64, - "0.0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000222507385850720138309023271733240406421921598046233183055332741688720443481391819585428315901251102056406733973103581100515243416155346010885601238537771882113077799353200233047961014744258363607192156504694250373420837525080665061665815894872049117996859163964850063590877011830487479978088775374994945158045160505091539985658247081864511353793580499211598108576605199243335211435239014879569960959128889160299264151106346631339366347758651302937176204732563178148566435087212282863764204484681140761391147706280168985324411002416144742161856716615054015428508471675290190316132277889672970737312333408698898317506783884692609277397797285865965494109136909540613646756870239867831529068098461721092462539672851562500000000000000001" - ); - assert_float_result_bits_eq!( - 0x7fefffffffffffff, - f64, - "179769313486231580793728971405303415079934132710037826936173778980444968292764750946649017977587207096330286416692887910946555547851940402630657488671505820681908902000708383676273854845817711531764475730270069855571366959622842914819860834936475292719074168444365510704342711559699508093042880177904174497791.9999999999999999999999999999999999999999999999999999999999999999999999" - ); - assert_float_result_bits_eq!(0x0, f64, "2.47032822920623272e-324"); - assert_float_result_bits_eq!( - 0x8000000, - f64, - "6.631236871469758276785396630275967243399099947355303144249971758736286630139265439618068200788048744105960420552601852889715006376325666595539603330361800519107591783233358492337208057849499360899425128640718856616503093444922854759159988160304439909868291973931426625698663157749836252274523485312442358651207051292453083278116143932569727918709786004497872322193856150225415211997283078496319412124640111777216148110752815101775295719811974338451936095907419622417538473679495148632480391435931767981122396703443803335529756003353209830071832230689201383015598792184172909927924176339315507402234836120730914783168400715462440053817592702766213559042115986763819482654128770595766806872783349146967171293949598850675682115696218943412532098591327667236328125E-316" - ); - assert_float_result_bits_eq!( - 0x10000, - f64, - "3.237883913302901289588352412501532174863037669423108059901297049552301970670676565786835742587799557860615776559838283435514391084153169252689190564396459577394618038928365305143463955100356696665629202017331344031730044369360205258345803431471660032699580731300954848363975548690010751530018881758184174569652173110473696022749934638425380623369774736560008997404060967498028389191878963968575439222206416981462690113342524002724385941651051293552601421155333430225237291523843322331326138431477823591142408800030775170625915670728657003151953664260769822494937951845801530895238439819708403389937873241463484205608000027270531106827387907791444918534771598750162812548862768493201518991668028251730299953143924168545708663913273994694463908672332763671875E-319" - ); - assert_float_result_bits_eq!( - 0x800000000100, - f64, - "6.953355807847677105972805215521891690222119817145950754416205607980030131549636688806115726399441880065386399864028691275539539414652831584795668560082999889551357784961446896042113198284213107935110217162654939802416034676213829409720583759540476786936413816541621287843248433202369209916612249676005573022703244799714622116542188837770376022371172079559125853382801396219552418839469770514904192657627060319372847562301074140442660237844114174497210955449896389180395827191602886654488182452409583981389442783377001505462015745017848754574668342161759496661766020028752888783387074850773192997102997936619876226688096314989645766000479009083731736585750335262099860150896718774401964796827166283225641992040747894382698751809812609536720628966577351093292236328125E-310" - ); - assert_float_result_bits_eq!( - 0x10800, - f64, - "3.339068557571188581835713701280943911923401916998521771655656997328440314559615318168849149074662609099998113009465566426808170378434065722991659642619467706034884424989741080790766778456332168200464651593995817371782125010668346652995912233993254584461125868481633343674905074271064409763090708017856584019776878812425312008812326260363035474811532236853359905334625575404216060622858633280744301892470300555678734689978476870369853549413277156622170245846166991655321535529623870646888786637528995592800436177901746286272273374471701452991433047257863864601424252024791567368195056077320885329384322332391564645264143400798619665040608077549162173963649264049738362290606875883456826586710961041737908872035803481241600376705491726170293986797332763671875E-319" - ); - assert_float_result_bits_eq!( - 0x0, - f64, - "2.4703282292062327208828439643411068618252990130716238221279284125033775363510437593264991818081799618989828234772285886546332835517796989819938739800539093906315035659515570226392290858392449105184435931802849936536152500319370457678249219365623669863658480757001585769269903706311928279558551332927834338409351978015531246597263579574622766465272827220056374006485499977096599470454020828166226237857393450736339007967761930577506740176324673600968951340535537458516661134223766678604162159680461914467291840300530057530849048765391711386591646239524912623653881879636239373280423891018672348497668235089863388587925628302755995657524455507255189313690836254779186948667994968324049705821028513185451396213837722826145437693412532098591327667236328124999e-324" - ); - assert_float_result_bits_eq!( - 0x0, - f64, - "2.4703282292062327208828439643411068618252990130716238221279284125033775363510437593264991818081799618989828234772285886546332835517796989819938739800539093906315035659515570226392290858392449105184435931802849936536152500319370457678249219365623669863658480757001585769269903706311928279558551332927834338409351978015531246597263579574622766465272827220056374006485499977096599470454020828166226237857393450736339007967761930577506740176324673600968951340535537458516661134223766678604162159680461914467291840300530057530849048765391711386591646239524912623653881879636239373280423891018672348497668235089863388587925628302755995657524455507255189313690836254779186948667994968324049705821028513185451396213837722826145437693412532098591327667236328125e-324" - ); - assert_float_result_bits_eq!( - 0x1, - f64, - "2.4703282292062327208828439643411068618252990130716238221279284125033775363510437593264991818081799618989828234772285886546332835517796989819938739800539093906315035659515570226392290858392449105184435931802849936536152500319370457678249219365623669863658480757001585769269903706311928279558551332927834338409351978015531246597263579574622766465272827220056374006485499977096599470454020828166226237857393450736339007967761930577506740176324673600968951340535537458516661134223766678604162159680461914467291840300530057530849048765391711386591646239524912623653881879636239373280423891018672348497668235089863388587925628302755995657524455507255189313690836254779186948667994968324049705821028513185451396213837722826145437693412532098591327667236328125001e-324" - ); - assert_float_result_bits_eq!( - 0x1, - f64, - "7.4109846876186981626485318930233205854758970392148714663837852375101326090531312779794975454245398856969484704316857659638998506553390969459816219401617281718945106978546710679176872575177347315553307795408549809608457500958111373034747658096871009590975442271004757307809711118935784838675653998783503015228055934046593739791790738723868299395818481660169122019456499931289798411362062484498678713572180352209017023903285791732520220528974020802906854021606612375549983402671300035812486479041385743401875520901590172592547146296175134159774938718574737870961645638908718119841271673056017045493004705269590165763776884908267986972573366521765567941072508764337560846003984904972149117463085539556354188641513168478436313080237596295773983001708984374999e-324" - ); - assert_float_result_bits_eq!( - 0x2, - f64, - "7.4109846876186981626485318930233205854758970392148714663837852375101326090531312779794975454245398856969484704316857659638998506553390969459816219401617281718945106978546710679176872575177347315553307795408549809608457500958111373034747658096871009590975442271004757307809711118935784838675653998783503015228055934046593739791790738723868299395818481660169122019456499931289798411362062484498678713572180352209017023903285791732520220528974020802906854021606612375549983402671300035812486479041385743401875520901590172592547146296175134159774938718574737870961645638908718119841271673056017045493004705269590165763776884908267986972573366521765567941072508764337560846003984904972149117463085539556354188641513168478436313080237596295773983001708984375e-324" - ); - assert_float_result_bits_eq!( - 0x2, - f64, - "7.4109846876186981626485318930233205854758970392148714663837852375101326090531312779794975454245398856969484704316857659638998506553390969459816219401617281718945106978546710679176872575177347315553307795408549809608457500958111373034747658096871009590975442271004757307809711118935784838675653998783503015228055934046593739791790738723868299395818481660169122019456499931289798411362062484498678713572180352209017023903285791732520220528974020802906854021606612375549983402671300035812486479041385743401875520901590172592547146296175134159774938718574737870961645638908718119841271673056017045493004705269590165763776884908267986972573366521765567941072508764337560846003984904972149117463085539556354188641513168478436313080237596295773983001708984375001e-324" - ); - assert_float_result_bits_eq!( - 0x6c9a143590c14, - f64, - "94393431193180696942841837085033647913224148539854e-358" - ); - assert_float_result_bits_eq!( - 0x7802665fd9600, - f64, - "104308485241983990666713401708072175773165034278685682646111762292409330928739751702404658197872319129036519947435319418387839758990478549477777586673075945844895981012024387992135617064532141489278815239849108105951619997829153633535314849999674266169258928940692239684771590065027025835804863585454872499320500023126142553932654370362024104462255244034053203998964360882487378334860197725139151265590832887433736189468858614521708567646743455601905935595381852723723645799866672558576993978025033590728687206296379801363024094048327273913079612469982585674824156000783167963081616214710691759864332339239688734656548790656486646106983450809073750535624894296242072010195710276073042036425579852459556183541199012652571123898996574563824424330960027873516082763671875e-1075" - ); -} - -#[test] -fn many_digits() { - // Check large numbers of digits to ensure we have cases where significant - // digits (above Decimal::MAX_DIGITS) occurs. - assert_float_result_bits_eq!( - 0x7ffffe, - f32, - "1.175494140627517859246175898662808184331245864732796240031385942718174675986064769972472277004271745681762695312500000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000e-38" - ); - assert_float_result_bits_eq!( - 0x7ffffe, - f32, - "1.175494140627517859246175898662808184331245864732796240031385942718174675986064769972472277004271745681762695312500000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000e-38" - ); -} diff --git a/library/core/tests/num/flt2dec/estimator.rs b/library/core/tests/num/flt2dec/estimator.rs deleted file mode 100644 index da203b5f3620e..0000000000000 --- a/library/core/tests/num/flt2dec/estimator.rs +++ /dev/null @@ -1,62 +0,0 @@ -use core::num::flt2dec::estimator::*; - -#[test] -fn test_estimate_scaling_factor() { - macro_rules! assert_almost_eq { - ($actual:expr, $expected:expr) => {{ - let actual = $actual; - let expected = $expected; - println!( - "{} - {} = {} - {} = {}", - stringify!($expected), - stringify!($actual), - expected, - actual, - expected - actual - ); - assert!( - expected == actual || expected == actual + 1, - "expected {}, actual {}", - expected, - actual - ); - }}; - } - - assert_almost_eq!(estimate_scaling_factor(1, 0), 0); - assert_almost_eq!(estimate_scaling_factor(2, 0), 1); - assert_almost_eq!(estimate_scaling_factor(10, 0), 1); - assert_almost_eq!(estimate_scaling_factor(11, 0), 2); - assert_almost_eq!(estimate_scaling_factor(100, 0), 2); - assert_almost_eq!(estimate_scaling_factor(101, 0), 3); - assert_almost_eq!(estimate_scaling_factor(10000000000000000000, 0), 19); - assert_almost_eq!(estimate_scaling_factor(10000000000000000001, 0), 20); - - // 1/2^20 = 0.00000095367... - assert_almost_eq!(estimate_scaling_factor(1 * 1048576 / 1000000, -20), -6); - assert_almost_eq!(estimate_scaling_factor(1 * 1048576 / 1000000 + 1, -20), -5); - assert_almost_eq!(estimate_scaling_factor(10 * 1048576 / 1000000, -20), -5); - assert_almost_eq!(estimate_scaling_factor(10 * 1048576 / 1000000 + 1, -20), -4); - assert_almost_eq!(estimate_scaling_factor(100 * 1048576 / 1000000, -20), -4); - assert_almost_eq!(estimate_scaling_factor(100 * 1048576 / 1000000 + 1, -20), -3); - assert_almost_eq!(estimate_scaling_factor(1048575, -20), 0); - assert_almost_eq!(estimate_scaling_factor(1048576, -20), 0); - assert_almost_eq!(estimate_scaling_factor(1048577, -20), 1); - assert_almost_eq!(estimate_scaling_factor(10485759999999999999, -20), 13); - assert_almost_eq!(estimate_scaling_factor(10485760000000000000, -20), 13); - assert_almost_eq!(estimate_scaling_factor(10485760000000000001, -20), 14); - - // extreme values: - // 2^-1074 = 4.94065... * 10^-324 - // (2^53-1) * 2^971 = 1.79763... * 10^308 - assert_almost_eq!(estimate_scaling_factor(1, -1074), -323); - assert_almost_eq!(estimate_scaling_factor(0x1fffffffffffff, 971), 309); - - // Miri is too slow - let step = if cfg!(miri) { 37 } else { 1 }; - - for i in (-1074..972).step_by(step) { - let expected = super::ldexp_f64(1.0, i).log10().ceil(); - assert_almost_eq!(estimate_scaling_factor(1, i as i16), expected as i16); - } -} diff --git a/library/core/tests/num/flt2dec/mod.rs b/library/core/tests/num/flt2dec/mod.rs deleted file mode 100644 index 83e2707b57e8b..0000000000000 --- a/library/core/tests/num/flt2dec/mod.rs +++ /dev/null @@ -1,1170 +0,0 @@ -use std::mem::MaybeUninit; -use std::{fmt, str}; - -use core::num::flt2dec::{decode, DecodableFloat, Decoded, FullDecoded}; -use core::num::flt2dec::{round_up, Sign, MAX_SIG_DIGITS}; -use core::num::flt2dec::{ - to_exact_exp_str, to_exact_fixed_str, to_shortest_exp_str, to_shortest_str, -}; -use core::num::fmt::{Formatted, Part}; - -mod estimator; -mod strategy { - mod dragon; - mod grisu; -} -mod random; - -pub fn decode_finite(v: T) -> Decoded { - match decode(v).1 { - FullDecoded::Finite(decoded) => decoded, - full_decoded => panic!("expected finite, got {full_decoded:?} instead"), - } -} - -macro_rules! check_shortest { - ($f:ident($v:expr) => $buf:expr, $exp:expr) => ( - check_shortest!($f($v) => $buf, $exp; - "shortest mismatch for v={v}: actual {actual:?}, expected {expected:?}", - v = stringify!($v)) - ); - - ($f:ident{$($k:ident: $v:expr),+} => $buf:expr, $exp:expr) => ( - check_shortest!($f{$($k: $v),+} => $buf, $exp; - "shortest mismatch for {v:?}: actual {actual:?}, expected {expected:?}", - v = Decoded { $($k: $v),+ }) - ); - - ($f:ident($v:expr) => $buf:expr, $exp:expr; $fmt:expr, $($key:ident = $val:expr),*) => ({ - let mut buf = [MaybeUninit::new(b'_'); MAX_SIG_DIGITS]; - let (buf, k) = $f(&decode_finite($v), &mut buf); - assert!((buf, k) == ($buf, $exp), - $fmt, actual = (str::from_utf8(buf).unwrap(), k), - expected = (str::from_utf8($buf).unwrap(), $exp), - $($key = $val),*); - }); - - ($f:ident{$($k:ident: $v:expr),+} => $buf:expr, $exp:expr; - $fmt:expr, $($key:ident = $val:expr),*) => ({ - let mut buf = [MaybeUninit::new(b'_'); MAX_SIG_DIGITS]; - let (buf, k) = $f(&Decoded { $($k: $v),+ }, &mut buf); - assert!((buf, k) == ($buf, $exp), - $fmt, actual = (str::from_utf8(buf).unwrap(), k), - expected = (str::from_utf8($buf).unwrap(), $exp), - $($key = $val),*); - }) -} - -macro_rules! try_exact { - ($f:ident($decoded:expr) => $buf:expr, $expected:expr, $expectedk:expr; - $fmt:expr, $($key:ident = $val:expr),*) => ({ - let (buf, k) = $f($decoded, &mut $buf[..$expected.len()], i16::MIN); - assert!((buf, k) == ($expected, $expectedk), - $fmt, actual = (str::from_utf8(buf).unwrap(), k), - expected = (str::from_utf8($expected).unwrap(), $expectedk), - $($key = $val),*); - }) -} - -macro_rules! try_fixed { - ($f:ident($decoded:expr) => $buf:expr, $request:expr, $expected:expr, $expectedk:expr; - $fmt:expr, $($key:ident = $val:expr),*) => ({ - let (buf, k) = $f($decoded, &mut $buf[..], $request); - assert!((buf, k) == ($expected, $expectedk), - $fmt, actual = (str::from_utf8(buf).unwrap(), k), - expected = (str::from_utf8($expected).unwrap(), $expectedk), - $($key = $val),*); - }) -} - -fn ldexp_f32(a: f32, b: i32) -> f32 { - ldexp_f64(a as f64, b) as f32 -} - -fn ldexp_f64(a: f64, b: i32) -> f64 { - extern "C" { - fn ldexp(x: f64, n: i32) -> f64; - } - // SAFETY: assuming a correct `ldexp` has been supplied, the given arguments cannot possibly - // cause undefined behavior - unsafe { ldexp(a, b) } -} - -fn check_exact(mut f: F, v: T, vstr: &str, expected: &[u8], expectedk: i16) -where - T: DecodableFloat, - F: for<'a> FnMut(&Decoded, &'a mut [MaybeUninit], i16) -> (&'a [u8], i16), -{ - // use a large enough buffer - let mut buf = [MaybeUninit::new(b'_'); 1024]; - let mut expected_ = [b'_'; 1024]; - - let decoded = decode_finite(v); - let cut = expected.iter().position(|&c| c == b' '); - - // check significant digits - for i in 1..cut.unwrap_or(expected.len() - 1) { - expected_[..i].copy_from_slice(&expected[..i]); - let mut expectedk_ = expectedk; - if expected[i] >= b'5' { - // check if this is a rounding-to-even case. - // we avoid rounding ...x5000... (with infinite zeroes) to ...(x+1) when x is even. - if !(i + 1 < expected.len() - && expected[i - 1] & 1 == 0 - && expected[i] == b'5' - && expected[i + 1] == b' ') - { - // if this returns true, expected_[..i] is all `9`s and being rounded up. - // we should always return `100..00` (`i` digits) instead, since that's - // what we can came up with `i` digits anyway. `round_up` assumes that - // the adjustment to the length is done by caller, which we simply ignore. - if let Some(_) = round_up(&mut expected_[..i]) { - expectedk_ += 1; - } - } - } - - try_exact!(f(&decoded) => &mut buf, &expected_[..i], expectedk_; - "exact sigdigit mismatch for v={v}, i={i}: \ - actual {actual:?}, expected {expected:?}", - v = vstr, i = i); - try_fixed!(f(&decoded) => &mut buf, expectedk_ - i as i16, &expected_[..i], expectedk_; - "fixed sigdigit mismatch for v={v}, i={i}: \ - actual {actual:?}, expected {expected:?}", - v = vstr, i = i); - } - - // check exact rounding for zero- and negative-width cases - let start; - if expected[0] > b'5' { - try_fixed!(f(&decoded) => &mut buf, expectedk, b"1", expectedk + 1; - "zero-width rounding-up mismatch for v={v}: \ - actual {actual:?}, expected {expected:?}", - v = vstr); - start = 1; - } else { - start = 0; - } - for i in start..-10 { - try_fixed!(f(&decoded) => &mut buf, expectedk - i, b"", expectedk; - "rounding-down mismatch for v={v}, i={i}: \ - actual {actual:?}, expected {expected:?}", - v = vstr, i = -i); - } - - // check infinite zero digits - if let Some(cut) = cut { - for i in cut..expected.len() - 1 { - expected_[..cut].copy_from_slice(&expected[..cut]); - for c in &mut expected_[cut..i] { - *c = b'0'; - } - - try_exact!(f(&decoded) => &mut buf, &expected_[..i], expectedk; - "exact infzero mismatch for v={v}, i={i}: \ - actual {actual:?}, expected {expected:?}", - v = vstr, i = i); - try_fixed!(f(&decoded) => &mut buf, expectedk - i as i16, &expected_[..i], expectedk; - "fixed infzero mismatch for v={v}, i={i}: \ - actual {actual:?}, expected {expected:?}", - v = vstr, i = i); - } - } -} - -trait TestableFloat: DecodableFloat + fmt::Display { - /// Returns `x * 2^exp`. Almost same to `std::{f32,f64}::ldexp`. - /// This is used for testing. - fn ldexpi(f: i64, exp: isize) -> Self; -} - -impl TestableFloat for f32 { - fn ldexpi(f: i64, exp: isize) -> Self { - f as Self * (exp as Self).exp2() - } -} - -impl TestableFloat for f64 { - fn ldexpi(f: i64, exp: isize) -> Self { - f as Self * (exp as Self).exp2() - } -} - -fn check_exact_one(mut f: F, x: i64, e: isize, tstr: &str, expected: &[u8], expectedk: i16) -where - T: TestableFloat, - F: for<'a> FnMut(&Decoded, &'a mut [MaybeUninit], i16) -> (&'a [u8], i16), -{ - // use a large enough buffer - let mut buf = [MaybeUninit::new(b'_'); 1024]; - let v: T = TestableFloat::ldexpi(x, e); - let decoded = decode_finite(v); - - try_exact!(f(&decoded) => &mut buf, &expected, expectedk; - "exact mismatch for v={x}p{e}{t}: actual {actual:?}, expected {expected:?}", - x = x, e = e, t = tstr); - try_fixed!(f(&decoded) => &mut buf, expectedk - expected.len() as i16, &expected, expectedk; - "fixed mismatch for v={x}p{e}{t}: actual {actual:?}, expected {expected:?}", - x = x, e = e, t = tstr); -} - -macro_rules! check_exact { - ($f:ident($v:expr) => $buf:expr, $exp:expr) => { - check_exact(|d, b, k| $f(d, b, k), $v, stringify!($v), $buf, $exp) - }; -} - -macro_rules! check_exact_one { - ($f:ident($x:expr, $e:expr; $t:ty) => $buf:expr, $exp:expr) => { - check_exact_one::<_, $t>(|d, b, k| $f(d, b, k), $x, $e, stringify!($t), $buf, $exp) - }; -} - -// in the following comments, three numbers are spaced by 1 ulp apart, -// and the second one is being formatted. -// -// some tests are derived from [1]. -// -// [1] Vern Paxson, A Program for Testing IEEE Decimal-Binary Conversion -// ftp://ftp.ee.lbl.gov/testbase-report.ps.Z - -pub fn f32_shortest_sanity_test(mut f: F) -where - F: for<'a> FnMut(&Decoded, &'a mut [MaybeUninit]) -> (&'a [u8], i16), -{ - // 0.0999999940395355224609375 - // 0.100000001490116119384765625 - // 0.10000000894069671630859375 - check_shortest!(f(0.1f32) => b"1", 0); - - // 0.333333313465118408203125 - // 0.3333333432674407958984375 (1/3 in the default rounding) - // 0.33333337306976318359375 - check_shortest!(f(1.0f32/3.0) => b"33333334", 0); - - // 10^1 * 0.31415917873382568359375 - // 10^1 * 0.31415920257568359375 - // 10^1 * 0.31415922641754150390625 - check_shortest!(f(3.141592f32) => b"3141592", 1); - - // 10^18 * 0.31415916243714048 - // 10^18 * 0.314159196796878848 - // 10^18 * 0.314159231156617216 - check_shortest!(f(3.141592e17f32) => b"3141592", 18); - - // regression test for decoders - // 10^8 * 0.3355443 - // 10^8 * 0.33554432 - // 10^8 * 0.33554436 - check_shortest!(f(ldexp_f32(1.0, 25)) => b"33554432", 8); - - // 10^39 * 0.340282326356119256160033759537265639424 - // 10^39 * 0.34028234663852885981170418348451692544 - // 10^39 * 0.340282366920938463463374607431768211456 - check_shortest!(f(f32::MAX) => b"34028235", 39); - - // 10^-37 * 0.1175494210692441075487029444849287348827... - // 10^-37 * 0.1175494350822287507968736537222245677818... - // 10^-37 * 0.1175494490952133940450443629595204006810... - check_shortest!(f(f32::MIN_POSITIVE) => b"11754944", -37); - - // 10^-44 * 0 - // 10^-44 * 0.1401298464324817070923729583289916131280... - // 10^-44 * 0.2802596928649634141847459166579832262560... - let minf32 = ldexp_f32(1.0, -149); - check_shortest!(f(minf32) => b"1", -44); -} - -pub fn f32_exact_sanity_test(mut f: F) -where - F: for<'a> FnMut(&Decoded, &'a mut [MaybeUninit], i16) -> (&'a [u8], i16), -{ - let minf32 = ldexp_f32(1.0, -149); - - check_exact!(f(0.1f32) => b"100000001490116119384765625 ", 0); - check_exact!(f(0.5f32) => b"5 ", 0); - check_exact!(f(1.0f32/3.0) => b"3333333432674407958984375 ", 0); - check_exact!(f(3.141592f32) => b"31415920257568359375 ", 1); - check_exact!(f(3.141592e17f32) => b"314159196796878848 ", 18); - check_exact!(f(f32::MAX) => b"34028234663852885981170418348451692544 ", 39); - check_exact!(f(f32::MIN_POSITIVE) => b"1175494350822287507968736537222245677818", -37); - check_exact!(f(minf32) => b"1401298464324817070923729583289916131280", -44); - - // [1], Table 16: Stress Inputs for Converting 24-bit Binary to Decimal, < 1/2 ULP - check_exact_one!(f(12676506, -102; f32) => b"2", -23); - check_exact_one!(f(12676506, -103; f32) => b"12", -23); - check_exact_one!(f(15445013, 86; f32) => b"119", 34); - check_exact_one!(f(13734123, -138; f32) => b"3941", -34); - check_exact_one!(f(12428269, -130; f32) => b"91308", -32); - check_exact_one!(f(15334037, -146; f32) => b"171900", -36); - check_exact_one!(f(11518287, -41; f32) => b"5237910", -5); - check_exact_one!(f(12584953, -145; f32) => b"28216440", -36); - check_exact_one!(f(15961084, -125; f32) => b"375243281", -30); - check_exact_one!(f(14915817, -146; f32) => b"1672120916", -36); - check_exact_one!(f(10845484, -102; f32) => b"21388945814", -23); - check_exact_one!(f(16431059, -61; f32) => b"712583594561", -11); - - // [1], Table 17: Stress Inputs for Converting 24-bit Binary to Decimal, > 1/2 ULP - check_exact_one!(f(16093626, 69; f32) => b"1", 29); - check_exact_one!(f( 9983778, 25; f32) => b"34", 15); - check_exact_one!(f(12745034, 104; f32) => b"259", 39); - check_exact_one!(f(12706553, 72; f32) => b"6001", 29); - check_exact_one!(f(11005028, 45; f32) => b"38721", 21); - check_exact_one!(f(15059547, 71; f32) => b"355584", 29); - check_exact_one!(f(16015691, -99; f32) => b"2526831", -22); - check_exact_one!(f( 8667859, 56; f32) => b"62458507", 24); - check_exact_one!(f(14855922, -82; f32) => b"307213267", -17); - check_exact_one!(f(14855922, -83; f32) => b"1536066333", -17); - check_exact_one!(f(10144164, -110; f32) => b"78147796834", -26); - check_exact_one!(f(13248074, 95; f32) => b"524810279937", 36); -} - -pub fn f64_shortest_sanity_test(mut f: F) -where - F: for<'a> FnMut(&Decoded, &'a mut [MaybeUninit]) -> (&'a [u8], i16), -{ - // 0.0999999999999999777955395074968691915273... - // 0.1000000000000000055511151231257827021181... - // 0.1000000000000000333066907387546962127089... - check_shortest!(f(0.1f64) => b"1", 0); - - // this example is explicitly mentioned in the paper. - // 10^3 * 0.0999999999999999857891452847979962825775... - // 10^3 * 0.1 (exact) - // 10^3 * 0.1000000000000000142108547152020037174224... - check_shortest!(f(100.0f64) => b"1", 3); - - // 0.3333333333333332593184650249895639717578... - // 0.3333333333333333148296162562473909929394... (1/3 in the default rounding) - // 0.3333333333333333703407674875052180141210... - check_shortest!(f(1.0f64/3.0) => b"3333333333333333", 0); - - // explicit test case for equally closest representations. - // Dragon has its own tie-breaking rule; Grisu should fall back. - // 10^1 * 0.1000007629394531027955395074968691915273... - // 10^1 * 0.100000762939453125 (exact) - // 10^1 * 0.1000007629394531472044604925031308084726... - check_shortest!(f(1.00000762939453125f64) => b"10000076293945313", 1); - - // 10^1 * 0.3141591999999999718085064159822650253772... - // 10^1 * 0.3141592000000000162174274009885266423225... - // 10^1 * 0.3141592000000000606263483859947882592678... - check_shortest!(f(3.141592f64) => b"3141592", 1); - - // 10^18 * 0.314159199999999936 - // 10^18 * 0.3141592 (exact) - // 10^18 * 0.314159200000000064 - check_shortest!(f(3.141592e17f64) => b"3141592", 18); - - // regression test for decoders - // 10^20 * 0.18446744073709549568 - // 10^20 * 0.18446744073709551616 - // 10^20 * 0.18446744073709555712 - check_shortest!(f(ldexp_f64(1.0, 64)) => b"18446744073709552", 20); - - // pathological case: high = 10^23 (exact). tie breaking should always prefer that. - // 10^24 * 0.099999999999999974834176 - // 10^24 * 0.099999999999999991611392 - // 10^24 * 0.100000000000000008388608 - check_shortest!(f(1.0e23f64) => b"1", 24); - - // 10^309 * 0.1797693134862315508561243283845062402343... - // 10^309 * 0.1797693134862315708145274237317043567980... - // 10^309 * 0.1797693134862315907729305190789024733617... - check_shortest!(f(f64::MAX) => b"17976931348623157", 309); - - // 10^-307 * 0.2225073858507200889024586876085859887650... - // 10^-307 * 0.2225073858507201383090232717332404064219... - // 10^-307 * 0.2225073858507201877155878558578948240788... - check_shortest!(f(f64::MIN_POSITIVE) => b"22250738585072014", -307); - - // 10^-323 * 0 - // 10^-323 * 0.4940656458412465441765687928682213723650... - // 10^-323 * 0.9881312916824930883531375857364427447301... - let minf64 = ldexp_f64(1.0, -1074); - check_shortest!(f(minf64) => b"5", -323); -} - -pub fn f64_exact_sanity_test(mut f: F) -where - F: for<'a> FnMut(&Decoded, &'a mut [MaybeUninit], i16) -> (&'a [u8], i16), -{ - let minf64 = ldexp_f64(1.0, -1074); - - check_exact!(f(0.1f64) => b"1000000000000000055511151231257827021181", 0); - check_exact!(f(0.45f64) => b"4500000000000000111022302462515654042363", 0); - check_exact!(f(0.5f64) => b"5 ", 0); - check_exact!(f(0.95f64) => b"9499999999999999555910790149937383830547", 0); - check_exact!(f(100.0f64) => b"1 ", 3); - check_exact!(f(999.5f64) => b"9995000000000000000000000000000000000000", 3); - check_exact!(f(1.0f64/3.0) => b"3333333333333333148296162562473909929394", 0); - check_exact!(f(3.141592f64) => b"3141592000000000162174274009885266423225", 1); - check_exact!(f(3.141592e17f64) => b"3141592 ", 18); - check_exact!(f(1.0e23f64) => b"99999999999999991611392 ", 23); - check_exact!(f(f64::MAX) => b"1797693134862315708145274237317043567980", 309); - check_exact!(f(f64::MIN_POSITIVE) => b"2225073858507201383090232717332404064219", -307); - check_exact!(f(minf64) => b"4940656458412465441765687928682213723650\ - 5980261432476442558568250067550727020875\ - 1865299836361635992379796564695445717730\ - 9266567103559397963987747960107818781263\ - 0071319031140452784581716784898210368871\ - 8636056998730723050006387409153564984387\ - 3124733972731696151400317153853980741262\ - 3856559117102665855668676818703956031062\ - 4931945271591492455329305456544401127480\ - 1297099995419319894090804165633245247571\ - 4786901472678015935523861155013480352649\ - 3472019379026810710749170333222684475333\ - 5720832431936092382893458368060106011506\ - 1698097530783422773183292479049825247307\ - 7637592724787465608477820373446969953364\ - 7017972677717585125660551199131504891101\ - 4510378627381672509558373897335989936648\ - 0994116420570263709027924276754456522908\ - 7538682506419718265533447265625 ", -323); - - // [1], Table 3: Stress Inputs for Converting 53-bit Binary to Decimal, < 1/2 ULP - check_exact_one!(f(8511030020275656, -342; f64) => b"9", -87); - check_exact_one!(f(5201988407066741, -824; f64) => b"46", -232); - check_exact_one!(f(6406892948269899, 237; f64) => b"141", 88); - check_exact_one!(f(8431154198732492, 72; f64) => b"3981", 38); - check_exact_one!(f(6475049196144587, 99; f64) => b"41040", 46); - check_exact_one!(f(8274307542972842, 726; f64) => b"292084", 235); - check_exact_one!(f(5381065484265332, -456; f64) => b"2891946", -121); - check_exact_one!(f(6761728585499734, -1057; f64) => b"43787718", -302); - check_exact_one!(f(7976538478610756, 376; f64) => b"122770163", 130); - check_exact_one!(f(5982403858958067, 377; f64) => b"1841552452", 130); - check_exact_one!(f(5536995190630837, 93; f64) => b"54835744350", 44); - check_exact_one!(f(7225450889282194, 710; f64) => b"389190181146", 230); - check_exact_one!(f(7225450889282194, 709; f64) => b"1945950905732", 230); - check_exact_one!(f(8703372741147379, 117; f64) => b"14460958381605", 52); - check_exact_one!(f(8944262675275217, -1001; f64) => b"417367747458531", -285); - check_exact_one!(f(7459803696087692, -707; f64) => b"1107950772878888", -196); - check_exact_one!(f(6080469016670379, -381; f64) => b"12345501366327440", -98); - check_exact_one!(f(8385515147034757, 721; f64) => b"925031711960365024", 233); - check_exact_one!(f(7514216811389786, -828; f64) => b"4198047150284889840", -233); - check_exact_one!(f(8397297803260511, -345; f64) => b"11716315319786511046", -87); - check_exact_one!(f(6733459239310543, 202; f64) => b"432810072844612493629", 77); - check_exact_one!(f(8091450587292794, -473; f64) => b"3317710118160031081518", -126); - - // [1], Table 4: Stress Inputs for Converting 53-bit Binary to Decimal, > 1/2 ULP - check_exact_one!(f(6567258882077402, 952; f64) => b"3", 303); - check_exact_one!(f(6712731423444934, 535; f64) => b"76", 177); - check_exact_one!(f(6712731423444934, 534; f64) => b"378", 177); - check_exact_one!(f(5298405411573037, -957; f64) => b"4350", -272); - check_exact_one!(f(5137311167659507, -144; f64) => b"23037", -27); - check_exact_one!(f(6722280709661868, 363; f64) => b"126301", 126); - check_exact_one!(f(5344436398034927, -169; f64) => b"7142211", -35); - check_exact_one!(f(8369123604277281, -853; f64) => b"13934574", -240); - check_exact_one!(f(8995822108487663, -780; f64) => b"141463449", -218); - check_exact_one!(f(8942832835564782, -383; f64) => b"4539277920", -99); - check_exact_one!(f(8942832835564782, -384; f64) => b"22696389598", -99); - check_exact_one!(f(8942832835564782, -385; f64) => b"113481947988", -99); - check_exact_one!(f(6965949469487146, -249; f64) => b"7700366561890", -59); - check_exact_one!(f(6965949469487146, -250; f64) => b"38501832809448", -59); - check_exact_one!(f(6965949469487146, -251; f64) => b"192509164047238", -59); - check_exact_one!(f(7487252720986826, 548; f64) => b"6898586531774201", 181); - check_exact_one!(f(5592117679628511, 164; f64) => b"13076622631878654", 66); - check_exact_one!(f(8887055249355788, 665; f64) => b"136052020756121240", 217); - check_exact_one!(f(6994187472632449, 690; f64) => b"3592810217475959676", 224); - check_exact_one!(f(8797576579012143, 588; f64) => b"89125197712484551899", 193); - check_exact_one!(f(7363326733505337, 272; f64) => b"558769757362301140950", 98); - check_exact_one!(f(8549497411294502, -448; f64) => b"1176257830728540379990", -118); -} - -pub fn more_shortest_sanity_test(mut f: F) -where - F: for<'a> FnMut(&Decoded, &'a mut [MaybeUninit]) -> (&'a [u8], i16), -{ - check_shortest!(f{mant: 99_999_999_999_999_999, minus: 1, plus: 1, - exp: 0, inclusive: true} => b"1", 18); - check_shortest!(f{mant: 99_999_999_999_999_999, minus: 1, plus: 1, - exp: 0, inclusive: false} => b"99999999999999999", 17); -} - -fn to_string_with_parts(mut f: F) -> String -where - F: for<'a> FnMut(&'a mut [MaybeUninit], &'a mut [MaybeUninit>]) -> Formatted<'a>, -{ - let mut buf = [MaybeUninit::new(0); 1024]; - let mut parts = [MaybeUninit::new(Part::Zero(0)); 16]; - let formatted = f(&mut buf, &mut parts); - let mut ret = vec![0; formatted.len()]; - assert_eq!(formatted.write(&mut ret), Some(ret.len())); - String::from_utf8(ret).unwrap() -} - -pub fn to_shortest_str_test(mut f_: F) -where - F: for<'a> FnMut(&Decoded, &'a mut [MaybeUninit]) -> (&'a [u8], i16), -{ - use core::num::flt2dec::Sign::*; - - fn to_string(f: &mut F, v: T, sign: Sign, frac_digits: usize) -> String - where - T: DecodableFloat, - F: for<'a> FnMut(&Decoded, &'a mut [MaybeUninit]) -> (&'a [u8], i16), - { - to_string_with_parts(|buf, parts| { - to_shortest_str(|d, b| f(d, b), v, sign, frac_digits, buf, parts) - }) - } - - let f = &mut f_; - - assert_eq!(to_string(f, 0.0, Minus, 0), "0"); - assert_eq!(to_string(f, 0.0, Minus, 0), "0"); - assert_eq!(to_string(f, 0.0, MinusPlus, 0), "+0"); - assert_eq!(to_string(f, -0.0, Minus, 0), "-0"); - assert_eq!(to_string(f, -0.0, MinusPlus, 0), "-0"); - assert_eq!(to_string(f, 0.0, Minus, 1), "0.0"); - assert_eq!(to_string(f, 0.0, Minus, 1), "0.0"); - assert_eq!(to_string(f, 0.0, MinusPlus, 1), "+0.0"); - assert_eq!(to_string(f, -0.0, Minus, 8), "-0.00000000"); - assert_eq!(to_string(f, -0.0, MinusPlus, 8), "-0.00000000"); - - assert_eq!(to_string(f, 1.0 / 0.0, Minus, 0), "inf"); - assert_eq!(to_string(f, 1.0 / 0.0, Minus, 0), "inf"); - assert_eq!(to_string(f, 1.0 / 0.0, MinusPlus, 0), "+inf"); - assert_eq!(to_string(f, 0.0 / 0.0, Minus, 0), "NaN"); - assert_eq!(to_string(f, 0.0 / 0.0, Minus, 1), "NaN"); - assert_eq!(to_string(f, 0.0 / 0.0, MinusPlus, 64), "NaN"); - assert_eq!(to_string(f, -1.0 / 0.0, Minus, 0), "-inf"); - assert_eq!(to_string(f, -1.0 / 0.0, Minus, 1), "-inf"); - assert_eq!(to_string(f, -1.0 / 0.0, MinusPlus, 64), "-inf"); - - assert_eq!(to_string(f, 3.14, Minus, 0), "3.14"); - assert_eq!(to_string(f, 3.14, Minus, 0), "3.14"); - assert_eq!(to_string(f, 3.14, MinusPlus, 0), "+3.14"); - assert_eq!(to_string(f, -3.14, Minus, 0), "-3.14"); - assert_eq!(to_string(f, -3.14, Minus, 0), "-3.14"); - assert_eq!(to_string(f, -3.14, MinusPlus, 0), "-3.14"); - assert_eq!(to_string(f, 3.14, Minus, 1), "3.14"); - assert_eq!(to_string(f, 3.14, Minus, 2), "3.14"); - assert_eq!(to_string(f, 3.14, MinusPlus, 4), "+3.1400"); - assert_eq!(to_string(f, -3.14, Minus, 8), "-3.14000000"); - assert_eq!(to_string(f, -3.14, Minus, 8), "-3.14000000"); - assert_eq!(to_string(f, -3.14, MinusPlus, 8), "-3.14000000"); - - assert_eq!(to_string(f, 7.5e-11, Minus, 0), "0.000000000075"); - assert_eq!(to_string(f, 7.5e-11, Minus, 3), "0.000000000075"); - assert_eq!(to_string(f, 7.5e-11, Minus, 12), "0.000000000075"); - assert_eq!(to_string(f, 7.5e-11, Minus, 13), "0.0000000000750"); - - assert_eq!(to_string(f, 1.9971e20, Minus, 0), "199710000000000000000"); - assert_eq!(to_string(f, 1.9971e20, Minus, 1), "199710000000000000000.0"); - assert_eq!(to_string(f, 1.9971e20, Minus, 8), "199710000000000000000.00000000"); - - assert_eq!(to_string(f, f32::MAX, Minus, 0), format!("34028235{:0>31}", "")); - assert_eq!(to_string(f, f32::MAX, Minus, 1), format!("34028235{:0>31}.0", "")); - assert_eq!(to_string(f, f32::MAX, Minus, 8), format!("34028235{:0>31}.00000000", "")); - - let minf32 = ldexp_f32(1.0, -149); - assert_eq!(to_string(f, minf32, Minus, 0), format!("0.{:0>44}1", "")); - assert_eq!(to_string(f, minf32, Minus, 45), format!("0.{:0>44}1", "")); - assert_eq!(to_string(f, minf32, Minus, 46), format!("0.{:0>44}10", "")); - - assert_eq!(to_string(f, f64::MAX, Minus, 0), format!("17976931348623157{:0>292}", "")); - assert_eq!(to_string(f, f64::MAX, Minus, 1), format!("17976931348623157{:0>292}.0", "")); - assert_eq!(to_string(f, f64::MAX, Minus, 8), format!("17976931348623157{:0>292}.00000000", "")); - - let minf64 = ldexp_f64(1.0, -1074); - assert_eq!(to_string(f, minf64, Minus, 0), format!("0.{:0>323}5", "")); - assert_eq!(to_string(f, minf64, Minus, 324), format!("0.{:0>323}5", "")); - assert_eq!(to_string(f, minf64, Minus, 325), format!("0.{:0>323}50", "")); - - if cfg!(miri) { - // Miri is too slow - return; - } - - // very large output - assert_eq!(to_string(f, 1.1, Minus, 80000), format!("1.1{:0>79999}", "")); -} - -pub fn to_shortest_exp_str_test(mut f_: F) -where - F: for<'a> FnMut(&Decoded, &'a mut [MaybeUninit]) -> (&'a [u8], i16), -{ - use core::num::flt2dec::Sign::*; - - fn to_string(f: &mut F, v: T, sign: Sign, exp_bounds: (i16, i16), upper: bool) -> String - where - T: DecodableFloat, - F: for<'a> FnMut(&Decoded, &'a mut [MaybeUninit]) -> (&'a [u8], i16), - { - to_string_with_parts(|buf, parts| { - to_shortest_exp_str(|d, b| f(d, b), v, sign, exp_bounds, upper, buf, parts) - }) - } - - let f = &mut f_; - - assert_eq!(to_string(f, 0.0, Minus, (-4, 16), false), "0"); - assert_eq!(to_string(f, 0.0, Minus, (-4, 16), false), "0"); - assert_eq!(to_string(f, 0.0, MinusPlus, (-4, 16), false), "+0"); - assert_eq!(to_string(f, -0.0, Minus, (-4, 16), false), "-0"); - assert_eq!(to_string(f, -0.0, MinusPlus, (-4, 16), false), "-0"); - assert_eq!(to_string(f, 0.0, Minus, (0, 0), true), "0E0"); - assert_eq!(to_string(f, 0.0, Minus, (0, 0), false), "0e0"); - assert_eq!(to_string(f, 0.0, MinusPlus, (5, 9), false), "+0e0"); - assert_eq!(to_string(f, -0.0, Minus, (0, 0), true), "-0E0"); - assert_eq!(to_string(f, -0.0, MinusPlus, (5, 9), false), "-0e0"); - - assert_eq!(to_string(f, 1.0 / 0.0, Minus, (-4, 16), false), "inf"); - assert_eq!(to_string(f, 1.0 / 0.0, Minus, (-4, 16), true), "inf"); - assert_eq!(to_string(f, 1.0 / 0.0, MinusPlus, (-4, 16), true), "+inf"); - assert_eq!(to_string(f, 0.0 / 0.0, Minus, (0, 0), false), "NaN"); - assert_eq!(to_string(f, 0.0 / 0.0, Minus, (0, 0), true), "NaN"); - assert_eq!(to_string(f, 0.0 / 0.0, MinusPlus, (5, 9), true), "NaN"); - assert_eq!(to_string(f, -1.0 / 0.0, Minus, (0, 0), false), "-inf"); - assert_eq!(to_string(f, -1.0 / 0.0, Minus, (0, 0), true), "-inf"); - assert_eq!(to_string(f, -1.0 / 0.0, MinusPlus, (5, 9), true), "-inf"); - - assert_eq!(to_string(f, 3.14, Minus, (-4, 16), false), "3.14"); - assert_eq!(to_string(f, 3.14, MinusPlus, (-4, 16), false), "+3.14"); - assert_eq!(to_string(f, -3.14, Minus, (-4, 16), false), "-3.14"); - assert_eq!(to_string(f, -3.14, MinusPlus, (-4, 16), false), "-3.14"); - assert_eq!(to_string(f, 3.14, Minus, (0, 0), true), "3.14E0"); - assert_eq!(to_string(f, 3.14, Minus, (0, 0), false), "3.14e0"); - assert_eq!(to_string(f, 3.14, MinusPlus, (5, 9), false), "+3.14e0"); - assert_eq!(to_string(f, -3.14, Minus, (0, 0), true), "-3.14E0"); - assert_eq!(to_string(f, -3.14, Minus, (0, 0), false), "-3.14e0"); - assert_eq!(to_string(f, -3.14, MinusPlus, (5, 9), false), "-3.14e0"); - - assert_eq!(to_string(f, 0.1, Minus, (-4, 16), false), "0.1"); - assert_eq!(to_string(f, 0.1, Minus, (-4, 16), false), "0.1"); - assert_eq!(to_string(f, 0.1, MinusPlus, (-4, 16), false), "+0.1"); - assert_eq!(to_string(f, -0.1, Minus, (-4, 16), false), "-0.1"); - assert_eq!(to_string(f, -0.1, MinusPlus, (-4, 16), false), "-0.1"); - assert_eq!(to_string(f, 0.1, Minus, (0, 0), true), "1E-1"); - assert_eq!(to_string(f, 0.1, Minus, (0, 0), false), "1e-1"); - assert_eq!(to_string(f, 0.1, MinusPlus, (5, 9), false), "+1e-1"); - assert_eq!(to_string(f, -0.1, Minus, (0, 0), true), "-1E-1"); - assert_eq!(to_string(f, -0.1, Minus, (0, 0), false), "-1e-1"); - assert_eq!(to_string(f, -0.1, MinusPlus, (5, 9), false), "-1e-1"); - - assert_eq!(to_string(f, 7.5e-11, Minus, (-4, 16), false), "7.5e-11"); - assert_eq!(to_string(f, 7.5e-11, Minus, (-11, 10), false), "0.000000000075"); - assert_eq!(to_string(f, 7.5e-11, Minus, (-10, 11), false), "7.5e-11"); - - assert_eq!(to_string(f, 1.9971e20, Minus, (-4, 16), false), "1.9971e20"); - assert_eq!(to_string(f, 1.9971e20, Minus, (-20, 21), false), "199710000000000000000"); - assert_eq!(to_string(f, 1.9971e20, Minus, (-21, 20), false), "1.9971e20"); - - // the true value of 1.0e23f64 is less than 10^23, but that shouldn't matter here - assert_eq!(to_string(f, 1.0e23, Minus, (22, 23), false), "1e23"); - assert_eq!(to_string(f, 1.0e23, Minus, (23, 24), false), "100000000000000000000000"); - assert_eq!(to_string(f, 1.0e23, Minus, (24, 25), false), "1e23"); - - assert_eq!(to_string(f, f32::MAX, Minus, (-4, 16), false), "3.4028235e38"); - assert_eq!(to_string(f, f32::MAX, Minus, (-39, 38), false), "3.4028235e38"); - assert_eq!(to_string(f, f32::MAX, Minus, (-38, 39), false), format!("34028235{:0>31}", "")); - - let minf32 = ldexp_f32(1.0, -149); - assert_eq!(to_string(f, minf32, Minus, (-4, 16), false), "1e-45"); - assert_eq!(to_string(f, minf32, Minus, (-44, 45), false), "1e-45"); - assert_eq!(to_string(f, minf32, Minus, (-45, 44), false), format!("0.{:0>44}1", "")); - - assert_eq!(to_string(f, f64::MAX, Minus, (-4, 16), false), "1.7976931348623157e308"); - assert_eq!( - to_string(f, f64::MAX, Minus, (-308, 309), false), - format!("17976931348623157{:0>292}", "") - ); - assert_eq!(to_string(f, f64::MAX, Minus, (-309, 308), false), "1.7976931348623157e308"); - - let minf64 = ldexp_f64(1.0, -1074); - assert_eq!(to_string(f, minf64, Minus, (-4, 16), false), "5e-324"); - assert_eq!(to_string(f, minf64, Minus, (-324, 323), false), format!("0.{:0>323}5", "")); - assert_eq!(to_string(f, minf64, Minus, (-323, 324), false), "5e-324"); - - assert_eq!(to_string(f, 1.1, Minus, (i16::MIN, i16::MAX), false), "1.1"); -} - -pub fn to_exact_exp_str_test(mut f_: F) -where - F: for<'a> FnMut(&Decoded, &'a mut [MaybeUninit], i16) -> (&'a [u8], i16), -{ - use core::num::flt2dec::Sign::*; - - fn to_string(f: &mut F, v: T, sign: Sign, ndigits: usize, upper: bool) -> String - where - T: DecodableFloat, - F: for<'a> FnMut(&Decoded, &'a mut [MaybeUninit], i16) -> (&'a [u8], i16), - { - to_string_with_parts(|buf, parts| { - to_exact_exp_str(|d, b, l| f(d, b, l), v, sign, ndigits, upper, buf, parts) - }) - } - - let f = &mut f_; - - assert_eq!(to_string(f, 0.0, Minus, 1, true), "0E0"); - assert_eq!(to_string(f, 0.0, Minus, 1, false), "0e0"); - assert_eq!(to_string(f, 0.0, MinusPlus, 1, false), "+0e0"); - assert_eq!(to_string(f, -0.0, Minus, 1, true), "-0E0"); - assert_eq!(to_string(f, -0.0, MinusPlus, 1, false), "-0e0"); - assert_eq!(to_string(f, 0.0, Minus, 2, true), "0.0E0"); - assert_eq!(to_string(f, 0.0, Minus, 2, false), "0.0e0"); - assert_eq!(to_string(f, 0.0, MinusPlus, 2, false), "+0.0e0"); - assert_eq!(to_string(f, -0.0, Minus, 8, false), "-0.0000000e0"); - assert_eq!(to_string(f, -0.0, MinusPlus, 8, false), "-0.0000000e0"); - - assert_eq!(to_string(f, 1.0 / 0.0, Minus, 1, false), "inf"); - assert_eq!(to_string(f, 1.0 / 0.0, Minus, 1, true), "inf"); - assert_eq!(to_string(f, 1.0 / 0.0, MinusPlus, 1, true), "+inf"); - assert_eq!(to_string(f, 0.0 / 0.0, Minus, 8, false), "NaN"); - assert_eq!(to_string(f, 0.0 / 0.0, Minus, 8, true), "NaN"); - assert_eq!(to_string(f, 0.0 / 0.0, MinusPlus, 8, true), "NaN"); - assert_eq!(to_string(f, -1.0 / 0.0, Minus, 64, false), "-inf"); - assert_eq!(to_string(f, -1.0 / 0.0, Minus, 64, true), "-inf"); - assert_eq!(to_string(f, -1.0 / 0.0, MinusPlus, 64, true), "-inf"); - - assert_eq!(to_string(f, 3.14, Minus, 1, true), "3E0"); - assert_eq!(to_string(f, 3.14, Minus, 1, false), "3e0"); - assert_eq!(to_string(f, 3.14, MinusPlus, 1, false), "+3e0"); - assert_eq!(to_string(f, -3.14, Minus, 2, true), "-3.1E0"); - assert_eq!(to_string(f, -3.14, Minus, 2, false), "-3.1e0"); - assert_eq!(to_string(f, -3.14, MinusPlus, 2, false), "-3.1e0"); - assert_eq!(to_string(f, 3.14, Minus, 3, true), "3.14E0"); - assert_eq!(to_string(f, 3.14, Minus, 3, false), "3.14e0"); - assert_eq!(to_string(f, 3.14, MinusPlus, 3, false), "+3.14e0"); - assert_eq!(to_string(f, -3.14, Minus, 4, true), "-3.140E0"); - assert_eq!(to_string(f, -3.14, Minus, 4, false), "-3.140e0"); - assert_eq!(to_string(f, -3.14, MinusPlus, 4, false), "-3.140e0"); - - assert_eq!(to_string(f, 0.195, Minus, 1, false), "2e-1"); - assert_eq!(to_string(f, 0.195, Minus, 1, true), "2E-1"); - assert_eq!(to_string(f, 0.195, MinusPlus, 1, true), "+2E-1"); - assert_eq!(to_string(f, -0.195, Minus, 2, false), "-2.0e-1"); - assert_eq!(to_string(f, -0.195, Minus, 2, true), "-2.0E-1"); - assert_eq!(to_string(f, -0.195, MinusPlus, 2, true), "-2.0E-1"); - assert_eq!(to_string(f, 0.195, Minus, 3, false), "1.95e-1"); - assert_eq!(to_string(f, 0.195, Minus, 3, true), "1.95E-1"); - assert_eq!(to_string(f, 0.195, MinusPlus, 3, true), "+1.95E-1"); - assert_eq!(to_string(f, -0.195, Minus, 4, false), "-1.950e-1"); - assert_eq!(to_string(f, -0.195, Minus, 4, true), "-1.950E-1"); - assert_eq!(to_string(f, -0.195, MinusPlus, 4, true), "-1.950E-1"); - - assert_eq!(to_string(f, 9.5, Minus, 1, false), "1e1"); - assert_eq!(to_string(f, 9.5, Minus, 2, false), "9.5e0"); - assert_eq!(to_string(f, 9.5, Minus, 3, false), "9.50e0"); - assert_eq!(to_string(f, 9.5, Minus, 30, false), "9.50000000000000000000000000000e0"); - - assert_eq!(to_string(f, 1.0e25, Minus, 1, false), "1e25"); - assert_eq!(to_string(f, 1.0e25, Minus, 2, false), "1.0e25"); - assert_eq!(to_string(f, 1.0e25, Minus, 15, false), "1.00000000000000e25"); - assert_eq!(to_string(f, 1.0e25, Minus, 16, false), "1.000000000000000e25"); - assert_eq!(to_string(f, 1.0e25, Minus, 17, false), "1.0000000000000001e25"); - assert_eq!(to_string(f, 1.0e25, Minus, 18, false), "1.00000000000000009e25"); - assert_eq!(to_string(f, 1.0e25, Minus, 19, false), "1.000000000000000091e25"); - assert_eq!(to_string(f, 1.0e25, Minus, 20, false), "1.0000000000000000906e25"); - assert_eq!(to_string(f, 1.0e25, Minus, 21, false), "1.00000000000000009060e25"); - assert_eq!(to_string(f, 1.0e25, Minus, 22, false), "1.000000000000000090597e25"); - assert_eq!(to_string(f, 1.0e25, Minus, 23, false), "1.0000000000000000905970e25"); - assert_eq!(to_string(f, 1.0e25, Minus, 24, false), "1.00000000000000009059697e25"); - assert_eq!(to_string(f, 1.0e25, Minus, 25, false), "1.000000000000000090596966e25"); - assert_eq!(to_string(f, 1.0e25, Minus, 26, false), "1.0000000000000000905969664e25"); - assert_eq!(to_string(f, 1.0e25, Minus, 27, false), "1.00000000000000009059696640e25"); - assert_eq!(to_string(f, 1.0e25, Minus, 30, false), "1.00000000000000009059696640000e25"); - - assert_eq!(to_string(f, 1.0e-6, Minus, 1, false), "1e-6"); - assert_eq!(to_string(f, 1.0e-6, Minus, 2, false), "1.0e-6"); - assert_eq!(to_string(f, 1.0e-6, Minus, 16, false), "1.000000000000000e-6"); - assert_eq!(to_string(f, 1.0e-6, Minus, 17, false), "9.9999999999999995e-7"); - assert_eq!(to_string(f, 1.0e-6, Minus, 18, false), "9.99999999999999955e-7"); - assert_eq!(to_string(f, 1.0e-6, Minus, 19, false), "9.999999999999999547e-7"); - assert_eq!(to_string(f, 1.0e-6, Minus, 20, false), "9.9999999999999995475e-7"); - assert_eq!(to_string(f, 1.0e-6, Minus, 30, false), "9.99999999999999954748111825886e-7"); - assert_eq!( - to_string(f, 1.0e-6, Minus, 40, false), - "9.999999999999999547481118258862586856139e-7" - ); - assert_eq!( - to_string(f, 1.0e-6, Minus, 50, false), - "9.9999999999999995474811182588625868561393872369081e-7" - ); - assert_eq!( - to_string(f, 1.0e-6, Minus, 60, false), - "9.99999999999999954748111825886258685613938723690807819366455e-7" - ); - assert_eq!( - to_string(f, 1.0e-6, Minus, 70, false), - "9.999999999999999547481118258862586856139387236908078193664550781250000e-7" - ); - - assert_eq!(to_string(f, f32::MAX, Minus, 1, false), "3e38"); - assert_eq!(to_string(f, f32::MAX, Minus, 2, false), "3.4e38"); - assert_eq!(to_string(f, f32::MAX, Minus, 4, false), "3.403e38"); - assert_eq!(to_string(f, f32::MAX, Minus, 8, false), "3.4028235e38"); - assert_eq!(to_string(f, f32::MAX, Minus, 16, false), "3.402823466385289e38"); - assert_eq!(to_string(f, f32::MAX, Minus, 32, false), "3.4028234663852885981170418348452e38"); - assert_eq!( - to_string(f, f32::MAX, Minus, 64, false), - "3.402823466385288598117041834845169254400000000000000000000000000e38" - ); - - let minf32 = ldexp_f32(1.0, -149); - assert_eq!(to_string(f, minf32, Minus, 1, false), "1e-45"); - assert_eq!(to_string(f, minf32, Minus, 2, false), "1.4e-45"); - assert_eq!(to_string(f, minf32, Minus, 4, false), "1.401e-45"); - assert_eq!(to_string(f, minf32, Minus, 8, false), "1.4012985e-45"); - assert_eq!(to_string(f, minf32, Minus, 16, false), "1.401298464324817e-45"); - assert_eq!(to_string(f, minf32, Minus, 32, false), "1.4012984643248170709237295832899e-45"); - assert_eq!( - to_string(f, minf32, Minus, 64, false), - "1.401298464324817070923729583289916131280261941876515771757068284e-45" - ); - assert_eq!( - to_string(f, minf32, Minus, 128, false), - "1.401298464324817070923729583289916131280261941876515771757068283\ - 8897910826858606014866381883621215820312500000000000000000000000e-45" - ); - - if cfg!(miri) { - // Miri is too slow - return; - } - - assert_eq!(to_string(f, f64::MAX, Minus, 1, false), "2e308"); - assert_eq!(to_string(f, f64::MAX, Minus, 2, false), "1.8e308"); - assert_eq!(to_string(f, f64::MAX, Minus, 4, false), "1.798e308"); - assert_eq!(to_string(f, f64::MAX, Minus, 8, false), "1.7976931e308"); - assert_eq!(to_string(f, f64::MAX, Minus, 16, false), "1.797693134862316e308"); - assert_eq!(to_string(f, f64::MAX, Minus, 32, false), "1.7976931348623157081452742373170e308"); - assert_eq!( - to_string(f, f64::MAX, Minus, 64, false), - "1.797693134862315708145274237317043567980705675258449965989174768e308" - ); - assert_eq!( - to_string(f, f64::MAX, Minus, 128, false), - "1.797693134862315708145274237317043567980705675258449965989174768\ - 0315726078002853876058955863276687817154045895351438246423432133e308" - ); - assert_eq!( - to_string(f, f64::MAX, Minus, 256, false), - "1.797693134862315708145274237317043567980705675258449965989174768\ - 0315726078002853876058955863276687817154045895351438246423432132\ - 6889464182768467546703537516986049910576551282076245490090389328\ - 9440758685084551339423045832369032229481658085593321233482747978e308" - ); - assert_eq!( - to_string(f, f64::MAX, Minus, 512, false), - "1.797693134862315708145274237317043567980705675258449965989174768\ - 0315726078002853876058955863276687817154045895351438246423432132\ - 6889464182768467546703537516986049910576551282076245490090389328\ - 9440758685084551339423045832369032229481658085593321233482747978\ - 2620414472316873817718091929988125040402618412485836800000000000\ - 0000000000000000000000000000000000000000000000000000000000000000\ - 0000000000000000000000000000000000000000000000000000000000000000\ - 0000000000000000000000000000000000000000000000000000000000000000e308" - ); - - // okay, this is becoming tough. fortunately for us, this is almost the worst case. - let minf64 = ldexp_f64(1.0, -1074); - assert_eq!(to_string(f, minf64, Minus, 1, false), "5e-324"); - assert_eq!(to_string(f, minf64, Minus, 2, false), "4.9e-324"); - assert_eq!(to_string(f, minf64, Minus, 4, false), "4.941e-324"); - assert_eq!(to_string(f, minf64, Minus, 8, false), "4.9406565e-324"); - assert_eq!(to_string(f, minf64, Minus, 16, false), "4.940656458412465e-324"); - assert_eq!(to_string(f, minf64, Minus, 32, false), "4.9406564584124654417656879286822e-324"); - assert_eq!( - to_string(f, minf64, Minus, 64, false), - "4.940656458412465441765687928682213723650598026143247644255856825e-324" - ); - assert_eq!( - to_string(f, minf64, Minus, 128, false), - "4.940656458412465441765687928682213723650598026143247644255856825\ - 0067550727020875186529983636163599237979656469544571773092665671e-324" - ); - assert_eq!( - to_string(f, minf64, Minus, 256, false), - "4.940656458412465441765687928682213723650598026143247644255856825\ - 0067550727020875186529983636163599237979656469544571773092665671\ - 0355939796398774796010781878126300713190311404527845817167848982\ - 1036887186360569987307230500063874091535649843873124733972731696e-324" - ); - assert_eq!( - to_string(f, minf64, Minus, 512, false), - "4.940656458412465441765687928682213723650598026143247644255856825\ - 0067550727020875186529983636163599237979656469544571773092665671\ - 0355939796398774796010781878126300713190311404527845817167848982\ - 1036887186360569987307230500063874091535649843873124733972731696\ - 1514003171538539807412623856559117102665855668676818703956031062\ - 4931945271591492455329305456544401127480129709999541931989409080\ - 4165633245247571478690147267801593552386115501348035264934720193\ - 7902681071074917033322268447533357208324319360923828934583680601e-324" - ); - assert_eq!( - to_string(f, minf64, Minus, 1024, false), - "4.940656458412465441765687928682213723650598026143247644255856825\ - 0067550727020875186529983636163599237979656469544571773092665671\ - 0355939796398774796010781878126300713190311404527845817167848982\ - 1036887186360569987307230500063874091535649843873124733972731696\ - 1514003171538539807412623856559117102665855668676818703956031062\ - 4931945271591492455329305456544401127480129709999541931989409080\ - 4165633245247571478690147267801593552386115501348035264934720193\ - 7902681071074917033322268447533357208324319360923828934583680601\ - 0601150616980975307834227731832924790498252473077637592724787465\ - 6084778203734469699533647017972677717585125660551199131504891101\ - 4510378627381672509558373897335989936648099411642057026370902792\ - 4276754456522908753868250641971826553344726562500000000000000000\ - 0000000000000000000000000000000000000000000000000000000000000000\ - 0000000000000000000000000000000000000000000000000000000000000000\ - 0000000000000000000000000000000000000000000000000000000000000000\ - 0000000000000000000000000000000000000000000000000000000000000000e-324" - ); - - // very large output - assert_eq!(to_string(f, 0.0, Minus, 80000, false), format!("0.{:0>79999}e0", "")); - assert_eq!(to_string(f, 1.0e1, Minus, 80000, false), format!("1.{:0>79999}e1", "")); - assert_eq!(to_string(f, 1.0e0, Minus, 80000, false), format!("1.{:0>79999}e0", "")); - assert_eq!( - to_string(f, 1.0e-1, Minus, 80000, false), - format!( - "1.000000000000000055511151231257827021181583404541015625{:0>79945}\ - e-1", - "" - ) - ); - assert_eq!( - to_string(f, 1.0e-20, Minus, 80000, false), - format!( - "9.999999999999999451532714542095716517295037027873924471077157760\ - 66783064379706047475337982177734375{:0>79901}e-21", - "" - ) - ); -} - -pub fn to_exact_fixed_str_test(mut f_: F) -where - F: for<'a> FnMut(&Decoded, &'a mut [MaybeUninit], i16) -> (&'a [u8], i16), -{ - use core::num::flt2dec::Sign::*; - - fn to_string(f: &mut F, v: T, sign: Sign, frac_digits: usize) -> String - where - T: DecodableFloat, - F: for<'a> FnMut(&Decoded, &'a mut [MaybeUninit], i16) -> (&'a [u8], i16), - { - to_string_with_parts(|buf, parts| { - to_exact_fixed_str(|d, b, l| f(d, b, l), v, sign, frac_digits, buf, parts) - }) - } - - let f = &mut f_; - - assert_eq!(to_string(f, 0.0, Minus, 0), "0"); - assert_eq!(to_string(f, 0.0, MinusPlus, 0), "+0"); - assert_eq!(to_string(f, -0.0, Minus, 0), "-0"); - assert_eq!(to_string(f, -0.0, MinusPlus, 0), "-0"); - assert_eq!(to_string(f, 0.0, Minus, 1), "0.0"); - assert_eq!(to_string(f, 0.0, MinusPlus, 1), "+0.0"); - assert_eq!(to_string(f, -0.0, Minus, 8), "-0.00000000"); - assert_eq!(to_string(f, -0.0, MinusPlus, 8), "-0.00000000"); - - assert_eq!(to_string(f, 1.0 / 0.0, Minus, 0), "inf"); - assert_eq!(to_string(f, 1.0 / 0.0, Minus, 1), "inf"); - assert_eq!(to_string(f, 1.0 / 0.0, MinusPlus, 64), "+inf"); - assert_eq!(to_string(f, 0.0 / 0.0, Minus, 0), "NaN"); - assert_eq!(to_string(f, 0.0 / 0.0, Minus, 1), "NaN"); - assert_eq!(to_string(f, 0.0 / 0.0, MinusPlus, 64), "NaN"); - assert_eq!(to_string(f, -1.0 / 0.0, Minus, 0), "-inf"); - assert_eq!(to_string(f, -1.0 / 0.0, Minus, 1), "-inf"); - assert_eq!(to_string(f, -1.0 / 0.0, MinusPlus, 64), "-inf"); - - assert_eq!(to_string(f, 3.14, Minus, 0), "3"); - assert_eq!(to_string(f, 3.14, Minus, 0), "3"); - assert_eq!(to_string(f, 3.14, MinusPlus, 0), "+3"); - assert_eq!(to_string(f, -3.14, Minus, 0), "-3"); - assert_eq!(to_string(f, -3.14, Minus, 0), "-3"); - assert_eq!(to_string(f, -3.14, MinusPlus, 0), "-3"); - assert_eq!(to_string(f, 3.14, Minus, 1), "3.1"); - assert_eq!(to_string(f, 3.14, Minus, 2), "3.14"); - assert_eq!(to_string(f, 3.14, MinusPlus, 4), "+3.1400"); - assert_eq!(to_string(f, -3.14, Minus, 8), "-3.14000000"); - assert_eq!(to_string(f, -3.14, Minus, 8), "-3.14000000"); - assert_eq!(to_string(f, -3.14, MinusPlus, 8), "-3.14000000"); - - assert_eq!(to_string(f, 0.195, Minus, 0), "0"); - assert_eq!(to_string(f, 0.195, MinusPlus, 0), "+0"); - assert_eq!(to_string(f, -0.195, Minus, 0), "-0"); - assert_eq!(to_string(f, -0.195, Minus, 0), "-0"); - assert_eq!(to_string(f, -0.195, MinusPlus, 0), "-0"); - assert_eq!(to_string(f, 0.195, Minus, 1), "0.2"); - assert_eq!(to_string(f, 0.195, Minus, 2), "0.20"); - assert_eq!(to_string(f, 0.195, MinusPlus, 4), "+0.1950"); - assert_eq!(to_string(f, -0.195, Minus, 5), "-0.19500"); - assert_eq!(to_string(f, -0.195, Minus, 6), "-0.195000"); - assert_eq!(to_string(f, -0.195, MinusPlus, 8), "-0.19500000"); - - assert_eq!(to_string(f, 999.5, Minus, 0), "1000"); - assert_eq!(to_string(f, 999.5, Minus, 1), "999.5"); - assert_eq!(to_string(f, 999.5, Minus, 2), "999.50"); - assert_eq!(to_string(f, 999.5, Minus, 3), "999.500"); - assert_eq!(to_string(f, 999.5, Minus, 30), "999.500000000000000000000000000000"); - - assert_eq!(to_string(f, 0.5, Minus, 0), "0"); - assert_eq!(to_string(f, 0.5, Minus, 1), "0.5"); - assert_eq!(to_string(f, 0.5, Minus, 2), "0.50"); - assert_eq!(to_string(f, 0.5, Minus, 3), "0.500"); - - assert_eq!(to_string(f, 0.95, Minus, 0), "1"); - assert_eq!(to_string(f, 0.95, Minus, 1), "0.9"); // because it really is less than 0.95 - assert_eq!(to_string(f, 0.95, Minus, 2), "0.95"); - assert_eq!(to_string(f, 0.95, Minus, 3), "0.950"); - assert_eq!(to_string(f, 0.95, Minus, 10), "0.9500000000"); - assert_eq!(to_string(f, 0.95, Minus, 30), "0.949999999999999955591079014994"); - - assert_eq!(to_string(f, 0.095, Minus, 0), "0"); - assert_eq!(to_string(f, 0.095, Minus, 1), "0.1"); - assert_eq!(to_string(f, 0.095, Minus, 2), "0.10"); - assert_eq!(to_string(f, 0.095, Minus, 3), "0.095"); - assert_eq!(to_string(f, 0.095, Minus, 4), "0.0950"); - assert_eq!(to_string(f, 0.095, Minus, 10), "0.0950000000"); - assert_eq!(to_string(f, 0.095, Minus, 30), "0.095000000000000001110223024625"); - - assert_eq!(to_string(f, 0.0095, Minus, 0), "0"); - assert_eq!(to_string(f, 0.0095, Minus, 1), "0.0"); - assert_eq!(to_string(f, 0.0095, Minus, 2), "0.01"); - assert_eq!(to_string(f, 0.0095, Minus, 3), "0.009"); // really is less than 0.0095 - assert_eq!(to_string(f, 0.0095, Minus, 4), "0.0095"); - assert_eq!(to_string(f, 0.0095, Minus, 5), "0.00950"); - assert_eq!(to_string(f, 0.0095, Minus, 10), "0.0095000000"); - assert_eq!(to_string(f, 0.0095, Minus, 30), "0.009499999999999999764077607267"); - - assert_eq!(to_string(f, 7.5e-11, Minus, 0), "0"); - assert_eq!(to_string(f, 7.5e-11, Minus, 3), "0.000"); - assert_eq!(to_string(f, 7.5e-11, Minus, 10), "0.0000000001"); - assert_eq!(to_string(f, 7.5e-11, Minus, 11), "0.00000000007"); // ditto - assert_eq!(to_string(f, 7.5e-11, Minus, 12), "0.000000000075"); - assert_eq!(to_string(f, 7.5e-11, Minus, 13), "0.0000000000750"); - assert_eq!(to_string(f, 7.5e-11, Minus, 20), "0.00000000007500000000"); - assert_eq!(to_string(f, 7.5e-11, Minus, 30), "0.000000000074999999999999999501"); - - assert_eq!(to_string(f, 1.0e25, Minus, 0), "10000000000000000905969664"); - assert_eq!(to_string(f, 1.0e25, Minus, 1), "10000000000000000905969664.0"); - assert_eq!(to_string(f, 1.0e25, Minus, 3), "10000000000000000905969664.000"); - - assert_eq!(to_string(f, 1.0e-6, Minus, 0), "0"); - assert_eq!(to_string(f, 1.0e-6, Minus, 3), "0.000"); - assert_eq!(to_string(f, 1.0e-6, Minus, 6), "0.000001"); - assert_eq!(to_string(f, 1.0e-6, Minus, 9), "0.000001000"); - assert_eq!(to_string(f, 1.0e-6, Minus, 12), "0.000001000000"); - assert_eq!(to_string(f, 1.0e-6, Minus, 22), "0.0000010000000000000000"); - assert_eq!(to_string(f, 1.0e-6, Minus, 23), "0.00000099999999999999995"); - assert_eq!(to_string(f, 1.0e-6, Minus, 24), "0.000000999999999999999955"); - assert_eq!(to_string(f, 1.0e-6, Minus, 25), "0.0000009999999999999999547"); - assert_eq!(to_string(f, 1.0e-6, Minus, 35), "0.00000099999999999999995474811182589"); - assert_eq!(to_string(f, 1.0e-6, Minus, 45), "0.000000999999999999999954748111825886258685614"); - assert_eq!( - to_string(f, 1.0e-6, Minus, 55), - "0.0000009999999999999999547481118258862586856139387236908" - ); - assert_eq!( - to_string(f, 1.0e-6, Minus, 65), - "0.00000099999999999999995474811182588625868561393872369080781936646" - ); - assert_eq!( - to_string(f, 1.0e-6, Minus, 75), - "0.000000999999999999999954748111825886258685613938723690807819366455078125000" - ); - - assert_eq!(to_string(f, f32::MAX, Minus, 0), "340282346638528859811704183484516925440"); - assert_eq!(to_string(f, f32::MAX, Minus, 1), "340282346638528859811704183484516925440.0"); - assert_eq!(to_string(f, f32::MAX, Minus, 2), "340282346638528859811704183484516925440.00"); - - if cfg!(miri) { - // Miri is too slow - return; - } - - let minf32 = ldexp_f32(1.0, -149); - assert_eq!(to_string(f, minf32, Minus, 0), "0"); - assert_eq!(to_string(f, minf32, Minus, 1), "0.0"); - assert_eq!(to_string(f, minf32, Minus, 2), "0.00"); - assert_eq!(to_string(f, minf32, Minus, 4), "0.0000"); - assert_eq!(to_string(f, minf32, Minus, 8), "0.00000000"); - assert_eq!(to_string(f, minf32, Minus, 16), "0.0000000000000000"); - assert_eq!(to_string(f, minf32, Minus, 32), "0.00000000000000000000000000000000"); - assert_eq!( - to_string(f, minf32, Minus, 64), - "0.0000000000000000000000000000000000000000000014012984643248170709" - ); - assert_eq!( - to_string(f, minf32, Minus, 128), - "0.0000000000000000000000000000000000000000000014012984643248170709\ - 2372958328991613128026194187651577175706828388979108268586060149" - ); - assert_eq!( - to_string(f, minf32, Minus, 256), - "0.0000000000000000000000000000000000000000000014012984643248170709\ - 2372958328991613128026194187651577175706828388979108268586060148\ - 6638188362121582031250000000000000000000000000000000000000000000\ - 0000000000000000000000000000000000000000000000000000000000000000" - ); - - assert_eq!( - to_string(f, f64::MAX, Minus, 0), - "1797693134862315708145274237317043567980705675258449965989174768\ - 0315726078002853876058955863276687817154045895351438246423432132\ - 6889464182768467546703537516986049910576551282076245490090389328\ - 9440758685084551339423045832369032229481658085593321233482747978\ - 26204144723168738177180919299881250404026184124858368" - ); - assert_eq!( - to_string(f, f64::MAX, Minus, 10), - "1797693134862315708145274237317043567980705675258449965989174768\ - 0315726078002853876058955863276687817154045895351438246423432132\ - 6889464182768467546703537516986049910576551282076245490090389328\ - 9440758685084551339423045832369032229481658085593321233482747978\ - 26204144723168738177180919299881250404026184124858368.0000000000" - ); - - let minf64 = ldexp_f64(1.0, -1074); - assert_eq!(to_string(f, minf64, Minus, 0), "0"); - assert_eq!(to_string(f, minf64, Minus, 1), "0.0"); - assert_eq!(to_string(f, minf64, Minus, 10), "0.0000000000"); - assert_eq!( - to_string(f, minf64, Minus, 100), - "0.0000000000000000000000000000000000000000000000000000000000000000\ - 000000000000000000000000000000000000" - ); - assert_eq!( - to_string(f, minf64, Minus, 1000), - "0.0000000000000000000000000000000000000000000000000000000000000000\ - 0000000000000000000000000000000000000000000000000000000000000000\ - 0000000000000000000000000000000000000000000000000000000000000000\ - 0000000000000000000000000000000000000000000000000000000000000000\ - 0000000000000000000000000000000000000000000000000000000000000000\ - 0004940656458412465441765687928682213723650598026143247644255856\ - 8250067550727020875186529983636163599237979656469544571773092665\ - 6710355939796398774796010781878126300713190311404527845817167848\ - 9821036887186360569987307230500063874091535649843873124733972731\ - 6961514003171538539807412623856559117102665855668676818703956031\ - 0624931945271591492455329305456544401127480129709999541931989409\ - 0804165633245247571478690147267801593552386115501348035264934720\ - 1937902681071074917033322268447533357208324319360923828934583680\ - 6010601150616980975307834227731832924790498252473077637592724787\ - 4656084778203734469699533647017972677717585125660551199131504891\ - 1014510378627381672509558373897335989937" - ); - - // very large output - assert_eq!(to_string(f, 0.0, Minus, 80000), format!("0.{:0>80000}", "")); - assert_eq!(to_string(f, 1.0e1, Minus, 80000), format!("10.{:0>80000}", "")); - assert_eq!(to_string(f, 1.0e0, Minus, 80000), format!("1.{:0>80000}", "")); - assert_eq!( - to_string(f, 1.0e-1, Minus, 80000), - format!("0.1000000000000000055511151231257827021181583404541015625{:0>79945}", "") - ); - assert_eq!( - to_string(f, 1.0e-20, Minus, 80000), - format!( - "0.0000000000000000000099999999999999994515327145420957165172950370\ - 2787392447107715776066783064379706047475337982177734375{:0>79881}", - "" - ) - ); -} diff --git a/library/core/tests/num/flt2dec/random.rs b/library/core/tests/num/flt2dec/random.rs deleted file mode 100644 index 0084c1c814e2d..0000000000000 --- a/library/core/tests/num/flt2dec/random.rs +++ /dev/null @@ -1,200 +0,0 @@ -#![cfg(not(target_arch = "wasm32"))] - -use std::mem::MaybeUninit; -use std::str; - -use core::num::flt2dec::strategy::grisu::format_exact_opt; -use core::num::flt2dec::strategy::grisu::format_shortest_opt; -use core::num::flt2dec::MAX_SIG_DIGITS; -use core::num::flt2dec::{decode, DecodableFloat, Decoded, FullDecoded}; - -use rand::distributions::{Distribution, Uniform}; - -pub fn decode_finite(v: T) -> Decoded { - match decode(v).1 { - FullDecoded::Finite(decoded) => decoded, - full_decoded => panic!("expected finite, got {full_decoded:?} instead"), - } -} - -fn iterate(func: &str, k: usize, n: usize, mut f: F, mut g: G, mut v: V) -> (usize, usize) -where - F: for<'a> FnMut(&Decoded, &'a mut [MaybeUninit]) -> Option<(&'a [u8], i16)>, - G: for<'a> FnMut(&Decoded, &'a mut [MaybeUninit]) -> (&'a [u8], i16), - V: FnMut(usize) -> Decoded, -{ - assert!(k <= 1024); - - let mut npassed = 0; // f(x) = Some(g(x)) - let mut nignored = 0; // f(x) = None - - for i in 0..n { - if (i & 0xfffff) == 0 { - println!( - "in progress, {:x}/{:x} (ignored={} passed={} failed={})", - i, - n, - nignored, - npassed, - i - nignored - npassed - ); - } - - let decoded = v(i); - let mut buf1 = [MaybeUninit::new(0); 1024]; - if let Some((buf1, e1)) = f(&decoded, &mut buf1[..k]) { - let mut buf2 = [MaybeUninit::new(0); 1024]; - let (buf2, e2) = g(&decoded, &mut buf2[..k]); - if e1 == e2 && buf1 == buf2 { - npassed += 1; - } else { - println!( - "equivalence test failed, {:x}/{:x}: {:?} f(i)={}e{} g(i)={}e{}", - i, - n, - decoded, - str::from_utf8(buf1).unwrap(), - e1, - str::from_utf8(buf2).unwrap(), - e2 - ); - } - } else { - nignored += 1; - } - } - println!( - "{}({}): done, ignored={} passed={} failed={}", - func, - k, - nignored, - npassed, - n - nignored - npassed - ); - assert!( - nignored + npassed == n, - "{}({}): {} out of {} values returns an incorrect value!", - func, - k, - n - nignored - npassed, - n - ); - (npassed, nignored) -} - -pub fn f32_random_equivalence_test(f: F, g: G, k: usize, n: usize) -where - F: for<'a> FnMut(&Decoded, &'a mut [MaybeUninit]) -> Option<(&'a [u8], i16)>, - G: for<'a> FnMut(&Decoded, &'a mut [MaybeUninit]) -> (&'a [u8], i16), -{ - if cfg!(target_os = "emscripten") { - return; // using rng pulls in i128 support, which doesn't work - } - let mut rng = crate::test_rng(); - let f32_range = Uniform::new(0x0000_0001u32, 0x7f80_0000); - iterate("f32_random_equivalence_test", k, n, f, g, |_| { - let x = f32::from_bits(f32_range.sample(&mut rng)); - decode_finite(x) - }); -} - -pub fn f64_random_equivalence_test(f: F, g: G, k: usize, n: usize) -where - F: for<'a> FnMut(&Decoded, &'a mut [MaybeUninit]) -> Option<(&'a [u8], i16)>, - G: for<'a> FnMut(&Decoded, &'a mut [MaybeUninit]) -> (&'a [u8], i16), -{ - if cfg!(target_os = "emscripten") { - return; // using rng pulls in i128 support, which doesn't work - } - let mut rng = crate::test_rng(); - let f64_range = Uniform::new(0x0000_0000_0000_0001u64, 0x7ff0_0000_0000_0000); - iterate("f64_random_equivalence_test", k, n, f, g, |_| { - let x = f64::from_bits(f64_range.sample(&mut rng)); - decode_finite(x) - }); -} - -pub fn f32_exhaustive_equivalence_test(f: F, g: G, k: usize) -where - F: for<'a> FnMut(&Decoded, &'a mut [MaybeUninit]) -> Option<(&'a [u8], i16)>, - G: for<'a> FnMut(&Decoded, &'a mut [MaybeUninit]) -> (&'a [u8], i16), -{ - // we have only 2^23 * (2^8 - 1) - 1 = 2,139,095,039 positive finite f32 values, - // so why not simply testing all of them? - // - // this is of course very stressful (and thus should be behind an `#[ignore]` attribute), - // but with `-C opt-level=3 -C lto` this only takes about an hour or so. - - // iterate from 0x0000_0001 to 0x7f7f_ffff, i.e., all finite ranges - let (npassed, nignored) = - iterate("f32_exhaustive_equivalence_test", k, 0x7f7f_ffff, f, g, |i: usize| { - let x = f32::from_bits(i as u32 + 1); - decode_finite(x) - }); - assert_eq!((npassed, nignored), (2121451881, 17643158)); -} - -#[test] -fn shortest_random_equivalence_test() { - use core::num::flt2dec::strategy::dragon::format_shortest as fallback; - // Miri is too slow - let n = if cfg!(miri) { 10 } else { 10_000 }; - - f64_random_equivalence_test(format_shortest_opt, fallback, MAX_SIG_DIGITS, n); - f32_random_equivalence_test(format_shortest_opt, fallback, MAX_SIG_DIGITS, n); -} - -#[test] -#[ignore] // it is too expensive -fn shortest_f32_exhaustive_equivalence_test() { - // it is hard to directly test the optimality of the output, but we can at least test if - // two different algorithms agree to each other. - // - // this reports the progress and the number of f32 values returned `None`. - // with `--nocapture` (and plenty of time and appropriate rustc flags), this should print: - // `done, ignored=17643158 passed=2121451881 failed=0`. - - use core::num::flt2dec::strategy::dragon::format_shortest as fallback; - f32_exhaustive_equivalence_test(format_shortest_opt, fallback, MAX_SIG_DIGITS); -} - -#[test] -#[ignore] // it is too expensive -fn shortest_f64_hard_random_equivalence_test() { - // this again probably has to use appropriate rustc flags. - - use core::num::flt2dec::strategy::dragon::format_shortest as fallback; - f64_random_equivalence_test(format_shortest_opt, fallback, MAX_SIG_DIGITS, 100_000_000); -} - -#[test] -fn exact_f32_random_equivalence_test() { - use core::num::flt2dec::strategy::dragon::format_exact as fallback; - // Miri is too slow - let n = if cfg!(miri) { 3 } else { 1_000 }; - - for k in 1..21 { - f32_random_equivalence_test( - |d, buf| format_exact_opt(d, buf, i16::MIN), - |d, buf| fallback(d, buf, i16::MIN), - k, - n, - ); - } -} - -#[test] -fn exact_f64_random_equivalence_test() { - use core::num::flt2dec::strategy::dragon::format_exact as fallback; - // Miri is too slow - let n = if cfg!(miri) { 2 } else { 1_000 }; - - for k in 1..21 { - f64_random_equivalence_test( - |d, buf| format_exact_opt(d, buf, i16::MIN), - |d, buf| fallback(d, buf, i16::MIN), - k, - n, - ); - } -} diff --git a/library/core/tests/num/flt2dec/strategy/dragon.rs b/library/core/tests/num/flt2dec/strategy/dragon.rs deleted file mode 100644 index fc2e724a20c7c..0000000000000 --- a/library/core/tests/num/flt2dec/strategy/dragon.rs +++ /dev/null @@ -1,63 +0,0 @@ -use super::super::*; -use core::num::bignum::Big32x40 as Big; -use core::num::flt2dec::strategy::dragon::*; - -#[test] -fn test_mul_pow10() { - let mut prevpow10 = Big::from_small(1); - for i in 1..340 { - let mut curpow10 = Big::from_small(1); - mul_pow10(&mut curpow10, i); - assert_eq!(curpow10, *prevpow10.clone().mul_small(10)); - prevpow10 = curpow10; - } -} - -#[test] -fn shortest_sanity_test() { - f64_shortest_sanity_test(format_shortest); - f32_shortest_sanity_test(format_shortest); - more_shortest_sanity_test(format_shortest); -} - -#[test] -#[cfg_attr(miri, ignore)] // Miri is too slow -fn exact_sanity_test() { - // This test ends up running what I can only assume is some corner-ish case - // of the `exp2` library function, defined in whatever C runtime we're - // using. In VS 2013 this function apparently had a bug as this test fails - // when linked, but with VS 2015 the bug appears fixed as the test runs just - // fine. - // - // The bug seems to be a difference in return value of `exp2(-1057)`, where - // in VS 2013 it returns a double with the bit pattern 0x2 and in VS 2015 it - // returns 0x20000. - // - // For now just ignore this test entirely on MSVC as it's tested elsewhere - // anyway and we're not super interested in testing each platform's exp2 - // implementation. - if !cfg!(target_env = "msvc") { - f64_exact_sanity_test(format_exact); - } - f32_exact_sanity_test(format_exact); -} - -#[test] -fn test_to_shortest_str() { - to_shortest_str_test(format_shortest); -} - -#[test] -fn test_to_shortest_exp_str() { - to_shortest_exp_str_test(format_shortest); -} - -#[test] -fn test_to_exact_exp_str() { - to_exact_exp_str_test(format_exact); -} - -#[test] -fn test_to_exact_fixed_str() { - to_exact_fixed_str_test(format_exact); -} diff --git a/library/core/tests/num/flt2dec/strategy/grisu.rs b/library/core/tests/num/flt2dec/strategy/grisu.rs deleted file mode 100644 index b59a3b9b72d3b..0000000000000 --- a/library/core/tests/num/flt2dec/strategy/grisu.rs +++ /dev/null @@ -1,72 +0,0 @@ -use super::super::*; -use core::num::flt2dec::strategy::grisu::*; - -#[test] -#[cfg_attr(miri, ignore)] // Miri is too slow -fn test_cached_power() { - assert_eq!(CACHED_POW10.first().unwrap().1, CACHED_POW10_FIRST_E); - assert_eq!(CACHED_POW10.last().unwrap().1, CACHED_POW10_LAST_E); - - for e in -1137..961 { - // full range for f64 - let low = ALPHA - e - 64; - let high = GAMMA - e - 64; - let (_k, cached) = cached_power(low, high); - assert!( - low <= cached.e && cached.e <= high, - "cached_power({}, {}) = {:?} is incorrect", - low, - high, - cached - ); - } -} - -#[test] -fn test_max_pow10_no_more_than() { - let mut prevtenk = 1; - for k in 1..10 { - let tenk = prevtenk * 10; - assert_eq!(max_pow10_no_more_than(tenk - 1), (k - 1, prevtenk)); - assert_eq!(max_pow10_no_more_than(tenk), (k, tenk)); - prevtenk = tenk; - } -} - -#[test] -fn shortest_sanity_test() { - f64_shortest_sanity_test(format_shortest); - f32_shortest_sanity_test(format_shortest); - more_shortest_sanity_test(format_shortest); -} - -#[test] -#[cfg_attr(miri, ignore)] // Miri is too slow -fn exact_sanity_test() { - // See comments in dragon.rs's exact_sanity_test for why this test is - // ignored on MSVC - if !cfg!(target_env = "msvc") { - f64_exact_sanity_test(format_exact); - } - f32_exact_sanity_test(format_exact); -} - -#[test] -fn test_to_shortest_str() { - to_shortest_str_test(format_shortest); -} - -#[test] -fn test_to_shortest_exp_str() { - to_shortest_exp_str_test(format_shortest); -} - -#[test] -fn test_to_exact_exp_str() { - to_exact_exp_str_test(format_exact); -} - -#[test] -fn test_to_exact_fixed_str() { - to_exact_fixed_str_test(format_exact); -} diff --git a/library/core/tests/num/i128.rs b/library/core/tests/num/i128.rs deleted file mode 100644 index 1ddd20f33d0b1..0000000000000 --- a/library/core/tests/num/i128.rs +++ /dev/null @@ -1 +0,0 @@ -int_module!(i128); diff --git a/library/core/tests/num/i16.rs b/library/core/tests/num/i16.rs deleted file mode 100644 index c7aa9fff964ed..0000000000000 --- a/library/core/tests/num/i16.rs +++ /dev/null @@ -1 +0,0 @@ -int_module!(i16); diff --git a/library/core/tests/num/i32.rs b/library/core/tests/num/i32.rs deleted file mode 100644 index efd5b1596a80d..0000000000000 --- a/library/core/tests/num/i32.rs +++ /dev/null @@ -1,30 +0,0 @@ -int_module!(i32); - -#[test] -fn test_arith_operation() { - let a: isize = 10; - assert_eq!(a * (a - 1), 90); - let i32_a: isize = 10; - assert_eq!(i32_a, 10); - assert_eq!(i32_a - 10, 0); - assert_eq!(i32_a / 10, 1); - assert_eq!(i32_a - 20, -10); - assert_eq!(i32_a << 10, 10240); - assert_eq!(i32_a << 16, 655360); - assert_eq!(i32_a * 16, 160); - assert_eq!(i32_a * i32_a * i32_a, 1000); - assert_eq!(i32_a * i32_a * i32_a * i32_a, 10000); - assert_eq!(i32_a * i32_a / i32_a * i32_a, 100); - assert_eq!(i32_a * (i32_a - 1) << (2 + i32_a as usize), 368640); - let i32_b: isize = 0x10101010; - assert_eq!(i32_b + 1 - 1, i32_b); - assert_eq!(i32_b << 1, i32_b << 1); - assert_eq!(i32_b >> 1, i32_b >> 1); - assert_eq!(i32_b & i32_b << 1, 0); - assert_eq!(i32_b | i32_b << 1, 0x30303030); - let i32_c: isize = 0x10101010; - assert_eq!( - i32_c + i32_c * 2 / 3 * 2 + (i32_c - 7 % 3), - i32_c + i32_c * 2 / 3 * 2 + (i32_c - 7 % 3) - ); -} diff --git a/library/core/tests/num/i64.rs b/library/core/tests/num/i64.rs deleted file mode 100644 index 93d23c10adf7e..0000000000000 --- a/library/core/tests/num/i64.rs +++ /dev/null @@ -1 +0,0 @@ -int_module!(i64); diff --git a/library/core/tests/num/i8.rs b/library/core/tests/num/i8.rs deleted file mode 100644 index 887d4f17d25ff..0000000000000 --- a/library/core/tests/num/i8.rs +++ /dev/null @@ -1 +0,0 @@ -int_module!(i8); diff --git a/library/core/tests/num/ieee754.rs b/library/core/tests/num/ieee754.rs deleted file mode 100644 index 48ab75b6f17a5..0000000000000 --- a/library/core/tests/num/ieee754.rs +++ /dev/null @@ -1,157 +0,0 @@ -//! IEEE 754 floating point compliance tests -//! -//! To understand IEEE 754's requirements on a programming language, one must understand that the -//! requirements of IEEE 754 rest on the total programming environment, and not entirely on any -//! one component. That means the hardware, language, and even libraries are considered part of -//! conforming floating point support in a programming environment. -//! -//! A programming language's duty, accordingly, is: -//! 1. offer access to the hardware where the hardware offers support -//! 2. provide operations that fulfill the remaining requirements of the standard -//! 3. provide the ability to write additional software that can fulfill those requirements -//! -//! This may be fulfilled in any combination that the language sees fit. However, to claim that -//! a language supports IEEE 754 is to suggest that it has fulfilled requirements 1 and 2, without -//! deferring minimum requirements to libraries. This is because support for IEEE 754 is defined -//! as complete support for at least one specified floating point type as an "arithmetic" and -//! "interchange" format, plus specified type conversions to "external character sequences" and -//! integer types. -//! -//! For our purposes, -//! "interchange format" => f32, f64 -//! "arithmetic format" => f32, f64, and any "soft floats" -//! "external character sequence" => str from any float -//! "integer format" => {i,u}{8,16,32,64,128} -//! -//! None of these tests are against Rust's own implementation. They are only tests against the -//! standard. That is why they accept wildly diverse inputs or may seem to duplicate other tests. -//! Please consider this carefully when adding, removing, or reorganizing these tests. They are -//! here so that it is clear what tests are required by the standard and what can be changed. -use ::core::str::FromStr; - -// IEEE 754 for many tests is applied to specific bit patterns. -// These generally are not applicable to NaN, however. -macro_rules! assert_biteq { - ($lhs:expr, $rhs:expr) => { - assert_eq!($lhs.to_bits(), $rhs.to_bits()) - }; -} - -// ToString uses the default fmt::Display impl without special concerns, and bypasses other parts -// of the formatting infrastructure, which makes it ideal for testing here. -macro_rules! roundtrip { - ($f:expr => $t:ty) => { - ($f).to_string().parse::<$t>().unwrap() - }; -} - -macro_rules! assert_floats_roundtrip { - ($f:ident) => { - assert_biteq!(f32::$f, roundtrip!(f32::$f => f32)); - assert_biteq!(f64::$f, roundtrip!(f64::$f => f64)); - }; - ($f:expr) => { - assert_biteq!($f as f32, roundtrip!($f => f32)); - assert_biteq!($f as f64, roundtrip!($f => f64)); - } -} - -macro_rules! assert_floats_bitne { - ($lhs:ident, $rhs:ident) => { - assert_ne!(f32::$lhs.to_bits(), f32::$rhs.to_bits()); - assert_ne!(f64::$lhs.to_bits(), f64::$rhs.to_bits()); - }; - ($lhs:expr, $rhs:expr) => { - assert_ne!(f32::to_bits($lhs), f32::to_bits($rhs)); - assert_ne!(f64::to_bits($lhs), f64::to_bits($rhs)); - }; -} - -// We must preserve signs on all numbers. That includes zero. -// -0 and 0 are == normally, so test bit equality. -#[test] -fn preserve_signed_zero() { - assert_floats_roundtrip!(-0.0); - assert_floats_roundtrip!(0.0); - assert_floats_bitne!(0.0, -0.0); -} - -#[test] -fn preserve_signed_infinity() { - assert_floats_roundtrip!(INFINITY); - assert_floats_roundtrip!(NEG_INFINITY); - assert_floats_bitne!(INFINITY, NEG_INFINITY); -} - -#[test] -fn infinity_to_str() { - assert!(match f32::INFINITY.to_string().to_lowercase().as_str() { - "+infinity" | "infinity" => true, - "+inf" | "inf" => true, - _ => false, - }); - assert!( - match f64::INFINITY.to_string().to_lowercase().as_str() { - "+infinity" | "infinity" => true, - "+inf" | "inf" => true, - _ => false, - }, - "Infinity must write to a string as some casing of inf or infinity, with an optional +." - ); -} - -#[test] -fn neg_infinity_to_str() { - assert!(match f32::NEG_INFINITY.to_string().to_lowercase().as_str() { - "-infinity" | "-inf" => true, - _ => false, - }); - assert!( - match f64::NEG_INFINITY.to_string().to_lowercase().as_str() { - "-infinity" | "-inf" => true, - _ => false, - }, - "Negative Infinity must write to a string as some casing of -inf or -infinity" - ) -} - -#[test] -fn nan_to_str() { - assert!( - match f32::NAN.to_string().to_lowercase().as_str() { - "nan" | "+nan" | "-nan" => true, - _ => false, - }, - "NaNs must write to a string as some casing of nan." - ) -} - -// "+"?("inf"|"infinity") in any case => Infinity -#[test] -fn infinity_from_str() { - assert_biteq!(f32::INFINITY, f32::from_str("infinity").unwrap()); - assert_biteq!(f32::INFINITY, f32::from_str("inf").unwrap()); - assert_biteq!(f32::INFINITY, f32::from_str("+infinity").unwrap()); - assert_biteq!(f32::INFINITY, f32::from_str("+inf").unwrap()); - // yes! this means you are weLcOmE tO mY iNfInItElY tWiStEd MiNd - assert_biteq!(f32::INFINITY, f32::from_str("+iNfInItY").unwrap()); -} - -// "-inf"|"-infinity" in any case => Negative Infinity -#[test] -fn neg_infinity_from_str() { - assert_biteq!(f32::NEG_INFINITY, f32::from_str("-infinity").unwrap()); - assert_biteq!(f32::NEG_INFINITY, f32::from_str("-inf").unwrap()); - assert_biteq!(f32::NEG_INFINITY, f32::from_str("-INF").unwrap()); - assert_biteq!(f32::NEG_INFINITY, f32::from_str("-INFinity").unwrap()); -} - -// ("+"|"-"")?"s"?"nan" in any case => qNaN -#[test] -fn qnan_from_str() { - assert!("nan".parse::().unwrap().is_nan()); - assert!("-nan".parse::().unwrap().is_nan()); - assert!("+nan".parse::().unwrap().is_nan()); - assert!("+NAN".parse::().unwrap().is_nan()); - assert!("-NaN".parse::().unwrap().is_nan()); -} diff --git a/library/core/tests/num/int_log.rs b/library/core/tests/num/int_log.rs deleted file mode 100644 index a1edb1a518632..0000000000000 --- a/library/core/tests/num/int_log.rs +++ /dev/null @@ -1,196 +0,0 @@ -//! This tests the `Integer::{ilog,log2,log10}` methods. These tests are in a -//! separate file because there's both a large number of them, and not all tests -//! can be run on Android. This is because in Android `ilog2` uses an imprecise -//! approximation:https://github.com/rust-lang/rust/blob/4825e12fc9c79954aa0fe18f5521efa6c19c7539/src/libstd/sys/unix/android.rs#L27-L53 - -#[test] -fn checked_ilog() { - assert_eq!(999u32.checked_ilog(10), Some(2)); - assert_eq!(1000u32.checked_ilog(10), Some(3)); - assert_eq!(555u32.checked_ilog(13), Some(2)); - assert_eq!(63u32.checked_ilog(4), Some(2)); - assert_eq!(64u32.checked_ilog(4), Some(3)); - assert_eq!(10460353203u64.checked_ilog(3), Some(21)); - assert_eq!(10460353202u64.checked_ilog(3), Some(20)); - assert_eq!(147808829414345923316083210206383297601u128.checked_ilog(3), Some(80)); - assert_eq!(147808829414345923316083210206383297600u128.checked_ilog(3), Some(79)); - assert_eq!(22528399544939174411840147874772641u128.checked_ilog(19683), Some(8)); - assert_eq!(22528399544939174411840147874772631i128.checked_ilog(19683), Some(7)); - - assert_eq!(0u8.checked_ilog(4), None); - assert_eq!(0u16.checked_ilog(4), None); - assert_eq!(0i8.checked_ilog(4), None); - assert_eq!(0i16.checked_ilog(4), None); - - #[cfg(not(miri))] // Miri is too slow - for i in i16::MIN..=0 { - assert_eq!(i.checked_ilog(4), None); - } - #[cfg(not(miri))] // Miri is too slow - for i in 1..=i16::MAX { - assert_eq!(i.checked_ilog(13), Some((i as f32).log(13.0) as u32)); - } - #[cfg(not(miri))] // Miri is too slow - for i in 1..=u16::MAX { - assert_eq!(i.checked_ilog(13), Some((i as f32).log(13.0) as u32)); - } -} - -#[test] -fn checked_ilog2() { - assert_eq!(5u32.checked_ilog2(), Some(2)); - assert_eq!(0u64.checked_ilog2(), None); - assert_eq!(128i32.checked_ilog2(), Some(7)); - assert_eq!((-55i16).checked_ilog2(), None); - - assert_eq!(0u8.checked_ilog2(), None); - assert_eq!(0u16.checked_ilog2(), None); - assert_eq!(0i8.checked_ilog2(), None); - assert_eq!(0i16.checked_ilog2(), None); - - for i in 1..=u8::MAX { - assert_eq!(i.checked_ilog2(), Some((i as f32).log2() as u32)); - } - #[cfg(not(miri))] // Miri is too slow - for i in 1..=u16::MAX { - // Guard against Android's imprecise f32::ilog2 implementation. - if i != 8192 && i != 32768 { - assert_eq!(i.checked_ilog2(), Some((i as f32).log2() as u32)); - } - } - for i in i8::MIN..=0 { - assert_eq!(i.checked_ilog2(), None); - } - for i in 1..=i8::MAX { - assert_eq!(i.checked_ilog2(), Some((i as f32).log2() as u32)); - } - #[cfg(not(miri))] // Miri is too slow - for i in i16::MIN..=0 { - assert_eq!(i.checked_ilog2(), None); - } - #[cfg(not(miri))] // Miri is too slow - for i in 1..=i16::MAX { - // Guard against Android's imprecise f32::ilog2 implementation. - if i != 8192 { - assert_eq!(i.checked_ilog2(), Some((i as f32).log2() as u32)); - } - } -} - -// Validate cases that fail on Android's imprecise float ilog2 implementation. -#[test] -#[cfg(not(target_os = "android"))] -fn checked_ilog2_not_android() { - assert_eq!(8192u16.checked_ilog2(), Some((8192f32).log2() as u32)); - assert_eq!(32768u16.checked_ilog2(), Some((32768f32).log2() as u32)); - assert_eq!(8192i16.checked_ilog2(), Some((8192f32).log2() as u32)); -} - -#[test] -fn checked_ilog10() { - assert_eq!(0u8.checked_ilog10(), None); - assert_eq!(0u16.checked_ilog10(), None); - assert_eq!(0i8.checked_ilog10(), None); - assert_eq!(0i16.checked_ilog10(), None); - - #[cfg(not(miri))] // Miri is too slow - for i in i16::MIN..=0 { - assert_eq!(i.checked_ilog10(), None); - } - #[cfg(not(miri))] // Miri is too slow - for i in 1..=i16::MAX { - assert_eq!(i.checked_ilog10(), Some((i as f32).log10() as u32)); - } - #[cfg(not(miri))] // Miri is too slow - for i in 1..=u16::MAX { - assert_eq!(i.checked_ilog10(), Some((i as f32).log10() as u32)); - } - #[cfg(not(miri))] // Miri is too slow - for i in 1..=100_000u32 { - assert_eq!(i.checked_ilog10(), Some((i as f32).log10() as u32)); - } -} - -macro_rules! ilog10_loop { - ($T:ty, $ilog10_max:expr) => { - assert_eq!(<$T>::MAX.ilog10(), $ilog10_max); - for i in 0..=$ilog10_max { - let p = (10 as $T).pow(i as u32); - if p >= 10 { - assert_eq!((p - 9).ilog10(), i - 1); - assert_eq!((p - 1).ilog10(), i - 1); - } - assert_eq!(p.ilog10(), i); - assert_eq!((p + 1).ilog10(), i); - if p >= 10 { - assert_eq!((p + 9).ilog10(), i); - } - - // also check `x.ilog(10)` - if p >= 10 { - assert_eq!((p - 9).ilog(10), i - 1); - assert_eq!((p - 1).ilog(10), i - 1); - } - assert_eq!(p.ilog(10), i); - assert_eq!((p + 1).ilog(10), i); - if p >= 10 { - assert_eq!((p + 9).ilog(10), i); - } - } - }; -} - -#[test] -fn ilog10_u8() { - ilog10_loop! { u8, 2 } -} - -#[test] -fn ilog10_u16() { - ilog10_loop! { u16, 4 } -} - -#[test] -fn ilog10_u32() { - ilog10_loop! { u32, 9 } -} - -#[test] -fn ilog10_u64() { - ilog10_loop! { u64, 19 } -} - -#[test] -fn ilog10_u128() { - ilog10_loop! { u128, 38 } -} - -#[test] -#[should_panic(expected = "argument of integer logarithm must be positive")] -fn ilog2_of_0_panic() { - let _ = 0u32.ilog2(); -} - -#[test] -#[should_panic(expected = "argument of integer logarithm must be positive")] -fn ilog10_of_0_panic() { - let _ = 0u32.ilog10(); -} - -#[test] -#[should_panic(expected = "argument of integer logarithm must be positive")] -fn ilog3_of_0_panic() { - let _ = 0u32.ilog(3); -} - -#[test] -#[should_panic(expected = "base of integer logarithm must be at least 2")] -fn ilog0_of_1_panic() { - let _ = 1u32.ilog(0); -} - -#[test] -#[should_panic(expected = "base of integer logarithm must be at least 2")] -fn ilog1_of_1_panic() { - let _ = 1u32.ilog(1); -} diff --git a/library/core/tests/num/int_macros.rs b/library/core/tests/num/int_macros.rs deleted file mode 100644 index 165d9a296176e..0000000000000 --- a/library/core/tests/num/int_macros.rs +++ /dev/null @@ -1,427 +0,0 @@ -macro_rules! int_module { - ($T:ident) => { - #[cfg(test)] - mod tests { - use core::ops::{BitAnd, BitOr, BitXor, Not, Shl, Shr}; - use core::$T::*; - - use crate::num; - - #[test] - fn test_overflows() { - assert!(MAX > 0); - assert!(MIN <= 0); - assert_eq!(MIN + MAX + 1, 0); - } - - #[test] - fn test_num() { - num::test_num(10 as $T, 2 as $T); - } - - #[test] - fn test_rem_euclid() { - assert_eq!((-1 as $T).rem_euclid(MIN), MAX); - } - - #[test] - pub fn test_abs() { - assert_eq!((1 as $T).abs(), 1 as $T); - assert_eq!((0 as $T).abs(), 0 as $T); - assert_eq!((-1 as $T).abs(), 1 as $T); - } - - #[test] - fn test_signum() { - assert_eq!((1 as $T).signum(), 1 as $T); - assert_eq!((0 as $T).signum(), 0 as $T); - assert_eq!((-0 as $T).signum(), 0 as $T); - assert_eq!((-1 as $T).signum(), -1 as $T); - } - - #[test] - fn test_is_positive() { - assert!((1 as $T).is_positive()); - assert!(!(0 as $T).is_positive()); - assert!(!(-0 as $T).is_positive()); - assert!(!(-1 as $T).is_positive()); - } - - #[test] - fn test_is_negative() { - assert!(!(1 as $T).is_negative()); - assert!(!(0 as $T).is_negative()); - assert!(!(-0 as $T).is_negative()); - assert!((-1 as $T).is_negative()); - } - - #[test] - fn test_bitwise_operators() { - assert_eq!(0b1110 as $T, (0b1100 as $T).bitor(0b1010 as $T)); - assert_eq!(0b1000 as $T, (0b1100 as $T).bitand(0b1010 as $T)); - assert_eq!(0b0110 as $T, (0b1100 as $T).bitxor(0b1010 as $T)); - assert_eq!(0b1110 as $T, (0b0111 as $T).shl(1)); - assert_eq!(0b0111 as $T, (0b1110 as $T).shr(1)); - assert_eq!(-(0b11 as $T) - (1 as $T), (0b11 as $T).not()); - } - - const A: $T = 0b0101100; - const B: $T = 0b0100001; - const C: $T = 0b1111001; - - const _0: $T = 0; - const _1: $T = !0; - - #[test] - fn test_count_ones() { - assert_eq!(A.count_ones(), 3); - assert_eq!(B.count_ones(), 2); - assert_eq!(C.count_ones(), 5); - } - - #[test] - fn test_count_zeros() { - assert_eq!(A.count_zeros(), $T::BITS - 3); - assert_eq!(B.count_zeros(), $T::BITS - 2); - assert_eq!(C.count_zeros(), $T::BITS - 5); - } - - #[test] - fn test_leading_trailing_ones() { - let a: $T = 0b0101_1111; - assert_eq!(a.trailing_ones(), 5); - assert_eq!((!a).leading_ones(), $T::BITS - 7); - - assert_eq!(a.reverse_bits().leading_ones(), 5); - - assert_eq!(_1.leading_ones(), $T::BITS); - assert_eq!(_1.trailing_ones(), $T::BITS); - - assert_eq!((_1 << 1).trailing_ones(), 0); - assert_eq!(MAX.leading_ones(), 0); - - assert_eq!((_1 << 1).leading_ones(), $T::BITS - 1); - assert_eq!(MAX.trailing_ones(), $T::BITS - 1); - - assert_eq!(_0.leading_ones(), 0); - assert_eq!(_0.trailing_ones(), 0); - - let x: $T = 0b0010_1100; - assert_eq!(x.leading_ones(), 0); - assert_eq!(x.trailing_ones(), 0); - } - - #[test] - fn test_rotate() { - assert_eq!(A.rotate_left(6).rotate_right(2).rotate_right(4), A); - assert_eq!(B.rotate_left(3).rotate_left(2).rotate_right(5), B); - assert_eq!(C.rotate_left(6).rotate_right(2).rotate_right(4), C); - - // Rotating these should make no difference - // - // We test using 124 bits because to ensure that overlong bit shifts do - // not cause undefined behaviour. See #10183. - assert_eq!(_0.rotate_left(124), _0); - assert_eq!(_1.rotate_left(124), _1); - assert_eq!(_0.rotate_right(124), _0); - assert_eq!(_1.rotate_right(124), _1); - - // Rotating by 0 should have no effect - assert_eq!(A.rotate_left(0), A); - assert_eq!(B.rotate_left(0), B); - assert_eq!(C.rotate_left(0), C); - // Rotating by a multiple of word size should also have no effect - assert_eq!(A.rotate_left(128), A); - assert_eq!(B.rotate_left(128), B); - assert_eq!(C.rotate_left(128), C); - } - - #[test] - fn test_swap_bytes() { - assert_eq!(A.swap_bytes().swap_bytes(), A); - assert_eq!(B.swap_bytes().swap_bytes(), B); - assert_eq!(C.swap_bytes().swap_bytes(), C); - - // Swapping these should make no difference - assert_eq!(_0.swap_bytes(), _0); - assert_eq!(_1.swap_bytes(), _1); - } - - #[test] - fn test_le() { - assert_eq!($T::from_le(A.to_le()), A); - assert_eq!($T::from_le(B.to_le()), B); - assert_eq!($T::from_le(C.to_le()), C); - assert_eq!($T::from_le(_0), _0); - assert_eq!($T::from_le(_1), _1); - assert_eq!(_0.to_le(), _0); - assert_eq!(_1.to_le(), _1); - } - - #[test] - fn test_be() { - assert_eq!($T::from_be(A.to_be()), A); - assert_eq!($T::from_be(B.to_be()), B); - assert_eq!($T::from_be(C.to_be()), C); - assert_eq!($T::from_be(_0), _0); - assert_eq!($T::from_be(_1), _1); - assert_eq!(_0.to_be(), _0); - assert_eq!(_1.to_be(), _1); - } - - #[test] - fn test_signed_checked_div() { - assert_eq!((10 as $T).checked_div(2), Some(5)); - assert_eq!((5 as $T).checked_div(0), None); - assert_eq!(isize::MIN.checked_div(-1), None); - } - - #[test] - fn test_saturating_abs() { - assert_eq!((0 as $T).saturating_abs(), 0); - assert_eq!((123 as $T).saturating_abs(), 123); - assert_eq!((-123 as $T).saturating_abs(), 123); - assert_eq!((MAX - 2).saturating_abs(), MAX - 2); - assert_eq!((MAX - 1).saturating_abs(), MAX - 1); - assert_eq!(MAX.saturating_abs(), MAX); - assert_eq!((MIN + 2).saturating_abs(), MAX - 1); - assert_eq!((MIN + 1).saturating_abs(), MAX); - assert_eq!(MIN.saturating_abs(), MAX); - } - - #[test] - fn test_saturating_neg() { - assert_eq!((0 as $T).saturating_neg(), 0); - assert_eq!((123 as $T).saturating_neg(), -123); - assert_eq!((-123 as $T).saturating_neg(), 123); - assert_eq!((MAX - 2).saturating_neg(), MIN + 3); - assert_eq!((MAX - 1).saturating_neg(), MIN + 2); - assert_eq!(MAX.saturating_neg(), MIN + 1); - assert_eq!((MIN + 2).saturating_neg(), MAX - 1); - assert_eq!((MIN + 1).saturating_neg(), MAX); - assert_eq!(MIN.saturating_neg(), MAX); - } - - #[test] - fn test_from_str() { - fn from_str(t: &str) -> Option { - std::str::FromStr::from_str(t).ok() - } - assert_eq!(from_str::<$T>("0"), Some(0 as $T)); - assert_eq!(from_str::<$T>("3"), Some(3 as $T)); - assert_eq!(from_str::<$T>("10"), Some(10 as $T)); - assert_eq!(from_str::("123456789"), Some(123456789 as i32)); - assert_eq!(from_str::<$T>("00100"), Some(100 as $T)); - - assert_eq!(from_str::<$T>("-1"), Some(-1 as $T)); - assert_eq!(from_str::<$T>("-3"), Some(-3 as $T)); - assert_eq!(from_str::<$T>("-10"), Some(-10 as $T)); - assert_eq!(from_str::("-123456789"), Some(-123456789 as i32)); - assert_eq!(from_str::<$T>("-00100"), Some(-100 as $T)); - - assert_eq!(from_str::<$T>(""), None); - assert_eq!(from_str::<$T>(" "), None); - assert_eq!(from_str::<$T>("x"), None); - } - - #[test] - fn test_from_str_radix() { - assert_eq!($T::from_str_radix("123", 10), Ok(123 as $T)); - assert_eq!($T::from_str_radix("1001", 2), Ok(9 as $T)); - assert_eq!($T::from_str_radix("123", 8), Ok(83 as $T)); - assert_eq!(i32::from_str_radix("123", 16), Ok(291 as i32)); - assert_eq!(i32::from_str_radix("ffff", 16), Ok(65535 as i32)); - assert_eq!(i32::from_str_radix("FFFF", 16), Ok(65535 as i32)); - assert_eq!($T::from_str_radix("z", 36), Ok(35 as $T)); - assert_eq!($T::from_str_radix("Z", 36), Ok(35 as $T)); - - assert_eq!($T::from_str_radix("-123", 10), Ok(-123 as $T)); - assert_eq!($T::from_str_radix("-1001", 2), Ok(-9 as $T)); - assert_eq!($T::from_str_radix("-123", 8), Ok(-83 as $T)); - assert_eq!(i32::from_str_radix("-123", 16), Ok(-291 as i32)); - assert_eq!(i32::from_str_radix("-ffff", 16), Ok(-65535 as i32)); - assert_eq!(i32::from_str_radix("-FFFF", 16), Ok(-65535 as i32)); - assert_eq!($T::from_str_radix("-z", 36), Ok(-35 as $T)); - assert_eq!($T::from_str_radix("-Z", 36), Ok(-35 as $T)); - - assert_eq!($T::from_str_radix("Z", 35).ok(), None::<$T>); - assert_eq!($T::from_str_radix("-9", 2).ok(), None::<$T>); - } - - #[test] - fn test_pow() { - let mut r = 2 as $T; - assert_eq!(r.pow(2), 4 as $T); - assert_eq!(r.pow(0), 1 as $T); - assert_eq!(r.wrapping_pow(2), 4 as $T); - assert_eq!(r.wrapping_pow(0), 1 as $T); - assert_eq!(r.checked_pow(2), Some(4 as $T)); - assert_eq!(r.checked_pow(0), Some(1 as $T)); - assert_eq!(r.overflowing_pow(2), (4 as $T, false)); - assert_eq!(r.overflowing_pow(0), (1 as $T, false)); - assert_eq!(r.saturating_pow(2), 4 as $T); - assert_eq!(r.saturating_pow(0), 1 as $T); - - r = MAX; - // use `^` to represent .pow() with no overflow. - // if itest::MAX == 2^j-1, then itest is a `j` bit int, - // so that `itest::MAX*itest::MAX == 2^(2*j)-2^(j+1)+1`, - // thussaturating_pow the overflowing result is exactly 1. - assert_eq!(r.wrapping_pow(2), 1 as $T); - assert_eq!(r.checked_pow(2), None); - assert_eq!(r.overflowing_pow(2), (1 as $T, true)); - assert_eq!(r.saturating_pow(2), MAX); - //test for negative exponent. - r = -2 as $T; - assert_eq!(r.pow(2), 4 as $T); - assert_eq!(r.pow(3), -8 as $T); - assert_eq!(r.pow(0), 1 as $T); - assert_eq!(r.wrapping_pow(2), 4 as $T); - assert_eq!(r.wrapping_pow(3), -8 as $T); - assert_eq!(r.wrapping_pow(0), 1 as $T); - assert_eq!(r.checked_pow(2), Some(4 as $T)); - assert_eq!(r.checked_pow(3), Some(-8 as $T)); - assert_eq!(r.checked_pow(0), Some(1 as $T)); - assert_eq!(r.overflowing_pow(2), (4 as $T, false)); - assert_eq!(r.overflowing_pow(3), (-8 as $T, false)); - assert_eq!(r.overflowing_pow(0), (1 as $T, false)); - assert_eq!(r.saturating_pow(2), 4 as $T); - assert_eq!(r.saturating_pow(3), -8 as $T); - assert_eq!(r.saturating_pow(0), 1 as $T); - } - - #[test] - fn test_isqrt() { - assert_eq!($T::MIN.checked_isqrt(), None); - assert_eq!((-1 as $T).checked_isqrt(), None); - assert_eq!((0 as $T).isqrt(), 0 as $T); - assert_eq!((1 as $T).isqrt(), 1 as $T); - assert_eq!((2 as $T).isqrt(), 1 as $T); - assert_eq!((99 as $T).isqrt(), 9 as $T); - assert_eq!((100 as $T).isqrt(), 10 as $T); - } - - #[cfg(not(miri))] // Miri is too slow - #[test] - fn test_lots_of_isqrt() { - let n_max: $T = (1024 * 1024).min($T::MAX as u128) as $T; - for n in 0..=n_max { - let isqrt: $T = n.isqrt(); - - assert!(isqrt.pow(2) <= n); - let (square, overflow) = (isqrt + 1).overflowing_pow(2); - assert!(overflow || square > n); - } - - for n in ($T::MAX - 127)..=$T::MAX { - let isqrt: $T = n.isqrt(); - - assert!(isqrt.pow(2) <= n); - let (square, overflow) = (isqrt + 1).overflowing_pow(2); - assert!(overflow || square > n); - } - } - - #[test] - fn test_div_floor() { - let a: $T = 8; - let b = 3; - assert_eq!(a.div_floor(b), 2); - assert_eq!(a.div_floor(-b), -3); - assert_eq!((-a).div_floor(b), -3); - assert_eq!((-a).div_floor(-b), 2); - } - - #[test] - fn test_div_ceil() { - let a: $T = 8; - let b = 3; - assert_eq!(a.div_ceil(b), 3); - assert_eq!(a.div_ceil(-b), -2); - assert_eq!((-a).div_ceil(b), -2); - assert_eq!((-a).div_ceil(-b), 3); - } - - #[test] - fn test_next_multiple_of() { - assert_eq!((16 as $T).next_multiple_of(8), 16); - assert_eq!((23 as $T).next_multiple_of(8), 24); - assert_eq!((16 as $T).next_multiple_of(-8), 16); - assert_eq!((23 as $T).next_multiple_of(-8), 16); - assert_eq!((-16 as $T).next_multiple_of(8), -16); - assert_eq!((-23 as $T).next_multiple_of(8), -16); - assert_eq!((-16 as $T).next_multiple_of(-8), -16); - assert_eq!((-23 as $T).next_multiple_of(-8), -24); - assert_eq!(MIN.next_multiple_of(-1), MIN); - } - - #[test] - fn test_checked_next_multiple_of() { - assert_eq!((16 as $T).checked_next_multiple_of(8), Some(16)); - assert_eq!((23 as $T).checked_next_multiple_of(8), Some(24)); - assert_eq!((16 as $T).checked_next_multiple_of(-8), Some(16)); - assert_eq!((23 as $T).checked_next_multiple_of(-8), Some(16)); - assert_eq!((-16 as $T).checked_next_multiple_of(8), Some(-16)); - assert_eq!((-23 as $T).checked_next_multiple_of(8), Some(-16)); - assert_eq!((-16 as $T).checked_next_multiple_of(-8), Some(-16)); - assert_eq!((-23 as $T).checked_next_multiple_of(-8), Some(-24)); - assert_eq!((1 as $T).checked_next_multiple_of(0), None); - assert_eq!(MAX.checked_next_multiple_of(2), None); - assert_eq!(MIN.checked_next_multiple_of(-3), None); - assert_eq!(MIN.checked_next_multiple_of(-1), Some(MIN)); - } - - #[test] - fn test_carrying_add() { - assert_eq!($T::MAX.carrying_add(1, false), ($T::MIN, true)); - assert_eq!($T::MAX.carrying_add(0, true), ($T::MIN, true)); - assert_eq!($T::MAX.carrying_add(1, true), ($T::MIN + 1, true)); - assert_eq!($T::MAX.carrying_add(-1, false), ($T::MAX - 1, false)); - assert_eq!($T::MAX.carrying_add(-1, true), ($T::MAX, false)); // no intermediate overflow - assert_eq!($T::MIN.carrying_add(-1, false), ($T::MAX, true)); - assert_eq!($T::MIN.carrying_add(-1, true), ($T::MIN, false)); // no intermediate overflow - assert_eq!((0 as $T).carrying_add($T::MAX, true), ($T::MIN, true)); - assert_eq!((0 as $T).carrying_add($T::MIN, true), ($T::MIN + 1, false)); - } - - #[test] - fn test_borrowing_sub() { - assert_eq!($T::MIN.borrowing_sub(1, false), ($T::MAX, true)); - assert_eq!($T::MIN.borrowing_sub(0, true), ($T::MAX, true)); - assert_eq!($T::MIN.borrowing_sub(1, true), ($T::MAX - 1, true)); - assert_eq!($T::MIN.borrowing_sub(-1, false), ($T::MIN + 1, false)); - assert_eq!($T::MIN.borrowing_sub(-1, true), ($T::MIN, false)); // no intermediate overflow - assert_eq!($T::MAX.borrowing_sub(-1, false), ($T::MIN, true)); - assert_eq!($T::MAX.borrowing_sub(-1, true), ($T::MAX, false)); // no intermediate overflow - assert_eq!((0 as $T).borrowing_sub($T::MIN, false), ($T::MIN, true)); - assert_eq!((0 as $T).borrowing_sub($T::MIN, true), ($T::MAX, false)); - } - - #[test] - fn test_midpoint() { - assert_eq!(<$T>::midpoint(1, 3), 2); - assert_eq!(<$T>::midpoint(3, 1), 2); - - assert_eq!(<$T>::midpoint(0, 0), 0); - assert_eq!(<$T>::midpoint(0, 2), 1); - assert_eq!(<$T>::midpoint(2, 0), 1); - assert_eq!(<$T>::midpoint(2, 2), 2); - - assert_eq!(<$T>::midpoint(1, 4), 2); - assert_eq!(<$T>::midpoint(4, 1), 2); - assert_eq!(<$T>::midpoint(3, 4), 3); - assert_eq!(<$T>::midpoint(4, 3), 3); - - assert_eq!(<$T>::midpoint(<$T>::MIN, <$T>::MAX), -1); - assert_eq!(<$T>::midpoint(<$T>::MAX, <$T>::MIN), -1); - assert_eq!(<$T>::midpoint(<$T>::MIN, <$T>::MIN), <$T>::MIN); - assert_eq!(<$T>::midpoint(<$T>::MAX, <$T>::MAX), <$T>::MAX); - - assert_eq!(<$T>::midpoint(<$T>::MIN, 6), <$T>::MIN / 2 + 3); - assert_eq!(<$T>::midpoint(6, <$T>::MIN), <$T>::MIN / 2 + 3); - assert_eq!(<$T>::midpoint(<$T>::MAX, 6), <$T>::MAX / 2 + 3); - assert_eq!(<$T>::midpoint(6, <$T>::MAX), <$T>::MAX / 2 + 3); - } - } - }; -} diff --git a/library/core/tests/num/mod.rs b/library/core/tests/num/mod.rs deleted file mode 100644 index 0fed854318d54..0000000000000 --- a/library/core/tests/num/mod.rs +++ /dev/null @@ -1,926 +0,0 @@ -use core::fmt::Debug; -use core::num::{can_not_overflow, IntErrorKind, ParseIntError, TryFromIntError}; -use core::ops::{Add, Div, Mul, Rem, Sub}; -use core::str::FromStr; - -#[macro_use] -mod int_macros; - -mod i128; -mod i16; -mod i32; -mod i64; -mod i8; - -#[macro_use] -mod uint_macros; - -mod u128; -mod u16; -mod u32; -mod u64; -mod u8; - -mod bignum; - -mod const_from; -mod dec2flt; -mod flt2dec; -mod int_log; -mod ops; -mod wrapping; - -mod ieee754; -mod nan; - -/// Adds the attribute to all items in the block. -macro_rules! cfg_block { - ($(#[$attr:meta]{$($it:item)*})*) => {$($( - #[$attr] - $it - )*)*} -} - -/// Groups items that assume the pointer width is either 16/32/64, and has to be altered if -/// support for larger/smaller pointer widths are added in the future. -macro_rules! assume_usize_width { - {$($it:item)*} => {#[cfg(not(any( - target_pointer_width = "16", target_pointer_width = "32", target_pointer_width = "64")))] - compile_error!("The current tests of try_from on usize/isize assume that \ - the pointer width is either 16, 32, or 64"); - $($it)* - } -} - -/// Helper function for testing numeric operations -pub fn test_num(ten: T, two: T) -where - T: PartialEq - + Add - + Sub - + Mul - + Div - + Rem - + Debug - + Copy, -{ - assert_eq!(ten.add(two), ten + two); - assert_eq!(ten.sub(two), ten - two); - assert_eq!(ten.mul(two), ten * two); - assert_eq!(ten.div(two), ten / two); - assert_eq!(ten.rem(two), ten % two); -} - -/// Helper function for asserting number parsing returns a specific error -fn test_parse(num_str: &str, expected: Result) -where - T: FromStr, - Result: PartialEq + Debug, -{ - assert_eq!(num_str.parse::().map_err(|e| e.kind().clone()), expected) -} - -#[test] -fn from_str_issue7588() { - let u: Option = u8::from_str_radix("1000", 10).ok(); - assert_eq!(u, None); - let s: Option = i16::from_str_radix("80000", 10).ok(); - assert_eq!(s, None); -} - -#[test] -fn test_int_from_str_overflow() { - test_parse::("127", Ok(127)); - test_parse::("128", Err(IntErrorKind::PosOverflow)); - - test_parse::("-128", Ok(-128)); - test_parse::("-129", Err(IntErrorKind::NegOverflow)); - - test_parse::("32767", Ok(32_767)); - test_parse::("32768", Err(IntErrorKind::PosOverflow)); - - test_parse::("-32768", Ok(-32_768)); - test_parse::("-32769", Err(IntErrorKind::NegOverflow)); - - test_parse::("2147483647", Ok(2_147_483_647)); - test_parse::("2147483648", Err(IntErrorKind::PosOverflow)); - - test_parse::("-2147483648", Ok(-2_147_483_648)); - test_parse::("-2147483649", Err(IntErrorKind::NegOverflow)); - - test_parse::("9223372036854775807", Ok(9_223_372_036_854_775_807)); - test_parse::("9223372036854775808", Err(IntErrorKind::PosOverflow)); - - test_parse::("-9223372036854775808", Ok(-9_223_372_036_854_775_808)); - test_parse::("-9223372036854775809", Err(IntErrorKind::NegOverflow)); -} - -#[test] -fn test_can_not_overflow() { - fn can_overflow(radix: u32, input: &str) -> bool - where - T: std::convert::TryFrom, - { - !can_not_overflow::(radix, T::try_from(-1_i8).is_ok(), input.as_bytes()) - } - - // Positive tests: - assert!(!can_overflow::(16, "F")); - assert!(!can_overflow::(16, "FF")); - - assert!(!can_overflow::(10, "9")); - assert!(!can_overflow::(10, "99")); - - // Negative tests: - - // Not currently in std lib (issue: #27728) - fn format_radix(mut x: T, radix: T) -> String - where - T: std::ops::Rem, - T: std::ops::Div, - T: std::cmp::PartialEq, - T: std::default::Default, - T: Copy, - T: Default, - u32: TryFrom, - { - let mut result = vec![]; - - loop { - let m = x % radix; - x = x / radix; - result.push( - std::char::from_digit(m.try_into().ok().unwrap(), radix.try_into().ok().unwrap()) - .unwrap(), - ); - if x == T::default() { - break; - } - } - result.into_iter().rev().collect() - } - - macro_rules! check { - ($($t:ty)*) => ($( - for base in 2..=36 { - let num = (<$t>::MAX as u128) + 1; - - // Calculate the string length for the smallest overflowing number: - let max_len_string = format_radix(num, base as u128); - // Ensure that string length is deemed to potentially overflow: - assert!(can_overflow::<$t>(base, &max_len_string)); - } - )*) - } - - check! { i8 i16 i32 i64 i128 isize usize u8 u16 u32 u64 } - - // Check u128 separately: - for base in 2..=36 { - let num = u128::MAX as u128; - let max_len_string = format_radix(num, base as u128); - // base 16 fits perfectly for u128 and won't overflow: - assert_eq!(can_overflow::(base, &max_len_string), base != 16); - } -} - -#[test] -fn test_leading_plus() { - test_parse::("+127", Ok(127)); - test_parse::("+9223372036854775807", Ok(9223372036854775807)); -} - -#[test] -fn test_invalid() { - test_parse::("--129", Err(IntErrorKind::InvalidDigit)); - test_parse::("++129", Err(IntErrorKind::InvalidDigit)); - test_parse::("Съешь", Err(IntErrorKind::InvalidDigit)); - test_parse::("123Hello", Err(IntErrorKind::InvalidDigit)); - test_parse::("--", Err(IntErrorKind::InvalidDigit)); - test_parse::("-", Err(IntErrorKind::InvalidDigit)); - test_parse::("+", Err(IntErrorKind::InvalidDigit)); - test_parse::("-1", Err(IntErrorKind::InvalidDigit)); -} - -#[test] -fn test_empty() { - test_parse::("", Err(IntErrorKind::Empty)); -} - -#[test] -fn test_infallible_try_from_int_error() { - let func = |x: i8| -> Result { Ok(x.try_into()?) }; - - assert!(func(0).is_ok()); -} - -const _TEST_CONST_PARSE: () = { - let Ok(-0x8000) = i16::from_str_radix("-8000", 16) else { panic!() }; - let Ok(12345) = u64::from_str_radix("12345", 10) else { panic!() }; - if let Err(e) = i8::from_str_radix("+", 10) { - let IntErrorKind::InvalidDigit = e.kind() else { panic!() }; - } else { - panic!() - } -}; - -macro_rules! test_impl_from { - ($fn_name:ident, bool, $target: ty) => { - #[test] - fn $fn_name() { - let one: $target = 1; - let zero: $target = 0; - assert_eq!(one, <$target>::from(true)); - assert_eq!(zero, <$target>::from(false)); - } - }; - ($fn_name: ident, $Small: ty, $Large: ty) => { - #[test] - fn $fn_name() { - let small_max = <$Small>::MAX; - let small_min = <$Small>::MIN; - let large_max: $Large = small_max.into(); - let large_min: $Large = small_min.into(); - assert_eq!(large_max as $Small, small_max); - assert_eq!(large_min as $Small, small_min); - } - }; -} - -// Unsigned -> Unsigned -test_impl_from! { test_u8u16, u8, u16 } -test_impl_from! { test_u8u32, u8, u32 } -test_impl_from! { test_u8u64, u8, u64 } -test_impl_from! { test_u8usize, u8, usize } -test_impl_from! { test_u16u32, u16, u32 } -test_impl_from! { test_u16u64, u16, u64 } -test_impl_from! { test_u32u64, u32, u64 } - -// Signed -> Signed -test_impl_from! { test_i8i16, i8, i16 } -test_impl_from! { test_i8i32, i8, i32 } -test_impl_from! { test_i8i64, i8, i64 } -test_impl_from! { test_i8isize, i8, isize } -test_impl_from! { test_i16i32, i16, i32 } -test_impl_from! { test_i16i64, i16, i64 } -test_impl_from! { test_i32i64, i32, i64 } - -// Unsigned -> Signed -test_impl_from! { test_u8i16, u8, i16 } -test_impl_from! { test_u8i32, u8, i32 } -test_impl_from! { test_u8i64, u8, i64 } -test_impl_from! { test_u16i32, u16, i32 } -test_impl_from! { test_u16i64, u16, i64 } -test_impl_from! { test_u32i64, u32, i64 } - -// Bool -> Integer -test_impl_from! { test_boolu8, bool, u8 } -test_impl_from! { test_boolu16, bool, u16 } -test_impl_from! { test_boolu32, bool, u32 } -test_impl_from! { test_boolu64, bool, u64 } -test_impl_from! { test_boolu128, bool, u128 } -test_impl_from! { test_booli8, bool, i8 } -test_impl_from! { test_booli16, bool, i16 } -test_impl_from! { test_booli32, bool, i32 } -test_impl_from! { test_booli64, bool, i64 } -test_impl_from! { test_booli128, bool, i128 } - -// Signed -> Float -test_impl_from! { test_i8f32, i8, f32 } -test_impl_from! { test_i8f64, i8, f64 } -test_impl_from! { test_i16f32, i16, f32 } -test_impl_from! { test_i16f64, i16, f64 } -test_impl_from! { test_i32f64, i32, f64 } - -// Unsigned -> Float -test_impl_from! { test_u8f32, u8, f32 } -test_impl_from! { test_u8f64, u8, f64 } -test_impl_from! { test_u16f32, u16, f32 } -test_impl_from! { test_u16f64, u16, f64 } -test_impl_from! { test_u32f64, u32, f64 } - -// Float -> Float -#[test] -fn test_f32f64() { - let max: f64 = f32::MAX.into(); - assert_eq!(max as f32, f32::MAX); - assert!(max.is_normal()); - - let min: f64 = f32::MIN.into(); - assert_eq!(min as f32, f32::MIN); - assert!(min.is_normal()); - - let min_positive: f64 = f32::MIN_POSITIVE.into(); - assert_eq!(min_positive as f32, f32::MIN_POSITIVE); - assert!(min_positive.is_normal()); - - let epsilon: f64 = f32::EPSILON.into(); - assert_eq!(epsilon as f32, f32::EPSILON); - assert!(epsilon.is_normal()); - - let zero: f64 = (0.0f32).into(); - assert_eq!(zero as f32, 0.0f32); - assert!(zero.is_sign_positive()); - - let neg_zero: f64 = (-0.0f32).into(); - assert_eq!(neg_zero as f32, -0.0f32); - assert!(neg_zero.is_sign_negative()); - - let infinity: f64 = f32::INFINITY.into(); - assert_eq!(infinity as f32, f32::INFINITY); - assert!(infinity.is_infinite()); - assert!(infinity.is_sign_positive()); - - let neg_infinity: f64 = f32::NEG_INFINITY.into(); - assert_eq!(neg_infinity as f32, f32::NEG_INFINITY); - assert!(neg_infinity.is_infinite()); - assert!(neg_infinity.is_sign_negative()); - - let nan: f64 = f32::NAN.into(); - assert!(nan.is_nan()); -} - -/// Conversions where the full width of $source can be represented as $target -macro_rules! test_impl_try_from_always_ok { - ($fn_name:ident, $source:ty, $target: ty) => { - #[test] - fn $fn_name() { - let max = <$source>::MAX; - let min = <$source>::MIN; - let zero: $source = 0; - assert_eq!(<$target as TryFrom<$source>>::try_from(max).unwrap(), max as $target); - assert_eq!(<$target as TryFrom<$source>>::try_from(min).unwrap(), min as $target); - assert_eq!(<$target as TryFrom<$source>>::try_from(zero).unwrap(), zero as $target); - } - }; -} - -test_impl_try_from_always_ok! { test_try_u8u8, u8, u8 } -test_impl_try_from_always_ok! { test_try_u8u16, u8, u16 } -test_impl_try_from_always_ok! { test_try_u8u32, u8, u32 } -test_impl_try_from_always_ok! { test_try_u8u64, u8, u64 } -test_impl_try_from_always_ok! { test_try_u8u128, u8, u128 } -test_impl_try_from_always_ok! { test_try_u8i16, u8, i16 } -test_impl_try_from_always_ok! { test_try_u8i32, u8, i32 } -test_impl_try_from_always_ok! { test_try_u8i64, u8, i64 } -test_impl_try_from_always_ok! { test_try_u8i128, u8, i128 } - -test_impl_try_from_always_ok! { test_try_u16u16, u16, u16 } -test_impl_try_from_always_ok! { test_try_u16u32, u16, u32 } -test_impl_try_from_always_ok! { test_try_u16u64, u16, u64 } -test_impl_try_from_always_ok! { test_try_u16u128, u16, u128 } -test_impl_try_from_always_ok! { test_try_u16i32, u16, i32 } -test_impl_try_from_always_ok! { test_try_u16i64, u16, i64 } -test_impl_try_from_always_ok! { test_try_u16i128, u16, i128 } - -test_impl_try_from_always_ok! { test_try_u32u32, u32, u32 } -test_impl_try_from_always_ok! { test_try_u32u64, u32, u64 } -test_impl_try_from_always_ok! { test_try_u32u128, u32, u128 } -test_impl_try_from_always_ok! { test_try_u32i64, u32, i64 } -test_impl_try_from_always_ok! { test_try_u32i128, u32, i128 } - -test_impl_try_from_always_ok! { test_try_u64u64, u64, u64 } -test_impl_try_from_always_ok! { test_try_u64u128, u64, u128 } -test_impl_try_from_always_ok! { test_try_u64i128, u64, i128 } - -test_impl_try_from_always_ok! { test_try_u128u128, u128, u128 } - -test_impl_try_from_always_ok! { test_try_i8i8, i8, i8 } -test_impl_try_from_always_ok! { test_try_i8i16, i8, i16 } -test_impl_try_from_always_ok! { test_try_i8i32, i8, i32 } -test_impl_try_from_always_ok! { test_try_i8i64, i8, i64 } -test_impl_try_from_always_ok! { test_try_i8i128, i8, i128 } - -test_impl_try_from_always_ok! { test_try_i16i16, i16, i16 } -test_impl_try_from_always_ok! { test_try_i16i32, i16, i32 } -test_impl_try_from_always_ok! { test_try_i16i64, i16, i64 } -test_impl_try_from_always_ok! { test_try_i16i128, i16, i128 } - -test_impl_try_from_always_ok! { test_try_i32i32, i32, i32 } -test_impl_try_from_always_ok! { test_try_i32i64, i32, i64 } -test_impl_try_from_always_ok! { test_try_i32i128, i32, i128 } - -test_impl_try_from_always_ok! { test_try_i64i64, i64, i64 } -test_impl_try_from_always_ok! { test_try_i64i128, i64, i128 } - -test_impl_try_from_always_ok! { test_try_i128i128, i128, i128 } - -test_impl_try_from_always_ok! { test_try_usizeusize, usize, usize } -test_impl_try_from_always_ok! { test_try_isizeisize, isize, isize } - -assume_usize_width! { - test_impl_try_from_always_ok! { test_try_u8usize, u8, usize } - test_impl_try_from_always_ok! { test_try_u8isize, u8, isize } - test_impl_try_from_always_ok! { test_try_i8isize, i8, isize } - - test_impl_try_from_always_ok! { test_try_u16usize, u16, usize } - test_impl_try_from_always_ok! { test_try_i16isize, i16, isize } - - test_impl_try_from_always_ok! { test_try_usizeu64, usize, u64 } - test_impl_try_from_always_ok! { test_try_usizeu128, usize, u128 } - test_impl_try_from_always_ok! { test_try_usizei128, usize, i128 } - - test_impl_try_from_always_ok! { test_try_isizei64, isize, i64 } - test_impl_try_from_always_ok! { test_try_isizei128, isize, i128 } - - cfg_block!( - #[cfg(target_pointer_width = "16")] { - test_impl_try_from_always_ok! { test_try_usizeu16, usize, u16 } - test_impl_try_from_always_ok! { test_try_isizei16, isize, i16 } - test_impl_try_from_always_ok! { test_try_usizeu32, usize, u32 } - test_impl_try_from_always_ok! { test_try_usizei32, usize, i32 } - test_impl_try_from_always_ok! { test_try_isizei32, isize, i32 } - test_impl_try_from_always_ok! { test_try_usizei64, usize, i64 } - } - - #[cfg(target_pointer_width = "32")] { - test_impl_try_from_always_ok! { test_try_u16isize, u16, isize } - test_impl_try_from_always_ok! { test_try_usizeu32, usize, u32 } - test_impl_try_from_always_ok! { test_try_isizei32, isize, i32 } - test_impl_try_from_always_ok! { test_try_u32usize, u32, usize } - test_impl_try_from_always_ok! { test_try_i32isize, i32, isize } - test_impl_try_from_always_ok! { test_try_usizei64, usize, i64 } - } - - #[cfg(target_pointer_width = "64")] { - test_impl_try_from_always_ok! { test_try_u16isize, u16, isize } - test_impl_try_from_always_ok! { test_try_u32usize, u32, usize } - test_impl_try_from_always_ok! { test_try_u32isize, u32, isize } - test_impl_try_from_always_ok! { test_try_i32isize, i32, isize } - test_impl_try_from_always_ok! { test_try_u64usize, u64, usize } - test_impl_try_from_always_ok! { test_try_i64isize, i64, isize } - } - ); -} - -/// Conversions where max of $source can be represented as $target, -macro_rules! test_impl_try_from_signed_to_unsigned_upper_ok { - ($fn_name:ident, $source:ty, $target:ty) => { - #[test] - fn $fn_name() { - let max = <$source>::MAX; - let min = <$source>::MIN; - let zero: $source = 0; - let neg_one: $source = -1; - assert_eq!(<$target as TryFrom<$source>>::try_from(max).unwrap(), max as $target); - assert!(<$target as TryFrom<$source>>::try_from(min).is_err()); - assert_eq!(<$target as TryFrom<$source>>::try_from(zero).unwrap(), zero as $target); - assert!(<$target as TryFrom<$source>>::try_from(neg_one).is_err()); - } - }; -} - -test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_i8u8, i8, u8 } -test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_i8u16, i8, u16 } -test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_i8u32, i8, u32 } -test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_i8u64, i8, u64 } -test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_i8u128, i8, u128 } - -test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_i16u16, i16, u16 } -test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_i16u32, i16, u32 } -test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_i16u64, i16, u64 } -test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_i16u128, i16, u128 } - -test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_i32u32, i32, u32 } -test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_i32u64, i32, u64 } -test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_i32u128, i32, u128 } - -test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_i64u64, i64, u64 } -test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_i64u128, i64, u128 } - -test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_i128u128, i128, u128 } - -assume_usize_width! { - test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_i8usize, i8, usize } - test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_i16usize, i16, usize } - - test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_isizeu64, isize, u64 } - test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_isizeu128, isize, u128 } - test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_isizeusize, isize, usize } - - cfg_block!( - #[cfg(target_pointer_width = "16")] { - test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_isizeu16, isize, u16 } - test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_isizeu32, isize, u32 } - } - - #[cfg(target_pointer_width = "32")] { - test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_isizeu32, isize, u32 } - - test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_i32usize, i32, usize } - } - - #[cfg(target_pointer_width = "64")] { - test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_i32usize, i32, usize } - test_impl_try_from_signed_to_unsigned_upper_ok! { test_try_i64usize, i64, usize } - } - ); -} - -/// Conversions where max of $source can not be represented as $target, -/// but min can. -macro_rules! test_impl_try_from_unsigned_to_signed_upper_err { - ($fn_name:ident, $source:ty, $target:ty) => { - #[test] - fn $fn_name() { - let max = <$source>::MAX; - let min = <$source>::MIN; - let zero: $source = 0; - assert!(<$target as TryFrom<$source>>::try_from(max).is_err()); - assert_eq!(<$target as TryFrom<$source>>::try_from(min).unwrap(), min as $target); - assert_eq!(<$target as TryFrom<$source>>::try_from(zero).unwrap(), zero as $target); - } - }; -} - -test_impl_try_from_unsigned_to_signed_upper_err! { test_try_u8i8, u8, i8 } - -test_impl_try_from_unsigned_to_signed_upper_err! { test_try_u16i8, u16, i8 } -test_impl_try_from_unsigned_to_signed_upper_err! { test_try_u16i16, u16, i16 } - -test_impl_try_from_unsigned_to_signed_upper_err! { test_try_u32i8, u32, i8 } -test_impl_try_from_unsigned_to_signed_upper_err! { test_try_u32i16, u32, i16 } -test_impl_try_from_unsigned_to_signed_upper_err! { test_try_u32i32, u32, i32 } - -test_impl_try_from_unsigned_to_signed_upper_err! { test_try_u64i8, u64, i8 } -test_impl_try_from_unsigned_to_signed_upper_err! { test_try_u64i16, u64, i16 } -test_impl_try_from_unsigned_to_signed_upper_err! { test_try_u64i32, u64, i32 } -test_impl_try_from_unsigned_to_signed_upper_err! { test_try_u64i64, u64, i64 } - -test_impl_try_from_unsigned_to_signed_upper_err! { test_try_u128i8, u128, i8 } -test_impl_try_from_unsigned_to_signed_upper_err! { test_try_u128i16, u128, i16 } -test_impl_try_from_unsigned_to_signed_upper_err! { test_try_u128i32, u128, i32 } -test_impl_try_from_unsigned_to_signed_upper_err! { test_try_u128i64, u128, i64 } -test_impl_try_from_unsigned_to_signed_upper_err! { test_try_u128i128, u128, i128 } - -assume_usize_width! { - test_impl_try_from_unsigned_to_signed_upper_err! { test_try_u64isize, u64, isize } - test_impl_try_from_unsigned_to_signed_upper_err! { test_try_u128isize, u128, isize } - - test_impl_try_from_unsigned_to_signed_upper_err! { test_try_usizei8, usize, i8 } - test_impl_try_from_unsigned_to_signed_upper_err! { test_try_usizei16, usize, i16 } - test_impl_try_from_unsigned_to_signed_upper_err! { test_try_usizeisize, usize, isize } - - cfg_block!( - #[cfg(target_pointer_width = "16")] { - test_impl_try_from_unsigned_to_signed_upper_err! { test_try_u16isize, u16, isize } - test_impl_try_from_unsigned_to_signed_upper_err! { test_try_u32isize, u32, isize } - } - - #[cfg(target_pointer_width = "32")] { - test_impl_try_from_unsigned_to_signed_upper_err! { test_try_u32isize, u32, isize } - test_impl_try_from_unsigned_to_signed_upper_err! { test_try_usizei32, usize, i32 } - } - - #[cfg(target_pointer_width = "64")] { - test_impl_try_from_unsigned_to_signed_upper_err! { test_try_usizei32, usize, i32 } - test_impl_try_from_unsigned_to_signed_upper_err! { test_try_usizei64, usize, i64 } - } - ); -} - -/// Conversions where min/max of $source can not be represented as $target. -macro_rules! test_impl_try_from_same_sign_err { - ($fn_name:ident, $source:ty, $target:ty) => { - #[test] - fn $fn_name() { - let max = <$source>::MAX; - let min = <$source>::MIN; - let zero: $source = 0; - let t_max = <$target>::MAX; - let t_min = <$target>::MIN; - assert!(<$target as TryFrom<$source>>::try_from(max).is_err()); - if min != 0 { - assert!(<$target as TryFrom<$source>>::try_from(min).is_err()); - } - assert_eq!(<$target as TryFrom<$source>>::try_from(zero).unwrap(), zero as $target); - assert_eq!( - <$target as TryFrom<$source>>::try_from(t_max as $source).unwrap(), - t_max as $target - ); - assert_eq!( - <$target as TryFrom<$source>>::try_from(t_min as $source).unwrap(), - t_min as $target - ); - } - }; -} - -test_impl_try_from_same_sign_err! { test_try_u16u8, u16, u8 } - -test_impl_try_from_same_sign_err! { test_try_u32u8, u32, u8 } -test_impl_try_from_same_sign_err! { test_try_u32u16, u32, u16 } - -test_impl_try_from_same_sign_err! { test_try_u64u8, u64, u8 } -test_impl_try_from_same_sign_err! { test_try_u64u16, u64, u16 } -test_impl_try_from_same_sign_err! { test_try_u64u32, u64, u32 } - -test_impl_try_from_same_sign_err! { test_try_u128u8, u128, u8 } -test_impl_try_from_same_sign_err! { test_try_u128u16, u128, u16 } -test_impl_try_from_same_sign_err! { test_try_u128u32, u128, u32 } -test_impl_try_from_same_sign_err! { test_try_u128u64, u128, u64 } - -test_impl_try_from_same_sign_err! { test_try_i16i8, i16, i8 } -test_impl_try_from_same_sign_err! { test_try_isizei8, isize, i8 } - -test_impl_try_from_same_sign_err! { test_try_i32i8, i32, i8 } -test_impl_try_from_same_sign_err! { test_try_i32i16, i32, i16 } - -test_impl_try_from_same_sign_err! { test_try_i64i8, i64, i8 } -test_impl_try_from_same_sign_err! { test_try_i64i16, i64, i16 } -test_impl_try_from_same_sign_err! { test_try_i64i32, i64, i32 } - -test_impl_try_from_same_sign_err! { test_try_i128i8, i128, i8 } -test_impl_try_from_same_sign_err! { test_try_i128i16, i128, i16 } -test_impl_try_from_same_sign_err! { test_try_i128i32, i128, i32 } -test_impl_try_from_same_sign_err! { test_try_i128i64, i128, i64 } - -assume_usize_width! { - test_impl_try_from_same_sign_err! { test_try_usizeu8, usize, u8 } - test_impl_try_from_same_sign_err! { test_try_u128usize, u128, usize } - test_impl_try_from_same_sign_err! { test_try_i128isize, i128, isize } - - cfg_block!( - #[cfg(target_pointer_width = "16")] { - test_impl_try_from_same_sign_err! { test_try_u32usize, u32, usize } - test_impl_try_from_same_sign_err! { test_try_u64usize, u64, usize } - - test_impl_try_from_same_sign_err! { test_try_i32isize, i32, isize } - test_impl_try_from_same_sign_err! { test_try_i64isize, i64, isize } - } - - #[cfg(target_pointer_width = "32")] { - test_impl_try_from_same_sign_err! { test_try_u64usize, u64, usize } - test_impl_try_from_same_sign_err! { test_try_usizeu16, usize, u16 } - - test_impl_try_from_same_sign_err! { test_try_i64isize, i64, isize } - test_impl_try_from_same_sign_err! { test_try_isizei16, isize, i16 } - } - - #[cfg(target_pointer_width = "64")] { - test_impl_try_from_same_sign_err! { test_try_usizeu16, usize, u16 } - test_impl_try_from_same_sign_err! { test_try_usizeu32, usize, u32 } - - test_impl_try_from_same_sign_err! { test_try_isizei16, isize, i16 } - test_impl_try_from_same_sign_err! { test_try_isizei32, isize, i32 } - } - ); -} - -/// Conversions where neither the min nor the max of $source can be represented by -/// $target, but max/min of the target can be represented by the source. -macro_rules! test_impl_try_from_signed_to_unsigned_err { - ($fn_name:ident, $source:ty, $target:ty) => { - #[test] - fn $fn_name() { - let max = <$source>::MAX; - let min = <$source>::MIN; - let zero: $source = 0; - let t_max = <$target>::MAX; - let t_min = <$target>::MIN; - assert!(<$target as TryFrom<$source>>::try_from(max).is_err()); - assert!(<$target as TryFrom<$source>>::try_from(min).is_err()); - assert_eq!(<$target as TryFrom<$source>>::try_from(zero).unwrap(), zero as $target); - assert_eq!( - <$target as TryFrom<$source>>::try_from(t_max as $source).unwrap(), - t_max as $target - ); - assert_eq!( - <$target as TryFrom<$source>>::try_from(t_min as $source).unwrap(), - t_min as $target - ); - } - }; -} - -test_impl_try_from_signed_to_unsigned_err! { test_try_i16u8, i16, u8 } - -test_impl_try_from_signed_to_unsigned_err! { test_try_i32u8, i32, u8 } -test_impl_try_from_signed_to_unsigned_err! { test_try_i32u16, i32, u16 } - -test_impl_try_from_signed_to_unsigned_err! { test_try_i64u8, i64, u8 } -test_impl_try_from_signed_to_unsigned_err! { test_try_i64u16, i64, u16 } -test_impl_try_from_signed_to_unsigned_err! { test_try_i64u32, i64, u32 } - -test_impl_try_from_signed_to_unsigned_err! { test_try_i128u8, i128, u8 } -test_impl_try_from_signed_to_unsigned_err! { test_try_i128u16, i128, u16 } -test_impl_try_from_signed_to_unsigned_err! { test_try_i128u32, i128, u32 } -test_impl_try_from_signed_to_unsigned_err! { test_try_i128u64, i128, u64 } - -assume_usize_width! { - test_impl_try_from_signed_to_unsigned_err! { test_try_isizeu8, isize, u8 } - test_impl_try_from_signed_to_unsigned_err! { test_try_i128usize, i128, usize } - - cfg_block! { - #[cfg(target_pointer_width = "16")] { - test_impl_try_from_signed_to_unsigned_err! { test_try_i32usize, i32, usize } - test_impl_try_from_signed_to_unsigned_err! { test_try_i64usize, i64, usize } - } - #[cfg(target_pointer_width = "32")] { - test_impl_try_from_signed_to_unsigned_err! { test_try_i64usize, i64, usize } - - test_impl_try_from_signed_to_unsigned_err! { test_try_isizeu16, isize, u16 } - } - #[cfg(target_pointer_width = "64")] { - test_impl_try_from_signed_to_unsigned_err! { test_try_isizeu16, isize, u16 } - test_impl_try_from_signed_to_unsigned_err! { test_try_isizeu32, isize, u32 } - } - } -} - -macro_rules! test_float { - ($modname: ident, $fty: ty, $inf: expr, $neginf: expr, $nan: expr, $min: expr, $max: expr, $min_pos: expr) => { - mod $modname { - #[test] - fn min() { - assert_eq!((0.0 as $fty).min(0.0), 0.0); - assert!((0.0 as $fty).min(0.0).is_sign_positive()); - assert_eq!((-0.0 as $fty).min(-0.0), -0.0); - assert!((-0.0 as $fty).min(-0.0).is_sign_negative()); - assert_eq!((9.0 as $fty).min(9.0), 9.0); - assert_eq!((-9.0 as $fty).min(0.0), -9.0); - assert_eq!((0.0 as $fty).min(9.0), 0.0); - assert!((0.0 as $fty).min(9.0).is_sign_positive()); - assert_eq!((-0.0 as $fty).min(9.0), -0.0); - assert!((-0.0 as $fty).min(9.0).is_sign_negative()); - assert_eq!((-0.0 as $fty).min(-9.0), -9.0); - assert_eq!(($inf as $fty).min(9.0), 9.0); - assert_eq!((9.0 as $fty).min($inf), 9.0); - assert_eq!(($inf as $fty).min(-9.0), -9.0); - assert_eq!((-9.0 as $fty).min($inf), -9.0); - assert_eq!(($neginf as $fty).min(9.0), $neginf); - assert_eq!((9.0 as $fty).min($neginf), $neginf); - assert_eq!(($neginf as $fty).min(-9.0), $neginf); - assert_eq!((-9.0 as $fty).min($neginf), $neginf); - assert_eq!(($nan as $fty).min(9.0), 9.0); - assert_eq!(($nan as $fty).min(-9.0), -9.0); - assert_eq!((9.0 as $fty).min($nan), 9.0); - assert_eq!((-9.0 as $fty).min($nan), -9.0); - assert!(($nan as $fty).min($nan).is_nan()); - } - #[test] - fn max() { - assert_eq!((0.0 as $fty).max(0.0), 0.0); - assert!((0.0 as $fty).max(0.0).is_sign_positive()); - assert_eq!((-0.0 as $fty).max(-0.0), -0.0); - assert!((-0.0 as $fty).max(-0.0).is_sign_negative()); - assert_eq!((9.0 as $fty).max(9.0), 9.0); - assert_eq!((-9.0 as $fty).max(0.0), 0.0); - assert!((-9.0 as $fty).max(0.0).is_sign_positive()); - assert_eq!((-9.0 as $fty).max(-0.0), -0.0); - assert!((-9.0 as $fty).max(-0.0).is_sign_negative()); - assert_eq!((0.0 as $fty).max(9.0), 9.0); - assert_eq!((0.0 as $fty).max(-9.0), 0.0); - assert!((0.0 as $fty).max(-9.0).is_sign_positive()); - assert_eq!((-0.0 as $fty).max(-9.0), -0.0); - assert!((-0.0 as $fty).max(-9.0).is_sign_negative()); - assert_eq!(($inf as $fty).max(9.0), $inf); - assert_eq!((9.0 as $fty).max($inf), $inf); - assert_eq!(($inf as $fty).max(-9.0), $inf); - assert_eq!((-9.0 as $fty).max($inf), $inf); - assert_eq!(($neginf as $fty).max(9.0), 9.0); - assert_eq!((9.0 as $fty).max($neginf), 9.0); - assert_eq!(($neginf as $fty).max(-9.0), -9.0); - assert_eq!((-9.0 as $fty).max($neginf), -9.0); - assert_eq!(($nan as $fty).max(9.0), 9.0); - assert_eq!(($nan as $fty).max(-9.0), -9.0); - assert_eq!((9.0 as $fty).max($nan), 9.0); - assert_eq!((-9.0 as $fty).max($nan), -9.0); - assert!(($nan as $fty).max($nan).is_nan()); - } - #[test] - fn minimum() { - assert_eq!((0.0 as $fty).minimum(0.0), 0.0); - assert!((0.0 as $fty).minimum(0.0).is_sign_positive()); - assert_eq!((-0.0 as $fty).minimum(0.0), -0.0); - assert!((-0.0 as $fty).minimum(0.0).is_sign_negative()); - assert_eq!((-0.0 as $fty).minimum(-0.0), -0.0); - assert!((-0.0 as $fty).minimum(-0.0).is_sign_negative()); - assert_eq!((9.0 as $fty).minimum(9.0), 9.0); - assert_eq!((-9.0 as $fty).minimum(0.0), -9.0); - assert_eq!((0.0 as $fty).minimum(9.0), 0.0); - assert!((0.0 as $fty).minimum(9.0).is_sign_positive()); - assert_eq!((-0.0 as $fty).minimum(9.0), -0.0); - assert!((-0.0 as $fty).minimum(9.0).is_sign_negative()); - assert_eq!((-0.0 as $fty).minimum(-9.0), -9.0); - assert_eq!(($inf as $fty).minimum(9.0), 9.0); - assert_eq!((9.0 as $fty).minimum($inf), 9.0); - assert_eq!(($inf as $fty).minimum(-9.0), -9.0); - assert_eq!((-9.0 as $fty).minimum($inf), -9.0); - assert_eq!(($neginf as $fty).minimum(9.0), $neginf); - assert_eq!((9.0 as $fty).minimum($neginf), $neginf); - assert_eq!(($neginf as $fty).minimum(-9.0), $neginf); - assert_eq!((-9.0 as $fty).minimum($neginf), $neginf); - assert!(($nan as $fty).minimum(9.0).is_nan()); - assert!(($nan as $fty).minimum(-9.0).is_nan()); - assert!((9.0 as $fty).minimum($nan).is_nan()); - assert!((-9.0 as $fty).minimum($nan).is_nan()); - assert!(($nan as $fty).minimum($nan).is_nan()); - } - #[test] - fn maximum() { - assert_eq!((0.0 as $fty).maximum(0.0), 0.0); - assert!((0.0 as $fty).maximum(0.0).is_sign_positive()); - assert_eq!((-0.0 as $fty).maximum(0.0), 0.0); - assert!((-0.0 as $fty).maximum(0.0).is_sign_positive()); - assert_eq!((-0.0 as $fty).maximum(-0.0), -0.0); - assert!((-0.0 as $fty).maximum(-0.0).is_sign_negative()); - assert_eq!((9.0 as $fty).maximum(9.0), 9.0); - assert_eq!((-9.0 as $fty).maximum(0.0), 0.0); - assert!((-9.0 as $fty).maximum(0.0).is_sign_positive()); - assert_eq!((-9.0 as $fty).maximum(-0.0), -0.0); - assert!((-9.0 as $fty).maximum(-0.0).is_sign_negative()); - assert_eq!((0.0 as $fty).maximum(9.0), 9.0); - assert_eq!((0.0 as $fty).maximum(-9.0), 0.0); - assert!((0.0 as $fty).maximum(-9.0).is_sign_positive()); - assert_eq!((-0.0 as $fty).maximum(-9.0), -0.0); - assert!((-0.0 as $fty).maximum(-9.0).is_sign_negative()); - assert_eq!(($inf as $fty).maximum(9.0), $inf); - assert_eq!((9.0 as $fty).maximum($inf), $inf); - assert_eq!(($inf as $fty).maximum(-9.0), $inf); - assert_eq!((-9.0 as $fty).maximum($inf), $inf); - assert_eq!(($neginf as $fty).maximum(9.0), 9.0); - assert_eq!((9.0 as $fty).maximum($neginf), 9.0); - assert_eq!(($neginf as $fty).maximum(-9.0), -9.0); - assert_eq!((-9.0 as $fty).maximum($neginf), -9.0); - assert!(($nan as $fty).maximum(9.0).is_nan()); - assert!(($nan as $fty).maximum(-9.0).is_nan()); - assert!((9.0 as $fty).maximum($nan).is_nan()); - assert!((-9.0 as $fty).maximum($nan).is_nan()); - assert!(($nan as $fty).maximum($nan).is_nan()); - } - #[test] - fn midpoint() { - assert_eq!((0.5 as $fty).midpoint(0.5), 0.5); - assert_eq!((0.5 as $fty).midpoint(2.5), 1.5); - assert_eq!((3.0 as $fty).midpoint(4.0), 3.5); - assert_eq!((-3.0 as $fty).midpoint(4.0), 0.5); - assert_eq!((3.0 as $fty).midpoint(-4.0), -0.5); - assert_eq!((-3.0 as $fty).midpoint(-4.0), -3.5); - assert_eq!((0.0 as $fty).midpoint(0.0), 0.0); - assert_eq!((-0.0 as $fty).midpoint(-0.0), -0.0); - assert_eq!((-5.0 as $fty).midpoint(5.0), 0.0); - assert_eq!(($max as $fty).midpoint($min), 0.0); - assert_eq!(($min as $fty).midpoint($max), -0.0); - assert_eq!(($max as $fty).midpoint($min_pos), $max / 2.); - assert_eq!((-$max as $fty).midpoint($min_pos), -$max / 2.); - assert_eq!(($max as $fty).midpoint(-$min_pos), $max / 2.); - assert_eq!((-$max as $fty).midpoint(-$min_pos), -$max / 2.); - assert_eq!(($min_pos as $fty).midpoint($max), $max / 2.); - assert_eq!(($min_pos as $fty).midpoint(-$max), -$max / 2.); - assert_eq!((-$min_pos as $fty).midpoint($max), $max / 2.); - assert_eq!((-$min_pos as $fty).midpoint(-$max), -$max / 2.); - assert_eq!(($max as $fty).midpoint($max), $max); - assert_eq!(($min_pos as $fty).midpoint($min_pos), $min_pos); - assert_eq!((-$min_pos as $fty).midpoint(-$min_pos), -$min_pos); - assert_eq!(($max as $fty).midpoint(5.0), $max / 2.0 + 2.5); - assert_eq!(($max as $fty).midpoint(-5.0), $max / 2.0 - 2.5); - assert_eq!(($inf as $fty).midpoint($inf), $inf); - assert_eq!(($neginf as $fty).midpoint($neginf), $neginf); - assert!(($nan as $fty).midpoint(1.0).is_nan()); - assert!((1.0 as $fty).midpoint($nan).is_nan()); - assert!(($nan as $fty).midpoint($nan).is_nan()); - } - #[test] - fn rem_euclid() { - let a: $fty = 42.0; - assert!($inf.rem_euclid(a).is_nan()); - assert_eq!(a.rem_euclid($inf), a); - assert!(a.rem_euclid($nan).is_nan()); - assert!($inf.rem_euclid($inf).is_nan()); - assert!($inf.rem_euclid($nan).is_nan()); - assert!($nan.rem_euclid($inf).is_nan()); - } - #[test] - fn div_euclid() { - let a: $fty = 42.0; - assert_eq!(a.div_euclid($inf), 0.0); - assert!(a.div_euclid($nan).is_nan()); - assert!($inf.div_euclid($inf).is_nan()); - assert!($inf.div_euclid($nan).is_nan()); - assert!($nan.div_euclid($inf).is_nan()); - } - } - }; -} - -test_float!( - f32, - f32, - f32::INFINITY, - f32::NEG_INFINITY, - f32::NAN, - f32::MIN, - f32::MAX, - f32::MIN_POSITIVE -); -test_float!( - f64, - f64, - f64::INFINITY, - f64::NEG_INFINITY, - f64::NAN, - f64::MIN, - f64::MAX, - f64::MIN_POSITIVE -); diff --git a/library/core/tests/num/nan.rs b/library/core/tests/num/nan.rs deleted file mode 100644 index ef81988c9612f..0000000000000 --- a/library/core/tests/num/nan.rs +++ /dev/null @@ -1,7 +0,0 @@ -#[test] -fn test_nan() { - let x = "NaN".to_string(); - assert_eq!(format!("{}", f64::NAN), x); - assert_eq!(format!("{:e}", f64::NAN), x); - assert_eq!(format!("{:E}", f64::NAN), x); -} diff --git a/library/core/tests/num/ops.rs b/library/core/tests/num/ops.rs deleted file mode 100644 index ae8b938250ec9..0000000000000 --- a/library/core/tests/num/ops.rs +++ /dev/null @@ -1,232 +0,0 @@ -use core::ops::*; - -// For types L and R, checks that a trait implementation exists for -// * binary ops: L op R, L op &R, &L op R and &L op &R -// * assign ops: &mut L op R, &mut L op &R -macro_rules! impl_defined { - ($op:ident, $method:ident($lhs:literal, $rhs:literal), $result:literal, $lt:ty, $rt:ty) => { - let lhs = $lhs as $lt; - let rhs = $rhs as $rt; - assert_eq!($result as $lt, $op::$method(lhs, rhs)); - assert_eq!($result as $lt, $op::$method(lhs, &rhs)); - assert_eq!($result as $lt, $op::$method(&lhs, rhs)); - assert_eq!($result as $lt, $op::$method(&lhs, &rhs)); - }; - ($op:ident, $method:ident(&mut $lhs:literal, $rhs:literal), $result:literal, $lt:ty, $rt:ty) => { - let rhs = $rhs as $rt; - let mut lhs = $lhs as $lt; - $op::$method(&mut lhs, rhs); - assert_eq!($result as $lt, lhs); - - let mut lhs = $lhs as $lt; - $op::$method(&mut lhs, &rhs); - assert_eq!($result as $lt, lhs); - }; -} - -// For all specified types T, checks that a trait implementation exists for -// * binary ops: T op T, T op &T, &T op T and &T op &T -// * assign ops: &mut T op T, &mut T op &T -// * unary ops: op T and op &T -macro_rules! impls_defined { - ($op:ident, $method:ident($lhs:literal, $rhs:literal), $result:literal, $($t:ty),+) => {$( - impl_defined!($op, $method($lhs, $rhs), $result, $t, $t); - )+}; - ($op:ident, $method:ident(&mut $lhs:literal, $rhs:literal), $result:literal, $($t:ty),+) => {$( - impl_defined!($op, $method(&mut $lhs, $rhs), $result, $t, $t); - )+}; - ($op:ident, $method:ident($operand:literal), $result:literal, $($t:ty),+) => {$( - let operand = $operand as $t; - assert_eq!($result as $t, $op::$method(operand)); - assert_eq!($result as $t, $op::$method(&operand)); - )+}; -} - -macro_rules! test_op { - ($fn_name:ident, $op:ident::$method:ident($lhs:literal), $result:literal, $($t:ty),+) => { - #[test] - fn $fn_name() { - impls_defined!($op, $method($lhs), $result, $($t),+); - } - }; -} - -test_op!(test_neg_defined, Neg::neg(0), 0, i8, i16, i32, i64, f32, f64); -#[cfg(not(target_os = "emscripten"))] -test_op!(test_neg_defined_128, Neg::neg(0), 0, i128); - -test_op!(test_not_defined_bool, Not::not(true), false, bool); - -macro_rules! test_arith_op { - ($fn_name:ident, $op:ident::$method:ident($lhs:literal, $rhs:literal)) => { - #[test] - fn $fn_name() { - impls_defined!( - $op, - $method($lhs, $rhs), - 0, - i8, - i16, - i32, - i64, - isize, - u8, - u16, - u32, - u64, - usize, - f32, - f64 - ); - #[cfg(not(target_os = "emscripten"))] - impls_defined!($op, $method($lhs, $rhs), 0, i128, u128); - } - }; - ($fn_name:ident, $op:ident::$method:ident(&mut $lhs:literal, $rhs:literal)) => { - #[test] - fn $fn_name() { - impls_defined!( - $op, - $method(&mut $lhs, $rhs), - 0, - i8, - i16, - i32, - i64, - isize, - u8, - u16, - u32, - u64, - usize, - f32, - f64 - ); - #[cfg(not(target_os = "emscripten"))] - impls_defined!($op, $method(&mut $lhs, $rhs), 0, i128, u128); - } - }; -} - -test_arith_op!(test_add_defined, Add::add(0, 0)); -test_arith_op!(test_add_assign_defined, AddAssign::add_assign(&mut 0, 0)); -test_arith_op!(test_sub_defined, Sub::sub(0, 0)); -test_arith_op!(test_sub_assign_defined, SubAssign::sub_assign(&mut 0, 0)); -test_arith_op!(test_mul_defined, Mul::mul(0, 0)); -test_arith_op!(test_mul_assign_defined, MulAssign::mul_assign(&mut 0, 0)); -test_arith_op!(test_div_defined, Div::div(0, 1)); -test_arith_op!(test_div_assign_defined, DivAssign::div_assign(&mut 0, 1)); -test_arith_op!(test_rem_defined, Rem::rem(0, 1)); -test_arith_op!(test_rem_assign_defined, RemAssign::rem_assign(&mut 0, 1)); - -macro_rules! test_bitop { - ($test_name:ident, $op:ident::$method:ident) => { - #[test] - fn $test_name() { - impls_defined!( - $op, - $method(0, 0), - 0, - i8, - i16, - i32, - i64, - isize, - u8, - u16, - u32, - u64, - usize - ); - #[cfg(not(target_os = "emscripten"))] - impls_defined!($op, $method(0, 0), 0, i128, u128); - impls_defined!($op, $method(false, false), false, bool); - } - }; -} -macro_rules! test_bitop_assign { - ($test_name:ident, $op:ident::$method:ident) => { - #[test] - fn $test_name() { - impls_defined!( - $op, - $method(&mut 0, 0), - 0, - i8, - i16, - i32, - i64, - isize, - u8, - u16, - u32, - u64, - usize - ); - #[cfg(not(target_os = "emscripten"))] - impls_defined!($op, $method(&mut 0, 0), 0, i128, u128); - impls_defined!($op, $method(&mut false, false), false, bool); - } - }; -} - -test_bitop!(test_bitand_defined, BitAnd::bitand); -test_bitop_assign!(test_bitand_assign_defined, BitAndAssign::bitand_assign); -test_bitop!(test_bitor_defined, BitOr::bitor); -test_bitop_assign!(test_bitor_assign_defined, BitOrAssign::bitor_assign); -test_bitop!(test_bitxor_defined, BitXor::bitxor); -test_bitop_assign!(test_bitxor_assign_defined, BitXorAssign::bitxor_assign); - -macro_rules! test_shift_inner { - ($op:ident::$method:ident, $lt:ty, $($rt:ty),+) => { - $(impl_defined!($op, $method(0,0), 0, $lt, $rt);)+ - }; - ($op:ident::$method:ident, $lt:ty) => { - test_shift_inner!($op::$method, $lt, i8, i16, i32, i64, isize, u8, u16, u32, u64, usize); - #[cfg(not(target_os = "emscripten"))] - test_shift_inner!($op::$method, $lt, i128, u128); - }; -} - -macro_rules! test_shift { - ($op:ident::$method:ident, $($lt:ty),+) => { - $(test_shift_inner!($op::$method, $lt);)+ - }; - ($test_name:ident, $op:ident::$method:ident) => { - #[test] - fn $test_name() { - test_shift!($op::$method, i8, i16, i32, i64, isize, u8, u16, u32, u64, usize); - #[cfg(not(target_os = "emscripten"))] - test_shift!($op::$method, i128, u128); - } - }; -} - -macro_rules! test_shift_assign_inner { - ($op:ident::$method:ident, $lt:ty, $($rt:ty),+) => { - $(impl_defined!($op, $method(&mut 0,0), 0, $lt, $rt);)+ - }; - ($op:ident::$method:ident, $lt:ty) => { - test_shift_assign_inner!($op::$method, $lt, i8, i16, i32, i64, isize, u8, u16, u32, u64, usize); - #[cfg(not(target_os = "emscripten"))] - test_shift_assign_inner!($op::$method, $lt, i128, u128); - }; -} - -macro_rules! test_shift_assign { - ($op:ident::$method:ident, $($lt:ty),+) => { - $(test_shift_assign_inner!($op::$method, $lt);)+ - }; - ($test_name:ident, $op:ident::$method:ident) => { - #[test] - fn $test_name() { - test_shift_assign!($op::$method, i8, i16, i32, i64, isize, u8, u16, u32, u64, usize); - #[cfg(not(target_os = "emscripten"))] - test_shift_assign!($op::$method, i128, u128); - } - }; -} -test_shift!(test_shl_defined, Shl::shl); -test_shift_assign!(test_shl_assign_defined, ShlAssign::shl_assign); -test_shift!(test_shr_defined, Shr::shr); -test_shift_assign!(test_shr_assign_defined, ShrAssign::shr_assign); diff --git a/library/core/tests/num/u128.rs b/library/core/tests/num/u128.rs deleted file mode 100644 index a7b0f9effefb9..0000000000000 --- a/library/core/tests/num/u128.rs +++ /dev/null @@ -1 +0,0 @@ -uint_module!(u128); diff --git a/library/core/tests/num/u16.rs b/library/core/tests/num/u16.rs deleted file mode 100644 index 010596a34a56c..0000000000000 --- a/library/core/tests/num/u16.rs +++ /dev/null @@ -1 +0,0 @@ -uint_module!(u16); diff --git a/library/core/tests/num/u32.rs b/library/core/tests/num/u32.rs deleted file mode 100644 index 687d3bbaa907f..0000000000000 --- a/library/core/tests/num/u32.rs +++ /dev/null @@ -1 +0,0 @@ -uint_module!(u32); diff --git a/library/core/tests/num/u64.rs b/library/core/tests/num/u64.rs deleted file mode 100644 index ee55071e94996..0000000000000 --- a/library/core/tests/num/u64.rs +++ /dev/null @@ -1 +0,0 @@ -uint_module!(u64); diff --git a/library/core/tests/num/u8.rs b/library/core/tests/num/u8.rs deleted file mode 100644 index 12b038ce0f75c..0000000000000 --- a/library/core/tests/num/u8.rs +++ /dev/null @@ -1 +0,0 @@ -uint_module!(u8); diff --git a/library/core/tests/num/uint_macros.rs b/library/core/tests/num/uint_macros.rs deleted file mode 100644 index 955440647eb98..0000000000000 --- a/library/core/tests/num/uint_macros.rs +++ /dev/null @@ -1,312 +0,0 @@ -macro_rules! uint_module { - ($T:ident) => { - #[cfg(test)] - mod tests { - use core::ops::{BitAnd, BitOr, BitXor, Not, Shl, Shr}; - use core::$T::*; - use std::str::FromStr; - - use crate::num; - - #[test] - fn test_overflows() { - assert!(MAX > 0); - assert!(MIN <= 0); - assert!((MIN + MAX).wrapping_add(1) == 0); - } - - #[test] - fn test_num() { - num::test_num(10 as $T, 2 as $T); - } - - #[test] - fn test_bitwise_operators() { - assert!(0b1110 as $T == (0b1100 as $T).bitor(0b1010 as $T)); - assert!(0b1000 as $T == (0b1100 as $T).bitand(0b1010 as $T)); - assert!(0b0110 as $T == (0b1100 as $T).bitxor(0b1010 as $T)); - assert!(0b1110 as $T == (0b0111 as $T).shl(1)); - assert!(0b0111 as $T == (0b1110 as $T).shr(1)); - assert!(MAX - (0b1011 as $T) == (0b1011 as $T).not()); - } - - const A: $T = 0b0101100; - const B: $T = 0b0100001; - const C: $T = 0b1111001; - - const _0: $T = 0; - const _1: $T = !0; - - #[test] - fn test_count_ones() { - assert!(A.count_ones() == 3); - assert!(B.count_ones() == 2); - assert!(C.count_ones() == 5); - } - - #[test] - fn test_count_zeros() { - assert!(A.count_zeros() == $T::BITS - 3); - assert!(B.count_zeros() == $T::BITS - 2); - assert!(C.count_zeros() == $T::BITS - 5); - } - - #[test] - fn test_leading_trailing_ones() { - let a: $T = 0b0101_1111; - assert_eq!(a.trailing_ones(), 5); - assert_eq!((!a).leading_ones(), $T::BITS - 7); - - assert_eq!(a.reverse_bits().leading_ones(), 5); - - assert_eq!(_1.leading_ones(), $T::BITS); - assert_eq!(_1.trailing_ones(), $T::BITS); - - assert_eq!((_1 << 1).trailing_ones(), 0); - assert_eq!((_1 >> 1).leading_ones(), 0); - - assert_eq!((_1 << 1).leading_ones(), $T::BITS - 1); - assert_eq!((_1 >> 1).trailing_ones(), $T::BITS - 1); - - assert_eq!(_0.leading_ones(), 0); - assert_eq!(_0.trailing_ones(), 0); - - let x: $T = 0b0010_1100; - assert_eq!(x.leading_ones(), 0); - assert_eq!(x.trailing_ones(), 0); - } - - #[test] - fn test_rotate() { - assert_eq!(A.rotate_left(6).rotate_right(2).rotate_right(4), A); - assert_eq!(B.rotate_left(3).rotate_left(2).rotate_right(5), B); - assert_eq!(C.rotate_left(6).rotate_right(2).rotate_right(4), C); - - // Rotating these should make no difference - // - // We test using 124 bits because to ensure that overlong bit shifts do - // not cause undefined behaviour. See #10183. - assert_eq!(_0.rotate_left(124), _0); - assert_eq!(_1.rotate_left(124), _1); - assert_eq!(_0.rotate_right(124), _0); - assert_eq!(_1.rotate_right(124), _1); - - // Rotating by 0 should have no effect - assert_eq!(A.rotate_left(0), A); - assert_eq!(B.rotate_left(0), B); - assert_eq!(C.rotate_left(0), C); - // Rotating by a multiple of word size should also have no effect - assert_eq!(A.rotate_left(128), A); - assert_eq!(B.rotate_left(128), B); - assert_eq!(C.rotate_left(128), C); - } - - #[test] - fn test_swap_bytes() { - assert_eq!(A.swap_bytes().swap_bytes(), A); - assert_eq!(B.swap_bytes().swap_bytes(), B); - assert_eq!(C.swap_bytes().swap_bytes(), C); - - // Swapping these should make no difference - assert_eq!(_0.swap_bytes(), _0); - assert_eq!(_1.swap_bytes(), _1); - } - - #[test] - fn test_reverse_bits() { - assert_eq!(A.reverse_bits().reverse_bits(), A); - assert_eq!(B.reverse_bits().reverse_bits(), B); - assert_eq!(C.reverse_bits().reverse_bits(), C); - - // Swapping these should make no difference - assert_eq!(_0.reverse_bits(), _0); - assert_eq!(_1.reverse_bits(), _1); - } - - #[test] - fn test_le() { - assert_eq!($T::from_le(A.to_le()), A); - assert_eq!($T::from_le(B.to_le()), B); - assert_eq!($T::from_le(C.to_le()), C); - assert_eq!($T::from_le(_0), _0); - assert_eq!($T::from_le(_1), _1); - assert_eq!(_0.to_le(), _0); - assert_eq!(_1.to_le(), _1); - } - - #[test] - fn test_be() { - assert_eq!($T::from_be(A.to_be()), A); - assert_eq!($T::from_be(B.to_be()), B); - assert_eq!($T::from_be(C.to_be()), C); - assert_eq!($T::from_be(_0), _0); - assert_eq!($T::from_be(_1), _1); - assert_eq!(_0.to_be(), _0); - assert_eq!(_1.to_be(), _1); - } - - #[test] - fn test_unsigned_checked_div() { - assert!((10 as $T).checked_div(2) == Some(5)); - assert!((5 as $T).checked_div(0) == None); - } - - fn from_str(t: &str) -> Option { - FromStr::from_str(t).ok() - } - - #[test] - pub fn test_from_str() { - assert_eq!(from_str::<$T>("0"), Some(0 as $T)); - assert_eq!(from_str::<$T>("3"), Some(3 as $T)); - assert_eq!(from_str::<$T>("10"), Some(10 as $T)); - assert_eq!(from_str::("123456789"), Some(123456789 as u32)); - assert_eq!(from_str::<$T>("00100"), Some(100 as $T)); - - assert_eq!(from_str::<$T>(""), None); - assert_eq!(from_str::<$T>(" "), None); - assert_eq!(from_str::<$T>("x"), None); - } - - #[test] - pub fn test_parse_bytes() { - assert_eq!($T::from_str_radix("123", 10), Ok(123 as $T)); - assert_eq!($T::from_str_radix("1001", 2), Ok(9 as $T)); - assert_eq!($T::from_str_radix("123", 8), Ok(83 as $T)); - assert_eq!(u16::from_str_radix("123", 16), Ok(291 as u16)); - assert_eq!(u16::from_str_radix("ffff", 16), Ok(65535 as u16)); - assert_eq!($T::from_str_radix("z", 36), Ok(35 as $T)); - - assert_eq!($T::from_str_radix("Z", 10).ok(), None::<$T>); - assert_eq!($T::from_str_radix("_", 2).ok(), None::<$T>); - } - - #[test] - fn test_pow() { - let mut r = 2 as $T; - assert_eq!(r.pow(2), 4 as $T); - assert_eq!(r.pow(0), 1 as $T); - assert_eq!(r.wrapping_pow(2), 4 as $T); - assert_eq!(r.wrapping_pow(0), 1 as $T); - assert_eq!(r.checked_pow(2), Some(4 as $T)); - assert_eq!(r.checked_pow(0), Some(1 as $T)); - assert_eq!(r.overflowing_pow(2), (4 as $T, false)); - assert_eq!(r.overflowing_pow(0), (1 as $T, false)); - assert_eq!(r.saturating_pow(2), 4 as $T); - assert_eq!(r.saturating_pow(0), 1 as $T); - - r = MAX; - // use `^` to represent .pow() with no overflow. - // if itest::MAX == 2^j-1, then itest is a `j` bit int, - // so that `itest::MAX*itest::MAX == 2^(2*j)-2^(j+1)+1`, - // thussaturating_pow the overflowing result is exactly 1. - assert_eq!(r.wrapping_pow(2), 1 as $T); - assert_eq!(r.checked_pow(2), None); - assert_eq!(r.overflowing_pow(2), (1 as $T, true)); - assert_eq!(r.saturating_pow(2), MAX); - } - - #[test] - fn test_isqrt() { - assert_eq!((0 as $T).isqrt(), 0 as $T); - assert_eq!((1 as $T).isqrt(), 1 as $T); - assert_eq!((2 as $T).isqrt(), 1 as $T); - assert_eq!((99 as $T).isqrt(), 9 as $T); - assert_eq!((100 as $T).isqrt(), 10 as $T); - assert_eq!($T::MAX.isqrt(), (1 << ($T::BITS / 2)) - 1); - } - - #[cfg(not(miri))] // Miri is too slow - #[test] - fn test_lots_of_isqrt() { - let n_max: $T = (1024 * 1024).min($T::MAX as u128) as $T; - for n in 0..=n_max { - let isqrt: $T = n.isqrt(); - - assert!(isqrt.pow(2) <= n); - assert!(isqrt + 1 == (1 as $T) << ($T::BITS / 2) || (isqrt + 1).pow(2) > n); - } - - for n in ($T::MAX - 255)..=$T::MAX { - let isqrt: $T = n.isqrt(); - - assert!(isqrt.pow(2) <= n); - assert!(isqrt + 1 == (1 as $T) << ($T::BITS / 2) || (isqrt + 1).pow(2) > n); - } - } - - #[test] - fn test_div_floor() { - assert_eq!((8 as $T).div_floor(3), 2); - } - - #[test] - fn test_div_ceil() { - assert_eq!((8 as $T).div_ceil(3), 3); - } - - #[test] - fn test_next_multiple_of() { - assert_eq!((16 as $T).next_multiple_of(8), 16); - assert_eq!((23 as $T).next_multiple_of(8), 24); - assert_eq!(MAX.next_multiple_of(1), MAX); - } - - #[test] - fn test_checked_next_multiple_of() { - assert_eq!((16 as $T).checked_next_multiple_of(8), Some(16)); - assert_eq!((23 as $T).checked_next_multiple_of(8), Some(24)); - assert_eq!((1 as $T).checked_next_multiple_of(0), None); - assert_eq!(MAX.checked_next_multiple_of(2), None); - } - - #[test] - fn test_carrying_add() { - assert_eq!($T::MAX.carrying_add(1, false), (0, true)); - assert_eq!($T::MAX.carrying_add(0, true), (0, true)); - assert_eq!($T::MAX.carrying_add(1, true), (1, true)); - - assert_eq!($T::MIN.carrying_add($T::MAX, false), ($T::MAX, false)); - assert_eq!($T::MIN.carrying_add(0, true), (1, false)); - assert_eq!($T::MIN.carrying_add($T::MAX, true), (0, true)); - } - - #[test] - fn test_borrowing_sub() { - assert_eq!($T::MIN.borrowing_sub(1, false), ($T::MAX, true)); - assert_eq!($T::MIN.borrowing_sub(0, true), ($T::MAX, true)); - assert_eq!($T::MIN.borrowing_sub(1, true), ($T::MAX - 1, true)); - - assert_eq!($T::MAX.borrowing_sub($T::MAX, false), (0, false)); - assert_eq!($T::MAX.borrowing_sub(0, true), ($T::MAX - 1, false)); - assert_eq!($T::MAX.borrowing_sub($T::MAX, true), ($T::MAX, true)); - } - - #[test] - fn test_midpoint() { - assert_eq!(<$T>::midpoint(1, 3), 2); - assert_eq!(<$T>::midpoint(3, 1), 2); - - assert_eq!(<$T>::midpoint(0, 0), 0); - assert_eq!(<$T>::midpoint(0, 2), 1); - assert_eq!(<$T>::midpoint(2, 0), 1); - assert_eq!(<$T>::midpoint(2, 2), 2); - - assert_eq!(<$T>::midpoint(1, 4), 2); - assert_eq!(<$T>::midpoint(4, 1), 2); - assert_eq!(<$T>::midpoint(3, 4), 3); - assert_eq!(<$T>::midpoint(4, 3), 3); - - assert_eq!(<$T>::midpoint(<$T>::MIN, <$T>::MAX), (<$T>::MAX - <$T>::MIN) / 2); - assert_eq!(<$T>::midpoint(<$T>::MAX, <$T>::MIN), (<$T>::MAX - <$T>::MIN) / 2); - assert_eq!(<$T>::midpoint(<$T>::MIN, <$T>::MIN), <$T>::MIN); - assert_eq!(<$T>::midpoint(<$T>::MAX, <$T>::MAX), <$T>::MAX); - - assert_eq!(<$T>::midpoint(<$T>::MIN, 6), <$T>::MIN / 2 + 3); - assert_eq!(<$T>::midpoint(6, <$T>::MIN), <$T>::MIN / 2 + 3); - assert_eq!(<$T>::midpoint(<$T>::MAX, 6), (<$T>::MAX - <$T>::MIN) / 2 + 3); - assert_eq!(<$T>::midpoint(6, <$T>::MAX), (<$T>::MAX - <$T>::MIN) / 2 + 3); - } - } - }; -} diff --git a/library/core/tests/num/wrapping.rs b/library/core/tests/num/wrapping.rs deleted file mode 100644 index c5a7198839517..0000000000000 --- a/library/core/tests/num/wrapping.rs +++ /dev/null @@ -1,318 +0,0 @@ -use core::num::Wrapping; - -macro_rules! wrapping_operation { - ($result:expr, $lhs:ident $op:tt $rhs:expr) => { - assert_eq!($result, $lhs $op $rhs); - assert_eq!($result, &$lhs $op $rhs); - assert_eq!($result, $lhs $op &$rhs); - assert_eq!($result, &$lhs $op &$rhs); - }; - ($result:expr, $op:tt $expr:expr) => { - assert_eq!($result, $op $expr); - assert_eq!($result, $op &$expr); - }; -} - -macro_rules! wrapping_assignment { - ($result:expr, $lhs:ident $op:tt $rhs:expr) => { - let mut lhs1 = $lhs; - lhs1 $op $rhs; - assert_eq!($result, lhs1); - - let mut lhs2 = $lhs; - lhs2 $op &$rhs; - assert_eq!($result, lhs2); - }; -} - -macro_rules! wrapping_test { - ($fn_name:ident, $type:ty, $min:expr, $max:expr) => { - #[test] - fn $fn_name() { - let zero: Wrapping<$type> = Wrapping(0); - let one: Wrapping<$type> = Wrapping(1); - let min: Wrapping<$type> = Wrapping($min); - let max: Wrapping<$type> = Wrapping($max); - - wrapping_operation!(min, max + one); - wrapping_assignment!(min, max += one); - wrapping_operation!(max, min - one); - wrapping_assignment!(max, min -= one); - wrapping_operation!(max, max * one); - wrapping_assignment!(max, max *= one); - wrapping_operation!(max, max / one); - wrapping_assignment!(max, max /= one); - wrapping_operation!(zero, max % one); - wrapping_assignment!(zero, max %= one); - wrapping_operation!(zero, zero & max); - wrapping_assignment!(zero, zero &= max); - wrapping_operation!(max, zero | max); - wrapping_assignment!(max, zero |= max); - wrapping_operation!(zero, max ^ max); - wrapping_assignment!(zero, max ^= max); - wrapping_operation!(zero, zero << 1usize); - wrapping_assignment!(zero, zero <<= 1usize); - wrapping_operation!(zero, zero >> 1usize); - wrapping_assignment!(zero, zero >>= 1usize); - wrapping_operation!(zero, -zero); - wrapping_operation!(max, !min); - } - }; -} - -wrapping_test!(test_wrapping_i8, i8, i8::MIN, i8::MAX); -wrapping_test!(test_wrapping_i16, i16, i16::MIN, i16::MAX); -wrapping_test!(test_wrapping_i32, i32, i32::MIN, i32::MAX); -wrapping_test!(test_wrapping_i64, i64, i64::MIN, i64::MAX); -#[cfg(not(target_os = "emscripten"))] -wrapping_test!(test_wrapping_i128, i128, i128::MIN, i128::MAX); -wrapping_test!(test_wrapping_isize, isize, isize::MIN, isize::MAX); -wrapping_test!(test_wrapping_u8, u8, u8::MIN, u8::MAX); -wrapping_test!(test_wrapping_u16, u16, u16::MIN, u16::MAX); -wrapping_test!(test_wrapping_u32, u32, u32::MIN, u32::MAX); -wrapping_test!(test_wrapping_u64, u64, u64::MIN, u64::MAX); -#[cfg(not(target_os = "emscripten"))] -wrapping_test!(test_wrapping_u128, u128, u128::MIN, u128::MAX); -wrapping_test!(test_wrapping_usize, usize, usize::MIN, usize::MAX); - -#[test] -fn wrapping_int_api() { - assert_eq!(i8::MAX.wrapping_add(1), i8::MIN); - assert_eq!(i16::MAX.wrapping_add(1), i16::MIN); - assert_eq!(i32::MAX.wrapping_add(1), i32::MIN); - assert_eq!(i64::MAX.wrapping_add(1), i64::MIN); - assert_eq!(isize::MAX.wrapping_add(1), isize::MIN); - - assert_eq!(i8::MIN.wrapping_sub(1), i8::MAX); - assert_eq!(i16::MIN.wrapping_sub(1), i16::MAX); - assert_eq!(i32::MIN.wrapping_sub(1), i32::MAX); - assert_eq!(i64::MIN.wrapping_sub(1), i64::MAX); - assert_eq!(isize::MIN.wrapping_sub(1), isize::MAX); - - assert_eq!(u8::MAX.wrapping_add(1), u8::MIN); - assert_eq!(u16::MAX.wrapping_add(1), u16::MIN); - assert_eq!(u32::MAX.wrapping_add(1), u32::MIN); - assert_eq!(u64::MAX.wrapping_add(1), u64::MIN); - assert_eq!(usize::MAX.wrapping_add(1), usize::MIN); - - assert_eq!(u8::MIN.wrapping_sub(1), u8::MAX); - assert_eq!(u16::MIN.wrapping_sub(1), u16::MAX); - assert_eq!(u32::MIN.wrapping_sub(1), u32::MAX); - assert_eq!(u64::MIN.wrapping_sub(1), u64::MAX); - assert_eq!(usize::MIN.wrapping_sub(1), usize::MAX); - - assert_eq!((0xfe_u8 as i8).wrapping_mul(16), (0xe0_u8 as i8)); - assert_eq!((0xfedc_u16 as i16).wrapping_mul(16), (0xedc0_u16 as i16)); - assert_eq!((0xfedc_ba98_u32 as i32).wrapping_mul(16), (0xedcb_a980_u32 as i32)); - assert_eq!( - (0xfedc_ba98_7654_3217_u64 as i64).wrapping_mul(16), - (0xedcb_a987_6543_2170_u64 as i64) - ); - - match () { - #[cfg(target_pointer_width = "32")] - () => { - assert_eq!((0xfedc_ba98_u32 as isize).wrapping_mul(16), (0xedcb_a980_u32 as isize)); - } - #[cfg(target_pointer_width = "64")] - () => { - assert_eq!( - (0xfedc_ba98_7654_3217_u64 as isize).wrapping_mul(16), - (0xedcb_a987_6543_2170_u64 as isize) - ); - } - } - - assert_eq!((0xfe as u8).wrapping_mul(16), (0xe0 as u8)); - assert_eq!((0xfedc as u16).wrapping_mul(16), (0xedc0 as u16)); - assert_eq!((0xfedc_ba98 as u32).wrapping_mul(16), (0xedcb_a980 as u32)); - assert_eq!((0xfedc_ba98_7654_3217 as u64).wrapping_mul(16), (0xedcb_a987_6543_2170 as u64)); - - match () { - #[cfg(target_pointer_width = "32")] - () => { - assert_eq!((0xfedc_ba98 as usize).wrapping_mul(16), (0xedcb_a980 as usize)); - } - #[cfg(target_pointer_width = "64")] - () => { - assert_eq!( - (0xfedc_ba98_7654_3217 as usize).wrapping_mul(16), - (0xedcb_a987_6543_2170 as usize) - ); - } - } - - macro_rules! check_mul_no_wrap { - ($e:expr, $f:expr) => { - assert_eq!(($e).wrapping_mul($f), ($e) * $f); - }; - } - macro_rules! check_mul_wraps { - ($e:expr, $f:expr) => { - assert_eq!(($e).wrapping_mul($f), $e); - }; - } - - check_mul_no_wrap!(0xfe_u8 as i8, -1); - check_mul_no_wrap!(0xfedc_u16 as i16, -1); - check_mul_no_wrap!(0xfedc_ba98_u32 as i32, -1); - check_mul_no_wrap!(0xfedc_ba98_7654_3217_u64 as i64, -1); - check_mul_no_wrap!(0xfedc_ba98_7654_3217_u64 as u64 as isize, -1); - - check_mul_no_wrap!(0xfe_u8 as i8, -2); - check_mul_no_wrap!(0xfedc_u16 as i16, -2); - check_mul_no_wrap!(0xfedc_ba98_u32 as i32, -2); - check_mul_no_wrap!(0xfedc_ba98_7654_3217_u64 as i64, -2); - check_mul_no_wrap!(0xfedc_ba98_fedc_ba98_u64 as u64 as isize, -2); - - check_mul_no_wrap!(0xfe_u8 as i8, 2); - check_mul_no_wrap!(0xfedc_u16 as i16, 2); - check_mul_no_wrap!(0xfedc_ba98_u32 as i32, 2); - check_mul_no_wrap!(0xfedc_ba98_7654_3217_u64 as i64, 2); - check_mul_no_wrap!(0xfedc_ba98_fedc_ba98_u64 as u64 as isize, 2); - - check_mul_wraps!(0x80_u8 as i8, -1); - check_mul_wraps!(0x8000_u16 as i16, -1); - check_mul_wraps!(0x8000_0000_u32 as i32, -1); - check_mul_wraps!(0x8000_0000_0000_0000_u64 as i64, -1); - match () { - #[cfg(target_pointer_width = "32")] - () => { - check_mul_wraps!(0x8000_0000_u32 as isize, -1); - } - #[cfg(target_pointer_width = "64")] - () => { - check_mul_wraps!(0x8000_0000_0000_0000_u64 as isize, -1); - } - } - - macro_rules! check_div_no_wrap { - ($e:expr, $f:expr) => { - assert_eq!(($e).wrapping_div($f), ($e) / $f); - }; - } - macro_rules! check_div_wraps { - ($e:expr, $f:expr) => { - assert_eq!(($e).wrapping_div($f), $e); - }; - } - - check_div_no_wrap!(0xfe_u8 as i8, -1); - check_div_no_wrap!(0xfedc_u16 as i16, -1); - check_div_no_wrap!(0xfedc_ba98_u32 as i32, -1); - check_div_no_wrap!(0xfedc_ba98_7654_3217_u64 as i64, -1); - check_div_no_wrap!(0xfedc_ba98_7654_3217_u64 as u64 as isize, -1); - - check_div_no_wrap!(0xfe_u8 as i8, -2); - check_div_no_wrap!(0xfedc_u16 as i16, -2); - check_div_no_wrap!(0xfedc_ba98_u32 as i32, -2); - check_div_no_wrap!(0xfedc_ba98_7654_3217_u64 as i64, -2); - check_div_no_wrap!(0xfedc_ba98_7654_3217_u64 as u64 as isize, -2); - - check_div_no_wrap!(0xfe_u8 as i8, 2); - check_div_no_wrap!(0xfedc_u16 as i16, 2); - check_div_no_wrap!(0xfedc_ba98_u32 as i32, 2); - check_div_no_wrap!(0xfedc_ba98_7654_3217_u64 as i64, 2); - check_div_no_wrap!(0xfedc_ba98_7654_3217_u64 as u64 as isize, 2); - - check_div_wraps!(-128 as i8, -1); - check_div_wraps!(0x8000_u16 as i16, -1); - check_div_wraps!(0x8000_0000_u32 as i32, -1); - check_div_wraps!(0x8000_0000_0000_0000_u64 as i64, -1); - match () { - #[cfg(target_pointer_width = "32")] - () => { - check_div_wraps!(0x8000_0000_u32 as isize, -1); - } - #[cfg(target_pointer_width = "64")] - () => { - check_div_wraps!(0x8000_0000_0000_0000_u64 as isize, -1); - } - } - - macro_rules! check_rem_no_wrap { - ($e:expr, $f:expr) => { - assert_eq!(($e).wrapping_rem($f), ($e) % $f); - }; - } - macro_rules! check_rem_wraps { - ($e:expr, $f:expr) => { - assert_eq!(($e).wrapping_rem($f), 0); - }; - } - - check_rem_no_wrap!(0xfe_u8 as i8, -1); - check_rem_no_wrap!(0xfedc_u16 as i16, -1); - check_rem_no_wrap!(0xfedc_ba98_u32 as i32, -1); - check_rem_no_wrap!(0xfedc_ba98_7654_3217_u64 as i64, -1); - check_rem_no_wrap!(0xfedc_ba98_7654_3217_u64 as u64 as isize, -1); - - check_rem_no_wrap!(0xfe_u8 as i8, -2); - check_rem_no_wrap!(0xfedc_u16 as i16, -2); - check_rem_no_wrap!(0xfedc_ba98_u32 as i32, -2); - check_rem_no_wrap!(0xfedc_ba98_7654_3217_u64 as i64, -2); - check_rem_no_wrap!(0xfedc_ba98_7654_3217_u64 as u64 as isize, -2); - - check_rem_no_wrap!(0xfe_u8 as i8, 2); - check_rem_no_wrap!(0xfedc_u16 as i16, 2); - check_rem_no_wrap!(0xfedc_ba98_u32 as i32, 2); - check_rem_no_wrap!(0xfedc_ba98_7654_3217_u64 as i64, 2); - check_rem_no_wrap!(0xfedc_ba98_7654_3217_u64 as u64 as isize, 2); - - check_rem_wraps!(0x80_u8 as i8, -1); - check_rem_wraps!(0x8000_u16 as i16, -1); - check_rem_wraps!(0x8000_0000_u32 as i32, -1); - check_rem_wraps!(0x8000_0000_0000_0000_u64 as i64, -1); - match () { - #[cfg(target_pointer_width = "32")] - () => { - check_rem_wraps!(0x8000_0000_u32 as isize, -1); - } - #[cfg(target_pointer_width = "64")] - () => { - check_rem_wraps!(0x8000_0000_0000_0000_u64 as isize, -1); - } - } - - macro_rules! check_neg_no_wrap { - ($e:expr) => { - assert_eq!(($e).wrapping_neg(), -($e)); - }; - } - macro_rules! check_neg_wraps { - ($e:expr) => { - assert_eq!(($e).wrapping_neg(), ($e)); - }; - } - - check_neg_no_wrap!(0xfe_u8 as i8); - check_neg_no_wrap!(0xfedc_u16 as i16); - check_neg_no_wrap!(0xfedc_ba98_u32 as i32); - check_neg_no_wrap!(0xfedc_ba98_7654_3217_u64 as i64); - check_neg_no_wrap!(0xfedc_ba98_7654_3217_u64 as u64 as isize); - - check_neg_wraps!(0x80_u8 as i8); - check_neg_wraps!(0x8000_u16 as i16); - check_neg_wraps!(0x8000_0000_u32 as i32); - check_neg_wraps!(0x8000_0000_0000_0000_u64 as i64); - match () { - #[cfg(target_pointer_width = "32")] - () => { - check_neg_wraps!(0x8000_0000_u32 as isize); - } - #[cfg(target_pointer_width = "64")] - () => { - check_neg_wraps!(0x8000_0000_0000_0000_u64 as isize); - } - } -} - -#[test] -fn wrapping_const() { - // Specifically the wrapping behavior of division and remainder is subtle, - // see https://github.com/rust-lang/rust/pull/94512. - const _: () = { - assert!(i32::MIN.wrapping_div(-1) == i32::MIN); - assert!(i32::MIN.wrapping_rem(-1) == 0); - }; -} diff --git a/library/core/tests/ops.rs b/library/core/tests/ops.rs deleted file mode 100644 index 0c81cba35b3df..0000000000000 --- a/library/core/tests/ops.rs +++ /dev/null @@ -1,240 +0,0 @@ -mod control_flow; - -use core::ops::{Bound, Range, RangeFrom, RangeFull, RangeInclusive, RangeTo, RangeToInclusive}; -use core::ops::{Deref, DerefMut}; - -// Test the Range structs and syntax. - -#[test] -fn test_range() { - let r = Range { start: 2, end: 10 }; - let mut count = 0; - for (i, ri) in r.enumerate() { - assert_eq!(ri, i + 2); - assert!(ri >= 2 && ri < 10); - count += 1; - } - assert_eq!(count, 8); -} - -#[test] -fn test_range_from() { - let r = RangeFrom { start: 2 }; - let mut count = 0; - for (i, ri) in r.take(10).enumerate() { - assert_eq!(ri, i + 2); - assert!(ri >= 2 && ri < 12); - count += 1; - } - assert_eq!(count, 10); -} - -#[test] -fn test_range_to() { - // Not much to test. - let _ = RangeTo { end: 42 }; -} - -#[test] -fn test_full_range() { - // Not much to test. - let _ = RangeFull; -} - -#[test] -fn test_range_inclusive() { - let mut r = RangeInclusive::new(1i8, 2); - assert_eq!(r.next(), Some(1)); - assert_eq!(r.next(), Some(2)); - assert_eq!(r.next(), None); - - r = RangeInclusive::new(127i8, 127); - assert_eq!(r.next(), Some(127)); - assert_eq!(r.next(), None); - - r = RangeInclusive::new(-128i8, -128); - assert_eq!(r.next_back(), Some(-128)); - assert_eq!(r.next_back(), None); - - // degenerate - r = RangeInclusive::new(1, -1); - assert_eq!(r.size_hint(), (0, Some(0))); - assert_eq!(r.next(), None); -} - -#[test] -fn test_range_to_inclusive() { - // Not much to test. - let _ = RangeToInclusive { end: 42 }; -} - -#[test] -fn test_range_is_empty() { - assert!(!(0.0..10.0).is_empty()); - assert!((-0.0..0.0).is_empty()); - assert!((10.0..0.0).is_empty()); - - assert!(!(f32::NEG_INFINITY..f32::INFINITY).is_empty()); - assert!((f32::EPSILON..f32::NAN).is_empty()); - assert!((f32::NAN..f32::EPSILON).is_empty()); - assert!((f32::NAN..f32::NAN).is_empty()); - - assert!(!(0.0..=10.0).is_empty()); - assert!(!(-0.0..=0.0).is_empty()); - assert!((10.0..=0.0).is_empty()); - - assert!(!(f32::NEG_INFINITY..=f32::INFINITY).is_empty()); - assert!((f32::EPSILON..=f32::NAN).is_empty()); - assert!((f32::NAN..=f32::EPSILON).is_empty()); - assert!((f32::NAN..=f32::NAN).is_empty()); -} - -#[test] -fn test_bound_cloned_unbounded() { - assert_eq!(Bound::<&u32>::Unbounded.cloned(), Bound::Unbounded); -} - -#[test] -fn test_bound_cloned_included() { - assert_eq!(Bound::Included(&3).cloned(), Bound::Included(3)); -} - -#[test] -fn test_bound_cloned_excluded() { - assert_eq!(Bound::Excluded(&3).cloned(), Bound::Excluded(3)); -} - -#[test] -#[allow(unused_comparisons)] -#[allow(unused_mut)] -fn test_range_syntax() { - let mut count = 0; - for i in 0_usize..10 { - assert!(i >= 0 && i < 10); - count += i; - } - assert_eq!(count, 45); - - let mut count = 0; - let mut range = 0_usize..10; - for i in range { - assert!(i >= 0 && i < 10); - count += i; - } - assert_eq!(count, 45); - - let mut count = 0; - let mut rf = 3_usize..; - for i in rf.take(10) { - assert!(i >= 3 && i < 13); - count += i; - } - assert_eq!(count, 75); - - let _ = 0_usize..4 + 4 - 3; - - fn foo() -> isize { - 42 - } - let _ = 0..foo(); - - let _ = { &42..&100 }; // references to literals are OK - let _ = ..42_usize; - - // Test we can use two different types with a common supertype. - let x = &42; - { - let y = 42; - let _ = x..&y; - } -} - -#[test] -#[allow(dead_code)] -fn test_range_syntax_in_return_statement() { - fn return_range_to() -> RangeTo { - return ..1; - } - fn return_full_range() -> RangeFull { - return ..; - } - // Not much to test. -} - -#[test] -fn range_structural_match() { - // test that all range types can be structurally matched upon - - const RANGE: Range = 0..1000; - match RANGE { - RANGE => {} - _ => unreachable!(), - } - - const RANGE_FROM: RangeFrom = 0..; - match RANGE_FROM { - RANGE_FROM => {} - _ => unreachable!(), - } - - const RANGE_FULL: RangeFull = ..; - match RANGE_FULL { - RANGE_FULL => {} - } - - const RANGE_INCLUSIVE: RangeInclusive = 0..=999; - match RANGE_INCLUSIVE { - RANGE_INCLUSIVE => {} - _ => unreachable!(), - } - - const RANGE_TO: RangeTo = ..1000; - match RANGE_TO { - RANGE_TO => {} - _ => unreachable!(), - } - - const RANGE_TO_INCLUSIVE: RangeToInclusive = ..=999; - match RANGE_TO_INCLUSIVE { - RANGE_TO_INCLUSIVE => {} - _ => unreachable!(), - } -} - -// Test Deref implementations - -#[test] -fn deref_mut_on_ref() { - // Test that `&mut T` implements `DerefMut` - - fn inc + DerefMut>(mut t: T) { - *t += 1; - } - - let mut x: isize = 5; - inc(&mut x); - assert_eq!(x, 6); -} - -#[test] -fn deref_on_ref() { - // Test that `&T` and `&mut T` implement `Deref` - - fn deref>(t: T) -> U { - *t - } - - let x: isize = 3; - let y = deref(&x); - assert_eq!(y, 3); - - let mut x: isize = 4; - let y = deref(&mut x); - assert_eq!(y, 4); -} - -#[test] -#[allow(unreachable_code)] -fn test_not_never() { - if !return () {} -} diff --git a/library/core/tests/ops/control_flow.rs b/library/core/tests/ops/control_flow.rs deleted file mode 100644 index eacfd63a6c48f..0000000000000 --- a/library/core/tests/ops/control_flow.rs +++ /dev/null @@ -1,18 +0,0 @@ -use core::intrinsics::discriminant_value; -use core::ops::ControlFlow; - -#[test] -fn control_flow_discriminants_match_result() { - // This isn't stable surface area, but helps keep `?` cheap between them, - // even if LLVM can't always take advantage of it right now. - // (Sadly Result and Option are inconsistent, so ControlFlow can't match both.) - - assert_eq!( - discriminant_value(&ControlFlow::::Break(3)), - discriminant_value(&Result::::Err(3)), - ); - assert_eq!( - discriminant_value(&ControlFlow::::Continue(3)), - discriminant_value(&Result::::Ok(3)), - ); -} diff --git a/library/core/tests/option.rs b/library/core/tests/option.rs deleted file mode 100644 index b1b9492f182e0..0000000000000 --- a/library/core/tests/option.rs +++ /dev/null @@ -1,577 +0,0 @@ -use core::cell::Cell; -use core::mem; -use core::ops::DerefMut; -use core::option::*; - -#[test] -fn test_get_ptr() { - unsafe { - let x: Box<_> = Box::new(0); - let addr_x: *const isize = mem::transmute(&*x); - let opt = Some(x); - let y = opt.unwrap(); - let addr_y: *const isize = mem::transmute(&*y); - assert_eq!(addr_x, addr_y); - } -} - -#[test] -fn test_get_str() { - let x = "test".to_string(); - let addr_x = x.as_ptr(); - let opt = Some(x); - let y = opt.unwrap(); - let addr_y = y.as_ptr(); - assert_eq!(addr_x, addr_y); -} - -#[test] -fn test_get_resource() { - use core::cell::RefCell; - use std::rc::Rc; - - struct R { - i: Rc>, - } - - impl Drop for R { - fn drop(&mut self) { - let ii = &*self.i; - let i = *ii.borrow(); - *ii.borrow_mut() = i + 1; - } - } - - fn r(i: Rc>) -> R { - R { i } - } - - let i = Rc::new(RefCell::new(0)); - { - let x = r(i.clone()); - let opt = Some(x); - let _y = opt.unwrap(); - } - assert_eq!(*i.borrow(), 1); -} - -#[test] -#[allow(for_loops_over_fallibles)] -fn test_option_dance() { - let x = Some(()); - let mut y = Some(5); - let mut y2 = 0; - for _x in x { - y2 = y.take().unwrap(); - } - assert_eq!(y2, 5); - assert!(y.is_none()); -} - -#[test] -#[should_panic] -fn test_option_too_much_dance() { - struct A; - let mut y = Some(A); - let _y2 = y.take().unwrap(); - let _y3 = y.take().unwrap(); -} - -#[test] -fn test_and() { - let x: Option = Some(1); - assert_eq!(x.and(Some(2)), Some(2)); - assert_eq!(x.and(None::), None); - - let x: Option = None; - assert_eq!(x.and(Some(2)), None); - assert_eq!(x.and(None::), None); - - /* FIXME(#110395) - const FOO: Option = Some(1); - const A: Option = FOO.and(Some(2)); - const B: Option = FOO.and(None); - assert_eq!(A, Some(2)); - assert_eq!(B, None); - - const BAR: Option = None; - const C: Option = BAR.and(Some(2)); - const D: Option = BAR.and(None); - assert_eq!(C, None); - assert_eq!(D, None); - */ -} - -#[test] -fn test_and_then() { - const fn plus_one(x: isize) -> Option { - Some(x + 1) - } - - const fn none(_: isize) -> Option { - None - } - - let x: Option = Some(1); - assert_eq!(x.and_then(plus_one), Some(2)); - assert_eq!(x.and_then(none), None); - - let x: Option = None; - assert_eq!(x.and_then(plus_one), None); - assert_eq!(x.and_then(none), None); - - /* FIXME(#110395) - const FOO: Option = Some(1); - const A: Option = FOO.and_then(plus_one); - const B: Option = FOO.and_then(none); - assert_eq!(A, Some(2)); - assert_eq!(B, None); - - const BAR: Option = None; - const C: Option = BAR.and_then(plus_one); - const D: Option = BAR.and_then(none); - assert_eq!(C, None); - assert_eq!(D, None); - */ -} - -#[test] -fn test_or() { - let x: Option = Some(1); - assert_eq!(x.or(Some(2)), Some(1)); - assert_eq!(x.or(None), Some(1)); - - let x: Option = None; - assert_eq!(x.or(Some(2)), Some(2)); - assert_eq!(x.or(None), None); - - /* FIXME(#110395) - const FOO: Option = Some(1); - const A: Option = FOO.or(Some(2)); - const B: Option = FOO.or(None); - assert_eq!(A, Some(1)); - assert_eq!(B, Some(1)); - - const BAR: Option = None; - const C: Option = BAR.or(Some(2)); - const D: Option = BAR.or(None); - assert_eq!(C, Some(2)); - assert_eq!(D, None); - */ -} - -#[test] -fn test_or_else() { - const fn two() -> Option { - Some(2) - } - - const fn none() -> Option { - None - } - - let x: Option = Some(1); - assert_eq!(x.or_else(two), Some(1)); - assert_eq!(x.or_else(none), Some(1)); - - let x: Option = None; - assert_eq!(x.or_else(two), Some(2)); - assert_eq!(x.or_else(none), None); - - /* FIXME(#110395) - const FOO: Option = Some(1); - const A: Option = FOO.or_else(two); - const B: Option = FOO.or_else(none); - assert_eq!(A, Some(1)); - assert_eq!(B, Some(1)); - - const BAR: Option = None; - const C: Option = BAR.or_else(two); - const D: Option = BAR.or_else(none); - assert_eq!(C, Some(2)); - assert_eq!(D, None); - */ -} - -#[test] -fn test_unwrap() { - assert_eq!(Some(1).unwrap(), 1); - let s = Some("hello".to_string()).unwrap(); - assert_eq!(s, "hello"); -} - -#[test] -#[should_panic] -fn test_unwrap_panic1() { - let x: Option = None; - x.unwrap(); -} - -#[test] -#[should_panic] -fn test_unwrap_panic2() { - let x: Option = None; - x.unwrap(); -} - -#[test] -fn test_unwrap_or() { - let x: Option = Some(1); - assert_eq!(x.unwrap_or(2), 1); - - let x: Option = None; - assert_eq!(x.unwrap_or(2), 2); - - /* FIXME(#110395) - const A: isize = Some(1).unwrap_or(2); - const B: isize = None.unwrap_or(2); - assert_eq!(A, 1); - assert_eq!(B, 2); - */ -} - -#[test] -fn test_unwrap_or_else() { - const fn two() -> isize { - 2 - } - - let x: Option = Some(1); - assert_eq!(x.unwrap_or_else(two), 1); - - let x: Option = None; - assert_eq!(x.unwrap_or_else(two), 2); - - /* FIXME(#110395) - const A: isize = Some(1).unwrap_or_else(two); - const B: isize = None.unwrap_or_else(two); - assert_eq!(A, 1); - assert_eq!(B, 2); - */ -} - -#[test] -fn test_unwrap_unchecked() { - assert_eq!(unsafe { Some(1).unwrap_unchecked() }, 1); - let s = unsafe { Some("hello".to_string()).unwrap_unchecked() }; - assert_eq!(s, "hello"); -} - -#[test] -fn test_iter() { - let val = 5; - - let x = Some(val); - let mut it = x.iter(); - - assert_eq!(it.size_hint(), (1, Some(1))); - assert_eq!(it.next(), Some(&val)); - assert_eq!(it.size_hint(), (0, Some(0))); - assert!(it.next().is_none()); - - let mut it = (&x).into_iter(); - assert_eq!(it.next(), Some(&val)); -} - -#[test] -fn test_mut_iter() { - let mut val = 5; - let new_val = 11; - - let mut x = Some(val); - { - let mut it = x.iter_mut(); - - assert_eq!(it.size_hint(), (1, Some(1))); - - match it.next() { - Some(interior) => { - assert_eq!(*interior, val); - *interior = new_val; - } - None => assert!(false), - } - - assert_eq!(it.size_hint(), (0, Some(0))); - assert!(it.next().is_none()); - } - assert_eq!(x, Some(new_val)); - - let mut y = Some(val); - let mut it = (&mut y).into_iter(); - assert_eq!(it.next(), Some(&mut val)); -} - -#[test] -fn test_ord() { - let small = Some(1.0f64); - let big = Some(5.0f64); - let nan = Some(0.0f64 / 0.0); - assert!(!(nan < big)); - assert!(!(nan > big)); - assert!(small < big); - assert!(None < big); - assert!(big > None); -} - -#[test] -fn test_collect() { - let v: Option> = (0..0).map(|_| Some(0)).collect(); - assert!(v == Some(vec![])); - - let v: Option> = (0..3).map(|x| Some(x)).collect(); - assert!(v == Some(vec![0, 1, 2])); - - let v: Option> = (0..3).map(|x| if x > 1 { None } else { Some(x) }).collect(); - assert!(v == None); - - // test that it does not take more elements than it needs - let mut functions: [Box Option<()>>; 3] = - [Box::new(|| Some(())), Box::new(|| None), Box::new(|| panic!())]; - - let v: Option> = functions.iter_mut().map(|f| (*f)()).collect(); - - assert!(v == None); -} - -#[test] -fn test_copied() { - let val = 1; - let val_ref = &val; - let opt_none: Option<&'static u32> = None; - let opt_ref = Some(&val); - let opt_ref_ref = Some(&val_ref); - - // None works - assert_eq!(opt_none.clone(), None); - assert_eq!(opt_none.copied(), None); - - // Immutable ref works - assert_eq!(opt_ref.clone(), Some(&val)); - assert_eq!(opt_ref.copied(), Some(1)); - - // Double Immutable ref works - assert_eq!(opt_ref_ref.clone(), Some(&val_ref)); - assert_eq!(opt_ref_ref.clone().copied(), Some(&val)); - assert_eq!(opt_ref_ref.copied().copied(), Some(1)); -} - -#[test] -fn test_cloned() { - let val = 1; - let val_ref = &val; - let opt_none: Option<&'static u32> = None; - let opt_ref = Some(&val); - let opt_ref_ref = Some(&val_ref); - - // None works - assert_eq!(opt_none.clone(), None); - assert_eq!(opt_none.cloned(), None); - - // Immutable ref works - assert_eq!(opt_ref.clone(), Some(&val)); - assert_eq!(opt_ref.cloned(), Some(1)); - - // Double Immutable ref works - assert_eq!(opt_ref_ref.clone(), Some(&val_ref)); - assert_eq!(opt_ref_ref.clone().cloned(), Some(&val)); - assert_eq!(opt_ref_ref.cloned().cloned(), Some(1)); -} - -#[test] -fn test_try() { - fn try_option_some() -> Option { - let val = Some(1)?; - Some(val) - } - assert_eq!(try_option_some(), Some(1)); - - fn try_option_none() -> Option { - let val = None?; - Some(val) - } - assert_eq!(try_option_none(), None); -} - -#[test] -fn test_option_as_deref() { - // Some: &Option::Some(T) -> Option<&T::Deref::Target>::Some(&*T) - let ref_option = &Some(&42); - assert_eq!(ref_option.as_deref(), Some(&42)); - - let ref_option = &Some(String::from("a result")); - assert_eq!(ref_option.as_deref(), Some("a result")); - - let ref_option = &Some(vec![1, 2, 3, 4, 5]); - assert_eq!(ref_option.as_deref(), Some([1, 2, 3, 4, 5].as_slice())); - - // None: &Option>::None -> None - let ref_option: &Option<&i32> = &None; - assert_eq!(ref_option.as_deref(), None); -} - -#[test] -fn test_option_as_deref_mut() { - // Some: &mut Option::Some(T) -> Option<&mut T::Deref::Target>::Some(&mut *T) - let mut val = 42; - let ref_option = &mut Some(&mut val); - assert_eq!(ref_option.as_deref_mut(), Some(&mut 42)); - - let ref_option = &mut Some(String::from("a result")); - assert_eq!(ref_option.as_deref_mut(), Some(String::from("a result").deref_mut())); - - let ref_option = &mut Some(vec![1, 2, 3, 4, 5]); - assert_eq!(ref_option.as_deref_mut(), Some([1, 2, 3, 4, 5].as_mut_slice())); - - // None: &mut Option>::None -> None - let ref_option: &mut Option<&mut i32> = &mut None; - assert_eq!(ref_option.as_deref_mut(), None); -} - -#[test] -fn test_replace() { - let mut x = Some(2); - let old = x.replace(5); - - assert_eq!(x, Some(5)); - assert_eq!(old, Some(2)); - - let mut x = None; - let old = x.replace(3); - - assert_eq!(x, Some(3)); - assert_eq!(old, None); -} - -#[test] -fn option_const() { - // test that the methods of `Option` are usable in a const context - - const OPTION: Option = Some(32); - assert_eq!(OPTION, Some(32)); - - // FIXME(#110395) - // const OPTION_FROM: Option = Option::from(32); - // assert_eq!(OPTION_FROM, Some(32)); - - const REF: Option<&usize> = OPTION.as_ref(); - assert_eq!(REF, Some(&32)); - - // const REF_FROM: Option<&usize> = Option::from(&OPTION); - // assert_eq!(REF_FROM, Some(&32)); - - const IS_SOME: bool = OPTION.is_some(); - assert!(IS_SOME); - - const IS_NONE: bool = OPTION.is_none(); - assert!(!IS_NONE); - - const COPIED: Option = OPTION.as_ref().copied(); - assert_eq!(COPIED, OPTION); -} - -#[test] -const fn option_const_mut() { - // test that the methods of `Option` that take mutable references are usable in a const context - - let mut option: Option = Some(32); - - let _take = option.take(); - let _replace = option.replace(42); - - { - let as_mut = option.as_mut(); - match as_mut { - Some(v) => *v = 32, - None => unreachable!(), - } - } - /* FIXME(const-hack) - { - let as_mut: Option<&mut usize> = Option::from(&mut option); - match as_mut { - Some(v) => *v = 42, - None => unreachable!(), - } - } - */ -} - -#[test] -fn test_unwrap_drop() { - struct Dtor<'a> { - x: &'a Cell, - } - - impl<'a> std::ops::Drop for Dtor<'a> { - fn drop(&mut self) { - self.x.set(self.x.get() - 1); - } - } - - fn unwrap(o: Option) -> T { - match o { - Some(v) => v, - None => panic!(), - } - } - - let x = &Cell::new(1); - - { - let b = Some(Dtor { x }); - let _c = unwrap(b); - } - - assert_eq!(x.get(), 0); -} - -#[test] -fn option_ext() { - let thing = "{{ f }}"; - let f = thing.find("{{"); - - if f.is_none() { - println!("None!"); - } -} - -#[test] -fn zip_options() { - let x = Some(10); - let y = Some("foo"); - let z: Option = None; - - assert_eq!(x.zip(y), Some((10, "foo"))); - assert_eq!(x.zip(z), None); - assert_eq!(z.zip(x), None); -} - -#[test] -fn unzip_options() { - let x = Some((10, "foo")); - let y = None::<(bool, i32)>; - - assert_eq!(x.unzip(), (Some(10), Some("foo"))); - assert_eq!(y.unzip(), (None, None)); -} - -#[test] -fn zip_unzip_roundtrip() { - let x = Some(10); - let y = Some("foo"); - - let z = x.zip(y); - assert_eq!(z, Some((10, "foo"))); - - let a = z.unzip(); - assert_eq!(a, (x, y)); -} - -#[test] -fn as_slice() { - assert_eq!(Some(42).as_slice(), &[42]); - assert_eq!(Some(43).as_mut_slice(), &[43]); - assert_eq!(None::.as_slice(), &[]); - assert_eq!(None::.as_mut_slice(), &[]); -} diff --git a/library/core/tests/panic.rs b/library/core/tests/panic.rs deleted file mode 100644 index 24b6c56b35691..0000000000000 --- a/library/core/tests/panic.rs +++ /dev/null @@ -1 +0,0 @@ -mod location; diff --git a/library/core/tests/panic/location.rs b/library/core/tests/panic/location.rs deleted file mode 100644 index d20241d838001..0000000000000 --- a/library/core/tests/panic/location.rs +++ /dev/null @@ -1,31 +0,0 @@ -use core::panic::Location; - -// Note: Some of the following tests depend on the source location, -// so please be careful when editing this file. - -#[test] -fn location_const_caller() { - const _CALLER_REFERENCE: &Location<'static> = Location::caller(); - const _CALLER: Location<'static> = *Location::caller(); -} - -#[test] -fn location_const_file() { - const CALLER: &Location<'static> = Location::caller(); - const FILE: &str = CALLER.file(); - assert_eq!(FILE, file!()); -} - -#[test] -fn location_const_line() { - const CALLER: &Location<'static> = Location::caller(); - const LINE: u32 = CALLER.line(); - assert_eq!(LINE, 21); -} - -#[test] -fn location_const_column() { - const CALLER: &Location<'static> = Location::caller(); - const COLUMN: u32 = CALLER.column(); - assert_eq!(COLUMN, 40); -} diff --git a/library/core/tests/pattern.rs b/library/core/tests/pattern.rs deleted file mode 100644 index d4bec996d89a1..0000000000000 --- a/library/core/tests/pattern.rs +++ /dev/null @@ -1,503 +0,0 @@ -use std::str::pattern::*; - -// This macro makes it easier to write -// tests that do a series of iterations -macro_rules! search_asserts { - ($haystack:expr, $needle:expr, $testname:expr, [$($func:ident),*], $result:expr) => { - let mut searcher = $needle.into_searcher($haystack); - let arr = [$( Step::from(searcher.$func()) ),*]; - assert_eq!(&arr[..], &$result, $testname); - } -} - -/// Combined enum for the results of next() and next_match()/next_reject() -#[derive(Debug, PartialEq, Eq)] -enum Step { - // variant names purposely chosen to - // be the same length for easy alignment - Matches(usize, usize), - Rejects(usize, usize), - InRange(usize, usize), - Done, -} - -use self::Step::*; - -impl From for Step { - fn from(x: SearchStep) -> Self { - match x { - SearchStep::Match(a, b) => Matches(a, b), - SearchStep::Reject(a, b) => Rejects(a, b), - SearchStep::Done => Done, - } - } -} - -impl From> for Step { - fn from(x: Option<(usize, usize)>) -> Self { - match x { - Some((a, b)) => InRange(a, b), - None => Done, - } - } -} - -// FIXME(Manishearth) these tests focus on single-character searching (CharSearcher) -// and on next()/next_match(), not next_reject(). This is because -// the memchr changes make next_match() for single chars complex, but next_reject() -// continues to use next() under the hood. We should add more test cases for all -// of these, as well as tests for StrSearcher and higher level tests for str::find() (etc) - -#[test] -fn test_simple_iteration() { - search_asserts!( - "abcdeabcd", - 'a', - "forward iteration for ASCII string", - // a b c d e a b c d EOF - [next, next, next, next, next, next, next, next, next, next], - [ - Matches(0, 1), - Rejects(1, 2), - Rejects(2, 3), - Rejects(3, 4), - Rejects(4, 5), - Matches(5, 6), - Rejects(6, 7), - Rejects(7, 8), - Rejects(8, 9), - Done - ] - ); - - search_asserts!( - "abcdeabcd", - 'a', - "reverse iteration for ASCII string", - // d c b a e d c b a EOF - [ - next_back, next_back, next_back, next_back, next_back, next_back, next_back, next_back, - next_back, next_back - ], - [ - Rejects(8, 9), - Rejects(7, 8), - Rejects(6, 7), - Matches(5, 6), - Rejects(4, 5), - Rejects(3, 4), - Rejects(2, 3), - Rejects(1, 2), - Matches(0, 1), - Done - ] - ); - - search_asserts!( - "我爱我的猫", - '我', - "forward iteration for Chinese string", - // 我 愛 我 的 貓 EOF - [next, next, next, next, next, next], - [Matches(0, 3), Rejects(3, 6), Matches(6, 9), Rejects(9, 12), Rejects(12, 15), Done] - ); - - search_asserts!( - "我的猫说meow", - 'm', - "forward iteration for mixed string", - // 我 的 猫 说 m e o w EOF - [next, next, next, next, next, next, next, next, next], - [ - Rejects(0, 3), - Rejects(3, 6), - Rejects(6, 9), - Rejects(9, 12), - Matches(12, 13), - Rejects(13, 14), - Rejects(14, 15), - Rejects(15, 16), - Done - ] - ); - - search_asserts!( - "我的猫说meow", - '猫', - "reverse iteration for mixed string", - // w o e m 说 猫 的 我 EOF - [ - next_back, next_back, next_back, next_back, next_back, next_back, next_back, next_back, - next_back - ], - [ - Rejects(15, 16), - Rejects(14, 15), - Rejects(13, 14), - Rejects(12, 13), - Rejects(9, 12), - Matches(6, 9), - Rejects(3, 6), - Rejects(0, 3), - Done - ] - ); -} - -#[test] -fn test_simple_search() { - search_asserts!( - "abcdeabcdeabcde", - 'a', - "next_match for ASCII string", - [next_match, next_match, next_match, next_match], - [InRange(0, 1), InRange(5, 6), InRange(10, 11), Done] - ); - - search_asserts!( - "abcdeabcdeabcde", - 'a', - "next_match_back for ASCII string", - [next_match_back, next_match_back, next_match_back, next_match_back], - [InRange(10, 11), InRange(5, 6), InRange(0, 1), Done] - ); - - search_asserts!( - "abcdeab", - 'a', - "next_reject for ASCII string", - [next_reject, next_reject, next_match, next_reject, next_reject], - [InRange(1, 2), InRange(2, 3), InRange(5, 6), InRange(6, 7), Done] - ); - - search_asserts!( - "abcdeabcdeabcde", - 'a', - "next_reject_back for ASCII string", - [ - next_reject_back, - next_reject_back, - next_match_back, - next_reject_back, - next_reject_back, - next_reject_back - ], - [ - InRange(14, 15), - InRange(13, 14), - InRange(10, 11), - InRange(9, 10), - InRange(8, 9), - InRange(7, 8) - ] - ); -} - -// Á, 각, ก, 😀 all end in 0x81 -// 🁀, ᘀ do not end in 0x81 but contain the byte -// ꁁ has 0x81 as its second and third bytes. -// -// The memchr-using implementation of next_match -// and next_match_back temporarily violate -// the property that the search is always on a unicode boundary, -// which is fine as long as this never reaches next() or next_back(). -// So we test if next() is correct after each next_match() as well. -const STRESS: &str = "Áa🁀bÁꁁfg😁각กᘀ각aÁ각ꁁก😁a"; - -#[test] -fn test_stress_indices() { - // this isn't really a test, more of documentation on the indices of each character in the stresstest string - - search_asserts!( - STRESS, - 'x', - "Indices of characters in stress test", - [ - next, next, next, next, next, next, next, next, next, next, next, next, next, next, - next, next, next, next, next, next, next - ], - [ - Rejects(0, 2), // Á - Rejects(2, 3), // a - Rejects(3, 7), // 🁀 - Rejects(7, 8), // b - Rejects(8, 10), // Á - Rejects(10, 13), // ꁁ - Rejects(13, 14), // f - Rejects(14, 15), // g - Rejects(15, 19), // 😀 - Rejects(19, 22), // 각 - Rejects(22, 25), // ก - Rejects(25, 28), // ᘀ - Rejects(28, 31), // 각 - Rejects(31, 32), // a - Rejects(32, 34), // Á - Rejects(34, 37), // 각 - Rejects(37, 40), // ꁁ - Rejects(40, 43), // ก - Rejects(43, 47), // 😀 - Rejects(47, 48), // a - Done - ] - ); -} - -#[test] -fn test_forward_search_shared_bytes() { - search_asserts!( - STRESS, - 'Á', - "Forward search for two-byte Latin character", - [next_match, next_match, next_match, next_match], - [InRange(0, 2), InRange(8, 10), InRange(32, 34), Done] - ); - - search_asserts!( - STRESS, - 'Á', - "Forward search for two-byte Latin character; check if next() still works", - [next_match, next, next_match, next, next_match, next, next_match], - [ - InRange(0, 2), - Rejects(2, 3), - InRange(8, 10), - Rejects(10, 13), - InRange(32, 34), - Rejects(34, 37), - Done - ] - ); - - search_asserts!( - STRESS, - '각', - "Forward search for three-byte Hangul character", - [next_match, next, next_match, next_match, next_match], - [InRange(19, 22), Rejects(22, 25), InRange(28, 31), InRange(34, 37), Done] - ); - - search_asserts!( - STRESS, - '각', - "Forward search for three-byte Hangul character; check if next() still works", - [next_match, next, next_match, next, next_match, next, next_match], - [ - InRange(19, 22), - Rejects(22, 25), - InRange(28, 31), - Rejects(31, 32), - InRange(34, 37), - Rejects(37, 40), - Done - ] - ); - - search_asserts!( - STRESS, - 'ก', - "Forward search for three-byte Thai character", - [next_match, next, next_match, next, next_match], - [InRange(22, 25), Rejects(25, 28), InRange(40, 43), Rejects(43, 47), Done] - ); - - search_asserts!( - STRESS, - 'ก', - "Forward search for three-byte Thai character; check if next() still works", - [next_match, next, next_match, next, next_match], - [InRange(22, 25), Rejects(25, 28), InRange(40, 43), Rejects(43, 47), Done] - ); - - search_asserts!( - STRESS, - '😁', - "Forward search for four-byte emoji", - [next_match, next, next_match, next, next_match], - [InRange(15, 19), Rejects(19, 22), InRange(43, 47), Rejects(47, 48), Done] - ); - - search_asserts!( - STRESS, - '😁', - "Forward search for four-byte emoji; check if next() still works", - [next_match, next, next_match, next, next_match], - [InRange(15, 19), Rejects(19, 22), InRange(43, 47), Rejects(47, 48), Done] - ); - - search_asserts!( - STRESS, - 'ꁁ', - "Forward search for three-byte Yi character with repeated bytes", - [next_match, next, next_match, next, next_match], - [InRange(10, 13), Rejects(13, 14), InRange(37, 40), Rejects(40, 43), Done] - ); - - search_asserts!( - STRESS, - 'ꁁ', - "Forward search for three-byte Yi character with repeated bytes; check if next() still works", - [next_match, next, next_match, next, next_match], - [InRange(10, 13), Rejects(13, 14), InRange(37, 40), Rejects(40, 43), Done] - ); -} - -#[test] -fn test_reverse_search_shared_bytes() { - search_asserts!( - STRESS, - 'Á', - "Reverse search for two-byte Latin character", - [next_match_back, next_match_back, next_match_back, next_match_back], - [InRange(32, 34), InRange(8, 10), InRange(0, 2), Done] - ); - - search_asserts!( - STRESS, - 'Á', - "Reverse search for two-byte Latin character; check if next_back() still works", - [next_match_back, next_back, next_match_back, next_back, next_match_back, next_back], - [InRange(32, 34), Rejects(31, 32), InRange(8, 10), Rejects(7, 8), InRange(0, 2), Done] - ); - - search_asserts!( - STRESS, - '각', - "Reverse search for three-byte Hangul character", - [next_match_back, next_back, next_match_back, next_match_back, next_match_back], - [InRange(34, 37), Rejects(32, 34), InRange(28, 31), InRange(19, 22), Done] - ); - - search_asserts!( - STRESS, - '각', - "Reverse search for three-byte Hangul character; check if next_back() still works", - [ - next_match_back, - next_back, - next_match_back, - next_back, - next_match_back, - next_back, - next_match_back - ], - [ - InRange(34, 37), - Rejects(32, 34), - InRange(28, 31), - Rejects(25, 28), - InRange(19, 22), - Rejects(15, 19), - Done - ] - ); - - search_asserts!( - STRESS, - 'ก', - "Reverse search for three-byte Thai character", - [next_match_back, next_back, next_match_back, next_back, next_match_back], - [InRange(40, 43), Rejects(37, 40), InRange(22, 25), Rejects(19, 22), Done] - ); - - search_asserts!( - STRESS, - 'ก', - "Reverse search for three-byte Thai character; check if next_back() still works", - [next_match_back, next_back, next_match_back, next_back, next_match_back], - [InRange(40, 43), Rejects(37, 40), InRange(22, 25), Rejects(19, 22), Done] - ); - - search_asserts!( - STRESS, - '😁', - "Reverse search for four-byte emoji", - [next_match_back, next_back, next_match_back, next_back, next_match_back], - [InRange(43, 47), Rejects(40, 43), InRange(15, 19), Rejects(14, 15), Done] - ); - - search_asserts!( - STRESS, - '😁', - "Reverse search for four-byte emoji; check if next_back() still works", - [next_match_back, next_back, next_match_back, next_back, next_match_back], - [InRange(43, 47), Rejects(40, 43), InRange(15, 19), Rejects(14, 15), Done] - ); - - search_asserts!( - STRESS, - 'ꁁ', - "Reverse search for three-byte Yi character with repeated bytes", - [next_match_back, next_back, next_match_back, next_back, next_match_back], - [InRange(37, 40), Rejects(34, 37), InRange(10, 13), Rejects(8, 10), Done] - ); - - search_asserts!( - STRESS, - 'ꁁ', - "Reverse search for three-byte Yi character with repeated bytes; check if next_back() still works", - [next_match_back, next_back, next_match_back, next_back, next_match_back], - [InRange(37, 40), Rejects(34, 37), InRange(10, 13), Rejects(8, 10), Done] - ); -} - -#[test] -fn double_ended_regression_test() { - // https://github.com/rust-lang/rust/issues/47175 - // Ensures that double ended searching comes to a convergence - search_asserts!( - "abcdeabcdeabcde", - 'a', - "alternating double ended search", - [next_match, next_match_back, next_match, next_match_back], - [InRange(0, 1), InRange(10, 11), InRange(5, 6), Done] - ); - search_asserts!( - "abcdeabcdeabcde", - 'a', - "triple double ended search for a", - [next_match, next_match_back, next_match_back, next_match_back], - [InRange(0, 1), InRange(10, 11), InRange(5, 6), Done] - ); - search_asserts!( - "abcdeabcdeabcde", - 'd', - "triple double ended search for d", - [next_match, next_match_back, next_match_back, next_match_back], - [InRange(3, 4), InRange(13, 14), InRange(8, 9), Done] - ); - search_asserts!( - STRESS, - 'Á', - "Double ended search for two-byte Latin character", - [next_match, next_match_back, next_match, next_match_back], - [InRange(0, 2), InRange(32, 34), InRange(8, 10), Done] - ); - search_asserts!( - STRESS, - '각', - "Reverse double ended search for three-byte Hangul character", - [next_match_back, next_back, next_match, next, next_match_back, next_match], - [InRange(34, 37), Rejects(32, 34), InRange(19, 22), Rejects(22, 25), InRange(28, 31), Done] - ); - search_asserts!( - STRESS, - 'ก', - "Double ended search for three-byte Thai character", - [next_match, next_back, next, next_match_back, next_match], - [InRange(22, 25), Rejects(47, 48), Rejects(25, 28), InRange(40, 43), Done] - ); - search_asserts!( - STRESS, - '😁', - "Double ended search for four-byte emoji", - [next_match_back, next, next_match, next_back, next_match], - [InRange(43, 47), Rejects(0, 2), InRange(15, 19), Rejects(40, 43), Done] - ); - search_asserts!( - STRESS, - 'ꁁ', - "Double ended search for three-byte Yi character with repeated bytes", - [next_match, next, next_match_back, next_back, next_match], - [InRange(10, 13), Rejects(13, 14), InRange(37, 40), Rejects(34, 37), Done] - ); -} diff --git a/library/core/tests/pin.rs b/library/core/tests/pin.rs deleted file mode 100644 index 6f617c8d0c297..0000000000000 --- a/library/core/tests/pin.rs +++ /dev/null @@ -1,31 +0,0 @@ -use core::pin::Pin; - -#[test] -fn pin_const() { - // test that the methods of `Pin` are usable in a const context - - const POINTER: &'static usize = &2; - - const PINNED: Pin<&'static usize> = Pin::new(POINTER); - const PINNED_UNCHECKED: Pin<&'static usize> = unsafe { Pin::new_unchecked(POINTER) }; - assert_eq!(PINNED_UNCHECKED, PINNED); - - const INNER: &'static usize = Pin::into_inner(PINNED); - assert_eq!(INNER, POINTER); - - const INNER_UNCHECKED: &'static usize = unsafe { Pin::into_inner_unchecked(PINNED) }; - assert_eq!(INNER_UNCHECKED, POINTER); - - const REF: &'static usize = PINNED.get_ref(); - assert_eq!(REF, POINTER); - - // Note: `pin_mut_const` tests that the methods of `Pin<&mut T>` are usable in a const context. - // A const fn is used because `&mut` is not (yet) usable in constants. - const fn pin_mut_const() { - let _ = Pin::new(&mut 2).into_ref(); - let _ = Pin::new(&mut 2).get_mut(); - let _ = unsafe { Pin::new(&mut 2).get_unchecked_mut() }; - } - - pin_mut_const(); -} diff --git a/library/core/tests/pin_macro.rs b/library/core/tests/pin_macro.rs deleted file mode 100644 index 79c8c166c58d9..0000000000000 --- a/library/core/tests/pin_macro.rs +++ /dev/null @@ -1,33 +0,0 @@ -// edition:2021 -use core::{ - marker::PhantomPinned, - mem::{drop as stuff, transmute}, - pin::{pin, Pin}, -}; - -#[test] -fn basic() { - let it: Pin<&mut PhantomPinned> = pin!(PhantomPinned); - stuff(it); -} - -#[test] -fn extension_works_through_block() { - let it: Pin<&mut PhantomPinned> = { pin!(PhantomPinned) }; - stuff(it); -} - -#[test] -fn extension_works_through_unsafe_block() { - // "retro-type-inference" works as well. - let it: Pin<&mut PhantomPinned> = unsafe { pin!(transmute(())) }; - stuff(it); -} - -#[test] -fn unsize_coercion() { - let slice: Pin<&mut [PhantomPinned]> = pin!([PhantomPinned; 2]); - stuff(slice); - let dyn_obj: Pin<&mut dyn Send> = pin!([PhantomPinned; 2]); - stuff(dyn_obj); -} diff --git a/library/core/tests/ptr.rs b/library/core/tests/ptr.rs deleted file mode 100644 index 7b55c2bf8a813..0000000000000 --- a/library/core/tests/ptr.rs +++ /dev/null @@ -1,1173 +0,0 @@ -use core::cell::RefCell; -use core::marker::Freeze; -use core::mem::{self, MaybeUninit}; -use core::num::NonZero; -use core::ptr; -use core::ptr::*; -use std::fmt::{Debug, Display}; - -#[test] -fn test_const_from_raw_parts() { - const SLICE: &[u8] = &[1, 2, 3, 4]; - const FROM_RAW: &[u8] = unsafe { &*slice_from_raw_parts(SLICE.as_ptr(), SLICE.len()) }; - assert_eq!(SLICE, FROM_RAW); - - let slice = &[1, 2, 3, 4, 5]; - let from_raw = unsafe { &*slice_from_raw_parts(slice.as_ptr(), 2) }; - assert_eq!(&slice[..2], from_raw); -} - -#[test] -fn test() { - unsafe { - #[repr(C)] - struct Pair { - fst: isize, - snd: isize, - } - let mut p = Pair { fst: 10, snd: 20 }; - let pptr: *mut Pair = addr_of_mut!(p); - let iptr: *mut isize = pptr as *mut isize; - assert_eq!(*iptr, 10); - *iptr = 30; - assert_eq!(*iptr, 30); - assert_eq!(p.fst, 30); - - *pptr = Pair { fst: 50, snd: 60 }; - assert_eq!(*iptr, 50); - assert_eq!(p.fst, 50); - assert_eq!(p.snd, 60); - - let v0 = vec![32000u16, 32001u16, 32002u16]; - let mut v1 = vec![0u16, 0u16, 0u16]; - - copy(v0.as_ptr().offset(1), v1.as_mut_ptr().offset(1), 1); - assert!((v1[0] == 0u16 && v1[1] == 32001u16 && v1[2] == 0u16)); - copy(v0.as_ptr().offset(2), v1.as_mut_ptr(), 1); - assert!((v1[0] == 32002u16 && v1[1] == 32001u16 && v1[2] == 0u16)); - copy(v0.as_ptr(), v1.as_mut_ptr().offset(2), 1); - assert!((v1[0] == 32002u16 && v1[1] == 32001u16 && v1[2] == 32000u16)); - } -} - -#[test] -fn test_is_null() { - let p: *const isize = null(); - assert!(p.is_null()); - - let q = p.wrapping_offset(1); - assert!(!q.is_null()); - - let mp: *mut isize = null_mut(); - assert!(mp.is_null()); - - let mq = mp.wrapping_offset(1); - assert!(!mq.is_null()); - - // Pointers to unsized types -- slices - let s: &mut [u8] = &mut [1, 2, 3]; - let cs: *const [u8] = s; - assert!(!cs.is_null()); - - let ms: *mut [u8] = s; - assert!(!ms.is_null()); - - let cz: *const [u8] = &[]; - assert!(!cz.is_null()); - - let mz: *mut [u8] = &mut []; - assert!(!mz.is_null()); - - let ncs: *const [u8] = null::<[u8; 3]>(); - assert!(ncs.is_null()); - - let nms: *mut [u8] = null_mut::<[u8; 3]>(); - assert!(nms.is_null()); - - // Pointers to unsized types -- trait objects - let ci: *const dyn ToString = &3; - assert!(!ci.is_null()); - - let mi: *mut dyn ToString = &mut 3; - assert!(!mi.is_null()); - - let nci: *const dyn ToString = null::(); - assert!(nci.is_null()); - - let nmi: *mut dyn ToString = null_mut::(); - assert!(nmi.is_null()); - - extern "C" { - type Extern; - } - let ec: *const Extern = null::(); - assert!(ec.is_null()); - - let em: *mut Extern = null_mut::(); - assert!(em.is_null()); -} - -#[test] -fn test_as_ref() { - unsafe { - let p: *const isize = null(); - assert_eq!(p.as_ref(), None); - - let q: *const isize = &2; - assert_eq!(q.as_ref().unwrap(), &2); - - let p: *mut isize = null_mut(); - assert_eq!(p.as_ref(), None); - - let q: *mut isize = &mut 2; - assert_eq!(q.as_ref().unwrap(), &2); - - // Lifetime inference - let u = 2isize; - { - let p = &u as *const isize; - assert_eq!(p.as_ref().unwrap(), &2); - } - - // Pointers to unsized types -- slices - let s: &mut [u8] = &mut [1, 2, 3]; - let cs: *const [u8] = s; - assert_eq!(cs.as_ref(), Some(&*s)); - - let ms: *mut [u8] = s; - assert_eq!(ms.as_ref(), Some(&*s)); - - let cz: *const [u8] = &[]; - assert_eq!(cz.as_ref(), Some(&[][..])); - - let mz: *mut [u8] = &mut []; - assert_eq!(mz.as_ref(), Some(&[][..])); - - let ncs: *const [u8] = null::<[u8; 3]>(); - assert_eq!(ncs.as_ref(), None); - - let nms: *mut [u8] = null_mut::<[u8; 3]>(); - assert_eq!(nms.as_ref(), None); - - // Pointers to unsized types -- trait objects - let ci: *const dyn ToString = &3; - assert!(ci.as_ref().is_some()); - - let mi: *mut dyn ToString = &mut 3; - assert!(mi.as_ref().is_some()); - - let nci: *const dyn ToString = null::(); - assert!(nci.as_ref().is_none()); - - let nmi: *mut dyn ToString = null_mut::(); - assert!(nmi.as_ref().is_none()); - } -} - -#[test] -fn test_as_mut() { - unsafe { - let p: *mut isize = null_mut(); - assert!(p.as_mut() == None); - - let q: *mut isize = &mut 2; - assert!(q.as_mut().unwrap() == &mut 2); - - // Lifetime inference - let mut u = 2isize; - { - let p = &mut u as *mut isize; - assert!(p.as_mut().unwrap() == &mut 2); - } - - // Pointers to unsized types -- slices - let s: &mut [u8] = &mut [1, 2, 3]; - let ms: *mut [u8] = s; - assert_eq!(ms.as_mut(), Some(&mut [1, 2, 3][..])); - - let mz: *mut [u8] = &mut []; - assert_eq!(mz.as_mut(), Some(&mut [][..])); - - let nms: *mut [u8] = null_mut::<[u8; 3]>(); - assert_eq!(nms.as_mut(), None); - - // Pointers to unsized types -- trait objects - let mi: *mut dyn ToString = &mut 3; - assert!(mi.as_mut().is_some()); - - let nmi: *mut dyn ToString = null_mut::(); - assert!(nmi.as_mut().is_none()); - } -} - -#[test] -fn test_ptr_addition() { - unsafe { - let xs = vec![5; 16]; - let mut ptr = xs.as_ptr(); - let end = ptr.offset(16); - - while ptr < end { - assert_eq!(*ptr, 5); - ptr = ptr.offset(1); - } - - let mut xs_mut = xs; - let mut m_ptr = xs_mut.as_mut_ptr(); - let m_end = m_ptr.offset(16); - - while m_ptr < m_end { - *m_ptr += 5; - m_ptr = m_ptr.offset(1); - } - - assert!(xs_mut == vec![10; 16]); - } -} - -#[test] -fn test_ptr_subtraction() { - unsafe { - let xs = vec![0, 1, 2, 3, 4, 5, 6, 7, 8, 9]; - let mut idx = 9; - let ptr = xs.as_ptr(); - - while idx >= 0 { - assert_eq!(*(ptr.offset(idx as isize)), idx as isize); - idx = idx - 1; - } - - let mut xs_mut = xs; - let m_start = xs_mut.as_mut_ptr(); - let mut m_ptr = m_start.offset(9); - - loop { - *m_ptr += *m_ptr; - if m_ptr == m_start { - break; - } - m_ptr = m_ptr.offset(-1); - } - - assert_eq!(xs_mut, [0, 2, 4, 6, 8, 10, 12, 14, 16, 18]); - } -} - -#[test] -fn test_set_memory() { - let mut xs = [0u8; 20]; - let ptr = xs.as_mut_ptr(); - unsafe { - write_bytes(ptr, 5u8, xs.len()); - } - assert!(xs == [5u8; 20]); -} - -#[test] -fn test_set_memory_const() { - const XS: [u8; 20] = { - let mut xs = [0u8; 20]; - let ptr = xs.as_mut_ptr(); - unsafe { - ptr.write_bytes(5u8, xs.len()); - } - xs - }; - - assert!(XS == [5u8; 20]); -} - -#[test] -fn test_unsized_nonnull() { - let xs: &[i32] = &[1, 2, 3]; - let ptr = unsafe { NonNull::new_unchecked(xs as *const [i32] as *mut [i32]) }; - let ys = unsafe { ptr.as_ref() }; - let zs: &[i32] = &[1, 2, 3]; - assert!(ys == zs); -} - -#[test] -fn test_const_nonnull_new() { - const { - assert!(NonNull::new(core::ptr::null_mut::<()>()).is_none()); - - let value = &mut 0u32; - let mut ptr = NonNull::new(value).unwrap(); - unsafe { *ptr.as_mut() = 42 }; - - let reference = unsafe { &*ptr.as_ref() }; - assert!(*reference == *value); - assert!(*reference == 42); - }; -} - -#[test] -#[cfg(unix)] // printf may not be available on other platforms -#[allow(deprecated)] // For SipHasher -pub fn test_variadic_fnptr() { - use core::ffi; - use core::hash::{Hash, SipHasher}; - extern "C" { - // This needs to use the correct function signature even though it isn't called as some - // codegen backends make it UB to declare a function with multiple conflicting signatures - // (like LLVM) while others straight up return an error (like Cranelift). - fn printf(_: *const ffi::c_char, ...) -> ffi::c_int; - } - let p: unsafe extern "C" fn(*const ffi::c_char, ...) -> ffi::c_int = printf; - let q = p.clone(); - assert_eq!(p, q); - assert!(!(p < q)); - let mut s = SipHasher::new(); - assert_eq!(p.hash(&mut s), q.hash(&mut s)); -} - -#[test] -fn write_unaligned_drop() { - thread_local! { - static DROPS: RefCell> = RefCell::new(Vec::new()); - } - - struct Dropper(u32); - - impl Drop for Dropper { - fn drop(&mut self) { - DROPS.with(|d| d.borrow_mut().push(self.0)); - } - } - - { - let c = Dropper(0); - let mut t = Dropper(1); - unsafe { - write_unaligned(&mut t, c); - } - } - DROPS.with(|d| assert_eq!(*d.borrow(), [0])); -} - -#[test] -fn align_offset_zst() { - // For pointers of stride = 0, the pointer is already aligned or it cannot be aligned at - // all, because no amount of elements will align the pointer. - let mut p = 1; - while p < 1024 { - assert_eq!(ptr::without_provenance::<()>(p).align_offset(p), 0); - if p != 1 { - assert_eq!(ptr::without_provenance::<()>(p + 1).align_offset(p), !0); - } - p = (p + 1).next_power_of_two(); - } -} - -#[test] -fn align_offset_zst_const() { - const { - // For pointers of stride = 0, the pointer is already aligned or it cannot be aligned at - // all, because no amount of elements will align the pointer. - let mut p = 1; - while p < 1024 { - assert!(ptr::without_provenance::<()>(p).align_offset(p) == 0); - if p != 1 { - assert!(ptr::without_provenance::<()>(p + 1).align_offset(p) == !0); - } - p = (p + 1).next_power_of_two(); - } - } -} - -#[test] -fn align_offset_stride_one() { - // For pointers of stride = 1, the pointer can always be aligned. The offset is equal to - // number of bytes. - let mut align = 1; - while align < 1024 { - for ptr in 1..2 * align { - let expected = ptr % align; - let offset = if expected == 0 { 0 } else { align - expected }; - assert_eq!( - ptr::without_provenance::(ptr).align_offset(align), - offset, - "ptr = {}, align = {}, size = 1", - ptr, - align - ); - } - align = (align + 1).next_power_of_two(); - } -} - -#[test] -fn align_offset_stride_one_const() { - const { - // For pointers of stride = 1, the pointer can always be aligned. The offset is equal to - // number of bytes. - let mut align = 1; - while align < 1024 { - let mut ptr = 1; - while ptr < 2 * align { - let expected = ptr % align; - let offset = if expected == 0 { 0 } else { align - expected }; - assert!(ptr::without_provenance::(ptr).align_offset(align) == offset); - ptr += 1; - } - align = (align + 1).next_power_of_two(); - } - } -} - -#[test] -fn align_offset_various_strides() { - unsafe fn test_stride(ptr: *const T, align: usize) -> bool { - let numptr = ptr as usize; - let mut expected = usize::MAX; - // Naive but definitely correct way to find the *first* aligned element of stride::. - for el in 0..align { - if (numptr + el * ::std::mem::size_of::()) % align == 0 { - expected = el; - break; - } - } - let got = ptr.align_offset(align); - if got != expected { - eprintln!( - "aligning {:p} (with stride of {}) to {}, expected {}, got {}", - ptr, - ::std::mem::size_of::(), - align, - expected, - got - ); - return true; - } - return false; - } - - // For pointers of stride != 1, we verify the algorithm against the naivest possible - // implementation - let mut align = 1; - let mut x = false; - // Miri is too slow - let limit = if cfg!(miri) { 32 } else { 1024 }; - while align < limit { - for ptr in 1usize..4 * align { - unsafe { - #[repr(packed)] - struct A3(#[allow(dead_code)] u16, #[allow(dead_code)] u8); - x |= test_stride::(ptr::without_provenance::(ptr), align); - - struct A4(#[allow(dead_code)] u32); - x |= test_stride::(ptr::without_provenance::(ptr), align); - - #[repr(packed)] - struct A5(#[allow(dead_code)] u32, #[allow(dead_code)] u8); - x |= test_stride::(ptr::without_provenance::(ptr), align); - - #[repr(packed)] - struct A6(#[allow(dead_code)] u32, #[allow(dead_code)] u16); - x |= test_stride::(ptr::without_provenance::(ptr), align); - - #[repr(packed)] - struct A7(#[allow(dead_code)] u32, #[allow(dead_code)] u16, #[allow(dead_code)] u8); - x |= test_stride::(ptr::without_provenance::(ptr), align); - - #[repr(packed)] - struct A8(#[allow(dead_code)] u32, #[allow(dead_code)] u32); - x |= test_stride::(ptr::without_provenance::(ptr), align); - - #[repr(packed)] - struct A9(#[allow(dead_code)] u32, #[allow(dead_code)] u32, #[allow(dead_code)] u8); - x |= test_stride::(ptr::without_provenance::(ptr), align); - - #[repr(packed)] - struct A10( - #[allow(dead_code)] u32, - #[allow(dead_code)] u32, - #[allow(dead_code)] u16, - ); - x |= test_stride::(ptr::without_provenance::(ptr), align); - - x |= test_stride::(ptr::without_provenance::(ptr), align); - x |= test_stride::(ptr::without_provenance::(ptr), align); - } - } - align = (align + 1).next_power_of_two(); - } - assert!(!x); -} - -#[test] -fn align_offset_various_strides_const() { - const unsafe fn test_stride(ptr: *const T, numptr: usize, align: usize) { - let mut expected = usize::MAX; - // Naive but definitely correct way to find the *first* aligned element of stride::. - let mut el = 0; - while el < align { - if (numptr + el * ::std::mem::size_of::()) % align == 0 { - expected = el; - break; - } - el += 1; - } - let got = ptr.align_offset(align); - assert!(got == expected); - } - - const { - // For pointers of stride != 1, we verify the algorithm against the naivest possible - // implementation - let mut align = 1; - let limit = 32; - while align < limit { - let mut ptr = 1; - while ptr < 4 * align { - unsafe { - #[repr(packed)] - struct A3(#[allow(dead_code)] u16, #[allow(dead_code)] u8); - test_stride::(ptr::without_provenance::(ptr), ptr, align); - - struct A4(#[allow(dead_code)] u32); - test_stride::(ptr::without_provenance::(ptr), ptr, align); - - #[repr(packed)] - struct A5(#[allow(dead_code)] u32, #[allow(dead_code)] u8); - test_stride::(ptr::without_provenance::(ptr), ptr, align); - - #[repr(packed)] - struct A6(#[allow(dead_code)] u32, #[allow(dead_code)] u16); - test_stride::(ptr::without_provenance::(ptr), ptr, align); - - #[repr(packed)] - struct A7( - #[allow(dead_code)] u32, - #[allow(dead_code)] u16, - #[allow(dead_code)] u8, - ); - test_stride::(ptr::without_provenance::(ptr), ptr, align); - - #[repr(packed)] - struct A8(#[allow(dead_code)] u32, #[allow(dead_code)] u32); - test_stride::(ptr::without_provenance::(ptr), ptr, align); - - #[repr(packed)] - struct A9( - #[allow(dead_code)] u32, - #[allow(dead_code)] u32, - #[allow(dead_code)] u8, - ); - test_stride::(ptr::without_provenance::(ptr), ptr, align); - - #[repr(packed)] - struct A10( - #[allow(dead_code)] u32, - #[allow(dead_code)] u32, - #[allow(dead_code)] u16, - ); - test_stride::(ptr::without_provenance::(ptr), ptr, align); - - test_stride::(ptr::without_provenance::(ptr), ptr, align); - test_stride::(ptr::without_provenance::(ptr), ptr, align); - } - ptr += 1; - } - align = (align + 1).next_power_of_two(); - } - } -} - -#[test] -fn align_offset_with_provenance_const() { - const { - // On some platforms (e.g. msp430-none-elf), the alignment of `i32` is less than 4. - #[repr(align(4))] - struct AlignedI32(i32); - - let data = AlignedI32(42); - - // `stride % align == 0` (usual case) - - let ptr: *const i32 = &data.0; - assert!(ptr.align_offset(1) == 0); - assert!(ptr.align_offset(2) == 0); - assert!(ptr.align_offset(4) == 0); - assert!(ptr.align_offset(8) == usize::MAX); - assert!(ptr.wrapping_byte_add(1).align_offset(1) == 0); - assert!(ptr.wrapping_byte_add(1).align_offset(2) == usize::MAX); - assert!(ptr.wrapping_byte_add(2).align_offset(1) == 0); - assert!(ptr.wrapping_byte_add(2).align_offset(2) == 0); - assert!(ptr.wrapping_byte_add(2).align_offset(4) == usize::MAX); - assert!(ptr.wrapping_byte_add(3).align_offset(1) == 0); - assert!(ptr.wrapping_byte_add(3).align_offset(2) == usize::MAX); - - assert!(ptr.wrapping_add(42).align_offset(4) == 0); - assert!(ptr.wrapping_add(42).align_offset(8) == usize::MAX); - - let ptr1: *const i8 = ptr.cast(); - assert!(ptr1.align_offset(1) == 0); - assert!(ptr1.align_offset(2) == 0); - assert!(ptr1.align_offset(4) == 0); - assert!(ptr1.align_offset(8) == usize::MAX); - assert!(ptr1.wrapping_byte_add(1).align_offset(1) == 0); - assert!(ptr1.wrapping_byte_add(1).align_offset(2) == 1); - assert!(ptr1.wrapping_byte_add(1).align_offset(4) == 3); - assert!(ptr1.wrapping_byte_add(1).align_offset(8) == usize::MAX); - assert!(ptr1.wrapping_byte_add(2).align_offset(1) == 0); - assert!(ptr1.wrapping_byte_add(2).align_offset(2) == 0); - assert!(ptr1.wrapping_byte_add(2).align_offset(4) == 2); - assert!(ptr1.wrapping_byte_add(2).align_offset(8) == usize::MAX); - assert!(ptr1.wrapping_byte_add(3).align_offset(1) == 0); - assert!(ptr1.wrapping_byte_add(3).align_offset(2) == 1); - assert!(ptr1.wrapping_byte_add(3).align_offset(4) == 1); - assert!(ptr1.wrapping_byte_add(3).align_offset(8) == usize::MAX); - - let ptr2: *const i16 = ptr.cast(); - assert!(ptr2.align_offset(1) == 0); - assert!(ptr2.align_offset(2) == 0); - assert!(ptr2.align_offset(4) == 0); - assert!(ptr2.align_offset(8) == usize::MAX); - assert!(ptr2.wrapping_byte_add(1).align_offset(1) == 0); - assert!(ptr2.wrapping_byte_add(1).align_offset(2) == usize::MAX); - assert!(ptr2.wrapping_byte_add(2).align_offset(1) == 0); - assert!(ptr2.wrapping_byte_add(2).align_offset(2) == 0); - assert!(ptr2.wrapping_byte_add(2).align_offset(4) == 1); - assert!(ptr2.wrapping_byte_add(2).align_offset(8) == usize::MAX); - assert!(ptr2.wrapping_byte_add(3).align_offset(1) == 0); - assert!(ptr2.wrapping_byte_add(3).align_offset(2) == usize::MAX); - - let ptr3: *const i64 = ptr.cast(); - assert!(ptr3.align_offset(1) == 0); - assert!(ptr3.align_offset(2) == 0); - assert!(ptr3.align_offset(4) == 0); - assert!(ptr3.align_offset(8) == usize::MAX); - assert!(ptr3.wrapping_byte_add(1).align_offset(1) == 0); - assert!(ptr3.wrapping_byte_add(1).align_offset(2) == usize::MAX); - - // `stride % align != 0` (edge case) - - let ptr4: *const [u8; 3] = ptr.cast(); - assert!(ptr4.align_offset(1) == 0); - assert!(ptr4.align_offset(2) == 0); - assert!(ptr4.align_offset(4) == 0); - assert!(ptr4.align_offset(8) == usize::MAX); - assert!(ptr4.wrapping_byte_add(1).align_offset(1) == 0); - assert!(ptr4.wrapping_byte_add(1).align_offset(2) == 1); - assert!(ptr4.wrapping_byte_add(1).align_offset(4) == 1); - assert!(ptr4.wrapping_byte_add(1).align_offset(8) == usize::MAX); - assert!(ptr4.wrapping_byte_add(2).align_offset(1) == 0); - assert!(ptr4.wrapping_byte_add(2).align_offset(2) == 0); - assert!(ptr4.wrapping_byte_add(2).align_offset(4) == 2); - assert!(ptr4.wrapping_byte_add(2).align_offset(8) == usize::MAX); - assert!(ptr4.wrapping_byte_add(3).align_offset(1) == 0); - assert!(ptr4.wrapping_byte_add(3).align_offset(2) == 1); - assert!(ptr4.wrapping_byte_add(3).align_offset(4) == 3); - assert!(ptr4.wrapping_byte_add(3).align_offset(8) == usize::MAX); - - let ptr5: *const [u8; 5] = ptr.cast(); - assert!(ptr5.align_offset(1) == 0); - assert!(ptr5.align_offset(2) == 0); - assert!(ptr5.align_offset(4) == 0); - assert!(ptr5.align_offset(8) == usize::MAX); - assert!(ptr5.wrapping_byte_add(1).align_offset(1) == 0); - assert!(ptr5.wrapping_byte_add(1).align_offset(2) == 1); - assert!(ptr5.wrapping_byte_add(1).align_offset(4) == 3); - assert!(ptr5.wrapping_byte_add(1).align_offset(8) == usize::MAX); - assert!(ptr5.wrapping_byte_add(2).align_offset(1) == 0); - assert!(ptr5.wrapping_byte_add(2).align_offset(2) == 0); - assert!(ptr5.wrapping_byte_add(2).align_offset(4) == 2); - assert!(ptr5.wrapping_byte_add(2).align_offset(8) == usize::MAX); - assert!(ptr5.wrapping_byte_add(3).align_offset(1) == 0); - assert!(ptr5.wrapping_byte_add(3).align_offset(2) == 1); - assert!(ptr5.wrapping_byte_add(3).align_offset(4) == 1); - assert!(ptr5.wrapping_byte_add(3).align_offset(8) == usize::MAX); - } -} - -#[test] -fn align_offset_issue_103361() { - #[cfg(target_pointer_width = "64")] - const SIZE: usize = 1 << 47; - #[cfg(target_pointer_width = "32")] - const SIZE: usize = 1 << 30; - #[cfg(target_pointer_width = "16")] - const SIZE: usize = 1 << 13; - struct HugeSize(#[allow(dead_code)] [u8; SIZE - 1]); - let _ = ptr::without_provenance::(SIZE).align_offset(SIZE); -} - -#[test] -fn align_offset_issue_103361_const() { - #[cfg(target_pointer_width = "64")] - const SIZE: usize = 1 << 47; - #[cfg(target_pointer_width = "32")] - const SIZE: usize = 1 << 30; - #[cfg(target_pointer_width = "16")] - const SIZE: usize = 1 << 13; - struct HugeSize(#[allow(dead_code)] [u8; SIZE - 1]); - - const { - assert!(ptr::without_provenance::(SIZE - 1).align_offset(SIZE) == SIZE - 1); - assert!(ptr::without_provenance::(SIZE).align_offset(SIZE) == 0); - assert!(ptr::without_provenance::(SIZE + 1).align_offset(SIZE) == 1); - } -} - -#[test] -fn is_aligned() { - let data = 42; - let ptr: *const i32 = &data; - assert!(ptr.is_aligned()); - assert!(ptr.is_aligned_to(1)); - assert!(ptr.is_aligned_to(2)); - assert!(ptr.is_aligned_to(4)); - assert!(ptr.wrapping_byte_add(2).is_aligned_to(1)); - assert!(ptr.wrapping_byte_add(2).is_aligned_to(2)); - assert!(!ptr.wrapping_byte_add(2).is_aligned_to(4)); - - // At runtime either `ptr` or `ptr+1` is aligned to 8. - assert_ne!(ptr.is_aligned_to(8), ptr.wrapping_add(1).is_aligned_to(8)); -} - -#[test] -fn is_aligned_const() { - const { - let data = 42; - let ptr: *const i32 = &data; - assert!(ptr.is_aligned()); - assert!(ptr.is_aligned_to(1)); - assert!(ptr.is_aligned_to(2)); - assert!(ptr.is_aligned_to(4)); - assert!(ptr.wrapping_byte_add(2).is_aligned_to(1)); - assert!(ptr.wrapping_byte_add(2).is_aligned_to(2)); - assert!(!ptr.wrapping_byte_add(2).is_aligned_to(4)); - - // At comptime neither `ptr` nor `ptr+1` is aligned to 8. - assert!(!ptr.is_aligned_to(8)); - assert!(!ptr.wrapping_add(1).is_aligned_to(8)); - } -} - -#[test] -fn offset_from() { - let mut a = [0; 5]; - let ptr1: *mut i32 = &mut a[1]; - let ptr2: *mut i32 = &mut a[3]; - unsafe { - assert_eq!(ptr2.offset_from(ptr1), 2); - assert_eq!(ptr1.offset_from(ptr2), -2); - assert_eq!(ptr1.offset(2), ptr2); - assert_eq!(ptr2.offset(-2), ptr1); - } -} - -#[test] -fn ptr_metadata() { - struct Unit; - struct Pair(A, B); - extern "C" { - type Extern; - } - let () = metadata(&()); - let () = metadata(&Unit); - let () = metadata(&4_u32); - let () = metadata(&String::new()); - let () = metadata(&Some(4_u32)); - let () = metadata(&ptr_metadata); - let () = metadata(&|| {}); - let () = metadata(&[4, 7]); - let () = metadata(&(4, String::new())); - let () = metadata(&Pair(4, String::new())); - let () = metadata(ptr::null::<()>() as *const Extern); - let () = metadata(ptr::null::<()>() as *const <&u32 as std::ops::Deref>::Target); - - assert_eq!(metadata("foo"), 3_usize); - assert_eq!(metadata(&[4, 7][..]), 2_usize); - - let dst_tuple: &(bool, [u8]) = &(true, [0x66, 0x6F, 0x6F]); - let dst_struct: &Pair = &Pair(true, [0x66, 0x6F, 0x6F]); - assert_eq!(metadata(dst_tuple), 3_usize); - assert_eq!(metadata(dst_struct), 3_usize); - unsafe { - let dst_tuple: &(bool, str) = std::mem::transmute(dst_tuple); - let dst_struct: &Pair = std::mem::transmute(dst_struct); - assert_eq!(&dst_tuple.1, "foo"); - assert_eq!(&dst_struct.1, "foo"); - assert_eq!(metadata(dst_tuple), 3_usize); - assert_eq!(metadata(dst_struct), 3_usize); - } - - let vtable_1: DynMetadata = metadata(&4_u16 as &dyn Debug); - let vtable_2: DynMetadata = metadata(&4_u16 as &dyn Display); - let vtable_3: DynMetadata = metadata(&4_u32 as &dyn Display); - let vtable_4: DynMetadata = metadata(&(true, 7_u32) as &(bool, dyn Display)); - let vtable_5: DynMetadata = - metadata(&Pair(true, 7_u32) as &Pair); - unsafe { - let address_1: *const () = std::mem::transmute(vtable_1); - let address_2: *const () = std::mem::transmute(vtable_2); - let address_3: *const () = std::mem::transmute(vtable_3); - let address_4: *const () = std::mem::transmute(vtable_4); - let address_5: *const () = std::mem::transmute(vtable_5); - // Different trait => different vtable pointer - assert_ne!(address_1, address_2); - // Different erased type => different vtable pointer - assert_ne!(address_2, address_3); - // Same erased type and same trait => same vtable pointer - assert_eq!(address_3, address_4); - assert_eq!(address_3, address_5); - } -} - -#[test] -fn ptr_metadata_bounds() { - fn metadata_eq_method_address() -> usize { - // The `Metadata` associated type has an `Ord` bound, so this is valid: - <::Metadata as PartialEq>::eq as usize - } - // "Synthetic" trait impls generated by the compiler like those of `Pointee` - // are not checked for bounds of associated type. - // So with a buggy core we could have both: - // * `::Metadata == DynMetadata` - // * `DynMetadata: !PartialEq` - // … and cause an ICE here: - metadata_eq_method_address::(); - - // For this reason, let’s check here that bounds are satisfied: - - let _ = static_assert_expected_bounds_for_metadata::<()>; - let _ = static_assert_expected_bounds_for_metadata::; - let _ = static_assert_expected_bounds_for_metadata::>; - fn _static_assert_associated_type() { - let _ = static_assert_expected_bounds_for_metadata::<::Metadata>; - } - - fn static_assert_expected_bounds_for_metadata() - where - // Keep this in sync with the associated type in `library/core/src/ptr/metadata.rs` - Meta: Debug + Copy + Send + Sync + Ord + std::hash::Hash + Unpin + Freeze, - { - } -} - -#[test] -fn pointee_metadata_debug() { - assert_eq!("()", format!("{:?}", metadata::(&17))); - assert_eq!("2", format!("{:?}", metadata::<[u32]>(&[19, 23]))); - let for_dyn = format!("{:?}", metadata::(&29)); - assert!(for_dyn.starts_with("DynMetadata(0x"), "{:?}", for_dyn); -} - -#[test] -fn dyn_metadata() { - #[derive(Debug)] - #[repr(align(32))] - struct Something(#[allow(dead_code)] [u8; 47]); - - let value = Something([0; 47]); - let trait_object: &dyn Debug = &value; - let meta = metadata(trait_object); - - assert_eq!(meta.size_of(), 64); - assert_eq!(meta.size_of(), std::mem::size_of::()); - assert_eq!(meta.align_of(), 32); - assert_eq!(meta.align_of(), std::mem::align_of::()); - assert_eq!(meta.layout(), std::alloc::Layout::new::()); - - assert!(format!("{meta:?}").starts_with("DynMetadata(0x")); -} - -#[test] -fn from_raw_parts() { - let mut value = 5_u32; - let address = &mut value as *mut _ as *mut (); - let trait_object: &dyn Display = &mut value; - let vtable = metadata(trait_object); - let trait_object = NonNull::from(trait_object); - - assert_eq!(ptr::from_raw_parts(address, vtable), trait_object.as_ptr()); - assert_eq!(ptr::from_raw_parts_mut(address, vtable), trait_object.as_ptr()); - assert_eq!(NonNull::from_raw_parts(NonNull::new(address).unwrap(), vtable), trait_object); - - let mut array = [5_u32, 5, 5, 5, 5]; - let address = &mut array as *mut _ as *mut (); - let array_ptr = NonNull::from(&mut array); - let slice_ptr = NonNull::from(&mut array[..]); - - assert_eq!(ptr::from_raw_parts(address, ()), array_ptr.as_ptr()); - assert_eq!(ptr::from_raw_parts_mut(address, ()), array_ptr.as_ptr()); - assert_eq!(NonNull::from_raw_parts(NonNull::new(address).unwrap(), ()), array_ptr); - - assert_eq!(ptr::from_raw_parts(address, 5), slice_ptr.as_ptr()); - assert_eq!(ptr::from_raw_parts_mut(address, 5), slice_ptr.as_ptr()); - assert_eq!(NonNull::from_raw_parts(NonNull::new(address).unwrap(), 5), slice_ptr); -} - -#[test] -fn thin_box() { - let foo = ThinBox::::new(4); - assert_eq!(foo.to_string(), "4"); - drop(foo); - let bar = ThinBox::::new(7); - assert_eq!(bar.to_string(), "7"); - - // A slightly more interesting library that could be built on top of metadata APIs. - // - // * It could be generalized to any `T: ?Sized` (not just trait object) - // if `{size,align}_of_for_meta(T::Metadata)` are added. - // * Constructing a `ThinBox` without consuming and deallocating a `Box` - // requires either the unstable `Unsize` marker trait, - // or the unstable `unsized_locals` language feature, - // or taking `&dyn T` and restricting to `T: Copy`. - - use std::alloc::*; - use std::marker::PhantomData; - - struct ThinBox - where - T: ?Sized + Pointee>, - { - ptr: NonNull>, - phantom: PhantomData, - } - - impl ThinBox - where - T: ?Sized + Pointee>, - { - pub fn new>(value: Value) -> Self { - let unsized_: &T = &value; - let meta = metadata(unsized_); - let meta_layout = Layout::for_value(&meta); - let value_layout = Layout::for_value(&value); - let (layout, offset) = meta_layout.extend(value_layout).unwrap(); - // `DynMetadata` is pointer-sized: - assert!(layout.size() > 0); - // If `ThinBox` is generalized to any `T: ?Sized`, - // handle ZSTs with a dangling pointer without going through `alloc()`, - // like `Box` does. - unsafe { - let ptr = NonNull::new(alloc(layout)) - .unwrap_or_else(|| handle_alloc_error(layout)) - .cast::>(); - ptr.as_ptr().write(meta); - ptr.as_ptr().byte_add(offset).cast::().write(value); - Self { ptr, phantom: PhantomData } - } - } - - fn meta(&self) -> DynMetadata { - unsafe { *self.ptr.as_ref() } - } - - fn layout(&self) -> (Layout, usize) { - let meta = self.meta(); - Layout::for_value(&meta).extend(meta.layout()).unwrap() - } - - fn value_ptr(&self) -> *const T { - let (_, offset) = self.layout(); - let data_ptr = unsafe { self.ptr.cast::().as_ptr().add(offset) }; - ptr::from_raw_parts(data_ptr.cast(), self.meta()) - } - - fn value_mut_ptr(&mut self) -> *mut T { - let (_, offset) = self.layout(); - // FIXME: can this line be shared with the same in `value_ptr()` - // without upsetting Stacked Borrows? - let data_ptr = unsafe { self.ptr.cast::().as_ptr().add(offset) }; - from_raw_parts_mut(data_ptr.cast(), self.meta()) - } - } - - impl std::ops::Deref for ThinBox - where - T: ?Sized + Pointee>, - { - type Target = T; - - fn deref(&self) -> &T { - unsafe { &*self.value_ptr() } - } - } - - impl std::ops::DerefMut for ThinBox - where - T: ?Sized + Pointee>, - { - fn deref_mut(&mut self) -> &mut T { - unsafe { &mut *self.value_mut_ptr() } - } - } - - impl std::ops::Drop for ThinBox - where - T: ?Sized + Pointee>, - { - fn drop(&mut self) { - let (layout, _) = self.layout(); - unsafe { - drop_in_place::(&mut **self); - dealloc(self.ptr.cast().as_ptr(), layout); - } - } - } -} - -#[test] -fn nonnull_tagged_pointer_with_provenance() { - let raw_pointer = Box::into_raw(Box::new(10)); - - let mut p = TaggedPointer::new(raw_pointer).unwrap(); - assert_eq!(p.tag(), 0); - - p.set_tag(1); - assert_eq!(p.tag(), 1); - assert_eq!(unsafe { *p.pointer().as_ptr() }, 10); - - p.set_tag(3); - assert_eq!(p.tag(), 3); - assert_eq!(unsafe { *p.pointer().as_ptr() }, 10); - - unsafe { drop(Box::from_raw(p.pointer().as_ptr())) }; - - /// A non-null pointer type which carries several bits of metadata and maintains provenance. - #[repr(transparent)] - pub struct TaggedPointer(NonNull); - - impl Clone for TaggedPointer { - fn clone(&self) -> Self { - Self(self.0) - } - } - - impl Copy for TaggedPointer {} - - impl TaggedPointer { - /// The ABI-required minimum alignment of the `P` type. - pub const ALIGNMENT: usize = core::mem::align_of::(); - /// A mask for data-carrying bits of the address. - pub const DATA_MASK: usize = !Self::ADDRESS_MASK; - /// Number of available bits of storage in the address. - pub const NUM_BITS: u32 = Self::ALIGNMENT.trailing_zeros(); - /// A mask for the non-data-carrying bits of the address. - pub const ADDRESS_MASK: usize = usize::MAX << Self::NUM_BITS; - - /// Create a new tagged pointer from a possibly null pointer. - pub fn new(pointer: *mut T) -> Option> { - Some(TaggedPointer(NonNull::new(pointer)?)) - } - - /// Consume this tagged pointer and produce a raw mutable pointer to the - /// memory location. - pub fn pointer(self) -> NonNull { - // SAFETY: The `addr` guaranteed to have bits set in the Self::ADDRESS_MASK, so the result will be non-null. - self.0 - .map_addr(|addr| unsafe { NonZero::new_unchecked(addr.get() & Self::ADDRESS_MASK) }) - } - - /// Consume this tagged pointer and produce the data it carries. - pub fn tag(&self) -> usize { - self.0.addr().get() & Self::DATA_MASK - } - - /// Update the data this tagged pointer carries to a new value. - pub fn set_tag(&mut self, data: usize) { - assert_eq!( - data & Self::ADDRESS_MASK, - 0, - "cannot set more data beyond the lowest NUM_BITS" - ); - let data = data & Self::DATA_MASK; - - // SAFETY: This value will always be non-zero because the upper bits (from - // ADDRESS_MASK) will always be non-zero. This a property of the type and its - // construction. - self.0 = self.0.map_addr(|addr| unsafe { - NonZero::new_unchecked((addr.get() & Self::ADDRESS_MASK) | data) - }) - } - } -} - -#[test] -fn swap_copy_untyped() { - // We call `{swap,copy}{,_nonoverlapping}` at `bool` type on data that is not a valid bool. - // These should all do untyped copies, so this should work fine. - let mut x = 5u8; - let mut y = 6u8; - - let ptr1 = addr_of_mut!(x).cast::(); - let ptr2 = addr_of_mut!(y).cast::(); - - unsafe { - ptr::swap(ptr1, ptr2); - ptr::swap_nonoverlapping(ptr1, ptr2, 1); - } - assert_eq!(x, 5); - assert_eq!(y, 6); - - unsafe { - ptr::copy(ptr1, ptr2, 1); - ptr::copy_nonoverlapping(ptr1, ptr2, 1); - } - assert_eq!(x, 5); - assert_eq!(y, 5); -} - -#[test] -fn test_const_copy() { - const { - let ptr1 = &1; - let mut ptr2 = &666; - - // Copy ptr1 to ptr2, bytewise. - unsafe { - ptr::copy( - &ptr1 as *const _ as *const MaybeUninit, - &mut ptr2 as *mut _ as *mut MaybeUninit, - mem::size_of::<&i32>(), - ); - } - - // Make sure they still work. - assert!(*ptr1 == 1); - assert!(*ptr2 == 1); - }; - - const { - let ptr1 = &1; - let mut ptr2 = &666; - - // Copy ptr1 to ptr2, bytewise. - unsafe { - ptr::copy_nonoverlapping( - &ptr1 as *const _ as *const MaybeUninit, - &mut ptr2 as *mut _ as *mut MaybeUninit, - mem::size_of::<&i32>(), - ); - } - - // Make sure they still work. - assert!(*ptr1 == 1); - assert!(*ptr2 == 1); - }; -} - -#[test] -fn test_null_array_as_slice() { - let arr: *mut [u8; 4] = null_mut(); - let ptr: *mut [u8] = arr.as_mut_slice(); - assert!(ptr.is_null()); - assert_eq!(ptr.len(), 4); - - let arr: *const [u8; 4] = null(); - let ptr: *const [u8] = arr.as_slice(); - assert!(ptr.is_null()); - assert_eq!(ptr.len(), 4); -} - -#[test] -fn test_ptr_from_raw_parts_in_const() { - const EMPTY_SLICE_PTR: *const [i32] = - std::ptr::slice_from_raw_parts(std::ptr::without_provenance(123), 456); - assert_eq!(EMPTY_SLICE_PTR.addr(), 123); - assert_eq!(EMPTY_SLICE_PTR.len(), 456); -} diff --git a/library/core/tests/result.rs b/library/core/tests/result.rs deleted file mode 100644 index 00a6fd75b4f46..0000000000000 --- a/library/core/tests/result.rs +++ /dev/null @@ -1,422 +0,0 @@ -use core::ops::DerefMut; -use core::option::*; - -fn op1() -> Result { - Ok(666) -} -fn op2() -> Result { - Err("sadface") -} - -#[test] -fn test_and() { - assert_eq!(op1().and(Ok(667)).unwrap(), 667); - assert_eq!(op1().and(Err::("bad")).unwrap_err(), "bad"); - - assert_eq!(op2().and(Ok(667)).unwrap_err(), "sadface"); - assert_eq!(op2().and(Err::("bad")).unwrap_err(), "sadface"); -} - -#[test] -fn test_and_then() { - assert_eq!(op1().and_then(|i| Ok::(i + 1)).unwrap(), 667); - assert_eq!(op1().and_then(|_| Err::("bad")).unwrap_err(), "bad"); - - assert_eq!(op2().and_then(|i| Ok::(i + 1)).unwrap_err(), "sadface"); - assert_eq!(op2().and_then(|_| Err::("bad")).unwrap_err(), "sadface"); -} - -#[test] -fn test_or() { - assert_eq!(op1().or(Ok::<_, &'static str>(667)).unwrap(), 666); - assert_eq!(op1().or(Err("bad")).unwrap(), 666); - - assert_eq!(op2().or(Ok::<_, &'static str>(667)).unwrap(), 667); - assert_eq!(op2().or(Err("bad")).unwrap_err(), "bad"); -} - -#[test] -fn test_or_else() { - assert_eq!(op1().or_else(|_| Ok::(667)).unwrap(), 666); - assert_eq!(op1().or_else(|e| Err::(e)).unwrap(), 666); - - assert_eq!(op2().or_else(|_| Ok::(667)).unwrap(), 667); - assert_eq!(op2().or_else(|e| Err::(e)).unwrap_err(), "sadface"); -} - -#[test] -fn test_impl_map() { - assert!(Ok::(1).map(|x| x + 1) == Ok(2)); - assert!(Err::(1).map(|x| x + 1) == Err(1)); -} - -#[test] -fn test_impl_map_err() { - assert!(Ok::(1).map_err(|x| x + 1) == Ok(1)); - assert!(Err::(1).map_err(|x| x + 1) == Err(2)); -} - -#[test] -fn test_collect() { - let v: Result, ()> = (0..0).map(|_| Ok::(0)).collect(); - assert!(v == Ok(vec![])); - - let v: Result, ()> = (0..3).map(|x| Ok::(x)).collect(); - assert!(v == Ok(vec![0, 1, 2])); - - let v: Result, isize> = (0..3).map(|x| if x > 1 { Err(x) } else { Ok(x) }).collect(); - assert!(v == Err(2)); - - // test that it does not take more elements than it needs - let mut functions: [Box Result<(), isize>>; 3] = - [Box::new(|| Ok(())), Box::new(|| Err(1)), Box::new(|| panic!())]; - - let v: Result, isize> = functions.iter_mut().map(|f| (*f)()).collect(); - assert!(v == Err(1)); -} - -#[test] -fn test_fmt_default() { - let ok: Result = Ok(100); - let err: Result = Err("Err"); - - let s = format!("{ok:?}"); - assert_eq!(s, "Ok(100)"); - let s = format!("{err:?}"); - assert_eq!(s, "Err(\"Err\")"); -} - -#[test] -fn test_unwrap_or() { - let ok: Result = Ok(100); - let ok_err: Result = Err("Err"); - - assert_eq!(ok.unwrap_or(50), 100); - assert_eq!(ok_err.unwrap_or(50), 50); -} - -#[test] -fn test_unwrap_or_else() { - fn handler(msg: &'static str) -> isize { - if msg == "I got this." { 50 } else { panic!("BadBad") } - } - - let ok: Result = Ok(100); - let ok_err: Result = Err("I got this."); - - assert_eq!(ok.unwrap_or_else(handler), 100); - assert_eq!(ok_err.unwrap_or_else(handler), 50); -} - -#[test] -#[should_panic] -pub fn test_unwrap_or_else_panic() { - fn handler(msg: &'static str) -> isize { - if msg == "I got this." { 50 } else { panic!("BadBad") } - } - - let bad_err: Result = Err("Unrecoverable mess."); - let _: isize = bad_err.unwrap_or_else(handler); -} - -#[test] -fn test_unwrap_unchecked() { - let ok: Result = Ok(100); - assert_eq!(unsafe { ok.unwrap_unchecked() }, 100); -} - -#[test] -fn test_unwrap_err_unchecked() { - let ok_err: Result = Err("Err"); - assert_eq!(unsafe { ok_err.unwrap_err_unchecked() }, "Err"); -} - -#[test] -pub fn test_expect_ok() { - let ok: Result = Ok(100); - assert_eq!(ok.expect("Unexpected error"), 100); -} -#[test] -#[should_panic(expected = "Got expected error: \"All good\"")] -pub fn test_expect_err() { - let err: Result = Err("All good"); - err.expect("Got expected error"); -} - -#[test] -pub fn test_expect_err_err() { - let ok: Result<&'static str, isize> = Err(100); - assert_eq!(ok.expect_err("Unexpected ok"), 100); -} -#[test] -#[should_panic(expected = "Got expected ok: \"All good\"")] -pub fn test_expect_err_ok() { - let err: Result<&'static str, isize> = Ok("All good"); - err.expect_err("Got expected ok"); -} - -#[test] -pub fn test_iter() { - let ok: Result = Ok(100); - let mut it = ok.iter(); - assert_eq!(it.size_hint(), (1, Some(1))); - assert_eq!(it.next(), Some(&100)); - assert_eq!(it.size_hint(), (0, Some(0))); - assert!(it.next().is_none()); - assert_eq!((&ok).into_iter().next(), Some(&100)); - - let err: Result = Err("error"); - assert_eq!(err.iter().next(), None); -} - -#[test] -#[allow(for_loops_over_fallibles)] -pub fn test_iter_mut() { - let mut ok: Result = Ok(100); - for loc in ok.iter_mut() { - *loc = 200; - } - assert_eq!(ok, Ok(200)); - for loc in &mut ok { - *loc = 300; - } - assert_eq!(ok, Ok(300)); - - let mut err: Result = Err("error"); - for loc in err.iter_mut() { - *loc = 200; - } - assert_eq!(err, Err("error")); -} - -#[test] -pub fn test_unwrap_or_default() { - assert_eq!(op1().unwrap_or_default(), 666); - assert_eq!(op2().unwrap_or_default(), 0); -} - -#[test] -#[allow(non_local_definitions)] -pub fn test_into_ok() { - fn infallible_op() -> Result { - Ok(666) - } - - assert_eq!(infallible_op().into_ok(), 666); - - enum MyNeverToken {} - impl From for ! { - fn from(never: MyNeverToken) -> ! { - match never {} - } - } - - fn infallible_op2() -> Result { - Ok(667) - } - - assert_eq!(infallible_op2().into_ok(), 667); -} - -#[test] -#[allow(non_local_definitions)] -pub fn test_into_err() { - fn until_error_op() -> Result { - Err(666) - } - - assert_eq!(until_error_op().into_err(), 666); - - enum MyNeverToken {} - impl From for ! { - fn from(never: MyNeverToken) -> ! { - match never {} - } - } - - fn until_error_op2() -> Result { - Err(667) - } - - assert_eq!(until_error_op2().into_err(), 667); -} - -#[test] -fn test_try() { - fn try_result_ok() -> Result { - let result: Result = Ok(1); - let val = result?; - Ok(val) - } - assert_eq!(try_result_ok(), Ok(1)); - - fn try_result_err() -> Result { - let result: Result = Err(1); - let val = result?; - Ok(val) - } - assert_eq!(try_result_err(), Err(1)); -} - -#[test] -fn test_result_as_deref() { - // &Result::Ok(T).as_deref() -> - // Result<&T::Deref::Target, &E>::Ok(&*T) - let ref_ok = &Result::Ok::<&i32, u8>(&42); - let expected_result = Result::Ok::<&i32, &u8>(&42); - assert_eq!(ref_ok.as_deref(), expected_result); - - let ref_ok = &Result::Ok::(String::from("a result")); - let expected_result = Result::Ok::<&str, &u32>("a result"); - assert_eq!(ref_ok.as_deref(), expected_result); - - let ref_ok = &Result::Ok::, u32>(vec![1, 2, 3, 4, 5]); - let expected_result = Result::Ok::<&[i32], &u32>([1, 2, 3, 4, 5].as_slice()); - assert_eq!(ref_ok.as_deref(), expected_result); - - // &Result::Err(T).as_deref() -> - // Result<&T::Deref::Target, &E>::Err(&*E) - let val = 41; - let ref_err = &Result::Err::<&u8, i32>(val); - let expected_result = Result::Err::<&u8, &i32>(&val); - assert_eq!(ref_err.as_deref(), expected_result); - - let s = String::from("an error"); - let ref_err = &Result::Err::<&u32, String>(s.clone()); - let expected_result = Result::Err::<&u32, &String>(&s); - assert_eq!(ref_err.as_deref(), expected_result); - - let v = vec![5, 4, 3, 2, 1]; - let ref_err = &Result::Err::<&u32, Vec>(v.clone()); - let expected_result = Result::Err::<&u32, &Vec>(&v); - assert_eq!(ref_err.as_deref(), expected_result); -} - -#[test] -fn test_result_as_deref_mut() { - // &mut Result::Ok(T).as_deref_mut() -> - // Result<&mut T::DerefMut::Target, &mut E>::Ok(&mut *T) - let mut val = 42; - let mut expected_val = 42; - let mut_ok = &mut Result::Ok::<&mut i32, u8>(&mut val); - let expected_result = Result::Ok::<&mut i32, &mut u8>(&mut expected_val); - assert_eq!(mut_ok.as_deref_mut(), expected_result); - - let mut expected_string = String::from("a result"); - let mut_ok = &mut Result::Ok::(expected_string.clone()); - let expected_result = Result::Ok::<&mut str, &mut u32>(expected_string.deref_mut()); - assert_eq!(mut_ok.as_deref_mut(), expected_result); - - let mut expected_vec = vec![1, 2, 3, 4, 5]; - let mut_ok = &mut Result::Ok::, u32>(expected_vec.clone()); - let expected_result = Result::Ok::<&mut [i32], &mut u32>(expected_vec.as_mut_slice()); - assert_eq!(mut_ok.as_deref_mut(), expected_result); - - // &mut Result::Err(T).as_deref_mut() -> - // Result<&mut T, &mut E>::Err(&mut *E) - let mut val = 41; - let mut_err = &mut Result::Err::<&mut u8, i32>(val); - let expected_result = Result::Err::<&mut u8, &mut i32>(&mut val); - assert_eq!(mut_err.as_deref_mut(), expected_result); - - let mut expected_string = String::from("an error"); - let mut_err = &mut Result::Err::<&mut u32, String>(expected_string.clone()); - let expected_result = Result::Err::<&mut u32, &mut String>(&mut expected_string); - assert_eq!(mut_err.as_deref_mut(), expected_result); - - let mut expected_vec = vec![5, 4, 3, 2, 1]; - let mut_err = &mut Result::Err::<&mut u32, Vec>(expected_vec.clone()); - let expected_result = Result::Err::<&mut u32, &mut Vec>(&mut expected_vec); - assert_eq!(mut_err.as_deref_mut(), expected_result); -} - -#[test] -fn result_const() { - // test that the methods of `Result` are usable in a const context - - const RESULT: Result = Ok(32); - - const REF: Result<&usize, &bool> = RESULT.as_ref(); - assert_eq!(REF, Ok(&32)); - - const IS_OK: bool = RESULT.is_ok(); - assert!(IS_OK); - - const IS_ERR: bool = RESULT.is_err(); - assert!(!IS_ERR) -} - -#[test] -const fn result_const_mut() { - let mut result: Result = Ok(32); - - { - let as_mut = result.as_mut(); - match as_mut { - Ok(v) => *v = 42, - Err(_) => unreachable!(), - } - } - - let mut result_err: Result = Err(false); - - { - let as_mut = result_err.as_mut(); - match as_mut { - Ok(_) => unreachable!(), - Err(v) => *v = true, - } - } -} - -#[test] -fn result_opt_conversions() { - #[derive(Copy, Clone, Debug, PartialEq)] - struct BadNumErr; - - fn try_num(x: i32) -> Result { - if x <= 5 { Ok(x + 1) } else { Err(BadNumErr) } - } - - type ResOpt = Result, BadNumErr>; - type OptRes = Option>; - - let mut x: ResOpt = Ok(Some(5)); - let mut y: OptRes = Some(Ok(5)); - assert_eq!(x, y.transpose()); - assert_eq!(x.transpose(), y); - - x = Ok(None); - y = None; - assert_eq!(x, y.transpose()); - assert_eq!(x.transpose(), y); - - x = Err(BadNumErr); - y = Some(Err(BadNumErr)); - assert_eq!(x, y.transpose()); - assert_eq!(x.transpose(), y); - - let res: Result, BadNumErr> = (0..10) - .map(|x| { - let y = try_num(x)?; - Ok(if y % 2 == 0 { Some(y - 1) } else { None }) - }) - .filter_map(Result::transpose) - .collect(); - - assert_eq!(res, Err(BadNumErr)) -} - -#[test] -fn result_try_trait_v2_branch() { - use core::num::NonZero; - use core::ops::{ControlFlow::*, Try}; - - assert_eq!(Ok::(4).branch(), Continue(4)); - assert_eq!(Err::(4).branch(), Break(Err(4))); - let one = NonZero::new(1).unwrap(); - assert_eq!(Ok::<(), NonZero>(()).branch(), Continue(())); - assert_eq!(Err::<(), NonZero>(one).branch(), Break(Err(one))); - assert_eq!(Ok::, ()>(one).branch(), Continue(one)); - assert_eq!(Err::, ()>(()).branch(), Break(Err(()))); -} diff --git a/library/core/tests/simd.rs b/library/core/tests/simd.rs deleted file mode 100644 index b8b5f26ca3fa4..0000000000000 --- a/library/core/tests/simd.rs +++ /dev/null @@ -1,13 +0,0 @@ -use core::simd::prelude::*; - -#[test] -fn testing() { - let x = f32x4::from_array([1.0, 1.0, 1.0, 1.0]); - let y = -x; - - let h = x * f32x4::splat(0.5); - - let r = y.abs(); - assert_eq!(x, r); - assert_eq!(h, f32x4::splat(0.5)); -} diff --git a/library/core/tests/slice.rs b/library/core/tests/slice.rs deleted file mode 100644 index c91ac2fbb43b0..0000000000000 --- a/library/core/tests/slice.rs +++ /dev/null @@ -1,2693 +0,0 @@ -use core::cell::Cell; -use core::cmp::Ordering; -use core::mem::MaybeUninit; -use core::num::NonZero; -use core::slice; - -#[test] -fn test_position() { - let b = [1, 2, 3, 5, 5]; - assert_eq!(b.iter().position(|&v| v == 9), None); - assert_eq!(b.iter().position(|&v| v == 5), Some(3)); - assert_eq!(b.iter().position(|&v| v == 3), Some(2)); - assert_eq!(b.iter().position(|&v| v == 0), None); -} - -#[test] -fn test_rposition() { - let b = [1, 2, 3, 5, 5]; - assert_eq!(b.iter().rposition(|&v| v == 9), None); - assert_eq!(b.iter().rposition(|&v| v == 5), Some(4)); - assert_eq!(b.iter().rposition(|&v| v == 3), Some(2)); - assert_eq!(b.iter().rposition(|&v| v == 0), None); -} - -#[test] -fn test_binary_search() { - let b: [i32; 0] = []; - assert_eq!(b.binary_search(&5), Err(0)); - - let b = [4]; - assert_eq!(b.binary_search(&3), Err(0)); - assert_eq!(b.binary_search(&4), Ok(0)); - assert_eq!(b.binary_search(&5), Err(1)); - - let b = [1, 2, 4, 6, 8, 9]; - assert_eq!(b.binary_search(&5), Err(3)); - assert_eq!(b.binary_search(&6), Ok(3)); - assert_eq!(b.binary_search(&7), Err(4)); - assert_eq!(b.binary_search(&8), Ok(4)); - - let b = [1, 2, 4, 5, 6, 8]; - assert_eq!(b.binary_search(&9), Err(6)); - - let b = [1, 2, 4, 6, 7, 8, 9]; - assert_eq!(b.binary_search(&6), Ok(3)); - assert_eq!(b.binary_search(&5), Err(3)); - assert_eq!(b.binary_search(&8), Ok(5)); - - let b = [1, 2, 4, 5, 6, 8, 9]; - assert_eq!(b.binary_search(&7), Err(5)); - assert_eq!(b.binary_search(&0), Err(0)); - - let b = [1, 3, 3, 3, 7]; - assert_eq!(b.binary_search(&0), Err(0)); - assert_eq!(b.binary_search(&1), Ok(0)); - assert_eq!(b.binary_search(&2), Err(1)); - assert!(match b.binary_search(&3) { - Ok(1..=3) => true, - _ => false, - }); - assert!(match b.binary_search(&3) { - Ok(1..=3) => true, - _ => false, - }); - assert_eq!(b.binary_search(&4), Err(4)); - assert_eq!(b.binary_search(&5), Err(4)); - assert_eq!(b.binary_search(&6), Err(4)); - assert_eq!(b.binary_search(&7), Ok(4)); - assert_eq!(b.binary_search(&8), Err(5)); - - let b = [(); usize::MAX]; - assert_eq!(b.binary_search(&()), Ok(usize::MAX / 2)); -} - -#[test] -fn test_binary_search_by_overflow() { - let b = [(); usize::MAX]; - assert_eq!(b.binary_search_by(|_| Ordering::Equal), Ok(usize::MAX / 2)); - assert_eq!(b.binary_search_by(|_| Ordering::Greater), Err(0)); - assert_eq!(b.binary_search_by(|_| Ordering::Less), Err(usize::MAX)); -} - -#[test] -// Test implementation specific behavior when finding equivalent elements. -// It is ok to break this test but when you do a crater run is highly advisable. -fn test_binary_search_implementation_details() { - let b = [1, 1, 2, 2, 3, 3, 3]; - assert_eq!(b.binary_search(&1), Ok(1)); - assert_eq!(b.binary_search(&2), Ok(3)); - assert_eq!(b.binary_search(&3), Ok(5)); - let b = [1, 1, 1, 1, 1, 3, 3, 3, 3]; - assert_eq!(b.binary_search(&1), Ok(4)); - assert_eq!(b.binary_search(&3), Ok(7)); - let b = [1, 1, 1, 1, 3, 3, 3, 3, 3]; - assert_eq!(b.binary_search(&1), Ok(2)); - assert_eq!(b.binary_search(&3), Ok(4)); -} - -#[test] -fn test_partition_point() { - let b: [i32; 0] = []; - assert_eq!(b.partition_point(|&x| x < 5), 0); - - let b = [4]; - assert_eq!(b.partition_point(|&x| x < 3), 0); - assert_eq!(b.partition_point(|&x| x < 4), 0); - assert_eq!(b.partition_point(|&x| x < 5), 1); - - let b = [1, 2, 4, 6, 8, 9]; - assert_eq!(b.partition_point(|&x| x < 5), 3); - assert_eq!(b.partition_point(|&x| x < 6), 3); - assert_eq!(b.partition_point(|&x| x < 7), 4); - assert_eq!(b.partition_point(|&x| x < 8), 4); - - let b = [1, 2, 4, 5, 6, 8]; - assert_eq!(b.partition_point(|&x| x < 9), 6); - - let b = [1, 2, 4, 6, 7, 8, 9]; - assert_eq!(b.partition_point(|&x| x < 6), 3); - assert_eq!(b.partition_point(|&x| x < 5), 3); - assert_eq!(b.partition_point(|&x| x < 8), 5); - - let b = [1, 2, 4, 5, 6, 8, 9]; - assert_eq!(b.partition_point(|&x| x < 7), 5); - assert_eq!(b.partition_point(|&x| x < 0), 0); - - let b = [1, 3, 3, 3, 7]; - assert_eq!(b.partition_point(|&x| x < 0), 0); - assert_eq!(b.partition_point(|&x| x < 1), 0); - assert_eq!(b.partition_point(|&x| x < 2), 1); - assert_eq!(b.partition_point(|&x| x < 3), 1); - assert_eq!(b.partition_point(|&x| x < 4), 4); - assert_eq!(b.partition_point(|&x| x < 5), 4); - assert_eq!(b.partition_point(|&x| x < 6), 4); - assert_eq!(b.partition_point(|&x| x < 7), 4); - assert_eq!(b.partition_point(|&x| x < 8), 5); -} - -#[test] -fn test_iterator_advance_by() { - let v = &[0, 1, 2, 3, 4]; - - for i in 0..=v.len() { - let mut iter = v.iter(); - assert_eq!(iter.advance_by(i), Ok(())); - assert_eq!(iter.as_slice(), &v[i..]); - } - - let mut iter = v.iter(); - assert_eq!(iter.advance_by(v.len() + 1), Err(NonZero::new(1).unwrap())); - assert_eq!(iter.as_slice(), &[]); - - let mut iter = v.iter(); - assert_eq!(iter.advance_by(3), Ok(())); - assert_eq!(iter.as_slice(), &v[3..]); - assert_eq!(iter.advance_by(2), Ok(())); - assert_eq!(iter.as_slice(), &[]); - assert_eq!(iter.advance_by(0), Ok(())); -} - -#[test] -fn test_iterator_advance_back_by() { - let v = &[0, 1, 2, 3, 4]; - - for i in 0..=v.len() { - let mut iter = v.iter(); - assert_eq!(iter.advance_back_by(i), Ok(())); - assert_eq!(iter.as_slice(), &v[..v.len() - i]); - } - - let mut iter = v.iter(); - assert_eq!(iter.advance_back_by(v.len() + 1), Err(NonZero::new(1).unwrap())); - assert_eq!(iter.as_slice(), &[]); - - let mut iter = v.iter(); - assert_eq!(iter.advance_back_by(3), Ok(())); - assert_eq!(iter.as_slice(), &v[..v.len() - 3]); - assert_eq!(iter.advance_back_by(2), Ok(())); - assert_eq!(iter.as_slice(), &[]); - assert_eq!(iter.advance_back_by(0), Ok(())); -} - -#[test] -fn test_iterator_nth() { - let v: &[_] = &[0, 1, 2, 3, 4]; - for i in 0..v.len() { - assert_eq!(v.iter().nth(i).unwrap(), &v[i]); - } - assert_eq!(v.iter().nth(v.len()), None); - - let mut iter = v.iter(); - assert_eq!(iter.nth(2).unwrap(), &v[2]); - assert_eq!(iter.nth(1).unwrap(), &v[4]); -} - -#[test] -fn test_iterator_nth_back() { - let v: &[_] = &[0, 1, 2, 3, 4]; - for i in 0..v.len() { - assert_eq!(v.iter().nth_back(i).unwrap(), &v[v.len() - i - 1]); - } - assert_eq!(v.iter().nth_back(v.len()), None); - - let mut iter = v.iter(); - assert_eq!(iter.nth_back(2).unwrap(), &v[2]); - assert_eq!(iter.nth_back(1).unwrap(), &v[0]); -} - -#[test] -fn test_iterator_last() { - let v: &[_] = &[0, 1, 2, 3, 4]; - assert_eq!(v.iter().last().unwrap(), &4); - assert_eq!(v[..1].iter().last().unwrap(), &0); -} - -#[test] -fn test_iterator_count() { - let v: &[_] = &[0, 1, 2, 3, 4]; - assert_eq!(v.iter().count(), 5); - - let mut iter2 = v.iter(); - iter2.next(); - iter2.next(); - assert_eq!(iter2.count(), 3); -} - -#[test] -fn test_chunks_count() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let c = v.chunks(3); - assert_eq!(c.count(), 2); - - let v2: &[i32] = &[0, 1, 2, 3, 4]; - let c2 = v2.chunks(2); - assert_eq!(c2.count(), 3); - - let v3: &[i32] = &[]; - let c3 = v3.chunks(2); - assert_eq!(c3.count(), 0); -} - -#[test] -fn test_chunks_nth() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let mut c = v.chunks(2); - assert_eq!(c.nth(1).unwrap(), &[2, 3]); - assert_eq!(c.next().unwrap(), &[4, 5]); - - let v2: &[i32] = &[0, 1, 2, 3, 4]; - let mut c2 = v2.chunks(3); - assert_eq!(c2.nth(1).unwrap(), &[3, 4]); - assert_eq!(c2.next(), None); -} - -#[test] -fn test_chunks_next() { - let v = [0, 1, 2, 3, 4, 5]; - let mut c = v.chunks(2); - assert_eq!(c.next().unwrap(), &[0, 1]); - assert_eq!(c.next().unwrap(), &[2, 3]); - assert_eq!(c.next().unwrap(), &[4, 5]); - assert_eq!(c.next(), None); - - let v = [0, 1, 2, 3, 4, 5, 6, 7]; - let mut c = v.chunks(3); - assert_eq!(c.next().unwrap(), &[0, 1, 2]); - assert_eq!(c.next().unwrap(), &[3, 4, 5]); - assert_eq!(c.next().unwrap(), &[6, 7]); - assert_eq!(c.next(), None); -} - -#[test] -fn test_chunks_next_back() { - let v = [0, 1, 2, 3, 4, 5]; - let mut c = v.chunks(2); - assert_eq!(c.next_back().unwrap(), &[4, 5]); - assert_eq!(c.next_back().unwrap(), &[2, 3]); - assert_eq!(c.next_back().unwrap(), &[0, 1]); - assert_eq!(c.next_back(), None); - - let v = [0, 1, 2, 3, 4, 5, 6, 7]; - let mut c = v.chunks(3); - assert_eq!(c.next_back().unwrap(), &[6, 7]); - assert_eq!(c.next_back().unwrap(), &[3, 4, 5]); - assert_eq!(c.next_back().unwrap(), &[0, 1, 2]); - assert_eq!(c.next_back(), None); -} - -#[test] -fn test_chunks_nth_back() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let mut c = v.chunks(2); - assert_eq!(c.nth_back(1).unwrap(), &[2, 3]); - assert_eq!(c.next().unwrap(), &[0, 1]); - assert_eq!(c.next(), None); - - let v2: &[i32] = &[0, 1, 2, 3, 4]; - let mut c2 = v2.chunks(3); - assert_eq!(c2.nth_back(1).unwrap(), &[0, 1, 2]); - assert_eq!(c2.next(), None); - assert_eq!(c2.next_back(), None); - - let v3: &[i32] = &[0, 1, 2, 3, 4]; - let mut c3 = v3.chunks(10); - assert_eq!(c3.nth_back(0).unwrap(), &[0, 1, 2, 3, 4]); - assert_eq!(c3.next(), None); - - let v4: &[i32] = &[0, 1, 2]; - let mut c4 = v4.chunks(10); - assert_eq!(c4.nth_back(1_000_000_000usize), None); -} - -#[test] -fn test_chunks_last() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let c = v.chunks(2); - assert_eq!(c.last().unwrap()[1], 5); - - let v2: &[i32] = &[0, 1, 2, 3, 4]; - let c2 = v2.chunks(2); - assert_eq!(c2.last().unwrap()[0], 4); -} - -#[test] -fn test_chunks_zip() { - let v1: &[i32] = &[0, 1, 2, 3, 4]; - let v2: &[i32] = &[6, 7, 8, 9, 10]; - - let res = v1 - .chunks(2) - .zip(v2.chunks(2)) - .map(|(a, b)| a.iter().sum::() + b.iter().sum::()) - .collect::>(); - assert_eq!(res, vec![14, 22, 14]); -} - -#[test] -fn test_chunks_mut_count() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4, 5]; - let c = v.chunks_mut(3); - assert_eq!(c.count(), 2); - - let v2: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let c2 = v2.chunks_mut(2); - assert_eq!(c2.count(), 3); - - let v3: &mut [i32] = &mut []; - let c3 = v3.chunks_mut(2); - assert_eq!(c3.count(), 0); -} - -#[test] -fn test_chunks_mut_nth() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4, 5]; - let mut c = v.chunks_mut(2); - assert_eq!(c.nth(1).unwrap(), &[2, 3]); - assert_eq!(c.next().unwrap(), &[4, 5]); - - let v2: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let mut c2 = v2.chunks_mut(3); - assert_eq!(c2.nth(1).unwrap(), &[3, 4]); - assert_eq!(c2.next(), None); -} - -#[test] -fn test_chunks_mut_nth_back() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4, 5]; - let mut c = v.chunks_mut(2); - assert_eq!(c.nth_back(1).unwrap(), &[2, 3]); - assert_eq!(c.next().unwrap(), &[0, 1]); - - let v1: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let mut c1 = v1.chunks_mut(3); - assert_eq!(c1.nth_back(1).unwrap(), &[0, 1, 2]); - assert_eq!(c1.next(), None); - - let v3: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let mut c3 = v3.chunks_mut(10); - assert_eq!(c3.nth_back(0).unwrap(), &[0, 1, 2, 3, 4]); - assert_eq!(c3.next(), None); - - let v4: &mut [i32] = &mut [0, 1, 2]; - let mut c4 = v4.chunks_mut(10); - assert_eq!(c4.nth_back(1_000_000_000usize), None); -} - -#[test] -fn test_chunks_mut_last() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4, 5]; - let c = v.chunks_mut(2); - assert_eq!(c.last().unwrap(), &[4, 5]); - - let v2: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let c2 = v2.chunks_mut(2); - assert_eq!(c2.last().unwrap(), &[4]); -} - -#[test] -fn test_chunks_mut_zip() { - let v1: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let v2: &[i32] = &[6, 7, 8, 9, 10]; - - for (a, b) in v1.chunks_mut(2).zip(v2.chunks(2)) { - let sum = b.iter().sum::(); - for v in a { - *v += sum; - } - } - assert_eq!(v1, [13, 14, 19, 20, 14]); -} - -#[test] -fn test_chunks_mut_zip_aliasing() { - let v1: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let v2: &[i32] = &[6, 7, 8, 9, 10]; - - let mut it = v1.chunks_mut(2).zip(v2.chunks(2)); - let first = it.next().unwrap(); - let _ = it.next().unwrap(); - assert_eq!(first, (&mut [0, 1][..], &[6, 7][..])); -} - -#[test] -fn test_chunks_exact_mut_zip_aliasing() { - let v1: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let v2: &[i32] = &[6, 7, 8, 9, 10]; - - let mut it = v1.chunks_exact_mut(2).zip(v2.chunks(2)); - let first = it.next().unwrap(); - let _ = it.next().unwrap(); - assert_eq!(first, (&mut [0, 1][..], &[6, 7][..])); -} - -#[test] -fn test_rchunks_mut_zip_aliasing() { - let v1: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let v2: &[i32] = &[6, 7, 8, 9, 10]; - - let mut it = v1.rchunks_mut(2).zip(v2.chunks(2)); - let first = it.next().unwrap(); - let _ = it.next().unwrap(); - assert_eq!(first, (&mut [3, 4][..], &[6, 7][..])); -} - -#[test] -fn test_rchunks_exact_mut_zip_aliasing() { - let v1: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let v2: &[i32] = &[6, 7, 8, 9, 10]; - - let mut it = v1.rchunks_exact_mut(2).zip(v2.chunks(2)); - let first = it.next().unwrap(); - let _ = it.next().unwrap(); - assert_eq!(first, (&mut [3, 4][..], &[6, 7][..])); -} - -#[test] -fn test_chunks_exact_count() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let c = v.chunks_exact(3); - assert_eq!(c.count(), 2); - - let v2: &[i32] = &[0, 1, 2, 3, 4]; - let c2 = v2.chunks_exact(2); - assert_eq!(c2.count(), 2); - - let v3: &[i32] = &[]; - let c3 = v3.chunks_exact(2); - assert_eq!(c3.count(), 0); -} - -#[test] -fn test_chunks_exact_nth() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let mut c = v.chunks_exact(2); - assert_eq!(c.nth(1).unwrap(), &[2, 3]); - assert_eq!(c.next().unwrap(), &[4, 5]); - - let v2: &[i32] = &[0, 1, 2, 3, 4, 5, 6]; - let mut c2 = v2.chunks_exact(3); - assert_eq!(c2.nth(1).unwrap(), &[3, 4, 5]); - assert_eq!(c2.next(), None); -} - -#[test] -fn test_chunks_exact_nth_back() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let mut c = v.chunks_exact(2); - assert_eq!(c.nth_back(1).unwrap(), &[2, 3]); - assert_eq!(c.next().unwrap(), &[0, 1]); - assert_eq!(c.next(), None); - - let v2: &[i32] = &[0, 1, 2, 3, 4]; - let mut c2 = v2.chunks_exact(3); - assert_eq!(c2.nth_back(0).unwrap(), &[0, 1, 2]); - assert_eq!(c2.next(), None); - assert_eq!(c2.next_back(), None); - - let v3: &[i32] = &[0, 1, 2, 3, 4]; - let mut c3 = v3.chunks_exact(10); - assert_eq!(c3.nth_back(0), None); -} - -#[test] -fn test_chunks_exact_last() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let c = v.chunks_exact(2); - assert_eq!(c.last().unwrap(), &[4, 5]); - - let v2: &[i32] = &[0, 1, 2, 3, 4]; - let c2 = v2.chunks_exact(2); - assert_eq!(c2.last().unwrap(), &[2, 3]); -} - -#[test] -fn test_chunks_exact_remainder() { - let v: &[i32] = &[0, 1, 2, 3, 4]; - let c = v.chunks_exact(2); - assert_eq!(c.remainder(), &[4]); -} - -#[test] -fn test_chunks_exact_zip() { - let v1: &[i32] = &[0, 1, 2, 3, 4]; - let v2: &[i32] = &[6, 7, 8, 9, 10]; - - let res = v1 - .chunks_exact(2) - .zip(v2.chunks_exact(2)) - .map(|(a, b)| a.iter().sum::() + b.iter().sum::()) - .collect::>(); - assert_eq!(res, vec![14, 22]); -} - -#[test] -fn test_chunks_exact_mut_count() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4, 5]; - let c = v.chunks_exact_mut(3); - assert_eq!(c.count(), 2); - - let v2: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let c2 = v2.chunks_exact_mut(2); - assert_eq!(c2.count(), 2); - - let v3: &mut [i32] = &mut []; - let c3 = v3.chunks_exact_mut(2); - assert_eq!(c3.count(), 0); -} - -#[test] -fn test_chunks_exact_mut_nth() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4, 5]; - let mut c = v.chunks_exact_mut(2); - assert_eq!(c.nth(1).unwrap(), &[2, 3]); - assert_eq!(c.next().unwrap(), &[4, 5]); - - let v2: &mut [i32] = &mut [0, 1, 2, 3, 4, 5, 6]; - let mut c2 = v2.chunks_exact_mut(3); - assert_eq!(c2.nth(1).unwrap(), &[3, 4, 5]); - assert_eq!(c2.next(), None); -} - -#[test] -fn test_chunks_exact_mut_nth_back() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4, 5]; - let mut c = v.chunks_exact_mut(2); - assert_eq!(c.nth_back(1).unwrap(), &[2, 3]); - assert_eq!(c.next().unwrap(), &[0, 1]); - assert_eq!(c.next(), None); - - let v2: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let mut c2 = v2.chunks_exact_mut(3); - assert_eq!(c2.nth_back(0).unwrap(), &[0, 1, 2]); - assert_eq!(c2.next(), None); - assert_eq!(c2.next_back(), None); - - let v3: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let mut c3 = v3.chunks_exact_mut(10); - assert_eq!(c3.nth_back(0), None); -} - -#[test] -fn test_chunks_exact_mut_last() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4, 5]; - let c = v.chunks_exact_mut(2); - assert_eq!(c.last().unwrap(), &[4, 5]); - - let v2: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let c2 = v2.chunks_exact_mut(2); - assert_eq!(c2.last().unwrap(), &[2, 3]); -} - -#[test] -fn test_chunks_exact_mut_remainder() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let c = v.chunks_exact_mut(2); - assert_eq!(c.into_remainder(), &[4]); -} - -#[test] -fn test_chunks_exact_mut_zip() { - let v1: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let v2: &[i32] = &[6, 7, 8, 9, 10]; - - for (a, b) in v1.chunks_exact_mut(2).zip(v2.chunks_exact(2)) { - let sum = b.iter().sum::(); - for v in a { - *v += sum; - } - } - assert_eq!(v1, [13, 14, 19, 20, 4]); -} - -#[test] -fn test_array_chunks_infer() { - let v: &[i32] = &[0, 1, 2, 3, 4, -4]; - let c = v.array_chunks(); - for &[a, b, c] in c { - assert_eq!(a + b + c, 3); - } - - let v2: &[i32] = &[0, 1, 2, 3, 4, 5, 6]; - let total = v2.array_chunks().map(|&[a, b]| a * b).sum::(); - assert_eq!(total, 2 * 3 + 4 * 5); -} - -#[test] -fn test_array_chunks_count() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let c = v.array_chunks::<3>(); - assert_eq!(c.count(), 2); - - let v2: &[i32] = &[0, 1, 2, 3, 4]; - let c2 = v2.array_chunks::<2>(); - assert_eq!(c2.count(), 2); - - let v3: &[i32] = &[]; - let c3 = v3.array_chunks::<2>(); - assert_eq!(c3.count(), 0); -} - -#[test] -fn test_array_chunks_nth() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let mut c = v.array_chunks::<2>(); - assert_eq!(c.nth(1).unwrap(), &[2, 3]); - assert_eq!(c.next().unwrap(), &[4, 5]); - - let v2: &[i32] = &[0, 1, 2, 3, 4, 5, 6]; - let mut c2 = v2.array_chunks::<3>(); - assert_eq!(c2.nth(1).unwrap(), &[3, 4, 5]); - assert_eq!(c2.next(), None); -} - -#[test] -fn test_array_chunks_nth_back() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let mut c = v.array_chunks::<2>(); - assert_eq!(c.nth_back(1).unwrap(), &[2, 3]); - assert_eq!(c.next().unwrap(), &[0, 1]); - assert_eq!(c.next(), None); - - let v2: &[i32] = &[0, 1, 2, 3, 4]; - let mut c2 = v2.array_chunks::<3>(); - assert_eq!(c2.nth_back(0).unwrap(), &[0, 1, 2]); - assert_eq!(c2.next(), None); - assert_eq!(c2.next_back(), None); - - let v3: &[i32] = &[0, 1, 2, 3, 4]; - let mut c3 = v3.array_chunks::<10>(); - assert_eq!(c3.nth_back(0), None); -} - -#[test] -fn test_array_chunks_last() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let c = v.array_chunks::<2>(); - assert_eq!(c.last().unwrap(), &[4, 5]); - - let v2: &[i32] = &[0, 1, 2, 3, 4]; - let c2 = v2.array_chunks::<2>(); - assert_eq!(c2.last().unwrap(), &[2, 3]); -} - -#[test] -fn test_array_chunks_remainder() { - let v: &[i32] = &[0, 1, 2, 3, 4]; - let c = v.array_chunks::<2>(); - assert_eq!(c.remainder(), &[4]); -} - -#[test] -fn test_array_chunks_zip() { - let v1: &[i32] = &[0, 1, 2, 3, 4]; - let v2: &[i32] = &[6, 7, 8, 9, 10]; - - let res = v1 - .array_chunks::<2>() - .zip(v2.array_chunks::<2>()) - .map(|(a, b)| a.iter().sum::() + b.iter().sum::()) - .collect::>(); - assert_eq!(res, vec![14, 22]); -} - -#[test] -fn test_array_chunks_mut_infer() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4, 5, 6]; - for a in v.array_chunks_mut() { - let sum = a.iter().sum::(); - *a = [sum; 3]; - } - assert_eq!(v, &[3, 3, 3, 12, 12, 12, 6]); - - let v2: &mut [i32] = &mut [0, 1, 2, 3, 4, 5, 6]; - v2.array_chunks_mut().for_each(|[a, b]| core::mem::swap(a, b)); - assert_eq!(v2, &[1, 0, 3, 2, 5, 4, 6]); -} - -#[test] -fn test_array_chunks_mut_count() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4, 5]; - let c = v.array_chunks_mut::<3>(); - assert_eq!(c.count(), 2); - - let v2: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let c2 = v2.array_chunks_mut::<2>(); - assert_eq!(c2.count(), 2); - - let v3: &mut [i32] = &mut []; - let c3 = v3.array_chunks_mut::<2>(); - assert_eq!(c3.count(), 0); -} - -#[test] -fn test_array_chunks_mut_nth() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4, 5]; - let mut c = v.array_chunks_mut::<2>(); - assert_eq!(c.nth(1).unwrap(), &[2, 3]); - assert_eq!(c.next().unwrap(), &[4, 5]); - - let v2: &mut [i32] = &mut [0, 1, 2, 3, 4, 5, 6]; - let mut c2 = v2.array_chunks_mut::<3>(); - assert_eq!(c2.nth(1).unwrap(), &[3, 4, 5]); - assert_eq!(c2.next(), None); -} - -#[test] -fn test_array_chunks_mut_nth_back() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4, 5]; - let mut c = v.array_chunks_mut::<2>(); - assert_eq!(c.nth_back(1).unwrap(), &[2, 3]); - assert_eq!(c.next().unwrap(), &[0, 1]); - assert_eq!(c.next(), None); - - let v2: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let mut c2 = v2.array_chunks_mut::<3>(); - assert_eq!(c2.nth_back(0).unwrap(), &[0, 1, 2]); - assert_eq!(c2.next(), None); - assert_eq!(c2.next_back(), None); - - let v3: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let mut c3 = v3.array_chunks_mut::<10>(); - assert_eq!(c3.nth_back(0), None); -} - -#[test] -fn test_array_chunks_mut_last() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4, 5]; - let c = v.array_chunks_mut::<2>(); - assert_eq!(c.last().unwrap(), &[4, 5]); - - let v2: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let c2 = v2.array_chunks_mut::<2>(); - assert_eq!(c2.last().unwrap(), &[2, 3]); -} - -#[test] -fn test_array_chunks_mut_remainder() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let c = v.array_chunks_mut::<2>(); - assert_eq!(c.into_remainder(), &[4]); -} - -#[test] -fn test_array_chunks_mut_zip() { - let v1: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let v2: &[i32] = &[6, 7, 8, 9, 10]; - - for (a, b) in v1.array_chunks_mut::<2>().zip(v2.array_chunks::<2>()) { - let sum = b.iter().sum::(); - for v in a { - *v += sum; - } - } - assert_eq!(v1, [13, 14, 19, 20, 4]); -} - -#[test] -fn test_array_windows_infer() { - let v: &[i32] = &[0, 1, 0, 1]; - assert_eq!(v.array_windows::<2>().count(), 3); - let c = v.array_windows(); - for &[a, b] in c { - assert_eq!(a + b, 1); - } - - let v2: &[i32] = &[0, 1, 2, 3, 4, 5, 6]; - let total = v2.array_windows().map(|&[a, b, c]| a + b + c).sum::(); - assert_eq!(total, 3 + 6 + 9 + 12 + 15); -} - -#[test] -fn test_array_windows_count() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let c = v.array_windows::<3>(); - assert_eq!(c.count(), 4); - - let v2: &[i32] = &[0, 1, 2, 3, 4]; - let c2 = v2.array_windows::<6>(); - assert_eq!(c2.count(), 0); - - let v3: &[i32] = &[]; - let c3 = v3.array_windows::<2>(); - assert_eq!(c3.count(), 0); - - let v4: &[()] = &[(); usize::MAX]; - let c4 = v4.array_windows::<1>(); - assert_eq!(c4.count(), usize::MAX); -} - -#[test] -fn test_array_windows_nth() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let snd = v.array_windows::<4>().nth(1); - assert_eq!(snd, Some(&[1, 2, 3, 4])); - let mut arr_windows = v.array_windows::<2>(); - assert_ne!(arr_windows.nth(0), arr_windows.nth(0)); - let last = v.array_windows::<3>().last(); - assert_eq!(last, Some(&[3, 4, 5])); -} - -#[test] -fn test_array_windows_nth_back() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let snd = v.array_windows::<4>().nth_back(1); - assert_eq!(snd, Some(&[1, 2, 3, 4])); - let mut arr_windows = v.array_windows::<2>(); - assert_ne!(arr_windows.nth_back(0), arr_windows.nth_back(0)); -} - -#[test] -fn test_rchunks_count() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let c = v.rchunks(3); - assert_eq!(c.count(), 2); - - let v2: &[i32] = &[0, 1, 2, 3, 4]; - let c2 = v2.rchunks(2); - assert_eq!(c2.count(), 3); - - let v3: &[i32] = &[]; - let c3 = v3.rchunks(2); - assert_eq!(c3.count(), 0); -} - -#[test] -fn test_rchunks_nth() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let mut c = v.rchunks(2); - assert_eq!(c.nth(1).unwrap(), &[2, 3]); - assert_eq!(c.next().unwrap(), &[0, 1]); - - let v2: &[i32] = &[0, 1, 2, 3, 4]; - let mut c2 = v2.rchunks(3); - assert_eq!(c2.nth(1).unwrap(), &[0, 1]); - assert_eq!(c2.next(), None); -} - -#[test] -fn test_rchunks_nth_back() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let mut c = v.rchunks(2); - assert_eq!(c.nth_back(1).unwrap(), &[2, 3]); - assert_eq!(c.next_back().unwrap(), &[4, 5]); - - let v2: &[i32] = &[0, 1, 2, 3, 4]; - let mut c2 = v2.rchunks(3); - assert_eq!(c2.nth_back(1).unwrap(), &[2, 3, 4]); - assert_eq!(c2.next_back(), None); -} - -#[test] -fn test_rchunks_next() { - let v = [0, 1, 2, 3, 4, 5]; - let mut c = v.rchunks(2); - assert_eq!(c.next().unwrap(), &[4, 5]); - assert_eq!(c.next().unwrap(), &[2, 3]); - assert_eq!(c.next().unwrap(), &[0, 1]); - assert_eq!(c.next(), None); - - let v = [0, 1, 2, 3, 4, 5, 6, 7]; - let mut c = v.rchunks(3); - assert_eq!(c.next().unwrap(), &[5, 6, 7]); - assert_eq!(c.next().unwrap(), &[2, 3, 4]); - assert_eq!(c.next().unwrap(), &[0, 1]); - assert_eq!(c.next(), None); -} - -#[test] -fn test_rchunks_next_back() { - let v = [0, 1, 2, 3, 4, 5]; - let mut c = v.rchunks(2); - assert_eq!(c.next_back().unwrap(), &[0, 1]); - assert_eq!(c.next_back().unwrap(), &[2, 3]); - assert_eq!(c.next_back().unwrap(), &[4, 5]); - assert_eq!(c.next_back(), None); - - let v = [0, 1, 2, 3, 4, 5, 6, 7]; - let mut c = v.rchunks(3); - assert_eq!(c.next_back().unwrap(), &[0, 1]); - assert_eq!(c.next_back().unwrap(), &[2, 3, 4]); - assert_eq!(c.next_back().unwrap(), &[5, 6, 7]); - assert_eq!(c.next_back(), None); -} - -#[test] -fn test_rchunks_last() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let c = v.rchunks(2); - assert_eq!(c.last().unwrap()[1], 1); - - let v2: &[i32] = &[0, 1, 2, 3, 4]; - let c2 = v2.rchunks(2); - assert_eq!(c2.last().unwrap()[0], 0); -} - -#[test] -fn test_rchunks_zip() { - let v1: &[i32] = &[0, 1, 2, 3, 4]; - let v2: &[i32] = &[6, 7, 8, 9, 10]; - - let res = v1 - .rchunks(2) - .zip(v2.rchunks(2)) - .map(|(a, b)| a.iter().sum::() + b.iter().sum::()) - .collect::>(); - assert_eq!(res, vec![26, 18, 6]); -} - -#[test] -fn test_rchunks_mut_count() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4, 5]; - let c = v.rchunks_mut(3); - assert_eq!(c.count(), 2); - - let v2: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let c2 = v2.rchunks_mut(2); - assert_eq!(c2.count(), 3); - - let v3: &mut [i32] = &mut []; - let c3 = v3.rchunks_mut(2); - assert_eq!(c3.count(), 0); -} - -#[test] -fn test_rchunks_mut_nth() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4, 5]; - let mut c = v.rchunks_mut(2); - assert_eq!(c.nth(1).unwrap(), &[2, 3]); - assert_eq!(c.next().unwrap(), &[0, 1]); - - let v2: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let mut c2 = v2.rchunks_mut(3); - assert_eq!(c2.nth(1).unwrap(), &[0, 1]); - assert_eq!(c2.next(), None); -} - -#[test] -fn test_rchunks_mut_nth_back() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4, 5]; - let mut c = v.rchunks_mut(2); - assert_eq!(c.nth_back(1).unwrap(), &[2, 3]); - assert_eq!(c.next_back().unwrap(), &[4, 5]); - - let v2: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let mut c2 = v2.rchunks_mut(3); - assert_eq!(c2.nth_back(1).unwrap(), &[2, 3, 4]); - assert_eq!(c2.next_back(), None); -} - -#[test] -fn test_rchunks_mut_next() { - let mut v = [0, 1, 2, 3, 4, 5]; - let mut c = v.rchunks_mut(2); - assert_eq!(c.next().unwrap(), &mut [4, 5]); - assert_eq!(c.next().unwrap(), &mut [2, 3]); - assert_eq!(c.next().unwrap(), &mut [0, 1]); - assert_eq!(c.next(), None); - - let mut v = [0, 1, 2, 3, 4, 5, 6, 7]; - let mut c = v.rchunks_mut(3); - assert_eq!(c.next().unwrap(), &mut [5, 6, 7]); - assert_eq!(c.next().unwrap(), &mut [2, 3, 4]); - assert_eq!(c.next().unwrap(), &mut [0, 1]); - assert_eq!(c.next(), None); -} - -#[test] -fn test_rchunks_mut_next_back() { - let mut v = [0, 1, 2, 3, 4, 5]; - let mut c = v.rchunks_mut(2); - assert_eq!(c.next_back().unwrap(), &mut [0, 1]); - assert_eq!(c.next_back().unwrap(), &mut [2, 3]); - assert_eq!(c.next_back().unwrap(), &mut [4, 5]); - assert_eq!(c.next_back(), None); - - let mut v = [0, 1, 2, 3, 4, 5, 6, 7]; - let mut c = v.rchunks_mut(3); - assert_eq!(c.next_back().unwrap(), &mut [0, 1]); - assert_eq!(c.next_back().unwrap(), &mut [2, 3, 4]); - assert_eq!(c.next_back().unwrap(), &mut [5, 6, 7]); - assert_eq!(c.next_back(), None); -} - -#[test] -fn test_rchunks_mut_last() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4, 5]; - let c = v.rchunks_mut(2); - assert_eq!(c.last().unwrap(), &[0, 1]); - - let v2: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let c2 = v2.rchunks_mut(2); - assert_eq!(c2.last().unwrap(), &[0]); -} - -#[test] -fn test_rchunks_mut_zip() { - let v1: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let v2: &[i32] = &[6, 7, 8, 9, 10]; - - for (a, b) in v1.rchunks_mut(2).zip(v2.rchunks(2)) { - let sum = b.iter().sum::(); - for v in a { - *v += sum; - } - } - assert_eq!(v1, [6, 16, 17, 22, 23]); -} - -#[test] -fn test_rchunks_exact_count() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let c = v.rchunks_exact(3); - assert_eq!(c.count(), 2); - - let v2: &[i32] = &[0, 1, 2, 3, 4]; - let c2 = v2.rchunks_exact(2); - assert_eq!(c2.count(), 2); - - let v3: &[i32] = &[]; - let c3 = v3.rchunks_exact(2); - assert_eq!(c3.count(), 0); -} - -#[test] -fn test_rchunks_exact_nth() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let mut c = v.rchunks_exact(2); - assert_eq!(c.nth(1).unwrap(), &[2, 3]); - assert_eq!(c.next().unwrap(), &[0, 1]); - - let v2: &[i32] = &[0, 1, 2, 3, 4, 5, 6]; - let mut c2 = v2.rchunks_exact(3); - assert_eq!(c2.nth(1).unwrap(), &[1, 2, 3]); - assert_eq!(c2.next(), None); -} - -#[test] -fn test_rchunks_exact_nth_back() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let mut c = v.rchunks_exact(2); - assert_eq!(c.nth_back(1).unwrap(), &[2, 3]); - assert_eq!(c.next_back().unwrap(), &[4, 5]); - - let v2: &[i32] = &[0, 1, 2, 3, 4, 5, 6]; - let mut c2 = v2.rchunks_exact(3); - assert_eq!(c2.nth_back(1).unwrap(), &[4, 5, 6]); - assert_eq!(c2.next(), None); -} - -#[test] -fn test_rchunks_exact_last() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let c = v.rchunks_exact(2); - assert_eq!(c.last().unwrap(), &[0, 1]); - - let v2: &[i32] = &[0, 1, 2, 3, 4]; - let c2 = v2.rchunks_exact(2); - assert_eq!(c2.last().unwrap(), &[1, 2]); -} - -#[test] -fn test_rchunks_exact_remainder() { - let v: &[i32] = &[0, 1, 2, 3, 4]; - let c = v.rchunks_exact(2); - assert_eq!(c.remainder(), &[0]); -} - -#[test] -fn test_rchunks_exact_zip() { - let v1: &[i32] = &[0, 1, 2, 3, 4]; - let v2: &[i32] = &[6, 7, 8, 9, 10]; - - let res = v1 - .rchunks_exact(2) - .zip(v2.rchunks_exact(2)) - .map(|(a, b)| a.iter().sum::() + b.iter().sum::()) - .collect::>(); - assert_eq!(res, vec![26, 18]); -} - -#[test] -fn test_rchunks_exact_mut_count() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4, 5]; - let c = v.rchunks_exact_mut(3); - assert_eq!(c.count(), 2); - - let v2: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let c2 = v2.rchunks_exact_mut(2); - assert_eq!(c2.count(), 2); - - let v3: &mut [i32] = &mut []; - let c3 = v3.rchunks_exact_mut(2); - assert_eq!(c3.count(), 0); -} - -#[test] -fn test_rchunks_exact_mut_nth() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4, 5]; - let mut c = v.rchunks_exact_mut(2); - assert_eq!(c.nth(1).unwrap(), &[2, 3]); - assert_eq!(c.next().unwrap(), &[0, 1]); - - let v2: &mut [i32] = &mut [0, 1, 2, 3, 4, 5, 6]; - let mut c2 = v2.rchunks_exact_mut(3); - assert_eq!(c2.nth(1).unwrap(), &[1, 2, 3]); - assert_eq!(c2.next(), None); -} - -#[test] -fn test_rchunks_exact_mut_nth_back() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4, 5]; - let mut c = v.rchunks_exact_mut(2); - assert_eq!(c.nth_back(1).unwrap(), &[2, 3]); - assert_eq!(c.next_back().unwrap(), &[4, 5]); - - let v2: &mut [i32] = &mut [0, 1, 2, 3, 4, 5, 6]; - let mut c2 = v2.rchunks_exact_mut(3); - assert_eq!(c2.nth_back(1).unwrap(), &[4, 5, 6]); - assert_eq!(c2.next(), None); -} - -#[test] -fn test_rchunks_exact_mut_last() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4, 5]; - let c = v.rchunks_exact_mut(2); - assert_eq!(c.last().unwrap(), &[0, 1]); - - let v2: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let c2 = v2.rchunks_exact_mut(2); - assert_eq!(c2.last().unwrap(), &[1, 2]); -} - -#[test] -fn test_rchunks_exact_mut_remainder() { - let v: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let c = v.rchunks_exact_mut(2); - assert_eq!(c.into_remainder(), &[0]); -} - -#[test] -fn test_rchunks_exact_mut_zip() { - let v1: &mut [i32] = &mut [0, 1, 2, 3, 4]; - let v2: &[i32] = &[6, 7, 8, 9, 10]; - - for (a, b) in v1.rchunks_exact_mut(2).zip(v2.rchunks_exact(2)) { - let sum = b.iter().sum::(); - for v in a { - *v += sum; - } - } - assert_eq!(v1, [0, 16, 17, 22, 23]); -} - -#[test] -fn chunks_mut_are_send_and_sync() { - use std::cell::Cell; - use std::slice::{ChunksExactMut, ChunksMut, RChunksExactMut, RChunksMut}; - use std::sync::MutexGuard; - - fn assert_send_and_sync() - where - ChunksMut<'static, Cell>: Send, - ChunksMut<'static, MutexGuard<'static, u32>>: Sync, - ChunksExactMut<'static, Cell>: Send, - ChunksExactMut<'static, MutexGuard<'static, u32>>: Sync, - RChunksMut<'static, Cell>: Send, - RChunksMut<'static, MutexGuard<'static, u32>>: Sync, - RChunksExactMut<'static, Cell>: Send, - RChunksExactMut<'static, MutexGuard<'static, u32>>: Sync, - { - } - - assert_send_and_sync(); -} - -#[test] -fn test_windows_count() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let c = v.windows(3); - assert_eq!(c.count(), 4); - - let v2: &[i32] = &[0, 1, 2, 3, 4]; - let c2 = v2.windows(6); - assert_eq!(c2.count(), 0); - - let v3: &[i32] = &[]; - let c3 = v3.windows(2); - assert_eq!(c3.count(), 0); - - let v4 = &[(); usize::MAX]; - let c4 = v4.windows(1); - assert_eq!(c4.count(), usize::MAX); -} - -#[test] -fn test_windows_nth() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let mut c = v.windows(2); - assert_eq!(c.nth(2).unwrap()[1], 3); - assert_eq!(c.next().unwrap()[0], 3); - - let v2: &[i32] = &[0, 1, 2, 3, 4]; - let mut c2 = v2.windows(4); - assert_eq!(c2.nth(1).unwrap()[1], 2); - assert_eq!(c2.next(), None); -} - -#[test] -fn test_windows_nth_back() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let mut c = v.windows(2); - assert_eq!(c.nth_back(2).unwrap()[0], 2); - assert_eq!(c.next_back().unwrap()[1], 2); - - let v2: &[i32] = &[0, 1, 2, 3, 4]; - let mut c2 = v2.windows(4); - assert_eq!(c2.nth_back(1).unwrap()[1], 1); - assert_eq!(c2.next_back(), None); -} - -#[test] -fn test_windows_last() { - let v: &[i32] = &[0, 1, 2, 3, 4, 5]; - let c = v.windows(2); - assert_eq!(c.last().unwrap()[1], 5); - - let v2: &[i32] = &[0, 1, 2, 3, 4]; - let c2 = v2.windows(2); - assert_eq!(c2.last().unwrap()[0], 3); -} - -#[test] -fn test_windows_zip() { - let v1: &[i32] = &[0, 1, 2, 3, 4]; - let v2: &[i32] = &[6, 7, 8, 9, 10]; - - let res = v1 - .windows(2) - .zip(v2.windows(2)) - .map(|(a, b)| a.iter().sum::() + b.iter().sum::()) - .collect::>(); - - assert_eq!(res, [14, 18, 22, 26]); -} - -#[test] -fn test_iter_ref_consistency() { - use std::fmt::Debug; - - fn test(x: T) { - let v: &[T] = &[x, x, x]; - let v_ptrs: [*const T; 3] = match v { - [ref v1, ref v2, ref v3] => [v1 as *const _, v2 as *const _, v3 as *const _], - _ => unreachable!(), - }; - let len = v.len(); - - // nth(i) - for i in 0..len { - assert_eq!(&v[i] as *const _, v_ptrs[i]); // check the v_ptrs array, just to be sure - let nth = v.iter().nth(i).unwrap(); - assert_eq!(nth as *const _, v_ptrs[i]); - } - assert_eq!(v.iter().nth(len), None, "nth(len) should return None"); - - // stepping through with nth(0) - { - let mut it = v.iter(); - for i in 0..len { - let next = it.nth(0).unwrap(); - assert_eq!(next as *const _, v_ptrs[i]); - } - assert_eq!(it.nth(0), None); - } - - // next() - { - let mut it = v.iter(); - for i in 0..len { - let remaining = len - i; - assert_eq!(it.size_hint(), (remaining, Some(remaining))); - - let next = it.next().unwrap(); - assert_eq!(next as *const _, v_ptrs[i]); - } - assert_eq!(it.size_hint(), (0, Some(0))); - assert_eq!(it.next(), None, "The final call to next() should return None"); - } - - // next_back() - { - let mut it = v.iter(); - for i in 0..len { - let remaining = len - i; - assert_eq!(it.size_hint(), (remaining, Some(remaining))); - - let prev = it.next_back().unwrap(); - assert_eq!(prev as *const _, v_ptrs[remaining - 1]); - } - assert_eq!(it.size_hint(), (0, Some(0))); - assert_eq!(it.next_back(), None, "The final call to next_back() should return None"); - } - } - - fn test_mut(x: T) { - let v: &mut [T] = &mut [x, x, x]; - let v_ptrs: [*mut T; 3] = match v { - [ref v1, ref v2, ref v3] => { - [v1 as *const _ as *mut _, v2 as *const _ as *mut _, v3 as *const _ as *mut _] - } - _ => unreachable!(), - }; - let len = v.len(); - - // nth(i) - for i in 0..len { - assert_eq!(&mut v[i] as *mut _, v_ptrs[i]); // check the v_ptrs array, just to be sure - let nth = v.iter_mut().nth(i).unwrap(); - assert_eq!(nth as *mut _, v_ptrs[i]); - } - assert_eq!(v.iter().nth(len), None, "nth(len) should return None"); - - // stepping through with nth(0) - { - let mut it = v.iter(); - for i in 0..len { - let next = it.nth(0).unwrap(); - assert_eq!(next as *const _, v_ptrs[i]); - } - assert_eq!(it.nth(0), None); - } - - // next() - { - let mut it = v.iter_mut(); - for i in 0..len { - let remaining = len - i; - assert_eq!(it.size_hint(), (remaining, Some(remaining))); - - let next = it.next().unwrap(); - assert_eq!(next as *mut _, v_ptrs[i]); - } - assert_eq!(it.size_hint(), (0, Some(0))); - assert_eq!(it.next(), None, "The final call to next() should return None"); - } - - // next_back() - { - let mut it = v.iter_mut(); - for i in 0..len { - let remaining = len - i; - assert_eq!(it.size_hint(), (remaining, Some(remaining))); - - let prev = it.next_back().unwrap(); - assert_eq!(prev as *mut _, v_ptrs[remaining - 1]); - } - assert_eq!(it.size_hint(), (0, Some(0))); - assert_eq!(it.next_back(), None, "The final call to next_back() should return None"); - } - } - - // Make sure iterators and slice patterns yield consistent addresses for various types, - // including ZSTs. - test(0u32); - test(()); - test([0u32; 0]); // ZST with alignment > 0 - test_mut(0u32); - test_mut(()); - test_mut([0u32; 0]); // ZST with alignment > 0 -} - -// The current implementation of SliceIndex fails to handle methods -// orthogonally from range types; therefore, it is worth testing -// all of the indexing operations on each input. -mod slice_index { - // This checks all six indexing methods, given an input range that - // should succeed. (it is NOT suitable for testing invalid inputs) - macro_rules! assert_range_eq { - ($arr:expr, $range:expr, $expected:expr) => { - let mut arr = $arr; - let mut expected = $expected; - { - let s: &[_] = &arr; - let expected: &[_] = &expected; - - assert_eq!(&s[$range], expected, "(in assertion for: index)"); - assert_eq!(s.get($range), Some(expected), "(in assertion for: get)"); - unsafe { - assert_eq!( - s.get_unchecked($range), - expected, - "(in assertion for: get_unchecked)", - ); - } - } - { - let s: &mut [_] = &mut arr; - let expected: &mut [_] = &mut expected; - - assert_eq!(&mut s[$range], expected, "(in assertion for: index_mut)",); - assert_eq!( - s.get_mut($range), - Some(&mut expected[..]), - "(in assertion for: get_mut)", - ); - unsafe { - assert_eq!( - s.get_unchecked_mut($range), - expected, - "(in assertion for: get_unchecked_mut)", - ); - } - } - }; - } - - // Make sure the macro can actually detect bugs, - // because if it can't, then what are we even doing here? - // - // (Be aware this only demonstrates the ability to detect bugs - // in the FIRST method that panics, as the macro is not designed - // to be used in `should_panic`) - #[test] - #[should_panic(expected = "out of range")] - fn assert_range_eq_can_fail_by_panic() { - assert_range_eq!([0, 1, 2], 0..5, [0, 1, 2]); - } - - // (Be aware this only demonstrates the ability to detect bugs - // in the FIRST method it calls, as the macro is not designed - // to be used in `should_panic`) - #[test] - #[should_panic(expected = "==")] - fn assert_range_eq_can_fail_by_inequality() { - assert_range_eq!([0, 1, 2], 0..2, [0, 1, 2]); - } - - // Test cases for bad index operations. - // - // This generates `should_panic` test cases for Index/IndexMut - // and `None` test cases for get/get_mut. - macro_rules! panic_cases { - ($( - // each test case needs a unique name to namespace the tests - in mod $case_name:ident { - data: $data:expr; - - // optional: - // - // one or more similar inputs for which data[input] succeeds, - // and the corresponding output as an array. This helps validate - // "critical points" where an input range straddles the boundary - // between valid and invalid. - // (such as the input `len..len`, which is just barely valid) - $( - good: data[$good:expr] == $output:expr; - )* - - bad: data[$bad:expr]; - message: $expect_msg:expr; - } - )*) => {$( - mod $case_name { - #[allow(unused_imports)] - use core::ops::Bound; - - #[test] - fn pass() { - let mut v = $data; - - $( assert_range_eq!($data, $good, $output); )* - - { - let v: &[_] = &v; - assert_eq!(v.get($bad), None, "(in None assertion for get)"); - } - - { - let v: &mut [_] = &mut v; - assert_eq!(v.get_mut($bad), None, "(in None assertion for get_mut)"); - } - } - - #[test] - #[should_panic(expected = $expect_msg)] - fn index_fail() { - let v = $data; - let v: &[_] = &v; - let _v = &v[$bad]; - } - - #[test] - #[should_panic(expected = $expect_msg)] - fn index_mut_fail() { - let mut v = $data; - let v: &mut [_] = &mut v; - let _v = &mut v[$bad]; - } - } - )*}; - } - - #[test] - fn simple() { - let v = [0, 1, 2, 3, 4, 5]; - - assert_range_eq!(v, .., [0, 1, 2, 3, 4, 5]); - assert_range_eq!(v, ..2, [0, 1]); - assert_range_eq!(v, ..=1, [0, 1]); - assert_range_eq!(v, 2.., [2, 3, 4, 5]); - assert_range_eq!(v, 1..4, [1, 2, 3]); - assert_range_eq!(v, 1..=3, [1, 2, 3]); - } - - panic_cases! { - in mod rangefrom_len { - data: [0, 1, 2, 3, 4, 5]; - - good: data[6..] == []; - bad: data[7..]; - message: "out of range"; - } - - in mod rangeto_len { - data: [0, 1, 2, 3, 4, 5]; - - good: data[..6] == [0, 1, 2, 3, 4, 5]; - bad: data[..7]; - message: "out of range"; - } - - in mod rangetoinclusive_len { - data: [0, 1, 2, 3, 4, 5]; - - good: data[..=5] == [0, 1, 2, 3, 4, 5]; - bad: data[..=6]; - message: "out of range"; - } - - in mod rangeinclusive_len { - data: [0, 1, 2, 3, 4, 5]; - - good: data[0..=5] == [0, 1, 2, 3, 4, 5]; - bad: data[0..=6]; - message: "out of range"; - } - - in mod range_len_len { - data: [0, 1, 2, 3, 4, 5]; - - good: data[6..6] == []; - bad: data[7..7]; - message: "out of range"; - } - - in mod rangeinclusive_len_len { - data: [0, 1, 2, 3, 4, 5]; - - good: data[6..=5] == []; - bad: data[7..=6]; - message: "out of range"; - } - - in mod boundpair_len { - data: [0, 1, 2, 3, 4, 5]; - - good: data[(Bound::Included(6), Bound::Unbounded)] == []; - good: data[(Bound::Unbounded, Bound::Included(5))] == [0, 1, 2, 3, 4, 5]; - good: data[(Bound::Unbounded, Bound::Excluded(6))] == [0, 1, 2, 3, 4, 5]; - good: data[(Bound::Included(0), Bound::Included(5))] == [0, 1, 2, 3, 4, 5]; - good: data[(Bound::Included(0), Bound::Excluded(6))] == [0, 1, 2, 3, 4, 5]; - good: data[(Bound::Included(2), Bound::Excluded(4))] == [2, 3]; - good: data[(Bound::Excluded(1), Bound::Included(4))] == [2, 3, 4]; - good: data[(Bound::Excluded(5), Bound::Excluded(6))] == []; - good: data[(Bound::Included(6), Bound::Excluded(6))] == []; - good: data[(Bound::Excluded(5), Bound::Included(5))] == []; - good: data[(Bound::Included(6), Bound::Included(5))] == []; - bad: data[(Bound::Unbounded, Bound::Included(6))]; - message: "out of range"; - } - } - - panic_cases! { - in mod rangeinclusive_exhausted { - data: [0, 1, 2, 3, 4, 5]; - - good: data[0..=5] == [0, 1, 2, 3, 4, 5]; - good: data[{ - let mut iter = 0..=5; - iter.by_ref().count(); // exhaust it - iter - }] == []; - - // 0..=6 is out of range before exhaustion, so it - // stands to reason that it still would be after. - bad: data[{ - let mut iter = 0..=6; - iter.by_ref().count(); // exhaust it - iter - }]; - message: "out of range"; - } - } - - panic_cases! { - in mod range_neg_width { - data: [0, 1, 2, 3, 4, 5]; - - good: data[4..4] == []; - bad: data[4..3]; - message: "but ends at"; - } - - in mod rangeinclusive_neg_width { - data: [0, 1, 2, 3, 4, 5]; - - good: data[4..=3] == []; - bad: data[4..=2]; - message: "but ends at"; - } - - in mod boundpair_neg_width { - data: [0, 1, 2, 3, 4, 5]; - - good: data[(Bound::Included(4), Bound::Excluded(4))] == []; - bad: data[(Bound::Included(4), Bound::Excluded(3))]; - message: "but ends at"; - } - } - - panic_cases! { - in mod rangeinclusive_overflow { - data: [0, 1]; - - // note: using 0 specifically ensures that the result of overflowing is 0..0, - // so that `get` doesn't simply return None for the wrong reason. - bad: data[0 ..= usize::MAX]; - message: "maximum usize"; - } - - in mod rangetoinclusive_overflow { - data: [0, 1]; - - bad: data[..= usize::MAX]; - message: "maximum usize"; - } - - in mod boundpair_overflow_end { - data: [0; 1]; - - bad: data[(Bound::Unbounded, Bound::Included(usize::MAX))]; - message: "maximum usize"; - } - - in mod boundpair_overflow_start { - data: [0; 1]; - - bad: data[(Bound::Excluded(usize::MAX), Bound::Unbounded)]; - message: "maximum usize"; - } - } // panic_cases! -} - -#[test] -fn test_find_rfind() { - let v = [0, 1, 2, 3, 4, 5]; - let mut iter = v.iter(); - let mut i = v.len(); - while let Some(&elt) = iter.rfind(|_| true) { - i -= 1; - assert_eq!(elt, v[i]); - } - assert_eq!(i, 0); - assert_eq!(v.iter().rfind(|&&x| x <= 3), Some(&3)); -} - -#[test] -fn test_iter_folds() { - let a = [1, 2, 3, 4, 5]; // len>4 so the unroll is used - assert_eq!(a.iter().fold(0, |acc, &x| 2 * acc + x), 57); - assert_eq!(a.iter().rfold(0, |acc, &x| 2 * acc + x), 129); - let fold = |acc: i32, &x| acc.checked_mul(2)?.checked_add(x); - assert_eq!(a.iter().try_fold(0, &fold), Some(57)); - assert_eq!(a.iter().try_rfold(0, &fold), Some(129)); - - // short-circuiting try_fold, through other methods - let a = [0, 1, 2, 3, 5, 5, 5, 7, 8, 9]; - let mut iter = a.iter(); - assert_eq!(iter.position(|&x| x == 3), Some(3)); - assert_eq!(iter.rfind(|&&x| x == 5), Some(&5)); - assert_eq!(iter.len(), 2); -} - -#[test] -fn test_rotate_left() { - const N: usize = 600; - let a: &mut [_] = &mut [0; N]; - for i in 0..N { - a[i] = i; - } - - a.rotate_left(42); - let k = N - 42; - - for i in 0..N { - assert_eq!(a[(i + k) % N], i); - } -} - -#[test] -fn test_rotate_right() { - const N: usize = 600; - let a: &mut [_] = &mut [0; N]; - for i in 0..N { - a[i] = i; - } - - a.rotate_right(42); - - for i in 0..N { - assert_eq!(a[(i + 42) % N], i); - } -} - -#[test] -#[cfg_attr(miri, ignore)] // Miri is too slow -fn brute_force_rotate_test_0() { - // In case of edge cases involving multiple algorithms - let n = 300; - for len in 0..n { - for s in 0..len { - let mut v = Vec::with_capacity(len); - for i in 0..len { - v.push(i); - } - v[..].rotate_right(s); - for i in 0..v.len() { - assert_eq!(v[i], v.len().wrapping_add(i.wrapping_sub(s)) % v.len()); - } - } - } -} - -#[test] -fn brute_force_rotate_test_1() { - // `ptr_rotate` covers so many kinds of pointer usage, that this is just a good test for - // pointers in general. This uses a `[usize; 4]` to hit all algorithms without overwhelming miri - let n = 30; - for len in 0..n { - for s in 0..len { - let mut v: Vec<[usize; 4]> = Vec::with_capacity(len); - for i in 0..len { - v.push([i, 0, 0, 0]); - } - v[..].rotate_right(s); - for i in 0..v.len() { - assert_eq!(v[i][0], v.len().wrapping_add(i.wrapping_sub(s)) % v.len()); - } - } - } -} - -#[test] -#[cfg(not(target_arch = "wasm32"))] -fn sort_unstable() { - use core::cmp::Ordering::{Equal, Greater, Less}; - use core::slice::heapsort; - use rand::{seq::SliceRandom, Rng}; - - // Miri is too slow (but still need to `chain` to make the types match) - let lens = if cfg!(miri) { (2..20).chain(0..0) } else { (2..25).chain(500..510) }; - let rounds = if cfg!(miri) { 1 } else { 100 }; - - let mut v = [0; 600]; - let mut tmp = [0; 600]; - let mut rng = crate::test_rng(); - - for len in lens { - let v = &mut v[0..len]; - let tmp = &mut tmp[0..len]; - - for &modulus in &[5, 10, 100, 1000] { - for _ in 0..rounds { - for i in 0..len { - v[i] = rng.gen::() % modulus; - } - - // Sort in default order. - tmp.copy_from_slice(v); - tmp.sort_unstable(); - assert!(tmp.windows(2).all(|w| w[0] <= w[1])); - - // Sort in ascending order. - tmp.copy_from_slice(v); - tmp.sort_unstable_by(|a, b| a.cmp(b)); - assert!(tmp.windows(2).all(|w| w[0] <= w[1])); - - // Sort in descending order. - tmp.copy_from_slice(v); - tmp.sort_unstable_by(|a, b| b.cmp(a)); - assert!(tmp.windows(2).all(|w| w[0] >= w[1])); - - // Test heapsort using `<` operator. - tmp.copy_from_slice(v); - heapsort(tmp, |a, b| a < b); - assert!(tmp.windows(2).all(|w| w[0] <= w[1])); - - // Test heapsort using `>` operator. - tmp.copy_from_slice(v); - heapsort(tmp, |a, b| a > b); - assert!(tmp.windows(2).all(|w| w[0] >= w[1])); - } - } - } - - // Sort using a completely random comparison function. - // This will reorder the elements *somehow*, but won't panic. - for i in 0..v.len() { - v[i] = i as i32; - } - v.sort_unstable_by(|_, _| *[Less, Equal, Greater].choose(&mut rng).unwrap()); - v.sort_unstable(); - for i in 0..v.len() { - assert_eq!(v[i], i as i32); - } - - // Should not panic. - [0i32; 0].sort_unstable(); - [(); 10].sort_unstable(); - [(); 100].sort_unstable(); - - let mut v = [0xDEADBEEFu64]; - v.sort_unstable(); - assert!(v == [0xDEADBEEF]); -} - -#[test] -#[cfg(not(target_arch = "wasm32"))] -#[cfg_attr(miri, ignore)] // Miri is too slow -fn select_nth_unstable() { - use core::cmp::Ordering::{Equal, Greater, Less}; - use rand::seq::SliceRandom; - use rand::Rng; - - let mut rng = crate::test_rng(); - - for len in (2..21).chain(500..501) { - let mut orig = vec![0; len]; - - for &modulus in &[5, 10, 1000] { - for _ in 0..10 { - for i in 0..len { - orig[i] = rng.gen::() % modulus; - } - - let v_sorted = { - let mut v = orig.clone(); - v.sort(); - v - }; - - // Sort in default order. - for pivot in 0..len { - let mut v = orig.clone(); - v.select_nth_unstable(pivot); - - assert_eq!(v_sorted[pivot], v[pivot]); - for i in 0..pivot { - for j in pivot..len { - assert!(v[i] <= v[j]); - } - } - } - - // Sort in ascending order. - for pivot in 0..len { - let mut v = orig.clone(); - let (left, pivot, right) = v.select_nth_unstable_by(pivot, |a, b| a.cmp(b)); - - assert_eq!(left.len() + right.len(), len - 1); - - for l in left { - assert!(l <= pivot); - for r in right.iter_mut() { - assert!(l <= r); - assert!(pivot <= r); - } - } - } - - // Sort in descending order. - let sort_descending_comparator = |a: &i32, b: &i32| b.cmp(a); - let v_sorted_descending = { - let mut v = orig.clone(); - v.sort_by(sort_descending_comparator); - v - }; - - for pivot in 0..len { - let mut v = orig.clone(); - v.select_nth_unstable_by(pivot, sort_descending_comparator); - - assert_eq!(v_sorted_descending[pivot], v[pivot]); - for i in 0..pivot { - for j in pivot..len { - assert!(v[j] <= v[i]); - } - } - } - } - } - } - - // Sort at index using a completely random comparison function. - // This will reorder the elements *somehow*, but won't panic. - let mut v = [0; 500]; - for i in 0..v.len() { - v[i] = i as i32; - } - - for pivot in 0..v.len() { - v.select_nth_unstable_by(pivot, |_, _| *[Less, Equal, Greater].choose(&mut rng).unwrap()); - v.sort(); - for i in 0..v.len() { - assert_eq!(v[i], i as i32); - } - } - - // Should not panic. - [(); 10].select_nth_unstable(0); - [(); 10].select_nth_unstable(5); - [(); 10].select_nth_unstable(9); - [(); 100].select_nth_unstable(0); - [(); 100].select_nth_unstable(50); - [(); 100].select_nth_unstable(99); - - let mut v = [0xDEADBEEFu64]; - v.select_nth_unstable(0); - assert!(v == [0xDEADBEEF]); -} - -#[test] -#[should_panic(expected = "index 0 greater than length of slice")] -fn select_nth_unstable_zero_length() { - [0i32; 0].select_nth_unstable(0); -} - -#[test] -#[should_panic(expected = "index 20 greater than length of slice")] -fn select_nth_unstable_past_length() { - [0i32; 10].select_nth_unstable(20); -} - -pub mod memchr { - use core::slice::memchr::{memchr, memrchr}; - - // test fallback implementations on all platforms - #[test] - fn matches_one() { - assert_eq!(Some(0), memchr(b'a', b"a")); - } - - #[test] - fn matches_begin() { - assert_eq!(Some(0), memchr(b'a', b"aaaa")); - } - - #[test] - fn matches_end() { - assert_eq!(Some(4), memchr(b'z', b"aaaaz")); - } - - #[test] - fn matches_nul() { - assert_eq!(Some(4), memchr(b'\x00', b"aaaa\x00")); - } - - #[test] - fn matches_past_nul() { - assert_eq!(Some(5), memchr(b'z', b"aaaa\x00z")); - } - - #[test] - fn no_match_empty() { - assert_eq!(None, memchr(b'a', b"")); - } - - #[test] - fn no_match() { - assert_eq!(None, memchr(b'a', b"xyz")); - } - - #[test] - fn matches_one_reversed() { - assert_eq!(Some(0), memrchr(b'a', b"a")); - } - - #[test] - fn matches_begin_reversed() { - assert_eq!(Some(3), memrchr(b'a', b"aaaa")); - } - - #[test] - fn matches_end_reversed() { - assert_eq!(Some(0), memrchr(b'z', b"zaaaa")); - } - - #[test] - fn matches_nul_reversed() { - assert_eq!(Some(4), memrchr(b'\x00', b"aaaa\x00")); - } - - #[test] - fn matches_past_nul_reversed() { - assert_eq!(Some(0), memrchr(b'z', b"z\x00aaaa")); - } - - #[test] - fn no_match_empty_reversed() { - assert_eq!(None, memrchr(b'a', b"")); - } - - #[test] - fn no_match_reversed() { - assert_eq!(None, memrchr(b'a', b"xyz")); - } - - #[test] - fn each_alignment_reversed() { - let mut data = [1u8; 64]; - let needle = 2; - let pos = 40; - data[pos] = needle; - for start in 0..16 { - assert_eq!(Some(pos - start), memrchr(needle, &data[start..])); - } - } -} - -#[test] -fn test_align_to_simple() { - let bytes = [1u8, 2, 3, 4, 5, 6, 7]; - let (prefix, aligned, suffix) = unsafe { bytes.align_to::() }; - assert_eq!(aligned.len(), 3); - assert!(prefix == [1] || suffix == [7]); - let expect1 = [1 << 8 | 2, 3 << 8 | 4, 5 << 8 | 6]; - let expect2 = [1 | 2 << 8, 3 | 4 << 8, 5 | 6 << 8]; - let expect3 = [2 << 8 | 3, 4 << 8 | 5, 6 << 8 | 7]; - let expect4 = [2 | 3 << 8, 4 | 5 << 8, 6 | 7 << 8]; - assert!( - aligned == expect1 || aligned == expect2 || aligned == expect3 || aligned == expect4, - "aligned={:?} expected={:?} || {:?} || {:?} || {:?}", - aligned, - expect1, - expect2, - expect3, - expect4 - ); -} - -#[test] -fn test_align_to_zst() { - let bytes = [1, 2, 3, 4, 5, 6, 7]; - let (prefix, aligned, suffix) = unsafe { bytes.align_to::<()>() }; - assert_eq!(aligned.len(), 0); - assert!(prefix == [1, 2, 3, 4, 5, 6, 7] || suffix == [1, 2, 3, 4, 5, 6, 7]); -} - -#[test] -fn test_align_to_non_trivial() { - #[repr(align(8))] - struct U64(#[allow(dead_code)] u64, #[allow(dead_code)] u64); - #[repr(align(8))] - struct U64U64U32(#[allow(dead_code)] u64, #[allow(dead_code)] u64, #[allow(dead_code)] u32); - let data = [ - U64(1, 2), - U64(3, 4), - U64(5, 6), - U64(7, 8), - U64(9, 10), - U64(11, 12), - U64(13, 14), - U64(15, 16), - ]; - let (prefix, aligned, suffix) = unsafe { data.align_to::() }; - assert_eq!(aligned.len(), 4); - assert_eq!(prefix.len() + suffix.len(), 2); -} - -#[test] -fn test_align_to_empty_mid() { - use core::mem; - - // Make sure that we do not create empty unaligned slices for the mid part, even when the - // overall slice is too short to contain an aligned address. - let bytes = [1, 2, 3, 4, 5, 6, 7]; - type Chunk = u32; - for offset in 0..4 { - let (_, mid, _) = unsafe { bytes[offset..offset + 1].align_to::() }; - assert_eq!(mid.as_ptr() as usize % mem::align_of::(), 0); - } -} - -#[test] -fn test_align_to_mut_aliasing() { - let mut val = [1u8, 2, 3, 4, 5]; - // `align_to_mut` used to create `mid` in a way that there was some intermediate - // incorrect aliasing, invalidating the resulting `mid` slice. - let (begin, mid, end) = unsafe { val.align_to_mut::<[u8; 2]>() }; - assert!(begin.len() == 0); - assert!(end.len() == 1); - mid[0] = mid[1]; - assert_eq!(val, [3, 4, 3, 4, 5]) -} - -#[test] -fn test_slice_partition_dedup_by() { - let mut slice: [i32; 9] = [1, -1, 2, 3, 1, -5, 5, -2, 2]; - - let (dedup, duplicates) = slice.partition_dedup_by(|a, b| a.abs() == b.abs()); - - assert_eq!(dedup, [1, 2, 3, 1, -5, -2]); - assert_eq!(duplicates, [5, -1, 2]); -} - -#[test] -fn test_slice_partition_dedup_empty() { - let mut slice: [i32; 0] = []; - - let (dedup, duplicates) = slice.partition_dedup(); - - assert_eq!(dedup, []); - assert_eq!(duplicates, []); -} - -#[test] -fn test_slice_partition_dedup_one() { - let mut slice = [12]; - - let (dedup, duplicates) = slice.partition_dedup(); - - assert_eq!(dedup, [12]); - assert_eq!(duplicates, []); -} - -#[test] -fn test_slice_partition_dedup_multiple_ident() { - let mut slice = [12, 12, 12, 12, 12, 11, 11, 11, 11, 11, 11]; - - let (dedup, duplicates) = slice.partition_dedup(); - - assert_eq!(dedup, [12, 11]); - assert_eq!(duplicates, [12, 12, 12, 12, 11, 11, 11, 11, 11]); -} - -#[test] -fn test_slice_partition_dedup_partialeq() { - #[derive(Debug)] - struct Foo(i32, #[allow(dead_code)] i32); - - impl PartialEq for Foo { - fn eq(&self, other: &Foo) -> bool { - self.0 == other.0 - } - } - - let mut slice = [Foo(0, 1), Foo(0, 5), Foo(1, 7), Foo(1, 9)]; - - let (dedup, duplicates) = slice.partition_dedup(); - - assert_eq!(dedup, [Foo(0, 1), Foo(1, 7)]); - assert_eq!(duplicates, [Foo(0, 5), Foo(1, 9)]); -} - -#[test] -fn test_copy_within() { - // Start to end, with a RangeTo. - let mut bytes = *b"Hello, World!"; - bytes.copy_within(..3, 10); - assert_eq!(&bytes, b"Hello, WorHel"); - - // End to start, with a RangeFrom. - let mut bytes = *b"Hello, World!"; - bytes.copy_within(10.., 0); - assert_eq!(&bytes, b"ld!lo, World!"); - - // Overlapping, with a RangeInclusive. - let mut bytes = *b"Hello, World!"; - bytes.copy_within(0..=11, 1); - assert_eq!(&bytes, b"HHello, World"); - - // Whole slice, with a RangeFull. - let mut bytes = *b"Hello, World!"; - bytes.copy_within(.., 0); - assert_eq!(&bytes, b"Hello, World!"); - - // Ensure that copying at the end of slice won't cause UB. - let mut bytes = *b"Hello, World!"; - bytes.copy_within(13..13, 5); - assert_eq!(&bytes, b"Hello, World!"); - bytes.copy_within(5..5, 13); - assert_eq!(&bytes, b"Hello, World!"); -} - -#[test] -#[should_panic(expected = "range end index 14 out of range for slice of length 13")] -fn test_copy_within_panics_src_too_long() { - let mut bytes = *b"Hello, World!"; - // The length is only 13, so 14 is out of bounds. - bytes.copy_within(10..14, 0); -} - -#[test] -#[should_panic(expected = "dest is out of bounds")] -fn test_copy_within_panics_dest_too_long() { - let mut bytes = *b"Hello, World!"; - // The length is only 13, so a slice of length 4 starting at index 10 is out of bounds. - bytes.copy_within(0..4, 10); -} - -#[test] -#[should_panic(expected = "slice index starts at 2 but ends at 1")] -fn test_copy_within_panics_src_inverted() { - let mut bytes = *b"Hello, World!"; - // 2 is greater than 1, so this range is invalid. - bytes.copy_within(2..1, 0); -} -#[test] -#[should_panic(expected = "attempted to index slice up to maximum usize")] -fn test_copy_within_panics_src_out_of_bounds() { - let mut bytes = *b"Hello, World!"; - // an inclusive range ending at usize::MAX would make src_end overflow - bytes.copy_within(usize::MAX..=usize::MAX, 0); -} - -#[test] -fn test_is_sorted() { - let empty: [i32; 0] = []; - - // Tests on integers - assert!([1, 2, 2, 9].is_sorted()); - assert!(![1, 3, 2].is_sorted()); - assert!([0].is_sorted()); - assert!([0, 0].is_sorted()); - assert!(empty.is_sorted()); - - // Tests on floats - assert!([1.0f32, 2.0, 2.0, 9.0].is_sorted()); - assert!(![1.0f32, 3.0f32, 2.0f32].is_sorted()); - assert!([0.0f32].is_sorted()); - assert!([0.0f32, 0.0f32].is_sorted()); - // Test cases with NaNs - assert!([f32::NAN].is_sorted()); - assert!(![f32::NAN, f32::NAN].is_sorted()); - assert!(![0.0, 1.0, f32::NAN].is_sorted()); - // Tests from - assert!(![f32::NAN, f32::NAN, f32::NAN].is_sorted()); - assert!(![1.0, f32::NAN, 2.0].is_sorted()); - assert!(![2.0, f32::NAN, 1.0].is_sorted()); - assert!(![2.0, f32::NAN, 1.0, 7.0].is_sorted()); - assert!(![2.0, f32::NAN, 1.0, 0.0].is_sorted()); - assert!(![-f32::NAN, -1.0, 0.0, 1.0, f32::NAN].is_sorted()); - assert!(![f32::NAN, -f32::NAN, -1.0, 0.0, 1.0].is_sorted()); - assert!(![1.0, f32::NAN, -f32::NAN, -1.0, 0.0].is_sorted()); - assert!(![0.0, 1.0, f32::NAN, -f32::NAN, -1.0].is_sorted()); - assert!(![-1.0, 0.0, 1.0, f32::NAN, -f32::NAN].is_sorted()); - - // Tests for is_sorted_by - assert!(![6, 2, 8, 5, 1, -60, 1337].is_sorted()); - assert!([6, 2, 8, 5, 1, -60, 1337].is_sorted_by(|_, _| true)); - - // Tests for is_sorted_by_key - assert!([-2, -1, 0, 3].is_sorted()); - assert!(![-2i32, -1, 0, 3].is_sorted_by_key(|n| n.abs())); - assert!(!["c", "bb", "aaa"].is_sorted()); - assert!(["c", "bb", "aaa"].is_sorted_by_key(|s| s.len())); -} - -#[test] -fn test_slice_run_destructors() { - // Make sure that destructors get run on slice literals - struct Foo<'a> { - x: &'a Cell, - } - - impl<'a> Drop for Foo<'a> { - fn drop(&mut self) { - self.x.set(self.x.get() + 1); - } - } - - fn foo(x: &Cell) -> Foo<'_> { - Foo { x } - } - - let x = &Cell::new(0); - - { - let l = &[foo(x)]; - assert_eq!(l[0].x.get(), 0); - } - - assert_eq!(x.get(), 1); -} - -#[test] -fn test_const_from_ref() { - const VALUE: &i32 = &1; - const SLICE: &[i32] = core::slice::from_ref(VALUE); - - assert!(core::ptr::eq(VALUE, &SLICE[0])) -} - -#[test] -fn test_slice_fill_with_uninit() { - // This should not UB. See #87891 - let mut a = [MaybeUninit::::uninit(); 10]; - a.fill(MaybeUninit::uninit()); -} - -#[test] -fn test_swap() { - let mut x = ["a", "b", "c", "d"]; - x.swap(1, 3); - assert_eq!(x, ["a", "d", "c", "b"]); - x.swap(0, 3); - assert_eq!(x, ["b", "d", "c", "a"]); -} - -mod swap_panics { - #[test] - #[should_panic(expected = "index out of bounds: the len is 4 but the index is 4")] - fn index_a_equals_len() { - let mut x = ["a", "b", "c", "d"]; - x.swap(4, 2); - } - - #[test] - #[should_panic(expected = "index out of bounds: the len is 4 but the index is 4")] - fn index_b_equals_len() { - let mut x = ["a", "b", "c", "d"]; - x.swap(2, 4); - } - - #[test] - #[should_panic(expected = "index out of bounds: the len is 4 but the index is 5")] - fn index_a_greater_than_len() { - let mut x = ["a", "b", "c", "d"]; - x.swap(5, 2); - } - - #[test] - #[should_panic(expected = "index out of bounds: the len is 4 but the index is 5")] - fn index_b_greater_than_len() { - let mut x = ["a", "b", "c", "d"]; - x.swap(2, 5); - } -} - -#[test] -fn slice_split_first_chunk_mut() { - let v = &mut [1, 2, 3, 4, 5, 6][..]; - - { - let (left, right) = v.split_first_chunk_mut::<0>().unwrap(); - assert_eq!(left, &mut []); - assert_eq!(right, [1, 2, 3, 4, 5, 6]); - } - - { - let (left, right) = v.split_first_chunk_mut::<6>().unwrap(); - assert_eq!(left, &mut [1, 2, 3, 4, 5, 6]); - assert_eq!(right, []); - } - - { - assert!(v.split_first_chunk_mut::<7>().is_none()); - } -} - -#[test] -fn slice_split_last_chunk_mut() { - let v = &mut [1, 2, 3, 4, 5, 6][..]; - - { - let (left, right) = v.split_last_chunk_mut::<0>().unwrap(); - assert_eq!(left, [1, 2, 3, 4, 5, 6]); - assert_eq!(right, &mut []); - } - - { - let (left, right) = v.split_last_chunk_mut::<6>().unwrap(); - assert_eq!(left, []); - assert_eq!(right, &mut [1, 2, 3, 4, 5, 6]); - } - - { - assert!(v.split_last_chunk_mut::<7>().is_none()); - } -} - -#[test] -fn split_as_slice() { - let arr = [1, 2, 3, 4, 5, 6]; - let mut split = arr.split(|v| v % 2 == 0); - assert_eq!(split.as_slice(), &[1, 2, 3, 4, 5, 6]); - assert!(split.next().is_some()); - assert_eq!(split.as_slice(), &[3, 4, 5, 6]); - assert!(split.next().is_some()); - assert!(split.next().is_some()); - assert_eq!(split.as_slice(), &[]); -} - -#[test] -fn slice_split_once() { - let v = &[1, 2, 3, 2, 4][..]; - - assert_eq!(v.split_once(|&x| x == 2), Some((&[1][..], &[3, 2, 4][..]))); - assert_eq!(v.split_once(|&x| x == 1), Some((&[][..], &[2, 3, 2, 4][..]))); - assert_eq!(v.split_once(|&x| x == 4), Some((&[1, 2, 3, 2][..], &[][..]))); - assert_eq!(v.split_once(|&x| x == 0), None); -} - -#[test] -fn slice_rsplit_once() { - let v = &[1, 2, 3, 2, 4][..]; - - assert_eq!(v.rsplit_once(|&x| x == 2), Some((&[1, 2, 3][..], &[4][..]))); - assert_eq!(v.rsplit_once(|&x| x == 1), Some((&[][..], &[2, 3, 2, 4][..]))); - assert_eq!(v.rsplit_once(|&x| x == 4), Some((&[1, 2, 3, 2][..], &[][..]))); - assert_eq!(v.rsplit_once(|&x| x == 0), None); -} - -macro_rules! take_tests { - (slice: &[], $($tts:tt)*) => { - take_tests!(ty: &[()], slice: &[], $($tts)*); - }; - (slice: &mut [], $($tts:tt)*) => { - take_tests!(ty: &mut [()], slice: &mut [], $($tts)*); - }; - (slice: &$slice:expr, $($tts:tt)*) => { - take_tests!(ty: &[_], slice: &$slice, $($tts)*); - }; - (slice: &mut $slice:expr, $($tts:tt)*) => { - take_tests!(ty: &mut [_], slice: &mut $slice, $($tts)*); - }; - (ty: $ty:ty, slice: $slice:expr, method: $method:ident, $(($test_name:ident, ($($args:expr),*), $output:expr, $remaining:expr),)*) => { - $( - #[test] - fn $test_name() { - let mut slice: $ty = $slice; - assert_eq!($output, slice.$method($($args)*)); - let remaining: $ty = $remaining; - assert_eq!(remaining, slice); - } - )* - }; -} - -take_tests! { - slice: &[0, 1, 2, 3], method: take, - (take_in_bounds_range_to, (..1), Some(&[0] as _), &[1, 2, 3]), - (take_in_bounds_range_to_inclusive, (..=0), Some(&[0] as _), &[1, 2, 3]), - (take_in_bounds_range_from, (2..), Some(&[2, 3] as _), &[0, 1]), - (take_oob_range_to, (..5), None, &[0, 1, 2, 3]), - (take_oob_range_to_inclusive, (..=4), None, &[0, 1, 2, 3]), - (take_oob_range_from, (5..), None, &[0, 1, 2, 3]), -} - -take_tests! { - slice: &mut [0, 1, 2, 3], method: take_mut, - (take_mut_in_bounds_range_to, (..1), Some(&mut [0] as _), &mut [1, 2, 3]), - (take_mut_in_bounds_range_to_inclusive, (..=0), Some(&mut [0] as _), &mut [1, 2, 3]), - (take_mut_in_bounds_range_from, (2..), Some(&mut [2, 3] as _), &mut [0, 1]), - (take_mut_oob_range_to, (..5), None, &mut [0, 1, 2, 3]), - (take_mut_oob_range_to_inclusive, (..=4), None, &mut [0, 1, 2, 3]), - (take_mut_oob_range_from, (5..), None, &mut [0, 1, 2, 3]), -} - -take_tests! { - slice: &[1, 2], method: take_first, - (take_first_nonempty, (), Some(&1), &[2]), -} - -take_tests! { - slice: &mut [1, 2], method: take_first_mut, - (take_first_mut_nonempty, (), Some(&mut 1), &mut [2]), -} - -take_tests! { - slice: &[1, 2], method: take_last, - (take_last_nonempty, (), Some(&2), &[1]), -} - -take_tests! { - slice: &mut [1, 2], method: take_last_mut, - (take_last_mut_nonempty, (), Some(&mut 2), &mut [1]), -} - -take_tests! { - slice: &[], method: take_first, - (take_first_empty, (), None, &[]), -} - -take_tests! { - slice: &mut [], method: take_first_mut, - (take_first_mut_empty, (), None, &mut []), -} - -take_tests! { - slice: &[], method: take_last, - (take_last_empty, (), None, &[]), -} - -take_tests! { - slice: &mut [], method: take_last_mut, - (take_last_mut_empty, (), None, &mut []), -} - -#[cfg(not(miri))] // unused in Miri -const EMPTY_MAX: &'static [()] = &[(); usize::MAX]; - -// can't be a constant due to const mutability rules -#[cfg(not(miri))] // unused in Miri -macro_rules! empty_max_mut { - () => { - &mut [(); usize::MAX] as _ - }; -} - -#[cfg(not(miri))] // Comparing usize::MAX many elements takes forever in Miri (and in rustc without optimizations) -take_tests! { - slice: &[(); usize::MAX], method: take, - (take_in_bounds_max_range_to, (..usize::MAX), Some(EMPTY_MAX), &[(); 0]), - (take_oob_max_range_to_inclusive, (..=usize::MAX), None, EMPTY_MAX), - (take_in_bounds_max_range_from, (usize::MAX..), Some(&[] as _), EMPTY_MAX), -} - -#[cfg(not(miri))] // Comparing usize::MAX many elements takes forever in Miri (and in rustc without optimizations) -take_tests! { - slice: &mut [(); usize::MAX], method: take_mut, - (take_mut_in_bounds_max_range_to, (..usize::MAX), Some(empty_max_mut!()), &mut [(); 0]), - (take_mut_oob_max_range_to_inclusive, (..=usize::MAX), None, empty_max_mut!()), - (take_mut_in_bounds_max_range_from, (usize::MAX..), Some(&mut [] as _), empty_max_mut!()), -} - -#[test] -fn test_slice_from_ptr_range() { - let arr = ["foo".to_owned(), "bar".to_owned()]; - let range = arr.as_ptr_range(); - unsafe { - assert_eq!(slice::from_ptr_range(range), &arr); - } - - let mut arr = [1, 2, 3]; - let range = arr.as_mut_ptr_range(); - unsafe { - assert_eq!(slice::from_mut_ptr_range(range), &mut [1, 2, 3]); - } - - let arr: [Vec; 0] = []; - let range = arr.as_ptr_range(); - unsafe { - assert_eq!(slice::from_ptr_range(range), &arr); - } -} - -#[test] -#[should_panic = "slice len overflow"] -fn test_flatten_size_overflow() { - let x = &[[(); usize::MAX]; 2][..]; - let _ = x.as_flattened(); -} - -#[test] -#[should_panic = "slice len overflow"] -fn test_flatten_mut_size_overflow() { - let x = &mut [[(); usize::MAX]; 2][..]; - let _ = x.as_flattened_mut(); -} - -#[test] -fn test_get_many_mut_normal_2() { - let mut v = vec![1, 2, 3, 4, 5]; - let [a, b] = v.get_many_mut([3, 0]).unwrap(); - *a += 10; - *b += 100; - assert_eq!(v, vec![101, 2, 3, 14, 5]); -} - -#[test] -fn test_get_many_mut_normal_3() { - let mut v = vec![1, 2, 3, 4, 5]; - let [a, b, c] = v.get_many_mut([0, 4, 2]).unwrap(); - *a += 10; - *b += 100; - *c += 1000; - assert_eq!(v, vec![11, 2, 1003, 4, 105]); -} - -#[test] -fn test_get_many_mut_empty() { - let mut v = vec![1, 2, 3, 4, 5]; - let [] = v.get_many_mut([]).unwrap(); - assert_eq!(v, vec![1, 2, 3, 4, 5]); -} - -#[test] -fn test_get_many_mut_single_first() { - let mut v = vec![1, 2, 3, 4, 5]; - let [a] = v.get_many_mut([0]).unwrap(); - *a += 10; - assert_eq!(v, vec![11, 2, 3, 4, 5]); -} - -#[test] -fn test_get_many_mut_single_last() { - let mut v = vec![1, 2, 3, 4, 5]; - let [a] = v.get_many_mut([4]).unwrap(); - *a += 10; - assert_eq!(v, vec![1, 2, 3, 4, 15]); -} - -#[test] -fn test_get_many_mut_oob_nonempty() { - let mut v = vec![1, 2, 3, 4, 5]; - assert!(v.get_many_mut([5]).is_err()); -} - -#[test] -fn test_get_many_mut_oob_empty() { - let mut v: Vec = vec![]; - assert!(v.get_many_mut([0]).is_err()); -} - -#[test] -fn test_get_many_mut_duplicate() { - let mut v = vec![1, 2, 3, 4, 5]; - assert!(v.get_many_mut([1, 3, 3, 4]).is_err()); -} - -#[test] -fn test_slice_from_raw_parts_in_const() { - static FANCY: i32 = 4; - static FANCY_SLICE: &[i32] = unsafe { std::slice::from_raw_parts(&FANCY, 1) }; - assert_eq!(FANCY_SLICE.as_ptr(), std::ptr::addr_of!(FANCY)); - assert_eq!(FANCY_SLICE.len(), 1); - - const EMPTY_SLICE: &[i32] = - unsafe { std::slice::from_raw_parts(std::ptr::without_provenance(123456), 0) }; - assert_eq!(EMPTY_SLICE.as_ptr().addr(), 123456); - assert_eq!(EMPTY_SLICE.len(), 0); -} diff --git a/library/core/tests/str.rs b/library/core/tests/str.rs deleted file mode 100644 index f5066343af20a..0000000000000 --- a/library/core/tests/str.rs +++ /dev/null @@ -1 +0,0 @@ -// All `str` tests live in library/alloc/tests/str.rs diff --git a/library/core/tests/str_lossy.rs b/library/core/tests/str_lossy.rs deleted file mode 100644 index 6e70ea3e28574..0000000000000 --- a/library/core/tests/str_lossy.rs +++ /dev/null @@ -1,83 +0,0 @@ -#[test] -fn chunks() { - macro_rules! assert_chunks { - ( $string:expr, $(($valid:expr, $invalid:expr)),* $(,)? ) => {{ - let mut iter = $string.utf8_chunks(); - $( - let chunk = iter.next().expect("missing chunk"); - assert_eq!($valid, chunk.valid()); - assert_eq!($invalid, chunk.invalid()); - )* - assert_eq!(None, iter.next()); - }}; - } - - assert_chunks!(b"hello", ("hello", b"")); - assert_chunks!("ศไทย中华Việt Nam".as_bytes(), ("ศไทย中华Việt Nam", b"")); - assert_chunks!( - b"Hello\xC2 There\xFF Goodbye", - ("Hello", b"\xC2"), - (" There", b"\xFF"), - (" Goodbye", b""), - ); - assert_chunks!( - b"Hello\xC0\x80 There\xE6\x83 Goodbye", - ("Hello", b"\xC0"), - ("", b"\x80"), - (" There", b"\xE6\x83"), - (" Goodbye", b""), - ); - assert_chunks!( - b"\xF5foo\xF5\x80bar", - ("", b"\xF5"), - ("foo", b"\xF5"), - ("", b"\x80"), - ("bar", b""), - ); - assert_chunks!( - b"\xF1foo\xF1\x80bar\xF1\x80\x80baz", - ("", b"\xF1"), - ("foo", b"\xF1\x80"), - ("bar", b"\xF1\x80\x80"), - ("baz", b""), - ); - assert_chunks!( - b"\xF4foo\xF4\x80bar\xF4\xBFbaz", - ("", b"\xF4"), - ("foo", b"\xF4\x80"), - ("bar", b"\xF4"), - ("", b"\xBF"), - ("baz", b""), - ); - assert_chunks!( - b"\xF0\x80\x80\x80foo\xF0\x90\x80\x80bar", - ("", b"\xF0"), - ("", b"\x80"), - ("", b"\x80"), - ("", b"\x80"), - ("foo\u{10000}bar", b""), - ); - - // surrogates - assert_chunks!( - b"\xED\xA0\x80foo\xED\xBF\xBFbar", - ("", b"\xED"), - ("", b"\xA0"), - ("", b"\x80"), - ("foo", b"\xED"), - ("", b"\xBF"), - ("", b"\xBF"), - ("bar", b""), - ); -} - -#[test] -fn debug() { - assert_eq!( - "\"Hello\\xC0\\x80 There\\xE6\\x83 Goodbye\\u{10d4ea}\"", - &format!( - "{:?}", - b"Hello\xC0\x80 There\xE6\x83 Goodbye\xf4\x8d\x93\xaa".utf8_chunks().debug(), - ), - ); -} diff --git a/library/core/tests/task.rs b/library/core/tests/task.rs deleted file mode 100644 index 163b34c964852..0000000000000 --- a/library/core/tests/task.rs +++ /dev/null @@ -1,25 +0,0 @@ -use core::task::{Poll, RawWaker, RawWakerVTable, Waker}; - -#[test] -fn poll_const() { - // test that the methods of `Poll` are usable in a const context - - const POLL: Poll = Poll::Pending; - - const IS_READY: bool = POLL.is_ready(); - assert!(!IS_READY); - - const IS_PENDING: bool = POLL.is_pending(); - assert!(IS_PENDING); -} - -#[test] -fn waker_const() { - const VOID_TABLE: RawWakerVTable = RawWakerVTable::new(|_| VOID_WAKER, |_| {}, |_| {}, |_| {}); - - const VOID_WAKER: RawWaker = RawWaker::new(&(), &VOID_TABLE); - - static WAKER: Waker = unsafe { Waker::from_raw(VOID_WAKER) }; - - WAKER.wake_by_ref(); -} diff --git a/library/core/tests/time.rs b/library/core/tests/time.rs deleted file mode 100644 index fe7bb11c67589..0000000000000 --- a/library/core/tests/time.rs +++ /dev/null @@ -1,564 +0,0 @@ -use core::time::Duration; - -#[test] -fn creation() { - assert_ne!(Duration::from_secs(1), Duration::from_secs(0)); - assert_eq!(Duration::from_secs(1) + Duration::from_secs(2), Duration::from_secs(3)); - assert_eq!( - Duration::from_millis(10) + Duration::from_secs(4), - Duration::new(4, 10 * 1_000_000) - ); - assert_eq!(Duration::from_millis(4000), Duration::new(4, 0)); -} - -#[test] -#[should_panic] -fn new_overflow() { - let _ = Duration::new(u64::MAX, 1_000_000_000); -} - -#[test] -#[should_panic] -fn from_mins_overflow() { - let overflow = u64::MAX / 60 + 1; - let _ = Duration::from_mins(overflow); -} - -#[test] -#[should_panic] -fn from_hours_overflow() { - let overflow = u64::MAX / (60 * 60) + 1; - let _ = Duration::from_hours(overflow); -} - -#[test] -#[should_panic] -fn from_days_overflow() { - let overflow = u64::MAX / (24 * 60 * 60) + 1; - let _ = Duration::from_days(overflow); -} - -#[test] -#[should_panic] -fn from_weeks_overflow() { - let overflow = u64::MAX / (7 * 24 * 60 * 60) + 1; - let _ = Duration::from_weeks(overflow); -} - -#[test] -fn constructors() { - assert_eq!(Duration::from_weeks(1), Duration::from_secs(7 * 24 * 60 * 60)); - assert_eq!(Duration::from_weeks(0), Duration::ZERO); - - assert_eq!(Duration::from_days(1), Duration::from_secs(86_400)); - assert_eq!(Duration::from_days(0), Duration::ZERO); - - assert_eq!(Duration::from_hours(1), Duration::from_secs(3_600)); - assert_eq!(Duration::from_hours(0), Duration::ZERO); - - assert_eq!(Duration::from_mins(1), Duration::from_secs(60)); - assert_eq!(Duration::from_mins(0), Duration::ZERO); -} - -#[test] -fn secs() { - assert_eq!(Duration::new(0, 0).as_secs(), 0); - assert_eq!(Duration::new(0, 500_000_005).as_secs(), 0); - assert_eq!(Duration::new(0, 1_050_000_001).as_secs(), 1); - assert_eq!(Duration::from_secs(1).as_secs(), 1); - assert_eq!(Duration::from_millis(999).as_secs(), 0); - assert_eq!(Duration::from_millis(1001).as_secs(), 1); - assert_eq!(Duration::from_micros(999_999).as_secs(), 0); - assert_eq!(Duration::from_micros(1_000_001).as_secs(), 1); - assert_eq!(Duration::from_nanos(999_999_999).as_secs(), 0); - assert_eq!(Duration::from_nanos(1_000_000_001).as_secs(), 1); -} - -#[test] -fn millis() { - assert_eq!(Duration::new(0, 0).subsec_millis(), 0); - assert_eq!(Duration::new(0, 500_000_005).subsec_millis(), 500); - assert_eq!(Duration::new(0, 1_050_000_001).subsec_millis(), 50); - assert_eq!(Duration::from_secs(1).subsec_millis(), 0); - assert_eq!(Duration::from_millis(999).subsec_millis(), 999); - assert_eq!(Duration::from_millis(1001).subsec_millis(), 1); - assert_eq!(Duration::from_micros(999_999).subsec_millis(), 999); - assert_eq!(Duration::from_micros(1_001_000).subsec_millis(), 1); - assert_eq!(Duration::from_nanos(999_999_999).subsec_millis(), 999); - assert_eq!(Duration::from_nanos(1_001_000_000).subsec_millis(), 1); -} - -#[test] -fn micros() { - assert_eq!(Duration::new(0, 0).subsec_micros(), 0); - assert_eq!(Duration::new(0, 500_000_005).subsec_micros(), 500_000); - assert_eq!(Duration::new(0, 1_050_000_001).subsec_micros(), 50_000); - assert_eq!(Duration::from_secs(1).subsec_micros(), 0); - assert_eq!(Duration::from_millis(999).subsec_micros(), 999_000); - assert_eq!(Duration::from_millis(1001).subsec_micros(), 1_000); - assert_eq!(Duration::from_micros(999_999).subsec_micros(), 999_999); - assert_eq!(Duration::from_micros(1_000_001).subsec_micros(), 1); - assert_eq!(Duration::from_nanos(999_999_999).subsec_micros(), 999_999); - assert_eq!(Duration::from_nanos(1_000_001_000).subsec_micros(), 1); -} - -#[test] -fn nanos() { - assert_eq!(Duration::new(0, 0).subsec_nanos(), 0); - assert_eq!(Duration::new(0, 5).subsec_nanos(), 5); - assert_eq!(Duration::new(0, 1_000_000_001).subsec_nanos(), 1); - assert_eq!(Duration::from_secs(1).subsec_nanos(), 0); - assert_eq!(Duration::from_millis(999).subsec_nanos(), 999_000_000); - assert_eq!(Duration::from_millis(1001).subsec_nanos(), 1_000_000); - assert_eq!(Duration::from_micros(999_999).subsec_nanos(), 999_999_000); - assert_eq!(Duration::from_micros(1_000_001).subsec_nanos(), 1000); - assert_eq!(Duration::from_nanos(999_999_999).subsec_nanos(), 999_999_999); - assert_eq!(Duration::from_nanos(1_000_000_001).subsec_nanos(), 1); -} - -#[test] -fn abs_diff() { - assert_eq!(Duration::new(2, 0).abs_diff(Duration::new(1, 0)), Duration::new(1, 0)); - assert_eq!(Duration::new(1, 0).abs_diff(Duration::new(2, 0)), Duration::new(1, 0)); - assert_eq!(Duration::new(1, 0).abs_diff(Duration::new(1, 0)), Duration::new(0, 0)); - assert_eq!(Duration::new(1, 1).abs_diff(Duration::new(0, 2)), Duration::new(0, 999_999_999)); - assert_eq!(Duration::new(1, 1).abs_diff(Duration::new(2, 1)), Duration::new(1, 0)); - assert_eq!(Duration::MAX.abs_diff(Duration::MAX), Duration::ZERO); - assert_eq!(Duration::ZERO.abs_diff(Duration::ZERO), Duration::ZERO); - assert_eq!(Duration::MAX.abs_diff(Duration::ZERO), Duration::MAX); - assert_eq!(Duration::ZERO.abs_diff(Duration::MAX), Duration::MAX); -} - -#[test] -fn add() { - assert_eq!(Duration::new(0, 0) + Duration::new(0, 1), Duration::new(0, 1)); - assert_eq!(Duration::new(0, 500_000_000) + Duration::new(0, 500_000_001), Duration::new(1, 1)); -} - -#[test] -fn checked_add() { - assert_eq!(Duration::new(0, 0).checked_add(Duration::new(0, 1)), Some(Duration::new(0, 1))); - assert_eq!( - Duration::new(0, 500_000_000).checked_add(Duration::new(0, 500_000_001)), - Some(Duration::new(1, 1)) - ); - assert_eq!(Duration::new(1, 0).checked_add(Duration::new(u64::MAX, 0)), None); -} - -#[test] -fn saturating_add() { - assert_eq!(Duration::new(0, 0).saturating_add(Duration::new(0, 1)), Duration::new(0, 1)); - assert_eq!( - Duration::new(0, 500_000_000).saturating_add(Duration::new(0, 500_000_001)), - Duration::new(1, 1) - ); - assert_eq!(Duration::new(1, 0).saturating_add(Duration::new(u64::MAX, 0)), Duration::MAX); -} - -#[test] -fn sub() { - assert_eq!(Duration::new(0, 1) - Duration::new(0, 0), Duration::new(0, 1)); - assert_eq!(Duration::new(0, 500_000_001) - Duration::new(0, 500_000_000), Duration::new(0, 1)); - assert_eq!(Duration::new(1, 0) - Duration::new(0, 1), Duration::new(0, 999_999_999)); -} - -#[test] -fn checked_sub() { - assert_eq!(Duration::NANOSECOND.checked_sub(Duration::ZERO), Some(Duration::NANOSECOND)); - assert_eq!( - Duration::SECOND.checked_sub(Duration::NANOSECOND), - Some(Duration::new(0, 999_999_999)) - ); - assert_eq!(Duration::ZERO.checked_sub(Duration::NANOSECOND), None); - assert_eq!(Duration::ZERO.checked_sub(Duration::SECOND), None); -} - -#[test] -fn saturating_sub() { - assert_eq!(Duration::NANOSECOND.saturating_sub(Duration::ZERO), Duration::NANOSECOND); - assert_eq!( - Duration::SECOND.saturating_sub(Duration::NANOSECOND), - Duration::new(0, 999_999_999) - ); - assert_eq!(Duration::ZERO.saturating_sub(Duration::NANOSECOND), Duration::ZERO); - assert_eq!(Duration::ZERO.saturating_sub(Duration::SECOND), Duration::ZERO); -} - -#[test] -#[should_panic] -fn sub_bad1() { - let _ = Duration::new(0, 0) - Duration::new(0, 1); -} - -#[test] -#[should_panic] -fn sub_bad2() { - let _ = Duration::new(0, 0) - Duration::new(1, 0); -} - -#[test] -fn mul() { - assert_eq!(Duration::new(0, 1) * 2, Duration::new(0, 2)); - assert_eq!(Duration::new(1, 1) * 3, Duration::new(3, 3)); - assert_eq!(Duration::new(0, 500_000_001) * 4, Duration::new(2, 4)); - assert_eq!(Duration::new(0, 500_000_001) * 4000, Duration::new(2000, 4000)); -} - -#[test] -fn checked_mul() { - assert_eq!(Duration::new(0, 1).checked_mul(2), Some(Duration::new(0, 2))); - assert_eq!(Duration::new(1, 1).checked_mul(3), Some(Duration::new(3, 3))); - assert_eq!(Duration::new(0, 500_000_001).checked_mul(4), Some(Duration::new(2, 4))); - assert_eq!(Duration::new(0, 500_000_001).checked_mul(4000), Some(Duration::new(2000, 4000))); - assert_eq!(Duration::new(u64::MAX - 1, 0).checked_mul(2), None); -} - -#[test] -fn saturating_mul() { - assert_eq!(Duration::new(0, 1).saturating_mul(2), Duration::new(0, 2)); - assert_eq!(Duration::new(1, 1).saturating_mul(3), Duration::new(3, 3)); - assert_eq!(Duration::new(0, 500_000_001).saturating_mul(4), Duration::new(2, 4)); - assert_eq!(Duration::new(0, 500_000_001).saturating_mul(4000), Duration::new(2000, 4000)); - assert_eq!(Duration::new(u64::MAX - 1, 0).saturating_mul(2), Duration::MAX); -} - -#[test] -fn div() { - assert_eq!(Duration::new(0, 1) / 2, Duration::new(0, 0)); - assert_eq!(Duration::new(1, 1) / 3, Duration::new(0, 333_333_333)); - assert_eq!(Duration::new(1, 1) / 7, Duration::new(0, 142_857_143)); - assert_eq!(Duration::new(99, 999_999_000) / 100, Duration::new(0, 999_999_990)); -} - -#[test] -fn div_duration_f32() { - assert_eq!(Duration::ZERO.div_duration_f32(Duration::MAX), 0.0); - assert_eq!(Duration::MAX.div_duration_f32(Duration::ZERO), f32::INFINITY); - assert_eq!((Duration::SECOND * 2).div_duration_f32(Duration::SECOND), 2.0); - assert!(Duration::ZERO.div_duration_f32(Duration::ZERO).is_nan()); - // These tests demonstrate it doesn't panic with extreme values. - // Accuracy of the computed value is not a huge concern, we know floats don't work well - // at these extremes. - assert!((Duration::MAX).div_duration_f32(Duration::NANOSECOND) > 10.0f32.powf(28.0)); - assert!((Duration::NANOSECOND).div_duration_f32(Duration::MAX) < 0.1); -} - -#[test] -fn div_duration_f64() { - assert_eq!(Duration::ZERO.div_duration_f64(Duration::MAX), 0.0); - assert_eq!(Duration::MAX.div_duration_f64(Duration::ZERO), f64::INFINITY); - assert_eq!((Duration::SECOND * 2).div_duration_f64(Duration::SECOND), 2.0); - assert!(Duration::ZERO.div_duration_f64(Duration::ZERO).is_nan()); - // These tests demonstrate it doesn't panic with extreme values. - // Accuracy of the computed value is not a huge concern, we know floats don't work well - // at these extremes. - assert!((Duration::MAX).div_duration_f64(Duration::NANOSECOND) > 10.0f64.powf(28.0)); - assert!((Duration::NANOSECOND).div_duration_f64(Duration::MAX) < 0.1); -} - -#[test] -fn checked_div() { - assert_eq!(Duration::new(2, 0).checked_div(2), Some(Duration::new(1, 0))); - assert_eq!(Duration::new(1, 0).checked_div(2), Some(Duration::new(0, 500_000_000))); - assert_eq!(Duration::new(2, 0).checked_div(0), None); -} - -#[test] -fn correct_sum() { - let durations = [ - Duration::new(1, 999_999_999), - Duration::new(2, 999_999_999), - Duration::new(0, 999_999_999), - Duration::new(0, 999_999_999), - Duration::new(0, 999_999_999), - Duration::new(5, 0), - ]; - let sum = durations.iter().sum::(); - assert_eq!(sum, Duration::new(1 + 2 + 5 + 4, 1_000_000_000 - 5)); -} - -#[test] -fn debug_formatting_extreme_values() { - assert_eq!( - format!("{:?}", Duration::new(u64::MAX, 123_456_789)), - "18446744073709551615.123456789s" - ); - assert_eq!(format!("{:.0?}", Duration::MAX), "18446744073709551616s"); - assert_eq!(format!("{:.0?}", Duration::new(u64::MAX, 500_000_000)), "18446744073709551616s"); - assert_eq!(format!("{:.0?}", Duration::new(u64::MAX, 499_999_999)), "18446744073709551615s"); - assert_eq!( - format!("{:.3?}", Duration::new(u64::MAX, 999_500_000)), - "18446744073709551616.000s" - ); - assert_eq!( - format!("{:.3?}", Duration::new(u64::MAX, 999_499_999)), - "18446744073709551615.999s" - ); - assert_eq!( - format!("{:.8?}", Duration::new(u64::MAX, 999_999_995)), - "18446744073709551616.00000000s" - ); - assert_eq!( - format!("{:.8?}", Duration::new(u64::MAX, 999_999_994)), - "18446744073709551615.99999999s" - ); - assert_eq!(format!("{:21.0?}", Duration::MAX), "18446744073709551616s"); - assert_eq!(format!("{:22.0?}", Duration::MAX), "18446744073709551616s "); - assert_eq!(format!("{:24.0?}", Duration::MAX), "18446744073709551616s "); -} - -#[test] -fn debug_formatting_secs() { - assert_eq!(format!("{:?}", Duration::new(7, 000_000_000)), "7s"); - assert_eq!(format!("{:?}", Duration::new(7, 100_000_000)), "7.1s"); - assert_eq!(format!("{:?}", Duration::new(7, 000_010_000)), "7.00001s"); - assert_eq!(format!("{:?}", Duration::new(7, 000_000_001)), "7.000000001s"); - assert_eq!(format!("{:?}", Duration::new(7, 123_456_789)), "7.123456789s"); - - assert_eq!(format!("{:?}", Duration::new(88, 000_000_000)), "88s"); - assert_eq!(format!("{:?}", Duration::new(88, 100_000_000)), "88.1s"); - assert_eq!(format!("{:?}", Duration::new(88, 000_010_000)), "88.00001s"); - assert_eq!(format!("{:?}", Duration::new(88, 000_000_001)), "88.000000001s"); - assert_eq!(format!("{:?}", Duration::new(88, 123_456_789)), "88.123456789s"); - - assert_eq!(format!("{:?}", Duration::new(999, 000_000_000)), "999s"); - assert_eq!(format!("{:?}", Duration::new(999, 100_000_000)), "999.1s"); - assert_eq!(format!("{:?}", Duration::new(999, 000_010_000)), "999.00001s"); - assert_eq!(format!("{:?}", Duration::new(999, 000_000_001)), "999.000000001s"); - assert_eq!(format!("{:?}", Duration::new(999, 123_456_789)), "999.123456789s"); -} - -#[test] -fn debug_formatting_millis() { - assert_eq!(format!("{:?}", Duration::new(0, 7_000_000)), "7ms"); - assert_eq!(format!("{:?}", Duration::new(0, 7_100_000)), "7.1ms"); - assert_eq!(format!("{:?}", Duration::new(0, 7_000_001)), "7.000001ms"); - assert_eq!(format!("{:?}", Duration::new(0, 7_123_456)), "7.123456ms"); - - assert_eq!(format!("{:?}", Duration::new(0, 88_000_000)), "88ms"); - assert_eq!(format!("{:?}", Duration::new(0, 88_100_000)), "88.1ms"); - assert_eq!(format!("{:?}", Duration::new(0, 88_000_001)), "88.000001ms"); - assert_eq!(format!("{:?}", Duration::new(0, 88_123_456)), "88.123456ms"); - - assert_eq!(format!("{:?}", Duration::new(0, 999_000_000)), "999ms"); - assert_eq!(format!("{:?}", Duration::new(0, 999_100_000)), "999.1ms"); - assert_eq!(format!("{:?}", Duration::new(0, 999_000_001)), "999.000001ms"); - assert_eq!(format!("{:?}", Duration::new(0, 999_123_456)), "999.123456ms"); -} - -#[test] -fn debug_formatting_micros() { - assert_eq!(format!("{:?}", Duration::new(0, 7_000)), "7µs"); - assert_eq!(format!("{:?}", Duration::new(0, 7_100)), "7.1µs"); - assert_eq!(format!("{:?}", Duration::new(0, 7_001)), "7.001µs"); - assert_eq!(format!("{:?}", Duration::new(0, 7_123)), "7.123µs"); - - assert_eq!(format!("{:?}", Duration::new(0, 88_000)), "88µs"); - assert_eq!(format!("{:?}", Duration::new(0, 88_100)), "88.1µs"); - assert_eq!(format!("{:?}", Duration::new(0, 88_001)), "88.001µs"); - assert_eq!(format!("{:?}", Duration::new(0, 88_123)), "88.123µs"); - - assert_eq!(format!("{:?}", Duration::new(0, 999_000)), "999µs"); - assert_eq!(format!("{:?}", Duration::new(0, 999_100)), "999.1µs"); - assert_eq!(format!("{:?}", Duration::new(0, 999_001)), "999.001µs"); - assert_eq!(format!("{:?}", Duration::new(0, 999_123)), "999.123µs"); -} - -#[test] -fn debug_formatting_nanos() { - assert_eq!(format!("{:?}", Duration::new(0, 0)), "0ns"); - assert_eq!(format!("{:?}", Duration::new(0, 1)), "1ns"); - assert_eq!(format!("{:?}", Duration::new(0, 88)), "88ns"); - assert_eq!(format!("{:?}", Duration::new(0, 999)), "999ns"); -} - -#[test] -fn debug_formatting_precision_zero() { - assert_eq!(format!("{:.0?}", Duration::new(0, 0)), "0ns"); - assert_eq!(format!("{:.0?}", Duration::new(0, 123)), "123ns"); - - assert_eq!(format!("{:.0?}", Duration::new(0, 1_001)), "1µs"); - assert_eq!(format!("{:.0?}", Duration::new(0, 1_499)), "1µs"); - assert_eq!(format!("{:.0?}", Duration::new(0, 1_500)), "2µs"); - assert_eq!(format!("{:.0?}", Duration::new(0, 1_999)), "2µs"); - - assert_eq!(format!("{:.0?}", Duration::new(0, 1_000_001)), "1ms"); - assert_eq!(format!("{:.0?}", Duration::new(0, 1_499_999)), "1ms"); - assert_eq!(format!("{:.0?}", Duration::new(0, 1_500_000)), "2ms"); - assert_eq!(format!("{:.0?}", Duration::new(0, 1_999_999)), "2ms"); - - assert_eq!(format!("{:.0?}", Duration::new(1, 000_000_001)), "1s"); - assert_eq!(format!("{:.0?}", Duration::new(1, 499_999_999)), "1s"); - assert_eq!(format!("{:.0?}", Duration::new(1, 500_000_000)), "2s"); - assert_eq!(format!("{:.0?}", Duration::new(1, 999_999_999)), "2s"); -} - -#[test] -fn debug_formatting_precision_two() { - assert_eq!(format!("{:.2?}", Duration::new(0, 0)), "0.00ns"); - assert_eq!(format!("{:.2?}", Duration::new(0, 123)), "123.00ns"); - - assert_eq!(format!("{:.2?}", Duration::new(0, 1_000)), "1.00µs"); - assert_eq!(format!("{:.2?}", Duration::new(0, 7_001)), "7.00µs"); - assert_eq!(format!("{:.2?}", Duration::new(0, 7_100)), "7.10µs"); - assert_eq!(format!("{:.2?}", Duration::new(0, 7_109)), "7.11µs"); - assert_eq!(format!("{:.2?}", Duration::new(0, 7_199)), "7.20µs"); - assert_eq!(format!("{:.2?}", Duration::new(0, 1_999)), "2.00µs"); - - assert_eq!(format!("{:.2?}", Duration::new(0, 1_000_000)), "1.00ms"); - assert_eq!(format!("{:.2?}", Duration::new(0, 3_001_000)), "3.00ms"); - assert_eq!(format!("{:.2?}", Duration::new(0, 3_100_000)), "3.10ms"); - assert_eq!(format!("{:.2?}", Duration::new(0, 1_999_999)), "2.00ms"); - - assert_eq!(format!("{:.2?}", Duration::new(1, 000_000_000)), "1.00s"); - assert_eq!(format!("{:.2?}", Duration::new(4, 001_000_000)), "4.00s"); - assert_eq!(format!("{:.2?}", Duration::new(2, 100_000_000)), "2.10s"); - assert_eq!(format!("{:.2?}", Duration::new(2, 104_990_000)), "2.10s"); - assert_eq!(format!("{:.2?}", Duration::new(2, 105_000_000)), "2.11s"); - assert_eq!(format!("{:.2?}", Duration::new(8, 999_999_999)), "9.00s"); -} - -#[test] -fn debug_formatting_padding() { - assert_eq!("0ns ", format!("{:<9?}", Duration::new(0, 0))); - assert_eq!(" 0ns", format!("{:>9?}", Duration::new(0, 0))); - assert_eq!(" 0ns ", format!("{:^9?}", Duration::new(0, 0))); - assert_eq!("123ns ", format!("{:<9.0?}", Duration::new(0, 123))); - assert_eq!(" 123ns", format!("{:>9.0?}", Duration::new(0, 123))); - assert_eq!(" 123ns ", format!("{:^9.0?}", Duration::new(0, 123))); - assert_eq!("123.0ns ", format!("{:<9.1?}", Duration::new(0, 123))); - assert_eq!(" 123.0ns", format!("{:>9.1?}", Duration::new(0, 123))); - assert_eq!(" 123.0ns ", format!("{:^9.1?}", Duration::new(0, 123))); - assert_eq!("7.1µs ", format!("{:<9?}", Duration::new(0, 7_100))); - assert_eq!(" 7.1µs", format!("{:>9?}", Duration::new(0, 7_100))); - assert_eq!(" 7.1µs ", format!("{:^9?}", Duration::new(0, 7_100))); - assert_eq!("999.123456ms", format!("{:<9?}", Duration::new(0, 999_123_456))); - assert_eq!("999.123456ms", format!("{:>9?}", Duration::new(0, 999_123_456))); - assert_eq!("999.123456ms", format!("{:^9?}", Duration::new(0, 999_123_456))); - assert_eq!("5s ", format!("{:<9?}", Duration::new(5, 0))); - assert_eq!(" 5s", format!("{:>9?}", Duration::new(5, 0))); - assert_eq!(" 5s ", format!("{:^9?}", Duration::new(5, 0))); - assert_eq!("5.000000000000s", format!("{:<9.12?}", Duration::new(5, 0))); - assert_eq!("5.000000000000s", format!("{:>9.12?}", Duration::new(5, 0))); - assert_eq!("5.000000000000s", format!("{:^9.12?}", Duration::new(5, 0))); - - // default alignment is left: - assert_eq!("5s ", format!("{:9?}", Duration::new(5, 0))); -} - -#[test] -fn debug_formatting_precision_high() { - assert_eq!(format!("{:.5?}", Duration::new(0, 23_678)), "23.67800µs"); - - assert_eq!(format!("{:.9?}", Duration::new(1, 000_000_000)), "1.000000000s"); - assert_eq!(format!("{:.10?}", Duration::new(4, 001_000_000)), "4.0010000000s"); - assert_eq!(format!("{:.20?}", Duration::new(4, 001_000_000)), "4.00100000000000000000s"); -} - -#[test] -fn duration_const() { - // test that the methods of `Duration` are usable in a const context - - const DURATION: Duration = Duration::new(0, 123_456_789); - - const SUB_SEC_MILLIS: u32 = DURATION.subsec_millis(); - assert_eq!(SUB_SEC_MILLIS, 123); - - const SUB_SEC_MICROS: u32 = DURATION.subsec_micros(); - assert_eq!(SUB_SEC_MICROS, 123_456); - - const SUB_SEC_NANOS: u32 = DURATION.subsec_nanos(); - assert_eq!(SUB_SEC_NANOS, 123_456_789); - - const IS_ZERO: bool = Duration::ZERO.is_zero(); - assert!(IS_ZERO); - - const SECONDS: u64 = Duration::SECOND.as_secs(); - assert_eq!(SECONDS, 1); - - const FROM_SECONDS: Duration = Duration::from_secs(1); - assert_eq!(FROM_SECONDS, Duration::SECOND); - - const SECONDS_F32: f32 = Duration::SECOND.as_secs_f32(); - assert_eq!(SECONDS_F32, 1.0); - - // FIXME(#110395) - // const FROM_SECONDS_F32: Duration = Duration::from_secs_f32(1.0); - // assert_eq!(FROM_SECONDS_F32, Duration::SECOND); - - const SECONDS_F64: f64 = Duration::SECOND.as_secs_f64(); - assert_eq!(SECONDS_F64, 1.0); - - // FIXME(#110395) - // const FROM_SECONDS_F64: Duration = Duration::from_secs_f64(1.0); - // assert_eq!(FROM_SECONDS_F64, Duration::SECOND); - - const MILLIS: u128 = Duration::SECOND.as_millis(); - assert_eq!(MILLIS, 1_000); - - const FROM_MILLIS: Duration = Duration::from_millis(1_000); - assert_eq!(FROM_MILLIS, Duration::SECOND); - - const MICROS: u128 = Duration::SECOND.as_micros(); - assert_eq!(MICROS, 1_000_000); - - const FROM_MICROS: Duration = Duration::from_micros(1_000_000); - assert_eq!(FROM_MICROS, Duration::SECOND); - - const NANOS: u128 = Duration::SECOND.as_nanos(); - assert_eq!(NANOS, 1_000_000_000); - - const FROM_NANOS: Duration = Duration::from_nanos(1_000_000_000); - assert_eq!(FROM_NANOS, Duration::SECOND); - - const MAX: Duration = Duration::new(u64::MAX, 999_999_999); - - const CHECKED_ADD: Option = MAX.checked_add(Duration::SECOND); - assert_eq!(CHECKED_ADD, None); - - const CHECKED_SUB: Option = Duration::ZERO.checked_sub(Duration::SECOND); - assert_eq!(CHECKED_SUB, None); - - const CHECKED_MUL: Option = Duration::SECOND.checked_mul(1); - assert_eq!(CHECKED_MUL, Some(Duration::SECOND)); - - /* FIXME(#110395) - const MUL_F32: Duration = Duration::SECOND.mul_f32(1.0); - assert_eq!(MUL_F32, Duration::SECOND); - - const MUL_F64: Duration = Duration::SECOND.mul_f64(1.0); - assert_eq!(MUL_F64, Duration::SECOND); - - const CHECKED_DIV: Option = Duration::SECOND.checked_div(1); - assert_eq!(CHECKED_DIV, Some(Duration::SECOND)); - - const DIV_F32: Duration = Duration::SECOND.div_f32(1.0); - assert_eq!(DIV_F32, Duration::SECOND); - - const DIV_F64: Duration = Duration::SECOND.div_f64(1.0); - assert_eq!(DIV_F64, Duration::SECOND); - */ - - const DIV_DURATION_F32: f32 = Duration::SECOND.div_duration_f32(Duration::SECOND); - assert_eq!(DIV_DURATION_F32, 1.0); - - const DIV_DURATION_F64: f64 = Duration::SECOND.div_duration_f64(Duration::SECOND); - assert_eq!(DIV_DURATION_F64, 1.0); - - const SATURATING_ADD: Duration = MAX.saturating_add(Duration::SECOND); - assert_eq!(SATURATING_ADD, MAX); - - const SATURATING_SUB: Duration = Duration::ZERO.saturating_sub(Duration::SECOND); - assert_eq!(SATURATING_SUB, Duration::ZERO); - - const SATURATING_MUL: Duration = MAX.saturating_mul(2); - assert_eq!(SATURATING_MUL, MAX); -} - -#[test] -fn from_neg_zero() { - assert_eq!(Duration::try_from_secs_f32(-0.0), Ok(Duration::ZERO)); - assert_eq!(Duration::try_from_secs_f64(-0.0), Ok(Duration::ZERO)); - assert_eq!(Duration::from_secs_f32(-0.0), Duration::ZERO); - assert_eq!(Duration::from_secs_f64(-0.0), Duration::ZERO); -} diff --git a/library/core/tests/tuple.rs b/library/core/tests/tuple.rs deleted file mode 100644 index ea1e281425c89..0000000000000 --- a/library/core/tests/tuple.rs +++ /dev/null @@ -1,61 +0,0 @@ -use std::cmp::Ordering::{Equal, Greater, Less}; - -#[test] -fn test_clone() { - let a = (1, "2"); - let b = a.clone(); - assert_eq!(a, b); -} - -#[test] -fn test_partial_eq() { - let (small, big) = ((1, 2, 3), (3, 2, 1)); - assert_eq!(small, small); - assert_eq!(big, big); - assert_ne!(small, big); - assert_ne!(big, small); -} - -#[test] -fn test_partial_ord() { - let (small, big) = ((1, 2, 3), (3, 2, 1)); - - assert!(small < big); - assert!(!(small < small)); - assert!(!(big < small)); - assert!(!(big < big)); - - assert!(small <= small); - assert!(big <= big); - - assert!(big > small); - assert!(small >= small); - assert!(big >= small); - assert!(big >= big); - - assert!(!((1.0f64, 2.0f64) < (f64::NAN, 3.0))); - assert!(!((1.0f64, 2.0f64) <= (f64::NAN, 3.0))); - assert!(!((1.0f64, 2.0f64) > (f64::NAN, 3.0))); - assert!(!((1.0f64, 2.0f64) >= (f64::NAN, 3.0))); - assert!(((1.0f64, 2.0f64) < (2.0, f64::NAN))); - assert!(!((2.0f64, 2.0f64) < (2.0, f64::NAN))); -} - -#[test] -fn test_ord() { - let (small, big) = ((1, 2, 3), (3, 2, 1)); - assert_eq!(small.cmp(&small), Equal); - assert_eq!(big.cmp(&big), Equal); - assert_eq!(small.cmp(&big), Less); - assert_eq!(big.cmp(&small), Greater); -} - -#[test] -fn test_show() { - let s = format!("{:?}", (1,)); - assert_eq!(s, "(1,)"); - let s = format!("{:?}", (1, true)); - assert_eq!(s, "(1, true)"); - let s = format!("{:?}", (1, "hi", true)); - assert_eq!(s, "(1, \"hi\", true)"); -} diff --git a/library/core/tests/unicode.rs b/library/core/tests/unicode.rs deleted file mode 100644 index bbace0ef66ca3..0000000000000 --- a/library/core/tests/unicode.rs +++ /dev/null @@ -1,5 +0,0 @@ -#[test] -pub fn version() { - let (major, _minor, _update) = core::char::UNICODE_VERSION; - assert!(major >= 10); -} diff --git a/library/core/tests/waker.rs b/library/core/tests/waker.rs deleted file mode 100644 index 2c66e0d7ad3a4..0000000000000 --- a/library/core/tests/waker.rs +++ /dev/null @@ -1,22 +0,0 @@ -use std::ptr; -use std::task::{RawWaker, RawWakerVTable, Waker}; - -#[test] -fn test_waker_getters() { - let raw_waker = RawWaker::new(ptr::without_provenance_mut(42usize), &WAKER_VTABLE); - assert_eq!(raw_waker.data() as usize, 42); - assert!(ptr::eq(raw_waker.vtable(), &WAKER_VTABLE)); - - let waker = unsafe { Waker::from_raw(raw_waker) }; - let waker2 = waker.clone(); - let raw_waker2 = waker2.as_raw(); - assert_eq!(raw_waker2.data() as usize, 43); - assert!(ptr::eq(raw_waker2.vtable(), &WAKER_VTABLE)); -} - -static WAKER_VTABLE: RawWakerVTable = RawWakerVTable::new( - |data| RawWaker::new(ptr::without_provenance_mut(data as usize + 1), &WAKER_VTABLE), - |_| {}, - |_| {}, - |_| {}, -); diff --git a/library/panic_abort/Cargo.toml b/library/panic_abort/Cargo.toml deleted file mode 100644 index a9d1f53761cbf..0000000000000 --- a/library/panic_abort/Cargo.toml +++ /dev/null @@ -1,21 +0,0 @@ -[package] -name = "panic_abort" -version = "0.0.0" -license = "MIT OR Apache-2.0" -repository = "https://github.com/rust-lang/rust.git" -description = "Implementation of Rust panics via process aborts" -edition = "2021" - -[lib] -test = false -bench = false -doc = false - -[dependencies] -alloc = { path = "../alloc" } -cfg-if = { version = "1.0", features = ['rustc-dep-of-std'] } -core = { path = "../core" } -compiler_builtins = "0.1.0" - -[target.'cfg(not(all(windows, target_env = "msvc")))'.dependencies] -libc = { version = "0.2", default-features = false } diff --git a/library/panic_abort/src/android.rs b/library/panic_abort/src/android.rs deleted file mode 100644 index 47c22834597de..0000000000000 --- a/library/panic_abort/src/android.rs +++ /dev/null @@ -1,49 +0,0 @@ -use alloc::string::String; -use core::mem::transmute; -use core::panic::PanicPayload; -use core::ptr::copy_nonoverlapping; - -const ANDROID_SET_ABORT_MESSAGE: &[u8] = b"android_set_abort_message\0"; -type SetAbortMessageType = unsafe extern "C" fn(*const libc::c_char) -> (); - -// Forward the abort message to libc's android_set_abort_message. We try our best to populate the -// message but as this function may already be called as part of a failed allocation, it might not be -// possible to do so. -// -// Some methods of core are on purpose avoided (such as try_reserve) as these rely on the correct -// resolution of rust_eh_personality which is loosely defined in panic_abort. -// -// Weakly resolve the symbol for android_set_abort_message. This function is only available -// for API >= 21. -pub(crate) unsafe fn android_set_abort_message(payload: &mut dyn PanicPayload) { - let func_addr = - libc::dlsym(libc::RTLD_DEFAULT, ANDROID_SET_ABORT_MESSAGE.as_ptr() as *const libc::c_char) - as usize; - if func_addr == 0 { - return; - } - - let payload = payload.get(); - let msg = match payload.downcast_ref::<&'static str>() { - Some(msg) => msg.as_bytes(), - None => match payload.downcast_ref::() { - Some(msg) => msg.as_bytes(), - None => &[], - }, - }; - if msg.is_empty() { - return; - } - - // Allocate a new buffer to append the null byte. - let size = msg.len() + 1usize; - let buf = libc::malloc(size) as *mut libc::c_char; - if buf.is_null() { - return; // allocation failure - } - copy_nonoverlapping(msg.as_ptr(), buf as *mut u8, msg.len()); - buf.add(msg.len()).write(0); - - let func = transmute::(func_addr); - func(buf); -} diff --git a/library/panic_abort/src/lib.rs b/library/panic_abort/src/lib.rs deleted file mode 100644 index 353de8c5c5743..0000000000000 --- a/library/panic_abort/src/lib.rs +++ /dev/null @@ -1,148 +0,0 @@ -//! Implementation of Rust panics via process aborts -//! -//! When compared to the implementation via unwinding, this crate is *much* -//! simpler! That being said, it's not quite as versatile, but here goes! - -#![no_std] -#![unstable(feature = "panic_abort", issue = "32837")] -#![doc(issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/")] -#![panic_runtime] -#![allow(unused_features)] -#![feature(asm_experimental_arch)] -#![feature(core_intrinsics)] -#![feature(panic_runtime)] -#![feature(std_internals)] -#![feature(staged_api)] -#![feature(rustc_attrs)] -#![feature(c_unwind)] -#![allow(internal_features)] - -#[cfg(target_os = "android")] -mod android; - -#[cfg(target_os = "zkvm")] -mod zkvm; - -use core::any::Any; -use core::panic::PanicPayload; - -#[rustc_std_internal_symbol] -#[allow(improper_ctypes_definitions)] -pub unsafe extern "C" fn __rust_panic_cleanup(_: *mut u8) -> *mut (dyn Any + Send + 'static) { - unreachable!() -} - -// "Leak" the payload and shim to the relevant abort on the platform in question. -#[rustc_std_internal_symbol] -pub unsafe fn __rust_start_panic(_payload: &mut dyn PanicPayload) -> u32 { - // Android has the ability to attach a message as part of the abort. - #[cfg(target_os = "android")] - android::android_set_abort_message(_payload); - #[cfg(target_os = "zkvm")] - zkvm::zkvm_set_abort_message(_payload); - - abort(); - - cfg_if::cfg_if! { - if #[cfg(any(unix, target_os = "solid_asp3"))] { - unsafe fn abort() -> ! { - libc::abort(); - } - } else if #[cfg(any(target_os = "hermit", - all(target_vendor = "fortanix", target_env = "sgx"), - target_os = "xous", - target_os = "uefi", - ))] { - unsafe fn abort() -> ! { - // call std::sys::abort_internal - extern "C" { - pub fn __rust_abort() -> !; - } - __rust_abort(); - } - } else if #[cfg(all(windows, not(miri)))] { - // On Windows, use the processor-specific __fastfail mechanism. In Windows 8 - // and later, this will terminate the process immediately without running any - // in-process exception handlers. In earlier versions of Windows, this - // sequence of instructions will be treated as an access violation, - // terminating the process but without necessarily bypassing all exception - // handlers. - // - // https://docs.microsoft.com/en-us/cpp/intrinsics/fastfail - // - // Note: this is the same implementation as in std's `abort_internal` - unsafe fn abort() -> ! { - #[allow(unused)] - const FAST_FAIL_FATAL_APP_EXIT: usize = 7; - cfg_if::cfg_if! { - if #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] { - core::arch::asm!("int $$0x29", in("ecx") FAST_FAIL_FATAL_APP_EXIT, options(noreturn, nostack)); - } else if #[cfg(all(target_arch = "arm", target_feature = "thumb-mode"))] { - core::arch::asm!(".inst 0xDEFB", in("r0") FAST_FAIL_FATAL_APP_EXIT, options(noreturn, nostack)); - } else if #[cfg(any(target_arch = "aarch64", target_arch = "arm64ec"))] { - core::arch::asm!("brk 0xF003", in("x0") FAST_FAIL_FATAL_APP_EXIT, options(noreturn, nostack)); - } else { - core::intrinsics::abort(); - } - } - } - } else if #[cfg(target_os = "teeos")] { - mod teeos { - extern "C" { - pub fn TEE_Panic(code: u32) -> !; - } - } - - unsafe fn abort() -> ! { - teeos::TEE_Panic(1); - } - } else { - unsafe fn abort() -> ! { - core::intrinsics::abort(); - } - } - } -} - -// This... is a bit of an oddity. The tl;dr; is that this is required to link -// correctly, the longer explanation is below. -// -// Right now the binaries of core/std that we ship are all compiled with -// `-C panic=unwind`. This is done to ensure that the binaries are maximally -// compatible with as many situations as possible. The compiler, however, -// requires a "personality function" for all functions compiled with `-C -// panic=unwind`. This personality function is hardcoded to the symbol -// `rust_eh_personality` and is defined by the `eh_personality` lang item. -// -// So... why not just define that lang item here? Good question! The way that -// panic runtimes are linked in is actually a little subtle in that they're -// "sort of" in the compiler's crate store, but only actually linked if another -// isn't actually linked. This ends up meaning that both this crate and the -// panic_unwind crate can appear in the compiler's crate store, and if both -// define the `eh_personality` lang item then that'll hit an error. -// -// To handle this the compiler only requires the `eh_personality` is defined if -// the panic runtime being linked in is the unwinding runtime, and otherwise -// it's not required to be defined (rightfully so). In this case, however, this -// library just defines this symbol so there's at least some personality -// somewhere. -// -// Essentially this symbol is just defined to get wired up to core/std -// binaries, but it should never be called as we don't link in an unwinding -// runtime at all. -pub mod personalities { - // In the past this module used to contain stubs for the personality - // functions of various platforms, but these where removed when personality - // functions were moved to std. - - // This corresponds to the `eh_catch_typeinfo` lang item - // that's only used on Emscripten currently. - // - // Since panics don't generate exceptions and foreign exceptions are - // currently UB with -C panic=abort (although this may be subject to - // change), any catch_unwind calls will never use this typeinfo. - #[rustc_std_internal_symbol] - #[allow(non_upper_case_globals)] - #[cfg(target_os = "emscripten")] - static rust_eh_catch_typeinfo: [usize; 2] = [0; 2]; -} diff --git a/library/panic_abort/src/zkvm.rs b/library/panic_abort/src/zkvm.rs deleted file mode 100644 index a6a02abf10976..0000000000000 --- a/library/panic_abort/src/zkvm.rs +++ /dev/null @@ -1,24 +0,0 @@ -use alloc::string::String; -use core::panic::PanicPayload; - -// Forward the abort message to zkVM's sys_panic. This is implemented by RISC Zero's -// platform crate which exposes system calls specifically for the zkVM. -pub(crate) unsafe fn zkvm_set_abort_message(payload: &mut dyn PanicPayload) { - let payload = payload.get(); - let msg = match payload.downcast_ref::<&'static str>() { - Some(msg) => msg.as_bytes(), - None => match payload.downcast_ref::() { - Some(msg) => msg.as_bytes(), - None => &[], - }, - }; - if msg.is_empty() { - return; - } - - extern "C" { - fn sys_panic(msg_ptr: *const u8, len: usize) -> !; - } - - sys_panic(msg.as_ptr(), msg.len()); -} diff --git a/library/panic_unwind/Cargo.toml b/library/panic_unwind/Cargo.toml deleted file mode 100644 index dce2da3164440..0000000000000 --- a/library/panic_unwind/Cargo.toml +++ /dev/null @@ -1,22 +0,0 @@ -[package] -name = "panic_unwind" -version = "0.0.0" -license = "MIT OR Apache-2.0" -repository = "https://github.com/rust-lang/rust.git" -description = "Implementation of Rust panics via stack unwinding" -edition = "2021" - -[lib] -test = false -bench = false -doc = false - -[dependencies] -alloc = { path = "../alloc" } -core = { path = "../core" } -unwind = { path = "../unwind" } -compiler_builtins = "0.1.0" -cfg-if = "1.0" - -[target.'cfg(not(all(windows, target_env = "msvc")))'.dependencies] -libc = { version = "0.2", default-features = false } diff --git a/library/panic_unwind/src/dummy.rs b/library/panic_unwind/src/dummy.rs deleted file mode 100644 index a4bcd216c60f0..0000000000000 --- a/library/panic_unwind/src/dummy.rs +++ /dev/null @@ -1,15 +0,0 @@ -//! Unwinding for unsupported target. -//! -//! Stubs that simply abort for targets that don't support unwinding otherwise. - -use alloc::boxed::Box; -use core::any::Any; -use core::intrinsics; - -pub unsafe fn cleanup(_ptr: *mut u8) -> Box { - intrinsics::abort() -} - -pub unsafe fn panic(_data: Box) -> u32 { - intrinsics::abort() -} diff --git a/library/panic_unwind/src/emcc.rs b/library/panic_unwind/src/emcc.rs deleted file mode 100644 index fed4c52e83c5f..0000000000000 --- a/library/panic_unwind/src/emcc.rs +++ /dev/null @@ -1,132 +0,0 @@ -//! Unwinding for *emscripten* target. -//! -//! Whereas Rust's usual unwinding implementation for Unix platforms -//! calls into the libunwind APIs directly, on Emscripten we instead -//! call into the C++ unwinding APIs. This is just an expedience since -//! Emscripten's runtime always implements those APIs and does not -//! implement libunwind. - -use alloc::boxed::Box; -use core::any::Any; -use core::intrinsics; -use core::mem; -use core::ptr; -use core::sync::atomic::{AtomicBool, Ordering}; -use unwind as uw; - -// This matches the layout of std::type_info in C++ -#[repr(C)] -struct TypeInfo { - vtable: *const usize, - name: *const u8, -} -unsafe impl Sync for TypeInfo {} - -extern "C" { - // The leading `\x01` byte here is actually a magical signal to LLVM to - // *not* apply any other mangling like prefixing with a `_` character. - // - // This symbol is the vtable used by C++'s `std::type_info`. Objects of type - // `std::type_info`, type descriptors, have a pointer to this table. Type - // descriptors are referenced by the C++ EH structures defined above and - // that we construct below. - // - // Note that the real size is larger than 3 usize, but we only need our - // vtable to point to the third element. - #[link_name = "\x01_ZTVN10__cxxabiv117__class_type_infoE"] - static CLASS_TYPE_INFO_VTABLE: [usize; 3]; -} - -// std::type_info for a rust_panic class -#[lang = "eh_catch_typeinfo"] -static EXCEPTION_TYPE_INFO: TypeInfo = TypeInfo { - // Normally we would use .as_ptr().add(2) but this doesn't work in a const context. - vtable: unsafe { &CLASS_TYPE_INFO_VTABLE[2] }, - // This intentionally doesn't use the normal name mangling scheme because - // we don't want C++ to be able to produce or catch Rust panics. - name: b"rust_panic\0".as_ptr(), -}; - -// NOTE(nbdd0121): The `canary` field is part of stable ABI. -#[repr(C)] -struct Exception { - // See `gcc.rs` on why this is present. We already have a static here so just use it. - canary: *const TypeInfo, - - // This is necessary because C++ code can capture our exception with - // std::exception_ptr and rethrow it multiple times, possibly even in - // another thread. - caught: AtomicBool, - - // This needs to be an Option because the object's lifetime follows C++ - // semantics: when catch_unwind moves the Box out of the exception it must - // still leave the exception object in a valid state because its destructor - // is still going to be called by __cxa_end_catch. - data: Option>, -} - -pub unsafe fn cleanup(ptr: *mut u8) -> Box { - // intrinsics::try actually gives us a pointer to this structure. - #[repr(C)] - struct CatchData { - ptr: *mut u8, - is_rust_panic: bool, - } - let catch_data = &*(ptr as *mut CatchData); - - let adjusted_ptr = __cxa_begin_catch(catch_data.ptr as *mut libc::c_void) as *mut Exception; - if !catch_data.is_rust_panic { - super::__rust_foreign_exception(); - } - - let canary = ptr::addr_of!((*adjusted_ptr).canary).read(); - if !ptr::eq(canary, &EXCEPTION_TYPE_INFO) { - super::__rust_foreign_exception(); - } - - let was_caught = (*adjusted_ptr).caught.swap(true, Ordering::Relaxed); - if was_caught { - // Since cleanup() isn't allowed to panic, we just abort instead. - intrinsics::abort(); - } - let out = (*adjusted_ptr).data.take().unwrap(); - __cxa_end_catch(); - out -} - -pub unsafe fn panic(data: Box) -> u32 { - let exception = __cxa_allocate_exception(mem::size_of::()) as *mut Exception; - if exception.is_null() { - return uw::_URC_FATAL_PHASE1_ERROR as u32; - } - ptr::write( - exception, - Exception { - canary: &EXCEPTION_TYPE_INFO, - caught: AtomicBool::new(false), - data: Some(data), - }, - ); - __cxa_throw(exception as *mut _, &EXCEPTION_TYPE_INFO, exception_cleanup); -} - -extern "C" fn exception_cleanup(ptr: *mut libc::c_void) -> *mut libc::c_void { - unsafe { - if let Some(b) = (ptr as *mut Exception).read().data { - drop(b); - super::__rust_drop_panic(); - } - ptr - } -} - -extern "C" { - fn __cxa_allocate_exception(thrown_size: libc::size_t) -> *mut libc::c_void; - fn __cxa_begin_catch(thrown_exception: *mut libc::c_void) -> *mut libc::c_void; - fn __cxa_end_catch(); - fn __cxa_throw( - thrown_exception: *mut libc::c_void, - tinfo: *const TypeInfo, - dest: extern "C" fn(*mut libc::c_void) -> *mut libc::c_void, - ) -> !; -} diff --git a/library/panic_unwind/src/gcc.rs b/library/panic_unwind/src/gcc.rs deleted file mode 100644 index 589d3c1b4d2d0..0000000000000 --- a/library/panic_unwind/src/gcc.rs +++ /dev/null @@ -1,113 +0,0 @@ -//! Implementation of panics backed by libgcc/libunwind (in some form). -//! -//! For background on exception handling and stack unwinding please see -//! "Exception Handling in LLVM" (llvm.org/docs/ExceptionHandling.html) and -//! documents linked from it. -//! These are also good reads: -//! * -//! * -//! * -//! -//! ## A brief summary -//! -//! Exception handling happens in two phases: a search phase and a cleanup -//! phase. -//! -//! In both phases the unwinder walks stack frames from top to bottom using -//! information from the stack frame unwind sections of the current process's -//! modules ("module" here refers to an OS module, i.e., an executable or a -//! dynamic library). -//! -//! For each stack frame, it invokes the associated "personality routine", whose -//! address is also stored in the unwind info section. -//! -//! In the search phase, the job of a personality routine is to examine -//! exception object being thrown, and to decide whether it should be caught at -//! that stack frame. Once the handler frame has been identified, cleanup phase -//! begins. -//! -//! In the cleanup phase, the unwinder invokes each personality routine again. -//! This time it decides which (if any) cleanup code needs to be run for -//! the current stack frame. If so, the control is transferred to a special -//! branch in the function body, the "landing pad", which invokes destructors, -//! frees memory, etc. At the end of the landing pad, control is transferred -//! back to the unwinder and unwinding resumes. -//! -//! Once stack has been unwound down to the handler frame level, unwinding stops -//! and the last personality routine transfers control to the catch block. - -use alloc::boxed::Box; -use core::any::Any; -use core::ptr; - -use unwind as uw; - -// In case where multiple copies of std exist in a single process, -// we use address of this static variable to distinguish an exception raised by -// this copy and some other copy (which needs to be treated as foreign exception). -static CANARY: u8 = 0; - -// NOTE(nbdd0121) -// There is an ABI stability requirement on this struct. -// The first two field must be `_Unwind_Exception` and `canary`, -// as it may be accessed by a different version of the std with a different compiler. -#[repr(C)] -struct Exception { - _uwe: uw::_Unwind_Exception, - canary: *const u8, - cause: Box, -} - -pub unsafe fn panic(data: Box) -> u32 { - let exception = Box::new(Exception { - _uwe: uw::_Unwind_Exception { - exception_class: rust_exception_class(), - exception_cleanup: Some(exception_cleanup), - private: [core::ptr::null(); uw::unwinder_private_data_size], - }, - canary: &CANARY, - cause: data, - }); - let exception_param = Box::into_raw(exception) as *mut uw::_Unwind_Exception; - return uw::_Unwind_RaiseException(exception_param) as u32; - - extern "C" fn exception_cleanup( - _unwind_code: uw::_Unwind_Reason_Code, - exception: *mut uw::_Unwind_Exception, - ) { - unsafe { - let _: Box = Box::from_raw(exception as *mut Exception); - super::__rust_drop_panic(); - } - } -} - -pub unsafe fn cleanup(ptr: *mut u8) -> Box { - let exception = ptr as *mut uw::_Unwind_Exception; - if (*exception).exception_class != rust_exception_class() { - uw::_Unwind_DeleteException(exception); - super::__rust_foreign_exception(); - } - - let exception = exception.cast::(); - // Just access the canary field, avoid accessing the entire `Exception` as - // it can be a foreign Rust exception. - let canary = ptr::addr_of!((*exception).canary).read(); - if !ptr::eq(canary, &CANARY) { - // A foreign Rust exception, treat it slightly differently from other - // foreign exceptions, because call into `_Unwind_DeleteException` will - // call into `__rust_drop_panic` which produces a confusing - // "Rust panic must be rethrown" message. - super::__rust_foreign_exception(); - } - - let exception = Box::from_raw(exception as *mut Exception); - exception.cause -} - -// Rust's exception class identifier. This is used by personality routines to -// determine whether the exception was thrown by their own runtime. -fn rust_exception_class() -> uw::_Unwind_Exception_Class { - // M O Z \0 R U S T -- vendor, language - 0x4d4f5a_00_52555354 -} diff --git a/library/panic_unwind/src/hermit.rs b/library/panic_unwind/src/hermit.rs deleted file mode 100644 index 69b9edb77c564..0000000000000 --- a/library/panic_unwind/src/hermit.rs +++ /dev/null @@ -1,20 +0,0 @@ -//! Unwinding for *hermit* target. -//! -//! Right now we don't support this, so this is just stubs. - -use alloc::boxed::Box; -use core::any::Any; - -pub unsafe fn cleanup(_ptr: *mut u8) -> Box { - extern "C" { - pub fn __rust_abort() -> !; - } - __rust_abort(); -} - -pub unsafe fn panic(_data: Box) -> u32 { - extern "C" { - pub fn __rust_abort() -> !; - } - __rust_abort(); -} diff --git a/library/panic_unwind/src/lib.rs b/library/panic_unwind/src/lib.rs deleted file mode 100644 index b0245de501e7e..0000000000000 --- a/library/panic_unwind/src/lib.rs +++ /dev/null @@ -1,109 +0,0 @@ -//! Implementation of panics via stack unwinding -//! -//! This crate is an implementation of panics in Rust using "most native" stack -//! unwinding mechanism of the platform this is being compiled for. This -//! essentially gets categorized into three buckets currently: -//! -//! 1. MSVC targets use SEH in the `seh.rs` file. -//! 2. Emscripten uses C++ exceptions in the `emcc.rs` file. -//! 3. All other targets use libunwind/libgcc in the `gcc.rs` file. -//! -//! More documentation about each implementation can be found in the respective -//! module. - -#![no_std] -#![unstable(feature = "panic_unwind", issue = "32837")] -#![doc(issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/")] -#![feature(core_intrinsics)] -#![feature(lang_items)] -#![feature(panic_unwind)] -#![feature(staged_api)] -#![feature(std_internals)] -#![feature(strict_provenance)] -#![feature(exposed_provenance)] -#![feature(rustc_attrs)] -#![panic_runtime] -#![feature(panic_runtime)] -#![feature(c_unwind)] -// `real_imp` is unused with Miri, so silence warnings. -#![cfg_attr(miri, allow(dead_code))] -#![allow(internal_features)] - -use alloc::boxed::Box; -use core::any::Any; -use core::panic::PanicPayload; - -cfg_if::cfg_if! { - if #[cfg(target_os = "emscripten")] { - #[path = "emcc.rs"] - mod real_imp; - } else if #[cfg(target_os = "hermit")] { - #[path = "hermit.rs"] - mod real_imp; - } else if #[cfg(target_os = "l4re")] { - // L4Re is unix family but does not yet support unwinding. - #[path = "dummy.rs"] - mod real_imp; - } else if #[cfg(all(target_env = "msvc", not(target_arch = "arm")))] { - // LLVM does not support unwinding on 32 bit ARM msvc (thumbv7a-pc-windows-msvc) - #[path = "seh.rs"] - mod real_imp; - } else if #[cfg(any( - all(target_family = "windows", target_env = "gnu"), - target_os = "psp", - target_os = "xous", - target_os = "solid_asp3", - all(target_family = "unix", not(target_os = "espidf")), - all(target_vendor = "fortanix", target_env = "sgx"), - target_family = "wasm", - ))] { - #[path = "gcc.rs"] - mod real_imp; - } else { - // Targets that don't support unwinding. - // - os=none ("bare metal" targets) - // - os=uefi - // - os=espidf - // - nvptx64-nvidia-cuda - // - arch=avr - #[path = "dummy.rs"] - mod real_imp; - } -} - -cfg_if::cfg_if! { - if #[cfg(miri)] { - // Use the Miri runtime. - // We still need to also load the normal runtime above, as rustc expects certain lang - // items from there to be defined. - #[path = "miri.rs"] - mod imp; - } else { - // Use the real runtime. - use real_imp as imp; - } -} - -extern "C" { - /// Handler in std called when a panic object is dropped outside of - /// `catch_unwind`. - fn __rust_drop_panic() -> !; - - /// Handler in std called when a foreign exception is caught. - fn __rust_foreign_exception() -> !; -} - -#[rustc_std_internal_symbol] -#[allow(improper_ctypes_definitions)] -pub unsafe extern "C" fn __rust_panic_cleanup(payload: *mut u8) -> *mut (dyn Any + Send + 'static) { - Box::into_raw(imp::cleanup(payload)) -} - -// Entry point for raising an exception, just delegates to the platform-specific -// implementation. -#[rustc_std_internal_symbol] -pub unsafe fn __rust_start_panic(payload: &mut dyn PanicPayload) -> u32 { - let payload = Box::from_raw(payload.take_box()); - - imp::panic(payload) -} diff --git a/library/panic_unwind/src/miri.rs b/library/panic_unwind/src/miri.rs deleted file mode 100644 index 4d21e846010e9..0000000000000 --- a/library/panic_unwind/src/miri.rs +++ /dev/null @@ -1,25 +0,0 @@ -//! Unwinding panics for Miri. -use alloc::boxed::Box; -use core::any::Any; - -// The type of the payload that the Miri engine propagates through unwinding for us. -// Must be pointer-sized. -type Payload = Box>; - -extern "Rust" { - /// Miri-provided extern function to begin unwinding. - fn miri_start_unwind(payload: *mut u8) -> !; -} - -pub unsafe fn panic(payload: Box) -> u32 { - // The payload we pass to `miri_start_unwind` will be exactly the argument we get - // in `cleanup` below. So we just box it up once, to get something pointer-sized. - let payload_box: Payload = Box::new(payload); - miri_start_unwind(Box::into_raw(payload_box) as *mut u8) -} - -pub unsafe fn cleanup(payload_box: *mut u8) -> Box { - // Recover the underlying `Box`. - let payload_box: Payload = Box::from_raw(payload_box as *mut _); - *payload_box -} diff --git a/library/panic_unwind/src/seh.rs b/library/panic_unwind/src/seh.rs deleted file mode 100644 index 04c3d3bf9c359..0000000000000 --- a/library/panic_unwind/src/seh.rs +++ /dev/null @@ -1,369 +0,0 @@ -//! Windows SEH -//! -//! On Windows (currently only on MSVC), the default exception handling -//! mechanism is Structured Exception Handling (SEH). This is quite different -//! than Dwarf-based exception handling (e.g., what other unix platforms use) in -//! terms of compiler internals, so LLVM is required to have a good deal of -//! extra support for SEH. -//! -//! In a nutshell, what happens here is: -//! -//! 1. The `panic` function calls the standard Windows function -//! `_CxxThrowException` to throw a C++-like exception, triggering the -//! unwinding process. -//! 2. All landing pads generated by the compiler use the personality function -//! `__CxxFrameHandler3`, a function in the CRT, and the unwinding code in -//! Windows will use this personality function to execute all cleanup code on -//! the stack. -//! 3. All compiler-generated calls to `invoke` have a landing pad set as a -//! `cleanuppad` LLVM instruction, which indicates the start of the cleanup -//! routine. The personality (in step 2, defined in the CRT) is responsible -//! for running the cleanup routines. -//! 4. Eventually the "catch" code in the `try` intrinsic (generated by the -//! compiler) is executed and indicates that control should come back to -//! Rust. This is done via a `catchswitch` plus a `catchpad` instruction in -//! LLVM IR terms, finally returning normal control to the program with a -//! `catchret` instruction. -//! -//! Some specific differences from the gcc-based exception handling are: -//! -//! * Rust has no custom personality function, it is instead *always* -//! `__CxxFrameHandler3`. Additionally, no extra filtering is performed, so we -//! end up catching any C++ exceptions that happen to look like the kind we're -//! throwing. Note that throwing an exception into Rust is undefined behavior -//! anyway, so this should be fine. -//! * We've got some data to transmit across the unwinding boundary, -//! specifically a `Box`. Like with Dwarf exceptions -//! these two pointers are stored as a payload in the exception itself. On -//! MSVC, however, there's no need for an extra heap allocation because the -//! call stack is preserved while filter functions are being executed. This -//! means that the pointers are passed directly to `_CxxThrowException` which -//! are then recovered in the filter function to be written to the stack frame -//! of the `try` intrinsic. -//! -//! [win64]: https://docs.microsoft.com/en-us/cpp/build/exception-handling-x64 -//! [llvm]: https://llvm.org/docs/ExceptionHandling.html#background-on-windows-exceptions - -#![allow(nonstandard_style)] - -use alloc::boxed::Box; -use core::any::Any; -use core::ffi::{c_int, c_uint, c_void}; -use core::mem::{self, ManuallyDrop}; -use core::ptr::{addr_of, addr_of_mut}; - -// NOTE(nbdd0121): The `canary` field is part of stable ABI. -#[repr(C)] -struct Exception { - // See `gcc.rs` on why this is present. We already have a static here so just use it. - canary: *const _TypeDescriptor, - - // This needs to be an Option because we catch the exception by reference - // and its destructor is executed by the C++ runtime. When we take the Box - // out of the exception, we need to leave the exception in a valid state - // for its destructor to run without double-dropping the Box. - data: Option>, -} - -// First up, a whole bunch of type definitions. There's a few platform-specific -// oddities here, and a lot that's just blatantly copied from LLVM. The purpose -// of all this is to implement the `panic` function below through a call to -// `_CxxThrowException`. -// -// This function takes two arguments. The first is a pointer to the data we're -// passing in, which in this case is our trait object. Pretty easy to find! The -// next, however, is more complicated. This is a pointer to a `_ThrowInfo` -// structure, and it generally is just intended to just describe the exception -// being thrown. -// -// Currently the definition of this type [1] is a little hairy, and the main -// oddity (and difference from the online article) is that on 32-bit the -// pointers are pointers but on 64-bit the pointers are expressed as 32-bit -// offsets from the `__ImageBase` symbol. The `ptr_t` and `ptr!` macro in the -// modules below are used to express this. -// -// The maze of type definitions also closely follows what LLVM emits for this -// sort of operation. For example, if you compile this C++ code on MSVC and emit -// the LLVM IR: -// -// #include -// -// struct rust_panic { -// rust_panic(const rust_panic&); -// ~rust_panic(); -// -// uint64_t x[2]; -// }; -// -// void foo() { -// rust_panic a = {0, 1}; -// throw a; -// } -// -// That's essentially what we're trying to emulate. Most of the constant values -// below were just copied from LLVM, -// -// In any case, these structures are all constructed in a similar manner, and -// it's just somewhat verbose for us. -// -// [1]: https://www.geoffchappell.com/studies/msvc/language/predefined/ - -#[cfg(target_arch = "x86")] -mod imp { - #[repr(transparent)] - #[derive(Copy, Clone)] - pub struct ptr_t(*mut u8); - - impl ptr_t { - pub const fn null() -> Self { - Self(core::ptr::null_mut()) - } - - pub const fn new(ptr: *mut u8) -> Self { - Self(ptr) - } - - pub const fn raw(self) -> *mut u8 { - self.0 - } - } -} - -#[cfg(not(target_arch = "x86"))] -mod imp { - use core::ptr::addr_of; - - // On 64-bit systems, SEH represents pointers as 32-bit offsets from `__ImageBase`. - #[repr(transparent)] - #[derive(Copy, Clone)] - pub struct ptr_t(u32); - - extern "C" { - pub static __ImageBase: u8; - } - - impl ptr_t { - pub const fn null() -> Self { - Self(0) - } - - pub fn new(ptr: *mut u8) -> Self { - // We need to expose the provenance of the pointer because it is not carried by - // the `u32`, while the FFI needs to have this provenance to excess our statics. - // - // NOTE(niluxv): we could use `MaybeUninit` instead to leak the provenance - // into the FFI. In theory then the other side would need to do some processing - // to get a pointer with correct provenance, but these system functions aren't - // going to be cross-lang LTOed anyway. However, using expose is shorter and - // requires less unsafe. - let addr: usize = ptr.expose_provenance(); - let image_base = unsafe { addr_of!(__ImageBase) }.addr(); - let offset: usize = addr - image_base; - Self(offset as u32) - } - - pub const fn raw(self) -> u32 { - self.0 - } - } -} - -use imp::ptr_t; - -#[repr(C)] -pub struct _ThrowInfo { - pub attributes: c_uint, - pub pmfnUnwind: ptr_t, - pub pForwardCompat: ptr_t, - pub pCatchableTypeArray: ptr_t, -} - -#[repr(C)] -pub struct _CatchableTypeArray { - pub nCatchableTypes: c_int, - pub arrayOfCatchableTypes: [ptr_t; 1], -} - -#[repr(C)] -pub struct _CatchableType { - pub properties: c_uint, - pub pType: ptr_t, - pub thisDisplacement: _PMD, - pub sizeOrOffset: c_int, - pub copyFunction: ptr_t, -} - -#[repr(C)] -pub struct _PMD { - pub mdisp: c_int, - pub pdisp: c_int, - pub vdisp: c_int, -} - -#[repr(C)] -pub struct _TypeDescriptor { - pub pVFTable: *const u8, - pub spare: *mut u8, - pub name: [u8; 11], -} - -// Note that we intentionally ignore name mangling rules here: we don't want C++ -// to be able to catch Rust panics by simply declaring a `struct rust_panic`. -// -// When modifying, make sure that the type name string exactly matches -// the one used in `compiler/rustc_codegen_llvm/src/intrinsic.rs`. -const TYPE_NAME: [u8; 11] = *b"rust_panic\0"; - -static mut THROW_INFO: _ThrowInfo = _ThrowInfo { - attributes: 0, - pmfnUnwind: ptr_t::null(), - pForwardCompat: ptr_t::null(), - pCatchableTypeArray: ptr_t::null(), -}; - -static mut CATCHABLE_TYPE_ARRAY: _CatchableTypeArray = - _CatchableTypeArray { nCatchableTypes: 1, arrayOfCatchableTypes: [ptr_t::null()] }; - -static mut CATCHABLE_TYPE: _CatchableType = _CatchableType { - properties: 0, - pType: ptr_t::null(), - thisDisplacement: _PMD { mdisp: 0, pdisp: -1, vdisp: 0 }, - sizeOrOffset: mem::size_of::() as c_int, - copyFunction: ptr_t::null(), -}; - -extern "C" { - // The leading `\x01` byte here is actually a magical signal to LLVM to - // *not* apply any other mangling like prefixing with a `_` character. - // - // This symbol is the vtable used by C++'s `std::type_info`. Objects of type - // `std::type_info`, type descriptors, have a pointer to this table. Type - // descriptors are referenced by the C++ EH structures defined above and - // that we construct below. - #[link_name = "\x01??_7type_info@@6B@"] - static TYPE_INFO_VTABLE: *const u8; -} - -// This type descriptor is only used when throwing an exception. The catch part -// is handled by the try intrinsic, which generates its own TypeDescriptor. -// -// This is fine since the MSVC runtime uses string comparison on the type name -// to match TypeDescriptors rather than pointer equality. -static mut TYPE_DESCRIPTOR: _TypeDescriptor = _TypeDescriptor { - pVFTable: unsafe { addr_of!(TYPE_INFO_VTABLE) } as *const _, - spare: core::ptr::null_mut(), - name: TYPE_NAME, -}; - -// Destructor used if the C++ code decides to capture the exception and drop it -// without propagating it. The catch part of the try intrinsic will set the -// first word of the exception object to 0 so that it is skipped by the -// destructor. -// -// Note that x86 Windows uses the "thiscall" calling convention for C++ member -// functions instead of the default "C" calling convention. -// -// The exception_copy function is a bit special here: it is invoked by the MSVC -// runtime under a try/catch block and the panic that we generate here will be -// used as the result of the exception copy. This is used by the C++ runtime to -// support capturing exceptions with std::exception_ptr, which we can't support -// because Box isn't clonable. -macro_rules! define_cleanup { - ($abi:tt $abi2:tt) => { - unsafe extern $abi fn exception_cleanup(e: *mut Exception) { - if let Exception { data: Some(b), .. } = e.read() { - drop(b); - super::__rust_drop_panic(); - } - } - unsafe extern $abi2 fn exception_copy( - _dest: *mut Exception, _src: *mut Exception - ) -> *mut Exception { - panic!("Rust panics cannot be copied"); - } - } -} -cfg_if::cfg_if! { - if #[cfg(target_arch = "x86")] { - define_cleanup!("thiscall" "thiscall-unwind"); - } else { - define_cleanup!("C" "C-unwind"); - } -} - -pub unsafe fn panic(data: Box) -> u32 { - use core::intrinsics::atomic_store_seqcst; - - // _CxxThrowException executes entirely on this stack frame, so there's no - // need to otherwise transfer `data` to the heap. We just pass a stack - // pointer to this function. - // - // The ManuallyDrop is needed here since we don't want Exception to be - // dropped when unwinding. Instead it will be dropped by exception_cleanup - // which is invoked by the C++ runtime. - let mut exception = - ManuallyDrop::new(Exception { canary: addr_of!(TYPE_DESCRIPTOR), data: Some(data) }); - let throw_ptr = addr_of_mut!(exception) as *mut _; - - // This... may seems surprising, and justifiably so. On 32-bit MSVC the - // pointers between these structure are just that, pointers. On 64-bit MSVC, - // however, the pointers between structures are rather expressed as 32-bit - // offsets from `__ImageBase`. - // - // Consequently, on 32-bit MSVC we can declare all these pointers in the - // `static`s above. On 64-bit MSVC, we would have to express subtraction of - // pointers in statics, which Rust does not currently allow, so we can't - // actually do that. - // - // The next best thing, then is to fill in these structures at runtime - // (panicking is already the "slow path" anyway). So here we reinterpret all - // of these pointer fields as 32-bit integers and then store the - // relevant value into it (atomically, as concurrent panics may be - // happening). Technically the runtime will probably do a nonatomic read of - // these fields, but in theory they never read the *wrong* value so it - // shouldn't be too bad... - // - // In any case, we basically need to do something like this until we can - // express more operations in statics (and we may never be able to). - atomic_store_seqcst( - addr_of_mut!(THROW_INFO.pmfnUnwind).cast(), - ptr_t::new(exception_cleanup as *mut u8).raw(), - ); - atomic_store_seqcst( - addr_of_mut!(THROW_INFO.pCatchableTypeArray).cast(), - ptr_t::new(addr_of_mut!(CATCHABLE_TYPE_ARRAY).cast()).raw(), - ); - atomic_store_seqcst( - addr_of_mut!(CATCHABLE_TYPE_ARRAY.arrayOfCatchableTypes[0]).cast(), - ptr_t::new(addr_of_mut!(CATCHABLE_TYPE).cast()).raw(), - ); - atomic_store_seqcst( - addr_of_mut!(CATCHABLE_TYPE.pType).cast(), - ptr_t::new(addr_of_mut!(TYPE_DESCRIPTOR).cast()).raw(), - ); - atomic_store_seqcst( - addr_of_mut!(CATCHABLE_TYPE.copyFunction).cast(), - ptr_t::new(exception_copy as *mut u8).raw(), - ); - - extern "system-unwind" { - fn _CxxThrowException(pExceptionObject: *mut c_void, pThrowInfo: *mut u8) -> !; - } - - _CxxThrowException(throw_ptr, addr_of_mut!(THROW_INFO) as *mut _); -} - -pub unsafe fn cleanup(payload: *mut u8) -> Box { - // A null payload here means that we got here from the catch (...) of - // __rust_try. This happens when a non-Rust foreign exception is caught. - if payload.is_null() { - super::__rust_foreign_exception(); - } - let exception = payload as *mut Exception; - let canary = addr_of!((*exception).canary).read(); - if !core::ptr::eq(canary, addr_of!(TYPE_DESCRIPTOR)) { - // A foreign Rust exception. - super::__rust_foreign_exception(); - } - (*exception).data.take().unwrap() -} diff --git a/library/portable-simd/.github/ISSUE_TEMPLATE/blank_issue.md b/library/portable-simd/.github/ISSUE_TEMPLATE/blank_issue.md deleted file mode 100644 index 9aef3ebe637a1..0000000000000 --- a/library/portable-simd/.github/ISSUE_TEMPLATE/blank_issue.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -name: Blank Issue -about: Create a blank issue. ---- diff --git a/library/portable-simd/.github/ISSUE_TEMPLATE/bug_report.md b/library/portable-simd/.github/ISSUE_TEMPLATE/bug_report.md deleted file mode 100644 index 16a8251d52ba9..0000000000000 --- a/library/portable-simd/.github/ISSUE_TEMPLATE/bug_report.md +++ /dev/null @@ -1,50 +0,0 @@ ---- -name: Bug Report -about: Create a bug report for Rust. -labels: C-bug ---- - - -I tried this code: - -```rust - -``` - -I expected to see this happen: *explanation* - -Instead, this happened: *explanation* - -### Meta - -`rustc --version --verbose`: -``` - -``` - - -`crate version in Cargo.toml`: -```toml -[dependencies] -stdsimd = -``` - - - - -

Backtrace -

- -``` - -``` - -

-
diff --git a/library/portable-simd/.github/ISSUE_TEMPLATE/config.yml b/library/portable-simd/.github/ISSUE_TEMPLATE/config.yml deleted file mode 100644 index 1567542c01a4c..0000000000000 --- a/library/portable-simd/.github/ISSUE_TEMPLATE/config.yml +++ /dev/null @@ -1,10 +0,0 @@ -# This only controls whether a tiny, hard-to-find "open a blank issue" link appears at the end of -# the template list. -blank_issues_enabled: true -contact_links: - - name: Intrinsic Support - url: https://github.com/rust-lang/stdarch/issues - about: Please direct issues about Rust's support for vendor intrinsics to core::arch - - name: Internal Compiler Error - url: https://github.com/rust-lang/rust/issues - about: Please report ICEs to the rustc repository diff --git a/library/portable-simd/.github/ISSUE_TEMPLATE/feature_request.md b/library/portable-simd/.github/ISSUE_TEMPLATE/feature_request.md deleted file mode 100644 index be6c9e3d17e25..0000000000000 --- a/library/portable-simd/.github/ISSUE_TEMPLATE/feature_request.md +++ /dev/null @@ -1,14 +0,0 @@ ---- -name: Feature Request -about: Request an addition to the core::simd API -labels: C-feature-request ---- - diff --git a/library/portable-simd/.github/PULL_REQUEST_TEMPLATE.md b/library/portable-simd/.github/PULL_REQUEST_TEMPLATE.md deleted file mode 100644 index 31422b7934501..0000000000000 --- a/library/portable-simd/.github/PULL_REQUEST_TEMPLATE.md +++ /dev/null @@ -1,18 +0,0 @@ -Hello, welcome to `std::simd`! - -It seems this pull request template checklist was created while a lot of vector math ops were being implemented, and only really applies to ops. Feel free to delete everything here if it's not applicable, or ask for help if you're not sure what it means! - -For a given vector math operation on TxN, please add tests for interactions with: - - [ ] `T::MAX` - - [ ] `T::MIN` - - [ ] -1 - - [ ] 1 - - [ ] 0 - - -For a given vector math operation on TxN where T is a float, please add tests for test interactions with: - - [ ] a really large number, larger than the mantissa - - [ ] a really small "subnormal" number - - [ ] NaN - - [ ] Infinity - - [ ] Negative Infinity diff --git a/library/portable-simd/.github/workflows/ci.yml b/library/portable-simd/.github/workflows/ci.yml deleted file mode 100644 index b292be2d6f999..0000000000000 --- a/library/portable-simd/.github/workflows/ci.yml +++ /dev/null @@ -1,275 +0,0 @@ -name: CI - -on: - pull_request: - push: - branches: - - master - -env: - CARGO_NET_RETRY: 10 - RUSTUP_MAX_RETRIES: 10 - -jobs: - rustfmt: - name: "rustfmt" - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v2 - - name: Setup Rust - run: | - rustup update nightly --no-self-update - rustup default nightly - rustup component add rustfmt - - name: Run rustfmt - run: cargo fmt --all -- --check - - clippy: - name: "clippy on ${{ matrix.target }}" - runs-on: ubuntu-latest - strategy: - fail-fast: false - matrix: - target: - # We shouldn't really have any OS-specific code, so think of this as a list of architectures - - x86_64-unknown-linux-gnu - - i686-unknown-linux-gnu - - i586-unknown-linux-gnu - - aarch64-unknown-linux-gnu - - armv7-unknown-linux-gnueabihf - # non-nightly since https://github.com/rust-lang/rust/pull/113274 - # - mips-unknown-linux-gnu - # - mips64-unknown-linux-gnuabi64 - - powerpc-unknown-linux-gnu - - powerpc64-unknown-linux-gnu - - riscv64gc-unknown-linux-gnu - - s390x-unknown-linux-gnu - - sparc64-unknown-linux-gnu - - wasm32-unknown-unknown - - steps: - - uses: actions/checkout@v2 - - name: Setup Rust - run: | - rustup update nightly --no-self-update - rustup default nightly - rustup target add ${{ matrix.target }} - rustup component add clippy - - name: Run Clippy - run: cargo clippy --all-targets --target ${{ matrix.target }} - - x86-tests: - name: "${{ matrix.target_feature }} on ${{ matrix.target }}" - runs-on: ${{ matrix.os }} - strategy: - fail-fast: false - matrix: - target: [x86_64-pc-windows-msvc, i686-pc-windows-msvc, i586-pc-windows-msvc, x86_64-unknown-linux-gnu, x86_64-apple-darwin] - # `default` means we use the default target config for the target, - # `native` means we run with `-Ctarget-cpu=native`, and anything else is - # an arg to `-Ctarget-feature` - target_feature: [default, native, +sse3, +ssse3, +sse4.1, +sse4.2, +avx, +avx2] - - exclude: - # The macos runners seem to only reliably support up to `avx`. - - { target: x86_64-apple-darwin, target_feature: +avx2 } - # These features are statically known to be present for all 64 bit - # macs, and thus are covered by the `default` test - - { target: x86_64-apple-darwin, target_feature: +sse3 } - - { target: x86_64-apple-darwin, target_feature: +ssse3 } - # -Ctarget-cpu=native sounds like bad-news if target != host - - { target: i686-pc-windows-msvc, target_feature: native } - - { target: i586-pc-windows-msvc, target_feature: native } - - include: - # Populate the `matrix.os` field - - { target: x86_64-apple-darwin, os: macos-latest } - - { target: x86_64-unknown-linux-gnu, os: ubuntu-latest } - - { target: x86_64-pc-windows-msvc, os: windows-latest } - - { target: i686-pc-windows-msvc, os: windows-latest } - - { target: i586-pc-windows-msvc, os: windows-latest } - - # These are globally available on all the other targets. - - { target: i586-pc-windows-msvc, target_feature: +sse, os: windows-latest } - - { target: i586-pc-windows-msvc, target_feature: +sse2, os: windows-latest } - - # Annoyingly, the x86_64-unknown-linux-gnu runner *almost* always has - # avx512vl, but occasionally doesn't. Maybe one day we can enable it. - - steps: - - uses: actions/checkout@v2 - - name: Setup Rust - run: | - rustup update nightly --no-self-update - rustup default nightly - rustup target add ${{ matrix.target }} - - - name: Configure RUSTFLAGS - shell: bash - run: | - case "${{ matrix.target_feature }}" in - default) - echo "RUSTFLAGS=-Dwarnings" >> $GITHUB_ENV;; - native) - echo "RUSTFLAGS=-Dwarnings -Ctarget-cpu=native" >> $GITHUB_ENV - ;; - *) - echo "RUSTFLAGS=-Dwarnings -Ctarget-feature=${{ matrix.target_feature }}" >> $GITHUB_ENV - ;; - esac - - # Super useful for debugging why a SIGILL occurred. - - name: Dump target configuration and support - run: | - rustc -Vv - - echo "Caveat: not all target features are expected to be logged" - - echo "## Requested target configuration (RUSTFLAGS=$RUSTFLAGS)" - rustc --print=cfg --target=${{ matrix.target }} $RUSTFLAGS - - echo "## Supported target configuration for --target=${{ matrix.target }}" - rustc --print=cfg --target=${{ matrix.target }} -Ctarget-cpu=native - - echo "## Natively supported target configuration" - rustc --print=cfg -Ctarget-cpu=native - - - name: Test (debug) - run: cargo test --verbose --target=${{ matrix.target }} - - - name: Test (release) - run: cargo test --verbose --target=${{ matrix.target }} --release - - - name: Generate docs - run: cargo doc --verbose --target=${{ matrix.target }} - env: - RUSTDOCFLAGS: -Dwarnings - - wasm-tests: - name: "wasm (firefox, ${{ matrix.name }})" - runs-on: ubuntu-latest - strategy: - matrix: - include: - - { name: default, RUSTFLAGS: "" } - - { name: simd128, RUSTFLAGS: "-C target-feature=+simd128" } - steps: - - uses: actions/checkout@v2 - - name: Setup Rust - run: | - rustup update nightly --no-self-update - rustup default nightly - - name: Install wasm-pack - run: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh - - name: Test (debug) - run: wasm-pack test --firefox --headless crates/core_simd - env: - RUSTFLAGS: ${{ matrix.rustflags }} - - name: Test (release) - run: wasm-pack test --firefox --headless crates/core_simd --release - env: - RUSTFLAGS: ${{ matrix.rustflags }} - - cross-tests: - name: "${{ matrix.target_feature }} on ${{ matrix.target }} (via cross)" - runs-on: ubuntu-latest - strategy: - fail-fast: false - - matrix: - target: - - armv7-unknown-linux-gnueabihf - - thumbv7neon-unknown-linux-gnueabihf # includes neon by default - - aarch64-unknown-linux-gnu # includes neon by default - - powerpc-unknown-linux-gnu - - powerpc64le-unknown-linux-gnu # includes altivec by default - - riscv64gc-unknown-linux-gnu - # MIPS uses a nonstandard binary representation for NaNs which makes it worth testing - # non-nightly since https://github.com/rust-lang/rust/pull/113274 - # - mips-unknown-linux-gnu - # - mips64-unknown-linux-gnuabi64 - # Lots of errors in QEMU and no real hardware to test on. Not clear if it's QEMU or bad codegen. - # - powerpc64-unknown-linux-gnu - target_feature: [default] - include: - - { target: powerpc64le-unknown-linux-gnu, target_feature: "+vsx" } - # Fails due to QEMU floating point errors, probably handling subnormals incorrectly. - # This target is somewhat redundant, since ppc64le has altivec as well. - # - { target: powerpc-unknown-linux-gnu, target_feature: "+altivec" } - # We should test this, but cross currently can't run it - # - { target: riscv64gc-unknown-linux-gnu, target_feature: "+v,+zvl128b" } - - steps: - - uses: actions/checkout@v2 - - name: Setup Rust - run: | - rustup update nightly --no-self-update - rustup default nightly - rustup target add ${{ matrix.target }} - rustup component add rust-src - - - name: Install Cross - # Equivalent to `cargo install cross`, but downloading a prebuilt - # binary. Ideally we wouldn't hardcode a version, but the version number - # being part of the tarball means we can't just use the download/latest - # URL :( - run: | - CROSS_URL=https://github.com/cross-rs/cross/releases/download/v0.2.5/cross-x86_64-unknown-linux-gnu.tar.gz - mkdir -p "$HOME/.bin" - curl -sfSL --retry-delay 10 --retry 5 "${CROSS_URL}" | tar zxf - -C "$HOME/.bin" - echo "$HOME/.bin" >> $GITHUB_PATH - - - name: Configure Emulated CPUs - run: | - echo "CARGO_TARGET_POWERPC_UNKNOWN_LINUX_GNU_RUNNER=qemu-ppc -cpu e600" >> $GITHUB_ENV - # echo "CARGO_TARGET_RISCV64GC_UNKNOWN_LINUX_GNU_RUNNER=qemu-riscv64 -cpu rv64,zba=true,zbb=true,v=true,vlen=256,vext_spec=v1.0" >> $GITHUB_ENV - - - name: Configure RUSTFLAGS - shell: bash - run: | - case "${{ matrix.target_feature }}" in - default) - echo "RUSTFLAGS=" >> $GITHUB_ENV;; - *) - echo "RUSTFLAGS=-Ctarget-feature=${{ matrix.target_feature }}" >> $GITHUB_ENV - ;; - esac - - - name: Test (debug) - run: cross test --verbose --target=${{ matrix.target }} - - - name: Test (release) - run: cross test --verbose --target=${{ matrix.target }} --release - - features: - name: "Test cargo features (${{ matrix.simd }} × ${{ matrix.features }})" - runs-on: ubuntu-latest - strategy: - fail-fast: false - matrix: - simd: - - "" - - "avx512" - features: - - "" - - "--features std" - - "--features all_lane_counts" - - "--all-features" - - steps: - - uses: actions/checkout@v2 - - name: Setup Rust - run: | - rustup update nightly --no-self-update - rustup default nightly - - name: Detect AVX512 - run: echo "CPU_FEATURE=$(lscpu | grep -o avx512[a-z]* | sed s/avx/+avx/ | tr '\n' ',' )" >> $GITHUB_ENV - - name: Check build - if: ${{ matrix.simd == '' }} - run: RUSTFLAGS="-Dwarnings" cargo test --all-targets --no-default-features ${{ matrix.features }} - - name: Check AVX - if: ${{ matrix.simd == 'avx512' && contains(env.CPU_FEATURE, 'avx512') }} - run: | - echo "Found AVX features: $CPU_FEATURE" - RUSTFLAGS="-Dwarnings -Ctarget-feature=$CPU_FEATURE" cargo test --all-targets --no-default-features ${{ matrix.features }} diff --git a/library/portable-simd/.github/workflows/doc.yml b/library/portable-simd/.github/workflows/doc.yml deleted file mode 100644 index 9d1fa66ccb595..0000000000000 --- a/library/portable-simd/.github/workflows/doc.yml +++ /dev/null @@ -1,30 +0,0 @@ -name: Documentation - -on: - push: - branches: - - master - -jobs: - release: - name: Deploy Documentation - runs-on: ubuntu-latest - - steps: - - name: Checkout Repository - uses: actions/checkout@v1 - - - name: Setup Rust - run: | - rustup update nightly --no-self-update - rustup default nightly - - - name: Build Documentation - run: cargo doc --no-deps - - - name: Deploy Documentation - uses: peaceiris/actions-gh-pages@v3 - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_branch: gh-pages - publish_dir: ./target/doc diff --git a/library/portable-simd/.gitignore b/library/portable-simd/.gitignore deleted file mode 100644 index ea8c4bf7f35f6..0000000000000 --- a/library/portable-simd/.gitignore +++ /dev/null @@ -1 +0,0 @@ -/target diff --git a/library/portable-simd/CONTRIBUTING.md b/library/portable-simd/CONTRIBUTING.md deleted file mode 100644 index 9612fe871c619..0000000000000 --- a/library/portable-simd/CONTRIBUTING.md +++ /dev/null @@ -1,32 +0,0 @@ -# Contributing to `std::simd` - -Simple version: -1. Fork it and `git clone` it -2. Create your feature branch: `git checkout -b my-branch` -3. Write your changes. -4. Test it: `cargo test`. Remember to enable whatever SIMD features you intend to test by setting `RUSTFLAGS`. -5. Commit your changes: `git commit add ./path/to/changes && git commit -m 'Fix some bug'` -6. Push the branch: `git push --set-upstream origin my-branch` -7. Submit a pull request! - -## Taking on an Issue - -SIMD can be quite complex, and even a "simple" issue can be huge. If an issue is organized like a tracking issue, with an itemized list of items that don't necessarily have to be done in a specific order, please take the issue one item at a time. This will help by letting work proceed apace on the rest of the issue. If it's a (relatively) small issue, feel free to announce your intention to solve it on the issue tracker and take it in one go! - -## CI - -We currently use GitHub Actions which will automatically build and test your change in order to verify that `std::simd`'s portable API is, in fact, portable. If your change builds locally, but does not build in CI, this is likely due to a platform-specific concern that your code has not addressed. Please consult the build logs and address the error, or ask for help if you need it. - -## Beyond stdsimd - -A large amount of the core SIMD implementation is found in the rustc_codegen_* crates in the [main rustc repo](https://github.com/rust-lang/rust). In addition, actual platform-specific functions are implemented in [stdarch]. Not all changes to `std::simd` require interacting with either of these, but if you're wondering where something is and it doesn't seem to be in this repository, those might be where to start looking. - -## Questions? Concerns? Need Help? - -Please feel free to ask in the [#project-portable-simd][zulip-portable-simd] stream on the [rust-lang Zulip][zulip] for help with making changes to `std::simd`! -If your changes include directly modifying the compiler, it might also be useful to ask in [#t-compiler/help][zulip-compiler-help]. - -[zulip-portable-simd]: https://rust-lang.zulipchat.com/#narrow/stream/257879-project-portable-simd -[zulip-compiler-help]: https://rust-lang.zulipchat.com/#narrow/stream/182449-t-compiler.2Fhelp -[zulip]: https://rust-lang.zulipchat.com -[stdarch]: https://github.com/rust-lang/stdarch diff --git a/library/portable-simd/Cargo.lock b/library/portable-simd/Cargo.lock deleted file mode 100644 index 1584c704fb221..0000000000000 --- a/library/portable-simd/Cargo.lock +++ /dev/null @@ -1,307 +0,0 @@ -# This file is automatically @generated by Cargo. -# It is not intended for manual editing. -version = 3 - -[[package]] -name = "autocfg" -version = "1.1.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "d468802bab17cbc0cc575e9b053f41e72aa36bfa6b7f55e3529ffa43161b97fa" - -[[package]] -name = "bitflags" -version = "1.3.2" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "bef38d45163c2f1dde094a7dfd33ccf595c92905c8f8f4fdc18d06fb1037718a" - -[[package]] -name = "bumpalo" -version = "3.13.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a3e2c3daef883ecc1b5d58c15adae93470a91d425f3532ba1695849656af3fc1" - -[[package]] -name = "byteorder" -version = "1.4.3" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "14c189c53d098945499cdfa7ecc63567cf3886b3332b312a5b4585d8d3a6a610" - -[[package]] -name = "cfg-if" -version = "1.0.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd" - -[[package]] -name = "console_error_panic_hook" -version = "0.1.7" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "a06aeb73f470f66dcdbf7223caeebb85984942f22f1adb2a088cf9668146bbbc" -dependencies = [ - "cfg-if", - "wasm-bindgen", -] - -[[package]] -name = "core_simd" -version = "0.1.0" -dependencies = [ - "proptest", - "std_float", - "test_helpers", - "wasm-bindgen", - "wasm-bindgen-test", -] - -[[package]] -name = "js-sys" -version = "0.3.64" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c5f195fe497f702db0f318b07fdd68edb16955aed830df8363d837542f8f935a" -dependencies = [ - "wasm-bindgen", -] - -[[package]] -name = "log" -version = "0.4.20" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b5e6163cb8c49088c2c36f57875e58ccd8c87c7427f7fbd50ea6710b2f3f2e8f" - -[[package]] -name = "num-traits" -version = "0.2.16" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f30b0abd723be7e2ffca1272140fac1a2f084c77ec3e123c192b66af1ee9e6c2" -dependencies = [ - "autocfg", -] - -[[package]] -name = "once_cell" -version = "1.18.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "dd8b5dd2ae5ed71462c540258bedcb51965123ad7e7ccf4b9a8cafaa4a63576d" - -[[package]] -name = "ppv-lite86" -version = "0.2.17" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5b40af805b3121feab8a3c29f04d8ad262fa8e0561883e7653e024ae4479e6de" - -[[package]] -name = "proc-macro2" -version = "1.0.66" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "18fb31db3f9bddb2ea821cde30a9f70117e3f119938b5ee630b7403aa6e2ead9" -dependencies = [ - "unicode-ident", -] - -[[package]] -name = "proptest" -version = "0.10.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "12e6c80c1139113c28ee4670dc50cc42915228b51f56a9e407f0ec60f966646f" -dependencies = [ - "bitflags", - "byteorder", - "num-traits", - "rand", - "rand_chacha", - "rand_xorshift", -] - -[[package]] -name = "quote" -version = "1.0.33" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5267fca4496028628a95160fc423a33e8b2e6af8a5302579e322e4b520293cae" -dependencies = [ - "proc-macro2", -] - -[[package]] -name = "rand" -version = "0.7.3" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "6a6b1679d49b24bbfe0c803429aa1874472f50d9b363131f0e89fc356b544d03" -dependencies = [ - "rand_chacha", - "rand_core", - "rand_hc", -] - -[[package]] -name = "rand_chacha" -version = "0.2.2" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "f4c8ed856279c9737206bf725bf36935d8666ead7aa69b52be55af369d193402" -dependencies = [ - "ppv-lite86", - "rand_core", -] - -[[package]] -name = "rand_core" -version = "0.5.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "90bde5296fc891b0cef12a6d03ddccc162ce7b2aff54160af9338f8d40df6d19" - -[[package]] -name = "rand_hc" -version = "0.2.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ca3129af7b92a17112d59ad498c6f81eaf463253766b90396d39ea7a39d6613c" -dependencies = [ - "rand_core", -] - -[[package]] -name = "rand_xorshift" -version = "0.2.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "77d416b86801d23dde1aa643023b775c3a462efc0ed96443add11546cdf1dca8" -dependencies = [ - "rand_core", -] - -[[package]] -name = "scoped-tls" -version = "1.0.1" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e1cf6437eb19a8f4a6cc0f7dca544973b0b78843adbfeb3683d1a94a0024a294" - -[[package]] -name = "std_float" -version = "0.1.0" -dependencies = [ - "core_simd", - "test_helpers", - "wasm-bindgen", - "wasm-bindgen-test", -] - -[[package]] -name = "syn" -version = "2.0.29" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c324c494eba9d92503e6f1ef2e6df781e78f6a7705a0202d9801b198807d518a" -dependencies = [ - "proc-macro2", - "quote", - "unicode-ident", -] - -[[package]] -name = "test_helpers" -version = "0.1.0" -dependencies = [ - "proptest", -] - -[[package]] -name = "unicode-ident" -version = "1.0.11" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "301abaae475aa91687eb82514b328ab47a211a533026cb25fc3e519b86adfc3c" - -[[package]] -name = "wasm-bindgen" -version = "0.2.87" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "7706a72ab36d8cb1f80ffbf0e071533974a60d0a308d01a5d0375bf60499a342" -dependencies = [ - "cfg-if", - "wasm-bindgen-macro", -] - -[[package]] -name = "wasm-bindgen-backend" -version = "0.2.87" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "5ef2b6d3c510e9625e5fe6f509ab07d66a760f0885d858736483c32ed7809abd" -dependencies = [ - "bumpalo", - "log", - "once_cell", - "proc-macro2", - "quote", - "syn", - "wasm-bindgen-shared", -] - -[[package]] -name = "wasm-bindgen-futures" -version = "0.4.37" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c02dbc21516f9f1f04f187958890d7e6026df8d16540b7ad9492bc34a67cea03" -dependencies = [ - "cfg-if", - "js-sys", - "wasm-bindgen", - "web-sys", -] - -[[package]] -name = "wasm-bindgen-macro" -version = "0.2.87" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "dee495e55982a3bd48105a7b947fd2a9b4a8ae3010041b9e0faab3f9cd028f1d" -dependencies = [ - "quote", - "wasm-bindgen-macro-support", -] - -[[package]] -name = "wasm-bindgen-macro-support" -version = "0.2.87" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "54681b18a46765f095758388f2d0cf16eb8d4169b639ab575a8f5693af210c7b" -dependencies = [ - "proc-macro2", - "quote", - "syn", - "wasm-bindgen-backend", - "wasm-bindgen-shared", -] - -[[package]] -name = "wasm-bindgen-shared" -version = "0.2.87" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ca6ad05a4870b2bf5fe995117d3728437bd27d7cd5f06f13c17443ef369775a1" - -[[package]] -name = "wasm-bindgen-test" -version = "0.3.37" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "6e6e302a7ea94f83a6d09e78e7dc7d9ca7b186bc2829c24a22d0753efd680671" -dependencies = [ - "console_error_panic_hook", - "js-sys", - "scoped-tls", - "wasm-bindgen", - "wasm-bindgen-futures", - "wasm-bindgen-test-macro", -] - -[[package]] -name = "wasm-bindgen-test-macro" -version = "0.3.37" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ecb993dd8c836930ed130e020e77d9b2e65dd0fbab1b67c790b0f5d80b11a575" -dependencies = [ - "proc-macro2", - "quote", -] - -[[package]] -name = "web-sys" -version = "0.3.64" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "9b85cbef8c220a6abc02aefd892dfc0fc23afb1c6a426316ec33253a3877249b" -dependencies = [ - "js-sys", - "wasm-bindgen", -] diff --git a/library/portable-simd/Cargo.toml b/library/portable-simd/Cargo.toml deleted file mode 100644 index d1732aaec2f92..0000000000000 --- a/library/portable-simd/Cargo.toml +++ /dev/null @@ -1,7 +0,0 @@ -[workspace] -resolver = "1" -members = [ - "crates/core_simd", - "crates/std_float", - "crates/test_helpers", -] diff --git a/library/portable-simd/LICENSE-APACHE b/library/portable-simd/LICENSE-APACHE deleted file mode 100644 index d645695673349..0000000000000 --- a/library/portable-simd/LICENSE-APACHE +++ /dev/null @@ -1,202 +0,0 @@ - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. diff --git a/library/portable-simd/LICENSE-MIT b/library/portable-simd/LICENSE-MIT deleted file mode 100644 index 0e9d2f43a0600..0000000000000 --- a/library/portable-simd/LICENSE-MIT +++ /dev/null @@ -1,19 +0,0 @@ -Copyright (c) 2020 The Rust Project Developers - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/library/portable-simd/README.md b/library/portable-simd/README.md deleted file mode 100644 index e8ac600debe67..0000000000000 --- a/library/portable-simd/README.md +++ /dev/null @@ -1,59 +0,0 @@ -# The Rust standard library's portable SIMD API -![Build Status](https://github.com/rust-lang/portable-simd/actions/workflows/ci.yml/badge.svg?branch=master) - -Code repository for the [Portable SIMD Project Group](https://github.com/rust-lang/project-portable-simd). -Please refer to [CONTRIBUTING.md](./CONTRIBUTING.md) for our contributing guidelines. - -The docs for this crate are published from the main branch. -You can [read them here][docs]. - -If you have questions about SIMD, we have begun writing a [guide][simd-guide]. -We can also be found on [Zulip][zulip-project-portable-simd]. - -If you are interested in support for a specific architecture, you may want [stdarch] instead. - -## Hello World - -Now we're gonna dip our toes into this world with a small SIMD "Hello, World!" example. Make sure your compiler is up to date and using `nightly`. We can do that by running - -```bash -rustup update -- nightly -``` - -or by setting up `rustup default nightly` or else with `cargo +nightly {build,test,run}`. After updating, run -```bash -cargo new hellosimd -``` -to create a new crate. Finally write this in `src/main.rs`: -```rust -#![feature(portable_simd)] -use std::simd::f32x4; -fn main() { - let a = f32x4::splat(10.0); - let b = f32x4::from_array([1.0, 2.0, 3.0, 4.0]); - println!("{:?}", a + b); -} -``` - -Explanation: We construct our SIMD vectors with methods like `splat` or `from_array`. Next, we can use operators like `+` on them, and the appropriate SIMD instructions will be carried out. When we run `cargo run` you should get `[11.0, 12.0, 13.0, 14.0]`. - -## Supported vectors - -Currently, vectors may have up to 64 elements, but aliases are provided only up to 512-bit vectors. - -Depending on the size of the primitive type, the number of lanes the vector will have varies. For example, 128-bit vectors have four `f32` lanes and two `f64` lanes. - -The supported element types are as follows: -* **Floating Point:** `f32`, `f64` -* **Signed Integers:** `i8`, `i16`, `i32`, `i64`, `isize` (`i128` excluded) -* **Unsigned Integers:** `u8`, `u16`, `u32`, `u64`, `usize` (`u128` excluded) -* **Pointers:** `*const T` and `*mut T` (zero-sized metadata only) -* **Masks:** 8-bit, 16-bit, 32-bit, 64-bit, and `usize`-sized masks - -Floating point, signed integers, unsigned integers, and pointers are the [primitive types](https://doc.rust-lang.org/core/primitive/index.html) you're already used to. -The mask types have elements that are "truthy" values, like `bool`, but have an unspecified layout because different architectures prefer different layouts for mask types. - -[simd-guide]: ./beginners-guide.md -[zulip-project-portable-simd]: https://rust-lang.zulipchat.com/#narrow/stream/257879-project-portable-simd -[stdarch]: https://github.com/rust-lang/stdarch -[docs]: https://rust-lang.github.io/portable-simd/core_simd diff --git a/library/portable-simd/beginners-guide.md b/library/portable-simd/beginners-guide.md deleted file mode 100644 index 17ade06ae80f9..0000000000000 --- a/library/portable-simd/beginners-guide.md +++ /dev/null @@ -1,91 +0,0 @@ - -# Beginner's Guide To SIMD - -Hello and welcome to our SIMD basics guide! - -Because SIMD is a subject that many programmers haven't worked with before, we thought that it's best to outline some terms and other basics for you to get started with. - -## Quick Background - -**SIMD** stands for *Single Instruction, Multiple Data*. In other words, SIMD is when the CPU performs a single action on more than one logical piece of data at the same time. Instead of adding two registers that each contain one `f32` value and getting an `f32` as the result, you might add two registers that each contain `f32x4` (128 bits of data) and then you get an `f32x4` as the output. - -This might seem a tiny bit weird at first, but there's a good reason for it. Back in the day, as CPUs got faster and faster, eventually they got so fast that the CPU would just melt itself. The heat management (heat sinks, fans, etc) simply couldn't keep up with how much electricity was going through the metal. Two main strategies were developed to help get around the limits of physics. -* One of them you're probably familiar with: Multi-core processors. By giving a processor more than one core, each core can do its own work, and because they're physically distant (at least on the CPU's scale) the heat can still be managed. Unfortunately, not all tasks can just be split up across cores in an efficient way. -* The second strategy is SIMD. If you can't make the register go any faster, you can still make the register *wider*. This lets you process more data at a time, which is *almost* as good as just having a faster CPU. As with multi-core programming, SIMD doesn't fit every kind of task, so you have to know when it will improve your program. - -## Terms - -SIMD has a few special vocabulary terms you should know: - -* **Vector:** A SIMD value is called a vector. This shouldn't be confused with the `Vec` type. A SIMD vector has a fixed size, known at compile time. All of the elements within the vector are of the same type. This makes vectors *similar to* arrays. One difference is that a vector is generally aligned to its *entire* size (eg: 16 bytes, 32 bytes, etc), not just the size of an individual element. Sometimes vector data is called "packed" data. - -* **Vectorize**: An operation that uses SIMD instructions to operate over a vector is often referred to as "vectorized". - -* **Autovectorization**: Also known as _implicit vectorization_. This is when a compiler can automatically recognize a situation where scalar instructions may be replaced with SIMD instructions, and use those instead. - -* **Scalar:** "Scalar" in mathematical contexts refers to values that can be represented as a single element, mostly numbers like 6, 3.14, or -2. It can also be used to describe "scalar operations" that use strictly scalar values, like addition. This term is mostly used to differentiate between vectorized operations that use SIMD instructions and scalar operations that don't. - -* **Lane:** A single element position within a vector is called a lane. If you have `N` lanes available then they're numbered from `0` to `N-1` when referring to them, again like an array. The biggest difference between an array element and a vector lane is that in general is *relatively costly* to access an individual lane value. On most architectures, the vector has to be pushed out of the SIMD register onto the stack, then an individual lane is accessed while it's on the stack (and possibly the stack value is read back into a register). For this reason, when working with SIMD you should avoid reading or writing the value of an individual lane during hot loops. - -* **Bit Widths:** When talking about SIMD, the bit widths used are the bit size of the vectors involved, *not* the individual elements. So "128-bit SIMD" has 128-bit vectors, and that might be `f32x4`, `i32x4`, `i16x8`, or other variations. While 128-bit SIMD is the most common, there's also 64-bit, 256-bit, and even 512-bit on the newest CPUs. - -* **Vector Register:** The extra-wide registers that are used for SIMD operations are commonly called vector registers, though you may also see "SIMD registers", vendor names for specific features, or even "floating-point register" as it is common for the same registers to be used with both scalar and vectorized floating-point operations. - -* **Vertical:** When an operation is "vertical", each lane processes individually without regard to the other lanes in the same vector. For example, a "vertical add" between two vectors would add lane 0 in `a` with lane 0 in `b`, with the total in lane 0 of `out`, and then the same thing for lanes 1, 2, etc. Most SIMD operations are vertical operations, so if your problem is a vertical problem then you can probably solve it with SIMD. - -* **Reducing/Reduce:** When an operation is "reducing" (functions named `reduce_*`), the lanes within a single vector are merged using some operation such as addition, returning the merged value as a scalar. For instance, a reducing add would return the sum of all the lanes' values. - -* **Target Feature:** Rust calls a CPU architecture extension a `target_feature`. Proper SIMD requires various CPU extensions to be enabled (details below). Don't confuse this with `feature`, which is a Cargo crate concept. - -## Target Features - -When using SIMD, you should be familiar with the CPU feature set that you're targeting. - -On `arm` and `aarch64` it's fairly simple. There's just one CPU feature that controls if SIMD is available: `neon` (or "NEON", all caps, as the ARM docs often put it). Neon registers can be used as 64-bit or 128-bit. When doing 128-bit operations it just uses two 64-bit registers as a single 128-bit register. - -> By default, the `aarch64`, `arm`, and `thumb` Rust targets generally do not enable `neon` unless it's in the target string. - -On `x86` and `x86_64` it's slightly more complicated. The SIMD support is split into many levels: -* 128-bit: `sse`, `sse2`, `sse3`, `ssse3` (not a typo!), `sse4.1`, `sse4.2`, `sse4a` (AMD only) -* 256-bit (mostly): `avx`, `avx2`, `fma` -* 512-bit (mostly): a *wide* range of `avx512` variations - -The list notes the bit widths available at each feature level, though the operations of the more advanced features can generally be used with the smaller register sizes as well. For example, new operations introduced in `avx` generally have a 128-bit form as well as a 256-bit form. This means that even if you only do 128-bit work you can still benefit from the later feature levels. - -> By default, the `i686` and `x86_64` Rust targets enable `sse` and `sse2`. - -### Selecting Additional Target Features - -If you want to enable support for a target feature within your build, generally you should use a [target-feature](https://rust-lang.github.io/packed_simd/perf-guide/target-feature/rustflags.html#target-feature) setting within you `RUSTFLAGS` setting. - -If you know that you're targeting a specific CPU you can instead use the [target-cpu](https://rust-lang.github.io/packed_simd/perf-guide/target-feature/rustflags.html#target-cpu) flag and the compiler will enable the correct set of features for that CPU. - -The [Steam Hardware Survey](https://store.steampowered.com/hwsurvey/Steam-Hardware-Software-Survey-Welcome-to-Steam) is one of the few places with data on how common various CPU features are. The dataset is limited to "the kinds of computers owned by people who play computer games", so the info only covers `x86`/`x86_64`, and it also probably skews to slightly higher quality computers than average. Still, we can see that the `sse` levels have very high support, `avx` and `avx2` are quite common as well, and the `avx-512` family is still so early in adoption you can barely find it in consumer grade stuff. - -## Running a program compiled for a CPU feature level that the CPU doesn't support is automatic undefined behavior. - -This means that if you build your program with `avx` support enabled and run it on a CPU without `avx` support, it's **instantly** undefined behavior. - -Even without an `unsafe` block in sight. - -This is no bug in Rust, or soundness hole in the type system. You just plain can't make a CPU do what it doesn't know how to do. - -This is why the various Rust targets *don't* enable many CPU feature flags by default: requiring a more advanced CPU makes the final binary *less* portable. - -So please select an appropriate CPU feature level when building your programs. - -## Size, Alignment, and Unsafe Code - -Most of the portable SIMD API is designed to allow the user to gloss over the details of different architectures and avoid using unsafe code. However, there are plenty of reasons to want to use unsafe code with these SIMD types, such as using an intrinsic function from `core::arch` to further accelerate particularly specialized SIMD operations on a given platform, while still using the portable API elsewhere. For these cases, there are some rules to keep in mind. - -Fortunately, most SIMD types have a fairly predictable size. `i32x4` is bit-equivalent to `[i32; 4]` and so can be bitcast to it, e.g. using [`mem::transmute`], though the API usually offers a safe cast you can use instead. - -However, this is not the same as alignment. Computer architectures generally prefer aligned accesses, especially when moving data between memory and vector registers, and while some support specialized operations that can bend the rules to help with this, unaligned access is still typically slow, or even undefined behavior. In addition, different architectures can require different alignments when interacting with their native SIMD types. For this reason, any `#[repr(simd)]` type has a non-portable alignment. If it is necessary to directly interact with the alignment of these types, it should be via [`mem::align_of`]. - -When working with slices, data correctly aligned for SIMD can be acquired using the [`as_simd`] and [`as_simd_mut`] methods of the slice primitive. - -[`mem::transmute`]: https://doc.rust-lang.org/core/mem/fn.transmute.html -[`mem::align_of`]: https://doc.rust-lang.org/core/mem/fn.align_of.html -[`as_simd`]: https://doc.rust-lang.org/nightly/std/primitive.slice.html#method.as_simd -[`as_simd_mut`]: https://doc.rust-lang.org/nightly/std/primitive.slice.html#method.as_simd_mut - diff --git a/library/portable-simd/crates/core_simd/Cargo.toml b/library/portable-simd/crates/core_simd/Cargo.toml deleted file mode 100644 index b4a8fd70f4c0e..0000000000000 --- a/library/portable-simd/crates/core_simd/Cargo.toml +++ /dev/null @@ -1,30 +0,0 @@ -[package] -name = "core_simd" -version = "0.1.0" -edition = "2021" -homepage = "https://github.com/rust-lang/portable-simd" -repository = "https://github.com/rust-lang/portable-simd" -keywords = ["core", "simd", "intrinsics"] -categories = ["hardware-support", "no-std"] -license = "MIT OR Apache-2.0" - -[features] -default = ["as_crate"] -as_crate = [] -std = [] -all_lane_counts = [] - -[target.'cfg(target_arch = "wasm32")'.dev-dependencies] -wasm-bindgen = "0.2" -wasm-bindgen-test = "0.3" - -[dev-dependencies.proptest] -version = "0.10" -default-features = false -features = ["alloc"] - -[dev-dependencies.test_helpers] -path = "../test_helpers" - -[dev-dependencies] -std_float = { path = "../std_float/", features = ["as_crate"] } diff --git a/library/portable-simd/crates/core_simd/LICENSE-APACHE b/library/portable-simd/crates/core_simd/LICENSE-APACHE deleted file mode 100644 index d645695673349..0000000000000 --- a/library/portable-simd/crates/core_simd/LICENSE-APACHE +++ /dev/null @@ -1,202 +0,0 @@ - - Apache License - Version 2.0, January 2004 - http://www.apache.org/licenses/ - - TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION - - 1. Definitions. - - "License" shall mean the terms and conditions for use, reproduction, - and distribution as defined by Sections 1 through 9 of this document. - - "Licensor" shall mean the copyright owner or entity authorized by - the copyright owner that is granting the License. - - "Legal Entity" shall mean the union of the acting entity and all - other entities that control, are controlled by, or are under common - control with that entity. For the purposes of this definition, - "control" means (i) the power, direct or indirect, to cause the - direction or management of such entity, whether by contract or - otherwise, or (ii) ownership of fifty percent (50%) or more of the - outstanding shares, or (iii) beneficial ownership of such entity. - - "You" (or "Your") shall mean an individual or Legal Entity - exercising permissions granted by this License. - - "Source" form shall mean the preferred form for making modifications, - including but not limited to software source code, documentation - source, and configuration files. - - "Object" form shall mean any form resulting from mechanical - transformation or translation of a Source form, including but - not limited to compiled object code, generated documentation, - and conversions to other media types. - - "Work" shall mean the work of authorship, whether in Source or - Object form, made available under the License, as indicated by a - copyright notice that is included in or attached to the work - (an example is provided in the Appendix below). - - "Derivative Works" shall mean any work, whether in Source or Object - form, that is based on (or derived from) the Work and for which the - editorial revisions, annotations, elaborations, or other modifications - represent, as a whole, an original work of authorship. For the purposes - of this License, Derivative Works shall not include works that remain - separable from, or merely link (or bind by name) to the interfaces of, - the Work and Derivative Works thereof. - - "Contribution" shall mean any work of authorship, including - the original version of the Work and any modifications or additions - to that Work or Derivative Works thereof, that is intentionally - submitted to Licensor for inclusion in the Work by the copyright owner - or by an individual or Legal Entity authorized to submit on behalf of - the copyright owner. For the purposes of this definition, "submitted" - means any form of electronic, verbal, or written communication sent - to the Licensor or its representatives, including but not limited to - communication on electronic mailing lists, source code control systems, - and issue tracking systems that are managed by, or on behalf of, the - Licensor for the purpose of discussing and improving the Work, but - excluding communication that is conspicuously marked or otherwise - designated in writing by the copyright owner as "Not a Contribution." - - "Contributor" shall mean Licensor and any individual or Legal Entity - on behalf of whom a Contribution has been received by Licensor and - subsequently incorporated within the Work. - - 2. Grant of Copyright License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - copyright license to reproduce, prepare Derivative Works of, - publicly display, publicly perform, sublicense, and distribute the - Work and such Derivative Works in Source or Object form. - - 3. Grant of Patent License. Subject to the terms and conditions of - this License, each Contributor hereby grants to You a perpetual, - worldwide, non-exclusive, no-charge, royalty-free, irrevocable - (except as stated in this section) patent license to make, have made, - use, offer to sell, sell, import, and otherwise transfer the Work, - where such license applies only to those patent claims licensable - by such Contributor that are necessarily infringed by their - Contribution(s) alone or by combination of their Contribution(s) - with the Work to which such Contribution(s) was submitted. If You - institute patent litigation against any entity (including a - cross-claim or counterclaim in a lawsuit) alleging that the Work - or a Contribution incorporated within the Work constitutes direct - or contributory patent infringement, then any patent licenses - granted to You under this License for that Work shall terminate - as of the date such litigation is filed. - - 4. Redistribution. You may reproduce and distribute copies of the - Work or Derivative Works thereof in any medium, with or without - modifications, and in Source or Object form, provided that You - meet the following conditions: - - (a) You must give any other recipients of the Work or - Derivative Works a copy of this License; and - - (b) You must cause any modified files to carry prominent notices - stating that You changed the files; and - - (c) You must retain, in the Source form of any Derivative Works - that You distribute, all copyright, patent, trademark, and - attribution notices from the Source form of the Work, - excluding those notices that do not pertain to any part of - the Derivative Works; and - - (d) If the Work includes a "NOTICE" text file as part of its - distribution, then any Derivative Works that You distribute must - include a readable copy of the attribution notices contained - within such NOTICE file, excluding those notices that do not - pertain to any part of the Derivative Works, in at least one - of the following places: within a NOTICE text file distributed - as part of the Derivative Works; within the Source form or - documentation, if provided along with the Derivative Works; or, - within a display generated by the Derivative Works, if and - wherever such third-party notices normally appear. The contents - of the NOTICE file are for informational purposes only and - do not modify the License. You may add Your own attribution - notices within Derivative Works that You distribute, alongside - or as an addendum to the NOTICE text from the Work, provided - that such additional attribution notices cannot be construed - as modifying the License. - - You may add Your own copyright statement to Your modifications and - may provide additional or different license terms and conditions - for use, reproduction, or distribution of Your modifications, or - for any such Derivative Works as a whole, provided Your use, - reproduction, and distribution of the Work otherwise complies with - the conditions stated in this License. - - 5. Submission of Contributions. Unless You explicitly state otherwise, - any Contribution intentionally submitted for inclusion in the Work - by You to the Licensor shall be under the terms and conditions of - this License, without any additional terms or conditions. - Notwithstanding the above, nothing herein shall supersede or modify - the terms of any separate license agreement you may have executed - with Licensor regarding such Contributions. - - 6. Trademarks. This License does not grant permission to use the trade - names, trademarks, service marks, or product names of the Licensor, - except as required for reasonable and customary use in describing the - origin of the Work and reproducing the content of the NOTICE file. - - 7. Disclaimer of Warranty. Unless required by applicable law or - agreed to in writing, Licensor provides the Work (and each - Contributor provides its Contributions) on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or - implied, including, without limitation, any warranties or conditions - of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A - PARTICULAR PURPOSE. You are solely responsible for determining the - appropriateness of using or redistributing the Work and assume any - risks associated with Your exercise of permissions under this License. - - 8. Limitation of Liability. In no event and under no legal theory, - whether in tort (including negligence), contract, or otherwise, - unless required by applicable law (such as deliberate and grossly - negligent acts) or agreed to in writing, shall any Contributor be - liable to You for damages, including any direct, indirect, special, - incidental, or consequential damages of any character arising as a - result of this License or out of the use or inability to use the - Work (including but not limited to damages for loss of goodwill, - work stoppage, computer failure or malfunction, or any and all - other commercial damages or losses), even if such Contributor - has been advised of the possibility of such damages. - - 9. Accepting Warranty or Additional Liability. While redistributing - the Work or Derivative Works thereof, You may choose to offer, - and charge a fee for, acceptance of support, warranty, indemnity, - or other liability obligations and/or rights consistent with this - License. However, in accepting such obligations, You may act only - on Your own behalf and on Your sole responsibility, not on behalf - of any other Contributor, and only if You agree to indemnify, - defend, and hold each Contributor harmless for any liability - incurred by, or claims asserted against, such Contributor by reason - of your accepting any such warranty or additional liability. - - END OF TERMS AND CONDITIONS - - APPENDIX: How to apply the Apache License to your work. - - To apply the Apache License to your work, attach the following - boilerplate notice, with the fields enclosed by brackets "[]" - replaced with your own identifying information. (Don't include - the brackets!) The text should be enclosed in the appropriate - comment syntax for the file format. We also recommend that a - file or class name and description of purpose be included on the - same "printed page" as the copyright notice for easier - identification within third-party archives. - - Copyright [yyyy] [name of copyright owner] - - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions and - limitations under the License. diff --git a/library/portable-simd/crates/core_simd/LICENSE-MIT b/library/portable-simd/crates/core_simd/LICENSE-MIT deleted file mode 100644 index 0e9d2f43a0600..0000000000000 --- a/library/portable-simd/crates/core_simd/LICENSE-MIT +++ /dev/null @@ -1,19 +0,0 @@ -Copyright (c) 2020 The Rust Project Developers - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in all -copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE -SOFTWARE. diff --git a/library/portable-simd/crates/core_simd/examples/README.md b/library/portable-simd/crates/core_simd/examples/README.md deleted file mode 100644 index 82747f1b5a6f9..0000000000000 --- a/library/portable-simd/crates/core_simd/examples/README.md +++ /dev/null @@ -1,13 +0,0 @@ -### `stdsimd` examples - -This crate is a port of example uses of `stdsimd`, mostly taken from the `packed_simd` crate. - -The examples contain, as in the case of `dot_product.rs`, multiple ways of solving the problem, in order to show idiomatic uses of SIMD and iteration of performance designs. - -Run the tests with the command - -``` -cargo run --example dot_product -``` - -and verify the code for `dot_product.rs` on your machine. diff --git a/library/portable-simd/crates/core_simd/examples/dot_product.rs b/library/portable-simd/crates/core_simd/examples/dot_product.rs deleted file mode 100644 index f047010a65c16..0000000000000 --- a/library/portable-simd/crates/core_simd/examples/dot_product.rs +++ /dev/null @@ -1,169 +0,0 @@ -// Code taken from the `packed_simd` crate -// Run this code with `cargo test --example dot_product` -//use std::iter::zip; - -#![feature(array_chunks)] -#![feature(slice_as_chunks)] -// Add these imports to use the stdsimd library -#![feature(portable_simd)] -use core_simd::simd::prelude::*; - -// This is your barebones dot product implementation: -// Take 2 vectors, multiply them element wise and *then* -// go along the resulting array and add up the result. -// In the next example we will see if there -// is any difference to adding and multiplying in tandem. -pub fn dot_prod_scalar_0(a: &[f32], b: &[f32]) -> f32 { - assert_eq!(a.len(), b.len()); - - a.iter().zip(b.iter()).map(|(a, b)| a * b).sum() -} - -// When dealing with SIMD, it is very important to think about the amount -// of data movement and when it happens. We're going over simple computation examples here, and yet -// it is not trivial to understand what may or may not contribute to performance -// changes. Eventually, you will need tools to inspect the generated assembly and confirm your -// hypothesis and benchmarks - we will mention them later on. -// With the use of `fold`, we're doing a multiplication, -// and then adding it to the sum, one element from both vectors at a time. -pub fn dot_prod_scalar_1(a: &[f32], b: &[f32]) -> f32 { - assert_eq!(a.len(), b.len()); - a.iter() - .zip(b.iter()) - .fold(0.0, |a, zipped| a + zipped.0 * zipped.1) -} - -// We now move on to the SIMD implementations: notice the following constructs: -// `array_chunks::<4>`: mapping this over the vector will let use construct SIMD vectors -// `f32x4::from_array`: construct the SIMD vector from a slice -// `(a * b).reduce_sum()`: Multiply both f32x4 vectors together, and then reduce them. -// This approach essentially uses SIMD to produce a vector of length N/4 of all the products, -// and then add those with `sum()`. This is suboptimal. -// TODO: ASCII diagrams -pub fn dot_prod_simd_0(a: &[f32], b: &[f32]) -> f32 { - assert_eq!(a.len(), b.len()); - // TODO handle remainder when a.len() % 4 != 0 - a.array_chunks::<4>() - .map(|&a| f32x4::from_array(a)) - .zip(b.array_chunks::<4>().map(|&b| f32x4::from_array(b))) - .map(|(a, b)| (a * b).reduce_sum()) - .sum() -} - -// There's some simple ways to improve the previous code: -// 1. Make a `zero` `f32x4` SIMD vector that we will be accumulating into -// So that there is only one `sum()` reduction when the last `f32x4` has been processed -// 2. Exploit Fused Multiply Add so that the multiplication, addition and sinking into the reduciton -// happen in the same step. -// If the arrays are large, minimizing the data shuffling will lead to great perf. -// If the arrays are small, handling the remainder elements when the length isn't a multiple of 4 -// Can become a problem. -pub fn dot_prod_simd_1(a: &[f32], b: &[f32]) -> f32 { - assert_eq!(a.len(), b.len()); - // TODO handle remainder when a.len() % 4 != 0 - a.array_chunks::<4>() - .map(|&a| f32x4::from_array(a)) - .zip(b.array_chunks::<4>().map(|&b| f32x4::from_array(b))) - .fold(f32x4::splat(0.0), |acc, zipped| acc + zipped.0 * zipped.1) - .reduce_sum() -} - -// A lot of knowledgeable use of SIMD comes from knowing specific instructions that are -// available - let's try to use the `mul_add` instruction, which is the fused-multiply-add we were looking for. -use std_float::StdFloat; -pub fn dot_prod_simd_2(a: &[f32], b: &[f32]) -> f32 { - assert_eq!(a.len(), b.len()); - // TODO handle remainder when a.len() % 4 != 0 - let mut res = f32x4::splat(0.0); - a.array_chunks::<4>() - .map(|&a| f32x4::from_array(a)) - .zip(b.array_chunks::<4>().map(|&b| f32x4::from_array(b))) - .for_each(|(a, b)| { - res = a.mul_add(b, res); - }); - res.reduce_sum() -} - -// Finally, we will write the same operation but handling the loop remainder. -const LANES: usize = 4; -pub fn dot_prod_simd_3(a: &[f32], b: &[f32]) -> f32 { - assert_eq!(a.len(), b.len()); - - let (a_extra, a_chunks) = a.as_rchunks(); - let (b_extra, b_chunks) = b.as_rchunks(); - - // These are always true, but for emphasis: - assert_eq!(a_chunks.len(), b_chunks.len()); - assert_eq!(a_extra.len(), b_extra.len()); - - let mut sums = [0.0; LANES]; - for ((x, y), d) in std::iter::zip(a_extra, b_extra).zip(&mut sums) { - *d = x * y; - } - - let mut sums = f32x4::from_array(sums); - std::iter::zip(a_chunks, b_chunks).for_each(|(x, y)| { - sums += f32x4::from_array(*x) * f32x4::from_array(*y); - }); - - sums.reduce_sum() -} - -// Finally, we present an iterator version for handling remainders in a scalar fashion at the end of the loop. -// Unfortunately, this is allocating 1 `XMM` register on the order of `~len(a)` - we'll see how we can get around it in the -// next example. -pub fn dot_prod_simd_4(a: &[f32], b: &[f32]) -> f32 { - let mut sum = a - .array_chunks::<4>() - .map(|&a| f32x4::from_array(a)) - .zip(b.array_chunks::<4>().map(|&b| f32x4::from_array(b))) - .map(|(a, b)| a * b) - .fold(f32x4::splat(0.0), std::ops::Add::add) - .reduce_sum(); - let remain = a.len() - (a.len() % 4); - sum += a[remain..] - .iter() - .zip(&b[remain..]) - .map(|(a, b)| a * b) - .sum::(); - sum -} - -// This version allocates a single `XMM` register for accumulation, and the folds don't allocate on top of that. -// Notice the use of `mul_add`, which can do a multiply and an add operation ber iteration. -pub fn dot_prod_simd_5(a: &[f32], b: &[f32]) -> f32 { - a.array_chunks::<4>() - .map(|&a| f32x4::from_array(a)) - .zip(b.array_chunks::<4>().map(|&b| f32x4::from_array(b))) - .fold(f32x4::splat(0.), |acc, (a, b)| a.mul_add(b, acc)) - .reduce_sum() -} - -fn main() { - // Empty main to make cargo happy -} - -#[cfg(test)] -mod tests { - #[test] - fn smoke_test() { - use super::*; - let a: Vec = vec![1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0]; - let b: Vec = vec![-8.0, -7.0, -6.0, -5.0, 4.0, 3.0, 2.0, 1.0]; - let x: Vec = [0.5; 1003].to_vec(); - let y: Vec = [2.0; 1003].to_vec(); - - // Basic check - assert_eq!(0.0, dot_prod_scalar_0(&a, &b)); - assert_eq!(0.0, dot_prod_scalar_1(&a, &b)); - assert_eq!(0.0, dot_prod_simd_0(&a, &b)); - assert_eq!(0.0, dot_prod_simd_1(&a, &b)); - assert_eq!(0.0, dot_prod_simd_2(&a, &b)); - assert_eq!(0.0, dot_prod_simd_3(&a, &b)); - assert_eq!(0.0, dot_prod_simd_4(&a, &b)); - assert_eq!(0.0, dot_prod_simd_5(&a, &b)); - - // We can handle vectors that are non-multiples of 4 - assert_eq!(1003.0, dot_prod_simd_3(&x, &y)); - } -} diff --git a/library/portable-simd/crates/core_simd/examples/matrix_inversion.rs b/library/portable-simd/crates/core_simd/examples/matrix_inversion.rs deleted file mode 100644 index bad86414401d7..0000000000000 --- a/library/portable-simd/crates/core_simd/examples/matrix_inversion.rs +++ /dev/null @@ -1,315 +0,0 @@ -//! 4x4 matrix inverse -// Code ported from the `packed_simd` crate -// Run this code with `cargo test --example matrix_inversion` -#![feature(array_chunks, portable_simd)] -use core_simd::simd::prelude::*; - -// Gotta define our own 4x4 matrix since Rust doesn't ship multidim arrays yet :^) -#[derive(Copy, Clone, Debug, PartialEq, PartialOrd)] -pub struct Matrix4x4([[f32; 4]; 4]); - -#[allow(clippy::too_many_lines)] -pub fn scalar_inv4x4(m: Matrix4x4) -> Option { - let m = m.0; - - #[rustfmt::skip] - let mut inv = [ - // row 0: - [ - // 0,0: - m[1][1] * m[2][2] * m[3][3] - - m[1][1] * m[2][3] * m[3][2] - - m[2][1] * m[1][2] * m[3][3] + - m[2][1] * m[1][3] * m[3][2] + - m[3][1] * m[1][2] * m[2][3] - - m[3][1] * m[1][3] * m[2][2], - // 0,1: - -m[0][1] * m[2][2] * m[3][3] + - m[0][1] * m[2][3] * m[3][2] + - m[2][1] * m[0][2] * m[3][3] - - m[2][1] * m[0][3] * m[3][2] - - m[3][1] * m[0][2] * m[2][3] + - m[3][1] * m[0][3] * m[2][2], - // 0,2: - m[0][1] * m[1][2] * m[3][3] - - m[0][1] * m[1][3] * m[3][2] - - m[1][1] * m[0][2] * m[3][3] + - m[1][1] * m[0][3] * m[3][2] + - m[3][1] * m[0][2] * m[1][3] - - m[3][1] * m[0][3] * m[1][2], - // 0,3: - -m[0][1] * m[1][2] * m[2][3] + - m[0][1] * m[1][3] * m[2][2] + - m[1][1] * m[0][2] * m[2][3] - - m[1][1] * m[0][3] * m[2][2] - - m[2][1] * m[0][2] * m[1][3] + - m[2][1] * m[0][3] * m[1][2], - ], - // row 1 - [ - // 1,0: - -m[1][0] * m[2][2] * m[3][3] + - m[1][0] * m[2][3] * m[3][2] + - m[2][0] * m[1][2] * m[3][3] - - m[2][0] * m[1][3] * m[3][2] - - m[3][0] * m[1][2] * m[2][3] + - m[3][0] * m[1][3] * m[2][2], - // 1,1: - m[0][0] * m[2][2] * m[3][3] - - m[0][0] * m[2][3] * m[3][2] - - m[2][0] * m[0][2] * m[3][3] + - m[2][0] * m[0][3] * m[3][2] + - m[3][0] * m[0][2] * m[2][3] - - m[3][0] * m[0][3] * m[2][2], - // 1,2: - -m[0][0] * m[1][2] * m[3][3] + - m[0][0] * m[1][3] * m[3][2] + - m[1][0] * m[0][2] * m[3][3] - - m[1][0] * m[0][3] * m[3][2] - - m[3][0] * m[0][2] * m[1][3] + - m[3][0] * m[0][3] * m[1][2], - // 1,3: - m[0][0] * m[1][2] * m[2][3] - - m[0][0] * m[1][3] * m[2][2] - - m[1][0] * m[0][2] * m[2][3] + - m[1][0] * m[0][3] * m[2][2] + - m[2][0] * m[0][2] * m[1][3] - - m[2][0] * m[0][3] * m[1][2], - ], - // row 2 - [ - // 2,0: - m[1][0] * m[2][1] * m[3][3] - - m[1][0] * m[2][3] * m[3][1] - - m[2][0] * m[1][1] * m[3][3] + - m[2][0] * m[1][3] * m[3][1] + - m[3][0] * m[1][1] * m[2][3] - - m[3][0] * m[1][3] * m[2][1], - // 2,1: - -m[0][0] * m[2][1] * m[3][3] + - m[0][0] * m[2][3] * m[3][1] + - m[2][0] * m[0][1] * m[3][3] - - m[2][0] * m[0][3] * m[3][1] - - m[3][0] * m[0][1] * m[2][3] + - m[3][0] * m[0][3] * m[2][1], - // 2,2: - m[0][0] * m[1][1] * m[3][3] - - m[0][0] * m[1][3] * m[3][1] - - m[1][0] * m[0][1] * m[3][3] + - m[1][0] * m[0][3] * m[3][1] + - m[3][0] * m[0][1] * m[1][3] - - m[3][0] * m[0][3] * m[1][1], - // 2,3: - -m[0][0] * m[1][1] * m[2][3] + - m[0][0] * m[1][3] * m[2][1] + - m[1][0] * m[0][1] * m[2][3] - - m[1][0] * m[0][3] * m[2][1] - - m[2][0] * m[0][1] * m[1][3] + - m[2][0] * m[0][3] * m[1][1], - ], - // row 3 - [ - // 3,0: - -m[1][0] * m[2][1] * m[3][2] + - m[1][0] * m[2][2] * m[3][1] + - m[2][0] * m[1][1] * m[3][2] - - m[2][0] * m[1][2] * m[3][1] - - m[3][0] * m[1][1] * m[2][2] + - m[3][0] * m[1][2] * m[2][1], - // 3,1: - m[0][0] * m[2][1] * m[3][2] - - m[0][0] * m[2][2] * m[3][1] - - m[2][0] * m[0][1] * m[3][2] + - m[2][0] * m[0][2] * m[3][1] + - m[3][0] * m[0][1] * m[2][2] - - m[3][0] * m[0][2] * m[2][1], - // 3,2: - -m[0][0] * m[1][1] * m[3][2] + - m[0][0] * m[1][2] * m[3][1] + - m[1][0] * m[0][1] * m[3][2] - - m[1][0] * m[0][2] * m[3][1] - - m[3][0] * m[0][1] * m[1][2] + - m[3][0] * m[0][2] * m[1][1], - // 3,3: - m[0][0] * m[1][1] * m[2][2] - - m[0][0] * m[1][2] * m[2][1] - - m[1][0] * m[0][1] * m[2][2] + - m[1][0] * m[0][2] * m[2][1] + - m[2][0] * m[0][1] * m[1][2] - - m[2][0] * m[0][2] * m[1][1], - ], - ]; - - let det = m[0][0] * inv[0][0] + m[0][1] * inv[1][0] + m[0][2] * inv[2][0] + m[0][3] * inv[3][0]; - if det == 0. { - return None; - } - - let det_inv = 1. / det; - - for row in &mut inv { - for elem in row.iter_mut() { - *elem *= det_inv; - } - } - - Some(Matrix4x4(inv)) -} - -pub fn simd_inv4x4(m: Matrix4x4) -> Option { - let m = m.0; - let m_0 = f32x4::from_array(m[0]); - let m_1 = f32x4::from_array(m[1]); - let m_2 = f32x4::from_array(m[2]); - let m_3 = f32x4::from_array(m[3]); - - const SHUFFLE01: [usize; 4] = [0, 1, 4, 5]; - const SHUFFLE02: [usize; 4] = [0, 2, 4, 6]; - const SHUFFLE13: [usize; 4] = [1, 3, 5, 7]; - const SHUFFLE23: [usize; 4] = [2, 3, 6, 7]; - - let tmp = simd_swizzle!(m_0, m_1, SHUFFLE01); - let row1 = simd_swizzle!(m_2, m_3, SHUFFLE01); - - let row0 = simd_swizzle!(tmp, row1, SHUFFLE02); - let row1 = simd_swizzle!(row1, tmp, SHUFFLE13); - - let tmp = simd_swizzle!(m_0, m_1, SHUFFLE23); - let row3 = simd_swizzle!(m_2, m_3, SHUFFLE23); - let row2 = simd_swizzle!(tmp, row3, SHUFFLE02); - let row3 = simd_swizzle!(row3, tmp, SHUFFLE13); - - let tmp = (row2 * row3).reverse().rotate_elements_right::<2>(); - let minor0 = row1 * tmp; - let minor1 = row0 * tmp; - let tmp = tmp.rotate_elements_right::<2>(); - let minor0 = (row1 * tmp) - minor0; - let minor1 = (row0 * tmp) - minor1; - let minor1 = minor1.rotate_elements_right::<2>(); - - let tmp = (row1 * row2).reverse().rotate_elements_right::<2>(); - let minor0 = (row3 * tmp) + minor0; - let minor3 = row0 * tmp; - let tmp = tmp.rotate_elements_right::<2>(); - - let minor0 = minor0 - row3 * tmp; - let minor3 = row0 * tmp - minor3; - let minor3 = minor3.rotate_elements_right::<2>(); - - let tmp = (row3 * row1.rotate_elements_right::<2>()) - .reverse() - .rotate_elements_right::<2>(); - let row2 = row2.rotate_elements_right::<2>(); - let minor0 = row2 * tmp + minor0; - let minor2 = row0 * tmp; - let tmp = tmp.rotate_elements_right::<2>(); - let minor0 = minor0 - row2 * tmp; - let minor2 = row0 * tmp - minor2; - let minor2 = minor2.rotate_elements_right::<2>(); - - let tmp = (row0 * row1).reverse().rotate_elements_right::<2>(); - let minor2 = minor2 + row3 * tmp; - let minor3 = row2 * tmp - minor3; - let tmp = tmp.rotate_elements_right::<2>(); - let minor2 = row3 * tmp - minor2; - let minor3 = minor3 - row2 * tmp; - - let tmp = (row0 * row3).reverse().rotate_elements_right::<2>(); - let minor1 = minor1 - row2 * tmp; - let minor2 = row1 * tmp + minor2; - let tmp = tmp.rotate_elements_right::<2>(); - let minor1 = row2 * tmp + minor1; - let minor2 = minor2 - row1 * tmp; - - let tmp = (row0 * row2).reverse().rotate_elements_right::<2>(); - let minor1 = row3 * tmp + minor1; - let minor3 = minor3 - row1 * tmp; - let tmp = tmp.rotate_elements_right::<2>(); - let minor1 = minor1 - row3 * tmp; - let minor3 = row1 * tmp + minor3; - - let det = row0 * minor0; - let det = det.rotate_elements_right::<2>() + det; - let det = det.reverse().rotate_elements_right::<2>() + det; - - if det.reduce_sum() == 0. { - return None; - } - // calculate the reciprocal - let tmp = f32x4::splat(1.0) / det; - let det = tmp + tmp - det * tmp * tmp; - - let res0 = minor0 * det; - let res1 = minor1 * det; - let res2 = minor2 * det; - let res3 = minor3 * det; - - let mut m = m; - - m[0] = res0.to_array(); - m[1] = res1.to_array(); - m[2] = res2.to_array(); - m[3] = res3.to_array(); - - Some(Matrix4x4(m)) -} - -#[cfg(test)] -#[rustfmt::skip] -mod tests { - use super::*; - - #[test] - fn test() { - let tests: &[(Matrix4x4, Option)] = &[ - // Identity: - (Matrix4x4([ - [1., 0., 0., 0.], - [0., 1., 0., 0.], - [0., 0., 1., 0.], - [0., 0., 0., 1.], - ]), - Some(Matrix4x4([ - [1., 0., 0., 0.], - [0., 1., 0., 0.], - [0., 0., 1., 0.], - [0., 0., 0., 1.], - ])) - ), - // None: - (Matrix4x4([ - [1., 2., 3., 4.], - [12., 11., 10., 9.], - [5., 6., 7., 8.], - [16., 15., 14., 13.], - ]), - None - ), - // Other: - (Matrix4x4([ - [1., 1., 1., 0.], - [0., 3., 1., 2.], - [2., 3., 1., 0.], - [1., 0., 2., 1.], - ]), - Some(Matrix4x4([ - [-3., -0.5, 1.5, 1.0], - [ 1., 0.25, -0.25, -0.5], - [ 3., 0.25, -1.25, -0.5], - [-3., 0.0, 1.0, 1.0], - ])) - ), - - - ]; - - for &(input, output) in tests { - assert_eq!(scalar_inv4x4(input), output); - assert_eq!(simd_inv4x4(input), output); - } - } -} - -fn main() { - // Empty main to make cargo happy -} diff --git a/library/portable-simd/crates/core_simd/examples/nbody.rs b/library/portable-simd/crates/core_simd/examples/nbody.rs deleted file mode 100644 index 65820d1340bd7..0000000000000 --- a/library/portable-simd/crates/core_simd/examples/nbody.rs +++ /dev/null @@ -1,194 +0,0 @@ -#![feature(portable_simd)] -#![allow(clippy::excessive_precision)] -extern crate std_float; - -/// Benchmarks game nbody code -/// Taken from the `packed_simd` crate -/// Run this benchmark with `cargo test --example nbody` -mod nbody { - use core_simd::simd::prelude::*; - #[allow(unused)] // False positive? - use std_float::StdFloat; - - use std::f64::consts::PI; - const SOLAR_MASS: f64 = 4.0 * PI * PI; - const DAYS_PER_YEAR: f64 = 365.24; - - #[derive(Debug, Clone, Copy)] - struct Body { - pub x: f64x4, - pub v: f64x4, - pub mass: f64, - } - - const N_BODIES: usize = 5; - const BODIES: [Body; N_BODIES] = [ - // sun: - Body { - x: f64x4::from_array([0., 0., 0., 0.]), - v: f64x4::from_array([0., 0., 0., 0.]), - mass: SOLAR_MASS, - }, - // jupiter: - Body { - x: f64x4::from_array([ - 4.84143144246472090e+00, - -1.16032004402742839e+00, - -1.03622044471123109e-01, - 0., - ]), - v: f64x4::from_array([ - 1.66007664274403694e-03 * DAYS_PER_YEAR, - 7.69901118419740425e-03 * DAYS_PER_YEAR, - -6.90460016972063023e-05 * DAYS_PER_YEAR, - 0., - ]), - mass: 9.54791938424326609e-04 * SOLAR_MASS, - }, - // saturn: - Body { - x: f64x4::from_array([ - 8.34336671824457987e+00, - 4.12479856412430479e+00, - -4.03523417114321381e-01, - 0., - ]), - v: f64x4::from_array([ - -2.76742510726862411e-03 * DAYS_PER_YEAR, - 4.99852801234917238e-03 * DAYS_PER_YEAR, - 2.30417297573763929e-05 * DAYS_PER_YEAR, - 0., - ]), - mass: 2.85885980666130812e-04 * SOLAR_MASS, - }, - // uranus: - Body { - x: f64x4::from_array([ - 1.28943695621391310e+01, - -1.51111514016986312e+01, - -2.23307578892655734e-01, - 0., - ]), - v: f64x4::from_array([ - 2.96460137564761618e-03 * DAYS_PER_YEAR, - 2.37847173959480950e-03 * DAYS_PER_YEAR, - -2.96589568540237556e-05 * DAYS_PER_YEAR, - 0., - ]), - mass: 4.36624404335156298e-05 * SOLAR_MASS, - }, - // neptune: - Body { - x: f64x4::from_array([ - 1.53796971148509165e+01, - -2.59193146099879641e+01, - 1.79258772950371181e-01, - 0., - ]), - v: f64x4::from_array([ - 2.68067772490389322e-03 * DAYS_PER_YEAR, - 1.62824170038242295e-03 * DAYS_PER_YEAR, - -9.51592254519715870e-05 * DAYS_PER_YEAR, - 0., - ]), - mass: 5.15138902046611451e-05 * SOLAR_MASS, - }, - ]; - - fn offset_momentum(bodies: &mut [Body; N_BODIES]) { - let (sun, rest) = bodies.split_at_mut(1); - let sun = &mut sun[0]; - for body in rest { - let m_ratio = body.mass / SOLAR_MASS; - sun.v -= body.v * Simd::splat(m_ratio); - } - } - - fn energy(bodies: &[Body; N_BODIES]) -> f64 { - let mut e = 0.; - for i in 0..N_BODIES { - let bi = &bodies[i]; - e += bi.mass * (bi.v * bi.v).reduce_sum() * 0.5; - for bj in bodies.iter().take(N_BODIES).skip(i + 1) { - let dx = bi.x - bj.x; - e -= bi.mass * bj.mass / (dx * dx).reduce_sum().sqrt() - } - } - e - } - - fn advance(bodies: &mut [Body; N_BODIES], dt: f64) { - const N: usize = N_BODIES * (N_BODIES - 1) / 2; - - // compute distance between bodies: - let mut r = [f64x4::splat(0.); N]; - { - let mut i = 0; - for j in 0..N_BODIES { - for k in j + 1..N_BODIES { - r[i] = bodies[j].x - bodies[k].x; - i += 1; - } - } - } - - let mut mag = [0.0; N]; - for i in (0..N).step_by(2) { - let d2s = f64x2::from_array([ - (r[i] * r[i]).reduce_sum(), - (r[i + 1] * r[i + 1]).reduce_sum(), - ]); - let dmags = f64x2::splat(dt) / (d2s * d2s.sqrt()); - mag[i] = dmags[0]; - mag[i + 1] = dmags[1]; - } - - let mut i = 0; - for j in 0..N_BODIES { - for k in j + 1..N_BODIES { - let f = r[i] * Simd::splat(mag[i]); - bodies[j].v -= f * Simd::splat(bodies[k].mass); - bodies[k].v += f * Simd::splat(bodies[j].mass); - i += 1 - } - } - for body in bodies { - body.x += Simd::splat(dt) * body.v - } - } - - pub fn run(n: usize) -> (f64, f64) { - let mut bodies = BODIES; - offset_momentum(&mut bodies); - let energy_before = energy(&bodies); - for _ in 0..n { - advance(&mut bodies, 0.01); - } - let energy_after = energy(&bodies); - - (energy_before, energy_after) - } -} - -#[cfg(test)] -mod tests { - // Good enough for demonstration purposes, not going for strictness here. - fn approx_eq_f64(a: f64, b: f64) -> bool { - (a - b).abs() < 0.00001 - } - #[test] - fn test() { - const OUTPUT: [f64; 2] = [-0.169075164, -0.169087605]; - let (energy_before, energy_after) = super::nbody::run(1000); - assert!(approx_eq_f64(energy_before, OUTPUT[0])); - assert!(approx_eq_f64(energy_after, OUTPUT[1])); - } -} - -fn main() { - { - let (energy_before, energy_after) = nbody::run(1000); - println!("Energy before: {energy_before}"); - println!("Energy after: {energy_after}"); - } -} diff --git a/library/portable-simd/crates/core_simd/examples/spectral_norm.rs b/library/portable-simd/crates/core_simd/examples/spectral_norm.rs deleted file mode 100644 index bc7934c252235..0000000000000 --- a/library/portable-simd/crates/core_simd/examples/spectral_norm.rs +++ /dev/null @@ -1,77 +0,0 @@ -#![feature(portable_simd)] - -use core_simd::simd::prelude::*; - -fn a(i: usize, j: usize) -> f64 { - ((i + j) * (i + j + 1) / 2 + i + 1) as f64 -} - -fn mult_av(v: &[f64], out: &mut [f64]) { - assert!(v.len() == out.len()); - assert!(v.len() % 2 == 0); - - for (i, out) in out.iter_mut().enumerate() { - let mut sum = f64x2::splat(0.0); - - let mut j = 0; - while j < v.len() { - let b = f64x2::from_slice(&v[j..]); - let a = f64x2::from_array([a(i, j), a(i, j + 1)]); - sum += b / a; - j += 2 - } - *out = sum.reduce_sum(); - } -} - -fn mult_atv(v: &[f64], out: &mut [f64]) { - assert!(v.len() == out.len()); - assert!(v.len() % 2 == 0); - - for (i, out) in out.iter_mut().enumerate() { - let mut sum = f64x2::splat(0.0); - - let mut j = 0; - while j < v.len() { - let b = f64x2::from_slice(&v[j..]); - let a = f64x2::from_array([a(j, i), a(j + 1, i)]); - sum += b / a; - j += 2 - } - *out = sum.reduce_sum(); - } -} - -fn mult_atav(v: &[f64], out: &mut [f64], tmp: &mut [f64]) { - mult_av(v, tmp); - mult_atv(tmp, out); -} - -pub fn spectral_norm(n: usize) -> f64 { - assert!(n % 2 == 0, "only even lengths are accepted"); - - let mut u = vec![1.0; n]; - let mut v = u.clone(); - let mut tmp = u.clone(); - - for _ in 0..10 { - mult_atav(&u, &mut v, &mut tmp); - mult_atav(&v, &mut u, &mut tmp); - } - (dot(&u, &v) / dot(&v, &v)).sqrt() -} - -fn dot(x: &[f64], y: &[f64]) -> f64 { - // This is auto-vectorized: - x.iter().zip(y).map(|(&x, &y)| x * y).sum() -} - -#[cfg(test)] -#[test] -fn test() { - assert_eq!(format!("{:.9}", spectral_norm(100)), "1.274219991"); -} - -fn main() { - // Empty main to make cargo happy -} diff --git a/library/portable-simd/crates/core_simd/src/alias.rs b/library/portable-simd/crates/core_simd/src/alias.rs deleted file mode 100644 index 23f121c46197c..0000000000000 --- a/library/portable-simd/crates/core_simd/src/alias.rs +++ /dev/null @@ -1,227 +0,0 @@ -macro_rules! number { - { 1 } => { "one" }; - { 2 } => { "two" }; - { 4 } => { "four" }; - { 8 } => { "eight" }; - { $x:literal } => { stringify!($x) }; -} - -macro_rules! plural { - { 1 } => { "" }; - { $x:literal } => { "s" }; -} - -macro_rules! alias { - { - $( - $element_ty:ty = { - $($alias:ident $num_elements:tt)* - } - )* - } => { - $( - $( - #[doc = concat!("A SIMD vector with ", number!($num_elements), " element", plural!($num_elements), " of type [`", stringify!($element_ty), "`].")] - #[allow(non_camel_case_types)] - pub type $alias = $crate::simd::Simd<$element_ty, $num_elements>; - )* - )* - } -} - -macro_rules! mask_alias { - { - $( - $element_ty:ty : $size:literal = { - $($alias:ident $num_elements:tt)* - } - )* - } => { - $( - $( - #[doc = concat!("A SIMD mask with ", number!($num_elements), " element", plural!($num_elements), " for vectors with ", $size, " element types.")] - /// - #[doc = concat!( - "The layout of this type is unspecified, and may change between platforms and/or Rust versions, and code should not assume that it is equivalent to `[", - stringify!($element_ty), "; ", $num_elements, "]`." - )] - #[allow(non_camel_case_types)] - pub type $alias = $crate::simd::Mask<$element_ty, $num_elements>; - )* - )* - } -} - -alias! { - i8 = { - i8x1 1 - i8x2 2 - i8x4 4 - i8x8 8 - i8x16 16 - i8x32 32 - i8x64 64 - } - - i16 = { - i16x1 1 - i16x2 2 - i16x4 4 - i16x8 8 - i16x16 16 - i16x32 32 - i16x64 64 - } - - i32 = { - i32x1 1 - i32x2 2 - i32x4 4 - i32x8 8 - i32x16 16 - i32x32 32 - i32x64 64 - } - - i64 = { - i64x1 1 - i64x2 2 - i64x4 4 - i64x8 8 - i64x16 16 - i64x32 32 - i64x64 64 - } - - isize = { - isizex1 1 - isizex2 2 - isizex4 4 - isizex8 8 - isizex16 16 - isizex32 32 - isizex64 64 - } - - u8 = { - u8x1 1 - u8x2 2 - u8x4 4 - u8x8 8 - u8x16 16 - u8x32 32 - u8x64 64 - } - - u16 = { - u16x1 1 - u16x2 2 - u16x4 4 - u16x8 8 - u16x16 16 - u16x32 32 - u16x64 64 - } - - u32 = { - u32x1 1 - u32x2 2 - u32x4 4 - u32x8 8 - u32x16 16 - u32x32 32 - u32x64 64 - } - - u64 = { - u64x1 1 - u64x2 2 - u64x4 4 - u64x8 8 - u64x16 16 - u64x32 32 - u64x64 64 - } - - usize = { - usizex1 1 - usizex2 2 - usizex4 4 - usizex8 8 - usizex16 16 - usizex32 32 - usizex64 64 - } - - f32 = { - f32x1 1 - f32x2 2 - f32x4 4 - f32x8 8 - f32x16 16 - f32x32 32 - f32x64 64 - } - - f64 = { - f64x1 1 - f64x2 2 - f64x4 4 - f64x8 8 - f64x16 16 - f64x32 32 - f64x64 64 - } -} - -mask_alias! { - i8 : "8-bit" = { - mask8x1 1 - mask8x2 2 - mask8x4 4 - mask8x8 8 - mask8x16 16 - mask8x32 32 - mask8x64 64 - } - - i16 : "16-bit" = { - mask16x1 1 - mask16x2 2 - mask16x4 4 - mask16x8 8 - mask16x16 16 - mask16x32 32 - mask16x64 64 - } - - i32 : "32-bit" = { - mask32x1 1 - mask32x2 2 - mask32x4 4 - mask32x8 8 - mask32x16 16 - mask32x32 32 - mask32x64 64 - } - - i64 : "64-bit" = { - mask64x1 1 - mask64x2 2 - mask64x4 4 - mask64x8 8 - mask64x16 16 - mask64x32 32 - mask64x64 64 - } - - isize : "pointer-sized" = { - masksizex1 1 - masksizex2 2 - masksizex4 4 - masksizex8 8 - masksizex16 16 - masksizex32 32 - masksizex64 64 - } -} diff --git a/library/portable-simd/crates/core_simd/src/cast.rs b/library/portable-simd/crates/core_simd/src/cast.rs deleted file mode 100644 index 1c3592f807578..0000000000000 --- a/library/portable-simd/crates/core_simd/src/cast.rs +++ /dev/null @@ -1,51 +0,0 @@ -use crate::simd::SimdElement; - -mod sealed { - /// Cast vector elements to other types. - /// - /// # Safety - /// Implementing this trait asserts that the type is a valid vector element for the `simd_cast` - /// or `simd_as` intrinsics. - pub unsafe trait Sealed {} -} -use sealed::Sealed; - -/// Supporting trait for `Simd::cast`. Typically doesn't need to be used directly. -pub trait SimdCast: Sealed + SimdElement {} - -// Safety: primitive number types can be cast to other primitive number types -unsafe impl Sealed for i8 {} -impl SimdCast for i8 {} -// Safety: primitive number types can be cast to other primitive number types -unsafe impl Sealed for i16 {} -impl SimdCast for i16 {} -// Safety: primitive number types can be cast to other primitive number types -unsafe impl Sealed for i32 {} -impl SimdCast for i32 {} -// Safety: primitive number types can be cast to other primitive number types -unsafe impl Sealed for i64 {} -impl SimdCast for i64 {} -// Safety: primitive number types can be cast to other primitive number types -unsafe impl Sealed for isize {} -impl SimdCast for isize {} -// Safety: primitive number types can be cast to other primitive number types -unsafe impl Sealed for u8 {} -impl SimdCast for u8 {} -// Safety: primitive number types can be cast to other primitive number types -unsafe impl Sealed for u16 {} -impl SimdCast for u16 {} -// Safety: primitive number types can be cast to other primitive number types -unsafe impl Sealed for u32 {} -impl SimdCast for u32 {} -// Safety: primitive number types can be cast to other primitive number types -unsafe impl Sealed for u64 {} -impl SimdCast for u64 {} -// Safety: primitive number types can be cast to other primitive number types -unsafe impl Sealed for usize {} -impl SimdCast for usize {} -// Safety: primitive number types can be cast to other primitive number types -unsafe impl Sealed for f32 {} -impl SimdCast for f32 {} -// Safety: primitive number types can be cast to other primitive number types -unsafe impl Sealed for f64 {} -impl SimdCast for f64 {} diff --git a/library/portable-simd/crates/core_simd/src/core_simd_docs.md b/library/portable-simd/crates/core_simd/src/core_simd_docs.md deleted file mode 100644 index bf412e035b513..0000000000000 --- a/library/portable-simd/crates/core_simd/src/core_simd_docs.md +++ /dev/null @@ -1,39 +0,0 @@ -Portable SIMD module. - -This module offers a portable abstraction for SIMD operations -that is not bound to any particular hardware architecture. - -# What is "portable"? - -This module provides a SIMD implementation that is fast and predictable on any target. - -### Portable SIMD works on every target - -Unlike target-specific SIMD in `std::arch`, portable SIMD compiles for every target. -In this regard, it is just like "regular" Rust. - -### Portable SIMD is consistent between targets - -A program using portable SIMD can expect identical behavior on any target. -In most regards, [`Simd`] can be thought of as a parallelized `[T; N]` and operates like a sequence of `T`. - -This has one notable exception: a handful of older architectures (e.g. `armv7` and `powerpc`) flush [subnormal](`f32::is_subnormal`) `f32` values to zero. -On these architectures, subnormal `f32` input values are replaced with zeros, and any operation producing subnormal `f32` values produces zeros instead. -This doesn't affect most architectures or programs. - -### Operations use the best instructions available - -Operations provided by this module compile to the best available SIMD instructions. - -Portable SIMD is not a low-level vendor library, and operations in portable SIMD _do not_ necessarily map to a single instruction. -Instead, they map to a reasonable implementation of the operation for the target. - -Consistency between targets is not compromised to use faster or fewer instructions. -In some cases, `std::arch` will provide a faster function that has slightly different behavior than the `std::simd` equivalent. -For example, `_mm_min_ps`[^1] can be slightly faster than [`SimdFloat::simd_min`](`num::SimdFloat::simd_min`), but does not conform to the IEEE standard also used by [`f32::min`]. -When necessary, [`Simd`] can be converted to the types provided by `std::arch` to make use of target-specific functions. - -Many targets simply don't have SIMD, or don't support SIMD for a particular element type. -In those cases, regular scalar operations are generated instead. - -[^1]: `_mm_min_ps(x, y)` is equivalent to `x.simd_lt(y).select(x, y)` diff --git a/library/portable-simd/crates/core_simd/src/fmt.rs b/library/portable-simd/crates/core_simd/src/fmt.rs deleted file mode 100644 index 3a540f5a04908..0000000000000 --- a/library/portable-simd/crates/core_simd/src/fmt.rs +++ /dev/null @@ -1,21 +0,0 @@ -use crate::simd::{LaneCount, Simd, SimdElement, SupportedLaneCount}; -use core::fmt; - -impl fmt::Debug for Simd -where - LaneCount: SupportedLaneCount, - T: SimdElement + fmt::Debug, -{ - /// A `Simd` has a debug format like the one for `[T]`: - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd::Simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd::Simd; - /// let floats = Simd::::splat(-1.0); - /// assert_eq!(format!("{:?}", [-1.0; 4]), format!("{:?}", floats)); - /// ``` - #[inline] - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - <[T] as fmt::Debug>::fmt(self.as_array(), f) - } -} diff --git a/library/portable-simd/crates/core_simd/src/iter.rs b/library/portable-simd/crates/core_simd/src/iter.rs deleted file mode 100644 index b3732fd74d5f6..0000000000000 --- a/library/portable-simd/crates/core_simd/src/iter.rs +++ /dev/null @@ -1,62 +0,0 @@ -use crate::simd::{LaneCount, Simd, SupportedLaneCount}; -use core::{ - iter::{Product, Sum}, - ops::{Add, Mul}, -}; - -macro_rules! impl_traits { - { $type:ty } => { - impl Sum for Simd<$type, N> - where - LaneCount: SupportedLaneCount, - { - #[inline] - fn sum>(iter: I) -> Self { - iter.fold(Simd::splat(0 as $type), Add::add) - } - } - - impl Product for Simd<$type, N> - where - LaneCount: SupportedLaneCount, - { - #[inline] - fn product>(iter: I) -> Self { - iter.fold(Simd::splat(1 as $type), Mul::mul) - } - } - - impl<'a, const N: usize> Sum<&'a Self> for Simd<$type, N> - where - LaneCount: SupportedLaneCount, - { - #[inline] - fn sum>(iter: I) -> Self { - iter.fold(Simd::splat(0 as $type), Add::add) - } - } - - impl<'a, const N: usize> Product<&'a Self> for Simd<$type, N> - where - LaneCount: SupportedLaneCount, - { - #[inline] - fn product>(iter: I) -> Self { - iter.fold(Simd::splat(1 as $type), Mul::mul) - } - } - } -} - -impl_traits! { f32 } -impl_traits! { f64 } -impl_traits! { u8 } -impl_traits! { u16 } -impl_traits! { u32 } -impl_traits! { u64 } -impl_traits! { usize } -impl_traits! { i8 } -impl_traits! { i16 } -impl_traits! { i32 } -impl_traits! { i64 } -impl_traits! { isize } diff --git a/library/portable-simd/crates/core_simd/src/lane_count.rs b/library/portable-simd/crates/core_simd/src/lane_count.rs deleted file mode 100644 index 4cd7265ed671e..0000000000000 --- a/library/portable-simd/crates/core_simd/src/lane_count.rs +++ /dev/null @@ -1,42 +0,0 @@ -mod sealed { - pub trait Sealed {} -} -use sealed::Sealed; - -/// Specifies the number of lanes in a SIMD vector as a type. -pub struct LaneCount; - -impl LaneCount { - /// The number of bytes in a bitmask with this many lanes. - pub const BITMASK_LEN: usize = (N + 7) / 8; -} - -/// Statically guarantees that a lane count is marked as supported. -/// -/// This trait is *sealed*: the list of implementors below is total. -/// Users do not have the ability to mark additional `LaneCount` values as supported. -/// Only SIMD vectors with supported lane counts are constructable. -pub trait SupportedLaneCount: Sealed { - #[doc(hidden)] - type BitMask: Copy + Default + AsRef<[u8]> + AsMut<[u8]>; -} - -impl Sealed for LaneCount {} - -macro_rules! supported_lane_count { - ($($lanes:literal),+) => { - $( - impl SupportedLaneCount for LaneCount<$lanes> { - type BitMask = [u8; ($lanes + 7) / 8]; - } - )+ - }; -} - -supported_lane_count!(1, 2, 4, 8, 16, 32, 64); -#[cfg(feature = "all_lane_counts")] -supported_lane_count!( - 3, 5, 6, 7, 9, 10, 11, 12, 13, 14, 15, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 27, 28, 29, 30, - 31, 33, 34, 35, 36, 37, 38, 39, 40, 41, 42, 43, 44, 45, 46, 47, 48, 49, 50, 51, 52, 53, 54, 55, - 56, 57, 58, 59, 60, 61, 62, 63 -); diff --git a/library/portable-simd/crates/core_simd/src/lib.rs b/library/portable-simd/crates/core_simd/src/lib.rs deleted file mode 100644 index 331b66262490c..0000000000000 --- a/library/portable-simd/crates/core_simd/src/lib.rs +++ /dev/null @@ -1,49 +0,0 @@ -#![no_std] -#![feature( - const_intrinsic_copy, - const_refs_to_cell, - const_maybe_uninit_as_mut_ptr, - const_mut_refs, - convert_float_to_int, - core_intrinsics, - decl_macro, - intra_doc_pointers, - repr_simd, - simd_ffi, - staged_api, - strict_provenance, - prelude_import, - ptr_metadata -)] -#![cfg_attr( - all( - any(target_arch = "aarch64", target_arch = "arm64ec", target_arch = "arm",), - any( - all(target_feature = "v6", not(target_feature = "mclass")), - all(target_feature = "mclass", target_feature = "dsp"), - ) - ), - feature(stdarch_arm_dsp) -)] -#![cfg_attr( - all(target_arch = "arm", target_feature = "v7"), - feature(stdarch_arm_neon_intrinsics) -)] -#![cfg_attr( - any(target_arch = "powerpc", target_arch = "powerpc64"), - feature(stdarch_powerpc) -)] -#![cfg_attr( - all(target_arch = "x86_64", target_feature = "avx512f"), - feature(stdarch_x86_avx512) -)] -#![warn(missing_docs, clippy::missing_inline_in_public_items)] // basically all items, really -#![deny(unsafe_op_in_unsafe_fn, clippy::undocumented_unsafe_blocks)] -#![doc(test(attr(deny(warnings))))] -#![allow(internal_features)] -#![unstable(feature = "portable_simd", issue = "86656")] -//! Portable SIMD module. - -#[path = "mod.rs"] -mod core_simd; -pub use self::core_simd::simd; diff --git a/library/portable-simd/crates/core_simd/src/masks.rs b/library/portable-simd/crates/core_simd/src/masks.rs deleted file mode 100644 index e6e27c76a5e99..0000000000000 --- a/library/portable-simd/crates/core_simd/src/masks.rs +++ /dev/null @@ -1,704 +0,0 @@ -//! Types and traits associated with masking elements of vectors. -//! Types representing -#![allow(non_camel_case_types)] - -#[cfg_attr( - not(all(target_arch = "x86_64", target_feature = "avx512f")), - path = "masks/full_masks.rs" -)] -#[cfg_attr( - all(target_arch = "x86_64", target_feature = "avx512f"), - path = "masks/bitmask.rs" -)] -mod mask_impl; - -use crate::simd::{LaneCount, Simd, SimdCast, SimdElement, SupportedLaneCount}; -use core::cmp::Ordering; -use core::{fmt, mem}; - -mod sealed { - use super::*; - - /// Not only does this seal the `MaskElement` trait, but these functions prevent other traits - /// from bleeding into the parent bounds. - /// - /// For example, `eq` could be provided by requiring `MaskElement: PartialEq`, but that would - /// prevent us from ever removing that bound, or from implementing `MaskElement` on - /// non-`PartialEq` types in the future. - pub trait Sealed { - fn valid(values: Simd) -> bool - where - LaneCount: SupportedLaneCount, - Self: SimdElement; - - fn eq(self, other: Self) -> bool; - - fn to_usize(self) -> usize; - fn max_unsigned() -> u64; - - type Unsigned: SimdElement; - - const TRUE: Self; - - const FALSE: Self; - } -} -use sealed::Sealed; - -/// Marker trait for types that may be used as SIMD mask elements. -/// -/// # Safety -/// Type must be a signed integer. -pub unsafe trait MaskElement: SimdElement + SimdCast + Sealed {} - -macro_rules! impl_element { - { $ty:ty, $unsigned:ty } => { - impl Sealed for $ty { - #[inline] - fn valid(value: Simd) -> bool - where - LaneCount: SupportedLaneCount, - { - // We can't use `Simd` directly, because `Simd`'s functions call this function and - // we will end up with an infinite loop. - // Safety: `value` is an integer vector - unsafe { - use core::intrinsics::simd; - let falses: Simd = simd::simd_eq(value, Simd::splat(0 as _)); - let trues: Simd = simd::simd_eq(value, Simd::splat(-1 as _)); - let valid: Simd = simd::simd_or(falses, trues); - simd::simd_reduce_all(valid) - } - } - - #[inline] - fn eq(self, other: Self) -> bool { self == other } - - #[inline] - fn to_usize(self) -> usize { - self as usize - } - - #[inline] - fn max_unsigned() -> u64 { - <$unsigned>::MAX as u64 - } - - type Unsigned = $unsigned; - - const TRUE: Self = -1; - const FALSE: Self = 0; - } - - // Safety: this is a valid mask element type - unsafe impl MaskElement for $ty {} - } -} - -impl_element! { i8, u8 } -impl_element! { i16, u16 } -impl_element! { i32, u32 } -impl_element! { i64, u64 } -impl_element! { isize, usize } - -/// A SIMD vector mask for `N` elements of width specified by `Element`. -/// -/// Masks represent boolean inclusion/exclusion on a per-element basis. -/// -/// The layout of this type is unspecified, and may change between platforms -/// and/or Rust versions, and code should not assume that it is equivalent to -/// `[T; N]`. -#[repr(transparent)] -pub struct Mask(mask_impl::Mask) -where - T: MaskElement, - LaneCount: SupportedLaneCount; - -impl Copy for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ -} - -impl Clone for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - #[inline] - fn clone(&self) -> Self { - *self - } -} - -impl Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - /// Construct a mask by setting all elements to the given value. - #[inline] - pub fn splat(value: bool) -> Self { - Self(mask_impl::Mask::splat(value)) - } - - /// Converts an array of bools to a SIMD mask. - #[inline] - pub fn from_array(array: [bool; N]) -> Self { - // SAFETY: Rust's bool has a layout of 1 byte (u8) with a value of - // true: 0b_0000_0001 - // false: 0b_0000_0000 - // Thus, an array of bools is also a valid array of bytes: [u8; N] - // This would be hypothetically valid as an "in-place" transmute, - // but these are "dependently-sized" types, so copy elision it is! - unsafe { - let bytes: [u8; N] = mem::transmute_copy(&array); - let bools: Simd = - core::intrinsics::simd::simd_ne(Simd::from_array(bytes), Simd::splat(0u8)); - Mask::from_int_unchecked(core::intrinsics::simd::simd_cast(bools)) - } - } - - /// Converts a SIMD mask to an array of bools. - #[inline] - pub fn to_array(self) -> [bool; N] { - // This follows mostly the same logic as from_array. - // SAFETY: Rust's bool has a layout of 1 byte (u8) with a value of - // true: 0b_0000_0001 - // false: 0b_0000_0000 - // Thus, an array of bools is also a valid array of bytes: [u8; N] - // Since our masks are equal to integers where all bits are set, - // we can simply convert them to i8s, and then bitand them by the - // bitpattern for Rust's "true" bool. - // This would be hypothetically valid as an "in-place" transmute, - // but these are "dependently-sized" types, so copy elision it is! - unsafe { - let mut bytes: Simd = core::intrinsics::simd::simd_cast(self.to_int()); - bytes &= Simd::splat(1i8); - mem::transmute_copy(&bytes) - } - } - - /// Converts a vector of integers to a mask, where 0 represents `false` and -1 - /// represents `true`. - /// - /// # Safety - /// All elements must be either 0 or -1. - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - pub unsafe fn from_int_unchecked(value: Simd) -> Self { - // Safety: the caller must confirm this invariant - unsafe { - core::intrinsics::assume(::valid(value)); - Self(mask_impl::Mask::from_int_unchecked(value)) - } - } - - /// Converts a vector of integers to a mask, where 0 represents `false` and -1 - /// represents `true`. - /// - /// # Panics - /// Panics if any element is not 0 or -1. - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - #[track_caller] - pub fn from_int(value: Simd) -> Self { - assert!(T::valid(value), "all values must be either 0 or -1",); - // Safety: the validity has been checked - unsafe { Self::from_int_unchecked(value) } - } - - /// Converts the mask to a vector of integers, where 0 represents `false` and -1 - /// represents `true`. - #[inline] - #[must_use = "method returns a new vector and does not mutate the original value"] - pub fn to_int(self) -> Simd { - self.0.to_int() - } - - /// Converts the mask to a mask of any other element size. - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - pub fn cast(self) -> Mask { - Mask(self.0.convert()) - } - - /// Tests the value of the specified element. - /// - /// # Safety - /// `index` must be less than `self.len()`. - #[inline] - #[must_use = "method returns a new bool and does not mutate the original value"] - pub unsafe fn test_unchecked(&self, index: usize) -> bool { - // Safety: the caller must confirm this invariant - unsafe { self.0.test_unchecked(index) } - } - - /// Tests the value of the specified element. - /// - /// # Panics - /// Panics if `index` is greater than or equal to the number of elements in the vector. - #[inline] - #[must_use = "method returns a new bool and does not mutate the original value"] - #[track_caller] - pub fn test(&self, index: usize) -> bool { - assert!(index < N, "element index out of range"); - // Safety: the element index has been checked - unsafe { self.test_unchecked(index) } - } - - /// Sets the value of the specified element. - /// - /// # Safety - /// `index` must be less than `self.len()`. - #[inline] - pub unsafe fn set_unchecked(&mut self, index: usize, value: bool) { - // Safety: the caller must confirm this invariant - unsafe { - self.0.set_unchecked(index, value); - } - } - - /// Sets the value of the specified element. - /// - /// # Panics - /// Panics if `index` is greater than or equal to the number of elements in the vector. - #[inline] - #[track_caller] - pub fn set(&mut self, index: usize, value: bool) { - assert!(index < N, "element index out of range"); - // Safety: the element index has been checked - unsafe { - self.set_unchecked(index, value); - } - } - - /// Returns true if any element is set, or false otherwise. - #[inline] - #[must_use = "method returns a new bool and does not mutate the original value"] - pub fn any(self) -> bool { - self.0.any() - } - - /// Returns true if all elements are set, or false otherwise. - #[inline] - #[must_use = "method returns a new bool and does not mutate the original value"] - pub fn all(self) -> bool { - self.0.all() - } - - /// Create a bitmask from a mask. - /// - /// Each bit is set if the corresponding element in the mask is `true`. - /// If the mask contains more than 64 elements, the bitmask is truncated to the first 64. - #[inline] - #[must_use = "method returns a new integer and does not mutate the original value"] - pub fn to_bitmask(self) -> u64 { - self.0.to_bitmask_integer() - } - - /// Create a mask from a bitmask. - /// - /// For each bit, if it is set, the corresponding element in the mask is set to `true`. - /// If the mask contains more than 64 elements, the remainder are set to `false`. - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - pub fn from_bitmask(bitmask: u64) -> Self { - Self(mask_impl::Mask::from_bitmask_integer(bitmask)) - } - - /// Create a bitmask vector from a mask. - /// - /// Each bit is set if the corresponding element in the mask is `true`. - /// The remaining bits are unset. - /// - /// The bits are packed into the first N bits of the vector: - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::mask32x8; - /// let mask = mask32x8::from_array([true, false, true, false, false, false, true, false]); - /// assert_eq!(mask.to_bitmask_vector()[0], 0b01000101); - /// ``` - #[inline] - #[must_use = "method returns a new integer and does not mutate the original value"] - pub fn to_bitmask_vector(self) -> Simd { - self.0.to_bitmask_vector() - } - - /// Create a mask from a bitmask vector. - /// - /// For each bit, if it is set, the corresponding element in the mask is set to `true`. - /// - /// The bits are packed into the first N bits of the vector: - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::{mask32x8, u8x8}; - /// let bitmask = u8x8::from_array([0b01000101, 0, 0, 0, 0, 0, 0, 0]); - /// assert_eq!( - /// mask32x8::from_bitmask_vector(bitmask), - /// mask32x8::from_array([true, false, true, false, false, false, true, false]), - /// ); - /// ``` - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - pub fn from_bitmask_vector(bitmask: Simd) -> Self { - Self(mask_impl::Mask::from_bitmask_vector(bitmask)) - } - - /// Find the index of the first set element. - /// - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::mask32x8; - /// assert_eq!(mask32x8::splat(false).first_set(), None); - /// assert_eq!(mask32x8::splat(true).first_set(), Some(0)); - /// - /// let mask = mask32x8::from_array([false, true, false, false, true, false, false, true]); - /// assert_eq!(mask.first_set(), Some(1)); - /// ``` - #[inline] - #[must_use = "method returns the index and does not mutate the original value"] - pub fn first_set(self) -> Option { - // If bitmasks are efficient, using them is better - if cfg!(target_feature = "sse") && N <= 64 { - let tz = self.to_bitmask().trailing_zeros(); - return if tz == 64 { None } else { Some(tz as usize) }; - } - - // To find the first set index: - // * create a vector 0..N - // * replace unset mask elements in that vector with -1 - // * perform _unsigned_ reduce-min - // * check if the result is -1 or an index - - let index = Simd::from_array( - const { - let mut index = [0; N]; - let mut i = 0; - while i < N { - index[i] = i; - i += 1; - } - index - }, - ); - - // Safety: the input and output are integer vectors - let index: Simd = unsafe { core::intrinsics::simd::simd_cast(index) }; - - let masked_index = self.select(index, Self::splat(true).to_int()); - - // Safety: the input and output are integer vectors - let masked_index: Simd = - unsafe { core::intrinsics::simd::simd_cast(masked_index) }; - - // Safety: the input is an integer vector - let min_index: T::Unsigned = - unsafe { core::intrinsics::simd::simd_reduce_min(masked_index) }; - - // Safety: the return value is the unsigned version of T - let min_index: T = unsafe { core::mem::transmute_copy(&min_index) }; - - if min_index.eq(T::TRUE) { - None - } else { - Some(min_index.to_usize()) - } - } -} - -// vector/array conversion -impl From<[bool; N]> for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - #[inline] - fn from(array: [bool; N]) -> Self { - Self::from_array(array) - } -} - -impl From> for [bool; N] -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - #[inline] - fn from(vector: Mask) -> Self { - vector.to_array() - } -} - -impl Default for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - #[inline] - #[must_use = "method returns a defaulted mask with all elements set to false (0)"] - fn default() -> Self { - Self::splat(false) - } -} - -impl PartialEq for Mask -where - T: MaskElement + PartialEq, - LaneCount: SupportedLaneCount, -{ - #[inline] - #[must_use = "method returns a new bool and does not mutate the original value"] - fn eq(&self, other: &Self) -> bool { - self.0 == other.0 - } -} - -impl PartialOrd for Mask -where - T: MaskElement + PartialOrd, - LaneCount: SupportedLaneCount, -{ - #[inline] - #[must_use = "method returns a new Ordering and does not mutate the original value"] - fn partial_cmp(&self, other: &Self) -> Option { - self.0.partial_cmp(&other.0) - } -} - -impl fmt::Debug for Mask -where - T: MaskElement + fmt::Debug, - LaneCount: SupportedLaneCount, -{ - #[inline] - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list() - .entries((0..N).map(|i| self.test(i))) - .finish() - } -} - -impl core::ops::BitAnd for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - type Output = Self; - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - fn bitand(self, rhs: Self) -> Self { - Self(self.0 & rhs.0) - } -} - -impl core::ops::BitAnd for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - type Output = Self; - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - fn bitand(self, rhs: bool) -> Self { - self & Self::splat(rhs) - } -} - -impl core::ops::BitAnd> for bool -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - type Output = Mask; - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - fn bitand(self, rhs: Mask) -> Mask { - Mask::splat(self) & rhs - } -} - -impl core::ops::BitOr for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - type Output = Self; - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - fn bitor(self, rhs: Self) -> Self { - Self(self.0 | rhs.0) - } -} - -impl core::ops::BitOr for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - type Output = Self; - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - fn bitor(self, rhs: bool) -> Self { - self | Self::splat(rhs) - } -} - -impl core::ops::BitOr> for bool -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - type Output = Mask; - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - fn bitor(self, rhs: Mask) -> Mask { - Mask::splat(self) | rhs - } -} - -impl core::ops::BitXor for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - type Output = Self; - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - fn bitxor(self, rhs: Self) -> Self::Output { - Self(self.0 ^ rhs.0) - } -} - -impl core::ops::BitXor for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - type Output = Self; - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - fn bitxor(self, rhs: bool) -> Self::Output { - self ^ Self::splat(rhs) - } -} - -impl core::ops::BitXor> for bool -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - type Output = Mask; - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - fn bitxor(self, rhs: Mask) -> Self::Output { - Mask::splat(self) ^ rhs - } -} - -impl core::ops::Not for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - type Output = Mask; - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - fn not(self) -> Self::Output { - Self(!self.0) - } -} - -impl core::ops::BitAndAssign for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - #[inline] - fn bitand_assign(&mut self, rhs: Self) { - self.0 = self.0 & rhs.0; - } -} - -impl core::ops::BitAndAssign for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - #[inline] - fn bitand_assign(&mut self, rhs: bool) { - *self &= Self::splat(rhs); - } -} - -impl core::ops::BitOrAssign for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - #[inline] - fn bitor_assign(&mut self, rhs: Self) { - self.0 = self.0 | rhs.0; - } -} - -impl core::ops::BitOrAssign for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - #[inline] - fn bitor_assign(&mut self, rhs: bool) { - *self |= Self::splat(rhs); - } -} - -impl core::ops::BitXorAssign for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - #[inline] - fn bitxor_assign(&mut self, rhs: Self) { - self.0 = self.0 ^ rhs.0; - } -} - -impl core::ops::BitXorAssign for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - #[inline] - fn bitxor_assign(&mut self, rhs: bool) { - *self ^= Self::splat(rhs); - } -} - -macro_rules! impl_from { - { $from:ty => $($to:ty),* } => { - $( - impl From> for Mask<$to, N> - where - LaneCount: SupportedLaneCount, - { - #[inline] - fn from(value: Mask<$from, N>) -> Self { - value.cast() - } - } - )* - } -} -impl_from! { i8 => i16, i32, i64, isize } -impl_from! { i16 => i32, i64, isize, i8 } -impl_from! { i32 => i64, isize, i8, i16 } -impl_from! { i64 => isize, i8, i16, i32 } -impl_from! { isize => i8, i16, i32, i64 } diff --git a/library/portable-simd/crates/core_simd/src/masks/bitmask.rs b/library/portable-simd/crates/core_simd/src/masks/bitmask.rs deleted file mode 100644 index 96c553426ee74..0000000000000 --- a/library/portable-simd/crates/core_simd/src/masks/bitmask.rs +++ /dev/null @@ -1,249 +0,0 @@ -#![allow(unused_imports)] -use super::MaskElement; -use crate::simd::{LaneCount, Simd, SupportedLaneCount}; -use core::marker::PhantomData; - -/// A mask where each lane is represented by a single bit. -#[repr(transparent)] -pub struct Mask( - as SupportedLaneCount>::BitMask, - PhantomData, -) -where - T: MaskElement, - LaneCount: SupportedLaneCount; - -impl Copy for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ -} - -impl Clone for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - #[inline] - fn clone(&self) -> Self { - *self - } -} - -impl PartialEq for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - #[inline] - fn eq(&self, other: &Self) -> bool { - self.0.as_ref() == other.0.as_ref() - } -} - -impl PartialOrd for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - #[inline] - fn partial_cmp(&self, other: &Self) -> Option { - self.0.as_ref().partial_cmp(other.0.as_ref()) - } -} - -impl Eq for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ -} - -impl Ord for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - #[inline] - fn cmp(&self, other: &Self) -> core::cmp::Ordering { - self.0.as_ref().cmp(other.0.as_ref()) - } -} - -impl Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - pub fn splat(value: bool) -> Self { - let mut mask = as SupportedLaneCount>::BitMask::default(); - if value { - mask.as_mut().fill(u8::MAX) - } else { - mask.as_mut().fill(u8::MIN) - } - if N % 8 > 0 { - *mask.as_mut().last_mut().unwrap() &= u8::MAX >> (8 - N % 8); - } - Self(mask, PhantomData) - } - - #[inline] - #[must_use = "method returns a new bool and does not mutate the original value"] - pub unsafe fn test_unchecked(&self, lane: usize) -> bool { - (self.0.as_ref()[lane / 8] >> (lane % 8)) & 0x1 > 0 - } - - #[inline] - pub unsafe fn set_unchecked(&mut self, lane: usize, value: bool) { - unsafe { - self.0.as_mut()[lane / 8] ^= ((value ^ self.test_unchecked(lane)) as u8) << (lane % 8) - } - } - - #[inline] - #[must_use = "method returns a new vector and does not mutate the original value"] - pub fn to_int(self) -> Simd { - unsafe { - core::intrinsics::simd::simd_select_bitmask( - self.0, - Simd::splat(T::TRUE), - Simd::splat(T::FALSE), - ) - } - } - - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - pub unsafe fn from_int_unchecked(value: Simd) -> Self { - unsafe { Self(core::intrinsics::simd::simd_bitmask(value), PhantomData) } - } - - #[inline] - #[must_use = "method returns a new vector and does not mutate the original value"] - pub fn to_bitmask_vector(self) -> Simd { - let mut bitmask = Simd::splat(0); - bitmask.as_mut_array()[..self.0.as_ref().len()].copy_from_slice(self.0.as_ref()); - bitmask - } - - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - pub fn from_bitmask_vector(bitmask: Simd) -> Self { - let mut bytes = as SupportedLaneCount>::BitMask::default(); - let len = bytes.as_ref().len(); - bytes.as_mut().copy_from_slice(&bitmask.as_array()[..len]); - Self(bytes, PhantomData) - } - - #[inline] - pub fn to_bitmask_integer(self) -> u64 { - let mut bitmask = [0u8; 8]; - bitmask[..self.0.as_ref().len()].copy_from_slice(self.0.as_ref()); - u64::from_ne_bytes(bitmask) - } - - #[inline] - pub fn from_bitmask_integer(bitmask: u64) -> Self { - let mut bytes = as SupportedLaneCount>::BitMask::default(); - let len = bytes.as_mut().len(); - bytes - .as_mut() - .copy_from_slice(&bitmask.to_ne_bytes()[..len]); - Self(bytes, PhantomData) - } - - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - pub fn convert(self) -> Mask - where - U: MaskElement, - { - // Safety: bitmask layout does not depend on the element width - unsafe { core::mem::transmute_copy(&self) } - } - - #[inline] - #[must_use = "method returns a new bool and does not mutate the original value"] - pub fn any(self) -> bool { - self != Self::splat(false) - } - - #[inline] - #[must_use = "method returns a new bool and does not mutate the original value"] - pub fn all(self) -> bool { - self == Self::splat(true) - } -} - -impl core::ops::BitAnd for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, - as SupportedLaneCount>::BitMask: AsRef<[u8]> + AsMut<[u8]>, -{ - type Output = Self; - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - fn bitand(mut self, rhs: Self) -> Self { - for (l, r) in self.0.as_mut().iter_mut().zip(rhs.0.as_ref().iter()) { - *l &= r; - } - self - } -} - -impl core::ops::BitOr for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, - as SupportedLaneCount>::BitMask: AsRef<[u8]> + AsMut<[u8]>, -{ - type Output = Self; - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - fn bitor(mut self, rhs: Self) -> Self { - for (l, r) in self.0.as_mut().iter_mut().zip(rhs.0.as_ref().iter()) { - *l |= r; - } - self - } -} - -impl core::ops::BitXor for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - type Output = Self; - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - fn bitxor(mut self, rhs: Self) -> Self::Output { - for (l, r) in self.0.as_mut().iter_mut().zip(rhs.0.as_ref().iter()) { - *l ^= r; - } - self - } -} - -impl core::ops::Not for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - type Output = Self; - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - fn not(mut self) -> Self::Output { - for x in self.0.as_mut() { - *x = !*x; - } - if N % 8 > 0 { - *self.0.as_mut().last_mut().unwrap() &= u8::MAX >> (8 - N % 8); - } - self - } -} diff --git a/library/portable-simd/crates/core_simd/src/masks/full_masks.rs b/library/portable-simd/crates/core_simd/src/masks/full_masks.rs deleted file mode 100644 index 87f031a9f367a..0000000000000 --- a/library/portable-simd/crates/core_simd/src/masks/full_masks.rs +++ /dev/null @@ -1,357 +0,0 @@ -//! Masks that take up full SIMD vector registers. - -use crate::simd::{LaneCount, MaskElement, Simd, SupportedLaneCount}; - -#[repr(transparent)] -pub struct Mask(Simd) -where - T: MaskElement, - LaneCount: SupportedLaneCount; - -impl Copy for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ -} - -impl Clone for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - fn clone(&self) -> Self { - *self - } -} - -impl PartialEq for Mask -where - T: MaskElement + PartialEq, - LaneCount: SupportedLaneCount, -{ - #[inline] - fn eq(&self, other: &Self) -> bool { - self.0.eq(&other.0) - } -} - -impl PartialOrd for Mask -where - T: MaskElement + PartialOrd, - LaneCount: SupportedLaneCount, -{ - #[inline] - fn partial_cmp(&self, other: &Self) -> Option { - self.0.partial_cmp(&other.0) - } -} - -impl Eq for Mask -where - T: MaskElement + Eq, - LaneCount: SupportedLaneCount, -{ -} - -impl Ord for Mask -where - T: MaskElement + Ord, - LaneCount: SupportedLaneCount, -{ - #[inline] - fn cmp(&self, other: &Self) -> core::cmp::Ordering { - self.0.cmp(&other.0) - } -} - -// Used for bitmask bit order workaround -pub(crate) trait ReverseBits { - // Reverse the least significant `n` bits of `self`. - // (Remaining bits must be 0.) - fn reverse_bits(self, n: usize) -> Self; -} - -macro_rules! impl_reverse_bits { - { $($int:ty),* } => { - $( - impl ReverseBits for $int { - #[inline(always)] - fn reverse_bits(self, n: usize) -> Self { - let rev = <$int>::reverse_bits(self); - let bitsize = core::mem::size_of::<$int>() * 8; - if n < bitsize { - // Shift things back to the right - rev >> (bitsize - n) - } else { - rev - } - } - } - )* - } -} - -impl_reverse_bits! { u8, u16, u32, u64 } - -impl Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - pub fn splat(value: bool) -> Self { - Self(Simd::splat(if value { T::TRUE } else { T::FALSE })) - } - - #[inline] - #[must_use = "method returns a new bool and does not mutate the original value"] - pub unsafe fn test_unchecked(&self, lane: usize) -> bool { - T::eq(self.0[lane], T::TRUE) - } - - #[inline] - pub unsafe fn set_unchecked(&mut self, lane: usize, value: bool) { - self.0[lane] = if value { T::TRUE } else { T::FALSE } - } - - #[inline] - #[must_use = "method returns a new vector and does not mutate the original value"] - pub fn to_int(self) -> Simd { - self.0 - } - - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - pub unsafe fn from_int_unchecked(value: Simd) -> Self { - Self(value) - } - - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - pub fn convert(self) -> Mask - where - U: MaskElement, - { - // Safety: masks are simply integer vectors of 0 and -1, and we can cast the element type. - unsafe { Mask(core::intrinsics::simd::simd_cast(self.0)) } - } - - #[inline] - #[must_use = "method returns a new vector and does not mutate the original value"] - pub fn to_bitmask_vector(self) -> Simd { - let mut bitmask = Simd::splat(0); - - // Safety: Bytes is the right size array - unsafe { - // Compute the bitmask - let mut bytes: as SupportedLaneCount>::BitMask = - core::intrinsics::simd::simd_bitmask(self.0); - - // LLVM assumes bit order should match endianness - if cfg!(target_endian = "big") { - for x in bytes.as_mut() { - *x = x.reverse_bits() - } - if N % 8 > 0 { - bytes.as_mut()[N / 8] >>= 8 - N % 8; - } - } - - bitmask.as_mut_array()[..bytes.as_ref().len()].copy_from_slice(bytes.as_ref()); - } - - bitmask - } - - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - pub fn from_bitmask_vector(bitmask: Simd) -> Self { - let mut bytes = as SupportedLaneCount>::BitMask::default(); - - // Safety: Bytes is the right size array - unsafe { - let len = bytes.as_ref().len(); - bytes.as_mut().copy_from_slice(&bitmask.as_array()[..len]); - - // LLVM assumes bit order should match endianness - if cfg!(target_endian = "big") { - for x in bytes.as_mut() { - *x = x.reverse_bits(); - } - if N % 8 > 0 { - bytes.as_mut()[N / 8] >>= 8 - N % 8; - } - } - - // Compute the regular mask - Self::from_int_unchecked(core::intrinsics::simd::simd_select_bitmask( - bytes, - Self::splat(true).to_int(), - Self::splat(false).to_int(), - )) - } - } - - #[inline] - unsafe fn to_bitmask_impl(self) -> U - where - LaneCount: SupportedLaneCount, - { - let resized = self.to_int().resize::(T::FALSE); - - // Safety: `resized` is an integer vector with length M, which must match T - let bitmask: U = unsafe { core::intrinsics::simd::simd_bitmask(resized) }; - - // LLVM assumes bit order should match endianness - if cfg!(target_endian = "big") { - bitmask.reverse_bits(M) - } else { - bitmask - } - } - - #[inline] - unsafe fn from_bitmask_impl(bitmask: U) -> Self - where - LaneCount: SupportedLaneCount, - { - // LLVM assumes bit order should match endianness - let bitmask = if cfg!(target_endian = "big") { - bitmask.reverse_bits(M) - } else { - bitmask - }; - - // SAFETY: `mask` is the correct bitmask type for a u64 bitmask - let mask: Simd = unsafe { - core::intrinsics::simd::simd_select_bitmask( - bitmask, - Simd::::splat(T::TRUE), - Simd::::splat(T::FALSE), - ) - }; - - // SAFETY: `mask` only contains `T::TRUE` or `T::FALSE` - unsafe { Self::from_int_unchecked(mask.resize::(T::FALSE)) } - } - - #[inline] - pub(crate) fn to_bitmask_integer(self) -> u64 { - // TODO modify simd_bitmask to zero-extend output, making this unnecessary - if N <= 8 { - // Safety: bitmask matches length - unsafe { self.to_bitmask_impl::() as u64 } - } else if N <= 16 { - // Safety: bitmask matches length - unsafe { self.to_bitmask_impl::() as u64 } - } else if N <= 32 { - // Safety: bitmask matches length - unsafe { self.to_bitmask_impl::() as u64 } - } else { - // Safety: bitmask matches length - unsafe { self.to_bitmask_impl::() } - } - } - - #[inline] - pub(crate) fn from_bitmask_integer(bitmask: u64) -> Self { - // TODO modify simd_bitmask_select to truncate input, making this unnecessary - if N <= 8 { - // Safety: bitmask matches length - unsafe { Self::from_bitmask_impl::(bitmask as u8) } - } else if N <= 16 { - // Safety: bitmask matches length - unsafe { Self::from_bitmask_impl::(bitmask as u16) } - } else if N <= 32 { - // Safety: bitmask matches length - unsafe { Self::from_bitmask_impl::(bitmask as u32) } - } else { - // Safety: bitmask matches length - unsafe { Self::from_bitmask_impl::(bitmask) } - } - } - - #[inline] - #[must_use = "method returns a new bool and does not mutate the original value"] - pub fn any(self) -> bool { - // Safety: use `self` as an integer vector - unsafe { core::intrinsics::simd::simd_reduce_any(self.to_int()) } - } - - #[inline] - #[must_use = "method returns a new vector and does not mutate the original value"] - pub fn all(self) -> bool { - // Safety: use `self` as an integer vector - unsafe { core::intrinsics::simd::simd_reduce_all(self.to_int()) } - } -} - -impl From> for Simd -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - #[inline] - fn from(value: Mask) -> Self { - value.0 - } -} - -impl core::ops::BitAnd for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - type Output = Self; - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - fn bitand(self, rhs: Self) -> Self { - // Safety: `self` is an integer vector - unsafe { Self(core::intrinsics::simd::simd_and(self.0, rhs.0)) } - } -} - -impl core::ops::BitOr for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - type Output = Self; - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - fn bitor(self, rhs: Self) -> Self { - // Safety: `self` is an integer vector - unsafe { Self(core::intrinsics::simd::simd_or(self.0, rhs.0)) } - } -} - -impl core::ops::BitXor for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - type Output = Self; - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - fn bitxor(self, rhs: Self) -> Self { - // Safety: `self` is an integer vector - unsafe { Self(core::intrinsics::simd::simd_xor(self.0, rhs.0)) } - } -} - -impl core::ops::Not for Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - type Output = Self; - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - fn not(self) -> Self::Output { - Self::splat(true) ^ self - } -} diff --git a/library/portable-simd/crates/core_simd/src/mod.rs b/library/portable-simd/crates/core_simd/src/mod.rs deleted file mode 100644 index 45b1a0f975141..0000000000000 --- a/library/portable-simd/crates/core_simd/src/mod.rs +++ /dev/null @@ -1,35 +0,0 @@ -#[macro_use] -mod swizzle; - -mod alias; -mod cast; -mod fmt; -mod iter; -mod lane_count; -mod masks; -mod ops; -mod select; -mod swizzle_dyn; -mod to_bytes; -mod vector; -mod vendor; - -pub mod simd { - #![doc = include_str!("core_simd_docs.md")] - - pub mod prelude; - - pub mod num; - - pub mod ptr; - - pub mod cmp; - - pub use crate::core_simd::alias::*; - pub use crate::core_simd::cast::*; - pub use crate::core_simd::lane_count::{LaneCount, SupportedLaneCount}; - pub use crate::core_simd::masks::*; - pub use crate::core_simd::swizzle::*; - pub use crate::core_simd::to_bytes::ToBytes; - pub use crate::core_simd::vector::*; -} diff --git a/library/portable-simd/crates/core_simd/src/ops.rs b/library/portable-simd/crates/core_simd/src/ops.rs deleted file mode 100644 index dd7303a97b197..0000000000000 --- a/library/portable-simd/crates/core_simd/src/ops.rs +++ /dev/null @@ -1,261 +0,0 @@ -use crate::simd::{cmp::SimdPartialEq, LaneCount, Simd, SimdElement, SupportedLaneCount}; -use core::ops::{Add, Mul}; -use core::ops::{BitAnd, BitOr, BitXor}; -use core::ops::{Div, Rem, Sub}; -use core::ops::{Shl, Shr}; - -mod assign; -mod deref; -mod shift_scalar; -mod unary; - -impl core::ops::Index for Simd -where - T: SimdElement, - LaneCount: SupportedLaneCount, - I: core::slice::SliceIndex<[T]>, -{ - type Output = I::Output; - #[inline] - fn index(&self, index: I) -> &Self::Output { - &self.as_array()[index] - } -} - -impl core::ops::IndexMut for Simd -where - T: SimdElement, - LaneCount: SupportedLaneCount, - I: core::slice::SliceIndex<[T]>, -{ - #[inline] - fn index_mut(&mut self, index: I) -> &mut Self::Output { - &mut self.as_mut_array()[index] - } -} - -macro_rules! unsafe_base { - ($lhs:ident, $rhs:ident, {$simd_call:ident}, $($_:tt)*) => { - // Safety: $lhs and $rhs are vectors - unsafe { core::intrinsics::simd::$simd_call($lhs, $rhs) } - }; -} - -/// SAFETY: This macro should not be used for anything except Shl or Shr, and passed the appropriate shift intrinsic. -/// It handles performing a bitand in addition to calling the shift operator, so that the result -/// is well-defined: LLVM can return a poison value if you shl, lshr, or ashr if `rhs >= ::BITS` -/// At worst, this will maybe add another instruction and cycle, -/// at best, it may open up more optimization opportunities, -/// or simply be elided entirely, especially for SIMD ISAs which default to this. -/// -// FIXME: Consider implementing this in cg_llvm instead? -// cg_clif defaults to this, and scalar MIR shifts also default to wrapping -macro_rules! wrap_bitshift { - ($lhs:ident, $rhs:ident, {$simd_call:ident}, $int:ident) => { - #[allow(clippy::suspicious_arithmetic_impl)] - // Safety: $lhs and the bitand result are vectors - unsafe { - core::intrinsics::simd::$simd_call( - $lhs, - $rhs.bitand(Simd::splat(<$int>::BITS as $int - 1)), - ) - } - }; -} - -/// SAFETY: This macro must only be used to impl Div or Rem and given the matching intrinsic. -/// It guards against LLVM's UB conditions for integer div or rem using masks and selects, -/// thus guaranteeing a Rust value returns instead. -/// -/// | | LLVM | Rust -/// | :--------------: | :--- | :---------- -/// | N {/,%} 0 | UB | panic!() -/// | <$int>::MIN / -1 | UB | <$int>::MIN -/// | <$int>::MIN % -1 | UB | 0 -/// -macro_rules! int_divrem_guard { - ( $lhs:ident, - $rhs:ident, - { const PANIC_ZERO: &'static str = $zero:literal; - $simd_call:ident - }, - $int:ident ) => { - if $rhs.simd_eq(Simd::splat(0 as _)).any() { - panic!($zero); - } else { - // Prevent otherwise-UB overflow on the MIN / -1 case. - let rhs = if <$int>::MIN != 0 { - // This should, at worst, optimize to a few branchless logical ops - // Ideally, this entire conditional should evaporate - // Fire LLVM and implement those manually if it doesn't get the hint - ($lhs.simd_eq(Simd::splat(<$int>::MIN)) - // type inference can break here, so cut an SInt to size - & $rhs.simd_eq(Simd::splat(-1i64 as _))) - .select(Simd::splat(1 as _), $rhs) - } else { - // Nice base case to make it easy to const-fold away the other branch. - $rhs - }; - // Safety: $lhs and rhs are vectors - unsafe { core::intrinsics::simd::$simd_call($lhs, rhs) } - } - }; -} - -macro_rules! for_base_types { - ( T = ($($scalar:ident),*); - type Lhs = Simd; - type Rhs = Simd; - type Output = $out:ty; - - impl $op:ident::$call:ident { - $macro_impl:ident $inner:tt - }) => { - $( - impl $op for Simd<$scalar, N> - where - $scalar: SimdElement, - LaneCount: SupportedLaneCount, - { - type Output = $out; - - #[inline] - #[must_use = "operator returns a new vector without mutating the inputs"] - // TODO: only useful for int Div::div, but we hope that this - // will essentially always get inlined anyway. - #[track_caller] - fn $call(self, rhs: Self) -> Self::Output { - $macro_impl!(self, rhs, $inner, $scalar) - } - } - )* - } -} - -// A "TokenTree muncher": takes a set of scalar types `T = {};` -// type parameters for the ops it implements, `Op::fn` names, -// and a macro that expands into an expr, substituting in an intrinsic. -// It passes that to for_base_types, which expands an impl for the types, -// using the expanded expr in the function, and recurses with itself. -// -// tl;dr impls a set of ops::{Traits} for a set of types -macro_rules! for_base_ops { - ( - T = $types:tt; - type Lhs = Simd; - type Rhs = Simd; - type Output = $out:ident; - impl $op:ident::$call:ident - $inner:tt - $($rest:tt)* - ) => { - for_base_types! { - T = $types; - type Lhs = Simd; - type Rhs = Simd; - type Output = $out; - impl $op::$call - $inner - } - for_base_ops! { - T = $types; - type Lhs = Simd; - type Rhs = Simd; - type Output = $out; - $($rest)* - } - }; - ($($done:tt)*) => { - // Done. - } -} - -// Integers can always accept add, mul, sub, bitand, bitor, and bitxor. -// For all of these operations, simd_* intrinsics apply wrapping logic. -for_base_ops! { - T = (i8, i16, i32, i64, isize, u8, u16, u32, u64, usize); - type Lhs = Simd; - type Rhs = Simd; - type Output = Self; - - impl Add::add { - unsafe_base { simd_add } - } - - impl Mul::mul { - unsafe_base { simd_mul } - } - - impl Sub::sub { - unsafe_base { simd_sub } - } - - impl BitAnd::bitand { - unsafe_base { simd_and } - } - - impl BitOr::bitor { - unsafe_base { simd_or } - } - - impl BitXor::bitxor { - unsafe_base { simd_xor } - } - - impl Div::div { - int_divrem_guard { - const PANIC_ZERO: &'static str = "attempt to divide by zero"; - simd_div - } - } - - impl Rem::rem { - int_divrem_guard { - const PANIC_ZERO: &'static str = "attempt to calculate the remainder with a divisor of zero"; - simd_rem - } - } - - // The only question is how to handle shifts >= ::BITS? - // Our current solution uses wrapping logic. - impl Shl::shl { - wrap_bitshift { simd_shl } - } - - impl Shr::shr { - wrap_bitshift { - // This automatically monomorphizes to lshr or ashr, depending, - // so it's fine to use it for both UInts and SInts. - simd_shr - } - } -} - -// We don't need any special precautions here: -// Floats always accept arithmetic ops, but may become NaN. -for_base_ops! { - T = (f32, f64); - type Lhs = Simd; - type Rhs = Simd; - type Output = Self; - - impl Add::add { - unsafe_base { simd_add } - } - - impl Mul::mul { - unsafe_base { simd_mul } - } - - impl Sub::sub { - unsafe_base { simd_sub } - } - - impl Div::div { - unsafe_base { simd_div } - } - - impl Rem::rem { - unsafe_base { simd_rem } - } -} diff --git a/library/portable-simd/crates/core_simd/src/ops/assign.rs b/library/portable-simd/crates/core_simd/src/ops/assign.rs deleted file mode 100644 index 0e87785025a38..0000000000000 --- a/library/portable-simd/crates/core_simd/src/ops/assign.rs +++ /dev/null @@ -1,124 +0,0 @@ -//! Assignment operators -use super::*; -use core::ops::{AddAssign, MulAssign}; // commutative binary op-assignment -use core::ops::{BitAndAssign, BitOrAssign, BitXorAssign}; // commutative bit binary op-assignment -use core::ops::{DivAssign, RemAssign, SubAssign}; // non-commutative binary op-assignment -use core::ops::{ShlAssign, ShrAssign}; // non-commutative bit binary op-assignment - -// Arithmetic - -macro_rules! assign_ops { - ($(impl $assignTrait:ident for Simd - where - Self: $trait:ident, - { - fn $assign_call:ident(rhs: U) { - $call:ident - } - })*) => { - $(impl $assignTrait for Simd - where - Self: $trait, - T: SimdElement, - LaneCount: SupportedLaneCount, - { - #[inline] - fn $assign_call(&mut self, rhs: U) { - *self = self.$call(rhs); - } - })* - } -} - -assign_ops! { - // Arithmetic - impl AddAssign for Simd - where - Self: Add, - { - fn add_assign(rhs: U) { - add - } - } - - impl MulAssign for Simd - where - Self: Mul, - { - fn mul_assign(rhs: U) { - mul - } - } - - impl SubAssign for Simd - where - Self: Sub, - { - fn sub_assign(rhs: U) { - sub - } - } - - impl DivAssign for Simd - where - Self: Div, - { - fn div_assign(rhs: U) { - div - } - } - impl RemAssign for Simd - where - Self: Rem, - { - fn rem_assign(rhs: U) { - rem - } - } - - // Bitops - impl BitAndAssign for Simd - where - Self: BitAnd, - { - fn bitand_assign(rhs: U) { - bitand - } - } - - impl BitOrAssign for Simd - where - Self: BitOr, - { - fn bitor_assign(rhs: U) { - bitor - } - } - - impl BitXorAssign for Simd - where - Self: BitXor, - { - fn bitxor_assign(rhs: U) { - bitxor - } - } - - impl ShlAssign for Simd - where - Self: Shl, - { - fn shl_assign(rhs: U) { - shl - } - } - - impl ShrAssign for Simd - where - Self: Shr, - { - fn shr_assign(rhs: U) { - shr - } - } -} diff --git a/library/portable-simd/crates/core_simd/src/ops/deref.rs b/library/portable-simd/crates/core_simd/src/ops/deref.rs deleted file mode 100644 index 89a60ba114146..0000000000000 --- a/library/portable-simd/crates/core_simd/src/ops/deref.rs +++ /dev/null @@ -1,124 +0,0 @@ -//! This module hacks in "implicit deref" for Simd's operators. -//! Ideally, Rust would take care of this itself, -//! and method calls usually handle the LHS implicitly. -//! But this is not the case with arithmetic ops. -use super::*; - -macro_rules! deref_lhs { - (impl $trait:ident for $simd:ty { - fn $call:ident - }) => { - impl $trait<$simd> for &$simd - where - T: SimdElement, - $simd: $trait<$simd, Output = $simd>, - LaneCount: SupportedLaneCount, - { - type Output = Simd; - - #[inline] - #[must_use = "operator returns a new vector without mutating the inputs"] - fn $call(self, rhs: $simd) -> Self::Output { - (*self).$call(rhs) - } - } - }; -} - -macro_rules! deref_rhs { - (impl $trait:ident for $simd:ty { - fn $call:ident - }) => { - impl $trait<&$simd> for $simd - where - T: SimdElement, - $simd: $trait<$simd, Output = $simd>, - LaneCount: SupportedLaneCount, - { - type Output = Simd; - - #[inline] - #[must_use = "operator returns a new vector without mutating the inputs"] - fn $call(self, rhs: &$simd) -> Self::Output { - self.$call(*rhs) - } - } - }; -} - -macro_rules! deref_ops { - ($(impl $trait:ident for $simd:ty { - fn $call:ident - })*) => { - $( - deref_rhs! { - impl $trait for $simd { - fn $call - } - } - deref_lhs! { - impl $trait for $simd { - fn $call - } - } - impl<'lhs, 'rhs, T, const N: usize> $trait<&'rhs $simd> for &'lhs $simd - where - T: SimdElement, - $simd: $trait<$simd, Output = $simd>, - LaneCount: SupportedLaneCount, - { - type Output = $simd; - - #[inline] - #[must_use = "operator returns a new vector without mutating the inputs"] - fn $call(self, rhs: &'rhs $simd) -> Self::Output { - (*self).$call(*rhs) - } - } - )* - } -} - -deref_ops! { - // Arithmetic - impl Add for Simd { - fn add - } - - impl Mul for Simd { - fn mul - } - - impl Sub for Simd { - fn sub - } - - impl Div for Simd { - fn div - } - - impl Rem for Simd { - fn rem - } - - // Bitops - impl BitAnd for Simd { - fn bitand - } - - impl BitOr for Simd { - fn bitor - } - - impl BitXor for Simd { - fn bitxor - } - - impl Shl for Simd { - fn shl - } - - impl Shr for Simd { - fn shr - } -} diff --git a/library/portable-simd/crates/core_simd/src/ops/shift_scalar.rs b/library/portable-simd/crates/core_simd/src/ops/shift_scalar.rs deleted file mode 100644 index f5115a5a5e935..0000000000000 --- a/library/portable-simd/crates/core_simd/src/ops/shift_scalar.rs +++ /dev/null @@ -1,62 +0,0 @@ -// Shift operations uniquely typically only have a scalar on the right-hand side. -// Here, we implement shifts for scalar RHS arguments. - -use crate::simd::{LaneCount, Simd, SupportedLaneCount}; - -macro_rules! impl_splatted_shifts { - { impl $trait:ident :: $trait_fn:ident for $ty:ty } => { - impl core::ops::$trait<$ty> for Simd<$ty, N> - where - LaneCount: SupportedLaneCount, - { - type Output = Self; - #[inline] - fn $trait_fn(self, rhs: $ty) -> Self::Output { - self.$trait_fn(Simd::splat(rhs)) - } - } - - impl core::ops::$trait<&$ty> for Simd<$ty, N> - where - LaneCount: SupportedLaneCount, - { - type Output = Self; - #[inline] - fn $trait_fn(self, rhs: &$ty) -> Self::Output { - self.$trait_fn(Simd::splat(*rhs)) - } - } - - impl<'lhs, const N: usize> core::ops::$trait<$ty> for &'lhs Simd<$ty, N> - where - LaneCount: SupportedLaneCount, - { - type Output = Simd<$ty, N>; - #[inline] - fn $trait_fn(self, rhs: $ty) -> Self::Output { - self.$trait_fn(Simd::splat(rhs)) - } - } - - impl<'lhs, const N: usize> core::ops::$trait<&$ty> for &'lhs Simd<$ty, N> - where - LaneCount: SupportedLaneCount, - { - type Output = Simd<$ty, N>; - #[inline] - fn $trait_fn(self, rhs: &$ty) -> Self::Output { - self.$trait_fn(Simd::splat(*rhs)) - } - } - }; - { $($ty:ty),* } => { - $( - impl_splatted_shifts! { impl Shl::shl for $ty } - impl_splatted_shifts! { impl Shr::shr for $ty } - )* - } -} - -// In the past there were inference issues when generically splatting arguments. -// Enumerate them instead. -impl_splatted_shifts! { i8, i16, i32, i64, isize, u8, u16, u32, u64, usize } diff --git a/library/portable-simd/crates/core_simd/src/ops/unary.rs b/library/portable-simd/crates/core_simd/src/ops/unary.rs deleted file mode 100644 index bdae96332a3ae..0000000000000 --- a/library/portable-simd/crates/core_simd/src/ops/unary.rs +++ /dev/null @@ -1,77 +0,0 @@ -use crate::simd::{LaneCount, Simd, SimdElement, SupportedLaneCount}; -use core::ops::{Neg, Not}; // unary ops - -macro_rules! neg { - ($(impl Neg for Simd<$scalar:ty, N>)*) => { - $(impl Neg for Simd<$scalar, N> - where - $scalar: SimdElement, - LaneCount: SupportedLaneCount, - { - type Output = Self; - - #[inline] - #[must_use = "operator returns a new vector without mutating the input"] - fn neg(self) -> Self::Output { - // Safety: `self` is a signed vector - unsafe { core::intrinsics::simd::simd_neg(self) } - } - })* - } -} - -neg! { - impl Neg for Simd - - impl Neg for Simd - - impl Neg for Simd - - impl Neg for Simd - - impl Neg for Simd - - impl Neg for Simd - - impl Neg for Simd -} - -macro_rules! not { - ($(impl Not for Simd<$scalar:ty, N>)*) => { - $(impl Not for Simd<$scalar, N> - where - $scalar: SimdElement, - LaneCount: SupportedLaneCount, - { - type Output = Self; - - #[inline] - #[must_use = "operator returns a new vector without mutating the input"] - fn not(self) -> Self::Output { - self ^ (Simd::splat(!(0 as $scalar))) - } - })* - } -} - -not! { - impl Not for Simd - - impl Not for Simd - - impl Not for Simd - - impl Not for Simd - - impl Not for Simd - - impl Not for Simd - - impl Not for Simd - - impl Not for Simd - - impl Not for Simd - - impl Not for Simd -} diff --git a/library/portable-simd/crates/core_simd/src/select.rs b/library/portable-simd/crates/core_simd/src/select.rs deleted file mode 100644 index f33aa261a928f..0000000000000 --- a/library/portable-simd/crates/core_simd/src/select.rs +++ /dev/null @@ -1,54 +0,0 @@ -use crate::simd::{LaneCount, Mask, MaskElement, Simd, SimdElement, SupportedLaneCount}; - -impl Mask -where - T: MaskElement, - LaneCount: SupportedLaneCount, -{ - /// Choose elements from two vectors. - /// - /// For each element in the mask, choose the corresponding element from `true_values` if - /// that element mask is true, and `false_values` if that element mask is false. - /// - /// # Examples - /// ``` - /// # #![feature(portable_simd)] - /// # use core::simd::{Simd, Mask}; - /// let a = Simd::from_array([0, 1, 2, 3]); - /// let b = Simd::from_array([4, 5, 6, 7]); - /// let mask = Mask::from_array([true, false, false, true]); - /// let c = mask.select(a, b); - /// assert_eq!(c.to_array(), [0, 5, 6, 3]); - /// ``` - #[inline] - #[must_use = "method returns a new vector and does not mutate the original inputs"] - pub fn select(self, true_values: Simd, false_values: Simd) -> Simd - where - U: SimdElement, - { - // Safety: The mask has been cast to a vector of integers, - // and the operands to select between are vectors of the same type and length. - unsafe { core::intrinsics::simd::simd_select(self.to_int(), true_values, false_values) } - } - - /// Choose elements from two masks. - /// - /// For each element in the mask, choose the corresponding element from `true_values` if - /// that element mask is true, and `false_values` if that element mask is false. - /// - /// # Examples - /// ``` - /// # #![feature(portable_simd)] - /// # use core::simd::Mask; - /// let a = Mask::::from_array([true, true, false, false]); - /// let b = Mask::::from_array([false, false, true, true]); - /// let mask = Mask::::from_array([true, false, false, true]); - /// let c = mask.select_mask(a, b); - /// assert_eq!(c.to_array(), [true, false, true, false]); - /// ``` - #[inline] - #[must_use = "method returns a new mask and does not mutate the original inputs"] - pub fn select_mask(self, true_values: Self, false_values: Self) -> Self { - self & true_values | !self & false_values - } -} diff --git a/library/portable-simd/crates/core_simd/src/simd/cmp.rs b/library/portable-simd/crates/core_simd/src/simd/cmp.rs deleted file mode 100644 index a8d81dbf20f16..0000000000000 --- a/library/portable-simd/crates/core_simd/src/simd/cmp.rs +++ /dev/null @@ -1,7 +0,0 @@ -//! Traits for comparing and ordering vectors. - -mod eq; -mod ord; - -pub use eq::*; -pub use ord::*; diff --git a/library/portable-simd/crates/core_simd/src/simd/cmp/eq.rs b/library/portable-simd/crates/core_simd/src/simd/cmp/eq.rs deleted file mode 100644 index 5b4615ce51d79..0000000000000 --- a/library/portable-simd/crates/core_simd/src/simd/cmp/eq.rs +++ /dev/null @@ -1,110 +0,0 @@ -use crate::simd::{ - ptr::{SimdConstPtr, SimdMutPtr}, - LaneCount, Mask, Simd, SimdElement, SupportedLaneCount, -}; - -/// Parallel `PartialEq`. -pub trait SimdPartialEq { - /// The mask type returned by each comparison. - type Mask; - - /// Test if each element is equal to the corresponding element in `other`. - #[must_use = "method returns a new mask and does not mutate the original value"] - fn simd_eq(self, other: Self) -> Self::Mask; - - /// Test if each element is equal to the corresponding element in `other`. - #[must_use = "method returns a new mask and does not mutate the original value"] - fn simd_ne(self, other: Self) -> Self::Mask; -} - -macro_rules! impl_number { - { $($number:ty),* } => { - $( - impl SimdPartialEq for Simd<$number, N> - where - LaneCount: SupportedLaneCount, - { - type Mask = Mask<<$number as SimdElement>::Mask, N>; - - #[inline] - fn simd_eq(self, other: Self) -> Self::Mask { - // Safety: `self` is a vector, and the result of the comparison - // is always a valid mask. - unsafe { Mask::from_int_unchecked(core::intrinsics::simd::simd_eq(self, other)) } - } - - #[inline] - fn simd_ne(self, other: Self) -> Self::Mask { - // Safety: `self` is a vector, and the result of the comparison - // is always a valid mask. - unsafe { Mask::from_int_unchecked(core::intrinsics::simd::simd_ne(self, other)) } - } - } - )* - } -} - -impl_number! { f32, f64, u8, u16, u32, u64, usize, i8, i16, i32, i64, isize } - -macro_rules! impl_mask { - { $($integer:ty),* } => { - $( - impl SimdPartialEq for Mask<$integer, N> - where - LaneCount: SupportedLaneCount, - { - type Mask = Self; - - #[inline] - fn simd_eq(self, other: Self) -> Self::Mask { - // Safety: `self` is a vector, and the result of the comparison - // is always a valid mask. - unsafe { Self::from_int_unchecked(core::intrinsics::simd::simd_eq(self.to_int(), other.to_int())) } - } - - #[inline] - fn simd_ne(self, other: Self) -> Self::Mask { - // Safety: `self` is a vector, and the result of the comparison - // is always a valid mask. - unsafe { Self::from_int_unchecked(core::intrinsics::simd::simd_ne(self.to_int(), other.to_int())) } - } - } - )* - } -} - -impl_mask! { i8, i16, i32, i64, isize } - -impl SimdPartialEq for Simd<*const T, N> -where - LaneCount: SupportedLaneCount, -{ - type Mask = Mask; - - #[inline] - fn simd_eq(self, other: Self) -> Self::Mask { - self.addr().simd_eq(other.addr()) - } - - #[inline] - fn simd_ne(self, other: Self) -> Self::Mask { - self.addr().simd_ne(other.addr()) - } -} - -impl SimdPartialEq for Simd<*mut T, N> -where - LaneCount: SupportedLaneCount, -{ - type Mask = Mask; - - #[inline] - fn simd_eq(self, other: Self) -> Self::Mask { - self.addr().simd_eq(other.addr()) - } - - #[inline] - fn simd_ne(self, other: Self) -> Self::Mask { - self.addr().simd_ne(other.addr()) - } -} diff --git a/library/portable-simd/crates/core_simd/src/simd/cmp/ord.rs b/library/portable-simd/crates/core_simd/src/simd/cmp/ord.rs deleted file mode 100644 index 899f00a831641..0000000000000 --- a/library/portable-simd/crates/core_simd/src/simd/cmp/ord.rs +++ /dev/null @@ -1,319 +0,0 @@ -use crate::simd::{ - cmp::SimdPartialEq, - ptr::{SimdConstPtr, SimdMutPtr}, - LaneCount, Mask, Simd, SupportedLaneCount, -}; - -/// Parallel `PartialOrd`. -pub trait SimdPartialOrd: SimdPartialEq { - /// Test if each element is less than the corresponding element in `other`. - #[must_use = "method returns a new mask and does not mutate the original value"] - fn simd_lt(self, other: Self) -> Self::Mask; - - /// Test if each element is less than or equal to the corresponding element in `other`. - #[must_use = "method returns a new mask and does not mutate the original value"] - fn simd_le(self, other: Self) -> Self::Mask; - - /// Test if each element is greater than the corresponding element in `other`. - #[must_use = "method returns a new mask and does not mutate the original value"] - fn simd_gt(self, other: Self) -> Self::Mask; - - /// Test if each element is greater than or equal to the corresponding element in `other`. - #[must_use = "method returns a new mask and does not mutate the original value"] - fn simd_ge(self, other: Self) -> Self::Mask; -} - -/// Parallel `Ord`. -pub trait SimdOrd: SimdPartialOrd { - /// Returns the element-wise maximum with `other`. - #[must_use = "method returns a new vector and does not mutate the original value"] - fn simd_max(self, other: Self) -> Self; - - /// Returns the element-wise minimum with `other`. - #[must_use = "method returns a new vector and does not mutate the original value"] - fn simd_min(self, other: Self) -> Self; - - /// Restrict each element to a certain interval. - /// - /// For each element, returns `max` if `self` is greater than `max`, and `min` if `self` is - /// less than `min`. Otherwise returns `self`. - /// - /// # Panics - /// - /// Panics if `min > max` on any element. - #[must_use = "method returns a new vector and does not mutate the original value"] - fn simd_clamp(self, min: Self, max: Self) -> Self; -} - -macro_rules! impl_integer { - { $($integer:ty),* } => { - $( - impl SimdPartialOrd for Simd<$integer, N> - where - LaneCount: SupportedLaneCount, - { - #[inline] - fn simd_lt(self, other: Self) -> Self::Mask { - // Safety: `self` is a vector, and the result of the comparison - // is always a valid mask. - unsafe { Mask::from_int_unchecked(core::intrinsics::simd::simd_lt(self, other)) } - } - - #[inline] - fn simd_le(self, other: Self) -> Self::Mask { - // Safety: `self` is a vector, and the result of the comparison - // is always a valid mask. - unsafe { Mask::from_int_unchecked(core::intrinsics::simd::simd_le(self, other)) } - } - - #[inline] - fn simd_gt(self, other: Self) -> Self::Mask { - // Safety: `self` is a vector, and the result of the comparison - // is always a valid mask. - unsafe { Mask::from_int_unchecked(core::intrinsics::simd::simd_gt(self, other)) } - } - - #[inline] - fn simd_ge(self, other: Self) -> Self::Mask { - // Safety: `self` is a vector, and the result of the comparison - // is always a valid mask. - unsafe { Mask::from_int_unchecked(core::intrinsics::simd::simd_ge(self, other)) } - } - } - - impl SimdOrd for Simd<$integer, N> - where - LaneCount: SupportedLaneCount, - { - #[inline] - fn simd_max(self, other: Self) -> Self { - self.simd_lt(other).select(other, self) - } - - #[inline] - fn simd_min(self, other: Self) -> Self { - self.simd_gt(other).select(other, self) - } - - #[inline] - #[track_caller] - fn simd_clamp(self, min: Self, max: Self) -> Self { - assert!( - min.simd_le(max).all(), - "each element in `min` must be less than or equal to the corresponding element in `max`", - ); - self.simd_max(min).simd_min(max) - } - } - )* - } -} - -impl_integer! { u8, u16, u32, u64, usize, i8, i16, i32, i64, isize } - -macro_rules! impl_float { - { $($float:ty),* } => { - $( - impl SimdPartialOrd for Simd<$float, N> - where - LaneCount: SupportedLaneCount, - { - #[inline] - fn simd_lt(self, other: Self) -> Self::Mask { - // Safety: `self` is a vector, and the result of the comparison - // is always a valid mask. - unsafe { Mask::from_int_unchecked(core::intrinsics::simd::simd_lt(self, other)) } - } - - #[inline] - fn simd_le(self, other: Self) -> Self::Mask { - // Safety: `self` is a vector, and the result of the comparison - // is always a valid mask. - unsafe { Mask::from_int_unchecked(core::intrinsics::simd::simd_le(self, other)) } - } - - #[inline] - fn simd_gt(self, other: Self) -> Self::Mask { - // Safety: `self` is a vector, and the result of the comparison - // is always a valid mask. - unsafe { Mask::from_int_unchecked(core::intrinsics::simd::simd_gt(self, other)) } - } - - #[inline] - fn simd_ge(self, other: Self) -> Self::Mask { - // Safety: `self` is a vector, and the result of the comparison - // is always a valid mask. - unsafe { Mask::from_int_unchecked(core::intrinsics::simd::simd_ge(self, other)) } - } - } - )* - } -} - -impl_float! { f32, f64 } - -macro_rules! impl_mask { - { $($integer:ty),* } => { - $( - impl SimdPartialOrd for Mask<$integer, N> - where - LaneCount: SupportedLaneCount, - { - #[inline] - fn simd_lt(self, other: Self) -> Self::Mask { - // Safety: `self` is a vector, and the result of the comparison - // is always a valid mask. - unsafe { Self::from_int_unchecked(core::intrinsics::simd::simd_lt(self.to_int(), other.to_int())) } - } - - #[inline] - fn simd_le(self, other: Self) -> Self::Mask { - // Safety: `self` is a vector, and the result of the comparison - // is always a valid mask. - unsafe { Self::from_int_unchecked(core::intrinsics::simd::simd_le(self.to_int(), other.to_int())) } - } - - #[inline] - fn simd_gt(self, other: Self) -> Self::Mask { - // Safety: `self` is a vector, and the result of the comparison - // is always a valid mask. - unsafe { Self::from_int_unchecked(core::intrinsics::simd::simd_gt(self.to_int(), other.to_int())) } - } - - #[inline] - fn simd_ge(self, other: Self) -> Self::Mask { - // Safety: `self` is a vector, and the result of the comparison - // is always a valid mask. - unsafe { Self::from_int_unchecked(core::intrinsics::simd::simd_ge(self.to_int(), other.to_int())) } - } - } - - impl SimdOrd for Mask<$integer, N> - where - LaneCount: SupportedLaneCount, - { - #[inline] - fn simd_max(self, other: Self) -> Self { - self.simd_gt(other).select_mask(other, self) - } - - #[inline] - fn simd_min(self, other: Self) -> Self { - self.simd_lt(other).select_mask(other, self) - } - - #[inline] - #[track_caller] - fn simd_clamp(self, min: Self, max: Self) -> Self { - assert!( - min.simd_le(max).all(), - "each element in `min` must be less than or equal to the corresponding element in `max`", - ); - self.simd_max(min).simd_min(max) - } - } - )* - } -} - -impl_mask! { i8, i16, i32, i64, isize } - -impl SimdPartialOrd for Simd<*const T, N> -where - LaneCount: SupportedLaneCount, -{ - #[inline] - fn simd_lt(self, other: Self) -> Self::Mask { - self.addr().simd_lt(other.addr()) - } - - #[inline] - fn simd_le(self, other: Self) -> Self::Mask { - self.addr().simd_le(other.addr()) - } - - #[inline] - fn simd_gt(self, other: Self) -> Self::Mask { - self.addr().simd_gt(other.addr()) - } - - #[inline] - fn simd_ge(self, other: Self) -> Self::Mask { - self.addr().simd_ge(other.addr()) - } -} - -impl SimdOrd for Simd<*const T, N> -where - LaneCount: SupportedLaneCount, -{ - #[inline] - fn simd_max(self, other: Self) -> Self { - self.simd_lt(other).select(other, self) - } - - #[inline] - fn simd_min(self, other: Self) -> Self { - self.simd_gt(other).select(other, self) - } - - #[inline] - #[track_caller] - fn simd_clamp(self, min: Self, max: Self) -> Self { - assert!( - min.simd_le(max).all(), - "each element in `min` must be less than or equal to the corresponding element in `max`", - ); - self.simd_max(min).simd_min(max) - } -} - -impl SimdPartialOrd for Simd<*mut T, N> -where - LaneCount: SupportedLaneCount, -{ - #[inline] - fn simd_lt(self, other: Self) -> Self::Mask { - self.addr().simd_lt(other.addr()) - } - - #[inline] - fn simd_le(self, other: Self) -> Self::Mask { - self.addr().simd_le(other.addr()) - } - - #[inline] - fn simd_gt(self, other: Self) -> Self::Mask { - self.addr().simd_gt(other.addr()) - } - - #[inline] - fn simd_ge(self, other: Self) -> Self::Mask { - self.addr().simd_ge(other.addr()) - } -} - -impl SimdOrd for Simd<*mut T, N> -where - LaneCount: SupportedLaneCount, -{ - #[inline] - fn simd_max(self, other: Self) -> Self { - self.simd_lt(other).select(other, self) - } - - #[inline] - fn simd_min(self, other: Self) -> Self { - self.simd_gt(other).select(other, self) - } - - #[inline] - #[track_caller] - fn simd_clamp(self, min: Self, max: Self) -> Self { - assert!( - min.simd_le(max).all(), - "each element in `min` must be less than or equal to the corresponding element in `max`", - ); - self.simd_max(min).simd_min(max) - } -} diff --git a/library/portable-simd/crates/core_simd/src/simd/num.rs b/library/portable-simd/crates/core_simd/src/simd/num.rs deleted file mode 100644 index 22a4802ec6cb5..0000000000000 --- a/library/portable-simd/crates/core_simd/src/simd/num.rs +++ /dev/null @@ -1,13 +0,0 @@ -//! Traits for vectors with numeric elements. - -mod float; -mod int; -mod uint; - -mod sealed { - pub trait Sealed {} -} - -pub use float::*; -pub use int::*; -pub use uint::*; diff --git a/library/portable-simd/crates/core_simd/src/simd/num/float.rs b/library/portable-simd/crates/core_simd/src/simd/num/float.rs deleted file mode 100644 index 59e43851ea8da..0000000000000 --- a/library/portable-simd/crates/core_simd/src/simd/num/float.rs +++ /dev/null @@ -1,425 +0,0 @@ -use super::sealed::Sealed; -use crate::simd::{ - cmp::{SimdPartialEq, SimdPartialOrd}, - LaneCount, Mask, Simd, SimdCast, SimdElement, SupportedLaneCount, -}; - -/// Operations on SIMD vectors of floats. -pub trait SimdFloat: Copy + Sealed { - /// Mask type used for manipulating this SIMD vector type. - type Mask; - - /// Scalar type contained by this SIMD vector type. - type Scalar; - - /// Bit representation of this SIMD vector type. - type Bits; - - /// A SIMD vector with a different element type. - type Cast; - - /// Performs elementwise conversion of this vector's elements to another SIMD-valid type. - /// - /// This follows the semantics of Rust's `as` conversion for floats (truncating or saturating - /// at the limits) for each element. - /// - /// # Example - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::prelude::*; - /// let floats: Simd = Simd::from_array([1.9, -4.5, f32::INFINITY, f32::NAN]); - /// let ints = floats.cast::(); - /// assert_eq!(ints, Simd::from_array([1, -4, i32::MAX, 0])); - /// - /// // Formally equivalent, but `Simd::cast` can optimize better. - /// assert_eq!(ints, Simd::from_array(floats.to_array().map(|x| x as i32))); - /// - /// // The float conversion does not round-trip. - /// let floats_again = ints.cast(); - /// assert_ne!(floats, floats_again); - /// assert_eq!(floats_again, Simd::from_array([1.0, -4.0, 2147483647.0, 0.0])); - /// ``` - #[must_use] - fn cast(self) -> Self::Cast; - - /// Rounds toward zero and converts to the same-width integer type, assuming that - /// the value is finite and fits in that type. - /// - /// # Safety - /// The value must: - /// - /// * Not be NaN - /// * Not be infinite - /// * Be representable in the return type, after truncating off its fractional part - /// - /// If these requirements are infeasible or costly, consider using the safe function [cast], - /// which saturates on conversion. - /// - /// [cast]: Simd::cast - unsafe fn to_int_unchecked(self) -> Self::Cast - where - Self::Scalar: core::convert::FloatToInt; - - /// Raw transmutation to an unsigned integer vector type with the - /// same size and number of elements. - #[must_use = "method returns a new vector and does not mutate the original value"] - fn to_bits(self) -> Self::Bits; - - /// Raw transmutation from an unsigned integer vector type with the - /// same size and number of elements. - #[must_use = "method returns a new vector and does not mutate the original value"] - fn from_bits(bits: Self::Bits) -> Self; - - /// Produces a vector where every element has the absolute value of the - /// equivalently-indexed element in `self`. - #[must_use = "method returns a new vector and does not mutate the original value"] - fn abs(self) -> Self; - - /// Takes the reciprocal (inverse) of each element, `1/x`. - #[must_use = "method returns a new vector and does not mutate the original value"] - fn recip(self) -> Self; - - /// Converts each element from radians to degrees. - #[must_use = "method returns a new vector and does not mutate the original value"] - fn to_degrees(self) -> Self; - - /// Converts each element from degrees to radians. - #[must_use = "method returns a new vector and does not mutate the original value"] - fn to_radians(self) -> Self; - - /// Returns true for each element if it has a positive sign, including - /// `+0.0`, `NaN`s with positive sign bit and positive infinity. - #[must_use = "method returns a new mask and does not mutate the original value"] - fn is_sign_positive(self) -> Self::Mask; - - /// Returns true for each element if it has a negative sign, including - /// `-0.0`, `NaN`s with negative sign bit and negative infinity. - #[must_use = "method returns a new mask and does not mutate the original value"] - fn is_sign_negative(self) -> Self::Mask; - - /// Returns true for each element if its value is `NaN`. - #[must_use = "method returns a new mask and does not mutate the original value"] - fn is_nan(self) -> Self::Mask; - - /// Returns true for each element if its value is positive infinity or negative infinity. - #[must_use = "method returns a new mask and does not mutate the original value"] - fn is_infinite(self) -> Self::Mask; - - /// Returns true for each element if its value is neither infinite nor `NaN`. - #[must_use = "method returns a new mask and does not mutate the original value"] - fn is_finite(self) -> Self::Mask; - - /// Returns true for each element if its value is subnormal. - #[must_use = "method returns a new mask and does not mutate the original value"] - fn is_subnormal(self) -> Self::Mask; - - /// Returns true for each element if its value is neither zero, infinite, - /// subnormal, nor `NaN`. - #[must_use = "method returns a new mask and does not mutate the original value"] - fn is_normal(self) -> Self::Mask; - - /// Replaces each element with a number that represents its sign. - /// - /// * `1.0` if the number is positive, `+0.0`, or `INFINITY` - /// * `-1.0` if the number is negative, `-0.0`, or `NEG_INFINITY` - /// * `NAN` if the number is `NAN` - #[must_use = "method returns a new vector and does not mutate the original value"] - fn signum(self) -> Self; - - /// Returns each element with the magnitude of `self` and the sign of `sign`. - /// - /// For any element containing a `NAN`, a `NAN` with the sign of `sign` is returned. - #[must_use = "method returns a new vector and does not mutate the original value"] - fn copysign(self, sign: Self) -> Self; - - /// Returns the minimum of each element. - /// - /// If one of the values is `NAN`, then the other value is returned. - #[must_use = "method returns a new vector and does not mutate the original value"] - fn simd_min(self, other: Self) -> Self; - - /// Returns the maximum of each element. - /// - /// If one of the values is `NAN`, then the other value is returned. - #[must_use = "method returns a new vector and does not mutate the original value"] - fn simd_max(self, other: Self) -> Self; - - /// Restrict each element to a certain interval unless it is NaN. - /// - /// For each element in `self`, returns the corresponding element in `max` if the element is - /// greater than `max`, and the corresponding element in `min` if the element is less - /// than `min`. Otherwise returns the element in `self`. - #[must_use = "method returns a new vector and does not mutate the original value"] - fn simd_clamp(self, min: Self, max: Self) -> Self; - - /// Returns the sum of the elements of the vector. - /// - /// # Examples - /// - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::prelude::*; - /// let v = f32x2::from_array([1., 2.]); - /// assert_eq!(v.reduce_sum(), 3.); - /// ``` - fn reduce_sum(self) -> Self::Scalar; - - /// Reducing multiply. Returns the product of the elements of the vector. - /// - /// # Examples - /// - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::prelude::*; - /// let v = f32x2::from_array([3., 4.]); - /// assert_eq!(v.reduce_product(), 12.); - /// ``` - fn reduce_product(self) -> Self::Scalar; - - /// Returns the maximum element in the vector. - /// - /// Returns values based on equality, so a vector containing both `0.` and `-0.` may - /// return either. - /// - /// This function will not return `NaN` unless all elements are `NaN`. - /// - /// # Examples - /// - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::prelude::*; - /// let v = f32x2::from_array([1., 2.]); - /// assert_eq!(v.reduce_max(), 2.); - /// - /// // NaN values are skipped... - /// let v = f32x2::from_array([1., f32::NAN]); - /// assert_eq!(v.reduce_max(), 1.); - /// - /// // ...unless all values are NaN - /// let v = f32x2::from_array([f32::NAN, f32::NAN]); - /// assert!(v.reduce_max().is_nan()); - /// ``` - fn reduce_max(self) -> Self::Scalar; - - /// Returns the minimum element in the vector. - /// - /// Returns values based on equality, so a vector containing both `0.` and `-0.` may - /// return either. - /// - /// This function will not return `NaN` unless all elements are `NaN`. - /// - /// # Examples - /// - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::prelude::*; - /// let v = f32x2::from_array([3., 7.]); - /// assert_eq!(v.reduce_min(), 3.); - /// - /// // NaN values are skipped... - /// let v = f32x2::from_array([1., f32::NAN]); - /// assert_eq!(v.reduce_min(), 1.); - /// - /// // ...unless all values are NaN - /// let v = f32x2::from_array([f32::NAN, f32::NAN]); - /// assert!(v.reduce_min().is_nan()); - /// ``` - fn reduce_min(self) -> Self::Scalar; -} - -macro_rules! impl_trait { - { $($ty:ty { bits: $bits_ty:ty, mask: $mask_ty:ty }),* } => { - $( - impl Sealed for Simd<$ty, N> - where - LaneCount: SupportedLaneCount, - { - } - - impl SimdFloat for Simd<$ty, N> - where - LaneCount: SupportedLaneCount, - { - type Mask = Mask<<$mask_ty as SimdElement>::Mask, N>; - type Scalar = $ty; - type Bits = Simd<$bits_ty, N>; - type Cast = Simd; - - #[inline] - fn cast(self) -> Self::Cast - { - // Safety: supported types are guaranteed by SimdCast - unsafe { core::intrinsics::simd::simd_as(self) } - } - - #[inline] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - unsafe fn to_int_unchecked(self) -> Self::Cast - where - Self::Scalar: core::convert::FloatToInt, - { - // Safety: supported types are guaranteed by SimdCast, the caller is responsible for the extra invariants - unsafe { core::intrinsics::simd::simd_cast(self) } - } - - #[inline] - fn to_bits(self) -> Simd<$bits_ty, N> { - assert_eq!(core::mem::size_of::(), core::mem::size_of::()); - // Safety: transmuting between vector types is safe - unsafe { core::mem::transmute_copy(&self) } - } - - #[inline] - fn from_bits(bits: Simd<$bits_ty, N>) -> Self { - assert_eq!(core::mem::size_of::(), core::mem::size_of::()); - // Safety: transmuting between vector types is safe - unsafe { core::mem::transmute_copy(&bits) } - } - - #[inline] - fn abs(self) -> Self { - // Safety: `self` is a float vector - unsafe { core::intrinsics::simd::simd_fabs(self) } - } - - #[inline] - fn recip(self) -> Self { - Self::splat(1.0) / self - } - - #[inline] - fn to_degrees(self) -> Self { - // to_degrees uses a special constant for better precision, so extract that constant - self * Self::splat(Self::Scalar::to_degrees(1.)) - } - - #[inline] - fn to_radians(self) -> Self { - self * Self::splat(Self::Scalar::to_radians(1.)) - } - - #[inline] - fn is_sign_positive(self) -> Self::Mask { - !self.is_sign_negative() - } - - #[inline] - fn is_sign_negative(self) -> Self::Mask { - let sign_bits = self.to_bits() & Simd::splat((!0 >> 1) + 1); - sign_bits.simd_gt(Simd::splat(0)) - } - - #[inline] - fn is_nan(self) -> Self::Mask { - self.simd_ne(self) - } - - #[inline] - fn is_infinite(self) -> Self::Mask { - self.abs().simd_eq(Self::splat(Self::Scalar::INFINITY)) - } - - #[inline] - fn is_finite(self) -> Self::Mask { - self.abs().simd_lt(Self::splat(Self::Scalar::INFINITY)) - } - - #[inline] - fn is_subnormal(self) -> Self::Mask { - // On some architectures (e.g. armv7 and some ppc) subnormals are flushed to zero, - // so this comparison must be done with integers. - let not_zero = self.abs().to_bits().simd_ne(Self::splat(0.0).to_bits()); - not_zero & (self.to_bits() & Self::splat(Self::Scalar::INFINITY).to_bits()).simd_eq(Simd::splat(0)) - } - - #[inline] - #[must_use = "method returns a new mask and does not mutate the original value"] - fn is_normal(self) -> Self::Mask { - !(self.abs().simd_eq(Self::splat(0.0)) | self.is_nan() | self.is_subnormal() | self.is_infinite()) - } - - #[inline] - fn signum(self) -> Self { - self.is_nan().select(Self::splat(Self::Scalar::NAN), Self::splat(1.0).copysign(self)) - } - - #[inline] - fn copysign(self, sign: Self) -> Self { - let sign_bit = sign.to_bits() & Self::splat(-0.).to_bits(); - let magnitude = self.to_bits() & !Self::splat(-0.).to_bits(); - Self::from_bits(sign_bit | magnitude) - } - - #[inline] - fn simd_min(self, other: Self) -> Self { - // Safety: `self` and `other` are float vectors - unsafe { core::intrinsics::simd::simd_fmin(self, other) } - } - - #[inline] - fn simd_max(self, other: Self) -> Self { - // Safety: `self` and `other` are floating point vectors - unsafe { core::intrinsics::simd::simd_fmax(self, other) } - } - - #[inline] - fn simd_clamp(self, min: Self, max: Self) -> Self { - assert!( - min.simd_le(max).all(), - "each element in `min` must be less than or equal to the corresponding element in `max`", - ); - let mut x = self; - x = x.simd_lt(min).select(min, x); - x = x.simd_gt(max).select(max, x); - x - } - - #[inline] - fn reduce_sum(self) -> Self::Scalar { - // LLVM sum is inaccurate on i586 - if cfg!(all(target_arch = "x86", not(target_feature = "sse2"))) { - self.as_array().iter().sum() - } else { - // Safety: `self` is a float vector - unsafe { core::intrinsics::simd::simd_reduce_add_ordered(self, 0.) } - } - } - - #[inline] - fn reduce_product(self) -> Self::Scalar { - // LLVM product is inaccurate on i586 - if cfg!(all(target_arch = "x86", not(target_feature = "sse2"))) { - self.as_array().iter().product() - } else { - // Safety: `self` is a float vector - unsafe { core::intrinsics::simd::simd_reduce_mul_ordered(self, 1.) } - } - } - - #[inline] - fn reduce_max(self) -> Self::Scalar { - // Safety: `self` is a float vector - unsafe { core::intrinsics::simd::simd_reduce_max(self) } - } - - #[inline] - fn reduce_min(self) -> Self::Scalar { - // Safety: `self` is a float vector - unsafe { core::intrinsics::simd::simd_reduce_min(self) } - } - } - )* - } -} - -impl_trait! { f32 { bits: u32, mask: i32 }, f64 { bits: u64, mask: i64 } } diff --git a/library/portable-simd/crates/core_simd/src/simd/num/int.rs b/library/portable-simd/crates/core_simd/src/simd/num/int.rs deleted file mode 100644 index d7598d9ceaf92..0000000000000 --- a/library/portable-simd/crates/core_simd/src/simd/num/int.rs +++ /dev/null @@ -1,371 +0,0 @@ -use super::sealed::Sealed; -use crate::simd::{ - cmp::SimdPartialOrd, num::SimdUint, LaneCount, Mask, Simd, SimdCast, SimdElement, - SupportedLaneCount, -}; - -/// Operations on SIMD vectors of signed integers. -pub trait SimdInt: Copy + Sealed { - /// Mask type used for manipulating this SIMD vector type. - type Mask; - - /// Scalar type contained by this SIMD vector type. - type Scalar; - - /// A SIMD vector of unsigned integers with the same element size. - type Unsigned; - - /// A SIMD vector with a different element type. - type Cast; - - /// Performs elementwise conversion of this vector's elements to another SIMD-valid type. - /// - /// This follows the semantics of Rust's `as` conversion for casting integers (wrapping to - /// other integer types, and saturating to float types). - #[must_use] - fn cast(self) -> Self::Cast; - - /// Lanewise saturating add. - /// - /// # Examples - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::prelude::*; - /// use core::i32::{MIN, MAX}; - /// let x = Simd::from_array([MIN, 0, 1, MAX]); - /// let max = Simd::splat(MAX); - /// let unsat = x + max; - /// let sat = x.saturating_add(max); - /// assert_eq!(unsat, Simd::from_array([-1, MAX, MIN, -2])); - /// assert_eq!(sat, Simd::from_array([-1, MAX, MAX, MAX])); - /// ``` - fn saturating_add(self, second: Self) -> Self; - - /// Lanewise saturating subtract. - /// - /// # Examples - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::prelude::*; - /// use core::i32::{MIN, MAX}; - /// let x = Simd::from_array([MIN, -2, -1, MAX]); - /// let max = Simd::splat(MAX); - /// let unsat = x - max; - /// let sat = x.saturating_sub(max); - /// assert_eq!(unsat, Simd::from_array([1, MAX, MIN, 0])); - /// assert_eq!(sat, Simd::from_array([MIN, MIN, MIN, 0])); - fn saturating_sub(self, second: Self) -> Self; - - /// Lanewise absolute value, implemented in Rust. - /// Every element becomes its absolute value. - /// - /// # Examples - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::prelude::*; - /// use core::i32::{MIN, MAX}; - /// let xs = Simd::from_array([MIN, MIN +1, -5, 0]); - /// assert_eq!(xs.abs(), Simd::from_array([MIN, MAX, 5, 0])); - /// ``` - fn abs(self) -> Self; - - /// Lanewise saturating absolute value, implemented in Rust. - /// As abs(), except the MIN value becomes MAX instead of itself. - /// - /// # Examples - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::prelude::*; - /// use core::i32::{MIN, MAX}; - /// let xs = Simd::from_array([MIN, -2, 0, 3]); - /// let unsat = xs.abs(); - /// let sat = xs.saturating_abs(); - /// assert_eq!(unsat, Simd::from_array([MIN, 2, 0, 3])); - /// assert_eq!(sat, Simd::from_array([MAX, 2, 0, 3])); - /// ``` - fn saturating_abs(self) -> Self; - - /// Lanewise saturating negation, implemented in Rust. - /// As neg(), except the MIN value becomes MAX instead of itself. - /// - /// # Examples - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::prelude::*; - /// use core::i32::{MIN, MAX}; - /// let x = Simd::from_array([MIN, -2, 3, MAX]); - /// let unsat = -x; - /// let sat = x.saturating_neg(); - /// assert_eq!(unsat, Simd::from_array([MIN, 2, -3, MIN + 1])); - /// assert_eq!(sat, Simd::from_array([MAX, 2, -3, MIN + 1])); - /// ``` - fn saturating_neg(self) -> Self; - - /// Returns true for each positive element and false if it is zero or negative. - fn is_positive(self) -> Self::Mask; - - /// Returns true for each negative element and false if it is zero or positive. - fn is_negative(self) -> Self::Mask; - - /// Returns numbers representing the sign of each element. - /// * `0` if the number is zero - /// * `1` if the number is positive - /// * `-1` if the number is negative - fn signum(self) -> Self; - - /// Returns the sum of the elements of the vector, with wrapping addition. - /// - /// # Examples - /// - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::prelude::*; - /// let v = i32x4::from_array([1, 2, 3, 4]); - /// assert_eq!(v.reduce_sum(), 10); - /// - /// // SIMD integer addition is always wrapping - /// let v = i32x4::from_array([i32::MAX, 1, 0, 0]); - /// assert_eq!(v.reduce_sum(), i32::MIN); - /// ``` - fn reduce_sum(self) -> Self::Scalar; - - /// Returns the product of the elements of the vector, with wrapping multiplication. - /// - /// # Examples - /// - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::prelude::*; - /// let v = i32x4::from_array([1, 2, 3, 4]); - /// assert_eq!(v.reduce_product(), 24); - /// - /// // SIMD integer multiplication is always wrapping - /// let v = i32x4::from_array([i32::MAX, 2, 1, 1]); - /// assert!(v.reduce_product() < i32::MAX); - /// ``` - fn reduce_product(self) -> Self::Scalar; - - /// Returns the maximum element in the vector. - /// - /// # Examples - /// - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::prelude::*; - /// let v = i32x4::from_array([1, 2, 3, 4]); - /// assert_eq!(v.reduce_max(), 4); - /// ``` - fn reduce_max(self) -> Self::Scalar; - - /// Returns the minimum element in the vector. - /// - /// # Examples - /// - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::prelude::*; - /// let v = i32x4::from_array([1, 2, 3, 4]); - /// assert_eq!(v.reduce_min(), 1); - /// ``` - fn reduce_min(self) -> Self::Scalar; - - /// Returns the cumulative bitwise "and" across the elements of the vector. - fn reduce_and(self) -> Self::Scalar; - - /// Returns the cumulative bitwise "or" across the elements of the vector. - fn reduce_or(self) -> Self::Scalar; - - /// Returns the cumulative bitwise "xor" across the elements of the vector. - fn reduce_xor(self) -> Self::Scalar; - - /// Reverses the byte order of each element. - fn swap_bytes(self) -> Self; - - /// Reverses the order of bits in each elemnent. - /// The least significant bit becomes the most significant bit, second least-significant bit becomes second most-significant bit, etc. - fn reverse_bits(self) -> Self; - - /// Returns the number of leading zeros in the binary representation of each element. - fn leading_zeros(self) -> Self::Unsigned; - - /// Returns the number of trailing zeros in the binary representation of each element. - fn trailing_zeros(self) -> Self::Unsigned; - - /// Returns the number of leading ones in the binary representation of each element. - fn leading_ones(self) -> Self::Unsigned; - - /// Returns the number of trailing ones in the binary representation of each element. - fn trailing_ones(self) -> Self::Unsigned; -} - -macro_rules! impl_trait { - { $($ty:ident ($unsigned:ident)),* } => { - $( - impl Sealed for Simd<$ty, N> - where - LaneCount: SupportedLaneCount, - { - } - - impl SimdInt for Simd<$ty, N> - where - LaneCount: SupportedLaneCount, - { - type Mask = Mask<<$ty as SimdElement>::Mask, N>; - type Scalar = $ty; - type Unsigned = Simd<$unsigned, N>; - type Cast = Simd; - - #[inline] - fn cast(self) -> Self::Cast { - // Safety: supported types are guaranteed by SimdCast - unsafe { core::intrinsics::simd::simd_as(self) } - } - - #[inline] - fn saturating_add(self, second: Self) -> Self { - // Safety: `self` is a vector - unsafe { core::intrinsics::simd::simd_saturating_add(self, second) } - } - - #[inline] - fn saturating_sub(self, second: Self) -> Self { - // Safety: `self` is a vector - unsafe { core::intrinsics::simd::simd_saturating_sub(self, second) } - } - - #[inline] - fn abs(self) -> Self { - const SHR: $ty = <$ty>::BITS as $ty - 1; - let m = self >> Simd::splat(SHR); - (self^m) - m - } - - #[inline] - fn saturating_abs(self) -> Self { - // arith shift for -1 or 0 mask based on sign bit, giving 2s complement - const SHR: $ty = <$ty>::BITS as $ty - 1; - let m = self >> Simd::splat(SHR); - (self^m).saturating_sub(m) - } - - #[inline] - fn saturating_neg(self) -> Self { - Self::splat(0).saturating_sub(self) - } - - #[inline] - fn is_positive(self) -> Self::Mask { - self.simd_gt(Self::splat(0)) - } - - #[inline] - fn is_negative(self) -> Self::Mask { - self.simd_lt(Self::splat(0)) - } - - #[inline] - fn signum(self) -> Self { - self.is_positive().select( - Self::splat(1), - self.is_negative().select(Self::splat(-1), Self::splat(0)) - ) - } - - #[inline] - fn reduce_sum(self) -> Self::Scalar { - // Safety: `self` is an integer vector - unsafe { core::intrinsics::simd::simd_reduce_add_ordered(self, 0) } - } - - #[inline] - fn reduce_product(self) -> Self::Scalar { - // Safety: `self` is an integer vector - unsafe { core::intrinsics::simd::simd_reduce_mul_ordered(self, 1) } - } - - #[inline] - fn reduce_max(self) -> Self::Scalar { - // Safety: `self` is an integer vector - unsafe { core::intrinsics::simd::simd_reduce_max(self) } - } - - #[inline] - fn reduce_min(self) -> Self::Scalar { - // Safety: `self` is an integer vector - unsafe { core::intrinsics::simd::simd_reduce_min(self) } - } - - #[inline] - fn reduce_and(self) -> Self::Scalar { - // Safety: `self` is an integer vector - unsafe { core::intrinsics::simd::simd_reduce_and(self) } - } - - #[inline] - fn reduce_or(self) -> Self::Scalar { - // Safety: `self` is an integer vector - unsafe { core::intrinsics::simd::simd_reduce_or(self) } - } - - #[inline] - fn reduce_xor(self) -> Self::Scalar { - // Safety: `self` is an integer vector - unsafe { core::intrinsics::simd::simd_reduce_xor(self) } - } - - #[inline] - fn swap_bytes(self) -> Self { - // Safety: `self` is an integer vector - unsafe { core::intrinsics::simd::simd_bswap(self) } - } - - #[inline] - fn reverse_bits(self) -> Self { - // Safety: `self` is an integer vector - unsafe { core::intrinsics::simd::simd_bitreverse(self) } - } - - #[inline] - fn leading_zeros(self) -> Self::Unsigned { - self.cast::<$unsigned>().leading_zeros() - } - - #[inline] - fn trailing_zeros(self) -> Self::Unsigned { - self.cast::<$unsigned>().trailing_zeros() - } - - #[inline] - fn leading_ones(self) -> Self::Unsigned { - self.cast::<$unsigned>().leading_ones() - } - - #[inline] - fn trailing_ones(self) -> Self::Unsigned { - self.cast::<$unsigned>().trailing_ones() - } - } - )* - } -} - -impl_trait! { i8 (u8), i16 (u16), i32 (u32), i64 (u64), isize (usize) } diff --git a/library/portable-simd/crates/core_simd/src/simd/num/uint.rs b/library/portable-simd/crates/core_simd/src/simd/num/uint.rs deleted file mode 100644 index 53dd97f501c63..0000000000000 --- a/library/portable-simd/crates/core_simd/src/simd/num/uint.rs +++ /dev/null @@ -1,221 +0,0 @@ -use super::sealed::Sealed; -use crate::simd::{LaneCount, Simd, SimdCast, SimdElement, SupportedLaneCount}; - -/// Operations on SIMD vectors of unsigned integers. -pub trait SimdUint: Copy + Sealed { - /// Scalar type contained by this SIMD vector type. - type Scalar; - - /// A SIMD vector with a different element type. - type Cast; - - /// Performs elementwise conversion of this vector's elements to another SIMD-valid type. - /// - /// This follows the semantics of Rust's `as` conversion for casting integers (wrapping to - /// other integer types, and saturating to float types). - #[must_use] - fn cast(self) -> Self::Cast; - - /// Wrapping negation. - /// - /// Like [`u32::wrapping_neg`], all applications of this function will wrap, with the exception - /// of `-0`. - fn wrapping_neg(self) -> Self; - - /// Lanewise saturating add. - /// - /// # Examples - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::prelude::*; - /// use core::u32::MAX; - /// let x = Simd::from_array([2, 1, 0, MAX]); - /// let max = Simd::splat(MAX); - /// let unsat = x + max; - /// let sat = x.saturating_add(max); - /// assert_eq!(unsat, Simd::from_array([1, 0, MAX, MAX - 1])); - /// assert_eq!(sat, max); - /// ``` - fn saturating_add(self, second: Self) -> Self; - - /// Lanewise saturating subtract. - /// - /// # Examples - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::prelude::*; - /// use core::u32::MAX; - /// let x = Simd::from_array([2, 1, 0, MAX]); - /// let max = Simd::splat(MAX); - /// let unsat = x - max; - /// let sat = x.saturating_sub(max); - /// assert_eq!(unsat, Simd::from_array([3, 2, 1, 0])); - /// assert_eq!(sat, Simd::splat(0)); - fn saturating_sub(self, second: Self) -> Self; - - /// Returns the sum of the elements of the vector, with wrapping addition. - fn reduce_sum(self) -> Self::Scalar; - - /// Returns the product of the elements of the vector, with wrapping multiplication. - fn reduce_product(self) -> Self::Scalar; - - /// Returns the maximum element in the vector. - fn reduce_max(self) -> Self::Scalar; - - /// Returns the minimum element in the vector. - fn reduce_min(self) -> Self::Scalar; - - /// Returns the cumulative bitwise "and" across the elements of the vector. - fn reduce_and(self) -> Self::Scalar; - - /// Returns the cumulative bitwise "or" across the elements of the vector. - fn reduce_or(self) -> Self::Scalar; - - /// Returns the cumulative bitwise "xor" across the elements of the vector. - fn reduce_xor(self) -> Self::Scalar; - - /// Reverses the byte order of each element. - fn swap_bytes(self) -> Self; - - /// Reverses the order of bits in each elemnent. - /// The least significant bit becomes the most significant bit, second least-significant bit becomes second most-significant bit, etc. - fn reverse_bits(self) -> Self; - - /// Returns the number of leading zeros in the binary representation of each element. - fn leading_zeros(self) -> Self; - - /// Returns the number of trailing zeros in the binary representation of each element. - fn trailing_zeros(self) -> Self; - - /// Returns the number of leading ones in the binary representation of each element. - fn leading_ones(self) -> Self; - - /// Returns the number of trailing ones in the binary representation of each element. - fn trailing_ones(self) -> Self; -} - -macro_rules! impl_trait { - { $($ty:ident ($signed:ident)),* } => { - $( - impl Sealed for Simd<$ty, N> - where - LaneCount: SupportedLaneCount, - { - } - - impl SimdUint for Simd<$ty, N> - where - LaneCount: SupportedLaneCount, - { - type Scalar = $ty; - type Cast = Simd; - - #[inline] - fn cast(self) -> Self::Cast { - // Safety: supported types are guaranteed by SimdCast - unsafe { core::intrinsics::simd::simd_as(self) } - } - - #[inline] - fn wrapping_neg(self) -> Self { - use crate::simd::num::SimdInt; - (-self.cast::<$signed>()).cast() - } - - #[inline] - fn saturating_add(self, second: Self) -> Self { - // Safety: `self` is a vector - unsafe { core::intrinsics::simd::simd_saturating_add(self, second) } - } - - #[inline] - fn saturating_sub(self, second: Self) -> Self { - // Safety: `self` is a vector - unsafe { core::intrinsics::simd::simd_saturating_sub(self, second) } - } - - #[inline] - fn reduce_sum(self) -> Self::Scalar { - // Safety: `self` is an integer vector - unsafe { core::intrinsics::simd::simd_reduce_add_ordered(self, 0) } - } - - #[inline] - fn reduce_product(self) -> Self::Scalar { - // Safety: `self` is an integer vector - unsafe { core::intrinsics::simd::simd_reduce_mul_ordered(self, 1) } - } - - #[inline] - fn reduce_max(self) -> Self::Scalar { - // Safety: `self` is an integer vector - unsafe { core::intrinsics::simd::simd_reduce_max(self) } - } - - #[inline] - fn reduce_min(self) -> Self::Scalar { - // Safety: `self` is an integer vector - unsafe { core::intrinsics::simd::simd_reduce_min(self) } - } - - #[inline] - fn reduce_and(self) -> Self::Scalar { - // Safety: `self` is an integer vector - unsafe { core::intrinsics::simd::simd_reduce_and(self) } - } - - #[inline] - fn reduce_or(self) -> Self::Scalar { - // Safety: `self` is an integer vector - unsafe { core::intrinsics::simd::simd_reduce_or(self) } - } - - #[inline] - fn reduce_xor(self) -> Self::Scalar { - // Safety: `self` is an integer vector - unsafe { core::intrinsics::simd::simd_reduce_xor(self) } - } - - #[inline] - fn swap_bytes(self) -> Self { - // Safety: `self` is an integer vector - unsafe { core::intrinsics::simd::simd_bswap(self) } - } - - #[inline] - fn reverse_bits(self) -> Self { - // Safety: `self` is an integer vector - unsafe { core::intrinsics::simd::simd_bitreverse(self) } - } - - #[inline] - fn leading_zeros(self) -> Self { - // Safety: `self` is an integer vector - unsafe { core::intrinsics::simd::simd_ctlz(self) } - } - - #[inline] - fn trailing_zeros(self) -> Self { - // Safety: `self` is an integer vector - unsafe { core::intrinsics::simd::simd_cttz(self) } - } - - #[inline] - fn leading_ones(self) -> Self { - (!self).leading_zeros() - } - - #[inline] - fn trailing_ones(self) -> Self { - (!self).trailing_zeros() - } - } - )* - } -} - -impl_trait! { u8 (i8), u16 (i16), u32 (i32), u64 (i64), usize (isize) } diff --git a/library/portable-simd/crates/core_simd/src/simd/prelude.rs b/library/portable-simd/crates/core_simd/src/simd/prelude.rs deleted file mode 100644 index 4b7c744c01326..0000000000000 --- a/library/portable-simd/crates/core_simd/src/simd/prelude.rs +++ /dev/null @@ -1,82 +0,0 @@ -//! The portable SIMD prelude. -//! -//! Includes important traits and types to be imported with a glob: -//! ```ignore -//! use std::simd::prelude::*; -//! ``` - -#[doc(no_inline)] -pub use super::{ - cmp::{SimdOrd, SimdPartialEq, SimdPartialOrd}, - num::{SimdFloat, SimdInt, SimdUint}, - ptr::{SimdConstPtr, SimdMutPtr}, - simd_swizzle, Mask, Simd, -}; - -#[rustfmt::skip] -#[doc(no_inline)] -pub use super::{f32x1, f32x2, f32x4, f32x8, f32x16, f32x32, f32x64}; - -#[rustfmt::skip] -#[doc(no_inline)] -pub use super::{f64x1, f64x2, f64x4, f64x8, f64x16, f64x32, f64x64}; - -#[rustfmt::skip] -#[doc(no_inline)] -pub use super::{i8x1, i8x2, i8x4, i8x8, i8x16, i8x32, i8x64}; - -#[rustfmt::skip] -#[doc(no_inline)] -pub use super::{i16x1, i16x2, i16x4, i16x8, i16x16, i16x32, i16x64}; - -#[rustfmt::skip] -#[doc(no_inline)] -pub use super::{i32x1, i32x2, i32x4, i32x8, i32x16, i32x32, i32x64}; - -#[rustfmt::skip] -#[doc(no_inline)] -pub use super::{i64x1, i64x2, i64x4, i64x8, i64x16, i64x32, i64x64}; - -#[rustfmt::skip] -#[doc(no_inline)] -pub use super::{isizex1, isizex2, isizex4, isizex8, isizex16, isizex32, isizex64}; - -#[rustfmt::skip] -#[doc(no_inline)] -pub use super::{u8x1, u8x2, u8x4, u8x8, u8x16, u8x32, u8x64}; - -#[rustfmt::skip] -#[doc(no_inline)] -pub use super::{u16x1, u16x2, u16x4, u16x8, u16x16, u16x32, u16x64}; - -#[rustfmt::skip] -#[doc(no_inline)] -pub use super::{u32x1, u32x2, u32x4, u32x8, u32x16, u32x32, u32x64}; - -#[rustfmt::skip] -#[doc(no_inline)] -pub use super::{u64x1, u64x2, u64x4, u64x8, u64x16, u64x32, u64x64}; - -#[rustfmt::skip] -#[doc(no_inline)] -pub use super::{usizex1, usizex2, usizex4, usizex8, usizex16, usizex32, usizex64}; - -#[rustfmt::skip] -#[doc(no_inline)] -pub use super::{mask8x1, mask8x2, mask8x4, mask8x8, mask8x16, mask8x32, mask8x64}; - -#[rustfmt::skip] -#[doc(no_inline)] -pub use super::{mask16x1, mask16x2, mask16x4, mask16x8, mask16x16, mask16x32, mask16x64}; - -#[rustfmt::skip] -#[doc(no_inline)] -pub use super::{mask32x1, mask32x2, mask32x4, mask32x8, mask32x16, mask32x32, mask32x64}; - -#[rustfmt::skip] -#[doc(no_inline)] -pub use super::{mask64x1, mask64x2, mask64x4, mask64x8, mask64x16, mask64x32, mask64x64}; - -#[rustfmt::skip] -#[doc(no_inline)] -pub use super::{masksizex1, masksizex2, masksizex4, masksizex8, masksizex16, masksizex32, masksizex64}; diff --git a/library/portable-simd/crates/core_simd/src/simd/ptr.rs b/library/portable-simd/crates/core_simd/src/simd/ptr.rs deleted file mode 100644 index 3f8e666911853..0000000000000 --- a/library/portable-simd/crates/core_simd/src/simd/ptr.rs +++ /dev/null @@ -1,11 +0,0 @@ -//! Traits for vectors of pointers. - -mod const_ptr; -mod mut_ptr; - -mod sealed { - pub trait Sealed {} -} - -pub use const_ptr::*; -pub use mut_ptr::*; diff --git a/library/portable-simd/crates/core_simd/src/simd/ptr/const_ptr.rs b/library/portable-simd/crates/core_simd/src/simd/ptr/const_ptr.rs deleted file mode 100644 index 0f1719206c9ce..0000000000000 --- a/library/portable-simd/crates/core_simd/src/simd/ptr/const_ptr.rs +++ /dev/null @@ -1,160 +0,0 @@ -use super::sealed::Sealed; -use crate::simd::{cmp::SimdPartialEq, num::SimdUint, LaneCount, Mask, Simd, SupportedLaneCount}; - -/// Operations on SIMD vectors of constant pointers. -pub trait SimdConstPtr: Copy + Sealed { - /// Vector of `usize` with the same number of elements. - type Usize; - - /// Vector of `isize` with the same number of elements. - type Isize; - - /// Vector of const pointers with the same number of elements. - type CastPtr; - - /// Vector of mutable pointers to the same type. - type MutPtr; - - /// Mask type used for manipulating this SIMD vector type. - type Mask; - - /// Returns `true` for each element that is null. - fn is_null(self) -> Self::Mask; - - /// Casts to a pointer of another type. - /// - /// Equivalent to calling [`pointer::cast`] on each element. - fn cast(self) -> Self::CastPtr; - - /// Changes constness without changing the type. - /// - /// Equivalent to calling [`pointer::cast_mut`] on each element. - fn cast_mut(self) -> Self::MutPtr; - - /// Gets the "address" portion of the pointer. - /// - /// This method discards pointer semantic metadata, so the result cannot be - /// directly cast into a valid pointer. - /// - /// This method semantically discards *provenance* and - /// *address-space* information. To properly restore that information, use [`Self::with_addr`]. - /// - /// Equivalent to calling [`pointer::addr`] on each element. - fn addr(self) -> Self::Usize; - - /// Creates a new pointer with the given address. - /// - /// This performs the same operation as a cast, but copies the *address-space* and - /// *provenance* of `self` to the new pointer. - /// - /// Equivalent to calling [`pointer::with_addr`] on each element. - fn with_addr(self, addr: Self::Usize) -> Self; - - /// Exposes the "provenance" part of the pointer for future use in - /// [`Self::with_exposed_provenance`] and returns the "address" portion. - fn expose_provenance(self) -> Self::Usize; - - /// Convert an address back to a pointer, picking up a previously "exposed" provenance. - /// - /// Equivalent to calling [`core::ptr::with_exposed_provenance`] on each element. - fn with_exposed_provenance(addr: Self::Usize) -> Self; - - /// Calculates the offset from a pointer using wrapping arithmetic. - /// - /// Equivalent to calling [`pointer::wrapping_offset`] on each element. - fn wrapping_offset(self, offset: Self::Isize) -> Self; - - /// Calculates the offset from a pointer using wrapping arithmetic. - /// - /// Equivalent to calling [`pointer::wrapping_add`] on each element. - fn wrapping_add(self, count: Self::Usize) -> Self; - - /// Calculates the offset from a pointer using wrapping arithmetic. - /// - /// Equivalent to calling [`pointer::wrapping_sub`] on each element. - fn wrapping_sub(self, count: Self::Usize) -> Self; -} - -impl Sealed for Simd<*const T, N> where LaneCount: SupportedLaneCount {} - -impl SimdConstPtr for Simd<*const T, N> -where - LaneCount: SupportedLaneCount, -{ - type Usize = Simd; - type Isize = Simd; - type CastPtr = Simd<*const U, N>; - type MutPtr = Simd<*mut T, N>; - type Mask = Mask; - - #[inline] - fn is_null(self) -> Self::Mask { - Simd::splat(core::ptr::null()).simd_eq(self) - } - - #[inline] - fn cast(self) -> Self::CastPtr { - // SimdElement currently requires zero-sized metadata, so this should never fail. - // If this ever changes, `simd_cast_ptr` should produce a post-mono error. - use core::{mem::size_of, ptr::Pointee}; - assert_eq!(size_of::<::Metadata>(), 0); - assert_eq!(size_of::<::Metadata>(), 0); - - // Safety: pointers can be cast - unsafe { core::intrinsics::simd::simd_cast_ptr(self) } - } - - #[inline] - fn cast_mut(self) -> Self::MutPtr { - // Safety: pointers can be cast - unsafe { core::intrinsics::simd::simd_cast_ptr(self) } - } - - #[inline] - fn addr(self) -> Self::Usize { - // FIXME(strict_provenance_magic): I am magic and should be a compiler intrinsic. - // SAFETY: Pointer-to-integer transmutes are valid (if you are okay with losing the - // provenance). - unsafe { core::mem::transmute_copy(&self) } - } - - #[inline] - fn with_addr(self, addr: Self::Usize) -> Self { - // FIXME(strict_provenance_magic): I am magic and should be a compiler intrinsic. - // - // In the mean-time, this operation is defined to be "as if" it was - // a wrapping_offset, so we can emulate it as such. This should properly - // restore pointer provenance even under today's compiler. - self.cast::() - .wrapping_offset(addr.cast::() - self.addr().cast::()) - .cast() - } - - #[inline] - fn expose_provenance(self) -> Self::Usize { - // Safety: `self` is a pointer vector - unsafe { core::intrinsics::simd::simd_expose_provenance(self) } - } - - #[inline] - fn with_exposed_provenance(addr: Self::Usize) -> Self { - // Safety: `self` is a pointer vector - unsafe { core::intrinsics::simd::simd_with_exposed_provenance(addr) } - } - - #[inline] - fn wrapping_offset(self, count: Self::Isize) -> Self { - // Safety: simd_arith_offset takes a vector of pointers and a vector of offsets - unsafe { core::intrinsics::simd::simd_arith_offset(self, count) } - } - - #[inline] - fn wrapping_add(self, count: Self::Usize) -> Self { - self.wrapping_offset(count.cast()) - } - - #[inline] - fn wrapping_sub(self, count: Self::Usize) -> Self { - self.wrapping_offset(-count.cast::()) - } -} diff --git a/library/portable-simd/crates/core_simd/src/simd/ptr/mut_ptr.rs b/library/portable-simd/crates/core_simd/src/simd/ptr/mut_ptr.rs deleted file mode 100644 index 7ba996d149c0c..0000000000000 --- a/library/portable-simd/crates/core_simd/src/simd/ptr/mut_ptr.rs +++ /dev/null @@ -1,157 +0,0 @@ -use super::sealed::Sealed; -use crate::simd::{cmp::SimdPartialEq, num::SimdUint, LaneCount, Mask, Simd, SupportedLaneCount}; - -/// Operations on SIMD vectors of mutable pointers. -pub trait SimdMutPtr: Copy + Sealed { - /// Vector of `usize` with the same number of elements. - type Usize; - - /// Vector of `isize` with the same number of elements. - type Isize; - - /// Vector of const pointers with the same number of elements. - type CastPtr; - - /// Vector of constant pointers to the same type. - type ConstPtr; - - /// Mask type used for manipulating this SIMD vector type. - type Mask; - - /// Returns `true` for each element that is null. - fn is_null(self) -> Self::Mask; - - /// Casts to a pointer of another type. - /// - /// Equivalent to calling [`pointer::cast`] on each element. - fn cast(self) -> Self::CastPtr; - - /// Changes constness without changing the type. - /// - /// Equivalent to calling [`pointer::cast_const`] on each element. - fn cast_const(self) -> Self::ConstPtr; - - /// Gets the "address" portion of the pointer. - /// - /// This method discards pointer semantic metadata, so the result cannot be - /// directly cast into a valid pointer. - /// - /// Equivalent to calling [`pointer::addr`] on each element. - fn addr(self) -> Self::Usize; - - /// Creates a new pointer with the given address. - /// - /// This performs the same operation as a cast, but copies the *address-space* and - /// *provenance* of `self` to the new pointer. - /// - /// Equivalent to calling [`pointer::with_addr`] on each element. - fn with_addr(self, addr: Self::Usize) -> Self; - - /// Exposes the "provenance" part of the pointer for future use in - /// [`Self::with_exposed_provenance`] and returns the "address" portion. - fn expose_provenance(self) -> Self::Usize; - - /// Convert an address back to a pointer, picking up a previously "exposed" provenance. - /// - /// Equivalent to calling [`core::ptr::with_exposed_provenance_mut`] on each element. - fn with_exposed_provenance(addr: Self::Usize) -> Self; - - /// Calculates the offset from a pointer using wrapping arithmetic. - /// - /// Equivalent to calling [`pointer::wrapping_offset`] on each element. - fn wrapping_offset(self, offset: Self::Isize) -> Self; - - /// Calculates the offset from a pointer using wrapping arithmetic. - /// - /// Equivalent to calling [`pointer::wrapping_add`] on each element. - fn wrapping_add(self, count: Self::Usize) -> Self; - - /// Calculates the offset from a pointer using wrapping arithmetic. - /// - /// Equivalent to calling [`pointer::wrapping_sub`] on each element. - fn wrapping_sub(self, count: Self::Usize) -> Self; -} - -impl Sealed for Simd<*mut T, N> where LaneCount: SupportedLaneCount {} - -impl SimdMutPtr for Simd<*mut T, N> -where - LaneCount: SupportedLaneCount, -{ - type Usize = Simd; - type Isize = Simd; - type CastPtr = Simd<*mut U, N>; - type ConstPtr = Simd<*const T, N>; - type Mask = Mask; - - #[inline] - fn is_null(self) -> Self::Mask { - Simd::splat(core::ptr::null_mut()).simd_eq(self) - } - - #[inline] - fn cast(self) -> Self::CastPtr { - // SimdElement currently requires zero-sized metadata, so this should never fail. - // If this ever changes, `simd_cast_ptr` should produce a post-mono error. - use core::{mem::size_of, ptr::Pointee}; - assert_eq!(size_of::<::Metadata>(), 0); - assert_eq!(size_of::<::Metadata>(), 0); - - // Safety: pointers can be cast - unsafe { core::intrinsics::simd::simd_cast_ptr(self) } - } - - #[inline] - fn cast_const(self) -> Self::ConstPtr { - // Safety: pointers can be cast - unsafe { core::intrinsics::simd::simd_cast_ptr(self) } - } - - #[inline] - fn addr(self) -> Self::Usize { - // FIXME(strict_provenance_magic): I am magic and should be a compiler intrinsic. - // SAFETY: Pointer-to-integer transmutes are valid (if you are okay with losing the - // provenance). - unsafe { core::mem::transmute_copy(&self) } - } - - #[inline] - fn with_addr(self, addr: Self::Usize) -> Self { - // FIXME(strict_provenance_magic): I am magic and should be a compiler intrinsic. - // - // In the mean-time, this operation is defined to be "as if" it was - // a wrapping_offset, so we can emulate it as such. This should properly - // restore pointer provenance even under today's compiler. - self.cast::() - .wrapping_offset(addr.cast::() - self.addr().cast::()) - .cast() - } - - #[inline] - fn expose_provenance(self) -> Self::Usize { - // Safety: `self` is a pointer vector - unsafe { core::intrinsics::simd::simd_expose_provenance(self) } - } - - #[inline] - fn with_exposed_provenance(addr: Self::Usize) -> Self { - // Safety: `self` is a pointer vector - unsafe { core::intrinsics::simd::simd_with_exposed_provenance(addr) } - } - - #[inline] - fn wrapping_offset(self, count: Self::Isize) -> Self { - // Safety: simd_arith_offset takes a vector of pointers and a vector of offsets - unsafe { core::intrinsics::simd::simd_arith_offset(self, count) } - } - - #[inline] - fn wrapping_add(self, count: Self::Usize) -> Self { - self.wrapping_offset(count.cast()) - } - - #[inline] - fn wrapping_sub(self, count: Self::Usize) -> Self { - self.wrapping_offset(-count.cast::()) - } -} diff --git a/library/portable-simd/crates/core_simd/src/swizzle.rs b/library/portable-simd/crates/core_simd/src/swizzle.rs deleted file mode 100644 index 71110bb282018..0000000000000 --- a/library/portable-simd/crates/core_simd/src/swizzle.rs +++ /dev/null @@ -1,386 +0,0 @@ -use crate::simd::{LaneCount, Mask, MaskElement, Simd, SimdElement, SupportedLaneCount}; - -/// Constructs a new SIMD vector by copying elements from selected elements in other vectors. -/// -/// When swizzling one vector, elements are selected like [`Swizzle::swizzle`]. -/// -/// When swizzling two vectors, elements are selected like [`Swizzle::concat_swizzle`]. -/// -/// # Examples -/// -/// With a single SIMD vector, the const array specifies element indices in that vector: -/// ``` -/// # #![feature(portable_simd)] -/// # use core::simd::{u32x2, u32x4, simd_swizzle}; -/// let v = u32x4::from_array([10, 11, 12, 13]); -/// -/// // Keeping the same size -/// let r: u32x4 = simd_swizzle!(v, [3, 0, 1, 2]); -/// assert_eq!(r.to_array(), [13, 10, 11, 12]); -/// -/// // Changing the number of elements -/// let r: u32x2 = simd_swizzle!(v, [3, 1]); -/// assert_eq!(r.to_array(), [13, 11]); -/// ``` -/// -/// With two input SIMD vectors, the const array specifies element indices in the concatenation of -/// those vectors: -/// ``` -/// # #![feature(portable_simd)] -/// # #[cfg(feature = "as_crate")] use core_simd::simd; -/// # #[cfg(not(feature = "as_crate"))] use core::simd; -/// # use simd::{u32x2, u32x4, simd_swizzle}; -/// let a = u32x4::from_array([0, 1, 2, 3]); -/// let b = u32x4::from_array([4, 5, 6, 7]); -/// -/// // Keeping the same size -/// let r: u32x4 = simd_swizzle!(a, b, [0, 1, 6, 7]); -/// assert_eq!(r.to_array(), [0, 1, 6, 7]); -/// -/// // Changing the number of elements -/// let r: u32x2 = simd_swizzle!(a, b, [0, 4]); -/// assert_eq!(r.to_array(), [0, 4]); -/// ``` -#[allow(unused_macros)] -pub macro simd_swizzle { - ( - $vector:expr, $index:expr $(,)? - ) => { - { - use $crate::simd::Swizzle; - struct Impl; - impl Swizzle<{$index.len()}> for Impl { - const INDEX: [usize; {$index.len()}] = $index; - } - Impl::swizzle($vector) - } - }, - ( - $first:expr, $second:expr, $index:expr $(,)? - ) => { - { - use $crate::simd::Swizzle; - struct Impl; - impl Swizzle<{$index.len()}> for Impl { - const INDEX: [usize; {$index.len()}] = $index; - } - Impl::concat_swizzle($first, $second) - } - } -} - -/// Create a vector from the elements of another vector. -pub trait Swizzle { - /// Map from the elements of the input vector to the output vector. - const INDEX: [usize; N]; - - /// Create a new vector from the elements of `vector`. - /// - /// Lane `i` of the output is `vector[Self::INDEX[i]]`. - #[inline] - #[must_use = "method returns a new vector and does not mutate the original inputs"] - fn swizzle(vector: Simd) -> Simd - where - T: SimdElement, - LaneCount: SupportedLaneCount, - LaneCount: SupportedLaneCount, - { - // Safety: `vector` is a vector, and the index is a const array of u32. - unsafe { - core::intrinsics::simd::simd_shuffle( - vector, - vector, - const { - let mut output = [0; N]; - let mut i = 0; - while i < N { - let index = Self::INDEX[i]; - assert!(index as u32 as usize == index); - assert!( - index < M, - "source element index exceeds input vector length" - ); - output[i] = index as u32; - i += 1; - } - output - }, - ) - } - } - - /// Create a new vector from the elements of `first` and `second`. - /// - /// Lane `i` of the output is `concat[Self::INDEX[i]]`, where `concat` is the concatenation of - /// `first` and `second`. - #[inline] - #[must_use = "method returns a new vector and does not mutate the original inputs"] - fn concat_swizzle(first: Simd, second: Simd) -> Simd - where - T: SimdElement, - LaneCount: SupportedLaneCount, - LaneCount: SupportedLaneCount, - { - // Safety: `first` and `second` are vectors, and the index is a const array of u32. - unsafe { - core::intrinsics::simd::simd_shuffle( - first, - second, - const { - let mut output = [0; N]; - let mut i = 0; - while i < N { - let index = Self::INDEX[i]; - assert!(index as u32 as usize == index); - assert!( - index < 2 * M, - "source element index exceeds input vector length" - ); - output[i] = index as u32; - i += 1; - } - output - }, - ) - } - } - - /// Create a new mask from the elements of `mask`. - /// - /// Element `i` of the output is `concat[Self::INDEX[i]]`, where `concat` is the concatenation of - /// `first` and `second`. - #[inline] - #[must_use = "method returns a new mask and does not mutate the original inputs"] - fn swizzle_mask(mask: Mask) -> Mask - where - T: MaskElement, - LaneCount: SupportedLaneCount, - LaneCount: SupportedLaneCount, - { - // SAFETY: all elements of this mask come from another mask - unsafe { Mask::from_int_unchecked(Self::swizzle(mask.to_int())) } - } - - /// Create a new mask from the elements of `first` and `second`. - /// - /// Element `i` of the output is `concat[Self::INDEX[i]]`, where `concat` is the concatenation of - /// `first` and `second`. - #[inline] - #[must_use = "method returns a new mask and does not mutate the original inputs"] - fn concat_swizzle_mask(first: Mask, second: Mask) -> Mask - where - T: MaskElement, - LaneCount: SupportedLaneCount, - LaneCount: SupportedLaneCount, - { - // SAFETY: all elements of this mask come from another mask - unsafe { Mask::from_int_unchecked(Self::concat_swizzle(first.to_int(), second.to_int())) } - } -} - -impl Simd -where - T: SimdElement, - LaneCount: SupportedLaneCount, -{ - /// Reverse the order of the elements in the vector. - #[inline] - #[must_use = "method returns a new vector and does not mutate the original inputs"] - pub fn reverse(self) -> Self { - struct Reverse; - - impl Swizzle for Reverse { - const INDEX: [usize; N] = const { - let mut index = [0; N]; - let mut i = 0; - while i < N { - index[i] = N - i - 1; - i += 1; - } - index - }; - } - - Reverse::swizzle(self) - } - - /// Rotates the vector such that the first `OFFSET` elements of the slice move to the end - /// while the last `self.len() - OFFSET` elements move to the front. After calling `rotate_elements_left`, - /// the element previously at index `OFFSET` will become the first element in the slice. - #[inline] - #[must_use = "method returns a new vector and does not mutate the original inputs"] - pub fn rotate_elements_left(self) -> Self { - struct Rotate; - - impl Swizzle for Rotate { - const INDEX: [usize; N] = const { - let offset = OFFSET % N; - let mut index = [0; N]; - let mut i = 0; - while i < N { - index[i] = (i + offset) % N; - i += 1; - } - index - }; - } - - Rotate::::swizzle(self) - } - - /// Rotates the vector such that the first `self.len() - OFFSET` elements of the vector move to - /// the end while the last `OFFSET` elements move to the front. After calling `rotate_elements_right`, - /// the element previously at index `self.len() - OFFSET` will become the first element in the slice. - #[inline] - #[must_use = "method returns a new vector and does not mutate the original inputs"] - pub fn rotate_elements_right(self) -> Self { - struct Rotate; - - impl Swizzle for Rotate { - const INDEX: [usize; N] = const { - let offset = N - OFFSET % N; - let mut index = [0; N]; - let mut i = 0; - while i < N { - index[i] = (i + offset) % N; - i += 1; - } - index - }; - } - - Rotate::::swizzle(self) - } - - /// Interleave two vectors. - /// - /// The resulting vectors contain elements taken alternatively from `self` and `other`, first - /// filling the first result, and then the second. - /// - /// The reverse of this operation is [`Simd::deinterleave`]. - /// - /// ``` - /// # #![feature(portable_simd)] - /// # use core::simd::Simd; - /// let a = Simd::from_array([0, 1, 2, 3]); - /// let b = Simd::from_array([4, 5, 6, 7]); - /// let (x, y) = a.interleave(b); - /// assert_eq!(x.to_array(), [0, 4, 1, 5]); - /// assert_eq!(y.to_array(), [2, 6, 3, 7]); - /// ``` - #[inline] - #[must_use = "method returns a new vector and does not mutate the original inputs"] - pub fn interleave(self, other: Self) -> (Self, Self) { - const fn interleave(high: bool) -> [usize; N] { - let mut idx = [0; N]; - let mut i = 0; - while i < N { - let dst_index = if high { i + N } else { i }; - let src_index = dst_index / 2 + (dst_index % 2) * N; - idx[i] = src_index; - i += 1; - } - idx - } - - struct Lo; - struct Hi; - - impl Swizzle for Lo { - const INDEX: [usize; N] = interleave::(false); - } - - impl Swizzle for Hi { - const INDEX: [usize; N] = interleave::(true); - } - - ( - Lo::concat_swizzle(self, other), - Hi::concat_swizzle(self, other), - ) - } - - /// Deinterleave two vectors. - /// - /// The first result takes every other element of `self` and then `other`, starting with - /// the first element. - /// - /// The second result takes every other element of `self` and then `other`, starting with - /// the second element. - /// - /// The reverse of this operation is [`Simd::interleave`]. - /// - /// ``` - /// # #![feature(portable_simd)] - /// # use core::simd::Simd; - /// let a = Simd::from_array([0, 4, 1, 5]); - /// let b = Simd::from_array([2, 6, 3, 7]); - /// let (x, y) = a.deinterleave(b); - /// assert_eq!(x.to_array(), [0, 1, 2, 3]); - /// assert_eq!(y.to_array(), [4, 5, 6, 7]); - /// ``` - #[inline] - #[must_use = "method returns a new vector and does not mutate the original inputs"] - pub fn deinterleave(self, other: Self) -> (Self, Self) { - const fn deinterleave(second: bool) -> [usize; N] { - let mut idx = [0; N]; - let mut i = 0; - while i < N { - idx[i] = i * 2 + second as usize; - i += 1; - } - idx - } - - struct Even; - struct Odd; - - impl Swizzle for Even { - const INDEX: [usize; N] = deinterleave::(false); - } - - impl Swizzle for Odd { - const INDEX: [usize; N] = deinterleave::(true); - } - - ( - Even::concat_swizzle(self, other), - Odd::concat_swizzle(self, other), - ) - } - - /// Resize a vector. - /// - /// If `M` > `N`, extends the length of a vector, setting the new elements to `value`. - /// If `M` < `N`, truncates the vector to the first `M` elements. - /// - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::u32x4; - /// let x = u32x4::from_array([0, 1, 2, 3]); - /// assert_eq!(x.resize::<8>(9).to_array(), [0, 1, 2, 3, 9, 9, 9, 9]); - /// assert_eq!(x.resize::<2>(9).to_array(), [0, 1]); - /// ``` - #[inline] - #[must_use = "method returns a new vector and does not mutate the original inputs"] - pub fn resize(self, value: T) -> Simd - where - LaneCount: SupportedLaneCount, - { - struct Resize; - impl Swizzle for Resize { - const INDEX: [usize; M] = const { - let mut index = [0; M]; - let mut i = 0; - while i < M { - index[i] = if i < N { i } else { N }; - i += 1; - } - index - }; - } - Resize::::concat_swizzle(self, Simd::splat(value)) - } -} diff --git a/library/portable-simd/crates/core_simd/src/swizzle_dyn.rs b/library/portable-simd/crates/core_simd/src/swizzle_dyn.rs deleted file mode 100644 index 8a1079042f076..0000000000000 --- a/library/portable-simd/crates/core_simd/src/swizzle_dyn.rs +++ /dev/null @@ -1,157 +0,0 @@ -use crate::simd::{LaneCount, Simd, SupportedLaneCount}; -use core::mem; - -impl Simd -where - LaneCount: SupportedLaneCount, -{ - /// Swizzle a vector of bytes according to the index vector. - /// Indices within range select the appropriate byte. - /// Indices "out of bounds" instead select 0. - /// - /// Note that the current implementation is selected during build-time - /// of the standard library, so `cargo build -Zbuild-std` may be necessary - /// to unlock better performance, especially for larger vectors. - /// A planned compiler improvement will enable using `#[target_feature]` instead. - #[inline] - pub fn swizzle_dyn(self, idxs: Simd) -> Self { - #![allow(unused_imports, unused_unsafe)] - #[cfg(all( - any(target_arch = "aarch64", target_arch = "arm64ec"), - target_endian = "little" - ))] - use core::arch::aarch64::{uint8x8_t, vqtbl1q_u8, vtbl1_u8}; - #[cfg(all( - target_arch = "arm", - target_feature = "v7", - target_feature = "neon", - target_endian = "little" - ))] - use core::arch::arm::{uint8x8_t, vtbl1_u8}; - #[cfg(target_arch = "wasm32")] - use core::arch::wasm32 as wasm; - #[cfg(target_arch = "x86")] - use core::arch::x86; - #[cfg(target_arch = "x86_64")] - use core::arch::x86_64 as x86; - // SAFETY: Intrinsics covered by cfg - unsafe { - match N { - #[cfg(all( - any( - target_arch = "aarch64", - target_arch = "arm64ec", - all(target_arch = "arm", target_feature = "v7") - ), - target_feature = "neon", - target_endian = "little" - ))] - 8 => transize(vtbl1_u8, self, idxs), - #[cfg(target_feature = "ssse3")] - 16 => transize(x86::_mm_shuffle_epi8, self, zeroing_idxs(idxs)), - #[cfg(target_feature = "simd128")] - 16 => transize(wasm::i8x16_swizzle, self, idxs), - #[cfg(all( - any(target_arch = "aarch64", target_arch = "arm64ec"), - target_feature = "neon", - target_endian = "little" - ))] - 16 => transize(vqtbl1q_u8, self, idxs), - #[cfg(all(target_feature = "avx2", not(target_feature = "avx512vbmi")))] - 32 => transize(avx2_pshufb, self, idxs), - #[cfg(all(target_feature = "avx512vl", target_feature = "avx512vbmi"))] - 32 => transize(x86::_mm256_permutexvar_epi8, zeroing_idxs(idxs), self), - // Notable absence: avx512bw shuffle - // If avx512bw is available, odds of avx512vbmi are good - // FIXME: initial AVX512VBMI variant didn't actually pass muster - // #[cfg(target_feature = "avx512vbmi")] - // 64 => transize(x86::_mm512_permutexvar_epi8, self, idxs), - _ => { - let mut array = [0; N]; - for (i, k) in idxs.to_array().into_iter().enumerate() { - if (k as usize) < N { - array[i] = self[k as usize]; - }; - } - array.into() - } - } - } - } -} - -/// "vpshufb like it was meant to be" on AVX2 -/// -/// # Safety -/// This requires AVX2 to work -#[cfg(any(target_arch = "x86", target_arch = "x86_64"))] -#[target_feature(enable = "avx2")] -#[allow(unused)] -#[inline] -#[allow(clippy::let_and_return)] -unsafe fn avx2_pshufb(bytes: Simd, idxs: Simd) -> Simd { - use crate::simd::cmp::SimdPartialOrd; - #[cfg(target_arch = "x86")] - use core::arch::x86; - #[cfg(target_arch = "x86_64")] - use core::arch::x86_64 as x86; - use x86::_mm256_permute2x128_si256 as avx2_cross_shuffle; - use x86::_mm256_shuffle_epi8 as avx2_half_pshufb; - let mid = Simd::splat(16u8); - let high = mid + mid; - // SAFETY: Caller promised AVX2 - unsafe { - // This is ordering sensitive, and LLVM will order these how you put them. - // Most AVX2 impls use ~5 "ports", and only 1 or 2 are capable of permutes. - // But the "compose" step will lower to ops that can also use at least 1 other port. - // So this tries to break up permutes so composition flows through "open" ports. - // Comparative benches should be done on multiple AVX2 CPUs before reordering this - - let hihi = avx2_cross_shuffle::<0x11>(bytes.into(), bytes.into()); - let hi_shuf = Simd::from(avx2_half_pshufb( - hihi, // duplicate the vector's top half - idxs.into(), // so that using only 4 bits of an index still picks bytes 16-31 - )); - // A zero-fill during the compose step gives the "all-Neon-like" OOB-is-0 semantics - let compose = idxs.simd_lt(high).select(hi_shuf, Simd::splat(0)); - let lolo = avx2_cross_shuffle::<0x00>(bytes.into(), bytes.into()); - let lo_shuf = Simd::from(avx2_half_pshufb(lolo, idxs.into())); - // Repeat, then pick indices < 16, overwriting indices 0-15 from previous compose step - let compose = idxs.simd_lt(mid).select(lo_shuf, compose); - compose - } -} - -/// This sets up a call to an architecture-specific function, and in doing so -/// it persuades rustc that everything is the correct size. Which it is. -/// This would not be needed if one could convince Rust that, by matching on N, -/// N is that value, and thus it would be valid to substitute e.g. 16. -/// -/// # Safety -/// The correctness of this function hinges on the sizes agreeing in actuality. -#[allow(dead_code)] -#[inline(always)] -unsafe fn transize( - f: unsafe fn(T, T) -> T, - a: Simd, - b: Simd, -) -> Simd -where - LaneCount: SupportedLaneCount, -{ - // SAFETY: Same obligation to use this function as to use mem::transmute_copy. - unsafe { mem::transmute_copy(&f(mem::transmute_copy(&a), mem::transmute_copy(&b))) } -} - -/// Make indices that yield 0 for x86 -#[cfg(any(target_arch = "x86", target_arch = "x86_64"))] -#[allow(unused)] -#[inline(always)] -fn zeroing_idxs(idxs: Simd) -> Simd -where - LaneCount: SupportedLaneCount, -{ - use crate::simd::cmp::SimdPartialOrd; - idxs.simd_lt(Simd::splat(N as u8)) - .select(idxs, Simd::splat(u8::MAX)) -} diff --git a/library/portable-simd/crates/core_simd/src/to_bytes.rs b/library/portable-simd/crates/core_simd/src/to_bytes.rs deleted file mode 100644 index 222526c4ab30a..0000000000000 --- a/library/portable-simd/crates/core_simd/src/to_bytes.rs +++ /dev/null @@ -1,145 +0,0 @@ -use crate::simd::{ - num::{SimdFloat, SimdInt, SimdUint}, - LaneCount, Simd, SimdElement, SupportedLaneCount, -}; - -mod sealed { - use super::*; - pub trait Sealed {} - impl Sealed for Simd where LaneCount: SupportedLaneCount {} -} -use sealed::Sealed; - -/// Convert SIMD vectors to vectors of bytes -pub trait ToBytes: Sealed { - /// This type, reinterpreted as bytes. - type Bytes: Copy - + Unpin - + Send - + Sync - + AsRef<[u8]> - + AsMut<[u8]> - + SimdUint - + 'static; - - /// Return the memory representation of this integer as a byte array in native byte - /// order. - fn to_ne_bytes(self) -> Self::Bytes; - - /// Return the memory representation of this integer as a byte array in big-endian - /// (network) byte order. - fn to_be_bytes(self) -> Self::Bytes; - - /// Return the memory representation of this integer as a byte array in little-endian - /// byte order. - fn to_le_bytes(self) -> Self::Bytes; - - /// Create a native endian integer value from its memory representation as a byte array - /// in native endianness. - fn from_ne_bytes(bytes: Self::Bytes) -> Self; - - /// Create an integer value from its representation as a byte array in big endian. - fn from_be_bytes(bytes: Self::Bytes) -> Self; - - /// Create an integer value from its representation as a byte array in little endian. - fn from_le_bytes(bytes: Self::Bytes) -> Self; -} - -macro_rules! swap_bytes { - { f32, $x:expr } => { Simd::from_bits($x.to_bits().swap_bytes()) }; - { f64, $x:expr } => { Simd::from_bits($x.to_bits().swap_bytes()) }; - { $ty:ty, $x:expr } => { $x.swap_bytes() } -} - -macro_rules! impl_to_bytes { - { $ty:tt, 1 } => { impl_to_bytes! { $ty, 1 * [1, 2, 4, 8, 16, 32, 64] } }; - { $ty:tt, 2 } => { impl_to_bytes! { $ty, 2 * [1, 2, 4, 8, 16, 32] } }; - { $ty:tt, 4 } => { impl_to_bytes! { $ty, 4 * [1, 2, 4, 8, 16] } }; - { $ty:tt, 8 } => { impl_to_bytes! { $ty, 8 * [1, 2, 4, 8] } }; - { $ty:tt, 16 } => { impl_to_bytes! { $ty, 16 * [1, 2, 4] } }; - { $ty:tt, 32 } => { impl_to_bytes! { $ty, 32 * [1, 2] } }; - { $ty:tt, 64 } => { impl_to_bytes! { $ty, 64 * [1] } }; - - { $ty:tt, $size:literal * [$($elems:literal),*] } => { - $( - impl ToBytes for Simd<$ty, $elems> { - type Bytes = Simd; - - #[inline] - fn to_ne_bytes(self) -> Self::Bytes { - // Safety: transmuting between vectors is safe - unsafe { - #![allow(clippy::useless_transmute)] - core::mem::transmute(self) - } - } - - #[inline] - fn to_be_bytes(mut self) -> Self::Bytes { - if !cfg!(target_endian = "big") { - self = swap_bytes!($ty, self); - } - self.to_ne_bytes() - } - - #[inline] - fn to_le_bytes(mut self) -> Self::Bytes { - if !cfg!(target_endian = "little") { - self = swap_bytes!($ty, self); - } - self.to_ne_bytes() - } - - #[inline] - fn from_ne_bytes(bytes: Self::Bytes) -> Self { - // Safety: transmuting between vectors is safe - unsafe { - #![allow(clippy::useless_transmute)] - core::mem::transmute(bytes) - } - } - - #[inline] - fn from_be_bytes(bytes: Self::Bytes) -> Self { - let ret = Self::from_ne_bytes(bytes); - if cfg!(target_endian = "big") { - ret - } else { - swap_bytes!($ty, ret) - } - } - - #[inline] - fn from_le_bytes(bytes: Self::Bytes) -> Self { - let ret = Self::from_ne_bytes(bytes); - if cfg!(target_endian = "little") { - ret - } else { - swap_bytes!($ty, ret) - } - } - } - )* - } -} - -impl_to_bytes! { u8, 1 } -impl_to_bytes! { u16, 2 } -impl_to_bytes! { u32, 4 } -impl_to_bytes! { u64, 8 } -#[cfg(target_pointer_width = "32")] -impl_to_bytes! { usize, 4 } -#[cfg(target_pointer_width = "64")] -impl_to_bytes! { usize, 8 } - -impl_to_bytes! { i8, 1 } -impl_to_bytes! { i16, 2 } -impl_to_bytes! { i32, 4 } -impl_to_bytes! { i64, 8 } -#[cfg(target_pointer_width = "32")] -impl_to_bytes! { isize, 4 } -#[cfg(target_pointer_width = "64")] -impl_to_bytes! { isize, 8 } - -impl_to_bytes! { f32, 4 } -impl_to_bytes! { f64, 8 } diff --git a/library/portable-simd/crates/core_simd/src/vector.rs b/library/portable-simd/crates/core_simd/src/vector.rs deleted file mode 100644 index 8dbdfc0e1fe03..0000000000000 --- a/library/portable-simd/crates/core_simd/src/vector.rs +++ /dev/null @@ -1,1225 +0,0 @@ -use crate::simd::{ - cmp::SimdPartialOrd, - num::SimdUint, - ptr::{SimdConstPtr, SimdMutPtr}, - LaneCount, Mask, MaskElement, SupportedLaneCount, Swizzle, -}; - -/// A SIMD vector with the shape of `[T; N]` but the operations of `T`. -/// -/// `Simd` supports the operators (+, *, etc.) that `T` does in "elementwise" fashion. -/// These take the element at each index from the left-hand side and right-hand side, -/// perform the operation, then return the result in the same index in a vector of equal size. -/// However, `Simd` differs from normal iteration and normal arrays: -/// - `Simd` executes `N` operations in a single step with no `break`s -/// - `Simd` can have an alignment greater than `T`, for better mechanical sympathy -/// -/// By always imposing these constraints on `Simd`, it is easier to compile elementwise operations -/// into machine instructions that can themselves be executed in parallel. -/// -/// ```rust -/// # #![feature(portable_simd)] -/// # use core::simd::{Simd}; -/// # use core::array; -/// let a: [i32; 4] = [-2, 0, 2, 4]; -/// let b = [10, 9, 8, 7]; -/// let sum = array::from_fn(|i| a[i] + b[i]); -/// let prod = array::from_fn(|i| a[i] * b[i]); -/// -/// // `Simd` implements `From<[T; N]>` -/// let (v, w) = (Simd::from(a), Simd::from(b)); -/// // Which means arrays implement `Into>`. -/// assert_eq!(v + w, sum.into()); -/// assert_eq!(v * w, prod.into()); -/// ``` -/// -/// -/// `Simd` with integer elements treats operators as wrapping, as if `T` was [`Wrapping`]. -/// Thus, `Simd` does not implement `wrapping_add`, because that is the default behavior. -/// This means there is no warning on overflows, even in "debug" builds. -/// For most applications where `Simd` is appropriate, it is "not a bug" to wrap, -/// and even "debug builds" are unlikely to tolerate the loss of performance. -/// You may want to consider using explicitly checked arithmetic if such is required. -/// Division by zero on integers still causes a panic, so -/// you may want to consider using `f32` or `f64` if that is unacceptable. -/// -/// [`Wrapping`]: core::num::Wrapping -/// -/// # Layout -/// `Simd` has a layout similar to `[T; N]` (identical "shapes"), with a greater alignment. -/// `[T; N]` is aligned to `T`, but `Simd` will have an alignment based on both `T` and `N`. -/// Thus it is sound to [`transmute`] `Simd` to `[T; N]` and should optimize to "zero cost", -/// but the reverse transmutation may require a copy the compiler cannot simply elide. -/// -/// # ABI "Features" -/// Due to Rust's safety guarantees, `Simd` is currently passed and returned via memory, -/// not SIMD registers, except as an optimization. Using `#[inline]` on functions that accept -/// `Simd` or return it is recommended, at the cost of code generation time, as -/// inlining SIMD-using functions can omit a large function prolog or epilog and thus -/// improve both speed and code size. The need for this may be corrected in the future. -/// -/// Using `#[inline(always)]` still requires additional care. -/// -/// # Safe SIMD with Unsafe Rust -/// -/// Operations with `Simd` are typically safe, but there are many reasons to want to combine SIMD with `unsafe` code. -/// Care must be taken to respect differences between `Simd` and other types it may be transformed into or derived from. -/// In particular, the layout of `Simd` may be similar to `[T; N]`, and may allow some transmutations, -/// but references to `[T; N]` are not interchangeable with those to `Simd`. -/// Thus, when using `unsafe` Rust to read and write `Simd` through [raw pointers], it is a good idea to first try with -/// [`read_unaligned`] and [`write_unaligned`]. This is because: -/// - [`read`] and [`write`] require full alignment (in this case, `Simd`'s alignment) -/// - `Simd` is often read from or written to [`[T]`](slice) and other types aligned to `T` -/// - combining these actions violates the `unsafe` contract and explodes the program into -/// a puff of **undefined behavior** -/// - the compiler can implicitly adjust layouts to make unaligned reads or writes fully aligned -/// if it sees the optimization -/// - most contemporary processors with "aligned" and "unaligned" read and write instructions -/// exhibit no performance difference if the "unaligned" variant is aligned at runtime -/// -/// Less obligations mean unaligned reads and writes are less likely to make the program unsound, -/// and may be just as fast as stricter alternatives. -/// When trying to guarantee alignment, [`[T]::as_simd`][as_simd] is an option for -/// converting `[T]` to `[Simd]`, and allows soundly operating on an aligned SIMD body, -/// but it may cost more time when handling the scalar head and tail. -/// If these are not enough, it is most ideal to design data structures to be already aligned -/// to `mem::align_of::>()` before using `unsafe` Rust to read or write. -/// Other ways to compensate for these facts, like materializing `Simd` to or from an array first, -/// are handled by safe methods like [`Simd::from_array`] and [`Simd::from_slice`]. -/// -/// [`transmute`]: core::mem::transmute -/// [raw pointers]: pointer -/// [`read_unaligned`]: pointer::read_unaligned -/// [`write_unaligned`]: pointer::write_unaligned -/// [`read`]: pointer::read -/// [`write`]: pointer::write -/// [as_simd]: slice::as_simd -// -// NOTE: Accessing the inner array directly in any way (e.g. by using the `.0` field syntax) or -// directly constructing an instance of the type (i.e. `let vector = Simd(array)`) should be -// avoided, as it will likely become illegal on `#[repr(simd)]` structs in the future. It also -// causes rustc to emit illegal LLVM IR in some cases. -#[repr(simd)] -pub struct Simd([T; N]) -where - LaneCount: SupportedLaneCount, - T: SimdElement; - -impl Simd -where - LaneCount: SupportedLaneCount, - T: SimdElement, -{ - /// Number of elements in this vector. - pub const LEN: usize = N; - - /// Returns the number of elements in this SIMD vector. - /// - /// # Examples - /// - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::u32x4; - /// let v = u32x4::splat(0); - /// assert_eq!(v.len(), 4); - /// ``` - #[inline] - #[allow(clippy::len_without_is_empty)] - pub const fn len(&self) -> usize { - Self::LEN - } - - /// Constructs a new SIMD vector with all elements set to the given value. - /// - /// # Examples - /// - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::u32x4; - /// let v = u32x4::splat(8); - /// assert_eq!(v.as_array(), &[8, 8, 8, 8]); - /// ``` - #[inline] - pub fn splat(value: T) -> Self { - // This is preferred over `[value; N]`, since it's explicitly a splat: - // https://github.com/rust-lang/rust/issues/97804 - struct Splat; - impl Swizzle for Splat { - const INDEX: [usize; N] = [0; N]; - } - Splat::swizzle::(Simd::::from([value])) - } - - /// Returns an array reference containing the entire SIMD vector. - /// - /// # Examples - /// - /// ``` - /// # #![feature(portable_simd)] - /// # use core::simd::{Simd, u64x4}; - /// let v: u64x4 = Simd::from_array([0, 1, 2, 3]); - /// assert_eq!(v.as_array(), &[0, 1, 2, 3]); - /// ``` - #[inline] - pub const fn as_array(&self) -> &[T; N] { - // SAFETY: `Simd` is just an overaligned `[T; N]` with - // potential padding at the end, so pointer casting to a - // `&[T; N]` is safe. - // - // NOTE: This deliberately doesn't just use `&self.0`, see the comment - // on the struct definition for details. - unsafe { &*(self as *const Self as *const [T; N]) } - } - - /// Returns a mutable array reference containing the entire SIMD vector. - #[inline] - pub fn as_mut_array(&mut self) -> &mut [T; N] { - // SAFETY: `Simd` is just an overaligned `[T; N]` with - // potential padding at the end, so pointer casting to a - // `&mut [T; N]` is safe. - // - // NOTE: This deliberately doesn't just use `&mut self.0`, see the comment - // on the struct definition for details. - unsafe { &mut *(self as *mut Self as *mut [T; N]) } - } - - /// Load a vector from an array of `T`. - /// - /// This function is necessary since `repr(simd)` has padding for non-power-of-2 vectors (at the time of writing). - /// With padding, `read_unaligned` will read past the end of an array of N elements. - /// - /// # Safety - /// Reading `ptr` must be safe, as if by `<*const [T; N]>::read`. - #[inline] - const unsafe fn load(ptr: *const [T; N]) -> Self { - // There are potentially simpler ways to write this function, but this should result in - // LLVM `load ` - - let mut tmp = core::mem::MaybeUninit::::uninit(); - // SAFETY: `Simd` always contains `N` elements of type `T`. It may have padding - // which does not need to be initialized. The safety of reading `ptr` is ensured by the - // caller. - unsafe { - core::ptr::copy_nonoverlapping(ptr, tmp.as_mut_ptr().cast(), 1); - tmp.assume_init() - } - } - - /// Store a vector to an array of `T`. - /// - /// See `load` as to why this function is necessary. - /// - /// # Safety - /// Writing to `ptr` must be safe, as if by `<*mut [T; N]>::write`. - #[inline] - const unsafe fn store(self, ptr: *mut [T; N]) { - // There are potentially simpler ways to write this function, but this should result in - // LLVM `store ` - - // Creating a temporary helps LLVM turn the memcpy into a store. - let tmp = self; - // SAFETY: `Simd` always contains `N` elements of type `T`. The safety of writing - // `ptr` is ensured by the caller. - unsafe { core::ptr::copy_nonoverlapping(tmp.as_array(), ptr, 1) } - } - - /// Converts an array to a SIMD vector. - #[inline] - pub const fn from_array(array: [T; N]) -> Self { - // SAFETY: `&array` is safe to read. - // - // FIXME: We currently use a pointer load instead of `transmute_copy` because `repr(simd)` - // results in padding for non-power-of-2 vectors (so vectors are larger than arrays). - // - // NOTE: This deliberately doesn't just use `Self(array)`, see the comment - // on the struct definition for details. - unsafe { Self::load(&array) } - } - - /// Converts a SIMD vector to an array. - #[inline] - pub const fn to_array(self) -> [T; N] { - let mut tmp = core::mem::MaybeUninit::uninit(); - // SAFETY: writing to `tmp` is safe and initializes it. - // - // FIXME: We currently use a pointer store instead of `transmute_copy` because `repr(simd)` - // results in padding for non-power-of-2 vectors (so vectors are larger than arrays). - // - // NOTE: This deliberately doesn't just use `self.0`, see the comment - // on the struct definition for details. - unsafe { - self.store(tmp.as_mut_ptr()); - tmp.assume_init() - } - } - - /// Converts a slice to a SIMD vector containing `slice[..N]`. - /// - /// # Panics - /// - /// Panics if the slice's length is less than the vector's `Simd::N`. - /// Use `load_or_default` for an alternative that does not panic. - /// - /// # Example - /// - /// ``` - /// # #![feature(portable_simd)] - /// # use core::simd::u32x4; - /// let source = vec![1, 2, 3, 4, 5, 6]; - /// let v = u32x4::from_slice(&source); - /// assert_eq!(v.as_array(), &[1, 2, 3, 4]); - /// ``` - #[must_use] - #[inline] - #[track_caller] - pub const fn from_slice(slice: &[T]) -> Self { - assert!( - slice.len() >= Self::LEN, - "slice length must be at least the number of elements" - ); - // SAFETY: We just checked that the slice contains - // at least `N` elements. - unsafe { Self::load(slice.as_ptr().cast()) } - } - - /// Writes a SIMD vector to the first `N` elements of a slice. - /// - /// # Panics - /// - /// Panics if the slice's length is less than the vector's `Simd::N`. - /// - /// # Example - /// - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::u32x4; - /// let mut dest = vec![0; 6]; - /// let v = u32x4::from_array([1, 2, 3, 4]); - /// v.copy_to_slice(&mut dest); - /// assert_eq!(&dest, &[1, 2, 3, 4, 0, 0]); - /// ``` - #[inline] - #[track_caller] - pub fn copy_to_slice(self, slice: &mut [T]) { - assert!( - slice.len() >= Self::LEN, - "slice length must be at least the number of elements" - ); - // SAFETY: We just checked that the slice contains - // at least `N` elements. - unsafe { self.store(slice.as_mut_ptr().cast()) } - } - - /// Reads contiguous elements from `slice`. Elements are read so long as they're in-bounds for - /// the `slice`. Otherwise, the default value for the element type is returned. - /// - /// # Examples - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::Simd; - /// let vec: Vec = vec![10, 11]; - /// - /// let result = Simd::::load_or_default(&vec); - /// assert_eq!(result, Simd::from_array([10, 11, 0, 0])); - /// ``` - #[must_use] - #[inline] - pub fn load_or_default(slice: &[T]) -> Self - where - T: Default, - { - Self::load_or(slice, Default::default()) - } - - /// Reads contiguous elements from `slice`. Elements are read so long as they're in-bounds for - /// the `slice`. Otherwise, the corresponding value from `or` is passed through. - /// - /// # Examples - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::Simd; - /// let vec: Vec = vec![10, 11]; - /// let or = Simd::from_array([-5, -4, -3, -2]); - /// - /// let result = Simd::load_or(&vec, or); - /// assert_eq!(result, Simd::from_array([10, 11, -3, -2])); - /// ``` - #[must_use] - #[inline] - pub fn load_or(slice: &[T], or: Self) -> Self { - Self::load_select(slice, Mask::splat(true), or) - } - - /// Reads contiguous elements from `slice`. Each element is read from memory if its - /// corresponding element in `enable` is `true`. - /// - /// When the element is disabled or out of bounds for the slice, that memory location - /// is not accessed and the corresponding value from `or` is passed through. - /// - /// # Examples - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::{Simd, Mask}; - /// let vec: Vec = vec![10, 11, 12, 13, 14, 15, 16, 17, 18]; - /// let enable = Mask::from_array([true, true, false, true]); - /// let or = Simd::from_array([-5, -4, -3, -2]); - /// - /// let result = Simd::load_select(&vec, enable, or); - /// assert_eq!(result, Simd::from_array([10, 11, -3, 13])); - /// ``` - #[must_use] - #[inline] - pub fn load_select_or_default(slice: &[T], enable: Mask<::Mask, N>) -> Self - where - T: Default, - { - Self::load_select(slice, enable, Default::default()) - } - - /// Reads contiguous elements from `slice`. Each element is read from memory if its - /// corresponding element in `enable` is `true`. - /// - /// When the element is disabled or out of bounds for the slice, that memory location - /// is not accessed and the corresponding value from `or` is passed through. - /// - /// # Examples - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::{Simd, Mask}; - /// let vec: Vec = vec![10, 11, 12, 13, 14, 15, 16, 17, 18]; - /// let enable = Mask::from_array([true, true, false, true]); - /// let or = Simd::from_array([-5, -4, -3, -2]); - /// - /// let result = Simd::load_select(&vec, enable, or); - /// assert_eq!(result, Simd::from_array([10, 11, -3, 13])); - /// ``` - #[must_use] - #[inline] - pub fn load_select( - slice: &[T], - mut enable: Mask<::Mask, N>, - or: Self, - ) -> Self { - enable &= mask_up_to(slice.len()); - // SAFETY: We performed the bounds check by updating the mask. &[T] is properly aligned to - // the element. - unsafe { Self::load_select_ptr(slice.as_ptr(), enable, or) } - } - - /// Reads contiguous elements from `slice`. Each element is read from memory if its - /// corresponding element in `enable` is `true`. - /// - /// When the element is disabled, that memory location is not accessed and the corresponding - /// value from `or` is passed through. - #[must_use] - #[inline] - pub unsafe fn load_select_unchecked( - slice: &[T], - enable: Mask<::Mask, N>, - or: Self, - ) -> Self { - let ptr = slice.as_ptr(); - // SAFETY: The safety of reading elements from `slice` is ensured by the caller. - unsafe { Self::load_select_ptr(ptr, enable, or) } - } - - /// Reads contiguous elements starting at `ptr`. Each element is read from memory if its - /// corresponding element in `enable` is `true`. - /// - /// When the element is disabled, that memory location is not accessed and the corresponding - /// value from `or` is passed through. - #[must_use] - #[inline] - pub unsafe fn load_select_ptr( - ptr: *const T, - enable: Mask<::Mask, N>, - or: Self, - ) -> Self { - // SAFETY: The safety of reading elements through `ptr` is ensured by the caller. - unsafe { core::intrinsics::simd::simd_masked_load(enable.to_int(), ptr, or) } - } - - /// Reads from potentially discontiguous indices in `slice` to construct a SIMD vector. - /// If an index is out-of-bounds, the element is instead selected from the `or` vector. - /// - /// # Examples - /// ``` - /// # #![feature(portable_simd)] - /// # use core::simd::Simd; - /// let vec: Vec = vec![10, 11, 12, 13, 14, 15, 16, 17, 18]; - /// let idxs = Simd::from_array([9, 3, 0, 5]); // Note the index that is out-of-bounds - /// let alt = Simd::from_array([-5, -4, -3, -2]); - /// - /// let result = Simd::gather_or(&vec, idxs, alt); - /// assert_eq!(result, Simd::from_array([-5, 13, 10, 15])); - /// ``` - #[must_use] - #[inline] - pub fn gather_or(slice: &[T], idxs: Simd, or: Self) -> Self { - Self::gather_select(slice, Mask::splat(true), idxs, or) - } - - /// Reads from indices in `slice` to construct a SIMD vector. - /// If an index is out-of-bounds, the element is set to the default given by `T: Default`. - /// - /// # Examples - /// ``` - /// # #![feature(portable_simd)] - /// # use core::simd::Simd; - /// let vec: Vec = vec![10, 11, 12, 13, 14, 15, 16, 17, 18]; - /// let idxs = Simd::from_array([9, 3, 0, 5]); // Note the index that is out-of-bounds - /// - /// let result = Simd::gather_or_default(&vec, idxs); - /// assert_eq!(result, Simd::from_array([0, 13, 10, 15])); - /// ``` - #[must_use] - #[inline] - pub fn gather_or_default(slice: &[T], idxs: Simd) -> Self - where - T: Default, - { - Self::gather_or(slice, idxs, Self::splat(T::default())) - } - - /// Reads from indices in `slice` to construct a SIMD vector. - /// The mask `enable`s all `true` indices and disables all `false` indices. - /// If an index is disabled or is out-of-bounds, the element is selected from the `or` vector. - /// - /// # Examples - /// ``` - /// # #![feature(portable_simd)] - /// # use core::simd::{Simd, Mask}; - /// let vec: Vec = vec![10, 11, 12, 13, 14, 15, 16, 17, 18]; - /// let idxs = Simd::from_array([9, 3, 0, 5]); // Includes an out-of-bounds index - /// let alt = Simd::from_array([-5, -4, -3, -2]); - /// let enable = Mask::from_array([true, true, true, false]); // Includes a masked element - /// - /// let result = Simd::gather_select(&vec, enable, idxs, alt); - /// assert_eq!(result, Simd::from_array([-5, 13, 10, -2])); - /// ``` - #[must_use] - #[inline] - pub fn gather_select( - slice: &[T], - enable: Mask, - idxs: Simd, - or: Self, - ) -> Self { - let enable: Mask = enable & idxs.simd_lt(Simd::splat(slice.len())); - // Safety: We have masked-off out-of-bounds indices. - unsafe { Self::gather_select_unchecked(slice, enable, idxs, or) } - } - - /// Reads from indices in `slice` to construct a SIMD vector. - /// The mask `enable`s all `true` indices and disables all `false` indices. - /// If an index is disabled, the element is selected from the `or` vector. - /// - /// # Safety - /// - /// Calling this function with an `enable`d out-of-bounds index is *[undefined behavior]* - /// even if the resulting value is not used. - /// - /// # Examples - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::{Simd, cmp::SimdPartialOrd, Mask}; - /// let vec: Vec = vec![10, 11, 12, 13, 14, 15, 16, 17, 18]; - /// let idxs = Simd::from_array([9, 3, 0, 5]); // Includes an out-of-bounds index - /// let alt = Simd::from_array([-5, -4, -3, -2]); - /// let enable = Mask::from_array([true, true, true, false]); // Includes a masked element - /// // If this mask was used to gather, it would be unsound. Let's fix that. - /// let enable = enable & idxs.simd_lt(Simd::splat(vec.len())); - /// - /// // The out-of-bounds index has been masked, so it's safe to gather now. - /// let result = unsafe { Simd::gather_select_unchecked(&vec, enable, idxs, alt) }; - /// assert_eq!(result, Simd::from_array([-5, 13, 10, -2])); - /// ``` - /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html - #[must_use] - #[inline] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub unsafe fn gather_select_unchecked( - slice: &[T], - enable: Mask, - idxs: Simd, - or: Self, - ) -> Self { - let base_ptr = Simd::<*const T, N>::splat(slice.as_ptr()); - // Ferris forgive me, I have done pointer arithmetic here. - let ptrs = base_ptr.wrapping_add(idxs); - // Safety: The caller is responsible for determining the indices are okay to read - unsafe { Self::gather_select_ptr(ptrs, enable, or) } - } - - /// Read elementwise from pointers into a SIMD vector. - /// - /// # Safety - /// - /// Each read must satisfy the same conditions as [`core::ptr::read`]. - /// - /// # Example - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::prelude::*; - /// let values = [6, 2, 4, 9]; - /// let offsets = Simd::from_array([1, 0, 0, 3]); - /// let source = Simd::splat(values.as_ptr()).wrapping_add(offsets); - /// let gathered = unsafe { Simd::gather_ptr(source) }; - /// assert_eq!(gathered, Simd::from_array([2, 6, 6, 9])); - /// ``` - #[must_use] - #[inline] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub unsafe fn gather_ptr(source: Simd<*const T, N>) -> Self - where - T: Default, - { - // TODO: add an intrinsic that doesn't use a passthru vector, and remove the T: Default bound - // Safety: The caller is responsible for upholding all invariants - unsafe { Self::gather_select_ptr(source, Mask::splat(true), Self::default()) } - } - - /// Conditionally read elementwise from pointers into a SIMD vector. - /// The mask `enable`s all `true` pointers and disables all `false` pointers. - /// If a pointer is disabled, the element is selected from the `or` vector, - /// and no read is performed. - /// - /// # Safety - /// - /// Enabled elements must satisfy the same conditions as [`core::ptr::read`]. - /// - /// # Example - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::prelude::*; - /// let values = [6, 2, 4, 9]; - /// let enable = Mask::from_array([true, true, false, true]); - /// let offsets = Simd::from_array([1, 0, 0, 3]); - /// let source = Simd::splat(values.as_ptr()).wrapping_add(offsets); - /// let gathered = unsafe { Simd::gather_select_ptr(source, enable, Simd::splat(0)) }; - /// assert_eq!(gathered, Simd::from_array([2, 6, 0, 9])); - /// ``` - #[must_use] - #[inline] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub unsafe fn gather_select_ptr( - source: Simd<*const T, N>, - enable: Mask, - or: Self, - ) -> Self { - // Safety: The caller is responsible for upholding all invariants - unsafe { core::intrinsics::simd::simd_gather(or, source, enable.to_int()) } - } - - /// Conditionally write contiguous elements to `slice`. The `enable` mask controls - /// which elements are written, as long as they're in-bounds of the `slice`. - /// If the element is disabled or out of bounds, no memory access to that location - /// is made. - /// - /// # Examples - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::{Simd, Mask}; - /// let mut arr = [0i32; 4]; - /// let write = Simd::from_array([-5, -4, -3, -2]); - /// let enable = Mask::from_array([false, true, true, true]); - /// - /// write.store_select(&mut arr[..3], enable); - /// assert_eq!(arr, [0, -4, -3, 0]); - /// ``` - #[inline] - pub fn store_select(self, slice: &mut [T], mut enable: Mask<::Mask, N>) { - enable &= mask_up_to(slice.len()); - // SAFETY: We performed the bounds check by updating the mask. &[T] is properly aligned to - // the element. - unsafe { self.store_select_ptr(slice.as_mut_ptr(), enable) } - } - - /// Conditionally write contiguous elements to `slice`. The `enable` mask controls - /// which elements are written. - /// - /// # Safety - /// - /// Every enabled element must be in bounds for the `slice`. - /// - /// # Examples - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::{Simd, Mask}; - /// let mut arr = [0i32; 4]; - /// let write = Simd::from_array([-5, -4, -3, -2]); - /// let enable = Mask::from_array([false, true, true, true]); - /// - /// unsafe { write.store_select_unchecked(&mut arr, enable) }; - /// assert_eq!(arr, [0, -4, -3, -2]); - /// ``` - #[inline] - pub unsafe fn store_select_unchecked( - self, - slice: &mut [T], - enable: Mask<::Mask, N>, - ) { - let ptr = slice.as_mut_ptr(); - // SAFETY: The safety of writing elements in `slice` is ensured by the caller. - unsafe { self.store_select_ptr(ptr, enable) } - } - - /// Conditionally write contiguous elements starting from `ptr`. - /// The `enable` mask controls which elements are written. - /// When disabled, the memory location corresponding to that element is not accessed. - /// - /// # Safety - /// - /// Memory addresses for element are calculated [`pointer::wrapping_offset`] and - /// each enabled element must satisfy the same conditions as [`core::ptr::write`]. - #[inline] - pub unsafe fn store_select_ptr(self, ptr: *mut T, enable: Mask<::Mask, N>) { - // SAFETY: The safety of writing elements through `ptr` is ensured by the caller. - unsafe { core::intrinsics::simd::simd_masked_store(enable.to_int(), ptr, self) } - } - - /// Writes the values in a SIMD vector to potentially discontiguous indices in `slice`. - /// If an index is out-of-bounds, the write is suppressed without panicking. - /// If two elements in the scattered vector would write to the same index - /// only the last element is guaranteed to actually be written. - /// - /// # Examples - /// ``` - /// # #![feature(portable_simd)] - /// # use core::simd::Simd; - /// let mut vec: Vec = vec![10, 11, 12, 13, 14, 15, 16, 17, 18]; - /// let idxs = Simd::from_array([9, 3, 0, 0]); // Note the duplicate index. - /// let vals = Simd::from_array([-27, 82, -41, 124]); - /// - /// vals.scatter(&mut vec, idxs); // two logical writes means the last wins. - /// assert_eq!(vec, vec![124, 11, 12, 82, 14, 15, 16, 17, 18]); - /// ``` - #[inline] - pub fn scatter(self, slice: &mut [T], idxs: Simd) { - self.scatter_select(slice, Mask::splat(true), idxs) - } - - /// Writes values from a SIMD vector to multiple potentially discontiguous indices in `slice`. - /// The mask `enable`s all `true` indices and disables all `false` indices. - /// If an enabled index is out-of-bounds, the write is suppressed without panicking. - /// If two enabled elements in the scattered vector would write to the same index, - /// only the last element is guaranteed to actually be written. - /// - /// # Examples - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::{Simd, Mask}; - /// let mut vec: Vec = vec![10, 11, 12, 13, 14, 15, 16, 17, 18]; - /// let idxs = Simd::from_array([9, 3, 0, 0]); // Includes an out-of-bounds index - /// let vals = Simd::from_array([-27, 82, -41, 124]); - /// let enable = Mask::from_array([true, true, true, false]); // Includes a masked element - /// - /// vals.scatter_select(&mut vec, enable, idxs); // The last write is masked, thus omitted. - /// assert_eq!(vec, vec![-41, 11, 12, 82, 14, 15, 16, 17, 18]); - /// ``` - #[inline] - pub fn scatter_select(self, slice: &mut [T], enable: Mask, idxs: Simd) { - let enable: Mask = enable & idxs.simd_lt(Simd::splat(slice.len())); - // Safety: We have masked-off out-of-bounds indices. - unsafe { self.scatter_select_unchecked(slice, enable, idxs) } - } - - /// Writes values from a SIMD vector to multiple potentially discontiguous indices in `slice`. - /// The mask `enable`s all `true` indices and disables all `false` indices. - /// If two enabled elements in the scattered vector would write to the same index, - /// only the last element is guaranteed to actually be written. - /// - /// # Safety - /// - /// Calling this function with an enabled out-of-bounds index is *[undefined behavior]*, - /// and may lead to memory corruption. - /// - /// # Examples - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::{Simd, cmp::SimdPartialOrd, Mask}; - /// let mut vec: Vec = vec![10, 11, 12, 13, 14, 15, 16, 17, 18]; - /// let idxs = Simd::from_array([9, 3, 0, 0]); - /// let vals = Simd::from_array([-27, 82, -41, 124]); - /// let enable = Mask::from_array([true, true, true, false]); // Masks the final index - /// // If this mask was used to scatter, it would be unsound. Let's fix that. - /// let enable = enable & idxs.simd_lt(Simd::splat(vec.len())); - /// - /// // We have masked the OOB index, so it's safe to scatter now. - /// unsafe { vals.scatter_select_unchecked(&mut vec, enable, idxs); } - /// // The second write to index 0 was masked, thus omitted. - /// assert_eq!(vec, vec![-41, 11, 12, 82, 14, 15, 16, 17, 18]); - /// ``` - /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html - #[inline] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub unsafe fn scatter_select_unchecked( - self, - slice: &mut [T], - enable: Mask, - idxs: Simd, - ) { - // Safety: This block works with *mut T derived from &mut 'a [T], - // which means it is delicate in Rust's borrowing model, circa 2021: - // &mut 'a [T] asserts uniqueness, so deriving &'a [T] invalidates live *mut Ts! - // Even though this block is largely safe methods, it must be exactly this way - // to prevent invalidating the raw ptrs while they're live. - // Thus, entering this block requires all values to use being already ready: - // 0. idxs we want to write to, which are used to construct the mask. - // 1. enable, which depends on an initial &'a [T] and the idxs. - // 2. actual values to scatter (self). - // 3. &mut [T] which will become our base ptr. - unsafe { - // Now Entering ☢️ *mut T Zone - let base_ptr = Simd::<*mut T, N>::splat(slice.as_mut_ptr()); - // Ferris forgive me, I have done pointer arithmetic here. - let ptrs = base_ptr.wrapping_add(idxs); - // The ptrs have been bounds-masked to prevent memory-unsafe writes insha'allah - self.scatter_select_ptr(ptrs, enable); - // Cleared ☢️ *mut T Zone - } - } - - /// Write pointers elementwise into a SIMD vector. - /// - /// # Safety - /// - /// Each write must satisfy the same conditions as [`core::ptr::write`]. - /// - /// # Example - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::{Simd, ptr::SimdMutPtr}; - /// let mut values = [0; 4]; - /// let offset = Simd::from_array([3, 2, 1, 0]); - /// let ptrs = Simd::splat(values.as_mut_ptr()).wrapping_add(offset); - /// unsafe { Simd::from_array([6, 3, 5, 7]).scatter_ptr(ptrs); } - /// assert_eq!(values, [7, 5, 3, 6]); - /// ``` - #[inline] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub unsafe fn scatter_ptr(self, dest: Simd<*mut T, N>) { - // Safety: The caller is responsible for upholding all invariants - unsafe { self.scatter_select_ptr(dest, Mask::splat(true)) } - } - - /// Conditionally write pointers elementwise into a SIMD vector. - /// The mask `enable`s all `true` pointers and disables all `false` pointers. - /// If a pointer is disabled, the write to its pointee is skipped. - /// - /// # Safety - /// - /// Enabled pointers must satisfy the same conditions as [`core::ptr::write`]. - /// - /// # Example - /// ``` - /// # #![feature(portable_simd)] - /// # #[cfg(feature = "as_crate")] use core_simd::simd; - /// # #[cfg(not(feature = "as_crate"))] use core::simd; - /// # use simd::{Mask, Simd, ptr::SimdMutPtr}; - /// let mut values = [0; 4]; - /// let offset = Simd::from_array([3, 2, 1, 0]); - /// let ptrs = Simd::splat(values.as_mut_ptr()).wrapping_add(offset); - /// let enable = Mask::from_array([true, true, false, false]); - /// unsafe { Simd::from_array([6, 3, 5, 7]).scatter_select_ptr(ptrs, enable); } - /// assert_eq!(values, [0, 0, 3, 6]); - /// ``` - #[inline] - #[cfg_attr(miri, track_caller)] // even without panics, this helps for Miri backtraces - pub unsafe fn scatter_select_ptr(self, dest: Simd<*mut T, N>, enable: Mask) { - // Safety: The caller is responsible for upholding all invariants - unsafe { core::intrinsics::simd::simd_scatter(self, dest, enable.to_int()) } - } -} - -impl Copy for Simd -where - LaneCount: SupportedLaneCount, - T: SimdElement, -{ -} - -impl Clone for Simd -where - LaneCount: SupportedLaneCount, - T: SimdElement, -{ - #[inline] - fn clone(&self) -> Self { - *self - } -} - -impl Default for Simd -where - LaneCount: SupportedLaneCount, - T: SimdElement + Default, -{ - #[inline] - fn default() -> Self { - Self::splat(T::default()) - } -} - -impl PartialEq for Simd -where - LaneCount: SupportedLaneCount, - T: SimdElement + PartialEq, -{ - #[inline] - fn eq(&self, other: &Self) -> bool { - // Safety: All SIMD vectors are SimdPartialEq, and the comparison produces a valid mask. - let mask = unsafe { - let tfvec: Simd<::Mask, N> = - core::intrinsics::simd::simd_eq(*self, *other); - Mask::from_int_unchecked(tfvec) - }; - - // Two vectors are equal if all elements are equal when compared elementwise - mask.all() - } - - #[allow(clippy::partialeq_ne_impl)] - #[inline] - fn ne(&self, other: &Self) -> bool { - // Safety: All SIMD vectors are SimdPartialEq, and the comparison produces a valid mask. - let mask = unsafe { - let tfvec: Simd<::Mask, N> = - core::intrinsics::simd::simd_ne(*self, *other); - Mask::from_int_unchecked(tfvec) - }; - - // Two vectors are non-equal if any elements are non-equal when compared elementwise - mask.any() - } -} - -impl PartialOrd for Simd -where - LaneCount: SupportedLaneCount, - T: SimdElement + PartialOrd, -{ - #[inline] - fn partial_cmp(&self, other: &Self) -> Option { - // TODO use SIMD equality - self.to_array().partial_cmp(other.as_ref()) - } -} - -impl Eq for Simd -where - LaneCount: SupportedLaneCount, - T: SimdElement + Eq, -{ -} - -impl Ord for Simd -where - LaneCount: SupportedLaneCount, - T: SimdElement + Ord, -{ - #[inline] - fn cmp(&self, other: &Self) -> core::cmp::Ordering { - // TODO use SIMD equality - self.to_array().cmp(other.as_ref()) - } -} - -impl core::hash::Hash for Simd -where - LaneCount: SupportedLaneCount, - T: SimdElement + core::hash::Hash, -{ - #[inline] - fn hash(&self, state: &mut H) - where - H: core::hash::Hasher, - { - self.as_array().hash(state) - } -} - -// array references -impl AsRef<[T; N]> for Simd -where - LaneCount: SupportedLaneCount, - T: SimdElement, -{ - #[inline] - fn as_ref(&self) -> &[T; N] { - self.as_array() - } -} - -impl AsMut<[T; N]> for Simd -where - LaneCount: SupportedLaneCount, - T: SimdElement, -{ - #[inline] - fn as_mut(&mut self) -> &mut [T; N] { - self.as_mut_array() - } -} - -// slice references -impl AsRef<[T]> for Simd -where - LaneCount: SupportedLaneCount, - T: SimdElement, -{ - #[inline] - fn as_ref(&self) -> &[T] { - self.as_array() - } -} - -impl AsMut<[T]> for Simd -where - LaneCount: SupportedLaneCount, - T: SimdElement, -{ - #[inline] - fn as_mut(&mut self) -> &mut [T] { - self.as_mut_array() - } -} - -// vector/array conversion -impl From<[T; N]> for Simd -where - LaneCount: SupportedLaneCount, - T: SimdElement, -{ - #[inline] - fn from(array: [T; N]) -> Self { - Self::from_array(array) - } -} - -impl From> for [T; N] -where - LaneCount: SupportedLaneCount, - T: SimdElement, -{ - #[inline] - fn from(vector: Simd) -> Self { - vector.to_array() - } -} - -impl TryFrom<&[T]> for Simd -where - LaneCount: SupportedLaneCount, - T: SimdElement, -{ - type Error = core::array::TryFromSliceError; - - #[inline] - fn try_from(slice: &[T]) -> Result { - Ok(Self::from_array(slice.try_into()?)) - } -} - -impl TryFrom<&mut [T]> for Simd -where - LaneCount: SupportedLaneCount, - T: SimdElement, -{ - type Error = core::array::TryFromSliceError; - - #[inline] - fn try_from(slice: &mut [T]) -> Result { - Ok(Self::from_array(slice.try_into()?)) - } -} - -mod sealed { - pub trait Sealed {} -} -use sealed::Sealed; - -/// Marker trait for types that may be used as SIMD vector elements. -/// -/// # Safety -/// This trait, when implemented, asserts the compiler can monomorphize -/// `#[repr(simd)]` structs with the marked type as an element. -/// Strictly, it is valid to impl if the vector will not be miscompiled. -/// Practically, it is user-unfriendly to impl it if the vector won't compile, -/// even when no soundness guarantees are broken by allowing the user to try. -pub unsafe trait SimdElement: Sealed + Copy { - /// The mask element type corresponding to this element type. - type Mask: MaskElement; -} - -impl Sealed for u8 {} - -// Safety: u8 is a valid SIMD element type, and is supported by this API -unsafe impl SimdElement for u8 { - type Mask = i8; -} - -impl Sealed for u16 {} - -// Safety: u16 is a valid SIMD element type, and is supported by this API -unsafe impl SimdElement for u16 { - type Mask = i16; -} - -impl Sealed for u32 {} - -// Safety: u32 is a valid SIMD element type, and is supported by this API -unsafe impl SimdElement for u32 { - type Mask = i32; -} - -impl Sealed for u64 {} - -// Safety: u64 is a valid SIMD element type, and is supported by this API -unsafe impl SimdElement for u64 { - type Mask = i64; -} - -impl Sealed for usize {} - -// Safety: usize is a valid SIMD element type, and is supported by this API -unsafe impl SimdElement for usize { - type Mask = isize; -} - -impl Sealed for i8 {} - -// Safety: i8 is a valid SIMD element type, and is supported by this API -unsafe impl SimdElement for i8 { - type Mask = i8; -} - -impl Sealed for i16 {} - -// Safety: i16 is a valid SIMD element type, and is supported by this API -unsafe impl SimdElement for i16 { - type Mask = i16; -} - -impl Sealed for i32 {} - -// Safety: i32 is a valid SIMD element type, and is supported by this API -unsafe impl SimdElement for i32 { - type Mask = i32; -} - -impl Sealed for i64 {} - -// Safety: i64 is a valid SIMD element type, and is supported by this API -unsafe impl SimdElement for i64 { - type Mask = i64; -} - -impl Sealed for isize {} - -// Safety: isize is a valid SIMD element type, and is supported by this API -unsafe impl SimdElement for isize { - type Mask = isize; -} - -impl Sealed for f32 {} - -// Safety: f32 is a valid SIMD element type, and is supported by this API -unsafe impl SimdElement for f32 { - type Mask = i32; -} - -impl Sealed for f64 {} - -// Safety: f64 is a valid SIMD element type, and is supported by this API -unsafe impl SimdElement for f64 { - type Mask = i64; -} - -impl Sealed for *const T {} - -// Safety: (thin) const pointers are valid SIMD element types, and are supported by this API -// -// Fat pointers may be supported in the future. -unsafe impl SimdElement for *const T -where - T: core::ptr::Pointee, -{ - type Mask = isize; -} - -impl Sealed for *mut T {} - -// Safety: (thin) mut pointers are valid SIMD element types, and are supported by this API -// -// Fat pointers may be supported in the future. -unsafe impl SimdElement for *mut T -where - T: core::ptr::Pointee, -{ - type Mask = isize; -} - -#[inline] -fn lane_indices() -> Simd -where - LaneCount: SupportedLaneCount, -{ - let mut index = [0; N]; - for i in 0..N { - index[i] = i; - } - Simd::from_array(index) -} - -#[inline] -fn mask_up_to(len: usize) -> Mask -where - LaneCount: SupportedLaneCount, - M: MaskElement, -{ - let index = lane_indices::(); - let max_value: u64 = M::max_unsigned(); - macro_rules! case { - ($ty:ty) => { - if N < <$ty>::MAX as usize && max_value as $ty as u64 == max_value { - return index.cast().simd_lt(Simd::splat(len.min(N) as $ty)).cast(); - } - }; - } - case!(u8); - case!(u16); - case!(u32); - case!(u64); - index.simd_lt(Simd::splat(len)).cast() -} diff --git a/library/portable-simd/crates/core_simd/src/vendor.rs b/library/portable-simd/crates/core_simd/src/vendor.rs deleted file mode 100644 index 1a34a3a8de5c4..0000000000000 --- a/library/portable-simd/crates/core_simd/src/vendor.rs +++ /dev/null @@ -1,31 +0,0 @@ -/// Provides implementations of `From<$a> for $b` and `From<$b> for $a` that transmutes the value. -#[allow(unused)] -macro_rules! from_transmute { - { unsafe $a:ty => $b:ty } => { - from_transmute!{ @impl $a => $b } - from_transmute!{ @impl $b => $a } - }; - { @impl $from:ty => $to:ty } => { - impl core::convert::From<$from> for $to { - #[inline] - fn from(value: $from) -> $to { - // Safety: transmuting between vectors is safe, but the caller of this macro - // checks the invariants - unsafe { core::mem::transmute(value) } - } - } - }; -} - -/// Conversions to x86's SIMD types. -#[cfg(any(target_arch = "x86", target_arch = "x86_64"))] -mod x86; - -#[cfg(target_arch = "wasm32")] -mod wasm32; - -#[cfg(any(target_arch = "aarch64", target_arch = "arm64ec", target_arch = "arm",))] -mod arm; - -#[cfg(any(target_arch = "powerpc", target_arch = "powerpc64"))] -mod powerpc; diff --git a/library/portable-simd/crates/core_simd/src/vendor/arm.rs b/library/portable-simd/crates/core_simd/src/vendor/arm.rs deleted file mode 100644 index f8878d11f094d..0000000000000 --- a/library/portable-simd/crates/core_simd/src/vendor/arm.rs +++ /dev/null @@ -1,83 +0,0 @@ -#![allow(unused)] -use crate::simd::*; - -#[cfg(target_arch = "arm")] -use core::arch::arm::*; - -#[cfg(any(target_arch = "aarch64", target_arch = "arm64ec"))] -use core::arch::aarch64::*; - -#[cfg(all( - any( - target_arch = "aarch64", - target_arch = "arm64ec", - all(target_arch = "arm", target_feature = "v7"), - ), - target_endian = "little" -))] -mod neon { - use super::*; - - from_transmute! { unsafe f32x2 => float32x2_t } - from_transmute! { unsafe f32x4 => float32x4_t } - - from_transmute! { unsafe u8x8 => uint8x8_t } - from_transmute! { unsafe u8x16 => uint8x16_t } - from_transmute! { unsafe i8x8 => int8x8_t } - from_transmute! { unsafe i8x16 => int8x16_t } - from_transmute! { unsafe u8x8 => poly8x8_t } - from_transmute! { unsafe u8x16 => poly8x16_t } - - from_transmute! { unsafe u16x4 => uint16x4_t } - from_transmute! { unsafe u16x8 => uint16x8_t } - from_transmute! { unsafe i16x4 => int16x4_t } - from_transmute! { unsafe i16x8 => int16x8_t } - from_transmute! { unsafe u16x4 => poly16x4_t } - from_transmute! { unsafe u16x8 => poly16x8_t } - - from_transmute! { unsafe u32x2 => uint32x2_t } - from_transmute! { unsafe u32x4 => uint32x4_t } - from_transmute! { unsafe i32x2 => int32x2_t } - from_transmute! { unsafe i32x4 => int32x4_t } - - from_transmute! { unsafe Simd => uint64x1_t } - from_transmute! { unsafe u64x2 => uint64x2_t } - from_transmute! { unsafe Simd => int64x1_t } - from_transmute! { unsafe i64x2 => int64x2_t } - from_transmute! { unsafe Simd => poly64x1_t } - from_transmute! { unsafe u64x2 => poly64x2_t } -} - -#[cfg(any( - all(target_feature = "v5te", not(target_feature = "mclass")), - all(target_feature = "mclass", target_feature = "dsp"), -))] -mod dsp { - use super::*; - - from_transmute! { unsafe Simd => uint16x2_t } - from_transmute! { unsafe Simd => int16x2_t } -} - -#[cfg(any( - all(target_feature = "v6", not(target_feature = "mclass")), - all(target_feature = "mclass", target_feature = "dsp"), -))] -mod simd32 { - use super::*; - - from_transmute! { unsafe Simd => uint8x4_t } - from_transmute! { unsafe Simd => int8x4_t } -} - -#[cfg(all( - any(target_arch = "aarch64", target_arch = "arm64ec"), - target_endian = "little" -))] -mod aarch64 { - use super::neon::*; - use super::*; - - from_transmute! { unsafe Simd => float64x1_t } - from_transmute! { unsafe f64x2 => float64x2_t } -} diff --git a/library/portable-simd/crates/core_simd/src/vendor/powerpc.rs b/library/portable-simd/crates/core_simd/src/vendor/powerpc.rs deleted file mode 100644 index 92f97d471b6e8..0000000000000 --- a/library/portable-simd/crates/core_simd/src/vendor/powerpc.rs +++ /dev/null @@ -1,11 +0,0 @@ -use crate::simd::*; - -#[cfg(target_arch = "powerpc")] -use core::arch::powerpc::*; - -#[cfg(target_arch = "powerpc64")] -use core::arch::powerpc64::*; - -from_transmute! { unsafe f64x2 => vector_double } -from_transmute! { unsafe i64x2 => vector_signed_long } -from_transmute! { unsafe u64x2 => vector_unsigned_long } diff --git a/library/portable-simd/crates/core_simd/src/vendor/wasm32.rs b/library/portable-simd/crates/core_simd/src/vendor/wasm32.rs deleted file mode 100644 index ef3baf885b0fb..0000000000000 --- a/library/portable-simd/crates/core_simd/src/vendor/wasm32.rs +++ /dev/null @@ -1,30 +0,0 @@ -use crate::simd::*; -use core::arch::wasm32::v128; - -from_transmute! { unsafe u8x16 => v128 } -from_transmute! { unsafe i8x16 => v128 } - -from_transmute! { unsafe u16x8 => v128 } -from_transmute! { unsafe i16x8 => v128 } - -from_transmute! { unsafe u32x4 => v128 } -from_transmute! { unsafe i32x4 => v128 } -from_transmute! { unsafe f32x4 => v128 } - -from_transmute! { unsafe u64x2 => v128 } -from_transmute! { unsafe i64x2 => v128 } -from_transmute! { unsafe f64x2 => v128 } - -#[cfg(target_pointer_width = "32")] -mod p32 { - use super::*; - from_transmute! { unsafe usizex4 => v128 } - from_transmute! { unsafe isizex4 => v128 } -} - -#[cfg(target_pointer_width = "64")] -mod p64 { - use super::*; - from_transmute! { unsafe usizex2 => v128 } - from_transmute! { unsafe isizex2 => v128 } -} diff --git a/library/portable-simd/crates/core_simd/src/vendor/x86.rs b/library/portable-simd/crates/core_simd/src/vendor/x86.rs deleted file mode 100644 index 66aaf90eef597..0000000000000 --- a/library/portable-simd/crates/core_simd/src/vendor/x86.rs +++ /dev/null @@ -1,63 +0,0 @@ -use crate::simd::*; - -#[cfg(target_arch = "x86")] -use core::arch::x86::*; - -#[cfg(target_arch = "x86_64")] -use core::arch::x86_64::*; - -from_transmute! { unsafe u8x16 => __m128i } -from_transmute! { unsafe u8x32 => __m256i } -from_transmute! { unsafe u8x64 => __m512i } -from_transmute! { unsafe i8x16 => __m128i } -from_transmute! { unsafe i8x32 => __m256i } -from_transmute! { unsafe i8x64 => __m512i } - -from_transmute! { unsafe u16x8 => __m128i } -from_transmute! { unsafe u16x16 => __m256i } -from_transmute! { unsafe u16x32 => __m512i } -from_transmute! { unsafe i16x8 => __m128i } -from_transmute! { unsafe i16x16 => __m256i } -from_transmute! { unsafe i16x32 => __m512i } - -from_transmute! { unsafe u32x4 => __m128i } -from_transmute! { unsafe u32x8 => __m256i } -from_transmute! { unsafe u32x16 => __m512i } -from_transmute! { unsafe i32x4 => __m128i } -from_transmute! { unsafe i32x8 => __m256i } -from_transmute! { unsafe i32x16 => __m512i } -from_transmute! { unsafe f32x4 => __m128 } -from_transmute! { unsafe f32x8 => __m256 } -from_transmute! { unsafe f32x16 => __m512 } - -from_transmute! { unsafe u64x2 => __m128i } -from_transmute! { unsafe u64x4 => __m256i } -from_transmute! { unsafe u64x8 => __m512i } -from_transmute! { unsafe i64x2 => __m128i } -from_transmute! { unsafe i64x4 => __m256i } -from_transmute! { unsafe i64x8 => __m512i } -from_transmute! { unsafe f64x2 => __m128d } -from_transmute! { unsafe f64x4 => __m256d } -from_transmute! { unsafe f64x8 => __m512d } - -#[cfg(target_pointer_width = "32")] -mod p32 { - use super::*; - from_transmute! { unsafe usizex4 => __m128i } - from_transmute! { unsafe usizex8 => __m256i } - from_transmute! { unsafe Simd => __m512i } - from_transmute! { unsafe isizex4 => __m128i } - from_transmute! { unsafe isizex8 => __m256i } - from_transmute! { unsafe Simd => __m512i } -} - -#[cfg(target_pointer_width = "64")] -mod p64 { - use super::*; - from_transmute! { unsafe usizex2 => __m128i } - from_transmute! { unsafe usizex4 => __m256i } - from_transmute! { unsafe usizex8 => __m512i } - from_transmute! { unsafe isizex2 => __m128i } - from_transmute! { unsafe isizex4 => __m256i } - from_transmute! { unsafe isizex8 => __m512i } -} diff --git a/library/portable-simd/crates/core_simd/tests/autoderef.rs b/library/portable-simd/crates/core_simd/tests/autoderef.rs deleted file mode 100644 index 3181826ef59a6..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/autoderef.rs +++ /dev/null @@ -1,22 +0,0 @@ -// Test that we handle all our "auto-deref" cases correctly. -#![feature(portable_simd)] -use core_simd::simd::f32x4; - -#[cfg(target_arch = "wasm32")] -use wasm_bindgen_test::*; - -#[cfg(target_arch = "wasm32")] -wasm_bindgen_test_configure!(run_in_browser); - -#[test] -#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] -fn deref() { - let x = f32x4::splat(1.0); - let y = f32x4::splat(2.0); - let a = &x; - let b = &y; - assert_eq!(f32x4::splat(3.0), x + y); - assert_eq!(f32x4::splat(3.0), x + b); - assert_eq!(f32x4::splat(3.0), a + y); - assert_eq!(f32x4::splat(3.0), a + b); -} diff --git a/library/portable-simd/crates/core_simd/tests/cast.rs b/library/portable-simd/crates/core_simd/tests/cast.rs deleted file mode 100644 index 185e1945faa2f..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/cast.rs +++ /dev/null @@ -1,38 +0,0 @@ -#![feature(portable_simd)] -macro_rules! cast_types { - ($start:ident, $($target:ident),*) => { - mod $start { - #[allow(unused)] - use core_simd::simd::prelude::*; - type Vector = Simd<$start, N>; - $( - mod $target { - use super::*; - test_helpers::test_lanes! { - fn cast_as() { - test_helpers::test_unary_elementwise( - &Vector::::cast::<$target>, - &|x| x as $target, - &|_| true, - ) - } - } - } - )* - } - }; -} - -// The hypothesis is that widening conversions aren't terribly interesting. -cast_types!(f32, f64, i8, u8, usize, isize); -cast_types!(f64, f32, i8, u8, usize, isize); -cast_types!(i8, u8, f32); -cast_types!(u8, i8, f32); -cast_types!(i16, u16, i8, u8, f32); -cast_types!(u16, i16, i8, u8, f32); -cast_types!(i32, u32, i8, u8, f32, f64); -cast_types!(u32, i32, i8, u8, f32, f64); -cast_types!(i64, u64, i8, u8, isize, usize, f32, f64); -cast_types!(u64, i64, i8, u8, isize, usize, f32, f64); -cast_types!(isize, usize, i8, u8, f32, f64); -cast_types!(usize, isize, i8, u8, f32, f64); diff --git a/library/portable-simd/crates/core_simd/tests/f32_ops.rs b/library/portable-simd/crates/core_simd/tests/f32_ops.rs deleted file mode 100644 index 414a832b1be41..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/f32_ops.rs +++ /dev/null @@ -1,5 +0,0 @@ -#![feature(portable_simd)] - -#[macro_use] -mod ops_macros; -impl_float_tests! { f32, i32 } diff --git a/library/portable-simd/crates/core_simd/tests/f64_ops.rs b/library/portable-simd/crates/core_simd/tests/f64_ops.rs deleted file mode 100644 index e0a1fa33f3327..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/f64_ops.rs +++ /dev/null @@ -1,5 +0,0 @@ -#![feature(portable_simd)] - -#[macro_use] -mod ops_macros; -impl_float_tests! { f64, i64 } diff --git a/library/portable-simd/crates/core_simd/tests/i16_ops.rs b/library/portable-simd/crates/core_simd/tests/i16_ops.rs deleted file mode 100644 index f6c5d74fbbcc6..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/i16_ops.rs +++ /dev/null @@ -1,5 +0,0 @@ -#![feature(portable_simd)] - -#[macro_use] -mod ops_macros; -impl_signed_tests! { i16 } diff --git a/library/portable-simd/crates/core_simd/tests/i32_ops.rs b/library/portable-simd/crates/core_simd/tests/i32_ops.rs deleted file mode 100644 index 69a831c52a3fa..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/i32_ops.rs +++ /dev/null @@ -1,5 +0,0 @@ -#![feature(portable_simd)] - -#[macro_use] -mod ops_macros; -impl_signed_tests! { i32 } diff --git a/library/portable-simd/crates/core_simd/tests/i64_ops.rs b/library/portable-simd/crates/core_simd/tests/i64_ops.rs deleted file mode 100644 index 37ac08117424c..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/i64_ops.rs +++ /dev/null @@ -1,5 +0,0 @@ -#![feature(portable_simd)] - -#[macro_use] -mod ops_macros; -impl_signed_tests! { i64 } diff --git a/library/portable-simd/crates/core_simd/tests/i8_ops.rs b/library/portable-simd/crates/core_simd/tests/i8_ops.rs deleted file mode 100644 index 11e4a5cd6a9a7..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/i8_ops.rs +++ /dev/null @@ -1,5 +0,0 @@ -#![feature(portable_simd)] - -#[macro_use] -mod ops_macros; -impl_signed_tests! { i8 } diff --git a/library/portable-simd/crates/core_simd/tests/isize_ops.rs b/library/portable-simd/crates/core_simd/tests/isize_ops.rs deleted file mode 100644 index 5cc9de2b7ff82..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/isize_ops.rs +++ /dev/null @@ -1,5 +0,0 @@ -#![feature(portable_simd)] - -#[macro_use] -mod ops_macros; -impl_signed_tests! { isize } diff --git a/library/portable-simd/crates/core_simd/tests/mask_ops.rs b/library/portable-simd/crates/core_simd/tests/mask_ops.rs deleted file mode 100644 index f113b50cb769d..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/mask_ops.rs +++ /dev/null @@ -1,3 +0,0 @@ -#![feature(portable_simd)] - -mod mask_ops_impl; diff --git a/library/portable-simd/crates/core_simd/tests/mask_ops_impl/mask16.rs b/library/portable-simd/crates/core_simd/tests/mask_ops_impl/mask16.rs deleted file mode 100644 index 0fe82fa680479..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/mask_ops_impl/mask16.rs +++ /dev/null @@ -1,4 +0,0 @@ -mask_tests! { mask16x4, 4 } -mask_tests! { mask16x8, 8 } -mask_tests! { mask16x16, 16 } -mask_tests! { mask16x32, 32 } diff --git a/library/portable-simd/crates/core_simd/tests/mask_ops_impl/mask32.rs b/library/portable-simd/crates/core_simd/tests/mask_ops_impl/mask32.rs deleted file mode 100644 index 66d987a43ce83..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/mask_ops_impl/mask32.rs +++ /dev/null @@ -1,4 +0,0 @@ -mask_tests! { mask32x2, 2 } -mask_tests! { mask32x4, 4 } -mask_tests! { mask32x8, 8 } -mask_tests! { mask32x16, 16 } diff --git a/library/portable-simd/crates/core_simd/tests/mask_ops_impl/mask64.rs b/library/portable-simd/crates/core_simd/tests/mask_ops_impl/mask64.rs deleted file mode 100644 index a1f1f67b23887..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/mask_ops_impl/mask64.rs +++ /dev/null @@ -1,3 +0,0 @@ -mask_tests! { mask64x2, 2 } -mask_tests! { mask64x4, 4 } -mask_tests! { mask64x8, 8 } diff --git a/library/portable-simd/crates/core_simd/tests/mask_ops_impl/mask8.rs b/library/portable-simd/crates/core_simd/tests/mask_ops_impl/mask8.rs deleted file mode 100644 index 9c06fbc0411d2..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/mask_ops_impl/mask8.rs +++ /dev/null @@ -1,3 +0,0 @@ -mask_tests! { mask8x8, 8 } -mask_tests! { mask8x16, 16 } -mask_tests! { mask8x32, 32 } diff --git a/library/portable-simd/crates/core_simd/tests/mask_ops_impl/mask_macros.rs b/library/portable-simd/crates/core_simd/tests/mask_ops_impl/mask_macros.rs deleted file mode 100644 index faafa5fa51f18..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/mask_ops_impl/mask_macros.rs +++ /dev/null @@ -1,225 +0,0 @@ -macro_rules! mask_tests { - { $vector:ident, $lanes:literal } => { - #[cfg(test)] - mod $vector { - use core_simd::simd::$vector as Vector; - const LANES: usize = $lanes; - - #[cfg(target_arch = "wasm32")] - use wasm_bindgen_test::*; - - #[cfg(target_arch = "wasm32")] - wasm_bindgen_test_configure!(run_in_browser); - - fn from_slice(slice: &[bool]) -> Vector { - let mut value = Vector::default(); - for (i, b) in slice.iter().take(LANES).enumerate() { - value.set(i, *b); - } - value - } - - fn apply_unary_lanewise(x: Vector, f: impl Fn(bool) -> bool) -> Vector { - let mut value = Vector::default(); - for i in 0..LANES { - value.set(i, f(x.test(i))); - } - value - } - - fn apply_binary_lanewise(x: Vector, y: Vector, f: impl Fn(bool, bool) -> bool) -> Vector { - let mut value = Vector::default(); - for i in 0..LANES { - value.set(i, f(x.test(i), y.test(i))); - } - value - } - - fn apply_binary_scalar_lhs_lanewise(x: bool, mut y: Vector, f: impl Fn(bool, bool) -> bool) -> Vector { - for i in 0..LANES { - y.set(i, f(x, y.test(i))); - } - y - } - - fn apply_binary_scalar_rhs_lanewise(mut x: Vector, y: bool, f: impl Fn(bool, bool) -> bool) -> Vector { - for i in 0..LANES { - x.set(i, f(x.test(i), y)); - } - x - } - - const A: [bool; 64] = [ - false, true, false, true, false, false, true, true, - false, true, false, true, false, false, true, true, - false, true, false, true, false, false, true, true, - false, true, false, true, false, false, true, true, - false, true, false, true, false, false, true, true, - false, true, false, true, false, false, true, true, - false, true, false, true, false, false, true, true, - false, true, false, true, false, false, true, true, - ]; - const B: [bool; 64] = [ - false, false, true, true, false, true, false, true, - false, false, true, true, false, true, false, true, - false, false, true, true, false, true, false, true, - false, false, true, true, false, true, false, true, - false, false, true, true, false, true, false, true, - false, false, true, true, false, true, false, true, - false, false, true, true, false, true, false, true, - false, false, true, true, false, true, false, true, - ]; - - #[test] - #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] - fn bitand() { - let a = from_slice(&A); - let b = from_slice(&B); - let expected = apply_binary_lanewise(a, b, core::ops::BitAnd::bitand); - assert_eq!(a & b, expected); - } - - #[test] - #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] - fn bitand_assign() { - let mut a = from_slice(&A); - let b = from_slice(&B); - let expected = apply_binary_lanewise(a, b, core::ops::BitAnd::bitand); - a &= b; - assert_eq!(a, expected); - } - - #[test] - #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] - fn bitand_scalar_rhs() { - let a = from_slice(&A); - let expected = a; - assert_eq!(a & true, expected); - assert_eq!(a & false, Vector::splat(false)); - } - - #[test] - #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] - fn bitand_scalar_lhs() { - let a = from_slice(&A); - let expected = a; - assert_eq!(true & a, expected); - assert_eq!(false & a, Vector::splat(false)); - } - - #[test] - #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] - fn bitand_assign_scalar() { - let mut a = from_slice(&A); - let expected = a; - a &= true; - assert_eq!(a, expected); - a &= false; - assert_eq!(a, Vector::splat(false)); - } - - #[test] - #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] - fn bitor() { - let a = from_slice(&A); - let b = from_slice(&B); - let expected = apply_binary_lanewise(a, b, core::ops::BitOr::bitor); - assert_eq!(a | b, expected); - } - - #[test] - #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] - fn bitor_assign() { - let mut a = from_slice(&A); - let b = from_slice(&B); - let expected = apply_binary_lanewise(a, b, core::ops::BitOr::bitor); - a |= b; - assert_eq!(a, expected); - } - - #[test] - #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] - fn bitor_scalar_rhs() { - let a = from_slice(&A); - assert_eq!(a | false, a); - assert_eq!(a | true, Vector::splat(true)); - } - - #[test] - #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] - fn bitor_scalar_lhs() { - let a = from_slice(&A); - assert_eq!(false | a, a); - assert_eq!(true | a, Vector::splat(true)); - } - - #[test] - #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] - fn bitor_assign_scalar() { - let mut a = from_slice(&A); - let expected = a; - a |= false; - assert_eq!(a, expected); - a |= true; - assert_eq!(a, Vector::splat(true)); - } - - #[test] - #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] - fn bitxor() { - let a = from_slice(&A); - let b = from_slice(&B); - let expected = apply_binary_lanewise(a, b, core::ops::BitXor::bitxor); - assert_eq!(a ^ b, expected); - } - - #[test] - #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] - fn bitxor_assign() { - let mut a = from_slice(&A); - let b = from_slice(&B); - let expected = apply_binary_lanewise(a, b, core::ops::BitXor::bitxor); - a ^= b; - assert_eq!(a, expected); - } - - #[test] - #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] - fn bitxor_scalar_rhs() { - let a = from_slice(&A); - let expected = apply_binary_scalar_rhs_lanewise(a, true, core::ops::BitXor::bitxor); - assert_eq!(a ^ false, a); - assert_eq!(a ^ true, expected); - } - - #[test] - #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] - fn bitxor_scalar_lhs() { - let a = from_slice(&A); - let expected = apply_binary_scalar_lhs_lanewise(true, a, core::ops::BitXor::bitxor); - assert_eq!(false ^ a, a); - assert_eq!(true ^ a, expected); - } - - #[test] - #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] - fn bitxor_assign_scalar() { - let mut a = from_slice(&A); - let expected_unset = a; - let expected_set = apply_binary_scalar_rhs_lanewise(a, true, core::ops::BitXor::bitxor); - a ^= false; - assert_eq!(a, expected_unset); - a ^= true; - assert_eq!(a, expected_set); - } - - #[test] - #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] - fn not() { - let v = from_slice(&A); - let expected = apply_unary_lanewise(v, core::ops::Not::not); - assert_eq!(!v, expected); - } - } - } -} diff --git a/library/portable-simd/crates/core_simd/tests/mask_ops_impl/masksize.rs b/library/portable-simd/crates/core_simd/tests/mask_ops_impl/masksize.rs deleted file mode 100644 index e0a44d870ca56..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/mask_ops_impl/masksize.rs +++ /dev/null @@ -1,3 +0,0 @@ -mask_tests! { masksizex2, 2 } -mask_tests! { masksizex4, 4 } -mask_tests! { masksizex8, 8 } diff --git a/library/portable-simd/crates/core_simd/tests/mask_ops_impl/mod.rs b/library/portable-simd/crates/core_simd/tests/mask_ops_impl/mod.rs deleted file mode 100644 index b9ec8462a052f..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/mask_ops_impl/mod.rs +++ /dev/null @@ -1,9 +0,0 @@ -#[macro_use] -mod mask_macros; - -#[rustfmt::skip] -mod mask8; -mod mask16; -mod mask32; -mod mask64; -mod masksize; diff --git a/library/portable-simd/crates/core_simd/tests/masked_load_store.rs b/library/portable-simd/crates/core_simd/tests/masked_load_store.rs deleted file mode 100644 index 3d38658e945f7..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/masked_load_store.rs +++ /dev/null @@ -1,35 +0,0 @@ -#![feature(portable_simd)] -use core_simd::simd::prelude::*; - -#[cfg(target_arch = "wasm32")] -use wasm_bindgen_test::*; - -#[cfg(target_arch = "wasm32")] -wasm_bindgen_test_configure!(run_in_browser); - -#[test] -#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] -fn masked_load_store() { - let mut arr = [u8::MAX; 7]; - - u8x4::splat(0).store_select(&mut arr[5..], Mask::from_array([false, true, false, true])); - // write to index 8 is OOB and dropped - assert_eq!(arr, [255u8, 255, 255, 255, 255, 255, 0]); - - u8x4::from_array([0, 1, 2, 3]).store_select(&mut arr[1..], Mask::splat(true)); - assert_eq!(arr, [255u8, 0, 1, 2, 3, 255, 0]); - - // read from index 8 is OOB and dropped - assert_eq!( - u8x4::load_or(&arr[4..], u8x4::splat(42)), - u8x4::from_array([3, 255, 0, 42]) - ); - assert_eq!( - u8x4::load_select( - &arr[4..], - Mask::from_array([true, false, true, true]), - u8x4::splat(42) - ), - u8x4::from_array([3, 42, 0, 42]) - ); -} diff --git a/library/portable-simd/crates/core_simd/tests/masks.rs b/library/portable-simd/crates/core_simd/tests/masks.rs deleted file mode 100644 index fc6a3476b7c60..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/masks.rs +++ /dev/null @@ -1,199 +0,0 @@ -#![feature(portable_simd)] - -#[cfg(target_arch = "wasm32")] -use wasm_bindgen_test::*; - -#[cfg(target_arch = "wasm32")] -wasm_bindgen_test_configure!(run_in_browser); - -macro_rules! test_mask_api { - { $type:ident } => { - #[allow(non_snake_case)] - mod $type { - #[cfg(target_arch = "wasm32")] - use wasm_bindgen_test::*; - - use core_simd::simd::Mask; - - #[test] - #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] - fn set_and_test() { - let values = [true, false, false, true, false, false, true, false]; - let mut mask = Mask::<$type, 8>::splat(false); - for (lane, value) in values.iter().copied().enumerate() { - mask.set(lane, value); - } - for (lane, value) in values.iter().copied().enumerate() { - assert_eq!(mask.test(lane), value); - } - } - - #[test] - #[should_panic] - fn set_invalid_lane() { - let mut mask = Mask::<$type, 8>::splat(false); - mask.set(8, true); - let _ = mask; - } - - #[test] - #[should_panic] - fn test_invalid_lane() { - let mask = Mask::<$type, 8>::splat(false); - let _ = mask.test(8); - } - - #[test] - fn any() { - assert!(!Mask::<$type, 8>::splat(false).any()); - assert!(Mask::<$type, 8>::splat(true).any()); - let mut v = Mask::<$type, 8>::splat(false); - v.set(2, true); - assert!(v.any()); - } - - #[test] - fn all() { - assert!(!Mask::<$type, 8>::splat(false).all()); - assert!(Mask::<$type, 8>::splat(true).all()); - let mut v = Mask::<$type, 8>::splat(false); - v.set(2, true); - assert!(!v.all()); - } - - #[test] - fn roundtrip_int_conversion() { - let values = [true, false, false, true, false, false, true, false]; - let mask = Mask::<$type, 8>::from_array(values); - let int = mask.to_int(); - assert_eq!(int.to_array(), [-1, 0, 0, -1, 0, 0, -1, 0]); - assert_eq!(Mask::<$type, 8>::from_int(int), mask); - } - - #[test] - fn roundtrip_bitmask_conversion() { - let values = [ - true, false, false, true, false, false, true, false, - true, true, false, false, false, false, false, true, - ]; - let mask = Mask::<$type, 16>::from_array(values); - let bitmask = mask.to_bitmask(); - assert_eq!(bitmask, 0b1000001101001001); - assert_eq!(Mask::<$type, 16>::from_bitmask(bitmask), mask); - } - - #[test] - fn roundtrip_bitmask_conversion_short() { - let values = [ - false, false, false, true, - ]; - let mask = Mask::<$type, 4>::from_array(values); - let bitmask = mask.to_bitmask(); - assert_eq!(bitmask, 0b1000); - assert_eq!(Mask::<$type, 4>::from_bitmask(bitmask), mask); - - let values = [true, false]; - let mask = Mask::<$type, 2>::from_array(values); - let bitmask = mask.to_bitmask(); - assert_eq!(bitmask, 0b01); - assert_eq!(Mask::<$type, 2>::from_bitmask(bitmask), mask); - } - - #[cfg(feature = "all_lane_counts")] - #[test] - fn roundtrip_bitmask_conversion_odd() { - let values = [ - true, false, true, false, true, true, false, false, false, true, true, - ]; - let mask = Mask::<$type, 11>::from_array(values); - let bitmask = mask.to_bitmask(); - assert_eq!(bitmask, 0b11000110101); - assert_eq!(Mask::<$type, 11>::from_bitmask(bitmask), mask); - } - - - #[test] - fn cast() { - fn cast_impl() - where - Mask<$type, 8>: Into>, - { - let values = [true, false, false, true, false, false, true, false]; - let mask = Mask::<$type, 8>::from_array(values); - - let cast_mask = mask.cast::(); - assert_eq!(values, cast_mask.to_array()); - - let into_mask: Mask = mask.into(); - assert_eq!(values, into_mask.to_array()); - } - - cast_impl::(); - cast_impl::(); - cast_impl::(); - cast_impl::(); - cast_impl::(); - } - - #[test] - fn roundtrip_bitmask_vector_conversion() { - use core_simd::simd::ToBytes; - let values = [ - true, false, false, true, false, false, true, false, - true, true, false, false, false, false, false, true, - ]; - let mask = Mask::<$type, 16>::from_array(values); - let bitmask = mask.to_bitmask_vector(); - assert_eq!(bitmask.resize::<2>(0).to_ne_bytes()[..2], [0b01001001, 0b10000011]); - assert_eq!(Mask::<$type, 16>::from_bitmask_vector(bitmask), mask); - } - - // rust-lang/portable-simd#379 - #[test] - fn roundtrip_bitmask_vector_conversion_small() { - use core_simd::simd::ToBytes; - let values = [ - true, false, true, true - ]; - let mask = Mask::<$type, 4>::from_array(values); - let bitmask = mask.to_bitmask_vector(); - assert_eq!(bitmask.resize::<1>(0).to_ne_bytes()[0], 0b00001101); - assert_eq!(Mask::<$type, 4>::from_bitmask_vector(bitmask), mask); - } - - /* FIXME doesn't work with non-powers-of-two, yet - // rust-lang/portable-simd#379 - #[cfg(feature = "all_lane_counts")] - #[test] - fn roundtrip_bitmask_vector_conversion_odd() { - use core_simd::simd::ToBytes; - let values = [ - true, false, true, false, true, true, false, false, false, true, true, - ]; - let mask = Mask::<$type, 11>::from_array(values); - let bitmask = mask.to_bitmask_vector(); - assert_eq!(bitmask.resize::<2>(0).to_ne_bytes()[..2], [0b00110101, 0b00000110]); - assert_eq!(Mask::<$type, 11>::from_bitmask_vector(bitmask), mask); - } - */ - } - } -} - -mod mask_api { - test_mask_api! { i8 } - test_mask_api! { i16 } - test_mask_api! { i32 } - test_mask_api! { i64 } - test_mask_api! { isize } -} - -#[test] -fn convert() { - use core_simd::simd::Mask; - let values = [true, false, false, true, false, false, true, false]; - assert_eq!( - Mask::::from_array(values), - Mask::::from_array(values).into() - ); -} diff --git a/library/portable-simd/crates/core_simd/tests/ops_macros.rs b/library/portable-simd/crates/core_simd/tests/ops_macros.rs deleted file mode 100644 index aa565a137527e..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/ops_macros.rs +++ /dev/null @@ -1,718 +0,0 @@ -/// Implements a test on a unary operation using proptest. -/// -/// Compares the vector operation to the equivalent scalar operation. -#[macro_export] -macro_rules! impl_unary_op_test { - { $scalar:ty, $trait:ident :: $fn:ident, $scalar_fn:expr } => { - test_helpers::test_lanes! { - fn $fn() { - test_helpers::test_unary_elementwise_flush_subnormals( - & as core::ops::$trait>::$fn, - &$scalar_fn, - &|_| true, - ); - } - } - }; - { $scalar:ty, $trait:ident :: $fn:ident } => { - impl_unary_op_test! { $scalar, $trait::$fn, <$scalar as core::ops::$trait>::$fn } - }; -} - -/// Implements a test on a binary operation using proptest. -/// -/// Compares the vector operation to the equivalent scalar operation. -#[macro_export] -macro_rules! impl_binary_op_test { - { $scalar:ty, $trait:ident :: $fn:ident, $trait_assign:ident :: $fn_assign:ident, $scalar_fn:expr } => { - mod $fn { - use super::*; - use core_simd::simd::Simd; - - test_helpers::test_lanes! { - fn normal() { - test_helpers::test_binary_elementwise_flush_subnormals( - & as core::ops::$trait>::$fn, - &$scalar_fn, - &|_, _| true, - ); - } - - fn assign() { - test_helpers::test_binary_elementwise_flush_subnormals( - &|mut a, b| { as core::ops::$trait_assign>::$fn_assign(&mut a, b); a }, - &$scalar_fn, - &|_, _| true, - ); - } - } - } - }; - { $scalar:ty, $trait:ident :: $fn:ident, $trait_assign:ident :: $fn_assign:ident } => { - impl_binary_op_test! { $scalar, $trait::$fn, $trait_assign::$fn_assign, <$scalar as core::ops::$trait>::$fn } - }; -} - -/// Implements a test on a binary operation using proptest. -/// -/// Like `impl_binary_op_test`, but allows providing a function for rejecting particular inputs -/// (like the `proptest_assume` macro). -/// -/// Compares the vector operation to the equivalent scalar operation. -#[macro_export] -macro_rules! impl_binary_checked_op_test { - { $scalar:ty, $trait:ident :: $fn:ident, $trait_assign:ident :: $fn_assign:ident, $scalar_fn:expr, $check_fn:expr } => { - mod $fn { - use super::*; - use core_simd::simd::Simd; - - test_helpers::test_lanes! { - fn normal() { - #![allow(clippy::redundant_closure_call)] - test_helpers::test_binary_elementwise( - & as core::ops::$trait>::$fn, - &$scalar_fn, - &|x, y| x.iter().zip(y.iter()).all(|(x, y)| $check_fn(*x, *y)), - ); - } - - fn assign() { - #![allow(clippy::redundant_closure_call)] - test_helpers::test_binary_elementwise( - &|mut a, b| { as core::ops::$trait_assign>::$fn_assign(&mut a, b); a }, - &$scalar_fn, - &|x, y| x.iter().zip(y.iter()).all(|(x, y)| $check_fn(*x, *y)), - ) - } - } - } - }; - { $scalar:ty, $trait:ident :: $fn:ident, $trait_assign:ident :: $fn_assign:ident, $check_fn:expr } => { - impl_binary_checked_op_test! { $scalar, $trait::$fn, $trait_assign::$fn_assign, <$scalar as core::ops::$trait>::$fn, $check_fn } - }; -} - -#[macro_export] -macro_rules! impl_common_integer_tests { - { $vector:ident, $scalar:ident } => { - test_helpers::test_lanes! { - fn shr() { - use core::ops::Shr; - let shr = |x: $scalar, y: $scalar| x.wrapping_shr(y as _); - test_helpers::test_binary_elementwise( - &<$vector:: as Shr<$vector::>>::shr, - &shr, - &|_, _| true, - ); - test_helpers::test_binary_scalar_rhs_elementwise( - &<$vector:: as Shr<$scalar>>::shr, - &shr, - &|_, _| true, - ); - } - - fn shl() { - use core::ops::Shl; - let shl = |x: $scalar, y: $scalar| x.wrapping_shl(y as _); - test_helpers::test_binary_elementwise( - &<$vector:: as Shl<$vector::>>::shl, - &shl, - &|_, _| true, - ); - test_helpers::test_binary_scalar_rhs_elementwise( - &<$vector:: as Shl<$scalar>>::shl, - &shl, - &|_, _| true, - ); - } - - fn reduce_sum() { - test_helpers::test_1(&|x| { - use test_helpers::subnormals::{flush, flush_in}; - test_helpers::prop_assert_biteq! ( - $vector::::from_array(x).reduce_sum(), - x.iter().copied().fold(0 as $scalar, $scalar::wrapping_add), - flush(x.iter().copied().map(flush_in).fold(0 as $scalar, $scalar::wrapping_add)), - ); - Ok(()) - }); - } - - fn reduce_product() { - test_helpers::test_1(&|x| { - use test_helpers::subnormals::{flush, flush_in}; - test_helpers::prop_assert_biteq! ( - $vector::::from_array(x).reduce_product(), - x.iter().copied().fold(1 as $scalar, $scalar::wrapping_mul), - flush(x.iter().copied().map(flush_in).fold(1 as $scalar, $scalar::wrapping_mul)), - ); - Ok(()) - }); - } - - fn reduce_and() { - test_helpers::test_1(&|x| { - test_helpers::prop_assert_biteq! ( - $vector::::from_array(x).reduce_and(), - x.iter().copied().fold(-1i8 as $scalar, <$scalar as core::ops::BitAnd>::bitand), - ); - Ok(()) - }); - } - - fn reduce_or() { - test_helpers::test_1(&|x| { - test_helpers::prop_assert_biteq! ( - $vector::::from_array(x).reduce_or(), - x.iter().copied().fold(0 as $scalar, <$scalar as core::ops::BitOr>::bitor), - ); - Ok(()) - }); - } - - fn reduce_xor() { - test_helpers::test_1(&|x| { - test_helpers::prop_assert_biteq! ( - $vector::::from_array(x).reduce_xor(), - x.iter().copied().fold(0 as $scalar, <$scalar as core::ops::BitXor>::bitxor), - ); - Ok(()) - }); - } - - fn reduce_max() { - test_helpers::test_1(&|x| { - test_helpers::prop_assert_biteq! ( - $vector::::from_array(x).reduce_max(), - x.iter().copied().max().unwrap(), - ); - Ok(()) - }); - } - - fn reduce_min() { - test_helpers::test_1(&|x| { - test_helpers::prop_assert_biteq! ( - $vector::::from_array(x).reduce_min(), - x.iter().copied().min().unwrap(), - ); - Ok(()) - }); - } - - fn swap_bytes() { - test_helpers::test_unary_elementwise( - &$vector::::swap_bytes, - &$scalar::swap_bytes, - &|_| true, - ) - } - - fn reverse_bits() { - test_helpers::test_unary_elementwise( - &$vector::::reverse_bits, - &$scalar::reverse_bits, - &|_| true, - ) - } - - fn leading_zeros() { - test_helpers::test_unary_elementwise( - &$vector::::leading_zeros, - &|x| x.leading_zeros() as _, - &|_| true, - ) - } - - fn trailing_zeros() { - test_helpers::test_unary_elementwise( - &$vector::::trailing_zeros, - &|x| x.trailing_zeros() as _, - &|_| true, - ) - } - - fn leading_ones() { - test_helpers::test_unary_elementwise( - &$vector::::leading_ones, - &|x| x.leading_ones() as _, - &|_| true, - ) - } - - fn trailing_ones() { - test_helpers::test_unary_elementwise( - &$vector::::trailing_ones, - &|x| x.trailing_ones() as _, - &|_| true, - ) - } - } - } -} - -/// Implement tests for signed integers. -#[macro_export] -macro_rules! impl_signed_tests { - { $scalar:tt } => { - mod $scalar { - use core_simd::simd::num::SimdInt; - type Vector = core_simd::simd::Simd; - type Scalar = $scalar; - - impl_common_integer_tests! { Vector, Scalar } - - test_helpers::test_lanes! { - fn neg() { - test_helpers::test_unary_elementwise( - & as core::ops::Neg>::neg, - &::neg, - &|x| !x.contains(&Scalar::MIN), - ); - } - - fn is_positive() { - test_helpers::test_unary_mask_elementwise( - &Vector::::is_positive, - &Scalar::is_positive, - &|_| true, - ); - } - - fn is_negative() { - test_helpers::test_unary_mask_elementwise( - &Vector::::is_negative, - &Scalar::is_negative, - &|_| true, - ); - } - - fn signum() { - test_helpers::test_unary_elementwise( - &Vector::::signum, - &Scalar::signum, - &|_| true, - ) - } - - fn div_min_may_overflow() { - let a = Vector::::splat(Scalar::MIN); - let b = Vector::::splat(-1); - assert_eq!(a / b, a); - } - - fn rem_min_may_overflow() { - let a = Vector::::splat(Scalar::MIN); - let b = Vector::::splat(-1); - assert_eq!(a % b, Vector::::splat(0)); - } - - fn simd_min() { - use core_simd::simd::cmp::SimdOrd; - let a = Vector::::splat(Scalar::MIN); - let b = Vector::::splat(0); - assert_eq!(a.simd_min(b), a); - let a = Vector::::splat(Scalar::MAX); - let b = Vector::::splat(0); - assert_eq!(a.simd_min(b), b); - } - - fn simd_max() { - use core_simd::simd::cmp::SimdOrd; - let a = Vector::::splat(Scalar::MIN); - let b = Vector::::splat(0); - assert_eq!(a.simd_max(b), b); - let a = Vector::::splat(Scalar::MAX); - let b = Vector::::splat(0); - assert_eq!(a.simd_max(b), a); - } - - fn simd_clamp() { - use core_simd::simd::cmp::SimdOrd; - let min = Vector::::splat(Scalar::MIN); - let max = Vector::::splat(Scalar::MAX); - let zero = Vector::::splat(0); - let one = Vector::::splat(1); - let negone = Vector::::splat(-1); - assert_eq!(zero.simd_clamp(min, max), zero); - assert_eq!(zero.simd_clamp(min, one), zero); - assert_eq!(zero.simd_clamp(one, max), one); - assert_eq!(zero.simd_clamp(min, negone), negone); - } - } - - test_helpers::test_lanes_panic! { - fn div_by_all_zeros_panics() { - let a = Vector::::splat(42); - let b = Vector::::splat(0); - let _ = a / b; - } - - fn div_by_one_zero_panics() { - let a = Vector::::splat(42); - let mut b = Vector::::splat(21); - b[0] = 0 as _; - let _ = a / b; - } - - fn rem_zero_panic() { - let a = Vector::::splat(42); - let b = Vector::::splat(0); - let _ = a % b; - } - } - - test_helpers::test_lanes! { - fn div_neg_one_no_panic() { - let a = Vector::::splat(42); - let b = Vector::::splat(-1); - let _ = a / b; - } - - fn rem_neg_one_no_panic() { - let a = Vector::::splat(42); - let b = Vector::::splat(-1); - let _ = a % b; - } - } - - impl_binary_op_test!(Scalar, Add::add, AddAssign::add_assign, Scalar::wrapping_add); - impl_binary_op_test!(Scalar, Sub::sub, SubAssign::sub_assign, Scalar::wrapping_sub); - impl_binary_op_test!(Scalar, Mul::mul, MulAssign::mul_assign, Scalar::wrapping_mul); - - // Exclude Div and Rem panicking cases - impl_binary_checked_op_test!(Scalar, Div::div, DivAssign::div_assign, Scalar::wrapping_div, |x, y| y != 0 && !(x == Scalar::MIN && y == -1)); - impl_binary_checked_op_test!(Scalar, Rem::rem, RemAssign::rem_assign, Scalar::wrapping_rem, |x, y| y != 0 && !(x == Scalar::MIN && y == -1)); - - impl_unary_op_test!(Scalar, Not::not); - impl_binary_op_test!(Scalar, BitAnd::bitand, BitAndAssign::bitand_assign); - impl_binary_op_test!(Scalar, BitOr::bitor, BitOrAssign::bitor_assign); - impl_binary_op_test!(Scalar, BitXor::bitxor, BitXorAssign::bitxor_assign); - } - } -} - -/// Implement tests for unsigned integers. -#[macro_export] -macro_rules! impl_unsigned_tests { - { $scalar:tt } => { - mod $scalar { - use core_simd::simd::num::SimdUint; - type Vector = core_simd::simd::Simd; - type Scalar = $scalar; - - impl_common_integer_tests! { Vector, Scalar } - - test_helpers::test_lanes_panic! { - fn rem_zero_panic() { - let a = Vector::::splat(42); - let b = Vector::::splat(0); - let _ = a % b; - } - } - - test_helpers::test_lanes! { - fn wrapping_neg() { - test_helpers::test_unary_elementwise( - &Vector::::wrapping_neg, - &Scalar::wrapping_neg, - &|_| true, - ); - } - } - - impl_binary_op_test!(Scalar, Add::add, AddAssign::add_assign, Scalar::wrapping_add); - impl_binary_op_test!(Scalar, Sub::sub, SubAssign::sub_assign, Scalar::wrapping_sub); - impl_binary_op_test!(Scalar, Mul::mul, MulAssign::mul_assign, Scalar::wrapping_mul); - - // Exclude Div and Rem panicking cases - impl_binary_checked_op_test!(Scalar, Div::div, DivAssign::div_assign, Scalar::wrapping_div, |_, y| y != 0); - impl_binary_checked_op_test!(Scalar, Rem::rem, RemAssign::rem_assign, Scalar::wrapping_rem, |_, y| y != 0); - - impl_unary_op_test!(Scalar, Not::not); - impl_binary_op_test!(Scalar, BitAnd::bitand, BitAndAssign::bitand_assign); - impl_binary_op_test!(Scalar, BitOr::bitor, BitOrAssign::bitor_assign); - impl_binary_op_test!(Scalar, BitXor::bitxor, BitXorAssign::bitxor_assign); - } - } -} - -/// Implement tests for floating point numbers. -#[macro_export] -macro_rules! impl_float_tests { - { $scalar:tt, $int_scalar:tt } => { - mod $scalar { - use core_simd::simd::num::SimdFloat; - type Vector = core_simd::simd::Simd; - type Scalar = $scalar; - - impl_unary_op_test!(Scalar, Neg::neg); - impl_binary_op_test!(Scalar, Add::add, AddAssign::add_assign); - impl_binary_op_test!(Scalar, Sub::sub, SubAssign::sub_assign); - impl_binary_op_test!(Scalar, Mul::mul, MulAssign::mul_assign); - impl_binary_op_test!(Scalar, Div::div, DivAssign::div_assign); - impl_binary_op_test!(Scalar, Rem::rem, RemAssign::rem_assign); - - test_helpers::test_lanes! { - fn is_sign_positive() { - test_helpers::test_unary_mask_elementwise( - &Vector::::is_sign_positive, - &Scalar::is_sign_positive, - &|_| true, - ); - } - - fn is_sign_negative() { - test_helpers::test_unary_mask_elementwise( - &Vector::::is_sign_negative, - &Scalar::is_sign_negative, - &|_| true, - ); - } - - fn is_finite() { - test_helpers::test_unary_mask_elementwise( - &Vector::::is_finite, - &Scalar::is_finite, - &|_| true, - ); - } - - fn is_infinite() { - test_helpers::test_unary_mask_elementwise( - &Vector::::is_infinite, - &Scalar::is_infinite, - &|_| true, - ); - } - - fn is_nan() { - test_helpers::test_unary_mask_elementwise( - &Vector::::is_nan, - &Scalar::is_nan, - &|_| true, - ); - } - - fn is_normal() { - test_helpers::test_unary_mask_elementwise( - &Vector::::is_normal, - &Scalar::is_normal, - &|_| true, - ); - } - - fn is_subnormal() { - test_helpers::test_unary_mask_elementwise( - &Vector::::is_subnormal, - &Scalar::is_subnormal, - &|_| true, - ); - } - - fn abs() { - test_helpers::test_unary_elementwise( - &Vector::::abs, - &Scalar::abs, - &|_| true, - ) - } - - fn recip() { - test_helpers::test_unary_elementwise( - &Vector::::recip, - &Scalar::recip, - &|_| true, - ) - } - - fn to_degrees() { - test_helpers::test_unary_elementwise_flush_subnormals( - &Vector::::to_degrees, - &Scalar::to_degrees, - &|_| true, - ) - } - - fn to_radians() { - test_helpers::test_unary_elementwise_flush_subnormals( - &Vector::::to_radians, - &Scalar::to_radians, - &|_| true, - ) - } - - fn signum() { - test_helpers::test_unary_elementwise( - &Vector::::signum, - &Scalar::signum, - &|_| true, - ) - } - - fn copysign() { - test_helpers::test_binary_elementwise( - &Vector::::copysign, - &Scalar::copysign, - &|_, _| true, - ) - } - - fn simd_min() { - // Regular conditions (both values aren't zero) - test_helpers::test_binary_elementwise( - &Vector::::simd_min, - &Scalar::min, - // Reject the case where both values are zero with different signs - &|a, b| { - for (a, b) in a.iter().zip(b.iter()) { - if *a == 0. && *b == 0. && a.signum() != b.signum() { - return false; - } - } - true - } - ); - - // Special case where both values are zero - let p_zero = Vector::::splat(0.); - let n_zero = Vector::::splat(-0.); - assert!(p_zero.simd_min(n_zero).to_array().iter().all(|x| *x == 0.)); - assert!(n_zero.simd_min(p_zero).to_array().iter().all(|x| *x == 0.)); - } - - fn simd_max() { - // Regular conditions (both values aren't zero) - test_helpers::test_binary_elementwise( - &Vector::::simd_max, - &Scalar::max, - // Reject the case where both values are zero with different signs - &|a, b| { - for (a, b) in a.iter().zip(b.iter()) { - if *a == 0. && *b == 0. && a.signum() != b.signum() { - return false; - } - } - true - } - ); - - // Special case where both values are zero - let p_zero = Vector::::splat(0.); - let n_zero = Vector::::splat(-0.); - assert!(p_zero.simd_max(n_zero).to_array().iter().all(|x| *x == 0.)); - assert!(n_zero.simd_max(p_zero).to_array().iter().all(|x| *x == 0.)); - } - - fn simd_clamp() { - if cfg!(all(target_arch = "powerpc64", target_feature = "vsx")) { - // https://gitlab.com/qemu-project/qemu/-/issues/1780 - return; - } - test_helpers::test_3(&|value: [Scalar; LANES], mut min: [Scalar; LANES], mut max: [Scalar; LANES]| { - use test_helpers::subnormals::flush_in; - for (min, max) in min.iter_mut().zip(max.iter_mut()) { - if max < min { - core::mem::swap(min, max); - } - if min.is_nan() { - *min = Scalar::NEG_INFINITY; - } - if max.is_nan() { - *max = Scalar::INFINITY; - } - } - - let mut result_scalar = [Scalar::default(); LANES]; - for i in 0..LANES { - result_scalar[i] = value[i].clamp(min[i], max[i]); - } - let mut result_scalar_flush = [Scalar::default(); LANES]; - for i in 0..LANES { - // Comparisons flush-to-zero, but return value selection is _not_ flushed. - let mut value = value[i]; - if flush_in(value) < flush_in(min[i]) { - value = min[i]; - } - if flush_in(value) > flush_in(max[i]) { - value = max[i]; - } - result_scalar_flush[i] = value - } - let result_vector = Vector::from_array(value).simd_clamp(min.into(), max.into()).to_array(); - test_helpers::prop_assert_biteq!(result_vector, result_scalar, result_scalar_flush); - Ok(()) - }) - } - - fn reduce_sum() { - test_helpers::test_1(&|x| { - test_helpers::prop_assert_biteq! ( - Vector::::from_array(x).reduce_sum(), - x.iter().sum(), - ); - Ok(()) - }); - } - - fn reduce_product() { - test_helpers::test_1(&|x| { - test_helpers::prop_assert_biteq! ( - Vector::::from_array(x).reduce_product(), - x.iter().product(), - ); - Ok(()) - }); - } - - fn reduce_max() { - test_helpers::test_1(&|x| { - let vmax = Vector::::from_array(x).reduce_max(); - let smax = x.iter().copied().fold(Scalar::NAN, Scalar::max); - // 0 and -0 are treated the same - if !(x.contains(&0.) && x.contains(&-0.) && vmax.abs() == 0. && smax.abs() == 0.) { - test_helpers::prop_assert_biteq!(vmax, smax); - } - Ok(()) - }); - } - - fn reduce_min() { - test_helpers::test_1(&|x| { - let vmax = Vector::::from_array(x).reduce_min(); - let smax = x.iter().copied().fold(Scalar::NAN, Scalar::min); - // 0 and -0 are treated the same - if !(x.contains(&0.) && x.contains(&-0.) && vmax.abs() == 0. && smax.abs() == 0.) { - test_helpers::prop_assert_biteq!(vmax, smax); - } - Ok(()) - }); - } - } - - #[cfg(feature = "std")] - mod std { - use std_float::StdFloat; - - use super::*; - test_helpers::test_lanes! { - fn sqrt() { - test_helpers::test_unary_elementwise( - &Vector::::sqrt, - &Scalar::sqrt, - &|_| true, - ) - } - - fn mul_add() { - test_helpers::test_ternary_elementwise( - &Vector::::mul_add, - &Scalar::mul_add, - &|_, _, _| true, - ) - } - } - } - } - } -} diff --git a/library/portable-simd/crates/core_simd/tests/pointers.rs b/library/portable-simd/crates/core_simd/tests/pointers.rs deleted file mode 100644 index 90bfc5d5fd6a5..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/pointers.rs +++ /dev/null @@ -1,114 +0,0 @@ -#![feature(portable_simd, strict_provenance, exposed_provenance)] - -use core_simd::simd::{ - ptr::{SimdConstPtr, SimdMutPtr}, - Simd, -}; - -macro_rules! common_tests { - { $constness:ident } => { - test_helpers::test_lanes! { - fn is_null() { - test_helpers::test_unary_mask_elementwise( - &Simd::<*$constness u32, LANES>::is_null, - &<*$constness u32>::is_null, - &|_| true, - ); - } - - fn addr() { - test_helpers::test_unary_elementwise( - &Simd::<*$constness u32, LANES>::addr, - &<*$constness u32>::addr, - &|_| true, - ); - } - - fn with_addr() { - test_helpers::test_binary_elementwise( - &Simd::<*$constness u32, LANES>::with_addr, - &<*$constness u32>::with_addr, - &|_, _| true, - ); - } - - fn expose_provenance() { - test_helpers::test_unary_elementwise( - &Simd::<*$constness u32, LANES>::expose_provenance, - &<*$constness u32>::expose_provenance, - &|_| true, - ); - } - - fn wrapping_offset() { - test_helpers::test_binary_elementwise( - &Simd::<*$constness u32, LANES>::wrapping_offset, - &<*$constness u32>::wrapping_offset, - &|_, _| true, - ); - } - - fn wrapping_add() { - test_helpers::test_binary_elementwise( - &Simd::<*$constness u32, LANES>::wrapping_add, - &<*$constness u32>::wrapping_add, - &|_, _| true, - ); - } - - fn wrapping_sub() { - test_helpers::test_binary_elementwise( - &Simd::<*$constness u32, LANES>::wrapping_sub, - &<*$constness u32>::wrapping_sub, - &|_, _| true, - ); - } - } - } -} - -mod const_ptr { - use super::*; - common_tests! { const } - - test_helpers::test_lanes! { - fn cast_mut() { - test_helpers::test_unary_elementwise( - &Simd::<*const u32, LANES>::cast_mut, - &<*const u32>::cast_mut, - &|_| true, - ); - } - - fn with_exposed_provenance() { - test_helpers::test_unary_elementwise( - &Simd::<*const u32, LANES>::with_exposed_provenance, - &core::ptr::with_exposed_provenance::, - &|_| true, - ); - } - } -} - -mod mut_ptr { - use super::*; - common_tests! { mut } - - test_helpers::test_lanes! { - fn cast_const() { - test_helpers::test_unary_elementwise( - &Simd::<*mut u32, LANES>::cast_const, - &<*mut u32>::cast_const, - &|_| true, - ); - } - - fn with_exposed_provenance() { - test_helpers::test_unary_elementwise( - &Simd::<*mut u32, LANES>::with_exposed_provenance, - &core::ptr::with_exposed_provenance_mut::, - &|_| true, - ); - } - } -} diff --git a/library/portable-simd/crates/core_simd/tests/round.rs b/library/portable-simd/crates/core_simd/tests/round.rs deleted file mode 100644 index 847766ec41ed2..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/round.rs +++ /dev/null @@ -1,86 +0,0 @@ -#![feature(portable_simd)] - -macro_rules! float_rounding_test { - { $scalar:tt, $int_scalar:tt } => { - mod $scalar { - use std_float::StdFloat; - - type Vector = core_simd::simd::Simd<$scalar, LANES>; - type Scalar = $scalar; - type IntScalar = $int_scalar; - - test_helpers::test_lanes! { - fn ceil() { - test_helpers::test_unary_elementwise( - &Vector::::ceil, - &Scalar::ceil, - &|_| true, - ) - } - - fn floor() { - test_helpers::test_unary_elementwise( - &Vector::::floor, - &Scalar::floor, - &|_| true, - ) - } - - fn round() { - test_helpers::test_unary_elementwise( - &Vector::::round, - &Scalar::round, - &|_| true, - ) - } - - fn trunc() { - test_helpers::test_unary_elementwise( - &Vector::::trunc, - &Scalar::trunc, - &|_| true, - ) - } - - fn fract() { - test_helpers::test_unary_elementwise_flush_subnormals( - &Vector::::fract, - &Scalar::fract, - &|_| true, - ) - } - } - - test_helpers::test_lanes! { - fn to_int_unchecked() { - use core_simd::simd::num::SimdFloat; - // The maximum integer that can be represented by the equivalently sized float has - // all of the mantissa digits set to 1, pushed up to the MSB. - const ALL_MANTISSA_BITS: IntScalar = ((1 << ::MANTISSA_DIGITS) - 1); - const MAX_REPRESENTABLE_VALUE: Scalar = - (ALL_MANTISSA_BITS << (core::mem::size_of::() * 8 - ::MANTISSA_DIGITS as usize - 1)) as Scalar; - - let mut runner = test_helpers::make_runner(); - runner.run( - &test_helpers::array::UniformArrayStrategy::new(-MAX_REPRESENTABLE_VALUE..MAX_REPRESENTABLE_VALUE), - |x| { - let result_1 = unsafe { Vector::from_array(x).to_int_unchecked::().to_array() }; - let result_2 = { - let mut result: [IntScalar; LANES] = [0; LANES]; - for (i, o) in x.iter().zip(result.iter_mut()) { - *o = unsafe { i.to_int_unchecked::() }; - } - result - }; - test_helpers::prop_assert_biteq!(result_1, result_2); - Ok(()) - }, - ).unwrap(); - } - } - } - } -} - -float_rounding_test! { f32, i32 } -float_rounding_test! { f64, i64 } diff --git a/library/portable-simd/crates/core_simd/tests/swizzle.rs b/library/portable-simd/crates/core_simd/tests/swizzle.rs deleted file mode 100644 index 522d71439b77d..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/swizzle.rs +++ /dev/null @@ -1,76 +0,0 @@ -#![feature(portable_simd)] -use core_simd::simd::{Simd, Swizzle}; - -#[cfg(target_arch = "wasm32")] -use wasm_bindgen_test::*; - -#[cfg(target_arch = "wasm32")] -wasm_bindgen_test_configure!(run_in_browser); - -#[test] -#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] -fn swizzle() { - struct Index; - impl Swizzle<4> for Index { - const INDEX: [usize; 4] = [2, 1, 3, 0]; - } - impl Swizzle<2> for Index { - const INDEX: [usize; 2] = [1, 1]; - } - - let vector = Simd::from_array([2, 4, 1, 9]); - assert_eq!(Index::swizzle(vector).to_array(), [1, 4, 9, 2]); - assert_eq!(Index::swizzle(vector).to_array(), [4, 4]); -} - -#[test] -#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] -fn reverse() { - let a = Simd::from_array([1, 2, 3, 4]); - assert_eq!(a.reverse().to_array(), [4, 3, 2, 1]); -} - -#[test] -#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] -fn rotate() { - let a = Simd::from_array([1, 2, 3, 4]); - assert_eq!(a.rotate_elements_left::<0>().to_array(), [1, 2, 3, 4]); - assert_eq!(a.rotate_elements_left::<1>().to_array(), [2, 3, 4, 1]); - assert_eq!(a.rotate_elements_left::<2>().to_array(), [3, 4, 1, 2]); - assert_eq!(a.rotate_elements_left::<3>().to_array(), [4, 1, 2, 3]); - assert_eq!(a.rotate_elements_left::<4>().to_array(), [1, 2, 3, 4]); - assert_eq!(a.rotate_elements_left::<5>().to_array(), [2, 3, 4, 1]); - assert_eq!(a.rotate_elements_right::<0>().to_array(), [1, 2, 3, 4]); - assert_eq!(a.rotate_elements_right::<1>().to_array(), [4, 1, 2, 3]); - assert_eq!(a.rotate_elements_right::<2>().to_array(), [3, 4, 1, 2]); - assert_eq!(a.rotate_elements_right::<3>().to_array(), [2, 3, 4, 1]); - assert_eq!(a.rotate_elements_right::<4>().to_array(), [1, 2, 3, 4]); - assert_eq!(a.rotate_elements_right::<5>().to_array(), [4, 1, 2, 3]); -} - -#[test] -#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] -fn interleave() { - let a = Simd::from_array([0, 1, 2, 3, 4, 5, 6, 7]); - let b = Simd::from_array([8, 9, 10, 11, 12, 13, 14, 15]); - let (lo, hi) = a.interleave(b); - assert_eq!(lo.to_array(), [0, 8, 1, 9, 2, 10, 3, 11]); - assert_eq!(hi.to_array(), [4, 12, 5, 13, 6, 14, 7, 15]); - let (even, odd) = lo.deinterleave(hi); - assert_eq!(even, a); - assert_eq!(odd, b); -} - -// portable-simd#298 -#[test] -#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] -fn interleave_one() { - let a = Simd::from_array([0]); - let b = Simd::from_array([1]); - let (lo, hi) = a.interleave(b); - assert_eq!(lo.to_array(), [0]); - assert_eq!(hi.to_array(), [1]); - let (even, odd) = lo.deinterleave(hi); - assert_eq!(even, a); - assert_eq!(odd, b); -} diff --git a/library/portable-simd/crates/core_simd/tests/swizzle_dyn.rs b/library/portable-simd/crates/core_simd/tests/swizzle_dyn.rs deleted file mode 100644 index 19ffe1417c8c4..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/swizzle_dyn.rs +++ /dev/null @@ -1,73 +0,0 @@ -#![feature(portable_simd)] -use core::{fmt, ops::RangeInclusive}; -use test_helpers::{biteq, make_runner, prop_assert_biteq}; - -fn swizzle_dyn_scalar_ver(values: [u8; N], idxs: [u8; N]) -> [u8; N] { - let mut array = [0; N]; - for (i, k) in idxs.into_iter().enumerate() { - if (k as usize) < N { - array[i] = values[k as usize]; - }; - } - array -} - -test_helpers::test_lanes! { - fn swizzle_dyn() { - match_simd_with_fallback( - &core_simd::simd::Simd::::swizzle_dyn, - &swizzle_dyn_scalar_ver, - &|_, _| true, - ); - } -} - -fn match_simd_with_fallback( - fv: &dyn Fn(Vector, Vector) -> VectorResult, - fs: &dyn Fn([Scalar; N], [Scalar; N]) -> [ScalarResult; N], - check: &dyn Fn([Scalar; N], [Scalar; N]) -> bool, -) where - Scalar: Copy + fmt::Debug + SwizzleStrategy, - ScalarResult: Copy + biteq::BitEq + fmt::Debug + SwizzleStrategy, - Vector: Into<[Scalar; N]> + From<[Scalar; N]> + Copy, - VectorResult: Into<[ScalarResult; N]> + From<[ScalarResult; N]> + Copy, -{ - test_swizzles_2(&|x: [Scalar; N], y: [Scalar; N]| { - proptest::prop_assume!(check(x, y)); - let result_v: [ScalarResult; N] = fv(x.into(), y.into()).into(); - let result_s: [ScalarResult; N] = fs(x, y); - crate::prop_assert_biteq!(result_v, result_s); - Ok(()) - }); -} - -fn test_swizzles_2( - f: &dyn Fn(A, B) -> proptest::test_runner::TestCaseResult, -) { - let mut runner = make_runner(); - runner - .run( - &(A::swizzled_strategy(), B::swizzled_strategy()), - |(a, b)| f(a, b), - ) - .unwrap(); -} - -pub trait SwizzleStrategy { - type Strategy: proptest::strategy::Strategy; - fn swizzled_strategy() -> Self::Strategy; -} - -impl SwizzleStrategy for u8 { - type Strategy = RangeInclusive; - fn swizzled_strategy() -> Self::Strategy { - 0..=64 - } -} - -impl SwizzleStrategy for [T; N] { - type Strategy = test_helpers::array::UniformArrayStrategy; - fn swizzled_strategy() -> Self::Strategy { - Self::Strategy::new(T::swizzled_strategy()) - } -} diff --git a/library/portable-simd/crates/core_simd/tests/to_bytes.rs b/library/portable-simd/crates/core_simd/tests/to_bytes.rs deleted file mode 100644 index 66a7981cdc3dd..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/to_bytes.rs +++ /dev/null @@ -1,20 +0,0 @@ -#![feature(portable_simd)] - -use core_simd::simd::{Simd, ToBytes}; - -#[test] -fn byte_convert() { - let int = Simd::::from_array([0xdeadbeef, 0x8badf00d]); - let ne_bytes = int.to_ne_bytes(); - let be_bytes = int.to_be_bytes(); - let le_bytes = int.to_le_bytes(); - assert_eq!(int[0].to_ne_bytes(), ne_bytes[..4]); - assert_eq!(int[1].to_ne_bytes(), ne_bytes[4..]); - assert_eq!(int[0].to_be_bytes(), be_bytes[..4]); - assert_eq!(int[1].to_be_bytes(), be_bytes[4..]); - assert_eq!(int[0].to_le_bytes(), le_bytes[..4]); - assert_eq!(int[1].to_le_bytes(), le_bytes[4..]); - assert_eq!(Simd::::from_ne_bytes(ne_bytes), int); - assert_eq!(Simd::::from_be_bytes(be_bytes), int); - assert_eq!(Simd::::from_le_bytes(le_bytes), int); -} diff --git a/library/portable-simd/crates/core_simd/tests/try_from_slice.rs b/library/portable-simd/crates/core_simd/tests/try_from_slice.rs deleted file mode 100644 index 859e3b94f2cd4..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/try_from_slice.rs +++ /dev/null @@ -1,25 +0,0 @@ -#![feature(portable_simd)] - -#[cfg(target_arch = "wasm32")] -use wasm_bindgen_test::*; - -#[cfg(target_arch = "wasm32")] -wasm_bindgen_test_configure!(run_in_browser); - -use core_simd::simd::i32x4; - -#[test] -#[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)] -fn try_from_slice() { - // Equal length - assert_eq!( - i32x4::try_from([1, 2, 3, 4].as_slice()).unwrap(), - i32x4::from_array([1, 2, 3, 4]) - ); - - // Slice length > vector length - assert!(i32x4::try_from([1, 2, 3, 4, 5].as_slice()).is_err()); - - // Slice length < vector length - assert!(i32x4::try_from([1, 2, 3].as_slice()).is_err()); -} diff --git a/library/portable-simd/crates/core_simd/tests/u16_ops.rs b/library/portable-simd/crates/core_simd/tests/u16_ops.rs deleted file mode 100644 index 9ae3bd6a47d00..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/u16_ops.rs +++ /dev/null @@ -1,5 +0,0 @@ -#![feature(portable_simd)] - -#[macro_use] -mod ops_macros; -impl_unsigned_tests! { u16 } diff --git a/library/portable-simd/crates/core_simd/tests/u32_ops.rs b/library/portable-simd/crates/core_simd/tests/u32_ops.rs deleted file mode 100644 index de34b73d65262..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/u32_ops.rs +++ /dev/null @@ -1,5 +0,0 @@ -#![feature(portable_simd)] - -#[macro_use] -mod ops_macros; -impl_unsigned_tests! { u32 } diff --git a/library/portable-simd/crates/core_simd/tests/u64_ops.rs b/library/portable-simd/crates/core_simd/tests/u64_ops.rs deleted file mode 100644 index 8ee5a318c83d7..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/u64_ops.rs +++ /dev/null @@ -1,5 +0,0 @@ -#![feature(portable_simd)] - -#[macro_use] -mod ops_macros; -impl_unsigned_tests! { u64 } diff --git a/library/portable-simd/crates/core_simd/tests/u8_ops.rs b/library/portable-simd/crates/core_simd/tests/u8_ops.rs deleted file mode 100644 index 6d7211121284b..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/u8_ops.rs +++ /dev/null @@ -1,5 +0,0 @@ -#![feature(portable_simd)] - -#[macro_use] -mod ops_macros; -impl_unsigned_tests! { u8 } diff --git a/library/portable-simd/crates/core_simd/tests/usize_ops.rs b/library/portable-simd/crates/core_simd/tests/usize_ops.rs deleted file mode 100644 index 9c7b1687a0855..0000000000000 --- a/library/portable-simd/crates/core_simd/tests/usize_ops.rs +++ /dev/null @@ -1,5 +0,0 @@ -#![feature(portable_simd)] - -#[macro_use] -mod ops_macros; -impl_unsigned_tests! { usize } diff --git a/library/portable-simd/crates/core_simd/webdriver.json b/library/portable-simd/crates/core_simd/webdriver.json deleted file mode 100644 index f1d5734f1cebd..0000000000000 --- a/library/portable-simd/crates/core_simd/webdriver.json +++ /dev/null @@ -1,7 +0,0 @@ -{ - "goog:chromeOptions": { - "args": [ - "--enable-features=WebAssemblySimd" - ] - } -} diff --git a/library/portable-simd/crates/std_float/Cargo.toml b/library/portable-simd/crates/std_float/Cargo.toml deleted file mode 100644 index 0896094ee63f4..0000000000000 --- a/library/portable-simd/crates/std_float/Cargo.toml +++ /dev/null @@ -1,20 +0,0 @@ -[package] -name = "std_float" -version = "0.1.0" -edition = "2021" - -# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html - -[dependencies] -core_simd = { path = "../core_simd", default-features = false } - -[dev-dependencies.test_helpers] -path = "../test_helpers" - -[target.'cfg(target_arch = "wasm32")'.dev-dependencies] -wasm-bindgen = "0.2" -wasm-bindgen-test = "0.3" - -[features] -default = ["as_crate"] -as_crate = [] diff --git a/library/portable-simd/crates/std_float/src/lib.rs b/library/portable-simd/crates/std_float/src/lib.rs deleted file mode 100644 index 148aa5f9f1771..0000000000000 --- a/library/portable-simd/crates/std_float/src/lib.rs +++ /dev/null @@ -1,207 +0,0 @@ -#![cfg_attr( - feature = "as_crate", - feature(core_intrinsics), - feature(portable_simd), - allow(internal_features) -)] -#[cfg(not(feature = "as_crate"))] -use core::simd; -#[cfg(feature = "as_crate")] -use core_simd::simd; - -use core::intrinsics::simd as intrinsics; - -use simd::{LaneCount, Simd, SupportedLaneCount}; - -#[cfg(feature = "as_crate")] -mod experimental { - pub trait Sealed {} -} - -#[cfg(feature = "as_crate")] -use experimental as sealed; - -use crate::sealed::Sealed; - -/// This trait provides a possibly-temporary implementation of float functions -/// that may, in the absence of hardware support, canonicalize to calling an -/// operating system's `math.h` dynamically-loaded library (also known as a -/// shared object). As these conditionally require runtime support, they -/// should only appear in binaries built assuming OS support: `std`. -/// -/// However, there is no reason SIMD types, in general, need OS support, -/// as for many architectures an embedded binary may simply configure that -/// support itself. This means these types must be visible in `core` -/// but have these functions available in `std`. -/// -/// [`f32`] and [`f64`] achieve a similar trick by using "lang items", but -/// due to compiler limitations, it is harder to implement this approach for -/// abstract data types like [`Simd`]. From that need, this trait is born. -/// -/// It is possible this trait will be replaced in some manner in the future, -/// when either the compiler or its supporting runtime functions are improved. -/// For now this trait is available to permit experimentation with SIMD float -/// operations that may lack hardware support, such as `mul_add`. -pub trait StdFloat: Sealed + Sized { - /// Elementwise fused multiply-add. Computes `(self * a) + b` with only one rounding error, - /// yielding a more accurate result than an unfused multiply-add. - /// - /// Using `mul_add` *may* be more performant than an unfused multiply-add if the target - /// architecture has a dedicated `fma` CPU instruction. However, this is not always - /// true, and will be heavily dependent on designing algorithms with specific target - /// hardware in mind. - #[inline] - #[must_use = "method returns a new vector and does not mutate the original value"] - fn mul_add(self, a: Self, b: Self) -> Self { - unsafe { intrinsics::simd_fma(self, a, b) } - } - - /// Produces a vector where every element has the square root value - /// of the equivalently-indexed element in `self` - #[inline] - #[must_use = "method returns a new vector and does not mutate the original value"] - fn sqrt(self) -> Self { - unsafe { intrinsics::simd_fsqrt(self) } - } - - /// Produces a vector where every element has the sine of the value - /// in the equivalently-indexed element in `self`. - #[must_use = "method returns a new vector and does not mutate the original value"] - fn sin(self) -> Self; - - /// Produces a vector where every element has the cosine of the value - /// in the equivalently-indexed element in `self`. - #[must_use = "method returns a new vector and does not mutate the original value"] - fn cos(self) -> Self; - - /// Produces a vector where every element has the exponential (base e) of the value - /// in the equivalently-indexed element in `self`. - #[must_use = "method returns a new vector and does not mutate the original value"] - fn exp(self) -> Self; - - /// Produces a vector where every element has the exponential (base 2) of the value - /// in the equivalently-indexed element in `self`. - #[must_use = "method returns a new vector and does not mutate the original value"] - fn exp2(self) -> Self; - - /// Produces a vector where every element has the natural logarithm of the value - /// in the equivalently-indexed element in `self`. - #[must_use = "method returns a new vector and does not mutate the original value"] - fn ln(self) -> Self; - - /// Produces a vector where every element has the logarithm with respect to an arbitrary - /// in the equivalently-indexed elements in `self` and `base`. - #[inline] - #[must_use = "method returns a new vector and does not mutate the original value"] - fn log(self, base: Self) -> Self { - unsafe { intrinsics::simd_div(self.ln(), base.ln()) } - } - - /// Produces a vector where every element has the base-2 logarithm of the value - /// in the equivalently-indexed element in `self`. - #[must_use = "method returns a new vector and does not mutate the original value"] - fn log2(self) -> Self; - - /// Produces a vector where every element has the base-10 logarithm of the value - /// in the equivalently-indexed element in `self`. - #[must_use = "method returns a new vector and does not mutate the original value"] - fn log10(self) -> Self; - - /// Returns the smallest integer greater than or equal to each element. - #[must_use = "method returns a new vector and does not mutate the original value"] - #[inline] - fn ceil(self) -> Self { - unsafe { intrinsics::simd_ceil(self) } - } - - /// Returns the largest integer value less than or equal to each element. - #[must_use = "method returns a new vector and does not mutate the original value"] - #[inline] - fn floor(self) -> Self { - unsafe { intrinsics::simd_floor(self) } - } - - /// Rounds to the nearest integer value. Ties round toward zero. - #[must_use = "method returns a new vector and does not mutate the original value"] - #[inline] - fn round(self) -> Self { - unsafe { intrinsics::simd_round(self) } - } - - /// Returns the floating point's integer value, with its fractional part removed. - #[must_use = "method returns a new vector and does not mutate the original value"] - #[inline] - fn trunc(self) -> Self { - unsafe { intrinsics::simd_trunc(self) } - } - - /// Returns the floating point's fractional value, with its integer part removed. - #[must_use = "method returns a new vector and does not mutate the original value"] - fn fract(self) -> Self; -} - -impl Sealed for Simd where LaneCount: SupportedLaneCount {} -impl Sealed for Simd where LaneCount: SupportedLaneCount {} - -macro_rules! impl_float { - { - $($fn:ident: $intrinsic:ident,)* - } => { - impl StdFloat for Simd - where - LaneCount: SupportedLaneCount, - { - #[inline] - fn fract(self) -> Self { - self - self.trunc() - } - - $( - #[inline] - fn $fn(self) -> Self { - unsafe { intrinsics::$intrinsic(self) } - } - )* - } - - impl StdFloat for Simd - where - LaneCount: SupportedLaneCount, - { - #[inline] - fn fract(self) -> Self { - self - self.trunc() - } - - $( - #[inline] - fn $fn(self) -> Self { - // https://github.com/llvm/llvm-project/issues/83729 - #[cfg(target_arch = "aarch64")] - { - let mut ln = Self::splat(0f64); - for i in 0..N { - ln[i] = self[i].$fn() - } - ln - } - - #[cfg(not(target_arch = "aarch64"))] - { - unsafe { intrinsics::$intrinsic(self) } - } - } - )* - } - } -} - -impl_float! { - sin: simd_fsin, - cos: simd_fcos, - exp: simd_fexp, - exp2: simd_fexp2, - ln: simd_flog, - log2: simd_flog2, - log10: simd_flog10, -} diff --git a/library/portable-simd/crates/std_float/tests/float.rs b/library/portable-simd/crates/std_float/tests/float.rs deleted file mode 100644 index c66c968f8c667..0000000000000 --- a/library/portable-simd/crates/std_float/tests/float.rs +++ /dev/null @@ -1,74 +0,0 @@ -#![feature(portable_simd)] - -macro_rules! unary_test { - { $scalar:tt, $($func:tt),+ } => { - test_helpers::test_lanes! { - $( - fn $func() { - test_helpers::test_unary_elementwise( - &core_simd::simd::Simd::<$scalar, LANES>::$func, - &$scalar::$func, - &|_| true, - ) - } - )* - } - } -} - -macro_rules! binary_test { - { $scalar:tt, $($func:tt),+ } => { - test_helpers::test_lanes! { - $( - fn $func() { - test_helpers::test_binary_elementwise( - &core_simd::simd::Simd::<$scalar, LANES>::$func, - &$scalar::$func, - &|_, _| true, - ) - } - )* - } - } -} - -macro_rules! ternary_test { - { $scalar:tt, $($func:tt),+ } => { - test_helpers::test_lanes! { - $( - fn $func() { - test_helpers::test_ternary_elementwise( - &core_simd::simd::Simd::<$scalar, LANES>::$func, - &$scalar::$func, - &|_, _, _| true, - ) - } - )* - } - } -} - -macro_rules! impl_tests { - { $scalar:tt } => { - mod $scalar { - use std_float::StdFloat; - - unary_test! { $scalar, sqrt, sin, cos, exp, exp2, ln, log2, log10, ceil, floor, round, trunc } - binary_test! { $scalar, log } - ternary_test! { $scalar, mul_add } - - test_helpers::test_lanes! { - fn fract() { - test_helpers::test_unary_elementwise_flush_subnormals( - &core_simd::simd::Simd::<$scalar, LANES>::fract, - &$scalar::fract, - &|_| true, - ) - } - } - } - } -} - -impl_tests! { f32 } -impl_tests! { f64 } diff --git a/library/portable-simd/crates/test_helpers/Cargo.toml b/library/portable-simd/crates/test_helpers/Cargo.toml deleted file mode 100644 index 23dae7c93381e..0000000000000 --- a/library/portable-simd/crates/test_helpers/Cargo.toml +++ /dev/null @@ -1,11 +0,0 @@ -[package] -name = "test_helpers" -version = "0.1.0" -edition = "2021" -publish = false - -[dependencies] -proptest = { version = "0.10", default-features = false, features = ["alloc"] } - -[features] -all_lane_counts = [] diff --git a/library/portable-simd/crates/test_helpers/src/array.rs b/library/portable-simd/crates/test_helpers/src/array.rs deleted file mode 100644 index 984a427320deb..0000000000000 --- a/library/portable-simd/crates/test_helpers/src/array.rs +++ /dev/null @@ -1,99 +0,0 @@ -//! Generic-length array strategy. - -// Adapted from proptest's array code -// Copyright 2017 Jason Lingle - -use core::{marker::PhantomData, mem::MaybeUninit}; -use proptest::{ - strategy::{NewTree, Strategy, ValueTree}, - test_runner::TestRunner, -}; - -#[must_use = "strategies do nothing unless used"] -#[derive(Clone, Copy, Debug)] -pub struct UniformArrayStrategy { - strategy: S, - _marker: PhantomData, -} - -impl UniformArrayStrategy { - pub const fn new(strategy: S) -> Self { - Self { - strategy, - _marker: PhantomData, - } - } -} - -pub struct ArrayValueTree { - tree: T, - shrinker: usize, - last_shrinker: Option, -} - -impl Strategy for UniformArrayStrategy -where - T: core::fmt::Debug, - S: Strategy, -{ - type Tree = ArrayValueTree<[S::Tree; LANES]>; - type Value = [T; LANES]; - - fn new_tree(&self, runner: &mut TestRunner) -> NewTree { - let tree: [S::Tree; LANES] = unsafe { - #[allow(clippy::uninit_assumed_init)] - let mut tree: [MaybeUninit; LANES] = MaybeUninit::uninit().assume_init(); - for t in tree.iter_mut() { - *t = MaybeUninit::new(self.strategy.new_tree(runner)?) - } - core::mem::transmute_copy(&tree) - }; - Ok(ArrayValueTree { - tree, - shrinker: 0, - last_shrinker: None, - }) - } -} - -impl ValueTree for ArrayValueTree<[T; LANES]> { - type Value = [T::Value; LANES]; - - fn current(&self) -> Self::Value { - unsafe { - #[allow(clippy::uninit_assumed_init)] - let mut value: [MaybeUninit; LANES] = MaybeUninit::uninit().assume_init(); - for (tree_elem, value_elem) in self.tree.iter().zip(value.iter_mut()) { - *value_elem = MaybeUninit::new(tree_elem.current()); - } - core::mem::transmute_copy(&value) - } - } - - fn simplify(&mut self) -> bool { - while self.shrinker < LANES { - if self.tree[self.shrinker].simplify() { - self.last_shrinker = Some(self.shrinker); - return true; - } else { - self.shrinker += 1; - } - } - - false - } - - fn complicate(&mut self) -> bool { - if let Some(shrinker) = self.last_shrinker { - self.shrinker = shrinker; - if self.tree[shrinker].complicate() { - true - } else { - self.last_shrinker = None; - false - } - } else { - false - } - } -} diff --git a/library/portable-simd/crates/test_helpers/src/biteq.rs b/library/portable-simd/crates/test_helpers/src/biteq.rs deleted file mode 100644 index cbc20cda0d626..0000000000000 --- a/library/portable-simd/crates/test_helpers/src/biteq.rs +++ /dev/null @@ -1,156 +0,0 @@ -//! Compare numeric types by exact bit value. - -pub trait BitEq { - fn biteq(&self, other: &Self) -> bool; - fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result; -} - -impl BitEq for bool { - fn biteq(&self, other: &Self) -> bool { - self == other - } - - fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result { - write!(f, "{:?}", self) - } -} - -macro_rules! impl_integer_biteq { - { $($type:ty),* } => { - $( - impl BitEq for $type { - fn biteq(&self, other: &Self) -> bool { - self == other - } - - fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result { - write!(f, "{:?} ({:x})", self, self) - } - } - )* - }; -} - -impl_integer_biteq! { u8, u16, u32, u64, u128, usize, i8, i16, i32, i64, i128, isize } - -macro_rules! impl_float_biteq { - { $($type:ty),* } => { - $( - impl BitEq for $type { - fn biteq(&self, other: &Self) -> bool { - if self.is_nan() && other.is_nan() { - true // exact nan bits don't matter - } else { - self.to_bits() == other.to_bits() - } - } - - fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result { - write!(f, "{:?} ({:x})", self, self.to_bits()) - } - } - )* - }; -} - -impl_float_biteq! { f32, f64 } - -impl BitEq for *const T { - fn biteq(&self, other: &Self) -> bool { - self == other - } - - fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result { - write!(f, "{:?}", self) - } -} - -impl BitEq for *mut T { - fn biteq(&self, other: &Self) -> bool { - self == other - } - - fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result { - write!(f, "{:?}", self) - } -} - -impl BitEq for [T; N] { - fn biteq(&self, other: &Self) -> bool { - self.iter() - .zip(other.iter()) - .fold(true, |value, (left, right)| value && left.biteq(right)) - } - - fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result { - #[repr(transparent)] - struct Wrapper<'a, T: BitEq>(&'a T); - - impl core::fmt::Debug for Wrapper<'_, T> { - fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result { - self.0.fmt(f) - } - } - - f.debug_list() - .entries(self.iter().map(|x| Wrapper(x))) - .finish() - } -} - -#[doc(hidden)] -pub struct BitEqWrapper<'a, T>(pub &'a T); - -impl PartialEq for BitEqWrapper<'_, T> { - fn eq(&self, other: &Self) -> bool { - self.0.biteq(other.0) - } -} - -impl core::fmt::Debug for BitEqWrapper<'_, T> { - fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result { - self.0.fmt(f) - } -} - -#[doc(hidden)] -pub struct BitEqEitherWrapper<'a, T>(pub &'a T, pub &'a T); - -impl PartialEq> for BitEqWrapper<'_, T> { - fn eq(&self, other: &BitEqEitherWrapper<'_, T>) -> bool { - self.0.biteq(other.0) || self.0.biteq(other.1) - } -} - -impl core::fmt::Debug for BitEqEitherWrapper<'_, T> { - fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result { - if self.0.biteq(self.1) { - self.0.fmt(f) - } else { - self.0.fmt(f)?; - write!(f, " or ")?; - self.1.fmt(f) - } - } -} - -#[macro_export] -macro_rules! prop_assert_biteq { - { $a:expr, $b:expr $(,)? } => { - { - use $crate::biteq::BitEqWrapper; - let a = $a; - let b = $b; - proptest::prop_assert_eq!(BitEqWrapper(&a), BitEqWrapper(&b)); - } - }; - { $a:expr, $b:expr, $c:expr $(,)? } => { - { - use $crate::biteq::{BitEqWrapper, BitEqEitherWrapper}; - let a = $a; - let b = $b; - let c = $c; - proptest::prop_assert_eq!(BitEqWrapper(&a), BitEqEitherWrapper(&b, &c)); - } - }; -} diff --git a/library/portable-simd/crates/test_helpers/src/lib.rs b/library/portable-simd/crates/test_helpers/src/lib.rs deleted file mode 100644 index 51b860a863560..0000000000000 --- a/library/portable-simd/crates/test_helpers/src/lib.rs +++ /dev/null @@ -1,729 +0,0 @@ -#![feature(powerpc_target_feature)] -#![cfg_attr( - any(target_arch = "powerpc", target_arch = "powerpc64"), - feature(stdarch_powerpc) -)] - -pub mod array; - -#[cfg(target_arch = "wasm32")] -pub mod wasm; - -#[macro_use] -pub mod biteq; - -pub mod subnormals; -use subnormals::FlushSubnormals; - -/// Specifies the default strategy for testing a type. -/// -/// This strategy should be what "makes sense" to test. -pub trait DefaultStrategy { - type Strategy: proptest::strategy::Strategy; - fn default_strategy() -> Self::Strategy; -} - -macro_rules! impl_num { - { $type:tt } => { - impl DefaultStrategy for $type { - type Strategy = proptest::num::$type::Any; - fn default_strategy() -> Self::Strategy { - proptest::num::$type::ANY - } - } - } -} - -impl_num! { i8 } -impl_num! { i16 } -impl_num! { i32 } -impl_num! { i64 } -impl_num! { isize } -impl_num! { u8 } -impl_num! { u16 } -impl_num! { u32 } -impl_num! { u64 } -impl_num! { usize } -impl_num! { f32 } -impl_num! { f64 } - -impl DefaultStrategy for *const T { - type Strategy = proptest::strategy::Map *const T>; - fn default_strategy() -> Self::Strategy { - fn map(x: isize) -> *const T { - x as _ - } - use proptest::strategy::Strategy; - proptest::num::isize::ANY.prop_map(map) - } -} - -impl DefaultStrategy for *mut T { - type Strategy = proptest::strategy::Map *mut T>; - fn default_strategy() -> Self::Strategy { - fn map(x: isize) -> *mut T { - x as _ - } - use proptest::strategy::Strategy; - proptest::num::isize::ANY.prop_map(map) - } -} - -#[cfg(not(target_arch = "wasm32"))] -impl DefaultStrategy for u128 { - type Strategy = proptest::num::u128::Any; - fn default_strategy() -> Self::Strategy { - proptest::num::u128::ANY - } -} - -#[cfg(not(target_arch = "wasm32"))] -impl DefaultStrategy for i128 { - type Strategy = proptest::num::i128::Any; - fn default_strategy() -> Self::Strategy { - proptest::num::i128::ANY - } -} - -#[cfg(target_arch = "wasm32")] -impl DefaultStrategy for u128 { - type Strategy = crate::wasm::u128::Any; - fn default_strategy() -> Self::Strategy { - crate::wasm::u128::ANY - } -} - -#[cfg(target_arch = "wasm32")] -impl DefaultStrategy for i128 { - type Strategy = crate::wasm::i128::Any; - fn default_strategy() -> Self::Strategy { - crate::wasm::i128::ANY - } -} - -impl DefaultStrategy for [T; LANES] { - type Strategy = crate::array::UniformArrayStrategy; - fn default_strategy() -> Self::Strategy { - Self::Strategy::new(T::default_strategy()) - } -} - -#[cfg(not(miri))] -pub fn make_runner() -> proptest::test_runner::TestRunner { - Default::default() -} -#[cfg(miri)] -pub fn make_runner() -> proptest::test_runner::TestRunner { - // Only run a few tests on Miri - proptest::test_runner::TestRunner::new(proptest::test_runner::Config::with_cases(4)) -} - -/// Test a function that takes a single value. -pub fn test_1( - f: &dyn Fn(A) -> proptest::test_runner::TestCaseResult, -) { - let mut runner = make_runner(); - runner.run(&A::default_strategy(), f).unwrap(); -} - -/// Test a function that takes two values. -pub fn test_2( - f: &dyn Fn(A, B) -> proptest::test_runner::TestCaseResult, -) { - let mut runner = make_runner(); - runner - .run(&(A::default_strategy(), B::default_strategy()), |(a, b)| { - f(a, b) - }) - .unwrap(); -} - -/// Test a function that takes two values. -pub fn test_3< - A: core::fmt::Debug + DefaultStrategy, - B: core::fmt::Debug + DefaultStrategy, - C: core::fmt::Debug + DefaultStrategy, ->( - f: &dyn Fn(A, B, C) -> proptest::test_runner::TestCaseResult, -) { - let mut runner = make_runner(); - runner - .run( - &( - A::default_strategy(), - B::default_strategy(), - C::default_strategy(), - ), - |(a, b, c)| f(a, b, c), - ) - .unwrap(); -} - -/// Test a unary vector function against a unary scalar function, applied elementwise. -pub fn test_unary_elementwise( - fv: &dyn Fn(Vector) -> VectorResult, - fs: &dyn Fn(Scalar) -> ScalarResult, - check: &dyn Fn([Scalar; LANES]) -> bool, -) where - Scalar: Copy + core::fmt::Debug + DefaultStrategy, - ScalarResult: Copy + biteq::BitEq + core::fmt::Debug + DefaultStrategy, - Vector: Into<[Scalar; LANES]> + From<[Scalar; LANES]> + Copy, - VectorResult: Into<[ScalarResult; LANES]> + From<[ScalarResult; LANES]> + Copy, -{ - test_1(&|x: [Scalar; LANES]| { - proptest::prop_assume!(check(x)); - let result_1: [ScalarResult; LANES] = fv(x.into()).into(); - let result_2: [ScalarResult; LANES] = x - .iter() - .copied() - .map(fs) - .collect::>() - .try_into() - .unwrap(); - crate::prop_assert_biteq!(result_1, result_2); - Ok(()) - }); -} - -/// Test a unary vector function against a unary scalar function, applied elementwise. -/// -/// Where subnormals are flushed, use approximate equality. -pub fn test_unary_elementwise_flush_subnormals< - Scalar, - ScalarResult, - Vector, - VectorResult, - const LANES: usize, ->( - fv: &dyn Fn(Vector) -> VectorResult, - fs: &dyn Fn(Scalar) -> ScalarResult, - check: &dyn Fn([Scalar; LANES]) -> bool, -) where - Scalar: Copy + core::fmt::Debug + DefaultStrategy + FlushSubnormals, - ScalarResult: Copy + biteq::BitEq + core::fmt::Debug + DefaultStrategy + FlushSubnormals, - Vector: Into<[Scalar; LANES]> + From<[Scalar; LANES]> + Copy, - VectorResult: Into<[ScalarResult; LANES]> + From<[ScalarResult; LANES]> + Copy, -{ - let flush = |x: Scalar| subnormals::flush(fs(subnormals::flush_in(x))); - test_1(&|x: [Scalar; LANES]| { - proptest::prop_assume!(check(x)); - let result_v: [ScalarResult; LANES] = fv(x.into()).into(); - let result_s: [ScalarResult; LANES] = x - .iter() - .copied() - .map(fs) - .collect::>() - .try_into() - .unwrap(); - let result_sf: [ScalarResult; LANES] = x - .iter() - .copied() - .map(flush) - .collect::>() - .try_into() - .unwrap(); - crate::prop_assert_biteq!(result_v, result_s, result_sf); - Ok(()) - }); -} - -/// Test a unary vector function against a unary scalar function, applied elementwise. -#[inline(never)] -pub fn test_unary_mask_elementwise( - fv: &dyn Fn(Vector) -> Mask, - fs: &dyn Fn(Scalar) -> bool, - check: &dyn Fn([Scalar; LANES]) -> bool, -) where - Scalar: Copy + core::fmt::Debug + DefaultStrategy, - Vector: Into<[Scalar; LANES]> + From<[Scalar; LANES]> + Copy, - Mask: Into<[bool; LANES]> + From<[bool; LANES]> + Copy, -{ - test_1(&|x: [Scalar; LANES]| { - proptest::prop_assume!(check(x)); - let result_1: [bool; LANES] = fv(x.into()).into(); - let result_2: [bool; LANES] = { - let mut result = [false; LANES]; - for (i, o) in x.iter().zip(result.iter_mut()) { - *o = fs(*i); - } - result - }; - crate::prop_assert_biteq!(result_1, result_2); - Ok(()) - }); -} - -/// Test a binary vector function against a binary scalar function, applied elementwise. -pub fn test_binary_elementwise< - Scalar1, - Scalar2, - ScalarResult, - Vector1, - Vector2, - VectorResult, - const LANES: usize, ->( - fv: &dyn Fn(Vector1, Vector2) -> VectorResult, - fs: &dyn Fn(Scalar1, Scalar2) -> ScalarResult, - check: &dyn Fn([Scalar1; LANES], [Scalar2; LANES]) -> bool, -) where - Scalar1: Copy + core::fmt::Debug + DefaultStrategy, - Scalar2: Copy + core::fmt::Debug + DefaultStrategy, - ScalarResult: Copy + biteq::BitEq + core::fmt::Debug + DefaultStrategy, - Vector1: Into<[Scalar1; LANES]> + From<[Scalar1; LANES]> + Copy, - Vector2: Into<[Scalar2; LANES]> + From<[Scalar2; LANES]> + Copy, - VectorResult: Into<[ScalarResult; LANES]> + From<[ScalarResult; LANES]> + Copy, -{ - test_2(&|x: [Scalar1; LANES], y: [Scalar2; LANES]| { - proptest::prop_assume!(check(x, y)); - let result_1: [ScalarResult; LANES] = fv(x.into(), y.into()).into(); - let result_2: [ScalarResult; LANES] = x - .iter() - .copied() - .zip(y.iter().copied()) - .map(|(x, y)| fs(x, y)) - .collect::>() - .try_into() - .unwrap(); - crate::prop_assert_biteq!(result_1, result_2); - Ok(()) - }); -} - -/// Test a binary vector function against a binary scalar function, applied elementwise. -/// -/// Where subnormals are flushed, use approximate equality. -pub fn test_binary_elementwise_flush_subnormals< - Scalar1, - Scalar2, - ScalarResult, - Vector1, - Vector2, - VectorResult, - const LANES: usize, ->( - fv: &dyn Fn(Vector1, Vector2) -> VectorResult, - fs: &dyn Fn(Scalar1, Scalar2) -> ScalarResult, - check: &dyn Fn([Scalar1; LANES], [Scalar2; LANES]) -> bool, -) where - Scalar1: Copy + core::fmt::Debug + DefaultStrategy + FlushSubnormals, - Scalar2: Copy + core::fmt::Debug + DefaultStrategy + FlushSubnormals, - ScalarResult: Copy + biteq::BitEq + core::fmt::Debug + DefaultStrategy + FlushSubnormals, - Vector1: Into<[Scalar1; LANES]> + From<[Scalar1; LANES]> + Copy, - Vector2: Into<[Scalar2; LANES]> + From<[Scalar2; LANES]> + Copy, - VectorResult: Into<[ScalarResult; LANES]> + From<[ScalarResult; LANES]> + Copy, -{ - let flush = |x: Scalar1, y: Scalar2| { - subnormals::flush(fs(subnormals::flush_in(x), subnormals::flush_in(y))) - }; - test_2(&|x: [Scalar1; LANES], y: [Scalar2; LANES]| { - proptest::prop_assume!(check(x, y)); - let result_v: [ScalarResult; LANES] = fv(x.into(), y.into()).into(); - let result_s: [ScalarResult; LANES] = x - .iter() - .copied() - .zip(y.iter().copied()) - .map(|(x, y)| fs(x, y)) - .collect::>() - .try_into() - .unwrap(); - let result_sf: [ScalarResult; LANES] = x - .iter() - .copied() - .zip(y.iter().copied()) - .map(|(x, y)| flush(x, y)) - .collect::>() - .try_into() - .unwrap(); - crate::prop_assert_biteq!(result_v, result_s, result_sf); - Ok(()) - }); -} - -/// Test a unary vector function against a unary scalar function, applied elementwise. -#[inline(never)] -pub fn test_binary_mask_elementwise( - fv: &dyn Fn(Vector1, Vector2) -> Mask, - fs: &dyn Fn(Scalar1, Scalar2) -> bool, - check: &dyn Fn([Scalar1; LANES], [Scalar2; LANES]) -> bool, -) where - Scalar1: Copy + core::fmt::Debug + DefaultStrategy, - Scalar2: Copy + core::fmt::Debug + DefaultStrategy, - Vector1: Into<[Scalar1; LANES]> + From<[Scalar1; LANES]> + Copy, - Vector2: Into<[Scalar2; LANES]> + From<[Scalar2; LANES]> + Copy, - Mask: Into<[bool; LANES]> + From<[bool; LANES]> + Copy, -{ - test_2(&|x: [Scalar1; LANES], y: [Scalar2; LANES]| { - proptest::prop_assume!(check(x, y)); - let result_v: [bool; LANES] = fv(x.into(), y.into()).into(); - let result_s: [bool; LANES] = x - .iter() - .copied() - .zip(y.iter().copied()) - .map(|(x, y)| fs(x, y)) - .collect::>() - .try_into() - .unwrap(); - crate::prop_assert_biteq!(result_v, result_s); - Ok(()) - }); -} - -/// Test a binary vector-scalar function against a binary scalar function, applied elementwise. -#[inline(never)] -pub fn test_binary_scalar_rhs_elementwise< - Scalar1, - Scalar2, - ScalarResult, - Vector, - VectorResult, - const LANES: usize, ->( - fv: &dyn Fn(Vector, Scalar2) -> VectorResult, - fs: &dyn Fn(Scalar1, Scalar2) -> ScalarResult, - check: &dyn Fn([Scalar1; LANES], Scalar2) -> bool, -) where - Scalar1: Copy + Default + core::fmt::Debug + DefaultStrategy, - Scalar2: Copy + Default + core::fmt::Debug + DefaultStrategy, - ScalarResult: Copy + Default + biteq::BitEq + core::fmt::Debug + DefaultStrategy, - Vector: Into<[Scalar1; LANES]> + From<[Scalar1; LANES]> + Copy, - VectorResult: Into<[ScalarResult; LANES]> + From<[ScalarResult; LANES]> + Copy, -{ - test_2(&|x: [Scalar1; LANES], y: Scalar2| { - proptest::prop_assume!(check(x, y)); - let result_1: [ScalarResult; LANES] = fv(x.into(), y).into(); - let result_2: [ScalarResult; LANES] = { - let mut result = [ScalarResult::default(); LANES]; - for (i, o) in x.iter().zip(result.iter_mut()) { - *o = fs(*i, y); - } - result - }; - crate::prop_assert_biteq!(result_1, result_2); - Ok(()) - }); -} - -/// Test a binary vector-scalar function against a binary scalar function, applied elementwise. -#[inline(never)] -pub fn test_binary_scalar_lhs_elementwise< - Scalar1, - Scalar2, - ScalarResult, - Vector, - VectorResult, - const LANES: usize, ->( - fv: &dyn Fn(Scalar1, Vector) -> VectorResult, - fs: &dyn Fn(Scalar1, Scalar2) -> ScalarResult, - check: &dyn Fn(Scalar1, [Scalar2; LANES]) -> bool, -) where - Scalar1: Copy + Default + core::fmt::Debug + DefaultStrategy, - Scalar2: Copy + Default + core::fmt::Debug + DefaultStrategy, - ScalarResult: Copy + Default + biteq::BitEq + core::fmt::Debug + DefaultStrategy, - Vector: Into<[Scalar2; LANES]> + From<[Scalar2; LANES]> + Copy, - VectorResult: Into<[ScalarResult; LANES]> + From<[ScalarResult; LANES]> + Copy, -{ - test_2(&|x: Scalar1, y: [Scalar2; LANES]| { - proptest::prop_assume!(check(x, y)); - let result_1: [ScalarResult; LANES] = fv(x, y.into()).into(); - let result_2: [ScalarResult; LANES] = { - let mut result = [ScalarResult::default(); LANES]; - for (i, o) in y.iter().zip(result.iter_mut()) { - *o = fs(x, *i); - } - result - }; - crate::prop_assert_biteq!(result_1, result_2); - Ok(()) - }); -} - -/// Test a ternary vector function against a ternary scalar function, applied elementwise. -#[inline(never)] -pub fn test_ternary_elementwise< - Scalar1, - Scalar2, - Scalar3, - ScalarResult, - Vector1, - Vector2, - Vector3, - VectorResult, - const LANES: usize, ->( - fv: &dyn Fn(Vector1, Vector2, Vector3) -> VectorResult, - fs: &dyn Fn(Scalar1, Scalar2, Scalar3) -> ScalarResult, - check: &dyn Fn([Scalar1; LANES], [Scalar2; LANES], [Scalar3; LANES]) -> bool, -) where - Scalar1: Copy + Default + core::fmt::Debug + DefaultStrategy, - Scalar2: Copy + Default + core::fmt::Debug + DefaultStrategy, - Scalar3: Copy + Default + core::fmt::Debug + DefaultStrategy, - ScalarResult: Copy + Default + biteq::BitEq + core::fmt::Debug + DefaultStrategy, - Vector1: Into<[Scalar1; LANES]> + From<[Scalar1; LANES]> + Copy, - Vector2: Into<[Scalar2; LANES]> + From<[Scalar2; LANES]> + Copy, - Vector3: Into<[Scalar3; LANES]> + From<[Scalar3; LANES]> + Copy, - VectorResult: Into<[ScalarResult; LANES]> + From<[ScalarResult; LANES]> + Copy, -{ - test_3( - &|x: [Scalar1; LANES], y: [Scalar2; LANES], z: [Scalar3; LANES]| { - proptest::prop_assume!(check(x, y, z)); - let result_1: [ScalarResult; LANES] = fv(x.into(), y.into(), z.into()).into(); - let result_2: [ScalarResult; LANES] = { - let mut result = [ScalarResult::default(); LANES]; - for ((i1, (i2, i3)), o) in - x.iter().zip(y.iter().zip(z.iter())).zip(result.iter_mut()) - { - *o = fs(*i1, *i2, *i3); - } - result - }; - crate::prop_assert_biteq!(result_1, result_2); - Ok(()) - }, - ); -} - -#[doc(hidden)] -#[macro_export] -macro_rules! test_lanes_helper { - ($($(#[$meta:meta])* $fn_name:ident $lanes:literal;)+) => { - $( - #[test] - $(#[$meta])* - fn $fn_name() { - implementation::<$lanes>(); - } - )+ - }; - ( - $(#[$meta:meta])+; - $($(#[$meta_before:meta])+ $fn_name_before:ident $lanes_before:literal;)* - $fn_name:ident $lanes:literal; - $($fn_name_rest:ident $lanes_rest:literal;)* - ) => { - $crate::test_lanes_helper!( - $(#[$meta])+; - $($(#[$meta_before])+ $fn_name_before $lanes_before;)* - $(#[$meta])+ $fn_name $lanes; - $($fn_name_rest $lanes_rest;)* - ); - }; - ( - $(#[$meta_ignored:meta])+; - $($(#[$meta:meta])+ $fn_name:ident $lanes:literal;)+ - ) => { - $crate::test_lanes_helper!($($(#[$meta])+ $fn_name $lanes;)+); - }; -} - -/// Expand a const-generic test into separate tests for each possible lane count. -#[macro_export] -macro_rules! test_lanes { - { - $(fn $test:ident() $body:tt)* - } => { - $( - mod $test { - use super::*; - - fn implementation() - where - core_simd::simd::LaneCount<$lanes>: core_simd::simd::SupportedLaneCount, - $body - - #[cfg(target_arch = "wasm32")] - wasm_bindgen_test::wasm_bindgen_test_configure!(run_in_browser); - - $crate::test_lanes_helper!( - #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]; - lanes_1 1; - lanes_2 2; - lanes_4 4; - ); - - #[cfg(not(miri))] // Miri intrinsic implementations are uniform and larger tests are sloooow - $crate::test_lanes_helper!( - #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]; - lanes_8 8; - lanes_16 16; - lanes_32 32; - lanes_64 64; - ); - - #[cfg(feature = "all_lane_counts")] - $crate::test_lanes_helper!( - // test some odd and even non-power-of-2 lengths on miri - #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]; - lanes_3 3; - lanes_5 5; - lanes_6 6; - ); - - #[cfg(feature = "all_lane_counts")] - #[cfg(not(miri))] // Miri intrinsic implementations are uniform and larger tests are sloooow - $crate::test_lanes_helper!( - #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test::wasm_bindgen_test)]; - lanes_7 7; - lanes_9 9; - lanes_10 10; - lanes_11 11; - lanes_12 12; - lanes_13 13; - lanes_14 14; - lanes_15 15; - lanes_17 17; - lanes_18 18; - lanes_19 19; - lanes_20 20; - lanes_21 21; - lanes_22 22; - lanes_23 23; - lanes_24 24; - lanes_25 25; - lanes_26 26; - lanes_27 27; - lanes_28 28; - lanes_29 29; - lanes_30 30; - lanes_31 31; - lanes_33 33; - lanes_34 34; - lanes_35 35; - lanes_36 36; - lanes_37 37; - lanes_38 38; - lanes_39 39; - lanes_40 40; - lanes_41 41; - lanes_42 42; - lanes_43 43; - lanes_44 44; - lanes_45 45; - lanes_46 46; - lanes_47 47; - lanes_48 48; - lanes_49 49; - lanes_50 50; - lanes_51 51; - lanes_52 52; - lanes_53 53; - lanes_54 54; - lanes_55 55; - lanes_56 56; - lanes_57 57; - lanes_58 58; - lanes_59 59; - lanes_60 60; - lanes_61 61; - lanes_62 62; - lanes_63 63; - ); - } - )* - } -} - -/// Expand a const-generic `#[should_panic]` test into separate tests for each possible lane count. -#[macro_export] -macro_rules! test_lanes_panic { - { - $(fn $test:ident() $body:tt)* - } => { - $( - mod $test { - use super::*; - - fn implementation() - where - core_simd::simd::LaneCount<$lanes>: core_simd::simd::SupportedLaneCount, - $body - - $crate::test_lanes_helper!( - #[should_panic]; - lanes_1 1; - lanes_2 2; - lanes_4 4; - ); - - #[cfg(not(miri))] // Miri intrinsic implementations are uniform and larger tests are sloooow - $crate::test_lanes_helper!( - #[should_panic]; - lanes_8 8; - lanes_16 16; - lanes_32 32; - lanes_64 64; - ); - - #[cfg(feature = "all_lane_counts")] - $crate::test_lanes_helper!( - // test some odd and even non-power-of-2 lengths on miri - #[should_panic]; - lanes_3 3; - lanes_5 5; - lanes_6 6; - ); - - #[cfg(feature = "all_lane_counts")] - #[cfg(not(miri))] // Miri intrinsic implementations are uniform and larger tests are sloooow - $crate::test_lanes_helper!( - #[should_panic]; - lanes_7 7; - lanes_9 9; - lanes_10 10; - lanes_11 11; - lanes_12 12; - lanes_13 13; - lanes_14 14; - lanes_15 15; - lanes_17 17; - lanes_18 18; - lanes_19 19; - lanes_20 20; - lanes_21 21; - lanes_22 22; - lanes_23 23; - lanes_24 24; - lanes_25 25; - lanes_26 26; - lanes_27 27; - lanes_28 28; - lanes_29 29; - lanes_30 30; - lanes_31 31; - lanes_33 33; - lanes_34 34; - lanes_35 35; - lanes_36 36; - lanes_37 37; - lanes_38 38; - lanes_39 39; - lanes_40 40; - lanes_41 41; - lanes_42 42; - lanes_43 43; - lanes_44 44; - lanes_45 45; - lanes_46 46; - lanes_47 47; - lanes_48 48; - lanes_49 49; - lanes_50 50; - lanes_51 51; - lanes_52 52; - lanes_53 53; - lanes_54 54; - lanes_55 55; - lanes_56 56; - lanes_57 57; - lanes_58 58; - lanes_59 59; - lanes_60 60; - lanes_61 61; - lanes_62 62; - lanes_63 63; - ); - } - )* - } -} diff --git a/library/portable-simd/crates/test_helpers/src/subnormals.rs b/library/portable-simd/crates/test_helpers/src/subnormals.rs deleted file mode 100644 index ec0f1fb24b936..0000000000000 --- a/library/portable-simd/crates/test_helpers/src/subnormals.rs +++ /dev/null @@ -1,91 +0,0 @@ -pub trait FlushSubnormals: Sized { - fn flush(self) -> Self { - self - } -} - -impl FlushSubnormals for *const T {} -impl FlushSubnormals for *mut T {} - -macro_rules! impl_float { - { $($ty:ty),* } => { - $( - impl FlushSubnormals for $ty { - fn flush(self) -> Self { - let is_f32 = core::mem::size_of::() == 4; - let ppc_flush = is_f32 && cfg!(all( - any(target_arch = "powerpc", all(target_arch = "powerpc64", target_endian = "big")), - target_feature = "altivec", - not(target_feature = "vsx"), - )); - let arm_flush = is_f32 && cfg!(all(target_arch = "arm", target_feature = "neon")); - let flush = ppc_flush || arm_flush; - if flush && self.is_subnormal() { - <$ty>::copysign(0., self) - } else { - self - } - } - } - )* - } -} - -macro_rules! impl_else { - { $($ty:ty),* } => { - $( - impl FlushSubnormals for $ty {} - )* - } -} - -impl_float! { f32, f64 } -impl_else! { i8, i16, i32, i64, isize, u8, u16, u32, u64, usize } - -/// AltiVec should flush subnormal inputs to zero, but QEMU seems to only flush outputs. -/// https://gitlab.com/qemu-project/qemu/-/issues/1779 -#[cfg(all( - any(target_arch = "powerpc", target_arch = "powerpc64"), - target_feature = "altivec" -))] -fn in_buggy_qemu() -> bool { - use std::sync::OnceLock; - static BUGGY: OnceLock = OnceLock::new(); - - fn add(x: f32, y: f32) -> f32 { - #[cfg(target_arch = "powerpc")] - use core::arch::powerpc::*; - #[cfg(target_arch = "powerpc64")] - use core::arch::powerpc64::*; - - let array: [f32; 4] = - unsafe { core::mem::transmute(vec_add(vec_splats(x), vec_splats(y))) }; - array[0] - } - - *BUGGY.get_or_init(|| add(-1.0857398e-38, 0.).is_sign_negative()) -} - -#[cfg(all( - any(target_arch = "powerpc", target_arch = "powerpc64"), - target_feature = "altivec" -))] -pub fn flush_in(x: T) -> T { - if in_buggy_qemu() { - x - } else { - x.flush() - } -} - -#[cfg(not(all( - any(target_arch = "powerpc", target_arch = "powerpc64"), - target_feature = "altivec" -)))] -pub fn flush_in(x: T) -> T { - x.flush() -} - -pub fn flush(x: T) -> T { - x.flush() -} diff --git a/library/portable-simd/crates/test_helpers/src/wasm.rs b/library/portable-simd/crates/test_helpers/src/wasm.rs deleted file mode 100644 index 3f11d67cbf390..0000000000000 --- a/library/portable-simd/crates/test_helpers/src/wasm.rs +++ /dev/null @@ -1,51 +0,0 @@ -//! Strategies for `u128` and `i128`, since proptest doesn't provide them for the wasm target. - -macro_rules! impl_num { - { $name:ident } => { - pub(crate) mod $name { - type InnerStrategy = crate::array::UniformArrayStrategy; - use proptest::strategy::{Strategy, ValueTree, NewTree}; - - - #[must_use = "strategies do nothing unless used"] - #[derive(Clone, Copy, Debug)] - pub struct Any { - strategy: InnerStrategy, - } - - pub struct BinarySearch { - inner: ::Tree, - } - - impl ValueTree for BinarySearch { - type Value = $name; - - fn current(&self) -> $name { - unsafe { core::mem::transmute(self.inner.current()) } - } - - fn simplify(&mut self) -> bool { - self.inner.simplify() - } - - fn complicate(&mut self) -> bool { - self.inner.complicate() - } - } - - impl Strategy for Any { - type Tree = BinarySearch; - type Value = $name; - - fn new_tree(&self, runner: &mut proptest::test_runner::TestRunner) -> NewTree { - Ok(BinarySearch { inner: self.strategy.new_tree(runner)? }) - } - } - - pub const ANY: Any = Any { strategy: InnerStrategy::new(proptest::num::u64::ANY) }; - } - } -} - -impl_num! { u128 } -impl_num! { i128 } diff --git a/library/proc_macro/Cargo.toml b/library/proc_macro/Cargo.toml deleted file mode 100644 index e54a50aa15c61..0000000000000 --- a/library/proc_macro/Cargo.toml +++ /dev/null @@ -1,11 +0,0 @@ -[package] -name = "proc_macro" -version = "0.0.0" -edition = "2021" - -[dependencies] -std = { path = "../std" } -# Workaround: when documenting this crate rustdoc will try to load crate named -# `core` when resolving doc links. Without this line a different `core` will be -# loaded from sysroot causing duplicate lang items and other similar errors. -core = { path = "../core" } diff --git a/library/proc_macro/src/bridge/arena.rs b/library/proc_macro/src/bridge/arena.rs deleted file mode 100644 index f81f2152cd046..0000000000000 --- a/library/proc_macro/src/bridge/arena.rs +++ /dev/null @@ -1,114 +0,0 @@ -//! A minimal arena allocator inspired by `rustc_arena::DroplessArena`. -//! -//! This is unfortunately a minimal re-implementation rather than a dependency -//! as it is difficult to depend on crates from within `proc_macro`, due to it -//! being built at the same time as `std`. - -use std::cell::{Cell, RefCell}; -use std::cmp; -use std::mem::MaybeUninit; -use std::ops::Range; -use std::ptr; -use std::slice; -use std::str; - -// The arenas start with PAGE-sized chunks, and then each new chunk is twice as -// big as its predecessor, up until we reach HUGE_PAGE-sized chunks, whereupon -// we stop growing. This scales well, from arenas that are barely used up to -// arenas that are used for 100s of MiBs. Note also that the chosen sizes match -// the usual sizes of pages and huge pages on Linux. -const PAGE: usize = 4096; -const HUGE_PAGE: usize = 2 * 1024 * 1024; - -/// A minimal arena allocator inspired by `rustc_arena::DroplessArena`. -/// -/// This is unfortunately a complete re-implementation rather than a dependency -/// as it is difficult to depend on crates from within `proc_macro`, due to it -/// being built at the same time as `std`. -/// -/// This arena doesn't have support for allocating anything other than byte -/// slices, as that is all that is necessary. -pub(crate) struct Arena { - start: Cell<*mut MaybeUninit>, - end: Cell<*mut MaybeUninit>, - chunks: RefCell]>>>, -} - -impl Arena { - pub(crate) fn new() -> Self { - Arena { - start: Cell::new(ptr::null_mut()), - end: Cell::new(ptr::null_mut()), - chunks: RefCell::new(Vec::new()), - } - } - - /// Add a new chunk with at least `additional` free bytes. - #[inline(never)] - #[cold] - fn grow(&self, additional: usize) { - let mut chunks = self.chunks.borrow_mut(); - let mut new_cap; - if let Some(last_chunk) = chunks.last_mut() { - // If the previous chunk's len is less than HUGE_PAGE - // bytes, then this chunk will be least double the previous - // chunk's size. - new_cap = last_chunk.len().min(HUGE_PAGE / 2); - new_cap *= 2; - } else { - new_cap = PAGE; - } - // Also ensure that this chunk can fit `additional`. - new_cap = cmp::max(additional, new_cap); - - let mut chunk = Box::new_uninit_slice(new_cap); - let Range { start, end } = chunk.as_mut_ptr_range(); - self.start.set(start); - self.end.set(end); - chunks.push(chunk); - } - - /// Allocates a byte slice with specified size from the current memory - /// chunk. Returns `None` if there is no free space left to satisfy the - /// request. - fn alloc_raw_without_grow(&self, bytes: usize) -> Option<&mut [MaybeUninit]> { - let start = self.start.get().addr(); - let old_end = self.end.get(); - let end = old_end.addr(); - - let new_end = end.checked_sub(bytes)?; - if start <= new_end { - let new_end = old_end.with_addr(new_end); - self.end.set(new_end); - // SAFETY: `bytes` bytes starting at `new_end` were just reserved. - Some(unsafe { slice::from_raw_parts_mut(new_end, bytes) }) - } else { - None - } - } - - fn alloc_raw(&self, bytes: usize) -> &mut [MaybeUninit] { - if bytes == 0 { - return &mut []; - } - - loop { - if let Some(a) = self.alloc_raw_without_grow(bytes) { - break a; - } - // No free space left. Allocate a new chunk to satisfy the request. - // On failure the grow will panic or abort. - self.grow(bytes); - } - } - - #[allow(clippy::mut_from_ref)] // arena allocator - pub(crate) fn alloc_str<'a>(&'a self, string: &str) -> &'a mut str { - let alloc = self.alloc_raw(string.len()); - let bytes = MaybeUninit::copy_from_slice(alloc, string.as_bytes()); - - // SAFETY: we convert from `&str` to `&[u8]`, clone it into the arena, - // and immediately convert the clone back to `&str`. - unsafe { str::from_utf8_unchecked_mut(bytes) } - } -} diff --git a/library/proc_macro/src/bridge/buffer.rs b/library/proc_macro/src/bridge/buffer.rs deleted file mode 100644 index 48030f8d82dca..0000000000000 --- a/library/proc_macro/src/bridge/buffer.rs +++ /dev/null @@ -1,156 +0,0 @@ -//! Buffer management for same-process client<->server communication. - -use std::io::{self, Write}; -use std::mem; -use std::ops::{Deref, DerefMut}; -use std::slice; - -#[repr(C)] -pub struct Buffer { - data: *mut u8, - len: usize, - capacity: usize, - reserve: extern "C" fn(Buffer, usize) -> Buffer, - drop: extern "C" fn(Buffer), -} - -unsafe impl Sync for Buffer {} -unsafe impl Send for Buffer {} - -impl Default for Buffer { - #[inline] - fn default() -> Self { - Self::from(vec![]) - } -} - -impl Deref for Buffer { - type Target = [u8]; - #[inline] - fn deref(&self) -> &[u8] { - unsafe { slice::from_raw_parts(self.data as *const u8, self.len) } - } -} - -impl DerefMut for Buffer { - #[inline] - fn deref_mut(&mut self) -> &mut [u8] { - unsafe { slice::from_raw_parts_mut(self.data, self.len) } - } -} - -impl Buffer { - #[inline] - pub(super) fn new() -> Self { - Self::default() - } - - #[inline] - pub(super) fn clear(&mut self) { - self.len = 0; - } - - #[inline] - pub(super) fn take(&mut self) -> Self { - mem::take(self) - } - - // We have the array method separate from extending from a slice. This is - // because in the case of small arrays, codegen can be more efficient - // (avoiding a memmove call). With extend_from_slice, LLVM at least - // currently is not able to make that optimization. - #[inline] - pub(super) fn extend_from_array(&mut self, xs: &[u8; N]) { - if xs.len() > (self.capacity - self.len) { - let b = self.take(); - *self = (b.reserve)(b, xs.len()); - } - unsafe { - xs.as_ptr().copy_to_nonoverlapping(self.data.add(self.len), xs.len()); - self.len += xs.len(); - } - } - - #[inline] - pub(super) fn extend_from_slice(&mut self, xs: &[u8]) { - if xs.len() > (self.capacity - self.len) { - let b = self.take(); - *self = (b.reserve)(b, xs.len()); - } - unsafe { - xs.as_ptr().copy_to_nonoverlapping(self.data.add(self.len), xs.len()); - self.len += xs.len(); - } - } - - #[inline] - pub(super) fn push(&mut self, v: u8) { - // The code here is taken from Vec::push, and we know that reserve() - // will panic if we're exceeding isize::MAX bytes and so there's no need - // to check for overflow. - if self.len == self.capacity { - let b = self.take(); - *self = (b.reserve)(b, 1); - } - unsafe { - *self.data.add(self.len) = v; - self.len += 1; - } - } -} - -impl Write for Buffer { - #[inline] - fn write(&mut self, xs: &[u8]) -> io::Result { - self.extend_from_slice(xs); - Ok(xs.len()) - } - - #[inline] - fn write_all(&mut self, xs: &[u8]) -> io::Result<()> { - self.extend_from_slice(xs); - Ok(()) - } - - #[inline] - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -impl Drop for Buffer { - #[inline] - fn drop(&mut self) { - let b = self.take(); - (b.drop)(b); - } -} - -impl From> for Buffer { - fn from(mut v: Vec) -> Self { - let (data, len, capacity) = (v.as_mut_ptr(), v.len(), v.capacity()); - mem::forget(v); - - // This utility function is nested in here because it can *only* - // be safely called on `Buffer`s created by *this* `proc_macro`. - fn to_vec(b: Buffer) -> Vec { - unsafe { - let Buffer { data, len, capacity, .. } = b; - mem::forget(b); - Vec::from_raw_parts(data, len, capacity) - } - } - - extern "C" fn reserve(b: Buffer, additional: usize) -> Buffer { - let mut v = to_vec(b); - v.reserve(additional); - Buffer::from(v) - } - - extern "C" fn drop(b: Buffer) { - mem::drop(to_vec(b)); - } - - Buffer { data, len, capacity, reserve, drop } - } -} diff --git a/library/proc_macro/src/bridge/client.rs b/library/proc_macro/src/bridge/client.rs deleted file mode 100644 index faca745e56f74..0000000000000 --- a/library/proc_macro/src/bridge/client.rs +++ /dev/null @@ -1,425 +0,0 @@ -//! Client-side types. - -use super::*; - -use std::cell::RefCell; -use std::marker::PhantomData; -use std::sync::atomic::AtomicU32; - -macro_rules! define_client_handles { - ( - 'owned: $($oty:ident,)* - 'interned: $($ity:ident,)* - ) => { - #[repr(C)] - #[allow(non_snake_case)] - pub(super) struct HandleCounters { - $(pub(super) $oty: AtomicU32,)* - $(pub(super) $ity: AtomicU32,)* - } - - impl HandleCounters { - // FIXME(eddyb) use a reference to the `static COUNTERS`, instead of - // a wrapper `fn` pointer, once `const fn` can reference `static`s. - extern "C" fn get() -> &'static Self { - static COUNTERS: HandleCounters = HandleCounters { - $($oty: AtomicU32::new(1),)* - $($ity: AtomicU32::new(1),)* - }; - &COUNTERS - } - } - - $( - pub(crate) struct $oty { - handle: handle::Handle, - // Prevent Send and Sync impls. `!Send`/`!Sync` is the usual - // way of doing this, but that requires unstable features. - // rust-analyzer uses this code and avoids unstable features. - _marker: PhantomData<*mut ()>, - } - - // Forward `Drop::drop` to the inherent `drop` method. - impl Drop for $oty { - fn drop(&mut self) { - $oty { - handle: self.handle, - _marker: PhantomData, - }.drop(); - } - } - - impl Encode for $oty { - fn encode(self, w: &mut Writer, s: &mut S) { - let handle = self.handle; - mem::forget(self); - handle.encode(w, s); - } - } - - impl Encode for &$oty { - fn encode(self, w: &mut Writer, s: &mut S) { - self.handle.encode(w, s); - } - } - - impl Encode for &mut $oty { - fn encode(self, w: &mut Writer, s: &mut S) { - self.handle.encode(w, s); - } - } - - impl DecodeMut<'_, '_, S> for $oty { - fn decode(r: &mut Reader<'_>, s: &mut S) -> Self { - $oty { - handle: handle::Handle::decode(r, s), - _marker: PhantomData, - } - } - } - )* - - $( - #[derive(Copy, Clone, PartialEq, Eq, Hash)] - pub(crate) struct $ity { - handle: handle::Handle, - // Prevent Send and Sync impls. `!Send`/`!Sync` is the usual - // way of doing this, but that requires unstable features. - // rust-analyzer uses this code and avoids unstable features. - _marker: PhantomData<*mut ()>, - } - - impl Encode for $ity { - fn encode(self, w: &mut Writer, s: &mut S) { - self.handle.encode(w, s); - } - } - - impl DecodeMut<'_, '_, S> for $ity { - fn decode(r: &mut Reader<'_>, s: &mut S) -> Self { - $ity { - handle: handle::Handle::decode(r, s), - _marker: PhantomData, - } - } - } - )* - } -} -with_api_handle_types!(define_client_handles); - -// FIXME(eddyb) generate these impls by pattern-matching on the -// names of methods - also could use the presence of `fn drop` -// to distinguish between 'owned and 'interned, above. -// Alternatively, special "modes" could be listed of types in with_api -// instead of pattern matching on methods, here and in server decl. - -impl Clone for TokenStream { - fn clone(&self) -> Self { - self.clone() - } -} - -impl Clone for SourceFile { - fn clone(&self) -> Self { - self.clone() - } -} - -impl Span { - pub(crate) fn def_site() -> Span { - Bridge::with(|bridge| bridge.globals.def_site) - } - - pub(crate) fn call_site() -> Span { - Bridge::with(|bridge| bridge.globals.call_site) - } - - pub(crate) fn mixed_site() -> Span { - Bridge::with(|bridge| bridge.globals.mixed_site) - } -} - -impl fmt::Debug for Span { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str(&self.debug()) - } -} - -pub(crate) use super::symbol::Symbol; - -macro_rules! define_client_side { - ($($name:ident { - $(fn $method:ident($($arg:ident: $arg_ty:ty),* $(,)?) $(-> $ret_ty:ty)?;)* - }),* $(,)?) => { - $(impl $name { - $(pub(crate) fn $method($($arg: $arg_ty),*) $(-> $ret_ty)? { - Bridge::with(|bridge| { - let mut buf = bridge.cached_buffer.take(); - - buf.clear(); - api_tags::Method::$name(api_tags::$name::$method).encode(&mut buf, &mut ()); - reverse_encode!(buf; $($arg),*); - - buf = bridge.dispatch.call(buf); - - let r = Result::<_, PanicMessage>::decode(&mut &buf[..], &mut ()); - - bridge.cached_buffer = buf; - - r.unwrap_or_else(|e| panic::resume_unwind(e.into())) - }) - })* - })* - } -} -with_api!(self, self, define_client_side); - -struct Bridge<'a> { - /// Reusable buffer (only `clear`-ed, never shrunk), primarily - /// used for making requests. - cached_buffer: Buffer, - - /// Server-side function that the client uses to make requests. - dispatch: closure::Closure<'a, Buffer, Buffer>, - - /// Provided globals for this macro expansion. - globals: ExpnGlobals, -} - -impl<'a> !Send for Bridge<'a> {} -impl<'a> !Sync for Bridge<'a> {} - -#[allow(unsafe_code)] -mod state { - use super::Bridge; - use std::cell::{Cell, RefCell}; - use std::ptr; - - thread_local! { - static BRIDGE_STATE: Cell<*const ()> = const { Cell::new(ptr::null()) }; - } - - pub(super) fn set<'bridge, R>(state: &RefCell>, f: impl FnOnce() -> R) -> R { - struct RestoreOnDrop(*const ()); - impl Drop for RestoreOnDrop { - fn drop(&mut self) { - BRIDGE_STATE.set(self.0); - } - } - - let inner = ptr::from_ref(state).cast(); - let outer = BRIDGE_STATE.replace(inner); - let _restore = RestoreOnDrop(outer); - - f() - } - - pub(super) fn with( - f: impl for<'bridge> FnOnce(Option<&RefCell>>) -> R, - ) -> R { - let state = BRIDGE_STATE.get(); - // SAFETY: the only place where the pointer is set is in `set`. It puts - // back the previous value after the inner call has returned, so we know - // that as long as the pointer is not null, it came from a reference to - // a `RefCell` that outlasts the call to this function. Since `f` - // works the same for any lifetime of the bridge, including the actual - // one, we can lie here and say that the lifetime is `'static` without - // anyone noticing. - let bridge = unsafe { state.cast::>>().as_ref() }; - f(bridge) - } -} - -impl Bridge<'_> { - fn with(f: impl FnOnce(&mut Bridge<'_>) -> R) -> R { - state::with(|state| { - let bridge = state.expect("procedural macro API is used outside of a procedural macro"); - let mut bridge = bridge - .try_borrow_mut() - .expect("procedural macro API is used while it's already in use"); - f(&mut bridge) - }) - } -} - -pub(crate) fn is_available() -> bool { - state::with(|s| s.is_some()) -} - -/// A client-side RPC entry-point, which may be using a different `proc_macro` -/// from the one used by the server, but can be invoked compatibly. -/// -/// Note that the (phantom) `I` ("input") and `O` ("output") type parameters -/// decorate the `Client` with the RPC "interface" of the entry-point, but -/// do not themselves participate in ABI, at all, only facilitate type-checking. -/// -/// E.g. `Client` is the common proc macro interface, -/// used for `#[proc_macro] fn foo(input: TokenStream) -> TokenStream`, -/// indicating that the RPC input and output will be serialized token streams, -/// and forcing the use of APIs that take/return `S::TokenStream`, server-side. -#[repr(C)] -pub struct Client { - // FIXME(eddyb) use a reference to the `static COUNTERS`, instead of - // a wrapper `fn` pointer, once `const fn` can reference `static`s. - pub(super) get_handle_counters: extern "C" fn() -> &'static HandleCounters, - - pub(super) run: extern "C" fn(BridgeConfig<'_>) -> Buffer, - - pub(super) _marker: PhantomData O>, -} - -impl Copy for Client {} -impl Clone for Client { - fn clone(&self) -> Self { - *self - } -} - -fn maybe_install_panic_hook(force_show_panics: bool) { - // Hide the default panic output within `proc_macro` expansions. - // NB. the server can't do this because it may use a different std. - static HIDE_PANICS_DURING_EXPANSION: Once = Once::new(); - HIDE_PANICS_DURING_EXPANSION.call_once(|| { - let prev = panic::take_hook(); - panic::set_hook(Box::new(move |info| { - // We normally report panics by catching unwinds and passing the payload from the - // unwind back to the compiler, but if the panic doesn't unwind we'll abort before - // the compiler has a chance to print an error. So we special-case PanicInfo where - // can_unwind is false. - if force_show_panics || !is_available() || !info.can_unwind() { - prev(info) - } - })); - }); -} - -/// Client-side helper for handling client panics, entering the bridge, -/// deserializing input and serializing output. -// FIXME(eddyb) maybe replace `Bridge::enter` with this? -fn run_client DecodeMut<'a, 's, ()>, R: Encode<()>>( - config: BridgeConfig<'_>, - f: impl FnOnce(A) -> R, -) -> Buffer { - let BridgeConfig { input: mut buf, dispatch, force_show_panics, .. } = config; - - panic::catch_unwind(panic::AssertUnwindSafe(|| { - maybe_install_panic_hook(force_show_panics); - - // Make sure the symbol store is empty before decoding inputs. - Symbol::invalidate_all(); - - let reader = &mut &buf[..]; - let (globals, input) = <(ExpnGlobals, A)>::decode(reader, &mut ()); - - // Put the buffer we used for input back in the `Bridge` for requests. - let state = RefCell::new(Bridge { cached_buffer: buf.take(), dispatch, globals }); - - let output = state::set(&state, || f(input)); - - // Take the `cached_buffer` back out, for the output value. - buf = RefCell::into_inner(state).cached_buffer; - - // HACK(eddyb) Separate encoding a success value (`Ok(output)`) - // from encoding a panic (`Err(e: PanicMessage)`) to avoid - // having handles outside the `bridge.enter(|| ...)` scope, and - // to catch panics that could happen while encoding the success. - // - // Note that panics should be impossible beyond this point, but - // this is defensively trying to avoid any accidental panicking - // reaching the `extern "C"` (which should `abort` but might not - // at the moment, so this is also potentially preventing UB). - buf.clear(); - Ok::<_, ()>(output).encode(&mut buf, &mut ()); - })) - .map_err(PanicMessage::from) - .unwrap_or_else(|e| { - buf.clear(); - Err::<(), _>(e).encode(&mut buf, &mut ()); - }); - - // Now that a response has been serialized, invalidate all symbols - // registered with the interner. - Symbol::invalidate_all(); - buf -} - -impl Client { - pub const fn expand1(f: impl Fn(crate::TokenStream) -> crate::TokenStream + Copy) -> Self { - Client { - get_handle_counters: HandleCounters::get, - run: super::selfless_reify::reify_to_extern_c_fn_hrt_bridge(move |bridge| { - run_client(bridge, |input| f(crate::TokenStream(Some(input))).0) - }), - _marker: PhantomData, - } - } -} - -impl Client<(crate::TokenStream, crate::TokenStream), crate::TokenStream> { - pub const fn expand2( - f: impl Fn(crate::TokenStream, crate::TokenStream) -> crate::TokenStream + Copy, - ) -> Self { - Client { - get_handle_counters: HandleCounters::get, - run: super::selfless_reify::reify_to_extern_c_fn_hrt_bridge(move |bridge| { - run_client(bridge, |(input, input2)| { - f(crate::TokenStream(Some(input)), crate::TokenStream(Some(input2))).0 - }) - }), - _marker: PhantomData, - } - } -} - -#[repr(C)] -#[derive(Copy, Clone)] -pub enum ProcMacro { - CustomDerive { - trait_name: &'static str, - attributes: &'static [&'static str], - client: Client, - }, - - Attr { - name: &'static str, - client: Client<(crate::TokenStream, crate::TokenStream), crate::TokenStream>, - }, - - Bang { - name: &'static str, - client: Client, - }, -} - -impl ProcMacro { - pub fn name(&self) -> &'static str { - match self { - ProcMacro::CustomDerive { trait_name, .. } => trait_name, - ProcMacro::Attr { name, .. } => name, - ProcMacro::Bang { name, .. } => name, - } - } - - pub const fn custom_derive( - trait_name: &'static str, - attributes: &'static [&'static str], - expand: impl Fn(crate::TokenStream) -> crate::TokenStream + Copy, - ) -> Self { - ProcMacro::CustomDerive { trait_name, attributes, client: Client::expand1(expand) } - } - - pub const fn attr( - name: &'static str, - expand: impl Fn(crate::TokenStream, crate::TokenStream) -> crate::TokenStream + Copy, - ) -> Self { - ProcMacro::Attr { name, client: Client::expand2(expand) } - } - - pub const fn bang( - name: &'static str, - expand: impl Fn(crate::TokenStream) -> crate::TokenStream + Copy, - ) -> Self { - ProcMacro::Bang { name, client: Client::expand1(expand) } - } -} diff --git a/library/proc_macro/src/bridge/closure.rs b/library/proc_macro/src/bridge/closure.rs deleted file mode 100644 index d371ae3cea098..0000000000000 --- a/library/proc_macro/src/bridge/closure.rs +++ /dev/null @@ -1,32 +0,0 @@ -//! Closure type (equivalent to `&mut dyn FnMut(A) -> R`) that's `repr(C)`. - -use std::marker::PhantomData; - -#[repr(C)] -pub struct Closure<'a, A, R> { - call: unsafe extern "C" fn(*mut Env, A) -> R, - env: *mut Env, - // Prevent Send and Sync impls. `!Send`/`!Sync` is the usual way of doing - // this, but that requires unstable features. rust-analyzer uses this code - // and avoids unstable features. - // - // The `'a` lifetime parameter represents the lifetime of `Env`. - _marker: PhantomData<*mut &'a mut ()>, -} - -struct Env; - -impl<'a, A, R, F: FnMut(A) -> R> From<&'a mut F> for Closure<'a, A, R> { - fn from(f: &'a mut F) -> Self { - unsafe extern "C" fn call R>(env: *mut Env, arg: A) -> R { - (*(env as *mut _ as *mut F))(arg) - } - Closure { call: call::, env: f as *mut _ as *mut Env, _marker: PhantomData } - } -} - -impl<'a, A, R> Closure<'a, A, R> { - pub fn call(&mut self, arg: A) -> R { - unsafe { (self.call)(self.env, arg) } - } -} diff --git a/library/proc_macro/src/bridge/fxhash.rs b/library/proc_macro/src/bridge/fxhash.rs deleted file mode 100644 index f4e9054419721..0000000000000 --- a/library/proc_macro/src/bridge/fxhash.rs +++ /dev/null @@ -1,115 +0,0 @@ -//! This is a copy of the `rustc_hash` crate, adapted to work as a module. -//! -//! If in the future it becomes more reasonable to add dependencies to -//! `proc_macro`, this module should be removed and replaced with a dependency -//! on the `rustc_hash` crate. - -use std::collections::HashMap; -use std::hash::BuildHasherDefault; -use std::hash::Hasher; -use std::mem::size_of; -use std::ops::BitXor; - -/// Type alias for a hashmap using the `fx` hash algorithm. -pub type FxHashMap = HashMap>; - -/// A speedy hash algorithm for use within rustc. The hashmap in alloc by -/// default uses SipHash which isn't quite as speedy as we want. In the compiler -/// we're not really worried about DOS attempts, so we use a fast -/// non-cryptographic hash. -/// -/// This is the same as the algorithm used by Firefox -- which is a homespun -/// one not based on any widely-known algorithm -- though modified to produce -/// 64-bit hash values instead of 32-bit hash values. It consistently -/// out-performs an FNV-based hash within rustc itself -- the collision rate is -/// similar or slightly worse than FNV, but the speed of the hash function -/// itself is much higher because it works on up to 8 bytes at a time. -pub struct FxHasher { - hash: usize, -} - -#[cfg(target_pointer_width = "32")] -const K: usize = 0x9e3779b9; -#[cfg(target_pointer_width = "64")] -const K: usize = 0x517cc1b727220a95; - -impl Default for FxHasher { - #[inline] - fn default() -> FxHasher { - FxHasher { hash: 0 } - } -} - -impl FxHasher { - #[inline] - fn add_to_hash(&mut self, i: usize) { - self.hash = self.hash.rotate_left(5).bitxor(i).wrapping_mul(K); - } -} - -impl Hasher for FxHasher { - #[inline] - fn write(&mut self, mut bytes: &[u8]) { - #[cfg(target_pointer_width = "32")] - let read_usize = |bytes: &[u8]| u32::from_ne_bytes(bytes[..4].try_into().unwrap()); - #[cfg(target_pointer_width = "64")] - let read_usize = |bytes: &[u8]| u64::from_ne_bytes(bytes[..8].try_into().unwrap()); - - let mut hash = FxHasher { hash: self.hash }; - assert!(size_of::() <= 8); - while bytes.len() >= size_of::() { - hash.add_to_hash(read_usize(bytes) as usize); - bytes = &bytes[size_of::()..]; - } - if (size_of::() > 4) && (bytes.len() >= 4) { - hash.add_to_hash(u32::from_ne_bytes(bytes[..4].try_into().unwrap()) as usize); - bytes = &bytes[4..]; - } - if (size_of::() > 2) && bytes.len() >= 2 { - hash.add_to_hash(u16::from_ne_bytes(bytes[..2].try_into().unwrap()) as usize); - bytes = &bytes[2..]; - } - if (size_of::() > 1) && bytes.len() >= 1 { - hash.add_to_hash(bytes[0] as usize); - } - self.hash = hash.hash; - } - - #[inline] - fn write_u8(&mut self, i: u8) { - self.add_to_hash(i as usize); - } - - #[inline] - fn write_u16(&mut self, i: u16) { - self.add_to_hash(i as usize); - } - - #[inline] - fn write_u32(&mut self, i: u32) { - self.add_to_hash(i as usize); - } - - #[cfg(target_pointer_width = "32")] - #[inline] - fn write_u64(&mut self, i: u64) { - self.add_to_hash(i as usize); - self.add_to_hash((i >> 32) as usize); - } - - #[cfg(target_pointer_width = "64")] - #[inline] - fn write_u64(&mut self, i: u64) { - self.add_to_hash(i as usize); - } - - #[inline] - fn write_usize(&mut self, i: usize) { - self.add_to_hash(i); - } - - #[inline] - fn finish(&self) -> u64 { - self.hash as u64 - } -} diff --git a/library/proc_macro/src/bridge/handle.rs b/library/proc_macro/src/bridge/handle.rs deleted file mode 100644 index 8c53bb609f60c..0000000000000 --- a/library/proc_macro/src/bridge/handle.rs +++ /dev/null @@ -1,75 +0,0 @@ -//! Server-side handles and storage for per-handle data. - -use std::collections::BTreeMap; -use std::hash::Hash; -use std::num::NonZero; -use std::ops::{Index, IndexMut}; -use std::sync::atomic::{AtomicU32, Ordering}; - -use super::fxhash::FxHashMap; - -pub(super) type Handle = NonZero; - -/// A store that associates values of type `T` with numeric handles. A value can -/// be looked up using its handle. -pub(super) struct OwnedStore { - counter: &'static AtomicU32, - data: BTreeMap, -} - -impl OwnedStore { - pub(super) fn new(counter: &'static AtomicU32) -> Self { - // Ensure the handle counter isn't 0, which would panic later, - // when `NonZero::new` (aka `Handle::new`) is called in `alloc`. - assert_ne!(counter.load(Ordering::Relaxed), 0); - - OwnedStore { counter, data: BTreeMap::new() } - } -} - -impl OwnedStore { - pub(super) fn alloc(&mut self, x: T) -> Handle { - let counter = self.counter.fetch_add(1, Ordering::Relaxed); - let handle = Handle::new(counter).expect("`proc_macro` handle counter overflowed"); - assert!(self.data.insert(handle, x).is_none()); - handle - } - - pub(super) fn take(&mut self, h: Handle) -> T { - self.data.remove(&h).expect("use-after-free in `proc_macro` handle") - } -} - -impl Index for OwnedStore { - type Output = T; - fn index(&self, h: Handle) -> &T { - self.data.get(&h).expect("use-after-free in `proc_macro` handle") - } -} - -impl IndexMut for OwnedStore { - fn index_mut(&mut self, h: Handle) -> &mut T { - self.data.get_mut(&h).expect("use-after-free in `proc_macro` handle") - } -} - -/// Like `OwnedStore`, but avoids storing any value more than once. -pub(super) struct InternedStore { - owned: OwnedStore, - interner: FxHashMap, -} - -impl InternedStore { - pub(super) fn new(counter: &'static AtomicU32) -> Self { - InternedStore { owned: OwnedStore::new(counter), interner: FxHashMap::default() } - } - - pub(super) fn alloc(&mut self, x: T) -> Handle { - let owned = &mut self.owned; - *self.interner.entry(x).or_insert_with(|| owned.alloc(x)) - } - - pub(super) fn copy(&mut self, h: Handle) -> T { - self.owned[h] - } -} diff --git a/library/proc_macro/src/bridge/mod.rs b/library/proc_macro/src/bridge/mod.rs deleted file mode 100644 index 8553e8d5e4fd6..0000000000000 --- a/library/proc_macro/src/bridge/mod.rs +++ /dev/null @@ -1,548 +0,0 @@ -//! Internal interface for communicating between a `proc_macro` client -//! (a proc macro crate) and a `proc_macro` server (a compiler front-end). -//! -//! Serialization (with C ABI buffers) and unique integer handles are employed -//! to allow safely interfacing between two copies of `proc_macro` built -//! (from the same source) by different compilers with potentially mismatching -//! Rust ABIs (e.g., stage0/bin/rustc vs stage1/bin/rustc during bootstrap). - -#![deny(unsafe_code)] - -use crate::{Delimiter, Level, Spacing}; -use std::fmt; -use std::hash::Hash; -use std::marker; -use std::mem; -use std::ops::Bound; -use std::ops::Range; -use std::panic; -use std::sync::Once; -use std::thread; - -/// Higher-order macro describing the server RPC API, allowing automatic -/// generation of type-safe Rust APIs, both client-side and server-side. -/// -/// `with_api!(MySelf, my_self, my_macro)` expands to: -/// ```rust,ignore (pseudo-code) -/// my_macro! { -/// // ... -/// Literal { -/// // ... -/// fn character(ch: char) -> MySelf::Literal; -/// // ... -/// fn span(my_self: &MySelf::Literal) -> MySelf::Span; -/// fn set_span(my_self: &mut MySelf::Literal, span: MySelf::Span); -/// }, -/// // ... -/// } -/// ``` -/// -/// The first two arguments serve to customize the arguments names -/// and argument/return types, to enable several different usecases: -/// -/// If `my_self` is just `self`, then each `fn` signature can be used -/// as-is for a method. If it's anything else (`self_` in practice), -/// then the signatures don't have a special `self` argument, and -/// can, therefore, have a different one introduced. -/// -/// If `MySelf` is just `Self`, then the types are only valid inside -/// a trait or a trait impl, where the trait has associated types -/// for each of the API types. If non-associated types are desired, -/// a module name (`self` in practice) can be used instead of `Self`. -macro_rules! with_api { - ($S:ident, $self:ident, $m:ident) => { - $m! { - FreeFunctions { - fn drop($self: $S::FreeFunctions); - fn injected_env_var(var: &str) -> Option; - fn track_env_var(var: &str, value: Option<&str>); - fn track_path(path: &str); - fn literal_from_str(s: &str) -> Result, ()>; - fn emit_diagnostic(diagnostic: Diagnostic<$S::Span>); - }, - TokenStream { - fn drop($self: $S::TokenStream); - fn clone($self: &$S::TokenStream) -> $S::TokenStream; - fn is_empty($self: &$S::TokenStream) -> bool; - fn expand_expr($self: &$S::TokenStream) -> Result<$S::TokenStream, ()>; - fn from_str(src: &str) -> $S::TokenStream; - fn to_string($self: &$S::TokenStream) -> String; - fn from_token_tree( - tree: TokenTree<$S::TokenStream, $S::Span, $S::Symbol>, - ) -> $S::TokenStream; - fn concat_trees( - base: Option<$S::TokenStream>, - trees: Vec>, - ) -> $S::TokenStream; - fn concat_streams( - base: Option<$S::TokenStream>, - streams: Vec<$S::TokenStream>, - ) -> $S::TokenStream; - fn into_trees( - $self: $S::TokenStream - ) -> Vec>; - }, - SourceFile { - fn drop($self: $S::SourceFile); - fn clone($self: &$S::SourceFile) -> $S::SourceFile; - fn eq($self: &$S::SourceFile, other: &$S::SourceFile) -> bool; - fn path($self: &$S::SourceFile) -> String; - fn is_real($self: &$S::SourceFile) -> bool; - }, - Span { - fn debug($self: $S::Span) -> String; - fn source_file($self: $S::Span) -> $S::SourceFile; - fn parent($self: $S::Span) -> Option<$S::Span>; - fn source($self: $S::Span) -> $S::Span; - fn byte_range($self: $S::Span) -> Range; - fn start($self: $S::Span) -> $S::Span; - fn end($self: $S::Span) -> $S::Span; - fn line($self: $S::Span) -> usize; - fn column($self: $S::Span) -> usize; - fn join($self: $S::Span, other: $S::Span) -> Option<$S::Span>; - fn subspan($self: $S::Span, start: Bound, end: Bound) -> Option<$S::Span>; - fn resolved_at($self: $S::Span, at: $S::Span) -> $S::Span; - fn source_text($self: $S::Span) -> Option; - fn save_span($self: $S::Span) -> usize; - fn recover_proc_macro_span(id: usize) -> $S::Span; - }, - Symbol { - fn normalize_and_validate_ident(string: &str) -> Result<$S::Symbol, ()>; - }, - } - }; -} - -// Similar to `with_api`, but only lists the types requiring handles, and they -// are divided into the two storage categories. -macro_rules! with_api_handle_types { - ($m:ident) => { - $m! { - 'owned: - FreeFunctions, - TokenStream, - SourceFile, - - 'interned: - Span, - // Symbol is handled manually - } - }; -} - -// FIXME(eddyb) this calls `encode` for each argument, but in reverse, -// to match the ordering in `reverse_decode`. -macro_rules! reverse_encode { - ($writer:ident;) => {}; - ($writer:ident; $first:ident $(, $rest:ident)*) => { - reverse_encode!($writer; $($rest),*); - $first.encode(&mut $writer, &mut ()); - } -} - -// FIXME(eddyb) this calls `decode` for each argument, but in reverse, -// to avoid borrow conflicts from borrows started by `&mut` arguments. -macro_rules! reverse_decode { - ($reader:ident, $s:ident;) => {}; - ($reader:ident, $s:ident; $first:ident: $first_ty:ty $(, $rest:ident: $rest_ty:ty)*) => { - reverse_decode!($reader, $s; $($rest: $rest_ty),*); - let $first = <$first_ty>::decode(&mut $reader, $s); - } -} - -#[allow(unsafe_code)] -mod arena; -#[allow(unsafe_code)] -mod buffer; -#[deny(unsafe_code)] -pub mod client; -#[allow(unsafe_code)] -mod closure; -#[forbid(unsafe_code)] -mod fxhash; -#[forbid(unsafe_code)] -mod handle; -#[macro_use] -#[forbid(unsafe_code)] -mod rpc; -#[allow(unsafe_code)] -mod selfless_reify; -#[forbid(unsafe_code)] -pub mod server; -#[allow(unsafe_code)] -mod symbol; - -use buffer::Buffer; -pub use rpc::PanicMessage; -use rpc::{Decode, DecodeMut, Encode, Reader, Writer}; - -/// Configuration for establishing an active connection between a server and a -/// client. The server creates the bridge config (`run_server` in `server.rs`), -/// then passes it to the client through the function pointer in the `run` field -/// of `client::Client`. The client constructs a local `Bridge` from the config -/// in TLS during its execution (`Bridge::{enter, with}` in `client.rs`). -#[repr(C)] -pub struct BridgeConfig<'a> { - /// Buffer used to pass initial input to the client. - input: Buffer, - - /// Server-side function that the client uses to make requests. - dispatch: closure::Closure<'a, Buffer, Buffer>, - - /// If 'true', always invoke the default panic hook - force_show_panics: bool, - - // Prevent Send and Sync impls. `!Send`/`!Sync` is the usual way of doing - // this, but that requires unstable features. rust-analyzer uses this code - // and avoids unstable features. - _marker: marker::PhantomData<*mut ()>, -} - -#[forbid(unsafe_code)] -#[allow(non_camel_case_types)] -mod api_tags { - use super::rpc::{DecodeMut, Encode, Reader, Writer}; - - macro_rules! declare_tags { - ($($name:ident { - $(fn $method:ident($($arg:ident: $arg_ty:ty),* $(,)?) $(-> $ret_ty:ty)*;)* - }),* $(,)?) => { - $( - pub(super) enum $name { - $($method),* - } - rpc_encode_decode!(enum $name { $($method),* }); - )* - - pub(super) enum Method { - $($name($name)),* - } - rpc_encode_decode!(enum Method { $($name(m)),* }); - } - } - with_api!(self, self, declare_tags); -} - -/// Helper to wrap associated types to allow trait impl dispatch. -/// That is, normally a pair of impls for `T::Foo` and `T::Bar` -/// can overlap, but if the impls are, instead, on types like -/// `Marked` and `Marked`, they can't. -trait Mark { - type Unmarked; - fn mark(unmarked: Self::Unmarked) -> Self; -} - -/// Unwrap types wrapped by `Mark::mark` (see `Mark` for details). -trait Unmark { - type Unmarked; - fn unmark(self) -> Self::Unmarked; -} - -#[derive(Copy, Clone, PartialEq, Eq, Hash)] -struct Marked { - value: T, - _marker: marker::PhantomData, -} - -impl Mark for Marked { - type Unmarked = T; - fn mark(unmarked: Self::Unmarked) -> Self { - Marked { value: unmarked, _marker: marker::PhantomData } - } -} -impl Unmark for Marked { - type Unmarked = T; - fn unmark(self) -> Self::Unmarked { - self.value - } -} -impl<'a, T, M> Unmark for &'a Marked { - type Unmarked = &'a T; - fn unmark(self) -> Self::Unmarked { - &self.value - } -} -impl<'a, T, M> Unmark for &'a mut Marked { - type Unmarked = &'a mut T; - fn unmark(self) -> Self::Unmarked { - &mut self.value - } -} - -impl Mark for Vec { - type Unmarked = Vec; - fn mark(unmarked: Self::Unmarked) -> Self { - // Should be a no-op due to std's in-place collect optimizations. - unmarked.into_iter().map(T::mark).collect() - } -} -impl Unmark for Vec { - type Unmarked = Vec; - fn unmark(self) -> Self::Unmarked { - // Should be a no-op due to std's in-place collect optimizations. - self.into_iter().map(T::unmark).collect() - } -} - -macro_rules! mark_noop { - ($($ty:ty),* $(,)?) => { - $( - impl Mark for $ty { - type Unmarked = Self; - fn mark(unmarked: Self::Unmarked) -> Self { - unmarked - } - } - impl Unmark for $ty { - type Unmarked = Self; - fn unmark(self) -> Self::Unmarked { - self - } - } - )* - } -} -mark_noop! { - (), - bool, - char, - &'_ [u8], - &'_ str, - String, - u8, - usize, - Delimiter, - LitKind, - Level, - Spacing, -} - -rpc_encode_decode!( - enum Delimiter { - Parenthesis, - Brace, - Bracket, - None, - } -); -rpc_encode_decode!( - enum Level { - Error, - Warning, - Note, - Help, - } -); -rpc_encode_decode!( - enum Spacing { - Alone, - Joint, - } -); - -#[derive(Copy, Clone, Eq, PartialEq, Debug)] -pub enum LitKind { - Byte, - Char, - Integer, - Float, - Str, - StrRaw(u8), - ByteStr, - ByteStrRaw(u8), - CStr, - CStrRaw(u8), - // This should have an `ErrorGuaranteed`, except that type isn't available - // in this crate. (Imagine it is there.) Hence the `WithGuar` suffix. Must - // only be constructed in `LitKind::from_internal`, where an - // `ErrorGuaranteed` is available. - ErrWithGuar, -} - -rpc_encode_decode!( - enum LitKind { - Byte, - Char, - Integer, - Float, - Str, - StrRaw(n), - ByteStr, - ByteStrRaw(n), - CStr, - CStrRaw(n), - ErrWithGuar, - } -); - -macro_rules! mark_compound { - (struct $name:ident <$($T:ident),+> { $($field:ident),* $(,)? }) => { - impl<$($T: Mark),+> Mark for $name <$($T),+> { - type Unmarked = $name <$($T::Unmarked),+>; - fn mark(unmarked: Self::Unmarked) -> Self { - $name { - $($field: Mark::mark(unmarked.$field)),* - } - } - } - - impl<$($T: Unmark),+> Unmark for $name <$($T),+> { - type Unmarked = $name <$($T::Unmarked),+>; - fn unmark(self) -> Self::Unmarked { - $name { - $($field: Unmark::unmark(self.$field)),* - } - } - } - }; - (enum $name:ident <$($T:ident),+> { $($variant:ident $(($field:ident))?),* $(,)? }) => { - impl<$($T: Mark),+> Mark for $name <$($T),+> { - type Unmarked = $name <$($T::Unmarked),+>; - fn mark(unmarked: Self::Unmarked) -> Self { - match unmarked { - $($name::$variant $(($field))? => { - $name::$variant $((Mark::mark($field)))? - })* - } - } - } - - impl<$($T: Unmark),+> Unmark for $name <$($T),+> { - type Unmarked = $name <$($T::Unmarked),+>; - fn unmark(self) -> Self::Unmarked { - match self { - $($name::$variant $(($field))? => { - $name::$variant $((Unmark::unmark($field)))? - })* - } - } - } - } -} - -macro_rules! compound_traits { - ($($t:tt)*) => { - rpc_encode_decode!($($t)*); - mark_compound!($($t)*); - }; -} - -compound_traits!( - enum Bound { - Included(x), - Excluded(x), - Unbounded, - } -); - -compound_traits!( - enum Option { - Some(t), - None, - } -); - -compound_traits!( - enum Result { - Ok(t), - Err(e), - } -); - -#[derive(Copy, Clone)] -pub struct DelimSpan { - pub open: Span, - pub close: Span, - pub entire: Span, -} - -impl DelimSpan { - pub fn from_single(span: Span) -> Self { - DelimSpan { open: span, close: span, entire: span } - } -} - -compound_traits!(struct DelimSpan { open, close, entire }); - -#[derive(Clone)] -pub struct Group { - pub delimiter: Delimiter, - pub stream: Option, - pub span: DelimSpan, -} - -compound_traits!(struct Group { delimiter, stream, span }); - -#[derive(Clone)] -pub struct Punct { - pub ch: u8, - pub joint: bool, - pub span: Span, -} - -compound_traits!(struct Punct { ch, joint, span }); - -#[derive(Copy, Clone, Eq, PartialEq)] -pub struct Ident { - pub sym: Symbol, - pub is_raw: bool, - pub span: Span, -} - -compound_traits!(struct Ident { sym, is_raw, span }); - -#[derive(Clone, Eq, PartialEq)] -pub struct Literal { - pub kind: LitKind, - pub symbol: Symbol, - pub suffix: Option, - pub span: Span, -} - -compound_traits!(struct Literal { kind, symbol, suffix, span }); - -#[derive(Clone)] -pub enum TokenTree { - Group(Group), - Punct(Punct), - Ident(Ident), - Literal(Literal), -} - -compound_traits!( - enum TokenTree { - Group(tt), - Punct(tt), - Ident(tt), - Literal(tt), - } -); - -#[derive(Clone, Debug)] -pub struct Diagnostic { - pub level: Level, - pub message: String, - pub spans: Vec, - pub children: Vec>, -} - -compound_traits!( - struct Diagnostic { level, message, spans, children } -); - -/// Globals provided alongside the initial inputs for a macro expansion. -/// Provides values such as spans which are used frequently to avoid RPC. -#[derive(Clone)] -pub struct ExpnGlobals { - pub def_site: Span, - pub call_site: Span, - pub mixed_site: Span, -} - -compound_traits!( - struct ExpnGlobals { def_site, call_site, mixed_site } -); - -compound_traits!( - struct Range { start, end } -); diff --git a/library/proc_macro/src/bridge/rpc.rs b/library/proc_macro/src/bridge/rpc.rs deleted file mode 100644 index 6d75a5a627c82..0000000000000 --- a/library/proc_macro/src/bridge/rpc.rs +++ /dev/null @@ -1,303 +0,0 @@ -//! Serialization for client-server communication. - -use std::any::Any; -use std::io::Write; -use std::num::NonZero; -use std::str; - -pub(super) type Writer = super::buffer::Buffer; - -pub(super) trait Encode: Sized { - fn encode(self, w: &mut Writer, s: &mut S); -} - -pub(super) type Reader<'a> = &'a [u8]; - -pub(super) trait Decode<'a, 's, S>: Sized { - fn decode(r: &mut Reader<'a>, s: &'s S) -> Self; -} - -pub(super) trait DecodeMut<'a, 's, S>: Sized { - fn decode(r: &mut Reader<'a>, s: &'s mut S) -> Self; -} - -macro_rules! rpc_encode_decode { - (le $ty:ty) => { - impl Encode for $ty { - fn encode(self, w: &mut Writer, _: &mut S) { - w.extend_from_array(&self.to_le_bytes()); - } - } - - impl DecodeMut<'_, '_, S> for $ty { - fn decode(r: &mut Reader<'_>, _: &mut S) -> Self { - const N: usize = ::std::mem::size_of::<$ty>(); - - let mut bytes = [0; N]; - bytes.copy_from_slice(&r[..N]); - *r = &r[N..]; - - Self::from_le_bytes(bytes) - } - } - }; - (struct $name:ident $(<$($T:ident),+>)? { $($field:ident),* $(,)? }) => { - impl),+)?> Encode for $name $(<$($T),+>)? { - fn encode(self, w: &mut Writer, s: &mut S) { - $(self.$field.encode(w, s);)* - } - } - - impl<'a, S, $($($T: for<'s> DecodeMut<'a, 's, S>),+)?> DecodeMut<'a, '_, S> - for $name $(<$($T),+>)? - { - fn decode(r: &mut Reader<'a>, s: &mut S) -> Self { - $name { - $($field: DecodeMut::decode(r, s)),* - } - } - } - }; - (enum $name:ident $(<$($T:ident),+>)? { $($variant:ident $(($field:ident))*),* $(,)? }) => { - impl),+)?> Encode for $name $(<$($T),+>)? { - fn encode(self, w: &mut Writer, s: &mut S) { - // HACK(eddyb): `Tag` enum duplicated between the - // two impls as there's no other place to stash it. - #[allow(non_upper_case_globals)] - mod tag { - #[repr(u8)] enum Tag { $($variant),* } - - $(pub const $variant: u8 = Tag::$variant as u8;)* - } - - match self { - $($name::$variant $(($field))* => { - tag::$variant.encode(w, s); - $($field.encode(w, s);)* - })* - } - } - } - - impl<'a, S, $($($T: for<'s> DecodeMut<'a, 's, S>),+)?> DecodeMut<'a, '_, S> - for $name $(<$($T),+>)? - { - fn decode(r: &mut Reader<'a>, s: &mut S) -> Self { - // HACK(eddyb): `Tag` enum duplicated between the - // two impls as there's no other place to stash it. - #[allow(non_upper_case_globals)] - mod tag { - #[repr(u8)] enum Tag { $($variant),* } - - $(pub const $variant: u8 = Tag::$variant as u8;)* - } - - match u8::decode(r, s) { - $(tag::$variant => { - $(let $field = DecodeMut::decode(r, s);)* - $name::$variant $(($field))* - })* - _ => unreachable!(), - } - } - } - } -} - -impl Encode for () { - fn encode(self, _: &mut Writer, _: &mut S) {} -} - -impl DecodeMut<'_, '_, S> for () { - fn decode(_: &mut Reader<'_>, _: &mut S) -> Self {} -} - -impl Encode for u8 { - fn encode(self, w: &mut Writer, _: &mut S) { - w.push(self); - } -} - -impl DecodeMut<'_, '_, S> for u8 { - fn decode(r: &mut Reader<'_>, _: &mut S) -> Self { - let x = r[0]; - *r = &r[1..]; - x - } -} - -rpc_encode_decode!(le u32); -rpc_encode_decode!(le usize); - -impl Encode for bool { - fn encode(self, w: &mut Writer, s: &mut S) { - (self as u8).encode(w, s); - } -} - -impl DecodeMut<'_, '_, S> for bool { - fn decode(r: &mut Reader<'_>, s: &mut S) -> Self { - match u8::decode(r, s) { - 0 => false, - 1 => true, - _ => unreachable!(), - } - } -} - -impl Encode for char { - fn encode(self, w: &mut Writer, s: &mut S) { - (self as u32).encode(w, s); - } -} - -impl DecodeMut<'_, '_, S> for char { - fn decode(r: &mut Reader<'_>, s: &mut S) -> Self { - char::from_u32(u32::decode(r, s)).unwrap() - } -} - -impl Encode for NonZero { - fn encode(self, w: &mut Writer, s: &mut S) { - self.get().encode(w, s); - } -} - -impl DecodeMut<'_, '_, S> for NonZero { - fn decode(r: &mut Reader<'_>, s: &mut S) -> Self { - Self::new(u32::decode(r, s)).unwrap() - } -} - -impl, B: Encode> Encode for (A, B) { - fn encode(self, w: &mut Writer, s: &mut S) { - self.0.encode(w, s); - self.1.encode(w, s); - } -} - -impl<'a, S, A: for<'s> DecodeMut<'a, 's, S>, B: for<'s> DecodeMut<'a, 's, S>> DecodeMut<'a, '_, S> - for (A, B) -{ - fn decode(r: &mut Reader<'a>, s: &mut S) -> Self { - (DecodeMut::decode(r, s), DecodeMut::decode(r, s)) - } -} - -impl Encode for &[u8] { - fn encode(self, w: &mut Writer, s: &mut S) { - self.len().encode(w, s); - w.write_all(self).unwrap(); - } -} - -impl<'a, S> DecodeMut<'a, '_, S> for &'a [u8] { - fn decode(r: &mut Reader<'a>, s: &mut S) -> Self { - let len = usize::decode(r, s); - let xs = &r[..len]; - *r = &r[len..]; - xs - } -} - -impl Encode for &str { - fn encode(self, w: &mut Writer, s: &mut S) { - self.as_bytes().encode(w, s); - } -} - -impl<'a, S> DecodeMut<'a, '_, S> for &'a str { - fn decode(r: &mut Reader<'a>, s: &mut S) -> Self { - str::from_utf8(<&[u8]>::decode(r, s)).unwrap() - } -} - -impl Encode for String { - fn encode(self, w: &mut Writer, s: &mut S) { - self[..].encode(w, s); - } -} - -impl DecodeMut<'_, '_, S> for String { - fn decode(r: &mut Reader<'_>, s: &mut S) -> Self { - <&str>::decode(r, s).to_string() - } -} - -impl> Encode for Vec { - fn encode(self, w: &mut Writer, s: &mut S) { - self.len().encode(w, s); - for x in self { - x.encode(w, s); - } - } -} - -impl<'a, S, T: for<'s> DecodeMut<'a, 's, S>> DecodeMut<'a, '_, S> for Vec { - fn decode(r: &mut Reader<'a>, s: &mut S) -> Self { - let len = usize::decode(r, s); - let mut vec = Vec::with_capacity(len); - for _ in 0..len { - vec.push(T::decode(r, s)); - } - vec - } -} - -/// Simplified version of panic payloads, ignoring -/// types other than `&'static str` and `String`. -pub enum PanicMessage { - StaticStr(&'static str), - String(String), - Unknown, -} - -impl From> for PanicMessage { - fn from(payload: Box) -> Self { - if let Some(s) = payload.downcast_ref::<&'static str>() { - return PanicMessage::StaticStr(s); - } - if let Ok(s) = payload.downcast::() { - return PanicMessage::String(*s); - } - PanicMessage::Unknown - } -} - -impl Into> for PanicMessage { - fn into(self) -> Box { - match self { - PanicMessage::StaticStr(s) => Box::new(s), - PanicMessage::String(s) => Box::new(s), - PanicMessage::Unknown => { - struct UnknownPanicMessage; - Box::new(UnknownPanicMessage) - } - } - } -} - -impl PanicMessage { - pub fn as_str(&self) -> Option<&str> { - match self { - PanicMessage::StaticStr(s) => Some(s), - PanicMessage::String(s) => Some(s), - PanicMessage::Unknown => None, - } - } -} - -impl Encode for PanicMessage { - fn encode(self, w: &mut Writer, s: &mut S) { - self.as_str().encode(w, s); - } -} - -impl DecodeMut<'_, '_, S> for PanicMessage { - fn decode(r: &mut Reader<'_>, s: &mut S) -> Self { - match Option::::decode(r, s) { - Some(s) => PanicMessage::String(s), - None => PanicMessage::Unknown, - } - } -} diff --git a/library/proc_macro/src/bridge/selfless_reify.rs b/library/proc_macro/src/bridge/selfless_reify.rs deleted file mode 100644 index 907ad256e4b43..0000000000000 --- a/library/proc_macro/src/bridge/selfless_reify.rs +++ /dev/null @@ -1,84 +0,0 @@ -//! Abstraction for creating `fn` pointers from any callable that *effectively* -//! has the equivalent of implementing `Default`, even if the compiler neither -//! provides `Default` nor allows reifying closures (i.e. creating `fn` pointers) -//! other than those with absolutely no captures. -//! -//! More specifically, for a closure-like type to be "effectively `Default`": -//! * it must be a ZST (zero-sized type): no information contained within, so -//! that `Default`'s return value (if it were implemented) is unambiguous -//! * it must be `Copy`: no captured "unique ZST tokens" or any other similar -//! types that would make duplicating values at will unsound -//! * combined with the ZST requirement, this confers a kind of "telecopy" -//! ability: similar to `Copy`, but without keeping the value around, and -//! instead "reconstructing" it (a noop given it's a ZST) when needed -//! * it must be *provably* inhabited: no captured uninhabited types or any -//! other types that cannot be constructed by the user of this abstraction -//! * the proof is a value of the closure-like type itself, in a sense the -//! "seed" for the "telecopy" process made possible by ZST + `Copy` -//! * this requirement is the only reason an abstraction limited to a specific -//! usecase is required: ZST + `Copy` can be checked with *at worst* a panic -//! at the "attempted `::default()` call" time, but that doesn't guarantee -//! that the value can be soundly created, and attempting to use the typical -//! "proof ZST token" approach leads yet again to having a ZST + `Copy` type -//! that is not proof of anything without a value (i.e. isomorphic to a -//! newtype of the type it's trying to prove the inhabitation of) -//! -//! A more flexible (and safer) solution to the general problem could exist once -//! `const`-generic parameters can have type parameters in their types: -//! -//! ```rust,ignore (needs future const-generics) -//! extern "C" fn ffi_wrapper< -//! A, R, -//! F: Fn(A) -> R, -//! const f: F, // <-- this `const`-generic is not yet allowed -//! >(arg: A) -> R { -//! f(arg) -//! } -//! ``` - -use std::mem; - -// FIXME(eddyb) this could be `trait` impls except for the `const fn` requirement. -macro_rules! define_reify_functions { - ($( - fn $name:ident $(<$($param:ident),*>)? - for $(extern $abi:tt)? fn($($arg:ident: $arg_ty:ty),*) -> $ret_ty:ty; - )+) => { - $(pub const fn $name< - $($($param,)*)? - F: Fn($($arg_ty),*) -> $ret_ty + Copy - >(f: F) -> $(extern $abi)? fn($($arg_ty),*) -> $ret_ty { - // FIXME(eddyb) describe the `F` type (e.g. via `type_name::`) once panic - // formatting becomes possible in `const fn`. - assert!(mem::size_of::() == 0, "selfless_reify: closure must be zero-sized"); - - $(extern $abi)? fn wrapper< - $($($param,)*)? - F: Fn($($arg_ty),*) -> $ret_ty + Copy - >($($arg: $arg_ty),*) -> $ret_ty { - let f = unsafe { - // SAFETY: `F` satisfies all criteria for "out of thin air" - // reconstructability (see module-level doc comment). - mem::MaybeUninit::::uninit().assume_init() - }; - f($($arg),*) - } - let _f_proof = f; - wrapper::< - $($($param,)*)? - F - > - })+ - } -} - -define_reify_functions! { - fn _reify_to_extern_c_fn_unary for extern "C" fn(arg: A) -> R; - - // HACK(eddyb) this abstraction is used with `for<'a> fn(BridgeConfig<'a>) - // -> T` but that doesn't work with just `reify_to_extern_c_fn_unary` - // because of the `fn` pointer type being "higher-ranked" (i.e. the - // `for<'a>` binder). - // FIXME(eddyb) try to remove the lifetime from `BridgeConfig`, that'd help. - fn reify_to_extern_c_fn_hrt_bridge for extern "C" fn(bridge: super::BridgeConfig<'_>) -> R; -} diff --git a/library/proc_macro/src/bridge/server.rs b/library/proc_macro/src/bridge/server.rs deleted file mode 100644 index 0dbd4bac85c9f..0000000000000 --- a/library/proc_macro/src/bridge/server.rs +++ /dev/null @@ -1,443 +0,0 @@ -//! Server-side traits. - -use super::*; - -use std::cell::Cell; -use std::marker::PhantomData; - -macro_rules! define_server_handles { - ( - 'owned: $($oty:ident,)* - 'interned: $($ity:ident,)* - ) => { - #[allow(non_snake_case)] - pub(super) struct HandleStore { - $($oty: handle::OwnedStore,)* - $($ity: handle::InternedStore,)* - } - - impl HandleStore { - fn new(handle_counters: &'static client::HandleCounters) -> Self { - HandleStore { - $($oty: handle::OwnedStore::new(&handle_counters.$oty),)* - $($ity: handle::InternedStore::new(&handle_counters.$ity),)* - } - } - } - - $( - impl Encode>> for Marked { - fn encode(self, w: &mut Writer, s: &mut HandleStore>) { - s.$oty.alloc(self).encode(w, s); - } - } - - impl DecodeMut<'_, '_, HandleStore>> - for Marked - { - fn decode(r: &mut Reader<'_>, s: &mut HandleStore>) -> Self { - s.$oty.take(handle::Handle::decode(r, &mut ())) - } - } - - impl<'s, S: Types> Decode<'_, 's, HandleStore>> - for &'s Marked - { - fn decode(r: &mut Reader<'_>, s: &'s HandleStore>) -> Self { - &s.$oty[handle::Handle::decode(r, &mut ())] - } - } - - impl<'s, S: Types> DecodeMut<'_, 's, HandleStore>> - for &'s mut Marked - { - fn decode( - r: &mut Reader<'_>, - s: &'s mut HandleStore> - ) -> Self { - &mut s.$oty[handle::Handle::decode(r, &mut ())] - } - } - )* - - $( - impl Encode>> for Marked { - fn encode(self, w: &mut Writer, s: &mut HandleStore>) { - s.$ity.alloc(self).encode(w, s); - } - } - - impl DecodeMut<'_, '_, HandleStore>> - for Marked - { - fn decode(r: &mut Reader<'_>, s: &mut HandleStore>) -> Self { - s.$ity.copy(handle::Handle::decode(r, &mut ())) - } - } - )* - } -} -with_api_handle_types!(define_server_handles); - -pub trait Types { - type FreeFunctions: 'static; - type TokenStream: 'static + Clone; - type SourceFile: 'static + Clone; - type Span: 'static + Copy + Eq + Hash; - type Symbol: 'static; -} - -/// Declare an associated fn of one of the traits below, adding necessary -/// default bodies. -macro_rules! associated_fn { - (fn drop(&mut self, $arg:ident: $arg_ty:ty)) => - (fn drop(&mut self, $arg: $arg_ty) { mem::drop($arg) }); - - (fn clone(&mut self, $arg:ident: $arg_ty:ty) -> $ret_ty:ty) => - (fn clone(&mut self, $arg: $arg_ty) -> $ret_ty { $arg.clone() }); - - ($($item:tt)*) => ($($item)*;) -} - -macro_rules! declare_server_traits { - ($($name:ident { - $(fn $method:ident($($arg:ident: $arg_ty:ty),* $(,)?) $(-> $ret_ty:ty)?;)* - }),* $(,)?) => { - $(pub trait $name: Types { - $(associated_fn!(fn $method(&mut self, $($arg: $arg_ty),*) $(-> $ret_ty)?);)* - })* - - pub trait Server: Types $(+ $name)* { - fn globals(&mut self) -> ExpnGlobals; - - /// Intern a symbol received from RPC - fn intern_symbol(ident: &str) -> Self::Symbol; - - /// Recover the string value of a symbol, and invoke a callback with it. - fn with_symbol_string(symbol: &Self::Symbol, f: impl FnOnce(&str)); - } - } -} -with_api!(Self, self_, declare_server_traits); - -pub(super) struct MarkedTypes(S); - -impl Server for MarkedTypes { - fn globals(&mut self) -> ExpnGlobals { - <_>::mark(Server::globals(&mut self.0)) - } - fn intern_symbol(ident: &str) -> Self::Symbol { - <_>::mark(S::intern_symbol(ident)) - } - fn with_symbol_string(symbol: &Self::Symbol, f: impl FnOnce(&str)) { - S::with_symbol_string(symbol.unmark(), f) - } -} - -macro_rules! define_mark_types_impls { - ($($name:ident { - $(fn $method:ident($($arg:ident: $arg_ty:ty),* $(,)?) $(-> $ret_ty:ty)?;)* - }),* $(,)?) => { - impl Types for MarkedTypes { - $(type $name = Marked;)* - } - - $(impl $name for MarkedTypes { - $(fn $method(&mut self, $($arg: $arg_ty),*) $(-> $ret_ty)? { - <_>::mark($name::$method(&mut self.0, $($arg.unmark()),*)) - })* - })* - } -} -with_api!(Self, self_, define_mark_types_impls); - -struct Dispatcher { - handle_store: HandleStore, - server: S, -} - -macro_rules! define_dispatcher_impl { - ($($name:ident { - $(fn $method:ident($($arg:ident: $arg_ty:ty),* $(,)?) $(-> $ret_ty:ty)?;)* - }),* $(,)?) => { - // FIXME(eddyb) `pub` only for `ExecutionStrategy` below. - pub trait DispatcherTrait { - // HACK(eddyb) these are here to allow `Self::$name` to work below. - $(type $name;)* - - fn dispatch(&mut self, buf: Buffer) -> Buffer; - } - - impl DispatcherTrait for Dispatcher> { - $(type $name = as Types>::$name;)* - - fn dispatch(&mut self, mut buf: Buffer) -> Buffer { - let Dispatcher { handle_store, server } = self; - - let mut reader = &buf[..]; - match api_tags::Method::decode(&mut reader, &mut ()) { - $(api_tags::Method::$name(m) => match m { - $(api_tags::$name::$method => { - let mut call_method = || { - reverse_decode!(reader, handle_store; $($arg: $arg_ty),*); - $name::$method(server, $($arg),*) - }; - // HACK(eddyb) don't use `panic::catch_unwind` in a panic. - // If client and server happen to use the same `std`, - // `catch_unwind` asserts that the panic counter was 0, - // even when the closure passed to it didn't panic. - let r = if thread::panicking() { - Ok(call_method()) - } else { - panic::catch_unwind(panic::AssertUnwindSafe(call_method)) - .map_err(PanicMessage::from) - }; - - buf.clear(); - r.encode(&mut buf, handle_store); - })* - }),* - } - buf - } - } - } -} -with_api!(Self, self_, define_dispatcher_impl); - -pub trait ExecutionStrategy { - fn run_bridge_and_client( - &self, - dispatcher: &mut impl DispatcherTrait, - input: Buffer, - run_client: extern "C" fn(BridgeConfig<'_>) -> Buffer, - force_show_panics: bool, - ) -> Buffer; -} - -thread_local! { - /// While running a proc-macro with the same-thread executor, this flag will - /// be set, forcing nested proc-macro invocations (e.g. due to - /// `TokenStream::expand_expr`) to be run using a cross-thread executor. - /// - /// This is required as the thread-local state in the proc_macro client does - /// not handle being re-entered, and will invalidate all `Symbol`s when - /// entering a nested macro. - static ALREADY_RUNNING_SAME_THREAD: Cell = const { Cell::new(false) }; -} - -/// Keep `ALREADY_RUNNING_SAME_THREAD` (see also its documentation) -/// set to `true`, preventing same-thread reentrance. -struct RunningSameThreadGuard(()); - -impl RunningSameThreadGuard { - fn new() -> Self { - let already_running = ALREADY_RUNNING_SAME_THREAD.replace(true); - assert!( - !already_running, - "same-thread nesting (\"reentrance\") of proc macro executions is not supported" - ); - RunningSameThreadGuard(()) - } -} - -impl Drop for RunningSameThreadGuard { - fn drop(&mut self) { - ALREADY_RUNNING_SAME_THREAD.set(false); - } -} - -pub struct MaybeCrossThread

{ - cross_thread: bool, - marker: PhantomData

, -} - -impl

MaybeCrossThread

{ - pub const fn new(cross_thread: bool) -> Self { - MaybeCrossThread { cross_thread, marker: PhantomData } - } -} - -impl

ExecutionStrategy for MaybeCrossThread

-where - P: MessagePipe + Send + 'static, -{ - fn run_bridge_and_client( - &self, - dispatcher: &mut impl DispatcherTrait, - input: Buffer, - run_client: extern "C" fn(BridgeConfig<'_>) -> Buffer, - force_show_panics: bool, - ) -> Buffer { - if self.cross_thread || ALREADY_RUNNING_SAME_THREAD.get() { - >::new().run_bridge_and_client( - dispatcher, - input, - run_client, - force_show_panics, - ) - } else { - SameThread.run_bridge_and_client(dispatcher, input, run_client, force_show_panics) - } - } -} - -pub struct SameThread; - -impl ExecutionStrategy for SameThread { - fn run_bridge_and_client( - &self, - dispatcher: &mut impl DispatcherTrait, - input: Buffer, - run_client: extern "C" fn(BridgeConfig<'_>) -> Buffer, - force_show_panics: bool, - ) -> Buffer { - let _guard = RunningSameThreadGuard::new(); - - let mut dispatch = |buf| dispatcher.dispatch(buf); - - run_client(BridgeConfig { - input, - dispatch: (&mut dispatch).into(), - force_show_panics, - _marker: marker::PhantomData, - }) - } -} - -pub struct CrossThread

(PhantomData

); - -impl

CrossThread

{ - pub const fn new() -> Self { - CrossThread(PhantomData) - } -} - -impl

ExecutionStrategy for CrossThread

-where - P: MessagePipe + Send + 'static, -{ - fn run_bridge_and_client( - &self, - dispatcher: &mut impl DispatcherTrait, - input: Buffer, - run_client: extern "C" fn(BridgeConfig<'_>) -> Buffer, - force_show_panics: bool, - ) -> Buffer { - let (mut server, mut client) = P::new(); - - let join_handle = thread::spawn(move || { - let mut dispatch = |b: Buffer| -> Buffer { - client.send(b); - client.recv().expect("server died while client waiting for reply") - }; - - run_client(BridgeConfig { - input, - dispatch: (&mut dispatch).into(), - force_show_panics, - _marker: marker::PhantomData, - }) - }); - - while let Some(b) = server.recv() { - server.send(dispatcher.dispatch(b)); - } - - join_handle.join().unwrap() - } -} - -/// A message pipe used for communicating between server and client threads. -pub trait MessagePipe: Sized { - /// Create a new pair of endpoints for the message pipe. - fn new() -> (Self, Self); - - /// Send a message to the other endpoint of this pipe. - fn send(&mut self, value: T); - - /// Receive a message from the other endpoint of this pipe. - /// - /// Returns `None` if the other end of the pipe has been destroyed, and no - /// message was received. - fn recv(&mut self) -> Option; -} - -fn run_server< - S: Server, - I: Encode>>, - O: for<'a, 's> DecodeMut<'a, 's, HandleStore>>, ->( - strategy: &impl ExecutionStrategy, - handle_counters: &'static client::HandleCounters, - server: S, - input: I, - run_client: extern "C" fn(BridgeConfig<'_>) -> Buffer, - force_show_panics: bool, -) -> Result { - let mut dispatcher = - Dispatcher { handle_store: HandleStore::new(handle_counters), server: MarkedTypes(server) }; - - let globals = dispatcher.server.globals(); - - let mut buf = Buffer::new(); - (globals, input).encode(&mut buf, &mut dispatcher.handle_store); - - buf = strategy.run_bridge_and_client(&mut dispatcher, buf, run_client, force_show_panics); - - Result::decode(&mut &buf[..], &mut dispatcher.handle_store) -} - -impl client::Client { - pub fn run( - &self, - strategy: &impl ExecutionStrategy, - server: S, - input: S::TokenStream, - force_show_panics: bool, - ) -> Result - where - S: Server, - S::TokenStream: Default, - { - let client::Client { get_handle_counters, run, _marker } = *self; - run_server( - strategy, - get_handle_counters(), - server, - as Types>::TokenStream::mark(input), - run, - force_show_panics, - ) - .map(|s| as Types>::TokenStream>>::unmark(s).unwrap_or_default()) - } -} - -impl client::Client<(crate::TokenStream, crate::TokenStream), crate::TokenStream> { - pub fn run( - &self, - strategy: &impl ExecutionStrategy, - server: S, - input: S::TokenStream, - input2: S::TokenStream, - force_show_panics: bool, - ) -> Result - where - S: Server, - S::TokenStream: Default, - { - let client::Client { get_handle_counters, run, _marker } = *self; - run_server( - strategy, - get_handle_counters(), - server, - ( - as Types>::TokenStream::mark(input), - as Types>::TokenStream::mark(input2), - ), - run, - force_show_panics, - ) - .map(|s| as Types>::TokenStream>>::unmark(s).unwrap_or_default()) - } -} diff --git a/library/proc_macro/src/bridge/symbol.rs b/library/proc_macro/src/bridge/symbol.rs deleted file mode 100644 index 86ce2cc189588..0000000000000 --- a/library/proc_macro/src/bridge/symbol.rs +++ /dev/null @@ -1,205 +0,0 @@ -//! Client-side interner used for symbols. -//! -//! This is roughly based on the symbol interner from `rustc_span` and the -//! DroplessArena from `rustc_arena`. It is unfortunately a complete -//! copy/re-implementation rather than a dependency as it is difficult to depend -//! on crates from within `proc_macro`, due to it being built at the same time -//! as `std`. -//! -//! If at some point in the future it becomes easier to add dependencies to -//! proc_macro, this module should probably be removed or simplified. - -use std::cell::RefCell; -use std::num::NonZero; -use std::str; - -use super::*; - -/// Handle for a symbol string stored within the Interner. -#[derive(Copy, Clone, PartialEq, Eq, Hash)] -pub struct Symbol(NonZero); - -impl !Send for Symbol {} -impl !Sync for Symbol {} - -impl Symbol { - /// Intern a new `Symbol` - pub(crate) fn new(string: &str) -> Self { - INTERNER.with_borrow_mut(|i| i.intern(string)) - } - - /// Create a new `Symbol` for an identifier. - /// - /// Validates and normalizes before converting it to a symbol. - pub(crate) fn new_ident(string: &str, is_raw: bool) -> Self { - // Fast-path: check if this is a valid ASCII identifier - if Self::is_valid_ascii_ident(string.as_bytes()) { - if is_raw && !Self::can_be_raw(string) { - panic!("`{}` cannot be a raw identifier", string); - } - return Self::new(string); - } - - // Slow-path: If the string is already ASCII we're done, otherwise ask - // our server to do this for us over RPC. - // We don't need to check for identifiers which can't be raw here, - // because all of them are ASCII. - if string.is_ascii() { - Err(()) - } else { - client::Symbol::normalize_and_validate_ident(string) - } - .unwrap_or_else(|_| panic!("`{:?}` is not a valid identifier", string)) - } - - /// Run a callback with the symbol's string value. - pub(crate) fn with(self, f: impl FnOnce(&str) -> R) -> R { - INTERNER.with_borrow(|i| f(i.get(self))) - } - - /// Clear out the thread-local symbol interner, making all previously - /// created symbols invalid such that `with` will panic when called on them. - pub(crate) fn invalidate_all() { - INTERNER.with_borrow_mut(|i| i.clear()); - } - - /// Check if the ident is a valid ASCII identifier. - /// - /// This is a short-circuit which is cheap to implement within the - /// proc-macro client to avoid RPC when creating simple idents, but may - /// return `false` for a valid identifier if it contains non-ASCII - /// characters. - fn is_valid_ascii_ident(bytes: &[u8]) -> bool { - matches!(bytes.first(), Some(b'_' | b'a'..=b'z' | b'A'..=b'Z')) - && bytes[1..] - .iter() - .all(|b| matches!(b, b'_' | b'a'..=b'z' | b'A'..=b'Z' | b'0'..=b'9')) - } - - // Mimics the behaviour of `Symbol::can_be_raw` from `rustc_span` - fn can_be_raw(string: &str) -> bool { - match string { - "_" | "super" | "self" | "Self" | "crate" => false, - _ => true, - } - } -} - -impl fmt::Debug for Symbol { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.with(|s| fmt::Debug::fmt(s, f)) - } -} - -impl ToString for Symbol { - fn to_string(&self) -> String { - self.with(|s| s.to_owned()) - } -} - -impl fmt::Display for Symbol { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.with(|s| fmt::Display::fmt(s, f)) - } -} - -impl Encode for Symbol { - fn encode(self, w: &mut Writer, s: &mut S) { - self.with(|sym| sym.encode(w, s)) - } -} - -impl DecodeMut<'_, '_, server::HandleStore>> - for Marked -{ - fn decode(r: &mut Reader<'_>, s: &mut server::HandleStore>) -> Self { - Mark::mark(S::intern_symbol(<&str>::decode(r, s))) - } -} - -impl Encode>> - for Marked -{ - fn encode(self, w: &mut Writer, s: &mut server::HandleStore>) { - S::with_symbol_string(&self.unmark(), |sym| sym.encode(w, s)) - } -} - -impl DecodeMut<'_, '_, S> for Symbol { - fn decode(r: &mut Reader<'_>, s: &mut S) -> Self { - Symbol::new(<&str>::decode(r, s)) - } -} - -thread_local! { - static INTERNER: RefCell = RefCell::new(Interner { - arena: arena::Arena::new(), - names: fxhash::FxHashMap::default(), - strings: Vec::new(), - // Start with a base of 1 to make sure that `NonZero` works. - sym_base: NonZero::new(1).unwrap(), - }); -} - -/// Basic interner for a `Symbol`, inspired by the one in `rustc_span`. -struct Interner { - arena: arena::Arena, - // SAFETY: These `'static` lifetimes are actually references to data owned - // by the Arena. This is safe, as we never return them as static references - // from `Interner`. - names: fxhash::FxHashMap<&'static str, Symbol>, - strings: Vec<&'static str>, - // The offset to apply to symbol names stored in the interner. This is used - // to ensure that symbol names are not re-used after the interner is - // cleared. - sym_base: NonZero, -} - -impl Interner { - fn intern(&mut self, string: &str) -> Symbol { - if let Some(&name) = self.names.get(string) { - return name; - } - - let name = Symbol( - self.sym_base - .checked_add(self.strings.len() as u32) - .expect("`proc_macro` symbol name overflow"), - ); - - let string: &str = self.arena.alloc_str(string); - - // SAFETY: we can extend the arena allocation to `'static` because we - // only access these while the arena is still alive. - let string: &'static str = unsafe { &*(string as *const str) }; - self.strings.push(string); - self.names.insert(string, name); - name - } - - /// Read a symbol's value from the store while it is held. - fn get(&self, symbol: Symbol) -> &str { - // NOTE: Subtract out the offset which was added to make the symbol - // nonzero and prevent symbol name re-use. - let name = symbol - .0 - .get() - .checked_sub(self.sym_base.get()) - .expect("use-after-free of `proc_macro` symbol"); - self.strings[name as usize] - } - - /// Clear all symbols from the store, invalidating them such that `get` will - /// panic if they are accessed in the future. - fn clear(&mut self) { - // NOTE: Be careful not to panic here, as we may be called on the client - // when a `catch_unwind` isn't installed. - self.sym_base = self.sym_base.saturating_add(self.strings.len() as u32); - self.names.clear(); - self.strings.clear(); - - // SAFETY: This is cleared after the names and strings tables are - // cleared out, so no references into the arena should remain. - self.arena = arena::Arena::new(); - } -} diff --git a/library/proc_macro/src/diagnostic.rs b/library/proc_macro/src/diagnostic.rs deleted file mode 100644 index 5a209f7c7aa18..0000000000000 --- a/library/proc_macro/src/diagnostic.rs +++ /dev/null @@ -1,175 +0,0 @@ -use crate::Span; - -/// An enum representing a diagnostic level. -#[unstable(feature = "proc_macro_diagnostic", issue = "54140")] -#[derive(Copy, Clone, Debug)] -#[non_exhaustive] -pub enum Level { - /// An error. - Error, - /// A warning. - Warning, - /// A note. - Note, - /// A help message. - Help, -} - -/// Trait implemented by types that can be converted into a set of `Span`s. -#[unstable(feature = "proc_macro_diagnostic", issue = "54140")] -pub trait MultiSpan { - /// Converts `self` into a `Vec`. - fn into_spans(self) -> Vec; -} - -#[unstable(feature = "proc_macro_diagnostic", issue = "54140")] -impl MultiSpan for Span { - fn into_spans(self) -> Vec { - vec![self] - } -} - -#[unstable(feature = "proc_macro_diagnostic", issue = "54140")] -impl MultiSpan for Vec { - fn into_spans(self) -> Vec { - self - } -} - -#[unstable(feature = "proc_macro_diagnostic", issue = "54140")] -impl<'a> MultiSpan for &'a [Span] { - fn into_spans(self) -> Vec { - self.to_vec() - } -} - -/// A structure representing a diagnostic message and associated children -/// messages. -#[unstable(feature = "proc_macro_diagnostic", issue = "54140")] -#[derive(Clone, Debug)] -pub struct Diagnostic { - level: Level, - message: String, - spans: Vec, - children: Vec, -} - -macro_rules! diagnostic_child_methods { - ($spanned:ident, $regular:ident, $level:expr) => { - #[unstable(feature = "proc_macro_diagnostic", issue = "54140")] - #[doc = concat!("Adds a new child diagnostics message to `self` with the [`", - stringify!($level), "`] level, and the given `spans` and `message`.")] - pub fn $spanned(mut self, spans: S, message: T) -> Diagnostic - where - S: MultiSpan, - T: Into, - { - self.children.push(Diagnostic::spanned(spans, $level, message)); - self - } - - #[unstable(feature = "proc_macro_diagnostic", issue = "54140")] - #[doc = concat!("Adds a new child diagnostic message to `self` with the [`", - stringify!($level), "`] level, and the given `message`.")] - pub fn $regular>(mut self, message: T) -> Diagnostic { - self.children.push(Diagnostic::new($level, message)); - self - } - }; -} - -/// Iterator over the children diagnostics of a `Diagnostic`. -#[derive(Debug, Clone)] -#[unstable(feature = "proc_macro_diagnostic", issue = "54140")] -pub struct Children<'a>(std::slice::Iter<'a, Diagnostic>); - -#[unstable(feature = "proc_macro_diagnostic", issue = "54140")] -impl<'a> Iterator for Children<'a> { - type Item = &'a Diagnostic; - - fn next(&mut self) -> Option { - self.0.next() - } -} - -#[unstable(feature = "proc_macro_diagnostic", issue = "54140")] -impl Diagnostic { - /// Creates a new diagnostic with the given `level` and `message`. - #[unstable(feature = "proc_macro_diagnostic", issue = "54140")] - pub fn new>(level: Level, message: T) -> Diagnostic { - Diagnostic { level, message: message.into(), spans: vec![], children: vec![] } - } - - /// Creates a new diagnostic with the given `level` and `message` pointing to - /// the given set of `spans`. - #[unstable(feature = "proc_macro_diagnostic", issue = "54140")] - pub fn spanned(spans: S, level: Level, message: T) -> Diagnostic - where - S: MultiSpan, - T: Into, - { - Diagnostic { level, message: message.into(), spans: spans.into_spans(), children: vec![] } - } - - diagnostic_child_methods!(span_error, error, Level::Error); - diagnostic_child_methods!(span_warning, warning, Level::Warning); - diagnostic_child_methods!(span_note, note, Level::Note); - diagnostic_child_methods!(span_help, help, Level::Help); - - /// Returns the diagnostic `level` for `self`. - #[unstable(feature = "proc_macro_diagnostic", issue = "54140")] - pub fn level(&self) -> Level { - self.level - } - - /// Sets the level in `self` to `level`. - #[unstable(feature = "proc_macro_diagnostic", issue = "54140")] - pub fn set_level(&mut self, level: Level) { - self.level = level; - } - - /// Returns the message in `self`. - #[unstable(feature = "proc_macro_diagnostic", issue = "54140")] - pub fn message(&self) -> &str { - &self.message - } - - /// Sets the message in `self` to `message`. - #[unstable(feature = "proc_macro_diagnostic", issue = "54140")] - pub fn set_message>(&mut self, message: T) { - self.message = message.into(); - } - - /// Returns the `Span`s in `self`. - #[unstable(feature = "proc_macro_diagnostic", issue = "54140")] - pub fn spans(&self) -> &[Span] { - &self.spans - } - - /// Sets the `Span`s in `self` to `spans`. - #[unstable(feature = "proc_macro_diagnostic", issue = "54140")] - pub fn set_spans(&mut self, spans: S) { - self.spans = spans.into_spans(); - } - - /// Returns an iterator over the children diagnostics of `self`. - #[unstable(feature = "proc_macro_diagnostic", issue = "54140")] - pub fn children(&self) -> Children<'_> { - Children(self.children.iter()) - } - - /// Emit the diagnostic. - #[unstable(feature = "proc_macro_diagnostic", issue = "54140")] - pub fn emit(self) { - fn to_internal(diag: Diagnostic) -> crate::bridge::Diagnostic { - crate::bridge::Diagnostic { - level: diag.level, - message: diag.message, - spans: diag.spans.into_iter().map(|s| s.0).collect(), - children: diag.children.into_iter().map(to_internal).collect(), - } - } - - crate::bridge::client::FreeFunctions::emit_diagnostic(to_internal(self)); - } -} diff --git a/library/proc_macro/src/lib.rs b/library/proc_macro/src/lib.rs deleted file mode 100644 index 3d7d36b27e53b..0000000000000 --- a/library/proc_macro/src/lib.rs +++ /dev/null @@ -1,1566 +0,0 @@ -//! A support library for macro authors when defining new macros. -//! -//! This library, provided by the standard distribution, provides the types -//! consumed in the interfaces of procedurally defined macro definitions such as -//! function-like macros `#[proc_macro]`, macro attributes `#[proc_macro_attribute]` and -//! custom derive attributes`#[proc_macro_derive]`. -//! -//! See [the book] for more. -//! -//! [the book]: ../book/ch19-06-macros.html#procedural-macros-for-generating-code-from-attributes - -#![stable(feature = "proc_macro_lib", since = "1.15.0")] -#![deny(missing_docs)] -#![doc( - html_playground_url = "https://play.rust-lang.org/", - issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/", - test(no_crate_inject, attr(deny(warnings))), - test(attr(allow(dead_code, deprecated, unused_variables, unused_mut))) -)] -#![doc(rust_logo)] -#![feature(rustdoc_internals)] -// This library is copied into rust-analyzer to allow loading rustc compiled proc macros. -// Please avoid unstable features where possible to minimize the amount of changes necessary -// to make it compile with rust-analyzer on stable. -#![feature(rustc_allow_const_fn_unstable)] -#![feature(staged_api)] -#![feature(allow_internal_unstable)] -#![feature(decl_macro)] -#![feature(maybe_uninit_write_slice)] -#![feature(negative_impls)] -#![feature(new_uninit)] -#![feature(panic_can_unwind)] -#![feature(restricted_std)] -#![feature(rustc_attrs)] -#![feature(min_specialization)] -#![feature(strict_provenance)] -#![recursion_limit = "256"] -#![allow(internal_features)] -#![deny(ffi_unwind_calls)] - -#[unstable(feature = "proc_macro_internals", issue = "27812")] -#[doc(hidden)] -pub mod bridge; - -mod diagnostic; - -#[unstable(feature = "proc_macro_diagnostic", issue = "54140")] -pub use diagnostic::{Diagnostic, Level, MultiSpan}; - -use std::ffi::CStr; -use std::ops::{Range, RangeBounds}; -use std::path::PathBuf; -use std::str::FromStr; -use std::{error, fmt}; - -/// Determines whether proc_macro has been made accessible to the currently -/// running program. -/// -/// The proc_macro crate is only intended for use inside the implementation of -/// procedural macros. All the functions in this crate panic if invoked from -/// outside of a procedural macro, such as from a build script or unit test or -/// ordinary Rust binary. -/// -/// With consideration for Rust libraries that are designed to support both -/// macro and non-macro use cases, `proc_macro::is_available()` provides a -/// non-panicking way to detect whether the infrastructure required to use the -/// API of proc_macro is presently available. Returns true if invoked from -/// inside of a procedural macro, false if invoked from any other binary. -#[stable(feature = "proc_macro_is_available", since = "1.57.0")] -pub fn is_available() -> bool { - bridge::client::is_available() -} - -/// The main type provided by this crate, representing an abstract stream of -/// tokens, or, more specifically, a sequence of token trees. -/// The type provides interfaces for iterating over those token trees and, conversely, -/// collecting a number of token trees into one stream. -/// -/// This is both the input and output of `#[proc_macro]`, `#[proc_macro_attribute]` -/// and `#[proc_macro_derive]` definitions. -#[rustc_diagnostic_item = "TokenStream"] -#[stable(feature = "proc_macro_lib", since = "1.15.0")] -#[derive(Clone)] -pub struct TokenStream(Option); - -#[stable(feature = "proc_macro_lib", since = "1.15.0")] -impl !Send for TokenStream {} -#[stable(feature = "proc_macro_lib", since = "1.15.0")] -impl !Sync for TokenStream {} - -/// Error returned from `TokenStream::from_str`. -#[stable(feature = "proc_macro_lib", since = "1.15.0")] -#[non_exhaustive] -#[derive(Debug)] -pub struct LexError; - -#[stable(feature = "proc_macro_lexerror_impls", since = "1.44.0")] -impl fmt::Display for LexError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str("cannot parse string into token stream") - } -} - -#[stable(feature = "proc_macro_lexerror_impls", since = "1.44.0")] -impl error::Error for LexError {} - -#[stable(feature = "proc_macro_lib", since = "1.15.0")] -impl !Send for LexError {} -#[stable(feature = "proc_macro_lib", since = "1.15.0")] -impl !Sync for LexError {} - -/// Error returned from `TokenStream::expand_expr`. -#[unstable(feature = "proc_macro_expand", issue = "90765")] -#[non_exhaustive] -#[derive(Debug)] -pub struct ExpandError; - -#[unstable(feature = "proc_macro_expand", issue = "90765")] -impl fmt::Display for ExpandError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str("macro expansion failed") - } -} - -#[unstable(feature = "proc_macro_expand", issue = "90765")] -impl error::Error for ExpandError {} - -#[unstable(feature = "proc_macro_expand", issue = "90765")] -impl !Send for ExpandError {} - -#[unstable(feature = "proc_macro_expand", issue = "90765")] -impl !Sync for ExpandError {} - -impl TokenStream { - /// Returns an empty `TokenStream` containing no token trees. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn new() -> TokenStream { - TokenStream(None) - } - - /// Checks if this `TokenStream` is empty. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn is_empty(&self) -> bool { - self.0.as_ref().map(|h| h.is_empty()).unwrap_or(true) - } - - /// Parses this `TokenStream` as an expression and attempts to expand any - /// macros within it. Returns the expanded `TokenStream`. - /// - /// Currently only expressions expanding to literals will succeed, although - /// this may be relaxed in the future. - /// - /// NOTE: In error conditions, `expand_expr` may leave macros unexpanded, - /// report an error, failing compilation, and/or return an `Err(..)`. The - /// specific behavior for any error condition, and what conditions are - /// considered errors, is unspecified and may change in the future. - #[unstable(feature = "proc_macro_expand", issue = "90765")] - pub fn expand_expr(&self) -> Result { - let stream = self.0.as_ref().ok_or(ExpandError)?; - match bridge::client::TokenStream::expand_expr(stream) { - Ok(stream) => Ok(TokenStream(Some(stream))), - Err(_) => Err(ExpandError), - } - } -} - -/// Attempts to break the string into tokens and parse those tokens into a token stream. -/// May fail for a number of reasons, for example, if the string contains unbalanced delimiters -/// or characters not existing in the language. -/// All tokens in the parsed stream get `Span::call_site()` spans. -/// -/// NOTE: some errors may cause panics instead of returning `LexError`. We reserve the right to -/// change these errors into `LexError`s later. -#[stable(feature = "proc_macro_lib", since = "1.15.0")] -impl FromStr for TokenStream { - type Err = LexError; - - fn from_str(src: &str) -> Result { - Ok(TokenStream(Some(bridge::client::TokenStream::from_str(src)))) - } -} - -// N.B., the bridge only provides `to_string`, implement `fmt::Display` -// based on it (the reverse of the usual relationship between the two). -#[doc(hidden)] -#[stable(feature = "proc_macro_lib", since = "1.15.0")] -impl ToString for TokenStream { - fn to_string(&self) -> String { - self.0.as_ref().map(|t| t.to_string()).unwrap_or_default() - } -} - -/// Prints the token stream as a string that is supposed to be losslessly convertible back -/// into the same token stream (modulo spans), except for possibly `TokenTree::Group`s -/// with `Delimiter::None` delimiters and negative numeric literals. -/// -/// Note: the exact form of the output is subject to change, e.g. there might -/// be changes in the whitespace used between tokens. Therefore, you should -/// *not* do any kind of simple substring matching on the output string (as -/// produced by `to_string`) to implement a proc macro, because that matching -/// might stop working if such changes happen. Instead, you should work at the -/// `TokenTree` level, e.g. matching against `TokenTree::Ident`, -/// `TokenTree::Punct`, or `TokenTree::Literal`. -#[stable(feature = "proc_macro_lib", since = "1.15.0")] -impl fmt::Display for TokenStream { - #[allow(clippy::recursive_format_impl)] // clippy doesn't see the specialization - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str(&self.to_string()) - } -} - -/// Prints token in a form convenient for debugging. -#[stable(feature = "proc_macro_lib", since = "1.15.0")] -impl fmt::Debug for TokenStream { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str("TokenStream ")?; - f.debug_list().entries(self.clone()).finish() - } -} - -#[stable(feature = "proc_macro_token_stream_default", since = "1.45.0")] -impl Default for TokenStream { - fn default() -> Self { - TokenStream::new() - } -} - -#[unstable(feature = "proc_macro_quote", issue = "54722")] -pub use quote::{quote, quote_span}; - -fn tree_to_bridge_tree( - tree: TokenTree, -) -> bridge::TokenTree { - match tree { - TokenTree::Group(tt) => bridge::TokenTree::Group(tt.0), - TokenTree::Punct(tt) => bridge::TokenTree::Punct(tt.0), - TokenTree::Ident(tt) => bridge::TokenTree::Ident(tt.0), - TokenTree::Literal(tt) => bridge::TokenTree::Literal(tt.0), - } -} - -/// Creates a token stream containing a single token tree. -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl From for TokenStream { - fn from(tree: TokenTree) -> TokenStream { - TokenStream(Some(bridge::client::TokenStream::from_token_tree(tree_to_bridge_tree(tree)))) - } -} - -/// Non-generic helper for implementing `FromIterator` and -/// `Extend` with less monomorphization in calling crates. -struct ConcatTreesHelper { - trees: Vec< - bridge::TokenTree< - bridge::client::TokenStream, - bridge::client::Span, - bridge::client::Symbol, - >, - >, -} - -impl ConcatTreesHelper { - fn new(capacity: usize) -> Self { - ConcatTreesHelper { trees: Vec::with_capacity(capacity) } - } - - fn push(&mut self, tree: TokenTree) { - self.trees.push(tree_to_bridge_tree(tree)); - } - - fn build(self) -> TokenStream { - if self.trees.is_empty() { - TokenStream(None) - } else { - TokenStream(Some(bridge::client::TokenStream::concat_trees(None, self.trees))) - } - } - - fn append_to(self, stream: &mut TokenStream) { - if self.trees.is_empty() { - return; - } - stream.0 = Some(bridge::client::TokenStream::concat_trees(stream.0.take(), self.trees)) - } -} - -/// Non-generic helper for implementing `FromIterator` and -/// `Extend` with less monomorphization in calling crates. -struct ConcatStreamsHelper { - streams: Vec, -} - -impl ConcatStreamsHelper { - fn new(capacity: usize) -> Self { - ConcatStreamsHelper { streams: Vec::with_capacity(capacity) } - } - - fn push(&mut self, stream: TokenStream) { - if let Some(stream) = stream.0 { - self.streams.push(stream); - } - } - - fn build(mut self) -> TokenStream { - if self.streams.len() <= 1 { - TokenStream(self.streams.pop()) - } else { - TokenStream(Some(bridge::client::TokenStream::concat_streams(None, self.streams))) - } - } - - fn append_to(mut self, stream: &mut TokenStream) { - if self.streams.is_empty() { - return; - } - let base = stream.0.take(); - if base.is_none() && self.streams.len() == 1 { - stream.0 = self.streams.pop(); - } else { - stream.0 = Some(bridge::client::TokenStream::concat_streams(base, self.streams)); - } - } -} - -/// Collects a number of token trees into a single stream. -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl FromIterator for TokenStream { - fn from_iter>(trees: I) -> Self { - let iter = trees.into_iter(); - let mut builder = ConcatTreesHelper::new(iter.size_hint().0); - iter.for_each(|tree| builder.push(tree)); - builder.build() - } -} - -/// A "flattening" operation on token streams, collects token trees -/// from multiple token streams into a single stream. -#[stable(feature = "proc_macro_lib", since = "1.15.0")] -impl FromIterator for TokenStream { - fn from_iter>(streams: I) -> Self { - let iter = streams.into_iter(); - let mut builder = ConcatStreamsHelper::new(iter.size_hint().0); - iter.for_each(|stream| builder.push(stream)); - builder.build() - } -} - -#[stable(feature = "token_stream_extend", since = "1.30.0")] -impl Extend for TokenStream { - fn extend>(&mut self, trees: I) { - let iter = trees.into_iter(); - let mut builder = ConcatTreesHelper::new(iter.size_hint().0); - iter.for_each(|tree| builder.push(tree)); - builder.append_to(self); - } -} - -#[stable(feature = "token_stream_extend", since = "1.30.0")] -impl Extend for TokenStream { - fn extend>(&mut self, streams: I) { - let iter = streams.into_iter(); - let mut builder = ConcatStreamsHelper::new(iter.size_hint().0); - iter.for_each(|stream| builder.push(stream)); - builder.append_to(self); - } -} - -/// Public implementation details for the `TokenStream` type, such as iterators. -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -pub mod token_stream { - use crate::{bridge, Group, Ident, Literal, Punct, TokenStream, TokenTree}; - - /// An iterator over `TokenStream`'s `TokenTree`s. - /// The iteration is "shallow", e.g., the iterator doesn't recurse into delimited groups, - /// and returns whole groups as token trees. - #[derive(Clone)] - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub struct IntoIter( - std::vec::IntoIter< - bridge::TokenTree< - bridge::client::TokenStream, - bridge::client::Span, - bridge::client::Symbol, - >, - >, - ); - - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - impl Iterator for IntoIter { - type Item = TokenTree; - - fn next(&mut self) -> Option { - self.0.next().map(|tree| match tree { - bridge::TokenTree::Group(tt) => TokenTree::Group(Group(tt)), - bridge::TokenTree::Punct(tt) => TokenTree::Punct(Punct(tt)), - bridge::TokenTree::Ident(tt) => TokenTree::Ident(Ident(tt)), - bridge::TokenTree::Literal(tt) => TokenTree::Literal(Literal(tt)), - }) - } - - fn size_hint(&self) -> (usize, Option) { - self.0.size_hint() - } - - fn count(self) -> usize { - self.0.count() - } - } - - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - impl IntoIterator for TokenStream { - type Item = TokenTree; - type IntoIter = IntoIter; - - fn into_iter(self) -> IntoIter { - IntoIter(self.0.map(|v| v.into_trees()).unwrap_or_default().into_iter()) - } - } -} - -/// `quote!(..)` accepts arbitrary tokens and expands into a `TokenStream` describing the input. -/// For example, `quote!(a + b)` will produce an expression, that, when evaluated, constructs -/// the `TokenStream` `[Ident("a"), Punct('+', Alone), Ident("b")]`. -/// -/// Unquoting is done with `$`, and works by taking the single next ident as the unquoted term. -/// To quote `$` itself, use `$$`. -#[unstable(feature = "proc_macro_quote", issue = "54722")] -#[allow_internal_unstable(proc_macro_def_site, proc_macro_internals)] -#[rustc_builtin_macro] -pub macro quote($($t:tt)*) { - /* compiler built-in */ -} - -#[unstable(feature = "proc_macro_internals", issue = "27812")] -#[doc(hidden)] -mod quote; - -/// A region of source code, along with macro expansion information. -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -#[derive(Copy, Clone)] -pub struct Span(bridge::client::Span); - -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl !Send for Span {} -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl !Sync for Span {} - -macro_rules! diagnostic_method { - ($name:ident, $level:expr) => { - /// Creates a new `Diagnostic` with the given `message` at the span - /// `self`. - #[unstable(feature = "proc_macro_diagnostic", issue = "54140")] - pub fn $name>(self, message: T) -> Diagnostic { - Diagnostic::spanned(self, $level, message) - } - }; -} - -impl Span { - /// A span that resolves at the macro definition site. - #[unstable(feature = "proc_macro_def_site", issue = "54724")] - pub fn def_site() -> Span { - Span(bridge::client::Span::def_site()) - } - - /// The span of the invocation of the current procedural macro. - /// Identifiers created with this span will be resolved as if they were written - /// directly at the macro call location (call-site hygiene) and other code - /// at the macro call site will be able to refer to them as well. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn call_site() -> Span { - Span(bridge::client::Span::call_site()) - } - - /// A span that represents `macro_rules` hygiene, and sometimes resolves at the macro - /// definition site (local variables, labels, `$crate`) and sometimes at the macro - /// call site (everything else). - /// The span location is taken from the call-site. - #[stable(feature = "proc_macro_mixed_site", since = "1.45.0")] - pub fn mixed_site() -> Span { - Span(bridge::client::Span::mixed_site()) - } - - /// The original source file into which this span points. - #[unstable(feature = "proc_macro_span", issue = "54725")] - pub fn source_file(&self) -> SourceFile { - SourceFile(self.0.source_file()) - } - - /// The `Span` for the tokens in the previous macro expansion from which - /// `self` was generated from, if any. - #[unstable(feature = "proc_macro_span", issue = "54725")] - pub fn parent(&self) -> Option { - self.0.parent().map(Span) - } - - /// The span for the origin source code that `self` was generated from. If - /// this `Span` wasn't generated from other macro expansions then the return - /// value is the same as `*self`. - #[unstable(feature = "proc_macro_span", issue = "54725")] - pub fn source(&self) -> Span { - Span(self.0.source()) - } - - /// Returns the span's byte position range in the source file. - #[unstable(feature = "proc_macro_span", issue = "54725")] - pub fn byte_range(&self) -> Range { - self.0.byte_range() - } - - /// Creates an empty span pointing to directly before this span. - #[unstable(feature = "proc_macro_span", issue = "54725")] - pub fn start(&self) -> Span { - Span(self.0.start()) - } - - /// Creates an empty span pointing to directly after this span. - #[unstable(feature = "proc_macro_span", issue = "54725")] - pub fn end(&self) -> Span { - Span(self.0.end()) - } - - /// The one-indexed line of the source file where the span starts. - /// - /// To obtain the line of the span's end, use `span.end().line()`. - #[unstable(feature = "proc_macro_span", issue = "54725")] - pub fn line(&self) -> usize { - self.0.line() - } - - /// The one-indexed column of the source file where the span starts. - /// - /// To obtain the column of the span's end, use `span.end().column()`. - #[unstable(feature = "proc_macro_span", issue = "54725")] - pub fn column(&self) -> usize { - self.0.column() - } - - /// Creates a new span encompassing `self` and `other`. - /// - /// Returns `None` if `self` and `other` are from different files. - #[unstable(feature = "proc_macro_span", issue = "54725")] - pub fn join(&self, other: Span) -> Option { - self.0.join(other.0).map(Span) - } - - /// Creates a new span with the same line/column information as `self` but - /// that resolves symbols as though it were at `other`. - #[stable(feature = "proc_macro_span_resolved_at", since = "1.45.0")] - pub fn resolved_at(&self, other: Span) -> Span { - Span(self.0.resolved_at(other.0)) - } - - /// Creates a new span with the same name resolution behavior as `self` but - /// with the line/column information of `other`. - #[stable(feature = "proc_macro_span_located_at", since = "1.45.0")] - pub fn located_at(&self, other: Span) -> Span { - other.resolved_at(*self) - } - - /// Compares two spans to see if they're equal. - #[unstable(feature = "proc_macro_span", issue = "54725")] - pub fn eq(&self, other: &Span) -> bool { - self.0 == other.0 - } - - /// Returns the source text behind a span. This preserves the original source - /// code, including spaces and comments. It only returns a result if the span - /// corresponds to real source code. - /// - /// Note: The observable result of a macro should only rely on the tokens and - /// not on this source text. The result of this function is a best effort to - /// be used for diagnostics only. - #[stable(feature = "proc_macro_source_text", since = "1.66.0")] - pub fn source_text(&self) -> Option { - self.0.source_text() - } - - // Used by the implementation of `Span::quote` - #[doc(hidden)] - #[unstable(feature = "proc_macro_internals", issue = "27812")] - pub fn save_span(&self) -> usize { - self.0.save_span() - } - - // Used by the implementation of `Span::quote` - #[doc(hidden)] - #[unstable(feature = "proc_macro_internals", issue = "27812")] - pub fn recover_proc_macro_span(id: usize) -> Span { - Span(bridge::client::Span::recover_proc_macro_span(id)) - } - - diagnostic_method!(error, Level::Error); - diagnostic_method!(warning, Level::Warning); - diagnostic_method!(note, Level::Note); - diagnostic_method!(help, Level::Help); -} - -/// Prints a span in a form convenient for debugging. -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl fmt::Debug for Span { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0.fmt(f) - } -} - -/// The source file of a given `Span`. -#[unstable(feature = "proc_macro_span", issue = "54725")] -#[derive(Clone)] -pub struct SourceFile(bridge::client::SourceFile); - -impl SourceFile { - /// Gets the path to this source file. - /// - /// ### Note - /// If the code span associated with this `SourceFile` was generated by an external macro, this - /// macro, this might not be an actual path on the filesystem. Use [`is_real`] to check. - /// - /// Also note that even if `is_real` returns `true`, if `--remap-path-prefix` was passed on - /// the command line, the path as given might not actually be valid. - /// - /// [`is_real`]: Self::is_real - #[unstable(feature = "proc_macro_span", issue = "54725")] - pub fn path(&self) -> PathBuf { - PathBuf::from(self.0.path()) - } - - /// Returns `true` if this source file is a real source file, and not generated by an external - /// macro's expansion. - #[unstable(feature = "proc_macro_span", issue = "54725")] - pub fn is_real(&self) -> bool { - // This is a hack until intercrate spans are implemented and we can have real source files - // for spans generated in external macros. - // https://github.com/rust-lang/rust/pull/43604#issuecomment-333334368 - self.0.is_real() - } -} - -#[unstable(feature = "proc_macro_span", issue = "54725")] -impl fmt::Debug for SourceFile { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("SourceFile") - .field("path", &self.path()) - .field("is_real", &self.is_real()) - .finish() - } -} - -#[unstable(feature = "proc_macro_span", issue = "54725")] -impl PartialEq for SourceFile { - fn eq(&self, other: &Self) -> bool { - self.0.eq(&other.0) - } -} - -#[unstable(feature = "proc_macro_span", issue = "54725")] -impl Eq for SourceFile {} - -/// A single token or a delimited sequence of token trees (e.g., `[1, (), ..]`). -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -#[derive(Clone)] -pub enum TokenTree { - /// A token stream surrounded by bracket delimiters. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - Group(#[stable(feature = "proc_macro_lib2", since = "1.29.0")] Group), - /// An identifier. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - Ident(#[stable(feature = "proc_macro_lib2", since = "1.29.0")] Ident), - /// A single punctuation character (`+`, `,`, `$`, etc.). - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - Punct(#[stable(feature = "proc_macro_lib2", since = "1.29.0")] Punct), - /// A literal character (`'a'`), string (`"hello"`), number (`2.3`), etc. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - Literal(#[stable(feature = "proc_macro_lib2", since = "1.29.0")] Literal), -} - -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl !Send for TokenTree {} -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl !Sync for TokenTree {} - -impl TokenTree { - /// Returns the span of this tree, delegating to the `span` method of - /// the contained token or a delimited stream. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn span(&self) -> Span { - match *self { - TokenTree::Group(ref t) => t.span(), - TokenTree::Ident(ref t) => t.span(), - TokenTree::Punct(ref t) => t.span(), - TokenTree::Literal(ref t) => t.span(), - } - } - - /// Configures the span for *only this token*. - /// - /// Note that if this token is a `Group` then this method will not configure - /// the span of each of the internal tokens, this will simply delegate to - /// the `set_span` method of each variant. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn set_span(&mut self, span: Span) { - match *self { - TokenTree::Group(ref mut t) => t.set_span(span), - TokenTree::Ident(ref mut t) => t.set_span(span), - TokenTree::Punct(ref mut t) => t.set_span(span), - TokenTree::Literal(ref mut t) => t.set_span(span), - } - } -} - -/// Prints token tree in a form convenient for debugging. -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl fmt::Debug for TokenTree { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - // Each of these has the name in the struct type in the derived debug, - // so don't bother with an extra layer of indirection - match *self { - TokenTree::Group(ref tt) => tt.fmt(f), - TokenTree::Ident(ref tt) => tt.fmt(f), - TokenTree::Punct(ref tt) => tt.fmt(f), - TokenTree::Literal(ref tt) => tt.fmt(f), - } - } -} - -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl From for TokenTree { - fn from(g: Group) -> TokenTree { - TokenTree::Group(g) - } -} - -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl From for TokenTree { - fn from(g: Ident) -> TokenTree { - TokenTree::Ident(g) - } -} - -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl From for TokenTree { - fn from(g: Punct) -> TokenTree { - TokenTree::Punct(g) - } -} - -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl From for TokenTree { - fn from(g: Literal) -> TokenTree { - TokenTree::Literal(g) - } -} - -// N.B., the bridge only provides `to_string`, implement `fmt::Display` -// based on it (the reverse of the usual relationship between the two). -#[doc(hidden)] -#[stable(feature = "proc_macro_lib", since = "1.15.0")] -impl ToString for TokenTree { - fn to_string(&self) -> String { - match *self { - TokenTree::Group(ref t) => t.to_string(), - TokenTree::Ident(ref t) => t.to_string(), - TokenTree::Punct(ref t) => t.to_string(), - TokenTree::Literal(ref t) => t.to_string(), - } - } -} - -/// Prints the token tree as a string that is supposed to be losslessly convertible back -/// into the same token tree (modulo spans), except for possibly `TokenTree::Group`s -/// with `Delimiter::None` delimiters and negative numeric literals. -/// -/// Note: the exact form of the output is subject to change, e.g. there might -/// be changes in the whitespace used between tokens. Therefore, you should -/// *not* do any kind of simple substring matching on the output string (as -/// produced by `to_string`) to implement a proc macro, because that matching -/// might stop working if such changes happen. Instead, you should work at the -/// `TokenTree` level, e.g. matching against `TokenTree::Ident`, -/// `TokenTree::Punct`, or `TokenTree::Literal`. -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl fmt::Display for TokenTree { - #[allow(clippy::recursive_format_impl)] // clippy doesn't see the specialization - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str(&self.to_string()) - } -} - -/// A delimited token stream. -/// -/// A `Group` internally contains a `TokenStream` which is surrounded by `Delimiter`s. -#[derive(Clone)] -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -pub struct Group(bridge::Group); - -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl !Send for Group {} -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl !Sync for Group {} - -/// Describes how a sequence of token trees is delimited. -#[derive(Copy, Clone, Debug, PartialEq, Eq)] -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -pub enum Delimiter { - /// `( ... )` - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - Parenthesis, - /// `{ ... }` - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - Brace, - /// `[ ... ]` - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - Bracket, - /// `∅ ... ∅` - /// An invisible delimiter, that may, for example, appear around tokens coming from a - /// "macro variable" `$var`. It is important to preserve operator priorities in cases like - /// `$var * 3` where `$var` is `1 + 2`. - /// Invisible delimiters might not survive roundtrip of a token stream through a string. - /// - ///

- /// - /// Note: rustc currently can ignore the grouping of tokens delimited by `None` in the output - /// of a proc_macro. Only `None`-delimited groups created by a macro_rules macro in the input - /// of a proc_macro macro are preserved, and only in very specific circumstances. - /// Any `None`-delimited groups (re)created by a proc_macro will therefore not preserve - /// operator priorities as indicated above. The other `Delimiter` variants should be used - /// instead in this context. This is a rustc bug. For details, see - /// [rust-lang/rust#67062](https://github.com/rust-lang/rust/issues/67062). - /// - ///
- #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - None, -} - -impl Group { - /// Creates a new `Group` with the given delimiter and token stream. - /// - /// This constructor will set the span for this group to - /// `Span::call_site()`. To change the span you can use the `set_span` - /// method below. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn new(delimiter: Delimiter, stream: TokenStream) -> Group { - Group(bridge::Group { - delimiter, - stream: stream.0, - span: bridge::DelimSpan::from_single(Span::call_site().0), - }) - } - - /// Returns the delimiter of this `Group` - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn delimiter(&self) -> Delimiter { - self.0.delimiter - } - - /// Returns the `TokenStream` of tokens that are delimited in this `Group`. - /// - /// Note that the returned token stream does not include the delimiter - /// returned above. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn stream(&self) -> TokenStream { - TokenStream(self.0.stream.clone()) - } - - /// Returns the span for the delimiters of this token stream, spanning the - /// entire `Group`. - /// - /// ```text - /// pub fn span(&self) -> Span { - /// ^^^^^^^ - /// ``` - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn span(&self) -> Span { - Span(self.0.span.entire) - } - - /// Returns the span pointing to the opening delimiter of this group. - /// - /// ```text - /// pub fn span_open(&self) -> Span { - /// ^ - /// ``` - #[stable(feature = "proc_macro_group_span", since = "1.55.0")] - pub fn span_open(&self) -> Span { - Span(self.0.span.open) - } - - /// Returns the span pointing to the closing delimiter of this group. - /// - /// ```text - /// pub fn span_close(&self) -> Span { - /// ^ - /// ``` - #[stable(feature = "proc_macro_group_span", since = "1.55.0")] - pub fn span_close(&self) -> Span { - Span(self.0.span.close) - } - - /// Configures the span for this `Group`'s delimiters, but not its internal - /// tokens. - /// - /// This method will **not** set the span of all the internal tokens spanned - /// by this group, but rather it will only set the span of the delimiter - /// tokens at the level of the `Group`. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn set_span(&mut self, span: Span) { - self.0.span = bridge::DelimSpan::from_single(span.0); - } -} - -// N.B., the bridge only provides `to_string`, implement `fmt::Display` -// based on it (the reverse of the usual relationship between the two). -#[doc(hidden)] -#[stable(feature = "proc_macro_lib", since = "1.15.0")] -impl ToString for Group { - fn to_string(&self) -> String { - TokenStream::from(TokenTree::from(self.clone())).to_string() - } -} - -/// Prints the group as a string that should be losslessly convertible back -/// into the same group (modulo spans), except for possibly `TokenTree::Group`s -/// with `Delimiter::None` delimiters. -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl fmt::Display for Group { - #[allow(clippy::recursive_format_impl)] // clippy doesn't see the specialization - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str(&self.to_string()) - } -} - -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl fmt::Debug for Group { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Group") - .field("delimiter", &self.delimiter()) - .field("stream", &self.stream()) - .field("span", &self.span()) - .finish() - } -} - -/// A `Punct` is a single punctuation character such as `+`, `-` or `#`. -/// -/// Multi-character operators like `+=` are represented as two instances of `Punct` with different -/// forms of `Spacing` returned. -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -#[derive(Clone)] -pub struct Punct(bridge::Punct); - -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl !Send for Punct {} -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl !Sync for Punct {} - -/// Indicates whether a `Punct` token can join with the following token -/// to form a multi-character operator. -#[derive(Copy, Clone, Debug, PartialEq, Eq)] -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -pub enum Spacing { - /// A `Punct` token can join with the following token to form a multi-character operator. - /// - /// In token streams constructed using proc macro interfaces, `Joint` punctuation tokens can be - /// followed by any other tokens. However, in token streams parsed from source code, the - /// compiler will only set spacing to `Joint` in the following cases. - /// - When a `Punct` is immediately followed by another `Punct` without a whitespace. E.g. `+` - /// is `Joint` in `+=` and `++`. - /// - When a single quote `'` is immediately followed by an identifier without a whitespace. - /// E.g. `'` is `Joint` in `'lifetime`. - /// - /// This list may be extended in the future to enable more token combinations. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - Joint, - /// A `Punct` token cannot join with the following token to form a multi-character operator. - /// - /// `Alone` punctuation tokens can be followed by any other tokens. In token streams parsed - /// from source code, the compiler will set spacing to `Alone` in all cases not covered by the - /// conditions for `Joint` above. E.g. `+` is `Alone` in `+ =`, `+ident` and `+()`. In - /// particular, tokens not followed by anything will be marked as `Alone`. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - Alone, -} - -impl Punct { - /// Creates a new `Punct` from the given character and spacing. - /// The `ch` argument must be a valid punctuation character permitted by the language, - /// otherwise the function will panic. - /// - /// The returned `Punct` will have the default span of `Span::call_site()` - /// which can be further configured with the `set_span` method below. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn new(ch: char, spacing: Spacing) -> Punct { - const LEGAL_CHARS: &[char] = &[ - '=', '<', '>', '!', '~', '+', '-', '*', '/', '%', '^', '&', '|', '@', '.', ',', ';', - ':', '#', '$', '?', '\'', - ]; - if !LEGAL_CHARS.contains(&ch) { - panic!("unsupported character `{:?}`", ch); - } - Punct(bridge::Punct { - ch: ch as u8, - joint: spacing == Spacing::Joint, - span: Span::call_site().0, - }) - } - - /// Returns the value of this punctuation character as `char`. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn as_char(&self) -> char { - self.0.ch as char - } - - /// Returns the spacing of this punctuation character, indicating whether it can be potentially - /// combined into a multi-character operator with the following token (`Joint`), or whether the - /// operator has definitely ended (`Alone`). - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn spacing(&self) -> Spacing { - if self.0.joint { Spacing::Joint } else { Spacing::Alone } - } - - /// Returns the span for this punctuation character. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn span(&self) -> Span { - Span(self.0.span) - } - - /// Configure the span for this punctuation character. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn set_span(&mut self, span: Span) { - self.0.span = span.0; - } -} - -#[doc(hidden)] -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl ToString for Punct { - fn to_string(&self) -> String { - self.as_char().to_string() - } -} - -/// Prints the punctuation character as a string that should be losslessly convertible -/// back into the same character. -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl fmt::Display for Punct { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "{}", self.as_char()) - } -} - -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl fmt::Debug for Punct { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Punct") - .field("ch", &self.as_char()) - .field("spacing", &self.spacing()) - .field("span", &self.span()) - .finish() - } -} - -#[stable(feature = "proc_macro_punct_eq", since = "1.50.0")] -impl PartialEq for Punct { - fn eq(&self, rhs: &char) -> bool { - self.as_char() == *rhs - } -} - -#[stable(feature = "proc_macro_punct_eq_flipped", since = "1.52.0")] -impl PartialEq for char { - fn eq(&self, rhs: &Punct) -> bool { - *self == rhs.as_char() - } -} - -/// An identifier (`ident`). -#[derive(Clone)] -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -pub struct Ident(bridge::Ident); - -impl Ident { - /// Creates a new `Ident` with the given `string` as well as the specified - /// `span`. - /// The `string` argument must be a valid identifier permitted by the - /// language (including keywords, e.g. `self` or `fn`). Otherwise, the function will panic. - /// - /// Note that `span`, currently in rustc, configures the hygiene information - /// for this identifier. - /// - /// As of this time `Span::call_site()` explicitly opts-in to "call-site" hygiene - /// meaning that identifiers created with this span will be resolved as if they were written - /// directly at the location of the macro call, and other code at the macro call site will be - /// able to refer to them as well. - /// - /// Later spans like `Span::def_site()` will allow to opt-in to "definition-site" hygiene - /// meaning that identifiers created with this span will be resolved at the location of the - /// macro definition and other code at the macro call site will not be able to refer to them. - /// - /// Due to the current importance of hygiene this constructor, unlike other - /// tokens, requires a `Span` to be specified at construction. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn new(string: &str, span: Span) -> Ident { - Ident(bridge::Ident { - sym: bridge::client::Symbol::new_ident(string, false), - is_raw: false, - span: span.0, - }) - } - - /// Same as `Ident::new`, but creates a raw identifier (`r#ident`). - /// The `string` argument be a valid identifier permitted by the language - /// (including keywords, e.g. `fn`). Keywords which are usable in path segments - /// (e.g. `self`, `super`) are not supported, and will cause a panic. - #[stable(feature = "proc_macro_raw_ident", since = "1.47.0")] - pub fn new_raw(string: &str, span: Span) -> Ident { - Ident(bridge::Ident { - sym: bridge::client::Symbol::new_ident(string, true), - is_raw: true, - span: span.0, - }) - } - - /// Returns the span of this `Ident`, encompassing the entire string returned - /// by [`to_string`](ToString::to_string). - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn span(&self) -> Span { - Span(self.0.span) - } - - /// Configures the span of this `Ident`, possibly changing its hygiene context. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn set_span(&mut self, span: Span) { - self.0.span = span.0; - } -} - -#[doc(hidden)] -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl ToString for Ident { - fn to_string(&self) -> String { - self.0.sym.with(|sym| if self.0.is_raw { ["r#", sym].concat() } else { sym.to_owned() }) - } -} - -/// Prints the identifier as a string that should be losslessly convertible back -/// into the same identifier. -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl fmt::Display for Ident { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - if self.0.is_raw { - f.write_str("r#")?; - } - fmt::Display::fmt(&self.0.sym, f) - } -} - -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl fmt::Debug for Ident { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Ident") - .field("ident", &self.to_string()) - .field("span", &self.span()) - .finish() - } -} - -/// A literal string (`"hello"`), byte string (`b"hello"`), -/// character (`'a'`), byte character (`b'a'`), an integer or floating point number -/// with or without a suffix (`1`, `1u8`, `2.3`, `2.3f32`). -/// Boolean literals like `true` and `false` do not belong here, they are `Ident`s. -#[derive(Clone)] -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -pub struct Literal(bridge::Literal); - -macro_rules! suffixed_int_literals { - ($($name:ident => $kind:ident,)*) => ($( - /// Creates a new suffixed integer literal with the specified value. - /// - /// This function will create an integer like `1u32` where the integer - /// value specified is the first part of the token and the integral is - /// also suffixed at the end. - /// Literals created from negative numbers might not survive round-trips through - /// `TokenStream` or strings and may be broken into two tokens (`-` and positive literal). - /// - /// Literals created through this method have the `Span::call_site()` - /// span by default, which can be configured with the `set_span` method - /// below. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn $name(n: $kind) -> Literal { - Literal(bridge::Literal { - kind: bridge::LitKind::Integer, - symbol: bridge::client::Symbol::new(&n.to_string()), - suffix: Some(bridge::client::Symbol::new(stringify!($kind))), - span: Span::call_site().0, - }) - } - )*) -} - -macro_rules! unsuffixed_int_literals { - ($($name:ident => $kind:ident,)*) => ($( - /// Creates a new unsuffixed integer literal with the specified value. - /// - /// This function will create an integer like `1` where the integer - /// value specified is the first part of the token. No suffix is - /// specified on this token, meaning that invocations like - /// `Literal::i8_unsuffixed(1)` are equivalent to - /// `Literal::u32_unsuffixed(1)`. - /// Literals created from negative numbers might not survive rountrips through - /// `TokenStream` or strings and may be broken into two tokens (`-` and positive literal). - /// - /// Literals created through this method have the `Span::call_site()` - /// span by default, which can be configured with the `set_span` method - /// below. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn $name(n: $kind) -> Literal { - Literal(bridge::Literal { - kind: bridge::LitKind::Integer, - symbol: bridge::client::Symbol::new(&n.to_string()), - suffix: None, - span: Span::call_site().0, - }) - } - )*) -} - -impl Literal { - fn new(kind: bridge::LitKind, value: &str, suffix: Option<&str>) -> Self { - Literal(bridge::Literal { - kind, - symbol: bridge::client::Symbol::new(value), - suffix: suffix.map(bridge::client::Symbol::new), - span: Span::call_site().0, - }) - } - - suffixed_int_literals! { - u8_suffixed => u8, - u16_suffixed => u16, - u32_suffixed => u32, - u64_suffixed => u64, - u128_suffixed => u128, - usize_suffixed => usize, - i8_suffixed => i8, - i16_suffixed => i16, - i32_suffixed => i32, - i64_suffixed => i64, - i128_suffixed => i128, - isize_suffixed => isize, - } - - unsuffixed_int_literals! { - u8_unsuffixed => u8, - u16_unsuffixed => u16, - u32_unsuffixed => u32, - u64_unsuffixed => u64, - u128_unsuffixed => u128, - usize_unsuffixed => usize, - i8_unsuffixed => i8, - i16_unsuffixed => i16, - i32_unsuffixed => i32, - i64_unsuffixed => i64, - i128_unsuffixed => i128, - isize_unsuffixed => isize, - } - - /// Creates a new unsuffixed floating-point literal. - /// - /// This constructor is similar to those like `Literal::i8_unsuffixed` where - /// the float's value is emitted directly into the token but no suffix is - /// used, so it may be inferred to be a `f64` later in the compiler. - /// Literals created from negative numbers might not survive rountrips through - /// `TokenStream` or strings and may be broken into two tokens (`-` and positive literal). - /// - /// # Panics - /// - /// This function requires that the specified float is finite, for - /// example if it is infinity or NaN this function will panic. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn f32_unsuffixed(n: f32) -> Literal { - if !n.is_finite() { - panic!("Invalid float literal {n}"); - } - let mut repr = n.to_string(); - if !repr.contains('.') { - repr.push_str(".0"); - } - Literal::new(bridge::LitKind::Float, &repr, None) - } - - /// Creates a new suffixed floating-point literal. - /// - /// This constructor will create a literal like `1.0f32` where the value - /// specified is the preceding part of the token and `f32` is the suffix of - /// the token. This token will always be inferred to be an `f32` in the - /// compiler. - /// Literals created from negative numbers might not survive rountrips through - /// `TokenStream` or strings and may be broken into two tokens (`-` and positive literal). - /// - /// # Panics - /// - /// This function requires that the specified float is finite, for - /// example if it is infinity or NaN this function will panic. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn f32_suffixed(n: f32) -> Literal { - if !n.is_finite() { - panic!("Invalid float literal {n}"); - } - Literal::new(bridge::LitKind::Float, &n.to_string(), Some("f32")) - } - - /// Creates a new unsuffixed floating-point literal. - /// - /// This constructor is similar to those like `Literal::i8_unsuffixed` where - /// the float's value is emitted directly into the token but no suffix is - /// used, so it may be inferred to be a `f64` later in the compiler. - /// Literals created from negative numbers might not survive rountrips through - /// `TokenStream` or strings and may be broken into two tokens (`-` and positive literal). - /// - /// # Panics - /// - /// This function requires that the specified float is finite, for - /// example if it is infinity or NaN this function will panic. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn f64_unsuffixed(n: f64) -> Literal { - if !n.is_finite() { - panic!("Invalid float literal {n}"); - } - let mut repr = n.to_string(); - if !repr.contains('.') { - repr.push_str(".0"); - } - Literal::new(bridge::LitKind::Float, &repr, None) - } - - /// Creates a new suffixed floating-point literal. - /// - /// This constructor will create a literal like `1.0f64` where the value - /// specified is the preceding part of the token and `f64` is the suffix of - /// the token. This token will always be inferred to be an `f64` in the - /// compiler. - /// Literals created from negative numbers might not survive rountrips through - /// `TokenStream` or strings and may be broken into two tokens (`-` and positive literal). - /// - /// # Panics - /// - /// This function requires that the specified float is finite, for - /// example if it is infinity or NaN this function will panic. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn f64_suffixed(n: f64) -> Literal { - if !n.is_finite() { - panic!("Invalid float literal {n}"); - } - Literal::new(bridge::LitKind::Float, &n.to_string(), Some("f64")) - } - - /// String literal. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn string(string: &str) -> Literal { - let quoted = format!("{:?}", string); - assert!(quoted.starts_with('"') && quoted.ends_with('"')); - let symbol = "ed[1..quoted.len() - 1]; - Literal::new(bridge::LitKind::Str, symbol, None) - } - - /// Character literal. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn character(ch: char) -> Literal { - let quoted = format!("{:?}", ch); - assert!(quoted.starts_with('\'') && quoted.ends_with('\'')); - let symbol = "ed[1..quoted.len() - 1]; - Literal::new(bridge::LitKind::Char, symbol, None) - } - - /// Byte character literal. - #[stable(feature = "proc_macro_byte_character", since = "1.79.0")] - pub fn byte_character(byte: u8) -> Literal { - let string = [byte].escape_ascii().to_string(); - Literal::new(bridge::LitKind::Byte, &string, None) - } - - /// Byte string literal. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn byte_string(bytes: &[u8]) -> Literal { - let string = bytes.escape_ascii().to_string(); - Literal::new(bridge::LitKind::ByteStr, &string, None) - } - - /// C string literal. - #[stable(feature = "proc_macro_c_str_literals", since = "1.79.0")] - pub fn c_string(string: &CStr) -> Literal { - let string = string.to_bytes().escape_ascii().to_string(); - Literal::new(bridge::LitKind::CStr, &string, None) - } - - /// Returns the span encompassing this literal. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn span(&self) -> Span { - Span(self.0.span) - } - - /// Configures the span associated for this literal. - #[stable(feature = "proc_macro_lib2", since = "1.29.0")] - pub fn set_span(&mut self, span: Span) { - self.0.span = span.0; - } - - /// Returns a `Span` that is a subset of `self.span()` containing only the - /// source bytes in range `range`. Returns `None` if the would-be trimmed - /// span is outside the bounds of `self`. - // FIXME(SergioBenitez): check that the byte range starts and ends at a - // UTF-8 boundary of the source. otherwise, it's likely that a panic will - // occur elsewhere when the source text is printed. - // FIXME(SergioBenitez): there is no way for the user to know what - // `self.span()` actually maps to, so this method can currently only be - // called blindly. For example, `to_string()` for the character 'c' returns - // "'\u{63}'"; there is no way for the user to know whether the source text - // was 'c' or whether it was '\u{63}'. - #[unstable(feature = "proc_macro_span", issue = "54725")] - pub fn subspan>(&self, range: R) -> Option { - self.0.span.subspan(range.start_bound().cloned(), range.end_bound().cloned()).map(Span) - } - - fn with_symbol_and_suffix(&self, f: impl FnOnce(&str, &str) -> R) -> R { - self.0.symbol.with(|symbol| match self.0.suffix { - Some(suffix) => suffix.with(|suffix| f(symbol, suffix)), - None => f(symbol, ""), - }) - } - - /// Invokes the callback with a `&[&str]` consisting of each part of the - /// literal's representation. This is done to allow the `ToString` and - /// `Display` implementations to borrow references to symbol values, and - /// both be optimized to reduce overhead. - fn with_stringify_parts(&self, f: impl FnOnce(&[&str]) -> R) -> R { - /// Returns a string containing exactly `num` '#' characters. - /// Uses a 256-character source string literal which is always safe to - /// index with a `u8` index. - fn get_hashes_str(num: u8) -> &'static str { - const HASHES: &str = "\ - ################################################################\ - ################################################################\ - ################################################################\ - ################################################################\ - "; - const _: () = assert!(HASHES.len() == 256); - &HASHES[..num as usize] - } - - self.with_symbol_and_suffix(|symbol, suffix| match self.0.kind { - bridge::LitKind::Byte => f(&["b'", symbol, "'", suffix]), - bridge::LitKind::Char => f(&["'", symbol, "'", suffix]), - bridge::LitKind::Str => f(&["\"", symbol, "\"", suffix]), - bridge::LitKind::StrRaw(n) => { - let hashes = get_hashes_str(n); - f(&["r", hashes, "\"", symbol, "\"", hashes, suffix]) - } - bridge::LitKind::ByteStr => f(&["b\"", symbol, "\"", suffix]), - bridge::LitKind::ByteStrRaw(n) => { - let hashes = get_hashes_str(n); - f(&["br", hashes, "\"", symbol, "\"", hashes, suffix]) - } - bridge::LitKind::CStr => f(&["c\"", symbol, "\"", suffix]), - bridge::LitKind::CStrRaw(n) => { - let hashes = get_hashes_str(n); - f(&["cr", hashes, "\"", symbol, "\"", hashes, suffix]) - } - - bridge::LitKind::Integer | bridge::LitKind::Float | bridge::LitKind::ErrWithGuar => { - f(&[symbol, suffix]) - } - }) - } -} - -/// Parse a single literal from its stringified representation. -/// -/// In order to parse successfully, the input string must not contain anything -/// but the literal token. Specifically, it must not contain whitespace or -/// comments in addition to the literal. -/// -/// The resulting literal token will have a `Span::call_site()` span. -/// -/// NOTE: some errors may cause panics instead of returning `LexError`. We -/// reserve the right to change these errors into `LexError`s later. -#[stable(feature = "proc_macro_literal_parse", since = "1.54.0")] -impl FromStr for Literal { - type Err = LexError; - - fn from_str(src: &str) -> Result { - match bridge::client::FreeFunctions::literal_from_str(src) { - Ok(literal) => Ok(Literal(literal)), - Err(()) => Err(LexError), - } - } -} - -#[doc(hidden)] -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl ToString for Literal { - fn to_string(&self) -> String { - self.with_stringify_parts(|parts| parts.concat()) - } -} - -/// Prints the literal as a string that should be losslessly convertible -/// back into the same literal (except for possible rounding for floating point literals). -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl fmt::Display for Literal { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.with_stringify_parts(|parts| { - for part in parts { - fmt::Display::fmt(part, f)?; - } - Ok(()) - }) - } -} - -#[stable(feature = "proc_macro_lib2", since = "1.29.0")] -impl fmt::Debug for Literal { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Literal") - // format the kind on one line even in {:#?} mode - .field("kind", &format_args!("{:?}", &self.0.kind)) - .field("symbol", &self.0.symbol) - // format `Some("...")` on one line even in {:#?} mode - .field("suffix", &format_args!("{:?}", &self.0.suffix)) - .field("span", &self.0.span) - .finish() - } -} - -/// Tracked access to environment variables. -#[unstable(feature = "proc_macro_tracked_env", issue = "99515")] -pub mod tracked_env { - use std::env::{self, VarError}; - use std::ffi::OsStr; - - /// Retrieve an environment variable and add it to build dependency info. - /// The build system executing the compiler will know that the variable was accessed during - /// compilation, and will be able to rerun the build when the value of that variable changes. - /// Besides the dependency tracking this function should be equivalent to `env::var` from the - /// standard library, except that the argument must be UTF-8. - #[unstable(feature = "proc_macro_tracked_env", issue = "99515")] - pub fn var + AsRef>(key: K) -> Result { - let key: &str = key.as_ref(); - let value = crate::bridge::client::FreeFunctions::injected_env_var(key) - .map_or_else(|| env::var(key), Ok); - crate::bridge::client::FreeFunctions::track_env_var(key, value.as_deref().ok()); - value - } -} - -/// Tracked access to additional files. -#[unstable(feature = "track_path", issue = "99515")] -pub mod tracked_path { - - /// Track a file explicitly. - /// - /// Commonly used for tracking asset preprocessing. - #[unstable(feature = "track_path", issue = "99515")] - pub fn path>(path: P) { - let path: &str = path.as_ref(); - crate::bridge::client::FreeFunctions::track_path(path); - } -} diff --git a/library/proc_macro/src/quote.rs b/library/proc_macro/src/quote.rs deleted file mode 100644 index 04fa696d5e6be..0000000000000 --- a/library/proc_macro/src/quote.rs +++ /dev/null @@ -1,141 +0,0 @@ -//! # Quasiquoter -//! This file contains the implementation internals of the quasiquoter provided by `quote!`. - -//! This quasiquoter uses macros 2.0 hygiene to reliably access -//! items from `proc_macro`, to build a `proc_macro::TokenStream`. - -use crate::{Delimiter, Group, Ident, Literal, Punct, Spacing, Span, TokenStream, TokenTree}; - -macro_rules! quote_tt { - (($($t:tt)*)) => { Group::new(Delimiter::Parenthesis, quote!($($t)*)) }; - ([$($t:tt)*]) => { Group::new(Delimiter::Bracket, quote!($($t)*)) }; - ({$($t:tt)*}) => { Group::new(Delimiter::Brace, quote!($($t)*)) }; - (,) => { Punct::new(',', Spacing::Alone) }; - (.) => { Punct::new('.', Spacing::Alone) }; - (;) => { Punct::new(';', Spacing::Alone) }; - (!) => { Punct::new('!', Spacing::Alone) }; - (<) => { Punct::new('<', Spacing::Alone) }; - (>) => { Punct::new('>', Spacing::Alone) }; - (&) => { Punct::new('&', Spacing::Alone) }; - (=) => { Punct::new('=', Spacing::Alone) }; - ($i:ident) => { Ident::new(stringify!($i), Span::def_site()) }; -} - -macro_rules! quote_ts { - ((@ $($t:tt)*)) => { $($t)* }; - (::) => { - [ - TokenTree::from(Punct::new(':', Spacing::Joint)), - TokenTree::from(Punct::new(':', Spacing::Alone)), - ].iter() - .cloned() - .map(|mut x| { - x.set_span(Span::def_site()); - x - }) - .collect::() - }; - ($t:tt) => { TokenTree::from(quote_tt!($t)) }; -} - -/// Simpler version of the real `quote!` macro, implemented solely -/// through `macro_rules`, for bootstrapping the real implementation -/// (see the `quote` function), which does not have access to the -/// real `quote!` macro due to the `proc_macro` crate not being -/// able to depend on itself. -/// -/// Note: supported tokens are a subset of the real `quote!`, but -/// unquoting is different: instead of `$x`, this uses `(@ expr)`. -macro_rules! quote { - () => { TokenStream::new() }; - ($($t:tt)*) => { - [ - $(TokenStream::from(quote_ts!($t)),)* - ].iter().cloned().collect::() - }; -} - -/// Quote a `TokenStream` into a `TokenStream`. -/// This is the actual implementation of the `quote!()` proc macro. -/// -/// It is loaded by the compiler in `register_builtin_macros`. -#[unstable(feature = "proc_macro_quote", issue = "54722")] -pub fn quote(stream: TokenStream) -> TokenStream { - if stream.is_empty() { - return quote!(crate::TokenStream::new()); - } - let proc_macro_crate = quote!(crate); - let mut after_dollar = false; - let tokens = stream - .into_iter() - .filter_map(|tree| { - if after_dollar { - after_dollar = false; - match tree { - TokenTree::Ident(_) => { - return Some(quote!(Into::::into( - Clone::clone(&(@ tree))),)); - } - TokenTree::Punct(ref tt) if tt.as_char() == '$' => {} - _ => panic!("`$` must be followed by an ident or `$` in `quote!`"), - } - } else if let TokenTree::Punct(ref tt) = tree { - if tt.as_char() == '$' { - after_dollar = true; - return None; - } - } - - Some(quote!(crate::TokenStream::from((@ match tree { - TokenTree::Punct(tt) => quote!(crate::TokenTree::Punct(crate::Punct::new( - (@ TokenTree::from(Literal::character(tt.as_char()))), - (@ match tt.spacing() { - Spacing::Alone => quote!(crate::Spacing::Alone), - Spacing::Joint => quote!(crate::Spacing::Joint), - }), - ))), - TokenTree::Group(tt) => quote!(crate::TokenTree::Group(crate::Group::new( - (@ match tt.delimiter() { - Delimiter::Parenthesis => quote!(crate::Delimiter::Parenthesis), - Delimiter::Brace => quote!(crate::Delimiter::Brace), - Delimiter::Bracket => quote!(crate::Delimiter::Bracket), - Delimiter::None => quote!(crate::Delimiter::None), - }), - (@ quote(tt.stream())), - ))), - TokenTree::Ident(tt) => quote!(crate::TokenTree::Ident(crate::Ident::new( - (@ TokenTree::from(Literal::string(&tt.to_string()))), - (@ quote_span(proc_macro_crate.clone(), tt.span())), - ))), - TokenTree::Literal(tt) => quote!(crate::TokenTree::Literal({ - let mut iter = (@ TokenTree::from(Literal::string(&tt.to_string()))) - .parse::() - .unwrap() - .into_iter(); - if let (Some(crate::TokenTree::Literal(mut lit)), None) = - (iter.next(), iter.next()) - { - lit.set_span((@ quote_span(proc_macro_crate.clone(), tt.span()))); - lit - } else { - unreachable!() - } - })) - })),)) - }) - .collect::(); - - if after_dollar { - panic!("unexpected trailing `$` in `quote!`"); - } - - quote!([(@ tokens)].iter().cloned().collect::()) -} - -/// Quote a `Span` into a `TokenStream`. -/// This is needed to implement a custom quoter. -#[unstable(feature = "proc_macro_quote", issue = "54722")] -pub fn quote_span(proc_macro_crate: TokenStream, span: Span) -> TokenStream { - let id = span.save_span(); - quote!((@ proc_macro_crate ) ::Span::recover_proc_macro_span((@ TokenTree::from(Literal::usize_unsuffixed(id))))) -} diff --git a/library/profiler_builtins/Cargo.toml b/library/profiler_builtins/Cargo.toml deleted file mode 100644 index 5b10fb5a2bd3f..0000000000000 --- a/library/profiler_builtins/Cargo.toml +++ /dev/null @@ -1,16 +0,0 @@ -[package] -name = "profiler_builtins" -version = "0.0.0" -edition = "2021" - -[lib] -test = false -bench = false -doc = false - -[dependencies] -core = { path = "../core" } -compiler_builtins = { version = "0.1.0", features = ['rustc-dep-of-std'] } - -[build-dependencies] -cc = "1.0.97" diff --git a/library/profiler_builtins/build.rs b/library/profiler_builtins/build.rs deleted file mode 100644 index 9d1c1ba305bc5..0000000000000 --- a/library/profiler_builtins/build.rs +++ /dev/null @@ -1,97 +0,0 @@ -//! Compiles the profiler part of the `compiler-rt` library. -//! -//! See the build.rs for libcompiler_builtins crate for details. - -use std::env; -use std::path::Path; - -fn main() { - println!("cargo:rerun-if-env-changed=LLVM_PROFILER_RT_LIB"); - if let Ok(rt) = env::var("LLVM_PROFILER_RT_LIB") { - println!("cargo:rustc-link-lib=static:+verbatim={rt}"); - return; - } - - let target_os = env::var("CARGO_CFG_TARGET_OS").expect("CARGO_CFG_TARGET_OS was not set"); - let target_env = env::var("CARGO_CFG_TARGET_ENV").expect("CARGO_CFG_TARGET_ENV was not set"); - let cfg = &mut cc::Build::new(); - - // FIXME: `rerun-if-changed` directives are not currently emitted and the build script - // will not rerun on changes in these source files or headers included into them. - let mut profile_sources = vec![ - "GCDAProfiling.c", - "InstrProfiling.c", - "InstrProfilingBuffer.c", - "InstrProfilingFile.c", - "InstrProfilingMerge.c", - "InstrProfilingMergeFile.c", - "InstrProfilingNameVar.c", - "InstrProfilingPlatformAIX.c", - "InstrProfilingPlatformDarwin.c", - "InstrProfilingPlatformFuchsia.c", - "InstrProfilingPlatformLinux.c", - "InstrProfilingPlatformOther.c", - "InstrProfilingPlatformWindows.c", - "InstrProfilingRuntime.cpp", - "InstrProfilingUtil.c", - "InstrProfilingValue.c", - "InstrProfilingVersionVar.c", - "InstrProfilingWriter.c", - // These files were added in LLVM 11. - "InstrProfilingInternal.c", - "InstrProfilingBiasVar.c", - ]; - - if target_env == "msvc" { - // Don't pull in extra libraries on MSVC - cfg.flag("/Zl"); - profile_sources.push("WindowsMMap.c"); - cfg.define("strdup", Some("_strdup")); - cfg.define("open", Some("_open")); - cfg.define("fdopen", Some("_fdopen")); - cfg.define("getpid", Some("_getpid")); - cfg.define("fileno", Some("_fileno")); - } else { - // Turn off various features of gcc and such, mostly copying - // compiler-rt's build system already - cfg.flag("-fno-builtin"); - cfg.flag("-fomit-frame-pointer"); - cfg.define("VISIBILITY_HIDDEN", None); - if target_os != "windows" { - cfg.flag("-fvisibility=hidden"); - cfg.define("COMPILER_RT_HAS_UNAME", Some("1")); - } else { - profile_sources.push("WindowsMMap.c"); - } - } - - // Assume that the Unixes we are building this for have fnctl() available - if env::var_os("CARGO_CFG_UNIX").is_some() { - cfg.define("COMPILER_RT_HAS_FCNTL_LCK", Some("1")); - } - - // This should be a pretty good heuristic for when to set - // COMPILER_RT_HAS_ATOMICS - if env::var_os("CARGO_CFG_TARGET_HAS_ATOMIC") - .map(|features| features.to_string_lossy().to_lowercase().contains("ptr")) - .unwrap_or(false) - { - cfg.define("COMPILER_RT_HAS_ATOMICS", Some("1")); - } - - // Note that this should exist if we're going to run (otherwise we just - // don't build profiler builtins at all). - let root = Path::new("../../src/llvm-project/compiler-rt"); - - let src_root = root.join("lib").join("profile"); - for src in profile_sources { - let path = src_root.join(src); - if path.exists() { - cfg.file(path); - } - } - - cfg.include(root.join("include")); - cfg.warnings(false); - cfg.compile("profiler-rt"); -} diff --git a/library/profiler_builtins/src/lib.rs b/library/profiler_builtins/src/lib.rs deleted file mode 100644 index ac685b18c2911..0000000000000 --- a/library/profiler_builtins/src/lib.rs +++ /dev/null @@ -1,11 +0,0 @@ -#![no_std] -#![feature(profiler_runtime)] -#![profiler_runtime] -#![unstable( - feature = "profiler_runtime_lib", - reason = "internal implementation detail of rustc right now", - issue = "none" -)] -#![allow(unused_features)] -#![allow(internal_features)] -#![feature(staged_api)] diff --git a/library/rtstartup/rsbegin.rs b/library/rtstartup/rsbegin.rs deleted file mode 100644 index 14bce2bbeee2b..0000000000000 --- a/library/rtstartup/rsbegin.rs +++ /dev/null @@ -1,107 +0,0 @@ -// rsbegin.o and rsend.o are the so called "compiler runtime startup objects". -// They contain code needed to correctly initialize the compiler runtime. -// -// When an executable or dylib image is linked, all user code and libraries are -// "sandwiched" between these two object files, so code or data from rsbegin.o -// become first in the respective sections of the image, whereas code and data -// from rsend.o become the last ones. This effect can be used to place symbols -// at the beginning or at the end of a section, as well as to insert any required -// headers or footers. -// -// Note that the actual module entry point is located in the C runtime startup -// object (usually called `crtX.o`), which then invokes initialization callbacks -// of other runtime components (registered via yet another special image section). - -#![feature(no_core)] -#![feature(lang_items)] -#![feature(auto_traits)] -#![crate_type = "rlib"] -#![no_core] -#![allow(non_camel_case_types)] -#![allow(internal_features)] - -#[lang = "sized"] -trait Sized {} -#[lang = "sync"] -auto trait Sync {} -#[lang = "copy"] -trait Copy {} -#[lang = "freeze"] -auto trait Freeze {} - -#[lang = "drop_in_place"] -#[inline] -#[allow(unconditional_recursion)] -pub unsafe fn drop_in_place(to_drop: *mut T) { - drop_in_place(to_drop); -} - -// Frame unwind info registration -// -// Each module's image contains a frame unwind info section (usually -// ".eh_frame"). When a module is loaded/unloaded into the process, the -// unwinder must be informed about the location of this section in memory. The -// methods of achieving that vary by the platform. On some (e.g., Linux), the -// unwinder can discover unwind info sections on its own (by dynamically -// enumerating currently loaded modules via the dl_iterate_phdr() API and -// finding their ".eh_frame" sections); Others, like Windows, require modules -// to actively register their unwind info sections via unwinder API. -#[cfg(all(target_os = "windows", target_arch = "x86", target_env = "gnu"))] -pub mod eh_frames { - #[no_mangle] - #[link_section = ".eh_frame"] - // Marks beginning of the stack frame unwind info section - pub static __EH_FRAME_BEGIN__: [u8; 0] = []; - - // Scratch space for unwinder's internal book-keeping. - // This is defined as `struct object` in $GCC/libgcc/unwind-dw2-fde.h. - static mut OBJ: [isize; 6] = [0; 6]; - - macro_rules! impl_copy { - ($($t:ty)*) => { - $( - impl ::Copy for $t {} - )* - } - } - - impl_copy! { - usize u8 u16 u32 u64 u128 - isize i8 i16 i32 i64 i128 - f32 f64 - bool char - } - - // Unwind info registration/deregistration routines. - extern "C" { - fn __register_frame_info(eh_frame_begin: *const u8, object: *mut u8); - fn __deregister_frame_info(eh_frame_begin: *const u8, object: *mut u8); - } - - unsafe extern "C" fn init() { - // register unwind info on module startup - __register_frame_info(&__EH_FRAME_BEGIN__ as *const u8, &mut OBJ as *mut _ as *mut u8); - } - - unsafe extern "C" fn uninit() { - // unregister on shutdown - __deregister_frame_info(&__EH_FRAME_BEGIN__ as *const u8, &mut OBJ as *mut _ as *mut u8); - } - - // MinGW-specific init/uninit routine registration - pub mod mingw_init { - // MinGW's startup objects (crt0.o / dllcrt0.o) will invoke global constructors in the - // .ctors and .dtors sections on startup and exit. In the case of DLLs, this is done when - // the DLL is loaded and unloaded. - // - // The linker will sort the sections, which ensures that our callbacks are located at the - // end of the list. Since constructors are run in reverse order, this ensures that our - // callbacks are the first and last ones executed. - - #[link_section = ".ctors.65535"] // .ctors.* : C initialization callbacks - pub static P_INIT: unsafe extern "C" fn() = super::init; - - #[link_section = ".dtors.65535"] // .dtors.* : C termination callbacks - pub static P_UNINIT: unsafe extern "C" fn() = super::uninit; - } -} diff --git a/library/rtstartup/rsend.rs b/library/rtstartup/rsend.rs deleted file mode 100644 index 714643c83866f..0000000000000 --- a/library/rtstartup/rsend.rs +++ /dev/null @@ -1,34 +0,0 @@ -// See rsbegin.rs for details. - -#![feature(no_core)] -#![feature(lang_items)] -#![feature(auto_traits)] -#![crate_type = "rlib"] -#![no_core] -#![allow(internal_features)] - -#[lang = "sized"] -trait Sized {} -#[lang = "sync"] -trait Sync {} -impl Sync for T {} -#[lang = "copy"] -trait Copy {} -#[lang = "freeze"] -auto trait Freeze {} - -#[lang = "drop_in_place"] -#[inline] -#[allow(unconditional_recursion)] -pub unsafe fn drop_in_place(to_drop: *mut T) { - drop_in_place(to_drop); -} - -#[cfg(all(target_os = "windows", target_arch = "x86", target_env = "gnu"))] -pub mod eh_frames { - // Terminate the frame unwind info section with a 0 as a sentinel; - // this would be the 'length' field in a real FDE. - #[no_mangle] - #[link_section = ".eh_frame"] - pub static __EH_FRAME_END__: u32 = 0; -} diff --git a/library/rustc-std-workspace-alloc/Cargo.toml b/library/rustc-std-workspace-alloc/Cargo.toml deleted file mode 100644 index 049ca3e46b57d..0000000000000 --- a/library/rustc-std-workspace-alloc/Cargo.toml +++ /dev/null @@ -1,14 +0,0 @@ -[package] -name = "rustc-std-workspace-alloc" -version = "1.99.0" -license = 'MIT OR Apache-2.0' -description = """ -Hack for the compiler's own build system -""" -edition = "2021" - -[lib] -path = "lib.rs" - -[dependencies] -alloc = { path = "../alloc" } diff --git a/library/rustc-std-workspace-alloc/lib.rs b/library/rustc-std-workspace-alloc/lib.rs deleted file mode 100644 index 87db7af44ae09..0000000000000 --- a/library/rustc-std-workspace-alloc/lib.rs +++ /dev/null @@ -1,9 +0,0 @@ -#![feature(no_core)] -#![no_core] - -// See rustc-std-workspace-core for why this crate is needed. - -// Rename the crate to avoid conflicting with the alloc module in alloc. -extern crate alloc as foo; - -pub use foo::*; diff --git a/library/rustc-std-workspace-core/Cargo.toml b/library/rustc-std-workspace-core/Cargo.toml deleted file mode 100644 index ff5cfcbd64144..0000000000000 --- a/library/rustc-std-workspace-core/Cargo.toml +++ /dev/null @@ -1,14 +0,0 @@ -[package] -name = "rustc-std-workspace-core" -version = "1.99.0" -license = 'MIT OR Apache-2.0' -description = """ -Hack for the compiler's own build system -""" -edition = "2021" - -[lib] -path = "lib.rs" - -[dependencies] -core = { path = "../core" } diff --git a/library/rustc-std-workspace-core/README.md b/library/rustc-std-workspace-core/README.md deleted file mode 100644 index 40e0b62afabfb..0000000000000 --- a/library/rustc-std-workspace-core/README.md +++ /dev/null @@ -1,29 +0,0 @@ -# The `rustc-std-workspace-core` crate - -This crate is a shim and empty crate which simply depends on `libcore` and -reexports all of its contents. The crate is the crux of empowering the standard -library to depend on crates from crates.io - -Crates on crates.io that the standard library depend on need to depend on the -`rustc-std-workspace-core` crate from crates.io, which is empty. We use -`[patch]` to override it to this crate in this repository. As a result, crates -on crates.io will draw a dependency edge to `libcore`, the version defined in -this repository. That should draw all the dependency edges to ensure Cargo -builds crates successfully! - -Note that crates on crates.io need to depend on this crate with the name `core` -for everything to work correctly. To do that they can use: - -```toml -core = { version = "1.0.0", optional = true, package = 'rustc-std-workspace-core' } -``` - -Through the use of the `package` key the crate is renamed to `core`, meaning -it'll look like - -``` ---extern core=.../librustc_std_workspace_core-XXXXXXX.rlib -``` - -when Cargo invokes the compiler, satisfying the implicit `extern crate core` -directive injected by the compiler. diff --git a/library/rustc-std-workspace-core/lib.rs b/library/rustc-std-workspace-core/lib.rs deleted file mode 100644 index 1432785256166..0000000000000 --- a/library/rustc-std-workspace-core/lib.rs +++ /dev/null @@ -1,4 +0,0 @@ -#![feature(no_core)] -#![no_core] - -pub use core::*; diff --git a/library/rustc-std-workspace-std/Cargo.toml b/library/rustc-std-workspace-std/Cargo.toml deleted file mode 100644 index 3a1dc2a02b557..0000000000000 --- a/library/rustc-std-workspace-std/Cargo.toml +++ /dev/null @@ -1,14 +0,0 @@ -[package] -name = "rustc-std-workspace-std" -version = "1.99.0" -license = 'MIT OR Apache-2.0' -description = """ -Hack for the compiler's own build system -""" -edition = "2021" - -[lib] -path = "lib.rs" - -[dependencies] -std = { path = "../std" } diff --git a/library/rustc-std-workspace-std/README.md b/library/rustc-std-workspace-std/README.md deleted file mode 100644 index 2228907f304c4..0000000000000 --- a/library/rustc-std-workspace-std/README.md +++ /dev/null @@ -1,3 +0,0 @@ -# The `rustc-std-workspace-std` crate - -See documentation for the `rustc-std-workspace-core` crate. diff --git a/library/rustc-std-workspace-std/lib.rs b/library/rustc-std-workspace-std/lib.rs deleted file mode 100644 index 1e955c61ac85f..0000000000000 --- a/library/rustc-std-workspace-std/lib.rs +++ /dev/null @@ -1,2 +0,0 @@ -#![feature(restricted_std)] -pub use std::*; diff --git a/library/std/Cargo.toml b/library/std/Cargo.toml deleted file mode 100644 index e56f03808b311..0000000000000 --- a/library/std/Cargo.toml +++ /dev/null @@ -1,113 +0,0 @@ -cargo-features = ["public-dependency"] - -[package] -name = "std" -version = "0.0.0" -license = "MIT OR Apache-2.0" -repository = "https://github.com/rust-lang/rust.git" -description = "The Rust Standard Library" -edition = "2021" - -[lib] -crate-type = ["dylib", "rlib"] - -[dependencies] -alloc = { path = "../alloc", public = true } -cfg-if = { version = "1.0", features = ['rustc-dep-of-std'] } -panic_unwind = { path = "../panic_unwind", optional = true } -panic_abort = { path = "../panic_abort" } -core = { path = "../core", public = true } -compiler_builtins = { version = "0.1.105" } -profiler_builtins = { path = "../profiler_builtins", optional = true } -unwind = { path = "../unwind" } -hashbrown = { version = "0.14", default-features = false, features = ['rustc-dep-of-std'] } -std_detect = { path = "../stdarch/crates/std_detect", default-features = false, features = ['rustc-dep-of-std'] } - -# Dependencies of the `backtrace` crate -rustc-demangle = { version = "0.1.21", features = ['rustc-dep-of-std'] } - -[target.'cfg(not(all(windows, target_env = "msvc", not(target_vendor = "uwp"))))'.dependencies] -miniz_oxide = { version = "0.7.0", optional = true, default-features = false } -addr2line = { version = "0.21.0", optional = true, default-features = false } - -[target.'cfg(not(all(windows, target_env = "msvc")))'.dependencies] -libc = { version = "0.2.153", default-features = false, features = ['rustc-dep-of-std'], public = true } - -[target.'cfg(all(not(target_os = "aix"), not(all(windows, target_env = "msvc", not(target_vendor = "uwp")))))'.dependencies] -object = { version = "0.32.0", default-features = false, optional = true, features = ['read_core', 'elf', 'macho', 'pe', 'unaligned', 'archive'] } - -[target.'cfg(target_os = "aix")'.dependencies] -object = { version = "0.32.0", default-features = false, optional = true, features = ['read_core', 'xcoff', 'unaligned', 'archive'] } - -[dev-dependencies] -rand = { version = "0.8.5", default-features = false, features = ["alloc"] } -rand_xorshift = "0.3.0" - -[target.'cfg(any(all(target_family = "wasm", target_os = "unknown"), target_os = "xous", all(target_vendor = "fortanix", target_env = "sgx")))'.dependencies] -dlmalloc = { version = "0.2.4", features = ['rustc-dep-of-std'] } - -[target.x86_64-fortanix-unknown-sgx.dependencies] -fortanix-sgx-abi = { version = "0.5.0", features = ['rustc-dep-of-std'], public = true } - -[target.'cfg(target_os = "hermit")'.dependencies] -hermit-abi = { version = "0.3.9", features = ['rustc-dep-of-std'], public = true } - -[target.'cfg(target_os = "wasi")'.dependencies] -wasi = { version = "0.11.0", features = ['rustc-dep-of-std'], default-features = false } - -[target.'cfg(target_os = "uefi")'.dependencies] -r-efi = { version = "4.2.0", features = ['rustc-dep-of-std'] } -r-efi-alloc = { version = "1.0.0", features = ['rustc-dep-of-std'] } - -[features] -backtrace = [ - 'addr2line/rustc-dep-of-std', - 'object/rustc-dep-of-std', - 'miniz_oxide/rustc-dep-of-std', -] - -panic-unwind = ["panic_unwind"] -profiler = ["profiler_builtins"] -compiler-builtins-c = ["alloc/compiler-builtins-c"] -compiler-builtins-mem = ["alloc/compiler-builtins-mem"] -compiler-builtins-no-asm = ["alloc/compiler-builtins-no-asm"] -compiler-builtins-mangled-names = ["alloc/compiler-builtins-mangled-names"] -compiler-builtins-weak-intrinsics = ["alloc/compiler-builtins-weak-intrinsics"] -llvm-libunwind = ["unwind/llvm-libunwind"] -system-llvm-libunwind = ["unwind/system-llvm-libunwind"] - -# Make panics and failed asserts immediately abort without formatting any message -panic_immediate_abort = ["core/panic_immediate_abort", "alloc/panic_immediate_abort"] -# Choose algorithms that are optimized for binary size instead of runtime performance -optimize_for_size = ["core/optimize_for_size", "alloc/optimize_for_size"] - -# Enable std_detect default features for stdarch/crates/std_detect: -# https://github.com/rust-lang/stdarch/blob/master/crates/std_detect/Cargo.toml -std_detect_file_io = ["std_detect/std_detect_file_io"] -std_detect_dlsym_getauxval = ["std_detect/std_detect_dlsym_getauxval"] -std_detect_env_override = ["std_detect/std_detect_env_override"] - -[package.metadata.fortanix-sgx] -# Maximum possible number of threads when testing -threads = 125 -# Maximum heap size -heap_size = 0x8000000 - -[[bench]] -name = "stdbenches" -path = "benches/lib.rs" -test = true - -[lints.rust.unexpected_cfgs] -level = "warn" -# x.py uses beta cargo, so `check-cfg` entries do not yet take effect -# for rust-lang/rust. But for users of `-Zbuild-std` it does. -# The unused warning is waiting for rust-lang/cargo#13925 to reach beta. -check-cfg = [ - 'cfg(bootstrap)', - 'cfg(target_arch, values("xtensa"))', - # std use #[path] imports to portable-simd `std_float` crate - # and to the `backtrace` crate which messes-up with Cargo list - # of declared features, we therefor expect any feature cfg - 'cfg(feature, values(any()))', -] diff --git a/library/std/benches/hash/map.rs b/library/std/benches/hash/map.rs deleted file mode 100644 index bf646cbae47db..0000000000000 --- a/library/std/benches/hash/map.rs +++ /dev/null @@ -1,103 +0,0 @@ -#![cfg(test)] - -use std::collections::HashMap; -use test::Bencher; - -#[bench] -fn new_drop(b: &mut Bencher) { - b.iter(|| { - let m: HashMap = HashMap::new(); - assert_eq!(m.len(), 0); - }) -} - -#[bench] -fn new_insert_drop(b: &mut Bencher) { - b.iter(|| { - let mut m = HashMap::new(); - m.insert(0, 0); - assert_eq!(m.len(), 1); - }) -} - -#[bench] -fn grow_by_insertion(b: &mut Bencher) { - let mut m = HashMap::new(); - - for i in 1..1001 { - m.insert(i, i); - } - - let mut k = 1001; - - b.iter(|| { - m.insert(k, k); - k += 1; - }); -} - -#[bench] -fn find_existing(b: &mut Bencher) { - let mut m = HashMap::new(); - - for i in 1..1001 { - m.insert(i, i); - } - - b.iter(|| { - for i in 1..1001 { - m.contains_key(&i); - } - }); -} - -#[bench] -fn find_nonexisting(b: &mut Bencher) { - let mut m = HashMap::new(); - - for i in 1..1001 { - m.insert(i, i); - } - - b.iter(|| { - for i in 1001..2001 { - m.contains_key(&i); - } - }); -} - -#[bench] -fn hashmap_as_queue(b: &mut Bencher) { - let mut m = HashMap::new(); - - for i in 1..1001 { - m.insert(i, i); - } - - let mut k = 1; - - b.iter(|| { - m.remove(&k); - m.insert(k + 1000, k + 1000); - k += 1; - }); -} - -#[bench] -fn get_remove_insert(b: &mut Bencher) { - let mut m = HashMap::new(); - - for i in 1..1001 { - m.insert(i, i); - } - - let mut k = 1; - - b.iter(|| { - m.get(&(k + 400)); - m.get(&(k + 2000)); - m.remove(&k); - m.insert(k + 1000, k + 1000); - k += 1; - }) -} diff --git a/library/std/benches/hash/mod.rs b/library/std/benches/hash/mod.rs deleted file mode 100644 index 42401a21b766d..0000000000000 --- a/library/std/benches/hash/mod.rs +++ /dev/null @@ -1,2 +0,0 @@ -mod map; -mod set_ops; diff --git a/library/std/benches/hash/set_ops.rs b/library/std/benches/hash/set_ops.rs deleted file mode 100644 index 1a4c4a66ee9e0..0000000000000 --- a/library/std/benches/hash/set_ops.rs +++ /dev/null @@ -1,42 +0,0 @@ -use std::collections::HashSet; -use test::Bencher; - -#[bench] -fn set_difference(b: &mut Bencher) { - let small: HashSet<_> = (0..10).collect(); - let large: HashSet<_> = (0..100).collect(); - - b.iter(|| small.difference(&large).count()); -} - -#[bench] -fn set_is_subset(b: &mut Bencher) { - let small: HashSet<_> = (0..10).collect(); - let large: HashSet<_> = (0..100).collect(); - - b.iter(|| small.is_subset(&large)); -} - -#[bench] -fn set_intersection(b: &mut Bencher) { - let small: HashSet<_> = (0..10).collect(); - let large: HashSet<_> = (0..100).collect(); - - b.iter(|| small.intersection(&large).count()); -} - -#[bench] -fn set_symmetric_difference(b: &mut Bencher) { - let small: HashSet<_> = (0..10).collect(); - let large: HashSet<_> = (0..100).collect(); - - b.iter(|| small.symmetric_difference(&large).count()); -} - -#[bench] -fn set_union(b: &mut Bencher) { - let small: HashSet<_> = (0..10).collect(); - let large: HashSet<_> = (0..100).collect(); - - b.iter(|| small.union(&large).count()); -} diff --git a/library/std/benches/lib.rs b/library/std/benches/lib.rs deleted file mode 100644 index 1b21c230a0bf2..0000000000000 --- a/library/std/benches/lib.rs +++ /dev/null @@ -1,7 +0,0 @@ -// Disabling in Miri as these would take too long. -#![cfg(not(miri))] -#![feature(test)] - -extern crate test; - -mod hash; diff --git a/library/std/build.rs b/library/std/build.rs deleted file mode 100644 index 7d975df545ecf..0000000000000 --- a/library/std/build.rs +++ /dev/null @@ -1,73 +0,0 @@ -use std::env; - -fn main() { - println!("cargo:rerun-if-changed=build.rs"); - let target_arch = env::var("CARGO_CFG_TARGET_ARCH").expect("CARGO_CFG_TARGET_ARCH was not set"); - let target_os = env::var("CARGO_CFG_TARGET_OS").expect("CARGO_CFG_TARGET_OS was not set"); - let target_vendor = - env::var("CARGO_CFG_TARGET_VENDOR").expect("CARGO_CFG_TARGET_VENDOR was not set"); - let target_env = env::var("CARGO_CFG_TARGET_ENV").expect("CARGO_CFG_TARGET_ENV was not set"); - - println!("cargo:rustc-check-cfg=cfg(netbsd10)"); - if target_os == "netbsd" && env::var("RUSTC_STD_NETBSD10").is_ok() { - println!("cargo:rustc-cfg=netbsd10"); - } - - println!("cargo:rustc-check-cfg=cfg(restricted_std)"); - if target_os == "linux" - || target_os == "android" - || target_os == "netbsd" - || target_os == "dragonfly" - || target_os == "openbsd" - || target_os == "freebsd" - || target_os == "solaris" - || target_os == "illumos" - || target_os == "macos" - || target_os == "ios" - || target_os == "tvos" - || target_os == "watchos" - || target_os == "visionos" - || target_os == "windows" - || target_os == "fuchsia" - || (target_vendor == "fortanix" && target_env == "sgx") - || target_os == "hermit" - || target_os == "l4re" - || target_os == "redox" - || target_os == "haiku" - || target_os == "vxworks" - || target_arch == "wasm32" - || target_arch == "wasm64" - || target_os == "espidf" - || target_os.starts_with("solid") - || (target_vendor == "nintendo" && target_env == "newlib") - || target_os == "vita" - || target_os == "aix" - || target_os == "nto" - || target_os == "xous" - || target_os == "hurd" - || target_os == "uefi" - || target_os == "teeos" - || target_os == "zkvm" - - // See src/bootstrap/src/core/build_steps/synthetic_targets.rs - || env::var("RUSTC_BOOTSTRAP_SYNTHETIC_TARGET").is_ok() - { - // These platforms don't have any special requirements. - } else { - // This is for Cargo's build-std support, to mark std as unstable for - // typically no_std platforms. - // This covers: - // - os=none ("bare metal" targets) - // - mipsel-sony-psp - // - nvptx64-nvidia-cuda - // - arch=avr - // - JSON targets - // - Any new targets that have not been explicitly added above. - println!("cargo:rustc-cfg=restricted_std"); - } - - println!("cargo:rustc-check-cfg=cfg(backtrace_in_libstd)"); - println!("cargo:rustc-cfg=backtrace_in_libstd"); - - println!("cargo:rustc-env=STD_ENV_ARCH={}", env::var("CARGO_CFG_TARGET_ARCH").unwrap()); -} diff --git a/library/std/src/alloc.rs b/library/std/src/alloc.rs deleted file mode 100644 index b98fbbf762fa2..0000000000000 --- a/library/std/src/alloc.rs +++ /dev/null @@ -1,435 +0,0 @@ -//! Memory allocation APIs. -//! -//! In a given program, the standard library has one “global” memory allocator -//! that is used for example by `Box` and `Vec`. -//! -//! Currently the default global allocator is unspecified. Libraries, however, -//! like `cdylib`s and `staticlib`s are guaranteed to use the [`System`] by -//! default. -//! -//! # The `#[global_allocator]` attribute -//! -//! This attribute allows configuring the choice of global allocator. -//! You can use this to implement a completely custom global allocator -//! to route all default allocation requests to a custom object. -//! -//! ```rust -//! use std::alloc::{GlobalAlloc, System, Layout}; -//! -//! struct MyAllocator; -//! -//! unsafe impl GlobalAlloc for MyAllocator { -//! unsafe fn alloc(&self, layout: Layout) -> *mut u8 { -//! System.alloc(layout) -//! } -//! -//! unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) { -//! System.dealloc(ptr, layout) -//! } -//! } -//! -//! #[global_allocator] -//! static GLOBAL: MyAllocator = MyAllocator; -//! -//! fn main() { -//! // This `Vec` will allocate memory through `GLOBAL` above -//! let mut v = Vec::new(); -//! v.push(1); -//! } -//! ``` -//! -//! The attribute is used on a `static` item whose type implements the -//! [`GlobalAlloc`] trait. This type can be provided by an external library: -//! -//! ```rust,ignore (demonstrates crates.io usage) -//! use jemallocator::Jemalloc; -//! -//! #[global_allocator] -//! static GLOBAL: Jemalloc = Jemalloc; -//! -//! fn main() {} -//! ``` -//! -//! The `#[global_allocator]` can only be used once in a crate -//! or its recursive dependencies. - -#![deny(unsafe_op_in_unsafe_fn)] -#![stable(feature = "alloc_module", since = "1.28.0")] - -use core::hint; -use core::ptr::NonNull; -use core::sync::atomic::{AtomicPtr, Ordering}; -use core::{mem, ptr}; - -#[stable(feature = "alloc_module", since = "1.28.0")] -#[doc(inline)] -pub use alloc_crate::alloc::*; - -/// The default memory allocator provided by the operating system. -/// -/// This is based on `malloc` on Unix platforms and `HeapAlloc` on Windows, -/// plus related functions. However, it is not valid to mix use of the backing -/// system allocator with `System`, as this implementation may include extra -/// work, such as to serve alignment requests greater than the alignment -/// provided directly by the backing system allocator. -/// -/// This type implements the `GlobalAlloc` trait and Rust programs by default -/// work as if they had this definition: -/// -/// ```rust -/// use std::alloc::System; -/// -/// #[global_allocator] -/// static A: System = System; -/// -/// fn main() { -/// let a = Box::new(4); // Allocates from the system allocator. -/// println!("{a}"); -/// } -/// ``` -/// -/// You can also define your own wrapper around `System` if you'd like, such as -/// keeping track of the number of all bytes allocated: -/// -/// ```rust -/// use std::alloc::{System, GlobalAlloc, Layout}; -/// use std::sync::atomic::{AtomicUsize, Ordering::Relaxed}; -/// -/// struct Counter; -/// -/// static ALLOCATED: AtomicUsize = AtomicUsize::new(0); -/// -/// unsafe impl GlobalAlloc for Counter { -/// unsafe fn alloc(&self, layout: Layout) -> *mut u8 { -/// let ret = System.alloc(layout); -/// if !ret.is_null() { -/// ALLOCATED.fetch_add(layout.size(), Relaxed); -/// } -/// ret -/// } -/// -/// unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) { -/// System.dealloc(ptr, layout); -/// ALLOCATED.fetch_sub(layout.size(), Relaxed); -/// } -/// } -/// -/// #[global_allocator] -/// static A: Counter = Counter; -/// -/// fn main() { -/// println!("allocated bytes before main: {}", ALLOCATED.load(Relaxed)); -/// } -/// ``` -/// -/// It can also be used directly to allocate memory independently of whatever -/// global allocator has been selected for a Rust program. For example if a Rust -/// program opts in to using jemalloc as the global allocator, `System` will -/// still allocate memory using `malloc` and `HeapAlloc`. -#[stable(feature = "alloc_system_type", since = "1.28.0")] -#[derive(Debug, Default, Copy, Clone)] -pub struct System; - -impl System { - #[inline] - fn alloc_impl(&self, layout: Layout, zeroed: bool) -> Result, AllocError> { - match layout.size() { - 0 => Ok(NonNull::slice_from_raw_parts(layout.dangling(), 0)), - // SAFETY: `layout` is non-zero in size, - size => unsafe { - let raw_ptr = if zeroed { - GlobalAlloc::alloc_zeroed(self, layout) - } else { - GlobalAlloc::alloc(self, layout) - }; - let ptr = NonNull::new(raw_ptr).ok_or(AllocError)?; - Ok(NonNull::slice_from_raw_parts(ptr, size)) - }, - } - } - - // SAFETY: Same as `Allocator::grow` - #[inline] - unsafe fn grow_impl( - &self, - ptr: NonNull, - old_layout: Layout, - new_layout: Layout, - zeroed: bool, - ) -> Result, AllocError> { - debug_assert!( - new_layout.size() >= old_layout.size(), - "`new_layout.size()` must be greater than or equal to `old_layout.size()`" - ); - - match old_layout.size() { - 0 => self.alloc_impl(new_layout, zeroed), - - // SAFETY: `new_size` is non-zero as `new_size` is greater than or equal to `old_size` - // as required by safety conditions and the `old_size == 0` case was handled in the - // previous match arm. Other conditions must be upheld by the caller - old_size if old_layout.align() == new_layout.align() => unsafe { - let new_size = new_layout.size(); - - // `realloc` probably checks for `new_size >= old_layout.size()` or something similar. - hint::assert_unchecked(new_size >= old_layout.size()); - - let raw_ptr = GlobalAlloc::realloc(self, ptr.as_ptr(), old_layout, new_size); - let ptr = NonNull::new(raw_ptr).ok_or(AllocError)?; - if zeroed { - raw_ptr.add(old_size).write_bytes(0, new_size - old_size); - } - Ok(NonNull::slice_from_raw_parts(ptr, new_size)) - }, - - // SAFETY: because `new_layout.size()` must be greater than or equal to `old_size`, - // both the old and new memory allocation are valid for reads and writes for `old_size` - // bytes. Also, because the old allocation wasn't yet deallocated, it cannot overlap - // `new_ptr`. Thus, the call to `copy_nonoverlapping` is safe. The safety contract - // for `dealloc` must be upheld by the caller. - old_size => unsafe { - let new_ptr = self.alloc_impl(new_layout, zeroed)?; - ptr::copy_nonoverlapping(ptr.as_ptr(), new_ptr.as_mut_ptr(), old_size); - Allocator::deallocate(self, ptr, old_layout); - Ok(new_ptr) - }, - } - } -} - -// The Allocator impl checks the layout size to be non-zero and forwards to the GlobalAlloc impl, -// which is in `std::sys::*::alloc`. -#[unstable(feature = "allocator_api", issue = "32838")] -unsafe impl Allocator for System { - #[inline] - fn allocate(&self, layout: Layout) -> Result, AllocError> { - self.alloc_impl(layout, false) - } - - #[inline] - fn allocate_zeroed(&self, layout: Layout) -> Result, AllocError> { - self.alloc_impl(layout, true) - } - - #[inline] - unsafe fn deallocate(&self, ptr: NonNull, layout: Layout) { - if layout.size() != 0 { - // SAFETY: `layout` is non-zero in size, - // other conditions must be upheld by the caller - unsafe { GlobalAlloc::dealloc(self, ptr.as_ptr(), layout) } - } - } - - #[inline] - unsafe fn grow( - &self, - ptr: NonNull, - old_layout: Layout, - new_layout: Layout, - ) -> Result, AllocError> { - // SAFETY: all conditions must be upheld by the caller - unsafe { self.grow_impl(ptr, old_layout, new_layout, false) } - } - - #[inline] - unsafe fn grow_zeroed( - &self, - ptr: NonNull, - old_layout: Layout, - new_layout: Layout, - ) -> Result, AllocError> { - // SAFETY: all conditions must be upheld by the caller - unsafe { self.grow_impl(ptr, old_layout, new_layout, true) } - } - - #[inline] - unsafe fn shrink( - &self, - ptr: NonNull, - old_layout: Layout, - new_layout: Layout, - ) -> Result, AllocError> { - debug_assert!( - new_layout.size() <= old_layout.size(), - "`new_layout.size()` must be smaller than or equal to `old_layout.size()`" - ); - - match new_layout.size() { - // SAFETY: conditions must be upheld by the caller - 0 => unsafe { - Allocator::deallocate(self, ptr, old_layout); - Ok(NonNull::slice_from_raw_parts(new_layout.dangling(), 0)) - }, - - // SAFETY: `new_size` is non-zero. Other conditions must be upheld by the caller - new_size if old_layout.align() == new_layout.align() => unsafe { - // `realloc` probably checks for `new_size <= old_layout.size()` or something similar. - hint::assert_unchecked(new_size <= old_layout.size()); - - let raw_ptr = GlobalAlloc::realloc(self, ptr.as_ptr(), old_layout, new_size); - let ptr = NonNull::new(raw_ptr).ok_or(AllocError)?; - Ok(NonNull::slice_from_raw_parts(ptr, new_size)) - }, - - // SAFETY: because `new_size` must be smaller than or equal to `old_layout.size()`, - // both the old and new memory allocation are valid for reads and writes for `new_size` - // bytes. Also, because the old allocation wasn't yet deallocated, it cannot overlap - // `new_ptr`. Thus, the call to `copy_nonoverlapping` is safe. The safety contract - // for `dealloc` must be upheld by the caller. - new_size => unsafe { - let new_ptr = Allocator::allocate(self, new_layout)?; - ptr::copy_nonoverlapping(ptr.as_ptr(), new_ptr.as_mut_ptr(), new_size); - Allocator::deallocate(self, ptr, old_layout); - Ok(new_ptr) - }, - } - } -} - -static HOOK: AtomicPtr<()> = AtomicPtr::new(ptr::null_mut()); - -/// Registers a custom allocation error hook, replacing any that was previously registered. -/// -/// The allocation error hook is invoked when an infallible memory allocation fails — that is, -/// as a consequence of calling [`handle_alloc_error`] — before the runtime aborts. -/// -/// The allocation error hook is a global resource. [`take_alloc_error_hook`] may be used to -/// retrieve a previously registered hook and wrap or discard it. -/// -/// # What the provided `hook` function should expect -/// -/// The hook function is provided with a [`Layout`] struct which contains information -/// about the allocation that failed. -/// -/// The hook function may choose to panic or abort; in the event that it returns normally, this -/// will cause an immediate abort. -/// -/// Since [`take_alloc_error_hook`] is a safe function that allows retrieving the hook, the hook -/// function must be _sound_ to call even if no memory allocations were attempted. -/// -/// # The default hook -/// -/// The default hook, used if [`set_alloc_error_hook`] is never called, prints a message to -/// standard error (and then returns, causing the runtime to abort the process). -/// Compiler options may cause it to panic instead, and the default behavior may be changed -/// to panicking in future versions of Rust. -/// -/// # Examples -/// -/// ``` -/// #![feature(alloc_error_hook)] -/// -/// use std::alloc::{Layout, set_alloc_error_hook}; -/// -/// fn custom_alloc_error_hook(layout: Layout) { -/// panic!("memory allocation of {} bytes failed", layout.size()); -/// } -/// -/// set_alloc_error_hook(custom_alloc_error_hook); -/// ``` -#[unstable(feature = "alloc_error_hook", issue = "51245")] -pub fn set_alloc_error_hook(hook: fn(Layout)) { - HOOK.store(hook as *mut (), Ordering::Release); -} - -/// Unregisters the current allocation error hook, returning it. -/// -/// *See also the function [`set_alloc_error_hook`].* -/// -/// If no custom hook is registered, the default hook will be returned. -#[unstable(feature = "alloc_error_hook", issue = "51245")] -pub fn take_alloc_error_hook() -> fn(Layout) { - let hook = HOOK.swap(ptr::null_mut(), Ordering::Acquire); - if hook.is_null() { default_alloc_error_hook } else { unsafe { mem::transmute(hook) } } -} - -fn default_alloc_error_hook(layout: Layout) { - extern "Rust" { - // This symbol is emitted by rustc next to __rust_alloc_error_handler. - // Its value depends on the -Zoom={panic,abort} compiler option. - static __rust_alloc_error_handler_should_panic: u8; - } - - if unsafe { __rust_alloc_error_handler_should_panic != 0 } { - panic!("memory allocation of {} bytes failed", layout.size()); - } else { - // This is the default path taken on OOM, and the only path taken on stable with std. - // Crucially, it does *not* call any user-defined code, and therefore users do not have to - // worry about allocation failure causing reentrancy issues. That makes it different from - // the default `__rdl_oom` defined in alloc (i.e., the default alloc error handler that is - // called when there is no `#[alloc_error_handler]`), which triggers a regular panic and - // thus can invoke a user-defined panic hook, executing arbitrary user-defined code. - rtprintpanic!("memory allocation of {} bytes failed\n", layout.size()); - } -} - -#[cfg(not(test))] -#[doc(hidden)] -#[alloc_error_handler] -#[unstable(feature = "alloc_internals", issue = "none")] -pub fn rust_oom(layout: Layout) -> ! { - let hook = HOOK.load(Ordering::Acquire); - let hook: fn(Layout) = - if hook.is_null() { default_alloc_error_hook } else { unsafe { mem::transmute(hook) } }; - hook(layout); - crate::process::abort() -} - -#[cfg(not(test))] -#[doc(hidden)] -#[allow(unused_attributes)] -#[unstable(feature = "alloc_internals", issue = "none")] -pub mod __default_lib_allocator { - use super::{GlobalAlloc, Layout, System}; - // These magic symbol names are used as a fallback for implementing the - // `__rust_alloc` etc symbols (see `src/liballoc/alloc.rs`) when there is - // no `#[global_allocator]` attribute. - - // for symbol names src/librustc_ast/expand/allocator.rs - // for signatures src/librustc_allocator/lib.rs - - // linkage directives are provided as part of the current compiler allocator - // ABI - - #[rustc_std_internal_symbol] - pub unsafe extern "C" fn __rdl_alloc(size: usize, align: usize) -> *mut u8 { - // SAFETY: see the guarantees expected by `Layout::from_size_align` and - // `GlobalAlloc::alloc`. - unsafe { - let layout = Layout::from_size_align_unchecked(size, align); - System.alloc(layout) - } - } - - #[rustc_std_internal_symbol] - pub unsafe extern "C" fn __rdl_dealloc(ptr: *mut u8, size: usize, align: usize) { - // SAFETY: see the guarantees expected by `Layout::from_size_align` and - // `GlobalAlloc::dealloc`. - unsafe { System.dealloc(ptr, Layout::from_size_align_unchecked(size, align)) } - } - - #[rustc_std_internal_symbol] - pub unsafe extern "C" fn __rdl_realloc( - ptr: *mut u8, - old_size: usize, - align: usize, - new_size: usize, - ) -> *mut u8 { - // SAFETY: see the guarantees expected by `Layout::from_size_align` and - // `GlobalAlloc::realloc`. - unsafe { - let old_layout = Layout::from_size_align_unchecked(old_size, align); - System.realloc(ptr, old_layout, new_size) - } - } - - #[rustc_std_internal_symbol] - pub unsafe extern "C" fn __rdl_alloc_zeroed(size: usize, align: usize) -> *mut u8 { - // SAFETY: see the guarantees expected by `Layout::from_size_align` and - // `GlobalAlloc::alloc_zeroed`. - unsafe { - let layout = Layout::from_size_align_unchecked(size, align); - System.alloc_zeroed(layout) - } - } -} diff --git a/library/std/src/ascii.rs b/library/std/src/ascii.rs deleted file mode 100644 index b18ab50de123e..0000000000000 --- a/library/std/src/ascii.rs +++ /dev/null @@ -1,211 +0,0 @@ -//! Operations on ASCII strings and characters. -//! -//! Most string operations in Rust act on UTF-8 strings. However, at times it -//! makes more sense to only consider the ASCII character set for a specific -//! operation. -//! -//! The [`AsciiExt`] trait provides methods that allow for character -//! operations that only act on the ASCII subset and leave non-ASCII characters -//! alone. -//! -//! The [`escape_default`] function provides an iterator over the bytes of an -//! escaped version of the character given. - -#![stable(feature = "rust1", since = "1.0.0")] - -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::ascii::{escape_default, EscapeDefault}; - -#[unstable(feature = "ascii_char", issue = "110998")] -pub use core::ascii::Char; - -/// Extension methods for ASCII-subset only operations. -/// -/// Be aware that operations on seemingly non-ASCII characters can sometimes -/// have unexpected results. Consider this example: -/// -/// ``` -/// use std::ascii::AsciiExt; -/// -/// assert_eq!(AsciiExt::to_ascii_uppercase("café"), "CAFÉ"); -/// assert_eq!(AsciiExt::to_ascii_uppercase("café"), "CAFé"); -/// ``` -/// -/// In the first example, the lowercased string is represented `"cafe\u{301}"` -/// (the last character is an acute accent [combining character]). Unlike the -/// other characters in the string, the combining character will not get mapped -/// to an uppercase variant, resulting in `"CAFE\u{301}"`. In the second -/// example, the lowercased string is represented `"caf\u{e9}"` (the last -/// character is a single Unicode character representing an 'e' with an acute -/// accent). Since the last character is defined outside the scope of ASCII, -/// it will not get mapped to an uppercase variant, resulting in `"CAF\u{e9}"`. -/// -/// [combining character]: https://en.wikipedia.org/wiki/Combining_character -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "1.26.0", note = "use inherent methods instead")] -pub trait AsciiExt { - /// Container type for copied ASCII characters. - #[stable(feature = "rust1", since = "1.0.0")] - type Owned; - - /// Checks if the value is within the ASCII range. - /// - /// # Note - /// - /// This method is deprecated in favor of the identically-named - /// inherent methods on `u8`, `char`, `[u8]` and `str`. - #[stable(feature = "rust1", since = "1.0.0")] - fn is_ascii(&self) -> bool; - - /// Makes a copy of the value in its ASCII upper case equivalent. - /// - /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', - /// but non-ASCII letters are unchanged. - /// - /// To uppercase the value in-place, use [`make_ascii_uppercase`]. - /// - /// To uppercase ASCII characters in addition to non-ASCII characters, use - /// [`str::to_uppercase`]. - /// - /// # Note - /// - /// This method is deprecated in favor of the identically-named - /// inherent methods on `u8`, `char`, `[u8]` and `str`. - /// - /// [`make_ascii_uppercase`]: AsciiExt::make_ascii_uppercase - #[stable(feature = "rust1", since = "1.0.0")] - #[allow(deprecated)] - fn to_ascii_uppercase(&self) -> Self::Owned; - - /// Makes a copy of the value in its ASCII lower case equivalent. - /// - /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', - /// but non-ASCII letters are unchanged. - /// - /// To lowercase the value in-place, use [`make_ascii_lowercase`]. - /// - /// To lowercase ASCII characters in addition to non-ASCII characters, use - /// [`str::to_lowercase`]. - /// - /// # Note - /// - /// This method is deprecated in favor of the identically-named - /// inherent methods on `u8`, `char`, `[u8]` and `str`. - /// - /// [`make_ascii_lowercase`]: AsciiExt::make_ascii_lowercase - #[stable(feature = "rust1", since = "1.0.0")] - #[allow(deprecated)] - fn to_ascii_lowercase(&self) -> Self::Owned; - - /// Checks that two values are an ASCII case-insensitive match. - /// - /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`, - /// but without allocating and copying temporaries. - /// - /// # Note - /// - /// This method is deprecated in favor of the identically-named - /// inherent methods on `u8`, `char`, `[u8]` and `str`. - #[stable(feature = "rust1", since = "1.0.0")] - fn eq_ignore_ascii_case(&self, other: &Self) -> bool; - - /// Converts this type to its ASCII upper case equivalent in-place. - /// - /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', - /// but non-ASCII letters are unchanged. - /// - /// To return a new uppercased value without modifying the existing one, use - /// [`to_ascii_uppercase`]. - /// - /// # Note - /// - /// This method is deprecated in favor of the identically-named - /// inherent methods on `u8`, `char`, `[u8]` and `str`. - /// - /// [`to_ascii_uppercase`]: AsciiExt::to_ascii_uppercase - #[stable(feature = "ascii", since = "1.9.0")] - fn make_ascii_uppercase(&mut self); - - /// Converts this type to its ASCII lower case equivalent in-place. - /// - /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', - /// but non-ASCII letters are unchanged. - /// - /// To return a new lowercased value without modifying the existing one, use - /// [`to_ascii_lowercase`]. - /// - /// # Note - /// - /// This method is deprecated in favor of the identically-named - /// inherent methods on `u8`, `char`, `[u8]` and `str`. - /// - /// [`to_ascii_lowercase`]: AsciiExt::to_ascii_lowercase - #[stable(feature = "ascii", since = "1.9.0")] - fn make_ascii_lowercase(&mut self); -} - -macro_rules! delegating_ascii_methods { - () => { - #[inline] - fn is_ascii(&self) -> bool { - self.is_ascii() - } - - #[inline] - fn to_ascii_uppercase(&self) -> Self::Owned { - self.to_ascii_uppercase() - } - - #[inline] - fn to_ascii_lowercase(&self) -> Self::Owned { - self.to_ascii_lowercase() - } - - #[inline] - fn eq_ignore_ascii_case(&self, o: &Self) -> bool { - self.eq_ignore_ascii_case(o) - } - - #[inline] - fn make_ascii_uppercase(&mut self) { - self.make_ascii_uppercase(); - } - - #[inline] - fn make_ascii_lowercase(&mut self) { - self.make_ascii_lowercase(); - } - }; -} - -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated)] -impl AsciiExt for u8 { - type Owned = u8; - - delegating_ascii_methods!(); -} - -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated)] -impl AsciiExt for char { - type Owned = char; - - delegating_ascii_methods!(); -} - -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated)] -impl AsciiExt for [u8] { - type Owned = Vec; - - delegating_ascii_methods!(); -} - -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated)] -impl AsciiExt for str { - type Owned = String; - - delegating_ascii_methods!(); -} diff --git a/library/std/src/backtrace.rs b/library/std/src/backtrace.rs deleted file mode 100644 index 475b3e7eb9312..0000000000000 --- a/library/std/src/backtrace.rs +++ /dev/null @@ -1,473 +0,0 @@ -//! Support for capturing a stack backtrace of an OS thread -//! -//! This module contains the support necessary to capture a stack backtrace of a -//! running OS thread from the OS thread itself. The `Backtrace` type supports -//! capturing a stack trace via the `Backtrace::capture` and -//! `Backtrace::force_capture` functions. -//! -//! A backtrace is typically quite handy to attach to errors (e.g. types -//! implementing `std::error::Error`) to get a causal chain of where an error -//! was generated. -//! -//! ## Accuracy -//! -//! Backtraces are attempted to be as accurate as possible, but no guarantees -//! are provided about the exact accuracy of a backtrace. Instruction pointers, -//! symbol names, filenames, line numbers, etc, may all be incorrect when -//! reported. Accuracy is attempted on a best-effort basis, however, any bug -//! reports are always welcome to indicate areas of improvement! -//! -//! For most platforms a backtrace with a filename/line number requires that -//! programs be compiled with debug information. Without debug information -//! filenames/line numbers will not be reported. -//! -//! ## Platform support -//! -//! Not all platforms that std compiles for support capturing backtraces. Some -//! platforms simply do nothing when capturing a backtrace. To check whether the -//! platform supports capturing backtraces you can consult the `BacktraceStatus` -//! enum as a result of `Backtrace::status`. -//! -//! Like above with accuracy platform support is done on a best effort basis. -//! Sometimes libraries might not be available at runtime or something may go -//! wrong which would cause a backtrace to not be captured. Please feel free to -//! report issues with platforms where a backtrace cannot be captured though! -//! -//! ## Environment Variables -//! -//! The `Backtrace::capture` function might not actually capture a backtrace by -//! default. Its behavior is governed by two environment variables: -//! -//! * `RUST_LIB_BACKTRACE` - if this is set to `0` then `Backtrace::capture` -//! will never capture a backtrace. Any other value set will enable -//! `Backtrace::capture`. -//! -//! * `RUST_BACKTRACE` - if `RUST_LIB_BACKTRACE` is not set, then this variable -//! is consulted with the same rules of `RUST_LIB_BACKTRACE`. -//! -//! * If neither of the above env vars are set, then `Backtrace::capture` will -//! be disabled. -//! -//! Capturing a backtrace can be a quite expensive runtime operation, so the -//! environment variables allow either forcibly disabling this runtime -//! performance hit or allow selectively enabling it in some programs. -//! -//! Note that the `Backtrace::force_capture` function can be used to ignore -//! these environment variables. Also note that the state of environment -//! variables is cached once the first backtrace is created, so altering -//! `RUST_LIB_BACKTRACE` or `RUST_BACKTRACE` at runtime might not actually change -//! how backtraces are captured. - -#![stable(feature = "backtrace", since = "1.65.0")] - -#[cfg(test)] -mod tests; - -// NB: A note on resolution of a backtrace: -// -// Backtraces primarily happen in two steps, one is where we actually capture -// the stack backtrace, giving us a list of instruction pointers corresponding -// to stack frames. Next we take these instruction pointers and, one-by-one, -// turn them into a human readable name (like `main`). -// -// The first phase can be somewhat expensive (walking the stack), especially -// on MSVC where debug information is consulted to return inline frames each as -// their own frame. The second phase, however, is almost always extremely -// expensive (on the order of milliseconds sometimes) when it's consulting debug -// information. -// -// We attempt to amortize this cost as much as possible by delaying resolution -// of an address to a human readable name for as long as possible. When -// `Backtrace::create` is called to capture a backtrace it doesn't actually -// perform any symbol resolution, but rather we lazily resolve symbols only just -// before they're needed for printing. This way we can make capturing a -// backtrace and throwing it away much cheaper, but actually printing a -// backtrace is still basically the same cost. -// -// This strategy comes at the cost of some synchronization required inside of a -// `Backtrace`, but that's a relatively small price to pay relative to capturing -// a backtrace or actually symbolizing it. - -use crate::backtrace_rs::{self, BytesOrWideString}; -use crate::env; -use crate::ffi::c_void; -use crate::fmt; -use crate::panic::UnwindSafe; -use crate::sync::atomic::{AtomicU8, Ordering::Relaxed}; -use crate::sync::LazyLock; -use crate::sys_common::backtrace::{lock, output_filename, set_image_base}; - -/// A captured OS thread stack backtrace. -/// -/// This type represents a stack backtrace for an OS thread captured at a -/// previous point in time. In some instances the `Backtrace` type may -/// internally be empty due to configuration. For more information see -/// `Backtrace::capture`. -#[stable(feature = "backtrace", since = "1.65.0")] -#[must_use] -pub struct Backtrace { - inner: Inner, -} - -/// The current status of a backtrace, indicating whether it was captured or -/// whether it is empty for some other reason. -#[stable(feature = "backtrace", since = "1.65.0")] -#[non_exhaustive] -#[derive(Debug, PartialEq, Eq)] -pub enum BacktraceStatus { - /// Capturing a backtrace is not supported, likely because it's not - /// implemented for the current platform. - #[stable(feature = "backtrace", since = "1.65.0")] - Unsupported, - /// Capturing a backtrace has been disabled through either the - /// `RUST_LIB_BACKTRACE` or `RUST_BACKTRACE` environment variables. - #[stable(feature = "backtrace", since = "1.65.0")] - Disabled, - /// A backtrace has been captured and the `Backtrace` should print - /// reasonable information when rendered. - #[stable(feature = "backtrace", since = "1.65.0")] - Captured, -} - -enum Inner { - Unsupported, - Disabled, - Captured(LazyLock), -} - -struct Capture { - actual_start: usize, - frames: Vec, -} - -fn _assert_send_sync() { - fn _assert() {} - _assert::(); -} - -/// A single frame of a backtrace. -#[unstable(feature = "backtrace_frames", issue = "79676")] -pub struct BacktraceFrame { - frame: RawFrame, - symbols: Vec, -} - -#[derive(Debug)] -enum RawFrame { - Actual(backtrace_rs::Frame), - #[cfg(test)] - Fake, -} - -struct BacktraceSymbol { - name: Option>, - filename: Option, - lineno: Option, - colno: Option, -} - -enum BytesOrWide { - Bytes(Vec), - Wide(Vec), -} - -#[stable(feature = "backtrace", since = "1.65.0")] -impl fmt::Debug for Backtrace { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - let capture = match &self.inner { - Inner::Unsupported => return fmt.write_str(""), - Inner::Disabled => return fmt.write_str(""), - Inner::Captured(c) => &**c, - }; - - let frames = &capture.frames[capture.actual_start..]; - - write!(fmt, "Backtrace ")?; - - let mut dbg = fmt.debug_list(); - - for frame in frames { - if frame.frame.ip().is_null() { - continue; - } - - dbg.entries(&frame.symbols); - } - - dbg.finish() - } -} - -#[unstable(feature = "backtrace_frames", issue = "79676")] -impl fmt::Debug for BacktraceFrame { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - let mut dbg = fmt.debug_list(); - dbg.entries(&self.symbols); - dbg.finish() - } -} - -impl fmt::Debug for BacktraceSymbol { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - // FIXME: improve formatting: https://github.com/rust-lang/rust/issues/65280 - // FIXME: Also, include column numbers into the debug format as Display already has them. - // Until there are stable per-frame accessors, the format shouldn't be changed: - // https://github.com/rust-lang/rust/issues/65280#issuecomment-638966585 - write!(fmt, "{{ ")?; - - if let Some(fn_name) = self.name.as_ref().map(|b| backtrace_rs::SymbolName::new(b)) { - write!(fmt, "fn: \"{:#}\"", fn_name)?; - } else { - write!(fmt, "fn: ")?; - } - - if let Some(fname) = self.filename.as_ref() { - write!(fmt, ", file: \"{:?}\"", fname)?; - } - - if let Some(line) = self.lineno { - write!(fmt, ", line: {:?}", line)?; - } - - write!(fmt, " }}") - } -} - -impl fmt::Debug for BytesOrWide { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - output_filename( - fmt, - match self { - BytesOrWide::Bytes(w) => BytesOrWideString::Bytes(w), - BytesOrWide::Wide(w) => BytesOrWideString::Wide(w), - }, - backtrace_rs::PrintFmt::Short, - crate::env::current_dir().as_ref().ok(), - ) - } -} - -impl Backtrace { - /// Returns whether backtrace captures are enabled through environment - /// variables. - fn enabled() -> bool { - // Cache the result of reading the environment variables to make - // backtrace captures speedy, because otherwise reading environment - // variables every time can be somewhat slow. - static ENABLED: AtomicU8 = AtomicU8::new(0); - match ENABLED.load(Relaxed) { - 0 => {} - 1 => return false, - _ => return true, - } - let enabled = match env::var("RUST_LIB_BACKTRACE") { - Ok(s) => s != "0", - Err(_) => match env::var("RUST_BACKTRACE") { - Ok(s) => s != "0", - Err(_) => false, - }, - }; - ENABLED.store(enabled as u8 + 1, Relaxed); - enabled - } - - /// Capture a stack backtrace of the current thread. - /// - /// This function will capture a stack backtrace of the current OS thread of - /// execution, returning a `Backtrace` type which can be later used to print - /// the entire stack trace or render it to a string. - /// - /// This function will be a noop if the `RUST_BACKTRACE` or - /// `RUST_LIB_BACKTRACE` backtrace variables are both not set. If either - /// environment variable is set and enabled then this function will actually - /// capture a backtrace. Capturing a backtrace can be both memory intensive - /// and slow, so these environment variables allow liberally using - /// `Backtrace::capture` and only incurring a slowdown when the environment - /// variables are set. - /// - /// To forcibly capture a backtrace regardless of environment variables, use - /// the `Backtrace::force_capture` function. - #[stable(feature = "backtrace", since = "1.65.0")] - #[inline(never)] // want to make sure there's a frame here to remove - pub fn capture() -> Backtrace { - if !Backtrace::enabled() { - return Backtrace { inner: Inner::Disabled }; - } - Backtrace::create(Backtrace::capture as usize) - } - - /// Forcibly captures a full backtrace, regardless of environment variable - /// configuration. - /// - /// This function behaves the same as `capture` except that it ignores the - /// values of the `RUST_BACKTRACE` and `RUST_LIB_BACKTRACE` environment - /// variables, always capturing a backtrace. - /// - /// Note that capturing a backtrace can be an expensive operation on some - /// platforms, so this should be used with caution in performance-sensitive - /// parts of code. - #[stable(feature = "backtrace", since = "1.65.0")] - #[inline(never)] // want to make sure there's a frame here to remove - pub fn force_capture() -> Backtrace { - Backtrace::create(Backtrace::force_capture as usize) - } - - /// Forcibly captures a disabled backtrace, regardless of environment - /// variable configuration. - #[stable(feature = "backtrace", since = "1.65.0")] - #[rustc_const_stable(feature = "backtrace", since = "1.65.0")] - pub const fn disabled() -> Backtrace { - Backtrace { inner: Inner::Disabled } - } - - // Capture a backtrace which start just before the function addressed by - // `ip` - fn create(ip: usize) -> Backtrace { - let _lock = lock(); - let mut frames = Vec::new(); - let mut actual_start = None; - set_image_base(); - unsafe { - backtrace_rs::trace_unsynchronized(|frame| { - frames.push(BacktraceFrame { - frame: RawFrame::Actual(frame.clone()), - symbols: Vec::new(), - }); - if frame.symbol_address().addr() == ip && actual_start.is_none() { - actual_start = Some(frames.len()); - } - true - }); - } - - // If no frames came out assume that this is an unsupported platform - // since `backtrace` doesn't provide a way of learning this right now, - // and this should be a good enough approximation. - let inner = if frames.is_empty() { - Inner::Unsupported - } else { - Inner::Captured(LazyLock::new(lazy_resolve(Capture { - actual_start: actual_start.unwrap_or(0), - frames, - }))) - }; - - Backtrace { inner } - } - - /// Returns the status of this backtrace, indicating whether this backtrace - /// request was unsupported, disabled, or a stack trace was actually - /// captured. - #[stable(feature = "backtrace", since = "1.65.0")] - #[must_use] - pub fn status(&self) -> BacktraceStatus { - match self.inner { - Inner::Unsupported => BacktraceStatus::Unsupported, - Inner::Disabled => BacktraceStatus::Disabled, - Inner::Captured(_) => BacktraceStatus::Captured, - } - } -} - -impl<'a> Backtrace { - /// Returns an iterator over the backtrace frames. - #[must_use] - #[unstable(feature = "backtrace_frames", issue = "79676")] - pub fn frames(&'a self) -> &'a [BacktraceFrame] { - if let Inner::Captured(c) = &self.inner { &c.frames } else { &[] } - } -} - -#[stable(feature = "backtrace", since = "1.65.0")] -impl fmt::Display for Backtrace { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - let capture = match &self.inner { - Inner::Unsupported => return fmt.write_str("unsupported backtrace"), - Inner::Disabled => return fmt.write_str("disabled backtrace"), - Inner::Captured(c) => &**c, - }; - - let full = fmt.alternate(); - let (frames, style) = if full { - (&capture.frames[..], backtrace_rs::PrintFmt::Full) - } else { - (&capture.frames[capture.actual_start..], backtrace_rs::PrintFmt::Short) - }; - - // When printing paths we try to strip the cwd if it exists, otherwise - // we just print the path as-is. Note that we also only do this for the - // short format, because if it's full we presumably want to print - // everything. - let cwd = crate::env::current_dir(); - let mut print_path = move |fmt: &mut fmt::Formatter<'_>, path: BytesOrWideString<'_>| { - output_filename(fmt, path, style, cwd.as_ref().ok()) - }; - - let mut f = backtrace_rs::BacktraceFmt::new(fmt, style, &mut print_path); - f.add_context()?; - for frame in frames { - if frame.symbols.is_empty() { - f.frame().print_raw(frame.frame.ip(), None, None, None)?; - } else { - for symbol in frame.symbols.iter() { - f.frame().print_raw_with_column( - frame.frame.ip(), - symbol.name.as_ref().map(|b| backtrace_rs::SymbolName::new(b)), - symbol.filename.as_ref().map(|b| match b { - BytesOrWide::Bytes(w) => BytesOrWideString::Bytes(w), - BytesOrWide::Wide(w) => BytesOrWideString::Wide(w), - }), - symbol.lineno, - symbol.colno, - )?; - } - } - } - f.finish()?; - Ok(()) - } -} - -type LazyResolve = impl (FnOnce() -> Capture) + Send + Sync + UnwindSafe; - -fn lazy_resolve(mut capture: Capture) -> LazyResolve { - move || { - // Use the global backtrace lock to synchronize this as it's a - // requirement of the `backtrace` crate, and then actually resolve - // everything. - let _lock = lock(); - for frame in capture.frames.iter_mut() { - let symbols = &mut frame.symbols; - let frame = match &frame.frame { - RawFrame::Actual(frame) => frame, - #[cfg(test)] - RawFrame::Fake => unimplemented!(), - }; - unsafe { - backtrace_rs::resolve_frame_unsynchronized(frame, |symbol| { - symbols.push(BacktraceSymbol { - name: symbol.name().map(|m| m.as_bytes().to_vec()), - filename: symbol.filename_raw().map(|b| match b { - BytesOrWideString::Bytes(b) => BytesOrWide::Bytes(b.to_owned()), - BytesOrWideString::Wide(b) => BytesOrWide::Wide(b.to_owned()), - }), - lineno: symbol.lineno(), - colno: symbol.colno(), - }); - }); - } - } - - capture - } -} - -impl RawFrame { - fn ip(&self) -> *mut c_void { - match self { - RawFrame::Actual(frame) => frame.ip(), - #[cfg(test)] - RawFrame::Fake => crate::ptr::without_provenance_mut(1), - } - } -} diff --git a/library/std/src/backtrace/tests.rs b/library/std/src/backtrace/tests.rs deleted file mode 100644 index 174d62813bd58..0000000000000 --- a/library/std/src/backtrace/tests.rs +++ /dev/null @@ -1,100 +0,0 @@ -use super::*; -use crate::panic::RefUnwindSafe; - -fn generate_fake_frames() -> Vec { - vec![ - BacktraceFrame { - frame: RawFrame::Fake, - symbols: vec![BacktraceSymbol { - name: Some(b"std::backtrace::Backtrace::create".to_vec()), - filename: Some(BytesOrWide::Bytes(b"rust/backtrace.rs".to_vec())), - lineno: Some(100), - colno: None, - }], - }, - BacktraceFrame { - frame: RawFrame::Fake, - symbols: vec![BacktraceSymbol { - name: Some(b"__rust_maybe_catch_panic".to_vec()), - filename: None, - lineno: None, - colno: None, - }], - }, - BacktraceFrame { - frame: RawFrame::Fake, - symbols: vec![ - BacktraceSymbol { - name: Some(b"std::rt::lang_start_internal".to_vec()), - filename: Some(BytesOrWide::Bytes(b"rust/rt.rs".to_vec())), - lineno: Some(300), - colno: Some(5), - }, - BacktraceSymbol { - name: Some(b"std::rt::lang_start".to_vec()), - filename: Some(BytesOrWide::Bytes(b"rust/rt.rs".to_vec())), - lineno: Some(400), - colno: None, - }, - ], - }, - ] -} - -#[test] -fn test_debug() { - let backtrace = Backtrace { - inner: Inner::Captured(LazyLock::preinit(Capture { - actual_start: 1, - frames: generate_fake_frames(), - })), - }; - - #[rustfmt::skip] - let expected = "Backtrace [\ - \n { fn: \"__rust_maybe_catch_panic\" },\ - \n { fn: \"std::rt::lang_start_internal\", file: \"rust/rt.rs\", line: 300 },\ - \n { fn: \"std::rt::lang_start\", file: \"rust/rt.rs\", line: 400 },\ - \n]"; - - assert_eq!(format!("{backtrace:#?}"), expected); - - // Format the backtrace a second time, just to make sure lazily resolved state is stable - assert_eq!(format!("{backtrace:#?}"), expected); -} - -#[test] -fn test_frames() { - let backtrace = Backtrace { - inner: Inner::Captured(LazyLock::preinit(Capture { - actual_start: 1, - frames: generate_fake_frames(), - })), - }; - - let frames = backtrace.frames(); - - #[rustfmt::skip] - let expected = vec![ - "[ - { fn: \"std::backtrace::Backtrace::create\", file: \"rust/backtrace.rs\", line: 100 }, -]", - "[ - { fn: \"__rust_maybe_catch_panic\" }, -]", - "[ - { fn: \"std::rt::lang_start_internal\", file: \"rust/rt.rs\", line: 300 }, - { fn: \"std::rt::lang_start\", file: \"rust/rt.rs\", line: 400 }, -]" - ]; - - let mut iter = frames.iter().zip(expected.iter()); - - assert!(iter.all(|(f, e)| format!("{f:#?}") == *e)); -} - -#[test] -fn backtrace_unwind_safe() { - fn assert_unwind_safe() {} - assert_unwind_safe::(); -} diff --git a/library/std/src/collections/hash/map.rs b/library/std/src/collections/hash/map.rs deleted file mode 100644 index 5039f0b6bb289..0000000000000 --- a/library/std/src/collections/hash/map.rs +++ /dev/null @@ -1,3248 +0,0 @@ -#[cfg(test)] -mod tests; - -use self::Entry::*; - -use hashbrown::hash_map as base; - -use crate::borrow::Borrow; -use crate::collections::TryReserveError; -use crate::collections::TryReserveErrorKind; -use crate::error::Error; -use crate::fmt::{self, Debug}; -use crate::hash::{BuildHasher, Hash, RandomState}; -use crate::iter::FusedIterator; -use crate::ops::Index; - -/// A [hash map] implemented with quadratic probing and SIMD lookup. -/// -/// By default, `HashMap` uses a hashing algorithm selected to provide -/// resistance against HashDoS attacks. The algorithm is randomly seeded, and a -/// reasonable best-effort is made to generate this seed from a high quality, -/// secure source of randomness provided by the host without blocking the -/// program. Because of this, the randomness of the seed depends on the output -/// quality of the system's random number coroutine when the seed is created. -/// In particular, seeds generated when the system's entropy pool is abnormally -/// low such as during system boot may be of a lower quality. -/// -/// The default hashing algorithm is currently SipHash 1-3, though this is -/// subject to change at any point in the future. While its performance is very -/// competitive for medium sized keys, other hashing algorithms will outperform -/// it for small keys such as integers as well as large keys such as long -/// strings, though those algorithms will typically *not* protect against -/// attacks such as HashDoS. -/// -/// The hashing algorithm can be replaced on a per-`HashMap` basis using the -/// [`default`], [`with_hasher`], and [`with_capacity_and_hasher`] methods. -/// There are many alternative [hashing algorithms available on crates.io]. -/// -/// It is required that the keys implement the [`Eq`] and [`Hash`] traits, although -/// this can frequently be achieved by using `#[derive(PartialEq, Eq, Hash)]`. -/// If you implement these yourself, it is important that the following -/// property holds: -/// -/// ```text -/// k1 == k2 -> hash(k1) == hash(k2) -/// ``` -/// -/// In other words, if two keys are equal, their hashes must be equal. -/// Violating this property is a logic error. -/// -/// It is also a logic error for a key to be modified in such a way that the key's -/// hash, as determined by the [`Hash`] trait, or its equality, as determined by -/// the [`Eq`] trait, changes while it is in the map. This is normally only -/// possible through [`Cell`], [`RefCell`], global state, I/O, or unsafe code. -/// -/// The behavior resulting from either logic error is not specified, but will -/// be encapsulated to the `HashMap` that observed the logic error and not -/// result in undefined behavior. This could include panics, incorrect results, -/// aborts, memory leaks, and non-termination. -/// -/// The hash table implementation is a Rust port of Google's [SwissTable]. -/// The original C++ version of SwissTable can be found [here], and this -/// [CppCon talk] gives an overview of how the algorithm works. -/// -/// [hash map]: crate::collections#use-a-hashmap-when -/// [hashing algorithms available on crates.io]: https://crates.io/keywords/hasher -/// [SwissTable]: https://abseil.io/blog/20180927-swisstables -/// [here]: https://github.com/abseil/abseil-cpp/blob/master/absl/container/internal/raw_hash_set.h -/// [CppCon talk]: https://www.youtube.com/watch?v=ncHmEUmJZf4 -/// -/// # Examples -/// -/// ``` -/// use std::collections::HashMap; -/// -/// // Type inference lets us omit an explicit type signature (which -/// // would be `HashMap` in this example). -/// let mut book_reviews = HashMap::new(); -/// -/// // Review some books. -/// book_reviews.insert( -/// "Adventures of Huckleberry Finn".to_string(), -/// "My favorite book.".to_string(), -/// ); -/// book_reviews.insert( -/// "Grimms' Fairy Tales".to_string(), -/// "Masterpiece.".to_string(), -/// ); -/// book_reviews.insert( -/// "Pride and Prejudice".to_string(), -/// "Very enjoyable.".to_string(), -/// ); -/// book_reviews.insert( -/// "The Adventures of Sherlock Holmes".to_string(), -/// "Eye lyked it alot.".to_string(), -/// ); -/// -/// // Check for a specific one. -/// // When collections store owned values (String), they can still be -/// // queried using references (&str). -/// if !book_reviews.contains_key("Les Misérables") { -/// println!("We've got {} reviews, but Les Misérables ain't one.", -/// book_reviews.len()); -/// } -/// -/// // oops, this review has a lot of spelling mistakes, let's delete it. -/// book_reviews.remove("The Adventures of Sherlock Holmes"); -/// -/// // Look up the values associated with some keys. -/// let to_find = ["Pride and Prejudice", "Alice's Adventure in Wonderland"]; -/// for &book in &to_find { -/// match book_reviews.get(book) { -/// Some(review) => println!("{book}: {review}"), -/// None => println!("{book} is unreviewed.") -/// } -/// } -/// -/// // Look up the value for a key (will panic if the key is not found). -/// println!("Review for Jane: {}", book_reviews["Pride and Prejudice"]); -/// -/// // Iterate over everything. -/// for (book, review) in &book_reviews { -/// println!("{book}: \"{review}\""); -/// } -/// ``` -/// -/// A `HashMap` with a known list of items can be initialized from an array: -/// -/// ``` -/// use std::collections::HashMap; -/// -/// let solar_distance = HashMap::from([ -/// ("Mercury", 0.4), -/// ("Venus", 0.7), -/// ("Earth", 1.0), -/// ("Mars", 1.5), -/// ]); -/// ``` -/// -/// `HashMap` implements an [`Entry` API](#method.entry), which allows -/// for complex methods of getting, setting, updating and removing keys and -/// their values: -/// -/// ``` -/// use std::collections::HashMap; -/// -/// // type inference lets us omit an explicit type signature (which -/// // would be `HashMap<&str, u8>` in this example). -/// let mut player_stats = HashMap::new(); -/// -/// fn random_stat_buff() -> u8 { -/// // could actually return some random value here - let's just return -/// // some fixed value for now -/// 42 -/// } -/// -/// // insert a key only if it doesn't already exist -/// player_stats.entry("health").or_insert(100); -/// -/// // insert a key using a function that provides a new value only if it -/// // doesn't already exist -/// player_stats.entry("defence").or_insert_with(random_stat_buff); -/// -/// // update a key, guarding against the key possibly not being set -/// let stat = player_stats.entry("attack").or_insert(100); -/// *stat += random_stat_buff(); -/// -/// // modify an entry before an insert with in-place mutation -/// player_stats.entry("mana").and_modify(|mana| *mana += 200).or_insert(100); -/// ``` -/// -/// The easiest way to use `HashMap` with a custom key type is to derive [`Eq`] and [`Hash`]. -/// We must also derive [`PartialEq`]. -/// -/// [`RefCell`]: crate::cell::RefCell -/// [`Cell`]: crate::cell::Cell -/// [`default`]: Default::default -/// [`with_hasher`]: Self::with_hasher -/// [`with_capacity_and_hasher`]: Self::with_capacity_and_hasher -/// -/// ``` -/// use std::collections::HashMap; -/// -/// #[derive(Hash, Eq, PartialEq, Debug)] -/// struct Viking { -/// name: String, -/// country: String, -/// } -/// -/// impl Viking { -/// /// Creates a new Viking. -/// fn new(name: &str, country: &str) -> Viking { -/// Viking { name: name.to_string(), country: country.to_string() } -/// } -/// } -/// -/// // Use a HashMap to store the vikings' health points. -/// let vikings = HashMap::from([ -/// (Viking::new("Einar", "Norway"), 25), -/// (Viking::new("Olaf", "Denmark"), 24), -/// (Viking::new("Harald", "Iceland"), 12), -/// ]); -/// -/// // Use derived implementation to print the status of the vikings. -/// for (viking, health) in &vikings { -/// println!("{viking:?} has {health} hp"); -/// } -/// ``` - -#[cfg_attr(not(test), rustc_diagnostic_item = "HashMap")] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_insignificant_dtor] -pub struct HashMap { - base: base::HashMap, -} - -impl HashMap { - /// Creates an empty `HashMap`. - /// - /// The hash map is initially created with a capacity of 0, so it will not allocate until it - /// is first inserted into. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// let mut map: HashMap<&str, i32> = HashMap::new(); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn new() -> HashMap { - Default::default() - } - - /// Creates an empty `HashMap` with at least the specified capacity. - /// - /// The hash map will be able to hold at least `capacity` elements without - /// reallocating. This method is allowed to allocate for more elements than - /// `capacity`. If `capacity` is 0, the hash map will not allocate. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// let mut map: HashMap<&str, i32> = HashMap::with_capacity(10); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn with_capacity(capacity: usize) -> HashMap { - HashMap::with_capacity_and_hasher(capacity, Default::default()) - } -} - -impl HashMap { - /// Creates an empty `HashMap` which will use the given hash builder to hash - /// keys. - /// - /// The created map has the default initial capacity. - /// - /// Warning: `hash_builder` is normally randomly generated, and - /// is designed to allow HashMaps to be resistant to attacks that - /// cause many collisions and very poor performance. Setting it - /// manually using this function can expose a DoS attack vector. - /// - /// The `hash_builder` passed should implement the [`BuildHasher`] trait for - /// the HashMap to be useful, see its documentation for details. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// use std::hash::RandomState; - /// - /// let s = RandomState::new(); - /// let mut map = HashMap::with_hasher(s); - /// map.insert(1, 2); - /// ``` - #[inline] - #[stable(feature = "hashmap_build_hasher", since = "1.7.0")] - #[rustc_const_unstable(feature = "const_collections_with_hasher", issue = "102575")] - pub const fn with_hasher(hash_builder: S) -> HashMap { - HashMap { base: base::HashMap::with_hasher(hash_builder) } - } - - /// Creates an empty `HashMap` with at least the specified capacity, using - /// `hasher` to hash the keys. - /// - /// The hash map will be able to hold at least `capacity` elements without - /// reallocating. This method is allowed to allocate for more elements than - /// `capacity`. If `capacity` is 0, the hash map will not allocate. - /// - /// Warning: `hasher` is normally randomly generated, and - /// is designed to allow HashMaps to be resistant to attacks that - /// cause many collisions and very poor performance. Setting it - /// manually using this function can expose a DoS attack vector. - /// - /// The `hasher` passed should implement the [`BuildHasher`] trait for - /// the HashMap to be useful, see its documentation for details. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// use std::hash::RandomState; - /// - /// let s = RandomState::new(); - /// let mut map = HashMap::with_capacity_and_hasher(10, s); - /// map.insert(1, 2); - /// ``` - #[inline] - #[stable(feature = "hashmap_build_hasher", since = "1.7.0")] - pub fn with_capacity_and_hasher(capacity: usize, hasher: S) -> HashMap { - HashMap { base: base::HashMap::with_capacity_and_hasher(capacity, hasher) } - } - - /// Returns the number of elements the map can hold without reallocating. - /// - /// This number is a lower bound; the `HashMap` might be able to hold - /// more, but is guaranteed to be able to hold at least this many. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// let map: HashMap = HashMap::with_capacity(100); - /// assert!(map.capacity() >= 100); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn capacity(&self) -> usize { - self.base.capacity() - } - - /// An iterator visiting all keys in arbitrary order. - /// The iterator element type is `&'a K`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let map = HashMap::from([ - /// ("a", 1), - /// ("b", 2), - /// ("c", 3), - /// ]); - /// - /// for key in map.keys() { - /// println!("{key}"); - /// } - /// ``` - /// - /// # Performance - /// - /// In the current implementation, iterating over keys takes O(capacity) time - /// instead of O(len) because it internally visits empty buckets too. - #[rustc_lint_query_instability] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn keys(&self) -> Keys<'_, K, V> { - Keys { inner: self.iter() } - } - - /// Creates a consuming iterator visiting all the keys in arbitrary order. - /// The map cannot be used after calling this. - /// The iterator element type is `K`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let map = HashMap::from([ - /// ("a", 1), - /// ("b", 2), - /// ("c", 3), - /// ]); - /// - /// let mut vec: Vec<&str> = map.into_keys().collect(); - /// // The `IntoKeys` iterator produces keys in arbitrary order, so the - /// // keys must be sorted to test them against a sorted array. - /// vec.sort_unstable(); - /// assert_eq!(vec, ["a", "b", "c"]); - /// ``` - /// - /// # Performance - /// - /// In the current implementation, iterating over keys takes O(capacity) time - /// instead of O(len) because it internally visits empty buckets too. - #[inline] - #[rustc_lint_query_instability] - #[stable(feature = "map_into_keys_values", since = "1.54.0")] - pub fn into_keys(self) -> IntoKeys { - IntoKeys { inner: self.into_iter() } - } - - /// An iterator visiting all values in arbitrary order. - /// The iterator element type is `&'a V`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let map = HashMap::from([ - /// ("a", 1), - /// ("b", 2), - /// ("c", 3), - /// ]); - /// - /// for val in map.values() { - /// println!("{val}"); - /// } - /// ``` - /// - /// # Performance - /// - /// In the current implementation, iterating over values takes O(capacity) time - /// instead of O(len) because it internally visits empty buckets too. - #[rustc_lint_query_instability] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn values(&self) -> Values<'_, K, V> { - Values { inner: self.iter() } - } - - /// An iterator visiting all values mutably in arbitrary order. - /// The iterator element type is `&'a mut V`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut map = HashMap::from([ - /// ("a", 1), - /// ("b", 2), - /// ("c", 3), - /// ]); - /// - /// for val in map.values_mut() { - /// *val = *val + 10; - /// } - /// - /// for val in map.values() { - /// println!("{val}"); - /// } - /// ``` - /// - /// # Performance - /// - /// In the current implementation, iterating over values takes O(capacity) time - /// instead of O(len) because it internally visits empty buckets too. - #[rustc_lint_query_instability] - #[stable(feature = "map_values_mut", since = "1.10.0")] - pub fn values_mut(&mut self) -> ValuesMut<'_, K, V> { - ValuesMut { inner: self.iter_mut() } - } - - /// Creates a consuming iterator visiting all the values in arbitrary order. - /// The map cannot be used after calling this. - /// The iterator element type is `V`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let map = HashMap::from([ - /// ("a", 1), - /// ("b", 2), - /// ("c", 3), - /// ]); - /// - /// let mut vec: Vec = map.into_values().collect(); - /// // The `IntoValues` iterator produces values in arbitrary order, so - /// // the values must be sorted to test them against a sorted array. - /// vec.sort_unstable(); - /// assert_eq!(vec, [1, 2, 3]); - /// ``` - /// - /// # Performance - /// - /// In the current implementation, iterating over values takes O(capacity) time - /// instead of O(len) because it internally visits empty buckets too. - #[inline] - #[rustc_lint_query_instability] - #[stable(feature = "map_into_keys_values", since = "1.54.0")] - pub fn into_values(self) -> IntoValues { - IntoValues { inner: self.into_iter() } - } - - /// An iterator visiting all key-value pairs in arbitrary order. - /// The iterator element type is `(&'a K, &'a V)`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let map = HashMap::from([ - /// ("a", 1), - /// ("b", 2), - /// ("c", 3), - /// ]); - /// - /// for (key, val) in map.iter() { - /// println!("key: {key} val: {val}"); - /// } - /// ``` - /// - /// # Performance - /// - /// In the current implementation, iterating over map takes O(capacity) time - /// instead of O(len) because it internally visits empty buckets too. - #[rustc_lint_query_instability] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn iter(&self) -> Iter<'_, K, V> { - Iter { base: self.base.iter() } - } - - /// An iterator visiting all key-value pairs in arbitrary order, - /// with mutable references to the values. - /// The iterator element type is `(&'a K, &'a mut V)`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut map = HashMap::from([ - /// ("a", 1), - /// ("b", 2), - /// ("c", 3), - /// ]); - /// - /// // Update all values - /// for (_, val) in map.iter_mut() { - /// *val *= 2; - /// } - /// - /// for (key, val) in &map { - /// println!("key: {key} val: {val}"); - /// } - /// ``` - /// - /// # Performance - /// - /// In the current implementation, iterating over map takes O(capacity) time - /// instead of O(len) because it internally visits empty buckets too. - #[rustc_lint_query_instability] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn iter_mut(&mut self) -> IterMut<'_, K, V> { - IterMut { base: self.base.iter_mut() } - } - - /// Returns the number of elements in the map. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut a = HashMap::new(); - /// assert_eq!(a.len(), 0); - /// a.insert(1, "a"); - /// assert_eq!(a.len(), 1); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn len(&self) -> usize { - self.base.len() - } - - /// Returns `true` if the map contains no elements. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut a = HashMap::new(); - /// assert!(a.is_empty()); - /// a.insert(1, "a"); - /// assert!(!a.is_empty()); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn is_empty(&self) -> bool { - self.base.is_empty() - } - - /// Clears the map, returning all key-value pairs as an iterator. Keeps the - /// allocated memory for reuse. - /// - /// If the returned iterator is dropped before being fully consumed, it - /// drops the remaining key-value pairs. The returned iterator keeps a - /// mutable borrow on the map to optimize its implementation. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut a = HashMap::new(); - /// a.insert(1, "a"); - /// a.insert(2, "b"); - /// - /// for (k, v) in a.drain().take(1) { - /// assert!(k == 1 || k == 2); - /// assert!(v == "a" || v == "b"); - /// } - /// - /// assert!(a.is_empty()); - /// ``` - #[inline] - #[rustc_lint_query_instability] - #[stable(feature = "drain", since = "1.6.0")] - pub fn drain(&mut self) -> Drain<'_, K, V> { - Drain { base: self.base.drain() } - } - - /// Creates an iterator which uses a closure to determine if an element should be removed. - /// - /// If the closure returns true, the element is removed from the map and yielded. - /// If the closure returns false, or panics, the element remains in the map and will not be - /// yielded. - /// - /// Note that `extract_if` lets you mutate every value in the filter closure, regardless of - /// whether you choose to keep or remove it. - /// - /// If the returned `ExtractIf` is not exhausted, e.g. because it is dropped without iterating - /// or the iteration short-circuits, then the remaining elements will be retained. - /// Use [`retain`] with a negated predicate if you do not need the returned iterator. - /// - /// [`retain`]: HashMap::retain - /// - /// # Examples - /// - /// Splitting a map into even and odd keys, reusing the original map: - /// - /// ``` - /// #![feature(hash_extract_if)] - /// use std::collections::HashMap; - /// - /// let mut map: HashMap = (0..8).map(|x| (x, x)).collect(); - /// let extracted: HashMap = map.extract_if(|k, _v| k % 2 == 0).collect(); - /// - /// let mut evens = extracted.keys().copied().collect::>(); - /// let mut odds = map.keys().copied().collect::>(); - /// evens.sort(); - /// odds.sort(); - /// - /// assert_eq!(evens, vec![0, 2, 4, 6]); - /// assert_eq!(odds, vec![1, 3, 5, 7]); - /// ``` - #[inline] - #[rustc_lint_query_instability] - #[unstable(feature = "hash_extract_if", issue = "59618")] - pub fn extract_if(&mut self, pred: F) -> ExtractIf<'_, K, V, F> - where - F: FnMut(&K, &mut V) -> bool, - { - ExtractIf { base: self.base.extract_if(pred) } - } - - /// Retains only the elements specified by the predicate. - /// - /// In other words, remove all pairs `(k, v)` for which `f(&k, &mut v)` returns `false`. - /// The elements are visited in unsorted (and unspecified) order. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut map: HashMap = (0..8).map(|x| (x, x*10)).collect(); - /// map.retain(|&k, _| k % 2 == 0); - /// assert_eq!(map.len(), 4); - /// ``` - /// - /// # Performance - /// - /// In the current implementation, this operation takes O(capacity) time - /// instead of O(len) because it internally visits empty buckets too. - #[inline] - #[rustc_lint_query_instability] - #[stable(feature = "retain_hash_collection", since = "1.18.0")] - pub fn retain(&mut self, f: F) - where - F: FnMut(&K, &mut V) -> bool, - { - self.base.retain(f) - } - - /// Clears the map, removing all key-value pairs. Keeps the allocated memory - /// for reuse. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut a = HashMap::new(); - /// a.insert(1, "a"); - /// a.clear(); - /// assert!(a.is_empty()); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn clear(&mut self) { - self.base.clear(); - } - - /// Returns a reference to the map's [`BuildHasher`]. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// use std::hash::RandomState; - /// - /// let hasher = RandomState::new(); - /// let map: HashMap = HashMap::with_hasher(hasher); - /// let hasher: &RandomState = map.hasher(); - /// ``` - #[inline] - #[stable(feature = "hashmap_public_hasher", since = "1.9.0")] - pub fn hasher(&self) -> &S { - self.base.hasher() - } -} - -impl HashMap -where - K: Eq + Hash, - S: BuildHasher, -{ - /// Reserves capacity for at least `additional` more elements to be inserted - /// in the `HashMap`. The collection may reserve more space to speculatively - /// avoid frequent reallocations. After calling `reserve`, - /// capacity will be greater than or equal to `self.len() + additional`. - /// Does nothing if capacity is already sufficient. - /// - /// # Panics - /// - /// Panics if the new allocation size overflows [`usize`]. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// let mut map: HashMap<&str, i32> = HashMap::new(); - /// map.reserve(10); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn reserve(&mut self, additional: usize) { - self.base.reserve(additional) - } - - /// Tries to reserve capacity for at least `additional` more elements to be inserted - /// in the `HashMap`. The collection may reserve more space to speculatively - /// avoid frequent reallocations. After calling `try_reserve`, - /// capacity will be greater than or equal to `self.len() + additional` if - /// it returns `Ok(())`. - /// Does nothing if capacity is already sufficient. - /// - /// # Errors - /// - /// If the capacity overflows, or the allocator reports a failure, then an error - /// is returned. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut map: HashMap<&str, isize> = HashMap::new(); - /// map.try_reserve(10).expect("why is the test harness OOMing on a handful of bytes?"); - /// ``` - #[inline] - #[stable(feature = "try_reserve", since = "1.57.0")] - pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> { - self.base.try_reserve(additional).map_err(map_try_reserve_error) - } - - /// Shrinks the capacity of the map as much as possible. It will drop - /// down as much as possible while maintaining the internal rules - /// and possibly leaving some space in accordance with the resize policy. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut map: HashMap = HashMap::with_capacity(100); - /// map.insert(1, 2); - /// map.insert(3, 4); - /// assert!(map.capacity() >= 100); - /// map.shrink_to_fit(); - /// assert!(map.capacity() >= 2); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn shrink_to_fit(&mut self) { - self.base.shrink_to_fit(); - } - - /// Shrinks the capacity of the map with a lower limit. It will drop - /// down no lower than the supplied limit while maintaining the internal rules - /// and possibly leaving some space in accordance with the resize policy. - /// - /// If the current capacity is less than the lower limit, this is a no-op. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut map: HashMap = HashMap::with_capacity(100); - /// map.insert(1, 2); - /// map.insert(3, 4); - /// assert!(map.capacity() >= 100); - /// map.shrink_to(10); - /// assert!(map.capacity() >= 10); - /// map.shrink_to(0); - /// assert!(map.capacity() >= 2); - /// ``` - #[inline] - #[stable(feature = "shrink_to", since = "1.56.0")] - pub fn shrink_to(&mut self, min_capacity: usize) { - self.base.shrink_to(min_capacity); - } - - /// Gets the given key's corresponding entry in the map for in-place manipulation. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut letters = HashMap::new(); - /// - /// for ch in "a short treatise on fungi".chars() { - /// letters.entry(ch).and_modify(|counter| *counter += 1).or_insert(1); - /// } - /// - /// assert_eq!(letters[&'s'], 2); - /// assert_eq!(letters[&'t'], 3); - /// assert_eq!(letters[&'u'], 1); - /// assert_eq!(letters.get(&'y'), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn entry(&mut self, key: K) -> Entry<'_, K, V> { - map_entry(self.base.rustc_entry(key)) - } - - /// Returns a reference to the value corresponding to the key. - /// - /// The key may be any borrowed form of the map's key type, but - /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for - /// the key type. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut map = HashMap::new(); - /// map.insert(1, "a"); - /// assert_eq!(map.get(&1), Some(&"a")); - /// assert_eq!(map.get(&2), None); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn get(&self, k: &Q) -> Option<&V> - where - K: Borrow, - Q: Hash + Eq, - { - self.base.get(k) - } - - /// Returns the key-value pair corresponding to the supplied key. - /// - /// The supplied key may be any borrowed form of the map's key type, but - /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for - /// the key type. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut map = HashMap::new(); - /// map.insert(1, "a"); - /// assert_eq!(map.get_key_value(&1), Some((&1, &"a"))); - /// assert_eq!(map.get_key_value(&2), None); - /// ``` - #[inline] - #[stable(feature = "map_get_key_value", since = "1.40.0")] - pub fn get_key_value(&self, k: &Q) -> Option<(&K, &V)> - where - K: Borrow, - Q: Hash + Eq, - { - self.base.get_key_value(k) - } - - /// Attempts to get mutable references to `N` values in the map at once. - /// - /// Returns an array of length `N` with the results of each query. For soundness, at most one - /// mutable reference will be returned to any value. `None` will be returned if any of the - /// keys are duplicates or missing. - /// - /// # Examples - /// - /// ``` - /// #![feature(map_many_mut)] - /// use std::collections::HashMap; - /// - /// let mut libraries = HashMap::new(); - /// libraries.insert("Bodleian Library".to_string(), 1602); - /// libraries.insert("Athenæum".to_string(), 1807); - /// libraries.insert("Herzogin-Anna-Amalia-Bibliothek".to_string(), 1691); - /// libraries.insert("Library of Congress".to_string(), 1800); - /// - /// let got = libraries.get_many_mut([ - /// "Athenæum", - /// "Library of Congress", - /// ]); - /// assert_eq!( - /// got, - /// Some([ - /// &mut 1807, - /// &mut 1800, - /// ]), - /// ); - /// - /// // Missing keys result in None - /// let got = libraries.get_many_mut([ - /// "Athenæum", - /// "New York Public Library", - /// ]); - /// assert_eq!(got, None); - /// - /// // Duplicate keys result in None - /// let got = libraries.get_many_mut([ - /// "Athenæum", - /// "Athenæum", - /// ]); - /// assert_eq!(got, None); - /// ``` - #[inline] - #[unstable(feature = "map_many_mut", issue = "97601")] - pub fn get_many_mut(&mut self, ks: [&Q; N]) -> Option<[&'_ mut V; N]> - where - K: Borrow, - Q: Hash + Eq, - { - self.base.get_many_mut(ks) - } - - /// Attempts to get mutable references to `N` values in the map at once, without validating that - /// the values are unique. - /// - /// Returns an array of length `N` with the results of each query. `None` will be returned if - /// any of the keys are missing. - /// - /// For a safe alternative see [`get_many_mut`](Self::get_many_mut). - /// - /// # Safety - /// - /// Calling this method with overlapping keys is *[undefined behavior]* even if the resulting - /// references are not used. - /// - /// [undefined behavior]: https://doc.rust-lang.org/reference/behavior-considered-undefined.html - /// - /// # Examples - /// - /// ``` - /// #![feature(map_many_mut)] - /// use std::collections::HashMap; - /// - /// let mut libraries = HashMap::new(); - /// libraries.insert("Bodleian Library".to_string(), 1602); - /// libraries.insert("Athenæum".to_string(), 1807); - /// libraries.insert("Herzogin-Anna-Amalia-Bibliothek".to_string(), 1691); - /// libraries.insert("Library of Congress".to_string(), 1800); - /// - /// let got = libraries.get_many_mut([ - /// "Athenæum", - /// "Library of Congress", - /// ]); - /// assert_eq!( - /// got, - /// Some([ - /// &mut 1807, - /// &mut 1800, - /// ]), - /// ); - /// - /// // Missing keys result in None - /// let got = libraries.get_many_mut([ - /// "Athenæum", - /// "New York Public Library", - /// ]); - /// assert_eq!(got, None); - /// ``` - #[inline] - #[unstable(feature = "map_many_mut", issue = "97601")] - pub unsafe fn get_many_unchecked_mut( - &mut self, - ks: [&Q; N], - ) -> Option<[&'_ mut V; N]> - where - K: Borrow, - Q: Hash + Eq, - { - self.base.get_many_unchecked_mut(ks) - } - - /// Returns `true` if the map contains a value for the specified key. - /// - /// The key may be any borrowed form of the map's key type, but - /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for - /// the key type. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut map = HashMap::new(); - /// map.insert(1, "a"); - /// assert_eq!(map.contains_key(&1), true); - /// assert_eq!(map.contains_key(&2), false); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn contains_key(&self, k: &Q) -> bool - where - K: Borrow, - Q: Hash + Eq, - { - self.base.contains_key(k) - } - - /// Returns a mutable reference to the value corresponding to the key. - /// - /// The key may be any borrowed form of the map's key type, but - /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for - /// the key type. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut map = HashMap::new(); - /// map.insert(1, "a"); - /// if let Some(x) = map.get_mut(&1) { - /// *x = "b"; - /// } - /// assert_eq!(map[&1], "b"); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn get_mut(&mut self, k: &Q) -> Option<&mut V> - where - K: Borrow, - Q: Hash + Eq, - { - self.base.get_mut(k) - } - - /// Inserts a key-value pair into the map. - /// - /// If the map did not have this key present, [`None`] is returned. - /// - /// If the map did have this key present, the value is updated, and the old - /// value is returned. The key is not updated, though; this matters for - /// types that can be `==` without being identical. See the [module-level - /// documentation] for more. - /// - /// [module-level documentation]: crate::collections#insert-and-complex-keys - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut map = HashMap::new(); - /// assert_eq!(map.insert(37, "a"), None); - /// assert_eq!(map.is_empty(), false); - /// - /// map.insert(37, "b"); - /// assert_eq!(map.insert(37, "c"), Some("b")); - /// assert_eq!(map[&37], "c"); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("push", "append", "put")] - pub fn insert(&mut self, k: K, v: V) -> Option { - self.base.insert(k, v) - } - - /// Tries to insert a key-value pair into the map, and returns - /// a mutable reference to the value in the entry. - /// - /// If the map already had this key present, nothing is updated, and - /// an error containing the occupied entry and the value is returned. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(map_try_insert)] - /// - /// use std::collections::HashMap; - /// - /// let mut map = HashMap::new(); - /// assert_eq!(map.try_insert(37, "a").unwrap(), &"a"); - /// - /// let err = map.try_insert(37, "b").unwrap_err(); - /// assert_eq!(err.entry.key(), &37); - /// assert_eq!(err.entry.get(), &"a"); - /// assert_eq!(err.value, "b"); - /// ``` - #[unstable(feature = "map_try_insert", issue = "82766")] - pub fn try_insert(&mut self, key: K, value: V) -> Result<&mut V, OccupiedError<'_, K, V>> { - match self.entry(key) { - Occupied(entry) => Err(OccupiedError { entry, value }), - Vacant(entry) => Ok(entry.insert(value)), - } - } - - /// Removes a key from the map, returning the value at the key if the key - /// was previously in the map. - /// - /// The key may be any borrowed form of the map's key type, but - /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for - /// the key type. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut map = HashMap::new(); - /// map.insert(1, "a"); - /// assert_eq!(map.remove(&1), Some("a")); - /// assert_eq!(map.remove(&1), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("delete", "take")] - pub fn remove(&mut self, k: &Q) -> Option - where - K: Borrow, - Q: Hash + Eq, - { - self.base.remove(k) - } - - /// Removes a key from the map, returning the stored key and value if the - /// key was previously in the map. - /// - /// The key may be any borrowed form of the map's key type, but - /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for - /// the key type. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// # fn main() { - /// let mut map = HashMap::new(); - /// map.insert(1, "a"); - /// assert_eq!(map.remove_entry(&1), Some((1, "a"))); - /// assert_eq!(map.remove(&1), None); - /// # } - /// ``` - #[inline] - #[stable(feature = "hash_map_remove_entry", since = "1.27.0")] - pub fn remove_entry(&mut self, k: &Q) -> Option<(K, V)> - where - K: Borrow, - Q: Hash + Eq, - { - self.base.remove_entry(k) - } -} - -impl HashMap -where - S: BuildHasher, -{ - /// Creates a raw entry builder for the HashMap. - /// - /// Raw entries provide the lowest level of control for searching and - /// manipulating a map. They must be manually initialized with a hash and - /// then manually searched. After this, insertions into a vacant entry - /// still require an owned key to be provided. - /// - /// Raw entries are useful for such exotic situations as: - /// - /// * Hash memoization - /// * Deferring the creation of an owned key until it is known to be required - /// * Using a search key that doesn't work with the Borrow trait - /// * Using custom comparison logic without newtype wrappers - /// - /// Because raw entries provide much more low-level control, it's much easier - /// to put the HashMap into an inconsistent state which, while memory-safe, - /// will cause the map to produce seemingly random results. Higher-level and - /// more foolproof APIs like `entry` should be preferred when possible. - /// - /// In particular, the hash used to initialized the raw entry must still be - /// consistent with the hash of the key that is ultimately stored in the entry. - /// This is because implementations of HashMap may need to recompute hashes - /// when resizing, at which point only the keys are available. - /// - /// Raw entries give mutable access to the keys. This must not be used - /// to modify how the key would compare or hash, as the map will not re-evaluate - /// where the key should go, meaning the keys may become "lost" if their - /// location does not reflect their state. For instance, if you change a key - /// so that the map now contains keys which compare equal, search may start - /// acting erratically, with two keys randomly masking each other. Implementations - /// are free to assume this doesn't happen (within the limits of memory-safety). - #[inline] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn raw_entry_mut(&mut self) -> RawEntryBuilderMut<'_, K, V, S> { - RawEntryBuilderMut { map: self } - } - - /// Creates a raw immutable entry builder for the HashMap. - /// - /// Raw entries provide the lowest level of control for searching and - /// manipulating a map. They must be manually initialized with a hash and - /// then manually searched. - /// - /// This is useful for - /// * Hash memoization - /// * Using a search key that doesn't work with the Borrow trait - /// * Using custom comparison logic without newtype wrappers - /// - /// Unless you are in such a situation, higher-level and more foolproof APIs like - /// `get` should be preferred. - /// - /// Immutable raw entries have very limited use; you might instead want `raw_entry_mut`. - #[inline] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn raw_entry(&self) -> RawEntryBuilder<'_, K, V, S> { - RawEntryBuilder { map: self } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for HashMap -where - K: Clone, - V: Clone, - S: Clone, -{ - #[inline] - fn clone(&self) -> Self { - Self { base: self.base.clone() } - } - - #[inline] - fn clone_from(&mut self, source: &Self) { - self.base.clone_from(&source.base); - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for HashMap -where - K: Eq + Hash, - V: PartialEq, - S: BuildHasher, -{ - fn eq(&self, other: &HashMap) -> bool { - if self.len() != other.len() { - return false; - } - - self.iter().all(|(key, value)| other.get(key).map_or(false, |v| *value == *v)) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Eq for HashMap -where - K: Eq + Hash, - V: Eq, - S: BuildHasher, -{ -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Debug for HashMap -where - K: Debug, - V: Debug, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_map().entries(self.iter()).finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Default for HashMap -where - S: Default, -{ - /// Creates an empty `HashMap`, with the `Default` value for the hasher. - #[inline] - fn default() -> HashMap { - HashMap::with_hasher(Default::default()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Index<&Q> for HashMap -where - K: Eq + Hash + Borrow, - Q: Eq + Hash, - S: BuildHasher, -{ - type Output = V; - - /// Returns a reference to the value corresponding to the supplied key. - /// - /// # Panics - /// - /// Panics if the key is not present in the `HashMap`. - #[inline] - fn index(&self, key: &Q) -> &V { - self.get(key).expect("no entry found for key") - } -} - -#[stable(feature = "std_collections_from_array", since = "1.56.0")] -// Note: as what is currently the most convenient built-in way to construct -// a HashMap, a simple usage of this function must not *require* the user -// to provide a type annotation in order to infer the third type parameter -// (the hasher parameter, conventionally "S"). -// To that end, this impl is defined using RandomState as the concrete -// type of S, rather than being generic over `S: BuildHasher + Default`. -// It is expected that users who want to specify a hasher will manually use -// `with_capacity_and_hasher`. -// If type parameter defaults worked on impls, and if type parameter -// defaults could be mixed with const generics, then perhaps -// this could be generalized. -// See also the equivalent impl on HashSet. -impl From<[(K, V); N]> for HashMap -where - K: Eq + Hash, -{ - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let map1 = HashMap::from([(1, 2), (3, 4)]); - /// let map2: HashMap<_, _> = [(1, 2), (3, 4)].into(); - /// assert_eq!(map1, map2); - /// ``` - fn from(arr: [(K, V); N]) -> Self { - Self::from_iter(arr) - } -} - -/// An iterator over the entries of a `HashMap`. -/// -/// This `struct` is created by the [`iter`] method on [`HashMap`]. See its -/// documentation for more. -/// -/// [`iter`]: HashMap::iter -/// -/// # Example -/// -/// ``` -/// use std::collections::HashMap; -/// -/// let map = HashMap::from([ -/// ("a", 1), -/// ]); -/// let iter = map.iter(); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Iter<'a, K: 'a, V: 'a> { - base: base::Iter<'a, K, V>, -} - -// FIXME(#26925) Remove in favor of `#[derive(Clone)]` -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Iter<'_, K, V> { - #[inline] - fn clone(&self) -> Self { - Iter { base: self.base.clone() } - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for Iter<'_, K, V> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.clone()).finish() - } -} - -/// A mutable iterator over the entries of a `HashMap`. -/// -/// This `struct` is created by the [`iter_mut`] method on [`HashMap`]. See its -/// documentation for more. -/// -/// [`iter_mut`]: HashMap::iter_mut -/// -/// # Example -/// -/// ``` -/// use std::collections::HashMap; -/// -/// let mut map = HashMap::from([ -/// ("a", 1), -/// ]); -/// let iter = map.iter_mut(); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub struct IterMut<'a, K: 'a, V: 'a> { - base: base::IterMut<'a, K, V>, -} - -impl<'a, K, V> IterMut<'a, K, V> { - /// Returns an iterator of references over the remaining items. - #[inline] - pub(super) fn iter(&self) -> Iter<'_, K, V> { - Iter { base: self.base.rustc_iter() } - } -} - -/// An owning iterator over the entries of a `HashMap`. -/// -/// This `struct` is created by the [`into_iter`] method on [`HashMap`] -/// (provided by the [`IntoIterator`] trait). See its documentation for more. -/// -/// [`into_iter`]: IntoIterator::into_iter -/// -/// # Example -/// -/// ``` -/// use std::collections::HashMap; -/// -/// let map = HashMap::from([ -/// ("a", 1), -/// ]); -/// let iter = map.into_iter(); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub struct IntoIter { - base: base::IntoIter, -} - -impl IntoIter { - /// Returns an iterator of references over the remaining items. - #[inline] - pub(super) fn iter(&self) -> Iter<'_, K, V> { - Iter { base: self.base.rustc_iter() } - } -} - -/// An iterator over the keys of a `HashMap`. -/// -/// This `struct` is created by the [`keys`] method on [`HashMap`]. See its -/// documentation for more. -/// -/// [`keys`]: HashMap::keys -/// -/// # Example -/// -/// ``` -/// use std::collections::HashMap; -/// -/// let map = HashMap::from([ -/// ("a", 1), -/// ]); -/// let iter_keys = map.keys(); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Keys<'a, K: 'a, V: 'a> { - inner: Iter<'a, K, V>, -} - -// FIXME(#26925) Remove in favor of `#[derive(Clone)]` -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Keys<'_, K, V> { - #[inline] - fn clone(&self) -> Self { - Keys { inner: self.inner.clone() } - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for Keys<'_, K, V> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.clone()).finish() - } -} - -/// An iterator over the values of a `HashMap`. -/// -/// This `struct` is created by the [`values`] method on [`HashMap`]. See its -/// documentation for more. -/// -/// [`values`]: HashMap::values -/// -/// # Example -/// -/// ``` -/// use std::collections::HashMap; -/// -/// let map = HashMap::from([ -/// ("a", 1), -/// ]); -/// let iter_values = map.values(); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Values<'a, K: 'a, V: 'a> { - inner: Iter<'a, K, V>, -} - -// FIXME(#26925) Remove in favor of `#[derive(Clone)]` -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Values<'_, K, V> { - #[inline] - fn clone(&self) -> Self { - Values { inner: self.inner.clone() } - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for Values<'_, K, V> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.clone()).finish() - } -} - -/// A draining iterator over the entries of a `HashMap`. -/// -/// This `struct` is created by the [`drain`] method on [`HashMap`]. See its -/// documentation for more. -/// -/// [`drain`]: HashMap::drain -/// -/// # Example -/// -/// ``` -/// use std::collections::HashMap; -/// -/// let mut map = HashMap::from([ -/// ("a", 1), -/// ]); -/// let iter = map.drain(); -/// ``` -#[stable(feature = "drain", since = "1.6.0")] -pub struct Drain<'a, K: 'a, V: 'a> { - base: base::Drain<'a, K, V>, -} - -impl<'a, K, V> Drain<'a, K, V> { - /// Returns an iterator of references over the remaining items. - #[inline] - pub(super) fn iter(&self) -> Iter<'_, K, V> { - Iter { base: self.base.rustc_iter() } - } -} - -/// A draining, filtering iterator over the entries of a `HashMap`. -/// -/// This `struct` is created by the [`extract_if`] method on [`HashMap`]. -/// -/// [`extract_if`]: HashMap::extract_if -/// -/// # Example -/// -/// ``` -/// #![feature(hash_extract_if)] -/// -/// use std::collections::HashMap; -/// -/// let mut map = HashMap::from([ -/// ("a", 1), -/// ]); -/// let iter = map.extract_if(|_k, v| *v % 2 == 0); -/// ``` -#[unstable(feature = "hash_extract_if", issue = "59618")] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct ExtractIf<'a, K, V, F> -where - F: FnMut(&K, &mut V) -> bool, -{ - base: base::ExtractIf<'a, K, V, F>, -} - -/// A mutable iterator over the values of a `HashMap`. -/// -/// This `struct` is created by the [`values_mut`] method on [`HashMap`]. See its -/// documentation for more. -/// -/// [`values_mut`]: HashMap::values_mut -/// -/// # Example -/// -/// ``` -/// use std::collections::HashMap; -/// -/// let mut map = HashMap::from([ -/// ("a", 1), -/// ]); -/// let iter_values = map.values_mut(); -/// ``` -#[stable(feature = "map_values_mut", since = "1.10.0")] -pub struct ValuesMut<'a, K: 'a, V: 'a> { - inner: IterMut<'a, K, V>, -} - -/// An owning iterator over the keys of a `HashMap`. -/// -/// This `struct` is created by the [`into_keys`] method on [`HashMap`]. -/// See its documentation for more. -/// -/// [`into_keys`]: HashMap::into_keys -/// -/// # Example -/// -/// ``` -/// use std::collections::HashMap; -/// -/// let map = HashMap::from([ -/// ("a", 1), -/// ]); -/// let iter_keys = map.into_keys(); -/// ``` -#[stable(feature = "map_into_keys_values", since = "1.54.0")] -pub struct IntoKeys { - inner: IntoIter, -} - -/// An owning iterator over the values of a `HashMap`. -/// -/// This `struct` is created by the [`into_values`] method on [`HashMap`]. -/// See its documentation for more. -/// -/// [`into_values`]: HashMap::into_values -/// -/// # Example -/// -/// ``` -/// use std::collections::HashMap; -/// -/// let map = HashMap::from([ -/// ("a", 1), -/// ]); -/// let iter_keys = map.into_values(); -/// ``` -#[stable(feature = "map_into_keys_values", since = "1.54.0")] -pub struct IntoValues { - inner: IntoIter, -} - -/// A builder for computing where in a HashMap a key-value pair would be stored. -/// -/// See the [`HashMap::raw_entry_mut`] docs for usage examples. -#[unstable(feature = "hash_raw_entry", issue = "56167")] -pub struct RawEntryBuilderMut<'a, K: 'a, V: 'a, S: 'a> { - map: &'a mut HashMap, -} - -/// A view into a single entry in a map, which may either be vacant or occupied. -/// -/// This is a lower-level version of [`Entry`]. -/// -/// This `enum` is constructed through the [`raw_entry_mut`] method on [`HashMap`], -/// then calling one of the methods of that [`RawEntryBuilderMut`]. -/// -/// [`raw_entry_mut`]: HashMap::raw_entry_mut -#[unstable(feature = "hash_raw_entry", issue = "56167")] -pub enum RawEntryMut<'a, K: 'a, V: 'a, S: 'a> { - /// An occupied entry. - Occupied(RawOccupiedEntryMut<'a, K, V, S>), - /// A vacant entry. - Vacant(RawVacantEntryMut<'a, K, V, S>), -} - -/// A view into an occupied entry in a `HashMap`. -/// It is part of the [`RawEntryMut`] enum. -#[unstable(feature = "hash_raw_entry", issue = "56167")] -pub struct RawOccupiedEntryMut<'a, K: 'a, V: 'a, S: 'a> { - base: base::RawOccupiedEntryMut<'a, K, V, S>, -} - -/// A view into a vacant entry in a `HashMap`. -/// It is part of the [`RawEntryMut`] enum. -#[unstable(feature = "hash_raw_entry", issue = "56167")] -pub struct RawVacantEntryMut<'a, K: 'a, V: 'a, S: 'a> { - base: base::RawVacantEntryMut<'a, K, V, S>, -} - -/// A builder for computing where in a HashMap a key-value pair would be stored. -/// -/// See the [`HashMap::raw_entry`] docs for usage examples. -#[unstable(feature = "hash_raw_entry", issue = "56167")] -pub struct RawEntryBuilder<'a, K: 'a, V: 'a, S: 'a> { - map: &'a HashMap, -} - -impl<'a, K, V, S> RawEntryBuilderMut<'a, K, V, S> -where - S: BuildHasher, -{ - /// Creates a `RawEntryMut` from the given key. - #[inline] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn from_key(self, k: &Q) -> RawEntryMut<'a, K, V, S> - where - K: Borrow, - Q: Hash + Eq, - { - map_raw_entry(self.map.base.raw_entry_mut().from_key(k)) - } - - /// Creates a `RawEntryMut` from the given key and its hash. - #[inline] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn from_key_hashed_nocheck(self, hash: u64, k: &Q) -> RawEntryMut<'a, K, V, S> - where - K: Borrow, - Q: Eq, - { - map_raw_entry(self.map.base.raw_entry_mut().from_key_hashed_nocheck(hash, k)) - } - - /// Creates a `RawEntryMut` from the given hash. - #[inline] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn from_hash(self, hash: u64, is_match: F) -> RawEntryMut<'a, K, V, S> - where - for<'b> F: FnMut(&'b K) -> bool, - { - map_raw_entry(self.map.base.raw_entry_mut().from_hash(hash, is_match)) - } -} - -impl<'a, K, V, S> RawEntryBuilder<'a, K, V, S> -where - S: BuildHasher, -{ - /// Access an entry by key. - #[inline] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn from_key(self, k: &Q) -> Option<(&'a K, &'a V)> - where - K: Borrow, - Q: Hash + Eq, - { - self.map.base.raw_entry().from_key(k) - } - - /// Access an entry by a key and its hash. - #[inline] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn from_key_hashed_nocheck(self, hash: u64, k: &Q) -> Option<(&'a K, &'a V)> - where - K: Borrow, - Q: Hash + Eq, - { - self.map.base.raw_entry().from_key_hashed_nocheck(hash, k) - } - - /// Access an entry by hash. - #[inline] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn from_hash(self, hash: u64, is_match: F) -> Option<(&'a K, &'a V)> - where - F: FnMut(&K) -> bool, - { - self.map.base.raw_entry().from_hash(hash, is_match) - } -} - -impl<'a, K, V, S> RawEntryMut<'a, K, V, S> { - /// Ensures a value is in the entry by inserting the default if empty, and returns - /// mutable references to the key and value in the entry. - /// - /// # Examples - /// - /// ``` - /// #![feature(hash_raw_entry)] - /// use std::collections::HashMap; - /// - /// let mut map: HashMap<&str, u32> = HashMap::new(); - /// - /// map.raw_entry_mut().from_key("poneyland").or_insert("poneyland", 3); - /// assert_eq!(map["poneyland"], 3); - /// - /// *map.raw_entry_mut().from_key("poneyland").or_insert("poneyland", 10).1 *= 2; - /// assert_eq!(map["poneyland"], 6); - /// ``` - #[inline] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn or_insert(self, default_key: K, default_val: V) -> (&'a mut K, &'a mut V) - where - K: Hash, - S: BuildHasher, - { - match self { - RawEntryMut::Occupied(entry) => entry.into_key_value(), - RawEntryMut::Vacant(entry) => entry.insert(default_key, default_val), - } - } - - /// Ensures a value is in the entry by inserting the result of the default function if empty, - /// and returns mutable references to the key and value in the entry. - /// - /// # Examples - /// - /// ``` - /// #![feature(hash_raw_entry)] - /// use std::collections::HashMap; - /// - /// let mut map: HashMap<&str, String> = HashMap::new(); - /// - /// map.raw_entry_mut().from_key("poneyland").or_insert_with(|| { - /// ("poneyland", "hoho".to_string()) - /// }); - /// - /// assert_eq!(map["poneyland"], "hoho".to_string()); - /// ``` - #[inline] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn or_insert_with(self, default: F) -> (&'a mut K, &'a mut V) - where - F: FnOnce() -> (K, V), - K: Hash, - S: BuildHasher, - { - match self { - RawEntryMut::Occupied(entry) => entry.into_key_value(), - RawEntryMut::Vacant(entry) => { - let (k, v) = default(); - entry.insert(k, v) - } - } - } - - /// Provides in-place mutable access to an occupied entry before any - /// potential inserts into the map. - /// - /// # Examples - /// - /// ``` - /// #![feature(hash_raw_entry)] - /// use std::collections::HashMap; - /// - /// let mut map: HashMap<&str, u32> = HashMap::new(); - /// - /// map.raw_entry_mut() - /// .from_key("poneyland") - /// .and_modify(|_k, v| { *v += 1 }) - /// .or_insert("poneyland", 42); - /// assert_eq!(map["poneyland"], 42); - /// - /// map.raw_entry_mut() - /// .from_key("poneyland") - /// .and_modify(|_k, v| { *v += 1 }) - /// .or_insert("poneyland", 0); - /// assert_eq!(map["poneyland"], 43); - /// ``` - #[inline] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn and_modify(self, f: F) -> Self - where - F: FnOnce(&mut K, &mut V), - { - match self { - RawEntryMut::Occupied(mut entry) => { - { - let (k, v) = entry.get_key_value_mut(); - f(k, v); - } - RawEntryMut::Occupied(entry) - } - RawEntryMut::Vacant(entry) => RawEntryMut::Vacant(entry), - } - } -} - -impl<'a, K, V, S> RawOccupiedEntryMut<'a, K, V, S> { - /// Gets a reference to the key in the entry. - #[inline] - #[must_use] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn key(&self) -> &K { - self.base.key() - } - - /// Gets a mutable reference to the key in the entry. - #[inline] - #[must_use] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn key_mut(&mut self) -> &mut K { - self.base.key_mut() - } - - /// Converts the entry into a mutable reference to the key in the entry - /// with a lifetime bound to the map itself. - #[inline] - #[must_use = "`self` will be dropped if the result is not used"] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn into_key(self) -> &'a mut K { - self.base.into_key() - } - - /// Gets a reference to the value in the entry. - #[inline] - #[must_use] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn get(&self) -> &V { - self.base.get() - } - - /// Converts the `OccupiedEntry` into a mutable reference to the value in the entry - /// with a lifetime bound to the map itself. - #[inline] - #[must_use = "`self` will be dropped if the result is not used"] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn into_mut(self) -> &'a mut V { - self.base.into_mut() - } - - /// Gets a mutable reference to the value in the entry. - #[inline] - #[must_use] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn get_mut(&mut self) -> &mut V { - self.base.get_mut() - } - - /// Gets a reference to the key and value in the entry. - #[inline] - #[must_use] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn get_key_value(&mut self) -> (&K, &V) { - self.base.get_key_value() - } - - /// Gets a mutable reference to the key and value in the entry. - #[inline] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn get_key_value_mut(&mut self) -> (&mut K, &mut V) { - self.base.get_key_value_mut() - } - - /// Converts the `OccupiedEntry` into a mutable reference to the key and value in the entry - /// with a lifetime bound to the map itself. - #[inline] - #[must_use = "`self` will be dropped if the result is not used"] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn into_key_value(self) -> (&'a mut K, &'a mut V) { - self.base.into_key_value() - } - - /// Sets the value of the entry, and returns the entry's old value. - #[inline] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn insert(&mut self, value: V) -> V { - self.base.insert(value) - } - - /// Sets the value of the entry, and returns the entry's old value. - #[inline] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn insert_key(&mut self, key: K) -> K { - self.base.insert_key(key) - } - - /// Takes the value out of the entry, and returns it. - #[inline] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn remove(self) -> V { - self.base.remove() - } - - /// Take the ownership of the key and value from the map. - #[inline] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn remove_entry(self) -> (K, V) { - self.base.remove_entry() - } -} - -impl<'a, K, V, S> RawVacantEntryMut<'a, K, V, S> { - /// Sets the value of the entry with the `VacantEntry`'s key, - /// and returns a mutable reference to it. - #[inline] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn insert(self, key: K, value: V) -> (&'a mut K, &'a mut V) - where - K: Hash, - S: BuildHasher, - { - self.base.insert(key, value) - } - - /// Sets the value of the entry with the VacantEntry's key, - /// and returns a mutable reference to it. - #[inline] - #[unstable(feature = "hash_raw_entry", issue = "56167")] - pub fn insert_hashed_nocheck(self, hash: u64, key: K, value: V) -> (&'a mut K, &'a mut V) - where - K: Hash, - S: BuildHasher, - { - self.base.insert_hashed_nocheck(hash, key, value) - } -} - -#[unstable(feature = "hash_raw_entry", issue = "56167")] -impl Debug for RawEntryBuilderMut<'_, K, V, S> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("RawEntryBuilder").finish_non_exhaustive() - } -} - -#[unstable(feature = "hash_raw_entry", issue = "56167")] -impl Debug for RawEntryMut<'_, K, V, S> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - match *self { - RawEntryMut::Vacant(ref v) => f.debug_tuple("RawEntry").field(v).finish(), - RawEntryMut::Occupied(ref o) => f.debug_tuple("RawEntry").field(o).finish(), - } - } -} - -#[unstable(feature = "hash_raw_entry", issue = "56167")] -impl Debug for RawOccupiedEntryMut<'_, K, V, S> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("RawOccupiedEntryMut") - .field("key", self.key()) - .field("value", self.get()) - .finish_non_exhaustive() - } -} - -#[unstable(feature = "hash_raw_entry", issue = "56167")] -impl Debug for RawVacantEntryMut<'_, K, V, S> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("RawVacantEntryMut").finish_non_exhaustive() - } -} - -#[unstable(feature = "hash_raw_entry", issue = "56167")] -impl Debug for RawEntryBuilder<'_, K, V, S> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("RawEntryBuilder").finish_non_exhaustive() - } -} - -/// A view into a single entry in a map, which may either be vacant or occupied. -/// -/// This `enum` is constructed from the [`entry`] method on [`HashMap`]. -/// -/// [`entry`]: HashMap::entry -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "HashMapEntry")] -pub enum Entry<'a, K: 'a, V: 'a> { - /// An occupied entry. - #[stable(feature = "rust1", since = "1.0.0")] - Occupied(#[stable(feature = "rust1", since = "1.0.0")] OccupiedEntry<'a, K, V>), - - /// A vacant entry. - #[stable(feature = "rust1", since = "1.0.0")] - Vacant(#[stable(feature = "rust1", since = "1.0.0")] VacantEntry<'a, K, V>), -} - -#[stable(feature = "debug_hash_map", since = "1.12.0")] -impl Debug for Entry<'_, K, V> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - match *self { - Vacant(ref v) => f.debug_tuple("Entry").field(v).finish(), - Occupied(ref o) => f.debug_tuple("Entry").field(o).finish(), - } - } -} - -/// A view into an occupied entry in a `HashMap`. -/// It is part of the [`Entry`] enum. -#[stable(feature = "rust1", since = "1.0.0")] -pub struct OccupiedEntry<'a, K: 'a, V: 'a> { - base: base::RustcOccupiedEntry<'a, K, V>, -} - -#[stable(feature = "debug_hash_map", since = "1.12.0")] -impl Debug for OccupiedEntry<'_, K, V> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("OccupiedEntry") - .field("key", self.key()) - .field("value", self.get()) - .finish_non_exhaustive() - } -} - -/// A view into a vacant entry in a `HashMap`. -/// It is part of the [`Entry`] enum. -#[stable(feature = "rust1", since = "1.0.0")] -pub struct VacantEntry<'a, K: 'a, V: 'a> { - base: base::RustcVacantEntry<'a, K, V>, -} - -#[stable(feature = "debug_hash_map", since = "1.12.0")] -impl Debug for VacantEntry<'_, K, V> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("VacantEntry").field(self.key()).finish() - } -} - -/// The error returned by [`try_insert`](HashMap::try_insert) when the key already exists. -/// -/// Contains the occupied entry, and the value that was not inserted. -#[unstable(feature = "map_try_insert", issue = "82766")] -pub struct OccupiedError<'a, K: 'a, V: 'a> { - /// The entry in the map that was already occupied. - pub entry: OccupiedEntry<'a, K, V>, - /// The value which was not inserted, because the entry was already occupied. - pub value: V, -} - -#[unstable(feature = "map_try_insert", issue = "82766")] -impl Debug for OccupiedError<'_, K, V> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("OccupiedError") - .field("key", self.entry.key()) - .field("old_value", self.entry.get()) - .field("new_value", &self.value) - .finish_non_exhaustive() - } -} - -#[unstable(feature = "map_try_insert", issue = "82766")] -impl<'a, K: Debug, V: Debug> fmt::Display for OccupiedError<'a, K, V> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!( - f, - "failed to insert {:?}, key {:?} already exists with value {:?}", - self.value, - self.entry.key(), - self.entry.get(), - ) - } -} - -#[unstable(feature = "map_try_insert", issue = "82766")] -impl<'a, K: fmt::Debug, V: fmt::Debug> Error for OccupiedError<'a, K, V> { - #[allow(deprecated)] - fn description(&self) -> &str { - "key already exists" - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, K, V, S> IntoIterator for &'a HashMap { - type Item = (&'a K, &'a V); - type IntoIter = Iter<'a, K, V>; - - #[inline] - #[rustc_lint_query_instability] - fn into_iter(self) -> Iter<'a, K, V> { - self.iter() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, K, V, S> IntoIterator for &'a mut HashMap { - type Item = (&'a K, &'a mut V); - type IntoIter = IterMut<'a, K, V>; - - #[inline] - #[rustc_lint_query_instability] - fn into_iter(self) -> IterMut<'a, K, V> { - self.iter_mut() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl IntoIterator for HashMap { - type Item = (K, V); - type IntoIter = IntoIter; - - /// Creates a consuming iterator, that is, one that moves each key-value - /// pair out of the map in arbitrary order. The map cannot be used after - /// calling this. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let map = HashMap::from([ - /// ("a", 1), - /// ("b", 2), - /// ("c", 3), - /// ]); - /// - /// // Not possible with .iter() - /// let vec: Vec<(&str, i32)> = map.into_iter().collect(); - /// ``` - #[inline] - #[rustc_lint_query_instability] - fn into_iter(self) -> IntoIter { - IntoIter { base: self.base.into_iter() } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, K, V> Iterator for Iter<'a, K, V> { - type Item = (&'a K, &'a V); - - #[inline] - fn next(&mut self) -> Option<(&'a K, &'a V)> { - self.base.next() - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.base.size_hint() - } - #[inline] - fn count(self) -> usize { - self.base.len() - } - #[inline] - fn fold(self, init: B, f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - self.base.fold(init, f) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Iter<'_, K, V> { - #[inline] - fn len(&self) -> usize { - self.base.len() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Iter<'_, K, V> {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, K, V> Iterator for IterMut<'a, K, V> { - type Item = (&'a K, &'a mut V); - - #[inline] - fn next(&mut self) -> Option<(&'a K, &'a mut V)> { - self.base.next() - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.base.size_hint() - } - #[inline] - fn count(self) -> usize { - self.base.len() - } - #[inline] - fn fold(self, init: B, f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - self.base.fold(init, f) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for IterMut<'_, K, V> { - #[inline] - fn len(&self) -> usize { - self.base.len() - } -} -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for IterMut<'_, K, V> {} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for IterMut<'_, K, V> -where - K: fmt::Debug, - V: fmt::Debug, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.iter()).finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for IntoIter { - type Item = (K, V); - - #[inline] - fn next(&mut self) -> Option<(K, V)> { - self.base.next() - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.base.size_hint() - } - #[inline] - fn count(self) -> usize { - self.base.len() - } - #[inline] - fn fold(self, init: B, f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - self.base.fold(init, f) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for IntoIter { - #[inline] - fn len(&self) -> usize { - self.base.len() - } -} -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for IntoIter {} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for IntoIter { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.iter()).finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, K, V> Iterator for Keys<'a, K, V> { - type Item = &'a K; - - #[inline] - fn next(&mut self) -> Option<&'a K> { - self.inner.next().map(|(k, _)| k) - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } - #[inline] - fn count(self) -> usize { - self.inner.len() - } - #[inline] - fn fold(self, init: B, mut f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - self.inner.fold(init, |acc, (k, _)| f(acc, k)) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Keys<'_, K, V> { - #[inline] - fn len(&self) -> usize { - self.inner.len() - } -} -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Keys<'_, K, V> {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, K, V> Iterator for Values<'a, K, V> { - type Item = &'a V; - - #[inline] - fn next(&mut self) -> Option<&'a V> { - self.inner.next().map(|(_, v)| v) - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } - #[inline] - fn count(self) -> usize { - self.inner.len() - } - #[inline] - fn fold(self, init: B, mut f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - self.inner.fold(init, |acc, (_, v)| f(acc, v)) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Values<'_, K, V> { - #[inline] - fn len(&self) -> usize { - self.inner.len() - } -} -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Values<'_, K, V> {} - -#[stable(feature = "map_values_mut", since = "1.10.0")] -impl<'a, K, V> Iterator for ValuesMut<'a, K, V> { - type Item = &'a mut V; - - #[inline] - fn next(&mut self) -> Option<&'a mut V> { - self.inner.next().map(|(_, v)| v) - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } - #[inline] - fn count(self) -> usize { - self.inner.len() - } - #[inline] - fn fold(self, init: B, mut f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - self.inner.fold(init, |acc, (_, v)| f(acc, v)) - } -} -#[stable(feature = "map_values_mut", since = "1.10.0")] -impl ExactSizeIterator for ValuesMut<'_, K, V> { - #[inline] - fn len(&self) -> usize { - self.inner.len() - } -} -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for ValuesMut<'_, K, V> {} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for ValuesMut<'_, K, V> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.inner.iter().map(|(_, val)| val)).finish() - } -} - -#[stable(feature = "map_into_keys_values", since = "1.54.0")] -impl Iterator for IntoKeys { - type Item = K; - - #[inline] - fn next(&mut self) -> Option { - self.inner.next().map(|(k, _)| k) - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } - #[inline] - fn count(self) -> usize { - self.inner.len() - } - #[inline] - fn fold(self, init: B, mut f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - self.inner.fold(init, |acc, (k, _)| f(acc, k)) - } -} -#[stable(feature = "map_into_keys_values", since = "1.54.0")] -impl ExactSizeIterator for IntoKeys { - #[inline] - fn len(&self) -> usize { - self.inner.len() - } -} -#[stable(feature = "map_into_keys_values", since = "1.54.0")] -impl FusedIterator for IntoKeys {} - -#[stable(feature = "map_into_keys_values", since = "1.54.0")] -impl fmt::Debug for IntoKeys { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.inner.iter().map(|(k, _)| k)).finish() - } -} - -#[stable(feature = "map_into_keys_values", since = "1.54.0")] -impl Iterator for IntoValues { - type Item = V; - - #[inline] - fn next(&mut self) -> Option { - self.inner.next().map(|(_, v)| v) - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } - #[inline] - fn count(self) -> usize { - self.inner.len() - } - #[inline] - fn fold(self, init: B, mut f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - self.inner.fold(init, |acc, (_, v)| f(acc, v)) - } -} -#[stable(feature = "map_into_keys_values", since = "1.54.0")] -impl ExactSizeIterator for IntoValues { - #[inline] - fn len(&self) -> usize { - self.inner.len() - } -} -#[stable(feature = "map_into_keys_values", since = "1.54.0")] -impl FusedIterator for IntoValues {} - -#[stable(feature = "map_into_keys_values", since = "1.54.0")] -impl fmt::Debug for IntoValues { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.inner.iter().map(|(_, v)| v)).finish() - } -} - -#[stable(feature = "drain", since = "1.6.0")] -impl<'a, K, V> Iterator for Drain<'a, K, V> { - type Item = (K, V); - - #[inline] - fn next(&mut self) -> Option<(K, V)> { - self.base.next() - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.base.size_hint() - } - #[inline] - fn fold(self, init: B, f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - self.base.fold(init, f) - } -} -#[stable(feature = "drain", since = "1.6.0")] -impl ExactSizeIterator for Drain<'_, K, V> { - #[inline] - fn len(&self) -> usize { - self.base.len() - } -} -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Drain<'_, K, V> {} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for Drain<'_, K, V> -where - K: fmt::Debug, - V: fmt::Debug, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.iter()).finish() - } -} - -#[unstable(feature = "hash_extract_if", issue = "59618")] -impl Iterator for ExtractIf<'_, K, V, F> -where - F: FnMut(&K, &mut V) -> bool, -{ - type Item = (K, V); - - #[inline] - fn next(&mut self) -> Option<(K, V)> { - self.base.next() - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.base.size_hint() - } -} - -#[unstable(feature = "hash_extract_if", issue = "59618")] -impl FusedIterator for ExtractIf<'_, K, V, F> where F: FnMut(&K, &mut V) -> bool {} - -#[unstable(feature = "hash_extract_if", issue = "59618")] -impl<'a, K, V, F> fmt::Debug for ExtractIf<'a, K, V, F> -where - F: FnMut(&K, &mut V) -> bool, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("ExtractIf").finish_non_exhaustive() - } -} - -impl<'a, K, V> Entry<'a, K, V> { - /// Ensures a value is in the entry by inserting the default if empty, and returns - /// a mutable reference to the value in the entry. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut map: HashMap<&str, u32> = HashMap::new(); - /// - /// map.entry("poneyland").or_insert(3); - /// assert_eq!(map["poneyland"], 3); - /// - /// *map.entry("poneyland").or_insert(10) *= 2; - /// assert_eq!(map["poneyland"], 6); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn or_insert(self, default: V) -> &'a mut V { - match self { - Occupied(entry) => entry.into_mut(), - Vacant(entry) => entry.insert(default), - } - } - - /// Ensures a value is in the entry by inserting the result of the default function if empty, - /// and returns a mutable reference to the value in the entry. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut map = HashMap::new(); - /// let value = "hoho"; - /// - /// map.entry("poneyland").or_insert_with(|| value); - /// - /// assert_eq!(map["poneyland"], "hoho"); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn or_insert_with V>(self, default: F) -> &'a mut V { - match self { - Occupied(entry) => entry.into_mut(), - Vacant(entry) => entry.insert(default()), - } - } - - /// Ensures a value is in the entry by inserting, if empty, the result of the default function. - /// This method allows for generating key-derived values for insertion by providing the default - /// function a reference to the key that was moved during the `.entry(key)` method call. - /// - /// The reference to the moved key is provided so that cloning or copying the key is - /// unnecessary, unlike with `.or_insert_with(|| ... )`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut map: HashMap<&str, usize> = HashMap::new(); - /// - /// map.entry("poneyland").or_insert_with_key(|key| key.chars().count()); - /// - /// assert_eq!(map["poneyland"], 9); - /// ``` - #[inline] - #[stable(feature = "or_insert_with_key", since = "1.50.0")] - pub fn or_insert_with_key V>(self, default: F) -> &'a mut V { - match self { - Occupied(entry) => entry.into_mut(), - Vacant(entry) => { - let value = default(entry.key()); - entry.insert(value) - } - } - } - - /// Returns a reference to this entry's key. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut map: HashMap<&str, u32> = HashMap::new(); - /// assert_eq!(map.entry("poneyland").key(), &"poneyland"); - /// ``` - #[inline] - #[stable(feature = "map_entry_keys", since = "1.10.0")] - pub fn key(&self) -> &K { - match *self { - Occupied(ref entry) => entry.key(), - Vacant(ref entry) => entry.key(), - } - } - - /// Provides in-place mutable access to an occupied entry before any - /// potential inserts into the map. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut map: HashMap<&str, u32> = HashMap::new(); - /// - /// map.entry("poneyland") - /// .and_modify(|e| { *e += 1 }) - /// .or_insert(42); - /// assert_eq!(map["poneyland"], 42); - /// - /// map.entry("poneyland") - /// .and_modify(|e| { *e += 1 }) - /// .or_insert(42); - /// assert_eq!(map["poneyland"], 43); - /// ``` - #[inline] - #[stable(feature = "entry_and_modify", since = "1.26.0")] - pub fn and_modify(self, f: F) -> Self - where - F: FnOnce(&mut V), - { - match self { - Occupied(mut entry) => { - f(entry.get_mut()); - Occupied(entry) - } - Vacant(entry) => Vacant(entry), - } - } - - /// Sets the value of the entry, and returns an `OccupiedEntry`. - /// - /// # Examples - /// - /// ``` - /// #![feature(entry_insert)] - /// use std::collections::HashMap; - /// - /// let mut map: HashMap<&str, String> = HashMap::new(); - /// let entry = map.entry("poneyland").insert_entry("hoho".to_string()); - /// - /// assert_eq!(entry.key(), &"poneyland"); - /// ``` - #[inline] - #[unstable(feature = "entry_insert", issue = "65225")] - pub fn insert_entry(self, value: V) -> OccupiedEntry<'a, K, V> { - match self { - Occupied(mut entry) => { - entry.insert(value); - entry - } - Vacant(entry) => entry.insert_entry(value), - } - } -} - -impl<'a, K, V: Default> Entry<'a, K, V> { - /// Ensures a value is in the entry by inserting the default value if empty, - /// and returns a mutable reference to the value in the entry. - /// - /// # Examples - /// - /// ``` - /// # fn main() { - /// use std::collections::HashMap; - /// - /// let mut map: HashMap<&str, Option> = HashMap::new(); - /// map.entry("poneyland").or_default(); - /// - /// assert_eq!(map["poneyland"], None); - /// # } - /// ``` - #[inline] - #[stable(feature = "entry_or_default", since = "1.28.0")] - pub fn or_default(self) -> &'a mut V { - match self { - Occupied(entry) => entry.into_mut(), - Vacant(entry) => entry.insert(Default::default()), - } - } -} - -impl<'a, K, V> OccupiedEntry<'a, K, V> { - /// Gets a reference to the key in the entry. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut map: HashMap<&str, u32> = HashMap::new(); - /// map.entry("poneyland").or_insert(12); - /// assert_eq!(map.entry("poneyland").key(), &"poneyland"); - /// ``` - #[inline] - #[stable(feature = "map_entry_keys", since = "1.10.0")] - pub fn key(&self) -> &K { - self.base.key() - } - - /// Take the ownership of the key and value from the map. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// use std::collections::hash_map::Entry; - /// - /// let mut map: HashMap<&str, u32> = HashMap::new(); - /// map.entry("poneyland").or_insert(12); - /// - /// if let Entry::Occupied(o) = map.entry("poneyland") { - /// // We delete the entry from the map. - /// o.remove_entry(); - /// } - /// - /// assert_eq!(map.contains_key("poneyland"), false); - /// ``` - #[inline] - #[stable(feature = "map_entry_recover_keys2", since = "1.12.0")] - pub fn remove_entry(self) -> (K, V) { - self.base.remove_entry() - } - - /// Gets a reference to the value in the entry. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// use std::collections::hash_map::Entry; - /// - /// let mut map: HashMap<&str, u32> = HashMap::new(); - /// map.entry("poneyland").or_insert(12); - /// - /// if let Entry::Occupied(o) = map.entry("poneyland") { - /// assert_eq!(o.get(), &12); - /// } - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn get(&self) -> &V { - self.base.get() - } - - /// Gets a mutable reference to the value in the entry. - /// - /// If you need a reference to the `OccupiedEntry` which may outlive the - /// destruction of the `Entry` value, see [`into_mut`]. - /// - /// [`into_mut`]: Self::into_mut - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// use std::collections::hash_map::Entry; - /// - /// let mut map: HashMap<&str, u32> = HashMap::new(); - /// map.entry("poneyland").or_insert(12); - /// - /// assert_eq!(map["poneyland"], 12); - /// if let Entry::Occupied(mut o) = map.entry("poneyland") { - /// *o.get_mut() += 10; - /// assert_eq!(*o.get(), 22); - /// - /// // We can use the same Entry multiple times. - /// *o.get_mut() += 2; - /// } - /// - /// assert_eq!(map["poneyland"], 24); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn get_mut(&mut self) -> &mut V { - self.base.get_mut() - } - - /// Converts the `OccupiedEntry` into a mutable reference to the value in the entry - /// with a lifetime bound to the map itself. - /// - /// If you need multiple references to the `OccupiedEntry`, see [`get_mut`]. - /// - /// [`get_mut`]: Self::get_mut - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// use std::collections::hash_map::Entry; - /// - /// let mut map: HashMap<&str, u32> = HashMap::new(); - /// map.entry("poneyland").or_insert(12); - /// - /// assert_eq!(map["poneyland"], 12); - /// if let Entry::Occupied(o) = map.entry("poneyland") { - /// *o.into_mut() += 10; - /// } - /// - /// assert_eq!(map["poneyland"], 22); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn into_mut(self) -> &'a mut V { - self.base.into_mut() - } - - /// Sets the value of the entry, and returns the entry's old value. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// use std::collections::hash_map::Entry; - /// - /// let mut map: HashMap<&str, u32> = HashMap::new(); - /// map.entry("poneyland").or_insert(12); - /// - /// if let Entry::Occupied(mut o) = map.entry("poneyland") { - /// assert_eq!(o.insert(15), 12); - /// } - /// - /// assert_eq!(map["poneyland"], 15); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn insert(&mut self, value: V) -> V { - self.base.insert(value) - } - - /// Takes the value out of the entry, and returns it. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// use std::collections::hash_map::Entry; - /// - /// let mut map: HashMap<&str, u32> = HashMap::new(); - /// map.entry("poneyland").or_insert(12); - /// - /// if let Entry::Occupied(o) = map.entry("poneyland") { - /// assert_eq!(o.remove(), 12); - /// } - /// - /// assert_eq!(map.contains_key("poneyland"), false); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn remove(self) -> V { - self.base.remove() - } - - /// Replaces the entry, returning the old key and value. The new key in the hash map will be - /// the key used to create this entry. - /// - /// # Examples - /// - /// ``` - /// #![feature(map_entry_replace)] - /// use std::collections::hash_map::{Entry, HashMap}; - /// use std::rc::Rc; - /// - /// let mut map: HashMap, u32> = HashMap::new(); - /// map.insert(Rc::new("Stringthing".to_string()), 15); - /// - /// let my_key = Rc::new("Stringthing".to_string()); - /// - /// if let Entry::Occupied(entry) = map.entry(my_key) { - /// // Also replace the key with a handle to our other key. - /// let (old_key, old_value): (Rc, u32) = entry.replace_entry(16); - /// } - /// - /// ``` - #[inline] - #[unstable(feature = "map_entry_replace", issue = "44286")] - pub fn replace_entry(self, value: V) -> (K, V) { - self.base.replace_entry(value) - } - - /// Replaces the key in the hash map with the key used to create this entry. - /// - /// # Examples - /// - /// ``` - /// #![feature(map_entry_replace)] - /// use std::collections::hash_map::{Entry, HashMap}; - /// use std::rc::Rc; - /// - /// let mut map: HashMap, u32> = HashMap::new(); - /// let known_strings: Vec> = Vec::new(); - /// - /// // Initialise known strings, run program, etc. - /// - /// reclaim_memory(&mut map, &known_strings); - /// - /// fn reclaim_memory(map: &mut HashMap, u32>, known_strings: &[Rc] ) { - /// for s in known_strings { - /// if let Entry::Occupied(entry) = map.entry(Rc::clone(s)) { - /// // Replaces the entry's key with our version of it in `known_strings`. - /// entry.replace_key(); - /// } - /// } - /// } - /// ``` - #[inline] - #[unstable(feature = "map_entry_replace", issue = "44286")] - pub fn replace_key(self) -> K { - self.base.replace_key() - } -} - -impl<'a, K: 'a, V: 'a> VacantEntry<'a, K, V> { - /// Gets a reference to the key that would be used when inserting a value - /// through the `VacantEntry`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// - /// let mut map: HashMap<&str, u32> = HashMap::new(); - /// assert_eq!(map.entry("poneyland").key(), &"poneyland"); - /// ``` - #[inline] - #[stable(feature = "map_entry_keys", since = "1.10.0")] - pub fn key(&self) -> &K { - self.base.key() - } - - /// Take ownership of the key. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// use std::collections::hash_map::Entry; - /// - /// let mut map: HashMap<&str, u32> = HashMap::new(); - /// - /// if let Entry::Vacant(v) = map.entry("poneyland") { - /// v.into_key(); - /// } - /// ``` - #[inline] - #[stable(feature = "map_entry_recover_keys2", since = "1.12.0")] - pub fn into_key(self) -> K { - self.base.into_key() - } - - /// Sets the value of the entry with the `VacantEntry`'s key, - /// and returns a mutable reference to it. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashMap; - /// use std::collections::hash_map::Entry; - /// - /// let mut map: HashMap<&str, u32> = HashMap::new(); - /// - /// if let Entry::Vacant(o) = map.entry("poneyland") { - /// o.insert(37); - /// } - /// assert_eq!(map["poneyland"], 37); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn insert(self, value: V) -> &'a mut V { - self.base.insert(value) - } - - /// Sets the value of the entry with the `VacantEntry`'s key, - /// and returns an `OccupiedEntry`. - /// - /// # Examples - /// - /// ``` - /// #![feature(entry_insert)] - /// use std::collections::HashMap; - /// use std::collections::hash_map::Entry; - /// - /// let mut map: HashMap<&str, u32> = HashMap::new(); - /// - /// if let Entry::Vacant(o) = map.entry("poneyland") { - /// o.insert_entry(37); - /// } - /// assert_eq!(map["poneyland"], 37); - /// ``` - #[inline] - #[unstable(feature = "entry_insert", issue = "65225")] - pub fn insert_entry(self, value: V) -> OccupiedEntry<'a, K, V> { - let base = self.base.insert_entry(value); - OccupiedEntry { base } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl FromIterator<(K, V)> for HashMap -where - K: Eq + Hash, - S: BuildHasher + Default, -{ - fn from_iter>(iter: T) -> HashMap { - let mut map = HashMap::with_hasher(Default::default()); - map.extend(iter); - map - } -} - -/// Inserts all new key-values from the iterator and replaces values with existing -/// keys with new values returned from the iterator. -#[stable(feature = "rust1", since = "1.0.0")] -impl Extend<(K, V)> for HashMap -where - K: Eq + Hash, - S: BuildHasher, -{ - #[inline] - fn extend>(&mut self, iter: T) { - self.base.extend(iter) - } - - #[inline] - fn extend_one(&mut self, (k, v): (K, V)) { - self.base.insert(k, v); - } - - #[inline] - fn extend_reserve(&mut self, additional: usize) { - self.base.extend_reserve(additional); - } -} - -#[stable(feature = "hash_extend_copy", since = "1.4.0")] -impl<'a, K, V, S> Extend<(&'a K, &'a V)> for HashMap -where - K: Eq + Hash + Copy, - V: Copy, - S: BuildHasher, -{ - #[inline] - fn extend>(&mut self, iter: T) { - self.base.extend(iter) - } - - #[inline] - fn extend_one(&mut self, (&k, &v): (&'a K, &'a V)) { - self.base.insert(k, v); - } - - #[inline] - fn extend_reserve(&mut self, additional: usize) { - Extend::<(K, V)>::extend_reserve(self, additional) - } -} - -#[inline] -fn map_entry<'a, K: 'a, V: 'a>(raw: base::RustcEntry<'a, K, V>) -> Entry<'a, K, V> { - match raw { - base::RustcEntry::Occupied(base) => Entry::Occupied(OccupiedEntry { base }), - base::RustcEntry::Vacant(base) => Entry::Vacant(VacantEntry { base }), - } -} - -#[inline] -pub(super) fn map_try_reserve_error(err: hashbrown::TryReserveError) -> TryReserveError { - match err { - hashbrown::TryReserveError::CapacityOverflow => { - TryReserveErrorKind::CapacityOverflow.into() - } - hashbrown::TryReserveError::AllocError { layout } => { - TryReserveErrorKind::AllocError { layout, non_exhaustive: () }.into() - } - } -} - -#[inline] -fn map_raw_entry<'a, K: 'a, V: 'a, S: 'a>( - raw: base::RawEntryMut<'a, K, V, S>, -) -> RawEntryMut<'a, K, V, S> { - match raw { - base::RawEntryMut::Occupied(base) => RawEntryMut::Occupied(RawOccupiedEntryMut { base }), - base::RawEntryMut::Vacant(base) => RawEntryMut::Vacant(RawVacantEntryMut { base }), - } -} - -#[allow(dead_code)] -fn assert_covariance() { - fn map_key<'new>(v: HashMap<&'static str, u8>) -> HashMap<&'new str, u8> { - v - } - fn map_val<'new>(v: HashMap) -> HashMap { - v - } - fn iter_key<'a, 'new>(v: Iter<'a, &'static str, u8>) -> Iter<'a, &'new str, u8> { - v - } - fn iter_val<'a, 'new>(v: Iter<'a, u8, &'static str>) -> Iter<'a, u8, &'new str> { - v - } - fn into_iter_key<'new>(v: IntoIter<&'static str, u8>) -> IntoIter<&'new str, u8> { - v - } - fn into_iter_val<'new>(v: IntoIter) -> IntoIter { - v - } - fn keys_key<'a, 'new>(v: Keys<'a, &'static str, u8>) -> Keys<'a, &'new str, u8> { - v - } - fn keys_val<'a, 'new>(v: Keys<'a, u8, &'static str>) -> Keys<'a, u8, &'new str> { - v - } - fn values_key<'a, 'new>(v: Values<'a, &'static str, u8>) -> Values<'a, &'new str, u8> { - v - } - fn values_val<'a, 'new>(v: Values<'a, u8, &'static str>) -> Values<'a, u8, &'new str> { - v - } - fn drain<'new>( - d: Drain<'static, &'static str, &'static str>, - ) -> Drain<'new, &'new str, &'new str> { - d - } -} diff --git a/library/std/src/collections/hash/map/tests.rs b/library/std/src/collections/hash/map/tests.rs deleted file mode 100644 index 8585376abc18b..0000000000000 --- a/library/std/src/collections/hash/map/tests.rs +++ /dev/null @@ -1,1126 +0,0 @@ -use super::Entry::{Occupied, Vacant}; -use super::HashMap; -use crate::assert_matches::assert_matches; -use crate::cell::RefCell; -use crate::hash::RandomState; -use crate::test_helpers::test_rng; -use rand::Rng; -use realstd::collections::TryReserveErrorKind::*; - -// https://github.com/rust-lang/rust/issues/62301 -fn _assert_hashmap_is_unwind_safe() { - fn assert_unwind_safe() {} - assert_unwind_safe::>>(); -} - -#[test] -fn test_zero_capacities() { - type HM = HashMap; - - let m = HM::new(); - assert_eq!(m.capacity(), 0); - - let m = HM::default(); - assert_eq!(m.capacity(), 0); - - let m = HM::with_hasher(RandomState::new()); - assert_eq!(m.capacity(), 0); - - let m = HM::with_capacity(0); - assert_eq!(m.capacity(), 0); - - let m = HM::with_capacity_and_hasher(0, RandomState::new()); - assert_eq!(m.capacity(), 0); - - let mut m = HM::new(); - m.insert(1, 1); - m.insert(2, 2); - m.remove(&1); - m.remove(&2); - m.shrink_to_fit(); - assert_eq!(m.capacity(), 0); - - let mut m = HM::new(); - m.reserve(0); - assert_eq!(m.capacity(), 0); -} - -#[test] -fn test_create_capacity_zero() { - let mut m = HashMap::with_capacity(0); - - assert!(m.insert(1, 1).is_none()); - - assert!(m.contains_key(&1)); - assert!(!m.contains_key(&0)); -} - -#[test] -fn test_insert() { - let mut m = HashMap::new(); - assert_eq!(m.len(), 0); - assert!(m.insert(1, 2).is_none()); - assert_eq!(m.len(), 1); - assert!(m.insert(2, 4).is_none()); - assert_eq!(m.len(), 2); - assert_eq!(*m.get(&1).unwrap(), 2); - assert_eq!(*m.get(&2).unwrap(), 4); -} - -#[test] -fn test_clone() { - let mut m = HashMap::new(); - assert_eq!(m.len(), 0); - assert!(m.insert(1, 2).is_none()); - assert_eq!(m.len(), 1); - assert!(m.insert(2, 4).is_none()); - assert_eq!(m.len(), 2); - let m2 = m.clone(); - assert_eq!(*m2.get(&1).unwrap(), 2); - assert_eq!(*m2.get(&2).unwrap(), 4); - assert_eq!(m2.len(), 2); -} - -thread_local! { static DROP_VECTOR: RefCell> = RefCell::new(Vec::new()) } - -#[derive(Hash, PartialEq, Eq)] -struct Droppable { - k: usize, -} - -impl Droppable { - fn new(k: usize) -> Droppable { - DROP_VECTOR.with(|slot| { - slot.borrow_mut()[k] += 1; - }); - - Droppable { k } - } -} - -impl Drop for Droppable { - fn drop(&mut self) { - DROP_VECTOR.with(|slot| { - slot.borrow_mut()[self.k] -= 1; - }); - } -} - -impl Clone for Droppable { - fn clone(&self) -> Droppable { - Droppable::new(self.k) - } -} - -#[test] -fn test_drops() { - DROP_VECTOR.with(|slot| { - *slot.borrow_mut() = vec![0; 200]; - }); - - { - let mut m = HashMap::new(); - - DROP_VECTOR.with(|v| { - for i in 0..200 { - assert_eq!(v.borrow()[i], 0); - } - }); - - for i in 0..100 { - let d1 = Droppable::new(i); - let d2 = Droppable::new(i + 100); - m.insert(d1, d2); - } - - DROP_VECTOR.with(|v| { - for i in 0..200 { - assert_eq!(v.borrow()[i], 1); - } - }); - - for i in 0..50 { - let k = Droppable::new(i); - let v = m.remove(&k); - - assert!(v.is_some()); - - DROP_VECTOR.with(|v| { - assert_eq!(v.borrow()[i], 1); - assert_eq!(v.borrow()[i + 100], 1); - }); - } - - DROP_VECTOR.with(|v| { - for i in 0..50 { - assert_eq!(v.borrow()[i], 0); - assert_eq!(v.borrow()[i + 100], 0); - } - - for i in 50..100 { - assert_eq!(v.borrow()[i], 1); - assert_eq!(v.borrow()[i + 100], 1); - } - }); - } - - DROP_VECTOR.with(|v| { - for i in 0..200 { - assert_eq!(v.borrow()[i], 0); - } - }); -} - -#[test] -fn test_into_iter_drops() { - DROP_VECTOR.with(|v| { - *v.borrow_mut() = vec![0; 200]; - }); - - let hm = { - let mut hm = HashMap::new(); - - DROP_VECTOR.with(|v| { - for i in 0..200 { - assert_eq!(v.borrow()[i], 0); - } - }); - - for i in 0..100 { - let d1 = Droppable::new(i); - let d2 = Droppable::new(i + 100); - hm.insert(d1, d2); - } - - DROP_VECTOR.with(|v| { - for i in 0..200 { - assert_eq!(v.borrow()[i], 1); - } - }); - - hm - }; - - // By the way, ensure that cloning doesn't screw up the dropping. - drop(hm.clone()); - - { - let mut half = hm.into_iter().take(50); - - DROP_VECTOR.with(|v| { - for i in 0..200 { - assert_eq!(v.borrow()[i], 1); - } - }); - - for _ in half.by_ref() {} - - DROP_VECTOR.with(|v| { - let nk = (0..100).filter(|&i| v.borrow()[i] == 1).count(); - - let nv = (0..100).filter(|&i| v.borrow()[i + 100] == 1).count(); - - assert_eq!(nk, 50); - assert_eq!(nv, 50); - }); - }; - - DROP_VECTOR.with(|v| { - for i in 0..200 { - assert_eq!(v.borrow()[i], 0); - } - }); -} - -#[test] -fn test_empty_remove() { - let mut m: HashMap = HashMap::new(); - assert_eq!(m.remove(&0), None); -} - -#[test] -fn test_empty_entry() { - let mut m: HashMap = HashMap::new(); - match m.entry(0) { - Occupied(_) => panic!(), - Vacant(_) => {} - } - assert!(*m.entry(0).or_insert(true)); - assert_eq!(m.len(), 1); -} - -#[test] -fn test_empty_iter() { - let mut m: HashMap = HashMap::new(); - assert_eq!(m.drain().next(), None); - assert_eq!(m.keys().next(), None); - assert_eq!(m.values().next(), None); - assert_eq!(m.values_mut().next(), None); - assert_eq!(m.iter().next(), None); - assert_eq!(m.iter_mut().next(), None); - assert_eq!(m.len(), 0); - assert!(m.is_empty()); - assert_eq!(m.into_iter().next(), None); -} - -#[test] -fn test_lots_of_insertions() { - let mut m = HashMap::new(); - - // Try this a few times to make sure we never screw up the hashmap's - // internal state. - let loops = if cfg!(miri) { 2 } else { 10 }; - for _ in 0..loops { - assert!(m.is_empty()); - - let count = if cfg!(miri) { 101 } else { 1001 }; - - for i in 1..count { - assert!(m.insert(i, i).is_none()); - - for j in 1..=i { - let r = m.get(&j); - assert_eq!(r, Some(&j)); - } - - for j in i + 1..count { - let r = m.get(&j); - assert_eq!(r, None); - } - } - - for i in count..(2 * count) { - assert!(!m.contains_key(&i)); - } - - // remove forwards - for i in 1..count { - assert!(m.remove(&i).is_some()); - - for j in 1..=i { - assert!(!m.contains_key(&j)); - } - - for j in i + 1..count { - assert!(m.contains_key(&j)); - } - } - - for i in 1..count { - assert!(!m.contains_key(&i)); - } - - for i in 1..count { - assert!(m.insert(i, i).is_none()); - } - - // remove backwards - for i in (1..count).rev() { - assert!(m.remove(&i).is_some()); - - for j in i..count { - assert!(!m.contains_key(&j)); - } - - for j in 1..i { - assert!(m.contains_key(&j)); - } - } - } -} - -#[test] -fn test_find_mut() { - let mut m = HashMap::new(); - assert!(m.insert(1, 12).is_none()); - assert!(m.insert(2, 8).is_none()); - assert!(m.insert(5, 14).is_none()); - let new = 100; - match m.get_mut(&5) { - None => panic!(), - Some(x) => *x = new, - } - assert_eq!(m.get(&5), Some(&new)); -} - -#[test] -fn test_insert_overwrite() { - let mut m = HashMap::new(); - assert!(m.insert(1, 2).is_none()); - assert_eq!(*m.get(&1).unwrap(), 2); - assert!(!m.insert(1, 3).is_none()); - assert_eq!(*m.get(&1).unwrap(), 3); -} - -#[test] -fn test_insert_conflicts() { - let mut m = HashMap::with_capacity(4); - assert!(m.insert(1, 2).is_none()); - assert!(m.insert(5, 3).is_none()); - assert!(m.insert(9, 4).is_none()); - assert_eq!(*m.get(&9).unwrap(), 4); - assert_eq!(*m.get(&5).unwrap(), 3); - assert_eq!(*m.get(&1).unwrap(), 2); -} - -#[test] -fn test_conflict_remove() { - let mut m = HashMap::with_capacity(4); - assert!(m.insert(1, 2).is_none()); - assert_eq!(*m.get(&1).unwrap(), 2); - assert!(m.insert(5, 3).is_none()); - assert_eq!(*m.get(&1).unwrap(), 2); - assert_eq!(*m.get(&5).unwrap(), 3); - assert!(m.insert(9, 4).is_none()); - assert_eq!(*m.get(&1).unwrap(), 2); - assert_eq!(*m.get(&5).unwrap(), 3); - assert_eq!(*m.get(&9).unwrap(), 4); - assert!(m.remove(&1).is_some()); - assert_eq!(*m.get(&9).unwrap(), 4); - assert_eq!(*m.get(&5).unwrap(), 3); -} - -#[test] -fn test_is_empty() { - let mut m = HashMap::with_capacity(4); - assert!(m.insert(1, 2).is_none()); - assert!(!m.is_empty()); - assert!(m.remove(&1).is_some()); - assert!(m.is_empty()); -} - -#[test] -fn test_remove() { - let mut m = HashMap::new(); - m.insert(1, 2); - assert_eq!(m.remove(&1), Some(2)); - assert_eq!(m.remove(&1), None); -} - -#[test] -fn test_remove_entry() { - let mut m = HashMap::new(); - m.insert(1, 2); - assert_eq!(m.remove_entry(&1), Some((1, 2))); - assert_eq!(m.remove(&1), None); -} - -#[test] -fn test_iterate() { - let mut m = HashMap::with_capacity(4); - for i in 0..32 { - assert!(m.insert(i, i * 2).is_none()); - } - assert_eq!(m.len(), 32); - - let mut observed: u32 = 0; - - for (k, v) in &m { - assert_eq!(*v, *k * 2); - observed |= 1 << *k; - } - assert_eq!(observed, 0xFFFF_FFFF); -} - -#[test] -fn test_keys() { - let pairs = [(1, 'a'), (2, 'b'), (3, 'c')]; - let map: HashMap<_, _> = pairs.into_iter().collect(); - let keys: Vec<_> = map.keys().cloned().collect(); - assert_eq!(keys.len(), 3); - assert!(keys.contains(&1)); - assert!(keys.contains(&2)); - assert!(keys.contains(&3)); -} - -#[test] -fn test_values() { - let pairs = [(1, 'a'), (2, 'b'), (3, 'c')]; - let map: HashMap<_, _> = pairs.into_iter().collect(); - let values: Vec<_> = map.values().cloned().collect(); - assert_eq!(values.len(), 3); - assert!(values.contains(&'a')); - assert!(values.contains(&'b')); - assert!(values.contains(&'c')); -} - -#[test] -fn test_values_mut() { - let pairs = [(1, 1), (2, 2), (3, 3)]; - let mut map: HashMap<_, _> = pairs.into_iter().collect(); - for value in map.values_mut() { - *value = (*value) * 2 - } - let values: Vec<_> = map.values().cloned().collect(); - assert_eq!(values.len(), 3); - assert!(values.contains(&2)); - assert!(values.contains(&4)); - assert!(values.contains(&6)); -} - -#[test] -fn test_into_keys() { - let pairs = [(1, 'a'), (2, 'b'), (3, 'c')]; - let map: HashMap<_, _> = pairs.into_iter().collect(); - let keys: Vec<_> = map.into_keys().collect(); - - assert_eq!(keys.len(), 3); - assert!(keys.contains(&1)); - assert!(keys.contains(&2)); - assert!(keys.contains(&3)); -} - -#[test] -fn test_into_values() { - let pairs = [(1, 'a'), (2, 'b'), (3, 'c')]; - let map: HashMap<_, _> = pairs.into_iter().collect(); - let values: Vec<_> = map.into_values().collect(); - - assert_eq!(values.len(), 3); - assert!(values.contains(&'a')); - assert!(values.contains(&'b')); - assert!(values.contains(&'c')); -} - -#[test] -fn test_find() { - let mut m = HashMap::new(); - assert!(m.get(&1).is_none()); - m.insert(1, 2); - match m.get(&1) { - None => panic!(), - Some(v) => assert_eq!(*v, 2), - } -} - -#[test] -fn test_eq() { - let mut m1 = HashMap::new(); - m1.insert(1, 2); - m1.insert(2, 3); - m1.insert(3, 4); - - let mut m2 = HashMap::new(); - m2.insert(1, 2); - m2.insert(2, 3); - - assert!(m1 != m2); - - m2.insert(3, 4); - - assert_eq!(m1, m2); -} - -#[test] -fn test_show() { - let mut map = HashMap::new(); - let empty: HashMap = HashMap::new(); - - map.insert(1, 2); - map.insert(3, 4); - - let map_str = format!("{map:?}"); - - assert!(map_str == "{1: 2, 3: 4}" || map_str == "{3: 4, 1: 2}"); - assert_eq!(format!("{empty:?}"), "{}"); -} - -#[test] -fn test_reserve_shrink_to_fit() { - let mut m = HashMap::new(); - m.insert(0, 0); - m.remove(&0); - assert!(m.capacity() >= m.len()); - for i in 0..128 { - m.insert(i, i); - } - m.reserve(256); - - let usable_cap = m.capacity(); - for i in 128..(128 + 256) { - m.insert(i, i); - assert_eq!(m.capacity(), usable_cap); - } - - for i in 100..(128 + 256) { - assert_eq!(m.remove(&i), Some(i)); - } - m.shrink_to_fit(); - - assert_eq!(m.len(), 100); - assert!(!m.is_empty()); - assert!(m.capacity() >= m.len()); - - for i in 0..100 { - assert_eq!(m.remove(&i), Some(i)); - } - m.shrink_to_fit(); - m.insert(0, 0); - - assert_eq!(m.len(), 1); - assert!(m.capacity() >= m.len()); - assert_eq!(m.remove(&0), Some(0)); -} - -#[test] -fn test_from_iter() { - let xs = [(1, 1), (2, 2), (2, 2), (3, 3), (4, 4), (5, 5), (6, 6)]; - - let map: HashMap<_, _> = xs.iter().cloned().collect(); - - for &(k, v) in &xs { - assert_eq!(map.get(&k), Some(&v)); - } - - assert_eq!(map.iter().len(), xs.len() - 1); -} - -#[test] -fn test_size_hint() { - let xs = [(1, 1), (2, 2), (3, 3), (4, 4), (5, 5), (6, 6)]; - - let map: HashMap<_, _> = xs.iter().cloned().collect(); - - let mut iter = map.iter(); - - for _ in iter.by_ref().take(3) {} - - assert_eq!(iter.size_hint(), (3, Some(3))); -} - -#[test] -fn test_iter_len() { - let xs = [(1, 1), (2, 2), (3, 3), (4, 4), (5, 5), (6, 6)]; - - let map: HashMap<_, _> = xs.iter().cloned().collect(); - - let mut iter = map.iter(); - - for _ in iter.by_ref().take(3) {} - - assert_eq!(iter.len(), 3); -} - -#[test] -fn test_mut_size_hint() { - let xs = [(1, 1), (2, 2), (3, 3), (4, 4), (5, 5), (6, 6)]; - - let mut map: HashMap<_, _> = xs.iter().cloned().collect(); - - let mut iter = map.iter_mut(); - - for _ in iter.by_ref().take(3) {} - - assert_eq!(iter.size_hint(), (3, Some(3))); -} - -#[test] -fn test_iter_mut_len() { - let xs = [(1, 1), (2, 2), (3, 3), (4, 4), (5, 5), (6, 6)]; - - let mut map: HashMap<_, _> = xs.iter().cloned().collect(); - - let mut iter = map.iter_mut(); - - for _ in iter.by_ref().take(3) {} - - assert_eq!(iter.len(), 3); -} - -#[test] -fn test_index() { - let mut map = HashMap::new(); - - map.insert(1, 2); - map.insert(2, 1); - map.insert(3, 4); - - assert_eq!(map[&2], 1); -} - -#[test] -#[should_panic] -fn test_index_nonexistent() { - let mut map = HashMap::new(); - - map.insert(1, 2); - map.insert(2, 1); - map.insert(3, 4); - - map[&4]; -} - -#[test] -fn test_entry() { - let xs = [(1, 10), (2, 20), (3, 30), (4, 40), (5, 50), (6, 60)]; - - let mut map: HashMap<_, _> = xs.iter().cloned().collect(); - - // Existing key (insert) - match map.entry(1) { - Vacant(_) => unreachable!(), - Occupied(mut view) => { - assert_eq!(view.get(), &10); - assert_eq!(view.insert(100), 10); - } - } - assert_eq!(map.get(&1).unwrap(), &100); - assert_eq!(map.len(), 6); - - // Existing key (update) - match map.entry(2) { - Vacant(_) => unreachable!(), - Occupied(mut view) => { - let v = view.get_mut(); - let new_v = (*v) * 10; - *v = new_v; - } - } - assert_eq!(map.get(&2).unwrap(), &200); - assert_eq!(map.len(), 6); - - // Existing key (take) - match map.entry(3) { - Vacant(_) => unreachable!(), - Occupied(view) => { - assert_eq!(view.remove(), 30); - } - } - assert_eq!(map.get(&3), None); - assert_eq!(map.len(), 5); - - // Inexistent key (insert) - match map.entry(10) { - Occupied(_) => unreachable!(), - Vacant(view) => { - assert_eq!(*view.insert(1000), 1000); - } - } - assert_eq!(map.get(&10).unwrap(), &1000); - assert_eq!(map.len(), 6); -} - -#[test] -fn test_entry_take_doesnt_corrupt() { - #![allow(deprecated)] //rand - // Test for #19292 - fn check(m: &HashMap) { - for k in m.keys() { - assert!(m.contains_key(k), "{k} is in keys() but not in the map?"); - } - } - - let mut m = HashMap::new(); - let mut rng = test_rng(); - - // Populate the map with some items. - for _ in 0..50 { - let x = rng.gen_range(-10..10); - m.insert(x, ()); - } - - for _ in 0..1000 { - let x = rng.gen_range(-10..10); - match m.entry(x) { - Vacant(_) => {} - Occupied(e) => { - e.remove(); - } - } - - check(&m); - } -} - -#[test] -fn test_extend_ref() { - let mut a = HashMap::new(); - a.insert(1, "one"); - let mut b = HashMap::new(); - b.insert(2, "two"); - b.insert(3, "three"); - - a.extend(&b); - - assert_eq!(a.len(), 3); - assert_eq!(a[&1], "one"); - assert_eq!(a[&2], "two"); - assert_eq!(a[&3], "three"); -} - -#[test] -fn test_capacity_not_less_than_len() { - let mut a = HashMap::new(); - let mut item = 0; - - for _ in 0..116 { - a.insert(item, 0); - item += 1; - } - - assert!(a.capacity() > a.len()); - - let free = a.capacity() - a.len(); - for _ in 0..free { - a.insert(item, 0); - item += 1; - } - - assert_eq!(a.len(), a.capacity()); - - // Insert at capacity should cause allocation. - a.insert(item, 0); - assert!(a.capacity() > a.len()); -} - -#[test] -fn test_occupied_entry_key() { - let mut a = HashMap::new(); - let key = "hello there"; - let value = "value goes here"; - assert!(a.is_empty()); - a.insert(key, value); - assert_eq!(a.len(), 1); - assert_eq!(a[key], value); - - match a.entry(key) { - Vacant(_) => panic!(), - Occupied(e) => assert_eq!(key, *e.key()), - } - assert_eq!(a.len(), 1); - assert_eq!(a[key], value); -} - -#[test] -fn test_vacant_entry_key() { - let mut a = HashMap::new(); - let key = "hello there"; - let value = "value goes here"; - - assert!(a.is_empty()); - match a.entry(key) { - Occupied(_) => panic!(), - Vacant(e) => { - assert_eq!(key, *e.key()); - e.insert(value); - } - } - assert_eq!(a.len(), 1); - assert_eq!(a[key], value); -} - -#[test] -fn test_retain() { - let mut map: HashMap = (0..100).map(|x| (x, x * 10)).collect(); - - map.retain(|&k, _| k % 2 == 0); - assert_eq!(map.len(), 50); - assert_eq!(map[&2], 20); - assert_eq!(map[&4], 40); - assert_eq!(map[&6], 60); -} - -#[test] -#[cfg_attr(miri, ignore)] // Miri does not support signalling OOM -#[cfg_attr(target_os = "android", ignore)] // Android used in CI has a broken dlmalloc -fn test_try_reserve() { - let mut empty_bytes: HashMap = HashMap::new(); - - const MAX_USIZE: usize = usize::MAX; - - assert_matches!( - empty_bytes.try_reserve(MAX_USIZE).map_err(|e| e.kind()), - Err(CapacityOverflow), - "usize::MAX should trigger an overflow!" - ); - - if let Err(AllocError { .. }) = empty_bytes.try_reserve(MAX_USIZE / 16).map_err(|e| e.kind()) { - } else { - // This may succeed if there is enough free memory. Attempt to - // allocate a few more hashmaps to ensure the allocation will fail. - let mut empty_bytes2: HashMap = HashMap::new(); - let _ = empty_bytes2.try_reserve(MAX_USIZE / 16); - let mut empty_bytes3: HashMap = HashMap::new(); - let _ = empty_bytes3.try_reserve(MAX_USIZE / 16); - let mut empty_bytes4: HashMap = HashMap::new(); - assert_matches!( - empty_bytes4.try_reserve(MAX_USIZE / 16).map_err(|e| e.kind()), - Err(AllocError { .. }), - "usize::MAX / 16 should trigger an OOM!" - ); - } -} - -#[test] -fn test_raw_entry() { - use super::RawEntryMut::{Occupied, Vacant}; - - let xs = [(1i32, 10i32), (2, 20), (3, 30), (4, 40), (5, 50), (6, 60)]; - - let mut map: HashMap<_, _> = xs.iter().cloned().collect(); - - let compute_hash = |map: &HashMap, k: i32| -> u64 { - use core::hash::{BuildHasher, Hash, Hasher}; - - let mut hasher = map.hasher().build_hasher(); - k.hash(&mut hasher); - hasher.finish() - }; - - // Existing key (insert) - match map.raw_entry_mut().from_key(&1) { - Vacant(_) => unreachable!(), - Occupied(mut view) => { - assert_eq!(view.get(), &10); - assert_eq!(view.insert(100), 10); - } - } - let hash1 = compute_hash(&map, 1); - assert_eq!(map.raw_entry().from_key(&1).unwrap(), (&1, &100)); - assert_eq!(map.raw_entry().from_hash(hash1, |k| *k == 1).unwrap(), (&1, &100)); - assert_eq!(map.raw_entry().from_key_hashed_nocheck(hash1, &1).unwrap(), (&1, &100)); - assert_eq!(map.len(), 6); - - // Existing key (update) - match map.raw_entry_mut().from_key(&2) { - Vacant(_) => unreachable!(), - Occupied(mut view) => { - let v = view.get_mut(); - let new_v = (*v) * 10; - *v = new_v; - } - } - let hash2 = compute_hash(&map, 2); - assert_eq!(map.raw_entry().from_key(&2).unwrap(), (&2, &200)); - assert_eq!(map.raw_entry().from_hash(hash2, |k| *k == 2).unwrap(), (&2, &200)); - assert_eq!(map.raw_entry().from_key_hashed_nocheck(hash2, &2).unwrap(), (&2, &200)); - assert_eq!(map.len(), 6); - - // Existing key (take) - let hash3 = compute_hash(&map, 3); - match map.raw_entry_mut().from_key_hashed_nocheck(hash3, &3) { - Vacant(_) => unreachable!(), - Occupied(view) => { - assert_eq!(view.remove_entry(), (3, 30)); - } - } - assert_eq!(map.raw_entry().from_key(&3), None); - assert_eq!(map.raw_entry().from_hash(hash3, |k| *k == 3), None); - assert_eq!(map.raw_entry().from_key_hashed_nocheck(hash3, &3), None); - assert_eq!(map.len(), 5); - - // Nonexistent key (insert) - match map.raw_entry_mut().from_key(&10) { - Occupied(_) => unreachable!(), - Vacant(view) => { - assert_eq!(view.insert(10, 1000), (&mut 10, &mut 1000)); - } - } - assert_eq!(map.raw_entry().from_key(&10).unwrap(), (&10, &1000)); - assert_eq!(map.len(), 6); - - // Ensure all lookup methods produce equivalent results. - for k in 0..12 { - let hash = compute_hash(&map, k); - let v = map.get(&k).cloned(); - let kv = v.as_ref().map(|v| (&k, v)); - - assert_eq!(map.raw_entry().from_key(&k), kv); - assert_eq!(map.raw_entry().from_hash(hash, |q| *q == k), kv); - assert_eq!(map.raw_entry().from_key_hashed_nocheck(hash, &k), kv); - - match map.raw_entry_mut().from_key(&k) { - Occupied(mut o) => assert_eq!(Some(o.get_key_value()), kv), - Vacant(_) => assert_eq!(v, None), - } - match map.raw_entry_mut().from_key_hashed_nocheck(hash, &k) { - Occupied(mut o) => assert_eq!(Some(o.get_key_value()), kv), - Vacant(_) => assert_eq!(v, None), - } - match map.raw_entry_mut().from_hash(hash, |q| *q == k) { - Occupied(mut o) => assert_eq!(Some(o.get_key_value()), kv), - Vacant(_) => assert_eq!(v, None), - } - } -} - -mod test_extract_if { - use super::*; - - use crate::panic::{catch_unwind, AssertUnwindSafe}; - use crate::sync::atomic::{AtomicUsize, Ordering}; - - trait EqSorted: Iterator { - fn eq_sorted>(self, other: I) -> bool; - } - - impl EqSorted for T - where - T::Item: Eq + Ord, - { - fn eq_sorted>(self, other: I) -> bool { - let mut v: Vec<_> = self.collect(); - v.sort_unstable(); - v.into_iter().eq(other) - } - } - - #[test] - fn empty() { - let mut map: HashMap = HashMap::new(); - map.extract_if(|_, _| unreachable!("there's nothing to decide on")).for_each(drop); - assert!(map.is_empty()); - } - - #[test] - fn consuming_nothing() { - let pairs = (0..3).map(|i| (i, i)); - let mut map: HashMap<_, _> = pairs.collect(); - assert!(map.extract_if(|_, _| false).eq_sorted(crate::iter::empty())); - assert_eq!(map.len(), 3); - } - - #[test] - fn consuming_all() { - let pairs = (0..3).map(|i| (i, i)); - let mut map: HashMap<_, _> = pairs.clone().collect(); - assert!(map.extract_if(|_, _| true).eq_sorted(pairs)); - assert!(map.is_empty()); - } - - #[test] - fn mutating_and_keeping() { - let pairs = (0..3).map(|i| (i, i)); - let mut map: HashMap<_, _> = pairs.collect(); - assert!( - map.extract_if(|_, v| { - *v += 6; - false - }) - .eq_sorted(crate::iter::empty()) - ); - assert!(map.keys().copied().eq_sorted(0..3)); - assert!(map.values().copied().eq_sorted(6..9)); - } - - #[test] - fn mutating_and_removing() { - let pairs = (0..3).map(|i| (i, i)); - let mut map: HashMap<_, _> = pairs.collect(); - assert!( - map.extract_if(|_, v| { - *v += 6; - true - }) - .eq_sorted((0..3).map(|i| (i, i + 6))) - ); - assert!(map.is_empty()); - } - - #[test] - fn drop_panic_leak() { - static PREDS: AtomicUsize = AtomicUsize::new(0); - static DROPS: AtomicUsize = AtomicUsize::new(0); - - struct D; - impl Drop for D { - fn drop(&mut self) { - if DROPS.fetch_add(1, Ordering::SeqCst) == 1 { - panic!("panic in `drop`"); - } - } - } - - let mut map = (0..3).map(|i| (i, D)).collect::>(); - - catch_unwind(move || { - map.extract_if(|_, _| { - PREDS.fetch_add(1, Ordering::SeqCst); - true - }) - .for_each(drop) - }) - .unwrap_err(); - - assert_eq!(PREDS.load(Ordering::SeqCst), 2); - assert_eq!(DROPS.load(Ordering::SeqCst), 3); - } - - #[test] - fn pred_panic_leak() { - static PREDS: AtomicUsize = AtomicUsize::new(0); - static DROPS: AtomicUsize = AtomicUsize::new(0); - - struct D; - impl Drop for D { - fn drop(&mut self) { - DROPS.fetch_add(1, Ordering::SeqCst); - } - } - - let mut map = (0..3).map(|i| (i, D)).collect::>(); - - catch_unwind(AssertUnwindSafe(|| { - map.extract_if(|_, _| match PREDS.fetch_add(1, Ordering::SeqCst) { - 0 => true, - _ => panic!(), - }) - .for_each(drop) - })) - .unwrap_err(); - - assert_eq!(PREDS.load(Ordering::SeqCst), 2); - assert_eq!(DROPS.load(Ordering::SeqCst), 1); - assert_eq!(map.len(), 2); - } - - // Same as above, but attempt to use the iterator again after the panic in the predicate - #[test] - fn pred_panic_reuse() { - static PREDS: AtomicUsize = AtomicUsize::new(0); - static DROPS: AtomicUsize = AtomicUsize::new(0); - - struct D; - impl Drop for D { - fn drop(&mut self) { - DROPS.fetch_add(1, Ordering::SeqCst); - } - } - - let mut map = (0..3).map(|i| (i, D)).collect::>(); - - { - let mut it = map.extract_if(|_, _| match PREDS.fetch_add(1, Ordering::SeqCst) { - 0 => true, - _ => panic!(), - }); - catch_unwind(AssertUnwindSafe(|| while it.next().is_some() {})).unwrap_err(); - // Iterator behaviour after a panic is explicitly unspecified, - // so this is just the current implementation: - let result = catch_unwind(AssertUnwindSafe(|| it.next())); - assert!(result.is_err()); - } - - assert_eq!(PREDS.load(Ordering::SeqCst), 3); - assert_eq!(DROPS.load(Ordering::SeqCst), 1); - assert_eq!(map.len(), 2); - } -} - -#[test] -fn from_array() { - let map = HashMap::from([(1, 2), (3, 4)]); - let unordered_duplicates = HashMap::from([(3, 4), (1, 2), (1, 2)]); - assert_eq!(map, unordered_duplicates); - - // This next line must infer the hasher type parameter. - // If you make a change that causes this line to no longer infer, - // that's a problem! - let _must_not_require_type_annotation = HashMap::from([(1, 2)]); -} - -#[test] -fn const_with_hasher() { - const X: HashMap<(), (), ()> = HashMap::with_hasher(()); - assert_eq!(X.len(), 0); -} diff --git a/library/std/src/collections/hash/mod.rs b/library/std/src/collections/hash/mod.rs deleted file mode 100644 index 348820af54bff..0000000000000 --- a/library/std/src/collections/hash/mod.rs +++ /dev/null @@ -1,4 +0,0 @@ -//! Unordered containers, implemented as hash-tables - -pub mod map; -pub mod set; diff --git a/library/std/src/collections/hash/set.rs b/library/std/src/collections/hash/set.rs deleted file mode 100644 index f0a498fc7bbca..0000000000000 --- a/library/std/src/collections/hash/set.rs +++ /dev/null @@ -1,1916 +0,0 @@ -#[cfg(test)] -mod tests; - -use hashbrown::hash_set as base; - -use crate::borrow::Borrow; -use crate::collections::TryReserveError; -use crate::fmt; -use crate::hash::{BuildHasher, Hash, RandomState}; -use crate::iter::{Chain, FusedIterator}; -use crate::ops::{BitAnd, BitOr, BitXor, Sub}; - -use super::map::map_try_reserve_error; - -/// A [hash set] implemented as a `HashMap` where the value is `()`. -/// -/// As with the [`HashMap`] type, a `HashSet` requires that the elements -/// implement the [`Eq`] and [`Hash`] traits. This can frequently be achieved by -/// using `#[derive(PartialEq, Eq, Hash)]`. If you implement these yourself, -/// it is important that the following property holds: -/// -/// ```text -/// k1 == k2 -> hash(k1) == hash(k2) -/// ``` -/// -/// In other words, if two keys are equal, their hashes must be equal. -/// Violating this property is a logic error. -/// -/// It is also a logic error for a key to be modified in such a way that the key's -/// hash, as determined by the [`Hash`] trait, or its equality, as determined by -/// the [`Eq`] trait, changes while it is in the map. This is normally only -/// possible through [`Cell`], [`RefCell`], global state, I/O, or unsafe code. -/// -/// The behavior resulting from either logic error is not specified, but will -/// be encapsulated to the `HashSet` that observed the logic error and not -/// result in undefined behavior. This could include panics, incorrect results, -/// aborts, memory leaks, and non-termination. -/// -/// # Examples -/// -/// ``` -/// use std::collections::HashSet; -/// // Type inference lets us omit an explicit type signature (which -/// // would be `HashSet` in this example). -/// let mut books = HashSet::new(); -/// -/// // Add some books. -/// books.insert("A Dance With Dragons".to_string()); -/// books.insert("To Kill a Mockingbird".to_string()); -/// books.insert("The Odyssey".to_string()); -/// books.insert("The Great Gatsby".to_string()); -/// -/// // Check for a specific one. -/// if !books.contains("The Winds of Winter") { -/// println!("We have {} books, but The Winds of Winter ain't one.", -/// books.len()); -/// } -/// -/// // Remove a book. -/// books.remove("The Odyssey"); -/// -/// // Iterate over everything. -/// for book in &books { -/// println!("{book}"); -/// } -/// ``` -/// -/// The easiest way to use `HashSet` with a custom type is to derive -/// [`Eq`] and [`Hash`]. We must also derive [`PartialEq`], -/// which is required if [`Eq`] is derived. -/// -/// ``` -/// use std::collections::HashSet; -/// #[derive(Hash, Eq, PartialEq, Debug)] -/// struct Viking { -/// name: String, -/// power: usize, -/// } -/// -/// let mut vikings = HashSet::new(); -/// -/// vikings.insert(Viking { name: "Einar".to_string(), power: 9 }); -/// vikings.insert(Viking { name: "Einar".to_string(), power: 9 }); -/// vikings.insert(Viking { name: "Olaf".to_string(), power: 4 }); -/// vikings.insert(Viking { name: "Harald".to_string(), power: 8 }); -/// -/// // Use derived implementation to print the vikings. -/// for x in &vikings { -/// println!("{x:?}"); -/// } -/// ``` -/// -/// A `HashSet` with a known list of items can be initialized from an array: -/// -/// ``` -/// use std::collections::HashSet; -/// -/// let viking_names = HashSet::from(["Einar", "Olaf", "Harald"]); -/// ``` -/// -/// [hash set]: crate::collections#use-the-set-variant-of-any-of-these-maps-when -/// [`HashMap`]: crate::collections::HashMap -/// [`RefCell`]: crate::cell::RefCell -/// [`Cell`]: crate::cell::Cell -#[cfg_attr(not(test), rustc_diagnostic_item = "HashSet")] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct HashSet { - base: base::HashSet, -} - -impl HashSet { - /// Creates an empty `HashSet`. - /// - /// The hash set is initially created with a capacity of 0, so it will not allocate until it - /// is first inserted into. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// let set: HashSet = HashSet::new(); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn new() -> HashSet { - Default::default() - } - - /// Creates an empty `HashSet` with at least the specified capacity. - /// - /// The hash set will be able to hold at least `capacity` elements without - /// reallocating. This method is allowed to allocate for more elements than - /// `capacity`. If `capacity` is 0, the hash set will not allocate. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// let set: HashSet = HashSet::with_capacity(10); - /// assert!(set.capacity() >= 10); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn with_capacity(capacity: usize) -> HashSet { - HashSet::with_capacity_and_hasher(capacity, Default::default()) - } -} - -impl HashSet { - /// Returns the number of elements the set can hold without reallocating. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// let set: HashSet = HashSet::with_capacity(100); - /// assert!(set.capacity() >= 100); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn capacity(&self) -> usize { - self.base.capacity() - } - - /// An iterator visiting all elements in arbitrary order. - /// The iterator element type is `&'a T`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// let mut set = HashSet::new(); - /// set.insert("a"); - /// set.insert("b"); - /// - /// // Will print in an arbitrary order. - /// for x in set.iter() { - /// println!("{x}"); - /// } - /// ``` - /// - /// # Performance - /// - /// In the current implementation, iterating over set takes O(capacity) time - /// instead of O(len) because it internally visits empty buckets too. - #[inline] - #[rustc_lint_query_instability] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn iter(&self) -> Iter<'_, T> { - Iter { base: self.base.iter() } - } - - /// Returns the number of elements in the set. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// - /// let mut v = HashSet::new(); - /// assert_eq!(v.len(), 0); - /// v.insert(1); - /// assert_eq!(v.len(), 1); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn len(&self) -> usize { - self.base.len() - } - - /// Returns `true` if the set contains no elements. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// - /// let mut v = HashSet::new(); - /// assert!(v.is_empty()); - /// v.insert(1); - /// assert!(!v.is_empty()); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn is_empty(&self) -> bool { - self.base.is_empty() - } - - /// Clears the set, returning all elements as an iterator. Keeps the - /// allocated memory for reuse. - /// - /// If the returned iterator is dropped before being fully consumed, it - /// drops the remaining elements. The returned iterator keeps a mutable - /// borrow on the set to optimize its implementation. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// - /// let mut set = HashSet::from([1, 2, 3]); - /// assert!(!set.is_empty()); - /// - /// // print 1, 2, 3 in an arbitrary order - /// for i in set.drain() { - /// println!("{i}"); - /// } - /// - /// assert!(set.is_empty()); - /// ``` - #[inline] - #[rustc_lint_query_instability] - #[stable(feature = "drain", since = "1.6.0")] - pub fn drain(&mut self) -> Drain<'_, T> { - Drain { base: self.base.drain() } - } - - /// Creates an iterator which uses a closure to determine if a value should be removed. - /// - /// If the closure returns true, then the value is removed and yielded. - /// If the closure returns false, the value will remain in the list and will not be yielded - /// by the iterator. - /// - /// If the returned `ExtractIf` is not exhausted, e.g. because it is dropped without iterating - /// or the iteration short-circuits, then the remaining elements will be retained. - /// Use [`retain`] with a negated predicate if you do not need the returned iterator. - /// - /// [`retain`]: HashSet::retain - /// - /// # Examples - /// - /// Splitting a set into even and odd values, reusing the original set: - /// - /// ``` - /// #![feature(hash_extract_if)] - /// use std::collections::HashSet; - /// - /// let mut set: HashSet = (0..8).collect(); - /// let extracted: HashSet = set.extract_if(|v| v % 2 == 0).collect(); - /// - /// let mut evens = extracted.into_iter().collect::>(); - /// let mut odds = set.into_iter().collect::>(); - /// evens.sort(); - /// odds.sort(); - /// - /// assert_eq!(evens, vec![0, 2, 4, 6]); - /// assert_eq!(odds, vec![1, 3, 5, 7]); - /// ``` - #[inline] - #[rustc_lint_query_instability] - #[unstable(feature = "hash_extract_if", issue = "59618")] - pub fn extract_if(&mut self, pred: F) -> ExtractIf<'_, T, F> - where - F: FnMut(&T) -> bool, - { - ExtractIf { base: self.base.extract_if(pred) } - } - - /// Retains only the elements specified by the predicate. - /// - /// In other words, remove all elements `e` for which `f(&e)` returns `false`. - /// The elements are visited in unsorted (and unspecified) order. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// - /// let mut set = HashSet::from([1, 2, 3, 4, 5, 6]); - /// set.retain(|&k| k % 2 == 0); - /// assert_eq!(set, HashSet::from([2, 4, 6])); - /// ``` - /// - /// # Performance - /// - /// In the current implementation, this operation takes O(capacity) time - /// instead of O(len) because it internally visits empty buckets too. - #[rustc_lint_query_instability] - #[stable(feature = "retain_hash_collection", since = "1.18.0")] - pub fn retain(&mut self, f: F) - where - F: FnMut(&T) -> bool, - { - self.base.retain(f) - } - - /// Clears the set, removing all values. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// - /// let mut v = HashSet::new(); - /// v.insert(1); - /// v.clear(); - /// assert!(v.is_empty()); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn clear(&mut self) { - self.base.clear() - } - - /// Creates a new empty hash set which will use the given hasher to hash - /// keys. - /// - /// The hash set is also created with the default initial capacity. - /// - /// Warning: `hasher` is normally randomly generated, and - /// is designed to allow `HashSet`s to be resistant to attacks that - /// cause many collisions and very poor performance. Setting it - /// manually using this function can expose a DoS attack vector. - /// - /// The `hash_builder` passed should implement the [`BuildHasher`] trait for - /// the HashMap to be useful, see its documentation for details. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// use std::hash::RandomState; - /// - /// let s = RandomState::new(); - /// let mut set = HashSet::with_hasher(s); - /// set.insert(2); - /// ``` - #[inline] - #[stable(feature = "hashmap_build_hasher", since = "1.7.0")] - #[rustc_const_unstable(feature = "const_collections_with_hasher", issue = "102575")] - pub const fn with_hasher(hasher: S) -> HashSet { - HashSet { base: base::HashSet::with_hasher(hasher) } - } - - /// Creates an empty `HashSet` with at least the specified capacity, using - /// `hasher` to hash the keys. - /// - /// The hash set will be able to hold at least `capacity` elements without - /// reallocating. This method is allowed to allocate for more elements than - /// `capacity`. If `capacity` is 0, the hash set will not allocate. - /// - /// Warning: `hasher` is normally randomly generated, and - /// is designed to allow `HashSet`s to be resistant to attacks that - /// cause many collisions and very poor performance. Setting it - /// manually using this function can expose a DoS attack vector. - /// - /// The `hash_builder` passed should implement the [`BuildHasher`] trait for - /// the HashMap to be useful, see its documentation for details. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// use std::hash::RandomState; - /// - /// let s = RandomState::new(); - /// let mut set = HashSet::with_capacity_and_hasher(10, s); - /// set.insert(1); - /// ``` - #[inline] - #[stable(feature = "hashmap_build_hasher", since = "1.7.0")] - pub fn with_capacity_and_hasher(capacity: usize, hasher: S) -> HashSet { - HashSet { base: base::HashSet::with_capacity_and_hasher(capacity, hasher) } - } - - /// Returns a reference to the set's [`BuildHasher`]. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// use std::hash::RandomState; - /// - /// let hasher = RandomState::new(); - /// let set: HashSet = HashSet::with_hasher(hasher); - /// let hasher: &RandomState = set.hasher(); - /// ``` - #[inline] - #[stable(feature = "hashmap_public_hasher", since = "1.9.0")] - pub fn hasher(&self) -> &S { - self.base.hasher() - } -} - -impl HashSet -where - T: Eq + Hash, - S: BuildHasher, -{ - /// Reserves capacity for at least `additional` more elements to be inserted - /// in the `HashSet`. The collection may reserve more space to speculatively - /// avoid frequent reallocations. After calling `reserve`, - /// capacity will be greater than or equal to `self.len() + additional`. - /// Does nothing if capacity is already sufficient. - /// - /// # Panics - /// - /// Panics if the new allocation size overflows `usize`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// let mut set: HashSet = HashSet::new(); - /// set.reserve(10); - /// assert!(set.capacity() >= 10); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn reserve(&mut self, additional: usize) { - self.base.reserve(additional) - } - - /// Tries to reserve capacity for at least `additional` more elements to be inserted - /// in the `HashSet`. The collection may reserve more space to speculatively - /// avoid frequent reallocations. After calling `try_reserve`, - /// capacity will be greater than or equal to `self.len() + additional` if - /// it returns `Ok(())`. - /// Does nothing if capacity is already sufficient. - /// - /// # Errors - /// - /// If the capacity overflows, or the allocator reports a failure, then an error - /// is returned. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// let mut set: HashSet = HashSet::new(); - /// set.try_reserve(10).expect("why is the test harness OOMing on a handful of bytes?"); - /// ``` - #[inline] - #[stable(feature = "try_reserve", since = "1.57.0")] - pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> { - self.base.try_reserve(additional).map_err(map_try_reserve_error) - } - - /// Shrinks the capacity of the set as much as possible. It will drop - /// down as much as possible while maintaining the internal rules - /// and possibly leaving some space in accordance with the resize policy. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// - /// let mut set = HashSet::with_capacity(100); - /// set.insert(1); - /// set.insert(2); - /// assert!(set.capacity() >= 100); - /// set.shrink_to_fit(); - /// assert!(set.capacity() >= 2); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn shrink_to_fit(&mut self) { - self.base.shrink_to_fit() - } - - /// Shrinks the capacity of the set with a lower limit. It will drop - /// down no lower than the supplied limit while maintaining the internal rules - /// and possibly leaving some space in accordance with the resize policy. - /// - /// If the current capacity is less than the lower limit, this is a no-op. - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// - /// let mut set = HashSet::with_capacity(100); - /// set.insert(1); - /// set.insert(2); - /// assert!(set.capacity() >= 100); - /// set.shrink_to(10); - /// assert!(set.capacity() >= 10); - /// set.shrink_to(0); - /// assert!(set.capacity() >= 2); - /// ``` - #[inline] - #[stable(feature = "shrink_to", since = "1.56.0")] - pub fn shrink_to(&mut self, min_capacity: usize) { - self.base.shrink_to(min_capacity) - } - - /// Visits the values representing the difference, - /// i.e., the values that are in `self` but not in `other`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// let a = HashSet::from([1, 2, 3]); - /// let b = HashSet::from([4, 2, 3, 4]); - /// - /// // Can be seen as `a - b`. - /// for x in a.difference(&b) { - /// println!("{x}"); // Print 1 - /// } - /// - /// let diff: HashSet<_> = a.difference(&b).collect(); - /// assert_eq!(diff, [1].iter().collect()); - /// - /// // Note that difference is not symmetric, - /// // and `b - a` means something else: - /// let diff: HashSet<_> = b.difference(&a).collect(); - /// assert_eq!(diff, [4].iter().collect()); - /// ``` - #[inline] - #[rustc_lint_query_instability] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn difference<'a>(&'a self, other: &'a HashSet) -> Difference<'a, T, S> { - Difference { iter: self.iter(), other } - } - - /// Visits the values representing the symmetric difference, - /// i.e., the values that are in `self` or in `other` but not in both. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// let a = HashSet::from([1, 2, 3]); - /// let b = HashSet::from([4, 2, 3, 4]); - /// - /// // Print 1, 4 in arbitrary order. - /// for x in a.symmetric_difference(&b) { - /// println!("{x}"); - /// } - /// - /// let diff1: HashSet<_> = a.symmetric_difference(&b).collect(); - /// let diff2: HashSet<_> = b.symmetric_difference(&a).collect(); - /// - /// assert_eq!(diff1, diff2); - /// assert_eq!(diff1, [1, 4].iter().collect()); - /// ``` - #[inline] - #[rustc_lint_query_instability] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn symmetric_difference<'a>( - &'a self, - other: &'a HashSet, - ) -> SymmetricDifference<'a, T, S> { - SymmetricDifference { iter: self.difference(other).chain(other.difference(self)) } - } - - /// Visits the values representing the intersection, - /// i.e., the values that are both in `self` and `other`. - /// - /// When an equal element is present in `self` and `other` - /// then the resulting `Intersection` may yield references to - /// one or the other. This can be relevant if `T` contains fields which - /// are not compared by its `Eq` implementation, and may hold different - /// value between the two equal copies of `T` in the two sets. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// let a = HashSet::from([1, 2, 3]); - /// let b = HashSet::from([4, 2, 3, 4]); - /// - /// // Print 2, 3 in arbitrary order. - /// for x in a.intersection(&b) { - /// println!("{x}"); - /// } - /// - /// let intersection: HashSet<_> = a.intersection(&b).collect(); - /// assert_eq!(intersection, [2, 3].iter().collect()); - /// ``` - #[inline] - #[rustc_lint_query_instability] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn intersection<'a>(&'a self, other: &'a HashSet) -> Intersection<'a, T, S> { - if self.len() <= other.len() { - Intersection { iter: self.iter(), other } - } else { - Intersection { iter: other.iter(), other: self } - } - } - - /// Visits the values representing the union, - /// i.e., all the values in `self` or `other`, without duplicates. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// let a = HashSet::from([1, 2, 3]); - /// let b = HashSet::from([4, 2, 3, 4]); - /// - /// // Print 1, 2, 3, 4 in arbitrary order. - /// for x in a.union(&b) { - /// println!("{x}"); - /// } - /// - /// let union: HashSet<_> = a.union(&b).collect(); - /// assert_eq!(union, [1, 2, 3, 4].iter().collect()); - /// ``` - #[inline] - #[rustc_lint_query_instability] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn union<'a>(&'a self, other: &'a HashSet) -> Union<'a, T, S> { - if self.len() >= other.len() { - Union { iter: self.iter().chain(other.difference(self)) } - } else { - Union { iter: other.iter().chain(self.difference(other)) } - } - } - - /// Returns `true` if the set contains a value. - /// - /// The value may be any borrowed form of the set's value type, but - /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for - /// the value type. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// - /// let set = HashSet::from([1, 2, 3]); - /// assert_eq!(set.contains(&1), true); - /// assert_eq!(set.contains(&4), false); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn contains(&self, value: &Q) -> bool - where - T: Borrow, - Q: Hash + Eq, - { - self.base.contains(value) - } - - /// Returns a reference to the value in the set, if any, that is equal to the given value. - /// - /// The value may be any borrowed form of the set's value type, but - /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for - /// the value type. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// - /// let set = HashSet::from([1, 2, 3]); - /// assert_eq!(set.get(&2), Some(&2)); - /// assert_eq!(set.get(&4), None); - /// ``` - #[inline] - #[stable(feature = "set_recovery", since = "1.9.0")] - pub fn get(&self, value: &Q) -> Option<&T> - where - T: Borrow, - Q: Hash + Eq, - { - self.base.get(value) - } - - /// Inserts the given `value` into the set if it is not present, then - /// returns a reference to the value in the set. - /// - /// # Examples - /// - /// ``` - /// #![feature(hash_set_entry)] - /// - /// use std::collections::HashSet; - /// - /// let mut set = HashSet::from([1, 2, 3]); - /// assert_eq!(set.len(), 3); - /// assert_eq!(set.get_or_insert(2), &2); - /// assert_eq!(set.get_or_insert(100), &100); - /// assert_eq!(set.len(), 4); // 100 was inserted - /// ``` - #[inline] - #[unstable(feature = "hash_set_entry", issue = "60896")] - pub fn get_or_insert(&mut self, value: T) -> &T { - // Although the raw entry gives us `&mut T`, we only return `&T` to be consistent with - // `get`. Key mutation is "raw" because you're not supposed to affect `Eq` or `Hash`. - self.base.get_or_insert(value) - } - - /// Inserts an owned copy of the given `value` into the set if it is not - /// present, then returns a reference to the value in the set. - /// - /// # Examples - /// - /// ``` - /// #![feature(hash_set_entry)] - /// - /// use std::collections::HashSet; - /// - /// let mut set: HashSet = ["cat", "dog", "horse"] - /// .iter().map(|&pet| pet.to_owned()).collect(); - /// - /// assert_eq!(set.len(), 3); - /// for &pet in &["cat", "dog", "fish"] { - /// let value = set.get_or_insert_owned(pet); - /// assert_eq!(value, pet); - /// } - /// assert_eq!(set.len(), 4); // a new "fish" was inserted - /// ``` - #[inline] - #[unstable(feature = "hash_set_entry", issue = "60896")] - pub fn get_or_insert_owned(&mut self, value: &Q) -> &T - where - T: Borrow, - Q: Hash + Eq + ToOwned, - { - // Although the raw entry gives us `&mut T`, we only return `&T` to be consistent with - // `get`. Key mutation is "raw" because you're not supposed to affect `Eq` or `Hash`. - self.base.get_or_insert_owned(value) - } - - /// Inserts a value computed from `f` into the set if the given `value` is - /// not present, then returns a reference to the value in the set. - /// - /// # Examples - /// - /// ``` - /// #![feature(hash_set_entry)] - /// - /// use std::collections::HashSet; - /// - /// let mut set: HashSet = ["cat", "dog", "horse"] - /// .iter().map(|&pet| pet.to_owned()).collect(); - /// - /// assert_eq!(set.len(), 3); - /// for &pet in &["cat", "dog", "fish"] { - /// let value = set.get_or_insert_with(pet, str::to_owned); - /// assert_eq!(value, pet); - /// } - /// assert_eq!(set.len(), 4); // a new "fish" was inserted - /// ``` - #[inline] - #[unstable(feature = "hash_set_entry", issue = "60896")] - pub fn get_or_insert_with(&mut self, value: &Q, f: F) -> &T - where - T: Borrow, - Q: Hash + Eq, - F: FnOnce(&Q) -> T, - { - // Although the raw entry gives us `&mut T`, we only return `&T` to be consistent with - // `get`. Key mutation is "raw" because you're not supposed to affect `Eq` or `Hash`. - self.base.get_or_insert_with(value, f) - } - - /// Returns `true` if `self` has no elements in common with `other`. - /// This is equivalent to checking for an empty intersection. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// - /// let a = HashSet::from([1, 2, 3]); - /// let mut b = HashSet::new(); - /// - /// assert_eq!(a.is_disjoint(&b), true); - /// b.insert(4); - /// assert_eq!(a.is_disjoint(&b), true); - /// b.insert(1); - /// assert_eq!(a.is_disjoint(&b), false); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn is_disjoint(&self, other: &HashSet) -> bool { - if self.len() <= other.len() { - self.iter().all(|v| !other.contains(v)) - } else { - other.iter().all(|v| !self.contains(v)) - } - } - - /// Returns `true` if the set is a subset of another, - /// i.e., `other` contains at least all the values in `self`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// - /// let sup = HashSet::from([1, 2, 3]); - /// let mut set = HashSet::new(); - /// - /// assert_eq!(set.is_subset(&sup), true); - /// set.insert(2); - /// assert_eq!(set.is_subset(&sup), true); - /// set.insert(4); - /// assert_eq!(set.is_subset(&sup), false); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn is_subset(&self, other: &HashSet) -> bool { - if self.len() <= other.len() { self.iter().all(|v| other.contains(v)) } else { false } - } - - /// Returns `true` if the set is a superset of another, - /// i.e., `self` contains at least all the values in `other`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// - /// let sub = HashSet::from([1, 2]); - /// let mut set = HashSet::new(); - /// - /// assert_eq!(set.is_superset(&sub), false); - /// - /// set.insert(0); - /// set.insert(1); - /// assert_eq!(set.is_superset(&sub), false); - /// - /// set.insert(2); - /// assert_eq!(set.is_superset(&sub), true); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn is_superset(&self, other: &HashSet) -> bool { - other.is_subset(self) - } - - /// Adds a value to the set. - /// - /// Returns whether the value was newly inserted. That is: - /// - /// - If the set did not previously contain this value, `true` is returned. - /// - If the set already contained this value, `false` is returned, - /// and the set is not modified: original value is not replaced, - /// and the value passed as argument is dropped. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// - /// let mut set = HashSet::new(); - /// - /// assert_eq!(set.insert(2), true); - /// assert_eq!(set.insert(2), false); - /// assert_eq!(set.len(), 1); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("push", "append", "put")] - pub fn insert(&mut self, value: T) -> bool { - self.base.insert(value) - } - - /// Adds a value to the set, replacing the existing value, if any, that is equal to the given - /// one. Returns the replaced value. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// - /// let mut set = HashSet::new(); - /// set.insert(Vec::::new()); - /// - /// assert_eq!(set.get(&[][..]).unwrap().capacity(), 0); - /// set.replace(Vec::with_capacity(10)); - /// assert_eq!(set.get(&[][..]).unwrap().capacity(), 10); - /// ``` - #[inline] - #[stable(feature = "set_recovery", since = "1.9.0")] - #[rustc_confusables("swap")] - pub fn replace(&mut self, value: T) -> Option { - self.base.replace(value) - } - - /// Removes a value from the set. Returns whether the value was - /// present in the set. - /// - /// The value may be any borrowed form of the set's value type, but - /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for - /// the value type. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// - /// let mut set = HashSet::new(); - /// - /// set.insert(2); - /// assert_eq!(set.remove(&2), true); - /// assert_eq!(set.remove(&2), false); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("delete", "take")] - pub fn remove(&mut self, value: &Q) -> bool - where - T: Borrow, - Q: Hash + Eq, - { - self.base.remove(value) - } - - /// Removes and returns the value in the set, if any, that is equal to the given one. - /// - /// The value may be any borrowed form of the set's value type, but - /// [`Hash`] and [`Eq`] on the borrowed form *must* match those for - /// the value type. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// - /// let mut set = HashSet::from([1, 2, 3]); - /// assert_eq!(set.take(&2), Some(2)); - /// assert_eq!(set.take(&2), None); - /// ``` - #[inline] - #[stable(feature = "set_recovery", since = "1.9.0")] - pub fn take(&mut self, value: &Q) -> Option - where - T: Borrow, - Q: Hash + Eq, - { - self.base.take(value) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for HashSet -where - T: Clone, - S: Clone, -{ - #[inline] - fn clone(&self) -> Self { - Self { base: self.base.clone() } - } - - /// Overwrites the contents of `self` with a clone of the contents of `source`. - /// - /// This method is preferred over simply assigning `source.clone()` to `self`, - /// as it avoids reallocation if possible. - #[inline] - fn clone_from(&mut self, other: &Self) { - self.base.clone_from(&other.base); - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for HashSet -where - T: Eq + Hash, - S: BuildHasher, -{ - fn eq(&self, other: &HashSet) -> bool { - if self.len() != other.len() { - return false; - } - - self.iter().all(|key| other.contains(key)) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Eq for HashSet -where - T: Eq + Hash, - S: BuildHasher, -{ -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for HashSet -where - T: fmt::Debug, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_set().entries(self.iter()).finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl FromIterator for HashSet -where - T: Eq + Hash, - S: BuildHasher + Default, -{ - #[inline] - fn from_iter>(iter: I) -> HashSet { - let mut set = HashSet::with_hasher(Default::default()); - set.extend(iter); - set - } -} - -#[stable(feature = "std_collections_from_array", since = "1.56.0")] -// Note: as what is currently the most convenient built-in way to construct -// a HashSet, a simple usage of this function must not *require* the user -// to provide a type annotation in order to infer the third type parameter -// (the hasher parameter, conventionally "S"). -// To that end, this impl is defined using RandomState as the concrete -// type of S, rather than being generic over `S: BuildHasher + Default`. -// It is expected that users who want to specify a hasher will manually use -// `with_capacity_and_hasher`. -// If type parameter defaults worked on impls, and if type parameter -// defaults could be mixed with const generics, then perhaps -// this could be generalized. -// See also the equivalent impl on HashMap. -impl From<[T; N]> for HashSet -where - T: Eq + Hash, -{ - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// - /// let set1 = HashSet::from([1, 2, 3, 4]); - /// let set2: HashSet<_> = [1, 2, 3, 4].into(); - /// assert_eq!(set1, set2); - /// ``` - fn from(arr: [T; N]) -> Self { - Self::from_iter(arr) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Extend for HashSet -where - T: Eq + Hash, - S: BuildHasher, -{ - #[inline] - fn extend>(&mut self, iter: I) { - self.base.extend(iter); - } - - #[inline] - fn extend_one(&mut self, item: T) { - self.base.insert(item); - } - - #[inline] - fn extend_reserve(&mut self, additional: usize) { - self.base.extend_reserve(additional); - } -} - -#[stable(feature = "hash_extend_copy", since = "1.4.0")] -impl<'a, T, S> Extend<&'a T> for HashSet -where - T: 'a + Eq + Hash + Copy, - S: BuildHasher, -{ - #[inline] - fn extend>(&mut self, iter: I) { - self.extend(iter.into_iter().cloned()); - } - - #[inline] - fn extend_one(&mut self, &item: &'a T) { - self.base.insert(item); - } - - #[inline] - fn extend_reserve(&mut self, additional: usize) { - Extend::::extend_reserve(self, additional) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Default for HashSet -where - S: Default, -{ - /// Creates an empty `HashSet` with the `Default` value for the hasher. - #[inline] - fn default() -> HashSet { - HashSet { base: Default::default() } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl BitOr<&HashSet> for &HashSet -where - T: Eq + Hash + Clone, - S: BuildHasher + Default, -{ - type Output = HashSet; - - /// Returns the union of `self` and `rhs` as a new `HashSet`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// - /// let a = HashSet::from([1, 2, 3]); - /// let b = HashSet::from([3, 4, 5]); - /// - /// let set = &a | &b; - /// - /// let mut i = 0; - /// let expected = [1, 2, 3, 4, 5]; - /// for x in &set { - /// assert!(expected.contains(x)); - /// i += 1; - /// } - /// assert_eq!(i, expected.len()); - /// ``` - fn bitor(self, rhs: &HashSet) -> HashSet { - self.union(rhs).cloned().collect() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl BitAnd<&HashSet> for &HashSet -where - T: Eq + Hash + Clone, - S: BuildHasher + Default, -{ - type Output = HashSet; - - /// Returns the intersection of `self` and `rhs` as a new `HashSet`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// - /// let a = HashSet::from([1, 2, 3]); - /// let b = HashSet::from([2, 3, 4]); - /// - /// let set = &a & &b; - /// - /// let mut i = 0; - /// let expected = [2, 3]; - /// for x in &set { - /// assert!(expected.contains(x)); - /// i += 1; - /// } - /// assert_eq!(i, expected.len()); - /// ``` - fn bitand(self, rhs: &HashSet) -> HashSet { - self.intersection(rhs).cloned().collect() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl BitXor<&HashSet> for &HashSet -where - T: Eq + Hash + Clone, - S: BuildHasher + Default, -{ - type Output = HashSet; - - /// Returns the symmetric difference of `self` and `rhs` as a new `HashSet`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// - /// let a = HashSet::from([1, 2, 3]); - /// let b = HashSet::from([3, 4, 5]); - /// - /// let set = &a ^ &b; - /// - /// let mut i = 0; - /// let expected = [1, 2, 4, 5]; - /// for x in &set { - /// assert!(expected.contains(x)); - /// i += 1; - /// } - /// assert_eq!(i, expected.len()); - /// ``` - fn bitxor(self, rhs: &HashSet) -> HashSet { - self.symmetric_difference(rhs).cloned().collect() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Sub<&HashSet> for &HashSet -where - T: Eq + Hash + Clone, - S: BuildHasher + Default, -{ - type Output = HashSet; - - /// Returns the difference of `self` and `rhs` as a new `HashSet`. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// - /// let a = HashSet::from([1, 2, 3]); - /// let b = HashSet::from([3, 4, 5]); - /// - /// let set = &a - &b; - /// - /// let mut i = 0; - /// let expected = [1, 2]; - /// for x in &set { - /// assert!(expected.contains(x)); - /// i += 1; - /// } - /// assert_eq!(i, expected.len()); - /// ``` - fn sub(self, rhs: &HashSet) -> HashSet { - self.difference(rhs).cloned().collect() - } -} - -/// An iterator over the items of a `HashSet`. -/// -/// This `struct` is created by the [`iter`] method on [`HashSet`]. -/// See its documentation for more. -/// -/// [`iter`]: HashSet::iter -/// -/// # Examples -/// -/// ``` -/// use std::collections::HashSet; -/// -/// let a = HashSet::from([1, 2, 3]); -/// -/// let mut iter = a.iter(); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Iter<'a, K: 'a> { - base: base::Iter<'a, K>, -} - -/// An owning iterator over the items of a `HashSet`. -/// -/// This `struct` is created by the [`into_iter`] method on [`HashSet`] -/// (provided by the [`IntoIterator`] trait). See its documentation for more. -/// -/// [`into_iter`]: IntoIterator::into_iter -/// -/// # Examples -/// -/// ``` -/// use std::collections::HashSet; -/// -/// let a = HashSet::from([1, 2, 3]); -/// -/// let mut iter = a.into_iter(); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub struct IntoIter { - base: base::IntoIter, -} - -/// A draining iterator over the items of a `HashSet`. -/// -/// This `struct` is created by the [`drain`] method on [`HashSet`]. -/// See its documentation for more. -/// -/// [`drain`]: HashSet::drain -/// -/// # Examples -/// -/// ``` -/// use std::collections::HashSet; -/// -/// let mut a = HashSet::from([1, 2, 3]); -/// -/// let mut drain = a.drain(); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Drain<'a, K: 'a> { - base: base::Drain<'a, K>, -} - -/// A draining, filtering iterator over the items of a `HashSet`. -/// -/// This `struct` is created by the [`extract_if`] method on [`HashSet`]. -/// -/// [`extract_if`]: HashSet::extract_if -/// -/// # Examples -/// -/// ``` -/// #![feature(hash_extract_if)] -/// -/// use std::collections::HashSet; -/// -/// let mut a = HashSet::from([1, 2, 3]); -/// -/// let mut extract_ifed = a.extract_if(|v| v % 2 == 0); -/// ``` -#[unstable(feature = "hash_extract_if", issue = "59618")] -pub struct ExtractIf<'a, K, F> -where - F: FnMut(&K) -> bool, -{ - base: base::ExtractIf<'a, K, F>, -} - -/// A lazy iterator producing elements in the intersection of `HashSet`s. -/// -/// This `struct` is created by the [`intersection`] method on [`HashSet`]. -/// See its documentation for more. -/// -/// [`intersection`]: HashSet::intersection -/// -/// # Examples -/// -/// ``` -/// use std::collections::HashSet; -/// -/// let a = HashSet::from([1, 2, 3]); -/// let b = HashSet::from([4, 2, 3, 4]); -/// -/// let mut intersection = a.intersection(&b); -/// ``` -#[must_use = "this returns the intersection as an iterator, \ - without modifying either input set"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Intersection<'a, T: 'a, S: 'a> { - // iterator of the first set - iter: Iter<'a, T>, - // the second set - other: &'a HashSet, -} - -/// A lazy iterator producing elements in the difference of `HashSet`s. -/// -/// This `struct` is created by the [`difference`] method on [`HashSet`]. -/// See its documentation for more. -/// -/// [`difference`]: HashSet::difference -/// -/// # Examples -/// -/// ``` -/// use std::collections::HashSet; -/// -/// let a = HashSet::from([1, 2, 3]); -/// let b = HashSet::from([4, 2, 3, 4]); -/// -/// let mut difference = a.difference(&b); -/// ``` -#[must_use = "this returns the difference as an iterator, \ - without modifying either input set"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Difference<'a, T: 'a, S: 'a> { - // iterator of the first set - iter: Iter<'a, T>, - // the second set - other: &'a HashSet, -} - -/// A lazy iterator producing elements in the symmetric difference of `HashSet`s. -/// -/// This `struct` is created by the [`symmetric_difference`] method on -/// [`HashSet`]. See its documentation for more. -/// -/// [`symmetric_difference`]: HashSet::symmetric_difference -/// -/// # Examples -/// -/// ``` -/// use std::collections::HashSet; -/// -/// let a = HashSet::from([1, 2, 3]); -/// let b = HashSet::from([4, 2, 3, 4]); -/// -/// let mut intersection = a.symmetric_difference(&b); -/// ``` -#[must_use = "this returns the difference as an iterator, \ - without modifying either input set"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct SymmetricDifference<'a, T: 'a, S: 'a> { - iter: Chain, Difference<'a, T, S>>, -} - -/// A lazy iterator producing elements in the union of `HashSet`s. -/// -/// This `struct` is created by the [`union`] method on [`HashSet`]. -/// See its documentation for more. -/// -/// [`union`]: HashSet::union -/// -/// # Examples -/// -/// ``` -/// use std::collections::HashSet; -/// -/// let a = HashSet::from([1, 2, 3]); -/// let b = HashSet::from([4, 2, 3, 4]); -/// -/// let mut union_iter = a.union(&b); -/// ``` -#[must_use = "this returns the union as an iterator, \ - without modifying either input set"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Union<'a, T: 'a, S: 'a> { - iter: Chain, Difference<'a, T, S>>, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T, S> IntoIterator for &'a HashSet { - type Item = &'a T; - type IntoIter = Iter<'a, T>; - - #[inline] - #[rustc_lint_query_instability] - fn into_iter(self) -> Iter<'a, T> { - self.iter() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl IntoIterator for HashSet { - type Item = T; - type IntoIter = IntoIter; - - /// Creates a consuming iterator, that is, one that moves each value out - /// of the set in arbitrary order. The set cannot be used after calling - /// this. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// let mut set = HashSet::new(); - /// set.insert("a".to_string()); - /// set.insert("b".to_string()); - /// - /// // Not possible to collect to a Vec with a regular `.iter()`. - /// let v: Vec = set.into_iter().collect(); - /// - /// // Will print in an arbitrary order. - /// for x in &v { - /// println!("{x}"); - /// } - /// ``` - #[inline] - #[rustc_lint_query_instability] - fn into_iter(self) -> IntoIter { - IntoIter { base: self.base.into_iter() } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Iter<'_, K> { - #[inline] - fn clone(&self) -> Self { - Iter { base: self.base.clone() } - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, K> Iterator for Iter<'a, K> { - type Item = &'a K; - - #[inline] - fn next(&mut self) -> Option<&'a K> { - self.base.next() - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.base.size_hint() - } - #[inline] - fn count(self) -> usize { - self.base.len() - } - #[inline] - fn fold(self, init: B, f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - self.base.fold(init, f) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Iter<'_, K> { - #[inline] - fn len(&self) -> usize { - self.base.len() - } -} -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Iter<'_, K> {} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for Iter<'_, K> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.clone()).finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for IntoIter { - type Item = K; - - #[inline] - fn next(&mut self) -> Option { - self.base.next() - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.base.size_hint() - } - #[inline] - fn count(self) -> usize { - self.base.len() - } - #[inline] - fn fold(self, init: B, f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - self.base.fold(init, f) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for IntoIter { - #[inline] - fn len(&self) -> usize { - self.base.len() - } -} -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for IntoIter {} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for IntoIter { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&self.base, f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, K> Iterator for Drain<'a, K> { - type Item = K; - - #[inline] - fn next(&mut self) -> Option { - self.base.next() - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.base.size_hint() - } - #[inline] - fn fold(self, init: B, f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - self.base.fold(init, f) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for Drain<'_, K> { - #[inline] - fn len(&self) -> usize { - self.base.len() - } -} -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Drain<'_, K> {} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for Drain<'_, K> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&self.base, f) - } -} - -#[unstable(feature = "hash_extract_if", issue = "59618")] -impl Iterator for ExtractIf<'_, K, F> -where - F: FnMut(&K) -> bool, -{ - type Item = K; - - #[inline] - fn next(&mut self) -> Option { - self.base.next() - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.base.size_hint() - } -} - -#[unstable(feature = "hash_extract_if", issue = "59618")] -impl FusedIterator for ExtractIf<'_, K, F> where F: FnMut(&K) -> bool {} - -#[unstable(feature = "hash_extract_if", issue = "59618")] -impl<'a, K, F> fmt::Debug for ExtractIf<'a, K, F> -where - F: FnMut(&K) -> bool, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("ExtractIf").finish_non_exhaustive() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Intersection<'_, T, S> { - #[inline] - fn clone(&self) -> Self { - Intersection { iter: self.iter.clone(), ..*self } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T, S> Iterator for Intersection<'a, T, S> -where - T: Eq + Hash, - S: BuildHasher, -{ - type Item = &'a T; - - #[inline] - fn next(&mut self) -> Option<&'a T> { - loop { - let elt = self.iter.next()?; - if self.other.contains(elt) { - return Some(elt); - } - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let (_, upper) = self.iter.size_hint(); - (0, upper) - } - - #[inline] - fn fold(self, init: B, mut f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - self.iter.fold(init, |acc, elt| if self.other.contains(elt) { f(acc, elt) } else { acc }) - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for Intersection<'_, T, S> -where - T: fmt::Debug + Eq + Hash, - S: BuildHasher, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.clone()).finish() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Intersection<'_, T, S> -where - T: Eq + Hash, - S: BuildHasher, -{ -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Difference<'_, T, S> { - #[inline] - fn clone(&self) -> Self { - Difference { iter: self.iter.clone(), ..*self } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T, S> Iterator for Difference<'a, T, S> -where - T: Eq + Hash, - S: BuildHasher, -{ - type Item = &'a T; - - #[inline] - fn next(&mut self) -> Option<&'a T> { - loop { - let elt = self.iter.next()?; - if !self.other.contains(elt) { - return Some(elt); - } - } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let (_, upper) = self.iter.size_hint(); - (0, upper) - } - - #[inline] - fn fold(self, init: B, mut f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - self.iter.fold(init, |acc, elt| if self.other.contains(elt) { acc } else { f(acc, elt) }) - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Difference<'_, T, S> -where - T: Eq + Hash, - S: BuildHasher, -{ -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for Difference<'_, T, S> -where - T: fmt::Debug + Eq + Hash, - S: BuildHasher, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.clone()).finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for SymmetricDifference<'_, T, S> { - #[inline] - fn clone(&self) -> Self { - SymmetricDifference { iter: self.iter.clone() } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T, S> Iterator for SymmetricDifference<'a, T, S> -where - T: Eq + Hash, - S: BuildHasher, -{ - type Item = &'a T; - - #[inline] - fn next(&mut self) -> Option<&'a T> { - self.iter.next() - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } - #[inline] - fn fold(self, init: B, f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - self.iter.fold(init, f) - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for SymmetricDifference<'_, T, S> -where - T: Eq + Hash, - S: BuildHasher, -{ -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for SymmetricDifference<'_, T, S> -where - T: fmt::Debug + Eq + Hash, - S: BuildHasher, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.clone()).finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Union<'_, T, S> { - #[inline] - fn clone(&self) -> Self { - Union { iter: self.iter.clone() } - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Union<'_, T, S> -where - T: Eq + Hash, - S: BuildHasher, -{ -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for Union<'_, T, S> -where - T: fmt::Debug + Eq + Hash, - S: BuildHasher, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.clone()).finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T, S> Iterator for Union<'a, T, S> -where - T: Eq + Hash, - S: BuildHasher, -{ - type Item = &'a T; - - #[inline] - fn next(&mut self) -> Option<&'a T> { - self.iter.next() - } - #[inline] - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } - #[inline] - fn count(self) -> usize { - self.iter.count() - } - #[inline] - fn fold(self, init: B, f: F) -> B - where - Self: Sized, - F: FnMut(B, Self::Item) -> B, - { - self.iter.fold(init, f) - } -} - -#[allow(dead_code)] -fn assert_covariance() { - fn set<'new>(v: HashSet<&'static str>) -> HashSet<&'new str> { - v - } - fn iter<'a, 'new>(v: Iter<'a, &'static str>) -> Iter<'a, &'new str> { - v - } - fn into_iter<'new>(v: IntoIter<&'static str>) -> IntoIter<&'new str> { - v - } - fn difference<'a, 'new>( - v: Difference<'a, &'static str, RandomState>, - ) -> Difference<'a, &'new str, RandomState> { - v - } - fn symmetric_difference<'a, 'new>( - v: SymmetricDifference<'a, &'static str, RandomState>, - ) -> SymmetricDifference<'a, &'new str, RandomState> { - v - } - fn intersection<'a, 'new>( - v: Intersection<'a, &'static str, RandomState>, - ) -> Intersection<'a, &'new str, RandomState> { - v - } - fn union<'a, 'new>( - v: Union<'a, &'static str, RandomState>, - ) -> Union<'a, &'new str, RandomState> { - v - } - fn drain<'new>(d: Drain<'static, &'static str>) -> Drain<'new, &'new str> { - d - } -} diff --git a/library/std/src/collections/hash/set/tests.rs b/library/std/src/collections/hash/set/tests.rs deleted file mode 100644 index a188409004305..0000000000000 --- a/library/std/src/collections/hash/set/tests.rs +++ /dev/null @@ -1,526 +0,0 @@ -use super::HashSet; - -use crate::hash::RandomState; -use crate::panic::{catch_unwind, AssertUnwindSafe}; -use crate::sync::atomic::{AtomicU32, Ordering}; -use crate::sync::Arc; - -#[test] -fn test_zero_capacities() { - type HS = HashSet; - - let s = HS::new(); - assert_eq!(s.capacity(), 0); - - let s = HS::default(); - assert_eq!(s.capacity(), 0); - - let s = HS::with_hasher(RandomState::new()); - assert_eq!(s.capacity(), 0); - - let s = HS::with_capacity(0); - assert_eq!(s.capacity(), 0); - - let s = HS::with_capacity_and_hasher(0, RandomState::new()); - assert_eq!(s.capacity(), 0); - - let mut s = HS::new(); - s.insert(1); - s.insert(2); - s.remove(&1); - s.remove(&2); - s.shrink_to_fit(); - assert_eq!(s.capacity(), 0); - - let mut s = HS::new(); - s.reserve(0); - assert_eq!(s.capacity(), 0); -} - -#[test] -fn test_disjoint() { - let mut xs = HashSet::new(); - let mut ys = HashSet::new(); - assert!(xs.is_disjoint(&ys)); - assert!(ys.is_disjoint(&xs)); - assert!(xs.insert(5)); - assert!(ys.insert(11)); - assert!(xs.is_disjoint(&ys)); - assert!(ys.is_disjoint(&xs)); - assert!(xs.insert(7)); - assert!(xs.insert(19)); - assert!(xs.insert(4)); - assert!(ys.insert(2)); - assert!(ys.insert(-11)); - assert!(xs.is_disjoint(&ys)); - assert!(ys.is_disjoint(&xs)); - assert!(ys.insert(7)); - assert!(!xs.is_disjoint(&ys)); - assert!(!ys.is_disjoint(&xs)); -} - -#[test] -fn test_subset_and_superset() { - let mut a = HashSet::new(); - assert!(a.insert(0)); - assert!(a.insert(5)); - assert!(a.insert(11)); - assert!(a.insert(7)); - - let mut b = HashSet::new(); - assert!(b.insert(0)); - assert!(b.insert(7)); - assert!(b.insert(19)); - assert!(b.insert(250)); - assert!(b.insert(11)); - assert!(b.insert(200)); - - assert!(!a.is_subset(&b)); - assert!(!a.is_superset(&b)); - assert!(!b.is_subset(&a)); - assert!(!b.is_superset(&a)); - - assert!(b.insert(5)); - - assert!(a.is_subset(&b)); - assert!(!a.is_superset(&b)); - assert!(!b.is_subset(&a)); - assert!(b.is_superset(&a)); -} - -#[test] -fn test_iterate() { - let mut a = HashSet::new(); - for i in 0..32 { - assert!(a.insert(i)); - } - let mut observed: u32 = 0; - for k in &a { - observed |= 1 << *k; - } - assert_eq!(observed, 0xFFFF_FFFF); -} - -#[test] -fn test_intersection() { - let mut a = HashSet::new(); - let mut b = HashSet::new(); - assert!(a.intersection(&b).next().is_none()); - - assert!(a.insert(11)); - assert!(a.insert(1)); - assert!(a.insert(3)); - assert!(a.insert(77)); - assert!(a.insert(103)); - assert!(a.insert(5)); - assert!(a.insert(-5)); - - assert!(b.insert(2)); - assert!(b.insert(11)); - assert!(b.insert(77)); - assert!(b.insert(-9)); - assert!(b.insert(-42)); - assert!(b.insert(5)); - assert!(b.insert(3)); - - let mut i = 0; - let expected = [3, 5, 11, 77]; - for x in a.intersection(&b) { - assert!(expected.contains(x)); - i += 1 - } - assert_eq!(i, expected.len()); - - assert!(a.insert(9)); // make a bigger than b - - i = 0; - for x in a.intersection(&b) { - assert!(expected.contains(x)); - i += 1 - } - assert_eq!(i, expected.len()); - - i = 0; - for x in b.intersection(&a) { - assert!(expected.contains(x)); - i += 1 - } - assert_eq!(i, expected.len()); -} - -#[test] -fn test_difference() { - let mut a = HashSet::new(); - let mut b = HashSet::new(); - - assert!(a.insert(1)); - assert!(a.insert(3)); - assert!(a.insert(5)); - assert!(a.insert(9)); - assert!(a.insert(11)); - - assert!(b.insert(3)); - assert!(b.insert(9)); - - let mut i = 0; - let expected = [1, 5, 11]; - for x in a.difference(&b) { - assert!(expected.contains(x)); - i += 1 - } - assert_eq!(i, expected.len()); -} - -#[test] -fn test_symmetric_difference() { - let mut a = HashSet::new(); - let mut b = HashSet::new(); - - assert!(a.insert(1)); - assert!(a.insert(3)); - assert!(a.insert(5)); - assert!(a.insert(9)); - assert!(a.insert(11)); - - assert!(b.insert(-2)); - assert!(b.insert(3)); - assert!(b.insert(9)); - assert!(b.insert(14)); - assert!(b.insert(22)); - - let mut i = 0; - let expected = [-2, 1, 5, 11, 14, 22]; - for x in a.symmetric_difference(&b) { - assert!(expected.contains(x)); - i += 1 - } - assert_eq!(i, expected.len()); -} - -#[test] -fn test_union() { - let mut a = HashSet::new(); - let mut b = HashSet::new(); - assert!(a.union(&b).next().is_none()); - assert!(b.union(&a).next().is_none()); - - assert!(a.insert(1)); - assert!(a.insert(3)); - assert!(a.insert(11)); - assert!(a.insert(16)); - assert!(a.insert(19)); - assert!(a.insert(24)); - - assert!(b.insert(-2)); - assert!(b.insert(1)); - assert!(b.insert(5)); - assert!(b.insert(9)); - assert!(b.insert(13)); - assert!(b.insert(19)); - - let mut i = 0; - let expected = [-2, 1, 3, 5, 9, 11, 13, 16, 19, 24]; - for x in a.union(&b) { - assert!(expected.contains(x)); - i += 1 - } - assert_eq!(i, expected.len()); - - assert!(a.insert(9)); // make a bigger than b - assert!(a.insert(5)); - - i = 0; - for x in a.union(&b) { - assert!(expected.contains(x)); - i += 1 - } - assert_eq!(i, expected.len()); - - i = 0; - for x in b.union(&a) { - assert!(expected.contains(x)); - i += 1 - } - assert_eq!(i, expected.len()); -} - -#[test] -fn test_from_iter() { - let xs = [1, 2, 2, 3, 4, 5, 6, 7, 8, 9]; - - let set: HashSet<_> = xs.iter().cloned().collect(); - - for x in &xs { - assert!(set.contains(x)); - } - - assert_eq!(set.iter().len(), xs.len() - 1); -} - -#[test] -fn test_move_iter() { - let hs = { - let mut hs = HashSet::new(); - - hs.insert('a'); - hs.insert('b'); - - hs - }; - - let v = hs.into_iter().collect::>(); - assert!(v == ['a', 'b'] || v == ['b', 'a']); -} - -#[test] -fn test_eq() { - // These constants once happened to expose a bug in insert(). - // I'm keeping them around to prevent a regression. - let mut s1 = HashSet::new(); - - s1.insert(1); - s1.insert(2); - s1.insert(3); - - let mut s2 = HashSet::new(); - - s2.insert(1); - s2.insert(2); - - assert!(s1 != s2); - - s2.insert(3); - - assert_eq!(s1, s2); -} - -#[test] -fn test_show() { - let mut set = HashSet::new(); - let empty = HashSet::::new(); - - set.insert(1); - set.insert(2); - - let set_str = format!("{set:?}"); - - assert!(set_str == "{1, 2}" || set_str == "{2, 1}"); - assert_eq!(format!("{empty:?}"), "{}"); -} - -#[test] -fn test_trivial_drain() { - let mut s = HashSet::::new(); - for _ in s.drain() {} - assert!(s.is_empty()); - drop(s); - - let mut s = HashSet::::new(); - drop(s.drain()); - assert!(s.is_empty()); -} - -#[test] -fn test_drain() { - let mut s: HashSet<_> = (1..100).collect(); - - // try this a bunch of times to make sure we don't screw up internal state. - for _ in 0..20 { - assert_eq!(s.len(), 99); - - { - let mut last_i = 0; - let mut d = s.drain(); - for (i, x) in d.by_ref().take(50).enumerate() { - last_i = i; - assert!(x != 0); - } - assert_eq!(last_i, 49); - } - - for _ in &s { - panic!("s should be empty!"); - } - - // reset to try again. - s.extend(1..100); - } -} - -#[test] -fn test_replace() { - use crate::hash; - - #[derive(Debug)] - struct Foo(&'static str, #[allow(dead_code)] i32); - - impl PartialEq for Foo { - fn eq(&self, other: &Self) -> bool { - self.0 == other.0 - } - } - - impl Eq for Foo {} - - impl hash::Hash for Foo { - fn hash(&self, h: &mut H) { - self.0.hash(h); - } - } - - let mut s = HashSet::new(); - assert_eq!(s.replace(Foo("a", 1)), None); - assert_eq!(s.len(), 1); - assert_eq!(s.replace(Foo("a", 2)), Some(Foo("a", 1))); - assert_eq!(s.len(), 1); - - let mut it = s.iter(); - assert_eq!(it.next(), Some(&Foo("a", 2))); - assert_eq!(it.next(), None); -} - -#[test] -fn test_extend_ref() { - let mut a = HashSet::new(); - a.insert(1); - - a.extend(&[2, 3, 4]); - - assert_eq!(a.len(), 4); - assert!(a.contains(&1)); - assert!(a.contains(&2)); - assert!(a.contains(&3)); - assert!(a.contains(&4)); - - let mut b = HashSet::new(); - b.insert(5); - b.insert(6); - - a.extend(&b); - - assert_eq!(a.len(), 6); - assert!(a.contains(&1)); - assert!(a.contains(&2)); - assert!(a.contains(&3)); - assert!(a.contains(&4)); - assert!(a.contains(&5)); - assert!(a.contains(&6)); -} - -#[test] -fn test_retain() { - let xs = [1, 2, 3, 4, 5, 6]; - let mut set: HashSet = xs.iter().cloned().collect(); - set.retain(|&k| k % 2 == 0); - assert_eq!(set.len(), 3); - assert!(set.contains(&2)); - assert!(set.contains(&4)); - assert!(set.contains(&6)); -} - -#[test] -fn test_extract_if() { - let mut x: HashSet<_> = [1].iter().copied().collect(); - let mut y: HashSet<_> = [1].iter().copied().collect(); - - x.extract_if(|_| true).for_each(drop); - y.extract_if(|_| false).for_each(drop); - assert_eq!(x.len(), 0); - assert_eq!(y.len(), 1); -} - -#[test] -fn test_extract_if_drop_panic_leak() { - static PREDS: AtomicU32 = AtomicU32::new(0); - static DROPS: AtomicU32 = AtomicU32::new(0); - - #[derive(PartialEq, Eq, PartialOrd, Hash)] - struct D(i32); - impl Drop for D { - fn drop(&mut self) { - if DROPS.fetch_add(1, Ordering::SeqCst) == 1 { - panic!("panic in `drop`"); - } - } - } - - let mut set = (0..3).map(|i| D(i)).collect::>(); - - catch_unwind(move || { - set.extract_if(|_| { - PREDS.fetch_add(1, Ordering::SeqCst); - true - }) - .for_each(drop) - }) - .ok(); - - assert_eq!(PREDS.load(Ordering::SeqCst), 2); - assert_eq!(DROPS.load(Ordering::SeqCst), 3); -} - -#[test] -fn test_extract_if_pred_panic_leak() { - static PREDS: AtomicU32 = AtomicU32::new(0); - static DROPS: AtomicU32 = AtomicU32::new(0); - - #[derive(PartialEq, Eq, PartialOrd, Hash)] - struct D; - impl Drop for D { - fn drop(&mut self) { - DROPS.fetch_add(1, Ordering::SeqCst); - } - } - - let mut set: HashSet<_> = (0..3).map(|_| D).collect(); - - catch_unwind(AssertUnwindSafe(|| { - set.extract_if(|_| match PREDS.fetch_add(1, Ordering::SeqCst) { - 0 => true, - _ => panic!(), - }) - .for_each(drop) - })) - .ok(); - - assert_eq!(PREDS.load(Ordering::SeqCst), 1); - assert_eq!(DROPS.load(Ordering::SeqCst), 3); - assert_eq!(set.len(), 0); -} - -#[test] -fn from_array() { - let set = HashSet::from([1, 2, 3, 4]); - let unordered_duplicates = HashSet::from([4, 1, 4, 3, 2]); - assert_eq!(set, unordered_duplicates); - - // This next line must infer the hasher type parameter. - // If you make a change that causes this line to no longer infer, - // that's a problem! - let _must_not_require_type_annotation = HashSet::from([1, 2]); -} - -#[test] -fn const_with_hasher() { - const X: HashSet<(), ()> = HashSet::with_hasher(()); - assert_eq!(X.len(), 0); -} - -#[test] -fn test_insert_does_not_overwrite_the_value() { - let first_value = Arc::new(17); - let second_value = Arc::new(17); - - let mut set = HashSet::new(); - let inserted = set.insert(first_value.clone()); - assert!(inserted); - - let inserted = set.insert(second_value); - assert!(!inserted); - - assert!( - Arc::ptr_eq(set.iter().next().unwrap(), &first_value), - "Insert must not overwrite the value, so the contained value pointer \ - must be the same as first value pointer we inserted" - ); -} diff --git a/library/std/src/collections/mod.rs b/library/std/src/collections/mod.rs deleted file mode 100644 index 1389d24a8c519..0000000000000 --- a/library/std/src/collections/mod.rs +++ /dev/null @@ -1,454 +0,0 @@ -//! Collection types. -//! -//! Rust's standard collection library provides efficient implementations of the -//! most common general purpose programming data structures. By using the -//! standard implementations, it should be possible for two libraries to -//! communicate without significant data conversion. -//! -//! To get this out of the way: you should probably just use [`Vec`] or [`HashMap`]. -//! These two collections cover most use cases for generic data storage and -//! processing. They are exceptionally good at doing what they do. All the other -//! collections in the standard library have specific use cases where they are -//! the optimal choice, but these cases are borderline *niche* in comparison. -//! Even when `Vec` and `HashMap` are technically suboptimal, they're probably a -//! good enough choice to get started. -//! -//! Rust's collections can be grouped into four major categories: -//! -//! * Sequences: [`Vec`], [`VecDeque`], [`LinkedList`] -//! * Maps: [`HashMap`], [`BTreeMap`] -//! * Sets: [`HashSet`], [`BTreeSet`] -//! * Misc: [`BinaryHeap`] -//! -//! # When Should You Use Which Collection? -//! -//! These are fairly high-level and quick break-downs of when each collection -//! should be considered. Detailed discussions of strengths and weaknesses of -//! individual collections can be found on their own documentation pages. -//! -//! ### Use a `Vec` when: -//! * You want to collect items up to be processed or sent elsewhere later, and -//! don't care about any properties of the actual values being stored. -//! * You want a sequence of elements in a particular order, and will only be -//! appending to (or near) the end. -//! * You want a stack. -//! * You want a resizable array. -//! * You want a heap-allocated array. -//! -//! ### Use a `VecDeque` when: -//! * You want a [`Vec`] that supports efficient insertion at both ends of the -//! sequence. -//! * You want a queue. -//! * You want a double-ended queue (deque). -//! -//! ### Use a `LinkedList` when: -//! * You want a [`Vec`] or [`VecDeque`] of unknown size, and can't tolerate -//! amortization. -//! * You want to efficiently split and append lists. -//! * You are *absolutely* certain you *really*, *truly*, want a doubly linked -//! list. -//! -//! ### Use a `HashMap` when: -//! * You want to associate arbitrary keys with an arbitrary value. -//! * You want a cache. -//! * You want a map, with no extra functionality. -//! -//! ### Use a `BTreeMap` when: -//! * You want a map sorted by its keys. -//! * You want to be able to get a range of entries on-demand. -//! * You're interested in what the smallest or largest key-value pair is. -//! * You want to find the largest or smallest key that is smaller or larger -//! than something. -//! -//! ### Use the `Set` variant of any of these `Map`s when: -//! * You just want to remember which keys you've seen. -//! * There is no meaningful value to associate with your keys. -//! * You just want a set. -//! -//! ### Use a `BinaryHeap` when: -//! -//! * You want to store a bunch of elements, but only ever want to process the -//! "biggest" or "most important" one at any given time. -//! * You want a priority queue. -//! -//! # Performance -//! -//! Choosing the right collection for the job requires an understanding of what -//! each collection is good at. Here we briefly summarize the performance of -//! different collections for certain important operations. For further details, -//! see each type's documentation, and note that the names of actual methods may -//! differ from the tables below on certain collections. -//! -//! Throughout the documentation, we will follow a few conventions. For all -//! operations, the collection's size is denoted by n. If another collection is -//! involved in the operation, it contains m elements. Operations which have an -//! *amortized* cost are suffixed with a `*`. Operations with an *expected* -//! cost are suffixed with a `~`. -//! -//! All amortized costs are for the potential need to resize when capacity is -//! exhausted. If a resize occurs it will take *O*(*n*) time. Our collections never -//! automatically shrink, so removal operations aren't amortized. Over a -//! sufficiently large series of operations, the average cost per operation will -//! deterministically equal the given cost. -//! -//! Only [`HashMap`] has expected costs, due to the probabilistic nature of hashing. -//! It is theoretically possible, though very unlikely, for [`HashMap`] to -//! experience worse performance. -//! -//! ## Sequences -//! -//! | | get(i) | insert(i) | remove(i) | append | split_off(i) | -//! |----------------|------------------------|-------------------------|------------------------|-----------|------------------------| -//! | [`Vec`] | *O*(1) | *O*(*n*-*i*)* | *O*(*n*-*i*) | *O*(*m*)* | *O*(*n*-*i*) | -//! | [`VecDeque`] | *O*(1) | *O*(min(*i*, *n*-*i*))* | *O*(min(*i*, *n*-*i*)) | *O*(*m*)* | *O*(min(*i*, *n*-*i*)) | -//! | [`LinkedList`] | *O*(min(*i*, *n*-*i*)) | *O*(min(*i*, *n*-*i*)) | *O*(min(*i*, *n*-*i*)) | *O*(1) | *O*(min(*i*, *n*-*i*)) | -//! -//! Note that where ties occur, [`Vec`] is generally going to be faster than [`VecDeque`], and -//! [`VecDeque`] is generally going to be faster than [`LinkedList`]. -//! -//! ## Maps -//! -//! For Sets, all operations have the cost of the equivalent Map operation. -//! -//! | | get | insert | remove | range | append | -//! |--------------|---------------|---------------|---------------|---------------|--------------| -//! | [`HashMap`] | *O*(1)~ | *O*(1)~* | *O*(1)~ | N/A | N/A | -//! | [`BTreeMap`] | *O*(log(*n*)) | *O*(log(*n*)) | *O*(log(*n*)) | *O*(log(*n*)) | *O*(*n*+*m*) | -//! -//! # Correct and Efficient Usage of Collections -//! -//! Of course, knowing which collection is the right one for the job doesn't -//! instantly permit you to use it correctly. Here are some quick tips for -//! efficient and correct usage of the standard collections in general. If -//! you're interested in how to use a specific collection in particular, consult -//! its documentation for detailed discussion and code examples. -//! -//! ## Capacity Management -//! -//! Many collections provide several constructors and methods that refer to -//! "capacity". These collections are generally built on top of an array. -//! Optimally, this array would be exactly the right size to fit only the -//! elements stored in the collection, but for the collection to do this would -//! be very inefficient. If the backing array was exactly the right size at all -//! times, then every time an element is inserted, the collection would have to -//! grow the array to fit it. Due to the way memory is allocated and managed on -//! most computers, this would almost surely require allocating an entirely new -//! array and copying every single element from the old one into the new one. -//! Hopefully you can see that this wouldn't be very efficient to do on every -//! operation. -//! -//! Most collections therefore use an *amortized* allocation strategy. They -//! generally let themselves have a fair amount of unoccupied space so that they -//! only have to grow on occasion. When they do grow, they allocate a -//! substantially larger array to move the elements into so that it will take a -//! while for another grow to be required. While this strategy is great in -//! general, it would be even better if the collection *never* had to resize its -//! backing array. Unfortunately, the collection itself doesn't have enough -//! information to do this itself. Therefore, it is up to us programmers to give -//! it hints. -//! -//! Any `with_capacity` constructor will instruct the collection to allocate -//! enough space for the specified number of elements. Ideally this will be for -//! exactly that many elements, but some implementation details may prevent -//! this. See collection-specific documentation for details. In general, use -//! `with_capacity` when you know exactly how many elements will be inserted, or -//! at least have a reasonable upper-bound on that number. -//! -//! When anticipating a large influx of elements, the `reserve` family of -//! methods can be used to hint to the collection how much room it should make -//! for the coming items. As with `with_capacity`, the precise behavior of -//! these methods will be specific to the collection of interest. -//! -//! For optimal performance, collections will generally avoid shrinking -//! themselves. If you believe that a collection will not soon contain any more -//! elements, or just really need the memory, the `shrink_to_fit` method prompts -//! the collection to shrink the backing array to the minimum size capable of -//! holding its elements. -//! -//! Finally, if ever you're interested in what the actual capacity of the -//! collection is, most collections provide a `capacity` method to query this -//! information on demand. This can be useful for debugging purposes, or for -//! use with the `reserve` methods. -//! -//! ## Iterators -//! -//! [Iterators][crate::iter] -//! are a powerful and robust mechanism used throughout Rust's -//! standard libraries. Iterators provide a sequence of values in a generic, -//! safe, efficient and convenient way. The contents of an iterator are usually -//! *lazily* evaluated, so that only the values that are actually needed are -//! ever actually produced, and no allocation need be done to temporarily store -//! them. Iterators are primarily consumed using a `for` loop, although many -//! functions also take iterators where a collection or sequence of values is -//! desired. -//! -//! All of the standard collections provide several iterators for performing -//! bulk manipulation of their contents. The three primary iterators almost -//! every collection should provide are `iter`, `iter_mut`, and `into_iter`. -//! Some of these are not provided on collections where it would be unsound or -//! unreasonable to provide them. -//! -//! `iter` provides an iterator of immutable references to all the contents of a -//! collection in the most "natural" order. For sequence collections like [`Vec`], -//! this means the items will be yielded in increasing order of index starting -//! at 0. For ordered collections like [`BTreeMap`], this means that the items -//! will be yielded in sorted order. For unordered collections like [`HashMap`], -//! the items will be yielded in whatever order the internal representation made -//! most convenient. This is great for reading through all the contents of the -//! collection. -//! -//! ``` -//! let vec = vec![1, 2, 3, 4]; -//! for x in vec.iter() { -//! println!("vec contained {x:?}"); -//! } -//! ``` -//! -//! `iter_mut` provides an iterator of *mutable* references in the same order as -//! `iter`. This is great for mutating all the contents of the collection. -//! -//! ``` -//! let mut vec = vec![1, 2, 3, 4]; -//! for x in vec.iter_mut() { -//! *x += 1; -//! } -//! ``` -//! -//! `into_iter` transforms the actual collection into an iterator over its -//! contents by-value. This is great when the collection itself is no longer -//! needed, and the values are needed elsewhere. Using `extend` with `into_iter` -//! is the main way that contents of one collection are moved into another. -//! `extend` automatically calls `into_iter`, and takes any T: [IntoIterator]. -//! Calling `collect` on an iterator itself is also a great way to convert one -//! collection into another. Both of these methods should internally use the -//! capacity management tools discussed in the previous section to do this as -//! efficiently as possible. -//! -//! ``` -//! let mut vec1 = vec![1, 2, 3, 4]; -//! let vec2 = vec![10, 20, 30, 40]; -//! vec1.extend(vec2); -//! ``` -//! -//! ``` -//! use std::collections::VecDeque; -//! -//! let vec = [1, 2, 3, 4]; -//! let buf: VecDeque<_> = vec.into_iter().collect(); -//! ``` -//! -//! Iterators also provide a series of *adapter* methods for performing common -//! threads to sequences. Among the adapters are functional favorites like `map`, -//! `fold`, `skip` and `take`. Of particular interest to collections is the -//! `rev` adapter, which reverses any iterator that supports this operation. Most -//! collections provide reversible iterators as the way to iterate over them in -//! reverse order. -//! -//! ``` -//! let vec = vec![1, 2, 3, 4]; -//! for x in vec.iter().rev() { -//! println!("vec contained {x:?}"); -//! } -//! ``` -//! -//! Several other collection methods also return iterators to yield a sequence -//! of results but avoid allocating an entire collection to store the result in. -//! This provides maximum flexibility as -//! [`collect`][crate::iter::Iterator::collect] or -//! [`extend`][crate::iter::Extend::extend] can be called to -//! "pipe" the sequence into any collection if desired. Otherwise, the sequence -//! can be looped over with a `for` loop. The iterator can also be discarded -//! after partial use, preventing the computation of the unused items. -//! -//! ## Entries -//! -//! The `entry` API is intended to provide an efficient mechanism for -//! manipulating the contents of a map conditionally on the presence of a key or -//! not. The primary motivating use case for this is to provide efficient -//! accumulator maps. For instance, if one wishes to maintain a count of the -//! number of times each key has been seen, they will have to perform some -//! conditional logic on whether this is the first time the key has been seen or -//! not. Normally, this would require a `find` followed by an `insert`, -//! effectively duplicating the search effort on each insertion. -//! -//! When a user calls `map.entry(key)`, the map will search for the key and -//! then yield a variant of the `Entry` enum. -//! -//! If a `Vacant(entry)` is yielded, then the key *was not* found. In this case -//! the only valid operation is to `insert` a value into the entry. When this is -//! done, the vacant entry is consumed and converted into a mutable reference to -//! the value that was inserted. This allows for further manipulation of the -//! value beyond the lifetime of the search itself. This is useful if complex -//! logic needs to be performed on the value regardless of whether the value was -//! just inserted. -//! -//! If an `Occupied(entry)` is yielded, then the key *was* found. In this case, -//! the user has several options: they can `get`, `insert` or `remove` the -//! value of the occupied entry. Additionally, they can convert the occupied -//! entry into a mutable reference to its value, providing symmetry to the -//! vacant `insert` case. -//! -//! ### Examples -//! -//! Here are the two primary ways in which `entry` is used. First, a simple -//! example where the logic performed on the values is trivial. -//! -//! #### Counting the number of times each character in a string occurs -//! -//! ``` -//! use std::collections::btree_map::BTreeMap; -//! -//! let mut count = BTreeMap::new(); -//! let message = "she sells sea shells by the sea shore"; -//! -//! for c in message.chars() { -//! *count.entry(c).or_insert(0) += 1; -//! } -//! -//! assert_eq!(count.get(&'s'), Some(&8)); -//! -//! println!("Number of occurrences of each character"); -//! for (char, count) in &count { -//! println!("{char}: {count}"); -//! } -//! ``` -//! -//! When the logic to be performed on the value is more complex, we may simply -//! use the `entry` API to ensure that the value is initialized and perform the -//! logic afterwards. -//! -//! #### Tracking the inebriation of customers at a bar -//! -//! ``` -//! use std::collections::btree_map::BTreeMap; -//! -//! // A client of the bar. They have a blood alcohol level. -//! struct Person { blood_alcohol: f32 } -//! -//! // All the orders made to the bar, by client ID. -//! let orders = vec![1, 2, 1, 2, 3, 4, 1, 2, 2, 3, 4, 1, 1, 1]; -//! -//! // Our clients. -//! let mut blood_alcohol = BTreeMap::new(); -//! -//! for id in orders { -//! // If this is the first time we've seen this customer, initialize them -//! // with no blood alcohol. Otherwise, just retrieve them. -//! let person = blood_alcohol.entry(id).or_insert(Person { blood_alcohol: 0.0 }); -//! -//! // Reduce their blood alcohol level. It takes time to order and drink a beer! -//! person.blood_alcohol *= 0.9; -//! -//! // Check if they're sober enough to have another beer. -//! if person.blood_alcohol > 0.3 { -//! // Too drunk... for now. -//! println!("Sorry {id}, I have to cut you off"); -//! } else { -//! // Have another! -//! person.blood_alcohol += 0.1; -//! } -//! } -//! ``` -//! -//! # Insert and complex keys -//! -//! If we have a more complex key, calls to `insert` will -//! not update the value of the key. For example: -//! -//! ``` -//! use std::cmp::Ordering; -//! use std::collections::BTreeMap; -//! use std::hash::{Hash, Hasher}; -//! -//! #[derive(Debug)] -//! struct Foo { -//! a: u32, -//! b: &'static str, -//! } -//! -//! // we will compare `Foo`s by their `a` value only. -//! impl PartialEq for Foo { -//! fn eq(&self, other: &Self) -> bool { self.a == other.a } -//! } -//! -//! impl Eq for Foo {} -//! -//! // we will hash `Foo`s by their `a` value only. -//! impl Hash for Foo { -//! fn hash(&self, h: &mut H) { self.a.hash(h); } -//! } -//! -//! impl PartialOrd for Foo { -//! fn partial_cmp(&self, other: &Self) -> Option { self.a.partial_cmp(&other.a) } -//! } -//! -//! impl Ord for Foo { -//! fn cmp(&self, other: &Self) -> Ordering { self.a.cmp(&other.a) } -//! } -//! -//! let mut map = BTreeMap::new(); -//! map.insert(Foo { a: 1, b: "baz" }, 99); -//! -//! // We already have a Foo with an a of 1, so this will be updating the value. -//! map.insert(Foo { a: 1, b: "xyz" }, 100); -//! -//! // The value has been updated... -//! assert_eq!(map.values().next().unwrap(), &100); -//! -//! // ...but the key hasn't changed. b is still "baz", not "xyz". -//! assert_eq!(map.keys().next().unwrap().b, "baz"); -//! ``` - -#![stable(feature = "rust1", since = "1.0.0")] - -#[stable(feature = "rust1", since = "1.0.0")] -// FIXME(#82080) The deprecation here is only theoretical, and does not actually produce a warning. -#[deprecated(note = "moved to `std::ops::Bound`", since = "1.26.0")] -#[doc(hidden)] -pub use crate::ops::Bound; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use alloc_crate::collections::{binary_heap, btree_map, btree_set}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use alloc_crate::collections::{linked_list, vec_deque}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use alloc_crate::collections::{BTreeMap, BTreeSet, BinaryHeap}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use alloc_crate::collections::{LinkedList, VecDeque}; - -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(inline)] -pub use self::hash_map::HashMap; -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(inline)] -pub use self::hash_set::HashSet; - -#[stable(feature = "try_reserve", since = "1.57.0")] -pub use alloc_crate::collections::TryReserveError; -#[unstable( - feature = "try_reserve_kind", - reason = "Uncertain how much info should be exposed", - issue = "48043" -)] -pub use alloc_crate::collections::TryReserveErrorKind; - -mod hash; - -#[stable(feature = "rust1", since = "1.0.0")] -pub mod hash_map { - //! A hash map implemented with quadratic probing and SIMD lookup. - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::hash::map::*; - - #[stable(feature = "hashmap_build_hasher", since = "1.7.0")] - pub use crate::hash::random::DefaultHasher; - #[stable(feature = "hashmap_build_hasher", since = "1.7.0")] - pub use crate::hash::random::RandomState; -} - -#[stable(feature = "rust1", since = "1.0.0")] -pub mod hash_set { - //! A hash set implemented as a `HashMap` where the value is `()`. - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::hash::set::*; -} diff --git a/library/std/src/env.rs b/library/std/src/env.rs deleted file mode 100644 index 6f8ac17f12c70..0000000000000 --- a/library/std/src/env.rs +++ /dev/null @@ -1,1033 +0,0 @@ -//! Inspection and manipulation of the process's environment. -//! -//! This module contains functions to inspect various aspects such as -//! environment variables, process arguments, the current directory, and various -//! other important directories. -//! -//! There are several functions and structs in this module that have a -//! counterpart ending in `os`. Those ending in `os` will return an [`OsString`] -//! and those without will return a [`String`]. - -#![stable(feature = "env", since = "1.0.0")] - -#[cfg(test)] -mod tests; - -use crate::error::Error; -use crate::ffi::{OsStr, OsString}; -use crate::fmt; -use crate::io; -use crate::path::{Path, PathBuf}; -use crate::sys; -use crate::sys::os as os_imp; - -/// Returns the current working directory as a [`PathBuf`]. -/// -/// # Platform-specific behavior -/// -/// This function [currently] corresponds to the `getcwd` function on Unix -/// and the `GetCurrentDirectoryW` function on Windows. -/// -/// [currently]: crate::io#platform-specific-behavior -/// -/// # Errors -/// -/// Returns an [`Err`] if the current working directory value is invalid. -/// Possible cases: -/// -/// * Current directory does not exist. -/// * There are insufficient permissions to access the current directory. -/// -/// # Examples -/// -/// ``` -/// use std::env; -/// -/// fn main() -> std::io::Result<()> { -/// let path = env::current_dir()?; -/// println!("The current directory is {}", path.display()); -/// Ok(()) -/// } -/// ``` -#[doc(alias = "pwd")] -#[doc(alias = "getcwd")] -#[doc(alias = "GetCurrentDirectory")] -#[stable(feature = "env", since = "1.0.0")] -pub fn current_dir() -> io::Result { - os_imp::getcwd() -} - -/// Changes the current working directory to the specified path. -/// -/// # Platform-specific behavior -/// -/// This function [currently] corresponds to the `chdir` function on Unix -/// and the `SetCurrentDirectoryW` function on Windows. -/// -/// Returns an [`Err`] if the operation fails. -/// -/// [currently]: crate::io#platform-specific-behavior -/// -/// # Examples -/// -/// ``` -/// use std::env; -/// use std::path::Path; -/// -/// let root = Path::new("/"); -/// assert!(env::set_current_dir(&root).is_ok()); -/// println!("Successfully changed working directory to {}!", root.display()); -/// ``` -#[doc(alias = "chdir", alias = "SetCurrentDirectory", alias = "SetCurrentDirectoryW")] -#[stable(feature = "env", since = "1.0.0")] -pub fn set_current_dir>(path: P) -> io::Result<()> { - os_imp::chdir(path.as_ref()) -} - -/// An iterator over a snapshot of the environment variables of this process. -/// -/// This structure is created by [`env::vars()`]. See its documentation for more. -/// -/// [`env::vars()`]: vars -#[stable(feature = "env", since = "1.0.0")] -pub struct Vars { - inner: VarsOs, -} - -/// An iterator over a snapshot of the environment variables of this process. -/// -/// This structure is created by [`env::vars_os()`]. See its documentation for more. -/// -/// [`env::vars_os()`]: vars_os -#[stable(feature = "env", since = "1.0.0")] -pub struct VarsOs { - inner: os_imp::Env, -} - -/// Returns an iterator of (variable, value) pairs of strings, for all the -/// environment variables of the current process. -/// -/// The returned iterator contains a snapshot of the process's environment -/// variables at the time of this invocation. Modifications to environment -/// variables afterwards will not be reflected in the returned iterator. -/// -/// # Panics -/// -/// While iterating, the returned iterator will panic if any key or value in the -/// environment is not valid unicode. If this is not desired, consider using -/// [`env::vars_os()`]. -/// -/// # Examples -/// -/// ``` -/// use std::env; -/// -/// // We will iterate through the references to the element returned by -/// // env::vars(); -/// for (key, value) in env::vars() { -/// println!("{key}: {value}"); -/// } -/// ``` -/// -/// [`env::vars_os()`]: vars_os -#[must_use] -#[stable(feature = "env", since = "1.0.0")] -pub fn vars() -> Vars { - Vars { inner: vars_os() } -} - -/// Returns an iterator of (variable, value) pairs of OS strings, for all the -/// environment variables of the current process. -/// -/// The returned iterator contains a snapshot of the process's environment -/// variables at the time of this invocation. Modifications to environment -/// variables afterwards will not be reflected in the returned iterator. -/// -/// Note that the returned iterator will not check if the environment variables -/// are valid Unicode. If you want to panic on invalid UTF-8, -/// use the [`vars`] function instead. -/// -/// # Examples -/// -/// ``` -/// use std::env; -/// -/// // We will iterate through the references to the element returned by -/// // env::vars_os(); -/// for (key, value) in env::vars_os() { -/// println!("{key:?}: {value:?}"); -/// } -/// ``` -#[must_use] -#[stable(feature = "env", since = "1.0.0")] -pub fn vars_os() -> VarsOs { - VarsOs { inner: os_imp::env() } -} - -#[stable(feature = "env", since = "1.0.0")] -impl Iterator for Vars { - type Item = (String, String); - fn next(&mut self) -> Option<(String, String)> { - self.inner.next().map(|(a, b)| (a.into_string().unwrap(), b.into_string().unwrap())) - } - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for Vars { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let Self { inner: VarsOs { inner } } = self; - f.debug_struct("Vars").field("inner", &inner.str_debug()).finish() - } -} - -#[stable(feature = "env", since = "1.0.0")] -impl Iterator for VarsOs { - type Item = (OsString, OsString); - fn next(&mut self) -> Option<(OsString, OsString)> { - self.inner.next() - } - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for VarsOs { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let Self { inner } = self; - f.debug_struct("VarsOs").field("inner", inner).finish() - } -} - -/// Fetches the environment variable `key` from the current process. -/// -/// # Errors -/// -/// This function will return an error if the environment variable isn't set. -/// -/// This function may return an error if the environment variable's name contains -/// the equal sign character (`=`) or the NUL character. -/// -/// This function will return an error if the environment variable's value is -/// not valid Unicode. If this is not desired, consider using [`var_os`]. -/// -/// # Examples -/// -/// ``` -/// use std::env; -/// -/// let key = "HOME"; -/// match env::var(key) { -/// Ok(val) => println!("{key}: {val:?}"), -/// Err(e) => println!("couldn't interpret {key}: {e}"), -/// } -/// ``` -#[stable(feature = "env", since = "1.0.0")] -pub fn var>(key: K) -> Result { - _var(key.as_ref()) -} - -fn _var(key: &OsStr) -> Result { - match var_os(key) { - Some(s) => s.into_string().map_err(VarError::NotUnicode), - None => Err(VarError::NotPresent), - } -} - -/// Fetches the environment variable `key` from the current process, returning -/// [`None`] if the variable isn't set or if there is another error. -/// -/// It may return `None` if the environment variable's name contains -/// the equal sign character (`=`) or the NUL character. -/// -/// Note that this function will not check if the environment variable -/// is valid Unicode. If you want to have an error on invalid UTF-8, -/// use the [`var`] function instead. -/// -/// # Examples -/// -/// ``` -/// use std::env; -/// -/// let key = "HOME"; -/// match env::var_os(key) { -/// Some(val) => println!("{key}: {val:?}"), -/// None => println!("{key} is not defined in the environment.") -/// } -/// ``` -/// -/// If expecting a delimited variable (such as `PATH`), [`split_paths`] -/// can be used to separate items. -#[must_use] -#[stable(feature = "env", since = "1.0.0")] -pub fn var_os>(key: K) -> Option { - _var_os(key.as_ref()) -} - -fn _var_os(key: &OsStr) -> Option { - os_imp::getenv(key) -} - -/// The error type for operations interacting with environment variables. -/// Possibly returned from [`env::var()`]. -/// -/// [`env::var()`]: var -#[derive(Debug, PartialEq, Eq, Clone)] -#[stable(feature = "env", since = "1.0.0")] -pub enum VarError { - /// The specified environment variable was not present in the current - /// process's environment. - #[stable(feature = "env", since = "1.0.0")] - NotPresent, - - /// The specified environment variable was found, but it did not contain - /// valid unicode data. The found data is returned as a payload of this - /// variant. - #[stable(feature = "env", since = "1.0.0")] - NotUnicode(#[stable(feature = "env", since = "1.0.0")] OsString), -} - -#[stable(feature = "env", since = "1.0.0")] -impl fmt::Display for VarError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - match *self { - VarError::NotPresent => write!(f, "environment variable not found"), - VarError::NotUnicode(ref s) => { - write!(f, "environment variable was not valid unicode: {:?}", s) - } - } - } -} - -#[stable(feature = "env", since = "1.0.0")] -impl Error for VarError { - #[allow(deprecated)] - fn description(&self) -> &str { - match *self { - VarError::NotPresent => "environment variable not found", - VarError::NotUnicode(..) => "environment variable was not valid unicode", - } - } -} - -/// Sets the environment variable `key` to the value `value` for the currently running -/// process. -/// -/// # Safety -/// -/// Even though this function is currently not marked as `unsafe`, it needs to -/// be because invoking it can cause undefined behaviour. The function will be -/// marked `unsafe` in a future version of Rust. This is tracked in -/// [rust#27970](https://github.com/rust-lang/rust/issues/27970). -/// -/// This function is safe to call in a single-threaded program. -/// -/// In multi-threaded programs, you must ensure that are no other threads -/// concurrently writing or *reading*(!) from the environment through functions -/// other than the ones in this module. You are responsible for figuring out -/// how to achieve this, but we strongly suggest not using `set_var` or -/// `remove_var` in multi-threaded programs at all. -/// -/// Most C libraries, including libc itself do not advertise which functions -/// read from the environment. Even functions from the Rust standard library do -/// that, e.g. for DNS lookups from [`std::net::ToSocketAddrs`]. -/// -/// Discussion of this unsafety on Unix may be found in: -/// -/// - [Austin Group Bugzilla](https://austingroupbugs.net/view.php?id=188) -/// - [GNU C library Bugzilla](https://sourceware.org/bugzilla/show_bug.cgi?id=15607#c2) -/// -/// [`std::net::ToSocketAddrs`]: crate::net::ToSocketAddrs -/// -/// # Panics -/// -/// This function may panic if `key` is empty, contains an ASCII equals sign `'='` -/// or the NUL character `'\0'`, or when `value` contains the NUL character. -/// -/// # Examples -/// -/// ``` -/// use std::env; -/// -/// let key = "KEY"; -/// env::set_var(key, "VALUE"); -/// assert_eq!(env::var(key), Ok("VALUE".to_string())); -/// ``` -#[stable(feature = "env", since = "1.0.0")] -pub fn set_var, V: AsRef>(key: K, value: V) { - _set_var(key.as_ref(), value.as_ref()) -} - -fn _set_var(key: &OsStr, value: &OsStr) { - os_imp::setenv(key, value).unwrap_or_else(|e| { - panic!("failed to set environment variable `{key:?}` to `{value:?}`: {e}") - }) -} - -/// Removes an environment variable from the environment of the currently running process. -/// -/// # Safety -/// -/// Even though this function is currently not marked as `unsafe`, it needs to -/// be because invoking it can cause undefined behaviour. The function will be -/// marked `unsafe` in a future version of Rust. This is tracked in -/// [rust#27970](https://github.com/rust-lang/rust/issues/27970). -/// -/// This function is safe to call in a single-threaded program. -/// -/// In multi-threaded programs, you must ensure that are no other threads -/// concurrently writing or *reading*(!) from the environment through functions -/// other than the ones in this module. You are responsible for figuring out -/// how to achieve this, but we strongly suggest not using `set_var` or -/// `remove_var` in multi-threaded programs at all. -/// -/// Most C libraries, including libc itself do not advertise which functions -/// read from the environment. Even functions from the Rust standard library do -/// that, e.g. for DNS lookups from [`std::net::ToSocketAddrs`]. -/// -/// Discussion of this unsafety on Unix may be found in: -/// -/// - [Austin Group Bugzilla](https://austingroupbugs.net/view.php?id=188) -/// - [GNU C library Bugzilla](https://sourceware.org/bugzilla/show_bug.cgi?id=15607#c2) -/// -/// [`std::net::ToSocketAddrs`]: crate::net::ToSocketAddrs -/// -/// # Panics -/// -/// This function may panic if `key` is empty, contains an ASCII equals sign -/// `'='` or the NUL character `'\0'`, or when the value contains the NUL -/// character. -/// -/// # Examples -/// -/// ``` -/// use std::env; -/// -/// let key = "KEY"; -/// env::set_var(key, "VALUE"); -/// assert_eq!(env::var(key), Ok("VALUE".to_string())); -/// -/// env::remove_var(key); -/// assert!(env::var(key).is_err()); -/// ``` -#[stable(feature = "env", since = "1.0.0")] -pub fn remove_var>(key: K) { - _remove_var(key.as_ref()) -} - -fn _remove_var(key: &OsStr) { - os_imp::unsetenv(key) - .unwrap_or_else(|e| panic!("failed to remove environment variable `{key:?}`: {e}")) -} - -/// An iterator that splits an environment variable into paths according to -/// platform-specific conventions. -/// -/// The iterator element type is [`PathBuf`]. -/// -/// This structure is created by [`env::split_paths()`]. See its -/// documentation for more. -/// -/// [`env::split_paths()`]: split_paths -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "env", since = "1.0.0")] -pub struct SplitPaths<'a> { - inner: os_imp::SplitPaths<'a>, -} - -/// Parses input according to platform conventions for the `PATH` -/// environment variable. -/// -/// Returns an iterator over the paths contained in `unparsed`. The iterator -/// element type is [`PathBuf`]. -/// -/// On most Unix platforms, the separator is `:` and on Windows it is `;`. This -/// also performs unquoting on Windows. -/// -/// [`join_paths`] can be used to recombine elements. -/// -/// # Panics -/// -/// This will panic on systems where there is no delimited `PATH` variable, -/// such as UEFI. -/// -/// # Examples -/// -/// ``` -/// use std::env; -/// -/// let key = "PATH"; -/// match env::var_os(key) { -/// Some(paths) => { -/// for path in env::split_paths(&paths) { -/// println!("'{}'", path.display()); -/// } -/// } -/// None => println!("{key} is not defined in the environment.") -/// } -/// ``` -#[stable(feature = "env", since = "1.0.0")] -pub fn split_paths + ?Sized>(unparsed: &T) -> SplitPaths<'_> { - SplitPaths { inner: os_imp::split_paths(unparsed.as_ref()) } -} - -#[stable(feature = "env", since = "1.0.0")] -impl<'a> Iterator for SplitPaths<'a> { - type Item = PathBuf; - fn next(&mut self) -> Option { - self.inner.next() - } - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for SplitPaths<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("SplitPaths").finish_non_exhaustive() - } -} - -/// The error type for operations on the `PATH` variable. Possibly returned from -/// [`env::join_paths()`]. -/// -/// [`env::join_paths()`]: join_paths -#[derive(Debug)] -#[stable(feature = "env", since = "1.0.0")] -pub struct JoinPathsError { - inner: os_imp::JoinPathsError, -} - -/// Joins a collection of [`Path`]s appropriately for the `PATH` -/// environment variable. -/// -/// # Errors -/// -/// Returns an [`Err`] (containing an error message) if one of the input -/// [`Path`]s contains an invalid character for constructing the `PATH` -/// variable (a double quote on Windows or a colon on Unix), or if the system -/// does not have a `PATH`-like variable (e.g. UEFI or WASI). -/// -/// # Examples -/// -/// Joining paths on a Unix-like platform: -/// -/// ``` -/// use std::env; -/// use std::ffi::OsString; -/// use std::path::Path; -/// -/// fn main() -> Result<(), env::JoinPathsError> { -/// # if cfg!(unix) { -/// let paths = [Path::new("/bin"), Path::new("/usr/bin")]; -/// let path_os_string = env::join_paths(paths.iter())?; -/// assert_eq!(path_os_string, OsString::from("/bin:/usr/bin")); -/// # } -/// Ok(()) -/// } -/// ``` -/// -/// Joining a path containing a colon on a Unix-like platform results in an -/// error: -/// -/// ``` -/// # if cfg!(unix) { -/// use std::env; -/// use std::path::Path; -/// -/// let paths = [Path::new("/bin"), Path::new("/usr/bi:n")]; -/// assert!(env::join_paths(paths.iter()).is_err()); -/// # } -/// ``` -/// -/// Using `env::join_paths()` with [`env::split_paths()`] to append an item to -/// the `PATH` environment variable: -/// -/// ``` -/// use std::env; -/// use std::path::PathBuf; -/// -/// fn main() -> Result<(), env::JoinPathsError> { -/// if let Some(path) = env::var_os("PATH") { -/// let mut paths = env::split_paths(&path).collect::>(); -/// paths.push(PathBuf::from("/home/xyz/bin")); -/// let new_path = env::join_paths(paths)?; -/// env::set_var("PATH", &new_path); -/// } -/// -/// Ok(()) -/// } -/// ``` -/// -/// [`env::split_paths()`]: split_paths -#[stable(feature = "env", since = "1.0.0")] -pub fn join_paths(paths: I) -> Result -where - I: IntoIterator, - T: AsRef, -{ - os_imp::join_paths(paths.into_iter()).map_err(|e| JoinPathsError { inner: e }) -} - -#[stable(feature = "env", since = "1.0.0")] -impl fmt::Display for JoinPathsError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.inner.fmt(f) - } -} - -#[stable(feature = "env", since = "1.0.0")] -impl Error for JoinPathsError { - #[allow(deprecated, deprecated_in_future)] - fn description(&self) -> &str { - self.inner.description() - } -} - -/// Returns the path of the current user's home directory if known. -/// -/// # Unix -/// -/// - Returns the value of the 'HOME' environment variable if it is set -/// (including to an empty string). -/// - Otherwise, it tries to determine the home directory by invoking the `getpwuid_r` function -/// using the UID of the current user. An empty home directory field returned from the -/// `getpwuid_r` function is considered to be a valid value. -/// - Returns `None` if the current user has no entry in the /etc/passwd file. -/// -/// # Windows -/// -/// - Returns the value of the 'HOME' environment variable if it is set -/// (including to an empty string). -/// - Otherwise, returns the value of the 'USERPROFILE' environment variable if it is set -/// (including to an empty string). -/// - If both do not exist, [`GetUserProfileDirectory`][msdn] is used to return the path. -/// -/// [msdn]: https://docs.microsoft.com/en-us/windows/win32/api/userenv/nf-userenv-getuserprofiledirectorya -/// -/// # Deprecation -/// -/// This function is deprecated because the behaviour on Windows is not correct. -/// The 'HOME' environment variable is not standard on Windows, and may not produce -/// desired results; for instance, under Cygwin or Mingw it will return `/home/you` -/// when it should return `C:\Users\you`. -/// -/// # Examples -/// -/// ``` -/// use std::env; -/// -/// match env::home_dir() { -/// Some(path) => println!("Your home directory, probably: {}", path.display()), -/// None => println!("Impossible to get your home dir!"), -/// } -/// ``` -#[deprecated( - since = "1.29.0", - note = "This function's behavior may be unexpected on Windows. \ - Consider using a crate from crates.io instead." -)] -#[must_use] -#[stable(feature = "env", since = "1.0.0")] -pub fn home_dir() -> Option { - os_imp::home_dir() -} - -/// Returns the path of a temporary directory. -/// -/// The temporary directory may be shared among users, or between processes -/// with different privileges; thus, the creation of any files or directories -/// in the temporary directory must use a secure method to create a uniquely -/// named file. Creating a file or directory with a fixed or predictable name -/// may result in "insecure temporary file" security vulnerabilities. Consider -/// using a crate that securely creates temporary files or directories. -/// -/// # Platform-specific behavior -/// -/// On Unix, returns the value of the `TMPDIR` environment variable if it is -/// set, otherwise for non-Android it returns `/tmp`. On Android, since there -/// is no global temporary folder (it is usually allocated per-app), it returns -/// `/data/local/tmp`. -/// On Windows, the behavior is equivalent to that of [`GetTempPath2`][GetTempPath2] / -/// [`GetTempPath`][GetTempPath], which this function uses internally. -/// Note that, this [may change in the future][changes]. -/// -/// [changes]: io#platform-specific-behavior -/// [GetTempPath2]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-gettemppath2a -/// [GetTempPath]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-gettemppatha -/// -/// ```no_run -/// use std::env; -/// -/// fn main() { -/// let dir = env::temp_dir(); -/// println!("Temporary directory: {}", dir.display()); -/// } -/// ``` -#[must_use] -#[doc(alias = "GetTempPath", alias = "GetTempPath2")] -#[stable(feature = "env", since = "1.0.0")] -pub fn temp_dir() -> PathBuf { - os_imp::temp_dir() -} - -/// Returns the full filesystem path of the current running executable. -/// -/// # Platform-specific behavior -/// -/// If the executable was invoked through a symbolic link, some platforms will -/// return the path of the symbolic link and other platforms will return the -/// path of the symbolic link’s target. -/// -/// If the executable is renamed while it is running, platforms may return the -/// path at the time it was loaded instead of the new path. -/// -/// # Errors -/// -/// Acquiring the path of the current executable is a platform-specific operation -/// that can fail for a good number of reasons. Some errors can include, but not -/// be limited to, filesystem operations failing or general syscall failures. -/// -/// # Security -/// -/// The output of this function should not be trusted for anything -/// that might have security implications. Basically, if users can run -/// the executable, they can change the output arbitrarily. -/// -/// As an example, you can easily introduce a race condition. It goes -/// like this: -/// -/// 1. You get the path to the current executable using `current_exe()`, and -/// store it in a variable. -/// 2. Time passes. A malicious actor removes the current executable, and -/// replaces it with a malicious one. -/// 3. You then use the stored path to re-execute the current -/// executable. -/// -/// You expected to safely execute the current executable, but you're -/// instead executing something completely different. The code you -/// just executed run with your privileges. -/// -/// This sort of behavior has been known to [lead to privilege escalation] when -/// used incorrectly. -/// -/// [lead to privilege escalation]: https://securityvulns.com/Wdocument183.html -/// -/// # Examples -/// -/// ``` -/// use std::env; -/// -/// match env::current_exe() { -/// Ok(exe_path) => println!("Path of this executable is: {}", -/// exe_path.display()), -/// Err(e) => println!("failed to get current exe path: {e}"), -/// }; -/// ``` -#[stable(feature = "env", since = "1.0.0")] -pub fn current_exe() -> io::Result { - os_imp::current_exe() -} - -/// An iterator over the arguments of a process, yielding a [`String`] value for -/// each argument. -/// -/// This struct is created by [`env::args()`]. See its documentation -/// for more. -/// -/// The first element is traditionally the path of the executable, but it can be -/// set to arbitrary text, and might not even exist. This means this property -/// should not be relied upon for security purposes. -/// -/// [`env::args()`]: args -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "env", since = "1.0.0")] -pub struct Args { - inner: ArgsOs, -} - -/// An iterator over the arguments of a process, yielding an [`OsString`] value -/// for each argument. -/// -/// This struct is created by [`env::args_os()`]. See its documentation -/// for more. -/// -/// The first element is traditionally the path of the executable, but it can be -/// set to arbitrary text, and might not even exist. This means this property -/// should not be relied upon for security purposes. -/// -/// [`env::args_os()`]: args_os -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "env", since = "1.0.0")] -pub struct ArgsOs { - inner: sys::args::Args, -} - -/// Returns the arguments that this program was started with (normally passed -/// via the command line). -/// -/// The first element is traditionally the path of the executable, but it can be -/// set to arbitrary text, and might not even exist. This means this property should -/// not be relied upon for security purposes. -/// -/// On Unix systems the shell usually expands unquoted arguments with glob patterns -/// (such as `*` and `?`). On Windows this is not done, and such arguments are -/// passed as-is. -/// -/// On glibc Linux systems, arguments are retrieved by placing a function in `.init_array`. -/// glibc passes `argc`, `argv`, and `envp` to functions in `.init_array`, as a non-standard -/// extension. This allows `std::env::args` to work even in a `cdylib` or `staticlib`, as it -/// does on macOS and Windows. -/// -/// # Panics -/// -/// The returned iterator will panic during iteration if any argument to the -/// process is not valid Unicode. If this is not desired, -/// use the [`args_os`] function instead. -/// -/// # Examples -/// -/// ``` -/// use std::env; -/// -/// // Prints each argument on a separate line -/// for argument in env::args() { -/// println!("{argument}"); -/// } -/// ``` -#[stable(feature = "env", since = "1.0.0")] -pub fn args() -> Args { - Args { inner: args_os() } -} - -/// Returns the arguments that this program was started with (normally passed -/// via the command line). -/// -/// The first element is traditionally the path of the executable, but it can be -/// set to arbitrary text, and might not even exist. This means this property should -/// not be relied upon for security purposes. -/// -/// On Unix systems the shell usually expands unquoted arguments with glob patterns -/// (such as `*` and `?`). On Windows this is not done, and such arguments are -/// passed as-is. -/// -/// On glibc Linux systems, arguments are retrieved by placing a function in `.init_array`. -/// glibc passes `argc`, `argv`, and `envp` to functions in `.init_array`, as a non-standard -/// extension. This allows `std::env::args_os` to work even in a `cdylib` or `staticlib`, as it -/// does on macOS and Windows. -/// -/// Note that the returned iterator will not check if the arguments to the -/// process are valid Unicode. If you want to panic on invalid UTF-8, -/// use the [`args`] function instead. -/// -/// # Examples -/// -/// ``` -/// use std::env; -/// -/// // Prints each argument on a separate line -/// for argument in env::args_os() { -/// println!("{argument:?}"); -/// } -/// ``` -#[stable(feature = "env", since = "1.0.0")] -pub fn args_os() -> ArgsOs { - ArgsOs { inner: sys::args::args() } -} - -#[stable(feature = "env_unimpl_send_sync", since = "1.26.0")] -impl !Send for Args {} - -#[stable(feature = "env_unimpl_send_sync", since = "1.26.0")] -impl !Sync for Args {} - -#[stable(feature = "env", since = "1.0.0")] -impl Iterator for Args { - type Item = String; - fn next(&mut self) -> Option { - self.inner.next().map(|s| s.into_string().unwrap()) - } - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } -} - -#[stable(feature = "env", since = "1.0.0")] -impl ExactSizeIterator for Args { - fn len(&self) -> usize { - self.inner.len() - } - fn is_empty(&self) -> bool { - self.inner.is_empty() - } -} - -#[stable(feature = "env_iterators", since = "1.12.0")] -impl DoubleEndedIterator for Args { - fn next_back(&mut self) -> Option { - self.inner.next_back().map(|s| s.into_string().unwrap()) - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for Args { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let Self { inner: ArgsOs { inner } } = self; - f.debug_struct("Args").field("inner", inner).finish() - } -} - -#[stable(feature = "env_unimpl_send_sync", since = "1.26.0")] -impl !Send for ArgsOs {} - -#[stable(feature = "env_unimpl_send_sync", since = "1.26.0")] -impl !Sync for ArgsOs {} - -#[stable(feature = "env", since = "1.0.0")] -impl Iterator for ArgsOs { - type Item = OsString; - fn next(&mut self) -> Option { - self.inner.next() - } - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } -} - -#[stable(feature = "env", since = "1.0.0")] -impl ExactSizeIterator for ArgsOs { - fn len(&self) -> usize { - self.inner.len() - } - fn is_empty(&self) -> bool { - self.inner.is_empty() - } -} - -#[stable(feature = "env_iterators", since = "1.12.0")] -impl DoubleEndedIterator for ArgsOs { - fn next_back(&mut self) -> Option { - self.inner.next_back() - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for ArgsOs { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let Self { inner } = self; - f.debug_struct("ArgsOs").field("inner", inner).finish() - } -} - -/// Constants associated with the current target -#[stable(feature = "env", since = "1.0.0")] -pub mod consts { - use crate::sys::env::os; - - /// A string describing the architecture of the CPU that is currently - /// in use. - /// - /// Some possible values: - /// - /// - x86 - /// - x86_64 - /// - arm - /// - aarch64 - /// - loongarch64 - /// - m68k - /// - csky - /// - mips - /// - mips64 - /// - powerpc - /// - powerpc64 - /// - riscv64 - /// - s390x - /// - sparc64 - #[stable(feature = "env", since = "1.0.0")] - pub const ARCH: &str = env!("STD_ENV_ARCH"); - - /// The family of the operating system. Example value is `unix`. - /// - /// Some possible values: - /// - /// - unix - /// - windows - #[stable(feature = "env", since = "1.0.0")] - pub const FAMILY: &str = os::FAMILY; - - /// A string describing the specific operating system in use. - /// Example value is `linux`. - /// - /// Some possible values: - /// - /// - linux - /// - macos - /// - ios - /// - freebsd - /// - dragonfly - /// - netbsd - /// - openbsd - /// - solaris - /// - android - /// - windows - #[stable(feature = "env", since = "1.0.0")] - pub const OS: &str = os::OS; - - /// Specifies the filename prefix used for shared libraries on this - /// platform. Example value is `lib`. - /// - /// Some possible values: - /// - /// - lib - /// - `""` (an empty string) - #[stable(feature = "env", since = "1.0.0")] - pub const DLL_PREFIX: &str = os::DLL_PREFIX; - - /// Specifies the filename suffix used for shared libraries on this - /// platform. Example value is `.so`. - /// - /// Some possible values: - /// - /// - .so - /// - .dylib - /// - .dll - #[stable(feature = "env", since = "1.0.0")] - pub const DLL_SUFFIX: &str = os::DLL_SUFFIX; - - /// Specifies the file extension used for shared libraries on this - /// platform that goes after the dot. Example value is `so`. - /// - /// Some possible values: - /// - /// - so - /// - dylib - /// - dll - #[stable(feature = "env", since = "1.0.0")] - pub const DLL_EXTENSION: &str = os::DLL_EXTENSION; - - /// Specifies the filename suffix used for executable binaries on this - /// platform. Example value is `.exe`. - /// - /// Some possible values: - /// - /// - .exe - /// - .nexe - /// - .pexe - /// - `""` (an empty string) - #[stable(feature = "env", since = "1.0.0")] - pub const EXE_SUFFIX: &str = os::EXE_SUFFIX; - - /// Specifies the file extension, if any, used for executable binaries - /// on this platform. Example value is `exe`. - /// - /// Some possible values: - /// - /// - exe - /// - `""` (an empty string) - #[stable(feature = "env", since = "1.0.0")] - pub const EXE_EXTENSION: &str = os::EXE_EXTENSION; -} diff --git a/library/std/src/env/tests.rs b/library/std/src/env/tests.rs deleted file mode 100644 index fc7aee2973329..0000000000000 --- a/library/std/src/env/tests.rs +++ /dev/null @@ -1,120 +0,0 @@ -use super::*; - -#[test] -#[cfg_attr(any(target_os = "emscripten", target_env = "sgx"), ignore)] -fn test_self_exe_path() { - let path = current_exe(); - assert!(path.is_ok()); - let path = path.unwrap(); - - // Hard to test this function - assert!(path.is_absolute()); -} - -#[test] -fn test() { - assert!((!Path::new("test-path").is_absolute())); - - #[cfg(not(target_env = "sgx"))] - current_dir().unwrap(); -} - -#[test] -#[cfg(windows)] -fn split_paths_windows() { - use crate::path::PathBuf; - - fn check_parse(unparsed: &str, parsed: &[&str]) -> bool { - split_paths(unparsed).collect::>() - == parsed.iter().map(|s| PathBuf::from(*s)).collect::>() - } - - assert!(check_parse("", &mut [""])); - assert!(check_parse(r#""""#, &mut [""])); - assert!(check_parse(";;", &mut ["", "", ""])); - assert!(check_parse(r"c:\", &mut [r"c:\"])); - assert!(check_parse(r"c:\;", &mut [r"c:\", ""])); - assert!(check_parse(r"c:\;c:\Program Files\", &mut [r"c:\", r"c:\Program Files\"])); - assert!(check_parse(r#"c:\;c:\"foo"\"#, &mut [r"c:\", r"c:\foo\"])); - assert!(check_parse(r#"c:\;c:\"foo;bar"\;c:\baz"#, &mut [r"c:\", r"c:\foo;bar\", r"c:\baz"])); -} - -#[test] -#[cfg(unix)] -fn split_paths_unix() { - use crate::path::PathBuf; - - fn check_parse(unparsed: &str, parsed: &[&str]) -> bool { - split_paths(unparsed).collect::>() - == parsed.iter().map(|s| PathBuf::from(*s)).collect::>() - } - - assert!(check_parse("", &mut [""])); - assert!(check_parse("::", &mut ["", "", ""])); - assert!(check_parse("/", &mut ["/"])); - assert!(check_parse("/:", &mut ["/", ""])); - assert!(check_parse("/:/usr/local", &mut ["/", "/usr/local"])); -} - -#[test] -#[cfg(unix)] -fn join_paths_unix() { - use crate::ffi::OsStr; - - fn test_eq(input: &[&str], output: &str) -> bool { - &*join_paths(input.iter().cloned()).unwrap() == OsStr::new(output) - } - - assert!(test_eq(&[], "")); - assert!(test_eq(&["/bin", "/usr/bin", "/usr/local/bin"], "/bin:/usr/bin:/usr/local/bin")); - assert!(test_eq(&["", "/bin", "", "", "/usr/bin", ""], ":/bin:::/usr/bin:")); - assert!(join_paths(["/te:st"].iter().cloned()).is_err()); -} - -#[test] -#[cfg(windows)] -fn join_paths_windows() { - use crate::ffi::OsStr; - - fn test_eq(input: &[&str], output: &str) -> bool { - &*join_paths(input.iter().cloned()).unwrap() == OsStr::new(output) - } - - assert!(test_eq(&[], "")); - assert!(test_eq(&[r"c:\windows", r"c:\"], r"c:\windows;c:\")); - assert!(test_eq(&["", r"c:\windows", "", "", r"c:\", ""], r";c:\windows;;;c:\;")); - assert!(test_eq(&[r"c:\te;st", r"c:\"], r#""c:\te;st";c:\"#)); - assert!(join_paths([r#"c:\te"st"#].iter().cloned()).is_err()); -} - -#[test] -fn args_debug() { - assert_eq!( - format!("Args {{ inner: {:?} }}", args().collect::>()), - format!("{:?}", args()) - ); -} - -#[test] -fn args_os_debug() { - assert_eq!( - format!("ArgsOs {{ inner: {:?} }}", args_os().collect::>()), - format!("{:?}", args_os()) - ); -} - -#[test] -fn vars_debug() { - assert_eq!( - format!("Vars {{ inner: {:?} }}", vars().collect::>()), - format!("{:?}", vars()) - ); -} - -#[test] -fn vars_os_debug() { - assert_eq!( - format!("VarsOs {{ inner: {:?} }}", vars_os().collect::>()), - format!("{:?}", vars_os()) - ); -} diff --git a/library/std/src/error.rs b/library/std/src/error.rs deleted file mode 100644 index b240e4e2c45be..0000000000000 --- a/library/std/src/error.rs +++ /dev/null @@ -1,570 +0,0 @@ -#![doc = include_str!("../../core/src/error.md")] -#![stable(feature = "rust1", since = "1.0.0")] - -#[cfg(test)] -mod tests; - -use crate::backtrace::Backtrace; -use crate::fmt::{self, Write}; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::error::Error; -#[unstable(feature = "error_generic_member_access", issue = "99301")] -pub use core::error::{request_ref, request_value, Request}; - -/// An error reporter that prints an error and its sources. -/// -/// Report also exposes configuration options for formatting the error sources, either entirely on a -/// single line, or in multi-line format with each source on a new line. -/// -/// `Report` only requires that the wrapped error implement `Error`. It doesn't require that the -/// wrapped error be `Send`, `Sync`, or `'static`. -/// -/// # Examples -/// -/// ```rust -/// #![feature(error_reporter)] -/// use std::error::{Error, Report}; -/// use std::fmt; -/// -/// #[derive(Debug)] -/// struct SuperError { -/// source: SuperErrorSideKick, -/// } -/// -/// impl fmt::Display for SuperError { -/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { -/// write!(f, "SuperError is here!") -/// } -/// } -/// -/// impl Error for SuperError { -/// fn source(&self) -> Option<&(dyn Error + 'static)> { -/// Some(&self.source) -/// } -/// } -/// -/// #[derive(Debug)] -/// struct SuperErrorSideKick; -/// -/// impl fmt::Display for SuperErrorSideKick { -/// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { -/// write!(f, "SuperErrorSideKick is here!") -/// } -/// } -/// -/// impl Error for SuperErrorSideKick {} -/// -/// fn get_super_error() -> Result<(), SuperError> { -/// Err(SuperError { source: SuperErrorSideKick }) -/// } -/// -/// fn main() { -/// match get_super_error() { -/// Err(e) => println!("Error: {}", Report::new(e)), -/// _ => println!("No error"), -/// } -/// } -/// ``` -/// -/// This example produces the following output: -/// -/// ```console -/// Error: SuperError is here!: SuperErrorSideKick is here! -/// ``` -/// -/// ## Output consistency -/// -/// Report prints the same output via `Display` and `Debug`, so it works well with -/// [`Result::unwrap`]/[`Result::expect`] which print their `Err` variant via `Debug`: -/// -/// ```should_panic -/// #![feature(error_reporter)] -/// use std::error::Report; -/// # use std::error::Error; -/// # use std::fmt; -/// # #[derive(Debug)] -/// # struct SuperError { -/// # source: SuperErrorSideKick, -/// # } -/// # impl fmt::Display for SuperError { -/// # fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { -/// # write!(f, "SuperError is here!") -/// # } -/// # } -/// # impl Error for SuperError { -/// # fn source(&self) -> Option<&(dyn Error + 'static)> { -/// # Some(&self.source) -/// # } -/// # } -/// # #[derive(Debug)] -/// # struct SuperErrorSideKick; -/// # impl fmt::Display for SuperErrorSideKick { -/// # fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { -/// # write!(f, "SuperErrorSideKick is here!") -/// # } -/// # } -/// # impl Error for SuperErrorSideKick {} -/// # fn get_super_error() -> Result<(), SuperError> { -/// # Err(SuperError { source: SuperErrorSideKick }) -/// # } -/// -/// get_super_error().map_err(Report::new).unwrap(); -/// ``` -/// -/// This example produces the following output: -/// -/// ```console -/// thread 'main' panicked at src/error.rs:34:40: -/// called `Result::unwrap()` on an `Err` value: SuperError is here!: SuperErrorSideKick is here! -/// note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace -/// ``` -/// -/// ## Return from `main` -/// -/// `Report` also implements `From` for all types that implement [`Error`]; this when combined with -/// the `Debug` output means `Report` is an ideal starting place for formatting errors returned -/// from `main`. -/// -/// ```should_panic -/// #![feature(error_reporter)] -/// use std::error::Report; -/// # use std::error::Error; -/// # use std::fmt; -/// # #[derive(Debug)] -/// # struct SuperError { -/// # source: SuperErrorSideKick, -/// # } -/// # impl fmt::Display for SuperError { -/// # fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { -/// # write!(f, "SuperError is here!") -/// # } -/// # } -/// # impl Error for SuperError { -/// # fn source(&self) -> Option<&(dyn Error + 'static)> { -/// # Some(&self.source) -/// # } -/// # } -/// # #[derive(Debug)] -/// # struct SuperErrorSideKick; -/// # impl fmt::Display for SuperErrorSideKick { -/// # fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { -/// # write!(f, "SuperErrorSideKick is here!") -/// # } -/// # } -/// # impl Error for SuperErrorSideKick {} -/// # fn get_super_error() -> Result<(), SuperError> { -/// # Err(SuperError { source: SuperErrorSideKick }) -/// # } -/// -/// fn main() -> Result<(), Report> { -/// get_super_error()?; -/// Ok(()) -/// } -/// ``` -/// -/// This example produces the following output: -/// -/// ```console -/// Error: SuperError is here!: SuperErrorSideKick is here! -/// ``` -/// -/// **Note**: `Report`s constructed via `?` and `From` will be configured to use the single line -/// output format. If you want to make sure your `Report`s are pretty printed and include backtrace -/// you will need to manually convert and enable those flags. -/// -/// ```should_panic -/// #![feature(error_reporter)] -/// use std::error::Report; -/// # use std::error::Error; -/// # use std::fmt; -/// # #[derive(Debug)] -/// # struct SuperError { -/// # source: SuperErrorSideKick, -/// # } -/// # impl fmt::Display for SuperError { -/// # fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { -/// # write!(f, "SuperError is here!") -/// # } -/// # } -/// # impl Error for SuperError { -/// # fn source(&self) -> Option<&(dyn Error + 'static)> { -/// # Some(&self.source) -/// # } -/// # } -/// # #[derive(Debug)] -/// # struct SuperErrorSideKick; -/// # impl fmt::Display for SuperErrorSideKick { -/// # fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { -/// # write!(f, "SuperErrorSideKick is here!") -/// # } -/// # } -/// # impl Error for SuperErrorSideKick {} -/// # fn get_super_error() -> Result<(), SuperError> { -/// # Err(SuperError { source: SuperErrorSideKick }) -/// # } -/// -/// fn main() -> Result<(), Report> { -/// get_super_error() -/// .map_err(Report::from) -/// .map_err(|r| r.pretty(true).show_backtrace(true))?; -/// Ok(()) -/// } -/// ``` -/// -/// This example produces the following output: -/// -/// ```console -/// Error: SuperError is here! -/// -/// Caused by: -/// SuperErrorSideKick is here! -/// ``` -#[unstable(feature = "error_reporter", issue = "90172")] -pub struct Report> { - /// The error being reported. - error: E, - /// Whether a backtrace should be included as part of the report. - show_backtrace: bool, - /// Whether the report should be pretty-printed. - pretty: bool, -} - -impl Report -where - Report: From, -{ - /// Create a new `Report` from an input error. - #[unstable(feature = "error_reporter", issue = "90172")] - pub fn new(error: E) -> Report { - Self::from(error) - } -} - -impl Report { - /// Enable pretty-printing the report across multiple lines. - /// - /// # Examples - /// - /// ```rust - /// #![feature(error_reporter)] - /// use std::error::Report; - /// # use std::error::Error; - /// # use std::fmt; - /// # #[derive(Debug)] - /// # struct SuperError { - /// # source: SuperErrorSideKick, - /// # } - /// # impl fmt::Display for SuperError { - /// # fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - /// # write!(f, "SuperError is here!") - /// # } - /// # } - /// # impl Error for SuperError { - /// # fn source(&self) -> Option<&(dyn Error + 'static)> { - /// # Some(&self.source) - /// # } - /// # } - /// # #[derive(Debug)] - /// # struct SuperErrorSideKick; - /// # impl fmt::Display for SuperErrorSideKick { - /// # fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - /// # write!(f, "SuperErrorSideKick is here!") - /// # } - /// # } - /// # impl Error for SuperErrorSideKick {} - /// - /// let error = SuperError { source: SuperErrorSideKick }; - /// let report = Report::new(error).pretty(true); - /// eprintln!("Error: {report:?}"); - /// ``` - /// - /// This example produces the following output: - /// - /// ```console - /// Error: SuperError is here! - /// - /// Caused by: - /// SuperErrorSideKick is here! - /// ``` - /// - /// When there are multiple source errors the causes will be numbered in order of iteration - /// starting from the outermost error. - /// - /// ```rust - /// #![feature(error_reporter)] - /// use std::error::Report; - /// # use std::error::Error; - /// # use std::fmt; - /// # #[derive(Debug)] - /// # struct SuperError { - /// # source: SuperErrorSideKick, - /// # } - /// # impl fmt::Display for SuperError { - /// # fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - /// # write!(f, "SuperError is here!") - /// # } - /// # } - /// # impl Error for SuperError { - /// # fn source(&self) -> Option<&(dyn Error + 'static)> { - /// # Some(&self.source) - /// # } - /// # } - /// # #[derive(Debug)] - /// # struct SuperErrorSideKick { - /// # source: SuperErrorSideKickSideKick, - /// # } - /// # impl fmt::Display for SuperErrorSideKick { - /// # fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - /// # write!(f, "SuperErrorSideKick is here!") - /// # } - /// # } - /// # impl Error for SuperErrorSideKick { - /// # fn source(&self) -> Option<&(dyn Error + 'static)> { - /// # Some(&self.source) - /// # } - /// # } - /// # #[derive(Debug)] - /// # struct SuperErrorSideKickSideKick; - /// # impl fmt::Display for SuperErrorSideKickSideKick { - /// # fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - /// # write!(f, "SuperErrorSideKickSideKick is here!") - /// # } - /// # } - /// # impl Error for SuperErrorSideKickSideKick { } - /// - /// let source = SuperErrorSideKickSideKick; - /// let source = SuperErrorSideKick { source }; - /// let error = SuperError { source }; - /// let report = Report::new(error).pretty(true); - /// eprintln!("Error: {report:?}"); - /// ``` - /// - /// This example produces the following output: - /// - /// ```console - /// Error: SuperError is here! - /// - /// Caused by: - /// 0: SuperErrorSideKick is here! - /// 1: SuperErrorSideKickSideKick is here! - /// ``` - #[unstable(feature = "error_reporter", issue = "90172")] - pub fn pretty(mut self, pretty: bool) -> Self { - self.pretty = pretty; - self - } - - /// Display backtrace if available when using pretty output format. - /// - /// # Examples - /// - /// **Note**: Report will search for the first `Backtrace` it can find starting from the - /// outermost error. In this example it will display the backtrace from the second error in the - /// sources, `SuperErrorSideKick`. - /// - /// ```rust - /// #![feature(error_reporter)] - /// #![feature(error_generic_member_access)] - /// # use std::error::Error; - /// # use std::fmt; - /// use std::error::Request; - /// use std::error::Report; - /// use std::backtrace::Backtrace; - /// - /// # #[derive(Debug)] - /// # struct SuperError { - /// # source: SuperErrorSideKick, - /// # } - /// # impl fmt::Display for SuperError { - /// # fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - /// # write!(f, "SuperError is here!") - /// # } - /// # } - /// # impl Error for SuperError { - /// # fn source(&self) -> Option<&(dyn Error + 'static)> { - /// # Some(&self.source) - /// # } - /// # } - /// #[derive(Debug)] - /// struct SuperErrorSideKick { - /// backtrace: Backtrace, - /// } - /// - /// impl SuperErrorSideKick { - /// fn new() -> SuperErrorSideKick { - /// SuperErrorSideKick { backtrace: Backtrace::force_capture() } - /// } - /// } - /// - /// impl Error for SuperErrorSideKick { - /// fn provide<'a>(&'a self, request: &mut Request<'a>) { - /// request.provide_ref::(&self.backtrace); - /// } - /// } - /// - /// // The rest of the example is unchanged ... - /// # impl fmt::Display for SuperErrorSideKick { - /// # fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - /// # write!(f, "SuperErrorSideKick is here!") - /// # } - /// # } - /// - /// let source = SuperErrorSideKick::new(); - /// let error = SuperError { source }; - /// let report = Report::new(error).pretty(true).show_backtrace(true); - /// eprintln!("Error: {report:?}"); - /// ``` - /// - /// This example produces something similar to the following output: - /// - /// ```console - /// Error: SuperError is here! - /// - /// Caused by: - /// SuperErrorSideKick is here! - /// - /// Stack backtrace: - /// 0: rust_out::main::_doctest_main_src_error_rs_1158_0::SuperErrorSideKick::new - /// 1: rust_out::main::_doctest_main_src_error_rs_1158_0 - /// 2: rust_out::main - /// 3: core::ops::function::FnOnce::call_once - /// 4: std::sys_common::backtrace::__rust_begin_short_backtrace - /// 5: std::rt::lang_start::{{closure}} - /// 6: std::panicking::try - /// 7: std::rt::lang_start_internal - /// 8: std::rt::lang_start - /// 9: main - /// 10: __libc_start_main - /// 11: _start - /// ``` - #[unstable(feature = "error_reporter", issue = "90172")] - pub fn show_backtrace(mut self, show_backtrace: bool) -> Self { - self.show_backtrace = show_backtrace; - self - } -} - -impl Report -where - E: Error, -{ - fn backtrace(&self) -> Option<&Backtrace> { - // have to grab the backtrace on the first error directly since that error may not be - // 'static - let backtrace = request_ref(&self.error); - let backtrace = backtrace.or_else(|| { - self.error - .source() - .map(|source| source.sources().find_map(|source| request_ref(source))) - .flatten() - }); - backtrace - } - - /// Format the report as a single line. - #[unstable(feature = "error_reporter", issue = "90172")] - fn fmt_singleline(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "{}", self.error)?; - - let sources = self.error.source().into_iter().flat_map(::sources); - - for cause in sources { - write!(f, ": {cause}")?; - } - - Ok(()) - } - - /// Format the report as multiple lines, with each error cause on its own line. - #[unstable(feature = "error_reporter", issue = "90172")] - fn fmt_multiline(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let error = &self.error; - - write!(f, "{error}")?; - - if let Some(cause) = error.source() { - write!(f, "\n\nCaused by:")?; - - let multiple = cause.source().is_some(); - - for (ind, error) in cause.sources().enumerate() { - writeln!(f)?; - let mut indented = Indented { inner: f }; - if multiple { - write!(indented, "{ind: >4}: {error}")?; - } else { - write!(indented, " {error}")?; - } - } - } - - if self.show_backtrace { - let backtrace = self.backtrace(); - - if let Some(backtrace) = backtrace { - let backtrace = backtrace.to_string(); - - f.write_str("\n\nStack backtrace:\n")?; - f.write_str(backtrace.trim_end())?; - } - } - - Ok(()) - } -} - -#[unstable(feature = "error_reporter", issue = "90172")] -impl From for Report -where - E: Error, -{ - fn from(error: E) -> Self { - Report { error, show_backtrace: false, pretty: false } - } -} - -#[unstable(feature = "error_reporter", issue = "90172")] -impl fmt::Display for Report -where - E: Error, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - if self.pretty { self.fmt_multiline(f) } else { self.fmt_singleline(f) } - } -} - -// This type intentionally outputs the same format for `Display` and `Debug`for -// situations where you unwrap a `Report` or return it from main. -#[unstable(feature = "error_reporter", issue = "90172")] -impl fmt::Debug for Report -where - Report: fmt::Display, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt(self, f) - } -} - -/// Wrapper type for indenting the inner source. -struct Indented<'a, D> { - inner: &'a mut D, -} - -impl Write for Indented<'_, T> -where - T: Write, -{ - fn write_str(&mut self, s: &str) -> fmt::Result { - for (i, line) in s.split('\n').enumerate() { - if i > 0 { - self.inner.write_char('\n')?; - self.inner.write_str(" ")?; - } - - self.inner.write_str(line)?; - } - - Ok(()) - } -} diff --git a/library/std/src/error/tests.rs b/library/std/src/error/tests.rs deleted file mode 100644 index ed070a26b0cf0..0000000000000 --- a/library/std/src/error/tests.rs +++ /dev/null @@ -1,443 +0,0 @@ -use super::Error; -use crate::fmt; -use core::error::Request; - -#[derive(Debug, PartialEq)] -struct A; -#[derive(Debug, PartialEq)] -struct B; - -impl fmt::Display for A { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "A") - } -} -impl fmt::Display for B { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "B") - } -} - -impl Error for A {} -impl Error for B {} - -#[test] -fn downcasting() { - let mut a = A; - let a = &mut a as &mut (dyn Error + 'static); - assert_eq!(a.downcast_ref::
(), Some(&A)); - assert_eq!(a.downcast_ref::(), None); - assert_eq!(a.downcast_mut::(), Some(&mut A)); - assert_eq!(a.downcast_mut::(), None); - - let a: Box = Box::new(A); - match a.downcast::() { - Ok(..) => panic!("expected error"), - Err(e) => assert_eq!(*e.downcast::().unwrap(), A), - } -} - -use crate::backtrace::Backtrace; -use crate::error::Report; - -#[derive(Debug)] -struct SuperError { - source: SuperErrorSideKick, -} - -impl fmt::Display for SuperError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "SuperError is here!") - } -} - -impl Error for SuperError { - fn source(&self) -> Option<&(dyn Error + 'static)> { - Some(&self.source) - } -} - -#[derive(Debug)] -struct SuperErrorSideKick; - -impl fmt::Display for SuperErrorSideKick { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "SuperErrorSideKick is here!") - } -} - -impl Error for SuperErrorSideKick {} - -#[test] -fn single_line_formatting() { - let error = SuperError { source: SuperErrorSideKick }; - let report = Report::new(&error); - let actual = report.to_string(); - let expected = String::from("SuperError is here!: SuperErrorSideKick is here!"); - - assert_eq!(expected, actual); -} - -#[test] -fn multi_line_formatting() { - let error = SuperError { source: SuperErrorSideKick }; - let report = Report::new(&error).pretty(true); - let actual = report.to_string(); - let expected = String::from( - "\ -SuperError is here! - -Caused by: - SuperErrorSideKick is here!", - ); - - assert_eq!(expected, actual); -} - -#[test] -fn error_with_no_sources_formats_single_line_correctly() { - let report = Report::new(SuperErrorSideKick); - let actual = report.to_string(); - let expected = String::from("SuperErrorSideKick is here!"); - - assert_eq!(expected, actual); -} - -#[test] -fn error_with_no_sources_formats_multi_line_correctly() { - let report = Report::new(SuperErrorSideKick).pretty(true); - let actual = report.to_string(); - let expected = String::from("SuperErrorSideKick is here!"); - - assert_eq!(expected, actual); -} - -#[test] -fn error_with_backtrace_outputs_correctly_with_one_source() { - let trace = Backtrace::force_capture(); - let expected = format!( - "\ -The source of the error - -Caused by: - Error with backtrace - -Stack backtrace: -{}", - trace - ); - let error = GenericError::new("Error with backtrace"); - let mut error = GenericError::new_with_source("The source of the error", error); - error.backtrace = Some(trace); - let report = Report::new(error).pretty(true).show_backtrace(true); - - println!("Error: {report}"); - assert_eq!(expected.trim_end(), report.to_string()); -} - -#[test] -fn error_with_backtrace_outputs_correctly_with_two_sources() { - let trace = Backtrace::force_capture(); - let expected = format!( - "\ -Error with two sources - -Caused by: - 0: The source of the error - 1: Error with backtrace - -Stack backtrace: -{}", - trace - ); - let mut error = GenericError::new("Error with backtrace"); - error.backtrace = Some(trace); - let error = GenericError::new_with_source("The source of the error", error); - let error = GenericError::new_with_source("Error with two sources", error); - let report = Report::new(error).pretty(true).show_backtrace(true); - - println!("Error: {report}"); - assert_eq!(expected.trim_end(), report.to_string()); -} - -#[derive(Debug)] -struct GenericError { - message: D, - backtrace: Option, - source: Option>, -} - -impl GenericError { - fn new(message: D) -> GenericError { - Self { message, backtrace: None, source: None } - } - - fn new_with_source(message: D, source: E) -> GenericError - where - E: Error + 'static, - { - let source: Box = Box::new(source); - let source = Some(source); - GenericError { message, backtrace: None, source } - } -} - -impl fmt::Display for GenericError -where - D: fmt::Display, -{ - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt(&self.message, f) - } -} - -impl Error for GenericError -where - D: fmt::Debug + fmt::Display, -{ - fn source(&self) -> Option<&(dyn Error + 'static)> { - self.source.as_deref() - } - - fn provide<'a>(&'a self, req: &mut Request<'a>) { - self.backtrace.as_ref().map(|bt| req.provide_ref::(bt)); - } -} - -#[test] -fn error_formats_single_line_with_rude_display_impl() { - #[derive(Debug)] - struct MyMessage; - - impl fmt::Display for MyMessage { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str("line 1\nline 2")?; - f.write_str("\nline 3\nline 4\n")?; - f.write_str("line 5\nline 6")?; - Ok(()) - } - } - - let error = GenericError::new(MyMessage); - let error = GenericError::new_with_source(MyMessage, error); - let error = GenericError::new_with_source(MyMessage, error); - let error = GenericError::new_with_source(MyMessage, error); - let report = Report::new(error); - let expected = "\ -line 1 -line 2 -line 3 -line 4 -line 5 -line 6: line 1 -line 2 -line 3 -line 4 -line 5 -line 6: line 1 -line 2 -line 3 -line 4 -line 5 -line 6: line 1 -line 2 -line 3 -line 4 -line 5 -line 6"; - - let actual = report.to_string(); - assert_eq!(expected, actual); -} - -#[test] -fn error_formats_multi_line_with_rude_display_impl() { - #[derive(Debug)] - struct MyMessage; - - impl fmt::Display for MyMessage { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str("line 1\nline 2")?; - f.write_str("\nline 3\nline 4\n")?; - f.write_str("line 5\nline 6")?; - Ok(()) - } - } - - let error = GenericError::new(MyMessage); - let error = GenericError::new_with_source(MyMessage, error); - let error = GenericError::new_with_source(MyMessage, error); - let error = GenericError::new_with_source(MyMessage, error); - let report = Report::new(error).pretty(true); - let expected = "line 1 -line 2 -line 3 -line 4 -line 5 -line 6 - -Caused by: - 0: line 1 - line 2 - line 3 - line 4 - line 5 - line 6 - 1: line 1 - line 2 - line 3 - line 4 - line 5 - line 6 - 2: line 1 - line 2 - line 3 - line 4 - line 5 - line 6"; - - let actual = report.to_string(); - assert_eq!(expected, actual); -} - -#[test] -fn errors_that_start_with_newline_formats_correctly() { - #[derive(Debug)] - struct MyMessage; - - impl fmt::Display for MyMessage { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str("\nThe message\n") - } - } - - let error = GenericError::new(MyMessage); - let error = GenericError::new_with_source(MyMessage, error); - let error = GenericError::new_with_source(MyMessage, error); - let report = Report::new(error).pretty(true); - let expected = " -The message - - -Caused by: - 0: \ -\n The message - \ -\n 1: \ -\n The message - "; - - let actual = report.to_string(); - assert_eq!(expected, actual); -} - -#[test] -fn errors_with_multiple_writes_on_same_line_dont_insert_erroneous_newlines() { - #[derive(Debug)] - struct MyMessage; - - impl fmt::Display for MyMessage { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str("The message")?; - f.write_str(" goes on")?; - f.write_str(" and on.") - } - } - - let error = GenericError::new(MyMessage); - let error = GenericError::new_with_source(MyMessage, error); - let error = GenericError::new_with_source(MyMessage, error); - let report = Report::new(error).pretty(true); - let expected = "\ -The message goes on and on. - -Caused by: - 0: The message goes on and on. - 1: The message goes on and on."; - - let actual = report.to_string(); - println!("{actual}"); - assert_eq!(expected, actual); -} - -#[test] -fn errors_with_string_interpolation_formats_correctly() { - #[derive(Debug)] - struct MyMessage(usize); - - impl fmt::Display for MyMessage { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "Got an error code: ({}). ", self.0)?; - write!(f, "What would you like to do in response?") - } - } - - let error = GenericError::new(MyMessage(10)); - let error = GenericError::new_with_source(MyMessage(20), error); - let report = Report::new(error).pretty(true); - let expected = "\ -Got an error code: (20). What would you like to do in response? - -Caused by: - Got an error code: (10). What would you like to do in response?"; - let actual = report.to_string(); - assert_eq!(expected, actual); -} - -#[test] -fn empty_lines_mid_message() { - #[derive(Debug)] - struct MyMessage; - - impl fmt::Display for MyMessage { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str("line 1\n\nline 2") - } - } - - let error = GenericError::new(MyMessage); - let error = GenericError::new_with_source(MyMessage, error); - let error = GenericError::new_with_source(MyMessage, error); - let report = Report::new(error).pretty(true); - let expected = "\ -line 1 - -line 2 - -Caused by: - 0: line 1 - \ -\n line 2 - 1: line 1 - \ -\n line 2"; - - let actual = report.to_string(); - assert_eq!(expected, actual); -} - -#[test] -fn only_one_source() { - #[derive(Debug)] - struct MyMessage; - - impl fmt::Display for MyMessage { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str("line 1\nline 2") - } - } - - let error = GenericError::new(MyMessage); - let error = GenericError::new_with_source(MyMessage, error); - let report = Report::new(error).pretty(true); - let expected = "\ -line 1 -line 2 - -Caused by: - line 1 - line 2"; - - let actual = report.to_string(); - assert_eq!(expected, actual); -} diff --git a/library/std/src/f128.rs b/library/std/src/f128.rs deleted file mode 100644 index 491235a872eaf..0000000000000 --- a/library/std/src/f128.rs +++ /dev/null @@ -1,35 +0,0 @@ -//! Constants for the `f128` double-precision floating point type. -//! -//! *[See also the `f128` primitive type](primitive@f128).* -//! -//! Mathematically significant numbers are provided in the `consts` sub-module. - -#[cfg(test)] -mod tests; - -#[cfg(not(test))] -use crate::intrinsics; - -#[unstable(feature = "f128", issue = "116909")] -pub use core::f128::consts; - -#[cfg(not(test))] -impl f128 { - /// Raises a number to an integer power. - /// - /// Using this function is generally faster than using `powf`. - /// It might have a different sequence of rounding operations than `powf`, - /// so the results are not guaranteed to agree. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - #[inline] - #[rustc_allow_incoherent_impl] - #[unstable(feature = "f128", issue = "116909")] - #[must_use = "method returns a new number and does not mutate the original value"] - pub fn powi(self, n: i32) -> f128 { - unsafe { intrinsics::powif128(self, n) } - } -} diff --git a/library/std/src/f128/tests.rs b/library/std/src/f128/tests.rs deleted file mode 100644 index b64c7f856a15f..0000000000000 --- a/library/std/src/f128/tests.rs +++ /dev/null @@ -1,40 +0,0 @@ -#![allow(dead_code)] // FIXME(f16_f128): remove once constants are used - -/// Smallest number -const TINY_BITS: u128 = 0x1; -/// Next smallest number -const TINY_UP_BITS: u128 = 0x2; -/// Exponent = 0b11...10, Sifnificand 0b1111..10. Min val > 0 -const MAX_DOWN_BITS: u128 = 0x7ffeffffffffffffffffffffffffffff; -/// Zeroed exponent, full significant -const LARGEST_SUBNORMAL_BITS: u128 = 0x0000ffffffffffffffffffffffffffff; -/// Exponent = 0b1, zeroed significand -const SMALLEST_NORMAL_BITS: u128 = 0x00010000000000000000000000000000; -/// First pattern over the mantissa -const NAN_MASK1: u128 = 0x0000aaaaaaaaaaaaaaaaaaaaaaaaaaaa; -/// Second pattern over the mantissa -const NAN_MASK2: u128 = 0x00005555555555555555555555555555; - -/// Compare by value -#[allow(unused_macros)] -macro_rules! assert_f128_eq { - ($a:expr, $b:expr) => { - let (l, r): (&f128, &f128) = (&$a, &$b); - assert_eq!(*l, *r, "\na: {:#0130x}\nb: {:#0130x}", l.to_bits(), r.to_bits()) - }; -} - -/// Compare by representation -#[allow(unused_macros)] -macro_rules! assert_f128_biteq { - ($a:expr, $b:expr) => { - let (l, r): (&f128, &f128) = (&$a, &$b); - let lb = l.to_bits(); - let rb = r.to_bits(); - assert_eq!( - lb, rb, - "float {:?} is not bitequal to {:?}.\na: {:#0130x}\nb: {:#0130x}", - *l, *r, lb, rb - ); - }; -} diff --git a/library/std/src/f16.rs b/library/std/src/f16.rs deleted file mode 100644 index 1cb655ffabd84..0000000000000 --- a/library/std/src/f16.rs +++ /dev/null @@ -1,35 +0,0 @@ -//! Constants for the `f16` double-precision floating point type. -//! -//! *[See also the `f16` primitive type](primitive@f16).* -//! -//! Mathematically significant numbers are provided in the `consts` sub-module. - -#[cfg(test)] -mod tests; - -#[cfg(not(test))] -use crate::intrinsics; - -#[unstable(feature = "f16", issue = "116909")] -pub use core::f16::consts; - -#[cfg(not(test))] -impl f16 { - /// Raises a number to an integer power. - /// - /// Using this function is generally faster than using `powf`. - /// It might have a different sequence of rounding operations than `powf`, - /// so the results are not guaranteed to agree. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - #[inline] - #[rustc_allow_incoherent_impl] - #[unstable(feature = "f16", issue = "116909")] - #[must_use = "method returns a new number and does not mutate the original value"] - pub fn powi(self, n: i32) -> f16 { - unsafe { intrinsics::powif16(self, n) } - } -} diff --git a/library/std/src/f16/tests.rs b/library/std/src/f16/tests.rs deleted file mode 100644 index d65c43eca4bb8..0000000000000 --- a/library/std/src/f16/tests.rs +++ /dev/null @@ -1,46 +0,0 @@ -#![allow(dead_code)] // FIXME(f16_f128): remove once constants are used - -// We run out of precision pretty quickly with f16 -const F16_APPROX_L1: f16 = 0.001; -const F16_APPROX_L2: f16 = 0.01; -const F16_APPROX_L3: f16 = 0.1; -const F16_APPROX_L4: f16 = 0.5; - -/// Smallest number -const TINY_BITS: u16 = 0x1; -/// Next smallest number -const TINY_UP_BITS: u16 = 0x2; -/// Exponent = 0b11...10, Sifnificand 0b1111..10. Min val > 0 -const MAX_DOWN_BITS: u16 = 0x7bfe; -/// Zeroed exponent, full significant -const LARGEST_SUBNORMAL_BITS: u16 = 0x03ff; -/// Exponent = 0b1, zeroed significand -const SMALLEST_NORMAL_BITS: u16 = 0x0400; -/// First pattern over the mantissa -const NAN_MASK1: u16 = 0x02aa; -/// Second pattern over the mantissa -const NAN_MASK2: u16 = 0x0155; - -/// Compare by value -#[allow(unused_macros)] -macro_rules! assert_f16_eq { - ($a:expr, $b:expr) => { - let (l, r): (&f16, &f16) = (&$a, &$b); - assert_eq!(*l, *r, "\na: {:#018x}\nb: {:#018x}", l.to_bits(), r.to_bits()) - }; -} - -/// Compare by representation -#[allow(unused_macros)] -macro_rules! assert_f16_biteq { - ($a:expr, $b:expr) => { - let (l, r): (&f16, &f16) = (&$a, &$b); - let lb = l.to_bits(); - let rb = r.to_bits(); - assert_eq!( - lb, rb, - "float {:?} is not bitequal to {:?}.\na: {:#018x}\nb: {:#018x}", - *l, *r, lb, rb - ); - }; -} diff --git a/library/std/src/f32.rs b/library/std/src/f32.rs deleted file mode 100644 index 4fc82fec0adbc..0000000000000 --- a/library/std/src/f32.rs +++ /dev/null @@ -1,1228 +0,0 @@ -//! Constants for the `f32` single-precision floating point type. -//! -//! *[See also the `f32` primitive type](primitive@f32).* -//! -//! Mathematically significant numbers are provided in the `consts` sub-module. -//! -//! For the constants defined directly in this module -//! (as distinct from those defined in the `consts` sub-module), -//! new code should instead use the associated constants -//! defined directly on the `f32` type. - -#![stable(feature = "rust1", since = "1.0.0")] -#![allow(missing_docs)] - -#[cfg(test)] -mod tests; - -#[cfg(not(test))] -use crate::intrinsics; -#[cfg(not(test))] -use crate::sys::cmath; - -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated, deprecated_in_future)] -pub use core::f32::{ - consts, DIGITS, EPSILON, INFINITY, MANTISSA_DIGITS, MAX, MAX_10_EXP, MAX_EXP, MIN, MIN_10_EXP, - MIN_EXP, MIN_POSITIVE, NAN, NEG_INFINITY, RADIX, -}; - -#[cfg(not(test))] -impl f32 { - /// Returns the largest integer less than or equal to `self`. - /// - /// This function always returns the precise result. - /// - /// # Examples - /// - /// ``` - /// let f = 3.7_f32; - /// let g = 3.0_f32; - /// let h = -3.7_f32; - /// - /// assert_eq!(f.floor(), 3.0); - /// assert_eq!(g.floor(), 3.0); - /// assert_eq!(h.floor(), -4.0); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn floor(self) -> f32 { - unsafe { intrinsics::floorf32(self) } - } - - /// Returns the smallest integer greater than or equal to `self`. - /// - /// This function always returns the precise result. - /// - /// # Examples - /// - /// ``` - /// let f = 3.01_f32; - /// let g = 4.0_f32; - /// - /// assert_eq!(f.ceil(), 4.0); - /// assert_eq!(g.ceil(), 4.0); - /// ``` - #[doc(alias = "ceiling")] - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn ceil(self) -> f32 { - unsafe { intrinsics::ceilf32(self) } - } - - /// Returns the nearest integer to `self`. If a value is half-way between two - /// integers, round away from `0.0`. - /// - /// This function always returns the precise result. - /// - /// # Examples - /// - /// ``` - /// let f = 3.3_f32; - /// let g = -3.3_f32; - /// let h = -3.7_f32; - /// let i = 3.5_f32; - /// let j = 4.5_f32; - /// - /// assert_eq!(f.round(), 3.0); - /// assert_eq!(g.round(), -3.0); - /// assert_eq!(h.round(), -4.0); - /// assert_eq!(i.round(), 4.0); - /// assert_eq!(j.round(), 5.0); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn round(self) -> f32 { - unsafe { intrinsics::roundf32(self) } - } - - /// Returns the nearest integer to a number. Rounds half-way cases to the number - /// with an even least significant digit. - /// - /// This function always returns the precise result. - /// - /// # Examples - /// - /// ``` - /// let f = 3.3_f32; - /// let g = -3.3_f32; - /// let h = 3.5_f32; - /// let i = 4.5_f32; - /// - /// assert_eq!(f.round_ties_even(), 3.0); - /// assert_eq!(g.round_ties_even(), -3.0); - /// assert_eq!(h.round_ties_even(), 4.0); - /// assert_eq!(i.round_ties_even(), 4.0); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "round_ties_even", since = "1.77.0")] - #[inline] - pub fn round_ties_even(self) -> f32 { - unsafe { intrinsics::rintf32(self) } - } - - /// Returns the integer part of `self`. - /// This means that non-integer numbers are always truncated towards zero. - /// - /// This function always returns the precise result. - /// - /// # Examples - /// - /// ``` - /// let f = 3.7_f32; - /// let g = 3.0_f32; - /// let h = -3.7_f32; - /// - /// assert_eq!(f.trunc(), 3.0); - /// assert_eq!(g.trunc(), 3.0); - /// assert_eq!(h.trunc(), -3.0); - /// ``` - #[doc(alias = "truncate")] - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn trunc(self) -> f32 { - unsafe { intrinsics::truncf32(self) } - } - - /// Returns the fractional part of `self`. - /// - /// This function always returns the precise result. - /// - /// # Examples - /// - /// ``` - /// let x = 3.6_f32; - /// let y = -3.6_f32; - /// let abs_difference_x = (x.fract() - 0.6).abs(); - /// let abs_difference_y = (y.fract() - (-0.6)).abs(); - /// - /// assert!(abs_difference_x <= f32::EPSILON); - /// assert!(abs_difference_y <= f32::EPSILON); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn fract(self) -> f32 { - self - self.trunc() - } - - /// Computes the absolute value of `self`. - /// - /// This function always returns the precise result. - /// - /// # Examples - /// - /// ``` - /// let x = 3.5_f32; - /// let y = -3.5_f32; - /// - /// assert_eq!(x.abs(), x); - /// assert_eq!(y.abs(), -y); - /// - /// assert!(f32::NAN.abs().is_nan()); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn abs(self) -> f32 { - unsafe { intrinsics::fabsf32(self) } - } - - /// Returns a number that represents the sign of `self`. - /// - /// - `1.0` if the number is positive, `+0.0` or `INFINITY` - /// - `-1.0` if the number is negative, `-0.0` or `NEG_INFINITY` - /// - NaN if the number is NaN - /// - /// # Examples - /// - /// ``` - /// let f = 3.5_f32; - /// - /// assert_eq!(f.signum(), 1.0); - /// assert_eq!(f32::NEG_INFINITY.signum(), -1.0); - /// - /// assert!(f32::NAN.signum().is_nan()); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn signum(self) -> f32 { - if self.is_nan() { Self::NAN } else { 1.0_f32.copysign(self) } - } - - /// Returns a number composed of the magnitude of `self` and the sign of - /// `sign`. - /// - /// Equal to `self` if the sign of `self` and `sign` are the same, otherwise - /// equal to `-self`. If `self` is a NaN, then a NaN with the sign bit of - /// `sign` is returned. Note, however, that conserving the sign bit on NaN - /// across arithmetical operations is not generally guaranteed. - /// See [explanation of NaN as a special value](primitive@f32) for more info. - /// - /// # Examples - /// - /// ``` - /// let f = 3.5_f32; - /// - /// assert_eq!(f.copysign(0.42), 3.5_f32); - /// assert_eq!(f.copysign(-0.42), -3.5_f32); - /// assert_eq!((-f).copysign(0.42), 3.5_f32); - /// assert_eq!((-f).copysign(-0.42), -3.5_f32); - /// - /// assert!(f32::NAN.copysign(1.0).is_nan()); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[inline] - #[stable(feature = "copysign", since = "1.35.0")] - pub fn copysign(self, sign: f32) -> f32 { - unsafe { intrinsics::copysignf32(self, sign) } - } - - /// Fused multiply-add. Computes `(self * a) + b` with only one rounding - /// error, yielding a more accurate result than an unfused multiply-add. - /// - /// Using `mul_add` *may* be more performant than an unfused multiply-add if - /// the target architecture has a dedicated `fma` CPU instruction. However, - /// this is not always true, and will be heavily dependant on designing - /// algorithms with specific target hardware in mind. - /// - /// # Precision - /// - /// The result of this operation is guaranteed to be the rounded - /// infinite-precision result. It is specified by IEEE 754 as - /// `fusedMultiplyAdd` and guaranteed not to change. - /// - /// # Examples - /// - /// ``` - /// let m = 10.0_f32; - /// let x = 4.0_f32; - /// let b = 60.0_f32; - /// - /// assert_eq!(m.mul_add(x, b), 100.0); - /// assert_eq!(m * x + b, 100.0); - /// - /// let one_plus_eps = 1.0_f32 + f32::EPSILON; - /// let one_minus_eps = 1.0_f32 - f32::EPSILON; - /// let minus_one = -1.0_f32; - /// - /// // The exact result (1 + eps) * (1 - eps) = 1 - eps * eps. - /// assert_eq!(one_plus_eps.mul_add(one_minus_eps, minus_one), -f32::EPSILON * f32::EPSILON); - /// // Different rounding with the non-fused multiply and add. - /// assert_eq!(one_plus_eps * one_minus_eps + minus_one, 0.0); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn mul_add(self, a: f32, b: f32) -> f32 { - unsafe { intrinsics::fmaf32(self, a, b) } - } - - /// Calculates Euclidean division, the matching method for `rem_euclid`. - /// - /// This computes the integer `n` such that - /// `self = n * rhs + self.rem_euclid(rhs)`. - /// In other words, the result is `self / rhs` rounded to the integer `n` - /// such that `self >= n * rhs`. - /// - /// # Precision - /// - /// The result of this operation is guaranteed to be the rounded - /// infinite-precision result. - /// - /// # Examples - /// - /// ``` - /// let a: f32 = 7.0; - /// let b = 4.0; - /// assert_eq!(a.div_euclid(b), 1.0); // 7.0 > 4.0 * 1.0 - /// assert_eq!((-a).div_euclid(b), -2.0); // -7.0 >= 4.0 * -2.0 - /// assert_eq!(a.div_euclid(-b), -1.0); // 7.0 >= -4.0 * -1.0 - /// assert_eq!((-a).div_euclid(-b), 2.0); // -7.0 >= -4.0 * 2.0 - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[inline] - #[stable(feature = "euclidean_division", since = "1.38.0")] - pub fn div_euclid(self, rhs: f32) -> f32 { - let q = (self / rhs).trunc(); - if self % rhs < 0.0 { - return if rhs > 0.0 { q - 1.0 } else { q + 1.0 }; - } - q - } - - /// Calculates the least nonnegative remainder of `self (mod rhs)`. - /// - /// In particular, the return value `r` satisfies `0.0 <= r < rhs.abs()` in - /// most cases. However, due to a floating point round-off error it can - /// result in `r == rhs.abs()`, violating the mathematical definition, if - /// `self` is much smaller than `rhs.abs()` in magnitude and `self < 0.0`. - /// This result is not an element of the function's codomain, but it is the - /// closest floating point number in the real numbers and thus fulfills the - /// property `self == self.div_euclid(rhs) * rhs + self.rem_euclid(rhs)` - /// approximately. - /// - /// # Precision - /// - /// The result of this operation is guaranteed to be the rounded - /// infinite-precision result. - /// - /// # Examples - /// - /// ``` - /// let a: f32 = 7.0; - /// let b = 4.0; - /// assert_eq!(a.rem_euclid(b), 3.0); - /// assert_eq!((-a).rem_euclid(b), 1.0); - /// assert_eq!(a.rem_euclid(-b), 3.0); - /// assert_eq!((-a).rem_euclid(-b), 1.0); - /// // limitation due to round-off error - /// assert!((-f32::EPSILON).rem_euclid(3.0) != 0.0); - /// ``` - #[doc(alias = "modulo", alias = "mod")] - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[inline] - #[stable(feature = "euclidean_division", since = "1.38.0")] - pub fn rem_euclid(self, rhs: f32) -> f32 { - let r = self % rhs; - if r < 0.0 { r + rhs.abs() } else { r } - } - - /// Raises a number to an integer power. - /// - /// Using this function is generally faster than using `powf`. - /// It might have a different sequence of rounding operations than `powf`, - /// so the results are not guaranteed to agree. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let x = 2.0_f32; - /// let abs_difference = (x.powi(2) - (x * x)).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn powi(self, n: i32) -> f32 { - unsafe { intrinsics::powif32(self, n) } - } - - /// Raises a number to a floating point power. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let x = 2.0_f32; - /// let abs_difference = (x.powf(2.0) - (x * x)).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn powf(self, n: f32) -> f32 { - unsafe { intrinsics::powf32(self, n) } - } - - /// Returns the square root of a number. - /// - /// Returns NaN if `self` is a negative number other than `-0.0`. - /// - /// # Precision - /// - /// The result of this operation is guaranteed to be the rounded - /// infinite-precision result. It is specified by IEEE 754 as `squareRoot` - /// and guaranteed not to change. - /// - /// # Examples - /// - /// ``` - /// let positive = 4.0_f32; - /// let negative = -4.0_f32; - /// let negative_zero = -0.0_f32; - /// - /// assert_eq!(positive.sqrt(), 2.0); - /// assert!(negative.sqrt().is_nan()); - /// assert!(negative_zero.sqrt() == negative_zero); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn sqrt(self) -> f32 { - unsafe { intrinsics::sqrtf32(self) } - } - - /// Returns `e^(self)`, (the exponential function). - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let one = 1.0f32; - /// // e^1 - /// let e = one.exp(); - /// - /// // ln(e) - 1 == 0 - /// let abs_difference = (e.ln() - 1.0).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn exp(self) -> f32 { - unsafe { intrinsics::expf32(self) } - } - - /// Returns `2^(self)`. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let f = 2.0f32; - /// - /// // 2^2 - 4 == 0 - /// let abs_difference = (f.exp2() - 4.0).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn exp2(self) -> f32 { - unsafe { intrinsics::exp2f32(self) } - } - - /// Returns the natural logarithm of the number. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let one = 1.0f32; - /// // e^1 - /// let e = one.exp(); - /// - /// // ln(e) - 1 == 0 - /// let abs_difference = (e.ln() - 1.0).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn ln(self) -> f32 { - unsafe { intrinsics::logf32(self) } - } - - /// Returns the logarithm of the number with respect to an arbitrary base. - /// - /// The result might not be correctly rounded owing to implementation details; - /// `self.log2()` can produce more accurate results for base 2, and - /// `self.log10()` can produce more accurate results for base 10. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let five = 5.0f32; - /// - /// // log5(5) - 1 == 0 - /// let abs_difference = (five.log(5.0) - 1.0).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn log(self, base: f32) -> f32 { - self.ln() / base.ln() - } - - /// Returns the base 2 logarithm of the number. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let two = 2.0f32; - /// - /// // log2(2) - 1 == 0 - /// let abs_difference = (two.log2() - 1.0).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn log2(self) -> f32 { - crate::sys::log2f32(self) - } - - /// Returns the base 10 logarithm of the number. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let ten = 10.0f32; - /// - /// // log10(10) - 1 == 0 - /// let abs_difference = (ten.log10() - 1.0).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn log10(self) -> f32 { - unsafe { intrinsics::log10f32(self) } - } - - /// The positive difference of two numbers. - /// - /// * If `self <= other`: `0.0` - /// * Else: `self - other` - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `fdimf` from libc on Unix - /// and Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let x = 3.0f32; - /// let y = -3.0f32; - /// - /// let abs_difference_x = (x.abs_sub(1.0) - 2.0).abs(); - /// let abs_difference_y = (y.abs_sub(1.0) - 0.0).abs(); - /// - /// assert!(abs_difference_x <= f32::EPSILON); - /// assert!(abs_difference_y <= f32::EPSILON); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - #[deprecated( - since = "1.10.0", - note = "you probably meant `(self - other).abs()`: \ - this operation is `(self - other).max(0.0)` \ - except that `abs_sub` also propagates NaNs (also \ - known as `fdimf` in C). If you truly need the positive \ - difference, consider using that expression or the C function \ - `fdimf`, depending on how you wish to handle NaN (please consider \ - filing an issue describing your use-case too)." - )] - pub fn abs_sub(self, other: f32) -> f32 { - unsafe { cmath::fdimf(self, other) } - } - - /// Returns the cube root of a number. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `cbrtf` from libc on Unix - /// and Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let x = 8.0f32; - /// - /// // x^(1/3) - 2 == 0 - /// let abs_difference = (x.cbrt() - 2.0).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn cbrt(self) -> f32 { - unsafe { cmath::cbrtf(self) } - } - - /// Compute the distance between the origin and a point (`x`, `y`) on the - /// Euclidean plane. Equivalently, compute the length of the hypotenuse of a - /// right-angle triangle with other sides having length `x.abs()` and - /// `y.abs()`. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `hypotf` from libc on Unix - /// and Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let x = 2.0f32; - /// let y = 3.0f32; - /// - /// // sqrt(x^2 + y^2) - /// let abs_difference = (x.hypot(y) - (x.powi(2) + y.powi(2)).sqrt()).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn hypot(self, other: f32) -> f32 { - unsafe { cmath::hypotf(self, other) } - } - - /// Computes the sine of a number (in radians). - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let x = std::f32::consts::FRAC_PI_2; - /// - /// let abs_difference = (x.sin() - 1.0).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn sin(self) -> f32 { - unsafe { intrinsics::sinf32(self) } - } - - /// Computes the cosine of a number (in radians). - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let x = 2.0 * std::f32::consts::PI; - /// - /// let abs_difference = (x.cos() - 1.0).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn cos(self) -> f32 { - unsafe { intrinsics::cosf32(self) } - } - - /// Computes the tangent of a number (in radians). - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `tanf` from libc on Unix and - /// Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let x = std::f32::consts::FRAC_PI_4; - /// let abs_difference = (x.tan() - 1.0).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn tan(self) -> f32 { - unsafe { cmath::tanf(self) } - } - - /// Computes the arcsine of a number. Return value is in radians in - /// the range [-pi/2, pi/2] or NaN if the number is outside the range - /// [-1, 1]. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `asinf` from libc on Unix - /// and Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let f = std::f32::consts::FRAC_PI_2; - /// - /// // asin(sin(pi/2)) - /// let abs_difference = (f.sin().asin() - std::f32::consts::FRAC_PI_2).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[doc(alias = "arcsin")] - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn asin(self) -> f32 { - unsafe { cmath::asinf(self) } - } - - /// Computes the arccosine of a number. Return value is in radians in - /// the range [0, pi] or NaN if the number is outside the range - /// [-1, 1]. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `acosf` from libc on Unix - /// and Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let f = std::f32::consts::FRAC_PI_4; - /// - /// // acos(cos(pi/4)) - /// let abs_difference = (f.cos().acos() - std::f32::consts::FRAC_PI_4).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[doc(alias = "arccos")] - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn acos(self) -> f32 { - unsafe { cmath::acosf(self) } - } - - /// Computes the arctangent of a number. Return value is in radians in the - /// range [-pi/2, pi/2]; - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `atanf` from libc on Unix - /// and Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let f = 1.0f32; - /// - /// // atan(tan(1)) - /// let abs_difference = (f.tan().atan() - 1.0).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[doc(alias = "arctan")] - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn atan(self) -> f32 { - unsafe { cmath::atanf(self) } - } - - /// Computes the four quadrant arctangent of `self` (`y`) and `other` (`x`) in radians. - /// - /// * `x = 0`, `y = 0`: `0` - /// * `x >= 0`: `arctan(y/x)` -> `[-pi/2, pi/2]` - /// * `y >= 0`: `arctan(y/x) + pi` -> `(pi/2, pi]` - /// * `y < 0`: `arctan(y/x) - pi` -> `(-pi, -pi/2)` - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `atan2f` from libc on Unix - /// and Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// // Positive angles measured counter-clockwise - /// // from positive x axis - /// // -pi/4 radians (45 deg clockwise) - /// let x1 = 3.0f32; - /// let y1 = -3.0f32; - /// - /// // 3pi/4 radians (135 deg counter-clockwise) - /// let x2 = -3.0f32; - /// let y2 = 3.0f32; - /// - /// let abs_difference_1 = (y1.atan2(x1) - (-std::f32::consts::FRAC_PI_4)).abs(); - /// let abs_difference_2 = (y2.atan2(x2) - (3.0 * std::f32::consts::FRAC_PI_4)).abs(); - /// - /// assert!(abs_difference_1 <= f32::EPSILON); - /// assert!(abs_difference_2 <= f32::EPSILON); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn atan2(self, other: f32) -> f32 { - unsafe { cmath::atan2f(self, other) } - } - - /// Simultaneously computes the sine and cosine of the number, `x`. Returns - /// `(sin(x), cos(x))`. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `(f32::sin(x), - /// f32::cos(x))`. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let x = std::f32::consts::FRAC_PI_4; - /// let f = x.sin_cos(); - /// - /// let abs_difference_0 = (f.0 - x.sin()).abs(); - /// let abs_difference_1 = (f.1 - x.cos()).abs(); - /// - /// assert!(abs_difference_0 <= f32::EPSILON); - /// assert!(abs_difference_1 <= f32::EPSILON); - /// ``` - #[doc(alias = "sincos")] - #[rustc_allow_incoherent_impl] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn sin_cos(self) -> (f32, f32) { - (self.sin(), self.cos()) - } - - /// Returns `e^(self) - 1` in a way that is accurate even if the - /// number is close to zero. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `expm1f` from libc on Unix - /// and Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let x = 1e-8_f32; - /// - /// // for very small x, e^x is approximately 1 + x + x^2 / 2 - /// let approx = x + x * x / 2.0; - /// let abs_difference = (x.exp_m1() - approx).abs(); - /// - /// assert!(abs_difference < 1e-10); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn exp_m1(self) -> f32 { - unsafe { cmath::expm1f(self) } - } - - /// Returns `ln(1+n)` (natural logarithm) more accurately than if - /// the operations were performed separately. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `log1pf` from libc on Unix - /// and Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let x = 1e-8_f32; - /// - /// // for very small x, ln(1 + x) is approximately x - x^2 / 2 - /// let approx = x - x * x / 2.0; - /// let abs_difference = (x.ln_1p() - approx).abs(); - /// - /// assert!(abs_difference < 1e-10); - /// ``` - #[doc(alias = "log1p")] - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn ln_1p(self) -> f32 { - unsafe { cmath::log1pf(self) } - } - - /// Hyperbolic sine function. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `sinhf` from libc on Unix - /// and Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let e = std::f32::consts::E; - /// let x = 1.0f32; - /// - /// let f = x.sinh(); - /// // Solving sinh() at 1 gives `(e^2-1)/(2e)` - /// let g = ((e * e) - 1.0) / (2.0 * e); - /// let abs_difference = (f - g).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn sinh(self) -> f32 { - unsafe { cmath::sinhf(self) } - } - - /// Hyperbolic cosine function. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `coshf` from libc on Unix - /// and Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let e = std::f32::consts::E; - /// let x = 1.0f32; - /// let f = x.cosh(); - /// // Solving cosh() at 1 gives this result - /// let g = ((e * e) + 1.0) / (2.0 * e); - /// let abs_difference = (f - g).abs(); - /// - /// // Same result - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn cosh(self) -> f32 { - unsafe { cmath::coshf(self) } - } - - /// Hyperbolic tangent function. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `tanhf` from libc on Unix - /// and Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let e = std::f32::consts::E; - /// let x = 1.0f32; - /// - /// let f = x.tanh(); - /// // Solving tanh() at 1 gives `(1 - e^(-2))/(1 + e^(-2))` - /// let g = (1.0 - e.powi(-2)) / (1.0 + e.powi(-2)); - /// let abs_difference = (f - g).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn tanh(self) -> f32 { - unsafe { cmath::tanhf(self) } - } - - /// Inverse hyperbolic sine function. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let x = 1.0f32; - /// let f = x.sinh().asinh(); - /// - /// let abs_difference = (f - x).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[doc(alias = "arcsinh")] - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn asinh(self) -> f32 { - let ax = self.abs(); - let ix = 1.0 / ax; - (ax + (ax / (Self::hypot(1.0, ix) + ix))).ln_1p().copysign(self) - } - - /// Inverse hyperbolic cosine function. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let x = 1.0f32; - /// let f = x.cosh().acosh(); - /// - /// let abs_difference = (f - x).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[doc(alias = "arccosh")] - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn acosh(self) -> f32 { - if self < 1.0 { - Self::NAN - } else { - (self + ((self - 1.0).sqrt() * (self + 1.0).sqrt())).ln() - } - } - - /// Inverse hyperbolic tangent function. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let e = std::f32::consts::E; - /// let f = e.tanh().atanh(); - /// - /// let abs_difference = (f - e).abs(); - /// - /// assert!(abs_difference <= 1e-5); - /// ``` - #[doc(alias = "arctanh")] - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn atanh(self) -> f32 { - 0.5 * ((2.0 * self) / (1.0 - self)).ln_1p() - } - - /// Gamma function. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `tgammaf` from libc on Unix - /// and Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// #![feature(float_gamma)] - /// let x = 5.0f32; - /// - /// let abs_difference = (x.gamma() - 24.0).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[unstable(feature = "float_gamma", issue = "99842")] - #[inline] - pub fn gamma(self) -> f32 { - unsafe { cmath::tgammaf(self) } - } - - /// Natural logarithm of the absolute value of the gamma function - /// - /// The integer part of the tuple indicates the sign of the gamma function. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `lgamma_r` from libc on Unix - /// and Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// #![feature(float_gamma)] - /// let x = 2.0f32; - /// - /// let abs_difference = (x.ln_gamma().0 - 0.0).abs(); - /// - /// assert!(abs_difference <= f32::EPSILON); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[unstable(feature = "float_gamma", issue = "99842")] - #[inline] - pub fn ln_gamma(self) -> (f32, i32) { - let mut signgamp: i32 = 0; - let x = unsafe { cmath::lgammaf_r(self, &mut signgamp) }; - (x, signgamp) - } -} diff --git a/library/std/src/f32/tests.rs b/library/std/src/f32/tests.rs deleted file mode 100644 index 9ca4e8f2f45fe..0000000000000 --- a/library/std/src/f32/tests.rs +++ /dev/null @@ -1,905 +0,0 @@ -use crate::f32::consts; -use crate::num::FpCategory as Fp; -use crate::num::*; - -#[test] -fn test_num_f32() { - test_num(10f32, 2f32); -} - -#[test] -fn test_min_nan() { - assert_eq!(f32::NAN.min(2.0), 2.0); - assert_eq!(2.0f32.min(f32::NAN), 2.0); -} - -#[test] -fn test_max_nan() { - assert_eq!(f32::NAN.max(2.0), 2.0); - assert_eq!(2.0f32.max(f32::NAN), 2.0); -} - -#[test] -fn test_minimum() { - assert!(f32::NAN.minimum(2.0).is_nan()); - assert!(2.0f32.minimum(f32::NAN).is_nan()); -} - -#[test] -fn test_maximum() { - assert!(f32::NAN.maximum(2.0).is_nan()); - assert!(2.0f32.maximum(f32::NAN).is_nan()); -} - -#[test] -fn test_nan() { - let nan: f32 = f32::NAN; - assert!(nan.is_nan()); - assert!(!nan.is_infinite()); - assert!(!nan.is_finite()); - assert!(!nan.is_normal()); - assert!(nan.is_sign_positive()); - assert!(!nan.is_sign_negative()); - assert_eq!(Fp::Nan, nan.classify()); -} - -#[test] -fn test_infinity() { - let inf: f32 = f32::INFINITY; - assert!(inf.is_infinite()); - assert!(!inf.is_finite()); - assert!(inf.is_sign_positive()); - assert!(!inf.is_sign_negative()); - assert!(!inf.is_nan()); - assert!(!inf.is_normal()); - assert_eq!(Fp::Infinite, inf.classify()); -} - -#[test] -fn test_neg_infinity() { - let neg_inf: f32 = f32::NEG_INFINITY; - assert!(neg_inf.is_infinite()); - assert!(!neg_inf.is_finite()); - assert!(!neg_inf.is_sign_positive()); - assert!(neg_inf.is_sign_negative()); - assert!(!neg_inf.is_nan()); - assert!(!neg_inf.is_normal()); - assert_eq!(Fp::Infinite, neg_inf.classify()); -} - -#[test] -fn test_zero() { - let zero: f32 = 0.0f32; - assert_eq!(0.0, zero); - assert!(!zero.is_infinite()); - assert!(zero.is_finite()); - assert!(zero.is_sign_positive()); - assert!(!zero.is_sign_negative()); - assert!(!zero.is_nan()); - assert!(!zero.is_normal()); - assert_eq!(Fp::Zero, zero.classify()); -} - -#[test] -fn test_neg_zero() { - let neg_zero: f32 = -0.0; - assert_eq!(0.0, neg_zero); - assert!(!neg_zero.is_infinite()); - assert!(neg_zero.is_finite()); - assert!(!neg_zero.is_sign_positive()); - assert!(neg_zero.is_sign_negative()); - assert!(!neg_zero.is_nan()); - assert!(!neg_zero.is_normal()); - assert_eq!(Fp::Zero, neg_zero.classify()); -} - -#[test] -fn test_one() { - let one: f32 = 1.0f32; - assert_eq!(1.0, one); - assert!(!one.is_infinite()); - assert!(one.is_finite()); - assert!(one.is_sign_positive()); - assert!(!one.is_sign_negative()); - assert!(!one.is_nan()); - assert!(one.is_normal()); - assert_eq!(Fp::Normal, one.classify()); -} - -#[test] -fn test_is_nan() { - let nan: f32 = f32::NAN; - let inf: f32 = f32::INFINITY; - let neg_inf: f32 = f32::NEG_INFINITY; - assert!(nan.is_nan()); - assert!(!0.0f32.is_nan()); - assert!(!5.3f32.is_nan()); - assert!(!(-10.732f32).is_nan()); - assert!(!inf.is_nan()); - assert!(!neg_inf.is_nan()); -} - -#[test] -fn test_is_infinite() { - let nan: f32 = f32::NAN; - let inf: f32 = f32::INFINITY; - let neg_inf: f32 = f32::NEG_INFINITY; - assert!(!nan.is_infinite()); - assert!(inf.is_infinite()); - assert!(neg_inf.is_infinite()); - assert!(!0.0f32.is_infinite()); - assert!(!42.8f32.is_infinite()); - assert!(!(-109.2f32).is_infinite()); -} - -#[test] -fn test_is_finite() { - let nan: f32 = f32::NAN; - let inf: f32 = f32::INFINITY; - let neg_inf: f32 = f32::NEG_INFINITY; - assert!(!nan.is_finite()); - assert!(!inf.is_finite()); - assert!(!neg_inf.is_finite()); - assert!(0.0f32.is_finite()); - assert!(42.8f32.is_finite()); - assert!((-109.2f32).is_finite()); -} - -#[test] -fn test_is_normal() { - let nan: f32 = f32::NAN; - let inf: f32 = f32::INFINITY; - let neg_inf: f32 = f32::NEG_INFINITY; - let zero: f32 = 0.0f32; - let neg_zero: f32 = -0.0; - assert!(!nan.is_normal()); - assert!(!inf.is_normal()); - assert!(!neg_inf.is_normal()); - assert!(!zero.is_normal()); - assert!(!neg_zero.is_normal()); - assert!(1f32.is_normal()); - assert!(1e-37f32.is_normal()); - assert!(!1e-38f32.is_normal()); -} - -#[test] -fn test_classify() { - let nan: f32 = f32::NAN; - let inf: f32 = f32::INFINITY; - let neg_inf: f32 = f32::NEG_INFINITY; - let zero: f32 = 0.0f32; - let neg_zero: f32 = -0.0; - assert_eq!(nan.classify(), Fp::Nan); - assert_eq!(inf.classify(), Fp::Infinite); - assert_eq!(neg_inf.classify(), Fp::Infinite); - assert_eq!(zero.classify(), Fp::Zero); - assert_eq!(neg_zero.classify(), Fp::Zero); - assert_eq!(1f32.classify(), Fp::Normal); - assert_eq!(1e-37f32.classify(), Fp::Normal); - assert_eq!(1e-38f32.classify(), Fp::Subnormal); -} - -#[test] -fn test_floor() { - assert_approx_eq!(1.0f32.floor(), 1.0f32); - assert_approx_eq!(1.3f32.floor(), 1.0f32); - assert_approx_eq!(1.5f32.floor(), 1.0f32); - assert_approx_eq!(1.7f32.floor(), 1.0f32); - assert_approx_eq!(0.0f32.floor(), 0.0f32); - assert_approx_eq!((-0.0f32).floor(), -0.0f32); - assert_approx_eq!((-1.0f32).floor(), -1.0f32); - assert_approx_eq!((-1.3f32).floor(), -2.0f32); - assert_approx_eq!((-1.5f32).floor(), -2.0f32); - assert_approx_eq!((-1.7f32).floor(), -2.0f32); -} - -#[test] -fn test_ceil() { - assert_approx_eq!(1.0f32.ceil(), 1.0f32); - assert_approx_eq!(1.3f32.ceil(), 2.0f32); - assert_approx_eq!(1.5f32.ceil(), 2.0f32); - assert_approx_eq!(1.7f32.ceil(), 2.0f32); - assert_approx_eq!(0.0f32.ceil(), 0.0f32); - assert_approx_eq!((-0.0f32).ceil(), -0.0f32); - assert_approx_eq!((-1.0f32).ceil(), -1.0f32); - assert_approx_eq!((-1.3f32).ceil(), -1.0f32); - assert_approx_eq!((-1.5f32).ceil(), -1.0f32); - assert_approx_eq!((-1.7f32).ceil(), -1.0f32); -} - -#[test] -fn test_round() { - assert_approx_eq!(2.5f32.round(), 3.0f32); - assert_approx_eq!(1.0f32.round(), 1.0f32); - assert_approx_eq!(1.3f32.round(), 1.0f32); - assert_approx_eq!(1.5f32.round(), 2.0f32); - assert_approx_eq!(1.7f32.round(), 2.0f32); - assert_approx_eq!(0.0f32.round(), 0.0f32); - assert_approx_eq!((-0.0f32).round(), -0.0f32); - assert_approx_eq!((-1.0f32).round(), -1.0f32); - assert_approx_eq!((-1.3f32).round(), -1.0f32); - assert_approx_eq!((-1.5f32).round(), -2.0f32); - assert_approx_eq!((-1.7f32).round(), -2.0f32); -} - -#[test] -fn test_round_ties_even() { - assert_approx_eq!(2.5f32.round_ties_even(), 2.0f32); - assert_approx_eq!(1.0f32.round_ties_even(), 1.0f32); - assert_approx_eq!(1.3f32.round_ties_even(), 1.0f32); - assert_approx_eq!(1.5f32.round_ties_even(), 2.0f32); - assert_approx_eq!(1.7f32.round_ties_even(), 2.0f32); - assert_approx_eq!(0.0f32.round_ties_even(), 0.0f32); - assert_approx_eq!((-0.0f32).round_ties_even(), -0.0f32); - assert_approx_eq!((-1.0f32).round_ties_even(), -1.0f32); - assert_approx_eq!((-1.3f32).round_ties_even(), -1.0f32); - assert_approx_eq!((-1.5f32).round_ties_even(), -2.0f32); - assert_approx_eq!((-1.7f32).round_ties_even(), -2.0f32); -} - -#[test] -fn test_trunc() { - assert_approx_eq!(1.0f32.trunc(), 1.0f32); - assert_approx_eq!(1.3f32.trunc(), 1.0f32); - assert_approx_eq!(1.5f32.trunc(), 1.0f32); - assert_approx_eq!(1.7f32.trunc(), 1.0f32); - assert_approx_eq!(0.0f32.trunc(), 0.0f32); - assert_approx_eq!((-0.0f32).trunc(), -0.0f32); - assert_approx_eq!((-1.0f32).trunc(), -1.0f32); - assert_approx_eq!((-1.3f32).trunc(), -1.0f32); - assert_approx_eq!((-1.5f32).trunc(), -1.0f32); - assert_approx_eq!((-1.7f32).trunc(), -1.0f32); -} - -#[test] -fn test_fract() { - assert_approx_eq!(1.0f32.fract(), 0.0f32); - assert_approx_eq!(1.3f32.fract(), 0.3f32); - assert_approx_eq!(1.5f32.fract(), 0.5f32); - assert_approx_eq!(1.7f32.fract(), 0.7f32); - assert_approx_eq!(0.0f32.fract(), 0.0f32); - assert_approx_eq!((-0.0f32).fract(), -0.0f32); - assert_approx_eq!((-1.0f32).fract(), -0.0f32); - assert_approx_eq!((-1.3f32).fract(), -0.3f32); - assert_approx_eq!((-1.5f32).fract(), -0.5f32); - assert_approx_eq!((-1.7f32).fract(), -0.7f32); -} - -#[test] -fn test_abs() { - assert_eq!(f32::INFINITY.abs(), f32::INFINITY); - assert_eq!(1f32.abs(), 1f32); - assert_eq!(0f32.abs(), 0f32); - assert_eq!((-0f32).abs(), 0f32); - assert_eq!((-1f32).abs(), 1f32); - assert_eq!(f32::NEG_INFINITY.abs(), f32::INFINITY); - assert_eq!((1f32 / f32::NEG_INFINITY).abs(), 0f32); - assert!(f32::NAN.abs().is_nan()); -} - -#[test] -fn test_signum() { - assert_eq!(f32::INFINITY.signum(), 1f32); - assert_eq!(1f32.signum(), 1f32); - assert_eq!(0f32.signum(), 1f32); - assert_eq!((-0f32).signum(), -1f32); - assert_eq!((-1f32).signum(), -1f32); - assert_eq!(f32::NEG_INFINITY.signum(), -1f32); - assert_eq!((1f32 / f32::NEG_INFINITY).signum(), -1f32); - assert!(f32::NAN.signum().is_nan()); -} - -#[test] -fn test_is_sign_positive() { - assert!(f32::INFINITY.is_sign_positive()); - assert!(1f32.is_sign_positive()); - assert!(0f32.is_sign_positive()); - assert!(!(-0f32).is_sign_positive()); - assert!(!(-1f32).is_sign_positive()); - assert!(!f32::NEG_INFINITY.is_sign_positive()); - assert!(!(1f32 / f32::NEG_INFINITY).is_sign_positive()); - assert!(f32::NAN.is_sign_positive()); - assert!(!(-f32::NAN).is_sign_positive()); -} - -#[test] -fn test_is_sign_negative() { - assert!(!f32::INFINITY.is_sign_negative()); - assert!(!1f32.is_sign_negative()); - assert!(!0f32.is_sign_negative()); - assert!((-0f32).is_sign_negative()); - assert!((-1f32).is_sign_negative()); - assert!(f32::NEG_INFINITY.is_sign_negative()); - assert!((1f32 / f32::NEG_INFINITY).is_sign_negative()); - assert!(!f32::NAN.is_sign_negative()); - assert!((-f32::NAN).is_sign_negative()); -} - -#[allow(unused_macros)] -macro_rules! assert_f32_biteq { - ($left : expr, $right : expr) => { - let l: &f32 = &$left; - let r: &f32 = &$right; - let lb = l.to_bits(); - let rb = r.to_bits(); - assert_eq!(lb, rb, "float {} ({:#x}) is not equal to {} ({:#x})", *l, lb, *r, rb); - }; -} - -// Ignore test on x87 floating point, these platforms do not guarantee NaN -// payloads are preserved and flush denormals to zero, failing the tests. -#[cfg(not(target_arch = "x86"))] -#[test] -fn test_next_up() { - let tiny = f32::from_bits(1); - let tiny_up = f32::from_bits(2); - let max_down = f32::from_bits(0x7f7f_fffe); - let largest_subnormal = f32::from_bits(0x007f_ffff); - let smallest_normal = f32::from_bits(0x0080_0000); - assert_f32_biteq!(f32::NEG_INFINITY.next_up(), f32::MIN); - assert_f32_biteq!(f32::MIN.next_up(), -max_down); - assert_f32_biteq!((-1.0 - f32::EPSILON).next_up(), -1.0); - assert_f32_biteq!((-smallest_normal).next_up(), -largest_subnormal); - assert_f32_biteq!((-tiny_up).next_up(), -tiny); - assert_f32_biteq!((-tiny).next_up(), -0.0f32); - assert_f32_biteq!((-0.0f32).next_up(), tiny); - assert_f32_biteq!(0.0f32.next_up(), tiny); - assert_f32_biteq!(tiny.next_up(), tiny_up); - assert_f32_biteq!(largest_subnormal.next_up(), smallest_normal); - assert_f32_biteq!(1.0f32.next_up(), 1.0 + f32::EPSILON); - assert_f32_biteq!(f32::MAX.next_up(), f32::INFINITY); - assert_f32_biteq!(f32::INFINITY.next_up(), f32::INFINITY); - - // Check that NaNs roundtrip. - let nan0 = f32::NAN; - let nan1 = f32::from_bits(f32::NAN.to_bits() ^ 0x002a_aaaa); - let nan2 = f32::from_bits(f32::NAN.to_bits() ^ 0x0055_5555); - assert_f32_biteq!(nan0.next_up(), nan0); - assert_f32_biteq!(nan1.next_up(), nan1); - assert_f32_biteq!(nan2.next_up(), nan2); -} - -// Ignore test on x87 floating point, these platforms do not guarantee NaN -// payloads are preserved and flush denormals to zero, failing the tests. -#[cfg(not(target_arch = "x86"))] -#[test] -fn test_next_down() { - let tiny = f32::from_bits(1); - let tiny_up = f32::from_bits(2); - let max_down = f32::from_bits(0x7f7f_fffe); - let largest_subnormal = f32::from_bits(0x007f_ffff); - let smallest_normal = f32::from_bits(0x0080_0000); - assert_f32_biteq!(f32::NEG_INFINITY.next_down(), f32::NEG_INFINITY); - assert_f32_biteq!(f32::MIN.next_down(), f32::NEG_INFINITY); - assert_f32_biteq!((-max_down).next_down(), f32::MIN); - assert_f32_biteq!((-1.0f32).next_down(), -1.0 - f32::EPSILON); - assert_f32_biteq!((-largest_subnormal).next_down(), -smallest_normal); - assert_f32_biteq!((-tiny).next_down(), -tiny_up); - assert_f32_biteq!((-0.0f32).next_down(), -tiny); - assert_f32_biteq!((0.0f32).next_down(), -tiny); - assert_f32_biteq!(tiny.next_down(), 0.0f32); - assert_f32_biteq!(tiny_up.next_down(), tiny); - assert_f32_biteq!(smallest_normal.next_down(), largest_subnormal); - assert_f32_biteq!((1.0 + f32::EPSILON).next_down(), 1.0f32); - assert_f32_biteq!(f32::MAX.next_down(), max_down); - assert_f32_biteq!(f32::INFINITY.next_down(), f32::MAX); - - // Check that NaNs roundtrip. - let nan0 = f32::NAN; - let nan1 = f32::from_bits(f32::NAN.to_bits() ^ 0x002a_aaaa); - let nan2 = f32::from_bits(f32::NAN.to_bits() ^ 0x0055_5555); - assert_f32_biteq!(nan0.next_down(), nan0); - assert_f32_biteq!(nan1.next_down(), nan1); - assert_f32_biteq!(nan2.next_down(), nan2); -} - -#[test] -fn test_mul_add() { - let nan: f32 = f32::NAN; - let inf: f32 = f32::INFINITY; - let neg_inf: f32 = f32::NEG_INFINITY; - assert_approx_eq!(12.3f32.mul_add(4.5, 6.7), 62.05); - assert_approx_eq!((-12.3f32).mul_add(-4.5, -6.7), 48.65); - assert_approx_eq!(0.0f32.mul_add(8.9, 1.2), 1.2); - assert_approx_eq!(3.4f32.mul_add(-0.0, 5.6), 5.6); - assert!(nan.mul_add(7.8, 9.0).is_nan()); - assert_eq!(inf.mul_add(7.8, 9.0), inf); - assert_eq!(neg_inf.mul_add(7.8, 9.0), neg_inf); - assert_eq!(8.9f32.mul_add(inf, 3.2), inf); - assert_eq!((-3.2f32).mul_add(2.4, neg_inf), neg_inf); -} - -#[test] -fn test_recip() { - let nan: f32 = f32::NAN; - let inf: f32 = f32::INFINITY; - let neg_inf: f32 = f32::NEG_INFINITY; - assert_eq!(1.0f32.recip(), 1.0); - assert_eq!(2.0f32.recip(), 0.5); - assert_eq!((-0.4f32).recip(), -2.5); - assert_eq!(0.0f32.recip(), inf); - assert!(nan.recip().is_nan()); - assert_eq!(inf.recip(), 0.0); - assert_eq!(neg_inf.recip(), 0.0); -} - -#[test] -fn test_powi() { - let nan: f32 = f32::NAN; - let inf: f32 = f32::INFINITY; - let neg_inf: f32 = f32::NEG_INFINITY; - assert_eq!(1.0f32.powi(1), 1.0); - assert_approx_eq!((-3.1f32).powi(2), 9.61); - assert_approx_eq!(5.9f32.powi(-2), 0.028727); - assert_eq!(8.3f32.powi(0), 1.0); - assert!(nan.powi(2).is_nan()); - assert_eq!(inf.powi(3), inf); - assert_eq!(neg_inf.powi(2), inf); -} - -#[test] -fn test_powf() { - let nan: f32 = f32::NAN; - let inf: f32 = f32::INFINITY; - let neg_inf: f32 = f32::NEG_INFINITY; - assert_eq!(1.0f32.powf(1.0), 1.0); - assert_approx_eq!(3.4f32.powf(4.5), 246.408218); - assert_approx_eq!(2.7f32.powf(-3.2), 0.041652); - assert_approx_eq!((-3.1f32).powf(2.0), 9.61); - assert_approx_eq!(5.9f32.powf(-2.0), 0.028727); - assert_eq!(8.3f32.powf(0.0), 1.0); - assert!(nan.powf(2.0).is_nan()); - assert_eq!(inf.powf(2.0), inf); - assert_eq!(neg_inf.powf(3.0), neg_inf); -} - -#[test] -fn test_sqrt_domain() { - assert!(f32::NAN.sqrt().is_nan()); - assert!(f32::NEG_INFINITY.sqrt().is_nan()); - assert!((-1.0f32).sqrt().is_nan()); - assert_eq!((-0.0f32).sqrt(), -0.0); - assert_eq!(0.0f32.sqrt(), 0.0); - assert_eq!(1.0f32.sqrt(), 1.0); - assert_eq!(f32::INFINITY.sqrt(), f32::INFINITY); -} - -#[test] -fn test_exp() { - assert_eq!(1.0, 0.0f32.exp()); - assert_approx_eq!(2.718282, 1.0f32.exp()); - assert_approx_eq!(148.413162, 5.0f32.exp()); - - let inf: f32 = f32::INFINITY; - let neg_inf: f32 = f32::NEG_INFINITY; - let nan: f32 = f32::NAN; - assert_eq!(inf, inf.exp()); - assert_eq!(0.0, neg_inf.exp()); - assert!(nan.exp().is_nan()); -} - -#[test] -fn test_exp2() { - assert_eq!(32.0, 5.0f32.exp2()); - assert_eq!(1.0, 0.0f32.exp2()); - - let inf: f32 = f32::INFINITY; - let neg_inf: f32 = f32::NEG_INFINITY; - let nan: f32 = f32::NAN; - assert_eq!(inf, inf.exp2()); - assert_eq!(0.0, neg_inf.exp2()); - assert!(nan.exp2().is_nan()); -} - -#[test] -fn test_ln() { - let nan: f32 = f32::NAN; - let inf: f32 = f32::INFINITY; - let neg_inf: f32 = f32::NEG_INFINITY; - assert_approx_eq!(1.0f32.exp().ln(), 1.0); - assert!(nan.ln().is_nan()); - assert_eq!(inf.ln(), inf); - assert!(neg_inf.ln().is_nan()); - assert!((-2.3f32).ln().is_nan()); - assert_eq!((-0.0f32).ln(), neg_inf); - assert_eq!(0.0f32.ln(), neg_inf); - assert_approx_eq!(4.0f32.ln(), 1.386294); -} - -#[test] -fn test_log() { - let nan: f32 = f32::NAN; - let inf: f32 = f32::INFINITY; - let neg_inf: f32 = f32::NEG_INFINITY; - assert_eq!(10.0f32.log(10.0), 1.0); - assert_approx_eq!(2.3f32.log(3.5), 0.664858); - assert_eq!(1.0f32.exp().log(1.0f32.exp()), 1.0); - assert!(1.0f32.log(1.0).is_nan()); - assert!(1.0f32.log(-13.9).is_nan()); - assert!(nan.log(2.3).is_nan()); - assert_eq!(inf.log(10.0), inf); - assert!(neg_inf.log(8.8).is_nan()); - assert!((-2.3f32).log(0.1).is_nan()); - assert_eq!((-0.0f32).log(2.0), neg_inf); - assert_eq!(0.0f32.log(7.0), neg_inf); -} - -#[test] -fn test_log2() { - let nan: f32 = f32::NAN; - let inf: f32 = f32::INFINITY; - let neg_inf: f32 = f32::NEG_INFINITY; - assert_approx_eq!(10.0f32.log2(), 3.321928); - assert_approx_eq!(2.3f32.log2(), 1.201634); - assert_approx_eq!(1.0f32.exp().log2(), 1.442695); - assert!(nan.log2().is_nan()); - assert_eq!(inf.log2(), inf); - assert!(neg_inf.log2().is_nan()); - assert!((-2.3f32).log2().is_nan()); - assert_eq!((-0.0f32).log2(), neg_inf); - assert_eq!(0.0f32.log2(), neg_inf); -} - -#[test] -fn test_log10() { - let nan: f32 = f32::NAN; - let inf: f32 = f32::INFINITY; - let neg_inf: f32 = f32::NEG_INFINITY; - assert_eq!(10.0f32.log10(), 1.0); - assert_approx_eq!(2.3f32.log10(), 0.361728); - assert_approx_eq!(1.0f32.exp().log10(), 0.434294); - assert_eq!(1.0f32.log10(), 0.0); - assert!(nan.log10().is_nan()); - assert_eq!(inf.log10(), inf); - assert!(neg_inf.log10().is_nan()); - assert!((-2.3f32).log10().is_nan()); - assert_eq!((-0.0f32).log10(), neg_inf); - assert_eq!(0.0f32.log10(), neg_inf); -} - -#[test] -fn test_to_degrees() { - let pi: f32 = consts::PI; - let nan: f32 = f32::NAN; - let inf: f32 = f32::INFINITY; - let neg_inf: f32 = f32::NEG_INFINITY; - assert_eq!(0.0f32.to_degrees(), 0.0); - assert_approx_eq!((-5.8f32).to_degrees(), -332.315521); - assert_eq!(pi.to_degrees(), 180.0); - assert!(nan.to_degrees().is_nan()); - assert_eq!(inf.to_degrees(), inf); - assert_eq!(neg_inf.to_degrees(), neg_inf); - assert_eq!(1_f32.to_degrees(), 57.2957795130823208767981548141051703); -} - -#[test] -fn test_to_radians() { - let pi: f32 = consts::PI; - let nan: f32 = f32::NAN; - let inf: f32 = f32::INFINITY; - let neg_inf: f32 = f32::NEG_INFINITY; - assert_eq!(0.0f32.to_radians(), 0.0); - assert_approx_eq!(154.6f32.to_radians(), 2.698279); - assert_approx_eq!((-332.31f32).to_radians(), -5.799903); - assert_eq!(180.0f32.to_radians(), pi); - assert!(nan.to_radians().is_nan()); - assert_eq!(inf.to_radians(), inf); - assert_eq!(neg_inf.to_radians(), neg_inf); -} - -#[test] -fn test_asinh() { - assert_eq!(0.0f32.asinh(), 0.0f32); - assert_eq!((-0.0f32).asinh(), -0.0f32); - - let inf: f32 = f32::INFINITY; - let neg_inf: f32 = f32::NEG_INFINITY; - let nan: f32 = f32::NAN; - assert_eq!(inf.asinh(), inf); - assert_eq!(neg_inf.asinh(), neg_inf); - assert!(nan.asinh().is_nan()); - assert!((-0.0f32).asinh().is_sign_negative()); // issue 63271 - assert_approx_eq!(2.0f32.asinh(), 1.443635475178810342493276740273105f32); - assert_approx_eq!((-2.0f32).asinh(), -1.443635475178810342493276740273105f32); - // regression test for the catastrophic cancellation fixed in 72486 - assert_approx_eq!((-3000.0f32).asinh(), -8.699514775987968673236893537700647f32); - - // test for low accuracy from issue 104548 - assert_approx_eq!(60.0f32, 60.0f32.sinh().asinh()); - // mul needed for approximate comparison to be meaningful - assert_approx_eq!(1.0f32, 1e-15f32.sinh().asinh() * 1e15f32); -} - -#[test] -fn test_acosh() { - assert_eq!(1.0f32.acosh(), 0.0f32); - assert!(0.999f32.acosh().is_nan()); - - let inf: f32 = f32::INFINITY; - let neg_inf: f32 = f32::NEG_INFINITY; - let nan: f32 = f32::NAN; - assert_eq!(inf.acosh(), inf); - assert!(neg_inf.acosh().is_nan()); - assert!(nan.acosh().is_nan()); - assert_approx_eq!(2.0f32.acosh(), 1.31695789692481670862504634730796844f32); - assert_approx_eq!(3.0f32.acosh(), 1.76274717403908605046521864995958461f32); - - // test for low accuracy from issue 104548 - assert_approx_eq!(60.0f32, 60.0f32.cosh().acosh()); -} - -#[test] -fn test_atanh() { - assert_eq!(0.0f32.atanh(), 0.0f32); - assert_eq!((-0.0f32).atanh(), -0.0f32); - - let inf32: f32 = f32::INFINITY; - let neg_inf32: f32 = f32::NEG_INFINITY; - assert_eq!(1.0f32.atanh(), inf32); - assert_eq!((-1.0f32).atanh(), neg_inf32); - - assert!(2f64.atanh().atanh().is_nan()); - assert!((-2f64).atanh().atanh().is_nan()); - - let inf64: f32 = f32::INFINITY; - let neg_inf64: f32 = f32::NEG_INFINITY; - let nan32: f32 = f32::NAN; - assert!(inf64.atanh().is_nan()); - assert!(neg_inf64.atanh().is_nan()); - assert!(nan32.atanh().is_nan()); - - assert_approx_eq!(0.5f32.atanh(), 0.54930614433405484569762261846126285f32); - assert_approx_eq!((-0.5f32).atanh(), -0.54930614433405484569762261846126285f32); -} - -#[test] -fn test_gamma() { - // precision can differ between platforms - assert_approx_eq!(1.0f32.gamma(), 1.0f32); - assert_approx_eq!(2.0f32.gamma(), 1.0f32); - assert_approx_eq!(3.0f32.gamma(), 2.0f32); - assert_approx_eq!(4.0f32.gamma(), 6.0f32); - assert_approx_eq!(5.0f32.gamma(), 24.0f32); - assert_approx_eq!(0.5f32.gamma(), consts::PI.sqrt()); - assert_approx_eq!((-0.5f32).gamma(), -2.0 * consts::PI.sqrt()); - assert_eq!(0.0f32.gamma(), f32::INFINITY); - assert_eq!((-0.0f32).gamma(), f32::NEG_INFINITY); - assert!((-1.0f32).gamma().is_nan()); - assert!((-2.0f32).gamma().is_nan()); - assert!(f32::NAN.gamma().is_nan()); - assert!(f32::NEG_INFINITY.gamma().is_nan()); - assert_eq!(f32::INFINITY.gamma(), f32::INFINITY); - assert_eq!(171.71f32.gamma(), f32::INFINITY); -} - -#[test] -fn test_ln_gamma() { - assert_approx_eq!(1.0f32.ln_gamma().0, 0.0f32); - assert_eq!(1.0f32.ln_gamma().1, 1); - assert_approx_eq!(2.0f32.ln_gamma().0, 0.0f32); - assert_eq!(2.0f32.ln_gamma().1, 1); - assert_approx_eq!(3.0f32.ln_gamma().0, 2.0f32.ln()); - assert_eq!(3.0f32.ln_gamma().1, 1); - assert_approx_eq!((-0.5f32).ln_gamma().0, (2.0 * consts::PI.sqrt()).ln()); - assert_eq!((-0.5f32).ln_gamma().1, -1); -} - -#[test] -fn test_real_consts() { - use super::consts; - - let pi: f32 = consts::PI; - let frac_pi_2: f32 = consts::FRAC_PI_2; - let frac_pi_3: f32 = consts::FRAC_PI_3; - let frac_pi_4: f32 = consts::FRAC_PI_4; - let frac_pi_6: f32 = consts::FRAC_PI_6; - let frac_pi_8: f32 = consts::FRAC_PI_8; - let frac_1_pi: f32 = consts::FRAC_1_PI; - let frac_2_pi: f32 = consts::FRAC_2_PI; - let frac_2_sqrtpi: f32 = consts::FRAC_2_SQRT_PI; - let sqrt2: f32 = consts::SQRT_2; - let frac_1_sqrt2: f32 = consts::FRAC_1_SQRT_2; - let e: f32 = consts::E; - let log2_e: f32 = consts::LOG2_E; - let log10_e: f32 = consts::LOG10_E; - let ln_2: f32 = consts::LN_2; - let ln_10: f32 = consts::LN_10; - - assert_approx_eq!(frac_pi_2, pi / 2f32); - assert_approx_eq!(frac_pi_3, pi / 3f32); - assert_approx_eq!(frac_pi_4, pi / 4f32); - assert_approx_eq!(frac_pi_6, pi / 6f32); - assert_approx_eq!(frac_pi_8, pi / 8f32); - assert_approx_eq!(frac_1_pi, 1f32 / pi); - assert_approx_eq!(frac_2_pi, 2f32 / pi); - assert_approx_eq!(frac_2_sqrtpi, 2f32 / pi.sqrt()); - assert_approx_eq!(sqrt2, 2f32.sqrt()); - assert_approx_eq!(frac_1_sqrt2, 1f32 / 2f32.sqrt()); - assert_approx_eq!(log2_e, e.log2()); - assert_approx_eq!(log10_e, e.log10()); - assert_approx_eq!(ln_2, 2f32.ln()); - assert_approx_eq!(ln_10, 10f32.ln()); -} - -#[test] -fn test_float_bits_conv() { - assert_eq!((1f32).to_bits(), 0x3f800000); - assert_eq!((12.5f32).to_bits(), 0x41480000); - assert_eq!((1337f32).to_bits(), 0x44a72000); - assert_eq!((-14.25f32).to_bits(), 0xc1640000); - assert_approx_eq!(f32::from_bits(0x3f800000), 1.0); - assert_approx_eq!(f32::from_bits(0x41480000), 12.5); - assert_approx_eq!(f32::from_bits(0x44a72000), 1337.0); - assert_approx_eq!(f32::from_bits(0xc1640000), -14.25); - - // Check that NaNs roundtrip their bits regardless of signaling-ness - // 0xA is 0b1010; 0x5 is 0b0101 -- so these two together clobbers all the mantissa bits - let masked_nan1 = f32::NAN.to_bits() ^ 0x002A_AAAA; - let masked_nan2 = f32::NAN.to_bits() ^ 0x0055_5555; - assert!(f32::from_bits(masked_nan1).is_nan()); - assert!(f32::from_bits(masked_nan2).is_nan()); - - assert_eq!(f32::from_bits(masked_nan1).to_bits(), masked_nan1); - assert_eq!(f32::from_bits(masked_nan2).to_bits(), masked_nan2); -} - -#[test] -#[should_panic] -fn test_clamp_min_greater_than_max() { - let _ = 1.0f32.clamp(3.0, 1.0); -} - -#[test] -#[should_panic] -fn test_clamp_min_is_nan() { - let _ = 1.0f32.clamp(f32::NAN, 1.0); -} - -#[test] -#[should_panic] -fn test_clamp_max_is_nan() { - let _ = 1.0f32.clamp(3.0, f32::NAN); -} - -#[test] -fn test_total_cmp() { - use core::cmp::Ordering; - - fn quiet_bit_mask() -> u32 { - 1 << (f32::MANTISSA_DIGITS - 2) - } - - fn min_subnorm() -> f32 { - f32::MIN_POSITIVE / f32::powf(2.0, f32::MANTISSA_DIGITS as f32 - 1.0) - } - - fn max_subnorm() -> f32 { - f32::MIN_POSITIVE - min_subnorm() - } - - fn q_nan() -> f32 { - f32::from_bits(f32::NAN.to_bits() | quiet_bit_mask()) - } - - fn s_nan() -> f32 { - f32::from_bits((f32::NAN.to_bits() & !quiet_bit_mask()) + 42) - } - - assert_eq!(Ordering::Equal, (-q_nan()).total_cmp(&-q_nan())); - assert_eq!(Ordering::Equal, (-s_nan()).total_cmp(&-s_nan())); - assert_eq!(Ordering::Equal, (-f32::INFINITY).total_cmp(&-f32::INFINITY)); - assert_eq!(Ordering::Equal, (-f32::MAX).total_cmp(&-f32::MAX)); - assert_eq!(Ordering::Equal, (-2.5_f32).total_cmp(&-2.5)); - assert_eq!(Ordering::Equal, (-1.0_f32).total_cmp(&-1.0)); - assert_eq!(Ordering::Equal, (-1.5_f32).total_cmp(&-1.5)); - assert_eq!(Ordering::Equal, (-0.5_f32).total_cmp(&-0.5)); - assert_eq!(Ordering::Equal, (-f32::MIN_POSITIVE).total_cmp(&-f32::MIN_POSITIVE)); - assert_eq!(Ordering::Equal, (-max_subnorm()).total_cmp(&-max_subnorm())); - assert_eq!(Ordering::Equal, (-min_subnorm()).total_cmp(&-min_subnorm())); - assert_eq!(Ordering::Equal, (-0.0_f32).total_cmp(&-0.0)); - assert_eq!(Ordering::Equal, 0.0_f32.total_cmp(&0.0)); - assert_eq!(Ordering::Equal, min_subnorm().total_cmp(&min_subnorm())); - assert_eq!(Ordering::Equal, max_subnorm().total_cmp(&max_subnorm())); - assert_eq!(Ordering::Equal, f32::MIN_POSITIVE.total_cmp(&f32::MIN_POSITIVE)); - assert_eq!(Ordering::Equal, 0.5_f32.total_cmp(&0.5)); - assert_eq!(Ordering::Equal, 1.0_f32.total_cmp(&1.0)); - assert_eq!(Ordering::Equal, 1.5_f32.total_cmp(&1.5)); - assert_eq!(Ordering::Equal, 2.5_f32.total_cmp(&2.5)); - assert_eq!(Ordering::Equal, f32::MAX.total_cmp(&f32::MAX)); - assert_eq!(Ordering::Equal, f32::INFINITY.total_cmp(&f32::INFINITY)); - assert_eq!(Ordering::Equal, s_nan().total_cmp(&s_nan())); - assert_eq!(Ordering::Equal, q_nan().total_cmp(&q_nan())); - - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-s_nan())); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&-f32::INFINITY)); - assert_eq!(Ordering::Less, (-f32::INFINITY).total_cmp(&-f32::MAX)); - assert_eq!(Ordering::Less, (-f32::MAX).total_cmp(&-2.5)); - assert_eq!(Ordering::Less, (-2.5_f32).total_cmp(&-1.5)); - assert_eq!(Ordering::Less, (-1.5_f32).total_cmp(&-1.0)); - assert_eq!(Ordering::Less, (-1.0_f32).total_cmp(&-0.5)); - assert_eq!(Ordering::Less, (-0.5_f32).total_cmp(&-f32::MIN_POSITIVE)); - assert_eq!(Ordering::Less, (-f32::MIN_POSITIVE).total_cmp(&-max_subnorm())); - assert_eq!(Ordering::Less, (-max_subnorm()).total_cmp(&-min_subnorm())); - assert_eq!(Ordering::Less, (-min_subnorm()).total_cmp(&-0.0)); - assert_eq!(Ordering::Less, (-0.0_f32).total_cmp(&0.0)); - assert_eq!(Ordering::Less, 0.0_f32.total_cmp(&min_subnorm())); - assert_eq!(Ordering::Less, min_subnorm().total_cmp(&max_subnorm())); - assert_eq!(Ordering::Less, max_subnorm().total_cmp(&f32::MIN_POSITIVE)); - assert_eq!(Ordering::Less, f32::MIN_POSITIVE.total_cmp(&0.5)); - assert_eq!(Ordering::Less, 0.5_f32.total_cmp(&1.0)); - assert_eq!(Ordering::Less, 1.0_f32.total_cmp(&1.5)); - assert_eq!(Ordering::Less, 1.5_f32.total_cmp(&2.5)); - assert_eq!(Ordering::Less, 2.5_f32.total_cmp(&f32::MAX)); - assert_eq!(Ordering::Less, f32::MAX.total_cmp(&f32::INFINITY)); - assert_eq!(Ordering::Less, f32::INFINITY.total_cmp(&s_nan())); - assert_eq!(Ordering::Less, s_nan().total_cmp(&q_nan())); - - assert_eq!(Ordering::Greater, (-s_nan()).total_cmp(&-q_nan())); - assert_eq!(Ordering::Greater, (-f32::INFINITY).total_cmp(&-s_nan())); - assert_eq!(Ordering::Greater, (-f32::MAX).total_cmp(&-f32::INFINITY)); - assert_eq!(Ordering::Greater, (-2.5_f32).total_cmp(&-f32::MAX)); - assert_eq!(Ordering::Greater, (-1.5_f32).total_cmp(&-2.5)); - assert_eq!(Ordering::Greater, (-1.0_f32).total_cmp(&-1.5)); - assert_eq!(Ordering::Greater, (-0.5_f32).total_cmp(&-1.0)); - assert_eq!(Ordering::Greater, (-f32::MIN_POSITIVE).total_cmp(&-0.5)); - assert_eq!(Ordering::Greater, (-max_subnorm()).total_cmp(&-f32::MIN_POSITIVE)); - assert_eq!(Ordering::Greater, (-min_subnorm()).total_cmp(&-max_subnorm())); - assert_eq!(Ordering::Greater, (-0.0_f32).total_cmp(&-min_subnorm())); - assert_eq!(Ordering::Greater, 0.0_f32.total_cmp(&-0.0)); - assert_eq!(Ordering::Greater, min_subnorm().total_cmp(&0.0)); - assert_eq!(Ordering::Greater, max_subnorm().total_cmp(&min_subnorm())); - assert_eq!(Ordering::Greater, f32::MIN_POSITIVE.total_cmp(&max_subnorm())); - assert_eq!(Ordering::Greater, 0.5_f32.total_cmp(&f32::MIN_POSITIVE)); - assert_eq!(Ordering::Greater, 1.0_f32.total_cmp(&0.5)); - assert_eq!(Ordering::Greater, 1.5_f32.total_cmp(&1.0)); - assert_eq!(Ordering::Greater, 2.5_f32.total_cmp(&1.5)); - assert_eq!(Ordering::Greater, f32::MAX.total_cmp(&2.5)); - assert_eq!(Ordering::Greater, f32::INFINITY.total_cmp(&f32::MAX)); - assert_eq!(Ordering::Greater, s_nan().total_cmp(&f32::INFINITY)); - assert_eq!(Ordering::Greater, q_nan().total_cmp(&s_nan())); - - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-s_nan())); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-f32::INFINITY)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-f32::MAX)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-2.5)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-1.5)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-1.0)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-0.5)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-f32::MIN_POSITIVE)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-max_subnorm())); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-min_subnorm())); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-0.0)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&0.0)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&min_subnorm())); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&max_subnorm())); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&f32::MIN_POSITIVE)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&0.5)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&1.0)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&1.5)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&2.5)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&f32::MAX)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&f32::INFINITY)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&s_nan())); - - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&-f32::INFINITY)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&-f32::MAX)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&-2.5)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&-1.5)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&-1.0)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&-0.5)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&-f32::MIN_POSITIVE)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&-max_subnorm())); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&-min_subnorm())); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&-0.0)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&0.0)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&min_subnorm())); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&max_subnorm())); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&f32::MIN_POSITIVE)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&0.5)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&1.0)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&1.5)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&2.5)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&f32::MAX)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&f32::INFINITY)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&s_nan())); -} diff --git a/library/std/src/f64.rs b/library/std/src/f64.rs deleted file mode 100644 index f8c66a3e71752..0000000000000 --- a/library/std/src/f64.rs +++ /dev/null @@ -1,1228 +0,0 @@ -//! Constants for the `f64` double-precision floating point type. -//! -//! *[See also the `f64` primitive type](primitive@f64).* -//! -//! Mathematically significant numbers are provided in the `consts` sub-module. -//! -//! For the constants defined directly in this module -//! (as distinct from those defined in the `consts` sub-module), -//! new code should instead use the associated constants -//! defined directly on the `f64` type. - -#![stable(feature = "rust1", since = "1.0.0")] -#![allow(missing_docs)] - -#[cfg(test)] -mod tests; - -#[cfg(not(test))] -use crate::intrinsics; -#[cfg(not(test))] -use crate::sys::cmath; - -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated, deprecated_in_future)] -pub use core::f64::{ - consts, DIGITS, EPSILON, INFINITY, MANTISSA_DIGITS, MAX, MAX_10_EXP, MAX_EXP, MIN, MIN_10_EXP, - MIN_EXP, MIN_POSITIVE, NAN, NEG_INFINITY, RADIX, -}; - -#[cfg(not(test))] -impl f64 { - /// Returns the largest integer less than or equal to `self`. - /// - /// This function always returns the precise result. - /// - /// # Examples - /// - /// ``` - /// let f = 3.7_f64; - /// let g = 3.0_f64; - /// let h = -3.7_f64; - /// - /// assert_eq!(f.floor(), 3.0); - /// assert_eq!(g.floor(), 3.0); - /// assert_eq!(h.floor(), -4.0); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn floor(self) -> f64 { - unsafe { intrinsics::floorf64(self) } - } - - /// Returns the smallest integer greater than or equal to `self`. - /// - /// This function always returns the precise result. - /// - /// # Examples - /// - /// ``` - /// let f = 3.01_f64; - /// let g = 4.0_f64; - /// - /// assert_eq!(f.ceil(), 4.0); - /// assert_eq!(g.ceil(), 4.0); - /// ``` - #[doc(alias = "ceiling")] - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn ceil(self) -> f64 { - unsafe { intrinsics::ceilf64(self) } - } - - /// Returns the nearest integer to `self`. If a value is half-way between two - /// integers, round away from `0.0`. - /// - /// This function always returns the precise result. - /// - /// # Examples - /// - /// ``` - /// let f = 3.3_f64; - /// let g = -3.3_f64; - /// let h = -3.7_f64; - /// let i = 3.5_f64; - /// let j = 4.5_f64; - /// - /// assert_eq!(f.round(), 3.0); - /// assert_eq!(g.round(), -3.0); - /// assert_eq!(h.round(), -4.0); - /// assert_eq!(i.round(), 4.0); - /// assert_eq!(j.round(), 5.0); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn round(self) -> f64 { - unsafe { intrinsics::roundf64(self) } - } - - /// Returns the nearest integer to a number. Rounds half-way cases to the number - /// with an even least significant digit. - /// - /// This function always returns the precise result. - /// - /// # Examples - /// - /// ``` - /// let f = 3.3_f64; - /// let g = -3.3_f64; - /// let h = 3.5_f64; - /// let i = 4.5_f64; - /// - /// assert_eq!(f.round_ties_even(), 3.0); - /// assert_eq!(g.round_ties_even(), -3.0); - /// assert_eq!(h.round_ties_even(), 4.0); - /// assert_eq!(i.round_ties_even(), 4.0); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "round_ties_even", since = "1.77.0")] - #[inline] - pub fn round_ties_even(self) -> f64 { - unsafe { intrinsics::rintf64(self) } - } - - /// Returns the integer part of `self`. - /// This means that non-integer numbers are always truncated towards zero. - /// - /// This function always returns the precise result. - /// - /// # Examples - /// - /// ``` - /// let f = 3.7_f64; - /// let g = 3.0_f64; - /// let h = -3.7_f64; - /// - /// assert_eq!(f.trunc(), 3.0); - /// assert_eq!(g.trunc(), 3.0); - /// assert_eq!(h.trunc(), -3.0); - /// ``` - #[doc(alias = "truncate")] - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn trunc(self) -> f64 { - unsafe { intrinsics::truncf64(self) } - } - - /// Returns the fractional part of `self`. - /// - /// This function always returns the precise result. - /// - /// # Examples - /// - /// ``` - /// let x = 3.6_f64; - /// let y = -3.6_f64; - /// let abs_difference_x = (x.fract() - 0.6).abs(); - /// let abs_difference_y = (y.fract() - (-0.6)).abs(); - /// - /// assert!(abs_difference_x < 1e-10); - /// assert!(abs_difference_y < 1e-10); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn fract(self) -> f64 { - self - self.trunc() - } - - /// Computes the absolute value of `self`. - /// - /// This function always returns the precise result. - /// - /// # Examples - /// - /// ``` - /// let x = 3.5_f64; - /// let y = -3.5_f64; - /// - /// assert_eq!(x.abs(), x); - /// assert_eq!(y.abs(), -y); - /// - /// assert!(f64::NAN.abs().is_nan()); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn abs(self) -> f64 { - unsafe { intrinsics::fabsf64(self) } - } - - /// Returns a number that represents the sign of `self`. - /// - /// - `1.0` if the number is positive, `+0.0` or `INFINITY` - /// - `-1.0` if the number is negative, `-0.0` or `NEG_INFINITY` - /// - NaN if the number is NaN - /// - /// # Examples - /// - /// ``` - /// let f = 3.5_f64; - /// - /// assert_eq!(f.signum(), 1.0); - /// assert_eq!(f64::NEG_INFINITY.signum(), -1.0); - /// - /// assert!(f64::NAN.signum().is_nan()); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn signum(self) -> f64 { - if self.is_nan() { Self::NAN } else { 1.0_f64.copysign(self) } - } - - /// Returns a number composed of the magnitude of `self` and the sign of - /// `sign`. - /// - /// Equal to `self` if the sign of `self` and `sign` are the same, otherwise - /// equal to `-self`. If `self` is a NaN, then a NaN with the sign bit of - /// `sign` is returned. Note, however, that conserving the sign bit on NaN - /// across arithmetical operations is not generally guaranteed. - /// See [explanation of NaN as a special value](primitive@f32) for more info. - /// - /// # Examples - /// - /// ``` - /// let f = 3.5_f64; - /// - /// assert_eq!(f.copysign(0.42), 3.5_f64); - /// assert_eq!(f.copysign(-0.42), -3.5_f64); - /// assert_eq!((-f).copysign(0.42), 3.5_f64); - /// assert_eq!((-f).copysign(-0.42), -3.5_f64); - /// - /// assert!(f64::NAN.copysign(1.0).is_nan()); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "copysign", since = "1.35.0")] - #[inline] - pub fn copysign(self, sign: f64) -> f64 { - unsafe { intrinsics::copysignf64(self, sign) } - } - - /// Fused multiply-add. Computes `(self * a) + b` with only one rounding - /// error, yielding a more accurate result than an unfused multiply-add. - /// - /// Using `mul_add` *may* be more performant than an unfused multiply-add if - /// the target architecture has a dedicated `fma` CPU instruction. However, - /// this is not always true, and will be heavily dependant on designing - /// algorithms with specific target hardware in mind. - /// - /// # Precision - /// - /// The result of this operation is guaranteed to be the rounded - /// infinite-precision result. It is specified by IEEE 754 as - /// `fusedMultiplyAdd` and guaranteed not to change. - /// - /// # Examples - /// - /// ``` - /// let m = 10.0_f64; - /// let x = 4.0_f64; - /// let b = 60.0_f64; - /// - /// assert_eq!(m.mul_add(x, b), 100.0); - /// assert_eq!(m * x + b, 100.0); - /// - /// let one_plus_eps = 1.0_f64 + f64::EPSILON; - /// let one_minus_eps = 1.0_f64 - f64::EPSILON; - /// let minus_one = -1.0_f64; - /// - /// // The exact result (1 + eps) * (1 - eps) = 1 - eps * eps. - /// assert_eq!(one_plus_eps.mul_add(one_minus_eps, minus_one), -f64::EPSILON * f64::EPSILON); - /// // Different rounding with the non-fused multiply and add. - /// assert_eq!(one_plus_eps * one_minus_eps + minus_one, 0.0); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn mul_add(self, a: f64, b: f64) -> f64 { - unsafe { intrinsics::fmaf64(self, a, b) } - } - - /// Calculates Euclidean division, the matching method for `rem_euclid`. - /// - /// This computes the integer `n` such that - /// `self = n * rhs + self.rem_euclid(rhs)`. - /// In other words, the result is `self / rhs` rounded to the integer `n` - /// such that `self >= n * rhs`. - /// - /// # Precision - /// - /// The result of this operation is guaranteed to be the rounded - /// infinite-precision result. - /// - /// # Examples - /// - /// ``` - /// let a: f64 = 7.0; - /// let b = 4.0; - /// assert_eq!(a.div_euclid(b), 1.0); // 7.0 > 4.0 * 1.0 - /// assert_eq!((-a).div_euclid(b), -2.0); // -7.0 >= 4.0 * -2.0 - /// assert_eq!(a.div_euclid(-b), -1.0); // 7.0 >= -4.0 * -1.0 - /// assert_eq!((-a).div_euclid(-b), 2.0); // -7.0 >= -4.0 * 2.0 - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[inline] - #[stable(feature = "euclidean_division", since = "1.38.0")] - pub fn div_euclid(self, rhs: f64) -> f64 { - let q = (self / rhs).trunc(); - if self % rhs < 0.0 { - return if rhs > 0.0 { q - 1.0 } else { q + 1.0 }; - } - q - } - - /// Calculates the least nonnegative remainder of `self (mod rhs)`. - /// - /// In particular, the return value `r` satisfies `0.0 <= r < rhs.abs()` in - /// most cases. However, due to a floating point round-off error it can - /// result in `r == rhs.abs()`, violating the mathematical definition, if - /// `self` is much smaller than `rhs.abs()` in magnitude and `self < 0.0`. - /// This result is not an element of the function's codomain, but it is the - /// closest floating point number in the real numbers and thus fulfills the - /// property `self == self.div_euclid(rhs) * rhs + self.rem_euclid(rhs)` - /// approximately. - /// - /// # Precision - /// - /// The result of this operation is guaranteed to be the rounded - /// infinite-precision result. - /// - /// # Examples - /// - /// ``` - /// let a: f64 = 7.0; - /// let b = 4.0; - /// assert_eq!(a.rem_euclid(b), 3.0); - /// assert_eq!((-a).rem_euclid(b), 1.0); - /// assert_eq!(a.rem_euclid(-b), 3.0); - /// assert_eq!((-a).rem_euclid(-b), 1.0); - /// // limitation due to round-off error - /// assert!((-f64::EPSILON).rem_euclid(3.0) != 0.0); - /// ``` - #[doc(alias = "modulo", alias = "mod")] - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[inline] - #[stable(feature = "euclidean_division", since = "1.38.0")] - pub fn rem_euclid(self, rhs: f64) -> f64 { - let r = self % rhs; - if r < 0.0 { r + rhs.abs() } else { r } - } - - /// Raises a number to an integer power. - /// - /// Using this function is generally faster than using `powf`. - /// It might have a different sequence of rounding operations than `powf`, - /// so the results are not guaranteed to agree. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let x = 2.0_f64; - /// let abs_difference = (x.powi(2) - (x * x)).abs(); - /// - /// assert!(abs_difference < 1e-10); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn powi(self, n: i32) -> f64 { - unsafe { intrinsics::powif64(self, n) } - } - - /// Raises a number to a floating point power. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let x = 2.0_f64; - /// let abs_difference = (x.powf(2.0) - (x * x)).abs(); - /// - /// assert!(abs_difference < 1e-10); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn powf(self, n: f64) -> f64 { - unsafe { intrinsics::powf64(self, n) } - } - - /// Returns the square root of a number. - /// - /// Returns NaN if `self` is a negative number other than `-0.0`. - /// - /// # Precision - /// - /// The result of this operation is guaranteed to be the rounded - /// infinite-precision result. It is specified by IEEE 754 as `squareRoot` - /// and guaranteed not to change. - /// - /// # Examples - /// - /// ``` - /// let positive = 4.0_f64; - /// let negative = -4.0_f64; - /// let negative_zero = -0.0_f64; - /// - /// assert_eq!(positive.sqrt(), 2.0); - /// assert!(negative.sqrt().is_nan()); - /// assert!(negative_zero.sqrt() == negative_zero); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn sqrt(self) -> f64 { - unsafe { intrinsics::sqrtf64(self) } - } - - /// Returns `e^(self)`, (the exponential function). - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let one = 1.0_f64; - /// // e^1 - /// let e = one.exp(); - /// - /// // ln(e) - 1 == 0 - /// let abs_difference = (e.ln() - 1.0).abs(); - /// - /// assert!(abs_difference < 1e-10); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn exp(self) -> f64 { - unsafe { intrinsics::expf64(self) } - } - - /// Returns `2^(self)`. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let f = 2.0_f64; - /// - /// // 2^2 - 4 == 0 - /// let abs_difference = (f.exp2() - 4.0).abs(); - /// - /// assert!(abs_difference < 1e-10); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn exp2(self) -> f64 { - unsafe { intrinsics::exp2f64(self) } - } - - /// Returns the natural logarithm of the number. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let one = 1.0_f64; - /// // e^1 - /// let e = one.exp(); - /// - /// // ln(e) - 1 == 0 - /// let abs_difference = (e.ln() - 1.0).abs(); - /// - /// assert!(abs_difference < 1e-10); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn ln(self) -> f64 { - crate::sys::log_wrapper(self, |n| unsafe { intrinsics::logf64(n) }) - } - - /// Returns the logarithm of the number with respect to an arbitrary base. - /// - /// The result might not be correctly rounded owing to implementation details; - /// `self.log2()` can produce more accurate results for base 2, and - /// `self.log10()` can produce more accurate results for base 10. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let twenty_five = 25.0_f64; - /// - /// // log5(25) - 2 == 0 - /// let abs_difference = (twenty_five.log(5.0) - 2.0).abs(); - /// - /// assert!(abs_difference < 1e-10); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn log(self, base: f64) -> f64 { - self.ln() / base.ln() - } - - /// Returns the base 2 logarithm of the number. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let four = 4.0_f64; - /// - /// // log2(4) - 2 == 0 - /// let abs_difference = (four.log2() - 2.0).abs(); - /// - /// assert!(abs_difference < 1e-10); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn log2(self) -> f64 { - crate::sys::log_wrapper(self, crate::sys::log2f64) - } - - /// Returns the base 10 logarithm of the number. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let hundred = 100.0_f64; - /// - /// // log10(100) - 2 == 0 - /// let abs_difference = (hundred.log10() - 2.0).abs(); - /// - /// assert!(abs_difference < 1e-10); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn log10(self) -> f64 { - crate::sys::log_wrapper(self, |n| unsafe { intrinsics::log10f64(n) }) - } - - /// The positive difference of two numbers. - /// - /// * If `self <= other`: `0.0` - /// * Else: `self - other` - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `fdim` from libc on Unix and - /// Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let x = 3.0_f64; - /// let y = -3.0_f64; - /// - /// let abs_difference_x = (x.abs_sub(1.0) - 2.0).abs(); - /// let abs_difference_y = (y.abs_sub(1.0) - 0.0).abs(); - /// - /// assert!(abs_difference_x < 1e-10); - /// assert!(abs_difference_y < 1e-10); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - #[deprecated( - since = "1.10.0", - note = "you probably meant `(self - other).abs()`: \ - this operation is `(self - other).max(0.0)` \ - except that `abs_sub` also propagates NaNs (also \ - known as `fdim` in C). If you truly need the positive \ - difference, consider using that expression or the C function \ - `fdim`, depending on how you wish to handle NaN (please consider \ - filing an issue describing your use-case too)." - )] - pub fn abs_sub(self, other: f64) -> f64 { - unsafe { cmath::fdim(self, other) } - } - - /// Returns the cube root of a number. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `cbrt` from libc on Unix and - /// Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let x = 8.0_f64; - /// - /// // x^(1/3) - 2 == 0 - /// let abs_difference = (x.cbrt() - 2.0).abs(); - /// - /// assert!(abs_difference < 1e-10); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn cbrt(self) -> f64 { - unsafe { cmath::cbrt(self) } - } - - /// Compute the distance between the origin and a point (`x`, `y`) on the - /// Euclidean plane. Equivalently, compute the length of the hypotenuse of a - /// right-angle triangle with other sides having length `x.abs()` and - /// `y.abs()`. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `hypot` from libc on Unix - /// and Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let x = 2.0_f64; - /// let y = 3.0_f64; - /// - /// // sqrt(x^2 + y^2) - /// let abs_difference = (x.hypot(y) - (x.powi(2) + y.powi(2)).sqrt()).abs(); - /// - /// assert!(abs_difference < 1e-10); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn hypot(self, other: f64) -> f64 { - unsafe { cmath::hypot(self, other) } - } - - /// Computes the sine of a number (in radians). - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let x = std::f64::consts::FRAC_PI_2; - /// - /// let abs_difference = (x.sin() - 1.0).abs(); - /// - /// assert!(abs_difference < 1e-10); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn sin(self) -> f64 { - unsafe { intrinsics::sinf64(self) } - } - - /// Computes the cosine of a number (in radians). - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let x = 2.0 * std::f64::consts::PI; - /// - /// let abs_difference = (x.cos() - 1.0).abs(); - /// - /// assert!(abs_difference < 1e-10); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn cos(self) -> f64 { - unsafe { intrinsics::cosf64(self) } - } - - /// Computes the tangent of a number (in radians). - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `tan` from libc on Unix and - /// Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let x = std::f64::consts::FRAC_PI_4; - /// let abs_difference = (x.tan() - 1.0).abs(); - /// - /// assert!(abs_difference < 1e-14); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn tan(self) -> f64 { - unsafe { cmath::tan(self) } - } - - /// Computes the arcsine of a number. Return value is in radians in - /// the range [-pi/2, pi/2] or NaN if the number is outside the range - /// [-1, 1]. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `asin` from libc on Unix and - /// Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let f = std::f64::consts::FRAC_PI_2; - /// - /// // asin(sin(pi/2)) - /// let abs_difference = (f.sin().asin() - std::f64::consts::FRAC_PI_2).abs(); - /// - /// assert!(abs_difference < 1e-10); - /// ``` - #[doc(alias = "arcsin")] - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn asin(self) -> f64 { - unsafe { cmath::asin(self) } - } - - /// Computes the arccosine of a number. Return value is in radians in - /// the range [0, pi] or NaN if the number is outside the range - /// [-1, 1]. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `acos` from libc on Unix and - /// Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let f = std::f64::consts::FRAC_PI_4; - /// - /// // acos(cos(pi/4)) - /// let abs_difference = (f.cos().acos() - std::f64::consts::FRAC_PI_4).abs(); - /// - /// assert!(abs_difference < 1e-10); - /// ``` - #[doc(alias = "arccos")] - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn acos(self) -> f64 { - unsafe { cmath::acos(self) } - } - - /// Computes the arctangent of a number. Return value is in radians in the - /// range [-pi/2, pi/2]; - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `atan` from libc on Unix and - /// Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let f = 1.0_f64; - /// - /// // atan(tan(1)) - /// let abs_difference = (f.tan().atan() - 1.0).abs(); - /// - /// assert!(abs_difference < 1e-10); - /// ``` - #[doc(alias = "arctan")] - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn atan(self) -> f64 { - unsafe { cmath::atan(self) } - } - - /// Computes the four quadrant arctangent of `self` (`y`) and `other` (`x`) in radians. - /// - /// * `x = 0`, `y = 0`: `0` - /// * `x >= 0`: `arctan(y/x)` -> `[-pi/2, pi/2]` - /// * `y >= 0`: `arctan(y/x) + pi` -> `(pi/2, pi]` - /// * `y < 0`: `arctan(y/x) - pi` -> `(-pi, -pi/2)` - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `atan2` from libc on Unix - /// and Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// // Positive angles measured counter-clockwise - /// // from positive x axis - /// // -pi/4 radians (45 deg clockwise) - /// let x1 = 3.0_f64; - /// let y1 = -3.0_f64; - /// - /// // 3pi/4 radians (135 deg counter-clockwise) - /// let x2 = -3.0_f64; - /// let y2 = 3.0_f64; - /// - /// let abs_difference_1 = (y1.atan2(x1) - (-std::f64::consts::FRAC_PI_4)).abs(); - /// let abs_difference_2 = (y2.atan2(x2) - (3.0 * std::f64::consts::FRAC_PI_4)).abs(); - /// - /// assert!(abs_difference_1 < 1e-10); - /// assert!(abs_difference_2 < 1e-10); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn atan2(self, other: f64) -> f64 { - unsafe { cmath::atan2(self, other) } - } - - /// Simultaneously computes the sine and cosine of the number, `x`. Returns - /// `(sin(x), cos(x))`. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `(f64::sin(x), - /// f64::cos(x))`. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let x = std::f64::consts::FRAC_PI_4; - /// let f = x.sin_cos(); - /// - /// let abs_difference_0 = (f.0 - x.sin()).abs(); - /// let abs_difference_1 = (f.1 - x.cos()).abs(); - /// - /// assert!(abs_difference_0 < 1e-10); - /// assert!(abs_difference_1 < 1e-10); - /// ``` - #[doc(alias = "sincos")] - #[rustc_allow_incoherent_impl] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn sin_cos(self) -> (f64, f64) { - (self.sin(), self.cos()) - } - - /// Returns `e^(self) - 1` in a way that is accurate even if the - /// number is close to zero. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `expm1` from libc on Unix - /// and Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let x = 1e-16_f64; - /// - /// // for very small x, e^x is approximately 1 + x + x^2 / 2 - /// let approx = x + x * x / 2.0; - /// let abs_difference = (x.exp_m1() - approx).abs(); - /// - /// assert!(abs_difference < 1e-20); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn exp_m1(self) -> f64 { - unsafe { cmath::expm1(self) } - } - - /// Returns `ln(1+n)` (natural logarithm) more accurately than if - /// the operations were performed separately. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `log1p` from libc on Unix - /// and Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let x = 1e-16_f64; - /// - /// // for very small x, ln(1 + x) is approximately x - x^2 / 2 - /// let approx = x - x * x / 2.0; - /// let abs_difference = (x.ln_1p() - approx).abs(); - /// - /// assert!(abs_difference < 1e-20); - /// ``` - #[doc(alias = "log1p")] - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn ln_1p(self) -> f64 { - unsafe { cmath::log1p(self) } - } - - /// Hyperbolic sine function. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `sinh` from libc on Unix - /// and Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let e = std::f64::consts::E; - /// let x = 1.0_f64; - /// - /// let f = x.sinh(); - /// // Solving sinh() at 1 gives `(e^2-1)/(2e)` - /// let g = ((e * e) - 1.0) / (2.0 * e); - /// let abs_difference = (f - g).abs(); - /// - /// assert!(abs_difference < 1e-10); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn sinh(self) -> f64 { - unsafe { cmath::sinh(self) } - } - - /// Hyperbolic cosine function. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `cosh` from libc on Unix - /// and Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let e = std::f64::consts::E; - /// let x = 1.0_f64; - /// let f = x.cosh(); - /// // Solving cosh() at 1 gives this result - /// let g = ((e * e) + 1.0) / (2.0 * e); - /// let abs_difference = (f - g).abs(); - /// - /// // Same result - /// assert!(abs_difference < 1.0e-10); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn cosh(self) -> f64 { - unsafe { cmath::cosh(self) } - } - - /// Hyperbolic tangent function. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `tanh` from libc on Unix - /// and Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// let e = std::f64::consts::E; - /// let x = 1.0_f64; - /// - /// let f = x.tanh(); - /// // Solving tanh() at 1 gives `(1 - e^(-2))/(1 + e^(-2))` - /// let g = (1.0 - e.powi(-2)) / (1.0 + e.powi(-2)); - /// let abs_difference = (f - g).abs(); - /// - /// assert!(abs_difference < 1.0e-10); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn tanh(self) -> f64 { - unsafe { cmath::tanh(self) } - } - - /// Inverse hyperbolic sine function. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let x = 1.0_f64; - /// let f = x.sinh().asinh(); - /// - /// let abs_difference = (f - x).abs(); - /// - /// assert!(abs_difference < 1.0e-10); - /// ``` - #[doc(alias = "arcsinh")] - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn asinh(self) -> f64 { - let ax = self.abs(); - let ix = 1.0 / ax; - (ax + (ax / (Self::hypot(1.0, ix) + ix))).ln_1p().copysign(self) - } - - /// Inverse hyperbolic cosine function. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let x = 1.0_f64; - /// let f = x.cosh().acosh(); - /// - /// let abs_difference = (f - x).abs(); - /// - /// assert!(abs_difference < 1.0e-10); - /// ``` - #[doc(alias = "arccosh")] - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn acosh(self) -> f64 { - if self < 1.0 { - Self::NAN - } else { - (self + ((self - 1.0).sqrt() * (self + 1.0).sqrt())).ln() - } - } - - /// Inverse hyperbolic tangent function. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// - /// # Examples - /// - /// ``` - /// let e = std::f64::consts::E; - /// let f = e.tanh().atanh(); - /// - /// let abs_difference = (f - e).abs(); - /// - /// assert!(abs_difference < 1.0e-10); - /// ``` - #[doc(alias = "arctanh")] - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn atanh(self) -> f64 { - 0.5 * ((2.0 * self) / (1.0 - self)).ln_1p() - } - - /// Gamma function. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `tgamma` from libc on Unix - /// and Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// #![feature(float_gamma)] - /// let x = 5.0f64; - /// - /// let abs_difference = (x.gamma() - 24.0).abs(); - /// - /// assert!(abs_difference <= f64::EPSILON); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[unstable(feature = "float_gamma", issue = "99842")] - #[inline] - pub fn gamma(self) -> f64 { - unsafe { cmath::tgamma(self) } - } - - /// Natural logarithm of the absolute value of the gamma function - /// - /// The integer part of the tuple indicates the sign of the gamma function. - /// - /// # Unspecified precision - /// - /// The precision of this function is non-deterministic. This means it varies by platform, Rust version, and - /// can even differ within the same execution from one invocation to the next. - /// This function currently corresponds to the `lgamma_r` from libc on Unix - /// and Windows. Note that this might change in the future. - /// - /// # Examples - /// - /// ``` - /// #![feature(float_gamma)] - /// let x = 2.0f64; - /// - /// let abs_difference = (x.ln_gamma().0 - 0.0).abs(); - /// - /// assert!(abs_difference <= f64::EPSILON); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "method returns a new number and does not mutate the original value"] - #[unstable(feature = "float_gamma", issue = "99842")] - #[inline] - pub fn ln_gamma(self) -> (f64, i32) { - let mut signgamp: i32 = 0; - let x = unsafe { cmath::lgamma_r(self, &mut signgamp) }; - (x, signgamp) - } -} diff --git a/library/std/src/f64/tests.rs b/library/std/src/f64/tests.rs deleted file mode 100644 index f88d01593b5e4..0000000000000 --- a/library/std/src/f64/tests.rs +++ /dev/null @@ -1,887 +0,0 @@ -use crate::f64::consts; -use crate::num::FpCategory as Fp; -use crate::num::*; - -#[test] -fn test_num_f64() { - test_num(10f64, 2f64); -} - -#[test] -fn test_min_nan() { - assert_eq!(f64::NAN.min(2.0), 2.0); - assert_eq!(2.0f64.min(f64::NAN), 2.0); -} - -#[test] -fn test_max_nan() { - assert_eq!(f64::NAN.max(2.0), 2.0); - assert_eq!(2.0f64.max(f64::NAN), 2.0); -} - -#[test] -fn test_nan() { - let nan: f64 = f64::NAN; - assert!(nan.is_nan()); - assert!(!nan.is_infinite()); - assert!(!nan.is_finite()); - assert!(!nan.is_normal()); - assert!(nan.is_sign_positive()); - assert!(!nan.is_sign_negative()); - assert_eq!(Fp::Nan, nan.classify()); -} - -#[test] -fn test_infinity() { - let inf: f64 = f64::INFINITY; - assert!(inf.is_infinite()); - assert!(!inf.is_finite()); - assert!(inf.is_sign_positive()); - assert!(!inf.is_sign_negative()); - assert!(!inf.is_nan()); - assert!(!inf.is_normal()); - assert_eq!(Fp::Infinite, inf.classify()); -} - -#[test] -fn test_neg_infinity() { - let neg_inf: f64 = f64::NEG_INFINITY; - assert!(neg_inf.is_infinite()); - assert!(!neg_inf.is_finite()); - assert!(!neg_inf.is_sign_positive()); - assert!(neg_inf.is_sign_negative()); - assert!(!neg_inf.is_nan()); - assert!(!neg_inf.is_normal()); - assert_eq!(Fp::Infinite, neg_inf.classify()); -} - -#[test] -fn test_zero() { - let zero: f64 = 0.0f64; - assert_eq!(0.0, zero); - assert!(!zero.is_infinite()); - assert!(zero.is_finite()); - assert!(zero.is_sign_positive()); - assert!(!zero.is_sign_negative()); - assert!(!zero.is_nan()); - assert!(!zero.is_normal()); - assert_eq!(Fp::Zero, zero.classify()); -} - -#[test] -fn test_neg_zero() { - let neg_zero: f64 = -0.0; - assert_eq!(0.0, neg_zero); - assert!(!neg_zero.is_infinite()); - assert!(neg_zero.is_finite()); - assert!(!neg_zero.is_sign_positive()); - assert!(neg_zero.is_sign_negative()); - assert!(!neg_zero.is_nan()); - assert!(!neg_zero.is_normal()); - assert_eq!(Fp::Zero, neg_zero.classify()); -} - -#[cfg_attr(all(target_arch = "wasm32", target_os = "emscripten"), ignore)] // issue 42630 -#[test] -fn test_one() { - let one: f64 = 1.0f64; - assert_eq!(1.0, one); - assert!(!one.is_infinite()); - assert!(one.is_finite()); - assert!(one.is_sign_positive()); - assert!(!one.is_sign_negative()); - assert!(!one.is_nan()); - assert!(one.is_normal()); - assert_eq!(Fp::Normal, one.classify()); -} - -#[test] -fn test_is_nan() { - let nan: f64 = f64::NAN; - let inf: f64 = f64::INFINITY; - let neg_inf: f64 = f64::NEG_INFINITY; - assert!(nan.is_nan()); - assert!(!0.0f64.is_nan()); - assert!(!5.3f64.is_nan()); - assert!(!(-10.732f64).is_nan()); - assert!(!inf.is_nan()); - assert!(!neg_inf.is_nan()); -} - -#[test] -fn test_is_infinite() { - let nan: f64 = f64::NAN; - let inf: f64 = f64::INFINITY; - let neg_inf: f64 = f64::NEG_INFINITY; - assert!(!nan.is_infinite()); - assert!(inf.is_infinite()); - assert!(neg_inf.is_infinite()); - assert!(!0.0f64.is_infinite()); - assert!(!42.8f64.is_infinite()); - assert!(!(-109.2f64).is_infinite()); -} - -#[test] -fn test_is_finite() { - let nan: f64 = f64::NAN; - let inf: f64 = f64::INFINITY; - let neg_inf: f64 = f64::NEG_INFINITY; - assert!(!nan.is_finite()); - assert!(!inf.is_finite()); - assert!(!neg_inf.is_finite()); - assert!(0.0f64.is_finite()); - assert!(42.8f64.is_finite()); - assert!((-109.2f64).is_finite()); -} - -#[cfg_attr(all(target_arch = "wasm32", target_os = "emscripten"), ignore)] // issue 42630 -#[test] -fn test_is_normal() { - let nan: f64 = f64::NAN; - let inf: f64 = f64::INFINITY; - let neg_inf: f64 = f64::NEG_INFINITY; - let zero: f64 = 0.0f64; - let neg_zero: f64 = -0.0; - assert!(!nan.is_normal()); - assert!(!inf.is_normal()); - assert!(!neg_inf.is_normal()); - assert!(!zero.is_normal()); - assert!(!neg_zero.is_normal()); - assert!(1f64.is_normal()); - assert!(1e-307f64.is_normal()); - assert!(!1e-308f64.is_normal()); -} - -#[cfg_attr(all(target_arch = "wasm32", target_os = "emscripten"), ignore)] // issue 42630 -#[test] -fn test_classify() { - let nan: f64 = f64::NAN; - let inf: f64 = f64::INFINITY; - let neg_inf: f64 = f64::NEG_INFINITY; - let zero: f64 = 0.0f64; - let neg_zero: f64 = -0.0; - assert_eq!(nan.classify(), Fp::Nan); - assert_eq!(inf.classify(), Fp::Infinite); - assert_eq!(neg_inf.classify(), Fp::Infinite); - assert_eq!(zero.classify(), Fp::Zero); - assert_eq!(neg_zero.classify(), Fp::Zero); - assert_eq!(1e-307f64.classify(), Fp::Normal); - assert_eq!(1e-308f64.classify(), Fp::Subnormal); -} - -#[test] -fn test_floor() { - assert_approx_eq!(1.0f64.floor(), 1.0f64); - assert_approx_eq!(1.3f64.floor(), 1.0f64); - assert_approx_eq!(1.5f64.floor(), 1.0f64); - assert_approx_eq!(1.7f64.floor(), 1.0f64); - assert_approx_eq!(0.0f64.floor(), 0.0f64); - assert_approx_eq!((-0.0f64).floor(), -0.0f64); - assert_approx_eq!((-1.0f64).floor(), -1.0f64); - assert_approx_eq!((-1.3f64).floor(), -2.0f64); - assert_approx_eq!((-1.5f64).floor(), -2.0f64); - assert_approx_eq!((-1.7f64).floor(), -2.0f64); -} - -#[test] -fn test_ceil() { - assert_approx_eq!(1.0f64.ceil(), 1.0f64); - assert_approx_eq!(1.3f64.ceil(), 2.0f64); - assert_approx_eq!(1.5f64.ceil(), 2.0f64); - assert_approx_eq!(1.7f64.ceil(), 2.0f64); - assert_approx_eq!(0.0f64.ceil(), 0.0f64); - assert_approx_eq!((-0.0f64).ceil(), -0.0f64); - assert_approx_eq!((-1.0f64).ceil(), -1.0f64); - assert_approx_eq!((-1.3f64).ceil(), -1.0f64); - assert_approx_eq!((-1.5f64).ceil(), -1.0f64); - assert_approx_eq!((-1.7f64).ceil(), -1.0f64); -} - -#[test] -fn test_round() { - assert_approx_eq!(2.5f64.round(), 3.0f64); - assert_approx_eq!(1.0f64.round(), 1.0f64); - assert_approx_eq!(1.3f64.round(), 1.0f64); - assert_approx_eq!(1.5f64.round(), 2.0f64); - assert_approx_eq!(1.7f64.round(), 2.0f64); - assert_approx_eq!(0.0f64.round(), 0.0f64); - assert_approx_eq!((-0.0f64).round(), -0.0f64); - assert_approx_eq!((-1.0f64).round(), -1.0f64); - assert_approx_eq!((-1.3f64).round(), -1.0f64); - assert_approx_eq!((-1.5f64).round(), -2.0f64); - assert_approx_eq!((-1.7f64).round(), -2.0f64); -} - -#[test] -fn test_round_ties_even() { - assert_approx_eq!(2.5f64.round_ties_even(), 2.0f64); - assert_approx_eq!(1.0f64.round_ties_even(), 1.0f64); - assert_approx_eq!(1.3f64.round_ties_even(), 1.0f64); - assert_approx_eq!(1.5f64.round_ties_even(), 2.0f64); - assert_approx_eq!(1.7f64.round_ties_even(), 2.0f64); - assert_approx_eq!(0.0f64.round_ties_even(), 0.0f64); - assert_approx_eq!((-0.0f64).round_ties_even(), -0.0f64); - assert_approx_eq!((-1.0f64).round_ties_even(), -1.0f64); - assert_approx_eq!((-1.3f64).round_ties_even(), -1.0f64); - assert_approx_eq!((-1.5f64).round_ties_even(), -2.0f64); - assert_approx_eq!((-1.7f64).round_ties_even(), -2.0f64); -} - -#[test] -fn test_trunc() { - assert_approx_eq!(1.0f64.trunc(), 1.0f64); - assert_approx_eq!(1.3f64.trunc(), 1.0f64); - assert_approx_eq!(1.5f64.trunc(), 1.0f64); - assert_approx_eq!(1.7f64.trunc(), 1.0f64); - assert_approx_eq!(0.0f64.trunc(), 0.0f64); - assert_approx_eq!((-0.0f64).trunc(), -0.0f64); - assert_approx_eq!((-1.0f64).trunc(), -1.0f64); - assert_approx_eq!((-1.3f64).trunc(), -1.0f64); - assert_approx_eq!((-1.5f64).trunc(), -1.0f64); - assert_approx_eq!((-1.7f64).trunc(), -1.0f64); -} - -#[test] -fn test_fract() { - assert_approx_eq!(1.0f64.fract(), 0.0f64); - assert_approx_eq!(1.3f64.fract(), 0.3f64); - assert_approx_eq!(1.5f64.fract(), 0.5f64); - assert_approx_eq!(1.7f64.fract(), 0.7f64); - assert_approx_eq!(0.0f64.fract(), 0.0f64); - assert_approx_eq!((-0.0f64).fract(), -0.0f64); - assert_approx_eq!((-1.0f64).fract(), -0.0f64); - assert_approx_eq!((-1.3f64).fract(), -0.3f64); - assert_approx_eq!((-1.5f64).fract(), -0.5f64); - assert_approx_eq!((-1.7f64).fract(), -0.7f64); -} - -#[test] -fn test_abs() { - assert_eq!(f64::INFINITY.abs(), f64::INFINITY); - assert_eq!(1f64.abs(), 1f64); - assert_eq!(0f64.abs(), 0f64); - assert_eq!((-0f64).abs(), 0f64); - assert_eq!((-1f64).abs(), 1f64); - assert_eq!(f64::NEG_INFINITY.abs(), f64::INFINITY); - assert_eq!((1f64 / f64::NEG_INFINITY).abs(), 0f64); - assert!(f64::NAN.abs().is_nan()); -} - -#[test] -fn test_signum() { - assert_eq!(f64::INFINITY.signum(), 1f64); - assert_eq!(1f64.signum(), 1f64); - assert_eq!(0f64.signum(), 1f64); - assert_eq!((-0f64).signum(), -1f64); - assert_eq!((-1f64).signum(), -1f64); - assert_eq!(f64::NEG_INFINITY.signum(), -1f64); - assert_eq!((1f64 / f64::NEG_INFINITY).signum(), -1f64); - assert!(f64::NAN.signum().is_nan()); -} - -#[test] -fn test_is_sign_positive() { - assert!(f64::INFINITY.is_sign_positive()); - assert!(1f64.is_sign_positive()); - assert!(0f64.is_sign_positive()); - assert!(!(-0f64).is_sign_positive()); - assert!(!(-1f64).is_sign_positive()); - assert!(!f64::NEG_INFINITY.is_sign_positive()); - assert!(!(1f64 / f64::NEG_INFINITY).is_sign_positive()); - assert!(f64::NAN.is_sign_positive()); - assert!(!(-f64::NAN).is_sign_positive()); -} - -#[test] -fn test_is_sign_negative() { - assert!(!f64::INFINITY.is_sign_negative()); - assert!(!1f64.is_sign_negative()); - assert!(!0f64.is_sign_negative()); - assert!((-0f64).is_sign_negative()); - assert!((-1f64).is_sign_negative()); - assert!(f64::NEG_INFINITY.is_sign_negative()); - assert!((1f64 / f64::NEG_INFINITY).is_sign_negative()); - assert!(!f64::NAN.is_sign_negative()); - assert!((-f64::NAN).is_sign_negative()); -} - -#[allow(unused_macros)] -macro_rules! assert_f64_biteq { - ($left : expr, $right : expr) => { - let l: &f64 = &$left; - let r: &f64 = &$right; - let lb = l.to_bits(); - let rb = r.to_bits(); - assert_eq!(lb, rb, "float {} ({:#x}) is not equal to {} ({:#x})", *l, lb, *r, rb); - }; -} - -// Ignore test on x87 floating point, these platforms do not guarantee NaN -// payloads are preserved and flush denormals to zero, failing the tests. -#[cfg(not(target_arch = "x86"))] -#[test] -fn test_next_up() { - let tiny = f64::from_bits(1); - let tiny_up = f64::from_bits(2); - let max_down = f64::from_bits(0x7fef_ffff_ffff_fffe); - let largest_subnormal = f64::from_bits(0x000f_ffff_ffff_ffff); - let smallest_normal = f64::from_bits(0x0010_0000_0000_0000); - assert_f64_biteq!(f64::NEG_INFINITY.next_up(), f64::MIN); - assert_f64_biteq!(f64::MIN.next_up(), -max_down); - assert_f64_biteq!((-1.0 - f64::EPSILON).next_up(), -1.0); - assert_f64_biteq!((-smallest_normal).next_up(), -largest_subnormal); - assert_f64_biteq!((-tiny_up).next_up(), -tiny); - assert_f64_biteq!((-tiny).next_up(), -0.0f64); - assert_f64_biteq!((-0.0f64).next_up(), tiny); - assert_f64_biteq!(0.0f64.next_up(), tiny); - assert_f64_biteq!(tiny.next_up(), tiny_up); - assert_f64_biteq!(largest_subnormal.next_up(), smallest_normal); - assert_f64_biteq!(1.0f64.next_up(), 1.0 + f64::EPSILON); - assert_f64_biteq!(f64::MAX.next_up(), f64::INFINITY); - assert_f64_biteq!(f64::INFINITY.next_up(), f64::INFINITY); - - let nan0 = f64::NAN; - let nan1 = f64::from_bits(f64::NAN.to_bits() ^ 0x000a_aaaa_aaaa_aaaa); - let nan2 = f64::from_bits(f64::NAN.to_bits() ^ 0x0005_5555_5555_5555); - assert_f64_biteq!(nan0.next_up(), nan0); - assert_f64_biteq!(nan1.next_up(), nan1); - assert_f64_biteq!(nan2.next_up(), nan2); -} - -// Ignore test on x87 floating point, these platforms do not guarantee NaN -// payloads are preserved and flush denormals to zero, failing the tests. -#[cfg(not(target_arch = "x86"))] -#[test] -fn test_next_down() { - let tiny = f64::from_bits(1); - let tiny_up = f64::from_bits(2); - let max_down = f64::from_bits(0x7fef_ffff_ffff_fffe); - let largest_subnormal = f64::from_bits(0x000f_ffff_ffff_ffff); - let smallest_normal = f64::from_bits(0x0010_0000_0000_0000); - assert_f64_biteq!(f64::NEG_INFINITY.next_down(), f64::NEG_INFINITY); - assert_f64_biteq!(f64::MIN.next_down(), f64::NEG_INFINITY); - assert_f64_biteq!((-max_down).next_down(), f64::MIN); - assert_f64_biteq!((-1.0f64).next_down(), -1.0 - f64::EPSILON); - assert_f64_biteq!((-largest_subnormal).next_down(), -smallest_normal); - assert_f64_biteq!((-tiny).next_down(), -tiny_up); - assert_f64_biteq!((-0.0f64).next_down(), -tiny); - assert_f64_biteq!((0.0f64).next_down(), -tiny); - assert_f64_biteq!(tiny.next_down(), 0.0f64); - assert_f64_biteq!(tiny_up.next_down(), tiny); - assert_f64_biteq!(smallest_normal.next_down(), largest_subnormal); - assert_f64_biteq!((1.0 + f64::EPSILON).next_down(), 1.0f64); - assert_f64_biteq!(f64::MAX.next_down(), max_down); - assert_f64_biteq!(f64::INFINITY.next_down(), f64::MAX); - - let nan0 = f64::NAN; - let nan1 = f64::from_bits(f64::NAN.to_bits() ^ 0x000a_aaaa_aaaa_aaaa); - let nan2 = f64::from_bits(f64::NAN.to_bits() ^ 0x0005_5555_5555_5555); - assert_f64_biteq!(nan0.next_down(), nan0); - assert_f64_biteq!(nan1.next_down(), nan1); - assert_f64_biteq!(nan2.next_down(), nan2); -} - -#[test] -fn test_mul_add() { - let nan: f64 = f64::NAN; - let inf: f64 = f64::INFINITY; - let neg_inf: f64 = f64::NEG_INFINITY; - assert_approx_eq!(12.3f64.mul_add(4.5, 6.7), 62.05); - assert_approx_eq!((-12.3f64).mul_add(-4.5, -6.7), 48.65); - assert_approx_eq!(0.0f64.mul_add(8.9, 1.2), 1.2); - assert_approx_eq!(3.4f64.mul_add(-0.0, 5.6), 5.6); - assert!(nan.mul_add(7.8, 9.0).is_nan()); - assert_eq!(inf.mul_add(7.8, 9.0), inf); - assert_eq!(neg_inf.mul_add(7.8, 9.0), neg_inf); - assert_eq!(8.9f64.mul_add(inf, 3.2), inf); - assert_eq!((-3.2f64).mul_add(2.4, neg_inf), neg_inf); -} - -#[test] -fn test_recip() { - let nan: f64 = f64::NAN; - let inf: f64 = f64::INFINITY; - let neg_inf: f64 = f64::NEG_INFINITY; - assert_eq!(1.0f64.recip(), 1.0); - assert_eq!(2.0f64.recip(), 0.5); - assert_eq!((-0.4f64).recip(), -2.5); - assert_eq!(0.0f64.recip(), inf); - assert!(nan.recip().is_nan()); - assert_eq!(inf.recip(), 0.0); - assert_eq!(neg_inf.recip(), 0.0); -} - -#[test] -fn test_powi() { - let nan: f64 = f64::NAN; - let inf: f64 = f64::INFINITY; - let neg_inf: f64 = f64::NEG_INFINITY; - assert_eq!(1.0f64.powi(1), 1.0); - assert_approx_eq!((-3.1f64).powi(2), 9.61); - assert_approx_eq!(5.9f64.powi(-2), 0.028727); - assert_eq!(8.3f64.powi(0), 1.0); - assert!(nan.powi(2).is_nan()); - assert_eq!(inf.powi(3), inf); - assert_eq!(neg_inf.powi(2), inf); -} - -#[test] -fn test_powf() { - let nan: f64 = f64::NAN; - let inf: f64 = f64::INFINITY; - let neg_inf: f64 = f64::NEG_INFINITY; - assert_eq!(1.0f64.powf(1.0), 1.0); - assert_approx_eq!(3.4f64.powf(4.5), 246.408183); - assert_approx_eq!(2.7f64.powf(-3.2), 0.041652); - assert_approx_eq!((-3.1f64).powf(2.0), 9.61); - assert_approx_eq!(5.9f64.powf(-2.0), 0.028727); - assert_eq!(8.3f64.powf(0.0), 1.0); - assert!(nan.powf(2.0).is_nan()); - assert_eq!(inf.powf(2.0), inf); - assert_eq!(neg_inf.powf(3.0), neg_inf); -} - -#[test] -fn test_sqrt_domain() { - assert!(f64::NAN.sqrt().is_nan()); - assert!(f64::NEG_INFINITY.sqrt().is_nan()); - assert!((-1.0f64).sqrt().is_nan()); - assert_eq!((-0.0f64).sqrt(), -0.0); - assert_eq!(0.0f64.sqrt(), 0.0); - assert_eq!(1.0f64.sqrt(), 1.0); - assert_eq!(f64::INFINITY.sqrt(), f64::INFINITY); -} - -#[test] -fn test_exp() { - assert_eq!(1.0, 0.0f64.exp()); - assert_approx_eq!(2.718282, 1.0f64.exp()); - assert_approx_eq!(148.413159, 5.0f64.exp()); - - let inf: f64 = f64::INFINITY; - let neg_inf: f64 = f64::NEG_INFINITY; - let nan: f64 = f64::NAN; - assert_eq!(inf, inf.exp()); - assert_eq!(0.0, neg_inf.exp()); - assert!(nan.exp().is_nan()); -} - -#[test] -fn test_exp2() { - assert_eq!(32.0, 5.0f64.exp2()); - assert_eq!(1.0, 0.0f64.exp2()); - - let inf: f64 = f64::INFINITY; - let neg_inf: f64 = f64::NEG_INFINITY; - let nan: f64 = f64::NAN; - assert_eq!(inf, inf.exp2()); - assert_eq!(0.0, neg_inf.exp2()); - assert!(nan.exp2().is_nan()); -} - -#[test] -fn test_ln() { - let nan: f64 = f64::NAN; - let inf: f64 = f64::INFINITY; - let neg_inf: f64 = f64::NEG_INFINITY; - assert_approx_eq!(1.0f64.exp().ln(), 1.0); - assert!(nan.ln().is_nan()); - assert_eq!(inf.ln(), inf); - assert!(neg_inf.ln().is_nan()); - assert!((-2.3f64).ln().is_nan()); - assert_eq!((-0.0f64).ln(), neg_inf); - assert_eq!(0.0f64.ln(), neg_inf); - assert_approx_eq!(4.0f64.ln(), 1.386294); -} - -#[test] -fn test_log() { - let nan: f64 = f64::NAN; - let inf: f64 = f64::INFINITY; - let neg_inf: f64 = f64::NEG_INFINITY; - assert_eq!(10.0f64.log(10.0), 1.0); - assert_approx_eq!(2.3f64.log(3.5), 0.664858); - assert_eq!(1.0f64.exp().log(1.0f64.exp()), 1.0); - assert!(1.0f64.log(1.0).is_nan()); - assert!(1.0f64.log(-13.9).is_nan()); - assert!(nan.log(2.3).is_nan()); - assert_eq!(inf.log(10.0), inf); - assert!(neg_inf.log(8.8).is_nan()); - assert!((-2.3f64).log(0.1).is_nan()); - assert_eq!((-0.0f64).log(2.0), neg_inf); - assert_eq!(0.0f64.log(7.0), neg_inf); -} - -#[test] -fn test_log2() { - let nan: f64 = f64::NAN; - let inf: f64 = f64::INFINITY; - let neg_inf: f64 = f64::NEG_INFINITY; - assert_approx_eq!(10.0f64.log2(), 3.321928); - assert_approx_eq!(2.3f64.log2(), 1.201634); - assert_approx_eq!(1.0f64.exp().log2(), 1.442695); - assert!(nan.log2().is_nan()); - assert_eq!(inf.log2(), inf); - assert!(neg_inf.log2().is_nan()); - assert!((-2.3f64).log2().is_nan()); - assert_eq!((-0.0f64).log2(), neg_inf); - assert_eq!(0.0f64.log2(), neg_inf); -} - -#[test] -fn test_log10() { - let nan: f64 = f64::NAN; - let inf: f64 = f64::INFINITY; - let neg_inf: f64 = f64::NEG_INFINITY; - assert_eq!(10.0f64.log10(), 1.0); - assert_approx_eq!(2.3f64.log10(), 0.361728); - assert_approx_eq!(1.0f64.exp().log10(), 0.434294); - assert_eq!(1.0f64.log10(), 0.0); - assert!(nan.log10().is_nan()); - assert_eq!(inf.log10(), inf); - assert!(neg_inf.log10().is_nan()); - assert!((-2.3f64).log10().is_nan()); - assert_eq!((-0.0f64).log10(), neg_inf); - assert_eq!(0.0f64.log10(), neg_inf); -} - -#[test] -fn test_to_degrees() { - let pi: f64 = consts::PI; - let nan: f64 = f64::NAN; - let inf: f64 = f64::INFINITY; - let neg_inf: f64 = f64::NEG_INFINITY; - assert_eq!(0.0f64.to_degrees(), 0.0); - assert_approx_eq!((-5.8f64).to_degrees(), -332.315521); - assert_eq!(pi.to_degrees(), 180.0); - assert!(nan.to_degrees().is_nan()); - assert_eq!(inf.to_degrees(), inf); - assert_eq!(neg_inf.to_degrees(), neg_inf); -} - -#[test] -fn test_to_radians() { - let pi: f64 = consts::PI; - let nan: f64 = f64::NAN; - let inf: f64 = f64::INFINITY; - let neg_inf: f64 = f64::NEG_INFINITY; - assert_eq!(0.0f64.to_radians(), 0.0); - assert_approx_eq!(154.6f64.to_radians(), 2.698279); - assert_approx_eq!((-332.31f64).to_radians(), -5.799903); - assert_eq!(180.0f64.to_radians(), pi); - assert!(nan.to_radians().is_nan()); - assert_eq!(inf.to_radians(), inf); - assert_eq!(neg_inf.to_radians(), neg_inf); -} - -#[test] -fn test_asinh() { - assert_eq!(0.0f64.asinh(), 0.0f64); - assert_eq!((-0.0f64).asinh(), -0.0f64); - - let inf: f64 = f64::INFINITY; - let neg_inf: f64 = f64::NEG_INFINITY; - let nan: f64 = f64::NAN; - assert_eq!(inf.asinh(), inf); - assert_eq!(neg_inf.asinh(), neg_inf); - assert!(nan.asinh().is_nan()); - assert!((-0.0f64).asinh().is_sign_negative()); - // issue 63271 - assert_approx_eq!(2.0f64.asinh(), 1.443635475178810342493276740273105f64); - assert_approx_eq!((-2.0f64).asinh(), -1.443635475178810342493276740273105f64); - // regression test for the catastrophic cancellation fixed in 72486 - assert_approx_eq!((-67452098.07139316f64).asinh(), -18.72007542627454439398548429400083); - - // test for low accuracy from issue 104548 - assert_approx_eq!(60.0f64, 60.0f64.sinh().asinh()); - // mul needed for approximate comparison to be meaningful - assert_approx_eq!(1.0f64, 1e-15f64.sinh().asinh() * 1e15f64); -} - -#[test] -fn test_acosh() { - assert_eq!(1.0f64.acosh(), 0.0f64); - assert!(0.999f64.acosh().is_nan()); - - let inf: f64 = f64::INFINITY; - let neg_inf: f64 = f64::NEG_INFINITY; - let nan: f64 = f64::NAN; - assert_eq!(inf.acosh(), inf); - assert!(neg_inf.acosh().is_nan()); - assert!(nan.acosh().is_nan()); - assert_approx_eq!(2.0f64.acosh(), 1.31695789692481670862504634730796844f64); - assert_approx_eq!(3.0f64.acosh(), 1.76274717403908605046521864995958461f64); - - // test for low accuracy from issue 104548 - assert_approx_eq!(60.0f64, 60.0f64.cosh().acosh()); -} - -#[test] -fn test_atanh() { - assert_eq!(0.0f64.atanh(), 0.0f64); - assert_eq!((-0.0f64).atanh(), -0.0f64); - - let inf: f64 = f64::INFINITY; - let neg_inf: f64 = f64::NEG_INFINITY; - let nan: f64 = f64::NAN; - assert_eq!(1.0f64.atanh(), inf); - assert_eq!((-1.0f64).atanh(), neg_inf); - assert!(2f64.atanh().atanh().is_nan()); - assert!((-2f64).atanh().atanh().is_nan()); - assert!(inf.atanh().is_nan()); - assert!(neg_inf.atanh().is_nan()); - assert!(nan.atanh().is_nan()); - assert_approx_eq!(0.5f64.atanh(), 0.54930614433405484569762261846126285f64); - assert_approx_eq!((-0.5f64).atanh(), -0.54930614433405484569762261846126285f64); -} - -#[test] -fn test_gamma() { - // precision can differ between platforms - assert_approx_eq!(1.0f64.gamma(), 1.0f64); - assert_approx_eq!(2.0f64.gamma(), 1.0f64); - assert_approx_eq!(3.0f64.gamma(), 2.0f64); - assert_approx_eq!(4.0f64.gamma(), 6.0f64); - assert_approx_eq!(5.0f64.gamma(), 24.0f64); - assert_approx_eq!(0.5f64.gamma(), consts::PI.sqrt()); - assert_approx_eq!((-0.5f64).gamma(), -2.0 * consts::PI.sqrt()); - assert_eq!(0.0f64.gamma(), f64::INFINITY); - assert_eq!((-0.0f64).gamma(), f64::NEG_INFINITY); - assert!((-1.0f64).gamma().is_nan()); - assert!((-2.0f64).gamma().is_nan()); - assert!(f64::NAN.gamma().is_nan()); - assert!(f64::NEG_INFINITY.gamma().is_nan()); - assert_eq!(f64::INFINITY.gamma(), f64::INFINITY); - assert_eq!(171.71f64.gamma(), f64::INFINITY); -} - -#[test] -fn test_ln_gamma() { - assert_approx_eq!(1.0f64.ln_gamma().0, 0.0f64); - assert_eq!(1.0f64.ln_gamma().1, 1); - assert_approx_eq!(2.0f64.ln_gamma().0, 0.0f64); - assert_eq!(2.0f64.ln_gamma().1, 1); - assert_approx_eq!(3.0f64.ln_gamma().0, 2.0f64.ln()); - assert_eq!(3.0f64.ln_gamma().1, 1); - assert_approx_eq!((-0.5f64).ln_gamma().0, (2.0 * consts::PI.sqrt()).ln()); - assert_eq!((-0.5f64).ln_gamma().1, -1); -} - -#[test] -fn test_real_consts() { - use super::consts; - let pi: f64 = consts::PI; - let frac_pi_2: f64 = consts::FRAC_PI_2; - let frac_pi_3: f64 = consts::FRAC_PI_3; - let frac_pi_4: f64 = consts::FRAC_PI_4; - let frac_pi_6: f64 = consts::FRAC_PI_6; - let frac_pi_8: f64 = consts::FRAC_PI_8; - let frac_1_pi: f64 = consts::FRAC_1_PI; - let frac_2_pi: f64 = consts::FRAC_2_PI; - let frac_2_sqrtpi: f64 = consts::FRAC_2_SQRT_PI; - let sqrt2: f64 = consts::SQRT_2; - let frac_1_sqrt2: f64 = consts::FRAC_1_SQRT_2; - let e: f64 = consts::E; - let log2_e: f64 = consts::LOG2_E; - let log10_e: f64 = consts::LOG10_E; - let ln_2: f64 = consts::LN_2; - let ln_10: f64 = consts::LN_10; - - assert_approx_eq!(frac_pi_2, pi / 2f64); - assert_approx_eq!(frac_pi_3, pi / 3f64); - assert_approx_eq!(frac_pi_4, pi / 4f64); - assert_approx_eq!(frac_pi_6, pi / 6f64); - assert_approx_eq!(frac_pi_8, pi / 8f64); - assert_approx_eq!(frac_1_pi, 1f64 / pi); - assert_approx_eq!(frac_2_pi, 2f64 / pi); - assert_approx_eq!(frac_2_sqrtpi, 2f64 / pi.sqrt()); - assert_approx_eq!(sqrt2, 2f64.sqrt()); - assert_approx_eq!(frac_1_sqrt2, 1f64 / 2f64.sqrt()); - assert_approx_eq!(log2_e, e.log2()); - assert_approx_eq!(log10_e, e.log10()); - assert_approx_eq!(ln_2, 2f64.ln()); - assert_approx_eq!(ln_10, 10f64.ln()); -} - -#[test] -fn test_float_bits_conv() { - assert_eq!((1f64).to_bits(), 0x3ff0000000000000); - assert_eq!((12.5f64).to_bits(), 0x4029000000000000); - assert_eq!((1337f64).to_bits(), 0x4094e40000000000); - assert_eq!((-14.25f64).to_bits(), 0xc02c800000000000); - assert_approx_eq!(f64::from_bits(0x3ff0000000000000), 1.0); - assert_approx_eq!(f64::from_bits(0x4029000000000000), 12.5); - assert_approx_eq!(f64::from_bits(0x4094e40000000000), 1337.0); - assert_approx_eq!(f64::from_bits(0xc02c800000000000), -14.25); - - // Check that NaNs roundtrip their bits regardless of signaling-ness - // 0xA is 0b1010; 0x5 is 0b0101 -- so these two together clobbers all the mantissa bits - let masked_nan1 = f64::NAN.to_bits() ^ 0x000A_AAAA_AAAA_AAAA; - let masked_nan2 = f64::NAN.to_bits() ^ 0x0005_5555_5555_5555; - assert!(f64::from_bits(masked_nan1).is_nan()); - assert!(f64::from_bits(masked_nan2).is_nan()); - - assert_eq!(f64::from_bits(masked_nan1).to_bits(), masked_nan1); - assert_eq!(f64::from_bits(masked_nan2).to_bits(), masked_nan2); -} - -#[test] -#[should_panic] -fn test_clamp_min_greater_than_max() { - let _ = 1.0f64.clamp(3.0, 1.0); -} - -#[test] -#[should_panic] -fn test_clamp_min_is_nan() { - let _ = 1.0f64.clamp(f64::NAN, 1.0); -} - -#[test] -#[should_panic] -fn test_clamp_max_is_nan() { - let _ = 1.0f64.clamp(3.0, f64::NAN); -} - -#[test] -fn test_total_cmp() { - use core::cmp::Ordering; - - fn quiet_bit_mask() -> u64 { - 1 << (f64::MANTISSA_DIGITS - 2) - } - - fn min_subnorm() -> f64 { - f64::MIN_POSITIVE / f64::powf(2.0, f64::MANTISSA_DIGITS as f64 - 1.0) - } - - fn max_subnorm() -> f64 { - f64::MIN_POSITIVE - min_subnorm() - } - - fn q_nan() -> f64 { - f64::from_bits(f64::NAN.to_bits() | quiet_bit_mask()) - } - - fn s_nan() -> f64 { - f64::from_bits((f64::NAN.to_bits() & !quiet_bit_mask()) + 42) - } - - assert_eq!(Ordering::Equal, (-q_nan()).total_cmp(&-q_nan())); - assert_eq!(Ordering::Equal, (-s_nan()).total_cmp(&-s_nan())); - assert_eq!(Ordering::Equal, (-f64::INFINITY).total_cmp(&-f64::INFINITY)); - assert_eq!(Ordering::Equal, (-f64::MAX).total_cmp(&-f64::MAX)); - assert_eq!(Ordering::Equal, (-2.5_f64).total_cmp(&-2.5)); - assert_eq!(Ordering::Equal, (-1.0_f64).total_cmp(&-1.0)); - assert_eq!(Ordering::Equal, (-1.5_f64).total_cmp(&-1.5)); - assert_eq!(Ordering::Equal, (-0.5_f64).total_cmp(&-0.5)); - assert_eq!(Ordering::Equal, (-f64::MIN_POSITIVE).total_cmp(&-f64::MIN_POSITIVE)); - assert_eq!(Ordering::Equal, (-max_subnorm()).total_cmp(&-max_subnorm())); - assert_eq!(Ordering::Equal, (-min_subnorm()).total_cmp(&-min_subnorm())); - assert_eq!(Ordering::Equal, (-0.0_f64).total_cmp(&-0.0)); - assert_eq!(Ordering::Equal, 0.0_f64.total_cmp(&0.0)); - assert_eq!(Ordering::Equal, min_subnorm().total_cmp(&min_subnorm())); - assert_eq!(Ordering::Equal, max_subnorm().total_cmp(&max_subnorm())); - assert_eq!(Ordering::Equal, f64::MIN_POSITIVE.total_cmp(&f64::MIN_POSITIVE)); - assert_eq!(Ordering::Equal, 0.5_f64.total_cmp(&0.5)); - assert_eq!(Ordering::Equal, 1.0_f64.total_cmp(&1.0)); - assert_eq!(Ordering::Equal, 1.5_f64.total_cmp(&1.5)); - assert_eq!(Ordering::Equal, 2.5_f64.total_cmp(&2.5)); - assert_eq!(Ordering::Equal, f64::MAX.total_cmp(&f64::MAX)); - assert_eq!(Ordering::Equal, f64::INFINITY.total_cmp(&f64::INFINITY)); - assert_eq!(Ordering::Equal, s_nan().total_cmp(&s_nan())); - assert_eq!(Ordering::Equal, q_nan().total_cmp(&q_nan())); - - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-s_nan())); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&-f64::INFINITY)); - assert_eq!(Ordering::Less, (-f64::INFINITY).total_cmp(&-f64::MAX)); - assert_eq!(Ordering::Less, (-f64::MAX).total_cmp(&-2.5)); - assert_eq!(Ordering::Less, (-2.5_f64).total_cmp(&-1.5)); - assert_eq!(Ordering::Less, (-1.5_f64).total_cmp(&-1.0)); - assert_eq!(Ordering::Less, (-1.0_f64).total_cmp(&-0.5)); - assert_eq!(Ordering::Less, (-0.5_f64).total_cmp(&-f64::MIN_POSITIVE)); - assert_eq!(Ordering::Less, (-f64::MIN_POSITIVE).total_cmp(&-max_subnorm())); - assert_eq!(Ordering::Less, (-max_subnorm()).total_cmp(&-min_subnorm())); - assert_eq!(Ordering::Less, (-min_subnorm()).total_cmp(&-0.0)); - assert_eq!(Ordering::Less, (-0.0_f64).total_cmp(&0.0)); - assert_eq!(Ordering::Less, 0.0_f64.total_cmp(&min_subnorm())); - assert_eq!(Ordering::Less, min_subnorm().total_cmp(&max_subnorm())); - assert_eq!(Ordering::Less, max_subnorm().total_cmp(&f64::MIN_POSITIVE)); - assert_eq!(Ordering::Less, f64::MIN_POSITIVE.total_cmp(&0.5)); - assert_eq!(Ordering::Less, 0.5_f64.total_cmp(&1.0)); - assert_eq!(Ordering::Less, 1.0_f64.total_cmp(&1.5)); - assert_eq!(Ordering::Less, 1.5_f64.total_cmp(&2.5)); - assert_eq!(Ordering::Less, 2.5_f64.total_cmp(&f64::MAX)); - assert_eq!(Ordering::Less, f64::MAX.total_cmp(&f64::INFINITY)); - assert_eq!(Ordering::Less, f64::INFINITY.total_cmp(&s_nan())); - assert_eq!(Ordering::Less, s_nan().total_cmp(&q_nan())); - - assert_eq!(Ordering::Greater, (-s_nan()).total_cmp(&-q_nan())); - assert_eq!(Ordering::Greater, (-f64::INFINITY).total_cmp(&-s_nan())); - assert_eq!(Ordering::Greater, (-f64::MAX).total_cmp(&-f64::INFINITY)); - assert_eq!(Ordering::Greater, (-2.5_f64).total_cmp(&-f64::MAX)); - assert_eq!(Ordering::Greater, (-1.5_f64).total_cmp(&-2.5)); - assert_eq!(Ordering::Greater, (-1.0_f64).total_cmp(&-1.5)); - assert_eq!(Ordering::Greater, (-0.5_f64).total_cmp(&-1.0)); - assert_eq!(Ordering::Greater, (-f64::MIN_POSITIVE).total_cmp(&-0.5)); - assert_eq!(Ordering::Greater, (-max_subnorm()).total_cmp(&-f64::MIN_POSITIVE)); - assert_eq!(Ordering::Greater, (-min_subnorm()).total_cmp(&-max_subnorm())); - assert_eq!(Ordering::Greater, (-0.0_f64).total_cmp(&-min_subnorm())); - assert_eq!(Ordering::Greater, 0.0_f64.total_cmp(&-0.0)); - assert_eq!(Ordering::Greater, min_subnorm().total_cmp(&0.0)); - assert_eq!(Ordering::Greater, max_subnorm().total_cmp(&min_subnorm())); - assert_eq!(Ordering::Greater, f64::MIN_POSITIVE.total_cmp(&max_subnorm())); - assert_eq!(Ordering::Greater, 0.5_f64.total_cmp(&f64::MIN_POSITIVE)); - assert_eq!(Ordering::Greater, 1.0_f64.total_cmp(&0.5)); - assert_eq!(Ordering::Greater, 1.5_f64.total_cmp(&1.0)); - assert_eq!(Ordering::Greater, 2.5_f64.total_cmp(&1.5)); - assert_eq!(Ordering::Greater, f64::MAX.total_cmp(&2.5)); - assert_eq!(Ordering::Greater, f64::INFINITY.total_cmp(&f64::MAX)); - assert_eq!(Ordering::Greater, s_nan().total_cmp(&f64::INFINITY)); - assert_eq!(Ordering::Greater, q_nan().total_cmp(&s_nan())); - - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-s_nan())); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-f64::INFINITY)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-f64::MAX)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-2.5)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-1.5)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-1.0)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-0.5)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-f64::MIN_POSITIVE)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-max_subnorm())); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-min_subnorm())); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&-0.0)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&0.0)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&min_subnorm())); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&max_subnorm())); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&f64::MIN_POSITIVE)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&0.5)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&1.0)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&1.5)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&2.5)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&f64::MAX)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&f64::INFINITY)); - assert_eq!(Ordering::Less, (-q_nan()).total_cmp(&s_nan())); - - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&-f64::INFINITY)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&-f64::MAX)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&-2.5)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&-1.5)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&-1.0)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&-0.5)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&-f64::MIN_POSITIVE)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&-max_subnorm())); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&-min_subnorm())); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&-0.0)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&0.0)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&min_subnorm())); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&max_subnorm())); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&f64::MIN_POSITIVE)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&0.5)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&1.0)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&1.5)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&2.5)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&f64::MAX)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&f64::INFINITY)); - assert_eq!(Ordering::Less, (-s_nan()).total_cmp(&s_nan())); -} diff --git a/library/std/src/ffi/c_str.rs b/library/std/src/ffi/c_str.rs deleted file mode 100644 index b59b0c5bba65a..0000000000000 --- a/library/std/src/ffi/c_str.rs +++ /dev/null @@ -1,19 +0,0 @@ -//! [`CStr`], [`CString`], and related types. - -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::ffi::c_str::CStr; - -#[stable(feature = "cstr_from_bytes", since = "1.10.0")] -pub use core::ffi::c_str::FromBytesWithNulError; - -#[stable(feature = "cstr_from_bytes_until_nul", since = "1.69.0")] -pub use core::ffi::c_str::FromBytesUntilNulError; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use alloc::ffi::c_str::{CString, NulError}; - -#[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")] -pub use alloc::ffi::c_str::FromVecWithNulError; - -#[stable(feature = "cstring_into", since = "1.7.0")] -pub use alloc::ffi::c_str::IntoStringError; diff --git a/library/std/src/ffi/mod.rs b/library/std/src/ffi/mod.rs deleted file mode 100644 index f45fd77e8b167..0000000000000 --- a/library/std/src/ffi/mod.rs +++ /dev/null @@ -1,213 +0,0 @@ -//! Utilities related to FFI bindings. -//! -//! This module provides utilities to handle data across non-Rust -//! interfaces, like other programming languages and the underlying -//! operating system. It is mainly of use for FFI (Foreign Function -//! Interface) bindings and code that needs to exchange C-like strings -//! with other languages. -//! -//! # Overview -//! -//! Rust represents owned strings with the [`String`] type, and -//! borrowed slices of strings with the [`str`] primitive. Both are -//! always in UTF-8 encoding, and may contain nul bytes in the middle, -//! i.e., if you look at the bytes that make up the string, there may -//! be a `\0` among them. Both `String` and `str` store their length -//! explicitly; there are no nul terminators at the end of strings -//! like in C. -//! -//! C strings are different from Rust strings: -//! -//! * **Encodings** - Rust strings are UTF-8, but C strings may use -//! other encodings. If you are using a string from C, you should -//! check its encoding explicitly, rather than just assuming that it -//! is UTF-8 like you can do in Rust. -//! -//! * **Character size** - C strings may use `char` or `wchar_t`-sized -//! characters; please **note** that C's `char` is different from Rust's. -//! The C standard leaves the actual sizes of those types open to -//! interpretation, but defines different APIs for strings made up of -//! each character type. Rust strings are always UTF-8, so different -//! Unicode characters will be encoded in a variable number of bytes -//! each. The Rust type [`char`] represents a '[Unicode scalar -//! value]', which is similar to, but not the same as, a '[Unicode -//! code point]'. -//! -//! * **Nul terminators and implicit string lengths** - Often, C -//! strings are nul-terminated, i.e., they have a `\0` character at the -//! end. The length of a string buffer is not stored, but has to be -//! calculated; to compute the length of a string, C code must -//! manually call a function like `strlen()` for `char`-based strings, -//! or `wcslen()` for `wchar_t`-based ones. Those functions return -//! the number of characters in the string excluding the nul -//! terminator, so the buffer length is really `len+1` characters. -//! Rust strings don't have a nul terminator; their length is always -//! stored and does not need to be calculated. While in Rust -//! accessing a string's length is an *O*(1) operation (because the -//! length is stored); in C it is an *O*(*n*) operation because the -//! length needs to be computed by scanning the string for the nul -//! terminator. -//! -//! * **Internal nul characters** - When C strings have a nul -//! terminator character, this usually means that they cannot have nul -//! characters in the middle — a nul character would essentially -//! truncate the string. Rust strings *can* have nul characters in -//! the middle, because nul does not have to mark the end of the -//! string in Rust. -//! -//! # Representations of non-Rust strings -//! -//! [`CString`] and [`CStr`] are useful when you need to transfer -//! UTF-8 strings to and from languages with a C ABI, like Python. -//! -//! * **From Rust to C:** [`CString`] represents an owned, C-friendly -//! string: it is nul-terminated, and has no internal nul characters. -//! Rust code can create a [`CString`] out of a normal string (provided -//! that the string doesn't have nul characters in the middle), and -//! then use a variety of methods to obtain a raw \*mut [u8] that can -//! then be passed as an argument to functions which use the C -//! conventions for strings. -//! -//! * **From C to Rust:** [`CStr`] represents a borrowed C string; it -//! is what you would use to wrap a raw \*const [u8] that you got from -//! a C function. A [`CStr`] is guaranteed to be a nul-terminated array -//! of bytes. Once you have a [`CStr`], you can convert it to a Rust -//! &[str] if it's valid UTF-8, or lossily convert it by adding -//! replacement characters. -//! -//! [`OsString`] and [`OsStr`] are useful when you need to transfer -//! strings to and from the operating system itself, or when capturing -//! the output of external commands. Conversions between [`OsString`], -//! [`OsStr`] and Rust strings work similarly to those for [`CString`] -//! and [`CStr`]. -//! -//! * [`OsString`] losslessly represents an owned platform string. However, this -//! representation is not necessarily in a form native to the platform. -//! In the Rust standard library, various APIs that transfer strings to/from the operating -//! system use [`OsString`] instead of plain strings. For example, -//! [`env::var_os()`] is used to query environment variables; it -//! returns an [Option]<[OsString]>. If the environment variable -//! exists you will get a [Some]\(os_string), which you can -//! *then* try to convert to a Rust string. This yields a [`Result`], so that -//! your code can detect errors in case the environment variable did -//! not in fact contain valid Unicode data. -//! -//! * [`OsStr`] losslessly represents a borrowed reference to a platform string. -//! However, this representation is not necessarily in a form native to the platform. -//! It can be converted into a UTF-8 Rust string slice in a similar way to -//! [`OsString`]. -//! -//! # Conversions -//! -//! ## On Unix -//! -//! On Unix, [`OsStr`] implements the -//! std::os::unix::ffi::[OsStrExt][unix.OsStrExt] trait, which -//! augments it with two methods, [`from_bytes`] and [`as_bytes`]. -//! These do inexpensive conversions from and to byte slices. -//! -//! Additionally, on Unix [`OsString`] implements the -//! std::os::unix::ffi::[OsStringExt][unix.OsStringExt] trait, -//! which provides [`from_vec`] and [`into_vec`] methods that consume -//! their arguments, and take or produce vectors of [`u8`]. -//! -//! ## On Windows -//! -//! An [`OsStr`] can be losslessly converted to a native Windows string. And -//! a native Windows string can be losslessly converted to an [`OsString`]. -//! -//! On Windows, [`OsStr`] implements the -//! std::os::windows::ffi::[OsStrExt][windows.OsStrExt] trait, -//! which provides an [`encode_wide`] method. This provides an -//! iterator that can be [`collect`]ed into a vector of [`u16`]. After a nul -//! characters is appended, this is the same as a native Windows string. -//! -//! Additionally, on Windows [`OsString`] implements the -//! std::os::windows:ffi::[OsStringExt][windows.OsStringExt] -//! trait, which provides a [`from_wide`] method to convert a native Windows -//! string (without the terminating nul character) to an [`OsString`]. -//! -//! ## Other platforms -//! -//! Many other platforms provide their own extension traits in a -//! `std::os::*::ffi` module. -//! -//! ## On all platforms -//! -//! On all platforms, [`OsStr`] consists of a sequence of bytes that is encoded as a superset of -//! UTF-8; see [`OsString`] for more details on its encoding on different platforms. -//! -//! For limited, inexpensive conversions from and to bytes, see [`OsStr::as_encoded_bytes`] and -//! [`OsStr::from_encoded_bytes_unchecked`]. -//! -//! For basic string processing, see [`OsStr::slice_encoded_bytes`]. -//! -//! [Unicode scalar value]: https://www.unicode.org/glossary/#unicode_scalar_value -//! [Unicode code point]: https://www.unicode.org/glossary/#code_point -//! [`env::set_var()`]: crate::env::set_var "env::set_var" -//! [`env::var_os()`]: crate::env::var_os "env::var_os" -//! [unix.OsStringExt]: crate::os::unix::ffi::OsStringExt "os::unix::ffi::OsStringExt" -//! [`from_vec`]: crate::os::unix::ffi::OsStringExt::from_vec "os::unix::ffi::OsStringExt::from_vec" -//! [`into_vec`]: crate::os::unix::ffi::OsStringExt::into_vec "os::unix::ffi::OsStringExt::into_vec" -//! [unix.OsStrExt]: crate::os::unix::ffi::OsStrExt "os::unix::ffi::OsStrExt" -//! [`from_bytes`]: crate::os::unix::ffi::OsStrExt::from_bytes "os::unix::ffi::OsStrExt::from_bytes" -//! [`as_bytes`]: crate::os::unix::ffi::OsStrExt::as_bytes "os::unix::ffi::OsStrExt::as_bytes" -//! [`OsStrExt`]: crate::os::unix::ffi::OsStrExt "os::unix::ffi::OsStrExt" -//! [windows.OsStrExt]: crate::os::windows::ffi::OsStrExt "os::windows::ffi::OsStrExt" -//! [`encode_wide`]: crate::os::windows::ffi::OsStrExt::encode_wide "os::windows::ffi::OsStrExt::encode_wide" -//! [`collect`]: crate::iter::Iterator::collect "iter::Iterator::collect" -//! [windows.OsStringExt]: crate::os::windows::ffi::OsStringExt "os::windows::ffi::OsStringExt" -//! [`from_wide`]: crate::os::windows::ffi::OsStringExt::from_wide "os::windows::ffi::OsStringExt::from_wide" - -#![stable(feature = "rust1", since = "1.0.0")] - -#[unstable(feature = "c_str_module", issue = "112134")] -pub mod c_str; - -#[doc(inline)] -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::c_str::{CStr, CString}; - -#[doc(no_inline)] -#[stable(feature = "cstr_from_bytes", since = "1.10.0")] -pub use self::c_str::FromBytesWithNulError; - -#[doc(no_inline)] -#[stable(feature = "cstr_from_bytes_until_nul", since = "1.69.0")] -pub use self::c_str::FromBytesUntilNulError; - -#[doc(no_inline)] -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::c_str::NulError; - -#[doc(no_inline)] -#[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")] -pub use self::c_str::FromVecWithNulError; - -#[doc(no_inline)] -#[stable(feature = "cstring_into", since = "1.7.0")] -pub use self::c_str::IntoStringError; - -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(inline)] -pub use self::os_str::{OsStr, OsString}; - -#[stable(feature = "core_ffi_c", since = "1.64.0")] -pub use core::ffi::{ - c_char, c_double, c_float, c_int, c_long, c_longlong, c_schar, c_short, c_uchar, c_uint, - c_ulong, c_ulonglong, c_ushort, -}; - -#[stable(feature = "core_c_void", since = "1.30.0")] -pub use core::ffi::c_void; - -#[unstable( - feature = "c_variadic", - reason = "the `c_variadic` feature has not been properly tested on \ - all supported platforms", - issue = "44930" -)] -pub use core::ffi::{VaList, VaListImpl}; - -#[unstable(feature = "os_str_display", issue = "120048")] -pub mod os_str; diff --git a/library/std/src/ffi/os_str.rs b/library/std/src/ffi/os_str.rs deleted file mode 100644 index 9dd3d7d3fa16a..0000000000000 --- a/library/std/src/ffi/os_str.rs +++ /dev/null @@ -1,1705 +0,0 @@ -//! The [`OsStr`] and [`OsString`] types and associated utilities. - -#[cfg(test)] -mod tests; - -use crate::borrow::{Borrow, Cow}; -use crate::cmp; -use crate::collections::TryReserveError; -use crate::fmt; -use crate::hash::{Hash, Hasher}; -use crate::ops::{self, Range}; -use crate::rc::Rc; -use crate::slice; -use crate::str::FromStr; -use crate::sync::Arc; - -use crate::sys::os_str::{Buf, Slice}; -use crate::sys_common::{AsInner, FromInner, IntoInner}; - -/// A type that can represent owned, mutable platform-native strings, but is -/// cheaply inter-convertible with Rust strings. -/// -/// The need for this type arises from the fact that: -/// -/// * On Unix systems, strings are often arbitrary sequences of non-zero -/// bytes, in many cases interpreted as UTF-8. -/// -/// * On Windows, strings are often arbitrary sequences of non-zero 16-bit -/// values, interpreted as UTF-16 when it is valid to do so. -/// -/// * In Rust, strings are always valid UTF-8, which may contain zeros. -/// -/// `OsString` and [`OsStr`] bridge this gap by simultaneously representing Rust -/// and platform-native string values, and in particular allowing a Rust string -/// to be converted into an "OS" string with no cost if possible. A consequence -/// of this is that `OsString` instances are *not* `NUL` terminated; in order -/// to pass to e.g., Unix system call, you should create a [`CStr`]. -/// -/// `OsString` is to &[OsStr] as [`String`] is to &[str]: the former -/// in each pair are owned strings; the latter are borrowed -/// references. -/// -/// Note, `OsString` and [`OsStr`] internally do not necessarily hold strings in -/// the form native to the platform; While on Unix, strings are stored as a -/// sequence of 8-bit values, on Windows, where strings are 16-bit value based -/// as just discussed, strings are also actually stored as a sequence of 8-bit -/// values, encoded in a less-strict variant of UTF-8. This is useful to -/// understand when handling capacity and length values. -/// -/// # Capacity of `OsString` -/// -/// Capacity uses units of UTF-8 bytes for OS strings which were created from valid unicode, and -/// uses units of bytes in an unspecified encoding for other contents. On a given target, all -/// `OsString` and `OsStr` values use the same units for capacity, so the following will work: -/// ``` -/// use std::ffi::{OsStr, OsString}; -/// -/// fn concat_os_strings(a: &OsStr, b: &OsStr) -> OsString { -/// let mut ret = OsString::with_capacity(a.len() + b.len()); // This will allocate -/// ret.push(a); // This will not allocate further -/// ret.push(b); // This will not allocate further -/// ret -/// } -/// ``` -/// -/// # Creating an `OsString` -/// -/// **From a Rust string**: `OsString` implements -/// [From]<[String]>, so you can use my_string.[into]\() to -/// create an `OsString` from a normal Rust string. -/// -/// **From slices:** Just like you can start with an empty Rust -/// [`String`] and then [`String::push_str`] some &[str] -/// sub-string slices into it, you can create an empty `OsString` with -/// the [`OsString::new`] method and then push string slices into it with the -/// [`OsString::push`] method. -/// -/// # Extracting a borrowed reference to the whole OS string -/// -/// You can use the [`OsString::as_os_str`] method to get an &[OsStr] from -/// an `OsString`; this is effectively a borrowed reference to the -/// whole string. -/// -/// # Conversions -/// -/// See the [module's toplevel documentation about conversions][conversions] for a discussion on -/// the traits which `OsString` implements for [conversions] from/to native representations. -/// -/// [`CStr`]: crate::ffi::CStr -/// [conversions]: super#conversions -/// [into]: Into::into -#[cfg_attr(not(test), rustc_diagnostic_item = "OsString")] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct OsString { - inner: Buf, -} - -/// Allows extension traits within `std`. -#[unstable(feature = "sealed", issue = "none")] -impl crate::sealed::Sealed for OsString {} - -/// Borrowed reference to an OS string (see [`OsString`]). -/// -/// This type represents a borrowed reference to a string in the operating system's preferred -/// representation. -/// -/// `&OsStr` is to [`OsString`] as &[str] is to [`String`]: the -/// former in each pair are borrowed references; the latter are owned strings. -/// -/// See the [module's toplevel documentation about conversions][conversions] for a discussion on -/// the traits which `OsStr` implements for [conversions] from/to native representations. -/// -/// [conversions]: super#conversions -#[cfg_attr(not(test), rustc_diagnostic_item = "OsStr")] -#[stable(feature = "rust1", since = "1.0.0")] -// `OsStr::from_inner` current implementation relies -// on `OsStr` being layout-compatible with `Slice`. -// However, `OsStr` layout is considered an implementation detail and must not be relied upon. We -// want `repr(transparent)` but we don't want it to show up in rustdoc, so we hide it under -// `cfg(doc)`. This is an ad-hoc implementation of attribute privacy. -#[cfg_attr(not(doc), repr(transparent))] -pub struct OsStr { - inner: Slice, -} - -/// Allows extension traits within `std`. -#[unstable(feature = "sealed", issue = "none")] -impl crate::sealed::Sealed for OsStr {} - -impl OsString { - /// Constructs a new empty `OsString`. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsString; - /// - /// let os_string = OsString::new(); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - #[inline] - pub fn new() -> OsString { - OsString { inner: Buf::from_string(String::new()) } - } - - /// Converts bytes to an `OsString` without checking that the bytes contains - /// valid [`OsStr`]-encoded data. - /// - /// The byte encoding is an unspecified, platform-specific, self-synchronizing superset of UTF-8. - /// By being a self-synchronizing superset of UTF-8, this encoding is also a superset of 7-bit - /// ASCII. - /// - /// See the [module's toplevel documentation about conversions][conversions] for safe, - /// cross-platform [conversions] from/to native representations. - /// - /// # Safety - /// - /// As the encoding is unspecified, callers must pass in bytes that originated as a mixture of - /// validated UTF-8 and bytes from [`OsStr::as_encoded_bytes`] from within the same Rust version - /// built for the same target platform. For example, reconstructing an `OsString` from bytes sent - /// over the network or stored in a file will likely violate these safety rules. - /// - /// Due to the encoding being self-synchronizing, the bytes from [`OsStr::as_encoded_bytes`] can be - /// split either immediately before or immediately after any valid non-empty UTF-8 substring. - /// - /// # Example - /// - /// ``` - /// use std::ffi::OsStr; - /// - /// let os_str = OsStr::new("Mary had a little lamb"); - /// let bytes = os_str.as_encoded_bytes(); - /// let words = bytes.split(|b| *b == b' '); - /// let words: Vec<&OsStr> = words.map(|word| { - /// // SAFETY: - /// // - Each `word` only contains content that originated from `OsStr::as_encoded_bytes` - /// // - Only split with ASCII whitespace which is a non-empty UTF-8 substring - /// unsafe { OsStr::from_encoded_bytes_unchecked(word) } - /// }).collect(); - /// ``` - /// - /// [conversions]: super#conversions - #[inline] - #[stable(feature = "os_str_bytes", since = "1.74.0")] - pub unsafe fn from_encoded_bytes_unchecked(bytes: Vec) -> Self { - OsString { inner: Buf::from_encoded_bytes_unchecked(bytes) } - } - - /// Converts to an [`OsStr`] slice. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::{OsString, OsStr}; - /// - /// let os_string = OsString::from("foo"); - /// let os_str = OsStr::new("foo"); - /// assert_eq!(os_string.as_os_str(), os_str); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - #[inline] - pub fn as_os_str(&self) -> &OsStr { - self - } - - /// Converts the `OsString` into a byte slice. To convert the byte slice back into an - /// `OsString`, use the [`OsStr::from_encoded_bytes_unchecked`] function. - /// - /// The byte encoding is an unspecified, platform-specific, self-synchronizing superset of UTF-8. - /// By being a self-synchronizing superset of UTF-8, this encoding is also a superset of 7-bit - /// ASCII. - /// - /// Note: As the encoding is unspecified, any sub-slice of bytes that is not valid UTF-8 should - /// be treated as opaque and only comparable within the same Rust version built for the same - /// target platform. For example, sending the bytes over the network or storing it in a file - /// will likely result in incompatible data. See [`OsString`] for more encoding details - /// and [`std::ffi`] for platform-specific, specified conversions. - /// - /// [`std::ffi`]: crate::ffi - #[inline] - #[stable(feature = "os_str_bytes", since = "1.74.0")] - pub fn into_encoded_bytes(self) -> Vec { - self.inner.into_encoded_bytes() - } - - /// Converts the `OsString` into a [`String`] if it contains valid Unicode data. - /// - /// On failure, ownership of the original `OsString` is returned. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsString; - /// - /// let os_string = OsString::from("foo"); - /// let string = os_string.into_string(); - /// assert_eq!(string, Ok(String::from("foo"))); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn into_string(self) -> Result { - self.inner.into_string().map_err(|buf| OsString { inner: buf }) - } - - /// Extends the string with the given &[OsStr] slice. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsString; - /// - /// let mut os_string = OsString::from("foo"); - /// os_string.push("bar"); - /// assert_eq!(&os_string, "foobar"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - #[rustc_confusables("append", "put")] - pub fn push>(&mut self, s: T) { - self.inner.push_slice(&s.as_ref().inner) - } - - /// Creates a new `OsString` with at least the given capacity. - /// - /// The string will be able to hold at least `capacity` length units of other - /// OS strings without reallocating. This method is allowed to allocate for - /// more units than `capacity`. If `capacity` is 0, the string will not - /// allocate. - /// - /// See the main `OsString` documentation information about encoding and capacity units. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsString; - /// - /// let mut os_string = OsString::with_capacity(10); - /// let capacity = os_string.capacity(); - /// - /// // This push is done without reallocating - /// os_string.push("foo"); - /// - /// assert_eq!(capacity, os_string.capacity()); - /// ``` - #[stable(feature = "osstring_simple_functions", since = "1.9.0")] - #[must_use] - #[inline] - pub fn with_capacity(capacity: usize) -> OsString { - OsString { inner: Buf::with_capacity(capacity) } - } - - /// Truncates the `OsString` to zero length. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsString; - /// - /// let mut os_string = OsString::from("foo"); - /// assert_eq!(&os_string, "foo"); - /// - /// os_string.clear(); - /// assert_eq!(&os_string, ""); - /// ``` - #[stable(feature = "osstring_simple_functions", since = "1.9.0")] - #[inline] - pub fn clear(&mut self) { - self.inner.clear() - } - - /// Returns the capacity this `OsString` can hold without reallocating. - /// - /// See the main `OsString` documentation information about encoding and capacity units. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsString; - /// - /// let os_string = OsString::with_capacity(10); - /// assert!(os_string.capacity() >= 10); - /// ``` - #[stable(feature = "osstring_simple_functions", since = "1.9.0")] - #[must_use] - #[inline] - pub fn capacity(&self) -> usize { - self.inner.capacity() - } - - /// Reserves capacity for at least `additional` more capacity to be inserted - /// in the given `OsString`. Does nothing if the capacity is - /// already sufficient. - /// - /// The collection may reserve more space to speculatively avoid frequent reallocations. - /// - /// See the main `OsString` documentation information about encoding and capacity units. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsString; - /// - /// let mut s = OsString::new(); - /// s.reserve(10); - /// assert!(s.capacity() >= 10); - /// ``` - #[stable(feature = "osstring_simple_functions", since = "1.9.0")] - #[inline] - pub fn reserve(&mut self, additional: usize) { - self.inner.reserve(additional) - } - - /// Tries to reserve capacity for at least `additional` more length units - /// in the given `OsString`. The string may reserve more space to speculatively avoid - /// frequent reallocations. After calling `try_reserve`, capacity will be - /// greater than or equal to `self.len() + additional` if it returns `Ok(())`. - /// Does nothing if capacity is already sufficient. This method preserves - /// the contents even if an error occurs. - /// - /// See the main `OsString` documentation information about encoding and capacity units. - /// - /// # Errors - /// - /// If the capacity overflows, or the allocator reports a failure, then an error - /// is returned. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::{OsStr, OsString}; - /// use std::collections::TryReserveError; - /// - /// fn process_data(data: &str) -> Result { - /// let mut s = OsString::new(); - /// - /// // Pre-reserve the memory, exiting if we can't - /// s.try_reserve(OsStr::new(data).len())?; - /// - /// // Now we know this can't OOM in the middle of our complex work - /// s.push(data); - /// - /// Ok(s) - /// } - /// # process_data("123").expect("why is the test harness OOMing on 3 bytes?"); - /// ``` - #[stable(feature = "try_reserve_2", since = "1.63.0")] - #[inline] - pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> { - self.inner.try_reserve(additional) - } - - /// Reserves the minimum capacity for at least `additional` more capacity to - /// be inserted in the given `OsString`. Does nothing if the capacity is - /// already sufficient. - /// - /// Note that the allocator may give the collection more space than it - /// requests. Therefore, capacity can not be relied upon to be precisely - /// minimal. Prefer [`reserve`] if future insertions are expected. - /// - /// [`reserve`]: OsString::reserve - /// - /// See the main `OsString` documentation information about encoding and capacity units. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsString; - /// - /// let mut s = OsString::new(); - /// s.reserve_exact(10); - /// assert!(s.capacity() >= 10); - /// ``` - #[stable(feature = "osstring_simple_functions", since = "1.9.0")] - #[inline] - pub fn reserve_exact(&mut self, additional: usize) { - self.inner.reserve_exact(additional) - } - - /// Tries to reserve the minimum capacity for at least `additional` - /// more length units in the given `OsString`. After calling - /// `try_reserve_exact`, capacity will be greater than or equal to - /// `self.len() + additional` if it returns `Ok(())`. - /// Does nothing if the capacity is already sufficient. - /// - /// Note that the allocator may give the `OsString` more space than it - /// requests. Therefore, capacity can not be relied upon to be precisely - /// minimal. Prefer [`try_reserve`] if future insertions are expected. - /// - /// [`try_reserve`]: OsString::try_reserve - /// - /// See the main `OsString` documentation information about encoding and capacity units. - /// - /// # Errors - /// - /// If the capacity overflows, or the allocator reports a failure, then an error - /// is returned. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::{OsStr, OsString}; - /// use std::collections::TryReserveError; - /// - /// fn process_data(data: &str) -> Result { - /// let mut s = OsString::new(); - /// - /// // Pre-reserve the memory, exiting if we can't - /// s.try_reserve_exact(OsStr::new(data).len())?; - /// - /// // Now we know this can't OOM in the middle of our complex work - /// s.push(data); - /// - /// Ok(s) - /// } - /// # process_data("123").expect("why is the test harness OOMing on 3 bytes?"); - /// ``` - #[stable(feature = "try_reserve_2", since = "1.63.0")] - #[inline] - pub fn try_reserve_exact(&mut self, additional: usize) -> Result<(), TryReserveError> { - self.inner.try_reserve_exact(additional) - } - - /// Shrinks the capacity of the `OsString` to match its length. - /// - /// See the main `OsString` documentation information about encoding and capacity units. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsString; - /// - /// let mut s = OsString::from("foo"); - /// - /// s.reserve(100); - /// assert!(s.capacity() >= 100); - /// - /// s.shrink_to_fit(); - /// assert_eq!(3, s.capacity()); - /// ``` - #[stable(feature = "osstring_shrink_to_fit", since = "1.19.0")] - #[inline] - pub fn shrink_to_fit(&mut self) { - self.inner.shrink_to_fit() - } - - /// Shrinks the capacity of the `OsString` with a lower bound. - /// - /// The capacity will remain at least as large as both the length - /// and the supplied value. - /// - /// If the current capacity is less than the lower limit, this is a no-op. - /// - /// See the main `OsString` documentation information about encoding and capacity units. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsString; - /// - /// let mut s = OsString::from("foo"); - /// - /// s.reserve(100); - /// assert!(s.capacity() >= 100); - /// - /// s.shrink_to(10); - /// assert!(s.capacity() >= 10); - /// s.shrink_to(0); - /// assert!(s.capacity() >= 3); - /// ``` - #[inline] - #[stable(feature = "shrink_to", since = "1.56.0")] - pub fn shrink_to(&mut self, min_capacity: usize) { - self.inner.shrink_to(min_capacity) - } - - /// Converts this `OsString` into a boxed [`OsStr`]. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::{OsString, OsStr}; - /// - /// let s = OsString::from("hello"); - /// - /// let b: Box = s.into_boxed_os_str(); - /// ``` - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "into_boxed_os_str", since = "1.20.0")] - pub fn into_boxed_os_str(self) -> Box { - let rw = Box::into_raw(self.inner.into_box()) as *mut OsStr; - unsafe { Box::from_raw(rw) } - } - - /// Part of a hack to make PathBuf::push/pop more efficient. - #[inline] - pub(crate) fn as_mut_vec_for_path_buf(&mut self) -> &mut Vec { - self.inner.as_mut_vec_for_path_buf() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl From for OsString { - /// Converts a [`String`] into an [`OsString`]. - /// - /// This conversion does not allocate or copy memory. - #[inline] - fn from(s: String) -> OsString { - OsString { inner: Buf::from_string(s) } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl> From<&T> for OsString { - /// Copies any value implementing [AsRef]<[OsStr]> - /// into a newly allocated [`OsString`]. - fn from(s: &T) -> OsString { - s.as_ref().to_os_string() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ops::Index for OsString { - type Output = OsStr; - - #[inline] - fn index(&self, _index: ops::RangeFull) -> &OsStr { - OsStr::from_inner(self.inner.as_slice()) - } -} - -#[stable(feature = "mut_osstr", since = "1.44.0")] -impl ops::IndexMut for OsString { - #[inline] - fn index_mut(&mut self, _index: ops::RangeFull) -> &mut OsStr { - OsStr::from_inner_mut(self.inner.as_mut_slice()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ops::Deref for OsString { - type Target = OsStr; - - #[inline] - fn deref(&self) -> &OsStr { - &self[..] - } -} - -#[stable(feature = "mut_osstr", since = "1.44.0")] -impl ops::DerefMut for OsString { - #[inline] - fn deref_mut(&mut self) -> &mut OsStr { - &mut self[..] - } -} - -#[stable(feature = "osstring_default", since = "1.9.0")] -impl Default for OsString { - /// Constructs an empty `OsString`. - #[inline] - fn default() -> OsString { - OsString::new() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for OsString { - #[inline] - fn clone(&self) -> Self { - OsString { inner: self.inner.clone() } - } - - /// Clones the contents of `source` into `self`. - /// - /// This method is preferred over simply assigning `source.clone()` to `self`, - /// as it avoids reallocation if possible. - #[inline] - fn clone_from(&mut self, source: &Self) { - self.inner.clone_from(&source.inner) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for OsString { - fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&**self, formatter) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for OsString { - #[inline] - fn eq(&self, other: &OsString) -> bool { - &**self == &**other - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for OsString { - #[inline] - fn eq(&self, other: &str) -> bool { - &**self == other - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for str { - #[inline] - fn eq(&self, other: &OsString) -> bool { - &**other == self - } -} - -#[stable(feature = "os_str_str_ref_eq", since = "1.29.0")] -impl PartialEq<&str> for OsString { - #[inline] - fn eq(&self, other: &&str) -> bool { - **self == **other - } -} - -#[stable(feature = "os_str_str_ref_eq", since = "1.29.0")] -impl<'a> PartialEq for &'a str { - #[inline] - fn eq(&self, other: &OsString) -> bool { - **other == **self - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Eq for OsString {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialOrd for OsString { - #[inline] - fn partial_cmp(&self, other: &OsString) -> Option { - (&**self).partial_cmp(&**other) - } - #[inline] - fn lt(&self, other: &OsString) -> bool { - &**self < &**other - } - #[inline] - fn le(&self, other: &OsString) -> bool { - &**self <= &**other - } - #[inline] - fn gt(&self, other: &OsString) -> bool { - &**self > &**other - } - #[inline] - fn ge(&self, other: &OsString) -> bool { - &**self >= &**other - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialOrd for OsString { - #[inline] - fn partial_cmp(&self, other: &str) -> Option { - (&**self).partial_cmp(other) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for OsString { - #[inline] - fn cmp(&self, other: &OsString) -> cmp::Ordering { - (&**self).cmp(&**other) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Hash for OsString { - #[inline] - fn hash(&self, state: &mut H) { - (&**self).hash(state) - } -} - -#[stable(feature = "os_string_fmt_write", since = "1.64.0")] -impl fmt::Write for OsString { - fn write_str(&mut self, s: &str) -> fmt::Result { - self.push(s); - Ok(()) - } -} - -impl OsStr { - /// Coerces into an `OsStr` slice. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsStr; - /// - /// let os_str = OsStr::new("foo"); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn new + ?Sized>(s: &S) -> &OsStr { - s.as_ref() - } - - /// Converts a slice of bytes to an OS string slice without checking that the string contains - /// valid `OsStr`-encoded data. - /// - /// The byte encoding is an unspecified, platform-specific, self-synchronizing superset of UTF-8. - /// By being a self-synchronizing superset of UTF-8, this encoding is also a superset of 7-bit - /// ASCII. - /// - /// See the [module's toplevel documentation about conversions][conversions] for safe, - /// cross-platform [conversions] from/to native representations. - /// - /// # Safety - /// - /// As the encoding is unspecified, callers must pass in bytes that originated as a mixture of - /// validated UTF-8 and bytes from [`OsStr::as_encoded_bytes`] from within the same Rust version - /// built for the same target platform. For example, reconstructing an `OsStr` from bytes sent - /// over the network or stored in a file will likely violate these safety rules. - /// - /// Due to the encoding being self-synchronizing, the bytes from [`OsStr::as_encoded_bytes`] can be - /// split either immediately before or immediately after any valid non-empty UTF-8 substring. - /// - /// # Example - /// - /// ``` - /// use std::ffi::OsStr; - /// - /// let os_str = OsStr::new("Mary had a little lamb"); - /// let bytes = os_str.as_encoded_bytes(); - /// let words = bytes.split(|b| *b == b' '); - /// let words: Vec<&OsStr> = words.map(|word| { - /// // SAFETY: - /// // - Each `word` only contains content that originated from `OsStr::as_encoded_bytes` - /// // - Only split with ASCII whitespace which is a non-empty UTF-8 substring - /// unsafe { OsStr::from_encoded_bytes_unchecked(word) } - /// }).collect(); - /// ``` - /// - /// [conversions]: super#conversions - #[inline] - #[stable(feature = "os_str_bytes", since = "1.74.0")] - pub unsafe fn from_encoded_bytes_unchecked(bytes: &[u8]) -> &Self { - Self::from_inner(Slice::from_encoded_bytes_unchecked(bytes)) - } - - #[inline] - fn from_inner(inner: &Slice) -> &OsStr { - // SAFETY: OsStr is just a wrapper of Slice, - // therefore converting &Slice to &OsStr is safe. - unsafe { &*(inner as *const Slice as *const OsStr) } - } - - #[inline] - fn from_inner_mut(inner: &mut Slice) -> &mut OsStr { - // SAFETY: OsStr is just a wrapper of Slice, - // therefore converting &mut Slice to &mut OsStr is safe. - // Any method that mutates OsStr must be careful not to - // break platform-specific encoding, in particular Wtf8 on Windows. - unsafe { &mut *(inner as *mut Slice as *mut OsStr) } - } - - /// Yields a &[str] slice if the `OsStr` is valid Unicode. - /// - /// This conversion may entail doing a check for UTF-8 validity. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsStr; - /// - /// let os_str = OsStr::new("foo"); - /// assert_eq!(os_str.to_str(), Some("foo")); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub fn to_str(&self) -> Option<&str> { - self.inner.to_str().ok() - } - - /// Converts an `OsStr` to a [Cow]<[str]>. - /// - /// Any non-Unicode sequences are replaced with - /// [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD]. - /// - /// [U+FFFD]: crate::char::REPLACEMENT_CHARACTER - /// - /// # Examples - /// - /// Calling `to_string_lossy` on an `OsStr` with invalid unicode: - /// - /// ``` - /// // Note, due to differences in how Unix and Windows represent strings, - /// // we are forced to complicate this example, setting up example `OsStr`s - /// // with different source data and via different platform extensions. - /// // Understand that in reality you could end up with such example invalid - /// // sequences simply through collecting user command line arguments, for - /// // example. - /// - /// #[cfg(unix)] { - /// use std::ffi::OsStr; - /// use std::os::unix::ffi::OsStrExt; - /// - /// // Here, the values 0x66 and 0x6f correspond to 'f' and 'o' - /// // respectively. The value 0x80 is a lone continuation byte, invalid - /// // in a UTF-8 sequence. - /// let source = [0x66, 0x6f, 0x80, 0x6f]; - /// let os_str = OsStr::from_bytes(&source[..]); - /// - /// assert_eq!(os_str.to_string_lossy(), "fo�o"); - /// } - /// #[cfg(windows)] { - /// use std::ffi::OsString; - /// use std::os::windows::prelude::*; - /// - /// // Here the values 0x0066 and 0x006f correspond to 'f' and 'o' - /// // respectively. The value 0xD800 is a lone surrogate half, invalid - /// // in a UTF-16 sequence. - /// let source = [0x0066, 0x006f, 0xD800, 0x006f]; - /// let os_string = OsString::from_wide(&source[..]); - /// let os_str = os_string.as_os_str(); - /// - /// assert_eq!(os_str.to_string_lossy(), "fo�o"); - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub fn to_string_lossy(&self) -> Cow<'_, str> { - self.inner.to_string_lossy() - } - - /// Copies the slice into an owned [`OsString`]. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::{OsStr, OsString}; - /// - /// let os_str = OsStr::new("foo"); - /// let os_string = os_str.to_os_string(); - /// assert_eq!(os_string, OsString::from("foo")); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub fn to_os_string(&self) -> OsString { - OsString { inner: self.inner.to_owned() } - } - - /// Checks whether the `OsStr` is empty. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsStr; - /// - /// let os_str = OsStr::new(""); - /// assert!(os_str.is_empty()); - /// - /// let os_str = OsStr::new("foo"); - /// assert!(!os_str.is_empty()); - /// ``` - #[stable(feature = "osstring_simple_functions", since = "1.9.0")] - #[must_use] - #[inline] - pub fn is_empty(&self) -> bool { - self.inner.inner.is_empty() - } - - /// Returns the length of this `OsStr`. - /// - /// Note that this does **not** return the number of bytes in the string in - /// OS string form. - /// - /// The length returned is that of the underlying storage used by `OsStr`. - /// As discussed in the [`OsString`] introduction, [`OsString`] and `OsStr` - /// store strings in a form best suited for cheap inter-conversion between - /// native-platform and Rust string forms, which may differ significantly - /// from both of them, including in storage size and encoding. - /// - /// This number is simply useful for passing to other methods, like - /// [`OsString::with_capacity`] to avoid reallocations. - /// - /// See the main `OsString` documentation information about encoding and capacity units. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsStr; - /// - /// let os_str = OsStr::new(""); - /// assert_eq!(os_str.len(), 0); - /// - /// let os_str = OsStr::new("foo"); - /// assert_eq!(os_str.len(), 3); - /// ``` - #[stable(feature = "osstring_simple_functions", since = "1.9.0")] - #[must_use] - #[inline] - pub fn len(&self) -> usize { - self.inner.inner.len() - } - - /// Converts a [Box]<[OsStr]> into an [`OsString`] without copying or allocating. - #[stable(feature = "into_boxed_os_str", since = "1.20.0")] - #[must_use = "`self` will be dropped if the result is not used"] - pub fn into_os_string(self: Box) -> OsString { - let boxed = unsafe { Box::from_raw(Box::into_raw(self) as *mut Slice) }; - OsString { inner: Buf::from_box(boxed) } - } - - /// Converts an OS string slice to a byte slice. To convert the byte slice back into an OS - /// string slice, use the [`OsStr::from_encoded_bytes_unchecked`] function. - /// - /// The byte encoding is an unspecified, platform-specific, self-synchronizing superset of UTF-8. - /// By being a self-synchronizing superset of UTF-8, this encoding is also a superset of 7-bit - /// ASCII. - /// - /// Note: As the encoding is unspecified, any sub-slice of bytes that is not valid UTF-8 should - /// be treated as opaque and only comparable within the same Rust version built for the same - /// target platform. For example, sending the slice over the network or storing it in a file - /// will likely result in incompatible byte slices. See [`OsString`] for more encoding details - /// and [`std::ffi`] for platform-specific, specified conversions. - /// - /// [`std::ffi`]: crate::ffi - #[inline] - #[stable(feature = "os_str_bytes", since = "1.74.0")] - pub fn as_encoded_bytes(&self) -> &[u8] { - self.inner.as_encoded_bytes() - } - - /// Takes a substring based on a range that corresponds to the return value of - /// [`OsStr::as_encoded_bytes`]. - /// - /// The range's start and end must lie on valid `OsStr` boundaries. - /// A valid `OsStr` boundary is one of: - /// - The start of the string - /// - The end of the string - /// - Immediately before a valid non-empty UTF-8 substring - /// - Immediately after a valid non-empty UTF-8 substring - /// - /// # Panics - /// - /// Panics if `range` does not lie on valid `OsStr` boundaries or if it - /// exceeds the end of the string. - /// - /// # Example - /// - /// ``` - /// #![feature(os_str_slice)] - /// - /// use std::ffi::OsStr; - /// - /// let os_str = OsStr::new("foo=bar"); - /// let bytes = os_str.as_encoded_bytes(); - /// if let Some(index) = bytes.iter().position(|b| *b == b'=') { - /// let key = os_str.slice_encoded_bytes(..index); - /// let value = os_str.slice_encoded_bytes(index + 1..); - /// assert_eq!(key, "foo"); - /// assert_eq!(value, "bar"); - /// } - /// ``` - #[unstable(feature = "os_str_slice", issue = "118485")] - pub fn slice_encoded_bytes>(&self, range: R) -> &Self { - let encoded_bytes = self.as_encoded_bytes(); - let Range { start, end } = slice::range(range, ..encoded_bytes.len()); - - // `check_public_boundary` should panic if the index does not lie on an - // `OsStr` boundary as described above. It's possible to do this in an - // encoding-agnostic way, but details of the internal encoding might - // permit a more efficient implementation. - self.inner.check_public_boundary(start); - self.inner.check_public_boundary(end); - - // SAFETY: `slice::range` ensures that `start` and `end` are valid - let slice = unsafe { encoded_bytes.get_unchecked(start..end) }; - - // SAFETY: `slice` comes from `self` and we validated the boundaries - unsafe { Self::from_encoded_bytes_unchecked(slice) } - } - - /// Converts this string to its ASCII lower case equivalent in-place. - /// - /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', - /// but non-ASCII letters are unchanged. - /// - /// To return a new lowercased value without modifying the existing one, use - /// [`OsStr::to_ascii_lowercase`]. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsString; - /// - /// let mut s = OsString::from("GRÜßE, JÜRGEN ❤"); - /// - /// s.make_ascii_lowercase(); - /// - /// assert_eq!("grÜße, jÜrgen ❤", s); - /// ``` - #[stable(feature = "osstring_ascii", since = "1.53.0")] - #[inline] - pub fn make_ascii_lowercase(&mut self) { - self.inner.make_ascii_lowercase() - } - - /// Converts this string to its ASCII upper case equivalent in-place. - /// - /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', - /// but non-ASCII letters are unchanged. - /// - /// To return a new uppercased value without modifying the existing one, use - /// [`OsStr::to_ascii_uppercase`]. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsString; - /// - /// let mut s = OsString::from("Grüße, Jürgen ❤"); - /// - /// s.make_ascii_uppercase(); - /// - /// assert_eq!("GRüßE, JüRGEN ❤", s); - /// ``` - #[stable(feature = "osstring_ascii", since = "1.53.0")] - #[inline] - pub fn make_ascii_uppercase(&mut self) { - self.inner.make_ascii_uppercase() - } - - /// Returns a copy of this string where each character is mapped to its - /// ASCII lower case equivalent. - /// - /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', - /// but non-ASCII letters are unchanged. - /// - /// To lowercase the value in-place, use [`OsStr::make_ascii_lowercase`]. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsString; - /// let s = OsString::from("Grüße, Jürgen ❤"); - /// - /// assert_eq!("grüße, jürgen ❤", s.to_ascii_lowercase()); - /// ``` - #[must_use = "to lowercase the value in-place, use `make_ascii_lowercase`"] - #[stable(feature = "osstring_ascii", since = "1.53.0")] - pub fn to_ascii_lowercase(&self) -> OsString { - OsString::from_inner(self.inner.to_ascii_lowercase()) - } - - /// Returns a copy of this string where each character is mapped to its - /// ASCII upper case equivalent. - /// - /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', - /// but non-ASCII letters are unchanged. - /// - /// To uppercase the value in-place, use [`OsStr::make_ascii_uppercase`]. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsString; - /// let s = OsString::from("Grüße, Jürgen ❤"); - /// - /// assert_eq!("GRüßE, JüRGEN ❤", s.to_ascii_uppercase()); - /// ``` - #[must_use = "to uppercase the value in-place, use `make_ascii_uppercase`"] - #[stable(feature = "osstring_ascii", since = "1.53.0")] - pub fn to_ascii_uppercase(&self) -> OsString { - OsString::from_inner(self.inner.to_ascii_uppercase()) - } - - /// Checks if all characters in this string are within the ASCII range. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsString; - /// - /// let ascii = OsString::from("hello!\n"); - /// let non_ascii = OsString::from("Grüße, Jürgen ❤"); - /// - /// assert!(ascii.is_ascii()); - /// assert!(!non_ascii.is_ascii()); - /// ``` - #[stable(feature = "osstring_ascii", since = "1.53.0")] - #[must_use] - #[inline] - pub fn is_ascii(&self) -> bool { - self.inner.is_ascii() - } - - /// Checks that two strings are an ASCII case-insensitive match. - /// - /// Same as `to_ascii_lowercase(a) == to_ascii_lowercase(b)`, - /// but without allocating and copying temporaries. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsString; - /// - /// assert!(OsString::from("Ferris").eq_ignore_ascii_case("FERRIS")); - /// assert!(OsString::from("Ferrös").eq_ignore_ascii_case("FERRöS")); - /// assert!(!OsString::from("Ferrös").eq_ignore_ascii_case("FERRÖS")); - /// ``` - #[stable(feature = "osstring_ascii", since = "1.53.0")] - pub fn eq_ignore_ascii_case>(&self, other: S) -> bool { - self.inner.eq_ignore_ascii_case(&other.as_ref().inner) - } - - /// Returns an object that implements [`Display`] for safely printing an - /// [`OsStr`] that may contain non-Unicode data. This may perform lossy - /// conversion, depending on the platform. If you would like an - /// implementation which escapes the [`OsStr`] please use [`Debug`] - /// instead. - /// - /// [`Display`]: fmt::Display - /// [`Debug`]: fmt::Debug - /// - /// # Examples - /// - /// ``` - /// #![feature(os_str_display)] - /// use std::ffi::OsStr; - /// - /// let s = OsStr::new("Hello, world!"); - /// println!("{}", s.display()); - /// ``` - #[unstable(feature = "os_str_display", issue = "120048")] - #[must_use = "this does not display the `OsStr`; \ - it returns an object that can be displayed"] - #[inline] - pub fn display(&self) -> Display<'_> { - Display { os_str: self } - } -} - -#[stable(feature = "box_from_os_str", since = "1.17.0")] -impl From<&OsStr> for Box { - /// Copies the string into a newly allocated [Box]<[OsStr]>. - #[inline] - fn from(s: &OsStr) -> Box { - let rw = Box::into_raw(s.inner.into_box()) as *mut OsStr; - unsafe { Box::from_raw(rw) } - } -} - -#[stable(feature = "box_from_cow", since = "1.45.0")] -impl From> for Box { - /// Converts a `Cow<'a, OsStr>` into a [Box]<[OsStr]>, - /// by copying the contents if they are borrowed. - #[inline] - fn from(cow: Cow<'_, OsStr>) -> Box { - match cow { - Cow::Borrowed(s) => Box::from(s), - Cow::Owned(s) => Box::from(s), - } - } -} - -#[stable(feature = "os_string_from_box", since = "1.18.0")] -impl From> for OsString { - /// Converts a [Box]<[OsStr]> into an [`OsString`] without copying or - /// allocating. - #[inline] - fn from(boxed: Box) -> OsString { - boxed.into_os_string() - } -} - -#[stable(feature = "box_from_os_string", since = "1.20.0")] -impl From for Box { - /// Converts an [`OsString`] into a [Box]<[OsStr]> without copying or allocating. - #[inline] - fn from(s: OsString) -> Box { - s.into_boxed_os_str() - } -} - -#[stable(feature = "more_box_slice_clone", since = "1.29.0")] -impl Clone for Box { - #[inline] - fn clone(&self) -> Self { - self.to_os_string().into_boxed_os_str() - } -} - -#[stable(feature = "shared_from_slice2", since = "1.24.0")] -impl From for Arc { - /// Converts an [`OsString`] into an [Arc]<[OsStr]> by moving the [`OsString`] - /// data into a new [`Arc`] buffer. - #[inline] - fn from(s: OsString) -> Arc { - let arc = s.inner.into_arc(); - unsafe { Arc::from_raw(Arc::into_raw(arc) as *const OsStr) } - } -} - -#[stable(feature = "shared_from_slice2", since = "1.24.0")] -impl From<&OsStr> for Arc { - /// Copies the string into a newly allocated [Arc]<[OsStr]>. - #[inline] - fn from(s: &OsStr) -> Arc { - let arc = s.inner.into_arc(); - unsafe { Arc::from_raw(Arc::into_raw(arc) as *const OsStr) } - } -} - -#[stable(feature = "shared_from_slice2", since = "1.24.0")] -impl From for Rc { - /// Converts an [`OsString`] into an [Rc]<[OsStr]> by moving the [`OsString`] - /// data into a new [`Rc`] buffer. - #[inline] - fn from(s: OsString) -> Rc { - let rc = s.inner.into_rc(); - unsafe { Rc::from_raw(Rc::into_raw(rc) as *const OsStr) } - } -} - -#[stable(feature = "shared_from_slice2", since = "1.24.0")] -impl From<&OsStr> for Rc { - /// Copies the string into a newly allocated [Rc]<[OsStr]>. - #[inline] - fn from(s: &OsStr) -> Rc { - let rc = s.inner.into_rc(); - unsafe { Rc::from_raw(Rc::into_raw(rc) as *const OsStr) } - } -} - -#[stable(feature = "cow_from_osstr", since = "1.28.0")] -impl<'a> From for Cow<'a, OsStr> { - /// Moves the string into a [`Cow::Owned`]. - #[inline] - fn from(s: OsString) -> Cow<'a, OsStr> { - Cow::Owned(s) - } -} - -#[stable(feature = "cow_from_osstr", since = "1.28.0")] -impl<'a> From<&'a OsStr> for Cow<'a, OsStr> { - /// Converts the string reference into a [`Cow::Borrowed`]. - #[inline] - fn from(s: &'a OsStr) -> Cow<'a, OsStr> { - Cow::Borrowed(s) - } -} - -#[stable(feature = "cow_from_osstr", since = "1.28.0")] -impl<'a> From<&'a OsString> for Cow<'a, OsStr> { - /// Converts the string reference into a [`Cow::Borrowed`]. - #[inline] - fn from(s: &'a OsString) -> Cow<'a, OsStr> { - Cow::Borrowed(s.as_os_str()) - } -} - -#[stable(feature = "osstring_from_cow_osstr", since = "1.28.0")] -impl<'a> From> for OsString { - /// Converts a `Cow<'a, OsStr>` into an [`OsString`], - /// by copying the contents if they are borrowed. - #[inline] - fn from(s: Cow<'a, OsStr>) -> Self { - s.into_owned() - } -} - -#[stable(feature = "str_tryfrom_osstr_impl", since = "1.72.0")] -impl<'a> TryFrom<&'a OsStr> for &'a str { - type Error = crate::str::Utf8Error; - - /// Tries to convert an `&OsStr` to a `&str`. - /// - /// ``` - /// use std::ffi::OsStr; - /// - /// let os_str = OsStr::new("foo"); - /// let as_str = <&str>::try_from(os_str).unwrap(); - /// assert_eq!(as_str, "foo"); - /// ``` - fn try_from(value: &'a OsStr) -> Result { - value.inner.to_str() - } -} - -#[stable(feature = "box_default_extra", since = "1.17.0")] -impl Default for Box { - #[inline] - fn default() -> Box { - let rw = Box::into_raw(Slice::empty_box()) as *mut OsStr; - unsafe { Box::from_raw(rw) } - } -} - -#[stable(feature = "osstring_default", since = "1.9.0")] -impl Default for &OsStr { - /// Creates an empty `OsStr`. - #[inline] - fn default() -> Self { - OsStr::new("") - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for OsStr { - #[inline] - fn eq(&self, other: &OsStr) -> bool { - self.as_encoded_bytes().eq(other.as_encoded_bytes()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for OsStr { - #[inline] - fn eq(&self, other: &str) -> bool { - *self == *OsStr::new(other) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for str { - #[inline] - fn eq(&self, other: &OsStr) -> bool { - *other == *OsStr::new(self) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Eq for OsStr {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialOrd for OsStr { - #[inline] - fn partial_cmp(&self, other: &OsStr) -> Option { - self.as_encoded_bytes().partial_cmp(other.as_encoded_bytes()) - } - #[inline] - fn lt(&self, other: &OsStr) -> bool { - self.as_encoded_bytes().lt(other.as_encoded_bytes()) - } - #[inline] - fn le(&self, other: &OsStr) -> bool { - self.as_encoded_bytes().le(other.as_encoded_bytes()) - } - #[inline] - fn gt(&self, other: &OsStr) -> bool { - self.as_encoded_bytes().gt(other.as_encoded_bytes()) - } - #[inline] - fn ge(&self, other: &OsStr) -> bool { - self.as_encoded_bytes().ge(other.as_encoded_bytes()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialOrd for OsStr { - #[inline] - fn partial_cmp(&self, other: &str) -> Option { - self.partial_cmp(OsStr::new(other)) - } -} - -// FIXME (#19470): cannot provide PartialOrd for str until we -// have more flexible coherence rules. - -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for OsStr { - #[inline] - fn cmp(&self, other: &OsStr) -> cmp::Ordering { - self.as_encoded_bytes().cmp(other.as_encoded_bytes()) - } -} - -macro_rules! impl_cmp { - ($lhs:ty, $rhs: ty) => { - #[stable(feature = "cmp_os_str", since = "1.8.0")] - impl<'a, 'b> PartialEq<$rhs> for $lhs { - #[inline] - fn eq(&self, other: &$rhs) -> bool { - ::eq(self, other) - } - } - - #[stable(feature = "cmp_os_str", since = "1.8.0")] - impl<'a, 'b> PartialEq<$lhs> for $rhs { - #[inline] - fn eq(&self, other: &$lhs) -> bool { - ::eq(self, other) - } - } - - #[stable(feature = "cmp_os_str", since = "1.8.0")] - impl<'a, 'b> PartialOrd<$rhs> for $lhs { - #[inline] - fn partial_cmp(&self, other: &$rhs) -> Option { - ::partial_cmp(self, other) - } - } - - #[stable(feature = "cmp_os_str", since = "1.8.0")] - impl<'a, 'b> PartialOrd<$lhs> for $rhs { - #[inline] - fn partial_cmp(&self, other: &$lhs) -> Option { - ::partial_cmp(self, other) - } - } - }; -} - -impl_cmp!(OsString, OsStr); -impl_cmp!(OsString, &'a OsStr); -impl_cmp!(Cow<'a, OsStr>, OsStr); -impl_cmp!(Cow<'a, OsStr>, &'b OsStr); -impl_cmp!(Cow<'a, OsStr>, OsString); - -#[stable(feature = "rust1", since = "1.0.0")] -impl Hash for OsStr { - #[inline] - fn hash(&self, state: &mut H) { - self.as_encoded_bytes().hash(state) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for OsStr { - fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&self.inner, formatter) - } -} - -/// Helper struct for safely printing an [`OsStr`] with [`format!`] and `{}`. -/// -/// An [`OsStr`] might contain non-Unicode data. This `struct` implements the -/// [`Display`] trait in a way that mitigates that. It is created by the -/// [`display`](OsStr::display) method on [`OsStr`]. This may perform lossy -/// conversion, depending on the platform. If you would like an implementation -/// which escapes the [`OsStr`] please use [`Debug`] instead. -/// -/// # Examples -/// -/// ``` -/// #![feature(os_str_display)] -/// use std::ffi::OsStr; -/// -/// let s = OsStr::new("Hello, world!"); -/// println!("{}", s.display()); -/// ``` -/// -/// [`Display`]: fmt::Display -/// [`format!`]: crate::format -#[unstable(feature = "os_str_display", issue = "120048")] -pub struct Display<'a> { - os_str: &'a OsStr, -} - -#[unstable(feature = "os_str_display", issue = "120048")] -impl fmt::Debug for Display<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&self.os_str, f) - } -} - -#[unstable(feature = "os_str_display", issue = "120048")] -impl fmt::Display for Display<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt(&self.os_str.inner, f) - } -} - -#[unstable(feature = "slice_concat_ext", issue = "27747")] -impl> alloc::slice::Join<&OsStr> for [S] { - type Output = OsString; - - fn join(slice: &Self, sep: &OsStr) -> OsString { - let Some((first, suffix)) = slice.split_first() else { - return OsString::new(); - }; - let first_owned = first.borrow().to_owned(); - suffix.iter().fold(first_owned, |mut a, b| { - a.push(sep); - a.push(b.borrow()); - a - }) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Borrow for OsString { - #[inline] - fn borrow(&self) -> &OsStr { - &self[..] - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ToOwned for OsStr { - type Owned = OsString; - #[inline] - fn to_owned(&self) -> OsString { - self.to_os_string() - } - #[inline] - fn clone_into(&self, target: &mut OsString) { - self.inner.clone_into(&mut target.inner) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef for OsStr { - #[inline] - fn as_ref(&self) -> &OsStr { - self - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef for OsString { - #[inline] - fn as_ref(&self) -> &OsStr { - self - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef for str { - #[inline] - fn as_ref(&self) -> &OsStr { - OsStr::from_inner(Slice::from_str(self)) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef for String { - #[inline] - fn as_ref(&self) -> &OsStr { - (&**self).as_ref() - } -} - -impl FromInner for OsString { - #[inline] - fn from_inner(buf: Buf) -> OsString { - OsString { inner: buf } - } -} - -impl IntoInner for OsString { - #[inline] - fn into_inner(self) -> Buf { - self.inner - } -} - -impl AsInner for OsStr { - #[inline] - fn as_inner(&self) -> &Slice { - &self.inner - } -} - -#[stable(feature = "osstring_from_str", since = "1.45.0")] -impl FromStr for OsString { - type Err = core::convert::Infallible; - - #[inline] - fn from_str(s: &str) -> Result { - Ok(OsString::from(s)) - } -} - -#[stable(feature = "osstring_extend", since = "1.52.0")] -impl Extend for OsString { - #[inline] - fn extend>(&mut self, iter: T) { - for s in iter { - self.push(&s); - } - } -} - -#[stable(feature = "osstring_extend", since = "1.52.0")] -impl<'a> Extend<&'a OsStr> for OsString { - #[inline] - fn extend>(&mut self, iter: T) { - for s in iter { - self.push(s); - } - } -} - -#[stable(feature = "osstring_extend", since = "1.52.0")] -impl<'a> Extend> for OsString { - #[inline] - fn extend>>(&mut self, iter: T) { - for s in iter { - self.push(&s); - } - } -} - -#[stable(feature = "osstring_extend", since = "1.52.0")] -impl FromIterator for OsString { - #[inline] - fn from_iter>(iter: I) -> Self { - let mut iterator = iter.into_iter(); - - // Because we're iterating over `OsString`s, we can avoid at least - // one allocation by getting the first string from the iterator - // and appending to it all the subsequent strings. - match iterator.next() { - None => OsString::new(), - Some(mut buf) => { - buf.extend(iterator); - buf - } - } - } -} - -#[stable(feature = "osstring_extend", since = "1.52.0")] -impl<'a> FromIterator<&'a OsStr> for OsString { - #[inline] - fn from_iter>(iter: I) -> Self { - let mut buf = Self::new(); - for s in iter { - buf.push(s); - } - buf - } -} - -#[stable(feature = "osstring_extend", since = "1.52.0")] -impl<'a> FromIterator> for OsString { - #[inline] - fn from_iter>>(iter: I) -> Self { - let mut iterator = iter.into_iter(); - - // Because we're iterating over `OsString`s, we can avoid at least - // one allocation by getting the first owned string from the iterator - // and appending to it all the subsequent strings. - match iterator.next() { - None => OsString::new(), - Some(Cow::Owned(mut buf)) => { - buf.extend(iterator); - buf - } - Some(Cow::Borrowed(buf)) => { - let mut buf = OsString::from(buf); - buf.extend(iterator); - buf - } - } - } -} diff --git a/library/std/src/ffi/os_str/tests.rs b/library/std/src/ffi/os_str/tests.rs deleted file mode 100644 index b020e05eaab20..0000000000000 --- a/library/std/src/ffi/os_str/tests.rs +++ /dev/null @@ -1,279 +0,0 @@ -use super::*; - -#[test] -fn test_os_string_with_capacity() { - let os_string = OsString::with_capacity(0); - assert_eq!(0, os_string.inner.into_inner().capacity()); - - let os_string = OsString::with_capacity(10); - assert_eq!(10, os_string.inner.into_inner().capacity()); - - let mut os_string = OsString::with_capacity(0); - os_string.push("abc"); - assert!(os_string.inner.into_inner().capacity() >= 3); -} - -#[test] -fn test_os_string_clear() { - let mut os_string = OsString::from("abc"); - assert_eq!(3, os_string.inner.as_inner().len()); - - os_string.clear(); - assert_eq!(&os_string, ""); - assert_eq!(0, os_string.inner.as_inner().len()); -} - -#[test] -fn test_os_string_capacity() { - let os_string = OsString::with_capacity(0); - assert_eq!(0, os_string.capacity()); - - let os_string = OsString::with_capacity(10); - assert_eq!(10, os_string.capacity()); - - let mut os_string = OsString::with_capacity(0); - os_string.push("abc"); - assert!(os_string.capacity() >= 3); -} - -#[test] -fn test_os_string_reserve() { - let mut os_string = OsString::new(); - assert_eq!(os_string.capacity(), 0); - - os_string.reserve(2); - assert!(os_string.capacity() >= 2); - - for _ in 0..16 { - os_string.push("a"); - } - - assert!(os_string.capacity() >= 16); - os_string.reserve(16); - assert!(os_string.capacity() >= 32); - - os_string.push("a"); - - os_string.reserve(16); - assert!(os_string.capacity() >= 33) -} - -#[test] -fn test_os_string_reserve_exact() { - let mut os_string = OsString::new(); - assert_eq!(os_string.capacity(), 0); - - os_string.reserve_exact(2); - assert!(os_string.capacity() >= 2); - - for _ in 0..16 { - os_string.push("a"); - } - - assert!(os_string.capacity() >= 16); - os_string.reserve_exact(16); - assert!(os_string.capacity() >= 32); - - os_string.push("a"); - - os_string.reserve_exact(16); - assert!(os_string.capacity() >= 33) -} - -#[test] -fn test_os_string_join() { - let strings = [OsStr::new("hello"), OsStr::new("dear"), OsStr::new("world")]; - assert_eq!("hello", strings[..1].join(OsStr::new(" "))); - assert_eq!("hello dear world", strings.join(OsStr::new(" "))); - assert_eq!("hellodearworld", strings.join(OsStr::new(""))); - assert_eq!("hello.\n dear.\n world", strings.join(OsStr::new(".\n "))); - - assert_eq!("dear world", strings[1..].join(&OsString::from(" "))); - - let strings_abc = [OsString::from("a"), OsString::from("b"), OsString::from("c")]; - assert_eq!("a b c", strings_abc.join(OsStr::new(" "))); -} - -#[test] -fn test_os_string_default() { - let os_string: OsString = Default::default(); - assert_eq!("", &os_string); -} - -#[test] -fn test_os_str_is_empty() { - let mut os_string = OsString::new(); - assert!(os_string.is_empty()); - - os_string.push("abc"); - assert!(!os_string.is_empty()); - - os_string.clear(); - assert!(os_string.is_empty()); -} - -#[test] -fn test_os_str_len() { - let mut os_string = OsString::new(); - assert_eq!(0, os_string.len()); - - os_string.push("abc"); - assert_eq!(3, os_string.len()); - - os_string.clear(); - assert_eq!(0, os_string.len()); -} - -#[test] -fn test_os_str_default() { - let os_str: &OsStr = Default::default(); - assert_eq!("", os_str); -} - -#[test] -fn into_boxed() { - let orig = "Hello, world!"; - let os_str = OsStr::new(orig); - let boxed: Box = Box::from(os_str); - let os_string = os_str.to_owned().into_boxed_os_str().into_os_string(); - assert_eq!(os_str, &*boxed); - assert_eq!(&*boxed, &*os_string); - assert_eq!(&*os_string, os_str); -} - -#[test] -fn boxed_default() { - let boxed = >::default(); - assert!(boxed.is_empty()); -} - -#[test] -fn test_os_str_clone_into() { - let mut os_string = OsString::with_capacity(123); - os_string.push("hello"); - let os_str = OsStr::new("bonjour"); - os_str.clone_into(&mut os_string); - assert_eq!(os_str, os_string); - assert!(os_string.capacity() >= 123); -} - -#[test] -fn into_rc() { - let orig = "Hello, world!"; - let os_str = OsStr::new(orig); - let rc: Rc = Rc::from(os_str); - let arc: Arc = Arc::from(os_str); - - assert_eq!(&*rc, os_str); - assert_eq!(&*arc, os_str); - - let rc2: Rc = Rc::from(os_str.to_owned()); - let arc2: Arc = Arc::from(os_str.to_owned()); - - assert_eq!(&*rc2, os_str); - assert_eq!(&*arc2, os_str); -} - -#[test] -fn slice_encoded_bytes() { - let os_str = OsStr::new("123θგ🦀"); - // ASCII - let digits = os_str.slice_encoded_bytes(..3); - assert_eq!(digits, "123"); - let three = os_str.slice_encoded_bytes(2..3); - assert_eq!(three, "3"); - // 2-byte UTF-8 - let theta = os_str.slice_encoded_bytes(3..5); - assert_eq!(theta, "θ"); - // 3-byte UTF-8 - let gani = os_str.slice_encoded_bytes(5..8); - assert_eq!(gani, "გ"); - // 4-byte UTF-8 - let crab = os_str.slice_encoded_bytes(8..); - assert_eq!(crab, "🦀"); -} - -#[test] -#[should_panic] -fn slice_out_of_bounds() { - let crab = OsStr::new("🦀"); - let _ = crab.slice_encoded_bytes(..5); -} - -#[test] -#[should_panic] -fn slice_mid_char() { - let crab = OsStr::new("🦀"); - let _ = crab.slice_encoded_bytes(..2); -} - -#[cfg(unix)] -#[test] -#[should_panic(expected = "byte index 1 is not an OsStr boundary")] -fn slice_invalid_data() { - use crate::os::unix::ffi::OsStrExt; - - let os_string = OsStr::from_bytes(b"\xFF\xFF"); - let _ = os_string.slice_encoded_bytes(1..); -} - -#[cfg(unix)] -#[test] -#[should_panic(expected = "byte index 1 is not an OsStr boundary")] -fn slice_partial_utf8() { - use crate::os::unix::ffi::{OsStrExt, OsStringExt}; - - let part_crab = OsStr::from_bytes(&"🦀".as_bytes()[..3]); - let mut os_string = OsString::from_vec(vec![0xFF]); - os_string.push(part_crab); - let _ = os_string.slice_encoded_bytes(1..); -} - -#[cfg(unix)] -#[test] -fn slice_invalid_edge() { - use crate::os::unix::ffi::{OsStrExt, OsStringExt}; - - let os_string = OsStr::from_bytes(b"a\xFFa"); - assert_eq!(os_string.slice_encoded_bytes(..1), "a"); - assert_eq!(os_string.slice_encoded_bytes(1..), OsStr::from_bytes(b"\xFFa")); - assert_eq!(os_string.slice_encoded_bytes(..2), OsStr::from_bytes(b"a\xFF")); - assert_eq!(os_string.slice_encoded_bytes(2..), "a"); - - let os_string = OsStr::from_bytes(&"abc🦀".as_bytes()[..6]); - assert_eq!(os_string.slice_encoded_bytes(..3), "abc"); - assert_eq!(os_string.slice_encoded_bytes(3..), OsStr::from_bytes(b"\xF0\x9F\xA6")); - - let mut os_string = OsString::from_vec(vec![0xFF]); - os_string.push("🦀"); - assert_eq!(os_string.slice_encoded_bytes(..1), OsStr::from_bytes(b"\xFF")); - assert_eq!(os_string.slice_encoded_bytes(1..), "🦀"); -} - -#[cfg(windows)] -#[test] -#[should_panic(expected = "byte index 3 lies between surrogate codepoints")] -fn slice_between_surrogates() { - use crate::os::windows::ffi::OsStringExt; - - let os_string = OsString::from_wide(&[0xD800, 0xD800]); - assert_eq!(os_string.as_encoded_bytes(), &[0xED, 0xA0, 0x80, 0xED, 0xA0, 0x80]); - let _ = os_string.slice_encoded_bytes(..3); -} - -#[cfg(windows)] -#[test] -fn slice_surrogate_edge() { - use crate::os::windows::ffi::OsStringExt; - - let surrogate = OsString::from_wide(&[0xD800]); - let mut pre_crab = surrogate.clone(); - pre_crab.push("🦀"); - assert_eq!(pre_crab.slice_encoded_bytes(..3), surrogate); - assert_eq!(pre_crab.slice_encoded_bytes(3..), "🦀"); - - let mut post_crab = OsString::from("🦀"); - post_crab.push(&surrogate); - assert_eq!(post_crab.slice_encoded_bytes(..4), "🦀"); - assert_eq!(post_crab.slice_encoded_bytes(4..), surrogate); -} diff --git a/library/std/src/fs.rs b/library/std/src/fs.rs deleted file mode 100644 index 77e94365b08ec..0000000000000 --- a/library/std/src/fs.rs +++ /dev/null @@ -1,2680 +0,0 @@ -//! Filesystem manipulation operations. -//! -//! This module contains basic methods to manipulate the contents of the local -//! filesystem. All methods in this module represent cross-platform filesystem -//! operations. Extra platform-specific functionality can be found in the -//! extension traits of `std::os::$platform`. - -#![stable(feature = "rust1", since = "1.0.0")] -#![deny(unsafe_op_in_unsafe_fn)] - -#[cfg(all(test, not(any(target_os = "emscripten", target_env = "sgx", target_os = "xous"))))] -mod tests; - -use crate::ffi::OsString; -use crate::fmt; -use crate::io::{self, BorrowedCursor, IoSlice, IoSliceMut, Read, Seek, SeekFrom, Write}; -use crate::path::{Path, PathBuf}; -use crate::sealed::Sealed; -use crate::sync::Arc; -use crate::sys::fs as fs_imp; -use crate::sys_common::{AsInner, AsInnerMut, FromInner, IntoInner}; -use crate::time::SystemTime; - -/// An object providing access to an open file on the filesystem. -/// -/// An instance of a `File` can be read and/or written depending on what options -/// it was opened with. Files also implement [`Seek`] to alter the logical cursor -/// that the file contains internally. -/// -/// Files are automatically closed when they go out of scope. Errors detected -/// on closing are ignored by the implementation of `Drop`. Use the method -/// [`sync_all`] if these errors must be manually handled. -/// -/// `File` does not buffer reads and writes. For efficiency, consider wrapping the -/// file in a [`BufReader`] or [`BufWriter`] when performing many small [`read`] -/// or [`write`] calls, unless unbuffered reads and writes are required. -/// -/// # Examples -/// -/// Creates a new file and write bytes to it (you can also use [`write`]): -/// -/// ```no_run -/// use std::fs::File; -/// use std::io::prelude::*; -/// -/// fn main() -> std::io::Result<()> { -/// let mut file = File::create("foo.txt")?; -/// file.write_all(b"Hello, world!")?; -/// Ok(()) -/// } -/// ``` -/// -/// Read the contents of a file into a [`String`] (you can also use [`read`]): -/// -/// ```no_run -/// use std::fs::File; -/// use std::io::prelude::*; -/// -/// fn main() -> std::io::Result<()> { -/// let mut file = File::open("foo.txt")?; -/// let mut contents = String::new(); -/// file.read_to_string(&mut contents)?; -/// assert_eq!(contents, "Hello, world!"); -/// Ok(()) -/// } -/// ``` -/// -/// Using a buffered [`Read`]er: -/// -/// ```no_run -/// use std::fs::File; -/// use std::io::BufReader; -/// use std::io::prelude::*; -/// -/// fn main() -> std::io::Result<()> { -/// let file = File::open("foo.txt")?; -/// let mut buf_reader = BufReader::new(file); -/// let mut contents = String::new(); -/// buf_reader.read_to_string(&mut contents)?; -/// assert_eq!(contents, "Hello, world!"); -/// Ok(()) -/// } -/// ``` -/// -/// Note that, although read and write methods require a `&mut File`, because -/// of the interfaces for [`Read`] and [`Write`], the holder of a `&File` can -/// still modify the file, either through methods that take `&File` or by -/// retrieving the underlying OS object and modifying the file that way. -/// Additionally, many operating systems allow concurrent modification of files -/// by different processes. Avoid assuming that holding a `&File` means that the -/// file will not change. -/// -/// # Platform-specific behavior -/// -/// On Windows, the implementation of [`Read`] and [`Write`] traits for `File` -/// perform synchronous I/O operations. Therefore the underlying file must not -/// have been opened for asynchronous I/O (e.g. by using `FILE_FLAG_OVERLAPPED`). -/// -/// [`BufReader`]: io::BufReader -/// [`BufWriter`]: io::BufWriter -/// [`sync_all`]: File::sync_all -/// [`write`]: File::write -/// [`read`]: File::read -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "File")] -pub struct File { - inner: fs_imp::File, -} - -/// Metadata information about a file. -/// -/// This structure is returned from the [`metadata`] or -/// [`symlink_metadata`] function or method and represents known -/// metadata about a file such as its permissions, size, modification -/// times, etc. -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Clone)] -pub struct Metadata(fs_imp::FileAttr); - -/// Iterator over the entries in a directory. -/// -/// This iterator is returned from the [`read_dir`] function of this module and -/// will yield instances of [io::Result]<[DirEntry]>. Through a [`DirEntry`] -/// information like the entry's path and possibly other metadata can be -/// learned. -/// -/// The order in which this iterator returns entries is platform and filesystem -/// dependent. -/// -/// # Errors -/// -/// This [`io::Result`] will be an [`Err`] if there's some sort of intermittent -/// IO error during iteration. -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Debug)] -pub struct ReadDir(fs_imp::ReadDir); - -/// Entries returned by the [`ReadDir`] iterator. -/// -/// An instance of `DirEntry` represents an entry inside of a directory on the -/// filesystem. Each entry can be inspected via methods to learn about the full -/// path or possibly other metadata through per-platform extension traits. -/// -/// # Platform-specific behavior -/// -/// On Unix, the `DirEntry` struct contains an internal reference to the open -/// directory. Holding `DirEntry` objects will consume a file handle even -/// after the `ReadDir` iterator is dropped. -/// -/// Note that this [may change in the future][changes]. -/// -/// [changes]: io#platform-specific-behavior -#[stable(feature = "rust1", since = "1.0.0")] -pub struct DirEntry(fs_imp::DirEntry); - -/// Options and flags which can be used to configure how a file is opened. -/// -/// This builder exposes the ability to configure how a [`File`] is opened and -/// what operations are permitted on the open file. The [`File::open`] and -/// [`File::create`] methods are aliases for commonly used options using this -/// builder. -/// -/// Generally speaking, when using `OpenOptions`, you'll first call -/// [`OpenOptions::new`], then chain calls to methods to set each option, then -/// call [`OpenOptions::open`], passing the path of the file you're trying to -/// open. This will give you a [`io::Result`] with a [`File`] inside that you -/// can further operate on. -/// -/// # Examples -/// -/// Opening a file to read: -/// -/// ```no_run -/// use std::fs::OpenOptions; -/// -/// let file = OpenOptions::new().read(true).open("foo.txt"); -/// ``` -/// -/// Opening a file for both reading and writing, as well as creating it if it -/// doesn't exist: -/// -/// ```no_run -/// use std::fs::OpenOptions; -/// -/// let file = OpenOptions::new() -/// .read(true) -/// .write(true) -/// .create(true) -/// .open("foo.txt"); -/// ``` -#[derive(Clone, Debug)] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "FsOpenOptions")] -pub struct OpenOptions(fs_imp::OpenOptions); - -/// Representation of the various timestamps on a file. -#[derive(Copy, Clone, Debug, Default)] -#[stable(feature = "file_set_times", since = "1.75.0")] -pub struct FileTimes(fs_imp::FileTimes); - -/// Representation of the various permissions on a file. -/// -/// This module only currently provides one bit of information, -/// [`Permissions::readonly`], which is exposed on all currently supported -/// platforms. Unix-specific functionality, such as mode bits, is available -/// through the [`PermissionsExt`] trait. -/// -/// [`PermissionsExt`]: crate::os::unix::fs::PermissionsExt -#[derive(Clone, PartialEq, Eq, Debug)] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "FsPermissions")] -pub struct Permissions(fs_imp::FilePermissions); - -/// A structure representing a type of file with accessors for each file type. -/// It is returned by [`Metadata::file_type`] method. -#[stable(feature = "file_type", since = "1.1.0")] -#[derive(Copy, Clone, PartialEq, Eq, Hash)] -#[cfg_attr(not(test), rustc_diagnostic_item = "FileType")] -pub struct FileType(fs_imp::FileType); - -/// A builder used to create directories in various manners. -/// -/// This builder also supports platform-specific options. -#[stable(feature = "dir_builder", since = "1.6.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "DirBuilder")] -#[derive(Debug)] -pub struct DirBuilder { - inner: fs_imp::DirBuilder, - recursive: bool, -} - -/// Read the entire contents of a file into a bytes vector. -/// -/// This is a convenience function for using [`File::open`] and [`read_to_end`] -/// with fewer imports and without an intermediate variable. -/// -/// [`read_to_end`]: Read::read_to_end -/// -/// # Errors -/// -/// This function will return an error if `path` does not already exist. -/// Other errors may also be returned according to [`OpenOptions::open`]. -/// -/// While reading from the file, this function handles [`io::ErrorKind::Interrupted`] -/// with automatic retries. See [io::Read] documentation for details. -/// -/// # Examples -/// -/// ```no_run -/// use std::fs; -/// -/// fn main() -> Result<(), Box> { -/// let data: Vec = fs::read("image.jpg")?; -/// assert_eq!(data[0..3], [0xFF, 0xD8, 0xFF]); -/// Ok(()) -/// } -/// ``` -#[stable(feature = "fs_read_write_bytes", since = "1.26.0")] -pub fn read>(path: P) -> io::Result> { - fn inner(path: &Path) -> io::Result> { - let mut file = File::open(path)?; - let size = file.metadata().map(|m| m.len() as usize).ok(); - let mut bytes = Vec::new(); - bytes.try_reserve_exact(size.unwrap_or(0))?; - io::default_read_to_end(&mut file, &mut bytes, size)?; - Ok(bytes) - } - inner(path.as_ref()) -} - -/// Read the entire contents of a file into a string. -/// -/// This is a convenience function for using [`File::open`] and [`read_to_string`] -/// with fewer imports and without an intermediate variable. -/// -/// [`read_to_string`]: Read::read_to_string -/// -/// # Errors -/// -/// This function will return an error if `path` does not already exist. -/// Other errors may also be returned according to [`OpenOptions::open`]. -/// -/// If the contents of the file are not valid UTF-8, then an error will also be -/// returned. -/// -/// While reading from the file, this function handles [`io::ErrorKind::Interrupted`] -/// with automatic retries. See [io::Read] documentation for details. -/// -/// # Examples -/// -/// ```no_run -/// use std::fs; -/// use std::error::Error; -/// -/// fn main() -> Result<(), Box> { -/// let message: String = fs::read_to_string("message.txt")?; -/// println!("{}", message); -/// Ok(()) -/// } -/// ``` -#[stable(feature = "fs_read_write", since = "1.26.0")] -pub fn read_to_string>(path: P) -> io::Result { - fn inner(path: &Path) -> io::Result { - let mut file = File::open(path)?; - let size = file.metadata().map(|m| m.len() as usize).ok(); - let mut string = String::new(); - string.try_reserve_exact(size.unwrap_or(0))?; - io::default_read_to_string(&mut file, &mut string, size)?; - Ok(string) - } - inner(path.as_ref()) -} - -/// Write a slice as the entire contents of a file. -/// -/// This function will create a file if it does not exist, -/// and will entirely replace its contents if it does. -/// -/// Depending on the platform, this function may fail if the -/// full directory path does not exist. -/// -/// This is a convenience function for using [`File::create`] and [`write_all`] -/// with fewer imports. -/// -/// [`write_all`]: Write::write_all -/// -/// # Examples -/// -/// ```no_run -/// use std::fs; -/// -/// fn main() -> std::io::Result<()> { -/// fs::write("foo.txt", b"Lorem ipsum")?; -/// fs::write("bar.txt", "dolor sit")?; -/// Ok(()) -/// } -/// ``` -#[stable(feature = "fs_read_write_bytes", since = "1.26.0")] -pub fn write, C: AsRef<[u8]>>(path: P, contents: C) -> io::Result<()> { - fn inner(path: &Path, contents: &[u8]) -> io::Result<()> { - File::create(path)?.write_all(contents) - } - inner(path.as_ref(), contents.as_ref()) -} - -impl File { - /// Attempts to open a file in read-only mode. - /// - /// See the [`OpenOptions::open`] method for more details. - /// - /// If you only need to read the entire file contents, - /// consider [`std::fs::read()`][self::read] or - /// [`std::fs::read_to_string()`][self::read_to_string] instead. - /// - /// # Errors - /// - /// This function will return an error if `path` does not already exist. - /// Other errors may also be returned according to [`OpenOptions::open`]. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::File; - /// use std::io::Read; - /// - /// fn main() -> std::io::Result<()> { - /// let mut f = File::open("foo.txt")?; - /// let mut data = vec![]; - /// f.read_to_end(&mut data)?; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn open>(path: P) -> io::Result { - OpenOptions::new().read(true).open(path.as_ref()) - } - - /// Opens a file in write-only mode. - /// - /// This function will create a file if it does not exist, - /// and will truncate it if it does. - /// - /// Depending on the platform, this function may fail if the - /// full directory path does not exist. - /// See the [`OpenOptions::open`] function for more details. - /// - /// See also [`std::fs::write()`][self::write] for a simple function to - /// create a file with some given data. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::File; - /// use std::io::Write; - /// - /// fn main() -> std::io::Result<()> { - /// let mut f = File::create("foo.txt")?; - /// f.write_all(&1234_u32.to_be_bytes())?; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn create>(path: P) -> io::Result { - OpenOptions::new().write(true).create(true).truncate(true).open(path.as_ref()) - } - - /// Creates a new file in read-write mode; error if the file exists. - /// - /// This function will create a file if it does not exist, or return an error if it does. This - /// way, if the call succeeds, the file returned is guaranteed to be new. - /// If a file exists at the target location, creating a new file will fail with [`AlreadyExists`] - /// or another error based on the situation. See [`OpenOptions::open`] for a - /// non-exhaustive list of likely errors. - /// - /// This option is useful because it is atomic. Otherwise between checking whether a file - /// exists and creating a new one, the file may have been created by another process (a TOCTOU - /// race condition / attack). - /// - /// This can also be written using - /// `File::options().read(true).write(true).create_new(true).open(...)`. - /// - /// [`AlreadyExists`]: crate::io::ErrorKind::AlreadyExists - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::File; - /// use std::io::Write; - /// - /// fn main() -> std::io::Result<()> { - /// let mut f = File::create_new("foo.txt")?; - /// f.write_all("Hello, world!".as_bytes())?; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "file_create_new", since = "1.77.0")] - pub fn create_new>(path: P) -> io::Result { - OpenOptions::new().read(true).write(true).create_new(true).open(path.as_ref()) - } - - /// Returns a new OpenOptions object. - /// - /// This function returns a new OpenOptions object that you can use to - /// open or create a file with specific options if `open()` or `create()` - /// are not appropriate. - /// - /// It is equivalent to `OpenOptions::new()`, but allows you to write more - /// readable code. Instead of - /// `OpenOptions::new().append(true).open("example.log")`, - /// you can write `File::options().append(true).open("example.log")`. This - /// also avoids the need to import `OpenOptions`. - /// - /// See the [`OpenOptions::new`] function for more details. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::File; - /// use std::io::Write; - /// - /// fn main() -> std::io::Result<()> { - /// let mut f = File::options().append(true).open("example.log")?; - /// writeln!(&mut f, "new line")?; - /// Ok(()) - /// } - /// ``` - #[must_use] - #[stable(feature = "with_options", since = "1.58.0")] - pub fn options() -> OpenOptions { - OpenOptions::new() - } - - /// Attempts to sync all OS-internal file content and metadata to disk. - /// - /// This function will attempt to ensure that all in-memory data reaches the - /// filesystem before returning. - /// - /// This can be used to handle errors that would otherwise only be caught - /// when the `File` is closed, as dropping a `File` will ignore all errors. - /// Note, however, that `sync_all` is generally more expensive than closing - /// a file by dropping it, because the latter is not required to block until - /// the data has been written to the filesystem. - /// - /// If synchronizing the metadata is not required, use [`sync_data`] instead. - /// - /// [`sync_data`]: File::sync_data - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::File; - /// use std::io::prelude::*; - /// - /// fn main() -> std::io::Result<()> { - /// let mut f = File::create("foo.txt")?; - /// f.write_all(b"Hello, world!")?; - /// - /// f.sync_all()?; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[doc(alias = "fsync")] - pub fn sync_all(&self) -> io::Result<()> { - self.inner.fsync() - } - - /// This function is similar to [`sync_all`], except that it might not - /// synchronize file metadata to the filesystem. - /// - /// This is intended for use cases that must synchronize content, but don't - /// need the metadata on disk. The goal of this method is to reduce disk - /// operations. - /// - /// Note that some platforms may simply implement this in terms of - /// [`sync_all`]. - /// - /// [`sync_all`]: File::sync_all - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::File; - /// use std::io::prelude::*; - /// - /// fn main() -> std::io::Result<()> { - /// let mut f = File::create("foo.txt")?; - /// f.write_all(b"Hello, world!")?; - /// - /// f.sync_data()?; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[doc(alias = "fdatasync")] - pub fn sync_data(&self) -> io::Result<()> { - self.inner.datasync() - } - - /// Truncates or extends the underlying file, updating the size of - /// this file to become `size`. - /// - /// If the `size` is less than the current file's size, then the file will - /// be shrunk. If it is greater than the current file's size, then the file - /// will be extended to `size` and have all of the intermediate data filled - /// in with 0s. - /// - /// The file's cursor isn't changed. In particular, if the cursor was at the - /// end and the file is shrunk using this operation, the cursor will now be - /// past the end. - /// - /// # Errors - /// - /// This function will return an error if the file is not opened for writing. - /// Also, [`std::io::ErrorKind::InvalidInput`](crate::io::ErrorKind::InvalidInput) - /// will be returned if the desired length would cause an overflow due to - /// the implementation specifics. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::File; - /// - /// fn main() -> std::io::Result<()> { - /// let mut f = File::create("foo.txt")?; - /// f.set_len(10)?; - /// Ok(()) - /// } - /// ``` - /// - /// Note that this method alters the content of the underlying file, even - /// though it takes `&self` rather than `&mut self`. - #[stable(feature = "rust1", since = "1.0.0")] - pub fn set_len(&self, size: u64) -> io::Result<()> { - self.inner.truncate(size) - } - - /// Queries metadata about the underlying file. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::File; - /// - /// fn main() -> std::io::Result<()> { - /// let mut f = File::open("foo.txt")?; - /// let metadata = f.metadata()?; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn metadata(&self) -> io::Result { - self.inner.file_attr().map(Metadata) - } - - /// Creates a new `File` instance that shares the same underlying file handle - /// as the existing `File` instance. Reads, writes, and seeks will affect - /// both `File` instances simultaneously. - /// - /// # Examples - /// - /// Creates two handles for a file named `foo.txt`: - /// - /// ```no_run - /// use std::fs::File; - /// - /// fn main() -> std::io::Result<()> { - /// let mut file = File::open("foo.txt")?; - /// let file_copy = file.try_clone()?; - /// Ok(()) - /// } - /// ``` - /// - /// Assuming there’s a file named `foo.txt` with contents `abcdef\n`, create - /// two handles, seek one of them, and read the remaining bytes from the - /// other handle: - /// - /// ```no_run - /// use std::fs::File; - /// use std::io::SeekFrom; - /// use std::io::prelude::*; - /// - /// fn main() -> std::io::Result<()> { - /// let mut file = File::open("foo.txt")?; - /// let mut file_copy = file.try_clone()?; - /// - /// file.seek(SeekFrom::Start(3))?; - /// - /// let mut contents = vec![]; - /// file_copy.read_to_end(&mut contents)?; - /// assert_eq!(contents, b"def\n"); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "file_try_clone", since = "1.9.0")] - pub fn try_clone(&self) -> io::Result { - Ok(File { inner: self.inner.duplicate()? }) - } - - /// Changes the permissions on the underlying file. - /// - /// # Platform-specific behavior - /// - /// This function currently corresponds to the `fchmod` function on Unix and - /// the `SetFileInformationByHandle` function on Windows. Note that, this - /// [may change in the future][changes]. - /// - /// [changes]: io#platform-specific-behavior - /// - /// # Errors - /// - /// This function will return an error if the user lacks permission change - /// attributes on the underlying file. It may also return an error in other - /// os-specific unspecified cases. - /// - /// # Examples - /// - /// ```no_run - /// fn main() -> std::io::Result<()> { - /// use std::fs::File; - /// - /// let file = File::open("foo.txt")?; - /// let mut perms = file.metadata()?.permissions(); - /// perms.set_readonly(true); - /// file.set_permissions(perms)?; - /// Ok(()) - /// } - /// ``` - /// - /// Note that this method alters the permissions of the underlying file, - /// even though it takes `&self` rather than `&mut self`. - #[doc(alias = "fchmod", alias = "SetFileInformationByHandle")] - #[stable(feature = "set_permissions_atomic", since = "1.16.0")] - pub fn set_permissions(&self, perm: Permissions) -> io::Result<()> { - self.inner.set_permissions(perm.0) - } - - /// Changes the timestamps of the underlying file. - /// - /// # Platform-specific behavior - /// - /// This function currently corresponds to the `futimens` function on Unix (falling back to - /// `futimes` on macOS before 10.13) and the `SetFileTime` function on Windows. Note that this - /// [may change in the future][changes]. - /// - /// [changes]: io#platform-specific-behavior - /// - /// # Errors - /// - /// This function will return an error if the user lacks permission to change timestamps on the - /// underlying file. It may also return an error in other os-specific unspecified cases. - /// - /// This function may return an error if the operating system lacks support to change one or - /// more of the timestamps set in the `FileTimes` structure. - /// - /// # Examples - /// - /// ```no_run - /// fn main() -> std::io::Result<()> { - /// use std::fs::{self, File, FileTimes}; - /// - /// let src = fs::metadata("src")?; - /// let dest = File::options().write(true).open("dest")?; - /// let times = FileTimes::new() - /// .set_accessed(src.accessed()?) - /// .set_modified(src.modified()?); - /// dest.set_times(times)?; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "file_set_times", since = "1.75.0")] - #[doc(alias = "futimens")] - #[doc(alias = "futimes")] - #[doc(alias = "SetFileTime")] - pub fn set_times(&self, times: FileTimes) -> io::Result<()> { - self.inner.set_times(times.0) - } - - /// Changes the modification time of the underlying file. - /// - /// This is an alias for `set_times(FileTimes::new().set_modified(time))`. - #[stable(feature = "file_set_times", since = "1.75.0")] - #[inline] - pub fn set_modified(&self, time: SystemTime) -> io::Result<()> { - self.set_times(FileTimes::new().set_modified(time)) - } -} - -// In addition to the `impl`s here, `File` also has `impl`s for -// `AsFd`/`From`/`Into` and -// `AsRawFd`/`IntoRawFd`/`FromRawFd`, on Unix and WASI, and -// `AsHandle`/`From`/`Into` and -// `AsRawHandle`/`IntoRawHandle`/`FromRawHandle` on Windows. - -impl AsInner for File { - #[inline] - fn as_inner(&self) -> &fs_imp::File { - &self.inner - } -} -impl FromInner for File { - fn from_inner(f: fs_imp::File) -> File { - File { inner: f } - } -} -impl IntoInner for File { - fn into_inner(self) -> fs_imp::File { - self.inner - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for File { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.inner.fmt(f) - } -} - -/// Indicates how much extra capacity is needed to read the rest of the file. -fn buffer_capacity_required(mut file: &File) -> Option { - let size = file.metadata().map(|m| m.len()).ok()?; - let pos = file.stream_position().ok()?; - // Don't worry about `usize` overflow because reading will fail regardless - // in that case. - Some(size.saturating_sub(pos) as usize) -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Read for &File { - #[inline] - fn read(&mut self, buf: &mut [u8]) -> io::Result { - self.inner.read(buf) - } - - #[inline] - fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - self.inner.read_vectored(bufs) - } - - #[inline] - fn read_buf(&mut self, cursor: BorrowedCursor<'_>) -> io::Result<()> { - self.inner.read_buf(cursor) - } - - #[inline] - fn is_read_vectored(&self) -> bool { - self.inner.is_read_vectored() - } - - // Reserves space in the buffer based on the file size when available. - fn read_to_end(&mut self, buf: &mut Vec) -> io::Result { - let size = buffer_capacity_required(self); - buf.try_reserve(size.unwrap_or(0))?; - io::default_read_to_end(self, buf, size) - } - - // Reserves space in the buffer based on the file size when available. - fn read_to_string(&mut self, buf: &mut String) -> io::Result { - let size = buffer_capacity_required(self); - buf.try_reserve(size.unwrap_or(0))?; - io::default_read_to_string(self, buf, size) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl Write for &File { - fn write(&mut self, buf: &[u8]) -> io::Result { - self.inner.write(buf) - } - - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - self.inner.write_vectored(bufs) - } - - #[inline] - fn is_write_vectored(&self) -> bool { - self.inner.is_write_vectored() - } - - #[inline] - fn flush(&mut self) -> io::Result<()> { - self.inner.flush() - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl Seek for &File { - fn seek(&mut self, pos: SeekFrom) -> io::Result { - self.inner.seek(pos) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Read for File { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - (&*self).read(buf) - } - fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - (&*self).read_vectored(bufs) - } - fn read_buf(&mut self, cursor: BorrowedCursor<'_>) -> io::Result<()> { - (&*self).read_buf(cursor) - } - #[inline] - fn is_read_vectored(&self) -> bool { - (&&*self).is_read_vectored() - } - fn read_to_end(&mut self, buf: &mut Vec) -> io::Result { - (&*self).read_to_end(buf) - } - fn read_to_string(&mut self, buf: &mut String) -> io::Result { - (&*self).read_to_string(buf) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl Write for File { - fn write(&mut self, buf: &[u8]) -> io::Result { - (&*self).write(buf) - } - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - (&*self).write_vectored(bufs) - } - #[inline] - fn is_write_vectored(&self) -> bool { - (&&*self).is_write_vectored() - } - #[inline] - fn flush(&mut self) -> io::Result<()> { - (&*self).flush() - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl Seek for File { - fn seek(&mut self, pos: SeekFrom) -> io::Result { - (&*self).seek(pos) - } -} - -#[stable(feature = "io_traits_arc", since = "1.73.0")] -impl Read for Arc { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - (&**self).read(buf) - } - fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - (&**self).read_vectored(bufs) - } - fn read_buf(&mut self, cursor: BorrowedCursor<'_>) -> io::Result<()> { - (&**self).read_buf(cursor) - } - #[inline] - fn is_read_vectored(&self) -> bool { - (&**self).is_read_vectored() - } - fn read_to_end(&mut self, buf: &mut Vec) -> io::Result { - (&**self).read_to_end(buf) - } - fn read_to_string(&mut self, buf: &mut String) -> io::Result { - (&**self).read_to_string(buf) - } -} -#[stable(feature = "io_traits_arc", since = "1.73.0")] -impl Write for Arc { - fn write(&mut self, buf: &[u8]) -> io::Result { - (&**self).write(buf) - } - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - (&**self).write_vectored(bufs) - } - #[inline] - fn is_write_vectored(&self) -> bool { - (&**self).is_write_vectored() - } - #[inline] - fn flush(&mut self) -> io::Result<()> { - (&**self).flush() - } -} -#[stable(feature = "io_traits_arc", since = "1.73.0")] -impl Seek for Arc { - fn seek(&mut self, pos: SeekFrom) -> io::Result { - (&**self).seek(pos) - } -} - -impl OpenOptions { - /// Creates a blank new set of options ready for configuration. - /// - /// All options are initially set to `false`. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::OpenOptions; - /// - /// let mut options = OpenOptions::new(); - /// let file = options.read(true).open("foo.txt"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - pub fn new() -> Self { - OpenOptions(fs_imp::OpenOptions::new()) - } - - /// Sets the option for read access. - /// - /// This option, when true, will indicate that the file should be - /// `read`-able if opened. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::OpenOptions; - /// - /// let file = OpenOptions::new().read(true).open("foo.txt"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn read(&mut self, read: bool) -> &mut Self { - self.0.read(read); - self - } - - /// Sets the option for write access. - /// - /// This option, when true, will indicate that the file should be - /// `write`-able if opened. - /// - /// If the file already exists, any write calls on it will overwrite its - /// contents, without truncating it. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::OpenOptions; - /// - /// let file = OpenOptions::new().write(true).open("foo.txt"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn write(&mut self, write: bool) -> &mut Self { - self.0.write(write); - self - } - - /// Sets the option for the append mode. - /// - /// This option, when true, means that writes will append to a file instead - /// of overwriting previous contents. - /// Note that setting `.write(true).append(true)` has the same effect as - /// setting only `.append(true)`. - /// - /// Append mode guarantees that writes will be positioned at the current end of file, - /// even when there are other processes or threads appending to the same file. This is - /// unlike [seek]\([SeekFrom]::[End]\(0)) followed by `write()`, which - /// has a race between seeking and writing during which another writer can write, with - /// our `write()` overwriting their data. - /// - /// Keep in mind that this does not necessarily guarantee that data appended by - /// different processes or threads does not interleave. The amount of data accepted a - /// single `write()` call depends on the operating system and file system. A - /// successful `write()` is allowed to write only part of the given data, so even if - /// you're careful to provide the whole message in a single call to `write()`, there - /// is no guarantee that it will be written out in full. If you rely on the filesystem - /// accepting the message in a single write, make sure that all data that belongs - /// together is written in one operation. This can be done by concatenating strings - /// before passing them to [`write()`]. - /// - /// If a file is opened with both read and append access, beware that after - /// opening, and after every write, the position for reading may be set at the - /// end of the file. So, before writing, save the current position (using - /// [Seek]::[stream_position]), and restore it before the next read. - /// - /// ## Note - /// - /// This function doesn't create the file if it doesn't exist. Use the - /// [`OpenOptions::create`] method to do so. - /// - /// [`write()`]: Write::write "io::Write::write" - /// [`flush()`]: Write::flush "io::Write::flush" - /// [stream_position]: Seek::stream_position "io::Seek::stream_position" - /// [seek]: Seek::seek "io::Seek::seek" - /// [Current]: SeekFrom::Current "io::SeekFrom::Current" - /// [End]: SeekFrom::End "io::SeekFrom::End" - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::OpenOptions; - /// - /// let file = OpenOptions::new().append(true).open("foo.txt"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn append(&mut self, append: bool) -> &mut Self { - self.0.append(append); - self - } - - /// Sets the option for truncating a previous file. - /// - /// If a file is successfully opened with this option set it will truncate - /// the file to 0 length if it already exists. - /// - /// The file must be opened with write access for truncate to work. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::OpenOptions; - /// - /// let file = OpenOptions::new().write(true).truncate(true).open("foo.txt"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn truncate(&mut self, truncate: bool) -> &mut Self { - self.0.truncate(truncate); - self - } - - /// Sets the option to create a new file, or open it if it already exists. - /// - /// In order for the file to be created, [`OpenOptions::write`] or - /// [`OpenOptions::append`] access must be used. - /// - /// See also [`std::fs::write()`][self::write] for a simple function to - /// create a file with some given data. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::OpenOptions; - /// - /// let file = OpenOptions::new().write(true).create(true).open("foo.txt"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn create(&mut self, create: bool) -> &mut Self { - self.0.create(create); - self - } - - /// Sets the option to create a new file, failing if it already exists. - /// - /// No file is allowed to exist at the target location, also no (dangling) symlink. In this - /// way, if the call succeeds, the file returned is guaranteed to be new. - /// If a file exists at the target location, creating a new file will fail with [`AlreadyExists`] - /// or another error based on the situation. See [`OpenOptions::open`] for a - /// non-exhaustive list of likely errors. - /// - /// This option is useful because it is atomic. Otherwise between checking - /// whether a file exists and creating a new one, the file may have been - /// created by another process (a TOCTOU race condition / attack). - /// - /// If `.create_new(true)` is set, [`.create()`] and [`.truncate()`] are - /// ignored. - /// - /// The file must be opened with write or append access in order to create - /// a new file. - /// - /// [`.create()`]: OpenOptions::create - /// [`.truncate()`]: OpenOptions::truncate - /// [`AlreadyExists`]: io::ErrorKind::AlreadyExists - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::OpenOptions; - /// - /// let file = OpenOptions::new().write(true) - /// .create_new(true) - /// .open("foo.txt"); - /// ``` - #[stable(feature = "expand_open_options2", since = "1.9.0")] - pub fn create_new(&mut self, create_new: bool) -> &mut Self { - self.0.create_new(create_new); - self - } - - /// Opens a file at `path` with the options specified by `self`. - /// - /// # Errors - /// - /// This function will return an error under a number of different - /// circumstances. Some of these error conditions are listed here, together - /// with their [`io::ErrorKind`]. The mapping to [`io::ErrorKind`]s is not - /// part of the compatibility contract of the function. - /// - /// * [`NotFound`]: The specified file does not exist and neither `create` - /// or `create_new` is set. - /// * [`NotFound`]: One of the directory components of the file path does - /// not exist. - /// * [`PermissionDenied`]: The user lacks permission to get the specified - /// access rights for the file. - /// * [`PermissionDenied`]: The user lacks permission to open one of the - /// directory components of the specified path. - /// * [`AlreadyExists`]: `create_new` was specified and the file already - /// exists. - /// * [`InvalidInput`]: Invalid combinations of open options (truncate - /// without write access, no access mode set, etc.). - /// - /// The following errors don't match any existing [`io::ErrorKind`] at the moment: - /// * One of the directory components of the specified file path - /// was not, in fact, a directory. - /// * Filesystem-level errors: full disk, write permission - /// requested on a read-only file system, exceeded disk quota, too many - /// open files, too long filename, too many symbolic links in the - /// specified path (Unix-like systems only), etc. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::OpenOptions; - /// - /// let file = OpenOptions::new().read(true).open("foo.txt"); - /// ``` - /// - /// [`AlreadyExists`]: io::ErrorKind::AlreadyExists - /// [`InvalidInput`]: io::ErrorKind::InvalidInput - /// [`NotFound`]: io::ErrorKind::NotFound - /// [`PermissionDenied`]: io::ErrorKind::PermissionDenied - #[stable(feature = "rust1", since = "1.0.0")] - pub fn open>(&self, path: P) -> io::Result { - self._open(path.as_ref()) - } - - fn _open(&self, path: &Path) -> io::Result { - fs_imp::File::open(path, &self.0).map(|inner| File { inner }) - } -} - -impl AsInner for OpenOptions { - #[inline] - fn as_inner(&self) -> &fs_imp::OpenOptions { - &self.0 - } -} - -impl AsInnerMut for OpenOptions { - #[inline] - fn as_inner_mut(&mut self) -> &mut fs_imp::OpenOptions { - &mut self.0 - } -} - -impl Metadata { - /// Returns the file type for this metadata. - /// - /// # Examples - /// - /// ```no_run - /// fn main() -> std::io::Result<()> { - /// use std::fs; - /// - /// let metadata = fs::metadata("foo.txt")?; - /// - /// println!("{:?}", metadata.file_type()); - /// Ok(()) - /// } - /// ``` - #[must_use] - #[stable(feature = "file_type", since = "1.1.0")] - pub fn file_type(&self) -> FileType { - FileType(self.0.file_type()) - } - - /// Returns `true` if this metadata is for a directory. The - /// result is mutually exclusive to the result of - /// [`Metadata::is_file`], and will be false for symlink metadata - /// obtained from [`symlink_metadata`]. - /// - /// # Examples - /// - /// ```no_run - /// fn main() -> std::io::Result<()> { - /// use std::fs; - /// - /// let metadata = fs::metadata("foo.txt")?; - /// - /// assert!(!metadata.is_dir()); - /// Ok(()) - /// } - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn is_dir(&self) -> bool { - self.file_type().is_dir() - } - - /// Returns `true` if this metadata is for a regular file. The - /// result is mutually exclusive to the result of - /// [`Metadata::is_dir`], and will be false for symlink metadata - /// obtained from [`symlink_metadata`]. - /// - /// When the goal is simply to read from (or write to) the source, the most - /// reliable way to test the source can be read (or written to) is to open - /// it. Only using `is_file` can break workflows like `diff <( prog_a )` on - /// a Unix-like system for example. See [`File::open`] or - /// [`OpenOptions::open`] for more information. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// - /// fn main() -> std::io::Result<()> { - /// let metadata = fs::metadata("foo.txt")?; - /// - /// assert!(metadata.is_file()); - /// Ok(()) - /// } - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn is_file(&self) -> bool { - self.file_type().is_file() - } - - /// Returns `true` if this metadata is for a symbolic link. - /// - /// # Examples - /// - #[cfg_attr(unix, doc = "```no_run")] - #[cfg_attr(not(unix), doc = "```ignore")] - /// use std::fs; - /// use std::path::Path; - /// use std::os::unix::fs::symlink; - /// - /// fn main() -> std::io::Result<()> { - /// let link_path = Path::new("link"); - /// symlink("/origin_does_not_exist/", link_path)?; - /// - /// let metadata = fs::symlink_metadata(link_path)?; - /// - /// assert!(metadata.is_symlink()); - /// Ok(()) - /// } - /// ``` - #[must_use] - #[stable(feature = "is_symlink", since = "1.58.0")] - pub fn is_symlink(&self) -> bool { - self.file_type().is_symlink() - } - - /// Returns the size of the file, in bytes, this metadata is for. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// - /// fn main() -> std::io::Result<()> { - /// let metadata = fs::metadata("foo.txt")?; - /// - /// assert_eq!(0, metadata.len()); - /// Ok(()) - /// } - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn len(&self) -> u64 { - self.0.size() - } - - /// Returns the permissions of the file this metadata is for. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// - /// fn main() -> std::io::Result<()> { - /// let metadata = fs::metadata("foo.txt")?; - /// - /// assert!(!metadata.permissions().readonly()); - /// Ok(()) - /// } - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn permissions(&self) -> Permissions { - Permissions(self.0.perm()) - } - - /// Returns the last modification time listed in this metadata. - /// - /// The returned value corresponds to the `mtime` field of `stat` on Unix - /// platforms and the `ftLastWriteTime` field on Windows platforms. - /// - /// # Errors - /// - /// This field might not be available on all platforms, and will return an - /// `Err` on platforms where it is not available. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// - /// fn main() -> std::io::Result<()> { - /// let metadata = fs::metadata("foo.txt")?; - /// - /// if let Ok(time) = metadata.modified() { - /// println!("{time:?}"); - /// } else { - /// println!("Not supported on this platform"); - /// } - /// Ok(()) - /// } - /// ``` - #[doc(alias = "mtime", alias = "ftLastWriteTime")] - #[stable(feature = "fs_time", since = "1.10.0")] - pub fn modified(&self) -> io::Result { - self.0.modified().map(FromInner::from_inner) - } - - /// Returns the last access time of this metadata. - /// - /// The returned value corresponds to the `atime` field of `stat` on Unix - /// platforms and the `ftLastAccessTime` field on Windows platforms. - /// - /// Note that not all platforms will keep this field update in a file's - /// metadata, for example Windows has an option to disable updating this - /// time when files are accessed and Linux similarly has `noatime`. - /// - /// # Errors - /// - /// This field might not be available on all platforms, and will return an - /// `Err` on platforms where it is not available. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// - /// fn main() -> std::io::Result<()> { - /// let metadata = fs::metadata("foo.txt")?; - /// - /// if let Ok(time) = metadata.accessed() { - /// println!("{time:?}"); - /// } else { - /// println!("Not supported on this platform"); - /// } - /// Ok(()) - /// } - /// ``` - #[doc(alias = "atime", alias = "ftLastAccessTime")] - #[stable(feature = "fs_time", since = "1.10.0")] - pub fn accessed(&self) -> io::Result { - self.0.accessed().map(FromInner::from_inner) - } - - /// Returns the creation time listed in this metadata. - /// - /// The returned value corresponds to the `btime` field of `statx` on - /// Linux kernel starting from to 4.11, the `birthtime` field of `stat` on other - /// Unix platforms, and the `ftCreationTime` field on Windows platforms. - /// - /// # Errors - /// - /// This field might not be available on all platforms, and will return an - /// `Err` on platforms or filesystems where it is not available. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// - /// fn main() -> std::io::Result<()> { - /// let metadata = fs::metadata("foo.txt")?; - /// - /// if let Ok(time) = metadata.created() { - /// println!("{time:?}"); - /// } else { - /// println!("Not supported on this platform or filesystem"); - /// } - /// Ok(()) - /// } - /// ``` - #[doc(alias = "btime", alias = "birthtime", alias = "ftCreationTime")] - #[stable(feature = "fs_time", since = "1.10.0")] - pub fn created(&self) -> io::Result { - self.0.created().map(FromInner::from_inner) - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for Metadata { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let mut debug = f.debug_struct("Metadata"); - debug.field("file_type", &self.file_type()); - debug.field("permissions", &self.permissions()); - debug.field("len", &self.len()); - if let Ok(modified) = self.modified() { - debug.field("modified", &modified); - } - if let Ok(accessed) = self.accessed() { - debug.field("accessed", &accessed); - } - if let Ok(created) = self.created() { - debug.field("created", &created); - } - debug.finish_non_exhaustive() - } -} - -impl AsInner for Metadata { - #[inline] - fn as_inner(&self) -> &fs_imp::FileAttr { - &self.0 - } -} - -impl FromInner for Metadata { - fn from_inner(attr: fs_imp::FileAttr) -> Metadata { - Metadata(attr) - } -} - -impl FileTimes { - /// Create a new `FileTimes` with no times set. - /// - /// Using the resulting `FileTimes` in [`File::set_times`] will not modify any timestamps. - #[stable(feature = "file_set_times", since = "1.75.0")] - pub fn new() -> Self { - Self::default() - } - - /// Set the last access time of a file. - #[stable(feature = "file_set_times", since = "1.75.0")] - pub fn set_accessed(mut self, t: SystemTime) -> Self { - self.0.set_accessed(t.into_inner()); - self - } - - /// Set the last modified time of a file. - #[stable(feature = "file_set_times", since = "1.75.0")] - pub fn set_modified(mut self, t: SystemTime) -> Self { - self.0.set_modified(t.into_inner()); - self - } -} - -impl AsInnerMut for FileTimes { - fn as_inner_mut(&mut self) -> &mut fs_imp::FileTimes { - &mut self.0 - } -} - -// For implementing OS extension traits in `std::os` -#[stable(feature = "file_set_times", since = "1.75.0")] -impl Sealed for FileTimes {} - -impl Permissions { - /// Returns `true` if these permissions describe a readonly (unwritable) file. - /// - /// # Note - /// - /// This function does not take Access Control Lists (ACLs) or Unix group - /// membership into account. - /// - /// # Windows - /// - /// On Windows this returns [`FILE_ATTRIBUTE_READONLY`](https://docs.microsoft.com/en-us/windows/win32/fileio/file-attribute-constants). - /// If `FILE_ATTRIBUTE_READONLY` is set then writes to the file will fail - /// but the user may still have permission to change this flag. If - /// `FILE_ATTRIBUTE_READONLY` is *not* set then writes may still fail due - /// to lack of write permission. - /// The behavior of this attribute for directories depends on the Windows - /// version. - /// - /// # Unix (including macOS) - /// - /// On Unix-based platforms this checks if *any* of the owner, group or others - /// write permission bits are set. It does not check if the current - /// user is in the file's assigned group. It also does not check ACLs. - /// Therefore the return value of this function cannot be relied upon - /// to predict whether attempts to read or write the file will actually succeed. - /// The [`PermissionsExt`] trait gives direct access to the permission bits but - /// also does not read ACLs. - /// - /// [`PermissionsExt`]: crate::os::unix::fs::PermissionsExt - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::File; - /// - /// fn main() -> std::io::Result<()> { - /// let mut f = File::create("foo.txt")?; - /// let metadata = f.metadata()?; - /// - /// assert_eq!(false, metadata.permissions().readonly()); - /// Ok(()) - /// } - /// ``` - #[must_use = "call `set_readonly` to modify the readonly flag"] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn readonly(&self) -> bool { - self.0.readonly() - } - - /// Modifies the readonly flag for this set of permissions. If the - /// `readonly` argument is `true`, using the resulting `Permission` will - /// update file permissions to forbid writing. Conversely, if it's `false`, - /// using the resulting `Permission` will update file permissions to allow - /// writing. - /// - /// This operation does **not** modify the files attributes. This only - /// changes the in-memory value of these attributes for this `Permissions` - /// instance. To modify the files attributes use the [`set_permissions`] - /// function which commits these attribute changes to the file. - /// - /// # Note - /// - /// `set_readonly(false)` makes the file *world-writable* on Unix. - /// You can use the [`PermissionsExt`] trait on Unix to avoid this issue. - /// - /// It also does not take Access Control Lists (ACLs) or Unix group - /// membership into account. - /// - /// # Windows - /// - /// On Windows this sets or clears [`FILE_ATTRIBUTE_READONLY`](https://docs.microsoft.com/en-us/windows/win32/fileio/file-attribute-constants). - /// If `FILE_ATTRIBUTE_READONLY` is set then writes to the file will fail - /// but the user may still have permission to change this flag. If - /// `FILE_ATTRIBUTE_READONLY` is *not* set then the write may still fail if - /// the user does not have permission to write to the file. - /// - /// In Windows 7 and earlier this attribute prevents deleting empty - /// directories. It does not prevent modifying the directory contents. - /// On later versions of Windows this attribute is ignored for directories. - /// - /// # Unix (including macOS) - /// - /// On Unix-based platforms this sets or clears the write access bit for - /// the owner, group *and* others, equivalent to `chmod a+w ` - /// or `chmod a-w ` respectively. The latter will grant write access - /// to all users! You can use the [`PermissionsExt`] trait on Unix - /// to avoid this issue. - /// - /// [`PermissionsExt`]: crate::os::unix::fs::PermissionsExt - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::File; - /// - /// fn main() -> std::io::Result<()> { - /// let f = File::create("foo.txt")?; - /// let metadata = f.metadata()?; - /// let mut permissions = metadata.permissions(); - /// - /// permissions.set_readonly(true); - /// - /// // filesystem doesn't change, only the in memory state of the - /// // readonly permission - /// assert_eq!(false, metadata.permissions().readonly()); - /// - /// // just this particular `permissions`. - /// assert_eq!(true, permissions.readonly()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn set_readonly(&mut self, readonly: bool) { - self.0.set_readonly(readonly) - } -} - -impl FileType { - /// Tests whether this file type represents a directory. The - /// result is mutually exclusive to the results of - /// [`is_file`] and [`is_symlink`]; only zero or one of these - /// tests may pass. - /// - /// [`is_file`]: FileType::is_file - /// [`is_symlink`]: FileType::is_symlink - /// - /// # Examples - /// - /// ```no_run - /// fn main() -> std::io::Result<()> { - /// use std::fs; - /// - /// let metadata = fs::metadata("foo.txt")?; - /// let file_type = metadata.file_type(); - /// - /// assert_eq!(file_type.is_dir(), false); - /// Ok(()) - /// } - /// ``` - #[must_use] - #[stable(feature = "file_type", since = "1.1.0")] - pub fn is_dir(&self) -> bool { - self.0.is_dir() - } - - /// Tests whether this file type represents a regular file. - /// The result is mutually exclusive to the results of - /// [`is_dir`] and [`is_symlink`]; only zero or one of these - /// tests may pass. - /// - /// When the goal is simply to read from (or write to) the source, the most - /// reliable way to test the source can be read (or written to) is to open - /// it. Only using `is_file` can break workflows like `diff <( prog_a )` on - /// a Unix-like system for example. See [`File::open`] or - /// [`OpenOptions::open`] for more information. - /// - /// [`is_dir`]: FileType::is_dir - /// [`is_symlink`]: FileType::is_symlink - /// - /// # Examples - /// - /// ```no_run - /// fn main() -> std::io::Result<()> { - /// use std::fs; - /// - /// let metadata = fs::metadata("foo.txt")?; - /// let file_type = metadata.file_type(); - /// - /// assert_eq!(file_type.is_file(), true); - /// Ok(()) - /// } - /// ``` - #[must_use] - #[stable(feature = "file_type", since = "1.1.0")] - pub fn is_file(&self) -> bool { - self.0.is_file() - } - - /// Tests whether this file type represents a symbolic link. - /// The result is mutually exclusive to the results of - /// [`is_dir`] and [`is_file`]; only zero or one of these - /// tests may pass. - /// - /// The underlying [`Metadata`] struct needs to be retrieved - /// with the [`fs::symlink_metadata`] function and not the - /// [`fs::metadata`] function. The [`fs::metadata`] function - /// follows symbolic links, so [`is_symlink`] would always - /// return `false` for the target file. - /// - /// [`fs::metadata`]: metadata - /// [`fs::symlink_metadata`]: symlink_metadata - /// [`is_dir`]: FileType::is_dir - /// [`is_file`]: FileType::is_file - /// [`is_symlink`]: FileType::is_symlink - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// - /// fn main() -> std::io::Result<()> { - /// let metadata = fs::symlink_metadata("foo.txt")?; - /// let file_type = metadata.file_type(); - /// - /// assert_eq!(file_type.is_symlink(), false); - /// Ok(()) - /// } - /// ``` - #[must_use] - #[stable(feature = "file_type", since = "1.1.0")] - pub fn is_symlink(&self) -> bool { - self.0.is_symlink() - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for FileType { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("FileType") - .field("is_file", &self.is_file()) - .field("is_dir", &self.is_dir()) - .field("is_symlink", &self.is_symlink()) - .finish_non_exhaustive() - } -} - -impl AsInner for FileType { - #[inline] - fn as_inner(&self) -> &fs_imp::FileType { - &self.0 - } -} - -impl FromInner for Permissions { - fn from_inner(f: fs_imp::FilePermissions) -> Permissions { - Permissions(f) - } -} - -impl AsInner for Permissions { - #[inline] - fn as_inner(&self) -> &fs_imp::FilePermissions { - &self.0 - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for ReadDir { - type Item = io::Result; - - fn next(&mut self) -> Option> { - self.0.next().map(|entry| entry.map(DirEntry)) - } -} - -impl DirEntry { - /// Returns the full path to the file that this entry represents. - /// - /// The full path is created by joining the original path to `read_dir` - /// with the filename of this entry. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// - /// fn main() -> std::io::Result<()> { - /// for entry in fs::read_dir(".")? { - /// let dir = entry?; - /// println!("{:?}", dir.path()); - /// } - /// Ok(()) - /// } - /// ``` - /// - /// This prints output like: - /// - /// ```text - /// "./whatever.txt" - /// "./foo.html" - /// "./hello_world.rs" - /// ``` - /// - /// The exact text, of course, depends on what files you have in `.`. - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn path(&self) -> PathBuf { - self.0.path() - } - - /// Returns the metadata for the file that this entry points at. - /// - /// This function will not traverse symlinks if this entry points at a - /// symlink. To traverse symlinks use [`fs::metadata`] or [`fs::File::metadata`]. - /// - /// [`fs::metadata`]: metadata - /// [`fs::File::metadata`]: File::metadata - /// - /// # Platform-specific behavior - /// - /// On Windows this function is cheap to call (no extra system calls - /// needed), but on Unix platforms this function is the equivalent of - /// calling `symlink_metadata` on the path. - /// - /// # Examples - /// - /// ``` - /// use std::fs; - /// - /// if let Ok(entries) = fs::read_dir(".") { - /// for entry in entries { - /// if let Ok(entry) = entry { - /// // Here, `entry` is a `DirEntry`. - /// if let Ok(metadata) = entry.metadata() { - /// // Now let's show our entry's permissions! - /// println!("{:?}: {:?}", entry.path(), metadata.permissions()); - /// } else { - /// println!("Couldn't get metadata for {:?}", entry.path()); - /// } - /// } - /// } - /// } - /// ``` - #[stable(feature = "dir_entry_ext", since = "1.1.0")] - pub fn metadata(&self) -> io::Result { - self.0.metadata().map(Metadata) - } - - /// Returns the file type for the file that this entry points at. - /// - /// This function will not traverse symlinks if this entry points at a - /// symlink. - /// - /// # Platform-specific behavior - /// - /// On Windows and most Unix platforms this function is free (no extra - /// system calls needed), but some Unix platforms may require the equivalent - /// call to `symlink_metadata` to learn about the target file type. - /// - /// # Examples - /// - /// ``` - /// use std::fs; - /// - /// if let Ok(entries) = fs::read_dir(".") { - /// for entry in entries { - /// if let Ok(entry) = entry { - /// // Here, `entry` is a `DirEntry`. - /// if let Ok(file_type) = entry.file_type() { - /// // Now let's show our entry's file type! - /// println!("{:?}: {:?}", entry.path(), file_type); - /// } else { - /// println!("Couldn't get file type for {:?}", entry.path()); - /// } - /// } - /// } - /// } - /// ``` - #[stable(feature = "dir_entry_ext", since = "1.1.0")] - pub fn file_type(&self) -> io::Result { - self.0.file_type().map(FileType) - } - - /// Returns the file name of this directory entry without any - /// leading path component(s). - /// - /// As an example, - /// the output of the function will result in "foo" for all the following paths: - /// - "./foo" - /// - "/the/foo" - /// - "../../foo" - /// - /// # Examples - /// - /// ``` - /// use std::fs; - /// - /// if let Ok(entries) = fs::read_dir(".") { - /// for entry in entries { - /// if let Ok(entry) = entry { - /// // Here, `entry` is a `DirEntry`. - /// println!("{:?}", entry.file_name()); - /// } - /// } - /// } - /// ``` - #[must_use] - #[stable(feature = "dir_entry_ext", since = "1.1.0")] - pub fn file_name(&self) -> OsString { - self.0.file_name() - } -} - -#[stable(feature = "dir_entry_debug", since = "1.13.0")] -impl fmt::Debug for DirEntry { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("DirEntry").field(&self.path()).finish() - } -} - -impl AsInner for DirEntry { - #[inline] - fn as_inner(&self) -> &fs_imp::DirEntry { - &self.0 - } -} - -/// Removes a file from the filesystem. -/// -/// Note that there is no -/// guarantee that the file is immediately deleted (e.g., depending on -/// platform, other open file descriptors may prevent immediate removal). -/// -/// # Platform-specific behavior -/// -/// This function currently corresponds to the `unlink` function on Unix -/// and the `DeleteFile` function on Windows. -/// Note that, this [may change in the future][changes]. -/// -/// [changes]: io#platform-specific-behavior -/// -/// # Errors -/// -/// This function will return an error in the following situations, but is not -/// limited to just these cases: -/// -/// * `path` points to a directory. -/// * The file doesn't exist. -/// * The user lacks permissions to remove the file. -/// -/// # Examples -/// -/// ```no_run -/// use std::fs; -/// -/// fn main() -> std::io::Result<()> { -/// fs::remove_file("a.txt")?; -/// Ok(()) -/// } -/// ``` -#[doc(alias = "rm", alias = "unlink", alias = "DeleteFile")] -#[stable(feature = "rust1", since = "1.0.0")] -pub fn remove_file>(path: P) -> io::Result<()> { - fs_imp::unlink(path.as_ref()) -} - -/// Given a path, query the file system to get information about a file, -/// directory, etc. -/// -/// This function will traverse symbolic links to query information about the -/// destination file. -/// -/// # Platform-specific behavior -/// -/// This function currently corresponds to the `stat` function on Unix -/// and the `GetFileInformationByHandle` function on Windows. -/// Note that, this [may change in the future][changes]. -/// -/// [changes]: io#platform-specific-behavior -/// -/// # Errors -/// -/// This function will return an error in the following situations, but is not -/// limited to just these cases: -/// -/// * The user lacks permissions to perform `metadata` call on `path`. -/// * `path` does not exist. -/// -/// # Examples -/// -/// ```rust,no_run -/// use std::fs; -/// -/// fn main() -> std::io::Result<()> { -/// let attr = fs::metadata("/some/file/path.txt")?; -/// // inspect attr ... -/// Ok(()) -/// } -/// ``` -#[doc(alias = "stat")] -#[stable(feature = "rust1", since = "1.0.0")] -pub fn metadata>(path: P) -> io::Result { - fs_imp::stat(path.as_ref()).map(Metadata) -} - -/// Query the metadata about a file without following symlinks. -/// -/// # Platform-specific behavior -/// -/// This function currently corresponds to the `lstat` function on Unix -/// and the `GetFileInformationByHandle` function on Windows. -/// Note that, this [may change in the future][changes]. -/// -/// [changes]: io#platform-specific-behavior -/// -/// # Errors -/// -/// This function will return an error in the following situations, but is not -/// limited to just these cases: -/// -/// * The user lacks permissions to perform `metadata` call on `path`. -/// * `path` does not exist. -/// -/// # Examples -/// -/// ```rust,no_run -/// use std::fs; -/// -/// fn main() -> std::io::Result<()> { -/// let attr = fs::symlink_metadata("/some/file/path.txt")?; -/// // inspect attr ... -/// Ok(()) -/// } -/// ``` -#[doc(alias = "lstat")] -#[stable(feature = "symlink_metadata", since = "1.1.0")] -pub fn symlink_metadata>(path: P) -> io::Result { - fs_imp::lstat(path.as_ref()).map(Metadata) -} - -/// Rename a file or directory to a new name, replacing the original file if -/// `to` already exists. -/// -/// This will not work if the new name is on a different mount point. -/// -/// # Platform-specific behavior -/// -/// This function currently corresponds to the `rename` function on Unix -/// and the `MoveFileEx` function with the `MOVEFILE_REPLACE_EXISTING` flag on Windows. -/// -/// Because of this, the behavior when both `from` and `to` exist differs. On -/// Unix, if `from` is a directory, `to` must also be an (empty) directory. If -/// `from` is not a directory, `to` must also be not a directory. In contrast, -/// on Windows, `from` can be anything, but `to` must *not* be a directory. -/// -/// Note that, this [may change in the future][changes]. -/// -/// [changes]: io#platform-specific-behavior -/// -/// # Errors -/// -/// This function will return an error in the following situations, but is not -/// limited to just these cases: -/// -/// * `from` does not exist. -/// * The user lacks permissions to view contents. -/// * `from` and `to` are on separate filesystems. -/// -/// # Examples -/// -/// ```no_run -/// use std::fs; -/// -/// fn main() -> std::io::Result<()> { -/// fs::rename("a.txt", "b.txt")?; // Rename a.txt to b.txt -/// Ok(()) -/// } -/// ``` -#[doc(alias = "mv", alias = "MoveFile", alias = "MoveFileEx")] -#[stable(feature = "rust1", since = "1.0.0")] -pub fn rename, Q: AsRef>(from: P, to: Q) -> io::Result<()> { - fs_imp::rename(from.as_ref(), to.as_ref()) -} - -/// Copies the contents of one file to another. This function will also -/// copy the permission bits of the original file to the destination file. -/// -/// This function will **overwrite** the contents of `to`. -/// -/// Note that if `from` and `to` both point to the same file, then the file -/// will likely get truncated by this operation. -/// -/// On success, the total number of bytes copied is returned and it is equal to -/// the length of the `to` file as reported by `metadata`. -/// -/// If you want to copy the contents of one file to another and you’re -/// working with [`File`]s, see the [`io::copy`](io::copy()) function. -/// -/// # Platform-specific behavior -/// -/// This function currently corresponds to the `open` function in Unix -/// with `O_RDONLY` for `from` and `O_WRONLY`, `O_CREAT`, and `O_TRUNC` for `to`. -/// `O_CLOEXEC` is set for returned file descriptors. -/// -/// On Linux (including Android), this function attempts to use `copy_file_range(2)`, -/// and falls back to reading and writing if that is not possible. -/// -/// On Windows, this function currently corresponds to `CopyFileEx`. Alternate -/// NTFS streams are copied but only the size of the main stream is returned by -/// this function. -/// -/// On MacOS, this function corresponds to `fclonefileat` and `fcopyfile`. -/// -/// Note that platform-specific behavior [may change in the future][changes]. -/// -/// [changes]: io#platform-specific-behavior -/// -/// # Errors -/// -/// This function will return an error in the following situations, but is not -/// limited to just these cases: -/// -/// * `from` is neither a regular file nor a symlink to a regular file. -/// * `from` does not exist. -/// * The current process does not have the permission rights to read -/// `from` or write `to`. -/// -/// # Examples -/// -/// ```no_run -/// use std::fs; -/// -/// fn main() -> std::io::Result<()> { -/// fs::copy("foo.txt", "bar.txt")?; // Copy foo.txt to bar.txt -/// Ok(()) -/// } -/// ``` -#[doc(alias = "cp")] -#[doc(alias = "CopyFile", alias = "CopyFileEx")] -#[doc(alias = "fclonefileat", alias = "fcopyfile")] -#[stable(feature = "rust1", since = "1.0.0")] -pub fn copy, Q: AsRef>(from: P, to: Q) -> io::Result { - fs_imp::copy(from.as_ref(), to.as_ref()) -} - -/// Creates a new hard link on the filesystem. -/// -/// The `link` path will be a link pointing to the `original` path. Note that -/// systems often require these two paths to both be located on the same -/// filesystem. -/// -/// If `original` names a symbolic link, it is platform-specific whether the -/// symbolic link is followed. On platforms where it's possible to not follow -/// it, it is not followed, and the created hard link points to the symbolic -/// link itself. -/// -/// # Platform-specific behavior -/// -/// This function currently corresponds the `CreateHardLink` function on Windows. -/// On most Unix systems, it corresponds to the `linkat` function with no flags. -/// On Android, VxWorks, and Redox, it instead corresponds to the `link` function. -/// On MacOS, it uses the `linkat` function if it is available, but on very old -/// systems where `linkat` is not available, `link` is selected at runtime instead. -/// Note that, this [may change in the future][changes]. -/// -/// [changes]: io#platform-specific-behavior -/// -/// # Errors -/// -/// This function will return an error in the following situations, but is not -/// limited to just these cases: -/// -/// * The `original` path is not a file or doesn't exist. -/// -/// # Examples -/// -/// ```no_run -/// use std::fs; -/// -/// fn main() -> std::io::Result<()> { -/// fs::hard_link("a.txt", "b.txt")?; // Hard link a.txt to b.txt -/// Ok(()) -/// } -/// ``` -#[doc(alias = "CreateHardLink", alias = "linkat")] -#[stable(feature = "rust1", since = "1.0.0")] -pub fn hard_link, Q: AsRef>(original: P, link: Q) -> io::Result<()> { - fs_imp::link(original.as_ref(), link.as_ref()) -} - -/// Creates a new symbolic link on the filesystem. -/// -/// The `link` path will be a symbolic link pointing to the `original` path. -/// On Windows, this will be a file symlink, not a directory symlink; -/// for this reason, the platform-specific [`std::os::unix::fs::symlink`] -/// and [`std::os::windows::fs::symlink_file`] or [`symlink_dir`] should be -/// used instead to make the intent explicit. -/// -/// [`std::os::unix::fs::symlink`]: crate::os::unix::fs::symlink -/// [`std::os::windows::fs::symlink_file`]: crate::os::windows::fs::symlink_file -/// [`symlink_dir`]: crate::os::windows::fs::symlink_dir -/// -/// # Examples -/// -/// ```no_run -/// use std::fs; -/// -/// fn main() -> std::io::Result<()> { -/// fs::soft_link("a.txt", "b.txt")?; -/// Ok(()) -/// } -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated( - since = "1.1.0", - note = "replaced with std::os::unix::fs::symlink and \ - std::os::windows::fs::{symlink_file, symlink_dir}" -)] -pub fn soft_link, Q: AsRef>(original: P, link: Q) -> io::Result<()> { - fs_imp::symlink(original.as_ref(), link.as_ref()) -} - -/// Reads a symbolic link, returning the file that the link points to. -/// -/// # Platform-specific behavior -/// -/// This function currently corresponds to the `readlink` function on Unix -/// and the `CreateFile` function with `FILE_FLAG_OPEN_REPARSE_POINT` and -/// `FILE_FLAG_BACKUP_SEMANTICS` flags on Windows. -/// Note that, this [may change in the future][changes]. -/// -/// [changes]: io#platform-specific-behavior -/// -/// # Errors -/// -/// This function will return an error in the following situations, but is not -/// limited to just these cases: -/// -/// * `path` is not a symbolic link. -/// * `path` does not exist. -/// -/// # Examples -/// -/// ```no_run -/// use std::fs; -/// -/// fn main() -> std::io::Result<()> { -/// let path = fs::read_link("a.txt")?; -/// Ok(()) -/// } -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub fn read_link>(path: P) -> io::Result { - fs_imp::readlink(path.as_ref()) -} - -/// Returns the canonical, absolute form of a path with all intermediate -/// components normalized and symbolic links resolved. -/// -/// # Platform-specific behavior -/// -/// This function currently corresponds to the `realpath` function on Unix -/// and the `CreateFile` and `GetFinalPathNameByHandle` functions on Windows. -/// Note that, this [may change in the future][changes]. -/// -/// On Windows, this converts the path to use [extended length path][path] -/// syntax, which allows your program to use longer path names, but means you -/// can only join backslash-delimited paths to it, and it may be incompatible -/// with other applications (if passed to the application on the command-line, -/// or written to a file another application may read). -/// -/// [changes]: io#platform-specific-behavior -/// [path]: https://docs.microsoft.com/en-us/windows/win32/fileio/naming-a-file -/// -/// # Errors -/// -/// This function will return an error in the following situations, but is not -/// limited to just these cases: -/// -/// * `path` does not exist. -/// * A non-final component in path is not a directory. -/// -/// # Examples -/// -/// ```no_run -/// use std::fs; -/// -/// fn main() -> std::io::Result<()> { -/// let path = fs::canonicalize("../a/../foo.txt")?; -/// Ok(()) -/// } -/// ``` -#[doc(alias = "realpath")] -#[doc(alias = "GetFinalPathNameByHandle")] -#[stable(feature = "fs_canonicalize", since = "1.5.0")] -pub fn canonicalize>(path: P) -> io::Result { - fs_imp::canonicalize(path.as_ref()) -} - -/// Creates a new, empty directory at the provided path -/// -/// # Platform-specific behavior -/// -/// This function currently corresponds to the `mkdir` function on Unix -/// and the `CreateDirectoryW` function on Windows. -/// Note that, this [may change in the future][changes]. -/// -/// [changes]: io#platform-specific-behavior -/// -/// **NOTE**: If a parent of the given path doesn't exist, this function will -/// return an error. To create a directory and all its missing parents at the -/// same time, use the [`create_dir_all`] function. -/// -/// # Errors -/// -/// This function will return an error in the following situations, but is not -/// limited to just these cases: -/// -/// * User lacks permissions to create directory at `path`. -/// * A parent of the given path doesn't exist. (To create a directory and all -/// its missing parents at the same time, use the [`create_dir_all`] -/// function.) -/// * `path` already exists. -/// -/// # Examples -/// -/// ```no_run -/// use std::fs; -/// -/// fn main() -> std::io::Result<()> { -/// fs::create_dir("/some/dir")?; -/// Ok(()) -/// } -/// ``` -#[doc(alias = "mkdir", alias = "CreateDirectory")] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "fs_create_dir")] -pub fn create_dir>(path: P) -> io::Result<()> { - DirBuilder::new().create(path.as_ref()) -} - -/// Recursively create a directory and all of its parent components if they -/// are missing. -/// -/// If this function returns an error, some of the parent components might have -/// been created already. -/// -/// # Platform-specific behavior -/// -/// This function currently corresponds to multiple calls to the `mkdir` -/// function on Unix and the `CreateDirectoryW` function on Windows. -/// -/// Note that, this [may change in the future][changes]. -/// -/// [changes]: io#platform-specific-behavior -/// -/// # Errors -/// -/// This function will return an error in the following situations, but is not -/// limited to just these cases: -/// -/// * If any directory in the path specified by `path` -/// does not already exist and it could not be created otherwise. The specific -/// error conditions for when a directory is being created (after it is -/// determined to not exist) are outlined by [`fs::create_dir`]. -/// -/// Notable exception is made for situations where any of the directories -/// specified in the `path` could not be created as it was being created concurrently. -/// Such cases are considered to be successful. That is, calling `create_dir_all` -/// concurrently from multiple threads or processes is guaranteed not to fail -/// due to a race condition with itself. -/// -/// [`fs::create_dir`]: create_dir -/// -/// # Examples -/// -/// ```no_run -/// use std::fs; -/// -/// fn main() -> std::io::Result<()> { -/// fs::create_dir_all("/some/dir")?; -/// Ok(()) -/// } -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub fn create_dir_all>(path: P) -> io::Result<()> { - DirBuilder::new().recursive(true).create(path.as_ref()) -} - -/// Removes an empty directory. -/// -/// # Platform-specific behavior -/// -/// This function currently corresponds to the `rmdir` function on Unix -/// and the `RemoveDirectory` function on Windows. -/// Note that, this [may change in the future][changes]. -/// -/// [changes]: io#platform-specific-behavior -/// -/// # Errors -/// -/// This function will return an error in the following situations, but is not -/// limited to just these cases: -/// -/// * `path` doesn't exist. -/// * `path` isn't a directory. -/// * The user lacks permissions to remove the directory at the provided `path`. -/// * The directory isn't empty. -/// -/// # Examples -/// -/// ```no_run -/// use std::fs; -/// -/// fn main() -> std::io::Result<()> { -/// fs::remove_dir("/some/dir")?; -/// Ok(()) -/// } -/// ``` -#[doc(alias = "rmdir", alias = "RemoveDirectory")] -#[stable(feature = "rust1", since = "1.0.0")] -pub fn remove_dir>(path: P) -> io::Result<()> { - fs_imp::rmdir(path.as_ref()) -} - -/// Removes a directory at this path, after removing all its contents. Use -/// carefully! -/// -/// This function does **not** follow symbolic links and it will simply remove the -/// symbolic link itself. -/// -/// # Platform-specific behavior -/// -/// This function currently corresponds to `openat`, `fdopendir`, `unlinkat` and `lstat` functions -/// on Unix (except for macOS before version 10.10 and REDOX) and the `CreateFileW`, -/// `GetFileInformationByHandleEx`, `SetFileInformationByHandle`, and `NtCreateFile` functions on -/// Windows. Note that, this [may change in the future][changes]. -/// -/// [changes]: io#platform-specific-behavior -/// -/// On macOS before version 10.10 and REDOX, as well as when running in Miri for any target, this -/// function is not protected against time-of-check to time-of-use (TOCTOU) race conditions, and -/// should not be used in security-sensitive code on those platforms. All other platforms are -/// protected. -/// -/// # Errors -/// -/// See [`fs::remove_file`] and [`fs::remove_dir`]. -/// -/// `remove_dir_all` will fail if `remove_dir` or `remove_file` fail on any constituent paths, including the root path. -/// As a result, the directory you are deleting must exist, meaning that this function is not idempotent. -/// -/// Consider ignoring the error if validating the removal is not required for your use case. -/// -/// [`fs::remove_file`]: remove_file -/// [`fs::remove_dir`]: remove_dir -/// -/// # Examples -/// -/// ```no_run -/// use std::fs; -/// -/// fn main() -> std::io::Result<()> { -/// fs::remove_dir_all("/some/dir")?; -/// Ok(()) -/// } -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub fn remove_dir_all>(path: P) -> io::Result<()> { - fs_imp::remove_dir_all(path.as_ref()) -} - -/// Returns an iterator over the entries within a directory. -/// -/// The iterator will yield instances of [io::Result]<[DirEntry]>. -/// New errors may be encountered after an iterator is initially constructed. -/// Entries for the current and parent directories (typically `.` and `..`) are -/// skipped. -/// -/// # Platform-specific behavior -/// -/// This function currently corresponds to the `opendir` function on Unix -/// and the `FindFirstFile` function on Windows. Advancing the iterator -/// currently corresponds to `readdir` on Unix and `FindNextFile` on Windows. -/// Note that, this [may change in the future][changes]. -/// -/// [changes]: io#platform-specific-behavior -/// -/// The order in which this iterator returns entries is platform and filesystem -/// dependent. -/// -/// # Errors -/// -/// This function will return an error in the following situations, but is not -/// limited to just these cases: -/// -/// * The provided `path` doesn't exist. -/// * The process lacks permissions to view the contents. -/// * The `path` points at a non-directory file. -/// -/// # Examples -/// -/// ``` -/// use std::io; -/// use std::fs::{self, DirEntry}; -/// use std::path::Path; -/// -/// // one possible implementation of walking a directory only visiting files -/// fn visit_dirs(dir: &Path, cb: &dyn Fn(&DirEntry)) -> io::Result<()> { -/// if dir.is_dir() { -/// for entry in fs::read_dir(dir)? { -/// let entry = entry?; -/// let path = entry.path(); -/// if path.is_dir() { -/// visit_dirs(&path, cb)?; -/// } else { -/// cb(&entry); -/// } -/// } -/// } -/// Ok(()) -/// } -/// ``` -/// -/// ```rust,no_run -/// use std::{fs, io}; -/// -/// fn main() -> io::Result<()> { -/// let mut entries = fs::read_dir(".")? -/// .map(|res| res.map(|e| e.path())) -/// .collect::, io::Error>>()?; -/// -/// // The order in which `read_dir` returns entries is not guaranteed. If reproducible -/// // ordering is required the entries should be explicitly sorted. -/// -/// entries.sort(); -/// -/// // The entries have now been sorted by their path. -/// -/// Ok(()) -/// } -/// ``` -#[doc(alias = "ls", alias = "opendir", alias = "FindFirstFile", alias = "FindNextFile")] -#[stable(feature = "rust1", since = "1.0.0")] -pub fn read_dir>(path: P) -> io::Result { - fs_imp::readdir(path.as_ref()).map(ReadDir) -} - -/// Changes the permissions found on a file or a directory. -/// -/// # Platform-specific behavior -/// -/// This function currently corresponds to the `chmod` function on Unix -/// and the `SetFileAttributes` function on Windows. -/// Note that, this [may change in the future][changes]. -/// -/// [changes]: io#platform-specific-behavior -/// -/// # Errors -/// -/// This function will return an error in the following situations, but is not -/// limited to just these cases: -/// -/// * `path` does not exist. -/// * The user lacks the permission to change attributes of the file. -/// -/// # Examples -/// -/// ```no_run -/// use std::fs; -/// -/// fn main() -> std::io::Result<()> { -/// let mut perms = fs::metadata("foo.txt")?.permissions(); -/// perms.set_readonly(true); -/// fs::set_permissions("foo.txt", perms)?; -/// Ok(()) -/// } -/// ``` -#[doc(alias = "chmod", alias = "SetFileAttributes")] -#[stable(feature = "set_permissions", since = "1.1.0")] -pub fn set_permissions>(path: P, perm: Permissions) -> io::Result<()> { - fs_imp::set_perm(path.as_ref(), perm.0) -} - -impl DirBuilder { - /// Creates a new set of options with default mode/security settings for all - /// platforms and also non-recursive. - /// - /// # Examples - /// - /// ``` - /// use std::fs::DirBuilder; - /// - /// let builder = DirBuilder::new(); - /// ``` - #[stable(feature = "dir_builder", since = "1.6.0")] - #[must_use] - pub fn new() -> DirBuilder { - DirBuilder { inner: fs_imp::DirBuilder::new(), recursive: false } - } - - /// Indicates that directories should be created recursively, creating all - /// parent directories. Parents that do not exist are created with the same - /// security and permissions settings. - /// - /// This option defaults to `false`. - /// - /// # Examples - /// - /// ``` - /// use std::fs::DirBuilder; - /// - /// let mut builder = DirBuilder::new(); - /// builder.recursive(true); - /// ``` - #[stable(feature = "dir_builder", since = "1.6.0")] - pub fn recursive(&mut self, recursive: bool) -> &mut Self { - self.recursive = recursive; - self - } - - /// Creates the specified directory with the options configured in this - /// builder. - /// - /// It is considered an error if the directory already exists unless - /// recursive mode is enabled. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::{self, DirBuilder}; - /// - /// let path = "/tmp/foo/bar/baz"; - /// DirBuilder::new() - /// .recursive(true) - /// .create(path).unwrap(); - /// - /// assert!(fs::metadata(path).unwrap().is_dir()); - /// ``` - #[stable(feature = "dir_builder", since = "1.6.0")] - pub fn create>(&self, path: P) -> io::Result<()> { - self._create(path.as_ref()) - } - - fn _create(&self, path: &Path) -> io::Result<()> { - if self.recursive { self.create_dir_all(path) } else { self.inner.mkdir(path) } - } - - fn create_dir_all(&self, path: &Path) -> io::Result<()> { - if path == Path::new("") { - return Ok(()); - } - - match self.inner.mkdir(path) { - Ok(()) => return Ok(()), - Err(ref e) if e.kind() == io::ErrorKind::NotFound => {} - Err(_) if path.is_dir() => return Ok(()), - Err(e) => return Err(e), - } - match path.parent() { - Some(p) => self.create_dir_all(p)?, - None => { - return Err(io::const_io_error!( - io::ErrorKind::Uncategorized, - "failed to create whole tree", - )); - } - } - match self.inner.mkdir(path) { - Ok(()) => Ok(()), - Err(_) if path.is_dir() => Ok(()), - Err(e) => Err(e), - } - } -} - -impl AsInnerMut for DirBuilder { - #[inline] - fn as_inner_mut(&mut self) -> &mut fs_imp::DirBuilder { - &mut self.inner - } -} - -/// Returns `Ok(true)` if the path points at an existing entity. -/// -/// This function will traverse symbolic links to query information about the -/// destination file. In case of broken symbolic links this will return `Ok(false)`. -/// -/// As opposed to the [`Path::exists`] method, this will only return `Ok(true)` or `Ok(false)` -/// if the path was _verified_ to exist or not exist. If its existence can neither be confirmed -/// nor denied, an `Err(_)` will be propagated instead. This can be the case if e.g. listing -/// permission is denied on one of the parent directories. -/// -/// Note that while this avoids some pitfalls of the `exists()` method, it still can not -/// prevent time-of-check to time-of-use (TOCTOU) bugs. You should only use it in scenarios -/// where those bugs are not an issue. -/// -/// # Examples -/// -/// ```no_run -/// #![feature(fs_try_exists)] -/// use std::fs; -/// -/// assert!(!fs::try_exists("does_not_exist.txt").expect("Can't check existence of file does_not_exist.txt")); -/// assert!(fs::try_exists("/root/secret_file.txt").is_err()); -/// ``` -/// -/// [`Path::exists`]: crate::path::Path::exists -// FIXME: stabilization should modify documentation of `exists()` to recommend this method -// instead. -#[unstable(feature = "fs_try_exists", issue = "83186")] -#[inline] -pub fn try_exists>(path: P) -> io::Result { - fs_imp::try_exists(path.as_ref()) -} diff --git a/library/std/src/fs/tests.rs b/library/std/src/fs/tests.rs deleted file mode 100644 index dfa05671ab0f1..0000000000000 --- a/library/std/src/fs/tests.rs +++ /dev/null @@ -1,1805 +0,0 @@ -use crate::io::prelude::*; - -use crate::env; -use crate::fs::{self, File, FileTimes, OpenOptions}; -use crate::io::{BorrowedBuf, ErrorKind, SeekFrom}; -use crate::mem::MaybeUninit; -use crate::path::Path; -use crate::str; -use crate::sync::Arc; -use crate::sys_common::io::test::{tmpdir, TempDir}; -use crate::thread; -use crate::time::{Duration, Instant, SystemTime}; - -use rand::RngCore; - -#[cfg(target_os = "macos")] -use crate::ffi::{c_char, c_int}; -#[cfg(unix)] -use crate::os::unix::fs::symlink as symlink_dir; -#[cfg(unix)] -use crate::os::unix::fs::symlink as symlink_file; -#[cfg(unix)] -use crate::os::unix::fs::symlink as junction_point; -#[cfg(windows)] -use crate::os::windows::fs::{junction_point, symlink_dir, symlink_file, OpenOptionsExt}; -#[cfg(target_os = "macos")] -use crate::sys::weak::weak; - -macro_rules! check { - ($e:expr) => { - match $e { - Ok(t) => t, - Err(e) => panic!("{} failed with: {e}", stringify!($e)), - } - }; -} - -#[cfg(windows)] -macro_rules! error { - ($e:expr, $s:expr) => { - match $e { - Ok(_) => panic!("Unexpected success. Should've been: {:?}", $s), - Err(ref err) => { - assert!(err.raw_os_error() == Some($s), "`{}` did not have a code of `{}`", err, $s) - } - } - }; -} - -#[cfg(unix)] -macro_rules! error { - ($e:expr, $s:expr) => { - error_contains!($e, $s) - }; -} - -macro_rules! error_contains { - ($e:expr, $s:expr) => { - match $e { - Ok(_) => panic!("Unexpected success. Should've been: {:?}", $s), - Err(ref err) => { - assert!(err.to_string().contains($s), "`{}` did not contain `{}`", err, $s) - } - } - }; -} - -// Several test fail on windows if the user does not have permission to -// create symlinks (the `SeCreateSymbolicLinkPrivilege`). Instead of -// disabling these test on Windows, use this function to test whether we -// have permission, and return otherwise. This way, we still don't run these -// tests most of the time, but at least we do if the user has the right -// permissions. -pub fn got_symlink_permission(tmpdir: &TempDir) -> bool { - if cfg!(not(windows)) || env::var_os("CI").is_some() { - return true; - } - let link = tmpdir.join("some_hopefully_unique_link_name"); - - match symlink_file(r"nonexisting_target", link) { - // ERROR_PRIVILEGE_NOT_HELD = 1314 - Err(ref err) if err.raw_os_error() == Some(1314) => false, - Ok(_) | Err(_) => true, - } -} - -#[cfg(target_os = "macos")] -fn able_to_not_follow_symlinks_while_hard_linking() -> bool { - weak!(fn linkat(c_int, *const c_char, c_int, *const c_char, c_int) -> c_int); - linkat.get().is_some() -} - -#[cfg(not(target_os = "macos"))] -fn able_to_not_follow_symlinks_while_hard_linking() -> bool { - return true; -} - -#[test] -fn file_test_io_smoke_test() { - let message = "it's alright. have a good time"; - let tmpdir = tmpdir(); - let filename = &tmpdir.join("file_rt_io_file_test.txt"); - { - let mut write_stream = check!(File::create(filename)); - check!(write_stream.write(message.as_bytes())); - } - { - let mut read_stream = check!(File::open(filename)); - let mut read_buf = [0; 1028]; - let read_str = match check!(read_stream.read(&mut read_buf)) { - 0 => panic!("shouldn't happen"), - n => str::from_utf8(&read_buf[..n]).unwrap().to_string(), - }; - assert_eq!(read_str, message); - } - check!(fs::remove_file(filename)); -} - -#[test] -fn invalid_path_raises() { - let tmpdir = tmpdir(); - let filename = &tmpdir.join("file_that_does_not_exist.txt"); - let result = File::open(filename); - - #[cfg(all(unix, not(target_os = "vxworks")))] - error!(result, "No such file or directory"); - #[cfg(target_os = "vxworks")] - error!(result, "no such file or directory"); - #[cfg(windows)] - error!(result, 2); // ERROR_FILE_NOT_FOUND -} - -#[test] -fn file_test_iounlinking_invalid_path_should_raise_condition() { - let tmpdir = tmpdir(); - let filename = &tmpdir.join("file_another_file_that_does_not_exist.txt"); - - let result = fs::remove_file(filename); - - #[cfg(all(unix, not(target_os = "vxworks")))] - error!(result, "No such file or directory"); - #[cfg(target_os = "vxworks")] - error!(result, "no such file or directory"); - #[cfg(windows)] - error!(result, 2); // ERROR_FILE_NOT_FOUND -} - -#[test] -fn file_test_io_non_positional_read() { - let message: &str = "ten-four"; - let mut read_mem = [0; 8]; - let tmpdir = tmpdir(); - let filename = &tmpdir.join("file_rt_io_file_test_positional.txt"); - { - let mut rw_stream = check!(File::create(filename)); - check!(rw_stream.write(message.as_bytes())); - } - { - let mut read_stream = check!(File::open(filename)); - { - let read_buf = &mut read_mem[0..4]; - check!(read_stream.read(read_buf)); - } - { - let read_buf = &mut read_mem[4..8]; - check!(read_stream.read(read_buf)); - } - } - check!(fs::remove_file(filename)); - let read_str = str::from_utf8(&read_mem).unwrap(); - assert_eq!(read_str, message); -} - -#[test] -fn file_test_io_seek_and_tell_smoke_test() { - let message = "ten-four"; - let mut read_mem = [0; 4]; - let set_cursor = 4 as u64; - let tell_pos_pre_read; - let tell_pos_post_read; - let tmpdir = tmpdir(); - let filename = &tmpdir.join("file_rt_io_file_test_seeking.txt"); - { - let mut rw_stream = check!(File::create(filename)); - check!(rw_stream.write(message.as_bytes())); - } - { - let mut read_stream = check!(File::open(filename)); - check!(read_stream.seek(SeekFrom::Start(set_cursor))); - tell_pos_pre_read = check!(read_stream.stream_position()); - check!(read_stream.read(&mut read_mem)); - tell_pos_post_read = check!(read_stream.stream_position()); - } - check!(fs::remove_file(filename)); - let read_str = str::from_utf8(&read_mem).unwrap(); - assert_eq!(read_str, &message[4..8]); - assert_eq!(tell_pos_pre_read, set_cursor); - assert_eq!(tell_pos_post_read, message.len() as u64); -} - -#[test] -fn file_test_io_seek_and_write() { - let initial_msg = "food-is-yummy"; - let overwrite_msg = "-the-bar!!"; - let final_msg = "foo-the-bar!!"; - let seek_idx = 3; - let mut read_mem = [0; 13]; - let tmpdir = tmpdir(); - let filename = &tmpdir.join("file_rt_io_file_test_seek_and_write.txt"); - { - let mut rw_stream = check!(File::create(filename)); - check!(rw_stream.write(initial_msg.as_bytes())); - check!(rw_stream.seek(SeekFrom::Start(seek_idx))); - check!(rw_stream.write(overwrite_msg.as_bytes())); - } - { - let mut read_stream = check!(File::open(filename)); - check!(read_stream.read(&mut read_mem)); - } - check!(fs::remove_file(filename)); - let read_str = str::from_utf8(&read_mem).unwrap(); - assert!(read_str == final_msg); -} - -#[test] -fn file_test_io_seek_shakedown() { - // 01234567890123 - let initial_msg = "qwer-asdf-zxcv"; - let chunk_one: &str = "qwer"; - let chunk_two: &str = "asdf"; - let chunk_three: &str = "zxcv"; - let mut read_mem = [0; 4]; - let tmpdir = tmpdir(); - let filename = &tmpdir.join("file_rt_io_file_test_seek_shakedown.txt"); - { - let mut rw_stream = check!(File::create(filename)); - check!(rw_stream.write(initial_msg.as_bytes())); - } - { - let mut read_stream = check!(File::open(filename)); - - check!(read_stream.seek(SeekFrom::End(-4))); - check!(read_stream.read(&mut read_mem)); - assert_eq!(str::from_utf8(&read_mem).unwrap(), chunk_three); - - check!(read_stream.seek(SeekFrom::Current(-9))); - check!(read_stream.read(&mut read_mem)); - assert_eq!(str::from_utf8(&read_mem).unwrap(), chunk_two); - - check!(read_stream.seek(SeekFrom::Start(0))); - check!(read_stream.read(&mut read_mem)); - assert_eq!(str::from_utf8(&read_mem).unwrap(), chunk_one); - } - check!(fs::remove_file(filename)); -} - -#[test] -fn file_test_io_eof() { - let tmpdir = tmpdir(); - let filename = tmpdir.join("file_rt_io_file_test_eof.txt"); - let mut buf = [0; 256]; - { - let oo = OpenOptions::new().create_new(true).write(true).read(true).clone(); - let mut rw = check!(oo.open(&filename)); - assert_eq!(check!(rw.read(&mut buf)), 0); - assert_eq!(check!(rw.read(&mut buf)), 0); - } - check!(fs::remove_file(&filename)); -} - -#[test] -#[cfg(unix)] -fn file_test_io_read_write_at() { - use crate::os::unix::fs::FileExt; - - let tmpdir = tmpdir(); - let filename = tmpdir.join("file_rt_io_file_test_read_write_at.txt"); - let mut buf = [0; 256]; - let write1 = "asdf"; - let write2 = "qwer-"; - let write3 = "-zxcv"; - let content = "qwer-asdf-zxcv"; - { - let oo = OpenOptions::new().create_new(true).write(true).read(true).clone(); - let mut rw = check!(oo.open(&filename)); - assert_eq!(check!(rw.write_at(write1.as_bytes(), 5)), write1.len()); - assert_eq!(check!(rw.stream_position()), 0); - assert_eq!(check!(rw.read_at(&mut buf, 5)), write1.len()); - assert_eq!(str::from_utf8(&buf[..write1.len()]), Ok(write1)); - assert_eq!(check!(rw.stream_position()), 0); - assert_eq!(check!(rw.read_at(&mut buf[..write2.len()], 0)), write2.len()); - assert_eq!(str::from_utf8(&buf[..write2.len()]), Ok("\0\0\0\0\0")); - assert_eq!(check!(rw.stream_position()), 0); - assert_eq!(check!(rw.write(write2.as_bytes())), write2.len()); - assert_eq!(check!(rw.stream_position()), 5); - assert_eq!(check!(rw.read(&mut buf)), write1.len()); - assert_eq!(str::from_utf8(&buf[..write1.len()]), Ok(write1)); - assert_eq!(check!(rw.stream_position()), 9); - assert_eq!(check!(rw.read_at(&mut buf[..write2.len()], 0)), write2.len()); - assert_eq!(str::from_utf8(&buf[..write2.len()]), Ok(write2)); - assert_eq!(check!(rw.stream_position()), 9); - assert_eq!(check!(rw.write_at(write3.as_bytes(), 9)), write3.len()); - assert_eq!(check!(rw.stream_position()), 9); - } - { - let mut read = check!(File::open(&filename)); - assert_eq!(check!(read.read_at(&mut buf, 0)), content.len()); - assert_eq!(str::from_utf8(&buf[..content.len()]), Ok(content)); - assert_eq!(check!(read.stream_position()), 0); - assert_eq!(check!(read.seek(SeekFrom::End(-5))), 9); - assert_eq!(check!(read.read_at(&mut buf, 0)), content.len()); - assert_eq!(str::from_utf8(&buf[..content.len()]), Ok(content)); - assert_eq!(check!(read.stream_position()), 9); - assert_eq!(check!(read.read(&mut buf)), write3.len()); - assert_eq!(str::from_utf8(&buf[..write3.len()]), Ok(write3)); - assert_eq!(check!(read.stream_position()), 14); - assert_eq!(check!(read.read_at(&mut buf, 0)), content.len()); - assert_eq!(str::from_utf8(&buf[..content.len()]), Ok(content)); - assert_eq!(check!(read.stream_position()), 14); - assert_eq!(check!(read.read_at(&mut buf, 14)), 0); - assert_eq!(check!(read.read_at(&mut buf, 15)), 0); - assert_eq!(check!(read.stream_position()), 14); - } - check!(fs::remove_file(&filename)); -} - -#[test] -#[cfg(unix)] -fn set_get_unix_permissions() { - use crate::os::unix::fs::PermissionsExt; - - let tmpdir = tmpdir(); - let filename = &tmpdir.join("set_get_unix_permissions"); - check!(fs::create_dir(filename)); - let mask = 0o7777; - - check!(fs::set_permissions(filename, fs::Permissions::from_mode(0))); - let metadata0 = check!(fs::metadata(filename)); - assert_eq!(mask & metadata0.permissions().mode(), 0); - - check!(fs::set_permissions(filename, fs::Permissions::from_mode(0o1777))); - let metadata1 = check!(fs::metadata(filename)); - #[cfg(all(unix, not(target_os = "vxworks")))] - assert_eq!(mask & metadata1.permissions().mode(), 0o1777); - #[cfg(target_os = "vxworks")] - assert_eq!(mask & metadata1.permissions().mode(), 0o0777); -} - -#[test] -#[cfg(windows)] -fn file_test_io_seek_read_write() { - use crate::os::windows::fs::FileExt; - - let tmpdir = tmpdir(); - let filename = tmpdir.join("file_rt_io_file_test_seek_read_write.txt"); - let mut buf = [0; 256]; - let write1 = "asdf"; - let write2 = "qwer-"; - let write3 = "-zxcv"; - let content = "qwer-asdf-zxcv"; - { - let oo = OpenOptions::new().create_new(true).write(true).read(true).clone(); - let mut rw = check!(oo.open(&filename)); - assert_eq!(check!(rw.seek_write(write1.as_bytes(), 5)), write1.len()); - assert_eq!(check!(rw.stream_position()), 9); - assert_eq!(check!(rw.seek_read(&mut buf, 5)), write1.len()); - assert_eq!(str::from_utf8(&buf[..write1.len()]), Ok(write1)); - assert_eq!(check!(rw.stream_position()), 9); - assert_eq!(check!(rw.seek(SeekFrom::Start(0))), 0); - assert_eq!(check!(rw.write(write2.as_bytes())), write2.len()); - assert_eq!(check!(rw.stream_position()), 5); - assert_eq!(check!(rw.read(&mut buf)), write1.len()); - assert_eq!(str::from_utf8(&buf[..write1.len()]), Ok(write1)); - assert_eq!(check!(rw.stream_position()), 9); - assert_eq!(check!(rw.seek_read(&mut buf[..write2.len()], 0)), write2.len()); - assert_eq!(str::from_utf8(&buf[..write2.len()]), Ok(write2)); - assert_eq!(check!(rw.stream_position()), 5); - assert_eq!(check!(rw.seek_write(write3.as_bytes(), 9)), write3.len()); - assert_eq!(check!(rw.stream_position()), 14); - } - { - let mut read = check!(File::open(&filename)); - assert_eq!(check!(read.seek_read(&mut buf, 0)), content.len()); - assert_eq!(str::from_utf8(&buf[..content.len()]), Ok(content)); - assert_eq!(check!(read.stream_position()), 14); - assert_eq!(check!(read.seek(SeekFrom::End(-5))), 9); - assert_eq!(check!(read.seek_read(&mut buf, 0)), content.len()); - assert_eq!(str::from_utf8(&buf[..content.len()]), Ok(content)); - assert_eq!(check!(read.stream_position()), 14); - assert_eq!(check!(read.seek(SeekFrom::End(-5))), 9); - assert_eq!(check!(read.read(&mut buf)), write3.len()); - assert_eq!(str::from_utf8(&buf[..write3.len()]), Ok(write3)); - assert_eq!(check!(read.stream_position()), 14); - assert_eq!(check!(read.seek_read(&mut buf, 0)), content.len()); - assert_eq!(str::from_utf8(&buf[..content.len()]), Ok(content)); - assert_eq!(check!(read.stream_position()), 14); - assert_eq!(check!(read.seek_read(&mut buf, 14)), 0); - assert_eq!(check!(read.seek_read(&mut buf, 15)), 0); - } - check!(fs::remove_file(&filename)); -} - -#[test] -fn file_test_read_buf() { - let tmpdir = tmpdir(); - let filename = &tmpdir.join("test"); - check!(fs::write(filename, &[1, 2, 3, 4])); - - let mut buf: [MaybeUninit; 128] = MaybeUninit::uninit_array(); - let mut buf = BorrowedBuf::from(buf.as_mut_slice()); - let mut file = check!(File::open(filename)); - check!(file.read_buf(buf.unfilled())); - assert_eq!(buf.filled(), &[1, 2, 3, 4]); - // File::read_buf should omit buffer initialization. - assert_eq!(buf.init_len(), 4); - - check!(fs::remove_file(filename)); -} - -#[test] -fn file_test_stat_is_correct_on_is_file() { - let tmpdir = tmpdir(); - let filename = &tmpdir.join("file_stat_correct_on_is_file.txt"); - { - let mut opts = OpenOptions::new(); - let mut fs = check!(opts.read(true).write(true).create(true).open(filename)); - let msg = "hw"; - fs.write(msg.as_bytes()).unwrap(); - - let fstat_res = check!(fs.metadata()); - assert!(fstat_res.is_file()); - } - let stat_res_fn = check!(fs::metadata(filename)); - assert!(stat_res_fn.is_file()); - let stat_res_meth = check!(filename.metadata()); - assert!(stat_res_meth.is_file()); - check!(fs::remove_file(filename)); -} - -#[test] -fn file_test_stat_is_correct_on_is_dir() { - let tmpdir = tmpdir(); - let filename = &tmpdir.join("file_stat_correct_on_is_dir"); - check!(fs::create_dir(filename)); - let stat_res_fn = check!(fs::metadata(filename)); - assert!(stat_res_fn.is_dir()); - let stat_res_meth = check!(filename.metadata()); - assert!(stat_res_meth.is_dir()); - check!(fs::remove_dir(filename)); -} - -#[test] -fn file_test_fileinfo_false_when_checking_is_file_on_a_directory() { - let tmpdir = tmpdir(); - let dir = &tmpdir.join("fileinfo_false_on_dir"); - check!(fs::create_dir(dir)); - assert!(!dir.is_file()); - check!(fs::remove_dir(dir)); -} - -#[test] -fn file_test_fileinfo_check_exists_before_and_after_file_creation() { - let tmpdir = tmpdir(); - let file = &tmpdir.join("fileinfo_check_exists_b_and_a.txt"); - check!(check!(File::create(file)).write(b"foo")); - assert!(file.exists()); - check!(fs::remove_file(file)); - assert!(!file.exists()); -} - -#[test] -fn file_test_directoryinfo_check_exists_before_and_after_mkdir() { - let tmpdir = tmpdir(); - let dir = &tmpdir.join("before_and_after_dir"); - assert!(!dir.exists()); - check!(fs::create_dir(dir)); - assert!(dir.exists()); - assert!(dir.is_dir()); - check!(fs::remove_dir(dir)); - assert!(!dir.exists()); -} - -#[test] -fn file_test_directoryinfo_readdir() { - let tmpdir = tmpdir(); - let dir = &tmpdir.join("di_readdir"); - check!(fs::create_dir(dir)); - let prefix = "foo"; - for n in 0..3 { - let f = dir.join(&format!("{n}.txt")); - let mut w = check!(File::create(&f)); - let msg_str = format!("{}{}", prefix, n.to_string()); - let msg = msg_str.as_bytes(); - check!(w.write(msg)); - } - let files = check!(fs::read_dir(dir)); - let mut mem = [0; 4]; - for f in files { - let f = f.unwrap().path(); - { - let n = f.file_stem().unwrap(); - check!(check!(File::open(&f)).read(&mut mem)); - let read_str = str::from_utf8(&mem).unwrap(); - let expected = format!("{}{}", prefix, n.to_str().unwrap()); - assert_eq!(expected, read_str); - } - check!(fs::remove_file(&f)); - } - check!(fs::remove_dir(dir)); -} - -#[test] -fn file_create_new_already_exists_error() { - let tmpdir = tmpdir(); - let file = &tmpdir.join("file_create_new_error_exists"); - check!(fs::File::create(file)); - let e = fs::OpenOptions::new().write(true).create_new(true).open(file).unwrap_err(); - assert_eq!(e.kind(), ErrorKind::AlreadyExists); -} - -#[test] -fn mkdir_path_already_exists_error() { - let tmpdir = tmpdir(); - let dir = &tmpdir.join("mkdir_error_twice"); - check!(fs::create_dir(dir)); - let e = fs::create_dir(dir).unwrap_err(); - assert_eq!(e.kind(), ErrorKind::AlreadyExists); -} - -#[test] -fn recursive_mkdir() { - let tmpdir = tmpdir(); - let dir = tmpdir.join("d1/d2"); - check!(fs::create_dir_all(&dir)); - assert!(dir.is_dir()) -} - -#[test] -fn recursive_mkdir_failure() { - let tmpdir = tmpdir(); - let dir = tmpdir.join("d1"); - let file = dir.join("f1"); - - check!(fs::create_dir_all(&dir)); - check!(File::create(&file)); - - let result = fs::create_dir_all(&file); - - assert!(result.is_err()); -} - -#[test] -fn concurrent_recursive_mkdir() { - for _ in 0..100 { - let dir = tmpdir(); - let mut dir = dir.join("a"); - for _ in 0..40 { - dir = dir.join("a"); - } - let mut join = vec![]; - for _ in 0..8 { - let dir = dir.clone(); - join.push(thread::spawn(move || { - check!(fs::create_dir_all(&dir)); - })) - } - - // No `Display` on result of `join()` - join.drain(..).map(|join| join.join().unwrap()).count(); - } -} - -#[test] -fn recursive_mkdir_slash() { - check!(fs::create_dir_all(Path::new("/"))); -} - -#[test] -fn recursive_mkdir_dot() { - check!(fs::create_dir_all(Path::new("."))); -} - -#[test] -fn recursive_mkdir_empty() { - check!(fs::create_dir_all(Path::new(""))); -} - -#[test] -fn recursive_rmdir() { - let tmpdir = tmpdir(); - let d1 = tmpdir.join("d1"); - let dt = d1.join("t"); - let dtt = dt.join("t"); - let d2 = tmpdir.join("d2"); - let canary = d2.join("do_not_delete"); - check!(fs::create_dir_all(&dtt)); - check!(fs::create_dir_all(&d2)); - check!(check!(File::create(&canary)).write(b"foo")); - check!(junction_point(&d2, &dt.join("d2"))); - let _ = symlink_file(&canary, &d1.join("canary")); - check!(fs::remove_dir_all(&d1)); - - assert!(!d1.is_dir()); - assert!(canary.exists()); -} - -#[test] -fn recursive_rmdir_of_symlink() { - // test we do not recursively delete a symlink but only dirs. - let tmpdir = tmpdir(); - let link = tmpdir.join("d1"); - let dir = tmpdir.join("d2"); - let canary = dir.join("do_not_delete"); - check!(fs::create_dir_all(&dir)); - check!(check!(File::create(&canary)).write(b"foo")); - check!(junction_point(&dir, &link)); - check!(fs::remove_dir_all(&link)); - - assert!(!link.is_dir()); - assert!(canary.exists()); -} - -#[test] -fn recursive_rmdir_of_file_fails() { - // test we do not delete a directly specified file. - let tmpdir = tmpdir(); - let canary = tmpdir.join("do_not_delete"); - check!(check!(File::create(&canary)).write(b"foo")); - let result = fs::remove_dir_all(&canary); - #[cfg(unix)] - error!(result, "Not a directory"); - #[cfg(windows)] - error!(result, 267); // ERROR_DIRECTORY - The directory name is invalid. - assert!(result.is_err()); - assert!(canary.exists()); -} - -#[test] -// only Windows makes a distinction between file and directory symlinks. -#[cfg(windows)] -fn recursive_rmdir_of_file_symlink() { - let tmpdir = tmpdir(); - if !got_symlink_permission(&tmpdir) { - return; - }; - - let f1 = tmpdir.join("f1"); - let f2 = tmpdir.join("f2"); - check!(check!(File::create(&f1)).write(b"foo")); - check!(symlink_file(&f1, &f2)); - match fs::remove_dir_all(&f2) { - Ok(..) => panic!("wanted a failure"), - Err(..) => {} - } -} - -#[test] -#[ignore] // takes too much time -fn recursive_rmdir_toctou() { - // Test for time-of-check to time-of-use issues. - // - // Scenario: - // The attacker wants to get directory contents deleted, to which they do not have access. - // They have a way to get a privileged Rust binary call `std::fs::remove_dir_all()` on a - // directory they control, e.g. in their home directory. - // - // The POC sets up the `attack_dest/attack_file` which the attacker wants to have deleted. - // The attacker repeatedly creates a directory and replaces it with a symlink from - // `victim_del` to `attack_dest` while the victim code calls `std::fs::remove_dir_all()` - // on `victim_del`. After a few seconds the attack has succeeded and - // `attack_dest/attack_file` is deleted. - let tmpdir = tmpdir(); - let victim_del_path = tmpdir.join("victim_del"); - let victim_del_path_clone = victim_del_path.clone(); - - // setup dest - let attack_dest_dir = tmpdir.join("attack_dest"); - let attack_dest_dir = attack_dest_dir.as_path(); - fs::create_dir(attack_dest_dir).unwrap(); - let attack_dest_file = tmpdir.join("attack_dest/attack_file"); - File::create(&attack_dest_file).unwrap(); - - let drop_canary_arc = Arc::new(()); - let drop_canary_weak = Arc::downgrade(&drop_canary_arc); - - eprintln!("x: {:?}", &victim_del_path); - - // victim just continuously removes `victim_del` - thread::spawn(move || { - while drop_canary_weak.upgrade().is_some() { - let _ = fs::remove_dir_all(&victim_del_path_clone); - } - }); - - // attacker (could of course be in a separate process) - let start_time = Instant::now(); - while Instant::now().duration_since(start_time) < Duration::from_secs(1000) { - if !attack_dest_file.exists() { - panic!( - "Victim deleted symlinked file outside of victim_del. Attack succeeded in {:?}.", - Instant::now().duration_since(start_time) - ); - } - let _ = fs::create_dir(&victim_del_path); - let _ = fs::remove_dir(&victim_del_path); - let _ = symlink_dir(attack_dest_dir, &victim_del_path); - } -} - -#[test] -fn unicode_path_is_dir() { - assert!(Path::new(".").is_dir()); - assert!(!Path::new("test/stdtest/fs.rs").is_dir()); - - let tmpdir = tmpdir(); - - let mut dirpath = tmpdir.path().to_path_buf(); - dirpath.push("test-가一ー你好"); - check!(fs::create_dir(&dirpath)); - assert!(dirpath.is_dir()); - - let mut filepath = dirpath; - filepath.push("unicode-file-\u{ac00}\u{4e00}\u{30fc}\u{4f60}\u{597d}.rs"); - check!(File::create(&filepath)); // ignore return; touch only - assert!(!filepath.is_dir()); - assert!(filepath.exists()); -} - -#[test] -fn unicode_path_exists() { - assert!(Path::new(".").exists()); - assert!(!Path::new("test/nonexistent-bogus-path").exists()); - - let tmpdir = tmpdir(); - let unicode = tmpdir.path(); - let unicode = unicode.join("test-각丁ー再见"); - check!(fs::create_dir(&unicode)); - assert!(unicode.exists()); - assert!(!Path::new("test/unicode-bogus-path-각丁ー再见").exists()); -} - -#[test] -fn copy_file_does_not_exist() { - let from = Path::new("test/nonexistent-bogus-path"); - let to = Path::new("test/other-bogus-path"); - - match fs::copy(&from, &to) { - Ok(..) => panic!(), - Err(..) => { - assert!(!from.exists()); - assert!(!to.exists()); - } - } -} - -#[test] -fn copy_src_does_not_exist() { - let tmpdir = tmpdir(); - let from = Path::new("test/nonexistent-bogus-path"); - let to = tmpdir.join("out.txt"); - check!(check!(File::create(&to)).write(b"hello")); - assert!(fs::copy(&from, &to).is_err()); - assert!(!from.exists()); - let mut v = Vec::new(); - check!(check!(File::open(&to)).read_to_end(&mut v)); - assert_eq!(v, b"hello"); -} - -#[test] -fn copy_file_ok() { - let tmpdir = tmpdir(); - let input = tmpdir.join("in.txt"); - let out = tmpdir.join("out.txt"); - - check!(check!(File::create(&input)).write(b"hello")); - check!(fs::copy(&input, &out)); - let mut v = Vec::new(); - check!(check!(File::open(&out)).read_to_end(&mut v)); - assert_eq!(v, b"hello"); - - assert_eq!(check!(input.metadata()).permissions(), check!(out.metadata()).permissions()); -} - -#[test] -fn copy_file_dst_dir() { - let tmpdir = tmpdir(); - let out = tmpdir.join("out"); - - check!(File::create(&out)); - match fs::copy(&*out, tmpdir.path()) { - Ok(..) => panic!(), - Err(..) => {} - } -} - -#[test] -fn copy_file_dst_exists() { - let tmpdir = tmpdir(); - let input = tmpdir.join("in"); - let output = tmpdir.join("out"); - - check!(check!(File::create(&input)).write("foo".as_bytes())); - check!(check!(File::create(&output)).write("bar".as_bytes())); - check!(fs::copy(&input, &output)); - - let mut v = Vec::new(); - check!(check!(File::open(&output)).read_to_end(&mut v)); - assert_eq!(v, b"foo".to_vec()); -} - -#[test] -fn copy_file_src_dir() { - let tmpdir = tmpdir(); - let out = tmpdir.join("out"); - - match fs::copy(tmpdir.path(), &out) { - Ok(..) => panic!(), - Err(..) => {} - } - assert!(!out.exists()); -} - -#[test] -fn copy_file_preserves_perm_bits() { - let tmpdir = tmpdir(); - let input = tmpdir.join("in.txt"); - let out = tmpdir.join("out.txt"); - - let attr = check!(check!(File::create(&input)).metadata()); - let mut p = attr.permissions(); - p.set_readonly(true); - check!(fs::set_permissions(&input, p)); - check!(fs::copy(&input, &out)); - assert!(check!(out.metadata()).permissions().readonly()); - check!(fs::set_permissions(&input, attr.permissions())); - check!(fs::set_permissions(&out, attr.permissions())); -} - -#[test] -#[cfg(windows)] -fn copy_file_preserves_streams() { - let tmp = tmpdir(); - check!(check!(File::create(tmp.join("in.txt:bunny"))).write("carrot".as_bytes())); - assert_eq!(check!(fs::copy(tmp.join("in.txt"), tmp.join("out.txt"))), 0); - assert_eq!(check!(tmp.join("out.txt").metadata()).len(), 0); - let mut v = Vec::new(); - check!(check!(File::open(tmp.join("out.txt:bunny"))).read_to_end(&mut v)); - assert_eq!(v, b"carrot".to_vec()); -} - -#[test] -fn copy_file_returns_metadata_len() { - let tmp = tmpdir(); - let in_path = tmp.join("in.txt"); - let out_path = tmp.join("out.txt"); - check!(check!(File::create(&in_path)).write(b"lettuce")); - #[cfg(windows)] - check!(check!(File::create(tmp.join("in.txt:bunny"))).write(b"carrot")); - let copied_len = check!(fs::copy(&in_path, &out_path)); - assert_eq!(check!(out_path.metadata()).len(), copied_len); -} - -#[test] -fn copy_file_follows_dst_symlink() { - let tmp = tmpdir(); - if !got_symlink_permission(&tmp) { - return; - }; - - let in_path = tmp.join("in.txt"); - let out_path = tmp.join("out.txt"); - let out_path_symlink = tmp.join("out_symlink.txt"); - - check!(fs::write(&in_path, "foo")); - check!(fs::write(&out_path, "bar")); - check!(symlink_file(&out_path, &out_path_symlink)); - - check!(fs::copy(&in_path, &out_path_symlink)); - - assert!(check!(out_path_symlink.symlink_metadata()).file_type().is_symlink()); - assert_eq!(check!(fs::read(&out_path_symlink)), b"foo".to_vec()); - assert_eq!(check!(fs::read(&out_path)), b"foo".to_vec()); -} - -#[test] -fn symlinks_work() { - let tmpdir = tmpdir(); - if !got_symlink_permission(&tmpdir) { - return; - }; - - let input = tmpdir.join("in.txt"); - let out = tmpdir.join("out.txt"); - - check!(check!(File::create(&input)).write("foobar".as_bytes())); - check!(symlink_file(&input, &out)); - assert!(check!(out.symlink_metadata()).file_type().is_symlink()); - assert_eq!(check!(fs::metadata(&out)).len(), check!(fs::metadata(&input)).len()); - let mut v = Vec::new(); - check!(check!(File::open(&out)).read_to_end(&mut v)); - assert_eq!(v, b"foobar".to_vec()); -} - -#[test] -fn symlink_noexist() { - // Symlinks can point to things that don't exist - let tmpdir = tmpdir(); - if !got_symlink_permission(&tmpdir) { - return; - }; - - // Use a relative path for testing. Symlinks get normalized by Windows, - // so we might not get the same path back for absolute paths - check!(symlink_file(&"foo", &tmpdir.join("bar"))); - assert_eq!(check!(fs::read_link(&tmpdir.join("bar"))).to_str().unwrap(), "foo"); -} - -#[test] -fn read_link() { - let tmpdir = tmpdir(); - if cfg!(windows) { - // directory symlink - assert_eq!(check!(fs::read_link(r"C:\Users\All Users")), Path::new(r"C:\ProgramData")); - // junction - assert_eq!(check!(fs::read_link(r"C:\Users\Default User")), Path::new(r"C:\Users\Default")); - // junction with special permissions - // Since not all localized windows versions contain the folder "Documents and Settings" in english, - // we will briefly check, if it exists and otherwise skip the test. Except during CI we will always execute the test. - if Path::new(r"C:\Documents and Settings\").exists() || env::var_os("CI").is_some() { - assert_eq!( - check!(fs::read_link(r"C:\Documents and Settings\")), - Path::new(r"C:\Users") - ); - } - // Check that readlink works with non-drive paths on Windows. - let link = tmpdir.join("link_unc"); - if got_symlink_permission(&tmpdir) { - check!(symlink_dir(r"\\localhost\c$\", &link)); - assert_eq!(check!(fs::read_link(&link)), Path::new(r"\\localhost\c$\")); - }; - } - let link = tmpdir.join("link"); - if !got_symlink_permission(&tmpdir) { - return; - }; - check!(symlink_file(&"foo", &link)); - assert_eq!(check!(fs::read_link(&link)).to_str().unwrap(), "foo"); -} - -#[test] -fn readlink_not_symlink() { - let tmpdir = tmpdir(); - match fs::read_link(tmpdir.path()) { - Ok(..) => panic!("wanted a failure"), - Err(..) => {} - } -} - -#[test] -#[cfg_attr(target_os = "android", ignore)] // Android SELinux rules prevent creating hardlinks -fn links_work() { - let tmpdir = tmpdir(); - let input = tmpdir.join("in.txt"); - let out = tmpdir.join("out.txt"); - - check!(check!(File::create(&input)).write("foobar".as_bytes())); - check!(fs::hard_link(&input, &out)); - assert_eq!(check!(fs::metadata(&out)).len(), check!(fs::metadata(&input)).len()); - assert_eq!(check!(fs::metadata(&out)).len(), check!(input.metadata()).len()); - let mut v = Vec::new(); - check!(check!(File::open(&out)).read_to_end(&mut v)); - assert_eq!(v, b"foobar".to_vec()); - - // can't link to yourself - match fs::hard_link(&input, &input) { - Ok(..) => panic!("wanted a failure"), - Err(..) => {} - } - // can't link to something that doesn't exist - match fs::hard_link(&tmpdir.join("foo"), &tmpdir.join("bar")) { - Ok(..) => panic!("wanted a failure"), - Err(..) => {} - } -} - -#[test] -fn chmod_works() { - let tmpdir = tmpdir(); - let file = tmpdir.join("in.txt"); - - check!(File::create(&file)); - let attr = check!(fs::metadata(&file)); - assert!(!attr.permissions().readonly()); - let mut p = attr.permissions(); - p.set_readonly(true); - check!(fs::set_permissions(&file, p.clone())); - let attr = check!(fs::metadata(&file)); - assert!(attr.permissions().readonly()); - - match fs::set_permissions(&tmpdir.join("foo"), p.clone()) { - Ok(..) => panic!("wanted an error"), - Err(..) => {} - } - - p.set_readonly(false); - check!(fs::set_permissions(&file, p)); -} - -#[test] -fn fchmod_works() { - let tmpdir = tmpdir(); - let path = tmpdir.join("in.txt"); - - let file = check!(File::create(&path)); - let attr = check!(fs::metadata(&path)); - assert!(!attr.permissions().readonly()); - let mut p = attr.permissions(); - p.set_readonly(true); - check!(file.set_permissions(p.clone())); - let attr = check!(fs::metadata(&path)); - assert!(attr.permissions().readonly()); - - p.set_readonly(false); - check!(file.set_permissions(p)); -} - -#[test] -fn sync_doesnt_kill_anything() { - let tmpdir = tmpdir(); - let path = tmpdir.join("in.txt"); - - let mut file = check!(File::create(&path)); - check!(file.sync_all()); - check!(file.sync_data()); - check!(file.write(b"foo")); - check!(file.sync_all()); - check!(file.sync_data()); -} - -#[test] -fn truncate_works() { - let tmpdir = tmpdir(); - let path = tmpdir.join("in.txt"); - - let mut file = check!(File::create(&path)); - check!(file.write(b"foo")); - check!(file.sync_all()); - - // Do some simple things with truncation - assert_eq!(check!(file.metadata()).len(), 3); - check!(file.set_len(10)); - assert_eq!(check!(file.metadata()).len(), 10); - check!(file.write(b"bar")); - check!(file.sync_all()); - assert_eq!(check!(file.metadata()).len(), 10); - - let mut v = Vec::new(); - check!(check!(File::open(&path)).read_to_end(&mut v)); - assert_eq!(v, b"foobar\0\0\0\0".to_vec()); - - // Truncate to a smaller length, don't seek, and then write something. - // Ensure that the intermediate zeroes are all filled in (we have `seek`ed - // past the end of the file). - check!(file.set_len(2)); - assert_eq!(check!(file.metadata()).len(), 2); - check!(file.write(b"wut")); - check!(file.sync_all()); - assert_eq!(check!(file.metadata()).len(), 9); - let mut v = Vec::new(); - check!(check!(File::open(&path)).read_to_end(&mut v)); - assert_eq!(v, b"fo\0\0\0\0wut".to_vec()); -} - -#[test] -fn open_flavors() { - use crate::fs::OpenOptions as OO; - fn c(t: &T) -> T { - t.clone() - } - - let tmpdir = tmpdir(); - - let mut r = OO::new(); - r.read(true); - let mut w = OO::new(); - w.write(true); - let mut rw = OO::new(); - rw.read(true).write(true); - let mut a = OO::new(); - a.append(true); - let mut ra = OO::new(); - ra.read(true).append(true); - - #[cfg(windows)] - let invalid_options = 87; // ERROR_INVALID_PARAMETER - #[cfg(all(unix, not(target_os = "vxworks")))] - let invalid_options = "Invalid argument"; - #[cfg(target_os = "vxworks")] - let invalid_options = "invalid argument"; - - // Test various combinations of creation modes and access modes. - // - // Allowed: - // creation mode | read | write | read-write | append | read-append | - // :-----------------------|:-----:|:-----:|:----------:|:------:|:-----------:| - // not set (open existing) | X | X | X | X | X | - // create | | X | X | X | X | - // truncate | | X | X | | | - // create and truncate | | X | X | | | - // create_new | | X | X | X | X | - // - // tested in reverse order, so 'create_new' creates the file, and 'open existing' opens it. - - // write-only - check!(c(&w).create_new(true).open(&tmpdir.join("a"))); - check!(c(&w).create(true).truncate(true).open(&tmpdir.join("a"))); - check!(c(&w).truncate(true).open(&tmpdir.join("a"))); - check!(c(&w).create(true).open(&tmpdir.join("a"))); - check!(c(&w).open(&tmpdir.join("a"))); - - // read-only - error!(c(&r).create_new(true).open(&tmpdir.join("b")), invalid_options); - error!(c(&r).create(true).truncate(true).open(&tmpdir.join("b")), invalid_options); - error!(c(&r).truncate(true).open(&tmpdir.join("b")), invalid_options); - error!(c(&r).create(true).open(&tmpdir.join("b")), invalid_options); - check!(c(&r).open(&tmpdir.join("a"))); // try opening the file created with write_only - - // read-write - check!(c(&rw).create_new(true).open(&tmpdir.join("c"))); - check!(c(&rw).create(true).truncate(true).open(&tmpdir.join("c"))); - check!(c(&rw).truncate(true).open(&tmpdir.join("c"))); - check!(c(&rw).create(true).open(&tmpdir.join("c"))); - check!(c(&rw).open(&tmpdir.join("c"))); - - // append - check!(c(&a).create_new(true).open(&tmpdir.join("d"))); - error!(c(&a).create(true).truncate(true).open(&tmpdir.join("d")), invalid_options); - error!(c(&a).truncate(true).open(&tmpdir.join("d")), invalid_options); - check!(c(&a).create(true).open(&tmpdir.join("d"))); - check!(c(&a).open(&tmpdir.join("d"))); - - // read-append - check!(c(&ra).create_new(true).open(&tmpdir.join("e"))); - error!(c(&ra).create(true).truncate(true).open(&tmpdir.join("e")), invalid_options); - error!(c(&ra).truncate(true).open(&tmpdir.join("e")), invalid_options); - check!(c(&ra).create(true).open(&tmpdir.join("e"))); - check!(c(&ra).open(&tmpdir.join("e"))); - - // Test opening a file without setting an access mode - let mut blank = OO::new(); - error!(blank.create(true).open(&tmpdir.join("f")), invalid_options); - - // Test write works - check!(check!(File::create(&tmpdir.join("h"))).write("foobar".as_bytes())); - - // Test write fails for read-only - check!(r.open(&tmpdir.join("h"))); - { - let mut f = check!(r.open(&tmpdir.join("h"))); - assert!(f.write("wut".as_bytes()).is_err()); - } - - // Test write overwrites - { - let mut f = check!(c(&w).open(&tmpdir.join("h"))); - check!(f.write("baz".as_bytes())); - } - { - let mut f = check!(c(&r).open(&tmpdir.join("h"))); - let mut b = vec![0; 6]; - check!(f.read(&mut b)); - assert_eq!(b, "bazbar".as_bytes()); - } - - // Test truncate works - { - let mut f = check!(c(&w).truncate(true).open(&tmpdir.join("h"))); - check!(f.write("foo".as_bytes())); - } - assert_eq!(check!(fs::metadata(&tmpdir.join("h"))).len(), 3); - - // Test append works - assert_eq!(check!(fs::metadata(&tmpdir.join("h"))).len(), 3); - { - let mut f = check!(c(&a).open(&tmpdir.join("h"))); - check!(f.write("bar".as_bytes())); - } - assert_eq!(check!(fs::metadata(&tmpdir.join("h"))).len(), 6); - - // Test .append(true) equals .write(true).append(true) - { - let mut f = check!(c(&w).append(true).open(&tmpdir.join("h"))); - check!(f.write("baz".as_bytes())); - } - assert_eq!(check!(fs::metadata(&tmpdir.join("h"))).len(), 9); -} - -#[test] -fn _assert_send_sync() { - fn _assert_send_sync() {} - _assert_send_sync::(); -} - -#[test] -fn binary_file() { - let mut bytes = [0; 1024]; - crate::test_helpers::test_rng().fill_bytes(&mut bytes); - - let tmpdir = tmpdir(); - - check!(check!(File::create(&tmpdir.join("test"))).write(&bytes)); - let mut v = Vec::new(); - check!(check!(File::open(&tmpdir.join("test"))).read_to_end(&mut v)); - assert!(v == &bytes[..]); -} - -#[test] -fn write_then_read() { - let mut bytes = [0; 1024]; - crate::test_helpers::test_rng().fill_bytes(&mut bytes); - - let tmpdir = tmpdir(); - - check!(fs::write(&tmpdir.join("test"), &bytes[..])); - let v = check!(fs::read(&tmpdir.join("test"))); - assert!(v == &bytes[..]); - - check!(fs::write(&tmpdir.join("not-utf8"), &[0xFF])); - error_contains!( - fs::read_to_string(&tmpdir.join("not-utf8")), - "stream did not contain valid UTF-8" - ); - - let s = "𐁁𐀓𐀠𐀴𐀍"; - check!(fs::write(&tmpdir.join("utf8"), s.as_bytes())); - let string = check!(fs::read_to_string(&tmpdir.join("utf8"))); - assert_eq!(string, s); -} - -#[test] -fn file_try_clone() { - let tmpdir = tmpdir(); - - let mut f1 = - check!(OpenOptions::new().read(true).write(true).create(true).open(&tmpdir.join("test"))); - let mut f2 = check!(f1.try_clone()); - - check!(f1.write_all(b"hello world")); - check!(f1.seek(SeekFrom::Start(2))); - - let mut buf = vec![]; - check!(f2.read_to_end(&mut buf)); - assert_eq!(buf, b"llo world"); - drop(f2); - - check!(f1.write_all(b"!")); -} - -#[test] -#[cfg(not(windows))] -fn unlink_readonly() { - let tmpdir = tmpdir(); - let path = tmpdir.join("file"); - check!(File::create(&path)); - let mut perm = check!(fs::metadata(&path)).permissions(); - perm.set_readonly(true); - check!(fs::set_permissions(&path, perm)); - check!(fs::remove_file(&path)); -} - -#[test] -fn mkdir_trailing_slash() { - let tmpdir = tmpdir(); - let path = tmpdir.join("file"); - check!(fs::create_dir_all(&path.join("a/"))); -} - -#[test] -fn canonicalize_works_simple() { - let tmpdir = tmpdir(); - let tmpdir = fs::canonicalize(tmpdir.path()).unwrap(); - let file = tmpdir.join("test"); - File::create(&file).unwrap(); - assert_eq!(fs::canonicalize(&file).unwrap(), file); -} - -#[test] -fn realpath_works() { - let tmpdir = tmpdir(); - if !got_symlink_permission(&tmpdir) { - return; - }; - - let tmpdir = fs::canonicalize(tmpdir.path()).unwrap(); - let file = tmpdir.join("test"); - let dir = tmpdir.join("test2"); - let link = dir.join("link"); - let linkdir = tmpdir.join("test3"); - - File::create(&file).unwrap(); - fs::create_dir(&dir).unwrap(); - symlink_file(&file, &link).unwrap(); - symlink_dir(&dir, &linkdir).unwrap(); - - assert!(link.symlink_metadata().unwrap().file_type().is_symlink()); - - assert_eq!(fs::canonicalize(&tmpdir).unwrap(), tmpdir); - assert_eq!(fs::canonicalize(&file).unwrap(), file); - assert_eq!(fs::canonicalize(&link).unwrap(), file); - assert_eq!(fs::canonicalize(&linkdir).unwrap(), dir); - assert_eq!(fs::canonicalize(&linkdir.join("link")).unwrap(), file); -} - -#[test] -fn realpath_works_tricky() { - let tmpdir = tmpdir(); - if !got_symlink_permission(&tmpdir) { - return; - }; - - let tmpdir = fs::canonicalize(tmpdir.path()).unwrap(); - let a = tmpdir.join("a"); - let b = a.join("b"); - let c = b.join("c"); - let d = a.join("d"); - let e = d.join("e"); - let f = a.join("f"); - - fs::create_dir_all(&b).unwrap(); - fs::create_dir_all(&d).unwrap(); - File::create(&f).unwrap(); - if cfg!(not(windows)) { - symlink_file("../d/e", &c).unwrap(); - symlink_file("../f", &e).unwrap(); - } - if cfg!(windows) { - symlink_file(r"..\d\e", &c).unwrap(); - symlink_file(r"..\f", &e).unwrap(); - } - - assert_eq!(fs::canonicalize(&c).unwrap(), f); - assert_eq!(fs::canonicalize(&e).unwrap(), f); -} - -#[test] -fn dir_entry_methods() { - let tmpdir = tmpdir(); - - fs::create_dir_all(&tmpdir.join("a")).unwrap(); - File::create(&tmpdir.join("b")).unwrap(); - - for file in tmpdir.path().read_dir().unwrap().map(|f| f.unwrap()) { - let fname = file.file_name(); - match fname.to_str() { - Some("a") => { - assert!(file.file_type().unwrap().is_dir()); - assert!(file.metadata().unwrap().is_dir()); - } - Some("b") => { - assert!(file.file_type().unwrap().is_file()); - assert!(file.metadata().unwrap().is_file()); - } - f => panic!("unknown file name: {f:?}"), - } - } -} - -#[test] -fn dir_entry_debug() { - let tmpdir = tmpdir(); - File::create(&tmpdir.join("b")).unwrap(); - let mut read_dir = tmpdir.path().read_dir().unwrap(); - let dir_entry = read_dir.next().unwrap().unwrap(); - let actual = format!("{dir_entry:?}"); - let expected = format!("DirEntry({:?})", dir_entry.0.path()); - assert_eq!(actual, expected); -} - -#[test] -fn read_dir_not_found() { - let res = fs::read_dir("/path/that/does/not/exist"); - assert_eq!(res.err().unwrap().kind(), ErrorKind::NotFound); -} - -#[test] -fn file_open_not_found() { - let res = File::open("/path/that/does/not/exist"); - assert_eq!(res.err().unwrap().kind(), ErrorKind::NotFound); -} - -#[test] -fn create_dir_all_with_junctions() { - let tmpdir = tmpdir(); - let target = tmpdir.join("target"); - - let junction = tmpdir.join("junction"); - let b = junction.join("a/b"); - - let link = tmpdir.join("link"); - let d = link.join("c/d"); - - fs::create_dir(&target).unwrap(); - - check!(junction_point(&target, &junction)); - check!(fs::create_dir_all(&b)); - // the junction itself is not a directory, but `is_dir()` on a Path - // follows links - assert!(junction.is_dir()); - assert!(b.exists()); - - if !got_symlink_permission(&tmpdir) { - return; - }; - check!(symlink_dir(&target, &link)); - check!(fs::create_dir_all(&d)); - assert!(link.is_dir()); - assert!(d.exists()); -} - -#[test] -fn metadata_access_times() { - let tmpdir = tmpdir(); - - let b = tmpdir.join("b"); - File::create(&b).unwrap(); - - let a = check!(fs::metadata(&tmpdir.path())); - let b = check!(fs::metadata(&b)); - - assert_eq!(check!(a.accessed()), check!(a.accessed())); - assert_eq!(check!(a.modified()), check!(a.modified())); - assert_eq!(check!(b.accessed()), check!(b.modified())); - - if cfg!(target_os = "macos") || cfg!(target_os = "windows") { - check!(a.created()); - check!(b.created()); - } - - if cfg!(target_os = "linux") { - // Not always available - match (a.created(), b.created()) { - (Ok(t1), Ok(t2)) => assert!(t1 <= t2), - (Err(e1), Err(e2)) - if e1.kind() == ErrorKind::Uncategorized - && e2.kind() == ErrorKind::Uncategorized - || e1.kind() == ErrorKind::Unsupported - && e2.kind() == ErrorKind::Unsupported => {} - (a, b) => { - panic!("creation time must be always supported or not supported: {a:?} {b:?}") - } - } - } -} - -/// Test creating hard links to symlinks. -#[test] -#[cfg_attr(target_os = "android", ignore)] // Android SELinux rules prevent creating hardlinks -fn symlink_hard_link() { - let tmpdir = tmpdir(); - if !got_symlink_permission(&tmpdir) { - return; - }; - if !able_to_not_follow_symlinks_while_hard_linking() { - return; - } - - // Create "file", a file. - check!(fs::File::create(tmpdir.join("file"))); - - // Create "symlink", a symlink to "file". - check!(symlink_file("file", tmpdir.join("symlink"))); - - // Create "hard_link", a hard link to "symlink". - check!(fs::hard_link(tmpdir.join("symlink"), tmpdir.join("hard_link"))); - - // "hard_link" should appear as a symlink. - assert!(check!(fs::symlink_metadata(tmpdir.join("hard_link"))).file_type().is_symlink()); - - // We should be able to open "file" via any of the above names. - let _ = check!(fs::File::open(tmpdir.join("file"))); - assert!(fs::File::open(tmpdir.join("file.renamed")).is_err()); - let _ = check!(fs::File::open(tmpdir.join("symlink"))); - let _ = check!(fs::File::open(tmpdir.join("hard_link"))); - - // Rename "file" to "file.renamed". - check!(fs::rename(tmpdir.join("file"), tmpdir.join("file.renamed"))); - - // Now, the symlink and the hard link should be dangling. - assert!(fs::File::open(tmpdir.join("file")).is_err()); - let _ = check!(fs::File::open(tmpdir.join("file.renamed"))); - assert!(fs::File::open(tmpdir.join("symlink")).is_err()); - assert!(fs::File::open(tmpdir.join("hard_link")).is_err()); - - // The symlink and the hard link should both still point to "file". - assert!(fs::read_link(tmpdir.join("file")).is_err()); - assert!(fs::read_link(tmpdir.join("file.renamed")).is_err()); - assert_eq!(check!(fs::read_link(tmpdir.join("symlink"))), Path::new("file")); - assert_eq!(check!(fs::read_link(tmpdir.join("hard_link"))), Path::new("file")); - - // Remove "file.renamed". - check!(fs::remove_file(tmpdir.join("file.renamed"))); - - // Now, we can't open the file by any name. - assert!(fs::File::open(tmpdir.join("file")).is_err()); - assert!(fs::File::open(tmpdir.join("file.renamed")).is_err()); - assert!(fs::File::open(tmpdir.join("symlink")).is_err()); - assert!(fs::File::open(tmpdir.join("hard_link")).is_err()); - - // "hard_link" should still appear as a symlink. - assert!(check!(fs::symlink_metadata(tmpdir.join("hard_link"))).file_type().is_symlink()); -} - -/// Ensure `fs::create_dir` works on Windows with longer paths. -#[test] -#[cfg(windows)] -fn create_dir_long_paths() { - use crate::{ffi::OsStr, iter, os::windows::ffi::OsStrExt}; - const PATH_LEN: usize = 247; - - let tmpdir = tmpdir(); - let mut path = tmpdir.path().to_path_buf(); - path.push("a"); - let mut path = path.into_os_string(); - - let utf16_len = path.encode_wide().count(); - if utf16_len >= PATH_LEN { - // Skip the test in the unlikely event the local user has a long temp directory path. - // This should not affect CI. - return; - } - // Increase the length of the path. - path.extend(iter::repeat(OsStr::new("a")).take(PATH_LEN - utf16_len)); - - // This should succeed. - fs::create_dir(&path).unwrap(); - - // This will fail if the path isn't converted to verbatim. - path.push("a"); - fs::create_dir(&path).unwrap(); - - // #90940: Ensure an empty path returns the "Not Found" error. - let path = Path::new(""); - assert_eq!(path.canonicalize().unwrap_err().kind(), crate::io::ErrorKind::NotFound); -} - -/// Ensure ReadDir works on large directories. -/// Regression test for https://github.com/rust-lang/rust/issues/93384. -#[test] -fn read_large_dir() { - let tmpdir = tmpdir(); - - let count = 32 * 1024; - for i in 0..count { - check!(fs::File::create(tmpdir.join(&i.to_string()))); - } - - for entry in fs::read_dir(tmpdir.path()).unwrap() { - entry.unwrap(); - } -} - -/// Test the fallback for getting the metadata of files like hiberfil.sys that -/// Windows holds a special lock on, preventing normal means of querying -/// metadata. See #96980. -/// -/// Note this fails in CI because `hiberfil.sys` does not actually exist there. -/// Therefore it's marked as ignored. -#[test] -#[ignore] -#[cfg(windows)] -fn hiberfil_sys() { - let hiberfil = Path::new(r"C:\hiberfil.sys"); - assert_eq!(true, hiberfil.try_exists().unwrap()); - fs::symlink_metadata(hiberfil).unwrap(); - fs::metadata(hiberfil).unwrap(); - assert_eq!(true, hiberfil.exists()); -} - -/// Test that two different ways of obtaining the FileType give the same result. -/// Cf. https://github.com/rust-lang/rust/issues/104900 -#[test] -fn test_eq_direntry_metadata() { - let tmpdir = tmpdir(); - let file_path = tmpdir.join("file"); - File::create(file_path).unwrap(); - for e in fs::read_dir(tmpdir.path()).unwrap() { - let e = e.unwrap(); - let p = e.path(); - let ft1 = e.file_type().unwrap(); - let ft2 = p.metadata().unwrap().file_type(); - assert_eq!(ft1, ft2); - } -} - -/// Regression test for https://github.com/rust-lang/rust/issues/50619. -#[test] -#[cfg(target_os = "linux")] -fn test_read_dir_infinite_loop() { - use crate::io::ErrorKind; - use crate::process::Command; - - // Create a zombie child process - let Ok(mut child) = Command::new("echo").spawn() else { return }; - - // Make sure the process is (un)dead - match child.kill() { - // InvalidInput means the child already exited - Err(e) if e.kind() != ErrorKind::InvalidInput => return, - _ => {} - } - - // open() on this path will succeed, but readdir() will fail - let id = child.id(); - let path = format!("/proc/{id}/net"); - - // Skip the test if we can't open the directory in the first place - let Ok(dir) = fs::read_dir(path) else { return }; - - // Check for duplicate errors - assert!(dir.filter(|e| e.is_err()).take(2).count() < 2); -} - -#[test] -fn rename_directory() { - let tmpdir = tmpdir(); - let old_path = tmpdir.join("foo/bar/baz"); - fs::create_dir_all(&old_path).unwrap(); - let test_file = &old_path.join("temp.txt"); - - File::create(test_file).unwrap(); - - let new_path = tmpdir.join("quux/blat"); - fs::create_dir_all(&new_path).unwrap(); - fs::rename(&old_path, &new_path.join("newdir")).unwrap(); - assert!(new_path.join("newdir").is_dir()); - assert!(new_path.join("newdir/temp.txt").exists()); -} - -#[test] -fn test_file_times() { - #[cfg(target_os = "ios")] - use crate::os::ios::fs::FileTimesExt; - #[cfg(target_os = "macos")] - use crate::os::macos::fs::FileTimesExt; - #[cfg(target_os = "tvos")] - use crate::os::tvos::fs::FileTimesExt; - #[cfg(target_os = "visionos")] - use crate::os::visionos::fs::FileTimesExt; - #[cfg(target_os = "watchos")] - use crate::os::watchos::fs::FileTimesExt; - #[cfg(windows)] - use crate::os::windows::fs::FileTimesExt; - - let tmp = tmpdir(); - let file = File::create(tmp.join("foo")).unwrap(); - let mut times = FileTimes::new(); - let accessed = SystemTime::UNIX_EPOCH + Duration::from_secs(12345); - let modified = SystemTime::UNIX_EPOCH + Duration::from_secs(54321); - times = times.set_accessed(accessed).set_modified(modified); - #[cfg(any(windows, target_vendor = "apple"))] - let created = SystemTime::UNIX_EPOCH + Duration::from_secs(32123); - #[cfg(any(windows, target_vendor = "apple"))] - { - times = times.set_created(created); - } - match file.set_times(times) { - // Allow unsupported errors on platforms which don't support setting times. - #[cfg(not(any( - windows, - all( - unix, - not(any( - target_os = "android", - target_os = "redox", - target_os = "espidf", - target_os = "horizon" - )) - ) - )))] - Err(e) if e.kind() == ErrorKind::Unsupported => return, - Err(e) => panic!("error setting file times: {e:?}"), - Ok(_) => {} - } - let metadata = file.metadata().unwrap(); - assert_eq!(metadata.accessed().unwrap(), accessed); - assert_eq!(metadata.modified().unwrap(), modified); - #[cfg(any(windows, target_vendor = "apple"))] - { - assert_eq!(metadata.created().unwrap(), created); - } -} - -#[test] -#[cfg(target_vendor = "apple")] -fn test_file_times_pre_epoch_with_nanos() { - #[cfg(target_os = "ios")] - use crate::os::ios::fs::FileTimesExt; - #[cfg(target_os = "macos")] - use crate::os::macos::fs::FileTimesExt; - #[cfg(target_os = "tvos")] - use crate::os::tvos::fs::FileTimesExt; - #[cfg(target_os = "visionos")] - use crate::os::visionos::fs::FileTimesExt; - #[cfg(target_os = "watchos")] - use crate::os::watchos::fs::FileTimesExt; - - let tmp = tmpdir(); - let file = File::create(tmp.join("foo")).unwrap(); - - for (accessed, modified, created) in [ - // The first round is to set filetimes to something we know works, but this time - // it's validated with nanoseconds as well which probe the numeric boundary. - ( - SystemTime::UNIX_EPOCH + Duration::new(12345, 1), - SystemTime::UNIX_EPOCH + Duration::new(54321, 100_000_000), - SystemTime::UNIX_EPOCH + Duration::new(32123, 999_999_999), - ), - // The second rounds uses pre-epoch dates along with nanoseconds that probe - // the numeric boundary. - ( - SystemTime::UNIX_EPOCH - Duration::new(1, 1), - SystemTime::UNIX_EPOCH - Duration::new(60, 100_000_000), - SystemTime::UNIX_EPOCH - Duration::new(3600, 999_999_999), - ), - ] { - let mut times = FileTimes::new(); - times = times.set_accessed(accessed).set_modified(modified).set_created(created); - file.set_times(times).unwrap(); - - let metadata = file.metadata().unwrap(); - assert_eq!(metadata.accessed().unwrap(), accessed); - assert_eq!(metadata.modified().unwrap(), modified); - assert_eq!(metadata.created().unwrap(), created); - } -} - -#[test] -#[cfg(windows)] -fn windows_unix_socket_exists() { - use crate::sys::{c, net}; - use crate::{mem, ptr}; - - let tmp = tmpdir(); - let socket_path = tmp.join("socket"); - - // std doesn't currently support Unix sockets on Windows so manually create one here. - net::init(); - unsafe { - let socket = c::WSASocketW( - c::AF_UNIX as i32, - c::SOCK_STREAM, - 0, - ptr::null_mut(), - 0, - c::WSA_FLAG_OVERLAPPED | c::WSA_FLAG_NO_HANDLE_INHERIT, - ); - // AF_UNIX is not supported on earlier versions of Windows, - // so skip this test if it's unsupported and we're not in CI. - if socket == c::INVALID_SOCKET { - let error = c::WSAGetLastError(); - if env::var_os("CI").is_none() && error == c::WSAEAFNOSUPPORT { - return; - } else { - panic!("Creating AF_UNIX socket failed (OS error {error})"); - } - } - let mut addr = c::SOCKADDR_UN { sun_family: c::AF_UNIX, sun_path: mem::zeroed() }; - let bytes = socket_path.as_os_str().as_encoded_bytes(); - let bytes = core::slice::from_raw_parts(bytes.as_ptr().cast::(), bytes.len()); - addr.sun_path[..bytes.len()].copy_from_slice(bytes); - let len = mem::size_of_val(&addr) as i32; - let result = c::bind(socket, ptr::addr_of!(addr).cast::(), len); - c::closesocket(socket); - assert_eq!(result, 0); - } - // Make sure all ways of testing a file exist work for a Unix socket. - assert_eq!(socket_path.exists(), true); - assert_eq!(socket_path.try_exists().unwrap(), true); - assert_eq!(socket_path.metadata().is_ok(), true); -} - -#[cfg(windows)] -#[test] -fn test_hidden_file_truncation() { - // Make sure that File::create works on an existing hidden file. See #115745. - let tmpdir = tmpdir(); - let path = tmpdir.join("hidden_file.txt"); - - // Create a hidden file. - const FILE_ATTRIBUTE_HIDDEN: u32 = 2; - let mut file = OpenOptions::new() - .write(true) - .create_new(true) - .attributes(FILE_ATTRIBUTE_HIDDEN) - .open(&path) - .unwrap(); - file.write("hidden world!".as_bytes()).unwrap(); - file.flush().unwrap(); - drop(file); - - // Create a new file by truncating the existing one. - let file = File::create(&path).unwrap(); - let metadata = file.metadata().unwrap(); - assert_eq!(metadata.len(), 0); -} diff --git a/library/std/src/hash/mod.rs b/library/std/src/hash/mod.rs deleted file mode 100644 index e5ef9e3359736..0000000000000 --- a/library/std/src/hash/mod.rs +++ /dev/null @@ -1,91 +0,0 @@ -//! Generic hashing support. -//! -//! This module provides a generic way to compute the [hash] of a value. -//! Hashes are most commonly used with [`HashMap`] and [`HashSet`]. -//! -//! [hash]: https://en.wikipedia.org/wiki/Hash_function -//! [`HashMap`]: ../../std/collections/struct.HashMap.html -//! [`HashSet`]: ../../std/collections/struct.HashSet.html -//! -//! The simplest way to make a type hashable is to use `#[derive(Hash)]`: -//! -//! # Examples -//! -//! ```rust -//! use std::hash::{DefaultHasher, Hash, Hasher}; -//! -//! #[derive(Hash)] -//! struct Person { -//! id: u32, -//! name: String, -//! phone: u64, -//! } -//! -//! let person1 = Person { -//! id: 5, -//! name: "Janet".to_string(), -//! phone: 555_666_7777, -//! }; -//! let person2 = Person { -//! id: 5, -//! name: "Bob".to_string(), -//! phone: 555_666_7777, -//! }; -//! -//! assert!(calculate_hash(&person1) != calculate_hash(&person2)); -//! -//! fn calculate_hash(t: &T) -> u64 { -//! let mut s = DefaultHasher::new(); -//! t.hash(&mut s); -//! s.finish() -//! } -//! ``` -//! -//! If you need more control over how a value is hashed, you need to implement -//! the [`Hash`] trait: -//! -//! ```rust -//! use std::hash::{DefaultHasher, Hash, Hasher}; -//! -//! struct Person { -//! id: u32, -//! # #[allow(dead_code)] -//! name: String, -//! phone: u64, -//! } -//! -//! impl Hash for Person { -//! fn hash(&self, state: &mut H) { -//! self.id.hash(state); -//! self.phone.hash(state); -//! } -//! } -//! -//! let person1 = Person { -//! id: 5, -//! name: "Janet".to_string(), -//! phone: 555_666_7777, -//! }; -//! let person2 = Person { -//! id: 5, -//! name: "Bob".to_string(), -//! phone: 555_666_7777, -//! }; -//! -//! assert_eq!(calculate_hash(&person1), calculate_hash(&person2)); -//! -//! fn calculate_hash(t: &T) -> u64 { -//! let mut s = DefaultHasher::new(); -//! t.hash(&mut s); -//! s.finish() -//! } -//! ``` -#![stable(feature = "rust1", since = "1.0.0")] - -pub(crate) mod random; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::hash::*; - -#[stable(feature = "std_hash_exports", since = "1.76.0")] -pub use self::random::{DefaultHasher, RandomState}; diff --git a/library/std/src/hash/random.rs b/library/std/src/hash/random.rs deleted file mode 100644 index a1ccbb25369bf..0000000000000 --- a/library/std/src/hash/random.rs +++ /dev/null @@ -1,161 +0,0 @@ -//! This module exists to isolate [`RandomState`] and [`DefaultHasher`] outside of the -//! [`collections`] module without actually publicly exporting them, so that parts of that -//! implementation can more easily be moved to the [`alloc`] crate. -//! -//! Although its items are public and contain stability attributes, they can't actually be accessed -//! outside this crate. -//! -//! [`collections`]: crate::collections -#[allow(deprecated)] -use super::{BuildHasher, Hasher, SipHasher13}; -use crate::cell::Cell; -use crate::fmt; -use crate::sys; - -/// `RandomState` is the default state for [`HashMap`] types. -/// -/// A particular instance `RandomState` will create the same instances of -/// [`Hasher`], but the hashers created by two different `RandomState` -/// instances are unlikely to produce the same result for the same values. -/// -/// [`HashMap`]: crate::collections::HashMap -/// -/// # Examples -/// -/// ``` -/// use std::collections::HashMap; -/// use std::hash::RandomState; -/// -/// let s = RandomState::new(); -/// let mut map = HashMap::with_hasher(s); -/// map.insert(1, 2); -/// ``` -#[stable(feature = "hashmap_build_hasher", since = "1.7.0")] -#[derive(Clone)] -pub struct RandomState { - k0: u64, - k1: u64, -} - -impl RandomState { - /// Constructs a new `RandomState` that is initialized with random keys. - /// - /// # Examples - /// - /// ``` - /// use std::hash::RandomState; - /// - /// let s = RandomState::new(); - /// ``` - #[inline] - #[allow(deprecated)] - // rand - #[must_use] - #[stable(feature = "hashmap_build_hasher", since = "1.7.0")] - pub fn new() -> RandomState { - // Historically this function did not cache keys from the OS and instead - // simply always called `rand::thread_rng().gen()` twice. In #31356 it - // was discovered, however, that because we re-seed the thread-local RNG - // from the OS periodically that this can cause excessive slowdown when - // many hash maps are created on a thread. To solve this performance - // trap we cache the first set of randomly generated keys per-thread. - // - // Later in #36481 it was discovered that exposing a deterministic - // iteration order allows a form of DOS attack. To counter that we - // increment one of the seeds on every RandomState creation, giving - // every corresponding HashMap a different iteration order. - thread_local!(static KEYS: Cell<(u64, u64)> = { - Cell::new(sys::hashmap_random_keys()) - }); - - KEYS.with(|keys| { - let (k0, k1) = keys.get(); - keys.set((k0.wrapping_add(1), k1)); - RandomState { k0, k1 } - }) - } -} - -#[stable(feature = "hashmap_build_hasher", since = "1.7.0")] -impl BuildHasher for RandomState { - type Hasher = DefaultHasher; - #[inline] - #[allow(deprecated)] - fn build_hasher(&self) -> DefaultHasher { - DefaultHasher(SipHasher13::new_with_keys(self.k0, self.k1)) - } -} - -/// The default [`Hasher`] used by [`RandomState`]. -/// -/// The internal algorithm is not specified, and so it and its hashes should -/// not be relied upon over releases. -#[allow(deprecated)] -#[derive(Clone, Debug)] -#[stable(feature = "hashmap_build_hasher", since = "1.7.0")] -pub struct DefaultHasher(SipHasher13); - -impl DefaultHasher { - /// Creates a new `DefaultHasher`. - /// - /// This hasher is not guaranteed to be the same as all other - /// `DefaultHasher` instances, but is the same as all other `DefaultHasher` - /// instances created through `new` or `default`. - #[stable(feature = "hashmap_default_hasher", since = "1.13.0")] - #[inline] - #[allow(deprecated)] - #[rustc_const_unstable(feature = "const_hash", issue = "104061")] - #[must_use] - pub const fn new() -> DefaultHasher { - DefaultHasher(SipHasher13::new_with_keys(0, 0)) - } -} - -#[stable(feature = "hashmap_default_hasher", since = "1.13.0")] -impl Default for DefaultHasher { - /// Creates a new `DefaultHasher` using [`new`]. - /// See its documentation for more. - /// - /// [`new`]: DefaultHasher::new - #[inline] - fn default() -> DefaultHasher { - DefaultHasher::new() - } -} - -#[stable(feature = "hashmap_default_hasher", since = "1.13.0")] -impl Hasher for DefaultHasher { - // The underlying `SipHasher13` doesn't override the other - // `write_*` methods, so it's ok not to forward them here. - - #[inline] - fn write(&mut self, msg: &[u8]) { - self.0.write(msg) - } - - #[inline] - fn write_str(&mut self, s: &str) { - self.0.write_str(s); - } - - #[inline] - fn finish(&self) -> u64 { - self.0.finish() - } -} - -#[stable(feature = "hashmap_build_hasher", since = "1.7.0")] -impl Default for RandomState { - /// Constructs a new `RandomState`. - #[inline] - fn default() -> RandomState { - RandomState::new() - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for RandomState { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("RandomState").finish_non_exhaustive() - } -} diff --git a/library/std/src/io/buffered/bufreader.rs b/library/std/src/io/buffered/bufreader.rs deleted file mode 100644 index 0cdc49c87d8fc..0000000000000 --- a/library/std/src/io/buffered/bufreader.rs +++ /dev/null @@ -1,534 +0,0 @@ -mod buffer; - -use crate::fmt; -use crate::io::{ - self, uninlined_slow_read_byte, BorrowedCursor, BufRead, IoSliceMut, Read, Seek, SeekFrom, - SizeHint, SpecReadByte, DEFAULT_BUF_SIZE, -}; -use buffer::Buffer; - -/// The `BufReader` struct adds buffering to any reader. -/// -/// It can be excessively inefficient to work directly with a [`Read`] instance. -/// For example, every call to [`read`][`TcpStream::read`] on [`TcpStream`] -/// results in a system call. A `BufReader` performs large, infrequent reads on -/// the underlying [`Read`] and maintains an in-memory buffer of the results. -/// -/// `BufReader` can improve the speed of programs that make *small* and -/// *repeated* read calls to the same file or network socket. It does not -/// help when reading very large amounts at once, or reading just one or a few -/// times. It also provides no advantage when reading from a source that is -/// already in memory, like a [Vec]\. -/// -/// When the `BufReader` is dropped, the contents of its buffer will be -/// discarded. Creating multiple instances of a `BufReader` on the same -/// stream can cause data loss. Reading from the underlying reader after -/// unwrapping the `BufReader` with [`BufReader::into_inner`] can also cause -/// data loss. -/// -/// [`TcpStream::read`]: crate::net::TcpStream::read -/// [`TcpStream`]: crate::net::TcpStream -/// -/// # Examples -/// -/// ```no_run -/// use std::io::prelude::*; -/// use std::io::BufReader; -/// use std::fs::File; -/// -/// fn main() -> std::io::Result<()> { -/// let f = File::open("log.txt")?; -/// let mut reader = BufReader::new(f); -/// -/// let mut line = String::new(); -/// let len = reader.read_line(&mut line)?; -/// println!("First line is {len} bytes long"); -/// Ok(()) -/// } -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub struct BufReader { - buf: Buffer, - inner: R, -} - -impl BufReader { - /// Creates a new `BufReader` with a default buffer capacity. The default is currently 8 KiB, - /// but may change in the future. - /// - /// # Examples - /// - /// ```no_run - /// use std::io::BufReader; - /// use std::fs::File; - /// - /// fn main() -> std::io::Result<()> { - /// let f = File::open("log.txt")?; - /// let reader = BufReader::new(f); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn new(inner: R) -> BufReader { - BufReader::with_capacity(DEFAULT_BUF_SIZE, inner) - } - - /// Creates a new `BufReader` with the specified buffer capacity. - /// - /// # Examples - /// - /// Creating a buffer with ten bytes of capacity: - /// - /// ```no_run - /// use std::io::BufReader; - /// use std::fs::File; - /// - /// fn main() -> std::io::Result<()> { - /// let f = File::open("log.txt")?; - /// let reader = BufReader::with_capacity(10, f); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn with_capacity(capacity: usize, inner: R) -> BufReader { - BufReader { inner, buf: Buffer::with_capacity(capacity) } - } -} - -impl BufReader { - /// Gets a reference to the underlying reader. - /// - /// It is inadvisable to directly read from the underlying reader. - /// - /// # Examples - /// - /// ```no_run - /// use std::io::BufReader; - /// use std::fs::File; - /// - /// fn main() -> std::io::Result<()> { - /// let f1 = File::open("log.txt")?; - /// let reader = BufReader::new(f1); - /// - /// let f2 = reader.get_ref(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn get_ref(&self) -> &R { - &self.inner - } - - /// Gets a mutable reference to the underlying reader. - /// - /// It is inadvisable to directly read from the underlying reader. - /// - /// # Examples - /// - /// ```no_run - /// use std::io::BufReader; - /// use std::fs::File; - /// - /// fn main() -> std::io::Result<()> { - /// let f1 = File::open("log.txt")?; - /// let mut reader = BufReader::new(f1); - /// - /// let f2 = reader.get_mut(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn get_mut(&mut self) -> &mut R { - &mut self.inner - } - - /// Returns a reference to the internally buffered data. - /// - /// Unlike [`fill_buf`], this will not attempt to fill the buffer if it is empty. - /// - /// [`fill_buf`]: BufRead::fill_buf - /// - /// # Examples - /// - /// ```no_run - /// use std::io::{BufReader, BufRead}; - /// use std::fs::File; - /// - /// fn main() -> std::io::Result<()> { - /// let f = File::open("log.txt")?; - /// let mut reader = BufReader::new(f); - /// assert!(reader.buffer().is_empty()); - /// - /// if reader.fill_buf()?.len() > 0 { - /// assert!(!reader.buffer().is_empty()); - /// } - /// Ok(()) - /// } - /// ``` - #[stable(feature = "bufreader_buffer", since = "1.37.0")] - pub fn buffer(&self) -> &[u8] { - self.buf.buffer() - } - - /// Returns the number of bytes the internal buffer can hold at once. - /// - /// # Examples - /// - /// ```no_run - /// use std::io::{BufReader, BufRead}; - /// use std::fs::File; - /// - /// fn main() -> std::io::Result<()> { - /// let f = File::open("log.txt")?; - /// let mut reader = BufReader::new(f); - /// - /// let capacity = reader.capacity(); - /// let buffer = reader.fill_buf()?; - /// assert!(buffer.len() <= capacity); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "buffered_io_capacity", since = "1.46.0")] - pub fn capacity(&self) -> usize { - self.buf.capacity() - } - - /// Unwraps this `BufReader`, returning the underlying reader. - /// - /// Note that any leftover data in the internal buffer is lost. Therefore, - /// a following read from the underlying reader may lead to data loss. - /// - /// # Examples - /// - /// ```no_run - /// use std::io::BufReader; - /// use std::fs::File; - /// - /// fn main() -> std::io::Result<()> { - /// let f1 = File::open("log.txt")?; - /// let reader = BufReader::new(f1); - /// - /// let f2 = reader.into_inner(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn into_inner(self) -> R - where - R: Sized, - { - self.inner - } - - /// Invalidates all data in the internal buffer. - #[inline] - pub(in crate::io) fn discard_buffer(&mut self) { - self.buf.discard_buffer() - } -} - -// This is only used by a test which asserts that the initialization-tracking is correct. -#[cfg(test)] -impl BufReader { - pub fn initialized(&self) -> usize { - self.buf.initialized() - } -} - -impl BufReader { - /// Seeks relative to the current position. If the new position lies within the buffer, - /// the buffer will not be flushed, allowing for more efficient seeks. - /// This method does not return the location of the underlying reader, so the caller - /// must track this information themselves if it is required. - #[stable(feature = "bufreader_seek_relative", since = "1.53.0")] - pub fn seek_relative(&mut self, offset: i64) -> io::Result<()> { - let pos = self.buf.pos() as u64; - if offset < 0 { - if let Some(_) = pos.checked_sub((-offset) as u64) { - self.buf.unconsume((-offset) as usize); - return Ok(()); - } - } else if let Some(new_pos) = pos.checked_add(offset as u64) { - if new_pos <= self.buf.filled() as u64 { - self.buf.consume(offset as usize); - return Ok(()); - } - } - - self.seek(SeekFrom::Current(offset)).map(drop) - } -} - -impl SpecReadByte for BufReader -where - Self: Read, -{ - #[inline] - fn spec_read_byte(&mut self) -> Option> { - let mut byte = 0; - if self.buf.consume_with(1, |claimed| byte = claimed[0]) { - return Some(Ok(byte)); - } - - // Fallback case, only reached once per buffer refill. - uninlined_slow_read_byte(self) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Read for BufReader { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - // If we don't have any buffered data and we're doing a massive read - // (larger than our internal buffer), bypass our internal buffer - // entirely. - if self.buf.pos() == self.buf.filled() && buf.len() >= self.capacity() { - self.discard_buffer(); - return self.inner.read(buf); - } - let mut rem = self.fill_buf()?; - let nread = rem.read(buf)?; - self.consume(nread); - Ok(nread) - } - - fn read_buf(&mut self, mut cursor: BorrowedCursor<'_>) -> io::Result<()> { - // If we don't have any buffered data and we're doing a massive read - // (larger than our internal buffer), bypass our internal buffer - // entirely. - if self.buf.pos() == self.buf.filled() && cursor.capacity() >= self.capacity() { - self.discard_buffer(); - return self.inner.read_buf(cursor); - } - - let prev = cursor.written(); - - let mut rem = self.fill_buf()?; - rem.read_buf(cursor.reborrow())?; - - self.consume(cursor.written() - prev); //slice impl of read_buf known to never unfill buf - - Ok(()) - } - - // Small read_exacts from a BufReader are extremely common when used with a deserializer. - // The default implementation calls read in a loop, which results in surprisingly poor code - // generation for the common path where the buffer has enough bytes to fill the passed-in - // buffer. - fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> { - if self.buf.consume_with(buf.len(), |claimed| buf.copy_from_slice(claimed)) { - return Ok(()); - } - - crate::io::default_read_exact(self, buf) - } - - fn read_buf_exact(&mut self, mut cursor: BorrowedCursor<'_>) -> io::Result<()> { - if self.buf.consume_with(cursor.capacity(), |claimed| cursor.append(claimed)) { - return Ok(()); - } - - crate::io::default_read_buf_exact(self, cursor) - } - - fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - let total_len = bufs.iter().map(|b| b.len()).sum::(); - if self.buf.pos() == self.buf.filled() && total_len >= self.capacity() { - self.discard_buffer(); - return self.inner.read_vectored(bufs); - } - let mut rem = self.fill_buf()?; - let nread = rem.read_vectored(bufs)?; - - self.consume(nread); - Ok(nread) - } - - fn is_read_vectored(&self) -> bool { - self.inner.is_read_vectored() - } - - // The inner reader might have an optimized `read_to_end`. Drain our buffer and then - // delegate to the inner implementation. - fn read_to_end(&mut self, buf: &mut Vec) -> io::Result { - let inner_buf = self.buffer(); - buf.try_reserve(inner_buf.len())?; - buf.extend_from_slice(inner_buf); - let nread = inner_buf.len(); - self.discard_buffer(); - Ok(nread + self.inner.read_to_end(buf)?) - } - - // The inner reader might have an optimized `read_to_end`. Drain our buffer and then - // delegate to the inner implementation. - fn read_to_string(&mut self, buf: &mut String) -> io::Result { - // In the general `else` case below we must read bytes into a side buffer, check - // that they are valid UTF-8, and then append them to `buf`. This requires a - // potentially large memcpy. - // - // If `buf` is empty--the most common case--we can leverage `append_to_string` - // to read directly into `buf`'s internal byte buffer, saving an allocation and - // a memcpy. - if buf.is_empty() { - // `append_to_string`'s safety relies on the buffer only being appended to since - // it only checks the UTF-8 validity of new data. If there were existing content in - // `buf` then an untrustworthy reader (i.e. `self.inner`) could not only append - // bytes but also modify existing bytes and render them invalid. On the other hand, - // if `buf` is empty then by definition any writes must be appends and - // `append_to_string` will validate all of the new bytes. - unsafe { crate::io::append_to_string(buf, |b| self.read_to_end(b)) } - } else { - // We cannot append our byte buffer directly onto the `buf` String as there could - // be an incomplete UTF-8 sequence that has only been partially read. We must read - // everything into a side buffer first and then call `from_utf8` on the complete - // buffer. - let mut bytes = Vec::new(); - self.read_to_end(&mut bytes)?; - let string = crate::str::from_utf8(&bytes).map_err(|_| io::Error::INVALID_UTF8)?; - *buf += string; - Ok(string.len()) - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl BufRead for BufReader { - fn fill_buf(&mut self) -> io::Result<&[u8]> { - self.buf.fill_buf(&mut self.inner) - } - - fn consume(&mut self, amt: usize) { - self.buf.consume(amt) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for BufReader -where - R: ?Sized + fmt::Debug, -{ - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_struct("BufReader") - .field("reader", &&self.inner) - .field( - "buffer", - &format_args!("{}/{}", self.buf.filled() - self.buf.pos(), self.capacity()), - ) - .finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Seek for BufReader { - /// Seek to an offset, in bytes, in the underlying reader. - /// - /// The position used for seeking with [SeekFrom::Current]\(_) is the - /// position the underlying reader would be at if the `BufReader` had no - /// internal buffer. - /// - /// Seeking always discards the internal buffer, even if the seek position - /// would otherwise fall within it. This guarantees that calling - /// [`BufReader::into_inner()`] immediately after a seek yields the underlying reader - /// at the same position. - /// - /// To seek without discarding the internal buffer, use [`BufReader::seek_relative`]. - /// - /// See [`std::io::Seek`] for more details. - /// - /// Note: In the edge case where you're seeking with [SeekFrom::Current]\(n) - /// where `n` minus the internal buffer length overflows an `i64`, two - /// seeks will be performed instead of one. If the second seek returns - /// [`Err`], the underlying reader will be left at the same position it would - /// have if you called `seek` with [SeekFrom::Current]\(0). - /// - /// [`std::io::Seek`]: Seek - fn seek(&mut self, pos: SeekFrom) -> io::Result { - let result: u64; - if let SeekFrom::Current(n) = pos { - let remainder = (self.buf.filled() - self.buf.pos()) as i64; - // it should be safe to assume that remainder fits within an i64 as the alternative - // means we managed to allocate 8 exbibytes and that's absurd. - // But it's not out of the realm of possibility for some weird underlying reader to - // support seeking by i64::MIN so we need to handle underflow when subtracting - // remainder. - if let Some(offset) = n.checked_sub(remainder) { - result = self.inner.seek(SeekFrom::Current(offset))?; - } else { - // seek backwards by our remainder, and then by the offset - self.inner.seek(SeekFrom::Current(-remainder))?; - self.discard_buffer(); - result = self.inner.seek(SeekFrom::Current(n))?; - } - } else { - // Seeking with Start/End doesn't care about our buffer length. - result = self.inner.seek(pos)?; - } - self.discard_buffer(); - Ok(result) - } - - /// Returns the current seek position from the start of the stream. - /// - /// The value returned is equivalent to `self.seek(SeekFrom::Current(0))` - /// but does not flush the internal buffer. Due to this optimization the - /// function does not guarantee that calling `.into_inner()` immediately - /// afterwards will yield the underlying reader at the same position. Use - /// [`BufReader::seek`] instead if you require that guarantee. - /// - /// # Panics - /// - /// This function will panic if the position of the inner reader is smaller - /// than the amount of buffered data. That can happen if the inner reader - /// has an incorrect implementation of [`Seek::stream_position`], or if the - /// position has gone out of sync due to calling [`Seek::seek`] directly on - /// the underlying reader. - /// - /// # Example - /// - /// ```no_run - /// use std::{ - /// io::{self, BufRead, BufReader, Seek}, - /// fs::File, - /// }; - /// - /// fn main() -> io::Result<()> { - /// let mut f = BufReader::new(File::open("foo.txt")?); - /// - /// let before = f.stream_position()?; - /// f.read_line(&mut String::new())?; - /// let after = f.stream_position()?; - /// - /// println!("The first line was {} bytes long", after - before); - /// Ok(()) - /// } - /// ``` - fn stream_position(&mut self) -> io::Result { - let remainder = (self.buf.filled() - self.buf.pos()) as u64; - self.inner.stream_position().map(|pos| { - pos.checked_sub(remainder).expect( - "overflow when subtracting remaining buffer size from inner stream position", - ) - }) - } - - /// Seeks relative to the current position. - /// - /// If the new position lies within the buffer, the buffer will not be - /// flushed, allowing for more efficient seeks. This method does not return - /// the location of the underlying reader, so the caller must track this - /// information themselves if it is required. - fn seek_relative(&mut self, offset: i64) -> io::Result<()> { - self.seek_relative(offset) - } -} - -impl SizeHint for BufReader { - #[inline] - fn lower_bound(&self) -> usize { - SizeHint::lower_bound(self.get_ref()) + self.buffer().len() - } - - #[inline] - fn upper_bound(&self) -> Option { - SizeHint::upper_bound(self.get_ref()).and_then(|up| self.buffer().len().checked_add(up)) - } -} diff --git a/library/std/src/io/buffered/bufreader/buffer.rs b/library/std/src/io/buffered/bufreader/buffer.rs deleted file mode 100644 index e9e29d60ca282..0000000000000 --- a/library/std/src/io/buffered/bufreader/buffer.rs +++ /dev/null @@ -1,122 +0,0 @@ -///! An encapsulation of `BufReader`'s buffer management logic. -/// -/// This module factors out the basic functionality of `BufReader` in order to protect two core -/// invariants: -/// * `filled` bytes of `buf` are always initialized -/// * `pos` is always <= `filled` -/// Since this module encapsulates the buffer management logic, we can ensure that the range -/// `pos..filled` is always a valid index into the initialized region of the buffer. This means -/// that user code which wants to do reads from a `BufReader` via `buffer` + `consume` can do so -/// without encountering any runtime bounds checks. -use crate::cmp; -use crate::io::{self, BorrowedBuf, Read}; -use crate::mem::MaybeUninit; - -pub struct Buffer { - // The buffer. - buf: Box<[MaybeUninit]>, - // The current seek offset into `buf`, must always be <= `filled`. - pos: usize, - // Each call to `fill_buf` sets `filled` to indicate how many bytes at the start of `buf` are - // initialized with bytes from a read. - filled: usize, - // This is the max number of bytes returned across all `fill_buf` calls. We track this so that we - // can accurately tell `read_buf` how many bytes of buf are initialized, to bypass as much of its - // defensive initialization as possible. Note that while this often the same as `filled`, it - // doesn't need to be. Calls to `fill_buf` are not required to actually fill the buffer, and - // omitting this is a huge perf regression for `Read` impls that do not. - initialized: usize, -} - -impl Buffer { - #[inline] - pub fn with_capacity(capacity: usize) -> Self { - let buf = Box::new_uninit_slice(capacity); - Self { buf, pos: 0, filled: 0, initialized: 0 } - } - - #[inline] - pub fn buffer(&self) -> &[u8] { - // SAFETY: self.pos and self.cap are valid, and self.cap => self.pos, and - // that region is initialized because those are all invariants of this type. - unsafe { MaybeUninit::slice_assume_init_ref(self.buf.get_unchecked(self.pos..self.filled)) } - } - - #[inline] - pub fn capacity(&self) -> usize { - self.buf.len() - } - - #[inline] - pub fn filled(&self) -> usize { - self.filled - } - - #[inline] - pub fn pos(&self) -> usize { - self.pos - } - - // This is only used by a test which asserts that the initialization-tracking is correct. - #[cfg(test)] - pub fn initialized(&self) -> usize { - self.initialized - } - - #[inline] - pub fn discard_buffer(&mut self) { - self.pos = 0; - self.filled = 0; - } - - #[inline] - pub fn consume(&mut self, amt: usize) { - self.pos = cmp::min(self.pos + amt, self.filled); - } - - /// If there are `amt` bytes available in the buffer, pass a slice containing those bytes to - /// `visitor` and return true. If there are not enough bytes available, return false. - #[inline] - pub fn consume_with(&mut self, amt: usize, mut visitor: V) -> bool - where - V: FnMut(&[u8]), - { - if let Some(claimed) = self.buffer().get(..amt) { - visitor(claimed); - // If the indexing into self.buffer() succeeds, amt must be a valid increment. - self.pos += amt; - true - } else { - false - } - } - - #[inline] - pub fn unconsume(&mut self, amt: usize) { - self.pos = self.pos.saturating_sub(amt); - } - - #[inline] - pub fn fill_buf(&mut self, mut reader: impl Read) -> io::Result<&[u8]> { - // If we've reached the end of our internal buffer then we need to fetch - // some more data from the reader. - // Branch using `>=` instead of the more correct `==` - // to tell the compiler that the pos..cap slice is always valid. - if self.pos >= self.filled { - debug_assert!(self.pos == self.filled); - - let mut buf = BorrowedBuf::from(&mut *self.buf); - // SAFETY: `self.filled` bytes will always have been initialized. - unsafe { - buf.set_init(self.initialized); - } - - reader.read_buf(buf.unfilled())?; - - self.pos = 0; - self.filled = buf.len(); - self.initialized = buf.init_len(); - } - Ok(self.buffer()) - } -} diff --git a/library/std/src/io/buffered/bufwriter.rs b/library/std/src/io/buffered/bufwriter.rs deleted file mode 100644 index 2d13230ffbabd..0000000000000 --- a/library/std/src/io/buffered/bufwriter.rs +++ /dev/null @@ -1,678 +0,0 @@ -use crate::error; -use crate::fmt; -use crate::io::{ - self, ErrorKind, IntoInnerError, IoSlice, Seek, SeekFrom, Write, DEFAULT_BUF_SIZE, -}; -use crate::mem; -use crate::ptr; - -/// Wraps a writer and buffers its output. -/// -/// It can be excessively inefficient to work directly with something that -/// implements [`Write`]. For example, every call to -/// [`write`][`TcpStream::write`] on [`TcpStream`] results in a system call. A -/// `BufWriter` keeps an in-memory buffer of data and writes it to an underlying -/// writer in large, infrequent batches. -/// -/// `BufWriter` can improve the speed of programs that make *small* and -/// *repeated* write calls to the same file or network socket. It does not -/// help when writing very large amounts at once, or writing just one or a few -/// times. It also provides no advantage when writing to a destination that is -/// in memory, like a [Vec]\. -/// -/// It is critical to call [`flush`] before `BufWriter` is dropped. Though -/// dropping will attempt to flush the contents of the buffer, any errors -/// that happen in the process of dropping will be ignored. Calling [`flush`] -/// ensures that the buffer is empty and thus dropping will not even attempt -/// file operations. -/// -/// # Examples -/// -/// Let's write the numbers one through ten to a [`TcpStream`]: -/// -/// ```no_run -/// use std::io::prelude::*; -/// use std::net::TcpStream; -/// -/// let mut stream = TcpStream::connect("127.0.0.1:34254").unwrap(); -/// -/// for i in 0..10 { -/// stream.write(&[i+1]).unwrap(); -/// } -/// ``` -/// -/// Because we're not buffering, we write each one in turn, incurring the -/// overhead of a system call per byte written. We can fix this with a -/// `BufWriter`: -/// -/// ```no_run -/// use std::io::prelude::*; -/// use std::io::BufWriter; -/// use std::net::TcpStream; -/// -/// let mut stream = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap()); -/// -/// for i in 0..10 { -/// stream.write(&[i+1]).unwrap(); -/// } -/// stream.flush().unwrap(); -/// ``` -/// -/// By wrapping the stream with a `BufWriter`, these ten writes are all grouped -/// together by the buffer and will all be written out in one system call when -/// the `stream` is flushed. -/// -/// [`TcpStream::write`]: crate::net::TcpStream::write -/// [`TcpStream`]: crate::net::TcpStream -/// [`flush`]: BufWriter::flush -#[stable(feature = "rust1", since = "1.0.0")] -pub struct BufWriter { - // The buffer. Avoid using this like a normal `Vec` in common code paths. - // That is, don't use `buf.push`, `buf.extend_from_slice`, or any other - // methods that require bounds checking or the like. This makes an enormous - // difference to performance (we may want to stop using a `Vec` entirely). - buf: Vec, - // #30888: If the inner writer panics in a call to write, we don't want to - // write the buffered data a second time in BufWriter's destructor. This - // flag tells the Drop impl if it should skip the flush. - panicked: bool, - inner: W, -} - -impl BufWriter { - /// Creates a new `BufWriter` with a default buffer capacity. The default is currently 8 KiB, - /// but may change in the future. - /// - /// # Examples - /// - /// ```no_run - /// use std::io::BufWriter; - /// use std::net::TcpStream; - /// - /// let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn new(inner: W) -> BufWriter { - BufWriter::with_capacity(DEFAULT_BUF_SIZE, inner) - } - - /// Creates a new `BufWriter` with at least the specified buffer capacity. - /// - /// # Examples - /// - /// Creating a buffer with a buffer of at least a hundred bytes. - /// - /// ```no_run - /// use std::io::BufWriter; - /// use std::net::TcpStream; - /// - /// let stream = TcpStream::connect("127.0.0.1:34254").unwrap(); - /// let mut buffer = BufWriter::with_capacity(100, stream); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn with_capacity(capacity: usize, inner: W) -> BufWriter { - BufWriter { inner, buf: Vec::with_capacity(capacity), panicked: false } - } - - /// Unwraps this `BufWriter`, returning the underlying writer. - /// - /// The buffer is written out before returning the writer. - /// - /// # Errors - /// - /// An [`Err`] will be returned if an error occurs while flushing the buffer. - /// - /// # Examples - /// - /// ```no_run - /// use std::io::BufWriter; - /// use std::net::TcpStream; - /// - /// let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap()); - /// - /// // unwrap the TcpStream and flush the buffer - /// let stream = buffer.into_inner().unwrap(); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn into_inner(mut self) -> Result>> { - match self.flush_buf() { - Err(e) => Err(IntoInnerError::new(self, e)), - Ok(()) => Ok(self.into_parts().0), - } - } - - /// Disassembles this `BufWriter`, returning the underlying writer, and any buffered but - /// unwritten data. - /// - /// If the underlying writer panicked, it is not known what portion of the data was written. - /// In this case, we return `WriterPanicked` for the buffered data (from which the buffer - /// contents can still be recovered). - /// - /// `into_parts` makes no attempt to flush data and cannot fail. - /// - /// # Examples - /// - /// ``` - /// use std::io::{BufWriter, Write}; - /// - /// let mut buffer = [0u8; 10]; - /// let mut stream = BufWriter::new(buffer.as_mut()); - /// write!(stream, "too much data").unwrap(); - /// stream.flush().expect_err("it doesn't fit"); - /// let (recovered_writer, buffered_data) = stream.into_parts(); - /// assert_eq!(recovered_writer.len(), 0); - /// assert_eq!(&buffered_data.unwrap(), b"ata"); - /// ``` - #[stable(feature = "bufwriter_into_parts", since = "1.56.0")] - pub fn into_parts(mut self) -> (W, Result, WriterPanicked>) { - let buf = mem::take(&mut self.buf); - let buf = if !self.panicked { Ok(buf) } else { Err(WriterPanicked { buf }) }; - - // SAFETY: forget(self) prevents double dropping inner - let inner = unsafe { ptr::read(&self.inner) }; - mem::forget(self); - - (inner, buf) - } -} - -impl BufWriter { - /// Send data in our local buffer into the inner writer, looping as - /// necessary until either it's all been sent or an error occurs. - /// - /// Because all the data in the buffer has been reported to our owner as - /// "successfully written" (by returning nonzero success values from - /// `write`), any 0-length writes from `inner` must be reported as i/o - /// errors from this method. - pub(in crate::io) fn flush_buf(&mut self) -> io::Result<()> { - /// Helper struct to ensure the buffer is updated after all the writes - /// are complete. It tracks the number of written bytes and drains them - /// all from the front of the buffer when dropped. - struct BufGuard<'a> { - buffer: &'a mut Vec, - written: usize, - } - - impl<'a> BufGuard<'a> { - fn new(buffer: &'a mut Vec) -> Self { - Self { buffer, written: 0 } - } - - /// The unwritten part of the buffer - fn remaining(&self) -> &[u8] { - &self.buffer[self.written..] - } - - /// Flag some bytes as removed from the front of the buffer - fn consume(&mut self, amt: usize) { - self.written += amt; - } - - /// true if all of the bytes have been written - fn done(&self) -> bool { - self.written >= self.buffer.len() - } - } - - impl Drop for BufGuard<'_> { - fn drop(&mut self) { - if self.written > 0 { - self.buffer.drain(..self.written); - } - } - } - - let mut guard = BufGuard::new(&mut self.buf); - while !guard.done() { - self.panicked = true; - let r = self.inner.write(guard.remaining()); - self.panicked = false; - - match r { - Ok(0) => { - return Err(io::const_io_error!( - ErrorKind::WriteZero, - "failed to write the buffered data", - )); - } - Ok(n) => guard.consume(n), - Err(ref e) if e.is_interrupted() => {} - Err(e) => return Err(e), - } - } - Ok(()) - } - - /// Buffer some data without flushing it, regardless of the size of the - /// data. Writes as much as possible without exceeding capacity. Returns - /// the number of bytes written. - pub(super) fn write_to_buf(&mut self, buf: &[u8]) -> usize { - let available = self.spare_capacity(); - let amt_to_buffer = available.min(buf.len()); - - // SAFETY: `amt_to_buffer` is <= buffer's spare capacity by construction. - unsafe { - self.write_to_buffer_unchecked(&buf[..amt_to_buffer]); - } - - amt_to_buffer - } - - /// Gets a reference to the underlying writer. - /// - /// # Examples - /// - /// ```no_run - /// use std::io::BufWriter; - /// use std::net::TcpStream; - /// - /// let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap()); - /// - /// // we can use reference just like buffer - /// let reference = buffer.get_ref(); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn get_ref(&self) -> &W { - &self.inner - } - - /// Gets a mutable reference to the underlying writer. - /// - /// It is inadvisable to directly write to the underlying writer. - /// - /// # Examples - /// - /// ```no_run - /// use std::io::BufWriter; - /// use std::net::TcpStream; - /// - /// let mut buffer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap()); - /// - /// // we can use reference just like buffer - /// let reference = buffer.get_mut(); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn get_mut(&mut self) -> &mut W { - &mut self.inner - } - - /// Returns a reference to the internally buffered data. - /// - /// # Examples - /// - /// ```no_run - /// use std::io::BufWriter; - /// use std::net::TcpStream; - /// - /// let buf_writer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap()); - /// - /// // See how many bytes are currently buffered - /// let bytes_buffered = buf_writer.buffer().len(); - /// ``` - #[stable(feature = "bufreader_buffer", since = "1.37.0")] - pub fn buffer(&self) -> &[u8] { - &self.buf - } - - /// Returns a mutable reference to the internal buffer. - /// - /// This can be used to write data directly into the buffer without triggering writers - /// to the underlying writer. - /// - /// That the buffer is a `Vec` is an implementation detail. - /// Callers should not modify the capacity as there currently is no public API to do so - /// and thus any capacity changes would be unexpected by the user. - pub(in crate::io) fn buffer_mut(&mut self) -> &mut Vec { - &mut self.buf - } - - /// Returns the number of bytes the internal buffer can hold without flushing. - /// - /// # Examples - /// - /// ```no_run - /// use std::io::BufWriter; - /// use std::net::TcpStream; - /// - /// let buf_writer = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap()); - /// - /// // Check the capacity of the inner buffer - /// let capacity = buf_writer.capacity(); - /// // Calculate how many bytes can be written without flushing - /// let without_flush = capacity - buf_writer.buffer().len(); - /// ``` - #[stable(feature = "buffered_io_capacity", since = "1.46.0")] - pub fn capacity(&self) -> usize { - self.buf.capacity() - } - - // Ensure this function does not get inlined into `write`, so that it - // remains inlineable and its common path remains as short as possible. - // If this function ends up being called frequently relative to `write`, - // it's likely a sign that the client is using an improperly sized buffer - // or their write patterns are somewhat pathological. - #[cold] - #[inline(never)] - fn write_cold(&mut self, buf: &[u8]) -> io::Result { - if buf.len() > self.spare_capacity() { - self.flush_buf()?; - } - - // Why not len > capacity? To avoid a needless trip through the buffer when the input - // exactly fills it. We'd just need to flush it to the underlying writer anyway. - if buf.len() >= self.buf.capacity() { - self.panicked = true; - let r = self.get_mut().write(buf); - self.panicked = false; - r - } else { - // Write to the buffer. In this case, we write to the buffer even if it fills it - // exactly. Doing otherwise would mean flushing the buffer, then writing this - // input to the inner writer, which in many cases would be a worse strategy. - - // SAFETY: There was either enough spare capacity already, or there wasn't and we - // flushed the buffer to ensure that there is. In the latter case, we know that there - // is because flushing ensured that our entire buffer is spare capacity, and we entered - // this block because the input buffer length is less than that capacity. In either - // case, it's safe to write the input buffer to our buffer. - unsafe { - self.write_to_buffer_unchecked(buf); - } - - Ok(buf.len()) - } - } - - // Ensure this function does not get inlined into `write_all`, so that it - // remains inlineable and its common path remains as short as possible. - // If this function ends up being called frequently relative to `write_all`, - // it's likely a sign that the client is using an improperly sized buffer - // or their write patterns are somewhat pathological. - #[cold] - #[inline(never)] - fn write_all_cold(&mut self, buf: &[u8]) -> io::Result<()> { - // Normally, `write_all` just calls `write` in a loop. We can do better - // by calling `self.get_mut().write_all()` directly, which avoids - // round trips through the buffer in the event of a series of partial - // writes in some circumstances. - - if buf.len() > self.spare_capacity() { - self.flush_buf()?; - } - - // Why not len > capacity? To avoid a needless trip through the buffer when the input - // exactly fills it. We'd just need to flush it to the underlying writer anyway. - if buf.len() >= self.buf.capacity() { - self.panicked = true; - let r = self.get_mut().write_all(buf); - self.panicked = false; - r - } else { - // Write to the buffer. In this case, we write to the buffer even if it fills it - // exactly. Doing otherwise would mean flushing the buffer, then writing this - // input to the inner writer, which in many cases would be a worse strategy. - - // SAFETY: There was either enough spare capacity already, or there wasn't and we - // flushed the buffer to ensure that there is. In the latter case, we know that there - // is because flushing ensured that our entire buffer is spare capacity, and we entered - // this block because the input buffer length is less than that capacity. In either - // case, it's safe to write the input buffer to our buffer. - unsafe { - self.write_to_buffer_unchecked(buf); - } - - Ok(()) - } - } - - // SAFETY: Requires `buf.len() <= self.buf.capacity() - self.buf.len()`, - // i.e., that input buffer length is less than or equal to spare capacity. - #[inline] - unsafe fn write_to_buffer_unchecked(&mut self, buf: &[u8]) { - debug_assert!(buf.len() <= self.spare_capacity()); - let old_len = self.buf.len(); - let buf_len = buf.len(); - let src = buf.as_ptr(); - let dst = self.buf.as_mut_ptr().add(old_len); - ptr::copy_nonoverlapping(src, dst, buf_len); - self.buf.set_len(old_len + buf_len); - } - - #[inline] - fn spare_capacity(&self) -> usize { - self.buf.capacity() - self.buf.len() - } -} - -#[stable(feature = "bufwriter_into_parts", since = "1.56.0")] -/// Error returned for the buffered data from `BufWriter::into_parts`, when the underlying -/// writer has previously panicked. Contains the (possibly partly written) buffered data. -/// -/// # Example -/// -/// ``` -/// use std::io::{self, BufWriter, Write}; -/// use std::panic::{catch_unwind, AssertUnwindSafe}; -/// -/// struct PanickingWriter; -/// impl Write for PanickingWriter { -/// fn write(&mut self, buf: &[u8]) -> io::Result { panic!() } -/// fn flush(&mut self) -> io::Result<()> { panic!() } -/// } -/// -/// let mut stream = BufWriter::new(PanickingWriter); -/// write!(stream, "some data").unwrap(); -/// let result = catch_unwind(AssertUnwindSafe(|| { -/// stream.flush().unwrap() -/// })); -/// assert!(result.is_err()); -/// let (recovered_writer, buffered_data) = stream.into_parts(); -/// assert!(matches!(recovered_writer, PanickingWriter)); -/// assert_eq!(buffered_data.unwrap_err().into_inner(), b"some data"); -/// ``` -pub struct WriterPanicked { - buf: Vec, -} - -impl WriterPanicked { - /// Returns the perhaps-unwritten data. Some of this data may have been written by the - /// panicking call(s) to the underlying writer, so simply writing it again is not a good idea. - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "bufwriter_into_parts", since = "1.56.0")] - pub fn into_inner(self) -> Vec { - self.buf - } - - const DESCRIPTION: &'static str = - "BufWriter inner writer panicked, what data remains unwritten is not known"; -} - -#[stable(feature = "bufwriter_into_parts", since = "1.56.0")] -impl error::Error for WriterPanicked { - #[allow(deprecated, deprecated_in_future)] - fn description(&self) -> &str { - Self::DESCRIPTION - } -} - -#[stable(feature = "bufwriter_into_parts", since = "1.56.0")] -impl fmt::Display for WriterPanicked { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "{}", Self::DESCRIPTION) - } -} - -#[stable(feature = "bufwriter_into_parts", since = "1.56.0")] -impl fmt::Debug for WriterPanicked { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("WriterPanicked") - .field("buffer", &format_args!("{}/{}", self.buf.len(), self.buf.capacity())) - .finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Write for BufWriter { - #[inline] - fn write(&mut self, buf: &[u8]) -> io::Result { - // Use < instead of <= to avoid a needless trip through the buffer in some cases. - // See `write_cold` for details. - if buf.len() < self.spare_capacity() { - // SAFETY: safe by above conditional. - unsafe { - self.write_to_buffer_unchecked(buf); - } - - Ok(buf.len()) - } else { - self.write_cold(buf) - } - } - - #[inline] - fn write_all(&mut self, buf: &[u8]) -> io::Result<()> { - // Use < instead of <= to avoid a needless trip through the buffer in some cases. - // See `write_all_cold` for details. - if buf.len() < self.spare_capacity() { - // SAFETY: safe by above conditional. - unsafe { - self.write_to_buffer_unchecked(buf); - } - - Ok(()) - } else { - self.write_all_cold(buf) - } - } - - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - // FIXME: Consider applying `#[inline]` / `#[inline(never)]` optimizations already applied - // to `write` and `write_all`. The performance benefits can be significant. See #79930. - if self.get_ref().is_write_vectored() { - // We have to handle the possibility that the total length of the buffers overflows - // `usize` (even though this can only happen if multiple `IoSlice`s reference the - // same underlying buffer, as otherwise the buffers wouldn't fit in memory). If the - // computation overflows, then surely the input cannot fit in our buffer, so we forward - // to the inner writer's `write_vectored` method to let it handle it appropriately. - let mut saturated_total_len: usize = 0; - - for buf in bufs { - saturated_total_len = saturated_total_len.saturating_add(buf.len()); - - if saturated_total_len > self.spare_capacity() && !self.buf.is_empty() { - // Flush if the total length of the input exceeds our buffer's spare capacity. - // If we would have overflowed, this condition also holds, and we need to flush. - self.flush_buf()?; - } - - if saturated_total_len >= self.buf.capacity() { - // Forward to our inner writer if the total length of the input is greater than or - // equal to our buffer capacity. If we would have overflowed, this condition also - // holds, and we punt to the inner writer. - self.panicked = true; - let r = self.get_mut().write_vectored(bufs); - self.panicked = false; - return r; - } - } - - // `saturated_total_len < self.buf.capacity()` implies that we did not saturate. - - // SAFETY: We checked whether or not the spare capacity was large enough above. If - // it was, then we're safe already. If it wasn't, we flushed, making sufficient - // room for any input <= the buffer size, which includes this input. - unsafe { - bufs.iter().for_each(|b| self.write_to_buffer_unchecked(b)); - }; - - Ok(saturated_total_len) - } else { - let mut iter = bufs.iter(); - let mut total_written = if let Some(buf) = iter.by_ref().find(|&buf| !buf.is_empty()) { - // This is the first non-empty slice to write, so if it does - // not fit in the buffer, we still get to flush and proceed. - if buf.len() > self.spare_capacity() { - self.flush_buf()?; - } - if buf.len() >= self.buf.capacity() { - // The slice is at least as large as the buffering capacity, - // so it's better to write it directly, bypassing the buffer. - self.panicked = true; - let r = self.get_mut().write(buf); - self.panicked = false; - return r; - } else { - // SAFETY: We checked whether or not the spare capacity was large enough above. - // If it was, then we're safe already. If it wasn't, we flushed, making - // sufficient room for any input <= the buffer size, which includes this input. - unsafe { - self.write_to_buffer_unchecked(buf); - } - - buf.len() - } - } else { - return Ok(0); - }; - debug_assert!(total_written != 0); - for buf in iter { - if buf.len() <= self.spare_capacity() { - // SAFETY: safe by above conditional. - unsafe { - self.write_to_buffer_unchecked(buf); - } - - // This cannot overflow `usize`. If we are here, we've written all of the bytes - // so far to our buffer, and we've ensured that we never exceed the buffer's - // capacity. Therefore, `total_written` <= `self.buf.capacity()` <= `usize::MAX`. - total_written += buf.len(); - } else { - break; - } - } - Ok(total_written) - } - } - - fn is_write_vectored(&self) -> bool { - true - } - - fn flush(&mut self) -> io::Result<()> { - self.flush_buf().and_then(|()| self.get_mut().flush()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for BufWriter -where - W: fmt::Debug, -{ - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_struct("BufWriter") - .field("writer", &&self.inner) - .field("buffer", &format_args!("{}/{}", self.buf.len(), self.buf.capacity())) - .finish() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Seek for BufWriter { - /// Seek to the offset, in bytes, in the underlying writer. - /// - /// Seeking always writes out the internal buffer before seeking. - fn seek(&mut self, pos: SeekFrom) -> io::Result { - self.flush_buf()?; - self.get_mut().seek(pos) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Drop for BufWriter { - fn drop(&mut self) { - if !self.panicked { - // dtors should not panic, so we ignore a failed flush - let _r = self.flush_buf(); - } - } -} diff --git a/library/std/src/io/buffered/linewriter.rs b/library/std/src/io/buffered/linewriter.rs deleted file mode 100644 index 3d4ae70419322..0000000000000 --- a/library/std/src/io/buffered/linewriter.rs +++ /dev/null @@ -1,234 +0,0 @@ -use crate::fmt; -use crate::io::{self, buffered::LineWriterShim, BufWriter, IntoInnerError, IoSlice, Write}; - -/// Wraps a writer and buffers output to it, flushing whenever a newline -/// (`0x0a`, `'\n'`) is detected. -/// -/// The [`BufWriter`] struct wraps a writer and buffers its output. -/// But it only does this batched write when it goes out of scope, or when the -/// internal buffer is full. Sometimes, you'd prefer to write each line as it's -/// completed, rather than the entire buffer at once. Enter `LineWriter`. It -/// does exactly that. -/// -/// Like [`BufWriter`], a `LineWriter`’s buffer will also be flushed when the -/// `LineWriter` goes out of scope or when its internal buffer is full. -/// -/// If there's still a partial line in the buffer when the `LineWriter` is -/// dropped, it will flush those contents. -/// -/// # Examples -/// -/// We can use `LineWriter` to write one line at a time, significantly -/// reducing the number of actual writes to the file. -/// -/// ```no_run -/// use std::fs::{self, File}; -/// use std::io::prelude::*; -/// use std::io::LineWriter; -/// -/// fn main() -> std::io::Result<()> { -/// let road_not_taken = b"I shall be telling this with a sigh -/// Somewhere ages and ages hence: -/// Two roads diverged in a wood, and I - -/// I took the one less traveled by, -/// And that has made all the difference."; -/// -/// let file = File::create("poem.txt")?; -/// let mut file = LineWriter::new(file); -/// -/// file.write_all(b"I shall be telling this with a sigh")?; -/// -/// // No bytes are written until a newline is encountered (or -/// // the internal buffer is filled). -/// assert_eq!(fs::read_to_string("poem.txt")?, ""); -/// file.write_all(b"\n")?; -/// assert_eq!( -/// fs::read_to_string("poem.txt")?, -/// "I shall be telling this with a sigh\n", -/// ); -/// -/// // Write the rest of the poem. -/// file.write_all(b"Somewhere ages and ages hence: -/// Two roads diverged in a wood, and I - -/// I took the one less traveled by, -/// And that has made all the difference.")?; -/// -/// // The last line of the poem doesn't end in a newline, so -/// // we have to flush or drop the `LineWriter` to finish -/// // writing. -/// file.flush()?; -/// -/// // Confirm the whole poem was written. -/// assert_eq!(fs::read("poem.txt")?, &road_not_taken[..]); -/// Ok(()) -/// } -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub struct LineWriter { - inner: BufWriter, -} - -impl LineWriter { - /// Creates a new `LineWriter`. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::File; - /// use std::io::LineWriter; - /// - /// fn main() -> std::io::Result<()> { - /// let file = File::create("poem.txt")?; - /// let file = LineWriter::new(file); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn new(inner: W) -> LineWriter { - // Lines typically aren't that long, don't use a giant buffer - LineWriter::with_capacity(1024, inner) - } - - /// Creates a new `LineWriter` with at least the specified capacity for the - /// internal buffer. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::File; - /// use std::io::LineWriter; - /// - /// fn main() -> std::io::Result<()> { - /// let file = File::create("poem.txt")?; - /// let file = LineWriter::with_capacity(100, file); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn with_capacity(capacity: usize, inner: W) -> LineWriter { - LineWriter { inner: BufWriter::with_capacity(capacity, inner) } - } - - /// Gets a mutable reference to the underlying writer. - /// - /// Caution must be taken when calling methods on the mutable reference - /// returned as extra writes could corrupt the output stream. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::File; - /// use std::io::LineWriter; - /// - /// fn main() -> std::io::Result<()> { - /// let file = File::create("poem.txt")?; - /// let mut file = LineWriter::new(file); - /// - /// // we can use reference just like file - /// let reference = file.get_mut(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn get_mut(&mut self) -> &mut W { - self.inner.get_mut() - } - - /// Unwraps this `LineWriter`, returning the underlying writer. - /// - /// The internal buffer is written out before returning the writer. - /// - /// # Errors - /// - /// An [`Err`] will be returned if an error occurs while flushing the buffer. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::File; - /// use std::io::LineWriter; - /// - /// fn main() -> std::io::Result<()> { - /// let file = File::create("poem.txt")?; - /// - /// let writer: LineWriter = LineWriter::new(file); - /// - /// let file: File = writer.into_inner()?; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn into_inner(self) -> Result>> { - self.inner.into_inner().map_err(|err| err.new_wrapped(|inner| LineWriter { inner })) - } -} - -impl LineWriter { - /// Gets a reference to the underlying writer. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::File; - /// use std::io::LineWriter; - /// - /// fn main() -> std::io::Result<()> { - /// let file = File::create("poem.txt")?; - /// let file = LineWriter::new(file); - /// - /// let reference = file.get_ref(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn get_ref(&self) -> &W { - self.inner.get_ref() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Write for LineWriter { - fn write(&mut self, buf: &[u8]) -> io::Result { - LineWriterShim::new(&mut self.inner).write(buf) - } - - fn flush(&mut self) -> io::Result<()> { - self.inner.flush() - } - - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - LineWriterShim::new(&mut self.inner).write_vectored(bufs) - } - - fn is_write_vectored(&self) -> bool { - self.inner.is_write_vectored() - } - - fn write_all(&mut self, buf: &[u8]) -> io::Result<()> { - LineWriterShim::new(&mut self.inner).write_all(buf) - } - - fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> { - LineWriterShim::new(&mut self.inner).write_all_vectored(bufs) - } - - fn write_fmt(&mut self, fmt: fmt::Arguments<'_>) -> io::Result<()> { - LineWriterShim::new(&mut self.inner).write_fmt(fmt) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for LineWriter -where - W: fmt::Debug, -{ - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.debug_struct("LineWriter") - .field("writer", &self.get_ref()) - .field( - "buffer", - &format_args!("{}/{}", self.inner.buffer().len(), self.inner.capacity()), - ) - .finish_non_exhaustive() - } -} diff --git a/library/std/src/io/buffered/linewritershim.rs b/library/std/src/io/buffered/linewritershim.rs deleted file mode 100644 index c3ac7855d4450..0000000000000 --- a/library/std/src/io/buffered/linewritershim.rs +++ /dev/null @@ -1,285 +0,0 @@ -use crate::io::{self, BufWriter, IoSlice, Write}; -use core::slice::memchr; - -/// Private helper struct for implementing the line-buffered writing logic. -/// This shim temporarily wraps a BufWriter, and uses its internals to -/// implement a line-buffered writer (specifically by using the internal -/// methods like write_to_buf and flush_buf). In this way, a more -/// efficient abstraction can be created than one that only had access to -/// `write` and `flush`, without needlessly duplicating a lot of the -/// implementation details of BufWriter. This also allows existing -/// `BufWriters` to be temporarily given line-buffering logic; this is what -/// enables Stdout to be alternately in line-buffered or block-buffered mode. -#[derive(Debug)] -pub struct LineWriterShim<'a, W: ?Sized + Write> { - buffer: &'a mut BufWriter, -} - -impl<'a, W: ?Sized + Write> LineWriterShim<'a, W> { - pub fn new(buffer: &'a mut BufWriter) -> Self { - Self { buffer } - } - - /// Get a reference to the inner writer (that is, the writer - /// wrapped by the BufWriter). - fn inner(&self) -> &W { - self.buffer.get_ref() - } - - /// Get a mutable reference to the inner writer (that is, the writer - /// wrapped by the BufWriter). Be careful with this writer, as writes to - /// it will bypass the buffer. - fn inner_mut(&mut self) -> &mut W { - self.buffer.get_mut() - } - - /// Get the content currently buffered in self.buffer - fn buffered(&self) -> &[u8] { - self.buffer.buffer() - } - - /// Flush the buffer iff the last byte is a newline (indicating that an - /// earlier write only succeeded partially, and we want to retry flushing - /// the buffered line before continuing with a subsequent write) - fn flush_if_completed_line(&mut self) -> io::Result<()> { - match self.buffered().last().copied() { - Some(b'\n') => self.buffer.flush_buf(), - _ => Ok(()), - } - } -} - -impl<'a, W: ?Sized + Write> Write for LineWriterShim<'a, W> { - /// Write some data into this BufReader with line buffering. This means - /// that, if any newlines are present in the data, the data up to the last - /// newline is sent directly to the underlying writer, and data after it - /// is buffered. Returns the number of bytes written. - /// - /// This function operates on a "best effort basis"; in keeping with the - /// convention of `Write::write`, it makes at most one attempt to write - /// new data to the underlying writer. If that write only reports a partial - /// success, the remaining data will be buffered. - /// - /// Because this function attempts to send completed lines to the underlying - /// writer, it will also flush the existing buffer if it ends with a - /// newline, even if the incoming data does not contain any newlines. - fn write(&mut self, buf: &[u8]) -> io::Result { - let newline_idx = match memchr::memrchr(b'\n', buf) { - // If there are no new newlines (that is, if this write is less than - // one line), just do a regular buffered write (which may flush if - // we exceed the inner buffer's size) - None => { - self.flush_if_completed_line()?; - return self.buffer.write(buf); - } - // Otherwise, arrange for the lines to be written directly to the - // inner writer. - Some(newline_idx) => newline_idx + 1, - }; - - // Flush existing content to prepare for our write. We have to do this - // before attempting to write `buf` in order to maintain consistency; - // if we add `buf` to the buffer then try to flush it all at once, - // we're obligated to return Ok(), which would mean suppressing any - // errors that occur during flush. - self.buffer.flush_buf()?; - - // This is what we're going to try to write directly to the inner - // writer. The rest will be buffered, if nothing goes wrong. - let lines = &buf[..newline_idx]; - - // Write `lines` directly to the inner writer. In keeping with the - // `write` convention, make at most one attempt to add new (unbuffered) - // data. Because this write doesn't touch the BufWriter state directly, - // and the buffer is known to be empty, we don't need to worry about - // self.buffer.panicked here. - let flushed = self.inner_mut().write(lines)?; - - // If buffer returns Ok(0), propagate that to the caller without - // doing additional buffering; otherwise we're just guaranteeing - // an "ErrorKind::WriteZero" later. - if flushed == 0 { - return Ok(0); - } - - // Now that the write has succeeded, buffer the rest (or as much of - // the rest as possible). If there were any unwritten newlines, we - // only buffer out to the last unwritten newline that fits in the - // buffer; this helps prevent flushing partial lines on subsequent - // calls to LineWriterShim::write. - - // Handle the cases in order of most-common to least-common, under - // the presumption that most writes succeed in totality, and that most - // writes are smaller than the buffer. - // - Is this a partial line (ie, no newlines left in the unwritten tail) - // - If not, does the data out to the last unwritten newline fit in - // the buffer? - // - If not, scan for the last newline that *does* fit in the buffer - let tail = if flushed >= newline_idx { - &buf[flushed..] - } else if newline_idx - flushed <= self.buffer.capacity() { - &buf[flushed..newline_idx] - } else { - let scan_area = &buf[flushed..]; - let scan_area = &scan_area[..self.buffer.capacity()]; - match memchr::memrchr(b'\n', scan_area) { - Some(newline_idx) => &scan_area[..newline_idx + 1], - None => scan_area, - } - }; - - let buffered = self.buffer.write_to_buf(tail); - Ok(flushed + buffered) - } - - fn flush(&mut self) -> io::Result<()> { - self.buffer.flush() - } - - /// Write some vectored data into this BufReader with line buffering. This - /// means that, if any newlines are present in the data, the data up to - /// and including the buffer containing the last newline is sent directly - /// to the inner writer, and the data after it is buffered. Returns the - /// number of bytes written. - /// - /// This function operates on a "best effort basis"; in keeping with the - /// convention of `Write::write`, it makes at most one attempt to write - /// new data to the underlying writer. - /// - /// Because this function attempts to send completed lines to the underlying - /// writer, it will also flush the existing buffer if it contains any - /// newlines. - /// - /// Because sorting through an array of `IoSlice` can be a bit convoluted, - /// This method differs from write in the following ways: - /// - /// - It attempts to write the full content of all the buffers up to and - /// including the one containing the last newline. This means that it - /// may attempt to write a partial line, that buffer has data past the - /// newline. - /// - If the write only reports partial success, it does not attempt to - /// find the precise location of the written bytes and buffer the rest. - /// - /// If the underlying vector doesn't support vectored writing, we instead - /// simply write the first non-empty buffer with `write`. This way, we - /// get the benefits of more granular partial-line handling without losing - /// anything in efficiency - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - // If there's no specialized behavior for write_vectored, just use - // write. This has the benefit of more granular partial-line handling. - if !self.is_write_vectored() { - return match bufs.iter().find(|buf| !buf.is_empty()) { - Some(buf) => self.write(buf), - None => Ok(0), - }; - } - - // Find the buffer containing the last newline - // FIXME: This is overly slow if there are very many bufs and none contain - // newlines. e.g. writev() on Linux only writes up to 1024 slices, so - // scanning the rest is wasted effort. This makes write_all_vectored() - // quadratic. - let last_newline_buf_idx = bufs - .iter() - .enumerate() - .rev() - .find_map(|(i, buf)| memchr::memchr(b'\n', buf).map(|_| i)); - - // If there are no new newlines (that is, if this write is less than - // one line), just do a regular buffered write - let last_newline_buf_idx = match last_newline_buf_idx { - // No newlines; just do a normal buffered write - None => { - self.flush_if_completed_line()?; - return self.buffer.write_vectored(bufs); - } - Some(i) => i, - }; - - // Flush existing content to prepare for our write - self.buffer.flush_buf()?; - - // This is what we're going to try to write directly to the inner - // writer. The rest will be buffered, if nothing goes wrong. - let (lines, tail) = bufs.split_at(last_newline_buf_idx + 1); - - // Write `lines` directly to the inner writer. In keeping with the - // `write` convention, make at most one attempt to add new (unbuffered) - // data. Because this write doesn't touch the BufWriter state directly, - // and the buffer is known to be empty, we don't need to worry about - // self.panicked here. - let flushed = self.inner_mut().write_vectored(lines)?; - - // If inner returns Ok(0), propagate that to the caller without - // doing additional buffering; otherwise we're just guaranteeing - // an "ErrorKind::WriteZero" later. - if flushed == 0 { - return Ok(0); - } - - // Don't try to reconstruct the exact amount written; just bail - // in the event of a partial write - let mut lines_len: usize = 0; - for buf in lines { - // With overlapping/duplicate slices the total length may in theory - // exceed usize::MAX - lines_len = lines_len.saturating_add(buf.len()); - if flushed < lines_len { - return Ok(flushed); - } - } - - // Now that the write has succeeded, buffer the rest (or as much of the - // rest as possible) - let buffered: usize = tail - .iter() - .filter(|buf| !buf.is_empty()) - .map(|buf| self.buffer.write_to_buf(buf)) - .take_while(|&n| n > 0) - .sum(); - - Ok(flushed + buffered) - } - - fn is_write_vectored(&self) -> bool { - self.inner().is_write_vectored() - } - - /// Write some data into this BufReader with line buffering. This means - /// that, if any newlines are present in the data, the data up to the last - /// newline is sent directly to the underlying writer, and data after it - /// is buffered. - /// - /// Because this function attempts to send completed lines to the underlying - /// writer, it will also flush the existing buffer if it contains any - /// newlines, even if the incoming data does not contain any newlines. - fn write_all(&mut self, buf: &[u8]) -> io::Result<()> { - match memchr::memrchr(b'\n', buf) { - // If there are no new newlines (that is, if this write is less than - // one line), just do a regular buffered write (which may flush if - // we exceed the inner buffer's size) - None => { - self.flush_if_completed_line()?; - self.buffer.write_all(buf) - } - Some(newline_idx) => { - let (lines, tail) = buf.split_at(newline_idx + 1); - - if self.buffered().is_empty() { - self.inner_mut().write_all(lines)?; - } else { - // If there is any buffered data, we add the incoming lines - // to that buffer before flushing, which saves us at least - // one write call. We can't really do this with `write`, - // since we can't do this *and* not suppress errors *and* - // report a consistent state to the caller in a return - // value, but here in write_all it's fine. - self.buffer.write_all(lines)?; - self.buffer.flush_buf()?; - } - - self.buffer.write_all(tail) - } - } - } -} diff --git a/library/std/src/io/buffered/mod.rs b/library/std/src/io/buffered/mod.rs deleted file mode 100644 index 100dab1e2493c..0000000000000 --- a/library/std/src/io/buffered/mod.rs +++ /dev/null @@ -1,196 +0,0 @@ -//! Buffering wrappers for I/O traits - -mod bufreader; -mod bufwriter; -mod linewriter; -mod linewritershim; - -#[cfg(test)] -mod tests; - -use crate::error; -use crate::fmt; -use crate::io::Error; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::{bufreader::BufReader, bufwriter::BufWriter, linewriter::LineWriter}; -use linewritershim::LineWriterShim; - -#[stable(feature = "bufwriter_into_parts", since = "1.56.0")] -pub use bufwriter::WriterPanicked; - -/// An error returned by [`BufWriter::into_inner`] which combines an error that -/// happened while writing out the buffer, and the buffered writer object -/// which may be used to recover from the condition. -/// -/// # Examples -/// -/// ```no_run -/// use std::io::BufWriter; -/// use std::net::TcpStream; -/// -/// let mut stream = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap()); -/// -/// // do stuff with the stream -/// -/// // we want to get our `TcpStream` back, so let's try: -/// -/// let stream = match stream.into_inner() { -/// Ok(s) => s, -/// Err(e) => { -/// // Here, e is an IntoInnerError -/// panic!("An error occurred"); -/// } -/// }; -/// ``` -#[derive(Debug)] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct IntoInnerError(W, Error); - -impl IntoInnerError { - /// Construct a new IntoInnerError - fn new(writer: W, error: Error) -> Self { - Self(writer, error) - } - - /// Helper to construct a new IntoInnerError; intended to help with - /// adapters that wrap other adapters - fn new_wrapped(self, f: impl FnOnce(W) -> W2) -> IntoInnerError { - let Self(writer, error) = self; - IntoInnerError::new(f(writer), error) - } - - /// Returns the error which caused the call to [`BufWriter::into_inner()`] - /// to fail. - /// - /// This error was returned when attempting to write the internal buffer. - /// - /// # Examples - /// - /// ```no_run - /// use std::io::BufWriter; - /// use std::net::TcpStream; - /// - /// let mut stream = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap()); - /// - /// // do stuff with the stream - /// - /// // we want to get our `TcpStream` back, so let's try: - /// - /// let stream = match stream.into_inner() { - /// Ok(s) => s, - /// Err(e) => { - /// // Here, e is an IntoInnerError, let's log the inner error. - /// // - /// // We'll just 'log' to stdout for this example. - /// println!("{}", e.error()); - /// - /// panic!("An unexpected error occurred."); - /// } - /// }; - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn error(&self) -> &Error { - &self.1 - } - - /// Returns the buffered writer instance which generated the error. - /// - /// The returned object can be used for error recovery, such as - /// re-inspecting the buffer. - /// - /// # Examples - /// - /// ```no_run - /// use std::io::BufWriter; - /// use std::net::TcpStream; - /// - /// let mut stream = BufWriter::new(TcpStream::connect("127.0.0.1:34254").unwrap()); - /// - /// // do stuff with the stream - /// - /// // we want to get our `TcpStream` back, so let's try: - /// - /// let stream = match stream.into_inner() { - /// Ok(s) => s, - /// Err(e) => { - /// // Here, e is an IntoInnerError, let's re-examine the buffer: - /// let buffer = e.into_inner(); - /// - /// // do stuff to try to recover - /// - /// // afterwards, let's just return the stream - /// buffer.into_inner().unwrap() - /// } - /// }; - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn into_inner(self) -> W { - self.0 - } - - /// Consumes the [`IntoInnerError`] and returns the error which caused the call to - /// [`BufWriter::into_inner()`] to fail. Unlike `error`, this can be used to - /// obtain ownership of the underlying error. - /// - /// # Example - /// ``` - /// use std::io::{BufWriter, ErrorKind, Write}; - /// - /// let mut not_enough_space = [0u8; 10]; - /// let mut stream = BufWriter::new(not_enough_space.as_mut()); - /// write!(stream, "this cannot be actually written").unwrap(); - /// let into_inner_err = stream.into_inner().expect_err("now we discover it's too small"); - /// let err = into_inner_err.into_error(); - /// assert_eq!(err.kind(), ErrorKind::WriteZero); - /// ``` - #[stable(feature = "io_into_inner_error_parts", since = "1.55.0")] - pub fn into_error(self) -> Error { - self.1 - } - - /// Consumes the [`IntoInnerError`] and returns the error which caused the call to - /// [`BufWriter::into_inner()`] to fail, and the underlying writer. - /// - /// This can be used to simply obtain ownership of the underlying error; it can also be used for - /// advanced error recovery. - /// - /// # Example - /// ``` - /// use std::io::{BufWriter, ErrorKind, Write}; - /// - /// let mut not_enough_space = [0u8; 10]; - /// let mut stream = BufWriter::new(not_enough_space.as_mut()); - /// write!(stream, "this cannot be actually written").unwrap(); - /// let into_inner_err = stream.into_inner().expect_err("now we discover it's too small"); - /// let (err, recovered_writer) = into_inner_err.into_parts(); - /// assert_eq!(err.kind(), ErrorKind::WriteZero); - /// assert_eq!(recovered_writer.buffer(), b"t be actually written"); - /// ``` - #[stable(feature = "io_into_inner_error_parts", since = "1.55.0")] - pub fn into_parts(self) -> (Error, W) { - (self.1, self.0) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl From> for Error { - fn from(iie: IntoInnerError) -> Error { - iie.1 - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl error::Error for IntoInnerError { - #[allow(deprecated, deprecated_in_future)] - fn description(&self) -> &str { - error::Error::description(self.error()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for IntoInnerError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.error().fmt(f) - } -} diff --git a/library/std/src/io/buffered/tests.rs b/library/std/src/io/buffered/tests.rs deleted file mode 100644 index ee0db30e22c2e..0000000000000 --- a/library/std/src/io/buffered/tests.rs +++ /dev/null @@ -1,1069 +0,0 @@ -use crate::io::prelude::*; -use crate::io::{ - self, BorrowedBuf, BufReader, BufWriter, ErrorKind, IoSlice, LineWriter, SeekFrom, -}; -use crate::mem::MaybeUninit; -use crate::panic; -use crate::sync::atomic::{AtomicUsize, Ordering}; -use crate::thread; - -/// A dummy reader intended at testing short-reads propagation. -pub struct ShortReader { - lengths: Vec, -} - -// FIXME: rustfmt and tidy disagree about the correct formatting of this -// function. This leads to issues for users with editors configured to -// rustfmt-on-save. -impl Read for ShortReader { - fn read(&mut self, _: &mut [u8]) -> io::Result { - if self.lengths.is_empty() { Ok(0) } else { Ok(self.lengths.remove(0)) } - } -} - -#[test] -fn test_buffered_reader() { - let inner: &[u8] = &[5, 6, 7, 0, 1, 2, 3, 4]; - let mut reader = BufReader::with_capacity(2, inner); - - let mut buf = [0, 0, 0]; - let nread = reader.read(&mut buf); - assert_eq!(nread.unwrap(), 3); - assert_eq!(buf, [5, 6, 7]); - assert_eq!(reader.buffer(), []); - - let mut buf = [0, 0]; - let nread = reader.read(&mut buf); - assert_eq!(nread.unwrap(), 2); - assert_eq!(buf, [0, 1]); - assert_eq!(reader.buffer(), []); - - let mut buf = [0]; - let nread = reader.read(&mut buf); - assert_eq!(nread.unwrap(), 1); - assert_eq!(buf, [2]); - assert_eq!(reader.buffer(), [3]); - - let mut buf = [0, 0, 0]; - let nread = reader.read(&mut buf); - assert_eq!(nread.unwrap(), 1); - assert_eq!(buf, [3, 0, 0]); - assert_eq!(reader.buffer(), []); - - let nread = reader.read(&mut buf); - assert_eq!(nread.unwrap(), 1); - assert_eq!(buf, [4, 0, 0]); - assert_eq!(reader.buffer(), []); - - assert_eq!(reader.read(&mut buf).unwrap(), 0); -} - -#[test] -fn test_buffered_reader_read_buf() { - let inner: &[u8] = &[5, 6, 7, 0, 1, 2, 3, 4]; - let mut reader = BufReader::with_capacity(2, inner); - - let buf: &mut [_] = &mut [MaybeUninit::uninit(); 3]; - let mut buf: BorrowedBuf<'_> = buf.into(); - - reader.read_buf(buf.unfilled()).unwrap(); - - assert_eq!(buf.filled(), [5, 6, 7]); - assert_eq!(reader.buffer(), []); - - let buf: &mut [_] = &mut [MaybeUninit::uninit(); 2]; - let mut buf: BorrowedBuf<'_> = buf.into(); - - reader.read_buf(buf.unfilled()).unwrap(); - - assert_eq!(buf.filled(), [0, 1]); - assert_eq!(reader.buffer(), []); - - let buf: &mut [_] = &mut [MaybeUninit::uninit(); 1]; - let mut buf: BorrowedBuf<'_> = buf.into(); - - reader.read_buf(buf.unfilled()).unwrap(); - - assert_eq!(buf.filled(), [2]); - assert_eq!(reader.buffer(), [3]); - - let buf: &mut [_] = &mut [MaybeUninit::uninit(); 3]; - let mut buf: BorrowedBuf<'_> = buf.into(); - - reader.read_buf(buf.unfilled()).unwrap(); - - assert_eq!(buf.filled(), [3]); - assert_eq!(reader.buffer(), []); - - reader.read_buf(buf.unfilled()).unwrap(); - - assert_eq!(buf.filled(), [3, 4]); - assert_eq!(reader.buffer(), []); - - buf.clear(); - - reader.read_buf(buf.unfilled()).unwrap(); - - assert!(buf.filled().is_empty()); -} - -#[test] -fn test_buffered_reader_seek() { - let inner: &[u8] = &[5, 6, 7, 0, 1, 2, 3, 4]; - let mut reader = BufReader::with_capacity(2, io::Cursor::new(inner)); - - assert_eq!(reader.seek(SeekFrom::Start(3)).ok(), Some(3)); - assert_eq!(reader.fill_buf().ok(), Some(&[0, 1][..])); - assert_eq!(reader.stream_position().ok(), Some(3)); - assert_eq!(reader.fill_buf().ok(), Some(&[0, 1][..])); - assert_eq!(reader.seek(SeekFrom::Current(1)).ok(), Some(4)); - assert_eq!(reader.fill_buf().ok(), Some(&[1, 2][..])); - reader.consume(1); - assert_eq!(reader.seek(SeekFrom::Current(-2)).ok(), Some(3)); -} - -#[test] -fn test_buffered_reader_seek_relative() { - let inner: &[u8] = &[5, 6, 7, 0, 1, 2, 3, 4]; - let mut reader = BufReader::with_capacity(2, io::Cursor::new(inner)); - - assert!(reader.seek_relative(3).is_ok()); - assert_eq!(reader.fill_buf().ok(), Some(&[0, 1][..])); - assert!(reader.seek_relative(0).is_ok()); - assert_eq!(reader.fill_buf().ok(), Some(&[0, 1][..])); - assert!(reader.seek_relative(1).is_ok()); - assert_eq!(reader.fill_buf().ok(), Some(&[1][..])); - assert!(reader.seek_relative(-1).is_ok()); - assert_eq!(reader.fill_buf().ok(), Some(&[0, 1][..])); - assert!(reader.seek_relative(2).is_ok()); - assert_eq!(reader.fill_buf().ok(), Some(&[2, 3][..])); -} - -#[test] -fn test_buffered_reader_stream_position() { - let inner: &[u8] = &[5, 6, 7, 0, 1, 2, 3, 4]; - let mut reader = BufReader::with_capacity(2, io::Cursor::new(inner)); - - assert_eq!(reader.stream_position().ok(), Some(0)); - assert_eq!(reader.seek(SeekFrom::Start(3)).ok(), Some(3)); - assert_eq!(reader.stream_position().ok(), Some(3)); - // relative seeking within the buffer and reading position should keep the buffer - assert_eq!(reader.fill_buf().ok(), Some(&[0, 1][..])); - assert!(reader.seek_relative(0).is_ok()); - assert_eq!(reader.stream_position().ok(), Some(3)); - assert_eq!(reader.buffer(), &[0, 1][..]); - assert!(reader.seek_relative(1).is_ok()); - assert_eq!(reader.stream_position().ok(), Some(4)); - assert_eq!(reader.buffer(), &[1][..]); - assert!(reader.seek_relative(-1).is_ok()); - assert_eq!(reader.stream_position().ok(), Some(3)); - assert_eq!(reader.buffer(), &[0, 1][..]); - // relative seeking outside the buffer will discard it - assert!(reader.seek_relative(2).is_ok()); - assert_eq!(reader.stream_position().ok(), Some(5)); - assert_eq!(reader.buffer(), &[][..]); -} - -#[test] -fn test_buffered_reader_stream_position_panic() { - let inner: &[u8] = &[5, 6, 7, 0, 1, 2, 3, 4]; - let mut reader = BufReader::with_capacity(4, io::Cursor::new(inner)); - - // cause internal buffer to be filled but read only partially - let mut buffer = [0, 0]; - assert!(reader.read_exact(&mut buffer).is_ok()); - // rewinding the internal reader will cause buffer to loose sync - let inner = reader.get_mut(); - assert!(inner.seek(SeekFrom::Start(0)).is_ok()); - // overflow when subtracting the remaining buffer size from current position - let result = panic::catch_unwind(panic::AssertUnwindSafe(|| reader.stream_position().ok())); - assert!(result.is_err()); -} - -#[test] -fn test_buffered_reader_invalidated_after_read() { - let inner: &[u8] = &[5, 6, 7, 0, 1, 2, 3, 4]; - let mut reader = BufReader::with_capacity(3, io::Cursor::new(inner)); - - assert_eq!(reader.fill_buf().ok(), Some(&[5, 6, 7][..])); - reader.consume(3); - - let mut buffer = [0, 0, 0, 0, 0]; - assert_eq!(reader.read(&mut buffer).ok(), Some(5)); - assert_eq!(buffer, [0, 1, 2, 3, 4]); - - assert!(reader.seek_relative(-2).is_ok()); - let mut buffer = [0, 0]; - assert_eq!(reader.read(&mut buffer).ok(), Some(2)); - assert_eq!(buffer, [3, 4]); -} - -#[test] -fn test_buffered_reader_invalidated_after_seek() { - let inner: &[u8] = &[5, 6, 7, 0, 1, 2, 3, 4]; - let mut reader = BufReader::with_capacity(3, io::Cursor::new(inner)); - - assert_eq!(reader.fill_buf().ok(), Some(&[5, 6, 7][..])); - reader.consume(3); - - assert!(reader.seek(SeekFrom::Current(5)).is_ok()); - - assert!(reader.seek_relative(-2).is_ok()); - let mut buffer = [0, 0]; - assert_eq!(reader.read(&mut buffer).ok(), Some(2)); - assert_eq!(buffer, [3, 4]); -} - -#[test] -fn test_buffered_reader_seek_underflow() { - // gimmick reader that yields its position modulo 256 for each byte - struct PositionReader { - pos: u64, - } - impl Read for PositionReader { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - let len = buf.len(); - for x in buf { - *x = self.pos as u8; - self.pos = self.pos.wrapping_add(1); - } - Ok(len) - } - } - // note: this implementation of `Seek` is "broken" due to position - // wrapping, so calling `reader.seek(Current(0))` is semantically different - // than `reader.stream_position()` - impl Seek for PositionReader { - fn seek(&mut self, pos: SeekFrom) -> io::Result { - match pos { - SeekFrom::Start(n) => { - self.pos = n; - } - SeekFrom::Current(n) => { - self.pos = self.pos.wrapping_add(n as u64); - } - SeekFrom::End(n) => { - self.pos = u64::MAX.wrapping_add(n as u64); - } - } - Ok(self.pos) - } - } - - let mut reader = BufReader::with_capacity(5, PositionReader { pos: 0 }); - assert_eq!(reader.fill_buf().ok(), Some(&[0, 1, 2, 3, 4][..])); - assert_eq!(reader.seek(SeekFrom::End(-5)).ok(), Some(u64::MAX - 5)); - assert_eq!(reader.fill_buf().ok().map(|s| s.len()), Some(5)); - // the following seek will require two underlying seeks - let expected = 9223372036854775802; - assert_eq!(reader.seek(SeekFrom::Current(i64::MIN)).ok(), Some(expected)); - assert_eq!(reader.fill_buf().ok().map(|s| s.len()), Some(5)); - // seeking to 0 should empty the buffer. - assert_eq!(reader.seek(SeekFrom::Current(0)).ok(), Some(expected)); - assert_eq!(reader.get_ref().pos, expected); -} - -#[test] -fn test_buffered_reader_seek_underflow_discard_buffer_between_seeks() { - // gimmick reader that returns Err after first seek - struct ErrAfterFirstSeekReader { - first_seek: bool, - } - impl Read for ErrAfterFirstSeekReader { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - for x in &mut *buf { - *x = 0; - } - Ok(buf.len()) - } - } - impl Seek for ErrAfterFirstSeekReader { - fn seek(&mut self, _: SeekFrom) -> io::Result { - if self.first_seek { - self.first_seek = false; - Ok(0) - } else { - Err(io::Error::new(io::ErrorKind::Other, "oh no!")) - } - } - } - - let mut reader = BufReader::with_capacity(5, ErrAfterFirstSeekReader { first_seek: true }); - assert_eq!(reader.fill_buf().ok(), Some(&[0, 0, 0, 0, 0][..])); - - // The following seek will require two underlying seeks. The first will - // succeed but the second will fail. This should still invalidate the - // buffer. - assert!(reader.seek(SeekFrom::Current(i64::MIN)).is_err()); - assert_eq!(reader.buffer().len(), 0); -} - -#[test] -fn test_buffered_reader_read_to_end_consumes_buffer() { - let data: &[u8] = &[0, 1, 2, 3, 4, 5, 6, 7]; - let mut reader = BufReader::with_capacity(3, data); - let mut buf = Vec::new(); - assert_eq!(reader.fill_buf().ok(), Some(&[0, 1, 2][..])); - assert_eq!(reader.read_to_end(&mut buf).ok(), Some(8)); - assert_eq!(&buf, &[0, 1, 2, 3, 4, 5, 6, 7]); - assert!(reader.buffer().is_empty()); -} - -#[test] -fn test_buffered_reader_read_to_string_consumes_buffer() { - let data: &[u8] = "deadbeef".as_bytes(); - let mut reader = BufReader::with_capacity(3, data); - let mut buf = String::new(); - assert_eq!(reader.fill_buf().ok(), Some("dea".as_bytes())); - assert_eq!(reader.read_to_string(&mut buf).ok(), Some(8)); - assert_eq!(&buf, "deadbeef"); - assert!(reader.buffer().is_empty()); -} - -#[test] -fn test_buffered_writer() { - let inner = Vec::new(); - let mut writer = BufWriter::with_capacity(2, inner); - - writer.write(&[0, 1]).unwrap(); - assert_eq!(writer.buffer(), []); - assert_eq!(*writer.get_ref(), [0, 1]); - - writer.write(&[2]).unwrap(); - assert_eq!(writer.buffer(), [2]); - assert_eq!(*writer.get_ref(), [0, 1]); - - writer.write(&[3]).unwrap(); - assert_eq!(writer.buffer(), [2, 3]); - assert_eq!(*writer.get_ref(), [0, 1]); - - writer.flush().unwrap(); - assert_eq!(writer.buffer(), []); - assert_eq!(*writer.get_ref(), [0, 1, 2, 3]); - - writer.write(&[4]).unwrap(); - writer.write(&[5]).unwrap(); - assert_eq!(writer.buffer(), [4, 5]); - assert_eq!(*writer.get_ref(), [0, 1, 2, 3]); - - writer.write(&[6]).unwrap(); - assert_eq!(writer.buffer(), [6]); - assert_eq!(*writer.get_ref(), [0, 1, 2, 3, 4, 5]); - - writer.write(&[7, 8]).unwrap(); - assert_eq!(writer.buffer(), []); - assert_eq!(*writer.get_ref(), [0, 1, 2, 3, 4, 5, 6, 7, 8]); - - writer.write(&[9, 10, 11]).unwrap(); - assert_eq!(writer.buffer(), []); - assert_eq!(*writer.get_ref(), [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]); - - writer.flush().unwrap(); - assert_eq!(writer.buffer(), []); - assert_eq!(*writer.get_ref(), [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11]); -} - -#[test] -fn test_buffered_writer_inner_flushes() { - let mut w = BufWriter::with_capacity(3, Vec::new()); - w.write(&[0, 1]).unwrap(); - assert_eq!(*w.get_ref(), []); - let w = w.into_inner().unwrap(); - assert_eq!(w, [0, 1]); -} - -#[test] -fn test_buffered_writer_seek() { - let mut w = BufWriter::with_capacity(3, io::Cursor::new(Vec::new())); - w.write_all(&[0, 1, 2, 3, 4, 5]).unwrap(); - w.write_all(&[6, 7]).unwrap(); - assert_eq!(w.stream_position().ok(), Some(8)); - assert_eq!(&w.get_ref().get_ref()[..], &[0, 1, 2, 3, 4, 5, 6, 7][..]); - assert_eq!(w.seek(SeekFrom::Start(2)).ok(), Some(2)); - w.write_all(&[8, 9]).unwrap(); - assert_eq!(&w.into_inner().unwrap().into_inner()[..], &[0, 1, 8, 9, 4, 5, 6, 7]); -} - -#[test] -fn test_read_until() { - let inner: &[u8] = &[0, 1, 2, 1, 0]; - let mut reader = BufReader::with_capacity(2, inner); - let mut v = Vec::new(); - reader.read_until(0, &mut v).unwrap(); - assert_eq!(v, [0]); - v.truncate(0); - reader.read_until(2, &mut v).unwrap(); - assert_eq!(v, [1, 2]); - v.truncate(0); - reader.read_until(1, &mut v).unwrap(); - assert_eq!(v, [1]); - v.truncate(0); - reader.read_until(8, &mut v).unwrap(); - assert_eq!(v, [0]); - v.truncate(0); - reader.read_until(9, &mut v).unwrap(); - assert_eq!(v, []); -} - -#[test] -fn test_line_buffer() { - let mut writer = LineWriter::new(Vec::new()); - writer.write(&[0]).unwrap(); - assert_eq!(*writer.get_ref(), []); - writer.write(&[1]).unwrap(); - assert_eq!(*writer.get_ref(), []); - writer.flush().unwrap(); - assert_eq!(*writer.get_ref(), [0, 1]); - writer.write(&[0, b'\n', 1, b'\n', 2]).unwrap(); - assert_eq!(*writer.get_ref(), [0, 1, 0, b'\n', 1, b'\n']); - writer.flush().unwrap(); - assert_eq!(*writer.get_ref(), [0, 1, 0, b'\n', 1, b'\n', 2]); - writer.write(&[3, b'\n']).unwrap(); - assert_eq!(*writer.get_ref(), [0, 1, 0, b'\n', 1, b'\n', 2, 3, b'\n']); -} - -#[test] -fn test_read_line() { - let in_buf: &[u8] = b"a\nb\nc"; - let mut reader = BufReader::with_capacity(2, in_buf); - let mut s = String::new(); - reader.read_line(&mut s).unwrap(); - assert_eq!(s, "a\n"); - s.truncate(0); - reader.read_line(&mut s).unwrap(); - assert_eq!(s, "b\n"); - s.truncate(0); - reader.read_line(&mut s).unwrap(); - assert_eq!(s, "c"); - s.truncate(0); - reader.read_line(&mut s).unwrap(); - assert_eq!(s, ""); -} - -#[test] -fn test_lines() { - let in_buf: &[u8] = b"a\nb\nc"; - let reader = BufReader::with_capacity(2, in_buf); - let mut it = reader.lines(); - assert_eq!(it.next().unwrap().unwrap(), "a".to_string()); - assert_eq!(it.next().unwrap().unwrap(), "b".to_string()); - assert_eq!(it.next().unwrap().unwrap(), "c".to_string()); - assert!(it.next().is_none()); -} - -#[test] -fn test_short_reads() { - let inner = ShortReader { lengths: vec![0, 1, 2, 0, 1, 0] }; - let mut reader = BufReader::new(inner); - let mut buf = [0, 0]; - assert_eq!(reader.read(&mut buf).unwrap(), 0); - assert_eq!(reader.read(&mut buf).unwrap(), 1); - assert_eq!(reader.read(&mut buf).unwrap(), 2); - assert_eq!(reader.read(&mut buf).unwrap(), 0); - assert_eq!(reader.read(&mut buf).unwrap(), 1); - assert_eq!(reader.read(&mut buf).unwrap(), 0); - assert_eq!(reader.read(&mut buf).unwrap(), 0); -} - -#[test] -#[should_panic] -fn dont_panic_in_drop_on_panicked_flush() { - struct FailFlushWriter; - - impl Write for FailFlushWriter { - fn write(&mut self, buf: &[u8]) -> io::Result { - Ok(buf.len()) - } - fn flush(&mut self) -> io::Result<()> { - Err(io::Error::last_os_error()) - } - } - - let writer = FailFlushWriter; - let _writer = BufWriter::new(writer); - - // If writer panics *again* due to the flush error then the process will - // abort. - panic!(); -} - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn panic_in_write_doesnt_flush_in_drop() { - static WRITES: AtomicUsize = AtomicUsize::new(0); - - struct PanicWriter; - - impl Write for PanicWriter { - fn write(&mut self, _: &[u8]) -> io::Result { - WRITES.fetch_add(1, Ordering::SeqCst); - panic!(); - } - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } - } - - thread::spawn(|| { - let mut writer = BufWriter::new(PanicWriter); - let _ = writer.write(b"hello world"); - let _ = writer.flush(); - }) - .join() - .unwrap_err(); - - assert_eq!(WRITES.load(Ordering::SeqCst), 1); -} - -#[bench] -fn bench_buffered_reader(b: &mut test::Bencher) { - b.iter(|| BufReader::new(io::empty())); -} - -#[bench] -fn bench_buffered_reader_small_reads(b: &mut test::Bencher) { - let data = (0..u8::MAX).cycle().take(1024 * 4).collect::>(); - b.iter(|| { - let mut reader = BufReader::new(&data[..]); - let mut buf = [0u8; 4]; - for _ in 0..1024 { - reader.read_exact(&mut buf).unwrap(); - core::hint::black_box(&buf); - } - }); -} - -#[bench] -fn bench_buffered_writer(b: &mut test::Bencher) { - b.iter(|| BufWriter::new(io::sink())); -} - -/// A simple `Write` target, designed to be wrapped by `LineWriter` / -/// `BufWriter` / etc, that can have its `write` & `flush` behavior -/// configured -#[derive(Default, Clone)] -struct ProgrammableSink { - // Writes append to this slice - pub buffer: Vec, - - // If true, writes will always be an error - pub always_write_error: bool, - - // If true, flushes will always be an error - pub always_flush_error: bool, - - // If set, only up to this number of bytes will be written in a single - // call to `write` - pub accept_prefix: Option, - - // If set, counts down with each write, and writes return an error - // when it hits 0 - pub max_writes: Option, - - // If set, attempting to write when max_writes == Some(0) will be an - // error; otherwise, it will return Ok(0). - pub error_after_max_writes: bool, -} - -impl Write for ProgrammableSink { - fn write(&mut self, data: &[u8]) -> io::Result { - if self.always_write_error { - return Err(io::Error::new(io::ErrorKind::Other, "test - always_write_error")); - } - - match self.max_writes { - Some(0) if self.error_after_max_writes => { - return Err(io::Error::new(io::ErrorKind::Other, "test - max_writes")); - } - Some(0) => return Ok(0), - Some(ref mut count) => *count -= 1, - None => {} - } - - let len = match self.accept_prefix { - None => data.len(), - Some(prefix) => data.len().min(prefix), - }; - - let data = &data[..len]; - self.buffer.extend_from_slice(data); - - Ok(len) - } - - fn flush(&mut self) -> io::Result<()> { - if self.always_flush_error { - Err(io::Error::new(io::ErrorKind::Other, "test - always_flush_error")) - } else { - Ok(()) - } - } -} - -/// Previously the `LineWriter` could successfully write some bytes but -/// then fail to report that it has done so. Additionally, an erroneous -/// flush after a successful write was permanently ignored. -/// -/// Test that a line writer correctly reports the number of written bytes, -/// and that it attempts to flush buffered lines from previous writes -/// before processing new data -/// -/// Regression test for #37807 -#[test] -fn erroneous_flush_retried() { - let writer = ProgrammableSink { - // Only write up to 4 bytes at a time - accept_prefix: Some(4), - - // Accept the first two writes, then error the others - max_writes: Some(2), - error_after_max_writes: true, - - ..Default::default() - }; - - // This should write the first 4 bytes. The rest will be buffered, out - // to the last newline. - let mut writer = LineWriter::new(writer); - assert_eq!(writer.write(b"a\nb\nc\nd\ne").unwrap(), 8); - - // This write should attempt to flush "c\nd\n", then buffer "e". No - // errors should happen here because no further writes should be - // attempted against `writer`. - assert_eq!(writer.write(b"e").unwrap(), 1); - assert_eq!(&writer.get_ref().buffer, b"a\nb\nc\nd\n"); -} - -#[test] -fn line_vectored() { - let mut a = LineWriter::new(Vec::new()); - assert_eq!( - a.write_vectored(&[ - IoSlice::new(&[]), - IoSlice::new(b"\n"), - IoSlice::new(&[]), - IoSlice::new(b"a"), - ]) - .unwrap(), - 2, - ); - assert_eq!(a.get_ref(), b"\n"); - - assert_eq!( - a.write_vectored(&[ - IoSlice::new(&[]), - IoSlice::new(b"b"), - IoSlice::new(&[]), - IoSlice::new(b"a"), - IoSlice::new(&[]), - IoSlice::new(b"c"), - ]) - .unwrap(), - 3, - ); - assert_eq!(a.get_ref(), b"\n"); - a.flush().unwrap(); - assert_eq!(a.get_ref(), b"\nabac"); - assert_eq!(a.write_vectored(&[]).unwrap(), 0); - assert_eq!( - a.write_vectored(&[ - IoSlice::new(&[]), - IoSlice::new(&[]), - IoSlice::new(&[]), - IoSlice::new(&[]), - ]) - .unwrap(), - 0, - ); - assert_eq!(a.write_vectored(&[IoSlice::new(b"a\nb"),]).unwrap(), 3); - assert_eq!(a.get_ref(), b"\nabaca\nb"); -} - -#[test] -fn line_vectored_partial_and_errors() { - use crate::collections::VecDeque; - - enum Call { - Write { inputs: Vec<&'static [u8]>, output: io::Result }, - Flush { output: io::Result<()> }, - } - - #[derive(Default)] - struct Writer { - calls: VecDeque, - } - - impl Write for Writer { - fn write(&mut self, buf: &[u8]) -> io::Result { - self.write_vectored(&[IoSlice::new(buf)]) - } - - fn write_vectored(&mut self, buf: &[IoSlice<'_>]) -> io::Result { - match self.calls.pop_front().expect("unexpected call to write") { - Call::Write { inputs, output } => { - assert_eq!(inputs, buf.iter().map(|b| &**b).collect::>()); - output - } - Call::Flush { .. } => panic!("unexpected call to write; expected a flush"), - } - } - - fn is_write_vectored(&self) -> bool { - true - } - - fn flush(&mut self) -> io::Result<()> { - match self.calls.pop_front().expect("Unexpected call to flush") { - Call::Flush { output } => output, - Call::Write { .. } => panic!("unexpected call to flush; expected a write"), - } - } - } - - impl Drop for Writer { - fn drop(&mut self) { - if !thread::panicking() { - assert_eq!(self.calls.len(), 0); - } - } - } - - // partial writes keep going - let mut a = LineWriter::new(Writer::default()); - a.write_vectored(&[IoSlice::new(&[]), IoSlice::new(b"abc")]).unwrap(); - - a.get_mut().calls.push_back(Call::Write { inputs: vec![b"abc"], output: Ok(1) }); - a.get_mut().calls.push_back(Call::Write { inputs: vec![b"bc"], output: Ok(2) }); - a.get_mut().calls.push_back(Call::Write { inputs: vec![b"x", b"\n"], output: Ok(2) }); - - a.write_vectored(&[IoSlice::new(b"x"), IoSlice::new(b"\n")]).unwrap(); - - a.get_mut().calls.push_back(Call::Flush { output: Ok(()) }); - a.flush().unwrap(); - - // erroneous writes stop and don't write more - a.get_mut().calls.push_back(Call::Write { inputs: vec![b"x", b"\na"], output: Err(err()) }); - a.get_mut().calls.push_back(Call::Flush { output: Ok(()) }); - assert!(a.write_vectored(&[IoSlice::new(b"x"), IoSlice::new(b"\na")]).is_err()); - a.flush().unwrap(); - - fn err() -> io::Error { - io::Error::new(io::ErrorKind::Other, "x") - } -} - -/// Test that, in cases where vectored writing is not enabled, the -/// LineWriter uses the normal `write` call, which more-correctly handles -/// partial lines -#[test] -fn line_vectored_ignored() { - let writer = ProgrammableSink::default(); - let mut writer = LineWriter::new(writer); - - let content = [ - IoSlice::new(&[]), - IoSlice::new(b"Line 1\nLine"), - IoSlice::new(b" 2\nLine 3\nL"), - IoSlice::new(&[]), - IoSlice::new(&[]), - IoSlice::new(b"ine 4"), - IoSlice::new(b"\nLine 5\n"), - ]; - - let count = writer.write_vectored(&content).unwrap(); - assert_eq!(count, 11); - assert_eq!(&writer.get_ref().buffer, b"Line 1\n"); - - let count = writer.write_vectored(&content[2..]).unwrap(); - assert_eq!(count, 11); - assert_eq!(&writer.get_ref().buffer, b"Line 1\nLine 2\nLine 3\n"); - - let count = writer.write_vectored(&content[5..]).unwrap(); - assert_eq!(count, 5); - assert_eq!(&writer.get_ref().buffer, b"Line 1\nLine 2\nLine 3\n"); - - let count = writer.write_vectored(&content[6..]).unwrap(); - assert_eq!(count, 8); - assert_eq!( - writer.get_ref().buffer.as_slice(), - b"Line 1\nLine 2\nLine 3\nLine 4\nLine 5\n".as_ref() - ); -} - -/// Test that, given this input: -/// -/// Line 1\n -/// Line 2\n -/// Line 3\n -/// Line 4 -/// -/// And given a result that only writes to midway through Line 2 -/// -/// That only up to the end of Line 3 is buffered -/// -/// This behavior is desirable because it prevents flushing partial lines -#[test] -fn partial_write_buffers_line() { - let writer = ProgrammableSink { accept_prefix: Some(13), ..Default::default() }; - let mut writer = LineWriter::new(writer); - - assert_eq!(writer.write(b"Line 1\nLine 2\nLine 3\nLine4").unwrap(), 21); - assert_eq!(&writer.get_ref().buffer, b"Line 1\nLine 2"); - - assert_eq!(writer.write(b"Line 4").unwrap(), 6); - assert_eq!(&writer.get_ref().buffer, b"Line 1\nLine 2\nLine 3\n"); -} - -/// Test that, given this input: -/// -/// Line 1\n -/// Line 2\n -/// Line 3 -/// -/// And given that the full write of lines 1 and 2 was successful -/// That data up to Line 3 is buffered -#[test] -fn partial_line_buffered_after_line_write() { - let writer = ProgrammableSink::default(); - let mut writer = LineWriter::new(writer); - - assert_eq!(writer.write(b"Line 1\nLine 2\nLine 3").unwrap(), 20); - assert_eq!(&writer.get_ref().buffer, b"Line 1\nLine 2\n"); - - assert!(writer.flush().is_ok()); - assert_eq!(&writer.get_ref().buffer, b"Line 1\nLine 2\nLine 3"); -} - -/// Test that for calls to LineBuffer::write where the passed bytes do not contain -/// a newline and on their own are greater in length than the internal buffer, the -/// passed bytes are immediately written to the inner writer. -#[test] -fn long_line_flushed() { - let writer = ProgrammableSink::default(); - let mut writer = LineWriter::with_capacity(5, writer); - - assert_eq!(writer.write(b"0123456789").unwrap(), 10); - assert_eq!(&writer.get_ref().buffer, b"0123456789"); -} - -/// Test that, given a very long partial line *after* successfully -/// flushing a complete line, the very long partial line is buffered -/// unconditionally, and no additional writes take place. This assures -/// the property that `write` should make at-most-one attempt to write -/// new data. -#[test] -fn line_long_tail_not_flushed() { - let writer = ProgrammableSink::default(); - let mut writer = LineWriter::with_capacity(5, writer); - - // Assert that Line 1\n is flushed, and 01234 is buffered - assert_eq!(writer.write(b"Line 1\n0123456789").unwrap(), 12); - assert_eq!(&writer.get_ref().buffer, b"Line 1\n"); - - // Because the buffer is full, this subsequent write will flush it - assert_eq!(writer.write(b"5").unwrap(), 1); - assert_eq!(&writer.get_ref().buffer, b"Line 1\n01234"); -} - -/// Test that, if an attempt to pre-flush buffered data returns Ok(0), -/// this is propagated as an error. -#[test] -fn line_buffer_write0_error() { - let writer = ProgrammableSink { - // Accept one write, then return Ok(0) on subsequent ones - max_writes: Some(1), - - ..Default::default() - }; - let mut writer = LineWriter::new(writer); - - // This should write "Line 1\n" and buffer "Partial" - assert_eq!(writer.write(b"Line 1\nPartial").unwrap(), 14); - assert_eq!(&writer.get_ref().buffer, b"Line 1\n"); - - // This will attempt to flush "partial", which will return Ok(0), which - // needs to be an error, because we've already informed the client - // that we accepted the write. - let err = writer.write(b" Line End\n").unwrap_err(); - assert_eq!(err.kind(), ErrorKind::WriteZero); - assert_eq!(&writer.get_ref().buffer, b"Line 1\n"); -} - -/// Test that, if a write returns Ok(0) after a successful pre-flush, this -/// is propagated as Ok(0) -#[test] -fn line_buffer_write0_normal() { - let writer = ProgrammableSink { - // Accept two writes, then return Ok(0) on subsequent ones - max_writes: Some(2), - - ..Default::default() - }; - let mut writer = LineWriter::new(writer); - - // This should write "Line 1\n" and buffer "Partial" - assert_eq!(writer.write(b"Line 1\nPartial").unwrap(), 14); - assert_eq!(&writer.get_ref().buffer, b"Line 1\n"); - - // This will flush partial, which will succeed, but then return Ok(0) - // when flushing " Line End\n" - assert_eq!(writer.write(b" Line End\n").unwrap(), 0); - assert_eq!(&writer.get_ref().buffer, b"Line 1\nPartial"); -} - -/// LineWriter has a custom `write_all`; make sure it works correctly -#[test] -fn line_write_all() { - let writer = ProgrammableSink { - // Only write 5 bytes at a time - accept_prefix: Some(5), - ..Default::default() - }; - let mut writer = LineWriter::new(writer); - - writer.write_all(b"Line 1\nLine 2\nLine 3\nLine 4\nPartial").unwrap(); - assert_eq!(&writer.get_ref().buffer, b"Line 1\nLine 2\nLine 3\nLine 4\n"); - writer.write_all(b" Line 5\n").unwrap(); - assert_eq!( - writer.get_ref().buffer.as_slice(), - b"Line 1\nLine 2\nLine 3\nLine 4\nPartial Line 5\n".as_ref(), - ); -} - -#[test] -fn line_write_all_error() { - let writer = ProgrammableSink { - // Only accept up to 3 writes of up to 5 bytes each - accept_prefix: Some(5), - max_writes: Some(3), - ..Default::default() - }; - - let mut writer = LineWriter::new(writer); - let res = writer.write_all(b"Line 1\nLine 2\nLine 3\nLine 4\nPartial"); - assert!(res.is_err()); - // An error from write_all leaves everything in an indeterminate state, - // so there's nothing else to test here -} - -/// Under certain circumstances, the old implementation of LineWriter -/// would try to buffer "to the last newline" but be forced to buffer -/// less than that, leading to inappropriate partial line writes. -/// Regression test for that issue. -#[test] -fn partial_multiline_buffering() { - let writer = ProgrammableSink { - // Write only up to 5 bytes at a time - accept_prefix: Some(5), - ..Default::default() - }; - - let mut writer = LineWriter::with_capacity(10, writer); - - let content = b"AAAAABBBBB\nCCCCDDDDDD\nEEE"; - - // When content is written, LineWriter will try to write blocks A, B, - // C, and D. Only block A will succeed. Under the old behavior, LineWriter - // would then try to buffer B, C and D, but because its capacity is 10, - // it will only be able to buffer B and C. We don't want to buffer - // partial lines concurrent with whole lines, so the correct behavior - // is to buffer only block B (out to the newline) - assert_eq!(writer.write(content).unwrap(), 11); - assert_eq!(writer.get_ref().buffer, *b"AAAAA"); - - writer.flush().unwrap(); - assert_eq!(writer.get_ref().buffer, *b"AAAAABBBBB\n"); -} - -/// Same as test_partial_multiline_buffering, but in the event NO full lines -/// fit in the buffer, just buffer as much as possible -#[test] -fn partial_multiline_buffering_without_full_line() { - let writer = ProgrammableSink { - // Write only up to 5 bytes at a time - accept_prefix: Some(5), - ..Default::default() - }; - - let mut writer = LineWriter::with_capacity(5, writer); - - let content = b"AAAAABBBBBBBBBB\nCCCCC\nDDDDD"; - - // When content is written, LineWriter will try to write blocks A, B, - // and C. Only block A will succeed. Under the old behavior, LineWriter - // would then try to buffer B and C, but because its capacity is 5, - // it will only be able to buffer part of B. Because it's not possible - // for it to buffer any complete lines, it should buffer as much of B as - // possible - assert_eq!(writer.write(content).unwrap(), 10); - assert_eq!(writer.get_ref().buffer, *b"AAAAA"); - - writer.flush().unwrap(); - assert_eq!(writer.get_ref().buffer, *b"AAAAABBBBB"); -} - -#[derive(Debug, Clone, PartialEq, Eq)] -enum RecordedEvent { - Write(String), - Flush, -} - -#[derive(Debug, Clone, Default)] -struct WriteRecorder { - pub events: Vec, -} - -impl Write for WriteRecorder { - fn write(&mut self, buf: &[u8]) -> io::Result { - use crate::str::from_utf8; - - self.events.push(RecordedEvent::Write(from_utf8(buf).unwrap().to_string())); - Ok(buf.len()) - } - - fn flush(&mut self) -> io::Result<()> { - self.events.push(RecordedEvent::Flush); - Ok(()) - } -} - -/// Test that a normal, formatted writeln only results in a single write -/// call to the underlying writer. A naive implementation of -/// LineWriter::write_all results in two writes: one of the buffered data, -/// and another of the final substring in the formatted set -#[test] -fn single_formatted_write() { - let writer = WriteRecorder::default(); - let mut writer = LineWriter::new(writer); - - // Under a naive implementation of LineWriter, this will result in two - // writes: "hello, world" and "!\n", because write() has to flush the - // buffer before attempting to write the last "!\n". write_all shouldn't - // have this limitation. - writeln!(&mut writer, "{}, {}!", "hello", "world").unwrap(); - assert_eq!(writer.get_ref().events, [RecordedEvent::Write("hello, world!\n".to_string())]); -} - -#[test] -fn bufreader_full_initialize() { - struct OneByteReader; - impl Read for OneByteReader { - fn read(&mut self, buf: &mut [u8]) -> crate::io::Result { - if buf.len() > 0 { - buf[0] = 0; - Ok(1) - } else { - Ok(0) - } - } - } - let mut reader = BufReader::new(OneByteReader); - // Nothing is initialized yet. - assert_eq!(reader.initialized(), 0); - - let buf = reader.fill_buf().unwrap(); - // We read one byte... - assert_eq!(buf.len(), 1); - // But we initialized the whole buffer! - assert_eq!(reader.initialized(), reader.capacity()); -} diff --git a/library/std/src/io/copy.rs b/library/std/src/io/copy.rs deleted file mode 100644 index d49866345cbf6..0000000000000 --- a/library/std/src/io/copy.rs +++ /dev/null @@ -1,294 +0,0 @@ -use super::{BorrowedBuf, BufReader, BufWriter, Read, Result, Write, DEFAULT_BUF_SIZE}; -use crate::alloc::Allocator; -use crate::cmp; -use crate::collections::VecDeque; -use crate::io::IoSlice; -use crate::mem::MaybeUninit; - -#[cfg(test)] -mod tests; - -/// Copies the entire contents of a reader into a writer. -/// -/// This function will continuously read data from `reader` and then -/// write it into `writer` in a streaming fashion until `reader` -/// returns EOF. -/// -/// On success, the total number of bytes that were copied from -/// `reader` to `writer` is returned. -/// -/// If you want to copy the contents of one file to another and you’re -/// working with filesystem paths, see the [`fs::copy`] function. -/// -/// [`fs::copy`]: crate::fs::copy -/// -/// # Errors -/// -/// This function will return an error immediately if any call to [`read`] or -/// [`write`] returns an error. All instances of [`ErrorKind::Interrupted`] are -/// handled by this function and the underlying operation is retried. -/// -/// [`read`]: Read::read -/// [`write`]: Write::write -/// [`ErrorKind::Interrupted`]: crate::io::ErrorKind::Interrupted -/// -/// # Examples -/// -/// ``` -/// use std::io; -/// -/// fn main() -> io::Result<()> { -/// let mut reader: &[u8] = b"hello"; -/// let mut writer: Vec = vec![]; -/// -/// io::copy(&mut reader, &mut writer)?; -/// -/// assert_eq!(&b"hello"[..], &writer[..]); -/// Ok(()) -/// } -/// ``` -/// -/// # Platform-specific behavior -/// -/// On Linux (including Android), this function uses `copy_file_range(2)`, -/// `sendfile(2)` or `splice(2)` syscalls to move data directly between file -/// descriptors if possible. -/// -/// Note that platform-specific behavior [may change in the future][changes]. -/// -/// [changes]: crate::io#platform-specific-behavior -#[stable(feature = "rust1", since = "1.0.0")] -pub fn copy(reader: &mut R, writer: &mut W) -> Result -where - R: Read, - W: Write, -{ - cfg_if::cfg_if! { - if #[cfg(any(target_os = "linux", target_os = "android"))] { - crate::sys::kernel_copy::copy_spec(reader, writer) - } else { - generic_copy(reader, writer) - } - } -} - -/// The userspace read-write-loop implementation of `io::copy` that is used when -/// OS-specific specializations for copy offloading are not available or not applicable. -pub(crate) fn generic_copy(reader: &mut R, writer: &mut W) -> Result -where - R: Read, - W: Write, -{ - let read_buf = BufferedReaderSpec::buffer_size(reader); - let write_buf = BufferedWriterSpec::buffer_size(writer); - - if read_buf >= DEFAULT_BUF_SIZE && read_buf >= write_buf { - return BufferedReaderSpec::copy_to(reader, writer); - } - - BufferedWriterSpec::copy_from(writer, reader) -} - -/// Specialization of the read-write loop that reuses the internal -/// buffer of a BufReader. If there's no buffer then the writer side -/// should be used instead. -trait BufferedReaderSpec { - fn buffer_size(&self) -> usize; - - fn copy_to(&mut self, to: &mut (impl Write + ?Sized)) -> Result; -} - -impl BufferedReaderSpec for T -where - Self: Read, - T: ?Sized, -{ - #[inline] - default fn buffer_size(&self) -> usize { - 0 - } - - default fn copy_to(&mut self, _to: &mut (impl Write + ?Sized)) -> Result { - unreachable!("only called from specializations") - } -} - -impl BufferedReaderSpec for &[u8] { - fn buffer_size(&self) -> usize { - // prefer this specialization since the source "buffer" is all we'll ever need, - // even if it's small - usize::MAX - } - - fn copy_to(&mut self, to: &mut (impl Write + ?Sized)) -> Result { - let len = self.len(); - to.write_all(self)?; - *self = &self[len..]; - Ok(len as u64) - } -} - -impl BufferedReaderSpec for VecDeque { - fn buffer_size(&self) -> usize { - // prefer this specialization since the source "buffer" is all we'll ever need, - // even if it's small - usize::MAX - } - - fn copy_to(&mut self, to: &mut (impl Write + ?Sized)) -> Result { - let len = self.len(); - let (front, back) = self.as_slices(); - let bufs = &mut [IoSlice::new(front), IoSlice::new(back)]; - to.write_all_vectored(bufs)?; - self.clear(); - Ok(len as u64) - } -} - -impl BufferedReaderSpec for BufReader -where - Self: Read, - I: ?Sized, -{ - fn buffer_size(&self) -> usize { - self.capacity() - } - - fn copy_to(&mut self, to: &mut (impl Write + ?Sized)) -> Result { - let mut len = 0; - - loop { - // Hack: this relies on `impl Read for BufReader` always calling fill_buf - // if the buffer is empty, even for empty slices. - // It can't be called directly here since specialization prevents us - // from adding I: Read - match self.read(&mut []) { - Ok(_) => {} - Err(e) if e.is_interrupted() => continue, - Err(e) => return Err(e), - } - let buf = self.buffer(); - if self.buffer().len() == 0 { - return Ok(len); - } - - // In case the writer side is a BufWriter then its write_all - // implements an optimization that passes through large - // buffers to the underlying writer. That code path is #[cold] - // but we're still avoiding redundant memcopies when doing - // a copy between buffered inputs and outputs. - to.write_all(buf)?; - len += buf.len() as u64; - self.discard_buffer(); - } - } -} - -/// Specialization of the read-write loop that either uses a stack buffer -/// or reuses the internal buffer of a BufWriter -trait BufferedWriterSpec: Write { - fn buffer_size(&self) -> usize; - - fn copy_from(&mut self, reader: &mut R) -> Result; -} - -impl BufferedWriterSpec for W { - #[inline] - default fn buffer_size(&self) -> usize { - 0 - } - - default fn copy_from(&mut self, reader: &mut R) -> Result { - stack_buffer_copy(reader, self) - } -} - -impl BufferedWriterSpec for BufWriter { - fn buffer_size(&self) -> usize { - self.capacity() - } - - fn copy_from(&mut self, reader: &mut R) -> Result { - if self.capacity() < DEFAULT_BUF_SIZE { - return stack_buffer_copy(reader, self); - } - - let mut len = 0; - let mut init = 0; - - loop { - let buf = self.buffer_mut(); - let mut read_buf: BorrowedBuf<'_> = buf.spare_capacity_mut().into(); - - unsafe { - // SAFETY: init is either 0 or the init_len from the previous iteration. - read_buf.set_init(init); - } - - if read_buf.capacity() >= DEFAULT_BUF_SIZE { - let mut cursor = read_buf.unfilled(); - match reader.read_buf(cursor.reborrow()) { - Ok(()) => { - let bytes_read = cursor.written(); - - if bytes_read == 0 { - return Ok(len); - } - - init = read_buf.init_len() - bytes_read; - len += bytes_read as u64; - - // SAFETY: BorrowedBuf guarantees all of its filled bytes are init - unsafe { buf.set_len(buf.len() + bytes_read) }; - - // Read again if the buffer still has enough capacity, as BufWriter itself would do - // This will occur if the reader returns short reads - } - Err(ref e) if e.is_interrupted() => {} - Err(e) => return Err(e), - } - } else { - self.flush_buf()?; - init = 0; - } - } - } -} - -impl BufferedWriterSpec for Vec { - fn buffer_size(&self) -> usize { - cmp::max(DEFAULT_BUF_SIZE, self.capacity() - self.len()) - } - - fn copy_from(&mut self, reader: &mut R) -> Result { - reader.read_to_end(self).map(|bytes| u64::try_from(bytes).expect("usize overflowed u64")) - } -} - -pub fn stack_buffer_copy( - reader: &mut R, - writer: &mut W, -) -> Result { - let buf: &mut [_] = &mut [MaybeUninit::uninit(); DEFAULT_BUF_SIZE]; - let mut buf: BorrowedBuf<'_> = buf.into(); - - let mut len = 0; - - loop { - match reader.read_buf(buf.unfilled()) { - Ok(()) => {} - Err(e) if e.is_interrupted() => continue, - Err(e) => return Err(e), - }; - - if buf.filled().is_empty() { - break; - } - - len += buf.filled().len() as u64; - writer.write_all(buf.filled())?; - buf.clear(); - } - - Ok(len) -} diff --git a/library/std/src/io/copy/tests.rs b/library/std/src/io/copy/tests.rs deleted file mode 100644 index a1f909a3c5386..0000000000000 --- a/library/std/src/io/copy/tests.rs +++ /dev/null @@ -1,147 +0,0 @@ -use crate::cmp::{max, min}; -use crate::collections::VecDeque; -use crate::io; -use crate::io::*; - -#[test] -fn copy_copies() { - let mut r = repeat(0).take(4); - let mut w = sink(); - assert_eq!(copy(&mut r, &mut w).unwrap(), 4); - - let mut r = repeat(0).take(1 << 17); - assert_eq!(copy(&mut r as &mut dyn Read, &mut w as &mut dyn Write).unwrap(), 1 << 17); -} - -struct ShortReader { - cap: usize, - read_size: usize, - observed_buffer: usize, -} - -impl Read for ShortReader { - fn read(&mut self, buf: &mut [u8]) -> Result { - let bytes = min(self.cap, self.read_size).min(buf.len()); - self.cap -= bytes; - self.observed_buffer = max(self.observed_buffer, buf.len()); - Ok(bytes) - } -} - -struct WriteObserver { - observed_buffer: usize, -} - -impl Write for WriteObserver { - fn write(&mut self, buf: &[u8]) -> Result { - self.observed_buffer = max(self.observed_buffer, buf.len()); - Ok(buf.len()) - } - - fn flush(&mut self) -> Result<()> { - Ok(()) - } -} - -#[test] -fn copy_specializes_bufwriter() { - let cap = 117 * 1024; - let buf_sz = 16 * 1024; - let mut r = ShortReader { cap, observed_buffer: 0, read_size: 1337 }; - let mut w = BufWriter::with_capacity(buf_sz, WriteObserver { observed_buffer: 0 }); - assert_eq!( - copy(&mut r, &mut w).unwrap(), - cap as u64, - "expected the whole capacity to be copied" - ); - assert_eq!(r.observed_buffer, buf_sz, "expected a large buffer to be provided to the reader"); - assert!(w.get_mut().observed_buffer > DEFAULT_BUF_SIZE, "expected coalesced writes"); -} - -#[test] -fn copy_specializes_bufreader() { - let mut source = vec![0; 768 * 1024]; - source[1] = 42; - let mut buffered = BufReader::with_capacity(256 * 1024, Cursor::new(&mut source)); - - let mut sink = Vec::new(); - assert_eq!(crate::io::copy(&mut buffered, &mut sink).unwrap(), source.len() as u64); - assert_eq!(source.as_slice(), sink.as_slice()); - - let buf_sz = 71 * 1024; - assert!(buf_sz > DEFAULT_BUF_SIZE, "test precondition"); - - let mut buffered = BufReader::with_capacity(buf_sz, Cursor::new(&mut source)); - let mut sink = WriteObserver { observed_buffer: 0 }; - assert_eq!(crate::io::copy(&mut buffered, &mut sink).unwrap(), source.len() as u64); - assert_eq!( - sink.observed_buffer, buf_sz, - "expected a large buffer to be provided to the writer" - ); -} - -#[test] -fn copy_specializes_to_vec() { - let cap = DEFAULT_BUF_SIZE * 10; - let mut source = ShortReader { cap, observed_buffer: 0, read_size: DEFAULT_BUF_SIZE }; - let mut sink = Vec::new(); - let copied = io::copy(&mut source, &mut sink).unwrap(); - assert_eq!(cap as u64, copied); - assert_eq!(sink.len() as u64, copied); - assert!( - source.observed_buffer > DEFAULT_BUF_SIZE, - "expected a large buffer to be provided to the reader, got {}", - source.observed_buffer - ); -} - -#[test] -fn copy_specializes_from_vecdeque() { - let mut source = VecDeque::with_capacity(100 * 1024); - for _ in 0..20 * 1024 { - source.push_front(0); - } - for _ in 0..20 * 1024 { - source.push_back(0); - } - let mut sink = WriteObserver { observed_buffer: 0 }; - assert_eq!(40 * 1024u64, io::copy(&mut source, &mut sink).unwrap()); - assert_eq!(20 * 1024, sink.observed_buffer); -} - -#[test] -fn copy_specializes_from_slice() { - let mut source = [1; 60 * 1024].as_slice(); - let mut sink = WriteObserver { observed_buffer: 0 }; - assert_eq!(60 * 1024u64, io::copy(&mut source, &mut sink).unwrap()); - assert_eq!(60 * 1024, sink.observed_buffer); -} - -#[cfg(unix)] -mod io_benches { - use crate::fs::File; - use crate::fs::OpenOptions; - use crate::io::prelude::*; - use crate::io::BufReader; - - use test::Bencher; - - #[bench] - fn bench_copy_buf_reader(b: &mut Bencher) { - let mut file_in = File::open("/dev/zero").expect("opening /dev/zero failed"); - // use dyn to avoid specializations unrelated to readbuf - let dyn_in = &mut file_in as &mut dyn Read; - let mut reader = BufReader::with_capacity(256 * 1024, dyn_in.take(0)); - let mut writer = - OpenOptions::new().write(true).open("/dev/null").expect("opening /dev/null failed"); - - const BYTES: u64 = 1024 * 1024; - - b.bytes = BYTES; - - b.iter(|| { - reader.get_mut().set_limit(BYTES); - crate::io::copy(&mut reader, &mut writer).unwrap() - }); - } -} diff --git a/library/std/src/io/cursor.rs b/library/std/src/io/cursor.rs deleted file mode 100644 index a1a8b2a3505c7..0000000000000 --- a/library/std/src/io/cursor.rs +++ /dev/null @@ -1,677 +0,0 @@ -#[cfg(test)] -mod tests; - -use crate::io::prelude::*; - -use crate::alloc::Allocator; -use crate::cmp; -use crate::io::{self, BorrowedCursor, ErrorKind, IoSlice, IoSliceMut, SeekFrom}; - -/// A `Cursor` wraps an in-memory buffer and provides it with a -/// [`Seek`] implementation. -/// -/// `Cursor`s are used with in-memory buffers, anything implementing -/// [AsRef]<\[u8]>, to allow them to implement [`Read`] and/or [`Write`], -/// allowing these buffers to be used anywhere you might use a reader or writer -/// that does actual I/O. -/// -/// The standard library implements some I/O traits on various types which -/// are commonly used as a buffer, like Cursor<[Vec]\> and -/// Cursor<[&\[u8\]][bytes]>. -/// -/// # Examples -/// -/// We may want to write bytes to a [`File`] in our production -/// code, but use an in-memory buffer in our tests. We can do this with -/// `Cursor`: -/// -/// [bytes]: crate::slice "slice" -/// [`File`]: crate::fs::File -/// -/// ```no_run -/// use std::io::prelude::*; -/// use std::io::{self, SeekFrom}; -/// use std::fs::File; -/// -/// // a library function we've written -/// fn write_ten_bytes_at_end(mut writer: W) -> io::Result<()> { -/// writer.seek(SeekFrom::End(-10))?; -/// -/// for i in 0..10 { -/// writer.write(&[i])?; -/// } -/// -/// // all went well -/// Ok(()) -/// } -/// -/// # fn foo() -> io::Result<()> { -/// // Here's some code that uses this library function. -/// // -/// // We might want to use a BufReader here for efficiency, but let's -/// // keep this example focused. -/// let mut file = File::create("foo.txt")?; -/// // First, we need to allocate 10 bytes to be able to write into. -/// file.set_len(10)?; -/// -/// write_ten_bytes_at_end(&mut file)?; -/// # Ok(()) -/// # } -/// -/// // now let's write a test -/// #[test] -/// fn test_writes_bytes() { -/// // setting up a real File is much slower than an in-memory buffer, -/// // let's use a cursor instead -/// use std::io::Cursor; -/// let mut buff = Cursor::new(vec![0; 15]); -/// -/// write_ten_bytes_at_end(&mut buff).unwrap(); -/// -/// assert_eq!(&buff.get_ref()[5..15], &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]); -/// } -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Debug, Default, Eq, PartialEq)] -pub struct Cursor { - inner: T, - pos: u64, -} - -impl Cursor { - /// Creates a new cursor wrapping the provided underlying in-memory buffer. - /// - /// Cursor initial position is `0` even if underlying buffer (e.g., [`Vec`]) - /// is not empty. So writing to cursor starts with overwriting [`Vec`] - /// content, not with appending to it. - /// - /// # Examples - /// - /// ``` - /// use std::io::Cursor; - /// - /// let buff = Cursor::new(Vec::new()); - /// # fn force_inference(_: &Cursor>) {} - /// # force_inference(&buff); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_io_structs", since = "1.79.0")] - pub const fn new(inner: T) -> Cursor { - Cursor { pos: 0, inner } - } - - /// Consumes this cursor, returning the underlying value. - /// - /// # Examples - /// - /// ``` - /// use std::io::Cursor; - /// - /// let buff = Cursor::new(Vec::new()); - /// # fn force_inference(_: &Cursor>) {} - /// # force_inference(&buff); - /// - /// let vec = buff.into_inner(); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn into_inner(self) -> T { - self.inner - } - - /// Gets a reference to the underlying value in this cursor. - /// - /// # Examples - /// - /// ``` - /// use std::io::Cursor; - /// - /// let buff = Cursor::new(Vec::new()); - /// # fn force_inference(_: &Cursor>) {} - /// # force_inference(&buff); - /// - /// let reference = buff.get_ref(); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_io_structs", since = "1.79.0")] - pub const fn get_ref(&self) -> &T { - &self.inner - } - - /// Gets a mutable reference to the underlying value in this cursor. - /// - /// Care should be taken to avoid modifying the internal I/O state of the - /// underlying value as it may corrupt this cursor's position. - /// - /// # Examples - /// - /// ``` - /// use std::io::Cursor; - /// - /// let mut buff = Cursor::new(Vec::new()); - /// # fn force_inference(_: &Cursor>) {} - /// # force_inference(&buff); - /// - /// let reference = buff.get_mut(); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn get_mut(&mut self) -> &mut T { - &mut self.inner - } - - /// Returns the current position of this cursor. - /// - /// # Examples - /// - /// ``` - /// use std::io::Cursor; - /// use std::io::prelude::*; - /// use std::io::SeekFrom; - /// - /// let mut buff = Cursor::new(vec![1, 2, 3, 4, 5]); - /// - /// assert_eq!(buff.position(), 0); - /// - /// buff.seek(SeekFrom::Current(2)).unwrap(); - /// assert_eq!(buff.position(), 2); - /// - /// buff.seek(SeekFrom::Current(-1)).unwrap(); - /// assert_eq!(buff.position(), 1); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_io_structs", since = "1.79.0")] - pub const fn position(&self) -> u64 { - self.pos - } - - /// Sets the position of this cursor. - /// - /// # Examples - /// - /// ``` - /// use std::io::Cursor; - /// - /// let mut buff = Cursor::new(vec![1, 2, 3, 4, 5]); - /// - /// assert_eq!(buff.position(), 0); - /// - /// buff.set_position(2); - /// assert_eq!(buff.position(), 2); - /// - /// buff.set_position(4); - /// assert_eq!(buff.position(), 4); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn set_position(&mut self, pos: u64) { - self.pos = pos; - } -} - -impl Cursor -where - T: AsRef<[u8]>, -{ - /// Returns the remaining slice. - /// - /// # Examples - /// - /// ``` - /// #![feature(cursor_remaining)] - /// use std::io::Cursor; - /// - /// let mut buff = Cursor::new(vec![1, 2, 3, 4, 5]); - /// - /// assert_eq!(buff.remaining_slice(), &[1, 2, 3, 4, 5]); - /// - /// buff.set_position(2); - /// assert_eq!(buff.remaining_slice(), &[3, 4, 5]); - /// - /// buff.set_position(4); - /// assert_eq!(buff.remaining_slice(), &[5]); - /// - /// buff.set_position(6); - /// assert_eq!(buff.remaining_slice(), &[]); - /// ``` - #[unstable(feature = "cursor_remaining", issue = "86369")] - pub fn remaining_slice(&self) -> &[u8] { - let len = self.pos.min(self.inner.as_ref().len() as u64); - &self.inner.as_ref()[(len as usize)..] - } - - /// Returns `true` if the remaining slice is empty. - /// - /// # Examples - /// - /// ``` - /// #![feature(cursor_remaining)] - /// use std::io::Cursor; - /// - /// let mut buff = Cursor::new(vec![1, 2, 3, 4, 5]); - /// - /// buff.set_position(2); - /// assert!(!buff.is_empty()); - /// - /// buff.set_position(5); - /// assert!(buff.is_empty()); - /// - /// buff.set_position(10); - /// assert!(buff.is_empty()); - /// ``` - #[unstable(feature = "cursor_remaining", issue = "86369")] - pub fn is_empty(&self) -> bool { - self.pos >= self.inner.as_ref().len() as u64 - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Cursor -where - T: Clone, -{ - #[inline] - fn clone(&self) -> Self { - Cursor { inner: self.inner.clone(), pos: self.pos } - } - - #[inline] - fn clone_from(&mut self, other: &Self) { - self.inner.clone_from(&other.inner); - self.pos = other.pos; - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl io::Seek for Cursor -where - T: AsRef<[u8]>, -{ - fn seek(&mut self, style: SeekFrom) -> io::Result { - let (base_pos, offset) = match style { - SeekFrom::Start(n) => { - self.pos = n; - return Ok(n); - } - SeekFrom::End(n) => (self.inner.as_ref().len() as u64, n), - SeekFrom::Current(n) => (self.pos, n), - }; - match base_pos.checked_add_signed(offset) { - Some(n) => { - self.pos = n; - Ok(self.pos) - } - None => Err(io::const_io_error!( - ErrorKind::InvalidInput, - "invalid seek to a negative or overflowing position", - )), - } - } - - fn stream_len(&mut self) -> io::Result { - Ok(self.inner.as_ref().len() as u64) - } - - fn stream_position(&mut self) -> io::Result { - Ok(self.pos) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Read for Cursor -where - T: AsRef<[u8]>, -{ - fn read(&mut self, buf: &mut [u8]) -> io::Result { - let n = Read::read(&mut self.remaining_slice(), buf)?; - self.pos += n as u64; - Ok(n) - } - - fn read_buf(&mut self, mut cursor: BorrowedCursor<'_>) -> io::Result<()> { - let prev_written = cursor.written(); - - Read::read_buf(&mut self.remaining_slice(), cursor.reborrow())?; - - self.pos += (cursor.written() - prev_written) as u64; - - Ok(()) - } - - fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - let mut nread = 0; - for buf in bufs { - let n = self.read(buf)?; - nread += n; - if n < buf.len() { - break; - } - } - Ok(nread) - } - - fn is_read_vectored(&self) -> bool { - true - } - - fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> { - let result = Read::read_exact(&mut self.remaining_slice(), buf); - - match result { - Ok(_) => self.pos += buf.len() as u64, - // The only possible error condition is EOF, so place the cursor at "EOF" - Err(_) => self.pos = self.inner.as_ref().len() as u64, - } - - result - } - - fn read_buf_exact(&mut self, mut cursor: BorrowedCursor<'_>) -> io::Result<()> { - let prev_written = cursor.written(); - - let result = Read::read_buf_exact(&mut self.remaining_slice(), cursor.reborrow()); - self.pos += (cursor.written() - prev_written) as u64; - - result - } - - fn read_to_end(&mut self, buf: &mut Vec) -> io::Result { - let content = self.remaining_slice(); - let len = content.len(); - buf.try_reserve(len)?; - buf.extend_from_slice(content); - self.pos += len as u64; - - Ok(len) - } - - fn read_to_string(&mut self, buf: &mut String) -> io::Result { - let content = - crate::str::from_utf8(self.remaining_slice()).map_err(|_| io::Error::INVALID_UTF8)?; - let len = content.len(); - buf.try_reserve(len)?; - buf.push_str(content); - self.pos += len as u64; - - Ok(len) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl BufRead for Cursor -where - T: AsRef<[u8]>, -{ - fn fill_buf(&mut self) -> io::Result<&[u8]> { - Ok(self.remaining_slice()) - } - fn consume(&mut self, amt: usize) { - self.pos += amt as u64; - } -} - -// Non-resizing write implementation -#[inline] -fn slice_write(pos_mut: &mut u64, slice: &mut [u8], buf: &[u8]) -> io::Result { - let pos = cmp::min(*pos_mut, slice.len() as u64); - let amt = (&mut slice[(pos as usize)..]).write(buf)?; - *pos_mut += amt as u64; - Ok(amt) -} - -#[inline] -fn slice_write_vectored( - pos_mut: &mut u64, - slice: &mut [u8], - bufs: &[IoSlice<'_>], -) -> io::Result { - let mut nwritten = 0; - for buf in bufs { - let n = slice_write(pos_mut, slice, buf)?; - nwritten += n; - if n < buf.len() { - break; - } - } - Ok(nwritten) -} - -/// Reserves the required space, and pads the vec with 0s if necessary. -fn reserve_and_pad( - pos_mut: &mut u64, - vec: &mut Vec, - buf_len: usize, -) -> io::Result { - let pos: usize = (*pos_mut).try_into().map_err(|_| { - io::const_io_error!( - ErrorKind::InvalidInput, - "cursor position exceeds maximum possible vector length", - ) - })?; - - // For safety reasons, we don't want these numbers to overflow - // otherwise our allocation won't be enough - let desired_cap = pos.saturating_add(buf_len); - if desired_cap > vec.capacity() { - // We want our vec's total capacity - // to have room for (pos+buf_len) bytes. Reserve allocates - // based on additional elements from the length, so we need to - // reserve the difference - vec.reserve(desired_cap - vec.len()); - } - // Pad if pos is above the current len. - if pos > vec.len() { - let diff = pos - vec.len(); - // Unfortunately, `resize()` would suffice but the optimiser does not - // realise the `reserve` it does can be eliminated. So we do it manually - // to eliminate that extra branch - let spare = vec.spare_capacity_mut(); - debug_assert!(spare.len() >= diff); - // Safety: we have allocated enough capacity for this. - // And we are only writing, not reading - unsafe { - spare.get_unchecked_mut(..diff).fill(core::mem::MaybeUninit::new(0)); - vec.set_len(pos); - } - } - - Ok(pos) -} - -/// Writes the slice to the vec without allocating -/// # Safety: vec must have buf.len() spare capacity -unsafe fn vec_write_unchecked(pos: usize, vec: &mut Vec, buf: &[u8]) -> usize -where - A: Allocator, -{ - debug_assert!(vec.capacity() >= pos + buf.len()); - vec.as_mut_ptr().add(pos).copy_from(buf.as_ptr(), buf.len()); - pos + buf.len() -} - -/// Resizing write implementation for [`Cursor`] -/// -/// Cursor is allowed to have a pre-allocated and initialised -/// vector body, but with a position of 0. This means the [`Write`] -/// will overwrite the contents of the vec. -/// -/// This also allows for the vec body to be empty, but with a position of N. -/// This means that [`Write`] will pad the vec with 0 initially, -/// before writing anything from that point -fn vec_write(pos_mut: &mut u64, vec: &mut Vec, buf: &[u8]) -> io::Result -where - A: Allocator, -{ - let buf_len = buf.len(); - let mut pos = reserve_and_pad(pos_mut, vec, buf_len)?; - - // Write the buf then progress the vec forward if necessary - // Safety: we have ensured that the capacity is available - // and that all bytes get written up to pos - unsafe { - pos = vec_write_unchecked(pos, vec, buf); - if pos > vec.len() { - vec.set_len(pos); - } - }; - - // Bump us forward - *pos_mut += buf_len as u64; - Ok(buf_len) -} - -/// Resizing write_vectored implementation for [`Cursor`] -/// -/// Cursor is allowed to have a pre-allocated and initialised -/// vector body, but with a position of 0. This means the [`Write`] -/// will overwrite the contents of the vec. -/// -/// This also allows for the vec body to be empty, but with a position of N. -/// This means that [`Write`] will pad the vec with 0 initially, -/// before writing anything from that point -fn vec_write_vectored( - pos_mut: &mut u64, - vec: &mut Vec, - bufs: &[IoSlice<'_>], -) -> io::Result -where - A: Allocator, -{ - // For safety reasons, we don't want this sum to overflow ever. - // If this saturates, the reserve should panic to avoid any unsound writing. - let buf_len = bufs.iter().fold(0usize, |a, b| a.saturating_add(b.len())); - let mut pos = reserve_and_pad(pos_mut, vec, buf_len)?; - - // Write the buf then progress the vec forward if necessary - // Safety: we have ensured that the capacity is available - // and that all bytes get written up to the last pos - unsafe { - for buf in bufs { - pos = vec_write_unchecked(pos, vec, buf); - } - if pos > vec.len() { - vec.set_len(pos); - } - } - - // Bump us forward - *pos_mut += buf_len as u64; - Ok(buf_len) -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Write for Cursor<&mut [u8]> { - #[inline] - fn write(&mut self, buf: &[u8]) -> io::Result { - slice_write(&mut self.pos, self.inner, buf) - } - - #[inline] - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - slice_write_vectored(&mut self.pos, self.inner, bufs) - } - - #[inline] - fn is_write_vectored(&self) -> bool { - true - } - - #[inline] - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -#[stable(feature = "cursor_mut_vec", since = "1.25.0")] -impl Write for Cursor<&mut Vec> -where - A: Allocator, -{ - fn write(&mut self, buf: &[u8]) -> io::Result { - vec_write(&mut self.pos, self.inner, buf) - } - - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - vec_write_vectored(&mut self.pos, self.inner, bufs) - } - - #[inline] - fn is_write_vectored(&self) -> bool { - true - } - - #[inline] - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Write for Cursor> -where - A: Allocator, -{ - fn write(&mut self, buf: &[u8]) -> io::Result { - vec_write(&mut self.pos, &mut self.inner, buf) - } - - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - vec_write_vectored(&mut self.pos, &mut self.inner, bufs) - } - - #[inline] - fn is_write_vectored(&self) -> bool { - true - } - - #[inline] - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -#[stable(feature = "cursor_box_slice", since = "1.5.0")] -impl Write for Cursor> -where - A: Allocator, -{ - #[inline] - fn write(&mut self, buf: &[u8]) -> io::Result { - slice_write(&mut self.pos, &mut self.inner, buf) - } - - #[inline] - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - slice_write_vectored(&mut self.pos, &mut self.inner, bufs) - } - - #[inline] - fn is_write_vectored(&self) -> bool { - true - } - - #[inline] - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -#[stable(feature = "cursor_array", since = "1.61.0")] -impl Write for Cursor<[u8; N]> { - #[inline] - fn write(&mut self, buf: &[u8]) -> io::Result { - slice_write(&mut self.pos, &mut self.inner, buf) - } - - #[inline] - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - slice_write_vectored(&mut self.pos, &mut self.inner, bufs) - } - - #[inline] - fn is_write_vectored(&self) -> bool { - true - } - - #[inline] - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} diff --git a/library/std/src/io/cursor/tests.rs b/library/std/src/io/cursor/tests.rs deleted file mode 100644 index d7c203c297fe6..0000000000000 --- a/library/std/src/io/cursor/tests.rs +++ /dev/null @@ -1,567 +0,0 @@ -use crate::io::prelude::*; -use crate::io::{Cursor, IoSlice, IoSliceMut, SeekFrom}; - -#[test] -fn test_vec_writer() { - let mut writer = Vec::new(); - assert_eq!(writer.write(&[0]).unwrap(), 1); - assert_eq!(writer.write(&[1, 2, 3]).unwrap(), 3); - assert_eq!(writer.write(&[4, 5, 6, 7]).unwrap(), 4); - assert_eq!( - writer - .write_vectored(&[IoSlice::new(&[]), IoSlice::new(&[8, 9]), IoSlice::new(&[10])],) - .unwrap(), - 3 - ); - let b: &[_] = &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; - assert_eq!(writer, b); -} - -#[test] -fn test_mem_writer() { - let mut writer = Cursor::new(Vec::new()); - writer.set_position(10); - assert_eq!(writer.write(&[0]).unwrap(), 1); - assert_eq!(writer.write(&[1, 2, 3]).unwrap(), 3); - assert_eq!(writer.write(&[4, 5, 6, 7]).unwrap(), 4); - assert_eq!( - writer - .write_vectored(&[IoSlice::new(&[]), IoSlice::new(&[8, 9]), IoSlice::new(&[10])],) - .unwrap(), - 3 - ); - let b: &[_] = &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; - assert_eq!(&writer.get_ref()[..10], &[0; 10]); - assert_eq!(&writer.get_ref()[10..], b); -} - -#[test] -fn test_mem_writer_preallocated() { - let mut writer = Cursor::new(vec![0, 0, 0, 0, 0, 0, 0, 0, 8, 9, 10]); - assert_eq!(writer.write(&[0]).unwrap(), 1); - assert_eq!(writer.write(&[1, 2, 3]).unwrap(), 3); - assert_eq!(writer.write(&[4, 5, 6, 7]).unwrap(), 4); - let b: &[_] = &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; - assert_eq!(&writer.get_ref()[..], b); -} - -#[test] -fn test_mem_mut_writer() { - let mut vec = Vec::new(); - let mut writer = Cursor::new(&mut vec); - assert_eq!(writer.write(&[0]).unwrap(), 1); - assert_eq!(writer.write(&[1, 2, 3]).unwrap(), 3); - assert_eq!(writer.write(&[4, 5, 6, 7]).unwrap(), 4); - assert_eq!( - writer - .write_vectored(&[IoSlice::new(&[]), IoSlice::new(&[8, 9]), IoSlice::new(&[10])],) - .unwrap(), - 3 - ); - let b: &[_] = &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; - assert_eq!(&writer.get_ref()[..], b); -} - -fn test_slice_writer(writer: &mut Cursor) -where - T: AsRef<[u8]>, - Cursor: Write, -{ - assert_eq!(writer.position(), 0); - assert_eq!(writer.write(&[0]).unwrap(), 1); - assert_eq!(writer.position(), 1); - assert_eq!(writer.write(&[1, 2, 3]).unwrap(), 3); - assert_eq!(writer.write(&[4, 5, 6, 7]).unwrap(), 4); - assert_eq!(writer.position(), 8); - assert_eq!(writer.write(&[]).unwrap(), 0); - assert_eq!(writer.position(), 8); - - assert_eq!(writer.write(&[8, 9]).unwrap(), 1); - assert_eq!(writer.write(&[10]).unwrap(), 0); - let b: &[_] = &[0, 1, 2, 3, 4, 5, 6, 7, 8]; - assert_eq!(writer.get_ref().as_ref(), b); -} - -fn test_slice_writer_vectored(writer: &mut Cursor) -where - T: AsRef<[u8]>, - Cursor: Write, -{ - assert_eq!(writer.position(), 0); - assert_eq!(writer.write_vectored(&[IoSlice::new(&[0])]).unwrap(), 1); - assert_eq!(writer.position(), 1); - assert_eq!( - writer.write_vectored(&[IoSlice::new(&[1, 2, 3]), IoSlice::new(&[4, 5, 6, 7]),]).unwrap(), - 7, - ); - assert_eq!(writer.position(), 8); - assert_eq!(writer.write_vectored(&[]).unwrap(), 0); - assert_eq!(writer.position(), 8); - - assert_eq!(writer.write_vectored(&[IoSlice::new(&[8, 9])]).unwrap(), 1); - assert_eq!(writer.write_vectored(&[IoSlice::new(&[10])]).unwrap(), 0); - let b: &[_] = &[0, 1, 2, 3, 4, 5, 6, 7, 8]; - assert_eq!(writer.get_ref().as_ref(), b); -} - -#[test] -fn test_box_slice_writer() { - let mut writer = Cursor::new(vec![0u8; 9].into_boxed_slice()); - test_slice_writer(&mut writer); -} - -#[test] -fn test_box_slice_writer_vectored() { - let mut writer = Cursor::new(vec![0u8; 9].into_boxed_slice()); - test_slice_writer_vectored(&mut writer); -} - -#[test] -fn test_array_writer() { - let mut writer = Cursor::new([0u8; 9]); - test_slice_writer(&mut writer); -} - -#[test] -fn test_array_writer_vectored() { - let mut writer = Cursor::new([0u8; 9]); - test_slice_writer_vectored(&mut writer); -} - -#[test] -fn test_buf_writer() { - let mut buf = [0 as u8; 9]; - let mut writer = Cursor::new(&mut buf[..]); - test_slice_writer(&mut writer); -} - -#[test] -fn test_buf_writer_vectored() { - let mut buf = [0 as u8; 9]; - let mut writer = Cursor::new(&mut buf[..]); - test_slice_writer_vectored(&mut writer); -} - -#[test] -fn test_buf_writer_seek() { - let mut buf = [0 as u8; 8]; - { - let mut writer = Cursor::new(&mut buf[..]); - assert_eq!(writer.position(), 0); - assert_eq!(writer.write(&[1]).unwrap(), 1); - assert_eq!(writer.position(), 1); - - assert_eq!(writer.seek(SeekFrom::Start(2)).unwrap(), 2); - assert_eq!(writer.position(), 2); - assert_eq!(writer.write(&[2]).unwrap(), 1); - assert_eq!(writer.position(), 3); - - assert_eq!(writer.seek(SeekFrom::Current(-2)).unwrap(), 1); - assert_eq!(writer.position(), 1); - assert_eq!(writer.write(&[3]).unwrap(), 1); - assert_eq!(writer.position(), 2); - - assert_eq!(writer.seek(SeekFrom::End(-1)).unwrap(), 7); - assert_eq!(writer.position(), 7); - assert_eq!(writer.write(&[4]).unwrap(), 1); - assert_eq!(writer.position(), 8); - } - let b: &[_] = &[1, 3, 2, 0, 0, 0, 0, 4]; - assert_eq!(buf, b); -} - -#[test] -fn test_buf_writer_error() { - let mut buf = [0 as u8; 2]; - let mut writer = Cursor::new(&mut buf[..]); - assert_eq!(writer.write(&[0]).unwrap(), 1); - assert_eq!(writer.write(&[0, 0]).unwrap(), 1); - assert_eq!(writer.write(&[0, 0]).unwrap(), 0); -} - -#[test] -fn test_mem_reader() { - let mut reader = Cursor::new(vec![0, 1, 2, 3, 4, 5, 6, 7]); - let mut buf = []; - assert_eq!(reader.read(&mut buf).unwrap(), 0); - assert_eq!(reader.position(), 0); - let mut buf = [0]; - assert_eq!(reader.read(&mut buf).unwrap(), 1); - assert_eq!(reader.position(), 1); - let b: &[_] = &[0]; - assert_eq!(buf, b); - let mut buf = [0; 4]; - assert_eq!(reader.read(&mut buf).unwrap(), 4); - assert_eq!(reader.position(), 5); - let b: &[_] = &[1, 2, 3, 4]; - assert_eq!(buf, b); - assert_eq!(reader.read(&mut buf).unwrap(), 3); - let b: &[_] = &[5, 6, 7]; - assert_eq!(&buf[..3], b); - assert_eq!(reader.read(&mut buf).unwrap(), 0); -} - -#[test] -fn test_mem_reader_vectored() { - let mut reader = Cursor::new(vec![0, 1, 2, 3, 4, 5, 6, 7]); - let mut buf = []; - assert_eq!(reader.read_vectored(&mut [IoSliceMut::new(&mut buf)]).unwrap(), 0); - assert_eq!(reader.position(), 0); - let mut buf = [0]; - assert_eq!( - reader.read_vectored(&mut [IoSliceMut::new(&mut []), IoSliceMut::new(&mut buf),]).unwrap(), - 1, - ); - assert_eq!(reader.position(), 1); - let b: &[_] = &[0]; - assert_eq!(buf, b); - let mut buf1 = [0; 4]; - let mut buf2 = [0; 4]; - assert_eq!( - reader - .read_vectored(&mut [IoSliceMut::new(&mut buf1), IoSliceMut::new(&mut buf2),]) - .unwrap(), - 7, - ); - let b1: &[_] = &[1, 2, 3, 4]; - let b2: &[_] = &[5, 6, 7]; - assert_eq!(buf1, b1); - assert_eq!(&buf2[..3], b2); - assert_eq!(reader.read(&mut buf).unwrap(), 0); -} - -#[test] -fn test_boxed_slice_reader() { - let mut reader = Cursor::new(vec![0, 1, 2, 3, 4, 5, 6, 7].into_boxed_slice()); - let mut buf = []; - assert_eq!(reader.read(&mut buf).unwrap(), 0); - assert_eq!(reader.position(), 0); - let mut buf = [0]; - assert_eq!(reader.read(&mut buf).unwrap(), 1); - assert_eq!(reader.position(), 1); - let b: &[_] = &[0]; - assert_eq!(buf, b); - let mut buf = [0; 4]; - assert_eq!(reader.read(&mut buf).unwrap(), 4); - assert_eq!(reader.position(), 5); - let b: &[_] = &[1, 2, 3, 4]; - assert_eq!(buf, b); - assert_eq!(reader.read(&mut buf).unwrap(), 3); - let b: &[_] = &[5, 6, 7]; - assert_eq!(&buf[..3], b); - assert_eq!(reader.read(&mut buf).unwrap(), 0); -} - -#[test] -fn test_boxed_slice_reader_vectored() { - let mut reader = Cursor::new(vec![0, 1, 2, 3, 4, 5, 6, 7].into_boxed_slice()); - let mut buf = []; - assert_eq!(reader.read_vectored(&mut [IoSliceMut::new(&mut buf)]).unwrap(), 0); - assert_eq!(reader.position(), 0); - let mut buf = [0]; - assert_eq!( - reader.read_vectored(&mut [IoSliceMut::new(&mut []), IoSliceMut::new(&mut buf),]).unwrap(), - 1, - ); - assert_eq!(reader.position(), 1); - let b: &[_] = &[0]; - assert_eq!(buf, b); - let mut buf1 = [0; 4]; - let mut buf2 = [0; 4]; - assert_eq!( - reader - .read_vectored(&mut [IoSliceMut::new(&mut buf1), IoSliceMut::new(&mut buf2)],) - .unwrap(), - 7, - ); - let b1: &[_] = &[1, 2, 3, 4]; - let b2: &[_] = &[5, 6, 7]; - assert_eq!(buf1, b1); - assert_eq!(&buf2[..3], b2); - assert_eq!(reader.read(&mut buf).unwrap(), 0); -} - -#[test] -fn read_to_end() { - let mut reader = Cursor::new(vec![0, 1, 2, 3, 4, 5, 6, 7]); - let mut v = Vec::new(); - reader.read_to_end(&mut v).unwrap(); - assert_eq!(v, [0, 1, 2, 3, 4, 5, 6, 7]); -} - -#[test] -fn test_slice_reader() { - let in_buf = vec![0, 1, 2, 3, 4, 5, 6, 7]; - let reader = &mut &in_buf[..]; - let mut buf = []; - assert_eq!(reader.read(&mut buf).unwrap(), 0); - let mut buf = [0]; - assert_eq!(reader.read(&mut buf).unwrap(), 1); - assert_eq!(reader.len(), 7); - let b: &[_] = &[0]; - assert_eq!(&buf[..], b); - let mut buf = [0; 4]; - assert_eq!(reader.read(&mut buf).unwrap(), 4); - assert_eq!(reader.len(), 3); - let b: &[_] = &[1, 2, 3, 4]; - assert_eq!(&buf[..], b); - assert_eq!(reader.read(&mut buf).unwrap(), 3); - let b: &[_] = &[5, 6, 7]; - assert_eq!(&buf[..3], b); - assert_eq!(reader.read(&mut buf).unwrap(), 0); -} - -#[test] -fn test_slice_reader_vectored() { - let in_buf = vec![0, 1, 2, 3, 4, 5, 6, 7]; - let reader = &mut &in_buf[..]; - let mut buf = []; - assert_eq!(reader.read_vectored(&mut [IoSliceMut::new(&mut buf)]).unwrap(), 0); - let mut buf = [0]; - assert_eq!( - reader.read_vectored(&mut [IoSliceMut::new(&mut []), IoSliceMut::new(&mut buf),]).unwrap(), - 1, - ); - assert_eq!(reader.len(), 7); - let b: &[_] = &[0]; - assert_eq!(buf, b); - let mut buf1 = [0; 4]; - let mut buf2 = [0; 4]; - assert_eq!( - reader - .read_vectored(&mut [IoSliceMut::new(&mut buf1), IoSliceMut::new(&mut buf2)],) - .unwrap(), - 7, - ); - let b1: &[_] = &[1, 2, 3, 4]; - let b2: &[_] = &[5, 6, 7]; - assert_eq!(buf1, b1); - assert_eq!(&buf2[..3], b2); - assert_eq!(reader.read(&mut buf).unwrap(), 0); -} - -#[test] -fn test_read_exact() { - let in_buf = vec![0, 1, 2, 3, 4, 5, 6, 7]; - let reader = &mut &in_buf[..]; - let mut buf = []; - assert!(reader.read_exact(&mut buf).is_ok()); - let mut buf = [8]; - assert!(reader.read_exact(&mut buf).is_ok()); - assert_eq!(buf[0], 0); - assert_eq!(reader.len(), 7); - let mut buf = [0, 0, 0, 0, 0, 0, 0]; - assert!(reader.read_exact(&mut buf).is_ok()); - assert_eq!(buf, [1, 2, 3, 4, 5, 6, 7]); - assert_eq!(reader.len(), 0); - let mut buf = [0]; - assert!(reader.read_exact(&mut buf).is_err()); -} - -#[test] -fn test_buf_reader() { - let in_buf = vec![0, 1, 2, 3, 4, 5, 6, 7]; - let mut reader = Cursor::new(&in_buf[..]); - let mut buf = []; - assert_eq!(reader.read(&mut buf).unwrap(), 0); - assert_eq!(reader.position(), 0); - let mut buf = [0]; - assert_eq!(reader.read(&mut buf).unwrap(), 1); - assert_eq!(reader.position(), 1); - let b: &[_] = &[0]; - assert_eq!(buf, b); - let mut buf = [0; 4]; - assert_eq!(reader.read(&mut buf).unwrap(), 4); - assert_eq!(reader.position(), 5); - let b: &[_] = &[1, 2, 3, 4]; - assert_eq!(buf, b); - assert_eq!(reader.read(&mut buf).unwrap(), 3); - let b: &[_] = &[5, 6, 7]; - assert_eq!(&buf[..3], b); - assert_eq!(reader.read(&mut buf).unwrap(), 0); -} - -#[test] -fn seek_past_end() { - let buf = [0xff]; - let mut r = Cursor::new(&buf[..]); - assert_eq!(r.seek(SeekFrom::Start(10)).unwrap(), 10); - assert_eq!(r.read(&mut [0]).unwrap(), 0); - - let mut r = Cursor::new(vec![10]); - assert_eq!(r.seek(SeekFrom::Start(10)).unwrap(), 10); - assert_eq!(r.read(&mut [0]).unwrap(), 0); - - let mut buf = [0]; - let mut r = Cursor::new(&mut buf[..]); - assert_eq!(r.seek(SeekFrom::Start(10)).unwrap(), 10); - assert_eq!(r.write(&[3]).unwrap(), 0); - - let mut r = Cursor::new(vec![10].into_boxed_slice()); - assert_eq!(r.seek(SeekFrom::Start(10)).unwrap(), 10); - assert_eq!(r.write(&[3]).unwrap(), 0); -} - -#[test] -fn seek_past_i64() { - let buf = [0xff]; - let mut r = Cursor::new(&buf[..]); - assert_eq!(r.seek(SeekFrom::Start(6)).unwrap(), 6); - assert_eq!(r.seek(SeekFrom::Current(0x7ffffffffffffff0)).unwrap(), 0x7ffffffffffffff6); - assert_eq!(r.seek(SeekFrom::Current(0x10)).unwrap(), 0x8000000000000006); - assert_eq!(r.seek(SeekFrom::Current(0)).unwrap(), 0x8000000000000006); - assert!(r.seek(SeekFrom::Current(0x7ffffffffffffffd)).is_err()); - assert_eq!(r.seek(SeekFrom::Current(-0x8000000000000000)).unwrap(), 6); - - let mut r = Cursor::new(vec![10]); - assert_eq!(r.seek(SeekFrom::Start(6)).unwrap(), 6); - assert_eq!(r.seek(SeekFrom::Current(0x7ffffffffffffff0)).unwrap(), 0x7ffffffffffffff6); - assert_eq!(r.seek(SeekFrom::Current(0x10)).unwrap(), 0x8000000000000006); - assert_eq!(r.seek(SeekFrom::Current(0)).unwrap(), 0x8000000000000006); - assert!(r.seek(SeekFrom::Current(0x7ffffffffffffffd)).is_err()); - assert_eq!(r.seek(SeekFrom::Current(-0x8000000000000000)).unwrap(), 6); - - let mut buf = [0]; - let mut r = Cursor::new(&mut buf[..]); - assert_eq!(r.seek(SeekFrom::Start(6)).unwrap(), 6); - assert_eq!(r.seek(SeekFrom::Current(0x7ffffffffffffff0)).unwrap(), 0x7ffffffffffffff6); - assert_eq!(r.seek(SeekFrom::Current(0x10)).unwrap(), 0x8000000000000006); - assert_eq!(r.seek(SeekFrom::Current(0)).unwrap(), 0x8000000000000006); - assert!(r.seek(SeekFrom::Current(0x7ffffffffffffffd)).is_err()); - assert_eq!(r.seek(SeekFrom::Current(-0x8000000000000000)).unwrap(), 6); - - let mut r = Cursor::new(vec![10].into_boxed_slice()); - assert_eq!(r.seek(SeekFrom::Start(6)).unwrap(), 6); - assert_eq!(r.seek(SeekFrom::Current(0x7ffffffffffffff0)).unwrap(), 0x7ffffffffffffff6); - assert_eq!(r.seek(SeekFrom::Current(0x10)).unwrap(), 0x8000000000000006); - assert_eq!(r.seek(SeekFrom::Current(0)).unwrap(), 0x8000000000000006); - assert!(r.seek(SeekFrom::Current(0x7ffffffffffffffd)).is_err()); - assert_eq!(r.seek(SeekFrom::Current(-0x8000000000000000)).unwrap(), 6); -} - -#[test] -fn seek_before_0() { - let buf = [0xff]; - let mut r = Cursor::new(&buf[..]); - assert!(r.seek(SeekFrom::End(-2)).is_err()); - - let mut r = Cursor::new(vec![10]); - assert!(r.seek(SeekFrom::End(-2)).is_err()); - - let mut buf = [0]; - let mut r = Cursor::new(&mut buf[..]); - assert!(r.seek(SeekFrom::End(-2)).is_err()); - - let mut r = Cursor::new(vec![10].into_boxed_slice()); - assert!(r.seek(SeekFrom::End(-2)).is_err()); -} - -#[test] -fn test_seekable_mem_writer() { - let mut writer = Cursor::new(Vec::::new()); - assert_eq!(writer.position(), 0); - assert_eq!(writer.write(&[0]).unwrap(), 1); - assert_eq!(writer.position(), 1); - assert_eq!(writer.write(&[1, 2, 3]).unwrap(), 3); - assert_eq!(writer.write(&[4, 5, 6, 7]).unwrap(), 4); - assert_eq!(writer.position(), 8); - let b: &[_] = &[0, 1, 2, 3, 4, 5, 6, 7]; - assert_eq!(&writer.get_ref()[..], b); - - assert_eq!(writer.seek(SeekFrom::Start(0)).unwrap(), 0); - assert_eq!(writer.position(), 0); - assert_eq!(writer.write(&[3, 4]).unwrap(), 2); - let b: &[_] = &[3, 4, 2, 3, 4, 5, 6, 7]; - assert_eq!(&writer.get_ref()[..], b); - - assert_eq!(writer.seek(SeekFrom::Current(1)).unwrap(), 3); - assert_eq!(writer.write(&[0, 1]).unwrap(), 2); - let b: &[_] = &[3, 4, 2, 0, 1, 5, 6, 7]; - assert_eq!(&writer.get_ref()[..], b); - - assert_eq!(writer.seek(SeekFrom::End(-1)).unwrap(), 7); - assert_eq!(writer.write(&[1, 2]).unwrap(), 2); - let b: &[_] = &[3, 4, 2, 0, 1, 5, 6, 1, 2]; - assert_eq!(&writer.get_ref()[..], b); - - assert_eq!(writer.seek(SeekFrom::End(1)).unwrap(), 10); - assert_eq!(writer.write(&[1]).unwrap(), 1); - let b: &[_] = &[3, 4, 2, 0, 1, 5, 6, 1, 2, 0, 1]; - assert_eq!(&writer.get_ref()[..], b); -} - -#[test] -fn vec_seek_past_end() { - let mut r = Cursor::new(Vec::new()); - assert_eq!(r.seek(SeekFrom::Start(10)).unwrap(), 10); - assert_eq!(r.write(&[3]).unwrap(), 1); -} - -#[test] -fn vec_seek_before_0() { - let mut r = Cursor::new(Vec::new()); - assert!(r.seek(SeekFrom::End(-2)).is_err()); -} - -#[test] -#[cfg(target_pointer_width = "32")] -fn vec_seek_and_write_past_usize_max() { - let mut c = Cursor::new(Vec::new()); - c.set_position(usize::MAX as u64 + 1); - assert!(c.write_all(&[1, 2, 3]).is_err()); -} - -#[test] -fn test_partial_eq() { - assert_eq!(Cursor::new(Vec::::new()), Cursor::new(Vec::::new())); -} - -#[test] -fn test_eq() { - struct AssertEq(pub T); - - let _: AssertEq>> = AssertEq(Cursor::new(Vec::new())); -} - -#[allow(dead_code)] -fn const_cursor() { - const CURSOR: Cursor<&[u8]> = Cursor::new(&[0]); - const _: &&[u8] = CURSOR.get_ref(); - const _: u64 = CURSOR.position(); -} - -#[bench] -fn bench_write_vec(b: &mut test::Bencher) { - let slice = &[1; 128]; - - b.iter(|| { - let mut buf = b"some random data to overwrite".to_vec(); - let mut cursor = Cursor::new(&mut buf); - - let _ = cursor.write_all(slice); - test::black_box(&cursor); - }) -} - -#[bench] -fn bench_write_vec_vectored(b: &mut test::Bencher) { - let slices = [ - IoSlice::new(&[1; 128]), - IoSlice::new(&[2; 256]), - IoSlice::new(&[3; 512]), - IoSlice::new(&[4; 1024]), - IoSlice::new(&[5; 2048]), - IoSlice::new(&[6; 4096]), - IoSlice::new(&[7; 8192]), - IoSlice::new(&[8; 8192 * 2]), - ]; - - b.iter(|| { - let mut buf = b"some random data to overwrite".to_vec(); - let mut cursor = Cursor::new(&mut buf); - - let mut slices = slices; - let _ = cursor.write_all_vectored(&mut slices); - test::black_box(&cursor); - }) -} diff --git a/library/std/src/io/error.rs b/library/std/src/io/error.rs deleted file mode 100644 index f366cb8f42baa..0000000000000 --- a/library/std/src/io/error.rs +++ /dev/null @@ -1,1063 +0,0 @@ -#[cfg(test)] -mod tests; - -#[cfg(all(target_pointer_width = "64", not(target_os = "uefi")))] -mod repr_bitpacked; -#[cfg(all(target_pointer_width = "64", not(target_os = "uefi")))] -use repr_bitpacked::Repr; - -#[cfg(any(not(target_pointer_width = "64"), target_os = "uefi"))] -mod repr_unpacked; -#[cfg(any(not(target_pointer_width = "64"), target_os = "uefi"))] -use repr_unpacked::Repr; - -use crate::error; -use crate::fmt; -use crate::result; -use crate::sys; - -/// A specialized [`Result`] type for I/O operations. -/// -/// This type is broadly used across [`std::io`] for any operation which may -/// produce an error. -/// -/// This typedef is generally used to avoid writing out [`io::Error`] directly and -/// is otherwise a direct mapping to [`Result`]. -/// -/// While usual Rust style is to import types directly, aliases of [`Result`] -/// often are not, to make it easier to distinguish between them. [`Result`] is -/// generally assumed to be [`std::result::Result`][`Result`], and so users of this alias -/// will generally use `io::Result` instead of shadowing the [prelude]'s import -/// of [`std::result::Result`][`Result`]. -/// -/// [`std::io`]: crate::io -/// [`io::Error`]: Error -/// [`Result`]: crate::result::Result -/// [prelude]: crate::prelude -/// -/// # Examples -/// -/// A convenience function that bubbles an `io::Result` to its caller: -/// -/// ``` -/// use std::io; -/// -/// fn get_string() -> io::Result { -/// let mut buffer = String::new(); -/// -/// io::stdin().read_line(&mut buffer)?; -/// -/// Ok(buffer) -/// } -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub type Result = result::Result; - -/// The error type for I/O operations of the [`Read`], [`Write`], [`Seek`], and -/// associated traits. -/// -/// Errors mostly originate from the underlying OS, but custom instances of -/// `Error` can be created with crafted error messages and a particular value of -/// [`ErrorKind`]. -/// -/// [`Read`]: crate::io::Read -/// [`Write`]: crate::io::Write -/// [`Seek`]: crate::io::Seek -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Error { - repr: Repr, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for Error { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&self.repr, f) - } -} - -/// Common errors constants for use in std -#[allow(dead_code)] -impl Error { - pub(crate) const INVALID_UTF8: Self = - const_io_error!(ErrorKind::InvalidData, "stream did not contain valid UTF-8"); - - pub(crate) const READ_EXACT_EOF: Self = - const_io_error!(ErrorKind::UnexpectedEof, "failed to fill whole buffer"); - - pub(crate) const UNKNOWN_THREAD_COUNT: Self = const_io_error!( - ErrorKind::NotFound, - "The number of hardware threads is not known for the target platform" - ); - - pub(crate) const UNSUPPORTED_PLATFORM: Self = - const_io_error!(ErrorKind::Unsupported, "operation not supported on this platform"); - - pub(crate) const WRITE_ALL_EOF: Self = - const_io_error!(ErrorKind::WriteZero, "failed to write whole buffer"); - - pub(crate) const ZERO_TIMEOUT: Self = - const_io_error!(ErrorKind::InvalidInput, "cannot set a 0 duration timeout"); -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl From for Error { - /// Converts a [`alloc::ffi::NulError`] into a [`Error`]. - fn from(_: alloc::ffi::NulError) -> Error { - const_io_error!(ErrorKind::InvalidInput, "data provided contains a nul byte") - } -} - -#[stable(feature = "io_error_from_try_reserve", since = "1.78.0")] -impl From for Error { - /// Converts `TryReserveError` to an error with [`ErrorKind::OutOfMemory`]. - /// - /// `TryReserveError` won't be available as the error `source()`, - /// but this may change in the future. - fn from(_: alloc::collections::TryReserveError) -> Error { - // ErrorData::Custom allocates, which isn't great for handling OOM errors. - ErrorKind::OutOfMemory.into() - } -} - -// Only derive debug in tests, to make sure it -// doesn't accidentally get printed. -#[cfg_attr(test, derive(Debug))] -enum ErrorData { - Os(RawOsError), - Simple(ErrorKind), - SimpleMessage(&'static SimpleMessage), - Custom(C), -} - -/// The type of raw OS error codes returned by [`Error::raw_os_error`]. -/// -/// This is an [`i32`] on all currently supported platforms, but platforms -/// added in the future (such as UEFI) may use a different primitive type like -/// [`usize`]. Use `as`or [`into`] conversions where applicable to ensure maximum -/// portability. -/// -/// [`into`]: Into::into -#[unstable(feature = "raw_os_error_ty", issue = "107792")] -pub type RawOsError = sys::RawOsError; - -// `#[repr(align(4))]` is probably redundant, it should have that value or -// higher already. We include it just because repr_bitpacked.rs's encoding -// requires an alignment >= 4 (note that `#[repr(align)]` will not reduce the -// alignment required by the struct, only increase it). -// -// If we add more variants to ErrorData, this can be increased to 8, but it -// should probably be behind `#[cfg_attr(target_pointer_width = "64", ...)]` or -// whatever cfg we're using to enable the `repr_bitpacked` code, since only the -// that version needs the alignment, and 8 is higher than the alignment we'll -// have on 32 bit platforms. -// -// (For the sake of being explicit: the alignment requirement here only matters -// if `error/repr_bitpacked.rs` is in use — for the unpacked repr it doesn't -// matter at all) -#[repr(align(4))] -#[derive(Debug)] -pub(crate) struct SimpleMessage { - kind: ErrorKind, - message: &'static str, -} - -impl SimpleMessage { - pub(crate) const fn new(kind: ErrorKind, message: &'static str) -> Self { - Self { kind, message } - } -} - -/// Create and return an `io::Error` for a given `ErrorKind` and constant -/// message. This doesn't allocate. -pub(crate) macro const_io_error($kind:expr, $message:expr $(,)?) { - $crate::io::error::Error::from_static_message({ - const MESSAGE_DATA: $crate::io::error::SimpleMessage = - $crate::io::error::SimpleMessage::new($kind, $message); - &MESSAGE_DATA - }) -} - -// As with `SimpleMessage`: `#[repr(align(4))]` here is just because -// repr_bitpacked's encoding requires it. In practice it almost certainly be -// already be this high or higher. -#[derive(Debug)] -#[repr(align(4))] -struct Custom { - kind: ErrorKind, - error: Box, -} - -/// A list specifying general categories of I/O error. -/// -/// This list is intended to grow over time and it is not recommended to -/// exhaustively match against it. -/// -/// It is used with the [`io::Error`] type. -/// -/// [`io::Error`]: Error -/// -/// # Handling errors and matching on `ErrorKind` -/// -/// In application code, use `match` for the `ErrorKind` values you are -/// expecting; use `_` to match "all other errors". -/// -/// In comprehensive and thorough tests that want to verify that a test doesn't -/// return any known incorrect error kind, you may want to cut-and-paste the -/// current full list of errors from here into your test code, and then match -/// `_` as the correct case. This seems counterintuitive, but it will make your -/// tests more robust. In particular, if you want to verify that your code does -/// produce an unrecognized error kind, the robust solution is to check for all -/// the recognized error kinds and fail in those cases. -#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)] -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated)] -#[non_exhaustive] -pub enum ErrorKind { - /// An entity was not found, often a file. - #[stable(feature = "rust1", since = "1.0.0")] - NotFound, - /// The operation lacked the necessary privileges to complete. - #[stable(feature = "rust1", since = "1.0.0")] - PermissionDenied, - /// The connection was refused by the remote server. - #[stable(feature = "rust1", since = "1.0.0")] - ConnectionRefused, - /// The connection was reset by the remote server. - #[stable(feature = "rust1", since = "1.0.0")] - ConnectionReset, - /// The remote host is not reachable. - #[unstable(feature = "io_error_more", issue = "86442")] - HostUnreachable, - /// The network containing the remote host is not reachable. - #[unstable(feature = "io_error_more", issue = "86442")] - NetworkUnreachable, - /// The connection was aborted (terminated) by the remote server. - #[stable(feature = "rust1", since = "1.0.0")] - ConnectionAborted, - /// The network operation failed because it was not connected yet. - #[stable(feature = "rust1", since = "1.0.0")] - NotConnected, - /// A socket address could not be bound because the address is already in - /// use elsewhere. - #[stable(feature = "rust1", since = "1.0.0")] - AddrInUse, - /// A nonexistent interface was requested or the requested address was not - /// local. - #[stable(feature = "rust1", since = "1.0.0")] - AddrNotAvailable, - /// The system's networking is down. - #[unstable(feature = "io_error_more", issue = "86442")] - NetworkDown, - /// The operation failed because a pipe was closed. - #[stable(feature = "rust1", since = "1.0.0")] - BrokenPipe, - /// An entity already exists, often a file. - #[stable(feature = "rust1", since = "1.0.0")] - AlreadyExists, - /// The operation needs to block to complete, but the blocking operation was - /// requested to not occur. - #[stable(feature = "rust1", since = "1.0.0")] - WouldBlock, - /// A filesystem object is, unexpectedly, not a directory. - /// - /// For example, a filesystem path was specified where one of the intermediate directory - /// components was, in fact, a plain file. - #[unstable(feature = "io_error_more", issue = "86442")] - NotADirectory, - /// The filesystem object is, unexpectedly, a directory. - /// - /// A directory was specified when a non-directory was expected. - #[unstable(feature = "io_error_more", issue = "86442")] - IsADirectory, - /// A non-empty directory was specified where an empty directory was expected. - #[unstable(feature = "io_error_more", issue = "86442")] - DirectoryNotEmpty, - /// The filesystem or storage medium is read-only, but a write operation was attempted. - #[unstable(feature = "io_error_more", issue = "86442")] - ReadOnlyFilesystem, - /// Loop in the filesystem or IO subsystem; often, too many levels of symbolic links. - /// - /// There was a loop (or excessively long chain) resolving a filesystem object - /// or file IO object. - /// - /// On Unix this is usually the result of a symbolic link loop; or, of exceeding the - /// system-specific limit on the depth of symlink traversal. - #[unstable(feature = "io_error_more", issue = "86442")] - FilesystemLoop, - /// Stale network file handle. - /// - /// With some network filesystems, notably NFS, an open file (or directory) can be invalidated - /// by problems with the network or server. - #[unstable(feature = "io_error_more", issue = "86442")] - StaleNetworkFileHandle, - /// A parameter was incorrect. - #[stable(feature = "rust1", since = "1.0.0")] - InvalidInput, - /// Data not valid for the operation were encountered. - /// - /// Unlike [`InvalidInput`], this typically means that the operation - /// parameters were valid, however the error was caused by malformed - /// input data. - /// - /// For example, a function that reads a file into a string will error with - /// `InvalidData` if the file's contents are not valid UTF-8. - /// - /// [`InvalidInput`]: ErrorKind::InvalidInput - #[stable(feature = "io_invalid_data", since = "1.2.0")] - InvalidData, - /// The I/O operation's timeout expired, causing it to be canceled. - #[stable(feature = "rust1", since = "1.0.0")] - TimedOut, - /// An error returned when an operation could not be completed because a - /// call to [`write`] returned [`Ok(0)`]. - /// - /// This typically means that an operation could only succeed if it wrote a - /// particular number of bytes but only a smaller number of bytes could be - /// written. - /// - /// [`write`]: crate::io::Write::write - /// [`Ok(0)`]: Ok - #[stable(feature = "rust1", since = "1.0.0")] - WriteZero, - /// The underlying storage (typically, a filesystem) is full. - /// - /// This does not include out of quota errors. - #[unstable(feature = "io_error_more", issue = "86442")] - StorageFull, - /// Seek on unseekable file. - /// - /// Seeking was attempted on an open file handle which is not suitable for seeking - for - /// example, on Unix, a named pipe opened with `File::open`. - #[unstable(feature = "io_error_more", issue = "86442")] - NotSeekable, - /// Filesystem quota was exceeded. - #[unstable(feature = "io_error_more", issue = "86442")] - FilesystemQuotaExceeded, - /// File larger than allowed or supported. - /// - /// This might arise from a hard limit of the underlying filesystem or file access API, or from - /// an administratively imposed resource limitation. Simple disk full, and out of quota, have - /// their own errors. - #[unstable(feature = "io_error_more", issue = "86442")] - FileTooLarge, - /// Resource is busy. - #[unstable(feature = "io_error_more", issue = "86442")] - ResourceBusy, - /// Executable file is busy. - /// - /// An attempt was made to write to a file which is also in use as a running program. (Not all - /// operating systems detect this situation.) - #[unstable(feature = "io_error_more", issue = "86442")] - ExecutableFileBusy, - /// Deadlock (avoided). - /// - /// A file locking operation would result in deadlock. This situation is typically detected, if - /// at all, on a best-effort basis. - #[unstable(feature = "io_error_more", issue = "86442")] - Deadlock, - /// Cross-device or cross-filesystem (hard) link or rename. - #[unstable(feature = "io_error_more", issue = "86442")] - CrossesDevices, - /// Too many (hard) links to the same filesystem object. - /// - /// The filesystem does not support making so many hardlinks to the same file. - #[unstable(feature = "io_error_more", issue = "86442")] - TooManyLinks, - /// A filename was invalid. - /// - /// This error can also cause if it exceeded the filename length limit. - #[unstable(feature = "io_error_more", issue = "86442")] - InvalidFilename, - /// Program argument list too long. - /// - /// When trying to run an external program, a system or process limit on the size of the - /// arguments would have been exceeded. - #[unstable(feature = "io_error_more", issue = "86442")] - ArgumentListTooLong, - /// This operation was interrupted. - /// - /// Interrupted operations can typically be retried. - #[stable(feature = "rust1", since = "1.0.0")] - Interrupted, - - /// This operation is unsupported on this platform. - /// - /// This means that the operation can never succeed. - #[stable(feature = "unsupported_error", since = "1.53.0")] - Unsupported, - - // ErrorKinds which are primarily categorisations for OS error - // codes should be added above. - // - /// An error returned when an operation could not be completed because an - /// "end of file" was reached prematurely. - /// - /// This typically means that an operation could only succeed if it read a - /// particular number of bytes but only a smaller number of bytes could be - /// read. - #[stable(feature = "read_exact", since = "1.6.0")] - UnexpectedEof, - - /// An operation could not be completed, because it failed - /// to allocate enough memory. - #[stable(feature = "out_of_memory_error", since = "1.54.0")] - OutOfMemory, - - // "Unusual" error kinds which do not correspond simply to (sets - // of) OS error codes, should be added just above this comment. - // `Other` and `Uncategorized` should remain at the end: - // - /// A custom error that does not fall under any other I/O error kind. - /// - /// This can be used to construct your own [`Error`]s that do not match any - /// [`ErrorKind`]. - /// - /// This [`ErrorKind`] is not used by the standard library. - /// - /// Errors from the standard library that do not fall under any of the I/O - /// error kinds cannot be `match`ed on, and will only match a wildcard (`_`) pattern. - /// New [`ErrorKind`]s might be added in the future for some of those. - #[stable(feature = "rust1", since = "1.0.0")] - Other, - - /// Any I/O error from the standard library that's not part of this list. - /// - /// Errors that are `Uncategorized` now may move to a different or a new - /// [`ErrorKind`] variant in the future. It is not recommended to match - /// an error against `Uncategorized`; use a wildcard match (`_`) instead. - #[unstable(feature = "io_error_uncategorized", issue = "none")] - #[doc(hidden)] - Uncategorized, -} - -impl ErrorKind { - pub(crate) fn as_str(&self) -> &'static str { - use ErrorKind::*; - // tidy-alphabetical-start - match *self { - AddrInUse => "address in use", - AddrNotAvailable => "address not available", - AlreadyExists => "entity already exists", - ArgumentListTooLong => "argument list too long", - BrokenPipe => "broken pipe", - ConnectionAborted => "connection aborted", - ConnectionRefused => "connection refused", - ConnectionReset => "connection reset", - CrossesDevices => "cross-device link or rename", - Deadlock => "deadlock", - DirectoryNotEmpty => "directory not empty", - ExecutableFileBusy => "executable file busy", - FileTooLarge => "file too large", - FilesystemLoop => "filesystem loop or indirection limit (e.g. symlink loop)", - FilesystemQuotaExceeded => "filesystem quota exceeded", - HostUnreachable => "host unreachable", - Interrupted => "operation interrupted", - InvalidData => "invalid data", - InvalidFilename => "invalid filename", - InvalidInput => "invalid input parameter", - IsADirectory => "is a directory", - NetworkDown => "network down", - NetworkUnreachable => "network unreachable", - NotADirectory => "not a directory", - NotConnected => "not connected", - NotFound => "entity not found", - NotSeekable => "seek on unseekable file", - Other => "other error", - OutOfMemory => "out of memory", - PermissionDenied => "permission denied", - ReadOnlyFilesystem => "read-only filesystem or storage medium", - ResourceBusy => "resource busy", - StaleNetworkFileHandle => "stale network file handle", - StorageFull => "no storage space", - TimedOut => "timed out", - TooManyLinks => "too many links", - Uncategorized => "uncategorized error", - UnexpectedEof => "unexpected end of file", - Unsupported => "unsupported", - WouldBlock => "operation would block", - WriteZero => "write zero", - } - // tidy-alphabetical-end - } -} - -#[stable(feature = "io_errorkind_display", since = "1.60.0")] -impl fmt::Display for ErrorKind { - /// Shows a human-readable description of the `ErrorKind`. - /// - /// This is similar to `impl Display for Error`, but doesn't require first converting to Error. - /// - /// # Examples - /// ``` - /// use std::io::ErrorKind; - /// assert_eq!("entity not found", ErrorKind::NotFound.to_string()); - /// ``` - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt.write_str(self.as_str()) - } -} - -/// Intended for use for errors not exposed to the user, where allocating onto -/// the heap (for normal construction via Error::new) is too costly. -#[stable(feature = "io_error_from_errorkind", since = "1.14.0")] -impl From for Error { - /// Converts an [`ErrorKind`] into an [`Error`]. - /// - /// This conversion creates a new error with a simple representation of error kind. - /// - /// # Examples - /// - /// ``` - /// use std::io::{Error, ErrorKind}; - /// - /// let not_found = ErrorKind::NotFound; - /// let error = Error::from(not_found); - /// assert_eq!("entity not found", format!("{error}")); - /// ``` - #[inline] - fn from(kind: ErrorKind) -> Error { - Error { repr: Repr::new_simple(kind) } - } -} - -impl Error { - /// Creates a new I/O error from a known kind of error as well as an - /// arbitrary error payload. - /// - /// This function is used to generically create I/O errors which do not - /// originate from the OS itself. The `error` argument is an arbitrary - /// payload which will be contained in this [`Error`]. - /// - /// Note that this function allocates memory on the heap. - /// If no extra payload is required, use the `From` conversion from - /// `ErrorKind`. - /// - /// # Examples - /// - /// ``` - /// use std::io::{Error, ErrorKind}; - /// - /// // errors can be created from strings - /// let custom_error = Error::new(ErrorKind::Other, "oh no!"); - /// - /// // errors can also be created from other errors - /// let custom_error2 = Error::new(ErrorKind::Interrupted, custom_error); - /// - /// // creating an error without payload (and without memory allocation) - /// let eof_error = Error::from(ErrorKind::UnexpectedEof); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline(never)] - pub fn new(kind: ErrorKind, error: E) -> Error - where - E: Into>, - { - Self::_new(kind, error.into()) - } - - /// Creates a new I/O error from an arbitrary error payload. - /// - /// This function is used to generically create I/O errors which do not - /// originate from the OS itself. It is a shortcut for [`Error::new`] - /// with [`ErrorKind::Other`]. - /// - /// # Examples - /// - /// ``` - /// use std::io::Error; - /// - /// // errors can be created from strings - /// let custom_error = Error::other("oh no!"); - /// - /// // errors can also be created from other errors - /// let custom_error2 = Error::other(custom_error); - /// ``` - #[stable(feature = "io_error_other", since = "1.74.0")] - pub fn other(error: E) -> Error - where - E: Into>, - { - Self::_new(ErrorKind::Other, error.into()) - } - - fn _new(kind: ErrorKind, error: Box) -> Error { - Error { repr: Repr::new_custom(Box::new(Custom { kind, error })) } - } - - /// Creates a new I/O error from a known kind of error as well as a constant - /// message. - /// - /// This function does not allocate. - /// - /// You should not use this directly, and instead use the `const_io_error!` - /// macro: `io::const_io_error!(ErrorKind::Something, "some_message")`. - /// - /// This function should maybe change to `from_static_message(kind: ErrorKind)` in the future, when const generics allow that. - #[inline] - pub(crate) const fn from_static_message(msg: &'static SimpleMessage) -> Error { - Self { repr: Repr::new_simple_message(msg) } - } - - /// Returns an error representing the last OS error which occurred. - /// - /// This function reads the value of `errno` for the target platform (e.g. - /// `GetLastError` on Windows) and will return a corresponding instance of - /// [`Error`] for the error code. - /// - /// This should be called immediately after a call to a platform function, - /// otherwise the state of the error value is indeterminate. In particular, - /// other standard library functions may call platform functions that may - /// (or may not) reset the error value even if they succeed. - /// - /// # Examples - /// - /// ``` - /// use std::io::Error; - /// - /// let os_error = Error::last_os_error(); - /// println!("last OS error: {os_error:?}"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[doc(alias = "GetLastError")] - #[doc(alias = "errno")] - #[must_use] - #[inline] - pub fn last_os_error() -> Error { - Error::from_raw_os_error(sys::os::errno()) - } - - /// Creates a new instance of an [`Error`] from a particular OS error code. - /// - /// # Examples - /// - /// On Linux: - /// - /// ``` - /// # if cfg!(target_os = "linux") { - /// use std::io; - /// - /// let error = io::Error::from_raw_os_error(22); - /// assert_eq!(error.kind(), io::ErrorKind::InvalidInput); - /// # } - /// ``` - /// - /// On Windows: - /// - /// ``` - /// # if cfg!(windows) { - /// use std::io; - /// - /// let error = io::Error::from_raw_os_error(10022); - /// assert_eq!(error.kind(), io::ErrorKind::InvalidInput); - /// # } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - #[inline] - pub fn from_raw_os_error(code: RawOsError) -> Error { - Error { repr: Repr::new_os(code) } - } - - /// Returns the OS error that this error represents (if any). - /// - /// If this [`Error`] was constructed via [`last_os_error`] or - /// [`from_raw_os_error`], then this function will return [`Some`], otherwise - /// it will return [`None`]. - /// - /// [`last_os_error`]: Error::last_os_error - /// [`from_raw_os_error`]: Error::from_raw_os_error - /// - /// # Examples - /// - /// ``` - /// use std::io::{Error, ErrorKind}; - /// - /// fn print_os_error(err: &Error) { - /// if let Some(raw_os_err) = err.raw_os_error() { - /// println!("raw OS error: {raw_os_err:?}"); - /// } else { - /// println!("Not an OS error"); - /// } - /// } - /// - /// fn main() { - /// // Will print "raw OS error: ...". - /// print_os_error(&Error::last_os_error()); - /// // Will print "Not an OS error". - /// print_os_error(&Error::new(ErrorKind::Other, "oh no!")); - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - #[inline] - pub fn raw_os_error(&self) -> Option { - match self.repr.data() { - ErrorData::Os(i) => Some(i), - ErrorData::Custom(..) => None, - ErrorData::Simple(..) => None, - ErrorData::SimpleMessage(..) => None, - } - } - - /// Returns a reference to the inner error wrapped by this error (if any). - /// - /// If this [`Error`] was constructed via [`new`] then this function will - /// return [`Some`], otherwise it will return [`None`]. - /// - /// [`new`]: Error::new - /// - /// # Examples - /// - /// ``` - /// use std::io::{Error, ErrorKind}; - /// - /// fn print_error(err: &Error) { - /// if let Some(inner_err) = err.get_ref() { - /// println!("Inner error: {inner_err:?}"); - /// } else { - /// println!("No inner error"); - /// } - /// } - /// - /// fn main() { - /// // Will print "No inner error". - /// print_error(&Error::last_os_error()); - /// // Will print "Inner error: ...". - /// print_error(&Error::new(ErrorKind::Other, "oh no!")); - /// } - /// ``` - #[stable(feature = "io_error_inner", since = "1.3.0")] - #[must_use] - #[inline] - pub fn get_ref(&self) -> Option<&(dyn error::Error + Send + Sync + 'static)> { - match self.repr.data() { - ErrorData::Os(..) => None, - ErrorData::Simple(..) => None, - ErrorData::SimpleMessage(..) => None, - ErrorData::Custom(c) => Some(&*c.error), - } - } - - /// Returns a mutable reference to the inner error wrapped by this error - /// (if any). - /// - /// If this [`Error`] was constructed via [`new`] then this function will - /// return [`Some`], otherwise it will return [`None`]. - /// - /// [`new`]: Error::new - /// - /// # Examples - /// - /// ``` - /// use std::io::{Error, ErrorKind}; - /// use std::{error, fmt}; - /// use std::fmt::Display; - /// - /// #[derive(Debug)] - /// struct MyError { - /// v: String, - /// } - /// - /// impl MyError { - /// fn new() -> MyError { - /// MyError { - /// v: "oh no!".to_string() - /// } - /// } - /// - /// fn change_message(&mut self, new_message: &str) { - /// self.v = new_message.to_string(); - /// } - /// } - /// - /// impl error::Error for MyError {} - /// - /// impl Display for MyError { - /// fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - /// write!(f, "MyError: {}", &self.v) - /// } - /// } - /// - /// fn change_error(mut err: Error) -> Error { - /// if let Some(inner_err) = err.get_mut() { - /// inner_err.downcast_mut::().unwrap().change_message("I've been changed!"); - /// } - /// err - /// } - /// - /// fn print_error(err: &Error) { - /// if let Some(inner_err) = err.get_ref() { - /// println!("Inner error: {inner_err}"); - /// } else { - /// println!("No inner error"); - /// } - /// } - /// - /// fn main() { - /// // Will print "No inner error". - /// print_error(&change_error(Error::last_os_error())); - /// // Will print "Inner error: ...". - /// print_error(&change_error(Error::new(ErrorKind::Other, MyError::new()))); - /// } - /// ``` - #[stable(feature = "io_error_inner", since = "1.3.0")] - #[must_use] - #[inline] - pub fn get_mut(&mut self) -> Option<&mut (dyn error::Error + Send + Sync + 'static)> { - match self.repr.data_mut() { - ErrorData::Os(..) => None, - ErrorData::Simple(..) => None, - ErrorData::SimpleMessage(..) => None, - ErrorData::Custom(c) => Some(&mut *c.error), - } - } - - /// Consumes the `Error`, returning its inner error (if any). - /// - /// If this [`Error`] was constructed via [`new`] then this function will - /// return [`Some`], otherwise it will return [`None`]. - /// - /// [`new`]: Error::new - /// - /// # Examples - /// - /// ``` - /// use std::io::{Error, ErrorKind}; - /// - /// fn print_error(err: Error) { - /// if let Some(inner_err) = err.into_inner() { - /// println!("Inner error: {inner_err}"); - /// } else { - /// println!("No inner error"); - /// } - /// } - /// - /// fn main() { - /// // Will print "No inner error". - /// print_error(Error::last_os_error()); - /// // Will print "Inner error: ...". - /// print_error(Error::new(ErrorKind::Other, "oh no!")); - /// } - /// ``` - #[stable(feature = "io_error_inner", since = "1.3.0")] - #[must_use = "`self` will be dropped if the result is not used"] - #[inline] - pub fn into_inner(self) -> Option> { - match self.repr.into_data() { - ErrorData::Os(..) => None, - ErrorData::Simple(..) => None, - ErrorData::SimpleMessage(..) => None, - ErrorData::Custom(c) => Some(c.error), - } - } - - /// Attempt to downcast the custom boxed error to `E`. - /// - /// If this [`Error`] contains a custom boxed error, - /// then it would attempt downcasting on the boxed error, - /// otherwise it will return [`Err`]. - /// - /// If the custom boxed error has the same type as `E`, it will return [`Ok`], - /// otherwise it will also return [`Err`]. - /// - /// This method is meant to be a convenience routine for calling - /// `Box::downcast` on the custom boxed error, returned by - /// [`Error::into_inner`]. - /// - /// - /// # Examples - /// - /// ``` - /// use std::fmt; - /// use std::io; - /// use std::error::Error; - /// - /// #[derive(Debug)] - /// enum E { - /// Io(io::Error), - /// SomeOtherVariant, - /// } - /// - /// impl fmt::Display for E { - /// // ... - /// # fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - /// # todo!() - /// # } - /// } - /// impl Error for E {} - /// - /// impl From for E { - /// fn from(err: io::Error) -> E { - /// err.downcast::() - /// .unwrap_or_else(E::Io) - /// } - /// } - /// - /// impl From for io::Error { - /// fn from(err: E) -> io::Error { - /// match err { - /// E::Io(io_error) => io_error, - /// e => io::Error::new(io::ErrorKind::Other, e), - /// } - /// } - /// } - /// - /// # fn main() { - /// let e = E::SomeOtherVariant; - /// // Convert it to an io::Error - /// let io_error = io::Error::from(e); - /// // Cast it back to the original variant - /// let e = E::from(io_error); - /// assert!(matches!(e, E::SomeOtherVariant)); - /// - /// let io_error = io::Error::from(io::ErrorKind::AlreadyExists); - /// // Convert it to E - /// let e = E::from(io_error); - /// // Cast it back to the original variant - /// let io_error = io::Error::from(e); - /// assert_eq!(io_error.kind(), io::ErrorKind::AlreadyExists); - /// assert!(io_error.get_ref().is_none()); - /// assert!(io_error.raw_os_error().is_none()); - /// # } - /// ``` - #[stable(feature = "io_error_downcast", since = "1.79.0")] - pub fn downcast(self) -> result::Result - where - E: error::Error + Send + Sync + 'static, - { - match self.repr.into_data() { - ErrorData::Custom(b) if b.error.is::() => { - let res = (*b).error.downcast::(); - - // downcast is a really trivial and is marked as inline, so - // it's likely be inlined here. - // - // And the compiler should be able to eliminate the branch - // that produces `Err` here since b.error.is::() - // returns true. - Ok(*res.unwrap()) - } - repr_data => Err(Self { repr: Repr::new(repr_data) }), - } - } - - /// Returns the corresponding [`ErrorKind`] for this error. - /// - /// This may be a value set by Rust code constructing custom `io::Error`s, - /// or if this `io::Error` was sourced from the operating system, - /// it will be a value inferred from the system's error encoding. - /// See [`last_os_error`] for more details. - /// - /// [`last_os_error`]: Error::last_os_error - /// - /// # Examples - /// - /// ``` - /// use std::io::{Error, ErrorKind}; - /// - /// fn print_error(err: Error) { - /// println!("{:?}", err.kind()); - /// } - /// - /// fn main() { - /// // As no error has (visibly) occurred, this may print anything! - /// // It likely prints a placeholder for unidentified (non-)errors. - /// print_error(Error::last_os_error()); - /// // Will print "AddrInUse". - /// print_error(Error::new(ErrorKind::AddrInUse, "oh no!")); - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - #[inline] - pub fn kind(&self) -> ErrorKind { - match self.repr.data() { - ErrorData::Os(code) => sys::decode_error_kind(code), - ErrorData::Custom(c) => c.kind, - ErrorData::Simple(kind) => kind, - ErrorData::SimpleMessage(m) => m.kind, - } - } - - #[inline] - pub(crate) fn is_interrupted(&self) -> bool { - match self.repr.data() { - ErrorData::Os(code) => sys::is_interrupted(code), - ErrorData::Custom(c) => c.kind == ErrorKind::Interrupted, - ErrorData::Simple(kind) => kind == ErrorKind::Interrupted, - ErrorData::SimpleMessage(m) => m.kind == ErrorKind::Interrupted, - } - } -} - -impl fmt::Debug for Repr { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - match self.data() { - ErrorData::Os(code) => fmt - .debug_struct("Os") - .field("code", &code) - .field("kind", &sys::decode_error_kind(code)) - .field("message", &sys::os::error_string(code)) - .finish(), - ErrorData::Custom(c) => fmt::Debug::fmt(&c, fmt), - ErrorData::Simple(kind) => fmt.debug_tuple("Kind").field(&kind).finish(), - ErrorData::SimpleMessage(msg) => fmt - .debug_struct("Error") - .field("kind", &msg.kind) - .field("message", &msg.message) - .finish(), - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for Error { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - match self.repr.data() { - ErrorData::Os(code) => { - let detail = sys::os::error_string(code); - write!(fmt, "{detail} (os error {code})") - } - ErrorData::Custom(ref c) => c.error.fmt(fmt), - ErrorData::Simple(kind) => write!(fmt, "{}", kind.as_str()), - ErrorData::SimpleMessage(msg) => msg.message.fmt(fmt), - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl error::Error for Error { - #[allow(deprecated, deprecated_in_future)] - fn description(&self) -> &str { - match self.repr.data() { - ErrorData::Os(..) | ErrorData::Simple(..) => self.kind().as_str(), - ErrorData::SimpleMessage(msg) => msg.message, - ErrorData::Custom(c) => c.error.description(), - } - } - - #[allow(deprecated)] - fn cause(&self) -> Option<&dyn error::Error> { - match self.repr.data() { - ErrorData::Os(..) => None, - ErrorData::Simple(..) => None, - ErrorData::SimpleMessage(..) => None, - ErrorData::Custom(c) => c.error.cause(), - } - } - - fn source(&self) -> Option<&(dyn error::Error + 'static)> { - match self.repr.data() { - ErrorData::Os(..) => None, - ErrorData::Simple(..) => None, - ErrorData::SimpleMessage(..) => None, - ErrorData::Custom(c) => c.error.source(), - } - } -} - -fn _assert_error_is_sync_send() { - fn _is_sync_send() {} - _is_sync_send::(); -} diff --git a/library/std/src/io/error/repr_bitpacked.rs b/library/std/src/io/error/repr_bitpacked.rs deleted file mode 100644 index 6f8d5e3777568..0000000000000 --- a/library/std/src/io/error/repr_bitpacked.rs +++ /dev/null @@ -1,414 +0,0 @@ -//! This is a densely packed error representation which is used on targets with -//! 64-bit pointers. -//! -//! (Note that `bitpacked` vs `unpacked` here has no relationship to -//! `#[repr(packed)]`, it just refers to attempting to use any available bits in -//! a more clever manner than `rustc`'s default layout algorithm would). -//! -//! Conceptually, it stores the same data as the "unpacked" equivalent we use on -//! other targets. Specifically, you can imagine it as an optimized version of -//! the following enum (which is roughly equivalent to what's stored by -//! `repr_unpacked::Repr`, e.g. `super::ErrorData>`): -//! -//! ```ignore (exposition-only) -//! enum ErrorData { -//! Os(i32), -//! Simple(ErrorKind), -//! SimpleMessage(&'static SimpleMessage), -//! Custom(Box), -//! } -//! ``` -//! -//! However, it packs this data into a 64bit non-zero value. -//! -//! This optimization not only allows `io::Error` to occupy a single pointer, -//! but improves `io::Result` as well, especially for situations like -//! `io::Result<()>` (which is now 64 bits) or `io::Result` (which is now -//! 128 bits), which are quite common. -//! -//! # Layout -//! Tagged values are 64 bits, with the 2 least significant bits used for the -//! tag. This means there are there are 4 "variants": -//! -//! - **Tag 0b00**: The first variant is equivalent to -//! `ErrorData::SimpleMessage`, and holds a `&'static SimpleMessage` directly. -//! -//! `SimpleMessage` has an alignment >= 4 (which is requested with -//! `#[repr(align)]` and checked statically at the bottom of this file), which -//! means every `&'static SimpleMessage` should have the both tag bits as 0, -//! meaning its tagged and untagged representation are equivalent. -//! -//! This means we can skip tagging it, which is necessary as this variant can -//! be constructed from a `const fn`, which probably cannot tag pointers (or -//! at least it would be difficult). -//! -//! - **Tag 0b01**: The other pointer variant holds the data for -//! `ErrorData::Custom` and the remaining 62 bits are used to store a -//! `Box`. `Custom` also has alignment >= 4, so the bottom two bits -//! are free to use for the tag. -//! -//! The only important thing to note is that `ptr::wrapping_add` and -//! `ptr::wrapping_sub` are used to tag the pointer, rather than bitwise -//! operations. This should preserve the pointer's provenance, which would -//! otherwise be lost. -//! -//! - **Tag 0b10**: Holds the data for `ErrorData::Os(i32)`. We store the `i32` -//! in the pointer's most significant 32 bits, and don't use the bits `2..32` -//! for anything. Using the top 32 bits is just to let us easily recover the -//! `i32` code with the correct sign. -//! -//! - **Tag 0b11**: Holds the data for `ErrorData::Simple(ErrorKind)`. This -//! stores the `ErrorKind` in the top 32 bits as well, although it doesn't -//! occupy nearly that many. Most of the bits are unused here, but it's not -//! like we need them for anything else yet. -//! -//! # Use of `NonNull<()>` -//! -//! Everything is stored in a `NonNull<()>`, which is odd, but actually serves a -//! purpose. -//! -//! Conceptually you might think of this more like: -//! -//! ```ignore (exposition-only) -//! union Repr { -//! // holds integer (Simple/Os) variants, and -//! // provides access to the tag bits. -//! bits: NonZero, -//! // Tag is 0, so this is stored untagged. -//! msg: &'static SimpleMessage, -//! // Tagged (offset) `Box` pointer. -//! tagged_custom: NonNull<()>, -//! } -//! ``` -//! -//! But there are a few problems with this: -//! -//! 1. Union access is equivalent to a transmute, so this representation would -//! require we transmute between integers and pointers in at least one -//! direction, which may be UB (and even if not, it is likely harder for a -//! compiler to reason about than explicit ptr->int operations). -//! -//! 2. Even if all fields of a union have a niche, the union itself doesn't, -//! although this may change in the future. This would make things like -//! `io::Result<()>` and `io::Result` larger, which defeats part of -//! the motivation of this bitpacking. -//! -//! Storing everything in a `NonZero` (or some other integer) would be a -//! bit more traditional for pointer tagging, but it would lose provenance -//! information, couldn't be constructed from a `const fn`, and would probably -//! run into other issues as well. -//! -//! The `NonNull<()>` seems like the only alternative, even if it's fairly odd -//! to use a pointer type to store something that may hold an integer, some of -//! the time. - -use super::{Custom, ErrorData, ErrorKind, RawOsError, SimpleMessage}; -use core::marker::PhantomData; -use core::mem::{align_of, size_of}; -use core::ptr::{self, NonNull}; - -// The 2 least-significant bits are used as tag. -const TAG_MASK: usize = 0b11; -const TAG_SIMPLE_MESSAGE: usize = 0b00; -const TAG_CUSTOM: usize = 0b01; -const TAG_OS: usize = 0b10; -const TAG_SIMPLE: usize = 0b11; - -/// The internal representation. -/// -/// See the module docs for more, this is just a way to hack in a check that we -/// indeed are not unwind-safe. -/// -/// ```compile_fail,E0277 -/// fn is_unwind_safe() {} -/// is_unwind_safe::(); -/// ``` -#[repr(transparent)] -pub(super) struct Repr(NonNull<()>, PhantomData>>); - -// All the types `Repr` stores internally are Send + Sync, and so is it. -unsafe impl Send for Repr {} -unsafe impl Sync for Repr {} - -impl Repr { - pub(super) fn new(dat: ErrorData>) -> Self { - match dat { - ErrorData::Os(code) => Self::new_os(code), - ErrorData::Simple(kind) => Self::new_simple(kind), - ErrorData::SimpleMessage(simple_message) => Self::new_simple_message(simple_message), - ErrorData::Custom(b) => Self::new_custom(b), - } - } - - pub(super) fn new_custom(b: Box) -> Self { - let p = Box::into_raw(b).cast::(); - // Should only be possible if an allocator handed out a pointer with - // wrong alignment. - debug_assert_eq!(p.addr() & TAG_MASK, 0); - // Note: We know `TAG_CUSTOM <= size_of::()` (static_assert at - // end of file), and both the start and end of the expression must be - // valid without address space wraparound due to `Box`'s semantics. - // - // This means it would be correct to implement this using `ptr::add` - // (rather than `ptr::wrapping_add`), but it's unclear this would give - // any benefit, so we just use `wrapping_add` instead. - let tagged = p.wrapping_add(TAG_CUSTOM).cast::<()>(); - // Safety: `TAG_CUSTOM + p` is the same as `TAG_CUSTOM | p`, - // because `p`'s alignment means it isn't allowed to have any of the - // `TAG_BITS` set (you can verify that addition and bitwise-or are the - // same when the operands have no bits in common using a truth table). - // - // Then, `TAG_CUSTOM | p` is not zero, as that would require - // `TAG_CUSTOM` and `p` both be zero, and neither is (as `p` came from a - // box, and `TAG_CUSTOM` just... isn't zero -- it's `0b01`). Therefore, - // `TAG_CUSTOM + p` isn't zero and so `tagged` can't be, and the - // `new_unchecked` is safe. - let res = Self(unsafe { NonNull::new_unchecked(tagged) }, PhantomData); - // quickly smoke-check we encoded the right thing (This generally will - // only run in std's tests, unless the user uses -Zbuild-std) - debug_assert!(matches!(res.data(), ErrorData::Custom(_)), "repr(custom) encoding failed"); - res - } - - #[inline] - pub(super) fn new_os(code: RawOsError) -> Self { - let utagged = ((code as usize) << 32) | TAG_OS; - // Safety: `TAG_OS` is not zero, so the result of the `|` is not 0. - let res = Self( - unsafe { NonNull::new_unchecked(ptr::without_provenance_mut(utagged)) }, - PhantomData, - ); - // quickly smoke-check we encoded the right thing (This generally will - // only run in std's tests, unless the user uses -Zbuild-std) - debug_assert!( - matches!(res.data(), ErrorData::Os(c) if c == code), - "repr(os) encoding failed for {code}" - ); - res - } - - #[inline] - pub(super) fn new_simple(kind: ErrorKind) -> Self { - let utagged = ((kind as usize) << 32) | TAG_SIMPLE; - // Safety: `TAG_SIMPLE` is not zero, so the result of the `|` is not 0. - let res = Self( - unsafe { NonNull::new_unchecked(ptr::without_provenance_mut(utagged)) }, - PhantomData, - ); - // quickly smoke-check we encoded the right thing (This generally will - // only run in std's tests, unless the user uses -Zbuild-std) - debug_assert!( - matches!(res.data(), ErrorData::Simple(k) if k == kind), - "repr(simple) encoding failed {:?}", - kind, - ); - res - } - - #[inline] - pub(super) const fn new_simple_message(m: &'static SimpleMessage) -> Self { - // Safety: References are never null. - Self(unsafe { NonNull::new_unchecked(m as *const _ as *mut ()) }, PhantomData) - } - - #[inline] - pub(super) fn data(&self) -> ErrorData<&Custom> { - // Safety: We're a Repr, decode_repr is fine. - unsafe { decode_repr(self.0, |c| &*c) } - } - - #[inline] - pub(super) fn data_mut(&mut self) -> ErrorData<&mut Custom> { - // Safety: We're a Repr, decode_repr is fine. - unsafe { decode_repr(self.0, |c| &mut *c) } - } - - #[inline] - pub(super) fn into_data(self) -> ErrorData> { - let this = core::mem::ManuallyDrop::new(self); - // Safety: We're a Repr, decode_repr is fine. The `Box::from_raw` is - // safe because we prevent double-drop using `ManuallyDrop`. - unsafe { decode_repr(this.0, |p| Box::from_raw(p)) } - } -} - -impl Drop for Repr { - #[inline] - fn drop(&mut self) { - // Safety: We're a Repr, decode_repr is fine. The `Box::from_raw` is - // safe because we're being dropped. - unsafe { - let _ = decode_repr(self.0, |p| Box::::from_raw(p)); - } - } -} - -// Shared helper to decode a `Repr`'s internal pointer into an ErrorData. -// -// Safety: `ptr`'s bits should be encoded as described in the document at the -// top (it should `some_repr.0`) -#[inline] -unsafe fn decode_repr(ptr: NonNull<()>, make_custom: F) -> ErrorData -where - F: FnOnce(*mut Custom) -> C, -{ - let bits = ptr.as_ptr().addr(); - match bits & TAG_MASK { - TAG_OS => { - let code = ((bits as i64) >> 32) as RawOsError; - ErrorData::Os(code) - } - TAG_SIMPLE => { - let kind_bits = (bits >> 32) as u32; - let kind = kind_from_prim(kind_bits).unwrap_or_else(|| { - debug_assert!(false, "Invalid io::error::Repr bits: `Repr({:#018x})`", bits); - // This means the `ptr` passed in was not valid, which violates - // the unsafe contract of `decode_repr`. - // - // Using this rather than unwrap meaningfully improves the code - // for callers which only care about one variant (usually - // `Custom`) - core::hint::unreachable_unchecked(); - }); - ErrorData::Simple(kind) - } - TAG_SIMPLE_MESSAGE => ErrorData::SimpleMessage(&*ptr.cast::().as_ptr()), - TAG_CUSTOM => { - // It would be correct for us to use `ptr::byte_sub` here (see the - // comment above the `wrapping_add` call in `new_custom` for why), - // but it isn't clear that it makes a difference, so we don't. - let custom = ptr.as_ptr().wrapping_byte_sub(TAG_CUSTOM).cast::(); - ErrorData::Custom(make_custom(custom)) - } - _ => { - // Can't happen, and compiler can tell - unreachable!(); - } - } -} - -// This compiles to the same code as the check+transmute, but doesn't require -// unsafe, or to hard-code max ErrorKind or its size in a way the compiler -// couldn't verify. -#[inline] -fn kind_from_prim(ek: u32) -> Option { - macro_rules! from_prim { - ($prim:expr => $Enum:ident { $($Variant:ident),* $(,)? }) => {{ - // Force a compile error if the list gets out of date. - const _: fn(e: $Enum) = |e: $Enum| match e { - $($Enum::$Variant => ()),* - }; - match $prim { - $(v if v == ($Enum::$Variant as _) => Some($Enum::$Variant),)* - _ => None, - } - }} - } - from_prim!(ek => ErrorKind { - NotFound, - PermissionDenied, - ConnectionRefused, - ConnectionReset, - HostUnreachable, - NetworkUnreachable, - ConnectionAborted, - NotConnected, - AddrInUse, - AddrNotAvailable, - NetworkDown, - BrokenPipe, - AlreadyExists, - WouldBlock, - NotADirectory, - IsADirectory, - DirectoryNotEmpty, - ReadOnlyFilesystem, - FilesystemLoop, - StaleNetworkFileHandle, - InvalidInput, - InvalidData, - TimedOut, - WriteZero, - StorageFull, - NotSeekable, - FilesystemQuotaExceeded, - FileTooLarge, - ResourceBusy, - ExecutableFileBusy, - Deadlock, - CrossesDevices, - TooManyLinks, - InvalidFilename, - ArgumentListTooLong, - Interrupted, - Other, - UnexpectedEof, - Unsupported, - OutOfMemory, - Uncategorized, - }) -} - -// Some static checking to alert us if a change breaks any of the assumptions -// that our encoding relies on for correctness and soundness. (Some of these are -// a bit overly thorough/cautious, admittedly) -// -// If any of these are hit on a platform that std supports, we should likely -// just use `repr_unpacked.rs` there instead (unless the fix is easy). -macro_rules! static_assert { - ($condition:expr) => { - const _: () = assert!($condition); - }; - (@usize_eq: $lhs:expr, $rhs:expr) => { - const _: [(); $lhs] = [(); $rhs]; - }; -} - -// The bitpacking we use requires pointers be exactly 64 bits. -static_assert!(@usize_eq: size_of::>(), 8); - -// We also require pointers and usize be the same size. -static_assert!(@usize_eq: size_of::>(), size_of::()); - -// `Custom` and `SimpleMessage` need to be thin pointers. -static_assert!(@usize_eq: size_of::<&'static SimpleMessage>(), 8); -static_assert!(@usize_eq: size_of::>(), 8); - -static_assert!((TAG_MASK + 1).is_power_of_two()); -// And they must have sufficient alignment. -static_assert!(align_of::() >= TAG_MASK + 1); -static_assert!(align_of::() >= TAG_MASK + 1); - -static_assert!(@usize_eq: TAG_MASK & TAG_SIMPLE_MESSAGE, TAG_SIMPLE_MESSAGE); -static_assert!(@usize_eq: TAG_MASK & TAG_CUSTOM, TAG_CUSTOM); -static_assert!(@usize_eq: TAG_MASK & TAG_OS, TAG_OS); -static_assert!(@usize_eq: TAG_MASK & TAG_SIMPLE, TAG_SIMPLE); - -// This is obviously true (`TAG_CUSTOM` is `0b01`), but in `Repr::new_custom` we -// offset a pointer by this value, and expect it to both be within the same -// object, and to not wrap around the address space. See the comment in that -// function for further details. -// -// Actually, at the moment we use `ptr::wrapping_add`, not `ptr::add`, so this -// check isn't needed for that one, although the assertion that we don't -// actually wrap around in that wrapping_add does simplify the safety reasoning -// elsewhere considerably. -static_assert!(size_of::() >= TAG_CUSTOM); - -// These two store a payload which is allowed to be zero, so they must be -// non-zero to preserve the `NonNull`'s range invariant. -static_assert!(TAG_OS != 0); -static_assert!(TAG_SIMPLE != 0); -// We can't tag `SimpleMessage`s, the tag must be 0. -static_assert!(@usize_eq: TAG_SIMPLE_MESSAGE, 0); - -// Check that the point of all of this still holds. -// -// We'd check against `io::Error`, but *technically* it's allowed to vary, -// as it's not `#[repr(transparent)]`/`#[repr(C)]`. We could add that, but -// the `#[repr()]` would show up in rustdoc, which might be seen as a stable -// commitment. -static_assert!(@usize_eq: size_of::(), 8); -static_assert!(@usize_eq: size_of::>(), 8); -static_assert!(@usize_eq: size_of::>(), 8); -static_assert!(@usize_eq: size_of::>(), 16); diff --git a/library/std/src/io/error/repr_unpacked.rs b/library/std/src/io/error/repr_unpacked.rs deleted file mode 100644 index dc8a95577c959..0000000000000 --- a/library/std/src/io/error/repr_unpacked.rs +++ /dev/null @@ -1,53 +0,0 @@ -//! This is a fairly simple unpacked error representation that's used on -//! non-64bit targets, where the packed 64 bit representation wouldn't work, and -//! would have no benefit. - -use super::{Custom, ErrorData, ErrorKind, RawOsError, SimpleMessage}; - -type Inner = ErrorData>; - -pub(super) struct Repr(Inner); - -impl Repr { - #[inline] - pub(super) fn new(dat: ErrorData>) -> Self { - Self(dat) - } - pub(super) fn new_custom(b: Box) -> Self { - Self(Inner::Custom(b)) - } - #[inline] - pub(super) fn new_os(code: RawOsError) -> Self { - Self(Inner::Os(code)) - } - #[inline] - pub(super) fn new_simple(kind: ErrorKind) -> Self { - Self(Inner::Simple(kind)) - } - #[inline] - pub(super) const fn new_simple_message(m: &'static SimpleMessage) -> Self { - Self(Inner::SimpleMessage(m)) - } - #[inline] - pub(super) fn into_data(self) -> ErrorData> { - self.0 - } - #[inline] - pub(super) fn data(&self) -> ErrorData<&Custom> { - match &self.0 { - Inner::Os(c) => ErrorData::Os(*c), - Inner::Simple(k) => ErrorData::Simple(*k), - Inner::SimpleMessage(m) => ErrorData::SimpleMessage(*m), - Inner::Custom(m) => ErrorData::Custom(&*m), - } - } - #[inline] - pub(super) fn data_mut(&mut self) -> ErrorData<&mut Custom> { - match &mut self.0 { - Inner::Os(c) => ErrorData::Os(*c), - Inner::Simple(k) => ErrorData::Simple(*k), - Inner::SimpleMessage(m) => ErrorData::SimpleMessage(*m), - Inner::Custom(m) => ErrorData::Custom(&mut *m), - } - } -} diff --git a/library/std/src/io/error/tests.rs b/library/std/src/io/error/tests.rs deleted file mode 100644 index fc6db2825e811..0000000000000 --- a/library/std/src/io/error/tests.rs +++ /dev/null @@ -1,194 +0,0 @@ -use super::{const_io_error, Custom, Error, ErrorData, ErrorKind, Repr, SimpleMessage}; -use crate::assert_matches::assert_matches; -use crate::error; -use crate::fmt; -use crate::mem::size_of; -use crate::sys::decode_error_kind; -use crate::sys::os::error_string; - -#[test] -fn test_size() { - assert!(size_of::() <= size_of::<[usize; 2]>()); -} - -#[test] -fn test_debug_error() { - let code = 6; - let msg = error_string(code); - let kind = decode_error_kind(code); - let err = Error { - repr: Repr::new_custom(Box::new(Custom { - kind: ErrorKind::InvalidInput, - error: Box::new(Error { repr: super::Repr::new_os(code) }), - })), - }; - let expected = format!( - "Custom {{ \ - kind: InvalidInput, \ - error: Os {{ \ - code: {:?}, \ - kind: {:?}, \ - message: {:?} \ - }} \ - }}", - code, kind, msg - ); - assert_eq!(format!("{err:?}"), expected); -} - -#[test] -fn test_downcasting() { - #[derive(Debug)] - struct TestError; - - impl fmt::Display for TestError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str("asdf") - } - } - - impl error::Error for TestError {} - - // we have to call all of these UFCS style right now since method - // resolution won't implicitly drop the Send+Sync bounds - let mut err = Error::new(ErrorKind::Other, TestError); - assert!(err.get_ref().unwrap().is::()); - assert_eq!("asdf", err.get_ref().unwrap().to_string()); - assert!(err.get_mut().unwrap().is::()); - let extracted = err.into_inner().unwrap(); - extracted.downcast::().unwrap(); -} - -#[test] -fn test_const() { - const E: Error = const_io_error!(ErrorKind::NotFound, "hello"); - - assert_eq!(E.kind(), ErrorKind::NotFound); - assert_eq!(E.to_string(), "hello"); - assert!(format!("{E:?}").contains("\"hello\"")); - assert!(format!("{E:?}").contains("NotFound")); -} - -#[test] -fn test_os_packing() { - for code in -20..20 { - let e = Error::from_raw_os_error(code); - assert_eq!(e.raw_os_error(), Some(code)); - assert_matches!( - e.repr.data(), - ErrorData::Os(c) if c == code, - ); - } -} - -#[test] -fn test_errorkind_packing() { - assert_eq!(Error::from(ErrorKind::NotFound).kind(), ErrorKind::NotFound); - assert_eq!(Error::from(ErrorKind::PermissionDenied).kind(), ErrorKind::PermissionDenied); - assert_eq!(Error::from(ErrorKind::Uncategorized).kind(), ErrorKind::Uncategorized); - // Check that the innards look like what we want. - assert_matches!( - Error::from(ErrorKind::OutOfMemory).repr.data(), - ErrorData::Simple(ErrorKind::OutOfMemory), - ); -} - -#[test] -fn test_simple_message_packing() { - use super::{ErrorKind::*, SimpleMessage}; - macro_rules! check_simple_msg { - ($err:expr, $kind:ident, $msg:literal) => {{ - let e = &$err; - // Check that the public api is right. - assert_eq!(e.kind(), $kind); - assert!(format!("{e:?}").contains($msg)); - // and we got what we expected - assert_matches!( - e.repr.data(), - ErrorData::SimpleMessage(SimpleMessage { kind: $kind, message: $msg }) - ); - }}; - } - - let not_static = const_io_error!(Uncategorized, "not a constant!"); - check_simple_msg!(not_static, Uncategorized, "not a constant!"); - - const CONST: Error = const_io_error!(NotFound, "definitely a constant!"); - check_simple_msg!(CONST, NotFound, "definitely a constant!"); - - static STATIC: Error = const_io_error!(BrokenPipe, "a constant, sort of!"); - check_simple_msg!(STATIC, BrokenPipe, "a constant, sort of!"); -} - -#[derive(Debug, PartialEq)] -struct Bojji(bool); -impl error::Error for Bojji {} -impl fmt::Display for Bojji { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "ah! {:?}", self) - } -} - -#[test] -fn test_custom_error_packing() { - use super::Custom; - let test = Error::new(ErrorKind::Uncategorized, Bojji(true)); - assert_matches!( - test.repr.data(), - ErrorData::Custom(Custom { - kind: ErrorKind::Uncategorized, - error, - }) if error.downcast_ref::().as_deref() == Some(&Bojji(true)), - ); -} - -#[derive(Debug)] -struct E; - -impl fmt::Display for E { - fn fmt(&self, _f: &mut fmt::Formatter<'_>) -> fmt::Result { - Ok(()) - } -} - -impl error::Error for E {} - -#[test] -fn test_std_io_error_downcast() { - // Case 1: custom error, downcast succeeds - let io_error = Error::new(ErrorKind::Other, Bojji(true)); - let e: Bojji = io_error.downcast().unwrap(); - assert!(e.0); - - // Case 2: custom error, downcast fails - let io_error = Error::new(ErrorKind::Other, Bojji(true)); - let io_error = io_error.downcast::().unwrap_err(); - - // ensures that the custom error is intact - assert_eq!(ErrorKind::Other, io_error.kind()); - let e: Bojji = io_error.downcast().unwrap(); - assert!(e.0); - - // Case 3: os error - let errno = 20; - let io_error = Error::from_raw_os_error(errno); - let io_error = io_error.downcast::().unwrap_err(); - - assert_eq!(errno, io_error.raw_os_error().unwrap()); - - // Case 4: simple - let kind = ErrorKind::OutOfMemory; - let io_error: Error = kind.into(); - let io_error = io_error.downcast::().unwrap_err(); - - assert_eq!(kind, io_error.kind()); - - // Case 5: simple message - const SIMPLE_MESSAGE: SimpleMessage = - SimpleMessage { kind: ErrorKind::Other, message: "simple message error test" }; - let io_error = Error::from_static_message(&SIMPLE_MESSAGE); - let io_error = io_error.downcast::().unwrap_err(); - - assert_eq!(SIMPLE_MESSAGE.kind, io_error.kind()); - assert_eq!(SIMPLE_MESSAGE.message, format!("{io_error}")); -} diff --git a/library/std/src/io/impls.rs b/library/std/src/io/impls.rs deleted file mode 100644 index a8a2e9413e11c..0000000000000 --- a/library/std/src/io/impls.rs +++ /dev/null @@ -1,554 +0,0 @@ -#[cfg(test)] -mod tests; - -use crate::alloc::Allocator; -use crate::cmp; -use crate::collections::VecDeque; -use crate::fmt; -use crate::io::{self, BorrowedCursor, BufRead, IoSlice, IoSliceMut, Read, Seek, SeekFrom, Write}; -use crate::mem; -use crate::str; - -// ============================================================================= -// Forwarding implementations - -#[stable(feature = "rust1", since = "1.0.0")] -impl Read for &mut R { - #[inline] - fn read(&mut self, buf: &mut [u8]) -> io::Result { - (**self).read(buf) - } - - #[inline] - fn read_buf(&mut self, cursor: BorrowedCursor<'_>) -> io::Result<()> { - (**self).read_buf(cursor) - } - - #[inline] - fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - (**self).read_vectored(bufs) - } - - #[inline] - fn is_read_vectored(&self) -> bool { - (**self).is_read_vectored() - } - - #[inline] - fn read_to_end(&mut self, buf: &mut Vec) -> io::Result { - (**self).read_to_end(buf) - } - - #[inline] - fn read_to_string(&mut self, buf: &mut String) -> io::Result { - (**self).read_to_string(buf) - } - - #[inline] - fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> { - (**self).read_exact(buf) - } - #[inline] - fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> io::Result<()> { - (**self).read_buf_exact(cursor) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl Write for &mut W { - #[inline] - fn write(&mut self, buf: &[u8]) -> io::Result { - (**self).write(buf) - } - - #[inline] - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - (**self).write_vectored(bufs) - } - - #[inline] - fn is_write_vectored(&self) -> bool { - (**self).is_write_vectored() - } - - #[inline] - fn flush(&mut self) -> io::Result<()> { - (**self).flush() - } - - #[inline] - fn write_all(&mut self, buf: &[u8]) -> io::Result<()> { - (**self).write_all(buf) - } - - #[inline] - fn write_fmt(&mut self, fmt: fmt::Arguments<'_>) -> io::Result<()> { - (**self).write_fmt(fmt) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl Seek for &mut S { - #[inline] - fn seek(&mut self, pos: SeekFrom) -> io::Result { - (**self).seek(pos) - } - - #[inline] - fn stream_position(&mut self) -> io::Result { - (**self).stream_position() - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl BufRead for &mut B { - #[inline] - fn fill_buf(&mut self) -> io::Result<&[u8]> { - (**self).fill_buf() - } - - #[inline] - fn consume(&mut self, amt: usize) { - (**self).consume(amt) - } - - #[inline] - fn read_until(&mut self, byte: u8, buf: &mut Vec) -> io::Result { - (**self).read_until(byte, buf) - } - - #[inline] - fn read_line(&mut self, buf: &mut String) -> io::Result { - (**self).read_line(buf) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Read for Box { - #[inline] - fn read(&mut self, buf: &mut [u8]) -> io::Result { - (**self).read(buf) - } - - #[inline] - fn read_buf(&mut self, cursor: BorrowedCursor<'_>) -> io::Result<()> { - (**self).read_buf(cursor) - } - - #[inline] - fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - (**self).read_vectored(bufs) - } - - #[inline] - fn is_read_vectored(&self) -> bool { - (**self).is_read_vectored() - } - - #[inline] - fn read_to_end(&mut self, buf: &mut Vec) -> io::Result { - (**self).read_to_end(buf) - } - - #[inline] - fn read_to_string(&mut self, buf: &mut String) -> io::Result { - (**self).read_to_string(buf) - } - - #[inline] - fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> { - (**self).read_exact(buf) - } - #[inline] - fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> io::Result<()> { - (**self).read_buf_exact(cursor) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl Write for Box { - #[inline] - fn write(&mut self, buf: &[u8]) -> io::Result { - (**self).write(buf) - } - - #[inline] - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - (**self).write_vectored(bufs) - } - - #[inline] - fn is_write_vectored(&self) -> bool { - (**self).is_write_vectored() - } - - #[inline] - fn flush(&mut self) -> io::Result<()> { - (**self).flush() - } - - #[inline] - fn write_all(&mut self, buf: &[u8]) -> io::Result<()> { - (**self).write_all(buf) - } - - #[inline] - fn write_fmt(&mut self, fmt: fmt::Arguments<'_>) -> io::Result<()> { - (**self).write_fmt(fmt) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl Seek for Box { - #[inline] - fn seek(&mut self, pos: SeekFrom) -> io::Result { - (**self).seek(pos) - } - - #[inline] - fn stream_position(&mut self) -> io::Result { - (**self).stream_position() - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl BufRead for Box { - #[inline] - fn fill_buf(&mut self) -> io::Result<&[u8]> { - (**self).fill_buf() - } - - #[inline] - fn consume(&mut self, amt: usize) { - (**self).consume(amt) - } - - #[inline] - fn read_until(&mut self, byte: u8, buf: &mut Vec) -> io::Result { - (**self).read_until(byte, buf) - } - - #[inline] - fn read_line(&mut self, buf: &mut String) -> io::Result { - (**self).read_line(buf) - } -} - -// ============================================================================= -// In-memory buffer implementations - -/// Read is implemented for `&[u8]` by copying from the slice. -/// -/// Note that reading updates the slice to point to the yet unread part. -/// The slice will be empty when EOF is reached. -#[stable(feature = "rust1", since = "1.0.0")] -impl Read for &[u8] { - #[inline] - fn read(&mut self, buf: &mut [u8]) -> io::Result { - let amt = cmp::min(buf.len(), self.len()); - let (a, b) = self.split_at(amt); - - // First check if the amount of bytes we want to read is small: - // `copy_from_slice` will generally expand to a call to `memcpy`, and - // for a single byte the overhead is significant. - if amt == 1 { - buf[0] = a[0]; - } else { - buf[..amt].copy_from_slice(a); - } - - *self = b; - Ok(amt) - } - - #[inline] - fn read_buf(&mut self, mut cursor: BorrowedCursor<'_>) -> io::Result<()> { - let amt = cmp::min(cursor.capacity(), self.len()); - let (a, b) = self.split_at(amt); - - cursor.append(a); - - *self = b; - Ok(()) - } - - #[inline] - fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - let mut nread = 0; - for buf in bufs { - nread += self.read(buf)?; - if self.is_empty() { - break; - } - } - - Ok(nread) - } - - #[inline] - fn is_read_vectored(&self) -> bool { - true - } - - #[inline] - fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> { - if buf.len() > self.len() { - // `read_exact` makes no promise about the content of `buf` if it - // fails so don't bother about that. - *self = &self[self.len()..]; - return Err(io::Error::READ_EXACT_EOF); - } - let (a, b) = self.split_at(buf.len()); - - // First check if the amount of bytes we want to read is small: - // `copy_from_slice` will generally expand to a call to `memcpy`, and - // for a single byte the overhead is significant. - if buf.len() == 1 { - buf[0] = a[0]; - } else { - buf.copy_from_slice(a); - } - - *self = b; - Ok(()) - } - - #[inline] - fn read_buf_exact(&mut self, mut cursor: BorrowedCursor<'_>) -> io::Result<()> { - if cursor.capacity() > self.len() { - // Append everything we can to the cursor. - cursor.append(*self); - *self = &self[self.len()..]; - return Err(io::Error::READ_EXACT_EOF); - } - let (a, b) = self.split_at(cursor.capacity()); - - cursor.append(a); - - *self = b; - Ok(()) - } - - #[inline] - fn read_to_end(&mut self, buf: &mut Vec) -> io::Result { - let len = self.len(); - buf.try_reserve(len)?; - buf.extend_from_slice(*self); - *self = &self[len..]; - Ok(len) - } - - #[inline] - fn read_to_string(&mut self, buf: &mut String) -> io::Result { - let content = str::from_utf8(self).map_err(|_| io::Error::INVALID_UTF8)?; - let len = self.len(); - buf.try_reserve(len)?; - buf.push_str(content); - *self = &self[len..]; - Ok(len) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl BufRead for &[u8] { - #[inline] - fn fill_buf(&mut self) -> io::Result<&[u8]> { - Ok(*self) - } - - #[inline] - fn consume(&mut self, amt: usize) { - *self = &self[amt..]; - } -} - -/// Write is implemented for `&mut [u8]` by copying into the slice, overwriting -/// its data. -/// -/// Note that writing updates the slice to point to the yet unwritten part. -/// The slice will be empty when it has been completely overwritten. -/// -/// If the number of bytes to be written exceeds the size of the slice, write operations will -/// return short writes: ultimately, `Ok(0)`; in this situation, `write_all` returns an error of -/// kind `ErrorKind::WriteZero`. -#[stable(feature = "rust1", since = "1.0.0")] -impl Write for &mut [u8] { - #[inline] - fn write(&mut self, data: &[u8]) -> io::Result { - let amt = cmp::min(data.len(), self.len()); - let (a, b) = mem::take(self).split_at_mut(amt); - a.copy_from_slice(&data[..amt]); - *self = b; - Ok(amt) - } - - #[inline] - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - let mut nwritten = 0; - for buf in bufs { - nwritten += self.write(buf)?; - if self.is_empty() { - break; - } - } - - Ok(nwritten) - } - - #[inline] - fn is_write_vectored(&self) -> bool { - true - } - - #[inline] - fn write_all(&mut self, data: &[u8]) -> io::Result<()> { - if self.write(data)? == data.len() { Ok(()) } else { Err(io::Error::WRITE_ALL_EOF) } - } - - #[inline] - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -/// Write is implemented for `Vec` by appending to the vector. -/// The vector will grow as needed. -#[stable(feature = "rust1", since = "1.0.0")] -impl Write for Vec { - #[inline] - fn write(&mut self, buf: &[u8]) -> io::Result { - self.extend_from_slice(buf); - Ok(buf.len()) - } - - #[inline] - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - let len = bufs.iter().map(|b| b.len()).sum(); - self.reserve(len); - for buf in bufs { - self.extend_from_slice(buf); - } - Ok(len) - } - - #[inline] - fn is_write_vectored(&self) -> bool { - true - } - - #[inline] - fn write_all(&mut self, buf: &[u8]) -> io::Result<()> { - self.extend_from_slice(buf); - Ok(()) - } - - #[inline] - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -/// Read is implemented for `VecDeque` by consuming bytes from the front of the `VecDeque`. -#[stable(feature = "vecdeque_read_write", since = "1.63.0")] -impl Read for VecDeque { - /// Fill `buf` with the contents of the "front" slice as returned by - /// [`as_slices`][`VecDeque::as_slices`]. If the contained byte slices of the `VecDeque` are - /// discontiguous, multiple calls to `read` will be needed to read the entire content. - #[inline] - fn read(&mut self, buf: &mut [u8]) -> io::Result { - let (ref mut front, _) = self.as_slices(); - let n = Read::read(front, buf)?; - self.drain(..n); - Ok(n) - } - - #[inline] - fn read_buf(&mut self, cursor: BorrowedCursor<'_>) -> io::Result<()> { - let (ref mut front, _) = self.as_slices(); - let n = cmp::min(cursor.capacity(), front.len()); - Read::read_buf(front, cursor)?; - self.drain(..n); - Ok(()) - } - - #[inline] - fn read_to_end(&mut self, buf: &mut Vec) -> io::Result { - // The total len is known upfront so we can reserve it in a single call. - let len = self.len(); - buf.try_reserve(len)?; - - let (front, back) = self.as_slices(); - buf.extend_from_slice(front); - buf.extend_from_slice(back); - self.clear(); - Ok(len) - } - - #[inline] - fn read_to_string(&mut self, buf: &mut String) -> io::Result { - // SAFETY: We only append to the buffer - unsafe { io::append_to_string(buf, |buf| self.read_to_end(buf)) } - } -} - -/// BufRead is implemented for `VecDeque` by reading bytes from the front of the `VecDeque`. -#[stable(feature = "vecdeque_buf_read", since = "1.75.0")] -impl BufRead for VecDeque { - /// Returns the contents of the "front" slice as returned by - /// [`as_slices`][`VecDeque::as_slices`]. If the contained byte slices of the `VecDeque` are - /// discontiguous, multiple calls to `fill_buf` will be needed to read the entire content. - #[inline] - fn fill_buf(&mut self) -> io::Result<&[u8]> { - let (front, _) = self.as_slices(); - Ok(front) - } - - #[inline] - fn consume(&mut self, amt: usize) { - self.drain(..amt); - } -} - -/// Write is implemented for `VecDeque` by appending to the `VecDeque`, growing it as needed. -#[stable(feature = "vecdeque_read_write", since = "1.63.0")] -impl Write for VecDeque { - #[inline] - fn write(&mut self, buf: &[u8]) -> io::Result { - self.extend(buf); - Ok(buf.len()) - } - - #[inline] - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - let len = bufs.iter().map(|b| b.len()).sum(); - self.reserve(len); - for buf in bufs { - self.extend(&**buf); - } - Ok(len) - } - - #[inline] - fn is_write_vectored(&self) -> bool { - true - } - - #[inline] - fn write_all(&mut self, buf: &[u8]) -> io::Result<()> { - self.extend(buf); - Ok(()) - } - - #[inline] - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -#[unstable(feature = "read_buf", issue = "78485")] -impl<'a> io::Write for core::io::BorrowedCursor<'a> { - fn write(&mut self, buf: &[u8]) -> io::Result { - let amt = cmp::min(buf.len(), self.capacity()); - self.append(&buf[..amt]); - Ok(amt) - } - - #[inline] - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} diff --git a/library/std/src/io/impls/tests.rs b/library/std/src/io/impls/tests.rs deleted file mode 100644 index d1cd84a67ada5..0000000000000 --- a/library/std/src/io/impls/tests.rs +++ /dev/null @@ -1,57 +0,0 @@ -use crate::io::prelude::*; - -#[bench] -fn bench_read_slice(b: &mut test::Bencher) { - let buf = [5; 1024]; - let mut dst = [0; 128]; - - b.iter(|| { - let mut rd = &buf[..]; - for _ in 0..8 { - let _ = rd.read(&mut dst); - test::black_box(&dst); - } - }) -} - -#[bench] -fn bench_write_slice(b: &mut test::Bencher) { - let mut buf = [0; 1024]; - let src = [5; 128]; - - b.iter(|| { - let mut wr = &mut buf[..]; - for _ in 0..8 { - let _ = wr.write_all(&src); - test::black_box(&wr); - } - }) -} - -#[bench] -fn bench_read_vec(b: &mut test::Bencher) { - let buf = vec![5; 1024]; - let mut dst = [0; 128]; - - b.iter(|| { - let mut rd = &buf[..]; - for _ in 0..8 { - let _ = rd.read(&mut dst); - test::black_box(&dst); - } - }) -} - -#[bench] -fn bench_write_vec(b: &mut test::Bencher) { - let mut buf = Vec::with_capacity(1024); - let src = [5; 128]; - - b.iter(|| { - let mut wr = &mut buf[..]; - for _ in 0..8 { - let _ = wr.write_all(&src); - test::black_box(&wr); - } - }) -} diff --git a/library/std/src/io/mod.rs b/library/std/src/io/mod.rs deleted file mode 100644 index f55ec1588f91d..0000000000000 --- a/library/std/src/io/mod.rs +++ /dev/null @@ -1,3195 +0,0 @@ -//! Traits, helpers, and type definitions for core I/O functionality. -//! -//! The `std::io` module contains a number of common things you'll need -//! when doing input and output. The most core part of this module is -//! the [`Read`] and [`Write`] traits, which provide the -//! most general interface for reading and writing input and output. -//! -//! ## Read and Write -//! -//! Because they are traits, [`Read`] and [`Write`] are implemented by a number -//! of other types, and you can implement them for your types too. As such, -//! you'll see a few different types of I/O throughout the documentation in -//! this module: [`File`]s, [`TcpStream`]s, and sometimes even [`Vec`]s. For -//! example, [`Read`] adds a [`read`][`Read::read`] method, which we can use on -//! [`File`]s: -//! -//! ```no_run -//! use std::io; -//! use std::io::prelude::*; -//! use std::fs::File; -//! -//! fn main() -> io::Result<()> { -//! let mut f = File::open("foo.txt")?; -//! let mut buffer = [0; 10]; -//! -//! // read up to 10 bytes -//! let n = f.read(&mut buffer)?; -//! -//! println!("The bytes: {:?}", &buffer[..n]); -//! Ok(()) -//! } -//! ``` -//! -//! [`Read`] and [`Write`] are so important, implementors of the two traits have a -//! nickname: readers and writers. So you'll sometimes see 'a reader' instead -//! of 'a type that implements the [`Read`] trait'. Much easier! -//! -//! ## Seek and BufRead -//! -//! Beyond that, there are two important traits that are provided: [`Seek`] -//! and [`BufRead`]. Both of these build on top of a reader to control -//! how the reading happens. [`Seek`] lets you control where the next byte is -//! coming from: -//! -//! ```no_run -//! use std::io; -//! use std::io::prelude::*; -//! use std::io::SeekFrom; -//! use std::fs::File; -//! -//! fn main() -> io::Result<()> { -//! let mut f = File::open("foo.txt")?; -//! let mut buffer = [0; 10]; -//! -//! // skip to the last 10 bytes of the file -//! f.seek(SeekFrom::End(-10))?; -//! -//! // read up to 10 bytes -//! let n = f.read(&mut buffer)?; -//! -//! println!("The bytes: {:?}", &buffer[..n]); -//! Ok(()) -//! } -//! ``` -//! -//! [`BufRead`] uses an internal buffer to provide a number of other ways to read, but -//! to show it off, we'll need to talk about buffers in general. Keep reading! -//! -//! ## BufReader and BufWriter -//! -//! Byte-based interfaces are unwieldy and can be inefficient, as we'd need to be -//! making near-constant calls to the operating system. To help with this, -//! `std::io` comes with two structs, [`BufReader`] and [`BufWriter`], which wrap -//! readers and writers. The wrapper uses a buffer, reducing the number of -//! calls and providing nicer methods for accessing exactly what you want. -//! -//! For example, [`BufReader`] works with the [`BufRead`] trait to add extra -//! methods to any reader: -//! -//! ```no_run -//! use std::io; -//! use std::io::prelude::*; -//! use std::io::BufReader; -//! use std::fs::File; -//! -//! fn main() -> io::Result<()> { -//! let f = File::open("foo.txt")?; -//! let mut reader = BufReader::new(f); -//! let mut buffer = String::new(); -//! -//! // read a line into buffer -//! reader.read_line(&mut buffer)?; -//! -//! println!("{buffer}"); -//! Ok(()) -//! } -//! ``` -//! -//! [`BufWriter`] doesn't add any new ways of writing; it just buffers every call -//! to [`write`][`Write::write`]: -//! -//! ```no_run -//! use std::io; -//! use std::io::prelude::*; -//! use std::io::BufWriter; -//! use std::fs::File; -//! -//! fn main() -> io::Result<()> { -//! let f = File::create("foo.txt")?; -//! { -//! let mut writer = BufWriter::new(f); -//! -//! // write a byte to the buffer -//! writer.write(&[42])?; -//! -//! } // the buffer is flushed once writer goes out of scope -//! -//! Ok(()) -//! } -//! ``` -//! -//! ## Standard input and output -//! -//! A very common source of input is standard input: -//! -//! ```no_run -//! use std::io; -//! -//! fn main() -> io::Result<()> { -//! let mut input = String::new(); -//! -//! io::stdin().read_line(&mut input)?; -//! -//! println!("You typed: {}", input.trim()); -//! Ok(()) -//! } -//! ``` -//! -//! Note that you cannot use the [`?` operator] in functions that do not return -//! a [`Result`][`Result`]. Instead, you can call [`.unwrap()`] -//! or `match` on the return value to catch any possible errors: -//! -//! ```no_run -//! use std::io; -//! -//! let mut input = String::new(); -//! -//! io::stdin().read_line(&mut input).unwrap(); -//! ``` -//! -//! And a very common source of output is standard output: -//! -//! ```no_run -//! use std::io; -//! use std::io::prelude::*; -//! -//! fn main() -> io::Result<()> { -//! io::stdout().write(&[42])?; -//! Ok(()) -//! } -//! ``` -//! -//! Of course, using [`io::stdout`] directly is less common than something like -//! [`println!`]. -//! -//! ## Iterator types -//! -//! A large number of the structures provided by `std::io` are for various -//! ways of iterating over I/O. For example, [`Lines`] is used to split over -//! lines: -//! -//! ```no_run -//! use std::io; -//! use std::io::prelude::*; -//! use std::io::BufReader; -//! use std::fs::File; -//! -//! fn main() -> io::Result<()> { -//! let f = File::open("foo.txt")?; -//! let reader = BufReader::new(f); -//! -//! for line in reader.lines() { -//! println!("{}", line?); -//! } -//! Ok(()) -//! } -//! ``` -//! -//! ## Functions -//! -//! There are a number of [functions][functions-list] that offer access to various -//! features. For example, we can use three of these functions to copy everything -//! from standard input to standard output: -//! -//! ```no_run -//! use std::io; -//! -//! fn main() -> io::Result<()> { -//! io::copy(&mut io::stdin(), &mut io::stdout())?; -//! Ok(()) -//! } -//! ``` -//! -//! [functions-list]: #functions-1 -//! -//! ## io::Result -//! -//! Last, but certainly not least, is [`io::Result`]. This type is used -//! as the return type of many `std::io` functions that can cause an error, and -//! can be returned from your own functions as well. Many of the examples in this -//! module use the [`?` operator]: -//! -//! ``` -//! use std::io; -//! -//! fn read_input() -> io::Result<()> { -//! let mut input = String::new(); -//! -//! io::stdin().read_line(&mut input)?; -//! -//! println!("You typed: {}", input.trim()); -//! -//! Ok(()) -//! } -//! ``` -//! -//! The return type of `read_input()`, [`io::Result<()>`][`io::Result`], is a very -//! common type for functions which don't have a 'real' return value, but do want to -//! return errors if they happen. In this case, the only purpose of this function is -//! to read the line and print it, so we use `()`. -//! -//! ## Platform-specific behavior -//! -//! Many I/O functions throughout the standard library are documented to indicate -//! what various library or syscalls they are delegated to. This is done to help -//! applications both understand what's happening under the hood as well as investigate -//! any possibly unclear semantics. Note, however, that this is informative, not a binding -//! contract. The implementation of many of these functions are subject to change over -//! time and may call fewer or more syscalls/library functions. -//! -//! ## I/O Safety -//! -//! Rust follows an I/O safety discipline that is comparable to its memory safety discipline. This -//! means that file descriptors can be *exclusively owned*. (Here, "file descriptor" is meant to -//! subsume similar concepts that exist across a wide range of operating systems even if they might -//! use a different name, such as "handle".) An exclusively owned file descriptor is one that no -//! other code is allowed to access in any way, but the owner is allowed to access and even close -//! it any time. A type that owns its file descriptor should usually close it in its `drop` -//! function. Types like [`File`] own their file descriptor. Similarly, file descriptors -//! can be *borrowed*, granting the temporary right to perform operations on this file descriptor. -//! This indicates that the file descriptor will not be closed for the lifetime of the borrow, but -//! it does *not* imply any right to close this file descriptor, since it will likely be owned by -//! someone else. -//! -//! The platform-specific parts of the Rust standard library expose types that reflect these -//! concepts, see [`os::unix`] and [`os::windows`]. -//! -//! To uphold I/O safety, it is crucial that no code acts on file descriptors it does not own or -//! borrow, and no code closes file descriptors it does not own. In other words, a safe function -//! that takes a regular integer, treats it as a file descriptor, and acts on it, is *unsound*. -//! -//! Not upholding I/O safety and acting on a file descriptor without proof of ownership can lead to -//! misbehavior and even Undefined Behavior in code that relies on ownership of its file -//! descriptors: a closed file descriptor could be re-allocated, so the original owner of that file -//! descriptor is now working on the wrong file. Some code might even rely on fully encapsulating -//! its file descriptors with no operations being performed by any other part of the program. -//! -//! Note that exclusive ownership of a file descriptor does *not* imply exclusive ownership of the -//! underlying kernel object that the file descriptor references (also called "open file description" on -//! some operating systems). File descriptors basically work like [`Arc`]: when you receive an owned -//! file descriptor, you cannot know whether there are any other file descriptors that reference the -//! same kernel object. However, when you create a new kernel object, you know that you are holding -//! the only reference to it. Just be careful not to lend it to anyone, since they can obtain a -//! clone and then you can no longer know what the reference count is! In that sense, [`OwnedFd`] is -//! like `Arc` and [`BorrowedFd<'a>`] is like `&'a Arc` (and similar for the Windows types). In -//! particular, given a `BorrowedFd<'a>`, you are not allowed to close the file descriptor -- just -//! like how, given a `&'a Arc`, you are not allowed to decrement the reference count and -//! potentially free the underlying object. There is no equivalent to `Box` for file descriptors in -//! the standard library (that would be a type that guarantees that the reference count is `1`), -//! however, it would be possible for a crate to define a type with those semantics. -//! -//! [`File`]: crate::fs::File -//! [`TcpStream`]: crate::net::TcpStream -//! [`io::stdout`]: stdout -//! [`io::Result`]: self::Result -//! [`?` operator]: ../../book/appendix-02-operators.html -//! [`Result`]: crate::result::Result -//! [`.unwrap()`]: crate::result::Result::unwrap -//! [`os::unix`]: ../os/unix/io/index.html -//! [`os::windows`]: ../os/windows/io/index.html -//! [`OwnedFd`]: ../os/fd/struct.OwnedFd.html -//! [`BorrowedFd<'a>`]: ../os/fd/struct.BorrowedFd.html -//! [`Arc`]: crate::sync::Arc - -#![stable(feature = "rust1", since = "1.0.0")] - -#[cfg(test)] -mod tests; - -use crate::cmp; -use crate::fmt; -use crate::mem::take; -use crate::ops::{Deref, DerefMut}; -use crate::slice; -use crate::str; -use crate::sys; -use core::slice::memchr; - -#[stable(feature = "bufwriter_into_parts", since = "1.56.0")] -pub use self::buffered::WriterPanicked; -#[unstable(feature = "raw_os_error_ty", issue = "107792")] -pub use self::error::RawOsError; -pub(crate) use self::stdio::attempt_print_to_stderr; -#[stable(feature = "is_terminal", since = "1.70.0")] -pub use self::stdio::IsTerminal; -#[unstable(feature = "print_internals", issue = "none")] -#[doc(hidden)] -pub use self::stdio::{_eprint, _print}; -#[unstable(feature = "internal_output_capture", issue = "none")] -#[doc(no_inline, hidden)] -pub use self::stdio::{set_output_capture, try_set_output_capture}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::{ - buffered::{BufReader, BufWriter, IntoInnerError, LineWriter}, - copy::copy, - cursor::Cursor, - error::{Error, ErrorKind, Result}, - stdio::{stderr, stdin, stdout, Stderr, StderrLock, Stdin, StdinLock, Stdout, StdoutLock}, - util::{empty, repeat, sink, Empty, Repeat, Sink}, -}; - -#[unstable(feature = "read_buf", issue = "78485")] -pub use core::io::{BorrowedBuf, BorrowedCursor}; -pub(crate) use error::const_io_error; - -mod buffered; -pub(crate) mod copy; -mod cursor; -mod error; -mod impls; -pub mod prelude; -mod stdio; -mod util; - -const DEFAULT_BUF_SIZE: usize = crate::sys_common::io::DEFAULT_BUF_SIZE; - -pub(crate) use stdio::cleanup; - -struct Guard<'a> { - buf: &'a mut Vec, - len: usize, -} - -impl Drop for Guard<'_> { - fn drop(&mut self) { - unsafe { - self.buf.set_len(self.len); - } - } -} - -// Several `read_to_string` and `read_line` methods in the standard library will -// append data into a `String` buffer, but we need to be pretty careful when -// doing this. The implementation will just call `.as_mut_vec()` and then -// delegate to a byte-oriented reading method, but we must ensure that when -// returning we never leave `buf` in a state such that it contains invalid UTF-8 -// in its bounds. -// -// To this end, we use an RAII guard (to protect against panics) which updates -// the length of the string when it is dropped. This guard initially truncates -// the string to the prior length and only after we've validated that the -// new contents are valid UTF-8 do we allow it to set a longer length. -// -// The unsafety in this function is twofold: -// -// 1. We're looking at the raw bytes of `buf`, so we take on the burden of UTF-8 -// checks. -// 2. We're passing a raw buffer to the function `f`, and it is expected that -// the function only *appends* bytes to the buffer. We'll get undefined -// behavior if existing bytes are overwritten to have non-UTF-8 data. -pub(crate) unsafe fn append_to_string(buf: &mut String, f: F) -> Result -where - F: FnOnce(&mut Vec) -> Result, -{ - let mut g = Guard { len: buf.len(), buf: buf.as_mut_vec() }; - let ret = f(g.buf); - - // SAFETY: the caller promises to only append data to `buf` - let appended = g.buf.get_unchecked(g.len..); - if str::from_utf8(appended).is_err() { - ret.and_then(|_| Err(Error::INVALID_UTF8)) - } else { - g.len = g.buf.len(); - ret - } -} - -// Here we must serve many masters with conflicting goals: -// -// - avoid allocating unless necessary -// - avoid overallocating if we know the exact size (#89165) -// - avoid passing large buffers to readers that always initialize the free capacity if they perform short reads (#23815, #23820) -// - pass large buffers to readers that do not initialize the spare capacity. this can amortize per-call overheads -// - and finally pass not-too-small and not-too-large buffers to Windows read APIs because they manage to suffer from both problems -// at the same time, i.e. small reads suffer from syscall overhead, all reads incur initialization cost -// proportional to buffer size (#110650) -// -pub(crate) fn default_read_to_end( - r: &mut R, - buf: &mut Vec, - size_hint: Option, -) -> Result { - let start_len = buf.len(); - let start_cap = buf.capacity(); - // Optionally limit the maximum bytes read on each iteration. - // This adds an arbitrary fiddle factor to allow for more data than we expect. - let mut max_read_size = size_hint - .and_then(|s| s.checked_add(1024)?.checked_next_multiple_of(DEFAULT_BUF_SIZE)) - .unwrap_or(DEFAULT_BUF_SIZE); - - let mut initialized = 0; // Extra initialized bytes from previous loop iteration - - const PROBE_SIZE: usize = 32; - - fn small_probe_read(r: &mut R, buf: &mut Vec) -> Result { - let mut probe = [0u8; PROBE_SIZE]; - - loop { - match r.read(&mut probe) { - Ok(n) => { - // there is no way to recover from allocation failure here - // because the data has already been read. - buf.extend_from_slice(&probe[..n]); - return Ok(n); - } - Err(ref e) if e.is_interrupted() => continue, - Err(e) => return Err(e), - } - } - } - - // avoid inflating empty/small vecs before we have determined that there's anything to read - if (size_hint.is_none() || size_hint == Some(0)) && buf.capacity() - buf.len() < PROBE_SIZE { - let read = small_probe_read(r, buf)?; - - if read == 0 { - return Ok(0); - } - } - - loop { - if buf.len() == buf.capacity() && buf.capacity() == start_cap { - // The buffer might be an exact fit. Let's read into a probe buffer - // and see if it returns `Ok(0)`. If so, we've avoided an - // unnecessary doubling of the capacity. But if not, append the - // probe buffer to the primary buffer and let its capacity grow. - let read = small_probe_read(r, buf)?; - - if read == 0 { - return Ok(buf.len() - start_len); - } - } - - if buf.len() == buf.capacity() { - // buf is full, need more space - buf.try_reserve(PROBE_SIZE)?; - } - - let mut spare = buf.spare_capacity_mut(); - let buf_len = cmp::min(spare.len(), max_read_size); - spare = &mut spare[..buf_len]; - let mut read_buf: BorrowedBuf<'_> = spare.into(); - - // SAFETY: These bytes were initialized but not filled in the previous loop - unsafe { - read_buf.set_init(initialized); - } - - let mut cursor = read_buf.unfilled(); - loop { - match r.read_buf(cursor.reborrow()) { - Ok(()) => break, - Err(e) if e.is_interrupted() => continue, - Err(e) => return Err(e), - } - } - - let unfilled_but_initialized = cursor.init_ref().len(); - let bytes_read = cursor.written(); - let was_fully_initialized = read_buf.init_len() == buf_len; - - if bytes_read == 0 { - return Ok(buf.len() - start_len); - } - - // store how much was initialized but not filled - initialized = unfilled_but_initialized; - - // SAFETY: BorrowedBuf's invariants mean this much memory is initialized. - unsafe { - let new_len = bytes_read + buf.len(); - buf.set_len(new_len); - } - - // Use heuristics to determine the max read size if no initial size hint was provided - if size_hint.is_none() { - // The reader is returning short reads but it doesn't call ensure_init(). - // In that case we no longer need to restrict read sizes to avoid - // initialization costs. - if !was_fully_initialized { - max_read_size = usize::MAX; - } - - // we have passed a larger buffer than previously and the - // reader still hasn't returned a short read - if buf_len >= max_read_size && bytes_read == buf_len { - max_read_size = max_read_size.saturating_mul(2); - } - } - } -} - -pub(crate) fn default_read_to_string( - r: &mut R, - buf: &mut String, - size_hint: Option, -) -> Result { - // Note that we do *not* call `r.read_to_end()` here. We are passing - // `&mut Vec` (the raw contents of `buf`) into the `read_to_end` - // method to fill it up. An arbitrary implementation could overwrite the - // entire contents of the vector, not just append to it (which is what - // we are expecting). - // - // To prevent extraneously checking the UTF-8-ness of the entire buffer - // we pass it to our hardcoded `default_read_to_end` implementation which - // we know is guaranteed to only read data into the end of the buffer. - unsafe { append_to_string(buf, |b| default_read_to_end(r, b, size_hint)) } -} - -pub(crate) fn default_read_vectored(read: F, bufs: &mut [IoSliceMut<'_>]) -> Result -where - F: FnOnce(&mut [u8]) -> Result, -{ - let buf = bufs.iter_mut().find(|b| !b.is_empty()).map_or(&mut [][..], |b| &mut **b); - read(buf) -} - -pub(crate) fn default_write_vectored(write: F, bufs: &[IoSlice<'_>]) -> Result -where - F: FnOnce(&[u8]) -> Result, -{ - let buf = bufs.iter().find(|b| !b.is_empty()).map_or(&[][..], |b| &**b); - write(buf) -} - -pub(crate) fn default_read_exact(this: &mut R, mut buf: &mut [u8]) -> Result<()> { - while !buf.is_empty() { - match this.read(buf) { - Ok(0) => break, - Ok(n) => { - buf = &mut buf[n..]; - } - Err(ref e) if e.is_interrupted() => {} - Err(e) => return Err(e), - } - } - if !buf.is_empty() { Err(Error::READ_EXACT_EOF) } else { Ok(()) } -} - -pub(crate) fn default_read_buf(read: F, mut cursor: BorrowedCursor<'_>) -> Result<()> -where - F: FnOnce(&mut [u8]) -> Result, -{ - let n = read(cursor.ensure_init().init_mut())?; - cursor.advance(n); - Ok(()) -} - -pub(crate) fn default_read_buf_exact( - this: &mut R, - mut cursor: BorrowedCursor<'_>, -) -> Result<()> { - while cursor.capacity() > 0 { - let prev_written = cursor.written(); - match this.read_buf(cursor.reborrow()) { - Ok(()) => {} - Err(e) if e.is_interrupted() => continue, - Err(e) => return Err(e), - } - - if cursor.written() == prev_written { - return Err(Error::READ_EXACT_EOF); - } - } - - Ok(()) -} - -/// The `Read` trait allows for reading bytes from a source. -/// -/// Implementors of the `Read` trait are called 'readers'. -/// -/// Readers are defined by one required method, [`read()`]. Each call to [`read()`] -/// will attempt to pull bytes from this source into a provided buffer. A -/// number of other methods are implemented in terms of [`read()`], giving -/// implementors a number of ways to read bytes while only needing to implement -/// a single method. -/// -/// Readers are intended to be composable with one another. Many implementors -/// throughout [`std::io`] take and provide types which implement the `Read` -/// trait. -/// -/// Please note that each call to [`read()`] may involve a system call, and -/// therefore, using something that implements [`BufRead`], such as -/// [`BufReader`], will be more efficient. -/// -/// Repeated calls to the reader use the same cursor, so for example -/// calling `read_to_end` twice on a [`File`] will only return the file's -/// contents once. It's recommended to first call `rewind()` in that case. -/// -/// # Examples -/// -/// [`File`]s implement `Read`: -/// -/// ```no_run -/// use std::io; -/// use std::io::prelude::*; -/// use std::fs::File; -/// -/// fn main() -> io::Result<()> { -/// let mut f = File::open("foo.txt")?; -/// let mut buffer = [0; 10]; -/// -/// // read up to 10 bytes -/// f.read(&mut buffer)?; -/// -/// let mut buffer = Vec::new(); -/// // read the whole file -/// f.read_to_end(&mut buffer)?; -/// -/// // read into a String, so that you don't need to do the conversion. -/// let mut buffer = String::new(); -/// f.read_to_string(&mut buffer)?; -/// -/// // and more! See the other methods for more details. -/// Ok(()) -/// } -/// ``` -/// -/// Read from [`&str`] because [`&[u8]`][prim@slice] implements `Read`: -/// -/// ```no_run -/// # use std::io; -/// use std::io::prelude::*; -/// -/// fn main() -> io::Result<()> { -/// let mut b = "This string will be read".as_bytes(); -/// let mut buffer = [0; 10]; -/// -/// // read up to 10 bytes -/// b.read(&mut buffer)?; -/// -/// // etc... it works exactly as a File does! -/// Ok(()) -/// } -/// ``` -/// -/// [`read()`]: Read::read -/// [`&str`]: prim@str -/// [`std::io`]: self -/// [`File`]: crate::fs::File -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(notable_trait)] -#[cfg_attr(not(test), rustc_diagnostic_item = "IoRead")] -pub trait Read { - /// Pull some bytes from this source into the specified buffer, returning - /// how many bytes were read. - /// - /// This function does not provide any guarantees about whether it blocks - /// waiting for data, but if an object needs to block for a read and cannot, - /// it will typically signal this via an [`Err`] return value. - /// - /// If the return value of this method is [`Ok(n)`], then implementations must - /// guarantee that `0 <= n <= buf.len()`. A nonzero `n` value indicates - /// that the buffer `buf` has been filled in with `n` bytes of data from this - /// source. If `n` is `0`, then it can indicate one of two scenarios: - /// - /// 1. This reader has reached its "end of file" and will likely no longer - /// be able to produce bytes. Note that this does not mean that the - /// reader will *always* no longer be able to produce bytes. As an example, - /// on Linux, this method will call the `recv` syscall for a [`TcpStream`], - /// where returning zero indicates the connection was shut down correctly. While - /// for [`File`], it is possible to reach the end of file and get zero as result, - /// but if more data is appended to the file, future calls to `read` will return - /// more data. - /// 2. The buffer specified was 0 bytes in length. - /// - /// It is not an error if the returned value `n` is smaller than the buffer size, - /// even when the reader is not at the end of the stream yet. - /// This may happen for example because fewer bytes are actually available right now - /// (e. g. being close to end-of-file) or because read() was interrupted by a signal. - /// - /// As this trait is safe to implement, callers in unsafe code cannot rely on - /// `n <= buf.len()` for safety. - /// Extra care needs to be taken when `unsafe` functions are used to access the read bytes. - /// Callers have to ensure that no unchecked out-of-bounds accesses are possible even if - /// `n > buf.len()`. - /// - /// *Implementations* of this method can make no assumptions about the contents of `buf` when - /// this function is called. It is recommended that implementations only write data to `buf` - /// instead of reading its contents. - /// - /// Correspondingly, however, *callers* of this method in unsafe code must not assume - /// any guarantees about how the implementation uses `buf`. The trait is safe to implement, - /// so it is possible that the code that's supposed to write to the buffer might also read - /// from it. It is your responsibility to make sure that `buf` is initialized - /// before calling `read`. Calling `read` with an uninitialized `buf` (of the kind one - /// obtains via [`MaybeUninit`]) is not safe, and can lead to undefined behavior. - /// - /// [`MaybeUninit`]: crate::mem::MaybeUninit - /// - /// # Errors - /// - /// If this function encounters any form of I/O or other error, an error - /// variant will be returned. If an error is returned then it must be - /// guaranteed that no bytes were read. - /// - /// An error of the [`ErrorKind::Interrupted`] kind is non-fatal and the read - /// operation should be retried if there is nothing else to do. - /// - /// # Examples - /// - /// [`File`]s implement `Read`: - /// - /// [`Ok(n)`]: Ok - /// [`File`]: crate::fs::File - /// [`TcpStream`]: crate::net::TcpStream - /// - /// ```no_run - /// use std::io; - /// use std::io::prelude::*; - /// use std::fs::File; - /// - /// fn main() -> io::Result<()> { - /// let mut f = File::open("foo.txt")?; - /// let mut buffer = [0; 10]; - /// - /// // read up to 10 bytes - /// let n = f.read(&mut buffer[..])?; - /// - /// println!("The bytes: {:?}", &buffer[..n]); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn read(&mut self, buf: &mut [u8]) -> Result; - - /// Like `read`, except that it reads into a slice of buffers. - /// - /// Data is copied to fill each buffer in order, with the final buffer - /// written to possibly being only partially filled. This method must - /// behave equivalently to a single call to `read` with concatenated - /// buffers. - /// - /// The default implementation calls `read` with either the first nonempty - /// buffer provided, or an empty one if none exists. - #[stable(feature = "iovec", since = "1.36.0")] - fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result { - default_read_vectored(|b| self.read(b), bufs) - } - - /// Determines if this `Read`er has an efficient `read_vectored` - /// implementation. - /// - /// If a `Read`er does not override the default `read_vectored` - /// implementation, code using it may want to avoid the method all together - /// and coalesce writes into a single buffer for higher performance. - /// - /// The default implementation returns `false`. - #[unstable(feature = "can_vector", issue = "69941")] - fn is_read_vectored(&self) -> bool { - false - } - - /// Read all bytes until EOF in this source, placing them into `buf`. - /// - /// All bytes read from this source will be appended to the specified buffer - /// `buf`. This function will continuously call [`read()`] to append more data to - /// `buf` until [`read()`] returns either [`Ok(0)`] or an error of - /// non-[`ErrorKind::Interrupted`] kind. - /// - /// If successful, this function will return the total number of bytes read. - /// - /// # Errors - /// - /// If this function encounters an error of the kind - /// [`ErrorKind::Interrupted`] then the error is ignored and the operation - /// will continue. - /// - /// If any other read error is encountered then this function immediately - /// returns. Any bytes which have already been read will be appended to - /// `buf`. - /// - /// # Examples - /// - /// [`File`]s implement `Read`: - /// - /// [`read()`]: Read::read - /// [`Ok(0)`]: Ok - /// [`File`]: crate::fs::File - /// - /// ```no_run - /// use std::io; - /// use std::io::prelude::*; - /// use std::fs::File; - /// - /// fn main() -> io::Result<()> { - /// let mut f = File::open("foo.txt")?; - /// let mut buffer = Vec::new(); - /// - /// // read the whole file - /// f.read_to_end(&mut buffer)?; - /// Ok(()) - /// } - /// ``` - /// - /// (See also the [`std::fs::read`] convenience function for reading from a - /// file.) - /// - /// [`std::fs::read`]: crate::fs::read - /// - /// ## Implementing `read_to_end` - /// - /// When implementing the `io::Read` trait, it is recommended to allocate - /// memory using [`Vec::try_reserve`]. However, this behavior is not guaranteed - /// by all implementations, and `read_to_end` may not handle out-of-memory - /// situations gracefully. - /// - /// ```no_run - /// # use std::io::{self, BufRead}; - /// # struct Example { example_datasource: io::Empty } impl Example { - /// # fn get_some_data_for_the_example(&self) -> &'static [u8] { &[] } - /// fn read_to_end(&mut self, dest_vec: &mut Vec) -> io::Result { - /// let initial_vec_len = dest_vec.len(); - /// loop { - /// let src_buf = self.example_datasource.fill_buf()?; - /// if src_buf.is_empty() { - /// break; - /// } - /// dest_vec.try_reserve(src_buf.len())?; - /// dest_vec.extend_from_slice(src_buf); - /// - /// // Any irreversible side effects should happen after `try_reserve` succeeds, - /// // to avoid losing data on allocation error. - /// let read = src_buf.len(); - /// self.example_datasource.consume(read); - /// } - /// Ok(dest_vec.len() - initial_vec_len) - /// } - /// # } - /// ``` - /// - /// [`Vec::try_reserve`]: crate::vec::Vec::try_reserve - #[stable(feature = "rust1", since = "1.0.0")] - fn read_to_end(&mut self, buf: &mut Vec) -> Result { - default_read_to_end(self, buf, None) - } - - /// Read all bytes until EOF in this source, appending them to `buf`. - /// - /// If successful, this function returns the number of bytes which were read - /// and appended to `buf`. - /// - /// # Errors - /// - /// If the data in this stream is *not* valid UTF-8 then an error is - /// returned and `buf` is unchanged. - /// - /// See [`read_to_end`] for other error semantics. - /// - /// [`read_to_end`]: Read::read_to_end - /// - /// # Examples - /// - /// [`File`]s implement `Read`: - /// - /// [`File`]: crate::fs::File - /// - /// ```no_run - /// use std::io; - /// use std::io::prelude::*; - /// use std::fs::File; - /// - /// fn main() -> io::Result<()> { - /// let mut f = File::open("foo.txt")?; - /// let mut buffer = String::new(); - /// - /// f.read_to_string(&mut buffer)?; - /// Ok(()) - /// } - /// ``` - /// - /// (See also the [`std::fs::read_to_string`] convenience function for - /// reading from a file.) - /// - /// [`std::fs::read_to_string`]: crate::fs::read_to_string - #[stable(feature = "rust1", since = "1.0.0")] - fn read_to_string(&mut self, buf: &mut String) -> Result { - default_read_to_string(self, buf, None) - } - - /// Read the exact number of bytes required to fill `buf`. - /// - /// This function reads as many bytes as necessary to completely fill the - /// specified buffer `buf`. - /// - /// *Implementations* of this method can make no assumptions about the contents of `buf` when - /// this function is called. It is recommended that implementations only write data to `buf` - /// instead of reading its contents. The documentation on [`read`] has a more detailed - /// explanation of this subject. - /// - /// # Errors - /// - /// If this function encounters an error of the kind - /// [`ErrorKind::Interrupted`] then the error is ignored and the operation - /// will continue. - /// - /// If this function encounters an "end of file" before completely filling - /// the buffer, it returns an error of the kind [`ErrorKind::UnexpectedEof`]. - /// The contents of `buf` are unspecified in this case. - /// - /// If any other read error is encountered then this function immediately - /// returns. The contents of `buf` are unspecified in this case. - /// - /// If this function returns an error, it is unspecified how many bytes it - /// has read, but it will never read more than would be necessary to - /// completely fill the buffer. - /// - /// # Examples - /// - /// [`File`]s implement `Read`: - /// - /// [`read`]: Read::read - /// [`File`]: crate::fs::File - /// - /// ```no_run - /// use std::io; - /// use std::io::prelude::*; - /// use std::fs::File; - /// - /// fn main() -> io::Result<()> { - /// let mut f = File::open("foo.txt")?; - /// let mut buffer = [0; 10]; - /// - /// // read exactly 10 bytes - /// f.read_exact(&mut buffer)?; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "read_exact", since = "1.6.0")] - fn read_exact(&mut self, buf: &mut [u8]) -> Result<()> { - default_read_exact(self, buf) - } - - /// Pull some bytes from this source into the specified buffer. - /// - /// This is equivalent to the [`read`](Read::read) method, except that it is passed a [`BorrowedCursor`] rather than `[u8]` to allow use - /// with uninitialized buffers. The new data will be appended to any existing contents of `buf`. - /// - /// The default implementation delegates to `read`. - #[unstable(feature = "read_buf", issue = "78485")] - fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<()> { - default_read_buf(|b| self.read(b), buf) - } - - /// Read the exact number of bytes required to fill `cursor`. - /// - /// This is similar to the [`read_exact`](Read::read_exact) method, except - /// that it is passed a [`BorrowedCursor`] rather than `[u8]` to allow use - /// with uninitialized buffers. - /// - /// # Errors - /// - /// If this function encounters an error of the kind [`ErrorKind::Interrupted`] - /// then the error is ignored and the operation will continue. - /// - /// If this function encounters an "end of file" before completely filling - /// the buffer, it returns an error of the kind [`ErrorKind::UnexpectedEof`]. - /// - /// If any other read error is encountered then this function immediately - /// returns. - /// - /// If this function returns an error, all bytes read will be appended to `cursor`. - #[unstable(feature = "read_buf", issue = "78485")] - fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<()> { - default_read_buf_exact(self, cursor) - } - - /// Creates a "by reference" adaptor for this instance of `Read`. - /// - /// The returned adapter also implements `Read` and will simply borrow this - /// current reader. - /// - /// # Examples - /// - /// [`File`]s implement `Read`: - /// - /// [`File`]: crate::fs::File - /// - /// ```no_run - /// use std::io; - /// use std::io::Read; - /// use std::fs::File; - /// - /// fn main() -> io::Result<()> { - /// let mut f = File::open("foo.txt")?; - /// let mut buffer = Vec::new(); - /// let mut other_buffer = Vec::new(); - /// - /// { - /// let reference = f.by_ref(); - /// - /// // read at most 5 bytes - /// reference.take(5).read_to_end(&mut buffer)?; - /// - /// } // drop our &mut reference so we can use f again - /// - /// // original file still usable, read the rest - /// f.read_to_end(&mut other_buffer)?; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn by_ref(&mut self) -> &mut Self - where - Self: Sized, - { - self - } - - /// Transforms this `Read` instance to an [`Iterator`] over its bytes. - /// - /// The returned type implements [`Iterator`] where the [`Item`] is - /// [Result]<[u8], [io::Error]>. - /// The yielded item is [`Ok`] if a byte was successfully read and [`Err`] - /// otherwise. EOF is mapped to returning [`None`] from this iterator. - /// - /// The default implementation calls `read` for each byte, - /// which can be very inefficient for data that's not in memory, - /// such as [`File`]. Consider using a [`BufReader`] in such cases. - /// - /// # Examples - /// - /// [`File`]s implement `Read`: - /// - /// [`Item`]: Iterator::Item - /// [`File`]: crate::fs::File "fs::File" - /// [Result]: crate::result::Result "Result" - /// [io::Error]: self::Error "io::Error" - /// - /// ```no_run - /// use std::io; - /// use std::io::prelude::*; - /// use std::io::BufReader; - /// use std::fs::File; - /// - /// fn main() -> io::Result<()> { - /// let f = BufReader::new(File::open("foo.txt")?); - /// - /// for byte in f.bytes() { - /// println!("{}", byte.unwrap()); - /// } - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn bytes(self) -> Bytes - where - Self: Sized, - { - Bytes { inner: self } - } - - /// Creates an adapter which will chain this stream with another. - /// - /// The returned `Read` instance will first read all bytes from this object - /// until EOF is encountered. Afterwards the output is equivalent to the - /// output of `next`. - /// - /// # Examples - /// - /// [`File`]s implement `Read`: - /// - /// [`File`]: crate::fs::File - /// - /// ```no_run - /// use std::io; - /// use std::io::prelude::*; - /// use std::fs::File; - /// - /// fn main() -> io::Result<()> { - /// let f1 = File::open("foo.txt")?; - /// let f2 = File::open("bar.txt")?; - /// - /// let mut handle = f1.chain(f2); - /// let mut buffer = String::new(); - /// - /// // read the value into a String. We could use any Read method here, - /// // this is just one example. - /// handle.read_to_string(&mut buffer)?; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn chain(self, next: R) -> Chain - where - Self: Sized, - { - Chain { first: self, second: next, done_first: false } - } - - /// Creates an adapter which will read at most `limit` bytes from it. - /// - /// This function returns a new instance of `Read` which will read at most - /// `limit` bytes, after which it will always return EOF ([`Ok(0)`]). Any - /// read errors will not count towards the number of bytes read and future - /// calls to [`read()`] may succeed. - /// - /// # Examples - /// - /// [`File`]s implement `Read`: - /// - /// [`File`]: crate::fs::File - /// [`Ok(0)`]: Ok - /// [`read()`]: Read::read - /// - /// ```no_run - /// use std::io; - /// use std::io::prelude::*; - /// use std::fs::File; - /// - /// fn main() -> io::Result<()> { - /// let f = File::open("foo.txt")?; - /// let mut buffer = [0; 5]; - /// - /// // read at most five bytes - /// let mut handle = f.take(5); - /// - /// handle.read(&mut buffer)?; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn take(self, limit: u64) -> Take - where - Self: Sized, - { - Take { inner: self, limit } - } -} - -/// Read all bytes from a [reader][Read] into a new [`String`]. -/// -/// This is a convenience function for [`Read::read_to_string`]. Using this -/// function avoids having to create a variable first and provides more type -/// safety since you can only get the buffer out if there were no errors. (If you -/// use [`Read::read_to_string`] you have to remember to check whether the read -/// succeeded because otherwise your buffer will be empty or only partially full.) -/// -/// # Performance -/// -/// The downside of this function's increased ease of use and type safety is -/// that it gives you less control over performance. For example, you can't -/// pre-allocate memory like you can using [`String::with_capacity`] and -/// [`Read::read_to_string`]. Also, you can't re-use the buffer if an error -/// occurs while reading. -/// -/// In many cases, this function's performance will be adequate and the ease of use -/// and type safety tradeoffs will be worth it. However, there are cases where you -/// need more control over performance, and in those cases you should definitely use -/// [`Read::read_to_string`] directly. -/// -/// Note that in some special cases, such as when reading files, this function will -/// pre-allocate memory based on the size of the input it is reading. In those -/// cases, the performance should be as good as if you had used -/// [`Read::read_to_string`] with a manually pre-allocated buffer. -/// -/// # Errors -/// -/// This function forces you to handle errors because the output (the `String`) -/// is wrapped in a [`Result`]. See [`Read::read_to_string`] for the errors -/// that can occur. If any error occurs, you will get an [`Err`], so you -/// don't have to worry about your buffer being empty or partially full. -/// -/// # Examples -/// -/// ```no_run -/// # use std::io; -/// fn main() -> io::Result<()> { -/// let stdin = io::read_to_string(io::stdin())?; -/// println!("Stdin was:"); -/// println!("{stdin}"); -/// Ok(()) -/// } -/// ``` -#[stable(feature = "io_read_to_string", since = "1.65.0")] -pub fn read_to_string(mut reader: R) -> Result { - let mut buf = String::new(); - reader.read_to_string(&mut buf)?; - Ok(buf) -} - -/// A buffer type used with `Read::read_vectored`. -/// -/// It is semantically a wrapper around an `&mut [u8]`, but is guaranteed to be -/// ABI compatible with the `iovec` type on Unix platforms and `WSABUF` on -/// Windows. -#[stable(feature = "iovec", since = "1.36.0")] -#[repr(transparent)] -pub struct IoSliceMut<'a>(sys::io::IoSliceMut<'a>); - -#[stable(feature = "iovec_send_sync", since = "1.44.0")] -unsafe impl<'a> Send for IoSliceMut<'a> {} - -#[stable(feature = "iovec_send_sync", since = "1.44.0")] -unsafe impl<'a> Sync for IoSliceMut<'a> {} - -#[stable(feature = "iovec", since = "1.36.0")] -impl<'a> fmt::Debug for IoSliceMut<'a> { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(self.0.as_slice(), fmt) - } -} - -impl<'a> IoSliceMut<'a> { - /// Creates a new `IoSliceMut` wrapping a byte slice. - /// - /// # Panics - /// - /// Panics on Windows if the slice is larger than 4GB. - #[stable(feature = "iovec", since = "1.36.0")] - #[inline] - pub fn new(buf: &'a mut [u8]) -> IoSliceMut<'a> { - IoSliceMut(sys::io::IoSliceMut::new(buf)) - } - - /// Advance the internal cursor of the slice. - /// - /// Also see [`IoSliceMut::advance_slices`] to advance the cursors of - /// multiple buffers. - /// - /// # Panics - /// - /// Panics when trying to advance beyond the end of the slice. - /// - /// # Examples - /// - /// ``` - /// #![feature(io_slice_advance)] - /// - /// use std::io::IoSliceMut; - /// use std::ops::Deref; - /// - /// let mut data = [1; 8]; - /// let mut buf = IoSliceMut::new(&mut data); - /// - /// // Mark 3 bytes as read. - /// buf.advance(3); - /// assert_eq!(buf.deref(), [1; 5].as_ref()); - /// ``` - #[unstable(feature = "io_slice_advance", issue = "62726")] - #[inline] - pub fn advance(&mut self, n: usize) { - self.0.advance(n) - } - - /// Advance a slice of slices. - /// - /// Shrinks the slice to remove any `IoSliceMut`s that are fully advanced over. - /// If the cursor ends up in the middle of an `IoSliceMut`, it is modified - /// to start at that cursor. - /// - /// For example, if we have a slice of two 8-byte `IoSliceMut`s, and we advance by 10 bytes, - /// the result will only include the second `IoSliceMut`, advanced by 2 bytes. - /// - /// # Panics - /// - /// Panics when trying to advance beyond the end of the slices. - /// - /// # Examples - /// - /// ``` - /// #![feature(io_slice_advance)] - /// - /// use std::io::IoSliceMut; - /// use std::ops::Deref; - /// - /// let mut buf1 = [1; 8]; - /// let mut buf2 = [2; 16]; - /// let mut buf3 = [3; 8]; - /// let mut bufs = &mut [ - /// IoSliceMut::new(&mut buf1), - /// IoSliceMut::new(&mut buf2), - /// IoSliceMut::new(&mut buf3), - /// ][..]; - /// - /// // Mark 10 bytes as read. - /// IoSliceMut::advance_slices(&mut bufs, 10); - /// assert_eq!(bufs[0].deref(), [2; 14].as_ref()); - /// assert_eq!(bufs[1].deref(), [3; 8].as_ref()); - /// ``` - #[unstable(feature = "io_slice_advance", issue = "62726")] - #[inline] - pub fn advance_slices(bufs: &mut &mut [IoSliceMut<'a>], n: usize) { - // Number of buffers to remove. - let mut remove = 0; - // Remaining length before reaching n. - let mut left = n; - for buf in bufs.iter() { - if let Some(remainder) = left.checked_sub(buf.len()) { - left = remainder; - remove += 1; - } else { - break; - } - } - - *bufs = &mut take(bufs)[remove..]; - if bufs.is_empty() { - assert!(left == 0, "advancing io slices beyond their length"); - } else { - bufs[0].advance(left); - } - } -} - -#[stable(feature = "iovec", since = "1.36.0")] -impl<'a> Deref for IoSliceMut<'a> { - type Target = [u8]; - - #[inline] - fn deref(&self) -> &[u8] { - self.0.as_slice() - } -} - -#[stable(feature = "iovec", since = "1.36.0")] -impl<'a> DerefMut for IoSliceMut<'a> { - #[inline] - fn deref_mut(&mut self) -> &mut [u8] { - self.0.as_mut_slice() - } -} - -/// A buffer type used with `Write::write_vectored`. -/// -/// It is semantically a wrapper around a `&[u8]`, but is guaranteed to be -/// ABI compatible with the `iovec` type on Unix platforms and `WSABUF` on -/// Windows. -#[stable(feature = "iovec", since = "1.36.0")] -#[derive(Copy, Clone)] -#[repr(transparent)] -pub struct IoSlice<'a>(sys::io::IoSlice<'a>); - -#[stable(feature = "iovec_send_sync", since = "1.44.0")] -unsafe impl<'a> Send for IoSlice<'a> {} - -#[stable(feature = "iovec_send_sync", since = "1.44.0")] -unsafe impl<'a> Sync for IoSlice<'a> {} - -#[stable(feature = "iovec", since = "1.36.0")] -impl<'a> fmt::Debug for IoSlice<'a> { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(self.0.as_slice(), fmt) - } -} - -impl<'a> IoSlice<'a> { - /// Creates a new `IoSlice` wrapping a byte slice. - /// - /// # Panics - /// - /// Panics on Windows if the slice is larger than 4GB. - #[stable(feature = "iovec", since = "1.36.0")] - #[must_use] - #[inline] - pub fn new(buf: &'a [u8]) -> IoSlice<'a> { - IoSlice(sys::io::IoSlice::new(buf)) - } - - /// Advance the internal cursor of the slice. - /// - /// Also see [`IoSlice::advance_slices`] to advance the cursors of multiple - /// buffers. - /// - /// # Panics - /// - /// Panics when trying to advance beyond the end of the slice. - /// - /// # Examples - /// - /// ``` - /// #![feature(io_slice_advance)] - /// - /// use std::io::IoSlice; - /// use std::ops::Deref; - /// - /// let data = [1; 8]; - /// let mut buf = IoSlice::new(&data); - /// - /// // Mark 3 bytes as read. - /// buf.advance(3); - /// assert_eq!(buf.deref(), [1; 5].as_ref()); - /// ``` - #[unstable(feature = "io_slice_advance", issue = "62726")] - #[inline] - pub fn advance(&mut self, n: usize) { - self.0.advance(n) - } - - /// Advance a slice of slices. - /// - /// Shrinks the slice to remove any `IoSlice`s that are fully advanced over. - /// If the cursor ends up in the middle of an `IoSlice`, it is modified - /// to start at that cursor. - /// - /// For example, if we have a slice of two 8-byte `IoSlice`s, and we advance by 10 bytes, - /// the result will only include the second `IoSlice`, advanced by 2 bytes. - /// - /// # Panics - /// - /// Panics when trying to advance beyond the end of the slices. - /// - /// # Examples - /// - /// ``` - /// #![feature(io_slice_advance)] - /// - /// use std::io::IoSlice; - /// use std::ops::Deref; - /// - /// let buf1 = [1; 8]; - /// let buf2 = [2; 16]; - /// let buf3 = [3; 8]; - /// let mut bufs = &mut [ - /// IoSlice::new(&buf1), - /// IoSlice::new(&buf2), - /// IoSlice::new(&buf3), - /// ][..]; - /// - /// // Mark 10 bytes as written. - /// IoSlice::advance_slices(&mut bufs, 10); - /// assert_eq!(bufs[0].deref(), [2; 14].as_ref()); - /// assert_eq!(bufs[1].deref(), [3; 8].as_ref()); - #[unstable(feature = "io_slice_advance", issue = "62726")] - #[inline] - pub fn advance_slices(bufs: &mut &mut [IoSlice<'a>], n: usize) { - // Number of buffers to remove. - let mut remove = 0; - // Remaining length before reaching n. This prevents overflow - // that could happen if the length of slices in `bufs` were instead - // accumulated. Those slice may be aliased and, if they are large - // enough, their added length may overflow a `usize`. - let mut left = n; - for buf in bufs.iter() { - if let Some(remainder) = left.checked_sub(buf.len()) { - left = remainder; - remove += 1; - } else { - break; - } - } - - *bufs = &mut take(bufs)[remove..]; - if bufs.is_empty() { - assert!(left == 0, "advancing io slices beyond their length"); - } else { - bufs[0].advance(left); - } - } -} - -#[stable(feature = "iovec", since = "1.36.0")] -impl<'a> Deref for IoSlice<'a> { - type Target = [u8]; - - #[inline] - fn deref(&self) -> &[u8] { - self.0.as_slice() - } -} - -/// A trait for objects which are byte-oriented sinks. -/// -/// Implementors of the `Write` trait are sometimes called 'writers'. -/// -/// Writers are defined by two required methods, [`write`] and [`flush`]: -/// -/// * The [`write`] method will attempt to write some data into the object, -/// returning how many bytes were successfully written. -/// -/// * The [`flush`] method is useful for adapters and explicit buffers -/// themselves for ensuring that all buffered data has been pushed out to the -/// 'true sink'. -/// -/// Writers are intended to be composable with one another. Many implementors -/// throughout [`std::io`] take and provide types which implement the `Write` -/// trait. -/// -/// [`write`]: Write::write -/// [`flush`]: Write::flush -/// [`std::io`]: self -/// -/// # Examples -/// -/// ```no_run -/// use std::io::prelude::*; -/// use std::fs::File; -/// -/// fn main() -> std::io::Result<()> { -/// let data = b"some bytes"; -/// -/// let mut pos = 0; -/// let mut buffer = File::create("foo.txt")?; -/// -/// while pos < data.len() { -/// let bytes_written = buffer.write(&data[pos..])?; -/// pos += bytes_written; -/// } -/// Ok(()) -/// } -/// ``` -/// -/// The trait also provides convenience methods like [`write_all`], which calls -/// `write` in a loop until its entire input has been written. -/// -/// [`write_all`]: Write::write_all -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(notable_trait)] -#[cfg_attr(not(test), rustc_diagnostic_item = "IoWrite")] -pub trait Write { - /// Write a buffer into this writer, returning how many bytes were written. - /// - /// This function will attempt to write the entire contents of `buf`, but - /// the entire write might not succeed, or the write may also generate an - /// error. Typically, a call to `write` represents one attempt to write to - /// any wrapped object. - /// - /// Calls to `write` are not guaranteed to block waiting for data to be - /// written, and a write which would otherwise block can be indicated through - /// an [`Err`] variant. - /// - /// If this method consumed `n > 0` bytes of `buf` it must return [`Ok(n)`]. - /// If the return value is `Ok(n)` then `n` must satisfy `n <= buf.len()`. - /// A return value of `Ok(0)` typically means that the underlying object is - /// no longer able to accept bytes and will likely not be able to in the - /// future as well, or that the buffer provided is empty. - /// - /// # Errors - /// - /// Each call to `write` may generate an I/O error indicating that the - /// operation could not be completed. If an error is returned then no bytes - /// in the buffer were written to this writer. - /// - /// It is **not** considered an error if the entire buffer could not be - /// written to this writer. - /// - /// An error of the [`ErrorKind::Interrupted`] kind is non-fatal and the - /// write operation should be retried if there is nothing else to do. - /// - /// # Examples - /// - /// ```no_run - /// use std::io::prelude::*; - /// use std::fs::File; - /// - /// fn main() -> std::io::Result<()> { - /// let mut buffer = File::create("foo.txt")?; - /// - /// // Writes some prefix of the byte string, not necessarily all of it. - /// buffer.write(b"some bytes")?; - /// Ok(()) - /// } - /// ``` - /// - /// [`Ok(n)`]: Ok - #[stable(feature = "rust1", since = "1.0.0")] - fn write(&mut self, buf: &[u8]) -> Result; - - /// Like [`write`], except that it writes from a slice of buffers. - /// - /// Data is copied from each buffer in order, with the final buffer - /// read from possibly being only partially consumed. This method must - /// behave as a call to [`write`] with the buffers concatenated would. - /// - /// The default implementation calls [`write`] with either the first nonempty - /// buffer provided, or an empty one if none exists. - /// - /// # Examples - /// - /// ```no_run - /// use std::io::IoSlice; - /// use std::io::prelude::*; - /// use std::fs::File; - /// - /// fn main() -> std::io::Result<()> { - /// let data1 = [1; 8]; - /// let data2 = [15; 8]; - /// let io_slice1 = IoSlice::new(&data1); - /// let io_slice2 = IoSlice::new(&data2); - /// - /// let mut buffer = File::create("foo.txt")?; - /// - /// // Writes some prefix of the byte string, not necessarily all of it. - /// buffer.write_vectored(&[io_slice1, io_slice2])?; - /// Ok(()) - /// } - /// ``` - /// - /// [`write`]: Write::write - #[stable(feature = "iovec", since = "1.36.0")] - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result { - default_write_vectored(|b| self.write(b), bufs) - } - - /// Determines if this `Write`r has an efficient [`write_vectored`] - /// implementation. - /// - /// If a `Write`r does not override the default [`write_vectored`] - /// implementation, code using it may want to avoid the method all together - /// and coalesce writes into a single buffer for higher performance. - /// - /// The default implementation returns `false`. - /// - /// [`write_vectored`]: Write::write_vectored - #[unstable(feature = "can_vector", issue = "69941")] - fn is_write_vectored(&self) -> bool { - false - } - - /// Flush this output stream, ensuring that all intermediately buffered - /// contents reach their destination. - /// - /// # Errors - /// - /// It is considered an error if not all bytes could be written due to - /// I/O errors or EOF being reached. - /// - /// # Examples - /// - /// ```no_run - /// use std::io::prelude::*; - /// use std::io::BufWriter; - /// use std::fs::File; - /// - /// fn main() -> std::io::Result<()> { - /// let mut buffer = BufWriter::new(File::create("foo.txt")?); - /// - /// buffer.write_all(b"some bytes")?; - /// buffer.flush()?; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn flush(&mut self) -> Result<()>; - - /// Attempts to write an entire buffer into this writer. - /// - /// This method will continuously call [`write`] until there is no more data - /// to be written or an error of non-[`ErrorKind::Interrupted`] kind is - /// returned. This method will not return until the entire buffer has been - /// successfully written or such an error occurs. The first error that is - /// not of [`ErrorKind::Interrupted`] kind generated from this method will be - /// returned. - /// - /// If the buffer contains no data, this will never call [`write`]. - /// - /// # Errors - /// - /// This function will return the first error of - /// non-[`ErrorKind::Interrupted`] kind that [`write`] returns. - /// - /// [`write`]: Write::write - /// - /// # Examples - /// - /// ```no_run - /// use std::io::prelude::*; - /// use std::fs::File; - /// - /// fn main() -> std::io::Result<()> { - /// let mut buffer = File::create("foo.txt")?; - /// - /// buffer.write_all(b"some bytes")?; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn write_all(&mut self, mut buf: &[u8]) -> Result<()> { - while !buf.is_empty() { - match self.write(buf) { - Ok(0) => { - return Err(Error::WRITE_ALL_EOF); - } - Ok(n) => buf = &buf[n..], - Err(ref e) if e.is_interrupted() => {} - Err(e) => return Err(e), - } - } - Ok(()) - } - - /// Attempts to write multiple buffers into this writer. - /// - /// This method will continuously call [`write_vectored`] until there is no - /// more data to be written or an error of non-[`ErrorKind::Interrupted`] - /// kind is returned. This method will not return until all buffers have - /// been successfully written or such an error occurs. The first error that - /// is not of [`ErrorKind::Interrupted`] kind generated from this method - /// will be returned. - /// - /// If the buffer contains no data, this will never call [`write_vectored`]. - /// - /// # Notes - /// - /// Unlike [`write_vectored`], this takes a *mutable* reference to - /// a slice of [`IoSlice`]s, not an immutable one. That's because we need to - /// modify the slice to keep track of the bytes already written. - /// - /// Once this function returns, the contents of `bufs` are unspecified, as - /// this depends on how many calls to [`write_vectored`] were necessary. It is - /// best to understand this function as taking ownership of `bufs` and to - /// not use `bufs` afterwards. The underlying buffers, to which the - /// [`IoSlice`]s point (but not the [`IoSlice`]s themselves), are unchanged and - /// can be reused. - /// - /// [`write_vectored`]: Write::write_vectored - /// - /// # Examples - /// - /// ``` - /// #![feature(write_all_vectored)] - /// # fn main() -> std::io::Result<()> { - /// - /// use std::io::{Write, IoSlice}; - /// - /// let mut writer = Vec::new(); - /// let bufs = &mut [ - /// IoSlice::new(&[1]), - /// IoSlice::new(&[2, 3]), - /// IoSlice::new(&[4, 5, 6]), - /// ]; - /// - /// writer.write_all_vectored(bufs)?; - /// // Note: the contents of `bufs` is now undefined, see the Notes section. - /// - /// assert_eq!(writer, &[1, 2, 3, 4, 5, 6]); - /// # Ok(()) } - /// ``` - #[unstable(feature = "write_all_vectored", issue = "70436")] - fn write_all_vectored(&mut self, mut bufs: &mut [IoSlice<'_>]) -> Result<()> { - // Guarantee that bufs is empty if it contains no data, - // to avoid calling write_vectored if there is no data to be written. - IoSlice::advance_slices(&mut bufs, 0); - while !bufs.is_empty() { - match self.write_vectored(bufs) { - Ok(0) => { - return Err(Error::WRITE_ALL_EOF); - } - Ok(n) => IoSlice::advance_slices(&mut bufs, n), - Err(ref e) if e.is_interrupted() => {} - Err(e) => return Err(e), - } - } - Ok(()) - } - - /// Writes a formatted string into this writer, returning any error - /// encountered. - /// - /// This method is primarily used to interface with the - /// [`format_args!()`] macro, and it is rare that this should - /// explicitly be called. The [`write!()`] macro should be favored to - /// invoke this method instead. - /// - /// This function internally uses the [`write_all`] method on - /// this trait and hence will continuously write data so long as no errors - /// are received. This also means that partial writes are not indicated in - /// this signature. - /// - /// [`write_all`]: Write::write_all - /// - /// # Errors - /// - /// This function will return any I/O error reported while formatting. - /// - /// # Examples - /// - /// ```no_run - /// use std::io::prelude::*; - /// use std::fs::File; - /// - /// fn main() -> std::io::Result<()> { - /// let mut buffer = File::create("foo.txt")?; - /// - /// // this call - /// write!(buffer, "{:.*}", 2, 1.234567)?; - /// // turns into this: - /// buffer.write_fmt(format_args!("{:.*}", 2, 1.234567))?; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn write_fmt(&mut self, fmt: fmt::Arguments<'_>) -> Result<()> { - // Create a shim which translates a Write to a fmt::Write and saves - // off I/O errors. instead of discarding them - struct Adapter<'a, T: ?Sized + 'a> { - inner: &'a mut T, - error: Result<()>, - } - - impl fmt::Write for Adapter<'_, T> { - fn write_str(&mut self, s: &str) -> fmt::Result { - match self.inner.write_all(s.as_bytes()) { - Ok(()) => Ok(()), - Err(e) => { - self.error = Err(e); - Err(fmt::Error) - } - } - } - } - - let mut output = Adapter { inner: self, error: Ok(()) }; - match fmt::write(&mut output, fmt) { - Ok(()) => Ok(()), - Err(..) => { - // check if the error came from the underlying `Write` or not - if output.error.is_err() { - output.error - } else { - // This shouldn't happen: the underlying stream did not error, but somehow - // the formatter still errored? - panic!( - "a formatting trait implementation returned an error when the underlying stream did not" - ); - } - } - } - } - - /// Creates a "by reference" adapter for this instance of `Write`. - /// - /// The returned adapter also implements `Write` and will simply borrow this - /// current writer. - /// - /// # Examples - /// - /// ```no_run - /// use std::io::Write; - /// use std::fs::File; - /// - /// fn main() -> std::io::Result<()> { - /// let mut buffer = File::create("foo.txt")?; - /// - /// let reference = buffer.by_ref(); - /// - /// // we can use reference just like our original buffer - /// reference.write_all(b"some bytes")?; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn by_ref(&mut self) -> &mut Self - where - Self: Sized, - { - self - } -} - -/// The `Seek` trait provides a cursor which can be moved within a stream of -/// bytes. -/// -/// The stream typically has a fixed size, allowing seeking relative to either -/// end or the current offset. -/// -/// # Examples -/// -/// [`File`]s implement `Seek`: -/// -/// [`File`]: crate::fs::File -/// -/// ```no_run -/// use std::io; -/// use std::io::prelude::*; -/// use std::fs::File; -/// use std::io::SeekFrom; -/// -/// fn main() -> io::Result<()> { -/// let mut f = File::open("foo.txt")?; -/// -/// // move the cursor 42 bytes from the start of the file -/// f.seek(SeekFrom::Start(42))?; -/// Ok(()) -/// } -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "IoSeek")] -pub trait Seek { - /// Seek to an offset, in bytes, in a stream. - /// - /// A seek beyond the end of a stream is allowed, but behavior is defined - /// by the implementation. - /// - /// If the seek operation completed successfully, - /// this method returns the new position from the start of the stream. - /// That position can be used later with [`SeekFrom::Start`]. - /// - /// # Errors - /// - /// Seeking can fail, for example because it might involve flushing a buffer. - /// - /// Seeking to a negative offset is considered an error. - #[stable(feature = "rust1", since = "1.0.0")] - fn seek(&mut self, pos: SeekFrom) -> Result; - - /// Rewind to the beginning of a stream. - /// - /// This is a convenience method, equivalent to `seek(SeekFrom::Start(0))`. - /// - /// # Errors - /// - /// Rewinding can fail, for example because it might involve flushing a buffer. - /// - /// # Example - /// - /// ```no_run - /// use std::io::{Read, Seek, Write}; - /// use std::fs::OpenOptions; - /// - /// let mut f = OpenOptions::new() - /// .write(true) - /// .read(true) - /// .create(true) - /// .open("foo.txt").unwrap(); - /// - /// let hello = "Hello!\n"; - /// write!(f, "{hello}").unwrap(); - /// f.rewind().unwrap(); - /// - /// let mut buf = String::new(); - /// f.read_to_string(&mut buf).unwrap(); - /// assert_eq!(&buf, hello); - /// ``` - #[stable(feature = "seek_rewind", since = "1.55.0")] - fn rewind(&mut self) -> Result<()> { - self.seek(SeekFrom::Start(0))?; - Ok(()) - } - - /// Returns the length of this stream (in bytes). - /// - /// This method is implemented using up to three seek operations. If this - /// method returns successfully, the seek position is unchanged (i.e. the - /// position before calling this method is the same as afterwards). - /// However, if this method returns an error, the seek position is - /// unspecified. - /// - /// If you need to obtain the length of *many* streams and you don't care - /// about the seek position afterwards, you can reduce the number of seek - /// operations by simply calling `seek(SeekFrom::End(0))` and using its - /// return value (it is also the stream length). - /// - /// Note that length of a stream can change over time (for example, when - /// data is appended to a file). So calling this method multiple times does - /// not necessarily return the same length each time. - /// - /// # Example - /// - /// ```no_run - /// #![feature(seek_stream_len)] - /// use std::{ - /// io::{self, Seek}, - /// fs::File, - /// }; - /// - /// fn main() -> io::Result<()> { - /// let mut f = File::open("foo.txt")?; - /// - /// let len = f.stream_len()?; - /// println!("The file is currently {len} bytes long"); - /// Ok(()) - /// } - /// ``` - #[unstable(feature = "seek_stream_len", issue = "59359")] - fn stream_len(&mut self) -> Result { - let old_pos = self.stream_position()?; - let len = self.seek(SeekFrom::End(0))?; - - // Avoid seeking a third time when we were already at the end of the - // stream. The branch is usually way cheaper than a seek operation. - if old_pos != len { - self.seek(SeekFrom::Start(old_pos))?; - } - - Ok(len) - } - - /// Returns the current seek position from the start of the stream. - /// - /// This is equivalent to `self.seek(SeekFrom::Current(0))`. - /// - /// # Example - /// - /// ```no_run - /// use std::{ - /// io::{self, BufRead, BufReader, Seek}, - /// fs::File, - /// }; - /// - /// fn main() -> io::Result<()> { - /// let mut f = BufReader::new(File::open("foo.txt")?); - /// - /// let before = f.stream_position()?; - /// f.read_line(&mut String::new())?; - /// let after = f.stream_position()?; - /// - /// println!("The first line was {} bytes long", after - before); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "seek_convenience", since = "1.51.0")] - fn stream_position(&mut self) -> Result { - self.seek(SeekFrom::Current(0)) - } - - /// Seeks relative to the current position. - /// - /// This is equivalent to `self.seek(SeekFrom::Current(offset))` but - /// doesn't return the new position which can allow some implementations - /// such as [`BufReader`] to perform more efficient seeks. - /// - /// # Example - /// - /// ```no_run - /// use std::{ - /// io::{self, Seek}, - /// fs::File, - /// }; - /// - /// fn main() -> io::Result<()> { - /// let mut f = File::open("foo.txt")?; - /// f.seek_relative(10)?; - /// assert_eq!(f.stream_position()?, 10); - /// Ok(()) - /// } - /// ``` - /// - /// [`BufReader`]: crate::io::BufReader - #[stable(feature = "seek_seek_relative", since = "CURRENT_RUSTC_VERSION")] - fn seek_relative(&mut self, offset: i64) -> Result<()> { - self.seek(SeekFrom::Current(offset))?; - Ok(()) - } -} - -/// Enumeration of possible methods to seek within an I/O object. -/// -/// It is used by the [`Seek`] trait. -#[derive(Copy, PartialEq, Eq, Clone, Debug)] -#[stable(feature = "rust1", since = "1.0.0")] -pub enum SeekFrom { - /// Sets the offset to the provided number of bytes. - #[stable(feature = "rust1", since = "1.0.0")] - Start(#[stable(feature = "rust1", since = "1.0.0")] u64), - - /// Sets the offset to the size of this object plus the specified number of - /// bytes. - /// - /// It is possible to seek beyond the end of an object, but it's an error to - /// seek before byte 0. - #[stable(feature = "rust1", since = "1.0.0")] - End(#[stable(feature = "rust1", since = "1.0.0")] i64), - - /// Sets the offset to the current position plus the specified number of - /// bytes. - /// - /// It is possible to seek beyond the end of an object, but it's an error to - /// seek before byte 0. - #[stable(feature = "rust1", since = "1.0.0")] - Current(#[stable(feature = "rust1", since = "1.0.0")] i64), -} - -fn read_until(r: &mut R, delim: u8, buf: &mut Vec) -> Result { - let mut read = 0; - loop { - let (done, used) = { - let available = match r.fill_buf() { - Ok(n) => n, - Err(ref e) if e.is_interrupted() => continue, - Err(e) => return Err(e), - }; - match memchr::memchr(delim, available) { - Some(i) => { - buf.extend_from_slice(&available[..=i]); - (true, i + 1) - } - None => { - buf.extend_from_slice(available); - (false, available.len()) - } - } - }; - r.consume(used); - read += used; - if done || used == 0 { - return Ok(read); - } - } -} - -fn skip_until(r: &mut R, delim: u8) -> Result { - let mut read = 0; - loop { - let (done, used) = { - let available = match r.fill_buf() { - Ok(n) => n, - Err(ref e) if e.kind() == ErrorKind::Interrupted => continue, - Err(e) => return Err(e), - }; - match memchr::memchr(delim, available) { - Some(i) => (true, i + 1), - None => (false, available.len()), - } - }; - r.consume(used); - read += used; - if done || used == 0 { - return Ok(read); - } - } -} - -/// A `BufRead` is a type of `Read`er which has an internal buffer, allowing it -/// to perform extra ways of reading. -/// -/// For example, reading line-by-line is inefficient without using a buffer, so -/// if you want to read by line, you'll need `BufRead`, which includes a -/// [`read_line`] method as well as a [`lines`] iterator. -/// -/// # Examples -/// -/// A locked standard input implements `BufRead`: -/// -/// ```no_run -/// use std::io; -/// use std::io::prelude::*; -/// -/// let stdin = io::stdin(); -/// for line in stdin.lock().lines() { -/// println!("{}", line.unwrap()); -/// } -/// ``` -/// -/// If you have something that implements [`Read`], you can use the [`BufReader` -/// type][`BufReader`] to turn it into a `BufRead`. -/// -/// For example, [`File`] implements [`Read`], but not `BufRead`. -/// [`BufReader`] to the rescue! -/// -/// [`File`]: crate::fs::File -/// [`read_line`]: BufRead::read_line -/// [`lines`]: BufRead::lines -/// -/// ```no_run -/// use std::io::{self, BufReader}; -/// use std::io::prelude::*; -/// use std::fs::File; -/// -/// fn main() -> io::Result<()> { -/// let f = File::open("foo.txt")?; -/// let f = BufReader::new(f); -/// -/// for line in f.lines() { -/// println!("{}", line.unwrap()); -/// } -/// -/// Ok(()) -/// } -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub trait BufRead: Read { - /// Returns the contents of the internal buffer, filling it with more data - /// from the inner reader if it is empty. - /// - /// This function is a lower-level call. It needs to be paired with the - /// [`consume`] method to function properly. When calling this - /// method, none of the contents will be "read" in the sense that later - /// calling `read` may return the same contents. As such, [`consume`] must - /// be called with the number of bytes that are consumed from this buffer to - /// ensure that the bytes are never returned twice. - /// - /// [`consume`]: BufRead::consume - /// - /// An empty buffer returned indicates that the stream has reached EOF. - /// - /// # Errors - /// - /// This function will return an I/O error if the underlying reader was - /// read, but returned an error. - /// - /// # Examples - /// - /// A locked standard input implements `BufRead`: - /// - /// ```no_run - /// use std::io; - /// use std::io::prelude::*; - /// - /// let stdin = io::stdin(); - /// let mut stdin = stdin.lock(); - /// - /// let buffer = stdin.fill_buf().unwrap(); - /// - /// // work with buffer - /// println!("{buffer:?}"); - /// - /// // ensure the bytes we worked with aren't returned again later - /// let length = buffer.len(); - /// stdin.consume(length); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn fill_buf(&mut self) -> Result<&[u8]>; - - /// Tells this buffer that `amt` bytes have been consumed from the buffer, - /// so they should no longer be returned in calls to `read`. - /// - /// This function is a lower-level call. It needs to be paired with the - /// [`fill_buf`] method to function properly. This function does - /// not perform any I/O, it simply informs this object that some amount of - /// its buffer, returned from [`fill_buf`], has been consumed and should - /// no longer be returned. As such, this function may do odd things if - /// [`fill_buf`] isn't called before calling it. - /// - /// The `amt` must be `<=` the number of bytes in the buffer returned by - /// [`fill_buf`]. - /// - /// # Examples - /// - /// Since `consume()` is meant to be used with [`fill_buf`], - /// that method's example includes an example of `consume()`. - /// - /// [`fill_buf`]: BufRead::fill_buf - #[stable(feature = "rust1", since = "1.0.0")] - fn consume(&mut self, amt: usize); - - /// Check if the underlying `Read` has any data left to be read. - /// - /// This function may fill the buffer to check for data, - /// so this functions returns `Result`, not `bool`. - /// - /// Default implementation calls `fill_buf` and checks that - /// returned slice is empty (which means that there is no data left, - /// since EOF is reached). - /// - /// Examples - /// - /// ``` - /// #![feature(buf_read_has_data_left)] - /// use std::io; - /// use std::io::prelude::*; - /// - /// let stdin = io::stdin(); - /// let mut stdin = stdin.lock(); - /// - /// while stdin.has_data_left().unwrap() { - /// let mut line = String::new(); - /// stdin.read_line(&mut line).unwrap(); - /// // work with line - /// println!("{line:?}"); - /// } - /// ``` - #[unstable(feature = "buf_read_has_data_left", reason = "recently added", issue = "86423")] - fn has_data_left(&mut self) -> Result { - self.fill_buf().map(|b| !b.is_empty()) - } - - /// Read all bytes into `buf` until the delimiter `byte` or EOF is reached. - /// - /// This function will read bytes from the underlying stream until the - /// delimiter or EOF is found. Once found, all bytes up to, and including, - /// the delimiter (if found) will be appended to `buf`. - /// - /// If successful, this function will return the total number of bytes read. - /// - /// This function is blocking and should be used carefully: it is possible for - /// an attacker to continuously send bytes without ever sending the delimiter - /// or EOF. - /// - /// # Errors - /// - /// This function will ignore all instances of [`ErrorKind::Interrupted`] and - /// will otherwise return any errors returned by [`fill_buf`]. - /// - /// If an I/O error is encountered then all bytes read so far will be - /// present in `buf` and its length will have been adjusted appropriately. - /// - /// [`fill_buf`]: BufRead::fill_buf - /// - /// # Examples - /// - /// [`std::io::Cursor`][`Cursor`] is a type that implements `BufRead`. In - /// this example, we use [`Cursor`] to read all the bytes in a byte slice - /// in hyphen delimited segments: - /// - /// ``` - /// use std::io::{self, BufRead}; - /// - /// let mut cursor = io::Cursor::new(b"lorem-ipsum"); - /// let mut buf = vec![]; - /// - /// // cursor is at 'l' - /// let num_bytes = cursor.read_until(b'-', &mut buf) - /// .expect("reading from cursor won't fail"); - /// assert_eq!(num_bytes, 6); - /// assert_eq!(buf, b"lorem-"); - /// buf.clear(); - /// - /// // cursor is at 'i' - /// let num_bytes = cursor.read_until(b'-', &mut buf) - /// .expect("reading from cursor won't fail"); - /// assert_eq!(num_bytes, 5); - /// assert_eq!(buf, b"ipsum"); - /// buf.clear(); - /// - /// // cursor is at EOF - /// let num_bytes = cursor.read_until(b'-', &mut buf) - /// .expect("reading from cursor won't fail"); - /// assert_eq!(num_bytes, 0); - /// assert_eq!(buf, b""); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn read_until(&mut self, byte: u8, buf: &mut Vec) -> Result { - read_until(self, byte, buf) - } - - /// Skip all bytes until the delimiter `byte` or EOF is reached. - /// - /// This function will read (and discard) bytes from the underlying stream until the - /// delimiter or EOF is found. - /// - /// If successful, this function will return the total number of bytes read, - /// including the delimiter byte. - /// - /// This is useful for efficiently skipping data such as NUL-terminated strings - /// in binary file formats without buffering. - /// - /// This function is blocking and should be used carefully: it is possible for - /// an attacker to continuously send bytes without ever sending the delimiter - /// or EOF. - /// - /// # Errors - /// - /// This function will ignore all instances of [`ErrorKind::Interrupted`] and - /// will otherwise return any errors returned by [`fill_buf`]. - /// - /// If an I/O error is encountered then all bytes read so far will be - /// present in `buf` and its length will have been adjusted appropriately. - /// - /// [`fill_buf`]: BufRead::fill_buf - /// - /// # Examples - /// - /// [`std::io::Cursor`][`Cursor`] is a type that implements `BufRead`. In - /// this example, we use [`Cursor`] to read some NUL-terminated information - /// about Ferris from a binary string, skipping the fun fact: - /// - /// ``` - /// #![feature(bufread_skip_until)] - /// - /// use std::io::{self, BufRead}; - /// - /// let mut cursor = io::Cursor::new(b"Ferris\0Likes long walks on the beach\0Crustacean\0"); - /// - /// // read name - /// let mut name = Vec::new(); - /// let num_bytes = cursor.read_until(b'\0', &mut name) - /// .expect("reading from cursor won't fail"); - /// assert_eq!(num_bytes, 7); - /// assert_eq!(name, b"Ferris\0"); - /// - /// // skip fun fact - /// let num_bytes = cursor.skip_until(b'\0') - /// .expect("reading from cursor won't fail"); - /// assert_eq!(num_bytes, 30); - /// - /// // read animal type - /// let mut animal = Vec::new(); - /// let num_bytes = cursor.read_until(b'\0', &mut animal) - /// .expect("reading from cursor won't fail"); - /// assert_eq!(num_bytes, 11); - /// assert_eq!(animal, b"Crustacean\0"); - /// ``` - #[unstable(feature = "bufread_skip_until", issue = "111735")] - fn skip_until(&mut self, byte: u8) -> Result { - skip_until(self, byte) - } - - /// Read all bytes until a newline (the `0xA` byte) is reached, and append - /// them to the provided `String` buffer. - /// - /// Previous content of the buffer will be preserved. To avoid appending to - /// the buffer, you need to [`clear`] it first. - /// - /// This function will read bytes from the underlying stream until the - /// newline delimiter (the `0xA` byte) or EOF is found. Once found, all bytes - /// up to, and including, the delimiter (if found) will be appended to - /// `buf`. - /// - /// If successful, this function will return the total number of bytes read. - /// - /// If this function returns [`Ok(0)`], the stream has reached EOF. - /// - /// This function is blocking and should be used carefully: it is possible for - /// an attacker to continuously send bytes without ever sending a newline - /// or EOF. You can use [`take`] to limit the maximum number of bytes read. - /// - /// [`Ok(0)`]: Ok - /// [`clear`]: String::clear - /// [`take`]: crate::io::Read::take - /// - /// # Errors - /// - /// This function has the same error semantics as [`read_until`] and will - /// also return an error if the read bytes are not valid UTF-8. If an I/O - /// error is encountered then `buf` may contain some bytes already read in - /// the event that all data read so far was valid UTF-8. - /// - /// [`read_until`]: BufRead::read_until - /// - /// # Examples - /// - /// [`std::io::Cursor`][`Cursor`] is a type that implements `BufRead`. In - /// this example, we use [`Cursor`] to read all the lines in a byte slice: - /// - /// ``` - /// use std::io::{self, BufRead}; - /// - /// let mut cursor = io::Cursor::new(b"foo\nbar"); - /// let mut buf = String::new(); - /// - /// // cursor is at 'f' - /// let num_bytes = cursor.read_line(&mut buf) - /// .expect("reading from cursor won't fail"); - /// assert_eq!(num_bytes, 4); - /// assert_eq!(buf, "foo\n"); - /// buf.clear(); - /// - /// // cursor is at 'b' - /// let num_bytes = cursor.read_line(&mut buf) - /// .expect("reading from cursor won't fail"); - /// assert_eq!(num_bytes, 3); - /// assert_eq!(buf, "bar"); - /// buf.clear(); - /// - /// // cursor is at EOF - /// let num_bytes = cursor.read_line(&mut buf) - /// .expect("reading from cursor won't fail"); - /// assert_eq!(num_bytes, 0); - /// assert_eq!(buf, ""); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn read_line(&mut self, buf: &mut String) -> Result { - // Note that we are not calling the `.read_until` method here, but - // rather our hardcoded implementation. For more details as to why, see - // the comments in `read_to_end`. - unsafe { append_to_string(buf, |b| read_until(self, b'\n', b)) } - } - - /// Returns an iterator over the contents of this reader split on the byte - /// `byte`. - /// - /// The iterator returned from this function will return instances of - /// [io::Result]<[Vec]\>. Each vector returned will *not* have - /// the delimiter byte at the end. - /// - /// This function will yield errors whenever [`read_until`] would have - /// also yielded an error. - /// - /// [io::Result]: self::Result "io::Result" - /// [`read_until`]: BufRead::read_until - /// - /// # Examples - /// - /// [`std::io::Cursor`][`Cursor`] is a type that implements `BufRead`. In - /// this example, we use [`Cursor`] to iterate over all hyphen delimited - /// segments in a byte slice - /// - /// ``` - /// use std::io::{self, BufRead}; - /// - /// let cursor = io::Cursor::new(b"lorem-ipsum-dolor"); - /// - /// let mut split_iter = cursor.split(b'-').map(|l| l.unwrap()); - /// assert_eq!(split_iter.next(), Some(b"lorem".to_vec())); - /// assert_eq!(split_iter.next(), Some(b"ipsum".to_vec())); - /// assert_eq!(split_iter.next(), Some(b"dolor".to_vec())); - /// assert_eq!(split_iter.next(), None); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn split(self, byte: u8) -> Split - where - Self: Sized, - { - Split { buf: self, delim: byte } - } - - /// Returns an iterator over the lines of this reader. - /// - /// The iterator returned from this function will yield instances of - /// [io::Result]<[String]>. Each string returned will *not* have a newline - /// byte (the `0xA` byte) or `CRLF` (`0xD`, `0xA` bytes) at the end. - /// - /// [io::Result]: self::Result "io::Result" - /// - /// # Examples - /// - /// [`std::io::Cursor`][`Cursor`] is a type that implements `BufRead`. In - /// this example, we use [`Cursor`] to iterate over all the lines in a byte - /// slice. - /// - /// ``` - /// use std::io::{self, BufRead}; - /// - /// let cursor = io::Cursor::new(b"lorem\nipsum\r\ndolor"); - /// - /// let mut lines_iter = cursor.lines().map(|l| l.unwrap()); - /// assert_eq!(lines_iter.next(), Some(String::from("lorem"))); - /// assert_eq!(lines_iter.next(), Some(String::from("ipsum"))); - /// assert_eq!(lines_iter.next(), Some(String::from("dolor"))); - /// assert_eq!(lines_iter.next(), None); - /// ``` - /// - /// # Errors - /// - /// Each line of the iterator has the same error semantics as [`BufRead::read_line`]. - #[stable(feature = "rust1", since = "1.0.0")] - fn lines(self) -> Lines - where - Self: Sized, - { - Lines { buf: self } - } -} - -/// Adapter to chain together two readers. -/// -/// This struct is generally created by calling [`chain`] on a reader. -/// Please see the documentation of [`chain`] for more details. -/// -/// [`chain`]: Read::chain -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Debug)] -pub struct Chain { - first: T, - second: U, - done_first: bool, -} - -impl Chain { - /// Consumes the `Chain`, returning the wrapped readers. - /// - /// # Examples - /// - /// ```no_run - /// use std::io; - /// use std::io::prelude::*; - /// use std::fs::File; - /// - /// fn main() -> io::Result<()> { - /// let mut foo_file = File::open("foo.txt")?; - /// let mut bar_file = File::open("bar.txt")?; - /// - /// let chain = foo_file.chain(bar_file); - /// let (foo_file, bar_file) = chain.into_inner(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "more_io_inner_methods", since = "1.20.0")] - pub fn into_inner(self) -> (T, U) { - (self.first, self.second) - } - - /// Gets references to the underlying readers in this `Chain`. - /// - /// # Examples - /// - /// ```no_run - /// use std::io; - /// use std::io::prelude::*; - /// use std::fs::File; - /// - /// fn main() -> io::Result<()> { - /// let mut foo_file = File::open("foo.txt")?; - /// let mut bar_file = File::open("bar.txt")?; - /// - /// let chain = foo_file.chain(bar_file); - /// let (foo_file, bar_file) = chain.get_ref(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "more_io_inner_methods", since = "1.20.0")] - pub fn get_ref(&self) -> (&T, &U) { - (&self.first, &self.second) - } - - /// Gets mutable references to the underlying readers in this `Chain`. - /// - /// Care should be taken to avoid modifying the internal I/O state of the - /// underlying readers as doing so may corrupt the internal state of this - /// `Chain`. - /// - /// # Examples - /// - /// ```no_run - /// use std::io; - /// use std::io::prelude::*; - /// use std::fs::File; - /// - /// fn main() -> io::Result<()> { - /// let mut foo_file = File::open("foo.txt")?; - /// let mut bar_file = File::open("bar.txt")?; - /// - /// let mut chain = foo_file.chain(bar_file); - /// let (foo_file, bar_file) = chain.get_mut(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "more_io_inner_methods", since = "1.20.0")] - pub fn get_mut(&mut self) -> (&mut T, &mut U) { - (&mut self.first, &mut self.second) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Read for Chain { - fn read(&mut self, buf: &mut [u8]) -> Result { - if !self.done_first { - match self.first.read(buf)? { - 0 if !buf.is_empty() => self.done_first = true, - n => return Ok(n), - } - } - self.second.read(buf) - } - - fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result { - if !self.done_first { - match self.first.read_vectored(bufs)? { - 0 if bufs.iter().any(|b| !b.is_empty()) => self.done_first = true, - n => return Ok(n), - } - } - self.second.read_vectored(bufs) - } - - #[inline] - fn is_read_vectored(&self) -> bool { - self.first.is_read_vectored() || self.second.is_read_vectored() - } - - fn read_to_end(&mut self, buf: &mut Vec) -> Result { - let mut read = 0; - if !self.done_first { - read += self.first.read_to_end(buf)?; - self.done_first = true; - } - read += self.second.read_to_end(buf)?; - Ok(read) - } - - // We don't override `read_to_string` here because an UTF-8 sequence could - // be split between the two parts of the chain - - fn read_buf(&mut self, mut buf: BorrowedCursor<'_>) -> Result<()> { - if buf.capacity() == 0 { - return Ok(()); - } - - if !self.done_first { - let old_len = buf.written(); - self.first.read_buf(buf.reborrow())?; - - if buf.written() != old_len { - return Ok(()); - } else { - self.done_first = true; - } - } - self.second.read_buf(buf) - } -} - -#[stable(feature = "chain_bufread", since = "1.9.0")] -impl BufRead for Chain { - fn fill_buf(&mut self) -> Result<&[u8]> { - if !self.done_first { - match self.first.fill_buf()? { - buf if buf.is_empty() => self.done_first = true, - buf => return Ok(buf), - } - } - self.second.fill_buf() - } - - fn consume(&mut self, amt: usize) { - if !self.done_first { self.first.consume(amt) } else { self.second.consume(amt) } - } - - fn read_until(&mut self, byte: u8, buf: &mut Vec) -> Result { - let mut read = 0; - if !self.done_first { - let n = self.first.read_until(byte, buf)?; - read += n; - - match buf.last() { - Some(b) if *b == byte && n != 0 => return Ok(read), - _ => self.done_first = true, - } - } - read += self.second.read_until(byte, buf)?; - Ok(read) - } - - // We don't override `read_line` here because an UTF-8 sequence could be - // split between the two parts of the chain -} - -impl SizeHint for Chain { - #[inline] - fn lower_bound(&self) -> usize { - SizeHint::lower_bound(&self.first) + SizeHint::lower_bound(&self.second) - } - - #[inline] - fn upper_bound(&self) -> Option { - match (SizeHint::upper_bound(&self.first), SizeHint::upper_bound(&self.second)) { - (Some(first), Some(second)) => first.checked_add(second), - _ => None, - } - } -} - -/// Reader adapter which limits the bytes read from an underlying reader. -/// -/// This struct is generally created by calling [`take`] on a reader. -/// Please see the documentation of [`take`] for more details. -/// -/// [`take`]: Read::take -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Debug)] -pub struct Take { - inner: T, - limit: u64, -} - -impl Take { - /// Returns the number of bytes that can be read before this instance will - /// return EOF. - /// - /// # Note - /// - /// This instance may reach `EOF` after reading fewer bytes than indicated by - /// this method if the underlying [`Read`] instance reaches EOF. - /// - /// # Examples - /// - /// ```no_run - /// use std::io; - /// use std::io::prelude::*; - /// use std::fs::File; - /// - /// fn main() -> io::Result<()> { - /// let f = File::open("foo.txt")?; - /// - /// // read at most five bytes - /// let handle = f.take(5); - /// - /// println!("limit: {}", handle.limit()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn limit(&self) -> u64 { - self.limit - } - - /// Sets the number of bytes that can be read before this instance will - /// return EOF. This is the same as constructing a new `Take` instance, so - /// the amount of bytes read and the previous limit value don't matter when - /// calling this method. - /// - /// # Examples - /// - /// ```no_run - /// use std::io; - /// use std::io::prelude::*; - /// use std::fs::File; - /// - /// fn main() -> io::Result<()> { - /// let f = File::open("foo.txt")?; - /// - /// // read at most five bytes - /// let mut handle = f.take(5); - /// handle.set_limit(10); - /// - /// assert_eq!(handle.limit(), 10); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "take_set_limit", since = "1.27.0")] - pub fn set_limit(&mut self, limit: u64) { - self.limit = limit; - } - - /// Consumes the `Take`, returning the wrapped reader. - /// - /// # Examples - /// - /// ```no_run - /// use std::io; - /// use std::io::prelude::*; - /// use std::fs::File; - /// - /// fn main() -> io::Result<()> { - /// let mut file = File::open("foo.txt")?; - /// - /// let mut buffer = [0; 5]; - /// let mut handle = file.take(5); - /// handle.read(&mut buffer)?; - /// - /// let file = handle.into_inner(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "io_take_into_inner", since = "1.15.0")] - pub fn into_inner(self) -> T { - self.inner - } - - /// Gets a reference to the underlying reader. - /// - /// # Examples - /// - /// ```no_run - /// use std::io; - /// use std::io::prelude::*; - /// use std::fs::File; - /// - /// fn main() -> io::Result<()> { - /// let mut file = File::open("foo.txt")?; - /// - /// let mut buffer = [0; 5]; - /// let mut handle = file.take(5); - /// handle.read(&mut buffer)?; - /// - /// let file = handle.get_ref(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "more_io_inner_methods", since = "1.20.0")] - pub fn get_ref(&self) -> &T { - &self.inner - } - - /// Gets a mutable reference to the underlying reader. - /// - /// Care should be taken to avoid modifying the internal I/O state of the - /// underlying reader as doing so may corrupt the internal limit of this - /// `Take`. - /// - /// # Examples - /// - /// ```no_run - /// use std::io; - /// use std::io::prelude::*; - /// use std::fs::File; - /// - /// fn main() -> io::Result<()> { - /// let mut file = File::open("foo.txt")?; - /// - /// let mut buffer = [0; 5]; - /// let mut handle = file.take(5); - /// handle.read(&mut buffer)?; - /// - /// let file = handle.get_mut(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "more_io_inner_methods", since = "1.20.0")] - pub fn get_mut(&mut self) -> &mut T { - &mut self.inner - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Read for Take { - fn read(&mut self, buf: &mut [u8]) -> Result { - // Don't call into inner reader at all at EOF because it may still block - if self.limit == 0 { - return Ok(0); - } - - let max = cmp::min(buf.len() as u64, self.limit) as usize; - let n = self.inner.read(&mut buf[..max])?; - assert!(n as u64 <= self.limit, "number of read bytes exceeds limit"); - self.limit -= n as u64; - Ok(n) - } - - fn read_buf(&mut self, mut buf: BorrowedCursor<'_>) -> Result<()> { - // Don't call into inner reader at all at EOF because it may still block - if self.limit == 0 { - return Ok(()); - } - - if self.limit <= buf.capacity() as u64 { - // if we just use an as cast to convert, limit may wrap around on a 32 bit target - let limit = cmp::min(self.limit, usize::MAX as u64) as usize; - - let extra_init = cmp::min(limit as usize, buf.init_ref().len()); - - // SAFETY: no uninit data is written to ibuf - let ibuf = unsafe { &mut buf.as_mut()[..limit] }; - - let mut sliced_buf: BorrowedBuf<'_> = ibuf.into(); - - // SAFETY: extra_init bytes of ibuf are known to be initialized - unsafe { - sliced_buf.set_init(extra_init); - } - - let mut cursor = sliced_buf.unfilled(); - self.inner.read_buf(cursor.reborrow())?; - - let new_init = cursor.init_ref().len(); - let filled = sliced_buf.len(); - - // cursor / sliced_buf / ibuf must drop here - - unsafe { - // SAFETY: filled bytes have been filled and therefore initialized - buf.advance_unchecked(filled); - // SAFETY: new_init bytes of buf's unfilled buffer have been initialized - buf.set_init(new_init); - } - - self.limit -= filled as u64; - } else { - let written = buf.written(); - self.inner.read_buf(buf.reborrow())?; - self.limit -= (buf.written() - written) as u64; - } - - Ok(()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl BufRead for Take { - fn fill_buf(&mut self) -> Result<&[u8]> { - // Don't call into inner reader at all at EOF because it may still block - if self.limit == 0 { - return Ok(&[]); - } - - let buf = self.inner.fill_buf()?; - let cap = cmp::min(buf.len() as u64, self.limit) as usize; - Ok(&buf[..cap]) - } - - fn consume(&mut self, amt: usize) { - // Don't let callers reset the limit by passing an overlarge value - let amt = cmp::min(amt as u64, self.limit) as usize; - self.limit -= amt as u64; - self.inner.consume(amt); - } -} - -impl SizeHint for Take { - #[inline] - fn lower_bound(&self) -> usize { - cmp::min(SizeHint::lower_bound(&self.inner) as u64, self.limit) as usize - } - - #[inline] - fn upper_bound(&self) -> Option { - match SizeHint::upper_bound(&self.inner) { - Some(upper_bound) => Some(cmp::min(upper_bound as u64, self.limit) as usize), - None => self.limit.try_into().ok(), - } - } -} - -/// An iterator over `u8` values of a reader. -/// -/// This struct is generally created by calling [`bytes`] on a reader. -/// Please see the documentation of [`bytes`] for more details. -/// -/// [`bytes`]: Read::bytes -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Debug)] -pub struct Bytes { - inner: R, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for Bytes { - type Item = Result; - - // Not `#[inline]`. This function gets inlined even without it, but having - // the inline annotation can result in worse code generation. See #116785. - fn next(&mut self) -> Option> { - SpecReadByte::spec_read_byte(&mut self.inner) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - SizeHint::size_hint(&self.inner) - } -} - -/// For the specialization of `Bytes::next`. -trait SpecReadByte { - fn spec_read_byte(&mut self) -> Option>; -} - -impl SpecReadByte for R -where - Self: Read, -{ - #[inline] - default fn spec_read_byte(&mut self) -> Option> { - inlined_slow_read_byte(self) - } -} - -/// Read a single byte in a slow, generic way. This is used by the default -/// `spec_read_byte`. -#[inline] -fn inlined_slow_read_byte(reader: &mut R) -> Option> { - let mut byte = 0; - loop { - return match reader.read(slice::from_mut(&mut byte)) { - Ok(0) => None, - Ok(..) => Some(Ok(byte)), - Err(ref e) if e.is_interrupted() => continue, - Err(e) => Some(Err(e)), - }; - } -} - -// Used by `BufReader::spec_read_byte`, for which the `inline(ever)` is -// important. -#[inline(never)] -fn uninlined_slow_read_byte(reader: &mut R) -> Option> { - inlined_slow_read_byte(reader) -} - -trait SizeHint { - fn lower_bound(&self) -> usize; - - fn upper_bound(&self) -> Option; - - fn size_hint(&self) -> (usize, Option) { - (self.lower_bound(), self.upper_bound()) - } -} - -impl SizeHint for T { - #[inline] - default fn lower_bound(&self) -> usize { - 0 - } - - #[inline] - default fn upper_bound(&self) -> Option { - None - } -} - -impl SizeHint for &mut T { - #[inline] - fn lower_bound(&self) -> usize { - SizeHint::lower_bound(*self) - } - - #[inline] - fn upper_bound(&self) -> Option { - SizeHint::upper_bound(*self) - } -} - -impl SizeHint for Box { - #[inline] - fn lower_bound(&self) -> usize { - SizeHint::lower_bound(&**self) - } - - #[inline] - fn upper_bound(&self) -> Option { - SizeHint::upper_bound(&**self) - } -} - -impl SizeHint for &[u8] { - #[inline] - fn lower_bound(&self) -> usize { - self.len() - } - - #[inline] - fn upper_bound(&self) -> Option { - Some(self.len()) - } -} - -/// An iterator over the contents of an instance of `BufRead` split on a -/// particular byte. -/// -/// This struct is generally created by calling [`split`] on a `BufRead`. -/// Please see the documentation of [`split`] for more details. -/// -/// [`split`]: BufRead::split -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Debug)] -pub struct Split { - buf: B, - delim: u8, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for Split { - type Item = Result>; - - fn next(&mut self) -> Option>> { - let mut buf = Vec::new(); - match self.buf.read_until(self.delim, &mut buf) { - Ok(0) => None, - Ok(_n) => { - if buf[buf.len() - 1] == self.delim { - buf.pop(); - } - Some(Ok(buf)) - } - Err(e) => Some(Err(e)), - } - } -} - -/// An iterator over the lines of an instance of `BufRead`. -/// -/// This struct is generally created by calling [`lines`] on a `BufRead`. -/// Please see the documentation of [`lines`] for more details. -/// -/// [`lines`]: BufRead::lines -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Debug)] -#[cfg_attr(not(test), rustc_diagnostic_item = "IoLines")] -pub struct Lines { - buf: B, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for Lines { - type Item = Result; - - fn next(&mut self) -> Option> { - let mut buf = String::new(); - match self.buf.read_line(&mut buf) { - Ok(0) => None, - Ok(_n) => { - if buf.ends_with('\n') { - buf.pop(); - if buf.ends_with('\r') { - buf.pop(); - } - } - Some(Ok(buf)) - } - Err(e) => Some(Err(e)), - } - } -} diff --git a/library/std/src/io/prelude.rs b/library/std/src/io/prelude.rs deleted file mode 100644 index d80643101f2ed..0000000000000 --- a/library/std/src/io/prelude.rs +++ /dev/null @@ -1,14 +0,0 @@ -//! The I/O Prelude. -//! -//! The purpose of this module is to alleviate imports of many common I/O traits -//! by adding a glob import to the top of I/O heavy modules: -//! -//! ``` -//! # #![allow(unused_imports)] -//! use std::io::prelude::*; -//! ``` - -#![stable(feature = "rust1", since = "1.0.0")] - -#[stable(feature = "rust1", since = "1.0.0")] -pub use super::{BufRead, Read, Seek, Write}; diff --git a/library/std/src/io/stdio.rs b/library/std/src/io/stdio.rs deleted file mode 100644 index c8968b74b12d1..0000000000000 --- a/library/std/src/io/stdio.rs +++ /dev/null @@ -1,1243 +0,0 @@ -#![cfg_attr(test, allow(unused))] - -#[cfg(test)] -mod tests; - -use crate::io::prelude::*; - -use crate::cell::{Cell, RefCell}; -use crate::fmt; -use crate::fs::File; -use crate::io::{ - self, BorrowedCursor, BufReader, IoSlice, IoSliceMut, LineWriter, Lines, SpecReadByte, -}; -use crate::panic::{RefUnwindSafe, UnwindSafe}; -use crate::sync::atomic::{AtomicBool, Ordering}; -use crate::sync::{Arc, Mutex, MutexGuard, OnceLock, ReentrantLock, ReentrantLockGuard}; -use crate::sys::stdio; -use crate::thread::AccessError; - -type LocalStream = Arc>>; - -thread_local! { - /// Used by the test crate to capture the output of the print macros and panics. - static OUTPUT_CAPTURE: Cell> = { - Cell::new(None) - } -} - -/// Flag to indicate OUTPUT_CAPTURE is used. -/// -/// If it is None and was never set on any thread, this flag is set to false, -/// and OUTPUT_CAPTURE can be safely ignored on all threads, saving some time -/// and memory registering an unused thread local. -/// -/// Note about memory ordering: This contains information about whether a -/// thread local variable might be in use. Although this is a global flag, the -/// memory ordering between threads does not matter: we only want this flag to -/// have a consistent order between set_output_capture and print_to *within -/// the same thread*. Within the same thread, things always have a perfectly -/// consistent order. So Ordering::Relaxed is fine. -static OUTPUT_CAPTURE_USED: AtomicBool = AtomicBool::new(false); - -/// A handle to a raw instance of the standard input stream of this process. -/// -/// This handle is not synchronized or buffered in any fashion. Constructed via -/// the `std::io::stdio::stdin_raw` function. -struct StdinRaw(stdio::Stdin); - -/// A handle to a raw instance of the standard output stream of this process. -/// -/// This handle is not synchronized or buffered in any fashion. Constructed via -/// the `std::io::stdio::stdout_raw` function. -struct StdoutRaw(stdio::Stdout); - -/// A handle to a raw instance of the standard output stream of this process. -/// -/// This handle is not synchronized or buffered in any fashion. Constructed via -/// the `std::io::stdio::stderr_raw` function. -struct StderrRaw(stdio::Stderr); - -/// Constructs a new raw handle to the standard input of this process. -/// -/// The returned handle does not interact with any other handles created nor -/// handles returned by `std::io::stdin`. Data buffered by the `std::io::stdin` -/// handles is **not** available to raw handles returned from this function. -/// -/// The returned handle has no external synchronization or buffering. -#[unstable(feature = "libstd_sys_internals", issue = "none")] -const fn stdin_raw() -> StdinRaw { - StdinRaw(stdio::Stdin::new()) -} - -/// Constructs a new raw handle to the standard output stream of this process. -/// -/// The returned handle does not interact with any other handles created nor -/// handles returned by `std::io::stdout`. Note that data is buffered by the -/// `std::io::stdout` handles so writes which happen via this raw handle may -/// appear before previous writes. -/// -/// The returned handle has no external synchronization or buffering layered on -/// top. -#[unstable(feature = "libstd_sys_internals", issue = "none")] -const fn stdout_raw() -> StdoutRaw { - StdoutRaw(stdio::Stdout::new()) -} - -/// Constructs a new raw handle to the standard error stream of this process. -/// -/// The returned handle does not interact with any other handles created nor -/// handles returned by `std::io::stderr`. -/// -/// The returned handle has no external synchronization or buffering layered on -/// top. -#[unstable(feature = "libstd_sys_internals", issue = "none")] -const fn stderr_raw() -> StderrRaw { - StderrRaw(stdio::Stderr::new()) -} - -impl Read for StdinRaw { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - handle_ebadf(self.0.read(buf), 0) - } - - fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> io::Result<()> { - handle_ebadf(self.0.read_buf(buf), ()) - } - - fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - handle_ebadf(self.0.read_vectored(bufs), 0) - } - - #[inline] - fn is_read_vectored(&self) -> bool { - self.0.is_read_vectored() - } - - fn read_to_end(&mut self, buf: &mut Vec) -> io::Result { - handle_ebadf(self.0.read_to_end(buf), 0) - } - - fn read_to_string(&mut self, buf: &mut String) -> io::Result { - handle_ebadf(self.0.read_to_string(buf), 0) - } -} - -impl Write for StdoutRaw { - fn write(&mut self, buf: &[u8]) -> io::Result { - handle_ebadf(self.0.write(buf), buf.len()) - } - - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - let total = || bufs.iter().map(|b| b.len()).sum(); - handle_ebadf_lazy(self.0.write_vectored(bufs), total) - } - - #[inline] - fn is_write_vectored(&self) -> bool { - self.0.is_write_vectored() - } - - fn flush(&mut self) -> io::Result<()> { - handle_ebadf(self.0.flush(), ()) - } - - fn write_all(&mut self, buf: &[u8]) -> io::Result<()> { - handle_ebadf(self.0.write_all(buf), ()) - } - - fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> { - handle_ebadf(self.0.write_all_vectored(bufs), ()) - } - - fn write_fmt(&mut self, fmt: fmt::Arguments<'_>) -> io::Result<()> { - handle_ebadf(self.0.write_fmt(fmt), ()) - } -} - -impl Write for StderrRaw { - fn write(&mut self, buf: &[u8]) -> io::Result { - handle_ebadf(self.0.write(buf), buf.len()) - } - - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - let total = || bufs.iter().map(|b| b.len()).sum(); - handle_ebadf_lazy(self.0.write_vectored(bufs), total) - } - - #[inline] - fn is_write_vectored(&self) -> bool { - self.0.is_write_vectored() - } - - fn flush(&mut self) -> io::Result<()> { - handle_ebadf(self.0.flush(), ()) - } - - fn write_all(&mut self, buf: &[u8]) -> io::Result<()> { - handle_ebadf(self.0.write_all(buf), ()) - } - - fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> { - handle_ebadf(self.0.write_all_vectored(bufs), ()) - } - - fn write_fmt(&mut self, fmt: fmt::Arguments<'_>) -> io::Result<()> { - handle_ebadf(self.0.write_fmt(fmt), ()) - } -} - -fn handle_ebadf(r: io::Result, default: T) -> io::Result { - match r { - Err(ref e) if stdio::is_ebadf(e) => Ok(default), - r => r, - } -} - -fn handle_ebadf_lazy(r: io::Result, default: impl FnOnce() -> T) -> io::Result { - match r { - Err(ref e) if stdio::is_ebadf(e) => Ok(default()), - r => r, - } -} - -/// A handle to the standard input stream of a process. -/// -/// Each handle is a shared reference to a global buffer of input data to this -/// process. A handle can be `lock`'d to gain full access to [`BufRead`] methods -/// (e.g., `.lines()`). Reads to this handle are otherwise locked with respect -/// to other reads. -/// -/// This handle implements the `Read` trait, but beware that concurrent reads -/// of `Stdin` must be executed with care. -/// -/// Created by the [`io::stdin`] method. -/// -/// [`io::stdin`]: stdin -/// -/// ### Note: Windows Portability Considerations -/// -/// When operating in a console, the Windows implementation of this stream does not support -/// non-UTF-8 byte sequences. Attempting to read bytes that are not valid UTF-8 will return -/// an error. -/// -/// In a process with a detached console, such as one using -/// `#![windows_subsystem = "windows"]`, or in a child process spawned from such a process, -/// the contained handle will be null. In such cases, the standard library's `Read` and -/// `Write` will do nothing and silently succeed. All other I/O operations, via the -/// standard library or via raw Windows API calls, will fail. -/// -/// # Examples -/// -/// ```no_run -/// use std::io; -/// -/// fn main() -> io::Result<()> { -/// let mut buffer = String::new(); -/// let stdin = io::stdin(); // We get `Stdin` here. -/// stdin.read_line(&mut buffer)?; -/// Ok(()) -/// } -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Stdin { - inner: &'static Mutex>, -} - -/// A locked reference to the [`Stdin`] handle. -/// -/// This handle implements both the [`Read`] and [`BufRead`] traits, and -/// is constructed via the [`Stdin::lock`] method. -/// -/// ### Note: Windows Portability Considerations -/// -/// When operating in a console, the Windows implementation of this stream does not support -/// non-UTF-8 byte sequences. Attempting to read bytes that are not valid UTF-8 will return -/// an error. -/// -/// In a process with a detached console, such as one using -/// `#![windows_subsystem = "windows"]`, or in a child process spawned from such a process, -/// the contained handle will be null. In such cases, the standard library's `Read` and -/// `Write` will do nothing and silently succeed. All other I/O operations, via the -/// standard library or via raw Windows API calls, will fail. -/// -/// # Examples -/// -/// ```no_run -/// use std::io::{self, BufRead}; -/// -/// fn main() -> io::Result<()> { -/// let mut buffer = String::new(); -/// let stdin = io::stdin(); // We get `Stdin` here. -/// { -/// let mut handle = stdin.lock(); // We get `StdinLock` here. -/// handle.read_line(&mut buffer)?; -/// } // `StdinLock` is dropped here. -/// Ok(()) -/// } -/// ``` -#[must_use = "if unused stdin will immediately unlock"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct StdinLock<'a> { - inner: MutexGuard<'a, BufReader>, -} - -/// Constructs a new handle to the standard input of the current process. -/// -/// Each handle returned is a reference to a shared global buffer whose access -/// is synchronized via a mutex. If you need more explicit control over -/// locking, see the [`Stdin::lock`] method. -/// -/// ### Note: Windows Portability Considerations -/// -/// When operating in a console, the Windows implementation of this stream does not support -/// non-UTF-8 byte sequences. Attempting to read bytes that are not valid UTF-8 will return -/// an error. -/// -/// In a process with a detached console, such as one using -/// `#![windows_subsystem = "windows"]`, or in a child process spawned from such a process, -/// the contained handle will be null. In such cases, the standard library's `Read` and -/// `Write` will do nothing and silently succeed. All other I/O operations, via the -/// standard library or via raw Windows API calls, will fail. -/// -/// # Examples -/// -/// Using implicit synchronization: -/// -/// ```no_run -/// use std::io; -/// -/// fn main() -> io::Result<()> { -/// let mut buffer = String::new(); -/// io::stdin().read_line(&mut buffer)?; -/// Ok(()) -/// } -/// ``` -/// -/// Using explicit synchronization: -/// -/// ```no_run -/// use std::io::{self, BufRead}; -/// -/// fn main() -> io::Result<()> { -/// let mut buffer = String::new(); -/// let stdin = io::stdin(); -/// let mut handle = stdin.lock(); -/// -/// handle.read_line(&mut buffer)?; -/// Ok(()) -/// } -/// ``` -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -pub fn stdin() -> Stdin { - static INSTANCE: OnceLock>> = OnceLock::new(); - Stdin { - inner: INSTANCE.get_or_init(|| { - Mutex::new(BufReader::with_capacity(stdio::STDIN_BUF_SIZE, stdin_raw())) - }), - } -} - -impl Stdin { - /// Locks this handle to the standard input stream, returning a readable - /// guard. - /// - /// The lock is released when the returned lock goes out of scope. The - /// returned guard also implements the [`Read`] and [`BufRead`] traits for - /// accessing the underlying data. - /// - /// # Examples - /// - /// ```no_run - /// use std::io::{self, BufRead}; - /// - /// fn main() -> io::Result<()> { - /// let mut buffer = String::new(); - /// let stdin = io::stdin(); - /// let mut handle = stdin.lock(); - /// - /// handle.read_line(&mut buffer)?; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn lock(&self) -> StdinLock<'static> { - // Locks this handle with 'static lifetime. This depends on the - // implementation detail that the underlying `Mutex` is static. - StdinLock { inner: self.inner.lock().unwrap_or_else(|e| e.into_inner()) } - } - - /// Locks this handle and reads a line of input, appending it to the specified buffer. - /// - /// For detailed semantics of this method, see the documentation on - /// [`BufRead::read_line`]. - /// - /// # Examples - /// - /// ```no_run - /// use std::io; - /// - /// let mut input = String::new(); - /// match io::stdin().read_line(&mut input) { - /// Ok(n) => { - /// println!("{n} bytes read"); - /// println!("{input}"); - /// } - /// Err(error) => println!("error: {error}"), - /// } - /// ``` - /// - /// You can run the example one of two ways: - /// - /// - Pipe some text to it, e.g., `printf foo | path/to/executable` - /// - Give it text interactively by running the executable directly, - /// in which case it will wait for the Enter key to be pressed before - /// continuing - #[stable(feature = "rust1", since = "1.0.0")] - pub fn read_line(&self, buf: &mut String) -> io::Result { - self.lock().read_line(buf) - } - - /// Consumes this handle and returns an iterator over input lines. - /// - /// For detailed semantics of this method, see the documentation on - /// [`BufRead::lines`]. - /// - /// # Examples - /// - /// ```no_run - /// use std::io; - /// - /// let lines = io::stdin().lines(); - /// for line in lines { - /// println!("got a line: {}", line.unwrap()); - /// } - /// ``` - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "stdin_forwarders", since = "1.62.0")] - pub fn lines(self) -> Lines> { - self.lock().lines() - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for Stdin { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Stdin").finish_non_exhaustive() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Read for Stdin { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - self.lock().read(buf) - } - fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> io::Result<()> { - self.lock().read_buf(buf) - } - fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - self.lock().read_vectored(bufs) - } - #[inline] - fn is_read_vectored(&self) -> bool { - self.lock().is_read_vectored() - } - fn read_to_end(&mut self, buf: &mut Vec) -> io::Result { - self.lock().read_to_end(buf) - } - fn read_to_string(&mut self, buf: &mut String) -> io::Result { - self.lock().read_to_string(buf) - } - fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> { - self.lock().read_exact(buf) - } - fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> io::Result<()> { - self.lock().read_buf_exact(cursor) - } -} - -#[stable(feature = "read_shared_stdin", since = "1.78.0")] -impl Read for &Stdin { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - self.lock().read(buf) - } - fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> io::Result<()> { - self.lock().read_buf(buf) - } - fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - self.lock().read_vectored(bufs) - } - #[inline] - fn is_read_vectored(&self) -> bool { - self.lock().is_read_vectored() - } - fn read_to_end(&mut self, buf: &mut Vec) -> io::Result { - self.lock().read_to_end(buf) - } - fn read_to_string(&mut self, buf: &mut String) -> io::Result { - self.lock().read_to_string(buf) - } - fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> { - self.lock().read_exact(buf) - } - fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> io::Result<()> { - self.lock().read_buf_exact(cursor) - } -} - -// only used by platform-dependent io::copy specializations, i.e. unused on some platforms -#[cfg(any(target_os = "linux", target_os = "android"))] -impl StdinLock<'_> { - pub(crate) fn as_mut_buf(&mut self) -> &mut BufReader { - &mut self.inner - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Read for StdinLock<'_> { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - self.inner.read(buf) - } - - fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> io::Result<()> { - self.inner.read_buf(buf) - } - - fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - self.inner.read_vectored(bufs) - } - - #[inline] - fn is_read_vectored(&self) -> bool { - self.inner.is_read_vectored() - } - - fn read_to_end(&mut self, buf: &mut Vec) -> io::Result { - self.inner.read_to_end(buf) - } - - fn read_to_string(&mut self, buf: &mut String) -> io::Result { - self.inner.read_to_string(buf) - } - - fn read_exact(&mut self, buf: &mut [u8]) -> io::Result<()> { - self.inner.read_exact(buf) - } - - fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> io::Result<()> { - self.inner.read_buf_exact(cursor) - } -} - -impl SpecReadByte for StdinLock<'_> { - #[inline] - fn spec_read_byte(&mut self) -> Option> { - BufReader::spec_read_byte(&mut *self.inner) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl BufRead for StdinLock<'_> { - fn fill_buf(&mut self) -> io::Result<&[u8]> { - self.inner.fill_buf() - } - - fn consume(&mut self, n: usize) { - self.inner.consume(n) - } - - fn read_until(&mut self, byte: u8, buf: &mut Vec) -> io::Result { - self.inner.read_until(byte, buf) - } - - fn read_line(&mut self, buf: &mut String) -> io::Result { - self.inner.read_line(buf) - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for StdinLock<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("StdinLock").finish_non_exhaustive() - } -} - -/// A handle to the global standard output stream of the current process. -/// -/// Each handle shares a global buffer of data to be written to the standard -/// output stream. Access is also synchronized via a lock and explicit control -/// over locking is available via the [`lock`] method. -/// -/// Created by the [`io::stdout`] method. -/// -/// ### Note: Windows Portability Considerations -/// -/// When operating in a console, the Windows implementation of this stream does not support -/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return -/// an error. -/// -/// In a process with a detached console, such as one using -/// `#![windows_subsystem = "windows"]`, or in a child process spawned from such a process, -/// the contained handle will be null. In such cases, the standard library's `Read` and -/// `Write` will do nothing and silently succeed. All other I/O operations, via the -/// standard library or via raw Windows API calls, will fail. -/// -/// [`lock`]: Stdout::lock -/// [`io::stdout`]: stdout -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Stdout { - // FIXME: this should be LineWriter or BufWriter depending on the state of - // stdout (tty or not). Note that if this is not line buffered it - // should also flush-on-panic or some form of flush-on-abort. - inner: &'static ReentrantLock>>, -} - -/// A locked reference to the [`Stdout`] handle. -/// -/// This handle implements the [`Write`] trait, and is constructed via -/// the [`Stdout::lock`] method. See its documentation for more. -/// -/// ### Note: Windows Portability Considerations -/// -/// When operating in a console, the Windows implementation of this stream does not support -/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return -/// an error. -/// -/// In a process with a detached console, such as one using -/// `#![windows_subsystem = "windows"]`, or in a child process spawned from such a process, -/// the contained handle will be null. In such cases, the standard library's `Read` and -/// `Write` will do nothing and silently succeed. All other I/O operations, via the -/// standard library or via raw Windows API calls, will fail. -#[must_use = "if unused stdout will immediately unlock"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct StdoutLock<'a> { - inner: ReentrantLockGuard<'a, RefCell>>, -} - -static STDOUT: OnceLock>>> = OnceLock::new(); - -/// Constructs a new handle to the standard output of the current process. -/// -/// Each handle returned is a reference to a shared global buffer whose access -/// is synchronized via a mutex. If you need more explicit control over -/// locking, see the [`Stdout::lock`] method. -/// -/// ### Note: Windows Portability Considerations -/// -/// When operating in a console, the Windows implementation of this stream does not support -/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return -/// an error. -/// -/// In a process with a detached console, such as one using -/// `#![windows_subsystem = "windows"]`, or in a child process spawned from such a process, -/// the contained handle will be null. In such cases, the standard library's `Read` and -/// `Write` will do nothing and silently succeed. All other I/O operations, via the -/// standard library or via raw Windows API calls, will fail. -/// -/// # Examples -/// -/// Using implicit synchronization: -/// -/// ```no_run -/// use std::io::{self, Write}; -/// -/// fn main() -> io::Result<()> { -/// io::stdout().write_all(b"hello world")?; -/// -/// Ok(()) -/// } -/// ``` -/// -/// Using explicit synchronization: -/// -/// ```no_run -/// use std::io::{self, Write}; -/// -/// fn main() -> io::Result<()> { -/// let stdout = io::stdout(); -/// let mut handle = stdout.lock(); -/// -/// handle.write_all(b"hello world")?; -/// -/// Ok(()) -/// } -/// ``` -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "io_stdout")] -pub fn stdout() -> Stdout { - Stdout { - inner: STDOUT - .get_or_init(|| ReentrantLock::new(RefCell::new(LineWriter::new(stdout_raw())))), - } -} - -// Flush the data and disable buffering during shutdown -// by replacing the line writer by one with zero -// buffering capacity. -pub fn cleanup() { - let mut initialized = false; - let stdout = STDOUT.get_or_init(|| { - initialized = true; - ReentrantLock::new(RefCell::new(LineWriter::with_capacity(0, stdout_raw()))) - }); - - if !initialized { - // The buffer was previously initialized, overwrite it here. - // We use try_lock() instead of lock(), because someone - // might have leaked a StdoutLock, which would - // otherwise cause a deadlock here. - if let Some(lock) = stdout.try_lock() { - *lock.borrow_mut() = LineWriter::with_capacity(0, stdout_raw()); - } - } -} - -impl Stdout { - /// Locks this handle to the standard output stream, returning a writable - /// guard. - /// - /// The lock is released when the returned lock goes out of scope. The - /// returned guard also implements the `Write` trait for writing data. - /// - /// # Examples - /// - /// ```no_run - /// use std::io::{self, Write}; - /// - /// fn main() -> io::Result<()> { - /// let mut stdout = io::stdout().lock(); - /// - /// stdout.write_all(b"hello world")?; - /// - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn lock(&self) -> StdoutLock<'static> { - // Locks this handle with 'static lifetime. This depends on the - // implementation detail that the underlying `ReentrantMutex` is - // static. - StdoutLock { inner: self.inner.lock() } - } -} - -#[stable(feature = "catch_unwind", since = "1.9.0")] -impl UnwindSafe for Stdout {} - -#[stable(feature = "catch_unwind", since = "1.9.0")] -impl RefUnwindSafe for Stdout {} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for Stdout { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Stdout").finish_non_exhaustive() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Write for Stdout { - fn write(&mut self, buf: &[u8]) -> io::Result { - (&*self).write(buf) - } - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - (&*self).write_vectored(bufs) - } - #[inline] - fn is_write_vectored(&self) -> bool { - io::Write::is_write_vectored(&&*self) - } - fn flush(&mut self) -> io::Result<()> { - (&*self).flush() - } - fn write_all(&mut self, buf: &[u8]) -> io::Result<()> { - (&*self).write_all(buf) - } - fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> { - (&*self).write_all_vectored(bufs) - } - fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> io::Result<()> { - (&*self).write_fmt(args) - } -} - -#[stable(feature = "write_mt", since = "1.48.0")] -impl Write for &Stdout { - fn write(&mut self, buf: &[u8]) -> io::Result { - self.lock().write(buf) - } - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - self.lock().write_vectored(bufs) - } - #[inline] - fn is_write_vectored(&self) -> bool { - self.lock().is_write_vectored() - } - fn flush(&mut self) -> io::Result<()> { - self.lock().flush() - } - fn write_all(&mut self, buf: &[u8]) -> io::Result<()> { - self.lock().write_all(buf) - } - fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> { - self.lock().write_all_vectored(bufs) - } - fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> io::Result<()> { - self.lock().write_fmt(args) - } -} - -#[stable(feature = "catch_unwind", since = "1.9.0")] -impl UnwindSafe for StdoutLock<'_> {} - -#[stable(feature = "catch_unwind", since = "1.9.0")] -impl RefUnwindSafe for StdoutLock<'_> {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Write for StdoutLock<'_> { - fn write(&mut self, buf: &[u8]) -> io::Result { - self.inner.borrow_mut().write(buf) - } - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - self.inner.borrow_mut().write_vectored(bufs) - } - #[inline] - fn is_write_vectored(&self) -> bool { - self.inner.borrow_mut().is_write_vectored() - } - fn flush(&mut self) -> io::Result<()> { - self.inner.borrow_mut().flush() - } - fn write_all(&mut self, buf: &[u8]) -> io::Result<()> { - self.inner.borrow_mut().write_all(buf) - } - fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> { - self.inner.borrow_mut().write_all_vectored(bufs) - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for StdoutLock<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("StdoutLock").finish_non_exhaustive() - } -} - -/// A handle to the standard error stream of a process. -/// -/// For more information, see the [`io::stderr`] method. -/// -/// [`io::stderr`]: stderr -/// -/// ### Note: Windows Portability Considerations -/// -/// When operating in a console, the Windows implementation of this stream does not support -/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return -/// an error. -/// -/// In a process with a detached console, such as one using -/// `#![windows_subsystem = "windows"]`, or in a child process spawned from such a process, -/// the contained handle will be null. In such cases, the standard library's `Read` and -/// `Write` will do nothing and silently succeed. All other I/O operations, via the -/// standard library or via raw Windows API calls, will fail. -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Stderr { - inner: &'static ReentrantLock>, -} - -/// A locked reference to the [`Stderr`] handle. -/// -/// This handle implements the [`Write`] trait and is constructed via -/// the [`Stderr::lock`] method. See its documentation for more. -/// -/// ### Note: Windows Portability Considerations -/// -/// When operating in a console, the Windows implementation of this stream does not support -/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return -/// an error. -/// -/// In a process with a detached console, such as one using -/// `#![windows_subsystem = "windows"]`, or in a child process spawned from such a process, -/// the contained handle will be null. In such cases, the standard library's `Read` and -/// `Write` will do nothing and silently succeed. All other I/O operations, via the -/// standard library or via raw Windows API calls, will fail. -#[must_use = "if unused stderr will immediately unlock"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct StderrLock<'a> { - inner: ReentrantLockGuard<'a, RefCell>, -} - -/// Constructs a new handle to the standard error of the current process. -/// -/// This handle is not buffered. -/// -/// ### Note: Windows Portability Considerations -/// -/// When operating in a console, the Windows implementation of this stream does not support -/// non-UTF-8 byte sequences. Attempting to write bytes that are not valid UTF-8 will return -/// an error. -/// -/// In a process with a detached console, such as one using -/// `#![windows_subsystem = "windows"]`, or in a child process spawned from such a process, -/// the contained handle will be null. In such cases, the standard library's `Read` and -/// `Write` will do nothing and silently succeed. All other I/O operations, via the -/// standard library or via raw Windows API calls, will fail. -/// -/// # Examples -/// -/// Using implicit synchronization: -/// -/// ```no_run -/// use std::io::{self, Write}; -/// -/// fn main() -> io::Result<()> { -/// io::stderr().write_all(b"hello world")?; -/// -/// Ok(()) -/// } -/// ``` -/// -/// Using explicit synchronization: -/// -/// ```no_run -/// use std::io::{self, Write}; -/// -/// fn main() -> io::Result<()> { -/// let stderr = io::stderr(); -/// let mut handle = stderr.lock(); -/// -/// handle.write_all(b"hello world")?; -/// -/// Ok(()) -/// } -/// ``` -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "io_stderr")] -pub fn stderr() -> Stderr { - // Note that unlike `stdout()` we don't use `at_exit` here to register a - // destructor. Stderr is not buffered, so there's no need to run a - // destructor for flushing the buffer - static INSTANCE: ReentrantLock> = - ReentrantLock::new(RefCell::new(stderr_raw())); - - Stderr { inner: &INSTANCE } -} - -impl Stderr { - /// Locks this handle to the standard error stream, returning a writable - /// guard. - /// - /// The lock is released when the returned lock goes out of scope. The - /// returned guard also implements the [`Write`] trait for writing data. - /// - /// # Examples - /// - /// ``` - /// use std::io::{self, Write}; - /// - /// fn foo() -> io::Result<()> { - /// let stderr = io::stderr(); - /// let mut handle = stderr.lock(); - /// - /// handle.write_all(b"hello world")?; - /// - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn lock(&self) -> StderrLock<'static> { - // Locks this handle with 'static lifetime. This depends on the - // implementation detail that the underlying `ReentrantMutex` is - // static. - StderrLock { inner: self.inner.lock() } - } -} - -#[stable(feature = "catch_unwind", since = "1.9.0")] -impl UnwindSafe for Stderr {} - -#[stable(feature = "catch_unwind", since = "1.9.0")] -impl RefUnwindSafe for Stderr {} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for Stderr { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Stderr").finish_non_exhaustive() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Write for Stderr { - fn write(&mut self, buf: &[u8]) -> io::Result { - (&*self).write(buf) - } - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - (&*self).write_vectored(bufs) - } - #[inline] - fn is_write_vectored(&self) -> bool { - io::Write::is_write_vectored(&&*self) - } - fn flush(&mut self) -> io::Result<()> { - (&*self).flush() - } - fn write_all(&mut self, buf: &[u8]) -> io::Result<()> { - (&*self).write_all(buf) - } - fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> { - (&*self).write_all_vectored(bufs) - } - fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> io::Result<()> { - (&*self).write_fmt(args) - } -} - -#[stable(feature = "write_mt", since = "1.48.0")] -impl Write for &Stderr { - fn write(&mut self, buf: &[u8]) -> io::Result { - self.lock().write(buf) - } - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - self.lock().write_vectored(bufs) - } - #[inline] - fn is_write_vectored(&self) -> bool { - self.lock().is_write_vectored() - } - fn flush(&mut self) -> io::Result<()> { - self.lock().flush() - } - fn write_all(&mut self, buf: &[u8]) -> io::Result<()> { - self.lock().write_all(buf) - } - fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> { - self.lock().write_all_vectored(bufs) - } - fn write_fmt(&mut self, args: fmt::Arguments<'_>) -> io::Result<()> { - self.lock().write_fmt(args) - } -} - -#[stable(feature = "catch_unwind", since = "1.9.0")] -impl UnwindSafe for StderrLock<'_> {} - -#[stable(feature = "catch_unwind", since = "1.9.0")] -impl RefUnwindSafe for StderrLock<'_> {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Write for StderrLock<'_> { - fn write(&mut self, buf: &[u8]) -> io::Result { - self.inner.borrow_mut().write(buf) - } - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - self.inner.borrow_mut().write_vectored(bufs) - } - #[inline] - fn is_write_vectored(&self) -> bool { - self.inner.borrow_mut().is_write_vectored() - } - fn flush(&mut self) -> io::Result<()> { - self.inner.borrow_mut().flush() - } - fn write_all(&mut self, buf: &[u8]) -> io::Result<()> { - self.inner.borrow_mut().write_all(buf) - } - fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> io::Result<()> { - self.inner.borrow_mut().write_all_vectored(bufs) - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for StderrLock<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("StderrLock").finish_non_exhaustive() - } -} - -/// Sets the thread-local output capture buffer and returns the old one. -#[unstable( - feature = "internal_output_capture", - reason = "this function is meant for use in the test crate \ - and may disappear in the future", - issue = "none" -)] -#[doc(hidden)] -pub fn set_output_capture(sink: Option) -> Option { - try_set_output_capture(sink).expect( - "cannot access a Thread Local Storage value \ - during or after destruction", - ) -} - -/// Tries to set the thread-local output capture buffer and returns the old one. -/// This may fail once thread-local destructors are called. It's used in panic -/// handling instead of `set_output_capture`. -#[unstable( - feature = "internal_output_capture", - reason = "this function is meant for use in the test crate \ - and may disappear in the future", - issue = "none" -)] -#[doc(hidden)] -pub fn try_set_output_capture( - sink: Option, -) -> Result, AccessError> { - if sink.is_none() && !OUTPUT_CAPTURE_USED.load(Ordering::Relaxed) { - // OUTPUT_CAPTURE is definitely None since OUTPUT_CAPTURE_USED is false. - return Ok(None); - } - OUTPUT_CAPTURE_USED.store(true, Ordering::Relaxed); - OUTPUT_CAPTURE.try_with(move |slot| slot.replace(sink)) -} - -/// Write `args` to the capture buffer if enabled and possible, or `global_s` -/// otherwise. `label` identifies the stream in a panic message. -/// -/// This function is used to print error messages, so it takes extra -/// care to avoid causing a panic when `OUTPUT_CAPTURE` is unusable. -/// For instance, if the TLS key for output capturing is already destroyed, or -/// if the local stream is in use by another thread, it will just fall back to -/// the global stream. -/// -/// However, if the actual I/O causes an error, this function does panic. -/// -/// Writing to non-blocking stdout/stderr can cause an error, which will lead -/// this function to panic. -fn print_to(args: fmt::Arguments<'_>, global_s: fn() -> T, label: &str) -where - T: Write, -{ - if print_to_buffer_if_capture_used(args) { - // Successfully wrote to capture buffer. - return; - } - - if let Err(e) = global_s().write_fmt(args) { - panic!("failed printing to {label}: {e}"); - } -} - -fn print_to_buffer_if_capture_used(args: fmt::Arguments<'_>) -> bool { - OUTPUT_CAPTURE_USED.load(Ordering::Relaxed) - && OUTPUT_CAPTURE.try_with(|s| { - // Note that we completely remove a local sink to write to in case - // our printing recursively panics/prints, so the recursive - // panic/print goes to the global sink instead of our local sink. - s.take().map(|w| { - let _ = w.lock().unwrap_or_else(|e| e.into_inner()).write_fmt(args); - s.set(Some(w)); - }) - }) == Ok(Some(())) -} - -/// Used by impl Termination for Result to print error after `main` or a test -/// has returned. Should avoid panicking, although we can't help it if one of -/// the Display impls inside args decides to. -pub(crate) fn attempt_print_to_stderr(args: fmt::Arguments<'_>) { - if print_to_buffer_if_capture_used(args) { - return; - } - - // Ignore error if the write fails, for example because stderr is already - // closed. There is not much point panicking at this point. - let _ = stderr().write_fmt(args); -} - -/// Trait to determine if a descriptor/handle refers to a terminal/tty. -#[stable(feature = "is_terminal", since = "1.70.0")] -pub trait IsTerminal: crate::sealed::Sealed { - /// Returns `true` if the descriptor/handle refers to a terminal/tty. - /// - /// On platforms where Rust does not know how to detect a terminal yet, this will return - /// `false`. This will also return `false` if an unexpected error occurred, such as from - /// passing an invalid file descriptor. - /// - /// # Platform-specific behavior - /// - /// On Windows, in addition to detecting consoles, this currently uses some heuristics to - /// detect older msys/cygwin/mingw pseudo-terminals based on device name: devices with names - /// starting with `msys-` or `cygwin-` and ending in `-pty` will be considered terminals. - /// Note that this [may change in the future][changes]. - /// - /// # Examples - /// - /// An example of a type for which `IsTerminal` is implemented is [`Stdin`]: - /// - /// ```no_run - /// use std::io::{self, IsTerminal, Write}; - /// - /// fn main() -> io::Result<()> { - /// let stdin = io::stdin(); - /// - /// // Indicate that the user is prompted for input, if this is a terminal. - /// if stdin.is_terminal() { - /// print!("> "); - /// io::stdout().flush()?; - /// } - /// - /// let mut name = String::new(); - /// let _ = stdin.read_line(&mut name)?; - /// - /// println!("Hello {}", name.trim_end()); - /// - /// Ok(()) - /// } - /// ``` - /// - /// The example can be run in two ways: - /// - /// - If you run this example by piping some text to it, e.g. `echo "foo" | path/to/executable` - /// it will print: `Hello foo`. - /// - If you instead run the example interactively by running the executable directly, it will - /// panic with the message "Expected input to be piped to the process". - /// - /// - /// [changes]: io#platform-specific-behavior - /// [`Stdin`]: crate::io::Stdin - #[stable(feature = "is_terminal", since = "1.70.0")] - fn is_terminal(&self) -> bool; -} - -macro_rules! impl_is_terminal { - ($($t:ty),*$(,)?) => {$( - #[unstable(feature = "sealed", issue = "none")] - impl crate::sealed::Sealed for $t {} - - #[stable(feature = "is_terminal", since = "1.70.0")] - impl IsTerminal for $t { - #[inline] - fn is_terminal(&self) -> bool { - crate::sys::io::is_terminal(self) - } - } - )*} -} - -impl_is_terminal!(File, Stdin, StdinLock<'_>, Stdout, StdoutLock<'_>, Stderr, StderrLock<'_>); - -#[unstable( - feature = "print_internals", - reason = "implementation detail which may disappear or be replaced at any time", - issue = "none" -)] -#[doc(hidden)] -#[cfg(not(test))] -pub fn _print(args: fmt::Arguments<'_>) { - print_to(args, stdout, "stdout"); -} - -#[unstable( - feature = "print_internals", - reason = "implementation detail which may disappear or be replaced at any time", - issue = "none" -)] -#[doc(hidden)] -#[cfg(not(test))] -pub fn _eprint(args: fmt::Arguments<'_>) { - print_to(args, stderr, "stderr"); -} - -#[cfg(test)] -pub use realstd::io::{_eprint, _print}; diff --git a/library/std/src/io/stdio/tests.rs b/library/std/src/io/stdio/tests.rs deleted file mode 100644 index f89fd27ce6c23..0000000000000 --- a/library/std/src/io/stdio/tests.rs +++ /dev/null @@ -1,166 +0,0 @@ -use super::*; -use crate::panic::{RefUnwindSafe, UnwindSafe}; -use crate::sync::mpsc::sync_channel; -use crate::thread; - -#[test] -fn stdout_unwind_safe() { - assert_unwind_safe::(); -} -#[test] -fn stdoutlock_unwind_safe() { - assert_unwind_safe::>(); - assert_unwind_safe::>(); -} -#[test] -fn stderr_unwind_safe() { - assert_unwind_safe::(); -} -#[test] -fn stderrlock_unwind_safe() { - assert_unwind_safe::>(); - assert_unwind_safe::>(); -} - -fn assert_unwind_safe() {} - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn panic_doesnt_poison() { - thread::spawn(|| { - let _a = stdin(); - let _a = _a.lock(); - let _a = stdout(); - let _a = _a.lock(); - let _a = stderr(); - let _a = _a.lock(); - panic!(); - }) - .join() - .unwrap_err(); - - let _a = stdin(); - let _a = _a.lock(); - let _a = stdout(); - let _a = _a.lock(); - let _a = stderr(); - let _a = _a.lock(); -} - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn test_lock_stderr() { - test_lock(stderr, || stderr().lock()); -} -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn test_lock_stdin() { - test_lock(stdin, || stdin().lock()); -} -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn test_lock_stdout() { - test_lock(stdout, || stdout().lock()); -} - -// Helper trait to make lock testing function generic. -trait Stdio<'a>: 'static -where - Self::Lock: 'a, -{ - type Lock; - fn lock(&'a self) -> Self::Lock; -} -impl<'a> Stdio<'a> for Stderr { - type Lock = StderrLock<'a>; - fn lock(&'a self) -> StderrLock<'a> { - self.lock() - } -} -impl<'a> Stdio<'a> for Stdin { - type Lock = StdinLock<'a>; - fn lock(&'a self) -> StdinLock<'a> { - self.lock() - } -} -impl<'a> Stdio<'a> for Stdout { - type Lock = StdoutLock<'a>; - fn lock(&'a self) -> StdoutLock<'a> { - self.lock() - } -} - -// Helper trait to make lock testing function generic. -trait StdioOwnedLock: 'static {} -impl StdioOwnedLock for StderrLock<'static> {} -impl StdioOwnedLock for StdinLock<'static> {} -impl StdioOwnedLock for StdoutLock<'static> {} - -// Tests locking on stdio handles by starting two threads and checking that -// they block each other appropriately. -fn test_lock(get_handle: fn() -> T, get_locked: fn() -> U) -where - T: for<'a> Stdio<'a>, - U: StdioOwnedLock, -{ - // State enum to track different phases of the test, primarily when - // each lock is acquired and released. - #[derive(Debug, PartialEq)] - enum State { - Start1, - Acquire1, - Start2, - Release1, - Acquire2, - Release2, - } - use State::*; - // Logging vector to be checked to make sure lock acquisitions and - // releases happened in the correct order. - let log = Arc::new(Mutex::new(Vec::new())); - let ((tx1, rx1), (tx2, rx2)) = (sync_channel(0), sync_channel(0)); - let th1 = { - let (log, tx) = (Arc::clone(&log), tx1); - thread::spawn(move || { - log.lock().unwrap().push(Start1); - let handle = get_handle(); - { - let locked = handle.lock(); - log.lock().unwrap().push(Acquire1); - tx.send(Acquire1).unwrap(); // notify of acquisition - tx.send(Release1).unwrap(); // wait for release command - log.lock().unwrap().push(Release1); - } - tx.send(Acquire1).unwrap(); // wait for th2 acquire - { - let locked = handle.lock(); - log.lock().unwrap().push(Acquire1); - } - log.lock().unwrap().push(Release1); - }) - }; - let th2 = { - let (log, tx) = (Arc::clone(&log), tx2); - thread::spawn(move || { - tx.send(Start2).unwrap(); // wait for start command - let locked = get_locked(); - log.lock().unwrap().push(Acquire2); - tx.send(Acquire2).unwrap(); // notify of acquisition - tx.send(Release2).unwrap(); // wait for release command - log.lock().unwrap().push(Release2); - }) - }; - assert_eq!(rx1.recv().unwrap(), Acquire1); // wait for th1 acquire - log.lock().unwrap().push(Start2); - assert_eq!(rx2.recv().unwrap(), Start2); // block th2 - assert_eq!(rx1.recv().unwrap(), Release1); // release th1 - assert_eq!(rx2.recv().unwrap(), Acquire2); // wait for th2 acquire - assert_eq!(rx1.recv().unwrap(), Acquire1); // block th1 - assert_eq!(rx2.recv().unwrap(), Release2); // release th2 - th2.join().unwrap(); - th1.join().unwrap(); - assert_eq!( - *log.lock().unwrap(), - [Start1, Acquire1, Start2, Release1, Acquire2, Release2, Acquire1, Release1] - ); -} diff --git a/library/std/src/io/tests.rs b/library/std/src/io/tests.rs deleted file mode 100644 index a2c1c430863ab..0000000000000 --- a/library/std/src/io/tests.rs +++ /dev/null @@ -1,747 +0,0 @@ -use super::{repeat, BorrowedBuf, Cursor, SeekFrom}; -use crate::cmp::{self, min}; -use crate::io::{self, IoSlice, IoSliceMut, DEFAULT_BUF_SIZE}; -use crate::io::{BufRead, BufReader, Read, Seek, Write}; -use crate::mem::MaybeUninit; -use crate::ops::Deref; - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn read_until() { - let mut buf = Cursor::new(&b"12"[..]); - let mut v = Vec::new(); - assert_eq!(buf.read_until(b'3', &mut v).unwrap(), 2); - assert_eq!(v, b"12"); - - let mut buf = Cursor::new(&b"1233"[..]); - let mut v = Vec::new(); - assert_eq!(buf.read_until(b'3', &mut v).unwrap(), 3); - assert_eq!(v, b"123"); - v.truncate(0); - assert_eq!(buf.read_until(b'3', &mut v).unwrap(), 1); - assert_eq!(v, b"3"); - v.truncate(0); - assert_eq!(buf.read_until(b'3', &mut v).unwrap(), 0); - assert_eq!(v, []); -} - -#[test] -fn skip_until() { - let bytes: &[u8] = b"read\0ignore\0read\0ignore\0read\0ignore\0"; - let mut reader = BufReader::new(bytes); - - // read from the bytes, alternating between - // consuming `read\0`s and skipping `ignore\0`s - loop { - // consume `read\0` - let mut out = Vec::new(); - let read = reader.read_until(0, &mut out).unwrap(); - if read == 0 { - // eof - break; - } else { - assert_eq!(out, b"read\0"); - assert_eq!(read, b"read\0".len()); - } - - // skip past `ignore\0` - let skipped = reader.skip_until(0).unwrap(); - assert_eq!(skipped, b"ignore\0".len()); - } - - // ensure we are at the end of the byte slice and that we can skip no further - // also ensure skip_until matches the behavior of read_until at EOF - let skipped = reader.skip_until(0).unwrap(); - assert_eq!(skipped, 0); -} - -#[test] -fn split() { - let buf = Cursor::new(&b"12"[..]); - let mut s = buf.split(b'3'); - assert_eq!(s.next().unwrap().unwrap(), vec![b'1', b'2']); - assert!(s.next().is_none()); - - let buf = Cursor::new(&b"1233"[..]); - let mut s = buf.split(b'3'); - assert_eq!(s.next().unwrap().unwrap(), vec![b'1', b'2']); - assert_eq!(s.next().unwrap().unwrap(), vec![]); - assert!(s.next().is_none()); -} - -#[test] -fn read_line() { - let mut buf = Cursor::new(&b"12"[..]); - let mut v = String::new(); - assert_eq!(buf.read_line(&mut v).unwrap(), 2); - assert_eq!(v, "12"); - - let mut buf = Cursor::new(&b"12\n\n"[..]); - let mut v = String::new(); - assert_eq!(buf.read_line(&mut v).unwrap(), 3); - assert_eq!(v, "12\n"); - v.truncate(0); - assert_eq!(buf.read_line(&mut v).unwrap(), 1); - assert_eq!(v, "\n"); - v.truncate(0); - assert_eq!(buf.read_line(&mut v).unwrap(), 0); - assert_eq!(v, ""); -} - -#[test] -fn lines() { - let buf = Cursor::new(&b"12\r"[..]); - let mut s = buf.lines(); - assert_eq!(s.next().unwrap().unwrap(), "12\r".to_string()); - assert!(s.next().is_none()); - - let buf = Cursor::new(&b"12\r\n\n"[..]); - let mut s = buf.lines(); - assert_eq!(s.next().unwrap().unwrap(), "12".to_string()); - assert_eq!(s.next().unwrap().unwrap(), "".to_string()); - assert!(s.next().is_none()); -} - -#[test] -fn buf_read_has_data_left() { - let mut buf = Cursor::new(&b"abcd"[..]); - assert!(buf.has_data_left().unwrap()); - buf.read_exact(&mut [0; 2]).unwrap(); - assert!(buf.has_data_left().unwrap()); - buf.read_exact(&mut [0; 2]).unwrap(); - assert!(!buf.has_data_left().unwrap()); -} - -#[test] -fn read_to_end() { - let mut c = Cursor::new(&b""[..]); - let mut v = Vec::new(); - assert_eq!(c.read_to_end(&mut v).unwrap(), 0); - assert_eq!(v, []); - - let mut c = Cursor::new(&b"1"[..]); - let mut v = Vec::new(); - assert_eq!(c.read_to_end(&mut v).unwrap(), 1); - assert_eq!(v, b"1"); - - let cap = if cfg!(miri) { 1024 } else { 1024 * 1024 }; - let data = (0..cap).map(|i| (i / 3) as u8).collect::>(); - let mut v = Vec::new(); - let (a, b) = data.split_at(data.len() / 2); - assert_eq!(Cursor::new(a).read_to_end(&mut v).unwrap(), a.len()); - assert_eq!(Cursor::new(b).read_to_end(&mut v).unwrap(), b.len()); - assert_eq!(v, data); -} - -#[test] -fn read_to_string() { - let mut c = Cursor::new(&b""[..]); - let mut v = String::new(); - assert_eq!(c.read_to_string(&mut v).unwrap(), 0); - assert_eq!(v, ""); - - let mut c = Cursor::new(&b"1"[..]); - let mut v = String::new(); - assert_eq!(c.read_to_string(&mut v).unwrap(), 1); - assert_eq!(v, "1"); - - let mut c = Cursor::new(&b"\xff"[..]); - let mut v = String::new(); - assert!(c.read_to_string(&mut v).is_err()); -} - -#[test] -fn read_exact() { - let mut buf = [0; 4]; - - let mut c = Cursor::new(&b""[..]); - assert_eq!(c.read_exact(&mut buf).unwrap_err().kind(), io::ErrorKind::UnexpectedEof); - - let mut c = Cursor::new(&b"123"[..]).chain(Cursor::new(&b"456789"[..])); - c.read_exact(&mut buf).unwrap(); - assert_eq!(&buf, b"1234"); - c.read_exact(&mut buf).unwrap(); - assert_eq!(&buf, b"5678"); - assert_eq!(c.read_exact(&mut buf).unwrap_err().kind(), io::ErrorKind::UnexpectedEof); -} - -#[test] -fn read_exact_slice() { - let mut buf = [0; 4]; - - let mut c = &b""[..]; - assert_eq!(c.read_exact(&mut buf).unwrap_err().kind(), io::ErrorKind::UnexpectedEof); - - let mut c = &b"123"[..]; - assert_eq!(c.read_exact(&mut buf).unwrap_err().kind(), io::ErrorKind::UnexpectedEof); - // make sure the optimized (early returning) method is being used - assert_eq!(&buf, &[0; 4]); - - let mut c = &b"1234"[..]; - c.read_exact(&mut buf).unwrap(); - assert_eq!(&buf, b"1234"); - - let mut c = &b"56789"[..]; - c.read_exact(&mut buf).unwrap(); - assert_eq!(&buf, b"5678"); - assert_eq!(c, b"9"); -} - -#[test] -fn read_buf_exact() { - let buf: &mut [_] = &mut [0; 4]; - let mut buf: BorrowedBuf<'_> = buf.into(); - - let mut c = Cursor::new(&b""[..]); - assert_eq!(c.read_buf_exact(buf.unfilled()).unwrap_err().kind(), io::ErrorKind::UnexpectedEof); - - let mut c = Cursor::new(&b"123456789"[..]); - c.read_buf_exact(buf.unfilled()).unwrap(); - assert_eq!(buf.filled(), b"1234"); - - buf.clear(); - - c.read_buf_exact(buf.unfilled()).unwrap(); - assert_eq!(buf.filled(), b"5678"); - - buf.clear(); - - assert_eq!(c.read_buf_exact(buf.unfilled()).unwrap_err().kind(), io::ErrorKind::UnexpectedEof); -} - -#[test] -#[should_panic] -fn borrowed_cursor_advance_overflow() { - let mut buf = [0; 512]; - let mut buf = BorrowedBuf::from(&mut buf[..]); - buf.unfilled().advance(1); - buf.unfilled().advance(usize::MAX); -} - -#[test] -fn take_eof() { - struct R; - - impl Read for R { - fn read(&mut self, _: &mut [u8]) -> io::Result { - Err(io::const_io_error!(io::ErrorKind::Other, "")) - } - } - impl BufRead for R { - fn fill_buf(&mut self) -> io::Result<&[u8]> { - Err(io::const_io_error!(io::ErrorKind::Other, "")) - } - fn consume(&mut self, _amt: usize) {} - } - - let mut buf = [0; 1]; - assert_eq!(0, R.take(0).read(&mut buf).unwrap()); - assert_eq!(b"", R.take(0).fill_buf().unwrap()); -} - -fn cmp_bufread(mut br1: Br1, mut br2: Br2, exp: &[u8]) { - let mut cat = Vec::new(); - loop { - let consume = { - let buf1 = br1.fill_buf().unwrap(); - let buf2 = br2.fill_buf().unwrap(); - let minlen = if buf1.len() < buf2.len() { buf1.len() } else { buf2.len() }; - assert_eq!(buf1[..minlen], buf2[..minlen]); - cat.extend_from_slice(&buf1[..minlen]); - minlen - }; - if consume == 0 { - break; - } - br1.consume(consume); - br2.consume(consume); - } - assert_eq!(br1.fill_buf().unwrap().len(), 0); - assert_eq!(br2.fill_buf().unwrap().len(), 0); - assert_eq!(&cat[..], &exp[..]) -} - -#[test] -fn chain_bufread() { - let testdata = b"ABCDEFGHIJKL"; - let chain1 = - (&testdata[..3]).chain(&testdata[3..6]).chain(&testdata[6..9]).chain(&testdata[9..]); - let chain2 = (&testdata[..4]).chain(&testdata[4..8]).chain(&testdata[8..]); - cmp_bufread(chain1, chain2, &testdata[..]); -} - -#[test] -fn chain_splitted_char() { - let chain = b"\xc3".chain(b"\xa9".as_slice()); - assert_eq!(crate::io::read_to_string(chain).unwrap(), "é"); - - let mut chain = b"\xc3".chain(b"\xa9\n".as_slice()); - let mut buf = String::new(); - assert_eq!(chain.read_line(&mut buf).unwrap(), 3); - assert_eq!(buf, "é\n"); -} - -#[test] -fn bufreader_size_hint() { - let testdata = b"ABCDEFGHIJKL"; - let mut buf_reader = BufReader::new(&testdata[..]); - assert_eq!(buf_reader.buffer().len(), 0); - - let buffer_length = testdata.len(); - buf_reader.fill_buf().unwrap(); - - // Check that size hint matches buffer contents - let mut buffered_bytes = buf_reader.bytes(); - let (lower_bound, _upper_bound) = buffered_bytes.size_hint(); - assert_eq!(lower_bound, buffer_length); - - // Check that size hint matches buffer contents after advancing - buffered_bytes.next().unwrap().unwrap(); - let (lower_bound, _upper_bound) = buffered_bytes.size_hint(); - assert_eq!(lower_bound, buffer_length - 1); -} - -#[test] -fn empty_size_hint() { - let size_hint = io::empty().bytes().size_hint(); - assert_eq!(size_hint, (0, Some(0))); -} - -#[test] -fn slice_size_hint() { - let size_hint = (&[1, 2, 3]).bytes().size_hint(); - assert_eq!(size_hint, (3, Some(3))); -} - -#[test] -fn take_size_hint() { - let size_hint = (&[1, 2, 3]).take(2).bytes().size_hint(); - assert_eq!(size_hint, (2, Some(2))); - - let size_hint = (&[1, 2, 3]).take(4).bytes().size_hint(); - assert_eq!(size_hint, (3, Some(3))); - - let size_hint = io::repeat(0).take(3).bytes().size_hint(); - assert_eq!(size_hint, (3, Some(3))); -} - -#[test] -fn chain_empty_size_hint() { - let chain = io::empty().chain(io::empty()); - let size_hint = chain.bytes().size_hint(); - assert_eq!(size_hint, (0, Some(0))); -} - -#[test] -fn chain_size_hint() { - let testdata = b"ABCDEFGHIJKL"; - let mut buf_reader_1 = BufReader::new(&testdata[..6]); - let mut buf_reader_2 = BufReader::new(&testdata[6..]); - - buf_reader_1.fill_buf().unwrap(); - buf_reader_2.fill_buf().unwrap(); - - let chain = buf_reader_1.chain(buf_reader_2); - let size_hint = chain.bytes().size_hint(); - assert_eq!(size_hint, (testdata.len(), Some(testdata.len()))); -} - -#[test] -fn chain_zero_length_read_is_not_eof() { - let a = b"A"; - let b = b"B"; - let mut s = String::new(); - let mut chain = (&a[..]).chain(&b[..]); - chain.read(&mut []).unwrap(); - chain.read_to_string(&mut s).unwrap(); - assert_eq!("AB", s); -} - -#[bench] -#[cfg_attr(target_os = "emscripten", ignore)] -#[cfg_attr(miri, ignore)] // Miri isn't fast... -fn bench_read_to_end(b: &mut test::Bencher) { - b.iter(|| { - let mut lr = repeat(1).take(10000000); - let mut vec = Vec::with_capacity(1024); - super::default_read_to_end(&mut lr, &mut vec, None) - }); -} - -#[test] -fn seek_len() -> io::Result<()> { - let mut c = Cursor::new(vec![0; 15]); - assert_eq!(c.stream_len()?, 15); - - c.seek(SeekFrom::End(0))?; - let old_pos = c.stream_position()?; - assert_eq!(c.stream_len()?, 15); - assert_eq!(c.stream_position()?, old_pos); - - c.seek(SeekFrom::Start(7))?; - c.seek(SeekFrom::Current(2))?; - let old_pos = c.stream_position()?; - assert_eq!(c.stream_len()?, 15); - assert_eq!(c.stream_position()?, old_pos); - - Ok(()) -} - -#[test] -fn seek_position() -> io::Result<()> { - // All `asserts` are duplicated here to make sure the method does not - // change anything about the seek state. - let mut c = Cursor::new(vec![0; 15]); - assert_eq!(c.stream_position()?, 0); - assert_eq!(c.stream_position()?, 0); - - c.seek(SeekFrom::End(0))?; - assert_eq!(c.stream_position()?, 15); - assert_eq!(c.stream_position()?, 15); - - c.seek(SeekFrom::Start(7))?; - c.seek(SeekFrom::Current(2))?; - assert_eq!(c.stream_position()?, 9); - assert_eq!(c.stream_position()?, 9); - - c.seek(SeekFrom::End(-3))?; - c.seek(SeekFrom::Current(1))?; - c.seek(SeekFrom::Current(-5))?; - assert_eq!(c.stream_position()?, 8); - assert_eq!(c.stream_position()?, 8); - - c.rewind()?; - assert_eq!(c.stream_position()?, 0); - assert_eq!(c.stream_position()?, 0); - - Ok(()) -} - -// A simple example reader which uses the default implementation of -// read_to_end. -struct ExampleSliceReader<'a> { - slice: &'a [u8], -} - -impl<'a> Read for ExampleSliceReader<'a> { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - let len = cmp::min(self.slice.len(), buf.len()); - buf[..len].copy_from_slice(&self.slice[..len]); - self.slice = &self.slice[len..]; - Ok(len) - } -} - -#[test] -fn test_read_to_end_capacity() -> io::Result<()> { - let input = &b"foo"[..]; - - // read_to_end() takes care not to over-allocate when a buffer is the - // exact size needed. - let mut vec1 = Vec::with_capacity(input.len()); - ExampleSliceReader { slice: input }.read_to_end(&mut vec1)?; - assert_eq!(vec1.len(), input.len()); - assert_eq!(vec1.capacity(), input.len(), "did not allocate more"); - - Ok(()) -} - -#[test] -fn io_slice_mut_advance_slices() { - let mut buf1 = [1; 8]; - let mut buf2 = [2; 16]; - let mut buf3 = [3; 8]; - let mut bufs = &mut [ - IoSliceMut::new(&mut buf1), - IoSliceMut::new(&mut buf2), - IoSliceMut::new(&mut buf3), - ][..]; - - // Only in a single buffer.. - IoSliceMut::advance_slices(&mut bufs, 1); - assert_eq!(bufs[0].deref(), [1; 7].as_ref()); - assert_eq!(bufs[1].deref(), [2; 16].as_ref()); - assert_eq!(bufs[2].deref(), [3; 8].as_ref()); - - // Removing a buffer, leaving others as is. - IoSliceMut::advance_slices(&mut bufs, 7); - assert_eq!(bufs[0].deref(), [2; 16].as_ref()); - assert_eq!(bufs[1].deref(), [3; 8].as_ref()); - - // Removing a buffer and removing from the next buffer. - IoSliceMut::advance_slices(&mut bufs, 18); - assert_eq!(bufs[0].deref(), [3; 6].as_ref()); -} - -#[test] -#[should_panic] -fn io_slice_mut_advance_slices_empty_slice() { - let mut empty_bufs = &mut [][..]; - IoSliceMut::advance_slices(&mut empty_bufs, 1); -} - -#[test] -#[should_panic] -fn io_slice_mut_advance_slices_beyond_total_length() { - let mut buf1 = [1; 8]; - let mut bufs = &mut [IoSliceMut::new(&mut buf1)][..]; - - IoSliceMut::advance_slices(&mut bufs, 9); - assert!(bufs.is_empty()); -} - -#[test] -fn io_slice_advance_slices() { - let buf1 = [1; 8]; - let buf2 = [2; 16]; - let buf3 = [3; 8]; - let mut bufs = &mut [IoSlice::new(&buf1), IoSlice::new(&buf2), IoSlice::new(&buf3)][..]; - - // Only in a single buffer.. - IoSlice::advance_slices(&mut bufs, 1); - assert_eq!(bufs[0].deref(), [1; 7].as_ref()); - assert_eq!(bufs[1].deref(), [2; 16].as_ref()); - assert_eq!(bufs[2].deref(), [3; 8].as_ref()); - - // Removing a buffer, leaving others as is. - IoSlice::advance_slices(&mut bufs, 7); - assert_eq!(bufs[0].deref(), [2; 16].as_ref()); - assert_eq!(bufs[1].deref(), [3; 8].as_ref()); - - // Removing a buffer and removing from the next buffer. - IoSlice::advance_slices(&mut bufs, 18); - assert_eq!(bufs[0].deref(), [3; 6].as_ref()); -} - -#[test] -#[should_panic] -fn io_slice_advance_slices_empty_slice() { - let mut empty_bufs = &mut [][..]; - IoSlice::advance_slices(&mut empty_bufs, 1); -} - -#[test] -#[should_panic] -fn io_slice_advance_slices_beyond_total_length() { - let buf1 = [1; 8]; - let mut bufs = &mut [IoSlice::new(&buf1)][..]; - - IoSlice::advance_slices(&mut bufs, 9); - assert!(bufs.is_empty()); -} - -/// Create a new writer that reads from at most `n_bufs` and reads -/// `per_call` bytes (in total) per call to write. -fn test_writer(n_bufs: usize, per_call: usize) -> TestWriter { - TestWriter { n_bufs, per_call, written: Vec::new() } -} - -struct TestWriter { - n_bufs: usize, - per_call: usize, - written: Vec, -} - -impl Write for TestWriter { - fn write(&mut self, buf: &[u8]) -> io::Result { - self.write_vectored(&[IoSlice::new(buf)]) - } - - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - let mut left = self.per_call; - let mut written = 0; - for buf in bufs.iter().take(self.n_bufs) { - let n = min(left, buf.len()); - self.written.extend_from_slice(&buf[0..n]); - left -= n; - written += n; - } - Ok(written) - } - - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -#[test] -fn test_writer_read_from_one_buf() { - let mut writer = test_writer(1, 2); - - assert_eq!(writer.write(&[]).unwrap(), 0); - assert_eq!(writer.write_vectored(&[]).unwrap(), 0); - - // Read at most 2 bytes. - assert_eq!(writer.write(&[1, 1, 1]).unwrap(), 2); - let bufs = &[IoSlice::new(&[2, 2, 2])]; - assert_eq!(writer.write_vectored(bufs).unwrap(), 2); - - // Only read from first buf. - let bufs = &[IoSlice::new(&[3]), IoSlice::new(&[4, 4])]; - assert_eq!(writer.write_vectored(bufs).unwrap(), 1); - - assert_eq!(writer.written, &[1, 1, 2, 2, 3]); -} - -#[test] -fn test_writer_read_from_multiple_bufs() { - let mut writer = test_writer(3, 3); - - // Read at most 3 bytes from two buffers. - let bufs = &[IoSlice::new(&[1]), IoSlice::new(&[2, 2, 2])]; - assert_eq!(writer.write_vectored(bufs).unwrap(), 3); - - // Read at most 3 bytes from three buffers. - let bufs = &[IoSlice::new(&[3]), IoSlice::new(&[4]), IoSlice::new(&[5, 5])]; - assert_eq!(writer.write_vectored(bufs).unwrap(), 3); - - assert_eq!(writer.written, &[1, 2, 2, 3, 4, 5]); -} - -#[test] -fn test_write_all_vectored() { - #[rustfmt::skip] // Becomes unreadable otherwise. - let tests: Vec<(_, &'static [u8])> = vec![ - (vec![], &[]), - (vec![IoSlice::new(&[]), IoSlice::new(&[])], &[]), - (vec![IoSlice::new(&[1])], &[1]), - (vec![IoSlice::new(&[1, 2])], &[1, 2]), - (vec![IoSlice::new(&[1, 2, 3])], &[1, 2, 3]), - (vec![IoSlice::new(&[1, 2, 3, 4])], &[1, 2, 3, 4]), - (vec![IoSlice::new(&[1, 2, 3, 4, 5])], &[1, 2, 3, 4, 5]), - (vec![IoSlice::new(&[1]), IoSlice::new(&[2])], &[1, 2]), - (vec![IoSlice::new(&[1]), IoSlice::new(&[2, 2])], &[1, 2, 2]), - (vec![IoSlice::new(&[1, 1]), IoSlice::new(&[2, 2])], &[1, 1, 2, 2]), - (vec![IoSlice::new(&[1, 1]), IoSlice::new(&[2, 2, 2])], &[1, 1, 2, 2, 2]), - (vec![IoSlice::new(&[1, 1]), IoSlice::new(&[2, 2, 2])], &[1, 1, 2, 2, 2]), - (vec![IoSlice::new(&[1, 1, 1]), IoSlice::new(&[2, 2, 2])], &[1, 1, 1, 2, 2, 2]), - (vec![IoSlice::new(&[1, 1, 1]), IoSlice::new(&[2, 2, 2, 2])], &[1, 1, 1, 2, 2, 2, 2]), - (vec![IoSlice::new(&[1, 1, 1, 1]), IoSlice::new(&[2, 2, 2, 2])], &[1, 1, 1, 1, 2, 2, 2, 2]), - (vec![IoSlice::new(&[1]), IoSlice::new(&[2]), IoSlice::new(&[3])], &[1, 2, 3]), - (vec![IoSlice::new(&[1, 1]), IoSlice::new(&[2, 2]), IoSlice::new(&[3, 3])], &[1, 1, 2, 2, 3, 3]), - (vec![IoSlice::new(&[1]), IoSlice::new(&[2, 2]), IoSlice::new(&[3, 3, 3])], &[1, 2, 2, 3, 3, 3]), - (vec![IoSlice::new(&[1, 1, 1]), IoSlice::new(&[2, 2, 2]), IoSlice::new(&[3, 3, 3])], &[1, 1, 1, 2, 2, 2, 3, 3, 3]), - ]; - - let writer_configs = &[(1, 1), (1, 2), (1, 3), (2, 2), (2, 3), (3, 3)]; - - for (n_bufs, per_call) in writer_configs.iter().copied() { - for (mut input, wanted) in tests.clone().into_iter() { - let mut writer = test_writer(n_bufs, per_call); - assert!(writer.write_all_vectored(&mut *input).is_ok()); - assert_eq!(&*writer.written, &*wanted); - } - } -} - -// Issue 94981 -#[test] -#[should_panic = "number of read bytes exceeds limit"] -fn test_take_wrong_length() { - struct LieAboutSize(bool); - - impl Read for LieAboutSize { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - // Lie about the read size at first time of read. - if core::mem::take(&mut self.0) { Ok(buf.len() + 1) } else { Ok(buf.len()) } - } - } - - let mut buffer = vec![0; 4]; - let mut reader = LieAboutSize(true).take(4); - // Primed the `Limit` by lying about the read size. - let _ = reader.read(&mut buffer[..]); -} - -#[test] -fn slice_read_exact_eof() { - let slice = &b"123456"[..]; - - let mut r = slice; - assert!(r.read_exact(&mut [0; 10]).is_err()); - assert!(r.is_empty()); - - let mut r = slice; - let buf = &mut [0; 10]; - let mut buf = BorrowedBuf::from(buf.as_mut_slice()); - assert!(r.read_buf_exact(buf.unfilled()).is_err()); - assert!(r.is_empty()); - assert_eq!(buf.filled(), b"123456"); -} - -#[test] -fn cursor_read_exact_eof() { - let slice = Cursor::new(b"123456"); - - let mut r = slice.clone(); - assert!(r.read_exact(&mut [0; 10]).is_err()); - assert!(r.is_empty()); - - let mut r = slice; - let buf = &mut [0; 10]; - let mut buf = BorrowedBuf::from(buf.as_mut_slice()); - assert!(r.read_buf_exact(buf.unfilled()).is_err()); - assert!(r.is_empty()); - assert_eq!(buf.filled(), b"123456"); -} - -#[bench] -fn bench_take_read(b: &mut test::Bencher) { - b.iter(|| { - let mut buf = [0; 64]; - - [255; 128].take(64).read(&mut buf).unwrap(); - }); -} - -#[bench] -fn bench_take_read_buf(b: &mut test::Bencher) { - b.iter(|| { - let buf: &mut [_] = &mut [MaybeUninit::uninit(); 64]; - - let mut buf: BorrowedBuf<'_> = buf.into(); - - [255; 128].take(64).read_buf(buf.unfilled()).unwrap(); - }); -} - -// Issue #120603 -#[test] -#[should_panic] -fn read_buf_broken_read() { - struct MalformedRead; - - impl Read for MalformedRead { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - // broken length calculation - Ok(buf.len() + 1) - } - } - - let _ = BufReader::new(MalformedRead).fill_buf(); -} - -#[test] -fn read_buf_full_read() { - struct FullRead; - - impl Read for FullRead { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - Ok(buf.len()) - } - } - - assert_eq!(BufReader::new(FullRead).fill_buf().unwrap().len(), DEFAULT_BUF_SIZE); -} - -#[test] -// Miri does not support signalling OOM -#[cfg_attr(miri, ignore)] -// 64-bit only to be sure the allocator will fail fast on an impossible to satsify size -#[cfg(target_pointer_width = "64")] -fn try_oom_error() { - let mut v = Vec::::new(); - let reserve_err = v.try_reserve(isize::MAX as usize - 1).unwrap_err(); - let io_err = io::Error::from(reserve_err); - assert_eq!(io::ErrorKind::OutOfMemory, io_err.kind()); -} diff --git a/library/std/src/io/util.rs b/library/std/src/io/util.rs deleted file mode 100644 index b4c4dffc371c1..0000000000000 --- a/library/std/src/io/util.rs +++ /dev/null @@ -1,330 +0,0 @@ -#![allow(missing_copy_implementations)] - -#[cfg(test)] -mod tests; - -use crate::fmt; -use crate::io::{ - self, BorrowedCursor, BufRead, IoSlice, IoSliceMut, Read, Seek, SeekFrom, SizeHint, Write, -}; - -/// `Empty` ignores any data written via [`Write`], and will always be empty -/// (returning zero bytes) when read via [`Read`]. -/// -/// This struct is generally created by calling [`empty()`]. Please -/// see the documentation of [`empty()`] for more details. -#[stable(feature = "rust1", since = "1.0.0")] -#[non_exhaustive] -#[derive(Copy, Clone, Debug, Default)] -pub struct Empty; - -/// Creates a value that is always at EOF for reads, and ignores all data written. -/// -/// All calls to [`write`] on the returned instance will return [`Ok(buf.len())`] -/// and the contents of the buffer will not be inspected. -/// -/// All calls to [`read`] from the returned reader will return [`Ok(0)`]. -/// -/// [`Ok(buf.len())`]: Ok -/// [`Ok(0)`]: Ok -/// -/// [`write`]: Write::write -/// [`read`]: Read::read -/// -/// # Examples -/// -/// ```rust -/// use std::io::{self, Write}; -/// -/// let buffer = vec![1, 2, 3, 5, 8]; -/// let num_bytes = io::empty().write(&buffer).unwrap(); -/// assert_eq!(num_bytes, 5); -/// ``` -/// -/// -/// ```rust -/// use std::io::{self, Read}; -/// -/// let mut buffer = String::new(); -/// io::empty().read_to_string(&mut buffer).unwrap(); -/// assert!(buffer.is_empty()); -/// ``` -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_const_stable(feature = "const_io_structs", since = "1.79.0")] -pub const fn empty() -> Empty { - Empty -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Read for Empty { - #[inline] - fn read(&mut self, _buf: &mut [u8]) -> io::Result { - Ok(0) - } - - #[inline] - fn read_buf(&mut self, _cursor: BorrowedCursor<'_>) -> io::Result<()> { - Ok(()) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl BufRead for Empty { - #[inline] - fn fill_buf(&mut self) -> io::Result<&[u8]> { - Ok(&[]) - } - #[inline] - fn consume(&mut self, _n: usize) {} -} - -#[stable(feature = "empty_seek", since = "1.51.0")] -impl Seek for Empty { - fn seek(&mut self, _pos: SeekFrom) -> io::Result { - Ok(0) - } - - fn stream_len(&mut self) -> io::Result { - Ok(0) - } - - fn stream_position(&mut self) -> io::Result { - Ok(0) - } -} - -impl SizeHint for Empty { - #[inline] - fn upper_bound(&self) -> Option { - Some(0) - } -} - -#[stable(feature = "empty_write", since = "1.73.0")] -impl Write for Empty { - #[inline] - fn write(&mut self, buf: &[u8]) -> io::Result { - Ok(buf.len()) - } - - #[inline] - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - let total_len = bufs.iter().map(|b| b.len()).sum(); - Ok(total_len) - } - - #[inline] - fn is_write_vectored(&self) -> bool { - true - } - - #[inline] - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -#[stable(feature = "empty_write", since = "1.73.0")] -impl Write for &Empty { - #[inline] - fn write(&mut self, buf: &[u8]) -> io::Result { - Ok(buf.len()) - } - - #[inline] - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - let total_len = bufs.iter().map(|b| b.len()).sum(); - Ok(total_len) - } - - #[inline] - fn is_write_vectored(&self) -> bool { - true - } - - #[inline] - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -/// A reader which yields one byte over and over and over and over and over and... -/// -/// This struct is generally created by calling [`repeat()`]. Please -/// see the documentation of [`repeat()`] for more details. -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Repeat { - byte: u8, -} - -/// Creates an instance of a reader that infinitely repeats one byte. -/// -/// All reads from this reader will succeed by filling the specified buffer with -/// the given byte. -/// -/// # Examples -/// -/// ``` -/// use std::io::{self, Read}; -/// -/// let mut buffer = [0; 3]; -/// io::repeat(0b101).read_exact(&mut buffer).unwrap(); -/// assert_eq!(buffer, [0b101, 0b101, 0b101]); -/// ``` -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_const_stable(feature = "const_io_structs", since = "1.79.0")] -pub const fn repeat(byte: u8) -> Repeat { - Repeat { byte } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Read for Repeat { - #[inline] - fn read(&mut self, buf: &mut [u8]) -> io::Result { - for slot in &mut *buf { - *slot = self.byte; - } - Ok(buf.len()) - } - - fn read_buf(&mut self, mut buf: BorrowedCursor<'_>) -> io::Result<()> { - // SAFETY: No uninit bytes are being written - for slot in unsafe { buf.as_mut() } { - slot.write(self.byte); - } - - let remaining = buf.capacity(); - - // SAFETY: the entire unfilled portion of buf has been initialized - unsafe { - buf.advance_unchecked(remaining); - } - - Ok(()) - } - - /// This function is not supported by `io::Repeat`, because there's no end of its data - fn read_to_end(&mut self, _: &mut Vec) -> io::Result { - Err(io::Error::from(io::ErrorKind::OutOfMemory)) - } - - /// This function is not supported by `io::Repeat`, because there's no end of its data - fn read_to_string(&mut self, _: &mut String) -> io::Result { - Err(io::Error::from(io::ErrorKind::OutOfMemory)) - } - - #[inline] - fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - let mut nwritten = 0; - for buf in bufs { - nwritten += self.read(buf)?; - } - Ok(nwritten) - } - - #[inline] - fn is_read_vectored(&self) -> bool { - true - } -} - -impl SizeHint for Repeat { - #[inline] - fn lower_bound(&self) -> usize { - usize::MAX - } - - #[inline] - fn upper_bound(&self) -> Option { - None - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for Repeat { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Repeat").finish_non_exhaustive() - } -} - -/// A writer which will move data into the void. -/// -/// This struct is generally created by calling [`sink()`]. Please -/// see the documentation of [`sink()`] for more details. -#[stable(feature = "rust1", since = "1.0.0")] -#[non_exhaustive] -#[derive(Copy, Clone, Debug, Default)] -pub struct Sink; - -/// Creates an instance of a writer which will successfully consume all data. -/// -/// All calls to [`write`] on the returned instance will return [`Ok(buf.len())`] -/// and the contents of the buffer will not be inspected. -/// -/// [`write`]: Write::write -/// [`Ok(buf.len())`]: Ok -/// -/// # Examples -/// -/// ```rust -/// use std::io::{self, Write}; -/// -/// let buffer = vec![1, 2, 3, 5, 8]; -/// let num_bytes = io::sink().write(&buffer).unwrap(); -/// assert_eq!(num_bytes, 5); -/// ``` -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_const_stable(feature = "const_io_structs", since = "1.79.0")] -pub const fn sink() -> Sink { - Sink -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Write for Sink { - #[inline] - fn write(&mut self, buf: &[u8]) -> io::Result { - Ok(buf.len()) - } - - #[inline] - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - let total_len = bufs.iter().map(|b| b.len()).sum(); - Ok(total_len) - } - - #[inline] - fn is_write_vectored(&self) -> bool { - true - } - - #[inline] - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -#[stable(feature = "write_mt", since = "1.48.0")] -impl Write for &Sink { - #[inline] - fn write(&mut self, buf: &[u8]) -> io::Result { - Ok(buf.len()) - } - - #[inline] - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - let total_len = bufs.iter().map(|b| b.len()).sum(); - Ok(total_len) - } - - #[inline] - fn is_write_vectored(&self) -> bool { - true - } - - #[inline] - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} diff --git a/library/std/src/io/util/tests.rs b/library/std/src/io/util/tests.rs deleted file mode 100644 index 6de91e29c7707..0000000000000 --- a/library/std/src/io/util/tests.rs +++ /dev/null @@ -1,97 +0,0 @@ -use crate::io::prelude::*; -use crate::io::{empty, repeat, sink, BorrowedBuf, Empty, Repeat, SeekFrom, Sink}; - -use crate::mem::MaybeUninit; - -#[test] -fn sink_sinks() { - let mut s = sink(); - assert_eq!(s.write(&[]).unwrap(), 0); - assert_eq!(s.write(&[0]).unwrap(), 1); - assert_eq!(s.write(&[0; 1024]).unwrap(), 1024); - assert_eq!(s.by_ref().write(&[0; 1024]).unwrap(), 1024); -} - -#[test] -fn empty_reads() { - let mut e = empty(); - assert_eq!(e.read(&mut []).unwrap(), 0); - assert_eq!(e.read(&mut [0]).unwrap(), 0); - assert_eq!(e.read(&mut [0; 1024]).unwrap(), 0); - assert_eq!(Read::by_ref(&mut e).read(&mut [0; 1024]).unwrap(), 0); - - let buf: &mut [MaybeUninit<_>] = &mut []; - let mut buf: BorrowedBuf<'_> = buf.into(); - e.read_buf(buf.unfilled()).unwrap(); - assert_eq!(buf.len(), 0); - assert_eq!(buf.init_len(), 0); - - let buf: &mut [_] = &mut [MaybeUninit::uninit()]; - let mut buf: BorrowedBuf<'_> = buf.into(); - e.read_buf(buf.unfilled()).unwrap(); - assert_eq!(buf.len(), 0); - assert_eq!(buf.init_len(), 0); - - let buf: &mut [_] = &mut [MaybeUninit::uninit(); 1024]; - let mut buf: BorrowedBuf<'_> = buf.into(); - e.read_buf(buf.unfilled()).unwrap(); - assert_eq!(buf.len(), 0); - assert_eq!(buf.init_len(), 0); - - let buf: &mut [_] = &mut [MaybeUninit::uninit(); 1024]; - let mut buf: BorrowedBuf<'_> = buf.into(); - Read::by_ref(&mut e).read_buf(buf.unfilled()).unwrap(); - assert_eq!(buf.len(), 0); - assert_eq!(buf.init_len(), 0); -} - -#[test] -fn empty_seeks() { - let mut e = empty(); - assert!(matches!(e.seek(SeekFrom::Start(0)), Ok(0))); - assert!(matches!(e.seek(SeekFrom::Start(1)), Ok(0))); - assert!(matches!(e.seek(SeekFrom::Start(u64::MAX)), Ok(0))); - - assert!(matches!(e.seek(SeekFrom::End(i64::MIN)), Ok(0))); - assert!(matches!(e.seek(SeekFrom::End(-1)), Ok(0))); - assert!(matches!(e.seek(SeekFrom::End(0)), Ok(0))); - assert!(matches!(e.seek(SeekFrom::End(1)), Ok(0))); - assert!(matches!(e.seek(SeekFrom::End(i64::MAX)), Ok(0))); - - assert!(matches!(e.seek(SeekFrom::Current(i64::MIN)), Ok(0))); - assert!(matches!(e.seek(SeekFrom::Current(-1)), Ok(0))); - assert!(matches!(e.seek(SeekFrom::Current(0)), Ok(0))); - assert!(matches!(e.seek(SeekFrom::Current(1)), Ok(0))); - assert!(matches!(e.seek(SeekFrom::Current(i64::MAX)), Ok(0))); -} - -#[test] -fn empty_sinks() { - let mut e = empty(); - assert_eq!(e.write(&[]).unwrap(), 0); - assert_eq!(e.write(&[0]).unwrap(), 1); - assert_eq!(e.write(&[0; 1024]).unwrap(), 1024); - assert_eq!(Write::by_ref(&mut e).write(&[0; 1024]).unwrap(), 1024); -} - -#[test] -fn repeat_repeats() { - let mut r = repeat(4); - let mut b = [0; 1024]; - assert_eq!(r.read(&mut b).unwrap(), 1024); - assert!(b.iter().all(|b| *b == 4)); -} - -#[test] -fn take_some_bytes() { - assert_eq!(repeat(4).take(100).bytes().count(), 100); - assert_eq!(repeat(4).take(100).bytes().next().unwrap().unwrap(), 4); - assert_eq!(repeat(1).take(10).chain(repeat(2).take(10)).bytes().count(), 20); -} - -#[allow(dead_code)] -fn const_utils() { - const _: Empty = empty(); - const _: Repeat = repeat(b'c'); - const _: Sink = sink(); -} diff --git a/library/std/src/keyword_docs.rs b/library/std/src/keyword_docs.rs deleted file mode 100644 index 8415f36eba251..0000000000000 --- a/library/std/src/keyword_docs.rs +++ /dev/null @@ -1,2459 +0,0 @@ -#[doc(keyword = "as")] -// -/// Cast between types, or rename an import. -/// -/// `as` is most commonly used to turn primitive types into other primitive types, but it has other -/// uses that include turning pointers into addresses, addresses into pointers, and pointers into -/// other pointers. -/// -/// ```rust -/// let thing1: u8 = 89.0 as u8; -/// assert_eq!('B' as u32, 66); -/// assert_eq!(thing1 as char, 'Y'); -/// let thing2: f32 = thing1 as f32 + 10.5; -/// assert_eq!(true as u8 + thing2 as u8, 100); -/// ``` -/// -/// In general, any cast that can be performed via ascribing the type can also be done using `as`, -/// so instead of writing `let x: u32 = 123`, you can write `let x = 123 as u32` (note: `let x: u32 -/// = 123` would be best in that situation). The same is not true in the other direction, however; -/// explicitly using `as` allows a few more coercions that aren't allowed implicitly, such as -/// changing the type of a raw pointer or turning closures into raw pointers. -/// -/// `as` can be seen as the primitive for `From` and `Into`: `as` only works with primitives -/// (`u8`, `bool`, `str`, pointers, ...) whereas `From` and `Into` also works with types like -/// `String` or `Vec`. -/// -/// `as` can also be used with the `_` placeholder when the destination type can be inferred. Note -/// that this can cause inference breakage and usually such code should use an explicit type for -/// both clarity and stability. This is most useful when converting pointers using `as *const _` or -/// `as *mut _` though the [`cast`][const-cast] method is recommended over `as *const _` and it is -/// [the same][mut-cast] for `as *mut _`: those methods make the intent clearer. -/// -/// `as` is also used to rename imports in [`use`] and [`extern crate`][`crate`] statements: -/// -/// ``` -/// # #[allow(unused_imports)] -/// use std::{mem as memory, net as network}; -/// // Now you can use the names `memory` and `network` to refer to `std::mem` and `std::net`. -/// ``` -/// For more information on what `as` is capable of, see the [Reference]. -/// -/// [Reference]: ../reference/expressions/operator-expr.html#type-cast-expressions -/// [`crate`]: keyword.crate.html -/// [`use`]: keyword.use.html -/// [const-cast]: pointer::cast -/// [mut-cast]: primitive.pointer.html#method.cast-1 -mod as_keyword {} - -#[doc(keyword = "break")] -// -/// Exit early from a loop or labelled block. -/// -/// When `break` is encountered, execution of the associated loop body is -/// immediately terminated. -/// -/// ```rust -/// let mut last = 0; -/// -/// for x in 1..100 { -/// if x > 12 { -/// break; -/// } -/// last = x; -/// } -/// -/// assert_eq!(last, 12); -/// println!("{last}"); -/// ``` -/// -/// A break expression is normally associated with the innermost loop enclosing the -/// `break` but a label can be used to specify which enclosing loop is affected. -/// -/// ```rust -/// 'outer: for i in 1..=5 { -/// println!("outer iteration (i): {i}"); -/// -/// '_inner: for j in 1..=200 { -/// println!(" inner iteration (j): {j}"); -/// if j >= 3 { -/// // breaks from inner loop, lets outer loop continue. -/// break; -/// } -/// if i >= 2 { -/// // breaks from outer loop, and directly to "Bye". -/// break 'outer; -/// } -/// } -/// } -/// println!("Bye."); -/// ``` -/// -/// When associated with `loop`, a break expression may be used to return a value from that loop. -/// This is only valid with `loop` and not with any other type of loop. -/// If no value is specified, `break;` returns `()`. -/// Every `break` within a loop must return the same type. -/// -/// ```rust -/// let (mut a, mut b) = (1, 1); -/// let result = loop { -/// if b > 10 { -/// break b; -/// } -/// let c = a + b; -/// a = b; -/// b = c; -/// }; -/// // first number in Fibonacci sequence over 10: -/// assert_eq!(result, 13); -/// println!("{result}"); -/// ``` -/// -/// For more details consult the [Reference on "break expression"] and the [Reference on "break and -/// loop values"]. -/// -/// [Reference on "break expression"]: ../reference/expressions/loop-expr.html#break-expressions -/// [Reference on "break and loop values"]: -/// ../reference/expressions/loop-expr.html#break-and-loop-values -mod break_keyword {} - -#[doc(keyword = "const")] -// -/// Compile-time constants, compile-time evaluable functions, and raw pointers. -/// -/// ## Compile-time constants -/// -/// Sometimes a certain value is used many times throughout a program, and it can become -/// inconvenient to copy it over and over. What's more, it's not always possible or desirable to -/// make it a variable that gets carried around to each function that needs it. In these cases, the -/// `const` keyword provides a convenient alternative to code duplication: -/// -/// ```rust -/// const THING: u32 = 0xABAD1DEA; -/// -/// let foo = 123 + THING; -/// ``` -/// -/// Constants must be explicitly typed; unlike with `let`, you can't ignore their type and let the -/// compiler figure it out. Any constant value can be defined in a `const`, which in practice happens -/// to be most things that would be reasonable to have in a constant (barring `const fn`s). For -/// example, you can't have a [`File`] as a `const`. -/// -/// [`File`]: crate::fs::File -/// -/// The only lifetime allowed in a constant is `'static`, which is the lifetime that encompasses -/// all others in a Rust program. For example, if you wanted to define a constant string, it would -/// look like this: -/// -/// ```rust -/// const WORDS: &'static str = "hello rust!"; -/// ``` -/// -/// Thanks to static lifetime elision, you usually don't have to explicitly use `'static`: -/// -/// ```rust -/// const WORDS: &str = "hello convenience!"; -/// ``` -/// -/// `const` items looks remarkably similar to `static` items, which introduces some confusion as -/// to which one should be used at which times. To put it simply, constants are inlined wherever -/// they're used, making using them identical to simply replacing the name of the `const` with its -/// value. Static variables, on the other hand, point to a single location in memory, which all -/// accesses share. This means that, unlike with constants, they can't have destructors, and act as -/// a single value across the entire codebase. -/// -/// Constants, like statics, should always be in `SCREAMING_SNAKE_CASE`. -/// -/// For more detail on `const`, see the [Rust Book] or the [Reference]. -/// -/// ## Compile-time evaluable functions -/// -/// The other main use of the `const` keyword is in `const fn`. This marks a function as being -/// callable in the body of a `const` or `static` item and in array initializers (commonly called -/// "const contexts"). `const fn` are restricted in the set of operations they can perform, to -/// ensure that they can be evaluated at compile-time. See the [Reference][const-eval] for more -/// detail. -/// -/// Turning a `fn` into a `const fn` has no effect on run-time uses of that function. -/// -/// ## Other uses of `const` -/// -/// The `const` keyword is also used in raw pointers in combination with `mut`, as seen in `*const -/// T` and `*mut T`. More about `const` as used in raw pointers can be read at the Rust docs for the [pointer primitive]. -/// -/// [pointer primitive]: pointer -/// [Rust Book]: ../book/ch03-01-variables-and-mutability.html#constants -/// [Reference]: ../reference/items/constant-items.html -/// [const-eval]: ../reference/const_eval.html -mod const_keyword {} - -#[doc(keyword = "continue")] -// -/// Skip to the next iteration of a loop. -/// -/// When `continue` is encountered, the current iteration is terminated, returning control to the -/// loop head, typically continuing with the next iteration. -/// -/// ```rust -/// // Printing odd numbers by skipping even ones -/// for number in 1..=10 { -/// if number % 2 == 0 { -/// continue; -/// } -/// println!("{number}"); -/// } -/// ``` -/// -/// Like `break`, `continue` is normally associated with the innermost enclosing loop, but labels -/// may be used to specify the affected loop. -/// -/// ```rust -/// // Print Odd numbers under 30 with unit <= 5 -/// 'tens: for ten in 0..3 { -/// '_units: for unit in 0..=9 { -/// if unit % 2 == 0 { -/// continue; -/// } -/// if unit > 5 { -/// continue 'tens; -/// } -/// println!("{}", ten * 10 + unit); -/// } -/// } -/// ``` -/// -/// See [continue expressions] from the reference for more details. -/// -/// [continue expressions]: ../reference/expressions/loop-expr.html#continue-expressions -mod continue_keyword {} - -#[doc(keyword = "crate")] -// -/// A Rust binary or library. -/// -/// The primary use of the `crate` keyword is as a part of `extern crate` declarations, which are -/// used to specify a dependency on a crate external to the one it's declared in. Crates are the -/// fundamental compilation unit of Rust code, and can be seen as libraries or projects. More can -/// be read about crates in the [Reference]. -/// -/// ```rust ignore -/// extern crate rand; -/// extern crate my_crate as thing; -/// extern crate std; // implicitly added to the root of every Rust project -/// ``` -/// -/// The `as` keyword can be used to change what the crate is referred to as in your project. If a -/// crate name includes a dash, it is implicitly imported with the dashes replaced by underscores. -/// -/// `crate` can also be used as in conjunction with `pub` to signify that the item it's attached to -/// is public only to other members of the same crate it's in. -/// -/// ```rust -/// # #[allow(unused_imports)] -/// pub(crate) use std::io::Error as IoError; -/// pub(crate) enum CoolMarkerType { } -/// pub struct PublicThing { -/// pub(crate) semi_secret_thing: bool, -/// } -/// ``` -/// -/// `crate` is also used to represent the absolute path of a module, where `crate` refers to the -/// root of the current crate. For instance, `crate::foo::bar` refers to the name `bar` inside the -/// module `foo`, from anywhere else in the same crate. -/// -/// [Reference]: ../reference/items/extern-crates.html -mod crate_keyword {} - -#[doc(keyword = "else")] -// -/// What expression to evaluate when an [`if`] condition evaluates to [`false`]. -/// -/// `else` expressions are optional. When no else expressions are supplied it is assumed to evaluate -/// to the unit type `()`. -/// -/// The type that the `else` blocks evaluate to must be compatible with the type that the `if` block -/// evaluates to. -/// -/// As can be seen below, `else` must be followed by either: `if`, `if let`, or a block `{}` and it -/// will return the value of that expression. -/// -/// ```rust -/// let result = if true == false { -/// "oh no" -/// } else if "something" == "other thing" { -/// "oh dear" -/// } else if let Some(200) = "blarg".parse::().ok() { -/// "uh oh" -/// } else { -/// println!("Sneaky side effect."); -/// "phew, nothing's broken" -/// }; -/// ``` -/// -/// Here's another example but here we do not try and return an expression: -/// -/// ```rust -/// if true == false { -/// println!("oh no"); -/// } else if "something" == "other thing" { -/// println!("oh dear"); -/// } else if let Some(200) = "blarg".parse::().ok() { -/// println!("uh oh"); -/// } else { -/// println!("phew, nothing's broken"); -/// } -/// ``` -/// -/// The above is _still_ an expression but it will always evaluate to `()`. -/// -/// There is possibly no limit to the number of `else` blocks that could follow an `if` expression -/// however if you have several then a [`match`] expression might be preferable. -/// -/// Read more about control flow in the [Rust Book]. -/// -/// [Rust Book]: ../book/ch03-05-control-flow.html#handling-multiple-conditions-with-else-if -/// [`match`]: keyword.match.html -/// [`false`]: keyword.false.html -/// [`if`]: keyword.if.html -mod else_keyword {} - -#[doc(keyword = "enum")] -// -/// A type that can be any one of several variants. -/// -/// Enums in Rust are similar to those of other compiled languages like C, but have important -/// differences that make them considerably more powerful. What Rust calls enums are more commonly -/// known as [Algebraic Data Types][ADT] if you're coming from a functional programming background. -/// The important detail is that each enum variant can have data to go along with it. -/// -/// ```rust -/// # struct Coord; -/// enum SimpleEnum { -/// FirstVariant, -/// SecondVariant, -/// ThirdVariant, -/// } -/// -/// enum Location { -/// Unknown, -/// Anonymous, -/// Known(Coord), -/// } -/// -/// enum ComplexEnum { -/// Nothing, -/// Something(u32), -/// LotsOfThings { -/// usual_struct_stuff: bool, -/// blah: String, -/// } -/// } -/// -/// enum EmptyEnum { } -/// ``` -/// -/// The first enum shown is the usual kind of enum you'd find in a C-style language. The second -/// shows off a hypothetical example of something storing location data, with `Coord` being any -/// other type that's needed, for example a struct. The third example demonstrates the kind of -/// data a variant can store, ranging from nothing, to a tuple, to an anonymous struct. -/// -/// Instantiating enum variants involves explicitly using the enum's name as its namespace, -/// followed by one of its variants. `SimpleEnum::SecondVariant` would be an example from above. -/// When data follows along with a variant, such as with rust's built-in [`Option`] type, the data -/// is added as the type describes, for example `Option::Some(123)`. The same follows with -/// struct-like variants, with things looking like `ComplexEnum::LotsOfThings { usual_struct_stuff: -/// true, blah: "hello!".to_string(), }`. Empty Enums are similar to [`!`] in that they cannot be -/// instantiated at all, and are used mainly to mess with the type system in interesting ways. -/// -/// For more information, take a look at the [Rust Book] or the [Reference] -/// -/// [ADT]: https://en.wikipedia.org/wiki/Algebraic_data_type -/// [Rust Book]: ../book/ch06-01-defining-an-enum.html -/// [Reference]: ../reference/items/enumerations.html -mod enum_keyword {} - -#[doc(keyword = "extern")] -// -/// Link to or import external code. -/// -/// The `extern` keyword is used in two places in Rust. One is in conjunction with the [`crate`] -/// keyword to make your Rust code aware of other Rust crates in your project, i.e., `extern crate -/// lazy_static;`. The other use is in foreign function interfaces (FFI). -/// -/// `extern` is used in two different contexts within FFI. The first is in the form of external -/// blocks, for declaring function interfaces that Rust code can call foreign code by. -/// -/// ```rust ignore -/// #[link(name = "my_c_library")] -/// extern "C" { -/// fn my_c_function(x: i32) -> bool; -/// } -/// ``` -/// -/// This code would attempt to link with `libmy_c_library.so` on unix-like systems and -/// `my_c_library.dll` on Windows at runtime, and panic if it can't find something to link to. Rust -/// code could then use `my_c_function` as if it were any other unsafe Rust function. Working with -/// non-Rust languages and FFI is inherently unsafe, so wrappers are usually built around C APIs. -/// -/// The mirror use case of FFI is also done via the `extern` keyword: -/// -/// ```rust -/// #[no_mangle] -/// pub extern "C" fn callable_from_c(x: i32) -> bool { -/// x % 3 == 0 -/// } -/// ``` -/// -/// If compiled as a dylib, the resulting .so could then be linked to from a C library, and the -/// function could be used as if it was from any other library. -/// -/// For more information on FFI, check the [Rust book] or the [Reference]. -/// -/// [Rust book]: -/// ../book/ch19-01-unsafe-rust.html#using-extern-functions-to-call-external-code -/// [Reference]: ../reference/items/external-blocks.html -/// [`crate`]: keyword.crate.html -mod extern_keyword {} - -#[doc(keyword = "false")] -// -/// A value of type [`bool`] representing logical **false**. -/// -/// `false` is the logical opposite of [`true`]. -/// -/// See the documentation for [`true`] for more information. -/// -/// [`true`]: keyword.true.html -mod false_keyword {} - -#[doc(keyword = "fn")] -// -/// A function or function pointer. -/// -/// Functions are the primary way code is executed within Rust. Function blocks, usually just -/// called functions, can be defined in a variety of different places and be assigned many -/// different attributes and modifiers. -/// -/// Standalone functions that just sit within a module not attached to anything else are common, -/// but most functions will end up being inside [`impl`] blocks, either on another type itself, or -/// as a trait impl for that type. -/// -/// ```rust -/// fn standalone_function() { -/// // code -/// } -/// -/// pub fn public_thing(argument: bool) -> String { -/// // code -/// # "".to_string() -/// } -/// -/// struct Thing { -/// foo: i32, -/// } -/// -/// impl Thing { -/// pub fn new() -> Self { -/// Self { -/// foo: 42, -/// } -/// } -/// } -/// ``` -/// -/// In addition to presenting fixed types in the form of `fn name(arg: type, ..) -> return_type`, -/// functions can also declare a list of type parameters along with trait bounds that they fall -/// into. -/// -/// ```rust -/// fn generic_function(x: T) -> (T, T, T) { -/// (x.clone(), x.clone(), x.clone()) -/// } -/// -/// fn generic_where(x: T) -> T -/// where T: std::ops::Add + Copy -/// { -/// x + x + x -/// } -/// ``` -/// -/// Declaring trait bounds in the angle brackets is functionally identical to using a `where` -/// clause. It's up to the programmer to decide which works better in each situation, but `where` -/// tends to be better when things get longer than one line. -/// -/// Along with being made public via `pub`, `fn` can also have an [`extern`] added for use in -/// FFI. -/// -/// For more information on the various types of functions and how they're used, consult the [Rust -/// book] or the [Reference]. -/// -/// [`impl`]: keyword.impl.html -/// [`extern`]: keyword.extern.html -/// [Rust book]: ../book/ch03-03-how-functions-work.html -/// [Reference]: ../reference/items/functions.html -mod fn_keyword {} - -#[doc(keyword = "for")] -// -/// Iteration with [`in`], trait implementation with [`impl`], or [higher-ranked trait bounds] -/// (`for<'a>`). -/// -/// The `for` keyword is used in many syntactic locations: -/// -/// * `for` is used in for-in-loops (see below). -/// * `for` is used when implementing traits as in `impl Trait for Type` (see [`impl`] for more info -/// on that). -/// * `for` is also used for [higher-ranked trait bounds] as in `for<'a> &'a T: PartialEq`. -/// -/// for-in-loops, or to be more precise, iterator loops, are a simple syntactic sugar over a common -/// practice within Rust, which is to loop over anything that implements [`IntoIterator`] until the -/// iterator returned by `.into_iter()` returns `None` (or the loop body uses `break`). -/// -/// ```rust -/// for i in 0..5 { -/// println!("{}", i * 2); -/// } -/// -/// for i in std::iter::repeat(5) { -/// println!("turns out {i} never stops being 5"); -/// break; // would loop forever otherwise -/// } -/// -/// 'outer: for x in 5..50 { -/// for y in 0..10 { -/// if x == y { -/// break 'outer; -/// } -/// } -/// } -/// ``` -/// -/// As shown in the example above, `for` loops (along with all other loops) can be tagged, using -/// similar syntax to lifetimes (only visually similar, entirely distinct in practice). Giving the -/// same tag to `break` breaks the tagged loop, which is useful for inner loops. It is definitely -/// not a goto. -/// -/// A `for` loop expands as shown: -/// -/// ```rust -/// # fn code() { } -/// # let iterator = 0..2; -/// for loop_variable in iterator { -/// code() -/// } -/// ``` -/// -/// ```rust -/// # fn code() { } -/// # let iterator = 0..2; -/// { -/// let result = match IntoIterator::into_iter(iterator) { -/// mut iter => loop { -/// match iter.next() { -/// None => break, -/// Some(loop_variable) => { code(); }, -/// }; -/// }, -/// }; -/// result -/// } -/// ``` -/// -/// More details on the functionality shown can be seen at the [`IntoIterator`] docs. -/// -/// For more information on for-loops, see the [Rust book] or the [Reference]. -/// -/// See also, [`loop`], [`while`]. -/// -/// [`in`]: keyword.in.html -/// [`impl`]: keyword.impl.html -/// [`loop`]: keyword.loop.html -/// [`while`]: keyword.while.html -/// [higher-ranked trait bounds]: ../reference/trait-bounds.html#higher-ranked-trait-bounds -/// [Rust book]: -/// ../book/ch03-05-control-flow.html#looping-through-a-collection-with-for -/// [Reference]: ../reference/expressions/loop-expr.html#iterator-loops -mod for_keyword {} - -#[doc(keyword = "if")] -// -/// Evaluate a block if a condition holds. -/// -/// `if` is a familiar construct to most programmers, and is the main way you'll often do logic in -/// your code. However, unlike in most languages, `if` blocks can also act as expressions. -/// -/// ```rust -/// # let rude = true; -/// if 1 == 2 { -/// println!("whoops, mathematics broke"); -/// } else { -/// println!("everything's fine!"); -/// } -/// -/// let greeting = if rude { -/// "sup nerd." -/// } else { -/// "hello, friend!" -/// }; -/// -/// if let Ok(x) = "123".parse::() { -/// println!("{} double that and you get {}!", greeting, x * 2); -/// } -/// ``` -/// -/// Shown above are the three typical forms an `if` block comes in. First is the usual kind of -/// thing you'd see in many languages, with an optional `else` block. Second uses `if` as an -/// expression, which is only possible if all branches return the same type. An `if` expression can -/// be used everywhere you'd expect. The third kind of `if` block is an `if let` block, which -/// behaves similarly to using a `match` expression: -/// -/// ```rust -/// if let Some(x) = Some(123) { -/// // code -/// # let _ = x; -/// } else { -/// // something else -/// } -/// -/// match Some(123) { -/// Some(x) => { -/// // code -/// # let _ = x; -/// }, -/// _ => { -/// // something else -/// }, -/// } -/// ``` -/// -/// Each kind of `if` expression can be mixed and matched as needed. -/// -/// ```rust -/// if true == false { -/// println!("oh no"); -/// } else if "something" == "other thing" { -/// println!("oh dear"); -/// } else if let Some(200) = "blarg".parse::().ok() { -/// println!("uh oh"); -/// } else { -/// println!("phew, nothing's broken"); -/// } -/// ``` -/// -/// The `if` keyword is used in one other place in Rust, namely as a part of pattern matching -/// itself, allowing patterns such as `Some(x) if x > 200` to be used. -/// -/// For more information on `if` expressions, see the [Rust book] or the [Reference]. -/// -/// [Rust book]: ../book/ch03-05-control-flow.html#if-expressions -/// [Reference]: ../reference/expressions/if-expr.html -mod if_keyword {} - -#[doc(keyword = "impl")] -// -/// Implement some functionality for a type. -/// -/// The `impl` keyword is primarily used to define implementations on types. Inherent -/// implementations are standalone, while trait implementations are used to implement traits for -/// types, or other traits. -/// -/// Functions and consts can both be defined in an implementation. A function defined in an -/// `impl` block can be standalone, meaning it would be called like `Foo::bar()`. If the function -/// takes `self`, `&self`, or `&mut self` as its first argument, it can also be called using -/// method-call syntax, a familiar feature to any object oriented programmer, like `foo.bar()`. -/// -/// ```rust -/// struct Example { -/// number: i32, -/// } -/// -/// impl Example { -/// fn boo() { -/// println!("boo! Example::boo() was called!"); -/// } -/// -/// fn answer(&mut self) { -/// self.number += 42; -/// } -/// -/// fn get_number(&self) -> i32 { -/// self.number -/// } -/// } -/// -/// trait Thingy { -/// fn do_thingy(&self); -/// } -/// -/// impl Thingy for Example { -/// fn do_thingy(&self) { -/// println!("doing a thing! also, number is {}!", self.number); -/// } -/// } -/// ``` -/// -/// For more information on implementations, see the [Rust book][book1] or the [Reference]. -/// -/// The other use of the `impl` keyword is in `impl Trait` syntax, which can be seen as a shorthand -/// for "a concrete type that implements this trait". Its primary use is working with closures, -/// which have type definitions generated at compile time that can't be simply typed out. -/// -/// ```rust -/// fn thing_returning_closure() -> impl Fn(i32) -> bool { -/// println!("here's a closure for you!"); -/// |x: i32| x % 3 == 0 -/// } -/// ``` -/// -/// For more information on `impl Trait` syntax, see the [Rust book][book2]. -/// -/// [book1]: ../book/ch05-03-method-syntax.html -/// [Reference]: ../reference/items/implementations.html -/// [book2]: ../book/ch10-02-traits.html#returning-types-that-implement-traits -mod impl_keyword {} - -#[doc(keyword = "in")] -// -/// Iterate over a series of values with [`for`]. -/// -/// The expression immediately following `in` must implement the [`IntoIterator`] trait. -/// -/// ## Literal Examples: -/// -/// * `for _ in 1..3 {}` - Iterate over an exclusive range up to but excluding 3. -/// * `for _ in 1..=3 {}` - Iterate over an inclusive range up to and including 3. -/// -/// (Read more about [range patterns]) -/// -/// [`IntoIterator`]: ../book/ch13-04-performance.html -/// [range patterns]: ../reference/patterns.html?highlight=range#range-patterns -/// [`for`]: keyword.for.html -/// -/// The other use of `in` is with the keyword `pub`. It allows users to declare an item as visible -/// only within a given scope. -/// -/// ## Literal Example: -/// -/// * `pub(in crate::outer_mod) fn outer_mod_visible_fn() {}` - fn is visible in `outer_mod` -/// -/// Starting with the 2018 edition, paths for `pub(in path)` must start with `crate`, `self` or -/// `super`. The 2015 edition may also use paths starting with `::` or modules from the crate root. -/// -/// For more information, see the [Reference]. -/// -/// [Reference]: ../reference/visibility-and-privacy.html#pubin-path-pubcrate-pubsuper-and-pubself -mod in_keyword {} - -#[doc(keyword = "let")] -// -/// Bind a value to a variable. -/// -/// The primary use for the `let` keyword is in `let` statements, which are used to introduce a new -/// set of variables into the current scope, as given by a pattern. -/// -/// ```rust -/// # #![allow(unused_assignments)] -/// let thing1: i32 = 100; -/// let thing2 = 200 + thing1; -/// -/// let mut changing_thing = true; -/// changing_thing = false; -/// -/// let (part1, part2) = ("first", "second"); -/// -/// struct Example { -/// a: bool, -/// b: u64, -/// } -/// -/// let Example { a, b: _ } = Example { -/// a: true, -/// b: 10004, -/// }; -/// assert!(a); -/// ``` -/// -/// The pattern is most commonly a single variable, which means no pattern matching is done and -/// the expression given is bound to the variable. Apart from that, patterns used in `let` bindings -/// can be as complicated as needed, given that the pattern is exhaustive. See the [Rust -/// book][book1] for more information on pattern matching. The type of the pattern is optionally -/// given afterwards, but if left blank is automatically inferred by the compiler if possible. -/// -/// Variables in Rust are immutable by default, and require the `mut` keyword to be made mutable. -/// -/// Multiple variables can be defined with the same name, known as shadowing. This doesn't affect -/// the original variable in any way beyond being unable to directly access it beyond the point of -/// shadowing. It continues to remain in scope, getting dropped only when it falls out of scope. -/// Shadowed variables don't need to have the same type as the variables shadowing them. -/// -/// ```rust -/// let shadowing_example = true; -/// let shadowing_example = 123.4; -/// let shadowing_example = shadowing_example as u32; -/// let mut shadowing_example = format!("cool! {shadowing_example}"); -/// shadowing_example += " something else!"; // not shadowing -/// ``` -/// -/// Other places the `let` keyword is used include along with [`if`], in the form of `if let` -/// expressions. They're useful if the pattern being matched isn't exhaustive, such as with -/// enumerations. `while let` also exists, which runs a loop with a pattern matched value until -/// that pattern can't be matched. -/// -/// For more information on the `let` keyword, see the [Rust book][book2] or the [Reference] -/// -/// [book1]: ../book/ch06-02-match.html -/// [`if`]: keyword.if.html -/// [book2]: ../book/ch18-01-all-the-places-for-patterns.html#let-statements -/// [Reference]: ../reference/statements.html#let-statements -mod let_keyword {} - -#[doc(keyword = "while")] -// -/// Loop while a condition is upheld. -/// -/// A `while` expression is used for predicate loops. The `while` expression runs the conditional -/// expression before running the loop body, then runs the loop body if the conditional -/// expression evaluates to `true`, or exits the loop otherwise. -/// -/// ```rust -/// let mut counter = 0; -/// -/// while counter < 10 { -/// println!("{counter}"); -/// counter += 1; -/// } -/// ``` -/// -/// Like the [`for`] expression, we can use `break` and `continue`. A `while` expression -/// cannot break with a value and always evaluates to `()` unlike [`loop`]. -/// -/// ```rust -/// let mut i = 1; -/// -/// while i < 100 { -/// i *= 2; -/// if i == 64 { -/// break; // Exit when `i` is 64. -/// } -/// } -/// ``` -/// -/// As `if` expressions have their pattern matching variant in `if let`, so too do `while` -/// expressions with `while let`. The `while let` expression matches the pattern against the -/// expression, then runs the loop body if pattern matching succeeds, or exits the loop otherwise. -/// We can use `break` and `continue` in `while let` expressions just like in `while`. -/// -/// ```rust -/// let mut counter = Some(0); -/// -/// while let Some(i) = counter { -/// if i == 10 { -/// counter = None; -/// } else { -/// println!("{i}"); -/// counter = Some (i + 1); -/// } -/// } -/// ``` -/// -/// For more information on `while` and loops in general, see the [reference]. -/// -/// See also, [`for`], [`loop`]. -/// -/// [`for`]: keyword.for.html -/// [`loop`]: keyword.loop.html -/// [reference]: ../reference/expressions/loop-expr.html#predicate-loops -mod while_keyword {} - -#[doc(keyword = "loop")] -// -/// Loop indefinitely. -/// -/// `loop` is used to define the simplest kind of loop supported in Rust. It runs the code inside -/// it until the code uses `break` or the program exits. -/// -/// ```rust -/// loop { -/// println!("hello world forever!"); -/// # break; -/// } -/// -/// let mut i = 1; -/// loop { -/// println!("i is {i}"); -/// if i > 100 { -/// break; -/// } -/// i *= 2; -/// } -/// assert_eq!(i, 128); -/// ``` -/// -/// Unlike the other kinds of loops in Rust (`while`, `while let`, and `for`), loops can be used as -/// expressions that return values via `break`. -/// -/// ```rust -/// let mut i = 1; -/// let something = loop { -/// i *= 2; -/// if i > 100 { -/// break i; -/// } -/// }; -/// assert_eq!(something, 128); -/// ``` -/// -/// Every `break` in a loop has to have the same type. When it's not explicitly giving something, -/// `break;` returns `()`. -/// -/// For more information on `loop` and loops in general, see the [Reference]. -/// -/// See also, [`for`], [`while`]. -/// -/// [`for`]: keyword.for.html -/// [`while`]: keyword.while.html -/// [Reference]: ../reference/expressions/loop-expr.html -mod loop_keyword {} - -#[doc(keyword = "match")] -// -/// Control flow based on pattern matching. -/// -/// `match` can be used to run code conditionally. Every pattern must -/// be handled exhaustively either explicitly or by using wildcards like -/// `_` in the `match`. Since `match` is an expression, values can also be -/// returned. -/// -/// ```rust -/// let opt = Option::None::; -/// let x = match opt { -/// Some(int) => int, -/// None => 10, -/// }; -/// assert_eq!(x, 10); -/// -/// let a_number = Option::Some(10); -/// match a_number { -/// Some(x) if x <= 5 => println!("0 to 5 num = {x}"), -/// Some(x @ 6..=10) => println!("6 to 10 num = {x}"), -/// None => panic!(), -/// // all other numbers -/// _ => panic!(), -/// } -/// ``` -/// -/// `match` can be used to gain access to the inner members of an enum -/// and use them directly. -/// -/// ```rust -/// enum Outer { -/// Double(Option, Option), -/// Single(Option), -/// Empty -/// } -/// -/// let get_inner = Outer::Double(None, Some(String::new())); -/// match get_inner { -/// Outer::Double(None, Some(st)) => println!("{st}"), -/// Outer::Single(opt) => println!("{opt:?}"), -/// _ => panic!(), -/// } -/// ``` -/// -/// For more information on `match` and matching in general, see the [Reference]. -/// -/// [Reference]: ../reference/expressions/match-expr.html -mod match_keyword {} - -#[doc(keyword = "mod")] -// -/// Organize code into [modules]. -/// -/// Use `mod` to create new [modules] to encapsulate code, including other -/// modules: -/// -/// ``` -/// mod foo { -/// mod bar { -/// type MyType = (u8, u8); -/// fn baz() {} -/// } -/// } -/// ``` -/// -/// Like [`struct`]s and [`enum`]s, a module and its content are private by -/// default, inaccessible to code outside of the module. -/// -/// To learn more about allowing access, see the documentation for the [`pub`] -/// keyword. -/// -/// [`enum`]: keyword.enum.html -/// [`pub`]: keyword.pub.html -/// [`struct`]: keyword.struct.html -/// [modules]: ../reference/items/modules.html -mod mod_keyword {} - -#[doc(keyword = "move")] -// -/// Capture a [closure]'s environment by value. -/// -/// `move` converts any variables captured by reference or mutable reference -/// to variables captured by value. -/// -/// ```rust -/// let data = vec![1, 2, 3]; -/// let closure = move || println!("captured {data:?} by value"); -/// -/// // data is no longer available, it is owned by the closure -/// ``` -/// -/// Note: `move` closures may still implement [`Fn`] or [`FnMut`], even though -/// they capture variables by `move`. This is because the traits implemented by -/// a closure type are determined by *what* the closure does with captured -/// values, not *how* it captures them: -/// -/// ```rust -/// fn create_fn() -> impl Fn() { -/// let text = "Fn".to_owned(); -/// move || println!("This is a: {text}") -/// } -/// -/// let fn_plain = create_fn(); -/// fn_plain(); -/// ``` -/// -/// `move` is often used when [threads] are involved. -/// -/// ```rust -/// let data = vec![1, 2, 3]; -/// -/// std::thread::spawn(move || { -/// println!("captured {data:?} by value") -/// }).join().unwrap(); -/// -/// // data was moved to the spawned thread, so we cannot use it here -/// ``` -/// -/// `move` is also valid before an async block. -/// -/// ```rust -/// let capture = "hello".to_owned(); -/// let block = async move { -/// println!("rust says {capture} from async block"); -/// }; -/// ``` -/// -/// For more information on the `move` keyword, see the [closures][closure] section -/// of the Rust book or the [threads] section. -/// -/// [closure]: ../book/ch13-01-closures.html -/// [threads]: ../book/ch16-01-threads.html#using-move-closures-with-threads -mod move_keyword {} - -#[doc(keyword = "mut")] -// -/// A mutable variable, reference, or pointer. -/// -/// `mut` can be used in several situations. The first is mutable variables, -/// which can be used anywhere you can bind a value to a variable name. Some -/// examples: -/// -/// ```rust -/// // A mutable variable in the parameter list of a function. -/// fn foo(mut x: u8, y: u8) -> u8 { -/// x += y; -/// x -/// } -/// -/// // Modifying a mutable variable. -/// # #[allow(unused_assignments)] -/// let mut a = 5; -/// a = 6; -/// -/// assert_eq!(foo(3, 4), 7); -/// assert_eq!(a, 6); -/// ``` -/// -/// The second is mutable references. They can be created from `mut` variables -/// and must be unique: no other variables can have a mutable reference, nor a -/// shared reference. -/// -/// ```rust -/// // Taking a mutable reference. -/// fn push_two(v: &mut Vec) { -/// v.push(2); -/// } -/// -/// // A mutable reference cannot be taken to a non-mutable variable. -/// let mut v = vec![0, 1]; -/// // Passing a mutable reference. -/// push_two(&mut v); -/// -/// assert_eq!(v, vec![0, 1, 2]); -/// ``` -/// -/// ```rust,compile_fail,E0502 -/// let mut v = vec![0, 1]; -/// let mut_ref_v = &mut v; -/// ##[allow(unused)] -/// let ref_v = &v; -/// mut_ref_v.push(2); -/// ``` -/// -/// Mutable raw pointers work much like mutable references, with the added -/// possibility of not pointing to a valid object. The syntax is `*mut Type`. -/// -/// More information on mutable references and pointers can be found in the [Reference]. -/// -/// [Reference]: ../reference/types/pointer.html#mutable-references-mut -mod mut_keyword {} - -#[doc(keyword = "pub")] -// -/// Make an item visible to others. -/// -/// The keyword `pub` makes any module, function, or data structure accessible from inside -/// of external modules. The `pub` keyword may also be used in a `use` declaration to re-export -/// an identifier from a namespace. -/// -/// For more information on the `pub` keyword, please see the visibility section -/// of the [reference] and for some examples, see [Rust by Example]. -/// -/// [reference]:../reference/visibility-and-privacy.html?highlight=pub#visibility-and-privacy -/// [Rust by Example]:../rust-by-example/mod/visibility.html -mod pub_keyword {} - -#[doc(keyword = "ref")] -// -/// Bind by reference during pattern matching. -/// -/// `ref` annotates pattern bindings to make them borrow rather than move. -/// It is **not** a part of the pattern as far as matching is concerned: it does -/// not affect *whether* a value is matched, only *how* it is matched. -/// -/// By default, [`match`] statements consume all they can, which can sometimes -/// be a problem, when you don't really need the value to be moved and owned: -/// -/// ```compile_fail,E0382 -/// let maybe_name = Some(String::from("Alice")); -/// // The variable 'maybe_name' is consumed here ... -/// match maybe_name { -/// Some(n) => println!("Hello, {n}"), -/// _ => println!("Hello, world"), -/// } -/// // ... and is now unavailable. -/// println!("Hello again, {}", maybe_name.unwrap_or("world".into())); -/// ``` -/// -/// Using the `ref` keyword, the value is only borrowed, not moved, making it -/// available for use after the [`match`] statement: -/// -/// ``` -/// let maybe_name = Some(String::from("Alice")); -/// // Using `ref`, the value is borrowed, not moved ... -/// match maybe_name { -/// Some(ref n) => println!("Hello, {n}"), -/// _ => println!("Hello, world"), -/// } -/// // ... so it's available here! -/// println!("Hello again, {}", maybe_name.unwrap_or("world".into())); -/// ``` -/// -/// # `&` vs `ref` -/// -/// - `&` denotes that your pattern expects a reference to an object. Hence `&` -/// is a part of said pattern: `&Foo` matches different objects than `Foo` does. -/// -/// - `ref` indicates that you want a reference to an unpacked value. It is not -/// matched against: `Foo(ref foo)` matches the same objects as `Foo(foo)`. -/// -/// See also the [Reference] for more information. -/// -/// [`match`]: keyword.match.html -/// [Reference]: ../reference/patterns.html#identifier-patterns -mod ref_keyword {} - -#[doc(keyword = "return")] -// -/// Return a value from a function. -/// -/// A `return` marks the end of an execution path in a function: -/// -/// ``` -/// fn foo() -> i32 { -/// return 3; -/// } -/// assert_eq!(foo(), 3); -/// ``` -/// -/// `return` is not needed when the returned value is the last expression in the -/// function. In this case the `;` is omitted: -/// -/// ``` -/// fn foo() -> i32 { -/// 3 -/// } -/// assert_eq!(foo(), 3); -/// ``` -/// -/// `return` returns from the function immediately (an "early return"): -/// -/// ```no_run -/// use std::fs::File; -/// use std::io::{Error, ErrorKind, Read, Result}; -/// -/// fn main() -> Result<()> { -/// let mut file = match File::open("foo.txt") { -/// Ok(f) => f, -/// Err(e) => return Err(e), -/// }; -/// -/// let mut contents = String::new(); -/// let size = match file.read_to_string(&mut contents) { -/// Ok(s) => s, -/// Err(e) => return Err(e), -/// }; -/// -/// if contents.contains("impossible!") { -/// return Err(Error::new(ErrorKind::Other, "oh no!")); -/// } -/// -/// if size > 9000 { -/// return Err(Error::new(ErrorKind::Other, "over 9000!")); -/// } -/// -/// assert_eq!(contents, "Hello, world!"); -/// Ok(()) -/// } -/// ``` -mod return_keyword {} - -#[doc(keyword = "self")] -// -/// The receiver of a method, or the current module. -/// -/// `self` is used in two situations: referencing the current module and marking -/// the receiver of a method. -/// -/// In paths, `self` can be used to refer to the current module, either in a -/// [`use`] statement or in a path to access an element: -/// -/// ``` -/// # #![allow(unused_imports)] -/// use std::io::{self, Read}; -/// ``` -/// -/// Is functionally the same as: -/// -/// ``` -/// # #![allow(unused_imports)] -/// use std::io; -/// use std::io::Read; -/// ``` -/// -/// Using `self` to access an element in the current module: -/// -/// ``` -/// # #![allow(dead_code)] -/// # fn main() {} -/// fn foo() {} -/// fn bar() { -/// self::foo() -/// } -/// ``` -/// -/// `self` as the current receiver for a method allows to omit the parameter -/// type most of the time. With the exception of this particularity, `self` is -/// used much like any other parameter: -/// -/// ``` -/// struct Foo(i32); -/// -/// impl Foo { -/// // No `self`. -/// fn new() -> Self { -/// Self(0) -/// } -/// -/// // Consuming `self`. -/// fn consume(self) -> Self { -/// Self(self.0 + 1) -/// } -/// -/// // Borrowing `self`. -/// fn borrow(&self) -> &i32 { -/// &self.0 -/// } -/// -/// // Borrowing `self` mutably. -/// fn borrow_mut(&mut self) -> &mut i32 { -/// &mut self.0 -/// } -/// } -/// -/// // This method must be called with a `Type::` prefix. -/// let foo = Foo::new(); -/// assert_eq!(foo.0, 0); -/// -/// // Those two calls produces the same result. -/// let foo = Foo::consume(foo); -/// assert_eq!(foo.0, 1); -/// let foo = foo.consume(); -/// assert_eq!(foo.0, 2); -/// -/// // Borrowing is handled automatically with the second syntax. -/// let borrow_1 = Foo::borrow(&foo); -/// let borrow_2 = foo.borrow(); -/// assert_eq!(borrow_1, borrow_2); -/// -/// // Borrowing mutably is handled automatically too with the second syntax. -/// let mut foo = Foo::new(); -/// *Foo::borrow_mut(&mut foo) += 1; -/// assert_eq!(foo.0, 1); -/// *foo.borrow_mut() += 1; -/// assert_eq!(foo.0, 2); -/// ``` -/// -/// Note that this automatic conversion when calling `foo.method()` is not -/// limited to the examples above. See the [Reference] for more information. -/// -/// [`use`]: keyword.use.html -/// [Reference]: ../reference/items/associated-items.html#methods -mod self_keyword {} - -// FIXME: Once rustdoc can handle URL conflicts on case insensitive file systems, we can remove the -// three next lines and put back: `#[doc(keyword = "Self")]`. -#[doc(alias = "Self")] -#[allow(rustc::existing_doc_keyword)] -#[doc(keyword = "SelfTy")] -// -/// The implementing type within a [`trait`] or [`impl`] block, or the current type within a type -/// definition. -/// -/// Within a type definition: -/// -/// ``` -/// # #![allow(dead_code)] -/// struct Node { -/// elem: i32, -/// // `Self` is a `Node` here. -/// next: Option>, -/// } -/// ``` -/// -/// In an [`impl`] block: -/// -/// ``` -/// struct Foo(i32); -/// -/// impl Foo { -/// fn new() -> Self { -/// Self(0) -/// } -/// } -/// -/// assert_eq!(Foo::new().0, Foo(0).0); -/// ``` -/// -/// Generic parameters are implicit with `Self`: -/// -/// ``` -/// # #![allow(dead_code)] -/// struct Wrap { -/// elem: T, -/// } -/// -/// impl Wrap { -/// fn new(elem: T) -> Self { -/// Self { elem } -/// } -/// } -/// ``` -/// -/// In a [`trait`] definition and related [`impl`] block: -/// -/// ``` -/// trait Example { -/// fn example() -> Self; -/// } -/// -/// struct Foo(i32); -/// -/// impl Example for Foo { -/// fn example() -> Self { -/// Self(42) -/// } -/// } -/// -/// assert_eq!(Foo::example().0, Foo(42).0); -/// ``` -/// -/// [`impl`]: keyword.impl.html -/// [`trait`]: keyword.trait.html -mod self_upper_keyword {} - -#[doc(keyword = "static")] -// -/// A static item is a value which is valid for the entire duration of your -/// program (a `'static` lifetime). -/// -/// On the surface, `static` items seem very similar to [`const`]s: both contain -/// a value, both require type annotations and both can only be initialized with -/// constant functions and values. However, `static`s are notably different in -/// that they represent a location in memory. That means that you can have -/// references to `static` items and potentially even modify them, making them -/// essentially global variables. -/// -/// Static items do not call [`drop`] at the end of the program. -/// -/// There are two types of `static` items: those declared in association with -/// the [`mut`] keyword and those without. -/// -/// Static items cannot be moved: -/// -/// ```rust,compile_fail,E0507 -/// static VEC: Vec = vec![]; -/// -/// fn move_vec(v: Vec) -> Vec { -/// v -/// } -/// -/// // This line causes an error -/// move_vec(VEC); -/// ``` -/// -/// # Simple `static`s -/// -/// Accessing non-[`mut`] `static` items is considered safe, but some -/// restrictions apply. Most notably, the type of a `static` value needs to -/// implement the [`Sync`] trait, ruling out interior mutability containers -/// like [`RefCell`]. See the [Reference] for more information. -/// -/// ```rust -/// static FOO: [i32; 5] = [1, 2, 3, 4, 5]; -/// -/// let r1 = &FOO as *const _; -/// let r2 = &FOO as *const _; -/// // With a strictly read-only static, references will have the same address -/// assert_eq!(r1, r2); -/// // A static item can be used just like a variable in many cases -/// println!("{FOO:?}"); -/// ``` -/// -/// # Mutable `static`s -/// -/// If a `static` item is declared with the [`mut`] keyword, then it is allowed -/// to be modified by the program. However, accessing mutable `static`s can -/// cause undefined behavior in a number of ways, for example due to data races -/// in a multithreaded context. As such, all accesses to mutable `static`s -/// require an [`unsafe`] block. -/// -/// Despite their unsafety, mutable `static`s are necessary in many contexts: -/// they can be used to represent global state shared by the whole program or in -/// [`extern`] blocks to bind to variables from C libraries. -/// -/// In an [`extern`] block: -/// -/// ```rust,no_run -/// # #![allow(dead_code)] -/// extern "C" { -/// static mut ERROR_MESSAGE: *mut std::os::raw::c_char; -/// } -/// ``` -/// -/// Mutable `static`s, just like simple `static`s, have some restrictions that -/// apply to them. See the [Reference] for more information. -/// -/// [`const`]: keyword.const.html -/// [`extern`]: keyword.extern.html -/// [`mut`]: keyword.mut.html -/// [`unsafe`]: keyword.unsafe.html -/// [`RefCell`]: cell::RefCell -/// [Reference]: ../reference/items/static-items.html -mod static_keyword {} - -#[doc(keyword = "struct")] -// -/// A type that is composed of other types. -/// -/// Structs in Rust come in three flavors: Structs with named fields, tuple structs, and unit -/// structs. -/// -/// ```rust -/// struct Regular { -/// field1: f32, -/// field2: String, -/// pub field3: bool -/// } -/// -/// struct Tuple(u32, String); -/// -/// struct Unit; -/// ``` -/// -/// Regular structs are the most commonly used. Each field defined within them has a name and a -/// type, and once defined can be accessed using `example_struct.field` syntax. The fields of a -/// struct share its mutability, so `foo.bar = 2;` would only be valid if `foo` was mutable. Adding -/// `pub` to a field makes it visible to code in other modules, as well as allowing it to be -/// directly accessed and modified. -/// -/// Tuple structs are similar to regular structs, but its fields have no names. They are used like -/// tuples, with deconstruction possible via `let TupleStruct(x, y) = foo;` syntax. For accessing -/// individual variables, the same syntax is used as with regular tuples, namely `foo.0`, `foo.1`, -/// etc, starting at zero. -/// -/// Unit structs are most commonly used as marker. They have a size of zero bytes, but unlike empty -/// enums they can be instantiated, making them isomorphic to the unit type `()`. Unit structs are -/// useful when you need to implement a trait on something, but don't need to store any data inside -/// it. -/// -/// # Instantiation -/// -/// Structs can be instantiated in different ways, all of which can be mixed and -/// matched as needed. The most common way to make a new struct is via a constructor method such as -/// `new()`, but when that isn't available (or you're writing the constructor itself), struct -/// literal syntax is used: -/// -/// ```rust -/// # struct Foo { field1: f32, field2: String, etc: bool } -/// let example = Foo { -/// field1: 42.0, -/// field2: "blah".to_string(), -/// etc: true, -/// }; -/// ``` -/// -/// It's only possible to directly instantiate a struct using struct literal syntax when all of its -/// fields are visible to you. -/// -/// There are a handful of shortcuts provided to make writing constructors more convenient, most -/// common of which is the Field Init shorthand. When there is a variable and a field of the same -/// name, the assignment can be simplified from `field: field` into simply `field`. The following -/// example of a hypothetical constructor demonstrates this: -/// -/// ```rust -/// struct User { -/// name: String, -/// admin: bool, -/// } -/// -/// impl User { -/// pub fn new(name: String) -> Self { -/// Self { -/// name, -/// admin: false, -/// } -/// } -/// } -/// ``` -/// -/// Another shortcut for struct instantiation is available, used when you need to make a new -/// struct that has the same values as most of a previous struct of the same type, called struct -/// update syntax: -/// -/// ```rust -/// # struct Foo { field1: String, field2: () } -/// # let thing = Foo { field1: "".to_string(), field2: () }; -/// let updated_thing = Foo { -/// field1: "a new value".to_string(), -/// ..thing -/// }; -/// ``` -/// -/// Tuple structs are instantiated in the same way as tuples themselves, except with the struct's -/// name as a prefix: `Foo(123, false, 0.1)`. -/// -/// Empty structs are instantiated with just their name, and don't need anything else. `let thing = -/// EmptyStruct;` -/// -/// # Style conventions -/// -/// Structs are always written in UpperCamelCase, with few exceptions. While the trailing comma on a -/// struct's list of fields can be omitted, it's usually kept for convenience in adding and -/// removing fields down the line. -/// -/// For more information on structs, take a look at the [Rust Book][book] or the -/// [Reference][reference]. -/// -/// [`PhantomData`]: marker::PhantomData -/// [book]: ../book/ch05-01-defining-structs.html -/// [reference]: ../reference/items/structs.html -mod struct_keyword {} - -#[doc(keyword = "super")] -// -/// The parent of the current [module]. -/// -/// ```rust -/// # #![allow(dead_code)] -/// # fn main() {} -/// mod a { -/// pub fn foo() {} -/// } -/// mod b { -/// pub fn foo() { -/// super::a::foo(); // call a's foo function -/// } -/// } -/// ``` -/// -/// It is also possible to use `super` multiple times: `super::super::foo`, -/// going up the ancestor chain. -/// -/// See the [Reference] for more information. -/// -/// [module]: ../reference/items/modules.html -/// [Reference]: ../reference/paths.html#super -mod super_keyword {} - -#[doc(keyword = "trait")] -// -/// A common interface for a group of types. -/// -/// A `trait` is like an interface that data types can implement. When a type -/// implements a trait it can be treated abstractly as that trait using generics -/// or trait objects. -/// -/// Traits can be made up of three varieties of associated items: -/// -/// - functions and methods -/// - types -/// - constants -/// -/// Traits may also contain additional type parameters. Those type parameters -/// or the trait itself can be constrained by other traits. -/// -/// Traits can serve as markers or carry other logical semantics that -/// aren't expressed through their items. When a type implements that -/// trait it is promising to uphold its contract. [`Send`] and [`Sync`] are two -/// such marker traits present in the standard library. -/// -/// See the [Reference][Ref-Traits] for a lot more information on traits. -/// -/// # Examples -/// -/// Traits are declared using the `trait` keyword. Types can implement them -/// using [`impl`] `Trait` [`for`] `Type`: -/// -/// ```rust -/// trait Zero { -/// const ZERO: Self; -/// fn is_zero(&self) -> bool; -/// } -/// -/// impl Zero for i32 { -/// const ZERO: Self = 0; -/// -/// fn is_zero(&self) -> bool { -/// *self == Self::ZERO -/// } -/// } -/// -/// assert_eq!(i32::ZERO, 0); -/// assert!(i32::ZERO.is_zero()); -/// assert!(!4.is_zero()); -/// ``` -/// -/// With an associated type: -/// -/// ```rust -/// trait Builder { -/// type Built; -/// -/// fn build(&self) -> Self::Built; -/// } -/// ``` -/// -/// Traits can be generic, with constraints or without: -/// -/// ```rust -/// trait MaybeFrom { -/// fn maybe_from(value: T) -> Option -/// where -/// Self: Sized; -/// } -/// ``` -/// -/// Traits can build upon the requirements of other traits. In the example -/// below `Iterator` is a **supertrait** and `ThreeIterator` is a **subtrait**: -/// -/// ```rust -/// trait ThreeIterator: Iterator { -/// fn next_three(&mut self) -> Option<[Self::Item; 3]>; -/// } -/// ``` -/// -/// Traits can be used in functions, as parameters: -/// -/// ```rust -/// # #![allow(dead_code)] -/// fn debug_iter(it: I) where I::Item: std::fmt::Debug { -/// for elem in it { -/// println!("{elem:#?}"); -/// } -/// } -/// -/// // u8_len_1, u8_len_2 and u8_len_3 are equivalent -/// -/// fn u8_len_1(val: impl Into>) -> usize { -/// val.into().len() -/// } -/// -/// fn u8_len_2>>(val: T) -> usize { -/// val.into().len() -/// } -/// -/// fn u8_len_3(val: T) -> usize -/// where -/// T: Into>, -/// { -/// val.into().len() -/// } -/// ``` -/// -/// Or as return types: -/// -/// ```rust -/// # #![allow(dead_code)] -/// fn from_zero_to(v: u8) -> impl Iterator { -/// (0..v).into_iter() -/// } -/// ``` -/// -/// The use of the [`impl`] keyword in this position allows the function writer -/// to hide the concrete type as an implementation detail which can change -/// without breaking user's code. -/// -/// # Trait objects -/// -/// A *trait object* is an opaque value of another type that implements a set of -/// traits. A trait object implements all specified traits as well as their -/// supertraits (if any). -/// -/// The syntax is the following: `dyn BaseTrait + AutoTrait1 + ... AutoTraitN`. -/// Only one `BaseTrait` can be used so this will not compile: -/// -/// ```rust,compile_fail,E0225 -/// trait A {} -/// trait B {} -/// -/// let _: Box; -/// ``` -/// -/// Neither will this, which is a syntax error: -/// -/// ```rust,compile_fail -/// trait A {} -/// trait B {} -/// -/// let _: Box; -/// ``` -/// -/// On the other hand, this is correct: -/// -/// ```rust -/// trait A {} -/// -/// let _: Box; -/// ``` -/// -/// The [Reference][Ref-Trait-Objects] has more information about trait objects, -/// their limitations and the differences between editions. -/// -/// # Unsafe traits -/// -/// Some traits may be unsafe to implement. Using the [`unsafe`] keyword in -/// front of the trait's declaration is used to mark this: -/// -/// ```rust -/// unsafe trait UnsafeTrait {} -/// -/// unsafe impl UnsafeTrait for i32 {} -/// ``` -/// -/// # Differences between the 2015 and 2018 editions -/// -/// In the 2015 edition the parameters pattern was not needed for traits: -/// -/// ```rust,edition2015 -/// # #![allow(anonymous_parameters)] -/// trait Tr { -/// fn f(i32); -/// } -/// ``` -/// -/// This behavior is no longer valid in edition 2018. -/// -/// [`for`]: keyword.for.html -/// [`impl`]: keyword.impl.html -/// [`unsafe`]: keyword.unsafe.html -/// [Ref-Traits]: ../reference/items/traits.html -/// [Ref-Trait-Objects]: ../reference/types/trait-object.html -mod trait_keyword {} - -#[doc(keyword = "true")] -// -/// A value of type [`bool`] representing logical **true**. -/// -/// Logically `true` is not equal to [`false`]. -/// -/// ## Control structures that check for **true** -/// -/// Several of Rust's control structures will check for a `bool` condition evaluating to **true**. -/// -/// * The condition in an [`if`] expression must be of type `bool`. -/// Whenever that condition evaluates to **true**, the `if` expression takes -/// on the value of the first block. If however, the condition evaluates -/// to `false`, the expression takes on value of the `else` block if there is one. -/// -/// * [`while`] is another control flow construct expecting a `bool`-typed condition. -/// As long as the condition evaluates to **true**, the `while` loop will continually -/// evaluate its associated block. -/// -/// * [`match`] arms can have guard clauses on them. -/// -/// [`if`]: keyword.if.html -/// [`while`]: keyword.while.html -/// [`match`]: ../reference/expressions/match-expr.html#match-guards -/// [`false`]: keyword.false.html -mod true_keyword {} - -#[doc(keyword = "type")] -// -/// Define an [alias] for an existing type. -/// -/// The syntax is `type Name = ExistingType;`. -/// -/// # Examples -/// -/// `type` does **not** create a new type: -/// -/// ```rust -/// type Meters = u32; -/// type Kilograms = u32; -/// -/// let m: Meters = 3; -/// let k: Kilograms = 3; -/// -/// assert_eq!(m, k); -/// ``` -/// -/// A type can be generic: -/// -/// ```rust -/// # use std::sync::{Arc, Mutex}; -/// type ArcMutex = Arc>; -/// ``` -/// -/// In traits, `type` is used to declare an [associated type]: -/// -/// ```rust -/// trait Iterator { -/// // associated type declaration -/// type Item; -/// fn next(&mut self) -> Option; -/// } -/// -/// struct Once(Option); -/// -/// impl Iterator for Once { -/// // associated type definition -/// type Item = T; -/// fn next(&mut self) -> Option { -/// self.0.take() -/// } -/// } -/// ``` -/// -/// [`trait`]: keyword.trait.html -/// [associated type]: ../reference/items/associated-items.html#associated-types -/// [alias]: ../reference/items/type-aliases.html -mod type_keyword {} - -#[doc(keyword = "unsafe")] -// -/// Code or interfaces whose [memory safety] cannot be verified by the type -/// system. -/// -/// The `unsafe` keyword has two uses: -/// - to declare the existence of contracts the compiler can't check (`unsafe fn` and `unsafe -/// trait`), -/// - and to declare that a programmer has checked that these contracts have been upheld (`unsafe -/// {}` and `unsafe impl`, but also `unsafe fn` -- see below). -/// -/// They are not mutually exclusive, as can be seen in `unsafe fn`: the body of an `unsafe fn` is, -/// by default, treated like an unsafe block. The `unsafe_op_in_unsafe_fn` lint can be enabled to -/// change that. -/// -/// # Unsafe abilities -/// -/// **No matter what, Safe Rust can't cause Undefined Behavior**. This is -/// referred to as [soundness]: a well-typed program actually has the desired -/// properties. The [Nomicon][nomicon-soundness] has a more detailed explanation -/// on the subject. -/// -/// To ensure soundness, Safe Rust is restricted enough that it can be -/// automatically checked. Sometimes, however, it is necessary to write code -/// that is correct for reasons which are too clever for the compiler to -/// understand. In those cases, you need to use Unsafe Rust. -/// -/// Here are the abilities Unsafe Rust has in addition to Safe Rust: -/// -/// - Dereference [raw pointers] -/// - Implement `unsafe` [`trait`]s -/// - Call `unsafe` functions -/// - Mutate [`static`]s (including [`extern`]al ones) -/// - Access fields of [`union`]s -/// -/// However, this extra power comes with extra responsibilities: it is now up to -/// you to ensure soundness. The `unsafe` keyword helps by clearly marking the -/// pieces of code that need to worry about this. -/// -/// ## The different meanings of `unsafe` -/// -/// Not all uses of `unsafe` are equivalent: some are here to mark the existence -/// of a contract the programmer must check, others are to say "I have checked -/// the contract, go ahead and do this". The following -/// [discussion on Rust Internals] has more in-depth explanations about this but -/// here is a summary of the main points: -/// -/// - `unsafe fn`: calling this function means abiding by a contract the -/// compiler cannot enforce. -/// - `unsafe trait`: implementing the [`trait`] means abiding by a -/// contract the compiler cannot enforce. -/// - `unsafe {}`: the contract necessary to call the operations inside the -/// block has been checked by the programmer and is guaranteed to be respected. -/// - `unsafe impl`: the contract necessary to implement the trait has been -/// checked by the programmer and is guaranteed to be respected. -/// -/// By default, `unsafe fn` also acts like an `unsafe {}` block -/// around the code inside the function. This means it is not just a signal to -/// the caller, but also promises that the preconditions for the operations -/// inside the function are upheld. Mixing these two meanings can be confusing, so the -/// `unsafe_op_in_unsafe_fn` lint can be enabled to warn against that and require explicit unsafe -/// blocks even inside `unsafe fn`. -/// -/// See the [Rustonomicon] and the [Reference] for more information. -/// -/// # Examples -/// -/// ## Marking elements as `unsafe` -/// -/// `unsafe` can be used on functions. Note that functions and statics declared -/// in [`extern`] blocks are implicitly marked as `unsafe` (but not functions -/// declared as `extern "something" fn ...`). Mutable statics are always unsafe, -/// wherever they are declared. Methods can also be declared as `unsafe`: -/// -/// ```rust -/// # #![allow(dead_code)] -/// static mut FOO: &str = "hello"; -/// -/// unsafe fn unsafe_fn() {} -/// -/// extern "C" { -/// fn unsafe_extern_fn(); -/// static BAR: *mut u32; -/// } -/// -/// trait SafeTraitWithUnsafeMethod { -/// unsafe fn unsafe_method(&self); -/// } -/// -/// struct S; -/// -/// impl S { -/// unsafe fn unsafe_method_on_struct() {} -/// } -/// ``` -/// -/// Traits can also be declared as `unsafe`: -/// -/// ```rust -/// unsafe trait UnsafeTrait {} -/// ``` -/// -/// Since `unsafe fn` and `unsafe trait` indicate that there is a safety -/// contract that the compiler cannot enforce, documenting it is important. The -/// standard library has many examples of this, like the following which is an -/// extract from [`Vec::set_len`]. The `# Safety` section explains the contract -/// that must be fulfilled to safely call the function. -/// -/// ```rust,ignore (stub-to-show-doc-example) -/// /// Forces the length of the vector to `new_len`. -/// /// -/// /// This is a low-level operation that maintains none of the normal -/// /// invariants of the type. Normally changing the length of a vector -/// /// is done using one of the safe operations instead, such as -/// /// `truncate`, `resize`, `extend`, or `clear`. -/// /// -/// /// # Safety -/// /// -/// /// - `new_len` must be less than or equal to `capacity()`. -/// /// - The elements at `old_len..new_len` must be initialized. -/// pub unsafe fn set_len(&mut self, new_len: usize) -/// ``` -/// -/// ## Using `unsafe {}` blocks and `impl`s -/// -/// Performing `unsafe` operations requires an `unsafe {}` block: -/// -/// ```rust -/// # #![allow(dead_code)] -/// #![deny(unsafe_op_in_unsafe_fn)] -/// -/// /// Dereference the given pointer. -/// /// -/// /// # Safety -/// /// -/// /// `ptr` must be aligned and must not be dangling. -/// unsafe fn deref_unchecked(ptr: *const i32) -> i32 { -/// // SAFETY: the caller is required to ensure that `ptr` is aligned and dereferenceable. -/// unsafe { *ptr } -/// } -/// -/// let a = 3; -/// let b = &a as *const _; -/// // SAFETY: `a` has not been dropped and references are always aligned, -/// // so `b` is a valid address. -/// unsafe { assert_eq!(*b, deref_unchecked(b)); }; -/// ``` -/// -/// ## `unsafe` and traits -/// -/// The interactions of `unsafe` and traits can be surprising, so let us contrast the -/// two combinations of safe `fn` in `unsafe trait` and `unsafe fn` in safe trait using two -/// examples: -/// -/// ```rust -/// /// # Safety -/// /// -/// /// `make_even` must return an even number. -/// unsafe trait MakeEven { -/// fn make_even(&self) -> i32; -/// } -/// -/// // SAFETY: Our `make_even` always returns something even. -/// unsafe impl MakeEven for i32 { -/// fn make_even(&self) -> i32 { -/// self << 1 -/// } -/// } -/// -/// fn use_make_even(x: impl MakeEven) { -/// if x.make_even() % 2 == 1 { -/// // SAFETY: this can never happen, because all `MakeEven` implementations -/// // ensure that `make_even` returns something even. -/// unsafe { std::hint::unreachable_unchecked() }; -/// } -/// } -/// ``` -/// -/// Note how the safety contract of the trait is upheld by the implementation, and is itself used to -/// uphold the safety contract of the unsafe function `unreachable_unchecked` called by -/// `use_make_even`. `make_even` itself is a safe function because its *callers* do not have to -/// worry about any contract, only the *implementation* of `MakeEven` is required to uphold a -/// certain contract. `use_make_even` is safe because it can use the promise made by `MakeEven` -/// implementations to uphold the safety contract of the `unsafe fn unreachable_unchecked` it calls. -/// -/// It is also possible to have `unsafe fn` in a regular safe `trait`: -/// -/// ```rust -/// # #![feature(never_type)] -/// #![deny(unsafe_op_in_unsafe_fn)] -/// -/// trait Indexable { -/// const LEN: usize; -/// -/// /// # Safety -/// /// -/// /// The caller must ensure that `idx < LEN`. -/// unsafe fn idx_unchecked(&self, idx: usize) -> i32; -/// } -/// -/// // The implementation for `i32` doesn't need to do any contract reasoning. -/// impl Indexable for i32 { -/// const LEN: usize = 1; -/// -/// unsafe fn idx_unchecked(&self, idx: usize) -> i32 { -/// debug_assert_eq!(idx, 0); -/// *self -/// } -/// } -/// -/// // The implementation for arrays exploits the function contract to -/// // make use of `get_unchecked` on slices and avoid a run-time check. -/// impl Indexable for [i32; 42] { -/// const LEN: usize = 42; -/// -/// unsafe fn idx_unchecked(&self, idx: usize) -> i32 { -/// // SAFETY: As per this trait's documentation, the caller ensures -/// // that `idx < 42`. -/// unsafe { *self.get_unchecked(idx) } -/// } -/// } -/// -/// // The implementation for the never type declares a length of 0, -/// // which means `idx_unchecked` can never be called. -/// impl Indexable for ! { -/// const LEN: usize = 0; -/// -/// unsafe fn idx_unchecked(&self, idx: usize) -> i32 { -/// // SAFETY: As per this trait's documentation, the caller ensures -/// // that `idx < 0`, which is impossible, so this is dead code. -/// unsafe { std::hint::unreachable_unchecked() } -/// } -/// } -/// -/// fn use_indexable(x: I, idx: usize) -> i32 { -/// if idx < I::LEN { -/// // SAFETY: We have checked that `idx < I::LEN`. -/// unsafe { x.idx_unchecked(idx) } -/// } else { -/// panic!("index out-of-bounds") -/// } -/// } -/// ``` -/// -/// This time, `use_indexable` is safe because it uses a run-time check to discharge the safety -/// contract of `idx_unchecked`. Implementing `Indexable` is safe because when writing -/// `idx_unchecked`, we don't have to worry: our *callers* need to discharge a proof obligation -/// (like `use_indexable` does), but the *implementation* of `get_unchecked` has no proof obligation -/// to contend with. Of course, the implementation of `Indexable` may choose to call other unsafe -/// operations, and then it needs an `unsafe` *block* to indicate it discharged the proof -/// obligations of its callees. (We enabled `unsafe_op_in_unsafe_fn`, so the body of `idx_unchecked` -/// is not implicitly an unsafe block.) For that purpose it can make use of the contract that all -/// its callers must uphold -- the fact that `idx < LEN`. -/// -/// Formally speaking, an `unsafe fn` in a trait is a function with *preconditions* that go beyond -/// those encoded by the argument types (such as `idx < LEN`), whereas an `unsafe trait` can declare -/// that some of its functions have *postconditions* that go beyond those encoded in the return type -/// (such as returning an even integer). If a trait needs a function with both extra precondition -/// and extra postcondition, then it needs an `unsafe fn` in an `unsafe trait`. -/// -/// [`extern`]: keyword.extern.html -/// [`trait`]: keyword.trait.html -/// [`static`]: keyword.static.html -/// [`union`]: keyword.union.html -/// [`impl`]: keyword.impl.html -/// [raw pointers]: ../reference/types/pointer.html -/// [memory safety]: ../book/ch19-01-unsafe-rust.html -/// [Rustonomicon]: ../nomicon/index.html -/// [nomicon-soundness]: ../nomicon/safe-unsafe-meaning.html -/// [soundness]: https://rust-lang.github.io/unsafe-code-guidelines/glossary.html#soundness-of-code--of-a-library -/// [Reference]: ../reference/unsafety.html -/// [discussion on Rust Internals]: https://internals.rust-lang.org/t/what-does-unsafe-mean/6696 -mod unsafe_keyword {} - -#[doc(keyword = "use")] -// -/// Import or rename items from other crates or modules. -/// -/// Usually a `use` keyword is used to shorten the path required to refer to a module item. -/// The keyword may appear in modules, blocks and even functions, usually at the top. -/// -/// The most basic usage of the keyword is `use path::to::item;`, -/// though a number of convenient shortcuts are supported: -/// -/// * Simultaneously binding a list of paths with a common prefix, -/// using the glob-like brace syntax `use a::b::{c, d, e::f, g::h::i};` -/// * Simultaneously binding a list of paths with a common prefix and their common parent module, -/// using the [`self`] keyword, such as `use a::b::{self, c, d::e};` -/// * Rebinding the target name as a new local name, using the syntax `use p::q::r as x;`. -/// This can also be used with the last two features: `use a::b::{self as ab, c as abc}`. -/// * Binding all paths matching a given prefix, -/// using the asterisk wildcard syntax `use a::b::*;`. -/// * Nesting groups of the previous features multiple times, -/// such as `use a::b::{self as ab, c, d::{*, e::f}};` -/// * Reexporting with visibility modifiers such as `pub use a::b;` -/// * Importing with `_` to only import the methods of a trait without binding it to a name -/// (to avoid conflict for example): `use ::std::io::Read as _;`. -/// -/// Using path qualifiers like [`crate`], [`super`] or [`self`] is supported: `use crate::a::b;`. -/// -/// Note that when the wildcard `*` is used on a type, it does not import its methods (though -/// for `enum`s it imports the variants, as shown in the example below). -/// -/// ```compile_fail,edition2018 -/// enum ExampleEnum { -/// VariantA, -/// VariantB, -/// } -/// -/// impl ExampleEnum { -/// fn new() -> Self { -/// Self::VariantA -/// } -/// } -/// -/// use ExampleEnum::*; -/// -/// // Compiles. -/// let _ = VariantA; -/// -/// // Does not compile ! -/// let n = new(); -/// ``` -/// -/// For more information on `use` and paths in general, see the [Reference]. -/// -/// The differences about paths and the `use` keyword between the 2015 and 2018 editions -/// can also be found in the [Reference]. -/// -/// [`crate`]: keyword.crate.html -/// [`self`]: keyword.self.html -/// [`super`]: keyword.super.html -/// [Reference]: ../reference/items/use-declarations.html -mod use_keyword {} - -#[doc(keyword = "where")] -// -/// Add constraints that must be upheld to use an item. -/// -/// `where` allows specifying constraints on lifetime and generic parameters. -/// The [RFC] introducing `where` contains detailed information about the -/// keyword. -/// -/// # Examples -/// -/// `where` can be used for constraints with traits: -/// -/// ```rust -/// fn new() -> T { -/// T::default() -/// } -/// -/// fn new_where() -> T -/// where -/// T: Default, -/// { -/// T::default() -/// } -/// -/// assert_eq!(0.0, new()); -/// assert_eq!(0.0, new_where()); -/// -/// assert_eq!(0, new()); -/// assert_eq!(0, new_where()); -/// ``` -/// -/// `where` can also be used for lifetimes. -/// -/// This compiles because `longer` outlives `shorter`, thus the constraint is -/// respected: -/// -/// ```rust -/// fn select<'short, 'long>(s1: &'short str, s2: &'long str, second: bool) -> &'short str -/// where -/// 'long: 'short, -/// { -/// if second { s2 } else { s1 } -/// } -/// -/// let outer = String::from("Long living ref"); -/// let longer = &outer; -/// { -/// let inner = String::from("Short living ref"); -/// let shorter = &inner; -/// -/// assert_eq!(select(shorter, longer, false), shorter); -/// assert_eq!(select(shorter, longer, true), longer); -/// } -/// ``` -/// -/// On the other hand, this will not compile because the `where 'b: 'a` clause -/// is missing: the `'b` lifetime is not known to live at least as long as `'a` -/// which means this function cannot ensure it always returns a valid reference: -/// -/// ```rust,compile_fail -/// fn select<'a, 'b>(s1: &'a str, s2: &'b str, second: bool) -> &'a str -/// { -/// if second { s2 } else { s1 } -/// } -/// ``` -/// -/// `where` can also be used to express more complicated constraints that cannot -/// be written with the `` syntax: -/// -/// ```rust -/// fn first_or_default(mut i: I) -> I::Item -/// where -/// I: Iterator, -/// I::Item: Default, -/// { -/// i.next().unwrap_or_else(I::Item::default) -/// } -/// -/// assert_eq!(first_or_default([1, 2, 3].into_iter()), 1); -/// assert_eq!(first_or_default(Vec::::new().into_iter()), 0); -/// ``` -/// -/// `where` is available anywhere generic and lifetime parameters are available, -/// as can be seen with the [`Cow`](crate::borrow::Cow) type from the standard -/// library: -/// -/// ```rust -/// # #![allow(dead_code)] -/// pub enum Cow<'a, B> -/// where -/// B: ToOwned + ?Sized, -/// { -/// Borrowed(&'a B), -/// Owned(::Owned), -/// } -/// ``` -/// -/// [RFC]: https://github.com/rust-lang/rfcs/blob/master/text/0135-where.md -mod where_keyword {} - -// 2018 Edition keywords - -#[doc(alias = "promise")] -#[doc(keyword = "async")] -// -/// Return a [`Future`] instead of blocking the current thread. -/// -/// Use `async` in front of `fn`, `closure`, or a `block` to turn the marked code into a `Future`. -/// As such the code will not be run immediately, but will only be evaluated when the returned -/// future is [`.await`]ed. -/// -/// We have written an [async book] detailing `async`/`await` and trade-offs compared to using threads. -/// -/// ## Editions -/// -/// `async` is a keyword from the 2018 edition onwards. -/// -/// It is available for use in stable Rust from version 1.39 onwards. -/// -/// [`Future`]: future::Future -/// [`.await`]: ../std/keyword.await.html -/// [async book]: https://rust-lang.github.io/async-book/ -mod async_keyword {} - -#[doc(keyword = "await")] -// -/// Suspend execution until the result of a [`Future`] is ready. -/// -/// `.await`ing a future will suspend the current function's execution until the executor -/// has run the future to completion. -/// -/// Read the [async book] for details on how [`async`]/`await` and executors work. -/// -/// ## Editions -/// -/// `await` is a keyword from the 2018 edition onwards. -/// -/// It is available for use in stable Rust from version 1.39 onwards. -/// -/// [`Future`]: future::Future -/// [async book]: https://rust-lang.github.io/async-book/ -/// [`async`]: ../std/keyword.async.html -mod await_keyword {} - -#[doc(keyword = "dyn")] -// -/// `dyn` is a prefix of a [trait object]'s type. -/// -/// The `dyn` keyword is used to highlight that calls to methods on the associated `Trait` -/// are [dynamically dispatched]. To use the trait this way, it must be 'object safe'. -/// -/// Unlike generic parameters or `impl Trait`, the compiler does not know the concrete type that -/// is being passed. That is, the type has been [erased]. -/// As such, a `dyn Trait` reference contains _two_ pointers. -/// One pointer goes to the data (e.g., an instance of a struct). -/// Another pointer goes to a map of method call names to function pointers -/// (known as a virtual method table or vtable). -/// -/// At run-time, when a method needs to be called on the `dyn Trait`, the vtable is consulted to get -/// the function pointer and then that function pointer is called. -/// -/// See the Reference for more information on [trait objects][ref-trait-obj] -/// and [object safety][ref-obj-safety]. -/// -/// ## Trade-offs -/// -/// The above indirection is the additional runtime cost of calling a function on a `dyn Trait`. -/// Methods called by dynamic dispatch generally cannot be inlined by the compiler. -/// -/// However, `dyn Trait` is likely to produce smaller code than `impl Trait` / generic parameters as -/// the method won't be duplicated for each concrete type. -/// -/// [trait object]: ../book/ch17-02-trait-objects.html -/// [dynamically dispatched]: https://en.wikipedia.org/wiki/Dynamic_dispatch -/// [ref-trait-obj]: ../reference/types/trait-object.html -/// [ref-obj-safety]: ../reference/items/traits.html#object-safety -/// [erased]: https://en.wikipedia.org/wiki/Type_erasure -mod dyn_keyword {} - -#[doc(keyword = "union")] -// -/// The [Rust equivalent of a C-style union][union]. -/// -/// A `union` looks like a [`struct`] in terms of declaration, but all of its -/// fields exist in the same memory, superimposed over one another. For instance, -/// if we wanted some bits in memory that we sometimes interpret as a `u32` and -/// sometimes as an `f32`, we could write: -/// -/// ```rust -/// union IntOrFloat { -/// i: u32, -/// f: f32, -/// } -/// -/// let mut u = IntOrFloat { f: 1.0 }; -/// // Reading the fields of a union is always unsafe -/// assert_eq!(unsafe { u.i }, 1065353216); -/// // Updating through any of the field will modify all of them -/// u.i = 1073741824; -/// assert_eq!(unsafe { u.f }, 2.0); -/// ``` -/// -/// # Matching on unions -/// -/// It is possible to use pattern matching on `union`s. A single field name must -/// be used and it must match the name of one of the `union`'s field. -/// Like reading from a `union`, pattern matching on a `union` requires `unsafe`. -/// -/// ```rust -/// union IntOrFloat { -/// i: u32, -/// f: f32, -/// } -/// -/// let u = IntOrFloat { f: 1.0 }; -/// -/// unsafe { -/// match u { -/// IntOrFloat { i: 10 } => println!("Found exactly ten!"), -/// // Matching the field `f` provides an `f32`. -/// IntOrFloat { f } => println!("Found f = {f} !"), -/// } -/// } -/// ``` -/// -/// # References to union fields -/// -/// All fields in a `union` are all at the same place in memory which means -/// borrowing one borrows the entire `union`, for the same lifetime: -/// -/// ```rust,compile_fail,E0502 -/// union IntOrFloat { -/// i: u32, -/// f: f32, -/// } -/// -/// let mut u = IntOrFloat { f: 1.0 }; -/// -/// let f = unsafe { &u.f }; -/// // This will not compile because the field has already been borrowed, even -/// // if only immutably -/// let i = unsafe { &mut u.i }; -/// -/// *i = 10; -/// println!("f = {f} and i = {i}"); -/// ``` -/// -/// See the [Reference][union] for more information on `union`s. -/// -/// [`struct`]: keyword.struct.html -/// [union]: ../reference/items/unions.html -mod union_keyword {} diff --git a/library/std/src/lib.miri.rs b/library/std/src/lib.miri.rs deleted file mode 100644 index 1f9bfb5b1b5c0..0000000000000 --- a/library/std/src/lib.miri.rs +++ /dev/null @@ -1,4 +0,0 @@ -//! Grep bootstrap for `MIRI_REPLACE_LIBRS_IF_NOT_TEST` to learn what this is about. -#![no_std] -extern crate std as realstd; -pub use realstd::*; diff --git a/library/std/src/lib.rs b/library/std/src/lib.rs deleted file mode 100644 index 4a18db3d5a3fc..0000000000000 --- a/library/std/src/lib.rs +++ /dev/null @@ -1,755 +0,0 @@ -//! # The Rust Standard Library -//! -//! The Rust Standard Library is the foundation of portable Rust software, a -//! set of minimal and battle-tested shared abstractions for the [broader Rust -//! ecosystem][crates.io]. It offers core types, like [`Vec`] and -//! [`Option`], library-defined [operations on language -//! primitives](#primitives), [standard macros](#macros), [I/O] and -//! [multithreading], among [many other things][other]. -//! -//! `std` is available to all Rust crates by default. Therefore, the -//! standard library can be accessed in [`use`] statements through the path -//! `std`, as in [`use std::env`]. -//! -//! # How to read this documentation -//! -//! If you already know the name of what you are looking for, the fastest way to -//! find it is to use the search -//! bar at the top of the page. -//! -//! Otherwise, you may want to jump to one of these useful sections: -//! -//! * [`std::*` modules](#modules) -//! * [Primitive types](#primitives) -//! * [Standard macros](#macros) -//! * [The Rust Prelude] -//! -//! If this is your first time, the documentation for the standard library is -//! written to be casually perused. Clicking on interesting things should -//! generally lead you to interesting places. Still, there are important bits -//! you don't want to miss, so read on for a tour of the standard library and -//! its documentation! -//! -//! Once you are familiar with the contents of the standard library you may -//! begin to find the verbosity of the prose distracting. At this stage in your -//! development you may want to press the `[-]` button near the top of the -//! page to collapse it into a more skimmable view. -//! -//! While you are looking at that `[-]` button also notice the `source` -//! link. Rust's API documentation comes with the source code and you are -//! encouraged to read it. The standard library source is generally high -//! quality and a peek behind the curtains is often enlightening. -//! -//! # What is in the standard library documentation? -//! -//! First of all, The Rust Standard Library is divided into a number of focused -//! modules, [all listed further down this page](#modules). These modules are -//! the bedrock upon which all of Rust is forged, and they have mighty names -//! like [`std::slice`] and [`std::cmp`]. Modules' documentation typically -//! includes an overview of the module along with examples, and are a smart -//! place to start familiarizing yourself with the library. -//! -//! Second, implicit methods on [primitive types] are documented here. This can -//! be a source of confusion for two reasons: -//! -//! 1. While primitives are implemented by the compiler, the standard library -//! implements methods directly on the primitive types (and it is the only -//! library that does so), which are [documented in the section on -//! primitives](#primitives). -//! 2. The standard library exports many modules *with the same name as -//! primitive types*. These define additional items related to the primitive -//! type, but not the all-important methods. -//! -//! So for example there is a [page for the primitive type -//! `i32`](primitive::i32) that lists all the methods that can be called on -//! 32-bit integers (very useful), and there is a [page for the module -//! `std::i32`] that documents the constant values [`MIN`] and [`MAX`] (rarely -//! useful). -//! -//! Note the documentation for the primitives [`str`] and [`[T]`][prim@slice] (also -//! called 'slice'). Many method calls on [`String`] and [`Vec`] are actually -//! calls to methods on [`str`] and [`[T]`][prim@slice] respectively, via [deref -//! coercions][deref-coercions]. -//! -//! Third, the standard library defines [The Rust Prelude], a small collection -//! of items - mostly traits - that are imported into every module of every -//! crate. The traits in the prelude are pervasive, making the prelude -//! documentation a good entry point to learning about the library. -//! -//! And finally, the standard library exports a number of standard macros, and -//! [lists them on this page](#macros) (technically, not all of the standard -//! macros are defined by the standard library - some are defined by the -//! compiler - but they are documented here the same). Like the prelude, the -//! standard macros are imported by default into all crates. -//! -//! # Contributing changes to the documentation -//! -//! Check out the Rust contribution guidelines [here]( -//! https://rustc-dev-guide.rust-lang.org/contributing.html#writing-documentation). -//! The source for this documentation can be found on -//! [GitHub](https://github.com/rust-lang/rust). -//! To contribute changes, make sure you read the guidelines first, then submit -//! pull-requests for your suggested changes. -//! -//! Contributions are appreciated! If you see a part of the docs that can be -//! improved, submit a PR, or chat with us first on [Discord][rust-discord] -//! #docs. -//! -//! # A Tour of The Rust Standard Library -//! -//! The rest of this crate documentation is dedicated to pointing out notable -//! features of The Rust Standard Library. -//! -//! ## Containers and collections -//! -//! The [`option`] and [`result`] modules define optional and error-handling -//! types, [`Option`] and [`Result`]. The [`iter`] module defines -//! Rust's iterator trait, [`Iterator`], which works with the [`for`] loop to -//! access collections. -//! -//! The standard library exposes three common ways to deal with contiguous -//! regions of memory: -//! -//! * [`Vec`] - A heap-allocated *vector* that is resizable at runtime. -//! * [`[T; N]`][prim@array] - An inline *array* with a fixed size at compile time. -//! * [`[T]`][prim@slice] - A dynamically sized *slice* into any other kind of contiguous -//! storage, whether heap-allocated or not. -//! -//! Slices can only be handled through some kind of *pointer*, and as such come -//! in many flavors such as: -//! -//! * `&[T]` - *shared slice* -//! * `&mut [T]` - *mutable slice* -//! * [`Box<[T]>`][owned slice] - *owned slice* -//! -//! [`str`], a UTF-8 string slice, is a primitive type, and the standard library -//! defines many methods for it. Rust [`str`]s are typically accessed as -//! immutable references: `&str`. Use the owned [`String`] for building and -//! mutating strings. -//! -//! For converting to strings use the [`format!`] macro, and for converting from -//! strings use the [`FromStr`] trait. -//! -//! Data may be shared by placing it in a reference-counted box or the [`Rc`] -//! type, and if further contained in a [`Cell`] or [`RefCell`], may be mutated -//! as well as shared. Likewise, in a concurrent setting it is common to pair an -//! atomically-reference-counted box, [`Arc`], with a [`Mutex`] to get the same -//! effect. -//! -//! The [`collections`] module defines maps, sets, linked lists and other -//! typical collection types, including the common [`HashMap`]. -//! -//! ## Platform abstractions and I/O -//! -//! Besides basic data types, the standard library is largely concerned with -//! abstracting over differences in common platforms, most notably Windows and -//! Unix derivatives. -//! -//! Common types of I/O, including [files], [TCP], and [UDP], are defined in -//! the [`io`], [`fs`], and [`net`] modules. -//! -//! The [`thread`] module contains Rust's threading abstractions. [`sync`] -//! contains further primitive shared memory types, including [`atomic`] and -//! [`mpsc`], which contains the channel types for message passing. -//! -//! # Use before and after `main()` -//! -//! Many parts of the standard library are expected to work before and after `main()`; -//! but this is not guaranteed or ensured by tests. It is recommended that you write your own tests -//! and run them on each platform you wish to support. -//! This means that use of `std` before/after main, especially of features that interact with the -//! OS or global state, is exempted from stability and portability guarantees and instead only -//! provided on a best-effort basis. Nevertheless bug reports are appreciated. -//! -//! On the other hand `core` and `alloc` are most likely to work in such environments with -//! the caveat that any hookable behavior such as panics, oom handling or allocators will also -//! depend on the compatibility of the hooks. -//! -//! Some features may also behave differently outside main, e.g. stdio could become unbuffered, -//! some panics might turn into aborts, backtraces might not get symbolicated or similar. -//! -//! Non-exhaustive list of known limitations: -//! -//! - after-main use of thread-locals, which also affects additional features: -//! - [`thread::current()`] -//! - [`thread::scope()`] -//! - [`sync::mpsc`] -//! - before-main stdio file descriptors are not guaranteed to be open on unix platforms -//! -//! -//! [I/O]: io -//! [`MIN`]: i32::MIN -//! [`MAX`]: i32::MAX -//! [page for the module `std::i32`]: crate::i32 -//! [TCP]: net::TcpStream -//! [The Rust Prelude]: prelude -//! [UDP]: net::UdpSocket -//! [`Arc`]: sync::Arc -//! [owned slice]: boxed -//! [`Cell`]: cell::Cell -//! [`FromStr`]: str::FromStr -//! [`HashMap`]: collections::HashMap -//! [`Mutex`]: sync::Mutex -//! [`Option`]: option::Option -//! [`Rc`]: rc::Rc -//! [`RefCell`]: cell::RefCell -//! [`Result`]: result::Result -//! [`Vec`]: vec::Vec -//! [`atomic`]: sync::atomic -//! [`for`]: ../book/ch03-05-control-flow.html#looping-through-a-collection-with-for -//! [`str`]: prim@str -//! [`mpsc`]: sync::mpsc -//! [`std::cmp`]: cmp -//! [`std::slice`]: mod@slice -//! [`use std::env`]: env/index.html -//! [`use`]: ../book/ch07-02-defining-modules-to-control-scope-and-privacy.html -//! [crates.io]: https://crates.io -//! [deref-coercions]: ../book/ch15-02-deref.html#implicit-deref-coercions-with-functions-and-methods -//! [files]: fs::File -//! [multithreading]: thread -//! [other]: #what-is-in-the-standard-library-documentation -//! [primitive types]: ../book/ch03-02-data-types.html -//! [rust-discord]: https://discord.gg/rust-lang -//! [array]: prim@array -//! [slice]: prim@slice - -#![cfg_attr(not(restricted_std), stable(feature = "rust1", since = "1.0.0"))] -#![cfg_attr( - restricted_std, - unstable( - feature = "restricted_std", - issue = "none", - reason = "You have attempted to use a standard library built for a platform that it doesn't \ - know how to support. Consider building it for a known environment, disabling it with \ - `#![no_std]` or overriding this warning by enabling this feature." - ) -)] -#![rustc_preserve_ub_checks] -#![doc( - html_playground_url = "https://play.rust-lang.org/", - issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/", - test(no_crate_inject, attr(deny(warnings))), - test(attr(allow(dead_code, deprecated, unused_variables, unused_mut))) -)] -#![doc(rust_logo)] -#![doc(cfg_hide( - not(test), - not(any(test, bootstrap)), - no_global_oom_handling, - not(no_global_oom_handling) -))] -// Don't link to std. We are std. -#![no_std] -// Tell the compiler to link to either panic_abort or panic_unwind -#![needs_panic_runtime] -// -// Lints: -#![warn(deprecated_in_future)] -#![warn(missing_docs)] -#![warn(missing_debug_implementations)] -#![allow(explicit_outlives_requirements)] -#![allow(unused_lifetimes)] -#![allow(internal_features)] -#![deny(rustc::existing_doc_keyword)] -#![deny(fuzzy_provenance_casts)] -#![allow(rustdoc::redundant_explicit_links)] -// Ensure that std can be linked against panic_abort despite compiled with `-C panic=unwind` -#![deny(ffi_unwind_calls)] -// std may use features in a platform-specific way -#![allow(unused_features)] -// -// Features: -#![cfg_attr(test, feature(internal_output_capture, print_internals, update_panic_count, rt))] -#![cfg_attr( - all(target_vendor = "fortanix", target_env = "sgx"), - feature(slice_index_methods, coerce_unsized, sgx_platform) -)] -#![cfg_attr(any(windows, target_os = "uefi"), feature(round_char_boundary))] -#![cfg_attr(target_family = "wasm", feature(stdarch_wasm_atomic_wait))] -#![cfg_attr( - all(any(target_arch = "x86_64", target_arch = "x86"), target_os = "uefi"), - feature(stdarch_x86_has_cpuid) -)] -// -// Language features: -// tidy-alphabetical-start -#![feature(alloc_error_handler)] -#![feature(allocator_internals)] -#![feature(allow_internal_unsafe)] -#![feature(allow_internal_unstable)] -#![feature(asm_experimental_arch)] -#![feature(c_unwind)] -#![feature(cfg_sanitizer_cfi)] -#![feature(cfg_target_thread_local)] -#![feature(cfi_encoding)] -#![feature(concat_idents)] -#![feature(const_mut_refs)] -#![feature(const_trait_impl)] -#![feature(decl_macro)] -#![feature(deprecated_suggestion)] -#![feature(doc_cfg)] -#![feature(doc_cfg_hide)] -#![feature(doc_masked)] -#![feature(doc_notable_trait)] -#![feature(dropck_eyepatch)] -#![feature(f128)] -#![feature(f16)] -#![feature(if_let_guard)] -#![feature(intra_doc_pointers)] -#![feature(lang_items)] -#![feature(let_chains)] -#![feature(link_cfg)] -#![feature(linkage)] -#![feature(min_exhaustive_patterns)] -#![feature(min_specialization)] -#![feature(must_not_suspend)] -#![feature(needs_panic_runtime)] -#![feature(negative_impls)] -#![feature(never_type)] -#![feature(no_sanitize)] -#![feature(prelude_import)] -#![feature(rustc_attrs)] -#![feature(rustdoc_internals)] -#![feature(staged_api)] -#![feature(thread_local)] -#![feature(try_blocks)] -#![feature(type_alias_impl_trait)] -// tidy-alphabetical-end -// -// Library features (core): -// tidy-alphabetical-start -#![feature(c_str_module)] -#![feature(char_internals)] -#![feature(core_intrinsics)] -#![feature(core_io_borrowed_buf)] -#![feature(duration_constants)] -#![feature(error_generic_member_access)] -#![feature(error_in_core)] -#![feature(error_iter)] -#![feature(exact_size_is_empty)] -#![feature(exclusive_wrapper)] -#![feature(exposed_provenance)] -#![feature(extend_one)] -#![feature(float_gamma)] -#![feature(float_minimum_maximum)] -#![feature(float_next_up_down)] -#![feature(fmt_internals)] -#![feature(hasher_prefixfree_extras)] -#![feature(hashmap_internals)] -#![feature(hint_assert_unchecked)] -#![feature(ip)] -#![feature(maybe_uninit_slice)] -#![feature(maybe_uninit_uninit_array)] -#![feature(maybe_uninit_write_slice)] -#![feature(panic_can_unwind)] -#![feature(panic_info_message)] -#![feature(panic_internals)] -#![feature(pointer_is_aligned_to)] -#![feature(portable_simd)] -#![feature(prelude_2024)] -#![feature(ptr_as_uninit)] -#![feature(ptr_mask)] -#![feature(slice_internals)] -#![feature(slice_ptr_get)] -#![feature(slice_range)] -#![feature(std_internals)] -#![feature(str_internals)] -#![feature(strict_provenance)] -#![feature(strict_provenance_atomic_ptr)] -#![feature(ub_checks)] -// tidy-alphabetical-end -// -// Library features (alloc): -// tidy-alphabetical-start -#![feature(alloc_layout_extra)] -#![feature(allocator_api)] -#![feature(get_mut_unchecked)] -#![feature(map_try_insert)] -#![feature(new_uninit)] -#![feature(slice_concat_trait)] -#![feature(thin_box)] -#![feature(try_reserve_kind)] -#![feature(vec_into_raw_parts)] -// tidy-alphabetical-end -// -// Library features (unwind): -// tidy-alphabetical-start -#![feature(panic_unwind)] -// tidy-alphabetical-end -// -// Library features (std_detect): -// tidy-alphabetical-start -#![feature(stdarch_internal)] -// tidy-alphabetical-end -// -// Only for re-exporting: -// tidy-alphabetical-start -#![feature(assert_matches)] -#![feature(async_iterator)] -#![feature(c_variadic)] -#![feature(cfg_accessible)] -#![feature(cfg_eval)] -#![feature(concat_bytes)] -#![feature(const_format_args)] -#![feature(custom_test_frameworks)] -#![feature(edition_panic)] -#![feature(format_args_nl)] -#![feature(get_many_mut)] -#![feature(lazy_cell)] -#![feature(log_syntax)] -#![feature(test)] -#![feature(trace_macros)] -// tidy-alphabetical-end -// -// Only used in tests/benchmarks: -// -// Only for const-ness: -// tidy-alphabetical-start -#![feature(const_collections_with_hasher)] -#![feature(const_hash)] -#![feature(const_ip)] -#![feature(const_ipv4)] -#![feature(const_ipv6)] -#![feature(const_maybe_uninit_uninit_array)] -#![feature(const_waker)] -#![feature(thread_local_internals)] -// tidy-alphabetical-end -// -#![default_lib_allocator] - -// Explicitly import the prelude. The compiler uses this same unstable attribute -// to import the prelude implicitly when building crates that depend on std. -#[prelude_import] -#[allow(unused)] -use prelude::rust_2021::*; - -// Access to Bencher, etc. -#[cfg(test)] -extern crate test; - -#[allow(unused_imports)] // macros from `alloc` are not used on all platforms -#[macro_use] -extern crate alloc as alloc_crate; - -// Many compiler tests depend on libc being pulled in by std -// so include it here even if it's unused. -#[doc(masked)] -#[allow(unused_extern_crates)] -#[cfg(not(all(windows, target_env = "msvc")))] -extern crate libc; - -// We always need an unwinder currently for backtraces -#[doc(masked)] -#[allow(unused_extern_crates)] -extern crate unwind; - -// FIXME: #94122 this extern crate definition only exist here to stop -// miniz_oxide docs leaking into std docs. Find better way to do it. -// Remove exclusion from tidy platform check when this removed. -#[doc(masked)] -#[allow(unused_extern_crates)] -#[cfg(all( - not(all(windows, target_env = "msvc", not(target_vendor = "uwp"))), - feature = "miniz_oxide" -))] -extern crate miniz_oxide; - -// During testing, this crate is not actually the "real" std library, but rather -// it links to the real std library, which was compiled from this same source -// code. So any lang items std defines are conditionally excluded (or else they -// would generate duplicate lang item errors), and any globals it defines are -// _not_ the globals used by "real" std. So this import, defined only during -// testing gives test-std access to real-std lang items and globals. See #2912 -#[cfg(test)] -extern crate std as realstd; - -// The standard macros that are not built-in to the compiler. -#[macro_use] -mod macros; - -// The runtime entry point and a few unstable public functions used by the -// compiler -#[macro_use] -pub mod rt; - -// The Rust prelude -pub mod prelude; - -// Public module declarations and re-exports -#[stable(feature = "rust1", since = "1.0.0")] -pub use alloc_crate::borrow; -#[stable(feature = "rust1", since = "1.0.0")] -pub use alloc_crate::boxed; -#[stable(feature = "rust1", since = "1.0.0")] -pub use alloc_crate::fmt; -#[stable(feature = "rust1", since = "1.0.0")] -pub use alloc_crate::format; -#[stable(feature = "rust1", since = "1.0.0")] -pub use alloc_crate::rc; -#[stable(feature = "rust1", since = "1.0.0")] -pub use alloc_crate::slice; -#[stable(feature = "rust1", since = "1.0.0")] -pub use alloc_crate::str; -#[stable(feature = "rust1", since = "1.0.0")] -pub use alloc_crate::string; -#[stable(feature = "rust1", since = "1.0.0")] -pub use alloc_crate::vec; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::any; -#[stable(feature = "core_array", since = "1.36.0")] -pub use core::array; -#[unstable(feature = "async_iterator", issue = "79024")] -pub use core::async_iter; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::cell; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::char; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::clone; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::cmp; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::convert; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::default; -#[stable(feature = "futures_api", since = "1.36.0")] -pub use core::future; -#[stable(feature = "core_hint", since = "1.27.0")] -pub use core::hint; -#[stable(feature = "i128", since = "1.26.0")] -#[allow(deprecated, deprecated_in_future)] -pub use core::i128; -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated, deprecated_in_future)] -pub use core::i16; -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated, deprecated_in_future)] -pub use core::i32; -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated, deprecated_in_future)] -pub use core::i64; -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated, deprecated_in_future)] -pub use core::i8; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::intrinsics; -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated, deprecated_in_future)] -pub use core::isize; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::iter; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::marker; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::mem; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::ops; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::option; -#[stable(feature = "pin", since = "1.33.0")] -pub use core::pin; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::ptr; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::result; -#[stable(feature = "i128", since = "1.26.0")] -#[allow(deprecated, deprecated_in_future)] -pub use core::u128; -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated, deprecated_in_future)] -pub use core::u16; -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated, deprecated_in_future)] -pub use core::u32; -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated, deprecated_in_future)] -pub use core::u64; -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated, deprecated_in_future)] -pub use core::u8; -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated, deprecated_in_future)] -pub use core::usize; - -#[unstable(feature = "f128", issue = "116909")] -pub mod f128; -#[unstable(feature = "f16", issue = "116909")] -pub mod f16; -pub mod f32; -pub mod f64; - -#[macro_use] -pub mod thread; -pub mod ascii; -pub mod backtrace; -pub mod collections; -pub mod env; -pub mod error; -pub mod ffi; -pub mod fs; -pub mod hash; -pub mod io; -pub mod net; -pub mod num; -pub mod os; -pub mod panic; -#[unstable(feature = "core_pattern_types", issue = "none")] -pub mod pat; -pub mod path; -pub mod process; -pub mod sync; -pub mod time; - -// Pull in `std_float` crate into std. The contents of -// `std_float` are in a different repository: rust-lang/portable-simd. -#[path = "../../portable-simd/crates/std_float/src/lib.rs"] -#[allow(missing_debug_implementations, dead_code, unsafe_op_in_unsafe_fn)] -#[allow(rustdoc::bare_urls)] -#[unstable(feature = "portable_simd", issue = "86656")] -mod std_float; - -#[unstable(feature = "portable_simd", issue = "86656")] -pub mod simd { - #![doc = include_str!("../../portable-simd/crates/core_simd/src/core_simd_docs.md")] - - #[doc(inline)] - pub use crate::std_float::StdFloat; - #[doc(inline)] - pub use core::simd::*; -} - -#[stable(feature = "futures_api", since = "1.36.0")] -pub mod task { - //! Types and Traits for working with asynchronous tasks. - - #[doc(inline)] - #[stable(feature = "futures_api", since = "1.36.0")] - pub use core::task::*; - - #[doc(inline)] - #[stable(feature = "wake_trait", since = "1.51.0")] - pub use alloc::task::*; -} - -#[doc = include_str!("../../stdarch/crates/core_arch/src/core_arch_docs.md")] -#[stable(feature = "simd_arch", since = "1.27.0")] -pub mod arch { - #[stable(feature = "simd_arch", since = "1.27.0")] - // The `no_inline`-attribute is required to make the documentation of all - // targets available. - // See https://github.com/rust-lang/rust/pull/57808#issuecomment-457390549 for - // more information. - #[doc(no_inline)] // Note (#82861): required for correct documentation - pub use core::arch::*; - - #[stable(feature = "simd_aarch64", since = "1.60.0")] - pub use std_detect::is_aarch64_feature_detected; - #[unstable(feature = "stdarch_arm_feature_detection", issue = "111190")] - pub use std_detect::is_arm_feature_detected; - #[unstable(feature = "is_riscv_feature_detected", issue = "111192")] - pub use std_detect::is_riscv_feature_detected; - #[stable(feature = "simd_x86", since = "1.27.0")] - pub use std_detect::is_x86_feature_detected; - #[unstable(feature = "stdarch_mips_feature_detection", issue = "111188")] - pub use std_detect::{is_mips64_feature_detected, is_mips_feature_detected}; - #[unstable(feature = "stdarch_powerpc_feature_detection", issue = "111191")] - pub use std_detect::{is_powerpc64_feature_detected, is_powerpc_feature_detected}; -} - -// This was stabilized in the crate root so we have to keep it there. -#[stable(feature = "simd_x86", since = "1.27.0")] -pub use std_detect::is_x86_feature_detected; - -// Platform-abstraction modules -mod sys; -mod sys_common; - -pub mod alloc; - -// Private support modules -mod panicking; - -#[path = "../../backtrace/src/lib.rs"] -#[allow(dead_code, unused_attributes, fuzzy_provenance_casts)] -mod backtrace_rs; - -// Re-export macros defined in core. -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated, deprecated_in_future)] -pub use core::{ - assert_eq, assert_ne, debug_assert, debug_assert_eq, debug_assert_ne, matches, todo, r#try, - unimplemented, unreachable, write, writeln, -}; - -// Re-export built-in macros defined through core. -#[stable(feature = "builtin_macro_prelude", since = "1.38.0")] -#[allow(deprecated)] -pub use core::{ - assert, assert_matches, cfg, column, compile_error, concat, concat_idents, const_format_args, - env, file, format_args, format_args_nl, include, include_bytes, include_str, line, log_syntax, - module_path, option_env, stringify, trace_macros, -}; - -#[unstable( - feature = "concat_bytes", - issue = "87555", - reason = "`concat_bytes` is not stable enough for use and is subject to change" -)] -pub use core::concat_bytes; - -#[unstable(feature = "cfg_match", issue = "115585")] -pub use core::cfg_match; - -#[stable(feature = "core_primitive", since = "1.43.0")] -pub use core::primitive; - -// Include a number of private modules that exist solely to provide -// the rustdoc documentation for primitive types. Using `include!` -// because rustdoc only looks for these modules at the crate level. -include!("../../core/src/primitive_docs.rs"); - -// Include a number of private modules that exist solely to provide -// the rustdoc documentation for the existing keywords. Using `include!` -// because rustdoc only looks for these modules at the crate level. -include!("keyword_docs.rs"); - -// This is required to avoid an unstable error when `restricted-std` is not -// enabled. The use of #![feature(restricted_std)] in rustc-std-workspace-std -// is unconditional, so the unstable feature needs to be defined somewhere. -#[unstable(feature = "restricted_std", issue = "none")] -mod __restricted_std_workaround {} - -mod sealed { - /// This trait being unreachable from outside the crate - /// prevents outside implementations of our extension traits. - /// This allows adding more trait methods in the future. - #[unstable(feature = "sealed", issue = "none")] - pub trait Sealed {} -} - -#[cfg(test)] -#[allow(dead_code)] // Not used in all configurations. -pub(crate) mod test_helpers { - /// Test-only replacement for `rand::thread_rng()`, which is unusable for - /// us, as we want to allow running stdlib tests on tier-3 targets which may - /// not have `getrandom` support. - /// - /// Does a bit of a song and dance to ensure that the seed is different on - /// each call (as some tests sadly rely on this), but doesn't try that hard. - /// - /// This is duplicated in the `core`, `alloc` test suites (as well as - /// `std`'s integration tests), but figuring out a mechanism to share these - /// seems far more painful than copy-pasting a 7 line function a couple - /// times, given that even under a perma-unstable feature, I don't think we - /// want to expose types from `rand` from `std`. - #[track_caller] - pub(crate) fn test_rng() -> rand_xorshift::XorShiftRng { - use core::hash::{BuildHasher, Hash, Hasher}; - let mut hasher = crate::hash::RandomState::new().build_hasher(); - core::panic::Location::caller().hash(&mut hasher); - let hc64 = hasher.finish(); - let seed_vec = hc64.to_le_bytes().into_iter().chain(0u8..8).collect::>(); - let seed: [u8; 16] = seed_vec.as_slice().try_into().unwrap(); - rand::SeedableRng::from_seed(seed) - } -} diff --git a/library/std/src/macros.rs b/library/std/src/macros.rs deleted file mode 100644 index 58df83bd79d23..0000000000000 --- a/library/std/src/macros.rs +++ /dev/null @@ -1,382 +0,0 @@ -//! Standard library macros -//! -//! This module contains a set of macros which are exported from the standard -//! library. Each macro is available for use when linking against the standard -//! library. -// ignore-tidy-dbg - -#[doc = include_str!("../../core/src/macros/panic.md")] -#[macro_export] -#[rustc_builtin_macro(std_panic)] -#[stable(feature = "rust1", since = "1.0.0")] -#[allow_internal_unstable(edition_panic)] -#[cfg_attr(not(test), rustc_diagnostic_item = "std_panic_macro")] -macro_rules! panic { - // Expands to either `$crate::panic::panic_2015` or `$crate::panic::panic_2021` - // depending on the edition of the caller. - ($($arg:tt)*) => { - /* compiler built-in */ - }; -} - -/// Prints to the standard output. -/// -/// Equivalent to the [`println!`] macro except that a newline is not printed at -/// the end of the message. -/// -/// Note that stdout is frequently line-buffered by default so it may be -/// necessary to use [`io::stdout().flush()`][flush] to ensure the output is emitted -/// immediately. -/// -/// The `print!` macro will lock the standard output on each call. If you call -/// `print!` within a hot loop, this behavior may be the bottleneck of the loop. -/// To avoid this, lock stdout with [`io::stdout().lock()`][lock]: -/// ``` -/// use std::io::{stdout, Write}; -/// -/// let mut lock = stdout().lock(); -/// write!(lock, "hello world").unwrap(); -/// ``` -/// -/// Use `print!` only for the primary output of your program. Use -/// [`eprint!`] instead to print error and progress messages. -/// -/// See [the formatting documentation in `std::fmt`](../std/fmt/index.html) -/// for details of the macro argument syntax. -/// -/// [flush]: crate::io::Write::flush -/// [`println!`]: crate::println -/// [`eprint!`]: crate::eprint -/// [lock]: crate::io::Stdout -/// -/// # Panics -/// -/// Panics if writing to `io::stdout()` fails. -/// -/// Writing to non-blocking stdout can cause an error, which will lead -/// this macro to panic. -/// -/// # Examples -/// -/// ``` -/// use std::io::{self, Write}; -/// -/// print!("this "); -/// print!("will "); -/// print!("be "); -/// print!("on "); -/// print!("the "); -/// print!("same "); -/// print!("line "); -/// -/// io::stdout().flush().unwrap(); -/// -/// print!("this string has a newline, why not choose println! instead?\n"); -/// -/// io::stdout().flush().unwrap(); -/// ``` -#[macro_export] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "print_macro")] -#[allow_internal_unstable(print_internals)] -macro_rules! print { - ($($arg:tt)*) => {{ - $crate::io::_print($crate::format_args!($($arg)*)); - }}; -} - -/// Prints to the standard output, with a newline. -/// -/// On all platforms, the newline is the LINE FEED character (`\n`/`U+000A`) alone -/// (no additional CARRIAGE RETURN (`\r`/`U+000D`)). -/// -/// This macro uses the same syntax as [`format!`], but writes to the standard output instead. -/// See [`std::fmt`] for more information. -/// -/// The `println!` macro will lock the standard output on each call. If you call -/// `println!` within a hot loop, this behavior may be the bottleneck of the loop. -/// To avoid this, lock stdout with [`io::stdout().lock()`][lock]: -/// ``` -/// use std::io::{stdout, Write}; -/// -/// let mut lock = stdout().lock(); -/// writeln!(lock, "hello world").unwrap(); -/// ``` -/// -/// Use `println!` only for the primary output of your program. Use -/// [`eprintln!`] instead to print error and progress messages. -/// -/// See [the formatting documentation in `std::fmt`](../std/fmt/index.html) -/// for details of the macro argument syntax. -/// -/// [`std::fmt`]: crate::fmt -/// [`eprintln!`]: crate::eprintln -/// [lock]: crate::io::Stdout -/// -/// # Panics -/// -/// Panics if writing to [`io::stdout`] fails. -/// -/// Writing to non-blocking stdout can cause an error, which will lead -/// this macro to panic. -/// -/// [`io::stdout`]: crate::io::stdout -/// -/// # Examples -/// -/// ``` -/// println!(); // prints just a newline -/// println!("hello there!"); -/// println!("format {} arguments", "some"); -/// let local_variable = "some"; -/// println!("format {local_variable} arguments"); -/// ``` -#[macro_export] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "println_macro")] -#[allow_internal_unstable(print_internals, format_args_nl)] -macro_rules! println { - () => { - $crate::print!("\n") - }; - ($($arg:tt)*) => {{ - $crate::io::_print($crate::format_args_nl!($($arg)*)); - }}; -} - -/// Prints to the standard error. -/// -/// Equivalent to the [`print!`] macro, except that output goes to -/// [`io::stderr`] instead of [`io::stdout`]. See [`print!`] for -/// example usage. -/// -/// Use `eprint!` only for error and progress messages. Use `print!` -/// instead for the primary output of your program. -/// -/// [`io::stderr`]: crate::io::stderr -/// [`io::stdout`]: crate::io::stdout -/// -/// See [the formatting documentation in `std::fmt`](../std/fmt/index.html) -/// for details of the macro argument syntax. -/// -/// # Panics -/// -/// Panics if writing to `io::stderr` fails. -/// -/// Writing to non-blocking stderr can cause an error, which will lead -/// this macro to panic. -/// -/// # Examples -/// -/// ``` -/// eprint!("Error: Could not complete task"); -/// ``` -#[macro_export] -#[stable(feature = "eprint", since = "1.19.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "eprint_macro")] -#[allow_internal_unstable(print_internals)] -macro_rules! eprint { - ($($arg:tt)*) => {{ - $crate::io::_eprint($crate::format_args!($($arg)*)); - }}; -} - -/// Prints to the standard error, with a newline. -/// -/// Equivalent to the [`println!`] macro, except that output goes to -/// [`io::stderr`] instead of [`io::stdout`]. See [`println!`] for -/// example usage. -/// -/// Use `eprintln!` only for error and progress messages. Use `println!` -/// instead for the primary output of your program. -/// -/// See [the formatting documentation in `std::fmt`](../std/fmt/index.html) -/// for details of the macro argument syntax. -/// -/// [`io::stderr`]: crate::io::stderr -/// [`io::stdout`]: crate::io::stdout -/// [`println!`]: crate::println -/// -/// # Panics -/// -/// Panics if writing to `io::stderr` fails. -/// -/// Writing to non-blocking stderr can cause an error, which will lead -/// this macro to panic. -/// -/// # Examples -/// -/// ``` -/// eprintln!("Error: Could not complete task"); -/// ``` -#[macro_export] -#[stable(feature = "eprint", since = "1.19.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "eprintln_macro")] -#[allow_internal_unstable(print_internals, format_args_nl)] -macro_rules! eprintln { - () => { - $crate::eprint!("\n") - }; - ($($arg:tt)*) => {{ - $crate::io::_eprint($crate::format_args_nl!($($arg)*)); - }}; -} - -/// Prints and returns the value of a given expression for quick and dirty -/// debugging. -/// -/// An example: -/// -/// ```rust -/// let a = 2; -/// let b = dbg!(a * 2) + 1; -/// // ^-- prints: [src/main.rs:2] a * 2 = 4 -/// assert_eq!(b, 5); -/// ``` -/// -/// The macro works by using the `Debug` implementation of the type of -/// the given expression to print the value to [stderr] along with the -/// source location of the macro invocation as well as the source code -/// of the expression. -/// -/// Invoking the macro on an expression moves and takes ownership of it -/// before returning the evaluated expression unchanged. If the type -/// of the expression does not implement `Copy` and you don't want -/// to give up ownership, you can instead borrow with `dbg!(&expr)` -/// for some expression `expr`. -/// -/// The `dbg!` macro works exactly the same in release builds. -/// This is useful when debugging issues that only occur in release -/// builds or when debugging in release mode is significantly faster. -/// -/// Note that the macro is intended as a debugging tool and therefore you -/// should avoid having uses of it in version control for long periods -/// (other than in tests and similar). -/// Debug output from production code is better done with other facilities -/// such as the [`debug!`] macro from the [`log`] crate. -/// -/// # Stability -/// -/// The exact output printed by this macro should not be relied upon -/// and is subject to future changes. -/// -/// # Panics -/// -/// Panics if writing to `io::stderr` fails. -/// -/// # Further examples -/// -/// With a method call: -/// -/// ```rust -/// fn foo(n: usize) { -/// if let Some(_) = dbg!(n.checked_sub(4)) { -/// // ... -/// } -/// } -/// -/// foo(3) -/// ``` -/// -/// This prints to [stderr]: -/// -/// ```text,ignore -/// [src/main.rs:4] n.checked_sub(4) = None -/// ``` -/// -/// Naive factorial implementation: -/// -/// ```rust -/// fn factorial(n: u32) -> u32 { -/// if dbg!(n <= 1) { -/// dbg!(1) -/// } else { -/// dbg!(n * factorial(n - 1)) -/// } -/// } -/// -/// dbg!(factorial(4)); -/// ``` -/// -/// This prints to [stderr]: -/// -/// ```text,ignore -/// [src/main.rs:3] n <= 1 = false -/// [src/main.rs:3] n <= 1 = false -/// [src/main.rs:3] n <= 1 = false -/// [src/main.rs:3] n <= 1 = true -/// [src/main.rs:4] 1 = 1 -/// [src/main.rs:5] n * factorial(n - 1) = 2 -/// [src/main.rs:5] n * factorial(n - 1) = 6 -/// [src/main.rs:5] n * factorial(n - 1) = 24 -/// [src/main.rs:11] factorial(4) = 24 -/// ``` -/// -/// The `dbg!(..)` macro moves the input: -/// -/// ```compile_fail -/// /// A wrapper around `usize` which importantly is not Copyable. -/// #[derive(Debug)] -/// struct NoCopy(usize); -/// -/// let a = NoCopy(42); -/// let _ = dbg!(a); // <-- `a` is moved here. -/// let _ = dbg!(a); // <-- `a` is moved again; error! -/// ``` -/// -/// You can also use `dbg!()` without a value to just print the -/// file and line whenever it's reached. -/// -/// Finally, if you want to `dbg!(..)` multiple values, it will treat them as -/// a tuple (and return it, too): -/// -/// ``` -/// assert_eq!(dbg!(1usize, 2u32), (1, 2)); -/// ``` -/// -/// However, a single argument with a trailing comma will still not be treated -/// as a tuple, following the convention of ignoring trailing commas in macro -/// invocations. You can use a 1-tuple directly if you need one: -/// -/// ``` -/// assert_eq!(1, dbg!(1u32,)); // trailing comma ignored -/// assert_eq!((1,), dbg!((1u32,))); // 1-tuple -/// ``` -/// -/// [stderr]: https://en.wikipedia.org/wiki/Standard_streams#Standard_error_(stderr) -/// [`debug!`]: https://docs.rs/log/*/log/macro.debug.html -/// [`log`]: https://crates.io/crates/log -#[macro_export] -#[cfg_attr(not(test), rustc_diagnostic_item = "dbg_macro")] -#[stable(feature = "dbg_macro", since = "1.32.0")] -macro_rules! dbg { - // NOTE: We cannot use `concat!` to make a static string as a format argument - // of `eprintln!` because `file!` could contain a `{` or - // `$val` expression could be a block (`{ .. }`), in which case the `eprintln!` - // will be malformed. - () => { - $crate::eprintln!("[{}:{}:{}]", $crate::file!(), $crate::line!(), $crate::column!()) - }; - ($val:expr $(,)?) => { - // Use of `match` here is intentional because it affects the lifetimes - // of temporaries - https://stackoverflow.com/a/48732525/1063961 - match $val { - tmp => { - $crate::eprintln!("[{}:{}:{}] {} = {:#?}", - $crate::file!(), $crate::line!(), $crate::column!(), $crate::stringify!($val), &tmp); - tmp - } - } - }; - ($($val:expr),+ $(,)?) => { - ($($crate::dbg!($val)),+,) - }; -} - -#[cfg(test)] -macro_rules! assert_approx_eq { - ($a:expr, $b:expr) => {{ - let (a, b) = (&$a, &$b); - assert!((*a - *b).abs() < 1.0e-6, "{} is not approximately equal to {}", *a, *b); - }}; -} diff --git a/library/std/src/net/ip_addr.rs b/library/std/src/net/ip_addr.rs deleted file mode 100644 index e167fbd1b9cf8..0000000000000 --- a/library/std/src/net/ip_addr.rs +++ /dev/null @@ -1,41 +0,0 @@ -// Tests for this module -#[cfg(all(test, not(target_os = "emscripten")))] -mod tests; - -use crate::sys::net::netc as c; -use crate::sys_common::{FromInner, IntoInner}; - -#[stable(feature = "ip_addr", since = "1.7.0")] -pub use core::net::IpAddr; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::net::{Ipv4Addr, Ipv6Addr}; - -#[unstable(feature = "ip", issue = "27709")] -pub use core::net::Ipv6MulticastScope; - -impl IntoInner for Ipv4Addr { - #[inline] - fn into_inner(self) -> c::in_addr { - // `s_addr` is stored as BE on all machines and the array is in BE order. - // So the native endian conversion method is used so that it's never swapped. - c::in_addr { s_addr: u32::from_ne_bytes(self.octets()) } - } -} -impl FromInner for Ipv4Addr { - fn from_inner(addr: c::in_addr) -> Ipv4Addr { - Ipv4Addr::from(addr.s_addr.to_ne_bytes()) - } -} - -impl IntoInner for Ipv6Addr { - fn into_inner(self) -> c::in6_addr { - c::in6_addr { s6_addr: self.octets() } - } -} -impl FromInner for Ipv6Addr { - #[inline] - fn from_inner(addr: c::in6_addr) -> Ipv6Addr { - Ipv6Addr::from(addr.s6_addr) - } -} diff --git a/library/std/src/net/ip_addr/tests.rs b/library/std/src/net/ip_addr/tests.rs deleted file mode 100644 index ab99c0c2fcc16..0000000000000 --- a/library/std/src/net/ip_addr/tests.rs +++ /dev/null @@ -1,8 +0,0 @@ -use crate::net::test::{sa4, tsa}; -use crate::net::Ipv4Addr; - -#[test] -fn to_socket_addr_socketaddr() { - let a = sa4(Ipv4Addr::new(77, 88, 21, 11), 12345); - assert_eq!(Ok(vec![a]), tsa(a)); -} diff --git a/library/std/src/net/mod.rs b/library/std/src/net/mod.rs deleted file mode 100644 index bcab15db35b5c..0000000000000 --- a/library/std/src/net/mod.rs +++ /dev/null @@ -1,89 +0,0 @@ -//! Networking primitives for TCP/UDP communication. -//! -//! This module provides networking functionality for the Transmission Control and User -//! Datagram Protocols, as well as types for IP and socket addresses. -//! -//! # Organization -//! -//! * [`TcpListener`] and [`TcpStream`] provide functionality for communication over TCP -//! * [`UdpSocket`] provides functionality for communication over UDP -//! * [`IpAddr`] represents IP addresses of either IPv4 or IPv6; [`Ipv4Addr`] and -//! [`Ipv6Addr`] are respectively IPv4 and IPv6 addresses -//! * [`SocketAddr`] represents socket addresses of either IPv4 or IPv6; [`SocketAddrV4`] -//! and [`SocketAddrV6`] are respectively IPv4 and IPv6 socket addresses -//! * [`ToSocketAddrs`] is a trait that is used for generic address resolution when interacting -//! with networking objects like [`TcpListener`], [`TcpStream`] or [`UdpSocket`] -//! * Other types are return or parameter types for various methods in this module -//! -//! Rust disables inheritance of socket objects to child processes by default when possible. For -//! example, through the use of the `CLOEXEC` flag in UNIX systems or the `HANDLE_FLAG_INHERIT` -//! flag on Windows. - -#![stable(feature = "rust1", since = "1.0.0")] - -use crate::io::{self, ErrorKind}; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::ip_addr::{IpAddr, Ipv4Addr, Ipv6Addr, Ipv6MulticastScope}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::socket_addr::{SocketAddr, SocketAddrV4, SocketAddrV6, ToSocketAddrs}; -#[unstable(feature = "tcplistener_into_incoming", issue = "88339")] -pub use self::tcp::IntoIncoming; -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::tcp::{Incoming, TcpListener, TcpStream}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::udp::UdpSocket; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::net::AddrParseError; - -mod ip_addr; -mod socket_addr; -mod tcp; -#[cfg(test)] -pub(crate) mod test; -mod udp; - -/// Possible values which can be passed to the [`TcpStream::shutdown`] method. -#[derive(Copy, Clone, PartialEq, Eq, Debug)] -#[stable(feature = "rust1", since = "1.0.0")] -pub enum Shutdown { - /// The reading portion of the [`TcpStream`] should be shut down. - /// - /// All currently blocked and future [reads] will return [Ok]\(0). - /// - /// [reads]: crate::io::Read "io::Read" - #[stable(feature = "rust1", since = "1.0.0")] - Read, - /// The writing portion of the [`TcpStream`] should be shut down. - /// - /// All currently blocked and future [writes] will return an error. - /// - /// [writes]: crate::io::Write "io::Write" - #[stable(feature = "rust1", since = "1.0.0")] - Write, - /// Both the reading and the writing portions of the [`TcpStream`] should be shut down. - /// - /// See [`Shutdown::Read`] and [`Shutdown::Write`] for more information. - #[stable(feature = "rust1", since = "1.0.0")] - Both, -} - -fn each_addr(addr: A, mut f: F) -> io::Result -where - F: FnMut(io::Result<&SocketAddr>) -> io::Result, -{ - let addrs = match addr.to_socket_addrs() { - Ok(addrs) => addrs, - Err(e) => return f(Err(e)), - }; - let mut last_err = None; - for addr in addrs { - match f(Ok(&addr)) { - Ok(l) => return Ok(l), - Err(e) => last_err = Some(e), - } - } - Err(last_err.unwrap_or_else(|| { - io::const_io_error!(ErrorKind::InvalidInput, "could not resolve to any addresses") - })) -} diff --git a/library/std/src/net/socket_addr.rs b/library/std/src/net/socket_addr.rs deleted file mode 100644 index 421fed9077c5b..0000000000000 --- a/library/std/src/net/socket_addr.rs +++ /dev/null @@ -1,315 +0,0 @@ -// Tests for this module -#[cfg(all(test, not(target_os = "emscripten")))] -mod tests; - -use crate::io; -use crate::iter; -use crate::mem; -use crate::net::{IpAddr, Ipv4Addr, Ipv6Addr}; -use crate::option; -use crate::slice; -use crate::sys::net::netc as c; -use crate::sys_common::net::LookupHost; -use crate::sys_common::{FromInner, IntoInner}; -use crate::vec; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::net::{SocketAddr, SocketAddrV4, SocketAddrV6}; - -impl FromInner for SocketAddrV4 { - fn from_inner(addr: c::sockaddr_in) -> SocketAddrV4 { - SocketAddrV4::new(Ipv4Addr::from_inner(addr.sin_addr), u16::from_be(addr.sin_port)) - } -} - -impl FromInner for SocketAddrV6 { - fn from_inner(addr: c::sockaddr_in6) -> SocketAddrV6 { - SocketAddrV6::new( - Ipv6Addr::from_inner(addr.sin6_addr), - u16::from_be(addr.sin6_port), - addr.sin6_flowinfo, - addr.sin6_scope_id, - ) - } -} - -impl IntoInner for SocketAddrV4 { - fn into_inner(self) -> c::sockaddr_in { - c::sockaddr_in { - sin_family: c::AF_INET as c::sa_family_t, - sin_port: self.port().to_be(), - sin_addr: self.ip().into_inner(), - ..unsafe { mem::zeroed() } - } - } -} - -impl IntoInner for SocketAddrV6 { - fn into_inner(self) -> c::sockaddr_in6 { - c::sockaddr_in6 { - sin6_family: c::AF_INET6 as c::sa_family_t, - sin6_port: self.port().to_be(), - sin6_addr: self.ip().into_inner(), - sin6_flowinfo: self.flowinfo(), - sin6_scope_id: self.scope_id(), - ..unsafe { mem::zeroed() } - } - } -} - -/// A trait for objects which can be converted or resolved to one or more -/// [`SocketAddr`] values. -/// -/// This trait is used for generic address resolution when constructing network -/// objects. By default it is implemented for the following types: -/// -/// * [`SocketAddr`]: [`to_socket_addrs`] is the identity function. -/// -/// * [`SocketAddrV4`], [`SocketAddrV6`], ([IpAddr], [u16]), -/// ([Ipv4Addr], [u16]), ([Ipv6Addr], [u16]): -/// [`to_socket_addrs`] constructs a [`SocketAddr`] trivially. -/// -/// * (&[str], [u16]): &[str] should be either a string representation -/// of an [`IpAddr`] address as expected by [`FromStr`] implementation or a host -/// name. [`u16`] is the port number. -/// -/// * &[str]: the string should be either a string representation of a -/// [`SocketAddr`] as expected by its [`FromStr`] implementation or a string like -/// `:` pair where `` is a [`u16`] value. -/// -/// This trait allows constructing network objects like [`TcpStream`] or -/// [`UdpSocket`] easily with values of various types for the bind/connection -/// address. It is needed because sometimes one type is more appropriate than -/// the other: for simple uses a string like `"localhost:12345"` is much nicer -/// than manual construction of the corresponding [`SocketAddr`], but sometimes -/// [`SocketAddr`] value is *the* main source of the address, and converting it to -/// some other type (e.g., a string) just for it to be converted back to -/// [`SocketAddr`] in constructor methods is pointless. -/// -/// Addresses returned by the operating system that are not IP addresses are -/// silently ignored. -/// -/// [`FromStr`]: crate::str::FromStr "std::str::FromStr" -/// [`TcpStream`]: crate::net::TcpStream "net::TcpStream" -/// [`to_socket_addrs`]: ToSocketAddrs::to_socket_addrs -/// [`UdpSocket`]: crate::net::UdpSocket "net::UdpSocket" -/// -/// # Examples -/// -/// Creating a [`SocketAddr`] iterator that yields one item: -/// -/// ``` -/// use std::net::{ToSocketAddrs, SocketAddr}; -/// -/// let addr = SocketAddr::from(([127, 0, 0, 1], 443)); -/// let mut addrs_iter = addr.to_socket_addrs().unwrap(); -/// -/// assert_eq!(Some(addr), addrs_iter.next()); -/// assert!(addrs_iter.next().is_none()); -/// ``` -/// -/// Creating a [`SocketAddr`] iterator from a hostname: -/// -/// ```no_run -/// use std::net::{SocketAddr, ToSocketAddrs}; -/// -/// // assuming 'localhost' resolves to 127.0.0.1 -/// let mut addrs_iter = "localhost:443".to_socket_addrs().unwrap(); -/// assert_eq!(addrs_iter.next(), Some(SocketAddr::from(([127, 0, 0, 1], 443)))); -/// assert!(addrs_iter.next().is_none()); -/// -/// // assuming 'foo' does not resolve -/// assert!("foo:443".to_socket_addrs().is_err()); -/// ``` -/// -/// Creating a [`SocketAddr`] iterator that yields multiple items: -/// -/// ``` -/// use std::net::{SocketAddr, ToSocketAddrs}; -/// -/// let addr1 = SocketAddr::from(([0, 0, 0, 0], 80)); -/// let addr2 = SocketAddr::from(([127, 0, 0, 1], 443)); -/// let addrs = vec![addr1, addr2]; -/// -/// let mut addrs_iter = (&addrs[..]).to_socket_addrs().unwrap(); -/// -/// assert_eq!(Some(addr1), addrs_iter.next()); -/// assert_eq!(Some(addr2), addrs_iter.next()); -/// assert!(addrs_iter.next().is_none()); -/// ``` -/// -/// Attempting to create a [`SocketAddr`] iterator from an improperly formatted -/// socket address `&str` (missing the port): -/// -/// ``` -/// use std::io; -/// use std::net::ToSocketAddrs; -/// -/// let err = "127.0.0.1".to_socket_addrs().unwrap_err(); -/// assert_eq!(err.kind(), io::ErrorKind::InvalidInput); -/// ``` -/// -/// [`TcpStream::connect`] is an example of an function that utilizes -/// `ToSocketAddrs` as a trait bound on its parameter in order to accept -/// different types: -/// -/// ```no_run -/// use std::net::{TcpStream, Ipv4Addr}; -/// -/// let stream = TcpStream::connect(("127.0.0.1", 443)); -/// // or -/// let stream = TcpStream::connect("127.0.0.1:443"); -/// // or -/// let stream = TcpStream::connect((Ipv4Addr::new(127, 0, 0, 1), 443)); -/// ``` -/// -/// [`TcpStream::connect`]: crate::net::TcpStream::connect -#[stable(feature = "rust1", since = "1.0.0")] -pub trait ToSocketAddrs { - /// Returned iterator over socket addresses which this type may correspond - /// to. - #[stable(feature = "rust1", since = "1.0.0")] - type Iter: Iterator; - - /// Converts this object to an iterator of resolved [`SocketAddr`]s. - /// - /// The returned iterator might not actually yield any values depending on the - /// outcome of any resolution performed. - /// - /// Note that this function may block the current thread while resolution is - /// performed. - #[stable(feature = "rust1", since = "1.0.0")] - fn to_socket_addrs(&self) -> io::Result; -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ToSocketAddrs for SocketAddr { - type Iter = option::IntoIter; - fn to_socket_addrs(&self) -> io::Result> { - Ok(Some(*self).into_iter()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ToSocketAddrs for SocketAddrV4 { - type Iter = option::IntoIter; - fn to_socket_addrs(&self) -> io::Result> { - SocketAddr::V4(*self).to_socket_addrs() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ToSocketAddrs for SocketAddrV6 { - type Iter = option::IntoIter; - fn to_socket_addrs(&self) -> io::Result> { - SocketAddr::V6(*self).to_socket_addrs() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ToSocketAddrs for (IpAddr, u16) { - type Iter = option::IntoIter; - fn to_socket_addrs(&self) -> io::Result> { - let (ip, port) = *self; - match ip { - IpAddr::V4(ref a) => (*a, port).to_socket_addrs(), - IpAddr::V6(ref a) => (*a, port).to_socket_addrs(), - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ToSocketAddrs for (Ipv4Addr, u16) { - type Iter = option::IntoIter; - fn to_socket_addrs(&self) -> io::Result> { - let (ip, port) = *self; - SocketAddrV4::new(ip, port).to_socket_addrs() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ToSocketAddrs for (Ipv6Addr, u16) { - type Iter = option::IntoIter; - fn to_socket_addrs(&self) -> io::Result> { - let (ip, port) = *self; - SocketAddrV6::new(ip, port, 0, 0).to_socket_addrs() - } -} - -fn resolve_socket_addr(lh: LookupHost) -> io::Result> { - let p = lh.port(); - let v: Vec<_> = lh - .map(|mut a| { - a.set_port(p); - a - }) - .collect(); - Ok(v.into_iter()) -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ToSocketAddrs for (&str, u16) { - type Iter = vec::IntoIter; - fn to_socket_addrs(&self) -> io::Result> { - let (host, port) = *self; - - // try to parse the host as a regular IP address first - if let Ok(addr) = host.parse::() { - let addr = SocketAddrV4::new(addr, port); - return Ok(vec![SocketAddr::V4(addr)].into_iter()); - } - if let Ok(addr) = host.parse::() { - let addr = SocketAddrV6::new(addr, port, 0, 0); - return Ok(vec![SocketAddr::V6(addr)].into_iter()); - } - - resolve_socket_addr((host, port).try_into()?) - } -} - -#[stable(feature = "string_u16_to_socket_addrs", since = "1.46.0")] -impl ToSocketAddrs for (String, u16) { - type Iter = vec::IntoIter; - fn to_socket_addrs(&self) -> io::Result> { - (&*self.0, self.1).to_socket_addrs() - } -} - -// accepts strings like 'localhost:12345' -#[stable(feature = "rust1", since = "1.0.0")] -impl ToSocketAddrs for str { - type Iter = vec::IntoIter; - fn to_socket_addrs(&self) -> io::Result> { - // try to parse as a regular SocketAddr first - if let Ok(addr) = self.parse() { - return Ok(vec![addr].into_iter()); - } - - resolve_socket_addr(self.try_into()?) - } -} - -#[stable(feature = "slice_to_socket_addrs", since = "1.8.0")] -impl<'a> ToSocketAddrs for &'a [SocketAddr] { - type Iter = iter::Cloned>; - - fn to_socket_addrs(&self) -> io::Result { - Ok(self.iter().cloned()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ToSocketAddrs for &T { - type Iter = T::Iter; - fn to_socket_addrs(&self) -> io::Result { - (**self).to_socket_addrs() - } -} - -#[stable(feature = "string_to_socket_addrs", since = "1.16.0")] -impl ToSocketAddrs for String { - type Iter = vec::IntoIter; - fn to_socket_addrs(&self) -> io::Result> { - (&**self).to_socket_addrs() - } -} diff --git a/library/std/src/net/socket_addr/tests.rs b/library/std/src/net/socket_addr/tests.rs deleted file mode 100644 index 6a065cfba2105..0000000000000 --- a/library/std/src/net/socket_addr/tests.rs +++ /dev/null @@ -1,306 +0,0 @@ -use crate::net::test::{sa4, sa6, tsa}; -use crate::net::*; - -#[test] -fn to_socket_addr_ipaddr_u16() { - let a = Ipv4Addr::new(77, 88, 21, 11); - let p = 12345; - let e = SocketAddr::V4(SocketAddrV4::new(a, p)); - assert_eq!(Ok(vec![e]), tsa((a, p))); -} - -#[test] -fn to_socket_addr_str_u16() { - let a = sa4(Ipv4Addr::new(77, 88, 21, 11), 24352); - assert_eq!(Ok(vec![a]), tsa(("77.88.21.11", 24352))); - - let a = sa6(Ipv6Addr::new(0x2a02, 0x6b8, 0, 1, 0, 0, 0, 1), 53); - assert_eq!(Ok(vec![a]), tsa(("2a02:6b8:0:1::1", 53))); - - let a = sa4(Ipv4Addr::new(127, 0, 0, 1), 23924); - #[cfg(not(target_env = "sgx"))] - assert!(tsa(("localhost", 23924)).unwrap().contains(&a)); - #[cfg(target_env = "sgx")] - let _ = a; -} - -#[test] -fn to_socket_addr_str() { - let a = sa4(Ipv4Addr::new(77, 88, 21, 11), 24352); - assert_eq!(Ok(vec![a]), tsa("77.88.21.11:24352")); - - let a = sa6(Ipv6Addr::new(0x2a02, 0x6b8, 0, 1, 0, 0, 0, 1), 53); - assert_eq!(Ok(vec![a]), tsa("[2a02:6b8:0:1::1]:53")); - - let a = sa4(Ipv4Addr::new(127, 0, 0, 1), 23924); - #[cfg(not(target_env = "sgx"))] - assert!(tsa("localhost:23924").unwrap().contains(&a)); - #[cfg(target_env = "sgx")] - let _ = a; -} - -#[test] -fn to_socket_addr_string() { - let a = sa4(Ipv4Addr::new(77, 88, 21, 11), 24352); - assert_eq!(Ok(vec![a]), tsa(&*format!("{}:{}", "77.88.21.11", "24352"))); - assert_eq!(Ok(vec![a]), tsa(&format!("{}:{}", "77.88.21.11", "24352"))); - assert_eq!(Ok(vec![a]), tsa(format!("{}:{}", "77.88.21.11", "24352"))); - - let s = format!("{}:{}", "77.88.21.11", "24352"); - assert_eq!(Ok(vec![a]), tsa(s)); - // s has been moved into the tsa call -} - -#[test] -fn ipv4_socket_addr_to_string() { - // Shortest possible IPv4 length. - assert_eq!(SocketAddrV4::new(Ipv4Addr::new(0, 0, 0, 0), 0).to_string(), "0.0.0.0:0"); - - // Longest possible IPv4 length. - assert_eq!( - SocketAddrV4::new(Ipv4Addr::new(255, 255, 255, 255), u16::MAX).to_string(), - "255.255.255.255:65535" - ); - - // Test padding. - assert_eq!( - format!("{:16}", SocketAddrV4::new(Ipv4Addr::new(1, 1, 1, 1), 53)), - "1.1.1.1:53 " - ); - assert_eq!( - format!("{:>16}", SocketAddrV4::new(Ipv4Addr::new(1, 1, 1, 1), 53)), - " 1.1.1.1:53" - ); -} - -#[test] -fn ipv6_socket_addr_to_string() { - // IPv4-mapped address. - assert_eq!( - SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc000, 0x280), 8080, 0, 0) - .to_string(), - "[::ffff:192.0.2.128]:8080" - ); - - // IPv4-compatible address. - assert_eq!( - SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0xc000, 0x280), 8080, 0, 0).to_string(), - "[::c000:280]:8080" - ); - - // IPv6 address with no zero segments. - assert_eq!( - SocketAddrV6::new(Ipv6Addr::new(8, 9, 10, 11, 12, 13, 14, 15), 80, 0, 0).to_string(), - "[8:9:a:b:c:d:e:f]:80" - ); - - // Shortest possible IPv6 length. - assert_eq!(SocketAddrV6::new(Ipv6Addr::UNSPECIFIED, 0, 0, 0).to_string(), "[::]:0"); - - // Longest possible IPv6 length. - assert_eq!( - SocketAddrV6::new( - Ipv6Addr::new(0x1111, 0x2222, 0x3333, 0x4444, 0x5555, 0x6666, 0x7777, 0x8888), - u16::MAX, - u32::MAX, - u32::MAX, - ) - .to_string(), - "[1111:2222:3333:4444:5555:6666:7777:8888%4294967295]:65535" - ); - - // Test padding. - assert_eq!( - format!("{:22}", SocketAddrV6::new(Ipv6Addr::new(1, 2, 3, 4, 5, 6, 7, 8), 9, 0, 0)), - "[1:2:3:4:5:6:7:8]:9 " - ); - assert_eq!( - format!("{:>22}", SocketAddrV6::new(Ipv6Addr::new(1, 2, 3, 4, 5, 6, 7, 8), 9, 0, 0)), - " [1:2:3:4:5:6:7:8]:9" - ); -} - -#[test] -fn bind_udp_socket_bad() { - // rust-lang/rust#53957: This is a regression test for a parsing problem - // discovered as part of issue rust-lang/rust#23076, where we were - // incorrectly parsing invalid input and then that would result in a - // successful `UdpSocket` binding when we would expect failure. - // - // At one time, this test was written as a call to `tsa` with - // INPUT_23076. However, that structure yields an unreliable test, - // because it ends up passing junk input to the DNS server, and some DNS - // servers will respond with `Ok` to such input, with the ip address of - // the DNS server itself. - // - // This form of the test is more robust: even when the DNS server - // returns its own address, it is still an error to bind a UDP socket to - // a non-local address, and so we still get an error here in that case. - - const INPUT_23076: &str = "1200::AB00:1234::2552:7777:1313:34300"; - - assert!(crate::net::UdpSocket::bind(INPUT_23076).is_err()) -} - -#[test] -fn set_ip() { - fn ip4(low: u8) -> Ipv4Addr { - Ipv4Addr::new(77, 88, 21, low) - } - fn ip6(low: u16) -> Ipv6Addr { - Ipv6Addr::new(0x2a02, 0x6b8, 0, 1, 0, 0, 0, low) - } - - let mut v4 = SocketAddrV4::new(ip4(11), 80); - assert_eq!(v4.ip(), &ip4(11)); - v4.set_ip(ip4(12)); - assert_eq!(v4.ip(), &ip4(12)); - - let mut addr = SocketAddr::V4(v4); - assert_eq!(addr.ip(), IpAddr::V4(ip4(12))); - addr.set_ip(IpAddr::V4(ip4(13))); - assert_eq!(addr.ip(), IpAddr::V4(ip4(13))); - addr.set_ip(IpAddr::V6(ip6(14))); - assert_eq!(addr.ip(), IpAddr::V6(ip6(14))); - - let mut v6 = SocketAddrV6::new(ip6(1), 80, 0, 0); - assert_eq!(v6.ip(), &ip6(1)); - v6.set_ip(ip6(2)); - assert_eq!(v6.ip(), &ip6(2)); - - let mut addr = SocketAddr::V6(v6); - assert_eq!(addr.ip(), IpAddr::V6(ip6(2))); - addr.set_ip(IpAddr::V6(ip6(3))); - assert_eq!(addr.ip(), IpAddr::V6(ip6(3))); - addr.set_ip(IpAddr::V4(ip4(4))); - assert_eq!(addr.ip(), IpAddr::V4(ip4(4))); -} - -#[test] -fn set_port() { - let mut v4 = SocketAddrV4::new(Ipv4Addr::new(77, 88, 21, 11), 80); - assert_eq!(v4.port(), 80); - v4.set_port(443); - assert_eq!(v4.port(), 443); - - let mut addr = SocketAddr::V4(v4); - assert_eq!(addr.port(), 443); - addr.set_port(8080); - assert_eq!(addr.port(), 8080); - - let mut v6 = SocketAddrV6::new(Ipv6Addr::new(0x2a02, 0x6b8, 0, 1, 0, 0, 0, 1), 80, 0, 0); - assert_eq!(v6.port(), 80); - v6.set_port(443); - assert_eq!(v6.port(), 443); - - let mut addr = SocketAddr::V6(v6); - assert_eq!(addr.port(), 443); - addr.set_port(8080); - assert_eq!(addr.port(), 8080); -} - -#[test] -fn set_flowinfo() { - let mut v6 = SocketAddrV6::new(Ipv6Addr::new(0x2a02, 0x6b8, 0, 1, 0, 0, 0, 1), 80, 10, 0); - assert_eq!(v6.flowinfo(), 10); - v6.set_flowinfo(20); - assert_eq!(v6.flowinfo(), 20); -} - -#[test] -fn set_scope_id() { - let mut v6 = SocketAddrV6::new(Ipv6Addr::new(0x2a02, 0x6b8, 0, 1, 0, 0, 0, 1), 80, 0, 10); - assert_eq!(v6.scope_id(), 10); - v6.set_scope_id(20); - assert_eq!(v6.scope_id(), 20); -} - -#[test] -fn is_v4() { - let v4 = SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(77, 88, 21, 11), 80)); - assert!(v4.is_ipv4()); - assert!(!v4.is_ipv6()); -} - -#[test] -fn is_v6() { - let v6 = SocketAddr::V6(SocketAddrV6::new( - Ipv6Addr::new(0x2a02, 0x6b8, 0, 1, 0, 0, 0, 1), - 80, - 10, - 0, - )); - assert!(!v6.is_ipv4()); - assert!(v6.is_ipv6()); -} - -#[test] -fn socket_v4_to_str() { - let socket = SocketAddrV4::new(Ipv4Addr::new(192, 168, 0, 1), 8080); - - assert_eq!(format!("{socket}"), "192.168.0.1:8080"); - assert_eq!(format!("{socket:<20}"), "192.168.0.1:8080 "); - assert_eq!(format!("{socket:>20}"), " 192.168.0.1:8080"); - assert_eq!(format!("{socket:^20}"), " 192.168.0.1:8080 "); - assert_eq!(format!("{socket:.10}"), "192.168.0."); -} - -#[test] -fn socket_v6_to_str() { - let mut socket = SocketAddrV6::new(Ipv6Addr::new(0x2a02, 0x6b8, 0, 1, 0, 0, 0, 1), 53, 0, 0); - - assert_eq!(format!("{socket}"), "[2a02:6b8:0:1::1]:53"); - assert_eq!(format!("{socket:<24}"), "[2a02:6b8:0:1::1]:53 "); - assert_eq!(format!("{socket:>24}"), " [2a02:6b8:0:1::1]:53"); - assert_eq!(format!("{socket:^24}"), " [2a02:6b8:0:1::1]:53 "); - assert_eq!(format!("{socket:.15}"), "[2a02:6b8:0:1::"); - - socket.set_scope_id(5); - - assert_eq!(format!("{socket}"), "[2a02:6b8:0:1::1%5]:53"); - assert_eq!(format!("{socket:<24}"), "[2a02:6b8:0:1::1%5]:53 "); - assert_eq!(format!("{socket:>24}"), " [2a02:6b8:0:1::1%5]:53"); - assert_eq!(format!("{socket:^24}"), " [2a02:6b8:0:1::1%5]:53 "); - assert_eq!(format!("{socket:.18}"), "[2a02:6b8:0:1::1%5"); -} - -#[test] -fn compare() { - let v4_1 = "224.120.45.1:23456".parse::().unwrap(); - let v4_2 = "224.210.103.5:12345".parse::().unwrap(); - let v4_3 = "224.210.103.5:23456".parse::().unwrap(); - let v6_1 = "[2001:db8:f00::1002]:23456".parse::().unwrap(); - let v6_2 = "[2001:db8:f00::2001]:12345".parse::().unwrap(); - let v6_3 = "[2001:db8:f00::2001]:23456".parse::().unwrap(); - - // equality - assert_eq!(v4_1, v4_1); - assert_eq!(v6_1, v6_1); - assert_eq!(SocketAddr::V4(v4_1), SocketAddr::V4(v4_1)); - assert_eq!(SocketAddr::V6(v6_1), SocketAddr::V6(v6_1)); - assert!(v4_1 != v4_2); - assert!(v6_1 != v6_2); - - // compare different addresses - assert!(v4_1 < v4_2); - assert!(v6_1 < v6_2); - assert!(v4_2 > v4_1); - assert!(v6_2 > v6_1); - - // compare the same address with different ports - assert!(v4_2 < v4_3); - assert!(v6_2 < v6_3); - assert!(v4_3 > v4_2); - assert!(v6_3 > v6_2); - - // compare different addresses with the same port - assert!(v4_1 < v4_3); - assert!(v6_1 < v6_3); - assert!(v4_3 > v4_1); - assert!(v6_3 > v6_1); - - // compare with an inferred right-hand side - assert_eq!(v4_1, "224.120.45.1:23456".parse().unwrap()); - assert_eq!(v6_1, "[2001:db8:f00::1002]:23456".parse().unwrap()); - assert_eq!(SocketAddr::V4(v4_1), "224.120.45.1:23456".parse().unwrap()); -} diff --git a/library/std/src/net/tcp.rs b/library/std/src/net/tcp.rs deleted file mode 100644 index 9667d5f920e43..0000000000000 --- a/library/std/src/net/tcp.rs +++ /dev/null @@ -1,1071 +0,0 @@ -#![deny(unsafe_op_in_unsafe_fn)] - -#[cfg(all(test, not(any(target_os = "emscripten", target_os = "xous"))))] -mod tests; - -use crate::io::prelude::*; - -use crate::fmt; -use crate::io::{self, BorrowedCursor, IoSlice, IoSliceMut}; -use crate::iter::FusedIterator; -use crate::net::{Shutdown, SocketAddr, ToSocketAddrs}; -use crate::sys_common::net as net_imp; -use crate::sys_common::{AsInner, FromInner, IntoInner}; -use crate::time::Duration; - -/// A TCP stream between a local and a remote socket. -/// -/// After creating a `TcpStream` by either [`connect`]ing to a remote host or -/// [`accept`]ing a connection on a [`TcpListener`], data can be transmitted -/// by [reading] and [writing] to it. -/// -/// The connection will be closed when the value is dropped. The reading and writing -/// portions of the connection can also be shut down individually with the [`shutdown`] -/// method. -/// -/// The Transmission Control Protocol is specified in [IETF RFC 793]. -/// -/// [`accept`]: TcpListener::accept -/// [`connect`]: TcpStream::connect -/// [IETF RFC 793]: https://tools.ietf.org/html/rfc793 -/// [reading]: Read -/// [`shutdown`]: TcpStream::shutdown -/// [writing]: Write -/// -/// # Examples -/// -/// ```no_run -/// use std::io::prelude::*; -/// use std::net::TcpStream; -/// -/// fn main() -> std::io::Result<()> { -/// let mut stream = TcpStream::connect("127.0.0.1:34254")?; -/// -/// stream.write(&[1])?; -/// stream.read(&mut [0; 128])?; -/// Ok(()) -/// } // the stream is closed here -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub struct TcpStream(net_imp::TcpStream); - -/// A TCP socket server, listening for connections. -/// -/// After creating a `TcpListener` by [`bind`]ing it to a socket address, it listens -/// for incoming TCP connections. These can be accepted by calling [`accept`] or by -/// iterating over the [`Incoming`] iterator returned by [`incoming`][`TcpListener::incoming`]. -/// -/// The socket will be closed when the value is dropped. -/// -/// The Transmission Control Protocol is specified in [IETF RFC 793]. -/// -/// [`accept`]: TcpListener::accept -/// [`bind`]: TcpListener::bind -/// [IETF RFC 793]: https://tools.ietf.org/html/rfc793 -/// -/// # Examples -/// -/// ```no_run -/// use std::net::{TcpListener, TcpStream}; -/// -/// fn handle_client(stream: TcpStream) { -/// // ... -/// } -/// -/// fn main() -> std::io::Result<()> { -/// let listener = TcpListener::bind("127.0.0.1:80")?; -/// -/// // accept connections and process them serially -/// for stream in listener.incoming() { -/// handle_client(stream?); -/// } -/// Ok(()) -/// } -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub struct TcpListener(net_imp::TcpListener); - -/// An iterator that infinitely [`accept`]s connections on a [`TcpListener`]. -/// -/// This `struct` is created by the [`TcpListener::incoming`] method. -/// See its documentation for more. -/// -/// [`accept`]: TcpListener::accept -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Debug)] -pub struct Incoming<'a> { - listener: &'a TcpListener, -} - -/// An iterator that infinitely [`accept`]s connections on a [`TcpListener`]. -/// -/// This `struct` is created by the [`TcpListener::into_incoming`] method. -/// See its documentation for more. -/// -/// [`accept`]: TcpListener::accept -#[derive(Debug)] -#[unstable(feature = "tcplistener_into_incoming", issue = "88339")] -pub struct IntoIncoming { - listener: TcpListener, -} - -impl TcpStream { - /// Opens a TCP connection to a remote host. - /// - /// `addr` is an address of the remote host. Anything which implements - /// [`ToSocketAddrs`] trait can be supplied for the address; see this trait - /// documentation for concrete examples. - /// - /// If `addr` yields multiple addresses, `connect` will be attempted with - /// each of the addresses until a connection is successful. If none of - /// the addresses result in a successful connection, the error returned from - /// the last connection attempt (the last address) is returned. - /// - /// # Examples - /// - /// Open a TCP connection to `127.0.0.1:8080`: - /// - /// ```no_run - /// use std::net::TcpStream; - /// - /// if let Ok(stream) = TcpStream::connect("127.0.0.1:8080") { - /// println!("Connected to the server!"); - /// } else { - /// println!("Couldn't connect to server..."); - /// } - /// ``` - /// - /// Open a TCP connection to `127.0.0.1:8080`. If the connection fails, open - /// a TCP connection to `127.0.0.1:8081`: - /// - /// ```no_run - /// use std::net::{SocketAddr, TcpStream}; - /// - /// let addrs = [ - /// SocketAddr::from(([127, 0, 0, 1], 8080)), - /// SocketAddr::from(([127, 0, 0, 1], 8081)), - /// ]; - /// if let Ok(stream) = TcpStream::connect(&addrs[..]) { - /// println!("Connected to the server!"); - /// } else { - /// println!("Couldn't connect to server..."); - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn connect(addr: A) -> io::Result { - super::each_addr(addr, net_imp::TcpStream::connect).map(TcpStream) - } - - /// Opens a TCP connection to a remote host with a timeout. - /// - /// Unlike `connect`, `connect_timeout` takes a single [`SocketAddr`] since - /// timeout must be applied to individual addresses. - /// - /// It is an error to pass a zero `Duration` to this function. - /// - /// Unlike other methods on `TcpStream`, this does not correspond to a - /// single system call. It instead calls `connect` in nonblocking mode and - /// then uses an OS-specific mechanism to await the completion of the - /// connection request. - #[stable(feature = "tcpstream_connect_timeout", since = "1.21.0")] - pub fn connect_timeout(addr: &SocketAddr, timeout: Duration) -> io::Result { - net_imp::TcpStream::connect_timeout(addr, timeout).map(TcpStream) - } - - /// Returns the socket address of the remote peer of this TCP connection. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4, TcpStream}; - /// - /// let stream = TcpStream::connect("127.0.0.1:8080") - /// .expect("Couldn't connect to the server..."); - /// assert_eq!(stream.peer_addr().unwrap(), - /// SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080))); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn peer_addr(&self) -> io::Result { - self.0.peer_addr() - } - - /// Returns the socket address of the local half of this TCP connection. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::{IpAddr, Ipv4Addr, TcpStream}; - /// - /// let stream = TcpStream::connect("127.0.0.1:8080") - /// .expect("Couldn't connect to the server..."); - /// assert_eq!(stream.local_addr().unwrap().ip(), - /// IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1))); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn local_addr(&self) -> io::Result { - self.0.socket_addr() - } - - /// Shuts down the read, write, or both halves of this connection. - /// - /// This function will cause all pending and future I/O on the specified - /// portions to return immediately with an appropriate value (see the - /// documentation of [`Shutdown`]). - /// - /// # Platform-specific behavior - /// - /// Calling this function multiple times may result in different behavior, - /// depending on the operating system. On Linux, the second call will - /// return `Ok(())`, but on macOS, it will return `ErrorKind::NotConnected`. - /// This may change in the future. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::{Shutdown, TcpStream}; - /// - /// let stream = TcpStream::connect("127.0.0.1:8080") - /// .expect("Couldn't connect to the server..."); - /// stream.shutdown(Shutdown::Both).expect("shutdown call failed"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn shutdown(&self, how: Shutdown) -> io::Result<()> { - self.0.shutdown(how) - } - - /// Creates a new independently owned handle to the underlying socket. - /// - /// The returned `TcpStream` is a reference to the same stream that this - /// object references. Both handles will read and write the same stream of - /// data, and options set on one stream will be propagated to the other - /// stream. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::TcpStream; - /// - /// let stream = TcpStream::connect("127.0.0.1:8080") - /// .expect("Couldn't connect to the server..."); - /// let stream_clone = stream.try_clone().expect("clone failed..."); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn try_clone(&self) -> io::Result { - self.0.duplicate().map(TcpStream) - } - - /// Sets the read timeout to the timeout specified. - /// - /// If the value specified is [`None`], then [`read`] calls will block - /// indefinitely. An [`Err`] is returned if the zero [`Duration`] is - /// passed to this method. - /// - /// # Platform-specific behavior - /// - /// Platforms may return a different error code whenever a read times out as - /// a result of setting this option. For example Unix typically returns an - /// error of the kind [`WouldBlock`], but Windows may return [`TimedOut`]. - /// - /// [`read`]: Read::read - /// [`WouldBlock`]: io::ErrorKind::WouldBlock - /// [`TimedOut`]: io::ErrorKind::TimedOut - /// - /// # Examples - /// - /// ```no_run - /// use std::net::TcpStream; - /// - /// let stream = TcpStream::connect("127.0.0.1:8080") - /// .expect("Couldn't connect to the server..."); - /// stream.set_read_timeout(None).expect("set_read_timeout call failed"); - /// ``` - /// - /// An [`Err`] is returned if the zero [`Duration`] is passed to this - /// method: - /// - /// ```no_run - /// use std::io; - /// use std::net::TcpStream; - /// use std::time::Duration; - /// - /// let stream = TcpStream::connect("127.0.0.1:8080").unwrap(); - /// let result = stream.set_read_timeout(Some(Duration::new(0, 0))); - /// let err = result.unwrap_err(); - /// assert_eq!(err.kind(), io::ErrorKind::InvalidInput) - /// ``` - #[stable(feature = "socket_timeout", since = "1.4.0")] - pub fn set_read_timeout(&self, dur: Option) -> io::Result<()> { - self.0.set_read_timeout(dur) - } - - /// Sets the write timeout to the timeout specified. - /// - /// If the value specified is [`None`], then [`write`] calls will block - /// indefinitely. An [`Err`] is returned if the zero [`Duration`] is - /// passed to this method. - /// - /// # Platform-specific behavior - /// - /// Platforms may return a different error code whenever a write times out - /// as a result of setting this option. For example Unix typically returns - /// an error of the kind [`WouldBlock`], but Windows may return [`TimedOut`]. - /// - /// [`write`]: Write::write - /// [`WouldBlock`]: io::ErrorKind::WouldBlock - /// [`TimedOut`]: io::ErrorKind::TimedOut - /// - /// # Examples - /// - /// ```no_run - /// use std::net::TcpStream; - /// - /// let stream = TcpStream::connect("127.0.0.1:8080") - /// .expect("Couldn't connect to the server..."); - /// stream.set_write_timeout(None).expect("set_write_timeout call failed"); - /// ``` - /// - /// An [`Err`] is returned if the zero [`Duration`] is passed to this - /// method: - /// - /// ```no_run - /// use std::io; - /// use std::net::TcpStream; - /// use std::time::Duration; - /// - /// let stream = TcpStream::connect("127.0.0.1:8080").unwrap(); - /// let result = stream.set_write_timeout(Some(Duration::new(0, 0))); - /// let err = result.unwrap_err(); - /// assert_eq!(err.kind(), io::ErrorKind::InvalidInput) - /// ``` - #[stable(feature = "socket_timeout", since = "1.4.0")] - pub fn set_write_timeout(&self, dur: Option) -> io::Result<()> { - self.0.set_write_timeout(dur) - } - - /// Returns the read timeout of this socket. - /// - /// If the timeout is [`None`], then [`read`] calls will block indefinitely. - /// - /// # Platform-specific behavior - /// - /// Some platforms do not provide access to the current timeout. - /// - /// [`read`]: Read::read - /// - /// # Examples - /// - /// ```no_run - /// use std::net::TcpStream; - /// - /// let stream = TcpStream::connect("127.0.0.1:8080") - /// .expect("Couldn't connect to the server..."); - /// stream.set_read_timeout(None).expect("set_read_timeout call failed"); - /// assert_eq!(stream.read_timeout().unwrap(), None); - /// ``` - #[stable(feature = "socket_timeout", since = "1.4.0")] - pub fn read_timeout(&self) -> io::Result> { - self.0.read_timeout() - } - - /// Returns the write timeout of this socket. - /// - /// If the timeout is [`None`], then [`write`] calls will block indefinitely. - /// - /// # Platform-specific behavior - /// - /// Some platforms do not provide access to the current timeout. - /// - /// [`write`]: Write::write - /// - /// # Examples - /// - /// ```no_run - /// use std::net::TcpStream; - /// - /// let stream = TcpStream::connect("127.0.0.1:8080") - /// .expect("Couldn't connect to the server..."); - /// stream.set_write_timeout(None).expect("set_write_timeout call failed"); - /// assert_eq!(stream.write_timeout().unwrap(), None); - /// ``` - #[stable(feature = "socket_timeout", since = "1.4.0")] - pub fn write_timeout(&self) -> io::Result> { - self.0.write_timeout() - } - - /// Receives data on the socket from the remote address to which it is - /// connected, without removing that data from the queue. On success, - /// returns the number of bytes peeked. - /// - /// Successive calls return the same data. This is accomplished by passing - /// `MSG_PEEK` as a flag to the underlying `recv` system call. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::TcpStream; - /// - /// let stream = TcpStream::connect("127.0.0.1:8000") - /// .expect("Couldn't connect to the server..."); - /// let mut buf = [0; 10]; - /// let len = stream.peek(&mut buf).expect("peek failed"); - /// ``` - #[stable(feature = "peek", since = "1.18.0")] - pub fn peek(&self, buf: &mut [u8]) -> io::Result { - self.0.peek(buf) - } - - /// Sets the value of the `SO_LINGER` option on this socket. - /// - /// This value controls how the socket is closed when data remains - /// to be sent. If `SO_LINGER` is set, the socket will remain open - /// for the specified duration as the system attempts to send pending data. - /// Otherwise, the system may close the socket immediately, or wait for a - /// default timeout. - /// - /// # Examples - /// - /// ```no_run - /// #![feature(tcp_linger)] - /// - /// use std::net::TcpStream; - /// use std::time::Duration; - /// - /// let stream = TcpStream::connect("127.0.0.1:8080") - /// .expect("Couldn't connect to the server..."); - /// stream.set_linger(Some(Duration::from_secs(0))).expect("set_linger call failed"); - /// ``` - #[unstable(feature = "tcp_linger", issue = "88494")] - pub fn set_linger(&self, linger: Option) -> io::Result<()> { - self.0.set_linger(linger) - } - - /// Gets the value of the `SO_LINGER` option on this socket. - /// - /// For more information about this option, see [`TcpStream::set_linger`]. - /// - /// # Examples - /// - /// ```no_run - /// #![feature(tcp_linger)] - /// - /// use std::net::TcpStream; - /// use std::time::Duration; - /// - /// let stream = TcpStream::connect("127.0.0.1:8080") - /// .expect("Couldn't connect to the server..."); - /// stream.set_linger(Some(Duration::from_secs(0))).expect("set_linger call failed"); - /// assert_eq!(stream.linger().unwrap(), Some(Duration::from_secs(0))); - /// ``` - #[unstable(feature = "tcp_linger", issue = "88494")] - pub fn linger(&self) -> io::Result> { - self.0.linger() - } - - /// Sets the value of the `TCP_NODELAY` option on this socket. - /// - /// If set, this option disables the Nagle algorithm. This means that - /// segments are always sent as soon as possible, even if there is only a - /// small amount of data. When not set, data is buffered until there is a - /// sufficient amount to send out, thereby avoiding the frequent sending of - /// small packets. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::TcpStream; - /// - /// let stream = TcpStream::connect("127.0.0.1:8080") - /// .expect("Couldn't connect to the server..."); - /// stream.set_nodelay(true).expect("set_nodelay call failed"); - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn set_nodelay(&self, nodelay: bool) -> io::Result<()> { - self.0.set_nodelay(nodelay) - } - - /// Gets the value of the `TCP_NODELAY` option on this socket. - /// - /// For more information about this option, see [`TcpStream::set_nodelay`]. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::TcpStream; - /// - /// let stream = TcpStream::connect("127.0.0.1:8080") - /// .expect("Couldn't connect to the server..."); - /// stream.set_nodelay(true).expect("set_nodelay call failed"); - /// assert_eq!(stream.nodelay().unwrap_or(false), true); - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn nodelay(&self) -> io::Result { - self.0.nodelay() - } - - /// Sets the value for the `IP_TTL` option on this socket. - /// - /// This value sets the time-to-live field that is used in every packet sent - /// from this socket. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::TcpStream; - /// - /// let stream = TcpStream::connect("127.0.0.1:8080") - /// .expect("Couldn't connect to the server..."); - /// stream.set_ttl(100).expect("set_ttl call failed"); - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn set_ttl(&self, ttl: u32) -> io::Result<()> { - self.0.set_ttl(ttl) - } - - /// Gets the value of the `IP_TTL` option for this socket. - /// - /// For more information about this option, see [`TcpStream::set_ttl`]. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::TcpStream; - /// - /// let stream = TcpStream::connect("127.0.0.1:8080") - /// .expect("Couldn't connect to the server..."); - /// stream.set_ttl(100).expect("set_ttl call failed"); - /// assert_eq!(stream.ttl().unwrap_or(0), 100); - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn ttl(&self) -> io::Result { - self.0.ttl() - } - - /// Gets the value of the `SO_ERROR` option on this socket. - /// - /// This will retrieve the stored error in the underlying socket, clearing - /// the field in the process. This can be useful for checking errors between - /// calls. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::TcpStream; - /// - /// let stream = TcpStream::connect("127.0.0.1:8080") - /// .expect("Couldn't connect to the server..."); - /// stream.take_error().expect("No error was expected..."); - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn take_error(&self) -> io::Result> { - self.0.take_error() - } - - /// Moves this TCP stream into or out of nonblocking mode. - /// - /// This will result in `read`, `write`, `recv` and `send` operations - /// becoming nonblocking, i.e., immediately returning from their calls. - /// If the IO operation is successful, `Ok` is returned and no further - /// action is required. If the IO operation could not be completed and needs - /// to be retried, an error with kind [`io::ErrorKind::WouldBlock`] is - /// returned. - /// - /// On Unix platforms, calling this method corresponds to calling `fcntl` - /// `FIONBIO`. On Windows calling this method corresponds to calling - /// `ioctlsocket` `FIONBIO`. - /// - /// # Examples - /// - /// Reading bytes from a TCP stream in non-blocking mode: - /// - /// ```no_run - /// use std::io::{self, Read}; - /// use std::net::TcpStream; - /// - /// let mut stream = TcpStream::connect("127.0.0.1:7878") - /// .expect("Couldn't connect to the server..."); - /// stream.set_nonblocking(true).expect("set_nonblocking call failed"); - /// - /// # fn wait_for_fd() { unimplemented!() } - /// let mut buf = vec![]; - /// loop { - /// match stream.read_to_end(&mut buf) { - /// Ok(_) => break, - /// Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => { - /// // wait until network socket is ready, typically implemented - /// // via platform-specific APIs such as epoll or IOCP - /// wait_for_fd(); - /// } - /// Err(e) => panic!("encountered IO error: {e}"), - /// }; - /// }; - /// println!("bytes: {buf:?}"); - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> { - self.0.set_nonblocking(nonblocking) - } -} - -// In addition to the `impl`s here, `TcpStream` also has `impl`s for -// `AsFd`/`From`/`Into` and -// `AsRawFd`/`IntoRawFd`/`FromRawFd`, on Unix and WASI, and -// `AsSocket`/`From`/`Into` and -// `AsRawSocket`/`IntoRawSocket`/`FromRawSocket` on Windows. - -#[stable(feature = "rust1", since = "1.0.0")] -impl Read for TcpStream { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - self.0.read(buf) - } - - fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> io::Result<()> { - self.0.read_buf(buf) - } - - fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - self.0.read_vectored(bufs) - } - - #[inline] - fn is_read_vectored(&self) -> bool { - self.0.is_read_vectored() - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl Write for TcpStream { - fn write(&mut self, buf: &[u8]) -> io::Result { - self.0.write(buf) - } - - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - self.0.write_vectored(bufs) - } - - #[inline] - fn is_write_vectored(&self) -> bool { - self.0.is_write_vectored() - } - - #[inline] - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl Read for &TcpStream { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - self.0.read(buf) - } - - fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> io::Result<()> { - self.0.read_buf(buf) - } - - fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - self.0.read_vectored(bufs) - } - - #[inline] - fn is_read_vectored(&self) -> bool { - self.0.is_read_vectored() - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl Write for &TcpStream { - fn write(&mut self, buf: &[u8]) -> io::Result { - self.0.write(buf) - } - - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - self.0.write_vectored(bufs) - } - - #[inline] - fn is_write_vectored(&self) -> bool { - self.0.is_write_vectored() - } - - #[inline] - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -impl AsInner for TcpStream { - #[inline] - fn as_inner(&self) -> &net_imp::TcpStream { - &self.0 - } -} - -impl FromInner for TcpStream { - fn from_inner(inner: net_imp::TcpStream) -> TcpStream { - TcpStream(inner) - } -} - -impl IntoInner for TcpStream { - fn into_inner(self) -> net_imp::TcpStream { - self.0 - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for TcpStream { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0.fmt(f) - } -} - -impl TcpListener { - /// Creates a new `TcpListener` which will be bound to the specified - /// address. - /// - /// The returned listener is ready for accepting connections. - /// - /// Binding with a port number of 0 will request that the OS assigns a port - /// to this listener. The port allocated can be queried via the - /// [`TcpListener::local_addr`] method. - /// - /// The address type can be any implementor of [`ToSocketAddrs`] trait. See - /// its documentation for concrete examples. - /// - /// If `addr` yields multiple addresses, `bind` will be attempted with - /// each of the addresses until one succeeds and returns the listener. If - /// none of the addresses succeed in creating a listener, the error returned - /// from the last attempt (the last address) is returned. - /// - /// # Examples - /// - /// Creates a TCP listener bound to `127.0.0.1:80`: - /// - /// ```no_run - /// use std::net::TcpListener; - /// - /// let listener = TcpListener::bind("127.0.0.1:80").unwrap(); - /// ``` - /// - /// Creates a TCP listener bound to `127.0.0.1:80`. If that fails, create a - /// TCP listener bound to `127.0.0.1:443`: - /// - /// ```no_run - /// use std::net::{SocketAddr, TcpListener}; - /// - /// let addrs = [ - /// SocketAddr::from(([127, 0, 0, 1], 80)), - /// SocketAddr::from(([127, 0, 0, 1], 443)), - /// ]; - /// let listener = TcpListener::bind(&addrs[..]).unwrap(); - /// ``` - /// - /// Creates a TCP listener bound to a port assigned by the operating system - /// at `127.0.0.1`. - /// - /// ```no_run - /// use std::net::TcpListener; - /// - /// let socket = TcpListener::bind("127.0.0.1:0").unwrap(); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn bind(addr: A) -> io::Result { - super::each_addr(addr, net_imp::TcpListener::bind).map(TcpListener) - } - - /// Returns the local socket address of this listener. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4, TcpListener}; - /// - /// let listener = TcpListener::bind("127.0.0.1:8080").unwrap(); - /// assert_eq!(listener.local_addr().unwrap(), - /// SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 8080))); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn local_addr(&self) -> io::Result { - self.0.socket_addr() - } - - /// Creates a new independently owned handle to the underlying socket. - /// - /// The returned [`TcpListener`] is a reference to the same socket that this - /// object references. Both handles can be used to accept incoming - /// connections and options set on one listener will affect the other. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::TcpListener; - /// - /// let listener = TcpListener::bind("127.0.0.1:8080").unwrap(); - /// let listener_clone = listener.try_clone().unwrap(); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn try_clone(&self) -> io::Result { - self.0.duplicate().map(TcpListener) - } - - /// Accept a new incoming connection from this listener. - /// - /// This function will block the calling thread until a new TCP connection - /// is established. When established, the corresponding [`TcpStream`] and the - /// remote peer's address will be returned. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::TcpListener; - /// - /// let listener = TcpListener::bind("127.0.0.1:8080").unwrap(); - /// match listener.accept() { - /// Ok((_socket, addr)) => println!("new client: {addr:?}"), - /// Err(e) => println!("couldn't get client: {e:?}"), - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn accept(&self) -> io::Result<(TcpStream, SocketAddr)> { - // On WASM, `TcpStream` is uninhabited (as it's unsupported) and so - // the `a` variable here is technically unused. - #[cfg_attr(target_arch = "wasm32", allow(unused_variables))] - self.0.accept().map(|(a, b)| (TcpStream(a), b)) - } - - /// Returns an iterator over the connections being received on this - /// listener. - /// - /// The returned iterator will never return [`None`] and will also not yield - /// the peer's [`SocketAddr`] structure. Iterating over it is equivalent to - /// calling [`TcpListener::accept`] in a loop. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::{TcpListener, TcpStream}; - /// - /// fn handle_connection(stream: TcpStream) { - /// //... - /// } - /// - /// fn main() -> std::io::Result<()> { - /// let listener = TcpListener::bind("127.0.0.1:80")?; - /// - /// for stream in listener.incoming() { - /// match stream { - /// Ok(stream) => { - /// handle_connection(stream); - /// } - /// Err(e) => { /* connection failed */ } - /// } - /// } - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn incoming(&self) -> Incoming<'_> { - Incoming { listener: self } - } - - /// Turn this into an iterator over the connections being received on this - /// listener. - /// - /// The returned iterator will never return [`None`] and will also not yield - /// the peer's [`SocketAddr`] structure. Iterating over it is equivalent to - /// calling [`TcpListener::accept`] in a loop. - /// - /// # Examples - /// - /// ```no_run - /// #![feature(tcplistener_into_incoming)] - /// use std::net::{TcpListener, TcpStream}; - /// - /// fn listen_on(port: u16) -> impl Iterator { - /// let listener = TcpListener::bind(("127.0.0.1", port)).unwrap(); - /// listener.into_incoming() - /// .filter_map(Result::ok) /* Ignore failed connections */ - /// } - /// - /// fn main() -> std::io::Result<()> { - /// for stream in listen_on(80) { - /// /* handle the connection here */ - /// } - /// Ok(()) - /// } - /// ``` - #[must_use = "`self` will be dropped if the result is not used"] - #[unstable(feature = "tcplistener_into_incoming", issue = "88339")] - pub fn into_incoming(self) -> IntoIncoming { - IntoIncoming { listener: self } - } - - /// Sets the value for the `IP_TTL` option on this socket. - /// - /// This value sets the time-to-live field that is used in every packet sent - /// from this socket. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::TcpListener; - /// - /// let listener = TcpListener::bind("127.0.0.1:80").unwrap(); - /// listener.set_ttl(100).expect("could not set TTL"); - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn set_ttl(&self, ttl: u32) -> io::Result<()> { - self.0.set_ttl(ttl) - } - - /// Gets the value of the `IP_TTL` option for this socket. - /// - /// For more information about this option, see [`TcpListener::set_ttl`]. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::TcpListener; - /// - /// let listener = TcpListener::bind("127.0.0.1:80").unwrap(); - /// listener.set_ttl(100).expect("could not set TTL"); - /// assert_eq!(listener.ttl().unwrap_or(0), 100); - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn ttl(&self) -> io::Result { - self.0.ttl() - } - - #[stable(feature = "net2_mutators", since = "1.9.0")] - #[deprecated(since = "1.16.0", note = "this option can only be set before the socket is bound")] - #[allow(missing_docs)] - pub fn set_only_v6(&self, only_v6: bool) -> io::Result<()> { - self.0.set_only_v6(only_v6) - } - - #[stable(feature = "net2_mutators", since = "1.9.0")] - #[deprecated(since = "1.16.0", note = "this option can only be set before the socket is bound")] - #[allow(missing_docs)] - pub fn only_v6(&self) -> io::Result { - self.0.only_v6() - } - - /// Gets the value of the `SO_ERROR` option on this socket. - /// - /// This will retrieve the stored error in the underlying socket, clearing - /// the field in the process. This can be useful for checking errors between - /// calls. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::TcpListener; - /// - /// let listener = TcpListener::bind("127.0.0.1:80").unwrap(); - /// listener.take_error().expect("No error was expected"); - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn take_error(&self) -> io::Result> { - self.0.take_error() - } - - /// Moves this TCP stream into or out of nonblocking mode. - /// - /// This will result in the `accept` operation becoming nonblocking, - /// i.e., immediately returning from their calls. If the IO operation is - /// successful, `Ok` is returned and no further action is required. If the - /// IO operation could not be completed and needs to be retried, an error - /// with kind [`io::ErrorKind::WouldBlock`] is returned. - /// - /// On Unix platforms, calling this method corresponds to calling `fcntl` - /// `FIONBIO`. On Windows calling this method corresponds to calling - /// `ioctlsocket` `FIONBIO`. - /// - /// # Examples - /// - /// Bind a TCP listener to an address, listen for connections, and read - /// bytes in nonblocking mode: - /// - /// ```no_run - /// use std::io; - /// use std::net::TcpListener; - /// - /// let listener = TcpListener::bind("127.0.0.1:7878").unwrap(); - /// listener.set_nonblocking(true).expect("Cannot set non-blocking"); - /// - /// # fn wait_for_fd() { unimplemented!() } - /// # fn handle_connection(stream: std::net::TcpStream) { unimplemented!() } - /// for stream in listener.incoming() { - /// match stream { - /// Ok(s) => { - /// // do something with the TcpStream - /// handle_connection(s); - /// } - /// Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => { - /// // wait until network socket is ready, typically implemented - /// // via platform-specific APIs such as epoll or IOCP - /// wait_for_fd(); - /// continue; - /// } - /// Err(e) => panic!("encountered IO error: {e}"), - /// } - /// } - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> { - self.0.set_nonblocking(nonblocking) - } -} - -// In addition to the `impl`s here, `TcpListener` also has `impl`s for -// `AsFd`/`From`/`Into` and -// `AsRawFd`/`IntoRawFd`/`FromRawFd`, on Unix and WASI, and -// `AsSocket`/`From`/`Into` and -// `AsRawSocket`/`IntoRawSocket`/`FromRawSocket` on Windows. - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a> Iterator for Incoming<'a> { - type Item = io::Result; - fn next(&mut self) -> Option> { - Some(self.listener.accept().map(|p| p.0)) - } -} - -#[stable(feature = "tcp_listener_incoming_fused_iterator", since = "1.64.0")] -impl FusedIterator for Incoming<'_> {} - -#[unstable(feature = "tcplistener_into_incoming", issue = "88339")] -impl Iterator for IntoIncoming { - type Item = io::Result; - fn next(&mut self) -> Option> { - Some(self.listener.accept().map(|p| p.0)) - } -} - -#[unstable(feature = "tcplistener_into_incoming", issue = "88339")] -impl FusedIterator for IntoIncoming {} - -impl AsInner for TcpListener { - #[inline] - fn as_inner(&self) -> &net_imp::TcpListener { - &self.0 - } -} - -impl FromInner for TcpListener { - fn from_inner(inner: net_imp::TcpListener) -> TcpListener { - TcpListener(inner) - } -} - -impl IntoInner for TcpListener { - fn into_inner(self) -> net_imp::TcpListener { - self.0 - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for TcpListener { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0.fmt(f) - } -} diff --git a/library/std/src/net/tcp/tests.rs b/library/std/src/net/tcp/tests.rs deleted file mode 100644 index ec8b62f968754..0000000000000 --- a/library/std/src/net/tcp/tests.rs +++ /dev/null @@ -1,919 +0,0 @@ -use crate::fmt; -use crate::io::prelude::*; -use crate::io::{BorrowedBuf, IoSlice, IoSliceMut}; -use crate::mem::MaybeUninit; -use crate::net::test::{next_test_ip4, next_test_ip6}; -use crate::net::*; -use crate::sync::mpsc::channel; -use crate::thread; -use crate::time::{Duration, Instant}; - -fn each_ip(f: &mut dyn FnMut(SocketAddr)) { - f(next_test_ip4()); - f(next_test_ip6()); -} - -macro_rules! t { - ($e:expr) => { - match $e { - Ok(t) => t, - Err(e) => panic!("received error for `{}`: {}", stringify!($e), e), - } - }; -} - -#[test] -fn bind_error() { - match TcpListener::bind("1.1.1.1:9999") { - Ok(..) => panic!(), - Err(e) => assert_eq!(e.kind(), ErrorKind::AddrNotAvailable), - } -} - -#[test] -fn connect_error() { - match TcpStream::connect("0.0.0.0:1") { - Ok(..) => panic!(), - Err(e) => assert!( - e.kind() == ErrorKind::ConnectionRefused - || e.kind() == ErrorKind::InvalidInput - || e.kind() == ErrorKind::AddrInUse - || e.kind() == ErrorKind::AddrNotAvailable, - "bad error: {} {:?}", - e, - e.kind() - ), - } -} - -#[test] -#[cfg_attr(target_env = "sgx", ignore)] // FIXME: https://github.com/fortanix/rust-sgx/issues/31 -fn connect_timeout_error() { - let socket_addr = next_test_ip4(); - let result = TcpStream::connect_timeout(&socket_addr, Duration::MAX); - assert!(!matches!(result, Err(e) if e.kind() == ErrorKind::TimedOut)); - - let _listener = TcpListener::bind(&socket_addr).unwrap(); - assert!(TcpStream::connect_timeout(&socket_addr, Duration::MAX).is_ok()); -} - -#[test] -fn listen_localhost() { - let socket_addr = next_test_ip4(); - let listener = t!(TcpListener::bind(&socket_addr)); - - let _t = thread::spawn(move || { - let mut stream = t!(TcpStream::connect(&("localhost", socket_addr.port()))); - t!(stream.write(&[144])); - }); - - let mut stream = t!(listener.accept()).0; - let mut buf = [0]; - t!(stream.read(&mut buf)); - assert!(buf[0] == 144); -} - -#[test] -fn connect_loopback() { - each_ip(&mut |addr| { - let acceptor = t!(TcpListener::bind(&addr)); - - let _t = thread::spawn(move || { - let host = match addr { - SocketAddr::V4(..) => "127.0.0.1", - SocketAddr::V6(..) => "::1", - }; - let mut stream = t!(TcpStream::connect(&(host, addr.port()))); - t!(stream.write(&[66])); - }); - - let mut stream = t!(acceptor.accept()).0; - let mut buf = [0]; - t!(stream.read(&mut buf)); - assert!(buf[0] == 66); - }) -} - -#[test] -fn smoke_test() { - each_ip(&mut |addr| { - let acceptor = t!(TcpListener::bind(&addr)); - - let (tx, rx) = channel(); - let _t = thread::spawn(move || { - let mut stream = t!(TcpStream::connect(&addr)); - t!(stream.write(&[99])); - tx.send(t!(stream.local_addr())).unwrap(); - }); - - let (mut stream, addr) = t!(acceptor.accept()); - let mut buf = [0]; - t!(stream.read(&mut buf)); - assert!(buf[0] == 99); - assert_eq!(addr, t!(rx.recv())); - }) -} - -#[test] -fn read_eof() { - each_ip(&mut |addr| { - let acceptor = t!(TcpListener::bind(&addr)); - - let _t = thread::spawn(move || { - let _stream = t!(TcpStream::connect(&addr)); - // Close - }); - - let mut stream = t!(acceptor.accept()).0; - let mut buf = [0]; - let nread = t!(stream.read(&mut buf)); - assert_eq!(nread, 0); - let nread = t!(stream.read(&mut buf)); - assert_eq!(nread, 0); - }) -} - -#[test] -fn write_close() { - each_ip(&mut |addr| { - let acceptor = t!(TcpListener::bind(&addr)); - - let (tx, rx) = channel(); - let _t = thread::spawn(move || { - drop(t!(TcpStream::connect(&addr))); - tx.send(()).unwrap(); - }); - - let mut stream = t!(acceptor.accept()).0; - rx.recv().unwrap(); - let buf = [0]; - match stream.write(&buf) { - Ok(..) => {} - Err(e) => { - assert!( - e.kind() == ErrorKind::ConnectionReset - || e.kind() == ErrorKind::BrokenPipe - || e.kind() == ErrorKind::ConnectionAborted, - "unknown error: {e}" - ); - } - } - }) -} - -#[test] -fn multiple_connect_serial() { - each_ip(&mut |addr| { - let max = 10; - let acceptor = t!(TcpListener::bind(&addr)); - - let _t = thread::spawn(move || { - for _ in 0..max { - let mut stream = t!(TcpStream::connect(&addr)); - t!(stream.write(&[99])); - } - }); - - for stream in acceptor.incoming().take(max) { - let mut stream = t!(stream); - let mut buf = [0]; - t!(stream.read(&mut buf)); - assert_eq!(buf[0], 99); - } - }) -} - -#[test] -fn multiple_connect_interleaved_greedy_schedule() { - const MAX: usize = 10; - each_ip(&mut |addr| { - let acceptor = t!(TcpListener::bind(&addr)); - - let _t = thread::spawn(move || { - let acceptor = acceptor; - for (i, stream) in acceptor.incoming().enumerate().take(MAX) { - // Start another thread to handle the connection - let _t = thread::spawn(move || { - let mut stream = t!(stream); - let mut buf = [0]; - t!(stream.read(&mut buf)); - assert!(buf[0] == i as u8); - }); - } - }); - - connect(0, addr); - }); - - fn connect(i: usize, addr: SocketAddr) { - if i == MAX { - return; - } - - let t = thread::spawn(move || { - let mut stream = t!(TcpStream::connect(&addr)); - // Connect again before writing - connect(i + 1, addr); - t!(stream.write(&[i as u8])); - }); - t.join().ok().expect("thread panicked"); - } -} - -#[test] -fn multiple_connect_interleaved_lazy_schedule() { - const MAX: usize = 10; - each_ip(&mut |addr| { - let acceptor = t!(TcpListener::bind(&addr)); - - let _t = thread::spawn(move || { - for stream in acceptor.incoming().take(MAX) { - // Start another thread to handle the connection - let _t = thread::spawn(move || { - let mut stream = t!(stream); - let mut buf = [0]; - t!(stream.read(&mut buf)); - assert!(buf[0] == 99); - }); - } - }); - - connect(0, addr); - }); - - fn connect(i: usize, addr: SocketAddr) { - if i == MAX { - return; - } - - let t = thread::spawn(move || { - let mut stream = t!(TcpStream::connect(&addr)); - connect(i + 1, addr); - t!(stream.write(&[99])); - }); - t.join().ok().expect("thread panicked"); - } -} - -#[test] -fn socket_and_peer_name() { - each_ip(&mut |addr| { - let listener = t!(TcpListener::bind(&addr)); - let so_name = t!(listener.local_addr()); - assert_eq!(addr, so_name); - let _t = thread::spawn(move || { - t!(listener.accept()); - }); - - let stream = t!(TcpStream::connect(&addr)); - assert_eq!(addr, t!(stream.peer_addr())); - }) -} - -#[test] -fn partial_read() { - each_ip(&mut |addr| { - let (tx, rx) = channel(); - let srv = t!(TcpListener::bind(&addr)); - let _t = thread::spawn(move || { - let mut cl = t!(srv.accept()).0; - cl.write(&[10]).unwrap(); - let mut b = [0]; - t!(cl.read(&mut b)); - tx.send(()).unwrap(); - }); - - let mut c = t!(TcpStream::connect(&addr)); - let mut b = [0; 10]; - assert_eq!(c.read(&mut b).unwrap(), 1); - t!(c.write(&[1])); - rx.recv().unwrap(); - }) -} - -#[test] -fn read_buf() { - each_ip(&mut |addr| { - let srv = t!(TcpListener::bind(&addr)); - let t = thread::spawn(move || { - let mut s = t!(TcpStream::connect(&addr)); - s.write_all(&[1, 2, 3, 4]).unwrap(); - }); - - let mut s = t!(srv.accept()).0; - let mut buf: [MaybeUninit; 128] = MaybeUninit::uninit_array(); - let mut buf = BorrowedBuf::from(buf.as_mut_slice()); - t!(s.read_buf(buf.unfilled())); - assert_eq!(buf.filled(), &[1, 2, 3, 4]); - - // FIXME: sgx uses default_read_buf that initializes the buffer. - if cfg!(not(target_env = "sgx")) { - // TcpStream::read_buf should omit buffer initialization. - assert_eq!(buf.init_len(), 4); - } - - t.join().ok().expect("thread panicked"); - }) -} - -#[test] -fn read_vectored() { - each_ip(&mut |addr| { - let srv = t!(TcpListener::bind(&addr)); - let mut s1 = t!(TcpStream::connect(&addr)); - let mut s2 = t!(srv.accept()).0; - - let len = s1.write(&[10, 11, 12]).unwrap(); - assert_eq!(len, 3); - - let mut a = []; - let mut b = [0]; - let mut c = [0; 3]; - let len = t!(s2.read_vectored(&mut [ - IoSliceMut::new(&mut a), - IoSliceMut::new(&mut b), - IoSliceMut::new(&mut c) - ],)); - assert!(len > 0); - assert_eq!(b, [10]); - // some implementations don't support readv, so we may only fill the first buffer - assert!(len == 1 || c == [11, 12, 0]); - }) -} - -#[test] -fn write_vectored() { - each_ip(&mut |addr| { - let srv = t!(TcpListener::bind(&addr)); - let mut s1 = t!(TcpStream::connect(&addr)); - let mut s2 = t!(srv.accept()).0; - - let a = []; - let b = [10]; - let c = [11, 12]; - t!(s1.write_vectored(&[IoSlice::new(&a), IoSlice::new(&b), IoSlice::new(&c)])); - - let mut buf = [0; 4]; - let len = t!(s2.read(&mut buf)); - // some implementations don't support writev, so we may only write the first buffer - if len == 1 { - assert_eq!(buf, [10, 0, 0, 0]); - } else { - assert_eq!(len, 3); - assert_eq!(buf, [10, 11, 12, 0]); - } - }) -} - -#[test] -fn double_bind() { - each_ip(&mut |addr| { - let listener1 = t!(TcpListener::bind(&addr)); - match TcpListener::bind(&addr) { - Ok(listener2) => panic!( - "This system (perhaps due to options set by TcpListener::bind) \ - permits double binding: {:?} and {:?}", - listener1, listener2 - ), - Err(e) => { - assert!( - e.kind() == ErrorKind::ConnectionRefused - || e.kind() == ErrorKind::Uncategorized - || e.kind() == ErrorKind::AddrInUse, - "unknown error: {} {:?}", - e, - e.kind() - ); - } - } - }) -} - -#[test] -fn tcp_clone_smoke() { - each_ip(&mut |addr| { - let acceptor = t!(TcpListener::bind(&addr)); - - let _t = thread::spawn(move || { - let mut s = t!(TcpStream::connect(&addr)); - let mut buf = [0, 0]; - assert_eq!(s.read(&mut buf).unwrap(), 1); - assert_eq!(buf[0], 1); - t!(s.write(&[2])); - }); - - let mut s1 = t!(acceptor.accept()).0; - let s2 = t!(s1.try_clone()); - - let (tx1, rx1) = channel(); - let (tx2, rx2) = channel(); - let _t = thread::spawn(move || { - let mut s2 = s2; - rx1.recv().unwrap(); - t!(s2.write(&[1])); - tx2.send(()).unwrap(); - }); - tx1.send(()).unwrap(); - let mut buf = [0, 0]; - assert_eq!(s1.read(&mut buf).unwrap(), 1); - rx2.recv().unwrap(); - }) -} - -#[test] -fn tcp_clone_two_read() { - each_ip(&mut |addr| { - let acceptor = t!(TcpListener::bind(&addr)); - let (tx1, rx) = channel(); - let tx2 = tx1.clone(); - - let _t = thread::spawn(move || { - let mut s = t!(TcpStream::connect(&addr)); - t!(s.write(&[1])); - rx.recv().unwrap(); - t!(s.write(&[2])); - rx.recv().unwrap(); - }); - - let mut s1 = t!(acceptor.accept()).0; - let s2 = t!(s1.try_clone()); - - let (done, rx) = channel(); - let _t = thread::spawn(move || { - let mut s2 = s2; - let mut buf = [0, 0]; - t!(s2.read(&mut buf)); - tx2.send(()).unwrap(); - done.send(()).unwrap(); - }); - let mut buf = [0, 0]; - t!(s1.read(&mut buf)); - tx1.send(()).unwrap(); - - rx.recv().unwrap(); - }) -} - -#[test] -fn tcp_clone_two_write() { - each_ip(&mut |addr| { - let acceptor = t!(TcpListener::bind(&addr)); - - let _t = thread::spawn(move || { - let mut s = t!(TcpStream::connect(&addr)); - let mut buf = [0, 1]; - t!(s.read(&mut buf)); - t!(s.read(&mut buf)); - }); - - let mut s1 = t!(acceptor.accept()).0; - let s2 = t!(s1.try_clone()); - - let (done, rx) = channel(); - let _t = thread::spawn(move || { - let mut s2 = s2; - t!(s2.write(&[1])); - done.send(()).unwrap(); - }); - t!(s1.write(&[2])); - - rx.recv().unwrap(); - }) -} - -#[test] -// FIXME: https://github.com/fortanix/rust-sgx/issues/110 -#[cfg_attr(target_env = "sgx", ignore)] -fn shutdown_smoke() { - each_ip(&mut |addr| { - let a = t!(TcpListener::bind(&addr)); - let _t = thread::spawn(move || { - let mut c = t!(a.accept()).0; - let mut b = [0]; - assert_eq!(c.read(&mut b).unwrap(), 0); - t!(c.write(&[1])); - }); - - let mut s = t!(TcpStream::connect(&addr)); - t!(s.shutdown(Shutdown::Write)); - assert!(s.write(&[1]).is_err()); - let mut b = [0, 0]; - assert_eq!(t!(s.read(&mut b)), 1); - assert_eq!(b[0], 1); - }) -} - -#[test] -// FIXME: https://github.com/fortanix/rust-sgx/issues/110 -#[cfg_attr(target_env = "sgx", ignore)] -fn close_readwrite_smoke() { - each_ip(&mut |addr| { - let a = t!(TcpListener::bind(&addr)); - let (tx, rx) = channel::<()>(); - let _t = thread::spawn(move || { - let _s = t!(a.accept()); - let _ = rx.recv(); - }); - - let mut b = [0]; - let mut s = t!(TcpStream::connect(&addr)); - let mut s2 = t!(s.try_clone()); - - // closing should prevent reads/writes - t!(s.shutdown(Shutdown::Write)); - assert!(s.write(&[0]).is_err()); - t!(s.shutdown(Shutdown::Read)); - assert_eq!(s.read(&mut b).unwrap(), 0); - - // closing should affect previous handles - assert!(s2.write(&[0]).is_err()); - assert_eq!(s2.read(&mut b).unwrap(), 0); - - // closing should affect new handles - let mut s3 = t!(s.try_clone()); - assert!(s3.write(&[0]).is_err()); - assert_eq!(s3.read(&mut b).unwrap(), 0); - - // make sure these don't die - let _ = s2.shutdown(Shutdown::Read); - let _ = s2.shutdown(Shutdown::Write); - let _ = s3.shutdown(Shutdown::Read); - let _ = s3.shutdown(Shutdown::Write); - drop(tx); - }) -} - -#[test] -// FIXME: https://github.com/fortanix/rust-sgx/issues/110 -#[cfg_attr(target_env = "sgx", ignore)] -// On windows, shutdown will not wake up blocking I/O operations. -#[cfg_attr(windows, ignore)] -fn close_read_wakes_up() { - each_ip(&mut |addr| { - let listener = t!(TcpListener::bind(&addr)); - let _t = thread::spawn(move || { - let (stream, _) = t!(listener.accept()); - stream - }); - - let mut stream = t!(TcpStream::connect(&addr)); - let stream2 = t!(stream.try_clone()); - - let _t = thread::spawn(move || { - let stream2 = stream2; - - // to make it more likely that `read` happens before `shutdown` - thread::sleep(Duration::from_millis(1000)); - - // this should wake up the reader up - t!(stream2.shutdown(Shutdown::Read)); - }); - - // this `read` should get interrupted by `shutdown` - assert_eq!(t!(stream.read(&mut [0])), 0); - }) -} - -#[test] -fn clone_while_reading() { - each_ip(&mut |addr| { - let accept = t!(TcpListener::bind(&addr)); - - // Enqueue a thread to write to a socket - let (tx, rx) = channel(); - let (txdone, rxdone) = channel(); - let txdone2 = txdone.clone(); - let _t = thread::spawn(move || { - let mut tcp = t!(TcpStream::connect(&addr)); - rx.recv().unwrap(); - t!(tcp.write(&[0])); - txdone2.send(()).unwrap(); - }); - - // Spawn off a reading clone - let tcp = t!(accept.accept()).0; - let tcp2 = t!(tcp.try_clone()); - let txdone3 = txdone.clone(); - let _t = thread::spawn(move || { - let mut tcp2 = tcp2; - t!(tcp2.read(&mut [0])); - txdone3.send(()).unwrap(); - }); - - // Try to ensure that the reading clone is indeed reading - for _ in 0..50 { - thread::yield_now(); - } - - // clone the handle again while it's reading, then let it finish the - // read. - let _ = t!(tcp.try_clone()); - tx.send(()).unwrap(); - rxdone.recv().unwrap(); - rxdone.recv().unwrap(); - }) -} - -#[test] -fn clone_accept_smoke() { - each_ip(&mut |addr| { - let a = t!(TcpListener::bind(&addr)); - let a2 = t!(a.try_clone()); - - let _t = thread::spawn(move || { - let _ = TcpStream::connect(&addr); - }); - let _t = thread::spawn(move || { - let _ = TcpStream::connect(&addr); - }); - - t!(a.accept()); - t!(a2.accept()); - }) -} - -#[test] -fn clone_accept_concurrent() { - each_ip(&mut |addr| { - let a = t!(TcpListener::bind(&addr)); - let a2 = t!(a.try_clone()); - - let (tx, rx) = channel(); - let tx2 = tx.clone(); - - let _t = thread::spawn(move || { - tx.send(t!(a.accept())).unwrap(); - }); - let _t = thread::spawn(move || { - tx2.send(t!(a2.accept())).unwrap(); - }); - - let _t = thread::spawn(move || { - let _ = TcpStream::connect(&addr); - }); - let _t = thread::spawn(move || { - let _ = TcpStream::connect(&addr); - }); - - rx.recv().unwrap(); - rx.recv().unwrap(); - }) -} - -#[test] -fn debug() { - #[cfg(not(target_env = "sgx"))] - fn render_socket_addr<'a>(addr: &'a SocketAddr) -> impl fmt::Debug + 'a { - addr - } - #[cfg(target_env = "sgx")] - fn render_socket_addr<'a>(addr: &'a SocketAddr) -> impl fmt::Debug + 'a { - addr.to_string() - } - - #[cfg(target_env = "sgx")] - use crate::os::fortanix_sgx::io::AsRawFd; - #[cfg(unix)] - use crate::os::unix::io::AsRawFd; - #[cfg(not(windows))] - fn render_inner(addr: &dyn AsRawFd) -> impl fmt::Debug { - addr.as_raw_fd() - } - #[cfg(windows)] - fn render_inner(addr: &dyn crate::os::windows::io::AsRawSocket) -> impl fmt::Debug { - addr.as_raw_socket() - } - - let inner_name = if cfg!(windows) { "socket" } else { "fd" }; - let socket_addr = next_test_ip4(); - - let listener = t!(TcpListener::bind(&socket_addr)); - let compare = format!( - "TcpListener {{ addr: {:?}, {}: {:?} }}", - render_socket_addr(&socket_addr), - inner_name, - render_inner(&listener) - ); - assert_eq!(format!("{listener:?}"), compare); - - let stream = t!(TcpStream::connect(&("localhost", socket_addr.port()))); - let compare = format!( - "TcpStream {{ addr: {:?}, peer: {:?}, {}: {:?} }}", - render_socket_addr(&stream.local_addr().unwrap()), - render_socket_addr(&stream.peer_addr().unwrap()), - inner_name, - render_inner(&stream) - ); - assert_eq!(format!("{stream:?}"), compare); -} - -// FIXME: re-enabled openbsd tests once their socket timeout code -// no longer has rounding errors. -// VxWorks ignores SO_SNDTIMEO. -#[cfg_attr( - any(target_os = "netbsd", target_os = "openbsd", target_os = "vxworks", target_os = "nto"), - ignore -)] -#[cfg_attr(target_env = "sgx", ignore)] // FIXME: https://github.com/fortanix/rust-sgx/issues/31 -#[test] -fn timeouts() { - let addr = next_test_ip4(); - let listener = t!(TcpListener::bind(&addr)); - - let stream = t!(TcpStream::connect(&("localhost", addr.port()))); - let dur = Duration::new(15410, 0); - - assert_eq!(None, t!(stream.read_timeout())); - - t!(stream.set_read_timeout(Some(dur))); - assert_eq!(Some(dur), t!(stream.read_timeout())); - - assert_eq!(None, t!(stream.write_timeout())); - - t!(stream.set_write_timeout(Some(dur))); - assert_eq!(Some(dur), t!(stream.write_timeout())); - - t!(stream.set_read_timeout(None)); - assert_eq!(None, t!(stream.read_timeout())); - - t!(stream.set_write_timeout(None)); - assert_eq!(None, t!(stream.write_timeout())); - drop(listener); -} - -#[test] -#[cfg_attr(target_env = "sgx", ignore)] // FIXME: https://github.com/fortanix/rust-sgx/issues/31 -fn test_read_timeout() { - let addr = next_test_ip4(); - let listener = t!(TcpListener::bind(&addr)); - - let mut stream = t!(TcpStream::connect(&("localhost", addr.port()))); - t!(stream.set_read_timeout(Some(Duration::from_millis(1000)))); - - let mut buf = [0; 10]; - let start = Instant::now(); - let kind = stream.read_exact(&mut buf).err().expect("expected error").kind(); - assert!( - kind == ErrorKind::WouldBlock || kind == ErrorKind::TimedOut, - "unexpected_error: {:?}", - kind - ); - assert!(start.elapsed() > Duration::from_millis(400)); - drop(listener); -} - -#[test] -#[cfg_attr(target_env = "sgx", ignore)] // FIXME: https://github.com/fortanix/rust-sgx/issues/31 -fn test_read_with_timeout() { - let addr = next_test_ip4(); - let listener = t!(TcpListener::bind(&addr)); - - let mut stream = t!(TcpStream::connect(&("localhost", addr.port()))); - t!(stream.set_read_timeout(Some(Duration::from_millis(1000)))); - - let mut other_end = t!(listener.accept()).0; - t!(other_end.write_all(b"hello world")); - - let mut buf = [0; 11]; - t!(stream.read(&mut buf)); - assert_eq!(b"hello world", &buf[..]); - - let start = Instant::now(); - let kind = stream.read_exact(&mut buf).err().expect("expected error").kind(); - assert!( - kind == ErrorKind::WouldBlock || kind == ErrorKind::TimedOut, - "unexpected_error: {:?}", - kind - ); - assert!(start.elapsed() > Duration::from_millis(400)); - drop(listener); -} - -// Ensure the `set_read_timeout` and `set_write_timeout` calls return errors -// when passed zero Durations -#[test] -fn test_timeout_zero_duration() { - let addr = next_test_ip4(); - - let listener = t!(TcpListener::bind(&addr)); - let stream = t!(TcpStream::connect(&addr)); - - let result = stream.set_write_timeout(Some(Duration::new(0, 0))); - let err = result.unwrap_err(); - assert_eq!(err.kind(), ErrorKind::InvalidInput); - - let result = stream.set_read_timeout(Some(Duration::new(0, 0))); - let err = result.unwrap_err(); - assert_eq!(err.kind(), ErrorKind::InvalidInput); - - drop(listener); -} - -#[test] -#[cfg_attr(target_env = "sgx", ignore)] -fn linger() { - let addr = next_test_ip4(); - let _listener = t!(TcpListener::bind(&addr)); - - let stream = t!(TcpStream::connect(&("localhost", addr.port()))); - - assert_eq!(None, t!(stream.linger())); - t!(stream.set_linger(Some(Duration::from_secs(1)))); - assert_eq!(Some(Duration::from_secs(1)), t!(stream.linger())); - t!(stream.set_linger(None)); - assert_eq!(None, t!(stream.linger())); -} - -#[test] -#[cfg_attr(target_env = "sgx", ignore)] -fn nodelay() { - let addr = next_test_ip4(); - let _listener = t!(TcpListener::bind(&addr)); - - let stream = t!(TcpStream::connect(&("localhost", addr.port()))); - - assert_eq!(false, t!(stream.nodelay())); - t!(stream.set_nodelay(true)); - assert_eq!(true, t!(stream.nodelay())); - t!(stream.set_nodelay(false)); - assert_eq!(false, t!(stream.nodelay())); -} - -#[test] -#[cfg_attr(target_env = "sgx", ignore)] -fn ttl() { - let ttl = 100; - - let addr = next_test_ip4(); - let listener = t!(TcpListener::bind(&addr)); - - t!(listener.set_ttl(ttl)); - assert_eq!(ttl, t!(listener.ttl())); - - let stream = t!(TcpStream::connect(&("localhost", addr.port()))); - - t!(stream.set_ttl(ttl)); - assert_eq!(ttl, t!(stream.ttl())); -} - -#[test] -#[cfg_attr(target_env = "sgx", ignore)] -fn set_nonblocking() { - let addr = next_test_ip4(); - let listener = t!(TcpListener::bind(&addr)); - - t!(listener.set_nonblocking(true)); - t!(listener.set_nonblocking(false)); - - let mut stream = t!(TcpStream::connect(&("localhost", addr.port()))); - - t!(stream.set_nonblocking(false)); - t!(stream.set_nonblocking(true)); - - let mut buf = [0]; - match stream.read(&mut buf) { - Ok(_) => panic!("expected error"), - Err(ref e) if e.kind() == ErrorKind::WouldBlock => {} - Err(e) => panic!("unexpected error {e}"), - } -} - -#[test] -#[cfg_attr(target_env = "sgx", ignore)] // FIXME: https://github.com/fortanix/rust-sgx/issues/31 -fn peek() { - each_ip(&mut |addr| { - let (txdone, rxdone) = channel(); - - let srv = t!(TcpListener::bind(&addr)); - let _t = thread::spawn(move || { - let mut cl = t!(srv.accept()).0; - cl.write(&[1, 3, 3, 7]).unwrap(); - t!(rxdone.recv()); - }); - - let mut c = t!(TcpStream::connect(&addr)); - let mut b = [0; 10]; - for _ in 1..3 { - let len = c.peek(&mut b).unwrap(); - assert_eq!(len, 4); - } - let len = c.read(&mut b).unwrap(); - assert_eq!(len, 4); - - t!(c.set_nonblocking(true)); - match c.peek(&mut b) { - Ok(_) => panic!("expected error"), - Err(ref e) if e.kind() == ErrorKind::WouldBlock => {} - Err(e) => panic!("unexpected error {e}"), - } - t!(txdone.send(())); - }) -} - -#[test] -#[cfg_attr(target_env = "sgx", ignore)] // FIXME: https://github.com/fortanix/rust-sgx/issues/31 -fn connect_timeout_valid() { - let listener = TcpListener::bind("127.0.0.1:0").unwrap(); - let addr = listener.local_addr().unwrap(); - TcpStream::connect_timeout(&addr, Duration::from_secs(2)).unwrap(); -} diff --git a/library/std/src/net/test.rs b/library/std/src/net/test.rs deleted file mode 100644 index d318d457f3569..0000000000000 --- a/library/std/src/net/test.rs +++ /dev/null @@ -1,60 +0,0 @@ -#![allow(warnings)] // not used on emscripten - -use crate::env; -use crate::net::{Ipv4Addr, Ipv6Addr, SocketAddr, SocketAddrV4, SocketAddrV6, ToSocketAddrs}; -use crate::sync::atomic::{AtomicUsize, Ordering}; - -static PORT: AtomicUsize = AtomicUsize::new(0); - -pub fn next_test_ip4() -> SocketAddr { - let port = PORT.fetch_add(1, Ordering::Relaxed) as u16 + base_port(); - SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), port)) -} - -pub fn next_test_ip6() -> SocketAddr { - let port = PORT.fetch_add(1, Ordering::Relaxed) as u16 + base_port(); - SocketAddr::V6(SocketAddrV6::new(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1), port, 0, 0)) -} - -pub fn sa4(a: Ipv4Addr, p: u16) -> SocketAddr { - SocketAddr::V4(SocketAddrV4::new(a, p)) -} - -pub fn sa6(a: Ipv6Addr, p: u16) -> SocketAddr { - SocketAddr::V6(SocketAddrV6::new(a, p, 0, 0)) -} - -pub fn tsa(a: A) -> Result, String> { - match a.to_socket_addrs() { - Ok(a) => Ok(a.collect()), - Err(e) => Err(e.to_string()), - } -} - -// The bots run multiple builds at the same time, and these builds -// all want to use ports. This function figures out which workspace -// it is running in and assigns a port range based on it. -fn base_port() -> u16 { - let cwd = if cfg!(target_env = "sgx") { - String::from("sgx") - } else { - env::current_dir().unwrap().into_os_string().into_string().unwrap() - }; - let dirs = [ - "32-opt", - "32-nopt", - "musl-64-opt", - "cross-opt", - "64-opt", - "64-nopt", - "64-opt-vg", - "64-debug-opt", - "all-opt", - "snap3", - "dist", - "sgx", - ]; - dirs.iter().enumerate().find(|&(_, dir)| cwd.contains(dir)).map(|p| p.0).unwrap_or(0) as u16 - * 1000 - + 19600 -} diff --git a/library/std/src/net/udp.rs b/library/std/src/net/udp.rs deleted file mode 100644 index 60347a11da9c5..0000000000000 --- a/library/std/src/net/udp.rs +++ /dev/null @@ -1,842 +0,0 @@ -#[cfg(all(test, not(any(target_os = "emscripten", target_env = "sgx", target_os = "xous"))))] -mod tests; - -use crate::fmt; -use crate::io::{self, ErrorKind}; -use crate::net::{Ipv4Addr, Ipv6Addr, SocketAddr, ToSocketAddrs}; -use crate::sys_common::net as net_imp; -use crate::sys_common::{AsInner, FromInner, IntoInner}; -use crate::time::Duration; - -/// A UDP socket. -/// -/// After creating a `UdpSocket` by [`bind`]ing it to a socket address, data can be -/// [sent to] and [received from] any other socket address. -/// -/// Although UDP is a connectionless protocol, this implementation provides an interface -/// to set an address where data should be sent and received from. After setting a remote -/// address with [`connect`], data can be sent to and received from that address with -/// [`send`] and [`recv`]. -/// -/// As stated in the User Datagram Protocol's specification in [IETF RFC 768], UDP is -/// an unordered, unreliable protocol; refer to [`TcpListener`] and [`TcpStream`] for TCP -/// primitives. -/// -/// [`bind`]: UdpSocket::bind -/// [`connect`]: UdpSocket::connect -/// [IETF RFC 768]: https://tools.ietf.org/html/rfc768 -/// [`recv`]: UdpSocket::recv -/// [received from]: UdpSocket::recv_from -/// [`send`]: UdpSocket::send -/// [sent to]: UdpSocket::send_to -/// [`TcpListener`]: crate::net::TcpListener -/// [`TcpStream`]: crate::net::TcpStream -/// -/// # Examples -/// -/// ```no_run -/// use std::net::UdpSocket; -/// -/// fn main() -> std::io::Result<()> { -/// { -/// let socket = UdpSocket::bind("127.0.0.1:34254")?; -/// -/// // Receives a single datagram message on the socket. If `buf` is too small to hold -/// // the message, it will be cut off. -/// let mut buf = [0; 10]; -/// let (amt, src) = socket.recv_from(&mut buf)?; -/// -/// // Redeclare `buf` as slice of the received data and send reverse data back to origin. -/// let buf = &mut buf[..amt]; -/// buf.reverse(); -/// socket.send_to(buf, &src)?; -/// } // the socket is closed here -/// Ok(()) -/// } -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub struct UdpSocket(net_imp::UdpSocket); - -impl UdpSocket { - /// Creates a UDP socket from the given address. - /// - /// The address type can be any implementor of [`ToSocketAddrs`] trait. See - /// its documentation for concrete examples. - /// - /// If `addr` yields multiple addresses, `bind` will be attempted with - /// each of the addresses until one succeeds and returns the socket. If none - /// of the addresses succeed in creating a socket, the error returned from - /// the last attempt (the last address) is returned. - /// - /// # Examples - /// - /// Creates a UDP socket bound to `127.0.0.1:3400`: - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:3400").expect("couldn't bind to address"); - /// ``` - /// - /// Creates a UDP socket bound to `127.0.0.1:3400`. If the socket cannot be - /// bound to that address, create a UDP socket bound to `127.0.0.1:3401`: - /// - /// ```no_run - /// use std::net::{SocketAddr, UdpSocket}; - /// - /// let addrs = [ - /// SocketAddr::from(([127, 0, 0, 1], 3400)), - /// SocketAddr::from(([127, 0, 0, 1], 3401)), - /// ]; - /// let socket = UdpSocket::bind(&addrs[..]).expect("couldn't bind to address"); - /// ``` - /// - /// Creates a UDP socket bound to a port assigned by the operating system - /// at `127.0.0.1`. - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:0").unwrap(); - /// ``` - /// - /// Note that `bind` declares the scope of your network connection. - /// You can only receive datagrams from and send datagrams to - /// participants in that view of the network. - /// For instance, binding to a loopback address as in the example - /// above will prevent you from sending datagrams to another device - /// in your local network. - /// - /// In order to limit your view of the network the least, `bind` to - /// [`Ipv4Addr::UNSPECIFIED`] or [`Ipv6Addr::UNSPECIFIED`]. - #[stable(feature = "rust1", since = "1.0.0")] - pub fn bind(addr: A) -> io::Result { - super::each_addr(addr, net_imp::UdpSocket::bind).map(UdpSocket) - } - - /// Receives a single datagram message on the socket. On success, returns the number - /// of bytes read and the origin. - /// - /// The function must be called with valid byte array `buf` of sufficient size to - /// hold the message bytes. If a message is too long to fit in the supplied buffer, - /// excess bytes may be discarded. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// let mut buf = [0; 10]; - /// let (number_of_bytes, src_addr) = socket.recv_from(&mut buf) - /// .expect("Didn't receive data"); - /// let filled_buf = &mut buf[..number_of_bytes]; - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn recv_from(&self, buf: &mut [u8]) -> io::Result<(usize, SocketAddr)> { - self.0.recv_from(buf) - } - - /// Receives a single datagram message on the socket, without removing it from the - /// queue. On success, returns the number of bytes read and the origin. - /// - /// The function must be called with valid byte array `buf` of sufficient size to - /// hold the message bytes. If a message is too long to fit in the supplied buffer, - /// excess bytes may be discarded. - /// - /// Successive calls return the same data. This is accomplished by passing - /// `MSG_PEEK` as a flag to the underlying `recvfrom` system call. - /// - /// Do not use this function to implement busy waiting, instead use `libc::poll` to - /// synchronize IO events on one or more sockets. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// let mut buf = [0; 10]; - /// let (number_of_bytes, src_addr) = socket.peek_from(&mut buf) - /// .expect("Didn't receive data"); - /// let filled_buf = &mut buf[..number_of_bytes]; - /// ``` - #[stable(feature = "peek", since = "1.18.0")] - pub fn peek_from(&self, buf: &mut [u8]) -> io::Result<(usize, SocketAddr)> { - self.0.peek_from(buf) - } - - /// Sends data on the socket to the given address. On success, returns the - /// number of bytes written. Note that the operating system may refuse - /// buffers larger than 65507. However, partial writes are not possible - /// until buffer sizes above `i32::MAX`. - /// - /// Address type can be any implementor of [`ToSocketAddrs`] trait. See its - /// documentation for concrete examples. - /// - /// It is possible for `addr` to yield multiple addresses, but `send_to` - /// will only send data to the first address yielded by `addr`. - /// - /// This will return an error when the IP version of the local socket - /// does not match that returned from [`ToSocketAddrs`]. - /// - /// See [Issue #34202] for more details. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// socket.send_to(&[0; 10], "127.0.0.1:4242").expect("couldn't send data"); - /// ``` - /// - /// [Issue #34202]: https://github.com/rust-lang/rust/issues/34202 - #[stable(feature = "rust1", since = "1.0.0")] - pub fn send_to(&self, buf: &[u8], addr: A) -> io::Result { - match addr.to_socket_addrs()?.next() { - Some(addr) => self.0.send_to(buf, &addr), - None => { - Err(io::const_io_error!(ErrorKind::InvalidInput, "no addresses to send data to")) - } - } - } - - /// Returns the socket address of the remote peer this socket was connected to. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4, UdpSocket}; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// socket.connect("192.168.0.1:41203").expect("couldn't connect to address"); - /// assert_eq!(socket.peer_addr().unwrap(), - /// SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(192, 168, 0, 1), 41203))); - /// ``` - /// - /// If the socket isn't connected, it will return a [`NotConnected`] error. - /// - /// [`NotConnected`]: io::ErrorKind::NotConnected - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// assert_eq!(socket.peer_addr().unwrap_err().kind(), - /// std::io::ErrorKind::NotConnected); - /// ``` - #[stable(feature = "udp_peer_addr", since = "1.40.0")] - pub fn peer_addr(&self) -> io::Result { - self.0.peer_addr() - } - - /// Returns the socket address that this socket was created from. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::{Ipv4Addr, SocketAddr, SocketAddrV4, UdpSocket}; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// assert_eq!(socket.local_addr().unwrap(), - /// SocketAddr::V4(SocketAddrV4::new(Ipv4Addr::new(127, 0, 0, 1), 34254))); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn local_addr(&self) -> io::Result { - self.0.socket_addr() - } - - /// Creates a new independently owned handle to the underlying socket. - /// - /// The returned `UdpSocket` is a reference to the same socket that this - /// object references. Both handles will read and write the same port, and - /// options set on one socket will be propagated to the other. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// let socket_clone = socket.try_clone().expect("couldn't clone the socket"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn try_clone(&self) -> io::Result { - self.0.duplicate().map(UdpSocket) - } - - /// Sets the read timeout to the timeout specified. - /// - /// If the value specified is [`None`], then [`read`] calls will block - /// indefinitely. An [`Err`] is returned if the zero [`Duration`] is - /// passed to this method. - /// - /// # Platform-specific behavior - /// - /// Platforms may return a different error code whenever a read times out as - /// a result of setting this option. For example Unix typically returns an - /// error of the kind [`WouldBlock`], but Windows may return [`TimedOut`]. - /// - /// [`read`]: io::Read::read - /// [`WouldBlock`]: io::ErrorKind::WouldBlock - /// [`TimedOut`]: io::ErrorKind::TimedOut - /// - /// # Examples - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// socket.set_read_timeout(None).expect("set_read_timeout call failed"); - /// ``` - /// - /// An [`Err`] is returned if the zero [`Duration`] is passed to this - /// method: - /// - /// ```no_run - /// use std::io; - /// use std::net::UdpSocket; - /// use std::time::Duration; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").unwrap(); - /// let result = socket.set_read_timeout(Some(Duration::new(0, 0))); - /// let err = result.unwrap_err(); - /// assert_eq!(err.kind(), io::ErrorKind::InvalidInput) - /// ``` - #[stable(feature = "socket_timeout", since = "1.4.0")] - pub fn set_read_timeout(&self, dur: Option) -> io::Result<()> { - self.0.set_read_timeout(dur) - } - - /// Sets the write timeout to the timeout specified. - /// - /// If the value specified is [`None`], then [`write`] calls will block - /// indefinitely. An [`Err`] is returned if the zero [`Duration`] is - /// passed to this method. - /// - /// # Platform-specific behavior - /// - /// Platforms may return a different error code whenever a write times out - /// as a result of setting this option. For example Unix typically returns - /// an error of the kind [`WouldBlock`], but Windows may return [`TimedOut`]. - /// - /// [`write`]: io::Write::write - /// [`WouldBlock`]: io::ErrorKind::WouldBlock - /// [`TimedOut`]: io::ErrorKind::TimedOut - /// - /// # Examples - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// socket.set_write_timeout(None).expect("set_write_timeout call failed"); - /// ``` - /// - /// An [`Err`] is returned if the zero [`Duration`] is passed to this - /// method: - /// - /// ```no_run - /// use std::io; - /// use std::net::UdpSocket; - /// use std::time::Duration; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").unwrap(); - /// let result = socket.set_write_timeout(Some(Duration::new(0, 0))); - /// let err = result.unwrap_err(); - /// assert_eq!(err.kind(), io::ErrorKind::InvalidInput) - /// ``` - #[stable(feature = "socket_timeout", since = "1.4.0")] - pub fn set_write_timeout(&self, dur: Option) -> io::Result<()> { - self.0.set_write_timeout(dur) - } - - /// Returns the read timeout of this socket. - /// - /// If the timeout is [`None`], then [`read`] calls will block indefinitely. - /// - /// [`read`]: io::Read::read - /// - /// # Examples - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// socket.set_read_timeout(None).expect("set_read_timeout call failed"); - /// assert_eq!(socket.read_timeout().unwrap(), None); - /// ``` - #[stable(feature = "socket_timeout", since = "1.4.0")] - pub fn read_timeout(&self) -> io::Result> { - self.0.read_timeout() - } - - /// Returns the write timeout of this socket. - /// - /// If the timeout is [`None`], then [`write`] calls will block indefinitely. - /// - /// [`write`]: io::Write::write - /// - /// # Examples - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// socket.set_write_timeout(None).expect("set_write_timeout call failed"); - /// assert_eq!(socket.write_timeout().unwrap(), None); - /// ``` - #[stable(feature = "socket_timeout", since = "1.4.0")] - pub fn write_timeout(&self) -> io::Result> { - self.0.write_timeout() - } - - /// Sets the value of the `SO_BROADCAST` option for this socket. - /// - /// When enabled, this socket is allowed to send packets to a broadcast - /// address. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// socket.set_broadcast(false).expect("set_broadcast call failed"); - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn set_broadcast(&self, broadcast: bool) -> io::Result<()> { - self.0.set_broadcast(broadcast) - } - - /// Gets the value of the `SO_BROADCAST` option for this socket. - /// - /// For more information about this option, see [`UdpSocket::set_broadcast`]. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// socket.set_broadcast(false).expect("set_broadcast call failed"); - /// assert_eq!(socket.broadcast().unwrap(), false); - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn broadcast(&self) -> io::Result { - self.0.broadcast() - } - - /// Sets the value of the `IP_MULTICAST_LOOP` option for this socket. - /// - /// If enabled, multicast packets will be looped back to the local socket. - /// Note that this might not have any effect on IPv6 sockets. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// socket.set_multicast_loop_v4(false).expect("set_multicast_loop_v4 call failed"); - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn set_multicast_loop_v4(&self, multicast_loop_v4: bool) -> io::Result<()> { - self.0.set_multicast_loop_v4(multicast_loop_v4) - } - - /// Gets the value of the `IP_MULTICAST_LOOP` option for this socket. - /// - /// For more information about this option, see [`UdpSocket::set_multicast_loop_v4`]. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// socket.set_multicast_loop_v4(false).expect("set_multicast_loop_v4 call failed"); - /// assert_eq!(socket.multicast_loop_v4().unwrap(), false); - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn multicast_loop_v4(&self) -> io::Result { - self.0.multicast_loop_v4() - } - - /// Sets the value of the `IP_MULTICAST_TTL` option for this socket. - /// - /// Indicates the time-to-live value of outgoing multicast packets for - /// this socket. The default value is 1 which means that multicast packets - /// don't leave the local network unless explicitly requested. - /// - /// Note that this might not have any effect on IPv6 sockets. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// socket.set_multicast_ttl_v4(42).expect("set_multicast_ttl_v4 call failed"); - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn set_multicast_ttl_v4(&self, multicast_ttl_v4: u32) -> io::Result<()> { - self.0.set_multicast_ttl_v4(multicast_ttl_v4) - } - - /// Gets the value of the `IP_MULTICAST_TTL` option for this socket. - /// - /// For more information about this option, see [`UdpSocket::set_multicast_ttl_v4`]. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// socket.set_multicast_ttl_v4(42).expect("set_multicast_ttl_v4 call failed"); - /// assert_eq!(socket.multicast_ttl_v4().unwrap(), 42); - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn multicast_ttl_v4(&self) -> io::Result { - self.0.multicast_ttl_v4() - } - - /// Sets the value of the `IPV6_MULTICAST_LOOP` option for this socket. - /// - /// Controls whether this socket sees the multicast packets it sends itself. - /// Note that this might not have any affect on IPv4 sockets. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// socket.set_multicast_loop_v6(false).expect("set_multicast_loop_v6 call failed"); - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn set_multicast_loop_v6(&self, multicast_loop_v6: bool) -> io::Result<()> { - self.0.set_multicast_loop_v6(multicast_loop_v6) - } - - /// Gets the value of the `IPV6_MULTICAST_LOOP` option for this socket. - /// - /// For more information about this option, see [`UdpSocket::set_multicast_loop_v6`]. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// socket.set_multicast_loop_v6(false).expect("set_multicast_loop_v6 call failed"); - /// assert_eq!(socket.multicast_loop_v6().unwrap(), false); - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn multicast_loop_v6(&self) -> io::Result { - self.0.multicast_loop_v6() - } - - /// Sets the value for the `IP_TTL` option on this socket. - /// - /// This value sets the time-to-live field that is used in every packet sent - /// from this socket. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// socket.set_ttl(42).expect("set_ttl call failed"); - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn set_ttl(&self, ttl: u32) -> io::Result<()> { - self.0.set_ttl(ttl) - } - - /// Gets the value of the `IP_TTL` option for this socket. - /// - /// For more information about this option, see [`UdpSocket::set_ttl`]. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// socket.set_ttl(42).expect("set_ttl call failed"); - /// assert_eq!(socket.ttl().unwrap(), 42); - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn ttl(&self) -> io::Result { - self.0.ttl() - } - - /// Executes an operation of the `IP_ADD_MEMBERSHIP` type. - /// - /// This function specifies a new multicast group for this socket to join. - /// The address must be a valid multicast address, and `interface` is the - /// address of the local interface with which the system should join the - /// multicast group. If it's equal to `INADDR_ANY` then an appropriate - /// interface is chosen by the system. - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn join_multicast_v4(&self, multiaddr: &Ipv4Addr, interface: &Ipv4Addr) -> io::Result<()> { - self.0.join_multicast_v4(multiaddr, interface) - } - - /// Executes an operation of the `IPV6_ADD_MEMBERSHIP` type. - /// - /// This function specifies a new multicast group for this socket to join. - /// The address must be a valid multicast address, and `interface` is the - /// index of the interface to join/leave (or 0 to indicate any interface). - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn join_multicast_v6(&self, multiaddr: &Ipv6Addr, interface: u32) -> io::Result<()> { - self.0.join_multicast_v6(multiaddr, interface) - } - - /// Executes an operation of the `IP_DROP_MEMBERSHIP` type. - /// - /// For more information about this option, see [`UdpSocket::join_multicast_v4`]. - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn leave_multicast_v4(&self, multiaddr: &Ipv4Addr, interface: &Ipv4Addr) -> io::Result<()> { - self.0.leave_multicast_v4(multiaddr, interface) - } - - /// Executes an operation of the `IPV6_DROP_MEMBERSHIP` type. - /// - /// For more information about this option, see [`UdpSocket::join_multicast_v6`]. - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn leave_multicast_v6(&self, multiaddr: &Ipv6Addr, interface: u32) -> io::Result<()> { - self.0.leave_multicast_v6(multiaddr, interface) - } - - /// Gets the value of the `SO_ERROR` option on this socket. - /// - /// This will retrieve the stored error in the underlying socket, clearing - /// the field in the process. This can be useful for checking errors between - /// calls. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// match socket.take_error() { - /// Ok(Some(error)) => println!("UdpSocket error: {error:?}"), - /// Ok(None) => println!("No error"), - /// Err(error) => println!("UdpSocket.take_error failed: {error:?}"), - /// } - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn take_error(&self) -> io::Result> { - self.0.take_error() - } - - /// Connects this UDP socket to a remote address, allowing the `send` and - /// `recv` syscalls to be used to send data and also applies filters to only - /// receive data from the specified address. - /// - /// If `addr` yields multiple addresses, `connect` will be attempted with - /// each of the addresses until the underlying OS function returns no - /// error. Note that usually, a successful `connect` call does not specify - /// that there is a remote server listening on the port, rather, such an - /// error would only be detected after the first send. If the OS returns an - /// error for each of the specified addresses, the error returned from the - /// last connection attempt (the last address) is returned. - /// - /// # Examples - /// - /// Creates a UDP socket bound to `127.0.0.1:3400` and connect the socket to - /// `127.0.0.1:8080`: - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:3400").expect("couldn't bind to address"); - /// socket.connect("127.0.0.1:8080").expect("connect function failed"); - /// ``` - /// - /// Unlike in the TCP case, passing an array of addresses to the `connect` - /// function of a UDP socket is not a useful thing to do: The OS will be - /// unable to determine whether something is listening on the remote - /// address without the application sending data. - /// - /// If your first `connect` is to a loopback address, subsequent - /// `connect`s to non-loopback addresses might fail, depending - /// on the platform. - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn connect(&self, addr: A) -> io::Result<()> { - super::each_addr(addr, |addr| self.0.connect(addr)) - } - - /// Sends data on the socket to the remote address to which it is connected. - /// On success, returns the number of bytes written. Note that the operating - /// system may refuse buffers larger than 65507. However, partial writes are - /// not possible until buffer sizes above `i32::MAX`. - /// - /// [`UdpSocket::connect`] will connect this socket to a remote address. This - /// method will fail if the socket is not connected. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// socket.connect("127.0.0.1:8080").expect("connect function failed"); - /// socket.send(&[0, 1, 2]).expect("couldn't send message"); - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn send(&self, buf: &[u8]) -> io::Result { - self.0.send(buf) - } - - /// Receives a single datagram message on the socket from the remote address to - /// which it is connected. On success, returns the number of bytes read. - /// - /// The function must be called with valid byte array `buf` of sufficient size to - /// hold the message bytes. If a message is too long to fit in the supplied buffer, - /// excess bytes may be discarded. - /// - /// [`UdpSocket::connect`] will connect this socket to a remote address. This - /// method will fail if the socket is not connected. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// socket.connect("127.0.0.1:8080").expect("connect function failed"); - /// let mut buf = [0; 10]; - /// match socket.recv(&mut buf) { - /// Ok(received) => println!("received {received} bytes {:?}", &buf[..received]), - /// Err(e) => println!("recv function failed: {e:?}"), - /// } - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn recv(&self, buf: &mut [u8]) -> io::Result { - self.0.recv(buf) - } - - /// Receives single datagram on the socket from the remote address to which it is - /// connected, without removing the message from input queue. On success, returns - /// the number of bytes peeked. - /// - /// The function must be called with valid byte array `buf` of sufficient size to - /// hold the message bytes. If a message is too long to fit in the supplied buffer, - /// excess bytes may be discarded. - /// - /// Successive calls return the same data. This is accomplished by passing - /// `MSG_PEEK` as a flag to the underlying `recv` system call. - /// - /// Do not use this function to implement busy waiting, instead use `libc::poll` to - /// synchronize IO events on one or more sockets. - /// - /// [`UdpSocket::connect`] will connect this socket to a remote address. This - /// method will fail if the socket is not connected. - /// - /// # Errors - /// - /// This method will fail if the socket is not connected. The `connect` method - /// will connect this socket to a remote address. - /// - /// # Examples - /// - /// ```no_run - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:34254").expect("couldn't bind to address"); - /// socket.connect("127.0.0.1:8080").expect("connect function failed"); - /// let mut buf = [0; 10]; - /// match socket.peek(&mut buf) { - /// Ok(received) => println!("received {received} bytes"), - /// Err(e) => println!("peek function failed: {e:?}"), - /// } - /// ``` - #[stable(feature = "peek", since = "1.18.0")] - pub fn peek(&self, buf: &mut [u8]) -> io::Result { - self.0.peek(buf) - } - - /// Moves this UDP socket into or out of nonblocking mode. - /// - /// This will result in `recv`, `recv_from`, `send`, and `send_to` - /// operations becoming nonblocking, i.e., immediately returning from their - /// calls. If the IO operation is successful, `Ok` is returned and no - /// further action is required. If the IO operation could not be completed - /// and needs to be retried, an error with kind - /// [`io::ErrorKind::WouldBlock`] is returned. - /// - /// On Unix platforms, calling this method corresponds to calling `fcntl` - /// `FIONBIO`. On Windows calling this method corresponds to calling - /// `ioctlsocket` `FIONBIO`. - /// - /// # Examples - /// - /// Creates a UDP socket bound to `127.0.0.1:7878` and read bytes in - /// nonblocking mode: - /// - /// ```no_run - /// use std::io; - /// use std::net::UdpSocket; - /// - /// let socket = UdpSocket::bind("127.0.0.1:7878").unwrap(); - /// socket.set_nonblocking(true).unwrap(); - /// - /// # fn wait_for_fd() { unimplemented!() } - /// let mut buf = [0; 10]; - /// let (num_bytes_read, _) = loop { - /// match socket.recv_from(&mut buf) { - /// Ok(n) => break n, - /// Err(ref e) if e.kind() == io::ErrorKind::WouldBlock => { - /// // wait until network socket is ready, typically implemented - /// // via platform-specific APIs such as epoll or IOCP - /// wait_for_fd(); - /// } - /// Err(e) => panic!("encountered IO error: {e}"), - /// } - /// }; - /// println!("bytes: {:?}", &buf[..num_bytes_read]); - /// ``` - #[stable(feature = "net2_mutators", since = "1.9.0")] - pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> { - self.0.set_nonblocking(nonblocking) - } -} - -// In addition to the `impl`s here, `UdpSocket` also has `impl`s for -// `AsFd`/`From`/`Into` and -// `AsRawFd`/`IntoRawFd`/`FromRawFd`, on Unix and WASI, and -// `AsSocket`/`From`/`Into` and -// `AsRawSocket`/`IntoRawSocket`/`FromRawSocket` on Windows. - -impl AsInner for UdpSocket { - #[inline] - fn as_inner(&self) -> &net_imp::UdpSocket { - &self.0 - } -} - -impl FromInner for UdpSocket { - fn from_inner(inner: net_imp::UdpSocket) -> UdpSocket { - UdpSocket(inner) - } -} - -impl IntoInner for UdpSocket { - fn into_inner(self) -> net_imp::UdpSocket { - self.0 - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for UdpSocket { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0.fmt(f) - } -} diff --git a/library/std/src/net/udp/tests.rs b/library/std/src/net/udp/tests.rs deleted file mode 100644 index 0cf9936645290..0000000000000 --- a/library/std/src/net/udp/tests.rs +++ /dev/null @@ -1,367 +0,0 @@ -use crate::net::test::{next_test_ip4, next_test_ip6}; -use crate::net::*; -use crate::sync::mpsc::channel; -use crate::thread; -use crate::time::{Duration, Instant}; - -fn each_ip(f: &mut dyn FnMut(SocketAddr, SocketAddr)) { - f(next_test_ip4(), next_test_ip4()); - f(next_test_ip6(), next_test_ip6()); -} - -macro_rules! t { - ($e:expr) => { - match $e { - Ok(t) => t, - Err(e) => panic!("received error for `{}`: {}", stringify!($e), e), - } - }; -} - -#[test] -fn bind_error() { - match UdpSocket::bind("1.1.1.1:9999") { - Ok(..) => panic!(), - Err(e) => assert_eq!(e.kind(), ErrorKind::AddrNotAvailable), - } -} - -#[test] -fn socket_smoke_test_ip4() { - each_ip(&mut |server_ip, client_ip| { - let (tx1, rx1) = channel(); - let (tx2, rx2) = channel(); - - let _t = thread::spawn(move || { - let client = t!(UdpSocket::bind(&client_ip)); - rx1.recv().unwrap(); - t!(client.send_to(&[99], &server_ip)); - tx2.send(()).unwrap(); - }); - - let server = t!(UdpSocket::bind(&server_ip)); - tx1.send(()).unwrap(); - let mut buf = [0]; - let (nread, src) = t!(server.recv_from(&mut buf)); - assert_eq!(nread, 1); - assert_eq!(buf[0], 99); - assert_eq!(src, client_ip); - rx2.recv().unwrap(); - }) -} - -#[test] -fn socket_name() { - each_ip(&mut |addr, _| { - let server = t!(UdpSocket::bind(&addr)); - assert_eq!(addr, t!(server.local_addr())); - }) -} - -#[test] -fn socket_peer() { - each_ip(&mut |addr1, addr2| { - let server = t!(UdpSocket::bind(&addr1)); - assert_eq!(server.peer_addr().unwrap_err().kind(), ErrorKind::NotConnected); - t!(server.connect(&addr2)); - assert_eq!(addr2, t!(server.peer_addr())); - }) -} - -#[test] -fn udp_clone_smoke() { - each_ip(&mut |addr1, addr2| { - let sock1 = t!(UdpSocket::bind(&addr1)); - let sock2 = t!(UdpSocket::bind(&addr2)); - - let _t = thread::spawn(move || { - let mut buf = [0, 0]; - assert_eq!(sock2.recv_from(&mut buf).unwrap(), (1, addr1)); - assert_eq!(buf[0], 1); - t!(sock2.send_to(&[2], &addr1)); - }); - - let sock3 = t!(sock1.try_clone()); - - let (tx1, rx1) = channel(); - let (tx2, rx2) = channel(); - let _t = thread::spawn(move || { - rx1.recv().unwrap(); - t!(sock3.send_to(&[1], &addr2)); - tx2.send(()).unwrap(); - }); - tx1.send(()).unwrap(); - let mut buf = [0, 0]; - assert_eq!(sock1.recv_from(&mut buf).unwrap(), (1, addr2)); - rx2.recv().unwrap(); - }) -} - -#[test] -fn udp_clone_two_read() { - each_ip(&mut |addr1, addr2| { - let sock1 = t!(UdpSocket::bind(&addr1)); - let sock2 = t!(UdpSocket::bind(&addr2)); - let (tx1, rx) = channel(); - let tx2 = tx1.clone(); - - let _t = thread::spawn(move || { - t!(sock2.send_to(&[1], &addr1)); - rx.recv().unwrap(); - t!(sock2.send_to(&[2], &addr1)); - rx.recv().unwrap(); - }); - - let sock3 = t!(sock1.try_clone()); - - let (done, rx) = channel(); - let _t = thread::spawn(move || { - let mut buf = [0, 0]; - t!(sock3.recv_from(&mut buf)); - tx2.send(()).unwrap(); - done.send(()).unwrap(); - }); - let mut buf = [0, 0]; - t!(sock1.recv_from(&mut buf)); - tx1.send(()).unwrap(); - - rx.recv().unwrap(); - }) -} - -#[test] -fn udp_clone_two_write() { - each_ip(&mut |addr1, addr2| { - let sock1 = t!(UdpSocket::bind(&addr1)); - let sock2 = t!(UdpSocket::bind(&addr2)); - - let (tx, rx) = channel(); - let (serv_tx, serv_rx) = channel(); - - let _t = thread::spawn(move || { - let mut buf = [0, 1]; - rx.recv().unwrap(); - t!(sock2.recv_from(&mut buf)); - serv_tx.send(()).unwrap(); - }); - - let sock3 = t!(sock1.try_clone()); - - let (done, rx) = channel(); - let tx2 = tx.clone(); - let _t = thread::spawn(move || { - if sock3.send_to(&[1], &addr2).is_ok() { - let _ = tx2.send(()); - } - done.send(()).unwrap(); - }); - if sock1.send_to(&[2], &addr2).is_ok() { - let _ = tx.send(()); - } - drop(tx); - - rx.recv().unwrap(); - serv_rx.recv().unwrap(); - }) -} - -#[test] -fn debug() { - let name = if cfg!(windows) { "socket" } else { "fd" }; - let socket_addr = next_test_ip4(); - - let udpsock = t!(UdpSocket::bind(&socket_addr)); - let udpsock_inner = udpsock.0.socket().as_raw(); - let compare = format!("UdpSocket {{ addr: {socket_addr:?}, {name}: {udpsock_inner:?} }}"); - assert_eq!(format!("{udpsock:?}"), compare); -} - -// FIXME: re-enabled openbsd/netbsd tests once their socket timeout code -// no longer has rounding errors. -// VxWorks ignores SO_SNDTIMEO. -#[cfg_attr( - any(target_os = "netbsd", target_os = "openbsd", target_os = "vxworks", target_os = "nto"), - ignore -)] -#[test] -fn timeouts() { - let addr = next_test_ip4(); - - let stream = t!(UdpSocket::bind(&addr)); - let dur = Duration::new(15410, 0); - - assert_eq!(None, t!(stream.read_timeout())); - - t!(stream.set_read_timeout(Some(dur))); - assert_eq!(Some(dur), t!(stream.read_timeout())); - - assert_eq!(None, t!(stream.write_timeout())); - - t!(stream.set_write_timeout(Some(dur))); - assert_eq!(Some(dur), t!(stream.write_timeout())); - - t!(stream.set_read_timeout(None)); - assert_eq!(None, t!(stream.read_timeout())); - - t!(stream.set_write_timeout(None)); - assert_eq!(None, t!(stream.write_timeout())); -} - -#[test] -fn test_read_timeout() { - let addr = next_test_ip4(); - - let stream = t!(UdpSocket::bind(&addr)); - t!(stream.set_read_timeout(Some(Duration::from_millis(1000)))); - - let mut buf = [0; 10]; - - let start = Instant::now(); - loop { - let kind = stream.recv_from(&mut buf).err().expect("expected error").kind(); - if kind != ErrorKind::Interrupted { - assert!( - kind == ErrorKind::WouldBlock || kind == ErrorKind::TimedOut, - "unexpected_error: {:?}", - kind - ); - break; - } - } - assert!(start.elapsed() > Duration::from_millis(400)); -} - -#[test] -fn test_read_with_timeout() { - let addr = next_test_ip4(); - - let stream = t!(UdpSocket::bind(&addr)); - t!(stream.set_read_timeout(Some(Duration::from_millis(1000)))); - - t!(stream.send_to(b"hello world", &addr)); - - let mut buf = [0; 11]; - t!(stream.recv_from(&mut buf)); - assert_eq!(b"hello world", &buf[..]); - - let start = Instant::now(); - loop { - let kind = stream.recv_from(&mut buf).err().expect("expected error").kind(); - if kind != ErrorKind::Interrupted { - assert!( - kind == ErrorKind::WouldBlock || kind == ErrorKind::TimedOut, - "unexpected_error: {:?}", - kind - ); - break; - } - } - assert!(start.elapsed() > Duration::from_millis(400)); -} - -// Ensure the `set_read_timeout` and `set_write_timeout` calls return errors -// when passed zero Durations -#[test] -fn test_timeout_zero_duration() { - let addr = next_test_ip4(); - - let socket = t!(UdpSocket::bind(&addr)); - - let result = socket.set_write_timeout(Some(Duration::new(0, 0))); - let err = result.unwrap_err(); - assert_eq!(err.kind(), ErrorKind::InvalidInput); - - let result = socket.set_read_timeout(Some(Duration::new(0, 0))); - let err = result.unwrap_err(); - assert_eq!(err.kind(), ErrorKind::InvalidInput); -} - -#[test] -fn connect_send_recv() { - let addr = next_test_ip4(); - - let socket = t!(UdpSocket::bind(&addr)); - t!(socket.connect(addr)); - - t!(socket.send(b"hello world")); - - let mut buf = [0; 11]; - t!(socket.recv(&mut buf)); - assert_eq!(b"hello world", &buf[..]); -} - -#[test] -fn connect_send_peek_recv() { - each_ip(&mut |addr, _| { - let socket = t!(UdpSocket::bind(&addr)); - t!(socket.connect(addr)); - - t!(socket.send(b"hello world")); - - for _ in 1..3 { - let mut buf = [0; 11]; - let size = t!(socket.peek(&mut buf)); - assert_eq!(b"hello world", &buf[..]); - assert_eq!(size, 11); - } - - let mut buf = [0; 11]; - let size = t!(socket.recv(&mut buf)); - assert_eq!(b"hello world", &buf[..]); - assert_eq!(size, 11); - }) -} - -#[test] -fn peek_from() { - each_ip(&mut |addr, _| { - let socket = t!(UdpSocket::bind(&addr)); - t!(socket.send_to(b"hello world", &addr)); - - for _ in 1..3 { - let mut buf = [0; 11]; - let (size, _) = t!(socket.peek_from(&mut buf)); - assert_eq!(b"hello world", &buf[..]); - assert_eq!(size, 11); - } - - let mut buf = [0; 11]; - let (size, _) = t!(socket.recv_from(&mut buf)); - assert_eq!(b"hello world", &buf[..]); - assert_eq!(size, 11); - }) -} - -#[test] -fn ttl() { - let ttl = 100; - - let addr = next_test_ip4(); - - let stream = t!(UdpSocket::bind(&addr)); - - t!(stream.set_ttl(ttl)); - assert_eq!(ttl, t!(stream.ttl())); -} - -#[test] -fn set_nonblocking() { - each_ip(&mut |addr, _| { - let socket = t!(UdpSocket::bind(&addr)); - - t!(socket.set_nonblocking(true)); - t!(socket.set_nonblocking(false)); - - t!(socket.connect(addr)); - - t!(socket.set_nonblocking(false)); - t!(socket.set_nonblocking(true)); - - let mut buf = [0]; - match socket.recv(&mut buf) { - Ok(_) => panic!("expected error"), - Err(ref e) if e.kind() == ErrorKind::WouldBlock => {} - Err(e) => panic!("unexpected error {e}"), - } - }) -} diff --git a/library/std/src/num.rs b/library/std/src/num.rs deleted file mode 100644 index 8910cdea7c0c9..0000000000000 --- a/library/std/src/num.rs +++ /dev/null @@ -1,61 +0,0 @@ -//! Additional functionality for numerics. -//! -//! This module provides some extra types that are useful when doing numerical -//! work. See the individual documentation for each piece for more information. - -#![stable(feature = "rust1", since = "1.0.0")] -#![allow(missing_docs)] - -#[cfg(test)] -mod tests; - -#[stable(feature = "saturating_int_impl", since = "1.74.0")] -pub use core::num::Saturating; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::num::Wrapping; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::num::{FpCategory, ParseFloatError, ParseIntError, TryFromIntError}; - -#[unstable( - feature = "nonzero_internals", - reason = "implementation detail which may disappear or be replaced at any time", - issue = "none" -)] -pub use core::num::ZeroablePrimitive; - -#[stable(feature = "generic_nonzero", since = "1.79.0")] -pub use core::num::NonZero; - -#[stable(feature = "signed_nonzero", since = "1.34.0")] -pub use core::num::{NonZeroI128, NonZeroI16, NonZeroI32, NonZeroI64, NonZeroI8, NonZeroIsize}; - -#[stable(feature = "nonzero", since = "1.28.0")] -pub use core::num::{NonZeroU128, NonZeroU16, NonZeroU32, NonZeroU64, NonZeroU8, NonZeroUsize}; - -#[stable(feature = "int_error_matching", since = "1.55.0")] -pub use core::num::IntErrorKind; - -#[cfg(test)] -use crate::fmt; -#[cfg(test)] -use crate::ops::{Add, Div, Mul, Rem, Sub}; - -/// Helper function for testing numeric operations -#[cfg(test)] -pub fn test_num(ten: T, two: T) -where - T: PartialEq - + Add - + Sub - + Mul - + Div - + Rem - + fmt::Debug - + Copy, -{ - assert_eq!(ten.add(two), ten + two); - assert_eq!(ten.sub(two), ten - two); - assert_eq!(ten.mul(two), ten * two); - assert_eq!(ten.div(two), ten / two); - assert_eq!(ten.rem(two), ten % two); -} diff --git a/library/std/src/num/tests.rs b/library/std/src/num/tests.rs deleted file mode 100644 index df0df3f23f756..0000000000000 --- a/library/std/src/num/tests.rs +++ /dev/null @@ -1,230 +0,0 @@ -use crate::ops::Mul; - -#[test] -fn test_saturating_add_uint() { - assert_eq!(3_usize.saturating_add(5_usize), 8_usize); - assert_eq!(3_usize.saturating_add(usize::MAX - 1), usize::MAX); - assert_eq!(usize::MAX.saturating_add(usize::MAX), usize::MAX); - assert_eq!((usize::MAX - 2).saturating_add(1), usize::MAX - 1); -} - -#[test] -fn test_saturating_sub_uint() { - assert_eq!(5_usize.saturating_sub(3_usize), 2_usize); - assert_eq!(3_usize.saturating_sub(5_usize), 0_usize); - assert_eq!(0_usize.saturating_sub(1_usize), 0_usize); - assert_eq!((usize::MAX - 1).saturating_sub(usize::MAX), 0); -} - -#[test] -fn test_saturating_add_int() { - assert_eq!(3i32.saturating_add(5), 8); - assert_eq!(3isize.saturating_add(isize::MAX - 1), isize::MAX); - assert_eq!(isize::MAX.saturating_add(isize::MAX), isize::MAX); - assert_eq!((isize::MAX - 2).saturating_add(1), isize::MAX - 1); - assert_eq!(3i32.saturating_add(-5), -2); - assert_eq!(isize::MIN.saturating_add(-1), isize::MIN); - assert_eq!((-2isize).saturating_add(-isize::MAX), isize::MIN); -} - -#[test] -fn test_saturating_sub_int() { - assert_eq!(3i32.saturating_sub(5), -2); - assert_eq!(isize::MIN.saturating_sub(1), isize::MIN); - assert_eq!((-2isize).saturating_sub(isize::MAX), isize::MIN); - assert_eq!(3i32.saturating_sub(-5), 8); - assert_eq!(3isize.saturating_sub(-(isize::MAX - 1)), isize::MAX); - assert_eq!(isize::MAX.saturating_sub(-isize::MAX), isize::MAX); - assert_eq!((isize::MAX - 2).saturating_sub(-1), isize::MAX - 1); -} - -#[test] -fn test_checked_add() { - let five_less = usize::MAX - 5; - assert_eq!(five_less.checked_add(0), Some(usize::MAX - 5)); - assert_eq!(five_less.checked_add(1), Some(usize::MAX - 4)); - assert_eq!(five_less.checked_add(2), Some(usize::MAX - 3)); - assert_eq!(five_less.checked_add(3), Some(usize::MAX - 2)); - assert_eq!(five_less.checked_add(4), Some(usize::MAX - 1)); - assert_eq!(five_less.checked_add(5), Some(usize::MAX)); - assert_eq!(five_less.checked_add(6), None); - assert_eq!(five_less.checked_add(7), None); -} - -#[test] -fn test_checked_sub() { - assert_eq!(5_usize.checked_sub(0), Some(5)); - assert_eq!(5_usize.checked_sub(1), Some(4)); - assert_eq!(5_usize.checked_sub(2), Some(3)); - assert_eq!(5_usize.checked_sub(3), Some(2)); - assert_eq!(5_usize.checked_sub(4), Some(1)); - assert_eq!(5_usize.checked_sub(5), Some(0)); - assert_eq!(5_usize.checked_sub(6), None); - assert_eq!(5_usize.checked_sub(7), None); -} - -#[test] -fn test_checked_mul() { - let third = usize::MAX / 3; - assert_eq!(third.checked_mul(0), Some(0)); - assert_eq!(third.checked_mul(1), Some(third)); - assert_eq!(third.checked_mul(2), Some(third * 2)); - assert_eq!(third.checked_mul(3), Some(third * 3)); - assert_eq!(third.checked_mul(4), None); -} - -macro_rules! test_is_power_of_two { - ($test_name:ident, $T:ident) => { - #[test] - fn $test_name() { - assert_eq!((0 as $T).is_power_of_two(), false); - assert_eq!((1 as $T).is_power_of_two(), true); - assert_eq!((2 as $T).is_power_of_two(), true); - assert_eq!((3 as $T).is_power_of_two(), false); - assert_eq!((4 as $T).is_power_of_two(), true); - assert_eq!((5 as $T).is_power_of_two(), false); - assert_eq!(($T::MAX / 2 + 1).is_power_of_two(), true); - } - }; -} - -test_is_power_of_two! { test_is_power_of_two_u8, u8 } -test_is_power_of_two! { test_is_power_of_two_u16, u16 } -test_is_power_of_two! { test_is_power_of_two_u32, u32 } -test_is_power_of_two! { test_is_power_of_two_u64, u64 } -test_is_power_of_two! { test_is_power_of_two_uint, usize } - -macro_rules! test_next_power_of_two { - ($test_name:ident, $T:ident) => { - #[test] - fn $test_name() { - assert_eq!((0 as $T).next_power_of_two(), 1); - let mut next_power = 1; - for i in 1 as $T..40 { - assert_eq!(i.next_power_of_two(), next_power); - if i == next_power { - next_power *= 2 - } - } - } - }; -} - -test_next_power_of_two! { test_next_power_of_two_u8, u8 } -test_next_power_of_two! { test_next_power_of_two_u16, u16 } -test_next_power_of_two! { test_next_power_of_two_u32, u32 } -test_next_power_of_two! { test_next_power_of_two_u64, u64 } -test_next_power_of_two! { test_next_power_of_two_uint, usize } - -macro_rules! test_checked_next_power_of_two { - ($test_name:ident, $T:ident) => { - #[test] - fn $test_name() { - assert_eq!((0 as $T).checked_next_power_of_two(), Some(1)); - let smax = $T::MAX >> 1; - assert_eq!(smax.checked_next_power_of_two(), Some(smax + 1)); - assert_eq!((smax + 1).checked_next_power_of_two(), Some(smax + 1)); - assert_eq!((smax + 2).checked_next_power_of_two(), None); - assert_eq!(($T::MAX - 1).checked_next_power_of_two(), None); - assert_eq!($T::MAX.checked_next_power_of_two(), None); - let mut next_power = 1; - for i in 1 as $T..40 { - assert_eq!(i.checked_next_power_of_two(), Some(next_power)); - if i == next_power { - next_power *= 2 - } - } - } - }; -} - -test_checked_next_power_of_two! { test_checked_next_power_of_two_u8, u8 } -test_checked_next_power_of_two! { test_checked_next_power_of_two_u16, u16 } -test_checked_next_power_of_two! { test_checked_next_power_of_two_u32, u32 } -test_checked_next_power_of_two! { test_checked_next_power_of_two_u64, u64 } -test_checked_next_power_of_two! { test_checked_next_power_of_two_uint, usize } - -#[test] -fn test_pow() { - fn naive_pow + Copy>(one: T, base: T, exp: usize) -> T { - (0..exp).fold(one, |acc, _| acc * base) - } - macro_rules! assert_pow { - (($num:expr, $exp:expr) => $expected:expr) => {{ - let result = $num.pow($exp); - assert_eq!(result, $expected); - assert_eq!(result, naive_pow(1, $num, $exp)); - }}; - } - assert_pow!((3u32, 0 ) => 1); - assert_pow!((5u32, 1 ) => 5); - assert_pow!((-4i32, 2 ) => 16); - assert_pow!((8u32, 3 ) => 512); - assert_pow!((2u64, 50) => 1125899906842624); -} - -#[test] -fn test_uint_to_str_overflow() { - let mut u8_val: u8 = 255; - assert_eq!(u8_val.to_string(), "255"); - - u8_val = u8_val.wrapping_add(1); - assert_eq!(u8_val.to_string(), "0"); - - let mut u16_val: u16 = 65_535; - assert_eq!(u16_val.to_string(), "65535"); - - u16_val = u16_val.wrapping_add(1); - assert_eq!(u16_val.to_string(), "0"); - - let mut u32_val: u32 = 4_294_967_295; - assert_eq!(u32_val.to_string(), "4294967295"); - - u32_val = u32_val.wrapping_add(1); - assert_eq!(u32_val.to_string(), "0"); - - let mut u64_val: u64 = 18_446_744_073_709_551_615; - assert_eq!(u64_val.to_string(), "18446744073709551615"); - - u64_val = u64_val.wrapping_add(1); - assert_eq!(u64_val.to_string(), "0"); -} - -fn from_str(t: &str) -> Option { - crate::str::FromStr::from_str(t).ok() -} - -#[test] -fn test_uint_from_str_overflow() { - let mut u8_val: u8 = 255; - assert_eq!(from_str::("255"), Some(u8_val)); - assert_eq!(from_str::("256"), None); - - u8_val = u8_val.wrapping_add(1); - assert_eq!(from_str::("0"), Some(u8_val)); - assert_eq!(from_str::("-1"), None); - - let mut u16_val: u16 = 65_535; - assert_eq!(from_str::("65535"), Some(u16_val)); - assert_eq!(from_str::("65536"), None); - - u16_val = u16_val.wrapping_add(1); - assert_eq!(from_str::("0"), Some(u16_val)); - assert_eq!(from_str::("-1"), None); - - let mut u32_val: u32 = 4_294_967_295; - assert_eq!(from_str::("4294967295"), Some(u32_val)); - assert_eq!(from_str::("4294967296"), None); - - u32_val = u32_val.wrapping_add(1); - assert_eq!(from_str::("0"), Some(u32_val)); - assert_eq!(from_str::("-1"), None); - - let mut u64_val: u64 = 18_446_744_073_709_551_615; - assert_eq!(from_str::("18446744073709551615"), Some(u64_val)); - assert_eq!(from_str::("18446744073709551616"), None); - - u64_val = u64_val.wrapping_add(1); - assert_eq!(from_str::("0"), Some(u64_val)); - assert_eq!(from_str::("-1"), None); -} diff --git a/library/std/src/os/aix/fs.rs b/library/std/src/os/aix/fs.rs deleted file mode 100644 index ac9dd45f05426..0000000000000 --- a/library/std/src/os/aix/fs.rs +++ /dev/null @@ -1,348 +0,0 @@ -//! AIX specific extensions to primitives in the [`std::fs`] module. -//! -//! [`std::fs`]: crate::fs - -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::Metadata; -use crate::sys_common::AsInner; - -/// OS-specific extensions to [`fs::Metadata`]. -/// -/// [`fs::Metadata`]: crate::fs::Metadata -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - /// Returns the device ID on which this file resides. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::aix::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_dev()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - /// Returns the inode number. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::aix::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_ino()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - /// Returns the file type and mode. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::aix::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_mode()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - /// Returns the number of hard links to file. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::aix::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_nlink()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - /// Returns the user ID of the file owner. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::aix::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_uid()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - /// Returns the group ID of the file owner. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::aix::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_gid()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - /// Returns the device ID that this file represents. Only relevant for special file. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::aix::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_rdev()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - /// Returns the size of the file (if it is a regular file or a symbolic link) in bytes. - /// - /// The size of a symbolic link is the length of the pathname it contains, - /// without a terminating null byte. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::aix::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_size()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - /// Returns the last access time of the file, in seconds since Unix Epoch. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::aix::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_atime()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - /// Returns the last access time of the file, in nanoseconds since [`st_atime`]. - /// - /// [`st_atime`]: Self::st_atime - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::aix::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_atime_nsec()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - /// Returns the last modification time of the file, in seconds since Unix Epoch. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::aix::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_mtime()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - /// Returns the last modification time of the file, in nanoseconds since [`st_mtime`]. - /// - /// [`st_mtime`]: Self::st_mtime - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::aix::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_mtime_nsec()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - /// Returns the last status change time of the file, in seconds since Unix Epoch. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::aix::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_ctime()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - /// Returns the last status change time of the file, in nanoseconds since [`st_ctime`]. - /// - /// [`st_ctime`]: Self::st_ctime - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::aix::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_ctime_nsec()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - /// Returns the "preferred" block size for efficient filesystem I/O. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::aix::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_blksize()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - /// Returns the number of blocks allocated to the file, 512-byte units. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::aix::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_blocks()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_dev as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - self.as_inner().as_inner().st_atime.tv_sec as i64 - } - fn st_atime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_atime.tv_nsec as i64 - } - fn st_mtime(&self) -> i64 { - self.as_inner().as_inner().st_mtime.tv_sec as i64 - } - fn st_mtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_mtime.tv_nsec as i64 - } - fn st_ctime(&self) -> i64 { - self.as_inner().as_inner().st_ctime.tv_sec as i64 - } - fn st_ctime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_ctime.tv_nsec as i64 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } -} diff --git a/library/std/src/os/aix/mod.rs b/library/std/src/os/aix/mod.rs deleted file mode 100644 index 7f86a3c77f210..0000000000000 --- a/library/std/src/os/aix/mod.rs +++ /dev/null @@ -1,6 +0,0 @@ -//! AIX specific definitions. - -#![stable(feature = "raw_ext", since = "1.1.0")] - -pub mod fs; -pub mod raw; diff --git a/library/std/src/os/aix/raw.rs b/library/std/src/os/aix/raw.rs deleted file mode 100644 index b4c8dc72cfe5b..0000000000000 --- a/library/std/src/os/aix/raw.rs +++ /dev/null @@ -1,9 +0,0 @@ -//! AIX specific raw type definitions. - -#![stable(feature = "raw_ext", since = "1.1.0")] - -#[stable(feature = "pthread_t", since = "1.8.0")] -pub use libc::pthread_t; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub use libc::{blkcnt_t, blksize_t, dev_t, ino_t, mode_t, nlink_t, off_t, stat, time_t}; diff --git a/library/std/src/os/android/fs.rs b/library/std/src/os/android/fs.rs deleted file mode 100644 index 1beb3cf6e84b5..0000000000000 --- a/library/std/src/os/android/fs.rs +++ /dev/null @@ -1,117 +0,0 @@ -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::Metadata; -use crate::sys_common::AsInner; - -#[allow(deprecated)] -use crate::os::android::raw; - -/// OS-specific extensions to [`fs::Metadata`]. -/// -/// [`fs::Metadata`]: crate::fs::Metadata -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - /// Gain a reference to the underlying `stat` structure which contains - /// the raw information returned by the OS. - /// - /// The contents of the returned `stat` are **not** consistent across - /// Unix platforms. The `os::unix::fs::MetadataExt` trait contains the - /// cross-Unix abstractions contained within the raw stat. - #[stable(feature = "metadata_ext", since = "1.1.0")] - #[deprecated( - since = "1.8.0", - note = "deprecated in favor of the accessor \ - methods of this trait" - )] - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat; - - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat { - unsafe { &*(self.as_inner().as_inner() as *const libc::stat as *const raw::stat) } - } - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_dev as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - self.as_inner().as_inner().st_atime as i64 - } - fn st_atime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_atime_nsec as i64 - } - fn st_mtime(&self) -> i64 { - self.as_inner().as_inner().st_mtime as i64 - } - fn st_mtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_mtime_nsec as i64 - } - fn st_ctime(&self) -> i64 { - self.as_inner().as_inner().st_ctime as i64 - } - fn st_ctime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_ctime_nsec as i64 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } -} diff --git a/library/std/src/os/android/mod.rs b/library/std/src/os/android/mod.rs deleted file mode 100644 index 5adcb82b6a49b..0000000000000 --- a/library/std/src/os/android/mod.rs +++ /dev/null @@ -1,7 +0,0 @@ -//! Android-specific definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] - -pub mod fs; -pub mod net; -pub mod raw; diff --git a/library/std/src/os/android/net.rs b/library/std/src/os/android/net.rs deleted file mode 100644 index 349e73eaabdaf..0000000000000 --- a/library/std/src/os/android/net.rs +++ /dev/null @@ -1,12 +0,0 @@ -//! Android-specific networking functionality. - -#![stable(feature = "unix_socket_abstract", since = "1.70.0")] - -#[stable(feature = "unix_socket_abstract", since = "1.70.0")] -pub use crate::os::net::linux_ext::addr::SocketAddrExt; - -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -pub use crate::os::net::linux_ext::socket::UnixSocketExt; - -#[unstable(feature = "tcp_quickack", issue = "96256")] -pub use crate::os::net::linux_ext::tcp::TcpStreamExt; diff --git a/library/std/src/os/android/raw.rs b/library/std/src/os/android/raw.rs deleted file mode 100644 index 175f8eac97176..0000000000000 --- a/library/std/src/os/android/raw.rs +++ /dev/null @@ -1,230 +0,0 @@ -//! Android-specific raw type definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![deprecated( - since = "1.8.0", - note = "these type aliases are no longer supported by \ - the standard library, the `libc` crate on \ - crates.io should be used instead for the correct \ - definitions" -)] -#![allow(deprecated)] - -use crate::os::raw::c_long; - -#[stable(feature = "pthread_t", since = "1.8.0")] -pub type pthread_t = c_long; - -#[doc(inline)] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub use self::arch::{blkcnt_t, blksize_t, dev_t, ino_t, mode_t, nlink_t, off_t, stat, time_t}; - -#[cfg(any(target_arch = "arm", target_arch = "x86"))] -mod arch { - use crate::os::raw::{c_long, c_longlong, c_uchar, c_uint, c_ulong, c_ulonglong}; - use crate::os::unix::raw::{gid_t, uid_t}; - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type dev_t = u32; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type mode_t = c_uint; - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blkcnt_t = c_ulong; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blksize_t = c_ulong; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type ino_t = c_ulong; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type nlink_t = u32; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type off_t = i32; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type time_t = c_long; - - #[repr(C)] - #[derive(Clone)] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: c_ulonglong, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad0: [c_uchar; 4], - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __st_ino: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: c_uint, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: c_uint, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: uid_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: gid_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: c_ulonglong, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad3: [c_uchar; 4], - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: c_longlong, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: c_ulonglong, - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: c_ulonglong, - } -} - -#[cfg(any(target_arch = "aarch64", target_arch = "riscv64"))] -mod arch { - use crate::os::raw::{c_int, c_long, c_uint, c_ulong}; - use crate::os::unix::raw::{gid_t, uid_t}; - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type dev_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type mode_t = c_uint; - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blkcnt_t = c_ulong; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blksize_t = c_ulong; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type ino_t = c_ulong; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type nlink_t = u32; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type off_t = i64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type time_t = c_long; - - #[repr(C)] - #[derive(Clone)] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: dev_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: ino_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: mode_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: nlink_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: uid_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: gid_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: dev_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad1: c_ulong, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: off_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: c_int, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad2: c_int, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: c_long, - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __unused4: c_uint, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __unused5: c_uint, - } -} - -#[cfg(target_arch = "x86_64")] -mod arch { - use crate::os::raw::{c_long, c_uint, c_ulong}; - use crate::os::unix::raw::{gid_t, uid_t}; - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type dev_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type mode_t = c_uint; - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blkcnt_t = c_ulong; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blksize_t = c_ulong; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type ino_t = c_ulong; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type nlink_t = u32; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type off_t = i64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type time_t = c_long; - - #[repr(C)] - #[derive(Clone)] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: dev_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: ino_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: c_ulong, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: c_uint, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: uid_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: gid_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad0: c_uint, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: dev_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: off_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: c_long, - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad3: [c_long; 3], - } -} diff --git a/library/std/src/os/dragonfly/fs.rs b/library/std/src/os/dragonfly/fs.rs deleted file mode 100644 index 1424fc4c69880..0000000000000 --- a/library/std/src/os/dragonfly/fs.rs +++ /dev/null @@ -1,132 +0,0 @@ -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::Metadata; -use crate::sys_common::AsInner; - -#[allow(deprecated)] -use crate::os::dragonfly::raw; - -/// OS-specific extensions to [`fs::Metadata`]. -/// -/// [`fs::Metadata`]: crate::fs::Metadata -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - /// Gain a reference to the underlying `stat` structure which contains - /// the raw information returned by the OS. - /// - /// The contents of the returned `stat` are **not** consistent across - /// Unix platforms. The `os::unix::fs::MetadataExt` trait contains the - /// cross-Unix abstractions contained within the raw stat. - #[stable(feature = "metadata_ext", since = "1.1.0")] - #[deprecated( - since = "1.8.0", - note = "deprecated in favor of the accessor \ - methods of this trait" - )] - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat; - - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_flags(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gen(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_lspare(&self) -> u32; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat { - unsafe { &*(self.as_inner().as_inner() as *const libc::stat as *const raw::stat) } - } - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_dev as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - self.as_inner().as_inner().st_atime as i64 - } - fn st_atime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_atime_nsec as i64 - } - fn st_mtime(&self) -> i64 { - self.as_inner().as_inner().st_mtime as i64 - } - fn st_mtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_mtime_nsec as i64 - } - fn st_ctime(&self) -> i64 { - self.as_inner().as_inner().st_ctime as i64 - } - fn st_ctime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_ctime_nsec as i64 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } - fn st_gen(&self) -> u32 { - self.as_inner().as_inner().st_gen as u32 - } - fn st_flags(&self) -> u32 { - self.as_inner().as_inner().st_flags as u32 - } - fn st_lspare(&self) -> u32 { - self.as_inner().as_inner().st_lspare as u32 - } -} diff --git a/library/std/src/os/dragonfly/mod.rs b/library/std/src/os/dragonfly/mod.rs deleted file mode 100644 index 350b5fca7ea66..0000000000000 --- a/library/std/src/os/dragonfly/mod.rs +++ /dev/null @@ -1,6 +0,0 @@ -//! Dragonfly-specific definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] - -pub mod fs; -pub mod raw; diff --git a/library/std/src/os/dragonfly/raw.rs b/library/std/src/os/dragonfly/raw.rs deleted file mode 100644 index 071bf6199aa23..0000000000000 --- a/library/std/src/os/dragonfly/raw.rs +++ /dev/null @@ -1,83 +0,0 @@ -//! Dragonfly-specific raw type definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![deprecated( - since = "1.8.0", - note = "these type aliases are no longer supported by \ - the standard library, the `libc` crate on \ - crates.io should be used instead for the correct \ - definitions" -)] -#![allow(deprecated)] - -use crate::os::raw::c_long; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blkcnt_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blksize_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type dev_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type fflags_t = u32; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type ino_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type mode_t = u32; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type nlink_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type off_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type time_t = i64; - -#[stable(feature = "pthread_t", since = "1.8.0")] -pub type pthread_t = usize; - -#[repr(C)] -#[derive(Clone)] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: u16, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: u16, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_flags: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gen: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_lspare: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_birthtime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_birthtime_nsec: c_long, -} diff --git a/library/std/src/os/emscripten/fs.rs b/library/std/src/os/emscripten/fs.rs deleted file mode 100644 index d5ec8e03c00d1..0000000000000 --- a/library/std/src/os/emscripten/fs.rs +++ /dev/null @@ -1,117 +0,0 @@ -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::Metadata; -use crate::sys_common::AsInner; - -#[allow(deprecated)] -use crate::os::emscripten::raw; - -/// OS-specific extensions to [`fs::Metadata`]. -/// -/// [`fs::Metadata`]: crate::fs::Metadata -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - /// Gain a reference to the underlying `stat` structure which contains - /// the raw information returned by the OS. - /// - /// The contents of the returned `stat` are **not** consistent across - /// Unix platforms. The `os::unix::fs::MetadataExt` trait contains the - /// cross-Unix abstractions contained within the raw stat. - #[stable(feature = "metadata_ext", since = "1.1.0")] - #[deprecated( - since = "1.8.0", - note = "deprecated in favor of the accessor \ - methods of this trait" - )] - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat; - - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat { - unsafe { &*(self.as_inner().as_inner() as *const libc::stat64 as *const raw::stat) } - } - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_dev as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - self.as_inner().as_inner().st_atime as i64 - } - fn st_atime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_atime_nsec as i64 - } - fn st_mtime(&self) -> i64 { - self.as_inner().as_inner().st_mtime as i64 - } - fn st_mtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_mtime_nsec as i64 - } - fn st_ctime(&self) -> i64 { - self.as_inner().as_inner().st_ctime as i64 - } - fn st_ctime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_ctime_nsec as i64 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } -} diff --git a/library/std/src/os/emscripten/mod.rs b/library/std/src/os/emscripten/mod.rs deleted file mode 100644 index d35307162cc7e..0000000000000 --- a/library/std/src/os/emscripten/mod.rs +++ /dev/null @@ -1,6 +0,0 @@ -//! Linux-specific definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] - -pub mod fs; -pub mod raw; diff --git a/library/std/src/os/emscripten/raw.rs b/library/std/src/os/emscripten/raw.rs deleted file mode 100644 index d23011c738141..0000000000000 --- a/library/std/src/os/emscripten/raw.rs +++ /dev/null @@ -1,80 +0,0 @@ -//! Emscripten-specific raw type definitions -//! This is basically exactly the same as the linux definitions, -//! except using the musl-specific stat64 structure in liblibc. - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![deprecated( - since = "1.8.0", - note = "these type aliases are no longer supported by \ - the standard library, the `libc` crate on \ - crates.io should be used instead for the correct \ - definitions" -)] -#![allow(deprecated)] - -use crate::os::raw::{c_long, c_short, c_uint, c_ulong}; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type dev_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type mode_t = u32; - -#[stable(feature = "pthread_t", since = "1.8.0")] -pub type pthread_t = c_ulong; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blkcnt_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blksize_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type ino_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type nlink_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type off_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type time_t = c_long; - -#[repr(C)] -#[derive(Clone)] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad1: c_short, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __st_ino: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad2: c_uint, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: u64, -} diff --git a/library/std/src/os/espidf/fs.rs b/library/std/src/os/espidf/fs.rs deleted file mode 100644 index 88701dafe20ce..0000000000000 --- a/library/std/src/os/espidf/fs.rs +++ /dev/null @@ -1,117 +0,0 @@ -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::Metadata; -use crate::sys_common::AsInner; - -#[allow(deprecated)] -use crate::os::espidf::raw; - -/// OS-specific extensions to [`fs::Metadata`]. -/// -/// [`fs::Metadata`]: crate::fs::Metadata -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - #[stable(feature = "metadata_ext", since = "1.1.0")] - #[deprecated( - since = "1.8.0", - note = "deprecated in favor of the accessor \ - methods of this trait" - )] - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat; - - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_spare4(&self) -> [u32; 2]; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat { - unsafe { &*(self.as_inner().as_inner() as *const libc::stat as *const raw::stat) } - } - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_dev as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - self.as_inner().as_inner().st_atime as i64 - } - fn st_atime_nsec(&self) -> i64 { - 0 - } - fn st_mtime(&self) -> i64 { - self.as_inner().as_inner().st_mtime as i64 - } - fn st_mtime_nsec(&self) -> i64 { - 0 - } - fn st_ctime(&self) -> i64 { - self.as_inner().as_inner().st_ctime as i64 - } - fn st_ctime_nsec(&self) -> i64 { - 0 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } - fn st_spare4(&self) -> [u32; 2] { - let spare4 = self.as_inner().as_inner().st_spare4; - [spare4[0] as u32, spare4[1] as u32] - } -} diff --git a/library/std/src/os/espidf/mod.rs b/library/std/src/os/espidf/mod.rs deleted file mode 100644 index a9cef97093082..0000000000000 --- a/library/std/src/os/espidf/mod.rs +++ /dev/null @@ -1,6 +0,0 @@ -//! Definitions for the ESP-IDF framework. - -#![stable(feature = "raw_ext", since = "1.1.0")] - -pub mod fs; -pub mod raw; diff --git a/library/std/src/os/espidf/raw.rs b/library/std/src/os/espidf/raw.rs deleted file mode 100644 index 7df0e74b22335..0000000000000 --- a/library/std/src/os/espidf/raw.rs +++ /dev/null @@ -1,69 +0,0 @@ -//! Raw type definitions for the ESP-IDF framework. - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![deprecated( - since = "1.8.0", - note = "these type aliases are no longer supported by \ - the standard library, the `libc` crate on \ - crates.io should be used instead for the correct \ - definitions" -)] - -use crate::os::raw::c_long; -use crate::os::unix::raw::{gid_t, uid_t}; - -#[stable(feature = "pthread_t", since = "1.8.0")] -pub type pthread_t = libc::pthread_t; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blkcnt_t = libc::blkcnt_t; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blksize_t = libc::blksize_t; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type dev_t = libc::dev_t; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type ino_t = libc::ino_t; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type mode_t = libc::mode_t; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type nlink_t = libc::nlink_t; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type off_t = libc::off_t; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type time_t = libc::time_t; - -#[repr(C)] -#[derive(Clone)] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: dev_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: ino_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: mode_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: nlink_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: uid_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: gid_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: dev_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: off_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: blksize_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: blkcnt_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_spare4: [c_long; 2usize], -} diff --git a/library/std/src/os/fd/mod.rs b/library/std/src/os/fd/mod.rs deleted file mode 100644 index 35de4860fe249..0000000000000 --- a/library/std/src/os/fd/mod.rs +++ /dev/null @@ -1,25 +0,0 @@ -//! Owned and borrowed Unix-like file descriptors. -//! -//! This module is supported on Unix platforms and WASI, which both use a -//! similar file descriptor system for referencing OS resources. - -#![stable(feature = "os_fd", since = "1.66.0")] -#![deny(unsafe_op_in_unsafe_fn)] - -// `RawFd`, `AsRawFd`, etc. -mod raw; - -// `OwnedFd`, `AsFd`, etc. -mod owned; - -// Implementations for `AsRawFd` etc. for network types. -mod net; - -#[cfg(test)] -mod tests; - -// Export the types and traits for the public API. -#[stable(feature = "os_fd", since = "1.66.0")] -pub use owned::*; -#[stable(feature = "os_fd", since = "1.66.0")] -pub use raw::*; diff --git a/library/std/src/os/fd/net.rs b/library/std/src/os/fd/net.rs deleted file mode 100644 index 843f45f7f5f98..0000000000000 --- a/library/std/src/os/fd/net.rs +++ /dev/null @@ -1,46 +0,0 @@ -use crate::os::fd::owned::OwnedFd; -use crate::os::fd::raw::{AsRawFd, FromRawFd, IntoRawFd, RawFd}; -use crate::sys_common::{self, AsInner, FromInner, IntoInner}; -use crate::{net, sys}; - -macro_rules! impl_as_raw_fd { - ($($t:ident)*) => {$( - #[stable(feature = "rust1", since = "1.0.0")] - impl AsRawFd for net::$t { - #[inline] - fn as_raw_fd(&self) -> RawFd { - self.as_inner().socket().as_raw_fd() - } - } - )*}; -} -impl_as_raw_fd! { TcpStream TcpListener UdpSocket } - -macro_rules! impl_from_raw_fd { - ($($t:ident)*) => {$( - #[stable(feature = "from_raw_os", since = "1.1.0")] - impl FromRawFd for net::$t { - #[inline] - unsafe fn from_raw_fd(fd: RawFd) -> net::$t { - unsafe { - let socket = sys::net::Socket::from_inner(FromInner::from_inner(OwnedFd::from_raw_fd(fd))); - net::$t::from_inner(sys_common::net::$t::from_inner(socket)) - } - } - } - )*}; -} -impl_from_raw_fd! { TcpStream TcpListener UdpSocket } - -macro_rules! impl_into_raw_fd { - ($($t:ident)*) => {$( - #[stable(feature = "into_raw_os", since = "1.4.0")] - impl IntoRawFd for net::$t { - #[inline] - fn into_raw_fd(self) -> RawFd { - self.into_inner().into_socket().into_inner().into_inner().into_raw_fd() - } - } - )*}; -} -impl_into_raw_fd! { TcpStream TcpListener UdpSocket } diff --git a/library/std/src/os/fd/owned.rs b/library/std/src/os/fd/owned.rs deleted file mode 100644 index 8c7fc4cb2e453..0000000000000 --- a/library/std/src/os/fd/owned.rs +++ /dev/null @@ -1,479 +0,0 @@ -//! Owned and borrowed Unix-like file descriptors. - -#![stable(feature = "io_safety", since = "1.63.0")] -#![deny(unsafe_op_in_unsafe_fn)] - -use super::raw::{AsRawFd, FromRawFd, IntoRawFd, RawFd}; -use crate::fmt; -use crate::fs; -use crate::io; -use crate::marker::PhantomData; -use crate::mem::forget; -#[cfg(not(any(target_arch = "wasm32", target_env = "sgx", target_os = "hermit")))] -use crate::sys::cvt; -use crate::sys_common::{AsInner, FromInner, IntoInner}; - -/// A borrowed file descriptor. -/// -/// This has a lifetime parameter to tie it to the lifetime of something that owns the file -/// descriptor. For the duration of that lifetime, it is guaranteed that nobody will close the file -/// descriptor. -/// -/// This uses `repr(transparent)` and has the representation of a host file -/// descriptor, so it can be used in FFI in places where a file descriptor is -/// passed as an argument, it is not captured or consumed, and it never has the -/// value `-1`. -/// -/// This type's `.to_owned()` implementation returns another `BorrowedFd` -/// rather than an `OwnedFd`. It just makes a trivial copy of the raw file -/// descriptor, which is then borrowed under the same lifetime. -#[derive(Copy, Clone)] -#[repr(transparent)] -#[rustc_layout_scalar_valid_range_start(0)] -// libstd/os/raw/mod.rs assures me that every libstd-supported platform has a -// 32-bit c_int. Below is -2, in two's complement, but that only works out -// because c_int is 32 bits. -#[rustc_layout_scalar_valid_range_end(0xFF_FF_FF_FE)] -#[rustc_nonnull_optimization_guaranteed] -#[stable(feature = "io_safety", since = "1.63.0")] -pub struct BorrowedFd<'fd> { - fd: RawFd, - _phantom: PhantomData<&'fd OwnedFd>, -} - -/// An owned file descriptor. -/// -/// This closes the file descriptor on drop. It is guaranteed that nobody else will close the file -/// descriptor. -/// -/// This uses `repr(transparent)` and has the representation of a host file -/// descriptor, so it can be used in FFI in places where a file descriptor is -/// passed as a consumed argument or returned as an owned value, and it never -/// has the value `-1`. -#[repr(transparent)] -#[rustc_layout_scalar_valid_range_start(0)] -// libstd/os/raw/mod.rs assures me that every libstd-supported platform has a -// 32-bit c_int. Below is -2, in two's complement, but that only works out -// because c_int is 32 bits. -#[rustc_layout_scalar_valid_range_end(0xFF_FF_FF_FE)] -#[rustc_nonnull_optimization_guaranteed] -#[stable(feature = "io_safety", since = "1.63.0")] -pub struct OwnedFd { - fd: RawFd, -} - -impl BorrowedFd<'_> { - /// Return a `BorrowedFd` holding the given raw file descriptor. - /// - /// # Safety - /// - /// The resource pointed to by `fd` must remain open for the duration of - /// the returned `BorrowedFd`, and it must not have the value `-1`. - #[inline] - #[rustc_const_stable(feature = "io_safety", since = "1.63.0")] - #[stable(feature = "io_safety", since = "1.63.0")] - pub const unsafe fn borrow_raw(fd: RawFd) -> Self { - assert!(fd != u32::MAX as RawFd); - // SAFETY: we just asserted that the value is in the valid range and isn't `-1` (the only value bigger than `0xFF_FF_FF_FE` unsigned) - unsafe { Self { fd, _phantom: PhantomData } } - } -} - -impl OwnedFd { - /// Creates a new `OwnedFd` instance that shares the same underlying file - /// description as the existing `OwnedFd` instance. - #[stable(feature = "io_safety", since = "1.63.0")] - pub fn try_clone(&self) -> crate::io::Result { - self.as_fd().try_clone_to_owned() - } -} - -impl BorrowedFd<'_> { - /// Creates a new `OwnedFd` instance that shares the same underlying file - /// description as the existing `BorrowedFd` instance. - #[cfg(not(any(target_arch = "wasm32", target_os = "hermit")))] - #[stable(feature = "io_safety", since = "1.63.0")] - pub fn try_clone_to_owned(&self) -> crate::io::Result { - // We want to atomically duplicate this file descriptor and set the - // CLOEXEC flag, and currently that's done via F_DUPFD_CLOEXEC. This - // is a POSIX flag that was added to Linux in 2.6.24. - #[cfg(not(any(target_os = "espidf", target_os = "vita")))] - let cmd = libc::F_DUPFD_CLOEXEC; - - // For ESP-IDF, F_DUPFD is used instead, because the CLOEXEC semantics - // will never be supported, as this is a bare metal framework with - // no capabilities for multi-process execution. While F_DUPFD is also - // not supported yet, it might be (currently it returns ENOSYS). - #[cfg(any(target_os = "espidf", target_os = "vita"))] - let cmd = libc::F_DUPFD; - - // Avoid using file descriptors below 3 as they are used for stdio - let fd = cvt(unsafe { libc::fcntl(self.as_raw_fd(), cmd, 3) })?; - Ok(unsafe { OwnedFd::from_raw_fd(fd) }) - } - - /// Creates a new `OwnedFd` instance that shares the same underlying file - /// description as the existing `BorrowedFd` instance. - #[cfg(any(target_arch = "wasm32", target_os = "hermit"))] - #[stable(feature = "io_safety", since = "1.63.0")] - pub fn try_clone_to_owned(&self) -> crate::io::Result { - Err(crate::io::Error::UNSUPPORTED_PLATFORM) - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsRawFd for BorrowedFd<'_> { - #[inline] - fn as_raw_fd(&self) -> RawFd { - self.fd - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsRawFd for OwnedFd { - #[inline] - fn as_raw_fd(&self) -> RawFd { - self.fd - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl IntoRawFd for OwnedFd { - #[inline] - fn into_raw_fd(self) -> RawFd { - let fd = self.fd; - forget(self); - fd - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl FromRawFd for OwnedFd { - /// Constructs a new instance of `Self` from the given raw file descriptor. - /// - /// # Safety - /// - /// The resource pointed to by `fd` must be open and suitable for assuming - /// [ownership][io-safety]. The resource must not require any cleanup other than `close`. - /// - /// [io-safety]: io#io-safety - #[inline] - unsafe fn from_raw_fd(fd: RawFd) -> Self { - assert_ne!(fd, u32::MAX as RawFd); - // SAFETY: we just asserted that the value is in the valid range and isn't `-1` (the only value bigger than `0xFF_FF_FF_FE` unsigned) - unsafe { Self { fd } } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl Drop for OwnedFd { - #[inline] - fn drop(&mut self) { - unsafe { - // Note that errors are ignored when closing a file descriptor. The - // reason for this is that if an error occurs we don't actually know if - // the file descriptor was closed or not, and if we retried (for - // something like EINTR), we might close another valid file descriptor - // opened after we closed ours. - #[cfg(not(target_os = "hermit"))] - { - #[cfg(unix)] - crate::sys::fs::debug_assert_fd_is_open(self.fd); - - let _ = libc::close(self.fd); - } - #[cfg(target_os = "hermit")] - let _ = hermit_abi::close(self.fd); - } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl fmt::Debug for BorrowedFd<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("BorrowedFd").field("fd", &self.fd).finish() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl fmt::Debug for OwnedFd { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("OwnedFd").field("fd", &self.fd).finish() - } -} - -macro_rules! impl_is_terminal { - ($($t:ty),*$(,)?) => {$( - #[unstable(feature = "sealed", issue = "none")] - impl crate::sealed::Sealed for $t {} - - #[stable(feature = "is_terminal", since = "1.70.0")] - impl crate::io::IsTerminal for $t { - #[inline] - fn is_terminal(&self) -> bool { - crate::sys::io::is_terminal(self) - } - } - )*} -} - -impl_is_terminal!(BorrowedFd<'_>, OwnedFd); - -/// A trait to borrow the file descriptor from an underlying object. -/// -/// This is only available on unix platforms and must be imported in order to -/// call the method. Windows platforms have a corresponding `AsHandle` and -/// `AsSocket` set of traits. -#[stable(feature = "io_safety", since = "1.63.0")] -pub trait AsFd { - /// Borrows the file descriptor. - /// - /// # Example - /// - /// ```rust,no_run - /// use std::fs::File; - /// # use std::io; - /// # #[cfg(any(unix, target_os = "wasi"))] - /// # use std::os::fd::{AsFd, BorrowedFd}; - /// - /// let mut f = File::open("foo.txt")?; - /// # #[cfg(any(unix, target_os = "wasi"))] - /// let borrowed_fd: BorrowedFd<'_> = f.as_fd(); - /// # Ok::<(), io::Error>(()) - /// ``` - #[stable(feature = "io_safety", since = "1.63.0")] - fn as_fd(&self) -> BorrowedFd<'_>; -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsFd for &T { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - T::as_fd(self) - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsFd for &mut T { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - T::as_fd(self) - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsFd for BorrowedFd<'_> { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - *self - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsFd for OwnedFd { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - // Safety: `OwnedFd` and `BorrowedFd` have the same validity - // invariants, and the `BorrowedFd` is bounded by the lifetime - // of `&self`. - unsafe { BorrowedFd::borrow_raw(self.as_raw_fd()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsFd for fs::File { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - self.as_inner().as_fd() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for OwnedFd { - /// Takes ownership of a [`File`](fs::File)'s underlying file descriptor. - #[inline] - fn from(file: fs::File) -> OwnedFd { - file.into_inner().into_inner().into_inner() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for fs::File { - /// Returns a [`File`](fs::File) that takes ownership of the given - /// file descriptor. - #[inline] - fn from(owned_fd: OwnedFd) -> Self { - Self::from_inner(FromInner::from_inner(FromInner::from_inner(owned_fd))) - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsFd for crate::net::TcpStream { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - self.as_inner().socket().as_fd() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for OwnedFd { - /// Takes ownership of a [`TcpStream`](crate::net::TcpStream)'s socket file descriptor. - #[inline] - fn from(tcp_stream: crate::net::TcpStream) -> OwnedFd { - tcp_stream.into_inner().into_socket().into_inner().into_inner().into() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for crate::net::TcpStream { - #[inline] - fn from(owned_fd: OwnedFd) -> Self { - Self::from_inner(FromInner::from_inner(FromInner::from_inner(FromInner::from_inner( - owned_fd, - )))) - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsFd for crate::net::TcpListener { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - self.as_inner().socket().as_fd() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for OwnedFd { - /// Takes ownership of a [`TcpListener`](crate::net::TcpListener)'s socket file descriptor. - #[inline] - fn from(tcp_listener: crate::net::TcpListener) -> OwnedFd { - tcp_listener.into_inner().into_socket().into_inner().into_inner().into() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for crate::net::TcpListener { - #[inline] - fn from(owned_fd: OwnedFd) -> Self { - Self::from_inner(FromInner::from_inner(FromInner::from_inner(FromInner::from_inner( - owned_fd, - )))) - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsFd for crate::net::UdpSocket { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - self.as_inner().socket().as_fd() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for OwnedFd { - /// Takes ownership of a [`UdpSocket`](crate::net::UdpSocket)'s file descriptor. - #[inline] - fn from(udp_socket: crate::net::UdpSocket) -> OwnedFd { - udp_socket.into_inner().into_socket().into_inner().into_inner().into() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for crate::net::UdpSocket { - #[inline] - fn from(owned_fd: OwnedFd) -> Self { - Self::from_inner(FromInner::from_inner(FromInner::from_inner(FromInner::from_inner( - owned_fd, - )))) - } -} - -#[stable(feature = "asfd_ptrs", since = "1.64.0")] -/// This impl allows implementing traits that require `AsFd` on Arc. -/// ``` -/// # #[cfg(any(unix, target_os = "wasi"))] mod group_cfg { -/// # #[cfg(target_os = "wasi")] -/// # use std::os::wasi::io::AsFd; -/// # #[cfg(unix)] -/// # use std::os::unix::io::AsFd; -/// use std::net::UdpSocket; -/// use std::sync::Arc; -/// -/// trait MyTrait: AsFd {} -/// impl MyTrait for Arc {} -/// impl MyTrait for Box {} -/// # } -/// ``` -impl AsFd for crate::sync::Arc { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - (**self).as_fd() - } -} - -#[stable(feature = "asfd_rc", since = "1.69.0")] -impl AsFd for crate::rc::Rc { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - (**self).as_fd() - } -} - -#[stable(feature = "asfd_ptrs", since = "1.64.0")] -impl AsFd for Box { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - (**self).as_fd() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsFd for io::Stdin { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - unsafe { BorrowedFd::borrow_raw(0) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl<'a> AsFd for io::StdinLock<'a> { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - // SAFETY: user code should not close stdin out from under the standard library - unsafe { BorrowedFd::borrow_raw(0) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsFd for io::Stdout { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - unsafe { BorrowedFd::borrow_raw(1) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl<'a> AsFd for io::StdoutLock<'a> { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - // SAFETY: user code should not close stdout out from under the standard library - unsafe { BorrowedFd::borrow_raw(1) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsFd for io::Stderr { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - unsafe { BorrowedFd::borrow_raw(2) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl<'a> AsFd for io::StderrLock<'a> { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - // SAFETY: user code should not close stderr out from under the standard library - unsafe { BorrowedFd::borrow_raw(2) } - } -} diff --git a/library/std/src/os/fd/raw.rs b/library/std/src/os/fd/raw.rs deleted file mode 100644 index ef896ea95c9c9..0000000000000 --- a/library/std/src/os/fd/raw.rs +++ /dev/null @@ -1,274 +0,0 @@ -//! Raw Unix-like file descriptors. - -#![stable(feature = "rust1", since = "1.0.0")] - -use crate::fs; -use crate::io; -#[cfg(target_os = "hermit")] -use crate::os::hermit::io::OwnedFd; -#[cfg(not(target_os = "hermit"))] -use crate::os::raw; -#[cfg(all(doc, not(target_arch = "wasm32")))] -use crate::os::unix::io::AsFd; -#[cfg(unix)] -use crate::os::unix::io::OwnedFd; -#[cfg(target_os = "wasi")] -use crate::os::wasi::io::OwnedFd; -use crate::sys_common::{AsInner, IntoInner}; -#[cfg(target_os = "hermit")] -use hermit_abi as libc; - -/// Raw file descriptors. -#[rustc_allowed_through_unstable_modules] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg(not(target_os = "hermit"))] -pub type RawFd = raw::c_int; -#[rustc_allowed_through_unstable_modules] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg(target_os = "hermit")] -pub type RawFd = i32; - -/// A trait to extract the raw file descriptor from an underlying object. -/// -/// This is only available on unix and WASI platforms and must be imported in -/// order to call the method. Windows platforms have a corresponding -/// `AsRawHandle` and `AsRawSocket` set of traits. -#[rustc_allowed_through_unstable_modules] -#[stable(feature = "rust1", since = "1.0.0")] -pub trait AsRawFd { - /// Extracts the raw file descriptor. - /// - /// This function is typically used to **borrow** an owned file descriptor. - /// When used in this way, this method does **not** pass ownership of the - /// raw file descriptor to the caller, and the file descriptor is only - /// guaranteed to be valid while the original object has not yet been - /// destroyed. - /// - /// However, borrowing is not strictly required. See [`AsFd::as_fd`] - /// for an API which strictly borrows a file descriptor. - /// - /// # Example - /// - /// ```no_run - /// use std::fs::File; - /// # use std::io; - /// #[cfg(any(unix, target_os = "wasi"))] - /// use std::os::fd::{AsRawFd, RawFd}; - /// - /// let mut f = File::open("foo.txt")?; - /// // Note that `raw_fd` is only valid as long as `f` exists. - /// #[cfg(any(unix, target_os = "wasi"))] - /// let raw_fd: RawFd = f.as_raw_fd(); - /// # Ok::<(), io::Error>(()) - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn as_raw_fd(&self) -> RawFd; -} - -/// A trait to express the ability to construct an object from a raw file -/// descriptor. -#[rustc_allowed_through_unstable_modules] -#[stable(feature = "from_raw_os", since = "1.1.0")] -pub trait FromRawFd { - /// Constructs a new instance of `Self` from the given raw file - /// descriptor. - /// - /// This function is typically used to **consume ownership** of the - /// specified file descriptor. When used in this way, the returned object - /// will take responsibility for closing it when the object goes out of - /// scope. - /// - /// However, consuming ownership is not strictly required. Use a - /// [`From::from`] implementation for an API which strictly - /// consumes ownership. - /// - /// # Safety - /// - /// The `fd` passed in must be an [owned file descriptor][io-safety]; - /// in particular, it must be open. - /// - /// [io-safety]: io#io-safety - /// - /// # Example - /// - /// ```no_run - /// use std::fs::File; - /// # use std::io; - /// #[cfg(any(unix, target_os = "wasi"))] - /// use std::os::fd::{FromRawFd, IntoRawFd, RawFd}; - /// - /// let f = File::open("foo.txt")?; - /// # #[cfg(any(unix, target_os = "wasi"))] - /// let raw_fd: RawFd = f.into_raw_fd(); - /// // SAFETY: no other functions should call `from_raw_fd`, so there - /// // is only one owner for the file descriptor. - /// # #[cfg(any(unix, target_os = "wasi"))] - /// let f = unsafe { File::from_raw_fd(raw_fd) }; - /// # Ok::<(), io::Error>(()) - /// ``` - #[stable(feature = "from_raw_os", since = "1.1.0")] - unsafe fn from_raw_fd(fd: RawFd) -> Self; -} - -/// A trait to express the ability to consume an object and acquire ownership of -/// its raw file descriptor. -#[rustc_allowed_through_unstable_modules] -#[stable(feature = "into_raw_os", since = "1.4.0")] -pub trait IntoRawFd { - /// Consumes this object, returning the raw underlying file descriptor. - /// - /// This function is typically used to **transfer ownership** of the underlying - /// file descriptor to the caller. When used in this way, callers are then the unique - /// owners of the file descriptor and must close it once it's no longer needed. - /// - /// However, transferring ownership is not strictly required. Use a - /// [`Into::into`] implementation for an API which strictly - /// transfers ownership. - /// - /// # Example - /// - /// ```no_run - /// use std::fs::File; - /// # use std::io; - /// #[cfg(any(unix, target_os = "wasi"))] - /// use std::os::fd::{IntoRawFd, RawFd}; - /// - /// let f = File::open("foo.txt")?; - /// #[cfg(any(unix, target_os = "wasi"))] - /// let raw_fd: RawFd = f.into_raw_fd(); - /// # Ok::<(), io::Error>(()) - /// ``` - #[stable(feature = "into_raw_os", since = "1.4.0")] - fn into_raw_fd(self) -> RawFd; -} - -#[stable(feature = "raw_fd_reflexive_traits", since = "1.48.0")] -impl AsRawFd for RawFd { - #[inline] - fn as_raw_fd(&self) -> RawFd { - *self - } -} -#[stable(feature = "raw_fd_reflexive_traits", since = "1.48.0")] -impl IntoRawFd for RawFd { - #[inline] - fn into_raw_fd(self) -> RawFd { - self - } -} -#[stable(feature = "raw_fd_reflexive_traits", since = "1.48.0")] -impl FromRawFd for RawFd { - #[inline] - unsafe fn from_raw_fd(fd: RawFd) -> RawFd { - fd - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRawFd for fs::File { - #[inline] - fn as_raw_fd(&self) -> RawFd { - self.as_inner().as_raw_fd() - } -} -#[stable(feature = "from_raw_os", since = "1.1.0")] -impl FromRawFd for fs::File { - #[inline] - unsafe fn from_raw_fd(fd: RawFd) -> fs::File { - unsafe { fs::File::from(OwnedFd::from_raw_fd(fd)) } - } -} -#[stable(feature = "into_raw_os", since = "1.4.0")] -impl IntoRawFd for fs::File { - #[inline] - fn into_raw_fd(self) -> RawFd { - self.into_inner().into_inner().into_raw_fd() - } -} - -#[stable(feature = "asraw_stdio", since = "1.21.0")] -impl AsRawFd for io::Stdin { - #[inline] - fn as_raw_fd(&self) -> RawFd { - libc::STDIN_FILENO - } -} - -#[stable(feature = "asraw_stdio", since = "1.21.0")] -impl AsRawFd for io::Stdout { - #[inline] - fn as_raw_fd(&self) -> RawFd { - libc::STDOUT_FILENO - } -} - -#[stable(feature = "asraw_stdio", since = "1.21.0")] -impl AsRawFd for io::Stderr { - #[inline] - fn as_raw_fd(&self) -> RawFd { - libc::STDERR_FILENO - } -} - -#[stable(feature = "asraw_stdio_locks", since = "1.35.0")] -impl<'a> AsRawFd for io::StdinLock<'a> { - #[inline] - fn as_raw_fd(&self) -> RawFd { - libc::STDIN_FILENO - } -} - -#[stable(feature = "asraw_stdio_locks", since = "1.35.0")] -impl<'a> AsRawFd for io::StdoutLock<'a> { - #[inline] - fn as_raw_fd(&self) -> RawFd { - libc::STDOUT_FILENO - } -} - -#[stable(feature = "asraw_stdio_locks", since = "1.35.0")] -impl<'a> AsRawFd for io::StderrLock<'a> { - #[inline] - fn as_raw_fd(&self) -> RawFd { - libc::STDERR_FILENO - } -} - -/// This impl allows implementing traits that require `AsRawFd` on Arc. -/// ``` -/// # #[cfg(any(unix, target_os = "wasi"))] mod group_cfg { -/// # #[cfg(target_os = "wasi")] -/// # use std::os::wasi::io::AsRawFd; -/// # #[cfg(unix)] -/// # use std::os::unix::io::AsRawFd; -/// use std::net::UdpSocket; -/// use std::sync::Arc; -/// trait MyTrait: AsRawFd { -/// } -/// impl MyTrait for Arc {} -/// impl MyTrait for Box {} -/// # } -/// ``` -#[stable(feature = "asrawfd_ptrs", since = "1.63.0")] -impl AsRawFd for crate::sync::Arc { - #[inline] - fn as_raw_fd(&self) -> RawFd { - (**self).as_raw_fd() - } -} - -#[stable(feature = "asfd_rc", since = "1.69.0")] -impl AsRawFd for crate::rc::Rc { - #[inline] - fn as_raw_fd(&self) -> RawFd { - (**self).as_raw_fd() - } -} - -#[stable(feature = "asrawfd_ptrs", since = "1.63.0")] -impl AsRawFd for Box { - #[inline] - fn as_raw_fd(&self) -> RawFd { - (**self).as_raw_fd() - } -} diff --git a/library/std/src/os/fd/tests.rs b/library/std/src/os/fd/tests.rs deleted file mode 100644 index b39863644f116..0000000000000 --- a/library/std/src/os/fd/tests.rs +++ /dev/null @@ -1,53 +0,0 @@ -#[cfg(any(unix, target_os = "wasi"))] -#[test] -fn test_raw_fd() { - #[cfg(unix)] - use crate::os::unix::io::{AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, RawFd}; - #[cfg(target_os = "wasi")] - use crate::os::wasi::io::{AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, RawFd}; - - let raw_fd: RawFd = crate::io::stdin().as_raw_fd(); - - let stdin_as_file = unsafe { crate::fs::File::from_raw_fd(raw_fd) }; - assert_eq!(stdin_as_file.as_raw_fd(), raw_fd); - assert_eq!(unsafe { BorrowedFd::borrow_raw(raw_fd).as_raw_fd() }, raw_fd); - assert_eq!(stdin_as_file.into_raw_fd(), 0); -} - -#[cfg(any(unix, target_os = "wasi"))] -#[test] -fn test_fd() { - #[cfg(unix)] - use crate::os::unix::io::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd}; - #[cfg(target_os = "wasi")] - use crate::os::wasi::io::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd}; - - let stdin = crate::io::stdin(); - let fd: BorrowedFd<'_> = stdin.as_fd(); - let raw_fd: RawFd = fd.as_raw_fd(); - let owned_fd: OwnedFd = unsafe { OwnedFd::from_raw_fd(raw_fd) }; - - let stdin_as_file = crate::fs::File::from(owned_fd); - - assert_eq!(stdin_as_file.as_fd().as_raw_fd(), raw_fd); - assert_eq!(Into::::into(stdin_as_file).into_raw_fd(), raw_fd); -} - -#[cfg(any(unix, target_os = "wasi"))] -#[test] -fn test_niche_optimizations() { - use crate::mem::size_of; - #[cfg(unix)] - use crate::os::unix::io::{BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd}; - #[cfg(target_os = "wasi")] - use crate::os::wasi::io::{BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd}; - - assert_eq!(size_of::>(), size_of::()); - assert_eq!(size_of::>>(), size_of::()); - unsafe { - assert_eq!(OwnedFd::from_raw_fd(RawFd::MIN).into_raw_fd(), RawFd::MIN); - assert_eq!(OwnedFd::from_raw_fd(RawFd::MAX).into_raw_fd(), RawFd::MAX); - assert_eq!(Some(OwnedFd::from_raw_fd(RawFd::MIN)).unwrap().into_raw_fd(), RawFd::MIN); - assert_eq!(Some(OwnedFd::from_raw_fd(RawFd::MAX)).unwrap().into_raw_fd(), RawFd::MAX); - } -} diff --git a/library/std/src/os/fortanix_sgx/arch.rs b/library/std/src/os/fortanix_sgx/arch.rs deleted file mode 100644 index 8358cb9e81b65..0000000000000 --- a/library/std/src/os/fortanix_sgx/arch.rs +++ /dev/null @@ -1,80 +0,0 @@ -//! SGX-specific access to architectural features. -//! -//! The functionality in this module is further documented in the Intel -//! Software Developer's Manual, Volume 3, Chapter 40. -#![unstable(feature = "sgx_platform", issue = "56975")] - -use crate::mem::MaybeUninit; -use core::arch::asm; - -/// Wrapper struct to force 16-byte alignment. -#[repr(align(16))] -#[unstable(feature = "sgx_platform", issue = "56975")] -pub struct Align16(pub T); - -/// Wrapper struct to force 128-byte alignment. -#[repr(align(128))] -#[unstable(feature = "sgx_platform", issue = "56975")] -pub struct Align128(pub T); - -/// Wrapper struct to force 512-byte alignment. -#[repr(align(512))] -#[unstable(feature = "sgx_platform", issue = "56975")] -pub struct Align512(pub T); - -const ENCLU_EREPORT: u32 = 0; -const ENCLU_EGETKEY: u32 = 1; - -/// Call the `EGETKEY` instruction to obtain a 128-bit secret key. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub fn egetkey(request: &Align512<[u8; 512]>) -> Result, u32> { - unsafe { - let mut out = MaybeUninit::uninit(); - let error; - - asm!( - // rbx is reserved by LLVM - "xchg %rbx, {0}", - "enclu", - "mov {0}, %rbx", - inout(reg) request => _, - inlateout("eax") ENCLU_EGETKEY => error, - in("rcx") out.as_mut_ptr(), - options(att_syntax, nostack), - ); - - match error { - 0 => Ok(out.assume_init()), - err => Err(err), - } - } -} - -/// Call the `EREPORT` instruction. -/// -/// This creates a cryptographic report describing the contents of the current -/// enclave. The report may be verified by the enclave described in -/// `targetinfo`. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub fn ereport( - targetinfo: &Align512<[u8; 512]>, - reportdata: &Align128<[u8; 64]>, -) -> Align512<[u8; 432]> { - unsafe { - let mut report = MaybeUninit::uninit(); - - asm!( - // rbx is reserved by LLVM - "xchg %rbx, {0}", - "enclu", - "mov {0}, %rbx", - inout(reg) targetinfo => _, - in("eax") ENCLU_EREPORT, - in("rcx") reportdata, - in("rdx") report.as_mut_ptr(), - options(att_syntax, preserves_flags, nostack), - ); - - report.assume_init() - } -} diff --git a/library/std/src/os/fortanix_sgx/ffi.rs b/library/std/src/os/fortanix_sgx/ffi.rs deleted file mode 100644 index ac1db0e5e39cc..0000000000000 --- a/library/std/src/os/fortanix_sgx/ffi.rs +++ /dev/null @@ -1,41 +0,0 @@ -//! SGX-specific extension to the primitives in the `std::ffi` module -//! -//! # Examples -//! -//! ``` -//! use std::ffi::OsString; -//! use std::os::fortanix_sgx::ffi::OsStringExt; -//! -//! let bytes = b"foo".to_vec(); -//! -//! // OsStringExt::from_vec -//! let os_string = OsString::from_vec(bytes); -//! assert_eq!(os_string.to_str(), Some("foo")); -//! -//! // OsStringExt::into_vec -//! let bytes = os_string.into_vec(); -//! assert_eq!(bytes, b"foo"); -//! ``` -//! -//! ``` -//! use std::ffi::OsStr; -//! use std::os::fortanix_sgx::ffi::OsStrExt; -//! -//! let bytes = b"foo"; -//! -//! // OsStrExt::from_bytes -//! let os_str = OsStr::from_bytes(bytes); -//! assert_eq!(os_str.to_str(), Some("foo")); -//! -//! // OsStrExt::as_bytes -//! let bytes = os_str.as_bytes(); -//! assert_eq!(bytes, b"foo"); -//! ``` - -#![unstable(feature = "sgx_platform", issue = "56975")] - -#[path = "../unix/ffi/os_str.rs"] -mod os_str; - -#[unstable(feature = "sgx_platform", issue = "56975")] -pub use self::os_str::{OsStrExt, OsStringExt}; diff --git a/library/std/src/os/fortanix_sgx/io.rs b/library/std/src/os/fortanix_sgx/io.rs deleted file mode 100644 index 7e57435b65ccd..0000000000000 --- a/library/std/src/os/fortanix_sgx/io.rs +++ /dev/null @@ -1,151 +0,0 @@ -//! SGX-specific extensions to general I/O primitives -//! -//! SGX file descriptors behave differently from Unix file descriptors. See the -//! description of [`TryIntoRawFd`] for more details. -#![unstable(feature = "sgx_platform", issue = "56975")] - -use crate::net; -pub use crate::sys::abi::usercalls::raw::Fd as RawFd; -use crate::sys::{self, AsInner, FromInner, IntoInner, TryIntoInner}; - -/// A trait to extract the raw SGX file descriptor from an underlying -/// object. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub trait AsRawFd { - /// Extracts the raw file descriptor. - /// - /// This method does **not** pass ownership of the raw file descriptor - /// to the caller. The descriptor is only guaranteed to be valid while - /// the original object has not yet been destroyed. - #[unstable(feature = "sgx_platform", issue = "56975")] - fn as_raw_fd(&self) -> RawFd; -} - -/// A trait to express the ability to construct an object from a raw file -/// descriptor. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub trait FromRawFd { - /// An associated type that contains relevant metadata for `Self`. - type Metadata: Default; - - /// Constructs a new instance of `Self` from the given raw file - /// descriptor and metadata. - /// - /// This function is typically used to **consume ownership** of the - /// specified file descriptor. When used in this way, the returned object - /// will take responsibility for closing it when the object goes out of - /// scope. - /// - /// However, consuming ownership is not strictly required. Use a - /// [`From::from`] implementation for an API which strictly - /// consumes ownership. - /// - /// # Safety - /// - /// The `fd` passed in must be an [owned file descriptor][io-safety]; - /// in particular, it must be open. - // FIXME: say something about `metadata`. - /// - /// [io-safety]: io#io-safety - #[unstable(feature = "sgx_platform", issue = "56975")] - unsafe fn from_raw_fd(fd: RawFd, metadata: Self::Metadata) -> Self; -} - -/// A trait to express the ability to consume an object and acquire ownership of -/// its raw file descriptor. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub trait TryIntoRawFd: Sized { - /// Consumes this object, returning the raw underlying file descriptor, if - /// this object is not cloned. - /// - /// This function **transfers ownership** of the underlying file descriptor - /// to the caller. Callers are then the unique owners of the file descriptor - /// and must close the descriptor once it's no longer needed. - /// - /// Unlike other platforms, on SGX, the file descriptor is shared between - /// all clones of an object. To avoid race conditions, this function will - /// only return `Ok` when called on the final clone. - #[unstable(feature = "sgx_platform", issue = "56975")] - fn try_into_raw_fd(self) -> Result; -} - -impl AsRawFd for net::TcpStream { - #[inline] - fn as_raw_fd(&self) -> RawFd { - *self.as_inner().as_inner().as_inner().as_inner() - } -} - -impl AsRawFd for net::TcpListener { - #[inline] - fn as_raw_fd(&self) -> RawFd { - *self.as_inner().as_inner().as_inner().as_inner() - } -} - -/// Metadata for `TcpStream`. -#[derive(Debug, Clone, Default)] -#[unstable(feature = "sgx_platform", issue = "56975")] -pub struct TcpStreamMetadata { - /// Local address of the TCP stream - pub local_addr: Option, - /// Peer address of the TCP stream - pub peer_addr: Option, -} - -impl FromRawFd for net::TcpStream { - type Metadata = TcpStreamMetadata; - - #[inline] - unsafe fn from_raw_fd(fd: RawFd, metadata: Self::Metadata) -> net::TcpStream { - let fd = sys::fd::FileDesc::from_inner(fd); - let socket = sys::net::Socket::from_inner((fd, metadata.local_addr)); - net::TcpStream::from_inner(sys::net::TcpStream::from_inner((socket, metadata.peer_addr))) - } -} - -/// Metadata for `TcpListener`. -#[derive(Debug, Clone, Default)] -#[unstable(feature = "sgx_platform", issue = "56975")] -pub struct TcpListenerMetadata { - /// Local address of the TCP listener - pub local_addr: Option, -} - -impl FromRawFd for net::TcpListener { - type Metadata = TcpListenerMetadata; - - #[inline] - unsafe fn from_raw_fd(fd: RawFd, metadata: Self::Metadata) -> net::TcpListener { - let fd = sys::fd::FileDesc::from_inner(fd); - let socket = sys::net::Socket::from_inner((fd, metadata.local_addr)); - net::TcpListener::from_inner(sys::net::TcpListener::from_inner(socket)) - } -} - -impl TryIntoRawFd for net::TcpStream { - #[inline] - fn try_into_raw_fd(self) -> Result { - let (socket, peer_addr) = self.into_inner().into_inner(); - match socket.try_into_inner() { - Ok(fd) => Ok(fd.into_inner()), - Err(socket) => { - let sys = sys::net::TcpStream::from_inner((socket, peer_addr)); - Err(net::TcpStream::from_inner(sys)) - } - } - } -} - -impl TryIntoRawFd for net::TcpListener { - #[inline] - fn try_into_raw_fd(self) -> Result { - match self.into_inner().into_inner().try_into_inner() { - Ok(fd) => Ok(fd.into_inner()), - Err(socket) => { - let sys = sys::net::TcpListener::from_inner(socket); - Err(net::TcpListener::from_inner(sys)) - } - } - } -} diff --git a/library/std/src/os/fortanix_sgx/mod.rs b/library/std/src/os/fortanix_sgx/mod.rs deleted file mode 100644 index 39a42f4e17fec..0000000000000 --- a/library/std/src/os/fortanix_sgx/mod.rs +++ /dev/null @@ -1,56 +0,0 @@ -//! Functionality specific to the `x86_64-fortanix-unknown-sgx` target. -//! -//! This includes functions to deal with memory isolation, usercalls, and the -//! SGX instruction set. - -#![deny(missing_docs)] -#![unstable(feature = "sgx_platform", issue = "56975")] - -/// Low-level interfaces to usercalls. See the [ABI documentation] for more -/// information. -/// -/// [ABI documentation]: https://docs.rs/fortanix-sgx-abi/ -pub mod usercalls { - pub use crate::sys::abi::usercalls::*; - - /// Primitives for allocating memory in userspace as well as copying data - /// to and from user memory. - pub mod alloc { - pub use crate::sys::abi::usercalls::alloc::*; - } - - /// Lowest-level interfaces to usercalls and usercall ABI type definitions. - pub mod raw { - pub use crate::sys::abi::usercalls::raw::{ - accept_stream, alloc, async_queues, bind_stream, close, connect_stream, exit, flush, - free, insecure_time, launch_thread, read, read_alloc, send, wait, write, - }; - pub use crate::sys::abi::usercalls::raw::{do_usercall, Usercalls as UsercallNrs}; - pub use crate::sys::abi::usercalls::raw::{Register, RegisterArgument, ReturnValue}; - - // fortanix-sgx-abi re-exports - pub use crate::sys::abi::usercalls::raw::Error; - pub use crate::sys::abi::usercalls::raw::{ - ByteBuffer, Cancel, FifoDescriptor, Return, Usercall, - }; - pub use crate::sys::abi::usercalls::raw::{Fd, Result, Tcs}; - pub use crate::sys::abi::usercalls::raw::{ - EV_RETURNQ_NOT_EMPTY, EV_UNPARK, EV_USERCALLQ_NOT_FULL, FD_STDERR, FD_STDIN, FD_STDOUT, - RESULT_SUCCESS, USERCALL_USER_DEFINED, WAIT_INDEFINITE, WAIT_NO, - }; - } -} - -/// Functions for querying mapping information for pointers. -pub mod mem { - pub use crate::sys::abi::mem::*; -} - -pub mod arch; -pub mod ffi; -pub mod io; - -/// Functions for querying thread-related information. -pub mod thread { - pub use crate::sys::abi::thread::current; -} diff --git a/library/std/src/os/freebsd/fs.rs b/library/std/src/os/freebsd/fs.rs deleted file mode 100644 index 5689a82e00a34..0000000000000 --- a/library/std/src/os/freebsd/fs.rs +++ /dev/null @@ -1,144 +0,0 @@ -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::Metadata; -use crate::sys_common::AsInner; - -#[allow(deprecated)] -use crate::os::freebsd::raw; - -/// OS-specific extensions to [`fs::Metadata`]. -/// -/// [`fs::Metadata`]: crate::fs::Metadata -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - /// Gain a reference to the underlying `stat` structure which contains - /// the raw information returned by the OS. - /// - /// The contents of the returned `stat` are **not** consistent across - /// Unix platforms. The `os::unix::fs::MetadataExt` trait contains the - /// cross-Unix abstractions contained within the raw stat. - #[stable(feature = "metadata_ext", since = "1.1.0")] - #[deprecated( - since = "1.8.0", - note = "deprecated in favor of the accessor \ - methods of this trait" - )] - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat; - - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_birthtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_birthtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_flags(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gen(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_lspare(&self) -> u32; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat { - // The methods below use libc::stat, so they work fine when libc is built with FreeBSD 12 ABI. - // This method would just return nonsense. - panic!("as_raw_stat not supported with FreeBSD 12 ABI"); - } - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_dev as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - self.as_inner().as_inner().st_atime as i64 - } - fn st_atime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_atime_nsec as i64 - } - fn st_mtime(&self) -> i64 { - self.as_inner().as_inner().st_mtime as i64 - } - fn st_mtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_mtime_nsec as i64 - } - fn st_ctime(&self) -> i64 { - self.as_inner().as_inner().st_ctime as i64 - } - fn st_ctime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_ctime_nsec as i64 - } - fn st_birthtime(&self) -> i64 { - self.as_inner().as_inner().st_birthtime as i64 - } - fn st_birthtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_birthtime_nsec as i64 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } - fn st_gen(&self) -> u32 { - self.as_inner().as_inner().st_gen as u32 - } - fn st_flags(&self) -> u32 { - self.as_inner().as_inner().st_flags as u32 - } - fn st_lspare(&self) -> u32 { - panic!("st_lspare not supported with FreeBSD 12 ABI"); - } -} diff --git a/library/std/src/os/freebsd/mod.rs b/library/std/src/os/freebsd/mod.rs deleted file mode 100644 index 39912e6970d45..0000000000000 --- a/library/std/src/os/freebsd/mod.rs +++ /dev/null @@ -1,7 +0,0 @@ -//! FreeBSD-specific definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] - -pub mod fs; -pub mod net; -pub mod raw; diff --git a/library/std/src/os/freebsd/net.rs b/library/std/src/os/freebsd/net.rs deleted file mode 100644 index b7e0fdc0a9aab..0000000000000 --- a/library/std/src/os/freebsd/net.rs +++ /dev/null @@ -1,91 +0,0 @@ -//! FreeBSD-specific networking functionality. - -#![unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - -use crate::ffi::CStr; -use crate::io; -use crate::os::unix::net; -use crate::sealed::Sealed; -use crate::sys_common::AsInner; - -/// FreeBSD-specific functionality for `AF_UNIX` sockets [`UnixDatagram`] -/// and [`UnixStream`]. -/// -/// [`UnixDatagram`]: net::UnixDatagram -/// [`UnixStream`]: net::UnixStream -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -pub trait UnixSocketExt: Sealed { - /// Query the current setting of socket option `LOCAL_CREDS_PERSISTENT`. - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - fn local_creds_persistent(&self) -> io::Result; - - /// Enable or disable socket option `LOCAL_CREDS_PERSISTENT`. - /// - /// This option enables the credentials of the sending process to be - /// received as a control message in [`AncillaryData`]. - /// - /// [`AncillaryData`]: net::AncillaryData - /// - /// # Examples - /// - /// ```no_run - /// #![feature(unix_socket_ancillary_data)] - /// use std::os::freebsd::net::UnixSocketExt; - /// use std::os::unix::net::UnixDatagram; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixDatagram::unbound()?; - /// sock.set_local_creds_persistent(true).expect("set_local_creds_persistent failed"); - /// Ok(()) - /// } - /// ``` - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - fn set_local_creds_persistent(&self, local_creds_persistent: bool) -> io::Result<()>; - - /// Get a filter name if one had been set previously on the socket. - #[unstable(feature = "acceptfilter", issue = "121891")] - fn acceptfilter(&self) -> io::Result<&CStr>; - - /// Set or disable a filter on the socket to filter incoming connections - /// to defer it before accept(2) - #[unstable(feature = "acceptfilter", issue = "121891")] - fn set_acceptfilter(&self, name: &CStr) -> io::Result<()>; -} - -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -impl UnixSocketExt for net::UnixDatagram { - fn local_creds_persistent(&self) -> io::Result { - self.as_inner().local_creds_persistent() - } - - fn set_local_creds_persistent(&self, local_creds_persistent: bool) -> io::Result<()> { - self.as_inner().set_local_creds_persistent(local_creds_persistent) - } - - fn acceptfilter(&self) -> io::Result<&CStr> { - self.as_inner().acceptfilter() - } - - fn set_acceptfilter(&self, name: &CStr) -> io::Result<()> { - self.as_inner().set_acceptfilter(name) - } -} - -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -impl UnixSocketExt for net::UnixStream { - fn local_creds_persistent(&self) -> io::Result { - self.as_inner().local_creds_persistent() - } - - fn set_local_creds_persistent(&self, local_creds_persistent: bool) -> io::Result<()> { - self.as_inner().set_local_creds_persistent(local_creds_persistent) - } - - fn acceptfilter(&self) -> io::Result<&CStr> { - self.as_inner().acceptfilter() - } - - fn set_acceptfilter(&self, name: &CStr) -> io::Result<()> { - self.as_inner().set_acceptfilter(name) - } -} diff --git a/library/std/src/os/freebsd/raw.rs b/library/std/src/os/freebsd/raw.rs deleted file mode 100644 index ab0bf79231948..0000000000000 --- a/library/std/src/os/freebsd/raw.rs +++ /dev/null @@ -1,86 +0,0 @@ -//! FreeBSD-specific raw type definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![deprecated( - since = "1.8.0", - note = "these type aliases are no longer supported by \ - the standard library, the `libc` crate on \ - crates.io should be used instead for the correct \ - definitions" -)] -#![allow(deprecated)] - -use crate::os::raw::c_long; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blkcnt_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blksize_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type dev_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type fflags_t = u32; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type ino_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type mode_t = u32; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type nlink_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type off_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type time_t = i64; - -#[stable(feature = "pthread_t", since = "1.8.0")] -pub type pthread_t = usize; - -#[repr(C)] -#[derive(Clone)] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: u16, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: u16, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_flags: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gen: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_lspare: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_birthtime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_birthtime_nsec: c_long, - #[cfg(target_arch = "x86")] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __unused: [u8; 8], -} diff --git a/library/std/src/os/fuchsia/fs.rs b/library/std/src/os/fuchsia/fs.rs deleted file mode 100644 index b48a46f9124a9..0000000000000 --- a/library/std/src/os/fuchsia/fs.rs +++ /dev/null @@ -1,95 +0,0 @@ -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::Metadata; -use crate::sys_common::AsInner; - -/// OS-specific extensions to [`fs::Metadata`]. -/// -/// [`fs::Metadata`]: crate::fs::Metadata -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_dev as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - self.as_inner().as_inner().st_atime as i64 - } - fn st_atime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_atime_nsec as i64 - } - fn st_mtime(&self) -> i64 { - self.as_inner().as_inner().st_mtime as i64 - } - fn st_mtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_mtime_nsec as i64 - } - fn st_ctime(&self) -> i64 { - self.as_inner().as_inner().st_ctime as i64 - } - fn st_ctime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_ctime_nsec as i64 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } -} diff --git a/library/std/src/os/fuchsia/mod.rs b/library/std/src/os/fuchsia/mod.rs deleted file mode 100644 index cd1b8233eb3ec..0000000000000 --- a/library/std/src/os/fuchsia/mod.rs +++ /dev/null @@ -1,6 +0,0 @@ -//! Fuchsia-specific definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] - -pub mod fs; -pub mod raw; diff --git a/library/std/src/os/fuchsia/raw.rs b/library/std/src/os/fuchsia/raw.rs deleted file mode 100644 index cb570beb8a1e7..0000000000000 --- a/library/std/src/os/fuchsia/raw.rs +++ /dev/null @@ -1,294 +0,0 @@ -//! Fuchsia-specific raw type definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![deprecated( - since = "1.8.0", - note = "these type aliases are no longer supported by \ - the standard library, the `libc` crate on \ - crates.io should be used instead for the correct \ - definitions" -)] -#![allow(deprecated)] - -use crate::os::raw::c_ulong; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type dev_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type mode_t = u32; - -#[stable(feature = "pthread_t", since = "1.8.0")] -pub type pthread_t = c_ulong; - -#[doc(inline)] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub use self::arch::{blkcnt_t, blksize_t, ino_t, nlink_t, off_t, stat, time_t}; - -#[cfg(any(target_arch = "x86", target_arch = "powerpc", target_arch = "arm"))] -mod arch { - use crate::os::raw::{c_long, c_short, c_uint}; - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blkcnt_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blksize_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type ino_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type nlink_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type off_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type time_t = i64; - - #[repr(C)] - #[derive(Clone)] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad1: c_short, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __st_ino: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad2: c_uint, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: u64, - } -} - -#[cfg(target_arch = "mips")] -mod arch { - use crate::os::raw::{c_long, c_ulong}; - - #[cfg(target_env = "musl")] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blkcnt_t = i64; - #[cfg(not(target_env = "musl"))] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blkcnt_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blksize_t = u64; - #[cfg(target_env = "musl")] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type ino_t = u64; - #[cfg(not(target_env = "musl"))] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type ino_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type nlink_t = u64; - #[cfg(target_env = "musl")] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type off_t = u64; - #[cfg(not(target_env = "musl"))] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type off_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type time_t = i64; - - #[repr(C)] - #[derive(Clone)] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: c_ulong, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_pad1: [c_long; 3], - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: c_ulong, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_pad2: [c_long; 2], - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_pad5: [c_long; 14], - } -} - -#[cfg(target_arch = "mips64")] -mod arch { - pub use libc::{blkcnt_t, blksize_t, ino_t, nlink_t, off_t, stat, time_t}; -} - -#[cfg(target_arch = "aarch64")] -mod arch { - use crate::os::raw::{c_int, c_long}; - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blkcnt_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blksize_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type ino_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type nlink_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type off_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type time_t = i64; - - #[repr(C)] - #[derive(Clone)] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad1: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad2: c_int, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __unused: [c_int; 2], - } -} - -#[cfg(target_arch = "x86_64")] -mod arch { - use crate::os::raw::{c_int, c_long}; - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blkcnt_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blksize_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type ino_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type nlink_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type off_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type time_t = i64; - - #[repr(C)] - #[derive(Clone)] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad0: c_int, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __unused: [c_long; 3], - } -} - -#[cfg(target_arch = "riscv64")] -mod arch { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub use libc::{blkcnt_t, blksize_t, ino_t, nlink_t, off_t, stat, time_t}; -} diff --git a/library/std/src/os/haiku/fs.rs b/library/std/src/os/haiku/fs.rs deleted file mode 100644 index a23a2af8f6e7b..0000000000000 --- a/library/std/src/os/haiku/fs.rs +++ /dev/null @@ -1,127 +0,0 @@ -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::Metadata; -use crate::sys_common::AsInner; - -#[allow(deprecated)] -use crate::os::haiku::raw; - -/// OS-specific extensions to [`fs::Metadata`]. -/// -/// [`fs::Metadata`]: crate::fs::Metadata -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - /// Gain a reference to the underlying `stat` structure which contains - /// the raw information returned by the OS. - /// - /// The contents of the returned `stat` are **not** consistent across - /// Unix platforms. The `os::unix::fs::MetadataExt` trait contains the - /// cross-Unix abstractions contained within the raw stat. - #[stable(feature = "metadata_ext", since = "1.1.0")] - #[deprecated( - since = "1.8.0", - note = "deprecated in favor of the accessor \ - methods of this trait" - )] - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat; - - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_crtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_crtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat { - unsafe { &*(self.as_inner().as_inner() as *const libc::stat as *const raw::stat) } - } - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_dev as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - self.as_inner().as_inner().st_atime as i64 - } - fn st_atime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_atime_nsec as i64 - } - fn st_mtime(&self) -> i64 { - self.as_inner().as_inner().st_mtime as i64 - } - fn st_mtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_mtime_nsec as i64 - } - fn st_ctime(&self) -> i64 { - self.as_inner().as_inner().st_ctime as i64 - } - fn st_ctime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_ctime_nsec as i64 - } - fn st_crtime(&self) -> i64 { - self.as_inner().as_inner().st_crtime as i64 - } - fn st_crtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_crtime_nsec as i64 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } -} diff --git a/library/std/src/os/haiku/mod.rs b/library/std/src/os/haiku/mod.rs deleted file mode 100644 index 73f500cadaa30..0000000000000 --- a/library/std/src/os/haiku/mod.rs +++ /dev/null @@ -1,6 +0,0 @@ -//! Haiku-specific definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] - -pub mod fs; -pub mod raw; diff --git a/library/std/src/os/haiku/raw.rs b/library/std/src/os/haiku/raw.rs deleted file mode 100644 index afbb66ccb5e5d..0000000000000 --- a/library/std/src/os/haiku/raw.rs +++ /dev/null @@ -1,79 +0,0 @@ -//! Haiku-specific raw type definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![deprecated( - since = "1.53.0", - note = "these type aliases are no longer supported by \ - the standard library, the `libc` crate on \ - crates.io should be used instead for the correct \ - definitions" -)] -#![allow(deprecated)] - -use crate::os::raw::c_long; -use crate::os::unix::raw::{gid_t, uid_t}; - -// Use the direct definition of usize, instead of uintptr_t like in libc -#[stable(feature = "pthread_t", since = "1.8.0")] -pub type pthread_t = usize; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blkcnt_t = i64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blksize_t = i32; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type dev_t = i32; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type ino_t = i64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type mode_t = u32; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type nlink_t = i32; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type off_t = i64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type time_t = i32; - -#[repr(C)] -#[derive(Clone)] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: dev_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: ino_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: mode_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: nlink_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: uid_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: gid_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: off_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: dev_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: blksize_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_crtime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_crtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_type: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: blkcnt_t, -} diff --git a/library/std/src/os/hermit/ffi.rs b/library/std/src/os/hermit/ffi.rs deleted file mode 100644 index 19761fd99b400..0000000000000 --- a/library/std/src/os/hermit/ffi.rs +++ /dev/null @@ -1,41 +0,0 @@ -//! HermitCore-specific extension to the primitives in the `std::ffi` module -//! -//! # Examples -//! -//! ``` -//! use std::ffi::OsString; -//! use std::os::hermit::ffi::OsStringExt; -//! -//! let bytes = b"foo".to_vec(); -//! -//! // OsStringExt::from_vec -//! let os_string = OsString::from_vec(bytes); -//! assert_eq!(os_string.to_str(), Some("foo")); -//! -//! // OsStringExt::into_vec -//! let bytes = os_string.into_vec(); -//! assert_eq!(bytes, b"foo"); -//! ``` -//! -//! ``` -//! use std::ffi::OsStr; -//! use std::os::hermit::ffi::OsStrExt; -//! -//! let bytes = b"foo"; -//! -//! // OsStrExt::from_bytes -//! let os_str = OsStr::from_bytes(bytes); -//! assert_eq!(os_str.to_str(), Some("foo")); -//! -//! // OsStrExt::as_bytes -//! let bytes = os_str.as_bytes(); -//! assert_eq!(bytes, b"foo"); -//! ``` - -#![stable(feature = "rust1", since = "1.0.0")] - -#[path = "../unix/ffi/os_str.rs"] -mod os_str; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::os_str::{OsStrExt, OsStringExt}; diff --git a/library/std/src/os/hermit/io/mod.rs b/library/std/src/os/hermit/io/mod.rs deleted file mode 100644 index 524dfae0d63ae..0000000000000 --- a/library/std/src/os/hermit/io/mod.rs +++ /dev/null @@ -1,13 +0,0 @@ -#![stable(feature = "os_fd", since = "1.66.0")] - -mod net; -#[path = "../../fd/owned.rs"] -mod owned; -#[path = "../../fd/raw.rs"] -mod raw; - -// Export the types and traits for the public API. -#[stable(feature = "os_fd", since = "1.66.0")] -pub use owned::*; -#[stable(feature = "os_fd", since = "1.66.0")] -pub use raw::*; diff --git a/library/std/src/os/hermit/io/net.rs b/library/std/src/os/hermit/io/net.rs deleted file mode 100644 index 8f3802d7873dc..0000000000000 --- a/library/std/src/os/hermit/io/net.rs +++ /dev/null @@ -1,46 +0,0 @@ -use crate::os::hermit::io::OwnedFd; -use crate::os::hermit::io::{AsRawFd, FromRawFd, IntoRawFd, RawFd}; -use crate::sys_common::{self, AsInner, FromInner, IntoInner}; -use crate::{net, sys}; - -macro_rules! impl_as_raw_fd { - ($($t:ident)*) => {$( - #[stable(feature = "rust1", since = "1.0.0")] - impl AsRawFd for net::$t { - #[inline] - fn as_raw_fd(&self) -> RawFd { - self.as_inner().socket().as_raw_fd() - } - } - )*}; -} -impl_as_raw_fd! { TcpStream TcpListener UdpSocket } - -macro_rules! impl_from_raw_fd { - ($($t:ident)*) => {$( - #[stable(feature = "from_raw_os", since = "1.1.0")] - impl FromRawFd for net::$t { - #[inline] - unsafe fn from_raw_fd(fd: RawFd) -> net::$t { - unsafe { - let socket = sys::net::Socket::from_inner(FromInner::from_inner(OwnedFd::from_raw_fd(fd))); - net::$t::from_inner(sys_common::net::$t::from_inner(socket)) - } - } - } - )*}; -} -impl_from_raw_fd! { TcpStream TcpListener UdpSocket } - -macro_rules! impl_into_raw_fd { - ($($t:ident)*) => {$( - #[stable(feature = "into_raw_os", since = "1.4.0")] - impl IntoRawFd for net::$t { - #[inline] - fn into_raw_fd(self) -> RawFd { - self.into_inner().into_socket().into_inner().into_inner().into_raw_fd() - } - } - )*}; -} -impl_into_raw_fd! { TcpStream TcpListener UdpSocket } diff --git a/library/std/src/os/hermit/mod.rs b/library/std/src/os/hermit/mod.rs deleted file mode 100644 index 02a4b2c3ab5e7..0000000000000 --- a/library/std/src/os/hermit/mod.rs +++ /dev/null @@ -1,18 +0,0 @@ -#![stable(feature = "rust1", since = "1.0.0")] - -#[allow(unused_extern_crates)] -#[stable(feature = "rust1", since = "1.0.0")] -pub extern crate hermit_abi; - -pub mod ffi; -pub mod io; - -/// A prelude for conveniently writing platform-specific code. -/// -/// Includes all extension traits, and some important type definitions. -#[stable(feature = "rust1", since = "1.0.0")] -pub mod prelude { - #[doc(no_inline)] - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::ffi::{OsStrExt, OsStringExt}; -} diff --git a/library/std/src/os/horizon/fs.rs b/library/std/src/os/horizon/fs.rs deleted file mode 100644 index 1325522105dc8..0000000000000 --- a/library/std/src/os/horizon/fs.rs +++ /dev/null @@ -1,95 +0,0 @@ -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::Metadata; -use crate::sys_common::AsInner; - -/// OS-specific extensions to [`fs::Metadata`]. -/// -/// [`fs::Metadata`]: crate::fs::Metadata -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_dev as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - self.as_inner().as_inner().st_atim.tv_sec - } - fn st_atime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_atim.tv_nsec as i64 - } - fn st_mtime(&self) -> i64 { - self.as_inner().as_inner().st_mtim.tv_sec - } - fn st_mtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_mtim.tv_nsec as i64 - } - fn st_ctime(&self) -> i64 { - self.as_inner().as_inner().st_ctim.tv_sec - } - fn st_ctime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_ctim.tv_nsec as i64 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } -} diff --git a/library/std/src/os/horizon/mod.rs b/library/std/src/os/horizon/mod.rs deleted file mode 100644 index 326d0ae9cb96d..0000000000000 --- a/library/std/src/os/horizon/mod.rs +++ /dev/null @@ -1,6 +0,0 @@ -//! Definitions for Horizon OS - -#![stable(feature = "raw_ext", since = "1.1.0")] - -pub mod fs; -pub(crate) mod raw; diff --git a/library/std/src/os/horizon/raw.rs b/library/std/src/os/horizon/raw.rs deleted file mode 100644 index 929fa7db1f964..0000000000000 --- a/library/std/src/os/horizon/raw.rs +++ /dev/null @@ -1,70 +0,0 @@ -//! Horizon OS raw type definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![deprecated( - since = "1.8.0", - note = "these type aliases are no longer supported by \ - the standard library, the `libc` crate on \ - crates.io should be used instead for the correct \ - definitions" -)] -#![allow(deprecated)] - -use crate::os::raw::c_long; -use crate::os::unix::raw::{gid_t, uid_t}; - -#[stable(feature = "pthread_t", since = "1.8.0")] -pub type pthread_t = libc::pthread_t; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blkcnt_t = libc::blkcnt_t; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blksize_t = libc::blksize_t; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type dev_t = libc::dev_t; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type ino_t = libc::ino_t; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type mode_t = libc::mode_t; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type nlink_t = libc::nlink_t; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type off_t = libc::off_t; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type time_t = libc::time_t; - -#[repr(C)] -#[derive(Clone)] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: dev_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: ino_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: mode_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: nlink_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: uid_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: gid_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: dev_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: off_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: blksize_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: blkcnt_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_spare4: [c_long; 2usize], -} diff --git a/library/std/src/os/hurd/fs.rs b/library/std/src/os/hurd/fs.rs deleted file mode 100644 index 00ff1560f31d9..0000000000000 --- a/library/std/src/os/hurd/fs.rs +++ /dev/null @@ -1,348 +0,0 @@ -//! Hurd-specific extensions to primitives in the [`std::fs`] module. -//! -//! [`std::fs`]: crate::fs - -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::Metadata; -use crate::sys_common::AsInner; - -/// OS-specific extensions to [`fs::Metadata`]. -/// -/// [`fs::Metadata`]: crate::fs::Metadata -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - /// Returns the device ID on which this file resides. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::hurd::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_dev()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - /// Returns the inode number. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::hurd::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_ino()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - /// Returns the file type and mode. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::hurd::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_mode()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - /// Returns the number of hard links to file. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::hurd::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_nlink()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - /// Returns the user ID of the file owner. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::hurd::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_uid()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - /// Returns the group ID of the file owner. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::hurd::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_gid()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - /// Returns the device ID that this file represents. Only relevant for special file. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::hurd::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_rdev()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - /// Returns the size of the file (if it is a regular file or a symbolic link) in bytes. - /// - /// The size of a symbolic link is the length of the pathname it contains, - /// without a terminating null byte. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::hurd::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_size()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - /// Returns the last access time of the file, in seconds since Unix Epoch. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::hurd::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_atime()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - /// Returns the last access time of the file, in nanoseconds since [`st_atime`]. - /// - /// [`st_atime`]: Self::st_atime - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::hurd::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_atime_nsec()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - /// Returns the last modification time of the file, in seconds since Unix Epoch. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::hurd::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_mtime()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - /// Returns the last modification time of the file, in nanoseconds since [`st_mtime`]. - /// - /// [`st_mtime`]: Self::st_mtime - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::hurd::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_mtime_nsec()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - /// Returns the last status change time of the file, in seconds since Unix Epoch. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::hurd::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_ctime()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - /// Returns the last status change time of the file, in nanoseconds since [`st_ctime`]. - /// - /// [`st_ctime`]: Self::st_ctime - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::hurd::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_ctime_nsec()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - /// Returns the "preferred" block size for efficient filesystem I/O. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::hurd::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_blksize()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - /// Returns the number of blocks allocated to the file, 512-byte units. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::hurd::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_blocks()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_fsid as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - self.as_inner().as_inner().st_atim.tv_sec as i64 - } - fn st_atime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_atim.tv_nsec as i64 - } - fn st_mtime(&self) -> i64 { - self.as_inner().as_inner().st_mtim.tv_sec as i64 - } - fn st_mtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_mtim.tv_nsec as i64 - } - fn st_ctime(&self) -> i64 { - self.as_inner().as_inner().st_ctim.tv_sec as i64 - } - fn st_ctime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_ctim.tv_nsec as i64 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } -} diff --git a/library/std/src/os/hurd/mod.rs b/library/std/src/os/hurd/mod.rs deleted file mode 100644 index aee86c7f61655..0000000000000 --- a/library/std/src/os/hurd/mod.rs +++ /dev/null @@ -1,6 +0,0 @@ -//! Hurd-specific definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] - -pub mod fs; -pub mod raw; diff --git a/library/std/src/os/hurd/raw.rs b/library/std/src/os/hurd/raw.rs deleted file mode 100644 index fa266663528ca..0000000000000 --- a/library/std/src/os/hurd/raw.rs +++ /dev/null @@ -1,33 +0,0 @@ -//! Hurd-specific raw type definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![deprecated( - since = "1.8.0", - note = "these type aliases are no longer supported by \ - the standard library, the `libc` crate on \ - crates.io should be used instead for the correct \ - definitions" -)] -#![allow(deprecated)] - -use crate::os::raw::{c_long, c_uint, c_ulong}; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blkcnt_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blksize_t = c_long; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type dev_t = c_ulong; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type ino_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type mode_t = c_uint; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type nlink_t = c_ulong; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type off_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type time_t = c_long; - -#[stable(feature = "pthread_t", since = "1.8.0")] -pub type pthread_t = c_long; diff --git a/library/std/src/os/illumos/fs.rs b/library/std/src/os/illumos/fs.rs deleted file mode 100644 index 63be48b8131b2..0000000000000 --- a/library/std/src/os/illumos/fs.rs +++ /dev/null @@ -1,116 +0,0 @@ -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::Metadata; -use crate::sys_common::AsInner; - -#[allow(deprecated)] -use crate::os::illumos::raw; - -/// OS-specific extensions to [`fs::Metadata`]. -/// -/// [`fs::Metadata`]: crate::fs::Metadata -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - /// Gain a reference to the underlying `stat` structure which contains - /// the raw information returned by the OS. - /// - /// The contents of the returned `stat` are **not** consistent across - /// Unix platforms. The `os::unix::fs::MetadataExt` trait contains the - /// cross-Unix abstractions contained within the raw stat. - #[stable(feature = "metadata_ext", since = "1.1.0")] - #[deprecated( - since = "1.8.0", - note = "deprecated in favor of the accessor methods of this trait" - )] - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat; - - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat { - unsafe { &*(self.as_inner().as_inner() as *const libc::stat as *const raw::stat) } - } - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_dev as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - self.as_inner().as_inner().st_atime as i64 - } - fn st_atime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_atime_nsec as i64 - } - fn st_mtime(&self) -> i64 { - self.as_inner().as_inner().st_mtime as i64 - } - fn st_mtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_mtime_nsec as i64 - } - fn st_ctime(&self) -> i64 { - self.as_inner().as_inner().st_ctime as i64 - } - fn st_ctime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_ctime_nsec as i64 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } -} diff --git a/library/std/src/os/illumos/mod.rs b/library/std/src/os/illumos/mod.rs deleted file mode 100644 index e61926f89356a..0000000000000 --- a/library/std/src/os/illumos/mod.rs +++ /dev/null @@ -1,6 +0,0 @@ -//! illumos-specific definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] - -pub mod fs; -pub mod raw; diff --git a/library/std/src/os/illumos/raw.rs b/library/std/src/os/illumos/raw.rs deleted file mode 100644 index 2bea9ebb3c836..0000000000000 --- a/library/std/src/os/illumos/raw.rs +++ /dev/null @@ -1,74 +0,0 @@ -//! illumos-specific raw type definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![deprecated( - since = "1.8.0", - note = "these type aliases are no longer supported by the standard library, the `libc` \ - crate on crates.io should be used instead for the correct definitions" -)] -#![allow(deprecated)] - -use crate::os::raw::c_long; -use crate::os::unix::raw::{gid_t, uid_t}; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blkcnt_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blksize_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type dev_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type fflags_t = u32; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type ino_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type mode_t = u32; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type nlink_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type off_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type time_t = i64; - -#[stable(feature = "pthread_t", since = "1.8.0")] -pub type pthread_t = u32; - -#[repr(C)] -#[derive(Clone)] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: dev_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: ino_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: mode_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: nlink_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: uid_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: gid_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: dev_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: off_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: blksize_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: blkcnt_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __unused: [u8; 16], -} diff --git a/library/std/src/os/ios/fs.rs b/library/std/src/os/ios/fs.rs deleted file mode 100644 index e5df4de0b7f71..0000000000000 --- a/library/std/src/os/ios/fs.rs +++ /dev/null @@ -1,160 +0,0 @@ -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::{self, Metadata}; -use crate::sealed::Sealed; -use crate::sys_common::{AsInner, AsInnerMut, IntoInner}; -use crate::time::SystemTime; - -#[allow(deprecated)] -use super::raw; - -/// OS-specific extensions to [`fs::Metadata`]. -/// -/// [`fs::Metadata`]: crate::fs::Metadata -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - /// Gain a reference to the underlying `stat` structure which contains - /// the raw information returned by the OS. - /// - /// The contents of the returned `stat` are **not** consistent across - /// Unix platforms. The `os::unix::fs::MetadataExt` trait contains the - /// cross-Unix abstractions contained within the raw stat. - #[stable(feature = "metadata_ext", since = "1.1.0")] - #[deprecated( - since = "1.8.0", - note = "deprecated in favor of the accessor \ - methods of this trait" - )] - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat; - - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_birthtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_birthtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_flags(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gen(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_lspare(&self) -> u32; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat { - unsafe { &*(self.as_inner().as_inner() as *const libc::stat as *const raw::stat) } - } - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_dev as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - self.as_inner().as_inner().st_atime as i64 - } - fn st_atime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_atime_nsec as i64 - } - fn st_mtime(&self) -> i64 { - self.as_inner().as_inner().st_mtime as i64 - } - fn st_mtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_mtime_nsec as i64 - } - fn st_ctime(&self) -> i64 { - self.as_inner().as_inner().st_ctime as i64 - } - fn st_ctime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_ctime_nsec as i64 - } - fn st_birthtime(&self) -> i64 { - self.as_inner().as_inner().st_birthtime as i64 - } - fn st_birthtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_birthtime_nsec as i64 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } - fn st_gen(&self) -> u32 { - self.as_inner().as_inner().st_gen as u32 - } - fn st_flags(&self) -> u32 { - self.as_inner().as_inner().st_flags as u32 - } - fn st_lspare(&self) -> u32 { - self.as_inner().as_inner().st_lspare as u32 - } -} - -/// OS-specific extensions to [`fs::FileTimes`]. -#[stable(feature = "file_set_times", since = "1.75.0")] -pub trait FileTimesExt: Sealed { - /// Set the creation time of a file. - #[stable(feature = "file_set_times", since = "1.75.0")] - fn set_created(self, t: SystemTime) -> Self; -} - -#[stable(feature = "file_set_times", since = "1.75.0")] -impl FileTimesExt for fs::FileTimes { - fn set_created(mut self, t: SystemTime) -> Self { - self.as_inner_mut().set_created(t.into_inner()); - self - } -} diff --git a/library/std/src/os/ios/mod.rs b/library/std/src/os/ios/mod.rs deleted file mode 100644 index fdefa1f6b21c4..0000000000000 --- a/library/std/src/os/ios/mod.rs +++ /dev/null @@ -1,6 +0,0 @@ -//! iOS-specific definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] - -pub mod fs; -pub mod raw; diff --git a/library/std/src/os/ios/raw.rs b/library/std/src/os/ios/raw.rs deleted file mode 100644 index af12aeebe5d0c..0000000000000 --- a/library/std/src/os/ios/raw.rs +++ /dev/null @@ -1,83 +0,0 @@ -//! iOS-specific raw type definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![deprecated( - since = "1.8.0", - note = "these type aliases are no longer supported by \ - the standard library, the `libc` crate on \ - crates.io should be used instead for the correct \ - definitions" -)] -#![allow(deprecated)] - -use crate::os::raw::c_long; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blkcnt_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blksize_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type dev_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type ino_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type mode_t = u32; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type nlink_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type off_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type time_t = i64; - -#[stable(feature = "pthread_t", since = "1.8.0")] -pub type pthread_t = usize; - -#[repr(C)] -#[derive(Clone)] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: u16, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: u16, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_birthtime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_birthtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_flags: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gen: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_lspare: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_qspare: [i64; 2], -} diff --git a/library/std/src/os/l4re/fs.rs b/library/std/src/os/l4re/fs.rs deleted file mode 100644 index 6d6a535b1e831..0000000000000 --- a/library/std/src/os/l4re/fs.rs +++ /dev/null @@ -1,382 +0,0 @@ -//! L4Re-specific extensions to primitives in the [`std::fs`] module. -//! -//! [`std::fs`]: crate::fs - -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::Metadata; -use crate::sys_common::AsInner; - -#[allow(deprecated)] -use crate::os::l4re::raw; - -/// OS-specific extensions to [`fs::Metadata`]. -/// -/// [`fs::Metadata`]: crate::fs::Metadata -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - /// Gain a reference to the underlying `stat` structure which contains - /// the raw information returned by the OS. - /// - /// The contents of the returned [`stat`] are **not** consistent across - /// Unix platforms. The `os::unix::fs::MetadataExt` trait contains the - /// cross-Unix abstractions contained within the raw stat. - /// - /// [`stat`]: struct@crate::os::linux::raw::stat - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// let stat = meta.as_raw_stat(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext", since = "1.1.0")] - #[deprecated(since = "1.8.0", note = "other methods of this trait are now preferred")] - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat; - - /// Returns the device ID on which this file resides. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_dev()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - /// Returns the inode number. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_ino()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - /// Returns the file type and mode. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_mode()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - /// Returns the number of hard links to file. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_nlink()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - /// Returns the user ID of the file owner. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_uid()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - /// Returns the group ID of the file owner. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_gid()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - /// Returns the device ID that this file represents. Only relevant for special file. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_rdev()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - /// Returns the size of the file (if it is a regular file or a symbolic link) in bytes. - /// - /// The size of a symbolic link is the length of the pathname it contains, - /// without a terminating null byte. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_size()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - /// Returns the last access time of the file, in seconds since Unix Epoch. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_atime()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - /// Returns the last access time of the file, in nanoseconds since [`st_atime`]. - /// - /// [`st_atime`]: Self::st_atime - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_atime_nsec()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - /// Returns the last modification time of the file, in seconds since Unix Epoch. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_mtime()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - /// Returns the last modification time of the file, in nanoseconds since [`st_mtime`]. - /// - /// [`st_mtime`]: Self::st_mtime - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_mtime_nsec()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - /// Returns the last status change time of the file, in seconds since Unix Epoch. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_ctime()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - /// Returns the last status change time of the file, in nanoseconds since [`st_ctime`]. - /// - /// [`st_ctime`]: Self::st_ctime - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_ctime_nsec()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - /// Returns the "preferred" block size for efficient filesystem I/O. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_blksize()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - /// Returns the number of blocks allocated to the file, 512-byte units. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_blocks()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat { - unsafe { &*(self.as_inner().as_inner() as *const libc::stat64 as *const raw::stat) } - } - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_dev as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - self.as_inner().as_inner().st_atime as i64 - } - fn st_atime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_atime_nsec as i64 - } - fn st_mtime(&self) -> i64 { - self.as_inner().as_inner().st_mtime as i64 - } - fn st_mtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_mtime_nsec as i64 - } - fn st_ctime(&self) -> i64 { - self.as_inner().as_inner().st_ctime as i64 - } - fn st_ctime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_ctime_nsec as i64 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } -} diff --git a/library/std/src/os/l4re/mod.rs b/library/std/src/os/l4re/mod.rs deleted file mode 100644 index 14c2425c16517..0000000000000 --- a/library/std/src/os/l4re/mod.rs +++ /dev/null @@ -1,7 +0,0 @@ -//! L4Re-specific definitions. - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![doc(cfg(target_os = "l4re"))] - -pub mod fs; -pub mod raw; diff --git a/library/std/src/os/l4re/raw.rs b/library/std/src/os/l4re/raw.rs deleted file mode 100644 index 8fb6e99ecfa1e..0000000000000 --- a/library/std/src/os/l4re/raw.rs +++ /dev/null @@ -1,364 +0,0 @@ -//! L4Re-specific raw type definitions. - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![deprecated( - since = "1.8.0", - note = "these type aliases are no longer supported by \ - the standard library, the `libc` crate on \ - crates.io should be used instead for the correct \ - definitions" -)] -#![allow(deprecated)] - -use crate::os::raw::c_ulong; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type dev_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type mode_t = u32; - -#[stable(feature = "pthread_t", since = "1.8.0")] -pub type pthread_t = c_ulong; - -#[doc(inline)] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub use self::arch::{blkcnt_t, blksize_t, ino_t, nlink_t, off_t, stat, time_t}; - -#[cfg(any( - target_arch = "x86", - target_arch = "m68k", - target_arch = "csky", - target_arch = "powerpc", - target_arch = "sparc", - target_arch = "arm", - target_arch = "wasm32" -))] -mod arch { - use crate::os::raw::{c_long, c_short, c_uint}; - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blkcnt_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blksize_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type ino_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type nlink_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type off_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type time_t = i64; - - #[repr(C)] - #[derive(Clone)] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad1: c_short, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __st_ino: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad2: c_uint, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: u64, - } -} - -#[cfg(target_arch = "mips")] -mod arch { - use crate::os::raw::{c_long, c_ulong}; - - #[cfg(target_env = "musl")] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blkcnt_t = i64; - #[cfg(not(target_env = "musl"))] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blkcnt_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blksize_t = u64; - #[cfg(target_env = "musl")] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type ino_t = u64; - #[cfg(not(target_env = "musl"))] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type ino_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type nlink_t = u64; - #[cfg(target_env = "musl")] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type off_t = u64; - #[cfg(not(target_env = "musl"))] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type off_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type time_t = i64; - - #[repr(C)] - #[derive(Clone)] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: c_ulong, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_pad1: [c_long; 3], - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: c_ulong, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_pad2: [c_long; 2], - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_pad5: [c_long; 14], - } -} - -#[cfg(target_arch = "hexagon")] -mod arch { - use crate::os::raw::{c_int, c_long, c_uint}; - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blkcnt_t = i64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blksize_t = c_long; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type ino_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type nlink_t = c_uint; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type off_t = i64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type time_t = i64; - - #[repr(C)] - #[derive(Clone)] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad1: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad2: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad3: [c_int; 2], - } -} - -#[cfg(any( - target_arch = "mips64", - target_arch = "s390x", - target_arch = "sparc64", - target_arch = "riscv64", - target_arch = "riscv32" -))] -mod arch { - pub use libc::{blkcnt_t, blksize_t, ino_t, nlink_t, off_t, stat, time_t}; -} - -#[cfg(target_arch = "aarch64")] -mod arch { - use crate::os::raw::{c_int, c_long}; - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blkcnt_t = i64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blksize_t = i32; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type ino_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type nlink_t = u32; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type off_t = i64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type time_t = c_long; - - #[repr(C)] - #[derive(Clone)] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad1: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad2: c_int, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __unused: [c_int; 2], - } -} - -#[cfg(any(target_arch = "x86_64", target_arch = "powerpc64"))] -mod arch { - use crate::os::raw::{c_int, c_long}; - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blkcnt_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blksize_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type ino_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type nlink_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type off_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type time_t = i64; - - #[repr(C)] - #[derive(Clone)] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad0: c_int, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __unused: [c_long; 3], - } -} diff --git a/library/std/src/os/linux/fs.rs b/library/std/src/os/linux/fs.rs deleted file mode 100644 index ab0b2a3eda3f5..0000000000000 --- a/library/std/src/os/linux/fs.rs +++ /dev/null @@ -1,404 +0,0 @@ -//! Linux-specific extensions to primitives in the [`std::fs`] module. -//! -//! [`std::fs`]: crate::fs - -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::Metadata; -use crate::sys_common::AsInner; - -#[allow(deprecated)] -use crate::os::linux::raw; - -/// OS-specific extensions to [`fs::Metadata`]. -/// -/// [`fs::Metadata`]: crate::fs::Metadata -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - /// Gain a reference to the underlying `stat` structure which contains - /// the raw information returned by the OS. - /// - /// The contents of the returned [`stat`] are **not** consistent across - /// Unix platforms. The `os::unix::fs::MetadataExt` trait contains the - /// cross-Unix abstractions contained within the raw stat. - /// - /// [`stat`]: struct@crate::os::linux::raw::stat - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// let stat = meta.as_raw_stat(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext", since = "1.1.0")] - #[deprecated(since = "1.8.0", note = "other methods of this trait are now preferred")] - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat; - - /// Returns the device ID on which this file resides. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_dev()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - /// Returns the inode number. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_ino()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - /// Returns the file type and mode. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_mode()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - /// Returns the number of hard links to file. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_nlink()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - /// Returns the user ID of the file owner. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_uid()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - /// Returns the group ID of the file owner. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_gid()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - /// Returns the device ID that this file represents. Only relevant for special file. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_rdev()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - /// Returns the size of the file (if it is a regular file or a symbolic link) in bytes. - /// - /// The size of a symbolic link is the length of the pathname it contains, - /// without a terminating null byte. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_size()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - /// Returns the last access time of the file, in seconds since Unix Epoch. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_atime()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - /// Returns the last access time of the file, in nanoseconds since [`st_atime`]. - /// - /// [`st_atime`]: Self::st_atime - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_atime_nsec()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - /// Returns the last modification time of the file, in seconds since Unix Epoch. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_mtime()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - /// Returns the last modification time of the file, in nanoseconds since [`st_mtime`]. - /// - /// [`st_mtime`]: Self::st_mtime - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_mtime_nsec()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - /// Returns the last status change time of the file, in seconds since Unix Epoch. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_ctime()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - /// Returns the last status change time of the file, in nanoseconds since [`st_ctime`]. - /// - /// [`st_ctime`]: Self::st_ctime - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_ctime_nsec()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - /// Returns the "preferred" block size for efficient filesystem I/O. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_blksize()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - /// Returns the number of blocks allocated to the file, 512-byte units. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::linux::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_blocks()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat { - #[cfg(target_env = "musl")] - unsafe { - &*(self.as_inner().as_inner() as *const libc::stat as *const raw::stat) - } - #[cfg(not(target_env = "musl"))] - unsafe { - &*(self.as_inner().as_inner() as *const libc::stat64 as *const raw::stat) - } - } - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_dev as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - let file_attr = self.as_inner(); - #[cfg(all(target_env = "gnu", target_pointer_width = "32"))] - if let Some(atime) = file_attr.stx_atime() { - return atime.tv_sec; - } - file_attr.as_inner().st_atime as i64 - } - fn st_atime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_atime_nsec as i64 - } - fn st_mtime(&self) -> i64 { - let file_attr = self.as_inner(); - #[cfg(all(target_env = "gnu", target_pointer_width = "32"))] - if let Some(mtime) = file_attr.stx_mtime() { - return mtime.tv_sec; - } - file_attr.as_inner().st_mtime as i64 - } - fn st_mtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_mtime_nsec as i64 - } - fn st_ctime(&self) -> i64 { - let file_attr = self.as_inner(); - #[cfg(all(target_env = "gnu", target_pointer_width = "32"))] - if let Some(ctime) = file_attr.stx_ctime() { - return ctime.tv_sec; - } - file_attr.as_inner().st_ctime as i64 - } - fn st_ctime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_ctime_nsec as i64 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } -} diff --git a/library/std/src/os/linux/mod.rs b/library/std/src/os/linux/mod.rs deleted file mode 100644 index c17053011adfc..0000000000000 --- a/library/std/src/os/linux/mod.rs +++ /dev/null @@ -1,9 +0,0 @@ -//! Linux-specific definitions. - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![doc(cfg(target_os = "linux"))] - -pub mod fs; -pub mod net; -pub mod process; -pub mod raw; diff --git a/library/std/src/os/linux/net.rs b/library/std/src/os/linux/net.rs deleted file mode 100644 index f898e70548706..0000000000000 --- a/library/std/src/os/linux/net.rs +++ /dev/null @@ -1,12 +0,0 @@ -//! Linux-specific networking functionality. - -#![stable(feature = "unix_socket_abstract", since = "1.70.0")] - -#[stable(feature = "unix_socket_abstract", since = "1.70.0")] -pub use crate::os::net::linux_ext::addr::SocketAddrExt; - -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -pub use crate::os::net::linux_ext::socket::UnixSocketExt; - -#[unstable(feature = "tcp_quickack", issue = "96256")] -pub use crate::os::net::linux_ext::tcp::TcpStreamExt; diff --git a/library/std/src/os/linux/process.rs b/library/std/src/os/linux/process.rs deleted file mode 100644 index 2ba67a6dd1aa9..0000000000000 --- a/library/std/src/os/linux/process.rs +++ /dev/null @@ -1,172 +0,0 @@ -//! Linux-specific extensions to primitives in the [`std::process`] module. -//! -//! [`std::process`]: crate::process - -#![unstable(feature = "linux_pidfd", issue = "82971")] - -use crate::io::Result; -use crate::os::unix::io::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd}; -use crate::process; -use crate::sealed::Sealed; -#[cfg(not(doc))] -use crate::sys::fd::FileDesc; -use crate::sys_common::{AsInner, AsInnerMut, FromInner, IntoInner}; - -#[cfg(doc)] -struct FileDesc; - -/// This type represents a file descriptor that refers to a process. -/// -/// A `PidFd` can be obtained by setting the corresponding option on [`Command`] -/// with [`create_pidfd`]. Subsequently, the created pidfd can be retrieved -/// from the [`Child`] by calling [`pidfd`] or [`take_pidfd`]. -/// -/// Example: -/// ```no_run -/// #![feature(linux_pidfd)] -/// use std::os::linux::process::{CommandExt, ChildExt}; -/// use std::process::Command; -/// -/// let mut child = Command::new("echo") -/// .create_pidfd(true) -/// .spawn() -/// .expect("Failed to spawn child"); -/// -/// let pidfd = child -/// .take_pidfd() -/// .expect("Failed to retrieve pidfd"); -/// -/// // The file descriptor will be closed when `pidfd` is dropped. -/// ``` -/// Refer to the man page of [`pidfd_open(2)`] for further details. -/// -/// [`Command`]: process::Command -/// [`create_pidfd`]: CommandExt::create_pidfd -/// [`Child`]: process::Child -/// [`pidfd`]: fn@ChildExt::pidfd -/// [`take_pidfd`]: ChildExt::take_pidfd -/// [`pidfd_open(2)`]: https://man7.org/linux/man-pages/man2/pidfd_open.2.html -#[derive(Debug)] -pub struct PidFd { - inner: FileDesc, -} - -impl AsInner for PidFd { - #[inline] - fn as_inner(&self) -> &FileDesc { - &self.inner - } -} - -impl FromInner for PidFd { - fn from_inner(inner: FileDesc) -> PidFd { - PidFd { inner } - } -} - -impl IntoInner for PidFd { - fn into_inner(self) -> FileDesc { - self.inner - } -} - -impl AsRawFd for PidFd { - #[inline] - fn as_raw_fd(&self) -> RawFd { - self.as_inner().as_raw_fd() - } -} - -impl FromRawFd for PidFd { - unsafe fn from_raw_fd(fd: RawFd) -> Self { - Self::from_inner(FileDesc::from_raw_fd(fd)) - } -} - -impl IntoRawFd for PidFd { - fn into_raw_fd(self) -> RawFd { - self.into_inner().into_raw_fd() - } -} - -impl AsFd for PidFd { - fn as_fd(&self) -> BorrowedFd<'_> { - self.as_inner().as_fd() - } -} - -impl From for PidFd { - fn from(fd: OwnedFd) -> Self { - Self::from_inner(FileDesc::from_inner(fd)) - } -} - -impl From for OwnedFd { - fn from(pid_fd: PidFd) -> Self { - pid_fd.into_inner().into_inner() - } -} - -/// Os-specific extensions for [`Child`] -/// -/// [`Child`]: process::Child -pub trait ChildExt: Sealed { - /// Obtains a reference to the [`PidFd`] created for this [`Child`], if available. - /// - /// A pidfd will only be available if its creation was requested with - /// [`create_pidfd`] when the corresponding [`Command`] was created. - /// - /// Even if requested, a pidfd may not be available due to an older - /// version of Linux being in use, or if some other error occurred. - /// - /// [`Command`]: process::Command - /// [`create_pidfd`]: CommandExt::create_pidfd - /// [`Child`]: process::Child - fn pidfd(&self) -> Result<&PidFd>; - - /// Takes ownership of the [`PidFd`] created for this [`Child`], if available. - /// - /// A pidfd will only be available if its creation was requested with - /// [`create_pidfd`] when the corresponding [`Command`] was created. - /// - /// Even if requested, a pidfd may not be available due to an older - /// version of Linux being in use, or if some other error occurred. - /// - /// [`Command`]: process::Command - /// [`create_pidfd`]: CommandExt::create_pidfd - /// [`Child`]: process::Child - fn take_pidfd(&mut self) -> Result; -} - -/// Os-specific extensions for [`Command`] -/// -/// [`Command`]: process::Command -pub trait CommandExt: Sealed { - /// Sets whether a [`PidFd`](struct@PidFd) should be created for the [`Child`] - /// spawned by this [`Command`]. - /// By default, no pidfd will be created. - /// - /// The pidfd can be retrieved from the child with [`pidfd`] or [`take_pidfd`]. - /// - /// A pidfd will only be created if it is possible to do so - /// in a guaranteed race-free manner. Otherwise, [`pidfd`] will return an error. - /// - /// If a pidfd has been successfully created and not been taken from the `Child` - /// then calls to `kill()`, `wait()` and `try_wait()` will use the pidfd - /// instead of the pid. This can prevent pid recycling races, e.g. - /// those caused by rogue libraries in the same process prematurely reaping - /// zombie children via `waitpid(-1, ...)` calls. - /// - /// [`Command`]: process::Command - /// [`Child`]: process::Child - /// [`pidfd`]: fn@ChildExt::pidfd - /// [`take_pidfd`]: ChildExt::take_pidfd - fn create_pidfd(&mut self, val: bool) -> &mut process::Command; -} - -impl CommandExt for process::Command { - fn create_pidfd(&mut self, val: bool) -> &mut process::Command { - self.as_inner_mut().create_pidfd(val); - self - } -} diff --git a/library/std/src/os/linux/raw.rs b/library/std/src/os/linux/raw.rs deleted file mode 100644 index c29dd62bc06f0..0000000000000 --- a/library/std/src/os/linux/raw.rs +++ /dev/null @@ -1,367 +0,0 @@ -//! Linux-specific raw type definitions. - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![deprecated( - since = "1.8.0", - note = "these type aliases are no longer supported by \ - the standard library, the `libc` crate on \ - crates.io should be used instead for the correct \ - definitions" -)] -#![allow(deprecated)] - -use crate::os::raw::c_ulong; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type dev_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type mode_t = u32; - -#[stable(feature = "pthread_t", since = "1.8.0")] -pub type pthread_t = c_ulong; - -#[doc(inline)] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub use self::arch::{blkcnt_t, blksize_t, ino_t, nlink_t, off_t, stat, time_t}; - -#[cfg(any( - target_arch = "x86", - target_arch = "m68k", - target_arch = "csky", - target_arch = "powerpc", - target_arch = "sparc", - target_arch = "arm", - target_arch = "wasm32" -))] -mod arch { - use crate::os::raw::{c_long, c_short, c_uint}; - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blkcnt_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blksize_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type ino_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type nlink_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type off_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type time_t = i64; - - #[repr(C)] - #[derive(Clone)] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad1: c_short, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __st_ino: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad2: c_uint, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: u64, - } -} - -#[cfg(any(target_arch = "mips", target_arch = "mips32r6"))] -mod arch { - use crate::os::raw::{c_long, c_ulong}; - - #[cfg(target_env = "musl")] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blkcnt_t = i64; - #[cfg(not(target_env = "musl"))] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blkcnt_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blksize_t = u64; - #[cfg(target_env = "musl")] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type ino_t = u64; - #[cfg(not(target_env = "musl"))] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type ino_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type nlink_t = u64; - #[cfg(target_env = "musl")] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type off_t = u64; - #[cfg(not(target_env = "musl"))] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type off_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type time_t = i64; - - #[repr(C)] - #[derive(Clone)] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: c_ulong, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_pad1: [c_long; 3], - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: c_ulong, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_pad2: [c_long; 2], - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_pad5: [c_long; 14], - } -} - -#[cfg(target_arch = "hexagon")] -mod arch { - use crate::os::raw::{c_int, c_long, c_uint}; - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blkcnt_t = i64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blksize_t = c_long; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type ino_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type nlink_t = c_uint; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type off_t = i64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type time_t = i64; - - #[repr(C)] - #[derive(Clone)] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad1: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad2: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad3: [c_int; 2], - } -} - -#[cfg(any( - target_arch = "loongarch64", - target_arch = "mips64", - target_arch = "mips64r6", - target_arch = "s390x", - target_arch = "sparc64", - target_arch = "riscv64", - target_arch = "riscv32" -))] -mod arch { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub use libc::{blkcnt_t, blksize_t, ino_t, nlink_t, off_t, stat, time_t}; -} - -#[cfg(target_arch = "aarch64")] -mod arch { - use crate::os::raw::{c_int, c_long}; - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blkcnt_t = i64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blksize_t = i32; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type ino_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type nlink_t = u32; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type off_t = i64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type time_t = c_long; - - #[repr(C)] - #[derive(Clone)] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad1: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad2: c_int, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __unused: [c_int; 2], - } -} - -#[cfg(any(target_arch = "x86_64", target_arch = "powerpc64"))] -mod arch { - use crate::os::raw::{c_int, c_long}; - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blkcnt_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blksize_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type ino_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type nlink_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type off_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type time_t = i64; - - #[repr(C)] - #[derive(Clone)] - #[stable(feature = "raw_ext", since = "1.1.0")] - pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __pad0: c_int, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __unused: [c_long; 3], - } -} diff --git a/library/std/src/os/macos/fs.rs b/library/std/src/os/macos/fs.rs deleted file mode 100644 index 573426d1a8646..0000000000000 --- a/library/std/src/os/macos/fs.rs +++ /dev/null @@ -1,166 +0,0 @@ -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::{self, Metadata}; -use crate::sealed::Sealed; -use crate::sys_common::{AsInner, AsInnerMut, IntoInner}; -use crate::time::SystemTime; - -#[allow(deprecated)] -use crate::os::macos::raw; - -/// OS-specific extensions to [`fs::Metadata`]. -/// -/// [`fs::Metadata`]: crate::fs::Metadata -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - /// Gain a reference to the underlying `stat` structure which contains - /// the raw information returned by the OS. - /// - /// The contents of the returned `stat` are **not** consistent across - /// Unix platforms. The `os::unix::fs::MetadataExt` trait contains the - /// cross-Unix abstractions contained within the raw stat. - #[stable(feature = "metadata_ext", since = "1.1.0")] - #[deprecated( - since = "1.8.0", - note = "deprecated in favor of the accessor \ - methods of this trait" - )] - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat; - - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_birthtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_birthtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_flags(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gen(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_lspare(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_qspare(&self) -> [u64; 2]; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat { - unsafe { &*(self.as_inner().as_inner() as *const libc::stat as *const raw::stat) } - } - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_dev as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - self.as_inner().as_inner().st_atime as i64 - } - fn st_atime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_atime_nsec as i64 - } - fn st_mtime(&self) -> i64 { - self.as_inner().as_inner().st_mtime as i64 - } - fn st_mtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_mtime_nsec as i64 - } - fn st_ctime(&self) -> i64 { - self.as_inner().as_inner().st_ctime as i64 - } - fn st_ctime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_ctime_nsec as i64 - } - fn st_birthtime(&self) -> i64 { - self.as_inner().as_inner().st_birthtime as i64 - } - fn st_birthtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_birthtime_nsec as i64 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } - fn st_gen(&self) -> u32 { - self.as_inner().as_inner().st_gen as u32 - } - fn st_flags(&self) -> u32 { - self.as_inner().as_inner().st_flags as u32 - } - fn st_lspare(&self) -> u32 { - self.as_inner().as_inner().st_lspare as u32 - } - fn st_qspare(&self) -> [u64; 2] { - let qspare = self.as_inner().as_inner().st_qspare; - [qspare[0] as u64, qspare[1] as u64] - } -} - -/// OS-specific extensions to [`fs::FileTimes`]. -#[stable(feature = "file_set_times", since = "1.75.0")] -pub trait FileTimesExt: Sealed { - /// Set the creation time of a file. - #[stable(feature = "file_set_times", since = "1.75.0")] - fn set_created(self, t: SystemTime) -> Self; -} - -#[stable(feature = "file_set_times", since = "1.75.0")] -impl FileTimesExt for fs::FileTimes { - fn set_created(mut self, t: SystemTime) -> Self { - self.as_inner_mut().set_created(t.into_inner()); - self - } -} diff --git a/library/std/src/os/macos/mod.rs b/library/std/src/os/macos/mod.rs deleted file mode 100644 index 791d703b142cf..0000000000000 --- a/library/std/src/os/macos/mod.rs +++ /dev/null @@ -1,6 +0,0 @@ -//! macOS-specific definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] - -pub mod fs; -pub mod raw; diff --git a/library/std/src/os/macos/raw.rs b/library/std/src/os/macos/raw.rs deleted file mode 100644 index 0b21f6ee5e498..0000000000000 --- a/library/std/src/os/macos/raw.rs +++ /dev/null @@ -1,83 +0,0 @@ -//! macOS-specific raw type definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![deprecated( - since = "1.8.0", - note = "these type aliases are no longer supported by \ - the standard library, the `libc` crate on \ - crates.io should be used instead for the correct \ - definitions" -)] -#![allow(deprecated)] - -use crate::os::raw::c_long; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blkcnt_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blksize_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type dev_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type ino_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type mode_t = u32; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type nlink_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type off_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type time_t = i64; - -#[stable(feature = "pthread_t", since = "1.8.0")] -pub type pthread_t = usize; - -#[repr(C)] -#[derive(Clone)] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: u16, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: u16, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_birthtime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_birthtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_flags: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gen: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_lspare: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_qspare: [i64; 2], -} diff --git a/library/std/src/os/mod.rs b/library/std/src/os/mod.rs deleted file mode 100644 index ca3584e82f918..0000000000000 --- a/library/std/src/os/mod.rs +++ /dev/null @@ -1,167 +0,0 @@ -//! OS-specific functionality. - -#![stable(feature = "os", since = "1.0.0")] -#![allow(missing_docs, nonstandard_style, missing_debug_implementations)] - -pub mod raw; - -// The code below could be written clearer using `cfg_if!`. However, the items below are -// publicly exported by `std` and external tools can have trouble analysing them because of the use -// of a macro that is not vendored by Rust and included in the toolchain. -// See https://github.com/rust-analyzer/rust-analyzer/issues/6038. - -// On certain platforms right now the "main modules" modules that are -// documented don't compile (missing things in `libc` which is empty), -// so just omit them with an empty module and add the "unstable" attribute. - -// Unix, linux, wasi and windows are handled a bit differently. -#[cfg(all( - doc, - any( - all(target_arch = "wasm32", not(target_os = "wasi")), - all(target_vendor = "fortanix", target_env = "sgx") - ) -))] -#[unstable(issue = "none", feature = "std_internals")] -pub mod unix {} -#[cfg(all( - doc, - any( - all(target_arch = "wasm32", not(target_os = "wasi")), - all(target_vendor = "fortanix", target_env = "sgx") - ) -))] -#[unstable(issue = "none", feature = "std_internals")] -pub mod linux {} -#[cfg(all( - doc, - any( - all(target_arch = "wasm32", not(target_os = "wasi")), - all(target_vendor = "fortanix", target_env = "sgx") - ) -))] -#[unstable(issue = "none", feature = "std_internals")] -pub mod wasi {} -#[cfg(all( - doc, - any( - all(target_arch = "wasm32", not(target_os = "wasi")), - all(target_vendor = "fortanix", target_env = "sgx") - ) -))] -#[unstable(issue = "none", feature = "std_internals")] -pub mod windows {} - -// unix -#[cfg(not(all( - doc, - any( - all(target_arch = "wasm32", not(target_os = "wasi")), - all(target_vendor = "fortanix", target_env = "sgx") - ) -)))] -#[cfg(all(not(target_os = "hermit"), any(unix, doc)))] -pub mod unix; - -// linux -#[cfg(not(all( - doc, - any( - all(target_arch = "wasm32", not(target_os = "wasi")), - all(target_vendor = "fortanix", target_env = "sgx") - ) -)))] -#[cfg(any(target_os = "linux", doc))] -pub mod linux; - -// wasi -#[cfg(not(all( - doc, - any( - all(target_arch = "wasm32", not(target_os = "wasi")), - all(target_vendor = "fortanix", target_env = "sgx") - ) -)))] -#[cfg(any(target_os = "wasi", doc))] -pub mod wasi; - -#[cfg(any(all(target_os = "wasi", target_env = "p2"), doc))] -pub mod wasip2; - -// windows -#[cfg(not(all( - doc, - any( - all(target_arch = "wasm32", not(target_os = "wasi")), - all(target_vendor = "fortanix", target_env = "sgx") - ) -)))] -#[cfg(any(windows, doc))] -pub mod windows; - -// Others. -#[cfg(target_os = "aix")] -pub mod aix; -#[cfg(target_os = "android")] -pub mod android; -#[cfg(target_os = "dragonfly")] -pub mod dragonfly; -#[cfg(target_os = "emscripten")] -pub mod emscripten; -#[cfg(target_os = "espidf")] -pub mod espidf; -#[cfg(all(target_vendor = "fortanix", target_env = "sgx"))] -pub mod fortanix_sgx; -#[cfg(target_os = "freebsd")] -pub mod freebsd; -#[cfg(target_os = "fuchsia")] -pub mod fuchsia; -#[cfg(target_os = "haiku")] -pub mod haiku; -#[cfg(target_os = "hermit")] -pub mod hermit; -#[cfg(target_os = "horizon")] -pub mod horizon; -#[cfg(target_os = "hurd")] -pub mod hurd; -#[cfg(target_os = "illumos")] -pub mod illumos; -#[cfg(target_os = "ios")] -pub mod ios; -#[cfg(target_os = "l4re")] -pub mod l4re; -#[cfg(target_os = "macos")] -pub mod macos; -#[cfg(target_os = "netbsd")] -pub mod netbsd; -#[cfg(target_os = "nto")] -pub mod nto; -#[cfg(target_os = "openbsd")] -pub mod openbsd; -#[cfg(target_os = "redox")] -pub mod redox; -#[cfg(target_os = "solaris")] -pub mod solaris; -#[cfg(target_os = "solid_asp3")] -pub mod solid; -#[cfg(target_os = "tvos")] -#[path = "ios/mod.rs"] -pub(crate) mod tvos; -#[cfg(target_os = "uefi")] -pub mod uefi; -#[cfg(target_os = "visionos")] -pub(crate) mod visionos; -#[cfg(target_os = "vita")] -pub mod vita; -#[cfg(target_os = "vxworks")] -pub mod vxworks; -#[cfg(target_os = "watchos")] -pub(crate) mod watchos; -#[cfg(target_os = "xous")] -pub mod xous; - -#[cfg(any(unix, target_os = "wasi", doc))] -pub mod fd; - -#[cfg(any(target_os = "linux", target_os = "android", doc))] -mod net; diff --git a/library/std/src/os/net/linux_ext/addr.rs b/library/std/src/os/net/linux_ext/addr.rs deleted file mode 100644 index aed772056e1b3..0000000000000 --- a/library/std/src/os/net/linux_ext/addr.rs +++ /dev/null @@ -1,64 +0,0 @@ -//! Linux and Android-specific extensions to socket addresses. - -use crate::os::unix::net::SocketAddr; -use crate::sealed::Sealed; - -/// Platform-specific extensions to [`SocketAddr`]. -#[stable(feature = "unix_socket_abstract", since = "1.70.0")] -pub trait SocketAddrExt: Sealed { - /// Creates a Unix socket address in the abstract namespace. - /// - /// The abstract namespace is a Linux-specific extension that allows Unix - /// sockets to be bound without creating an entry in the filesystem. - /// Abstract sockets are unaffected by filesystem layout or permissions, - /// and no cleanup is necessary when the socket is closed. - /// - /// An abstract socket address name may contain any bytes, including zero. - /// - /// # Errors - /// - /// Returns an error if the name is longer than `SUN_LEN - 1`. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::{UnixListener, SocketAddr}; - /// use std::os::linux::net::SocketAddrExt; - /// - /// fn main() -> std::io::Result<()> { - /// let addr = SocketAddr::from_abstract_name(b"hidden")?; - /// let listener = match UnixListener::bind_addr(&addr) { - /// Ok(sock) => sock, - /// Err(err) => { - /// println!("Couldn't bind: {err:?}"); - /// return Err(err); - /// } - /// }; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket_abstract", since = "1.70.0")] - fn from_abstract_name(name: N) -> crate::io::Result - where - N: AsRef<[u8]>; - - /// Returns the contents of this address if it is in the abstract namespace. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::{UnixListener, SocketAddr}; - /// use std::os::linux::net::SocketAddrExt; - /// - /// fn main() -> std::io::Result<()> { - /// let name = b"hidden"; - /// let name_addr = SocketAddr::from_abstract_name(name)?; - /// let socket = UnixListener::bind_addr(&name_addr)?; - /// let local_addr = socket.local_addr().expect("Couldn't get local address"); - /// assert_eq!(local_addr.as_abstract_name(), Some(&name[..])); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket_abstract", since = "1.70.0")] - fn as_abstract_name(&self) -> Option<&[u8]>; -} diff --git a/library/std/src/os/net/linux_ext/mod.rs b/library/std/src/os/net/linux_ext/mod.rs deleted file mode 100644 index d0979640c32ea..0000000000000 --- a/library/std/src/os/net/linux_ext/mod.rs +++ /dev/null @@ -1,15 +0,0 @@ -//! Linux and Android-specific networking functionality. - -#![doc(cfg(any(target_os = "linux", target_os = "android")))] - -#[stable(feature = "unix_socket_abstract", since = "1.70.0")] -pub(crate) mod addr; - -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -pub(crate) mod socket; - -#[unstable(feature = "tcp_quickack", issue = "96256")] -pub(crate) mod tcp; - -#[cfg(test)] -mod tests; diff --git a/library/std/src/os/net/linux_ext/socket.rs b/library/std/src/os/net/linux_ext/socket.rs deleted file mode 100644 index 4e4168f693c34..0000000000000 --- a/library/std/src/os/net/linux_ext/socket.rs +++ /dev/null @@ -1,63 +0,0 @@ -//! Linux and Android-specific socket functionality. - -use crate::io; -use crate::os::unix::net; -use crate::sealed::Sealed; -use crate::sys_common::AsInner; - -/// Linux-specific functionality for `AF_UNIX` sockets [`UnixDatagram`] -/// and [`UnixStream`]. -/// -/// [`UnixDatagram`]: net::UnixDatagram -/// [`UnixStream`]: net::UnixStream -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -pub trait UnixSocketExt: Sealed { - /// Query the current setting of socket option `SO_PASSCRED`. - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - fn passcred(&self) -> io::Result; - - /// Enable or disable socket option `SO_PASSCRED`. - /// - /// This option enables the credentials of the sending process to be - /// received as a control message in [`AncillaryData`]. - /// - /// [`AncillaryData`]: net::AncillaryData - /// - /// # Examples - /// - /// ```no_run - /// #![feature(unix_socket_ancillary_data)] - /// use std::os::linux::net::UnixSocketExt; - /// use std::os::unix::net::UnixDatagram; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixDatagram::unbound()?; - /// sock.set_passcred(true).expect("set_passcred failed"); - /// Ok(()) - /// } - /// ``` - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - fn set_passcred(&self, passcred: bool) -> io::Result<()>; -} - -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -impl UnixSocketExt for net::UnixDatagram { - fn passcred(&self) -> io::Result { - self.as_inner().passcred() - } - - fn set_passcred(&self, passcred: bool) -> io::Result<()> { - self.as_inner().set_passcred(passcred) - } -} - -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -impl UnixSocketExt for net::UnixStream { - fn passcred(&self) -> io::Result { - self.as_inner().passcred() - } - - fn set_passcred(&self, passcred: bool) -> io::Result<()> { - self.as_inner().set_passcred(passcred) - } -} diff --git a/library/std/src/os/net/linux_ext/tcp.rs b/library/std/src/os/net/linux_ext/tcp.rs deleted file mode 100644 index ff29afe7ed311..0000000000000 --- a/library/std/src/os/net/linux_ext/tcp.rs +++ /dev/null @@ -1,125 +0,0 @@ -//! Linux and Android-specific tcp extensions to primitives in the [`std::net`] module. -//! -//! [`std::net`]: crate::net - -use crate::io; -use crate::net; -use crate::sealed::Sealed; -use crate::sys_common::AsInner; - -/// Os-specific extensions for [`TcpStream`] -/// -/// [`TcpStream`]: net::TcpStream -#[unstable(feature = "tcp_quickack", issue = "96256")] -pub trait TcpStreamExt: Sealed { - /// Enable or disable `TCP_QUICKACK`. - /// - /// This flag causes Linux to eagerly send ACKs rather than delaying them. - /// Linux may reset this flag after further operations on the socket. - /// - /// See [`man 7 tcp`](https://man7.org/linux/man-pages/man7/tcp.7.html) and - /// [TCP delayed acknowledgement](https://en.wikipedia.org/wiki/TCP_delayed_acknowledgment) - /// for more information. - /// - /// # Examples - /// - /// ```no_run - /// #![feature(tcp_quickack)] - /// use std::net::TcpStream; - /// use std::os::linux::net::TcpStreamExt; - /// - /// let stream = TcpStream::connect("127.0.0.1:8080") - /// .expect("Couldn't connect to the server..."); - /// stream.set_quickack(true).expect("set_quickack call failed"); - /// ``` - #[unstable(feature = "tcp_quickack", issue = "96256")] - fn set_quickack(&self, quickack: bool) -> io::Result<()>; - - /// Gets the value of the `TCP_QUICKACK` option on this socket. - /// - /// For more information about this option, see [`TcpStreamExt::set_quickack`]. - /// - /// # Examples - /// - /// ```no_run - /// #![feature(tcp_quickack)] - /// use std::net::TcpStream; - /// use std::os::linux::net::TcpStreamExt; - /// - /// let stream = TcpStream::connect("127.0.0.1:8080") - /// .expect("Couldn't connect to the server..."); - /// stream.set_quickack(true).expect("set_quickack call failed"); - /// assert_eq!(stream.quickack().unwrap_or(false), true); - /// ``` - #[unstable(feature = "tcp_quickack", issue = "96256")] - fn quickack(&self) -> io::Result; - - /// A socket listener will be awakened solely when data arrives. - /// - /// The `accept` argument set the delay in seconds until the - /// data is available to read, reducing the number of short lived - /// connections without data to process. - /// Contrary to other platforms `SO_ACCEPTFILTER` feature equivalent, there is - /// no necessity to set it after the `listen` call. - /// - /// See [`man 7 tcp`](https://man7.org/linux/man-pages/man7/tcp.7.html) - /// - /// # Examples - /// - /// ```no run - /// #![feature(tcp_deferaccept)] - /// use std::net::TcpStream; - /// use std::os::linux::net::TcpStreamExt; - /// - /// let stream = TcpStream::connect("127.0.0.1:8080") - /// .expect("Couldn't connect to the server..."); - /// stream.set_deferaccept(1).expect("set_deferaccept call failed"); - /// ``` - #[unstable(feature = "tcp_deferaccept", issue = "119639")] - #[cfg(target_os = "linux")] - fn set_deferaccept(&self, accept: u32) -> io::Result<()>; - - /// Gets the accept delay value (in seconds) of the `TCP_DEFER_ACCEPT` option. - /// - /// For more information about this option, see [`TcpStreamExt::set_deferaccept`]. - /// - /// # Examples - /// - /// ```no_run - /// #![feature(tcp_deferaccept)] - /// use std::net::TcpStream; - /// use std::os::linux::net::TcpStreamExt; - /// - /// let stream = TcpStream::connect("127.0.0.1:8080") - /// .expect("Couldn't connect to the server..."); - /// stream.set_deferaccept(1).expect("set_deferaccept call failed"); - /// assert_eq!(stream.deferaccept().unwrap_or(0), 1); - /// ``` - #[unstable(feature = "tcp_deferaccept", issue = "119639")] - #[cfg(target_os = "linux")] - fn deferaccept(&self) -> io::Result; -} - -#[unstable(feature = "tcp_quickack", issue = "96256")] -impl Sealed for net::TcpStream {} - -#[unstable(feature = "tcp_quickack", issue = "96256")] -impl TcpStreamExt for net::TcpStream { - fn set_quickack(&self, quickack: bool) -> io::Result<()> { - self.as_inner().as_inner().set_quickack(quickack) - } - - fn quickack(&self) -> io::Result { - self.as_inner().as_inner().quickack() - } - - #[cfg(target_os = "linux")] - fn set_deferaccept(&self, accept: u32) -> io::Result<()> { - self.as_inner().as_inner().set_deferaccept(accept) - } - - #[cfg(target_os = "linux")] - fn deferaccept(&self) -> io::Result { - self.as_inner().as_inner().deferaccept() - } -} diff --git a/library/std/src/os/net/linux_ext/tests.rs b/library/std/src/os/net/linux_ext/tests.rs deleted file mode 100644 index f8dbbfc18e28e..0000000000000 --- a/library/std/src/os/net/linux_ext/tests.rs +++ /dev/null @@ -1,54 +0,0 @@ -#[test] -fn quickack() { - use crate::{ - net::{test::next_test_ip4, TcpListener, TcpStream}, - os::net::linux_ext::tcp::TcpStreamExt, - }; - - macro_rules! t { - ($e:expr) => { - match $e { - Ok(t) => t, - Err(e) => panic!("received error for `{}`: {}", stringify!($e), e), - } - }; - } - - let addr = next_test_ip4(); - let _listener = t!(TcpListener::bind(&addr)); - - let stream = t!(TcpStream::connect(&("localhost", addr.port()))); - - t!(stream.set_quickack(false)); - assert_eq!(false, t!(stream.quickack())); - t!(stream.set_quickack(true)); - assert_eq!(true, t!(stream.quickack())); - t!(stream.set_quickack(false)); - assert_eq!(false, t!(stream.quickack())); -} - -#[test] -#[cfg(target_os = "linux")] -fn deferaccept() { - use crate::{ - net::{test::next_test_ip4, TcpListener, TcpStream}, - os::net::linux_ext::tcp::TcpStreamExt, - }; - - macro_rules! t { - ($e:expr) => { - match $e { - Ok(t) => t, - Err(e) => panic!("received error for `{}`: {}", stringify!($e), e), - } - }; - } - - let addr = next_test_ip4(); - let _listener = t!(TcpListener::bind(&addr)); - let stream = t!(TcpStream::connect(&("localhost", addr.port()))); - stream.set_deferaccept(1).expect("set_deferaccept failed"); - assert_eq!(stream.deferaccept().unwrap(), 1); - stream.set_deferaccept(0).expect("set_deferaccept failed"); - assert_eq!(stream.deferaccept().unwrap(), 0); -} diff --git a/library/std/src/os/net/mod.rs b/library/std/src/os/net/mod.rs deleted file mode 100644 index b7046dd7c598c..0000000000000 --- a/library/std/src/os/net/mod.rs +++ /dev/null @@ -1,13 +0,0 @@ -//! OS-specific networking functionality. - -// See cfg macros in `library/std/src/os/mod.rs` for why these platforms must -// be special-cased during rustdoc generation. -#[cfg(not(all( - doc, - any( - all(target_arch = "wasm32", not(target_os = "wasi")), - all(target_vendor = "fortanix", target_env = "sgx") - ) -)))] -#[cfg(any(target_os = "linux", target_os = "android", doc))] -pub(super) mod linux_ext; diff --git a/library/std/src/os/netbsd/fs.rs b/library/std/src/os/netbsd/fs.rs deleted file mode 100644 index fe0be069e5e3f..0000000000000 --- a/library/std/src/os/netbsd/fs.rs +++ /dev/null @@ -1,137 +0,0 @@ -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::Metadata; -use crate::sys_common::AsInner; - -#[allow(deprecated)] -use crate::os::netbsd::raw; - -/// OS-specific extensions to [`fs::Metadata`]. -/// -/// [`fs::Metadata`]: crate::fs::Metadata -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - /// Gain a reference to the underlying `stat` structure which contains - /// the raw information returned by the OS. - /// - /// The contents of the returned `stat` are **not** consistent across - /// Unix platforms. The `os::unix::fs::MetadataExt` trait contains the - /// cross-Unix abstractions contained within the raw stat. - #[stable(feature = "metadata_ext", since = "1.1.0")] - #[deprecated( - since = "1.8.0", - note = "deprecated in favor of the accessor \ - methods of this trait" - )] - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat; - - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_birthtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_birthtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_flags(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gen(&self) -> u32; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat { - unsafe { &*(self.as_inner().as_inner() as *const libc::stat as *const raw::stat) } - } - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_dev as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - self.as_inner().as_inner().st_atime as i64 - } - fn st_atime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_atimensec as i64 - } - fn st_mtime(&self) -> i64 { - self.as_inner().as_inner().st_mtime as i64 - } - fn st_mtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_mtimensec as i64 - } - fn st_ctime(&self) -> i64 { - self.as_inner().as_inner().st_ctime as i64 - } - fn st_ctime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_ctimensec as i64 - } - fn st_birthtime(&self) -> i64 { - self.as_inner().as_inner().st_birthtime as i64 - } - fn st_birthtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_birthtimensec as i64 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } - fn st_gen(&self) -> u32 { - self.as_inner().as_inner().st_gen as u32 - } - fn st_flags(&self) -> u32 { - self.as_inner().as_inner().st_flags as u32 - } -} diff --git a/library/std/src/os/netbsd/mod.rs b/library/std/src/os/netbsd/mod.rs deleted file mode 100644 index 2f21e98a6f4cb..0000000000000 --- a/library/std/src/os/netbsd/mod.rs +++ /dev/null @@ -1,7 +0,0 @@ -//! OpenBSD-specific definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] - -pub mod fs; -pub mod net; -pub mod raw; diff --git a/library/std/src/os/netbsd/net.rs b/library/std/src/os/netbsd/net.rs deleted file mode 100644 index b9679c7b3af33..0000000000000 --- a/library/std/src/os/netbsd/net.rs +++ /dev/null @@ -1,91 +0,0 @@ -//! NetBSD-specific networking functionality. - -#![unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - -use crate::ffi::CStr; -use crate::io; -use crate::os::unix::net; -use crate::sealed::Sealed; -use crate::sys_common::AsInner; - -/// NetBSD-specific functionality for `AF_UNIX` sockets [`UnixDatagram`] -/// and [`UnixStream`]. -/// -/// [`UnixDatagram`]: net::UnixDatagram -/// [`UnixStream`]: net::UnixStream -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -pub trait UnixSocketExt: Sealed { - /// Query the current setting of socket option `LOCAL_CREDS`. - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - fn local_creds(&self) -> io::Result; - - /// Enable or disable socket option `LOCAL_CREDS`. - /// - /// This option enables the credentials of the sending process to be - /// received as a control message in [`AncillaryData`]. - /// - /// [`AncillaryData`]: net::AncillaryData - /// - /// # Examples - /// - /// ```no_run - /// #![feature(unix_socket_ancillary_data)] - /// use std::os::netbsd::net::UnixSocketExt; - /// use std::os::unix::net::UnixDatagram; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixDatagram::unbound()?; - /// sock.set_local_creds(true).expect("set_local_creds failed"); - /// Ok(()) - /// } - /// ``` - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - fn set_local_creds(&self, local_creds: bool) -> io::Result<()>; - - /// Get a filter name if one had been set previously on the socket. - #[unstable(feature = "acceptfilter", issue = "121891")] - fn acceptfilter(&self) -> io::Result<&CStr>; - - /// Set or disable a filter on the socket to filter incoming connections - /// to defer it before accept(2) - #[unstable(feature = "acceptfilter", issue = "121891")] - fn set_acceptfilter(&self, name: &CStr) -> io::Result<()>; -} - -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -impl UnixSocketExt for net::UnixDatagram { - fn local_creds(&self) -> io::Result { - self.as_inner().local_creds() - } - - fn set_local_creds(&self, local_creds: bool) -> io::Result<()> { - self.as_inner().set_local_creds(local_creds) - } - - fn acceptfilter(&self) -> io::Result<&CStr> { - self.as_inner().acceptfilter() - } - - fn set_acceptfilter(&self, name: &CStr) -> io::Result<()> { - self.as_inner().set_acceptfilter(name) - } -} - -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -impl UnixSocketExt for net::UnixStream { - fn local_creds(&self) -> io::Result { - self.as_inner().local_creds() - } - - fn set_local_creds(&self, local_creds: bool) -> io::Result<()> { - self.as_inner().set_local_creds(local_creds) - } - - fn acceptfilter(&self) -> io::Result<&CStr> { - self.as_inner().acceptfilter() - } - - fn set_acceptfilter(&self, name: &CStr) -> io::Result<()> { - self.as_inner().set_acceptfilter(name) - } -} diff --git a/library/std/src/os/netbsd/raw.rs b/library/std/src/os/netbsd/raw.rs deleted file mode 100644 index 18057291feec8..0000000000000 --- a/library/std/src/os/netbsd/raw.rs +++ /dev/null @@ -1,83 +0,0 @@ -//! NetBSD-specific raw type definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![deprecated( - since = "1.8.0", - note = "these type aliases are no longer supported by \ - the standard library, the `libc` crate on \ - crates.io should be used instead for the correct \ - definitions" -)] -#![allow(deprecated)] - -use crate::os::raw::c_long; -use crate::os::unix::raw::{gid_t, uid_t}; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blkcnt_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blksize_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type dev_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type fflags_t = u32; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type ino_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type mode_t = u32; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type nlink_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type off_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type time_t = i64; - -#[stable(feature = "pthread_t", since = "1.8.0")] -pub type pthread_t = usize; - -#[repr(C)] -#[derive(Clone)] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: uid_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: gid_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_birthtime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_birthtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_flags: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gen: u32, - st_spare: [u32; 2], -} diff --git a/library/std/src/os/nto/fs.rs b/library/std/src/os/nto/fs.rs deleted file mode 100644 index 8f915b08c9e2e..0000000000000 --- a/library/std/src/os/nto/fs.rs +++ /dev/null @@ -1,92 +0,0 @@ -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::Metadata; -use crate::sys_common::AsInner; - -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_dev as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - self.as_inner().as_inner().st_atim.tv_sec as i64 - } - fn st_atime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_atim.tv_nsec as i64 - } - fn st_mtime(&self) -> i64 { - self.as_inner().as_inner().st_mtim.tv_sec as i64 - } - fn st_mtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_mtim.tv_nsec as i64 - } - fn st_ctime(&self) -> i64 { - self.as_inner().as_inner().st_ctim.tv_sec as i64 - } - fn st_ctime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_ctim.tv_nsec as i64 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } -} diff --git a/library/std/src/os/nto/mod.rs b/library/std/src/os/nto/mod.rs deleted file mode 100644 index 3e591dace9274..0000000000000 --- a/library/std/src/os/nto/mod.rs +++ /dev/null @@ -1,4 +0,0 @@ -#![stable(feature = "raw_ext", since = "1.1.0")] - -pub mod fs; -pub(super) mod raw; diff --git a/library/std/src/os/nto/raw.rs b/library/std/src/os/nto/raw.rs deleted file mode 100644 index 90e9ad546432a..0000000000000 --- a/library/std/src/os/nto/raw.rs +++ /dev/null @@ -1,40 +0,0 @@ -#![stable(feature = "raw_ext", since = "1.1.0")] -#![deprecated( - since = "1.8.0", - note = "these type aliases are no longer supported by \ - the standard library, the `libc` crate on \ - crates.io should be used instead for the correct \ - definitions" -)] -#![allow(deprecated)] - -use crate::os::raw::c_int; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type dev_t = u32; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type mode_t = u32; - -#[stable(feature = "pthread_t", since = "1.8.0")] -pub type pthread_t = c_int; - -#[doc(inline)] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub use self::arch::{blkcnt_t, blksize_t, ino_t, nlink_t, off_t, time_t}; - -mod arch { - use crate::os::raw::c_long; - - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blkcnt_t = i64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type blksize_t = i32; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type ino_t = u64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type nlink_t = u32; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type off_t = i64; - #[stable(feature = "raw_ext", since = "1.1.0")] - pub type time_t = c_long; -} diff --git a/library/std/src/os/openbsd/fs.rs b/library/std/src/os/openbsd/fs.rs deleted file mode 100644 index b8d8d31c5b8cf..0000000000000 --- a/library/std/src/os/openbsd/fs.rs +++ /dev/null @@ -1,137 +0,0 @@ -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::Metadata; -use crate::sys_common::AsInner; - -#[allow(deprecated)] -use crate::os::openbsd::raw; - -/// OS-specific extensions to [`fs::Metadata`]. -/// -/// [`fs::Metadata`]: crate::fs::Metadata -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - /// Gain a reference to the underlying `stat` structure which contains - /// the raw information returned by the OS. - /// - /// The contents of the returned `stat` are **not** consistent across - /// Unix platforms. The `os::unix::fs::MetadataExt` trait contains the - /// cross-Unix abstractions contained within the raw stat. - #[stable(feature = "metadata_ext", since = "1.1.0")] - #[deprecated( - since = "1.8.0", - note = "deprecated in favor of the accessor \ - methods of this trait" - )] - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat; - - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_birthtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_birthtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_flags(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gen(&self) -> u32; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat { - unsafe { &*(self.as_inner().as_inner() as *const libc::stat as *const raw::stat) } - } - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_dev as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - self.as_inner().as_inner().st_atime as i64 - } - fn st_atime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_atime_nsec as i64 - } - fn st_mtime(&self) -> i64 { - self.as_inner().as_inner().st_mtime as i64 - } - fn st_mtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_mtime_nsec as i64 - } - fn st_ctime(&self) -> i64 { - self.as_inner().as_inner().st_ctime as i64 - } - fn st_ctime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_ctime_nsec as i64 - } - fn st_birthtime(&self) -> i64 { - self.as_inner().as_inner().st_birthtime as i64 - } - fn st_birthtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_birthtime_nsec as i64 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } - fn st_gen(&self) -> u32 { - self.as_inner().as_inner().st_gen as u32 - } - fn st_flags(&self) -> u32 { - self.as_inner().as_inner().st_flags as u32 - } -} diff --git a/library/std/src/os/openbsd/mod.rs b/library/std/src/os/openbsd/mod.rs deleted file mode 100644 index 497a51a1df6fd..0000000000000 --- a/library/std/src/os/openbsd/mod.rs +++ /dev/null @@ -1,6 +0,0 @@ -//! OpenBSD-specific definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] - -pub mod fs; -pub mod raw; diff --git a/library/std/src/os/openbsd/raw.rs b/library/std/src/os/openbsd/raw.rs deleted file mode 100644 index 6711fb51b1702..0000000000000 --- a/library/std/src/os/openbsd/raw.rs +++ /dev/null @@ -1,81 +0,0 @@ -//! OpenBSD-specific raw type definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![deprecated( - since = "1.8.0", - note = "these type aliases are no longer supported by \ - the standard library, the `libc` crate on \ - crates.io should be used instead for the correct \ - definitions" -)] -#![allow(deprecated)] - -use crate::os::raw::c_long; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blkcnt_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blksize_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type dev_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type fflags_t = u32; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type ino_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type mode_t = u32; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type nlink_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type off_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type time_t = i64; - -#[stable(feature = "pthread_t", since = "1.8.0")] -pub type pthread_t = usize; - -#[repr(C)] -#[derive(Clone)] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_flags: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gen: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_birthtime: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_birthtime_nsec: c_long, -} diff --git a/library/std/src/os/raw/mod.rs b/library/std/src/os/raw/mod.rs deleted file mode 100644 index 5b302e3c2c824..0000000000000 --- a/library/std/src/os/raw/mod.rs +++ /dev/null @@ -1,26 +0,0 @@ -//! Compatibility module for C platform-specific types. Use [`core::ffi`] instead. - -#![stable(feature = "raw_os", since = "1.1.0")] - -#[cfg(test)] -mod tests; - -macro_rules! alias_core_ffi { - ($($t:ident)*) => {$( - #[stable(feature = "raw_os", since = "1.1.0")] - #[doc = include_str!(concat!("../../../../core/src/ffi/", stringify!($t), ".md"))] - #[doc(cfg(all()))] - pub type $t = core::ffi::$t; - )*} -} - -alias_core_ffi! { - c_char c_schar c_uchar - c_short c_ushort - c_int c_uint - c_long c_ulong - c_longlong c_ulonglong - c_float - c_double - c_void -} diff --git a/library/std/src/os/raw/tests.rs b/library/std/src/os/raw/tests.rs deleted file mode 100644 index f41a22e1bcce4..0000000000000 --- a/library/std/src/os/raw/tests.rs +++ /dev/null @@ -1,17 +0,0 @@ -#![cfg(not(all(windows, target_env = "msvc")))] - -use crate::any::TypeId; - -macro_rules! ok { - ($($t:ident)*) => {$( - assert!(TypeId::of::() == TypeId::of::(), - "{} is wrong", stringify!($t)); - )*} -} - -#[test] -fn same() { - use crate::os::raw; - ok!(c_char c_schar c_uchar c_short c_ushort c_int c_uint c_long c_ulong - c_longlong c_ulonglong c_float c_double); -} diff --git a/library/std/src/os/redox/fs.rs b/library/std/src/os/redox/fs.rs deleted file mode 100644 index 682ca6a2c0309..0000000000000 --- a/library/std/src/os/redox/fs.rs +++ /dev/null @@ -1,382 +0,0 @@ -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::Metadata; -use crate::sys_common::AsInner; - -#[allow(deprecated)] -use crate::os::redox::raw; - -/// OS-specific extensions to [`fs::Metadata`]. -/// -/// [`fs::Metadata`]: crate::fs::Metadata -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - /// Gain a reference to the underlying `stat` structure which contains - /// the raw information returned by the OS. - /// - /// The contents of the returned [`stat`] are **not** consistent across - /// Unix platforms. The `os::unix::fs::MetadataExt` trait contains the - /// cross-Unix abstractions contained within the raw stat. - /// - /// [`stat`]: crate::os::redox::raw::stat - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::redox::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// let stat = meta.as_raw_stat(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext", since = "1.1.0")] - #[deprecated( - since = "1.8.0", - note = "deprecated in favor of the accessor \ - methods of this trait" - )] - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat; - - /// Returns the device ID on which this file resides. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::redox::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_dev()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - /// Returns the inode number. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::redox::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_ino()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - /// Returns the file type and mode. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::redox::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_mode()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - /// Returns the number of hard links to file. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::redox::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_nlink()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - /// Returns the user ID of the file owner. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::redox::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_uid()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - /// Returns the group ID of the file owner. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::redox::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_gid()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - /// Returns the device ID that this file represents. Only relevant for special file. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::redox::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_rdev()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - /// Returns the size of the file (if it is a regular file or a symbolic link) in bytes. - /// - /// The size of a symbolic link is the length of the pathname it contains, - /// without a terminating null byte. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::redox::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_size()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - /// Returns the last access time of the file, in seconds since Unix Epoch. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::redox::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_atime()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - /// Returns the last access time of the file, in nanoseconds since [`st_atime`]. - /// - /// [`st_atime`]: Self::st_atime - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::redox::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_atime_nsec()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - /// Returns the last modification time of the file, in seconds since Unix Epoch. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::redox::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_mtime()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - /// Returns the last modification time of the file, in nanoseconds since [`st_mtime`]. - /// - /// [`st_mtime`]: Self::st_mtime - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::redox::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_mtime_nsec()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - /// Returns the last status change time of the file, in seconds since Unix Epoch. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::redox::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_ctime()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - /// Returns the last status change time of the file, in nanoseconds since [`st_ctime`]. - /// - /// [`st_ctime`]: Self::st_ctime - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::redox::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_ctime_nsec()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - /// Returns the "preferred" block size for efficient filesystem I/O. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::redox::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_blksize()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - /// Returns the number of blocks allocated to the file, 512-byte units. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::io; - /// use std::os::redox::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// println!("{}", meta.st_blocks()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat { - unsafe { &*(self.as_inner().as_inner() as *const libc::stat as *const raw::stat) } - } - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_dev as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - self.as_inner().as_inner().st_atime as i64 - } - fn st_atime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_atime_nsec as i64 - } - fn st_mtime(&self) -> i64 { - self.as_inner().as_inner().st_mtime as i64 - } - fn st_mtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_mtime_nsec as i64 - } - fn st_ctime(&self) -> i64 { - self.as_inner().as_inner().st_ctime as i64 - } - fn st_ctime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_ctime_nsec as i64 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } -} diff --git a/library/std/src/os/redox/mod.rs b/library/std/src/os/redox/mod.rs deleted file mode 100644 index d786759c6111a..0000000000000 --- a/library/std/src/os/redox/mod.rs +++ /dev/null @@ -1,6 +0,0 @@ -//! Redox-specific definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] - -pub mod fs; -pub mod raw; diff --git a/library/std/src/os/redox/raw.rs b/library/std/src/os/redox/raw.rs deleted file mode 100644 index 7b1cd8ae800a4..0000000000000 --- a/library/std/src/os/redox/raw.rs +++ /dev/null @@ -1,78 +0,0 @@ -//! Redox-specific raw type definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![deprecated( - since = "1.8.0", - note = "these type aliases are no longer supported by \ - the standard library, the `libc` crate on \ - crates.io should be used instead for the correct \ - definitions" -)] -#![allow(deprecated)] - -use crate::os::raw::{c_char, c_int, c_long, c_ulong, c_void}; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type dev_t = c_long; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type gid_t = c_int; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type mode_t = c_int; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type uid_t = c_int; - -#[stable(feature = "pthread_t", since = "1.8.0")] -pub type pthread_t = *mut c_void; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blkcnt_t = c_ulong; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blksize_t = c_ulong; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type ino_t = c_ulong; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type nlink_t = c_ulong; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type off_t = c_long; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type time_t = c_long; - -#[repr(C)] -#[derive(Clone)] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: dev_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: ino_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: nlink_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: mode_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: uid_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: gid_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: dev_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: off_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: blksize_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: blkcnt_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub _pad: [c_char; 24], -} diff --git a/library/std/src/os/solaris/fs.rs b/library/std/src/os/solaris/fs.rs deleted file mode 100644 index 0931437370429..0000000000000 --- a/library/std/src/os/solaris/fs.rs +++ /dev/null @@ -1,117 +0,0 @@ -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::Metadata; -use crate::sys_common::AsInner; - -#[allow(deprecated)] -use crate::os::solaris::raw; - -/// OS-specific extensions to [`fs::Metadata`]. -/// -/// [`fs::Metadata`]: crate::fs::Metadata -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - /// Gain a reference to the underlying `stat` structure which contains - /// the raw information returned by the OS. - /// - /// The contents of the returned `stat` are **not** consistent across - /// Unix platforms. The `os::unix::fs::MetadataExt` trait contains the - /// cross-Unix abstractions contained within the raw stat. - #[stable(feature = "metadata_ext", since = "1.1.0")] - #[deprecated( - since = "1.8.0", - note = "deprecated in favor of the accessor \ - methods of this trait" - )] - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat; - - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat { - unsafe { &*(self.as_inner().as_inner() as *const libc::stat as *const raw::stat) } - } - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_dev as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - self.as_inner().as_inner().st_atime as i64 - } - fn st_atime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_atime_nsec as i64 - } - fn st_mtime(&self) -> i64 { - self.as_inner().as_inner().st_mtime as i64 - } - fn st_mtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_mtime_nsec as i64 - } - fn st_ctime(&self) -> i64 { - self.as_inner().as_inner().st_ctime as i64 - } - fn st_ctime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_ctime_nsec as i64 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } -} diff --git a/library/std/src/os/solaris/mod.rs b/library/std/src/os/solaris/mod.rs deleted file mode 100644 index e4cfd53291a6e..0000000000000 --- a/library/std/src/os/solaris/mod.rs +++ /dev/null @@ -1,6 +0,0 @@ -//! Solaris-specific definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] - -pub mod fs; -pub mod raw; diff --git a/library/std/src/os/solaris/raw.rs b/library/std/src/os/solaris/raw.rs deleted file mode 100644 index 63426c96951f5..0000000000000 --- a/library/std/src/os/solaris/raw.rs +++ /dev/null @@ -1,76 +0,0 @@ -//! Solaris-specific raw type definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![deprecated( - since = "1.8.0", - note = "these type aliases are no longer supported by \ - the standard library, the `libc` crate on \ - crates.io should be used instead for the correct \ - definitions" -)] -#![allow(deprecated)] - -use crate::os::raw::c_long; -use crate::os::unix::raw::{gid_t, uid_t}; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blkcnt_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blksize_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type dev_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type fflags_t = u32; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type ino_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type mode_t = u32; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type nlink_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type off_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type time_t = i64; - -#[stable(feature = "pthread_t", since = "1.8.0")] -pub type pthread_t = u32; - -#[repr(C)] -#[derive(Clone)] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: dev_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: ino_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: mode_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: nlink_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: uid_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: gid_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: dev_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: off_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: blksize_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: blkcnt_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub __unused: [u8; 16], -} diff --git a/library/std/src/os/solid/ffi.rs b/library/std/src/os/solid/ffi.rs deleted file mode 100644 index aaa2070a6abe9..0000000000000 --- a/library/std/src/os/solid/ffi.rs +++ /dev/null @@ -1,41 +0,0 @@ -//! SOLID-specific extension to the primitives in the `std::ffi` module -//! -//! # Examples -//! -//! ``` -//! use std::ffi::OsString; -//! use std::os::solid::ffi::OsStringExt; -//! -//! let bytes = b"foo".to_vec(); -//! -//! // OsStringExt::from_vec -//! let os_string = OsString::from_vec(bytes); -//! assert_eq!(os_string.to_str(), Some("foo")); -//! -//! // OsStringExt::into_vec -//! let bytes = os_string.into_vec(); -//! assert_eq!(bytes, b"foo"); -//! ``` -//! -//! ``` -//! use std::ffi::OsStr; -//! use std::os::solid::ffi::OsStrExt; -//! -//! let bytes = b"foo"; -//! -//! // OsStrExt::from_bytes -//! let os_str = OsStr::from_bytes(bytes); -//! assert_eq!(os_str.to_str(), Some("foo")); -//! -//! // OsStrExt::as_bytes -//! let bytes = os_str.as_bytes(); -//! assert_eq!(bytes, b"foo"); -//! ``` - -#![stable(feature = "rust1", since = "1.0.0")] - -#[path = "../unix/ffi/os_str.rs"] -mod os_str; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::os_str::{OsStrExt, OsStringExt}; diff --git a/library/std/src/os/solid/io.rs b/library/std/src/os/solid/io.rs deleted file mode 100644 index 19b4fe22093c3..0000000000000 --- a/library/std/src/os/solid/io.rs +++ /dev/null @@ -1,413 +0,0 @@ -//! SOLID-specific extensions to general I/O primitives -//! -//! Just like raw pointers, raw SOLID Sockets file descriptors point to -//! resources with dynamic lifetimes, and they can dangle if they outlive their -//! resources or be forged if they're created from invalid values. -//! -//! This module provides three types for representing raw file descriptors -//! with different ownership properties: raw, borrowed, and owned, which are -//! analogous to types used for representing pointers: -//! -//! | Type | Analogous to | -//! | ------------------ | ------------ | -//! | [`RawFd`] | `*const _` | -//! | [`BorrowedFd<'a>`] | `&'a _` | -//! | [`OwnedFd`] | `Box<_>` | -//! -//! Like raw pointers, `RawFd` values are primitive values. And in new code, -//! they should be considered unsafe to do I/O on (analogous to dereferencing -//! them). Rust did not always provide this guidance, so existing code in the -//! Rust ecosystem often doesn't mark `RawFd` usage as unsafe. Once the -//! `io_safety` feature is stable, libraries will be encouraged to migrate, -//! either by adding `unsafe` to APIs that dereference `RawFd` values, or by -//! using to `BorrowedFd` or `OwnedFd` instead. -//! -//! Like references, `BorrowedFd` values are tied to a lifetime, to ensure -//! that they don't outlive the resource they point to. These are safe to -//! use. `BorrowedFd` values may be used in APIs which provide safe access to -//! any system call except for: -//! -//! - `close`, because that would end the dynamic lifetime of the resource -//! without ending the lifetime of the file descriptor. -//! -//! - `dup2`/`dup3`, in the second argument, because this argument is -//! closed and assigned a new resource, which may break the assumptions -//! other code using that file descriptor. -//! -//! `BorrowedFd` values may be used in APIs which provide safe access to `dup` -//! system calls, so types implementing `AsFd` or `From` should not -//! assume they always have exclusive access to the underlying file -//! description. -//! -//! Like boxes, `OwnedFd` values conceptually own the resource they point to, -//! and free (close) it when they are dropped. -//! -//! [`BorrowedFd<'a>`]: crate::os::solid::io::BorrowedFd - -#![deny(unsafe_op_in_unsafe_fn)] -#![unstable(feature = "solid_ext", issue = "none")] - -use crate::fmt; -use crate::marker::PhantomData; -use crate::mem::forget; -use crate::net; -use crate::sys; -use crate::sys_common::{self, AsInner, FromInner, IntoInner}; - -/// Raw file descriptors. -pub type RawFd = i32; - -/// A borrowed SOLID Sockets file descriptor. -/// -/// This has a lifetime parameter to tie it to the lifetime of something that -/// owns the socket. -/// -/// This uses `repr(transparent)` and has the representation of a host file -/// descriptor, so it can be used in FFI in places where a socket is passed as -/// an argument, it is not captured or consumed, and it never has the value -/// `SOLID_NET_INVALID_FD`. -/// -/// This type's `.to_owned()` implementation returns another `BorrowedFd` -/// rather than an `OwnedFd`. It just makes a trivial copy of the raw -/// socket, which is then borrowed under the same lifetime. -#[derive(Copy, Clone)] -#[repr(transparent)] -#[rustc_layout_scalar_valid_range_start(0)] -// This is -2, in two's complement. -1 is `SOLID_NET_INVALID_FD`. -#[rustc_layout_scalar_valid_range_end(0xFF_FF_FF_FE)] -#[rustc_nonnull_optimization_guaranteed] -pub struct BorrowedFd<'socket> { - fd: RawFd, - _phantom: PhantomData<&'socket OwnedFd>, -} - -/// An owned SOLID Sockets file descriptor. -/// -/// This closes the file descriptor on drop. -/// -/// This uses `repr(transparent)` and has the representation of a host file -/// descriptor, so it can be used in FFI in places where a socket is passed as -/// an argument, it is not captured or consumed, and it never has the value -/// `SOLID_NET_INVALID_FD`. -#[repr(transparent)] -#[rustc_layout_scalar_valid_range_start(0)] -// This is -2, in two's complement. -1 is `SOLID_NET_INVALID_FD`. -#[rustc_layout_scalar_valid_range_end(0xFF_FF_FF_FE)] -#[rustc_nonnull_optimization_guaranteed] -pub struct OwnedFd { - fd: RawFd, -} - -impl BorrowedFd<'_> { - /// Return a `BorrowedFd` holding the given raw file descriptor. - /// - /// # Safety - /// - /// The resource pointed to by `fd` must remain open for the duration of - /// the returned `BorrowedFd`, and it must not have the value - /// `SOLID_NET_INVALID_FD`. - #[inline] - pub const unsafe fn borrow_raw(fd: RawFd) -> Self { - assert!(fd != -1 as RawFd); - // SAFETY: we just asserted that the value is in the valid range and - // isn't `-1` (the only value bigger than `0xFF_FF_FF_FE` unsigned) - unsafe { Self { fd, _phantom: PhantomData } } - } -} - -impl OwnedFd { - /// Creates a new `OwnedFd` instance that shares the same underlying file - /// description as the existing `OwnedFd` instance. - pub fn try_clone(&self) -> crate::io::Result { - self.as_fd().try_clone_to_owned() - } -} - -impl BorrowedFd<'_> { - /// Creates a new `OwnedFd` instance that shares the same underlying file - /// description as the existing `BorrowedFd` instance. - pub fn try_clone_to_owned(&self) -> crate::io::Result { - let fd = sys::net::cvt(unsafe { sys::net::netc::dup(self.as_raw_fd()) })?; - Ok(unsafe { OwnedFd::from_raw_fd(fd) }) - } -} - -impl AsRawFd for BorrowedFd<'_> { - #[inline] - fn as_raw_fd(&self) -> RawFd { - self.fd - } -} - -impl AsRawFd for OwnedFd { - #[inline] - fn as_raw_fd(&self) -> RawFd { - self.fd - } -} - -impl IntoRawFd for OwnedFd { - #[inline] - fn into_raw_fd(self) -> RawFd { - let fd = self.fd; - forget(self); - fd - } -} - -impl FromRawFd for OwnedFd { - /// Constructs a new instance of `Self` from the given raw file descriptor. - /// - /// # Safety - /// - /// The resource pointed to by `fd` must be open and suitable for assuming - /// ownership. The resource must not require any cleanup other than `close`. - #[inline] - unsafe fn from_raw_fd(fd: RawFd) -> Self { - assert_ne!(fd, -1 as RawFd); - // SAFETY: we just asserted that the value is in the valid range and - // isn't `-1` (the only value bigger than `0xFF_FF_FF_FE` unsigned) - unsafe { Self { fd } } - } -} - -impl Drop for OwnedFd { - #[inline] - fn drop(&mut self) { - unsafe { sys::net::netc::close(self.fd) }; - } -} - -impl fmt::Debug for BorrowedFd<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("BorrowedFd").field("fd", &self.fd).finish() - } -} - -impl fmt::Debug for OwnedFd { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("OwnedFd").field("fd", &self.fd).finish() - } -} - -macro_rules! impl_is_terminal { - ($($t:ty),*$(,)?) => {$( - #[unstable(feature = "sealed", issue = "none")] - impl crate::sealed::Sealed for $t {} - - #[stable(feature = "is_terminal", since = "1.70.0")] - impl crate::io::IsTerminal for $t { - #[inline] - fn is_terminal(&self) -> bool { - crate::sys::io::is_terminal(self) - } - } - )*} -} - -impl_is_terminal!(BorrowedFd<'_>, OwnedFd); - -/// A trait to borrow the SOLID Sockets file descriptor from an underlying -/// object. -pub trait AsFd { - /// Borrows the file descriptor. - fn as_fd(&self) -> BorrowedFd<'_>; -} - -impl AsFd for &T { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - T::as_fd(self) - } -} - -impl AsFd for &mut T { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - T::as_fd(self) - } -} - -impl AsFd for BorrowedFd<'_> { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - *self - } -} - -impl AsFd for OwnedFd { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - // Safety: `OwnedFd` and `BorrowedFd` have the same validity - // invariants, and the `BorrowedFd` is bounded by the lifetime - // of `&self`. - unsafe { BorrowedFd::borrow_raw(self.as_raw_fd()) } - } -} - -macro_rules! impl_owned_fd_traits { - ($($t:ident)*) => {$( - impl AsFd for net::$t { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - self.as_inner().socket().as_fd() - } - } - - impl From for OwnedFd { - #[inline] - fn from(socket: net::$t) -> OwnedFd { - socket.into_inner().into_socket().into_inner() - } - } - - impl From for net::$t { - #[inline] - fn from(owned_fd: OwnedFd) -> Self { - Self::from_inner(FromInner::from_inner(FromInner::from_inner(owned_fd))) - } - } - )*}; -} -impl_owned_fd_traits! { TcpStream TcpListener UdpSocket } - -/// This impl allows implementing traits that require `AsFd` on Arc. -/// ``` -/// # #[cfg(target_os = "solid_asp3")] mod group_cfg { -/// # use std::os::solid::io::AsFd; -/// use std::net::UdpSocket; -/// use std::sync::Arc; -/// -/// trait MyTrait: AsFd {} -/// impl MyTrait for Arc {} -/// impl MyTrait for Box {} -/// # } -/// ``` -impl AsFd for crate::sync::Arc { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - (**self).as_fd() - } -} - -impl AsFd for crate::rc::Rc { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - (**self).as_fd() - } -} - -impl AsFd for Box { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - (**self).as_fd() - } -} - -/// A trait to extract the raw SOLID Sockets file descriptor from an underlying -/// object. -pub trait AsRawFd { - /// Extracts the raw file descriptor. - /// - /// This method does **not** pass ownership of the raw file descriptor - /// to the caller. The descriptor is only guaranteed to be valid while - /// the original object has not yet been destroyed. - fn as_raw_fd(&self) -> RawFd; -} - -/// A trait to express the ability to construct an object from a raw file -/// descriptor. -pub trait FromRawFd { - /// Constructs a new instance of `Self` from the given raw file - /// descriptor. - /// - /// This function is typically used to **consume ownership** of the - /// specified file descriptor. When used in this way, the returned object - /// will take responsibility for closing it when the object goes out of - /// scope. - /// - /// However, consuming ownership is not strictly required. Use a - /// [`From::from`] implementation for an API which strictly - /// consumes ownership. - /// - /// # Safety - /// - /// The `fd` passed in must be an [owned file descriptor][io-safety]; - /// in particular, it must be open. - /// - /// [io-safety]: io#io-safety - unsafe fn from_raw_fd(fd: RawFd) -> Self; -} - -/// A trait to express the ability to consume an object and acquire ownership of -/// its raw file descriptor. -pub trait IntoRawFd { - /// Consumes this object, returning the raw underlying file descriptor. - /// - /// This function **transfers ownership** of the underlying file descriptor - /// to the caller. Callers are then the unique owners of the file descriptor - /// and must close the descriptor once it's no longer needed. - fn into_raw_fd(self) -> RawFd; -} - -#[stable(feature = "raw_fd_reflexive_traits", since = "1.48.0")] -impl AsRawFd for RawFd { - #[inline] - fn as_raw_fd(&self) -> RawFd { - *self - } -} -#[stable(feature = "raw_fd_reflexive_traits", since = "1.48.0")] -impl IntoRawFd for RawFd { - #[inline] - fn into_raw_fd(self) -> RawFd { - self - } -} -#[stable(feature = "raw_fd_reflexive_traits", since = "1.48.0")] -impl FromRawFd for RawFd { - #[inline] - unsafe fn from_raw_fd(fd: RawFd) -> RawFd { - fd - } -} - -macro_rules! impl_as_raw_fd { - ($($t:ident)*) => {$( - #[stable(feature = "rust1", since = "1.0.0")] - impl AsRawFd for net::$t { - #[inline] - fn as_raw_fd(&self) -> RawFd { - self.as_inner().socket().as_raw_fd() - } - } - )*}; -} -impl_as_raw_fd! { TcpStream TcpListener UdpSocket } - -macro_rules! impl_from_raw_fd { - ($($t:ident)*) => {$( - #[stable(feature = "from_raw_os", since = "1.1.0")] - impl FromRawFd for net::$t { - #[inline] - unsafe fn from_raw_fd(fd: RawFd) -> net::$t { - let socket = unsafe { sys::net::Socket::from_raw_fd(fd) }; - net::$t::from_inner(sys_common::net::$t::from_inner(socket)) - } - } - )*}; -} -impl_from_raw_fd! { TcpStream TcpListener UdpSocket } - -macro_rules! impl_into_raw_fd { - ($($t:ident)*) => {$( - #[stable(feature = "into_raw_os", since = "1.4.0")] - impl IntoRawFd for net::$t { - #[inline] - fn into_raw_fd(self) -> RawFd { - self.into_inner().into_socket().into_raw_fd() - } - } - )*}; -} -impl_into_raw_fd! { TcpStream TcpListener UdpSocket } diff --git a/library/std/src/os/solid/mod.rs b/library/std/src/os/solid/mod.rs deleted file mode 100644 index 0bb83c73ddf7c..0000000000000 --- a/library/std/src/os/solid/mod.rs +++ /dev/null @@ -1,17 +0,0 @@ -#![stable(feature = "rust1", since = "1.0.0")] - -pub mod ffi; -pub mod io; - -/// A prelude for conveniently writing platform-specific code. -/// -/// Includes all extension traits, and some important type definitions. -#[stable(feature = "rust1", since = "1.0.0")] -pub mod prelude { - #[doc(no_inline)] - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::ffi::{OsStrExt, OsStringExt}; - #[doc(no_inline)] - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::io::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd}; -} diff --git a/library/std/src/os/uefi/env.rs b/library/std/src/os/uefi/env.rs deleted file mode 100644 index 5d082e7c11388..0000000000000 --- a/library/std/src/os/uefi/env.rs +++ /dev/null @@ -1,92 +0,0 @@ -//! UEFI-specific extensions to the primitives in `std::env` module - -#![unstable(feature = "uefi_std", issue = "100499")] - -use crate::sync::atomic::{AtomicBool, AtomicPtr, Ordering}; -use crate::{ffi::c_void, ptr::NonNull}; - -static SYSTEM_TABLE: AtomicPtr = AtomicPtr::new(crate::ptr::null_mut()); -static IMAGE_HANDLE: AtomicPtr = AtomicPtr::new(crate::ptr::null_mut()); -// Flag to check if BootServices are still valid. -// Start with assuming that they are not available -static BOOT_SERVICES_FLAG: AtomicBool = AtomicBool::new(false); - -/// Initializes the global System Table and Image Handle pointers. -/// -/// The standard library requires access to the UEFI System Table and the Application Image Handle -/// to operate. Those are provided to UEFI Applications via their application entry point. By -/// calling `init_globals()`, those pointers are retained by the standard library for future use. -/// Thus this function must be called before any of the standard library services are used. -/// -/// The pointers are never exposed to any entity outside of this application and it is guaranteed -/// that, once the application exited, these pointers are never dereferenced again. -/// -/// Callers are required to ensure the pointers are valid for the entire lifetime of this -/// application. In particular, UEFI Boot Services must not be exited while an application with the -/// standard library is loaded. -/// -/// # SAFETY -/// Calling this function more than once will panic -pub(crate) unsafe fn init_globals(handle: NonNull, system_table: NonNull) { - IMAGE_HANDLE - .compare_exchange( - crate::ptr::null_mut(), - handle.as_ptr(), - Ordering::Release, - Ordering::Acquire, - ) - .unwrap(); - SYSTEM_TABLE - .compare_exchange( - crate::ptr::null_mut(), - system_table.as_ptr(), - Ordering::Release, - Ordering::Acquire, - ) - .unwrap(); - BOOT_SERVICES_FLAG.store(true, Ordering::Release) -} - -/// Get the SystemTable Pointer. -/// If you want to use `BootServices` then please use [`boot_services`] as it performs some -/// additional checks. -/// -/// Note: This function panics if the System Table or Image Handle is not initialized -pub fn system_table() -> NonNull { - try_system_table().unwrap() -} - -/// Get the ImageHandle Pointer. -/// -/// Note: This function panics if the System Table or Image Handle is not initialized -pub fn image_handle() -> NonNull { - try_image_handle().unwrap() -} - -/// Get the BootServices Pointer. -/// This function also checks if `ExitBootServices` has already been called. -pub fn boot_services() -> Option> { - if BOOT_SERVICES_FLAG.load(Ordering::Acquire) { - let system_table: NonNull = try_system_table()?.cast(); - let boot_services = unsafe { (*system_table.as_ptr()).boot_services }; - NonNull::new(boot_services).map(|x| x.cast()) - } else { - None - } -} - -/// Get the SystemTable Pointer. -/// This function is mostly intended for places where panic is not an option -pub(crate) fn try_system_table() -> Option> { - NonNull::new(SYSTEM_TABLE.load(Ordering::Acquire)) -} - -/// Get the SystemHandle Pointer. -/// This function is mostly intended for places where panicking is not an option -pub(crate) fn try_image_handle() -> Option> { - NonNull::new(IMAGE_HANDLE.load(Ordering::Acquire)) -} - -pub(crate) fn disable_boot_services() { - BOOT_SERVICES_FLAG.store(false, Ordering::Release) -} diff --git a/library/std/src/os/uefi/mod.rs b/library/std/src/os/uefi/mod.rs deleted file mode 100644 index 8ef05eee1f4e7..0000000000000 --- a/library/std/src/os/uefi/mod.rs +++ /dev/null @@ -1,8 +0,0 @@ -//! Platform-specific extensions to `std` for UEFI. - -#![unstable(feature = "uefi_std", issue = "100499")] -#![doc(cfg(target_os = "uefi"))] - -pub mod env; -#[path = "../windows/ffi.rs"] -pub mod ffi; diff --git a/library/std/src/os/unix/ffi/mod.rs b/library/std/src/os/unix/ffi/mod.rs deleted file mode 100644 index 5b49f50763d74..0000000000000 --- a/library/std/src/os/unix/ffi/mod.rs +++ /dev/null @@ -1,42 +0,0 @@ -//! Unix-specific extensions to primitives in the [`std::ffi`] module. -//! -//! # Examples -//! -//! ``` -//! use std::ffi::OsString; -//! use std::os::unix::ffi::OsStringExt; -//! -//! let bytes = b"foo".to_vec(); -//! -//! // OsStringExt::from_vec -//! let os_string = OsString::from_vec(bytes); -//! assert_eq!(os_string.to_str(), Some("foo")); -//! -//! // OsStringExt::into_vec -//! let bytes = os_string.into_vec(); -//! assert_eq!(bytes, b"foo"); -//! ``` -//! -//! ``` -//! use std::ffi::OsStr; -//! use std::os::unix::ffi::OsStrExt; -//! -//! let bytes = b"foo"; -//! -//! // OsStrExt::from_bytes -//! let os_str = OsStr::from_bytes(bytes); -//! assert_eq!(os_str.to_str(), Some("foo")); -//! -//! // OsStrExt::as_bytes -//! let bytes = os_str.as_bytes(); -//! assert_eq!(bytes, b"foo"); -//! ``` -//! -//! [`std::ffi`]: crate::ffi - -#![stable(feature = "rust1", since = "1.0.0")] - -mod os_str; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::os_str::{OsStrExt, OsStringExt}; diff --git a/library/std/src/os/unix/ffi/os_str.rs b/library/std/src/os/unix/ffi/os_str.rs deleted file mode 100644 index 650f712bc6eef..0000000000000 --- a/library/std/src/os/unix/ffi/os_str.rs +++ /dev/null @@ -1,70 +0,0 @@ -use crate::ffi::{OsStr, OsString}; -use crate::mem; -use crate::sealed::Sealed; -use crate::sys::os_str::Buf; -use crate::sys_common::{AsInner, FromInner, IntoInner}; - -// Note: this file is currently reused in other `std::os::{platform}::ffi` modules to reduce duplication. -// Keep this in mind when applying changes to this file that only apply to `unix`. - -/// Platform-specific extensions to [`OsString`]. -/// -/// This trait is sealed: it cannot be implemented outside the standard library. -/// This is so that future additional methods are not breaking changes. -#[stable(feature = "rust1", since = "1.0.0")] -pub trait OsStringExt: Sealed { - /// Creates an [`OsString`] from a byte vector. - /// - /// See the module documentation for an example. - #[stable(feature = "rust1", since = "1.0.0")] - fn from_vec(vec: Vec) -> Self; - - /// Yields the underlying byte vector of this [`OsString`]. - /// - /// See the module documentation for an example. - #[stable(feature = "rust1", since = "1.0.0")] - fn into_vec(self) -> Vec; -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl OsStringExt for OsString { - #[inline] - fn from_vec(vec: Vec) -> OsString { - FromInner::from_inner(Buf { inner: vec }) - } - #[inline] - fn into_vec(self) -> Vec { - self.into_inner().inner - } -} - -/// Platform-specific extensions to [`OsStr`]. -/// -/// This trait is sealed: it cannot be implemented outside the standard library. -/// This is so that future additional methods are not breaking changes. -#[stable(feature = "rust1", since = "1.0.0")] -pub trait OsStrExt: Sealed { - #[stable(feature = "rust1", since = "1.0.0")] - /// Creates an [`OsStr`] from a byte slice. - /// - /// See the module documentation for an example. - fn from_bytes(slice: &[u8]) -> &Self; - - /// Gets the underlying byte view of the [`OsStr`] slice. - /// - /// See the module documentation for an example. - #[stable(feature = "rust1", since = "1.0.0")] - fn as_bytes(&self) -> &[u8]; -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl OsStrExt for OsStr { - #[inline] - fn from_bytes(slice: &[u8]) -> &OsStr { - unsafe { mem::transmute(slice) } - } - #[inline] - fn as_bytes(&self) -> &[u8] { - &self.as_inner().inner - } -} diff --git a/library/std/src/os/unix/fs.rs b/library/std/src/os/unix/fs.rs deleted file mode 100644 index 970023d8cf19e..0000000000000 --- a/library/std/src/os/unix/fs.rs +++ /dev/null @@ -1,1070 +0,0 @@ -//! Unix-specific extensions to primitives in the [`std::fs`] module. -//! -//! [`std::fs`]: crate::fs - -#![stable(feature = "rust1", since = "1.0.0")] - -use super::platform::fs::MetadataExt as _; -use crate::fs::{self, OpenOptions, Permissions}; -use crate::io; -use crate::os::unix::io::{AsFd, AsRawFd}; -use crate::path::Path; -use crate::sys; -use crate::sys_common::{AsInner, AsInnerMut, FromInner}; -// Used for `File::read` on intra-doc links -use crate::ffi::OsStr; -use crate::sealed::Sealed; -#[allow(unused_imports)] -use io::{Read, Write}; - -// Tests for this module -#[cfg(test)] -mod tests; - -/// Unix-specific extensions to [`fs::File`]. -#[stable(feature = "file_offset", since = "1.15.0")] -pub trait FileExt { - /// Reads a number of bytes starting from a given offset. - /// - /// Returns the number of bytes read. - /// - /// The offset is relative to the start of the file and thus independent - /// from the current cursor. - /// - /// The current file cursor is not affected by this function. - /// - /// Note that similar to [`File::read`], it is not an error to return with a - /// short read. - /// - /// [`File::read`]: fs::File::read - /// - /// # Examples - /// - /// ```no_run - /// use std::io; - /// use std::fs::File; - /// use std::os::unix::prelude::FileExt; - /// - /// fn main() -> io::Result<()> { - /// let mut buf = [0u8; 8]; - /// let file = File::open("foo.txt")?; - /// - /// // We now read 8 bytes from the offset 10. - /// let num_bytes_read = file.read_at(&mut buf, 10)?; - /// println!("read {num_bytes_read} bytes: {buf:?}"); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "file_offset", since = "1.15.0")] - fn read_at(&self, buf: &mut [u8], offset: u64) -> io::Result; - - /// Like `read_at`, except that it reads into a slice of buffers. - /// - /// Data is copied to fill each buffer in order, with the final buffer - /// written to possibly being only partially filled. This method must behave - /// equivalently to a single call to read with concatenated buffers. - #[unstable(feature = "unix_file_vectored_at", issue = "89517")] - fn read_vectored_at(&self, bufs: &mut [io::IoSliceMut<'_>], offset: u64) -> io::Result { - io::default_read_vectored(|b| self.read_at(b, offset), bufs) - } - - /// Reads the exact number of bytes required to fill `buf` from the given offset. - /// - /// The offset is relative to the start of the file and thus independent - /// from the current cursor. - /// - /// The current file cursor is not affected by this function. - /// - /// Similar to [`io::Read::read_exact`] but uses [`read_at`] instead of `read`. - /// - /// [`read_at`]: FileExt::read_at - /// - /// # Errors - /// - /// If this function encounters an error of the kind - /// [`io::ErrorKind::Interrupted`] then the error is ignored and the operation - /// will continue. - /// - /// If this function encounters an "end of file" before completely filling - /// the buffer, it returns an error of the kind [`io::ErrorKind::UnexpectedEof`]. - /// The contents of `buf` are unspecified in this case. - /// - /// If any other read error is encountered then this function immediately - /// returns. The contents of `buf` are unspecified in this case. - /// - /// If this function returns an error, it is unspecified how many bytes it - /// has read, but it will never read more than would be necessary to - /// completely fill the buffer. - /// - /// # Examples - /// - /// ```no_run - /// use std::io; - /// use std::fs::File; - /// use std::os::unix::prelude::FileExt; - /// - /// fn main() -> io::Result<()> { - /// let mut buf = [0u8; 8]; - /// let file = File::open("foo.txt")?; - /// - /// // We now read exactly 8 bytes from the offset 10. - /// file.read_exact_at(&mut buf, 10)?; - /// println!("read {} bytes: {:?}", buf.len(), buf); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rw_exact_all_at", since = "1.33.0")] - fn read_exact_at(&self, mut buf: &mut [u8], mut offset: u64) -> io::Result<()> { - while !buf.is_empty() { - match self.read_at(buf, offset) { - Ok(0) => break, - Ok(n) => { - let tmp = buf; - buf = &mut tmp[n..]; - offset += n as u64; - } - Err(ref e) if e.is_interrupted() => {} - Err(e) => return Err(e), - } - } - if !buf.is_empty() { Err(io::Error::READ_EXACT_EOF) } else { Ok(()) } - } - - /// Writes a number of bytes starting from a given offset. - /// - /// Returns the number of bytes written. - /// - /// The offset is relative to the start of the file and thus independent - /// from the current cursor. - /// - /// The current file cursor is not affected by this function. - /// - /// When writing beyond the end of the file, the file is appropriately - /// extended and the intermediate bytes are initialized with the value 0. - /// - /// Note that similar to [`File::write`], it is not an error to return a - /// short write. - /// - /// # Bug - /// On some systems, `write_at` utilises [`pwrite64`] to write to files. - /// However, this syscall has a [bug] where files opened with the `O_APPEND` - /// flag fail to respect the offset parameter, always appending to the end - /// of the file instead. - /// - /// It is possible to inadvertently set this flag, like in the example below. - /// Therefore, it is important to be vigilant while changing options to mitigate - /// unexpected behaviour. - /// - /// ```no_run - /// use std::fs::File; - /// use std::io; - /// use std::os::unix::prelude::FileExt; - /// - /// fn main() -> io::Result<()> { - /// // Open a file with the append option (sets the `O_APPEND` flag) - /// let file = File::options().append(true).open("foo.txt")?; - /// - /// // We attempt to write at offset 10; instead appended to EOF - /// file.write_at(b"sushi", 10)?; - /// - /// // foo.txt is 5 bytes long instead of 15 - /// Ok(()) - /// } - /// ``` - /// - /// [`File::write`]: fs::File::write - /// [`pwrite64`]: https://man7.org/linux/man-pages/man2/pwrite.2.html - /// [bug]: https://man7.org/linux/man-pages/man2/pwrite.2.html#BUGS - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::File; - /// use std::io; - /// use std::os::unix::prelude::FileExt; - /// - /// fn main() -> io::Result<()> { - /// let file = File::create("foo.txt")?; - /// - /// // We now write at the offset 10. - /// file.write_at(b"sushi", 10)?; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "file_offset", since = "1.15.0")] - fn write_at(&self, buf: &[u8], offset: u64) -> io::Result; - - /// Like `write_at`, except that it writes from a slice of buffers. - /// - /// Data is copied from each buffer in order, with the final buffer read - /// from possibly being only partially consumed. This method must behave as - /// a call to `write_at` with the buffers concatenated would. - #[unstable(feature = "unix_file_vectored_at", issue = "89517")] - fn write_vectored_at(&self, bufs: &[io::IoSlice<'_>], offset: u64) -> io::Result { - io::default_write_vectored(|b| self.write_at(b, offset), bufs) - } - - /// Attempts to write an entire buffer starting from a given offset. - /// - /// The offset is relative to the start of the file and thus independent - /// from the current cursor. - /// - /// The current file cursor is not affected by this function. - /// - /// This method will continuously call [`write_at`] until there is no more data - /// to be written or an error of non-[`io::ErrorKind::Interrupted`] kind is - /// returned. This method will not return until the entire buffer has been - /// successfully written or such an error occurs. The first error that is - /// not of [`io::ErrorKind::Interrupted`] kind generated from this method will be - /// returned. - /// - /// # Errors - /// - /// This function will return the first error of - /// non-[`io::ErrorKind::Interrupted`] kind that [`write_at`] returns. - /// - /// [`write_at`]: FileExt::write_at - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::File; - /// use std::io; - /// use std::os::unix::prelude::FileExt; - /// - /// fn main() -> io::Result<()> { - /// let file = File::open("foo.txt")?; - /// - /// // We now write at the offset 10. - /// file.write_all_at(b"sushi", 10)?; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "rw_exact_all_at", since = "1.33.0")] - fn write_all_at(&self, mut buf: &[u8], mut offset: u64) -> io::Result<()> { - while !buf.is_empty() { - match self.write_at(buf, offset) { - Ok(0) => { - return Err(io::Error::WRITE_ALL_EOF); - } - Ok(n) => { - buf = &buf[n..]; - offset += n as u64 - } - Err(ref e) if e.is_interrupted() => {} - Err(e) => return Err(e), - } - } - Ok(()) - } -} - -#[stable(feature = "file_offset", since = "1.15.0")] -impl FileExt for fs::File { - fn read_at(&self, buf: &mut [u8], offset: u64) -> io::Result { - self.as_inner().read_at(buf, offset) - } - fn read_vectored_at(&self, bufs: &mut [io::IoSliceMut<'_>], offset: u64) -> io::Result { - self.as_inner().read_vectored_at(bufs, offset) - } - fn write_at(&self, buf: &[u8], offset: u64) -> io::Result { - self.as_inner().write_at(buf, offset) - } - fn write_vectored_at(&self, bufs: &[io::IoSlice<'_>], offset: u64) -> io::Result { - self.as_inner().write_vectored_at(bufs, offset) - } -} - -/// Unix-specific extensions to [`fs::Permissions`]. -#[stable(feature = "fs_ext", since = "1.1.0")] -pub trait PermissionsExt { - /// Returns the underlying raw `st_mode` bits that contain the standard - /// Unix permissions for this file. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::File; - /// use std::os::unix::fs::PermissionsExt; - /// - /// fn main() -> std::io::Result<()> { - /// let f = File::create("foo.txt")?; - /// let metadata = f.metadata()?; - /// let permissions = metadata.permissions(); - /// - /// println!("permissions: {:o}", permissions.mode()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "fs_ext", since = "1.1.0")] - fn mode(&self) -> u32; - - /// Sets the underlying raw bits for this set of permissions. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::File; - /// use std::os::unix::fs::PermissionsExt; - /// - /// fn main() -> std::io::Result<()> { - /// let f = File::create("foo.txt")?; - /// let metadata = f.metadata()?; - /// let mut permissions = metadata.permissions(); - /// - /// permissions.set_mode(0o644); // Read/write for owner and read for others. - /// assert_eq!(permissions.mode(), 0o644); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "fs_ext", since = "1.1.0")] - fn set_mode(&mut self, mode: u32); - - /// Creates a new instance of `Permissions` from the given set of Unix - /// permission bits. - /// - /// # Examples - /// - /// ``` - /// use std::fs::Permissions; - /// use std::os::unix::fs::PermissionsExt; - /// - /// // Read/write for owner and read for others. - /// let permissions = Permissions::from_mode(0o644); - /// assert_eq!(permissions.mode(), 0o644); - /// ``` - #[stable(feature = "fs_ext", since = "1.1.0")] - fn from_mode(mode: u32) -> Self; -} - -#[stable(feature = "fs_ext", since = "1.1.0")] -impl PermissionsExt for Permissions { - fn mode(&self) -> u32 { - self.as_inner().mode() - } - - fn set_mode(&mut self, mode: u32) { - *self = Permissions::from_inner(FromInner::from_inner(mode)); - } - - fn from_mode(mode: u32) -> Permissions { - Permissions::from_inner(FromInner::from_inner(mode)) - } -} - -/// Unix-specific extensions to [`fs::OpenOptions`]. -#[stable(feature = "fs_ext", since = "1.1.0")] -pub trait OpenOptionsExt { - /// Sets the mode bits that a new file will be created with. - /// - /// If a new file is created as part of an `OpenOptions::open` call then this - /// specified `mode` will be used as the permission bits for the new file. - /// If no `mode` is set, the default of `0o666` will be used. - /// The operating system masks out bits with the system's `umask`, to produce - /// the final permissions. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::OpenOptions; - /// use std::os::unix::fs::OpenOptionsExt; - /// - /// # fn main() { - /// let mut options = OpenOptions::new(); - /// options.mode(0o644); // Give read/write for owner and read for others. - /// let file = options.open("foo.txt"); - /// # } - /// ``` - #[stable(feature = "fs_ext", since = "1.1.0")] - fn mode(&mut self, mode: u32) -> &mut Self; - - /// Pass custom flags to the `flags` argument of `open`. - /// - /// The bits that define the access mode are masked out with `O_ACCMODE`, to - /// ensure they do not interfere with the access mode set by Rusts options. - /// - /// Custom flags can only set flags, not remove flags set by Rusts options. - /// This options overwrites any previously set custom flags. - /// - /// # Examples - /// - /// ```no_run - /// # #![feature(rustc_private)] - /// use std::fs::OpenOptions; - /// use std::os::unix::fs::OpenOptionsExt; - /// - /// # fn main() { - /// let mut options = OpenOptions::new(); - /// options.write(true); - /// if cfg!(unix) { - /// options.custom_flags(libc::O_NOFOLLOW); - /// } - /// let file = options.open("foo.txt"); - /// # } - /// ``` - #[stable(feature = "open_options_ext", since = "1.10.0")] - fn custom_flags(&mut self, flags: i32) -> &mut Self; -} - -#[stable(feature = "fs_ext", since = "1.1.0")] -impl OpenOptionsExt for OpenOptions { - fn mode(&mut self, mode: u32) -> &mut OpenOptions { - self.as_inner_mut().mode(mode); - self - } - - fn custom_flags(&mut self, flags: i32) -> &mut OpenOptions { - self.as_inner_mut().custom_flags(flags); - self - } -} - -/// Unix-specific extensions to [`fs::Metadata`]. -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - /// Returns the ID of the device containing the file. - /// - /// # Examples - /// - /// ```no_run - /// use std::io; - /// use std::fs; - /// use std::os::unix::fs::MetadataExt; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// let dev_id = meta.dev(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext", since = "1.1.0")] - fn dev(&self) -> u64; - /// Returns the inode number. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::os::unix::fs::MetadataExt; - /// use std::io; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// let inode = meta.ino(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext", since = "1.1.0")] - fn ino(&self) -> u64; - /// Returns the rights applied to this file. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::os::unix::fs::MetadataExt; - /// use std::io; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// let mode = meta.mode(); - /// let user_has_write_access = mode & 0o200; - /// let user_has_read_write_access = mode & 0o600; - /// let group_has_read_access = mode & 0o040; - /// let others_have_exec_access = mode & 0o001; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext", since = "1.1.0")] - fn mode(&self) -> u32; - /// Returns the number of hard links pointing to this file. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::os::unix::fs::MetadataExt; - /// use std::io; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// let nb_hard_links = meta.nlink(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext", since = "1.1.0")] - fn nlink(&self) -> u64; - /// Returns the user ID of the owner of this file. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::os::unix::fs::MetadataExt; - /// use std::io; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// let user_id = meta.uid(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext", since = "1.1.0")] - fn uid(&self) -> u32; - /// Returns the group ID of the owner of this file. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::os::unix::fs::MetadataExt; - /// use std::io; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// let group_id = meta.gid(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext", since = "1.1.0")] - fn gid(&self) -> u32; - /// Returns the device ID of this file (if it is a special one). - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::os::unix::fs::MetadataExt; - /// use std::io; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// let device_id = meta.rdev(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext", since = "1.1.0")] - fn rdev(&self) -> u64; - /// Returns the total size of this file in bytes. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::os::unix::fs::MetadataExt; - /// use std::io; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// let file_size = meta.size(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext", since = "1.1.0")] - fn size(&self) -> u64; - /// Returns the last access time of the file, in seconds since Unix Epoch. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::os::unix::fs::MetadataExt; - /// use std::io; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// let last_access_time = meta.atime(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext", since = "1.1.0")] - fn atime(&self) -> i64; - /// Returns the last access time of the file, in nanoseconds since [`atime`]. - /// - /// [`atime`]: MetadataExt::atime - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::os::unix::fs::MetadataExt; - /// use std::io; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// let nano_last_access_time = meta.atime_nsec(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext", since = "1.1.0")] - fn atime_nsec(&self) -> i64; - /// Returns the last modification time of the file, in seconds since Unix Epoch. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::os::unix::fs::MetadataExt; - /// use std::io; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// let last_modification_time = meta.mtime(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext", since = "1.1.0")] - fn mtime(&self) -> i64; - /// Returns the last modification time of the file, in nanoseconds since [`mtime`]. - /// - /// [`mtime`]: MetadataExt::mtime - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::os::unix::fs::MetadataExt; - /// use std::io; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// let nano_last_modification_time = meta.mtime_nsec(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext", since = "1.1.0")] - fn mtime_nsec(&self) -> i64; - /// Returns the last status change time of the file, in seconds since Unix Epoch. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::os::unix::fs::MetadataExt; - /// use std::io; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// let last_status_change_time = meta.ctime(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext", since = "1.1.0")] - fn ctime(&self) -> i64; - /// Returns the last status change time of the file, in nanoseconds since [`ctime`]. - /// - /// [`ctime`]: MetadataExt::ctime - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::os::unix::fs::MetadataExt; - /// use std::io; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// let nano_last_status_change_time = meta.ctime_nsec(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext", since = "1.1.0")] - fn ctime_nsec(&self) -> i64; - /// Returns the block size for filesystem I/O. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::os::unix::fs::MetadataExt; - /// use std::io; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// let block_size = meta.blksize(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext", since = "1.1.0")] - fn blksize(&self) -> u64; - /// Returns the number of blocks allocated to the file, in 512-byte units. - /// - /// Please note that this may be smaller than `st_size / 512` when the file has holes. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::os::unix::fs::MetadataExt; - /// use std::io; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("some_file")?; - /// let blocks = meta.blocks(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext", since = "1.1.0")] - fn blocks(&self) -> u64; - #[cfg(target_os = "vxworks")] - #[stable(feature = "metadata_ext", since = "1.1.0")] - fn attrib(&self) -> u8; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for fs::Metadata { - fn dev(&self) -> u64 { - self.st_dev() - } - fn ino(&self) -> u64 { - self.st_ino() - } - fn mode(&self) -> u32 { - self.st_mode() - } - fn nlink(&self) -> u64 { - self.st_nlink() - } - fn uid(&self) -> u32 { - self.st_uid() - } - fn gid(&self) -> u32 { - self.st_gid() - } - fn rdev(&self) -> u64 { - self.st_rdev() - } - fn size(&self) -> u64 { - self.st_size() - } - fn atime(&self) -> i64 { - self.st_atime() - } - fn atime_nsec(&self) -> i64 { - self.st_atime_nsec() - } - fn mtime(&self) -> i64 { - self.st_mtime() - } - fn mtime_nsec(&self) -> i64 { - self.st_mtime_nsec() - } - fn ctime(&self) -> i64 { - self.st_ctime() - } - fn ctime_nsec(&self) -> i64 { - self.st_ctime_nsec() - } - fn blksize(&self) -> u64 { - self.st_blksize() - } - fn blocks(&self) -> u64 { - self.st_blocks() - } - #[cfg(target_os = "vxworks")] - fn attrib(&self) -> u8 { - self.st_attrib() - } -} - -/// Unix-specific extensions for [`fs::FileType`]. -/// -/// Adds support for special Unix file types such as block/character devices, -/// pipes, and sockets. -#[stable(feature = "file_type_ext", since = "1.5.0")] -pub trait FileTypeExt { - /// Returns `true` if this file type is a block device. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::os::unix::fs::FileTypeExt; - /// use std::io; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("block_device_file")?; - /// let file_type = meta.file_type(); - /// assert!(file_type.is_block_device()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "file_type_ext", since = "1.5.0")] - fn is_block_device(&self) -> bool; - /// Returns `true` if this file type is a char device. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::os::unix::fs::FileTypeExt; - /// use std::io; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("char_device_file")?; - /// let file_type = meta.file_type(); - /// assert!(file_type.is_char_device()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "file_type_ext", since = "1.5.0")] - fn is_char_device(&self) -> bool; - /// Returns `true` if this file type is a fifo. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::os::unix::fs::FileTypeExt; - /// use std::io; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("fifo_file")?; - /// let file_type = meta.file_type(); - /// assert!(file_type.is_fifo()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "file_type_ext", since = "1.5.0")] - fn is_fifo(&self) -> bool; - /// Returns `true` if this file type is a socket. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs; - /// use std::os::unix::fs::FileTypeExt; - /// use std::io; - /// - /// fn main() -> io::Result<()> { - /// let meta = fs::metadata("unix.socket")?; - /// let file_type = meta.file_type(); - /// assert!(file_type.is_socket()); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "file_type_ext", since = "1.5.0")] - fn is_socket(&self) -> bool; -} - -#[stable(feature = "file_type_ext", since = "1.5.0")] -impl FileTypeExt for fs::FileType { - fn is_block_device(&self) -> bool { - self.as_inner().is(libc::S_IFBLK) - } - fn is_char_device(&self) -> bool { - self.as_inner().is(libc::S_IFCHR) - } - fn is_fifo(&self) -> bool { - self.as_inner().is(libc::S_IFIFO) - } - fn is_socket(&self) -> bool { - self.as_inner().is(libc::S_IFSOCK) - } -} - -/// Unix-specific extension methods for [`fs::DirEntry`]. -#[stable(feature = "dir_entry_ext", since = "1.1.0")] -pub trait DirEntryExt { - /// Returns the underlying `d_ino` field in the contained `dirent` - /// structure. - /// - /// # Examples - /// - /// ``` - /// use std::fs; - /// use std::os::unix::fs::DirEntryExt; - /// - /// if let Ok(entries) = fs::read_dir(".") { - /// for entry in entries { - /// if let Ok(entry) = entry { - /// // Here, `entry` is a `DirEntry`. - /// println!("{:?}: {}", entry.file_name(), entry.ino()); - /// } - /// } - /// } - /// ``` - #[stable(feature = "dir_entry_ext", since = "1.1.0")] - fn ino(&self) -> u64; -} - -#[stable(feature = "dir_entry_ext", since = "1.1.0")] -impl DirEntryExt for fs::DirEntry { - fn ino(&self) -> u64 { - self.as_inner().ino() - } -} - -/// Sealed Unix-specific extension methods for [`fs::DirEntry`]. -#[unstable(feature = "dir_entry_ext2", issue = "85573")] -pub trait DirEntryExt2: Sealed { - /// Returns a reference to the underlying `OsStr` of this entry's filename. - /// - /// # Examples - /// - /// ``` - /// #![feature(dir_entry_ext2)] - /// use std::os::unix::fs::DirEntryExt2; - /// use std::{fs, io}; - /// - /// fn main() -> io::Result<()> { - /// let mut entries = fs::read_dir(".")?.collect::, io::Error>>()?; - /// entries.sort_unstable_by(|a, b| a.file_name_ref().cmp(b.file_name_ref())); - /// - /// for p in entries { - /// println!("{p:?}"); - /// } - /// - /// Ok(()) - /// } - /// ``` - fn file_name_ref(&self) -> &OsStr; -} - -/// Allows extension traits within `std`. -#[unstable(feature = "sealed", issue = "none")] -impl Sealed for fs::DirEntry {} - -#[unstable(feature = "dir_entry_ext2", issue = "85573")] -impl DirEntryExt2 for fs::DirEntry { - fn file_name_ref(&self) -> &OsStr { - self.as_inner().file_name_os_str() - } -} - -/// Creates a new symbolic link on the filesystem. -/// -/// The `link` path will be a symbolic link pointing to the `original` path. -/// -/// # Examples -/// -/// ```no_run -/// use std::os::unix::fs; -/// -/// fn main() -> std::io::Result<()> { -/// fs::symlink("a.txt", "b.txt")?; -/// Ok(()) -/// } -/// ``` -#[stable(feature = "symlink", since = "1.1.0")] -pub fn symlink, Q: AsRef>(original: P, link: Q) -> io::Result<()> { - sys::fs::symlink(original.as_ref(), link.as_ref()) -} - -/// Unix-specific extensions to [`fs::DirBuilder`]. -#[stable(feature = "dir_builder", since = "1.6.0")] -pub trait DirBuilderExt { - /// Sets the mode to create new directories with. This option defaults to - /// 0o777. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::DirBuilder; - /// use std::os::unix::fs::DirBuilderExt; - /// - /// let mut builder = DirBuilder::new(); - /// builder.mode(0o755); - /// ``` - #[stable(feature = "dir_builder", since = "1.6.0")] - fn mode(&mut self, mode: u32) -> &mut Self; -} - -#[stable(feature = "dir_builder", since = "1.6.0")] -impl DirBuilderExt for fs::DirBuilder { - fn mode(&mut self, mode: u32) -> &mut fs::DirBuilder { - self.as_inner_mut().set_mode(mode); - self - } -} - -/// Change the owner and group of the specified path. -/// -/// Specifying either the uid or gid as `None` will leave it unchanged. -/// -/// Changing the owner typically requires privileges, such as root or a specific capability. -/// Changing the group typically requires either being the owner and a member of the group, or -/// having privileges. -/// -/// If called on a symbolic link, this will change the owner and group of the link target. To -/// change the owner and group of the link itself, see [`lchown`]. -/// -/// # Examples -/// -/// ```no_run -/// use std::os::unix::fs; -/// -/// fn main() -> std::io::Result<()> { -/// fs::chown("/sandbox", Some(0), Some(0))?; -/// Ok(()) -/// } -/// ``` -#[stable(feature = "unix_chown", since = "1.73.0")] -pub fn chown>(dir: P, uid: Option, gid: Option) -> io::Result<()> { - sys::fs::chown(dir.as_ref(), uid.unwrap_or(u32::MAX), gid.unwrap_or(u32::MAX)) -} - -/// Change the owner and group of the file referenced by the specified open file descriptor. -/// -/// For semantics and required privileges, see [`chown`]. -/// -/// # Examples -/// -/// ```no_run -/// use std::os::unix::fs; -/// -/// fn main() -> std::io::Result<()> { -/// let f = std::fs::File::open("/file")?; -/// fs::fchown(&f, Some(0), Some(0))?; -/// Ok(()) -/// } -/// ``` -#[stable(feature = "unix_chown", since = "1.73.0")] -pub fn fchown(fd: F, uid: Option, gid: Option) -> io::Result<()> { - sys::fs::fchown(fd.as_fd().as_raw_fd(), uid.unwrap_or(u32::MAX), gid.unwrap_or(u32::MAX)) -} - -/// Change the owner and group of the specified path, without dereferencing symbolic links. -/// -/// Identical to [`chown`], except that if called on a symbolic link, this will change the owner -/// and group of the link itself rather than the owner and group of the link target. -/// -/// # Examples -/// -/// ```no_run -/// use std::os::unix::fs; -/// -/// fn main() -> std::io::Result<()> { -/// fs::lchown("/symlink", Some(0), Some(0))?; -/// Ok(()) -/// } -/// ``` -#[stable(feature = "unix_chown", since = "1.73.0")] -pub fn lchown>(dir: P, uid: Option, gid: Option) -> io::Result<()> { - sys::fs::lchown(dir.as_ref(), uid.unwrap_or(u32::MAX), gid.unwrap_or(u32::MAX)) -} - -/// Change the root directory of the current process to the specified path. -/// -/// This typically requires privileges, such as root or a specific capability. -/// -/// This does not change the current working directory; you should call -/// [`std::env::set_current_dir`][`crate::env::set_current_dir`] afterwards. -/// -/// # Examples -/// -/// ```no_run -/// use std::os::unix::fs; -/// -/// fn main() -> std::io::Result<()> { -/// fs::chroot("/sandbox")?; -/// std::env::set_current_dir("/")?; -/// // continue working in sandbox -/// Ok(()) -/// } -/// ``` -#[stable(feature = "unix_chroot", since = "1.56.0")] -#[cfg(not(any(target_os = "fuchsia", target_os = "vxworks")))] -pub fn chroot>(dir: P) -> io::Result<()> { - sys::fs::chroot(dir.as_ref()) -} diff --git a/library/std/src/os/unix/fs/tests.rs b/library/std/src/os/unix/fs/tests.rs deleted file mode 100644 index 67f607bd46837..0000000000000 --- a/library/std/src/os/unix/fs/tests.rs +++ /dev/null @@ -1,57 +0,0 @@ -use super::*; - -#[test] -fn read_vectored_at() { - let msg = b"preadv is working!"; - let dir = crate::sys_common::io::test::tmpdir(); - - let filename = dir.join("preadv.txt"); - { - let mut file = fs::File::create(&filename).unwrap(); - file.write_all(msg).unwrap(); - } - { - let file = fs::File::open(&filename).unwrap(); - let mut buf0 = [0; 4]; - let mut buf1 = [0; 3]; - - let mut iovec = [io::IoSliceMut::new(&mut buf0), io::IoSliceMut::new(&mut buf1)]; - - let n = file.read_vectored_at(&mut iovec, 4).unwrap(); - - assert!(n == 4 || n == 7); - assert_eq!(&buf0, b"dv i"); - - if n == 7 { - assert_eq!(&buf1, b"s w"); - } - } -} - -#[test] -fn write_vectored_at() { - let msg = b"pwritev is not working!"; - let dir = crate::sys_common::io::test::tmpdir(); - - let filename = dir.join("preadv.txt"); - { - let mut file = fs::File::create(&filename).unwrap(); - file.write_all(msg).unwrap(); - } - let expected = { - let file = fs::File::options().write(true).open(&filename).unwrap(); - let buf0 = b" "; - let buf1 = b"great "; - - let iovec = [io::IoSlice::new(buf0), io::IoSlice::new(buf1)]; - - let n = file.write_vectored_at(&iovec, 11).unwrap(); - - assert!(n == 4 || n == 11); - - if n == 4 { b"pwritev is working!" } else { b"pwritev is great !" } - }; - - let content = fs::read(&filename).unwrap(); - assert_eq!(&content, expected); -} diff --git a/library/std/src/os/unix/io/mod.rs b/library/std/src/os/unix/io/mod.rs deleted file mode 100644 index 6d4090ee31cfc..0000000000000 --- a/library/std/src/os/unix/io/mod.rs +++ /dev/null @@ -1,100 +0,0 @@ -//! Unix-specific extensions to general I/O primitives. -//! -//! Just like raw pointers, raw file descriptors point to resources with -//! dynamic lifetimes, and they can dangle if they outlive their resources -//! or be forged if they're created from invalid values. -//! -//! This module provides three types for representing file descriptors, -//! with different ownership properties: raw, borrowed, and owned, which are -//! analogous to types used for representing pointers. These types reflect concepts of [I/O -//! safety][io-safety] on Unix. -//! -//! | Type | Analogous to | -//! | ------------------ | ------------ | -//! | [`RawFd`] | `*const _` | -//! | [`BorrowedFd<'a>`] | `&'a Arc<_>` | -//! | [`OwnedFd`] | `Arc<_>` | -//! -//! Like raw pointers, `RawFd` values are primitive values. And in new code, -//! they should be considered unsafe to do I/O on (analogous to dereferencing -//! them). Rust did not always provide this guidance, so existing code in the -//! Rust ecosystem often doesn't mark `RawFd` usage as unsafe. -//! Libraries are encouraged to migrate, -//! either by adding `unsafe` to APIs that dereference `RawFd` values, or by -//! using to `BorrowedFd` or `OwnedFd` instead. -//! -//! The use of `Arc` for borrowed/owned file descriptors may be surprising. Unix file descriptors -//! are mere references to internal kernel objects called "open file descriptions", and the same -//! open file description can be referenced by multiple file descriptors (e.g. if `dup` is used). -//! State such as the offset within the file is shared among all file descriptors that refer to the -//! same open file description, and the kernel internally does reference-counting to only close the -//! underlying resource once all file descriptors referencing it are closed. That's why `Arc` (and -//! not `Box`) is the closest Rust analogy to an "owned" file descriptor. -//! -//! Like references, `BorrowedFd` values are tied to a lifetime, to ensure -//! that they don't outlive the resource they point to. These are safe to -//! use. `BorrowedFd` values may be used in APIs which provide safe access to -//! any system call except for: -//! -//! - `close`, because that would end the dynamic lifetime of the resource -//! without ending the lifetime of the file descriptor. (Equivalently: -//! an `&Arc<_>` cannot be `drop`ed.) -//! -//! - `dup2`/`dup3`, in the second argument, because this argument is -//! closed and assigned a new resource, which may break the assumptions of -//! other code using that file descriptor. -//! -//! `BorrowedFd` values may be used in APIs which provide safe access to `dup` system calls, so code -//! working with `OwnedFd` cannot assume to have exclusive access to the underlying open file -//! description. (Equivalently: `&Arc` may be used in APIs that provide safe access to `clone`, so -//! code working with an `Arc` cannot assume that the reference count is 1.) -//! -//! `BorrowedFd` values may also be used with `mmap`, since `mmap` uses the -//! provided file descriptor in a manner similar to `dup` and does not require -//! the `BorrowedFd` passed to it to live for the lifetime of the resulting -//! mapping. That said, `mmap` is unsafe for other reasons: it operates on raw -//! pointers, and it can have undefined behavior if the underlying storage is -//! mutated. Mutations may come from other processes, or from the same process -//! if the API provides `BorrowedFd` access, since as mentioned earlier, -//! `BorrowedFd` values may be used in APIs which provide safe access to any -//! system call. Consequently, code using `mmap` and presenting a safe API must -//! take full responsibility for ensuring that safe Rust code cannot evoke -//! undefined behavior through it. -//! -//! Like `Arc`, `OwnedFd` values conceptually own one reference to the resource they point to, -//! and decrement the reference count when they are dropped (by calling `close`). -//! When the reference count reaches 0, the underlying open file description will be freed -//! by the kernel. -//! -//! See the [`io` module docs][io-safety] for a general explanation of I/O safety. -//! -//! ## `/proc/self/mem` and similar OS features -//! -//! Some platforms have special files, such as `/proc/self/mem`, which -//! provide read and write access to the process's memory. Such reads -//! and writes happen outside the control of the Rust compiler, so they do not -//! uphold Rust's memory safety guarantees. -//! -//! This does not mean that all APIs that might allow `/proc/self/mem` -//! to be opened and read from or written must be `unsafe`. Rust's safety guarantees -//! only cover what the program itself can do, and not what entities outside -//! the program can do to it. `/proc/self/mem` is considered to be such an -//! external entity, along with `/proc/self/fd/*`, debugging interfaces, and people with physical -//! access to the hardware. This is true even in cases where the program is controlling the external -//! entity. -//! -//! If you desire to comprehensively prevent programs from reaching out and -//! causing external entities to reach back in and violate memory safety, it's -//! necessary to use *sandboxing*, which is outside the scope of `std`. -//! -//! [`BorrowedFd<'a>`]: crate::os::unix::io::BorrowedFd -//! [io-safety]: crate::io#io-safety - -#![stable(feature = "rust1", since = "1.0.0")] - -#[stable(feature = "rust1", since = "1.0.0")] -pub use crate::os::fd::*; - -// Tests for this module -#[cfg(test)] -mod tests; diff --git a/library/std/src/os/unix/io/tests.rs b/library/std/src/os/unix/io/tests.rs deleted file mode 100644 index 84d2a7a1a91b4..0000000000000 --- a/library/std/src/os/unix/io/tests.rs +++ /dev/null @@ -1,11 +0,0 @@ -use crate::mem::size_of; -use crate::os::unix::io::RawFd; - -#[test] -fn test_raw_fd_layout() { - // `OwnedFd` and `BorrowedFd` use `rustc_layout_scalar_valid_range_start` - // and `rustc_layout_scalar_valid_range_end`, with values that depend on - // the bit width of `RawFd`. If this ever changes, those values will need - // to be updated. - assert_eq!(size_of::(), 4); -} diff --git a/library/std/src/os/unix/mod.rs b/library/std/src/os/unix/mod.rs deleted file mode 100644 index d7a622012a5ac..0000000000000 --- a/library/std/src/os/unix/mod.rs +++ /dev/null @@ -1,126 +0,0 @@ -//! Platform-specific extensions to `std` for Unix platforms. -//! -//! Provides access to platform-level information on Unix platforms, and -//! exposes Unix-specific functions that would otherwise be inappropriate as -//! part of the core `std` library. -//! -//! It exposes more ways to deal with platform-specific strings ([`OsStr`], -//! [`OsString`]), allows to set permissions more granularly, extract low-level -//! file descriptors from files and sockets, and has platform-specific helpers -//! for spawning processes. -//! -//! # Examples -//! -//! ```no_run -//! use std::fs::File; -//! use std::os::unix::prelude::*; -//! -//! fn main() -> std::io::Result<()> { -//! let f = File::create("foo.txt")?; -//! let fd = f.as_raw_fd(); -//! -//! // use fd with native unix bindings -//! -//! Ok(()) -//! } -//! ``` -//! -//! [`OsStr`]: crate::ffi::OsStr -//! [`OsString`]: crate::ffi::OsString - -#![stable(feature = "rust1", since = "1.0.0")] -#![doc(cfg(unix))] - -// Use linux as the default platform when documenting on other platforms like Windows -#[cfg(doc)] -use crate::os::linux as platform; - -#[cfg(not(doc))] -mod platform { - #[cfg(target_os = "aix")] - pub use crate::os::aix::*; - #[cfg(target_os = "android")] - pub use crate::os::android::*; - #[cfg(target_os = "dragonfly")] - pub use crate::os::dragonfly::*; - #[cfg(target_os = "emscripten")] - pub use crate::os::emscripten::*; - #[cfg(target_os = "espidf")] - pub use crate::os::espidf::*; - #[cfg(target_os = "freebsd")] - pub use crate::os::freebsd::*; - #[cfg(target_os = "fuchsia")] - pub use crate::os::fuchsia::*; - #[cfg(target_os = "haiku")] - pub use crate::os::haiku::*; - #[cfg(target_os = "horizon")] - pub use crate::os::horizon::*; - #[cfg(target_os = "hurd")] - pub use crate::os::hurd::*; - #[cfg(target_os = "illumos")] - pub use crate::os::illumos::*; - #[cfg(target_os = "ios")] - pub use crate::os::ios::*; - #[cfg(target_os = "l4re")] - pub use crate::os::l4re::*; - #[cfg(target_os = "linux")] - pub use crate::os::linux::*; - #[cfg(target_os = "macos")] - pub use crate::os::macos::*; - #[cfg(target_os = "netbsd")] - pub use crate::os::netbsd::*; - #[cfg(target_os = "nto")] - pub use crate::os::nto::*; - #[cfg(target_os = "openbsd")] - pub use crate::os::openbsd::*; - #[cfg(target_os = "redox")] - pub use crate::os::redox::*; - #[cfg(target_os = "solaris")] - pub use crate::os::solaris::*; - #[cfg(target_os = "tvos")] - pub use crate::os::tvos::*; - #[cfg(target_os = "visionos")] - pub use crate::os::visionos::*; - #[cfg(target_os = "vita")] - pub use crate::os::vita::*; - #[cfg(target_os = "vxworks")] - pub use crate::os::vxworks::*; - #[cfg(target_os = "watchos")] - pub use crate::os::watchos::*; -} - -pub mod ffi; -pub mod fs; -pub mod io; -pub mod net; -pub mod process; -pub mod raw; -pub mod thread; - -/// A prelude for conveniently writing platform-specific code. -/// -/// Includes all extension traits, and some important type definitions. -#[stable(feature = "rust1", since = "1.0.0")] -pub mod prelude { - #[doc(no_inline)] - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::ffi::{OsStrExt, OsStringExt}; - #[doc(no_inline)] - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::fs::DirEntryExt; - #[doc(no_inline)] - #[stable(feature = "file_offset", since = "1.15.0")] - pub use super::fs::FileExt; - #[doc(no_inline)] - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::fs::{FileTypeExt, MetadataExt, OpenOptionsExt, PermissionsExt}; - #[doc(no_inline)] - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::io::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd}; - #[doc(no_inline)] - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::process::{CommandExt, ExitStatusExt}; - #[doc(no_inline)] - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::thread::JoinHandleExt; -} diff --git a/library/std/src/os/unix/net/addr.rs b/library/std/src/os/unix/net/addr.rs deleted file mode 100644 index 79f2c365025b7..0000000000000 --- a/library/std/src/os/unix/net/addr.rs +++ /dev/null @@ -1,305 +0,0 @@ -use crate::ffi::OsStr; -#[cfg(any(doc, target_os = "android", target_os = "linux"))] -use crate::os::net::linux_ext; -use crate::os::unix::ffi::OsStrExt; -use crate::path::Path; -use crate::sealed::Sealed; -use crate::sys::cvt; -use crate::{fmt, io, mem, ptr}; - -// FIXME(#43348): Make libc adapt #[doc(cfg(...))] so we don't need these fake definitions here? -#[cfg(not(unix))] -#[allow(non_camel_case_types)] -mod libc { - pub use core::ffi::c_int; - pub type socklen_t = u32; - pub struct sockaddr; - #[derive(Clone)] - pub struct sockaddr_un; -} - -fn sun_path_offset(addr: &libc::sockaddr_un) -> usize { - // Work with an actual instance of the type since using a null pointer is UB - let base = (addr as *const libc::sockaddr_un).addr(); - let path = core::ptr::addr_of!(addr.sun_path).addr(); - path - base -} - -pub(super) fn sockaddr_un(path: &Path) -> io::Result<(libc::sockaddr_un, libc::socklen_t)> { - // SAFETY: All zeros is a valid representation for `sockaddr_un`. - let mut addr: libc::sockaddr_un = unsafe { mem::zeroed() }; - addr.sun_family = libc::AF_UNIX as libc::sa_family_t; - - let bytes = path.as_os_str().as_bytes(); - - if bytes.contains(&0) { - return Err(io::const_io_error!( - io::ErrorKind::InvalidInput, - "paths must not contain interior null bytes", - )); - } - - if bytes.len() >= addr.sun_path.len() { - return Err(io::const_io_error!( - io::ErrorKind::InvalidInput, - "path must be shorter than SUN_LEN", - )); - } - // SAFETY: `bytes` and `addr.sun_path` are not overlapping and - // both point to valid memory. - // NOTE: We zeroed the memory above, so the path is already null - // terminated. - unsafe { - ptr::copy_nonoverlapping(bytes.as_ptr(), addr.sun_path.as_mut_ptr().cast(), bytes.len()) - }; - - let mut len = sun_path_offset(&addr) + bytes.len(); - match bytes.get(0) { - Some(&0) | None => {} - Some(_) => len += 1, - } - Ok((addr, len as libc::socklen_t)) -} - -enum AddressKind<'a> { - Unnamed, - Pathname(&'a Path), - Abstract(&'a [u8]), -} - -/// An address associated with a Unix socket. -/// -/// # Examples -/// -/// ``` -/// use std::os::unix::net::UnixListener; -/// -/// let socket = match UnixListener::bind("/tmp/sock") { -/// Ok(sock) => sock, -/// Err(e) => { -/// println!("Couldn't bind: {e:?}"); -/// return -/// } -/// }; -/// let addr = socket.local_addr().expect("Couldn't get local address"); -/// ``` -#[derive(Clone)] -#[stable(feature = "unix_socket", since = "1.10.0")] -pub struct SocketAddr { - pub(super) addr: libc::sockaddr_un, - pub(super) len: libc::socklen_t, -} - -impl SocketAddr { - pub(super) fn new(f: F) -> io::Result - where - F: FnOnce(*mut libc::sockaddr, *mut libc::socklen_t) -> libc::c_int, - { - unsafe { - let mut addr: libc::sockaddr_un = mem::zeroed(); - let mut len = mem::size_of::() as libc::socklen_t; - cvt(f(core::ptr::addr_of_mut!(addr) as *mut _, &mut len))?; - SocketAddr::from_parts(addr, len) - } - } - - pub(super) fn from_parts( - addr: libc::sockaddr_un, - mut len: libc::socklen_t, - ) -> io::Result { - if cfg!(target_os = "openbsd") { - // on OpenBSD, getsockname(2) returns the actual size of the socket address, - // and not the len of the content. Figure out the length for ourselves. - // https://marc.info/?l=openbsd-bugs&m=170105481926736&w=2 - let sun_path: &[u8] = - unsafe { mem::transmute::<&[libc::c_char], &[u8]>(&addr.sun_path) }; - len = core::slice::memchr::memchr(0, sun_path) - .map_or(len, |new_len| (new_len + sun_path_offset(&addr)) as libc::socklen_t); - } - - if len == 0 { - // When there is a datagram from unnamed unix socket - // linux returns zero bytes of address - len = sun_path_offset(&addr) as libc::socklen_t; // i.e., zero-length address - } else if addr.sun_family != libc::AF_UNIX as libc::sa_family_t { - return Err(io::const_io_error!( - io::ErrorKind::InvalidInput, - "file descriptor did not correspond to a Unix socket", - )); - } - - Ok(SocketAddr { addr, len }) - } - - /// Constructs a `SockAddr` with the family `AF_UNIX` and the provided path. - /// - /// # Errors - /// - /// Returns an error if the path is longer than `SUN_LEN` or if it contains - /// NULL bytes. - /// - /// # Examples - /// - /// ``` - /// use std::os::unix::net::SocketAddr; - /// use std::path::Path; - /// - /// # fn main() -> std::io::Result<()> { - /// let address = SocketAddr::from_pathname("/path/to/socket")?; - /// assert_eq!(address.as_pathname(), Some(Path::new("/path/to/socket"))); - /// # Ok(()) - /// # } - /// ``` - /// - /// Creating a `SocketAddr` with a NULL byte results in an error. - /// - /// ``` - /// use std::os::unix::net::SocketAddr; - /// - /// assert!(SocketAddr::from_pathname("/path/with/\0/bytes").is_err()); - /// ``` - #[stable(feature = "unix_socket_creation", since = "1.61.0")] - pub fn from_pathname

(path: P) -> io::Result - where - P: AsRef, - { - sockaddr_un(path.as_ref()).map(|(addr, len)| SocketAddr { addr, len }) - } - - /// Returns `true` if the address is unnamed. - /// - /// # Examples - /// - /// A named address: - /// - /// ```no_run - /// use std::os::unix::net::UnixListener; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UnixListener::bind("/tmp/sock")?; - /// let addr = socket.local_addr().expect("Couldn't get local address"); - /// assert_eq!(addr.is_unnamed(), false); - /// Ok(()) - /// } - /// ``` - /// - /// An unnamed address: - /// - /// ``` - /// use std::os::unix::net::UnixDatagram; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UnixDatagram::unbound()?; - /// let addr = socket.local_addr().expect("Couldn't get local address"); - /// assert_eq!(addr.is_unnamed(), true); - /// Ok(()) - /// } - /// ``` - #[must_use] - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn is_unnamed(&self) -> bool { - matches!(self.address(), AddressKind::Unnamed) - } - - /// Returns the contents of this address if it is a `pathname` address. - /// - /// # Examples - /// - /// With a pathname: - /// - /// ```no_run - /// use std::os::unix::net::UnixListener; - /// use std::path::Path; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UnixListener::bind("/tmp/sock")?; - /// let addr = socket.local_addr().expect("Couldn't get local address"); - /// assert_eq!(addr.as_pathname(), Some(Path::new("/tmp/sock"))); - /// Ok(()) - /// } - /// ``` - /// - /// Without a pathname: - /// - /// ``` - /// use std::os::unix::net::UnixDatagram; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UnixDatagram::unbound()?; - /// let addr = socket.local_addr().expect("Couldn't get local address"); - /// assert_eq!(addr.as_pathname(), None); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - #[must_use] - pub fn as_pathname(&self) -> Option<&Path> { - if let AddressKind::Pathname(path) = self.address() { Some(path) } else { None } - } - - fn address(&self) -> AddressKind<'_> { - let len = self.len as usize - sun_path_offset(&self.addr); - let path = unsafe { mem::transmute::<&[libc::c_char], &[u8]>(&self.addr.sun_path) }; - - // macOS seems to return a len of 16 and a zeroed sun_path for unnamed addresses - if len == 0 - || (cfg!(not(any(target_os = "linux", target_os = "android"))) - && self.addr.sun_path[0] == 0) - { - AddressKind::Unnamed - } else if self.addr.sun_path[0] == 0 { - AddressKind::Abstract(&path[1..len]) - } else { - AddressKind::Pathname(OsStr::from_bytes(&path[..len - 1]).as_ref()) - } - } -} - -#[stable(feature = "unix_socket_abstract", since = "1.70.0")] -impl Sealed for SocketAddr {} - -#[doc(cfg(any(target_os = "android", target_os = "linux")))] -#[cfg(any(doc, target_os = "android", target_os = "linux"))] -#[stable(feature = "unix_socket_abstract", since = "1.70.0")] -impl linux_ext::addr::SocketAddrExt for SocketAddr { - fn as_abstract_name(&self) -> Option<&[u8]> { - if let AddressKind::Abstract(name) = self.address() { Some(name) } else { None } - } - - fn from_abstract_name(name: N) -> crate::io::Result - where - N: AsRef<[u8]>, - { - let name = name.as_ref(); - unsafe { - let mut addr: libc::sockaddr_un = mem::zeroed(); - addr.sun_family = libc::AF_UNIX as libc::sa_family_t; - - if name.len() + 1 > addr.sun_path.len() { - return Err(io::const_io_error!( - io::ErrorKind::InvalidInput, - "abstract socket name must be shorter than SUN_LEN", - )); - } - - crate::ptr::copy_nonoverlapping( - name.as_ptr(), - addr.sun_path.as_mut_ptr().add(1) as *mut u8, - name.len(), - ); - let len = (sun_path_offset(&addr) + 1 + name.len()) as libc::socklen_t; - SocketAddr::from_parts(addr, len) - } - } -} - -#[stable(feature = "unix_socket", since = "1.10.0")] -impl fmt::Debug for SocketAddr { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - match self.address() { - AddressKind::Unnamed => write!(fmt, "(unnamed)"), - AddressKind::Abstract(name) => write!(fmt, "\"{}\" (abstract)", name.escape_ascii()), - AddressKind::Pathname(path) => write!(fmt, "{path:?} (pathname)"), - } - } -} diff --git a/library/std/src/os/unix/net/ancillary.rs b/library/std/src/os/unix/net/ancillary.rs deleted file mode 100644 index 0597fdcbd7289..0000000000000 --- a/library/std/src/os/unix/net/ancillary.rs +++ /dev/null @@ -1,798 +0,0 @@ -// FIXME: This is currently disabled on *BSD. - -use super::{sockaddr_un, SocketAddr}; -use crate::io::{self, IoSlice, IoSliceMut}; -use crate::marker::PhantomData; -use crate::mem::{size_of, zeroed}; -use crate::os::unix::io::RawFd; -use crate::path::Path; -use crate::ptr::{eq, read_unaligned}; -use crate::slice::from_raw_parts; -use crate::sys::net::Socket; - -// FIXME(#43348): Make libc adapt #[doc(cfg(...))] so we don't need these fake definitions here? -#[cfg(all( - doc, - not(target_os = "linux"), - not(target_os = "android"), - not(target_os = "netbsd"), - not(target_os = "freebsd") -))] -#[allow(non_camel_case_types)] -mod libc { - pub use core::ffi::c_int; - pub struct ucred; - pub struct cmsghdr; - pub struct sockcred2; - pub type pid_t = i32; - pub type gid_t = u32; - pub type uid_t = u32; -} - -pub(super) fn recv_vectored_with_ancillary_from( - socket: &Socket, - bufs: &mut [IoSliceMut<'_>], - ancillary: &mut SocketAncillary<'_>, -) -> io::Result<(usize, bool, io::Result)> { - unsafe { - let mut msg_name: libc::sockaddr_un = zeroed(); - let mut msg: libc::msghdr = zeroed(); - msg.msg_name = core::ptr::addr_of_mut!(msg_name) as *mut _; - msg.msg_namelen = size_of::() as libc::socklen_t; - msg.msg_iov = bufs.as_mut_ptr().cast(); - msg.msg_iovlen = bufs.len() as _; - msg.msg_controllen = ancillary.buffer.len() as _; - // macos requires that the control pointer is null when the len is 0. - if msg.msg_controllen > 0 { - msg.msg_control = ancillary.buffer.as_mut_ptr().cast(); - } - - let count = socket.recv_msg(&mut msg)?; - - ancillary.length = msg.msg_controllen as usize; - ancillary.truncated = msg.msg_flags & libc::MSG_CTRUNC == libc::MSG_CTRUNC; - - let truncated = msg.msg_flags & libc::MSG_TRUNC == libc::MSG_TRUNC; - let addr = SocketAddr::from_parts(msg_name, msg.msg_namelen); - - Ok((count, truncated, addr)) - } -} - -pub(super) fn send_vectored_with_ancillary_to( - socket: &Socket, - path: Option<&Path>, - bufs: &[IoSlice<'_>], - ancillary: &mut SocketAncillary<'_>, -) -> io::Result { - unsafe { - let (mut msg_name, msg_namelen) = - if let Some(path) = path { sockaddr_un(path)? } else { (zeroed(), 0) }; - - let mut msg: libc::msghdr = zeroed(); - msg.msg_name = core::ptr::addr_of_mut!(msg_name) as *mut _; - msg.msg_namelen = msg_namelen; - msg.msg_iov = bufs.as_ptr() as *mut _; - msg.msg_iovlen = bufs.len() as _; - msg.msg_controllen = ancillary.length as _; - // macos requires that the control pointer is null when the len is 0. - if msg.msg_controllen > 0 { - msg.msg_control = ancillary.buffer.as_mut_ptr().cast(); - } - - ancillary.truncated = false; - - socket.send_msg(&mut msg) - } -} - -fn add_to_ancillary_data( - buffer: &mut [u8], - length: &mut usize, - source: &[T], - cmsg_level: libc::c_int, - cmsg_type: libc::c_int, -) -> bool { - #[cfg(not(target_os = "freebsd"))] - let cmsg_size = source.len().checked_mul(size_of::()); - #[cfg(target_os = "freebsd")] - let cmsg_size = Some(unsafe { libc::SOCKCRED2SIZE(1) }); - - let source_len = if let Some(source_len) = cmsg_size { - if let Ok(source_len) = u32::try_from(source_len) { - source_len - } else { - return false; - } - } else { - return false; - }; - - unsafe { - let additional_space = libc::CMSG_SPACE(source_len) as usize; - - let new_length = if let Some(new_length) = additional_space.checked_add(*length) { - new_length - } else { - return false; - }; - - if new_length > buffer.len() { - return false; - } - - buffer[*length..new_length].fill(0); - - *length = new_length; - - let mut msg: libc::msghdr = zeroed(); - msg.msg_control = buffer.as_mut_ptr().cast(); - msg.msg_controllen = *length as _; - - let mut cmsg = libc::CMSG_FIRSTHDR(&msg); - let mut previous_cmsg = cmsg; - while !cmsg.is_null() { - previous_cmsg = cmsg; - cmsg = libc::CMSG_NXTHDR(&msg, cmsg); - - // Most operating systems, but not Linux or emscripten, return the previous pointer - // when its length is zero. Therefore, check if the previous pointer is the same as - // the current one. - if eq(cmsg, previous_cmsg) { - break; - } - } - - if previous_cmsg.is_null() { - return false; - } - - (*previous_cmsg).cmsg_level = cmsg_level; - (*previous_cmsg).cmsg_type = cmsg_type; - (*previous_cmsg).cmsg_len = libc::CMSG_LEN(source_len) as _; - - let data = libc::CMSG_DATA(previous_cmsg).cast(); - - libc::memcpy(data, source.as_ptr().cast(), source_len as usize); - } - true -} - -struct AncillaryDataIter<'a, T> { - data: &'a [u8], - phantom: PhantomData, -} - -impl<'a, T> AncillaryDataIter<'a, T> { - /// Create `AncillaryDataIter` struct to iterate through the data unit in the control message. - /// - /// # Safety - /// - /// `data` must contain a valid control message. - unsafe fn new(data: &'a [u8]) -> AncillaryDataIter<'a, T> { - AncillaryDataIter { data, phantom: PhantomData } - } -} - -impl<'a, T> Iterator for AncillaryDataIter<'a, T> { - type Item = T; - - fn next(&mut self) -> Option { - if size_of::() <= self.data.len() { - unsafe { - let unit = read_unaligned(self.data.as_ptr().cast()); - self.data = &self.data[size_of::()..]; - Some(unit) - } - } else { - None - } - } -} - -#[cfg(all( - doc, - not(target_os = "android"), - not(target_os = "linux"), - not(target_os = "netbsd"), - not(target_os = "freebsd") -))] -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -#[derive(Clone)] -pub struct SocketCred(()); - -/// Unix credential. -#[cfg(any(target_os = "android", target_os = "linux",))] -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -#[derive(Clone)] -pub struct SocketCred(libc::ucred); - -#[cfg(target_os = "netbsd")] -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -#[derive(Clone)] -pub struct SocketCred(libc::sockcred); - -#[cfg(target_os = "freebsd")] -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -#[derive(Clone)] -pub struct SocketCred(libc::sockcred2); - -#[doc(cfg(any(target_os = "android", target_os = "linux")))] -#[cfg(any(target_os = "android", target_os = "linux"))] -impl SocketCred { - /// Create a Unix credential struct. - /// - /// PID, UID and GID is set to 0. - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - #[must_use] - pub fn new() -> SocketCred { - SocketCred(libc::ucred { pid: 0, uid: 0, gid: 0 }) - } - - /// Set the PID. - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn set_pid(&mut self, pid: libc::pid_t) { - self.0.pid = pid; - } - - /// Get the current PID. - #[must_use] - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn get_pid(&self) -> libc::pid_t { - self.0.pid - } - - /// Set the UID. - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn set_uid(&mut self, uid: libc::uid_t) { - self.0.uid = uid; - } - - /// Get the current UID. - #[must_use] - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn get_uid(&self) -> libc::uid_t { - self.0.uid - } - - /// Set the GID. - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn set_gid(&mut self, gid: libc::gid_t) { - self.0.gid = gid; - } - - /// Get the current GID. - #[must_use] - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn get_gid(&self) -> libc::gid_t { - self.0.gid - } -} - -#[cfg(target_os = "freebsd")] -impl SocketCred { - /// Create a Unix credential struct. - /// - /// PID, UID and GID is set to 0. - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - #[must_use] - pub fn new() -> SocketCred { - SocketCred(libc::sockcred2 { - sc_version: 0, - sc_pid: 0, - sc_uid: 0, - sc_euid: 0, - sc_gid: 0, - sc_egid: 0, - sc_ngroups: 0, - sc_groups: [0; 1], - }) - } - - /// Set the PID. - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn set_pid(&mut self, pid: libc::pid_t) { - self.0.sc_pid = pid; - } - - /// Get the current PID. - #[must_use] - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn get_pid(&self) -> libc::pid_t { - self.0.sc_pid - } - - /// Set the UID. - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn set_uid(&mut self, uid: libc::uid_t) { - self.0.sc_euid = uid; - } - - /// Get the current UID. - #[must_use] - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn get_uid(&self) -> libc::uid_t { - self.0.sc_euid - } - - /// Set the GID. - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn set_gid(&mut self, gid: libc::gid_t) { - self.0.sc_egid = gid; - } - - /// Get the current GID. - #[must_use] - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn get_gid(&self) -> libc::gid_t { - self.0.sc_egid - } -} - -#[cfg(target_os = "netbsd")] -impl SocketCred { - /// Create a Unix credential struct. - /// - /// PID, UID and GID is set to 0. - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn new() -> SocketCred { - SocketCred(libc::sockcred { - sc_pid: 0, - sc_uid: 0, - sc_euid: 0, - sc_gid: 0, - sc_egid: 0, - sc_ngroups: 0, - sc_groups: [0u32; 1], - }) - } - - /// Set the PID. - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn set_pid(&mut self, pid: libc::pid_t) { - self.0.sc_pid = pid; - } - - /// Get the current PID. - #[must_use] - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn get_pid(&self) -> libc::pid_t { - self.0.sc_pid - } - - /// Set the UID. - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn set_uid(&mut self, uid: libc::uid_t) { - self.0.sc_uid = uid; - } - - /// Get the current UID. - #[must_use] - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn get_uid(&self) -> libc::uid_t { - self.0.sc_uid - } - - /// Set the GID. - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn set_gid(&mut self, gid: libc::gid_t) { - self.0.sc_gid = gid; - } - - /// Get the current GID. - #[must_use] - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn get_gid(&self) -> libc::gid_t { - self.0.sc_gid - } -} - -/// This control message contains file descriptors. -/// -/// The level is equal to `SOL_SOCKET` and the type is equal to `SCM_RIGHTS`. -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -pub struct ScmRights<'a>(AncillaryDataIter<'a, RawFd>); - -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -impl<'a> Iterator for ScmRights<'a> { - type Item = RawFd; - - fn next(&mut self) -> Option { - self.0.next() - } -} - -#[cfg(all( - doc, - not(target_os = "android"), - not(target_os = "linux"), - not(target_os = "netbsd"), - not(target_os = "freebsd") -))] -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -pub struct ScmCredentials<'a>(AncillaryDataIter<'a, ()>); - -/// This control message contains unix credentials. -/// -/// The level is equal to `SOL_SOCKET` and the type is equal to `SCM_CREDENTIALS` or `SCM_CREDS`. -#[cfg(any(target_os = "android", target_os = "linux",))] -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -pub struct ScmCredentials<'a>(AncillaryDataIter<'a, libc::ucred>); - -#[cfg(target_os = "freebsd")] -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -pub struct ScmCredentials<'a>(AncillaryDataIter<'a, libc::sockcred2>); - -#[cfg(target_os = "netbsd")] -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -pub struct ScmCredentials<'a>(AncillaryDataIter<'a, libc::sockcred>); - -#[cfg(any( - doc, - target_os = "android", - target_os = "linux", - target_os = "netbsd", - target_os = "freebsd" -))] -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -impl<'a> Iterator for ScmCredentials<'a> { - type Item = SocketCred; - - fn next(&mut self) -> Option { - Some(SocketCred(self.0.next()?)) - } -} - -/// The error type which is returned from parsing the type a control message. -#[non_exhaustive] -#[derive(Debug)] -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -pub enum AncillaryError { - Unknown { cmsg_level: i32, cmsg_type: i32 }, -} - -/// This enum represent one control message of variable type. -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -pub enum AncillaryData<'a> { - ScmRights(ScmRights<'a>), - #[cfg(any( - doc, - target_os = "android", - target_os = "linux", - target_os = "netbsd", - target_os = "freebsd" - ))] - ScmCredentials(ScmCredentials<'a>), -} - -impl<'a> AncillaryData<'a> { - /// Create an `AncillaryData::ScmRights` variant. - /// - /// # Safety - /// - /// `data` must contain a valid control message and the control message must be type of - /// `SOL_SOCKET` and level of `SCM_RIGHTS`. - unsafe fn as_rights(data: &'a [u8]) -> Self { - let ancillary_data_iter = AncillaryDataIter::new(data); - let scm_rights = ScmRights(ancillary_data_iter); - AncillaryData::ScmRights(scm_rights) - } - - /// Create an `AncillaryData::ScmCredentials` variant. - /// - /// # Safety - /// - /// `data` must contain a valid control message and the control message must be type of - /// `SOL_SOCKET` and level of `SCM_CREDENTIALS` or `SCM_CREDS`. - #[cfg(any( - doc, - target_os = "android", - target_os = "linux", - target_os = "netbsd", - target_os = "freebsd" - ))] - unsafe fn as_credentials(data: &'a [u8]) -> Self { - let ancillary_data_iter = AncillaryDataIter::new(data); - let scm_credentials = ScmCredentials(ancillary_data_iter); - AncillaryData::ScmCredentials(scm_credentials) - } - - fn try_from_cmsghdr(cmsg: &'a libc::cmsghdr) -> Result { - unsafe { - let cmsg_len_zero = libc::CMSG_LEN(0) as usize; - let data_len = (*cmsg).cmsg_len as usize - cmsg_len_zero; - let data = libc::CMSG_DATA(cmsg).cast(); - let data = from_raw_parts(data, data_len); - - match (*cmsg).cmsg_level { - libc::SOL_SOCKET => match (*cmsg).cmsg_type { - libc::SCM_RIGHTS => Ok(AncillaryData::as_rights(data)), - #[cfg(any(target_os = "android", target_os = "linux",))] - libc::SCM_CREDENTIALS => Ok(AncillaryData::as_credentials(data)), - #[cfg(target_os = "freebsd")] - libc::SCM_CREDS2 => Ok(AncillaryData::as_credentials(data)), - #[cfg(target_os = "netbsd")] - libc::SCM_CREDS => Ok(AncillaryData::as_credentials(data)), - cmsg_type => { - Err(AncillaryError::Unknown { cmsg_level: libc::SOL_SOCKET, cmsg_type }) - } - }, - cmsg_level => { - Err(AncillaryError::Unknown { cmsg_level, cmsg_type: (*cmsg).cmsg_type }) - } - } - } - } -} - -/// This struct is used to iterate through the control messages. -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -pub struct Messages<'a> { - buffer: &'a [u8], - current: Option<&'a libc::cmsghdr>, -} - -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -impl<'a> Iterator for Messages<'a> { - type Item = Result, AncillaryError>; - - fn next(&mut self) -> Option { - unsafe { - let mut msg: libc::msghdr = zeroed(); - msg.msg_control = self.buffer.as_ptr() as *mut _; - msg.msg_controllen = self.buffer.len() as _; - - let cmsg = if let Some(current) = self.current { - libc::CMSG_NXTHDR(&msg, current) - } else { - libc::CMSG_FIRSTHDR(&msg) - }; - - let cmsg = cmsg.as_ref()?; - - // Most operating systems, but not Linux or emscripten, return the previous pointer - // when its length is zero. Therefore, check if the previous pointer is the same as - // the current one. - if let Some(current) = self.current { - if eq(current, cmsg) { - return None; - } - } - - self.current = Some(cmsg); - let ancillary_result = AncillaryData::try_from_cmsghdr(cmsg); - Some(ancillary_result) - } - } -} - -/// A Unix socket Ancillary data struct. -/// -/// # Example -/// ```no_run -/// #![feature(unix_socket_ancillary_data)] -/// use std::os::unix::net::{UnixStream, SocketAncillary, AncillaryData}; -/// use std::io::IoSliceMut; -/// -/// fn main() -> std::io::Result<()> { -/// let sock = UnixStream::connect("/tmp/sock")?; -/// -/// let mut fds = [0; 8]; -/// let mut ancillary_buffer = [0; 128]; -/// let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]); -/// -/// let mut buf = [1; 8]; -/// let mut bufs = &mut [IoSliceMut::new(&mut buf[..])][..]; -/// sock.recv_vectored_with_ancillary(bufs, &mut ancillary)?; -/// -/// for ancillary_result in ancillary.messages() { -/// if let AncillaryData::ScmRights(scm_rights) = ancillary_result.unwrap() { -/// for fd in scm_rights { -/// println!("receive file descriptor: {fd}"); -/// } -/// } -/// } -/// Ok(()) -/// } -/// ``` -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -#[derive(Debug)] -pub struct SocketAncillary<'a> { - buffer: &'a mut [u8], - length: usize, - truncated: bool, -} - -impl<'a> SocketAncillary<'a> { - /// Create an ancillary data with the given buffer. - /// - /// # Example - /// - /// ```no_run - /// # #![allow(unused_mut)] - /// #![feature(unix_socket_ancillary_data)] - /// use std::os::unix::net::SocketAncillary; - /// let mut ancillary_buffer = [0; 128]; - /// let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]); - /// ``` - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn new(buffer: &'a mut [u8]) -> Self { - SocketAncillary { buffer, length: 0, truncated: false } - } - - /// Returns the capacity of the buffer. - #[must_use] - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn capacity(&self) -> usize { - self.buffer.len() - } - - /// Returns `true` if the ancillary data is empty. - #[must_use] - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn is_empty(&self) -> bool { - self.length == 0 - } - - /// Returns the number of used bytes. - #[must_use] - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn len(&self) -> usize { - self.length - } - - /// Returns the iterator of the control messages. - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn messages(&self) -> Messages<'_> { - Messages { buffer: &self.buffer[..self.length], current: None } - } - - /// Is `true` if during a recv operation the ancillary was truncated. - /// - /// # Example - /// - /// ```no_run - /// #![feature(unix_socket_ancillary_data)] - /// use std::os::unix::net::{UnixStream, SocketAncillary}; - /// use std::io::IoSliceMut; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixStream::connect("/tmp/sock")?; - /// - /// let mut ancillary_buffer = [0; 128]; - /// let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]); - /// - /// let mut buf = [1; 8]; - /// let mut bufs = &mut [IoSliceMut::new(&mut buf[..])][..]; - /// sock.recv_vectored_with_ancillary(bufs, &mut ancillary)?; - /// - /// println!("Is truncated: {}", ancillary.truncated()); - /// Ok(()) - /// } - /// ``` - #[must_use] - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn truncated(&self) -> bool { - self.truncated - } - - /// Add file descriptors to the ancillary data. - /// - /// The function returns `true` if there was enough space in the buffer. - /// If there was not enough space then no file descriptors was appended. - /// Technically, that means this operation adds a control message with the level `SOL_SOCKET` - /// and type `SCM_RIGHTS`. - /// - /// # Example - /// - /// ```no_run - /// #![feature(unix_socket_ancillary_data)] - /// use std::os::unix::net::{UnixStream, SocketAncillary}; - /// use std::os::unix::io::AsRawFd; - /// use std::io::IoSlice; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixStream::connect("/tmp/sock")?; - /// - /// let mut ancillary_buffer = [0; 128]; - /// let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]); - /// ancillary.add_fds(&[sock.as_raw_fd()][..]); - /// - /// let buf = [1; 8]; - /// let mut bufs = &mut [IoSlice::new(&buf[..])][..]; - /// sock.send_vectored_with_ancillary(bufs, &mut ancillary)?; - /// Ok(()) - /// } - /// ``` - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn add_fds(&mut self, fds: &[RawFd]) -> bool { - self.truncated = false; - add_to_ancillary_data( - &mut self.buffer, - &mut self.length, - fds, - libc::SOL_SOCKET, - libc::SCM_RIGHTS, - ) - } - - /// Add credentials to the ancillary data. - /// - /// The function returns `true` if there is enough space in the buffer. - /// If there is not enough space then no credentials will be appended. - /// Technically, that means this operation adds a control message with the level `SOL_SOCKET` - /// and type `SCM_CREDENTIALS`, `SCM_CREDS`, or `SCM_CREDS2`. - /// - #[cfg(any( - doc, - target_os = "android", - target_os = "linux", - target_os = "netbsd", - target_os = "freebsd" - ))] - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn add_creds(&mut self, creds: &[SocketCred]) -> bool { - self.truncated = false; - add_to_ancillary_data( - &mut self.buffer, - &mut self.length, - creds, - libc::SOL_SOCKET, - #[cfg(not(any(target_os = "netbsd", target_os = "freebsd")))] - libc::SCM_CREDENTIALS, - #[cfg(target_os = "freebsd")] - libc::SCM_CREDS2, - #[cfg(target_os = "netbsd")] - libc::SCM_CREDS, - ) - } - - /// Clears the ancillary data, removing all values. - /// - /// # Example - /// - /// ```no_run - /// #![feature(unix_socket_ancillary_data)] - /// use std::os::unix::net::{UnixStream, SocketAncillary, AncillaryData}; - /// use std::io::IoSliceMut; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixStream::connect("/tmp/sock")?; - /// - /// let mut fds1 = [0; 8]; - /// let mut fds2 = [0; 8]; - /// let mut ancillary_buffer = [0; 128]; - /// let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]); - /// - /// let mut buf = [1; 8]; - /// let mut bufs = &mut [IoSliceMut::new(&mut buf[..])][..]; - /// - /// sock.recv_vectored_with_ancillary(bufs, &mut ancillary)?; - /// for ancillary_result in ancillary.messages() { - /// if let AncillaryData::ScmRights(scm_rights) = ancillary_result.unwrap() { - /// for fd in scm_rights { - /// println!("receive file descriptor: {fd}"); - /// } - /// } - /// } - /// - /// ancillary.clear(); - /// - /// sock.recv_vectored_with_ancillary(bufs, &mut ancillary)?; - /// for ancillary_result in ancillary.messages() { - /// if let AncillaryData::ScmRights(scm_rights) = ancillary_result.unwrap() { - /// for fd in scm_rights { - /// println!("receive file descriptor: {fd}"); - /// } - /// } - /// } - /// Ok(()) - /// } - /// ``` - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn clear(&mut self) { - self.length = 0; - self.truncated = false; - } -} diff --git a/library/std/src/os/unix/net/datagram.rs b/library/std/src/os/unix/net/datagram.rs deleted file mode 100644 index b29f9099a1111..0000000000000 --- a/library/std/src/os/unix/net/datagram.rs +++ /dev/null @@ -1,989 +0,0 @@ -#[cfg(any(doc, target_os = "android", target_os = "linux"))] -use super::{recv_vectored_with_ancillary_from, send_vectored_with_ancillary_to, SocketAncillary}; -use super::{sockaddr_un, SocketAddr}; -#[cfg(any(doc, target_os = "android", target_os = "linux"))] -use crate::io::{IoSlice, IoSliceMut}; -use crate::net::Shutdown; -use crate::os::unix::io::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd}; -use crate::path::Path; -use crate::sealed::Sealed; -use crate::sys::cvt; -use crate::sys::net::Socket; -use crate::sys_common::{AsInner, FromInner, IntoInner}; -use crate::time::Duration; -use crate::{fmt, io}; - -#[cfg(any( - target_os = "linux", - target_os = "android", - target_os = "dragonfly", - target_os = "freebsd", - target_os = "openbsd", - target_os = "netbsd", - target_os = "haiku", - target_os = "nto", -))] -use libc::MSG_NOSIGNAL; -#[cfg(not(any( - target_os = "linux", - target_os = "android", - target_os = "dragonfly", - target_os = "freebsd", - target_os = "openbsd", - target_os = "netbsd", - target_os = "haiku", - target_os = "nto", -)))] -const MSG_NOSIGNAL: core::ffi::c_int = 0x0; - -/// A Unix datagram socket. -/// -/// # Examples -/// -/// ```no_run -/// use std::os::unix::net::UnixDatagram; -/// -/// fn main() -> std::io::Result<()> { -/// let socket = UnixDatagram::bind("/path/to/my/socket")?; -/// socket.send_to(b"hello world", "/path/to/other/socket")?; -/// let mut buf = [0; 100]; -/// let (count, address) = socket.recv_from(&mut buf)?; -/// println!("socket {:?} sent {:?}", address, &buf[..count]); -/// Ok(()) -/// } -/// ``` -#[stable(feature = "unix_socket", since = "1.10.0")] -pub struct UnixDatagram(Socket); - -/// Allows extension traits within `std`. -#[unstable(feature = "sealed", issue = "none")] -impl Sealed for UnixDatagram {} - -#[stable(feature = "unix_socket", since = "1.10.0")] -impl fmt::Debug for UnixDatagram { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - let mut builder = fmt.debug_struct("UnixDatagram"); - builder.field("fd", self.0.as_inner()); - if let Ok(addr) = self.local_addr() { - builder.field("local", &addr); - } - if let Ok(addr) = self.peer_addr() { - builder.field("peer", &addr); - } - builder.finish() - } -} - -impl UnixDatagram { - /// Creates a Unix datagram socket bound to the given path. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixDatagram; - /// - /// let sock = match UnixDatagram::bind("/path/to/the/socket") { - /// Ok(sock) => sock, - /// Err(e) => { - /// println!("Couldn't bind: {e:?}"); - /// return - /// } - /// }; - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn bind>(path: P) -> io::Result { - unsafe { - let socket = UnixDatagram::unbound()?; - let (addr, len) = sockaddr_un(path.as_ref())?; - - cvt(libc::bind(socket.as_raw_fd(), core::ptr::addr_of!(addr) as *const _, len as _))?; - - Ok(socket) - } - } - - /// Creates a Unix datagram socket bound to an address. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::{UnixDatagram}; - /// - /// fn main() -> std::io::Result<()> { - /// let sock1 = UnixDatagram::bind("path/to/socket")?; - /// let addr = sock1.local_addr()?; - /// - /// let sock2 = match UnixDatagram::bind_addr(&addr) { - /// Ok(sock) => sock, - /// Err(err) => { - /// println!("Couldn't bind: {err:?}"); - /// return Err(err); - /// } - /// }; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket_abstract", since = "1.70.0")] - pub fn bind_addr(socket_addr: &SocketAddr) -> io::Result { - unsafe { - let socket = UnixDatagram::unbound()?; - cvt(libc::bind( - socket.as_raw_fd(), - core::ptr::addr_of!(socket_addr.addr) as *const _, - socket_addr.len as _, - ))?; - Ok(socket) - } - } - - /// Creates a Unix Datagram socket which is not bound to any address. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixDatagram; - /// - /// let sock = match UnixDatagram::unbound() { - /// Ok(sock) => sock, - /// Err(e) => { - /// println!("Couldn't unbound: {e:?}"); - /// return - /// } - /// }; - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn unbound() -> io::Result { - let inner = Socket::new_raw(libc::AF_UNIX, libc::SOCK_DGRAM)?; - Ok(UnixDatagram(inner)) - } - - /// Creates an unnamed pair of connected sockets. - /// - /// Returns two `UnixDatagrams`s which are connected to each other. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixDatagram; - /// - /// let (sock1, sock2) = match UnixDatagram::pair() { - /// Ok((sock1, sock2)) => (sock1, sock2), - /// Err(e) => { - /// println!("Couldn't unbound: {e:?}"); - /// return - /// } - /// }; - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn pair() -> io::Result<(UnixDatagram, UnixDatagram)> { - let (i1, i2) = Socket::new_pair(libc::AF_UNIX, libc::SOCK_DGRAM)?; - Ok((UnixDatagram(i1), UnixDatagram(i2))) - } - - /// Connects the socket to the specified path address. - /// - /// The [`send`] method may be used to send data to the specified address. - /// [`recv`] and [`recv_from`] will only receive data from that address. - /// - /// [`send`]: UnixDatagram::send - /// [`recv`]: UnixDatagram::recv - /// [`recv_from`]: UnixDatagram::recv_from - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixDatagram; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixDatagram::unbound()?; - /// match sock.connect("/path/to/the/socket") { - /// Ok(sock) => sock, - /// Err(e) => { - /// println!("Couldn't connect: {e:?}"); - /// return Err(e) - /// } - /// }; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn connect>(&self, path: P) -> io::Result<()> { - unsafe { - let (addr, len) = sockaddr_un(path.as_ref())?; - - cvt(libc::connect(self.as_raw_fd(), core::ptr::addr_of!(addr) as *const _, len))?; - } - Ok(()) - } - - /// Connects the socket to an address. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::{UnixDatagram}; - /// - /// fn main() -> std::io::Result<()> { - /// let bound = UnixDatagram::bind("/path/to/socket")?; - /// let addr = bound.local_addr()?; - /// - /// let sock = UnixDatagram::unbound()?; - /// match sock.connect_addr(&addr) { - /// Ok(sock) => sock, - /// Err(e) => { - /// println!("Couldn't connect: {e:?}"); - /// return Err(e) - /// } - /// }; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket_abstract", since = "1.70.0")] - pub fn connect_addr(&self, socket_addr: &SocketAddr) -> io::Result<()> { - unsafe { - cvt(libc::connect( - self.as_raw_fd(), - core::ptr::addr_of!(socket_addr.addr) as *const _, - socket_addr.len, - ))?; - } - Ok(()) - } - - /// Creates a new independently owned handle to the underlying socket. - /// - /// The returned `UnixDatagram` is a reference to the same socket that this - /// object references. Both handles can be used to accept incoming - /// connections and options set on one side will affect the other. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixDatagram; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixDatagram::bind("/path/to/the/socket")?; - /// let sock_copy = sock.try_clone().expect("try_clone failed"); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn try_clone(&self) -> io::Result { - self.0.duplicate().map(UnixDatagram) - } - - /// Returns the address of this socket. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixDatagram; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixDatagram::bind("/path/to/the/socket")?; - /// let addr = sock.local_addr().expect("Couldn't get local address"); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn local_addr(&self) -> io::Result { - SocketAddr::new(|addr, len| unsafe { libc::getsockname(self.as_raw_fd(), addr, len) }) - } - - /// Returns the address of this socket's peer. - /// - /// The [`connect`] method will connect the socket to a peer. - /// - /// [`connect`]: UnixDatagram::connect - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixDatagram; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixDatagram::unbound()?; - /// sock.connect("/path/to/the/socket")?; - /// - /// let addr = sock.peer_addr().expect("Couldn't get peer address"); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn peer_addr(&self) -> io::Result { - SocketAddr::new(|addr, len| unsafe { libc::getpeername(self.as_raw_fd(), addr, len) }) - } - - fn recv_from_flags( - &self, - buf: &mut [u8], - flags: core::ffi::c_int, - ) -> io::Result<(usize, SocketAddr)> { - let mut count = 0; - let addr = SocketAddr::new(|addr, len| unsafe { - count = libc::recvfrom( - self.as_raw_fd(), - buf.as_mut_ptr() as *mut _, - buf.len(), - flags, - addr, - len, - ); - if count > 0 { - 1 - } else if count == 0 { - 0 - } else { - -1 - } - })?; - - Ok((count as usize, addr)) - } - - /// Receives data from the socket. - /// - /// On success, returns the number of bytes read and the address from - /// whence the data came. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixDatagram; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixDatagram::unbound()?; - /// let mut buf = vec![0; 10]; - /// let (size, sender) = sock.recv_from(buf.as_mut_slice())?; - /// println!("received {size} bytes from {sender:?}"); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn recv_from(&self, buf: &mut [u8]) -> io::Result<(usize, SocketAddr)> { - self.recv_from_flags(buf, 0) - } - - /// Receives data from the socket. - /// - /// On success, returns the number of bytes read. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixDatagram; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixDatagram::bind("/path/to/the/socket")?; - /// let mut buf = vec![0; 10]; - /// sock.recv(buf.as_mut_slice()).expect("recv function failed"); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn recv(&self, buf: &mut [u8]) -> io::Result { - self.0.read(buf) - } - - /// Receives data and ancillary data from socket. - /// - /// On success, returns the number of bytes read, if the data was truncated and the address from whence the msg came. - /// - /// # Examples - /// - #[cfg_attr(any(target_os = "android", target_os = "linux"), doc = "```no_run")] - #[cfg_attr(not(any(target_os = "android", target_os = "linux")), doc = "```ignore")] - /// #![feature(unix_socket_ancillary_data)] - /// use std::os::unix::net::{UnixDatagram, SocketAncillary, AncillaryData}; - /// use std::io::IoSliceMut; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixDatagram::unbound()?; - /// let mut buf1 = [1; 8]; - /// let mut buf2 = [2; 16]; - /// let mut buf3 = [3; 8]; - /// let mut bufs = &mut [ - /// IoSliceMut::new(&mut buf1), - /// IoSliceMut::new(&mut buf2), - /// IoSliceMut::new(&mut buf3), - /// ][..]; - /// let mut fds = [0; 8]; - /// let mut ancillary_buffer = [0; 128]; - /// let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]); - /// let (size, _truncated, sender) = sock.recv_vectored_with_ancillary_from(bufs, &mut ancillary)?; - /// println!("received {size}"); - /// for ancillary_result in ancillary.messages() { - /// if let AncillaryData::ScmRights(scm_rights) = ancillary_result.unwrap() { - /// for fd in scm_rights { - /// println!("receive file descriptor: {fd}"); - /// } - /// } - /// } - /// Ok(()) - /// } - /// ``` - #[cfg(any(doc, target_os = "android", target_os = "linux"))] - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn recv_vectored_with_ancillary_from( - &self, - bufs: &mut [IoSliceMut<'_>], - ancillary: &mut SocketAncillary<'_>, - ) -> io::Result<(usize, bool, SocketAddr)> { - let (count, truncated, addr) = recv_vectored_with_ancillary_from(&self.0, bufs, ancillary)?; - let addr = addr?; - - Ok((count, truncated, addr)) - } - - /// Receives data and ancillary data from socket. - /// - /// On success, returns the number of bytes read and if the data was truncated. - /// - /// # Examples - /// - #[cfg_attr(any(target_os = "android", target_os = "linux"), doc = "```no_run")] - #[cfg_attr(not(any(target_os = "android", target_os = "linux")), doc = "```ignore")] - /// #![feature(unix_socket_ancillary_data)] - /// use std::os::unix::net::{UnixDatagram, SocketAncillary, AncillaryData}; - /// use std::io::IoSliceMut; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixDatagram::unbound()?; - /// let mut buf1 = [1; 8]; - /// let mut buf2 = [2; 16]; - /// let mut buf3 = [3; 8]; - /// let mut bufs = &mut [ - /// IoSliceMut::new(&mut buf1), - /// IoSliceMut::new(&mut buf2), - /// IoSliceMut::new(&mut buf3), - /// ][..]; - /// let mut fds = [0; 8]; - /// let mut ancillary_buffer = [0; 128]; - /// let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]); - /// let (size, _truncated) = sock.recv_vectored_with_ancillary(bufs, &mut ancillary)?; - /// println!("received {size}"); - /// for ancillary_result in ancillary.messages() { - /// if let AncillaryData::ScmRights(scm_rights) = ancillary_result.unwrap() { - /// for fd in scm_rights { - /// println!("receive file descriptor: {fd}"); - /// } - /// } - /// } - /// Ok(()) - /// } - /// ``` - #[cfg(any(doc, target_os = "android", target_os = "linux"))] - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn recv_vectored_with_ancillary( - &self, - bufs: &mut [IoSliceMut<'_>], - ancillary: &mut SocketAncillary<'_>, - ) -> io::Result<(usize, bool)> { - let (count, truncated, addr) = recv_vectored_with_ancillary_from(&self.0, bufs, ancillary)?; - addr?; - - Ok((count, truncated)) - } - - /// Sends data on the socket to the specified address. - /// - /// On success, returns the number of bytes written. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixDatagram; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixDatagram::unbound()?; - /// sock.send_to(b"omelette au fromage", "/some/sock").expect("send_to function failed"); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn send_to>(&self, buf: &[u8], path: P) -> io::Result { - unsafe { - let (addr, len) = sockaddr_un(path.as_ref())?; - - let count = cvt(libc::sendto( - self.as_raw_fd(), - buf.as_ptr() as *const _, - buf.len(), - MSG_NOSIGNAL, - core::ptr::addr_of!(addr) as *const _, - len, - ))?; - Ok(count as usize) - } - } - - /// Sends data on the socket to the specified [SocketAddr]. - /// - /// On success, returns the number of bytes written. - /// - /// [SocketAddr]: crate::os::unix::net::SocketAddr - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::{UnixDatagram}; - /// - /// fn main() -> std::io::Result<()> { - /// let bound = UnixDatagram::bind("/path/to/socket")?; - /// let addr = bound.local_addr()?; - /// - /// let sock = UnixDatagram::unbound()?; - /// sock.send_to_addr(b"bacon egg and cheese", &addr).expect("send_to_addr function failed"); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket_abstract", since = "1.70.0")] - pub fn send_to_addr(&self, buf: &[u8], socket_addr: &SocketAddr) -> io::Result { - unsafe { - let count = cvt(libc::sendto( - self.as_raw_fd(), - buf.as_ptr() as *const _, - buf.len(), - MSG_NOSIGNAL, - core::ptr::addr_of!(socket_addr.addr) as *const _, - socket_addr.len, - ))?; - Ok(count as usize) - } - } - - /// Sends data on the socket to the socket's peer. - /// - /// The peer address may be set by the `connect` method, and this method - /// will return an error if the socket has not already been connected. - /// - /// On success, returns the number of bytes written. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixDatagram; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixDatagram::unbound()?; - /// sock.connect("/some/sock").expect("Couldn't connect"); - /// sock.send(b"omelette au fromage").expect("send_to function failed"); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn send(&self, buf: &[u8]) -> io::Result { - self.0.write(buf) - } - - /// Sends data and ancillary data on the socket to the specified address. - /// - /// On success, returns the number of bytes written. - /// - /// # Examples - /// - #[cfg_attr(any(target_os = "android", target_os = "linux"), doc = "```no_run")] - #[cfg_attr(not(any(target_os = "android", target_os = "linux")), doc = "```ignore")] - /// #![feature(unix_socket_ancillary_data)] - /// use std::os::unix::net::{UnixDatagram, SocketAncillary}; - /// use std::io::IoSlice; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixDatagram::unbound()?; - /// let buf1 = [1; 8]; - /// let buf2 = [2; 16]; - /// let buf3 = [3; 8]; - /// let bufs = &[ - /// IoSlice::new(&buf1), - /// IoSlice::new(&buf2), - /// IoSlice::new(&buf3), - /// ][..]; - /// let fds = [0, 1, 2]; - /// let mut ancillary_buffer = [0; 128]; - /// let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]); - /// ancillary.add_fds(&fds[..]); - /// sock.send_vectored_with_ancillary_to(bufs, &mut ancillary, "/some/sock") - /// .expect("send_vectored_with_ancillary_to function failed"); - /// Ok(()) - /// } - /// ``` - #[cfg(any(doc, target_os = "android", target_os = "linux"))] - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn send_vectored_with_ancillary_to>( - &self, - bufs: &[IoSlice<'_>], - ancillary: &mut SocketAncillary<'_>, - path: P, - ) -> io::Result { - send_vectored_with_ancillary_to(&self.0, Some(path.as_ref()), bufs, ancillary) - } - - /// Sends data and ancillary data on the socket. - /// - /// On success, returns the number of bytes written. - /// - /// # Examples - /// - #[cfg_attr(any(target_os = "android", target_os = "linux"), doc = "```no_run")] - #[cfg_attr(not(any(target_os = "android", target_os = "linux")), doc = "```ignore")] - /// #![feature(unix_socket_ancillary_data)] - /// use std::os::unix::net::{UnixDatagram, SocketAncillary}; - /// use std::io::IoSlice; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixDatagram::unbound()?; - /// let buf1 = [1; 8]; - /// let buf2 = [2; 16]; - /// let buf3 = [3; 8]; - /// let bufs = &[ - /// IoSlice::new(&buf1), - /// IoSlice::new(&buf2), - /// IoSlice::new(&buf3), - /// ][..]; - /// let fds = [0, 1, 2]; - /// let mut ancillary_buffer = [0; 128]; - /// let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]); - /// ancillary.add_fds(&fds[..]); - /// sock.send_vectored_with_ancillary(bufs, &mut ancillary) - /// .expect("send_vectored_with_ancillary function failed"); - /// Ok(()) - /// } - /// ``` - #[cfg(any(doc, target_os = "android", target_os = "linux"))] - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn send_vectored_with_ancillary( - &self, - bufs: &[IoSlice<'_>], - ancillary: &mut SocketAncillary<'_>, - ) -> io::Result { - send_vectored_with_ancillary_to(&self.0, None, bufs, ancillary) - } - - /// Sets the read timeout for the socket. - /// - /// If the provided value is [`None`], then [`recv`] and [`recv_from`] calls will - /// block indefinitely. An [`Err`] is returned if the zero [`Duration`] - /// is passed to this method. - /// - /// [`recv`]: UnixDatagram::recv - /// [`recv_from`]: UnixDatagram::recv_from - /// - /// # Examples - /// - /// ``` - /// use std::os::unix::net::UnixDatagram; - /// use std::time::Duration; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixDatagram::unbound()?; - /// sock.set_read_timeout(Some(Duration::new(1, 0))) - /// .expect("set_read_timeout function failed"); - /// Ok(()) - /// } - /// ``` - /// - /// An [`Err`] is returned if the zero [`Duration`] is passed to this - /// method: - /// - /// ```no_run - /// use std::io; - /// use std::os::unix::net::UnixDatagram; - /// use std::time::Duration; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UnixDatagram::unbound()?; - /// let result = socket.set_read_timeout(Some(Duration::new(0, 0))); - /// let err = result.unwrap_err(); - /// assert_eq!(err.kind(), io::ErrorKind::InvalidInput); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn set_read_timeout(&self, timeout: Option) -> io::Result<()> { - self.0.set_timeout(timeout, libc::SO_RCVTIMEO) - } - - /// Sets the write timeout for the socket. - /// - /// If the provided value is [`None`], then [`send`] and [`send_to`] calls will - /// block indefinitely. An [`Err`] is returned if the zero [`Duration`] is passed to this - /// method. - /// - /// [`send`]: UnixDatagram::send - /// [`send_to`]: UnixDatagram::send_to - /// - /// # Examples - /// - /// ``` - /// use std::os::unix::net::UnixDatagram; - /// use std::time::Duration; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixDatagram::unbound()?; - /// sock.set_write_timeout(Some(Duration::new(1, 0))) - /// .expect("set_write_timeout function failed"); - /// Ok(()) - /// } - /// ``` - /// - /// An [`Err`] is returned if the zero [`Duration`] is passed to this - /// method: - /// - /// ```no_run - /// use std::io; - /// use std::os::unix::net::UnixDatagram; - /// use std::time::Duration; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UnixDatagram::unbound()?; - /// let result = socket.set_write_timeout(Some(Duration::new(0, 0))); - /// let err = result.unwrap_err(); - /// assert_eq!(err.kind(), io::ErrorKind::InvalidInput); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn set_write_timeout(&self, timeout: Option) -> io::Result<()> { - self.0.set_timeout(timeout, libc::SO_SNDTIMEO) - } - - /// Returns the read timeout of this socket. - /// - /// # Examples - /// - /// ``` - /// use std::os::unix::net::UnixDatagram; - /// use std::time::Duration; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixDatagram::unbound()?; - /// sock.set_read_timeout(Some(Duration::new(1, 0))) - /// .expect("set_read_timeout function failed"); - /// assert_eq!(sock.read_timeout()?, Some(Duration::new(1, 0))); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn read_timeout(&self) -> io::Result> { - self.0.timeout(libc::SO_RCVTIMEO) - } - - /// Returns the write timeout of this socket. - /// - /// # Examples - /// - /// ``` - /// use std::os::unix::net::UnixDatagram; - /// use std::time::Duration; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixDatagram::unbound()?; - /// sock.set_write_timeout(Some(Duration::new(1, 0))) - /// .expect("set_write_timeout function failed"); - /// assert_eq!(sock.write_timeout()?, Some(Duration::new(1, 0))); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn write_timeout(&self) -> io::Result> { - self.0.timeout(libc::SO_SNDTIMEO) - } - - /// Moves the socket into or out of nonblocking mode. - /// - /// # Examples - /// - /// ``` - /// use std::os::unix::net::UnixDatagram; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixDatagram::unbound()?; - /// sock.set_nonblocking(true).expect("set_nonblocking function failed"); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> { - self.0.set_nonblocking(nonblocking) - } - - /// Set the id of the socket for network filtering purpose - /// - #[cfg_attr( - any(target_os = "linux", target_os = "freebsd", target_os = "openbsd"), - doc = "```no_run" - )] - #[cfg_attr( - not(any(target_os = "linux", target_os = "freebsd", target_os = "openbsd")), - doc = "```ignore" - )] - /// #![feature(unix_set_mark)] - /// use std::os::unix::net::UnixDatagram; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixDatagram::unbound()?; - /// sock.set_mark(32)?; - /// Ok(()) - /// } - /// ``` - #[cfg(any(doc, target_os = "linux", target_os = "freebsd", target_os = "openbsd",))] - #[unstable(feature = "unix_set_mark", issue = "96467")] - pub fn set_mark(&self, mark: u32) -> io::Result<()> { - self.0.set_mark(mark) - } - - /// Returns the value of the `SO_ERROR` option. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixDatagram; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixDatagram::unbound()?; - /// if let Ok(Some(err)) = sock.take_error() { - /// println!("Got error: {err:?}"); - /// } - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn take_error(&self) -> io::Result> { - self.0.take_error() - } - - /// Shut down the read, write, or both halves of this connection. - /// - /// This function will cause all pending and future I/O calls on the - /// specified portions to immediately return with an appropriate value - /// (see the documentation of [`Shutdown`]). - /// - /// ```no_run - /// use std::os::unix::net::UnixDatagram; - /// use std::net::Shutdown; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixDatagram::unbound()?; - /// sock.shutdown(Shutdown::Both).expect("shutdown function failed"); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn shutdown(&self, how: Shutdown) -> io::Result<()> { - self.0.shutdown(how) - } - - /// Receives data on the socket from the remote address to which it is - /// connected, without removing that data from the queue. On success, - /// returns the number of bytes peeked. - /// - /// Successive calls return the same data. This is accomplished by passing - /// `MSG_PEEK` as a flag to the underlying `recv` system call. - /// - /// # Examples - /// - /// ```no_run - /// #![feature(unix_socket_peek)] - /// - /// use std::os::unix::net::UnixDatagram; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UnixDatagram::bind("/tmp/sock")?; - /// let mut buf = [0; 10]; - /// let len = socket.peek(&mut buf).expect("peek failed"); - /// Ok(()) - /// } - /// ``` - #[unstable(feature = "unix_socket_peek", issue = "76923")] - pub fn peek(&self, buf: &mut [u8]) -> io::Result { - self.0.peek(buf) - } - - /// Receives a single datagram message on the socket, without removing it from the - /// queue. On success, returns the number of bytes read and the origin. - /// - /// The function must be called with valid byte array `buf` of sufficient size to - /// hold the message bytes. If a message is too long to fit in the supplied buffer, - /// excess bytes may be discarded. - /// - /// Successive calls return the same data. This is accomplished by passing - /// `MSG_PEEK` as a flag to the underlying `recvfrom` system call. - /// - /// Do not use this function to implement busy waiting, instead use `libc::poll` to - /// synchronize IO events on one or more sockets. - /// - /// # Examples - /// - /// ```no_run - /// #![feature(unix_socket_peek)] - /// - /// use std::os::unix::net::UnixDatagram; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UnixDatagram::bind("/tmp/sock")?; - /// let mut buf = [0; 10]; - /// let (len, addr) = socket.peek_from(&mut buf).expect("peek failed"); - /// Ok(()) - /// } - /// ``` - #[unstable(feature = "unix_socket_peek", issue = "76923")] - pub fn peek_from(&self, buf: &mut [u8]) -> io::Result<(usize, SocketAddr)> { - self.recv_from_flags(buf, libc::MSG_PEEK) - } -} - -#[stable(feature = "unix_socket", since = "1.10.0")] -impl AsRawFd for UnixDatagram { - #[inline] - fn as_raw_fd(&self) -> RawFd { - self.0.as_inner().as_raw_fd() - } -} - -#[stable(feature = "unix_socket", since = "1.10.0")] -impl FromRawFd for UnixDatagram { - #[inline] - unsafe fn from_raw_fd(fd: RawFd) -> UnixDatagram { - UnixDatagram(Socket::from_inner(FromInner::from_inner(OwnedFd::from_raw_fd(fd)))) - } -} - -#[stable(feature = "unix_socket", since = "1.10.0")] -impl IntoRawFd for UnixDatagram { - #[inline] - fn into_raw_fd(self) -> RawFd { - self.0.into_inner().into_inner().into_raw_fd() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsFd for UnixDatagram { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - self.0.as_inner().as_fd() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for OwnedFd { - /// Takes ownership of a [`UnixDatagram`]'s socket file descriptor. - #[inline] - fn from(unix_datagram: UnixDatagram) -> OwnedFd { - unsafe { OwnedFd::from_raw_fd(unix_datagram.into_raw_fd()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for UnixDatagram { - #[inline] - fn from(owned: OwnedFd) -> Self { - unsafe { Self::from_raw_fd(owned.into_raw_fd()) } - } -} - -impl AsInner for UnixDatagram { - #[inline] - fn as_inner(&self) -> &Socket { - &self.0 - } -} diff --git a/library/std/src/os/unix/net/listener.rs b/library/std/src/os/unix/net/listener.rs deleted file mode 100644 index a55199c82fc10..0000000000000 --- a/library/std/src/os/unix/net/listener.rs +++ /dev/null @@ -1,422 +0,0 @@ -use super::{sockaddr_un, SocketAddr, UnixStream}; -use crate::os::unix::io::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd}; -use crate::path::Path; -use crate::sys::cvt; -use crate::sys::net::Socket; -use crate::sys_common::{AsInner, FromInner, IntoInner}; -use crate::{fmt, io, mem}; - -/// A structure representing a Unix domain socket server. -/// -/// # Examples -/// -/// ```no_run -/// use std::thread; -/// use std::os::unix::net::{UnixStream, UnixListener}; -/// -/// fn handle_client(stream: UnixStream) { -/// // ... -/// } -/// -/// fn main() -> std::io::Result<()> { -/// let listener = UnixListener::bind("/path/to/the/socket")?; -/// -/// // accept connections and process them, spawning a new thread for each one -/// for stream in listener.incoming() { -/// match stream { -/// Ok(stream) => { -/// /* connection succeeded */ -/// thread::spawn(|| handle_client(stream)); -/// } -/// Err(err) => { -/// /* connection failed */ -/// break; -/// } -/// } -/// } -/// Ok(()) -/// } -/// ``` -#[stable(feature = "unix_socket", since = "1.10.0")] -pub struct UnixListener(Socket); - -#[stable(feature = "unix_socket", since = "1.10.0")] -impl fmt::Debug for UnixListener { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - let mut builder = fmt.debug_struct("UnixListener"); - builder.field("fd", self.0.as_inner()); - if let Ok(addr) = self.local_addr() { - builder.field("local", &addr); - } - builder.finish() - } -} - -impl UnixListener { - /// Creates a new `UnixListener` bound to the specified socket. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixListener; - /// - /// let listener = match UnixListener::bind("/path/to/the/socket") { - /// Ok(sock) => sock, - /// Err(e) => { - /// println!("Couldn't connect: {e:?}"); - /// return - /// } - /// }; - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn bind>(path: P) -> io::Result { - unsafe { - let inner = Socket::new_raw(libc::AF_UNIX, libc::SOCK_STREAM)?; - let (addr, len) = sockaddr_un(path.as_ref())?; - #[cfg(any( - target_os = "windows", - target_os = "redox", - target_os = "espidf", - target_os = "horizon" - ))] - const backlog: core::ffi::c_int = 128; - #[cfg(any( - // Silently capped to `/proc/sys/net/core/somaxconn`. - target_os = "linux", - // Silently capped to `kern.ipc.soacceptqueue`. - target_os = "freebsd", - // Silently capped to `kern.somaxconn sysctl`. - target_os = "openbsd", - // Silently capped to the default 128. - target_vendor = "apple", - ))] - const backlog: core::ffi::c_int = -1; - #[cfg(not(any( - target_os = "windows", - target_os = "redox", - target_os = "espidf", - target_os = "horizon", - target_os = "linux", - target_os = "freebsd", - target_os = "openbsd", - target_vendor = "apple", - )))] - const backlog: libc::c_int = libc::SOMAXCONN; - - cvt(libc::bind( - inner.as_inner().as_raw_fd(), - core::ptr::addr_of!(addr) as *const _, - len as _, - ))?; - cvt(libc::listen(inner.as_inner().as_raw_fd(), backlog))?; - - Ok(UnixListener(inner)) - } - } - - /// Creates a new `UnixListener` bound to the specified [`socket address`]. - /// - /// [`socket address`]: crate::os::unix::net::SocketAddr - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::{UnixListener}; - /// - /// fn main() -> std::io::Result<()> { - /// let listener1 = UnixListener::bind("path/to/socket")?; - /// let addr = listener1.local_addr()?; - /// - /// let listener2 = match UnixListener::bind_addr(&addr) { - /// Ok(sock) => sock, - /// Err(err) => { - /// println!("Couldn't bind: {err:?}"); - /// return Err(err); - /// } - /// }; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket_abstract", since = "1.70.0")] - pub fn bind_addr(socket_addr: &SocketAddr) -> io::Result { - unsafe { - let inner = Socket::new_raw(libc::AF_UNIX, libc::SOCK_STREAM)?; - #[cfg(target_os = "linux")] - const backlog: core::ffi::c_int = -1; - #[cfg(not(target_os = "linux"))] - const backlog: core::ffi::c_int = 128; - cvt(libc::bind( - inner.as_raw_fd(), - core::ptr::addr_of!(socket_addr.addr) as *const _, - socket_addr.len as _, - ))?; - cvt(libc::listen(inner.as_raw_fd(), backlog))?; - Ok(UnixListener(inner)) - } - } - - /// Accepts a new incoming connection to this listener. - /// - /// This function will block the calling thread until a new Unix connection - /// is established. When established, the corresponding [`UnixStream`] and - /// the remote peer's address will be returned. - /// - /// [`UnixStream`]: crate::os::unix::net::UnixStream - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixListener; - /// - /// fn main() -> std::io::Result<()> { - /// let listener = UnixListener::bind("/path/to/the/socket")?; - /// - /// match listener.accept() { - /// Ok((socket, addr)) => println!("Got a client: {addr:?}"), - /// Err(e) => println!("accept function failed: {e:?}"), - /// } - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn accept(&self) -> io::Result<(UnixStream, SocketAddr)> { - let mut storage: libc::sockaddr_un = unsafe { mem::zeroed() }; - let mut len = mem::size_of_val(&storage) as libc::socklen_t; - let sock = self.0.accept(core::ptr::addr_of_mut!(storage) as *mut _, &mut len)?; - let addr = SocketAddr::from_parts(storage, len)?; - Ok((UnixStream(sock), addr)) - } - - /// Creates a new independently owned handle to the underlying socket. - /// - /// The returned `UnixListener` is a reference to the same socket that this - /// object references. Both handles can be used to accept incoming - /// connections and options set on one listener will affect the other. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixListener; - /// - /// fn main() -> std::io::Result<()> { - /// let listener = UnixListener::bind("/path/to/the/socket")?; - /// let listener_copy = listener.try_clone().expect("try_clone failed"); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn try_clone(&self) -> io::Result { - self.0.duplicate().map(UnixListener) - } - - /// Returns the local socket address of this listener. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixListener; - /// - /// fn main() -> std::io::Result<()> { - /// let listener = UnixListener::bind("/path/to/the/socket")?; - /// let addr = listener.local_addr().expect("Couldn't get local address"); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn local_addr(&self) -> io::Result { - SocketAddr::new(|addr, len| unsafe { libc::getsockname(self.as_raw_fd(), addr, len) }) - } - - /// Moves the socket into or out of nonblocking mode. - /// - /// This will result in the `accept` operation becoming nonblocking, - /// i.e., immediately returning from their calls. If the IO operation is - /// successful, `Ok` is returned and no further action is required. If the - /// IO operation could not be completed and needs to be retried, an error - /// with kind [`io::ErrorKind::WouldBlock`] is returned. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixListener; - /// - /// fn main() -> std::io::Result<()> { - /// let listener = UnixListener::bind("/path/to/the/socket")?; - /// listener.set_nonblocking(true).expect("Couldn't set non blocking"); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> { - self.0.set_nonblocking(nonblocking) - } - - /// Returns the value of the `SO_ERROR` option. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixListener; - /// - /// fn main() -> std::io::Result<()> { - /// let listener = UnixListener::bind("/tmp/sock")?; - /// - /// if let Ok(Some(err)) = listener.take_error() { - /// println!("Got error: {err:?}"); - /// } - /// Ok(()) - /// } - /// ``` - /// - /// # Platform specific - /// On Redox this always returns `None`. - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn take_error(&self) -> io::Result> { - self.0.take_error() - } - - /// Returns an iterator over incoming connections. - /// - /// The iterator will never return [`None`] and will also not yield the - /// peer's [`SocketAddr`] structure. - /// - /// # Examples - /// - /// ```no_run - /// use std::thread; - /// use std::os::unix::net::{UnixStream, UnixListener}; - /// - /// fn handle_client(stream: UnixStream) { - /// // ... - /// } - /// - /// fn main() -> std::io::Result<()> { - /// let listener = UnixListener::bind("/path/to/the/socket")?; - /// - /// for stream in listener.incoming() { - /// match stream { - /// Ok(stream) => { - /// thread::spawn(|| handle_client(stream)); - /// } - /// Err(err) => { - /// break; - /// } - /// } - /// } - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn incoming(&self) -> Incoming<'_> { - Incoming { listener: self } - } -} - -#[stable(feature = "unix_socket", since = "1.10.0")] -impl AsRawFd for UnixListener { - #[inline] - fn as_raw_fd(&self) -> RawFd { - self.0.as_inner().as_raw_fd() - } -} - -#[stable(feature = "unix_socket", since = "1.10.0")] -impl FromRawFd for UnixListener { - #[inline] - unsafe fn from_raw_fd(fd: RawFd) -> UnixListener { - UnixListener(Socket::from_inner(FromInner::from_inner(OwnedFd::from_raw_fd(fd)))) - } -} - -#[stable(feature = "unix_socket", since = "1.10.0")] -impl IntoRawFd for UnixListener { - #[inline] - fn into_raw_fd(self) -> RawFd { - self.0.into_inner().into_inner().into_raw_fd() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsFd for UnixListener { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - self.0.as_inner().as_fd() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for UnixListener { - #[inline] - fn from(fd: OwnedFd) -> UnixListener { - UnixListener(Socket::from_inner(FromInner::from_inner(fd))) - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for OwnedFd { - /// Takes ownership of a [`UnixListener`]'s socket file descriptor. - #[inline] - fn from(listener: UnixListener) -> OwnedFd { - listener.0.into_inner().into_inner() - } -} - -#[stable(feature = "unix_socket", since = "1.10.0")] -impl<'a> IntoIterator for &'a UnixListener { - type Item = io::Result; - type IntoIter = Incoming<'a>; - - fn into_iter(self) -> Incoming<'a> { - self.incoming() - } -} - -/// An iterator over incoming connections to a [`UnixListener`]. -/// -/// It will never return [`None`]. -/// -/// # Examples -/// -/// ```no_run -/// use std::thread; -/// use std::os::unix::net::{UnixStream, UnixListener}; -/// -/// fn handle_client(stream: UnixStream) { -/// // ... -/// } -/// -/// fn main() -> std::io::Result<()> { -/// let listener = UnixListener::bind("/path/to/the/socket")?; -/// -/// for stream in listener.incoming() { -/// match stream { -/// Ok(stream) => { -/// thread::spawn(|| handle_client(stream)); -/// } -/// Err(err) => { -/// break; -/// } -/// } -/// } -/// Ok(()) -/// } -/// ``` -#[derive(Debug)] -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "unix_socket", since = "1.10.0")] -pub struct Incoming<'a> { - listener: &'a UnixListener, -} - -#[stable(feature = "unix_socket", since = "1.10.0")] -impl<'a> Iterator for Incoming<'a> { - type Item = io::Result; - - fn next(&mut self) -> Option> { - Some(self.listener.accept().map(|s| s.0)) - } - - fn size_hint(&self) -> (usize, Option) { - (usize::MAX, None) - } -} diff --git a/library/std/src/os/unix/net/mod.rs b/library/std/src/os/unix/net/mod.rs deleted file mode 100644 index 3e45e3533ed28..0000000000000 --- a/library/std/src/os/unix/net/mod.rs +++ /dev/null @@ -1,49 +0,0 @@ -//! Unix-specific networking functionality. - -#![allow(irrefutable_let_patterns)] -#![stable(feature = "unix_socket", since = "1.10.0")] - -mod addr; -#[doc(cfg(any(target_os = "android", target_os = "linux")))] -#[cfg(any(doc, target_os = "android", target_os = "linux"))] -mod ancillary; -mod datagram; -mod listener; -mod stream; -#[cfg(all(test, not(target_os = "emscripten")))] -mod tests; -#[cfg(any( - target_os = "android", - target_os = "linux", - target_os = "dragonfly", - target_os = "freebsd", - target_os = "netbsd", - target_os = "openbsd", - target_os = "nto", - target_vendor = "apple", -))] -mod ucred; - -#[stable(feature = "unix_socket", since = "1.10.0")] -pub use self::addr::*; -#[cfg(any(doc, target_os = "android", target_os = "linux"))] -#[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] -pub use self::ancillary::*; -#[stable(feature = "unix_socket", since = "1.10.0")] -pub use self::datagram::*; -#[stable(feature = "unix_socket", since = "1.10.0")] -pub use self::listener::*; -#[stable(feature = "unix_socket", since = "1.10.0")] -pub use self::stream::*; -#[cfg(any( - target_os = "android", - target_os = "linux", - target_os = "dragonfly", - target_os = "freebsd", - target_os = "netbsd", - target_os = "openbsd", - target_os = "nto", - target_vendor = "apple", -))] -#[unstable(feature = "peer_credentials_unix_socket", issue = "42839", reason = "unstable")] -pub use self::ucred::*; diff --git a/library/std/src/os/unix/net/stream.rs b/library/std/src/os/unix/net/stream.rs deleted file mode 100644 index 19fc7b3d8532f..0000000000000 --- a/library/std/src/os/unix/net/stream.rs +++ /dev/null @@ -1,706 +0,0 @@ -#[cfg(any( - target_os = "android", - target_os = "linux", - target_os = "dragonfly", - target_os = "freebsd", - target_os = "netbsd", - target_os = "openbsd", - target_os = "nto", - target_vendor = "apple", -))] -use super::{peer_cred, UCred}; -#[cfg(any(doc, target_os = "android", target_os = "linux"))] -use super::{recv_vectored_with_ancillary_from, send_vectored_with_ancillary_to, SocketAncillary}; -use super::{sockaddr_un, SocketAddr}; -use crate::fmt; -use crate::io::{self, IoSlice, IoSliceMut}; -use crate::net::Shutdown; -use crate::os::unix::io::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd}; -use crate::path::Path; -use crate::sealed::Sealed; -use crate::sys::cvt; -use crate::sys::net::Socket; -use crate::sys_common::{AsInner, FromInner}; -use crate::time::Duration; - -/// A Unix stream socket. -/// -/// # Examples -/// -/// ```no_run -/// use std::os::unix::net::UnixStream; -/// use std::io::prelude::*; -/// -/// fn main() -> std::io::Result<()> { -/// let mut stream = UnixStream::connect("/path/to/my/socket")?; -/// stream.write_all(b"hello world")?; -/// let mut response = String::new(); -/// stream.read_to_string(&mut response)?; -/// println!("{response}"); -/// Ok(()) -/// } -/// ``` -#[stable(feature = "unix_socket", since = "1.10.0")] -pub struct UnixStream(pub(super) Socket); - -/// Allows extension traits within `std`. -#[unstable(feature = "sealed", issue = "none")] -impl Sealed for UnixStream {} - -#[stable(feature = "unix_socket", since = "1.10.0")] -impl fmt::Debug for UnixStream { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - let mut builder = fmt.debug_struct("UnixStream"); - builder.field("fd", self.0.as_inner()); - if let Ok(addr) = self.local_addr() { - builder.field("local", &addr); - } - if let Ok(addr) = self.peer_addr() { - builder.field("peer", &addr); - } - builder.finish() - } -} - -impl UnixStream { - /// Connects to the socket named by `path`. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixStream; - /// - /// let socket = match UnixStream::connect("/tmp/sock") { - /// Ok(sock) => sock, - /// Err(e) => { - /// println!("Couldn't connect: {e:?}"); - /// return - /// } - /// }; - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn connect>(path: P) -> io::Result { - unsafe { - let inner = Socket::new_raw(libc::AF_UNIX, libc::SOCK_STREAM)?; - let (addr, len) = sockaddr_un(path.as_ref())?; - - cvt(libc::connect(inner.as_raw_fd(), core::ptr::addr_of!(addr) as *const _, len))?; - Ok(UnixStream(inner)) - } - } - - /// Connects to the socket specified by [`address`]. - /// - /// [`address`]: crate::os::unix::net::SocketAddr - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::{UnixListener, UnixStream}; - /// - /// fn main() -> std::io::Result<()> { - /// let listener = UnixListener::bind("/path/to/the/socket")?; - /// let addr = listener.local_addr()?; - /// - /// let sock = match UnixStream::connect_addr(&addr) { - /// Ok(sock) => sock, - /// Err(e) => { - /// println!("Couldn't connect: {e:?}"); - /// return Err(e) - /// } - /// }; - /// Ok(()) - /// } - /// ```` - #[stable(feature = "unix_socket_abstract", since = "1.70.0")] - pub fn connect_addr(socket_addr: &SocketAddr) -> io::Result { - unsafe { - let inner = Socket::new_raw(libc::AF_UNIX, libc::SOCK_STREAM)?; - cvt(libc::connect( - inner.as_raw_fd(), - core::ptr::addr_of!(socket_addr.addr) as *const _, - socket_addr.len, - ))?; - Ok(UnixStream(inner)) - } - } - - /// Creates an unnamed pair of connected sockets. - /// - /// Returns two `UnixStream`s which are connected to each other. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixStream; - /// - /// let (sock1, sock2) = match UnixStream::pair() { - /// Ok((sock1, sock2)) => (sock1, sock2), - /// Err(e) => { - /// println!("Couldn't create a pair of sockets: {e:?}"); - /// return - /// } - /// }; - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn pair() -> io::Result<(UnixStream, UnixStream)> { - let (i1, i2) = Socket::new_pair(libc::AF_UNIX, libc::SOCK_STREAM)?; - Ok((UnixStream(i1), UnixStream(i2))) - } - - /// Creates a new independently owned handle to the underlying socket. - /// - /// The returned `UnixStream` is a reference to the same stream that this - /// object references. Both handles will read and write the same stream of - /// data, and options set on one stream will be propagated to the other - /// stream. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixStream; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UnixStream::connect("/tmp/sock")?; - /// let sock_copy = socket.try_clone().expect("Couldn't clone socket"); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn try_clone(&self) -> io::Result { - self.0.duplicate().map(UnixStream) - } - - /// Returns the socket address of the local half of this connection. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixStream; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UnixStream::connect("/tmp/sock")?; - /// let addr = socket.local_addr().expect("Couldn't get local address"); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn local_addr(&self) -> io::Result { - SocketAddr::new(|addr, len| unsafe { libc::getsockname(self.as_raw_fd(), addr, len) }) - } - - /// Returns the socket address of the remote half of this connection. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixStream; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UnixStream::connect("/tmp/sock")?; - /// let addr = socket.peer_addr().expect("Couldn't get peer address"); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn peer_addr(&self) -> io::Result { - SocketAddr::new(|addr, len| unsafe { libc::getpeername(self.as_raw_fd(), addr, len) }) - } - - /// Gets the peer credentials for this Unix domain socket. - /// - /// # Examples - /// - /// ```no_run - /// #![feature(peer_credentials_unix_socket)] - /// use std::os::unix::net::UnixStream; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UnixStream::connect("/tmp/sock")?; - /// let peer_cred = socket.peer_cred().expect("Couldn't get peer credentials"); - /// Ok(()) - /// } - /// ``` - #[unstable(feature = "peer_credentials_unix_socket", issue = "42839", reason = "unstable")] - #[cfg(any( - target_os = "android", - target_os = "linux", - target_os = "dragonfly", - target_os = "freebsd", - target_os = "netbsd", - target_os = "openbsd", - target_os = "nto", - target_vendor = "apple", - ))] - pub fn peer_cred(&self) -> io::Result { - peer_cred(self) - } - - /// Sets the read timeout for the socket. - /// - /// If the provided value is [`None`], then [`read`] calls will block - /// indefinitely. An [`Err`] is returned if the zero [`Duration`] is passed to this - /// method. - /// - /// [`read`]: io::Read::read - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixStream; - /// use std::time::Duration; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UnixStream::connect("/tmp/sock")?; - /// socket.set_read_timeout(Some(Duration::new(1, 0))).expect("Couldn't set read timeout"); - /// Ok(()) - /// } - /// ``` - /// - /// An [`Err`] is returned if the zero [`Duration`] is passed to this - /// method: - /// - /// ```no_run - /// use std::io; - /// use std::os::unix::net::UnixStream; - /// use std::time::Duration; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UnixStream::connect("/tmp/sock")?; - /// let result = socket.set_read_timeout(Some(Duration::new(0, 0))); - /// let err = result.unwrap_err(); - /// assert_eq!(err.kind(), io::ErrorKind::InvalidInput); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn set_read_timeout(&self, timeout: Option) -> io::Result<()> { - self.0.set_timeout(timeout, libc::SO_RCVTIMEO) - } - - /// Sets the write timeout for the socket. - /// - /// If the provided value is [`None`], then [`write`] calls will block - /// indefinitely. An [`Err`] is returned if the zero [`Duration`] is - /// passed to this method. - /// - /// [`read`]: io::Read::read - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixStream; - /// use std::time::Duration; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UnixStream::connect("/tmp/sock")?; - /// socket.set_write_timeout(Some(Duration::new(1, 0))) - /// .expect("Couldn't set write timeout"); - /// Ok(()) - /// } - /// ``` - /// - /// An [`Err`] is returned if the zero [`Duration`] is passed to this - /// method: - /// - /// ```no_run - /// use std::io; - /// use std::net::UdpSocket; - /// use std::time::Duration; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UdpSocket::bind("127.0.0.1:34254")?; - /// let result = socket.set_write_timeout(Some(Duration::new(0, 0))); - /// let err = result.unwrap_err(); - /// assert_eq!(err.kind(), io::ErrorKind::InvalidInput); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn set_write_timeout(&self, timeout: Option) -> io::Result<()> { - self.0.set_timeout(timeout, libc::SO_SNDTIMEO) - } - - /// Returns the read timeout of this socket. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixStream; - /// use std::time::Duration; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UnixStream::connect("/tmp/sock")?; - /// socket.set_read_timeout(Some(Duration::new(1, 0))).expect("Couldn't set read timeout"); - /// assert_eq!(socket.read_timeout()?, Some(Duration::new(1, 0))); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn read_timeout(&self) -> io::Result> { - self.0.timeout(libc::SO_RCVTIMEO) - } - - /// Returns the write timeout of this socket. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixStream; - /// use std::time::Duration; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UnixStream::connect("/tmp/sock")?; - /// socket.set_write_timeout(Some(Duration::new(1, 0))) - /// .expect("Couldn't set write timeout"); - /// assert_eq!(socket.write_timeout()?, Some(Duration::new(1, 0))); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn write_timeout(&self) -> io::Result> { - self.0.timeout(libc::SO_SNDTIMEO) - } - - /// Moves the socket into or out of nonblocking mode. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixStream; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UnixStream::connect("/tmp/sock")?; - /// socket.set_nonblocking(true).expect("Couldn't set nonblocking"); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> { - self.0.set_nonblocking(nonblocking) - } - - /// Set the id of the socket for network filtering purpose - /// - #[cfg_attr( - any(target_os = "linux", target_os = "freebsd", target_os = "openbsd"), - doc = "```no_run" - )] - #[cfg_attr( - not(any(target_os = "linux", target_os = "freebsd", target_os = "openbsd")), - doc = "```ignore" - )] - /// #![feature(unix_set_mark)] - /// use std::os::unix::net::UnixStream; - /// - /// fn main() -> std::io::Result<()> { - /// let sock = UnixStream::connect("/tmp/sock")?; - /// sock.set_mark(32)?; - /// Ok(()) - /// } - /// ``` - #[cfg(any(doc, target_os = "linux", target_os = "freebsd", target_os = "openbsd",))] - #[unstable(feature = "unix_set_mark", issue = "96467")] - pub fn set_mark(&self, mark: u32) -> io::Result<()> { - self.0.set_mark(mark) - } - - /// Returns the value of the `SO_ERROR` option. - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixStream; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UnixStream::connect("/tmp/sock")?; - /// if let Ok(Some(err)) = socket.take_error() { - /// println!("Got error: {err:?}"); - /// } - /// Ok(()) - /// } - /// ``` - /// - /// # Platform specific - /// On Redox this always returns `None`. - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn take_error(&self) -> io::Result> { - self.0.take_error() - } - - /// Shuts down the read, write, or both halves of this connection. - /// - /// This function will cause all pending and future I/O calls on the - /// specified portions to immediately return with an appropriate value - /// (see the documentation of [`Shutdown`]). - /// - /// # Examples - /// - /// ```no_run - /// use std::os::unix::net::UnixStream; - /// use std::net::Shutdown; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UnixStream::connect("/tmp/sock")?; - /// socket.shutdown(Shutdown::Both).expect("shutdown function failed"); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "unix_socket", since = "1.10.0")] - pub fn shutdown(&self, how: Shutdown) -> io::Result<()> { - self.0.shutdown(how) - } - - /// Receives data on the socket from the remote address to which it is - /// connected, without removing that data from the queue. On success, - /// returns the number of bytes peeked. - /// - /// Successive calls return the same data. This is accomplished by passing - /// `MSG_PEEK` as a flag to the underlying `recv` system call. - /// - /// # Examples - /// - /// ```no_run - /// #![feature(unix_socket_peek)] - /// - /// use std::os::unix::net::UnixStream; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UnixStream::connect("/tmp/sock")?; - /// let mut buf = [0; 10]; - /// let len = socket.peek(&mut buf).expect("peek failed"); - /// Ok(()) - /// } - /// ``` - #[unstable(feature = "unix_socket_peek", issue = "76923")] - pub fn peek(&self, buf: &mut [u8]) -> io::Result { - self.0.peek(buf) - } - - /// Receives data and ancillary data from socket. - /// - /// On success, returns the number of bytes read. - /// - /// # Examples - /// - #[cfg_attr(any(target_os = "android", target_os = "linux"), doc = "```no_run")] - #[cfg_attr(not(any(target_os = "android", target_os = "linux")), doc = "```ignore")] - /// #![feature(unix_socket_ancillary_data)] - /// use std::os::unix::net::{UnixStream, SocketAncillary, AncillaryData}; - /// use std::io::IoSliceMut; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UnixStream::connect("/tmp/sock")?; - /// let mut buf1 = [1; 8]; - /// let mut buf2 = [2; 16]; - /// let mut buf3 = [3; 8]; - /// let mut bufs = &mut [ - /// IoSliceMut::new(&mut buf1), - /// IoSliceMut::new(&mut buf2), - /// IoSliceMut::new(&mut buf3), - /// ][..]; - /// let mut fds = [0; 8]; - /// let mut ancillary_buffer = [0; 128]; - /// let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]); - /// let size = socket.recv_vectored_with_ancillary(bufs, &mut ancillary)?; - /// println!("received {size}"); - /// for ancillary_result in ancillary.messages() { - /// if let AncillaryData::ScmRights(scm_rights) = ancillary_result.unwrap() { - /// for fd in scm_rights { - /// println!("receive file descriptor: {fd}"); - /// } - /// } - /// } - /// Ok(()) - /// } - /// ``` - #[cfg(any(doc, target_os = "android", target_os = "linux"))] - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn recv_vectored_with_ancillary( - &self, - bufs: &mut [IoSliceMut<'_>], - ancillary: &mut SocketAncillary<'_>, - ) -> io::Result { - let (count, _, _) = recv_vectored_with_ancillary_from(&self.0, bufs, ancillary)?; - - Ok(count) - } - - /// Sends data and ancillary data on the socket. - /// - /// On success, returns the number of bytes written. - /// - /// # Examples - /// - #[cfg_attr(any(target_os = "android", target_os = "linux"), doc = "```no_run")] - #[cfg_attr(not(any(target_os = "android", target_os = "linux")), doc = "```ignore")] - /// #![feature(unix_socket_ancillary_data)] - /// use std::os::unix::net::{UnixStream, SocketAncillary}; - /// use std::io::IoSlice; - /// - /// fn main() -> std::io::Result<()> { - /// let socket = UnixStream::connect("/tmp/sock")?; - /// let buf1 = [1; 8]; - /// let buf2 = [2; 16]; - /// let buf3 = [3; 8]; - /// let bufs = &[ - /// IoSlice::new(&buf1), - /// IoSlice::new(&buf2), - /// IoSlice::new(&buf3), - /// ][..]; - /// let fds = [0, 1, 2]; - /// let mut ancillary_buffer = [0; 128]; - /// let mut ancillary = SocketAncillary::new(&mut ancillary_buffer[..]); - /// ancillary.add_fds(&fds[..]); - /// socket.send_vectored_with_ancillary(bufs, &mut ancillary) - /// .expect("send_vectored_with_ancillary function failed"); - /// Ok(()) - /// } - /// ``` - #[cfg(any(doc, target_os = "android", target_os = "linux"))] - #[unstable(feature = "unix_socket_ancillary_data", issue = "76915")] - pub fn send_vectored_with_ancillary( - &self, - bufs: &[IoSlice<'_>], - ancillary: &mut SocketAncillary<'_>, - ) -> io::Result { - send_vectored_with_ancillary_to(&self.0, None, bufs, ancillary) - } -} - -#[stable(feature = "unix_socket", since = "1.10.0")] -impl io::Read for UnixStream { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - io::Read::read(&mut &*self, buf) - } - - fn read_buf(&mut self, buf: io::BorrowedCursor<'_>) -> io::Result<()> { - io::Read::read_buf(&mut &*self, buf) - } - - fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - io::Read::read_vectored(&mut &*self, bufs) - } - - #[inline] - fn is_read_vectored(&self) -> bool { - io::Read::is_read_vectored(&&*self) - } -} - -#[stable(feature = "unix_socket", since = "1.10.0")] -impl<'a> io::Read for &'a UnixStream { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - self.0.read(buf) - } - - fn read_buf(&mut self, buf: io::BorrowedCursor<'_>) -> io::Result<()> { - self.0.read_buf(buf) - } - - fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - self.0.read_vectored(bufs) - } - - #[inline] - fn is_read_vectored(&self) -> bool { - self.0.is_read_vectored() - } -} - -#[stable(feature = "unix_socket", since = "1.10.0")] -impl io::Write for UnixStream { - fn write(&mut self, buf: &[u8]) -> io::Result { - io::Write::write(&mut &*self, buf) - } - - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - io::Write::write_vectored(&mut &*self, bufs) - } - - #[inline] - fn is_write_vectored(&self) -> bool { - io::Write::is_write_vectored(&&*self) - } - - fn flush(&mut self) -> io::Result<()> { - io::Write::flush(&mut &*self) - } -} - -#[stable(feature = "unix_socket", since = "1.10.0")] -impl<'a> io::Write for &'a UnixStream { - fn write(&mut self, buf: &[u8]) -> io::Result { - self.0.write(buf) - } - - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - self.0.write_vectored(bufs) - } - - #[inline] - fn is_write_vectored(&self) -> bool { - self.0.is_write_vectored() - } - - #[inline] - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -#[stable(feature = "unix_socket", since = "1.10.0")] -impl AsRawFd for UnixStream { - #[inline] - fn as_raw_fd(&self) -> RawFd { - self.0.as_raw_fd() - } -} - -#[stable(feature = "unix_socket", since = "1.10.0")] -impl FromRawFd for UnixStream { - #[inline] - unsafe fn from_raw_fd(fd: RawFd) -> UnixStream { - UnixStream(Socket::from_inner(FromInner::from_inner(OwnedFd::from_raw_fd(fd)))) - } -} - -#[stable(feature = "unix_socket", since = "1.10.0")] -impl IntoRawFd for UnixStream { - #[inline] - fn into_raw_fd(self) -> RawFd { - self.0.into_raw_fd() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsFd for UnixStream { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - self.0.as_fd() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for OwnedFd { - /// Takes ownership of a [`UnixStream`]'s socket file descriptor. - #[inline] - fn from(unix_stream: UnixStream) -> OwnedFd { - unsafe { OwnedFd::from_raw_fd(unix_stream.into_raw_fd()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for UnixStream { - #[inline] - fn from(owned: OwnedFd) -> Self { - unsafe { Self::from_raw_fd(owned.into_raw_fd()) } - } -} - -impl AsInner for UnixStream { - #[inline] - fn as_inner(&self) -> &Socket { - &self.0 - } -} diff --git a/library/std/src/os/unix/net/tests.rs b/library/std/src/os/unix/net/tests.rs deleted file mode 100644 index e456e41b21c88..0000000000000 --- a/library/std/src/os/unix/net/tests.rs +++ /dev/null @@ -1,778 +0,0 @@ -use super::*; -use crate::io::prelude::*; -use crate::io::{self, ErrorKind, IoSlice, IoSliceMut}; -#[cfg(any(target_os = "android", target_os = "linux"))] -use crate::os::unix::io::AsRawFd; -use crate::sys_common::io::test::tmpdir; -use crate::thread; -use crate::time::Duration; - -#[cfg(target_os = "android")] -use crate::os::android::net::{SocketAddrExt, UnixSocketExt}; - -#[cfg(target_os = "linux")] -use crate::os::linux::net::{SocketAddrExt, UnixSocketExt}; - -macro_rules! or_panic { - ($e:expr) => { - match $e { - Ok(e) => e, - Err(e) => panic!("{e}"), - } - }; -} - -#[test] -#[cfg_attr(target_os = "android", ignore)] // Android SELinux rules prevent creating Unix sockets -fn basic() { - let dir = tmpdir(); - let socket_path = dir.path().join("sock"); - let msg1 = b"hello"; - let msg2 = b"world!"; - - let listener = or_panic!(UnixListener::bind(&socket_path)); - let thread = thread::spawn(move || { - let mut stream = or_panic!(listener.accept()).0; - let mut buf = [0; 5]; - or_panic!(stream.read(&mut buf)); - assert_eq!(&msg1[..], &buf[..]); - or_panic!(stream.write_all(msg2)); - }); - - let mut stream = or_panic!(UnixStream::connect(&socket_path)); - assert_eq!(Some(&*socket_path), stream.peer_addr().unwrap().as_pathname()); - or_panic!(stream.write_all(msg1)); - let mut buf = vec![]; - or_panic!(stream.read_to_end(&mut buf)); - assert_eq!(&msg2[..], &buf[..]); - drop(stream); - - thread.join().unwrap(); -} - -#[test] -fn vectored() { - let (mut s1, mut s2) = or_panic!(UnixStream::pair()); - - let len = or_panic!(s1.write_vectored(&[ - IoSlice::new(b"hello"), - IoSlice::new(b" "), - IoSlice::new(b"world!") - ],)); - assert_eq!(len, 12); - - let mut buf1 = [0; 6]; - let mut buf2 = [0; 7]; - let len = - or_panic!(s2.read_vectored(&mut [IoSliceMut::new(&mut buf1), IoSliceMut::new(&mut buf2)],)); - assert_eq!(len, 12); - assert_eq!(&buf1, b"hello "); - assert_eq!(&buf2, b"world!\0"); -} - -#[test] -fn pair() { - let msg1 = b"hello"; - let msg2 = b"world!"; - - let (mut s1, mut s2) = or_panic!(UnixStream::pair()); - let thread = thread::spawn(move || { - // s1 must be moved in or the test will hang! - let mut buf = [0; 5]; - or_panic!(s1.read(&mut buf)); - assert_eq!(&msg1[..], &buf[..]); - or_panic!(s1.write_all(msg2)); - }); - - or_panic!(s2.write_all(msg1)); - let mut buf = vec![]; - or_panic!(s2.read_to_end(&mut buf)); - assert_eq!(&msg2[..], &buf[..]); - drop(s2); - - thread.join().unwrap(); -} - -#[test] -#[cfg_attr(target_os = "android", ignore)] // Android SELinux rules prevent creating Unix sockets -fn try_clone() { - let dir = tmpdir(); - let socket_path = dir.path().join("sock"); - let msg1 = b"hello"; - let msg2 = b"world"; - - let listener = or_panic!(UnixListener::bind(&socket_path)); - let thread = thread::spawn(move || { - let mut stream = or_panic!(listener.accept()).0; - or_panic!(stream.write_all(msg1)); - or_panic!(stream.write_all(msg2)); - }); - - let mut stream = or_panic!(UnixStream::connect(&socket_path)); - let mut stream2 = or_panic!(stream.try_clone()); - - let mut buf = [0; 5]; - or_panic!(stream.read(&mut buf)); - assert_eq!(&msg1[..], &buf[..]); - or_panic!(stream2.read(&mut buf)); - assert_eq!(&msg2[..], &buf[..]); - - thread.join().unwrap(); -} - -#[test] -#[cfg_attr(target_os = "android", ignore)] // Android SELinux rules prevent creating Unix sockets -fn iter() { - let dir = tmpdir(); - let socket_path = dir.path().join("sock"); - - let listener = or_panic!(UnixListener::bind(&socket_path)); - let thread = thread::spawn(move || { - for stream in listener.incoming().take(2) { - let mut stream = or_panic!(stream); - let mut buf = [0]; - or_panic!(stream.read(&mut buf)); - } - }); - - for _ in 0..2 { - let mut stream = or_panic!(UnixStream::connect(&socket_path)); - or_panic!(stream.write_all(&[0])); - } - - thread.join().unwrap(); -} - -#[test] -fn long_path() { - let dir = tmpdir(); - let socket_path = dir.path().join( - "asdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfasdfa\ - sasdfasdfasdasdfasdfasdfadfasdfasdfasdfasdfasdf", - ); - match UnixStream::connect(&socket_path) { - Err(ref e) if e.kind() == io::ErrorKind::InvalidInput => {} - Err(e) => panic!("unexpected error {e}"), - Ok(_) => panic!("unexpected success"), - } - - match UnixListener::bind(&socket_path) { - Err(ref e) if e.kind() == io::ErrorKind::InvalidInput => {} - Err(e) => panic!("unexpected error {e}"), - Ok(_) => panic!("unexpected success"), - } - - match UnixDatagram::bind(&socket_path) { - Err(ref e) if e.kind() == io::ErrorKind::InvalidInput => {} - Err(e) => panic!("unexpected error {e}"), - Ok(_) => panic!("unexpected success"), - } -} - -#[test] -#[cfg(not(target_os = "nto"))] -#[cfg_attr(target_os = "android", ignore)] // Android SELinux rules prevent creating Unix sockets -fn timeouts() { - let dir = tmpdir(); - let socket_path = dir.path().join("sock"); - - let _listener = or_panic!(UnixListener::bind(&socket_path)); - - let stream = or_panic!(UnixStream::connect(&socket_path)); - let dur = Duration::new(15410, 0); - - assert_eq!(None, or_panic!(stream.read_timeout())); - - or_panic!(stream.set_read_timeout(Some(dur))); - assert_eq!(Some(dur), or_panic!(stream.read_timeout())); - - assert_eq!(None, or_panic!(stream.write_timeout())); - - or_panic!(stream.set_write_timeout(Some(dur))); - assert_eq!(Some(dur), or_panic!(stream.write_timeout())); - - or_panic!(stream.set_read_timeout(None)); - assert_eq!(None, or_panic!(stream.read_timeout())); - - or_panic!(stream.set_write_timeout(None)); - assert_eq!(None, or_panic!(stream.write_timeout())); -} - -#[test] -#[cfg_attr(target_os = "android", ignore)] // Android SELinux rules prevent creating Unix sockets -fn test_read_timeout() { - let dir = tmpdir(); - let socket_path = dir.path().join("sock"); - - let _listener = or_panic!(UnixListener::bind(&socket_path)); - - let mut stream = or_panic!(UnixStream::connect(&socket_path)); - or_panic!(stream.set_read_timeout(Some(Duration::from_millis(1000)))); - - let mut buf = [0; 10]; - let kind = stream.read_exact(&mut buf).err().expect("expected error").kind(); - assert!( - kind == ErrorKind::WouldBlock || kind == ErrorKind::TimedOut, - "unexpected_error: {:?}", - kind - ); -} - -#[test] -#[cfg_attr(target_os = "android", ignore)] // Android SELinux rules prevent creating Unix sockets -fn test_read_with_timeout() { - let dir = tmpdir(); - let socket_path = dir.path().join("sock"); - - let listener = or_panic!(UnixListener::bind(&socket_path)); - - let mut stream = or_panic!(UnixStream::connect(&socket_path)); - or_panic!(stream.set_read_timeout(Some(Duration::from_millis(1000)))); - - let mut other_end = or_panic!(listener.accept()).0; - or_panic!(other_end.write_all(b"hello world")); - - let mut buf = [0; 11]; - or_panic!(stream.read(&mut buf)); - assert_eq!(b"hello world", &buf[..]); - - let kind = stream.read_exact(&mut buf).err().expect("expected error").kind(); - assert!( - kind == ErrorKind::WouldBlock || kind == ErrorKind::TimedOut, - "unexpected_error: {:?}", - kind - ); -} - -// Ensure the `set_read_timeout` and `set_write_timeout` calls return errors -// when passed zero Durations -#[test] -#[cfg_attr(target_os = "android", ignore)] // Android SELinux rules prevent creating Unix sockets -fn test_unix_stream_timeout_zero_duration() { - let dir = tmpdir(); - let socket_path = dir.path().join("sock"); - - let listener = or_panic!(UnixListener::bind(&socket_path)); - let stream = or_panic!(UnixStream::connect(&socket_path)); - - let result = stream.set_write_timeout(Some(Duration::new(0, 0))); - let err = result.unwrap_err(); - assert_eq!(err.kind(), ErrorKind::InvalidInput); - - let result = stream.set_read_timeout(Some(Duration::new(0, 0))); - let err = result.unwrap_err(); - assert_eq!(err.kind(), ErrorKind::InvalidInput); - - drop(listener); -} - -#[test] -#[cfg_attr(target_os = "android", ignore)] // Android SELinux rules prevent creating Unix sockets -fn test_unix_datagram() { - let dir = tmpdir(); - let path1 = dir.path().join("sock1"); - let path2 = dir.path().join("sock2"); - - let sock1 = or_panic!(UnixDatagram::bind(&path1)); - let sock2 = or_panic!(UnixDatagram::bind(&path2)); - - let msg = b"hello world"; - or_panic!(sock1.send_to(msg, &path2)); - let mut buf = [0; 11]; - or_panic!(sock2.recv_from(&mut buf)); - assert_eq!(msg, &buf[..]); -} - -#[test] -#[cfg_attr(target_os = "android", ignore)] // Android SELinux rules prevent creating Unix sockets -fn test_unnamed_unix_datagram() { - let dir = tmpdir(); - let path1 = dir.path().join("sock1"); - - let sock1 = or_panic!(UnixDatagram::bind(&path1)); - let sock2 = or_panic!(UnixDatagram::unbound()); - - let msg = b"hello world"; - or_panic!(sock2.send_to(msg, &path1)); - let mut buf = [0; 11]; - let (usize, addr) = or_panic!(sock1.recv_from(&mut buf)); - assert_eq!(usize, 11); - assert!(addr.is_unnamed()); - assert_eq!(msg, &buf[..]); -} - -#[test] -#[cfg_attr(target_os = "android", ignore)] // Android SELinux rules prevent creating Unix sockets -fn test_unix_datagram_connect_to_recv_addr() { - let dir = tmpdir(); - let path1 = dir.path().join("sock1"); - let path2 = dir.path().join("sock2"); - - let sock1 = or_panic!(UnixDatagram::bind(&path1)); - let sock2 = or_panic!(UnixDatagram::bind(&path2)); - - let msg = b"hello world"; - let sock1_addr = or_panic!(sock1.local_addr()); - or_panic!(sock2.send_to_addr(msg, &sock1_addr)); - let mut buf = [0; 11]; - let (_, addr) = or_panic!(sock1.recv_from(&mut buf)); - - let new_msg = b"hello back"; - let mut new_buf = [0; 10]; - or_panic!(sock2.connect_addr(&addr)); - or_panic!(sock2.send(new_msg)); // set by connect_addr - let usize = or_panic!(sock2.recv(&mut new_buf)); - assert_eq!(usize, 10); - assert_eq!(new_msg, &new_buf[..]); -} - -#[test] -#[cfg_attr(target_os = "android", ignore)] // Android SELinux rules prevent creating Unix sockets -fn test_connect_unix_datagram() { - let dir = tmpdir(); - let path1 = dir.path().join("sock1"); - let path2 = dir.path().join("sock2"); - - let bsock1 = or_panic!(UnixDatagram::bind(&path1)); - let bsock2 = or_panic!(UnixDatagram::bind(&path2)); - let sock = or_panic!(UnixDatagram::unbound()); - or_panic!(sock.connect(&path1)); - - // Check send() - let msg = b"hello there"; - or_panic!(sock.send(msg)); - let mut buf = [0; 11]; - let (usize, addr) = or_panic!(bsock1.recv_from(&mut buf)); - assert_eq!(usize, 11); - assert!(addr.is_unnamed()); - assert_eq!(msg, &buf[..]); - - // Changing default socket works too - or_panic!(sock.connect(&path2)); - or_panic!(sock.send(msg)); - or_panic!(bsock2.recv_from(&mut buf)); -} - -#[test] -#[cfg_attr(target_os = "android", ignore)] // Android SELinux rules prevent creating Unix sockets -fn test_unix_datagram_recv() { - let dir = tmpdir(); - let path1 = dir.path().join("sock1"); - - let sock1 = or_panic!(UnixDatagram::bind(&path1)); - let sock2 = or_panic!(UnixDatagram::unbound()); - or_panic!(sock2.connect(&path1)); - - let msg = b"hello world"; - or_panic!(sock2.send(msg)); - let mut buf = [0; 11]; - let size = or_panic!(sock1.recv(&mut buf)); - assert_eq!(size, 11); - assert_eq!(msg, &buf[..]); -} - -#[test] -fn datagram_pair() { - let msg1 = b"hello"; - let msg2 = b"world!"; - - let (s1, s2) = or_panic!(UnixDatagram::pair()); - let thread = thread::spawn(move || { - // s1 must be moved in or the test will hang! - let mut buf = [0; 5]; - or_panic!(s1.recv(&mut buf)); - assert_eq!(&msg1[..], &buf[..]); - or_panic!(s1.send(msg2)); - }); - - or_panic!(s2.send(msg1)); - let mut buf = [0; 6]; - or_panic!(s2.recv(&mut buf)); - assert_eq!(&msg2[..], &buf[..]); - drop(s2); - - thread.join().unwrap(); -} - -// Ensure the `set_read_timeout` and `set_write_timeout` calls return errors -// when passed zero Durations -#[test] -#[cfg_attr(target_os = "android", ignore)] // Android SELinux rules prevent creating Unix sockets -fn test_unix_datagram_timeout_zero_duration() { - let dir = tmpdir(); - let path = dir.path().join("sock"); - - let datagram = or_panic!(UnixDatagram::bind(&path)); - - let result = datagram.set_write_timeout(Some(Duration::new(0, 0))); - let err = result.unwrap_err(); - assert_eq!(err.kind(), ErrorKind::InvalidInput); - - let result = datagram.set_read_timeout(Some(Duration::new(0, 0))); - let err = result.unwrap_err(); - assert_eq!(err.kind(), ErrorKind::InvalidInput); -} - -#[test] -fn abstract_namespace_not_allowed_connect() { - assert!(UnixStream::connect("\0asdf").is_err()); -} - -#[cfg(any(target_os = "android", target_os = "linux"))] -#[test] -fn test_abstract_stream_connect() { - let msg1 = b"hello"; - let msg2 = b"world"; - - let socket_addr = or_panic!(SocketAddr::from_abstract_name(b"name")); - let listener = or_panic!(UnixListener::bind_addr(&socket_addr)); - - let thread = thread::spawn(move || { - let mut stream = or_panic!(listener.accept()).0; - let mut buf = [0; 5]; - or_panic!(stream.read(&mut buf)); - assert_eq!(&msg1[..], &buf[..]); - or_panic!(stream.write_all(msg2)); - }); - - let mut stream = or_panic!(UnixStream::connect_addr(&socket_addr)); - - let peer = or_panic!(stream.peer_addr()); - assert_eq!(peer.as_abstract_name().unwrap(), b"name"); - - or_panic!(stream.write_all(msg1)); - let mut buf = vec![]; - or_panic!(stream.read_to_end(&mut buf)); - assert_eq!(&msg2[..], &buf[..]); - drop(stream); - - thread.join().unwrap(); -} - -#[cfg(any(target_os = "android", target_os = "linux"))] -#[test] -fn test_abstract_stream_iter() { - let addr = or_panic!(SocketAddr::from_abstract_name(b"hidden")); - let listener = or_panic!(UnixListener::bind_addr(&addr)); - - let thread = thread::spawn(move || { - for stream in listener.incoming().take(2) { - let mut stream = or_panic!(stream); - let mut buf = [0]; - or_panic!(stream.read(&mut buf)); - } - }); - - for _ in 0..2 { - let mut stream = or_panic!(UnixStream::connect_addr(&addr)); - or_panic!(stream.write_all(&[0])); - } - - thread.join().unwrap(); -} - -#[cfg(any(target_os = "android", target_os = "linux"))] -#[test] -fn test_abstract_datagram_bind_send_to_addr() { - let addr1 = or_panic!(SocketAddr::from_abstract_name(b"ns1")); - let sock1 = or_panic!(UnixDatagram::bind_addr(&addr1)); - - let local = or_panic!(sock1.local_addr()); - assert_eq!(local.as_abstract_name().unwrap(), b"ns1"); - - let addr2 = or_panic!(SocketAddr::from_abstract_name(b"ns2")); - let sock2 = or_panic!(UnixDatagram::bind_addr(&addr2)); - - let msg = b"hello world"; - or_panic!(sock1.send_to_addr(msg, &addr2)); - let mut buf = [0; 11]; - let (len, addr) = or_panic!(sock2.recv_from(&mut buf)); - assert_eq!(msg, &buf[..]); - assert_eq!(len, 11); - assert_eq!(addr.as_abstract_name().unwrap(), b"ns1"); -} - -#[cfg(any(target_os = "android", target_os = "linux"))] -#[test] -fn test_abstract_datagram_connect_addr() { - let addr1 = or_panic!(SocketAddr::from_abstract_name(b"ns3")); - let bsock1 = or_panic!(UnixDatagram::bind_addr(&addr1)); - - let sock = or_panic!(UnixDatagram::unbound()); - or_panic!(sock.connect_addr(&addr1)); - - let msg = b"hello world"; - or_panic!(sock.send(msg)); - let mut buf = [0; 11]; - let (len, addr) = or_panic!(bsock1.recv_from(&mut buf)); - assert_eq!(len, 11); - assert_eq!(addr.is_unnamed(), true); - assert_eq!(msg, &buf[..]); - - let addr2 = or_panic!(SocketAddr::from_abstract_name(b"ns4")); - let bsock2 = or_panic!(UnixDatagram::bind_addr(&addr2)); - - or_panic!(sock.connect_addr(&addr2)); - or_panic!(sock.send(msg)); - or_panic!(bsock2.recv_from(&mut buf)); -} - -#[cfg(any(target_os = "android", target_os = "linux"))] -#[test] -fn test_abstract_name_too_long() { - match SocketAddr::from_abstract_name( - b"abcdefghijklmnopqrstuvwxyzabcdefghijklmn\ - opqrstuvwxyzabcdefghijklmnopqrstuvwxyzabcdefghi\ - jklmnopqrstuvwxyzabcdefghijklmnopqrstuvwxyz", - ) { - Err(ref e) if e.kind() == io::ErrorKind::InvalidInput => {} - Err(e) => panic!("unexpected error {e}"), - Ok(_) => panic!("unexpected success"), - } -} - -#[cfg(any(target_os = "android", target_os = "linux"))] -#[test] -fn test_abstract_no_pathname_and_not_unnamed() { - let name = b"local"; - let addr = or_panic!(SocketAddr::from_abstract_name(name)); - assert_eq!(addr.as_pathname(), None); - assert_eq!(addr.as_abstract_name(), Some(&name[..])); - assert_eq!(addr.is_unnamed(), false); -} - -#[test] -#[cfg_attr(target_os = "android", ignore)] // Android SELinux rules prevent creating Unix sockets -fn test_unix_stream_peek() { - let (txdone, rxdone) = crate::sync::mpsc::channel(); - - let dir = tmpdir(); - let path = dir.path().join("sock"); - - let listener = or_panic!(UnixListener::bind(&path)); - let thread = thread::spawn(move || { - let mut stream = or_panic!(listener.accept()).0; - or_panic!(stream.write_all(&[1, 3, 3, 7])); - or_panic!(rxdone.recv()); - }); - - let mut stream = or_panic!(UnixStream::connect(&path)); - let mut buf = [0; 10]; - for _ in 0..2 { - assert_eq!(or_panic!(stream.peek(&mut buf)), 4); - } - assert_eq!(or_panic!(stream.read(&mut buf)), 4); - - or_panic!(stream.set_nonblocking(true)); - match stream.peek(&mut buf) { - Ok(_) => panic!("expected error"), - Err(ref e) if e.kind() == ErrorKind::WouldBlock => {} - Err(e) => panic!("unexpected error: {e}"), - } - - or_panic!(txdone.send(())); - thread.join().unwrap(); -} - -#[test] -#[cfg_attr(target_os = "android", ignore)] // Android SELinux rules prevent creating Unix sockets -fn test_unix_datagram_peek() { - let dir = tmpdir(); - let path1 = dir.path().join("sock"); - - let sock1 = or_panic!(UnixDatagram::bind(&path1)); - let sock2 = or_panic!(UnixDatagram::unbound()); - or_panic!(sock2.connect(&path1)); - - let msg = b"hello world"; - or_panic!(sock2.send(msg)); - for _ in 0..2 { - let mut buf = [0; 11]; - let size = or_panic!(sock1.peek(&mut buf)); - assert_eq!(size, 11); - assert_eq!(msg, &buf[..]); - } - - let mut buf = [0; 11]; - let size = or_panic!(sock1.recv(&mut buf)); - assert_eq!(size, 11); - assert_eq!(msg, &buf[..]); -} - -#[test] -#[cfg_attr(target_os = "android", ignore)] // Android SELinux rules prevent creating Unix sockets -fn test_unix_datagram_peek_from() { - let dir = tmpdir(); - let path1 = dir.path().join("sock"); - - let sock1 = or_panic!(UnixDatagram::bind(&path1)); - let sock2 = or_panic!(UnixDatagram::unbound()); - or_panic!(sock2.connect(&path1)); - - let msg = b"hello world"; - or_panic!(sock2.send(msg)); - for _ in 0..2 { - let mut buf = [0; 11]; - let (size, _) = or_panic!(sock1.peek_from(&mut buf)); - assert_eq!(size, 11); - assert_eq!(msg, &buf[..]); - } - - let mut buf = [0; 11]; - let size = or_panic!(sock1.recv(&mut buf)); - assert_eq!(size, 11); - assert_eq!(msg, &buf[..]); -} - -#[cfg(any(target_os = "android", target_os = "linux"))] -#[test] -fn test_send_vectored_fds_unix_stream() { - let (s1, s2) = or_panic!(UnixStream::pair()); - - let buf1 = [1; 8]; - let bufs_send = &[IoSlice::new(&buf1[..])][..]; - - let mut ancillary1_buffer = [0; 128]; - let mut ancillary1 = SocketAncillary::new(&mut ancillary1_buffer[..]); - assert!(ancillary1.add_fds(&[s1.as_raw_fd()][..])); - - let usize = or_panic!(s1.send_vectored_with_ancillary(&bufs_send, &mut ancillary1)); - assert_eq!(usize, 8); - - let mut buf2 = [0; 8]; - let mut bufs_recv = &mut [IoSliceMut::new(&mut buf2[..])][..]; - - let mut ancillary2_buffer = [0; 128]; - let mut ancillary2 = SocketAncillary::new(&mut ancillary2_buffer[..]); - - let usize = or_panic!(s2.recv_vectored_with_ancillary(&mut bufs_recv, &mut ancillary2)); - assert_eq!(usize, 8); - assert_eq!(buf1, buf2); - - let mut ancillary_data_vec = Vec::from_iter(ancillary2.messages()); - assert_eq!(ancillary_data_vec.len(), 1); - if let AncillaryData::ScmRights(scm_rights) = ancillary_data_vec.pop().unwrap().unwrap() { - let fd_vec = Vec::from_iter(scm_rights); - assert_eq!(fd_vec.len(), 1); - unsafe { - libc::close(fd_vec[0]); - } - } else { - unreachable!("must be ScmRights"); - } -} - -#[cfg(any(target_os = "android", target_os = "linux"))] -#[test] -#[cfg_attr(target_os = "android", ignore)] // Android SELinux rules prevent creating Unix sockets -fn test_send_vectored_with_ancillary_to_unix_datagram() { - fn getpid() -> libc::pid_t { - unsafe { libc::getpid() } - } - - fn getuid() -> libc::uid_t { - unsafe { libc::getuid() } - } - - fn getgid() -> libc::gid_t { - unsafe { libc::getgid() } - } - - let dir = tmpdir(); - let path1 = dir.path().join("sock1"); - let path2 = dir.path().join("sock2"); - - let bsock1 = or_panic!(UnixDatagram::bind(&path1)); - let bsock2 = or_panic!(UnixDatagram::bind(&path2)); - - or_panic!(bsock2.set_passcred(true)); - - let buf1 = [1; 8]; - let bufs_send = &[IoSlice::new(&buf1[..])][..]; - - let mut ancillary1_buffer = [0; 128]; - let mut ancillary1 = SocketAncillary::new(&mut ancillary1_buffer[..]); - let mut cred1 = SocketCred::new(); - cred1.set_pid(getpid()); - cred1.set_uid(getuid()); - cred1.set_gid(getgid()); - assert!(ancillary1.add_creds(&[cred1.clone()][..])); - - let usize = - or_panic!(bsock1.send_vectored_with_ancillary_to(&bufs_send, &mut ancillary1, &path2)); - assert_eq!(usize, 8); - - let mut buf2 = [0; 8]; - let mut bufs_recv = &mut [IoSliceMut::new(&mut buf2[..])][..]; - - let mut ancillary2_buffer = [0; 128]; - let mut ancillary2 = SocketAncillary::new(&mut ancillary2_buffer[..]); - - let (usize, truncated, _addr) = - or_panic!(bsock2.recv_vectored_with_ancillary_from(&mut bufs_recv, &mut ancillary2)); - assert_eq!(ancillary2.truncated(), false); - assert_eq!(usize, 8); - assert_eq!(truncated, false); - assert_eq!(buf1, buf2); - - let mut ancillary_data_vec = Vec::from_iter(ancillary2.messages()); - assert_eq!(ancillary_data_vec.len(), 1); - if let AncillaryData::ScmCredentials(scm_credentials) = - ancillary_data_vec.pop().unwrap().unwrap() - { - let cred_vec = Vec::from_iter(scm_credentials); - assert_eq!(cred_vec.len(), 1); - assert_eq!(cred1.get_pid(), cred_vec[0].get_pid()); - assert_eq!(cred1.get_uid(), cred_vec[0].get_uid()); - assert_eq!(cred1.get_gid(), cred_vec[0].get_gid()); - } else { - unreachable!("must be ScmCredentials"); - } -} - -#[cfg(any(target_os = "android", target_os = "linux"))] -#[test] -#[cfg_attr(target_os = "android", ignore)] // Android SELinux rules prevent creating Unix sockets -fn test_send_vectored_with_ancillary_unix_datagram() { - let dir = tmpdir(); - let path1 = dir.path().join("sock1"); - let path2 = dir.path().join("sock2"); - - let bsock1 = or_panic!(UnixDatagram::bind(&path1)); - let bsock2 = or_panic!(UnixDatagram::bind(&path2)); - - let buf1 = [1; 8]; - let bufs_send = &[IoSlice::new(&buf1[..])][..]; - - let mut ancillary1_buffer = [0; 128]; - let mut ancillary1 = SocketAncillary::new(&mut ancillary1_buffer[..]); - assert!(ancillary1.add_fds(&[bsock1.as_raw_fd()][..])); - - or_panic!(bsock1.connect(&path2)); - let usize = or_panic!(bsock1.send_vectored_with_ancillary(&bufs_send, &mut ancillary1)); - assert_eq!(usize, 8); - - let mut buf2 = [0; 8]; - let mut bufs_recv = &mut [IoSliceMut::new(&mut buf2[..])][..]; - - let mut ancillary2_buffer = [0; 128]; - let mut ancillary2 = SocketAncillary::new(&mut ancillary2_buffer[..]); - - let (usize, truncated) = - or_panic!(bsock2.recv_vectored_with_ancillary(&mut bufs_recv, &mut ancillary2)); - assert_eq!(usize, 8); - assert_eq!(truncated, false); - assert_eq!(buf1, buf2); - - let mut ancillary_data_vec = Vec::from_iter(ancillary2.messages()); - assert_eq!(ancillary_data_vec.len(), 1); - if let AncillaryData::ScmRights(scm_rights) = ancillary_data_vec.pop().unwrap().unwrap() { - let fd_vec = Vec::from_iter(scm_rights); - assert_eq!(fd_vec.len(), 1); - unsafe { - libc::close(fd_vec[0]); - } - } else { - unreachable!("must be ScmRights"); - } -} diff --git a/library/std/src/os/unix/net/ucred.rs b/library/std/src/os/unix/net/ucred.rs deleted file mode 100644 index 1497e730bbf15..0000000000000 --- a/library/std/src/os/unix/net/ucred.rs +++ /dev/null @@ -1,136 +0,0 @@ -// NOTE: Code in this file is heavily based on work done in PR 13 from the tokio-uds repository on -// GitHub. -// -// For reference, the link is here: https://github.com/tokio-rs/tokio-uds/pull/13 -// Credit to Martin Habovštiak (GitHub username Kixunil) and contributors for this work. - -use libc::{gid_t, pid_t, uid_t}; - -/// Credentials for a UNIX process for credentials passing. -#[unstable(feature = "peer_credentials_unix_socket", issue = "42839", reason = "unstable")] -#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)] -pub struct UCred { - /// The UID part of the peer credential. This is the effective UID of the process at the domain - /// socket's endpoint. - pub uid: uid_t, - /// The GID part of the peer credential. This is the effective GID of the process at the domain - /// socket's endpoint. - pub gid: gid_t, - /// The PID part of the peer credential. This field is optional because the PID part of the - /// peer credentials is not supported on every platform. On platforms where the mechanism to - /// discover the PID exists, this field will be populated to the PID of the process at the - /// domain socket's endpoint. Otherwise, it will be set to None. - pub pid: Option, -} - -#[cfg(any(target_os = "android", target_os = "linux"))] -pub(super) use self::impl_linux::peer_cred; - -#[cfg(any( - target_os = "dragonfly", - target_os = "freebsd", - target_os = "openbsd", - target_os = "netbsd", - target_os = "nto" -))] -pub(super) use self::impl_bsd::peer_cred; - -#[cfg(target_vendor = "apple")] -pub(super) use self::impl_apple::peer_cred; - -#[cfg(any(target_os = "linux", target_os = "android"))] -mod impl_linux { - use super::UCred; - use crate::os::unix::io::AsRawFd; - use crate::os::unix::net::UnixStream; - use crate::{io, mem}; - use libc::{c_void, getsockopt, socklen_t, ucred, SOL_SOCKET, SO_PEERCRED}; - - pub fn peer_cred(socket: &UnixStream) -> io::Result { - let ucred_size = mem::size_of::(); - - // Trivial sanity checks. - assert!(mem::size_of::() <= mem::size_of::()); - assert!(ucred_size <= u32::MAX as usize); - - let mut ucred_size = ucred_size as socklen_t; - let mut ucred: ucred = ucred { pid: 1, uid: 1, gid: 1 }; - - unsafe { - let ret = getsockopt( - socket.as_raw_fd(), - SOL_SOCKET, - SO_PEERCRED, - core::ptr::addr_of_mut!(ucred) as *mut c_void, - &mut ucred_size, - ); - - if ret == 0 && ucred_size as usize == mem::size_of::() { - Ok(UCred { uid: ucred.uid, gid: ucred.gid, pid: Some(ucred.pid) }) - } else { - Err(io::Error::last_os_error()) - } - } - } -} - -#[cfg(any( - target_os = "dragonfly", - target_os = "freebsd", - target_os = "openbsd", - target_os = "netbsd", - target_os = "nto", -))] -mod impl_bsd { - use super::UCred; - use crate::io; - use crate::os::unix::io::AsRawFd; - use crate::os::unix::net::UnixStream; - - pub fn peer_cred(socket: &UnixStream) -> io::Result { - let mut cred = UCred { uid: 1, gid: 1, pid: None }; - unsafe { - let ret = libc::getpeereid(socket.as_raw_fd(), &mut cred.uid, &mut cred.gid); - - if ret == 0 { Ok(cred) } else { Err(io::Error::last_os_error()) } - } - } -} - -#[cfg(target_vendor = "apple")] -mod impl_apple { - use super::UCred; - use crate::os::unix::io::AsRawFd; - use crate::os::unix::net::UnixStream; - use crate::{io, mem}; - use libc::{c_void, getpeereid, getsockopt, pid_t, socklen_t, LOCAL_PEERPID, SOL_LOCAL}; - - pub fn peer_cred(socket: &UnixStream) -> io::Result { - let mut cred = UCred { uid: 1, gid: 1, pid: None }; - unsafe { - let ret = getpeereid(socket.as_raw_fd(), &mut cred.uid, &mut cred.gid); - - if ret != 0 { - return Err(io::Error::last_os_error()); - } - - let mut pid: pid_t = 1; - let mut pid_size = mem::size_of::() as socklen_t; - - let ret = getsockopt( - socket.as_raw_fd(), - SOL_LOCAL, - LOCAL_PEERPID, - core::ptr::addr_of_mut!(pid) as *mut c_void, - &mut pid_size, - ); - - if ret == 0 && pid_size as usize == mem::size_of::() { - cred.pid = Some(pid); - Ok(cred) - } else { - Err(io::Error::last_os_error()) - } - } - } -} diff --git a/library/std/src/os/unix/net/ucred/tests.rs b/library/std/src/os/unix/net/ucred/tests.rs deleted file mode 100644 index a6cc81318fc08..0000000000000 --- a/library/std/src/os/unix/net/ucred/tests.rs +++ /dev/null @@ -1,37 +0,0 @@ -use crate::os::unix::net::UnixStream; -use libc::{getegid, geteuid, getpid}; - -#[test] -#[cfg(any( - target_os = "android", - target_os = "linux", - target_os = "dragonfly", - target_os = "freebsd", - target_os = "openbsd", - target_vendor = "apple", -))] -fn test_socket_pair() { - // Create two connected sockets and get their peer credentials. They should be equal. - let (sock_a, sock_b) = UnixStream::pair().unwrap(); - let (cred_a, cred_b) = (sock_a.peer_cred().unwrap(), sock_b.peer_cred().unwrap()); - assert_eq!(cred_a, cred_b); - - // Check that the UID and GIDs match up. - let uid = unsafe { geteuid() }; - let gid = unsafe { getegid() }; - assert_eq!(cred_a.uid, uid); - assert_eq!(cred_a.gid, gid); -} - -#[test] -#[cfg(any(target_os = "linux", target_vendor = "apple"))] -fn test_socket_pair_pids(arg: Type) -> RetType { - // Create two connected sockets and get their peer credentials. - let (sock_a, sock_b) = UnixStream::pair().unwrap(); - let (cred_a, cred_b) = (sock_a.peer_cred().unwrap(), sock_b.peer_cred().unwrap()); - - // On supported platforms (see the cfg above), the credentials should always include the PID. - let pid = unsafe { getpid() }; - assert_eq!(cred_a.pid, Some(pid)); - assert_eq!(cred_b.pid, Some(pid)); -} diff --git a/library/std/src/os/unix/process.rs b/library/std/src/os/unix/process.rs deleted file mode 100644 index 72ea54bd77203..0000000000000 --- a/library/std/src/os/unix/process.rs +++ /dev/null @@ -1,528 +0,0 @@ -//! Unix-specific extensions to primitives in the [`std::process`] module. -//! -//! [`std::process`]: crate::process - -#![stable(feature = "rust1", since = "1.0.0")] - -use crate::ffi::OsStr; -use crate::io; -use crate::os::unix::io::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd}; -use crate::process; -use crate::sealed::Sealed; -use crate::sys; -use crate::sys_common::{AsInner, AsInnerMut, FromInner, IntoInner}; - -use cfg_if::cfg_if; - -cfg_if! { - if #[cfg(any(target_os = "vxworks", target_os = "espidf", target_os = "horizon", target_os = "vita"))] { - type UserId = u16; - type GroupId = u16; - } else if #[cfg(target_os = "nto")] { - // Both IDs are signed, see `sys/target_nto.h` of the QNX Neutrino SDP. - // Only positive values should be used, see e.g. - // https://www.qnx.com/developers/docs/7.1/#com.qnx.doc.neutrino.lib_ref/topic/s/setuid.html - type UserId = i32; - type GroupId = i32; - } else { - type UserId = u32; - type GroupId = u32; - } -} - -/// Unix-specific extensions to the [`process::Command`] builder. -/// -/// This trait is sealed: it cannot be implemented outside the standard library. -/// This is so that future additional methods are not breaking changes. -#[stable(feature = "rust1", since = "1.0.0")] -pub trait CommandExt: Sealed { - /// Sets the child process's user ID. This translates to a - /// `setuid` call in the child process. Failure in the `setuid` - /// call will cause the spawn to fail. - /// - /// # Notes - /// - /// This will also trigger a call to `setgroups(0, NULL)` in the child - /// process if no groups have been specified. - /// This removes supplementary groups that might have given the child - /// unwanted permissions. - #[stable(feature = "rust1", since = "1.0.0")] - fn uid(&mut self, id: UserId) -> &mut process::Command; - - /// Similar to `uid`, but sets the group ID of the child process. This has - /// the same semantics as the `uid` field. - #[stable(feature = "rust1", since = "1.0.0")] - fn gid(&mut self, id: GroupId) -> &mut process::Command; - - /// Sets the supplementary group IDs for the calling process. Translates to - /// a `setgroups` call in the child process. - #[unstable(feature = "setgroups", issue = "90747")] - fn groups(&mut self, groups: &[GroupId]) -> &mut process::Command; - - /// Schedules a closure to be run just before the `exec` function is - /// invoked. - /// - /// The closure is allowed to return an I/O error whose OS error code will - /// be communicated back to the parent and returned as an error from when - /// the spawn was requested. - /// - /// Multiple closures can be registered and they will be called in order of - /// their registration. If a closure returns `Err` then no further closures - /// will be called and the spawn operation will immediately return with a - /// failure. - /// - /// # Notes and Safety - /// - /// This closure will be run in the context of the child process after a - /// `fork`. This primarily means that any modifications made to memory on - /// behalf of this closure will **not** be visible to the parent process. - /// This is often a very constrained environment where normal operations - /// like `malloc`, accessing environment variables through [`std::env`] - /// or acquiring a mutex are not guaranteed to work (due to - /// other threads perhaps still running when the `fork` was run). - /// - /// For further details refer to the [POSIX fork() specification] - /// and the equivalent documentation for any targeted - /// platform, especially the requirements around *async-signal-safety*. - /// - /// This also means that all resources such as file descriptors and - /// memory-mapped regions got duplicated. It is your responsibility to make - /// sure that the closure does not violate library invariants by making - /// invalid use of these duplicates. - /// - /// Panicking in the closure is safe only if all the format arguments for the - /// panic message can be safely formatted; this is because although - /// `Command` calls [`std::panic::always_abort`](crate::panic::always_abort) - /// before calling the pre_exec hook, panic will still try to format the - /// panic message. - /// - /// When this closure is run, aspects such as the stdio file descriptors and - /// working directory have successfully been changed, so output to these - /// locations might not appear where intended. - /// - /// [POSIX fork() specification]: - /// https://pubs.opengroup.org/onlinepubs/9699919799/functions/fork.html - /// [`std::env`]: mod@crate::env - #[stable(feature = "process_pre_exec", since = "1.34.0")] - unsafe fn pre_exec(&mut self, f: F) -> &mut process::Command - where - F: FnMut() -> io::Result<()> + Send + Sync + 'static; - - /// Schedules a closure to be run just before the `exec` function is - /// invoked. - /// - /// This method is stable and usable, but it should be unsafe. To fix - /// that, it got deprecated in favor of the unsafe [`pre_exec`]. - /// - /// [`pre_exec`]: CommandExt::pre_exec - #[stable(feature = "process_exec", since = "1.15.0")] - #[deprecated(since = "1.37.0", note = "should be unsafe, use `pre_exec` instead")] - fn before_exec(&mut self, f: F) -> &mut process::Command - where - F: FnMut() -> io::Result<()> + Send + Sync + 'static, - { - unsafe { self.pre_exec(f) } - } - - /// Performs all the required setup by this `Command`, followed by calling - /// the `execvp` syscall. - /// - /// On success this function will not return, and otherwise it will return - /// an error indicating why the exec (or another part of the setup of the - /// `Command`) failed. - /// - /// `exec` not returning has the same implications as calling - /// [`process::exit`] – no destructors on the current stack or any other - /// thread’s stack will be run. Therefore, it is recommended to only call - /// `exec` at a point where it is fine to not run any destructors. Note, - /// that the `execvp` syscall independently guarantees that all memory is - /// freed and all file descriptors with the `CLOEXEC` option (set by default - /// on all file descriptors opened by the standard library) are closed. - /// - /// This function, unlike `spawn`, will **not** `fork` the process to create - /// a new child. Like spawn, however, the default behavior for the stdio - /// descriptors will be to inherited from the current process. - /// - /// # Notes - /// - /// The process may be in a "broken state" if this function returns in - /// error. For example the working directory, environment variables, signal - /// handling settings, various user/group information, or aspects of stdio - /// file descriptors may have changed. If a "transactional spawn" is - /// required to gracefully handle errors it is recommended to use the - /// cross-platform `spawn` instead. - #[stable(feature = "process_exec2", since = "1.9.0")] - fn exec(&mut self) -> io::Error; - - /// Set executable argument - /// - /// Set the first process argument, `argv[0]`, to something other than the - /// default executable path. - #[stable(feature = "process_set_argv0", since = "1.45.0")] - fn arg0(&mut self, arg: S) -> &mut process::Command - where - S: AsRef; - - /// Sets the process group ID (PGID) of the child process. Equivalent to a - /// `setpgid` call in the child process, but may be more efficient. - /// - /// Process groups determine which processes receive signals. - /// - /// # Examples - /// - /// Pressing Ctrl-C in a terminal will send SIGINT to all processes in - /// the current foreground process group. By spawning the `sleep` - /// subprocess in a new process group, it will not receive SIGINT from the - /// terminal. - /// - /// The parent process could install a signal handler and manage the - /// subprocess on its own terms. - /// - /// A process group ID of 0 will use the process ID as the PGID. - /// - /// ```no_run - /// use std::process::Command; - /// use std::os::unix::process::CommandExt; - /// - /// Command::new("sleep") - /// .arg("10") - /// .process_group(0) - /// .spawn()? - /// .wait()?; - /// # - /// # Ok::<_, Box>(()) - /// ``` - #[stable(feature = "process_set_process_group", since = "1.64.0")] - fn process_group(&mut self, pgroup: i32) -> &mut process::Command; -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl CommandExt for process::Command { - fn uid(&mut self, id: UserId) -> &mut process::Command { - self.as_inner_mut().uid(id); - self - } - - fn gid(&mut self, id: GroupId) -> &mut process::Command { - self.as_inner_mut().gid(id); - self - } - - fn groups(&mut self, groups: &[GroupId]) -> &mut process::Command { - self.as_inner_mut().groups(groups); - self - } - - unsafe fn pre_exec(&mut self, f: F) -> &mut process::Command - where - F: FnMut() -> io::Result<()> + Send + Sync + 'static, - { - self.as_inner_mut().pre_exec(Box::new(f)); - self - } - - fn exec(&mut self) -> io::Error { - // NOTE: This may *not* be safe to call after `libc::fork`, because it - // may allocate. That may be worth fixing at some point in the future. - self.as_inner_mut().exec(sys::process::Stdio::Inherit) - } - - fn arg0(&mut self, arg: S) -> &mut process::Command - where - S: AsRef, - { - self.as_inner_mut().set_arg_0(arg.as_ref()); - self - } - - fn process_group(&mut self, pgroup: i32) -> &mut process::Command { - self.as_inner_mut().pgroup(pgroup); - self - } -} - -/// Unix-specific extensions to [`process::ExitStatus`] and -/// [`ExitStatusError`](process::ExitStatusError). -/// -/// On Unix, `ExitStatus` **does not necessarily represent an exit status**, as -/// passed to the `_exit` system call or returned by -/// [`ExitStatus::code()`](crate::process::ExitStatus::code). It represents **any wait status** -/// as returned by one of the `wait` family of system -/// calls. -/// -/// A Unix wait status (a Rust `ExitStatus`) can represent a Unix exit status, but can also -/// represent other kinds of process event. -/// -/// This trait is sealed: it cannot be implemented outside the standard library. -/// This is so that future additional methods are not breaking changes. -#[stable(feature = "rust1", since = "1.0.0")] -pub trait ExitStatusExt: Sealed { - /// Creates a new `ExitStatus` or `ExitStatusError` from the raw underlying integer status - /// value from `wait` - /// - /// The value should be a **wait status, not an exit status**. - /// - /// # Panics - /// - /// Panics on an attempt to make an `ExitStatusError` from a wait status of `0`. - /// - /// Making an `ExitStatus` always succeeds and never panics. - #[stable(feature = "exit_status_from", since = "1.12.0")] - fn from_raw(raw: i32) -> Self; - - /// If the process was terminated by a signal, returns that signal. - /// - /// In other words, if `WIFSIGNALED`, this returns `WTERMSIG`. - #[stable(feature = "rust1", since = "1.0.0")] - fn signal(&self) -> Option; - - /// If the process was terminated by a signal, says whether it dumped core. - #[stable(feature = "unix_process_wait_more", since = "1.58.0")] - fn core_dumped(&self) -> bool; - - /// If the process was stopped by a signal, returns that signal. - /// - /// In other words, if `WIFSTOPPED`, this returns `WSTOPSIG`. This is only possible if the status came from - /// a `wait` system call which was passed `WUNTRACED`, and was then converted into an `ExitStatus`. - #[stable(feature = "unix_process_wait_more", since = "1.58.0")] - fn stopped_signal(&self) -> Option; - - /// Whether the process was continued from a stopped status. - /// - /// Ie, `WIFCONTINUED`. This is only possible if the status came from a `wait` system call - /// which was passed `WCONTINUED`, and was then converted into an `ExitStatus`. - #[stable(feature = "unix_process_wait_more", since = "1.58.0")] - fn continued(&self) -> bool; - - /// Returns the underlying raw `wait` status. - /// - /// The returned integer is a **wait status, not an exit status**. - #[stable(feature = "unix_process_wait_more", since = "1.58.0")] - fn into_raw(self) -> i32; -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExitStatusExt for process::ExitStatus { - fn from_raw(raw: i32) -> Self { - process::ExitStatus::from_inner(From::from(raw)) - } - - fn signal(&self) -> Option { - self.as_inner().signal() - } - - fn core_dumped(&self) -> bool { - self.as_inner().core_dumped() - } - - fn stopped_signal(&self) -> Option { - self.as_inner().stopped_signal() - } - - fn continued(&self) -> bool { - self.as_inner().continued() - } - - fn into_raw(self) -> i32 { - self.as_inner().into_raw().into() - } -} - -#[unstable(feature = "exit_status_error", issue = "84908")] -impl ExitStatusExt for process::ExitStatusError { - fn from_raw(raw: i32) -> Self { - process::ExitStatus::from_raw(raw) - .exit_ok() - .expect_err("::from_raw(0) but zero is not an error") - } - - fn signal(&self) -> Option { - self.into_status().signal() - } - - fn core_dumped(&self) -> bool { - self.into_status().core_dumped() - } - - fn stopped_signal(&self) -> Option { - self.into_status().stopped_signal() - } - - fn continued(&self) -> bool { - self.into_status().continued() - } - - fn into_raw(self) -> i32 { - self.into_status().into_raw() - } -} - -#[stable(feature = "process_extensions", since = "1.2.0")] -impl FromRawFd for process::Stdio { - #[inline] - unsafe fn from_raw_fd(fd: RawFd) -> process::Stdio { - let fd = sys::fd::FileDesc::from_raw_fd(fd); - let io = sys::process::Stdio::Fd(fd); - process::Stdio::from_inner(io) - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for process::Stdio { - /// Takes ownership of a file descriptor and returns a [`Stdio`](process::Stdio) - /// that can attach a stream to it. - #[inline] - fn from(fd: OwnedFd) -> process::Stdio { - let fd = sys::fd::FileDesc::from_inner(fd); - let io = sys::process::Stdio::Fd(fd); - process::Stdio::from_inner(io) - } -} - -#[stable(feature = "process_extensions", since = "1.2.0")] -impl AsRawFd for process::ChildStdin { - #[inline] - fn as_raw_fd(&self) -> RawFd { - self.as_inner().as_raw_fd() - } -} - -#[stable(feature = "process_extensions", since = "1.2.0")] -impl AsRawFd for process::ChildStdout { - #[inline] - fn as_raw_fd(&self) -> RawFd { - self.as_inner().as_raw_fd() - } -} - -#[stable(feature = "process_extensions", since = "1.2.0")] -impl AsRawFd for process::ChildStderr { - #[inline] - fn as_raw_fd(&self) -> RawFd { - self.as_inner().as_raw_fd() - } -} - -#[stable(feature = "into_raw_os", since = "1.4.0")] -impl IntoRawFd for process::ChildStdin { - #[inline] - fn into_raw_fd(self) -> RawFd { - self.into_inner().into_inner().into_raw_fd() - } -} - -#[stable(feature = "into_raw_os", since = "1.4.0")] -impl IntoRawFd for process::ChildStdout { - #[inline] - fn into_raw_fd(self) -> RawFd { - self.into_inner().into_inner().into_raw_fd() - } -} - -#[stable(feature = "into_raw_os", since = "1.4.0")] -impl IntoRawFd for process::ChildStderr { - #[inline] - fn into_raw_fd(self) -> RawFd { - self.into_inner().into_inner().into_raw_fd() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsFd for crate::process::ChildStdin { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - self.as_inner().as_fd() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for OwnedFd { - /// Takes ownership of a [`ChildStdin`](crate::process::ChildStdin)'s file descriptor. - #[inline] - fn from(child_stdin: crate::process::ChildStdin) -> OwnedFd { - child_stdin.into_inner().into_inner().into_inner() - } -} - -/// Create a `ChildStdin` from the provided `OwnedFd`. -/// -/// The provided file descriptor must point to a pipe -/// with the `CLOEXEC` flag set. -#[stable(feature = "child_stream_from_fd", since = "1.74.0")] -impl From for process::ChildStdin { - #[inline] - fn from(fd: OwnedFd) -> process::ChildStdin { - let fd = sys::fd::FileDesc::from_inner(fd); - let pipe = sys::pipe::AnonPipe::from_inner(fd); - process::ChildStdin::from_inner(pipe) - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsFd for crate::process::ChildStdout { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - self.as_inner().as_fd() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for OwnedFd { - /// Takes ownership of a [`ChildStdout`](crate::process::ChildStdout)'s file descriptor. - #[inline] - fn from(child_stdout: crate::process::ChildStdout) -> OwnedFd { - child_stdout.into_inner().into_inner().into_inner() - } -} - -/// Create a `ChildStdout` from the provided `OwnedFd`. -/// -/// The provided file descriptor must point to a pipe -/// with the `CLOEXEC` flag set. -#[stable(feature = "child_stream_from_fd", since = "1.74.0")] -impl From for process::ChildStdout { - #[inline] - fn from(fd: OwnedFd) -> process::ChildStdout { - let fd = sys::fd::FileDesc::from_inner(fd); - let pipe = sys::pipe::AnonPipe::from_inner(fd); - process::ChildStdout::from_inner(pipe) - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsFd for crate::process::ChildStderr { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - self.as_inner().as_fd() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for OwnedFd { - /// Takes ownership of a [`ChildStderr`](crate::process::ChildStderr)'s file descriptor. - #[inline] - fn from(child_stderr: crate::process::ChildStderr) -> OwnedFd { - child_stderr.into_inner().into_inner().into_inner() - } -} - -/// Create a `ChildStderr` from the provided `OwnedFd`. -/// -/// The provided file descriptor must point to a pipe -/// with the `CLOEXEC` flag set. -#[stable(feature = "child_stream_from_fd", since = "1.74.0")] -impl From for process::ChildStderr { - #[inline] - fn from(fd: OwnedFd) -> process::ChildStderr { - let fd = sys::fd::FileDesc::from_inner(fd); - let pipe = sys::pipe::AnonPipe::from_inner(fd); - process::ChildStderr::from_inner(pipe) - } -} - -/// Returns the OS-assigned process identifier associated with this process's parent. -#[must_use] -#[stable(feature = "unix_ppid", since = "1.27.0")] -pub fn parent_id() -> u32 { - crate::sys::os::getppid() -} diff --git a/library/std/src/os/unix/raw.rs b/library/std/src/os/unix/raw.rs deleted file mode 100644 index fe761627bc1f2..0000000000000 --- a/library/std/src/os/unix/raw.rs +++ /dev/null @@ -1,33 +0,0 @@ -//! Unix-specific primitives available on all unix platforms. - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![deprecated( - since = "1.8.0", - note = "these type aliases are no longer supported by \ - the standard library, the `libc` crate on \ - crates.io should be used instead for the correct \ - definitions" -)] -#![allow(deprecated)] - -#[stable(feature = "raw_ext", since = "1.1.0")] -#[allow(non_camel_case_types)] -pub type uid_t = u32; - -#[stable(feature = "raw_ext", since = "1.1.0")] -#[allow(non_camel_case_types)] -pub type gid_t = u32; - -#[stable(feature = "raw_ext", since = "1.1.0")] -#[allow(non_camel_case_types)] -pub type pid_t = i32; - -#[doc(inline)] -#[stable(feature = "pthread_t", since = "1.8.0")] -pub use super::platform::raw::pthread_t; -#[doc(inline)] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub use super::platform::raw::{blkcnt_t, time_t}; -#[doc(inline)] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub use super::platform::raw::{blksize_t, dev_t, ino_t, mode_t, nlink_t, off_t}; diff --git a/library/std/src/os/unix/thread.rs b/library/std/src/os/unix/thread.rs deleted file mode 100644 index 03dcc3a4f9ba0..0000000000000 --- a/library/std/src/os/unix/thread.rs +++ /dev/null @@ -1,41 +0,0 @@ -//! Unix-specific extensions to primitives in the [`std::thread`] module. -//! -//! [`std::thread`]: crate::thread - -#![stable(feature = "thread_extensions", since = "1.9.0")] - -#[allow(deprecated)] -use crate::os::unix::raw::pthread_t; -use crate::sys_common::{AsInner, IntoInner}; -use crate::thread::JoinHandle; - -#[stable(feature = "thread_extensions", since = "1.9.0")] -#[allow(deprecated)] -pub type RawPthread = pthread_t; - -/// Unix-specific extensions to [`JoinHandle`]. -#[stable(feature = "thread_extensions", since = "1.9.0")] -pub trait JoinHandleExt { - /// Extracts the raw pthread_t without taking ownership - #[stable(feature = "thread_extensions", since = "1.9.0")] - fn as_pthread_t(&self) -> RawPthread; - - /// Consumes the thread, returning the raw pthread_t - /// - /// This function **transfers ownership** of the underlying pthread_t to - /// the caller. Callers are then the unique owners of the pthread_t and - /// must either detach or join the pthread_t once it's no longer needed. - #[stable(feature = "thread_extensions", since = "1.9.0")] - fn into_pthread_t(self) -> RawPthread; -} - -#[stable(feature = "thread_extensions", since = "1.9.0")] -impl JoinHandleExt for JoinHandle { - fn as_pthread_t(&self) -> RawPthread { - self.as_inner().id() as RawPthread - } - - fn into_pthread_t(self) -> RawPthread { - self.into_inner().into_id() as RawPthread - } -} diff --git a/library/std/src/os/visionos/fs.rs b/library/std/src/os/visionos/fs.rs deleted file mode 100644 index e5df4de0b7f71..0000000000000 --- a/library/std/src/os/visionos/fs.rs +++ /dev/null @@ -1,160 +0,0 @@ -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::{self, Metadata}; -use crate::sealed::Sealed; -use crate::sys_common::{AsInner, AsInnerMut, IntoInner}; -use crate::time::SystemTime; - -#[allow(deprecated)] -use super::raw; - -/// OS-specific extensions to [`fs::Metadata`]. -/// -/// [`fs::Metadata`]: crate::fs::Metadata -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - /// Gain a reference to the underlying `stat` structure which contains - /// the raw information returned by the OS. - /// - /// The contents of the returned `stat` are **not** consistent across - /// Unix platforms. The `os::unix::fs::MetadataExt` trait contains the - /// cross-Unix abstractions contained within the raw stat. - #[stable(feature = "metadata_ext", since = "1.1.0")] - #[deprecated( - since = "1.8.0", - note = "deprecated in favor of the accessor \ - methods of this trait" - )] - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat; - - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_birthtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_birthtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_flags(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gen(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_lspare(&self) -> u32; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat { - unsafe { &*(self.as_inner().as_inner() as *const libc::stat as *const raw::stat) } - } - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_dev as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - self.as_inner().as_inner().st_atime as i64 - } - fn st_atime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_atime_nsec as i64 - } - fn st_mtime(&self) -> i64 { - self.as_inner().as_inner().st_mtime as i64 - } - fn st_mtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_mtime_nsec as i64 - } - fn st_ctime(&self) -> i64 { - self.as_inner().as_inner().st_ctime as i64 - } - fn st_ctime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_ctime_nsec as i64 - } - fn st_birthtime(&self) -> i64 { - self.as_inner().as_inner().st_birthtime as i64 - } - fn st_birthtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_birthtime_nsec as i64 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } - fn st_gen(&self) -> u32 { - self.as_inner().as_inner().st_gen as u32 - } - fn st_flags(&self) -> u32 { - self.as_inner().as_inner().st_flags as u32 - } - fn st_lspare(&self) -> u32 { - self.as_inner().as_inner().st_lspare as u32 - } -} - -/// OS-specific extensions to [`fs::FileTimes`]. -#[stable(feature = "file_set_times", since = "1.75.0")] -pub trait FileTimesExt: Sealed { - /// Set the creation time of a file. - #[stable(feature = "file_set_times", since = "1.75.0")] - fn set_created(self, t: SystemTime) -> Self; -} - -#[stable(feature = "file_set_times", since = "1.75.0")] -impl FileTimesExt for fs::FileTimes { - fn set_created(mut self, t: SystemTime) -> Self { - self.as_inner_mut().set_created(t.into_inner()); - self - } -} diff --git a/library/std/src/os/visionos/mod.rs b/library/std/src/os/visionos/mod.rs deleted file mode 100644 index f4b061ffda898..0000000000000 --- a/library/std/src/os/visionos/mod.rs +++ /dev/null @@ -1,6 +0,0 @@ -//! visionos-specific definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] - -pub mod fs; -pub mod raw; diff --git a/library/std/src/os/visionos/raw.rs b/library/std/src/os/visionos/raw.rs deleted file mode 100644 index 2b3eca6f493df..0000000000000 --- a/library/std/src/os/visionos/raw.rs +++ /dev/null @@ -1,83 +0,0 @@ -//! visionos-specific raw type definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![deprecated( - since = "1.8.0", - note = "these type aliases are no longer supported by \ - the standard library, the `libc` crate on \ - crates.io should be used instead for the correct \ - definitions" -)] -#![allow(deprecated)] - -use crate::os::raw::c_long; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blkcnt_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blksize_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type dev_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type ino_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type mode_t = u32; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type nlink_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type off_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type time_t = i64; - -#[stable(feature = "pthread_t", since = "1.8.0")] -pub type pthread_t = usize; - -#[repr(C)] -#[derive(Clone)] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: u16, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: u16, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_birthtime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_birthtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_flags: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gen: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_lspare: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_qspare: [i64; 2], -} diff --git a/library/std/src/os/vita/fs.rs b/library/std/src/os/vita/fs.rs deleted file mode 100644 index a5a06764a4dd8..0000000000000 --- a/library/std/src/os/vita/fs.rs +++ /dev/null @@ -1,95 +0,0 @@ -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::Metadata; -use crate::sys_common::AsInner; - -/// OS-specific extensions to [`fs::Metadata`]. -/// -/// [`fs::Metadata`]: crate::fs::Metadata -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_dev as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - self.as_inner().as_inner().st_atime as i64 - } - fn st_atime_nsec(&self) -> i64 { - 0 - } - fn st_mtime(&self) -> i64 { - self.as_inner().as_inner().st_mtime as i64 - } - fn st_mtime_nsec(&self) -> i64 { - 0 - } - fn st_ctime(&self) -> i64 { - self.as_inner().as_inner().st_ctime as i64 - } - fn st_ctime_nsec(&self) -> i64 { - 0 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } -} diff --git a/library/std/src/os/vita/mod.rs b/library/std/src/os/vita/mod.rs deleted file mode 100644 index da9edd12f7b03..0000000000000 --- a/library/std/src/os/vita/mod.rs +++ /dev/null @@ -1,6 +0,0 @@ -//! Definitions for vita - -#![stable(feature = "raw_ext", since = "1.1.0")] - -pub mod fs; -pub(crate) mod raw; diff --git a/library/std/src/os/vita/raw.rs b/library/std/src/os/vita/raw.rs deleted file mode 100644 index 74cae4d4135d1..0000000000000 --- a/library/std/src/os/vita/raw.rs +++ /dev/null @@ -1,70 +0,0 @@ -//! vita raw type definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![deprecated( - since = "1.8.0", - note = "these type aliases are no longer supported by \ - the standard library, the `libc` crate on \ - crates.io should be used instead for the correct \ - definitions" -)] -#![allow(deprecated)] - -use crate::os::raw::c_long; -use crate::os::unix::raw::{gid_t, uid_t}; - -#[stable(feature = "pthread_t", since = "1.8.0")] -pub type pthread_t = libc::pthread_t; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blkcnt_t = libc::blkcnt_t; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blksize_t = libc::blksize_t; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type dev_t = libc::dev_t; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type ino_t = libc::ino_t; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type mode_t = libc::mode_t; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type nlink_t = libc::nlink_t; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type off_t = libc::off_t; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type time_t = libc::time_t; - -#[repr(C)] -#[derive(Clone)] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: dev_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: ino_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: mode_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: nlink_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: uid_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: gid_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: dev_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: off_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: time_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: blksize_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: blkcnt_t, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_spare4: [c_long; 2usize], -} diff --git a/library/std/src/os/vxworks/fs.rs b/library/std/src/os/vxworks/fs.rs deleted file mode 100644 index 77e6238ca1f52..0000000000000 --- a/library/std/src/os/vxworks/fs.rs +++ /dev/null @@ -1,99 +0,0 @@ -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::Metadata; -use crate::sys_common::AsInner; - -/// -/// [`fs::Metadata`]: crate::fs::Metadata -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_attrib(&self) -> u8; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_dev as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - self.as_inner().as_inner().st_atime as i64 - } - fn st_atime_nsec(&self) -> i64 { - 0 - } - fn st_mtime(&self) -> i64 { - self.as_inner().as_inner().st_mtime as i64 - } - fn st_mtime_nsec(&self) -> i64 { - 0 - } - fn st_ctime(&self) -> i64 { - self.as_inner().as_inner().st_ctime as i64 - } - fn st_ctime_nsec(&self) -> i64 { - 0 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } - fn st_attrib(&self) -> u8 { - self.as_inner().as_inner().st_attrib as u8 - } -} diff --git a/library/std/src/os/vxworks/mod.rs b/library/std/src/os/vxworks/mod.rs deleted file mode 100644 index 0a7ac641dd3e1..0000000000000 --- a/library/std/src/os/vxworks/mod.rs +++ /dev/null @@ -1,6 +0,0 @@ -//! VxWorks-specific definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] - -pub mod fs; -pub mod raw; diff --git a/library/std/src/os/vxworks/raw.rs b/library/std/src/os/vxworks/raw.rs deleted file mode 100644 index cb41ddfe2a9bf..0000000000000 --- a/library/std/src/os/vxworks/raw.rs +++ /dev/null @@ -1,10 +0,0 @@ -//! VxWorks-specific raw type definitions -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::os::raw::c_ulong; - -#[stable(feature = "pthread_t", since = "1.8.0")] -pub type pthread_t = c_ulong; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub use libc::{blkcnt_t, blksize_t, dev_t, ino_t, mode_t, nlink_t, off_t, time_t}; diff --git a/library/std/src/os/wasi/ffi.rs b/library/std/src/os/wasi/ffi.rs deleted file mode 100644 index 41dd8702e98e9..0000000000000 --- a/library/std/src/os/wasi/ffi.rs +++ /dev/null @@ -1,11 +0,0 @@ -//! WASI-specific extensions to primitives in the [`std::ffi`] module -//! -//! [`std::ffi`]: crate::ffi - -#![stable(feature = "rust1", since = "1.0.0")] - -#[path = "../unix/ffi/os_str.rs"] -mod os_str; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::os_str::{OsStrExt, OsStringExt}; diff --git a/library/std/src/os/wasi/fs.rs b/library/std/src/os/wasi/fs.rs deleted file mode 100644 index 46fc2a50de911..0000000000000 --- a/library/std/src/os/wasi/fs.rs +++ /dev/null @@ -1,565 +0,0 @@ -//! WASI-specific extensions to primitives in the [`std::fs`] module. -//! -//! [`std::fs`]: crate::fs - -#![deny(unsafe_op_in_unsafe_fn)] -#![unstable(feature = "wasi_ext", issue = "71213")] - -use crate::ffi::OsStr; -use crate::fs::{self, File, Metadata, OpenOptions}; -use crate::io::{self, IoSlice, IoSliceMut}; -use crate::path::{Path, PathBuf}; -use crate::sys_common::{AsInner, AsInnerMut, FromInner}; -// Used for `File::read` on intra-doc links -#[allow(unused_imports)] -use io::{Read, Write}; - -/// WASI-specific extensions to [`File`]. -pub trait FileExt { - /// Reads a number of bytes starting from a given offset. - /// - /// Returns the number of bytes read. - /// - /// The offset is relative to the start of the file and thus independent - /// from the current cursor. - /// - /// The current file cursor is not affected by this function. - /// - /// Note that similar to [`File::read`], it is not an error to return with a - /// short read. - fn read_at(&self, buf: &mut [u8], offset: u64) -> io::Result { - let bufs = &mut [IoSliceMut::new(buf)]; - self.read_vectored_at(bufs, offset) - } - - /// Reads a number of bytes starting from a given offset. - /// - /// Returns the number of bytes read. - /// - /// The offset is relative to the start of the file and thus independent - /// from the current cursor. - /// - /// The current file cursor is not affected by this function. - /// - /// Note that similar to [`File::read_vectored`], it is not an error to - /// return with a short read. - fn read_vectored_at(&self, bufs: &mut [IoSliceMut<'_>], offset: u64) -> io::Result; - - /// Reads the exact number of byte required to fill `buf` from the given offset. - /// - /// The offset is relative to the start of the file and thus independent - /// from the current cursor. - /// - /// The current file cursor is not affected by this function. - /// - /// Similar to [`Read::read_exact`] but uses [`read_at`] instead of `read`. - /// - /// [`read_at`]: FileExt::read_at - /// - /// # Errors - /// - /// If this function encounters an error of the kind - /// [`io::ErrorKind::Interrupted`] then the error is ignored and the operation - /// will continue. - /// - /// If this function encounters an "end of file" before completely filling - /// the buffer, it returns an error of the kind [`io::ErrorKind::UnexpectedEof`]. - /// The contents of `buf` are unspecified in this case. - /// - /// If any other read error is encountered then this function immediately - /// returns. The contents of `buf` are unspecified in this case. - /// - /// If this function returns an error, it is unspecified how many bytes it - /// has read, but it will never read more than would be necessary to - /// completely fill the buffer. - #[stable(feature = "rw_exact_all_at", since = "1.33.0")] - fn read_exact_at(&self, mut buf: &mut [u8], mut offset: u64) -> io::Result<()> { - while !buf.is_empty() { - match self.read_at(buf, offset) { - Ok(0) => break, - Ok(n) => { - let tmp = buf; - buf = &mut tmp[n..]; - offset += n as u64; - } - Err(ref e) if e.is_interrupted() => {} - Err(e) => return Err(e), - } - } - if !buf.is_empty() { Err(io::Error::READ_EXACT_EOF) } else { Ok(()) } - } - - /// Writes a number of bytes starting from a given offset. - /// - /// Returns the number of bytes written. - /// - /// The offset is relative to the start of the file and thus independent - /// from the current cursor. - /// - /// The current file cursor is not affected by this function. - /// - /// When writing beyond the end of the file, the file is appropriately - /// extended and the intermediate bytes are initialized with the value 0. - /// - /// Note that similar to [`File::write`], it is not an error to return a - /// short write. - fn write_at(&self, buf: &[u8], offset: u64) -> io::Result { - let bufs = &[IoSlice::new(buf)]; - self.write_vectored_at(bufs, offset) - } - - /// Writes a number of bytes starting from a given offset. - /// - /// Returns the number of bytes written. - /// - /// The offset is relative to the start of the file and thus independent - /// from the current cursor. - /// - /// The current file cursor is not affected by this function. - /// - /// When writing beyond the end of the file, the file is appropriately - /// extended and the intermediate bytes are initialized with the value 0. - /// - /// Note that similar to [`File::write_vectored`], it is not an error to return a - /// short write. - fn write_vectored_at(&self, bufs: &[IoSlice<'_>], offset: u64) -> io::Result; - - /// Attempts to write an entire buffer starting from a given offset. - /// - /// The offset is relative to the start of the file and thus independent - /// from the current cursor. - /// - /// The current file cursor is not affected by this function. - /// - /// This method will continuously call [`write_at`] until there is no more data - /// to be written or an error of non-[`io::ErrorKind::Interrupted`] kind is - /// returned. This method will not return until the entire buffer has been - /// successfully written or such an error occurs. The first error that is - /// not of [`io::ErrorKind::Interrupted`] kind generated from this method will be - /// returned. - /// - /// # Errors - /// - /// This function will return the first error of - /// non-[`io::ErrorKind::Interrupted`] kind that [`write_at`] returns. - /// - /// [`write_at`]: FileExt::write_at - #[stable(feature = "rw_exact_all_at", since = "1.33.0")] - fn write_all_at(&self, mut buf: &[u8], mut offset: u64) -> io::Result<()> { - while !buf.is_empty() { - match self.write_at(buf, offset) { - Ok(0) => { - return Err(io::Error::WRITE_ALL_EOF); - } - Ok(n) => { - buf = &buf[n..]; - offset += n as u64 - } - Err(ref e) if e.is_interrupted() => {} - Err(e) => return Err(e), - } - } - Ok(()) - } - - /// Returns the current position within the file. - /// - /// This corresponds to the `fd_tell` syscall and is similar to - /// `seek` where you offset 0 bytes from the current position. - #[doc(alias = "fd_tell")] - fn tell(&self) -> io::Result; - - /// Adjust the flags associated with this file. - /// - /// This corresponds to the `fd_fdstat_set_flags` syscall. - #[doc(alias = "fd_fdstat_set_flags")] - fn fdstat_set_flags(&self, flags: u16) -> io::Result<()>; - - /// Adjust the rights associated with this file. - /// - /// This corresponds to the `fd_fdstat_set_rights` syscall. - #[doc(alias = "fd_fdstat_set_rights")] - fn fdstat_set_rights(&self, rights: u64, inheriting: u64) -> io::Result<()>; - - /// Provide file advisory information on a file descriptor. - /// - /// This corresponds to the `fd_advise` syscall. - #[doc(alias = "fd_advise")] - fn advise(&self, offset: u64, len: u64, advice: u8) -> io::Result<()>; - - /// Force the allocation of space in a file. - /// - /// This corresponds to the `fd_allocate` syscall. - #[doc(alias = "fd_allocate")] - fn allocate(&self, offset: u64, len: u64) -> io::Result<()>; - - /// Create a directory. - /// - /// This corresponds to the `path_create_directory` syscall. - #[doc(alias = "path_create_directory")] - fn create_directory>(&self, dir: P) -> io::Result<()>; - - /// Read the contents of a symbolic link. - /// - /// This corresponds to the `path_readlink` syscall. - #[doc(alias = "path_readlink")] - fn read_link>(&self, path: P) -> io::Result; - - /// Return the attributes of a file or directory. - /// - /// This corresponds to the `path_filestat_get` syscall. - #[doc(alias = "path_filestat_get")] - fn metadata_at>(&self, lookup_flags: u32, path: P) -> io::Result; - - /// Unlink a file. - /// - /// This corresponds to the `path_unlink_file` syscall. - #[doc(alias = "path_unlink_file")] - fn remove_file>(&self, path: P) -> io::Result<()>; - - /// Remove a directory. - /// - /// This corresponds to the `path_remove_directory` syscall. - #[doc(alias = "path_remove_directory")] - fn remove_directory>(&self, path: P) -> io::Result<()>; -} - -// FIXME: bind fd_fdstat_get - need to define a custom return type -// FIXME: bind fd_readdir - can't return `ReadDir` since we only have entry name -// FIXME: bind fd_filestat_set_times maybe? - on crates.io for unix -// FIXME: bind path_filestat_set_times maybe? - on crates.io for unix -// FIXME: bind poll_oneoff maybe? - probably should wait for I/O to settle -// FIXME: bind random_get maybe? - on crates.io for unix - -impl FileExt for fs::File { - fn read_vectored_at(&self, bufs: &mut [IoSliceMut<'_>], offset: u64) -> io::Result { - self.as_inner().as_inner().pread(bufs, offset) - } - - fn write_vectored_at(&self, bufs: &[IoSlice<'_>], offset: u64) -> io::Result { - self.as_inner().as_inner().pwrite(bufs, offset) - } - - fn tell(&self) -> io::Result { - self.as_inner().as_inner().tell() - } - - fn fdstat_set_flags(&self, flags: u16) -> io::Result<()> { - self.as_inner().as_inner().set_flags(flags) - } - - fn fdstat_set_rights(&self, rights: u64, inheriting: u64) -> io::Result<()> { - self.as_inner().as_inner().set_rights(rights, inheriting) - } - - fn advise(&self, offset: u64, len: u64, advice: u8) -> io::Result<()> { - let advice = match advice { - a if a == wasi::ADVICE_NORMAL.raw() => wasi::ADVICE_NORMAL, - a if a == wasi::ADVICE_SEQUENTIAL.raw() => wasi::ADVICE_SEQUENTIAL, - a if a == wasi::ADVICE_RANDOM.raw() => wasi::ADVICE_RANDOM, - a if a == wasi::ADVICE_WILLNEED.raw() => wasi::ADVICE_WILLNEED, - a if a == wasi::ADVICE_DONTNEED.raw() => wasi::ADVICE_DONTNEED, - a if a == wasi::ADVICE_NOREUSE.raw() => wasi::ADVICE_NOREUSE, - _ => { - return Err(io::const_io_error!( - io::ErrorKind::InvalidInput, - "invalid parameter 'advice'", - )); - } - }; - - self.as_inner().as_inner().advise(offset, len, advice) - } - - fn allocate(&self, offset: u64, len: u64) -> io::Result<()> { - self.as_inner().as_inner().allocate(offset, len) - } - - fn create_directory>(&self, dir: P) -> io::Result<()> { - self.as_inner().as_inner().create_directory(osstr2str(dir.as_ref().as_ref())?) - } - - fn read_link>(&self, path: P) -> io::Result { - self.as_inner().read_link(path.as_ref()) - } - - fn metadata_at>(&self, lookup_flags: u32, path: P) -> io::Result { - let m = self.as_inner().metadata_at(lookup_flags, path.as_ref())?; - Ok(FromInner::from_inner(m)) - } - - fn remove_file>(&self, path: P) -> io::Result<()> { - self.as_inner().as_inner().unlink_file(osstr2str(path.as_ref().as_ref())?) - } - - fn remove_directory>(&self, path: P) -> io::Result<()> { - self.as_inner().as_inner().remove_directory(osstr2str(path.as_ref().as_ref())?) - } -} - -/// WASI-specific extensions to [`fs::OpenOptions`]. -pub trait OpenOptionsExt { - /// Pass custom `dirflags` argument to `path_open`. - /// - /// This option configures the `dirflags` argument to the - /// `path_open` syscall which `OpenOptions` will eventually call. The - /// `dirflags` argument configures how the file is looked up, currently - /// primarily affecting whether symlinks are followed or not. - /// - /// By default this value is `__WASI_LOOKUP_SYMLINK_FOLLOW`, or symlinks are - /// followed. You can call this method with 0 to disable following symlinks - fn lookup_flags(&mut self, flags: u32) -> &mut Self; - - /// Indicates whether `OpenOptions` must open a directory or not. - /// - /// This method will configure whether the `__WASI_O_DIRECTORY` flag is - /// passed when opening a file. When passed it will require that the opened - /// path is a directory. - /// - /// This option is by default `false` - fn directory(&mut self, dir: bool) -> &mut Self; - - /// Indicates whether `__WASI_FDFLAG_DSYNC` is passed in the `fs_flags` - /// field of `path_open`. - /// - /// This option is by default `false` - fn dsync(&mut self, dsync: bool) -> &mut Self; - - /// Indicates whether `__WASI_FDFLAG_NONBLOCK` is passed in the `fs_flags` - /// field of `path_open`. - /// - /// This option is by default `false` - fn nonblock(&mut self, nonblock: bool) -> &mut Self; - - /// Indicates whether `__WASI_FDFLAG_RSYNC` is passed in the `fs_flags` - /// field of `path_open`. - /// - /// This option is by default `false` - fn rsync(&mut self, rsync: bool) -> &mut Self; - - /// Indicates whether `__WASI_FDFLAG_SYNC` is passed in the `fs_flags` - /// field of `path_open`. - /// - /// This option is by default `false` - fn sync(&mut self, sync: bool) -> &mut Self; - - /// Indicates the value that should be passed in for the `fs_rights_base` - /// parameter of `path_open`. - /// - /// This option defaults based on the `read` and `write` configuration of - /// this `OpenOptions` builder. If this method is called, however, the - /// exact mask passed in will be used instead. - fn fs_rights_base(&mut self, rights: u64) -> &mut Self; - - /// Indicates the value that should be passed in for the - /// `fs_rights_inheriting` parameter of `path_open`. - /// - /// The default for this option is the same value as what will be passed - /// for the `fs_rights_base` parameter but if this method is called then - /// the specified value will be used instead. - fn fs_rights_inheriting(&mut self, rights: u64) -> &mut Self; - - /// Open a file or directory. - /// - /// This corresponds to the `path_open` syscall. - #[doc(alias = "path_open")] - fn open_at>(&self, file: &File, path: P) -> io::Result; -} - -impl OpenOptionsExt for OpenOptions { - fn lookup_flags(&mut self, flags: u32) -> &mut OpenOptions { - self.as_inner_mut().lookup_flags(flags); - self - } - - fn directory(&mut self, dir: bool) -> &mut OpenOptions { - self.as_inner_mut().directory(dir); - self - } - - fn dsync(&mut self, enabled: bool) -> &mut OpenOptions { - self.as_inner_mut().dsync(enabled); - self - } - - fn nonblock(&mut self, enabled: bool) -> &mut OpenOptions { - self.as_inner_mut().nonblock(enabled); - self - } - - fn rsync(&mut self, enabled: bool) -> &mut OpenOptions { - self.as_inner_mut().rsync(enabled); - self - } - - fn sync(&mut self, enabled: bool) -> &mut OpenOptions { - self.as_inner_mut().sync(enabled); - self - } - - fn fs_rights_base(&mut self, rights: u64) -> &mut OpenOptions { - self.as_inner_mut().fs_rights_base(rights); - self - } - - fn fs_rights_inheriting(&mut self, rights: u64) -> &mut OpenOptions { - self.as_inner_mut().fs_rights_inheriting(rights); - self - } - - fn open_at>(&self, file: &File, path: P) -> io::Result { - let inner = file.as_inner().open_at(path.as_ref(), self.as_inner())?; - Ok(File::from_inner(inner)) - } -} - -/// WASI-specific extensions to [`fs::Metadata`]. -pub trait MetadataExt { - /// Returns the `st_dev` field of the internal `filestat_t` - fn dev(&self) -> u64; - /// Returns the `st_ino` field of the internal `filestat_t` - fn ino(&self) -> u64; - /// Returns the `st_nlink` field of the internal `filestat_t` - fn nlink(&self) -> u64; - /// Returns the `st_size` field of the internal `filestat_t` - fn size(&self) -> u64; - /// Returns the `st_atim` field of the internal `filestat_t` - fn atim(&self) -> u64; - /// Returns the `st_mtim` field of the internal `filestat_t` - fn mtim(&self) -> u64; - /// Returns the `st_ctim` field of the internal `filestat_t` - fn ctim(&self) -> u64; -} - -impl MetadataExt for fs::Metadata { - fn dev(&self) -> u64 { - self.as_inner().as_wasi().dev - } - fn ino(&self) -> u64 { - self.as_inner().as_wasi().ino - } - fn nlink(&self) -> u64 { - self.as_inner().as_wasi().nlink - } - fn size(&self) -> u64 { - self.as_inner().as_wasi().size - } - fn atim(&self) -> u64 { - self.as_inner().as_wasi().atim - } - fn mtim(&self) -> u64 { - self.as_inner().as_wasi().mtim - } - fn ctim(&self) -> u64 { - self.as_inner().as_wasi().ctim - } -} - -/// WASI-specific extensions for [`fs::FileType`]. -/// -/// Adds support for special WASI file types such as block/character devices, -/// pipes, and sockets. -pub trait FileTypeExt { - /// Returns `true` if this file type is a block device. - fn is_block_device(&self) -> bool; - /// Returns `true` if this file type is a character device. - fn is_char_device(&self) -> bool; - /// Returns `true` if this file type is a socket datagram. - fn is_socket_dgram(&self) -> bool; - /// Returns `true` if this file type is a socket stream. - fn is_socket_stream(&self) -> bool; - /// Returns `true` if this file type is any type of socket. - fn is_socket(&self) -> bool { - self.is_socket_stream() || self.is_socket_dgram() - } -} - -impl FileTypeExt for fs::FileType { - fn is_block_device(&self) -> bool { - self.as_inner().bits() == wasi::FILETYPE_BLOCK_DEVICE - } - fn is_char_device(&self) -> bool { - self.as_inner().bits() == wasi::FILETYPE_CHARACTER_DEVICE - } - fn is_socket_dgram(&self) -> bool { - self.as_inner().bits() == wasi::FILETYPE_SOCKET_DGRAM - } - fn is_socket_stream(&self) -> bool { - self.as_inner().bits() == wasi::FILETYPE_SOCKET_STREAM - } -} - -/// WASI-specific extension methods for [`fs::DirEntry`]. -pub trait DirEntryExt { - /// Returns the underlying `d_ino` field of the `dirent_t` - fn ino(&self) -> u64; -} - -impl DirEntryExt for fs::DirEntry { - fn ino(&self) -> u64 { - self.as_inner().ino() - } -} - -/// Create a hard link. -/// -/// This corresponds to the `path_link` syscall. -#[doc(alias = "path_link")] -pub fn link, U: AsRef>( - old_fd: &File, - old_flags: u32, - old_path: P, - new_fd: &File, - new_path: U, -) -> io::Result<()> { - old_fd.as_inner().as_inner().link( - old_flags, - osstr2str(old_path.as_ref().as_ref())?, - new_fd.as_inner().as_inner(), - osstr2str(new_path.as_ref().as_ref())?, - ) -} - -/// Rename a file or directory. -/// -/// This corresponds to the `path_rename` syscall. -#[doc(alias = "path_rename")] -pub fn rename, U: AsRef>( - old_fd: &File, - old_path: P, - new_fd: &File, - new_path: U, -) -> io::Result<()> { - old_fd.as_inner().as_inner().rename( - osstr2str(old_path.as_ref().as_ref())?, - new_fd.as_inner().as_inner(), - osstr2str(new_path.as_ref().as_ref())?, - ) -} - -/// Create a symbolic link. -/// -/// This corresponds to the `path_symlink` syscall. -#[doc(alias = "path_symlink")] -pub fn symlink, U: AsRef>( - old_path: P, - fd: &File, - new_path: U, -) -> io::Result<()> { - fd.as_inner() - .as_inner() - .symlink(osstr2str(old_path.as_ref().as_ref())?, osstr2str(new_path.as_ref().as_ref())?) -} - -/// Create a symbolic link. -/// -/// This is a convenience API similar to `std::os::unix::fs::symlink` and -/// `std::os::windows::fs::symlink_file` and `std::os::windows::fs::symlink_dir`. -pub fn symlink_path, U: AsRef>(old_path: P, new_path: U) -> io::Result<()> { - crate::sys::fs::symlink(old_path.as_ref(), new_path.as_ref()) -} - -fn osstr2str(f: &OsStr) -> io::Result<&str> { - f.to_str() - .ok_or_else(|| io::const_io_error!(io::ErrorKind::Uncategorized, "input must be utf-8")) -} diff --git a/library/std/src/os/wasi/io/fd.rs b/library/std/src/os/wasi/io/fd.rs deleted file mode 100644 index 930aca887e3c4..0000000000000 --- a/library/std/src/os/wasi/io/fd.rs +++ /dev/null @@ -1,9 +0,0 @@ -//! Owned and borrowed file descriptors. - -#![unstable(feature = "wasi_ext", issue = "71213")] - -// Tests for this module -#[cfg(test)] -mod tests; - -pub use crate::os::fd::owned::*; diff --git a/library/std/src/os/wasi/io/fd/tests.rs b/library/std/src/os/wasi/io/fd/tests.rs deleted file mode 100644 index 418274752b0ad..0000000000000 --- a/library/std/src/os/wasi/io/fd/tests.rs +++ /dev/null @@ -1,11 +0,0 @@ -use crate::mem::size_of; -use crate::os::wasi::io::RawFd; - -#[test] -fn test_raw_fd_layout() { - // `OwnedFd` and `BorrowedFd` use `rustc_layout_scalar_valid_range_start` - // and `rustc_layout_scalar_valid_range_end`, with values that depend on - // the bit width of `RawFd`. If this ever changes, those values will need - // to be updated. - assert_eq!(size_of::(), 4); -} diff --git a/library/std/src/os/wasi/io/mod.rs b/library/std/src/os/wasi/io/mod.rs deleted file mode 100644 index 4e123a1eec8ae..0000000000000 --- a/library/std/src/os/wasi/io/mod.rs +++ /dev/null @@ -1,6 +0,0 @@ -//! WASI-specific extensions to general I/O primitives. - -#![stable(feature = "io_safety_wasi", since = "1.65.0")] - -#[stable(feature = "io_safety_wasi", since = "1.65.0")] -pub use crate::os::fd::*; diff --git a/library/std/src/os/wasi/io/raw.rs b/library/std/src/os/wasi/io/raw.rs deleted file mode 100644 index da3b36adad409..0000000000000 --- a/library/std/src/os/wasi/io/raw.rs +++ /dev/null @@ -1,20 +0,0 @@ -//! WASI-specific extensions to general I/O primitives. - -#![unstable(feature = "wasi_ext", issue = "71213")] - -// NOTE: despite the fact that this module is unstable, -// stable Rust had the capability to access the stable -// re-exported items from os::fd::raw through this -// unstable module. -// In PR #95956 the stability checker was changed to check -// all path segments of an item rather than just the last, -// which caused the aforementioned stable usage to regress -// (see issue #99502). -// As a result, the items in os::fd::raw were given the -// rustc_allowed_through_unstable_modules attribute. -// No regression tests were added to ensure this property, -// as CI is not configured to test wasm32-wasi. -// If this module is stabilized, -// you may want to remove those attributes -// (assuming no other unstable modules need them). -pub use crate::os::fd::raw::*; diff --git a/library/std/src/os/wasi/mod.rs b/library/std/src/os/wasi/mod.rs deleted file mode 100644 index e36b93e60ea1c..0000000000000 --- a/library/std/src/os/wasi/mod.rs +++ /dev/null @@ -1,58 +0,0 @@ -//! Platform-specific extensions to `std` for the WebAssembly System Interface (WASI). -//! -//! Provides access to platform-level information on WASI, and exposes -//! WASI-specific functions that would otherwise be inappropriate as -//! part of the core `std` library. -//! -//! It exposes more ways to deal with platform-specific strings (`OsStr`, -//! `OsString`), allows to set permissions more granularly, extract low-level -//! file descriptors from files and sockets, and has platform-specific helpers -//! for spawning processes. -//! -//! # Examples -//! -//! ```no_run -//! use std::fs::File; -//! use std::os::wasi::prelude::*; -//! -//! fn main() -> std::io::Result<()> { -//! let f = File::create("foo.txt")?; -//! let fd = f.as_raw_fd(); -//! -//! // use fd with native WASI bindings -//! -//! Ok(()) -//! } -//! ``` -//! -//! [`OsStr`]: crate::ffi::OsStr -//! [`OsString`]: crate::ffi::OsString - -#![cfg_attr(not(target_env = "p2"), stable(feature = "rust1", since = "1.0.0"))] -#![cfg_attr(target_env = "p2", unstable(feature = "wasip2", issue = "none"))] -#![deny(unsafe_op_in_unsafe_fn)] -#![doc(cfg(target_os = "wasi"))] - -pub mod ffi; -pub mod fs; -pub mod io; -pub mod net; - -/// A prelude for conveniently writing platform-specific code. -/// -/// Includes all extension traits, and some important type definitions. -#[stable(feature = "rust1", since = "1.0.0")] -pub mod prelude { - #[doc(no_inline)] - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::ffi::{OsStrExt, OsStringExt}; - #[doc(no_inline)] - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::fs::FileTypeExt; - #[doc(no_inline)] - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::fs::{DirEntryExt, FileExt, MetadataExt, OpenOptionsExt}; - #[doc(no_inline)] - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::io::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd, RawFd}; -} diff --git a/library/std/src/os/wasi/net/mod.rs b/library/std/src/os/wasi/net/mod.rs deleted file mode 100644 index 73c097d4a50ab..0000000000000 --- a/library/std/src/os/wasi/net/mod.rs +++ /dev/null @@ -1,23 +0,0 @@ -//! WASI-specific networking functionality - -#![unstable(feature = "wasi_ext", issue = "71213")] - -use crate::io; -use crate::net; -use crate::sys_common::AsInner; - -/// WASI-specific extensions to [`std::net::TcpListener`]. -/// -/// [`std::net::TcpListener`]: crate::net::TcpListener -pub trait TcpListenerExt { - /// Accept a socket. - /// - /// This corresponds to the `sock_accept` syscall. - fn sock_accept(&self, flags: u16) -> io::Result; -} - -impl TcpListenerExt for net::TcpListener { - fn sock_accept(&self, flags: u16) -> io::Result { - self.as_inner().as_inner().as_inner().sock_accept(flags) - } -} diff --git a/library/std/src/os/wasip2/mod.rs b/library/std/src/os/wasip2/mod.rs deleted file mode 100644 index 1d44dd72814b8..0000000000000 --- a/library/std/src/os/wasip2/mod.rs +++ /dev/null @@ -1,5 +0,0 @@ -//! Platform-specific extensions to `std` for Preview 2 of the WebAssembly System Interface (WASI). -//! -//! This module is currently empty, but will be filled over time as wasi-libc support for WASI Preview 2 is stabilized. - -#![stable(feature = "raw_ext", since = "1.1.0")] diff --git a/library/std/src/os/watchos/fs.rs b/library/std/src/os/watchos/fs.rs deleted file mode 100644 index ee215dd598441..0000000000000 --- a/library/std/src/os/watchos/fs.rs +++ /dev/null @@ -1,160 +0,0 @@ -#![stable(feature = "metadata_ext", since = "1.1.0")] - -use crate::fs::{self, Metadata}; -use crate::sealed::Sealed; -use crate::sys_common::{AsInner, AsInnerMut, IntoInner}; -use crate::time::SystemTime; - -#[allow(deprecated)] -use crate::os::watchos::raw; - -/// OS-specific extensions to [`fs::Metadata`]. -/// -/// [`fs::Metadata`]: crate::fs::Metadata -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - /// Gain a reference to the underlying `stat` structure which contains - /// the raw information returned by the OS. - /// - /// The contents of the returned `stat` are **not** consistent across - /// Unix platforms. The `os::unix::fs::MetadataExt` trait contains the - /// cross-Unix abstractions contained within the raw stat. - #[stable(feature = "metadata_ext", since = "1.1.0")] - #[deprecated( - since = "1.8.0", - note = "deprecated in favor of the accessor \ - methods of this trait" - )] - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat; - - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_dev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ino(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mode(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_nlink(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_uid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gid(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_rdev(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_size(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_atime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_mtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_ctime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_birthtime(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_birthtime_nsec(&self) -> i64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blksize(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_blocks(&self) -> u64; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_flags(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_gen(&self) -> u32; - #[stable(feature = "metadata_ext2", since = "1.8.0")] - fn st_lspare(&self) -> u32; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - #[allow(deprecated)] - fn as_raw_stat(&self) -> &raw::stat { - unsafe { &*(self.as_inner().as_inner() as *const libc::stat as *const raw::stat) } - } - fn st_dev(&self) -> u64 { - self.as_inner().as_inner().st_dev as u64 - } - fn st_ino(&self) -> u64 { - self.as_inner().as_inner().st_ino as u64 - } - fn st_mode(&self) -> u32 { - self.as_inner().as_inner().st_mode as u32 - } - fn st_nlink(&self) -> u64 { - self.as_inner().as_inner().st_nlink as u64 - } - fn st_uid(&self) -> u32 { - self.as_inner().as_inner().st_uid as u32 - } - fn st_gid(&self) -> u32 { - self.as_inner().as_inner().st_gid as u32 - } - fn st_rdev(&self) -> u64 { - self.as_inner().as_inner().st_rdev as u64 - } - fn st_size(&self) -> u64 { - self.as_inner().as_inner().st_size as u64 - } - fn st_atime(&self) -> i64 { - self.as_inner().as_inner().st_atime as i64 - } - fn st_atime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_atime_nsec as i64 - } - fn st_mtime(&self) -> i64 { - self.as_inner().as_inner().st_mtime as i64 - } - fn st_mtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_mtime_nsec as i64 - } - fn st_ctime(&self) -> i64 { - self.as_inner().as_inner().st_ctime as i64 - } - fn st_ctime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_ctime_nsec as i64 - } - fn st_birthtime(&self) -> i64 { - self.as_inner().as_inner().st_birthtime as i64 - } - fn st_birthtime_nsec(&self) -> i64 { - self.as_inner().as_inner().st_birthtime_nsec as i64 - } - fn st_blksize(&self) -> u64 { - self.as_inner().as_inner().st_blksize as u64 - } - fn st_blocks(&self) -> u64 { - self.as_inner().as_inner().st_blocks as u64 - } - fn st_gen(&self) -> u32 { - self.as_inner().as_inner().st_gen as u32 - } - fn st_flags(&self) -> u32 { - self.as_inner().as_inner().st_flags as u32 - } - fn st_lspare(&self) -> u32 { - self.as_inner().as_inner().st_lspare as u32 - } -} - -/// OS-specific extensions to [`fs::FileTimes`]. -#[stable(feature = "file_set_times", since = "1.75.0")] -pub trait FileTimesExt: Sealed { - /// Set the creation time of a file. - #[stable(feature = "file_set_times", since = "1.75.0")] - fn set_created(self, t: SystemTime) -> Self; -} - -#[stable(feature = "file_set_times", since = "1.75.0")] -impl FileTimesExt for fs::FileTimes { - fn set_created(mut self, t: SystemTime) -> Self { - self.as_inner_mut().set_created(t.into_inner()); - self - } -} diff --git a/library/std/src/os/watchos/mod.rs b/library/std/src/os/watchos/mod.rs deleted file mode 100644 index cd6454ebbf99b..0000000000000 --- a/library/std/src/os/watchos/mod.rs +++ /dev/null @@ -1,6 +0,0 @@ -//! watchOS-specific definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] - -pub mod fs; -pub mod raw; diff --git a/library/std/src/os/watchos/raw.rs b/library/std/src/os/watchos/raw.rs deleted file mode 100644 index 630a533d9aaf2..0000000000000 --- a/library/std/src/os/watchos/raw.rs +++ /dev/null @@ -1,83 +0,0 @@ -//! watchOS-specific raw type definitions - -#![stable(feature = "raw_ext", since = "1.1.0")] -#![deprecated( - since = "1.8.0", - note = "these type aliases are no longer supported by \ - the standard library, the `libc` crate on \ - crates.io should be used instead for the correct \ - definitions" -)] -#![allow(deprecated)] - -use crate::os::raw::c_long; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blkcnt_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type blksize_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type dev_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type ino_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type mode_t = u32; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type nlink_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type off_t = u64; -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type time_t = i64; - -#[stable(feature = "pthread_t", since = "1.8.0")] -pub type pthread_t = usize; - -#[repr(C)] -#[derive(Clone)] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub struct stat { - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_dev: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mode: u16, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_nlink: u16, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ino: u64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_uid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gid: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_rdev: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_atime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_mtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_ctime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_birthtime: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_birthtime_nsec: c_long, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_size: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blocks: i64, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_blksize: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_flags: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_gen: u32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_lspare: i32, - #[stable(feature = "raw_ext", since = "1.1.0")] - pub st_qspare: [i64; 2], -} diff --git a/library/std/src/os/windows/ffi.rs b/library/std/src/os/windows/ffi.rs deleted file mode 100644 index 96bab59d3f8d7..0000000000000 --- a/library/std/src/os/windows/ffi.rs +++ /dev/null @@ -1,136 +0,0 @@ -//! Windows-specific extensions to primitives in the [`std::ffi`] module. -//! -//! # Overview -//! -//! For historical reasons, the Windows API uses a form of potentially -//! ill-formed UTF-16 encoding for strings. Specifically, the 16-bit -//! code units in Windows strings may contain [isolated surrogate code -//! points which are not paired together][ill-formed-utf-16]. The -//! Unicode standard requires that surrogate code points (those in the -//! range U+D800 to U+DFFF) always be *paired*, because in the UTF-16 -//! encoding a *surrogate code unit pair* is used to encode a single -//! character. For compatibility with code that does not enforce -//! these pairings, Windows does not enforce them, either. -//! -//! While it is not always possible to convert such a string losslessly into -//! a valid UTF-16 string (or even UTF-8), it is often desirable to be -//! able to round-trip such a string from and to Windows APIs -//! losslessly. For example, some Rust code may be "bridging" some -//! Windows APIs together, just passing `WCHAR` strings among those -//! APIs without ever really looking into the strings. -//! -//! If Rust code *does* need to look into those strings, it can -//! convert them to valid UTF-8, possibly lossily, by substituting -//! invalid sequences with [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD], as is -//! conventionally done in other Rust APIs that deal with string -//! encodings. -//! -//! # `OsStringExt` and `OsStrExt` -//! -//! [`OsString`] is the Rust wrapper for owned strings in the -//! preferred representation of the operating system. On Windows, -//! this struct gets augmented with an implementation of the -//! [`OsStringExt`] trait, which has an [`OsStringExt::from_wide`] method. This -//! lets you create an [`OsString`] from a `&[u16]` slice; presumably -//! you get such a slice out of a `WCHAR` Windows API. -//! -//! Similarly, [`OsStr`] is the Rust wrapper for borrowed strings from -//! preferred representation of the operating system. On Windows, the -//! [`OsStrExt`] trait provides the [`OsStrExt::encode_wide`] method, which -//! outputs an [`EncodeWide`] iterator. You can [`collect`] this -//! iterator, for example, to obtain a `Vec`; you can later get a -//! pointer to this vector's contents and feed it to Windows APIs. -//! -//! These traits, along with [`OsString`] and [`OsStr`], work in -//! conjunction so that it is possible to **round-trip** strings from -//! Windows and back, with no loss of data, even if the strings are -//! ill-formed UTF-16. -//! -//! [ill-formed-utf-16]: https://simonsapin.github.io/wtf-8/#ill-formed-utf-16 -//! [`collect`]: crate::iter::Iterator::collect -//! [U+FFFD]: crate::char::REPLACEMENT_CHARACTER -//! [`std::ffi`]: crate::ffi - -#![stable(feature = "rust1", since = "1.0.0")] - -use crate::ffi::{OsStr, OsString}; -use crate::sealed::Sealed; -use crate::sys::os_str::Buf; -use crate::sys_common::wtf8::Wtf8Buf; -use crate::sys_common::{AsInner, FromInner}; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use crate::sys_common::wtf8::EncodeWide; - -/// Windows-specific extensions to [`OsString`]. -/// -/// This trait is sealed: it cannot be implemented outside the standard library. -/// This is so that future additional methods are not breaking changes. -#[stable(feature = "rust1", since = "1.0.0")] -pub trait OsStringExt: Sealed { - /// Creates an `OsString` from a potentially ill-formed UTF-16 slice of - /// 16-bit code units. - /// - /// This is lossless: calling [`OsStrExt::encode_wide`] on the resulting string - /// will always return the original code units. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsString; - /// use std::os::windows::prelude::*; - /// - /// // UTF-16 encoding for "Unicode". - /// let source = [0x0055, 0x006E, 0x0069, 0x0063, 0x006F, 0x0064, 0x0065]; - /// - /// let string = OsString::from_wide(&source[..]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn from_wide(wide: &[u16]) -> Self; -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl OsStringExt for OsString { - fn from_wide(wide: &[u16]) -> OsString { - FromInner::from_inner(Buf { inner: Wtf8Buf::from_wide(wide) }) - } -} - -/// Windows-specific extensions to [`OsStr`]. -/// -/// This trait is sealed: it cannot be implemented outside the standard library. -/// This is so that future additional methods are not breaking changes. -#[stable(feature = "rust1", since = "1.0.0")] -pub trait OsStrExt: Sealed { - /// Re-encodes an `OsStr` as a wide character sequence, i.e., potentially - /// ill-formed UTF-16. - /// - /// This is lossless: calling [`OsStringExt::from_wide`] and then - /// `encode_wide` on the result will yield the original code units. - /// Note that the encoding does not add a final null terminator. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsString; - /// use std::os::windows::prelude::*; - /// - /// // UTF-16 encoding for "Unicode". - /// let source = [0x0055, 0x006E, 0x0069, 0x0063, 0x006F, 0x0064, 0x0065]; - /// - /// let string = OsString::from_wide(&source[..]); - /// - /// let result: Vec = string.encode_wide().collect(); - /// assert_eq!(&source[..], &result[..]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - fn encode_wide(&self) -> EncodeWide<'_>; -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl OsStrExt for OsStr { - #[inline] - fn encode_wide(&self) -> EncodeWide<'_> { - self.as_inner().inner.encode_wide() - } -} diff --git a/library/std/src/os/windows/fs.rs b/library/std/src/os/windows/fs.rs deleted file mode 100644 index 27947d91c99de..0000000000000 --- a/library/std/src/os/windows/fs.rs +++ /dev/null @@ -1,634 +0,0 @@ -//! Windows-specific extensions to primitives in the [`std::fs`] module. -//! -//! [`std::fs`]: crate::fs - -#![stable(feature = "rust1", since = "1.0.0")] - -use crate::fs::{self, Metadata, OpenOptions}; -use crate::io; -use crate::path::Path; -use crate::sealed::Sealed; -use crate::sys; -use crate::sys_common::{AsInner, AsInnerMut, IntoInner}; -use crate::time::SystemTime; - -/// Windows-specific extensions to [`fs::File`]. -#[stable(feature = "file_offset", since = "1.15.0")] -pub trait FileExt { - /// Seeks to a given position and reads a number of bytes. - /// - /// Returns the number of bytes read. - /// - /// The offset is relative to the start of the file and thus independent - /// from the current cursor. The current cursor **is** affected by this - /// function, it is set to the end of the read. - /// - /// Reading beyond the end of the file will always return with a length of - /// 0\. - /// - /// Note that similar to `File::read`, it is not an error to return with a - /// short read. When returning from such a short read, the file pointer is - /// still updated. - /// - /// # Examples - /// - /// ```no_run - /// use std::io; - /// use std::fs::File; - /// use std::os::windows::prelude::*; - /// - /// fn main() -> io::Result<()> { - /// let mut file = File::open("foo.txt")?; - /// let mut buffer = [0; 10]; - /// - /// // Read 10 bytes, starting 72 bytes from the - /// // start of the file. - /// file.seek_read(&mut buffer[..], 72)?; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "file_offset", since = "1.15.0")] - fn seek_read(&self, buf: &mut [u8], offset: u64) -> io::Result; - - /// Seeks to a given position and writes a number of bytes. - /// - /// Returns the number of bytes written. - /// - /// The offset is relative to the start of the file and thus independent - /// from the current cursor. The current cursor **is** affected by this - /// function, it is set to the end of the write. - /// - /// When writing beyond the end of the file, the file is appropriately - /// extended and the intermediate bytes are set to zero. - /// - /// Note that similar to `File::write`, it is not an error to return a - /// short write. When returning from such a short write, the file pointer - /// is still updated. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::File; - /// use std::os::windows::prelude::*; - /// - /// fn main() -> std::io::Result<()> { - /// let mut buffer = File::create("foo.txt")?; - /// - /// // Write a byte string starting 72 bytes from - /// // the start of the file. - /// buffer.seek_write(b"some bytes", 72)?; - /// Ok(()) - /// } - /// ``` - #[stable(feature = "file_offset", since = "1.15.0")] - fn seek_write(&self, buf: &[u8], offset: u64) -> io::Result; -} - -#[stable(feature = "file_offset", since = "1.15.0")] -impl FileExt for fs::File { - fn seek_read(&self, buf: &mut [u8], offset: u64) -> io::Result { - self.as_inner().read_at(buf, offset) - } - - fn seek_write(&self, buf: &[u8], offset: u64) -> io::Result { - self.as_inner().write_at(buf, offset) - } -} - -/// Windows-specific extensions to [`fs::OpenOptions`]. -#[stable(feature = "open_options_ext", since = "1.10.0")] -pub trait OpenOptionsExt { - /// Overrides the `dwDesiredAccess` argument to the call to [`CreateFile`] - /// with the specified value. - /// - /// This will override the `read`, `write`, and `append` flags on the - /// `OpenOptions` structure. This method provides fine-grained control over - /// the permissions to read, write and append data, attributes (like hidden - /// and system), and extended attributes. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::OpenOptions; - /// use std::os::windows::prelude::*; - /// - /// // Open without read and write permission, for example if you only need - /// // to call `stat` on the file - /// let file = OpenOptions::new().access_mode(0).open("foo.txt"); - /// ``` - /// - /// [`CreateFile`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea - #[stable(feature = "open_options_ext", since = "1.10.0")] - fn access_mode(&mut self, access: u32) -> &mut Self; - - /// Overrides the `dwShareMode` argument to the call to [`CreateFile`] with - /// the specified value. - /// - /// By default `share_mode` is set to - /// `FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE`. This allows - /// other processes to read, write, and delete/rename the same file - /// while it is open. Removing any of the flags will prevent other - /// processes from performing the corresponding operation until the file - /// handle is closed. - /// - /// # Examples - /// - /// ```no_run - /// use std::fs::OpenOptions; - /// use std::os::windows::prelude::*; - /// - /// // Do not allow others to read or modify this file while we have it open - /// // for writing. - /// let file = OpenOptions::new() - /// .write(true) - /// .share_mode(0) - /// .open("foo.txt"); - /// ``` - /// - /// [`CreateFile`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea - #[stable(feature = "open_options_ext", since = "1.10.0")] - fn share_mode(&mut self, val: u32) -> &mut Self; - - /// Sets extra flags for the `dwFileFlags` argument to the call to - /// [`CreateFile2`] to the specified value (or combines it with - /// `attributes` and `security_qos_flags` to set the `dwFlagsAndAttributes` - /// for [`CreateFile`]). - /// - /// Custom flags can only set flags, not remove flags set by Rust's options. - /// This option overwrites any previously set custom flags. - /// - /// # Examples - /// - /// ```no_run - /// # #![allow(unexpected_cfgs)] - /// # #[cfg(for_demonstration_only)] - /// extern crate winapi; - /// # mod winapi { pub const FILE_FLAG_DELETE_ON_CLOSE: u32 = 0x04000000; } - /// - /// use std::fs::OpenOptions; - /// use std::os::windows::prelude::*; - /// - /// let file = OpenOptions::new() - /// .create(true) - /// .write(true) - /// .custom_flags(winapi::FILE_FLAG_DELETE_ON_CLOSE) - /// .open("foo.txt"); - /// ``` - /// - /// [`CreateFile`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea - /// [`CreateFile2`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfile2 - #[stable(feature = "open_options_ext", since = "1.10.0")] - fn custom_flags(&mut self, flags: u32) -> &mut Self; - - /// Sets the `dwFileAttributes` argument to the call to [`CreateFile2`] to - /// the specified value (or combines it with `custom_flags` and - /// `security_qos_flags` to set the `dwFlagsAndAttributes` for - /// [`CreateFile`]). - /// - /// If a _new_ file is created because it does not yet exist and - /// `.create(true)` or `.create_new(true)` are specified, the new file is - /// given the attributes declared with `.attributes()`. - /// - /// If an _existing_ file is opened with `.create(true).truncate(true)`, its - /// existing attributes are preserved and combined with the ones declared - /// with `.attributes()`. - /// - /// In all other cases the attributes get ignored. - /// - /// # Examples - /// - /// ```no_run - /// # #![allow(unexpected_cfgs)] - /// # #[cfg(for_demonstration_only)] - /// extern crate winapi; - /// # mod winapi { pub const FILE_ATTRIBUTE_HIDDEN: u32 = 2; } - /// - /// use std::fs::OpenOptions; - /// use std::os::windows::prelude::*; - /// - /// let file = OpenOptions::new() - /// .write(true) - /// .create(true) - /// .attributes(winapi::FILE_ATTRIBUTE_HIDDEN) - /// .open("foo.txt"); - /// ``` - /// - /// [`CreateFile`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea - /// [`CreateFile2`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfile2 - #[stable(feature = "open_options_ext", since = "1.10.0")] - fn attributes(&mut self, val: u32) -> &mut Self; - - /// Sets the `dwSecurityQosFlags` argument to the call to [`CreateFile2`] to - /// the specified value (or combines it with `custom_flags` and `attributes` - /// to set the `dwFlagsAndAttributes` for [`CreateFile`]). - /// - /// By default `security_qos_flags` is not set. It should be specified when - /// opening a named pipe, to control to which degree a server process can - /// act on behalf of a client process (security impersonation level). - /// - /// When `security_qos_flags` is not set, a malicious program can gain the - /// elevated privileges of a privileged Rust process when it allows opening - /// user-specified paths, by tricking it into opening a named pipe. So - /// arguably `security_qos_flags` should also be set when opening arbitrary - /// paths. However the bits can then conflict with other flags, specifically - /// `FILE_FLAG_OPEN_NO_RECALL`. - /// - /// For information about possible values, see [Impersonation Levels] on the - /// Windows Dev Center site. The `SECURITY_SQOS_PRESENT` flag is set - /// automatically when using this method. - - /// # Examples - /// - /// ```no_run - /// # #![allow(unexpected_cfgs)] - /// # #[cfg(for_demonstration_only)] - /// extern crate winapi; - /// # mod winapi { pub const SECURITY_IDENTIFICATION: u32 = 0; } - /// use std::fs::OpenOptions; - /// use std::os::windows::prelude::*; - /// - /// let file = OpenOptions::new() - /// .write(true) - /// .create(true) - /// - /// // Sets the flag value to `SecurityIdentification`. - /// .security_qos_flags(winapi::SECURITY_IDENTIFICATION) - /// - /// .open(r"\\.\pipe\MyPipe"); - /// ``` - /// - /// [`CreateFile`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfilea - /// [`CreateFile2`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createfile2 - /// [Impersonation Levels]: - /// https://docs.microsoft.com/en-us/windows/win32/api/winnt/ne-winnt-security_impersonation_level - #[stable(feature = "open_options_ext", since = "1.10.0")] - fn security_qos_flags(&mut self, flags: u32) -> &mut Self; -} - -#[stable(feature = "open_options_ext", since = "1.10.0")] -impl OpenOptionsExt for OpenOptions { - fn access_mode(&mut self, access: u32) -> &mut OpenOptions { - self.as_inner_mut().access_mode(access); - self - } - - fn share_mode(&mut self, share: u32) -> &mut OpenOptions { - self.as_inner_mut().share_mode(share); - self - } - - fn custom_flags(&mut self, flags: u32) -> &mut OpenOptions { - self.as_inner_mut().custom_flags(flags); - self - } - - fn attributes(&mut self, attributes: u32) -> &mut OpenOptions { - self.as_inner_mut().attributes(attributes); - self - } - - fn security_qos_flags(&mut self, flags: u32) -> &mut OpenOptions { - self.as_inner_mut().security_qos_flags(flags); - self - } -} - -/// Windows-specific extensions to [`fs::Metadata`]. -/// -/// The data members that this trait exposes correspond to the members -/// of the [`BY_HANDLE_FILE_INFORMATION`] structure. -/// -/// [`BY_HANDLE_FILE_INFORMATION`]: -/// https://docs.microsoft.com/en-us/windows/win32/api/fileapi/ns-fileapi-by_handle_file_information -#[stable(feature = "metadata_ext", since = "1.1.0")] -pub trait MetadataExt { - /// Returns the value of the `dwFileAttributes` field of this metadata. - /// - /// This field contains the file system attribute information for a file - /// or directory. For possible values and their descriptions, see - /// [File Attribute Constants] in the Windows Dev Center. - /// - /// # Examples - /// - /// ```no_run - /// use std::io; - /// use std::fs; - /// use std::os::windows::prelude::*; - /// - /// fn main() -> io::Result<()> { - /// let metadata = fs::metadata("foo.txt")?; - /// let attributes = metadata.file_attributes(); - /// Ok(()) - /// } - /// ``` - /// - /// [File Attribute Constants]: - /// https://docs.microsoft.com/en-us/windows/win32/fileio/file-attribute-constants - #[stable(feature = "metadata_ext", since = "1.1.0")] - fn file_attributes(&self) -> u32; - - /// Returns the value of the `ftCreationTime` field of this metadata. - /// - /// The returned 64-bit value is equivalent to a [`FILETIME`] struct, - /// which represents the number of 100-nanosecond intervals since - /// January 1, 1601 (UTC). The struct is automatically - /// converted to a `u64` value, as that is the recommended way - /// to use it. - /// - /// If the underlying filesystem does not support creation time, the - /// returned value is 0. - /// - /// # Examples - /// - /// ```no_run - /// use std::io; - /// use std::fs; - /// use std::os::windows::prelude::*; - /// - /// fn main() -> io::Result<()> { - /// let metadata = fs::metadata("foo.txt")?; - /// let creation_time = metadata.creation_time(); - /// Ok(()) - /// } - /// ``` - /// - /// [`FILETIME`]: https://docs.microsoft.com/en-us/windows/win32/api/minwinbase/ns-minwinbase-filetime - #[stable(feature = "metadata_ext", since = "1.1.0")] - fn creation_time(&self) -> u64; - - /// Returns the value of the `ftLastAccessTime` field of this metadata. - /// - /// The returned 64-bit value is equivalent to a [`FILETIME`] struct, - /// which represents the number of 100-nanosecond intervals since - /// January 1, 1601 (UTC). The struct is automatically - /// converted to a `u64` value, as that is the recommended way - /// to use it. - /// - /// For a file, the value specifies the last time that a file was read - /// from or written to. For a directory, the value specifies when - /// the directory was created. For both files and directories, the - /// specified date is correct, but the time of day is always set to - /// midnight. - /// - /// If the underlying filesystem does not support last access time, the - /// returned value is 0. - /// - /// # Examples - /// - /// ```no_run - /// use std::io; - /// use std::fs; - /// use std::os::windows::prelude::*; - /// - /// fn main() -> io::Result<()> { - /// let metadata = fs::metadata("foo.txt")?; - /// let last_access_time = metadata.last_access_time(); - /// Ok(()) - /// } - /// ``` - /// - /// [`FILETIME`]: https://docs.microsoft.com/en-us/windows/win32/api/minwinbase/ns-minwinbase-filetime - #[stable(feature = "metadata_ext", since = "1.1.0")] - fn last_access_time(&self) -> u64; - - /// Returns the value of the `ftLastWriteTime` field of this metadata. - /// - /// The returned 64-bit value is equivalent to a [`FILETIME`] struct, - /// which represents the number of 100-nanosecond intervals since - /// January 1, 1601 (UTC). The struct is automatically - /// converted to a `u64` value, as that is the recommended way - /// to use it. - /// - /// For a file, the value specifies the last time that a file was written - /// to. For a directory, the structure specifies when the directory was - /// created. - /// - /// If the underlying filesystem does not support the last write time, - /// the returned value is 0. - /// - /// # Examples - /// - /// ```no_run - /// use std::io; - /// use std::fs; - /// use std::os::windows::prelude::*; - /// - /// fn main() -> io::Result<()> { - /// let metadata = fs::metadata("foo.txt")?; - /// let last_write_time = metadata.last_write_time(); - /// Ok(()) - /// } - /// ``` - /// - /// [`FILETIME`]: https://docs.microsoft.com/en-us/windows/win32/api/minwinbase/ns-minwinbase-filetime - #[stable(feature = "metadata_ext", since = "1.1.0")] - fn last_write_time(&self) -> u64; - - /// Returns the value of the `nFileSize{High,Low}` fields of this - /// metadata. - /// - /// The returned value does not have meaning for directories. - /// - /// # Examples - /// - /// ```no_run - /// use std::io; - /// use std::fs; - /// use std::os::windows::prelude::*; - /// - /// fn main() -> io::Result<()> { - /// let metadata = fs::metadata("foo.txt")?; - /// let file_size = metadata.file_size(); - /// Ok(()) - /// } - /// ``` - #[stable(feature = "metadata_ext", since = "1.1.0")] - fn file_size(&self) -> u64; - - /// Returns the value of the `dwVolumeSerialNumber` field of this - /// metadata. - /// - /// This will return `None` if the `Metadata` instance was created from a - /// call to `DirEntry::metadata`. If this `Metadata` was created by using - /// `fs::metadata` or `File::metadata`, then this will return `Some`. - #[unstable(feature = "windows_by_handle", issue = "63010")] - fn volume_serial_number(&self) -> Option; - - /// Returns the value of the `nNumberOfLinks` field of this - /// metadata. - /// - /// This will return `None` if the `Metadata` instance was created from a - /// call to `DirEntry::metadata`. If this `Metadata` was created by using - /// `fs::metadata` or `File::metadata`, then this will return `Some`. - #[unstable(feature = "windows_by_handle", issue = "63010")] - fn number_of_links(&self) -> Option; - - /// Returns the value of the `nFileIndex{Low,High}` fields of this - /// metadata. - /// - /// This will return `None` if the `Metadata` instance was created from a - /// call to `DirEntry::metadata`. If this `Metadata` was created by using - /// `fs::metadata` or `File::metadata`, then this will return `Some`. - #[unstable(feature = "windows_by_handle", issue = "63010")] - fn file_index(&self) -> Option; -} - -#[stable(feature = "metadata_ext", since = "1.1.0")] -impl MetadataExt for Metadata { - fn file_attributes(&self) -> u32 { - self.as_inner().attrs() - } - fn creation_time(&self) -> u64 { - self.as_inner().created_u64() - } - fn last_access_time(&self) -> u64 { - self.as_inner().accessed_u64() - } - fn last_write_time(&self) -> u64 { - self.as_inner().modified_u64() - } - fn file_size(&self) -> u64 { - self.as_inner().size() - } - fn volume_serial_number(&self) -> Option { - self.as_inner().volume_serial_number() - } - fn number_of_links(&self) -> Option { - self.as_inner().number_of_links() - } - fn file_index(&self) -> Option { - self.as_inner().file_index() - } -} - -/// Windows-specific extensions to [`fs::FileType`]. -/// -/// On Windows, a symbolic link knows whether it is a file or directory. -#[stable(feature = "windows_file_type_ext", since = "1.64.0")] -pub trait FileTypeExt: Sealed { - /// Returns `true` if this file type is a symbolic link that is also a directory. - #[stable(feature = "windows_file_type_ext", since = "1.64.0")] - fn is_symlink_dir(&self) -> bool; - /// Returns `true` if this file type is a symbolic link that is also a file. - #[stable(feature = "windows_file_type_ext", since = "1.64.0")] - fn is_symlink_file(&self) -> bool; -} - -#[stable(feature = "windows_file_type_ext", since = "1.64.0")] -impl Sealed for fs::FileType {} - -#[stable(feature = "windows_file_type_ext", since = "1.64.0")] -impl FileTypeExt for fs::FileType { - fn is_symlink_dir(&self) -> bool { - self.as_inner().is_symlink_dir() - } - fn is_symlink_file(&self) -> bool { - self.as_inner().is_symlink_file() - } -} - -/// Windows-specific extensions to [`fs::FileTimes`]. -#[stable(feature = "file_set_times", since = "1.75.0")] -pub trait FileTimesExt: Sealed { - /// Set the creation time of a file. - #[stable(feature = "file_set_times", since = "1.75.0")] - fn set_created(self, t: SystemTime) -> Self; -} - -#[stable(feature = "file_set_times", since = "1.75.0")] -impl FileTimesExt for fs::FileTimes { - fn set_created(mut self, t: SystemTime) -> Self { - self.as_inner_mut().set_created(t.into_inner()); - self - } -} - -/// Creates a new symlink to a non-directory file on the filesystem. -/// -/// The `link` path will be a file symbolic link pointing to the `original` -/// path. -/// -/// The `original` path should not be a directory or a symlink to a directory, -/// otherwise the symlink will be broken. Use [`symlink_dir`] for directories. -/// -/// This function currently corresponds to [`CreateSymbolicLinkW`][CreateSymbolicLinkW]. -/// Note that this [may change in the future][changes]. -/// -/// [CreateSymbolicLinkW]: https://docs.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-createsymboliclinkw -/// [changes]: io#platform-specific-behavior -/// -/// # Examples -/// -/// ```no_run -/// use std::os::windows::fs; -/// -/// fn main() -> std::io::Result<()> { -/// fs::symlink_file("a.txt", "b.txt")?; -/// Ok(()) -/// } -/// ``` -/// -/// # Limitations -/// -/// Windows treats symlink creation as a [privileged action][symlink-security], -/// therefore this function is likely to fail unless the user makes changes to -/// their system to permit symlink creation. Users can try enabling Developer -/// Mode, granting the `SeCreateSymbolicLinkPrivilege` privilege, or running -/// the process as an administrator. -/// -/// [symlink-security]: https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/create-symbolic-links -#[stable(feature = "symlink", since = "1.1.0")] -pub fn symlink_file, Q: AsRef>(original: P, link: Q) -> io::Result<()> { - sys::fs::symlink_inner(original.as_ref(), link.as_ref(), false) -} - -/// Creates a new symlink to a directory on the filesystem. -/// -/// The `link` path will be a directory symbolic link pointing to the `original` -/// path. -/// -/// The `original` path must be a directory or a symlink to a directory, -/// otherwise the symlink will be broken. Use [`symlink_file`] for other files. -/// -/// This function currently corresponds to [`CreateSymbolicLinkW`][CreateSymbolicLinkW]. -/// Note that this [may change in the future][changes]. -/// -/// [CreateSymbolicLinkW]: https://docs.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-createsymboliclinkw -/// [changes]: io#platform-specific-behavior -/// -/// # Examples -/// -/// ```no_run -/// use std::os::windows::fs; -/// -/// fn main() -> std::io::Result<()> { -/// fs::symlink_dir("a", "b")?; -/// Ok(()) -/// } -/// ``` -/// -/// # Limitations -/// -/// Windows treats symlink creation as a [privileged action][symlink-security], -/// therefore this function is likely to fail unless the user makes changes to -/// their system to permit symlink creation. Users can try enabling Developer -/// Mode, granting the `SeCreateSymbolicLinkPrivilege` privilege, or running -/// the process as an administrator. -/// -/// [symlink-security]: https://docs.microsoft.com/en-us/windows/security/threat-protection/security-policy-settings/create-symbolic-links -#[stable(feature = "symlink", since = "1.1.0")] -pub fn symlink_dir, Q: AsRef>(original: P, link: Q) -> io::Result<()> { - sys::fs::symlink_inner(original.as_ref(), link.as_ref(), true) -} - -/// Create a junction point. -/// -/// The `link` path will be a directory junction pointing to the original path. -/// If `link` is a relative path then it will be made absolute prior to creating the junction point. -/// The `original` path must be a directory or a link to a directory, otherwise the junction point will be broken. -/// -/// If either path is not a local file path then this will fail. -#[unstable(feature = "junction_point", issue = "121709")] -pub fn junction_point, Q: AsRef>(original: P, link: Q) -> io::Result<()> { - sys::fs::junction_point(original.as_ref(), link.as_ref()) -} diff --git a/library/std/src/os/windows/io/handle.rs b/library/std/src/os/windows/io/handle.rs deleted file mode 100644 index a9d1983dce610..0000000000000 --- a/library/std/src/os/windows/io/handle.rs +++ /dev/null @@ -1,660 +0,0 @@ -//! Owned and borrowed OS handles. - -#![stable(feature = "io_safety", since = "1.63.0")] - -use super::raw::{AsRawHandle, FromRawHandle, IntoRawHandle, RawHandle}; -use crate::fmt; -use crate::fs; -use crate::io; -use crate::marker::PhantomData; -use crate::mem::{forget, ManuallyDrop}; -use crate::ptr; -use crate::sys; -use crate::sys::cvt; -use crate::sys_common::{AsInner, FromInner, IntoInner}; - -/// A borrowed handle. -/// -/// This has a lifetime parameter to tie it to the lifetime of something that -/// owns the handle. -/// -/// This uses `repr(transparent)` and has the representation of a host handle, -/// so it can be used in FFI in places where a handle is passed as an argument, -/// it is not captured or consumed. -/// -/// Note that it *may* have the value `-1`, which in `BorrowedHandle` always -/// represents a valid handle value, such as [the current process handle], and -/// not `INVALID_HANDLE_VALUE`, despite the two having the same value. See -/// [here] for the full story. -/// -/// And, it *may* have the value `NULL` (0), which can occur when consoles are -/// detached from processes, or when `windows_subsystem` is used. -/// -/// This type's `.to_owned()` implementation returns another `BorrowedHandle` -/// rather than an `OwnedHandle`. It just makes a trivial copy of the raw -/// handle, which is then borrowed under the same lifetime. -/// -/// [here]: https://devblogs.microsoft.com/oldnewthing/20040302-00/?p=40443 -/// [the current process handle]: https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getcurrentprocess#remarks -#[derive(Copy, Clone)] -#[repr(transparent)] -#[stable(feature = "io_safety", since = "1.63.0")] -pub struct BorrowedHandle<'handle> { - handle: RawHandle, - _phantom: PhantomData<&'handle OwnedHandle>, -} - -/// An owned handle. -/// -/// This closes the handle on drop. -/// -/// Note that it *may* have the value `-1`, which in `OwnedHandle` always -/// represents a valid handle value, such as [the current process handle], and -/// not `INVALID_HANDLE_VALUE`, despite the two having the same value. See -/// [here] for the full story. -/// -/// And, it *may* have the value `NULL` (0), which can occur when consoles are -/// detached from processes, or when `windows_subsystem` is used. -/// -/// `OwnedHandle` uses [`CloseHandle`] to close its handle on drop. As such, -/// it must not be used with handles to open registry keys which need to be -/// closed with [`RegCloseKey`] instead. -/// -/// [`CloseHandle`]: https://docs.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-closehandle -/// [`RegCloseKey`]: https://docs.microsoft.com/en-us/windows/win32/api/winreg/nf-winreg-regclosekey -/// -/// [here]: https://devblogs.microsoft.com/oldnewthing/20040302-00/?p=40443 -/// [the current process handle]: https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getcurrentprocess#remarks -#[repr(transparent)] -#[stable(feature = "io_safety", since = "1.63.0")] -pub struct OwnedHandle { - handle: RawHandle, -} - -/// FFI type for handles in return values or out parameters, where `NULL` is used -/// as a sentry value to indicate errors, such as in the return value of `CreateThread`. This uses -/// `repr(transparent)` and has the representation of a host handle, so that it can be used in such -/// FFI declarations. -/// -/// The only thing you can usefully do with a `HandleOrNull` is to convert it into an -/// `OwnedHandle` using its [`TryFrom`] implementation; this conversion takes care of the check for -/// `NULL`. This ensures that such FFI calls cannot start using the handle without -/// checking for `NULL` first. -/// -/// This type may hold any handle value that [`OwnedHandle`] may hold. As with `OwnedHandle`, when -/// it holds `-1`, that value is interpreted as a valid handle value, such as -/// [the current process handle], and not `INVALID_HANDLE_VALUE`. -/// -/// If this holds a non-null handle, it will close the handle on drop. -/// -/// [the current process handle]: https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getcurrentprocess#remarks -#[repr(transparent)] -#[stable(feature = "io_safety", since = "1.63.0")] -#[derive(Debug)] -pub struct HandleOrNull(RawHandle); - -/// FFI type for handles in return values or out parameters, where `INVALID_HANDLE_VALUE` is used -/// as a sentry value to indicate errors, such as in the return value of `CreateFileW`. This uses -/// `repr(transparent)` and has the representation of a host handle, so that it can be used in such -/// FFI declarations. -/// -/// The only thing you can usefully do with a `HandleOrInvalid` is to convert it into an -/// `OwnedHandle` using its [`TryFrom`] implementation; this conversion takes care of the check for -/// `INVALID_HANDLE_VALUE`. This ensures that such FFI calls cannot start using the handle without -/// checking for `INVALID_HANDLE_VALUE` first. -/// -/// This type may hold any handle value that [`OwnedHandle`] may hold, except that when it holds -/// `-1`, that value is interpreted to mean `INVALID_HANDLE_VALUE`. -/// -/// If holds a handle other than `INVALID_HANDLE_VALUE`, it will close the handle on drop. -#[repr(transparent)] -#[stable(feature = "io_safety", since = "1.63.0")] -#[derive(Debug)] -pub struct HandleOrInvalid(RawHandle); - -// The Windows [`HANDLE`] type may be transferred across and shared between -// thread boundaries (despite containing a `*mut void`, which in general isn't -// `Send` or `Sync`). -// -// [`HANDLE`]: std::os::windows::raw::HANDLE -#[stable(feature = "io_safety", since = "1.63.0")] -unsafe impl Send for OwnedHandle {} -#[stable(feature = "io_safety", since = "1.63.0")] -unsafe impl Send for HandleOrNull {} -#[stable(feature = "io_safety", since = "1.63.0")] -unsafe impl Send for HandleOrInvalid {} -#[stable(feature = "io_safety", since = "1.63.0")] -unsafe impl Send for BorrowedHandle<'_> {} -#[stable(feature = "io_safety", since = "1.63.0")] -unsafe impl Sync for OwnedHandle {} -#[stable(feature = "io_safety", since = "1.63.0")] -unsafe impl Sync for HandleOrNull {} -#[stable(feature = "io_safety", since = "1.63.0")] -unsafe impl Sync for HandleOrInvalid {} -#[stable(feature = "io_safety", since = "1.63.0")] -unsafe impl Sync for BorrowedHandle<'_> {} - -impl BorrowedHandle<'_> { - /// Return a `BorrowedHandle` holding the given raw handle. - /// - /// # Safety - /// - /// The resource pointed to by `handle` must be a valid open handle, it - /// must remain open for the duration of the returned `BorrowedHandle`. - /// - /// Note that it *may* have the value `INVALID_HANDLE_VALUE` (-1), which is - /// sometimes a valid handle value. See [here] for the full story. - /// - /// And, it *may* have the value `NULL` (0), which can occur when consoles are - /// detached from processes, or when `windows_subsystem` is used. - /// - /// [here]: https://devblogs.microsoft.com/oldnewthing/20040302-00/?p=40443 - #[inline] - #[rustc_const_stable(feature = "io_safety", since = "1.63.0")] - #[stable(feature = "io_safety", since = "1.63.0")] - pub const unsafe fn borrow_raw(handle: RawHandle) -> Self { - Self { handle, _phantom: PhantomData } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl TryFrom for OwnedHandle { - type Error = NullHandleError; - - #[inline] - fn try_from(handle_or_null: HandleOrNull) -> Result { - let handle_or_null = ManuallyDrop::new(handle_or_null); - if handle_or_null.is_valid() { - // SAFETY: The handle is not null. - Ok(unsafe { OwnedHandle::from_raw_handle(handle_or_null.0) }) - } else { - Err(NullHandleError(())) - } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl Drop for HandleOrNull { - #[inline] - fn drop(&mut self) { - if self.is_valid() { - unsafe { - let _ = sys::c::CloseHandle(self.0); - } - } - } -} - -impl OwnedHandle { - /// Creates a new `OwnedHandle` instance that shares the same underlying - /// object as the existing `OwnedHandle` instance. - #[stable(feature = "io_safety", since = "1.63.0")] - pub fn try_clone(&self) -> crate::io::Result { - self.as_handle().try_clone_to_owned() - } -} - -impl BorrowedHandle<'_> { - /// Creates a new `OwnedHandle` instance that shares the same underlying - /// object as the existing `BorrowedHandle` instance. - #[stable(feature = "io_safety", since = "1.63.0")] - pub fn try_clone_to_owned(&self) -> crate::io::Result { - self.duplicate(0, false, sys::c::DUPLICATE_SAME_ACCESS) - } - - pub(crate) fn duplicate( - &self, - access: u32, - inherit: bool, - options: u32, - ) -> io::Result { - let handle = self.as_raw_handle(); - - // `Stdin`, `Stdout`, and `Stderr` can all hold null handles, such as - // in a process with a detached console. `DuplicateHandle` would fail - // if we passed it a null handle, but we can treat null as a valid - // handle which doesn't do any I/O, and allow it to be duplicated. - if handle.is_null() { - return unsafe { Ok(OwnedHandle::from_raw_handle(handle)) }; - } - - let mut ret = ptr::null_mut(); - cvt(unsafe { - let cur_proc = sys::c::GetCurrentProcess(); - sys::c::DuplicateHandle( - cur_proc, - handle, - cur_proc, - &mut ret, - access, - inherit as sys::c::BOOL, - options, - ) - })?; - unsafe { Ok(OwnedHandle::from_raw_handle(ret)) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl TryFrom for OwnedHandle { - type Error = InvalidHandleError; - - #[inline] - fn try_from(handle_or_invalid: HandleOrInvalid) -> Result { - let handle_or_invalid = ManuallyDrop::new(handle_or_invalid); - if handle_or_invalid.is_valid() { - // SAFETY: The handle is not invalid. - Ok(unsafe { OwnedHandle::from_raw_handle(handle_or_invalid.0) }) - } else { - Err(InvalidHandleError(())) - } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl Drop for HandleOrInvalid { - #[inline] - fn drop(&mut self) { - if self.is_valid() { - unsafe { - let _ = sys::c::CloseHandle(self.0); - } - } - } -} - -/// This is the error type used by [`HandleOrNull`] when attempting to convert -/// into a handle, to indicate that the value is null. -// The empty field prevents constructing this, and allows extending it in the future. -#[stable(feature = "io_safety", since = "1.63.0")] -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct NullHandleError(()); - -#[stable(feature = "io_safety", since = "1.63.0")] -impl fmt::Display for NullHandleError { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - "A HandleOrNull could not be converted to a handle because it was null".fmt(fmt) - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl crate::error::Error for NullHandleError {} - -/// This is the error type used by [`HandleOrInvalid`] when attempting to -/// convert into a handle, to indicate that the value is -/// `INVALID_HANDLE_VALUE`. -// The empty field prevents constructing this, and allows extending it in the future. -#[stable(feature = "io_safety", since = "1.63.0")] -#[derive(Debug, Clone, PartialEq, Eq)] -pub struct InvalidHandleError(()); - -#[stable(feature = "io_safety", since = "1.63.0")] -impl fmt::Display for InvalidHandleError { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - "A HandleOrInvalid could not be converted to a handle because it was INVALID_HANDLE_VALUE" - .fmt(fmt) - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl crate::error::Error for InvalidHandleError {} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsRawHandle for BorrowedHandle<'_> { - #[inline] - fn as_raw_handle(&self) -> RawHandle { - self.handle - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsRawHandle for OwnedHandle { - #[inline] - fn as_raw_handle(&self) -> RawHandle { - self.handle - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl IntoRawHandle for OwnedHandle { - #[inline] - fn into_raw_handle(self) -> RawHandle { - let handle = self.handle; - forget(self); - handle - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl FromRawHandle for OwnedHandle { - #[inline] - unsafe fn from_raw_handle(handle: RawHandle) -> Self { - Self { handle } - } -} - -impl HandleOrNull { - /// Constructs a new instance of `Self` from the given `RawHandle` returned - /// from a Windows API that uses null to indicate failure, such as - /// `CreateThread`. - /// - /// Use `HandleOrInvalid` instead of `HandleOrNull` for APIs that - /// use `INVALID_HANDLE_VALUE` to indicate failure. - /// - /// # Safety - /// - /// The passed `handle` value must either satisfy the safety requirements - /// of [`FromRawHandle::from_raw_handle`], or be null. Note that not all - /// Windows APIs use null for errors; see [here] for the full story. - /// - /// [here]: https://devblogs.microsoft.com/oldnewthing/20040302-00/?p=40443 - #[stable(feature = "io_safety", since = "1.63.0")] - #[inline] - pub unsafe fn from_raw_handle(handle: RawHandle) -> Self { - Self(handle) - } - - fn is_valid(&self) -> bool { - !self.0.is_null() - } -} - -impl HandleOrInvalid { - /// Constructs a new instance of `Self` from the given `RawHandle` returned - /// from a Windows API that uses `INVALID_HANDLE_VALUE` to indicate - /// failure, such as `CreateFileW`. - /// - /// Use `HandleOrNull` instead of `HandleOrInvalid` for APIs that - /// use null to indicate failure. - /// - /// # Safety - /// - /// The passed `handle` value must either satisfy the safety requirements - /// of [`FromRawHandle::from_raw_handle`], or be - /// `INVALID_HANDLE_VALUE` (-1). Note that not all Windows APIs use - /// `INVALID_HANDLE_VALUE` for errors; see [here] for the full story. - /// - /// [here]: https://devblogs.microsoft.com/oldnewthing/20040302-00/?p=40443 - #[stable(feature = "io_safety", since = "1.63.0")] - #[inline] - pub unsafe fn from_raw_handle(handle: RawHandle) -> Self { - Self(handle) - } - - fn is_valid(&self) -> bool { - self.0 != sys::c::INVALID_HANDLE_VALUE - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl Drop for OwnedHandle { - #[inline] - fn drop(&mut self) { - unsafe { - let _ = sys::c::CloseHandle(self.handle); - } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl fmt::Debug for BorrowedHandle<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("BorrowedHandle").field("handle", &self.handle).finish() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl fmt::Debug for OwnedHandle { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("OwnedHandle").field("handle", &self.handle).finish() - } -} - -macro_rules! impl_is_terminal { - ($($t:ty),*$(,)?) => {$( - #[unstable(feature = "sealed", issue = "none")] - impl crate::sealed::Sealed for $t {} - - #[stable(feature = "is_terminal", since = "1.70.0")] - impl crate::io::IsTerminal for $t { - #[inline] - fn is_terminal(&self) -> bool { - crate::sys::io::is_terminal(self) - } - } - )*} -} - -impl_is_terminal!(BorrowedHandle<'_>, OwnedHandle); - -/// A trait to borrow the handle from an underlying object. -#[stable(feature = "io_safety", since = "1.63.0")] -pub trait AsHandle { - /// Borrows the handle. - /// - /// # Example - /// - /// ```rust,no_run - /// use std::fs::File; - /// # use std::io; - /// use std::os::windows::io::{AsHandle, BorrowedHandle}; - /// - /// let mut f = File::open("foo.txt")?; - /// let borrowed_handle: BorrowedHandle<'_> = f.as_handle(); - /// # Ok::<(), io::Error>(()) - /// ``` - #[stable(feature = "io_safety", since = "1.63.0")] - fn as_handle(&self) -> BorrowedHandle<'_>; -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsHandle for &T { - #[inline] - fn as_handle(&self) -> BorrowedHandle<'_> { - T::as_handle(self) - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsHandle for &mut T { - #[inline] - fn as_handle(&self) -> BorrowedHandle<'_> { - T::as_handle(self) - } -} - -#[stable(feature = "as_windows_ptrs", since = "1.71.0")] -/// This impl allows implementing traits that require `AsHandle` on Arc. -/// ``` -/// # #[cfg(windows)] mod group_cfg { -/// # use std::os::windows::io::AsHandle; -/// use std::fs::File; -/// use std::sync::Arc; -/// -/// trait MyTrait: AsHandle {} -/// impl MyTrait for Arc {} -/// impl MyTrait for Box {} -/// # } -/// ``` -impl AsHandle for crate::sync::Arc { - #[inline] - fn as_handle(&self) -> BorrowedHandle<'_> { - (**self).as_handle() - } -} - -#[stable(feature = "as_windows_ptrs", since = "1.71.0")] -impl AsHandle for crate::rc::Rc { - #[inline] - fn as_handle(&self) -> BorrowedHandle<'_> { - (**self).as_handle() - } -} - -#[stable(feature = "as_windows_ptrs", since = "1.71.0")] -impl AsHandle for Box { - #[inline] - fn as_handle(&self) -> BorrowedHandle<'_> { - (**self).as_handle() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsHandle for BorrowedHandle<'_> { - #[inline] - fn as_handle(&self) -> BorrowedHandle<'_> { - *self - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsHandle for OwnedHandle { - #[inline] - fn as_handle(&self) -> BorrowedHandle<'_> { - // Safety: `OwnedHandle` and `BorrowedHandle` have the same validity - // invariants, and the `BorrowedHandle` is bounded by the lifetime - // of `&self`. - unsafe { BorrowedHandle::borrow_raw(self.as_raw_handle()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsHandle for fs::File { - #[inline] - fn as_handle(&self) -> BorrowedHandle<'_> { - self.as_inner().as_handle() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for OwnedHandle { - /// Takes ownership of a [`File`](fs::File)'s underlying file handle. - #[inline] - fn from(file: fs::File) -> OwnedHandle { - file.into_inner().into_inner().into_inner() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for fs::File { - /// Returns a [`File`](fs::File) that takes ownership of the given handle. - #[inline] - fn from(owned: OwnedHandle) -> Self { - Self::from_inner(FromInner::from_inner(FromInner::from_inner(owned))) - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsHandle for crate::io::Stdin { - #[inline] - fn as_handle(&self) -> BorrowedHandle<'_> { - unsafe { BorrowedHandle::borrow_raw(self.as_raw_handle()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl<'a> AsHandle for crate::io::StdinLock<'a> { - #[inline] - fn as_handle(&self) -> BorrowedHandle<'_> { - unsafe { BorrowedHandle::borrow_raw(self.as_raw_handle()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsHandle for crate::io::Stdout { - #[inline] - fn as_handle(&self) -> BorrowedHandle<'_> { - unsafe { BorrowedHandle::borrow_raw(self.as_raw_handle()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl<'a> AsHandle for crate::io::StdoutLock<'a> { - #[inline] - fn as_handle(&self) -> BorrowedHandle<'_> { - unsafe { BorrowedHandle::borrow_raw(self.as_raw_handle()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsHandle for crate::io::Stderr { - #[inline] - fn as_handle(&self) -> BorrowedHandle<'_> { - unsafe { BorrowedHandle::borrow_raw(self.as_raw_handle()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl<'a> AsHandle for crate::io::StderrLock<'a> { - #[inline] - fn as_handle(&self) -> BorrowedHandle<'_> { - unsafe { BorrowedHandle::borrow_raw(self.as_raw_handle()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsHandle for crate::process::ChildStdin { - #[inline] - fn as_handle(&self) -> BorrowedHandle<'_> { - unsafe { BorrowedHandle::borrow_raw(self.as_raw_handle()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for OwnedHandle { - /// Takes ownership of a [`ChildStdin`](crate::process::ChildStdin)'s file handle. - #[inline] - fn from(child_stdin: crate::process::ChildStdin) -> OwnedHandle { - unsafe { OwnedHandle::from_raw_handle(child_stdin.into_raw_handle()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsHandle for crate::process::ChildStdout { - #[inline] - fn as_handle(&self) -> BorrowedHandle<'_> { - unsafe { BorrowedHandle::borrow_raw(self.as_raw_handle()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for OwnedHandle { - /// Takes ownership of a [`ChildStdout`](crate::process::ChildStdout)'s file handle. - #[inline] - fn from(child_stdout: crate::process::ChildStdout) -> OwnedHandle { - unsafe { OwnedHandle::from_raw_handle(child_stdout.into_raw_handle()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsHandle for crate::process::ChildStderr { - #[inline] - fn as_handle(&self) -> BorrowedHandle<'_> { - unsafe { BorrowedHandle::borrow_raw(self.as_raw_handle()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for OwnedHandle { - /// Takes ownership of a [`ChildStderr`](crate::process::ChildStderr)'s file handle. - #[inline] - fn from(child_stderr: crate::process::ChildStderr) -> OwnedHandle { - unsafe { OwnedHandle::from_raw_handle(child_stderr.into_raw_handle()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsHandle for crate::thread::JoinHandle { - #[inline] - fn as_handle(&self) -> BorrowedHandle<'_> { - unsafe { BorrowedHandle::borrow_raw(self.as_raw_handle()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From> for OwnedHandle { - #[inline] - fn from(join_handle: crate::thread::JoinHandle) -> OwnedHandle { - join_handle.into_inner().into_handle().into_inner() - } -} diff --git a/library/std/src/os/windows/io/mod.rs b/library/std/src/os/windows/io/mod.rs deleted file mode 100644 index 3d3ae38788639..0000000000000 --- a/library/std/src/os/windows/io/mod.rs +++ /dev/null @@ -1,69 +0,0 @@ -//! Windows-specific extensions to general I/O primitives. -//! -//! Just like raw pointers, raw Windows handles and sockets point to resources -//! with dynamic lifetimes, and they can dangle if they outlive their resources -//! or be forged if they're created from invalid values. -//! -//! This module provides three types for representing raw handles and sockets -//! with different ownership properties: raw, borrowed, and owned, which are -//! analogous to types used for representing pointers. These types reflect concepts of [I/O -//! safety][io-safety] on Windows. -//! -//! | Type | Analogous to | -//! | ---------------------- | ------------ | -//! | [`RawHandle`] | `*const _` | -//! | [`RawSocket`] | `*const _` | -//! | | | -//! | [`BorrowedHandle<'a>`] | `&'a _` | -//! | [`BorrowedSocket<'a>`] | `&'a _` | -//! | | | -//! | [`OwnedHandle`] | `Box<_>` | -//! | [`OwnedSocket`] | `Box<_>` | -//! -//! Like raw pointers, `RawHandle` and `RawSocket` values are primitive values. -//! And in new code, they should be considered unsafe to do I/O on (analogous -//! to dereferencing them). Rust did not always provide this guidance, so -//! existing code in the Rust ecosystem often doesn't mark `RawHandle` and -//! `RawSocket` usage as unsafe. -//! Libraries are encouraged to migrate, either by adding `unsafe` to APIs -//! that dereference `RawHandle` and `RawSocket` values, or by using to -//! `BorrowedHandle`, `BorrowedSocket`, `OwnedHandle`, or `OwnedSocket`. -//! -//! Like references, `BorrowedHandle` and `BorrowedSocket` values are tied to a -//! lifetime, to ensure that they don't outlive the resource they point to. -//! These are safe to use. `BorrowedHandle` and `BorrowedSocket` values may be -//! used in APIs which provide safe access to any system call except for -//! `CloseHandle`, `closesocket`, or any other call that would end the -//! dynamic lifetime of the resource without ending the lifetime of the -//! handle or socket. -//! -//! `BorrowedHandle` and `BorrowedSocket` values may be used in APIs which -//! provide safe access to `DuplicateHandle` and `WSADuplicateSocketW` and -//! related functions, so types implementing `AsHandle`, `AsSocket`, -//! `From`, or `From` should not assume they always -//! have exclusive access to the underlying object. -//! -//! Like boxes, `OwnedHandle` and `OwnedSocket` values conceptually own the -//! resource they point to, and free (close) it when they are dropped. -//! -//! See the [`io` module docs][io-safety] for a general explanation of I/O safety. -//! -//! [`BorrowedHandle<'a>`]: crate::os::windows::io::BorrowedHandle -//! [`BorrowedSocket<'a>`]: crate::os::windows::io::BorrowedSocket -//! [io-safety]: crate::io#io-safety - -#![stable(feature = "rust1", since = "1.0.0")] - -mod handle; -mod raw; -mod socket; - -#[stable(feature = "io_safety", since = "1.63.0")] -pub use handle::*; -#[stable(feature = "rust1", since = "1.0.0")] -pub use raw::*; -#[stable(feature = "io_safety", since = "1.63.0")] -pub use socket::*; - -#[cfg(test)] -mod tests; diff --git a/library/std/src/os/windows/io/raw.rs b/library/std/src/os/windows/io/raw.rs deleted file mode 100644 index 770583a9ce3e0..0000000000000 --- a/library/std/src/os/windows/io/raw.rs +++ /dev/null @@ -1,306 +0,0 @@ -//! Windows-specific extensions to general I/O primitives. - -#![stable(feature = "rust1", since = "1.0.0")] - -use crate::fs; -use crate::io; -use crate::net; -#[cfg(doc)] -use crate::os::windows::io::{AsHandle, AsSocket}; -use crate::os::windows::io::{OwnedHandle, OwnedSocket}; -use crate::os::windows::raw; -use crate::ptr; -use crate::sys; -use crate::sys_common::{self, AsInner, FromInner, IntoInner}; - -/// Raw HANDLEs. -#[stable(feature = "rust1", since = "1.0.0")] -pub type RawHandle = raw::HANDLE; - -/// Raw SOCKETs. -#[stable(feature = "rust1", since = "1.0.0")] -pub type RawSocket = raw::SOCKET; - -/// Extracts raw handles. -#[stable(feature = "rust1", since = "1.0.0")] -pub trait AsRawHandle { - /// Extracts the raw handle. - /// - /// This function is typically used to **borrow** an owned handle. - /// When used in this way, this method does **not** pass ownership of the - /// raw handle to the caller, and the handle is only guaranteed - /// to be valid while the original object has not yet been destroyed. - /// - /// This function may return null, such as when called on [`Stdin`], - /// [`Stdout`], or [`Stderr`] when the console is detached. - /// - /// However, borrowing is not strictly required. See [`AsHandle::as_handle`] - /// for an API which strictly borrows a handle. - /// - /// [`Stdin`]: io::Stdin - /// [`Stdout`]: io::Stdout - /// [`Stderr`]: io::Stderr - #[stable(feature = "rust1", since = "1.0.0")] - fn as_raw_handle(&self) -> RawHandle; -} - -/// Construct I/O objects from raw handles. -#[stable(feature = "from_raw_os", since = "1.1.0")] -pub trait FromRawHandle { - /// Constructs a new I/O object from the specified raw handle. - /// - /// This function is typically used to **consume ownership** of the handle - /// given, passing responsibility for closing the handle to the returned - /// object. When used in this way, the returned object - /// will take responsibility for closing it when the object goes out of - /// scope. - /// - /// However, consuming ownership is not strictly required. Use a - /// `From::from` implementation for an API which strictly - /// consumes ownership. - /// - /// # Safety - /// - /// The `handle` passed in must: - /// - be an [owned handle][io-safety]; in particular, it must be open. - /// - be a handle for a resource that may be freed via [`CloseHandle`] - /// (as opposed to `RegCloseKey` or other close functions). - /// - /// Note that the handle *may* have the value `INVALID_HANDLE_VALUE` (-1), - /// which is sometimes a valid handle value. See [here] for the full story. - /// - /// [`CloseHandle`]: https://docs.microsoft.com/en-us/windows/win32/api/handleapi/nf-handleapi-closehandle - /// [here]: https://devblogs.microsoft.com/oldnewthing/20040302-00/?p=40443 - /// [io-safety]: io#io-safety - #[stable(feature = "from_raw_os", since = "1.1.0")] - unsafe fn from_raw_handle(handle: RawHandle) -> Self; -} - -/// A trait to express the ability to consume an object and acquire ownership of -/// its raw `HANDLE`. -#[stable(feature = "into_raw_os", since = "1.4.0")] -pub trait IntoRawHandle { - /// Consumes this object, returning the raw underlying handle. - /// - /// This function is typically used to **transfer ownership** of the underlying - /// handle to the caller. When used in this way, callers are then the unique - /// owners of the handle and must close it once it's no longer needed. - /// - /// However, transferring ownership is not strictly required. Use a - /// `Into::into` implementation for an API which strictly - /// transfers ownership. - #[stable(feature = "into_raw_os", since = "1.4.0")] - fn into_raw_handle(self) -> RawHandle; -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRawHandle for fs::File { - #[inline] - fn as_raw_handle(&self) -> RawHandle { - self.as_inner().as_raw_handle() as RawHandle - } -} - -#[stable(feature = "asraw_stdio", since = "1.21.0")] -impl AsRawHandle for io::Stdin { - fn as_raw_handle(&self) -> RawHandle { - stdio_handle(unsafe { sys::c::GetStdHandle(sys::c::STD_INPUT_HANDLE) as RawHandle }) - } -} - -#[stable(feature = "asraw_stdio", since = "1.21.0")] -impl AsRawHandle for io::Stdout { - fn as_raw_handle(&self) -> RawHandle { - stdio_handle(unsafe { sys::c::GetStdHandle(sys::c::STD_OUTPUT_HANDLE) as RawHandle }) - } -} - -#[stable(feature = "asraw_stdio", since = "1.21.0")] -impl AsRawHandle for io::Stderr { - fn as_raw_handle(&self) -> RawHandle { - stdio_handle(unsafe { sys::c::GetStdHandle(sys::c::STD_ERROR_HANDLE) as RawHandle }) - } -} - -#[stable(feature = "asraw_stdio_locks", since = "1.35.0")] -impl<'a> AsRawHandle for io::StdinLock<'a> { - fn as_raw_handle(&self) -> RawHandle { - stdio_handle(unsafe { sys::c::GetStdHandle(sys::c::STD_INPUT_HANDLE) as RawHandle }) - } -} - -#[stable(feature = "asraw_stdio_locks", since = "1.35.0")] -impl<'a> AsRawHandle for io::StdoutLock<'a> { - fn as_raw_handle(&self) -> RawHandle { - stdio_handle(unsafe { sys::c::GetStdHandle(sys::c::STD_OUTPUT_HANDLE) as RawHandle }) - } -} - -#[stable(feature = "asraw_stdio_locks", since = "1.35.0")] -impl<'a> AsRawHandle for io::StderrLock<'a> { - fn as_raw_handle(&self) -> RawHandle { - stdio_handle(unsafe { sys::c::GetStdHandle(sys::c::STD_ERROR_HANDLE) as RawHandle }) - } -} - -// Translate a handle returned from `GetStdHandle` into a handle to return to -// the user. -fn stdio_handle(raw: RawHandle) -> RawHandle { - // `GetStdHandle` isn't expected to actually fail, so when it returns - // `INVALID_HANDLE_VALUE`, it means we were launched from a parent which - // didn't provide us with stdio handles, such as a parent with a detached - // console. In that case, return null to the user, which is consistent - // with what they'd get in the parent, and which avoids the problem that - // `INVALID_HANDLE_VALUE` aliases the current process handle. - if raw == sys::c::INVALID_HANDLE_VALUE { ptr::null_mut() } else { raw } -} - -#[stable(feature = "from_raw_os", since = "1.1.0")] -impl FromRawHandle for fs::File { - #[inline] - unsafe fn from_raw_handle(handle: RawHandle) -> fs::File { - let handle = handle as sys::c::HANDLE; - fs::File::from_inner(sys::fs::File::from_inner(FromInner::from_inner( - OwnedHandle::from_raw_handle(handle), - ))) - } -} - -#[stable(feature = "into_raw_os", since = "1.4.0")] -impl IntoRawHandle for fs::File { - #[inline] - fn into_raw_handle(self) -> RawHandle { - self.into_inner().into_raw_handle() as *mut _ - } -} - -/// Extracts raw sockets. -#[stable(feature = "rust1", since = "1.0.0")] -pub trait AsRawSocket { - /// Extracts the raw socket. - /// - /// This function is typically used to **borrow** an owned socket. - /// When used in this way, this method does **not** pass ownership of the - /// raw socket to the caller, and the socket is only guaranteed - /// to be valid while the original object has not yet been destroyed. - /// - /// However, borrowing is not strictly required. See [`AsSocket::as_socket`] - /// for an API which strictly borrows a socket. - #[stable(feature = "rust1", since = "1.0.0")] - fn as_raw_socket(&self) -> RawSocket; -} - -/// Creates I/O objects from raw sockets. -#[stable(feature = "from_raw_os", since = "1.1.0")] -pub trait FromRawSocket { - /// Constructs a new I/O object from the specified raw socket. - /// - /// This function is typically used to **consume ownership** of the socket - /// given, passing responsibility for closing the socket to the returned - /// object. When used in this way, the returned object - /// will take responsibility for closing it when the object goes out of - /// scope. - /// - /// However, consuming ownership is not strictly required. Use a - /// `From::from` implementation for an API which strictly - /// consumes ownership. - /// - /// # Safety - /// - /// The `socket` passed in must: - /// - be an [owned socket][io-safety]; in particular, it must be open. - /// - be a socket that may be freed via [`closesocket`]. - /// - /// [`closesocket`]: https://docs.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-closesocket - /// [io-safety]: io#io-safety - #[stable(feature = "from_raw_os", since = "1.1.0")] - unsafe fn from_raw_socket(sock: RawSocket) -> Self; -} - -/// A trait to express the ability to consume an object and acquire ownership of -/// its raw `SOCKET`. -#[stable(feature = "into_raw_os", since = "1.4.0")] -pub trait IntoRawSocket { - /// Consumes this object, returning the raw underlying socket. - /// - /// This function is typically used to **transfer ownership** of the underlying - /// socket to the caller. When used in this way, callers are then the unique - /// owners of the socket and must close it once it's no longer needed. - /// - /// However, transferring ownership is not strictly required. Use a - /// `Into::into` implementation for an API which strictly - /// transfers ownership. - #[stable(feature = "into_raw_os", since = "1.4.0")] - fn into_raw_socket(self) -> RawSocket; -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRawSocket for net::TcpStream { - #[inline] - fn as_raw_socket(&self) -> RawSocket { - self.as_inner().socket().as_raw_socket() - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRawSocket for net::TcpListener { - #[inline] - fn as_raw_socket(&self) -> RawSocket { - self.as_inner().socket().as_raw_socket() - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRawSocket for net::UdpSocket { - #[inline] - fn as_raw_socket(&self) -> RawSocket { - self.as_inner().socket().as_raw_socket() - } -} - -#[stable(feature = "from_raw_os", since = "1.1.0")] -impl FromRawSocket for net::TcpStream { - #[inline] - unsafe fn from_raw_socket(sock: RawSocket) -> net::TcpStream { - let sock = sys::net::Socket::from_inner(OwnedSocket::from_raw_socket(sock)); - net::TcpStream::from_inner(sys_common::net::TcpStream::from_inner(sock)) - } -} -#[stable(feature = "from_raw_os", since = "1.1.0")] -impl FromRawSocket for net::TcpListener { - #[inline] - unsafe fn from_raw_socket(sock: RawSocket) -> net::TcpListener { - let sock = sys::net::Socket::from_inner(OwnedSocket::from_raw_socket(sock)); - net::TcpListener::from_inner(sys_common::net::TcpListener::from_inner(sock)) - } -} -#[stable(feature = "from_raw_os", since = "1.1.0")] -impl FromRawSocket for net::UdpSocket { - #[inline] - unsafe fn from_raw_socket(sock: RawSocket) -> net::UdpSocket { - let sock = sys::net::Socket::from_inner(OwnedSocket::from_raw_socket(sock)); - net::UdpSocket::from_inner(sys_common::net::UdpSocket::from_inner(sock)) - } -} - -#[stable(feature = "into_raw_os", since = "1.4.0")] -impl IntoRawSocket for net::TcpStream { - #[inline] - fn into_raw_socket(self) -> RawSocket { - self.into_inner().into_socket().into_inner().into_raw_socket() - } -} - -#[stable(feature = "into_raw_os", since = "1.4.0")] -impl IntoRawSocket for net::TcpListener { - #[inline] - fn into_raw_socket(self) -> RawSocket { - self.into_inner().into_socket().into_inner().into_raw_socket() - } -} - -#[stable(feature = "into_raw_os", since = "1.4.0")] -impl IntoRawSocket for net::UdpSocket { - #[inline] - fn into_raw_socket(self) -> RawSocket { - self.into_inner().into_socket().into_inner().into_raw_socket() - } -} diff --git a/library/std/src/os/windows/io/socket.rs b/library/std/src/os/windows/io/socket.rs deleted file mode 100644 index 6ffdf907c8ed3..0000000000000 --- a/library/std/src/os/windows/io/socket.rs +++ /dev/null @@ -1,385 +0,0 @@ -//! Owned and borrowed OS sockets. - -#![stable(feature = "io_safety", since = "1.63.0")] - -use super::raw::{AsRawSocket, FromRawSocket, IntoRawSocket, RawSocket}; -use crate::fmt; -use crate::io; -use crate::marker::PhantomData; -use crate::mem; -use crate::mem::forget; -use crate::sys; -#[cfg(not(target_vendor = "uwp"))] -use crate::sys::cvt; - -/// A borrowed socket. -/// -/// This has a lifetime parameter to tie it to the lifetime of something that -/// owns the socket. -/// -/// This uses `repr(transparent)` and has the representation of a host socket, -/// so it can be used in FFI in places where a socket is passed as an argument, -/// it is not captured or consumed, and it never has the value -/// `INVALID_SOCKET`. -/// -/// This type's `.to_owned()` implementation returns another `BorrowedSocket` -/// rather than an `OwnedSocket`. It just makes a trivial copy of the raw -/// socket, which is then borrowed under the same lifetime. -#[derive(Copy, Clone)] -#[repr(transparent)] -#[rustc_layout_scalar_valid_range_start(0)] -// This is -2, in two's complement. -1 is `INVALID_SOCKET`. -#[cfg_attr(target_pointer_width = "32", rustc_layout_scalar_valid_range_end(0xFF_FF_FF_FE))] -#[cfg_attr( - target_pointer_width = "64", - rustc_layout_scalar_valid_range_end(0xFF_FF_FF_FF_FF_FF_FF_FE) -)] -#[rustc_nonnull_optimization_guaranteed] -#[stable(feature = "io_safety", since = "1.63.0")] -pub struct BorrowedSocket<'socket> { - socket: RawSocket, - _phantom: PhantomData<&'socket OwnedSocket>, -} - -/// An owned socket. -/// -/// This closes the socket on drop. -/// -/// This uses `repr(transparent)` and has the representation of a host socket, -/// so it can be used in FFI in places where a socket is passed as a consumed -/// argument or returned as an owned value, and it never has the value -/// `INVALID_SOCKET`. -#[repr(transparent)] -#[rustc_layout_scalar_valid_range_start(0)] -// This is -2, in two's complement. -1 is `INVALID_SOCKET`. -#[cfg_attr(target_pointer_width = "32", rustc_layout_scalar_valid_range_end(0xFF_FF_FF_FE))] -#[cfg_attr( - target_pointer_width = "64", - rustc_layout_scalar_valid_range_end(0xFF_FF_FF_FF_FF_FF_FF_FE) -)] -#[rustc_nonnull_optimization_guaranteed] -#[stable(feature = "io_safety", since = "1.63.0")] -pub struct OwnedSocket { - socket: RawSocket, -} - -impl BorrowedSocket<'_> { - /// Return a `BorrowedSocket` holding the given raw socket. - /// - /// # Safety - /// - /// The resource pointed to by `raw` must remain open for the duration of - /// the returned `BorrowedSocket`, and it must not have the value - /// `INVALID_SOCKET`. - #[inline] - #[rustc_const_stable(feature = "io_safety", since = "1.63.0")] - #[stable(feature = "io_safety", since = "1.63.0")] - pub const unsafe fn borrow_raw(socket: RawSocket) -> Self { - assert!(socket != sys::c::INVALID_SOCKET as RawSocket); - Self { socket, _phantom: PhantomData } - } -} - -impl OwnedSocket { - /// Creates a new `OwnedSocket` instance that shares the same underlying - /// object as the existing `OwnedSocket` instance. - #[stable(feature = "io_safety", since = "1.63.0")] - pub fn try_clone(&self) -> io::Result { - self.as_socket().try_clone_to_owned() - } - - // FIXME(strict_provenance_magic): we defined RawSocket to be a u64 ;-; - #[allow(fuzzy_provenance_casts)] - #[cfg(not(target_vendor = "uwp"))] - pub(crate) fn set_no_inherit(&self) -> io::Result<()> { - cvt(unsafe { - sys::c::SetHandleInformation( - self.as_raw_socket() as sys::c::HANDLE, - sys::c::HANDLE_FLAG_INHERIT, - 0, - ) - }) - .map(drop) - } - - #[cfg(target_vendor = "uwp")] - pub(crate) fn set_no_inherit(&self) -> io::Result<()> { - Err(io::const_io_error!(io::ErrorKind::Unsupported, "Unavailable on UWP")) - } -} - -impl BorrowedSocket<'_> { - /// Creates a new `OwnedSocket` instance that shares the same underlying - /// object as the existing `BorrowedSocket` instance. - #[stable(feature = "io_safety", since = "1.63.0")] - pub fn try_clone_to_owned(&self) -> io::Result { - let mut info = unsafe { mem::zeroed::() }; - let result = unsafe { - sys::c::WSADuplicateSocketW( - self.as_raw_socket() as sys::c::SOCKET, - sys::c::GetCurrentProcessId(), - &mut info, - ) - }; - sys::net::cvt(result)?; - let socket = unsafe { - sys::c::WSASocketW( - info.iAddressFamily, - info.iSocketType, - info.iProtocol, - &info, - 0, - sys::c::WSA_FLAG_OVERLAPPED | sys::c::WSA_FLAG_NO_HANDLE_INHERIT, - ) - }; - - if socket != sys::c::INVALID_SOCKET { - unsafe { Ok(OwnedSocket::from_raw_socket(socket as RawSocket)) } - } else { - let error = unsafe { sys::c::WSAGetLastError() }; - - if error != sys::c::WSAEPROTOTYPE && error != sys::c::WSAEINVAL { - return Err(io::Error::from_raw_os_error(error)); - } - - let socket = unsafe { - sys::c::WSASocketW( - info.iAddressFamily, - info.iSocketType, - info.iProtocol, - &info, - 0, - sys::c::WSA_FLAG_OVERLAPPED, - ) - }; - - if socket == sys::c::INVALID_SOCKET { - return Err(last_error()); - } - - unsafe { - let socket = OwnedSocket::from_raw_socket(socket as RawSocket); - socket.set_no_inherit()?; - Ok(socket) - } - } - } -} - -/// Returns the last error from the Windows socket interface. -fn last_error() -> io::Error { - io::Error::from_raw_os_error(unsafe { sys::c::WSAGetLastError() }) -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsRawSocket for BorrowedSocket<'_> { - #[inline] - fn as_raw_socket(&self) -> RawSocket { - self.socket - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsRawSocket for OwnedSocket { - #[inline] - fn as_raw_socket(&self) -> RawSocket { - self.socket - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl IntoRawSocket for OwnedSocket { - #[inline] - fn into_raw_socket(self) -> RawSocket { - let socket = self.socket; - forget(self); - socket - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl FromRawSocket for OwnedSocket { - #[inline] - unsafe fn from_raw_socket(socket: RawSocket) -> Self { - debug_assert_ne!(socket, sys::c::INVALID_SOCKET as RawSocket); - Self { socket } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl Drop for OwnedSocket { - #[inline] - fn drop(&mut self) { - unsafe { - let _ = sys::c::closesocket(self.socket as sys::c::SOCKET); - } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl fmt::Debug for BorrowedSocket<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("BorrowedSocket").field("socket", &self.socket).finish() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl fmt::Debug for OwnedSocket { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("OwnedSocket").field("socket", &self.socket).finish() - } -} - -/// A trait to borrow the socket from an underlying object. -#[stable(feature = "io_safety", since = "1.63.0")] -pub trait AsSocket { - /// Borrows the socket. - #[stable(feature = "io_safety", since = "1.63.0")] - fn as_socket(&self) -> BorrowedSocket<'_>; -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsSocket for &T { - #[inline] - fn as_socket(&self) -> BorrowedSocket<'_> { - T::as_socket(self) - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsSocket for &mut T { - #[inline] - fn as_socket(&self) -> BorrowedSocket<'_> { - T::as_socket(self) - } -} - -#[stable(feature = "as_windows_ptrs", since = "1.71.0")] -/// This impl allows implementing traits that require `AsSocket` on Arc. -/// ``` -/// # #[cfg(windows)] mod group_cfg { -/// # use std::os::windows::io::AsSocket; -/// use std::net::UdpSocket; -/// use std::sync::Arc; -/// -/// trait MyTrait: AsSocket {} -/// impl MyTrait for Arc {} -/// impl MyTrait for Box {} -/// # } -/// ``` -impl AsSocket for crate::sync::Arc { - #[inline] - fn as_socket(&self) -> BorrowedSocket<'_> { - (**self).as_socket() - } -} - -#[stable(feature = "as_windows_ptrs", since = "1.71.0")] -impl AsSocket for crate::rc::Rc { - #[inline] - fn as_socket(&self) -> BorrowedSocket<'_> { - (**self).as_socket() - } -} - -#[stable(feature = "as_windows_ptrs", since = "1.71.0")] -impl AsSocket for Box { - #[inline] - fn as_socket(&self) -> BorrowedSocket<'_> { - (**self).as_socket() - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsSocket for BorrowedSocket<'_> { - #[inline] - fn as_socket(&self) -> BorrowedSocket<'_> { - *self - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsSocket for OwnedSocket { - #[inline] - fn as_socket(&self) -> BorrowedSocket<'_> { - // Safety: `OwnedSocket` and `BorrowedSocket` have the same validity - // invariants, and the `BorrowedSocket` is bounded by the lifetime - // of `&self`. - unsafe { BorrowedSocket::borrow_raw(self.as_raw_socket()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsSocket for crate::net::TcpStream { - #[inline] - fn as_socket(&self) -> BorrowedSocket<'_> { - unsafe { BorrowedSocket::borrow_raw(self.as_raw_socket()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for OwnedSocket { - /// Takes ownership of a [`TcpStream`](crate::net::TcpStream)'s socket. - #[inline] - fn from(tcp_stream: crate::net::TcpStream) -> OwnedSocket { - unsafe { OwnedSocket::from_raw_socket(tcp_stream.into_raw_socket()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for crate::net::TcpStream { - #[inline] - fn from(owned: OwnedSocket) -> Self { - unsafe { Self::from_raw_socket(owned.into_raw_socket()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsSocket for crate::net::TcpListener { - #[inline] - fn as_socket(&self) -> BorrowedSocket<'_> { - unsafe { BorrowedSocket::borrow_raw(self.as_raw_socket()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for OwnedSocket { - /// Takes ownership of a [`TcpListener`](crate::net::TcpListener)'s socket. - #[inline] - fn from(tcp_listener: crate::net::TcpListener) -> OwnedSocket { - unsafe { OwnedSocket::from_raw_socket(tcp_listener.into_raw_socket()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for crate::net::TcpListener { - #[inline] - fn from(owned: OwnedSocket) -> Self { - unsafe { Self::from_raw_socket(owned.into_raw_socket()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsSocket for crate::net::UdpSocket { - #[inline] - fn as_socket(&self) -> BorrowedSocket<'_> { - unsafe { BorrowedSocket::borrow_raw(self.as_raw_socket()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for OwnedSocket { - /// Takes ownership of a [`UdpSocket`](crate::net::UdpSocket)'s underlying socket. - #[inline] - fn from(udp_socket: crate::net::UdpSocket) -> OwnedSocket { - unsafe { OwnedSocket::from_raw_socket(udp_socket.into_raw_socket()) } - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for crate::net::UdpSocket { - #[inline] - fn from(owned: OwnedSocket) -> Self { - unsafe { Self::from_raw_socket(owned.into_raw_socket()) } - } -} diff --git a/library/std/src/os/windows/io/tests.rs b/library/std/src/os/windows/io/tests.rs deleted file mode 100644 index 41734e52e8cce..0000000000000 --- a/library/std/src/os/windows/io/tests.rs +++ /dev/null @@ -1,21 +0,0 @@ -#[test] -fn test_niche_optimizations_socket() { - use crate::mem::size_of; - use crate::os::windows::io::{ - BorrowedSocket, FromRawSocket, IntoRawSocket, OwnedSocket, RawSocket, - }; - - assert_eq!(size_of::>(), size_of::()); - assert_eq!(size_of::>>(), size_of::(),); - unsafe { - #[cfg(target_pointer_width = "32")] - let (min, max) = (i32::MIN as u32, i32::MAX as u32); - #[cfg(target_pointer_width = "64")] - let (min, max) = (i64::MIN as u64, i64::MAX as u64); - - assert_eq!(OwnedSocket::from_raw_socket(min).into_raw_socket(), min); - assert_eq!(OwnedSocket::from_raw_socket(max).into_raw_socket(), max); - assert_eq!(Some(OwnedSocket::from_raw_socket(min)).unwrap().into_raw_socket(), min); - assert_eq!(Some(OwnedSocket::from_raw_socket(max)).unwrap().into_raw_socket(), max); - } -} diff --git a/library/std/src/os/windows/mod.rs b/library/std/src/os/windows/mod.rs deleted file mode 100644 index 52eb3b7c06769..0000000000000 --- a/library/std/src/os/windows/mod.rs +++ /dev/null @@ -1,58 +0,0 @@ -//! Platform-specific extensions to `std` for Windows. -//! -//! Provides access to platform-level information for Windows, and exposes -//! Windows-specific idioms that would otherwise be inappropriate as part -//! the core `std` library. These extensions allow developers to use -//! `std` types and idioms with Windows in a way that the normal -//! platform-agnostic idioms would not normally support. -//! -//! # Examples -//! -//! ```no_run -//! use std::fs::File; -//! use std::os::windows::prelude::*; -//! -//! fn main() -> std::io::Result<()> { -//! let f = File::create("foo.txt")?; -//! let handle = f.as_raw_handle(); -//! -//! // use handle with native windows bindings -//! -//! Ok(()) -//! } -//! ``` - -#![stable(feature = "rust1", since = "1.0.0")] -#![doc(cfg(windows))] - -pub mod ffi; -pub mod fs; -pub mod io; -pub mod process; -pub mod raw; -pub mod thread; - -/// A prelude for conveniently writing platform-specific code. -/// -/// Includes all extension traits, and some important type definitions. -#[stable(feature = "rust1", since = "1.0.0")] -pub mod prelude { - #[doc(no_inline)] - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::ffi::{OsStrExt, OsStringExt}; - #[doc(no_inline)] - #[stable(feature = "file_offset", since = "1.15.0")] - pub use super::fs::FileExt; - #[doc(no_inline)] - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::fs::{MetadataExt, OpenOptionsExt}; - #[doc(no_inline)] - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::io::{ - AsHandle, AsSocket, BorrowedHandle, BorrowedSocket, FromRawHandle, FromRawSocket, - HandleOrInvalid, IntoRawHandle, IntoRawSocket, OwnedHandle, OwnedSocket, - }; - #[doc(no_inline)] - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::io::{AsRawHandle, AsRawSocket, RawHandle, RawSocket}; -} diff --git a/library/std/src/os/windows/process.rs b/library/std/src/os/windows/process.rs deleted file mode 100644 index 9cca27fa5dd5b..0000000000000 --- a/library/std/src/os/windows/process.rs +++ /dev/null @@ -1,437 +0,0 @@ -//! Windows-specific extensions to primitives in the [`std::process`] module. -//! -//! [`std::process`]: crate::process - -#![stable(feature = "process_extensions", since = "1.2.0")] - -use crate::ffi::OsStr; -use crate::os::windows::io::{ - AsHandle, AsRawHandle, BorrowedHandle, FromRawHandle, IntoRawHandle, OwnedHandle, RawHandle, -}; -use crate::process; -use crate::sealed::Sealed; -use crate::sys; -use crate::sys_common::{AsInner, AsInnerMut, FromInner, IntoInner}; - -#[stable(feature = "process_extensions", since = "1.2.0")] -impl FromRawHandle for process::Stdio { - unsafe fn from_raw_handle(handle: RawHandle) -> process::Stdio { - let handle = sys::handle::Handle::from_raw_handle(handle as *mut _); - let io = sys::process::Stdio::Handle(handle); - process::Stdio::from_inner(io) - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for process::Stdio { - /// Takes ownership of a handle and returns a [`Stdio`](process::Stdio) - /// that can attach a stream to it. - fn from(handle: OwnedHandle) -> process::Stdio { - let handle = sys::handle::Handle::from_inner(handle); - let io = sys::process::Stdio::Handle(handle); - process::Stdio::from_inner(io) - } -} - -#[stable(feature = "process_extensions", since = "1.2.0")] -impl AsRawHandle for process::Child { - #[inline] - fn as_raw_handle(&self) -> RawHandle { - self.as_inner().handle().as_raw_handle() as *mut _ - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl AsHandle for process::Child { - #[inline] - fn as_handle(&self) -> BorrowedHandle<'_> { - self.as_inner().handle().as_handle() - } -} - -#[stable(feature = "into_raw_os", since = "1.4.0")] -impl IntoRawHandle for process::Child { - fn into_raw_handle(self) -> RawHandle { - self.into_inner().into_handle().into_raw_handle() as *mut _ - } -} - -#[stable(feature = "io_safety", since = "1.63.0")] -impl From for OwnedHandle { - /// Takes ownership of a [`Child`](process::Child)'s process handle. - fn from(child: process::Child) -> OwnedHandle { - child.into_inner().into_handle().into_inner() - } -} - -#[stable(feature = "process_extensions", since = "1.2.0")] -impl AsRawHandle for process::ChildStdin { - #[inline] - fn as_raw_handle(&self) -> RawHandle { - self.as_inner().handle().as_raw_handle() as *mut _ - } -} - -#[stable(feature = "process_extensions", since = "1.2.0")] -impl AsRawHandle for process::ChildStdout { - #[inline] - fn as_raw_handle(&self) -> RawHandle { - self.as_inner().handle().as_raw_handle() as *mut _ - } -} - -#[stable(feature = "process_extensions", since = "1.2.0")] -impl AsRawHandle for process::ChildStderr { - #[inline] - fn as_raw_handle(&self) -> RawHandle { - self.as_inner().handle().as_raw_handle() as *mut _ - } -} - -#[stable(feature = "into_raw_os", since = "1.4.0")] -impl IntoRawHandle for process::ChildStdin { - fn into_raw_handle(self) -> RawHandle { - self.into_inner().into_handle().into_raw_handle() as *mut _ - } -} - -#[stable(feature = "into_raw_os", since = "1.4.0")] -impl IntoRawHandle for process::ChildStdout { - fn into_raw_handle(self) -> RawHandle { - self.into_inner().into_handle().into_raw_handle() as *mut _ - } -} - -#[stable(feature = "into_raw_os", since = "1.4.0")] -impl IntoRawHandle for process::ChildStderr { - fn into_raw_handle(self) -> RawHandle { - self.into_inner().into_handle().into_raw_handle() as *mut _ - } -} - -/// Create a `ChildStdin` from the provided `OwnedHandle`. -/// -/// The provided handle must be asynchronous, as reading and -/// writing from and to it is implemented using asynchronous APIs. -#[stable(feature = "child_stream_from_fd", since = "1.74.0")] -impl From for process::ChildStdin { - fn from(handle: OwnedHandle) -> process::ChildStdin { - let handle = sys::handle::Handle::from_inner(handle); - let pipe = sys::pipe::AnonPipe::from_inner(handle); - process::ChildStdin::from_inner(pipe) - } -} - -/// Create a `ChildStdout` from the provided `OwnedHandle`. -/// -/// The provided handle must be asynchronous, as reading and -/// writing from and to it is implemented using asynchronous APIs. -#[stable(feature = "child_stream_from_fd", since = "1.74.0")] -impl From for process::ChildStdout { - fn from(handle: OwnedHandle) -> process::ChildStdout { - let handle = sys::handle::Handle::from_inner(handle); - let pipe = sys::pipe::AnonPipe::from_inner(handle); - process::ChildStdout::from_inner(pipe) - } -} - -/// Create a `ChildStderr` from the provided `OwnedHandle`. -/// -/// The provided handle must be asynchronous, as reading and -/// writing from and to it is implemented using asynchronous APIs. -#[stable(feature = "child_stream_from_fd", since = "1.74.0")] -impl From for process::ChildStderr { - fn from(handle: OwnedHandle) -> process::ChildStderr { - let handle = sys::handle::Handle::from_inner(handle); - let pipe = sys::pipe::AnonPipe::from_inner(handle); - process::ChildStderr::from_inner(pipe) - } -} - -/// Windows-specific extensions to [`process::ExitStatus`]. -/// -/// This trait is sealed: it cannot be implemented outside the standard library. -/// This is so that future additional methods are not breaking changes. -#[stable(feature = "exit_status_from", since = "1.12.0")] -pub trait ExitStatusExt: Sealed { - /// Creates a new `ExitStatus` from the raw underlying `u32` return value of - /// a process. - #[stable(feature = "exit_status_from", since = "1.12.0")] - fn from_raw(raw: u32) -> Self; -} - -#[stable(feature = "exit_status_from", since = "1.12.0")] -impl ExitStatusExt for process::ExitStatus { - fn from_raw(raw: u32) -> Self { - process::ExitStatus::from_inner(From::from(raw)) - } -} - -/// Windows-specific extensions to the [`process::Command`] builder. -/// -/// This trait is sealed: it cannot be implemented outside the standard library. -/// This is so that future additional methods are not breaking changes. -#[stable(feature = "windows_process_extensions", since = "1.16.0")] -pub trait CommandExt: Sealed { - /// Sets the [process creation flags][1] to be passed to `CreateProcess`. - /// - /// These will always be ORed with `CREATE_UNICODE_ENVIRONMENT`. - /// - /// [1]: https://docs.microsoft.com/en-us/windows/win32/procthread/process-creation-flags - #[stable(feature = "windows_process_extensions", since = "1.16.0")] - fn creation_flags(&mut self, flags: u32) -> &mut process::Command; - - /// Forces all arguments to be wrapped in quote (`"`) characters. - /// - /// This is useful for passing arguments to [MSYS2/Cygwin][1] based - /// executables: these programs will expand unquoted arguments containing - /// wildcard characters (`?` and `*`) by searching for any file paths - /// matching the wildcard pattern. - /// - /// Adding quotes has no effect when passing arguments to programs - /// that use [msvcrt][2]. This includes programs built with both - /// MinGW and MSVC. - /// - /// [1]: - /// [2]: - #[unstable(feature = "windows_process_extensions_force_quotes", issue = "82227")] - fn force_quotes(&mut self, enabled: bool) -> &mut process::Command; - - /// Append literal text to the command line without any quoting or escaping. - /// - /// This is useful for passing arguments to applications that don't follow - /// the standard C run-time escaping rules, such as `cmd.exe /c`. - /// - /// # Batch files - /// - /// Note the `cmd /c` command line has slightly different escaping rules than batch files - /// themselves. If possible, it may be better to write complex arguments to a temporary - /// `.bat` file, with appropriate escaping, and simply run that using: - /// - /// ```no_run - /// # use std::process::Command; - /// # let temp_bat_file = ""; - /// # #[allow(unused)] - /// let output = Command::new("cmd").args(["/c", &format!("\"{temp_bat_file}\"")]).output(); - /// ``` - /// - /// # Example - /// - /// Run a batch script using both trusted and untrusted arguments. - /// - /// ```no_run - /// #[cfg(windows)] - /// // `my_script_path` is a path to known bat file. - /// // `user_name` is an untrusted name given by the user. - /// fn run_script( - /// my_script_path: &str, - /// user_name: &str, - /// ) -> Result { - /// use std::io::{Error, ErrorKind}; - /// use std::os::windows::process::CommandExt; - /// use std::process::Command; - /// - /// // Create the command line, making sure to quote the script path. - /// // This assumes the fixed arguments have been tested to work with the script we're using. - /// let mut cmd_args = format!(r#""{my_script_path}" "--features=[a,b,c]""#); - /// - /// // Make sure the user name is safe. In particular we need to be - /// // cautious of ascii symbols that cmd may interpret specially. - /// // Here we only allow alphanumeric characters. - /// if !user_name.chars().all(|c| c.is_alphanumeric()) { - /// return Err(Error::new(ErrorKind::InvalidInput, "invalid user name")); - /// } - /// - /// // now we have validated the user name, let's add that too. - /// cmd_args.push_str(" --user "); - /// cmd_args.push_str(user_name); - /// - /// // call cmd.exe and return the output - /// Command::new("cmd.exe") - /// .arg("/c") - /// // surround the entire command in an extra pair of quotes, as required by cmd.exe. - /// .raw_arg(&format!("\"{cmd_args}\"")) - /// .output() - /// } - /// ```` - #[stable(feature = "windows_process_extensions_raw_arg", since = "1.62.0")] - fn raw_arg>(&mut self, text_to_append_as_is: S) -> &mut process::Command; - - /// When [`process::Command`] creates pipes, request that our side is always async. - /// - /// By default [`process::Command`] may choose to use pipes where both ends - /// are opened for synchronous read or write operations. By using - /// `async_pipes(true)`, this behavior is overridden so that our side is - /// always async. - /// - /// This is important because if doing async I/O a pipe or a file has to be - /// opened for async access. - /// - /// The end of the pipe sent to the child process will always be synchronous - /// regardless of this option. - /// - /// # Example - /// - /// ``` - /// #![feature(windows_process_extensions_async_pipes)] - /// use std::os::windows::process::CommandExt; - /// use std::process::{Command, Stdio}; - /// - /// # let program = ""; - /// - /// Command::new(program) - /// .async_pipes(true) - /// .stdin(Stdio::piped()) - /// .stdout(Stdio::piped()) - /// .stderr(Stdio::piped()); - /// ``` - #[unstable(feature = "windows_process_extensions_async_pipes", issue = "98289")] - fn async_pipes(&mut self, always_async: bool) -> &mut process::Command; - - /// Set a raw attribute on the command, providing extended configuration options for Windows - /// processes. - /// - /// This method allows you to specify custom attributes for a child process on Windows systems - /// using raw attribute values. Raw attributes provide extended configurability for process - /// creation, but their usage can be complex and potentially unsafe. - /// - /// The `attribute` parameter specifies the raw attribute to be set, while the `value` - /// parameter holds the value associated with that attribute. Please refer to the - /// [`windows-rs` documentation] or the [Win32 API documentation] for detailed information - /// about available attributes and their meanings. - /// - /// [`windows-rs` documentation]: https://microsoft.github.io/windows-docs-rs/doc/windows/ - /// [Win32 API documentation]: https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-updateprocthreadattribute - /// - /// # Note - /// - /// The maximum number of raw attributes is the value of [`u32::MAX`]. - /// If this limit is exceeded, the call to [`process::Command::spawn`] will return an `Error` - /// indicating that the maximum number of attributes has been exceeded. - /// - /// # Safety - /// - /// The usage of raw attributes is potentially unsafe and should be done with caution. - /// Incorrect attribute values or improper configuration can lead to unexpected behavior or - /// errors. - /// - /// # Example - /// - /// The following example demonstrates how to create a child process with a specific parent - /// process ID using a raw attribute. - /// - /// ```rust - /// #![feature(windows_process_extensions_raw_attribute)] - /// use std::os::windows::{process::CommandExt, io::AsRawHandle}; - /// use std::process::Command; - /// - /// # struct ProcessDropGuard(std::process::Child); - /// # impl Drop for ProcessDropGuard { - /// # fn drop(&mut self) { - /// # let _ = self.0.kill(); - /// # } - /// # } - /// - /// let parent = Command::new("cmd").spawn()?; - /// - /// let mut child_cmd = Command::new("cmd"); - /// - /// const PROC_THREAD_ATTRIBUTE_PARENT_PROCESS: usize = 0x00020000; - /// - /// unsafe { - /// child_cmd.raw_attribute(PROC_THREAD_ATTRIBUTE_PARENT_PROCESS, parent.as_raw_handle() as isize); - /// } - /// # - /// # let parent = ProcessDropGuard(parent); - /// - /// let mut child = child_cmd.spawn()?; - /// - /// # child.kill()?; - /// # Ok::<(), std::io::Error>(()) - /// ``` - /// - /// # Safety Note - /// - /// Remember that improper use of raw attributes can lead to undefined behavior or security - /// vulnerabilities. Always consult the documentation and ensure proper attribute values are - /// used. - #[unstable(feature = "windows_process_extensions_raw_attribute", issue = "114854")] - unsafe fn raw_attribute( - &mut self, - attribute: usize, - value: T, - ) -> &mut process::Command; -} - -#[stable(feature = "windows_process_extensions", since = "1.16.0")] -impl CommandExt for process::Command { - fn creation_flags(&mut self, flags: u32) -> &mut process::Command { - self.as_inner_mut().creation_flags(flags); - self - } - - fn force_quotes(&mut self, enabled: bool) -> &mut process::Command { - self.as_inner_mut().force_quotes(enabled); - self - } - - fn raw_arg>(&mut self, raw_text: S) -> &mut process::Command { - self.as_inner_mut().raw_arg(raw_text.as_ref()); - self - } - - fn async_pipes(&mut self, always_async: bool) -> &mut process::Command { - // FIXME: This currently has an intentional no-op implementation. - // For the time being our side of the pipes will always be async. - // Once the ecosystem has adjusted, we may then be able to start making - // use of synchronous pipes within the standard library. - let _ = always_async; - self - } - - unsafe fn raw_attribute( - &mut self, - attribute: usize, - value: T, - ) -> &mut process::Command { - self.as_inner_mut().raw_attribute(attribute, value); - self - } -} - -#[unstable(feature = "windows_process_extensions_main_thread_handle", issue = "96723")] -pub trait ChildExt: Sealed { - /// Extracts the main thread raw handle, without taking ownership - #[unstable(feature = "windows_process_extensions_main_thread_handle", issue = "96723")] - fn main_thread_handle(&self) -> BorrowedHandle<'_>; -} - -#[unstable(feature = "windows_process_extensions_main_thread_handle", issue = "96723")] -impl ChildExt for process::Child { - fn main_thread_handle(&self) -> BorrowedHandle<'_> { - self.handle.main_thread_handle() - } -} - -/// Windows-specific extensions to [`process::ExitCode`]. -/// -/// This trait is sealed: it cannot be implemented outside the standard library. -/// This is so that future additional methods are not breaking changes. -#[unstable(feature = "windows_process_exit_code_from", issue = "111688")] -pub trait ExitCodeExt: Sealed { - /// Creates a new `ExitCode` from the raw underlying `u32` return value of - /// a process. - /// - /// The exit code should not be 259, as this conflicts with the `STILL_ACTIVE` - /// macro returned from the `GetExitCodeProcess` function to signal that the - /// process has yet to run to completion. - #[unstable(feature = "windows_process_exit_code_from", issue = "111688")] - fn from_raw(raw: u32) -> Self; -} - -#[unstable(feature = "windows_process_exit_code_from", issue = "111688")] -impl ExitCodeExt for process::ExitCode { - fn from_raw(raw: u32) -> Self { - process::ExitCode::from_inner(From::from(raw)) - } -} diff --git a/library/std/src/os/windows/raw.rs b/library/std/src/os/windows/raw.rs deleted file mode 100644 index 0ef3adade5c83..0000000000000 --- a/library/std/src/os/windows/raw.rs +++ /dev/null @@ -1,16 +0,0 @@ -//! Windows-specific primitives. - -#![stable(feature = "raw_ext", since = "1.1.0")] - -use crate::os::raw::c_void; - -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type HANDLE = *mut c_void; -#[cfg(target_pointer_width = "32")] -#[doc(cfg(all()))] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type SOCKET = u32; -#[cfg(target_pointer_width = "64")] -#[doc(cfg(all()))] -#[stable(feature = "raw_ext", since = "1.1.0")] -pub type SOCKET = u64; diff --git a/library/std/src/os/windows/thread.rs b/library/std/src/os/windows/thread.rs deleted file mode 100644 index d81d6d0ac28a9..0000000000000 --- a/library/std/src/os/windows/thread.rs +++ /dev/null @@ -1,25 +0,0 @@ -//! Windows-specific extensions to primitives in the [`std::thread`] module. -//! -//! [`std::thread`]: crate::thread - -#![stable(feature = "thread_extensions", since = "1.9.0")] - -use crate::os::windows::io::{AsRawHandle, IntoRawHandle, RawHandle}; -use crate::sys_common::{AsInner, IntoInner}; -use crate::thread; - -#[stable(feature = "thread_extensions", since = "1.9.0")] -impl AsRawHandle for thread::JoinHandle { - #[inline] - fn as_raw_handle(&self) -> RawHandle { - self.as_inner().handle().as_raw_handle() as *mut _ - } -} - -#[stable(feature = "thread_extensions", since = "1.9.0")] -impl IntoRawHandle for thread::JoinHandle { - #[inline] - fn into_raw_handle(self) -> RawHandle { - self.into_inner().into_handle().into_raw_handle() as *mut _ - } -} diff --git a/library/std/src/os/xous/ffi.rs b/library/std/src/os/xous/ffi.rs deleted file mode 100644 index e9a9f53372026..0000000000000 --- a/library/std/src/os/xous/ffi.rs +++ /dev/null @@ -1,649 +0,0 @@ -#![allow(dead_code)] -#![allow(unused_variables)] -#![stable(feature = "rust1", since = "1.0.0")] - -#[path = "../unix/ffi/os_str.rs"] -mod os_str; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::os_str::{OsStrExt, OsStringExt}; - -mod definitions; -#[stable(feature = "rust1", since = "1.0.0")] -pub use definitions::*; - -fn lend_mut_impl( - connection: Connection, - opcode: usize, - data: &mut [u8], - arg1: usize, - arg2: usize, - blocking: bool, -) -> Result<(usize, usize), Error> { - let mut a0 = if blocking { Syscall::SendMessage } else { Syscall::TrySendMessage } as usize; - let mut a1: usize = connection.try_into().unwrap(); - let mut a2 = InvokeType::LendMut as usize; - let a3 = opcode; - let a4 = data.as_mut_ptr() as usize; - let a5 = data.len(); - let a6 = arg1; - let a7 = arg2; - - unsafe { - core::arch::asm!( - "ecall", - inlateout("a0") a0, - inlateout("a1") a1, - inlateout("a2") a2, - inlateout("a3") a3 => _, - inlateout("a4") a4 => _, - inlateout("a5") a5 => _, - inlateout("a6") a6 => _, - inlateout("a7") a7 => _, - ) - }; - - let result = a0; - - if result == SyscallResult::MemoryReturned as usize { - Ok((a1, a2)) - } else if result == SyscallResult::Error as usize { - Err(a1.into()) - } else { - Err(Error::InternalError) - } -} - -pub(crate) fn lend_mut( - connection: Connection, - opcode: usize, - data: &mut [u8], - arg1: usize, - arg2: usize, -) -> Result<(usize, usize), Error> { - lend_mut_impl(connection, opcode, data, arg1, arg2, true) -} - -pub(crate) fn try_lend_mut( - connection: Connection, - opcode: usize, - data: &mut [u8], - arg1: usize, - arg2: usize, -) -> Result<(usize, usize), Error> { - lend_mut_impl(connection, opcode, data, arg1, arg2, false) -} - -fn lend_impl( - connection: Connection, - opcode: usize, - data: &[u8], - arg1: usize, - arg2: usize, - blocking: bool, -) -> Result<(usize, usize), Error> { - let mut a0 = if blocking { Syscall::SendMessage } else { Syscall::TrySendMessage } as usize; - let a1: usize = connection.try_into().unwrap(); - let a2 = InvokeType::Lend as usize; - let a3 = opcode; - let a4 = data.as_ptr() as usize; - let a5 = data.len(); - let a6 = arg1; - let a7 = arg2; - let mut ret1; - let mut ret2; - - unsafe { - core::arch::asm!( - "ecall", - inlateout("a0") a0, - inlateout("a1") a1 => ret1, - inlateout("a2") a2 => ret2, - inlateout("a3") a3 => _, - inlateout("a4") a4 => _, - inlateout("a5") a5 => _, - inlateout("a6") a6 => _, - inlateout("a7") a7 => _, - ) - }; - - let result = a0; - - if result == SyscallResult::MemoryReturned as usize { - Ok((ret1, ret2)) - } else if result == SyscallResult::Error as usize { - Err(ret1.into()) - } else { - Err(Error::InternalError) - } -} - -pub(crate) fn lend( - connection: Connection, - opcode: usize, - data: &[u8], - arg1: usize, - arg2: usize, -) -> Result<(usize, usize), Error> { - lend_impl(connection, opcode, data, arg1, arg2, true) -} - -pub(crate) fn try_lend( - connection: Connection, - opcode: usize, - data: &[u8], - arg1: usize, - arg2: usize, -) -> Result<(usize, usize), Error> { - lend_impl(connection, opcode, data, arg1, arg2, false) -} - -fn scalar_impl(connection: Connection, args: [usize; 5], blocking: bool) -> Result<(), Error> { - let mut a0 = if blocking { Syscall::SendMessage } else { Syscall::TrySendMessage } as usize; - let mut a1: usize = connection.try_into().unwrap(); - let a2 = InvokeType::Scalar as usize; - let a3 = args[0]; - let a4 = args[1]; - let a5 = args[2]; - let a6 = args[3]; - let a7 = args[4]; - - unsafe { - core::arch::asm!( - "ecall", - inlateout("a0") a0, - inlateout("a1") a1, - inlateout("a2") a2 => _, - inlateout("a3") a3 => _, - inlateout("a4") a4 => _, - inlateout("a5") a5 => _, - inlateout("a6") a6 => _, - inlateout("a7") a7 => _, - ) - }; - - let result = a0; - - if result == SyscallResult::Ok as usize { - Ok(()) - } else if result == SyscallResult::Error as usize { - Err(a1.into()) - } else { - Err(Error::InternalError) - } -} - -pub(crate) fn scalar(connection: Connection, args: [usize; 5]) -> Result<(), Error> { - scalar_impl(connection, args, true) -} - -pub(crate) fn try_scalar(connection: Connection, args: [usize; 5]) -> Result<(), Error> { - scalar_impl(connection, args, false) -} - -fn blocking_scalar_impl( - connection: Connection, - args: [usize; 5], - blocking: bool, -) -> Result<[usize; 5], Error> { - let mut a0 = if blocking { Syscall::SendMessage } else { Syscall::TrySendMessage } as usize; - let mut a1: usize = connection.try_into().unwrap(); - let mut a2 = InvokeType::BlockingScalar as usize; - let mut a3 = args[0]; - let mut a4 = args[1]; - let mut a5 = args[2]; - let a6 = args[3]; - let a7 = args[4]; - - unsafe { - core::arch::asm!( - "ecall", - inlateout("a0") a0, - inlateout("a1") a1, - inlateout("a2") a2, - inlateout("a3") a3, - inlateout("a4") a4, - inlateout("a5") a5, - inlateout("a6") a6 => _, - inlateout("a7") a7 => _, - ) - }; - - let result = a0; - - if result == SyscallResult::Scalar1 as usize { - Ok([a1, 0, 0, 0, 0]) - } else if result == SyscallResult::Scalar2 as usize { - Ok([a1, a2, 0, 0, 0]) - } else if result == SyscallResult::Scalar5 as usize { - Ok([a1, a2, a3, a4, a5]) - } else if result == SyscallResult::Error as usize { - Err(a1.into()) - } else { - Err(Error::InternalError) - } -} - -pub(crate) fn blocking_scalar( - connection: Connection, - args: [usize; 5], -) -> Result<[usize; 5], Error> { - blocking_scalar_impl(connection, args, true) -} - -pub(crate) fn try_blocking_scalar( - connection: Connection, - args: [usize; 5], -) -> Result<[usize; 5], Error> { - blocking_scalar_impl(connection, args, false) -} - -fn connect_impl(address: ServerAddress, blocking: bool) -> Result { - let a0 = if blocking { Syscall::Connect } else { Syscall::TryConnect } as usize; - let address: [u32; 4] = address.into(); - let a1: usize = address[0].try_into().unwrap(); - let a2: usize = address[1].try_into().unwrap(); - let a3: usize = address[2].try_into().unwrap(); - let a4: usize = address[3].try_into().unwrap(); - let a5 = 0; - let a6 = 0; - let a7 = 0; - - let mut result: usize; - let mut value: usize; - - unsafe { - core::arch::asm!( - "ecall", - inlateout("a0") a0 => result, - inlateout("a1") a1 => value, - inlateout("a2") a2 => _, - inlateout("a3") a3 => _, - inlateout("a4") a4 => _, - inlateout("a5") a5 => _, - inlateout("a6") a6 => _, - inlateout("a7") a7 => _, - ) - }; - if result == SyscallResult::ConnectionId as usize { - Ok(value.try_into().unwrap()) - } else if result == SyscallResult::Error as usize { - Err(value.into()) - } else { - Err(Error::InternalError) - } -} - -/// Connect to a Xous server represented by the specified `address`. -/// -/// The current thread will block until the server is available. Returns -/// an error if the server cannot accept any more connections. -pub(crate) fn connect(address: ServerAddress) -> Result { - connect_impl(address, true) -} - -/// Attempt to connect to a Xous server represented by the specified `address`. -/// -/// If the server does not exist then None is returned. -pub(crate) fn try_connect(address: ServerAddress) -> Result, Error> { - match connect_impl(address, false) { - Ok(conn) => Ok(Some(conn)), - Err(Error::ServerNotFound) => Ok(None), - Err(e) => Err(e), - } -} - -/// Terminate the current process and return the specified code to the parent process. -pub(crate) fn exit(return_code: u32) -> ! { - let a0 = Syscall::TerminateProcess as usize; - let a1 = return_code as usize; - let a2 = 0; - let a3 = 0; - let a4 = 0; - let a5 = 0; - let a6 = 0; - let a7 = 0; - - unsafe { - core::arch::asm!( - "ecall", - in("a0") a0, - in("a1") a1, - in("a2") a2, - in("a3") a3, - in("a4") a4, - in("a5") a5, - in("a6") a6, - in("a7") a7, - ) - }; - unreachable!(); -} - -/// Suspend the current thread and allow another thread to run. This thread may -/// continue executing again immediately if there are no other threads available -/// to run on the system. -pub(crate) fn do_yield() { - let a0 = Syscall::Yield as usize; - let a1 = 0; - let a2 = 0; - let a3 = 0; - let a4 = 0; - let a5 = 0; - let a6 = 0; - let a7 = 0; - - unsafe { - core::arch::asm!( - "ecall", - inlateout("a0") a0 => _, - inlateout("a1") a1 => _, - inlateout("a2") a2 => _, - inlateout("a3") a3 => _, - inlateout("a4") a4 => _, - inlateout("a5") a5 => _, - inlateout("a6") a6 => _, - inlateout("a7") a7 => _, - ) - }; -} - -/// Allocate memory from the system. An optional physical and/or virtual address -/// may be specified in order to ensure memory is allocated at specific offsets, -/// otherwise the kernel will select an address. -/// -/// # Safety -/// -/// This function is safe unless a virtual address is specified. In that case, -/// the kernel will return an alias to the existing range. This violates Rust's -/// pointer uniqueness guarantee. -pub(crate) unsafe fn map_memory( - phys: Option>, - virt: Option>, - count: usize, - flags: MemoryFlags, -) -> Result<&'static mut [T], Error> { - let mut a0 = Syscall::MapMemory as usize; - let mut a1 = phys.map(|p| p.as_ptr() as usize).unwrap_or_default(); - let mut a2 = virt.map(|p| p.as_ptr() as usize).unwrap_or_default(); - let a3 = count * core::mem::size_of::(); - let a4 = flags.bits(); - let a5 = 0; - let a6 = 0; - let a7 = 0; - - unsafe { - core::arch::asm!( - "ecall", - inlateout("a0") a0, - inlateout("a1") a1, - inlateout("a2") a2, - inlateout("a3") a3 => _, - inlateout("a4") a4 => _, - inlateout("a5") a5 => _, - inlateout("a6") a6 => _, - inlateout("a7") a7 => _, - ) - }; - - let result = a0; - - if result == SyscallResult::MemoryRange as usize { - let start = core::ptr::with_exposed_provenance_mut::(a1); - let len = a2 / core::mem::size_of::(); - let end = unsafe { start.add(len) }; - Ok(unsafe { core::slice::from_raw_parts_mut(start, len) }) - } else if result == SyscallResult::Error as usize { - Err(a1.into()) - } else { - Err(Error::InternalError) - } -} - -/// Destroy the given memory, returning it to the compiler. -/// -/// Safety: The memory pointed to by `range` should not be used after this -/// function returns, even if this function returns Err(). -pub(crate) unsafe fn unmap_memory(range: *mut [T]) -> Result<(), Error> { - let mut a0 = Syscall::UnmapMemory as usize; - let mut a1 = range.as_mut_ptr() as usize; - let a2 = range.len() * core::mem::size_of::(); - let a3 = 0; - let a4 = 0; - let a5 = 0; - let a6 = 0; - let a7 = 0; - - unsafe { - core::arch::asm!( - "ecall", - inlateout("a0") a0, - inlateout("a1") a1, - inlateout("a2") a2 => _, - inlateout("a3") a3 => _, - inlateout("a4") a4 => _, - inlateout("a5") a5 => _, - inlateout("a6") a6 => _, - inlateout("a7") a7 => _, - ) - }; - - let result = a0; - - if result == SyscallResult::Ok as usize { - Ok(()) - } else if result == SyscallResult::Error as usize { - Err(a1.into()) - } else { - Err(Error::InternalError) - } -} - -/// Adjust the memory flags for the given range. This can be used to remove flags -/// from a given region in order to harden memory access. Note that flags may -/// only be removed and may never be added. -/// -/// Safety: The memory pointed to by `range` may become inaccessible or have its -/// mutability removed. It is up to the caller to ensure that the flags specified -/// by `new_flags` are upheld, otherwise the program will crash. -pub(crate) unsafe fn update_memory_flags( - range: *mut [T], - new_flags: MemoryFlags, -) -> Result<(), Error> { - let mut a0 = Syscall::UpdateMemoryFlags as usize; - let mut a1 = range.as_mut_ptr() as usize; - let a2 = range.len() * core::mem::size_of::(); - let a3 = new_flags.bits(); - let a4 = 0; // Process ID is currently None - let a5 = 0; - let a6 = 0; - let a7 = 0; - - unsafe { - core::arch::asm!( - "ecall", - inlateout("a0") a0, - inlateout("a1") a1, - inlateout("a2") a2 => _, - inlateout("a3") a3 => _, - inlateout("a4") a4 => _, - inlateout("a5") a5 => _, - inlateout("a6") a6 => _, - inlateout("a7") a7 => _, - ) - }; - - let result = a0; - - if result == SyscallResult::Ok as usize { - Ok(()) - } else if result == SyscallResult::Error as usize { - Err(a1.into()) - } else { - Err(Error::InternalError) - } -} - -/// Create a thread with a given stack and up to four arguments -pub(crate) fn create_thread( - start: *mut usize, - stack: *mut [u8], - arg0: usize, - arg1: usize, - arg2: usize, - arg3: usize, -) -> Result { - let mut a0 = Syscall::CreateThread as usize; - let mut a1 = start as usize; - let a2 = stack.as_mut_ptr() as usize; - let a3 = stack.len(); - let a4 = arg0; - let a5 = arg1; - let a6 = arg2; - let a7 = arg3; - - unsafe { - core::arch::asm!( - "ecall", - inlateout("a0") a0, - inlateout("a1") a1, - inlateout("a2") a2 => _, - inlateout("a3") a3 => _, - inlateout("a4") a4 => _, - inlateout("a5") a5 => _, - inlateout("a6") a6 => _, - inlateout("a7") a7 => _, - ) - }; - - let result = a0; - - if result == SyscallResult::ThreadId as usize { - Ok(a1.into()) - } else if result == SyscallResult::Error as usize { - Err(a1.into()) - } else { - Err(Error::InternalError) - } -} - -/// Wait for the given thread to terminate and return the exit code from that thread. -pub(crate) fn join_thread(thread_id: ThreadId) -> Result { - let mut a0 = Syscall::JoinThread as usize; - let mut a1 = thread_id.into(); - let a2 = 0; - let a3 = 0; - let a4 = 0; - let a5 = 0; - let a6 = 0; - let a7 = 0; - - unsafe { - core::arch::asm!( - "ecall", - inlateout("a0") a0, - inlateout("a1") a1, - inlateout("a2") a2 => _, - inlateout("a3") a3 => _, - inlateout("a4") a4 => _, - inlateout("a5") a5 => _, - inlateout("a6") a6 => _, - inlateout("a7") a7 => _, - ) - }; - - let result = a0; - - if result == SyscallResult::Scalar1 as usize { - Ok(a1) - } else if result == SyscallResult::Scalar2 as usize { - Ok(a1) - } else if result == SyscallResult::Scalar5 as usize { - Ok(a1) - } else if result == SyscallResult::Error as usize { - Err(a1.into()) - } else { - Err(Error::InternalError) - } -} - -/// Get the current thread's ID -pub(crate) fn thread_id() -> Result { - let mut a0 = Syscall::GetThreadId as usize; - let mut a1 = 0; - let a2 = 0; - let a3 = 0; - let a4 = 0; - let a5 = 0; - let a6 = 0; - let a7 = 0; - - unsafe { - core::arch::asm!( - "ecall", - inlateout("a0") a0, - inlateout("a1") a1, - inlateout("a2") a2 => _, - inlateout("a3") a3 => _, - inlateout("a4") a4 => _, - inlateout("a5") a5 => _, - inlateout("a6") a6 => _, - inlateout("a7") a7 => _, - ) - }; - - let result = a0; - - if result == SyscallResult::ThreadId as usize { - Ok(a1.into()) - } else if result == SyscallResult::Error as usize { - Err(a1.into()) - } else { - Err(Error::InternalError) - } -} - -/// Adjust the given `knob` limit to match the new value `new`. The current value must -/// match the `current` in order for this to take effect. -/// -/// The new value is returned as a result of this call. If the call fails, then the old -/// value is returned. In either case, this function returns successfully. -/// -/// An error is generated if the `knob` is not a valid limit, or if the call -/// would not succeed. -pub(crate) fn adjust_limit(knob: Limits, current: usize, new: usize) -> Result { - let mut a0 = Syscall::JoinThread as usize; - let mut a1 = knob as usize; - let a2 = current; - let a3 = new; - let a4 = 0; - let a5 = 0; - let a6 = 0; - let a7 = 0; - - unsafe { - core::arch::asm!( - "ecall", - inlateout("a0") a0, - inlateout("a1") a1, - inlateout("a2") a2 => _, - inlateout("a3") a3 => _, - inlateout("a4") a4 => _, - inlateout("a5") a5 => _, - inlateout("a6") a6 => _, - inlateout("a7") a7 => _, - ) - }; - - let result = a0; - - if result == SyscallResult::Scalar2 as usize && a1 == knob as usize { - Ok(a2) - } else if result == SyscallResult::Scalar5 as usize && a1 == knob as usize { - Ok(a1) - } else if result == SyscallResult::Error as usize { - Err(a1.into()) - } else { - Err(Error::InternalError) - } -} diff --git a/library/std/src/os/xous/ffi/definitions.rs b/library/std/src/os/xous/ffi/definitions.rs deleted file mode 100644 index 345005bcc78d7..0000000000000 --- a/library/std/src/os/xous/ffi/definitions.rs +++ /dev/null @@ -1,283 +0,0 @@ -mod memoryflags; -pub(crate) use memoryflags::*; - -#[stable(feature = "rust1", since = "1.0.0")] -/// Indicates a particular syscall number as used by the Xous kernel. -#[derive(Copy, Clone)] -#[repr(usize)] -pub enum Syscall { - MapMemory = 2, - Yield = 3, - UpdateMemoryFlags = 12, - ReceiveMessage = 15, - SendMessage = 16, - Connect = 17, - CreateThread = 18, - UnmapMemory = 19, - ReturnMemory = 20, - TerminateProcess = 22, - TrySendMessage = 24, - TryConnect = 25, - GetThreadId = 32, - JoinThread = 36, - AdjustProcessLimit = 38, - ReturnScalar = 40, -} - -#[stable(feature = "rust1", since = "1.0.0")] -/// Copies of these invocation types here for when we're running -/// in environments without libxous. -#[derive(Copy, Clone)] -#[repr(usize)] -pub enum SyscallResult { - Ok = 0, - Error = 1, - MemoryRange = 3, - ConnectionId = 7, - Message = 9, - ThreadId = 10, - Scalar1 = 14, - Scalar2 = 15, - MemoryReturned = 18, - Scalar5 = 20, -} - -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Copy, Clone)] -/// A list of all known errors that may be returned by the Xous kernel. -#[repr(usize)] -pub enum Error { - NoError = 0, - BadAlignment = 1, - BadAddress = 2, - OutOfMemory = 3, - MemoryInUse = 4, - InterruptNotFound = 5, - InterruptInUse = 6, - InvalidString = 7, - ServerExists = 8, - ServerNotFound = 9, - ProcessNotFound = 10, - ProcessNotChild = 11, - ProcessTerminated = 12, - Timeout = 13, - InternalError = 14, - ServerQueueFull = 15, - ThreadNotAvailable = 16, - UnhandledSyscall = 17, - InvalidSyscall = 18, - ShareViolation = 19, - InvalidThread = 20, - InvalidPid = 21, - UnknownError = 22, - AccessDenied = 23, - UseBeforeInit = 24, - DoubleFree = 25, - DebugInProgress = 26, - InvalidLimit = 27, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl From for Error { - fn from(src: usize) -> Self { - match src { - 0 => Self::NoError, - 1 => Self::BadAlignment, - 2 => Self::BadAddress, - 3 => Self::OutOfMemory, - 4 => Self::MemoryInUse, - 5 => Self::InterruptNotFound, - 6 => Self::InterruptInUse, - 7 => Self::InvalidString, - 8 => Self::ServerExists, - 9 => Self::ServerNotFound, - 10 => Self::ProcessNotFound, - 11 => Self::ProcessNotChild, - 12 => Self::ProcessTerminated, - 13 => Self::Timeout, - 14 => Self::InternalError, - 15 => Self::ServerQueueFull, - 16 => Self::ThreadNotAvailable, - 17 => Self::UnhandledSyscall, - 18 => Self::InvalidSyscall, - 19 => Self::ShareViolation, - 20 => Self::InvalidThread, - 21 => Self::InvalidPid, - 23 => Self::AccessDenied, - 24 => Self::UseBeforeInit, - 25 => Self::DoubleFree, - 26 => Self::DebugInProgress, - 27 => Self::InvalidLimit, - 22 | _ => Self::UnknownError, - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl From for Error { - fn from(src: i32) -> Self { - let Ok(src) = core::convert::TryInto::::try_into(src) else { - return Self::UnknownError; - }; - src.into() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl core::fmt::Display for Error { - fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { - write!( - f, - "{}", - match self { - Error::NoError => "no error occurred", - Error::BadAlignment => "memory was not properly aligned", - Error::BadAddress => "an invalid address was supplied", - Error::OutOfMemory => "the process or service has run out of memory", - Error::MemoryInUse => "the requested address is in use", - Error::InterruptNotFound => - "the requested interrupt does not exist on this platform", - Error::InterruptInUse => "the requested interrupt is currently in use", - Error::InvalidString => "the specified string was not formatted correctly", - Error::ServerExists => "a server with that address already exists", - Error::ServerNotFound => "the requetsed server could not be found", - Error::ProcessNotFound => "the target process does not exist", - Error::ProcessNotChild => - "the requested operation can only be done on child processes", - Error::ProcessTerminated => "the target process has crashed", - Error::Timeout => "the requested operation timed out", - Error::InternalError => "an internal error occurred", - Error::ServerQueueFull => "the server has too many pending messages", - Error::ThreadNotAvailable => "the specified thread does not exist", - Error::UnhandledSyscall => "the kernel did not recognize that syscall", - Error::InvalidSyscall => "the syscall had incorrect parameters", - Error::ShareViolation => "an attempt was made to share memory twice", - Error::InvalidThread => "tried to resume a thread that was not ready", - Error::InvalidPid => "kernel attempted to use a pid that was not valid", - Error::AccessDenied => "no permission to perform the requested operation", - Error::UseBeforeInit => "attempt to use a service before initialization finished", - Error::DoubleFree => "the requested resource was freed twice", - Error::DebugInProgress => "kernel attempted to activate a thread being debugged", - Error::InvalidLimit => "process attempted to adjust an invalid limit", - Error::UnknownError => "an unknown error occurred", - } - ) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl core::fmt::Debug for Error { - fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { - write!(f, "{}", self) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl crate::error::Error for Error {} - -/// Indicates the type of Message that is sent when making a `SendMessage` syscall. -#[derive(Copy, Clone)] -#[repr(usize)] -pub(crate) enum InvokeType { - LendMut = 1, - Lend = 2, - Move = 3, - Scalar = 4, - BlockingScalar = 5, -} - -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Debug, Copy, Clone)] -/// A representation of a connection to a Xous service. -pub struct Connection(u32); - -#[stable(feature = "rust1", since = "1.0.0")] -impl From for Connection { - fn from(src: u32) -> Connection { - Connection(src) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl TryFrom for Connection { - type Error = core::num::TryFromIntError; - fn try_from(src: usize) -> Result { - Ok(Connection(src.try_into()?)) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Into for Connection { - fn into(self) -> u32 { - self.0 - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl TryInto for Connection { - type Error = core::num::TryFromIntError; - fn try_into(self) -> Result { - self.0.try_into() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Debug)] -pub enum ServerAddressError { - InvalidLength, -} - -#[stable(feature = "rust1", since = "1.0.0")] -pub struct ServerAddress([u32; 4]); - -#[stable(feature = "rust1", since = "1.0.0")] -impl TryFrom<&str> for ServerAddress { - type Error = ServerAddressError; - fn try_from(value: &str) -> Result { - let b = value.as_bytes(); - if b.len() == 0 || b.len() > 16 { - return Err(Self::Error::InvalidLength); - } - - let mut this_temp = [0u8; 16]; - for (dest, src) in this_temp.iter_mut().zip(b.iter()) { - *dest = *src; - } - - let mut this = [0u32; 4]; - for (dest, src) in this.iter_mut().zip(this_temp.chunks_exact(4)) { - *dest = u32::from_le_bytes(src.try_into().unwrap()); - } - Ok(ServerAddress(this)) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Into<[u32; 4]> for ServerAddress { - fn into(self) -> [u32; 4] { - self.0 - } -} - -#[derive(Debug, Copy, Clone)] -pub(crate) struct ThreadId(usize); - -impl From for ThreadId { - fn from(src: usize) -> ThreadId { - ThreadId(src) - } -} - -impl Into for ThreadId { - fn into(self) -> usize { - self.0 - } -} - -#[derive(Copy, Clone)] -#[repr(usize)] -/// Limits that can be passed to `AdjustLimit` -pub(crate) enum Limits { - HeapMaximum = 1, - HeapSize = 2, -} diff --git a/library/std/src/os/xous/ffi/definitions/memoryflags.rs b/library/std/src/os/xous/ffi/definitions/memoryflags.rs deleted file mode 100644 index af9de3cbff29b..0000000000000 --- a/library/std/src/os/xous/ffi/definitions/memoryflags.rs +++ /dev/null @@ -1,176 +0,0 @@ -/// Flags to be passed to the MapMemory struct. -/// Note that it is an error to have memory be -/// writable and not readable. -#[derive(Copy, PartialEq, Eq, Clone, PartialOrd, Ord, Hash, Debug)] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct MemoryFlags { - bits: usize, -} - -impl MemoryFlags { - /// Free this memory - #[stable(feature = "rust1", since = "1.0.0")] - pub const FREE: Self = Self { bits: 0b0000_0000 }; - - /// Immediately allocate this memory. Otherwise it will - /// be demand-paged. This is implicitly set when `phys` - /// is not 0. - #[stable(feature = "rust1", since = "1.0.0")] - pub const RESERVE: Self = Self { bits: 0b0000_0001 }; - - /// Allow the CPU to read from this page. - #[stable(feature = "rust1", since = "1.0.0")] - pub const R: Self = Self { bits: 0b0000_0010 }; - - /// Allow the CPU to write to this page. - #[stable(feature = "rust1", since = "1.0.0")] - pub const W: Self = Self { bits: 0b0000_0100 }; - - /// Allow the CPU to execute from this page. - #[stable(feature = "rust1", since = "1.0.0")] - pub const X: Self = Self { bits: 0b0000_1000 }; - - #[stable(feature = "rust1", since = "1.0.0")] - pub fn bits(&self) -> usize { - self.bits - } - - #[stable(feature = "rust1", since = "1.0.0")] - pub fn from_bits(raw: usize) -> Option { - if raw > 16 { None } else { Some(MemoryFlags { bits: raw }) } - } - - #[stable(feature = "rust1", since = "1.0.0")] - pub fn is_empty(&self) -> bool { - self.bits == 0 - } - - #[stable(feature = "rust1", since = "1.0.0")] - pub fn empty() -> MemoryFlags { - MemoryFlags { bits: 0 } - } - - #[stable(feature = "rust1", since = "1.0.0")] - pub fn all() -> MemoryFlags { - MemoryFlags { bits: 15 } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl core::fmt::Binary for MemoryFlags { - fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { - core::fmt::Binary::fmt(&self.bits, f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl core::fmt::Octal for MemoryFlags { - fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { - core::fmt::Octal::fmt(&self.bits, f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl core::fmt::LowerHex for MemoryFlags { - fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { - core::fmt::LowerHex::fmt(&self.bits, f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl core::fmt::UpperHex for MemoryFlags { - fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result { - core::fmt::UpperHex::fmt(&self.bits, f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl core::ops::BitOr for MemoryFlags { - type Output = Self; - - /// Returns the union of the two sets of flags. - #[inline] - fn bitor(self, other: MemoryFlags) -> Self { - Self { bits: self.bits | other.bits } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl core::ops::BitOrAssign for MemoryFlags { - /// Adds the set of flags. - #[inline] - fn bitor_assign(&mut self, other: Self) { - self.bits |= other.bits; - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl core::ops::BitXor for MemoryFlags { - type Output = Self; - - /// Returns the left flags, but with all the right flags toggled. - #[inline] - fn bitxor(self, other: Self) -> Self { - Self { bits: self.bits ^ other.bits } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl core::ops::BitXorAssign for MemoryFlags { - /// Toggles the set of flags. - #[inline] - fn bitxor_assign(&mut self, other: Self) { - self.bits ^= other.bits; - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl core::ops::BitAnd for MemoryFlags { - type Output = Self; - - /// Returns the intersection between the two sets of flags. - #[inline] - fn bitand(self, other: Self) -> Self { - Self { bits: self.bits & other.bits } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl core::ops::BitAndAssign for MemoryFlags { - /// Disables all flags disabled in the set. - #[inline] - fn bitand_assign(&mut self, other: Self) { - self.bits &= other.bits; - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl core::ops::Sub for MemoryFlags { - type Output = Self; - - /// Returns the set difference of the two sets of flags. - #[inline] - fn sub(self, other: Self) -> Self { - Self { bits: self.bits & !other.bits } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl core::ops::SubAssign for MemoryFlags { - /// Disables all flags enabled in the set. - #[inline] - fn sub_assign(&mut self, other: Self) { - self.bits &= !other.bits; - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl core::ops::Not for MemoryFlags { - type Output = Self; - - /// Returns the complement of this set of flags. - #[inline] - fn not(self) -> Self { - Self { bits: !self.bits } & MemoryFlags { bits: 15 } - } -} diff --git a/library/std/src/os/xous/mod.rs b/library/std/src/os/xous/mod.rs deleted file mode 100644 index 153694a89a78d..0000000000000 --- a/library/std/src/os/xous/mod.rs +++ /dev/null @@ -1,17 +0,0 @@ -#![stable(feature = "rust1", since = "1.0.0")] -#![doc(cfg(target_os = "xous"))] - -pub mod ffi; - -#[stable(feature = "rust1", since = "1.0.0")] -pub mod services; - -/// A prelude for conveniently writing platform-specific code. -/// -/// Includes all extension traits, and some important type definitions. -#[stable(feature = "rust1", since = "1.0.0")] -pub mod prelude { - #[doc(no_inline)] - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::ffi::{OsStrExt, OsStringExt}; -} diff --git a/library/std/src/os/xous/services.rs b/library/std/src/os/xous/services.rs deleted file mode 100644 index a75be1b857003..0000000000000 --- a/library/std/src/os/xous/services.rs +++ /dev/null @@ -1,138 +0,0 @@ -use crate::os::xous::ffi::Connection; -use core::sync::atomic::{AtomicU32, Ordering}; - -mod dns; -pub(crate) use dns::*; - -mod log; -pub(crate) use log::*; - -mod net; -pub(crate) use net::*; - -mod systime; -pub(crate) use systime::*; - -mod ticktimer; -pub(crate) use ticktimer::*; - -mod ns { - const NAME_MAX_LENGTH: usize = 64; - use crate::os::xous::ffi::{lend_mut, Connection}; - // By making this repr(C), the layout of this struct becomes well-defined - // and no longer shifts around. - // By marking it as `align(4096)` we define that it will be page-aligned, - // meaning it can be sent between processes. We make sure to pad out the - // entire struct so that memory isn't leaked to the name server. - #[repr(C, align(4096))] - struct ConnectRequest { - data: [u8; 4096], - } - - impl ConnectRequest { - pub fn new(name: &str) -> Self { - let mut cr = ConnectRequest { data: [0u8; 4096] }; - let name_bytes = name.as_bytes(); - - // Copy the string into our backing store. - for (&src_byte, dest_byte) in name_bytes.iter().zip(&mut cr.data[0..NAME_MAX_LENGTH]) { - *dest_byte = src_byte; - } - - // Set the string length to the length of the passed-in String, - // or the maximum possible length. Which ever is smaller. - for (&src_byte, dest_byte) in (name.len().min(NAME_MAX_LENGTH) as u32) - .to_le_bytes() - .iter() - .zip(&mut cr.data[NAME_MAX_LENGTH..]) - { - *dest_byte = src_byte; - } - cr - } - } - - pub fn connect_with_name_impl(name: &str, blocking: bool) -> Option { - let mut request = ConnectRequest::new(name); - let opcode = if blocking { - 6 /* BlockingConnect */ - } else { - 7 /* TryConnect */ - }; - let cid = if blocking { super::name_server() } else { super::try_name_server()? }; - - lend_mut(cid, opcode, &mut request.data, 0, name.len().min(NAME_MAX_LENGTH)) - .expect("unable to perform lookup"); - - // Read the result code back from the nameserver - let result = u32::from_le_bytes(request.data[0..4].try_into().unwrap()); - if result == 0 { - // If the result was successful, then the CID is stored in the next 4 bytes - Some(u32::from_le_bytes(request.data[4..8].try_into().unwrap()).into()) - } else { - None - } - } - - pub fn connect_with_name(name: &str) -> Option { - connect_with_name_impl(name, true) - } - - pub fn try_connect_with_name(name: &str) -> Option { - connect_with_name_impl(name, false) - } -} - -/// Attempt to connect to a server by name. If the server does not exist, this will -/// block until the server is created. -/// -/// Note that this is different from connecting to a server by address. Server -/// addresses are always 16 bytes long, whereas server names are arbitrary-length -/// strings up to 64 bytes in length. -#[stable(feature = "rust1", since = "1.0.0")] -pub fn connect(name: &str) -> Option { - ns::connect_with_name(name) -} - -/// Attempt to connect to a server by name. If the server does not exist, this will -/// immediately return `None`. -/// -/// Note that this is different from connecting to a server by address. Server -/// addresses are always 16 bytes long, whereas server names are arbitrary-length -/// strings. -#[stable(feature = "rust1", since = "1.0.0")] -pub fn try_connect(name: &str) -> Option { - ns::try_connect_with_name(name) -} - -static NAME_SERVER_CONNECTION: AtomicU32 = AtomicU32::new(0); - -/// Return a `Connection` to the name server. If the name server has not been started, -/// then this call will block until the name server has been started. The `Connection` -/// will be shared among all connections in a process, so it is safe to call this -/// multiple times. -pub(crate) fn name_server() -> Connection { - let cid = NAME_SERVER_CONNECTION.load(Ordering::Relaxed); - if cid != 0 { - return cid.into(); - } - - let cid = crate::os::xous::ffi::connect("xous-name-server".try_into().unwrap()).unwrap(); - NAME_SERVER_CONNECTION.store(cid.into(), Ordering::Relaxed); - cid -} - -fn try_name_server() -> Option { - let cid = NAME_SERVER_CONNECTION.load(Ordering::Relaxed); - if cid != 0 { - return Some(cid.into()); - } - - if let Ok(Some(cid)) = crate::os::xous::ffi::try_connect("xous-name-server".try_into().unwrap()) - { - NAME_SERVER_CONNECTION.store(cid.into(), Ordering::Relaxed); - Some(cid) - } else { - None - } -} diff --git a/library/std/src/os/xous/services/dns.rs b/library/std/src/os/xous/services/dns.rs deleted file mode 100644 index a7d88f4892cda..0000000000000 --- a/library/std/src/os/xous/services/dns.rs +++ /dev/null @@ -1,28 +0,0 @@ -use crate::os::xous::ffi::Connection; -use crate::os::xous::services::connect; -use core::sync::atomic::{AtomicU32, Ordering}; - -#[repr(usize)] -pub(crate) enum DnsLendMut { - RawLookup = 6, -} - -impl Into for DnsLendMut { - fn into(self) -> usize { - self as usize - } -} - -/// Return a `Connection` to the DNS lookup server. This server is used for -/// querying domain name values. -pub(crate) fn dns_server() -> Connection { - static DNS_CONNECTION: AtomicU32 = AtomicU32::new(0); - let cid = DNS_CONNECTION.load(Ordering::Relaxed); - if cid != 0 { - return cid.into(); - } - - let cid = connect("_DNS Resolver Middleware_").unwrap(); - DNS_CONNECTION.store(cid.into(), Ordering::Relaxed); - cid -} diff --git a/library/std/src/os/xous/services/log.rs b/library/std/src/os/xous/services/log.rs deleted file mode 100644 index 55a501dc7d00e..0000000000000 --- a/library/std/src/os/xous/services/log.rs +++ /dev/null @@ -1,74 +0,0 @@ -use crate::os::xous::ffi::Connection; -use core::sync::atomic::{AtomicU32, Ordering}; - -/// Group `usize` bytes into a `usize` and return it, beginning -/// from `offset` * sizeof(usize) bytes from the start. For example, -/// `group_or_null([1,2,3,4,5,6,7,8], 1)` on a 32-bit system will -/// return a usize with 5678 packed into it. -fn group_or_null(data: &[u8], offset: usize) -> usize { - let start = offset * core::mem::size_of::(); - let mut out_array = [0u8; core::mem::size_of::()]; - if start < data.len() { - for (dest, src) in out_array.iter_mut().zip(&data[start..]) { - *dest = *src; - } - } - usize::from_le_bytes(out_array) -} - -pub(crate) enum LogScalar<'a> { - /// A panic occurred, and a panic log is forthcoming - BeginPanic, - - /// Some number of bytes will be appended to the log message - AppendPanicMessage(&'a [u8]), -} - -impl<'a> Into<[usize; 5]> for LogScalar<'a> { - fn into(self) -> [usize; 5] { - match self { - LogScalar::BeginPanic => [1000, 0, 0, 0, 0], - LogScalar::AppendPanicMessage(c) => - // Text is grouped into 4x `usize` words. The id is 1100 plus - // the number of characters in this message. - // Ignore errors since we're already panicking. - { - [ - 1100 + c.len(), - group_or_null(&c, 0), - group_or_null(&c, 1), - group_or_null(&c, 2), - group_or_null(&c, 3), - ] - } - } - } -} - -pub(crate) enum LogLend { - StandardOutput = 1, - StandardError = 2, -} - -impl Into for LogLend { - fn into(self) -> usize { - self as usize - } -} - -/// Return a `Connection` to the log server, which is used for printing messages to -/// the console and reporting panics. If the log server has not yet started, this -/// will block until the server is running. It is safe to call this multiple times, -/// because the address is shared among all threads in a process. -pub(crate) fn log_server() -> Connection { - static LOG_SERVER_CONNECTION: AtomicU32 = AtomicU32::new(0); - - let cid = LOG_SERVER_CONNECTION.load(Ordering::Relaxed); - if cid != 0 { - return cid.into(); - } - - let cid = crate::os::xous::ffi::connect("xous-log-server ".try_into().unwrap()).unwrap(); - LOG_SERVER_CONNECTION.store(cid.into(), Ordering::Relaxed); - cid -} diff --git a/library/std/src/os/xous/services/net.rs b/library/std/src/os/xous/services/net.rs deleted file mode 100644 index 26d337dcef168..0000000000000 --- a/library/std/src/os/xous/services/net.rs +++ /dev/null @@ -1,95 +0,0 @@ -use crate::os::xous::ffi::Connection; -use crate::os::xous::services::connect; -use core::sync::atomic::{AtomicU32, Ordering}; - -pub(crate) enum NetBlockingScalar { - StdGetTtlUdp(u16 /* fd */), /* 36 */ - StdSetTtlUdp(u16 /* fd */, u32 /* ttl */), /* 37 */ - StdGetTtlTcp(u16 /* fd */), /* 36 */ - StdSetTtlTcp(u16 /* fd */, u32 /* ttl */), /* 37 */ - StdGetNodelay(u16 /* fd */), /* 38 */ - StdSetNodelay(u16 /* fd */, bool), /* 39 */ - StdTcpClose(u16 /* fd */), /* 34 */ - StdUdpClose(u16 /* fd */), /* 41 */ - StdTcpStreamShutdown(u16 /* fd */, crate::net::Shutdown /* how */), /* 46 */ -} - -pub(crate) enum NetLendMut { - StdTcpConnect, /* 30 */ - StdTcpTx(u16 /* fd */), /* 31 */ - StdTcpPeek(u16 /* fd */, bool /* nonblocking */), /* 32 */ - StdTcpRx(u16 /* fd */, bool /* nonblocking */), /* 33 */ - StdGetAddress(u16 /* fd */), /* 35 */ - StdUdpBind, /* 40 */ - StdUdpRx(u16 /* fd */), /* 42 */ - StdUdpTx(u16 /* fd */), /* 43 */ - StdTcpListen, /* 44 */ - StdTcpAccept(u16 /* fd */), /* 45 */ -} - -impl Into for NetLendMut { - fn into(self) -> usize { - match self { - NetLendMut::StdTcpConnect => 30, - NetLendMut::StdTcpTx(fd) => 31 | ((fd as usize) << 16), - NetLendMut::StdTcpPeek(fd, blocking) => { - 32 | ((fd as usize) << 16) | if blocking { 0x8000 } else { 0 } - } - NetLendMut::StdTcpRx(fd, blocking) => { - 33 | ((fd as usize) << 16) | if blocking { 0x8000 } else { 0 } - } - NetLendMut::StdGetAddress(fd) => 35 | ((fd as usize) << 16), - NetLendMut::StdUdpBind => 40, - NetLendMut::StdUdpRx(fd) => 42 | ((fd as usize) << 16), - NetLendMut::StdUdpTx(fd) => 43 | ((fd as usize) << 16), - NetLendMut::StdTcpListen => 44, - NetLendMut::StdTcpAccept(fd) => 45 | ((fd as usize) << 16), - } - } -} - -impl<'a> Into<[usize; 5]> for NetBlockingScalar { - fn into(self) -> [usize; 5] { - match self { - NetBlockingScalar::StdGetTtlTcp(fd) => [36 | ((fd as usize) << 16), 0, 0, 0, 0], - NetBlockingScalar::StdGetTtlUdp(fd) => [36 | ((fd as usize) << 16), 0, 0, 0, 1], - NetBlockingScalar::StdSetTtlTcp(fd, ttl) => { - [37 | ((fd as usize) << 16), ttl as _, 0, 0, 0] - } - NetBlockingScalar::StdSetTtlUdp(fd, ttl) => { - [37 | ((fd as usize) << 16), ttl as _, 0, 0, 1] - } - NetBlockingScalar::StdGetNodelay(fd) => [38 | ((fd as usize) << 16), 0, 0, 0, 0], - NetBlockingScalar::StdSetNodelay(fd, enabled) => { - [39 | ((fd as usize) << 16), if enabled { 1 } else { 0 }, 0, 0, 1] - } - NetBlockingScalar::StdTcpClose(fd) => [34 | ((fd as usize) << 16), 0, 0, 0, 0], - NetBlockingScalar::StdUdpClose(fd) => [41 | ((fd as usize) << 16), 0, 0, 0, 0], - NetBlockingScalar::StdTcpStreamShutdown(fd, how) => [ - 46 | ((fd as usize) << 16), - match how { - crate::net::Shutdown::Read => 1, - crate::net::Shutdown::Write => 2, - crate::net::Shutdown::Both => 3, - }, - 0, - 0, - 0, - ], - } - } -} - -/// Return a `Connection` to the Network server. This server provides all -/// OS-level networking functions. -pub(crate) fn net_server() -> Connection { - static NET_CONNECTION: AtomicU32 = AtomicU32::new(0); - let cid = NET_CONNECTION.load(Ordering::Relaxed); - if cid != 0 { - return cid.into(); - } - - let cid = connect("_Middleware Network Server_").unwrap(); - NET_CONNECTION.store(cid.into(), Ordering::Relaxed); - cid -} diff --git a/library/std/src/os/xous/services/systime.rs b/library/std/src/os/xous/services/systime.rs deleted file mode 100644 index bbb875c69426e..0000000000000 --- a/library/std/src/os/xous/services/systime.rs +++ /dev/null @@ -1,28 +0,0 @@ -use crate::os::xous::ffi::{connect, Connection}; -use core::sync::atomic::{AtomicU32, Ordering}; - -pub(crate) enum SystimeScalar { - GetUtcTimeMs, -} - -impl Into<[usize; 5]> for SystimeScalar { - fn into(self) -> [usize; 5] { - match self { - SystimeScalar::GetUtcTimeMs => [3, 0, 0, 0, 0], - } - } -} - -/// Return a `Connection` to the systime server. This server is used for reporting the -/// realtime clock. -pub(crate) fn systime_server() -> Connection { - static SYSTIME_SERVER_CONNECTION: AtomicU32 = AtomicU32::new(0); - let cid = SYSTIME_SERVER_CONNECTION.load(Ordering::Relaxed); - if cid != 0 { - return cid.into(); - } - - let cid = connect("timeserverpublic".try_into().unwrap()).unwrap(); - SYSTIME_SERVER_CONNECTION.store(cid.into(), Ordering::Relaxed); - cid -} diff --git a/library/std/src/os/xous/services/ticktimer.rs b/library/std/src/os/xous/services/ticktimer.rs deleted file mode 100644 index 7759303fdbe23..0000000000000 --- a/library/std/src/os/xous/services/ticktimer.rs +++ /dev/null @@ -1,42 +0,0 @@ -use crate::os::xous::ffi::Connection; -use core::sync::atomic::{AtomicU32, Ordering}; - -pub(crate) enum TicktimerScalar { - ElapsedMs, - SleepMs(usize), - LockMutex(usize /* cookie */), - UnlockMutex(usize /* cookie */), - WaitForCondition(usize /* cookie */, usize /* timeout (ms) */), - NotifyCondition(usize /* cookie */, usize /* count */), - FreeMutex(usize /* cookie */), - FreeCondition(usize /* cookie */), -} - -impl Into<[usize; 5]> for TicktimerScalar { - fn into(self) -> [usize; 5] { - match self { - TicktimerScalar::ElapsedMs => [0, 0, 0, 0, 0], - TicktimerScalar::SleepMs(msecs) => [1, msecs, 0, 0, 0], - TicktimerScalar::LockMutex(cookie) => [6, cookie, 0, 0, 0], - TicktimerScalar::UnlockMutex(cookie) => [7, cookie, 0, 0, 0], - TicktimerScalar::WaitForCondition(cookie, timeout_ms) => [8, cookie, timeout_ms, 0, 0], - TicktimerScalar::NotifyCondition(cookie, count) => [9, cookie, count, 0, 0], - TicktimerScalar::FreeMutex(cookie) => [10, cookie, 0, 0, 0], - TicktimerScalar::FreeCondition(cookie) => [11, cookie, 0, 0, 0], - } - } -} - -/// Return a `Connection` to the ticktimer server. This server is used for synchronization -/// primitives such as sleep, Mutex, and Condvar. -pub(crate) fn ticktimer_server() -> Connection { - static TICKTIMER_SERVER_CONNECTION: AtomicU32 = AtomicU32::new(0); - let cid = TICKTIMER_SERVER_CONNECTION.load(Ordering::Relaxed); - if cid != 0 { - return cid.into(); - } - - let cid = crate::os::xous::ffi::connect("ticktimer-server".try_into().unwrap()).unwrap(); - TICKTIMER_SERVER_CONNECTION.store(cid.into(), Ordering::Relaxed); - cid -} diff --git a/library/std/src/panic.rs b/library/std/src/panic.rs deleted file mode 100644 index e63b46ab70548..0000000000000 --- a/library/std/src/panic.rs +++ /dev/null @@ -1,330 +0,0 @@ -//! Panic support in the standard library. - -#![stable(feature = "std_panic", since = "1.9.0")] - -use crate::any::Any; -use crate::collections; -use crate::panicking; -use crate::sync::atomic::{AtomicU8, Ordering}; -use crate::sync::{Condvar, Mutex, RwLock}; -use crate::thread::Result; - -#[doc(hidden)] -#[unstable(feature = "edition_panic", issue = "none", reason = "use panic!() instead")] -#[allow_internal_unstable(libstd_sys_internals, const_format_args, panic_internals, rt)] -#[cfg_attr(not(test), rustc_diagnostic_item = "std_panic_2015_macro")] -#[rustc_macro_transparency = "semitransparent"] -pub macro panic_2015 { - () => ({ - $crate::rt::begin_panic("explicit panic") - }), - ($msg:expr $(,)?) => ({ - $crate::rt::begin_panic($msg); - }), - // Special-case the single-argument case for const_panic. - ("{}", $arg:expr $(,)?) => ({ - $crate::rt::panic_display(&$arg); - }), - ($fmt:expr, $($arg:tt)+) => ({ - // Semicolon to prevent temporaries inside the formatting machinery from - // being considered alive in the caller after the panic_fmt call. - $crate::rt::panic_fmt($crate::const_format_args!($fmt, $($arg)+)); - }), -} - -#[doc(hidden)] -#[unstable(feature = "edition_panic", issue = "none", reason = "use panic!() instead")] -pub use core::panic::panic_2021; - -#[stable(feature = "panic_hooks", since = "1.10.0")] -pub use crate::panicking::{set_hook, take_hook}; - -#[unstable(feature = "panic_update_hook", issue = "92649")] -pub use crate::panicking::update_hook; - -#[stable(feature = "panic_hooks", since = "1.10.0")] -pub use core::panic::{Location, PanicInfo}; - -#[stable(feature = "catch_unwind", since = "1.9.0")] -pub use core::panic::{AssertUnwindSafe, RefUnwindSafe, UnwindSafe}; - -/// Panic the current thread with the given message as the panic payload. -/// -/// The message can be of any (`Any + Send`) type, not just strings. -/// -/// The message is wrapped in a `Box<'static + Any + Send>`, which can be -/// accessed later using [`PanicInfo::payload`]. -/// -/// See the [`panic!`] macro for more information about panicking. -#[stable(feature = "panic_any", since = "1.51.0")] -#[inline] -#[track_caller] -pub fn panic_any(msg: M) -> ! { - crate::panicking::begin_panic(msg); -} - -#[stable(feature = "catch_unwind", since = "1.9.0")] -impl UnwindSafe for Mutex {} -#[stable(feature = "catch_unwind", since = "1.9.0")] -impl UnwindSafe for RwLock {} -#[stable(feature = "catch_unwind", since = "1.9.0")] -impl UnwindSafe for Condvar {} - -#[stable(feature = "unwind_safe_lock_refs", since = "1.12.0")] -impl RefUnwindSafe for Mutex {} -#[stable(feature = "unwind_safe_lock_refs", since = "1.12.0")] -impl RefUnwindSafe for RwLock {} -#[stable(feature = "unwind_safe_lock_refs", since = "1.12.0")] -impl RefUnwindSafe for Condvar {} - -// https://github.com/rust-lang/rust/issues/62301 -#[stable(feature = "hashbrown", since = "1.36.0")] -impl UnwindSafe for collections::HashMap -where - K: UnwindSafe, - V: UnwindSafe, - S: UnwindSafe, -{ -} - -/// Invokes a closure, capturing the cause of an unwinding panic if one occurs. -/// -/// This function will return `Ok` with the closure's result if the closure -/// does not panic, and will return `Err(cause)` if the closure panics. The -/// `cause` returned is the object with which panic was originally invoked. -/// -/// It is currently undefined behavior to unwind from Rust code into foreign -/// code, so this function is particularly useful when Rust is called from -/// another language (normally C). This can run arbitrary Rust code, capturing a -/// panic and allowing a graceful handling of the error. -/// -/// It is **not** recommended to use this function for a general try/catch -/// mechanism. The [`Result`] type is more appropriate to use for functions that -/// can fail on a regular basis. Additionally, this function is not guaranteed -/// to catch all panics, see the "Notes" section below. -/// -/// The closure provided is required to adhere to the [`UnwindSafe`] trait to ensure -/// that all captured variables are safe to cross this boundary. The purpose of -/// this bound is to encode the concept of [exception safety][rfc] in the type -/// system. Most usage of this function should not need to worry about this -/// bound as programs are naturally unwind safe without `unsafe` code. If it -/// becomes a problem the [`AssertUnwindSafe`] wrapper struct can be used to quickly -/// assert that the usage here is indeed unwind safe. -/// -/// [rfc]: https://github.com/rust-lang/rfcs/blob/master/text/1236-stabilize-catch-panic.md -/// -/// # Notes -/// -/// Note that this function **might not catch all panics** in Rust. A panic in -/// Rust is not always implemented via unwinding, but can be implemented by -/// aborting the process as well. This function *only* catches unwinding panics, -/// not those that abort the process. -/// -/// Note that if a custom panic hook has been set, it will be invoked before -/// the panic is caught, before unwinding. -/// -/// Also note that unwinding into Rust code with a foreign exception (e.g. -/// an exception thrown from C++ code) is undefined behavior. -/// -/// Finally, be **careful in how you drop the result of this function**. -/// If it is `Err`, it contains the panic payload, and dropping that may in turn panic! -/// -/// # Examples -/// -/// ``` -/// use std::panic; -/// -/// let result = panic::catch_unwind(|| { -/// println!("hello!"); -/// }); -/// assert!(result.is_ok()); -/// -/// let result = panic::catch_unwind(|| { -/// panic!("oh no!"); -/// }); -/// assert!(result.is_err()); -/// ``` -#[stable(feature = "catch_unwind", since = "1.9.0")] -pub fn catch_unwind R + UnwindSafe, R>(f: F) -> Result { - unsafe { panicking::r#try(f) } -} - -/// Triggers a panic without invoking the panic hook. -/// -/// This is designed to be used in conjunction with [`catch_unwind`] to, for -/// example, carry a panic across a layer of C code. -/// -/// # Notes -/// -/// Note that panics in Rust are not always implemented via unwinding, but they -/// may be implemented by aborting the process. If this function is called when -/// panics are implemented this way then this function will abort the process, -/// not trigger an unwind. -/// -/// # Examples -/// -/// ```should_panic -/// use std::panic; -/// -/// let result = panic::catch_unwind(|| { -/// panic!("oh no!"); -/// }); -/// -/// if let Err(err) = result { -/// panic::resume_unwind(err); -/// } -/// ``` -#[stable(feature = "resume_unwind", since = "1.9.0")] -pub fn resume_unwind(payload: Box) -> ! { - panicking::rust_panic_without_hook(payload) -} - -/// Make all future panics abort directly without running the panic hook or unwinding. -/// -/// There is no way to undo this; the effect lasts until the process exits or -/// execs (or the equivalent). -/// -/// # Use after fork -/// -/// This function is particularly useful for calling after `libc::fork`. After `fork`, in a -/// multithreaded program it is (on many platforms) not safe to call the allocator. It is also -/// generally highly undesirable for an unwind to unwind past the `fork`, because that results in -/// the unwind propagating to code that was only ever expecting to run in the parent. -/// -/// `panic::always_abort()` helps avoid both of these. It directly avoids any further unwinding, -/// and if there is a panic, the abort will occur without allocating provided that the arguments to -/// panic can be formatted without allocating. -/// -/// Examples -/// -/// ```no_run -/// #![feature(panic_always_abort)] -/// use std::panic; -/// -/// panic::always_abort(); -/// -/// let _ = panic::catch_unwind(|| { -/// panic!("inside the catch"); -/// }); -/// -/// // We will have aborted already, due to the panic. -/// unreachable!(); -/// ``` -#[unstable(feature = "panic_always_abort", issue = "84438")] -pub fn always_abort() { - crate::panicking::panic_count::set_always_abort(); -} - -/// The configuration for whether and how the default panic hook will capture -/// and display the backtrace. -#[derive(Debug, Copy, Clone, PartialEq, Eq)] -#[unstable(feature = "panic_backtrace_config", issue = "93346")] -#[non_exhaustive] -pub enum BacktraceStyle { - /// Prints a terser backtrace which ideally only contains relevant - /// information. - Short, - /// Prints a backtrace with all possible information. - Full, - /// Disable collecting and displaying backtraces. - Off, -} - -impl BacktraceStyle { - pub(crate) fn full() -> Option { - if cfg!(feature = "backtrace") { Some(BacktraceStyle::Full) } else { None } - } - - fn as_u8(self) -> u8 { - match self { - BacktraceStyle::Short => 1, - BacktraceStyle::Full => 2, - BacktraceStyle::Off => 3, - } - } - - fn from_u8(s: u8) -> Option { - Some(match s { - 0 => return None, - 1 => BacktraceStyle::Short, - 2 => BacktraceStyle::Full, - 3 => BacktraceStyle::Off, - _ => unreachable!(), - }) - } -} - -// Tracks whether we should/can capture a backtrace, and how we should display -// that backtrace. -// -// Internally stores equivalent of an Option. -static SHOULD_CAPTURE: AtomicU8 = AtomicU8::new(0); - -/// Configure whether the default panic hook will capture and display a -/// backtrace. -/// -/// The default value for this setting may be set by the `RUST_BACKTRACE` -/// environment variable; see the details in [`get_backtrace_style`]. -#[unstable(feature = "panic_backtrace_config", issue = "93346")] -pub fn set_backtrace_style(style: BacktraceStyle) { - if !cfg!(feature = "backtrace") { - // If the `backtrace` feature of this crate isn't enabled, skip setting. - return; - } - SHOULD_CAPTURE.store(style.as_u8(), Ordering::Release); -} - -/// Checks whether the standard library's panic hook will capture and print a -/// backtrace. -/// -/// This function will, if a backtrace style has not been set via -/// [`set_backtrace_style`], read the environment variable `RUST_BACKTRACE` to -/// determine a default value for the backtrace formatting: -/// -/// The first call to `get_backtrace_style` may read the `RUST_BACKTRACE` -/// environment variable if `set_backtrace_style` has not been called to -/// override the default value. After a call to `set_backtrace_style` or -/// `get_backtrace_style`, any changes to `RUST_BACKTRACE` will have no effect. -/// -/// `RUST_BACKTRACE` is read according to these rules: -/// -/// * `0` for `BacktraceStyle::Off` -/// * `full` for `BacktraceStyle::Full` -/// * `1` for `BacktraceStyle::Short` -/// * Other values are currently `BacktraceStyle::Short`, but this may change in -/// the future -/// -/// Returns `None` if backtraces aren't currently supported. -#[unstable(feature = "panic_backtrace_config", issue = "93346")] -pub fn get_backtrace_style() -> Option { - if !cfg!(feature = "backtrace") { - // If the `backtrace` feature of this crate isn't enabled quickly return - // `Unsupported` so this can be constant propagated all over the place - // to optimize away callers. - return None; - } - if let Some(style) = BacktraceStyle::from_u8(SHOULD_CAPTURE.load(Ordering::Acquire)) { - return Some(style); - } - - let format = crate::env::var_os("RUST_BACKTRACE") - .map(|x| { - if &x == "0" { - BacktraceStyle::Off - } else if &x == "full" { - BacktraceStyle::Full - } else { - BacktraceStyle::Short - } - }) - .unwrap_or(if crate::sys::FULL_BACKTRACE_DEFAULT { - BacktraceStyle::Full - } else { - BacktraceStyle::Off - }); - set_backtrace_style(format); - Some(format) -} - -#[cfg(test)] -mod tests; diff --git a/library/std/src/panic/tests.rs b/library/std/src/panic/tests.rs deleted file mode 100644 index b37d74011cc67..0000000000000 --- a/library/std/src/panic/tests.rs +++ /dev/null @@ -1,56 +0,0 @@ -#![allow(dead_code)] - -use crate::cell::RefCell; -use crate::panic::{AssertUnwindSafe, UnwindSafe}; -use crate::rc::Rc; -use crate::sync::{Arc, Mutex, RwLock}; - -struct Foo { - a: i32, -} - -fn assert() {} - -#[test] -fn panic_safety_traits() { - assert::(); - assert::<&i32>(); - assert::<*mut i32>(); - assert::<*const i32>(); - assert::(); - assert::(); - assert::<&str>(); - assert::(); - assert::<&Foo>(); - assert::>(); - assert::(); - assert::>(); - assert::>(); - assert::>(); - assert::>(); - assert::<&Mutex>(); - assert::<&RwLock>(); - assert::>(); - assert::>(); - assert::>(); - - { - trait Trait: UnwindSafe {} - assert::>(); - } - - fn bar() { - assert::>(); - assert::>(); - } - - fn baz() { - assert::>(); - assert::>(); - assert::>(); - assert::>(); - assert::<&AssertUnwindSafe>(); - assert::>>(); - assert::>>(); - } -} diff --git a/library/std/src/panicking.rs b/library/std/src/panicking.rs deleted file mode 100644 index 5699937cdb49b..0000000000000 --- a/library/std/src/panicking.rs +++ /dev/null @@ -1,857 +0,0 @@ -//! Implementation of various bits and pieces of the `panic!` macro and -//! associated runtime pieces. -//! -//! Specifically, this module contains the implementation of: -//! -//! * Panic hooks -//! * Executing a panic up to doing the actual implementation -//! * Shims around "try" - -#![deny(unsafe_op_in_unsafe_fn)] - -use crate::panic::BacktraceStyle; -use core::panic::{Location, PanicInfo, PanicPayload}; - -use crate::any::Any; -use crate::fmt; -use crate::intrinsics; -use crate::mem::{self, ManuallyDrop}; -use crate::process; -use crate::sync::atomic::{AtomicBool, Ordering}; -use crate::sync::{PoisonError, RwLock}; -use crate::sys::stdio::panic_output; -use crate::sys_common::backtrace; -use crate::thread; - -#[cfg(not(test))] -use crate::io::try_set_output_capture; -// make sure to use the stderr output configured -// by libtest in the real copy of std -#[cfg(test)] -use realstd::io::try_set_output_capture; - -// Binary interface to the panic runtime that the standard library depends on. -// -// The standard library is tagged with `#![needs_panic_runtime]` (introduced in -// RFC 1513) to indicate that it requires some other crate tagged with -// `#![panic_runtime]` to exist somewhere. Each panic runtime is intended to -// implement these symbols (with the same signatures) so we can get matched up -// to them. -// -// One day this may look a little less ad-hoc with the compiler helping out to -// hook up these functions, but it is not this day! -#[allow(improper_ctypes)] -extern "C" { - fn __rust_panic_cleanup(payload: *mut u8) -> *mut (dyn Any + Send + 'static); -} - -extern "Rust" { - /// `PanicPayload` lazily performs allocation only when needed (this avoids - /// allocations when using the "abort" panic runtime). - fn __rust_start_panic(payload: &mut dyn PanicPayload) -> u32; -} - -/// This function is called by the panic runtime if FFI code catches a Rust -/// panic but doesn't rethrow it. We don't support this case since it messes -/// with our panic count. -#[cfg(not(test))] -#[rustc_std_internal_symbol] -extern "C" fn __rust_drop_panic() -> ! { - rtabort!("Rust panics must be rethrown"); -} - -/// This function is called by the panic runtime if it catches an exception -/// object which does not correspond to a Rust panic. -#[cfg(not(test))] -#[rustc_std_internal_symbol] -extern "C" fn __rust_foreign_exception() -> ! { - rtabort!("Rust cannot catch foreign exceptions"); -} - -enum Hook { - Default, - Custom(Box) + 'static + Sync + Send>), -} - -impl Hook { - #[inline] - fn into_box(self) -> Box) + 'static + Sync + Send> { - match self { - Hook::Default => Box::new(default_hook), - Hook::Custom(hook) => hook, - } - } -} - -impl Default for Hook { - #[inline] - fn default() -> Hook { - Hook::Default - } -} - -static HOOK: RwLock = RwLock::new(Hook::Default); - -/// Registers a custom panic hook, replacing the previously registered hook. -/// -/// The panic hook is invoked when a thread panics, but before the panic runtime -/// is invoked. As such, the hook will run with both the aborting and unwinding -/// runtimes. -/// -/// The default hook, which is registered at startup, prints a message to standard error and -/// generates a backtrace if requested. This behavior can be customized using the `set_hook` function. -/// The current hook can be retrieved while reinstating the default hook with the [`take_hook`] -/// function. -/// -/// [`take_hook`]: ./fn.take_hook.html -/// -/// The hook is provided with a `PanicInfo` struct which contains information -/// about the origin of the panic, including the payload passed to `panic!` and -/// the source code location from which the panic originated. -/// -/// The panic hook is a global resource. -/// -/// # Panics -/// -/// Panics if called from a panicking thread. -/// -/// # Examples -/// -/// The following will print "Custom panic hook": -/// -/// ```should_panic -/// use std::panic; -/// -/// panic::set_hook(Box::new(|_| { -/// println!("Custom panic hook"); -/// })); -/// -/// panic!("Normal panic"); -/// ``` -#[stable(feature = "panic_hooks", since = "1.10.0")] -pub fn set_hook(hook: Box) + 'static + Sync + Send>) { - if thread::panicking() { - panic!("cannot modify the panic hook from a panicking thread"); - } - - let new = Hook::Custom(hook); - let mut hook = HOOK.write().unwrap_or_else(PoisonError::into_inner); - let old = mem::replace(&mut *hook, new); - drop(hook); - // Only drop the old hook after releasing the lock to avoid deadlocking - // if its destructor panics. - drop(old); -} - -/// Unregisters the current panic hook and returns it, registering the default hook -/// in its place. -/// -/// *See also the function [`set_hook`].* -/// -/// [`set_hook`]: ./fn.set_hook.html -/// -/// If the default hook is registered it will be returned, but remain registered. -/// -/// # Panics -/// -/// Panics if called from a panicking thread. -/// -/// # Examples -/// -/// The following will print "Normal panic": -/// -/// ```should_panic -/// use std::panic; -/// -/// panic::set_hook(Box::new(|_| { -/// println!("Custom panic hook"); -/// })); -/// -/// let _ = panic::take_hook(); -/// -/// panic!("Normal panic"); -/// ``` -#[must_use] -#[stable(feature = "panic_hooks", since = "1.10.0")] -pub fn take_hook() -> Box) + 'static + Sync + Send> { - if thread::panicking() { - panic!("cannot modify the panic hook from a panicking thread"); - } - - let mut hook = HOOK.write().unwrap_or_else(PoisonError::into_inner); - let old_hook = mem::take(&mut *hook); - drop(hook); - - old_hook.into_box() -} - -/// Atomic combination of [`take_hook`] and [`set_hook`]. Use this to replace the panic handler with -/// a new panic handler that does something and then executes the old handler. -/// -/// [`take_hook`]: ./fn.take_hook.html -/// [`set_hook`]: ./fn.set_hook.html -/// -/// # Panics -/// -/// Panics if called from a panicking thread. -/// -/// # Examples -/// -/// The following will print the custom message, and then the normal output of panic. -/// -/// ```should_panic -/// #![feature(panic_update_hook)] -/// use std::panic; -/// -/// // Equivalent to -/// // let prev = panic::take_hook(); -/// // panic::set_hook(move |info| { -/// // println!("..."); -/// // prev(info); -/// // ); -/// panic::update_hook(move |prev, info| { -/// println!("Print custom message and execute panic handler as usual"); -/// prev(info); -/// }); -/// -/// panic!("Custom and then normal"); -/// ``` -#[unstable(feature = "panic_update_hook", issue = "92649")] -pub fn update_hook(hook_fn: F) -where - F: Fn(&(dyn Fn(&PanicInfo<'_>) + Send + Sync + 'static), &PanicInfo<'_>) - + Sync - + Send - + 'static, -{ - if thread::panicking() { - panic!("cannot modify the panic hook from a panicking thread"); - } - - let mut hook = HOOK.write().unwrap_or_else(PoisonError::into_inner); - let prev = mem::take(&mut *hook).into_box(); - *hook = Hook::Custom(Box::new(move |info| hook_fn(&prev, info))); -} - -/// The default panic handler. -fn default_hook(info: &PanicInfo<'_>) { - // If this is a double panic, make sure that we print a backtrace - // for this panic. Otherwise only print it if logging is enabled. - let backtrace = if info.force_no_backtrace() { - None - } else if panic_count::get_count() >= 2 { - BacktraceStyle::full() - } else { - crate::panic::get_backtrace_style() - }; - - // The current implementation always returns `Some`. - let location = info.location().unwrap(); - - let msg = match info.payload().downcast_ref::<&'static str>() { - Some(s) => *s, - None => match info.payload().downcast_ref::() { - Some(s) => &s[..], - None => "Box", - }, - }; - let thread = thread::try_current(); - let name = thread.as_ref().and_then(|t| t.name()).unwrap_or(""); - - let write = |err: &mut dyn crate::io::Write| { - let _ = writeln!(err, "thread '{name}' panicked at {location}:\n{msg}"); - - static FIRST_PANIC: AtomicBool = AtomicBool::new(true); - - match backtrace { - Some(BacktraceStyle::Short) => { - drop(backtrace::print(err, crate::backtrace_rs::PrintFmt::Short)) - } - Some(BacktraceStyle::Full) => { - drop(backtrace::print(err, crate::backtrace_rs::PrintFmt::Full)) - } - Some(BacktraceStyle::Off) => { - if FIRST_PANIC.swap(false, Ordering::Relaxed) { - let _ = writeln!( - err, - "note: run with `RUST_BACKTRACE=1` environment variable to display a \ - backtrace" - ); - if cfg!(miri) { - let _ = writeln!( - err, - "note: in Miri, you may have to set `-Zmiri-env-forward=RUST_BACKTRACE` \ - for the environment variable to have an effect" - ); - } - } - } - // If backtraces aren't supported or are forced-off, do nothing. - None => {} - } - }; - - if let Ok(Some(local)) = try_set_output_capture(None) { - write(&mut *local.lock().unwrap_or_else(|e| e.into_inner())); - try_set_output_capture(Some(local)).ok(); - } else if let Some(mut out) = panic_output() { - write(&mut out); - } -} - -#[cfg(not(test))] -#[doc(hidden)] -#[cfg(feature = "panic_immediate_abort")] -#[unstable(feature = "update_panic_count", issue = "none")] -pub mod panic_count { - /// A reason for forcing an immediate abort on panic. - #[derive(Debug)] - pub enum MustAbort { - AlwaysAbort, - PanicInHook, - } - - #[inline] - pub fn increase(run_panic_hook: bool) -> Option { - None - } - - #[inline] - pub fn finished_panic_hook() {} - - #[inline] - pub fn decrease() {} - - #[inline] - pub fn set_always_abort() {} - - // Disregards ALWAYS_ABORT_FLAG - #[inline] - #[must_use] - pub fn get_count() -> usize { - 0 - } - - #[must_use] - #[inline] - pub fn count_is_zero() -> bool { - true - } -} - -#[cfg(not(test))] -#[doc(hidden)] -#[cfg(not(feature = "panic_immediate_abort"))] -#[unstable(feature = "update_panic_count", issue = "none")] -pub mod panic_count { - use crate::cell::Cell; - use crate::sync::atomic::{AtomicUsize, Ordering}; - - const ALWAYS_ABORT_FLAG: usize = 1 << (usize::BITS - 1); - - /// A reason for forcing an immediate abort on panic. - #[derive(Debug)] - pub enum MustAbort { - AlwaysAbort, - PanicInHook, - } - - // Panic count for the current thread and whether a panic hook is currently - // being executed.. - thread_local! { - static LOCAL_PANIC_COUNT: Cell<(usize, bool)> = const { Cell::new((0, false)) } - } - - // Sum of panic counts from all threads. The purpose of this is to have - // a fast path in `count_is_zero` (which is used by `panicking`). In any particular - // thread, if that thread currently views `GLOBAL_PANIC_COUNT` as being zero, - // then `LOCAL_PANIC_COUNT` in that thread is zero. This invariant holds before - // and after increase and decrease, but not necessarily during their execution. - // - // Additionally, the top bit of GLOBAL_PANIC_COUNT (GLOBAL_ALWAYS_ABORT_FLAG) - // records whether panic::always_abort() has been called. This can only be - // set, never cleared. - // panic::always_abort() is usually called to prevent memory allocations done by - // the panic handling in the child created by `libc::fork`. - // Memory allocations performed in a child created with `libc::fork` are undefined - // behavior in most operating systems. - // Accessing LOCAL_PANIC_COUNT in a child created by `libc::fork` would lead to a memory - // allocation. Only GLOBAL_PANIC_COUNT can be accessed in this situation. This is - // sufficient because a child process will always have exactly one thread only. - // See also #85261 for details. - // - // This could be viewed as a struct containing a single bit and an n-1-bit - // value, but if we wrote it like that it would be more than a single word, - // and even a newtype around usize would be clumsy because we need atomics. - // But we use such a tuple for the return type of increase(). - // - // Stealing a bit is fine because it just amounts to assuming that each - // panicking thread consumes at least 2 bytes of address space. - static GLOBAL_PANIC_COUNT: AtomicUsize = AtomicUsize::new(0); - - // Increases the global and local panic count, and returns whether an - // immediate abort is required. - // - // This also updates thread-local state to keep track of whether a panic - // hook is currently executing. - pub fn increase(run_panic_hook: bool) -> Option { - let global_count = GLOBAL_PANIC_COUNT.fetch_add(1, Ordering::Relaxed); - if global_count & ALWAYS_ABORT_FLAG != 0 { - // Do *not* access thread-local state, we might be after a `fork`. - return Some(MustAbort::AlwaysAbort); - } - - LOCAL_PANIC_COUNT.with(|c| { - let (count, in_panic_hook) = c.get(); - if in_panic_hook { - return Some(MustAbort::PanicInHook); - } - c.set((count + 1, run_panic_hook)); - None - }) - } - - pub fn finished_panic_hook() { - LOCAL_PANIC_COUNT.with(|c| { - let (count, _) = c.get(); - c.set((count, false)); - }); - } - - pub fn decrease() { - GLOBAL_PANIC_COUNT.fetch_sub(1, Ordering::Relaxed); - LOCAL_PANIC_COUNT.with(|c| { - let (count, _) = c.get(); - c.set((count - 1, false)); - }); - } - - pub fn set_always_abort() { - GLOBAL_PANIC_COUNT.fetch_or(ALWAYS_ABORT_FLAG, Ordering::Relaxed); - } - - // Disregards ALWAYS_ABORT_FLAG - #[must_use] - pub fn get_count() -> usize { - LOCAL_PANIC_COUNT.with(|c| c.get().0) - } - - // Disregards ALWAYS_ABORT_FLAG - #[must_use] - #[inline] - pub fn count_is_zero() -> bool { - if GLOBAL_PANIC_COUNT.load(Ordering::Relaxed) & !ALWAYS_ABORT_FLAG == 0 { - // Fast path: if `GLOBAL_PANIC_COUNT` is zero, all threads - // (including the current one) will have `LOCAL_PANIC_COUNT` - // equal to zero, so TLS access can be avoided. - // - // In terms of performance, a relaxed atomic load is similar to a normal - // aligned memory read (e.g., a mov instruction in x86), but with some - // compiler optimization restrictions. On the other hand, a TLS access - // might require calling a non-inlinable function (such as `__tls_get_addr` - // when using the GD TLS model). - true - } else { - is_zero_slow_path() - } - } - - // Slow path is in a separate function to reduce the amount of code - // inlined from `count_is_zero`. - #[inline(never)] - #[cold] - fn is_zero_slow_path() -> bool { - LOCAL_PANIC_COUNT.with(|c| c.get().0 == 0) - } -} - -#[cfg(test)] -pub use realstd::rt::panic_count; - -/// Invoke a closure, capturing the cause of an unwinding panic if one occurs. -#[cfg(feature = "panic_immediate_abort")] -pub unsafe fn r#try R>(f: F) -> Result> { - Ok(f()) -} - -/// Invoke a closure, capturing the cause of an unwinding panic if one occurs. -#[cfg(not(feature = "panic_immediate_abort"))] -pub unsafe fn r#try R>(f: F) -> Result> { - union Data { - f: ManuallyDrop, - r: ManuallyDrop, - p: ManuallyDrop>, - } - - // We do some sketchy operations with ownership here for the sake of - // performance. We can only pass pointers down to `do_call` (can't pass - // objects by value), so we do all the ownership tracking here manually - // using a union. - // - // We go through a transition where: - // - // * First, we set the data field `f` to be the argumentless closure that we're going to call. - // * When we make the function call, the `do_call` function below, we take - // ownership of the function pointer. At this point the `data` union is - // entirely uninitialized. - // * If the closure successfully returns, we write the return value into the - // data's return slot (field `r`). - // * If the closure panics (`do_catch` below), we write the panic payload into field `p`. - // * Finally, when we come back out of the `try` intrinsic we're - // in one of two states: - // - // 1. The closure didn't panic, in which case the return value was - // filled in. We move it out of `data.r` and return it. - // 2. The closure panicked, in which case the panic payload was - // filled in. We move it out of `data.p` and return it. - // - // Once we stack all that together we should have the "most efficient' - // method of calling a catch panic whilst juggling ownership. - let mut data = Data { f: ManuallyDrop::new(f) }; - - let data_ptr = core::ptr::addr_of_mut!(data) as *mut u8; - // SAFETY: - // - // Access to the union's fields: this is `std` and we know that the `r#try` - // intrinsic fills in the `r` or `p` union field based on its return value. - // - // The call to `intrinsics::catch_unwind` is made safe by: - // - `do_call`, the first argument, can be called with the initial `data_ptr`. - // - `do_catch`, the second argument, can be called with the `data_ptr` as well. - // See their safety preconditions for more information - unsafe { - return if intrinsics::catch_unwind(do_call::, data_ptr, do_catch::) == 0 { - Ok(ManuallyDrop::into_inner(data.r)) - } else { - Err(ManuallyDrop::into_inner(data.p)) - }; - } - - // We consider unwinding to be rare, so mark this function as cold. However, - // do not mark it no-inline -- that decision is best to leave to the - // optimizer (in most cases this function is not inlined even as a normal, - // non-cold function, though, as of the writing of this comment). - #[cold] - unsafe fn cleanup(payload: *mut u8) -> Box { - // SAFETY: The whole unsafe block hinges on a correct implementation of - // the panic handler `__rust_panic_cleanup`. As such we can only - // assume it returns the correct thing for `Box::from_raw` to work - // without undefined behavior. - let obj = unsafe { Box::from_raw(__rust_panic_cleanup(payload)) }; - panic_count::decrease(); - obj - } - - // SAFETY: - // data must be non-NUL, correctly aligned, and a pointer to a `Data` - // Its must contains a valid `f` (type: F) value that can be use to fill - // `data.r`. - // - // This function cannot be marked as `unsafe` because `intrinsics::catch_unwind` - // expects normal function pointers. - #[inline] - fn do_call R, R>(data: *mut u8) { - // SAFETY: this is the responsibility of the caller, see above. - unsafe { - let data = data as *mut Data; - let data = &mut (*data); - let f = ManuallyDrop::take(&mut data.f); - data.r = ManuallyDrop::new(f()); - } - } - - // We *do* want this part of the catch to be inlined: this allows the - // compiler to properly track accesses to the Data union and optimize it - // away most of the time. - // - // SAFETY: - // data must be non-NUL, correctly aligned, and a pointer to a `Data` - // Since this uses `cleanup` it also hinges on a correct implementation of - // `__rustc_panic_cleanup`. - // - // This function cannot be marked as `unsafe` because `intrinsics::catch_unwind` - // expects normal function pointers. - #[inline] - #[rustc_nounwind] // `intrinsic::r#try` requires catch fn to be nounwind - fn do_catch R, R>(data: *mut u8, payload: *mut u8) { - // SAFETY: this is the responsibility of the caller, see above. - // - // When `__rustc_panic_cleaner` is correctly implemented we can rely - // on `obj` being the correct thing to pass to `data.p` (after wrapping - // in `ManuallyDrop`). - unsafe { - let data = data as *mut Data; - let data = &mut (*data); - let obj = cleanup(payload); - data.p = ManuallyDrop::new(obj); - } - } -} - -/// Determines whether the current thread is unwinding because of panic. -#[inline] -pub fn panicking() -> bool { - !panic_count::count_is_zero() -} - -/// Entry point of panics from the core crate (`panic_impl` lang item). -#[cfg(not(any(test, doctest)))] -#[panic_handler] -pub fn begin_panic_handler(info: &PanicInfo<'_>) -> ! { - struct FormatStringPayload<'a> { - inner: &'a fmt::Arguments<'a>, - string: Option, - } - - impl<'a> FormatStringPayload<'a> { - fn new(inner: &'a fmt::Arguments<'a>) -> Self { - Self { inner, string: None } - } - - fn fill(&mut self) -> &mut String { - use crate::fmt::Write; - - let inner = self.inner; - // Lazily, the first time this gets called, run the actual string formatting. - self.string.get_or_insert_with(|| { - let mut s = String::new(); - let _err = s.write_fmt(*inner); - s - }) - } - } - - unsafe impl<'a> PanicPayload for FormatStringPayload<'a> { - fn take_box(&mut self) -> *mut (dyn Any + Send) { - // We do two allocations here, unfortunately. But (a) they're required with the current - // scheme, and (b) we don't handle panic + OOM properly anyway (see comment in - // begin_panic below). - let contents = mem::take(self.fill()); - Box::into_raw(Box::new(contents)) - } - - fn get(&mut self) -> &(dyn Any + Send) { - self.fill() - } - } - - struct StaticStrPayload(&'static str); - - unsafe impl PanicPayload for StaticStrPayload { - fn take_box(&mut self) -> *mut (dyn Any + Send) { - Box::into_raw(Box::new(self.0)) - } - - fn get(&mut self) -> &(dyn Any + Send) { - &self.0 - } - } - - let loc = info.location().unwrap(); // The current implementation always returns Some - let msg = info.message().unwrap(); // The current implementation always returns Some - crate::sys_common::backtrace::__rust_end_short_backtrace(move || { - // FIXME: can we just pass `info` along rather than taking it apart here, only to have - // `rust_panic_with_hook` construct a new `PanicInfo`? - if let Some(msg) = msg.as_str() { - rust_panic_with_hook( - &mut StaticStrPayload(msg), - info.message(), - loc, - info.can_unwind(), - info.force_no_backtrace(), - ); - } else { - rust_panic_with_hook( - &mut FormatStringPayload::new(msg), - info.message(), - loc, - info.can_unwind(), - info.force_no_backtrace(), - ); - } - }) -} - -/// This is the entry point of panicking for the non-format-string variants of -/// panic!() and assert!(). In particular, this is the only entry point that supports -/// arbitrary payloads, not just format strings. -#[unstable(feature = "libstd_sys_internals", reason = "used by the panic! macro", issue = "none")] -#[cfg_attr(not(any(test, doctest)), lang = "begin_panic")] -// lang item for CTFE panic support -// never inline unless panic_immediate_abort to avoid code -// bloat at the call sites as much as possible -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never), cold)] -#[cfg_attr(feature = "panic_immediate_abort", inline)] -#[track_caller] -#[rustc_do_not_const_check] // hooked by const-eval -pub const fn begin_panic(msg: M) -> ! { - if cfg!(feature = "panic_immediate_abort") { - intrinsics::abort() - } - - let loc = Location::caller(); - return crate::sys_common::backtrace::__rust_end_short_backtrace(move || { - rust_panic_with_hook( - &mut Payload::new(msg), - None, - loc, - /* can_unwind */ true, - /* force_no_backtrace */ false, - ) - }); - - struct Payload { - inner: Option, - } - - impl Payload { - fn new(inner: A) -> Payload { - Payload { inner: Some(inner) } - } - } - - unsafe impl PanicPayload for Payload { - fn take_box(&mut self) -> *mut (dyn Any + Send) { - // Note that this should be the only allocation performed in this code path. Currently - // this means that panic!() on OOM will invoke this code path, but then again we're not - // really ready for panic on OOM anyway. If we do start doing this, then we should - // propagate this allocation to be performed in the parent of this thread instead of the - // thread that's panicking. - let data = match self.inner.take() { - Some(a) => Box::new(a) as Box, - None => process::abort(), - }; - Box::into_raw(data) - } - - fn get(&mut self) -> &(dyn Any + Send) { - match self.inner { - Some(ref a) => a, - None => process::abort(), - } - } - } -} - -/// Central point for dispatching panics. -/// -/// Executes the primary logic for a panic, including checking for recursive -/// panics, panic hooks, and finally dispatching to the panic runtime to either -/// abort or unwind. -fn rust_panic_with_hook( - payload: &mut dyn PanicPayload, - message: Option<&fmt::Arguments<'_>>, - location: &Location<'_>, - can_unwind: bool, - force_no_backtrace: bool, -) -> ! { - let must_abort = panic_count::increase(true); - - // Check if we need to abort immediately. - if let Some(must_abort) = must_abort { - match must_abort { - panic_count::MustAbort::PanicInHook => { - // Don't try to format the message in this case, perhaps that is causing the - // recursive panics. However if the message is just a string, no user-defined - // code is involved in printing it, so that is risk-free. - let msg_str = message.and_then(|m| m.as_str()).map(|m| [m]); - let message = msg_str.as_ref().map(|m| fmt::Arguments::new_const(m)); - let panicinfo = PanicInfo::internal_constructor( - message.as_ref(), - location, - can_unwind, - force_no_backtrace, - ); - rtprintpanic!("{panicinfo}\nthread panicked while processing panic. aborting.\n"); - } - panic_count::MustAbort::AlwaysAbort => { - // Unfortunately, this does not print a backtrace, because creating - // a `Backtrace` will allocate, which we must avoid here. - let panicinfo = PanicInfo::internal_constructor( - message, - location, - can_unwind, - force_no_backtrace, - ); - rtprintpanic!("{panicinfo}\npanicked after panic::always_abort(), aborting.\n"); - } - } - crate::sys::abort_internal(); - } - - let mut info = - PanicInfo::internal_constructor(message, location, can_unwind, force_no_backtrace); - let hook = HOOK.read().unwrap_or_else(PoisonError::into_inner); - match *hook { - // Some platforms (like wasm) know that printing to stderr won't ever actually - // print anything, and if that's the case we can skip the default - // hook. Since string formatting happens lazily when calling `payload` - // methods, this means we avoid formatting the string at all! - // (The panic runtime might still call `payload.take_box()` though and trigger - // formatting.) - Hook::Default if panic_output().is_none() => {} - Hook::Default => { - info.set_payload(payload.get()); - default_hook(&info); - } - Hook::Custom(ref hook) => { - info.set_payload(payload.get()); - hook(&info); - } - }; - drop(hook); - - // Indicate that we have finished executing the panic hook. After this point - // it is fine if there is a panic while executing destructors, as long as it - // it contained within a `catch_unwind`. - panic_count::finished_panic_hook(); - - if !can_unwind { - // If a thread panics while running destructors or tries to unwind - // through a nounwind function (e.g. extern "C") then we cannot continue - // unwinding and have to abort immediately. - rtprintpanic!("thread caused non-unwinding panic. aborting.\n"); - crate::sys::abort_internal(); - } - - rust_panic(payload) -} - -/// This is the entry point for `resume_unwind`. -/// It just forwards the payload to the panic runtime. -#[cfg_attr(feature = "panic_immediate_abort", inline)] -pub fn rust_panic_without_hook(payload: Box) -> ! { - panic_count::increase(false); - - struct RewrapBox(Box); - - unsafe impl PanicPayload for RewrapBox { - fn take_box(&mut self) -> *mut (dyn Any + Send) { - Box::into_raw(mem::replace(&mut self.0, Box::new(()))) - } - - fn get(&mut self) -> &(dyn Any + Send) { - &*self.0 - } - } - - rust_panic(&mut RewrapBox(payload)) -} - -/// An unmangled function (through `rustc_std_internal_symbol`) on which to slap -/// yer breakpoints. -#[inline(never)] -#[cfg_attr(not(test), rustc_std_internal_symbol)] -#[cfg(not(feature = "panic_immediate_abort"))] -fn rust_panic(msg: &mut dyn PanicPayload) -> ! { - let code = unsafe { __rust_start_panic(msg) }; - rtabort!("failed to initiate panic, error {code}") -} - -#[cfg_attr(not(test), rustc_std_internal_symbol)] -#[cfg(feature = "panic_immediate_abort")] -fn rust_panic(_: &mut dyn PanicPayload) -> ! { - unsafe { - crate::intrinsics::abort(); - } -} diff --git a/library/std/src/pat.rs b/library/std/src/pat.rs deleted file mode 100644 index aeddd84c2cb54..0000000000000 --- a/library/std/src/pat.rs +++ /dev/null @@ -1,3 +0,0 @@ -//! Helper module for exporting the `pattern_type` macro - -pub use core::pattern_type; diff --git a/library/std/src/path.rs b/library/std/src/path.rs deleted file mode 100644 index f835b69f0cfb5..0000000000000 --- a/library/std/src/path.rs +++ /dev/null @@ -1,3388 +0,0 @@ -//! Cross-platform path manipulation. -//! -//! This module provides two types, [`PathBuf`] and [`Path`] (akin to [`String`] -//! and [`str`]), for working with paths abstractly. These types are thin wrappers -//! around [`OsString`] and [`OsStr`] respectively, meaning that they work directly -//! on strings according to the local platform's path syntax. -//! -//! Paths can be parsed into [`Component`]s by iterating over the structure -//! returned by the [`components`] method on [`Path`]. [`Component`]s roughly -//! correspond to the substrings between path separators (`/` or `\`). You can -//! reconstruct an equivalent path from components with the [`push`] method on -//! [`PathBuf`]; note that the paths may differ syntactically by the -//! normalization described in the documentation for the [`components`] method. -//! -//! ## Case sensitivity -//! -//! Unless otherwise indicated path methods that do not access the filesystem, -//! such as [`Path::starts_with`] and [`Path::ends_with`], are case sensitive no -//! matter the platform or filesystem. An exception to this is made for Windows -//! drive letters. -//! -//! ## Simple usage -//! -//! Path manipulation includes both parsing components from slices and building -//! new owned paths. -//! -//! To parse a path, you can create a [`Path`] slice from a [`str`] -//! slice and start asking questions: -//! -//! ``` -//! use std::path::Path; -//! use std::ffi::OsStr; -//! -//! let path = Path::new("/tmp/foo/bar.txt"); -//! -//! let parent = path.parent(); -//! assert_eq!(parent, Some(Path::new("/tmp/foo"))); -//! -//! let file_stem = path.file_stem(); -//! assert_eq!(file_stem, Some(OsStr::new("bar"))); -//! -//! let extension = path.extension(); -//! assert_eq!(extension, Some(OsStr::new("txt"))); -//! ``` -//! -//! To build or modify paths, use [`PathBuf`]: -//! -//! ``` -//! use std::path::PathBuf; -//! -//! // This way works... -//! let mut path = PathBuf::from("c:\\"); -//! -//! path.push("windows"); -//! path.push("system32"); -//! -//! path.set_extension("dll"); -//! -//! // ... but push is best used if you don't know everything up -//! // front. If you do, this way is better: -//! let path: PathBuf = ["c:\\", "windows", "system32.dll"].iter().collect(); -//! ``` -//! -//! [`components`]: Path::components -//! [`push`]: PathBuf::push - -#![stable(feature = "rust1", since = "1.0.0")] -#![deny(unsafe_op_in_unsafe_fn)] - -#[cfg(test)] -mod tests; - -use crate::borrow::{Borrow, Cow}; -use crate::cmp; -use crate::collections::TryReserveError; -use crate::error::Error; -use crate::fmt; -use crate::fs; -use crate::hash::{Hash, Hasher}; -use crate::io; -use crate::iter::FusedIterator; -use crate::ops::{self, Deref}; -use crate::rc::Rc; -use crate::str::FromStr; -use crate::sync::Arc; - -use crate::ffi::{os_str, OsStr, OsString}; -use crate::sys; -use crate::sys::path::{is_sep_byte, is_verbatim_sep, parse_prefix, MAIN_SEP_STR}; - -//////////////////////////////////////////////////////////////////////////////// -// GENERAL NOTES -//////////////////////////////////////////////////////////////////////////////// -// -// Parsing in this module is done by directly transmuting OsStr to [u8] slices, -// taking advantage of the fact that OsStr always encodes ASCII characters -// as-is. Eventually, this transmutation should be replaced by direct uses of -// OsStr APIs for parsing, but it will take a while for those to become -// available. - -//////////////////////////////////////////////////////////////////////////////// -// Windows Prefixes -//////////////////////////////////////////////////////////////////////////////// - -/// Windows path prefixes, e.g., `C:` or `\\server\share`. -/// -/// Windows uses a variety of path prefix styles, including references to drive -/// volumes (like `C:`), network shared folders (like `\\server\share`), and -/// others. In addition, some path prefixes are "verbatim" (i.e., prefixed with -/// `\\?\`), in which case `/` is *not* treated as a separator and essentially -/// no normalization is performed. -/// -/// # Examples -/// -/// ``` -/// use std::path::{Component, Path, Prefix}; -/// use std::path::Prefix::*; -/// use std::ffi::OsStr; -/// -/// fn get_path_prefix(s: &str) -> Prefix<'_> { -/// let path = Path::new(s); -/// match path.components().next().unwrap() { -/// Component::Prefix(prefix_component) => prefix_component.kind(), -/// _ => panic!(), -/// } -/// } -/// -/// # if cfg!(windows) { -/// assert_eq!(Verbatim(OsStr::new("pictures")), -/// get_path_prefix(r"\\?\pictures\kittens")); -/// assert_eq!(VerbatimUNC(OsStr::new("server"), OsStr::new("share")), -/// get_path_prefix(r"\\?\UNC\server\share")); -/// assert_eq!(VerbatimDisk(b'C'), get_path_prefix(r"\\?\c:\")); -/// assert_eq!(DeviceNS(OsStr::new("BrainInterface")), -/// get_path_prefix(r"\\.\BrainInterface")); -/// assert_eq!(UNC(OsStr::new("server"), OsStr::new("share")), -/// get_path_prefix(r"\\server\share")); -/// assert_eq!(Disk(b'C'), get_path_prefix(r"C:\Users\Rust\Pictures\Ferris")); -/// # } -/// ``` -#[derive(Copy, Clone, Debug, Hash, PartialOrd, Ord, PartialEq, Eq)] -#[stable(feature = "rust1", since = "1.0.0")] -pub enum Prefix<'a> { - /// Verbatim prefix, e.g., `\\?\cat_pics`. - /// - /// Verbatim prefixes consist of `\\?\` immediately followed by the given - /// component. - #[stable(feature = "rust1", since = "1.0.0")] - Verbatim(#[stable(feature = "rust1", since = "1.0.0")] &'a OsStr), - - /// Verbatim prefix using Windows' _**U**niform **N**aming **C**onvention_, - /// e.g., `\\?\UNC\server\share`. - /// - /// Verbatim UNC prefixes consist of `\\?\UNC\` immediately followed by the - /// server's hostname and a share name. - #[stable(feature = "rust1", since = "1.0.0")] - VerbatimUNC( - #[stable(feature = "rust1", since = "1.0.0")] &'a OsStr, - #[stable(feature = "rust1", since = "1.0.0")] &'a OsStr, - ), - - /// Verbatim disk prefix, e.g., `\\?\C:`. - /// - /// Verbatim disk prefixes consist of `\\?\` immediately followed by the - /// drive letter and `:`. - #[stable(feature = "rust1", since = "1.0.0")] - VerbatimDisk(#[stable(feature = "rust1", since = "1.0.0")] u8), - - /// Device namespace prefix, e.g., `\\.\COM42`. - /// - /// Device namespace prefixes consist of `\\.\` (possibly using `/` - /// instead of `\`), immediately followed by the device name. - #[stable(feature = "rust1", since = "1.0.0")] - DeviceNS(#[stable(feature = "rust1", since = "1.0.0")] &'a OsStr), - - /// Prefix using Windows' _**U**niform **N**aming **C**onvention_, e.g. - /// `\\server\share`. - /// - /// UNC prefixes consist of the server's hostname and a share name. - #[stable(feature = "rust1", since = "1.0.0")] - UNC( - #[stable(feature = "rust1", since = "1.0.0")] &'a OsStr, - #[stable(feature = "rust1", since = "1.0.0")] &'a OsStr, - ), - - /// Prefix `C:` for the given disk drive. - #[stable(feature = "rust1", since = "1.0.0")] - Disk(#[stable(feature = "rust1", since = "1.0.0")] u8), -} - -impl<'a> Prefix<'a> { - #[inline] - fn len(&self) -> usize { - use self::Prefix::*; - fn os_str_len(s: &OsStr) -> usize { - s.as_encoded_bytes().len() - } - match *self { - Verbatim(x) => 4 + os_str_len(x), - VerbatimUNC(x, y) => { - 8 + os_str_len(x) + if os_str_len(y) > 0 { 1 + os_str_len(y) } else { 0 } - } - VerbatimDisk(_) => 6, - UNC(x, y) => 2 + os_str_len(x) + if os_str_len(y) > 0 { 1 + os_str_len(y) } else { 0 }, - DeviceNS(x) => 4 + os_str_len(x), - Disk(_) => 2, - } - } - - /// Determines if the prefix is verbatim, i.e., begins with `\\?\`. - /// - /// # Examples - /// - /// ``` - /// use std::path::Prefix::*; - /// use std::ffi::OsStr; - /// - /// assert!(Verbatim(OsStr::new("pictures")).is_verbatim()); - /// assert!(VerbatimUNC(OsStr::new("server"), OsStr::new("share")).is_verbatim()); - /// assert!(VerbatimDisk(b'C').is_verbatim()); - /// assert!(!DeviceNS(OsStr::new("BrainInterface")).is_verbatim()); - /// assert!(!UNC(OsStr::new("server"), OsStr::new("share")).is_verbatim()); - /// assert!(!Disk(b'C').is_verbatim()); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn is_verbatim(&self) -> bool { - use self::Prefix::*; - matches!(*self, Verbatim(_) | VerbatimDisk(_) | VerbatimUNC(..)) - } - - #[inline] - fn is_drive(&self) -> bool { - matches!(*self, Prefix::Disk(_)) - } - - #[inline] - fn has_implicit_root(&self) -> bool { - !self.is_drive() - } -} - -//////////////////////////////////////////////////////////////////////////////// -// Exposed parsing helpers -//////////////////////////////////////////////////////////////////////////////// - -/// Determines whether the character is one of the permitted path -/// separators for the current platform. -/// -/// # Examples -/// -/// ``` -/// use std::path; -/// -/// assert!(path::is_separator('/')); // '/' works for both Unix and Windows -/// assert!(!path::is_separator('❤')); -/// ``` -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -pub fn is_separator(c: char) -> bool { - c.is_ascii() && is_sep_byte(c as u8) -} - -/// The primary separator of path components for the current platform. -/// -/// For example, `/` on Unix and `\` on Windows. -#[stable(feature = "rust1", since = "1.0.0")] -pub const MAIN_SEPARATOR: char = crate::sys::path::MAIN_SEP; - -/// The primary separator of path components for the current platform. -/// -/// For example, `/` on Unix and `\` on Windows. -#[stable(feature = "main_separator_str", since = "1.68.0")] -pub const MAIN_SEPARATOR_STR: &str = crate::sys::path::MAIN_SEP_STR; - -//////////////////////////////////////////////////////////////////////////////// -// Misc helpers -//////////////////////////////////////////////////////////////////////////////// - -// Iterate through `iter` while it matches `prefix`; return `None` if `prefix` -// is not a prefix of `iter`, otherwise return `Some(iter_after_prefix)` giving -// `iter` after having exhausted `prefix`. -fn iter_after<'a, 'b, I, J>(mut iter: I, mut prefix: J) -> Option -where - I: Iterator> + Clone, - J: Iterator>, -{ - loop { - let mut iter_next = iter.clone(); - match (iter_next.next(), prefix.next()) { - (Some(ref x), Some(ref y)) if x == y => (), - (Some(_), Some(_)) => return None, - (Some(_), None) => return Some(iter), - (None, None) => return Some(iter), - (None, Some(_)) => return None, - } - iter = iter_next; - } -} - -// Detect scheme on Redox -fn has_redox_scheme(s: &[u8]) -> bool { - cfg!(target_os = "redox") && s.contains(&b':') -} - -//////////////////////////////////////////////////////////////////////////////// -// Cross-platform, iterator-independent parsing -//////////////////////////////////////////////////////////////////////////////// - -/// Says whether the first byte after the prefix is a separator. -fn has_physical_root(s: &[u8], prefix: Option>) -> bool { - let path = if let Some(p) = prefix { &s[p.len()..] } else { s }; - !path.is_empty() && is_sep_byte(path[0]) -} - -// basic workhorse for splitting stem and extension -fn rsplit_file_at_dot(file: &OsStr) -> (Option<&OsStr>, Option<&OsStr>) { - if file.as_encoded_bytes() == b".." { - return (Some(file), None); - } - - // The unsafety here stems from converting between &OsStr and &[u8] - // and back. This is safe to do because (1) we only look at ASCII - // contents of the encoding and (2) new &OsStr values are produced - // only from ASCII-bounded slices of existing &OsStr values. - let mut iter = file.as_encoded_bytes().rsplitn(2, |b| *b == b'.'); - let after = iter.next(); - let before = iter.next(); - if before == Some(b"") { - (Some(file), None) - } else { - unsafe { - ( - before.map(|s| OsStr::from_encoded_bytes_unchecked(s)), - after.map(|s| OsStr::from_encoded_bytes_unchecked(s)), - ) - } - } -} - -fn split_file_at_dot(file: &OsStr) -> (&OsStr, Option<&OsStr>) { - let slice = file.as_encoded_bytes(); - if slice == b".." { - return (file, None); - } - - // The unsafety here stems from converting between &OsStr and &[u8] - // and back. This is safe to do because (1) we only look at ASCII - // contents of the encoding and (2) new &OsStr values are produced - // only from ASCII-bounded slices of existing &OsStr values. - let i = match slice[1..].iter().position(|b| *b == b'.') { - Some(i) => i + 1, - None => return (file, None), - }; - let before = &slice[..i]; - let after = &slice[i + 1..]; - unsafe { - ( - OsStr::from_encoded_bytes_unchecked(before), - Some(OsStr::from_encoded_bytes_unchecked(after)), - ) - } -} - -//////////////////////////////////////////////////////////////////////////////// -// The core iterators -//////////////////////////////////////////////////////////////////////////////// - -/// Component parsing works by a double-ended state machine; the cursors at the -/// front and back of the path each keep track of what parts of the path have -/// been consumed so far. -/// -/// Going front to back, a path is made up of a prefix, a starting -/// directory component, and a body (of normal components) -#[derive(Copy, Clone, PartialEq, PartialOrd, Debug)] -enum State { - Prefix = 0, // c: - StartDir = 1, // / or . or nothing - Body = 2, // foo/bar/baz - Done = 3, -} - -/// A structure wrapping a Windows path prefix as well as its unparsed string -/// representation. -/// -/// In addition to the parsed [`Prefix`] information returned by [`kind`], -/// `PrefixComponent` also holds the raw and unparsed [`OsStr`] slice, -/// returned by [`as_os_str`]. -/// -/// Instances of this `struct` can be obtained by matching against the -/// [`Prefix` variant] on [`Component`]. -/// -/// Does not occur on Unix. -/// -/// # Examples -/// -/// ``` -/// # if cfg!(windows) { -/// use std::path::{Component, Path, Prefix}; -/// use std::ffi::OsStr; -/// -/// let path = Path::new(r"c:\you\later\"); -/// match path.components().next().unwrap() { -/// Component::Prefix(prefix_component) => { -/// assert_eq!(Prefix::Disk(b'C'), prefix_component.kind()); -/// assert_eq!(OsStr::new("c:"), prefix_component.as_os_str()); -/// } -/// _ => unreachable!(), -/// } -/// # } -/// ``` -/// -/// [`as_os_str`]: PrefixComponent::as_os_str -/// [`kind`]: PrefixComponent::kind -/// [`Prefix` variant]: Component::Prefix -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Copy, Clone, Eq, Debug)] -pub struct PrefixComponent<'a> { - /// The prefix as an unparsed `OsStr` slice. - raw: &'a OsStr, - - /// The parsed prefix data. - parsed: Prefix<'a>, -} - -impl<'a> PrefixComponent<'a> { - /// Returns the parsed prefix data. - /// - /// See [`Prefix`]'s documentation for more information on the different - /// kinds of prefixes. - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - #[inline] - pub fn kind(&self) -> Prefix<'a> { - self.parsed - } - - /// Returns the raw [`OsStr`] slice for this prefix. - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - #[inline] - pub fn as_os_str(&self) -> &'a OsStr { - self.raw - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a> PartialEq for PrefixComponent<'a> { - #[inline] - fn eq(&self, other: &PrefixComponent<'a>) -> bool { - self.parsed == other.parsed - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a> PartialOrd for PrefixComponent<'a> { - #[inline] - fn partial_cmp(&self, other: &PrefixComponent<'a>) -> Option { - PartialOrd::partial_cmp(&self.parsed, &other.parsed) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for PrefixComponent<'_> { - #[inline] - fn cmp(&self, other: &Self) -> cmp::Ordering { - Ord::cmp(&self.parsed, &other.parsed) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Hash for PrefixComponent<'_> { - fn hash(&self, h: &mut H) { - self.parsed.hash(h); - } -} - -/// A single component of a path. -/// -/// A `Component` roughly corresponds to a substring between path separators -/// (`/` or `\`). -/// -/// This `enum` is created by iterating over [`Components`], which in turn is -/// created by the [`components`](Path::components) method on [`Path`]. -/// -/// # Examples -/// -/// ```rust -/// use std::path::{Component, Path}; -/// -/// let path = Path::new("/tmp/foo/bar.txt"); -/// let components = path.components().collect::>(); -/// assert_eq!(&components, &[ -/// Component::RootDir, -/// Component::Normal("tmp".as_ref()), -/// Component::Normal("foo".as_ref()), -/// Component::Normal("bar.txt".as_ref()), -/// ]); -/// ``` -#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)] -#[stable(feature = "rust1", since = "1.0.0")] -pub enum Component<'a> { - /// A Windows path prefix, e.g., `C:` or `\\server\share`. - /// - /// There is a large variety of prefix types, see [`Prefix`]'s documentation - /// for more. - /// - /// Does not occur on Unix. - #[stable(feature = "rust1", since = "1.0.0")] - Prefix(#[stable(feature = "rust1", since = "1.0.0")] PrefixComponent<'a>), - - /// The root directory component, appears after any prefix and before anything else. - /// - /// It represents a separator that designates that a path starts from root. - #[stable(feature = "rust1", since = "1.0.0")] - RootDir, - - /// A reference to the current directory, i.e., `.`. - #[stable(feature = "rust1", since = "1.0.0")] - CurDir, - - /// A reference to the parent directory, i.e., `..`. - #[stable(feature = "rust1", since = "1.0.0")] - ParentDir, - - /// A normal component, e.g., `a` and `b` in `a/b`. - /// - /// This variant is the most common one, it represents references to files - /// or directories. - #[stable(feature = "rust1", since = "1.0.0")] - Normal(#[stable(feature = "rust1", since = "1.0.0")] &'a OsStr), -} - -impl<'a> Component<'a> { - /// Extracts the underlying [`OsStr`] slice. - /// - /// # Examples - /// - /// ``` - /// use std::path::Path; - /// - /// let path = Path::new("./tmp/foo/bar.txt"); - /// let components: Vec<_> = path.components().map(|comp| comp.as_os_str()).collect(); - /// assert_eq!(&components, &[".", "tmp", "foo", "bar.txt"]); - /// ``` - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn as_os_str(self) -> &'a OsStr { - match self { - Component::Prefix(p) => p.as_os_str(), - Component::RootDir => OsStr::new(MAIN_SEP_STR), - Component::CurDir => OsStr::new("."), - Component::ParentDir => OsStr::new(".."), - Component::Normal(path) => path, - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef for Component<'_> { - #[inline] - fn as_ref(&self) -> &OsStr { - self.as_os_str() - } -} - -#[stable(feature = "path_component_asref", since = "1.25.0")] -impl AsRef for Component<'_> { - #[inline] - fn as_ref(&self) -> &Path { - self.as_os_str().as_ref() - } -} - -/// An iterator over the [`Component`]s of a [`Path`]. -/// -/// This `struct` is created by the [`components`] method on [`Path`]. -/// See its documentation for more. -/// -/// # Examples -/// -/// ``` -/// use std::path::Path; -/// -/// let path = Path::new("/tmp/foo/bar.txt"); -/// -/// for component in path.components() { -/// println!("{component:?}"); -/// } -/// ``` -/// -/// [`components`]: Path::components -#[derive(Clone)] -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Components<'a> { - // The path left to parse components from - path: &'a [u8], - - // The prefix as it was originally parsed, if any - prefix: Option>, - - // true if path *physically* has a root separator; for most Windows - // prefixes, it may have a "logical" root separator for the purposes of - // normalization, e.g., \\server\share == \\server\share\. - has_physical_root: bool, - - // The iterator is double-ended, and these two states keep track of what has - // been produced from either end - front: State, - back: State, -} - -/// An iterator over the [`Component`]s of a [`Path`], as [`OsStr`] slices. -/// -/// This `struct` is created by the [`iter`] method on [`Path`]. -/// See its documentation for more. -/// -/// [`iter`]: Path::iter -#[derive(Clone)] -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Iter<'a> { - inner: Components<'a>, -} - -#[stable(feature = "path_components_debug", since = "1.13.0")] -impl fmt::Debug for Components<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - struct DebugHelper<'a>(&'a Path); - - impl fmt::Debug for DebugHelper<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.0.components()).finish() - } - } - - f.debug_tuple("Components").field(&DebugHelper(self.as_path())).finish() - } -} - -impl<'a> Components<'a> { - // how long is the prefix, if any? - #[inline] - fn prefix_len(&self) -> usize { - self.prefix.as_ref().map(Prefix::len).unwrap_or(0) - } - - #[inline] - fn prefix_verbatim(&self) -> bool { - self.prefix.as_ref().map(Prefix::is_verbatim).unwrap_or(false) - } - - /// how much of the prefix is left from the point of view of iteration? - #[inline] - fn prefix_remaining(&self) -> usize { - if self.front == State::Prefix { self.prefix_len() } else { 0 } - } - - // Given the iteration so far, how much of the pre-State::Body path is left? - #[inline] - fn len_before_body(&self) -> usize { - let root = if self.front <= State::StartDir && self.has_physical_root { 1 } else { 0 }; - let cur_dir = if self.front <= State::StartDir && self.include_cur_dir() { 1 } else { 0 }; - self.prefix_remaining() + root + cur_dir - } - - // is the iteration complete? - #[inline] - fn finished(&self) -> bool { - self.front == State::Done || self.back == State::Done || self.front > self.back - } - - #[inline] - fn is_sep_byte(&self, b: u8) -> bool { - if self.prefix_verbatim() { is_verbatim_sep(b) } else { is_sep_byte(b) } - } - - /// Extracts a slice corresponding to the portion of the path remaining for iteration. - /// - /// # Examples - /// - /// ``` - /// use std::path::Path; - /// - /// let mut components = Path::new("/tmp/foo/bar.txt").components(); - /// components.next(); - /// components.next(); - /// - /// assert_eq!(Path::new("foo/bar.txt"), components.as_path()); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn as_path(&self) -> &'a Path { - let mut comps = self.clone(); - if comps.front == State::Body { - comps.trim_left(); - } - if comps.back == State::Body { - comps.trim_right(); - } - unsafe { Path::from_u8_slice(comps.path) } - } - - /// Is the *original* path rooted? - fn has_root(&self) -> bool { - if self.has_physical_root { - return true; - } - if let Some(p) = self.prefix { - if p.has_implicit_root() { - return true; - } - } - false - } - - /// Should the normalized path include a leading . ? - fn include_cur_dir(&self) -> bool { - if self.has_root() { - return false; - } - let mut iter = self.path[self.prefix_remaining()..].iter(); - match (iter.next(), iter.next()) { - (Some(&b'.'), None) => true, - (Some(&b'.'), Some(&b)) => self.is_sep_byte(b), - _ => false, - } - } - - // parse a given byte sequence following the OsStr encoding into the - // corresponding path component - unsafe fn parse_single_component<'b>(&self, comp: &'b [u8]) -> Option> { - match comp { - b"." if self.prefix_verbatim() => Some(Component::CurDir), - b"." => None, // . components are normalized away, except at - // the beginning of a path, which is treated - // separately via `include_cur_dir` - b".." => Some(Component::ParentDir), - b"" => None, - _ => Some(Component::Normal(unsafe { OsStr::from_encoded_bytes_unchecked(comp) })), - } - } - - // parse a component from the left, saying how many bytes to consume to - // remove the component - fn parse_next_component(&self) -> (usize, Option>) { - debug_assert!(self.front == State::Body); - let (extra, comp) = match self.path.iter().position(|b| self.is_sep_byte(*b)) { - None => (0, self.path), - Some(i) => (1, &self.path[..i]), - }; - // SAFETY: `comp` is a valid substring, since it is split on a separator. - (comp.len() + extra, unsafe { self.parse_single_component(comp) }) - } - - // parse a component from the right, saying how many bytes to consume to - // remove the component - fn parse_next_component_back(&self) -> (usize, Option>) { - debug_assert!(self.back == State::Body); - let start = self.len_before_body(); - let (extra, comp) = match self.path[start..].iter().rposition(|b| self.is_sep_byte(*b)) { - None => (0, &self.path[start..]), - Some(i) => (1, &self.path[start + i + 1..]), - }; - // SAFETY: `comp` is a valid substring, since it is split on a separator. - (comp.len() + extra, unsafe { self.parse_single_component(comp) }) - } - - // trim away repeated separators (i.e., empty components) on the left - fn trim_left(&mut self) { - while !self.path.is_empty() { - let (size, comp) = self.parse_next_component(); - if comp.is_some() { - return; - } else { - self.path = &self.path[size..]; - } - } - } - - // trim away repeated separators (i.e., empty components) on the right - fn trim_right(&mut self) { - while self.path.len() > self.len_before_body() { - let (size, comp) = self.parse_next_component_back(); - if comp.is_some() { - return; - } else { - self.path = &self.path[..self.path.len() - size]; - } - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef for Components<'_> { - #[inline] - fn as_ref(&self) -> &Path { - self.as_path() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef for Components<'_> { - #[inline] - fn as_ref(&self) -> &OsStr { - self.as_path().as_os_str() - } -} - -#[stable(feature = "path_iter_debug", since = "1.13.0")] -impl fmt::Debug for Iter<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - struct DebugHelper<'a>(&'a Path); - - impl fmt::Debug for DebugHelper<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.0.iter()).finish() - } - } - - f.debug_tuple("Iter").field(&DebugHelper(self.as_path())).finish() - } -} - -impl<'a> Iter<'a> { - /// Extracts a slice corresponding to the portion of the path remaining for iteration. - /// - /// # Examples - /// - /// ``` - /// use std::path::Path; - /// - /// let mut iter = Path::new("/tmp/foo/bar.txt").iter(); - /// iter.next(); - /// iter.next(); - /// - /// assert_eq!(Path::new("foo/bar.txt"), iter.as_path()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - #[inline] - pub fn as_path(&self) -> &'a Path { - self.inner.as_path() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef for Iter<'_> { - #[inline] - fn as_ref(&self) -> &Path { - self.as_path() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef for Iter<'_> { - #[inline] - fn as_ref(&self) -> &OsStr { - self.as_path().as_os_str() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a> Iterator for Iter<'a> { - type Item = &'a OsStr; - - #[inline] - fn next(&mut self) -> Option<&'a OsStr> { - self.inner.next().map(Component::as_os_str) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a> DoubleEndedIterator for Iter<'a> { - #[inline] - fn next_back(&mut self) -> Option<&'a OsStr> { - self.inner.next_back().map(Component::as_os_str) - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Iter<'_> {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a> Iterator for Components<'a> { - type Item = Component<'a>; - - fn next(&mut self) -> Option> { - while !self.finished() { - match self.front { - State::Prefix if self.prefix_len() > 0 => { - self.front = State::StartDir; - debug_assert!(self.prefix_len() <= self.path.len()); - let raw = &self.path[..self.prefix_len()]; - self.path = &self.path[self.prefix_len()..]; - return Some(Component::Prefix(PrefixComponent { - raw: unsafe { OsStr::from_encoded_bytes_unchecked(raw) }, - parsed: self.prefix.unwrap(), - })); - } - State::Prefix => { - self.front = State::StartDir; - } - State::StartDir => { - self.front = State::Body; - if self.has_physical_root { - debug_assert!(!self.path.is_empty()); - self.path = &self.path[1..]; - return Some(Component::RootDir); - } else if let Some(p) = self.prefix { - if p.has_implicit_root() && !p.is_verbatim() { - return Some(Component::RootDir); - } - } else if self.include_cur_dir() { - debug_assert!(!self.path.is_empty()); - self.path = &self.path[1..]; - return Some(Component::CurDir); - } - } - State::Body if !self.path.is_empty() => { - let (size, comp) = self.parse_next_component(); - self.path = &self.path[size..]; - if comp.is_some() { - return comp; - } - } - State::Body => { - self.front = State::Done; - } - State::Done => unreachable!(), - } - } - None - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a> DoubleEndedIterator for Components<'a> { - fn next_back(&mut self) -> Option> { - while !self.finished() { - match self.back { - State::Body if self.path.len() > self.len_before_body() => { - let (size, comp) = self.parse_next_component_back(); - self.path = &self.path[..self.path.len() - size]; - if comp.is_some() { - return comp; - } - } - State::Body => { - self.back = State::StartDir; - } - State::StartDir => { - self.back = State::Prefix; - if self.has_physical_root { - self.path = &self.path[..self.path.len() - 1]; - return Some(Component::RootDir); - } else if let Some(p) = self.prefix { - if p.has_implicit_root() && !p.is_verbatim() { - return Some(Component::RootDir); - } - } else if self.include_cur_dir() { - self.path = &self.path[..self.path.len() - 1]; - return Some(Component::CurDir); - } - } - State::Prefix if self.prefix_len() > 0 => { - self.back = State::Done; - return Some(Component::Prefix(PrefixComponent { - raw: unsafe { OsStr::from_encoded_bytes_unchecked(self.path) }, - parsed: self.prefix.unwrap(), - })); - } - State::Prefix => { - self.back = State::Done; - return None; - } - State::Done => unreachable!(), - } - } - None - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Components<'_> {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a> PartialEq for Components<'a> { - #[inline] - fn eq(&self, other: &Components<'a>) -> bool { - let Components { path: _, front: _, back: _, has_physical_root: _, prefix: _ } = self; - - // Fast path for exact matches, e.g. for hashmap lookups. - // Don't explicitly compare the prefix or has_physical_root fields since they'll - // either be covered by the `path` buffer or are only relevant for `prefix_verbatim()`. - if self.path.len() == other.path.len() - && self.front == other.front - && self.back == State::Body - && other.back == State::Body - && self.prefix_verbatim() == other.prefix_verbatim() - { - // possible future improvement: this could bail out earlier if there were a - // reverse memcmp/bcmp comparing back to front - if self.path == other.path { - return true; - } - } - - // compare back to front since absolute paths often share long prefixes - Iterator::eq(self.clone().rev(), other.clone().rev()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Eq for Components<'_> {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a> PartialOrd for Components<'a> { - #[inline] - fn partial_cmp(&self, other: &Components<'a>) -> Option { - Some(compare_components(self.clone(), other.clone())) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for Components<'_> { - #[inline] - fn cmp(&self, other: &Self) -> cmp::Ordering { - compare_components(self.clone(), other.clone()) - } -} - -fn compare_components(mut left: Components<'_>, mut right: Components<'_>) -> cmp::Ordering { - // Fast path for long shared prefixes - // - // - compare raw bytes to find first mismatch - // - backtrack to find separator before mismatch to avoid ambiguous parsings of '.' or '..' characters - // - if found update state to only do a component-wise comparison on the remainder, - // otherwise do it on the full path - // - // The fast path isn't taken for paths with a PrefixComponent to avoid backtracking into - // the middle of one - if left.prefix.is_none() && right.prefix.is_none() && left.front == right.front { - // possible future improvement: a [u8]::first_mismatch simd implementation - let first_difference = match left.path.iter().zip(right.path).position(|(&a, &b)| a != b) { - None if left.path.len() == right.path.len() => return cmp::Ordering::Equal, - None => left.path.len().min(right.path.len()), - Some(diff) => diff, - }; - - if let Some(previous_sep) = - left.path[..first_difference].iter().rposition(|&b| left.is_sep_byte(b)) - { - let mismatched_component_start = previous_sep + 1; - left.path = &left.path[mismatched_component_start..]; - left.front = State::Body; - right.path = &right.path[mismatched_component_start..]; - right.front = State::Body; - } - } - - Iterator::cmp(left, right) -} - -/// An iterator over [`Path`] and its ancestors. -/// -/// This `struct` is created by the [`ancestors`] method on [`Path`]. -/// See its documentation for more. -/// -/// # Examples -/// -/// ``` -/// use std::path::Path; -/// -/// let path = Path::new("/foo/bar"); -/// -/// for ancestor in path.ancestors() { -/// println!("{}", ancestor.display()); -/// } -/// ``` -/// -/// [`ancestors`]: Path::ancestors -#[derive(Copy, Clone, Debug)] -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "path_ancestors", since = "1.28.0")] -pub struct Ancestors<'a> { - next: Option<&'a Path>, -} - -#[stable(feature = "path_ancestors", since = "1.28.0")] -impl<'a> Iterator for Ancestors<'a> { - type Item = &'a Path; - - #[inline] - fn next(&mut self) -> Option { - let next = self.next; - self.next = next.and_then(Path::parent); - next - } -} - -#[stable(feature = "path_ancestors", since = "1.28.0")] -impl FusedIterator for Ancestors<'_> {} - -//////////////////////////////////////////////////////////////////////////////// -// Basic types and traits -//////////////////////////////////////////////////////////////////////////////// - -/// An owned, mutable path (akin to [`String`]). -/// -/// This type provides methods like [`push`] and [`set_extension`] that mutate -/// the path in place. It also implements [`Deref`] to [`Path`], meaning that -/// all methods on [`Path`] slices are available on `PathBuf` values as well. -/// -/// [`push`]: PathBuf::push -/// [`set_extension`]: PathBuf::set_extension -/// -/// More details about the overall approach can be found in -/// the [module documentation](self). -/// -/// # Examples -/// -/// You can use [`push`] to build up a `PathBuf` from -/// components: -/// -/// ``` -/// use std::path::PathBuf; -/// -/// let mut path = PathBuf::new(); -/// -/// path.push(r"C:\"); -/// path.push("windows"); -/// path.push("system32"); -/// -/// path.set_extension("dll"); -/// ``` -/// -/// However, [`push`] is best used for dynamic situations. This is a better way -/// to do this when you know all of the components ahead of time: -/// -/// ``` -/// use std::path::PathBuf; -/// -/// let path: PathBuf = [r"C:\", "windows", "system32.dll"].iter().collect(); -/// ``` -/// -/// We can still do better than this! Since these are all strings, we can use -/// `From::from`: -/// -/// ``` -/// use std::path::PathBuf; -/// -/// let path = PathBuf::from(r"C:\windows\system32.dll"); -/// ``` -/// -/// Which method works best depends on what kind of situation you're in. -#[cfg_attr(not(test), rustc_diagnostic_item = "PathBuf")] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct PathBuf { - inner: OsString, -} - -impl PathBuf { - #[inline] - fn as_mut_vec(&mut self) -> &mut Vec { - self.inner.as_mut_vec_for_path_buf() - } - - /// Allocates an empty `PathBuf`. - /// - /// # Examples - /// - /// ``` - /// use std::path::PathBuf; - /// - /// let path = PathBuf::new(); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - #[inline] - pub fn new() -> PathBuf { - PathBuf { inner: OsString::new() } - } - - /// Creates a new `PathBuf` with a given capacity used to create the - /// internal [`OsString`]. See [`with_capacity`] defined on [`OsString`]. - /// - /// # Examples - /// - /// ``` - /// use std::path::PathBuf; - /// - /// let mut path = PathBuf::with_capacity(10); - /// let capacity = path.capacity(); - /// - /// // This push is done without reallocating - /// path.push(r"C:\"); - /// - /// assert_eq!(capacity, path.capacity()); - /// ``` - /// - /// [`with_capacity`]: OsString::with_capacity - #[stable(feature = "path_buf_capacity", since = "1.44.0")] - #[must_use] - #[inline] - pub fn with_capacity(capacity: usize) -> PathBuf { - PathBuf { inner: OsString::with_capacity(capacity) } - } - - /// Coerces to a [`Path`] slice. - /// - /// # Examples - /// - /// ``` - /// use std::path::{Path, PathBuf}; - /// - /// let p = PathBuf::from("/test"); - /// assert_eq!(Path::new("/test"), p.as_path()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - #[inline] - pub fn as_path(&self) -> &Path { - self - } - - /// Extends `self` with `path`. - /// - /// If `path` is absolute, it replaces the current path. - /// - /// On Windows: - /// - /// * if `path` has a root but no prefix (e.g., `\windows`), it - /// replaces everything except for the prefix (if any) of `self`. - /// * if `path` has a prefix but no root, it replaces `self`. - /// * if `self` has a verbatim prefix (e.g. `\\?\C:\windows`) - /// and `path` is not empty, the new path is normalized: all references - /// to `.` and `..` are removed. - /// - /// Consider using [`Path::join`] if you need a new `PathBuf` instead of - /// using this function on a cloned `PathBuf`. - /// - /// # Examples - /// - /// Pushing a relative path extends the existing path: - /// - /// ``` - /// use std::path::PathBuf; - /// - /// let mut path = PathBuf::from("/tmp"); - /// path.push("file.bk"); - /// assert_eq!(path, PathBuf::from("/tmp/file.bk")); - /// ``` - /// - /// Pushing an absolute path replaces the existing path: - /// - /// ``` - /// use std::path::PathBuf; - /// - /// let mut path = PathBuf::from("/tmp"); - /// path.push("/etc"); - /// assert_eq!(path, PathBuf::from("/etc")); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("append", "put")] - pub fn push>(&mut self, path: P) { - self._push(path.as_ref()) - } - - fn _push(&mut self, path: &Path) { - // in general, a separator is needed if the rightmost byte is not a separator - let mut need_sep = self.as_mut_vec().last().map(|c| !is_sep_byte(*c)).unwrap_or(false); - - // in the special case of `C:` on Windows, do *not* add a separator - let comps = self.components(); - - if comps.prefix_len() > 0 - && comps.prefix_len() == comps.path.len() - && comps.prefix.unwrap().is_drive() - { - need_sep = false - } - - // absolute `path` replaces `self` - if path.is_absolute() || path.prefix().is_some() { - self.as_mut_vec().truncate(0); - - // verbatim paths need . and .. removed - } else if comps.prefix_verbatim() && !path.inner.is_empty() { - let mut buf: Vec<_> = comps.collect(); - for c in path.components() { - match c { - Component::RootDir => { - buf.truncate(1); - buf.push(c); - } - Component::CurDir => (), - Component::ParentDir => { - if let Some(Component::Normal(_)) = buf.last() { - buf.pop(); - } - } - _ => buf.push(c), - } - } - - let mut res = OsString::new(); - let mut need_sep = false; - - for c in buf { - if need_sep && c != Component::RootDir { - res.push(MAIN_SEP_STR); - } - res.push(c.as_os_str()); - - need_sep = match c { - Component::RootDir => false, - Component::Prefix(prefix) => { - !prefix.parsed.is_drive() && prefix.parsed.len() > 0 - } - _ => true, - } - } - - self.inner = res; - return; - - // `path` has a root but no prefix, e.g., `\windows` (Windows only) - } else if path.has_root() { - let prefix_len = self.components().prefix_remaining(); - self.as_mut_vec().truncate(prefix_len); - - // `path` is a pure relative path - } else if need_sep { - self.inner.push(MAIN_SEP_STR); - } - - self.inner.push(path); - } - - /// Truncates `self` to [`self.parent`]. - /// - /// Returns `false` and does nothing if [`self.parent`] is [`None`]. - /// Otherwise, returns `true`. - /// - /// [`self.parent`]: Path::parent - /// - /// # Examples - /// - /// ``` - /// use std::path::{Path, PathBuf}; - /// - /// let mut p = PathBuf::from("/spirited/away.rs"); - /// - /// p.pop(); - /// assert_eq!(Path::new("/spirited"), p); - /// p.pop(); - /// assert_eq!(Path::new("/"), p); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn pop(&mut self) -> bool { - match self.parent().map(|p| p.as_u8_slice().len()) { - Some(len) => { - self.as_mut_vec().truncate(len); - true - } - None => false, - } - } - - /// Updates [`self.file_name`] to `file_name`. - /// - /// If [`self.file_name`] was [`None`], this is equivalent to pushing - /// `file_name`. - /// - /// Otherwise it is equivalent to calling [`pop`] and then pushing - /// `file_name`. The new path will be a sibling of the original path. - /// (That is, it will have the same parent.) - /// - /// [`self.file_name`]: Path::file_name - /// [`pop`]: PathBuf::pop - /// - /// # Examples - /// - /// ``` - /// use std::path::PathBuf; - /// - /// let mut buf = PathBuf::from("/"); - /// assert!(buf.file_name() == None); - /// - /// buf.set_file_name("foo.txt"); - /// assert!(buf == PathBuf::from("/foo.txt")); - /// assert!(buf.file_name().is_some()); - /// - /// buf.set_file_name("bar.txt"); - /// assert!(buf == PathBuf::from("/bar.txt")); - /// - /// buf.set_file_name("baz"); - /// assert!(buf == PathBuf::from("/baz")); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn set_file_name>(&mut self, file_name: S) { - self._set_file_name(file_name.as_ref()) - } - - fn _set_file_name(&mut self, file_name: &OsStr) { - if self.file_name().is_some() { - let popped = self.pop(); - debug_assert!(popped); - } - self.push(file_name); - } - - /// Updates [`self.extension`] to `Some(extension)` or to `None` if - /// `extension` is empty. - /// - /// Returns `false` and does nothing if [`self.file_name`] is [`None`], - /// returns `true` and updates the extension otherwise. - /// - /// If [`self.extension`] is [`None`], the extension is added; otherwise - /// it is replaced. - /// - /// If `extension` is the empty string, [`self.extension`] will be [`None`] - /// afterwards, not `Some("")`. - /// - /// # Caveats - /// - /// The new `extension` may contain dots and will be used in its entirety, - /// but only the part after the final dot will be reflected in - /// [`self.extension`]. - /// - /// If the file stem contains internal dots and `extension` is empty, part - /// of the old file stem will be considered the new [`self.extension`]. - /// - /// See the examples below. - /// - /// [`self.file_name`]: Path::file_name - /// [`self.extension`]: Path::extension - /// - /// # Examples - /// - /// ``` - /// use std::path::{Path, PathBuf}; - /// - /// let mut p = PathBuf::from("/feel/the"); - /// - /// p.set_extension("force"); - /// assert_eq!(Path::new("/feel/the.force"), p.as_path()); - /// - /// p.set_extension("dark.side"); - /// assert_eq!(Path::new("/feel/the.dark.side"), p.as_path()); - /// - /// p.set_extension("cookie"); - /// assert_eq!(Path::new("/feel/the.dark.cookie"), p.as_path()); - /// - /// p.set_extension(""); - /// assert_eq!(Path::new("/feel/the.dark"), p.as_path()); - /// - /// p.set_extension(""); - /// assert_eq!(Path::new("/feel/the"), p.as_path()); - /// - /// p.set_extension(""); - /// assert_eq!(Path::new("/feel/the"), p.as_path()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn set_extension>(&mut self, extension: S) -> bool { - self._set_extension(extension.as_ref()) - } - - fn _set_extension(&mut self, extension: &OsStr) -> bool { - let file_stem = match self.file_stem() { - None => return false, - Some(f) => f.as_encoded_bytes(), - }; - - // truncate until right after the file stem - let end_file_stem = file_stem[file_stem.len()..].as_ptr().addr(); - let start = self.inner.as_encoded_bytes().as_ptr().addr(); - let v = self.as_mut_vec(); - v.truncate(end_file_stem.wrapping_sub(start)); - - // add the new extension, if any - let new = extension.as_encoded_bytes(); - if !new.is_empty() { - v.reserve_exact(new.len() + 1); - v.push(b'.'); - v.extend_from_slice(new); - } - - true - } - - /// Yields a mutable reference to the underlying [`OsString`] instance. - /// - /// # Examples - /// - /// ``` - /// use std::path::{Path, PathBuf}; - /// - /// let mut path = PathBuf::from("/foo"); - /// - /// path.push("bar"); - /// assert_eq!(path, Path::new("/foo/bar")); - /// - /// // OsString's `push` does not add a separator. - /// path.as_mut_os_string().push("baz"); - /// assert_eq!(path, Path::new("/foo/barbaz")); - /// ``` - #[stable(feature = "path_as_mut_os_str", since = "1.70.0")] - #[must_use] - #[inline] - pub fn as_mut_os_string(&mut self) -> &mut OsString { - &mut self.inner - } - - /// Consumes the `PathBuf`, yielding its internal [`OsString`] storage. - /// - /// # Examples - /// - /// ``` - /// use std::path::PathBuf; - /// - /// let p = PathBuf::from("/the/head"); - /// let os_str = p.into_os_string(); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use = "`self` will be dropped if the result is not used"] - #[inline] - pub fn into_os_string(self) -> OsString { - self.inner - } - - /// Converts this `PathBuf` into a [boxed](Box) [`Path`]. - #[stable(feature = "into_boxed_path", since = "1.20.0")] - #[must_use = "`self` will be dropped if the result is not used"] - #[inline] - pub fn into_boxed_path(self) -> Box { - let rw = Box::into_raw(self.inner.into_boxed_os_str()) as *mut Path; - unsafe { Box::from_raw(rw) } - } - - /// Invokes [`capacity`] on the underlying instance of [`OsString`]. - /// - /// [`capacity`]: OsString::capacity - #[stable(feature = "path_buf_capacity", since = "1.44.0")] - #[must_use] - #[inline] - pub fn capacity(&self) -> usize { - self.inner.capacity() - } - - /// Invokes [`clear`] on the underlying instance of [`OsString`]. - /// - /// [`clear`]: OsString::clear - #[stable(feature = "path_buf_capacity", since = "1.44.0")] - #[inline] - pub fn clear(&mut self) { - self.inner.clear() - } - - /// Invokes [`reserve`] on the underlying instance of [`OsString`]. - /// - /// [`reserve`]: OsString::reserve - #[stable(feature = "path_buf_capacity", since = "1.44.0")] - #[inline] - pub fn reserve(&mut self, additional: usize) { - self.inner.reserve(additional) - } - - /// Invokes [`try_reserve`] on the underlying instance of [`OsString`]. - /// - /// [`try_reserve`]: OsString::try_reserve - #[stable(feature = "try_reserve_2", since = "1.63.0")] - #[inline] - pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> { - self.inner.try_reserve(additional) - } - - /// Invokes [`reserve_exact`] on the underlying instance of [`OsString`]. - /// - /// [`reserve_exact`]: OsString::reserve_exact - #[stable(feature = "path_buf_capacity", since = "1.44.0")] - #[inline] - pub fn reserve_exact(&mut self, additional: usize) { - self.inner.reserve_exact(additional) - } - - /// Invokes [`try_reserve_exact`] on the underlying instance of [`OsString`]. - /// - /// [`try_reserve_exact`]: OsString::try_reserve_exact - #[stable(feature = "try_reserve_2", since = "1.63.0")] - #[inline] - pub fn try_reserve_exact(&mut self, additional: usize) -> Result<(), TryReserveError> { - self.inner.try_reserve_exact(additional) - } - - /// Invokes [`shrink_to_fit`] on the underlying instance of [`OsString`]. - /// - /// [`shrink_to_fit`]: OsString::shrink_to_fit - #[stable(feature = "path_buf_capacity", since = "1.44.0")] - #[inline] - pub fn shrink_to_fit(&mut self) { - self.inner.shrink_to_fit() - } - - /// Invokes [`shrink_to`] on the underlying instance of [`OsString`]. - /// - /// [`shrink_to`]: OsString::shrink_to - #[stable(feature = "shrink_to", since = "1.56.0")] - #[inline] - pub fn shrink_to(&mut self, min_capacity: usize) { - self.inner.shrink_to(min_capacity) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for PathBuf { - #[inline] - fn clone(&self) -> Self { - PathBuf { inner: self.inner.clone() } - } - - /// Clones the contents of `source` into `self`. - /// - /// This method is preferred over simply assigning `source.clone()` to `self`, - /// as it avoids reallocation if possible. - #[inline] - fn clone_from(&mut self, source: &Self) { - self.inner.clone_from(&source.inner) - } -} - -#[stable(feature = "box_from_path", since = "1.17.0")] -impl From<&Path> for Box { - /// Creates a boxed [`Path`] from a reference. - /// - /// This will allocate and clone `path` to it. - fn from(path: &Path) -> Box { - let boxed: Box = path.inner.into(); - let rw = Box::into_raw(boxed) as *mut Path; - unsafe { Box::from_raw(rw) } - } -} - -#[stable(feature = "box_from_cow", since = "1.45.0")] -impl From> for Box { - /// Creates a boxed [`Path`] from a clone-on-write pointer. - /// - /// Converting from a `Cow::Owned` does not clone or allocate. - #[inline] - fn from(cow: Cow<'_, Path>) -> Box { - match cow { - Cow::Borrowed(path) => Box::from(path), - Cow::Owned(path) => Box::from(path), - } - } -} - -#[stable(feature = "path_buf_from_box", since = "1.18.0")] -impl From> for PathBuf { - /// Converts a [Box]<[Path]> into a [`PathBuf`]. - /// - /// This conversion does not allocate or copy memory. - #[inline] - fn from(boxed: Box) -> PathBuf { - boxed.into_path_buf() - } -} - -#[stable(feature = "box_from_path_buf", since = "1.20.0")] -impl From for Box { - /// Converts a [`PathBuf`] into a [Box]<[Path]>. - /// - /// This conversion currently should not allocate memory, - /// but this behavior is not guaranteed on all platforms or in all future versions. - #[inline] - fn from(p: PathBuf) -> Box { - p.into_boxed_path() - } -} - -#[stable(feature = "more_box_slice_clone", since = "1.29.0")] -impl Clone for Box { - #[inline] - fn clone(&self) -> Self { - self.to_path_buf().into_boxed_path() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl> From<&T> for PathBuf { - /// Converts a borrowed [`OsStr`] to a [`PathBuf`]. - /// - /// Allocates a [`PathBuf`] and copies the data into it. - #[inline] - fn from(s: &T) -> PathBuf { - PathBuf::from(s.as_ref().to_os_string()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl From for PathBuf { - /// Converts an [`OsString`] into a [`PathBuf`] - /// - /// This conversion does not allocate or copy memory. - #[inline] - fn from(s: OsString) -> PathBuf { - PathBuf { inner: s } - } -} - -#[stable(feature = "from_path_buf_for_os_string", since = "1.14.0")] -impl From for OsString { - /// Converts a [`PathBuf`] into an [`OsString`] - /// - /// This conversion does not allocate or copy memory. - #[inline] - fn from(path_buf: PathBuf) -> OsString { - path_buf.inner - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl From for PathBuf { - /// Converts a [`String`] into a [`PathBuf`] - /// - /// This conversion does not allocate or copy memory. - #[inline] - fn from(s: String) -> PathBuf { - PathBuf::from(OsString::from(s)) - } -} - -#[stable(feature = "path_from_str", since = "1.32.0")] -impl FromStr for PathBuf { - type Err = core::convert::Infallible; - - #[inline] - fn from_str(s: &str) -> Result { - Ok(PathBuf::from(s)) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl> FromIterator

for PathBuf { - fn from_iter>(iter: I) -> PathBuf { - let mut buf = PathBuf::new(); - buf.extend(iter); - buf - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl> Extend

for PathBuf { - fn extend>(&mut self, iter: I) { - iter.into_iter().for_each(move |p| self.push(p.as_ref())); - } - - #[inline] - fn extend_one(&mut self, p: P) { - self.push(p.as_ref()); - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for PathBuf { - fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&**self, formatter) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ops::Deref for PathBuf { - type Target = Path; - #[inline] - fn deref(&self) -> &Path { - Path::new(&self.inner) - } -} - -#[stable(feature = "path_buf_deref_mut", since = "1.68.0")] -impl ops::DerefMut for PathBuf { - #[inline] - fn deref_mut(&mut self) -> &mut Path { - Path::from_inner_mut(&mut self.inner) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Borrow for PathBuf { - #[inline] - fn borrow(&self) -> &Path { - self.deref() - } -} - -#[stable(feature = "default_for_pathbuf", since = "1.17.0")] -impl Default for PathBuf { - #[inline] - fn default() -> Self { - PathBuf::new() - } -} - -#[stable(feature = "cow_from_path", since = "1.6.0")] -impl<'a> From<&'a Path> for Cow<'a, Path> { - /// Creates a clone-on-write pointer from a reference to - /// [`Path`]. - /// - /// This conversion does not clone or allocate. - #[inline] - fn from(s: &'a Path) -> Cow<'a, Path> { - Cow::Borrowed(s) - } -} - -#[stable(feature = "cow_from_path", since = "1.6.0")] -impl<'a> From for Cow<'a, Path> { - /// Creates a clone-on-write pointer from an owned - /// instance of [`PathBuf`]. - /// - /// This conversion does not clone or allocate. - #[inline] - fn from(s: PathBuf) -> Cow<'a, Path> { - Cow::Owned(s) - } -} - -#[stable(feature = "cow_from_pathbuf_ref", since = "1.28.0")] -impl<'a> From<&'a PathBuf> for Cow<'a, Path> { - /// Creates a clone-on-write pointer from a reference to - /// [`PathBuf`]. - /// - /// This conversion does not clone or allocate. - #[inline] - fn from(p: &'a PathBuf) -> Cow<'a, Path> { - Cow::Borrowed(p.as_path()) - } -} - -#[stable(feature = "pathbuf_from_cow_path", since = "1.28.0")] -impl<'a> From> for PathBuf { - /// Converts a clone-on-write pointer to an owned path. - /// - /// Converting from a `Cow::Owned` does not clone or allocate. - #[inline] - fn from(p: Cow<'a, Path>) -> Self { - p.into_owned() - } -} - -#[stable(feature = "shared_from_slice2", since = "1.24.0")] -impl From for Arc { - /// Converts a [`PathBuf`] into an [Arc]<[Path]> by moving the [`PathBuf`] data - /// into a new [`Arc`] buffer. - #[inline] - fn from(s: PathBuf) -> Arc { - let arc: Arc = Arc::from(s.into_os_string()); - unsafe { Arc::from_raw(Arc::into_raw(arc) as *const Path) } - } -} - -#[stable(feature = "shared_from_slice2", since = "1.24.0")] -impl From<&Path> for Arc { - /// Converts a [`Path`] into an [`Arc`] by copying the [`Path`] data into a new [`Arc`] buffer. - #[inline] - fn from(s: &Path) -> Arc { - let arc: Arc = Arc::from(s.as_os_str()); - unsafe { Arc::from_raw(Arc::into_raw(arc) as *const Path) } - } -} - -#[stable(feature = "shared_from_slice2", since = "1.24.0")] -impl From for Rc { - /// Converts a [`PathBuf`] into an [Rc]<[Path]> by moving the [`PathBuf`] data into - /// a new [`Rc`] buffer. - #[inline] - fn from(s: PathBuf) -> Rc { - let rc: Rc = Rc::from(s.into_os_string()); - unsafe { Rc::from_raw(Rc::into_raw(rc) as *const Path) } - } -} - -#[stable(feature = "shared_from_slice2", since = "1.24.0")] -impl From<&Path> for Rc { - /// Converts a [`Path`] into an [`Rc`] by copying the [`Path`] data into a new [`Rc`] buffer. - #[inline] - fn from(s: &Path) -> Rc { - let rc: Rc = Rc::from(s.as_os_str()); - unsafe { Rc::from_raw(Rc::into_raw(rc) as *const Path) } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ToOwned for Path { - type Owned = PathBuf; - #[inline] - fn to_owned(&self) -> PathBuf { - self.to_path_buf() - } - #[inline] - fn clone_into(&self, target: &mut PathBuf) { - self.inner.clone_into(&mut target.inner); - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for PathBuf { - #[inline] - fn eq(&self, other: &PathBuf) -> bool { - self.components() == other.components() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Hash for PathBuf { - fn hash(&self, h: &mut H) { - self.as_path().hash(h) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Eq for PathBuf {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialOrd for PathBuf { - #[inline] - fn partial_cmp(&self, other: &PathBuf) -> Option { - Some(compare_components(self.components(), other.components())) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for PathBuf { - #[inline] - fn cmp(&self, other: &PathBuf) -> cmp::Ordering { - compare_components(self.components(), other.components()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef for PathBuf { - #[inline] - fn as_ref(&self) -> &OsStr { - &self.inner[..] - } -} - -/// A slice of a path (akin to [`str`]). -/// -/// This type supports a number of operations for inspecting a path, including -/// breaking the path into its components (separated by `/` on Unix and by either -/// `/` or `\` on Windows), extracting the file name, determining whether the path -/// is absolute, and so on. -/// -/// This is an *unsized* type, meaning that it must always be used behind a -/// pointer like `&` or [`Box`]. For an owned version of this type, -/// see [`PathBuf`]. -/// -/// More details about the overall approach can be found in -/// the [module documentation](self). -/// -/// # Examples -/// -/// ``` -/// use std::path::Path; -/// use std::ffi::OsStr; -/// -/// // Note: this example does work on Windows -/// let path = Path::new("./foo/bar.txt"); -/// -/// let parent = path.parent(); -/// assert_eq!(parent, Some(Path::new("./foo"))); -/// -/// let file_stem = path.file_stem(); -/// assert_eq!(file_stem, Some(OsStr::new("bar"))); -/// -/// let extension = path.extension(); -/// assert_eq!(extension, Some(OsStr::new("txt"))); -/// ``` -#[cfg_attr(not(test), rustc_diagnostic_item = "Path")] -#[stable(feature = "rust1", since = "1.0.0")] -// `Path::new` current implementation relies -// on `Path` being layout-compatible with `OsStr`. -// However, `Path` layout is considered an implementation detail and must not be relied upon. We -// want `repr(transparent)` but we don't want it to show up in rustdoc, so we hide it under -// `cfg(doc)`. This is an ad-hoc implementation of attribute privacy. -#[cfg_attr(not(doc), repr(transparent))] -pub struct Path { - inner: OsStr, -} - -/// An error returned from [`Path::strip_prefix`] if the prefix was not found. -/// -/// This `struct` is created by the [`strip_prefix`] method on [`Path`]. -/// See its documentation for more. -/// -/// [`strip_prefix`]: Path::strip_prefix -#[derive(Debug, Clone, PartialEq, Eq)] -#[stable(since = "1.7.0", feature = "strip_prefix")] -pub struct StripPrefixError(()); - -impl Path { - // The following (private!) function allows construction of a path from a u8 - // slice, which is only safe when it is known to follow the OsStr encoding. - unsafe fn from_u8_slice(s: &[u8]) -> &Path { - unsafe { Path::new(OsStr::from_encoded_bytes_unchecked(s)) } - } - // The following (private!) function reveals the byte encoding used for OsStr. - fn as_u8_slice(&self) -> &[u8] { - self.inner.as_encoded_bytes() - } - - /// Directly wraps a string slice as a `Path` slice. - /// - /// This is a cost-free conversion. - /// - /// # Examples - /// - /// ``` - /// use std::path::Path; - /// - /// Path::new("foo.txt"); - /// ``` - /// - /// You can create `Path`s from `String`s, or even other `Path`s: - /// - /// ``` - /// use std::path::Path; - /// - /// let string = String::from("foo.txt"); - /// let from_string = Path::new(&string); - /// let from_path = Path::new(&from_string); - /// assert_eq!(from_string, from_path); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn new + ?Sized>(s: &S) -> &Path { - unsafe { &*(s.as_ref() as *const OsStr as *const Path) } - } - - fn from_inner_mut(inner: &mut OsStr) -> &mut Path { - // SAFETY: Path is just a wrapper around OsStr, - // therefore converting &mut OsStr to &mut Path is safe. - unsafe { &mut *(inner as *mut OsStr as *mut Path) } - } - - /// Yields the underlying [`OsStr`] slice. - /// - /// # Examples - /// - /// ``` - /// use std::path::Path; - /// - /// let os_str = Path::new("foo.txt").as_os_str(); - /// assert_eq!(os_str, std::ffi::OsStr::new("foo.txt")); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - #[inline] - pub fn as_os_str(&self) -> &OsStr { - &self.inner - } - - /// Yields a mutable reference to the underlying [`OsStr`] slice. - /// - /// # Examples - /// - /// ``` - /// use std::path::{Path, PathBuf}; - /// - /// let mut path = PathBuf::from("Foo.TXT"); - /// - /// assert_ne!(path, Path::new("foo.txt")); - /// - /// path.as_mut_os_str().make_ascii_lowercase(); - /// assert_eq!(path, Path::new("foo.txt")); - /// ``` - #[stable(feature = "path_as_mut_os_str", since = "1.70.0")] - #[must_use] - #[inline] - pub fn as_mut_os_str(&mut self) -> &mut OsStr { - &mut self.inner - } - - /// Yields a [`&str`] slice if the `Path` is valid unicode. - /// - /// This conversion may entail doing a check for UTF-8 validity. - /// Note that validation is performed because non-UTF-8 strings are - /// perfectly valid for some OS. - /// - /// [`&str`]: str - /// - /// # Examples - /// - /// ``` - /// use std::path::Path; - /// - /// let path = Path::new("foo.txt"); - /// assert_eq!(path.to_str(), Some("foo.txt")); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub fn to_str(&self) -> Option<&str> { - self.inner.to_str() - } - - /// Converts a `Path` to a [`Cow`]. - /// - /// Any non-Unicode sequences are replaced with - /// [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD]. - /// - /// [U+FFFD]: super::char::REPLACEMENT_CHARACTER - /// - /// # Examples - /// - /// Calling `to_string_lossy` on a `Path` with valid unicode: - /// - /// ``` - /// use std::path::Path; - /// - /// let path = Path::new("foo.txt"); - /// assert_eq!(path.to_string_lossy(), "foo.txt"); - /// ``` - /// - /// Had `path` contained invalid unicode, the `to_string_lossy` call might - /// have returned `"fo�.txt"`. - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[inline] - pub fn to_string_lossy(&self) -> Cow<'_, str> { - self.inner.to_string_lossy() - } - - /// Converts a `Path` to an owned [`PathBuf`]. - /// - /// # Examples - /// - /// ``` - /// use std::path::{Path, PathBuf}; - /// - /// let path_buf = Path::new("foo.txt").to_path_buf(); - /// assert_eq!(path_buf, PathBuf::from("foo.txt")); - /// ``` - #[rustc_conversion_suggestion] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn to_path_buf(&self) -> PathBuf { - PathBuf::from(self.inner.to_os_string()) - } - - /// Returns `true` if the `Path` is absolute, i.e., if it is independent of - /// the current directory. - /// - /// * On Unix, a path is absolute if it starts with the root, so - /// `is_absolute` and [`has_root`] are equivalent. - /// - /// * On Windows, a path is absolute if it has a prefix and starts with the - /// root: `c:\windows` is absolute, while `c:temp` and `\temp` are not. - /// - /// # Examples - /// - /// ``` - /// use std::path::Path; - /// - /// assert!(!Path::new("foo.txt").is_absolute()); - /// ``` - /// - /// [`has_root`]: Path::has_root - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - #[allow(deprecated)] - pub fn is_absolute(&self) -> bool { - if cfg!(target_os = "redox") { - // FIXME: Allow Redox prefixes - self.has_root() || has_redox_scheme(self.as_u8_slice()) - } else { - self.has_root() && (cfg!(any(unix, target_os = "wasi")) || self.prefix().is_some()) - } - } - - /// Returns `true` if the `Path` is relative, i.e., not absolute. - /// - /// See [`is_absolute`]'s documentation for more details. - /// - /// # Examples - /// - /// ``` - /// use std::path::Path; - /// - /// assert!(Path::new("foo.txt").is_relative()); - /// ``` - /// - /// [`is_absolute`]: Path::is_absolute - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - #[inline] - pub fn is_relative(&self) -> bool { - !self.is_absolute() - } - - fn prefix(&self) -> Option> { - self.components().prefix - } - - /// Returns `true` if the `Path` has a root. - /// - /// * On Unix, a path has a root if it begins with `/`. - /// - /// * On Windows, a path has a root if it: - /// * has no prefix and begins with a separator, e.g., `\windows` - /// * has a prefix followed by a separator, e.g., `c:\windows` but not `c:windows` - /// * has any non-disk prefix, e.g., `\\server\share` - /// - /// # Examples - /// - /// ``` - /// use std::path::Path; - /// - /// assert!(Path::new("/etc/passwd").has_root()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - #[inline] - pub fn has_root(&self) -> bool { - self.components().has_root() - } - - /// Returns the `Path` without its final component, if there is one. - /// - /// This means it returns `Some("")` for relative paths with one component. - /// - /// Returns [`None`] if the path terminates in a root or prefix, or if it's - /// the empty string. - /// - /// # Examples - /// - /// ``` - /// use std::path::Path; - /// - /// let path = Path::new("/foo/bar"); - /// let parent = path.parent().unwrap(); - /// assert_eq!(parent, Path::new("/foo")); - /// - /// let grand_parent = parent.parent().unwrap(); - /// assert_eq!(grand_parent, Path::new("/")); - /// assert_eq!(grand_parent.parent(), None); - /// - /// let relative_path = Path::new("foo/bar"); - /// let parent = relative_path.parent(); - /// assert_eq!(parent, Some(Path::new("foo"))); - /// let grand_parent = parent.and_then(Path::parent); - /// assert_eq!(grand_parent, Some(Path::new(""))); - /// let great_grand_parent = grand_parent.and_then(Path::parent); - /// assert_eq!(great_grand_parent, None); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[doc(alias = "dirname")] - #[must_use] - pub fn parent(&self) -> Option<&Path> { - let mut comps = self.components(); - let comp = comps.next_back(); - comp.and_then(|p| match p { - Component::Normal(_) | Component::CurDir | Component::ParentDir => { - Some(comps.as_path()) - } - _ => None, - }) - } - - /// Produces an iterator over `Path` and its ancestors. - /// - /// The iterator will yield the `Path` that is returned if the [`parent`] method is used zero - /// or more times. If the [`parent`] method returns [`None`], the iterator will do likewise. - /// The iterator will always yield at least one value, namely `Some(&self)`. Next it will yield - /// `&self.parent()`, `&self.parent().and_then(Path::parent)` and so on. - /// - /// # Examples - /// - /// ``` - /// use std::path::Path; - /// - /// let mut ancestors = Path::new("/foo/bar").ancestors(); - /// assert_eq!(ancestors.next(), Some(Path::new("/foo/bar"))); - /// assert_eq!(ancestors.next(), Some(Path::new("/foo"))); - /// assert_eq!(ancestors.next(), Some(Path::new("/"))); - /// assert_eq!(ancestors.next(), None); - /// - /// let mut ancestors = Path::new("../foo/bar").ancestors(); - /// assert_eq!(ancestors.next(), Some(Path::new("../foo/bar"))); - /// assert_eq!(ancestors.next(), Some(Path::new("../foo"))); - /// assert_eq!(ancestors.next(), Some(Path::new(".."))); - /// assert_eq!(ancestors.next(), Some(Path::new(""))); - /// assert_eq!(ancestors.next(), None); - /// ``` - /// - /// [`parent`]: Path::parent - #[stable(feature = "path_ancestors", since = "1.28.0")] - #[inline] - pub fn ancestors(&self) -> Ancestors<'_> { - Ancestors { next: Some(&self) } - } - - /// Returns the final component of the `Path`, if there is one. - /// - /// If the path is a normal file, this is the file name. If it's the path of a directory, this - /// is the directory name. - /// - /// Returns [`None`] if the path terminates in `..`. - /// - /// # Examples - /// - /// ``` - /// use std::path::Path; - /// use std::ffi::OsStr; - /// - /// assert_eq!(Some(OsStr::new("bin")), Path::new("/usr/bin/").file_name()); - /// assert_eq!(Some(OsStr::new("foo.txt")), Path::new("tmp/foo.txt").file_name()); - /// assert_eq!(Some(OsStr::new("foo.txt")), Path::new("foo.txt/.").file_name()); - /// assert_eq!(Some(OsStr::new("foo.txt")), Path::new("foo.txt/.//").file_name()); - /// assert_eq!(None, Path::new("foo.txt/..").file_name()); - /// assert_eq!(None, Path::new("/").file_name()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[doc(alias = "basename")] - #[must_use] - pub fn file_name(&self) -> Option<&OsStr> { - self.components().next_back().and_then(|p| match p { - Component::Normal(p) => Some(p), - _ => None, - }) - } - - /// Returns a path that, when joined onto `base`, yields `self`. - /// - /// # Errors - /// - /// If `base` is not a prefix of `self` (i.e., [`starts_with`] - /// returns `false`), returns [`Err`]. - /// - /// [`starts_with`]: Path::starts_with - /// - /// # Examples - /// - /// ``` - /// use std::path::{Path, PathBuf}; - /// - /// let path = Path::new("/test/haha/foo.txt"); - /// - /// assert_eq!(path.strip_prefix("/"), Ok(Path::new("test/haha/foo.txt"))); - /// assert_eq!(path.strip_prefix("/test"), Ok(Path::new("haha/foo.txt"))); - /// assert_eq!(path.strip_prefix("/test/"), Ok(Path::new("haha/foo.txt"))); - /// assert_eq!(path.strip_prefix("/test/haha/foo.txt"), Ok(Path::new(""))); - /// assert_eq!(path.strip_prefix("/test/haha/foo.txt/"), Ok(Path::new(""))); - /// - /// assert!(path.strip_prefix("test").is_err()); - /// assert!(path.strip_prefix("/haha").is_err()); - /// - /// let prefix = PathBuf::from("/test/"); - /// assert_eq!(path.strip_prefix(prefix), Ok(Path::new("haha/foo.txt"))); - /// ``` - #[stable(since = "1.7.0", feature = "path_strip_prefix")] - pub fn strip_prefix

(&self, base: P) -> Result<&Path, StripPrefixError> - where - P: AsRef, - { - self._strip_prefix(base.as_ref()) - } - - fn _strip_prefix(&self, base: &Path) -> Result<&Path, StripPrefixError> { - iter_after(self.components(), base.components()) - .map(|c| c.as_path()) - .ok_or(StripPrefixError(())) - } - - /// Determines whether `base` is a prefix of `self`. - /// - /// Only considers whole path components to match. - /// - /// # Examples - /// - /// ``` - /// use std::path::Path; - /// - /// let path = Path::new("/etc/passwd"); - /// - /// assert!(path.starts_with("/etc")); - /// assert!(path.starts_with("/etc/")); - /// assert!(path.starts_with("/etc/passwd")); - /// assert!(path.starts_with("/etc/passwd/")); // extra slash is okay - /// assert!(path.starts_with("/etc/passwd///")); // multiple extra slashes are okay - /// - /// assert!(!path.starts_with("/e")); - /// assert!(!path.starts_with("/etc/passwd.txt")); - /// - /// assert!(!Path::new("/etc/foo.rs").starts_with("/etc/foo")); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - pub fn starts_with>(&self, base: P) -> bool { - self._starts_with(base.as_ref()) - } - - fn _starts_with(&self, base: &Path) -> bool { - iter_after(self.components(), base.components()).is_some() - } - - /// Determines whether `child` is a suffix of `self`. - /// - /// Only considers whole path components to match. - /// - /// # Examples - /// - /// ``` - /// use std::path::Path; - /// - /// let path = Path::new("/etc/resolv.conf"); - /// - /// assert!(path.ends_with("resolv.conf")); - /// assert!(path.ends_with("etc/resolv.conf")); - /// assert!(path.ends_with("/etc/resolv.conf")); - /// - /// assert!(!path.ends_with("/resolv.conf")); - /// assert!(!path.ends_with("conf")); // use .extension() instead - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - pub fn ends_with>(&self, child: P) -> bool { - self._ends_with(child.as_ref()) - } - - fn _ends_with(&self, child: &Path) -> bool { - iter_after(self.components().rev(), child.components().rev()).is_some() - } - - /// Extracts the stem (non-extension) portion of [`self.file_name`]. - /// - /// [`self.file_name`]: Path::file_name - /// - /// The stem is: - /// - /// * [`None`], if there is no file name; - /// * The entire file name if there is no embedded `.`; - /// * The entire file name if the file name begins with `.` and has no other `.`s within; - /// * Otherwise, the portion of the file name before the final `.` - /// - /// # Examples - /// - /// ``` - /// use std::path::Path; - /// - /// assert_eq!("foo", Path::new("foo.rs").file_stem().unwrap()); - /// assert_eq!("foo.tar", Path::new("foo.tar.gz").file_stem().unwrap()); - /// ``` - /// - /// # See Also - /// This method is similar to [`Path::file_prefix`], which extracts the portion of the file name - /// before the *first* `.` - /// - /// [`Path::file_prefix`]: Path::file_prefix - /// - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - pub fn file_stem(&self) -> Option<&OsStr> { - self.file_name().map(rsplit_file_at_dot).and_then(|(before, after)| before.or(after)) - } - - /// Extracts the prefix of [`self.file_name`]. - /// - /// The prefix is: - /// - /// * [`None`], if there is no file name; - /// * The entire file name if there is no embedded `.`; - /// * The portion of the file name before the first non-beginning `.`; - /// * The entire file name if the file name begins with `.` and has no other `.`s within; - /// * The portion of the file name before the second `.` if the file name begins with `.` - /// - /// [`self.file_name`]: Path::file_name - /// - /// # Examples - /// - /// ``` - /// # #![feature(path_file_prefix)] - /// use std::path::Path; - /// - /// assert_eq!("foo", Path::new("foo.rs").file_prefix().unwrap()); - /// assert_eq!("foo", Path::new("foo.tar.gz").file_prefix().unwrap()); - /// ``` - /// - /// # See Also - /// This method is similar to [`Path::file_stem`], which extracts the portion of the file name - /// before the *last* `.` - /// - /// [`Path::file_stem`]: Path::file_stem - /// - #[unstable(feature = "path_file_prefix", issue = "86319")] - #[must_use] - pub fn file_prefix(&self) -> Option<&OsStr> { - self.file_name().map(split_file_at_dot).and_then(|(before, _after)| Some(before)) - } - - /// Extracts the extension (without the leading dot) of [`self.file_name`], if possible. - /// - /// The extension is: - /// - /// * [`None`], if there is no file name; - /// * [`None`], if there is no embedded `.`; - /// * [`None`], if the file name begins with `.` and has no other `.`s within; - /// * Otherwise, the portion of the file name after the final `.` - /// - /// [`self.file_name`]: Path::file_name - /// - /// # Examples - /// - /// ``` - /// use std::path::Path; - /// - /// assert_eq!("rs", Path::new("foo.rs").extension().unwrap()); - /// assert_eq!("gz", Path::new("foo.tar.gz").extension().unwrap()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - pub fn extension(&self) -> Option<&OsStr> { - self.file_name().map(rsplit_file_at_dot).and_then(|(before, after)| before.and(after)) - } - - /// Creates an owned [`PathBuf`] with `path` adjoined to `self`. - /// - /// If `path` is absolute, it replaces the current path. - /// - /// See [`PathBuf::push`] for more details on what it means to adjoin a path. - /// - /// # Examples - /// - /// ``` - /// use std::path::{Path, PathBuf}; - /// - /// assert_eq!(Path::new("/etc").join("passwd"), PathBuf::from("/etc/passwd")); - /// assert_eq!(Path::new("/etc").join("/bin/sh"), PathBuf::from("/bin/sh")); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - pub fn join>(&self, path: P) -> PathBuf { - self._join(path.as_ref()) - } - - fn _join(&self, path: &Path) -> PathBuf { - let mut buf = self.to_path_buf(); - buf.push(path); - buf - } - - /// Creates an owned [`PathBuf`] like `self` but with the given file name. - /// - /// See [`PathBuf::set_file_name`] for more details. - /// - /// # Examples - /// - /// ``` - /// use std::path::{Path, PathBuf}; - /// - /// let path = Path::new("/tmp/foo.png"); - /// assert_eq!(path.with_file_name("bar"), PathBuf::from("/tmp/bar")); - /// assert_eq!(path.with_file_name("bar.txt"), PathBuf::from("/tmp/bar.txt")); - /// - /// let path = Path::new("/tmp"); - /// assert_eq!(path.with_file_name("var"), PathBuf::from("/var")); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - pub fn with_file_name>(&self, file_name: S) -> PathBuf { - self._with_file_name(file_name.as_ref()) - } - - fn _with_file_name(&self, file_name: &OsStr) -> PathBuf { - let mut buf = self.to_path_buf(); - buf.set_file_name(file_name); - buf - } - - /// Creates an owned [`PathBuf`] like `self` but with the given extension. - /// - /// See [`PathBuf::set_extension`] for more details. - /// - /// # Examples - /// - /// ``` - /// use std::path::{Path, PathBuf}; - /// - /// let path = Path::new("foo.rs"); - /// assert_eq!(path.with_extension("txt"), PathBuf::from("foo.txt")); - /// - /// let path = Path::new("foo.tar.gz"); - /// assert_eq!(path.with_extension(""), PathBuf::from("foo.tar")); - /// assert_eq!(path.with_extension("xz"), PathBuf::from("foo.tar.xz")); - /// assert_eq!(path.with_extension("").with_extension("txt"), PathBuf::from("foo.txt")); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn with_extension>(&self, extension: S) -> PathBuf { - self._with_extension(extension.as_ref()) - } - - fn _with_extension(&self, extension: &OsStr) -> PathBuf { - let self_len = self.as_os_str().len(); - let self_bytes = self.as_os_str().as_encoded_bytes(); - - let (new_capacity, slice_to_copy) = match self.extension() { - None => { - // Enough capacity for the extension and the dot - let capacity = self_len + extension.len() + 1; - let whole_path = self_bytes.iter(); - (capacity, whole_path) - } - Some(previous_extension) => { - let capacity = self_len + extension.len() - previous_extension.len(); - let path_till_dot = self_bytes[..self_len - previous_extension.len()].iter(); - (capacity, path_till_dot) - } - }; - - let mut new_path = PathBuf::with_capacity(new_capacity); - new_path.as_mut_vec().extend(slice_to_copy); - new_path.set_extension(extension); - new_path - } - - /// Produces an iterator over the [`Component`]s of the path. - /// - /// When parsing the path, there is a small amount of normalization: - /// - /// * Repeated separators are ignored, so `a/b` and `a//b` both have - /// `a` and `b` as components. - /// - /// * Occurrences of `.` are normalized away, except if they are at the - /// beginning of the path. For example, `a/./b`, `a/b/`, `a/b/.` and - /// `a/b` all have `a` and `b` as components, but `./a/b` starts with - /// an additional [`CurDir`] component. - /// - /// * A trailing slash is normalized away, `/a/b` and `/a/b/` are equivalent. - /// - /// Note that no other normalization takes place; in particular, `a/c` - /// and `a/b/../c` are distinct, to account for the possibility that `b` - /// is a symbolic link (so its parent isn't `a`). - /// - /// # Examples - /// - /// ``` - /// use std::path::{Path, Component}; - /// use std::ffi::OsStr; - /// - /// let mut components = Path::new("/tmp/foo.txt").components(); - /// - /// assert_eq!(components.next(), Some(Component::RootDir)); - /// assert_eq!(components.next(), Some(Component::Normal(OsStr::new("tmp")))); - /// assert_eq!(components.next(), Some(Component::Normal(OsStr::new("foo.txt")))); - /// assert_eq!(components.next(), None) - /// ``` - /// - /// [`CurDir`]: Component::CurDir - #[stable(feature = "rust1", since = "1.0.0")] - pub fn components(&self) -> Components<'_> { - let prefix = parse_prefix(self.as_os_str()); - Components { - path: self.as_u8_slice(), - prefix, - has_physical_root: has_physical_root(self.as_u8_slice(), prefix) - || has_redox_scheme(self.as_u8_slice()), - front: State::Prefix, - back: State::Body, - } - } - - /// Produces an iterator over the path's components viewed as [`OsStr`] - /// slices. - /// - /// For more information about the particulars of how the path is separated - /// into components, see [`components`]. - /// - /// [`components`]: Path::components - /// - /// # Examples - /// - /// ``` - /// use std::path::{self, Path}; - /// use std::ffi::OsStr; - /// - /// let mut it = Path::new("/tmp/foo.txt").iter(); - /// assert_eq!(it.next(), Some(OsStr::new(&path::MAIN_SEPARATOR.to_string()))); - /// assert_eq!(it.next(), Some(OsStr::new("tmp"))); - /// assert_eq!(it.next(), Some(OsStr::new("foo.txt"))); - /// assert_eq!(it.next(), None) - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn iter(&self) -> Iter<'_> { - Iter { inner: self.components() } - } - - /// Returns an object that implements [`Display`] for safely printing paths - /// that may contain non-Unicode data. This may perform lossy conversion, - /// depending on the platform. If you would like an implementation which - /// escapes the path please use [`Debug`] instead. - /// - /// [`Display`]: fmt::Display - /// [`Debug`]: fmt::Debug - /// - /// # Examples - /// - /// ``` - /// use std::path::Path; - /// - /// let path = Path::new("/tmp/foo.rs"); - /// - /// println!("{}", path.display()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use = "this does not display the path, \ - it returns an object that can be displayed"] - #[inline] - pub fn display(&self) -> Display<'_> { - Display { inner: self.inner.display() } - } - - /// Queries the file system to get information about a file, directory, etc. - /// - /// This function will traverse symbolic links to query information about the - /// destination file. - /// - /// This is an alias to [`fs::metadata`]. - /// - /// # Examples - /// - /// ```no_run - /// use std::path::Path; - /// - /// let path = Path::new("/Minas/tirith"); - /// let metadata = path.metadata().expect("metadata call failed"); - /// println!("{:?}", metadata.file_type()); - /// ``` - #[stable(feature = "path_ext", since = "1.5.0")] - #[inline] - pub fn metadata(&self) -> io::Result { - fs::metadata(self) - } - - /// Queries the metadata about a file without following symlinks. - /// - /// This is an alias to [`fs::symlink_metadata`]. - /// - /// # Examples - /// - /// ```no_run - /// use std::path::Path; - /// - /// let path = Path::new("/Minas/tirith"); - /// let metadata = path.symlink_metadata().expect("symlink_metadata call failed"); - /// println!("{:?}", metadata.file_type()); - /// ``` - #[stable(feature = "path_ext", since = "1.5.0")] - #[inline] - pub fn symlink_metadata(&self) -> io::Result { - fs::symlink_metadata(self) - } - - /// Returns the canonical, absolute form of the path with all intermediate - /// components normalized and symbolic links resolved. - /// - /// This is an alias to [`fs::canonicalize`]. - /// - /// # Examples - /// - /// ```no_run - /// use std::path::{Path, PathBuf}; - /// - /// let path = Path::new("/foo/test/../test/bar.rs"); - /// assert_eq!(path.canonicalize().unwrap(), PathBuf::from("/foo/test/bar.rs")); - /// ``` - #[stable(feature = "path_ext", since = "1.5.0")] - #[inline] - pub fn canonicalize(&self) -> io::Result { - fs::canonicalize(self) - } - - /// Reads a symbolic link, returning the file that the link points to. - /// - /// This is an alias to [`fs::read_link`]. - /// - /// # Examples - /// - /// ```no_run - /// use std::path::Path; - /// - /// let path = Path::new("/laputa/sky_castle.rs"); - /// let path_link = path.read_link().expect("read_link call failed"); - /// ``` - #[stable(feature = "path_ext", since = "1.5.0")] - #[inline] - pub fn read_link(&self) -> io::Result { - fs::read_link(self) - } - - /// Returns an iterator over the entries within a directory. - /// - /// The iterator will yield instances of [io::Result]<[fs::DirEntry]>. New - /// errors may be encountered after an iterator is initially constructed. - /// - /// This is an alias to [`fs::read_dir`]. - /// - /// # Examples - /// - /// ```no_run - /// use std::path::Path; - /// - /// let path = Path::new("/laputa"); - /// for entry in path.read_dir().expect("read_dir call failed") { - /// if let Ok(entry) = entry { - /// println!("{:?}", entry.path()); - /// } - /// } - /// ``` - #[stable(feature = "path_ext", since = "1.5.0")] - #[inline] - pub fn read_dir(&self) -> io::Result { - fs::read_dir(self) - } - - /// Returns `true` if the path points at an existing entity. - /// - /// Warning: this method may be error-prone, consider using [`try_exists()`] instead! - /// It also has a risk of introducing time-of-check to time-of-use (TOCTOU) bugs. - /// - /// This function will traverse symbolic links to query information about the - /// destination file. - /// - /// If you cannot access the metadata of the file, e.g. because of a - /// permission error or broken symbolic links, this will return `false`. - /// - /// # Examples - /// - /// ```no_run - /// use std::path::Path; - /// assert!(!Path::new("does_not_exist.txt").exists()); - /// ``` - /// - /// # See Also - /// - /// This is a convenience function that coerces errors to false. If you want to - /// check errors, call [`Path::try_exists`]. - /// - /// [`try_exists()`]: Self::try_exists - #[stable(feature = "path_ext", since = "1.5.0")] - #[must_use] - #[inline] - pub fn exists(&self) -> bool { - fs::metadata(self).is_ok() - } - - /// Returns `Ok(true)` if the path points at an existing entity. - /// - /// This function will traverse symbolic links to query information about the - /// destination file. In case of broken symbolic links this will return `Ok(false)`. - /// - /// [`Path::exists()`] only checks whether or not a path was both found and readable. By - /// contrast, `try_exists` will return `Ok(true)` or `Ok(false)`, respectively, if the path - /// was _verified_ to exist or not exist. If its existence can neither be confirmed nor - /// denied, it will propagate an `Err(_)` instead. This can be the case if e.g. listing - /// permission is denied on one of the parent directories. - /// - /// Note that while this avoids some pitfalls of the `exists()` method, it still can not - /// prevent time-of-check to time-of-use (TOCTOU) bugs. You should only use it in scenarios - /// where those bugs are not an issue. - /// - /// # Examples - /// - /// ```no_run - /// use std::path::Path; - /// assert!(!Path::new("does_not_exist.txt").try_exists().expect("Can't check existence of file does_not_exist.txt")); - /// assert!(Path::new("/root/secret_file.txt").try_exists().is_err()); - /// ``` - /// - /// [`exists()`]: Self::exists - #[stable(feature = "path_try_exists", since = "1.63.0")] - #[inline] - pub fn try_exists(&self) -> io::Result { - fs::try_exists(self) - } - - /// Returns `true` if the path exists on disk and is pointing at a regular file. - /// - /// This function will traverse symbolic links to query information about the - /// destination file. - /// - /// If you cannot access the metadata of the file, e.g. because of a - /// permission error or broken symbolic links, this will return `false`. - /// - /// # Examples - /// - /// ```no_run - /// use std::path::Path; - /// assert_eq!(Path::new("./is_a_directory/").is_file(), false); - /// assert_eq!(Path::new("a_file.txt").is_file(), true); - /// ``` - /// - /// # See Also - /// - /// This is a convenience function that coerces errors to false. If you want to - /// check errors, call [`fs::metadata`] and handle its [`Result`]. Then call - /// [`fs::Metadata::is_file`] if it was [`Ok`]. - /// - /// When the goal is simply to read from (or write to) the source, the most - /// reliable way to test the source can be read (or written to) is to open - /// it. Only using `is_file` can break workflows like `diff <( prog_a )` on - /// a Unix-like system for example. See [`fs::File::open`] or - /// [`fs::OpenOptions::open`] for more information. - #[stable(feature = "path_ext", since = "1.5.0")] - #[must_use] - pub fn is_file(&self) -> bool { - fs::metadata(self).map(|m| m.is_file()).unwrap_or(false) - } - - /// Returns `true` if the path exists on disk and is pointing at a directory. - /// - /// This function will traverse symbolic links to query information about the - /// destination file. - /// - /// If you cannot access the metadata of the file, e.g. because of a - /// permission error or broken symbolic links, this will return `false`. - /// - /// # Examples - /// - /// ```no_run - /// use std::path::Path; - /// assert_eq!(Path::new("./is_a_directory/").is_dir(), true); - /// assert_eq!(Path::new("a_file.txt").is_dir(), false); - /// ``` - /// - /// # See Also - /// - /// This is a convenience function that coerces errors to false. If you want to - /// check errors, call [`fs::metadata`] and handle its [`Result`]. Then call - /// [`fs::Metadata::is_dir`] if it was [`Ok`]. - #[stable(feature = "path_ext", since = "1.5.0")] - #[must_use] - pub fn is_dir(&self) -> bool { - fs::metadata(self).map(|m| m.is_dir()).unwrap_or(false) - } - - /// Returns `true` if the path exists on disk and is pointing at a symbolic link. - /// - /// This function will not traverse symbolic links. - /// In case of a broken symbolic link this will also return true. - /// - /// If you cannot access the directory containing the file, e.g., because of a - /// permission error, this will return false. - /// - /// # Examples - /// - #[cfg_attr(unix, doc = "```no_run")] - #[cfg_attr(not(unix), doc = "```ignore")] - /// use std::path::Path; - /// use std::os::unix::fs::symlink; - /// - /// let link_path = Path::new("link"); - /// symlink("/origin_does_not_exist/", link_path).unwrap(); - /// assert_eq!(link_path.is_symlink(), true); - /// assert_eq!(link_path.exists(), false); - /// ``` - /// - /// # See Also - /// - /// This is a convenience function that coerces errors to false. If you want to - /// check errors, call [`fs::symlink_metadata`] and handle its [`Result`]. Then call - /// [`fs::Metadata::is_symlink`] if it was [`Ok`]. - #[must_use] - #[stable(feature = "is_symlink", since = "1.58.0")] - pub fn is_symlink(&self) -> bool { - fs::symlink_metadata(self).map(|m| m.is_symlink()).unwrap_or(false) - } - - /// Converts a [`Box`](Box) into a [`PathBuf`] without copying or - /// allocating. - #[stable(feature = "into_boxed_path", since = "1.20.0")] - #[must_use = "`self` will be dropped if the result is not used"] - pub fn into_path_buf(self: Box) -> PathBuf { - let rw = Box::into_raw(self) as *mut OsStr; - let inner = unsafe { Box::from_raw(rw) }; - PathBuf { inner: OsString::from(inner) } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef for Path { - #[inline] - fn as_ref(&self) -> &OsStr { - &self.inner - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for Path { - fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&self.inner, formatter) - } -} - -/// Helper struct for safely printing paths with [`format!`] and `{}`. -/// -/// A [`Path`] might contain non-Unicode data. This `struct` implements the -/// [`Display`] trait in a way that mitigates that. It is created by the -/// [`display`](Path::display) method on [`Path`]. This may perform lossy -/// conversion, depending on the platform. If you would like an implementation -/// which escapes the path please use [`Debug`] instead. -/// -/// # Examples -/// -/// ``` -/// use std::path::Path; -/// -/// let path = Path::new("/tmp/foo.rs"); -/// -/// println!("{}", path.display()); -/// ``` -/// -/// [`Display`]: fmt::Display -/// [`format!`]: crate::format -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Display<'a> { - inner: os_str::Display<'a>, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for Display<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&self.inner, f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for Display<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt(&self.inner, f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for Path { - #[inline] - fn eq(&self, other: &Path) -> bool { - self.components() == other.components() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Hash for Path { - fn hash(&self, h: &mut H) { - let bytes = self.as_u8_slice(); - let (prefix_len, verbatim) = match parse_prefix(&self.inner) { - Some(prefix) => { - prefix.hash(h); - (prefix.len(), prefix.is_verbatim()) - } - None => (0, false), - }; - let bytes = &bytes[prefix_len..]; - - let mut component_start = 0; - let mut bytes_hashed = 0; - - for i in 0..bytes.len() { - let is_sep = if verbatim { is_verbatim_sep(bytes[i]) } else { is_sep_byte(bytes[i]) }; - if is_sep { - if i > component_start { - let to_hash = &bytes[component_start..i]; - h.write(to_hash); - bytes_hashed += to_hash.len(); - } - - // skip over separator and optionally a following CurDir item - // since components() would normalize these away. - component_start = i + 1; - - let tail = &bytes[component_start..]; - - if !verbatim { - component_start += match tail { - [b'.'] => 1, - [b'.', sep @ _, ..] if is_sep_byte(*sep) => 1, - _ => 0, - }; - } - } - } - - if component_start < bytes.len() { - let to_hash = &bytes[component_start..]; - h.write(to_hash); - bytes_hashed += to_hash.len(); - } - - h.write_usize(bytes_hashed); - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Eq for Path {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialOrd for Path { - #[inline] - fn partial_cmp(&self, other: &Path) -> Option { - Some(compare_components(self.components(), other.components())) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for Path { - #[inline] - fn cmp(&self, other: &Path) -> cmp::Ordering { - compare_components(self.components(), other.components()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef for Path { - #[inline] - fn as_ref(&self) -> &Path { - self - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef for OsStr { - #[inline] - fn as_ref(&self) -> &Path { - Path::new(self) - } -} - -#[stable(feature = "cow_os_str_as_ref_path", since = "1.8.0")] -impl AsRef for Cow<'_, OsStr> { - #[inline] - fn as_ref(&self) -> &Path { - Path::new(self) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef for OsString { - #[inline] - fn as_ref(&self) -> &Path { - Path::new(self) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef for str { - #[inline] - fn as_ref(&self) -> &Path { - Path::new(self) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef for String { - #[inline] - fn as_ref(&self) -> &Path { - Path::new(self) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef for PathBuf { - #[inline] - fn as_ref(&self) -> &Path { - self - } -} - -#[stable(feature = "path_into_iter", since = "1.6.0")] -impl<'a> IntoIterator for &'a PathBuf { - type Item = &'a OsStr; - type IntoIter = Iter<'a>; - #[inline] - fn into_iter(self) -> Iter<'a> { - self.iter() - } -} - -#[stable(feature = "path_into_iter", since = "1.6.0")] -impl<'a> IntoIterator for &'a Path { - type Item = &'a OsStr; - type IntoIter = Iter<'a>; - #[inline] - fn into_iter(self) -> Iter<'a> { - self.iter() - } -} - -macro_rules! impl_cmp { - (<$($life:lifetime),*> $lhs:ty, $rhs: ty) => { - #[stable(feature = "partialeq_path", since = "1.6.0")] - impl<$($life),*> PartialEq<$rhs> for $lhs { - #[inline] - fn eq(&self, other: &$rhs) -> bool { - ::eq(self, other) - } - } - - #[stable(feature = "partialeq_path", since = "1.6.0")] - impl<$($life),*> PartialEq<$lhs> for $rhs { - #[inline] - fn eq(&self, other: &$lhs) -> bool { - ::eq(self, other) - } - } - - #[stable(feature = "cmp_path", since = "1.8.0")] - impl<$($life),*> PartialOrd<$rhs> for $lhs { - #[inline] - fn partial_cmp(&self, other: &$rhs) -> Option { - ::partial_cmp(self, other) - } - } - - #[stable(feature = "cmp_path", since = "1.8.0")] - impl<$($life),*> PartialOrd<$lhs> for $rhs { - #[inline] - fn partial_cmp(&self, other: &$lhs) -> Option { - ::partial_cmp(self, other) - } - } - }; -} - -impl_cmp!(<> PathBuf, Path); -impl_cmp!(<'a> PathBuf, &'a Path); -impl_cmp!(<'a> Cow<'a, Path>, Path); -impl_cmp!(<'a, 'b> Cow<'a, Path>, &'b Path); -impl_cmp!(<'a> Cow<'a, Path>, PathBuf); - -macro_rules! impl_cmp_os_str { - (<$($life:lifetime),*> $lhs:ty, $rhs: ty) => { - #[stable(feature = "cmp_path", since = "1.8.0")] - impl<$($life),*> PartialEq<$rhs> for $lhs { - #[inline] - fn eq(&self, other: &$rhs) -> bool { - ::eq(self, other.as_ref()) - } - } - - #[stable(feature = "cmp_path", since = "1.8.0")] - impl<$($life),*> PartialEq<$lhs> for $rhs { - #[inline] - fn eq(&self, other: &$lhs) -> bool { - ::eq(self.as_ref(), other) - } - } - - #[stable(feature = "cmp_path", since = "1.8.0")] - impl<$($life),*> PartialOrd<$rhs> for $lhs { - #[inline] - fn partial_cmp(&self, other: &$rhs) -> Option { - ::partial_cmp(self, other.as_ref()) - } - } - - #[stable(feature = "cmp_path", since = "1.8.0")] - impl<$($life),*> PartialOrd<$lhs> for $rhs { - #[inline] - fn partial_cmp(&self, other: &$lhs) -> Option { - ::partial_cmp(self.as_ref(), other) - } - } - }; -} - -impl_cmp_os_str!(<> PathBuf, OsStr); -impl_cmp_os_str!(<'a> PathBuf, &'a OsStr); -impl_cmp_os_str!(<'a> PathBuf, Cow<'a, OsStr>); -impl_cmp_os_str!(<> PathBuf, OsString); -impl_cmp_os_str!(<> Path, OsStr); -impl_cmp_os_str!(<'a> Path, &'a OsStr); -impl_cmp_os_str!(<'a> Path, Cow<'a, OsStr>); -impl_cmp_os_str!(<> Path, OsString); -impl_cmp_os_str!(<'a> &'a Path, OsStr); -impl_cmp_os_str!(<'a, 'b> &'a Path, Cow<'b, OsStr>); -impl_cmp_os_str!(<'a> &'a Path, OsString); -impl_cmp_os_str!(<'a> Cow<'a, Path>, OsStr); -impl_cmp_os_str!(<'a, 'b> Cow<'a, Path>, &'b OsStr); -impl_cmp_os_str!(<'a> Cow<'a, Path>, OsString); - -#[stable(since = "1.7.0", feature = "strip_prefix")] -impl fmt::Display for StripPrefixError { - #[allow(deprecated, deprecated_in_future)] - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.description().fmt(f) - } -} - -#[stable(since = "1.7.0", feature = "strip_prefix")] -impl Error for StripPrefixError { - #[allow(deprecated)] - fn description(&self) -> &str { - "prefix not found" - } -} - -/// Makes the path absolute without accessing the filesystem. -/// -/// If the path is relative, the current directory is used as the base directory. -/// All intermediate components will be resolved according to platforms-specific -/// rules but unlike [`canonicalize`][crate::fs::canonicalize] this does not -/// resolve symlinks and may succeed even if the path does not exist. -/// -/// If the `path` is empty or getting the -/// [current directory][crate::env::current_dir] fails then an error will be -/// returned. -/// -/// # Examples -/// -/// ## POSIX paths -/// -/// ``` -/// # #[cfg(unix)] -/// fn main() -> std::io::Result<()> { -/// use std::path::{self, Path}; -/// -/// // Relative to absolute -/// let absolute = path::absolute("foo/./bar")?; -/// assert!(absolute.ends_with("foo/bar")); -/// -/// // Absolute to absolute -/// let absolute = path::absolute("/foo//test/.././bar.rs")?; -/// assert_eq!(absolute, Path::new("/foo/test/../bar.rs")); -/// Ok(()) -/// } -/// # #[cfg(not(unix))] -/// # fn main() {} -/// ``` -/// -/// The path is resolved using [POSIX semantics][posix-semantics] except that -/// it stops short of resolving symlinks. This means it will keep `..` -/// components and trailing slashes. -/// -/// ## Windows paths -/// -/// ``` -/// # #[cfg(windows)] -/// fn main() -> std::io::Result<()> { -/// use std::path::{self, Path}; -/// -/// // Relative to absolute -/// let absolute = path::absolute("foo/./bar")?; -/// assert!(absolute.ends_with(r"foo\bar")); -/// -/// // Absolute to absolute -/// let absolute = path::absolute(r"C:\foo//test\..\./bar.rs")?; -/// -/// assert_eq!(absolute, Path::new(r"C:\foo\bar.rs")); -/// Ok(()) -/// } -/// # #[cfg(not(windows))] -/// # fn main() {} -/// ``` -/// -/// For verbatim paths this will simply return the path as given. For other -/// paths this is currently equivalent to calling -/// [`GetFullPathNameW`][windows-path]. -/// -/// Note that this [may change in the future][changes]. -/// -/// [changes]: io#platform-specific-behavior -/// [posix-semantics]: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13 -/// [windows-path]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getfullpathnamew -#[stable(feature = "absolute_path", since = "1.79.0")] -pub fn absolute>(path: P) -> io::Result { - let path = path.as_ref(); - if path.as_os_str().is_empty() { - Err(io::const_io_error!(io::ErrorKind::InvalidInput, "cannot make an empty path absolute",)) - } else { - sys::path::absolute(path) - } -} diff --git a/library/std/src/path/tests.rs b/library/std/src/path/tests.rs deleted file mode 100644 index fde6ed4f0c057..0000000000000 --- a/library/std/src/path/tests.rs +++ /dev/null @@ -1,1914 +0,0 @@ -use super::*; - -use crate::collections::{BTreeSet, HashSet}; -use crate::hash::DefaultHasher; -use core::hint::black_box; - -#[allow(unknown_lints, unused_macro_rules)] -macro_rules! t ( - ($path:expr, iter: $iter:expr) => ( - { - let path = Path::new($path); - - // Forward iteration - let comps = path.iter() - .map(|p| p.to_string_lossy().into_owned()) - .collect::>(); - let exp: &[&str] = &$iter; - let exps = exp.iter().map(|s| s.to_string()).collect::>(); - assert!(comps == exps, "iter: Expected {:?}, found {:?}", - exps, comps); - - // Reverse iteration - let comps = Path::new($path).iter().rev() - .map(|p| p.to_string_lossy().into_owned()) - .collect::>(); - let exps = exps.into_iter().rev().collect::>(); - assert!(comps == exps, "iter().rev(): Expected {:?}, found {:?}", - exps, comps); - } - ); - - ($path:expr, has_root: $has_root:expr, is_absolute: $is_absolute:expr) => ( - { - let path = Path::new($path); - - let act_root = path.has_root(); - assert!(act_root == $has_root, "has_root: Expected {:?}, found {:?}", - $has_root, act_root); - - let act_abs = path.is_absolute(); - assert!(act_abs == $is_absolute, "is_absolute: Expected {:?}, found {:?}", - $is_absolute, act_abs); - } - ); - - ($path:expr, parent: $parent:expr, file_name: $file:expr) => ( - { - let path = Path::new($path); - - let parent = path.parent().map(|p| p.to_str().unwrap()); - let exp_parent: Option<&str> = $parent; - assert!(parent == exp_parent, "parent: Expected {:?}, found {:?}", - exp_parent, parent); - - let file = path.file_name().map(|p| p.to_str().unwrap()); - let exp_file: Option<&str> = $file; - assert!(file == exp_file, "file_name: Expected {:?}, found {:?}", - exp_file, file); - } - ); - - ($path:expr, file_stem: $file_stem:expr, extension: $extension:expr) => ( - { - let path = Path::new($path); - - let stem = path.file_stem().map(|p| p.to_str().unwrap()); - let exp_stem: Option<&str> = $file_stem; - assert!(stem == exp_stem, "file_stem: Expected {:?}, found {:?}", - exp_stem, stem); - - let ext = path.extension().map(|p| p.to_str().unwrap()); - let exp_ext: Option<&str> = $extension; - assert!(ext == exp_ext, "extension: Expected {:?}, found {:?}", - exp_ext, ext); - } - ); - - ($path:expr, file_prefix: $file_prefix:expr, extension: $extension:expr) => ( - { - let path = Path::new($path); - - let prefix = path.file_prefix().map(|p| p.to_str().unwrap()); - let exp_prefix: Option<&str> = $file_prefix; - assert!(prefix == exp_prefix, "file_prefix: Expected {:?}, found {:?}", - exp_prefix, prefix); - - let ext = path.extension().map(|p| p.to_str().unwrap()); - let exp_ext: Option<&str> = $extension; - assert!(ext == exp_ext, "extension: Expected {:?}, found {:?}", - exp_ext, ext); - } - ); - - ($path:expr, iter: $iter:expr, - has_root: $has_root:expr, is_absolute: $is_absolute:expr, - parent: $parent:expr, file_name: $file:expr, - file_stem: $file_stem:expr, extension: $extension:expr, - file_prefix: $file_prefix:expr) => ( - { - t!($path, iter: $iter); - t!($path, has_root: $has_root, is_absolute: $is_absolute); - t!($path, parent: $parent, file_name: $file); - t!($path, file_stem: $file_stem, extension: $extension); - t!($path, file_prefix: $file_prefix, extension: $extension); - } - ); -); - -#[test] -fn into() { - use crate::borrow::Cow; - - let static_path = Path::new("/home/foo"); - let static_cow_path: Cow<'static, Path> = static_path.into(); - let pathbuf = PathBuf::from("/home/foo"); - - { - let path: &Path = &pathbuf; - let borrowed_cow_path: Cow<'_, Path> = path.into(); - - assert_eq!(static_cow_path, borrowed_cow_path); - } - - let owned_cow_path: Cow<'static, Path> = pathbuf.into(); - - assert_eq!(static_cow_path, owned_cow_path); -} - -#[test] -#[cfg(unix)] -pub fn test_decompositions_unix() { - t!("", - iter: [], - has_root: false, - is_absolute: false, - parent: None, - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("foo", - iter: ["foo"], - has_root: false, - is_absolute: false, - parent: Some(""), - file_name: Some("foo"), - file_stem: Some("foo"), - extension: None, - file_prefix: Some("foo") - ); - - t!("/", - iter: ["/"], - has_root: true, - is_absolute: true, - parent: None, - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("/foo", - iter: ["/", "foo"], - has_root: true, - is_absolute: true, - parent: Some("/"), - file_name: Some("foo"), - file_stem: Some("foo"), - extension: None, - file_prefix: Some("foo") - ); - - t!("foo/", - iter: ["foo"], - has_root: false, - is_absolute: false, - parent: Some(""), - file_name: Some("foo"), - file_stem: Some("foo"), - extension: None, - file_prefix: Some("foo") - ); - - t!("/foo/", - iter: ["/", "foo"], - has_root: true, - is_absolute: true, - parent: Some("/"), - file_name: Some("foo"), - file_stem: Some("foo"), - extension: None, - file_prefix: Some("foo") - ); - - t!("foo/bar", - iter: ["foo", "bar"], - has_root: false, - is_absolute: false, - parent: Some("foo"), - file_name: Some("bar"), - file_stem: Some("bar"), - extension: None, - file_prefix: Some("bar") - ); - - t!("/foo/bar", - iter: ["/", "foo", "bar"], - has_root: true, - is_absolute: true, - parent: Some("/foo"), - file_name: Some("bar"), - file_stem: Some("bar"), - extension: None, - file_prefix: Some("bar") - ); - - t!("///foo///", - iter: ["/", "foo"], - has_root: true, - is_absolute: true, - parent: Some("/"), - file_name: Some("foo"), - file_stem: Some("foo"), - extension: None, - file_prefix: Some("foo") - ); - - t!("///foo///bar", - iter: ["/", "foo", "bar"], - has_root: true, - is_absolute: true, - parent: Some("///foo"), - file_name: Some("bar"), - file_stem: Some("bar"), - extension: None, - file_prefix: Some("bar") - ); - - t!("./.", - iter: ["."], - has_root: false, - is_absolute: false, - parent: Some(""), - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("/..", - iter: ["/", ".."], - has_root: true, - is_absolute: true, - parent: Some("/"), - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("../", - iter: [".."], - has_root: false, - is_absolute: false, - parent: Some(""), - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("foo/.", - iter: ["foo"], - has_root: false, - is_absolute: false, - parent: Some(""), - file_name: Some("foo"), - file_stem: Some("foo"), - extension: None, - file_prefix: Some("foo") - ); - - t!("foo/..", - iter: ["foo", ".."], - has_root: false, - is_absolute: false, - parent: Some("foo"), - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("foo/./", - iter: ["foo"], - has_root: false, - is_absolute: false, - parent: Some(""), - file_name: Some("foo"), - file_stem: Some("foo"), - extension: None, - file_prefix: Some("foo") - ); - - t!("foo/./bar", - iter: ["foo", "bar"], - has_root: false, - is_absolute: false, - parent: Some("foo"), - file_name: Some("bar"), - file_stem: Some("bar"), - extension: None, - file_prefix: Some("bar") - ); - - t!("foo/../", - iter: ["foo", ".."], - has_root: false, - is_absolute: false, - parent: Some("foo"), - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("foo/../bar", - iter: ["foo", "..", "bar"], - has_root: false, - is_absolute: false, - parent: Some("foo/.."), - file_name: Some("bar"), - file_stem: Some("bar"), - extension: None, - file_prefix: Some("bar") - ); - - t!("./a", - iter: [".", "a"], - has_root: false, - is_absolute: false, - parent: Some("."), - file_name: Some("a"), - file_stem: Some("a"), - extension: None, - file_prefix: Some("a") - ); - - t!(".", - iter: ["."], - has_root: false, - is_absolute: false, - parent: Some(""), - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("./", - iter: ["."], - has_root: false, - is_absolute: false, - parent: Some(""), - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("a/b", - iter: ["a", "b"], - has_root: false, - is_absolute: false, - parent: Some("a"), - file_name: Some("b"), - file_stem: Some("b"), - extension: None, - file_prefix: Some("b") - ); - - t!("a//b", - iter: ["a", "b"], - has_root: false, - is_absolute: false, - parent: Some("a"), - file_name: Some("b"), - file_stem: Some("b"), - extension: None, - file_prefix: Some("b") - ); - - t!("a/./b", - iter: ["a", "b"], - has_root: false, - is_absolute: false, - parent: Some("a"), - file_name: Some("b"), - file_stem: Some("b"), - extension: None, - file_prefix: Some("b") - ); - - t!("a/b/c", - iter: ["a", "b", "c"], - has_root: false, - is_absolute: false, - parent: Some("a/b"), - file_name: Some("c"), - file_stem: Some("c"), - extension: None, - file_prefix: Some("c") - ); - - t!(".foo", - iter: [".foo"], - has_root: false, - is_absolute: false, - parent: Some(""), - file_name: Some(".foo"), - file_stem: Some(".foo"), - extension: None, - file_prefix: Some(".foo") - ); - - t!("a/.foo", - iter: ["a", ".foo"], - has_root: false, - is_absolute: false, - parent: Some("a"), - file_name: Some(".foo"), - file_stem: Some(".foo"), - extension: None, - file_prefix: Some(".foo") - ); - - t!("a/.rustfmt.toml", - iter: ["a", ".rustfmt.toml"], - has_root: false, - is_absolute: false, - parent: Some("a"), - file_name: Some(".rustfmt.toml"), - file_stem: Some(".rustfmt"), - extension: Some("toml"), - file_prefix: Some(".rustfmt") - ); - - t!("a/.x.y.z", - iter: ["a", ".x.y.z"], - has_root: false, - is_absolute: false, - parent: Some("a"), - file_name: Some(".x.y.z"), - file_stem: Some(".x.y"), - extension: Some("z"), - file_prefix: Some(".x") - ); -} - -#[test] -#[cfg(windows)] -pub fn test_decompositions_windows() { - t!("", - iter: [], - has_root: false, - is_absolute: false, - parent: None, - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("foo", - iter: ["foo"], - has_root: false, - is_absolute: false, - parent: Some(""), - file_name: Some("foo"), - file_stem: Some("foo"), - extension: None, - file_prefix: Some("foo") - ); - - t!("/", - iter: ["\\"], - has_root: true, - is_absolute: false, - parent: None, - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("\\", - iter: ["\\"], - has_root: true, - is_absolute: false, - parent: None, - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("c:", - iter: ["c:"], - has_root: false, - is_absolute: false, - parent: None, - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("c:\\", - iter: ["c:", "\\"], - has_root: true, - is_absolute: true, - parent: None, - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("c:/", - iter: ["c:", "\\"], - has_root: true, - is_absolute: true, - parent: None, - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("/foo", - iter: ["\\", "foo"], - has_root: true, - is_absolute: false, - parent: Some("/"), - file_name: Some("foo"), - file_stem: Some("foo"), - extension: None, - file_prefix: Some("foo") - ); - - t!("foo/", - iter: ["foo"], - has_root: false, - is_absolute: false, - parent: Some(""), - file_name: Some("foo"), - file_stem: Some("foo"), - extension: None, - file_prefix: Some("foo") - ); - - t!("/foo/", - iter: ["\\", "foo"], - has_root: true, - is_absolute: false, - parent: Some("/"), - file_name: Some("foo"), - file_stem: Some("foo"), - extension: None, - file_prefix: Some("foo") - ); - - t!("foo/bar", - iter: ["foo", "bar"], - has_root: false, - is_absolute: false, - parent: Some("foo"), - file_name: Some("bar"), - file_stem: Some("bar"), - extension: None, - file_prefix: Some("bar") - ); - - t!("/foo/bar", - iter: ["\\", "foo", "bar"], - has_root: true, - is_absolute: false, - parent: Some("/foo"), - file_name: Some("bar"), - file_stem: Some("bar"), - extension: None, - file_prefix: Some("bar") - ); - - t!("///foo///", - iter: ["\\", "foo"], - has_root: true, - is_absolute: false, - parent: Some("/"), - file_name: Some("foo"), - file_stem: Some("foo"), - extension: None, - file_prefix: Some("foo") - ); - - t!("///foo///bar", - iter: ["\\", "foo", "bar"], - has_root: true, - is_absolute: false, - parent: Some("///foo"), - file_name: Some("bar"), - file_stem: Some("bar"), - extension: None, - file_prefix: Some("bar") - ); - - t!("./.", - iter: ["."], - has_root: false, - is_absolute: false, - parent: Some(""), - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("/..", - iter: ["\\", ".."], - has_root: true, - is_absolute: false, - parent: Some("/"), - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("../", - iter: [".."], - has_root: false, - is_absolute: false, - parent: Some(""), - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("foo/.", - iter: ["foo"], - has_root: false, - is_absolute: false, - parent: Some(""), - file_name: Some("foo"), - file_stem: Some("foo"), - extension: None, - file_prefix: Some("foo") - ); - - t!("foo/..", - iter: ["foo", ".."], - has_root: false, - is_absolute: false, - parent: Some("foo"), - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("foo/./", - iter: ["foo"], - has_root: false, - is_absolute: false, - parent: Some(""), - file_name: Some("foo"), - file_stem: Some("foo"), - extension: None, - file_prefix: Some("foo") - ); - - t!("foo/./bar", - iter: ["foo", "bar"], - has_root: false, - is_absolute: false, - parent: Some("foo"), - file_name: Some("bar"), - file_stem: Some("bar"), - extension: None, - file_prefix: Some("bar") - ); - - t!("foo/../", - iter: ["foo", ".."], - has_root: false, - is_absolute: false, - parent: Some("foo"), - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("foo/../bar", - iter: ["foo", "..", "bar"], - has_root: false, - is_absolute: false, - parent: Some("foo/.."), - file_name: Some("bar"), - file_stem: Some("bar"), - extension: None, - file_prefix: Some("bar") - ); - - t!("./a", - iter: [".", "a"], - has_root: false, - is_absolute: false, - parent: Some("."), - file_name: Some("a"), - file_stem: Some("a"), - extension: None, - file_prefix: Some("a") - ); - - t!(".", - iter: ["."], - has_root: false, - is_absolute: false, - parent: Some(""), - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("./", - iter: ["."], - has_root: false, - is_absolute: false, - parent: Some(""), - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("a/b", - iter: ["a", "b"], - has_root: false, - is_absolute: false, - parent: Some("a"), - file_name: Some("b"), - file_stem: Some("b"), - extension: None, - file_prefix: Some("b") - ); - - t!("a//b", - iter: ["a", "b"], - has_root: false, - is_absolute: false, - parent: Some("a"), - file_name: Some("b"), - file_stem: Some("b"), - extension: None, - file_prefix: Some("b") - ); - - t!("a/./b", - iter: ["a", "b"], - has_root: false, - is_absolute: false, - parent: Some("a"), - file_name: Some("b"), - file_stem: Some("b"), - extension: None, - file_prefix: Some("b") - ); - - t!("a/b/c", - iter: ["a", "b", "c"], - has_root: false, - is_absolute: false, - parent: Some("a/b"), - file_name: Some("c"), - file_stem: Some("c"), - extension: None, - file_prefix: Some("c") - ); - - t!("a\\b\\c", - iter: ["a", "b", "c"], - has_root: false, - is_absolute: false, - parent: Some("a\\b"), - file_name: Some("c"), - file_stem: Some("c"), - extension: None, - file_prefix: Some("c") - ); - - t!("\\a", - iter: ["\\", "a"], - has_root: true, - is_absolute: false, - parent: Some("\\"), - file_name: Some("a"), - file_stem: Some("a"), - extension: None, - file_prefix: Some("a") - ); - - t!("c:\\foo.txt", - iter: ["c:", "\\", "foo.txt"], - has_root: true, - is_absolute: true, - parent: Some("c:\\"), - file_name: Some("foo.txt"), - file_stem: Some("foo"), - extension: Some("txt"), - file_prefix: Some("foo") - ); - - t!("\\\\server\\share\\foo.txt", - iter: ["\\\\server\\share", "\\", "foo.txt"], - has_root: true, - is_absolute: true, - parent: Some("\\\\server\\share\\"), - file_name: Some("foo.txt"), - file_stem: Some("foo"), - extension: Some("txt"), - file_prefix: Some("foo") - ); - - t!("\\\\server\\share", - iter: ["\\\\server\\share", "\\"], - has_root: true, - is_absolute: true, - parent: None, - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("\\\\server", - iter: ["\\", "server"], - has_root: true, - is_absolute: false, - parent: Some("\\"), - file_name: Some("server"), - file_stem: Some("server"), - extension: None, - file_prefix: Some("server") - ); - - t!("\\\\?\\bar\\foo.txt", - iter: ["\\\\?\\bar", "\\", "foo.txt"], - has_root: true, - is_absolute: true, - parent: Some("\\\\?\\bar\\"), - file_name: Some("foo.txt"), - file_stem: Some("foo"), - extension: Some("txt"), - file_prefix: Some("foo") - ); - - t!("\\\\?\\bar", - iter: ["\\\\?\\bar"], - has_root: true, - is_absolute: true, - parent: None, - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("\\\\?\\", - iter: ["\\\\?\\"], - has_root: true, - is_absolute: true, - parent: None, - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("\\\\?\\UNC\\server\\share\\foo.txt", - iter: ["\\\\?\\UNC\\server\\share", "\\", "foo.txt"], - has_root: true, - is_absolute: true, - parent: Some("\\\\?\\UNC\\server\\share\\"), - file_name: Some("foo.txt"), - file_stem: Some("foo"), - extension: Some("txt"), - file_prefix: Some("foo") - ); - - t!("\\\\?\\UNC\\server", - iter: ["\\\\?\\UNC\\server"], - has_root: true, - is_absolute: true, - parent: None, - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("\\\\?\\UNC\\", - iter: ["\\\\?\\UNC\\"], - has_root: true, - is_absolute: true, - parent: None, - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("\\\\?\\C:\\foo.txt", - iter: ["\\\\?\\C:", "\\", "foo.txt"], - has_root: true, - is_absolute: true, - parent: Some("\\\\?\\C:\\"), - file_name: Some("foo.txt"), - file_stem: Some("foo"), - extension: Some("txt"), - file_prefix: Some("foo") - ); - - t!("\\\\?\\C:\\", - iter: ["\\\\?\\C:", "\\"], - has_root: true, - is_absolute: true, - parent: None, - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("\\\\?\\C:", - iter: ["\\\\?\\C:"], - has_root: true, - is_absolute: true, - parent: None, - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("\\\\?\\foo/bar", - iter: ["\\\\?\\foo/bar"], - has_root: true, - is_absolute: true, - parent: None, - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("\\\\?\\C:/foo/bar", - iter: ["\\\\?\\C:", "\\", "foo/bar"], - has_root: true, - is_absolute: true, - parent: Some("\\\\?\\C:/"), - file_name: Some("foo/bar"), - file_stem: Some("foo/bar"), - extension: None, - file_prefix: Some("foo/bar") - ); - - t!("\\\\.\\foo\\bar", - iter: ["\\\\.\\foo", "\\", "bar"], - has_root: true, - is_absolute: true, - parent: Some("\\\\.\\foo\\"), - file_name: Some("bar"), - file_stem: Some("bar"), - extension: None, - file_prefix: Some("bar") - ); - - t!("\\\\.\\foo", - iter: ["\\\\.\\foo", "\\"], - has_root: true, - is_absolute: true, - parent: None, - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("\\\\.\\foo/bar", - iter: ["\\\\.\\foo", "\\", "bar"], - has_root: true, - is_absolute: true, - parent: Some("\\\\.\\foo/"), - file_name: Some("bar"), - file_stem: Some("bar"), - extension: None, - file_prefix: Some("bar") - ); - - t!("\\\\.\\foo\\bar/baz", - iter: ["\\\\.\\foo", "\\", "bar", "baz"], - has_root: true, - is_absolute: true, - parent: Some("\\\\.\\foo\\bar"), - file_name: Some("baz"), - file_stem: Some("baz"), - extension: None, - file_prefix: Some("baz") - ); - - t!("\\\\.\\", - iter: ["\\\\.\\", "\\"], - has_root: true, - is_absolute: true, - parent: None, - file_name: None, - file_stem: None, - extension: None, - file_prefix: None - ); - - t!("\\\\?\\a\\b\\", - iter: ["\\\\?\\a", "\\", "b"], - has_root: true, - is_absolute: true, - parent: Some("\\\\?\\a\\"), - file_name: Some("b"), - file_stem: Some("b"), - extension: None, - file_prefix: Some("b") - ); - - t!("\\\\?\\C:\\foo.txt.zip", - iter: ["\\\\?\\C:", "\\", "foo.txt.zip"], - has_root: true, - is_absolute: true, - parent: Some("\\\\?\\C:\\"), - file_name: Some("foo.txt.zip"), - file_stem: Some("foo.txt"), - extension: Some("zip"), - file_prefix: Some("foo") - ); - - t!("\\\\?\\C:\\.foo.txt.zip", - iter: ["\\\\?\\C:", "\\", ".foo.txt.zip"], - has_root: true, - is_absolute: true, - parent: Some("\\\\?\\C:\\"), - file_name: Some(".foo.txt.zip"), - file_stem: Some(".foo.txt"), - extension: Some("zip"), - file_prefix: Some(".foo") - ); - - t!("\\\\?\\C:\\.foo", - iter: ["\\\\?\\C:", "\\", ".foo"], - has_root: true, - is_absolute: true, - parent: Some("\\\\?\\C:\\"), - file_name: Some(".foo"), - file_stem: Some(".foo"), - extension: None, - file_prefix: Some(".foo") - ); - - t!("a/.x.y.z", - iter: ["a", ".x.y.z"], - has_root: false, - is_absolute: false, - parent: Some("a"), - file_name: Some(".x.y.z"), - file_stem: Some(".x.y"), - extension: Some("z"), - file_prefix: Some(".x") - ); -} - -#[test] -pub fn test_stem_ext() { - t!("foo", - file_stem: Some("foo"), - extension: None - ); - - t!("foo.", - file_stem: Some("foo"), - extension: Some("") - ); - - t!(".foo", - file_stem: Some(".foo"), - extension: None - ); - - t!("foo.txt", - file_stem: Some("foo"), - extension: Some("txt") - ); - - t!("foo.bar.txt", - file_stem: Some("foo.bar"), - extension: Some("txt") - ); - - t!("foo.bar.", - file_stem: Some("foo.bar"), - extension: Some("") - ); - - t!(".", file_stem: None, extension: None); - - t!("..", file_stem: None, extension: None); - - t!(".x.y.z", file_stem: Some(".x.y"), extension: Some("z")); - - t!("..x.y.z", file_stem: Some("..x.y"), extension: Some("z")); - - t!("", file_stem: None, extension: None); -} - -#[test] -pub fn test_prefix_ext() { - t!("foo", - file_prefix: Some("foo"), - extension: None - ); - - t!("foo.", - file_prefix: Some("foo"), - extension: Some("") - ); - - t!(".foo", - file_prefix: Some(".foo"), - extension: None - ); - - t!("foo.txt", - file_prefix: Some("foo"), - extension: Some("txt") - ); - - t!("foo.bar.txt", - file_prefix: Some("foo"), - extension: Some("txt") - ); - - t!("foo.bar.", - file_prefix: Some("foo"), - extension: Some("") - ); - - t!(".", file_prefix: None, extension: None); - - t!("..", file_prefix: None, extension: None); - - t!(".x.y.z", file_prefix: Some(".x"), extension: Some("z")); - - t!("..x.y.z", file_prefix: Some("."), extension: Some("z")); - - t!("", file_prefix: None, extension: None); -} - -#[test] -pub fn test_push() { - macro_rules! tp ( - ($path:expr, $push:expr, $expected:expr) => ({ - let mut actual = PathBuf::from($path); - actual.push($push); - assert!(actual.to_str() == Some($expected), - "pushing {:?} onto {:?}: Expected {:?}, got {:?}", - $push, $path, $expected, actual.to_str().unwrap()); - }); - ); - - if cfg!(unix) || cfg!(all(target_env = "sgx", target_vendor = "fortanix")) { - tp!("", "foo", "foo"); - tp!("foo", "bar", "foo/bar"); - tp!("foo/", "bar", "foo/bar"); - tp!("foo//", "bar", "foo//bar"); - tp!("foo/.", "bar", "foo/./bar"); - tp!("foo./.", "bar", "foo././bar"); - tp!("foo", "", "foo/"); - tp!("foo", ".", "foo/."); - tp!("foo", "..", "foo/.."); - tp!("foo", "/", "/"); - tp!("/foo/bar", "/", "/"); - tp!("/foo/bar", "/baz", "/baz"); - tp!("/foo/bar", "./baz", "/foo/bar/./baz"); - } else { - tp!("", "foo", "foo"); - tp!("foo", "bar", r"foo\bar"); - tp!("foo/", "bar", r"foo/bar"); - tp!(r"foo\", "bar", r"foo\bar"); - tp!("foo//", "bar", r"foo//bar"); - tp!(r"foo\\", "bar", r"foo\\bar"); - tp!("foo/.", "bar", r"foo/.\bar"); - tp!("foo./.", "bar", r"foo./.\bar"); - tp!(r"foo\.", "bar", r"foo\.\bar"); - tp!(r"foo.\.", "bar", r"foo.\.\bar"); - tp!("foo", "", "foo\\"); - tp!("foo", ".", r"foo\."); - tp!("foo", "..", r"foo\.."); - tp!("foo", "/", "/"); - tp!("foo", r"\", r"\"); - tp!("/foo/bar", "/", "/"); - tp!(r"\foo\bar", r"\", r"\"); - tp!("/foo/bar", "/baz", "/baz"); - tp!("/foo/bar", r"\baz", r"\baz"); - tp!("/foo/bar", "./baz", r"/foo/bar\./baz"); - tp!("/foo/bar", r".\baz", r"/foo/bar\.\baz"); - - tp!("c:\\", "windows", "c:\\windows"); - tp!("c:", "windows", "c:windows"); - - tp!("a\\b\\c", "d", "a\\b\\c\\d"); - tp!("\\a\\b\\c", "d", "\\a\\b\\c\\d"); - tp!("a\\b", "c\\d", "a\\b\\c\\d"); - tp!("a\\b", "\\c\\d", "\\c\\d"); - tp!("a\\b", ".", "a\\b\\."); - tp!("a\\b", "..\\c", "a\\b\\..\\c"); - tp!("a\\b", "C:a.txt", "C:a.txt"); - tp!("a\\b", "C:\\a.txt", "C:\\a.txt"); - tp!("C:\\a", "C:\\b.txt", "C:\\b.txt"); - tp!("C:\\a\\b\\c", "C:d", "C:d"); - tp!("C:a\\b\\c", "C:d", "C:d"); - tp!("C:", r"a\b\c", r"C:a\b\c"); - tp!("C:", r"..\a", r"C:..\a"); - tp!("\\\\server\\share\\foo", "bar", "\\\\server\\share\\foo\\bar"); - tp!("\\\\server\\share\\foo", "C:baz", "C:baz"); - tp!("\\\\?\\C:\\a\\b", "C:c\\d", "C:c\\d"); - tp!("\\\\?\\C:a\\b", "C:c\\d", "C:c\\d"); - tp!("\\\\?\\C:\\a\\b", "C:\\c\\d", "C:\\c\\d"); - tp!("\\\\?\\foo\\bar", "baz", "\\\\?\\foo\\bar\\baz"); - tp!("\\\\?\\UNC\\server\\share\\foo", "bar", "\\\\?\\UNC\\server\\share\\foo\\bar"); - tp!("\\\\?\\UNC\\server\\share", "C:\\a", "C:\\a"); - tp!("\\\\?\\UNC\\server\\share", "C:a", "C:a"); - - // Note: modified from old path API - tp!("\\\\?\\UNC\\server", "foo", "\\\\?\\UNC\\server\\foo"); - - tp!("C:\\a", "\\\\?\\UNC\\server\\share", "\\\\?\\UNC\\server\\share"); - tp!("\\\\.\\foo\\bar", "baz", "\\\\.\\foo\\bar\\baz"); - tp!("\\\\.\\foo\\bar", "C:a", "C:a"); - // again, not sure about the following, but I'm assuming \\.\ should be verbatim - tp!("\\\\.\\foo", "..\\bar", "\\\\.\\foo\\..\\bar"); - - tp!("\\\\?\\C:", "foo", "\\\\?\\C:\\foo"); // this is a weird one - - tp!(r"\\?\C:\bar", "../foo", r"\\?\C:\foo"); - tp!(r"\\?\C:\bar", "../../foo", r"\\?\C:\foo"); - tp!(r"\\?\C:\", "../foo", r"\\?\C:\foo"); - tp!(r"\\?\C:", r"D:\foo/./", r"D:\foo/./"); - tp!(r"\\?\C:", r"\\?\D:\foo\.\", r"\\?\D:\foo\.\"); - tp!(r"\\?\A:\x\y", "/foo", r"\\?\A:\foo"); - tp!(r"\\?\A:", r"..\foo\.", r"\\?\A:\foo"); - tp!(r"\\?\A:\x\y", r".\foo\.", r"\\?\A:\x\y\foo"); - tp!(r"\\?\A:\x\y", r"", r"\\?\A:\x\y\"); - } -} - -#[test] -pub fn test_pop() { - macro_rules! tp ( - ($path:expr, $expected:expr, $output:expr) => ({ - let mut actual = PathBuf::from($path); - let output = actual.pop(); - assert!(actual.to_str() == Some($expected) && output == $output, - "popping from {:?}: Expected {:?}/{:?}, got {:?}/{:?}", - $path, $expected, $output, - actual.to_str().unwrap(), output); - }); - ); - - tp!("", "", false); - tp!("/", "/", false); - tp!("foo", "", true); - tp!(".", "", true); - tp!("/foo", "/", true); - tp!("/foo/bar", "/foo", true); - tp!("foo/bar", "foo", true); - tp!("foo/.", "", true); - tp!("foo//bar", "foo", true); - - if cfg!(windows) { - tp!("a\\b\\c", "a\\b", true); - tp!("\\a", "\\", true); - tp!("\\", "\\", false); - - tp!("C:\\a\\b", "C:\\a", true); - tp!("C:\\a", "C:\\", true); - tp!("C:\\", "C:\\", false); - tp!("C:a\\b", "C:a", true); - tp!("C:a", "C:", true); - tp!("C:", "C:", false); - tp!("\\\\server\\share\\a\\b", "\\\\server\\share\\a", true); - tp!("\\\\server\\share\\a", "\\\\server\\share\\", true); - tp!("\\\\server\\share", "\\\\server\\share", false); - tp!("\\\\?\\a\\b\\c", "\\\\?\\a\\b", true); - tp!("\\\\?\\a\\b", "\\\\?\\a\\", true); - tp!("\\\\?\\a", "\\\\?\\a", false); - tp!("\\\\?\\C:\\a\\b", "\\\\?\\C:\\a", true); - tp!("\\\\?\\C:\\a", "\\\\?\\C:\\", true); - tp!("\\\\?\\C:\\", "\\\\?\\C:\\", false); - tp!("\\\\?\\UNC\\server\\share\\a\\b", "\\\\?\\UNC\\server\\share\\a", true); - tp!("\\\\?\\UNC\\server\\share\\a", "\\\\?\\UNC\\server\\share\\", true); - tp!("\\\\?\\UNC\\server\\share", "\\\\?\\UNC\\server\\share", false); - tp!("\\\\.\\a\\b\\c", "\\\\.\\a\\b", true); - tp!("\\\\.\\a\\b", "\\\\.\\a\\", true); - tp!("\\\\.\\a", "\\\\.\\a", false); - - tp!("\\\\?\\a\\b\\", "\\\\?\\a\\", true); - } -} - -#[test] -pub fn test_set_file_name() { - macro_rules! tfn ( - ($path:expr, $file:expr, $expected:expr) => ({ - let mut p = PathBuf::from($path); - p.set_file_name($file); - assert!(p.to_str() == Some($expected), - "setting file name of {:?} to {:?}: Expected {:?}, got {:?}", - $path, $file, $expected, - p.to_str().unwrap()); - }); - ); - - tfn!("foo", "foo", "foo"); - tfn!("foo", "bar", "bar"); - tfn!("foo", "", ""); - tfn!("", "foo", "foo"); - if cfg!(unix) || cfg!(all(target_env = "sgx", target_vendor = "fortanix")) { - tfn!(".", "foo", "./foo"); - tfn!("foo/", "bar", "bar"); - tfn!("foo/.", "bar", "bar"); - tfn!("..", "foo", "../foo"); - tfn!("foo/..", "bar", "foo/../bar"); - tfn!("/", "foo", "/foo"); - } else { - tfn!(".", "foo", r".\foo"); - tfn!(r"foo\", "bar", r"bar"); - tfn!(r"foo\.", "bar", r"bar"); - tfn!("..", "foo", r"..\foo"); - tfn!(r"foo\..", "bar", r"foo\..\bar"); - tfn!(r"\", "foo", r"\foo"); - } -} - -#[test] -pub fn test_set_extension() { - macro_rules! tfe ( - ($path:expr, $ext:expr, $expected:expr, $output:expr) => ({ - let mut p = PathBuf::from($path); - let output = p.set_extension($ext); - assert!(p.to_str() == Some($expected) && output == $output, - "setting extension of {:?} to {:?}: Expected {:?}/{:?}, got {:?}/{:?}", - $path, $ext, $expected, $output, - p.to_str().unwrap(), output); - }); - ); - - tfe!("foo", "txt", "foo.txt", true); - tfe!("foo.bar", "txt", "foo.txt", true); - tfe!("foo.bar.baz", "txt", "foo.bar.txt", true); - tfe!(".test", "txt", ".test.txt", true); - tfe!("foo.txt", "", "foo", true); - tfe!("foo", "", "foo", true); - tfe!("", "foo", "", false); - tfe!(".", "foo", ".", false); - tfe!("foo/", "bar", "foo.bar", true); - tfe!("foo/.", "bar", "foo.bar", true); - tfe!("..", "foo", "..", false); - tfe!("foo/..", "bar", "foo/..", false); - tfe!("/", "foo", "/", false); -} - -#[test] -pub fn test_with_extension() { - macro_rules! twe ( - ($input:expr, $extension:expr, $expected:expr) => ({ - let input = Path::new($input); - let output = input.with_extension($extension); - - assert!( - output.to_str() == Some($expected), - "calling Path::new({:?}).with_extension({:?}): Expected {:?}, got {:?}", - $input, $extension, $expected, output, - ); - }); - ); - - twe!("foo", "txt", "foo.txt"); - twe!("foo.bar", "txt", "foo.txt"); - twe!("foo.bar.baz", "txt", "foo.bar.txt"); - twe!(".test", "txt", ".test.txt"); - twe!("foo.txt", "", "foo"); - twe!("foo", "", "foo"); - twe!("", "foo", ""); - twe!(".", "foo", "."); - twe!("foo/", "bar", "foo.bar"); - twe!("foo/.", "bar", "foo.bar"); - twe!("..", "foo", ".."); - twe!("foo/..", "bar", "foo/.."); - twe!("/", "foo", "/"); - - // New extension is smaller than file name - twe!("aaa_aaa_aaa", "bbb_bbb", "aaa_aaa_aaa.bbb_bbb"); - // New extension is greater than file name - twe!("bbb_bbb", "aaa_aaa_aaa", "bbb_bbb.aaa_aaa_aaa"); - - // New extension is smaller than previous extension - twe!("ccc.aaa_aaa_aaa", "bbb_bbb", "ccc.bbb_bbb"); - // New extension is greater than previous extension - twe!("ccc.bbb_bbb", "aaa_aaa_aaa", "ccc.aaa_aaa_aaa"); -} - -#[test] -fn test_eq_receivers() { - use crate::borrow::Cow; - - let borrowed: &Path = Path::new("foo/bar"); - let mut owned: PathBuf = PathBuf::new(); - owned.push("foo"); - owned.push("bar"); - let borrowed_cow: Cow<'_, Path> = borrowed.into(); - let owned_cow: Cow<'_, Path> = owned.clone().into(); - - macro_rules! t { - ($($current:expr),+) => { - $( - assert_eq!($current, borrowed); - assert_eq!($current, owned); - assert_eq!($current, borrowed_cow); - assert_eq!($current, owned_cow); - )+ - } - } - - t!(borrowed, owned, borrowed_cow, owned_cow); -} - -#[test] -pub fn test_compare() { - use crate::hash::{DefaultHasher, Hash, Hasher}; - - fn hash(t: T) -> u64 { - let mut s = DefaultHasher::new(); - t.hash(&mut s); - s.finish() - } - - macro_rules! tc ( - ($path1:expr, $path2:expr, eq: $eq:expr, - starts_with: $starts_with:expr, ends_with: $ends_with:expr, - relative_from: $relative_from:expr) => ({ - let path1 = Path::new($path1); - let path2 = Path::new($path2); - - let eq = path1 == path2; - assert!(eq == $eq, "{:?} == {:?}, expected {:?}, got {:?}", - $path1, $path2, $eq, eq); - assert!($eq == (hash(path1) == hash(path2)), - "{:?} == {:?}, expected {:?}, got {} and {}", - $path1, $path2, $eq, hash(path1), hash(path2)); - - let starts_with = path1.starts_with(path2); - assert!(starts_with == $starts_with, - "{:?}.starts_with({:?}), expected {:?}, got {:?}", $path1, $path2, - $starts_with, starts_with); - - let ends_with = path1.ends_with(path2); - assert!(ends_with == $ends_with, - "{:?}.ends_with({:?}), expected {:?}, got {:?}", $path1, $path2, - $ends_with, ends_with); - - let relative_from = path1.strip_prefix(path2) - .map(|p| p.to_str().unwrap()) - .ok(); - let exp: Option<&str> = $relative_from; - assert!(relative_from == exp, - "{:?}.strip_prefix({:?}), expected {:?}, got {:?}", - $path1, $path2, exp, relative_from); - }); - ); - - tc!("", "", - eq: true, - starts_with: true, - ends_with: true, - relative_from: Some("") - ); - - tc!("foo", "", - eq: false, - starts_with: true, - ends_with: true, - relative_from: Some("foo") - ); - - tc!("", "foo", - eq: false, - starts_with: false, - ends_with: false, - relative_from: None - ); - - tc!("foo", "foo", - eq: true, - starts_with: true, - ends_with: true, - relative_from: Some("") - ); - - tc!("foo/", "foo", - eq: true, - starts_with: true, - ends_with: true, - relative_from: Some("") - ); - - tc!("foo/.", "foo", - eq: true, - starts_with: true, - ends_with: true, - relative_from: Some("") - ); - - tc!("foo/./bar", "foo/bar", - eq: true, - starts_with: true, - ends_with: true, - relative_from: Some("") - ); - - tc!("foo/bar", "foo", - eq: false, - starts_with: true, - ends_with: false, - relative_from: Some("bar") - ); - - tc!("foo/bar/baz", "foo/bar", - eq: false, - starts_with: true, - ends_with: false, - relative_from: Some("baz") - ); - - tc!("foo/bar", "foo/bar/baz", - eq: false, - starts_with: false, - ends_with: false, - relative_from: None - ); - - tc!("./foo/bar/", ".", - eq: false, - starts_with: true, - ends_with: false, - relative_from: Some("foo/bar") - ); - - if cfg!(windows) { - tc!(r"C:\src\rust\cargo-test\test\Cargo.toml", - r"c:\src\rust\cargo-test\test", - eq: false, - starts_with: true, - ends_with: false, - relative_from: Some("Cargo.toml") - ); - - tc!(r"c:\foo", r"C:\foo", - eq: true, - starts_with: true, - ends_with: true, - relative_from: Some("") - ); - - tc!(r"C:\foo\.\bar.txt", r"C:\foo\bar.txt", - eq: true, - starts_with: true, - ends_with: true, - relative_from: Some("") - ); - - tc!(r"C:\foo\.", r"C:\foo", - eq: true, - starts_with: true, - ends_with: true, - relative_from: Some("") - ); - - tc!(r"\\?\C:\foo\.\bar.txt", r"\\?\C:\foo\bar.txt", - eq: false, - starts_with: false, - ends_with: false, - relative_from: None - ); - } -} - -#[test] -fn test_components_debug() { - let path = Path::new("/tmp"); - - let mut components = path.components(); - - let expected = "Components([RootDir, Normal(\"tmp\")])"; - let actual = format!("{components:?}"); - assert_eq!(expected, actual); - - let _ = components.next().unwrap(); - let expected = "Components([Normal(\"tmp\")])"; - let actual = format!("{components:?}"); - assert_eq!(expected, actual); - - let _ = components.next().unwrap(); - let expected = "Components([])"; - let actual = format!("{components:?}"); - assert_eq!(expected, actual); -} - -#[cfg(unix)] -#[test] -fn test_iter_debug() { - let path = Path::new("/tmp"); - - let mut iter = path.iter(); - - let expected = "Iter([\"/\", \"tmp\"])"; - let actual = format!("{iter:?}"); - assert_eq!(expected, actual); - - let _ = iter.next().unwrap(); - let expected = "Iter([\"tmp\"])"; - let actual = format!("{iter:?}"); - assert_eq!(expected, actual); - - let _ = iter.next().unwrap(); - let expected = "Iter([])"; - let actual = format!("{iter:?}"); - assert_eq!(expected, actual); -} - -#[test] -fn into_boxed() { - let orig: &str = "some/sort/of/path"; - let path = Path::new(orig); - let boxed: Box = Box::from(path); - let path_buf = path.to_owned().into_boxed_path().into_path_buf(); - assert_eq!(path, &*boxed); - assert_eq!(&*boxed, &*path_buf); - assert_eq!(&*path_buf, path); -} - -#[test] -fn test_clone_into() { - let mut path_buf = PathBuf::from("supercalifragilisticexpialidocious"); - let path = Path::new("short"); - path.clone_into(&mut path_buf); - assert_eq!(path, path_buf); - assert!(path_buf.into_os_string().capacity() >= 15); -} - -#[test] -fn display_format_flags() { - assert_eq!(format!("a{:#<5}b", Path::new("").display()), "a#####b"); - assert_eq!(format!("a{:#<5}b", Path::new("a").display()), "aa####b"); -} - -#[test] -fn into_rc() { - let orig = "hello/world"; - let path = Path::new(orig); - let rc: Rc = Rc::from(path); - let arc: Arc = Arc::from(path); - - assert_eq!(&*rc, path); - assert_eq!(&*arc, path); - - let rc2: Rc = Rc::from(path.to_owned()); - let arc2: Arc = Arc::from(path.to_owned()); - - assert_eq!(&*rc2, path); - assert_eq!(&*arc2, path); -} - -#[test] -fn test_ord() { - macro_rules! ord( - ($ord:ident, $left:expr, $right:expr) => ({ - use core::cmp::Ordering; - - let left = Path::new($left); - let right = Path::new($right); - assert_eq!(left.cmp(&right), Ordering::$ord); - if (core::cmp::Ordering::$ord == Ordering::Equal) { - assert_eq!(left, right); - - let mut hasher = DefaultHasher::new(); - left.hash(&mut hasher); - let left_hash = hasher.finish(); - hasher = DefaultHasher::new(); - right.hash(&mut hasher); - let right_hash = hasher.finish(); - - assert_eq!(left_hash, right_hash, "hashes for {:?} and {:?} must match", left, right); - } else { - assert_ne!(left, right); - } - }); - ); - - ord!(Less, "1", "2"); - ord!(Less, "/foo/bar", "/foo./bar"); - ord!(Less, "foo/bar", "foo/bar."); - ord!(Equal, "foo/./bar", "foo/bar/"); - ord!(Equal, "foo/bar", "foo/bar/"); - ord!(Equal, "foo/bar", "foo/bar/."); - ord!(Equal, "foo/bar", "foo/bar//"); -} - -#[test] -#[cfg(unix)] -fn test_unix_absolute() { - use crate::path::absolute; - - assert!(absolute("").is_err()); - - let relative = "a/b"; - let mut expected = crate::env::current_dir().unwrap(); - expected.push(relative); - assert_eq!(absolute(relative).unwrap().as_os_str(), expected.as_os_str()); - - // Test how components are collected. - assert_eq!(absolute("/a/b/c").unwrap().as_os_str(), Path::new("/a/b/c").as_os_str()); - assert_eq!(absolute("/a//b/c").unwrap().as_os_str(), Path::new("/a/b/c").as_os_str()); - assert_eq!(absolute("//a/b/c").unwrap().as_os_str(), Path::new("//a/b/c").as_os_str()); - assert_eq!(absolute("///a/b/c").unwrap().as_os_str(), Path::new("/a/b/c").as_os_str()); - assert_eq!(absolute("/a/b/c/").unwrap().as_os_str(), Path::new("/a/b/c/").as_os_str()); - assert_eq!( - absolute("/a/./b/../c/.././..").unwrap().as_os_str(), - Path::new("/a/b/../c/../..").as_os_str() - ); - - // Test leading `.` and `..` components - let curdir = crate::env::current_dir().unwrap(); - assert_eq!(absolute("./a").unwrap().as_os_str(), curdir.join("a").as_os_str()); - assert_eq!(absolute("../a").unwrap().as_os_str(), curdir.join("../a").as_os_str()); // return /pwd/../a -} - -#[test] -#[cfg(windows)] -fn test_windows_absolute() { - use crate::path::absolute; - // An empty path is an error. - assert!(absolute("").is_err()); - - let relative = r"a\b"; - let mut expected = crate::env::current_dir().unwrap(); - expected.push(relative); - assert_eq!(absolute(relative).unwrap().as_os_str(), expected.as_os_str()); - - macro_rules! unchanged( - ($path:expr) => { - assert_eq!(absolute($path).unwrap().as_os_str(), Path::new($path).as_os_str()); - } - ); - - unchanged!(r"C:\path\to\file"); - unchanged!(r"C:\path\to\file\"); - unchanged!(r"\\server\share\to\file"); - unchanged!(r"\\server.\share.\to\file"); - unchanged!(r"\\.\PIPE\name"); - unchanged!(r"\\.\C:\path\to\COM1"); - unchanged!(r"\\?\C:\path\to\file"); - unchanged!(r"\\?\UNC\server\share\to\file"); - unchanged!(r"\\?\PIPE\name"); - // Verbatim paths are always unchanged, no matter what. - unchanged!(r"\\?\path.\to/file.."); - - assert_eq!( - absolute(r"C:\path..\to.\file.").unwrap().as_os_str(), - Path::new(r"C:\path..\to\file").as_os_str() - ); - assert_eq!(absolute(r"COM1").unwrap().as_os_str(), Path::new(r"\\.\COM1").as_os_str()); -} - -#[bench] -#[cfg_attr(miri, ignore)] // Miri isn't fast... -fn bench_path_cmp_fast_path_buf_sort(b: &mut test::Bencher) { - let prefix = "my/home"; - let mut paths: Vec<_> = - (0..1000).map(|num| PathBuf::from(prefix).join(format!("file {num}.rs"))).collect(); - - paths.sort(); - - b.iter(|| { - black_box(paths.as_mut_slice()).sort_unstable(); - }); -} - -#[bench] -#[cfg_attr(miri, ignore)] // Miri isn't fast... -fn bench_path_cmp_fast_path_long(b: &mut test::Bencher) { - let prefix = "/my/home/is/my/castle/and/my/castle/has/a/rusty/workbench/"; - let paths: Vec<_> = - (0..1000).map(|num| PathBuf::from(prefix).join(format!("file {num}.rs"))).collect(); - - let mut set = BTreeSet::new(); - - paths.iter().for_each(|p| { - set.insert(p.as_path()); - }); - - b.iter(|| { - set.remove(paths[500].as_path()); - set.insert(paths[500].as_path()); - }); -} - -#[bench] -#[cfg_attr(miri, ignore)] // Miri isn't fast... -fn bench_path_cmp_fast_path_short(b: &mut test::Bencher) { - let prefix = "my/home"; - let paths: Vec<_> = - (0..1000).map(|num| PathBuf::from(prefix).join(format!("file {num}.rs"))).collect(); - - let mut set = BTreeSet::new(); - - paths.iter().for_each(|p| { - set.insert(p.as_path()); - }); - - b.iter(|| { - set.remove(paths[500].as_path()); - set.insert(paths[500].as_path()); - }); -} - -#[bench] -#[cfg_attr(miri, ignore)] // Miri isn't fast... -fn bench_path_hashset(b: &mut test::Bencher) { - let prefix = "/my/home/is/my/castle/and/my/castle/has/a/rusty/workbench/"; - let paths: Vec<_> = - (0..1000).map(|num| PathBuf::from(prefix).join(format!("file {num}.rs"))).collect(); - - let mut set = HashSet::new(); - - paths.iter().for_each(|p| { - set.insert(p.as_path()); - }); - - b.iter(|| { - set.remove(paths[500].as_path()); - set.insert(black_box(paths[500].as_path())) - }); -} - -#[bench] -#[cfg_attr(miri, ignore)] // Miri isn't fast... -fn bench_path_hashset_miss(b: &mut test::Bencher) { - let prefix = "/my/home/is/my/castle/and/my/castle/has/a/rusty/workbench/"; - let paths: Vec<_> = - (0..1000).map(|num| PathBuf::from(prefix).join(format!("file {num}.rs"))).collect(); - - let mut set = HashSet::new(); - - paths.iter().for_each(|p| { - set.insert(p.as_path()); - }); - - let probe = PathBuf::from(prefix).join("other"); - - b.iter(|| set.remove(black_box(probe.as_path()))); -} - -#[bench] -fn bench_hash_path_short(b: &mut test::Bencher) { - let mut hasher = DefaultHasher::new(); - let path = Path::new("explorer.exe"); - - b.iter(|| black_box(path).hash(&mut hasher)); - - black_box(hasher.finish()); -} - -#[bench] -fn bench_hash_path_long(b: &mut test::Bencher) { - let mut hasher = DefaultHasher::new(); - let path = - Path::new("/aaaaa/aaaaaa/./../aaaaaaaa/bbbbbbbbbbbbb/ccccccccccc/ddddddddd/eeeeeee.fff"); - - b.iter(|| black_box(path).hash(&mut hasher)); - - black_box(hasher.finish()); -} diff --git a/library/std/src/prelude/common.rs b/library/std/src/prelude/common.rs deleted file mode 100644 index 01936734d7548..0000000000000 --- a/library/std/src/prelude/common.rs +++ /dev/null @@ -1,111 +0,0 @@ -//! Items common to the prelude of all editions. -//! -//! See the [module-level documentation](super) for more. - -// Re-exported core operators -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(no_inline)] -pub use crate::marker::{Send, Sized, Sync, Unpin}; -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(no_inline)] -pub use crate::ops::{Drop, Fn, FnMut, FnOnce}; - -// Re-exported functions -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(no_inline)] -pub use crate::mem::drop; - -// Re-exported types and traits -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(no_inline)] -pub use crate::convert::{AsMut, AsRef, From, Into}; -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(no_inline)] -pub use crate::iter::{DoubleEndedIterator, ExactSizeIterator}; -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(no_inline)] -pub use crate::iter::{Extend, IntoIterator, Iterator}; -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(no_inline)] -pub use crate::option::Option::{self, None, Some}; -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(no_inline)] -pub use crate::result::Result::{self, Err, Ok}; - -// Re-exported built-in macros -#[stable(feature = "builtin_macro_prelude", since = "1.38.0")] -#[allow(deprecated)] -#[doc(no_inline)] -pub use core::prelude::v1::{ - assert, cfg, column, compile_error, concat, concat_idents, env, file, format_args, - format_args_nl, include, include_bytes, include_str, line, log_syntax, module_path, option_env, - stringify, trace_macros, Clone, Copy, Debug, Default, Eq, Hash, Ord, PartialEq, PartialOrd, -}; - -#[unstable( - feature = "concat_bytes", - issue = "87555", - reason = "`concat_bytes` is not stable enough for use and is subject to change" -)] -#[doc(no_inline)] -pub use core::prelude::v1::concat_bytes; - -// Do not `doc(no_inline)` so that they become doc items on their own -// (no public module for them to be re-exported from). -#[stable(feature = "builtin_macro_prelude", since = "1.38.0")] -pub use core::prelude::v1::{ - alloc_error_handler, bench, derive, global_allocator, test, test_case, -}; - -#[unstable(feature = "derive_const", issue = "none")] -pub use core::prelude::v1::derive_const; - -// Do not `doc(no_inline)` either. -#[unstable( - feature = "cfg_accessible", - issue = "64797", - reason = "`cfg_accessible` is not fully implemented" -)] -pub use core::prelude::v1::cfg_accessible; - -// Do not `doc(no_inline)` either. -#[unstable( - feature = "cfg_eval", - issue = "82679", - reason = "`cfg_eval` is a recently implemented feature" -)] -pub use core::prelude::v1::cfg_eval; - -// Do not `doc(no_inline)` either. -#[unstable( - feature = "type_ascription", - issue = "23416", - reason = "placeholder syntax for type ascription" -)] -pub use core::prelude::v1::type_ascribe; - -// Do not `doc(no_inline)` either. -#[unstable( - feature = "deref_patterns", - issue = "87121", - reason = "placeholder syntax for deref patterns" -)] -pub use core::prelude::v1::deref; - -// The file so far is equivalent to core/src/prelude/v1.rs. It is duplicated -// rather than glob imported because we want docs to show these re-exports as -// pointing to within `std`. -// Below are the items from the alloc crate. - -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(no_inline)] -pub use crate::borrow::ToOwned; -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(no_inline)] -pub use crate::boxed::Box; -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(no_inline)] -pub use crate::string::{String, ToString}; -#[stable(feature = "rust1", since = "1.0.0")] -#[doc(no_inline)] -pub use crate::vec::Vec; diff --git a/library/std/src/prelude/mod.rs b/library/std/src/prelude/mod.rs deleted file mode 100644 index 0bdbab716adb4..0000000000000 --- a/library/std/src/prelude/mod.rs +++ /dev/null @@ -1,162 +0,0 @@ -//! # The Rust Prelude -//! -//! Rust comes with a variety of things in its standard library. However, if -//! you had to manually import every single thing that you used, it would be -//! very verbose. But importing a lot of things that a program never uses isn't -//! good either. A balance needs to be struck. -//! -//! The *prelude* is the list of things that Rust automatically imports into -//! every Rust program. It's kept as small as possible, and is focused on -//! things, particularly traits, which are used in almost every single Rust -//! program. -//! -//! # Other preludes -//! -//! Preludes can be seen as a pattern to make using multiple types more -//! convenient. As such, you'll find other preludes in the standard library, -//! such as [`std::io::prelude`]. Various libraries in the Rust ecosystem may -//! also define their own preludes. -//! -//! [`std::io::prelude`]: crate::io::prelude -//! -//! The difference between 'the prelude' and these other preludes is that they -//! are not automatically `use`'d, and must be imported manually. This is still -//! easier than importing all of their constituent components. -//! -//! # Prelude contents -//! -//! The first version of the prelude is used in Rust 2015 and Rust 2018, -//! and lives in [`std::prelude::v1`]. -//! [`std::prelude::rust_2015`] and [`std::prelude::rust_2018`] re-export this prelude. -//! It re-exports the following: -//! -//! * [std::marker]::{[Copy], [Send], [Sized], [Sync], [Unpin]}, -//! marker traits that indicate fundamental properties of types. -//! * [std::ops]::{[Drop], [Fn], [FnMut], [FnOnce]}, various -//! operations for both destructors and overloading `()`. -//! * [std::mem]::[drop], a convenience function for explicitly -//! dropping a value. -//! * [std::boxed]::[Box], a way to allocate values on the heap. -//! * [std::borrow]::[ToOwned], the conversion trait that defines -//! [`to_owned`], the generic method for creating an owned type from a -//! borrowed type. -//! * [std::clone]::[Clone], the ubiquitous trait that defines -//! [`clone`][Clone::clone], the method for producing a copy of a value. -//! * [std::cmp]::{[PartialEq], [PartialOrd], [Eq], [Ord]}, the -//! comparison traits, which implement the comparison operators and are often -//! seen in trait bounds. -//! * [std::convert]::{[AsRef], [AsMut], [Into], [From]}, generic -//! conversions, used by savvy API authors to create overloaded methods. -//! * [std::default]::[Default], types that have default values. -//! * [std::iter]::{[Iterator], [Extend], [IntoIterator], [DoubleEndedIterator], [ExactSizeIterator]}, -//! iterators of various -//! kinds. -//! * [std::option]::[Option]::{[self][Option], [Some], [None]}, a -//! type which expresses the presence or absence of a value. This type is so -//! commonly used, its variants are also exported. -//! * [std::result]::[Result]::{[self][Result], [Ok], [Err]}, a type -//! for functions that may succeed or fail. Like [`Option`], its variants are -//! exported as well. -//! * [std::string]::{[String], [ToString]}, heap-allocated strings. -//! * [std::vec]::[Vec], a growable, heap-allocated vector. -//! -//! The prelude used in Rust 2021, [`std::prelude::rust_2021`], includes all of the above, -//! and in addition re-exports: -//! -//! * [std::convert]::{[TryFrom], [TryInto]}, -//! * [std::iter]::[FromIterator]. -//! -//! [std::borrow]: crate::borrow -//! [std::boxed]: crate::boxed -//! [std::clone]: crate::clone -//! [std::cmp]: crate::cmp -//! [std::convert]: crate::convert -//! [std::default]: crate::default -//! [std::iter]: crate::iter -//! [std::marker]: crate::marker -//! [std::mem]: crate::mem -//! [std::ops]: crate::ops -//! [std::option]: crate::option -//! [`std::prelude::v1`]: v1 -//! [`std::prelude::rust_2015`]: rust_2015 -//! [`std::prelude::rust_2018`]: rust_2018 -//! [`std::prelude::rust_2021`]: rust_2021 -//! [std::result]: crate::result -//! [std::slice]: crate::slice -//! [std::string]: crate::string -//! [std::vec]: mod@crate::vec -//! [`to_owned`]: crate::borrow::ToOwned::to_owned -//! [book-closures]: ../../book/ch13-01-closures.html -//! [book-dtor]: ../../book/ch15-03-drop.html -//! [book-enums]: ../../book/ch06-01-defining-an-enum.html -//! [book-iter]: ../../book/ch13-02-iterators.html - -#![stable(feature = "rust1", since = "1.0.0")] - -mod common; - -/// The first version of the prelude of The Rust Standard Library. -/// -/// See the [module-level documentation](self) for more. -#[stable(feature = "rust1", since = "1.0.0")] -pub mod v1 { - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::common::*; - - // Do not `doc(inline)` these `doc(hidden)` items. - #[unstable( - feature = "rustc_encodable_decodable", - issue = "none", - soft, - reason = "derive macro for `rustc-serialize`; should not be used in new code" - )] - #[allow(deprecated)] - pub use core::prelude::v1::{RustcDecodable, RustcEncodable}; -} - -/// The 2015 version of the prelude of The Rust Standard Library. -/// -/// See the [module-level documentation](self) for more. -#[stable(feature = "prelude_2015", since = "1.55.0")] -pub mod rust_2015 { - #[stable(feature = "prelude_2015", since = "1.55.0")] - #[doc(no_inline)] - pub use super::v1::*; -} - -/// The 2018 version of the prelude of The Rust Standard Library. -/// -/// See the [module-level documentation](self) for more. -#[stable(feature = "prelude_2018", since = "1.55.0")] -pub mod rust_2018 { - #[stable(feature = "prelude_2018", since = "1.55.0")] - #[doc(no_inline)] - pub use super::v1::*; -} - -/// The 2021 version of the prelude of The Rust Standard Library. -/// -/// See the [module-level documentation](self) for more. -#[stable(feature = "prelude_2021", since = "1.55.0")] -pub mod rust_2021 { - #[stable(feature = "prelude_2021", since = "1.55.0")] - #[doc(no_inline)] - pub use super::v1::*; - - #[stable(feature = "prelude_2021", since = "1.55.0")] - #[doc(no_inline)] - pub use core::prelude::rust_2021::*; -} - -/// The 2024 version of the prelude of The Rust Standard Library. -/// -/// See the [module-level documentation](self) for more. -#[unstable(feature = "prelude_2024", issue = "121042")] -pub mod rust_2024 { - #[stable(feature = "rust1", since = "1.0.0")] - pub use super::common::*; - - #[unstable(feature = "prelude_2024", issue = "121042")] - #[doc(no_inline)] - pub use core::prelude::rust_2024::*; -} diff --git a/library/std/src/process.rs b/library/std/src/process.rs deleted file mode 100644 index c926c89f7a97f..0000000000000 --- a/library/std/src/process.rs +++ /dev/null @@ -1,2459 +0,0 @@ -//! A module for working with processes. -//! -//! This module is mostly concerned with spawning and interacting with child -//! processes, but it also provides [`abort`] and [`exit`] for terminating the -//! current process. -//! -//! # Spawning a process -//! -//! The [`Command`] struct is used to configure and spawn processes: -//! -//! ```no_run -//! use std::process::Command; -//! -//! let output = Command::new("echo") -//! .arg("Hello world") -//! .output() -//! .expect("Failed to execute command"); -//! -//! assert_eq!(b"Hello world\n", output.stdout.as_slice()); -//! ``` -//! -//! Several methods on [`Command`], such as [`spawn`] or [`output`], can be used -//! to spawn a process. In particular, [`output`] spawns the child process and -//! waits until the process terminates, while [`spawn`] will return a [`Child`] -//! that represents the spawned child process. -//! -//! # Handling I/O -//! -//! The [`stdout`], [`stdin`], and [`stderr`] of a child process can be -//! configured by passing an [`Stdio`] to the corresponding method on -//! [`Command`]. Once spawned, they can be accessed from the [`Child`]. For -//! example, piping output from one command into another command can be done -//! like so: -//! -//! ```no_run -//! use std::process::{Command, Stdio}; -//! -//! // stdout must be configured with `Stdio::piped` in order to use -//! // `echo_child.stdout` -//! let echo_child = Command::new("echo") -//! .arg("Oh no, a tpyo!") -//! .stdout(Stdio::piped()) -//! .spawn() -//! .expect("Failed to start echo process"); -//! -//! // Note that `echo_child` is moved here, but we won't be needing -//! // `echo_child` anymore -//! let echo_out = echo_child.stdout.expect("Failed to open echo stdout"); -//! -//! let mut sed_child = Command::new("sed") -//! .arg("s/tpyo/typo/") -//! .stdin(Stdio::from(echo_out)) -//! .stdout(Stdio::piped()) -//! .spawn() -//! .expect("Failed to start sed process"); -//! -//! let output = sed_child.wait_with_output().expect("Failed to wait on sed"); -//! assert_eq!(b"Oh no, a typo!\n", output.stdout.as_slice()); -//! ``` -//! -//! Note that [`ChildStderr`] and [`ChildStdout`] implement [`Read`] and -//! [`ChildStdin`] implements [`Write`]: -//! -//! ```no_run -//! use std::process::{Command, Stdio}; -//! use std::io::Write; -//! -//! let mut child = Command::new("/bin/cat") -//! .stdin(Stdio::piped()) -//! .stdout(Stdio::piped()) -//! .spawn() -//! .expect("failed to execute child"); -//! -//! // If the child process fills its stdout buffer, it may end up -//! // waiting until the parent reads the stdout, and not be able to -//! // read stdin in the meantime, causing a deadlock. -//! // Writing from another thread ensures that stdout is being read -//! // at the same time, avoiding the problem. -//! let mut stdin = child.stdin.take().expect("failed to get stdin"); -//! std::thread::spawn(move || { -//! stdin.write_all(b"test").expect("failed to write to stdin"); -//! }); -//! -//! let output = child -//! .wait_with_output() -//! .expect("failed to wait on child"); -//! -//! assert_eq!(b"test", output.stdout.as_slice()); -//! ``` -//! -//! # Windows argument splitting -//! -//! On Unix systems arguments are passed to a new process as an array of strings, -//! but on Windows arguments are passed as a single commandline string and it is -//! up to the child process to parse it into an array. Therefore the parent and -//! child processes must agree on how the commandline string is encoded. -//! -//! Most programs use the standard C run-time `argv`, which in practice results -//! in consistent argument handling. However some programs have their own way of -//! parsing the commandline string. In these cases using [`arg`] or [`args`] may -//! result in the child process seeing a different array of arguments then the -//! parent process intended. -//! -//! Two ways of mitigating this are: -//! -//! * Validate untrusted input so that only a safe subset is allowed. -//! * Use [`raw_arg`] to build a custom commandline. This bypasses the escaping -//! rules used by [`arg`] so should be used with due caution. -//! -//! `cmd.exe` and `.bat` files use non-standard argument parsing and are especially -//! vulnerable to malicious input as they may be used to run arbitrary shell -//! commands. Untrusted arguments should be restricted as much as possible. -//! For examples on handling this see [`raw_arg`]. -//! -//! ### Batch file special handling -//! -//! On Windows, `Command` uses the Windows API function [`CreateProcessW`] to -//! spawn new processes. An undocumented feature of this function is that -//! when given a `.bat` file as the application to run, it will automatically -//! convert that into running `cmd.exe /c` with the batch file as the next argument. -//! -//! For historical reasons Rust currently preserves this behaviour when using -//! [`Command::new`], and escapes the arguments according to `cmd.exe` rules. -//! Due to the complexity of `cmd.exe` argument handling, it might not be -//! possible to safely escape some special characters, and using them will result -//! in an error being returned at process spawn. The set of unescapeable -//! special characters might change between releases. -//! -//! Also note that running batch scripts in this way may be removed in the -//! future and so should not be relied upon. -//! -//! [`spawn`]: Command::spawn -//! [`output`]: Command::output -//! -//! [`stdout`]: Command::stdout -//! [`stdin`]: Command::stdin -//! [`stderr`]: Command::stderr -//! -//! [`Write`]: io::Write -//! [`Read`]: io::Read -//! -//! [`arg`]: Command::arg -//! [`args`]: Command::args -//! [`raw_arg`]: crate::os::windows::process::CommandExt::raw_arg -//! -//! [`CreateProcessW`]: https://learn.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw - -#![stable(feature = "process", since = "1.0.0")] -#![deny(unsafe_op_in_unsafe_fn)] - -#[cfg(all(test, not(any(target_os = "emscripten", target_env = "sgx", target_os = "xous"))))] -mod tests; - -use crate::io::prelude::*; - -use crate::convert::Infallible; -use crate::ffi::OsStr; -use crate::fmt; -use crate::fs; -use crate::io::{self, BorrowedCursor, IoSlice, IoSliceMut}; -use crate::num::NonZero; -use crate::path::Path; -use crate::str; -use crate::sys::pipe::{read2, AnonPipe}; -use crate::sys::process as imp; -#[stable(feature = "command_access", since = "1.57.0")] -pub use crate::sys_common::process::CommandEnvs; -use crate::sys_common::{AsInner, AsInnerMut, FromInner, IntoInner}; - -/// Representation of a running or exited child process. -/// -/// This structure is used to represent and manage child processes. A child -/// process is created via the [`Command`] struct, which configures the -/// spawning process and can itself be constructed using a builder-style -/// interface. -/// -/// There is no implementation of [`Drop`] for child processes, -/// so if you do not ensure the `Child` has exited then it will continue to -/// run, even after the `Child` handle to the child process has gone out of -/// scope. -/// -/// Calling [`wait`] (or other functions that wrap around it) will make -/// the parent process wait until the child has actually exited before -/// continuing. -/// -/// # Warning -/// -/// On some systems, calling [`wait`] or similar is necessary for the OS to -/// release resources. A process that terminated but has not been waited on is -/// still around as a "zombie". Leaving too many zombies around may exhaust -/// global resources (for example process IDs). -/// -/// The standard library does *not* automatically wait on child processes (not -/// even if the `Child` is dropped), it is up to the application developer to do -/// so. As a consequence, dropping `Child` handles without waiting on them first -/// is not recommended in long-running applications. -/// -/// # Examples -/// -/// ```should_panic -/// use std::process::Command; -/// -/// let mut child = Command::new("/bin/cat") -/// .arg("file.txt") -/// .spawn() -/// .expect("failed to execute child"); -/// -/// let ecode = child.wait().expect("failed to wait on child"); -/// -/// assert!(ecode.success()); -/// ``` -/// -/// [`wait`]: Child::wait -#[stable(feature = "process", since = "1.0.0")] -pub struct Child { - pub(crate) handle: imp::Process, - - /// The handle for writing to the child's standard input (stdin), if it - /// has been captured. You might find it helpful to do - /// - /// ```ignore (incomplete) - /// let stdin = child.stdin.take().unwrap(); - /// ``` - /// - /// to avoid partially moving the `child` and thus blocking yourself from calling - /// functions on `child` while using `stdin`. - #[stable(feature = "process", since = "1.0.0")] - pub stdin: Option, - - /// The handle for reading from the child's standard output (stdout), if it - /// has been captured. You might find it helpful to do - /// - /// ```ignore (incomplete) - /// let stdout = child.stdout.take().unwrap(); - /// ``` - /// - /// to avoid partially moving the `child` and thus blocking yourself from calling - /// functions on `child` while using `stdout`. - #[stable(feature = "process", since = "1.0.0")] - pub stdout: Option, - - /// The handle for reading from the child's standard error (stderr), if it - /// has been captured. You might find it helpful to do - /// - /// ```ignore (incomplete) - /// let stderr = child.stderr.take().unwrap(); - /// ``` - /// - /// to avoid partially moving the `child` and thus blocking yourself from calling - /// functions on `child` while using `stderr`. - #[stable(feature = "process", since = "1.0.0")] - pub stderr: Option, -} - -/// Allows extension traits within `std`. -#[unstable(feature = "sealed", issue = "none")] -impl crate::sealed::Sealed for Child {} - -impl AsInner for Child { - #[inline] - fn as_inner(&self) -> &imp::Process { - &self.handle - } -} - -impl FromInner<(imp::Process, imp::StdioPipes)> for Child { - fn from_inner((handle, io): (imp::Process, imp::StdioPipes)) -> Child { - Child { - handle, - stdin: io.stdin.map(ChildStdin::from_inner), - stdout: io.stdout.map(ChildStdout::from_inner), - stderr: io.stderr.map(ChildStderr::from_inner), - } - } -} - -impl IntoInner for Child { - fn into_inner(self) -> imp::Process { - self.handle - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for Child { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Child") - .field("stdin", &self.stdin) - .field("stdout", &self.stdout) - .field("stderr", &self.stderr) - .finish_non_exhaustive() - } -} - -/// A handle to a child process's standard input (stdin). -/// -/// This struct is used in the [`stdin`] field on [`Child`]. -/// -/// When an instance of `ChildStdin` is [dropped], the `ChildStdin`'s underlying -/// file handle will be closed. If the child process was blocked on input prior -/// to being dropped, it will become unblocked after dropping. -/// -/// [`stdin`]: Child::stdin -/// [dropped]: Drop -#[stable(feature = "process", since = "1.0.0")] -pub struct ChildStdin { - inner: AnonPipe, -} - -// In addition to the `impl`s here, `ChildStdin` also has `impl`s for -// `AsFd`/`From`/`Into` and -// `AsRawFd`/`IntoRawFd`/`FromRawFd`, on Unix and WASI, and -// `AsHandle`/`From`/`Into` and -// `AsRawHandle`/`IntoRawHandle`/`FromRawHandle` on Windows. - -#[stable(feature = "process", since = "1.0.0")] -impl Write for ChildStdin { - fn write(&mut self, buf: &[u8]) -> io::Result { - (&*self).write(buf) - } - - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - (&*self).write_vectored(bufs) - } - - fn is_write_vectored(&self) -> bool { - io::Write::is_write_vectored(&&*self) - } - - #[inline] - fn flush(&mut self) -> io::Result<()> { - (&*self).flush() - } -} - -#[stable(feature = "write_mt", since = "1.48.0")] -impl Write for &ChildStdin { - fn write(&mut self, buf: &[u8]) -> io::Result { - self.inner.write(buf) - } - - fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> io::Result { - self.inner.write_vectored(bufs) - } - - fn is_write_vectored(&self) -> bool { - self.inner.is_write_vectored() - } - - #[inline] - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -impl AsInner for ChildStdin { - #[inline] - fn as_inner(&self) -> &AnonPipe { - &self.inner - } -} - -impl IntoInner for ChildStdin { - fn into_inner(self) -> AnonPipe { - self.inner - } -} - -impl FromInner for ChildStdin { - fn from_inner(pipe: AnonPipe) -> ChildStdin { - ChildStdin { inner: pipe } - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for ChildStdin { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("ChildStdin").finish_non_exhaustive() - } -} - -/// A handle to a child process's standard output (stdout). -/// -/// This struct is used in the [`stdout`] field on [`Child`]. -/// -/// When an instance of `ChildStdout` is [dropped], the `ChildStdout`'s -/// underlying file handle will be closed. -/// -/// [`stdout`]: Child::stdout -/// [dropped]: Drop -#[stable(feature = "process", since = "1.0.0")] -pub struct ChildStdout { - inner: AnonPipe, -} - -// In addition to the `impl`s here, `ChildStdout` also has `impl`s for -// `AsFd`/`From`/`Into` and -// `AsRawFd`/`IntoRawFd`/`FromRawFd`, on Unix and WASI, and -// `AsHandle`/`From`/`Into` and -// `AsRawHandle`/`IntoRawHandle`/`FromRawHandle` on Windows. - -#[stable(feature = "process", since = "1.0.0")] -impl Read for ChildStdout { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - self.inner.read(buf) - } - - fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> io::Result<()> { - self.inner.read_buf(buf) - } - - fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - self.inner.read_vectored(bufs) - } - - #[inline] - fn is_read_vectored(&self) -> bool { - self.inner.is_read_vectored() - } - - fn read_to_end(&mut self, buf: &mut Vec) -> io::Result { - self.inner.read_to_end(buf) - } -} - -impl AsInner for ChildStdout { - #[inline] - fn as_inner(&self) -> &AnonPipe { - &self.inner - } -} - -impl IntoInner for ChildStdout { - fn into_inner(self) -> AnonPipe { - self.inner - } -} - -impl FromInner for ChildStdout { - fn from_inner(pipe: AnonPipe) -> ChildStdout { - ChildStdout { inner: pipe } - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for ChildStdout { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("ChildStdout").finish_non_exhaustive() - } -} - -/// A handle to a child process's stderr. -/// -/// This struct is used in the [`stderr`] field on [`Child`]. -/// -/// When an instance of `ChildStderr` is [dropped], the `ChildStderr`'s -/// underlying file handle will be closed. -/// -/// [`stderr`]: Child::stderr -/// [dropped]: Drop -#[stable(feature = "process", since = "1.0.0")] -pub struct ChildStderr { - inner: AnonPipe, -} - -// In addition to the `impl`s here, `ChildStderr` also has `impl`s for -// `AsFd`/`From`/`Into` and -// `AsRawFd`/`IntoRawFd`/`FromRawFd`, on Unix and WASI, and -// `AsHandle`/`From`/`Into` and -// `AsRawHandle`/`IntoRawHandle`/`FromRawHandle` on Windows. - -#[stable(feature = "process", since = "1.0.0")] -impl Read for ChildStderr { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - self.inner.read(buf) - } - - fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> io::Result<()> { - self.inner.read_buf(buf) - } - - fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - self.inner.read_vectored(bufs) - } - - #[inline] - fn is_read_vectored(&self) -> bool { - self.inner.is_read_vectored() - } - - fn read_to_end(&mut self, buf: &mut Vec) -> io::Result { - self.inner.read_to_end(buf) - } -} - -impl AsInner for ChildStderr { - #[inline] - fn as_inner(&self) -> &AnonPipe { - &self.inner - } -} - -impl IntoInner for ChildStderr { - fn into_inner(self) -> AnonPipe { - self.inner - } -} - -impl FromInner for ChildStderr { - fn from_inner(pipe: AnonPipe) -> ChildStderr { - ChildStderr { inner: pipe } - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for ChildStderr { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("ChildStderr").finish_non_exhaustive() - } -} - -/// A process builder, providing fine-grained control -/// over how a new process should be spawned. -/// -/// A default configuration can be -/// generated using `Command::new(program)`, where `program` gives a path to the -/// program to be executed. Additional builder methods allow the configuration -/// to be changed (for example, by adding arguments) prior to spawning: -/// -/// ``` -/// use std::process::Command; -/// -/// let output = if cfg!(target_os = "windows") { -/// Command::new("cmd") -/// .args(["/C", "echo hello"]) -/// .output() -/// .expect("failed to execute process") -/// } else { -/// Command::new("sh") -/// .arg("-c") -/// .arg("echo hello") -/// .output() -/// .expect("failed to execute process") -/// }; -/// -/// let hello = output.stdout; -/// ``` -/// -/// `Command` can be reused to spawn multiple processes. The builder methods -/// change the command without needing to immediately spawn the process. -/// -/// ```no_run -/// use std::process::Command; -/// -/// let mut echo_hello = Command::new("sh"); -/// echo_hello.arg("-c").arg("echo hello"); -/// let hello_1 = echo_hello.output().expect("failed to execute process"); -/// let hello_2 = echo_hello.output().expect("failed to execute process"); -/// ``` -/// -/// Similarly, you can call builder methods after spawning a process and then -/// spawn a new process with the modified settings. -/// -/// ```no_run -/// use std::process::Command; -/// -/// let mut list_dir = Command::new("ls"); -/// -/// // Execute `ls` in the current directory of the program. -/// list_dir.status().expect("process failed to execute"); -/// -/// println!(); -/// -/// // Change `ls` to execute in the root directory. -/// list_dir.current_dir("/"); -/// -/// // And then execute `ls` again but in the root directory. -/// list_dir.status().expect("process failed to execute"); -/// ``` -#[stable(feature = "process", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "Command")] -pub struct Command { - inner: imp::Command, -} - -/// Allows extension traits within `std`. -#[unstable(feature = "sealed", issue = "none")] -impl crate::sealed::Sealed for Command {} - -impl Command { - /// Constructs a new `Command` for launching the program at - /// path `program`, with the following default configuration: - /// - /// * No arguments to the program - /// * Inherit the current process's environment - /// * Inherit the current process's working directory - /// * Inherit stdin/stdout/stderr for [`spawn`] or [`status`], but create pipes for [`output`] - /// - /// [`spawn`]: Self::spawn - /// [`status`]: Self::status - /// [`output`]: Self::output - /// - /// Builder methods are provided to change these defaults and - /// otherwise configure the process. - /// - /// If `program` is not an absolute path, the `PATH` will be searched in - /// an OS-defined way. - /// - /// The search path to be used may be controlled by setting the - /// `PATH` environment variable on the Command, - /// but this has some implementation limitations on Windows - /// (see issue #37519). - /// - /// # Platform-specific behavior - /// - /// Note on Windows: For executable files with the .exe extension, - /// it can be omitted when specifying the program for this Command. - /// However, if the file has a different extension, - /// a filename including the extension needs to be provided, - /// otherwise the file won't be found. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ```no_run - /// use std::process::Command; - /// - /// Command::new("sh") - /// .spawn() - /// .expect("sh command failed to start"); - /// ``` - #[stable(feature = "process", since = "1.0.0")] - pub fn new>(program: S) -> Command { - Command { inner: imp::Command::new(program.as_ref()) } - } - - /// Adds an argument to pass to the program. - /// - /// Only one argument can be passed per use. So instead of: - /// - /// ```no_run - /// # std::process::Command::new("sh") - /// .arg("-C /path/to/repo") - /// # ; - /// ``` - /// - /// usage would be: - /// - /// ```no_run - /// # std::process::Command::new("sh") - /// .arg("-C") - /// .arg("/path/to/repo") - /// # ; - /// ``` - /// - /// To pass multiple arguments see [`args`]. - /// - /// [`args`]: Command::args - /// - /// Note that the argument is not passed through a shell, but given - /// literally to the program. This means that shell syntax like quotes, - /// escaped characters, word splitting, glob patterns, variable substitution, - /// etc. have no effect. - /// - ///

- /// - /// # Examples - /// - /// Basic usage: - /// - /// ```no_run - /// use std::process::Command; - /// - /// Command::new("ls") - /// .arg("-l") - /// .arg("-a") - /// .spawn() - /// .expect("ls command failed to start"); - /// ``` - #[stable(feature = "process", since = "1.0.0")] - pub fn arg>(&mut self, arg: S) -> &mut Command { - self.inner.arg(arg.as_ref()); - self - } - - /// Adds multiple arguments to pass to the program. - /// - /// To pass a single argument see [`arg`]. - /// - /// [`arg`]: Command::arg - /// - /// Note that the arguments are not passed through a shell, but given - /// literally to the program. This means that shell syntax like quotes, - /// escaped characters, word splitting, glob patterns, variable substitution, etc. - /// have no effect. - /// - ///
- /// - /// On Windows, use caution with untrusted inputs. Most applications use the - /// standard convention for decoding arguments passed to them. These are safe to - /// use with `arg`. However, some applications such as `cmd.exe` and `.bat` files - /// use a non-standard way of decoding arguments. They are therefore vulnerable - /// to malicious input. - /// - /// In the case of `cmd.exe` this is especially important because a malicious - /// argument can potentially run arbitrary shell commands. - /// - /// See [Windows argument splitting][windows-args] for more details - /// or [`raw_arg`] for manually implementing non-standard argument encoding. - /// - /// [`raw_arg`]: crate::os::windows::process::CommandExt::raw_arg - /// [windows-args]: crate::process#windows-argument-splitting - /// - ///
- /// - /// # Examples - /// - /// Basic usage: - /// - /// ```no_run - /// use std::process::Command; - /// - /// Command::new("ls") - /// .args(["-l", "-a"]) - /// .spawn() - /// .expect("ls command failed to start"); - /// ``` - #[stable(feature = "process", since = "1.0.0")] - pub fn args(&mut self, args: I) -> &mut Command - where - I: IntoIterator, - S: AsRef, - { - for arg in args { - self.arg(arg.as_ref()); - } - self - } - - /// Inserts or updates an explicit environment variable mapping. - /// - /// This method allows you to add an environment variable mapping to the spawned process or - /// overwrite a previously set value. You can use [`Command::envs`] to set multiple environment - /// variables simultaneously. - /// - /// Child processes will inherit environment variables from their parent process by default. - /// Environment variables explicitly set using [`Command::env`] take precedence over inherited - /// variables. You can disable environment variable inheritance entirely using - /// [`Command::env_clear`] or for a single key using [`Command::env_remove`]. - /// - /// Note that environment variable names are case-insensitive (but - /// case-preserving) on Windows and case-sensitive on all other platforms. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ```no_run - /// use std::process::Command; - /// - /// Command::new("ls") - /// .env("PATH", "/bin") - /// .spawn() - /// .expect("ls command failed to start"); - /// ``` - #[stable(feature = "process", since = "1.0.0")] - pub fn env(&mut self, key: K, val: V) -> &mut Command - where - K: AsRef, - V: AsRef, - { - self.inner.env_mut().set(key.as_ref(), val.as_ref()); - self - } - - /// Inserts or updates multiple explicit environment variable mappings. - /// - /// This method allows you to add multiple environment variable mappings to the spawned process - /// or overwrite previously set values. You can use [`Command::env`] to set a single environment - /// variable. - /// - /// Child processes will inherit environment variables from their parent process by default. - /// Environment variables explicitly set using [`Command::envs`] take precedence over inherited - /// variables. You can disable environment variable inheritance entirely using - /// [`Command::env_clear`] or for a single key using [`Command::env_remove`]. - /// - /// Note that environment variable names are case-insensitive (but case-preserving) on Windows - /// and case-sensitive on all other platforms. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ```no_run - /// use std::process::{Command, Stdio}; - /// use std::env; - /// use std::collections::HashMap; - /// - /// let filtered_env : HashMap = - /// env::vars().filter(|&(ref k, _)| - /// k == "TERM" || k == "TZ" || k == "LANG" || k == "PATH" - /// ).collect(); - /// - /// Command::new("printenv") - /// .stdin(Stdio::null()) - /// .stdout(Stdio::inherit()) - /// .env_clear() - /// .envs(&filtered_env) - /// .spawn() - /// .expect("printenv failed to start"); - /// ``` - #[stable(feature = "command_envs", since = "1.19.0")] - pub fn envs(&mut self, vars: I) -> &mut Command - where - I: IntoIterator, - K: AsRef, - V: AsRef, - { - for (ref key, ref val) in vars { - self.inner.env_mut().set(key.as_ref(), val.as_ref()); - } - self - } - - /// Removes an explicitly set environment variable and prevents inheriting it from a parent - /// process. - /// - /// This method will remove the explicit value of an environment variable set via - /// [`Command::env`] or [`Command::envs`]. In addition, it will prevent the spawned child - /// process from inheriting that environment variable from its parent process. - /// - /// After calling [`Command::env_remove`], the value associated with its key from - /// [`Command::get_envs`] will be [`None`]. - /// - /// To clear all explicitly set environment variables and disable all environment variable - /// inheritance, you can use [`Command::env_clear`]. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ```no_run - /// use std::process::Command; - /// - /// Command::new("ls") - /// .env_remove("PATH") - /// .spawn() - /// .expect("ls command failed to start"); - /// ``` - #[stable(feature = "process", since = "1.0.0")] - pub fn env_remove>(&mut self, key: K) -> &mut Command { - self.inner.env_mut().remove(key.as_ref()); - self - } - - /// Clears all explicitly set environment variables and prevents inheriting any parent process - /// environment variables. - /// - /// This method will remove all explicitly added environment variables set via [`Command::env`] - /// or [`Command::envs`]. In addition, it will prevent the spawned child process from inheriting - /// any environment variable from its parent process. - /// - /// After calling [`Command::env_clear`], the iterator from [`Command::get_envs`] will be - /// empty. - /// - /// You can use [`Command::env_remove`] to clear a single mapping. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ```no_run - /// use std::process::Command; - /// - /// Command::new("ls") - /// .env_clear() - /// .spawn() - /// .expect("ls command failed to start"); - /// ``` - #[stable(feature = "process", since = "1.0.0")] - pub fn env_clear(&mut self) -> &mut Command { - self.inner.env_mut().clear(); - self - } - - /// Sets the working directory for the child process. - /// - /// # Platform-specific behavior - /// - /// If the program path is relative (e.g., `"./script.sh"`), it's ambiguous - /// whether it should be interpreted relative to the parent's working - /// directory or relative to `current_dir`. The behavior in this case is - /// platform specific and unstable, and it's recommended to use - /// [`canonicalize`] to get an absolute program path instead. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ```no_run - /// use std::process::Command; - /// - /// Command::new("ls") - /// .current_dir("/bin") - /// .spawn() - /// .expect("ls command failed to start"); - /// ``` - /// - /// [`canonicalize`]: crate::fs::canonicalize - #[stable(feature = "process", since = "1.0.0")] - pub fn current_dir>(&mut self, dir: P) -> &mut Command { - self.inner.cwd(dir.as_ref().as_ref()); - self - } - - /// Configuration for the child process's standard input (stdin) handle. - /// - /// Defaults to [`inherit`] when used with [`spawn`] or [`status`], and - /// defaults to [`piped`] when used with [`output`]. - /// - /// [`inherit`]: Stdio::inherit - /// [`piped`]: Stdio::piped - /// [`spawn`]: Self::spawn - /// [`status`]: Self::status - /// [`output`]: Self::output - /// - /// # Examples - /// - /// Basic usage: - /// - /// ```no_run - /// use std::process::{Command, Stdio}; - /// - /// Command::new("ls") - /// .stdin(Stdio::null()) - /// .spawn() - /// .expect("ls command failed to start"); - /// ``` - #[stable(feature = "process", since = "1.0.0")] - pub fn stdin>(&mut self, cfg: T) -> &mut Command { - self.inner.stdin(cfg.into().0); - self - } - - /// Configuration for the child process's standard output (stdout) handle. - /// - /// Defaults to [`inherit`] when used with [`spawn`] or [`status`], and - /// defaults to [`piped`] when used with [`output`]. - /// - /// [`inherit`]: Stdio::inherit - /// [`piped`]: Stdio::piped - /// [`spawn`]: Self::spawn - /// [`status`]: Self::status - /// [`output`]: Self::output - /// - /// # Examples - /// - /// Basic usage: - /// - /// ```no_run - /// use std::process::{Command, Stdio}; - /// - /// Command::new("ls") - /// .stdout(Stdio::null()) - /// .spawn() - /// .expect("ls command failed to start"); - /// ``` - #[stable(feature = "process", since = "1.0.0")] - pub fn stdout>(&mut self, cfg: T) -> &mut Command { - self.inner.stdout(cfg.into().0); - self - } - - /// Configuration for the child process's standard error (stderr) handle. - /// - /// Defaults to [`inherit`] when used with [`spawn`] or [`status`], and - /// defaults to [`piped`] when used with [`output`]. - /// - /// [`inherit`]: Stdio::inherit - /// [`piped`]: Stdio::piped - /// [`spawn`]: Self::spawn - /// [`status`]: Self::status - /// [`output`]: Self::output - /// - /// # Examples - /// - /// Basic usage: - /// - /// ```no_run - /// use std::process::{Command, Stdio}; - /// - /// Command::new("ls") - /// .stderr(Stdio::null()) - /// .spawn() - /// .expect("ls command failed to start"); - /// ``` - #[stable(feature = "process", since = "1.0.0")] - pub fn stderr>(&mut self, cfg: T) -> &mut Command { - self.inner.stderr(cfg.into().0); - self - } - - /// Executes the command as a child process, returning a handle to it. - /// - /// By default, stdin, stdout and stderr are inherited from the parent. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ```no_run - /// use std::process::Command; - /// - /// Command::new("ls") - /// .spawn() - /// .expect("ls command failed to start"); - /// ``` - #[stable(feature = "process", since = "1.0.0")] - pub fn spawn(&mut self) -> io::Result { - self.inner.spawn(imp::Stdio::Inherit, true).map(Child::from_inner) - } - - /// Executes the command as a child process, waiting for it to finish and - /// collecting all of its output. - /// - /// By default, stdout and stderr are captured (and used to provide the - /// resulting output). Stdin is not inherited from the parent and any - /// attempt by the child process to read from the stdin stream will result - /// in the stream immediately closing. - /// - /// # Examples - /// - /// ```should_panic - /// use std::process::Command; - /// use std::io::{self, Write}; - /// let output = Command::new("/bin/cat") - /// .arg("file.txt") - /// .output() - /// .expect("failed to execute process"); - /// - /// println!("status: {}", output.status); - /// io::stdout().write_all(&output.stdout).unwrap(); - /// io::stderr().write_all(&output.stderr).unwrap(); - /// - /// assert!(output.status.success()); - /// ``` - #[stable(feature = "process", since = "1.0.0")] - pub fn output(&mut self) -> io::Result { - let (status, stdout, stderr) = self.inner.output()?; - Ok(Output { status: ExitStatus(status), stdout, stderr }) - } - - /// Executes a command as a child process, waiting for it to finish and - /// collecting its status. - /// - /// By default, stdin, stdout and stderr are inherited from the parent. - /// - /// # Examples - /// - /// ```should_panic - /// use std::process::Command; - /// - /// let status = Command::new("/bin/cat") - /// .arg("file.txt") - /// .status() - /// .expect("failed to execute process"); - /// - /// println!("process finished with: {status}"); - /// - /// assert!(status.success()); - /// ``` - #[stable(feature = "process", since = "1.0.0")] - pub fn status(&mut self) -> io::Result { - self.inner - .spawn(imp::Stdio::Inherit, true) - .map(Child::from_inner) - .and_then(|mut p| p.wait()) - } - - /// Returns the path to the program that was given to [`Command::new`]. - /// - /// # Examples - /// - /// ``` - /// use std::process::Command; - /// - /// let cmd = Command::new("echo"); - /// assert_eq!(cmd.get_program(), "echo"); - /// ``` - #[must_use] - #[stable(feature = "command_access", since = "1.57.0")] - pub fn get_program(&self) -> &OsStr { - self.inner.get_program() - } - - /// Returns an iterator of the arguments that will be passed to the program. - /// - /// This does not include the path to the program as the first argument; - /// it only includes the arguments specified with [`Command::arg`] and - /// [`Command::args`]. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsStr; - /// use std::process::Command; - /// - /// let mut cmd = Command::new("echo"); - /// cmd.arg("first").arg("second"); - /// let args: Vec<&OsStr> = cmd.get_args().collect(); - /// assert_eq!(args, &["first", "second"]); - /// ``` - #[stable(feature = "command_access", since = "1.57.0")] - pub fn get_args(&self) -> CommandArgs<'_> { - CommandArgs { inner: self.inner.get_args() } - } - - /// Returns an iterator of the environment variables explicitly set for the child process. - /// - /// Environment variables explicitly set using [`Command::env`], [`Command::envs`], and - /// [`Command::env_remove`] can be retrieved with this method. - /// - /// Note that this output does not include environment variables inherited from the parent - /// process. - /// - /// Each element is a tuple key/value pair `(&OsStr, Option<&OsStr>)`. A [`None`] value - /// indicates its key was explicitly removed via [`Command::env_remove`]. The associated key for - /// the [`None`] value will no longer inherit from its parent process. - /// - /// An empty iterator can indicate that no explicit mappings were added or that - /// [`Command::env_clear`] was called. After calling [`Command::env_clear`], the child process - /// will not inherit any environment variables from its parent process. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::OsStr; - /// use std::process::Command; - /// - /// let mut cmd = Command::new("ls"); - /// cmd.env("TERM", "dumb").env_remove("TZ"); - /// let envs: Vec<(&OsStr, Option<&OsStr>)> = cmd.get_envs().collect(); - /// assert_eq!(envs, &[ - /// (OsStr::new("TERM"), Some(OsStr::new("dumb"))), - /// (OsStr::new("TZ"), None) - /// ]); - /// ``` - #[stable(feature = "command_access", since = "1.57.0")] - pub fn get_envs(&self) -> CommandEnvs<'_> { - self.inner.get_envs() - } - - /// Returns the working directory for the child process. - /// - /// This returns [`None`] if the working directory will not be changed. - /// - /// # Examples - /// - /// ``` - /// use std::path::Path; - /// use std::process::Command; - /// - /// let mut cmd = Command::new("ls"); - /// assert_eq!(cmd.get_current_dir(), None); - /// cmd.current_dir("/bin"); - /// assert_eq!(cmd.get_current_dir(), Some(Path::new("/bin"))); - /// ``` - #[must_use] - #[stable(feature = "command_access", since = "1.57.0")] - pub fn get_current_dir(&self) -> Option<&Path> { - self.inner.get_current_dir() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for Command { - /// Format the program and arguments of a Command for display. Any - /// non-utf8 data is lossily converted using the utf8 replacement - /// character. - /// - /// The default format approximates a shell invocation of the program along with its - /// arguments. It does not include most of the other command properties. The output is not guaranteed to work - /// (e.g. due to lack of shell-escaping or differences in path resolution). - /// On some platforms you can use [the alternate syntax] to show more fields. - /// - /// Note that the debug implementation is platform-specific. - /// - /// [the alternate syntax]: fmt#sign0 - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.inner.fmt(f) - } -} - -impl AsInner for Command { - #[inline] - fn as_inner(&self) -> &imp::Command { - &self.inner - } -} - -impl AsInnerMut for Command { - #[inline] - fn as_inner_mut(&mut self) -> &mut imp::Command { - &mut self.inner - } -} - -/// An iterator over the command arguments. -/// -/// This struct is created by [`Command::get_args`]. See its documentation for -/// more. -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "command_access", since = "1.57.0")] -#[derive(Debug)] -pub struct CommandArgs<'a> { - inner: imp::CommandArgs<'a>, -} - -#[stable(feature = "command_access", since = "1.57.0")] -impl<'a> Iterator for CommandArgs<'a> { - type Item = &'a OsStr; - fn next(&mut self) -> Option<&'a OsStr> { - self.inner.next() - } - fn size_hint(&self) -> (usize, Option) { - self.inner.size_hint() - } -} - -#[stable(feature = "command_access", since = "1.57.0")] -impl<'a> ExactSizeIterator for CommandArgs<'a> { - fn len(&self) -> usize { - self.inner.len() - } - fn is_empty(&self) -> bool { - self.inner.is_empty() - } -} - -/// The output of a finished process. -/// -/// This is returned in a Result by either the [`output`] method of a -/// [`Command`], or the [`wait_with_output`] method of a [`Child`] -/// process. -/// -/// [`output`]: Command::output -/// [`wait_with_output`]: Child::wait_with_output -#[derive(PartialEq, Eq, Clone)] -#[stable(feature = "process", since = "1.0.0")] -pub struct Output { - /// The status (exit code) of the process. - #[stable(feature = "process", since = "1.0.0")] - pub status: ExitStatus, - /// The data that the process wrote to stdout. - #[stable(feature = "process", since = "1.0.0")] - pub stdout: Vec, - /// The data that the process wrote to stderr. - #[stable(feature = "process", since = "1.0.0")] - pub stderr: Vec, -} - -// If either stderr or stdout are valid utf8 strings it prints the valid -// strings, otherwise it prints the byte sequence instead -#[stable(feature = "process_output_debug", since = "1.7.0")] -impl fmt::Debug for Output { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - let stdout_utf8 = str::from_utf8(&self.stdout); - let stdout_debug: &dyn fmt::Debug = match stdout_utf8 { - Ok(ref str) => str, - Err(_) => &self.stdout, - }; - - let stderr_utf8 = str::from_utf8(&self.stderr); - let stderr_debug: &dyn fmt::Debug = match stderr_utf8 { - Ok(ref str) => str, - Err(_) => &self.stderr, - }; - - fmt.debug_struct("Output") - .field("status", &self.status) - .field("stdout", stdout_debug) - .field("stderr", stderr_debug) - .finish() - } -} - -/// Describes what to do with a standard I/O stream for a child process when -/// passed to the [`stdin`], [`stdout`], and [`stderr`] methods of [`Command`]. -/// -/// [`stdin`]: Command::stdin -/// [`stdout`]: Command::stdout -/// [`stderr`]: Command::stderr -#[stable(feature = "process", since = "1.0.0")] -pub struct Stdio(imp::Stdio); - -impl Stdio { - /// A new pipe should be arranged to connect the parent and child processes. - /// - /// # Examples - /// - /// With stdout: - /// - /// ```no_run - /// use std::process::{Command, Stdio}; - /// - /// let output = Command::new("echo") - /// .arg("Hello, world!") - /// .stdout(Stdio::piped()) - /// .output() - /// .expect("Failed to execute command"); - /// - /// assert_eq!(String::from_utf8_lossy(&output.stdout), "Hello, world!\n"); - /// // Nothing echoed to console - /// ``` - /// - /// With stdin: - /// - /// ```no_run - /// use std::io::Write; - /// use std::process::{Command, Stdio}; - /// - /// let mut child = Command::new("rev") - /// .stdin(Stdio::piped()) - /// .stdout(Stdio::piped()) - /// .spawn() - /// .expect("Failed to spawn child process"); - /// - /// let mut stdin = child.stdin.take().expect("Failed to open stdin"); - /// std::thread::spawn(move || { - /// stdin.write_all("Hello, world!".as_bytes()).expect("Failed to write to stdin"); - /// }); - /// - /// let output = child.wait_with_output().expect("Failed to read stdout"); - /// assert_eq!(String::from_utf8_lossy(&output.stdout), "!dlrow ,olleH"); - /// ``` - /// - /// Writing more than a pipe buffer's worth of input to stdin without also reading - /// stdout and stderr at the same time may cause a deadlock. - /// This is an issue when running any program that doesn't guarantee that it reads - /// its entire stdin before writing more than a pipe buffer's worth of output. - /// The size of a pipe buffer varies on different targets. - /// - #[must_use] - #[stable(feature = "process", since = "1.0.0")] - pub fn piped() -> Stdio { - Stdio(imp::Stdio::MakePipe) - } - - /// The child inherits from the corresponding parent descriptor. - /// - /// # Examples - /// - /// With stdout: - /// - /// ```no_run - /// use std::process::{Command, Stdio}; - /// - /// let output = Command::new("echo") - /// .arg("Hello, world!") - /// .stdout(Stdio::inherit()) - /// .output() - /// .expect("Failed to execute command"); - /// - /// assert_eq!(String::from_utf8_lossy(&output.stdout), ""); - /// // "Hello, world!" echoed to console - /// ``` - /// - /// With stdin: - /// - /// ```no_run - /// use std::process::{Command, Stdio}; - /// use std::io::{self, Write}; - /// - /// let output = Command::new("rev") - /// .stdin(Stdio::inherit()) - /// .stdout(Stdio::piped()) - /// .output() - /// .expect("Failed to execute command"); - /// - /// print!("You piped in the reverse of: "); - /// io::stdout().write_all(&output.stdout).unwrap(); - /// ``` - #[must_use] - #[stable(feature = "process", since = "1.0.0")] - pub fn inherit() -> Stdio { - Stdio(imp::Stdio::Inherit) - } - - /// This stream will be ignored. This is the equivalent of attaching the - /// stream to `/dev/null`. - /// - /// # Examples - /// - /// With stdout: - /// - /// ```no_run - /// use std::process::{Command, Stdio}; - /// - /// let output = Command::new("echo") - /// .arg("Hello, world!") - /// .stdout(Stdio::null()) - /// .output() - /// .expect("Failed to execute command"); - /// - /// assert_eq!(String::from_utf8_lossy(&output.stdout), ""); - /// // Nothing echoed to console - /// ``` - /// - /// With stdin: - /// - /// ```no_run - /// use std::process::{Command, Stdio}; - /// - /// let output = Command::new("rev") - /// .stdin(Stdio::null()) - /// .stdout(Stdio::piped()) - /// .output() - /// .expect("Failed to execute command"); - /// - /// assert_eq!(String::from_utf8_lossy(&output.stdout), ""); - /// // Ignores any piped-in input - /// ``` - #[must_use] - #[stable(feature = "process", since = "1.0.0")] - pub fn null() -> Stdio { - Stdio(imp::Stdio::Null) - } - - /// Returns `true` if this requires [`Command`] to create a new pipe. - /// - /// # Example - /// - /// ``` - /// #![feature(stdio_makes_pipe)] - /// use std::process::Stdio; - /// - /// let io = Stdio::piped(); - /// assert_eq!(io.makes_pipe(), true); - /// ``` - #[unstable(feature = "stdio_makes_pipe", issue = "98288")] - pub fn makes_pipe(&self) -> bool { - matches!(self.0, imp::Stdio::MakePipe) - } -} - -impl FromInner for Stdio { - fn from_inner(inner: imp::Stdio) -> Stdio { - Stdio(inner) - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for Stdio { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Stdio").finish_non_exhaustive() - } -} - -#[stable(feature = "stdio_from", since = "1.20.0")] -impl From for Stdio { - /// Converts a [`ChildStdin`] into a [`Stdio`]. - /// - /// # Examples - /// - /// `ChildStdin` will be converted to `Stdio` using `Stdio::from` under the hood. - /// - /// ```rust,no_run - /// use std::process::{Command, Stdio}; - /// - /// let reverse = Command::new("rev") - /// .stdin(Stdio::piped()) - /// .spawn() - /// .expect("failed reverse command"); - /// - /// let _echo = Command::new("echo") - /// .arg("Hello, world!") - /// .stdout(reverse.stdin.unwrap()) // Converted into a Stdio here - /// .output() - /// .expect("failed echo command"); - /// - /// // "!dlrow ,olleH" echoed to console - /// ``` - fn from(child: ChildStdin) -> Stdio { - Stdio::from_inner(child.into_inner().into()) - } -} - -#[stable(feature = "stdio_from", since = "1.20.0")] -impl From for Stdio { - /// Converts a [`ChildStdout`] into a [`Stdio`]. - /// - /// # Examples - /// - /// `ChildStdout` will be converted to `Stdio` using `Stdio::from` under the hood. - /// - /// ```rust,no_run - /// use std::process::{Command, Stdio}; - /// - /// let hello = Command::new("echo") - /// .arg("Hello, world!") - /// .stdout(Stdio::piped()) - /// .spawn() - /// .expect("failed echo command"); - /// - /// let reverse = Command::new("rev") - /// .stdin(hello.stdout.unwrap()) // Converted into a Stdio here - /// .output() - /// .expect("failed reverse command"); - /// - /// assert_eq!(reverse.stdout, b"!dlrow ,olleH\n"); - /// ``` - fn from(child: ChildStdout) -> Stdio { - Stdio::from_inner(child.into_inner().into()) - } -} - -#[stable(feature = "stdio_from", since = "1.20.0")] -impl From for Stdio { - /// Converts a [`ChildStderr`] into a [`Stdio`]. - /// - /// # Examples - /// - /// ```rust,no_run - /// use std::process::{Command, Stdio}; - /// - /// let reverse = Command::new("rev") - /// .arg("non_existing_file.txt") - /// .stderr(Stdio::piped()) - /// .spawn() - /// .expect("failed reverse command"); - /// - /// let cat = Command::new("cat") - /// .arg("-") - /// .stdin(reverse.stderr.unwrap()) // Converted into a Stdio here - /// .output() - /// .expect("failed echo command"); - /// - /// assert_eq!( - /// String::from_utf8_lossy(&cat.stdout), - /// "rev: cannot open non_existing_file.txt: No such file or directory\n" - /// ); - /// ``` - fn from(child: ChildStderr) -> Stdio { - Stdio::from_inner(child.into_inner().into()) - } -} - -#[stable(feature = "stdio_from", since = "1.20.0")] -impl From for Stdio { - /// Converts a [`File`](fs::File) into a [`Stdio`]. - /// - /// # Examples - /// - /// `File` will be converted to `Stdio` using `Stdio::from` under the hood. - /// - /// ```rust,no_run - /// use std::fs::File; - /// use std::process::Command; - /// - /// // With the `foo.txt` file containing "Hello, world!" - /// let file = File::open("foo.txt").unwrap(); - /// - /// let reverse = Command::new("rev") - /// .stdin(file) // Implicit File conversion into a Stdio - /// .output() - /// .expect("failed reverse command"); - /// - /// assert_eq!(reverse.stdout, b"!dlrow ,olleH"); - /// ``` - fn from(file: fs::File) -> Stdio { - Stdio::from_inner(file.into_inner().into()) - } -} - -#[stable(feature = "stdio_from_stdio", since = "1.74.0")] -impl From for Stdio { - /// Redirect command stdout/stderr to our stdout - /// - /// # Examples - /// - /// ```rust - /// #![feature(exit_status_error)] - /// use std::io; - /// use std::process::Command; - /// - /// # fn test() -> Result<(), Box> { - /// let output = Command::new("whoami") - // "whoami" is a command which exists on both Unix and Windows, - // and which succeeds, producing some stdout output but no stderr. - /// .stdout(io::stdout()) - /// .output()?; - /// output.status.exit_ok()?; - /// assert!(output.stdout.is_empty()); - /// # Ok(()) - /// # } - /// # - /// # if cfg!(unix) { - /// # test().unwrap(); - /// # } - /// ``` - fn from(inherit: io::Stdout) -> Stdio { - Stdio::from_inner(inherit.into()) - } -} - -#[stable(feature = "stdio_from_stdio", since = "1.74.0")] -impl From for Stdio { - /// Redirect command stdout/stderr to our stderr - /// - /// # Examples - /// - /// ```rust - /// #![feature(exit_status_error)] - /// use std::io; - /// use std::process::Command; - /// - /// # fn test() -> Result<(), Box> { - /// let output = Command::new("whoami") - /// .stdout(io::stderr()) - /// .output()?; - /// output.status.exit_ok()?; - /// assert!(output.stdout.is_empty()); - /// # Ok(()) - /// # } - /// # - /// # if cfg!(unix) { - /// # test().unwrap(); - /// # } - /// ``` - fn from(inherit: io::Stderr) -> Stdio { - Stdio::from_inner(inherit.into()) - } -} - -/// Describes the result of a process after it has terminated. -/// -/// This `struct` is used to represent the exit status or other termination of a child process. -/// Child processes are created via the [`Command`] struct and their exit -/// status is exposed through the [`status`] method, or the [`wait`] method -/// of a [`Child`] process. -/// -/// An `ExitStatus` represents every possible disposition of a process. On Unix this -/// is the **wait status**. It is *not* simply an *exit status* (a value passed to `exit`). -/// -/// For proper error reporting of failed processes, print the value of `ExitStatus` or -/// `ExitStatusError` using their implementations of [`Display`](crate::fmt::Display). -/// -/// # Differences from `ExitCode` -/// -/// [`ExitCode`] is intended for terminating the currently running process, via -/// the `Termination` trait, in contrast to `ExitStatus`, which represents the -/// termination of a child process. These APIs are separate due to platform -/// compatibility differences and their expected usage; it is not generally -/// possible to exactly reproduce an `ExitStatus` from a child for the current -/// process after the fact. -/// -/// [`status`]: Command::status -/// [`wait`]: Child::wait -// -// We speak slightly loosely (here and in various other places in the stdlib docs) about `exit` -// vs `_exit`. Naming of Unix system calls is not standardised across Unices, so terminology is a -// matter of convention and tradition. For clarity we usually speak of `exit`, even when we might -// mean an underlying system call such as `_exit`. -#[derive(PartialEq, Eq, Clone, Copy, Debug)] -#[stable(feature = "process", since = "1.0.0")] -pub struct ExitStatus(imp::ExitStatus); - -/// The default value is one which indicates successful completion. -#[stable(feature = "process_exitstatus_default", since = "1.73.0")] -impl Default for ExitStatus { - fn default() -> Self { - // Ideally this would be done by ExitCode::default().into() but that is complicated. - ExitStatus::from_inner(imp::ExitStatus::default()) - } -} - -/// Allows extension traits within `std`. -#[unstable(feature = "sealed", issue = "none")] -impl crate::sealed::Sealed for ExitStatus {} - -impl ExitStatus { - /// Was termination successful? Returns a `Result`. - /// - /// # Examples - /// - /// ``` - /// #![feature(exit_status_error)] - /// # if cfg!(unix) { - /// use std::process::Command; - /// - /// let status = Command::new("ls") - /// .arg("/dev/nonexistent") - /// .status() - /// .expect("ls could not be executed"); - /// - /// println!("ls: {status}"); - /// status.exit_ok().expect_err("/dev/nonexistent could be listed!"); - /// # } // cfg!(unix) - /// ``` - #[unstable(feature = "exit_status_error", issue = "84908")] - pub fn exit_ok(&self) -> Result<(), ExitStatusError> { - self.0.exit_ok().map_err(ExitStatusError) - } - - /// Was termination successful? Signal termination is not considered a - /// success, and success is defined as a zero exit status. - /// - /// # Examples - /// - /// ```rust,no_run - /// use std::process::Command; - /// - /// let status = Command::new("mkdir") - /// .arg("projects") - /// .status() - /// .expect("failed to execute mkdir"); - /// - /// if status.success() { - /// println!("'projects/' directory created"); - /// } else { - /// println!("failed to create 'projects/' directory: {status}"); - /// } - /// ``` - #[must_use] - #[stable(feature = "process", since = "1.0.0")] - pub fn success(&self) -> bool { - self.0.exit_ok().is_ok() - } - - /// Returns the exit code of the process, if any. - /// - /// In Unix terms the return value is the **exit status**: the value passed to `exit`, if the - /// process finished by calling `exit`. Note that on Unix the exit status is truncated to 8 - /// bits, and that values that didn't come from a program's call to `exit` may be invented by the - /// runtime system (often, for example, 255, 254, 127 or 126). - /// - /// On Unix, this will return `None` if the process was terminated by a signal. - /// [`ExitStatusExt`](crate::os::unix::process::ExitStatusExt) is an - /// extension trait for extracting any such signal, and other details, from the `ExitStatus`. - /// - /// # Examples - /// - /// ```no_run - /// use std::process::Command; - /// - /// let status = Command::new("mkdir") - /// .arg("projects") - /// .status() - /// .expect("failed to execute mkdir"); - /// - /// match status.code() { - /// Some(code) => println!("Exited with status code: {code}"), - /// None => println!("Process terminated by signal") - /// } - /// ``` - #[must_use] - #[stable(feature = "process", since = "1.0.0")] - pub fn code(&self) -> Option { - self.0.code() - } -} - -impl AsInner for ExitStatus { - #[inline] - fn as_inner(&self) -> &imp::ExitStatus { - &self.0 - } -} - -impl FromInner for ExitStatus { - fn from_inner(s: imp::ExitStatus) -> ExitStatus { - ExitStatus(s) - } -} - -#[stable(feature = "process", since = "1.0.0")] -impl fmt::Display for ExitStatus { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0.fmt(f) - } -} - -/// Allows extension traits within `std`. -#[unstable(feature = "sealed", issue = "none")] -impl crate::sealed::Sealed for ExitStatusError {} - -/// Describes the result of a process after it has failed -/// -/// Produced by the [`.exit_ok`](ExitStatus::exit_ok) method on [`ExitStatus`]. -/// -/// # Examples -/// -/// ``` -/// #![feature(exit_status_error)] -/// # if cfg!(unix) { -/// use std::process::{Command, ExitStatusError}; -/// -/// fn run(cmd: &str) -> Result<(),ExitStatusError> { -/// Command::new(cmd).status().unwrap().exit_ok()?; -/// Ok(()) -/// } -/// -/// run("true").unwrap(); -/// run("false").unwrap_err(); -/// # } // cfg!(unix) -/// ``` -#[derive(PartialEq, Eq, Clone, Copy, Debug)] -#[unstable(feature = "exit_status_error", issue = "84908")] -// The definition of imp::ExitStatusError should ideally be such that -// Result<(), imp::ExitStatusError> has an identical representation to imp::ExitStatus. -pub struct ExitStatusError(imp::ExitStatusError); - -#[unstable(feature = "exit_status_error", issue = "84908")] -impl ExitStatusError { - /// Reports the exit code, if applicable, from an `ExitStatusError`. - /// - /// In Unix terms the return value is the **exit status**: the value passed to `exit`, if the - /// process finished by calling `exit`. Note that on Unix the exit status is truncated to 8 - /// bits, and that values that didn't come from a program's call to `exit` may be invented by the - /// runtime system (often, for example, 255, 254, 127 or 126). - /// - /// On Unix, this will return `None` if the process was terminated by a signal. If you want to - /// handle such situations specially, consider using methods from - /// [`ExitStatusExt`](crate::os::unix::process::ExitStatusExt). - /// - /// If the process finished by calling `exit` with a nonzero value, this will return - /// that exit status. - /// - /// If the error was something else, it will return `None`. - /// - /// If the process exited successfully (ie, by calling `exit(0)`), there is no - /// `ExitStatusError`. So the return value from `ExitStatusError::code()` is always nonzero. - /// - /// # Examples - /// - /// ``` - /// #![feature(exit_status_error)] - /// # #[cfg(unix)] { - /// use std::process::Command; - /// - /// let bad = Command::new("false").status().unwrap().exit_ok().unwrap_err(); - /// assert_eq!(bad.code(), Some(1)); - /// # } // #[cfg(unix)] - /// ``` - #[must_use] - pub fn code(&self) -> Option { - self.code_nonzero().map(Into::into) - } - - /// Reports the exit code, if applicable, from an `ExitStatusError`, as a [`NonZero`]. - /// - /// This is exactly like [`code()`](Self::code), except that it returns a [NonZero]<[i32]>. - /// - /// Plain `code`, returning a plain integer, is provided because it is often more convenient. - /// The returned value from `code()` is indeed also nonzero; use `code_nonzero()` when you want - /// a type-level guarantee of nonzeroness. - /// - /// # Examples - /// - /// ``` - /// #![feature(exit_status_error)] - /// - /// # if cfg!(unix) { - /// use std::num::NonZero; - /// use std::process::Command; - /// - /// let bad = Command::new("false").status().unwrap().exit_ok().unwrap_err(); - /// assert_eq!(bad.code_nonzero().unwrap(), NonZero::new(1).unwrap()); - /// # } // cfg!(unix) - /// ``` - #[must_use] - pub fn code_nonzero(&self) -> Option> { - self.0.code() - } - - /// Converts an `ExitStatusError` (back) to an `ExitStatus`. - #[must_use] - pub fn into_status(&self) -> ExitStatus { - ExitStatus(self.0.into()) - } -} - -#[unstable(feature = "exit_status_error", issue = "84908")] -impl From for ExitStatus { - fn from(error: ExitStatusError) -> Self { - Self(error.0.into()) - } -} - -#[unstable(feature = "exit_status_error", issue = "84908")] -impl fmt::Display for ExitStatusError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "process exited unsuccessfully: {}", self.into_status()) - } -} - -#[unstable(feature = "exit_status_error", issue = "84908")] -impl crate::error::Error for ExitStatusError {} - -/// This type represents the status code the current process can return -/// to its parent under normal termination. -/// -/// `ExitCode` is intended to be consumed only by the standard library (via -/// [`Termination::report()`]), and intentionally does not provide accessors like -/// `PartialEq`, `Eq`, or `Hash`. Instead the standard library provides the -/// canonical `SUCCESS` and `FAILURE` exit codes as well as `From for -/// ExitCode` for constructing other arbitrary exit codes. -/// -/// # Portability -/// -/// Numeric values used in this type don't have portable meanings, and -/// different platforms may mask different amounts of them. -/// -/// For the platform's canonical successful and unsuccessful codes, see -/// the [`SUCCESS`] and [`FAILURE`] associated items. -/// -/// [`SUCCESS`]: ExitCode::SUCCESS -/// [`FAILURE`]: ExitCode::FAILURE -/// -/// # Differences from `ExitStatus` -/// -/// `ExitCode` is intended for terminating the currently running process, via -/// the `Termination` trait, in contrast to [`ExitStatus`], which represents the -/// termination of a child process. These APIs are separate due to platform -/// compatibility differences and their expected usage; it is not generally -/// possible to exactly reproduce an `ExitStatus` from a child for the current -/// process after the fact. -/// -/// # Examples -/// -/// `ExitCode` can be returned from the `main` function of a crate, as it implements -/// [`Termination`]: -/// -/// ``` -/// use std::process::ExitCode; -/// # fn check_foo() -> bool { true } -/// -/// fn main() -> ExitCode { -/// if !check_foo() { -/// return ExitCode::from(42); -/// } -/// -/// ExitCode::SUCCESS -/// } -/// ``` -#[derive(Clone, Copy, Debug)] -#[stable(feature = "process_exitcode", since = "1.61.0")] -pub struct ExitCode(imp::ExitCode); - -/// Allows extension traits within `std`. -#[unstable(feature = "sealed", issue = "none")] -impl crate::sealed::Sealed for ExitCode {} - -#[stable(feature = "process_exitcode", since = "1.61.0")] -impl ExitCode { - /// The canonical `ExitCode` for successful termination on this platform. - /// - /// Note that a `()`-returning `main` implicitly results in a successful - /// termination, so there's no need to return this from `main` unless - /// you're also returning other possible codes. - #[stable(feature = "process_exitcode", since = "1.61.0")] - pub const SUCCESS: ExitCode = ExitCode(imp::ExitCode::SUCCESS); - - /// The canonical `ExitCode` for unsuccessful termination on this platform. - /// - /// If you're only returning this and `SUCCESS` from `main`, consider - /// instead returning `Err(_)` and `Ok(())` respectively, which will - /// return the same codes (but will also `eprintln!` the error). - #[stable(feature = "process_exitcode", since = "1.61.0")] - pub const FAILURE: ExitCode = ExitCode(imp::ExitCode::FAILURE); - - /// Exit the current process with the given `ExitCode`. - /// - /// Note that this has the same caveats as [`process::exit()`][exit], namely that this function - /// terminates the process immediately, so no destructors on the current stack or any other - /// thread's stack will be run. If a clean shutdown is needed, it is recommended to simply - /// return this ExitCode from the `main` function, as demonstrated in the [type - /// documentation](#examples). - /// - /// # Differences from `process::exit()` - /// - /// `process::exit()` accepts any `i32` value as the exit code for the process; however, there - /// are platforms that only use a subset of that value (see [`process::exit` platform-specific - /// behavior][exit#platform-specific-behavior]). `ExitCode` exists because of this; only - /// `ExitCode`s that are supported by a majority of our platforms can be created, so those - /// problems don't exist (as much) with this method. - /// - /// # Examples - /// - /// ``` - /// #![feature(exitcode_exit_method)] - /// # use std::process::ExitCode; - /// # use std::fmt; - /// # enum UhOhError { GenericProblem, Specific, WithCode { exit_code: ExitCode, _x: () } } - /// # impl fmt::Display for UhOhError { - /// # fn fmt(&self, _: &mut fmt::Formatter<'_>) -> fmt::Result { unimplemented!() } - /// # } - /// // there's no way to gracefully recover from an UhOhError, so we just - /// // print a message and exit - /// fn handle_unrecoverable_error(err: UhOhError) -> ! { - /// eprintln!("UH OH! {err}"); - /// let code = match err { - /// UhOhError::GenericProblem => ExitCode::FAILURE, - /// UhOhError::Specific => ExitCode::from(3), - /// UhOhError::WithCode { exit_code, .. } => exit_code, - /// }; - /// code.exit_process() - /// } - /// ``` - #[unstable(feature = "exitcode_exit_method", issue = "97100")] - pub fn exit_process(self) -> ! { - exit(self.to_i32()) - } -} - -impl ExitCode { - // This is private/perma-unstable because ExitCode is opaque; we don't know that i32 will serve - // all usecases, for example windows seems to use u32, unix uses the 8-15th bits of an i32, we - // likely want to isolate users anything that could restrict the platform specific - // representation of an ExitCode - // - // More info: https://internals.rust-lang.org/t/mini-pre-rfc-redesigning-process-exitstatus/5426 - /// Convert an `ExitCode` into an i32 - #[unstable( - feature = "process_exitcode_internals", - reason = "exposed only for libstd", - issue = "none" - )] - #[inline] - #[doc(hidden)] - pub fn to_i32(self) -> i32 { - self.0.as_i32() - } -} - -/// The default value is [`ExitCode::SUCCESS`] -#[stable(feature = "process_exitcode_default", since = "1.75.0")] -impl Default for ExitCode { - fn default() -> Self { - ExitCode::SUCCESS - } -} - -#[stable(feature = "process_exitcode", since = "1.61.0")] -impl From for ExitCode { - /// Construct an `ExitCode` from an arbitrary u8 value. - fn from(code: u8) -> Self { - ExitCode(imp::ExitCode::from(code)) - } -} - -impl AsInner for ExitCode { - #[inline] - fn as_inner(&self) -> &imp::ExitCode { - &self.0 - } -} - -impl FromInner for ExitCode { - fn from_inner(s: imp::ExitCode) -> ExitCode { - ExitCode(s) - } -} - -impl Child { - /// Forces the child process to exit. If the child has already exited, `Ok(())` - /// is returned. - /// - /// The mapping to [`ErrorKind`]s is not part of the compatibility contract of the function. - /// - /// This is equivalent to sending a SIGKILL on Unix platforms. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ```no_run - /// use std::process::Command; - /// - /// let mut command = Command::new("yes"); - /// if let Ok(mut child) = command.spawn() { - /// child.kill().expect("command couldn't be killed"); - /// } else { - /// println!("yes command didn't start"); - /// } - /// ``` - /// - /// [`ErrorKind`]: io::ErrorKind - /// [`InvalidInput`]: io::ErrorKind::InvalidInput - #[stable(feature = "process", since = "1.0.0")] - pub fn kill(&mut self) -> io::Result<()> { - self.handle.kill() - } - - /// Returns the OS-assigned process identifier associated with this child. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ```no_run - /// use std::process::Command; - /// - /// let mut command = Command::new("ls"); - /// if let Ok(child) = command.spawn() { - /// println!("Child's ID is {}", child.id()); - /// } else { - /// println!("ls command didn't start"); - /// } - /// ``` - #[must_use] - #[stable(feature = "process_id", since = "1.3.0")] - pub fn id(&self) -> u32 { - self.handle.id() - } - - /// Waits for the child to exit completely, returning the status that it - /// exited with. This function will continue to have the same return value - /// after it has been called at least once. - /// - /// The stdin handle to the child process, if any, will be closed - /// before waiting. This helps avoid deadlock: it ensures that the - /// child does not block waiting for input from the parent, while - /// the parent waits for the child to exit. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ```no_run - /// use std::process::Command; - /// - /// let mut command = Command::new("ls"); - /// if let Ok(mut child) = command.spawn() { - /// child.wait().expect("command wasn't running"); - /// println!("Child has finished its execution!"); - /// } else { - /// println!("ls command didn't start"); - /// } - /// ``` - #[stable(feature = "process", since = "1.0.0")] - pub fn wait(&mut self) -> io::Result { - drop(self.stdin.take()); - self.handle.wait().map(ExitStatus) - } - - /// Attempts to collect the exit status of the child if it has already - /// exited. - /// - /// This function will not block the calling thread and will only - /// check to see if the child process has exited or not. If the child has - /// exited then on Unix the process ID is reaped. This function is - /// guaranteed to repeatedly return a successful exit status so long as the - /// child has already exited. - /// - /// If the child has exited, then `Ok(Some(status))` is returned. If the - /// exit status is not available at this time then `Ok(None)` is returned. - /// If an error occurs, then that error is returned. - /// - /// Note that unlike `wait`, this function will not attempt to drop stdin. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ```no_run - /// use std::process::Command; - /// - /// let mut child = Command::new("ls").spawn().unwrap(); - /// - /// match child.try_wait() { - /// Ok(Some(status)) => println!("exited with: {status}"), - /// Ok(None) => { - /// println!("status not ready yet, let's really wait"); - /// let res = child.wait(); - /// println!("result: {res:?}"); - /// } - /// Err(e) => println!("error attempting to wait: {e}"), - /// } - /// ``` - #[stable(feature = "process_try_wait", since = "1.18.0")] - pub fn try_wait(&mut self) -> io::Result> { - Ok(self.handle.try_wait()?.map(ExitStatus)) - } - - /// Simultaneously waits for the child to exit and collect all remaining - /// output on the stdout/stderr handles, returning an `Output` - /// instance. - /// - /// The stdin handle to the child process, if any, will be closed - /// before waiting. This helps avoid deadlock: it ensures that the - /// child does not block waiting for input from the parent, while - /// the parent waits for the child to exit. - /// - /// By default, stdin, stdout and stderr are inherited from the parent. - /// In order to capture the output into this `Result` it is - /// necessary to create new pipes between parent and child. Use - /// `stdout(Stdio::piped())` or `stderr(Stdio::piped())`, respectively. - /// - /// # Examples - /// - /// ```should_panic - /// use std::process::{Command, Stdio}; - /// - /// let child = Command::new("/bin/cat") - /// .arg("file.txt") - /// .stdout(Stdio::piped()) - /// .spawn() - /// .expect("failed to execute child"); - /// - /// let output = child - /// .wait_with_output() - /// .expect("failed to wait on child"); - /// - /// assert!(output.status.success()); - /// ``` - /// - #[stable(feature = "process", since = "1.0.0")] - pub fn wait_with_output(mut self) -> io::Result { - drop(self.stdin.take()); - - let (mut stdout, mut stderr) = (Vec::new(), Vec::new()); - match (self.stdout.take(), self.stderr.take()) { - (None, None) => {} - (Some(mut out), None) => { - let res = out.read_to_end(&mut stdout); - res.unwrap(); - } - (None, Some(mut err)) => { - let res = err.read_to_end(&mut stderr); - res.unwrap(); - } - (Some(out), Some(err)) => { - let res = read2(out.inner, &mut stdout, err.inner, &mut stderr); - res.unwrap(); - } - } - - let status = self.wait()?; - Ok(Output { status, stdout, stderr }) - } -} - -/// Terminates the current process with the specified exit code. -/// -/// This function will never return and will immediately terminate the current -/// process. The exit code is passed through to the underlying OS and will be -/// available for consumption by another process. -/// -/// Note that because this function never returns, and that it terminates the -/// process, no destructors on the current stack or any other thread's stack -/// will be run. If a clean shutdown is needed it is recommended to only call -/// this function at a known point where there are no more destructors left -/// to run; or, preferably, simply return a type implementing [`Termination`] -/// (such as [`ExitCode`] or `Result`) from the `main` function and avoid this -/// function altogether: -/// -/// ``` -/// # use std::io::Error as MyError; -/// fn main() -> Result<(), MyError> { -/// // ... -/// Ok(()) -/// } -/// ``` -/// -/// ## Platform-specific behavior -/// -/// **Unix**: On Unix-like platforms, it is unlikely that all 32 bits of `exit` -/// will be visible to a parent process inspecting the exit code. On most -/// Unix-like platforms, only the eight least-significant bits are considered. -/// -/// For example, the exit code for this example will be `0` on Linux, but `256` -/// on Windows: -/// -/// ```no_run -/// use std::process; -/// -/// process::exit(0x0100); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "process_exit")] -pub fn exit(code: i32) -> ! { - crate::rt::cleanup(); - crate::sys::os::exit(code) -} - -/// Terminates the process in an abnormal fashion. -/// -/// The function will never return and will immediately terminate the current -/// process in a platform specific "abnormal" manner. -/// -/// Note that because this function never returns, and that it terminates the -/// process, no destructors on the current stack or any other thread's stack -/// will be run. -/// -/// Rust IO buffers (eg, from `BufWriter`) will not be flushed. -/// Likewise, C stdio buffers will (on most platforms) not be flushed. -/// -/// This is in contrast to the default behaviour of [`panic!`] which unwinds -/// the current thread's stack and calls all destructors. -/// When `panic="abort"` is set, either as an argument to `rustc` or in a -/// crate's Cargo.toml, [`panic!`] and `abort` are similar. However, -/// [`panic!`] will still call the [panic hook] while `abort` will not. -/// -/// If a clean shutdown is needed it is recommended to only call -/// this function at a known point where there are no more destructors left -/// to run. -/// -/// The process's termination will be similar to that from the C `abort()` -/// function. On Unix, the process will terminate with signal `SIGABRT`, which -/// typically means that the shell prints "Aborted". -/// -/// # Examples -/// -/// ```no_run -/// use std::process; -/// -/// fn main() { -/// println!("aborting"); -/// -/// process::abort(); -/// -/// // execution never gets here -/// } -/// ``` -/// -/// The `abort` function terminates the process, so the destructor will not -/// get run on the example below: -/// -/// ```no_run -/// use std::process; -/// -/// struct HasDrop; -/// -/// impl Drop for HasDrop { -/// fn drop(&mut self) { -/// println!("This will never be printed!"); -/// } -/// } -/// -/// fn main() { -/// let _x = HasDrop; -/// process::abort(); -/// // the destructor implemented for HasDrop will never get run -/// } -/// ``` -/// -/// [panic hook]: crate::panic::set_hook -#[stable(feature = "process_abort", since = "1.17.0")] -#[cold] -pub fn abort() -> ! { - crate::sys::abort_internal(); -} - -/// Returns the OS-assigned process identifier associated with this process. -/// -/// # Examples -/// -/// Basic usage: -/// -/// ```no_run -/// use std::process; -/// -/// println!("My pid is {}", process::id()); -/// ``` -/// -/// -#[must_use] -#[stable(feature = "getpid", since = "1.26.0")] -pub fn id() -> u32 { - crate::sys::os::getpid() -} - -/// A trait for implementing arbitrary return types in the `main` function. -/// -/// The C-main function only supports returning integers. -/// So, every type implementing the `Termination` trait has to be converted -/// to an integer. -/// -/// The default implementations are returning `libc::EXIT_SUCCESS` to indicate -/// a successful execution. In case of a failure, `libc::EXIT_FAILURE` is returned. -/// -/// Because different runtimes have different specifications on the return value -/// of the `main` function, this trait is likely to be available only on -/// standard library's runtime for convenience. Other runtimes are not required -/// to provide similar functionality. -#[cfg_attr(not(any(test, doctest)), lang = "termination")] -#[stable(feature = "termination_trait_lib", since = "1.61.0")] -#[rustc_on_unimplemented(on( - cause = "MainFunctionType", - message = "`main` has invalid return type `{Self}`", - label = "`main` can only return types that implement `{Termination}`" -))] -pub trait Termination { - /// Is called to get the representation of the value as status code. - /// This status code is returned to the operating system. - #[stable(feature = "termination_trait_lib", since = "1.61.0")] - fn report(self) -> ExitCode; -} - -#[stable(feature = "termination_trait_lib", since = "1.61.0")] -impl Termination for () { - #[inline] - fn report(self) -> ExitCode { - ExitCode::SUCCESS - } -} - -#[stable(feature = "termination_trait_lib", since = "1.61.0")] -impl Termination for ! { - fn report(self) -> ExitCode { - self - } -} - -#[stable(feature = "termination_trait_lib", since = "1.61.0")] -impl Termination for Infallible { - fn report(self) -> ExitCode { - match self {} - } -} - -#[stable(feature = "termination_trait_lib", since = "1.61.0")] -impl Termination for ExitCode { - #[inline] - fn report(self) -> ExitCode { - self - } -} - -#[stable(feature = "termination_trait_lib", since = "1.61.0")] -impl Termination for Result { - fn report(self) -> ExitCode { - match self { - Ok(val) => val.report(), - Err(err) => { - io::attempt_print_to_stderr(format_args_nl!("Error: {err:?}")); - ExitCode::FAILURE - } - } - } -} diff --git a/library/std/src/process/tests.rs b/library/std/src/process/tests.rs deleted file mode 100644 index 07d4de5c1a26e..0000000000000 --- a/library/std/src/process/tests.rs +++ /dev/null @@ -1,729 +0,0 @@ -use crate::io::prelude::*; - -use super::{Command, Output, Stdio}; -use crate::io::{BorrowedBuf, ErrorKind}; -use crate::mem::MaybeUninit; -use crate::str; - -fn known_command() -> Command { - if cfg!(windows) { Command::new("help") } else { Command::new("echo") } -} - -#[cfg(target_os = "android")] -fn shell_cmd() -> Command { - Command::new("/system/bin/sh") -} - -#[cfg(not(target_os = "android"))] -fn shell_cmd() -> Command { - Command::new("/bin/sh") -} - -#[test] -#[cfg_attr(any(target_os = "vxworks"), ignore)] -fn smoke() { - let p = if cfg!(target_os = "windows") { - Command::new("cmd").args(&["/C", "exit 0"]).spawn() - } else { - shell_cmd().arg("-c").arg("true").spawn() - }; - assert!(p.is_ok()); - let mut p = p.unwrap(); - assert!(p.wait().unwrap().success()); -} - -#[test] -#[cfg_attr(target_os = "android", ignore)] -fn smoke_failure() { - match Command::new("if-this-is-a-binary-then-the-world-has-ended").spawn() { - Ok(..) => panic!(), - Err(..) => {} - } -} - -#[test] -#[cfg_attr(any(target_os = "vxworks"), ignore)] -fn exit_reported_right() { - let p = if cfg!(target_os = "windows") { - Command::new("cmd").args(&["/C", "exit 1"]).spawn() - } else { - shell_cmd().arg("-c").arg("false").spawn() - }; - assert!(p.is_ok()); - let mut p = p.unwrap(); - assert!(p.wait().unwrap().code() == Some(1)); - drop(p.wait()); -} - -#[test] -#[cfg(unix)] -#[cfg_attr(any(target_os = "vxworks"), ignore)] -fn signal_reported_right() { - use crate::os::unix::process::ExitStatusExt; - - let mut p = shell_cmd().arg("-c").arg("read a").stdin(Stdio::piped()).spawn().unwrap(); - p.kill().unwrap(); - match p.wait().unwrap().signal() { - Some(9) => {} - result => panic!("not terminated by signal 9 (instead, {result:?})"), - } -} - -pub fn run_output(mut cmd: Command) -> String { - let p = cmd.spawn(); - assert!(p.is_ok()); - let mut p = p.unwrap(); - assert!(p.stdout.is_some()); - let mut ret = String::new(); - p.stdout.as_mut().unwrap().read_to_string(&mut ret).unwrap(); - assert!(p.wait().unwrap().success()); - return ret; -} - -#[test] -#[cfg_attr(any(target_os = "vxworks"), ignore)] -fn stdout_works() { - if cfg!(target_os = "windows") { - let mut cmd = Command::new("cmd"); - cmd.args(&["/C", "echo foobar"]).stdout(Stdio::piped()); - assert_eq!(run_output(cmd), "foobar\r\n"); - } else { - let mut cmd = shell_cmd(); - cmd.arg("-c").arg("echo foobar").stdout(Stdio::piped()); - assert_eq!(run_output(cmd), "foobar\n"); - } -} - -#[test] -#[cfg_attr(any(windows, target_os = "vxworks"), ignore)] -fn set_current_dir_works() { - let mut cmd = shell_cmd(); - cmd.arg("-c").arg("pwd").current_dir("/").stdout(Stdio::piped()); - assert_eq!(run_output(cmd), "/\n"); -} - -#[test] -#[cfg_attr(any(windows, target_os = "vxworks"), ignore)] -fn stdin_works() { - let mut p = shell_cmd() - .arg("-c") - .arg("read line; echo $line") - .stdin(Stdio::piped()) - .stdout(Stdio::piped()) - .spawn() - .unwrap(); - p.stdin.as_mut().unwrap().write("foobar".as_bytes()).unwrap(); - drop(p.stdin.take()); - let mut out = String::new(); - p.stdout.as_mut().unwrap().read_to_string(&mut out).unwrap(); - assert!(p.wait().unwrap().success()); - assert_eq!(out, "foobar\n"); -} - -#[test] -#[cfg_attr(any(target_os = "vxworks"), ignore)] -fn child_stdout_read_buf() { - let mut cmd = if cfg!(target_os = "windows") { - let mut cmd = Command::new("cmd"); - cmd.arg("/C").arg("echo abc"); - cmd - } else { - let mut cmd = shell_cmd(); - cmd.arg("-c").arg("echo abc"); - cmd - }; - cmd.stdin(Stdio::null()); - cmd.stdout(Stdio::piped()); - let child = cmd.spawn().unwrap(); - - let mut stdout = child.stdout.unwrap(); - let mut buf: [MaybeUninit; 128] = MaybeUninit::uninit_array(); - let mut buf = BorrowedBuf::from(buf.as_mut_slice()); - stdout.read_buf(buf.unfilled()).unwrap(); - - // ChildStdout::read_buf should omit buffer initialization. - if cfg!(target_os = "windows") { - assert_eq!(buf.filled(), b"abc\r\n"); - assert_eq!(buf.init_len(), 5); - } else { - assert_eq!(buf.filled(), b"abc\n"); - assert_eq!(buf.init_len(), 4); - }; -} - -#[test] -#[cfg_attr(any(target_os = "vxworks"), ignore)] -fn test_process_status() { - let mut status = if cfg!(target_os = "windows") { - Command::new("cmd").args(&["/C", "exit 1"]).status().unwrap() - } else { - shell_cmd().arg("-c").arg("false").status().unwrap() - }; - assert!(status.code() == Some(1)); - - status = if cfg!(target_os = "windows") { - Command::new("cmd").args(&["/C", "exit 0"]).status().unwrap() - } else { - shell_cmd().arg("-c").arg("true").status().unwrap() - }; - assert!(status.success()); -} - -#[test] -fn test_process_output_fail_to_start() { - match Command::new("/no-binary-by-this-name-should-exist").output() { - Err(e) => assert_eq!(e.kind(), ErrorKind::NotFound), - Ok(..) => panic!(), - } -} - -#[test] -#[cfg_attr(any(target_os = "vxworks"), ignore)] -fn test_process_output_output() { - let Output { status, stdout, stderr } = if cfg!(target_os = "windows") { - Command::new("cmd").args(&["/C", "echo hello"]).output().unwrap() - } else { - shell_cmd().arg("-c").arg("echo hello").output().unwrap() - }; - let output_str = str::from_utf8(&stdout).unwrap(); - - assert!(status.success()); - assert_eq!(output_str.trim().to_string(), "hello"); - assert_eq!(stderr, Vec::new()); -} - -#[test] -#[cfg_attr(any(target_os = "vxworks"), ignore)] -fn test_process_output_error() { - let Output { status, stdout, stderr } = if cfg!(target_os = "windows") { - Command::new("cmd").args(&["/C", "mkdir ."]).output().unwrap() - } else { - Command::new("mkdir").arg("./").output().unwrap() - }; - - assert!(status.code().is_some()); - assert!(status.code() != Some(0)); - assert_eq!(stdout, Vec::new()); - assert!(!stderr.is_empty()); -} - -#[test] -#[cfg_attr(any(target_os = "vxworks"), ignore)] -fn test_finish_once() { - let mut prog = if cfg!(target_os = "windows") { - Command::new("cmd").args(&["/C", "exit 1"]).spawn().unwrap() - } else { - shell_cmd().arg("-c").arg("false").spawn().unwrap() - }; - assert!(prog.wait().unwrap().code() == Some(1)); -} - -#[test] -#[cfg_attr(any(target_os = "vxworks"), ignore)] -fn test_finish_twice() { - let mut prog = if cfg!(target_os = "windows") { - Command::new("cmd").args(&["/C", "exit 1"]).spawn().unwrap() - } else { - shell_cmd().arg("-c").arg("false").spawn().unwrap() - }; - assert!(prog.wait().unwrap().code() == Some(1)); - assert!(prog.wait().unwrap().code() == Some(1)); -} - -#[test] -#[cfg_attr(any(target_os = "vxworks"), ignore)] -fn test_wait_with_output_once() { - let prog = if cfg!(target_os = "windows") { - Command::new("cmd").args(&["/C", "echo hello"]).stdout(Stdio::piped()).spawn().unwrap() - } else { - shell_cmd().arg("-c").arg("echo hello").stdout(Stdio::piped()).spawn().unwrap() - }; - - let Output { status, stdout, stderr } = prog.wait_with_output().unwrap(); - let output_str = str::from_utf8(&stdout).unwrap(); - - assert!(status.success()); - assert_eq!(output_str.trim().to_string(), "hello"); - assert_eq!(stderr, Vec::new()); -} - -#[cfg(all(unix, not(target_os = "android")))] -pub fn env_cmd() -> Command { - Command::new("env") -} -#[cfg(target_os = "android")] -pub fn env_cmd() -> Command { - let mut cmd = Command::new("/system/bin/sh"); - cmd.arg("-c").arg("set"); - cmd -} - -#[cfg(windows)] -pub fn env_cmd() -> Command { - let mut cmd = Command::new("cmd"); - cmd.arg("/c").arg("set"); - cmd -} - -#[test] -#[cfg_attr(target_os = "vxworks", ignore)] -fn test_override_env() { - use crate::env; - - // In some build environments (such as chrooted Nix builds), `env` can - // only be found in the explicitly-provided PATH env variable, not in - // default places such as /bin or /usr/bin. So we need to pass through - // PATH to our sub-process. - let mut cmd = env_cmd(); - cmd.env_clear().env("RUN_TEST_NEW_ENV", "123"); - if let Some(p) = env::var_os("PATH") { - cmd.env("PATH", &p); - } - let result = cmd.output().unwrap(); - let output = String::from_utf8_lossy(&result.stdout).to_string(); - - assert!( - output.contains("RUN_TEST_NEW_ENV=123"), - "didn't find RUN_TEST_NEW_ENV inside of:\n\n{output}", - ); -} - -#[test] -#[cfg_attr(target_os = "vxworks", ignore)] -fn test_add_to_env() { - let result = env_cmd().env("RUN_TEST_NEW_ENV", "123").output().unwrap(); - let output = String::from_utf8_lossy(&result.stdout).to_string(); - - assert!( - output.contains("RUN_TEST_NEW_ENV=123"), - "didn't find RUN_TEST_NEW_ENV inside of:\n\n{output}" - ); -} - -#[test] -#[cfg_attr(target_os = "vxworks", ignore)] -fn test_capture_env_at_spawn() { - use crate::env; - - let mut cmd = env_cmd(); - cmd.env("RUN_TEST_NEW_ENV1", "123"); - - // This variable will not be present if the environment has already - // been captured above. - env::set_var("RUN_TEST_NEW_ENV2", "456"); - let result = cmd.output().unwrap(); - env::remove_var("RUN_TEST_NEW_ENV2"); - - let output = String::from_utf8_lossy(&result.stdout).to_string(); - - assert!( - output.contains("RUN_TEST_NEW_ENV1=123"), - "didn't find RUN_TEST_NEW_ENV1 inside of:\n\n{output}" - ); - assert!( - output.contains("RUN_TEST_NEW_ENV2=456"), - "didn't find RUN_TEST_NEW_ENV2 inside of:\n\n{output}" - ); -} - -// Regression tests for #30858. -#[test] -fn test_interior_nul_in_progname_is_error() { - match Command::new("has-some-\0\0s-inside").spawn() { - Err(e) => assert_eq!(e.kind(), ErrorKind::InvalidInput), - Ok(_) => panic!(), - } -} - -#[test] -fn test_interior_nul_in_arg_is_error() { - match known_command().arg("has-some-\0\0s-inside").spawn() { - Err(e) => assert_eq!(e.kind(), ErrorKind::InvalidInput), - Ok(_) => panic!(), - } -} - -#[test] -fn test_interior_nul_in_args_is_error() { - match known_command().args(&["has-some-\0\0s-inside"]).spawn() { - Err(e) => assert_eq!(e.kind(), ErrorKind::InvalidInput), - Ok(_) => panic!(), - } -} - -#[test] -fn test_interior_nul_in_current_dir_is_error() { - match known_command().current_dir("has-some-\0\0s-inside").spawn() { - Err(e) => assert_eq!(e.kind(), ErrorKind::InvalidInput), - Ok(_) => panic!(), - } -} - -// Regression tests for #30862. -#[test] -#[cfg_attr(target_os = "vxworks", ignore)] -fn test_interior_nul_in_env_key_is_error() { - match env_cmd().env("has-some-\0\0s-inside", "value").spawn() { - Err(e) => assert_eq!(e.kind(), ErrorKind::InvalidInput), - Ok(_) => panic!(), - } -} - -#[test] -#[cfg_attr(target_os = "vxworks", ignore)] -fn test_interior_nul_in_env_value_is_error() { - match env_cmd().env("key", "has-some-\0\0s-inside").spawn() { - Err(e) => assert_eq!(e.kind(), ErrorKind::InvalidInput), - Ok(_) => panic!(), - } -} - -/// Tests that process creation flags work by debugging a process. -/// Other creation flags make it hard or impossible to detect -/// behavioral changes in the process. -#[test] -#[cfg(windows)] -fn test_creation_flags() { - use crate::os::windows::process::CommandExt; - use crate::sys::c::{BOOL, DWORD, INFINITE}; - #[repr(C, packed)] - struct DEBUG_EVENT { - pub event_code: DWORD, - pub process_id: DWORD, - pub thread_id: DWORD, - // This is a union in the real struct, but we don't - // need this data for the purposes of this test. - pub _junk: [u8; 164], - } - - extern "system" { - fn WaitForDebugEvent(lpDebugEvent: *mut DEBUG_EVENT, dwMilliseconds: DWORD) -> BOOL; - fn ContinueDebugEvent( - dwProcessId: DWORD, - dwThreadId: DWORD, - dwContinueStatus: DWORD, - ) -> BOOL; - } - - const DEBUG_PROCESS: DWORD = 1; - const EXIT_PROCESS_DEBUG_EVENT: DWORD = 5; - const DBG_EXCEPTION_NOT_HANDLED: DWORD = 0x80010001; - - let mut child = - Command::new("cmd").creation_flags(DEBUG_PROCESS).stdin(Stdio::piped()).spawn().unwrap(); - child.stdin.take().unwrap().write_all(b"exit\r\n").unwrap(); - let mut events = 0; - let mut event = DEBUG_EVENT { event_code: 0, process_id: 0, thread_id: 0, _junk: [0; 164] }; - loop { - if unsafe { WaitForDebugEvent(&mut event as *mut DEBUG_EVENT, INFINITE) } == 0 { - panic!("WaitForDebugEvent failed!"); - } - events += 1; - - if event.event_code == EXIT_PROCESS_DEBUG_EVENT { - break; - } - - if unsafe { - ContinueDebugEvent(event.process_id, event.thread_id, DBG_EXCEPTION_NOT_HANDLED) - } == 0 - { - panic!("ContinueDebugEvent failed!"); - } - } - assert!(events > 0); -} - -/// Tests proc thread attributes by spawning a process with a custom parent process, -/// then comparing the parent process ID with the expected parent process ID. -#[test] -#[cfg(windows)] -fn test_proc_thread_attributes() { - use crate::mem; - use crate::os::windows::io::AsRawHandle; - use crate::os::windows::process::CommandExt; - use crate::sys::c::{CloseHandle, BOOL, HANDLE}; - use crate::sys::cvt; - - #[repr(C)] - #[allow(non_snake_case)] - struct PROCESSENTRY32W { - dwSize: u32, - cntUsage: u32, - th32ProcessID: u32, - th32DefaultHeapID: usize, - th32ModuleID: u32, - cntThreads: u32, - th32ParentProcessID: u32, - pcPriClassBase: i32, - dwFlags: u32, - szExeFile: [u16; 260], - } - - extern "system" { - fn CreateToolhelp32Snapshot(dwflags: u32, th32processid: u32) -> HANDLE; - fn Process32First(hsnapshot: HANDLE, lppe: *mut PROCESSENTRY32W) -> BOOL; - fn Process32Next(hsnapshot: HANDLE, lppe: *mut PROCESSENTRY32W) -> BOOL; - } - - const PROC_THREAD_ATTRIBUTE_PARENT_PROCESS: usize = 0x00020000; - const TH32CS_SNAPPROCESS: u32 = 0x00000002; - - struct ProcessDropGuard(crate::process::Child); - - impl Drop for ProcessDropGuard { - fn drop(&mut self) { - let _ = self.0.kill(); - } - } - - let parent = ProcessDropGuard(Command::new("cmd").spawn().unwrap()); - - let mut child_cmd = Command::new("cmd"); - - unsafe { - child_cmd - .raw_attribute(PROC_THREAD_ATTRIBUTE_PARENT_PROCESS, parent.0.as_raw_handle() as isize); - } - - let child = ProcessDropGuard(child_cmd.spawn().unwrap()); - - let h_snapshot = unsafe { CreateToolhelp32Snapshot(TH32CS_SNAPPROCESS, 0) }; - - let mut process_entry = PROCESSENTRY32W { - dwSize: mem::size_of::() as u32, - cntUsage: 0, - th32ProcessID: 0, - th32DefaultHeapID: 0, - th32ModuleID: 0, - cntThreads: 0, - th32ParentProcessID: 0, - pcPriClassBase: 0, - dwFlags: 0, - szExeFile: [0; 260], - }; - - unsafe { cvt(Process32First(h_snapshot, &mut process_entry as *mut _)) }.unwrap(); - - loop { - if child.0.id() == process_entry.th32ProcessID { - break; - } - unsafe { cvt(Process32Next(h_snapshot, &mut process_entry as *mut _)) }.unwrap(); - } - - unsafe { cvt(CloseHandle(h_snapshot)) }.unwrap(); - - assert_eq!(parent.0.id(), process_entry.th32ParentProcessID); - - drop(child) -} - -#[test] -fn test_command_implements_send_sync() { - fn take_send_sync_type(_: T) {} - take_send_sync_type(Command::new("")) -} - -// Ensure that starting a process with no environment variables works on Windows. -// This will fail if the environment block is ill-formed. -#[test] -#[cfg(windows)] -fn env_empty() { - let p = Command::new("cmd").args(&["/C", "exit 0"]).env_clear().spawn(); - assert!(p.is_ok()); -} - -#[test] -#[cfg(not(windows))] -#[cfg_attr(any(target_os = "emscripten", target_env = "sgx"), ignore)] -fn debug_print() { - const PIDFD: &'static str = - if cfg!(target_os = "linux") { " create_pidfd: false,\n" } else { "" }; - - let mut command = Command::new("some-boring-name"); - - assert_eq!(format!("{command:?}"), format!(r#""some-boring-name""#)); - - assert_eq!( - format!("{command:#?}"), - format!( - r#"Command {{ - program: "some-boring-name", - args: [ - "some-boring-name", - ], -{PIDFD}}}"# - ) - ); - - command.args(&["1", "2", "3"]); - - assert_eq!(format!("{command:?}"), format!(r#""some-boring-name" "1" "2" "3""#)); - - assert_eq!( - format!("{command:#?}"), - format!( - r#"Command {{ - program: "some-boring-name", - args: [ - "some-boring-name", - "1", - "2", - "3", - ], -{PIDFD}}}"# - ) - ); - - crate::os::unix::process::CommandExt::arg0(&mut command, "exciting-name"); - - assert_eq!( - format!("{command:?}"), - format!(r#"["some-boring-name"] "exciting-name" "1" "2" "3""#) - ); - - assert_eq!( - format!("{command:#?}"), - format!( - r#"Command {{ - program: "some-boring-name", - args: [ - "exciting-name", - "1", - "2", - "3", - ], -{PIDFD}}}"# - ) - ); - - let mut command_with_env_and_cwd = Command::new("boring-name"); - command_with_env_and_cwd.current_dir("/some/path").env("FOO", "bar"); - assert_eq!( - format!("{command_with_env_and_cwd:?}"), - r#"cd "/some/path" && FOO="bar" "boring-name""# - ); - assert_eq!( - format!("{command_with_env_and_cwd:#?}"), - format!( - r#"Command {{ - program: "boring-name", - args: [ - "boring-name", - ], - env: CommandEnv {{ - clear: false, - vars: {{ - "FOO": Some( - "bar", - ), - }}, - }}, - cwd: Some( - "/some/path", - ), -{PIDFD}}}"# - ) - ); - - let mut command_with_removed_env = Command::new("boring-name"); - command_with_removed_env.env_remove("FOO").env_remove("BAR"); - assert_eq!(format!("{command_with_removed_env:?}"), r#"env -u BAR -u FOO "boring-name""#); - assert_eq!( - format!("{command_with_removed_env:#?}"), - format!( - r#"Command {{ - program: "boring-name", - args: [ - "boring-name", - ], - env: CommandEnv {{ - clear: false, - vars: {{ - "BAR": None, - "FOO": None, - }}, - }}, -{PIDFD}}}"# - ) - ); - - let mut command_with_cleared_env = Command::new("boring-name"); - command_with_cleared_env.env_clear().env("BAR", "val").env_remove("FOO"); - assert_eq!(format!("{command_with_cleared_env:?}"), r#"env -i BAR="val" "boring-name""#); - assert_eq!( - format!("{command_with_cleared_env:#?}"), - format!( - r#"Command {{ - program: "boring-name", - args: [ - "boring-name", - ], - env: CommandEnv {{ - clear: true, - vars: {{ - "BAR": Some( - "val", - ), - }}, - }}, -{PIDFD}}}"# - ) - ); -} - -// See issue #91991 -#[test] -#[cfg(windows)] -fn run_bat_script() { - let tempdir = crate::sys_common::io::test::tmpdir(); - let script_path = tempdir.join("hello.cmd"); - - crate::fs::write(&script_path, "@echo Hello, %~1!").unwrap(); - let output = Command::new(&script_path) - .arg("fellow Rustaceans") - .stdout(crate::process::Stdio::piped()) - .spawn() - .unwrap() - .wait_with_output() - .unwrap(); - assert!(output.status.success()); - assert_eq!(String::from_utf8_lossy(&output.stdout).trim(), "Hello, fellow Rustaceans!"); -} - -// See issue #95178 -#[test] -#[cfg(windows)] -fn run_canonical_bat_script() { - let tempdir = crate::sys_common::io::test::tmpdir(); - let script_path = tempdir.join("hello.cmd"); - - crate::fs::write(&script_path, "@echo Hello, %~1!").unwrap(); - - // Try using a canonical path - let output = Command::new(&script_path.canonicalize().unwrap()) - .arg("fellow Rustaceans") - .stdout(crate::process::Stdio::piped()) - .spawn() - .unwrap() - .wait_with_output() - .unwrap(); - assert!(output.status.success()); - assert_eq!(String::from_utf8_lossy(&output.stdout).trim(), "Hello, fellow Rustaceans!"); -} - -#[test] -fn terminate_exited_process() { - let mut cmd = if cfg!(target_os = "android") { - let mut p = shell_cmd(); - p.args(&["-c", "true"]); - p - } else { - known_command() - }; - let mut p = cmd.stdout(Stdio::null()).spawn().unwrap(); - p.wait().unwrap(); - assert!(p.kill().is_ok()); - assert!(p.kill().is_ok()); -} diff --git a/library/std/src/rt.rs b/library/std/src/rt.rs deleted file mode 100644 index 46f691d7b7504..0000000000000 --- a/library/std/src/rt.rs +++ /dev/null @@ -1,165 +0,0 @@ -//! Runtime services -//! -//! The `rt` module provides a narrow set of runtime services, -//! including the global heap (exported in `heap`) and unwinding and -//! backtrace support. The APIs in this module are highly unstable, -//! and should be considered as private implementation details for the -//! time being. - -#![unstable( - feature = "rt", - reason = "this public module should not exist and is highly likely \ - to disappear", - issue = "none" -)] -#![doc(hidden)] -#![deny(unsafe_op_in_unsafe_fn)] -#![allow(unused_macros)] - -// Re-export some of our utilities which are expected by other crates. -pub use crate::panicking::{begin_panic, panic_count}; -pub use core::panicking::{panic_display, panic_fmt}; - -use crate::sync::Once; -use crate::sys; -use crate::thread::{self, Thread}; - -// Prints to the "panic output", depending on the platform this may be: -// - the standard error output -// - some dedicated platform specific output -// - nothing (so this macro is a no-op) -macro_rules! rtprintpanic { - ($($t:tt)*) => { - if let Some(mut out) = crate::sys::stdio::panic_output() { - let _ = crate::io::Write::write_fmt(&mut out, format_args!($($t)*)); - } - } -} - -macro_rules! rtabort { - ($($t:tt)*) => { - { - rtprintpanic!("fatal runtime error: {}\n", format_args!($($t)*)); - crate::sys::abort_internal(); - } - } -} - -macro_rules! rtassert { - ($e:expr) => { - if !$e { - rtabort!(concat!("assertion failed: ", stringify!($e))); - } - }; -} - -macro_rules! rtunwrap { - ($ok:ident, $e:expr) => { - match $e { - $ok(v) => v, - ref err => { - let err = err.as_ref().map(drop); // map Ok/Some which might not be Debug - rtabort!(concat!("unwrap failed: ", stringify!($e), " = {:?}"), err) - } - } - }; -} - -// One-time runtime initialization. -// Runs before `main`. -// SAFETY: must be called only once during runtime initialization. -// NOTE: this is not guaranteed to run, for example when Rust code is called externally. -// -// # The `sigpipe` parameter -// -// Since 2014, the Rust runtime on Unix has set the `SIGPIPE` handler to -// `SIG_IGN`. Applications have good reasons to want a different behavior -// though, so there is a `-Zon-broken-pipe` compiler flag that -// can be used to select how `SIGPIPE` shall be setup (if changed at all) before -// `fn main()` is called. See -// for more info. -// -// The `sigpipe` parameter to this function gets its value via the code that -// rustc generates to invoke `fn lang_start()`. The reason we have `sigpipe` for -// all platforms and not only Unix, is because std is not allowed to have `cfg` -// directives as this high level. See the module docs in -// `src/tools/tidy/src/pal.rs` for more info. On all other platforms, `sigpipe` -// has a value, but its value is ignored. -// -// Even though it is an `u8`, it only ever has 4 values. These are documented in -// `compiler/rustc_session/src/config/sigpipe.rs`. -#[cfg_attr(test, allow(dead_code))] -unsafe fn init(argc: isize, argv: *const *const u8, sigpipe: u8) { - unsafe { - sys::init(argc, argv, sigpipe); - - // Set up the current thread to give it the right name. - let thread = Thread::new_main(); - thread::set_current(thread); - } -} - -// One-time runtime cleanup. -// Runs after `main` or at program exit. -// NOTE: this is not guaranteed to run, for example when the program aborts. -pub(crate) fn cleanup() { - static CLEANUP: Once = Once::new(); - CLEANUP.call_once(|| unsafe { - // Flush stdout and disable buffering. - crate::io::cleanup(); - // SAFETY: Only called once during runtime cleanup. - sys::cleanup(); - }); -} - -// To reduce the generated code of the new `lang_start`, this function is doing -// the real work. -#[cfg(not(test))] -fn lang_start_internal( - main: &(dyn Fn() -> i32 + Sync + crate::panic::RefUnwindSafe), - argc: isize, - argv: *const *const u8, - sigpipe: u8, -) -> Result { - use crate::{mem, panic}; - let rt_abort = move |e| { - mem::forget(e); - rtabort!("initialization or cleanup bug"); - }; - // Guard against the code called by this function from unwinding outside of the Rust-controlled - // code, which is UB. This is a requirement imposed by a combination of how the - // `#[lang="start"]` attribute is implemented as well as by the implementation of the panicking - // mechanism itself. - // - // There are a couple of instances where unwinding can begin. First is inside of the - // `rt::init`, `rt::cleanup` and similar functions controlled by bstd. In those instances a - // panic is a std implementation bug. A quite likely one too, as there isn't any way to - // prevent std from accidentally introducing a panic to these functions. Another is from - // user code from `main` or, more nefariously, as described in e.g. issue #86030. - // SAFETY: Only called once during runtime initialization. - panic::catch_unwind(move || unsafe { init(argc, argv, sigpipe) }).map_err(rt_abort)?; - let ret_code = panic::catch_unwind(move || panic::catch_unwind(main).unwrap_or(101) as isize) - .map_err(move |e| { - mem::forget(e); - rtabort!("drop of the panic payload panicked"); - }); - panic::catch_unwind(cleanup).map_err(rt_abort)?; - ret_code -} - -#[cfg(not(any(test, doctest)))] -#[lang = "start"] -fn lang_start( - main: fn() -> T, - argc: isize, - argv: *const *const u8, - sigpipe: u8, -) -> isize { - let Ok(v) = lang_start_internal( - &move || crate::sys_common::backtrace::__rust_begin_short_backtrace(main).report().to_i32(), - argc, - argv, - sigpipe, - ); - v -} diff --git a/library/std/src/sync/barrier.rs b/library/std/src/sync/barrier.rs deleted file mode 100644 index b4bac081e7ab7..0000000000000 --- a/library/std/src/sync/barrier.rs +++ /dev/null @@ -1,175 +0,0 @@ -#[cfg(test)] -mod tests; - -use crate::fmt; -use crate::sync::{Condvar, Mutex}; - -/// A barrier enables multiple threads to synchronize the beginning -/// of some computation. -/// -/// # Examples -/// -/// ``` -/// use std::sync::{Arc, Barrier}; -/// use std::thread; -/// -/// let n = 10; -/// let mut handles = Vec::with_capacity(n); -/// let barrier = Arc::new(Barrier::new(n)); -/// for _ in 0..n { -/// let c = Arc::clone(&barrier); -/// // The same messages will be printed together. -/// // You will NOT see any interleaving. -/// handles.push(thread::spawn(move|| { -/// println!("before wait"); -/// c.wait(); -/// println!("after wait"); -/// })); -/// } -/// // Wait for other threads to finish. -/// for handle in handles { -/// handle.join().unwrap(); -/// } -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Barrier { - lock: Mutex, - cvar: Condvar, - num_threads: usize, -} - -// The inner state of a double barrier -struct BarrierState { - count: usize, - generation_id: usize, -} - -/// A `BarrierWaitResult` is returned by [`Barrier::wait()`] when all threads -/// in the [`Barrier`] have rendezvoused. -/// -/// # Examples -/// -/// ``` -/// use std::sync::Barrier; -/// -/// let barrier = Barrier::new(1); -/// let barrier_wait_result = barrier.wait(); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub struct BarrierWaitResult(bool); - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for Barrier { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Barrier").finish_non_exhaustive() - } -} - -impl Barrier { - /// Creates a new barrier that can block a given number of threads. - /// - /// A barrier will block `n`-1 threads which call [`wait()`] and then wake - /// up all threads at once when the `n`th thread calls [`wait()`]. - /// - /// [`wait()`]: Barrier::wait - /// - /// # Examples - /// - /// ``` - /// use std::sync::Barrier; - /// - /// let barrier = Barrier::new(10); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_barrier", since = "1.78.0")] - #[must_use] - #[inline] - pub const fn new(n: usize) -> Barrier { - Barrier { - lock: Mutex::new(BarrierState { count: 0, generation_id: 0 }), - cvar: Condvar::new(), - num_threads: n, - } - } - - /// Blocks the current thread until all threads have rendezvoused here. - /// - /// Barriers are re-usable after all threads have rendezvoused once, and can - /// be used continuously. - /// - /// A single (arbitrary) thread will receive a [`BarrierWaitResult`] that - /// returns `true` from [`BarrierWaitResult::is_leader()`] when returning - /// from this function, and all other threads will receive a result that - /// will return `false` from [`BarrierWaitResult::is_leader()`]. - /// - /// # Examples - /// - /// ``` - /// use std::sync::{Arc, Barrier}; - /// use std::thread; - /// - /// let n = 10; - /// let mut handles = Vec::with_capacity(n); - /// let barrier = Arc::new(Barrier::new(n)); - /// for _ in 0..n { - /// let c = Arc::clone(&barrier); - /// // The same messages will be printed together. - /// // You will NOT see any interleaving. - /// handles.push(thread::spawn(move|| { - /// println!("before wait"); - /// c.wait(); - /// println!("after wait"); - /// })); - /// } - /// // Wait for other threads to finish. - /// for handle in handles { - /// handle.join().unwrap(); - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn wait(&self) -> BarrierWaitResult { - let mut lock = self.lock.lock().unwrap(); - let local_gen = lock.generation_id; - lock.count += 1; - if lock.count < self.num_threads { - let _guard = - self.cvar.wait_while(lock, |state| local_gen == state.generation_id).unwrap(); - BarrierWaitResult(false) - } else { - lock.count = 0; - lock.generation_id = lock.generation_id.wrapping_add(1); - self.cvar.notify_all(); - BarrierWaitResult(true) - } - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for BarrierWaitResult { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("BarrierWaitResult").field("is_leader", &self.is_leader()).finish() - } -} - -impl BarrierWaitResult { - /// Returns `true` if this thread is the "leader thread" for the call to - /// [`Barrier::wait()`]. - /// - /// Only one thread will have `true` returned from their result, all other - /// threads will have `false` returned. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Barrier; - /// - /// let barrier = Barrier::new(1); - /// let barrier_wait_result = barrier.wait(); - /// println!("{:?}", barrier_wait_result.is_leader()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - pub fn is_leader(&self) -> bool { - self.0 - } -} diff --git a/library/std/src/sync/barrier/tests.rs b/library/std/src/sync/barrier/tests.rs deleted file mode 100644 index 834a3e75158a7..0000000000000 --- a/library/std/src/sync/barrier/tests.rs +++ /dev/null @@ -1,35 +0,0 @@ -use crate::sync::mpsc::{channel, TryRecvError}; -use crate::sync::{Arc, Barrier}; -use crate::thread; - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn test_barrier() { - const N: usize = 10; - - let barrier = Arc::new(Barrier::new(N)); - let (tx, rx) = channel(); - - for _ in 0..N - 1 { - let c = barrier.clone(); - let tx = tx.clone(); - thread::spawn(move || { - tx.send(c.wait().is_leader()).unwrap(); - }); - } - - // At this point, all spawned threads should be blocked, - // so we shouldn't get anything from the port - assert!(matches!(rx.try_recv(), Err(TryRecvError::Empty))); - - let mut leader_found = barrier.wait().is_leader(); - - // Now, the barrier is cleared and we should get data. - for _ in 0..N - 1 { - if rx.recv().unwrap() { - assert!(!leader_found); - leader_found = true; - } - } - assert!(leader_found); -} diff --git a/library/std/src/sync/condvar.rs b/library/std/src/sync/condvar.rs deleted file mode 100644 index b20574e4f1493..0000000000000 --- a/library/std/src/sync/condvar.rs +++ /dev/null @@ -1,562 +0,0 @@ -#[cfg(test)] -mod tests; - -use crate::fmt; -use crate::sync::{mutex, poison, LockResult, MutexGuard, PoisonError}; -use crate::sys::sync as sys; -use crate::time::{Duration, Instant}; - -/// A type indicating whether a timed wait on a condition variable returned -/// due to a time out or not. -/// -/// It is returned by the [`wait_timeout`] method. -/// -/// [`wait_timeout`]: Condvar::wait_timeout -#[derive(Debug, PartialEq, Eq, Copy, Clone)] -#[stable(feature = "wait_timeout", since = "1.5.0")] -pub struct WaitTimeoutResult(bool); - -impl WaitTimeoutResult { - /// Returns `true` if the wait was known to have timed out. - /// - /// # Examples - /// - /// This example spawns a thread which will sleep 20 milliseconds before - /// updating a boolean value and then notifying the condvar. - /// - /// The main thread will wait with a 10 millisecond timeout on the condvar - /// and will leave the loop upon timeout. - /// - /// ``` - /// use std::sync::{Arc, Condvar, Mutex}; - /// use std::thread; - /// use std::time::Duration; - /// - /// let pair = Arc::new((Mutex::new(false), Condvar::new())); - /// let pair2 = Arc::clone(&pair); - /// - /// thread::spawn(move || { - /// let (lock, cvar) = &*pair2; - /// - /// // Let's wait 20 milliseconds before notifying the condvar. - /// thread::sleep(Duration::from_millis(20)); - /// - /// let mut started = lock.lock().unwrap(); - /// // We update the boolean value. - /// *started = true; - /// cvar.notify_one(); - /// }); - /// - /// // Wait for the thread to start up. - /// let (lock, cvar) = &*pair; - /// loop { - /// // Let's put a timeout on the condvar's wait. - /// let result = cvar.wait_timeout(lock.lock().unwrap(), Duration::from_millis(10)).unwrap(); - /// // 10 milliseconds have passed. - /// if result.1.timed_out() { - /// // timed out now and we can leave. - /// break - /// } - /// } - /// ``` - #[must_use] - #[stable(feature = "wait_timeout", since = "1.5.0")] - pub fn timed_out(&self) -> bool { - self.0 - } -} - -/// A Condition Variable -/// -/// Condition variables represent the ability to block a thread such that it -/// consumes no CPU time while waiting for an event to occur. Condition -/// variables are typically associated with a boolean predicate (a condition) -/// and a mutex. The predicate is always verified inside of the mutex before -/// determining that a thread must block. -/// -/// Functions in this module will block the current **thread** of execution. -/// Note that any attempt to use multiple mutexes on the same condition -/// variable may result in a runtime panic. -/// -/// # Examples -/// -/// ``` -/// use std::sync::{Arc, Mutex, Condvar}; -/// use std::thread; -/// -/// let pair = Arc::new((Mutex::new(false), Condvar::new())); -/// let pair2 = Arc::clone(&pair); -/// -/// // Inside of our lock, spawn a new thread, and then wait for it to start. -/// thread::spawn(move|| { -/// let (lock, cvar) = &*pair2; -/// let mut started = lock.lock().unwrap(); -/// *started = true; -/// // We notify the condvar that the value has changed. -/// cvar.notify_one(); -/// }); -/// -/// // Wait for the thread to start up. -/// let (lock, cvar) = &*pair; -/// let mut started = lock.lock().unwrap(); -/// while !*started { -/// started = cvar.wait(started).unwrap(); -/// } -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Condvar { - inner: sys::Condvar, -} - -impl Condvar { - /// Creates a new condition variable which is ready to be waited on and - /// notified. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Condvar; - /// - /// let condvar = Condvar::new(); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_locks", since = "1.63.0")] - #[must_use] - #[inline] - pub const fn new() -> Condvar { - Condvar { inner: sys::Condvar::new() } - } - - /// Blocks the current thread until this condition variable receives a - /// notification. - /// - /// This function will atomically unlock the mutex specified (represented by - /// `guard`) and block the current thread. This means that any calls - /// to [`notify_one`] or [`notify_all`] which happen logically after the - /// mutex is unlocked are candidates to wake this thread up. When this - /// function call returns, the lock specified will have been re-acquired. - /// - /// Note that this function is susceptible to spurious wakeups. Condition - /// variables normally have a boolean predicate associated with them, and - /// the predicate must always be checked each time this function returns to - /// protect against spurious wakeups. - /// - /// # Errors - /// - /// This function will return an error if the mutex being waited on is - /// poisoned when this thread re-acquires the lock. For more information, - /// see information about [poisoning] on the [`Mutex`] type. - /// - /// # Panics - /// - /// This function may [`panic!`] if it is used with more than one mutex - /// over time. - /// - /// [`notify_one`]: Self::notify_one - /// [`notify_all`]: Self::notify_all - /// [poisoning]: super::Mutex#poisoning - /// [`Mutex`]: super::Mutex - /// - /// # Examples - /// - /// ``` - /// use std::sync::{Arc, Mutex, Condvar}; - /// use std::thread; - /// - /// let pair = Arc::new((Mutex::new(false), Condvar::new())); - /// let pair2 = Arc::clone(&pair); - /// - /// thread::spawn(move|| { - /// let (lock, cvar) = &*pair2; - /// let mut started = lock.lock().unwrap(); - /// *started = true; - /// // We notify the condvar that the value has changed. - /// cvar.notify_one(); - /// }); - /// - /// // Wait for the thread to start up. - /// let (lock, cvar) = &*pair; - /// let mut started = lock.lock().unwrap(); - /// // As long as the value inside the `Mutex` is `false`, we wait. - /// while !*started { - /// started = cvar.wait(started).unwrap(); - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn wait<'a, T>(&self, guard: MutexGuard<'a, T>) -> LockResult> { - let poisoned = unsafe { - let lock = mutex::guard_lock(&guard); - self.inner.wait(lock); - mutex::guard_poison(&guard).get() - }; - if poisoned { Err(PoisonError::new(guard)) } else { Ok(guard) } - } - - /// Blocks the current thread until this condition variable receives a - /// notification and the provided condition is false. - /// - /// This function will atomically unlock the mutex specified (represented by - /// `guard`) and block the current thread. This means that any calls - /// to [`notify_one`] or [`notify_all`] which happen logically after the - /// mutex is unlocked are candidates to wake this thread up. When this - /// function call returns, the lock specified will have been re-acquired. - /// - /// # Errors - /// - /// This function will return an error if the mutex being waited on is - /// poisoned when this thread re-acquires the lock. For more information, - /// see information about [poisoning] on the [`Mutex`] type. - /// - /// [`notify_one`]: Self::notify_one - /// [`notify_all`]: Self::notify_all - /// [poisoning]: super::Mutex#poisoning - /// [`Mutex`]: super::Mutex - /// - /// # Examples - /// - /// ``` - /// use std::sync::{Arc, Mutex, Condvar}; - /// use std::thread; - /// - /// let pair = Arc::new((Mutex::new(true), Condvar::new())); - /// let pair2 = Arc::clone(&pair); - /// - /// thread::spawn(move|| { - /// let (lock, cvar) = &*pair2; - /// let mut pending = lock.lock().unwrap(); - /// *pending = false; - /// // We notify the condvar that the value has changed. - /// cvar.notify_one(); - /// }); - /// - /// // Wait for the thread to start up. - /// let (lock, cvar) = &*pair; - /// // As long as the value inside the `Mutex` is `true`, we wait. - /// let _guard = cvar.wait_while(lock.lock().unwrap(), |pending| { *pending }).unwrap(); - /// ``` - #[stable(feature = "wait_until", since = "1.42.0")] - pub fn wait_while<'a, T, F>( - &self, - mut guard: MutexGuard<'a, T>, - mut condition: F, - ) -> LockResult> - where - F: FnMut(&mut T) -> bool, - { - while condition(&mut *guard) { - guard = self.wait(guard)?; - } - Ok(guard) - } - - /// Waits on this condition variable for a notification, timing out after a - /// specified duration. - /// - /// The semantics of this function are equivalent to [`wait`] - /// except that the thread will be blocked for roughly no longer - /// than `ms` milliseconds. This method should not be used for - /// precise timing due to anomalies such as preemption or platform - /// differences that might not cause the maximum amount of time - /// waited to be precisely `ms`. - /// - /// Note that the best effort is made to ensure that the time waited is - /// measured with a monotonic clock, and not affected by the changes made to - /// the system time. - /// - /// The returned boolean is `false` only if the timeout is known - /// to have elapsed. - /// - /// Like [`wait`], the lock specified will be re-acquired when this function - /// returns, regardless of whether the timeout elapsed or not. - /// - /// [`wait`]: Self::wait - /// - /// # Examples - /// - /// ``` - /// use std::sync::{Arc, Mutex, Condvar}; - /// use std::thread; - /// - /// let pair = Arc::new((Mutex::new(false), Condvar::new())); - /// let pair2 = Arc::clone(&pair); - /// - /// thread::spawn(move|| { - /// let (lock, cvar) = &*pair2; - /// let mut started = lock.lock().unwrap(); - /// *started = true; - /// // We notify the condvar that the value has changed. - /// cvar.notify_one(); - /// }); - /// - /// // Wait for the thread to start up. - /// let (lock, cvar) = &*pair; - /// let mut started = lock.lock().unwrap(); - /// // As long as the value inside the `Mutex` is `false`, we wait. - /// loop { - /// let result = cvar.wait_timeout_ms(started, 10).unwrap(); - /// // 10 milliseconds have passed, or maybe the value changed! - /// started = result.0; - /// if *started == true { - /// // We received the notification and the value has been updated, we can leave. - /// break - /// } - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[deprecated(since = "1.6.0", note = "replaced by `std::sync::Condvar::wait_timeout`")] - pub fn wait_timeout_ms<'a, T>( - &self, - guard: MutexGuard<'a, T>, - ms: u32, - ) -> LockResult<(MutexGuard<'a, T>, bool)> { - let res = self.wait_timeout(guard, Duration::from_millis(ms as u64)); - poison::map_result(res, |(a, b)| (a, !b.timed_out())) - } - - /// Waits on this condition variable for a notification, timing out after a - /// specified duration. - /// - /// The semantics of this function are equivalent to [`wait`] except that - /// the thread will be blocked for roughly no longer than `dur`. This - /// method should not be used for precise timing due to anomalies such as - /// preemption or platform differences that might not cause the maximum - /// amount of time waited to be precisely `dur`. - /// - /// Note that the best effort is made to ensure that the time waited is - /// measured with a monotonic clock, and not affected by the changes made to - /// the system time. This function is susceptible to spurious wakeups. - /// Condition variables normally have a boolean predicate associated with - /// them, and the predicate must always be checked each time this function - /// returns to protect against spurious wakeups. Additionally, it is - /// typically desirable for the timeout to not exceed some duration in - /// spite of spurious wakes, thus the sleep-duration is decremented by the - /// amount slept. Alternatively, use the `wait_timeout_while` method - /// to wait with a timeout while a predicate is true. - /// - /// The returned [`WaitTimeoutResult`] value indicates if the timeout is - /// known to have elapsed. - /// - /// Like [`wait`], the lock specified will be re-acquired when this function - /// returns, regardless of whether the timeout elapsed or not. - /// - /// [`wait`]: Self::wait - /// [`wait_timeout_while`]: Self::wait_timeout_while - /// - /// # Examples - /// - /// ``` - /// use std::sync::{Arc, Mutex, Condvar}; - /// use std::thread; - /// use std::time::Duration; - /// - /// let pair = Arc::new((Mutex::new(false), Condvar::new())); - /// let pair2 = Arc::clone(&pair); - /// - /// thread::spawn(move|| { - /// let (lock, cvar) = &*pair2; - /// let mut started = lock.lock().unwrap(); - /// *started = true; - /// // We notify the condvar that the value has changed. - /// cvar.notify_one(); - /// }); - /// - /// // wait for the thread to start up - /// let (lock, cvar) = &*pair; - /// let mut started = lock.lock().unwrap(); - /// // as long as the value inside the `Mutex` is `false`, we wait - /// loop { - /// let result = cvar.wait_timeout(started, Duration::from_millis(10)).unwrap(); - /// // 10 milliseconds have passed, or maybe the value changed! - /// started = result.0; - /// if *started == true { - /// // We received the notification and the value has been updated, we can leave. - /// break - /// } - /// } - /// ``` - #[stable(feature = "wait_timeout", since = "1.5.0")] - pub fn wait_timeout<'a, T>( - &self, - guard: MutexGuard<'a, T>, - dur: Duration, - ) -> LockResult<(MutexGuard<'a, T>, WaitTimeoutResult)> { - let (poisoned, result) = unsafe { - let lock = mutex::guard_lock(&guard); - let success = self.inner.wait_timeout(lock, dur); - (mutex::guard_poison(&guard).get(), WaitTimeoutResult(!success)) - }; - if poisoned { Err(PoisonError::new((guard, result))) } else { Ok((guard, result)) } - } - - /// Waits on this condition variable for a notification, timing out after a - /// specified duration. - /// - /// The semantics of this function are equivalent to [`wait_while`] except - /// that the thread will be blocked for roughly no longer than `dur`. This - /// method should not be used for precise timing due to anomalies such as - /// preemption or platform differences that might not cause the maximum - /// amount of time waited to be precisely `dur`. - /// - /// Note that the best effort is made to ensure that the time waited is - /// measured with a monotonic clock, and not affected by the changes made to - /// the system time. - /// - /// The returned [`WaitTimeoutResult`] value indicates if the timeout is - /// known to have elapsed without the condition being met. - /// - /// Like [`wait_while`], the lock specified will be re-acquired when this - /// function returns, regardless of whether the timeout elapsed or not. - /// - /// [`wait_while`]: Self::wait_while - /// [`wait_timeout`]: Self::wait_timeout - /// - /// # Examples - /// - /// ``` - /// use std::sync::{Arc, Mutex, Condvar}; - /// use std::thread; - /// use std::time::Duration; - /// - /// let pair = Arc::new((Mutex::new(true), Condvar::new())); - /// let pair2 = Arc::clone(&pair); - /// - /// thread::spawn(move|| { - /// let (lock, cvar) = &*pair2; - /// let mut pending = lock.lock().unwrap(); - /// *pending = false; - /// // We notify the condvar that the value has changed. - /// cvar.notify_one(); - /// }); - /// - /// // wait for the thread to start up - /// let (lock, cvar) = &*pair; - /// let result = cvar.wait_timeout_while( - /// lock.lock().unwrap(), - /// Duration::from_millis(100), - /// |&mut pending| pending, - /// ).unwrap(); - /// if result.1.timed_out() { - /// // timed-out without the condition ever evaluating to false. - /// } - /// // access the locked mutex via result.0 - /// ``` - #[stable(feature = "wait_timeout_until", since = "1.42.0")] - pub fn wait_timeout_while<'a, T, F>( - &self, - mut guard: MutexGuard<'a, T>, - dur: Duration, - mut condition: F, - ) -> LockResult<(MutexGuard<'a, T>, WaitTimeoutResult)> - where - F: FnMut(&mut T) -> bool, - { - let start = Instant::now(); - loop { - if !condition(&mut *guard) { - return Ok((guard, WaitTimeoutResult(false))); - } - let timeout = match dur.checked_sub(start.elapsed()) { - Some(timeout) => timeout, - None => return Ok((guard, WaitTimeoutResult(true))), - }; - guard = self.wait_timeout(guard, timeout)?.0; - } - } - - /// Wakes up one blocked thread on this condvar. - /// - /// If there is a blocked thread on this condition variable, then it will - /// be woken up from its call to [`wait`] or [`wait_timeout`]. Calls to - /// `notify_one` are not buffered in any way. - /// - /// To wake up all threads, see [`notify_all`]. - /// - /// [`wait`]: Self::wait - /// [`wait_timeout`]: Self::wait_timeout - /// [`notify_all`]: Self::notify_all - /// - /// # Examples - /// - /// ``` - /// use std::sync::{Arc, Mutex, Condvar}; - /// use std::thread; - /// - /// let pair = Arc::new((Mutex::new(false), Condvar::new())); - /// let pair2 = Arc::clone(&pair); - /// - /// thread::spawn(move|| { - /// let (lock, cvar) = &*pair2; - /// let mut started = lock.lock().unwrap(); - /// *started = true; - /// // We notify the condvar that the value has changed. - /// cvar.notify_one(); - /// }); - /// - /// // Wait for the thread to start up. - /// let (lock, cvar) = &*pair; - /// let mut started = lock.lock().unwrap(); - /// // As long as the value inside the `Mutex` is `false`, we wait. - /// while !*started { - /// started = cvar.wait(started).unwrap(); - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn notify_one(&self) { - self.inner.notify_one() - } - - /// Wakes up all blocked threads on this condvar. - /// - /// This method will ensure that any current waiters on the condition - /// variable are awoken. Calls to `notify_all()` are not buffered in any - /// way. - /// - /// To wake up only one thread, see [`notify_one`]. - /// - /// [`notify_one`]: Self::notify_one - /// - /// # Examples - /// - /// ``` - /// use std::sync::{Arc, Mutex, Condvar}; - /// use std::thread; - /// - /// let pair = Arc::new((Mutex::new(false), Condvar::new())); - /// let pair2 = Arc::clone(&pair); - /// - /// thread::spawn(move|| { - /// let (lock, cvar) = &*pair2; - /// let mut started = lock.lock().unwrap(); - /// *started = true; - /// // We notify the condvar that the value has changed. - /// cvar.notify_all(); - /// }); - /// - /// // Wait for the thread to start up. - /// let (lock, cvar) = &*pair; - /// let mut started = lock.lock().unwrap(); - /// // As long as the value inside the `Mutex` is `false`, we wait. - /// while !*started { - /// started = cvar.wait(started).unwrap(); - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn notify_all(&self) { - self.inner.notify_all() - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for Condvar { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Condvar").finish_non_exhaustive() - } -} - -#[stable(feature = "condvar_default", since = "1.10.0")] -impl Default for Condvar { - /// Creates a `Condvar` which is ready to be waited on and notified. - fn default() -> Condvar { - Condvar::new() - } -} diff --git a/library/std/src/sync/condvar/tests.rs b/library/std/src/sync/condvar/tests.rs deleted file mode 100644 index 12d13a6b20be3..0000000000000 --- a/library/std/src/sync/condvar/tests.rs +++ /dev/null @@ -1,190 +0,0 @@ -use crate::sync::atomic::{AtomicBool, Ordering}; -use crate::sync::mpsc::channel; -use crate::sync::{Arc, Condvar, Mutex}; -use crate::thread; -use crate::time::Duration; - -#[test] -fn smoke() { - let c = Condvar::new(); - c.notify_one(); - c.notify_all(); -} - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn notify_one() { - let m = Arc::new(Mutex::new(())); - let m2 = m.clone(); - let c = Arc::new(Condvar::new()); - let c2 = c.clone(); - - let g = m.lock().unwrap(); - let _t = thread::spawn(move || { - let _g = m2.lock().unwrap(); - c2.notify_one(); - }); - let g = c.wait(g).unwrap(); - drop(g); -} - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn notify_all() { - const N: usize = 10; - - let data = Arc::new((Mutex::new(0), Condvar::new())); - let (tx, rx) = channel(); - for _ in 0..N { - let data = data.clone(); - let tx = tx.clone(); - thread::spawn(move || { - let &(ref lock, ref cond) = &*data; - let mut cnt = lock.lock().unwrap(); - *cnt += 1; - if *cnt == N { - tx.send(()).unwrap(); - } - while *cnt != 0 { - cnt = cond.wait(cnt).unwrap(); - } - tx.send(()).unwrap(); - }); - } - drop(tx); - - let &(ref lock, ref cond) = &*data; - rx.recv().unwrap(); - let mut cnt = lock.lock().unwrap(); - *cnt = 0; - cond.notify_all(); - drop(cnt); - - for _ in 0..N { - rx.recv().unwrap(); - } -} - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn wait_while() { - let pair = Arc::new((Mutex::new(false), Condvar::new())); - let pair2 = pair.clone(); - - // Inside of our lock, spawn a new thread, and then wait for it to start. - thread::spawn(move || { - let &(ref lock, ref cvar) = &*pair2; - let mut started = lock.lock().unwrap(); - *started = true; - // We notify the condvar that the value has changed. - cvar.notify_one(); - }); - - // Wait for the thread to start up. - let &(ref lock, ref cvar) = &*pair; - let guard = cvar.wait_while(lock.lock().unwrap(), |started| !*started); - assert!(*guard.unwrap()); -} - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn wait_timeout_wait() { - let m = Arc::new(Mutex::new(())); - let c = Arc::new(Condvar::new()); - - loop { - let g = m.lock().unwrap(); - let (_g, no_timeout) = c.wait_timeout(g, Duration::from_millis(1)).unwrap(); - // spurious wakeups mean this isn't necessarily true - // so execute test again, if not timeout - if !no_timeout.timed_out() { - continue; - } - - break; - } -} - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn wait_timeout_while_wait() { - let m = Arc::new(Mutex::new(())); - let c = Arc::new(Condvar::new()); - - let g = m.lock().unwrap(); - let (_g, wait) = c.wait_timeout_while(g, Duration::from_millis(1), |_| true).unwrap(); - // no spurious wakeups. ensure it timed-out - assert!(wait.timed_out()); -} - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn wait_timeout_while_instant_satisfy() { - let m = Arc::new(Mutex::new(())); - let c = Arc::new(Condvar::new()); - - let g = m.lock().unwrap(); - let (_g, wait) = c.wait_timeout_while(g, Duration::from_millis(0), |_| false).unwrap(); - // ensure it didn't time-out even if we were not given any time. - assert!(!wait.timed_out()); -} - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn wait_timeout_while_wake() { - let pair = Arc::new((Mutex::new(false), Condvar::new())); - let pair_copy = pair.clone(); - - let &(ref m, ref c) = &*pair; - let g = m.lock().unwrap(); - let _t = thread::spawn(move || { - let &(ref lock, ref cvar) = &*pair_copy; - let mut started = lock.lock().unwrap(); - thread::sleep(Duration::from_millis(1)); - *started = true; - cvar.notify_one(); - }); - let (g2, wait) = c - .wait_timeout_while(g, Duration::from_millis(u64::MAX), |&mut notified| !notified) - .unwrap(); - // ensure it didn't time-out even if we were not given any time. - assert!(!wait.timed_out()); - assert!(*g2); -} - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn wait_timeout_wake() { - let m = Arc::new(Mutex::new(())); - let c = Arc::new(Condvar::new()); - - loop { - let g = m.lock().unwrap(); - - let c2 = c.clone(); - let m2 = m.clone(); - - let notified = Arc::new(AtomicBool::new(false)); - let notified_copy = notified.clone(); - - let t = thread::spawn(move || { - let _g = m2.lock().unwrap(); - thread::sleep(Duration::from_millis(1)); - notified_copy.store(true, Ordering::Relaxed); - c2.notify_one(); - }); - let (g, timeout_res) = c.wait_timeout(g, Duration::from_millis(u64::MAX)).unwrap(); - assert!(!timeout_res.timed_out()); - // spurious wakeups mean this isn't necessarily true - // so execute test again, if not notified - if !notified.load(Ordering::Relaxed) { - t.join().unwrap(); - continue; - } - drop(g); - - t.join().unwrap(); - - break; - } -} diff --git a/library/std/src/sync/lazy_lock.rs b/library/std/src/sync/lazy_lock.rs deleted file mode 100644 index 27b59cfc8c24d..0000000000000 --- a/library/std/src/sync/lazy_lock.rs +++ /dev/null @@ -1,255 +0,0 @@ -use crate::cell::UnsafeCell; -use crate::mem::ManuallyDrop; -use crate::ops::Deref; -use crate::panic::{RefUnwindSafe, UnwindSafe}; -use crate::sync::Once; -use crate::{fmt, ptr}; - -use super::once::ExclusiveState; - -// We use the state of a Once as discriminant value. Upon creation, the state is -// "incomplete" and `f` contains the initialization closure. In the first call to -// `call_once`, `f` is taken and run. If it succeeds, `value` is set and the state -// is changed to "complete". If it panics, the Once is poisoned, so none of the -// two fields is initialized. -union Data { - value: ManuallyDrop, - f: ManuallyDrop, -} - -/// A value which is initialized on the first access. -/// -/// This type is a thread-safe [`LazyCell`], and can be used in statics. -/// Since initialization may be called from multiple threads, any -/// dereferencing call will block the calling thread if another -/// initialization routine is currently running. -/// -/// [`LazyCell`]: crate::cell::LazyCell -/// -/// # Examples -/// -/// Initialize static variables with `LazyLock`. -/// -/// ``` -/// #![feature(lazy_cell)] -/// -/// use std::collections::HashMap; -/// -/// use std::sync::LazyLock; -/// -/// static HASHMAP: LazyLock> = LazyLock::new(|| { -/// println!("initializing"); -/// let mut m = HashMap::new(); -/// m.insert(13, "Spica".to_string()); -/// m.insert(74, "Hoyten".to_string()); -/// m -/// }); -/// -/// fn main() { -/// println!("ready"); -/// std::thread::spawn(|| { -/// println!("{:?}", HASHMAP.get(&13)); -/// }).join().unwrap(); -/// println!("{:?}", HASHMAP.get(&74)); -/// -/// // Prints: -/// // ready -/// // initializing -/// // Some("Spica") -/// // Some("Hoyten") -/// } -/// ``` -/// Initialize fields with `LazyLock`. -/// ``` -/// #![feature(lazy_cell)] -/// -/// use std::sync::LazyLock; -/// -/// #[derive(Debug)] -/// struct UseCellLock { -/// number: LazyLock, -/// } -/// fn main() { -/// let lock: LazyLock = LazyLock::new(|| 0u32); -/// -/// let data = UseCellLock { number: lock }; -/// println!("{}", *data.number); -/// } -/// ``` - -#[unstable(feature = "lazy_cell", issue = "109736")] -pub struct LazyLock T> { - once: Once, - data: UnsafeCell>, -} - -impl T> LazyLock { - /// Creates a new lazy value with the given initializing function. - #[inline] - #[unstable(feature = "lazy_cell", issue = "109736")] - pub const fn new(f: F) -> LazyLock { - LazyLock { once: Once::new(), data: UnsafeCell::new(Data { f: ManuallyDrop::new(f) }) } - } - - /// Creates a new lazy value that is already initialized. - #[inline] - #[cfg(test)] - pub(crate) fn preinit(value: T) -> LazyLock { - let once = Once::new(); - once.call_once(|| {}); - LazyLock { once, data: UnsafeCell::new(Data { value: ManuallyDrop::new(value) }) } - } - - /// Consumes this `LazyLock` returning the stored value. - /// - /// Returns `Ok(value)` if `Lazy` is initialized and `Err(f)` otherwise. - /// - /// # Examples - /// - /// ``` - /// #![feature(lazy_cell)] - /// #![feature(lazy_cell_consume)] - /// - /// use std::sync::LazyLock; - /// - /// let hello = "Hello, World!".to_string(); - /// - /// let lazy = LazyLock::new(|| hello.to_uppercase()); - /// - /// assert_eq!(&*lazy, "HELLO, WORLD!"); - /// assert_eq!(LazyLock::into_inner(lazy).ok(), Some("HELLO, WORLD!".to_string())); - /// ``` - #[unstable(feature = "lazy_cell_consume", issue = "109736")] - pub fn into_inner(mut this: Self) -> Result { - let state = this.once.state(); - match state { - ExclusiveState::Poisoned => panic!("LazyLock instance has previously been poisoned"), - state => { - let this = ManuallyDrop::new(this); - let data = unsafe { ptr::read(&this.data) }.into_inner(); - match state { - ExclusiveState::Incomplete => Err(ManuallyDrop::into_inner(unsafe { data.f })), - ExclusiveState::Complete => Ok(ManuallyDrop::into_inner(unsafe { data.value })), - ExclusiveState::Poisoned => unreachable!(), - } - } - } - } - - /// Forces the evaluation of this lazy value and returns a reference to - /// result. This is equivalent to the `Deref` impl, but is explicit. - /// - /// This method will block the calling thread if another initialization - /// routine is currently running. - /// - /// # Examples - /// - /// ``` - /// #![feature(lazy_cell)] - /// - /// use std::sync::LazyLock; - /// - /// let lazy = LazyLock::new(|| 92); - /// - /// assert_eq!(LazyLock::force(&lazy), &92); - /// assert_eq!(&*lazy, &92); - /// ``` - #[inline] - #[unstable(feature = "lazy_cell", issue = "109736")] - pub fn force(this: &LazyLock) -> &T { - this.once.call_once(|| { - // SAFETY: `call_once` only runs this closure once, ever. - let data = unsafe { &mut *this.data.get() }; - let f = unsafe { ManuallyDrop::take(&mut data.f) }; - let value = f(); - data.value = ManuallyDrop::new(value); - }); - - // SAFETY: - // There are four possible scenarios: - // * the closure was called and initialized `value`. - // * the closure was called and panicked, so this point is never reached. - // * the closure was not called, but a previous call initialized `value`. - // * the closure was not called because the Once is poisoned, so this point - // is never reached. - // So `value` has definitely been initialized and will not be modified again. - unsafe { &*(*this.data.get()).value } - } -} - -impl LazyLock { - /// Get the inner value if it has already been initialized. - fn get(&self) -> Option<&T> { - if self.once.is_completed() { - // SAFETY: - // The closure has been run successfully, so `value` has been initialized - // and will not be modified again. - Some(unsafe { &*(*self.data.get()).value }) - } else { - None - } - } -} - -#[unstable(feature = "lazy_cell", issue = "109736")] -impl Drop for LazyLock { - fn drop(&mut self) { - match self.once.state() { - ExclusiveState::Incomplete => unsafe { ManuallyDrop::drop(&mut self.data.get_mut().f) }, - ExclusiveState::Complete => unsafe { - ManuallyDrop::drop(&mut self.data.get_mut().value) - }, - ExclusiveState::Poisoned => {} - } - } -} - -#[unstable(feature = "lazy_cell", issue = "109736")] -impl T> Deref for LazyLock { - type Target = T; - - /// Dereferences the value. - /// - /// This method will block the calling thread if another initialization - /// routine is currently running. - /// - #[inline] - fn deref(&self) -> &T { - LazyLock::force(self) - } -} - -#[unstable(feature = "lazy_cell", issue = "109736")] -impl Default for LazyLock { - /// Creates a new lazy value using `Default` as the initializing function. - #[inline] - fn default() -> LazyLock { - LazyLock::new(T::default) - } -} - -#[unstable(feature = "lazy_cell", issue = "109736")] -impl fmt::Debug for LazyLock { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let mut d = f.debug_tuple("LazyLock"); - match self.get() { - Some(v) => d.field(v), - None => d.field(&format_args!("")), - }; - d.finish() - } -} - -// We never create a `&F` from a `&LazyLock` so it is fine -// to not impl `Sync` for `F`. -#[unstable(feature = "lazy_cell", issue = "109736")] -unsafe impl Sync for LazyLock {} -// auto-derived `Send` impl is OK. - -#[unstable(feature = "lazy_cell", issue = "109736")] -impl RefUnwindSafe for LazyLock {} -#[unstable(feature = "lazy_cell", issue = "109736")] -impl UnwindSafe for LazyLock {} - -#[cfg(test)] -mod tests; diff --git a/library/std/src/sync/lazy_lock/tests.rs b/library/std/src/sync/lazy_lock/tests.rs deleted file mode 100644 index a5d4e25c5962a..0000000000000 --- a/library/std/src/sync/lazy_lock/tests.rs +++ /dev/null @@ -1,149 +0,0 @@ -use crate::{ - cell::LazyCell, - panic, - sync::{ - atomic::{AtomicUsize, Ordering::SeqCst}, - Mutex, - }, - sync::{LazyLock, OnceLock}, - thread, -}; - -fn spawn_and_wait(f: impl FnOnce() -> R + Send + 'static) -> R { - thread::spawn(f).join().unwrap() -} - -#[test] -fn lazy_default() { - static CALLED: AtomicUsize = AtomicUsize::new(0); - - struct Foo(u8); - impl Default for Foo { - fn default() -> Self { - CALLED.fetch_add(1, SeqCst); - Foo(42) - } - } - - let lazy: LazyCell> = <_>::default(); - - assert_eq!(CALLED.load(SeqCst), 0); - - assert_eq!(lazy.lock().unwrap().0, 42); - assert_eq!(CALLED.load(SeqCst), 1); - - lazy.lock().unwrap().0 = 21; - - assert_eq!(lazy.lock().unwrap().0, 21); - assert_eq!(CALLED.load(SeqCst), 1); -} - -#[test] -fn lazy_poisoning() { - let x: LazyCell = LazyCell::new(|| panic!("kaboom")); - for _ in 0..2 { - let res = panic::catch_unwind(panic::AssertUnwindSafe(|| x.len())); - assert!(res.is_err()); - } -} - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn sync_lazy_new() { - static CALLED: AtomicUsize = AtomicUsize::new(0); - static SYNC_LAZY: LazyLock = LazyLock::new(|| { - CALLED.fetch_add(1, SeqCst); - 92 - }); - - assert_eq!(CALLED.load(SeqCst), 0); - - spawn_and_wait(|| { - let y = *SYNC_LAZY - 30; - assert_eq!(y, 62); - assert_eq!(CALLED.load(SeqCst), 1); - }); - - let y = *SYNC_LAZY - 30; - assert_eq!(y, 62); - assert_eq!(CALLED.load(SeqCst), 1); -} - -#[test] -fn sync_lazy_default() { - static CALLED: AtomicUsize = AtomicUsize::new(0); - - struct Foo(u8); - impl Default for Foo { - fn default() -> Self { - CALLED.fetch_add(1, SeqCst); - Foo(42) - } - } - - let lazy: LazyLock> = <_>::default(); - - assert_eq!(CALLED.load(SeqCst), 0); - - assert_eq!(lazy.lock().unwrap().0, 42); - assert_eq!(CALLED.load(SeqCst), 1); - - lazy.lock().unwrap().0 = 21; - - assert_eq!(lazy.lock().unwrap().0, 21); - assert_eq!(CALLED.load(SeqCst), 1); -} - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn static_sync_lazy() { - static XS: LazyLock> = LazyLock::new(|| { - let mut xs = Vec::new(); - xs.push(1); - xs.push(2); - xs.push(3); - xs - }); - - spawn_and_wait(|| { - assert_eq!(&*XS, &vec![1, 2, 3]); - }); - - assert_eq!(&*XS, &vec![1, 2, 3]); -} - -#[test] -fn static_sync_lazy_via_fn() { - fn xs() -> &'static Vec { - static XS: OnceLock> = OnceLock::new(); - XS.get_or_init(|| { - let mut xs = Vec::new(); - xs.push(1); - xs.push(2); - xs.push(3); - xs - }) - } - assert_eq!(xs(), &vec![1, 2, 3]); -} - -#[test] -fn sync_lazy_poisoning() { - let x: LazyLock = LazyLock::new(|| panic!("kaboom")); - for _ in 0..2 { - let res = panic::catch_unwind(|| x.len()); - assert!(res.is_err()); - } -} - -// Check that we can infer `T` from closure's type. -#[test] -fn lazy_type_inference() { - let _ = LazyCell::new(|| ()); -} - -#[test] -fn is_sync_send() { - fn assert_traits() {} - assert_traits::>(); -} diff --git a/library/std/src/sync/mod.rs b/library/std/src/sync/mod.rs deleted file mode 100644 index e8c35bd48a70b..0000000000000 --- a/library/std/src/sync/mod.rs +++ /dev/null @@ -1,201 +0,0 @@ -//! Useful synchronization primitives. -//! -//! ## The need for synchronization -//! -//! Conceptually, a Rust program is a series of operations which will -//! be executed on a computer. The timeline of events happening in the -//! program is consistent with the order of the operations in the code. -//! -//! Consider the following code, operating on some global static variables: -//! -//! ```rust -//! static mut A: u32 = 0; -//! static mut B: u32 = 0; -//! static mut C: u32 = 0; -//! -//! fn main() { -//! unsafe { -//! A = 3; -//! B = 4; -//! A = A + B; -//! C = B; -//! println!("{A} {B} {C}"); -//! C = A; -//! } -//! } -//! ``` -//! -//! It appears as if some variables stored in memory are changed, an addition -//! is performed, result is stored in `A` and the variable `C` is -//! modified twice. -//! -//! When only a single thread is involved, the results are as expected: -//! the line `7 4 4` gets printed. -//! -//! As for what happens behind the scenes, when optimizations are enabled the -//! final generated machine code might look very different from the code: -//! -//! - The first store to `C` might be moved before the store to `A` or `B`, -//! _as if_ we had written `C = 4; A = 3; B = 4`. -//! -//! - Assignment of `A + B` to `A` might be removed, since the sum can be stored -//! in a temporary location until it gets printed, with the global variable -//! never getting updated. -//! -//! - The final result could be determined just by looking at the code -//! at compile time, so [constant folding] might turn the whole -//! block into a simple `println!("7 4 4")`. -//! -//! The compiler is allowed to perform any combination of these -//! optimizations, as long as the final optimized code, when executed, -//! produces the same results as the one without optimizations. -//! -//! Due to the [concurrency] involved in modern computers, assumptions -//! about the program's execution order are often wrong. Access to -//! global variables can lead to nondeterministic results, **even if** -//! compiler optimizations are disabled, and it is **still possible** -//! to introduce synchronization bugs. -//! -//! Note that thanks to Rust's safety guarantees, accessing global (static) -//! variables requires `unsafe` code, assuming we don't use any of the -//! synchronization primitives in this module. -//! -//! [constant folding]: https://en.wikipedia.org/wiki/Constant_folding -//! [concurrency]: https://en.wikipedia.org/wiki/Concurrency_(computer_science) -//! -//! ## Out-of-order execution -//! -//! Instructions can execute in a different order from the one we define, due to -//! various reasons: -//! -//! - The **compiler** reordering instructions: If the compiler can issue an -//! instruction at an earlier point, it will try to do so. For example, it -//! might hoist memory loads at the top of a code block, so that the CPU can -//! start [prefetching] the values from memory. -//! -//! In single-threaded scenarios, this can cause issues when writing -//! signal handlers or certain kinds of low-level code. -//! Use [compiler fences] to prevent this reordering. -//! -//! - A **single processor** executing instructions [out-of-order]: -//! Modern CPUs are capable of [superscalar] execution, -//! i.e., multiple instructions might be executing at the same time, -//! even though the machine code describes a sequential process. -//! -//! This kind of reordering is handled transparently by the CPU. -//! -//! - A **multiprocessor** system executing multiple hardware threads -//! at the same time: In multi-threaded scenarios, you can use two -//! kinds of primitives to deal with synchronization: -//! - [memory fences] to ensure memory accesses are made visible to -//! other CPUs in the right order. -//! - [atomic operations] to ensure simultaneous access to the same -//! memory location doesn't lead to undefined behavior. -//! -//! [prefetching]: https://en.wikipedia.org/wiki/Cache_prefetching -//! [compiler fences]: crate::sync::atomic::compiler_fence -//! [out-of-order]: https://en.wikipedia.org/wiki/Out-of-order_execution -//! [superscalar]: https://en.wikipedia.org/wiki/Superscalar_processor -//! [memory fences]: crate::sync::atomic::fence -//! [atomic operations]: crate::sync::atomic -//! -//! ## Higher-level synchronization objects -//! -//! Most of the low-level synchronization primitives are quite error-prone and -//! inconvenient to use, which is why the standard library also exposes some -//! higher-level synchronization objects. -//! -//! These abstractions can be built out of lower-level primitives. -//! For efficiency, the sync objects in the standard library are usually -//! implemented with help from the operating system's kernel, which is -//! able to reschedule the threads while they are blocked on acquiring -//! a lock. -//! -//! The following is an overview of the available synchronization -//! objects: -//! -//! - [`Arc`]: Atomically Reference-Counted pointer, which can be used -//! in multithreaded environments to prolong the lifetime of some -//! data until all the threads have finished using it. -//! -//! - [`Barrier`]: Ensures multiple threads will wait for each other -//! to reach a point in the program, before continuing execution all -//! together. -//! -//! - [`Condvar`]: Condition Variable, providing the ability to block -//! a thread while waiting for an event to occur. -//! -//! - [`mpsc`]: Multi-producer, single-consumer queues, used for -//! message-based communication. Can provide a lightweight -//! inter-thread synchronisation mechanism, at the cost of some -//! extra memory. -//! -//! - [`Mutex`]: Mutual Exclusion mechanism, which ensures that at -//! most one thread at a time is able to access some data. -//! -//! - [`Once`]: Used for a thread-safe, one-time global initialization routine -//! -//! - [`OnceLock`]: Used for thread-safe, one-time initialization of a -//! global variable. -//! -//! - [`RwLock`]: Provides a mutual exclusion mechanism which allows -//! multiple readers at the same time, while allowing only one -//! writer at a time. In some cases, this can be more efficient than -//! a mutex. -//! -//! [`Arc`]: crate::sync::Arc -//! [`Barrier`]: crate::sync::Barrier -//! [`Condvar`]: crate::sync::Condvar -//! [`mpsc`]: crate::sync::mpsc -//! [`Mutex`]: crate::sync::Mutex -//! [`Once`]: crate::sync::Once -//! [`OnceLock`]: crate::sync::OnceLock -//! [`RwLock`]: crate::sync::RwLock - -#![stable(feature = "rust1", since = "1.0.0")] - -#[stable(feature = "rust1", since = "1.0.0")] -pub use alloc_crate::sync::{Arc, Weak}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::sync::atomic; -#[unstable(feature = "exclusive_wrapper", issue = "98407")] -pub use core::sync::Exclusive; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::barrier::{Barrier, BarrierWaitResult}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::condvar::{Condvar, WaitTimeoutResult}; -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -pub use self::mutex::MappedMutexGuard; -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::mutex::{Mutex, MutexGuard}; -#[stable(feature = "rust1", since = "1.0.0")] -#[allow(deprecated)] -pub use self::once::{Once, OnceState, ONCE_INIT}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::poison::{LockResult, PoisonError, TryLockError, TryLockResult}; -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -pub use self::rwlock::{MappedRwLockReadGuard, MappedRwLockWriteGuard}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::rwlock::{RwLock, RwLockReadGuard, RwLockWriteGuard}; - -#[unstable(feature = "lazy_cell", issue = "109736")] -pub use self::lazy_lock::LazyLock; -#[stable(feature = "once_cell", since = "1.70.0")] -pub use self::once_lock::OnceLock; - -#[unstable(feature = "reentrant_lock", issue = "121440")] -pub use self::reentrant_lock::{ReentrantLock, ReentrantLockGuard}; - -pub mod mpsc; - -mod barrier; -mod condvar; -mod lazy_lock; -mod mpmc; -mod mutex; -pub(crate) mod once; -mod once_lock; -mod poison; -mod reentrant_lock; -mod rwlock; diff --git a/library/std/src/sync/mpmc/array.rs b/library/std/src/sync/mpmc/array.rs deleted file mode 100644 index 492e21d9bdb63..0000000000000 --- a/library/std/src/sync/mpmc/array.rs +++ /dev/null @@ -1,564 +0,0 @@ -//! Bounded channel based on a preallocated array. -//! -//! This flavor has a fixed, positive capacity. -//! -//! The implementation is based on Dmitry Vyukov's bounded MPMC queue. -//! -//! Source: -//! - -//! - - -use super::context::Context; -use super::error::*; -use super::select::{Operation, Selected, Token}; -use super::utils::{Backoff, CachePadded}; -use super::waker::SyncWaker; - -use crate::cell::UnsafeCell; -use crate::mem::MaybeUninit; -use crate::ptr; -use crate::sync::atomic::{self, AtomicUsize, Ordering}; -use crate::time::Instant; - -/// A slot in a channel. -struct Slot { - /// The current stamp. - stamp: AtomicUsize, - - /// The message in this slot. Either read out in `read` or dropped through - /// `discard_all_messages`. - msg: UnsafeCell>, -} - -/// The token type for the array flavor. -#[derive(Debug)] -pub(crate) struct ArrayToken { - /// Slot to read from or write to. - slot: *const u8, - - /// Stamp to store into the slot after reading or writing. - stamp: usize, -} - -impl Default for ArrayToken { - #[inline] - fn default() -> Self { - ArrayToken { slot: ptr::null(), stamp: 0 } - } -} - -/// Bounded channel based on a preallocated array. -pub(crate) struct Channel { - /// The head of the channel. - /// - /// This value is a "stamp" consisting of an index into the buffer, a mark bit, and a lap, but - /// packed into a single `usize`. The lower bits represent the index, while the upper bits - /// represent the lap. The mark bit in the head is always zero. - /// - /// Messages are popped from the head of the channel. - head: CachePadded, - - /// The tail of the channel. - /// - /// This value is a "stamp" consisting of an index into the buffer, a mark bit, and a lap, but - /// packed into a single `usize`. The lower bits represent the index, while the upper bits - /// represent the lap. The mark bit indicates that the channel is disconnected. - /// - /// Messages are pushed into the tail of the channel. - tail: CachePadded, - - /// The buffer holding slots. - buffer: Box<[Slot]>, - - /// The channel capacity. - cap: usize, - - /// A stamp with the value of `{ lap: 1, mark: 0, index: 0 }`. - one_lap: usize, - - /// If this bit is set in the tail, that means the channel is disconnected. - mark_bit: usize, - - /// Senders waiting while the channel is full. - senders: SyncWaker, - - /// Receivers waiting while the channel is empty and not disconnected. - receivers: SyncWaker, -} - -impl Channel { - /// Creates a bounded channel of capacity `cap`. - pub(crate) fn with_capacity(cap: usize) -> Self { - assert!(cap > 0, "capacity must be positive"); - - // Compute constants `mark_bit` and `one_lap`. - let mark_bit = (cap + 1).next_power_of_two(); - let one_lap = mark_bit * 2; - - // Head is initialized to `{ lap: 0, mark: 0, index: 0 }`. - let head = 0; - // Tail is initialized to `{ lap: 0, mark: 0, index: 0 }`. - let tail = 0; - - // Allocate a buffer of `cap` slots initialized - // with stamps. - let buffer: Box<[Slot]> = (0..cap) - .map(|i| { - // Set the stamp to `{ lap: 0, mark: 0, index: i }`. - Slot { stamp: AtomicUsize::new(i), msg: UnsafeCell::new(MaybeUninit::uninit()) } - }) - .collect(); - - Channel { - buffer, - cap, - one_lap, - mark_bit, - head: CachePadded::new(AtomicUsize::new(head)), - tail: CachePadded::new(AtomicUsize::new(tail)), - senders: SyncWaker::new(), - receivers: SyncWaker::new(), - } - } - - /// Attempts to reserve a slot for sending a message. - fn start_send(&self, token: &mut Token) -> bool { - let backoff = Backoff::new(); - let mut tail = self.tail.load(Ordering::Relaxed); - - loop { - // Check if the channel is disconnected. - if tail & self.mark_bit != 0 { - token.array.slot = ptr::null(); - token.array.stamp = 0; - return true; - } - - // Deconstruct the tail. - let index = tail & (self.mark_bit - 1); - let lap = tail & !(self.one_lap - 1); - - // Inspect the corresponding slot. - debug_assert!(index < self.buffer.len()); - let slot = unsafe { self.buffer.get_unchecked(index) }; - let stamp = slot.stamp.load(Ordering::Acquire); - - // If the tail and the stamp match, we may attempt to push. - if tail == stamp { - let new_tail = if index + 1 < self.cap { - // Same lap, incremented index. - // Set to `{ lap: lap, mark: 0, index: index + 1 }`. - tail + 1 - } else { - // One lap forward, index wraps around to zero. - // Set to `{ lap: lap.wrapping_add(1), mark: 0, index: 0 }`. - lap.wrapping_add(self.one_lap) - }; - - // Try moving the tail. - match self.tail.compare_exchange_weak( - tail, - new_tail, - Ordering::SeqCst, - Ordering::Relaxed, - ) { - Ok(_) => { - // Prepare the token for the follow-up call to `write`. - token.array.slot = slot as *const Slot as *const u8; - token.array.stamp = tail + 1; - return true; - } - Err(_) => { - backoff.spin_light(); - tail = self.tail.load(Ordering::Relaxed); - } - } - } else if stamp.wrapping_add(self.one_lap) == tail + 1 { - atomic::fence(Ordering::SeqCst); - let head = self.head.load(Ordering::Relaxed); - - // If the head lags one lap behind the tail as well... - if head.wrapping_add(self.one_lap) == tail { - // ...then the channel is full. - return false; - } - - backoff.spin_light(); - tail = self.tail.load(Ordering::Relaxed); - } else { - // Snooze because we need to wait for the stamp to get updated. - backoff.spin_heavy(); - tail = self.tail.load(Ordering::Relaxed); - } - } - } - - /// Writes a message into the channel. - pub(crate) unsafe fn write(&self, token: &mut Token, msg: T) -> Result<(), T> { - // If there is no slot, the channel is disconnected. - if token.array.slot.is_null() { - return Err(msg); - } - - let slot: &Slot = &*(token.array.slot as *const Slot); - - // Write the message into the slot and update the stamp. - slot.msg.get().write(MaybeUninit::new(msg)); - slot.stamp.store(token.array.stamp, Ordering::Release); - - // Wake a sleeping receiver. - self.receivers.notify(); - Ok(()) - } - - /// Attempts to reserve a slot for receiving a message. - fn start_recv(&self, token: &mut Token) -> bool { - let backoff = Backoff::new(); - let mut head = self.head.load(Ordering::Relaxed); - - loop { - // Deconstruct the head. - let index = head & (self.mark_bit - 1); - let lap = head & !(self.one_lap - 1); - - // Inspect the corresponding slot. - debug_assert!(index < self.buffer.len()); - let slot = unsafe { self.buffer.get_unchecked(index) }; - let stamp = slot.stamp.load(Ordering::Acquire); - - // If the stamp is ahead of the head by 1, we may attempt to pop. - if head + 1 == stamp { - let new = if index + 1 < self.cap { - // Same lap, incremented index. - // Set to `{ lap: lap, mark: 0, index: index + 1 }`. - head + 1 - } else { - // One lap forward, index wraps around to zero. - // Set to `{ lap: lap.wrapping_add(1), mark: 0, index: 0 }`. - lap.wrapping_add(self.one_lap) - }; - - // Try moving the head. - match self.head.compare_exchange_weak( - head, - new, - Ordering::SeqCst, - Ordering::Relaxed, - ) { - Ok(_) => { - // Prepare the token for the follow-up call to `read`. - token.array.slot = slot as *const Slot as *const u8; - token.array.stamp = head.wrapping_add(self.one_lap); - return true; - } - Err(_) => { - backoff.spin_light(); - head = self.head.load(Ordering::Relaxed); - } - } - } else if stamp == head { - atomic::fence(Ordering::SeqCst); - let tail = self.tail.load(Ordering::Relaxed); - - // If the tail equals the head, that means the channel is empty. - if (tail & !self.mark_bit) == head { - // If the channel is disconnected... - if tail & self.mark_bit != 0 { - // ...then receive an error. - token.array.slot = ptr::null(); - token.array.stamp = 0; - return true; - } else { - // Otherwise, the receive operation is not ready. - return false; - } - } - - backoff.spin_light(); - head = self.head.load(Ordering::Relaxed); - } else { - // Snooze because we need to wait for the stamp to get updated. - backoff.spin_heavy(); - head = self.head.load(Ordering::Relaxed); - } - } - } - - /// Reads a message from the channel. - pub(crate) unsafe fn read(&self, token: &mut Token) -> Result { - if token.array.slot.is_null() { - // The channel is disconnected. - return Err(()); - } - - let slot: &Slot = &*(token.array.slot as *const Slot); - - // Read the message from the slot and update the stamp. - let msg = slot.msg.get().read().assume_init(); - slot.stamp.store(token.array.stamp, Ordering::Release); - - // Wake a sleeping sender. - self.senders.notify(); - Ok(msg) - } - - /// Attempts to send a message into the channel. - pub(crate) fn try_send(&self, msg: T) -> Result<(), TrySendError> { - let token = &mut Token::default(); - if self.start_send(token) { - unsafe { self.write(token, msg).map_err(TrySendError::Disconnected) } - } else { - Err(TrySendError::Full(msg)) - } - } - - /// Sends a message into the channel. - pub(crate) fn send( - &self, - msg: T, - deadline: Option, - ) -> Result<(), SendTimeoutError> { - let token = &mut Token::default(); - loop { - // Try sending a message. - if self.start_send(token) { - let res = unsafe { self.write(token, msg) }; - return res.map_err(SendTimeoutError::Disconnected); - } - - if let Some(d) = deadline { - if Instant::now() >= d { - return Err(SendTimeoutError::Timeout(msg)); - } - } - - Context::with(|cx| { - // Prepare for blocking until a receiver wakes us up. - let oper = Operation::hook(token); - self.senders.register(oper, cx); - - // Has the channel become ready just now? - if !self.is_full() || self.is_disconnected() { - let _ = cx.try_select(Selected::Aborted); - } - - // Block the current thread. - let sel = cx.wait_until(deadline); - - match sel { - Selected::Waiting => unreachable!(), - Selected::Aborted | Selected::Disconnected => { - self.senders.unregister(oper).unwrap(); - } - Selected::Operation(_) => {} - } - }); - } - } - - /// Attempts to receive a message without blocking. - pub(crate) fn try_recv(&self) -> Result { - let token = &mut Token::default(); - - if self.start_recv(token) { - unsafe { self.read(token).map_err(|_| TryRecvError::Disconnected) } - } else { - Err(TryRecvError::Empty) - } - } - - /// Receives a message from the channel. - pub(crate) fn recv(&self, deadline: Option) -> Result { - let token = &mut Token::default(); - loop { - // Try receiving a message. - if self.start_recv(token) { - let res = unsafe { self.read(token) }; - return res.map_err(|_| RecvTimeoutError::Disconnected); - } - - if let Some(d) = deadline { - if Instant::now() >= d { - return Err(RecvTimeoutError::Timeout); - } - } - - Context::with(|cx| { - // Prepare for blocking until a sender wakes us up. - let oper = Operation::hook(token); - self.receivers.register(oper, cx); - - // Has the channel become ready just now? - if !self.is_empty() || self.is_disconnected() { - let _ = cx.try_select(Selected::Aborted); - } - - // Block the current thread. - let sel = cx.wait_until(deadline); - - match sel { - Selected::Waiting => unreachable!(), - Selected::Aborted | Selected::Disconnected => { - self.receivers.unregister(oper).unwrap(); - // If the channel was disconnected, we still have to check for remaining - // messages. - } - Selected::Operation(_) => {} - } - }); - } - } - - /// Returns the current number of messages inside the channel. - pub(crate) fn len(&self) -> usize { - loop { - // Load the tail, then load the head. - let tail = self.tail.load(Ordering::SeqCst); - let head = self.head.load(Ordering::SeqCst); - - // If the tail didn't change, we've got consistent values to work with. - if self.tail.load(Ordering::SeqCst) == tail { - let hix = head & (self.mark_bit - 1); - let tix = tail & (self.mark_bit - 1); - - return if hix < tix { - tix - hix - } else if hix > tix { - self.cap - hix + tix - } else if (tail & !self.mark_bit) == head { - 0 - } else { - self.cap - }; - } - } - } - - /// Returns the capacity of the channel. - #[allow(clippy::unnecessary_wraps)] // This is intentional. - pub(crate) fn capacity(&self) -> Option { - Some(self.cap) - } - - /// Disconnects senders and wakes up all blocked receivers. - /// - /// Returns `true` if this call disconnected the channel. - pub(crate) fn disconnect_senders(&self) -> bool { - let tail = self.tail.fetch_or(self.mark_bit, Ordering::SeqCst); - - if tail & self.mark_bit == 0 { - self.receivers.disconnect(); - true - } else { - false - } - } - - /// Disconnects receivers and wakes up all blocked senders. - /// - /// Returns `true` if this call disconnected the channel. - /// - /// # Safety - /// May only be called once upon dropping the last receiver. The - /// destruction of all other receivers must have been observed with acquire - /// ordering or stronger. - pub(crate) unsafe fn disconnect_receivers(&self) -> bool { - let tail = self.tail.fetch_or(self.mark_bit, Ordering::SeqCst); - let disconnected = if tail & self.mark_bit == 0 { - self.senders.disconnect(); - true - } else { - false - }; - - self.discard_all_messages(tail); - disconnected - } - - /// Discards all messages. - /// - /// `tail` should be the current (and therefore last) value of `tail`. - /// - /// # Panicking - /// If a destructor panics, the remaining messages are leaked, matching the - /// behaviour of the unbounded channel. - /// - /// # Safety - /// This method must only be called when dropping the last receiver. The - /// destruction of all other receivers must have been observed with acquire - /// ordering or stronger. - unsafe fn discard_all_messages(&self, tail: usize) { - debug_assert!(self.is_disconnected()); - - // Only receivers modify `head`, so since we are the last one, - // this value will not change and will not be observed (since - // no new messages can be sent after disconnection). - let mut head = self.head.load(Ordering::Relaxed); - let tail = tail & !self.mark_bit; - - let backoff = Backoff::new(); - loop { - // Deconstruct the head. - let index = head & (self.mark_bit - 1); - let lap = head & !(self.one_lap - 1); - - // Inspect the corresponding slot. - debug_assert!(index < self.buffer.len()); - let slot = unsafe { self.buffer.get_unchecked(index) }; - let stamp = slot.stamp.load(Ordering::Acquire); - - // If the stamp is ahead of the head by 1, we may drop the message. - if head + 1 == stamp { - head = if index + 1 < self.cap { - // Same lap, incremented index. - // Set to `{ lap: lap, mark: 0, index: index + 1 }`. - head + 1 - } else { - // One lap forward, index wraps around to zero. - // Set to `{ lap: lap.wrapping_add(1), mark: 0, index: 0 }`. - lap.wrapping_add(self.one_lap) - }; - - unsafe { - (*slot.msg.get()).assume_init_drop(); - } - // If the tail equals the head, that means the channel is empty. - } else if tail == head { - return; - // Otherwise, a sender is about to write into the slot, so we need - // to wait for it to update the stamp. - } else { - backoff.spin_heavy(); - } - } - } - - /// Returns `true` if the channel is disconnected. - pub(crate) fn is_disconnected(&self) -> bool { - self.tail.load(Ordering::SeqCst) & self.mark_bit != 0 - } - - /// Returns `true` if the channel is empty. - pub(crate) fn is_empty(&self) -> bool { - let head = self.head.load(Ordering::SeqCst); - let tail = self.tail.load(Ordering::SeqCst); - - // Is the tail equal to the head? - // - // Note: If the head changes just before we load the tail, that means there was a moment - // when the channel was not empty, so it is safe to just return `false`. - (tail & !self.mark_bit) == head - } - - /// Returns `true` if the channel is full. - pub(crate) fn is_full(&self) -> bool { - let tail = self.tail.load(Ordering::SeqCst); - let head = self.head.load(Ordering::SeqCst); - - // Is the head lagging one lap behind tail? - // - // Note: If the tail changes just before we load the head, that means there was a moment - // when the channel was not full, so it is safe to just return `false`. - head.wrapping_add(self.one_lap) == tail & !self.mark_bit - } -} diff --git a/library/std/src/sync/mpmc/context.rs b/library/std/src/sync/mpmc/context.rs deleted file mode 100644 index bbfc6ce00ffc2..0000000000000 --- a/library/std/src/sync/mpmc/context.rs +++ /dev/null @@ -1,155 +0,0 @@ -//! Thread-local channel context. - -use super::select::Selected; -use super::waker::current_thread_id; - -use crate::cell::Cell; -use crate::ptr; -use crate::sync::atomic::{AtomicPtr, AtomicUsize, Ordering}; -use crate::sync::Arc; -use crate::thread::{self, Thread}; -use crate::time::Instant; - -/// Thread-local context. -#[derive(Debug, Clone)] -pub struct Context { - inner: Arc, -} - -/// Inner representation of `Context`. -#[derive(Debug)] -struct Inner { - /// Selected operation. - select: AtomicUsize, - - /// A slot into which another thread may store a pointer to its `Packet`. - packet: AtomicPtr<()>, - - /// Thread handle. - thread: Thread, - - /// Thread id. - thread_id: usize, -} - -impl Context { - /// Creates a new context for the duration of the closure. - #[inline] - pub fn with(f: F) -> R - where - F: FnOnce(&Context) -> R, - { - thread_local! { - /// Cached thread-local context. - static CONTEXT: Cell> = Cell::new(Some(Context::new())); - } - - let mut f = Some(f); - let mut f = |cx: &Context| -> R { - let f = f.take().unwrap(); - f(cx) - }; - - CONTEXT - .try_with(|cell| match cell.take() { - None => f(&Context::new()), - Some(cx) => { - cx.reset(); - let res = f(&cx); - cell.set(Some(cx)); - res - } - }) - .unwrap_or_else(|_| f(&Context::new())) - } - - /// Creates a new `Context`. - #[cold] - fn new() -> Context { - Context { - inner: Arc::new(Inner { - select: AtomicUsize::new(Selected::Waiting.into()), - packet: AtomicPtr::new(ptr::null_mut()), - thread: thread::current(), - thread_id: current_thread_id(), - }), - } - } - - /// Resets `select` and `packet`. - #[inline] - fn reset(&self) { - self.inner.select.store(Selected::Waiting.into(), Ordering::Release); - self.inner.packet.store(ptr::null_mut(), Ordering::Release); - } - - /// Attempts to select an operation. - /// - /// On failure, the previously selected operation is returned. - #[inline] - pub fn try_select(&self, select: Selected) -> Result<(), Selected> { - self.inner - .select - .compare_exchange( - Selected::Waiting.into(), - select.into(), - Ordering::AcqRel, - Ordering::Acquire, - ) - .map(|_| ()) - .map_err(|e| e.into()) - } - - /// Stores a packet. - /// - /// This method must be called after `try_select` succeeds and there is a packet to provide. - #[inline] - pub fn store_packet(&self, packet: *mut ()) { - if !packet.is_null() { - self.inner.packet.store(packet, Ordering::Release); - } - } - - /// Waits until an operation is selected and returns it. - /// - /// If the deadline is reached, `Selected::Aborted` will be selected. - #[inline] - pub fn wait_until(&self, deadline: Option) -> Selected { - loop { - // Check whether an operation has been selected. - let sel = Selected::from(self.inner.select.load(Ordering::Acquire)); - if sel != Selected::Waiting { - return sel; - } - - // If there's a deadline, park the current thread until the deadline is reached. - if let Some(end) = deadline { - let now = Instant::now(); - - if now < end { - thread::park_timeout(end - now); - } else { - // The deadline has been reached. Try aborting select. - return match self.try_select(Selected::Aborted) { - Ok(()) => Selected::Aborted, - Err(s) => s, - }; - } - } else { - thread::park(); - } - } - } - - /// Unparks the thread this context belongs to. - #[inline] - pub fn unpark(&self) { - self.inner.thread.unpark(); - } - - /// Returns the id of the thread this context belongs to. - #[inline] - pub fn thread_id(&self) -> usize { - self.inner.thread_id - } -} diff --git a/library/std/src/sync/mpmc/counter.rs b/library/std/src/sync/mpmc/counter.rs deleted file mode 100644 index a5a6bdc67f13f..0000000000000 --- a/library/std/src/sync/mpmc/counter.rs +++ /dev/null @@ -1,137 +0,0 @@ -use crate::ops; -use crate::process; -use crate::sync::atomic::{AtomicBool, AtomicUsize, Ordering}; - -/// Reference counter internals. -struct Counter { - /// The number of senders associated with the channel. - senders: AtomicUsize, - - /// The number of receivers associated with the channel. - receivers: AtomicUsize, - - /// Set to `true` if the last sender or the last receiver reference deallocates the channel. - destroy: AtomicBool, - - /// The internal channel. - chan: C, -} - -/// Wraps a channel into the reference counter. -pub(crate) fn new(chan: C) -> (Sender, Receiver) { - let counter = Box::into_raw(Box::new(Counter { - senders: AtomicUsize::new(1), - receivers: AtomicUsize::new(1), - destroy: AtomicBool::new(false), - chan, - })); - let s = Sender { counter }; - let r = Receiver { counter }; - (s, r) -} - -/// The sending side. -pub(crate) struct Sender { - counter: *mut Counter, -} - -impl Sender { - /// Returns the internal `Counter`. - fn counter(&self) -> &Counter { - unsafe { &*self.counter } - } - - /// Acquires another sender reference. - pub(crate) fn acquire(&self) -> Sender { - let count = self.counter().senders.fetch_add(1, Ordering::Relaxed); - - // Cloning senders and calling `mem::forget` on the clones could potentially overflow the - // counter. It's very difficult to recover sensibly from such degenerate scenarios so we - // just abort when the count becomes very large. - if count > isize::MAX as usize { - process::abort(); - } - - Sender { counter: self.counter } - } - - /// Releases the sender reference. - /// - /// Function `disconnect` will be called if this is the last sender reference. - pub(crate) unsafe fn release bool>(&self, disconnect: F) { - if self.counter().senders.fetch_sub(1, Ordering::AcqRel) == 1 { - disconnect(&self.counter().chan); - - if self.counter().destroy.swap(true, Ordering::AcqRel) { - drop(Box::from_raw(self.counter)); - } - } - } -} - -impl ops::Deref for Sender { - type Target = C; - - fn deref(&self) -> &C { - &self.counter().chan - } -} - -impl PartialEq for Sender { - fn eq(&self, other: &Sender) -> bool { - self.counter == other.counter - } -} - -/// The receiving side. -pub(crate) struct Receiver { - counter: *mut Counter, -} - -impl Receiver { - /// Returns the internal `Counter`. - fn counter(&self) -> &Counter { - unsafe { &*self.counter } - } - - /// Acquires another receiver reference. - pub(crate) fn acquire(&self) -> Receiver { - let count = self.counter().receivers.fetch_add(1, Ordering::Relaxed); - - // Cloning receivers and calling `mem::forget` on the clones could potentially overflow the - // counter. It's very difficult to recover sensibly from such degenerate scenarios so we - // just abort when the count becomes very large. - if count > isize::MAX as usize { - process::abort(); - } - - Receiver { counter: self.counter } - } - - /// Releases the receiver reference. - /// - /// Function `disconnect` will be called if this is the last receiver reference. - pub(crate) unsafe fn release bool>(&self, disconnect: F) { - if self.counter().receivers.fetch_sub(1, Ordering::AcqRel) == 1 { - disconnect(&self.counter().chan); - - if self.counter().destroy.swap(true, Ordering::AcqRel) { - drop(Box::from_raw(self.counter)); - } - } - } -} - -impl ops::Deref for Receiver { - type Target = C; - - fn deref(&self) -> &C { - &self.counter().chan - } -} - -impl PartialEq for Receiver { - fn eq(&self, other: &Receiver) -> bool { - self.counter == other.counter - } -} diff --git a/library/std/src/sync/mpmc/error.rs b/library/std/src/sync/mpmc/error.rs deleted file mode 100644 index 33b2bff853498..0000000000000 --- a/library/std/src/sync/mpmc/error.rs +++ /dev/null @@ -1,46 +0,0 @@ -use crate::error; -use crate::fmt; - -pub use crate::sync::mpsc::{RecvError, RecvTimeoutError, SendError, TryRecvError, TrySendError}; - -/// An error returned from the [`send_timeout`] method. -/// -/// The error contains the message being sent so it can be recovered. -/// -/// [`send_timeout`]: super::Sender::send_timeout -#[derive(PartialEq, Eq, Clone, Copy)] -pub enum SendTimeoutError { - /// The message could not be sent because the channel is full and the operation timed out. - /// - /// If this is a zero-capacity channel, then the error indicates that there was no receiver - /// available to receive the message and the operation timed out. - Timeout(T), - - /// The message could not be sent because the channel is disconnected. - Disconnected(T), -} - -impl fmt::Debug for SendTimeoutError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - "SendTimeoutError(..)".fmt(f) - } -} - -impl fmt::Display for SendTimeoutError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - match *self { - SendTimeoutError::Timeout(..) => "timed out waiting on send operation".fmt(f), - SendTimeoutError::Disconnected(..) => "sending on a disconnected channel".fmt(f), - } - } -} - -impl error::Error for SendTimeoutError {} - -impl From> for SendTimeoutError { - fn from(err: SendError) -> SendTimeoutError { - match err { - SendError(e) => SendTimeoutError::Disconnected(e), - } - } -} diff --git a/library/std/src/sync/mpmc/list.rs b/library/std/src/sync/mpmc/list.rs deleted file mode 100644 index 9e7148c716cda..0000000000000 --- a/library/std/src/sync/mpmc/list.rs +++ /dev/null @@ -1,653 +0,0 @@ -//! Unbounded channel implemented as a linked list. - -use super::context::Context; -use super::error::*; -use super::select::{Operation, Selected, Token}; -use super::utils::{Backoff, CachePadded}; -use super::waker::SyncWaker; - -use crate::cell::UnsafeCell; -use crate::marker::PhantomData; -use crate::mem::MaybeUninit; -use crate::ptr; -use crate::sync::atomic::{self, AtomicPtr, AtomicUsize, Ordering}; -use crate::time::Instant; - -// Bits indicating the state of a slot: -// * If a message has been written into the slot, `WRITE` is set. -// * If a message has been read from the slot, `READ` is set. -// * If the block is being destroyed, `DESTROY` is set. -const WRITE: usize = 1; -const READ: usize = 2; -const DESTROY: usize = 4; - -// Each block covers one "lap" of indices. -const LAP: usize = 32; -// The maximum number of messages a block can hold. -const BLOCK_CAP: usize = LAP - 1; -// How many lower bits are reserved for metadata. -const SHIFT: usize = 1; -// Has two different purposes: -// * If set in head, indicates that the block is not the last one. -// * If set in tail, indicates that the channel is disconnected. -const MARK_BIT: usize = 1; - -/// A slot in a block. -struct Slot { - /// The message. - msg: UnsafeCell>, - - /// The state of the slot. - state: AtomicUsize, -} - -impl Slot { - /// Waits until a message is written into the slot. - fn wait_write(&self) { - let backoff = Backoff::new(); - while self.state.load(Ordering::Acquire) & WRITE == 0 { - backoff.spin_heavy(); - } - } -} - -/// A block in a linked list. -/// -/// Each block in the list can hold up to `BLOCK_CAP` messages. -struct Block { - /// The next block in the linked list. - next: AtomicPtr>, - - /// Slots for messages. - slots: [Slot; BLOCK_CAP], -} - -impl Block { - /// Creates an empty block. - fn new() -> Block { - // SAFETY: This is safe because: - // [1] `Block::next` (AtomicPtr) may be safely zero initialized. - // [2] `Block::slots` (Array) may be safely zero initialized because of [3, 4]. - // [3] `Slot::msg` (UnsafeCell) may be safely zero initialized because it - // holds a MaybeUninit. - // [4] `Slot::state` (AtomicUsize) may be safely zero initialized. - unsafe { MaybeUninit::zeroed().assume_init() } - } - - /// Waits until the next pointer is set. - fn wait_next(&self) -> *mut Block { - let backoff = Backoff::new(); - loop { - let next = self.next.load(Ordering::Acquire); - if !next.is_null() { - return next; - } - backoff.spin_heavy(); - } - } - - /// Sets the `DESTROY` bit in slots starting from `start` and destroys the block. - unsafe fn destroy(this: *mut Block, start: usize) { - // It is not necessary to set the `DESTROY` bit in the last slot because that slot has - // begun destruction of the block. - for i in start..BLOCK_CAP - 1 { - let slot = (*this).slots.get_unchecked(i); - - // Mark the `DESTROY` bit if a thread is still using the slot. - if slot.state.load(Ordering::Acquire) & READ == 0 - && slot.state.fetch_or(DESTROY, Ordering::AcqRel) & READ == 0 - { - // If a thread is still using the slot, it will continue destruction of the block. - return; - } - } - - // No thread is using the block, now it is safe to destroy it. - drop(Box::from_raw(this)); - } -} - -/// A position in a channel. -#[derive(Debug)] -struct Position { - /// The index in the channel. - index: AtomicUsize, - - /// The block in the linked list. - block: AtomicPtr>, -} - -/// The token type for the list flavor. -#[derive(Debug)] -pub(crate) struct ListToken { - /// The block of slots. - block: *const u8, - - /// The offset into the block. - offset: usize, -} - -impl Default for ListToken { - #[inline] - fn default() -> Self { - ListToken { block: ptr::null(), offset: 0 } - } -} - -/// Unbounded channel implemented as a linked list. -/// -/// Each message sent into the channel is assigned a sequence number, i.e. an index. Indices are -/// represented as numbers of type `usize` and wrap on overflow. -/// -/// Consecutive messages are grouped into blocks in order to put less pressure on the allocator and -/// improve cache efficiency. -pub(crate) struct Channel { - /// The head of the channel. - head: CachePadded>, - - /// The tail of the channel. - tail: CachePadded>, - - /// Receivers waiting while the channel is empty and not disconnected. - receivers: SyncWaker, - - /// Indicates that dropping a `Channel` may drop messages of type `T`. - _marker: PhantomData, -} - -impl Channel { - /// Creates a new unbounded channel. - pub(crate) fn new() -> Self { - Channel { - head: CachePadded::new(Position { - block: AtomicPtr::new(ptr::null_mut()), - index: AtomicUsize::new(0), - }), - tail: CachePadded::new(Position { - block: AtomicPtr::new(ptr::null_mut()), - index: AtomicUsize::new(0), - }), - receivers: SyncWaker::new(), - _marker: PhantomData, - } - } - - /// Attempts to reserve a slot for sending a message. - fn start_send(&self, token: &mut Token) -> bool { - let backoff = Backoff::new(); - let mut tail = self.tail.index.load(Ordering::Acquire); - let mut block = self.tail.block.load(Ordering::Acquire); - let mut next_block = None; - - loop { - // Check if the channel is disconnected. - if tail & MARK_BIT != 0 { - token.list.block = ptr::null(); - return true; - } - - // Calculate the offset of the index into the block. - let offset = (tail >> SHIFT) % LAP; - - // If we reached the end of the block, wait until the next one is installed. - if offset == BLOCK_CAP { - backoff.spin_heavy(); - tail = self.tail.index.load(Ordering::Acquire); - block = self.tail.block.load(Ordering::Acquire); - continue; - } - - // If we're going to have to install the next block, allocate it in advance in order to - // make the wait for other threads as short as possible. - if offset + 1 == BLOCK_CAP && next_block.is_none() { - next_block = Some(Box::new(Block::::new())); - } - - // If this is the first message to be sent into the channel, we need to allocate the - // first block and install it. - if block.is_null() { - let new = Box::into_raw(Box::new(Block::::new())); - - if self - .tail - .block - .compare_exchange(block, new, Ordering::Release, Ordering::Relaxed) - .is_ok() - { - self.head.block.store(new, Ordering::Release); - block = new; - } else { - next_block = unsafe { Some(Box::from_raw(new)) }; - tail = self.tail.index.load(Ordering::Acquire); - block = self.tail.block.load(Ordering::Acquire); - continue; - } - } - - let new_tail = tail + (1 << SHIFT); - - // Try advancing the tail forward. - match self.tail.index.compare_exchange_weak( - tail, - new_tail, - Ordering::SeqCst, - Ordering::Acquire, - ) { - Ok(_) => unsafe { - // If we've reached the end of the block, install the next one. - if offset + 1 == BLOCK_CAP { - let next_block = Box::into_raw(next_block.unwrap()); - self.tail.block.store(next_block, Ordering::Release); - self.tail.index.fetch_add(1 << SHIFT, Ordering::Release); - (*block).next.store(next_block, Ordering::Release); - } - - token.list.block = block as *const u8; - token.list.offset = offset; - return true; - }, - Err(_) => { - backoff.spin_light(); - tail = self.tail.index.load(Ordering::Acquire); - block = self.tail.block.load(Ordering::Acquire); - } - } - } - } - - /// Writes a message into the channel. - pub(crate) unsafe fn write(&self, token: &mut Token, msg: T) -> Result<(), T> { - // If there is no slot, the channel is disconnected. - if token.list.block.is_null() { - return Err(msg); - } - - // Write the message into the slot. - let block = token.list.block as *mut Block; - let offset = token.list.offset; - let slot = (*block).slots.get_unchecked(offset); - slot.msg.get().write(MaybeUninit::new(msg)); - slot.state.fetch_or(WRITE, Ordering::Release); - - // Wake a sleeping receiver. - self.receivers.notify(); - Ok(()) - } - - /// Attempts to reserve a slot for receiving a message. - fn start_recv(&self, token: &mut Token) -> bool { - let backoff = Backoff::new(); - let mut head = self.head.index.load(Ordering::Acquire); - let mut block = self.head.block.load(Ordering::Acquire); - - loop { - // Calculate the offset of the index into the block. - let offset = (head >> SHIFT) % LAP; - - // If we reached the end of the block, wait until the next one is installed. - if offset == BLOCK_CAP { - backoff.spin_heavy(); - head = self.head.index.load(Ordering::Acquire); - block = self.head.block.load(Ordering::Acquire); - continue; - } - - let mut new_head = head + (1 << SHIFT); - - if new_head & MARK_BIT == 0 { - atomic::fence(Ordering::SeqCst); - let tail = self.tail.index.load(Ordering::Relaxed); - - // If the tail equals the head, that means the channel is empty. - if head >> SHIFT == tail >> SHIFT { - // If the channel is disconnected... - if tail & MARK_BIT != 0 { - // ...then receive an error. - token.list.block = ptr::null(); - return true; - } else { - // Otherwise, the receive operation is not ready. - return false; - } - } - - // If head and tail are not in the same block, set `MARK_BIT` in head. - if (head >> SHIFT) / LAP != (tail >> SHIFT) / LAP { - new_head |= MARK_BIT; - } - } - - // The block can be null here only if the first message is being sent into the channel. - // In that case, just wait until it gets initialized. - if block.is_null() { - backoff.spin_heavy(); - head = self.head.index.load(Ordering::Acquire); - block = self.head.block.load(Ordering::Acquire); - continue; - } - - // Try moving the head index forward. - match self.head.index.compare_exchange_weak( - head, - new_head, - Ordering::SeqCst, - Ordering::Acquire, - ) { - Ok(_) => unsafe { - // If we've reached the end of the block, move to the next one. - if offset + 1 == BLOCK_CAP { - let next = (*block).wait_next(); - let mut next_index = (new_head & !MARK_BIT).wrapping_add(1 << SHIFT); - if !(*next).next.load(Ordering::Relaxed).is_null() { - next_index |= MARK_BIT; - } - - self.head.block.store(next, Ordering::Release); - self.head.index.store(next_index, Ordering::Release); - } - - token.list.block = block as *const u8; - token.list.offset = offset; - return true; - }, - Err(_) => { - backoff.spin_light(); - head = self.head.index.load(Ordering::Acquire); - block = self.head.block.load(Ordering::Acquire); - } - } - } - } - - /// Reads a message from the channel. - pub(crate) unsafe fn read(&self, token: &mut Token) -> Result { - if token.list.block.is_null() { - // The channel is disconnected. - return Err(()); - } - - // Read the message. - let block = token.list.block as *mut Block; - let offset = token.list.offset; - let slot = (*block).slots.get_unchecked(offset); - slot.wait_write(); - let msg = slot.msg.get().read().assume_init(); - - // Destroy the block if we've reached the end, or if another thread wanted to destroy but - // couldn't because we were busy reading from the slot. - if offset + 1 == BLOCK_CAP { - Block::destroy(block, 0); - } else if slot.state.fetch_or(READ, Ordering::AcqRel) & DESTROY != 0 { - Block::destroy(block, offset + 1); - } - - Ok(msg) - } - - /// Attempts to send a message into the channel. - pub(crate) fn try_send(&self, msg: T) -> Result<(), TrySendError> { - self.send(msg, None).map_err(|err| match err { - SendTimeoutError::Disconnected(msg) => TrySendError::Disconnected(msg), - SendTimeoutError::Timeout(_) => unreachable!(), - }) - } - - /// Sends a message into the channel. - pub(crate) fn send( - &self, - msg: T, - _deadline: Option, - ) -> Result<(), SendTimeoutError> { - let token = &mut Token::default(); - assert!(self.start_send(token)); - unsafe { self.write(token, msg).map_err(SendTimeoutError::Disconnected) } - } - - /// Attempts to receive a message without blocking. - pub(crate) fn try_recv(&self) -> Result { - let token = &mut Token::default(); - - if self.start_recv(token) { - unsafe { self.read(token).map_err(|_| TryRecvError::Disconnected) } - } else { - Err(TryRecvError::Empty) - } - } - - /// Receives a message from the channel. - pub(crate) fn recv(&self, deadline: Option) -> Result { - let token = &mut Token::default(); - loop { - if self.start_recv(token) { - unsafe { - return self.read(token).map_err(|_| RecvTimeoutError::Disconnected); - } - } - - if let Some(d) = deadline { - if Instant::now() >= d { - return Err(RecvTimeoutError::Timeout); - } - } - - // Prepare for blocking until a sender wakes us up. - Context::with(|cx| { - let oper = Operation::hook(token); - self.receivers.register(oper, cx); - - // Has the channel become ready just now? - if !self.is_empty() || self.is_disconnected() { - let _ = cx.try_select(Selected::Aborted); - } - - // Block the current thread. - let sel = cx.wait_until(deadline); - - match sel { - Selected::Waiting => unreachable!(), - Selected::Aborted | Selected::Disconnected => { - self.receivers.unregister(oper).unwrap(); - // If the channel was disconnected, we still have to check for remaining - // messages. - } - Selected::Operation(_) => {} - } - }); - } - } - - /// Returns the current number of messages inside the channel. - pub(crate) fn len(&self) -> usize { - loop { - // Load the tail index, then load the head index. - let mut tail = self.tail.index.load(Ordering::SeqCst); - let mut head = self.head.index.load(Ordering::SeqCst); - - // If the tail index didn't change, we've got consistent indices to work with. - if self.tail.index.load(Ordering::SeqCst) == tail { - // Erase the lower bits. - tail &= !((1 << SHIFT) - 1); - head &= !((1 << SHIFT) - 1); - - // Fix up indices if they fall onto block ends. - if (tail >> SHIFT) & (LAP - 1) == LAP - 1 { - tail = tail.wrapping_add(1 << SHIFT); - } - if (head >> SHIFT) & (LAP - 1) == LAP - 1 { - head = head.wrapping_add(1 << SHIFT); - } - - // Rotate indices so that head falls into the first block. - let lap = (head >> SHIFT) / LAP; - tail = tail.wrapping_sub((lap * LAP) << SHIFT); - head = head.wrapping_sub((lap * LAP) << SHIFT); - - // Remove the lower bits. - tail >>= SHIFT; - head >>= SHIFT; - - // Return the difference minus the number of blocks between tail and head. - return tail - head - tail / LAP; - } - } - } - - /// Returns the capacity of the channel. - pub(crate) fn capacity(&self) -> Option { - None - } - - /// Disconnects senders and wakes up all blocked receivers. - /// - /// Returns `true` if this call disconnected the channel. - pub(crate) fn disconnect_senders(&self) -> bool { - let tail = self.tail.index.fetch_or(MARK_BIT, Ordering::SeqCst); - - if tail & MARK_BIT == 0 { - self.receivers.disconnect(); - true - } else { - false - } - } - - /// Disconnects receivers. - /// - /// Returns `true` if this call disconnected the channel. - pub(crate) fn disconnect_receivers(&self) -> bool { - let tail = self.tail.index.fetch_or(MARK_BIT, Ordering::SeqCst); - - if tail & MARK_BIT == 0 { - // If receivers are dropped first, discard all messages to free - // memory eagerly. - self.discard_all_messages(); - true - } else { - false - } - } - - /// Discards all messages. - /// - /// This method should only be called when all receivers are dropped. - fn discard_all_messages(&self) { - let backoff = Backoff::new(); - let mut tail = self.tail.index.load(Ordering::Acquire); - loop { - let offset = (tail >> SHIFT) % LAP; - if offset != BLOCK_CAP { - break; - } - - // New updates to tail will be rejected by MARK_BIT and aborted unless it's - // at boundary. We need to wait for the updates take affect otherwise there - // can be memory leaks. - backoff.spin_heavy(); - tail = self.tail.index.load(Ordering::Acquire); - } - - let mut head = self.head.index.load(Ordering::Acquire); - // The channel may be uninitialized, so we have to swap to avoid overwriting any sender's attempts - // to initalize the first block before noticing that the receivers disconnected. Late allocations - // will be deallocated by the sender in Drop. - let mut block = self.head.block.swap(ptr::null_mut(), Ordering::AcqRel); - - // If we're going to be dropping messages we need to synchronize with initialization - if head >> SHIFT != tail >> SHIFT { - // The block can be null here only if a sender is in the process of initializing the - // channel while another sender managed to send a message by inserting it into the - // semi-initialized channel and advanced the tail. - // In that case, just wait until it gets initialized. - while block.is_null() { - backoff.spin_heavy(); - block = self.head.block.load(Ordering::Acquire); - } - } - - unsafe { - // Drop all messages between head and tail and deallocate the heap-allocated blocks. - while head >> SHIFT != tail >> SHIFT { - let offset = (head >> SHIFT) % LAP; - - if offset < BLOCK_CAP { - // Drop the message in the slot. - let slot = (*block).slots.get_unchecked(offset); - slot.wait_write(); - let p = &mut *slot.msg.get(); - p.as_mut_ptr().drop_in_place(); - } else { - (*block).wait_next(); - // Deallocate the block and move to the next one. - let next = (*block).next.load(Ordering::Acquire); - drop(Box::from_raw(block)); - block = next; - } - - head = head.wrapping_add(1 << SHIFT); - } - - // Deallocate the last remaining block. - if !block.is_null() { - drop(Box::from_raw(block)); - } - } - - head &= !MARK_BIT; - self.head.index.store(head, Ordering::Release); - } - - /// Returns `true` if the channel is disconnected. - pub(crate) fn is_disconnected(&self) -> bool { - self.tail.index.load(Ordering::SeqCst) & MARK_BIT != 0 - } - - /// Returns `true` if the channel is empty. - pub(crate) fn is_empty(&self) -> bool { - let head = self.head.index.load(Ordering::SeqCst); - let tail = self.tail.index.load(Ordering::SeqCst); - head >> SHIFT == tail >> SHIFT - } - - /// Returns `true` if the channel is full. - pub(crate) fn is_full(&self) -> bool { - false - } -} - -impl Drop for Channel { - fn drop(&mut self) { - let mut head = self.head.index.load(Ordering::Relaxed); - let mut tail = self.tail.index.load(Ordering::Relaxed); - let mut block = self.head.block.load(Ordering::Relaxed); - - // Erase the lower bits. - head &= !((1 << SHIFT) - 1); - tail &= !((1 << SHIFT) - 1); - - unsafe { - // Drop all messages between head and tail and deallocate the heap-allocated blocks. - while head != tail { - let offset = (head >> SHIFT) % LAP; - - if offset < BLOCK_CAP { - // Drop the message in the slot. - let slot = (*block).slots.get_unchecked(offset); - let p = &mut *slot.msg.get(); - p.as_mut_ptr().drop_in_place(); - } else { - // Deallocate the block and move to the next one. - let next = (*block).next.load(Ordering::Relaxed); - drop(Box::from_raw(block)); - block = next; - } - - head = head.wrapping_add(1 << SHIFT); - } - - // Deallocate the last remaining block. - if !block.is_null() { - drop(Box::from_raw(block)); - } - } - } -} diff --git a/library/std/src/sync/mpmc/mod.rs b/library/std/src/sync/mpmc/mod.rs deleted file mode 100644 index 2068dda393a2b..0000000000000 --- a/library/std/src/sync/mpmc/mod.rs +++ /dev/null @@ -1,430 +0,0 @@ -//! Multi-producer multi-consumer channels. - -// This module is not currently exposed publicly, but is used -// as the implementation for the channels in `sync::mpsc`. The -// implementation comes from the crossbeam-channel crate: -// -// Copyright (c) 2019 The Crossbeam Project Developers -// -// Permission is hereby granted, free of charge, to any -// person obtaining a copy of this software and associated -// documentation files (the "Software"), to deal in the -// Software without restriction, including without -// limitation the rights to use, copy, modify, merge, -// publish, distribute, sublicense, and/or sell copies of -// the Software, and to permit persons to whom the Software -// is furnished to do so, subject to the following -// conditions: -// -// The above copyright notice and this permission notice -// shall be included in all copies or substantial portions -// of the Software. -// -// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF -// ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED -// TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A -// PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT -// SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY -// CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION -// OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR -// IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER -// DEALINGS IN THE SOFTWARE. - -mod array; -mod context; -mod counter; -mod error; -mod list; -mod select; -mod utils; -mod waker; -mod zero; - -use crate::fmt; -use crate::panic::{RefUnwindSafe, UnwindSafe}; -use crate::time::{Duration, Instant}; -pub use error::*; - -/// Creates a channel of unbounded capacity. -/// -/// This channel has a growable buffer that can hold any number of messages at a time. -pub fn channel() -> (Sender, Receiver) { - let (s, r) = counter::new(list::Channel::new()); - let s = Sender { flavor: SenderFlavor::List(s) }; - let r = Receiver { flavor: ReceiverFlavor::List(r) }; - (s, r) -} - -/// Creates a channel of bounded capacity. -/// -/// This channel has a buffer that can hold at most `cap` messages at a time. -/// -/// A special case is zero-capacity channel, which cannot hold any messages. Instead, send and -/// receive operations must appear at the same time in order to pair up and pass the message over. -pub fn sync_channel(cap: usize) -> (Sender, Receiver) { - if cap == 0 { - let (s, r) = counter::new(zero::Channel::new()); - let s = Sender { flavor: SenderFlavor::Zero(s) }; - let r = Receiver { flavor: ReceiverFlavor::Zero(r) }; - (s, r) - } else { - let (s, r) = counter::new(array::Channel::with_capacity(cap)); - let s = Sender { flavor: SenderFlavor::Array(s) }; - let r = Receiver { flavor: ReceiverFlavor::Array(r) }; - (s, r) - } -} - -/// The sending side of a channel. -pub struct Sender { - flavor: SenderFlavor, -} - -/// Sender flavors. -enum SenderFlavor { - /// Bounded channel based on a preallocated array. - Array(counter::Sender>), - - /// Unbounded channel implemented as a linked list. - List(counter::Sender>), - - /// Zero-capacity channel. - Zero(counter::Sender>), -} - -unsafe impl Send for Sender {} -unsafe impl Sync for Sender {} - -impl UnwindSafe for Sender {} -impl RefUnwindSafe for Sender {} - -impl Sender { - /// Attempts to send a message into the channel without blocking. - /// - /// This method will either send a message into the channel immediately or return an error if - /// the channel is full or disconnected. The returned error contains the original message. - /// - /// If called on a zero-capacity channel, this method will send the message only if there - /// happens to be a receive operation on the other side of the channel at the same time. - pub fn try_send(&self, msg: T) -> Result<(), TrySendError> { - match &self.flavor { - SenderFlavor::Array(chan) => chan.try_send(msg), - SenderFlavor::List(chan) => chan.try_send(msg), - SenderFlavor::Zero(chan) => chan.try_send(msg), - } - } - - /// Blocks the current thread until a message is sent or the channel is disconnected. - /// - /// If the channel is full and not disconnected, this call will block until the send operation - /// can proceed. If the channel becomes disconnected, this call will wake up and return an - /// error. The returned error contains the original message. - /// - /// If called on a zero-capacity channel, this method will wait for a receive operation to - /// appear on the other side of the channel. - pub fn send(&self, msg: T) -> Result<(), SendError> { - match &self.flavor { - SenderFlavor::Array(chan) => chan.send(msg, None), - SenderFlavor::List(chan) => chan.send(msg, None), - SenderFlavor::Zero(chan) => chan.send(msg, None), - } - .map_err(|err| match err { - SendTimeoutError::Disconnected(msg) => SendError(msg), - SendTimeoutError::Timeout(_) => unreachable!(), - }) - } -} - -// The methods below are not used by `sync::mpsc`, but -// are useful and we'll likely want to expose them -// eventually -#[allow(unused)] -impl Sender { - /// Waits for a message to be sent into the channel, but only for a limited time. - /// - /// If the channel is full and not disconnected, this call will block until the send operation - /// can proceed or the operation times out. If the channel becomes disconnected, this call will - /// wake up and return an error. The returned error contains the original message. - /// - /// If called on a zero-capacity channel, this method will wait for a receive operation to - /// appear on the other side of the channel. - pub fn send_timeout(&self, msg: T, timeout: Duration) -> Result<(), SendTimeoutError> { - match Instant::now().checked_add(timeout) { - Some(deadline) => self.send_deadline(msg, deadline), - // So far in the future that it's practically the same as waiting indefinitely. - None => self.send(msg).map_err(SendTimeoutError::from), - } - } - - /// Waits for a message to be sent into the channel, but only until a given deadline. - /// - /// If the channel is full and not disconnected, this call will block until the send operation - /// can proceed or the operation times out. If the channel becomes disconnected, this call will - /// wake up and return an error. The returned error contains the original message. - /// - /// If called on a zero-capacity channel, this method will wait for a receive operation to - /// appear on the other side of the channel. - pub fn send_deadline(&self, msg: T, deadline: Instant) -> Result<(), SendTimeoutError> { - match &self.flavor { - SenderFlavor::Array(chan) => chan.send(msg, Some(deadline)), - SenderFlavor::List(chan) => chan.send(msg, Some(deadline)), - SenderFlavor::Zero(chan) => chan.send(msg, Some(deadline)), - } - } - - /// Returns `true` if the channel is empty. - /// - /// Note: Zero-capacity channels are always empty. - pub fn is_empty(&self) -> bool { - match &self.flavor { - SenderFlavor::Array(chan) => chan.is_empty(), - SenderFlavor::List(chan) => chan.is_empty(), - SenderFlavor::Zero(chan) => chan.is_empty(), - } - } - - /// Returns `true` if the channel is full. - /// - /// Note: Zero-capacity channels are always full. - pub fn is_full(&self) -> bool { - match &self.flavor { - SenderFlavor::Array(chan) => chan.is_full(), - SenderFlavor::List(chan) => chan.is_full(), - SenderFlavor::Zero(chan) => chan.is_full(), - } - } - - /// Returns the number of messages in the channel. - pub fn len(&self) -> usize { - match &self.flavor { - SenderFlavor::Array(chan) => chan.len(), - SenderFlavor::List(chan) => chan.len(), - SenderFlavor::Zero(chan) => chan.len(), - } - } - - /// If the channel is bounded, returns its capacity. - pub fn capacity(&self) -> Option { - match &self.flavor { - SenderFlavor::Array(chan) => chan.capacity(), - SenderFlavor::List(chan) => chan.capacity(), - SenderFlavor::Zero(chan) => chan.capacity(), - } - } - - /// Returns `true` if senders belong to the same channel. - pub fn same_channel(&self, other: &Sender) -> bool { - match (&self.flavor, &other.flavor) { - (SenderFlavor::Array(ref a), SenderFlavor::Array(ref b)) => a == b, - (SenderFlavor::List(ref a), SenderFlavor::List(ref b)) => a == b, - (SenderFlavor::Zero(ref a), SenderFlavor::Zero(ref b)) => a == b, - _ => false, - } - } -} - -impl Drop for Sender { - fn drop(&mut self) { - unsafe { - match &self.flavor { - SenderFlavor::Array(chan) => chan.release(|c| c.disconnect_senders()), - SenderFlavor::List(chan) => chan.release(|c| c.disconnect_senders()), - SenderFlavor::Zero(chan) => chan.release(|c| c.disconnect()), - } - } - } -} - -impl Clone for Sender { - fn clone(&self) -> Self { - let flavor = match &self.flavor { - SenderFlavor::Array(chan) => SenderFlavor::Array(chan.acquire()), - SenderFlavor::List(chan) => SenderFlavor::List(chan.acquire()), - SenderFlavor::Zero(chan) => SenderFlavor::Zero(chan.acquire()), - }; - - Sender { flavor } - } -} - -impl fmt::Debug for Sender { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.pad("Sender { .. }") - } -} - -/// The receiving side of a channel. -pub struct Receiver { - flavor: ReceiverFlavor, -} - -/// Receiver flavors. -enum ReceiverFlavor { - /// Bounded channel based on a preallocated array. - Array(counter::Receiver>), - - /// Unbounded channel implemented as a linked list. - List(counter::Receiver>), - - /// Zero-capacity channel. - Zero(counter::Receiver>), -} - -unsafe impl Send for Receiver {} -unsafe impl Sync for Receiver {} - -impl UnwindSafe for Receiver {} -impl RefUnwindSafe for Receiver {} - -impl Receiver { - /// Attempts to receive a message from the channel without blocking. - /// - /// This method will either receive a message from the channel immediately or return an error - /// if the channel is empty. - /// - /// If called on a zero-capacity channel, this method will receive a message only if there - /// happens to be a send operation on the other side of the channel at the same time. - pub fn try_recv(&self) -> Result { - match &self.flavor { - ReceiverFlavor::Array(chan) => chan.try_recv(), - ReceiverFlavor::List(chan) => chan.try_recv(), - ReceiverFlavor::Zero(chan) => chan.try_recv(), - } - } - - /// Blocks the current thread until a message is received or the channel is empty and - /// disconnected. - /// - /// If the channel is empty and not disconnected, this call will block until the receive - /// operation can proceed. If the channel is empty and becomes disconnected, this call will - /// wake up and return an error. - /// - /// If called on a zero-capacity channel, this method will wait for a send operation to appear - /// on the other side of the channel. - pub fn recv(&self) -> Result { - match &self.flavor { - ReceiverFlavor::Array(chan) => chan.recv(None), - ReceiverFlavor::List(chan) => chan.recv(None), - ReceiverFlavor::Zero(chan) => chan.recv(None), - } - .map_err(|_| RecvError) - } - - /// Waits for a message to be received from the channel, but only for a limited time. - /// - /// If the channel is empty and not disconnected, this call will block until the receive - /// operation can proceed or the operation times out. If the channel is empty and becomes - /// disconnected, this call will wake up and return an error. - /// - /// If called on a zero-capacity channel, this method will wait for a send operation to appear - /// on the other side of the channel. - pub fn recv_timeout(&self, timeout: Duration) -> Result { - match Instant::now().checked_add(timeout) { - Some(deadline) => self.recv_deadline(deadline), - // So far in the future that it's practically the same as waiting indefinitely. - None => self.recv().map_err(RecvTimeoutError::from), - } - } - - /// Waits for a message to be received from the channel, but only for a limited time. - /// - /// If the channel is empty and not disconnected, this call will block until the receive - /// operation can proceed or the operation times out. If the channel is empty and becomes - /// disconnected, this call will wake up and return an error. - /// - /// If called on a zero-capacity channel, this method will wait for a send operation to appear - /// on the other side of the channel. - pub fn recv_deadline(&self, deadline: Instant) -> Result { - match &self.flavor { - ReceiverFlavor::Array(chan) => chan.recv(Some(deadline)), - ReceiverFlavor::List(chan) => chan.recv(Some(deadline)), - ReceiverFlavor::Zero(chan) => chan.recv(Some(deadline)), - } - } -} - -// The methods below are not used by `sync::mpsc`, but -// are useful and we'll likely want to expose them -// eventually -#[allow(unused)] -impl Receiver { - /// Returns `true` if the channel is empty. - /// - /// Note: Zero-capacity channels are always empty. - pub fn is_empty(&self) -> bool { - match &self.flavor { - ReceiverFlavor::Array(chan) => chan.is_empty(), - ReceiverFlavor::List(chan) => chan.is_empty(), - ReceiverFlavor::Zero(chan) => chan.is_empty(), - } - } - - /// Returns `true` if the channel is full. - /// - /// Note: Zero-capacity channels are always full. - pub fn is_full(&self) -> bool { - match &self.flavor { - ReceiverFlavor::Array(chan) => chan.is_full(), - ReceiverFlavor::List(chan) => chan.is_full(), - ReceiverFlavor::Zero(chan) => chan.is_full(), - } - } - - /// Returns the number of messages in the channel. - pub fn len(&self) -> usize { - match &self.flavor { - ReceiverFlavor::Array(chan) => chan.len(), - ReceiverFlavor::List(chan) => chan.len(), - ReceiverFlavor::Zero(chan) => chan.len(), - } - } - - /// If the channel is bounded, returns its capacity. - pub fn capacity(&self) -> Option { - match &self.flavor { - ReceiverFlavor::Array(chan) => chan.capacity(), - ReceiverFlavor::List(chan) => chan.capacity(), - ReceiverFlavor::Zero(chan) => chan.capacity(), - } - } - - /// Returns `true` if receivers belong to the same channel. - pub fn same_channel(&self, other: &Receiver) -> bool { - match (&self.flavor, &other.flavor) { - (ReceiverFlavor::Array(a), ReceiverFlavor::Array(b)) => a == b, - (ReceiverFlavor::List(a), ReceiverFlavor::List(b)) => a == b, - (ReceiverFlavor::Zero(a), ReceiverFlavor::Zero(b)) => a == b, - _ => false, - } - } -} - -impl Drop for Receiver { - fn drop(&mut self) { - unsafe { - match &self.flavor { - ReceiverFlavor::Array(chan) => chan.release(|c| c.disconnect_receivers()), - ReceiverFlavor::List(chan) => chan.release(|c| c.disconnect_receivers()), - ReceiverFlavor::Zero(chan) => chan.release(|c| c.disconnect()), - } - } - } -} - -impl Clone for Receiver { - fn clone(&self) -> Self { - let flavor = match &self.flavor { - ReceiverFlavor::Array(chan) => ReceiverFlavor::Array(chan.acquire()), - ReceiverFlavor::List(chan) => ReceiverFlavor::List(chan.acquire()), - ReceiverFlavor::Zero(chan) => ReceiverFlavor::Zero(chan.acquire()), - }; - - Receiver { flavor } - } -} - -impl fmt::Debug for Receiver { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.pad("Receiver { .. }") - } -} diff --git a/library/std/src/sync/mpmc/select.rs b/library/std/src/sync/mpmc/select.rs deleted file mode 100644 index 56a83fee2e119..0000000000000 --- a/library/std/src/sync/mpmc/select.rs +++ /dev/null @@ -1,71 +0,0 @@ -/// Temporary data that gets initialized during a blocking operation, and is consumed by -/// `read` or `write`. -/// -/// Each field contains data associated with a specific channel flavor. -#[derive(Debug, Default)] -pub struct Token { - pub(crate) array: super::array::ArrayToken, - pub(crate) list: super::list::ListToken, - #[allow(dead_code)] - pub(crate) zero: super::zero::ZeroToken, -} - -/// Identifier associated with an operation by a specific thread on a specific channel. -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub struct Operation(usize); - -impl Operation { - /// Creates an operation identifier from a mutable reference. - /// - /// This function essentially just turns the address of the reference into a number. The - /// reference should point to a variable that is specific to the thread and the operation, - /// and is alive for the entire duration of a blocking operation. - #[inline] - pub fn hook(r: &mut T) -> Operation { - let val = r as *mut T as usize; - // Make sure that the pointer address doesn't equal the numerical representation of - // `Selected::{Waiting, Aborted, Disconnected}`. - assert!(val > 2); - Operation(val) - } -} - -/// Current state of a blocking operation. -#[derive(Debug, Clone, Copy, PartialEq, Eq)] -pub enum Selected { - /// Still waiting for an operation. - Waiting, - - /// The attempt to block the current thread has been aborted. - Aborted, - - /// An operation became ready because a channel is disconnected. - Disconnected, - - /// An operation became ready because a message can be sent or received. - Operation(Operation), -} - -impl From for Selected { - #[inline] - fn from(val: usize) -> Selected { - match val { - 0 => Selected::Waiting, - 1 => Selected::Aborted, - 2 => Selected::Disconnected, - oper => Selected::Operation(Operation(oper)), - } - } -} - -impl Into for Selected { - #[inline] - fn into(self) -> usize { - match self { - Selected::Waiting => 0, - Selected::Aborted => 1, - Selected::Disconnected => 2, - Selected::Operation(Operation(val)) => val, - } - } -} diff --git a/library/std/src/sync/mpmc/utils.rs b/library/std/src/sync/mpmc/utils.rs deleted file mode 100644 index 0cbc61160f7ee..0000000000000 --- a/library/std/src/sync/mpmc/utils.rs +++ /dev/null @@ -1,139 +0,0 @@ -use crate::cell::Cell; -use crate::ops::{Deref, DerefMut}; - -/// Pads and aligns a value to the length of a cache line. -#[derive(Clone, Copy, Default, Hash, PartialEq, Eq)] -// Starting from Intel's Sandy Bridge, spatial prefetcher is now pulling pairs of 64-byte cache -// lines at a time, so we have to align to 128 bytes rather than 64. -// -// Sources: -// - https://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-optimization-manual.pdf -// - https://github.com/facebook/folly/blob/1b5288e6eea6df074758f877c849b6e73bbb9fbb/folly/lang/Align.h#L107 -// -// ARM's big.LITTLE architecture has asymmetric cores and "big" cores have 128-byte cache line size. -// -// Sources: -// - https://www.mono-project.com/news/2016/09/12/arm64-icache/ -// -// powerpc64 has 128-byte cache line size. -// -// Sources: -// - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_ppc64x.go#L9 -#[cfg_attr( - any(target_arch = "x86_64", target_arch = "aarch64", target_arch = "powerpc64",), - repr(align(128)) -)] -// arm, mips, mips64, and riscv64 have 32-byte cache line size. -// -// Sources: -// - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_arm.go#L7 -// - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_mips.go#L7 -// - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_mipsle.go#L7 -// - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_mips64x.go#L9 -// - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_riscv64.go#L7 -#[cfg_attr( - any( - target_arch = "arm", - target_arch = "mips", - target_arch = "mips32r6", - target_arch = "mips64", - target_arch = "mips64r6", - target_arch = "riscv64", - ), - repr(align(32)) -)] -// s390x has 256-byte cache line size. -// -// Sources: -// - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_s390x.go#L7 -#[cfg_attr(target_arch = "s390x", repr(align(256)))] -// x86 and wasm have 64-byte cache line size. -// -// Sources: -// - https://github.com/golang/go/blob/dda2991c2ea0c5914714469c4defc2562a907230/src/internal/cpu/cpu_x86.go#L9 -// - https://github.com/golang/go/blob/3dd58676054223962cd915bb0934d1f9f489d4d2/src/internal/cpu/cpu_wasm.go#L7 -// -// All others are assumed to have 64-byte cache line size. -#[cfg_attr( - not(any( - target_arch = "x86_64", - target_arch = "aarch64", - target_arch = "powerpc64", - target_arch = "arm", - target_arch = "mips", - target_arch = "mips32r6", - target_arch = "mips64", - target_arch = "mips64r6", - target_arch = "riscv64", - target_arch = "s390x", - )), - repr(align(64)) -)] -pub struct CachePadded { - value: T, -} - -impl CachePadded { - /// Pads and aligns a value to the length of a cache line. - pub fn new(value: T) -> CachePadded { - CachePadded:: { value } - } -} - -impl Deref for CachePadded { - type Target = T; - - fn deref(&self) -> &T { - &self.value - } -} - -impl DerefMut for CachePadded { - fn deref_mut(&mut self) -> &mut T { - &mut self.value - } -} - -const SPIN_LIMIT: u32 = 6; - -/// Performs quadratic backoff in spin loops. -pub struct Backoff { - step: Cell, -} - -impl Backoff { - /// Creates a new `Backoff`. - pub fn new() -> Self { - Backoff { step: Cell::new(0) } - } - - /// Backs off using lightweight spinning. - /// - /// This method should be used for retrying an operation because another thread made - /// progress. i.e. on CAS failure. - #[inline] - pub fn spin_light(&self) { - let step = self.step.get().min(SPIN_LIMIT); - for _ in 0..step.pow(2) { - crate::hint::spin_loop(); - } - - self.step.set(self.step.get() + 1); - } - - /// Backs off using heavyweight spinning. - /// - /// This method should be used in blocking loops where parking the thread is not an option. - #[inline] - pub fn spin_heavy(&self) { - if self.step.get() <= SPIN_LIMIT { - for _ in 0..self.step.get().pow(2) { - crate::hint::spin_loop() - } - } else { - crate::thread::yield_now(); - } - - self.step.set(self.step.get() + 1); - } -} diff --git a/library/std/src/sync/mpmc/waker.rs b/library/std/src/sync/mpmc/waker.rs deleted file mode 100644 index 9aab1b9417edb..0000000000000 --- a/library/std/src/sync/mpmc/waker.rs +++ /dev/null @@ -1,210 +0,0 @@ -//! Waking mechanism for threads blocked on channel operations. - -use super::context::Context; -use super::select::{Operation, Selected}; - -use crate::ptr; -use crate::sync::atomic::{AtomicBool, Ordering}; -use crate::sync::Mutex; - -/// Represents a thread blocked on a specific channel operation. -pub(crate) struct Entry { - /// The operation. - pub(crate) oper: Operation, - - /// Optional packet. - pub(crate) packet: *mut (), - - /// Context associated with the thread owning this operation. - pub(crate) cx: Context, -} - -/// A queue of threads blocked on channel operations. -/// -/// This data structure is used by threads to register blocking operations and get woken up once -/// an operation becomes ready. -pub(crate) struct Waker { - /// A list of select operations. - selectors: Vec, - - /// A list of operations waiting to be ready. - observers: Vec, -} - -impl Waker { - /// Creates a new `Waker`. - #[inline] - pub(crate) fn new() -> Self { - Waker { selectors: Vec::new(), observers: Vec::new() } - } - - /// Registers a select operation. - #[inline] - pub(crate) fn register(&mut self, oper: Operation, cx: &Context) { - self.register_with_packet(oper, ptr::null_mut(), cx); - } - - /// Registers a select operation and a packet. - #[inline] - pub(crate) fn register_with_packet(&mut self, oper: Operation, packet: *mut (), cx: &Context) { - self.selectors.push(Entry { oper, packet, cx: cx.clone() }); - } - - /// Unregisters a select operation. - #[inline] - pub(crate) fn unregister(&mut self, oper: Operation) -> Option { - if let Some((i, _)) = - self.selectors.iter().enumerate().find(|&(_, entry)| entry.oper == oper) - { - let entry = self.selectors.remove(i); - Some(entry) - } else { - None - } - } - - /// Attempts to find another thread's entry, select the operation, and wake it up. - #[inline] - pub(crate) fn try_select(&mut self) -> Option { - if self.selectors.is_empty() { - None - } else { - let thread_id = current_thread_id(); - - self.selectors - .iter() - .position(|selector| { - // Does the entry belong to a different thread? - selector.cx.thread_id() != thread_id - && selector // Try selecting this operation. - .cx - .try_select(Selected::Operation(selector.oper)) - .is_ok() - && { - // Provide the packet. - selector.cx.store_packet(selector.packet); - // Wake the thread up. - selector.cx.unpark(); - true - } - }) - // Remove the entry from the queue to keep it clean and improve - // performance. - .map(|pos| self.selectors.remove(pos)) - } - } - - /// Notifies all operations waiting to be ready. - #[inline] - pub(crate) fn notify(&mut self) { - for entry in self.observers.drain(..) { - if entry.cx.try_select(Selected::Operation(entry.oper)).is_ok() { - entry.cx.unpark(); - } - } - } - - /// Notifies all registered operations that the channel is disconnected. - #[inline] - pub(crate) fn disconnect(&mut self) { - for entry in self.selectors.iter() { - if entry.cx.try_select(Selected::Disconnected).is_ok() { - // Wake the thread up. - // - // Here we don't remove the entry from the queue. Registered threads must - // unregister from the waker by themselves. They might also want to recover the - // packet value and destroy it, if necessary. - entry.cx.unpark(); - } - } - - self.notify(); - } -} - -impl Drop for Waker { - #[inline] - fn drop(&mut self) { - debug_assert_eq!(self.selectors.len(), 0); - debug_assert_eq!(self.observers.len(), 0); - } -} - -/// A waker that can be shared among threads without locking. -/// -/// This is a simple wrapper around `Waker` that internally uses a mutex for synchronization. -pub(crate) struct SyncWaker { - /// The inner `Waker`. - inner: Mutex, - - /// `true` if the waker is empty. - is_empty: AtomicBool, -} - -impl SyncWaker { - /// Creates a new `SyncWaker`. - #[inline] - pub(crate) fn new() -> Self { - SyncWaker { inner: Mutex::new(Waker::new()), is_empty: AtomicBool::new(true) } - } - - /// Registers the current thread with an operation. - #[inline] - pub(crate) fn register(&self, oper: Operation, cx: &Context) { - let mut inner = self.inner.lock().unwrap(); - inner.register(oper, cx); - self.is_empty - .store(inner.selectors.is_empty() && inner.observers.is_empty(), Ordering::SeqCst); - } - - /// Unregisters an operation previously registered by the current thread. - #[inline] - pub(crate) fn unregister(&self, oper: Operation) -> Option { - let mut inner = self.inner.lock().unwrap(); - let entry = inner.unregister(oper); - self.is_empty - .store(inner.selectors.is_empty() && inner.observers.is_empty(), Ordering::SeqCst); - entry - } - - /// Attempts to find one thread (not the current one), select its operation, and wake it up. - #[inline] - pub(crate) fn notify(&self) { - if !self.is_empty.load(Ordering::SeqCst) { - let mut inner = self.inner.lock().unwrap(); - if !self.is_empty.load(Ordering::SeqCst) { - inner.try_select(); - inner.notify(); - self.is_empty.store( - inner.selectors.is_empty() && inner.observers.is_empty(), - Ordering::SeqCst, - ); - } - } - } - - /// Notifies all threads that the channel is disconnected. - #[inline] - pub(crate) fn disconnect(&self) { - let mut inner = self.inner.lock().unwrap(); - inner.disconnect(); - self.is_empty - .store(inner.selectors.is_empty() && inner.observers.is_empty(), Ordering::SeqCst); - } -} - -impl Drop for SyncWaker { - #[inline] - fn drop(&mut self) { - debug_assert!(self.is_empty.load(Ordering::SeqCst)); - } -} - -/// Returns a unique id for the current thread. -#[inline] -pub fn current_thread_id() -> usize { - // `u8` is not drop so this variable will be available during thread destruction, - // whereas `thread::current()` would not be - thread_local! { static DUMMY: u8 = 0 } - DUMMY.with(|x| (x as *const u8).addr()) -} diff --git a/library/std/src/sync/mpmc/zero.rs b/library/std/src/sync/mpmc/zero.rs deleted file mode 100644 index 1b82713edc748..0000000000000 --- a/library/std/src/sync/mpmc/zero.rs +++ /dev/null @@ -1,322 +0,0 @@ -//! Zero-capacity channel. -//! -//! This kind of channel is also known as *rendezvous* channel. - -use super::context::Context; -use super::error::*; -use super::select::{Operation, Selected, Token}; -use super::utils::Backoff; -use super::waker::Waker; - -use crate::cell::UnsafeCell; -use crate::marker::PhantomData; -use crate::sync::atomic::{AtomicBool, Ordering}; -use crate::sync::Mutex; -use crate::time::Instant; -use crate::{fmt, ptr}; - -/// A pointer to a packet. -pub(crate) struct ZeroToken(*mut ()); - -impl Default for ZeroToken { - fn default() -> Self { - Self(ptr::null_mut()) - } -} - -impl fmt::Debug for ZeroToken { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&(self.0 as usize), f) - } -} - -/// A slot for passing one message from a sender to a receiver. -struct Packet { - /// Equals `true` if the packet is allocated on the stack. - on_stack: bool, - - /// Equals `true` once the packet is ready for reading or writing. - ready: AtomicBool, - - /// The message. - msg: UnsafeCell>, -} - -impl Packet { - /// Creates an empty packet on the stack. - fn empty_on_stack() -> Packet { - Packet { on_stack: true, ready: AtomicBool::new(false), msg: UnsafeCell::new(None) } - } - - /// Creates a packet on the stack, containing a message. - fn message_on_stack(msg: T) -> Packet { - Packet { on_stack: true, ready: AtomicBool::new(false), msg: UnsafeCell::new(Some(msg)) } - } - - /// Waits until the packet becomes ready for reading or writing. - fn wait_ready(&self) { - let backoff = Backoff::new(); - while !self.ready.load(Ordering::Acquire) { - backoff.spin_heavy(); - } - } -} - -/// Inner representation of a zero-capacity channel. -struct Inner { - /// Senders waiting to pair up with a receive operation. - senders: Waker, - - /// Receivers waiting to pair up with a send operation. - receivers: Waker, - - /// Equals `true` when the channel is disconnected. - is_disconnected: bool, -} - -/// Zero-capacity channel. -pub(crate) struct Channel { - /// Inner representation of the channel. - inner: Mutex, - - /// Indicates that dropping a `Channel` may drop values of type `T`. - _marker: PhantomData, -} - -impl Channel { - /// Constructs a new zero-capacity channel. - pub(crate) fn new() -> Self { - Channel { - inner: Mutex::new(Inner { - senders: Waker::new(), - receivers: Waker::new(), - is_disconnected: false, - }), - _marker: PhantomData, - } - } - - /// Writes a message into the packet. - pub(crate) unsafe fn write(&self, token: &mut Token, msg: T) -> Result<(), T> { - // If there is no packet, the channel is disconnected. - if token.zero.0.is_null() { - return Err(msg); - } - - let packet = &*(token.zero.0 as *const Packet); - packet.msg.get().write(Some(msg)); - packet.ready.store(true, Ordering::Release); - Ok(()) - } - - /// Reads a message from the packet. - pub(crate) unsafe fn read(&self, token: &mut Token) -> Result { - // If there is no packet, the channel is disconnected. - if token.zero.0.is_null() { - return Err(()); - } - - let packet = &*(token.zero.0 as *const Packet); - - if packet.on_stack { - // The message has been in the packet from the beginning, so there is no need to wait - // for it. However, after reading the message, we need to set `ready` to `true` in - // order to signal that the packet can be destroyed. - let msg = packet.msg.get().replace(None).unwrap(); - packet.ready.store(true, Ordering::Release); - Ok(msg) - } else { - // Wait until the message becomes available, then read it and destroy the - // heap-allocated packet. - packet.wait_ready(); - let msg = packet.msg.get().replace(None).unwrap(); - drop(Box::from_raw(token.zero.0 as *mut Packet)); - Ok(msg) - } - } - - /// Attempts to send a message into the channel. - pub(crate) fn try_send(&self, msg: T) -> Result<(), TrySendError> { - let token = &mut Token::default(); - let mut inner = self.inner.lock().unwrap(); - - // If there's a waiting receiver, pair up with it. - if let Some(operation) = inner.receivers.try_select() { - token.zero.0 = operation.packet; - drop(inner); - unsafe { - self.write(token, msg).ok().unwrap(); - } - Ok(()) - } else if inner.is_disconnected { - Err(TrySendError::Disconnected(msg)) - } else { - Err(TrySendError::Full(msg)) - } - } - - /// Sends a message into the channel. - pub(crate) fn send( - &self, - msg: T, - deadline: Option, - ) -> Result<(), SendTimeoutError> { - let token = &mut Token::default(); - let mut inner = self.inner.lock().unwrap(); - - // If there's a waiting receiver, pair up with it. - if let Some(operation) = inner.receivers.try_select() { - token.zero.0 = operation.packet; - drop(inner); - unsafe { - self.write(token, msg).ok().unwrap(); - } - return Ok(()); - } - - if inner.is_disconnected { - return Err(SendTimeoutError::Disconnected(msg)); - } - - Context::with(|cx| { - // Prepare for blocking until a receiver wakes us up. - let oper = Operation::hook(token); - let mut packet = Packet::::message_on_stack(msg); - inner.senders.register_with_packet( - oper, - core::ptr::addr_of_mut!(packet) as *mut (), - cx, - ); - inner.receivers.notify(); - drop(inner); - - // Block the current thread. - let sel = cx.wait_until(deadline); - - match sel { - Selected::Waiting => unreachable!(), - Selected::Aborted => { - self.inner.lock().unwrap().senders.unregister(oper).unwrap(); - let msg = unsafe { packet.msg.get().replace(None).unwrap() }; - Err(SendTimeoutError::Timeout(msg)) - } - Selected::Disconnected => { - self.inner.lock().unwrap().senders.unregister(oper).unwrap(); - let msg = unsafe { packet.msg.get().replace(None).unwrap() }; - Err(SendTimeoutError::Disconnected(msg)) - } - Selected::Operation(_) => { - // Wait until the message is read, then drop the packet. - packet.wait_ready(); - Ok(()) - } - } - }) - } - - /// Attempts to receive a message without blocking. - pub(crate) fn try_recv(&self) -> Result { - let token = &mut Token::default(); - let mut inner = self.inner.lock().unwrap(); - - // If there's a waiting sender, pair up with it. - if let Some(operation) = inner.senders.try_select() { - token.zero.0 = operation.packet; - drop(inner); - unsafe { self.read(token).map_err(|_| TryRecvError::Disconnected) } - } else if inner.is_disconnected { - Err(TryRecvError::Disconnected) - } else { - Err(TryRecvError::Empty) - } - } - - /// Receives a message from the channel. - pub(crate) fn recv(&self, deadline: Option) -> Result { - let token = &mut Token::default(); - let mut inner = self.inner.lock().unwrap(); - - // If there's a waiting sender, pair up with it. - if let Some(operation) = inner.senders.try_select() { - token.zero.0 = operation.packet; - drop(inner); - unsafe { - return self.read(token).map_err(|_| RecvTimeoutError::Disconnected); - } - } - - if inner.is_disconnected { - return Err(RecvTimeoutError::Disconnected); - } - - Context::with(|cx| { - // Prepare for blocking until a sender wakes us up. - let oper = Operation::hook(token); - let mut packet = Packet::::empty_on_stack(); - inner.receivers.register_with_packet( - oper, - core::ptr::addr_of_mut!(packet) as *mut (), - cx, - ); - inner.senders.notify(); - drop(inner); - - // Block the current thread. - let sel = cx.wait_until(deadline); - - match sel { - Selected::Waiting => unreachable!(), - Selected::Aborted => { - self.inner.lock().unwrap().receivers.unregister(oper).unwrap(); - Err(RecvTimeoutError::Timeout) - } - Selected::Disconnected => { - self.inner.lock().unwrap().receivers.unregister(oper).unwrap(); - Err(RecvTimeoutError::Disconnected) - } - Selected::Operation(_) => { - // Wait until the message is provided, then read it. - packet.wait_ready(); - unsafe { Ok(packet.msg.get().replace(None).unwrap()) } - } - } - }) - } - - /// Disconnects the channel and wakes up all blocked senders and receivers. - /// - /// Returns `true` if this call disconnected the channel. - pub(crate) fn disconnect(&self) -> bool { - let mut inner = self.inner.lock().unwrap(); - - if !inner.is_disconnected { - inner.is_disconnected = true; - inner.senders.disconnect(); - inner.receivers.disconnect(); - true - } else { - false - } - } - - /// Returns the current number of messages inside the channel. - pub(crate) fn len(&self) -> usize { - 0 - } - - /// Returns the capacity of the channel. - #[allow(clippy::unnecessary_wraps)] // This is intentional. - pub(crate) fn capacity(&self) -> Option { - Some(0) - } - - /// Returns `true` if the channel is empty. - pub(crate) fn is_empty(&self) -> bool { - true - } - - /// Returns `true` if the channel is full. - pub(crate) fn is_full(&self) -> bool { - true - } -} diff --git a/library/std/src/sync/mpsc/mod.rs b/library/std/src/sync/mpsc/mod.rs deleted file mode 100644 index d353c7bd5de9e..0000000000000 --- a/library/std/src/sync/mpsc/mod.rs +++ /dev/null @@ -1,1246 +0,0 @@ -//! Multi-producer, single-consumer FIFO queue communication primitives. -//! -//! This module provides message-based communication over channels, concretely -//! defined among three types: -//! -//! * [`Sender`] -//! * [`SyncSender`] -//! * [`Receiver`] -//! -//! A [`Sender`] or [`SyncSender`] is used to send data to a [`Receiver`]. Both -//! senders are clone-able (multi-producer) such that many threads can send -//! simultaneously to one receiver (single-consumer). -//! -//! These channels come in two flavors: -//! -//! 1. An asynchronous, infinitely buffered channel. The [`channel`] function -//! will return a `(Sender, Receiver)` tuple where all sends will be -//! **asynchronous** (they never block). The channel conceptually has an -//! infinite buffer. -//! -//! 2. A synchronous, bounded channel. The [`sync_channel`] function will -//! return a `(SyncSender, Receiver)` tuple where the storage for pending -//! messages is a pre-allocated buffer of a fixed size. All sends will be -//! **synchronous** by blocking until there is buffer space available. Note -//! that a bound of 0 is allowed, causing the channel to become a "rendezvous" -//! channel where each sender atomically hands off a message to a receiver. -//! -//! [`send`]: Sender::send -//! -//! ## Disconnection -//! -//! The send and receive operations on channels will all return a [`Result`] -//! indicating whether the operation succeeded or not. An unsuccessful operation -//! is normally indicative of the other half of a channel having "hung up" by -//! being dropped in its corresponding thread. -//! -//! Once half of a channel has been deallocated, most operations can no longer -//! continue to make progress, so [`Err`] will be returned. Many applications -//! will continue to [`unwrap`] the results returned from this module, -//! instigating a propagation of failure among threads if one unexpectedly dies. -//! -//! [`unwrap`]: Result::unwrap -//! -//! # Examples -//! -//! Simple usage: -//! -//! ``` -//! use std::thread; -//! use std::sync::mpsc::channel; -//! -//! // Create a simple streaming channel -//! let (tx, rx) = channel(); -//! thread::spawn(move|| { -//! tx.send(10).unwrap(); -//! }); -//! assert_eq!(rx.recv().unwrap(), 10); -//! ``` -//! -//! Shared usage: -//! -//! ``` -//! use std::thread; -//! use std::sync::mpsc::channel; -//! -//! // Create a shared channel that can be sent along from many threads -//! // where tx is the sending half (tx for transmission), and rx is the receiving -//! // half (rx for receiving). -//! let (tx, rx) = channel(); -//! for i in 0..10 { -//! let tx = tx.clone(); -//! thread::spawn(move|| { -//! tx.send(i).unwrap(); -//! }); -//! } -//! -//! for _ in 0..10 { -//! let j = rx.recv().unwrap(); -//! assert!(0 <= j && j < 10); -//! } -//! ``` -//! -//! Propagating panics: -//! -//! ``` -//! use std::sync::mpsc::channel; -//! -//! // The call to recv() will return an error because the channel has already -//! // hung up (or been deallocated) -//! let (tx, rx) = channel::(); -//! drop(tx); -//! assert!(rx.recv().is_err()); -//! ``` -//! -//! Synchronous channels: -//! -//! ``` -//! use std::thread; -//! use std::sync::mpsc::sync_channel; -//! -//! let (tx, rx) = sync_channel::(0); -//! thread::spawn(move|| { -//! // This will wait for the parent thread to start receiving -//! tx.send(53).unwrap(); -//! }); -//! rx.recv().unwrap(); -//! ``` -//! -//! Unbounded receive loop: -//! -//! ``` -//! use std::sync::mpsc::sync_channel; -//! use std::thread; -//! -//! let (tx, rx) = sync_channel(3); -//! -//! for _ in 0..3 { -//! // It would be the same without thread and clone here -//! // since there will still be one `tx` left. -//! let tx = tx.clone(); -//! // cloned tx dropped within thread -//! thread::spawn(move || tx.send("ok").unwrap()); -//! } -//! -//! // Drop the last sender to stop `rx` waiting for message. -//! // The program will not complete if we comment this out. -//! // **All** `tx` needs to be dropped for `rx` to have `Err`. -//! drop(tx); -//! -//! // Unbounded receiver waiting for all senders to complete. -//! while let Ok(msg) = rx.recv() { -//! println!("{msg}"); -//! } -//! -//! println!("completed"); -//! ``` - -#![stable(feature = "rust1", since = "1.0.0")] - -#[cfg(all(test, not(target_os = "emscripten")))] -mod tests; - -#[cfg(all(test, not(target_os = "emscripten")))] -mod sync_tests; - -// MPSC channels are built as a wrapper around MPMC channels, which -// were ported from the `crossbeam-channel` crate. MPMC channels are -// not exposed publicly, but if you are curious about the implementation, -// that's where everything is. - -use crate::error; -use crate::fmt; -use crate::sync::mpmc; -use crate::time::{Duration, Instant}; - -/// The receiving half of Rust's [`channel`] (or [`sync_channel`]) type. -/// This half can only be owned by one thread. -/// -/// Messages sent to the channel can be retrieved using [`recv`]. -/// -/// [`recv`]: Receiver::recv -/// -/// # Examples -/// -/// ```rust -/// use std::sync::mpsc::channel; -/// use std::thread; -/// use std::time::Duration; -/// -/// let (send, recv) = channel(); -/// -/// thread::spawn(move || { -/// send.send("Hello world!").unwrap(); -/// thread::sleep(Duration::from_secs(2)); // block for two seconds -/// send.send("Delayed for 2 seconds").unwrap(); -/// }); -/// -/// println!("{}", recv.recv().unwrap()); // Received immediately -/// println!("Waiting..."); -/// println!("{}", recv.recv().unwrap()); // Received after 2 seconds -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "Receiver")] -pub struct Receiver { - inner: mpmc::Receiver, -} - -// The receiver port can be sent from place to place, so long as it -// is not used to receive non-sendable things. -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Send for Receiver {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl !Sync for Receiver {} - -/// An iterator over messages on a [`Receiver`], created by [`iter`]. -/// -/// This iterator will block whenever [`next`] is called, -/// waiting for a new message, and [`None`] will be returned -/// when the corresponding channel has hung up. -/// -/// [`iter`]: Receiver::iter -/// [`next`]: Iterator::next -/// -/// # Examples -/// -/// ```rust -/// use std::sync::mpsc::channel; -/// use std::thread; -/// -/// let (send, recv) = channel(); -/// -/// thread::spawn(move || { -/// send.send(1u8).unwrap(); -/// send.send(2u8).unwrap(); -/// send.send(3u8).unwrap(); -/// }); -/// -/// for x in recv.iter() { -/// println!("Got: {x}"); -/// } -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Debug)] -pub struct Iter<'a, T: 'a> { - rx: &'a Receiver, -} - -/// An iterator that attempts to yield all pending values for a [`Receiver`], -/// created by [`try_iter`]. -/// -/// [`None`] will be returned when there are no pending values remaining or -/// if the corresponding channel has hung up. -/// -/// This iterator will never block the caller in order to wait for data to -/// become available. Instead, it will return [`None`]. -/// -/// [`try_iter`]: Receiver::try_iter -/// -/// # Examples -/// -/// ```rust -/// use std::sync::mpsc::channel; -/// use std::thread; -/// use std::time::Duration; -/// -/// let (sender, receiver) = channel(); -/// -/// // Nothing is in the buffer yet -/// assert!(receiver.try_iter().next().is_none()); -/// println!("Nothing in the buffer..."); -/// -/// thread::spawn(move || { -/// sender.send(1).unwrap(); -/// sender.send(2).unwrap(); -/// sender.send(3).unwrap(); -/// }); -/// -/// println!("Going to sleep..."); -/// thread::sleep(Duration::from_secs(2)); // block for two seconds -/// -/// for x in receiver.try_iter() { -/// println!("Got: {x}"); -/// } -/// ``` -#[stable(feature = "receiver_try_iter", since = "1.15.0")] -#[derive(Debug)] -pub struct TryIter<'a, T: 'a> { - rx: &'a Receiver, -} - -/// An owning iterator over messages on a [`Receiver`], -/// created by [`into_iter`]. -/// -/// This iterator will block whenever [`next`] -/// is called, waiting for a new message, and [`None`] will be -/// returned if the corresponding channel has hung up. -/// -/// [`into_iter`]: Receiver::into_iter -/// [`next`]: Iterator::next -/// -/// # Examples -/// -/// ```rust -/// use std::sync::mpsc::channel; -/// use std::thread; -/// -/// let (send, recv) = channel(); -/// -/// thread::spawn(move || { -/// send.send(1u8).unwrap(); -/// send.send(2u8).unwrap(); -/// send.send(3u8).unwrap(); -/// }); -/// -/// for x in recv.into_iter() { -/// println!("Got: {x}"); -/// } -/// ``` -#[stable(feature = "receiver_into_iter", since = "1.1.0")] -#[derive(Debug)] -pub struct IntoIter { - rx: Receiver, -} - -/// The sending-half of Rust's asynchronous [`channel`] type. -/// -/// Messages can be sent through this channel with [`send`]. -/// -/// Note: all senders (the original and its clones) need to be dropped for the receiver -/// to stop blocking to receive messages with [`Receiver::recv`]. -/// -/// [`send`]: Sender::send -/// -/// # Examples -/// -/// ```rust -/// use std::sync::mpsc::channel; -/// use std::thread; -/// -/// let (sender, receiver) = channel(); -/// let sender2 = sender.clone(); -/// -/// // First thread owns sender -/// thread::spawn(move || { -/// sender.send(1).unwrap(); -/// }); -/// -/// // Second thread owns sender2 -/// thread::spawn(move || { -/// sender2.send(2).unwrap(); -/// }); -/// -/// let msg = receiver.recv().unwrap(); -/// let msg2 = receiver.recv().unwrap(); -/// -/// assert_eq!(3, msg + msg2); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Sender { - inner: mpmc::Sender, -} - -// The send port can be sent from place to place, so long as it -// is not used to send non-sendable things. -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Send for Sender {} - -#[stable(feature = "mpsc_sender_sync", since = "1.72.0")] -unsafe impl Sync for Sender {} - -/// The sending-half of Rust's synchronous [`sync_channel`] type. -/// -/// Messages can be sent through this channel with [`send`] or [`try_send`]. -/// -/// [`send`] will block if there is no space in the internal buffer. -/// -/// [`send`]: SyncSender::send -/// [`try_send`]: SyncSender::try_send -/// -/// # Examples -/// -/// ```rust -/// use std::sync::mpsc::sync_channel; -/// use std::thread; -/// -/// // Create a sync_channel with buffer size 2 -/// let (sync_sender, receiver) = sync_channel(2); -/// let sync_sender2 = sync_sender.clone(); -/// -/// // First thread owns sync_sender -/// thread::spawn(move || { -/// sync_sender.send(1).unwrap(); -/// sync_sender.send(2).unwrap(); -/// }); -/// -/// // Second thread owns sync_sender2 -/// thread::spawn(move || { -/// sync_sender2.send(3).unwrap(); -/// // thread will now block since the buffer is full -/// println!("Thread unblocked!"); -/// }); -/// -/// let mut msg; -/// -/// msg = receiver.recv().unwrap(); -/// println!("message {msg} received"); -/// -/// // "Thread unblocked!" will be printed now -/// -/// msg = receiver.recv().unwrap(); -/// println!("message {msg} received"); -/// -/// msg = receiver.recv().unwrap(); -/// -/// println!("message {msg} received"); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub struct SyncSender { - inner: mpmc::Sender, -} - -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Send for SyncSender {} - -/// An error returned from the [`Sender::send`] or [`SyncSender::send`] -/// function on **channel**s. -/// -/// A **send** operation can only fail if the receiving end of a channel is -/// disconnected, implying that the data could never be received. The error -/// contains the data being sent as a payload so it can be recovered. -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(PartialEq, Eq, Clone, Copy)] -pub struct SendError(#[stable(feature = "rust1", since = "1.0.0")] pub T); - -/// An error returned from the [`recv`] function on a [`Receiver`]. -/// -/// The [`recv`] operation can only fail if the sending half of a -/// [`channel`] (or [`sync_channel`]) is disconnected, implying that no further -/// messages will ever be received. -/// -/// [`recv`]: Receiver::recv -#[derive(PartialEq, Eq, Clone, Copy, Debug)] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct RecvError; - -/// This enumeration is the list of the possible reasons that [`try_recv`] could -/// not return data when called. This can occur with both a [`channel`] and -/// a [`sync_channel`]. -/// -/// [`try_recv`]: Receiver::try_recv -#[derive(PartialEq, Eq, Clone, Copy, Debug)] -#[stable(feature = "rust1", since = "1.0.0")] -pub enum TryRecvError { - /// This **channel** is currently empty, but the **Sender**(s) have not yet - /// disconnected, so data may yet become available. - #[stable(feature = "rust1", since = "1.0.0")] - Empty, - - /// The **channel**'s sending half has become disconnected, and there will - /// never be any more data received on it. - #[stable(feature = "rust1", since = "1.0.0")] - Disconnected, -} - -/// This enumeration is the list of possible errors that made [`recv_timeout`] -/// unable to return data when called. This can occur with both a [`channel`] and -/// a [`sync_channel`]. -/// -/// [`recv_timeout`]: Receiver::recv_timeout -#[derive(PartialEq, Eq, Clone, Copy, Debug)] -#[stable(feature = "mpsc_recv_timeout", since = "1.12.0")] -pub enum RecvTimeoutError { - /// This **channel** is currently empty, but the **Sender**(s) have not yet - /// disconnected, so data may yet become available. - #[stable(feature = "mpsc_recv_timeout", since = "1.12.0")] - Timeout, - /// The **channel**'s sending half has become disconnected, and there will - /// never be any more data received on it. - #[stable(feature = "mpsc_recv_timeout", since = "1.12.0")] - Disconnected, -} - -/// This enumeration is the list of the possible error outcomes for the -/// [`try_send`] method. -/// -/// [`try_send`]: SyncSender::try_send -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(PartialEq, Eq, Clone, Copy)] -pub enum TrySendError { - /// The data could not be sent on the [`sync_channel`] because it would require that - /// the callee block to send the data. - /// - /// If this is a buffered channel, then the buffer is full at this time. If - /// this is not a buffered channel, then there is no [`Receiver`] available to - /// acquire the data. - #[stable(feature = "rust1", since = "1.0.0")] - Full(#[stable(feature = "rust1", since = "1.0.0")] T), - - /// This [`sync_channel`]'s receiving half has disconnected, so the data could not be - /// sent. The data is returned back to the callee in this case. - #[stable(feature = "rust1", since = "1.0.0")] - Disconnected(#[stable(feature = "rust1", since = "1.0.0")] T), -} - -/// Creates a new asynchronous channel, returning the sender/receiver halves. -/// All data sent on the [`Sender`] will become available on the [`Receiver`] in -/// the same order as it was sent, and no [`send`] will block the calling thread -/// (this channel has an "infinite buffer", unlike [`sync_channel`], which will -/// block after its buffer limit is reached). [`recv`] will block until a message -/// is available while there is at least one [`Sender`] alive (including clones). -/// -/// The [`Sender`] can be cloned to [`send`] to the same channel multiple times, but -/// only one [`Receiver`] is supported. -/// -/// If the [`Receiver`] is disconnected while trying to [`send`] with the -/// [`Sender`], the [`send`] method will return a [`SendError`]. Similarly, if the -/// [`Sender`] is disconnected while trying to [`recv`], the [`recv`] method will -/// return a [`RecvError`]. -/// -/// [`send`]: Sender::send -/// [`recv`]: Receiver::recv -/// -/// # Examples -/// -/// ``` -/// use std::sync::mpsc::channel; -/// use std::thread; -/// -/// let (sender, receiver) = channel(); -/// -/// // Spawn off an expensive computation -/// thread::spawn(move|| { -/// # fn expensive_computation() {} -/// sender.send(expensive_computation()).unwrap(); -/// }); -/// -/// // Do some useful work for awhile -/// -/// // Let's see what that answer was -/// println!("{:?}", receiver.recv().unwrap()); -/// ``` -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -pub fn channel() -> (Sender, Receiver) { - let (tx, rx) = mpmc::channel(); - (Sender { inner: tx }, Receiver { inner: rx }) -} - -/// Creates a new synchronous, bounded channel. -/// All data sent on the [`SyncSender`] will become available on the [`Receiver`] -/// in the same order as it was sent. Like asynchronous [`channel`]s, the -/// [`Receiver`] will block until a message becomes available. `sync_channel` -/// differs greatly in the semantics of the sender, however. -/// -/// This channel has an internal buffer on which messages will be queued. -/// `bound` specifies the buffer size. When the internal buffer becomes full, -/// future sends will *block* waiting for the buffer to open up. Note that a -/// buffer size of 0 is valid, in which case this becomes "rendezvous channel" -/// where each [`send`] will not return until a [`recv`] is paired with it. -/// -/// The [`SyncSender`] can be cloned to [`send`] to the same channel multiple -/// times, but only one [`Receiver`] is supported. -/// -/// Like asynchronous channels, if the [`Receiver`] is disconnected while trying -/// to [`send`] with the [`SyncSender`], the [`send`] method will return a -/// [`SendError`]. Similarly, If the [`SyncSender`] is disconnected while trying -/// to [`recv`], the [`recv`] method will return a [`RecvError`]. -/// -/// [`send`]: SyncSender::send -/// [`recv`]: Receiver::recv -/// -/// # Examples -/// -/// ``` -/// use std::sync::mpsc::sync_channel; -/// use std::thread; -/// -/// let (sender, receiver) = sync_channel(1); -/// -/// // this returns immediately -/// sender.send(1).unwrap(); -/// -/// thread::spawn(move|| { -/// // this will block until the previous message has been received -/// sender.send(2).unwrap(); -/// }); -/// -/// assert_eq!(receiver.recv().unwrap(), 1); -/// assert_eq!(receiver.recv().unwrap(), 2); -/// ``` -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -pub fn sync_channel(bound: usize) -> (SyncSender, Receiver) { - let (tx, rx) = mpmc::sync_channel(bound); - (SyncSender { inner: tx }, Receiver { inner: rx }) -} - -//////////////////////////////////////////////////////////////////////////////// -// Sender -//////////////////////////////////////////////////////////////////////////////// - -impl Sender { - /// Attempts to send a value on this channel, returning it back if it could - /// not be sent. - /// - /// A successful send occurs when it is determined that the other end of - /// the channel has not hung up already. An unsuccessful send would be one - /// where the corresponding receiver has already been deallocated. Note - /// that a return value of [`Err`] means that the data will never be - /// received, but a return value of [`Ok`] does *not* mean that the data - /// will be received. It is possible for the corresponding receiver to - /// hang up immediately after this function returns [`Ok`]. - /// - /// This method will never block the current thread. - /// - /// # Examples - /// - /// ``` - /// use std::sync::mpsc::channel; - /// - /// let (tx, rx) = channel(); - /// - /// // This send is always successful - /// tx.send(1).unwrap(); - /// - /// // This send will fail because the receiver is gone - /// drop(rx); - /// assert_eq!(tx.send(1).unwrap_err().0, 1); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn send(&self, t: T) -> Result<(), SendError> { - self.inner.send(t) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Sender { - /// Clone a sender to send to other threads. - /// - /// Note, be aware of the lifetime of the sender because all senders - /// (including the original) need to be dropped in order for - /// [`Receiver::recv`] to stop blocking. - fn clone(&self) -> Sender { - Sender { inner: self.inner.clone() } - } -} - -#[stable(feature = "mpsc_debug", since = "1.8.0")] -impl fmt::Debug for Sender { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Sender").finish_non_exhaustive() - } -} - -//////////////////////////////////////////////////////////////////////////////// -// SyncSender -//////////////////////////////////////////////////////////////////////////////// - -impl SyncSender { - /// Sends a value on this synchronous channel. - /// - /// This function will *block* until space in the internal buffer becomes - /// available or a receiver is available to hand off the message to. - /// - /// Note that a successful send does *not* guarantee that the receiver will - /// ever see the data if there is a buffer on this channel. Items may be - /// enqueued in the internal buffer for the receiver to receive at a later - /// time. If the buffer size is 0, however, the channel becomes a rendezvous - /// channel and it guarantees that the receiver has indeed received - /// the data if this function returns success. - /// - /// This function will never panic, but it may return [`Err`] if the - /// [`Receiver`] has disconnected and is no longer able to receive - /// information. - /// - /// # Examples - /// - /// ```rust - /// use std::sync::mpsc::sync_channel; - /// use std::thread; - /// - /// // Create a rendezvous sync_channel with buffer size 0 - /// let (sync_sender, receiver) = sync_channel(0); - /// - /// thread::spawn(move || { - /// println!("sending message..."); - /// sync_sender.send(1).unwrap(); - /// // Thread is now blocked until the message is received - /// - /// println!("...message received!"); - /// }); - /// - /// let msg = receiver.recv().unwrap(); - /// assert_eq!(1, msg); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn send(&self, t: T) -> Result<(), SendError> { - self.inner.send(t) - } - - /// Attempts to send a value on this channel without blocking. - /// - /// This method differs from [`send`] by returning immediately if the - /// channel's buffer is full or no receiver is waiting to acquire some - /// data. Compared with [`send`], this function has two failure cases - /// instead of one (one for disconnection, one for a full buffer). - /// - /// See [`send`] for notes about guarantees of whether the - /// receiver has received the data or not if this function is successful. - /// - /// [`send`]: Self::send - /// - /// # Examples - /// - /// ```rust - /// use std::sync::mpsc::sync_channel; - /// use std::thread; - /// - /// // Create a sync_channel with buffer size 1 - /// let (sync_sender, receiver) = sync_channel(1); - /// let sync_sender2 = sync_sender.clone(); - /// - /// // First thread owns sync_sender - /// thread::spawn(move || { - /// sync_sender.send(1).unwrap(); - /// sync_sender.send(2).unwrap(); - /// // Thread blocked - /// }); - /// - /// // Second thread owns sync_sender2 - /// thread::spawn(move || { - /// // This will return an error and send - /// // no message if the buffer is full - /// let _ = sync_sender2.try_send(3); - /// }); - /// - /// let mut msg; - /// msg = receiver.recv().unwrap(); - /// println!("message {msg} received"); - /// - /// msg = receiver.recv().unwrap(); - /// println!("message {msg} received"); - /// - /// // Third message may have never been sent - /// match receiver.try_recv() { - /// Ok(msg) => println!("message {msg} received"), - /// Err(_) => println!("the third message was never sent"), - /// } - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn try_send(&self, t: T) -> Result<(), TrySendError> { - self.inner.try_send(t) - } - - // Attempts to send for a value on this receiver, returning an error if the - // corresponding channel has hung up, or if it waits more than `timeout`. - // - // This method is currently private and only used for tests. - #[allow(unused)] - fn send_timeout(&self, t: T, timeout: Duration) -> Result<(), mpmc::SendTimeoutError> { - self.inner.send_timeout(t, timeout) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for SyncSender { - fn clone(&self) -> SyncSender { - SyncSender { inner: self.inner.clone() } - } -} - -#[stable(feature = "mpsc_debug", since = "1.8.0")] -impl fmt::Debug for SyncSender { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("SyncSender").finish_non_exhaustive() - } -} - -//////////////////////////////////////////////////////////////////////////////// -// Receiver -//////////////////////////////////////////////////////////////////////////////// - -impl Receiver { - /// Attempts to return a pending value on this receiver without blocking. - /// - /// This method will never block the caller in order to wait for data to - /// become available. Instead, this will always return immediately with a - /// possible option of pending data on the channel. - /// - /// This is useful for a flavor of "optimistic check" before deciding to - /// block on a receiver. - /// - /// Compared with [`recv`], this function has two failure cases instead of one - /// (one for disconnection, one for an empty buffer). - /// - /// [`recv`]: Self::recv - /// - /// # Examples - /// - /// ```rust - /// use std::sync::mpsc::{Receiver, channel}; - /// - /// let (_, receiver): (_, Receiver) = channel(); - /// - /// assert!(receiver.try_recv().is_err()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn try_recv(&self) -> Result { - self.inner.try_recv() - } - - /// Attempts to wait for a value on this receiver, returning an error if the - /// corresponding channel has hung up. - /// - /// This function will always block the current thread if there is no data - /// available and it's possible for more data to be sent (at least one sender - /// still exists). Once a message is sent to the corresponding [`Sender`] - /// (or [`SyncSender`]), this receiver will wake up and return that - /// message. - /// - /// If the corresponding [`Sender`] has disconnected, or it disconnects while - /// this call is blocking, this call will wake up and return [`Err`] to - /// indicate that no more messages can ever be received on this channel. - /// However, since channels are buffered, messages sent before the disconnect - /// will still be properly received. - /// - /// # Examples - /// - /// ``` - /// use std::sync::mpsc; - /// use std::thread; - /// - /// let (send, recv) = mpsc::channel(); - /// let handle = thread::spawn(move || { - /// send.send(1u8).unwrap(); - /// }); - /// - /// handle.join().unwrap(); - /// - /// assert_eq!(Ok(1), recv.recv()); - /// ``` - /// - /// Buffering behavior: - /// - /// ``` - /// use std::sync::mpsc; - /// use std::thread; - /// use std::sync::mpsc::RecvError; - /// - /// let (send, recv) = mpsc::channel(); - /// let handle = thread::spawn(move || { - /// send.send(1u8).unwrap(); - /// send.send(2).unwrap(); - /// send.send(3).unwrap(); - /// drop(send); - /// }); - /// - /// // wait for the thread to join so we ensure the sender is dropped - /// handle.join().unwrap(); - /// - /// assert_eq!(Ok(1), recv.recv()); - /// assert_eq!(Ok(2), recv.recv()); - /// assert_eq!(Ok(3), recv.recv()); - /// assert_eq!(Err(RecvError), recv.recv()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn recv(&self) -> Result { - self.inner.recv() - } - - /// Attempts to wait for a value on this receiver, returning an error if the - /// corresponding channel has hung up, or if it waits more than `timeout`. - /// - /// This function will always block the current thread if there is no data - /// available and it's possible for more data to be sent (at least one sender - /// still exists). Once a message is sent to the corresponding [`Sender`] - /// (or [`SyncSender`]), this receiver will wake up and return that - /// message. - /// - /// If the corresponding [`Sender`] has disconnected, or it disconnects while - /// this call is blocking, this call will wake up and return [`Err`] to - /// indicate that no more messages can ever be received on this channel. - /// However, since channels are buffered, messages sent before the disconnect - /// will still be properly received. - /// - /// # Examples - /// - /// Successfully receiving value before encountering timeout: - /// - /// ```no_run - /// use std::thread; - /// use std::time::Duration; - /// use std::sync::mpsc; - /// - /// let (send, recv) = mpsc::channel(); - /// - /// thread::spawn(move || { - /// send.send('a').unwrap(); - /// }); - /// - /// assert_eq!( - /// recv.recv_timeout(Duration::from_millis(400)), - /// Ok('a') - /// ); - /// ``` - /// - /// Receiving an error upon reaching timeout: - /// - /// ```no_run - /// use std::thread; - /// use std::time::Duration; - /// use std::sync::mpsc; - /// - /// let (send, recv) = mpsc::channel(); - /// - /// thread::spawn(move || { - /// thread::sleep(Duration::from_millis(800)); - /// send.send('a').unwrap(); - /// }); - /// - /// assert_eq!( - /// recv.recv_timeout(Duration::from_millis(400)), - /// Err(mpsc::RecvTimeoutError::Timeout) - /// ); - /// ``` - #[stable(feature = "mpsc_recv_timeout", since = "1.12.0")] - pub fn recv_timeout(&self, timeout: Duration) -> Result { - self.inner.recv_timeout(timeout) - } - - /// Attempts to wait for a value on this receiver, returning an error if the - /// corresponding channel has hung up, or if `deadline` is reached. - /// - /// This function will always block the current thread if there is no data - /// available and it's possible for more data to be sent. Once a message is - /// sent to the corresponding [`Sender`] (or [`SyncSender`]), then this - /// receiver will wake up and return that message. - /// - /// If the corresponding [`Sender`] has disconnected, or it disconnects while - /// this call is blocking, this call will wake up and return [`Err`] to - /// indicate that no more messages can ever be received on this channel. - /// However, since channels are buffered, messages sent before the disconnect - /// will still be properly received. - /// - /// # Examples - /// - /// Successfully receiving value before reaching deadline: - /// - /// ```no_run - /// #![feature(deadline_api)] - /// use std::thread; - /// use std::time::{Duration, Instant}; - /// use std::sync::mpsc; - /// - /// let (send, recv) = mpsc::channel(); - /// - /// thread::spawn(move || { - /// send.send('a').unwrap(); - /// }); - /// - /// assert_eq!( - /// recv.recv_deadline(Instant::now() + Duration::from_millis(400)), - /// Ok('a') - /// ); - /// ``` - /// - /// Receiving an error upon reaching deadline: - /// - /// ```no_run - /// #![feature(deadline_api)] - /// use std::thread; - /// use std::time::{Duration, Instant}; - /// use std::sync::mpsc; - /// - /// let (send, recv) = mpsc::channel(); - /// - /// thread::spawn(move || { - /// thread::sleep(Duration::from_millis(800)); - /// send.send('a').unwrap(); - /// }); - /// - /// assert_eq!( - /// recv.recv_deadline(Instant::now() + Duration::from_millis(400)), - /// Err(mpsc::RecvTimeoutError::Timeout) - /// ); - /// ``` - #[unstable(feature = "deadline_api", issue = "46316")] - pub fn recv_deadline(&self, deadline: Instant) -> Result { - self.inner.recv_deadline(deadline) - } - - /// Returns an iterator that will block waiting for messages, but never - /// [`panic!`]. It will return [`None`] when the channel has hung up. - /// - /// # Examples - /// - /// ```rust - /// use std::sync::mpsc::channel; - /// use std::thread; - /// - /// let (send, recv) = channel(); - /// - /// thread::spawn(move || { - /// send.send(1).unwrap(); - /// send.send(2).unwrap(); - /// send.send(3).unwrap(); - /// }); - /// - /// let mut iter = recv.iter(); - /// assert_eq!(iter.next(), Some(1)); - /// assert_eq!(iter.next(), Some(2)); - /// assert_eq!(iter.next(), Some(3)); - /// assert_eq!(iter.next(), None); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn iter(&self) -> Iter<'_, T> { - Iter { rx: self } - } - - /// Returns an iterator that will attempt to yield all pending values. - /// It will return `None` if there are no more pending values or if the - /// channel has hung up. The iterator will never [`panic!`] or block the - /// user by waiting for values. - /// - /// # Examples - /// - /// ```no_run - /// use std::sync::mpsc::channel; - /// use std::thread; - /// use std::time::Duration; - /// - /// let (sender, receiver) = channel(); - /// - /// // nothing is in the buffer yet - /// assert!(receiver.try_iter().next().is_none()); - /// - /// thread::spawn(move || { - /// thread::sleep(Duration::from_secs(1)); - /// sender.send(1).unwrap(); - /// sender.send(2).unwrap(); - /// sender.send(3).unwrap(); - /// }); - /// - /// // nothing is in the buffer yet - /// assert!(receiver.try_iter().next().is_none()); - /// - /// // block for two seconds - /// thread::sleep(Duration::from_secs(2)); - /// - /// let mut iter = receiver.try_iter(); - /// assert_eq!(iter.next(), Some(1)); - /// assert_eq!(iter.next(), Some(2)); - /// assert_eq!(iter.next(), Some(3)); - /// assert_eq!(iter.next(), None); - /// ``` - #[stable(feature = "receiver_try_iter", since = "1.15.0")] - pub fn try_iter(&self) -> TryIter<'_, T> { - TryIter { rx: self } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> Iterator for Iter<'a, T> { - type Item = T; - - fn next(&mut self) -> Option { - self.rx.recv().ok() - } -} - -#[stable(feature = "receiver_try_iter", since = "1.15.0")] -impl<'a, T> Iterator for TryIter<'a, T> { - type Item = T; - - fn next(&mut self) -> Option { - self.rx.try_recv().ok() - } -} - -#[stable(feature = "receiver_into_iter", since = "1.1.0")] -impl<'a, T> IntoIterator for &'a Receiver { - type Item = T; - type IntoIter = Iter<'a, T>; - - fn into_iter(self) -> Iter<'a, T> { - self.iter() - } -} - -#[stable(feature = "receiver_into_iter", since = "1.1.0")] -impl Iterator for IntoIter { - type Item = T; - fn next(&mut self) -> Option { - self.rx.recv().ok() - } -} - -#[stable(feature = "receiver_into_iter", since = "1.1.0")] -impl IntoIterator for Receiver { - type Item = T; - type IntoIter = IntoIter; - - fn into_iter(self) -> IntoIter { - IntoIter { rx: self } - } -} - -#[stable(feature = "mpsc_debug", since = "1.8.0")] -impl fmt::Debug for Receiver { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Receiver").finish_non_exhaustive() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for SendError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("SendError").finish_non_exhaustive() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for SendError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - "sending on a closed channel".fmt(f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl error::Error for SendError { - #[allow(deprecated)] - fn description(&self) -> &str { - "sending on a closed channel" - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for TrySendError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - match *self { - TrySendError::Full(..) => "Full(..)".fmt(f), - TrySendError::Disconnected(..) => "Disconnected(..)".fmt(f), - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for TrySendError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - match *self { - TrySendError::Full(..) => "sending on a full channel".fmt(f), - TrySendError::Disconnected(..) => "sending on a closed channel".fmt(f), - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl error::Error for TrySendError { - #[allow(deprecated)] - fn description(&self) -> &str { - match *self { - TrySendError::Full(..) => "sending on a full channel", - TrySendError::Disconnected(..) => "sending on a closed channel", - } - } -} - -#[stable(feature = "mpsc_error_conversions", since = "1.24.0")] -impl From> for TrySendError { - /// Converts a `SendError` into a `TrySendError`. - /// - /// This conversion always returns a `TrySendError::Disconnected` containing the data in the `SendError`. - /// - /// No data is allocated on the heap. - fn from(err: SendError) -> TrySendError { - match err { - SendError(t) => TrySendError::Disconnected(t), - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for RecvError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - "receiving on a closed channel".fmt(f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl error::Error for RecvError { - #[allow(deprecated)] - fn description(&self) -> &str { - "receiving on a closed channel" - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for TryRecvError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - match *self { - TryRecvError::Empty => "receiving on an empty channel".fmt(f), - TryRecvError::Disconnected => "receiving on a closed channel".fmt(f), - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl error::Error for TryRecvError { - #[allow(deprecated)] - fn description(&self) -> &str { - match *self { - TryRecvError::Empty => "receiving on an empty channel", - TryRecvError::Disconnected => "receiving on a closed channel", - } - } -} - -#[stable(feature = "mpsc_error_conversions", since = "1.24.0")] -impl From for TryRecvError { - /// Converts a `RecvError` into a `TryRecvError`. - /// - /// This conversion always returns `TryRecvError::Disconnected`. - /// - /// No data is allocated on the heap. - fn from(err: RecvError) -> TryRecvError { - match err { - RecvError => TryRecvError::Disconnected, - } - } -} - -#[stable(feature = "mpsc_recv_timeout_error", since = "1.15.0")] -impl fmt::Display for RecvTimeoutError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - match *self { - RecvTimeoutError::Timeout => "timed out waiting on channel".fmt(f), - RecvTimeoutError::Disconnected => "channel is empty and sending half is closed".fmt(f), - } - } -} - -#[stable(feature = "mpsc_recv_timeout_error", since = "1.15.0")] -impl error::Error for RecvTimeoutError { - #[allow(deprecated)] - fn description(&self) -> &str { - match *self { - RecvTimeoutError::Timeout => "timed out waiting on channel", - RecvTimeoutError::Disconnected => "channel is empty and sending half is closed", - } - } -} - -#[stable(feature = "mpsc_error_conversions", since = "1.24.0")] -impl From for RecvTimeoutError { - /// Converts a `RecvError` into a `RecvTimeoutError`. - /// - /// This conversion always returns `RecvTimeoutError::Disconnected`. - /// - /// No data is allocated on the heap. - fn from(err: RecvError) -> RecvTimeoutError { - match err { - RecvError => RecvTimeoutError::Disconnected, - } - } -} diff --git a/library/std/src/sync/mpsc/sync_tests.rs b/library/std/src/sync/mpsc/sync_tests.rs deleted file mode 100644 index 945de280f40d8..0000000000000 --- a/library/std/src/sync/mpsc/sync_tests.rs +++ /dev/null @@ -1,670 +0,0 @@ -use super::*; -use crate::env; -use crate::rc::Rc; -use crate::sync::mpmc::SendTimeoutError; -use crate::thread; - -pub fn stress_factor() -> usize { - match env::var("RUST_TEST_STRESS") { - Ok(val) => val.parse().unwrap(), - Err(..) => 1, - } -} - -#[test] -fn smoke() { - let (tx, rx) = sync_channel::(1); - tx.send(1).unwrap(); - assert_eq!(rx.recv().unwrap(), 1); -} - -#[test] -fn drop_full() { - let (tx, _rx) = sync_channel::>(1); - tx.send(Box::new(1)).unwrap(); -} - -#[test] -fn smoke_shared() { - let (tx, rx) = sync_channel::(1); - tx.send(1).unwrap(); - assert_eq!(rx.recv().unwrap(), 1); - let tx = tx.clone(); - tx.send(1).unwrap(); - assert_eq!(rx.recv().unwrap(), 1); -} - -#[test] -fn recv_timeout() { - let (tx, rx) = sync_channel::(1); - assert_eq!(rx.recv_timeout(Duration::from_millis(1)), Err(RecvTimeoutError::Timeout)); - tx.send(1).unwrap(); - assert_eq!(rx.recv_timeout(Duration::from_millis(1)), Ok(1)); -} - -#[test] -fn send_timeout() { - let (tx, _rx) = sync_channel::(1); - assert_eq!(tx.send_timeout(1, Duration::from_millis(1)), Ok(())); - assert_eq!(tx.send_timeout(1, Duration::from_millis(1)), Err(SendTimeoutError::Timeout(1))); -} - -#[test] -fn smoke_threads() { - let (tx, rx) = sync_channel::(0); - let _t = thread::spawn(move || { - tx.send(1).unwrap(); - }); - assert_eq!(rx.recv().unwrap(), 1); -} - -#[test] -fn smoke_port_gone() { - let (tx, rx) = sync_channel::(0); - drop(rx); - assert!(tx.send(1).is_err()); -} - -#[test] -fn smoke_shared_port_gone2() { - let (tx, rx) = sync_channel::(0); - drop(rx); - let tx2 = tx.clone(); - drop(tx); - assert!(tx2.send(1).is_err()); -} - -#[test] -fn port_gone_concurrent() { - let (tx, rx) = sync_channel::(0); - let _t = thread::spawn(move || { - rx.recv().unwrap(); - }); - while tx.send(1).is_ok() {} -} - -#[test] -fn port_gone_concurrent_shared() { - let (tx, rx) = sync_channel::(0); - let tx2 = tx.clone(); - let _t = thread::spawn(move || { - rx.recv().unwrap(); - }); - while tx.send(1).is_ok() && tx2.send(1).is_ok() {} -} - -#[test] -fn smoke_chan_gone() { - let (tx, rx) = sync_channel::(0); - drop(tx); - assert!(rx.recv().is_err()); -} - -#[test] -fn smoke_chan_gone_shared() { - let (tx, rx) = sync_channel::<()>(0); - let tx2 = tx.clone(); - drop(tx); - drop(tx2); - assert!(rx.recv().is_err()); -} - -#[test] -fn chan_gone_concurrent() { - let (tx, rx) = sync_channel::(0); - thread::spawn(move || { - tx.send(1).unwrap(); - tx.send(1).unwrap(); - }); - while rx.recv().is_ok() {} -} - -#[test] -fn stress() { - let count = if cfg!(miri) { 100 } else { 10000 }; - let (tx, rx) = sync_channel::(0); - thread::spawn(move || { - for _ in 0..count { - tx.send(1).unwrap(); - } - }); - for _ in 0..count { - assert_eq!(rx.recv().unwrap(), 1); - } -} - -#[test] -fn stress_recv_timeout_two_threads() { - let count = if cfg!(miri) { 100 } else { 10000 }; - let (tx, rx) = sync_channel::(0); - - thread::spawn(move || { - for _ in 0..count { - tx.send(1).unwrap(); - } - }); - - let mut recv_count = 0; - loop { - match rx.recv_timeout(Duration::from_millis(1)) { - Ok(v) => { - assert_eq!(v, 1); - recv_count += 1; - } - Err(RecvTimeoutError::Timeout) => continue, - Err(RecvTimeoutError::Disconnected) => break, - } - } - - assert_eq!(recv_count, count); -} - -#[test] -fn stress_recv_timeout_shared() { - const AMT: u32 = if cfg!(miri) { 100 } else { 1000 }; - const NTHREADS: u32 = 8; - let (tx, rx) = sync_channel::(0); - let (dtx, drx) = sync_channel::<()>(0); - - thread::spawn(move || { - let mut recv_count = 0; - loop { - match rx.recv_timeout(Duration::from_millis(10)) { - Ok(v) => { - assert_eq!(v, 1); - recv_count += 1; - } - Err(RecvTimeoutError::Timeout) => continue, - Err(RecvTimeoutError::Disconnected) => break, - } - } - - assert_eq!(recv_count, AMT * NTHREADS); - assert!(rx.try_recv().is_err()); - - dtx.send(()).unwrap(); - }); - - for _ in 0..NTHREADS { - let tx = tx.clone(); - thread::spawn(move || { - for _ in 0..AMT { - tx.send(1).unwrap(); - } - }); - } - - drop(tx); - - drx.recv().unwrap(); -} - -#[test] -fn stress_shared() { - const AMT: u32 = if cfg!(miri) { 100 } else { 1000 }; - const NTHREADS: u32 = 8; - let (tx, rx) = sync_channel::(0); - let (dtx, drx) = sync_channel::<()>(0); - - thread::spawn(move || { - for _ in 0..AMT * NTHREADS { - assert_eq!(rx.recv().unwrap(), 1); - } - match rx.try_recv() { - Ok(..) => panic!(), - _ => {} - } - dtx.send(()).unwrap(); - }); - - for _ in 0..NTHREADS { - let tx = tx.clone(); - thread::spawn(move || { - for _ in 0..AMT { - tx.send(1).unwrap(); - } - }); - } - drop(tx); - drx.recv().unwrap(); -} - -#[test] -fn oneshot_single_thread_close_port_first() { - // Simple test of closing without sending - let (_tx, rx) = sync_channel::(0); - drop(rx); -} - -#[test] -fn oneshot_single_thread_close_chan_first() { - // Simple test of closing without sending - let (tx, _rx) = sync_channel::(0); - drop(tx); -} - -#[test] -fn oneshot_single_thread_send_port_close() { - // Testing that the sender cleans up the payload if receiver is closed - let (tx, rx) = sync_channel::>(0); - drop(rx); - assert!(tx.send(Box::new(0)).is_err()); -} - -#[test] -fn oneshot_single_thread_recv_chan_close() { - // Receiving on a closed chan will panic - let res = thread::spawn(move || { - let (tx, rx) = sync_channel::(0); - drop(tx); - rx.recv().unwrap(); - }) - .join(); - // What is our res? - assert!(res.is_err()); -} - -#[test] -fn oneshot_single_thread_send_then_recv() { - let (tx, rx) = sync_channel::>(1); - tx.send(Box::new(10)).unwrap(); - assert!(*rx.recv().unwrap() == 10); -} - -#[test] -fn oneshot_single_thread_try_send_open() { - let (tx, rx) = sync_channel::(1); - assert_eq!(tx.try_send(10), Ok(())); - assert!(rx.recv().unwrap() == 10); -} - -#[test] -fn oneshot_single_thread_try_send_closed() { - let (tx, rx) = sync_channel::(0); - drop(rx); - assert_eq!(tx.try_send(10), Err(TrySendError::Disconnected(10))); -} - -#[test] -fn oneshot_single_thread_try_send_closed2() { - let (tx, _rx) = sync_channel::(0); - assert_eq!(tx.try_send(10), Err(TrySendError::Full(10))); -} - -#[test] -fn oneshot_single_thread_try_recv_open() { - let (tx, rx) = sync_channel::(1); - tx.send(10).unwrap(); - assert!(rx.recv() == Ok(10)); -} - -#[test] -fn oneshot_single_thread_try_recv_closed() { - let (tx, rx) = sync_channel::(0); - drop(tx); - assert!(rx.recv().is_err()); -} - -#[test] -fn oneshot_single_thread_try_recv_closed_with_data() { - let (tx, rx) = sync_channel::(1); - tx.send(10).unwrap(); - drop(tx); - assert_eq!(rx.try_recv(), Ok(10)); - assert_eq!(rx.try_recv(), Err(TryRecvError::Disconnected)); -} - -#[test] -fn oneshot_single_thread_peek_data() { - let (tx, rx) = sync_channel::(1); - assert_eq!(rx.try_recv(), Err(TryRecvError::Empty)); - tx.send(10).unwrap(); - assert_eq!(rx.try_recv(), Ok(10)); -} - -#[test] -fn oneshot_single_thread_peek_close() { - let (tx, rx) = sync_channel::(0); - drop(tx); - assert_eq!(rx.try_recv(), Err(TryRecvError::Disconnected)); - assert_eq!(rx.try_recv(), Err(TryRecvError::Disconnected)); -} - -#[test] -fn oneshot_single_thread_peek_open() { - let (_tx, rx) = sync_channel::(0); - assert_eq!(rx.try_recv(), Err(TryRecvError::Empty)); -} - -#[test] -fn oneshot_multi_task_recv_then_send() { - let (tx, rx) = sync_channel::>(0); - let _t = thread::spawn(move || { - assert!(*rx.recv().unwrap() == 10); - }); - - tx.send(Box::new(10)).unwrap(); -} - -#[test] -fn oneshot_multi_task_recv_then_close() { - let (tx, rx) = sync_channel::>(0); - let _t = thread::spawn(move || { - drop(tx); - }); - let res = thread::spawn(move || { - assert!(*rx.recv().unwrap() == 10); - }) - .join(); - assert!(res.is_err()); -} - -#[test] -fn oneshot_multi_thread_close_stress() { - for _ in 0..stress_factor() { - let (tx, rx) = sync_channel::(0); - let _t = thread::spawn(move || { - drop(rx); - }); - drop(tx); - } -} - -#[test] -fn oneshot_multi_thread_send_close_stress() { - for _ in 0..stress_factor() { - let (tx, rx) = sync_channel::(0); - let _t = thread::spawn(move || { - drop(rx); - }); - let _ = thread::spawn(move || { - tx.send(1).unwrap(); - }) - .join(); - } -} - -#[test] -fn oneshot_multi_thread_recv_close_stress() { - for _ in 0..stress_factor() { - let (tx, rx) = sync_channel::(0); - let _t = thread::spawn(move || { - let res = thread::spawn(move || { - rx.recv().unwrap(); - }) - .join(); - assert!(res.is_err()); - }); - let _t = thread::spawn(move || { - thread::spawn(move || { - drop(tx); - }); - }); - } -} - -#[test] -fn oneshot_multi_thread_send_recv_stress() { - for _ in 0..stress_factor() { - let (tx, rx) = sync_channel::>(0); - let _t = thread::spawn(move || { - tx.send(Box::new(10)).unwrap(); - }); - assert!(*rx.recv().unwrap() == 10); - } -} - -#[test] -fn stream_send_recv_stress() { - for _ in 0..stress_factor() { - let (tx, rx) = sync_channel::>(0); - - send(tx, 0); - recv(rx, 0); - - fn send(tx: SyncSender>, i: i32) { - if i == 10 { - return; - } - - thread::spawn(move || { - tx.send(Box::new(i)).unwrap(); - send(tx, i + 1); - }); - } - - fn recv(rx: Receiver>, i: i32) { - if i == 10 { - return; - } - - thread::spawn(move || { - assert!(*rx.recv().unwrap() == i); - recv(rx, i + 1); - }); - } - } -} - -#[test] -fn recv_a_lot() { - let count = if cfg!(miri) { 1000 } else { 10000 }; - // Regression test that we don't run out of stack in scheduler context - let (tx, rx) = sync_channel(count); - for _ in 0..count { - tx.send(()).unwrap(); - } - for _ in 0..count { - rx.recv().unwrap(); - } -} - -#[test] -fn shared_chan_stress() { - let (tx, rx) = sync_channel(0); - let total = stress_factor() + 100; - for _ in 0..total { - let tx = tx.clone(); - thread::spawn(move || { - tx.send(()).unwrap(); - }); - } - - for _ in 0..total { - rx.recv().unwrap(); - } -} - -#[test] -fn test_nested_recv_iter() { - let (tx, rx) = sync_channel::(0); - let (total_tx, total_rx) = sync_channel::(0); - - let _t = thread::spawn(move || { - let mut acc = 0; - for x in rx.iter() { - acc += x; - } - total_tx.send(acc).unwrap(); - }); - - tx.send(3).unwrap(); - tx.send(1).unwrap(); - tx.send(2).unwrap(); - drop(tx); - assert_eq!(total_rx.recv().unwrap(), 6); -} - -#[test] -fn test_recv_iter_break() { - let (tx, rx) = sync_channel::(0); - let (count_tx, count_rx) = sync_channel(0); - - let _t = thread::spawn(move || { - let mut count = 0; - for x in rx.iter() { - if count >= 3 { - break; - } else { - count += x; - } - } - count_tx.send(count).unwrap(); - }); - - tx.send(2).unwrap(); - tx.send(2).unwrap(); - tx.send(2).unwrap(); - let _ = tx.try_send(2); - drop(tx); - assert_eq!(count_rx.recv().unwrap(), 4); -} - -#[test] -fn try_recv_states() { - let (tx1, rx1) = sync_channel::(1); - let (tx2, rx2) = sync_channel::<()>(1); - let (tx3, rx3) = sync_channel::<()>(1); - let _t = thread::spawn(move || { - rx2.recv().unwrap(); - tx1.send(1).unwrap(); - tx3.send(()).unwrap(); - rx2.recv().unwrap(); - drop(tx1); - tx3.send(()).unwrap(); - }); - - assert_eq!(rx1.try_recv(), Err(TryRecvError::Empty)); - tx2.send(()).unwrap(); - rx3.recv().unwrap(); - assert_eq!(rx1.try_recv(), Ok(1)); - assert_eq!(rx1.try_recv(), Err(TryRecvError::Empty)); - tx2.send(()).unwrap(); - rx3.recv().unwrap(); - assert_eq!(rx1.try_recv(), Err(TryRecvError::Disconnected)); -} - -// This bug used to end up in a livelock inside of the Receiver destructor -// because the internal state of the Shared packet was corrupted -#[test] -fn destroy_upgraded_shared_port_when_sender_still_active() { - let (tx, rx) = sync_channel::<()>(0); - let (tx2, rx2) = sync_channel::<()>(0); - let _t = thread::spawn(move || { - rx.recv().unwrap(); // wait on a oneshot - drop(rx); // destroy a shared - tx2.send(()).unwrap(); - }); - // make sure the other thread has gone to sleep - for _ in 0..5000 { - thread::yield_now(); - } - - // upgrade to a shared chan and send a message - let t = tx.clone(); - drop(tx); - t.send(()).unwrap(); - - // wait for the child thread to exit before we exit - rx2.recv().unwrap(); -} - -#[test] -fn send1() { - let (tx, rx) = sync_channel::(0); - let _t = thread::spawn(move || { - rx.recv().unwrap(); - }); - assert_eq!(tx.send(1), Ok(())); -} - -#[test] -fn send2() { - let (tx, rx) = sync_channel::(0); - let _t = thread::spawn(move || { - drop(rx); - }); - assert!(tx.send(1).is_err()); -} - -#[test] -fn send3() { - let (tx, rx) = sync_channel::(1); - assert_eq!(tx.send(1), Ok(())); - let _t = thread::spawn(move || { - drop(rx); - }); - assert!(tx.send(1).is_err()); -} - -#[test] -fn send4() { - let (tx, rx) = sync_channel::(0); - let tx2 = tx.clone(); - let (done, donerx) = channel(); - let done2 = done.clone(); - let _t = thread::spawn(move || { - assert!(tx.send(1).is_err()); - done.send(()).unwrap(); - }); - let _t = thread::spawn(move || { - assert!(tx2.send(2).is_err()); - done2.send(()).unwrap(); - }); - drop(rx); - donerx.recv().unwrap(); - donerx.recv().unwrap(); -} - -#[test] -fn try_send1() { - let (tx, _rx) = sync_channel::(0); - assert_eq!(tx.try_send(1), Err(TrySendError::Full(1))); -} - -#[test] -fn try_send2() { - let (tx, _rx) = sync_channel::(1); - assert_eq!(tx.try_send(1), Ok(())); - assert_eq!(tx.try_send(1), Err(TrySendError::Full(1))); -} - -#[test] -fn try_send3() { - let (tx, rx) = sync_channel::(1); - assert_eq!(tx.try_send(1), Ok(())); - drop(rx); - assert_eq!(tx.try_send(1), Err(TrySendError::Disconnected(1))); -} - -#[test] -fn issue_15761() { - fn repro() { - let (tx1, rx1) = sync_channel::<()>(3); - let (tx2, rx2) = sync_channel::<()>(3); - - let _t = thread::spawn(move || { - rx1.recv().unwrap(); - tx2.try_send(()).unwrap(); - }); - - tx1.try_send(()).unwrap(); - rx2.recv().unwrap(); - } - - for _ in 0..100 { - repro() - } -} - -#[test] -fn drop_unreceived() { - let (tx, rx) = sync_channel::>(1); - let msg = Rc::new(()); - let weak = Rc::downgrade(&msg); - assert!(tx.send(msg).is_ok()); - drop(rx); - // Messages should be dropped immediately when the last receiver is destroyed. - assert!(weak.upgrade().is_none()); - drop(tx); -} diff --git a/library/std/src/sync/mpsc/tests.rs b/library/std/src/sync/mpsc/tests.rs deleted file mode 100644 index ac1a804cf9c84..0000000000000 --- a/library/std/src/sync/mpsc/tests.rs +++ /dev/null @@ -1,722 +0,0 @@ -use super::*; -use crate::env; -use crate::thread; - -pub fn stress_factor() -> usize { - match env::var("RUST_TEST_STRESS") { - Ok(val) => val.parse().unwrap(), - Err(..) => 1, - } -} - -#[test] -fn smoke() { - let (tx, rx) = channel::(); - tx.send(1).unwrap(); - assert_eq!(rx.recv().unwrap(), 1); -} - -#[test] -fn drop_full() { - let (tx, _rx) = channel::>(); - tx.send(Box::new(1)).unwrap(); -} - -#[test] -fn drop_full_shared() { - let (tx, _rx) = channel::>(); - drop(tx.clone()); - drop(tx.clone()); - tx.send(Box::new(1)).unwrap(); -} - -#[test] -fn smoke_shared() { - let (tx, rx) = channel::(); - tx.send(1).unwrap(); - assert_eq!(rx.recv().unwrap(), 1); - let tx = tx.clone(); - tx.send(1).unwrap(); - assert_eq!(rx.recv().unwrap(), 1); -} - -#[test] -fn smoke_threads() { - let (tx, rx) = channel::(); - let _t = thread::spawn(move || { - tx.send(1).unwrap(); - }); - assert_eq!(rx.recv().unwrap(), 1); -} - -#[test] -fn smoke_port_gone() { - let (tx, rx) = channel::(); - drop(rx); - assert!(tx.send(1).is_err()); -} - -#[test] -fn smoke_shared_port_gone() { - let (tx, rx) = channel::(); - drop(rx); - assert!(tx.send(1).is_err()) -} - -#[test] -fn smoke_shared_port_gone2() { - let (tx, rx) = channel::(); - drop(rx); - let tx2 = tx.clone(); - drop(tx); - assert!(tx2.send(1).is_err()); -} - -#[test] -fn port_gone_concurrent() { - let (tx, rx) = channel::(); - let _t = thread::spawn(move || { - rx.recv().unwrap(); - }); - while tx.send(1).is_ok() {} -} - -#[test] -fn port_gone_concurrent_shared() { - let (tx, rx) = channel::(); - let tx2 = tx.clone(); - let _t = thread::spawn(move || { - rx.recv().unwrap(); - }); - while tx.send(1).is_ok() && tx2.send(1).is_ok() {} -} - -#[test] -fn smoke_chan_gone() { - let (tx, rx) = channel::(); - drop(tx); - assert!(rx.recv().is_err()); -} - -#[test] -fn smoke_chan_gone_shared() { - let (tx, rx) = channel::<()>(); - let tx2 = tx.clone(); - drop(tx); - drop(tx2); - assert!(rx.recv().is_err()); -} - -#[test] -fn chan_gone_concurrent() { - let (tx, rx) = channel::(); - let _t = thread::spawn(move || { - tx.send(1).unwrap(); - tx.send(1).unwrap(); - }); - while rx.recv().is_ok() {} -} - -#[test] -fn stress() { - let count = if cfg!(miri) { 100 } else { 10000 }; - let (tx, rx) = channel::(); - let t = thread::spawn(move || { - for _ in 0..count { - tx.send(1).unwrap(); - } - }); - for _ in 0..count { - assert_eq!(rx.recv().unwrap(), 1); - } - t.join().ok().expect("thread panicked"); -} - -#[test] -fn stress_shared() { - const AMT: u32 = if cfg!(miri) { 100 } else { 10000 }; - const NTHREADS: u32 = 8; - let (tx, rx) = channel::(); - - let t = thread::spawn(move || { - for _ in 0..AMT * NTHREADS { - assert_eq!(rx.recv().unwrap(), 1); - } - match rx.try_recv() { - Ok(..) => panic!(), - _ => {} - } - }); - - for _ in 0..NTHREADS { - let tx = tx.clone(); - thread::spawn(move || { - for _ in 0..AMT { - tx.send(1).unwrap(); - } - }); - } - drop(tx); - t.join().ok().expect("thread panicked"); -} - -#[test] -fn send_from_outside_runtime() { - let (tx1, rx1) = channel::<()>(); - let (tx2, rx2) = channel::(); - let t1 = thread::spawn(move || { - tx1.send(()).unwrap(); - for _ in 0..40 { - assert_eq!(rx2.recv().unwrap(), 1); - } - }); - rx1.recv().unwrap(); - let t2 = thread::spawn(move || { - for _ in 0..40 { - tx2.send(1).unwrap(); - } - }); - t1.join().ok().expect("thread panicked"); - t2.join().ok().expect("thread panicked"); -} - -#[test] -fn recv_from_outside_runtime() { - let (tx, rx) = channel::(); - let t = thread::spawn(move || { - for _ in 0..40 { - assert_eq!(rx.recv().unwrap(), 1); - } - }); - for _ in 0..40 { - tx.send(1).unwrap(); - } - t.join().ok().expect("thread panicked"); -} - -#[test] -fn no_runtime() { - let (tx1, rx1) = channel::(); - let (tx2, rx2) = channel::(); - let t1 = thread::spawn(move || { - assert_eq!(rx1.recv().unwrap(), 1); - tx2.send(2).unwrap(); - }); - let t2 = thread::spawn(move || { - tx1.send(1).unwrap(); - assert_eq!(rx2.recv().unwrap(), 2); - }); - t1.join().ok().expect("thread panicked"); - t2.join().ok().expect("thread panicked"); -} - -#[test] -fn oneshot_single_thread_close_port_first() { - // Simple test of closing without sending - let (_tx, rx) = channel::(); - drop(rx); -} - -#[test] -fn oneshot_single_thread_close_chan_first() { - // Simple test of closing without sending - let (tx, _rx) = channel::(); - drop(tx); -} - -#[test] -fn oneshot_single_thread_send_port_close() { - // Testing that the sender cleans up the payload if receiver is closed - let (tx, rx) = channel::>(); - drop(rx); - assert!(tx.send(Box::new(0)).is_err()); -} - -#[test] -fn oneshot_single_thread_recv_chan_close() { - // Receiving on a closed chan will panic - let res = thread::spawn(move || { - let (tx, rx) = channel::(); - drop(tx); - rx.recv().unwrap(); - }) - .join(); - // What is our res? - assert!(res.is_err()); -} - -#[test] -fn oneshot_single_thread_send_then_recv() { - let (tx, rx) = channel::>(); - tx.send(Box::new(10)).unwrap(); - assert!(*rx.recv().unwrap() == 10); -} - -#[test] -fn oneshot_single_thread_try_send_open() { - let (tx, rx) = channel::(); - assert!(tx.send(10).is_ok()); - assert!(rx.recv().unwrap() == 10); -} - -#[test] -fn oneshot_single_thread_try_send_closed() { - let (tx, rx) = channel::(); - drop(rx); - assert!(tx.send(10).is_err()); -} - -#[test] -fn oneshot_single_thread_try_recv_open() { - let (tx, rx) = channel::(); - tx.send(10).unwrap(); - assert!(rx.recv() == Ok(10)); -} - -#[test] -fn oneshot_single_thread_try_recv_closed() { - let (tx, rx) = channel::(); - drop(tx); - assert!(rx.recv().is_err()); -} - -#[test] -fn oneshot_single_thread_peek_data() { - let (tx, rx) = channel::(); - assert_eq!(rx.try_recv(), Err(TryRecvError::Empty)); - tx.send(10).unwrap(); - assert_eq!(rx.try_recv(), Ok(10)); -} - -#[test] -fn oneshot_single_thread_peek_close() { - let (tx, rx) = channel::(); - drop(tx); - assert_eq!(rx.try_recv(), Err(TryRecvError::Disconnected)); - assert_eq!(rx.try_recv(), Err(TryRecvError::Disconnected)); -} - -#[test] -fn oneshot_single_thread_peek_open() { - let (_tx, rx) = channel::(); - assert_eq!(rx.try_recv(), Err(TryRecvError::Empty)); -} - -#[test] -fn oneshot_multi_task_recv_then_send() { - let (tx, rx) = channel::>(); - let _t = thread::spawn(move || { - assert!(*rx.recv().unwrap() == 10); - }); - - tx.send(Box::new(10)).unwrap(); -} - -#[test] -fn oneshot_multi_task_recv_then_close() { - let (tx, rx) = channel::>(); - let _t = thread::spawn(move || { - drop(tx); - }); - let res = thread::spawn(move || { - assert!(*rx.recv().unwrap() == 10); - }) - .join(); - assert!(res.is_err()); -} - -#[test] -fn oneshot_multi_thread_close_stress() { - for _ in 0..stress_factor() { - let (tx, rx) = channel::(); - let _t = thread::spawn(move || { - drop(rx); - }); - drop(tx); - } -} - -#[test] -fn oneshot_multi_thread_send_close_stress() { - for _ in 0..stress_factor() { - let (tx, rx) = channel::(); - let _t = thread::spawn(move || { - drop(rx); - }); - let _ = thread::spawn(move || { - tx.send(1).unwrap(); - }) - .join(); - } -} - -#[test] -fn oneshot_multi_thread_recv_close_stress() { - for _ in 0..stress_factor() { - let (tx, rx) = channel::(); - thread::spawn(move || { - let res = thread::spawn(move || { - rx.recv().unwrap(); - }) - .join(); - assert!(res.is_err()); - }); - let _t = thread::spawn(move || { - thread::spawn(move || { - drop(tx); - }); - }); - } -} - -#[test] -fn oneshot_multi_thread_send_recv_stress() { - for _ in 0..stress_factor() { - let (tx, rx) = channel::>(); - let _t = thread::spawn(move || { - tx.send(Box::new(10)).unwrap(); - }); - assert!(*rx.recv().unwrap() == 10); - } -} - -#[test] -fn stream_send_recv_stress() { - for _ in 0..stress_factor() { - let (tx, rx) = channel(); - - send(tx, 0); - recv(rx, 0); - - fn send(tx: Sender>, i: i32) { - if i == 10 { - return; - } - - thread::spawn(move || { - tx.send(Box::new(i)).unwrap(); - send(tx, i + 1); - }); - } - - fn recv(rx: Receiver>, i: i32) { - if i == 10 { - return; - } - - thread::spawn(move || { - assert!(*rx.recv().unwrap() == i); - recv(rx, i + 1); - }); - } - } -} - -#[test] -fn oneshot_single_thread_recv_timeout() { - let (tx, rx) = channel(); - tx.send(()).unwrap(); - assert_eq!(rx.recv_timeout(Duration::from_millis(1)), Ok(())); - assert_eq!(rx.recv_timeout(Duration::from_millis(1)), Err(RecvTimeoutError::Timeout)); - tx.send(()).unwrap(); - assert_eq!(rx.recv_timeout(Duration::from_millis(1)), Ok(())); -} - -#[test] -fn stress_recv_timeout_two_threads() { - let (tx, rx) = channel(); - let stress = stress_factor() + 100; - let timeout = Duration::from_millis(100); - - thread::spawn(move || { - for i in 0..stress { - if i % 2 == 0 { - thread::sleep(timeout * 2); - } - tx.send(1usize).unwrap(); - } - }); - - let mut recv_count = 0; - loop { - match rx.recv_timeout(timeout) { - Ok(n) => { - assert_eq!(n, 1usize); - recv_count += 1; - } - Err(RecvTimeoutError::Timeout) => continue, - Err(RecvTimeoutError::Disconnected) => break, - } - } - - assert_eq!(recv_count, stress); -} - -#[test] -fn recv_timeout_upgrade() { - let (tx, rx) = channel::<()>(); - let timeout = Duration::from_millis(1); - let _tx_clone = tx.clone(); - - let start = Instant::now(); - assert_eq!(rx.recv_timeout(timeout), Err(RecvTimeoutError::Timeout)); - assert!(Instant::now() >= start + timeout); -} - -#[test] -fn stress_recv_timeout_shared() { - let (tx, rx) = channel(); - let stress = stress_factor() + 100; - - for i in 0..stress { - let tx = tx.clone(); - thread::spawn(move || { - thread::sleep(Duration::from_millis(i as u64 * 10)); - tx.send(1usize).unwrap(); - }); - } - - drop(tx); - - let mut recv_count = 0; - loop { - match rx.recv_timeout(Duration::from_millis(10)) { - Ok(n) => { - assert_eq!(n, 1usize); - recv_count += 1; - } - Err(RecvTimeoutError::Timeout) => continue, - Err(RecvTimeoutError::Disconnected) => break, - } - } - - assert_eq!(recv_count, stress); -} - -#[test] -fn very_long_recv_timeout_wont_panic() { - let (tx, rx) = channel::<()>(); - let join_handle = thread::spawn(move || rx.recv_timeout(Duration::from_secs(u64::MAX))); - thread::sleep(Duration::from_secs(1)); - assert!(tx.send(()).is_ok()); - assert_eq!(join_handle.join().unwrap(), Ok(())); -} - -#[test] -fn recv_a_lot() { - let count = if cfg!(miri) { 1000 } else { 10000 }; - // Regression test that we don't run out of stack in scheduler context - let (tx, rx) = channel(); - for _ in 0..count { - tx.send(()).unwrap(); - } - for _ in 0..count { - rx.recv().unwrap(); - } -} - -#[test] -fn shared_recv_timeout() { - let (tx, rx) = channel(); - let total = 5; - for _ in 0..total { - let tx = tx.clone(); - thread::spawn(move || { - tx.send(()).unwrap(); - }); - } - - for _ in 0..total { - rx.recv().unwrap(); - } - - assert_eq!(rx.recv_timeout(Duration::from_millis(1)), Err(RecvTimeoutError::Timeout)); - tx.send(()).unwrap(); - assert_eq!(rx.recv_timeout(Duration::from_millis(1)), Ok(())); -} - -#[test] -fn shared_chan_stress() { - let (tx, rx) = channel(); - let total = stress_factor() + 100; - for _ in 0..total { - let tx = tx.clone(); - thread::spawn(move || { - tx.send(()).unwrap(); - }); - } - - for _ in 0..total { - rx.recv().unwrap(); - } -} - -#[test] -fn test_nested_recv_iter() { - let (tx, rx) = channel::(); - let (total_tx, total_rx) = channel::(); - - let _t = thread::spawn(move || { - let mut acc = 0; - for x in rx.iter() { - acc += x; - } - total_tx.send(acc).unwrap(); - }); - - tx.send(3).unwrap(); - tx.send(1).unwrap(); - tx.send(2).unwrap(); - drop(tx); - assert_eq!(total_rx.recv().unwrap(), 6); -} - -#[test] -fn test_recv_iter_break() { - let (tx, rx) = channel::(); - let (count_tx, count_rx) = channel(); - - let _t = thread::spawn(move || { - let mut count = 0; - for x in rx.iter() { - if count >= 3 { - break; - } else { - count += x; - } - } - count_tx.send(count).unwrap(); - }); - - tx.send(2).unwrap(); - tx.send(2).unwrap(); - tx.send(2).unwrap(); - let _ = tx.send(2); - drop(tx); - assert_eq!(count_rx.recv().unwrap(), 4); -} - -#[test] -fn test_recv_try_iter() { - let (request_tx, request_rx) = channel(); - let (response_tx, response_rx) = channel(); - - // Request `x`s until we have `6`. - let t = thread::spawn(move || { - let mut count = 0; - loop { - for x in response_rx.try_iter() { - count += x; - if count == 6 { - return count; - } - } - request_tx.send(()).unwrap(); - } - }); - - for _ in request_rx.iter() { - if response_tx.send(2).is_err() { - break; - } - } - - assert_eq!(t.join().unwrap(), 6); -} - -#[test] -fn test_recv_into_iter_owned() { - let mut iter = { - let (tx, rx) = channel::(); - tx.send(1).unwrap(); - tx.send(2).unwrap(); - - rx.into_iter() - }; - assert_eq!(iter.next().unwrap(), 1); - assert_eq!(iter.next().unwrap(), 2); - assert_eq!(iter.next().is_none(), true); -} - -#[test] -fn test_recv_into_iter_borrowed() { - let (tx, rx) = channel::(); - tx.send(1).unwrap(); - tx.send(2).unwrap(); - drop(tx); - let mut iter = (&rx).into_iter(); - assert_eq!(iter.next().unwrap(), 1); - assert_eq!(iter.next().unwrap(), 2); - assert_eq!(iter.next().is_none(), true); -} - -#[test] -fn try_recv_states() { - let (tx1, rx1) = channel::(); - let (tx2, rx2) = channel::<()>(); - let (tx3, rx3) = channel::<()>(); - let _t = thread::spawn(move || { - rx2.recv().unwrap(); - tx1.send(1).unwrap(); - tx3.send(()).unwrap(); - rx2.recv().unwrap(); - drop(tx1); - tx3.send(()).unwrap(); - }); - - assert_eq!(rx1.try_recv(), Err(TryRecvError::Empty)); - tx2.send(()).unwrap(); - rx3.recv().unwrap(); - assert_eq!(rx1.try_recv(), Ok(1)); - assert_eq!(rx1.try_recv(), Err(TryRecvError::Empty)); - tx2.send(()).unwrap(); - rx3.recv().unwrap(); - assert_eq!(rx1.try_recv(), Err(TryRecvError::Disconnected)); -} - -// This bug used to end up in a livelock inside of the Receiver destructor -// because the internal state of the Shared packet was corrupted -#[test] -fn destroy_upgraded_shared_port_when_sender_still_active() { - let (tx, rx) = channel(); - let (tx2, rx2) = channel(); - let _t = thread::spawn(move || { - rx.recv().unwrap(); // wait on a oneshot - drop(rx); // destroy a shared - tx2.send(()).unwrap(); - }); - // make sure the other thread has gone to sleep - for _ in 0..5000 { - thread::yield_now(); - } - - // upgrade to a shared chan and send a message - let t = tx.clone(); - drop(tx); - t.send(()).unwrap(); - - // wait for the child thread to exit before we exit - rx2.recv().unwrap(); -} - -#[test] -fn issue_32114() { - let (tx, _) = channel(); - let _ = tx.send(123); - assert_eq!(tx.send(123), Err(SendError(123))); -} - -#[test] -fn issue_39364() { - let (tx, rx) = channel::<()>(); - let t = thread::spawn(move || { - thread::sleep(Duration::from_millis(300)); - let _ = tx.clone(); - // Don't drop; hand back to caller. - tx - }); - - let _ = rx.recv_timeout(Duration::from_millis(500)); - let _tx = t.join().unwrap(); // delay dropping until end of test - let _ = rx.recv_timeout(Duration::from_millis(500)); -} diff --git a/library/std/src/sync/mutex.rs b/library/std/src/sync/mutex.rs deleted file mode 100644 index d417034f5af85..0000000000000 --- a/library/std/src/sync/mutex.rs +++ /dev/null @@ -1,751 +0,0 @@ -#[cfg(all(test, not(target_os = "emscripten")))] -mod tests; - -use crate::cell::UnsafeCell; -use crate::fmt; -use crate::marker::PhantomData; -use crate::mem::ManuallyDrop; -use crate::ops::{Deref, DerefMut}; -use crate::ptr::NonNull; -use crate::sync::{poison, LockResult, TryLockError, TryLockResult}; -use crate::sys::sync as sys; - -/// A mutual exclusion primitive useful for protecting shared data -/// -/// This mutex will block threads waiting for the lock to become available. The -/// mutex can be created via a [`new`] constructor. Each mutex has a type parameter -/// which represents the data that it is protecting. The data can only be accessed -/// through the RAII guards returned from [`lock`] and [`try_lock`], which -/// guarantees that the data is only ever accessed when the mutex is locked. -/// -/// # Poisoning -/// -/// The mutexes in this module implement a strategy called "poisoning" where a -/// mutex is considered poisoned whenever a thread panics while holding the -/// mutex. Once a mutex is poisoned, all other threads are unable to access the -/// data by default as it is likely tainted (some invariant is not being -/// upheld). -/// -/// For a mutex, this means that the [`lock`] and [`try_lock`] methods return a -/// [`Result`] which indicates whether a mutex has been poisoned or not. Most -/// usage of a mutex will simply [`unwrap()`] these results, propagating panics -/// among threads to ensure that a possibly invalid invariant is not witnessed. -/// -/// A poisoned mutex, however, does not prevent all access to the underlying -/// data. The [`PoisonError`] type has an [`into_inner`] method which will return -/// the guard that would have otherwise been returned on a successful lock. This -/// allows access to the data, despite the lock being poisoned. -/// -/// [`new`]: Self::new -/// [`lock`]: Self::lock -/// [`try_lock`]: Self::try_lock -/// [`unwrap()`]: Result::unwrap -/// [`PoisonError`]: super::PoisonError -/// [`into_inner`]: super::PoisonError::into_inner -/// -/// # Examples -/// -/// ``` -/// use std::sync::{Arc, Mutex}; -/// use std::thread; -/// use std::sync::mpsc::channel; -/// -/// const N: usize = 10; -/// -/// // Spawn a few threads to increment a shared variable (non-atomically), and -/// // let the main thread know once all increments are done. -/// // -/// // Here we're using an Arc to share memory among threads, and the data inside -/// // the Arc is protected with a mutex. -/// let data = Arc::new(Mutex::new(0)); -/// -/// let (tx, rx) = channel(); -/// for _ in 0..N { -/// let (data, tx) = (Arc::clone(&data), tx.clone()); -/// thread::spawn(move || { -/// // The shared state can only be accessed once the lock is held. -/// // Our non-atomic increment is safe because we're the only thread -/// // which can access the shared state when the lock is held. -/// // -/// // We unwrap() the return value to assert that we are not expecting -/// // threads to ever fail while holding the lock. -/// let mut data = data.lock().unwrap(); -/// *data += 1; -/// if *data == N { -/// tx.send(()).unwrap(); -/// } -/// // the lock is unlocked here when `data` goes out of scope. -/// }); -/// } -/// -/// rx.recv().unwrap(); -/// ``` -/// -/// To recover from a poisoned mutex: -/// -/// ``` -/// use std::sync::{Arc, Mutex}; -/// use std::thread; -/// -/// let lock = Arc::new(Mutex::new(0_u32)); -/// let lock2 = Arc::clone(&lock); -/// -/// let _ = thread::spawn(move || -> () { -/// // This thread will acquire the mutex first, unwrapping the result of -/// // `lock` because the lock has not been poisoned. -/// let _guard = lock2.lock().unwrap(); -/// -/// // This panic while holding the lock (`_guard` is in scope) will poison -/// // the mutex. -/// panic!(); -/// }).join(); -/// -/// // The lock is poisoned by this point, but the returned result can be -/// // pattern matched on to return the underlying guard on both branches. -/// let mut guard = match lock.lock() { -/// Ok(guard) => guard, -/// Err(poisoned) => poisoned.into_inner(), -/// }; -/// -/// *guard += 1; -/// ``` -/// -/// To unlock a mutex guard sooner than the end of the enclosing scope, -/// either create an inner scope or drop the guard manually. -/// -/// ``` -/// use std::sync::{Arc, Mutex}; -/// use std::thread; -/// -/// const N: usize = 3; -/// -/// let data_mutex = Arc::new(Mutex::new(vec![1, 2, 3, 4])); -/// let res_mutex = Arc::new(Mutex::new(0)); -/// -/// let mut threads = Vec::with_capacity(N); -/// (0..N).for_each(|_| { -/// let data_mutex_clone = Arc::clone(&data_mutex); -/// let res_mutex_clone = Arc::clone(&res_mutex); -/// -/// threads.push(thread::spawn(move || { -/// // Here we use a block to limit the lifetime of the lock guard. -/// let result = { -/// let mut data = data_mutex_clone.lock().unwrap(); -/// // This is the result of some important and long-ish work. -/// let result = data.iter().fold(0, |acc, x| acc + x * 2); -/// data.push(result); -/// result -/// // The mutex guard gets dropped here, together with any other values -/// // created in the critical section. -/// }; -/// // The guard created here is a temporary dropped at the end of the statement, i.e. -/// // the lock would not remain being held even if the thread did some additional work. -/// *res_mutex_clone.lock().unwrap() += result; -/// })); -/// }); -/// -/// let mut data = data_mutex.lock().unwrap(); -/// // This is the result of some important and long-ish work. -/// let result = data.iter().fold(0, |acc, x| acc + x * 2); -/// data.push(result); -/// // We drop the `data` explicitly because it's not necessary anymore and the -/// // thread still has work to do. This allows other threads to start working on -/// // the data immediately, without waiting for the rest of the unrelated work -/// // to be done here. -/// // -/// // It's even more important here than in the threads because we `.join` the -/// // threads after that. If we had not dropped the mutex guard, a thread could -/// // be waiting forever for it, causing a deadlock. -/// // As in the threads, a block could have been used instead of calling the -/// // `drop` function. -/// drop(data); -/// // Here the mutex guard is not assigned to a variable and so, even if the -/// // scope does not end after this line, the mutex is still released: there is -/// // no deadlock. -/// *res_mutex.lock().unwrap() += result; -/// -/// threads.into_iter().for_each(|thread| { -/// thread -/// .join() -/// .expect("The thread creating or execution failed !") -/// }); -/// -/// assert_eq!(*res_mutex.lock().unwrap(), 800); -/// ``` -/// -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "Mutex")] -pub struct Mutex { - inner: sys::Mutex, - poison: poison::Flag, - data: UnsafeCell, -} - -// these are the only places where `T: Send` matters; all other -// functionality works fine on a single thread. -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Send for Mutex {} -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Sync for Mutex {} - -/// An RAII implementation of a "scoped lock" of a mutex. When this structure is -/// dropped (falls out of scope), the lock will be unlocked. -/// -/// The data protected by the mutex can be accessed through this guard via its -/// [`Deref`] and [`DerefMut`] implementations. -/// -/// This structure is created by the [`lock`] and [`try_lock`] methods on -/// [`Mutex`]. -/// -/// [`lock`]: Mutex::lock -/// [`try_lock`]: Mutex::try_lock -#[must_use = "if unused the Mutex will immediately unlock"] -#[must_not_suspend = "holding a MutexGuard across suspend \ - points can cause deadlocks, delays, \ - and cause Futures to not implement `Send`"] -#[stable(feature = "rust1", since = "1.0.0")] -#[clippy::has_significant_drop] -#[cfg_attr(not(test), rustc_diagnostic_item = "MutexGuard")] -pub struct MutexGuard<'a, T: ?Sized + 'a> { - lock: &'a Mutex, - poison: poison::Guard, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl !Send for MutexGuard<'_, T> {} -#[stable(feature = "mutexguard", since = "1.19.0")] -unsafe impl Sync for MutexGuard<'_, T> {} - -/// An RAII mutex guard returned by `MutexGuard::map`, which can point to a -/// subfield of the protected data. When this structure is dropped (falls out -/// of scope), the lock will be unlocked. -/// -/// The main difference between `MappedMutexGuard` and [`MutexGuard`] is that the -/// former cannot be used with [`Condvar`], since that -/// could introduce soundness issues if the locked object is modified by another -/// thread while the `Mutex` is unlocked. -/// -/// The data protected by the mutex can be accessed through this guard via its -/// [`Deref`] and [`DerefMut`] implementations. -/// -/// This structure is created by the [`map`] and [`try_map`] methods on -/// [`MutexGuard`]. -/// -/// [`map`]: MutexGuard::map -/// [`try_map`]: MutexGuard::try_map -/// [`Condvar`]: crate::sync::Condvar -#[must_use = "if unused the Mutex will immediately unlock"] -#[must_not_suspend = "holding a MappedMutexGuard across suspend \ - points can cause deadlocks, delays, \ - and cause Futures to not implement `Send`"] -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -#[clippy::has_significant_drop] -pub struct MappedMutexGuard<'a, T: ?Sized + 'a> { - // NB: we use a pointer instead of `&'a mut T` to avoid `noalias` violations, because a - // `MappedMutexGuard` argument doesn't hold uniqueness for its whole scope, only until it drops. - // `NonNull` is covariant over `T`, so we add a `PhantomData<&'a mut T>` field - // below for the correct variance over `T` (invariance). - data: NonNull, - inner: &'a sys::Mutex, - poison_flag: &'a poison::Flag, - poison: poison::Guard, - _variance: PhantomData<&'a mut T>, -} - -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -impl !Send for MappedMutexGuard<'_, T> {} -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -unsafe impl Sync for MappedMutexGuard<'_, T> {} - -impl Mutex { - /// Creates a new mutex in an unlocked state ready for use. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Mutex; - /// - /// let mutex = Mutex::new(0); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_locks", since = "1.63.0")] - #[inline] - pub const fn new(t: T) -> Mutex { - Mutex { inner: sys::Mutex::new(), poison: poison::Flag::new(), data: UnsafeCell::new(t) } - } -} - -impl Mutex { - /// Acquires a mutex, blocking the current thread until it is able to do so. - /// - /// This function will block the local thread until it is available to acquire - /// the mutex. Upon returning, the thread is the only thread with the lock - /// held. An RAII guard is returned to allow scoped unlock of the lock. When - /// the guard goes out of scope, the mutex will be unlocked. - /// - /// The exact behavior on locking a mutex in the thread which already holds - /// the lock is left unspecified. However, this function will not return on - /// the second call (it might panic or deadlock, for example). - /// - /// # Errors - /// - /// If another user of this mutex panicked while holding the mutex, then - /// this call will return an error once the mutex is acquired. - /// - /// # Panics - /// - /// This function might panic when called if the lock is already held by - /// the current thread. - /// - /// # Examples - /// - /// ``` - /// use std::sync::{Arc, Mutex}; - /// use std::thread; - /// - /// let mutex = Arc::new(Mutex::new(0)); - /// let c_mutex = Arc::clone(&mutex); - /// - /// thread::spawn(move || { - /// *c_mutex.lock().unwrap() = 10; - /// }).join().expect("thread::spawn failed"); - /// assert_eq!(*mutex.lock().unwrap(), 10); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn lock(&self) -> LockResult> { - unsafe { - self.inner.lock(); - MutexGuard::new(self) - } - } - - /// Attempts to acquire this lock. - /// - /// If the lock could not be acquired at this time, then [`Err`] is returned. - /// Otherwise, an RAII guard is returned. The lock will be unlocked when the - /// guard is dropped. - /// - /// This function does not block. - /// - /// # Errors - /// - /// If another user of this mutex panicked while holding the mutex, then - /// this call will return the [`Poisoned`] error if the mutex would - /// otherwise be acquired. - /// - /// If the mutex could not be acquired because it is already locked, then - /// this call will return the [`WouldBlock`] error. - /// - /// [`Poisoned`]: TryLockError::Poisoned - /// [`WouldBlock`]: TryLockError::WouldBlock - /// - /// # Examples - /// - /// ``` - /// use std::sync::{Arc, Mutex}; - /// use std::thread; - /// - /// let mutex = Arc::new(Mutex::new(0)); - /// let c_mutex = Arc::clone(&mutex); - /// - /// thread::spawn(move || { - /// let mut lock = c_mutex.try_lock(); - /// if let Ok(ref mut mutex) = lock { - /// **mutex = 10; - /// } else { - /// println!("try_lock failed"); - /// } - /// }).join().expect("thread::spawn failed"); - /// assert_eq!(*mutex.lock().unwrap(), 10); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn try_lock(&self) -> TryLockResult> { - unsafe { - if self.inner.try_lock() { - Ok(MutexGuard::new(self)?) - } else { - Err(TryLockError::WouldBlock) - } - } - } - - /// Determines whether the mutex is poisoned. - /// - /// If another thread is active, the mutex can still become poisoned at any - /// time. You should not trust a `false` value for program correctness - /// without additional synchronization. - /// - /// # Examples - /// - /// ``` - /// use std::sync::{Arc, Mutex}; - /// use std::thread; - /// - /// let mutex = Arc::new(Mutex::new(0)); - /// let c_mutex = Arc::clone(&mutex); - /// - /// let _ = thread::spawn(move || { - /// let _lock = c_mutex.lock().unwrap(); - /// panic!(); // the mutex gets poisoned - /// }).join(); - /// assert_eq!(mutex.is_poisoned(), true); - /// ``` - #[inline] - #[stable(feature = "sync_poison", since = "1.2.0")] - pub fn is_poisoned(&self) -> bool { - self.poison.get() - } - - /// Clear the poisoned state from a mutex. - /// - /// If the mutex is poisoned, it will remain poisoned until this function is called. This - /// allows recovering from a poisoned state and marking that it has recovered. For example, if - /// the value is overwritten by a known-good value, then the mutex can be marked as - /// un-poisoned. Or possibly, the value could be inspected to determine if it is in a - /// consistent state, and if so the poison is removed. - /// - /// # Examples - /// - /// ``` - /// use std::sync::{Arc, Mutex}; - /// use std::thread; - /// - /// let mutex = Arc::new(Mutex::new(0)); - /// let c_mutex = Arc::clone(&mutex); - /// - /// let _ = thread::spawn(move || { - /// let _lock = c_mutex.lock().unwrap(); - /// panic!(); // the mutex gets poisoned - /// }).join(); - /// - /// assert_eq!(mutex.is_poisoned(), true); - /// let x = mutex.lock().unwrap_or_else(|mut e| { - /// **e.get_mut() = 1; - /// mutex.clear_poison(); - /// e.into_inner() - /// }); - /// assert_eq!(mutex.is_poisoned(), false); - /// assert_eq!(*x, 1); - /// ``` - #[inline] - #[stable(feature = "mutex_unpoison", since = "1.77.0")] - pub fn clear_poison(&self) { - self.poison.clear(); - } - - /// Consumes this mutex, returning the underlying data. - /// - /// # Errors - /// - /// If another user of this mutex panicked while holding the mutex, then - /// this call will return an error instead. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Mutex; - /// - /// let mutex = Mutex::new(0); - /// assert_eq!(mutex.into_inner().unwrap(), 0); - /// ``` - #[stable(feature = "mutex_into_inner", since = "1.6.0")] - pub fn into_inner(self) -> LockResult - where - T: Sized, - { - let data = self.data.into_inner(); - poison::map_result(self.poison.borrow(), |()| data) - } - - /// Returns a mutable reference to the underlying data. - /// - /// Since this call borrows the `Mutex` mutably, no actual locking needs to - /// take place -- the mutable borrow statically guarantees no locks exist. - /// - /// # Errors - /// - /// If another user of this mutex panicked while holding the mutex, then - /// this call will return an error instead. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Mutex; - /// - /// let mut mutex = Mutex::new(0); - /// *mutex.get_mut().unwrap() = 10; - /// assert_eq!(*mutex.lock().unwrap(), 10); - /// ``` - #[stable(feature = "mutex_get_mut", since = "1.6.0")] - pub fn get_mut(&mut self) -> LockResult<&mut T> { - let data = self.data.get_mut(); - poison::map_result(self.poison.borrow(), |()| data) - } -} - -#[stable(feature = "mutex_from", since = "1.24.0")] -impl From for Mutex { - /// Creates a new mutex in an unlocked state ready for use. - /// This is equivalent to [`Mutex::new`]. - fn from(t: T) -> Self { - Mutex::new(t) - } -} - -#[stable(feature = "mutex_default", since = "1.10.0")] -impl Default for Mutex { - /// Creates a `Mutex`, with the `Default` value for T. - fn default() -> Mutex { - Mutex::new(Default::default()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for Mutex { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let mut d = f.debug_struct("Mutex"); - match self.try_lock() { - Ok(guard) => { - d.field("data", &&*guard); - } - Err(TryLockError::Poisoned(err)) => { - d.field("data", &&**err.get_ref()); - } - Err(TryLockError::WouldBlock) => { - d.field("data", &format_args!("")); - } - } - d.field("poisoned", &self.poison.get()); - d.finish_non_exhaustive() - } -} - -impl<'mutex, T: ?Sized> MutexGuard<'mutex, T> { - unsafe fn new(lock: &'mutex Mutex) -> LockResult> { - poison::map_result(lock.poison.guard(), |guard| MutexGuard { lock, poison: guard }) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Deref for MutexGuard<'_, T> { - type Target = T; - - fn deref(&self) -> &T { - unsafe { &*self.lock.data.get() } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DerefMut for MutexGuard<'_, T> { - fn deref_mut(&mut self) -> &mut T { - unsafe { &mut *self.lock.data.get() } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Drop for MutexGuard<'_, T> { - #[inline] - fn drop(&mut self) { - unsafe { - self.lock.poison.done(&self.poison); - self.lock.inner.unlock(); - } - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for MutexGuard<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&**self, f) - } -} - -#[stable(feature = "std_guard_impls", since = "1.20.0")] -impl fmt::Display for MutexGuard<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - (**self).fmt(f) - } -} - -pub fn guard_lock<'a, T: ?Sized>(guard: &MutexGuard<'a, T>) -> &'a sys::Mutex { - &guard.lock.inner -} - -pub fn guard_poison<'a, T: ?Sized>(guard: &MutexGuard<'a, T>) -> &'a poison::Flag { - &guard.lock.poison -} - -impl<'a, T: ?Sized> MutexGuard<'a, T> { - /// Makes a [`MappedMutexGuard`] for a component of the borrowed data, e.g. - /// an enum variant. - /// - /// The `Mutex` is already locked, so this cannot fail. - /// - /// This is an associated function that needs to be used as - /// `MutexGuard::map(...)`. A method would interfere with methods of the - /// same name on the contents of the `MutexGuard` used through `Deref`. - #[unstable(feature = "mapped_lock_guards", issue = "117108")] - pub fn map(orig: Self, f: F) -> MappedMutexGuard<'a, U> - where - F: FnOnce(&mut T) -> &mut U, - U: ?Sized, - { - // SAFETY: the conditions of `MutexGuard::new` were satisfied when the original guard - // was created, and have been upheld throughout `map` and/or `try_map`. - // The signature of the closure guarantees that it will not "leak" the lifetime of the reference - // passed to it. If the closure panics, the guard will be dropped. - let data = NonNull::from(f(unsafe { &mut *orig.lock.data.get() })); - let orig = ManuallyDrop::new(orig); - MappedMutexGuard { - data, - inner: &orig.lock.inner, - poison_flag: &orig.lock.poison, - poison: orig.poison.clone(), - _variance: PhantomData, - } - } - - /// Makes a [`MappedMutexGuard`] for a component of the borrowed data. The - /// original guard is returned as an `Err(...)` if the closure returns - /// `None`. - /// - /// The `Mutex` is already locked, so this cannot fail. - /// - /// This is an associated function that needs to be used as - /// `MutexGuard::try_map(...)`. A method would interfere with methods of the - /// same name on the contents of the `MutexGuard` used through `Deref`. - #[doc(alias = "filter_map")] - #[unstable(feature = "mapped_lock_guards", issue = "117108")] - pub fn try_map(orig: Self, f: F) -> Result, Self> - where - F: FnOnce(&mut T) -> Option<&mut U>, - U: ?Sized, - { - // SAFETY: the conditions of `MutexGuard::new` were satisfied when the original guard - // was created, and have been upheld throughout `map` and/or `try_map`. - // The signature of the closure guarantees that it will not "leak" the lifetime of the reference - // passed to it. If the closure panics, the guard will be dropped. - match f(unsafe { &mut *orig.lock.data.get() }) { - Some(data) => { - let data = NonNull::from(data); - let orig = ManuallyDrop::new(orig); - Ok(MappedMutexGuard { - data, - inner: &orig.lock.inner, - poison_flag: &orig.lock.poison, - poison: orig.poison.clone(), - _variance: PhantomData, - }) - } - None => Err(orig), - } - } -} - -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -impl Deref for MappedMutexGuard<'_, T> { - type Target = T; - - fn deref(&self) -> &T { - unsafe { self.data.as_ref() } - } -} - -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -impl DerefMut for MappedMutexGuard<'_, T> { - fn deref_mut(&mut self) -> &mut T { - unsafe { self.data.as_mut() } - } -} - -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -impl Drop for MappedMutexGuard<'_, T> { - #[inline] - fn drop(&mut self) { - unsafe { - self.poison_flag.done(&self.poison); - self.inner.unlock(); - } - } -} - -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -impl fmt::Debug for MappedMutexGuard<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&**self, f) - } -} - -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -impl fmt::Display for MappedMutexGuard<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - (**self).fmt(f) - } -} - -impl<'a, T: ?Sized> MappedMutexGuard<'a, T> { - /// Makes a [`MappedMutexGuard`] for a component of the borrowed data, e.g. - /// an enum variant. - /// - /// The `Mutex` is already locked, so this cannot fail. - /// - /// This is an associated function that needs to be used as - /// `MappedMutexGuard::map(...)`. A method would interfere with methods of the - /// same name on the contents of the `MutexGuard` used through `Deref`. - #[unstable(feature = "mapped_lock_guards", issue = "117108")] - pub fn map(mut orig: Self, f: F) -> MappedMutexGuard<'a, U> - where - F: FnOnce(&mut T) -> &mut U, - U: ?Sized, - { - // SAFETY: the conditions of `MutexGuard::new` were satisfied when the original guard - // was created, and have been upheld throughout `map` and/or `try_map`. - // The signature of the closure guarantees that it will not "leak" the lifetime of the reference - // passed to it. If the closure panics, the guard will be dropped. - let data = NonNull::from(f(unsafe { orig.data.as_mut() })); - let orig = ManuallyDrop::new(orig); - MappedMutexGuard { - data, - inner: orig.inner, - poison_flag: orig.poison_flag, - poison: orig.poison.clone(), - _variance: PhantomData, - } - } - - /// Makes a [`MappedMutexGuard`] for a component of the borrowed data. The - /// original guard is returned as an `Err(...)` if the closure returns - /// `None`. - /// - /// The `Mutex` is already locked, so this cannot fail. - /// - /// This is an associated function that needs to be used as - /// `MappedMutexGuard::try_map(...)`. A method would interfere with methods of the - /// same name on the contents of the `MutexGuard` used through `Deref`. - #[doc(alias = "filter_map")] - #[unstable(feature = "mapped_lock_guards", issue = "117108")] - pub fn try_map(mut orig: Self, f: F) -> Result, Self> - where - F: FnOnce(&mut T) -> Option<&mut U>, - U: ?Sized, - { - // SAFETY: the conditions of `MutexGuard::new` were satisfied when the original guard - // was created, and have been upheld throughout `map` and/or `try_map`. - // The signature of the closure guarantees that it will not "leak" the lifetime of the reference - // passed to it. If the closure panics, the guard will be dropped. - match f(unsafe { orig.data.as_mut() }) { - Some(data) => { - let data = NonNull::from(data); - let orig = ManuallyDrop::new(orig); - Ok(MappedMutexGuard { - data, - inner: orig.inner, - poison_flag: orig.poison_flag, - poison: orig.poison.clone(), - _variance: PhantomData, - }) - } - None => Err(orig), - } - } -} diff --git a/library/std/src/sync/mutex/tests.rs b/library/std/src/sync/mutex/tests.rs deleted file mode 100644 index 19ec096c59334..0000000000000 --- a/library/std/src/sync/mutex/tests.rs +++ /dev/null @@ -1,327 +0,0 @@ -use crate::sync::atomic::{AtomicUsize, Ordering}; -use crate::sync::mpsc::channel; -use crate::sync::{Arc, Condvar, MappedMutexGuard, Mutex, MutexGuard, TryLockError}; -use crate::thread; - -struct Packet(Arc<(Mutex, Condvar)>); - -#[derive(Eq, PartialEq, Debug)] -struct NonCopy(i32); - -#[test] -fn smoke() { - let m = Mutex::new(()); - drop(m.lock().unwrap()); - drop(m.lock().unwrap()); -} - -#[test] -fn lots_and_lots() { - const J: u32 = 1000; - const K: u32 = 3; - - let m = Arc::new(Mutex::new(0)); - - fn inc(m: &Mutex) { - for _ in 0..J { - *m.lock().unwrap() += 1; - } - } - - let (tx, rx) = channel(); - for _ in 0..K { - let tx2 = tx.clone(); - let m2 = m.clone(); - thread::spawn(move || { - inc(&m2); - tx2.send(()).unwrap(); - }); - let tx2 = tx.clone(); - let m2 = m.clone(); - thread::spawn(move || { - inc(&m2); - tx2.send(()).unwrap(); - }); - } - - drop(tx); - for _ in 0..2 * K { - rx.recv().unwrap(); - } - assert_eq!(*m.lock().unwrap(), J * K * 2); -} - -#[test] -fn try_lock() { - let m = Mutex::new(()); - *m.try_lock().unwrap() = (); -} - -#[test] -fn test_into_inner() { - let m = Mutex::new(NonCopy(10)); - assert_eq!(m.into_inner().unwrap(), NonCopy(10)); -} - -#[test] -fn test_into_inner_drop() { - struct Foo(Arc); - impl Drop for Foo { - fn drop(&mut self) { - self.0.fetch_add(1, Ordering::SeqCst); - } - } - let num_drops = Arc::new(AtomicUsize::new(0)); - let m = Mutex::new(Foo(num_drops.clone())); - assert_eq!(num_drops.load(Ordering::SeqCst), 0); - { - let _inner = m.into_inner().unwrap(); - assert_eq!(num_drops.load(Ordering::SeqCst), 0); - } - assert_eq!(num_drops.load(Ordering::SeqCst), 1); -} - -#[test] -fn test_into_inner_poison() { - let m = Arc::new(Mutex::new(NonCopy(10))); - let m2 = m.clone(); - let _ = thread::spawn(move || { - let _lock = m2.lock().unwrap(); - panic!("test panic in inner thread to poison mutex"); - }) - .join(); - - assert!(m.is_poisoned()); - match Arc::try_unwrap(m).unwrap().into_inner() { - Err(e) => assert_eq!(e.into_inner(), NonCopy(10)), - Ok(x) => panic!("into_inner of poisoned Mutex is Ok: {x:?}"), - } -} - -#[test] -fn test_get_mut() { - let mut m = Mutex::new(NonCopy(10)); - *m.get_mut().unwrap() = NonCopy(20); - assert_eq!(m.into_inner().unwrap(), NonCopy(20)); -} - -#[test] -fn test_get_mut_poison() { - let m = Arc::new(Mutex::new(NonCopy(10))); - let m2 = m.clone(); - let _ = thread::spawn(move || { - let _lock = m2.lock().unwrap(); - panic!("test panic in inner thread to poison mutex"); - }) - .join(); - - assert!(m.is_poisoned()); - match Arc::try_unwrap(m).unwrap().get_mut() { - Err(e) => assert_eq!(*e.into_inner(), NonCopy(10)), - Ok(x) => panic!("get_mut of poisoned Mutex is Ok: {x:?}"), - } -} - -#[test] -fn test_mutex_arc_condvar() { - let packet = Packet(Arc::new((Mutex::new(false), Condvar::new()))); - let packet2 = Packet(packet.0.clone()); - let (tx, rx) = channel(); - let _t = thread::spawn(move || { - // wait until parent gets in - rx.recv().unwrap(); - let &(ref lock, ref cvar) = &*packet2.0; - let mut lock = lock.lock().unwrap(); - *lock = true; - cvar.notify_one(); - }); - - let &(ref lock, ref cvar) = &*packet.0; - let mut lock = lock.lock().unwrap(); - tx.send(()).unwrap(); - assert!(!*lock); - while !*lock { - lock = cvar.wait(lock).unwrap(); - } -} - -#[test] -fn test_arc_condvar_poison() { - let packet = Packet(Arc::new((Mutex::new(1), Condvar::new()))); - let packet2 = Packet(packet.0.clone()); - let (tx, rx) = channel(); - - let _t = thread::spawn(move || -> () { - rx.recv().unwrap(); - let &(ref lock, ref cvar) = &*packet2.0; - let _g = lock.lock().unwrap(); - cvar.notify_one(); - // Parent should fail when it wakes up. - panic!(); - }); - - let &(ref lock, ref cvar) = &*packet.0; - let mut lock = lock.lock().unwrap(); - tx.send(()).unwrap(); - while *lock == 1 { - match cvar.wait(lock) { - Ok(l) => { - lock = l; - assert_eq!(*lock, 1); - } - Err(..) => break, - } - } -} - -#[test] -fn test_mutex_arc_poison() { - let arc = Arc::new(Mutex::new(1)); - assert!(!arc.is_poisoned()); - let arc2 = arc.clone(); - let _ = thread::spawn(move || { - let lock = arc2.lock().unwrap(); - assert_eq!(*lock, 2); // deliberate assertion failure to poison the mutex - }) - .join(); - assert!(arc.lock().is_err()); - assert!(arc.is_poisoned()); -} - -#[test] -fn test_mutex_arc_poison_mapped() { - let arc = Arc::new(Mutex::new(1)); - assert!(!arc.is_poisoned()); - let arc2 = arc.clone(); - let _ = thread::spawn(move || { - let lock = arc2.lock().unwrap(); - let lock = MutexGuard::map(lock, |val| val); - assert_eq!(*lock, 2); // deliberate assertion failure to poison the mutex - }) - .join(); - assert!(arc.lock().is_err()); - assert!(arc.is_poisoned()); -} - -#[test] -fn test_mutex_arc_nested() { - // Tests nested mutexes and access - // to underlying data. - let arc = Arc::new(Mutex::new(1)); - let arc2 = Arc::new(Mutex::new(arc)); - let (tx, rx) = channel(); - let _t = thread::spawn(move || { - let lock = arc2.lock().unwrap(); - let lock2 = lock.lock().unwrap(); - assert_eq!(*lock2, 1); - tx.send(()).unwrap(); - }); - rx.recv().unwrap(); -} - -#[test] -fn test_mutex_arc_access_in_unwind() { - let arc = Arc::new(Mutex::new(1)); - let arc2 = arc.clone(); - let _ = thread::spawn(move || -> () { - struct Unwinder { - i: Arc>, - } - impl Drop for Unwinder { - fn drop(&mut self) { - *self.i.lock().unwrap() += 1; - } - } - let _u = Unwinder { i: arc2 }; - panic!(); - }) - .join(); - let lock = arc.lock().unwrap(); - assert_eq!(*lock, 2); -} - -#[test] -fn test_mutex_unsized() { - let mutex: &Mutex<[i32]> = &Mutex::new([1, 2, 3]); - { - let b = &mut *mutex.lock().unwrap(); - b[0] = 4; - b[2] = 5; - } - let comp: &[i32] = &[4, 2, 5]; - assert_eq!(&*mutex.lock().unwrap(), comp); -} - -#[test] -fn test_mapping_mapped_guard() { - let arr = [0; 4]; - let mut lock = Mutex::new(arr); - let guard = lock.lock().unwrap(); - let guard = MutexGuard::map(guard, |arr| &mut arr[..2]); - let mut guard = MappedMutexGuard::map(guard, |slice| &mut slice[1..]); - assert_eq!(guard.len(), 1); - guard[0] = 42; - drop(guard); - assert_eq!(*lock.get_mut().unwrap(), [0, 42, 0, 0]); -} - -#[test] -fn panic_while_mapping_unlocked_poison() { - let lock = Mutex::new(()); - - let _ = crate::panic::catch_unwind(|| { - let guard = lock.lock().unwrap(); - let _guard = MutexGuard::map::<(), _>(guard, |_| panic!()); - }); - - match lock.try_lock() { - Ok(_) => panic!("panicking in a MutexGuard::map closure should poison the Mutex"), - Err(TryLockError::WouldBlock) => { - panic!("panicking in a MutexGuard::map closure should unlock the mutex") - } - Err(TryLockError::Poisoned(_)) => {} - } - - let _ = crate::panic::catch_unwind(|| { - let guard = lock.lock().unwrap(); - let _guard = MutexGuard::try_map::<(), _>(guard, |_| panic!()); - }); - - match lock.try_lock() { - Ok(_) => panic!("panicking in a MutexGuard::try_map closure should poison the Mutex"), - Err(TryLockError::WouldBlock) => { - panic!("panicking in a MutexGuard::try_map closure should unlock the mutex") - } - Err(TryLockError::Poisoned(_)) => {} - } - - let _ = crate::panic::catch_unwind(|| { - let guard = lock.lock().unwrap(); - let guard = MutexGuard::map::<(), _>(guard, |val| val); - let _guard = MappedMutexGuard::map::<(), _>(guard, |_| panic!()); - }); - - match lock.try_lock() { - Ok(_) => panic!("panicking in a MappedMutexGuard::map closure should poison the Mutex"), - Err(TryLockError::WouldBlock) => { - panic!("panicking in a MappedMutexGuard::map closure should unlock the mutex") - } - Err(TryLockError::Poisoned(_)) => {} - } - - let _ = crate::panic::catch_unwind(|| { - let guard = lock.lock().unwrap(); - let guard = MutexGuard::map::<(), _>(guard, |val| val); - let _guard = MappedMutexGuard::try_map::<(), _>(guard, |_| panic!()); - }); - - match lock.try_lock() { - Ok(_) => panic!("panicking in a MappedMutexGuard::try_map closure should poison the Mutex"), - Err(TryLockError::WouldBlock) => { - panic!("panicking in a MappedMutexGuard::try_map closure should unlock the mutex") - } - Err(TryLockError::Poisoned(_)) => {} - } - - drop(lock); -} diff --git a/library/std/src/sync/once.rs b/library/std/src/sync/once.rs deleted file mode 100644 index 608229fd674d8..0000000000000 --- a/library/std/src/sync/once.rs +++ /dev/null @@ -1,330 +0,0 @@ -//! A "once initialization" primitive -//! -//! This primitive is meant to be used to run one-time initialization. An -//! example use case would be for initializing an FFI library. - -#[cfg(all(test, not(target_os = "emscripten")))] -mod tests; - -use crate::fmt; -use crate::panic::{RefUnwindSafe, UnwindSafe}; -use crate::sys::sync as sys; - -/// A synchronization primitive which can be used to run a one-time global -/// initialization. Useful for one-time initialization for FFI or related -/// functionality. This type can only be constructed with [`Once::new()`]. -/// -/// # Examples -/// -/// ``` -/// use std::sync::Once; -/// -/// static START: Once = Once::new(); -/// -/// START.call_once(|| { -/// // run initialization here -/// }); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Once { - inner: sys::Once, -} - -#[stable(feature = "sync_once_unwind_safe", since = "1.59.0")] -impl UnwindSafe for Once {} - -#[stable(feature = "sync_once_unwind_safe", since = "1.59.0")] -impl RefUnwindSafe for Once {} - -/// State yielded to [`Once::call_once_force()`]’s closure parameter. The state -/// can be used to query the poison status of the [`Once`]. -#[stable(feature = "once_poison", since = "1.51.0")] -pub struct OnceState { - pub(crate) inner: sys::OnceState, -} - -pub(crate) enum ExclusiveState { - Incomplete, - Poisoned, - Complete, -} - -/// Initialization value for static [`Once`] values. -/// -/// # Examples -/// -/// ``` -/// use std::sync::{Once, ONCE_INIT}; -/// -/// static START: Once = ONCE_INIT; -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated( - since = "1.38.0", - note = "the `new` function is now preferred", - suggestion = "Once::new()" -)] -pub const ONCE_INIT: Once = Once::new(); - -impl Once { - /// Creates a new `Once` value. - #[inline] - #[stable(feature = "once_new", since = "1.2.0")] - #[rustc_const_stable(feature = "const_once_new", since = "1.32.0")] - #[must_use] - pub const fn new() -> Once { - Once { inner: sys::Once::new() } - } - - /// Performs an initialization routine once and only once. The given closure - /// will be executed if this is the first time `call_once` has been called, - /// and otherwise the routine will *not* be invoked. - /// - /// This method will block the calling thread if another initialization - /// routine is currently running. - /// - /// When this function returns, it is guaranteed that some initialization - /// has run and completed (it might not be the closure specified). It is also - /// guaranteed that any memory writes performed by the executed closure can - /// be reliably observed by other threads at this point (there is a - /// happens-before relation between the closure and code executing after the - /// return). - /// - /// If the given closure recursively invokes `call_once` on the same [`Once`] - /// instance, the exact behavior is not specified: allowed outcomes are - /// a panic or a deadlock. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Once; - /// - /// static mut VAL: usize = 0; - /// static INIT: Once = Once::new(); - /// - /// // Accessing a `static mut` is unsafe much of the time, but if we do so - /// // in a synchronized fashion (e.g., write once or read all) then we're - /// // good to go! - /// // - /// // This function will only call `expensive_computation` once, and will - /// // otherwise always return the value returned from the first invocation. - /// fn get_cached_val() -> usize { - /// unsafe { - /// INIT.call_once(|| { - /// VAL = expensive_computation(); - /// }); - /// VAL - /// } - /// } - /// - /// fn expensive_computation() -> usize { - /// // ... - /// # 2 - /// } - /// ``` - /// - /// # Panics - /// - /// The closure `f` will only be executed once even if this is called - /// concurrently amongst many threads. If that closure panics, however, then - /// it will *poison* this [`Once`] instance, causing all future invocations of - /// `call_once` to also panic. - /// - /// This is similar to [poisoning with mutexes][poison]. - /// - /// [poison]: struct.Mutex.html#poisoning - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[track_caller] - pub fn call_once(&self, f: F) - where - F: FnOnce(), - { - // Fast path check - if self.inner.is_completed() { - return; - } - - let mut f = Some(f); - self.inner.call(false, &mut |_| f.take().unwrap()()); - } - - /// Performs the same function as [`call_once()`] except ignores poisoning. - /// - /// Unlike [`call_once()`], if this [`Once`] has been poisoned (i.e., a previous - /// call to [`call_once()`] or [`call_once_force()`] caused a panic), calling - /// [`call_once_force()`] will still invoke the closure `f` and will _not_ - /// result in an immediate panic. If `f` panics, the [`Once`] will remain - /// in a poison state. If `f` does _not_ panic, the [`Once`] will no - /// longer be in a poison state and all future calls to [`call_once()`] or - /// [`call_once_force()`] will be no-ops. - /// - /// The closure `f` is yielded a [`OnceState`] structure which can be used - /// to query the poison status of the [`Once`]. - /// - /// [`call_once()`]: Once::call_once - /// [`call_once_force()`]: Once::call_once_force - /// - /// # Examples - /// - /// ``` - /// use std::sync::Once; - /// use std::thread; - /// - /// static INIT: Once = Once::new(); - /// - /// // poison the once - /// let handle = thread::spawn(|| { - /// INIT.call_once(|| panic!()); - /// }); - /// assert!(handle.join().is_err()); - /// - /// // poisoning propagates - /// let handle = thread::spawn(|| { - /// INIT.call_once(|| {}); - /// }); - /// assert!(handle.join().is_err()); - /// - /// // call_once_force will still run and reset the poisoned state - /// INIT.call_once_force(|state| { - /// assert!(state.is_poisoned()); - /// }); - /// - /// // once any success happens, we stop propagating the poison - /// INIT.call_once(|| {}); - /// ``` - #[inline] - #[stable(feature = "once_poison", since = "1.51.0")] - pub fn call_once_force(&self, f: F) - where - F: FnOnce(&OnceState), - { - // Fast path check - if self.inner.is_completed() { - return; - } - - let mut f = Some(f); - self.inner.call(true, &mut |p| f.take().unwrap()(p)); - } - - /// Returns `true` if some [`call_once()`] call has completed - /// successfully. Specifically, `is_completed` will return false in - /// the following situations: - /// * [`call_once()`] was not called at all, - /// * [`call_once()`] was called, but has not yet completed, - /// * the [`Once`] instance is poisoned - /// - /// This function returning `false` does not mean that [`Once`] has not been - /// executed. For example, it may have been executed in the time between - /// when `is_completed` starts executing and when it returns, in which case - /// the `false` return value would be stale (but still permissible). - /// - /// [`call_once()`]: Once::call_once - /// - /// # Examples - /// - /// ``` - /// use std::sync::Once; - /// - /// static INIT: Once = Once::new(); - /// - /// assert_eq!(INIT.is_completed(), false); - /// INIT.call_once(|| { - /// assert_eq!(INIT.is_completed(), false); - /// }); - /// assert_eq!(INIT.is_completed(), true); - /// ``` - /// - /// ``` - /// use std::sync::Once; - /// use std::thread; - /// - /// static INIT: Once = Once::new(); - /// - /// assert_eq!(INIT.is_completed(), false); - /// let handle = thread::spawn(|| { - /// INIT.call_once(|| panic!()); - /// }); - /// assert!(handle.join().is_err()); - /// assert_eq!(INIT.is_completed(), false); - /// ``` - #[stable(feature = "once_is_completed", since = "1.43.0")] - #[inline] - pub fn is_completed(&self) -> bool { - self.inner.is_completed() - } - - /// Returns the current state of the `Once` instance. - /// - /// Since this takes a mutable reference, no initialization can currently - /// be running, so the state must be either "incomplete", "poisoned" or - /// "complete". - #[inline] - pub(crate) fn state(&mut self) -> ExclusiveState { - self.inner.state() - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for Once { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Once").finish_non_exhaustive() - } -} - -impl OnceState { - /// Returns `true` if the associated [`Once`] was poisoned prior to the - /// invocation of the closure passed to [`Once::call_once_force()`]. - /// - /// # Examples - /// - /// A poisoned [`Once`]: - /// - /// ``` - /// use std::sync::Once; - /// use std::thread; - /// - /// static INIT: Once = Once::new(); - /// - /// // poison the once - /// let handle = thread::spawn(|| { - /// INIT.call_once(|| panic!()); - /// }); - /// assert!(handle.join().is_err()); - /// - /// INIT.call_once_force(|state| { - /// assert!(state.is_poisoned()); - /// }); - /// ``` - /// - /// An unpoisoned [`Once`]: - /// - /// ``` - /// use std::sync::Once; - /// - /// static INIT: Once = Once::new(); - /// - /// INIT.call_once_force(|state| { - /// assert!(!state.is_poisoned()); - /// }); - #[stable(feature = "once_poison", since = "1.51.0")] - #[inline] - pub fn is_poisoned(&self) -> bool { - self.inner.is_poisoned() - } - - /// Poison the associated [`Once`] without explicitly panicking. - // NOTE: This is currently only exposed for `OnceLock`. - #[inline] - pub(crate) fn poison(&self) { - self.inner.poison(); - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for OnceState { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("OnceState").field("poisoned", &self.is_poisoned()).finish() - } -} diff --git a/library/std/src/sync/once/tests.rs b/library/std/src/sync/once/tests.rs deleted file mode 100644 index 0c35597e11c51..0000000000000 --- a/library/std/src/sync/once/tests.rs +++ /dev/null @@ -1,116 +0,0 @@ -use super::Once; -use crate::panic; -use crate::sync::mpsc::channel; -use crate::thread; - -#[test] -fn smoke_once() { - static O: Once = Once::new(); - let mut a = 0; - O.call_once(|| a += 1); - assert_eq!(a, 1); - O.call_once(|| a += 1); - assert_eq!(a, 1); -} - -#[test] -fn stampede_once() { - static O: Once = Once::new(); - static mut RUN: bool = false; - - let (tx, rx) = channel(); - for _ in 0..10 { - let tx = tx.clone(); - thread::spawn(move || { - for _ in 0..4 { - thread::yield_now() - } - unsafe { - O.call_once(|| { - assert!(!RUN); - RUN = true; - }); - assert!(RUN); - } - tx.send(()).unwrap(); - }); - } - - unsafe { - O.call_once(|| { - assert!(!RUN); - RUN = true; - }); - assert!(RUN); - } - - for _ in 0..10 { - rx.recv().unwrap(); - } -} - -#[test] -fn poison_bad() { - static O: Once = Once::new(); - - // poison the once - let t = panic::catch_unwind(|| { - O.call_once(|| panic!()); - }); - assert!(t.is_err()); - - // poisoning propagates - let t = panic::catch_unwind(|| { - O.call_once(|| {}); - }); - assert!(t.is_err()); - - // we can subvert poisoning, however - let mut called = false; - O.call_once_force(|p| { - called = true; - assert!(p.is_poisoned()) - }); - assert!(called); - - // once any success happens, we stop propagating the poison - O.call_once(|| {}); -} - -#[test] -fn wait_for_force_to_finish() { - static O: Once = Once::new(); - - // poison the once - let t = panic::catch_unwind(|| { - O.call_once(|| panic!()); - }); - assert!(t.is_err()); - - // make sure someone's waiting inside the once via a force - let (tx1, rx1) = channel(); - let (tx2, rx2) = channel(); - let t1 = thread::spawn(move || { - O.call_once_force(|p| { - assert!(p.is_poisoned()); - tx1.send(()).unwrap(); - rx2.recv().unwrap(); - }); - }); - - rx1.recv().unwrap(); - - // put another waiter on the once - let t2 = thread::spawn(|| { - let mut called = false; - O.call_once(|| { - called = true; - }); - assert!(!called); - }); - - tx2.send(()).unwrap(); - - assert!(t1.join().is_ok()); - assert!(t2.join().is_ok()); -} diff --git a/library/std/src/sync/once_lock.rs b/library/std/src/sync/once_lock.rs deleted file mode 100644 index fc830baccedd2..0000000000000 --- a/library/std/src/sync/once_lock.rs +++ /dev/null @@ -1,605 +0,0 @@ -use crate::cell::UnsafeCell; -use crate::fmt; -use crate::marker::PhantomData; -use crate::mem::MaybeUninit; -use crate::panic::{RefUnwindSafe, UnwindSafe}; -use crate::sync::Once; - -/// A synchronization primitive which can be written to only once. -/// -/// This type is a thread-safe [`OnceCell`], and can be used in statics. -/// -/// [`OnceCell`]: crate::cell::OnceCell -/// -/// # Examples -/// -/// Using `OnceLock` to store a function’s previously computed value (a.k.a. -/// ‘lazy static’ or ‘memoizing’): -/// -/// ``` -/// use std::sync::OnceLock; -/// -/// struct DeepThought { -/// answer: String, -/// } -/// -/// impl DeepThought { -/// # fn great_question() -> String { -/// # "42".to_string() -/// # } -/// # -/// fn new() -> Self { -/// Self { -/// // M3 Ultra takes about 16 million years in --release config -/// answer: Self::great_question(), -/// } -/// } -/// } -/// -/// fn computation() -> &'static DeepThought { -/// // n.b. static items do not call [`Drop`] on program termination, so if -/// // [`DeepThought`] impls Drop, that will not be used for this instance. -/// static COMPUTATION: OnceLock = OnceLock::new(); -/// COMPUTATION.get_or_init(|| DeepThought::new()) -/// } -/// -/// // The `DeepThought` is built, stored in the `OnceLock`, and returned. -/// let _ = computation().answer; -/// // The `DeepThought` is retrieved from the `OnceLock` and returned. -/// let _ = computation().answer; -/// ``` -/// -/// Writing to a `OnceLock` from a separate thread: -/// -/// ``` -/// use std::sync::OnceLock; -/// -/// static CELL: OnceLock = OnceLock::new(); -/// -/// // `OnceLock` has not been written to yet. -/// assert!(CELL.get().is_none()); -/// -/// // Spawn a thread and write to `OnceLock`. -/// std::thread::spawn(|| { -/// let value = CELL.get_or_init(|| 12345); -/// assert_eq!(value, &12345); -/// }) -/// .join() -/// .unwrap(); -/// -/// // `OnceLock` now contains the value. -/// assert_eq!( -/// CELL.get(), -/// Some(&12345), -/// ); -/// ``` -#[stable(feature = "once_cell", since = "1.70.0")] -pub struct OnceLock { - once: Once, - // Whether or not the value is initialized is tracked by `once.is_completed()`. - value: UnsafeCell>, - /// `PhantomData` to make sure dropck understands we're dropping T in our Drop impl. - /// - /// ```compile_fail,E0597 - /// use std::sync::OnceLock; - /// - /// struct A<'a>(&'a str); - /// - /// impl<'a> Drop for A<'a> { - /// fn drop(&mut self) {} - /// } - /// - /// let cell = OnceLock::new(); - /// { - /// let s = String::new(); - /// let _ = cell.set(A(&s)); - /// } - /// ``` - _marker: PhantomData, -} - -impl OnceLock { - /// Creates a new empty cell. - #[inline] - #[must_use] - #[stable(feature = "once_cell", since = "1.70.0")] - #[rustc_const_stable(feature = "once_cell", since = "1.70.0")] - pub const fn new() -> OnceLock { - OnceLock { - once: Once::new(), - value: UnsafeCell::new(MaybeUninit::uninit()), - _marker: PhantomData, - } - } - - /// Gets the reference to the underlying value. - /// - /// Returns `None` if the cell is empty, or being initialized. This - /// method never blocks. - #[inline] - #[stable(feature = "once_cell", since = "1.70.0")] - pub fn get(&self) -> Option<&T> { - if self.is_initialized() { - // Safe b/c checked is_initialized - Some(unsafe { self.get_unchecked() }) - } else { - None - } - } - - /// Gets the mutable reference to the underlying value. - /// - /// Returns `None` if the cell is empty. This method never blocks. - #[inline] - #[stable(feature = "once_cell", since = "1.70.0")] - pub fn get_mut(&mut self) -> Option<&mut T> { - if self.is_initialized() { - // Safe b/c checked is_initialized and we have a unique access - Some(unsafe { self.get_unchecked_mut() }) - } else { - None - } - } - - /// Sets the contents of this cell to `value`. - /// - /// May block if another thread is currently attempting to initialize the cell. The cell is - /// guaranteed to contain a value when set returns, though not necessarily the one provided. - /// - /// Returns `Ok(())` if the cell's value was set by this call. - /// - /// # Examples - /// - /// ``` - /// use std::sync::OnceLock; - /// - /// static CELL: OnceLock = OnceLock::new(); - /// - /// fn main() { - /// assert!(CELL.get().is_none()); - /// - /// std::thread::spawn(|| { - /// assert_eq!(CELL.set(92), Ok(())); - /// }).join().unwrap(); - /// - /// assert_eq!(CELL.set(62), Err(62)); - /// assert_eq!(CELL.get(), Some(&92)); - /// } - /// ``` - #[inline] - #[stable(feature = "once_cell", since = "1.70.0")] - pub fn set(&self, value: T) -> Result<(), T> { - match self.try_insert(value) { - Ok(_) => Ok(()), - Err((_, value)) => Err(value), - } - } - - /// Sets the contents of this cell to `value` if the cell was empty, then - /// returns a reference to it. - /// - /// May block if another thread is currently attempting to initialize the cell. The cell is - /// guaranteed to contain a value when set returns, though not necessarily the one provided. - /// - /// Returns `Ok(&value)` if the cell was empty and `Err(¤t_value, value)` if it was full. - /// - /// # Examples - /// - /// ``` - /// #![feature(once_cell_try_insert)] - /// - /// use std::sync::OnceLock; - /// - /// static CELL: OnceLock = OnceLock::new(); - /// - /// fn main() { - /// assert!(CELL.get().is_none()); - /// - /// std::thread::spawn(|| { - /// assert_eq!(CELL.try_insert(92), Ok(&92)); - /// }).join().unwrap(); - /// - /// assert_eq!(CELL.try_insert(62), Err((&92, 62))); - /// assert_eq!(CELL.get(), Some(&92)); - /// } - /// ``` - #[inline] - #[unstable(feature = "once_cell_try_insert", issue = "116693")] - pub fn try_insert(&self, value: T) -> Result<&T, (&T, T)> { - let mut value = Some(value); - let res = self.get_or_init(|| value.take().unwrap()); - match value { - None => Ok(res), - Some(value) => Err((res, value)), - } - } - - /// Gets the contents of the cell, initializing it with `f` if the cell - /// was empty. - /// - /// Many threads may call `get_or_init` concurrently with different - /// initializing functions, but it is guaranteed that only one function - /// will be executed. - /// - /// # Panics - /// - /// If `f` panics, the panic is propagated to the caller, and the cell - /// remains uninitialized. - /// - /// It is an error to reentrantly initialize the cell from `f`. The - /// exact outcome is unspecified. Current implementation deadlocks, but - /// this may be changed to a panic in the future. - /// - /// # Examples - /// - /// ``` - /// use std::sync::OnceLock; - /// - /// let cell = OnceLock::new(); - /// let value = cell.get_or_init(|| 92); - /// assert_eq!(value, &92); - /// let value = cell.get_or_init(|| unreachable!()); - /// assert_eq!(value, &92); - /// ``` - #[inline] - #[stable(feature = "once_cell", since = "1.70.0")] - pub fn get_or_init(&self, f: F) -> &T - where - F: FnOnce() -> T, - { - match self.get_or_try_init(|| Ok::(f())) { - Ok(val) => val, - } - } - - /// Gets the mutable reference of the contents of the cell, initializing - /// it with `f` if the cell was empty. - /// - /// Many threads may call `get_mut_or_init` concurrently with different - /// initializing functions, but it is guaranteed that only one function - /// will be executed. - /// - /// # Panics - /// - /// If `f` panics, the panic is propagated to the caller, and the cell - /// remains uninitialized. - /// - /// # Examples - /// - /// ``` - /// #![feature(once_cell_get_mut)] - /// - /// use std::sync::OnceLock; - /// - /// let mut cell = OnceLock::new(); - /// let value = cell.get_mut_or_init(|| 92); - /// assert_eq!(*value, 92); - /// - /// *value += 2; - /// assert_eq!(*value, 94); - /// - /// let value = cell.get_mut_or_init(|| unreachable!()); - /// assert_eq!(*value, 94); - /// ``` - #[inline] - #[unstable(feature = "once_cell_get_mut", issue = "121641")] - pub fn get_mut_or_init(&mut self, f: F) -> &mut T - where - F: FnOnce() -> T, - { - match self.get_mut_or_try_init(|| Ok::(f())) { - Ok(val) => val, - } - } - - /// Gets the contents of the cell, initializing it with `f` if - /// the cell was empty. If the cell was empty and `f` failed, an - /// error is returned. - /// - /// # Panics - /// - /// If `f` panics, the panic is propagated to the caller, and - /// the cell remains uninitialized. - /// - /// It is an error to reentrantly initialize the cell from `f`. - /// The exact outcome is unspecified. Current implementation - /// deadlocks, but this may be changed to a panic in the future. - /// - /// # Examples - /// - /// ``` - /// #![feature(once_cell_try)] - /// - /// use std::sync::OnceLock; - /// - /// let cell = OnceLock::new(); - /// assert_eq!(cell.get_or_try_init(|| Err(())), Err(())); - /// assert!(cell.get().is_none()); - /// let value = cell.get_or_try_init(|| -> Result { - /// Ok(92) - /// }); - /// assert_eq!(value, Ok(&92)); - /// assert_eq!(cell.get(), Some(&92)) - /// ``` - #[inline] - #[unstable(feature = "once_cell_try", issue = "109737")] - pub fn get_or_try_init(&self, f: F) -> Result<&T, E> - where - F: FnOnce() -> Result, - { - // Fast path check - // NOTE: We need to perform an acquire on the state in this method - // in order to correctly synchronize `LazyLock::force`. This is - // currently done by calling `self.get()`, which in turn calls - // `self.is_initialized()`, which in turn performs the acquire. - if let Some(value) = self.get() { - return Ok(value); - } - self.initialize(f)?; - - debug_assert!(self.is_initialized()); - - // SAFETY: The inner value has been initialized - Ok(unsafe { self.get_unchecked() }) - } - - /// Gets the mutable reference of the contents of the cell, initializing - /// it with `f` if the cell was empty. If the cell was empty and `f` failed, - /// an error is returned. - /// - /// # Panics - /// - /// If `f` panics, the panic is propagated to the caller, and - /// the cell remains uninitialized. - /// - /// # Examples - /// - /// ``` - /// #![feature(once_cell_get_mut)] - /// - /// use std::sync::OnceLock; - /// - /// let mut cell: OnceLock = OnceLock::new(); - /// - /// // Failed initializers do not change the value - /// assert!(cell.get_mut_or_try_init(|| "not a number!".parse()).is_err()); - /// assert!(cell.get().is_none()); - /// - /// let value = cell.get_mut_or_try_init(|| "1234".parse()); - /// assert_eq!(value, Ok(&mut 1234)); - /// *value.unwrap() += 2; - /// assert_eq!(cell.get(), Some(&1236)) - /// ``` - #[inline] - #[unstable(feature = "once_cell_get_mut", issue = "121641")] - pub fn get_mut_or_try_init(&mut self, f: F) -> Result<&mut T, E> - where - F: FnOnce() -> Result, - { - if self.get().is_none() { - self.initialize(f)?; - } - debug_assert!(self.is_initialized()); - // SAFETY: The inner value has been initialized - Ok(unsafe { self.get_unchecked_mut() }) - } - - /// Consumes the `OnceLock`, returning the wrapped value. Returns - /// `None` if the cell was empty. - /// - /// # Examples - /// - /// ``` - /// use std::sync::OnceLock; - /// - /// let cell: OnceLock = OnceLock::new(); - /// assert_eq!(cell.into_inner(), None); - /// - /// let cell = OnceLock::new(); - /// cell.set("hello".to_string()).unwrap(); - /// assert_eq!(cell.into_inner(), Some("hello".to_string())); - /// ``` - #[inline] - #[stable(feature = "once_cell", since = "1.70.0")] - pub fn into_inner(mut self) -> Option { - self.take() - } - - /// Takes the value out of this `OnceLock`, moving it back to an uninitialized state. - /// - /// Has no effect and returns `None` if the `OnceLock` hasn't been initialized. - /// - /// Safety is guaranteed by requiring a mutable reference. - /// - /// # Examples - /// - /// ``` - /// use std::sync::OnceLock; - /// - /// let mut cell: OnceLock = OnceLock::new(); - /// assert_eq!(cell.take(), None); - /// - /// let mut cell = OnceLock::new(); - /// cell.set("hello".to_string()).unwrap(); - /// assert_eq!(cell.take(), Some("hello".to_string())); - /// assert_eq!(cell.get(), None); - /// ``` - #[inline] - #[stable(feature = "once_cell", since = "1.70.0")] - pub fn take(&mut self) -> Option { - if self.is_initialized() { - self.once = Once::new(); - // SAFETY: `self.value` is initialized and contains a valid `T`. - // `self.once` is reset, so `is_initialized()` will be false again - // which prevents the value from being read twice. - unsafe { Some((&mut *self.value.get()).assume_init_read()) } - } else { - None - } - } - - #[inline] - fn is_initialized(&self) -> bool { - self.once.is_completed() - } - - #[cold] - fn initialize(&self, f: F) -> Result<(), E> - where - F: FnOnce() -> Result, - { - let mut res: Result<(), E> = Ok(()); - let slot = &self.value; - - // Ignore poisoning from other threads - // If another thread panics, then we'll be able to run our closure - self.once.call_once_force(|p| { - match f() { - Ok(value) => { - unsafe { (&mut *slot.get()).write(value) }; - } - Err(e) => { - res = Err(e); - - // Treat the underlying `Once` as poisoned since we - // failed to initialize our value. Calls - p.poison(); - } - } - }); - res - } - - /// # Safety - /// - /// The value must be initialized - #[inline] - unsafe fn get_unchecked(&self) -> &T { - debug_assert!(self.is_initialized()); - (&*self.value.get()).assume_init_ref() - } - - /// # Safety - /// - /// The value must be initialized - #[inline] - unsafe fn get_unchecked_mut(&mut self) -> &mut T { - debug_assert!(self.is_initialized()); - (&mut *self.value.get()).assume_init_mut() - } -} - -// Why do we need `T: Send`? -// Thread A creates a `OnceLock` and shares it with -// scoped thread B, which fills the cell, which is -// then destroyed by A. That is, destructor observes -// a sent value. -#[stable(feature = "once_cell", since = "1.70.0")] -unsafe impl Sync for OnceLock {} -#[stable(feature = "once_cell", since = "1.70.0")] -unsafe impl Send for OnceLock {} - -#[stable(feature = "once_cell", since = "1.70.0")] -impl RefUnwindSafe for OnceLock {} -#[stable(feature = "once_cell", since = "1.70.0")] -impl UnwindSafe for OnceLock {} - -#[stable(feature = "once_cell", since = "1.70.0")] -impl Default for OnceLock { - /// Creates a new empty cell. - /// - /// # Example - /// - /// ``` - /// use std::sync::OnceLock; - /// - /// fn main() { - /// assert_eq!(OnceLock::<()>::new(), OnceLock::default()); - /// } - /// ``` - #[inline] - fn default() -> OnceLock { - OnceLock::new() - } -} - -#[stable(feature = "once_cell", since = "1.70.0")] -impl fmt::Debug for OnceLock { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let mut d = f.debug_tuple("OnceLock"); - match self.get() { - Some(v) => d.field(v), - None => d.field(&format_args!("")), - }; - d.finish() - } -} - -#[stable(feature = "once_cell", since = "1.70.0")] -impl Clone for OnceLock { - #[inline] - fn clone(&self) -> OnceLock { - let cell = Self::new(); - if let Some(value) = self.get() { - match cell.set(value.clone()) { - Ok(()) => (), - Err(_) => unreachable!(), - } - } - cell - } -} - -#[stable(feature = "once_cell", since = "1.70.0")] -impl From for OnceLock { - /// Create a new cell with its contents set to `value`. - /// - /// # Example - /// - /// ``` - /// use std::sync::OnceLock; - /// - /// # fn main() -> Result<(), i32> { - /// let a = OnceLock::from(3); - /// let b = OnceLock::new(); - /// b.set(3)?; - /// assert_eq!(a, b); - /// Ok(()) - /// # } - /// ``` - #[inline] - fn from(value: T) -> Self { - let cell = Self::new(); - match cell.set(value) { - Ok(()) => cell, - Err(_) => unreachable!(), - } - } -} - -#[stable(feature = "once_cell", since = "1.70.0")] -impl PartialEq for OnceLock { - #[inline] - fn eq(&self, other: &OnceLock) -> bool { - self.get() == other.get() - } -} - -#[stable(feature = "once_cell", since = "1.70.0")] -impl Eq for OnceLock {} - -#[stable(feature = "once_cell", since = "1.70.0")] -unsafe impl<#[may_dangle] T> Drop for OnceLock { - #[inline] - fn drop(&mut self) { - if self.is_initialized() { - // SAFETY: The cell is initialized and being dropped, so it can't - // be accessed again. We also don't touch the `T` other than - // dropping it, which validates our usage of #[may_dangle]. - unsafe { (&mut *self.value.get()).assume_init_drop() }; - } - } -} - -#[cfg(test)] -mod tests; diff --git a/library/std/src/sync/once_lock/tests.rs b/library/std/src/sync/once_lock/tests.rs deleted file mode 100644 index d5d32e73d8880..0000000000000 --- a/library/std/src/sync/once_lock/tests.rs +++ /dev/null @@ -1,203 +0,0 @@ -use crate::{ - panic, - sync::OnceLock, - sync::{ - atomic::{AtomicUsize, Ordering::SeqCst}, - mpsc::channel, - }, - thread, -}; - -fn spawn_and_wait(f: impl FnOnce() -> R + Send + 'static) -> R { - thread::spawn(f).join().unwrap() -} - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn sync_once_cell() { - static ONCE_CELL: OnceLock = OnceLock::new(); - - assert!(ONCE_CELL.get().is_none()); - - spawn_and_wait(|| { - ONCE_CELL.get_or_init(|| 92); - assert_eq!(ONCE_CELL.get(), Some(&92)); - }); - - ONCE_CELL.get_or_init(|| panic!("Kaboom!")); - assert_eq!(ONCE_CELL.get(), Some(&92)); -} - -#[test] -fn sync_once_cell_get_mut() { - let mut c = OnceLock::new(); - assert!(c.get_mut().is_none()); - c.set(90).unwrap(); - *c.get_mut().unwrap() += 2; - assert_eq!(c.get_mut(), Some(&mut 92)); -} - -#[test] -fn sync_once_cell_get_unchecked() { - let c = OnceLock::new(); - c.set(92).unwrap(); - unsafe { - assert_eq!(c.get_unchecked(), &92); - } -} - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn sync_once_cell_drop() { - static DROP_CNT: AtomicUsize = AtomicUsize::new(0); - struct Dropper; - impl Drop for Dropper { - fn drop(&mut self) { - DROP_CNT.fetch_add(1, SeqCst); - } - } - - let x = OnceLock::new(); - spawn_and_wait(move || { - x.get_or_init(|| Dropper); - assert_eq!(DROP_CNT.load(SeqCst), 0); - drop(x); - }); - - assert_eq!(DROP_CNT.load(SeqCst), 1); -} - -#[test] -fn sync_once_cell_drop_empty() { - let x = OnceLock::::new(); - drop(x); -} - -#[test] -fn clone() { - let s = OnceLock::new(); - let c = s.clone(); - assert!(c.get().is_none()); - - s.set("hello".to_string()).unwrap(); - let c = s.clone(); - assert_eq!(c.get().map(String::as_str), Some("hello")); -} - -#[test] -fn get_or_try_init() { - let cell: OnceLock = OnceLock::new(); - assert!(cell.get().is_none()); - - let res = panic::catch_unwind(|| cell.get_or_try_init(|| -> Result<_, ()> { panic!() })); - assert!(res.is_err()); - assert!(!cell.is_initialized()); - assert!(cell.get().is_none()); - - assert_eq!(cell.get_or_try_init(|| Err(())), Err(())); - - assert_eq!(cell.get_or_try_init(|| Ok::<_, ()>("hello".to_string())), Ok(&"hello".to_string())); - assert_eq!(cell.get(), Some(&"hello".to_string())); -} - -#[test] -fn from_impl() { - assert_eq!(OnceLock::from("value").get(), Some(&"value")); - assert_ne!(OnceLock::from("foo").get(), Some(&"bar")); -} - -#[test] -fn partialeq_impl() { - assert!(OnceLock::from("value") == OnceLock::from("value")); - assert!(OnceLock::from("foo") != OnceLock::from("bar")); - - assert!(OnceLock::::new() == OnceLock::new()); - assert!(OnceLock::::new() != OnceLock::from("value".to_owned())); -} - -#[test] -fn into_inner() { - let cell: OnceLock = OnceLock::new(); - assert_eq!(cell.into_inner(), None); - let cell = OnceLock::new(); - cell.set("hello".to_string()).unwrap(); - assert_eq!(cell.into_inner(), Some("hello".to_string())); -} - -#[test] -fn is_sync_send() { - fn assert_traits() {} - assert_traits::>(); -} - -#[test] -fn eval_once_macro() { - macro_rules! eval_once { - (|| -> $ty:ty { - $($body:tt)* - }) => {{ - static ONCE_CELL: OnceLock<$ty> = OnceLock::new(); - fn init() -> $ty { - $($body)* - } - ONCE_CELL.get_or_init(init) - }}; - } - - let fib: &'static Vec = eval_once! { - || -> Vec { - let mut res = vec![1, 1]; - for i in 0..10 { - let next = res[i] + res[i + 1]; - res.push(next); - } - res - } - }; - assert_eq!(fib[5], 8) -} - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn sync_once_cell_does_not_leak_partially_constructed_boxes() { - static ONCE_CELL: OnceLock = OnceLock::new(); - - let n_readers = 10; - let n_writers = 3; - const MSG: &str = "Hello, World"; - - let (tx, rx) = channel(); - - for _ in 0..n_readers { - let tx = tx.clone(); - thread::spawn(move || { - loop { - if let Some(msg) = ONCE_CELL.get() { - tx.send(msg).unwrap(); - break; - } - #[cfg(target_env = "sgx")] - crate::thread::yield_now(); - } - }); - } - for _ in 0..n_writers { - thread::spawn(move || { - let _ = ONCE_CELL.set(MSG.to_owned()); - }); - } - - for _ in 0..n_readers { - let msg = rx.recv().unwrap(); - assert_eq!(msg, MSG); - } -} - -#[test] -fn dropck() { - let cell = OnceLock::new(); - { - let s = String::new(); - cell.set(&s).unwrap(); - } -} diff --git a/library/std/src/sync/poison.rs b/library/std/src/sync/poison.rs deleted file mode 100644 index f4975088b372d..0000000000000 --- a/library/std/src/sync/poison.rs +++ /dev/null @@ -1,328 +0,0 @@ -use crate::error::Error; -use crate::fmt; - -#[cfg(panic = "unwind")] -use crate::sync::atomic::{AtomicBool, Ordering}; -#[cfg(panic = "unwind")] -use crate::thread; - -pub struct Flag { - #[cfg(panic = "unwind")] - failed: AtomicBool, -} - -// Note that the Ordering uses to access the `failed` field of `Flag` below is -// always `Relaxed`, and that's because this isn't actually protecting any data, -// it's just a flag whether we've panicked or not. -// -// The actual location that this matters is when a mutex is **locked** which is -// where we have external synchronization ensuring that we see memory -// reads/writes to this flag. -// -// As a result, if it matters, we should see the correct value for `failed` in -// all cases. - -impl Flag { - #[inline] - pub const fn new() -> Flag { - Flag { - #[cfg(panic = "unwind")] - failed: AtomicBool::new(false), - } - } - - /// Check the flag for an unguarded borrow, where we only care about existing poison. - #[inline] - pub fn borrow(&self) -> LockResult<()> { - if self.get() { Err(PoisonError::new(())) } else { Ok(()) } - } - - /// Check the flag for a guarded borrow, where we may also set poison when `done`. - #[inline] - pub fn guard(&self) -> LockResult { - let ret = Guard { - #[cfg(panic = "unwind")] - panicking: thread::panicking(), - }; - if self.get() { Err(PoisonError::new(ret)) } else { Ok(ret) } - } - - #[inline] - #[cfg(panic = "unwind")] - pub fn done(&self, guard: &Guard) { - if !guard.panicking && thread::panicking() { - self.failed.store(true, Ordering::Relaxed); - } - } - - #[inline] - #[cfg(not(panic = "unwind"))] - pub fn done(&self, _guard: &Guard) {} - - #[inline] - #[cfg(panic = "unwind")] - pub fn get(&self) -> bool { - self.failed.load(Ordering::Relaxed) - } - - #[inline(always)] - #[cfg(not(panic = "unwind"))] - pub fn get(&self) -> bool { - false - } - - #[inline] - pub fn clear(&self) { - #[cfg(panic = "unwind")] - self.failed.store(false, Ordering::Relaxed) - } -} - -#[derive(Clone)] -pub struct Guard { - #[cfg(panic = "unwind")] - panicking: bool, -} - -/// A type of error which can be returned whenever a lock is acquired. -/// -/// Both [`Mutex`]es and [`RwLock`]s are poisoned whenever a thread fails while the lock -/// is held. The precise semantics for when a lock is poisoned is documented on -/// each lock, but once a lock is poisoned then all future acquisitions will -/// return this error. -/// -/// # Examples -/// -/// ``` -/// use std::sync::{Arc, Mutex}; -/// use std::thread; -/// -/// let mutex = Arc::new(Mutex::new(1)); -/// -/// // poison the mutex -/// let c_mutex = Arc::clone(&mutex); -/// let _ = thread::spawn(move || { -/// let mut data = c_mutex.lock().unwrap(); -/// *data = 2; -/// panic!(); -/// }).join(); -/// -/// match mutex.lock() { -/// Ok(_) => unreachable!(), -/// Err(p_err) => { -/// let data = p_err.get_ref(); -/// println!("recovered: {data}"); -/// } -/// }; -/// ``` -/// [`Mutex`]: crate::sync::Mutex -/// [`RwLock`]: crate::sync::RwLock -#[stable(feature = "rust1", since = "1.0.0")] -pub struct PoisonError { - guard: T, - #[cfg(not(panic = "unwind"))] - _never: !, -} - -/// An enumeration of possible errors associated with a [`TryLockResult`] which -/// can occur while trying to acquire a lock, from the [`try_lock`] method on a -/// [`Mutex`] or the [`try_read`] and [`try_write`] methods on an [`RwLock`]. -/// -/// [`try_lock`]: crate::sync::Mutex::try_lock -/// [`try_read`]: crate::sync::RwLock::try_read -/// [`try_write`]: crate::sync::RwLock::try_write -/// [`Mutex`]: crate::sync::Mutex -/// [`RwLock`]: crate::sync::RwLock -#[stable(feature = "rust1", since = "1.0.0")] -pub enum TryLockError { - /// The lock could not be acquired because another thread failed while holding - /// the lock. - #[stable(feature = "rust1", since = "1.0.0")] - Poisoned(#[stable(feature = "rust1", since = "1.0.0")] PoisonError), - /// The lock could not be acquired at this time because the operation would - /// otherwise block. - #[stable(feature = "rust1", since = "1.0.0")] - WouldBlock, -} - -/// A type alias for the result of a lock method which can be poisoned. -/// -/// The [`Ok`] variant of this result indicates that the primitive was not -/// poisoned, and the `Guard` is contained within. The [`Err`] variant indicates -/// that the primitive was poisoned. Note that the [`Err`] variant *also* carries -/// the associated guard, and it can be acquired through the [`into_inner`] -/// method. -/// -/// [`into_inner`]: PoisonError::into_inner -#[stable(feature = "rust1", since = "1.0.0")] -pub type LockResult = Result>; - -/// A type alias for the result of a nonblocking locking method. -/// -/// For more information, see [`LockResult`]. A `TryLockResult` doesn't -/// necessarily hold the associated guard in the [`Err`] type as the lock might not -/// have been acquired for other reasons. -#[stable(feature = "rust1", since = "1.0.0")] -pub type TryLockResult = Result>; - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for PoisonError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("PoisonError").finish_non_exhaustive() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for PoisonError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - "poisoned lock: another task failed inside".fmt(f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Error for PoisonError { - #[allow(deprecated)] - fn description(&self) -> &str { - "poisoned lock: another task failed inside" - } -} - -impl PoisonError { - /// Creates a `PoisonError`. - /// - /// This is generally created by methods like [`Mutex::lock`](crate::sync::Mutex::lock) - /// or [`RwLock::read`](crate::sync::RwLock::read). - /// - /// This method may panic if std was built with `panic="abort"`. - #[cfg(panic = "unwind")] - #[stable(feature = "sync_poison", since = "1.2.0")] - pub fn new(guard: T) -> PoisonError { - PoisonError { guard } - } - - /// Creates a `PoisonError`. - /// - /// This is generally created by methods like [`Mutex::lock`](crate::sync::Mutex::lock) - /// or [`RwLock::read`](crate::sync::RwLock::read). - /// - /// This method may panic if std was built with `panic="abort"`. - #[cfg(not(panic = "unwind"))] - #[stable(feature = "sync_poison", since = "1.2.0")] - #[track_caller] - pub fn new(_guard: T) -> PoisonError { - panic!("PoisonError created in a libstd built with panic=\"abort\"") - } - - /// Consumes this error indicating that a lock is poisoned, returning the - /// underlying guard to allow access regardless. - /// - /// # Examples - /// - /// ``` - /// use std::collections::HashSet; - /// use std::sync::{Arc, Mutex}; - /// use std::thread; - /// - /// let mutex = Arc::new(Mutex::new(HashSet::new())); - /// - /// // poison the mutex - /// let c_mutex = Arc::clone(&mutex); - /// let _ = thread::spawn(move || { - /// let mut data = c_mutex.lock().unwrap(); - /// data.insert(10); - /// panic!(); - /// }).join(); - /// - /// let p_err = mutex.lock().unwrap_err(); - /// let data = p_err.into_inner(); - /// println!("recovered {} items", data.len()); - /// ``` - #[stable(feature = "sync_poison", since = "1.2.0")] - pub fn into_inner(self) -> T { - self.guard - } - - /// Reaches into this error indicating that a lock is poisoned, returning a - /// reference to the underlying guard to allow access regardless. - #[stable(feature = "sync_poison", since = "1.2.0")] - pub fn get_ref(&self) -> &T { - &self.guard - } - - /// Reaches into this error indicating that a lock is poisoned, returning a - /// mutable reference to the underlying guard to allow access regardless. - #[stable(feature = "sync_poison", since = "1.2.0")] - pub fn get_mut(&mut self) -> &mut T { - &mut self.guard - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl From> for TryLockError { - fn from(err: PoisonError) -> TryLockError { - TryLockError::Poisoned(err) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for TryLockError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - match *self { - #[cfg(panic = "unwind")] - TryLockError::Poisoned(..) => "Poisoned(..)".fmt(f), - #[cfg(not(panic = "unwind"))] - TryLockError::Poisoned(ref p) => match p._never {}, - TryLockError::WouldBlock => "WouldBlock".fmt(f), - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for TryLockError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - match *self { - #[cfg(panic = "unwind")] - TryLockError::Poisoned(..) => "poisoned lock: another task failed inside", - #[cfg(not(panic = "unwind"))] - TryLockError::Poisoned(ref p) => match p._never {}, - TryLockError::WouldBlock => "try_lock failed because the operation would block", - } - .fmt(f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Error for TryLockError { - #[allow(deprecated, deprecated_in_future)] - fn description(&self) -> &str { - match *self { - #[cfg(panic = "unwind")] - TryLockError::Poisoned(ref p) => p.description(), - #[cfg(not(panic = "unwind"))] - TryLockError::Poisoned(ref p) => match p._never {}, - TryLockError::WouldBlock => "try_lock failed because the operation would block", - } - } - - #[allow(deprecated)] - fn cause(&self) -> Option<&dyn Error> { - match *self { - #[cfg(panic = "unwind")] - TryLockError::Poisoned(ref p) => Some(p), - #[cfg(not(panic = "unwind"))] - TryLockError::Poisoned(ref p) => match p._never {}, - _ => None, - } - } -} - -pub fn map_result(result: LockResult, f: F) -> LockResult -where - F: FnOnce(T) -> U, -{ - match result { - Ok(t) => Ok(f(t)), - #[cfg(panic = "unwind")] - Err(PoisonError { guard }) => Err(PoisonError::new(f(guard))), - } -} diff --git a/library/std/src/sync/reentrant_lock.rs b/library/std/src/sync/reentrant_lock.rs deleted file mode 100644 index 80b9e0cf15214..0000000000000 --- a/library/std/src/sync/reentrant_lock.rs +++ /dev/null @@ -1,320 +0,0 @@ -#[cfg(all(test, not(target_os = "emscripten")))] -mod tests; - -use crate::cell::UnsafeCell; -use crate::fmt; -use crate::ops::Deref; -use crate::panic::{RefUnwindSafe, UnwindSafe}; -use crate::sync::atomic::{AtomicUsize, Ordering::Relaxed}; -use crate::sys::sync as sys; - -/// A re-entrant mutual exclusion lock -/// -/// This lock will block *other* threads waiting for the lock to become -/// available. The thread which has already locked the mutex can lock it -/// multiple times without blocking, preventing a common source of deadlocks. -/// -/// # Examples -/// -/// Allow recursively calling a function needing synchronization from within -/// a callback (this is how [`StdoutLock`](crate::io::StdoutLock) is currently -/// implemented): -/// -/// ``` -/// #![feature(reentrant_lock)] -/// -/// use std::cell::RefCell; -/// use std::sync::ReentrantLock; -/// -/// pub struct Log { -/// data: RefCell, -/// } -/// -/// impl Log { -/// pub fn append(&self, msg: &str) { -/// self.data.borrow_mut().push_str(msg); -/// } -/// } -/// -/// static LOG: ReentrantLock = ReentrantLock::new(Log { data: RefCell::new(String::new()) }); -/// -/// pub fn with_log(f: impl FnOnce(&Log) -> R) -> R { -/// let log = LOG.lock(); -/// f(&*log) -/// } -/// -/// with_log(|log| { -/// log.append("Hello"); -/// with_log(|log| log.append(" there!")); -/// }); -/// ``` -/// -// # Implementation details -// -// The 'owner' field tracks which thread has locked the mutex. -// -// We use current_thread_unique_ptr() as the thread identifier, -// which is just the address of a thread local variable. -// -// If `owner` is set to the identifier of the current thread, -// we assume the mutex is already locked and instead of locking it again, -// we increment `lock_count`. -// -// When unlocking, we decrement `lock_count`, and only unlock the mutex when -// it reaches zero. -// -// `lock_count` is protected by the mutex and only accessed by the thread that has -// locked the mutex, so needs no synchronization. -// -// `owner` can be checked by other threads that want to see if they already -// hold the lock, so needs to be atomic. If it compares equal, we're on the -// same thread that holds the mutex and memory access can use relaxed ordering -// since we're not dealing with multiple threads. If it's not equal, -// synchronization is left to the mutex, making relaxed memory ordering for -// the `owner` field fine in all cases. -#[unstable(feature = "reentrant_lock", issue = "121440")] -pub struct ReentrantLock { - mutex: sys::Mutex, - owner: AtomicUsize, - lock_count: UnsafeCell, - data: T, -} - -#[unstable(feature = "reentrant_lock", issue = "121440")] -unsafe impl Send for ReentrantLock {} -#[unstable(feature = "reentrant_lock", issue = "121440")] -unsafe impl Sync for ReentrantLock {} - -// Because of the `UnsafeCell`, these traits are not implemented automatically -#[unstable(feature = "reentrant_lock", issue = "121440")] -impl UnwindSafe for ReentrantLock {} -#[unstable(feature = "reentrant_lock", issue = "121440")] -impl RefUnwindSafe for ReentrantLock {} - -/// An RAII implementation of a "scoped lock" of a re-entrant lock. When this -/// structure is dropped (falls out of scope), the lock will be unlocked. -/// -/// The data protected by the mutex can be accessed through this guard via its -/// [`Deref`] implementation. -/// -/// This structure is created by the [`lock`](ReentrantLock::lock) method on -/// [`ReentrantLock`]. -/// -/// # Mutability -/// -/// Unlike [`MutexGuard`](super::MutexGuard), `ReentrantLockGuard` does not -/// implement [`DerefMut`](crate::ops::DerefMut), because implementation of -/// the trait would violate Rust’s reference aliasing rules. Use interior -/// mutability (usually [`RefCell`](crate::cell::RefCell)) in order to mutate -/// the guarded data. -#[must_use = "if unused the ReentrantLock will immediately unlock"] -#[unstable(feature = "reentrant_lock", issue = "121440")] -pub struct ReentrantLockGuard<'a, T: ?Sized + 'a> { - lock: &'a ReentrantLock, -} - -#[unstable(feature = "reentrant_lock", issue = "121440")] -impl !Send for ReentrantLockGuard<'_, T> {} - -#[unstable(feature = "reentrant_lock", issue = "121440")] -impl ReentrantLock { - /// Creates a new re-entrant lock in an unlocked state ready for use. - /// - /// # Examples - /// - /// ``` - /// #![feature(reentrant_lock)] - /// use std::sync::ReentrantLock; - /// - /// let lock = ReentrantLock::new(0); - /// ``` - pub const fn new(t: T) -> ReentrantLock { - ReentrantLock { - mutex: sys::Mutex::new(), - owner: AtomicUsize::new(0), - lock_count: UnsafeCell::new(0), - data: t, - } - } - - /// Consumes this lock, returning the underlying data. - /// - /// # Examples - /// - /// ``` - /// #![feature(reentrant_lock)] - /// - /// use std::sync::ReentrantLock; - /// - /// let lock = ReentrantLock::new(0); - /// assert_eq!(lock.into_inner(), 0); - /// ``` - pub fn into_inner(self) -> T { - self.data - } -} - -#[unstable(feature = "reentrant_lock", issue = "121440")] -impl ReentrantLock { - /// Acquires the lock, blocking the current thread until it is able to do - /// so. - /// - /// This function will block the caller until it is available to acquire - /// the lock. Upon returning, the thread is the only thread with the lock - /// held. When the thread calling this method already holds the lock, the - /// call succeeds without blocking. - /// - /// # Examples - /// - /// ``` - /// #![feature(reentrant_lock)] - /// use std::cell::Cell; - /// use std::sync::{Arc, ReentrantLock}; - /// use std::thread; - /// - /// let lock = Arc::new(ReentrantLock::new(Cell::new(0))); - /// let c_lock = Arc::clone(&lock); - /// - /// thread::spawn(move || { - /// c_lock.lock().set(10); - /// }).join().expect("thread::spawn failed"); - /// assert_eq!(lock.lock().get(), 10); - /// ``` - pub fn lock(&self) -> ReentrantLockGuard<'_, T> { - let this_thread = current_thread_unique_ptr(); - // Safety: We only touch lock_count when we own the lock. - unsafe { - if self.owner.load(Relaxed) == this_thread { - self.increment_lock_count().expect("lock count overflow in reentrant mutex"); - } else { - self.mutex.lock(); - self.owner.store(this_thread, Relaxed); - debug_assert_eq!(*self.lock_count.get(), 0); - *self.lock_count.get() = 1; - } - } - ReentrantLockGuard { lock: self } - } - - /// Returns a mutable reference to the underlying data. - /// - /// Since this call borrows the `ReentrantLock` mutably, no actual locking - /// needs to take place -- the mutable borrow statically guarantees no locks - /// exist. - /// - /// # Examples - /// - /// ``` - /// #![feature(reentrant_lock)] - /// use std::sync::ReentrantLock; - /// - /// let mut lock = ReentrantLock::new(0); - /// *lock.get_mut() = 10; - /// assert_eq!(*lock.lock(), 10); - /// ``` - pub fn get_mut(&mut self) -> &mut T { - &mut self.data - } - - /// Attempts to acquire this lock. - /// - /// If the lock could not be acquired at this time, then `None` is returned. - /// Otherwise, an RAII guard is returned. - /// - /// This function does not block. - pub(crate) fn try_lock(&self) -> Option> { - let this_thread = current_thread_unique_ptr(); - // Safety: We only touch lock_count when we own the lock. - unsafe { - if self.owner.load(Relaxed) == this_thread { - self.increment_lock_count()?; - Some(ReentrantLockGuard { lock: self }) - } else if self.mutex.try_lock() { - self.owner.store(this_thread, Relaxed); - debug_assert_eq!(*self.lock_count.get(), 0); - *self.lock_count.get() = 1; - Some(ReentrantLockGuard { lock: self }) - } else { - None - } - } - } - - unsafe fn increment_lock_count(&self) -> Option<()> { - *self.lock_count.get() = (*self.lock_count.get()).checked_add(1)?; - Some(()) - } -} - -#[unstable(feature = "reentrant_lock", issue = "121440")] -impl fmt::Debug for ReentrantLock { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let mut d = f.debug_struct("ReentrantLock"); - match self.try_lock() { - Some(v) => d.field("data", &&*v), - None => d.field("data", &format_args!("")), - }; - d.finish_non_exhaustive() - } -} - -#[unstable(feature = "reentrant_lock", issue = "121440")] -impl Default for ReentrantLock { - fn default() -> Self { - Self::new(T::default()) - } -} - -#[unstable(feature = "reentrant_lock", issue = "121440")] -impl From for ReentrantLock { - fn from(t: T) -> Self { - Self::new(t) - } -} - -#[unstable(feature = "reentrant_lock", issue = "121440")] -impl Deref for ReentrantLockGuard<'_, T> { - type Target = T; - - fn deref(&self) -> &T { - &self.lock.data - } -} - -#[unstable(feature = "reentrant_lock", issue = "121440")] -impl fmt::Debug for ReentrantLockGuard<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - (**self).fmt(f) - } -} - -#[unstable(feature = "reentrant_lock", issue = "121440")] -impl fmt::Display for ReentrantLockGuard<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - (**self).fmt(f) - } -} - -#[unstable(feature = "reentrant_lock", issue = "121440")] -impl Drop for ReentrantLockGuard<'_, T> { - #[inline] - fn drop(&mut self) { - // Safety: We own the lock. - unsafe { - *self.lock.lock_count.get() -= 1; - if *self.lock.lock_count.get() == 0 { - self.lock.owner.store(0, Relaxed); - self.lock.mutex.unlock(); - } - } - } -} - -/// Get an address that is unique per running thread. -/// -/// This can be used as a non-null usize-sized ID. -pub(crate) fn current_thread_unique_ptr() -> usize { - // Use a non-drop type to make sure it's still available during thread destruction. - thread_local! { static X: u8 = const { 0 } } - X.with(|x| <*const _>::addr(x)) -} diff --git a/library/std/src/sync/reentrant_lock/tests.rs b/library/std/src/sync/reentrant_lock/tests.rs deleted file mode 100644 index aeef0289d28f8..0000000000000 --- a/library/std/src/sync/reentrant_lock/tests.rs +++ /dev/null @@ -1,53 +0,0 @@ -use super::ReentrantLock; -use crate::cell::RefCell; -use crate::sync::Arc; -use crate::thread; - -#[test] -fn smoke() { - let l = ReentrantLock::new(()); - { - let a = l.lock(); - { - let b = l.lock(); - { - let c = l.lock(); - assert_eq!(*c, ()); - } - assert_eq!(*b, ()); - } - assert_eq!(*a, ()); - } -} - -#[test] -fn is_mutex() { - let l = Arc::new(ReentrantLock::new(RefCell::new(0))); - let l2 = l.clone(); - let lock = l.lock(); - let child = thread::spawn(move || { - let lock = l2.lock(); - assert_eq!(*lock.borrow(), 4950); - }); - for i in 0..100 { - let lock = l.lock(); - *lock.borrow_mut() += i; - } - drop(lock); - child.join().unwrap(); -} - -#[test] -fn trylock_works() { - let l = Arc::new(ReentrantLock::new(())); - let l2 = l.clone(); - let _lock = l.try_lock(); - let _lock2 = l.try_lock(); - thread::spawn(move || { - let lock = l2.try_lock(); - assert!(lock.is_none()); - }) - .join() - .unwrap(); - let _lock3 = l.try_lock(); -} diff --git a/library/std/src/sync/rwlock.rs b/library/std/src/sync/rwlock.rs deleted file mode 100644 index e0a8a7603d71a..0000000000000 --- a/library/std/src/sync/rwlock.rs +++ /dev/null @@ -1,1037 +0,0 @@ -#[cfg(all(test, not(target_os = "emscripten")))] -mod tests; - -use crate::cell::UnsafeCell; -use crate::fmt; -use crate::marker::PhantomData; -use crate::mem::ManuallyDrop; -use crate::ops::{Deref, DerefMut}; -use crate::ptr::NonNull; -use crate::sync::{poison, LockResult, TryLockError, TryLockResult}; -use crate::sys::sync as sys; - -/// A reader-writer lock -/// -/// This type of lock allows a number of readers or at most one writer at any -/// point in time. The write portion of this lock typically allows modification -/// of the underlying data (exclusive access) and the read portion of this lock -/// typically allows for read-only access (shared access). -/// -/// In comparison, a [`Mutex`] does not distinguish between readers or writers -/// that acquire the lock, therefore blocking any threads waiting for the lock to -/// become available. An `RwLock` will allow any number of readers to acquire the -/// lock as long as a writer is not holding the lock. -/// -/// The priority policy of the lock is dependent on the underlying operating -/// system's implementation, and this type does not guarantee that any -/// particular policy will be used. In particular, a writer which is waiting to -/// acquire the lock in `write` might or might not block concurrent calls to -/// `read`, e.g.: -/// -///
Potential deadlock example -/// -/// ```text -/// // Thread 1 | // Thread 2 -/// let _rg1 = lock.read(); | -/// | // will block -/// | let _wg = lock.write(); -/// // may deadlock | -/// let _rg2 = lock.read(); | -/// ``` -/// -///
-/// -/// The type parameter `T` represents the data that this lock protects. It is -/// required that `T` satisfies [`Send`] to be shared across threads and -/// [`Sync`] to allow concurrent access through readers. The RAII guards -/// returned from the locking methods implement [`Deref`] (and [`DerefMut`] -/// for the `write` methods) to allow access to the content of the lock. -/// -/// # Poisoning -/// -/// An `RwLock`, like [`Mutex`], will become poisoned on a panic. Note, however, -/// that an `RwLock` may only be poisoned if a panic occurs while it is locked -/// exclusively (write mode). If a panic occurs in any reader, then the lock -/// will not be poisoned. -/// -/// # Examples -/// -/// ``` -/// use std::sync::RwLock; -/// -/// let lock = RwLock::new(5); -/// -/// // many reader locks can be held at once -/// { -/// let r1 = lock.read().unwrap(); -/// let r2 = lock.read().unwrap(); -/// assert_eq!(*r1, 5); -/// assert_eq!(*r2, 5); -/// } // read locks are dropped at this point -/// -/// // only one write lock may be held, however -/// { -/// let mut w = lock.write().unwrap(); -/// *w += 1; -/// assert_eq!(*w, 6); -/// } // write lock is dropped here -/// ``` -/// -/// [`Mutex`]: super::Mutex -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "RwLock")] -pub struct RwLock { - inner: sys::RwLock, - poison: poison::Flag, - data: UnsafeCell, -} - -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Send for RwLock {} -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Sync for RwLock {} - -/// RAII structure used to release the shared read access of a lock when -/// dropped. -/// -/// This structure is created by the [`read`] and [`try_read`] methods on -/// [`RwLock`]. -/// -/// [`read`]: RwLock::read -/// [`try_read`]: RwLock::try_read -#[must_use = "if unused the RwLock will immediately unlock"] -#[must_not_suspend = "holding a RwLockReadGuard across suspend \ - points can cause deadlocks, delays, \ - and cause Futures to not implement `Send`"] -#[stable(feature = "rust1", since = "1.0.0")] -#[clippy::has_significant_drop] -#[cfg_attr(not(test), rustc_diagnostic_item = "RwLockReadGuard")] -pub struct RwLockReadGuard<'a, T: ?Sized + 'a> { - // NB: we use a pointer instead of `&'a T` to avoid `noalias` violations, because a - // `RwLockReadGuard` argument doesn't hold immutability for its whole scope, only until it drops. - // `NonNull` is also covariant over `T`, just like we would have with `&T`. `NonNull` - // is preferable over `const* T` to allow for niche optimization. - data: NonNull, - inner_lock: &'a sys::RwLock, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl !Send for RwLockReadGuard<'_, T> {} - -#[stable(feature = "rwlock_guard_sync", since = "1.23.0")] -unsafe impl Sync for RwLockReadGuard<'_, T> {} - -/// RAII structure used to release the exclusive write access of a lock when -/// dropped. -/// -/// This structure is created by the [`write`] and [`try_write`] methods -/// on [`RwLock`]. -/// -/// [`write`]: RwLock::write -/// [`try_write`]: RwLock::try_write -#[must_use = "if unused the RwLock will immediately unlock"] -#[must_not_suspend = "holding a RwLockWriteGuard across suspend \ - points can cause deadlocks, delays, \ - and cause Future's to not implement `Send`"] -#[stable(feature = "rust1", since = "1.0.0")] -#[clippy::has_significant_drop] -#[cfg_attr(not(test), rustc_diagnostic_item = "RwLockWriteGuard")] -pub struct RwLockWriteGuard<'a, T: ?Sized + 'a> { - lock: &'a RwLock, - poison: poison::Guard, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl !Send for RwLockWriteGuard<'_, T> {} - -#[stable(feature = "rwlock_guard_sync", since = "1.23.0")] -unsafe impl Sync for RwLockWriteGuard<'_, T> {} - -/// RAII structure used to release the shared read access of a lock when -/// dropped, which can point to a subfield of the protected data. -/// -/// This structure is created by the [`map`] and [`try_map`] methods -/// on [`RwLockReadGuard`]. -/// -/// [`map`]: RwLockReadGuard::map -/// [`try_map`]: RwLockReadGuard::try_map -#[must_use = "if unused the RwLock will immediately unlock"] -#[must_not_suspend = "holding a MappedRwLockReadGuard across suspend \ - points can cause deadlocks, delays, \ - and cause Futures to not implement `Send`"] -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -#[clippy::has_significant_drop] -pub struct MappedRwLockReadGuard<'a, T: ?Sized + 'a> { - // NB: we use a pointer instead of `&'a T` to avoid `noalias` violations, because a - // `MappedRwLockReadGuard` argument doesn't hold immutability for its whole scope, only until it drops. - // `NonNull` is also covariant over `T`, just like we would have with `&T`. `NonNull` - // is preferable over `const* T` to allow for niche optimization. - data: NonNull, - inner_lock: &'a sys::RwLock, -} - -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -impl !Send for MappedRwLockReadGuard<'_, T> {} - -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -unsafe impl Sync for MappedRwLockReadGuard<'_, T> {} - -/// RAII structure used to release the exclusive write access of a lock when -/// dropped, which can point to a subfield of the protected data. -/// -/// This structure is created by the [`map`] and [`try_map`] methods -/// on [`RwLockWriteGuard`]. -/// -/// [`map`]: RwLockWriteGuard::map -/// [`try_map`]: RwLockWriteGuard::try_map -#[must_use = "if unused the RwLock will immediately unlock"] -#[must_not_suspend = "holding a MappedRwLockWriteGuard across suspend \ - points can cause deadlocks, delays, \ - and cause Future's to not implement `Send`"] -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -#[clippy::has_significant_drop] -pub struct MappedRwLockWriteGuard<'a, T: ?Sized + 'a> { - // NB: we use a pointer instead of `&'a mut T` to avoid `noalias` violations, because a - // `MappedRwLockWriteGuard` argument doesn't hold uniqueness for its whole scope, only until it drops. - // `NonNull` is covariant over `T`, so we add a `PhantomData<&'a mut T>` field - // below for the correct variance over `T` (invariance). - data: NonNull, - inner_lock: &'a sys::RwLock, - poison_flag: &'a poison::Flag, - poison: poison::Guard, - _variance: PhantomData<&'a mut T>, -} - -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -impl !Send for MappedRwLockWriteGuard<'_, T> {} - -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -unsafe impl Sync for MappedRwLockWriteGuard<'_, T> {} - -impl RwLock { - /// Creates a new instance of an `RwLock` which is unlocked. - /// - /// # Examples - /// - /// ``` - /// use std::sync::RwLock; - /// - /// let lock = RwLock::new(5); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_stable(feature = "const_locks", since = "1.63.0")] - #[inline] - pub const fn new(t: T) -> RwLock { - RwLock { inner: sys::RwLock::new(), poison: poison::Flag::new(), data: UnsafeCell::new(t) } - } -} - -impl RwLock { - /// Locks this `RwLock` with shared read access, blocking the current thread - /// until it can be acquired. - /// - /// The calling thread will be blocked until there are no more writers which - /// hold the lock. There may be other readers currently inside the lock when - /// this method returns. This method does not provide any guarantees with - /// respect to the ordering of whether contentious readers or writers will - /// acquire the lock first. - /// - /// Returns an RAII guard which will release this thread's shared access - /// once it is dropped. - /// - /// # Errors - /// - /// This function will return an error if the `RwLock` is poisoned. An - /// `RwLock` is poisoned whenever a writer panics while holding an exclusive - /// lock. The failure will occur immediately after the lock has been - /// acquired. - /// - /// # Panics - /// - /// This function might panic when called if the lock is already held by the current thread. - /// - /// # Examples - /// - /// ``` - /// use std::sync::{Arc, RwLock}; - /// use std::thread; - /// - /// let lock = Arc::new(RwLock::new(1)); - /// let c_lock = Arc::clone(&lock); - /// - /// let n = lock.read().unwrap(); - /// assert_eq!(*n, 1); - /// - /// thread::spawn(move || { - /// let r = c_lock.read(); - /// assert!(r.is_ok()); - /// }).join().unwrap(); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn read(&self) -> LockResult> { - unsafe { - self.inner.read(); - RwLockReadGuard::new(self) - } - } - - /// Attempts to acquire this `RwLock` with shared read access. - /// - /// If the access could not be granted at this time, then `Err` is returned. - /// Otherwise, an RAII guard is returned which will release the shared access - /// when it is dropped. - /// - /// This function does not block. - /// - /// This function does not provide any guarantees with respect to the ordering - /// of whether contentious readers or writers will acquire the lock first. - /// - /// # Errors - /// - /// This function will return the [`Poisoned`] error if the `RwLock` is - /// poisoned. An `RwLock` is poisoned whenever a writer panics while holding - /// an exclusive lock. `Poisoned` will only be returned if the lock would - /// have otherwise been acquired. - /// - /// This function will return the [`WouldBlock`] error if the `RwLock` could - /// not be acquired because it was already locked exclusively. - /// - /// [`Poisoned`]: TryLockError::Poisoned - /// [`WouldBlock`]: TryLockError::WouldBlock - /// - /// # Examples - /// - /// ``` - /// use std::sync::RwLock; - /// - /// let lock = RwLock::new(1); - /// - /// match lock.try_read() { - /// Ok(n) => assert_eq!(*n, 1), - /// Err(_) => unreachable!(), - /// }; - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn try_read(&self) -> TryLockResult> { - unsafe { - if self.inner.try_read() { - Ok(RwLockReadGuard::new(self)?) - } else { - Err(TryLockError::WouldBlock) - } - } - } - - /// Locks this `RwLock` with exclusive write access, blocking the current - /// thread until it can be acquired. - /// - /// This function will not return while other writers or other readers - /// currently have access to the lock. - /// - /// Returns an RAII guard which will drop the write access of this `RwLock` - /// when dropped. - /// - /// # Errors - /// - /// This function will return an error if the `RwLock` is poisoned. An - /// `RwLock` is poisoned whenever a writer panics while holding an exclusive - /// lock. An error will be returned when the lock is acquired. - /// - /// # Panics - /// - /// This function might panic when called if the lock is already held by the current thread. - /// - /// # Examples - /// - /// ``` - /// use std::sync::RwLock; - /// - /// let lock = RwLock::new(1); - /// - /// let mut n = lock.write().unwrap(); - /// *n = 2; - /// - /// assert!(lock.try_read().is_err()); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn write(&self) -> LockResult> { - unsafe { - self.inner.write(); - RwLockWriteGuard::new(self) - } - } - - /// Attempts to lock this `RwLock` with exclusive write access. - /// - /// If the lock could not be acquired at this time, then `Err` is returned. - /// Otherwise, an RAII guard is returned which will release the lock when - /// it is dropped. - /// - /// This function does not block. - /// - /// This function does not provide any guarantees with respect to the ordering - /// of whether contentious readers or writers will acquire the lock first. - /// - /// # Errors - /// - /// This function will return the [`Poisoned`] error if the `RwLock` is - /// poisoned. An `RwLock` is poisoned whenever a writer panics while holding - /// an exclusive lock. `Poisoned` will only be returned if the lock would - /// have otherwise been acquired. - /// - /// This function will return the [`WouldBlock`] error if the `RwLock` could - /// not be acquired because it was already locked exclusively. - /// - /// [`Poisoned`]: TryLockError::Poisoned - /// [`WouldBlock`]: TryLockError::WouldBlock - /// - /// - /// # Examples - /// - /// ``` - /// use std::sync::RwLock; - /// - /// let lock = RwLock::new(1); - /// - /// let n = lock.read().unwrap(); - /// assert_eq!(*n, 1); - /// - /// assert!(lock.try_write().is_err()); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn try_write(&self) -> TryLockResult> { - unsafe { - if self.inner.try_write() { - Ok(RwLockWriteGuard::new(self)?) - } else { - Err(TryLockError::WouldBlock) - } - } - } - - /// Determines whether the lock is poisoned. - /// - /// If another thread is active, the lock can still become poisoned at any - /// time. You should not trust a `false` value for program correctness - /// without additional synchronization. - /// - /// # Examples - /// - /// ``` - /// use std::sync::{Arc, RwLock}; - /// use std::thread; - /// - /// let lock = Arc::new(RwLock::new(0)); - /// let c_lock = Arc::clone(&lock); - /// - /// let _ = thread::spawn(move || { - /// let _lock = c_lock.write().unwrap(); - /// panic!(); // the lock gets poisoned - /// }).join(); - /// assert_eq!(lock.is_poisoned(), true); - /// ``` - #[inline] - #[stable(feature = "sync_poison", since = "1.2.0")] - pub fn is_poisoned(&self) -> bool { - self.poison.get() - } - - /// Clear the poisoned state from a lock. - /// - /// If the lock is poisoned, it will remain poisoned until this function is called. This allows - /// recovering from a poisoned state and marking that it has recovered. For example, if the - /// value is overwritten by a known-good value, then the lock can be marked as un-poisoned. Or - /// possibly, the value could be inspected to determine if it is in a consistent state, and if - /// so the poison is removed. - /// - /// # Examples - /// - /// ``` - /// use std::sync::{Arc, RwLock}; - /// use std::thread; - /// - /// let lock = Arc::new(RwLock::new(0)); - /// let c_lock = Arc::clone(&lock); - /// - /// let _ = thread::spawn(move || { - /// let _lock = c_lock.write().unwrap(); - /// panic!(); // the lock gets poisoned - /// }).join(); - /// - /// assert_eq!(lock.is_poisoned(), true); - /// let guard = lock.write().unwrap_or_else(|mut e| { - /// **e.get_mut() = 1; - /// lock.clear_poison(); - /// e.into_inner() - /// }); - /// assert_eq!(lock.is_poisoned(), false); - /// assert_eq!(*guard, 1); - /// ``` - #[inline] - #[stable(feature = "mutex_unpoison", since = "1.77.0")] - pub fn clear_poison(&self) { - self.poison.clear(); - } - - /// Consumes this `RwLock`, returning the underlying data. - /// - /// # Errors - /// - /// This function will return an error if the `RwLock` is poisoned. An - /// `RwLock` is poisoned whenever a writer panics while holding an exclusive - /// lock. An error will only be returned if the lock would have otherwise - /// been acquired. - /// - /// # Examples - /// - /// ``` - /// use std::sync::RwLock; - /// - /// let lock = RwLock::new(String::new()); - /// { - /// let mut s = lock.write().unwrap(); - /// *s = "modified".to_owned(); - /// } - /// assert_eq!(lock.into_inner().unwrap(), "modified"); - /// ``` - #[stable(feature = "rwlock_into_inner", since = "1.6.0")] - pub fn into_inner(self) -> LockResult - where - T: Sized, - { - let data = self.data.into_inner(); - poison::map_result(self.poison.borrow(), |()| data) - } - - /// Returns a mutable reference to the underlying data. - /// - /// Since this call borrows the `RwLock` mutably, no actual locking needs to - /// take place -- the mutable borrow statically guarantees no locks exist. - /// - /// # Errors - /// - /// This function will return an error if the `RwLock` is poisoned. An - /// `RwLock` is poisoned whenever a writer panics while holding an exclusive - /// lock. An error will only be returned if the lock would have otherwise - /// been acquired. - /// - /// # Examples - /// - /// ``` - /// use std::sync::RwLock; - /// - /// let mut lock = RwLock::new(0); - /// *lock.get_mut().unwrap() = 10; - /// assert_eq!(*lock.read().unwrap(), 10); - /// ``` - #[stable(feature = "rwlock_get_mut", since = "1.6.0")] - pub fn get_mut(&mut self) -> LockResult<&mut T> { - let data = self.data.get_mut(); - poison::map_result(self.poison.borrow(), |()| data) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for RwLock { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let mut d = f.debug_struct("RwLock"); - match self.try_read() { - Ok(guard) => { - d.field("data", &&*guard); - } - Err(TryLockError::Poisoned(err)) => { - d.field("data", &&**err.get_ref()); - } - Err(TryLockError::WouldBlock) => { - d.field("data", &format_args!("")); - } - } - d.field("poisoned", &self.poison.get()); - d.finish_non_exhaustive() - } -} - -#[stable(feature = "rw_lock_default", since = "1.10.0")] -impl Default for RwLock { - /// Creates a new `RwLock`, with the `Default` value for T. - fn default() -> RwLock { - RwLock::new(Default::default()) - } -} - -#[stable(feature = "rw_lock_from", since = "1.24.0")] -impl From for RwLock { - /// Creates a new instance of an `RwLock` which is unlocked. - /// This is equivalent to [`RwLock::new`]. - fn from(t: T) -> Self { - RwLock::new(t) - } -} - -impl<'rwlock, T: ?Sized> RwLockReadGuard<'rwlock, T> { - /// Create a new instance of `RwLockReadGuard` from a `RwLock`. - // SAFETY: if and only if `lock.inner.read()` (or `lock.inner.try_read()`) has been - // successfully called from the same thread before instantiating this object. - unsafe fn new(lock: &'rwlock RwLock) -> LockResult> { - poison::map_result(lock.poison.borrow(), |()| RwLockReadGuard { - data: NonNull::new_unchecked(lock.data.get()), - inner_lock: &lock.inner, - }) - } -} - -impl<'rwlock, T: ?Sized> RwLockWriteGuard<'rwlock, T> { - /// Create a new instance of `RwLockWriteGuard` from a `RwLock`. - // SAFETY: if and only if `lock.inner.write()` (or `lock.inner.try_write()`) has been - // successfully called from the same thread before instantiating this object. - unsafe fn new(lock: &'rwlock RwLock) -> LockResult> { - poison::map_result(lock.poison.guard(), |guard| RwLockWriteGuard { lock, poison: guard }) - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for RwLockReadGuard<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - (**self).fmt(f) - } -} - -#[stable(feature = "std_guard_impls", since = "1.20.0")] -impl fmt::Display for RwLockReadGuard<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - (**self).fmt(f) - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for RwLockWriteGuard<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - (**self).fmt(f) - } -} - -#[stable(feature = "std_guard_impls", since = "1.20.0")] -impl fmt::Display for RwLockWriteGuard<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - (**self).fmt(f) - } -} - -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -impl fmt::Debug for MappedRwLockReadGuard<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - (**self).fmt(f) - } -} - -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -impl fmt::Display for MappedRwLockReadGuard<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - (**self).fmt(f) - } -} - -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -impl fmt::Debug for MappedRwLockWriteGuard<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - (**self).fmt(f) - } -} - -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -impl fmt::Display for MappedRwLockWriteGuard<'_, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - (**self).fmt(f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Deref for RwLockReadGuard<'_, T> { - type Target = T; - - fn deref(&self) -> &T { - // SAFETY: the conditions of `RwLockReadGuard::new` were satisfied when created. - unsafe { self.data.as_ref() } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Deref for RwLockWriteGuard<'_, T> { - type Target = T; - - fn deref(&self) -> &T { - // SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when created. - unsafe { &*self.lock.data.get() } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DerefMut for RwLockWriteGuard<'_, T> { - fn deref_mut(&mut self) -> &mut T { - // SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when created. - unsafe { &mut *self.lock.data.get() } - } -} - -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -impl Deref for MappedRwLockReadGuard<'_, T> { - type Target = T; - - fn deref(&self) -> &T { - // SAFETY: the conditions of `RwLockReadGuard::new` were satisfied when the original guard - // was created, and have been upheld throughout `map` and/or `try_map`. - unsafe { self.data.as_ref() } - } -} - -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -impl Deref for MappedRwLockWriteGuard<'_, T> { - type Target = T; - - fn deref(&self) -> &T { - // SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when the original guard - // was created, and have been upheld throughout `map` and/or `try_map`. - unsafe { self.data.as_ref() } - } -} - -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -impl DerefMut for MappedRwLockWriteGuard<'_, T> { - fn deref_mut(&mut self) -> &mut T { - // SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when the original guard - // was created, and have been upheld throughout `map` and/or `try_map`. - unsafe { self.data.as_mut() } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Drop for RwLockReadGuard<'_, T> { - fn drop(&mut self) { - // SAFETY: the conditions of `RwLockReadGuard::new` were satisfied when created. - unsafe { - self.inner_lock.read_unlock(); - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Drop for RwLockWriteGuard<'_, T> { - fn drop(&mut self) { - self.lock.poison.done(&self.poison); - // SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when created. - unsafe { - self.lock.inner.write_unlock(); - } - } -} - -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -impl Drop for MappedRwLockReadGuard<'_, T> { - fn drop(&mut self) { - // SAFETY: the conditions of `RwLockReadGuard::new` were satisfied when the original guard - // was created, and have been upheld throughout `map` and/or `try_map`. - unsafe { - self.inner_lock.read_unlock(); - } - } -} - -#[unstable(feature = "mapped_lock_guards", issue = "117108")] -impl Drop for MappedRwLockWriteGuard<'_, T> { - fn drop(&mut self) { - self.poison_flag.done(&self.poison); - // SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when the original guard - // was created, and have been upheld throughout `map` and/or `try_map`. - unsafe { - self.inner_lock.write_unlock(); - } - } -} - -impl<'a, T: ?Sized> RwLockReadGuard<'a, T> { - /// Makes a [`MappedRwLockReadGuard`] for a component of the borrowed data, e.g. - /// an enum variant. - /// - /// The `RwLock` is already locked for reading, so this cannot fail. - /// - /// This is an associated function that needs to be used as - /// `RwLockReadGuard::map(...)`. A method would interfere with methods of - /// the same name on the contents of the `RwLockReadGuard` used through - /// `Deref`. - /// - /// # Panics - /// - /// If the closure panics, the guard will be dropped (unlocked) and the RwLock will not be poisoned. - #[unstable(feature = "mapped_lock_guards", issue = "117108")] - pub fn map(orig: Self, f: F) -> MappedRwLockReadGuard<'a, U> - where - F: FnOnce(&T) -> &U, - U: ?Sized, - { - // SAFETY: the conditions of `RwLockReadGuard::new` were satisfied when the original guard - // was created, and have been upheld throughout `map` and/or `try_map`. - // The signature of the closure guarantees that it will not "leak" the lifetime of the reference - // passed to it. If the closure panics, the guard will be dropped. - let data = NonNull::from(f(unsafe { orig.data.as_ref() })); - let orig = ManuallyDrop::new(orig); - MappedRwLockReadGuard { data, inner_lock: &orig.inner_lock } - } - - /// Makes a [`MappedRwLockReadGuard`] for a component of the borrowed data. The - /// original guard is returned as an `Err(...)` if the closure returns - /// `None`. - /// - /// The `RwLock` is already locked for reading, so this cannot fail. - /// - /// This is an associated function that needs to be used as - /// `RwLockReadGuard::try_map(...)`. A method would interfere with methods - /// of the same name on the contents of the `RwLockReadGuard` used through - /// `Deref`. - /// - /// # Panics - /// - /// If the closure panics, the guard will be dropped (unlocked) and the RwLock will not be poisoned. - #[doc(alias = "filter_map")] - #[unstable(feature = "mapped_lock_guards", issue = "117108")] - pub fn try_map(orig: Self, f: F) -> Result, Self> - where - F: FnOnce(&T) -> Option<&U>, - U: ?Sized, - { - // SAFETY: the conditions of `RwLockReadGuard::new` were satisfied when the original guard - // was created, and have been upheld throughout `map` and/or `try_map`. - // The signature of the closure guarantees that it will not "leak" the lifetime of the reference - // passed to it. If the closure panics, the guard will be dropped. - match f(unsafe { orig.data.as_ref() }) { - Some(data) => { - let data = NonNull::from(data); - let orig = ManuallyDrop::new(orig); - Ok(MappedRwLockReadGuard { data, inner_lock: &orig.inner_lock }) - } - None => Err(orig), - } - } -} - -impl<'a, T: ?Sized> MappedRwLockReadGuard<'a, T> { - /// Makes a [`MappedRwLockReadGuard`] for a component of the borrowed data, - /// e.g. an enum variant. - /// - /// The `RwLock` is already locked for reading, so this cannot fail. - /// - /// This is an associated function that needs to be used as - /// `MappedRwLockReadGuard::map(...)`. A method would interfere with - /// methods of the same name on the contents of the `MappedRwLockReadGuard` - /// used through `Deref`. - /// - /// # Panics - /// - /// If the closure panics, the guard will be dropped (unlocked) and the RwLock will not be poisoned. - #[unstable(feature = "mapped_lock_guards", issue = "117108")] - pub fn map(orig: Self, f: F) -> MappedRwLockReadGuard<'a, U> - where - F: FnOnce(&T) -> &U, - U: ?Sized, - { - // SAFETY: the conditions of `RwLockReadGuard::new` were satisfied when the original guard - // was created, and have been upheld throughout `map` and/or `try_map`. - // The signature of the closure guarantees that it will not "leak" the lifetime of the reference - // passed to it. If the closure panics, the guard will be dropped. - let data = NonNull::from(f(unsafe { orig.data.as_ref() })); - let orig = ManuallyDrop::new(orig); - MappedRwLockReadGuard { data, inner_lock: &orig.inner_lock } - } - - /// Makes a [`MappedRwLockReadGuard`] for a component of the borrowed data. - /// The original guard is returned as an `Err(...)` if the closure returns - /// `None`. - /// - /// The `RwLock` is already locked for reading, so this cannot fail. - /// - /// This is an associated function that needs to be used as - /// `MappedRwLockReadGuard::try_map(...)`. A method would interfere with - /// methods of the same name on the contents of the `MappedRwLockReadGuard` - /// used through `Deref`. - /// - /// # Panics - /// - /// If the closure panics, the guard will be dropped (unlocked) and the RwLock will not be poisoned. - #[doc(alias = "filter_map")] - #[unstable(feature = "mapped_lock_guards", issue = "117108")] - pub fn try_map(orig: Self, f: F) -> Result, Self> - where - F: FnOnce(&T) -> Option<&U>, - U: ?Sized, - { - // SAFETY: the conditions of `RwLockReadGuard::new` were satisfied when the original guard - // was created, and have been upheld throughout `map` and/or `try_map`. - // The signature of the closure guarantees that it will not "leak" the lifetime of the reference - // passed to it. If the closure panics, the guard will be dropped. - match f(unsafe { orig.data.as_ref() }) { - Some(data) => { - let data = NonNull::from(data); - let orig = ManuallyDrop::new(orig); - Ok(MappedRwLockReadGuard { data, inner_lock: &orig.inner_lock }) - } - None => Err(orig), - } - } -} - -impl<'a, T: ?Sized> RwLockWriteGuard<'a, T> { - /// Makes a [`MappedRwLockWriteGuard`] for a component of the borrowed data, e.g. - /// an enum variant. - /// - /// The `RwLock` is already locked for writing, so this cannot fail. - /// - /// This is an associated function that needs to be used as - /// `RwLockWriteGuard::map(...)`. A method would interfere with methods of - /// the same name on the contents of the `RwLockWriteGuard` used through - /// `Deref`. - /// - /// # Panics - /// - /// If the closure panics, the guard will be dropped (unlocked) and the RwLock will be poisoned. - #[unstable(feature = "mapped_lock_guards", issue = "117108")] - pub fn map(orig: Self, f: F) -> MappedRwLockWriteGuard<'a, U> - where - F: FnOnce(&mut T) -> &mut U, - U: ?Sized, - { - // SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when the original guard - // was created, and have been upheld throughout `map` and/or `try_map`. - // The signature of the closure guarantees that it will not "leak" the lifetime of the reference - // passed to it. If the closure panics, the guard will be dropped. - let data = NonNull::from(f(unsafe { &mut *orig.lock.data.get() })); - let orig = ManuallyDrop::new(orig); - MappedRwLockWriteGuard { - data, - inner_lock: &orig.lock.inner, - poison_flag: &orig.lock.poison, - poison: orig.poison.clone(), - _variance: PhantomData, - } - } - - /// Makes a [`MappedRwLockWriteGuard`] for a component of the borrowed data. The - /// original guard is returned as an `Err(...)` if the closure returns - /// `None`. - /// - /// The `RwLock` is already locked for writing, so this cannot fail. - /// - /// This is an associated function that needs to be used as - /// `RwLockWriteGuard::try_map(...)`. A method would interfere with methods - /// of the same name on the contents of the `RwLockWriteGuard` used through - /// `Deref`. - /// - /// # Panics - /// - /// If the closure panics, the guard will be dropped (unlocked) and the RwLock will be poisoned. - #[doc(alias = "filter_map")] - #[unstable(feature = "mapped_lock_guards", issue = "117108")] - pub fn try_map(orig: Self, f: F) -> Result, Self> - where - F: FnOnce(&mut T) -> Option<&mut U>, - U: ?Sized, - { - // SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when the original guard - // was created, and have been upheld throughout `map` and/or `try_map`. - // The signature of the closure guarantees that it will not "leak" the lifetime of the reference - // passed to it. If the closure panics, the guard will be dropped. - match f(unsafe { &mut *orig.lock.data.get() }) { - Some(data) => { - let data = NonNull::from(data); - let orig = ManuallyDrop::new(orig); - Ok(MappedRwLockWriteGuard { - data, - inner_lock: &orig.lock.inner, - poison_flag: &orig.lock.poison, - poison: orig.poison.clone(), - _variance: PhantomData, - }) - } - None => Err(orig), - } - } -} - -impl<'a, T: ?Sized> MappedRwLockWriteGuard<'a, T> { - /// Makes a [`MappedRwLockWriteGuard`] for a component of the borrowed data, - /// e.g. an enum variant. - /// - /// The `RwLock` is already locked for writing, so this cannot fail. - /// - /// This is an associated function that needs to be used as - /// `MappedRwLockWriteGuard::map(...)`. A method would interfere with - /// methods of the same name on the contents of the `MappedRwLockWriteGuard` - /// used through `Deref`. - /// - /// # Panics - /// - /// If the closure panics, the guard will be dropped (unlocked) and the RwLock will be poisoned. - #[unstable(feature = "mapped_lock_guards", issue = "117108")] - pub fn map(mut orig: Self, f: F) -> MappedRwLockWriteGuard<'a, U> - where - F: FnOnce(&mut T) -> &mut U, - U: ?Sized, - { - // SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when the original guard - // was created, and have been upheld throughout `map` and/or `try_map`. - // The signature of the closure guarantees that it will not "leak" the lifetime of the reference - // passed to it. If the closure panics, the guard will be dropped. - let data = NonNull::from(f(unsafe { orig.data.as_mut() })); - let orig = ManuallyDrop::new(orig); - MappedRwLockWriteGuard { - data, - inner_lock: orig.inner_lock, - poison_flag: orig.poison_flag, - poison: orig.poison.clone(), - _variance: PhantomData, - } - } - - /// Makes a [`MappedRwLockWriteGuard`] for a component of the borrowed data. - /// The original guard is returned as an `Err(...)` if the closure returns - /// `None`. - /// - /// The `RwLock` is already locked for writing, so this cannot fail. - /// - /// This is an associated function that needs to be used as - /// `MappedRwLockWriteGuard::try_map(...)`. A method would interfere with - /// methods of the same name on the contents of the `MappedRwLockWriteGuard` - /// used through `Deref`. - /// - /// # Panics - /// - /// If the closure panics, the guard will be dropped (unlocked) and the RwLock will be poisoned. - #[doc(alias = "filter_map")] - #[unstable(feature = "mapped_lock_guards", issue = "117108")] - pub fn try_map(mut orig: Self, f: F) -> Result, Self> - where - F: FnOnce(&mut T) -> Option<&mut U>, - U: ?Sized, - { - // SAFETY: the conditions of `RwLockWriteGuard::new` were satisfied when the original guard - // was created, and have been upheld throughout `map` and/or `try_map`. - // The signature of the closure guarantees that it will not "leak" the lifetime of the reference - // passed to it. If the closure panics, the guard will be dropped. - match f(unsafe { orig.data.as_mut() }) { - Some(data) => { - let data = NonNull::from(data); - let orig = ManuallyDrop::new(orig); - Ok(MappedRwLockWriteGuard { - data, - inner_lock: orig.inner_lock, - poison_flag: orig.poison_flag, - poison: orig.poison.clone(), - _variance: PhantomData, - }) - } - None => Err(orig), - } - } -} diff --git a/library/std/src/sync/rwlock/tests.rs b/library/std/src/sync/rwlock/tests.rs deleted file mode 100644 index 9cc5e7a3a60f1..0000000000000 --- a/library/std/src/sync/rwlock/tests.rs +++ /dev/null @@ -1,498 +0,0 @@ -use crate::sync::atomic::{AtomicUsize, Ordering}; -use crate::sync::mpsc::channel; -use crate::sync::{ - Arc, MappedRwLockReadGuard, MappedRwLockWriteGuard, RwLock, RwLockReadGuard, RwLockWriteGuard, - TryLockError, -}; -use crate::thread; -use rand::Rng; - -#[derive(Eq, PartialEq, Debug)] -struct NonCopy(i32); - -#[test] -fn smoke() { - let l = RwLock::new(()); - drop(l.read().unwrap()); - drop(l.write().unwrap()); - drop((l.read().unwrap(), l.read().unwrap())); - drop(l.write().unwrap()); -} - -#[test] -fn frob() { - const N: u32 = 10; - const M: usize = if cfg!(miri) { 100 } else { 1000 }; - - let r = Arc::new(RwLock::new(())); - - let (tx, rx) = channel::<()>(); - for _ in 0..N { - let tx = tx.clone(); - let r = r.clone(); - thread::spawn(move || { - let mut rng = crate::test_helpers::test_rng(); - for _ in 0..M { - if rng.gen_bool(1.0 / (N as f64)) { - drop(r.write().unwrap()); - } else { - drop(r.read().unwrap()); - } - } - drop(tx); - }); - } - drop(tx); - let _ = rx.recv(); -} - -#[test] -fn test_rw_arc_poison_wr() { - let arc = Arc::new(RwLock::new(1)); - let arc2 = arc.clone(); - let _: Result<(), _> = thread::spawn(move || { - let _lock = arc2.write().unwrap(); - panic!(); - }) - .join(); - assert!(arc.read().is_err()); -} - -#[test] -fn test_rw_arc_poison_mapped_w_r() { - let arc = Arc::new(RwLock::new(1)); - let arc2 = arc.clone(); - let _: Result<(), _> = thread::spawn(move || { - let lock = arc2.write().unwrap(); - let _lock = RwLockWriteGuard::map(lock, |val| val); - panic!(); - }) - .join(); - assert!(arc.read().is_err()); -} - -#[test] -fn test_rw_arc_poison_ww() { - let arc = Arc::new(RwLock::new(1)); - assert!(!arc.is_poisoned()); - let arc2 = arc.clone(); - let _: Result<(), _> = thread::spawn(move || { - let _lock = arc2.write().unwrap(); - panic!(); - }) - .join(); - assert!(arc.write().is_err()); - assert!(arc.is_poisoned()); -} - -#[test] -fn test_rw_arc_poison_mapped_w_w() { - let arc = Arc::new(RwLock::new(1)); - let arc2 = arc.clone(); - let _: Result<(), _> = thread::spawn(move || { - let lock = arc2.write().unwrap(); - let _lock = RwLockWriteGuard::map(lock, |val| val); - panic!(); - }) - .join(); - assert!(arc.write().is_err()); - assert!(arc.is_poisoned()); -} - -#[test] -fn test_rw_arc_no_poison_rr() { - let arc = Arc::new(RwLock::new(1)); - let arc2 = arc.clone(); - let _: Result<(), _> = thread::spawn(move || { - let _lock = arc2.read().unwrap(); - panic!(); - }) - .join(); - let lock = arc.read().unwrap(); - assert_eq!(*lock, 1); -} - -#[test] -fn test_rw_arc_no_poison_mapped_r_r() { - let arc = Arc::new(RwLock::new(1)); - let arc2 = arc.clone(); - let _: Result<(), _> = thread::spawn(move || { - let lock = arc2.read().unwrap(); - let _lock = RwLockReadGuard::map(lock, |val| val); - panic!(); - }) - .join(); - let lock = arc.read().unwrap(); - assert_eq!(*lock, 1); -} - -#[test] -fn test_rw_arc_no_poison_rw() { - let arc = Arc::new(RwLock::new(1)); - let arc2 = arc.clone(); - let _: Result<(), _> = thread::spawn(move || { - let _lock = arc2.read().unwrap(); - panic!() - }) - .join(); - let lock = arc.write().unwrap(); - assert_eq!(*lock, 1); -} - -#[test] -fn test_rw_arc_no_poison_mapped_r_w() { - let arc = Arc::new(RwLock::new(1)); - let arc2 = arc.clone(); - let _: Result<(), _> = thread::spawn(move || { - let lock = arc2.read().unwrap(); - let _lock = RwLockReadGuard::map(lock, |val| val); - panic!(); - }) - .join(); - let lock = arc.write().unwrap(); - assert_eq!(*lock, 1); -} - -#[test] -fn test_rw_arc() { - let arc = Arc::new(RwLock::new(0)); - let arc2 = arc.clone(); - let (tx, rx) = channel(); - - thread::spawn(move || { - let mut lock = arc2.write().unwrap(); - for _ in 0..10 { - let tmp = *lock; - *lock = -1; - thread::yield_now(); - *lock = tmp + 1; - } - tx.send(()).unwrap(); - }); - - // Readers try to catch the writer in the act - let mut children = Vec::new(); - for _ in 0..5 { - let arc3 = arc.clone(); - children.push(thread::spawn(move || { - let lock = arc3.read().unwrap(); - assert!(*lock >= 0); - })); - } - - // Wait for children to pass their asserts - for r in children { - assert!(r.join().is_ok()); - } - - // Wait for writer to finish - rx.recv().unwrap(); - let lock = arc.read().unwrap(); - assert_eq!(*lock, 10); -} - -#[test] -fn test_rw_arc_access_in_unwind() { - let arc = Arc::new(RwLock::new(1)); - let arc2 = arc.clone(); - let _ = thread::spawn(move || -> () { - struct Unwinder { - i: Arc>, - } - impl Drop for Unwinder { - fn drop(&mut self) { - let mut lock = self.i.write().unwrap(); - *lock += 1; - } - } - let _u = Unwinder { i: arc2 }; - panic!(); - }) - .join(); - let lock = arc.read().unwrap(); - assert_eq!(*lock, 2); -} - -#[test] -fn test_rwlock_unsized() { - let rw: &RwLock<[i32]> = &RwLock::new([1, 2, 3]); - { - let b = &mut *rw.write().unwrap(); - b[0] = 4; - b[2] = 5; - } - let comp: &[i32] = &[4, 2, 5]; - assert_eq!(&*rw.read().unwrap(), comp); -} - -#[test] -fn test_rwlock_try_write() { - let lock = RwLock::new(0isize); - let read_guard = lock.read().unwrap(); - - let write_result = lock.try_write(); - match write_result { - Err(TryLockError::WouldBlock) => (), - Ok(_) => assert!(false, "try_write should not succeed while read_guard is in scope"), - Err(_) => assert!(false, "unexpected error"), - } - - drop(read_guard); - let mapped_read_guard = RwLockReadGuard::map(lock.read().unwrap(), |_| &()); - - let write_result = lock.try_write(); - match write_result { - Err(TryLockError::WouldBlock) => (), - Ok(_) => assert!(false, "try_write should not succeed while mapped_read_guard is in scope"), - Err(_) => assert!(false, "unexpected error"), - } - - drop(mapped_read_guard); -} - -#[test] -fn test_into_inner() { - let m = RwLock::new(NonCopy(10)); - assert_eq!(m.into_inner().unwrap(), NonCopy(10)); -} - -#[test] -fn test_into_inner_drop() { - struct Foo(Arc); - impl Drop for Foo { - fn drop(&mut self) { - self.0.fetch_add(1, Ordering::SeqCst); - } - } - let num_drops = Arc::new(AtomicUsize::new(0)); - let m = RwLock::new(Foo(num_drops.clone())); - assert_eq!(num_drops.load(Ordering::SeqCst), 0); - { - let _inner = m.into_inner().unwrap(); - assert_eq!(num_drops.load(Ordering::SeqCst), 0); - } - assert_eq!(num_drops.load(Ordering::SeqCst), 1); -} - -#[test] -fn test_into_inner_poison() { - let m = Arc::new(RwLock::new(NonCopy(10))); - let m2 = m.clone(); - let _ = thread::spawn(move || { - let _lock = m2.write().unwrap(); - panic!("test panic in inner thread to poison RwLock"); - }) - .join(); - - assert!(m.is_poisoned()); - match Arc::try_unwrap(m).unwrap().into_inner() { - Err(e) => assert_eq!(e.into_inner(), NonCopy(10)), - Ok(x) => panic!("into_inner of poisoned RwLock is Ok: {x:?}"), - } -} - -#[test] -fn test_get_mut() { - let mut m = RwLock::new(NonCopy(10)); - *m.get_mut().unwrap() = NonCopy(20); - assert_eq!(m.into_inner().unwrap(), NonCopy(20)); -} - -#[test] -fn test_get_mut_poison() { - let m = Arc::new(RwLock::new(NonCopy(10))); - let m2 = m.clone(); - let _ = thread::spawn(move || { - let _lock = m2.write().unwrap(); - panic!("test panic in inner thread to poison RwLock"); - }) - .join(); - - assert!(m.is_poisoned()); - match Arc::try_unwrap(m).unwrap().get_mut() { - Err(e) => assert_eq!(*e.into_inner(), NonCopy(10)), - Ok(x) => panic!("get_mut of poisoned RwLock is Ok: {x:?}"), - } -} - -#[test] -fn test_read_guard_covariance() { - fn do_stuff<'a>(_: RwLockReadGuard<'_, &'a i32>, _: &'a i32) {} - let j: i32 = 5; - let lock = RwLock::new(&j); - { - let i = 6; - do_stuff(lock.read().unwrap(), &i); - } - drop(lock); -} - -#[test] -fn test_mapped_read_guard_covariance() { - fn do_stuff<'a>(_: MappedRwLockReadGuard<'_, &'a i32>, _: &'a i32) {} - let j: i32 = 5; - let lock = RwLock::new((&j, &j)); - { - let i = 6; - let guard = lock.read().unwrap(); - let guard = RwLockReadGuard::map(guard, |(val, _val)| val); - do_stuff(guard, &i); - } - drop(lock); -} - -#[test] -fn test_mapping_mapped_guard() { - let arr = [0; 4]; - let mut lock = RwLock::new(arr); - let guard = lock.write().unwrap(); - let guard = RwLockWriteGuard::map(guard, |arr| &mut arr[..2]); - let mut guard = MappedRwLockWriteGuard::map(guard, |slice| &mut slice[1..]); - assert_eq!(guard.len(), 1); - guard[0] = 42; - drop(guard); - assert_eq!(*lock.get_mut().unwrap(), [0, 42, 0, 0]); - - let guard = lock.read().unwrap(); - let guard = RwLockReadGuard::map(guard, |arr| &arr[..2]); - let guard = MappedRwLockReadGuard::map(guard, |slice| &slice[1..]); - assert_eq!(*guard, [42]); - drop(guard); - assert_eq!(*lock.get_mut().unwrap(), [0, 42, 0, 0]); -} - -#[test] -fn panic_while_mapping_read_unlocked_no_poison() { - let lock = RwLock::new(()); - - let _ = crate::panic::catch_unwind(|| { - let guard = lock.read().unwrap(); - let _guard = RwLockReadGuard::map::<(), _>(guard, |_| panic!()); - }); - - match lock.try_write() { - Ok(_) => {} - Err(TryLockError::WouldBlock) => { - panic!("panicking in a RwLockReadGuard::map closure should release the read lock") - } - Err(TryLockError::Poisoned(_)) => { - panic!("panicking in a RwLockReadGuard::map closure should not poison the RwLock") - } - } - - let _ = crate::panic::catch_unwind(|| { - let guard = lock.read().unwrap(); - let _guard = RwLockReadGuard::try_map::<(), _>(guard, |_| panic!()); - }); - - match lock.try_write() { - Ok(_) => {} - Err(TryLockError::WouldBlock) => { - panic!("panicking in a RwLockReadGuard::try_map closure should release the read lock") - } - Err(TryLockError::Poisoned(_)) => { - panic!("panicking in a RwLockReadGuard::try_map closure should not poison the RwLock") - } - } - - let _ = crate::panic::catch_unwind(|| { - let guard = lock.read().unwrap(); - let guard = RwLockReadGuard::map::<(), _>(guard, |val| val); - let _guard = MappedRwLockReadGuard::map::<(), _>(guard, |_| panic!()); - }); - - match lock.try_write() { - Ok(_) => {} - Err(TryLockError::WouldBlock) => { - panic!("panicking in a MappedRwLockReadGuard::map closure should release the read lock") - } - Err(TryLockError::Poisoned(_)) => { - panic!("panicking in a MappedRwLockReadGuard::map closure should not poison the RwLock") - } - } - - let _ = crate::panic::catch_unwind(|| { - let guard = lock.read().unwrap(); - let guard = RwLockReadGuard::map::<(), _>(guard, |val| val); - let _guard = MappedRwLockReadGuard::try_map::<(), _>(guard, |_| panic!()); - }); - - match lock.try_write() { - Ok(_) => {} - Err(TryLockError::WouldBlock) => panic!( - "panicking in a MappedRwLockReadGuard::try_map closure should release the read lock" - ), - Err(TryLockError::Poisoned(_)) => panic!( - "panicking in a MappedRwLockReadGuard::try_map closure should not poison the RwLock" - ), - } - - drop(lock); -} - -#[test] -fn panic_while_mapping_write_unlocked_poison() { - let lock = RwLock::new(()); - - let _ = crate::panic::catch_unwind(|| { - let guard = lock.write().unwrap(); - let _guard = RwLockWriteGuard::map::<(), _>(guard, |_| panic!()); - }); - - match lock.try_write() { - Ok(_) => panic!("panicking in a RwLockWriteGuard::map closure should poison the RwLock"), - Err(TryLockError::WouldBlock) => { - panic!("panicking in a RwLockWriteGuard::map closure should release the write lock") - } - Err(TryLockError::Poisoned(_)) => {} - } - - let _ = crate::panic::catch_unwind(|| { - let guard = lock.write().unwrap(); - let _guard = RwLockWriteGuard::try_map::<(), _>(guard, |_| panic!()); - }); - - match lock.try_write() { - Ok(_) => { - panic!("panicking in a RwLockWriteGuard::try_map closure should poison the RwLock") - } - Err(TryLockError::WouldBlock) => { - panic!("panicking in a RwLockWriteGuard::try_map closure should release the write lock") - } - Err(TryLockError::Poisoned(_)) => {} - } - - let _ = crate::panic::catch_unwind(|| { - let guard = lock.write().unwrap(); - let guard = RwLockWriteGuard::map::<(), _>(guard, |val| val); - let _guard = MappedRwLockWriteGuard::map::<(), _>(guard, |_| panic!()); - }); - - match lock.try_write() { - Ok(_) => { - panic!("panicking in a MappedRwLockWriteGuard::map closure should poison the RwLock") - } - Err(TryLockError::WouldBlock) => panic!( - "panicking in a MappedRwLockWriteGuard::map closure should release the write lock" - ), - Err(TryLockError::Poisoned(_)) => {} - } - - let _ = crate::panic::catch_unwind(|| { - let guard = lock.write().unwrap(); - let guard = RwLockWriteGuard::map::<(), _>(guard, |val| val); - let _guard = MappedRwLockWriteGuard::try_map::<(), _>(guard, |_| panic!()); - }); - - match lock.try_write() { - Ok(_) => panic!( - "panicking in a MappedRwLockWriteGuard::try_map closure should poison the RwLock" - ), - Err(TryLockError::WouldBlock) => panic!( - "panicking in a MappedRwLockWriteGuard::try_map closure should release the write lock" - ), - Err(TryLockError::Poisoned(_)) => {} - } - - drop(lock); -} diff --git a/library/std/src/sys/cmath.rs b/library/std/src/sys/cmath.rs deleted file mode 100644 index 99df503b82de2..0000000000000 --- a/library/std/src/sys/cmath.rs +++ /dev/null @@ -1,88 +0,0 @@ -#![cfg(not(test))] - -// These symbols are all defined by `libm`, -// or by `compiler-builtins` on unsupported platforms. -extern "C" { - pub fn acos(n: f64) -> f64; - pub fn asin(n: f64) -> f64; - pub fn atan(n: f64) -> f64; - pub fn atan2(a: f64, b: f64) -> f64; - pub fn cbrt(n: f64) -> f64; - pub fn cbrtf(n: f32) -> f32; - pub fn cosh(n: f64) -> f64; - pub fn expm1(n: f64) -> f64; - pub fn expm1f(n: f32) -> f32; - pub fn fdim(a: f64, b: f64) -> f64; - pub fn fdimf(a: f32, b: f32) -> f32; - #[cfg_attr(target_env = "msvc", link_name = "_hypot")] - pub fn hypot(x: f64, y: f64) -> f64; - #[cfg_attr(target_env = "msvc", link_name = "_hypotf")] - pub fn hypotf(x: f32, y: f32) -> f32; - pub fn log1p(n: f64) -> f64; - pub fn log1pf(n: f32) -> f32; - pub fn sinh(n: f64) -> f64; - pub fn tan(n: f64) -> f64; - pub fn tanh(n: f64) -> f64; - pub fn tgamma(n: f64) -> f64; - pub fn tgammaf(n: f32) -> f32; - pub fn lgamma_r(n: f64, s: &mut i32) -> f64; - pub fn lgammaf_r(n: f32, s: &mut i32) -> f32; - - cfg_if::cfg_if! { - if #[cfg(not(all(target_os = "windows", target_env = "msvc", target_arch = "x86")))] { - pub fn acosf(n: f32) -> f32; - pub fn asinf(n: f32) -> f32; - pub fn atan2f(a: f32, b: f32) -> f32; - pub fn atanf(n: f32) -> f32; - pub fn coshf(n: f32) -> f32; - pub fn sinhf(n: f32) -> f32; - pub fn tanf(n: f32) -> f32; - pub fn tanhf(n: f32) -> f32; - }} -} - -// On 32-bit x86 MSVC these functions aren't defined, so we just define shims -// which promote everything to f64, perform the calculation, and then demote -// back to f32. While not precisely correct should be "correct enough" for now. -cfg_if::cfg_if! { -if #[cfg(all(target_os = "windows", target_env = "msvc", target_arch = "x86"))] { - #[inline] - pub unsafe fn acosf(n: f32) -> f32 { - f64::acos(n as f64) as f32 - } - - #[inline] - pub unsafe fn asinf(n: f32) -> f32 { - f64::asin(n as f64) as f32 - } - - #[inline] - pub unsafe fn atan2f(n: f32, b: f32) -> f32 { - f64::atan2(n as f64, b as f64) as f32 - } - - #[inline] - pub unsafe fn atanf(n: f32) -> f32 { - f64::atan(n as f64) as f32 - } - - #[inline] - pub unsafe fn coshf(n: f32) -> f32 { - f64::cosh(n as f64) as f32 - } - - #[inline] - pub unsafe fn sinhf(n: f32) -> f32 { - f64::sinh(n as f64) as f32 - } - - #[inline] - pub unsafe fn tanf(n: f32) -> f32 { - f64::tan(n as f64) as f32 - } - - #[inline] - pub unsafe fn tanhf(n: f32) -> f32 { - f64::tanh(n as f64) as f32 - } -}} diff --git a/library/std/src/sys/mod.rs b/library/std/src/sys/mod.rs deleted file mode 100644 index 8f70cefc60121..0000000000000 --- a/library/std/src/sys/mod.rs +++ /dev/null @@ -1,16 +0,0 @@ -/// The PAL (platform abstraction layer) contains platform-specific abstractions -/// for implementing the features in the other submodules, e.g. UNIX file -/// descriptors. -mod pal; - -mod personality; - -pub mod cmath; -pub mod os_str; -pub mod path; -pub mod sync; -pub mod thread_local; - -// FIXME(117276): remove this, move feature implementations into individual -// submodules. -pub use pal::*; diff --git a/library/std/src/sys/os_str/bytes.rs b/library/std/src/sys/os_str/bytes.rs deleted file mode 100644 index 18b969bca85a6..0000000000000 --- a/library/std/src/sys/os_str/bytes.rs +++ /dev/null @@ -1,334 +0,0 @@ -//! The underlying OsString/OsStr implementation on Unix and many other -//! systems: just a `Vec`/`[u8]`. - -use crate::borrow::Cow; -use crate::collections::TryReserveError; -use crate::fmt; -use crate::fmt::Write; -use crate::mem; -use crate::rc::Rc; -use crate::str; -use crate::sync::Arc; -use crate::sys_common::{AsInner, IntoInner}; - -#[cfg(test)] -mod tests; - -#[derive(Hash)] -#[repr(transparent)] -pub struct Buf { - pub inner: Vec, -} - -#[repr(transparent)] -pub struct Slice { - pub inner: [u8], -} - -impl fmt::Debug for Slice { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&self.inner.utf8_chunks().debug(), f) - } -} - -impl fmt::Display for Slice { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - // If we're the empty string then our iterator won't actually yield - // anything, so perform the formatting manually - if self.inner.is_empty() { - return "".fmt(f); - } - - for chunk in self.inner.utf8_chunks() { - let valid = chunk.valid(); - // If we successfully decoded the whole chunk as a valid string then - // we can return a direct formatting of the string which will also - // respect various formatting flags if possible. - if chunk.invalid().is_empty() { - return valid.fmt(f); - } - - f.write_str(valid)?; - f.write_char(char::REPLACEMENT_CHARACTER)?; - } - Ok(()) - } -} - -impl fmt::Debug for Buf { - fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(self.as_slice(), formatter) - } -} - -impl fmt::Display for Buf { - fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt(self.as_slice(), formatter) - } -} - -impl Clone for Buf { - #[inline] - fn clone(&self) -> Self { - Buf { inner: self.inner.clone() } - } - - #[inline] - fn clone_from(&mut self, source: &Self) { - self.inner.clone_from(&source.inner) - } -} - -impl IntoInner> for Buf { - fn into_inner(self) -> Vec { - self.inner - } -} - -impl AsInner<[u8]> for Buf { - #[inline] - fn as_inner(&self) -> &[u8] { - &self.inner - } -} - -impl Buf { - #[inline] - pub fn into_encoded_bytes(self) -> Vec { - self.inner - } - - #[inline] - pub unsafe fn from_encoded_bytes_unchecked(s: Vec) -> Self { - Self { inner: s } - } - - pub fn from_string(s: String) -> Buf { - Buf { inner: s.into_bytes() } - } - - #[inline] - pub fn with_capacity(capacity: usize) -> Buf { - Buf { inner: Vec::with_capacity(capacity) } - } - - #[inline] - pub fn clear(&mut self) { - self.inner.clear() - } - - #[inline] - pub fn capacity(&self) -> usize { - self.inner.capacity() - } - - #[inline] - pub fn reserve(&mut self, additional: usize) { - self.inner.reserve(additional) - } - - #[inline] - pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> { - self.inner.try_reserve(additional) - } - - #[inline] - pub fn reserve_exact(&mut self, additional: usize) { - self.inner.reserve_exact(additional) - } - - #[inline] - pub fn try_reserve_exact(&mut self, additional: usize) -> Result<(), TryReserveError> { - self.inner.try_reserve_exact(additional) - } - - #[inline] - pub fn shrink_to_fit(&mut self) { - self.inner.shrink_to_fit() - } - - #[inline] - pub fn shrink_to(&mut self, min_capacity: usize) { - self.inner.shrink_to(min_capacity) - } - - #[inline] - pub fn as_slice(&self) -> &Slice { - // SAFETY: Slice just wraps [u8], - // and &*self.inner is &[u8], therefore - // transmuting &[u8] to &Slice is safe. - unsafe { mem::transmute(&*self.inner) } - } - - #[inline] - pub fn as_mut_slice(&mut self) -> &mut Slice { - // SAFETY: Slice just wraps [u8], - // and &mut *self.inner is &mut [u8], therefore - // transmuting &mut [u8] to &mut Slice is safe. - unsafe { mem::transmute(&mut *self.inner) } - } - - pub fn into_string(self) -> Result { - String::from_utf8(self.inner).map_err(|p| Buf { inner: p.into_bytes() }) - } - - pub fn push_slice(&mut self, s: &Slice) { - self.inner.extend_from_slice(&s.inner) - } - - #[inline] - pub fn into_box(self) -> Box { - unsafe { mem::transmute(self.inner.into_boxed_slice()) } - } - - #[inline] - pub fn from_box(boxed: Box) -> Buf { - let inner: Box<[u8]> = unsafe { mem::transmute(boxed) }; - Buf { inner: inner.into_vec() } - } - - #[inline] - pub fn into_arc(&self) -> Arc { - self.as_slice().into_arc() - } - - #[inline] - pub fn into_rc(&self) -> Rc { - self.as_slice().into_rc() - } - - /// Part of a hack to make PathBuf::push/pop more efficient. - #[inline] - pub(crate) fn as_mut_vec_for_path_buf(&mut self) -> &mut Vec { - &mut self.inner - } -} - -impl Slice { - #[inline] - pub fn as_encoded_bytes(&self) -> &[u8] { - &self.inner - } - - #[inline] - pub unsafe fn from_encoded_bytes_unchecked(s: &[u8]) -> &Slice { - unsafe { mem::transmute(s) } - } - - #[track_caller] - #[inline] - pub fn check_public_boundary(&self, index: usize) { - if index == 0 || index == self.inner.len() { - return; - } - if index < self.inner.len() - && (self.inner[index - 1].is_ascii() || self.inner[index].is_ascii()) - { - return; - } - - slow_path(&self.inner, index); - - /// We're betting that typical splits will involve an ASCII character. - /// - /// Putting the expensive checks in a separate function generates notably - /// better assembly. - #[track_caller] - #[inline(never)] - fn slow_path(bytes: &[u8], index: usize) { - let (before, after) = bytes.split_at(index); - - // UTF-8 takes at most 4 bytes per codepoint, so we don't - // need to check more than that. - let after = after.get(..4).unwrap_or(after); - match str::from_utf8(after) { - Ok(_) => return, - Err(err) if err.valid_up_to() != 0 => return, - Err(_) => (), - } - - for len in 2..=4.min(index) { - let before = &before[index - len..]; - if str::from_utf8(before).is_ok() { - return; - } - } - - panic!("byte index {index} is not an OsStr boundary"); - } - } - - #[inline] - pub fn from_str(s: &str) -> &Slice { - unsafe { Slice::from_encoded_bytes_unchecked(s.as_bytes()) } - } - - pub fn to_str(&self) -> Result<&str, crate::str::Utf8Error> { - str::from_utf8(&self.inner) - } - - pub fn to_string_lossy(&self) -> Cow<'_, str> { - String::from_utf8_lossy(&self.inner) - } - - pub fn to_owned(&self) -> Buf { - Buf { inner: self.inner.to_vec() } - } - - pub fn clone_into(&self, buf: &mut Buf) { - self.inner.clone_into(&mut buf.inner) - } - - #[inline] - pub fn into_box(&self) -> Box { - let boxed: Box<[u8]> = self.inner.into(); - unsafe { mem::transmute(boxed) } - } - - pub fn empty_box() -> Box { - let boxed: Box<[u8]> = Default::default(); - unsafe { mem::transmute(boxed) } - } - - #[inline] - pub fn into_arc(&self) -> Arc { - let arc: Arc<[u8]> = Arc::from(&self.inner); - unsafe { Arc::from_raw(Arc::into_raw(arc) as *const Slice) } - } - - #[inline] - pub fn into_rc(&self) -> Rc { - let rc: Rc<[u8]> = Rc::from(&self.inner); - unsafe { Rc::from_raw(Rc::into_raw(rc) as *const Slice) } - } - - #[inline] - pub fn make_ascii_lowercase(&mut self) { - self.inner.make_ascii_lowercase() - } - - #[inline] - pub fn make_ascii_uppercase(&mut self) { - self.inner.make_ascii_uppercase() - } - - #[inline] - pub fn to_ascii_lowercase(&self) -> Buf { - Buf { inner: self.inner.to_ascii_lowercase() } - } - - #[inline] - pub fn to_ascii_uppercase(&self) -> Buf { - Buf { inner: self.inner.to_ascii_uppercase() } - } - - #[inline] - pub fn is_ascii(&self) -> bool { - self.inner.is_ascii() - } - - #[inline] - pub fn eq_ignore_ascii_case(&self, other: &Self) -> bool { - self.inner.eq_ignore_ascii_case(&other.inner) - } -} diff --git a/library/std/src/sys/os_str/bytes/tests.rs b/library/std/src/sys/os_str/bytes/tests.rs deleted file mode 100644 index e2a99045e41f6..0000000000000 --- a/library/std/src/sys/os_str/bytes/tests.rs +++ /dev/null @@ -1,17 +0,0 @@ -use super::*; - -#[test] -fn slice_debug_output() { - let input = unsafe { Slice::from_encoded_bytes_unchecked(b"\xF0hello,\tworld") }; - let expected = r#""\xF0hello,\tworld""#; - let output = format!("{input:?}"); - - assert_eq!(output, expected); -} - -#[test] -fn display() { - assert_eq!("Hello\u{FFFD}\u{FFFD} There\u{FFFD} Goodbye", unsafe { - Slice::from_encoded_bytes_unchecked(b"Hello\xC0\x80 There\xE6\x83 Goodbye").to_string() - },); -} diff --git a/library/std/src/sys/os_str/mod.rs b/library/std/src/sys/os_str/mod.rs deleted file mode 100644 index b509729475bf7..0000000000000 --- a/library/std/src/sys/os_str/mod.rs +++ /dev/null @@ -1,12 +0,0 @@ -cfg_if::cfg_if! { - if #[cfg(any( - target_os = "windows", - target_os = "uefi", - ))] { - mod wtf8; - pub use wtf8::{Buf, Slice}; - } else { - mod bytes; - pub use bytes::{Buf, Slice}; - } -} diff --git a/library/std/src/sys/os_str/wtf8.rs b/library/std/src/sys/os_str/wtf8.rs deleted file mode 100644 index b3ceb55802dc5..0000000000000 --- a/library/std/src/sys/os_str/wtf8.rs +++ /dev/null @@ -1,256 +0,0 @@ -/// The underlying OsString/OsStr implementation on Windows is a -/// wrapper around the "WTF-8" encoding; see the `wtf8` module for more. -use crate::borrow::Cow; -use crate::collections::TryReserveError; -use crate::fmt; -use crate::mem; -use crate::rc::Rc; -use crate::sync::Arc; -use crate::sys_common::wtf8::{check_utf8_boundary, Wtf8, Wtf8Buf}; -use crate::sys_common::{AsInner, FromInner, IntoInner}; - -#[derive(Clone, Hash)] -pub struct Buf { - pub inner: Wtf8Buf, -} - -impl IntoInner for Buf { - fn into_inner(self) -> Wtf8Buf { - self.inner - } -} - -impl FromInner for Buf { - fn from_inner(inner: Wtf8Buf) -> Self { - Buf { inner } - } -} - -impl AsInner for Buf { - #[inline] - fn as_inner(&self) -> &Wtf8 { - &self.inner - } -} - -impl fmt::Debug for Buf { - fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(self.as_slice(), formatter) - } -} - -impl fmt::Display for Buf { - fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt(self.as_slice(), formatter) - } -} - -#[repr(transparent)] -pub struct Slice { - pub inner: Wtf8, -} - -impl fmt::Debug for Slice { - fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&self.inner, formatter) - } -} - -impl fmt::Display for Slice { - fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt(&self.inner, formatter) - } -} - -impl Buf { - #[inline] - pub fn into_encoded_bytes(self) -> Vec { - self.inner.into_bytes() - } - - #[inline] - pub unsafe fn from_encoded_bytes_unchecked(s: Vec) -> Self { - Self { inner: Wtf8Buf::from_bytes_unchecked(s) } - } - - pub fn with_capacity(capacity: usize) -> Buf { - Buf { inner: Wtf8Buf::with_capacity(capacity) } - } - - pub fn clear(&mut self) { - self.inner.clear() - } - - pub fn capacity(&self) -> usize { - self.inner.capacity() - } - - pub fn from_string(s: String) -> Buf { - Buf { inner: Wtf8Buf::from_string(s) } - } - - pub fn as_slice(&self) -> &Slice { - // SAFETY: Slice is just a wrapper for Wtf8, - // and self.inner.as_slice() returns &Wtf8. - // Therefore, transmuting &Wtf8 to &Slice is safe. - unsafe { mem::transmute(self.inner.as_slice()) } - } - - pub fn as_mut_slice(&mut self) -> &mut Slice { - // SAFETY: Slice is just a wrapper for Wtf8, - // and self.inner.as_mut_slice() returns &mut Wtf8. - // Therefore, transmuting &mut Wtf8 to &mut Slice is safe. - // Additionally, care should be taken to ensure the slice - // is always valid Wtf8. - unsafe { mem::transmute(self.inner.as_mut_slice()) } - } - - pub fn into_string(self) -> Result { - self.inner.into_string().map_err(|buf| Buf { inner: buf }) - } - - pub fn push_slice(&mut self, s: &Slice) { - self.inner.push_wtf8(&s.inner) - } - - pub fn reserve(&mut self, additional: usize) { - self.inner.reserve(additional) - } - - pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> { - self.inner.try_reserve(additional) - } - - pub fn reserve_exact(&mut self, additional: usize) { - self.inner.reserve_exact(additional) - } - - pub fn try_reserve_exact(&mut self, additional: usize) -> Result<(), TryReserveError> { - self.inner.try_reserve_exact(additional) - } - - pub fn shrink_to_fit(&mut self) { - self.inner.shrink_to_fit() - } - - #[inline] - pub fn shrink_to(&mut self, min_capacity: usize) { - self.inner.shrink_to(min_capacity) - } - - #[inline] - pub fn into_box(self) -> Box { - unsafe { mem::transmute(self.inner.into_box()) } - } - - #[inline] - pub fn from_box(boxed: Box) -> Buf { - let inner: Box = unsafe { mem::transmute(boxed) }; - Buf { inner: Wtf8Buf::from_box(inner) } - } - - #[inline] - pub fn into_arc(&self) -> Arc { - self.as_slice().into_arc() - } - - #[inline] - pub fn into_rc(&self) -> Rc { - self.as_slice().into_rc() - } - - /// Part of a hack to make PathBuf::push/pop more efficient. - #[inline] - pub(crate) fn as_mut_vec_for_path_buf(&mut self) -> &mut Vec { - self.inner.as_mut_vec_for_path_buf() - } -} - -impl Slice { - #[inline] - pub fn as_encoded_bytes(&self) -> &[u8] { - self.inner.as_bytes() - } - - #[inline] - pub unsafe fn from_encoded_bytes_unchecked(s: &[u8]) -> &Slice { - mem::transmute(Wtf8::from_bytes_unchecked(s)) - } - - #[track_caller] - pub fn check_public_boundary(&self, index: usize) { - check_utf8_boundary(&self.inner, index); - } - - #[inline] - pub fn from_str(s: &str) -> &Slice { - unsafe { mem::transmute(Wtf8::from_str(s)) } - } - - pub fn to_str(&self) -> Result<&str, crate::str::Utf8Error> { - self.inner.as_str() - } - - pub fn to_string_lossy(&self) -> Cow<'_, str> { - self.inner.to_string_lossy() - } - - pub fn to_owned(&self) -> Buf { - Buf { inner: self.inner.to_owned() } - } - - pub fn clone_into(&self, buf: &mut Buf) { - self.inner.clone_into(&mut buf.inner) - } - - #[inline] - pub fn into_box(&self) -> Box { - unsafe { mem::transmute(self.inner.into_box()) } - } - - pub fn empty_box() -> Box { - unsafe { mem::transmute(Wtf8::empty_box()) } - } - - #[inline] - pub fn into_arc(&self) -> Arc { - let arc = self.inner.into_arc(); - unsafe { Arc::from_raw(Arc::into_raw(arc) as *const Slice) } - } - - #[inline] - pub fn into_rc(&self) -> Rc { - let rc = self.inner.into_rc(); - unsafe { Rc::from_raw(Rc::into_raw(rc) as *const Slice) } - } - - #[inline] - pub fn make_ascii_lowercase(&mut self) { - self.inner.make_ascii_lowercase() - } - - #[inline] - pub fn make_ascii_uppercase(&mut self) { - self.inner.make_ascii_uppercase() - } - - #[inline] - pub fn to_ascii_lowercase(&self) -> Buf { - Buf { inner: self.inner.to_ascii_lowercase() } - } - - #[inline] - pub fn to_ascii_uppercase(&self) -> Buf { - Buf { inner: self.inner.to_ascii_uppercase() } - } - - #[inline] - pub fn is_ascii(&self) -> bool { - self.inner.is_ascii() - } - - #[inline] - pub fn eq_ignore_ascii_case(&self, other: &Self) -> bool { - self.inner.eq_ignore_ascii_case(&other.inner) - } -} diff --git a/library/std/src/sys/pal/common/alloc.rs b/library/std/src/sys/pal/common/alloc.rs deleted file mode 100644 index 598b6db71f5de..0000000000000 --- a/library/std/src/sys/pal/common/alloc.rs +++ /dev/null @@ -1,59 +0,0 @@ -use crate::alloc::{GlobalAlloc, Layout, System}; -use crate::cmp; -use crate::ptr; - -// The minimum alignment guaranteed by the architecture. This value is used to -// add fast paths for low alignment values. -#[cfg(any( - target_arch = "x86", - target_arch = "arm", - target_arch = "m68k", - target_arch = "csky", - target_arch = "mips", - target_arch = "mips32r6", - target_arch = "powerpc", - target_arch = "powerpc64", - target_arch = "sparc", - target_arch = "wasm32", - target_arch = "hexagon", - all(target_arch = "riscv32", not(any(target_os = "espidf", target_os = "zkvm"))), - all(target_arch = "xtensa", not(target_os = "espidf")), -))] -pub const MIN_ALIGN: usize = 8; -#[cfg(any( - target_arch = "x86_64", - target_arch = "aarch64", - target_arch = "arm64ec", - target_arch = "loongarch64", - target_arch = "mips64", - target_arch = "mips64r6", - target_arch = "s390x", - target_arch = "sparc64", - target_arch = "riscv64", - target_arch = "wasm64", -))] -pub const MIN_ALIGN: usize = 16; -// The allocator on the esp-idf and zkvm platforms guarantee 4 byte alignment. -#[cfg(all(any( - all(target_arch = "riscv32", any(target_os = "espidf", target_os = "zkvm")), - all(target_arch = "xtensa", target_os = "espidf"), -)))] -pub const MIN_ALIGN: usize = 4; - -pub unsafe fn realloc_fallback( - alloc: &System, - ptr: *mut u8, - old_layout: Layout, - new_size: usize, -) -> *mut u8 { - // Docs for GlobalAlloc::realloc require this to be valid: - let new_layout = Layout::from_size_align_unchecked(new_size, old_layout.align()); - - let new_ptr = GlobalAlloc::alloc(alloc, new_layout); - if !new_ptr.is_null() { - let size = cmp::min(old_layout.size(), new_size); - ptr::copy_nonoverlapping(ptr, new_ptr, size); - GlobalAlloc::dealloc(alloc, ptr, old_layout); - } - new_ptr -} diff --git a/library/std/src/sys/pal/common/mod.rs b/library/std/src/sys/pal/common/mod.rs deleted file mode 100644 index 29fc0835d7666..0000000000000 --- a/library/std/src/sys/pal/common/mod.rs +++ /dev/null @@ -1,17 +0,0 @@ -// This module contains code that is shared between all platforms, mostly utility or fallback code. -// This explicitly does not include code that is shared between only a few platforms, -// such as when reusing an implementation from `unix` or `unsupported`. -// In those cases the desired code should be included directly using the #[path] attribute, -// not moved to this module. -// -// Currently `sys_common` contains a lot of code that should live in this module, -// ideally `sys_common` would only contain platform-independent abstractions on top of `sys`. -// Progress on this is tracked in #84187. - -#![allow(dead_code)] - -pub mod alloc; -pub mod small_c_string; - -#[cfg(test)] -mod tests; diff --git a/library/std/src/sys/pal/common/small_c_string.rs b/library/std/src/sys/pal/common/small_c_string.rs deleted file mode 100644 index 37812fc0659a2..0000000000000 --- a/library/std/src/sys/pal/common/small_c_string.rs +++ /dev/null @@ -1,61 +0,0 @@ -use crate::ffi::{CStr, CString}; -use crate::mem::MaybeUninit; -use crate::path::Path; -use crate::slice; -use crate::{io, ptr}; - -// Make sure to stay under 4096 so the compiler doesn't insert a probe frame: -// https://docs.rs/compiler_builtins/latest/compiler_builtins/probestack/index.html -#[cfg(not(target_os = "espidf"))] -const MAX_STACK_ALLOCATION: usize = 384; -#[cfg(target_os = "espidf")] -const MAX_STACK_ALLOCATION: usize = 32; - -const NUL_ERR: io::Error = - io::const_io_error!(io::ErrorKind::InvalidInput, "file name contained an unexpected NUL byte"); - -#[inline] -pub fn run_path_with_cstr(path: &Path, f: &dyn Fn(&CStr) -> io::Result) -> io::Result { - run_with_cstr(path.as_os_str().as_encoded_bytes(), f) -} - -#[inline] -pub fn run_with_cstr(bytes: &[u8], f: &dyn Fn(&CStr) -> io::Result) -> io::Result { - // Dispatch and dyn erase the closure type to prevent mono bloat. - // See https://github.com/rust-lang/rust/pull/121101. - if bytes.len() >= MAX_STACK_ALLOCATION { - run_with_cstr_allocating(bytes, f) - } else { - unsafe { run_with_cstr_stack(bytes, f) } - } -} - -/// # Safety -/// -/// `bytes` must have a length less than `MAX_STACK_ALLOCATION`. -unsafe fn run_with_cstr_stack( - bytes: &[u8], - f: &dyn Fn(&CStr) -> io::Result, -) -> io::Result { - let mut buf = MaybeUninit::<[u8; MAX_STACK_ALLOCATION]>::uninit(); - let buf_ptr = buf.as_mut_ptr() as *mut u8; - - unsafe { - ptr::copy_nonoverlapping(bytes.as_ptr(), buf_ptr, bytes.len()); - buf_ptr.add(bytes.len()).write(0); - } - - match CStr::from_bytes_with_nul(unsafe { slice::from_raw_parts(buf_ptr, bytes.len() + 1) }) { - Ok(s) => f(s), - Err(_) => Err(NUL_ERR), - } -} - -#[cold] -#[inline(never)] -fn run_with_cstr_allocating(bytes: &[u8], f: &dyn Fn(&CStr) -> io::Result) -> io::Result { - match CString::new(bytes) { - Ok(s) => f(&s), - Err(_) => Err(NUL_ERR), - } -} diff --git a/library/std/src/sys/pal/common/tests.rs b/library/std/src/sys/pal/common/tests.rs deleted file mode 100644 index e72d02203da10..0000000000000 --- a/library/std/src/sys/pal/common/tests.rs +++ /dev/null @@ -1,66 +0,0 @@ -use crate::ffi::CString; -use crate::hint::black_box; -use crate::path::Path; -use crate::sys::common::small_c_string::run_path_with_cstr; -use core::iter::repeat; - -#[test] -fn stack_allocation_works() { - let path = Path::new("abc"); - let result = run_path_with_cstr(path, &|p| { - assert_eq!(p, &*CString::new(path.as_os_str().as_encoded_bytes()).unwrap()); - Ok(42) - }); - assert_eq!(result.unwrap(), 42); -} - -#[test] -fn stack_allocation_fails() { - let path = Path::new("ab\0"); - assert!(run_path_with_cstr::<()>(path, &|_| unreachable!()).is_err()); -} - -#[test] -fn heap_allocation_works() { - let path = repeat("a").take(384).collect::(); - let path = Path::new(&path); - let result = run_path_with_cstr(path, &|p| { - assert_eq!(p, &*CString::new(path.as_os_str().as_encoded_bytes()).unwrap()); - Ok(42) - }); - assert_eq!(result.unwrap(), 42); -} - -#[test] -fn heap_allocation_fails() { - let mut path = repeat("a").take(384).collect::(); - path.push('\0'); - let path = Path::new(&path); - assert!(run_path_with_cstr::<()>(path, &|_| unreachable!()).is_err()); -} - -#[bench] -fn bench_stack_path_alloc(b: &mut test::Bencher) { - let path = repeat("a").take(383).collect::(); - let p = Path::new(&path); - b.iter(|| { - run_path_with_cstr(p, &|cstr| { - black_box(cstr); - Ok(()) - }) - .unwrap(); - }); -} - -#[bench] -fn bench_heap_path_alloc(b: &mut test::Bencher) { - let path = repeat("a").take(384).collect::(); - let p = Path::new(&path); - b.iter(|| { - run_path_with_cstr(p, &|cstr| { - black_box(cstr); - Ok(()) - }) - .unwrap(); - }); -} diff --git a/library/std/src/sys/pal/hermit/alloc.rs b/library/std/src/sys/pal/hermit/alloc.rs deleted file mode 100644 index 2cd0db909403b..0000000000000 --- a/library/std/src/sys/pal/hermit/alloc.rs +++ /dev/null @@ -1,31 +0,0 @@ -use super::hermit_abi; -use crate::alloc::{GlobalAlloc, Layout, System}; -use crate::ptr; - -#[stable(feature = "alloc_system_type", since = "1.28.0")] -unsafe impl GlobalAlloc for System { - #[inline] - unsafe fn alloc(&self, layout: Layout) -> *mut u8 { - hermit_abi::malloc(layout.size(), layout.align()) - } - - unsafe fn alloc_zeroed(&self, layout: Layout) -> *mut u8 { - let addr = hermit_abi::malloc(layout.size(), layout.align()); - - if !addr.is_null() { - ptr::write_bytes(addr, 0x00, layout.size()); - } - - addr - } - - #[inline] - unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) { - hermit_abi::free(ptr, layout.size(), layout.align()) - } - - #[inline] - unsafe fn realloc(&self, ptr: *mut u8, layout: Layout, new_size: usize) -> *mut u8 { - hermit_abi::realloc(ptr, layout.size(), layout.align(), new_size) - } -} diff --git a/library/std/src/sys/pal/hermit/args.rs b/library/std/src/sys/pal/hermit/args.rs deleted file mode 100644 index 220a76e4b1237..0000000000000 --- a/library/std/src/sys/pal/hermit/args.rs +++ /dev/null @@ -1,70 +0,0 @@ -use crate::ffi::{c_char, CStr, OsString}; -use crate::fmt; -use crate::os::hermit::ffi::OsStringExt; -use crate::ptr; -use crate::sync::atomic::{ - AtomicIsize, AtomicPtr, - Ordering::{Acquire, Relaxed, Release}, -}; -use crate::vec; - -static ARGC: AtomicIsize = AtomicIsize::new(0); -static ARGV: AtomicPtr<*const u8> = AtomicPtr::new(ptr::null_mut()); - -/// One-time global initialization. -pub unsafe fn init(argc: isize, argv: *const *const u8) { - ARGC.store(argc, Relaxed); - // Use release ordering here to broadcast writes by the OS. - ARGV.store(argv as *mut *const u8, Release); -} - -/// Returns the command line arguments -pub fn args() -> Args { - // Synchronize with the store above. - let argv = ARGV.load(Acquire); - // If argv has not been initialized yet, do not return any arguments. - let argc = if argv.is_null() { 0 } else { ARGC.load(Relaxed) }; - let args: Vec = (0..argc) - .map(|i| unsafe { - let cstr = CStr::from_ptr(*argv.offset(i) as *const c_char); - OsStringExt::from_vec(cstr.to_bytes().to_vec()) - }) - .collect(); - - Args { iter: args.into_iter() } -} - -pub struct Args { - iter: vec::IntoIter, -} - -impl fmt::Debug for Args { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.iter.as_slice().fmt(f) - } -} - -impl !Send for Args {} -impl !Sync for Args {} - -impl Iterator for Args { - type Item = OsString; - fn next(&mut self) -> Option { - self.iter.next() - } - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } -} - -impl ExactSizeIterator for Args { - fn len(&self) -> usize { - self.iter.len() - } -} - -impl DoubleEndedIterator for Args { - fn next_back(&mut self) -> Option { - self.iter.next_back() - } -} diff --git a/library/std/src/sys/pal/hermit/env.rs b/library/std/src/sys/pal/hermit/env.rs deleted file mode 100644 index 7a0fcb31ef2e8..0000000000000 --- a/library/std/src/sys/pal/hermit/env.rs +++ /dev/null @@ -1,9 +0,0 @@ -pub mod os { - pub const FAMILY: &str = ""; - pub const OS: &str = "hermit"; - pub const DLL_PREFIX: &str = ""; - pub const DLL_SUFFIX: &str = ""; - pub const DLL_EXTENSION: &str = ""; - pub const EXE_SUFFIX: &str = ""; - pub const EXE_EXTENSION: &str = ""; -} diff --git a/library/std/src/sys/pal/hermit/fd.rs b/library/std/src/sys/pal/hermit/fd.rs deleted file mode 100644 index d7dab08cfbd57..0000000000000 --- a/library/std/src/sys/pal/hermit/fd.rs +++ /dev/null @@ -1,108 +0,0 @@ -#![unstable(reason = "not public", issue = "none", feature = "fd")] - -use super::hermit_abi; -use crate::io::{self, Read}; -use crate::os::hermit::io::{FromRawFd, OwnedFd, RawFd}; -use crate::sys::cvt; -use crate::sys::unsupported; -use crate::sys_common::{AsInner, FromInner, IntoInner}; - -use crate::os::hermit::io::*; - -#[derive(Debug)] -pub struct FileDesc { - fd: OwnedFd, -} - -impl FileDesc { - pub fn read(&self, buf: &mut [u8]) -> io::Result { - let result = - cvt(unsafe { hermit_abi::read(self.fd.as_raw_fd(), buf.as_mut_ptr(), buf.len()) })?; - Ok(result as usize) - } - - pub fn read_to_end(&self, buf: &mut Vec) -> io::Result { - let mut me = self; - (&mut me).read_to_end(buf) - } - - pub fn write(&self, buf: &[u8]) -> io::Result { - let result = - cvt(unsafe { hermit_abi::write(self.fd.as_raw_fd(), buf.as_ptr(), buf.len()) })?; - Ok(result as usize) - } - - pub fn duplicate(&self) -> io::Result { - self.duplicate_path(&[]) - } - pub fn duplicate_path(&self, _path: &[u8]) -> io::Result { - unsupported() - } - - pub fn nonblocking(&self) -> io::Result { - Ok(false) - } - - pub fn set_cloexec(&self) -> io::Result<()> { - unsupported() - } - - pub fn set_nonblocking(&self, _nonblocking: bool) -> io::Result<()> { - unsupported() - } - - pub fn fstat(&self, stat: *mut hermit_abi::stat) -> io::Result<()> { - cvt(unsafe { hermit_abi::fstat(self.fd.as_raw_fd(), stat) })?; - Ok(()) - } -} - -impl<'a> Read for &'a FileDesc { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - (**self).read(buf) - } -} - -impl IntoInner for FileDesc { - fn into_inner(self) -> OwnedFd { - self.fd - } -} - -impl FromInner for FileDesc { - fn from_inner(owned_fd: OwnedFd) -> Self { - Self { fd: owned_fd } - } -} - -impl FromRawFd for FileDesc { - unsafe fn from_raw_fd(raw_fd: RawFd) -> Self { - Self { fd: FromRawFd::from_raw_fd(raw_fd) } - } -} - -impl AsInner for FileDesc { - #[inline] - fn as_inner(&self) -> &OwnedFd { - &self.fd - } -} - -impl AsFd for FileDesc { - fn as_fd(&self) -> BorrowedFd<'_> { - self.fd.as_fd() - } -} - -impl AsRawFd for FileDesc { - #[inline] - fn as_raw_fd(&self) -> RawFd { - self.fd.as_raw_fd() - } -} - -impl IntoRawFd for FileDesc { - fn into_raw_fd(self) -> RawFd { - self.fd.into_raw_fd() - } -} diff --git a/library/std/src/sys/pal/hermit/fs.rs b/library/std/src/sys/pal/hermit/fs.rs deleted file mode 100644 index a4a16e6e86b0c..0000000000000 --- a/library/std/src/sys/pal/hermit/fs.rs +++ /dev/null @@ -1,594 +0,0 @@ -use super::fd::FileDesc; -use super::hermit_abi::{ - self, dirent64, stat as stat_struct, DT_DIR, DT_LNK, DT_REG, DT_UNKNOWN, O_APPEND, O_CREAT, - O_EXCL, O_RDONLY, O_RDWR, O_TRUNC, O_WRONLY, S_IFDIR, S_IFLNK, S_IFMT, S_IFREG, -}; -use crate::ffi::{CStr, OsStr, OsString}; -use crate::fmt; -use crate::io::{self, Error, ErrorKind}; -use crate::io::{BorrowedCursor, IoSlice, IoSliceMut, SeekFrom}; -use crate::mem; -use crate::os::hermit::ffi::OsStringExt; -use crate::os::hermit::io::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, RawFd}; -use crate::path::{Path, PathBuf}; -use crate::sync::Arc; -use crate::sys::common::small_c_string::run_path_with_cstr; -use crate::sys::cvt; -use crate::sys::time::SystemTime; -use crate::sys::unsupported; -use crate::sys_common::{AsInner, AsInnerMut, FromInner, IntoInner}; - -pub use crate::sys_common::fs::{copy, try_exists}; - -#[derive(Debug)] -pub struct File(FileDesc); -#[derive(Clone)] -pub struct FileAttr { - stat_val: stat_struct, -} - -impl FileAttr { - fn from_stat(stat_val: stat_struct) -> Self { - Self { stat_val } - } -} - -// all DirEntry's will have a reference to this struct -struct InnerReadDir { - root: PathBuf, - dir: Vec, -} - -impl InnerReadDir { - pub fn new(root: PathBuf, dir: Vec) -> Self { - Self { root, dir } - } -} - -pub struct ReadDir { - inner: Arc, - pos: usize, -} - -impl ReadDir { - fn new(inner: InnerReadDir) -> Self { - Self { inner: Arc::new(inner), pos: 0 } - } -} - -pub struct DirEntry { - /// path to the entry - root: PathBuf, - /// 64-bit inode number - ino: u64, - /// File type - type_: u32, - /// name of the entry - name: OsString, -} - -#[derive(Clone, Debug)] -pub struct OpenOptions { - // generic - read: bool, - write: bool, - append: bool, - truncate: bool, - create: bool, - create_new: bool, - // system-specific - mode: i32, -} - -#[derive(Copy, Clone, Debug, Default)] -pub struct FileTimes {} - -#[derive(Clone, PartialEq, Eq, Debug)] -pub struct FilePermissions { - mode: u32, -} - -#[derive(Copy, Clone, Eq, Debug)] -pub struct FileType { - mode: u32, -} - -impl PartialEq for FileType { - fn eq(&self, other: &Self) -> bool { - self.mode == other.mode - } -} - -impl core::hash::Hash for FileType { - fn hash(&self, state: &mut H) { - self.mode.hash(state); - } -} - -#[derive(Debug)] -pub struct DirBuilder { - mode: u32, -} - -impl FileAttr { - pub fn modified(&self) -> io::Result { - Ok(SystemTime::new( - self.stat_val.st_mtime.try_into().unwrap(), - self.stat_val.st_mtime_nsec.try_into().unwrap(), - )) - } - - pub fn accessed(&self) -> io::Result { - Ok(SystemTime::new( - self.stat_val.st_atime.try_into().unwrap(), - self.stat_val.st_atime_nsec.try_into().unwrap(), - )) - } - - pub fn created(&self) -> io::Result { - Ok(SystemTime::new( - self.stat_val.st_ctime.try_into().unwrap(), - self.stat_val.st_ctime_nsec.try_into().unwrap(), - )) - } - - pub fn size(&self) -> u64 { - self.stat_val.st_size as u64 - } - pub fn perm(&self) -> FilePermissions { - FilePermissions { mode: (self.stat_val.st_mode) } - } - - pub fn file_type(&self) -> FileType { - let masked_mode = self.stat_val.st_mode & S_IFMT; - let mode = match masked_mode { - S_IFDIR => DT_DIR, - S_IFLNK => DT_LNK, - S_IFREG => DT_REG, - _ => DT_UNKNOWN, - }; - FileType { mode: mode } - } -} - -impl FilePermissions { - pub fn readonly(&self) -> bool { - // check if any class (owner, group, others) has write permission - self.mode & 0o222 == 0 - } - - pub fn set_readonly(&mut self, _readonly: bool) { - unimplemented!() - } - - #[allow(dead_code)] - pub fn mode(&self) -> u32 { - self.mode as u32 - } -} - -impl FileTimes { - pub fn set_accessed(&mut self, _t: SystemTime) {} - pub fn set_modified(&mut self, _t: SystemTime) {} -} - -impl FileType { - pub fn is_dir(&self) -> bool { - self.mode == DT_DIR - } - pub fn is_file(&self) -> bool { - self.mode == DT_REG - } - pub fn is_symlink(&self) -> bool { - self.mode == DT_LNK - } -} - -impl fmt::Debug for ReadDir { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - // This will only be called from std::fs::ReadDir, which will add a "ReadDir()" frame. - // Thus the result will be e.g. 'ReadDir("/home")' - fmt::Debug::fmt(&*self.inner.root, f) - } -} - -impl Iterator for ReadDir { - type Item = io::Result; - - fn next(&mut self) -> Option> { - let mut counter: usize = 0; - let mut offset: usize = 0; - - // loop over all directory entries and search the entry for the current position - loop { - // leave function, if the loop reaches the of the buffer (with all entries) - if offset >= self.inner.dir.len() { - return None; - } - - let dir = unsafe { &*(self.inner.dir.as_ptr().add(offset) as *const dirent64) }; - - if counter == self.pos { - self.pos += 1; - - // After dirent64, the file name is stored. d_reclen represents the length of the dirent64 - // plus the length of the file name. Consequently, file name has a size of d_reclen minus - // the size of dirent64. The file name is always a C string and terminated by `\0`. - // Consequently, we are able to ignore the last byte. - let name_bytes = - unsafe { CStr::from_ptr(&dir.d_name as *const _ as *const i8).to_bytes() }; - let entry = DirEntry { - root: self.inner.root.clone(), - ino: dir.d_ino, - type_: dir.d_type as u32, - name: OsString::from_vec(name_bytes.to_vec()), - }; - - return Some(Ok(entry)); - } - - counter += 1; - - // move to the next dirent64, which is directly stored after the previous one - offset = offset + usize::from(dir.d_reclen); - } - } -} - -impl DirEntry { - pub fn path(&self) -> PathBuf { - self.root.join(self.file_name_os_str()) - } - - pub fn file_name(&self) -> OsString { - self.file_name_os_str().to_os_string() - } - - pub fn metadata(&self) -> io::Result { - let mut path = self.path(); - path.set_file_name(self.file_name_os_str()); - lstat(&path) - } - - pub fn file_type(&self) -> io::Result { - Ok(FileType { mode: self.type_ as u32 }) - } - - #[allow(dead_code)] - pub fn ino(&self) -> u64 { - self.ino - } - - pub fn file_name_os_str(&self) -> &OsStr { - self.name.as_os_str() - } -} - -impl OpenOptions { - pub fn new() -> OpenOptions { - OpenOptions { - // generic - read: false, - write: false, - append: false, - truncate: false, - create: false, - create_new: false, - // system-specific - mode: 0o777, - } - } - - pub fn read(&mut self, read: bool) { - self.read = read; - } - pub fn write(&mut self, write: bool) { - self.write = write; - } - pub fn append(&mut self, append: bool) { - self.append = append; - } - pub fn truncate(&mut self, truncate: bool) { - self.truncate = truncate; - } - pub fn create(&mut self, create: bool) { - self.create = create; - } - pub fn create_new(&mut self, create_new: bool) { - self.create_new = create_new; - } - - fn get_access_mode(&self) -> io::Result { - match (self.read, self.write, self.append) { - (true, false, false) => Ok(O_RDONLY), - (false, true, false) => Ok(O_WRONLY), - (true, true, false) => Ok(O_RDWR), - (false, _, true) => Ok(O_WRONLY | O_APPEND), - (true, _, true) => Ok(O_RDWR | O_APPEND), - (false, false, false) => { - Err(io::const_io_error!(ErrorKind::InvalidInput, "invalid access mode")) - } - } - } - - fn get_creation_mode(&self) -> io::Result { - match (self.write, self.append) { - (true, false) => {} - (false, false) => { - if self.truncate || self.create || self.create_new { - return Err(io::const_io_error!( - ErrorKind::InvalidInput, - "invalid creation mode", - )); - } - } - (_, true) => { - if self.truncate && !self.create_new { - return Err(io::const_io_error!( - ErrorKind::InvalidInput, - "invalid creation mode", - )); - } - } - } - - Ok(match (self.create, self.truncate, self.create_new) { - (false, false, false) => 0, - (true, false, false) => O_CREAT, - (false, true, false) => O_TRUNC, - (true, true, false) => O_CREAT | O_TRUNC, - (_, _, true) => O_CREAT | O_EXCL, - }) - } -} - -impl File { - pub fn open(path: &Path, opts: &OpenOptions) -> io::Result { - run_path_with_cstr(path, &|path| File::open_c(&path, opts)) - } - - pub fn open_c(path: &CStr, opts: &OpenOptions) -> io::Result { - let mut flags = opts.get_access_mode()?; - flags = flags | opts.get_creation_mode()?; - - let mode; - if flags & O_CREAT == O_CREAT { - mode = opts.mode; - } else { - mode = 0; - } - - let fd = unsafe { cvt(hermit_abi::open(path.as_ptr(), flags, mode))? }; - Ok(File(unsafe { FileDesc::from_raw_fd(fd as i32) })) - } - - pub fn file_attr(&self) -> io::Result { - let mut stat_val: stat_struct = unsafe { mem::zeroed() }; - self.0.fstat(&mut stat_val)?; - Ok(FileAttr::from_stat(stat_val)) - } - - pub fn fsync(&self) -> io::Result<()> { - Err(Error::from_raw_os_error(22)) - } - - pub fn datasync(&self) -> io::Result<()> { - self.fsync() - } - - pub fn truncate(&self, _size: u64) -> io::Result<()> { - Err(Error::from_raw_os_error(22)) - } - - pub fn read(&self, buf: &mut [u8]) -> io::Result { - self.0.read(buf) - } - - pub fn read_vectored(&self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - crate::io::default_read_vectored(|buf| self.read(buf), bufs) - } - - #[inline] - pub fn is_read_vectored(&self) -> bool { - false - } - - pub fn read_buf(&self, cursor: BorrowedCursor<'_>) -> io::Result<()> { - crate::io::default_read_buf(|buf| self.read(buf), cursor) - } - - pub fn write(&self, buf: &[u8]) -> io::Result { - self.0.write(buf) - } - - pub fn write_vectored(&self, bufs: &[IoSlice<'_>]) -> io::Result { - crate::io::default_write_vectored(|buf| self.write(buf), bufs) - } - - #[inline] - pub fn is_write_vectored(&self) -> bool { - false - } - - #[inline] - pub fn flush(&self) -> io::Result<()> { - Ok(()) - } - - pub fn seek(&self, _pos: SeekFrom) -> io::Result { - Err(Error::from_raw_os_error(22)) - } - - pub fn duplicate(&self) -> io::Result { - Err(Error::from_raw_os_error(22)) - } - - pub fn set_permissions(&self, _perm: FilePermissions) -> io::Result<()> { - Err(Error::from_raw_os_error(22)) - } - - pub fn set_times(&self, _times: FileTimes) -> io::Result<()> { - Err(Error::from_raw_os_error(22)) - } -} - -impl DirBuilder { - pub fn new() -> DirBuilder { - DirBuilder { mode: 0o777 } - } - - pub fn mkdir(&self, path: &Path) -> io::Result<()> { - run_path_with_cstr(path, &|path| { - cvt(unsafe { hermit_abi::mkdir(path.as_ptr(), self.mode) }).map(|_| ()) - }) - } - - #[allow(dead_code)] - pub fn set_mode(&mut self, mode: u32) { - self.mode = mode as u32; - } -} - -impl AsInner for File { - #[inline] - fn as_inner(&self) -> &FileDesc { - &self.0 - } -} - -impl AsInnerMut for File { - #[inline] - fn as_inner_mut(&mut self) -> &mut FileDesc { - &mut self.0 - } -} - -impl IntoInner for File { - fn into_inner(self) -> FileDesc { - self.0 - } -} - -impl FromInner for File { - fn from_inner(file_desc: FileDesc) -> Self { - Self(file_desc) - } -} - -impl AsFd for File { - fn as_fd(&self) -> BorrowedFd<'_> { - self.0.as_fd() - } -} - -impl AsRawFd for File { - #[inline] - fn as_raw_fd(&self) -> RawFd { - self.0.as_raw_fd() - } -} - -impl IntoRawFd for File { - fn into_raw_fd(self) -> RawFd { - self.0.into_raw_fd() - } -} - -impl FromRawFd for File { - unsafe fn from_raw_fd(raw_fd: RawFd) -> Self { - Self(FromRawFd::from_raw_fd(raw_fd)) - } -} - -pub fn readdir(path: &Path) -> io::Result { - let fd_raw = - run_path_with_cstr(path, &|path| cvt(unsafe { hermit_abi::opendir(path.as_ptr()) }))?; - let fd = unsafe { FileDesc::from_raw_fd(fd_raw as i32) }; - let root = path.to_path_buf(); - - // read all director entries - let mut vec: Vec = Vec::new(); - let mut sz = 512; - loop { - // reserve memory to receive all directory entries - vec.resize(sz, 0); - - let readlen = unsafe { - hermit_abi::getdents64(fd.as_raw_fd(), vec.as_mut_ptr() as *mut dirent64, sz) - }; - if readlen > 0 { - // shrink down to the minimal size - vec.resize(readlen.try_into().unwrap(), 0); - break; - } - - // if the buffer is too small, getdents64 returns EINVAL - // otherwise, getdents64 returns an error number - if readlen != (-hermit_abi::errno::EINVAL).into() { - return Err(Error::from_raw_os_error(readlen.try_into().unwrap())); - } - - // we don't have enough memory => try to increase the vector size - sz = sz * 2; - - // 1 MB for directory entries should be enough - // stop here to avoid an endless loop - if sz > 0x100000 { - return Err(Error::from(ErrorKind::Uncategorized)); - } - } - - Ok(ReadDir::new(InnerReadDir::new(root, vec))) -} - -pub fn unlink(path: &Path) -> io::Result<()> { - run_path_with_cstr(path, &|path| cvt(unsafe { hermit_abi::unlink(path.as_ptr()) }).map(|_| ())) -} - -pub fn rename(_old: &Path, _new: &Path) -> io::Result<()> { - unsupported() -} - -pub fn set_perm(_p: &Path, _perm: FilePermissions) -> io::Result<()> { - Err(Error::from_raw_os_error(22)) -} - -pub fn rmdir(path: &Path) -> io::Result<()> { - run_path_with_cstr(path, &|path| cvt(unsafe { hermit_abi::rmdir(path.as_ptr()) }).map(|_| ())) -} - -pub fn remove_dir_all(_path: &Path) -> io::Result<()> { - unsupported() -} - -pub fn readlink(_p: &Path) -> io::Result { - unsupported() -} - -pub fn symlink(_original: &Path, _link: &Path) -> io::Result<()> { - unsupported() -} - -pub fn link(_original: &Path, _link: &Path) -> io::Result<()> { - unsupported() -} - -pub fn stat(path: &Path) -> io::Result { - run_path_with_cstr(path, &|path| { - let mut stat_val: stat_struct = unsafe { mem::zeroed() }; - cvt(unsafe { hermit_abi::stat(path.as_ptr(), &mut stat_val) })?; - Ok(FileAttr::from_stat(stat_val)) - }) -} - -pub fn lstat(path: &Path) -> io::Result { - run_path_with_cstr(path, &|path| { - let mut stat_val: stat_struct = unsafe { mem::zeroed() }; - cvt(unsafe { hermit_abi::lstat(path.as_ptr(), &mut stat_val) })?; - Ok(FileAttr::from_stat(stat_val)) - }) -} - -pub fn canonicalize(_p: &Path) -> io::Result { - unsupported() -} diff --git a/library/std/src/sys/pal/hermit/futex.rs b/library/std/src/sys/pal/hermit/futex.rs deleted file mode 100644 index 571b288565871..0000000000000 --- a/library/std/src/sys/pal/hermit/futex.rs +++ /dev/null @@ -1,39 +0,0 @@ -use super::hermit_abi; -use crate::ptr::null; -use crate::sync::atomic::AtomicU32; -use crate::time::Duration; - -pub fn futex_wait(futex: &AtomicU32, expected: u32, timeout: Option) -> bool { - // Calculate the timeout as a relative timespec. - // - // Overflows are rounded up to an infinite timeout (None). - let timespec = timeout.and_then(|dur| { - Some(hermit_abi::timespec { - tv_sec: dur.as_secs().try_into().ok()?, - tv_nsec: dur.subsec_nanos().into(), - }) - }); - - let r = unsafe { - hermit_abi::futex_wait( - futex.as_ptr(), - expected, - timespec.as_ref().map_or(null(), |t| t as *const hermit_abi::timespec), - hermit_abi::FUTEX_RELATIVE_TIMEOUT, - ) - }; - - r != -hermit_abi::errno::ETIMEDOUT -} - -#[inline] -pub fn futex_wake(futex: &AtomicU32) -> bool { - unsafe { hermit_abi::futex_wake(futex.as_ptr(), 1) > 0 } -} - -#[inline] -pub fn futex_wake_all(futex: &AtomicU32) { - unsafe { - hermit_abi::futex_wake(futex.as_ptr(), i32::MAX); - } -} diff --git a/library/std/src/sys/pal/hermit/mod.rs b/library/std/src/sys/pal/hermit/mod.rs deleted file mode 100644 index a64323a3a296e..0000000000000 --- a/library/std/src/sys/pal/hermit/mod.rs +++ /dev/null @@ -1,190 +0,0 @@ -//! System bindings for HermitCore -//! -//! This module contains the facade (aka platform-specific) implementations of -//! OS level functionality for HermitCore. -//! -//! This is all super highly experimental and not actually intended for -//! wide/production use yet, it's still all in the experimental category. This -//! will likely change over time. -//! -//! Currently all functions here are basically stubs that immediately return -//! errors. The hope is that with a portability lint we can turn actually just -//! remove all this and just omit parts of the standard library if we're -//! compiling for wasm. That way it's a compile time error for something that's -//! guaranteed to be a runtime error! - -#![allow(missing_docs, nonstandard_style, unsafe_op_in_unsafe_fn)] - -use crate::os::raw::c_char; - -pub mod alloc; -pub mod args; -pub mod env; -pub mod fd; -pub mod fs; -pub mod futex; -#[path = "../unsupported/io.rs"] -pub mod io; -pub mod net; -pub mod os; -#[path = "../unsupported/pipe.rs"] -pub mod pipe; -#[path = "../unsupported/process.rs"] -pub mod process; -pub mod stdio; -pub mod thread; -pub mod thread_local_dtor; -#[path = "../unsupported/thread_local_key.rs"] -pub mod thread_local_key; -pub mod time; - -use crate::io::ErrorKind; -use crate::os::hermit::hermit_abi; - -pub fn unsupported() -> crate::io::Result { - Err(unsupported_err()) -} - -pub fn unsupported_err() -> crate::io::Error { - crate::io::const_io_error!( - crate::io::ErrorKind::Unsupported, - "operation not supported on HermitCore yet", - ) -} - -pub fn abort_internal() -> ! { - unsafe { - hermit_abi::abort(); - } -} - -pub fn hashmap_random_keys() -> (u64, u64) { - let mut buf = [0; 16]; - let mut slice = &mut buf[..]; - while !slice.is_empty() { - let res = cvt(unsafe { hermit_abi::read_entropy(slice.as_mut_ptr(), slice.len(), 0) }) - .expect("failed to generate random hashmap keys"); - slice = &mut slice[res as usize..]; - } - - let key1 = buf[..8].try_into().unwrap(); - let key2 = buf[8..].try_into().unwrap(); - (u64::from_ne_bytes(key1), u64::from_ne_bytes(key2)) -} - -// This function is needed by the panic runtime. The symbol is named in -// pre-link args for the target specification, so keep that in sync. -#[cfg(not(test))] -#[no_mangle] -// NB. used by both libunwind and libpanic_abort -pub extern "C" fn __rust_abort() { - abort_internal(); -} - -// SAFETY: must be called only once during runtime initialization. -// NOTE: this is not guaranteed to run, for example when Rust code is called externally. -pub unsafe fn init(argc: isize, argv: *const *const u8, _sigpipe: u8) { - args::init(argc, argv); -} - -// SAFETY: must be called only once during runtime cleanup. -// NOTE: this is not guaranteed to run, for example when the program aborts. -pub unsafe fn cleanup() {} - -#[cfg(not(test))] -#[no_mangle] -pub unsafe extern "C" fn runtime_entry( - argc: i32, - argv: *const *const c_char, - env: *const *const c_char, -) -> ! { - use thread_local_dtor::run_dtors; - extern "C" { - fn main(argc: isize, argv: *const *const c_char) -> i32; - } - - // initialize environment - os::init_environment(env as *const *const i8); - - let result = main(argc as isize, argv); - - run_dtors(); - hermit_abi::exit(result); -} - -#[inline] -pub(crate) fn is_interrupted(errno: i32) -> bool { - errno == hermit_abi::errno::EINTR -} - -pub fn decode_error_kind(errno: i32) -> ErrorKind { - match errno { - hermit_abi::errno::EACCES => ErrorKind::PermissionDenied, - hermit_abi::errno::EADDRINUSE => ErrorKind::AddrInUse, - hermit_abi::errno::EADDRNOTAVAIL => ErrorKind::AddrNotAvailable, - hermit_abi::errno::EAGAIN => ErrorKind::WouldBlock, - hermit_abi::errno::ECONNABORTED => ErrorKind::ConnectionAborted, - hermit_abi::errno::ECONNREFUSED => ErrorKind::ConnectionRefused, - hermit_abi::errno::ECONNRESET => ErrorKind::ConnectionReset, - hermit_abi::errno::EEXIST => ErrorKind::AlreadyExists, - hermit_abi::errno::EINTR => ErrorKind::Interrupted, - hermit_abi::errno::EINVAL => ErrorKind::InvalidInput, - hermit_abi::errno::ENOENT => ErrorKind::NotFound, - hermit_abi::errno::ENOTCONN => ErrorKind::NotConnected, - hermit_abi::errno::EPERM => ErrorKind::PermissionDenied, - hermit_abi::errno::EPIPE => ErrorKind::BrokenPipe, - hermit_abi::errno::ETIMEDOUT => ErrorKind::TimedOut, - _ => ErrorKind::Uncategorized, - } -} - -#[doc(hidden)] -pub trait IsNegative { - fn is_negative(&self) -> bool; - fn negate(&self) -> i32; -} - -macro_rules! impl_is_negative { - ($($t:ident)*) => ($(impl IsNegative for $t { - fn is_negative(&self) -> bool { - *self < 0 - } - - fn negate(&self) -> i32 { - i32::try_from(-(*self)).unwrap() - } - })*) -} - -impl IsNegative for i32 { - fn is_negative(&self) -> bool { - *self < 0 - } - - fn negate(&self) -> i32 { - -(*self) - } -} -impl_is_negative! { i8 i16 i64 isize } - -pub fn cvt(t: T) -> crate::io::Result { - if t.is_negative() { - let e = decode_error_kind(t.negate()); - Err(crate::io::Error::from(e)) - } else { - Ok(t) - } -} - -pub fn cvt_r(mut f: F) -> crate::io::Result -where - T: IsNegative, - F: FnMut() -> T, -{ - loop { - match cvt(f()) { - Err(ref e) if e.is_interrupted() => {} - other => return other, - } - } -} diff --git a/library/std/src/sys/pal/hermit/net.rs b/library/std/src/sys/pal/hermit/net.rs deleted file mode 100644 index 00dbca86a4bae..0000000000000 --- a/library/std/src/sys/pal/hermit/net.rs +++ /dev/null @@ -1,349 +0,0 @@ -#![allow(dead_code)] - -use super::fd::FileDesc; -use crate::cmp; -use crate::io::{self, BorrowedBuf, BorrowedCursor, IoSlice, IoSliceMut}; -use crate::mem; -use crate::net::{Shutdown, SocketAddr}; -use crate::os::hermit::io::{AsFd, AsRawFd, BorrowedFd, FromRawFd, RawFd}; -use crate::sys::time::Instant; -use crate::sys_common::net::{getsockopt, setsockopt, sockaddr_to_addr}; -use crate::sys_common::{AsInner, FromInner, IntoInner}; -use crate::time::Duration; - -use core::ffi::c_int; - -#[allow(unused_extern_crates)] -pub extern crate hermit_abi as netc; - -pub use crate::sys::{cvt, cvt_r}; - -pub type wrlen_t = usize; - -pub fn cvt_gai(err: i32) -> io::Result<()> { - if err == 0 { - return Ok(()); - } - - let detail = ""; - - Err(io::Error::new( - io::ErrorKind::Uncategorized, - &format!("failed to lookup address information: {detail}")[..], - )) -} - -pub fn init() {} - -#[derive(Debug)] -pub struct Socket(FileDesc); - -impl Socket { - pub fn new(addr: &SocketAddr, ty: i32) -> io::Result { - let fam = match *addr { - SocketAddr::V4(..) => netc::AF_INET, - SocketAddr::V6(..) => netc::AF_INET6, - }; - Socket::new_raw(fam, ty) - } - - pub fn new_raw(fam: i32, ty: i32) -> io::Result { - let fd = cvt(unsafe { netc::socket(fam, ty, 0) })?; - Ok(Socket(unsafe { FileDesc::from_raw_fd(fd) })) - } - - pub fn new_pair(_fam: i32, _ty: i32) -> io::Result<(Socket, Socket)> { - unimplemented!() - } - - pub fn connect(&self, addr: &SocketAddr) -> io::Result<()> { - let (addr, len) = addr.into_inner(); - cvt_r(|| unsafe { netc::connect(self.as_raw_fd(), addr.as_ptr(), len) })?; - Ok(()) - } - - pub fn connect_timeout(&self, addr: &SocketAddr, timeout: Duration) -> io::Result<()> { - self.set_nonblocking(true)?; - let r = unsafe { - let (addr, len) = addr.into_inner(); - cvt(netc::connect(self.as_raw_fd(), addr.as_ptr(), len)) - }; - self.set_nonblocking(false)?; - - match r { - Ok(_) => return Ok(()), - // there's no ErrorKind for EINPROGRESS :( - Err(ref e) if e.raw_os_error() == Some(netc::errno::EINPROGRESS) => {} - Err(e) => return Err(e), - } - - let mut pollfd = netc::pollfd { fd: self.as_raw_fd(), events: netc::POLLOUT, revents: 0 }; - - if timeout.as_secs() == 0 && timeout.subsec_nanos() == 0 { - return Err(io::Error::ZERO_TIMEOUT); - } - - let start = Instant::now(); - - loop { - let elapsed = start.elapsed(); - if elapsed >= timeout { - return Err(io::const_io_error!(io::ErrorKind::TimedOut, "connection timed out")); - } - - let timeout = timeout - elapsed; - let mut timeout = timeout - .as_secs() - .saturating_mul(1_000) - .saturating_add(timeout.subsec_nanos() as u64 / 1_000_000); - if timeout == 0 { - timeout = 1; - } - - let timeout = cmp::min(timeout, c_int::MAX as u64) as c_int; - - match unsafe { netc::poll(&mut pollfd, 1, timeout) } { - -1 => { - let err = io::Error::last_os_error(); - if !err.is_interrupted() { - return Err(err); - } - } - 0 => {} - _ => { - // linux returns POLLOUT|POLLERR|POLLHUP for refused connections (!), so look - // for POLLHUP rather than read readiness - if pollfd.revents & netc::POLLHUP != 0 { - let e = self.take_error()?.unwrap_or_else(|| { - io::const_io_error!( - io::ErrorKind::Uncategorized, - "no error set after POLLHUP", - ) - }); - return Err(e); - } - - return Ok(()); - } - } - } - } - - pub fn accept( - &self, - storage: *mut netc::sockaddr, - len: *mut netc::socklen_t, - ) -> io::Result { - let fd = cvt(unsafe { netc::accept(self.0.as_raw_fd(), storage, len) })?; - Ok(Socket(unsafe { FileDesc::from_raw_fd(fd) })) - } - - pub fn duplicate(&self) -> io::Result { - let fd = cvt(unsafe { netc::dup(self.0.as_raw_fd()) })?; - Ok(Socket(unsafe { FileDesc::from_raw_fd(fd) })) - } - - fn recv_with_flags(&self, mut buf: BorrowedCursor<'_>, flags: i32) -> io::Result<()> { - let ret = cvt(unsafe { - netc::recv( - self.0.as_raw_fd(), - buf.as_mut().as_mut_ptr() as *mut u8, - buf.capacity(), - flags, - ) - })?; - unsafe { - buf.advance_unchecked(ret as usize); - } - Ok(()) - } - - pub fn read(&self, buf: &mut [u8]) -> io::Result { - let mut buf = BorrowedBuf::from(buf); - self.recv_with_flags(buf.unfilled(), 0)?; - Ok(buf.len()) - } - - pub fn peek(&self, buf: &mut [u8]) -> io::Result { - let mut buf = BorrowedBuf::from(buf); - self.recv_with_flags(buf.unfilled(), netc::MSG_PEEK)?; - Ok(buf.len()) - } - - pub fn read_buf(&self, buf: BorrowedCursor<'_>) -> io::Result<()> { - self.recv_with_flags(buf, 0) - } - - pub fn read_vectored(&self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - crate::io::default_read_vectored(|b| self.read(b), bufs) - } - - #[inline] - pub fn is_read_vectored(&self) -> bool { - false - } - - fn recv_from_with_flags(&self, buf: &mut [u8], flags: i32) -> io::Result<(usize, SocketAddr)> { - let mut storage: netc::sockaddr_storage = unsafe { mem::zeroed() }; - let mut addrlen = mem::size_of_val(&storage) as netc::socklen_t; - - let n = cvt(unsafe { - netc::recvfrom( - self.as_raw_fd(), - buf.as_mut_ptr(), - buf.len(), - flags, - core::ptr::addr_of_mut!(storage) as *mut _, - &mut addrlen, - ) - })?; - Ok((n as usize, sockaddr_to_addr(&storage, addrlen as usize)?)) - } - - pub fn recv_from(&self, buf: &mut [u8]) -> io::Result<(usize, SocketAddr)> { - self.recv_from_with_flags(buf, 0) - } - - pub fn peek_from(&self, buf: &mut [u8]) -> io::Result<(usize, SocketAddr)> { - self.recv_from_with_flags(buf, netc::MSG_PEEK) - } - - pub fn write(&self, buf: &[u8]) -> io::Result { - let sz = cvt(unsafe { netc::write(self.0.as_raw_fd(), buf.as_ptr(), buf.len()) })?; - Ok(sz.try_into().unwrap()) - } - - pub fn write_vectored(&self, bufs: &[IoSlice<'_>]) -> io::Result { - crate::io::default_write_vectored(|b| self.write(b), bufs) - } - - pub fn is_write_vectored(&self) -> bool { - false - } - - pub fn set_timeout(&self, dur: Option, kind: i32) -> io::Result<()> { - let timeout = match dur { - Some(dur) => { - if dur.as_secs() == 0 && dur.subsec_nanos() == 0 { - return Err(io::Error::ZERO_TIMEOUT); - } - - let secs = if dur.as_secs() > netc::time_t::MAX as u64 { - netc::time_t::MAX - } else { - dur.as_secs() as netc::time_t - }; - let mut timeout = netc::timeval { - tv_sec: secs, - tv_usec: dur.subsec_micros() as netc::suseconds_t, - }; - if timeout.tv_sec == 0 && timeout.tv_usec == 0 { - timeout.tv_usec = 1; - } - timeout - } - None => netc::timeval { tv_sec: 0, tv_usec: 0 }, - }; - - setsockopt(self, netc::SOL_SOCKET, kind, timeout) - } - - pub fn timeout(&self, kind: i32) -> io::Result> { - let raw: netc::timeval = getsockopt(self, netc::SOL_SOCKET, kind)?; - if raw.tv_sec == 0 && raw.tv_usec == 0 { - Ok(None) - } else { - let sec = raw.tv_sec as u64; - let nsec = (raw.tv_usec as u32) * 1000; - Ok(Some(Duration::new(sec, nsec))) - } - } - - pub fn shutdown(&self, how: Shutdown) -> io::Result<()> { - let how = match how { - Shutdown::Write => netc::SHUT_WR, - Shutdown::Read => netc::SHUT_RD, - Shutdown::Both => netc::SHUT_RDWR, - }; - cvt(unsafe { netc::shutdown_socket(self.as_raw_fd(), how) })?; - Ok(()) - } - - pub fn set_linger(&self, linger: Option) -> io::Result<()> { - let linger = netc::linger { - l_onoff: linger.is_some() as i32, - l_linger: linger.unwrap_or_default().as_secs() as libc::c_int, - }; - - setsockopt(self, netc::SOL_SOCKET, netc::SO_LINGER, linger) - } - - pub fn linger(&self) -> io::Result> { - let val: netc::linger = getsockopt(self, netc::SOL_SOCKET, netc::SO_LINGER)?; - - Ok((val.l_onoff != 0).then(|| Duration::from_secs(val.l_linger as u64))) - } - - pub fn set_nodelay(&self, nodelay: bool) -> io::Result<()> { - let value: i32 = if nodelay { 1 } else { 0 }; - setsockopt(self, netc::IPPROTO_TCP, netc::TCP_NODELAY, value) - } - - pub fn nodelay(&self) -> io::Result { - let raw: i32 = getsockopt(self, netc::IPPROTO_TCP, netc::TCP_NODELAY)?; - Ok(raw != 0) - } - - pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> { - let mut nonblocking: i32 = if nonblocking { 1 } else { 0 }; - cvt(unsafe { - netc::ioctl( - self.as_raw_fd(), - netc::FIONBIO, - core::ptr::addr_of_mut!(nonblocking) as *mut core::ffi::c_void, - ) - }) - .map(drop) - } - - pub fn take_error(&self) -> io::Result> { - unimplemented!() - } - - // This is used by sys_common code to abstract over Windows and Unix. - pub fn as_raw(&self) -> RawFd { - self.0.as_raw_fd() - } -} - -impl AsInner for Socket { - #[inline] - fn as_inner(&self) -> &FileDesc { - &self.0 - } -} - -impl IntoInner for Socket { - fn into_inner(self) -> FileDesc { - self.0 - } -} - -impl FromInner for Socket { - fn from_inner(file_desc: FileDesc) -> Self { - Self(file_desc) - } -} - -impl AsFd for Socket { - fn as_fd(&self) -> BorrowedFd<'_> { - self.0.as_fd() - } -} - -impl AsRawFd for Socket { - #[inline] - fn as_raw_fd(&self) -> RawFd { - self.0.as_raw_fd() - } -} diff --git a/library/std/src/sys/pal/hermit/os.rs b/library/std/src/sys/pal/hermit/os.rs deleted file mode 100644 index cc6781238319b..0000000000000 --- a/library/std/src/sys/pal/hermit/os.rs +++ /dev/null @@ -1,206 +0,0 @@ -use super::hermit_abi; -use crate::collections::HashMap; -use crate::error::Error as StdError; -use crate::ffi::{CStr, OsStr, OsString}; -use crate::fmt; -use crate::io; -use crate::marker::PhantomData; -use crate::os::hermit::ffi::OsStringExt; -use crate::path::{self, PathBuf}; -use crate::str; -use crate::sync::Mutex; -use crate::sys::unsupported; -use crate::vec; -use core::slice::memchr; - -pub fn errno() -> i32 { - unsafe { hermit_abi::get_errno() } -} - -pub fn error_string(errno: i32) -> String { - hermit_abi::error_string(errno).to_string() -} - -pub fn getcwd() -> io::Result { - Ok(PathBuf::from("/")) -} - -pub fn chdir(_: &path::Path) -> io::Result<()> { - unsupported() -} - -pub struct SplitPaths<'a>(!, PhantomData<&'a ()>); - -pub fn split_paths(_unparsed: &OsStr) -> SplitPaths<'_> { - panic!("unsupported") -} - -impl<'a> Iterator for SplitPaths<'a> { - type Item = PathBuf; - fn next(&mut self) -> Option { - self.0 - } -} - -#[derive(Debug)] -pub struct JoinPathsError; - -pub fn join_paths(_paths: I) -> Result -where - I: Iterator, - T: AsRef, -{ - Err(JoinPathsError) -} - -impl fmt::Display for JoinPathsError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - "not supported on hermit yet".fmt(f) - } -} - -impl StdError for JoinPathsError { - #[allow(deprecated)] - fn description(&self) -> &str { - "not supported on hermit yet" - } -} - -pub fn current_exe() -> io::Result { - unsupported() -} - -static mut ENV: Option>> = None; - -pub fn init_environment(env: *const *const i8) { - unsafe { - ENV = Some(Mutex::new(HashMap::new())); - - if env.is_null() { - return; - } - - let mut guard = ENV.as_ref().unwrap().lock().unwrap(); - let mut environ = env; - while !(*environ).is_null() { - if let Some((key, value)) = parse(CStr::from_ptr(*environ).to_bytes()) { - guard.insert(key, value); - } - environ = environ.add(1); - } - } - - fn parse(input: &[u8]) -> Option<(OsString, OsString)> { - // Strategy (copied from glibc): Variable name and value are separated - // by an ASCII equals sign '='. Since a variable name must not be - // empty, allow variable names starting with an equals sign. Skip all - // malformed lines. - if input.is_empty() { - return None; - } - let pos = memchr::memchr(b'=', &input[1..]).map(|p| p + 1); - pos.map(|p| { - ( - OsStringExt::from_vec(input[..p].to_vec()), - OsStringExt::from_vec(input[p + 1..].to_vec()), - ) - }) - } -} - -pub struct Env { - iter: vec::IntoIter<(OsString, OsString)>, -} - -// FIXME(https://github.com/rust-lang/rust/issues/114583): Remove this when ::fmt matches ::fmt. -pub struct EnvStrDebug<'a> { - slice: &'a [(OsString, OsString)], -} - -impl fmt::Debug for EnvStrDebug<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let Self { slice } = self; - f.debug_list() - .entries(slice.iter().map(|(a, b)| (a.to_str().unwrap(), b.to_str().unwrap()))) - .finish() - } -} - -impl Env { - pub fn str_debug(&self) -> impl fmt::Debug + '_ { - let Self { iter } = self; - EnvStrDebug { slice: iter.as_slice() } - } -} - -impl fmt::Debug for Env { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let Self { iter } = self; - f.debug_list().entries(iter.as_slice()).finish() - } -} - -impl !Send for Env {} -impl !Sync for Env {} - -impl Iterator for Env { - type Item = (OsString, OsString); - fn next(&mut self) -> Option<(OsString, OsString)> { - self.iter.next() - } - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } -} - -/// Returns a vector of (variable, value) byte-vector pairs for all the -/// environment variables of the current process. -pub fn env() -> Env { - unsafe { - let guard = ENV.as_ref().unwrap().lock().unwrap(); - let mut result = Vec::new(); - - for (key, value) in guard.iter() { - result.push((key.clone(), value.clone())); - } - - return Env { iter: result.into_iter() }; - } -} - -pub fn getenv(k: &OsStr) -> Option { - unsafe { ENV.as_ref().unwrap().lock().unwrap().get_mut(k).cloned() } -} - -pub fn setenv(k: &OsStr, v: &OsStr) -> io::Result<()> { - unsafe { - let (k, v) = (k.to_owned(), v.to_owned()); - ENV.as_ref().unwrap().lock().unwrap().insert(k, v); - } - Ok(()) -} - -pub fn unsetenv(k: &OsStr) -> io::Result<()> { - unsafe { - ENV.as_ref().unwrap().lock().unwrap().remove(k); - } - Ok(()) -} - -pub fn temp_dir() -> PathBuf { - PathBuf::from("/tmp") -} - -pub fn home_dir() -> Option { - None -} - -pub fn exit(code: i32) -> ! { - unsafe { - hermit_abi::exit(code); - } -} - -pub fn getpid() -> u32 { - unsafe { hermit_abi::getpid() } -} diff --git a/library/std/src/sys/pal/hermit/stdio.rs b/library/std/src/sys/pal/hermit/stdio.rs deleted file mode 100644 index 777c57b391c89..0000000000000 --- a/library/std/src/sys/pal/hermit/stdio.rs +++ /dev/null @@ -1,120 +0,0 @@ -use super::hermit_abi; -use crate::io; -use crate::io::{IoSlice, IoSliceMut}; - -pub struct Stdin; -pub struct Stdout; -pub struct Stderr; - -impl Stdin { - pub const fn new() -> Stdin { - Stdin - } -} - -impl io::Read for Stdin { - fn read(&mut self, data: &mut [u8]) -> io::Result { - self.read_vectored(&mut [IoSliceMut::new(data)]) - } - - fn read_vectored(&mut self, _data: &mut [IoSliceMut<'_>]) -> io::Result { - Ok(0) - } - - #[inline] - fn is_read_vectored(&self) -> bool { - true - } -} - -impl Stdout { - pub const fn new() -> Stdout { - Stdout - } -} - -impl io::Write for Stdout { - fn write(&mut self, data: &[u8]) -> io::Result { - let len; - - unsafe { len = hermit_abi::write(1, data.as_ptr() as *const u8, data.len()) } - - if len < 0 { - Err(io::const_io_error!(io::ErrorKind::Uncategorized, "Stdout is not able to print")) - } else { - Ok(len as usize) - } - } - - fn write_vectored(&mut self, data: &[IoSlice<'_>]) -> io::Result { - let len; - - unsafe { len = hermit_abi::write(1, data.as_ptr() as *const u8, data.len()) } - - if len < 0 { - Err(io::const_io_error!(io::ErrorKind::Uncategorized, "Stdout is not able to print")) - } else { - Ok(len as usize) - } - } - - #[inline] - fn is_write_vectored(&self) -> bool { - true - } - - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -impl Stderr { - pub const fn new() -> Stderr { - Stderr - } -} - -impl io::Write for Stderr { - fn write(&mut self, data: &[u8]) -> io::Result { - let len; - - unsafe { len = hermit_abi::write(2, data.as_ptr() as *const u8, data.len()) } - - if len < 0 { - Err(io::const_io_error!(io::ErrorKind::Uncategorized, "Stderr is not able to print")) - } else { - Ok(len as usize) - } - } - - fn write_vectored(&mut self, data: &[IoSlice<'_>]) -> io::Result { - let len; - - unsafe { len = hermit_abi::write(2, data.as_ptr() as *const u8, data.len()) } - - if len < 0 { - Err(io::const_io_error!(io::ErrorKind::Uncategorized, "Stderr is not able to print")) - } else { - Ok(len as usize) - } - } - - #[inline] - fn is_write_vectored(&self) -> bool { - true - } - - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -pub const STDIN_BUF_SIZE: usize = 0; - -pub fn is_ebadf(_err: &io::Error) -> bool { - true -} - -pub fn panic_output() -> Option { - Some(Stderr::new()) -} diff --git a/library/std/src/sys/pal/hermit/thread.rs b/library/std/src/sys/pal/hermit/thread.rs deleted file mode 100644 index b336dcd6860e4..0000000000000 --- a/library/std/src/sys/pal/hermit/thread.rs +++ /dev/null @@ -1,102 +0,0 @@ -#![allow(dead_code)] - -use super::hermit_abi; -use super::thread_local_dtor::run_dtors; -use crate::ffi::CStr; -use crate::io; -use crate::mem; -use crate::num::NonZero; -use crate::ptr; -use crate::time::Duration; - -pub type Tid = hermit_abi::Tid; - -pub struct Thread { - tid: Tid, -} - -unsafe impl Send for Thread {} -unsafe impl Sync for Thread {} - -pub const DEFAULT_MIN_STACK_SIZE: usize = 1 << 20; - -impl Thread { - pub unsafe fn new_with_coreid( - stack: usize, - p: Box, - core_id: isize, - ) -> io::Result { - let p = Box::into_raw(Box::new(p)); - let tid = hermit_abi::spawn2( - thread_start, - p.expose_provenance(), - hermit_abi::Priority::into(hermit_abi::NORMAL_PRIO), - stack, - core_id, - ); - - return if tid == 0 { - // The thread failed to start and as a result p was not consumed. Therefore, it is - // safe to reconstruct the box so that it gets deallocated. - drop(Box::from_raw(p)); - Err(io::const_io_error!(io::ErrorKind::Uncategorized, "Unable to create thread!")) - } else { - Ok(Thread { tid: tid }) - }; - - extern "C" fn thread_start(main: usize) { - unsafe { - // Finally, let's run some code. - Box::from_raw(ptr::with_exposed_provenance::>(main).cast_mut())(); - - // run all destructors - run_dtors(); - } - } - } - - pub unsafe fn new(stack: usize, p: Box) -> io::Result { - Thread::new_with_coreid(stack, p, -1 /* = no specific core */) - } - - #[inline] - pub fn yield_now() { - unsafe { - hermit_abi::yield_now(); - } - } - - #[inline] - pub fn set_name(_name: &CStr) { - // nope - } - - #[inline] - pub fn sleep(dur: Duration) { - unsafe { - hermit_abi::usleep(dur.as_micros() as u64); - } - } - - pub fn join(self) { - unsafe { - let _ = hermit_abi::join(self.tid); - } - } - - #[inline] - pub fn id(&self) -> Tid { - self.tid - } - - #[inline] - pub fn into_id(self) -> Tid { - let id = self.tid; - mem::forget(self); - id - } -} - -pub fn available_parallelism() -> io::Result> { - unsafe { Ok(NonZero::new_unchecked(hermit_abi::get_processor_count())) } -} diff --git a/library/std/src/sys/pal/hermit/thread_local_dtor.rs b/library/std/src/sys/pal/hermit/thread_local_dtor.rs deleted file mode 100644 index 98adaf4bff1aa..0000000000000 --- a/library/std/src/sys/pal/hermit/thread_local_dtor.rs +++ /dev/null @@ -1,29 +0,0 @@ -#![cfg(target_thread_local)] -#![unstable(feature = "thread_local_internals", issue = "none")] - -// Simplify dtor registration by using a list of destructors. -// The this solution works like the implementation of macOS and -// doesn't additional OS support - -use crate::cell::RefCell; - -#[thread_local] -static DTORS: RefCell> = RefCell::new(Vec::new()); - -pub unsafe fn register_dtor(t: *mut u8, dtor: unsafe extern "C" fn(*mut u8)) { - match DTORS.try_borrow_mut() { - Ok(mut dtors) => dtors.push((t, dtor)), - Err(_) => rtabort!("global allocator may not use TLS"), - } -} - -// every thread call this function to run through all possible destructors -pub unsafe fn run_dtors() { - let mut list = DTORS.take(); - while !list.is_empty() { - for (ptr, dtor) in list { - dtor(ptr); - } - list = DTORS.take(); - } -} diff --git a/library/std/src/sys/pal/hermit/time.rs b/library/std/src/sys/pal/hermit/time.rs deleted file mode 100644 index 2bf24462fa825..0000000000000 --- a/library/std/src/sys/pal/hermit/time.rs +++ /dev/null @@ -1,226 +0,0 @@ -#![allow(dead_code)] - -use super::hermit_abi::{self, timespec, CLOCK_MONOTONIC, CLOCK_REALTIME, NSEC_PER_SEC}; -use crate::cmp::Ordering; -use crate::ops::{Add, AddAssign, Sub, SubAssign}; -use crate::time::Duration; -use core::hash::{Hash, Hasher}; - -#[derive(Copy, Clone, Debug)] -struct Timespec { - t: timespec, -} - -impl Timespec { - const fn zero() -> Timespec { - Timespec { t: timespec { tv_sec: 0, tv_nsec: 0 } } - } - - const fn new(tv_sec: i64, tv_nsec: i64) -> Timespec { - assert!(tv_nsec >= 0 && tv_nsec < NSEC_PER_SEC as i64); - // SAFETY: The assert above checks tv_nsec is within the valid range - Timespec { t: timespec { tv_sec: tv_sec, tv_nsec: tv_nsec } } - } - - fn sub_timespec(&self, other: &Timespec) -> Result { - if self >= other { - Ok(if self.t.tv_nsec >= other.t.tv_nsec { - Duration::new( - (self.t.tv_sec - other.t.tv_sec) as u64, - (self.t.tv_nsec - other.t.tv_nsec) as u32, - ) - } else { - Duration::new( - (self.t.tv_sec - 1 - other.t.tv_sec) as u64, - self.t.tv_nsec as u32 + (NSEC_PER_SEC as u32) - other.t.tv_nsec as u32, - ) - }) - } else { - match other.sub_timespec(self) { - Ok(d) => Err(d), - Err(d) => Ok(d), - } - } - } - - fn checked_add_duration(&self, other: &Duration) -> Option { - let mut secs = self.t.tv_sec.checked_add_unsigned(other.as_secs())?; - - // Nano calculations can't overflow because nanos are <1B which fit - // in a u32. - let mut nsec = other.subsec_nanos() + self.t.tv_nsec as u32; - if nsec >= NSEC_PER_SEC as u32 { - nsec -= NSEC_PER_SEC as u32; - secs = secs.checked_add(1)?; - } - Some(Timespec { t: timespec { tv_sec: secs, tv_nsec: nsec as _ } }) - } - - fn checked_sub_duration(&self, other: &Duration) -> Option { - let mut secs = self.t.tv_sec.checked_sub_unsigned(other.as_secs())?; - - // Similar to above, nanos can't overflow. - let mut nsec = self.t.tv_nsec as i32 - other.subsec_nanos() as i32; - if nsec < 0 { - nsec += NSEC_PER_SEC as i32; - secs = secs.checked_sub(1)?; - } - Some(Timespec { t: timespec { tv_sec: secs, tv_nsec: nsec as _ } }) - } -} - -impl PartialEq for Timespec { - fn eq(&self, other: &Timespec) -> bool { - self.t.tv_sec == other.t.tv_sec && self.t.tv_nsec == other.t.tv_nsec - } -} - -impl Eq for Timespec {} - -impl PartialOrd for Timespec { - fn partial_cmp(&self, other: &Timespec) -> Option { - Some(self.cmp(other)) - } -} - -impl Ord for Timespec { - fn cmp(&self, other: &Timespec) -> Ordering { - let me = (self.t.tv_sec, self.t.tv_nsec); - let other = (other.t.tv_sec, other.t.tv_nsec); - me.cmp(&other) - } -} - -impl Hash for Timespec { - fn hash(&self, state: &mut H) { - self.t.tv_sec.hash(state); - self.t.tv_nsec.hash(state); - } -} - -#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)] -pub struct Instant(Timespec); - -impl Instant { - pub fn now() -> Instant { - let mut time: Timespec = Timespec::zero(); - let _ = - unsafe { hermit_abi::clock_gettime(CLOCK_MONOTONIC, core::ptr::addr_of_mut!(time.t)) }; - - Instant(time) - } - - #[stable(feature = "time2", since = "1.8.0")] - pub fn elapsed(&self) -> Duration { - Instant::now() - *self - } - - pub fn duration_since(&self, earlier: Instant) -> Duration { - self.checked_duration_since(earlier).unwrap_or_default() - } - - pub fn checked_duration_since(&self, earlier: Instant) -> Option { - self.checked_sub_instant(&earlier) - } - - pub fn checked_sub_instant(&self, other: &Instant) -> Option { - self.0.sub_timespec(&other.0).ok() - } - - pub fn checked_add_duration(&self, other: &Duration) -> Option { - Some(Instant(self.0.checked_add_duration(other)?)) - } - - pub fn checked_sub_duration(&self, other: &Duration) -> Option { - Some(Instant(self.0.checked_sub_duration(other)?)) - } - - pub fn checked_add(&self, duration: Duration) -> Option { - self.0.checked_add_duration(&duration).map(Instant) - } - - pub fn checked_sub(&self, duration: Duration) -> Option { - self.0.checked_sub_duration(&duration).map(Instant) - } -} - -impl Add for Instant { - type Output = Instant; - - /// # Panics - /// - /// This function may panic if the resulting point in time cannot be represented by the - /// underlying data structure. See [`Instant::checked_add`] for a version without panic. - fn add(self, other: Duration) -> Instant { - self.checked_add(other).expect("overflow when adding duration to instant") - } -} - -impl AddAssign for Instant { - fn add_assign(&mut self, other: Duration) { - *self = *self + other; - } -} - -impl Sub for Instant { - type Output = Instant; - - fn sub(self, other: Duration) -> Instant { - self.checked_sub(other).expect("overflow when subtracting duration from instant") - } -} - -impl SubAssign for Instant { - fn sub_assign(&mut self, other: Duration) { - *self = *self - other; - } -} - -impl Sub for Instant { - type Output = Duration; - - /// Returns the amount of time elapsed from another instant to this one, - /// or zero duration if that instant is later than this one. - /// - /// # Panics - /// - /// Previous Rust versions panicked when `other` was later than `self`. Currently this - /// method saturates. Future versions may reintroduce the panic in some circumstances. - /// See [Monotonicity]. - /// - /// [Monotonicity]: Instant#monotonicity - fn sub(self, other: Instant) -> Duration { - self.duration_since(other) - } -} - -#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash, Debug)] -pub struct SystemTime(Timespec); - -pub const UNIX_EPOCH: SystemTime = SystemTime(Timespec::zero()); - -impl SystemTime { - pub fn new(tv_sec: i64, tv_nsec: i64) -> SystemTime { - SystemTime(Timespec::new(tv_sec, tv_nsec)) - } - - pub fn now() -> SystemTime { - let mut time: Timespec = Timespec::zero(); - let _ = - unsafe { hermit_abi::clock_gettime(CLOCK_REALTIME, core::ptr::addr_of_mut!(time.t)) }; - - SystemTime(time) - } - - pub fn sub_time(&self, other: &SystemTime) -> Result { - self.0.sub_timespec(&other.0) - } - - pub fn checked_add_duration(&self, other: &Duration) -> Option { - Some(SystemTime(self.0.checked_add_duration(other)?)) - } - - pub fn checked_sub_duration(&self, other: &Duration) -> Option { - Some(SystemTime(self.0.checked_sub_duration(other)?)) - } -} diff --git a/library/std/src/sys/pal/itron/abi.rs b/library/std/src/sys/pal/itron/abi.rs deleted file mode 100644 index 5eb14bb7e534b..0000000000000 --- a/library/std/src/sys/pal/itron/abi.rs +++ /dev/null @@ -1,197 +0,0 @@ -//! ABI for μITRON derivatives -pub type int_t = crate::os::raw::c_int; -pub type uint_t = crate::os::raw::c_uint; -pub type bool_t = int_t; - -/// Kernel object ID -pub type ID = int_t; - -/// The current task. -pub const TSK_SELF: ID = 0; - -/// Relative time -pub type RELTIM = u32; - -/// Timeout (a valid `RELTIM` value or `TMO_FEVR`) -pub type TMO = u32; - -/// The infinite timeout value -pub const TMO_FEVR: TMO = TMO::MAX; - -/// The maximum valid value of `RELTIM` -pub const TMAX_RELTIM: RELTIM = 4_000_000_000; - -/// System time -pub type SYSTIM = u64; - -/// Error code type -pub type ER = int_t; - -/// Error code type, `ID` on success -pub type ER_ID = int_t; - -/// Service call operational mode -pub type MODE = uint_t; - -/// OR waiting condition for an eventflag -pub const TWF_ORW: MODE = 0x01; - -/// Object attributes -pub type ATR = uint_t; - -/// FIFO wait order -pub const TA_FIFO: ATR = 0; -/// Only one task is allowed to be in the waiting state for the eventflag -pub const TA_WSGL: ATR = 0; -/// The eventflag’s bit pattern is cleared when a task is released from the -/// waiting state for that eventflag. -pub const TA_CLR: ATR = 0x04; - -/// Bit pattern of an eventflag -pub type FLGPTN = uint_t; - -/// Task or interrupt priority -pub type PRI = int_t; - -/// The special value of `PRI` representing the current task's priority. -pub const TPRI_SELF: PRI = 0; - -/// Use the priority inheritance protocol -#[cfg(target_os = "solid_asp3")] -pub const TA_INHERIT: ATR = 0x02; - -/// Activate the task on creation -pub const TA_ACT: ATR = 0x01; - -/// The maximum count of a semaphore -pub const TMAX_MAXSEM: uint_t = uint_t::MAX; - -/// Callback parameter -pub type EXINF = isize; - -/// Task entrypoint -pub type TASK = Option; - -// Error codes -pub const E_OK: ER = 0; -pub const E_SYS: ER = -5; -pub const E_NOSPT: ER = -9; -pub const E_RSFN: ER = -10; -pub const E_RSATR: ER = -11; -pub const E_PAR: ER = -17; -pub const E_ID: ER = -18; -pub const E_CTX: ER = -25; -pub const E_MACV: ER = -26; -pub const E_OACV: ER = -27; -pub const E_ILUSE: ER = -28; -pub const E_NOMEM: ER = -33; -pub const E_NOID: ER = -34; -pub const E_NORES: ER = -35; -pub const E_OBJ: ER = -41; -pub const E_NOEXS: ER = -42; -pub const E_QOVR: ER = -43; -pub const E_RLWAI: ER = -49; -pub const E_TMOUT: ER = -50; -pub const E_DLT: ER = -51; -pub const E_CLS: ER = -52; -pub const E_RASTER: ER = -53; -pub const E_WBLK: ER = -57; -pub const E_BOVR: ER = -58; -pub const E_COMM: ER = -65; - -#[derive(Clone, Copy)] -#[repr(C)] -pub struct T_CSEM { - pub sematr: ATR, - pub isemcnt: uint_t, - pub maxsem: uint_t, -} - -#[derive(Clone, Copy)] -#[repr(C)] -pub struct T_CFLG { - pub flgatr: ATR, - pub iflgptn: FLGPTN, -} - -#[derive(Clone, Copy)] -#[repr(C)] -pub struct T_CMTX { - pub mtxatr: ATR, - pub ceilpri: PRI, -} - -#[derive(Clone, Copy)] -#[repr(C)] -pub struct T_CTSK { - pub tskatr: ATR, - pub exinf: EXINF, - pub task: TASK, - pub itskpri: PRI, - pub stksz: usize, - pub stk: *mut u8, -} - -extern "C" { - #[link_name = "__asp3_acre_tsk"] - pub fn acre_tsk(pk_ctsk: *const T_CTSK) -> ER_ID; - #[link_name = "__asp3_get_tid"] - pub fn get_tid(p_tskid: *mut ID) -> ER; - #[link_name = "__asp3_dly_tsk"] - pub fn dly_tsk(dlytim: RELTIM) -> ER; - #[link_name = "__asp3_ter_tsk"] - pub fn ter_tsk(tskid: ID) -> ER; - #[link_name = "__asp3_del_tsk"] - pub fn del_tsk(tskid: ID) -> ER; - #[link_name = "__asp3_get_pri"] - pub fn get_pri(tskid: ID, p_tskpri: *mut PRI) -> ER; - #[link_name = "__asp3_rot_rdq"] - pub fn rot_rdq(tskpri: PRI) -> ER; - #[link_name = "__asp3_slp_tsk"] - pub fn slp_tsk() -> ER; - #[link_name = "__asp3_tslp_tsk"] - pub fn tslp_tsk(tmout: TMO) -> ER; - #[link_name = "__asp3_wup_tsk"] - pub fn wup_tsk(tskid: ID) -> ER; - #[link_name = "__asp3_unl_cpu"] - pub fn unl_cpu() -> ER; - #[link_name = "__asp3_dis_dsp"] - pub fn dis_dsp() -> ER; - #[link_name = "__asp3_ena_dsp"] - pub fn ena_dsp() -> ER; - #[link_name = "__asp3_sns_dsp"] - pub fn sns_dsp() -> bool_t; - #[link_name = "__asp3_get_tim"] - pub fn get_tim(p_systim: *mut SYSTIM) -> ER; - #[link_name = "__asp3_acre_flg"] - pub fn acre_flg(pk_cflg: *const T_CFLG) -> ER_ID; - #[link_name = "__asp3_del_flg"] - pub fn del_flg(flgid: ID) -> ER; - #[link_name = "__asp3_set_flg"] - pub fn set_flg(flgid: ID, setptn: FLGPTN) -> ER; - #[link_name = "__asp3_clr_flg"] - pub fn clr_flg(flgid: ID, clrptn: FLGPTN) -> ER; - #[link_name = "__asp3_wai_flg"] - pub fn wai_flg(flgid: ID, waiptn: FLGPTN, wfmode: MODE, p_flgptn: *mut FLGPTN) -> ER; - #[link_name = "__asp3_twai_flg"] - pub fn twai_flg( - flgid: ID, - waiptn: FLGPTN, - wfmode: MODE, - p_flgptn: *mut FLGPTN, - tmout: TMO, - ) -> ER; - #[link_name = "__asp3_acre_mtx"] - pub fn acre_mtx(pk_cmtx: *const T_CMTX) -> ER_ID; - #[link_name = "__asp3_del_mtx"] - pub fn del_mtx(tskid: ID) -> ER; - #[link_name = "__asp3_loc_mtx"] - pub fn loc_mtx(mtxid: ID) -> ER; - #[link_name = "__asp3_ploc_mtx"] - pub fn ploc_mtx(mtxid: ID) -> ER; - #[link_name = "__asp3_tloc_mtx"] - pub fn tloc_mtx(mtxid: ID, tmout: TMO) -> ER; - #[link_name = "__asp3_unl_mtx"] - pub fn unl_mtx(mtxid: ID) -> ER; - pub fn exd_tsk() -> ER; -} diff --git a/library/std/src/sys/pal/itron/error.rs b/library/std/src/sys/pal/itron/error.rs deleted file mode 100644 index fbc822d4eb6e1..0000000000000 --- a/library/std/src/sys/pal/itron/error.rs +++ /dev/null @@ -1,164 +0,0 @@ -use crate::{fmt, io::ErrorKind}; - -use super::abi; - -/// Wraps a μITRON error code. -#[derive(Debug, Copy, Clone)] -pub struct ItronError { - er: abi::ER, -} - -impl ItronError { - /// Construct `ItronError` from the specified error code. Returns `None` if the - /// error code does not represent a failure or warning. - #[inline] - pub fn new(er: abi::ER) -> Option { - if er < 0 { Some(Self { er }) } else { None } - } - - /// Returns `Ok(er)` if `er` represents a success or `Err(_)` otherwise. - #[inline] - pub fn err_if_negative(er: abi::ER) -> Result { - if let Some(error) = Self::new(er) { Err(error) } else { Ok(er) } - } - - /// Get the raw error code. - #[inline] - pub fn as_raw(&self) -> abi::ER { - self.er - } -} - -impl fmt::Display for ItronError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - // Allow the platforms to extend `error_name` - if let Some(name) = crate::sys::error::error_name(self.er) { - write!(f, "{} ({})", name, self.er) - } else { - write!(f, "{}", self.er) - } - } -} - -/// Describe the specified μITRON error code. Returns `None` if it's an -/// undefined error code. -pub fn error_name(er: abi::ER) -> Option<&'static str> { - match er { - // Success - er if er >= 0 => None, - - // μITRON 4.0 - abi::E_SYS => Some("system error"), - abi::E_NOSPT => Some("unsupported function"), - abi::E_RSFN => Some("reserved function code"), - abi::E_RSATR => Some("reserved attribute"), - abi::E_PAR => Some("parameter error"), - abi::E_ID => Some("invalid ID number"), - abi::E_CTX => Some("context error"), - abi::E_MACV => Some("memory access violation"), - abi::E_OACV => Some("object access violation"), - abi::E_ILUSE => Some("illegal service call use"), - abi::E_NOMEM => Some("insufficient memory"), - abi::E_NOID => Some("no ID number available"), - abi::E_OBJ => Some("object state error"), - abi::E_NOEXS => Some("non-existent object"), - abi::E_QOVR => Some("queue overflow"), - abi::E_RLWAI => Some("forced release from waiting"), - abi::E_TMOUT => Some("polling failure or timeout"), - abi::E_DLT => Some("waiting object deleted"), - abi::E_CLS => Some("waiting object state changed"), - abi::E_WBLK => Some("non-blocking code accepted"), - abi::E_BOVR => Some("buffer overflow"), - - // The TOPPERS third generation kernels - abi::E_NORES => Some("insufficient system resources"), - abi::E_RASTER => Some("termination request raised"), - abi::E_COMM => Some("communication failure"), - - _ => None, - } -} - -#[inline] -pub fn is_interrupted(er: abi::ER) -> bool { - er == abi::E_RLWAI -} - -pub fn decode_error_kind(er: abi::ER) -> ErrorKind { - match er { - // Success - er if er >= 0 => ErrorKind::Uncategorized, - - // μITRON 4.0 - // abi::E_SYS - abi::E_NOSPT => ErrorKind::Unsupported, // Some("unsupported function"), - abi::E_RSFN => ErrorKind::InvalidInput, // Some("reserved function code"), - abi::E_RSATR => ErrorKind::InvalidInput, // Some("reserved attribute"), - abi::E_PAR => ErrorKind::InvalidInput, // Some("parameter error"), - abi::E_ID => ErrorKind::NotFound, // Some("invalid ID number"), - // abi::E_CTX - abi::E_MACV => ErrorKind::PermissionDenied, // Some("memory access violation"), - abi::E_OACV => ErrorKind::PermissionDenied, // Some("object access violation"), - // abi::E_ILUSE - abi::E_NOMEM => ErrorKind::OutOfMemory, // Some("insufficient memory"), - abi::E_NOID => ErrorKind::OutOfMemory, // Some("no ID number available"), - // abi::E_OBJ - abi::E_NOEXS => ErrorKind::NotFound, // Some("non-existent object"), - // abi::E_QOVR - abi::E_RLWAI => ErrorKind::Interrupted, // Some("forced release from waiting"), - abi::E_TMOUT => ErrorKind::TimedOut, // Some("polling failure or timeout"), - // abi::E_DLT - // abi::E_CLS - // abi::E_WBLK - // abi::E_BOVR - - // The TOPPERS third generation kernels - abi::E_NORES => ErrorKind::OutOfMemory, // Some("insufficient system resources"), - // abi::E_RASTER - // abi::E_COMM - _ => ErrorKind::Uncategorized, - } -} - -/// Similar to `ItronError::err_if_negative(er).expect()` except that, while -/// panicking, it prints the message to `panic_output` and aborts the program -/// instead. This ensures the error message is not obscured by double -/// panicking. -/// -/// This is useful for diagnosing creation failures of synchronization -/// primitives that are used by `std`'s internal mechanisms. Such failures -/// are common when the system is mis-configured to provide a too-small pool for -/// kernel objects. -#[inline] -pub fn expect_success(er: abi::ER, msg: &&str) -> abi::ER { - match ItronError::err_if_negative(er) { - Ok(x) => x, - Err(e) => fail(e, msg), - } -} - -/// Similar to `ItronError::err_if_negative(er).expect()` but aborts instead. -/// -/// Use this where panicking is not allowed or the effect of the failure -/// would be persistent. -#[inline] -pub fn expect_success_aborting(er: abi::ER, msg: &&str) -> abi::ER { - match ItronError::err_if_negative(er) { - Ok(x) => x, - Err(e) => fail_aborting(e, msg), - } -} - -#[cold] -pub fn fail(e: impl fmt::Display, msg: &&str) -> ! { - if crate::thread::panicking() { - fail_aborting(e, msg) - } else { - panic!("{} failed: {}", *msg, e) - } -} - -#[cold] -pub fn fail_aborting(e: impl fmt::Display, msg: &&str) -> ! { - rtabort!("{} failed: {}", *msg, e) -} diff --git a/library/std/src/sys/pal/itron/spin.rs b/library/std/src/sys/pal/itron/spin.rs deleted file mode 100644 index 44d409444bca4..0000000000000 --- a/library/std/src/sys/pal/itron/spin.rs +++ /dev/null @@ -1,163 +0,0 @@ -use super::abi; -use crate::{ - cell::UnsafeCell, - mem::MaybeUninit, - sync::atomic::{AtomicBool, AtomicUsize, Ordering}, -}; - -/// A mutex implemented by `dis_dsp` (for intra-core synchronization) and a -/// spinlock (for inter-core synchronization). -pub struct SpinMutex { - locked: AtomicBool, - data: UnsafeCell, -} - -impl SpinMutex { - #[inline] - pub const fn new(x: T) -> Self { - Self { locked: AtomicBool::new(false), data: UnsafeCell::new(x) } - } - - /// Acquire a lock. - #[inline] - pub fn with_locked(&self, f: impl FnOnce(&mut T) -> R) -> R { - struct SpinMutexGuard<'a>(&'a AtomicBool); - - impl Drop for SpinMutexGuard<'_> { - #[inline] - fn drop(&mut self) { - self.0.store(false, Ordering::Release); - unsafe { abi::ena_dsp() }; - } - } - - let _guard; - if unsafe { abi::sns_dsp() } == 0 { - let er = unsafe { abi::dis_dsp() }; - debug_assert!(er >= 0); - - // Wait until the current processor acquires a lock. - while self.locked.swap(true, Ordering::Acquire) {} - - _guard = SpinMutexGuard(&self.locked); - } - - f(unsafe { &mut *self.data.get() }) - } -} - -/// `OnceCell<(abi::ID, T)>` implemented by `dis_dsp` (for intra-core -/// synchronization) and a spinlock (for inter-core synchronization). -/// -/// It's assumed that `0` is not a valid ID, and all kernel -/// object IDs fall into range `1..=usize::MAX`. -pub struct SpinIdOnceCell { - id: AtomicUsize, - spin: SpinMutex<()>, - extra: UnsafeCell>, -} - -const ID_UNINIT: usize = 0; - -impl SpinIdOnceCell { - #[inline] - pub const fn new() -> Self { - Self { - id: AtomicUsize::new(ID_UNINIT), - extra: UnsafeCell::new(MaybeUninit::uninit()), - spin: SpinMutex::new(()), - } - } - - #[inline] - pub fn get(&self) -> Option<(abi::ID, &T)> { - match self.id.load(Ordering::Acquire) { - ID_UNINIT => None, - id => Some((id as abi::ID, unsafe { (&*self.extra.get()).assume_init_ref() })), - } - } - - #[inline] - pub fn get_mut(&mut self) -> Option<(abi::ID, &mut T)> { - match *self.id.get_mut() { - ID_UNINIT => None, - id => Some((id as abi::ID, unsafe { (&mut *self.extra.get()).assume_init_mut() })), - } - } - - #[inline] - pub unsafe fn get_unchecked(&self) -> (abi::ID, &T) { - (self.id.load(Ordering::Acquire) as abi::ID, unsafe { - (&*self.extra.get()).assume_init_ref() - }) - } - - /// Assign the content without checking if it's already initialized or - /// being initialized. - pub unsafe fn set_unchecked(&self, (id, extra): (abi::ID, T)) { - debug_assert!(self.get().is_none()); - - // Assumption: A positive `abi::ID` fits in `usize`. - debug_assert!(id >= 0); - debug_assert!(usize::try_from(id).is_ok()); - let id = id as usize; - - unsafe { *self.extra.get() = MaybeUninit::new(extra) }; - self.id.store(id, Ordering::Release); - } - - /// Gets the contents of the cell, initializing it with `f` if - /// the cell was empty. If the cell was empty and `f` failed, an - /// error is returned. - /// - /// Warning: `f` must not perform a blocking operation, which - /// includes panicking. - #[inline] - pub fn get_or_try_init(&self, f: F) -> Result<(abi::ID, &T), E> - where - F: FnOnce() -> Result<(abi::ID, T), E>, - { - // Fast path - if let Some(x) = self.get() { - return Ok(x); - } - - self.initialize(f)?; - - debug_assert!(self.get().is_some()); - - // Safety: The inner value has been initialized - Ok(unsafe { self.get_unchecked() }) - } - - fn initialize(&self, f: F) -> Result<(), E> - where - F: FnOnce() -> Result<(abi::ID, T), E>, - { - self.spin.with_locked(|_| { - if self.id.load(Ordering::Relaxed) == ID_UNINIT { - let (initialized_id, initialized_extra) = f()?; - - // Assumption: A positive `abi::ID` fits in `usize`. - debug_assert!(initialized_id >= 0); - debug_assert!(usize::try_from(initialized_id).is_ok()); - let initialized_id = initialized_id as usize; - - // Store the initialized contents. Use the release ordering to - // make sure the write is visible to the callers of `get`. - unsafe { *self.extra.get() = MaybeUninit::new(initialized_extra) }; - self.id.store(initialized_id, Ordering::Release); - } - Ok(()) - }) - } -} - -impl Drop for SpinIdOnceCell { - #[inline] - fn drop(&mut self) { - if self.get_mut().is_some() { - unsafe { (&mut *self.extra.get()).assume_init_drop() }; - } - } -} diff --git a/library/std/src/sys/pal/itron/task.rs b/library/std/src/sys/pal/itron/task.rs deleted file mode 100644 index 94beb50a2541b..0000000000000 --- a/library/std/src/sys/pal/itron/task.rs +++ /dev/null @@ -1,44 +0,0 @@ -use super::{ - abi, - error::{fail, fail_aborting, ItronError}, -}; - -use crate::mem::MaybeUninit; - -/// Get the ID of the task in Running state. Panics on failure. -#[inline] -pub fn current_task_id() -> abi::ID { - try_current_task_id().unwrap_or_else(|e| fail(e, &"get_tid")) -} - -/// Get the ID of the task in Running state. Aborts on failure. -#[inline] -pub fn current_task_id_aborting() -> abi::ID { - try_current_task_id().unwrap_or_else(|e| fail_aborting(e, &"get_tid")) -} - -/// Get the ID of the task in Running state. -#[inline] -pub fn try_current_task_id() -> Result { - unsafe { - let mut out = MaybeUninit::uninit(); - ItronError::err_if_negative(abi::get_tid(out.as_mut_ptr()))?; - Ok(out.assume_init()) - } -} - -/// Get the specified task's priority. Panics on failure. -#[inline] -pub fn task_priority(task: abi::ID) -> abi::PRI { - try_task_priority(task).unwrap_or_else(|e| fail(e, &"get_pri")) -} - -/// Get the specified task's priority. -#[inline] -pub fn try_task_priority(task: abi::ID) -> Result { - unsafe { - let mut out = MaybeUninit::uninit(); - ItronError::err_if_negative(abi::get_pri(task, out.as_mut_ptr()))?; - Ok(out.assume_init()) - } -} diff --git a/library/std/src/sys/pal/itron/thread.rs b/library/std/src/sys/pal/itron/thread.rs deleted file mode 100644 index 205226ce1da80..0000000000000 --- a/library/std/src/sys/pal/itron/thread.rs +++ /dev/null @@ -1,359 +0,0 @@ -//! Thread implementation backed by μITRON tasks. Assumes `acre_tsk` and -//! `exd_tsk` are available. -use super::{ - abi, - error::{expect_success, expect_success_aborting, ItronError}, - task, - time::dur2reltims, -}; -use crate::{ - cell::UnsafeCell, - ffi::CStr, - hint, io, - mem::ManuallyDrop, - num::NonZero, - ptr::NonNull, - sync::atomic::{AtomicUsize, Ordering}, - sys::thread_local_dtor::run_dtors, - time::Duration, -}; - -pub struct Thread { - p_inner: NonNull, - - /// The ID of the underlying task. - task: abi::ID, -} - -// Safety: There's nothing in `Thread` that ties it to the original creator. It -// can be dropped by any threads. -unsafe impl Send for Thread {} -// Safety: `Thread` provides no methods that take `&self`. -unsafe impl Sync for Thread {} - -/// State data shared between a parent thread and child thread. It's dropped on -/// a transition to one of the final states. -struct ThreadInner { - /// This field is used on thread creation to pass a closure from - /// `Thread::new` to the created task. - start: UnsafeCell>>, - - /// A state machine. Each transition is annotated with `[...]` in the - /// source code. - /// - /// ```text - /// - ///

: parent, : child, (?): don't-care - /// - /// DETACHED (-1) --------------------> EXITED (?) - /// finish/exd_tsk - /// ^ - /// | - /// |

detach - /// | - /// - /// INIT (0) -----------------------> FINISHED (-1) - /// finish - /// | | - /// |

join/slp_tsk |

join/del_tsk - /// | |

detach/del_tsk - /// v v - /// - /// JOINING JOINED (?) - /// (parent_tid) - /// ^ - /// \ / - /// \ finish/wup_tsk /

slp_tsk-complete/ter_tsk - /// \ / & del_tsk - /// \ / - /// '--> JOIN_FINALIZE ---' - /// (-1) - /// - lifecycle: AtomicUsize, -} - -// Safety: The only `!Sync` field, `ThreadInner::start`, is only touched by -// the task represented by `ThreadInner`. -unsafe impl Sync for ThreadInner {} - -const LIFECYCLE_INIT: usize = 0; -const LIFECYCLE_FINISHED: usize = usize::MAX; -const LIFECYCLE_DETACHED: usize = usize::MAX; -const LIFECYCLE_JOIN_FINALIZE: usize = usize::MAX; -const LIFECYCLE_DETACHED_OR_JOINED: usize = usize::MAX; -const LIFECYCLE_EXITED_OR_FINISHED_OR_JOIN_FINALIZE: usize = usize::MAX; -// there's no single value for `JOINING` - -// 64KiB for 32-bit ISAs, 128KiB for 64-bit ISAs. -pub const DEFAULT_MIN_STACK_SIZE: usize = 0x4000 * crate::mem::size_of::(); - -impl Thread { - /// # Safety - /// - /// See `thread::Builder::spawn_unchecked` for safety requirements. - pub unsafe fn new(stack: usize, p: Box) -> io::Result { - let inner = Box::new(ThreadInner { - start: UnsafeCell::new(ManuallyDrop::new(p)), - lifecycle: AtomicUsize::new(LIFECYCLE_INIT), - }); - - unsafe extern "C" fn trampoline(exinf: isize) { - let p_inner: *mut ThreadInner = crate::ptr::with_exposed_provenance_mut(exinf as usize); - // Safety: `ThreadInner` is alive at this point - let inner = unsafe { &*p_inner }; - - // Safety: Since `trampoline` is called only once for each - // `ThreadInner` and only `trampoline` touches `start`, - // `start` contains contents and is safe to mutably borrow. - let p = unsafe { ManuallyDrop::take(&mut *inner.start.get()) }; - p(); - - // Fix the current thread's state just in case, so that the - // destructors won't abort - // Safety: Not really unsafe - let _ = unsafe { abi::unl_cpu() }; - let _ = unsafe { abi::ena_dsp() }; - - // Run TLS destructors now because they are not - // called automatically for terminated tasks. - unsafe { run_dtors() }; - - let old_lifecycle = inner - .lifecycle - .swap(LIFECYCLE_EXITED_OR_FINISHED_OR_JOIN_FINALIZE, Ordering::AcqRel); - - match old_lifecycle { - LIFECYCLE_DETACHED => { - // [DETACHED → EXITED] - // No one will ever join, so we'll ask the collector task to - // delete the task. - - // In this case, `*p_inner`'s ownership has been moved to - // us, and we are responsible for dropping it. The acquire - // ordering ensures that the swap operation that wrote - // `LIFECYCLE_DETACHED` happens-before `Box::from_raw( - // p_inner)`. - // Safety: See above. - let _ = unsafe { Box::from_raw(p_inner) }; - - // Safety: There are no pinned references to the stack - unsafe { terminate_and_delete_current_task() }; - } - LIFECYCLE_INIT => { - // [INIT → FINISHED] - // The parent hasn't decided whether to join or detach this - // thread yet. Whichever option the parent chooses, - // it'll have to delete this task. - // Since the parent might drop `*inner` as soon as it sees - // `FINISHED`, the release ordering must be used in the - // above `swap` call. - } - parent_tid => { - // Since the parent might drop `*inner` and terminate us as - // soon as it sees `JOIN_FINALIZE`, the release ordering - // must be used in the above `swap` call. - // - // To make the task referred to by `parent_tid` visible, we - // must use the acquire ordering in the above `swap` call. - - // [JOINING → JOIN_FINALIZE] - // Wake up the parent task. - expect_success( - unsafe { - let mut er = abi::wup_tsk(parent_tid as _); - if er == abi::E_QOVR { - // `E_QOVR` indicates there's already - // a parking token - er = abi::E_OK; - } - er - }, - &"wup_tsk", - ); - } - } - } - - // Safety: `Box::into_raw` returns a non-null pointer - let p_inner = unsafe { NonNull::new_unchecked(Box::into_raw(inner)) }; - - let new_task = ItronError::err_if_negative(unsafe { - abi::acre_tsk(&abi::T_CTSK { - // Activate this task immediately - tskatr: abi::TA_ACT, - exinf: p_inner.as_ptr().expose_provenance() as abi::EXINF, - // The entry point - task: Some(trampoline), - // Inherit the calling task's base priority - itskpri: abi::TPRI_SELF, - stksz: stack, - // Let the kernel allocate the stack, - stk: crate::ptr::null_mut(), - }) - }) - .map_err(|e| e.as_io_error())?; - - Ok(Self { p_inner, task: new_task }) - } - - pub fn yield_now() { - expect_success(unsafe { abi::rot_rdq(abi::TPRI_SELF) }, &"rot_rdq"); - } - - pub fn set_name(_name: &CStr) { - // nope - } - - pub fn sleep(dur: Duration) { - for timeout in dur2reltims(dur) { - expect_success(unsafe { abi::dly_tsk(timeout) }, &"dly_tsk"); - } - } - - pub fn join(self) { - // Safety: `ThreadInner` is alive at this point - let inner = unsafe { self.p_inner.as_ref() }; - // Get the current task ID. Panicking here would cause a resource leak, - // so just abort on failure. - let current_task = task::current_task_id_aborting(); - debug_assert!(usize::try_from(current_task).is_ok()); - debug_assert_ne!(current_task as usize, LIFECYCLE_INIT); - debug_assert_ne!(current_task as usize, LIFECYCLE_DETACHED); - - let current_task = current_task as usize; - - match inner.lifecycle.swap(current_task, Ordering::AcqRel) { - LIFECYCLE_INIT => { - // [INIT → JOINING] - // The child task will transition the state to `JOIN_FINALIZE` - // and wake us up. - // - // To make the task referred to by `current_task` visible from - // the child task's point of view, we must use the release - // ordering in the above `swap` call. - loop { - expect_success_aborting(unsafe { abi::slp_tsk() }, &"slp_tsk"); - // To synchronize with the child task's memory accesses to - // `inner` up to the point of the assignment of - // `JOIN_FINALIZE`, `Ordering::Acquire` must be used for the - // `load`. - if inner.lifecycle.load(Ordering::Acquire) == LIFECYCLE_JOIN_FINALIZE { - break; - } - } - - // [JOIN_FINALIZE → JOINED] - } - LIFECYCLE_FINISHED => { - // [FINISHED → JOINED] - // To synchronize with the child task's memory accesses to - // `inner` up to the point of the assignment of `FINISHED`, - // `Ordering::Acquire` must be used for the above `swap` call. - } - _ => unsafe { hint::unreachable_unchecked() }, - } - - // Terminate and delete the task - // Safety: `self.task` still represents a task we own (because this - // method or `detach_inner` is called only once for each - // `Thread`). The task indicated that it's safe to delete by - // entering the `FINISHED` or `JOIN_FINALIZE` state. - unsafe { terminate_and_delete_task(self.task) }; - - // In either case, we are responsible for dropping `inner`. - // Safety: The contents of `*p_inner` will not be accessed hereafter - let _inner = unsafe { Box::from_raw(self.p_inner.as_ptr()) }; - - // Skip the destructor (because it would attempt to detach the thread) - crate::mem::forget(self); - } -} - -impl Drop for Thread { - fn drop(&mut self) { - // Safety: `ThreadInner` is alive at this point - let inner = unsafe { self.p_inner.as_ref() }; - - // Detach the thread. - match inner.lifecycle.swap(LIFECYCLE_DETACHED_OR_JOINED, Ordering::AcqRel) { - LIFECYCLE_INIT => { - // [INIT → DETACHED] - // When the time comes, the child will figure out that no - // one will ever join it. - // The ownership of `*p_inner` is moved to the child thread. - // The release ordering ensures that the above swap operation on - // `lifecycle` happens-before the child thread's - // `Box::from_raw(p_inner)`. - } - LIFECYCLE_FINISHED => { - // [FINISHED → JOINED] - // The task has already decided that we should delete the task. - // To synchronize with the child task's memory accesses to - // `inner` up to the point of the assignment of `FINISHED`, - // the acquire ordering is required for the above `swap` call. - - // Terminate and delete the task - // Safety: `self.task` still represents a task we own (because - // this method or `join_inner` is called only once for - // each `Thread`). The task indicated that it's safe to - // delete by entering the `FINISHED` state. - unsafe { terminate_and_delete_task(self.task) }; - - // Wwe are responsible for dropping `*p_inner`. - // Safety: The contents of `*p_inner` will not be accessed hereafter - let _ = unsafe { Box::from_raw(self.p_inner.as_ptr()) }; - } - _ => unsafe { hint::unreachable_unchecked() }, - } - } -} - -/// Terminate and delete the specified task. -/// -/// This function will abort if `deleted_task` refers to the calling task. -/// -/// It is assumed that the specified task is solely managed by the caller - -/// i.e., other threads must not "resuscitate" the specified task or delete it -/// prematurely while this function is still in progress. It is allowed for the -/// specified task to exit by its own. -/// -/// # Safety -/// -/// The task must be safe to terminate. This is in general not true -/// because there might be pinned references to the task's stack. -unsafe fn terminate_and_delete_task(deleted_task: abi::ID) { - // Terminate the task - // Safety: Upheld by the caller - match unsafe { abi::ter_tsk(deleted_task) } { - // Indicates the task is already dormant, ignore it - abi::E_OBJ => {} - er => { - expect_success_aborting(er, &"ter_tsk"); - } - } - - // Delete the task - // Safety: Upheld by the caller - expect_success_aborting(unsafe { abi::del_tsk(deleted_task) }, &"del_tsk"); -} - -/// Terminate and delete the calling task. -/// -/// Atomicity is not required - i.e., it can be assumed that other threads won't -/// `ter_tsk` the calling task while this function is still in progress. (This -/// property makes it easy to implement this operation on μITRON-derived kernels -/// that don't support `exd_tsk`.) -/// -/// # Safety -/// -/// The task must be safe to terminate. This is in general not true -/// because there might be pinned references to the task's stack. -unsafe fn terminate_and_delete_current_task() -> ! { - expect_success_aborting(unsafe { abi::exd_tsk() }, &"exd_tsk"); - // Safety: `exd_tsk` never returns on success - unsafe { crate::hint::unreachable_unchecked() }; -} - -pub fn available_parallelism() -> io::Result> { - super::unsupported() -} diff --git a/library/std/src/sys/pal/itron/thread_parking.rs b/library/std/src/sys/pal/itron/thread_parking.rs deleted file mode 100644 index fe9934439d152..0000000000000 --- a/library/std/src/sys/pal/itron/thread_parking.rs +++ /dev/null @@ -1,37 +0,0 @@ -use super::abi; -use super::error::expect_success_aborting; -use super::time::with_tmos; -use crate::time::Duration; - -pub type ThreadId = abi::ID; - -pub use super::task::current_task_id_aborting as current; - -pub fn park(_hint: usize) { - match unsafe { abi::slp_tsk() } { - abi::E_OK | abi::E_RLWAI => {} - err => { - expect_success_aborting(err, &"slp_tsk"); - } - } -} - -pub fn park_timeout(dur: Duration, _hint: usize) { - match with_tmos(dur, |tmo| unsafe { abi::tslp_tsk(tmo) }) { - abi::E_OK | abi::E_RLWAI | abi::E_TMOUT => {} - err => { - expect_success_aborting(err, &"tslp_tsk"); - } - } -} - -pub fn unpark(id: ThreadId, _hint: usize) { - match unsafe { abi::wup_tsk(id) } { - // It is allowed to try to wake up a destroyed or unrelated task, so we ignore all - // errors that could result from that situation. - abi::E_OK | abi::E_NOEXS | abi::E_OBJ | abi::E_QOVR => {} - err => { - expect_success_aborting(err, &"wup_tsk"); - } - } -} diff --git a/library/std/src/sys/pal/itron/time.rs b/library/std/src/sys/pal/itron/time.rs deleted file mode 100644 index 427ea0d80e107..0000000000000 --- a/library/std/src/sys/pal/itron/time.rs +++ /dev/null @@ -1,114 +0,0 @@ -use super::{abi, error::expect_success}; -use crate::{mem::MaybeUninit, time::Duration}; - -#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)] -pub struct Instant(abi::SYSTIM); - -impl Instant { - pub fn now() -> Instant { - // Safety: The provided pointer is valid - unsafe { - let mut out = MaybeUninit::uninit(); - expect_success(abi::get_tim(out.as_mut_ptr()), &"get_tim"); - Instant(out.assume_init()) - } - } - - pub fn checked_sub_instant(&self, other: &Instant) -> Option { - self.0.checked_sub(other.0).map(|ticks| { - // `SYSTIM` is measured in microseconds - Duration::from_micros(ticks) - }) - } - - pub fn checked_add_duration(&self, other: &Duration) -> Option { - // `SYSTIM` is measured in microseconds - let ticks = other.as_micros(); - - Some(Instant(self.0.checked_add(ticks.try_into().ok()?)?)) - } - - pub fn checked_sub_duration(&self, other: &Duration) -> Option { - // `SYSTIM` is measured in microseconds - let ticks = other.as_micros(); - - Some(Instant(self.0.checked_sub(ticks.try_into().ok()?)?)) - } -} - -/// Split `Duration` into zero or more `RELTIM`s. -#[inline] -pub fn dur2reltims(dur: Duration) -> impl Iterator { - // `RELTIM` is microseconds - let mut ticks = dur.as_micros(); - - crate::iter::from_fn(move || { - if ticks == 0 { - None - } else if ticks <= abi::TMAX_RELTIM as u128 { - Some(crate::mem::replace(&mut ticks, 0) as abi::RELTIM) - } else { - ticks -= abi::TMAX_RELTIM as u128; - Some(abi::TMAX_RELTIM) - } - }) -} - -/// Split `Duration` into one or more `TMO`s. -#[inline] -fn dur2tmos(dur: Duration) -> impl Iterator { - // `TMO` is microseconds - let mut ticks = dur.as_micros(); - let mut end = false; - - crate::iter::from_fn(move || { - if end { - None - } else if ticks <= abi::TMAX_RELTIM as u128 { - end = true; - Some(crate::mem::replace(&mut ticks, 0) as abi::TMO) - } else { - ticks -= abi::TMAX_RELTIM as u128; - Some(abi::TMAX_RELTIM) - } - }) -} - -/// Split `Duration` into one or more API calls with timeout. -#[inline] -pub fn with_tmos(dur: Duration, mut f: impl FnMut(abi::TMO) -> abi::ER) -> abi::ER { - let mut er = abi::E_TMOUT; - for tmo in dur2tmos(dur) { - er = f(tmo); - if er != abi::E_TMOUT { - break; - } - } - er -} - -/// Split `Duration` into one or more API calls with timeout. This function can -/// handle spurious wakeups. -#[inline] -pub fn with_tmos_strong(dur: Duration, mut f: impl FnMut(abi::TMO) -> abi::ER) -> abi::ER { - // `TMO` and `SYSTIM` are microseconds. - // Clamp at `SYSTIM::MAX` for performance reasons. This shouldn't cause - // a problem in practice. (`u64::MAX` μs ≈ 584942 years) - let ticks = dur.as_micros().min(abi::SYSTIM::MAX as u128) as abi::SYSTIM; - - let start = Instant::now().0; - let mut elapsed = 0; - let mut er = abi::E_TMOUT; - while elapsed <= ticks { - er = f(elapsed.min(abi::TMAX_RELTIM as abi::SYSTIM) as abi::TMO); - if er != abi::E_TMOUT { - break; - } - elapsed = Instant::now().0.wrapping_sub(start); - } - - er -} - -#[cfg(test)] -mod tests; diff --git a/library/std/src/sys/pal/itron/time/tests.rs b/library/std/src/sys/pal/itron/time/tests.rs deleted file mode 100644 index d14035d9da49f..0000000000000 --- a/library/std/src/sys/pal/itron/time/tests.rs +++ /dev/null @@ -1,33 +0,0 @@ -use super::*; - -fn reltim2dur(t: u64) -> Duration { - Duration::from_micros(t) -} - -#[test] -fn test_dur2reltims() { - assert_eq!(dur2reltims(reltim2dur(0)).collect::>(), vec![]); - assert_eq!(dur2reltims(reltim2dur(42)).collect::>(), vec![42]); - assert_eq!( - dur2reltims(reltim2dur(abi::TMAX_RELTIM as u64)).collect::>(), - vec![abi::TMAX_RELTIM] - ); - assert_eq!( - dur2reltims(reltim2dur(abi::TMAX_RELTIM as u64 + 10000)).collect::>(), - vec![abi::TMAX_RELTIM, 10000] - ); -} - -#[test] -fn test_dur2tmos() { - assert_eq!(dur2tmos(reltim2dur(0)).collect::>(), vec![0]); - assert_eq!(dur2tmos(reltim2dur(42)).collect::>(), vec![42]); - assert_eq!( - dur2tmos(reltim2dur(abi::TMAX_RELTIM as u64)).collect::>(), - vec![abi::TMAX_RELTIM] - ); - assert_eq!( - dur2tmos(reltim2dur(abi::TMAX_RELTIM as u64 + 10000)).collect::>(), - vec![abi::TMAX_RELTIM, 10000] - ); -} diff --git a/library/std/src/sys/pal/mod.rs b/library/std/src/sys/pal/mod.rs deleted file mode 100644 index 8c75ac652998b..0000000000000 --- a/library/std/src/sys/pal/mod.rs +++ /dev/null @@ -1,129 +0,0 @@ -//! Platform-dependent platform abstraction. -//! -//! The `std::sys` module is the abstracted interface through which -//! `std` talks to the underlying operating system. It has different -//! implementations for different operating system families, today -//! just Unix and Windows, and initial support for Redox. -//! -//! The centralization of platform-specific code in this module is -//! enforced by the "platform abstraction layer" tidy script in -//! `tools/tidy/src/pal.rs`. -//! -//! This module is closely related to the platform-independent system -//! integration code in `std::sys_common`. See that module's -//! documentation for details. -//! -//! In the future it would be desirable for the independent -//! implementations of this module to be extracted to their own crates -//! that `std` can link to, thus enabling their implementation -//! out-of-tree via crate replacement. Though due to the complex -//! inter-dependencies within `std` that will be a challenging goal to -//! achieve. - -#![allow(missing_debug_implementations)] - -pub mod common; - -cfg_if::cfg_if! { - if #[cfg(unix)] { - mod unix; - pub use self::unix::*; - } else if #[cfg(windows)] { - mod windows; - pub use self::windows::*; - } else if #[cfg(target_os = "solid_asp3")] { - mod solid; - pub use self::solid::*; - } else if #[cfg(target_os = "hermit")] { - mod hermit; - pub use self::hermit::*; - } else if #[cfg(all(target_os = "wasi", target_env = "p2"))] { - mod wasip2; - pub use self::wasip2::*; - } else if #[cfg(target_os = "wasi")] { - mod wasi; - pub use self::wasi::*; - } else if #[cfg(target_family = "wasm")] { - mod wasm; - pub use self::wasm::*; - } else if #[cfg(target_os = "xous")] { - mod xous; - pub use self::xous::*; - } else if #[cfg(target_os = "uefi")] { - mod uefi; - pub use self::uefi::*; - } else if #[cfg(all(target_vendor = "fortanix", target_env = "sgx"))] { - mod sgx; - pub use self::sgx::*; - } else if #[cfg(target_os = "teeos")] { - mod teeos; - pub use self::teeos::*; - } else if #[cfg(target_os = "zkvm")] { - mod zkvm; - pub use self::zkvm::*; - } else { - mod unsupported; - pub use self::unsupported::*; - } -} - -cfg_if::cfg_if! { - // Fuchsia components default to full backtrace. - if #[cfg(target_os = "fuchsia")] { - pub const FULL_BACKTRACE_DEFAULT: bool = true; - } else { - pub const FULL_BACKTRACE_DEFAULT: bool = false; - } -} - -#[cfg(not(test))] -cfg_if::cfg_if! { - if #[cfg(target_os = "android")] { - pub use self::android::log2f32; - pub use self::android::log2f64; - } else { - #[inline] - pub fn log2f32(n: f32) -> f32 { - unsafe { crate::intrinsics::log2f32(n) } - } - - #[inline] - pub fn log2f64(n: f64) -> f64 { - unsafe { crate::intrinsics::log2f64(n) } - } - } -} - -// Solaris/Illumos requires a wrapper around log, log2, and log10 functions -// because of their non-standard behavior (e.g., log(-n) returns -Inf instead -// of expected NaN). -#[cfg(not(test))] -#[cfg(any(target_os = "solaris", target_os = "illumos"))] -#[inline] -pub fn log_wrapper f64>(n: f64, log_fn: F) -> f64 { - if n.is_finite() { - if n > 0.0 { - log_fn(n) - } else if n == 0.0 { - f64::NEG_INFINITY // log(0) = -Inf - } else { - f64::NAN // log(-n) = NaN - } - } else if n.is_nan() { - n // log(NaN) = NaN - } else if n > 0.0 { - n // log(Inf) = Inf - } else { - f64::NAN // log(-Inf) = NaN - } -} - -#[cfg(not(test))] -#[cfg(not(any(target_os = "solaris", target_os = "illumos")))] -#[inline] -pub fn log_wrapper f64>(n: f64, log_fn: F) -> f64 { - log_fn(n) -} - -#[cfg(not(target_os = "uefi"))] -pub type RawOsError = i32; diff --git a/library/std/src/sys/pal/sgx/abi/entry.S b/library/std/src/sys/pal/sgx/abi/entry.S deleted file mode 100644 index 8a063b65dac50..0000000000000 --- a/library/std/src/sys/pal/sgx/abi/entry.S +++ /dev/null @@ -1,376 +0,0 @@ -/* This symbol is used at runtime to figure out the virtual address that the */ -/* enclave is loaded at. */ -.section absolute -.global IMAGE_BASE -IMAGE_BASE: - -.section ".note.x86_64-fortanix-unknown-sgx", "", @note - .align 4 - .long 1f - 0f /* name length (not including padding) */ - .long 3f - 2f /* desc length (not including padding) */ - .long 1 /* type = NT_VERSION */ -0: .asciz "toolchain-version" /* name */ -1: .align 4 -2: .long 1 /* desc - toolchain version number, 32-bit LE */ -3: .align 4 - -.section .rodata -/* The XSAVE area needs to be a large chunk of readable memory, but since we are */ -/* going to restore everything to its initial state (XSTATE_BV=0), only certain */ -/* parts need to have a defined value. In particular: */ -/* */ -/* * MXCSR in the legacy area. This register is always restored if RFBM[1] or */ -/* RFBM[2] is set, regardless of the value of XSTATE_BV */ -/* * XSAVE header */ -.align 64 -.Lxsave_clear: -.org .+24 -.Lxsave_mxcsr: - .short 0x1fbf - -/* We can store a bunch of data in the gap between MXCSR and the XSAVE header */ - -/* The following symbols point at read-only data that will be filled in by the */ -/* post-linker. */ - -/* When using this macro, don't forget to adjust the linker version script! */ -.macro globvar name:req size:req - .global \name - .protected \name - .align \size - .size \name , \size - \name : - .org .+\size -.endm - /* The base address (relative to enclave start) of the heap area */ - globvar HEAP_BASE 8 - /* The heap size in bytes */ - globvar HEAP_SIZE 8 - /* Value of the RELA entry in the dynamic table */ - globvar RELA 8 - /* Value of the RELACOUNT entry in the dynamic table */ - globvar RELACOUNT 8 - /* The enclave size in bytes */ - globvar ENCLAVE_SIZE 8 - /* The base address (relative to enclave start) of the enclave configuration area */ - globvar CFGDATA_BASE 8 - /* Non-zero if debugging is enabled, zero otherwise */ - globvar DEBUG 1 - /* The base address (relative to enclave start) of the enclave text section */ - globvar TEXT_BASE 8 - /* The size in bytes of enclave text section */ - globvar TEXT_SIZE 8 - /* The base address (relative to enclave start) of the enclave .eh_frame_hdr section */ - globvar EH_FRM_HDR_OFFSET 8 - /* The size in bytes of enclave .eh_frame_hdr section */ - globvar EH_FRM_HDR_LEN 8 - /* The base address (relative to enclave start) of the enclave .eh_frame section */ - globvar EH_FRM_OFFSET 8 - /* The size in bytes of enclave .eh_frame section */ - globvar EH_FRM_LEN 8 - -.org .Lxsave_clear+512 -.Lxsave_header: - .int 0, 0 /* XSTATE_BV */ - .int 0, 0 /* XCOMP_BV */ - .org .+48 /* reserved bits */ - -.data -.Laborted: - .byte 0 - -/* TCS local storage section */ -.equ tcsls_tos, 0x00 /* initialized by loader to *offset* from image base to TOS */ -.equ tcsls_flags, 0x08 /* initialized by loader */ -.equ tcsls_flag_secondary, 0 /* initialized by loader; 0 = standard TCS, 1 = secondary TCS */ -.equ tcsls_flag_init_once, 1 /* initialized by loader to 0 */ -/* 14 unused bits */ -.equ tcsls_user_fcw, 0x0a -.equ tcsls_user_mxcsr, 0x0c -.equ tcsls_last_rsp, 0x10 /* initialized by loader to 0 */ -.equ tcsls_panic_last_rsp, 0x18 /* initialized by loader to 0 */ -.equ tcsls_debug_panic_buf_ptr, 0x20 /* initialized by loader to 0 */ -.equ tcsls_user_rsp, 0x28 -.equ tcsls_user_retip, 0x30 -.equ tcsls_user_rbp, 0x38 -.equ tcsls_user_r12, 0x40 -.equ tcsls_user_r13, 0x48 -.equ tcsls_user_r14, 0x50 -.equ tcsls_user_r15, 0x58 -.equ tcsls_tls_ptr, 0x60 -.equ tcsls_tcs_addr, 0x68 - -.macro load_tcsls_flag_secondary_bool reg:req comments:vararg - .ifne tcsls_flag_secondary /* to convert to a bool, must be the first bit */ - .abort - .endif - mov $(1< !; - -// Called once when a TCS is first entered -extern "C" fn tcs_init(secondary: bool); - -// Standard TCS entrypoint -extern "C" fn entry(p1: u64, p2: u64, p3: u64, secondary: bool, p4: u64, p5: u64) -> (u64, u64); -``` -*/ - -.global get_tcs_addr -get_tcs_addr: - mov %gs:tcsls_tcs_addr,%rax - pop %r11 - lfence - jmp *%r11 - -.global get_tls_ptr -get_tls_ptr: - mov %gs:tcsls_tls_ptr,%rax - pop %r11 - lfence - jmp *%r11 - -.global set_tls_ptr -set_tls_ptr: - mov %rdi,%gs:tcsls_tls_ptr - pop %r11 - lfence - jmp *%r11 - -.global take_debug_panic_buf_ptr -take_debug_panic_buf_ptr: - xor %rax,%rax - xchg %gs:tcsls_debug_panic_buf_ptr,%rax - pop %r11 - lfence - jmp *%r11 diff --git a/library/std/src/sys/pal/sgx/abi/mem.rs b/library/std/src/sys/pal/sgx/abi/mem.rs deleted file mode 100644 index 18e6d5b3fa24d..0000000000000 --- a/library/std/src/sys/pal/sgx/abi/mem.rs +++ /dev/null @@ -1,93 +0,0 @@ -use core::arch::asm; - -// Do not remove inline: will result in relocation failure -#[inline(always)] -pub(crate) unsafe fn rel_ptr(offset: u64) -> *const T { - (image_base() + offset) as *const T -} - -// Do not remove inline: will result in relocation failure -#[inline(always)] -pub(crate) unsafe fn rel_ptr_mut(offset: u64) -> *mut T { - (image_base() + offset) as *mut T -} - -extern "C" { - static ENCLAVE_SIZE: usize; - static HEAP_BASE: u64; - static HEAP_SIZE: usize; -} - -/// Returns the base memory address of the heap -pub(crate) fn heap_base() -> *const u8 { - unsafe { rel_ptr_mut(HEAP_BASE) } -} - -/// Returns the size of the heap -pub(crate) fn heap_size() -> usize { - unsafe { HEAP_SIZE } -} - -// Do not remove inline: will result in relocation failure -// For the same reason we use inline ASM here instead of an extern static to -// locate the base -/// Returns address at which current enclave is loaded. -#[inline(always)] -#[unstable(feature = "sgx_platform", issue = "56975")] -pub fn image_base() -> u64 { - let base: u64; - unsafe { - asm!( - "lea IMAGE_BASE(%rip), {}", - lateout(reg) base, - options(att_syntax, nostack, preserves_flags, nomem, pure), - ) - }; - base -} - -/// Returns `true` if the specified memory range is in the enclave. -/// -/// For safety, this function also checks whether the range given overflows, -/// returning `false` if so. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub fn is_enclave_range(p: *const u8, len: usize) -> bool { - let start = p as usize; - - // Subtract one from `len` when calculating `end` in case `p + len` is - // exactly at the end of addressable memory (`p + len` would overflow, but - // the range is still valid). - let end = if len == 0 { - start - } else if let Some(end) = start.checked_add(len - 1) { - end - } else { - return false; - }; - - let base = image_base() as usize; - start >= base && end <= base + (unsafe { ENCLAVE_SIZE } - 1) // unsafe ok: link-time constant -} - -/// Returns `true` if the specified memory range is in userspace. -/// -/// For safety, this function also checks whether the range given overflows, -/// returning `false` if so. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub fn is_user_range(p: *const u8, len: usize) -> bool { - let start = p as usize; - - // Subtract one from `len` when calculating `end` in case `p + len` is - // exactly at the end of addressable memory (`p + len` would overflow, but - // the range is still valid). - let end = if len == 0 { - start - } else if let Some(end) = start.checked_add(len - 1) { - end - } else { - return false; - }; - - let base = image_base() as usize; - end < base || start > base + (unsafe { ENCLAVE_SIZE } - 1) // unsafe ok: link-time constant -} diff --git a/library/std/src/sys/pal/sgx/abi/mod.rs b/library/std/src/sys/pal/sgx/abi/mod.rs deleted file mode 100644 index 9508c38741551..0000000000000 --- a/library/std/src/sys/pal/sgx/abi/mod.rs +++ /dev/null @@ -1,108 +0,0 @@ -#![cfg_attr(test, allow(unused))] // RT initialization logic is not compiled for test - -use crate::io::Write; -use core::arch::global_asm; -use core::sync::atomic::{AtomicUsize, Ordering}; - -// runtime features -pub(super) mod panic; -mod reloc; - -// library features -pub mod mem; -pub mod thread; -pub mod tls; -#[macro_use] -pub mod usercalls; - -#[cfg(not(test))] -global_asm!(include_str!("entry.S"), options(att_syntax)); - -#[repr(C)] -struct EntryReturn(u64, u64); - -#[cfg(not(test))] -#[no_mangle] -unsafe extern "C" fn tcs_init(secondary: bool) { - // Be very careful when changing this code: it runs before the binary has been - // relocated. Any indirect accesses to symbols will likely fail. - const UNINIT: usize = 0; - const BUSY: usize = 1; - const DONE: usize = 2; - // Three-state spin-lock - static RELOC_STATE: AtomicUsize = AtomicUsize::new(UNINIT); - - if secondary && RELOC_STATE.load(Ordering::Relaxed) != DONE { - rtabort!("Entered secondary TCS before main TCS!") - } - - // Try to atomically swap UNINIT with BUSY. The returned state can be: - match RELOC_STATE.compare_exchange(UNINIT, BUSY, Ordering::Acquire, Ordering::Acquire) { - // This thread just obtained the lock and other threads will observe BUSY - Ok(_) => { - reloc::relocate_elf_rela(); - RELOC_STATE.store(DONE, Ordering::Release); - } - // We need to wait until the initialization is done. - Err(BUSY) => { - while RELOC_STATE.load(Ordering::Acquire) == BUSY { - core::hint::spin_loop(); - } - } - // Initialization is done. - Err(DONE) => {} - _ => unreachable!(), - } -} - -// FIXME: this item should only exist if this is linked into an executable -// (main function exists). If this is a library, the crate author should be -// able to specify this -#[cfg(not(test))] -#[no_mangle] -extern "C" fn entry(p1: u64, p2: u64, p3: u64, secondary: bool, p4: u64, p5: u64) -> EntryReturn { - // FIXME: how to support TLS in library mode? - let tls = Box::new(tls::Tls::new()); - let tls_guard = unsafe { tls.activate() }; - - if secondary { - let join_notifier = super::thread::Thread::entry(); - drop(tls_guard); - drop(join_notifier); - - EntryReturn(0, 0) - } else { - extern "C" { - fn main(argc: isize, argv: *const *const u8) -> isize; - } - - // check entry is being called according to ABI - rtassert!(p3 == 0); - rtassert!(p4 == 0); - rtassert!(p5 == 0); - - unsafe { - // The actual types of these arguments are `p1: *const Arg, p2: - // usize`. We can't currently customize the argument list of Rust's - // main function, so we pass these in as the standard pointer-sized - // values in `argc` and `argv`. - let ret = main(p2 as _, p1 as _); - exit_with_code(ret) - } - } -} - -pub(super) fn exit_with_code(code: isize) -> ! { - if code != 0 { - if let Some(mut out) = panic::SgxPanicOutput::new() { - let _ = write!(out, "Exited with status code {code}"); - } - } - usercalls::exit(code != 0); -} - -#[cfg(not(test))] -#[no_mangle] -extern "C" fn abort_reentry() -> ! { - usercalls::exit(false) -} diff --git a/library/std/src/sys/pal/sgx/abi/panic.rs b/library/std/src/sys/pal/sgx/abi/panic.rs deleted file mode 100644 index 229b3b3291f63..0000000000000 --- a/library/std/src/sys/pal/sgx/abi/panic.rs +++ /dev/null @@ -1,42 +0,0 @@ -use super::usercalls::alloc::UserRef; -use crate::cmp; -use crate::io::{self, Write}; -use crate::mem; - -extern "C" { - fn take_debug_panic_buf_ptr() -> *mut u8; - static DEBUG: u8; -} - -pub(crate) struct SgxPanicOutput(Option<&'static mut UserRef<[u8]>>); - -fn empty_user_slice() -> &'static mut UserRef<[u8]> { - unsafe { UserRef::from_raw_parts_mut(1 as *mut u8, 0) } -} - -impl SgxPanicOutput { - pub(crate) fn new() -> Option { - if unsafe { DEBUG == 0 } { None } else { Some(SgxPanicOutput(None)) } - } - - fn init(&mut self) -> &mut &'static mut UserRef<[u8]> { - self.0.get_or_insert_with(|| unsafe { - let ptr = take_debug_panic_buf_ptr(); - if ptr.is_null() { empty_user_slice() } else { UserRef::from_raw_parts_mut(ptr, 1024) } - }) - } -} - -impl Write for SgxPanicOutput { - fn write(&mut self, src: &[u8]) -> io::Result { - let dst = mem::replace(self.init(), empty_user_slice()); - let written = cmp::min(src.len(), dst.len()); - dst[..written].copy_from_enclave(&src[..written]); - self.0 = Some(&mut dst[written..]); - Ok(written) - } - - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} diff --git a/library/std/src/sys/pal/sgx/abi/reloc.rs b/library/std/src/sys/pal/sgx/abi/reloc.rs deleted file mode 100644 index 02dff0ad29fc3..0000000000000 --- a/library/std/src/sys/pal/sgx/abi/reloc.rs +++ /dev/null @@ -1,32 +0,0 @@ -use super::mem; -use crate::slice::from_raw_parts; - -const R_X86_64_RELATIVE: u32 = 8; - -#[repr(packed)] -struct Rela { - offset: T, - info: T, - addend: T, -} - -pub fn relocate_elf_rela() { - extern "C" { - static RELA: u64; - static RELACOUNT: usize; - } - - if unsafe { RELACOUNT } == 0 { - return; - } // unsafe ok: link-time constant - - let relas = unsafe { - from_raw_parts::>(mem::rel_ptr(RELA), RELACOUNT) // unsafe ok: link-time constant - }; - for rela in relas { - if rela.info != (/*0 << 32 |*/R_X86_64_RELATIVE as u64) { - rtabort!("Invalid relocation"); - } - unsafe { *mem::rel_ptr_mut::<*const ()>(rela.offset) = mem::rel_ptr(rela.addend) }; - } -} diff --git a/library/std/src/sys/pal/sgx/abi/thread.rs b/library/std/src/sys/pal/sgx/abi/thread.rs deleted file mode 100644 index 2b23e368cc31a..0000000000000 --- a/library/std/src/sys/pal/sgx/abi/thread.rs +++ /dev/null @@ -1,17 +0,0 @@ -use fortanix_sgx_abi::Tcs; - -/// Gets the ID for the current thread. The ID is guaranteed to be unique among -/// all currently running threads in the enclave, and it is guaranteed to be -/// constant for the lifetime of the thread. More specifically for SGX, there -/// is a one-to-one correspondence of the ID to the address of the TCS. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub fn current() -> Tcs { - extern "C" { - fn get_tcs_addr() -> *mut u8; - } - let addr = unsafe { get_tcs_addr() }; - match Tcs::new(addr) { - Some(tcs) => tcs, - None => rtabort!("TCS must not be placed at address zero (this is a linker error)"), - } -} diff --git a/library/std/src/sys/pal/sgx/abi/tls/mod.rs b/library/std/src/sys/pal/sgx/abi/tls/mod.rs deleted file mode 100644 index 8a9ea4ac00df0..0000000000000 --- a/library/std/src/sys/pal/sgx/abi/tls/mod.rs +++ /dev/null @@ -1,133 +0,0 @@ -mod sync_bitset; - -use self::sync_bitset::*; -use crate::cell::Cell; -use crate::mem; -use crate::num::NonZero; -use crate::ptr; -use crate::sync::atomic::{AtomicUsize, Ordering}; - -#[cfg(target_pointer_width = "64")] -const USIZE_BITS: usize = 64; -const TLS_KEYS: usize = 128; // Same as POSIX minimum -const TLS_KEYS_BITSET_SIZE: usize = (TLS_KEYS + (USIZE_BITS - 1)) / USIZE_BITS; - -#[cfg_attr(test, linkage = "available_externally")] -#[export_name = "_ZN16__rust_internals3std3sys3sgx3abi3tls14TLS_KEY_IN_USEE"] -static TLS_KEY_IN_USE: SyncBitset = SYNC_BITSET_INIT; -macro_rules! dup { - ((* $($exp:tt)*) $($val:tt)*) => (dup!( ($($exp)*) $($val)* $($val)* )); - (() $($val:tt)*) => ([$($val),*]) -} -#[cfg_attr(test, linkage = "available_externally")] -#[export_name = "_ZN16__rust_internals3std3sys3sgx3abi3tls14TLS_DESTRUCTORE"] -static TLS_DESTRUCTOR: [AtomicUsize; TLS_KEYS] = dup!((* * * * * * *) (AtomicUsize::new(0))); - -extern "C" { - fn get_tls_ptr() -> *const u8; - fn set_tls_ptr(tls: *const u8); -} - -#[derive(Copy, Clone)] -#[repr(C)] -pub struct Key(NonZero); - -impl Key { - fn to_index(self) -> usize { - self.0.get() - 1 - } - - fn from_index(index: usize) -> Self { - Key(NonZero::new(index + 1).unwrap()) - } - - pub fn as_usize(self) -> usize { - self.0.get() - } - - pub fn from_usize(index: usize) -> Self { - Key(NonZero::new(index).unwrap()) - } -} - -#[repr(C)] -pub struct Tls { - data: [Cell<*mut u8>; TLS_KEYS], -} - -pub struct ActiveTls<'a> { - tls: &'a Tls, -} - -impl<'a> Drop for ActiveTls<'a> { - fn drop(&mut self) { - let value_with_destructor = |key: usize| { - let ptr = TLS_DESTRUCTOR[key].load(Ordering::Relaxed); - unsafe { mem::transmute::<_, Option>(ptr) } - .map(|dtor| (&self.tls.data[key], dtor)) - }; - - let mut any_non_null_dtor = true; - while any_non_null_dtor { - any_non_null_dtor = false; - for (value, dtor) in TLS_KEY_IN_USE.iter().filter_map(&value_with_destructor) { - let value = value.replace(ptr::null_mut()); - if !value.is_null() { - any_non_null_dtor = true; - unsafe { dtor(value) } - } - } - } - } -} - -impl Tls { - pub fn new() -> Tls { - Tls { data: dup!((* * * * * * *) (Cell::new(ptr::null_mut()))) } - } - - pub unsafe fn activate(&self) -> ActiveTls<'_> { - // FIXME: Needs safety information. See entry.S for `set_tls_ptr` definition. - unsafe { set_tls_ptr(self as *const Tls as _) }; - ActiveTls { tls: self } - } - - #[allow(unused)] - pub unsafe fn activate_persistent(self: Box) { - // FIXME: Needs safety information. See entry.S for `set_tls_ptr` definition. - unsafe { set_tls_ptr(core::ptr::addr_of!(*self) as _) }; - mem::forget(self); - } - - unsafe fn current<'a>() -> &'a Tls { - // FIXME: Needs safety information. See entry.S for `set_tls_ptr` definition. - unsafe { &*(get_tls_ptr() as *const Tls) } - } - - pub fn create(dtor: Option) -> Key { - let index = if let Some(index) = TLS_KEY_IN_USE.set() { - index - } else { - rtabort!("TLS limit exceeded") - }; - TLS_DESTRUCTOR[index].store(dtor.map_or(0, |f| f as usize), Ordering::Relaxed); - unsafe { Self::current() }.data[index].set(ptr::null_mut()); - Key::from_index(index) - } - - pub fn set(key: Key, value: *mut u8) { - let index = key.to_index(); - rtassert!(TLS_KEY_IN_USE.get(index)); - unsafe { Self::current() }.data[index].set(value); - } - - pub fn get(key: Key) -> *mut u8 { - let index = key.to_index(); - rtassert!(TLS_KEY_IN_USE.get(index)); - unsafe { Self::current() }.data[index].get() - } - - pub fn destroy(key: Key) { - TLS_KEY_IN_USE.clear(key.to_index()); - } -} diff --git a/library/std/src/sys/pal/sgx/abi/tls/sync_bitset.rs b/library/std/src/sys/pal/sgx/abi/tls/sync_bitset.rs deleted file mode 100644 index 4eeff8f6ef773..0000000000000 --- a/library/std/src/sys/pal/sgx/abi/tls/sync_bitset.rs +++ /dev/null @@ -1,85 +0,0 @@ -#[cfg(test)] -mod tests; - -use super::{TLS_KEYS_BITSET_SIZE, USIZE_BITS}; -use crate::iter::{Enumerate, Peekable}; -use crate::slice::Iter; -use crate::sync::atomic::{AtomicUsize, Ordering}; - -/// A bitset that can be used synchronously. -pub(super) struct SyncBitset([AtomicUsize; TLS_KEYS_BITSET_SIZE]); - -pub(super) const SYNC_BITSET_INIT: SyncBitset = - SyncBitset([AtomicUsize::new(0), AtomicUsize::new(0)]); - -impl SyncBitset { - pub fn get(&self, index: usize) -> bool { - let (hi, lo) = Self::split(index); - (self.0[hi].load(Ordering::Relaxed) & lo) != 0 - } - - /// Not atomic. - pub fn iter(&self) -> SyncBitsetIter<'_> { - SyncBitsetIter { iter: self.0.iter().enumerate().peekable(), elem_idx: 0 } - } - - pub fn clear(&self, index: usize) { - let (hi, lo) = Self::split(index); - self.0[hi].fetch_and(!lo, Ordering::Relaxed); - } - - /// Sets any unset bit. Not atomic. Returns `None` if all bits were - /// observed to be set. - pub fn set(&self) -> Option { - 'elems: for (idx, elem) in self.0.iter().enumerate() { - let mut current = elem.load(Ordering::Relaxed); - loop { - if 0 == !current { - continue 'elems; - } - let trailing_ones = (!current).trailing_zeros() as usize; - match elem.compare_exchange( - current, - current | (1 << trailing_ones), - Ordering::AcqRel, - Ordering::Relaxed, - ) { - Ok(_) => return Some(idx * USIZE_BITS + trailing_ones), - Err(previous) => current = previous, - } - } - } - None - } - - fn split(index: usize) -> (usize, usize) { - (index / USIZE_BITS, 1 << (index % USIZE_BITS)) - } -} - -pub(super) struct SyncBitsetIter<'a> { - iter: Peekable>>, - elem_idx: usize, -} - -impl<'a> Iterator for SyncBitsetIter<'a> { - type Item = usize; - - fn next(&mut self) -> Option { - self.iter.peek().cloned().and_then(|(idx, elem)| { - let elem = elem.load(Ordering::Relaxed); - let low_mask = (1 << self.elem_idx) - 1; - let next = elem & !low_mask; - let next_idx = next.trailing_zeros() as usize; - self.elem_idx = next_idx + 1; - if self.elem_idx >= 64 { - self.elem_idx = 0; - self.iter.next(); - } - match next_idx { - 64 => self.next(), - _ => Some(idx * USIZE_BITS + next_idx), - } - }) - } -} diff --git a/library/std/src/sys/pal/sgx/abi/tls/sync_bitset/tests.rs b/library/std/src/sys/pal/sgx/abi/tls/sync_bitset/tests.rs deleted file mode 100644 index d7eb2e139d011..0000000000000 --- a/library/std/src/sys/pal/sgx/abi/tls/sync_bitset/tests.rs +++ /dev/null @@ -1,25 +0,0 @@ -use super::*; - -fn test_data(bitset: [usize; 2], bit_indices: &[usize]) { - let set = SyncBitset([AtomicUsize::new(bitset[0]), AtomicUsize::new(bitset[1])]); - assert_eq!(set.iter().collect::>(), bit_indices); - for &i in bit_indices { - assert!(set.get(i)); - } -} - -#[test] -fn iter() { - test_data([0b0110_1001, 0], &[0, 3, 5, 6]); - test_data([0x8000_0000_0000_0000, 0x8000_0000_0000_0001], &[63, 64, 127]); - test_data([0, 0], &[]); -} - -#[test] -fn set_get_clear() { - let set = SYNC_BITSET_INIT; - let key = set.set().unwrap(); - assert!(set.get(key)); - set.clear(key); - assert!(!set.get(key)); -} diff --git a/library/std/src/sys/pal/sgx/abi/usercalls/alloc.rs b/library/std/src/sys/pal/sgx/abi/usercalls/alloc.rs deleted file mode 100644 index f99cea360f1f4..0000000000000 --- a/library/std/src/sys/pal/sgx/abi/usercalls/alloc.rs +++ /dev/null @@ -1,819 +0,0 @@ -#![allow(unused)] - -use crate::arch::asm; -use crate::cell::UnsafeCell; -use crate::cmp; -use crate::convert::TryInto; -use crate::intrinsics; -use crate::mem; -use crate::ops::{CoerceUnsized, Deref, DerefMut, Index, IndexMut}; -use crate::ptr::{self, NonNull}; -use crate::slice; -use crate::slice::SliceIndex; - -use super::super::mem::{is_enclave_range, is_user_range}; -use fortanix_sgx_abi::*; - -/// A type that can be safely read from or written to userspace. -/// -/// Non-exhaustive list of specific requirements for reading and writing: -/// * **Type is `Copy`** (and therefore also not `Drop`). Copies will be -/// created when copying from/to userspace. Destructors will not be called. -/// * **No references or Rust-style owned pointers** (`Vec`, `Arc`, etc.). When -/// reading from userspace, references into enclave memory must not be -/// created. Also, only enclave memory is considered managed by the Rust -/// compiler's static analysis. When reading from userspace, there can be no -/// guarantee that the value correctly adheres to the expectations of the -/// type. When writing to userspace, memory addresses of data in enclave -/// memory must not be leaked for confidentiality reasons. `User` and -/// `UserRef` are also not allowed for the same reasons. -/// * **No fat pointers.** When reading from userspace, the size or vtable -/// pointer could be automatically interpreted and used by the code. When -/// writing to userspace, memory addresses of data in enclave memory (such -/// as vtable pointers) must not be leaked for confidentiality reasons. -/// -/// Non-exhaustive list of specific requirements for reading from userspace: -/// * **Any bit pattern is valid** for this type (no `enum`s). There can be no -/// guarantee that the value correctly adheres to the expectations of the -/// type, so any value must be valid for this type. -/// -/// Non-exhaustive list of specific requirements for writing to userspace: -/// * **No pointers to enclave memory.** Memory addresses of data in enclave -/// memory must not be leaked for confidentiality reasons. -/// * **No internal padding.** Padding might contain previously-initialized -/// secret data stored at that memory location and must not be leaked for -/// confidentiality reasons. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub unsafe trait UserSafeSized: Copy + Sized {} - -#[unstable(feature = "sgx_platform", issue = "56975")] -unsafe impl UserSafeSized for u8 {} -#[unstable(feature = "sgx_platform", issue = "56975")] -unsafe impl UserSafeSized for FifoDescriptor {} -#[unstable(feature = "sgx_platform", issue = "56975")] -unsafe impl UserSafeSized for ByteBuffer {} -#[unstable(feature = "sgx_platform", issue = "56975")] -unsafe impl UserSafeSized for Usercall {} -#[unstable(feature = "sgx_platform", issue = "56975")] -unsafe impl UserSafeSized for Return {} -#[unstable(feature = "sgx_platform", issue = "56975")] -unsafe impl UserSafeSized for Cancel {} -#[unstable(feature = "sgx_platform", issue = "56975")] -unsafe impl UserSafeSized for [T; 2] {} - -/// A type that can be represented in memory as one or more `UserSafeSized`s. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub unsafe trait UserSafe { - /// Equivalent to `mem::align_of::`. - fn align_of() -> usize; - - /// Construct a pointer to `Self` given a memory range in user space. - /// - /// N.B., this takes a size, not a length! - /// - /// # Safety - /// - /// The caller must ensure the memory range is in user memory, is the - /// correct size and is correctly aligned and points to the right type. - unsafe fn from_raw_sized_unchecked(ptr: *mut u8, size: usize) -> *mut Self; - - /// Construct a pointer to `Self` given a memory range. - /// - /// N.B., this takes a size, not a length! - /// - /// # Safety - /// - /// The caller must ensure the memory range points to the correct type. - /// - /// # Panics - /// - /// This function panics if: - /// - /// * the pointer is not aligned. - /// * the pointer is null. - /// * the pointed-to range does not fit in the address space. - /// * the pointed-to range is not in user memory. - unsafe fn from_raw_sized(ptr: *mut u8, size: usize) -> NonNull { - assert!(ptr.wrapping_add(size) >= ptr); - // SAFETY: The caller has guaranteed the pointer is valid - let ret = unsafe { Self::from_raw_sized_unchecked(ptr, size) }; - unsafe { - Self::check_ptr(ret); - NonNull::new_unchecked(ret as _) - } - } - - /// Checks if a pointer may point to `Self` in user memory. - /// - /// # Safety - /// - /// The caller must ensure the memory range points to the correct type and - /// length (if this is a slice). - /// - /// # Panics - /// - /// This function panics if: - /// - /// * the pointer is not aligned. - /// * the pointer is null. - /// * the pointed-to range is not in user memory. - unsafe fn check_ptr(ptr: *const Self) { - let is_aligned = |p: *const u8| -> bool { p.is_aligned_to(Self::align_of()) }; - - assert!(is_aligned(ptr as *const u8)); - assert!(is_user_range(ptr as _, mem::size_of_val(unsafe { &*ptr }))); - assert!(!ptr.is_null()); - } -} - -#[unstable(feature = "sgx_platform", issue = "56975")] -unsafe impl UserSafe for T { - fn align_of() -> usize { - mem::align_of::() - } - - unsafe fn from_raw_sized_unchecked(ptr: *mut u8, size: usize) -> *mut Self { - assert_eq!(size, mem::size_of::()); - ptr as _ - } -} - -#[unstable(feature = "sgx_platform", issue = "56975")] -unsafe impl UserSafe for [T] { - fn align_of() -> usize { - mem::align_of::() - } - - /// # Safety - /// Behavior is undefined if any of these conditions are violated: - /// * `ptr` must be [valid] for writes of `size` many bytes, and it must be - /// properly aligned. - /// - /// [valid]: core::ptr#safety - /// # Panics - /// - /// This function panics if: - /// - /// * the element size is not a factor of the size - unsafe fn from_raw_sized_unchecked(ptr: *mut u8, size: usize) -> *mut Self { - let elem_size = mem::size_of::(); - assert_eq!(size % elem_size, 0); - let len = size / elem_size; - // SAFETY: The caller must uphold the safety contract for `from_raw_sized_unchecked` - unsafe { slice::from_raw_parts_mut(ptr as _, len) } - } -} - -/// A reference to some type in userspace memory. `&UserRef` is equivalent -/// to `&T` in enclave memory. Access to the memory is only allowed by copying -/// to avoid TOCTTOU issues. After copying, code should make sure to completely -/// check the value before use. -/// -/// It is also possible to obtain a mutable reference `&mut UserRef`. Unlike -/// regular mutable references, these are not exclusive. Userspace may always -/// write to the backing memory at any time, so it can't be assumed that there -/// the pointed-to memory is uniquely borrowed. The two different reference types -/// are used solely to indicate intent: a mutable reference is for writing to -/// user memory, an immutable reference for reading from user memory. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub struct UserRef(UnsafeCell); -/// An owned type in userspace memory. `User` is equivalent to `Box` in -/// enclave memory. Access to the memory is only allowed by copying to avoid -/// TOCTTOU issues. The user memory will be freed when the value is dropped. -/// After copying, code should make sure to completely check the value before -/// use. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub struct User(NonNull>); - -#[unstable(feature = "sgx_platform", issue = "56975")] -unsafe impl Send for User {} - -#[unstable(feature = "sgx_platform", issue = "56975")] -unsafe impl Send for User<[T]> {} - -trait NewUserRef { - unsafe fn new_userref(v: T) -> Self; -} - -impl NewUserRef<*mut T> for NonNull> { - unsafe fn new_userref(v: *mut T) -> Self { - // SAFETY: The caller has guaranteed the pointer is valid - unsafe { NonNull::new_unchecked(v as _) } - } -} - -impl NewUserRef> for NonNull> { - unsafe fn new_userref(v: NonNull) -> Self { - // SAFETY: The caller has guaranteed the pointer is valid - unsafe { NonNull::new_userref(v.as_ptr()) } - } -} - -#[unstable(feature = "sgx_platform", issue = "56975")] -impl User -where - T: UserSafe, -{ - // This function returns memory that is practically uninitialized, but is - // not considered "unspecified" or "undefined" for purposes of an - // optimizing compiler. This is achieved by returning a pointer from - // from outside as obtained by `super::alloc`. - fn new_uninit_bytes(size: usize) -> Self { - unsafe { - // Mustn't call alloc with size 0. - let ptr = if size > 0 { - // `copy_to_userspace` is more efficient when data is 8-byte aligned - let alignment = cmp::max(T::align_of(), 8); - rtunwrap!(Ok, super::alloc(size, alignment)) as _ - } else { - T::align_of() as _ // dangling pointer ok for size 0 - }; - if let Ok(v) = crate::panic::catch_unwind(|| T::from_raw_sized(ptr, size)) { - User(NonNull::new_userref(v)) - } else { - rtabort!("Got invalid pointer from alloc() usercall") - } - } - } - - /// Copies `val` into freshly allocated space in user memory. - pub fn new_from_enclave(val: &T) -> Self { - unsafe { - let mut user = Self::new_uninit_bytes(mem::size_of_val(val)); - user.copy_from_enclave(val); - user - } - } - - /// Creates an owned `User` from a raw pointer. - /// - /// # Safety - /// The caller must ensure `ptr` points to `T`, is freeable with the `free` - /// usercall and the alignment of `T`, and is uniquely owned. - /// - /// # Panics - /// This function panics if: - /// - /// * The pointer is not aligned - /// * The pointer is null - /// * The pointed-to range is not in user memory - pub unsafe fn from_raw(ptr: *mut T) -> Self { - // SAFETY: the caller must uphold the safety contract for `from_raw`. - unsafe { T::check_ptr(ptr) }; - User(unsafe { NonNull::new_userref(ptr) }) - } - - /// Converts this value into a raw pointer. The value will no longer be - /// automatically freed. - pub fn into_raw(self) -> *mut T { - let ret = self.0; - mem::forget(self); - ret.as_ptr() as _ - } -} - -#[unstable(feature = "sgx_platform", issue = "56975")] -impl User -where - T: UserSafe, -{ - /// Allocate space for `T` in user memory. - pub fn uninitialized() -> Self { - Self::new_uninit_bytes(mem::size_of::()) - } -} - -#[unstable(feature = "sgx_platform", issue = "56975")] -impl User<[T]> -where - [T]: UserSafe, -{ - /// Allocate space for a `[T]` of `n` elements in user memory. - pub fn uninitialized(n: usize) -> Self { - Self::new_uninit_bytes(n * mem::size_of::()) - } - - /// Creates an owned `User<[T]>` from a raw thin pointer and a slice length. - /// - /// # Safety - /// The caller must ensure `ptr` points to `len` elements of `T`, is - /// freeable with the `free` usercall and the alignment of `T`, and is - /// uniquely owned. - /// - /// # Panics - /// This function panics if: - /// - /// * The pointer is not aligned - /// * The pointer is null - /// * The pointed-to range does not fit in the address space - /// * The pointed-to range is not in user memory - pub unsafe fn from_raw_parts(ptr: *mut T, len: usize) -> Self { - User(unsafe { - NonNull::new_userref(<[T]>::from_raw_sized(ptr as _, len * mem::size_of::())) - }) - } -} - -/// Divide the slice `(ptr, len)` into three parts, where the middle part is -/// aligned to `u64`. -/// -/// The return values `(prefix_len, mid_len, suffix_len)` add back up to `len`. -/// The return values are such that the memory region `(ptr + prefix_len, -/// mid_len)` is the largest possible region where `ptr + prefix_len` is aligned -/// to `u64` and `mid_len` is a multiple of the byte size of `u64`. This means -/// that `prefix_len` and `suffix_len` are guaranteed to be less than the byte -/// size of `u64`, and that `(ptr, prefix_len)` and `(ptr + prefix_len + -/// mid_len, suffix_len)` don't straddle an alignment boundary. -// Standard Rust functions such as `<[u8]>::align_to::` and -// `<*const u8>::align_offset` aren't _guaranteed_ to compute the largest -// possible middle region, and as such can't be used. -fn u64_align_to_guaranteed(ptr: *const u8, mut len: usize) -> (usize, usize, usize) { - const QWORD_SIZE: usize = mem::size_of::(); - - let offset = ptr as usize % QWORD_SIZE; - - let prefix_len = if intrinsics::unlikely(offset > 0) { QWORD_SIZE - offset } else { 0 }; - - len = match len.checked_sub(prefix_len) { - Some(remaining_len) => remaining_len, - None => return (len, 0, 0), - }; - - let suffix_len = len % QWORD_SIZE; - len -= suffix_len; - - (prefix_len, len, suffix_len) -} - -unsafe fn copy_quadwords(src: *const u8, dst: *mut u8, len: usize) { - unsafe { - asm!( - "rep movsq (%rsi), (%rdi)", - inout("rcx") len / 8 => _, - inout("rdi") dst => _, - inout("rsi") src => _, - options(att_syntax, nostack, preserves_flags) - ); - } -} - -/// Copies `len` bytes of data from enclave pointer `src` to userspace `dst` -/// -/// This function mitigates stale data vulnerabilities by ensuring all writes to untrusted memory are either: -/// - preceded by the VERW instruction and followed by the MFENCE; LFENCE instruction sequence -/// - or are in multiples of 8 bytes, aligned to an 8-byte boundary -/// -/// # Panics -/// This function panics if: -/// -/// * The `src` pointer is null -/// * The `dst` pointer is null -/// * The `src` memory range is not in enclave memory -/// * The `dst` memory range is not in user memory -/// -/// # References -/// - https://www.intel.com/content/www/us/en/security-center/advisory/intel-sa-00615.html -/// - https://www.intel.com/content/www/us/en/developer/articles/technical/software-security-guidance/technical-documentation/processor-mmio-stale-data-vulnerabilities.html#inpage-nav-3-2-2 -pub(crate) unsafe fn copy_to_userspace(src: *const u8, dst: *mut u8, len: usize) { - /// Like `ptr::copy(src, dst, len)`, except it uses the Intel-recommended - /// instruction sequence for unaligned writes. - unsafe fn write_bytewise_to_userspace(src: *const u8, dst: *mut u8, len: usize) { - if intrinsics::likely(len == 0) { - return; - } - - unsafe { - let mut seg_sel: u16 = 0; - for off in 0..len { - asm!(" - mov %ds, ({seg_sel}) - verw ({seg_sel}) - movb {val}, ({dst}) - mfence - lfence - ", - val = in(reg_byte) *src.add(off), - dst = in(reg) dst.add(off), - seg_sel = in(reg) &mut seg_sel, - options(nostack, att_syntax) - ); - } - } - } - - assert!(!src.is_null()); - assert!(!dst.is_null()); - assert!(is_enclave_range(src, len)); - assert!(is_user_range(dst, len)); - assert!(len < isize::MAX as usize); - assert!(!src.addr().overflowing_add(len).1); - assert!(!dst.addr().overflowing_add(len).1); - - unsafe { - let (len1, len2, len3) = u64_align_to_guaranteed(dst, len); - let (src1, dst1) = (src, dst); - let (src2, dst2) = (src1.add(len1), dst1.add(len1)); - let (src3, dst3) = (src2.add(len2), dst2.add(len2)); - - write_bytewise_to_userspace(src1, dst1, len1); - copy_quadwords(src2, dst2, len2); - write_bytewise_to_userspace(src3, dst3, len3); - } -} - -/// Copies `len` bytes of data from userspace pointer `src` to enclave pointer `dst` -/// -/// This function mitigates AEPIC leak vulnerabilities by ensuring all reads from untrusted memory are 8-byte aligned -/// -/// # Panics -/// This function panics if: -/// -/// * The `src` pointer is null -/// * The `dst` pointer is null -/// * The `src` memory range is not in user memory -/// * The `dst` memory range is not in enclave memory -/// -/// # References -/// - https://www.intel.com/content/www/us/en/security-center/advisory/intel-sa-00657.html -/// - https://www.intel.com/content/www/us/en/developer/articles/technical/software-security-guidance/advisory-guidance/stale-data-read-from-xapic.html -pub(crate) unsafe fn copy_from_userspace(src: *const u8, dst: *mut u8, len: usize) { - /// Like `ptr::copy(src, dst, len)`, except it uses only u64-aligned reads. - /// - /// # Safety - /// The source memory region must not straddle an alignment boundary. - unsafe fn read_misaligned_from_userspace(src: *const u8, dst: *mut u8, len: usize) { - if intrinsics::likely(len == 0) { - return; - } - - unsafe { - let offset: usize; - let data: u64; - // doing a memory read that's potentially out of bounds for `src`, - // this isn't supported by Rust, so have to use assembly - asm!(" - movl {src:e}, {offset:e} - andl $7, {offset:e} - andq $-8, {src} - movq ({src}), {dst} - ", - src = inout(reg) src => _, - offset = out(reg) offset, - dst = out(reg) data, - options(nostack, att_syntax, readonly, pure) - ); - let data = data.to_le_bytes(); - ptr::copy_nonoverlapping(data.as_ptr().add(offset), dst, len); - } - } - - assert!(!src.is_null()); - assert!(!dst.is_null()); - assert!(is_user_range(src, len)); - assert!(is_enclave_range(dst, len)); - assert!(len < isize::MAX as usize); - assert!(!(src as usize).overflowing_add(len).1); - assert!(!(dst as usize).overflowing_add(len).1); - - unsafe { - let (len1, len2, len3) = u64_align_to_guaranteed(src, len); - let (src1, dst1) = (src, dst); - let (src2, dst2) = (src1.add(len1), dst1.add(len1)); - let (src3, dst3) = (src2.add(len2), dst2.add(len2)); - - read_misaligned_from_userspace(src1, dst1, len1); - copy_quadwords(src2, dst2, len2); - read_misaligned_from_userspace(src3, dst3, len3); - } -} - -#[unstable(feature = "sgx_platform", issue = "56975")] -impl UserRef -where - T: UserSafe, -{ - /// Creates a `&UserRef<[T]>` from a raw pointer. - /// - /// # Safety - /// The caller must ensure `ptr` points to `T`. - /// - /// # Panics - /// This function panics if: - /// - /// * The pointer is not aligned - /// * The pointer is null - /// * The pointed-to range is not in user memory - pub unsafe fn from_ptr<'a>(ptr: *const T) -> &'a Self { - // SAFETY: The caller must uphold the safety contract for `from_ptr`. - unsafe { T::check_ptr(ptr) }; - unsafe { &*(ptr as *const Self) } - } - - /// Creates a `&mut UserRef<[T]>` from a raw pointer. See the struct - /// documentation for the nuances regarding a `&mut UserRef`. - /// - /// # Safety - /// The caller must ensure `ptr` points to `T`. - /// - /// # Panics - /// This function panics if: - /// - /// * The pointer is not aligned - /// * The pointer is null - /// * The pointed-to range is not in user memory - pub unsafe fn from_mut_ptr<'a>(ptr: *mut T) -> &'a mut Self { - // SAFETY: The caller must uphold the safety contract for `from_mut_ptr`. - unsafe { T::check_ptr(ptr) }; - unsafe { &mut *(ptr as *mut Self) } - } - - /// Copies `val` into user memory. - /// - /// # Panics - /// This function panics if the destination doesn't have the same size as - /// the source. This can happen for dynamically-sized types such as slices. - pub fn copy_from_enclave(&mut self, val: &T) { - unsafe { - assert_eq!(mem::size_of_val(val), mem::size_of_val(&*self.0.get())); - copy_to_userspace( - val as *const T as *const u8, - self.0.get() as *mut T as *mut u8, - mem::size_of_val(val), - ); - } - } - - /// Copies the value from user memory and place it into `dest`. - /// - /// # Panics - /// This function panics if the destination doesn't have the same size as - /// the source. This can happen for dynamically-sized types such as slices. - pub fn copy_to_enclave(&self, dest: &mut T) { - unsafe { - assert_eq!(mem::size_of_val(dest), mem::size_of_val(&*self.0.get())); - copy_from_userspace( - self.0.get() as *const T as *const u8, - dest as *mut T as *mut u8, - mem::size_of_val(dest), - ); - } - } - - /// Obtain a raw pointer from this reference. - pub fn as_raw_ptr(&self) -> *const T { - self as *const _ as _ - } - - /// Obtain a raw pointer from this reference. - pub fn as_raw_mut_ptr(&mut self) -> *mut T { - self as *mut _ as _ - } -} - -#[unstable(feature = "sgx_platform", issue = "56975")] -impl UserRef -where - T: UserSafe, -{ - /// Copies the value from user memory into enclave memory. - pub fn to_enclave(&self) -> T { - unsafe { - let mut data = mem::MaybeUninit::uninit(); - copy_from_userspace(self.0.get() as _, data.as_mut_ptr() as _, mem::size_of::()); - data.assume_init() - } - } -} - -#[unstable(feature = "sgx_platform", issue = "56975")] -impl UserRef<[T]> -where - [T]: UserSafe, -{ - /// Creates a `&UserRef<[T]>` from a raw thin pointer and a slice length. - /// - /// # Safety - /// The caller must ensure `ptr` points to `n` elements of `T`. - /// - /// # Panics - /// This function panics if: - /// - /// * The pointer is not aligned - /// * The pointer is null - /// * The pointed-to range does not fit in the address space - /// * The pointed-to range is not in user memory - pub unsafe fn from_raw_parts<'a>(ptr: *const T, len: usize) -> &'a Self { - // SAFETY: The caller must uphold the safety contract for `from_raw_parts`. - unsafe { - &*(<[T]>::from_raw_sized(ptr as _, len * mem::size_of::()).as_ptr() as *const Self) - } - } - - /// Creates a `&mut UserRef<[T]>` from a raw thin pointer and a slice length. - /// See the struct documentation for the nuances regarding a - /// `&mut UserRef`. - /// - /// # Safety - /// The caller must ensure `ptr` points to `n` elements of `T`. - /// - /// # Panics - /// This function panics if: - /// - /// * The pointer is not aligned - /// * The pointer is null - /// * The pointed-to range does not fit in the address space - /// * The pointed-to range is not in user memory - pub unsafe fn from_raw_parts_mut<'a>(ptr: *mut T, len: usize) -> &'a mut Self { - // SAFETY: The caller must uphold the safety contract for `from_raw_parts_mut`. - unsafe { - &mut *(<[T]>::from_raw_sized(ptr as _, len * mem::size_of::()).as_ptr() as *mut Self) - } - } - - /// Obtain a raw pointer to the first element of this user slice. - pub fn as_ptr(&self) -> *const T { - self.0.get() as _ - } - - /// Obtain a raw pointer to the first element of this user slice. - pub fn as_mut_ptr(&mut self) -> *mut T { - self.0.get() as _ - } - - /// Obtain the number of elements in this user slice. - pub fn len(&self) -> usize { - unsafe { (*self.0.get()).len() } - } - - /// Copies the value from user memory and place it into `dest`. Afterwards, - /// `dest` will contain exactly `self.len()` elements. - /// - /// # Panics - /// This function panics if the destination doesn't have the same size as - /// the source. This can happen for dynamically-sized types such as slices. - pub fn copy_to_enclave_vec(&self, dest: &mut Vec) { - if let Some(missing) = self.len().checked_sub(dest.capacity()) { - dest.reserve(missing) - } - // SAFETY: We reserve enough space above. - unsafe { dest.set_len(self.len()) }; - self.copy_to_enclave(&mut dest[..]); - } - - /// Copies the value from user memory into a vector in enclave memory. - pub fn to_enclave(&self) -> Vec { - let mut ret = Vec::with_capacity(self.len()); - self.copy_to_enclave_vec(&mut ret); - ret - } - - /// Returns an iterator over the slice. - pub fn iter(&self) -> Iter<'_, T> - where - T: UserSafe, // FIXME: should be implied by [T]: UserSafe? - { - unsafe { Iter((&*self.as_raw_ptr()).iter()) } - } - - /// Returns an iterator that allows modifying each value. - pub fn iter_mut(&mut self) -> IterMut<'_, T> - where - T: UserSafe, // FIXME: should be implied by [T]: UserSafe? - { - unsafe { IterMut((&mut *self.as_raw_mut_ptr()).iter_mut()) } - } -} - -/// Immutable user slice iterator -/// -/// This struct is created by the `iter` method on `UserRef<[T]>`. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub struct Iter<'a, T: 'a + UserSafe>(slice::Iter<'a, T>); - -#[unstable(feature = "sgx_platform", issue = "56975")] -impl<'a, T: UserSafe> Iterator for Iter<'a, T> { - type Item = &'a UserRef; - - #[inline] - fn next(&mut self) -> Option { - unsafe { self.0.next().map(|e| UserRef::from_ptr(e)) } - } -} - -/// Mutable user slice iterator -/// -/// This struct is created by the `iter_mut` method on `UserRef<[T]>`. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub struct IterMut<'a, T: 'a + UserSafe>(slice::IterMut<'a, T>); - -#[unstable(feature = "sgx_platform", issue = "56975")] -impl<'a, T: UserSafe> Iterator for IterMut<'a, T> { - type Item = &'a mut UserRef; - - #[inline] - fn next(&mut self) -> Option { - unsafe { self.0.next().map(|e| UserRef::from_mut_ptr(e)) } - } -} - -#[unstable(feature = "sgx_platform", issue = "56975")] -impl Deref for User -where - T: UserSafe, -{ - type Target = UserRef; - - fn deref(&self) -> &Self::Target { - unsafe { &*self.0.as_ptr() } - } -} - -#[unstable(feature = "sgx_platform", issue = "56975")] -impl DerefMut for User -where - T: UserSafe, -{ - fn deref_mut(&mut self) -> &mut Self::Target { - unsafe { &mut *self.0.as_ptr() } - } -} - -#[unstable(feature = "sgx_platform", issue = "56975")] -impl Drop for User -where - T: UserSafe, -{ - fn drop(&mut self) { - unsafe { - let ptr = (*self.0.as_ptr()).0.get(); - super::free(ptr as _, mem::size_of_val(&mut *ptr), T::align_of()); - } - } -} - -#[unstable(feature = "sgx_platform", issue = "56975")] -impl, U> CoerceUnsized> for UserRef {} - -#[unstable(feature = "sgx_platform", issue = "56975")] -impl Index for UserRef<[T]> -where - [T]: UserSafe, - I: SliceIndex<[T]>, - I::Output: UserSafe, -{ - type Output = UserRef; - - #[inline] - fn index(&self, index: I) -> &UserRef { - unsafe { - if let Some(slice) = index.get(&*self.as_raw_ptr()) { - UserRef::from_ptr(slice) - } else { - rtabort!("index out of range for user slice"); - } - } - } -} - -#[unstable(feature = "sgx_platform", issue = "56975")] -impl IndexMut for UserRef<[T]> -where - [T]: UserSafe, - I: SliceIndex<[T]>, - I::Output: UserSafe, -{ - #[inline] - fn index_mut(&mut self, index: I) -> &mut UserRef { - unsafe { - if let Some(slice) = index.get_mut(&mut *self.as_raw_mut_ptr()) { - UserRef::from_mut_ptr(slice) - } else { - rtabort!("index out of range for user slice"); - } - } - } -} - -#[unstable(feature = "sgx_platform", issue = "56975")] -impl UserRef { - /// Copies the user memory range pointed to by the user `ByteBuffer` to - /// enclave memory. - /// - /// # Panics - /// This function panics if, in the user `ByteBuffer`: - /// - /// * The pointer is null - /// * The pointed-to range does not fit in the address space - /// * The pointed-to range is not in user memory - pub fn copy_user_buffer(&self) -> Vec { - unsafe { - let buf = self.to_enclave(); - if buf.len > 0 { - User::from_raw_parts(buf.data as _, buf.len).to_enclave() - } else { - // Mustn't look at `data` or call `free` if `len` is `0`. - Vec::with_capacity(0) - } - } - } -} diff --git a/library/std/src/sys/pal/sgx/abi/usercalls/mod.rs b/library/std/src/sys/pal/sgx/abi/usercalls/mod.rs deleted file mode 100644 index e19e843267a90..0000000000000 --- a/library/std/src/sys/pal/sgx/abi/usercalls/mod.rs +++ /dev/null @@ -1,329 +0,0 @@ -use crate::cmp; -use crate::io::{Error as IoError, ErrorKind, IoSlice, IoSliceMut, Result as IoResult}; -use crate::sys::rand::rdrand64; -use crate::time::{Duration, Instant}; - -pub(crate) mod alloc; -#[macro_use] -pub(crate) mod raw; -#[cfg(test)] -mod tests; - -use self::raw::*; - -/// Usercall `read`. See the ABI documentation for more information. -/// -/// This will do a single `read` usercall and scatter the read data among -/// `bufs`. To read to a single buffer, just pass a slice of length one. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub fn read(fd: Fd, bufs: &mut [IoSliceMut<'_>]) -> IoResult { - unsafe { - let total_len = bufs.iter().fold(0usize, |sum, buf| sum.saturating_add(buf.len())); - let mut userbuf = alloc::User::<[u8]>::uninitialized(total_len); - let ret_len = raw::read(fd, userbuf.as_mut_ptr(), userbuf.len()).from_sgx_result()?; - let userbuf = &userbuf[..ret_len]; - let mut index = 0; - for buf in bufs { - let end = cmp::min(index + buf.len(), userbuf.len()); - if let Some(buflen) = end.checked_sub(index) { - userbuf[index..end].copy_to_enclave(&mut buf[..buflen]); - index += buf.len(); - } else { - break; - } - } - Ok(userbuf.len()) - } -} - -/// Usercall `read_alloc`. See the ABI documentation for more information. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub fn read_alloc(fd: Fd) -> IoResult> { - unsafe { - let userbuf = ByteBuffer { data: crate::ptr::null_mut(), len: 0 }; - let mut userbuf = alloc::User::new_from_enclave(&userbuf); - raw::read_alloc(fd, userbuf.as_raw_mut_ptr()).from_sgx_result()?; - Ok(userbuf.copy_user_buffer()) - } -} - -/// Usercall `write`. See the ABI documentation for more information. -/// -/// This will do a single `write` usercall and gather the written data from -/// `bufs`. To write from a single buffer, just pass a slice of length one. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub fn write(fd: Fd, bufs: &[IoSlice<'_>]) -> IoResult { - unsafe { - let total_len = bufs.iter().fold(0usize, |sum, buf| sum.saturating_add(buf.len())); - let mut userbuf = alloc::User::<[u8]>::uninitialized(total_len); - let mut index = 0; - for buf in bufs { - let end = cmp::min(index + buf.len(), userbuf.len()); - if let Some(buflen) = end.checked_sub(index) { - userbuf[index..end].copy_from_enclave(&buf[..buflen]); - index += buf.len(); - } else { - break; - } - } - raw::write(fd, userbuf.as_ptr(), userbuf.len()).from_sgx_result() - } -} - -/// Usercall `flush`. See the ABI documentation for more information. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub fn flush(fd: Fd) -> IoResult<()> { - unsafe { raw::flush(fd).from_sgx_result() } -} - -/// Usercall `close`. See the ABI documentation for more information. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub fn close(fd: Fd) { - unsafe { raw::close(fd) } -} - -fn string_from_bytebuffer(buf: &alloc::UserRef, usercall: &str, arg: &str) -> String { - String::from_utf8(buf.copy_user_buffer()) - .unwrap_or_else(|_| rtabort!("Usercall {usercall}: expected {arg} to be valid UTF-8")) -} - -/// Usercall `bind_stream`. See the ABI documentation for more information. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub fn bind_stream(addr: &str) -> IoResult<(Fd, String)> { - unsafe { - let addr_user = alloc::User::new_from_enclave(addr.as_bytes()); - let mut local = alloc::User::::uninitialized(); - let fd = raw::bind_stream(addr_user.as_ptr(), addr_user.len(), local.as_raw_mut_ptr()) - .from_sgx_result()?; - let local = string_from_bytebuffer(&local, "bind_stream", "local_addr"); - Ok((fd, local)) - } -} - -/// Usercall `accept_stream`. See the ABI documentation for more information. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub fn accept_stream(fd: Fd) -> IoResult<(Fd, String, String)> { - unsafe { - let mut bufs = alloc::User::<[ByteBuffer; 2]>::uninitialized(); - let mut buf_it = alloc::UserRef::iter_mut(&mut *bufs); // FIXME: can this be done - // without forcing coercion? - let (local, peer) = (buf_it.next().unwrap(), buf_it.next().unwrap()); - let fd = raw::accept_stream(fd, local.as_raw_mut_ptr(), peer.as_raw_mut_ptr()) - .from_sgx_result()?; - let local = string_from_bytebuffer(&local, "accept_stream", "local_addr"); - let peer = string_from_bytebuffer(&peer, "accept_stream", "peer_addr"); - Ok((fd, local, peer)) - } -} - -/// Usercall `connect_stream`. See the ABI documentation for more information. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub fn connect_stream(addr: &str) -> IoResult<(Fd, String, String)> { - unsafe { - let addr_user = alloc::User::new_from_enclave(addr.as_bytes()); - let mut bufs = alloc::User::<[ByteBuffer; 2]>::uninitialized(); - let mut buf_it = alloc::UserRef::iter_mut(&mut *bufs); // FIXME: can this be done - // without forcing coercion? - let (local, peer) = (buf_it.next().unwrap(), buf_it.next().unwrap()); - let fd = raw::connect_stream( - addr_user.as_ptr(), - addr_user.len(), - local.as_raw_mut_ptr(), - peer.as_raw_mut_ptr(), - ) - .from_sgx_result()?; - let local = string_from_bytebuffer(&local, "connect_stream", "local_addr"); - let peer = string_from_bytebuffer(&peer, "connect_stream", "peer_addr"); - Ok((fd, local, peer)) - } -} - -/// Usercall `launch_thread`. See the ABI documentation for more information. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub unsafe fn launch_thread() -> IoResult<()> { - // SAFETY: The caller must uphold the safety contract for `launch_thread`. - unsafe { raw::launch_thread().from_sgx_result() } -} - -/// Usercall `exit`. See the ABI documentation for more information. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub fn exit(panic: bool) -> ! { - unsafe { raw::exit(panic) } -} - -/// Usercall `wait`. See the ABI documentation for more information. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub fn wait(event_mask: u64, mut timeout: u64) -> IoResult { - if timeout != WAIT_NO && timeout != WAIT_INDEFINITE { - // We don't want people to rely on accuracy of timeouts to make - // security decisions in an SGX enclave. That's why we add a random - // amount not exceeding +/- 10% to the timeout value to discourage - // people from relying on accuracy of timeouts while providing a way - // to make things work in other cases. Note that in the SGX threat - // model the enclave runner which is serving the wait usercall is not - // trusted to ensure accurate timeouts. - if let Ok(timeout_signed) = i64::try_from(timeout) { - let tenth = timeout_signed / 10; - let deviation = (rdrand64() as i64).checked_rem(tenth).unwrap_or(0); - timeout = timeout_signed.saturating_add(deviation) as _; - } - } - unsafe { raw::wait(event_mask, timeout).from_sgx_result() } -} - -/// This function makes an effort to wait for a non-spurious event at least as -/// long as `duration`. Note that in general there is no guarantee about accuracy -/// of time and timeouts in SGX model. The enclave runner serving usercalls may -/// lie about current time and/or ignore timeout values. -/// -/// Once the event is observed, `should_wake_up` will be used to determine -/// whether or not the event was spurious. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub fn wait_timeout(event_mask: u64, duration: Duration, should_wake_up: F) -where - F: Fn() -> bool, -{ - // Calls the wait usercall and checks the result. Returns true if event was - // returned, and false if WouldBlock/TimedOut was returned. - // If duration is None, it will use WAIT_NO. - fn wait_checked(event_mask: u64, duration: Option) -> bool { - let timeout = duration.map_or(raw::WAIT_NO, |duration| { - cmp::min((u64::MAX - 1) as u128, duration.as_nanos()) as u64 - }); - match wait(event_mask, timeout) { - Ok(eventset) => { - if event_mask == 0 { - rtabort!("expected wait() to return Err, found Ok."); - } - rtassert!(eventset != 0 && eventset & !event_mask == 0); - true - } - Err(e) => { - rtassert!(e.kind() == ErrorKind::TimedOut || e.kind() == ErrorKind::WouldBlock); - false - } - } - } - - match wait_checked(event_mask, Some(duration)) { - false => return, // timed out - true if should_wake_up() => return, // woken up - true => {} // spurious event - } - - // Drain all cached events. - // Note that `event_mask != 0` is implied if we get here. - loop { - match wait_checked(event_mask, None) { - false => break, // no more cached events - true if should_wake_up() => return, // woken up - true => {} // spurious event - } - } - - // Continue waiting, but take note of time spent waiting so we don't wait - // forever. We intentionally don't call `Instant::now()` before this point - // to avoid the cost of the `insecure_time` usercall in case there are no - // spurious wakeups. - - let start = Instant::now(); - let mut remaining = duration; - loop { - match wait_checked(event_mask, Some(remaining)) { - false => return, // timed out - true if should_wake_up() => return, // woken up - true => {} // spurious event - } - remaining = match duration.checked_sub(start.elapsed()) { - Some(remaining) => remaining, - None => break, - } - } -} - -/// Usercall `send`. See the ABI documentation for more information. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub fn send(event_set: u64, tcs: Option) -> IoResult<()> { - unsafe { raw::send(event_set, tcs).from_sgx_result() } -} - -/// Usercall `insecure_time`. See the ABI documentation for more information. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub fn insecure_time() -> Duration { - let t = unsafe { raw::insecure_time() }; - Duration::new(t / 1_000_000_000, (t % 1_000_000_000) as _) -} - -/// Usercall `alloc`. See the ABI documentation for more information. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub fn alloc(size: usize, alignment: usize) -> IoResult<*mut u8> { - unsafe { raw::alloc(size, alignment).from_sgx_result() } -} - -#[unstable(feature = "sgx_platform", issue = "56975")] -#[doc(inline)] -pub use self::raw::free; - -fn check_os_error(err: Result) -> i32 { - // FIXME: not sure how to make sure all variants of Error are covered - if err == Error::NotFound as _ - || err == Error::PermissionDenied as _ - || err == Error::ConnectionRefused as _ - || err == Error::ConnectionReset as _ - || err == Error::ConnectionAborted as _ - || err == Error::NotConnected as _ - || err == Error::AddrInUse as _ - || err == Error::AddrNotAvailable as _ - || err == Error::BrokenPipe as _ - || err == Error::AlreadyExists as _ - || err == Error::WouldBlock as _ - || err == Error::InvalidInput as _ - || err == Error::InvalidData as _ - || err == Error::TimedOut as _ - || err == Error::WriteZero as _ - || err == Error::Interrupted as _ - || err == Error::Other as _ - || err == Error::UnexpectedEof as _ - || ((Error::UserRangeStart as _)..=(Error::UserRangeEnd as _)).contains(&err) - { - err - } else { - rtabort!("Usercall: returned invalid error value {err}") - } -} - -/// Translate the raw result of an SGX usercall. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub trait FromSgxResult { - /// Return type - type Return; - - /// Translate the raw result of an SGX usercall. - fn from_sgx_result(self) -> IoResult; -} - -#[unstable(feature = "sgx_platform", issue = "56975")] -impl FromSgxResult for (Result, T) { - type Return = T; - - fn from_sgx_result(self) -> IoResult { - if self.0 == RESULT_SUCCESS { - Ok(self.1) - } else { - Err(IoError::from_raw_os_error(check_os_error(self.0))) - } - } -} - -#[unstable(feature = "sgx_platform", issue = "56975")] -impl FromSgxResult for Result { - type Return = (); - - fn from_sgx_result(self) -> IoResult { - if self == RESULT_SUCCESS { - Ok(()) - } else { - Err(IoError::from_raw_os_error(check_os_error(self))) - } - } -} diff --git a/library/std/src/sys/pal/sgx/abi/usercalls/raw.rs b/library/std/src/sys/pal/sgx/abi/usercalls/raw.rs deleted file mode 100644 index 943b771498f8f..0000000000000 --- a/library/std/src/sys/pal/sgx/abi/usercalls/raw.rs +++ /dev/null @@ -1,270 +0,0 @@ -#![allow(unused)] - -#[unstable(feature = "sgx_platform", issue = "56975")] -pub use fortanix_sgx_abi::*; - -use crate::num::NonZero; -use crate::ptr::NonNull; - -#[repr(C)] -struct UsercallReturn(u64, u64); - -extern "C" { - fn usercall(nr: NonZero, p1: u64, p2: u64, abort: u64, p3: u64, p4: u64) - -> UsercallReturn; -} - -/// Performs the raw usercall operation as defined in the ABI calling convention. -/// -/// # Safety -/// -/// The caller must ensure to pass parameters appropriate for the usercall `nr` -/// and to observe all requirements specified in the ABI. -/// -/// # Panics -/// -/// Panics if `nr` is `0`. -#[unstable(feature = "sgx_platform", issue = "56975")] -#[inline] -pub unsafe fn do_usercall( - nr: NonZero, - p1: u64, - p2: u64, - p3: u64, - p4: u64, - abort: bool, -) -> (u64, u64) { - let UsercallReturn(a, b) = unsafe { usercall(nr, p1, p2, abort as _, p3, p4) }; - (a, b) -} - -/// A value passed or returned in a CPU register. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub type Register = u64; - -/// Translate a type from/to Register to be used as an argument. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub trait RegisterArgument { - /// Translate a Register to Self. - fn from_register(_: Register) -> Self; - /// Translate self to a Register. - fn into_register(self) -> Register; -} - -/// Translate a pair of Registers to the raw usercall return value. -#[unstable(feature = "sgx_platform", issue = "56975")] -pub trait ReturnValue { - /// Translate a pair of Registers to the raw usercall return value. - fn from_registers(call: &'static str, regs: (Register, Register)) -> Self; -} - -macro_rules! define_usercalls { - ($(fn $f:ident($($n:ident: $t:ty),*) $(-> $r:tt)*; )*) => { - /// Usercall numbers as per the ABI. - #[repr(u64)] - #[unstable(feature = "sgx_platform", issue = "56975")] - #[derive(Copy, Clone, Hash, PartialEq, Eq, Debug)] - #[allow(missing_docs, non_camel_case_types)] - #[non_exhaustive] - pub enum Usercalls { - #[doc(hidden)] - __enclave_usercalls_invalid = 0, - $($f,)* - } - - $(enclave_usercalls_internal_define_usercalls!(def fn $f($($n: $t),*) $(-> $r)*);)* - }; -} - -macro_rules! define_ra { - (< $i:ident > $t:ty) => { - #[unstable(feature = "sgx_platform", issue = "56975")] - impl<$i> RegisterArgument for $t { - fn from_register(a: Register) -> Self { - a as _ - } - fn into_register(self) -> Register { - self as _ - } - } - }; - ($i:ty as $t:ty) => { - #[unstable(feature = "sgx_platform", issue = "56975")] - impl RegisterArgument for $t { - fn from_register(a: Register) -> Self { - a as $i as _ - } - fn into_register(self) -> Register { - self as $i as _ - } - } - }; - ($t:ty) => { - #[unstable(feature = "sgx_platform", issue = "56975")] - impl RegisterArgument for $t { - fn from_register(a: Register) -> Self { - a as _ - } - fn into_register(self) -> Register { - self as _ - } - } - }; -} - -define_ra!(Register); -define_ra!(i64); -define_ra!(u32); -define_ra!(u32 as i32); -define_ra!(u16); -define_ra!(u16 as i16); -define_ra!(u8); -define_ra!(u8 as i8); -define_ra!(usize); -define_ra!(usize as isize); -define_ra!( *const T); -define_ra!( *mut T); - -#[unstable(feature = "sgx_platform", issue = "56975")] -impl RegisterArgument for bool { - fn from_register(a: Register) -> bool { - if a != 0 { true } else { false } - } - fn into_register(self) -> Register { - self as _ - } -} - -#[unstable(feature = "sgx_platform", issue = "56975")] -impl RegisterArgument for Option> { - fn from_register(a: Register) -> Option> { - NonNull::new(a as _) - } - fn into_register(self) -> Register { - self.map_or(0 as _, NonNull::as_ptr) as _ - } -} - -#[unstable(feature = "sgx_platform", issue = "56975")] -impl ReturnValue for ! { - fn from_registers(call: &'static str, _regs: (Register, Register)) -> Self { - rtabort!("Usercall {call}: did not expect to be re-entered"); - } -} - -#[unstable(feature = "sgx_platform", issue = "56975")] -impl ReturnValue for () { - fn from_registers(call: &'static str, usercall_retval: (Register, Register)) -> Self { - rtassert!(usercall_retval.0 == 0); - rtassert!(usercall_retval.1 == 0); - () - } -} - -#[unstable(feature = "sgx_platform", issue = "56975")] -impl ReturnValue for T { - fn from_registers(call: &'static str, usercall_retval: (Register, Register)) -> Self { - rtassert!(usercall_retval.1 == 0); - T::from_register(usercall_retval.0) - } -} - -#[unstable(feature = "sgx_platform", issue = "56975")] -impl ReturnValue for (T, U) { - fn from_registers(_call: &'static str, regs: (Register, Register)) -> Self { - (T::from_register(regs.0), U::from_register(regs.1)) - } -} - -macro_rules! return_type_is_abort { - (!) => { - true - }; - ($r:ty) => { - false - }; -} - -// In this macro: using `$r:tt` because `$r:ty` doesn't match ! in `return_type_is_abort` -macro_rules! enclave_usercalls_internal_define_usercalls { - (def fn $f:ident($n1:ident: $t1:ty, $n2:ident: $t2:ty, - $n3:ident: $t3:ty, $n4:ident: $t4:ty) -> $r:tt) => ( - /// This is the raw function definition, see the ABI documentation for - /// more information. - #[unstable(feature = "sgx_platform", issue = "56975")] - #[inline(always)] - pub unsafe fn $f($n1: $t1, $n2: $t2, $n3: $t3, $n4: $t4) -> $r { - ReturnValue::from_registers(stringify!($f), unsafe { do_usercall( - rtunwrap!(Some, NonZero::new(Usercalls::$f as Register)), - RegisterArgument::into_register($n1), - RegisterArgument::into_register($n2), - RegisterArgument::into_register($n3), - RegisterArgument::into_register($n4), - return_type_is_abort!($r) - ) }) - } - ); - (def fn $f:ident($n1:ident: $t1:ty, $n2:ident: $t2:ty, $n3:ident: $t3:ty) -> $r:tt) => ( - /// This is the raw function definition, see the ABI documentation for - /// more information. - #[unstable(feature = "sgx_platform", issue = "56975")] - #[inline(always)] - pub unsafe fn $f($n1: $t1, $n2: $t2, $n3: $t3) -> $r { - ReturnValue::from_registers(stringify!($f), unsafe { do_usercall( - rtunwrap!(Some, NonZero::new(Usercalls::$f as Register)), - RegisterArgument::into_register($n1), - RegisterArgument::into_register($n2), - RegisterArgument::into_register($n3), - 0, - return_type_is_abort!($r) - ) }) - } - ); - (def fn $f:ident($n1:ident: $t1:ty, $n2:ident: $t2:ty) -> $r:tt) => ( - /// This is the raw function definition, see the ABI documentation for - /// more information. - #[unstable(feature = "sgx_platform", issue = "56975")] - #[inline(always)] - pub unsafe fn $f($n1: $t1, $n2: $t2) -> $r { - ReturnValue::from_registers(stringify!($f), unsafe { do_usercall( - rtunwrap!(Some, NonZero::new(Usercalls::$f as Register)), - RegisterArgument::into_register($n1), - RegisterArgument::into_register($n2), - 0,0, - return_type_is_abort!($r) - ) }) - } - ); - (def fn $f:ident($n1:ident: $t1:ty) -> $r:tt) => ( - /// This is the raw function definition, see the ABI documentation for - /// more information. - #[unstable(feature = "sgx_platform", issue = "56975")] - #[inline(always)] - pub unsafe fn $f($n1: $t1) -> $r { - ReturnValue::from_registers(stringify!($f), unsafe { do_usercall( - rtunwrap!(Some, NonZero::new(Usercalls::$f as Register)), - RegisterArgument::into_register($n1), - 0,0,0, - return_type_is_abort!($r) - ) }) - } - ); - (def fn $f:ident() -> $r:tt) => ( - /// This is the raw function definition, see the ABI documentation for - /// more information. - #[unstable(feature = "sgx_platform", issue = "56975")] - #[inline(always)] - pub unsafe fn $f() -> $r { - ReturnValue::from_registers(stringify!($f), unsafe { do_usercall( - rtunwrap!(Some, NonZero::new(Usercalls::$f as Register)), - 0,0,0,0, - return_type_is_abort!($r) - ) }) - } - ); - (def fn $f:ident($($n:ident: $t:ty),*)) => ( - enclave_usercalls_internal_define_usercalls!(def fn $f($($n: $t),*) -> ()); - ); -} - -invoke_with_usercalls!(define_usercalls); diff --git a/library/std/src/sys/pal/sgx/abi/usercalls/tests.rs b/library/std/src/sys/pal/sgx/abi/usercalls/tests.rs deleted file mode 100644 index 58b8eb215d73c..0000000000000 --- a/library/std/src/sys/pal/sgx/abi/usercalls/tests.rs +++ /dev/null @@ -1,56 +0,0 @@ -use super::alloc::User; -use super::alloc::{copy_from_userspace, copy_to_userspace}; - -#[test] -fn test_copy_to_userspace_function() { - let mut src = [0u8; 100]; - let mut dst = User::<[u8]>::uninitialized(100); - - for i in 0..src.len() { - src[i] = i as _; - } - - for size in 0..48 { - // For all possible alignment - for offset in 0..8 { - // overwrite complete dst - dst.copy_from_enclave(&[0u8; 100]); - - // Copy src[0..size] to dst + offset - unsafe { copy_to_userspace(src.as_ptr(), dst.as_mut_ptr().add(offset), size) }; - - // Verify copy - for byte in 0..size { - unsafe { - assert_eq!(*dst.as_ptr().add(offset + byte), src[byte as usize]); - } - } - } - } -} - -#[test] -fn test_copy_from_userspace_function() { - let mut dst = [0u8; 100]; - let mut src = User::<[u8]>::uninitialized(100); - - src.copy_from_enclave(&[0u8; 100]); - - for size in 0..48 { - // For all possible alignment - for offset in 0..8 { - // overwrite complete dst - dst = [0u8; 100]; - - // Copy src[0..size] to dst + offset - unsafe { copy_from_userspace(src.as_ptr().offset(offset), dst.as_mut_ptr(), size) }; - - // Verify copy - for byte in 0..size { - unsafe { - assert_eq!(dst[byte as usize], *src.as_ptr().offset(offset + byte as isize)); - } - } - } - } -} diff --git a/library/std/src/sys/pal/sgx/alloc.rs b/library/std/src/sys/pal/sgx/alloc.rs deleted file mode 100644 index 0c7bf9a9201f2..0000000000000 --- a/library/std/src/sys/pal/sgx/alloc.rs +++ /dev/null @@ -1,98 +0,0 @@ -use crate::alloc::{GlobalAlloc, Layout, System}; -use crate::ptr; -use core::sync::atomic::{AtomicBool, Ordering}; - -use super::abi::mem as sgx_mem; -use super::waitqueue::SpinMutex; - -// Using a SpinMutex because we never want to exit the enclave waiting for the -// allocator. -// -// The current allocator here is the `dlmalloc` crate which we've got included -// in the rust-lang/rust repository as a submodule. The crate is a port of -// dlmalloc.c from C to Rust. -#[cfg_attr(test, linkage = "available_externally")] -#[export_name = "_ZN16__rust_internals3std3sys3sgx5alloc8DLMALLOCE"] -static DLMALLOC: SpinMutex> = - SpinMutex::new(dlmalloc::Dlmalloc::new_with_allocator(Sgx {})); - -struct Sgx; - -unsafe impl dlmalloc::Allocator for Sgx { - /// Allocs system resources - fn alloc(&self, _size: usize) -> (*mut u8, usize, u32) { - static INIT: AtomicBool = AtomicBool::new(false); - - // No ordering requirement since this function is protected by the global lock. - if !INIT.swap(true, Ordering::Relaxed) { - (sgx_mem::heap_base() as _, sgx_mem::heap_size(), 0) - } else { - (ptr::null_mut(), 0, 0) - } - } - - fn remap(&self, _ptr: *mut u8, _oldsize: usize, _newsize: usize, _can_move: bool) -> *mut u8 { - ptr::null_mut() - } - - fn free_part(&self, _ptr: *mut u8, _oldsize: usize, _newsize: usize) -> bool { - false - } - - fn free(&self, _ptr: *mut u8, _size: usize) -> bool { - return false; - } - - fn can_release_part(&self, _flags: u32) -> bool { - false - } - - fn allocates_zeros(&self) -> bool { - false - } - - fn page_size(&self) -> usize { - 0x1000 - } -} - -#[stable(feature = "alloc_system_type", since = "1.28.0")] -unsafe impl GlobalAlloc for System { - #[inline] - unsafe fn alloc(&self, layout: Layout) -> *mut u8 { - // SAFETY: the caller must uphold the safety contract for `malloc` - unsafe { DLMALLOC.lock().malloc(layout.size(), layout.align()) } - } - - #[inline] - unsafe fn alloc_zeroed(&self, layout: Layout) -> *mut u8 { - // SAFETY: the caller must uphold the safety contract for `malloc` - unsafe { DLMALLOC.lock().calloc(layout.size(), layout.align()) } - } - - #[inline] - unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) { - // SAFETY: the caller must uphold the safety contract for `malloc` - unsafe { DLMALLOC.lock().free(ptr, layout.size(), layout.align()) } - } - - #[inline] - unsafe fn realloc(&self, ptr: *mut u8, layout: Layout, new_size: usize) -> *mut u8 { - // SAFETY: the caller must uphold the safety contract for `malloc` - unsafe { DLMALLOC.lock().realloc(ptr, layout.size(), layout.align(), new_size) } - } -} - -// The following functions are needed by libunwind. These symbols are named -// in pre-link args for the target specification, so keep that in sync. -#[cfg(not(test))] -#[no_mangle] -pub unsafe extern "C" fn __rust_c_alloc(size: usize, align: usize) -> *mut u8 { - unsafe { crate::alloc::alloc(Layout::from_size_align_unchecked(size, align)) } -} - -#[cfg(not(test))] -#[no_mangle] -pub unsafe extern "C" fn __rust_c_dealloc(ptr: *mut u8, size: usize, align: usize) { - unsafe { crate::alloc::dealloc(ptr, Layout::from_size_align_unchecked(size, align)) } -} diff --git a/library/std/src/sys/pal/sgx/args.rs b/library/std/src/sys/pal/sgx/args.rs deleted file mode 100644 index ef4176c4ac0f0..0000000000000 --- a/library/std/src/sys/pal/sgx/args.rs +++ /dev/null @@ -1,59 +0,0 @@ -use super::abi::usercalls::{alloc, raw::ByteBuffer}; -use crate::ffi::OsString; -use crate::fmt; -use crate::slice; -use crate::sync::atomic::{AtomicUsize, Ordering}; -use crate::sys::os_str::Buf; -use crate::sys_common::FromInner; - -#[cfg_attr(test, linkage = "available_externally")] -#[export_name = "_ZN16__rust_internals3std3sys3sgx4args4ARGSE"] -static ARGS: AtomicUsize = AtomicUsize::new(0); -type ArgsStore = Vec; - -#[cfg_attr(test, allow(dead_code))] -pub unsafe fn init(argc: isize, argv: *const *const u8) { - if argc != 0 { - let args = unsafe { alloc::User::<[ByteBuffer]>::from_raw_parts(argv as _, argc as _) }; - let args = args - .iter() - .map(|a| OsString::from_inner(Buf { inner: a.copy_user_buffer() })) - .collect::(); - ARGS.store(Box::into_raw(Box::new(args)) as _, Ordering::Relaxed); - } -} - -pub fn args() -> Args { - let args = unsafe { (ARGS.load(Ordering::Relaxed) as *const ArgsStore).as_ref() }; - if let Some(args) = args { Args(args.iter()) } else { Args([].iter()) } -} - -pub struct Args(slice::Iter<'static, OsString>); - -impl fmt::Debug for Args { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0.as_slice().fmt(f) - } -} - -impl Iterator for Args { - type Item = OsString; - fn next(&mut self) -> Option { - self.0.next().cloned() - } - fn size_hint(&self) -> (usize, Option) { - self.0.size_hint() - } -} - -impl ExactSizeIterator for Args { - fn len(&self) -> usize { - self.0.len() - } -} - -impl DoubleEndedIterator for Args { - fn next_back(&mut self) -> Option { - self.0.next_back().cloned() - } -} diff --git a/library/std/src/sys/pal/sgx/env.rs b/library/std/src/sys/pal/sgx/env.rs deleted file mode 100644 index 8043b7c5213a1..0000000000000 --- a/library/std/src/sys/pal/sgx/env.rs +++ /dev/null @@ -1,9 +0,0 @@ -pub mod os { - pub const FAMILY: &str = ""; - pub const OS: &str = ""; - pub const DLL_PREFIX: &str = ""; - pub const DLL_SUFFIX: &str = ".sgxs"; - pub const DLL_EXTENSION: &str = "sgxs"; - pub const EXE_SUFFIX: &str = ".sgxs"; - pub const EXE_EXTENSION: &str = "sgxs"; -} diff --git a/library/std/src/sys/pal/sgx/fd.rs b/library/std/src/sys/pal/sgx/fd.rs deleted file mode 100644 index b3686d0e28328..0000000000000 --- a/library/std/src/sys/pal/sgx/fd.rs +++ /dev/null @@ -1,89 +0,0 @@ -use fortanix_sgx_abi::Fd; - -use super::abi::usercalls; -use crate::io::{self, BorrowedCursor, IoSlice, IoSliceMut}; -use crate::mem; -use crate::sys::{AsInner, FromInner, IntoInner}; - -#[derive(Debug)] -pub struct FileDesc { - fd: Fd, -} - -impl FileDesc { - pub fn new(fd: Fd) -> FileDesc { - FileDesc { fd: fd } - } - - pub fn raw(&self) -> Fd { - self.fd - } - - /// Extracts the actual file descriptor without closing it. - pub fn into_raw(self) -> Fd { - let fd = self.fd; - mem::forget(self); - fd - } - - pub fn read(&self, buf: &mut [u8]) -> io::Result { - usercalls::read(self.fd, &mut [IoSliceMut::new(buf)]) - } - - pub fn read_buf(&self, buf: BorrowedCursor<'_>) -> io::Result<()> { - crate::io::default_read_buf(|b| self.read(b), buf) - } - - pub fn read_vectored(&self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - usercalls::read(self.fd, bufs) - } - - #[inline] - pub fn is_read_vectored(&self) -> bool { - true - } - - pub fn write(&self, buf: &[u8]) -> io::Result { - usercalls::write(self.fd, &[IoSlice::new(buf)]) - } - - pub fn write_vectored(&self, bufs: &[IoSlice<'_>]) -> io::Result { - usercalls::write(self.fd, bufs) - } - - #[inline] - pub fn is_write_vectored(&self) -> bool { - true - } - - pub fn flush(&self) -> io::Result<()> { - usercalls::flush(self.fd) - } -} - -impl AsInner for FileDesc { - #[inline] - fn as_inner(&self) -> &Fd { - &self.fd - } -} - -impl IntoInner for FileDesc { - fn into_inner(self) -> Fd { - let fd = self.fd; - mem::forget(self); - fd - } -} - -impl FromInner for FileDesc { - fn from_inner(fd: Fd) -> FileDesc { - FileDesc { fd } - } -} - -impl Drop for FileDesc { - fn drop(&mut self) { - usercalls::close(self.fd) - } -} diff --git a/library/std/src/sys/pal/sgx/libunwind_integration.rs b/library/std/src/sys/pal/sgx/libunwind_integration.rs deleted file mode 100644 index debfd324c864e..0000000000000 --- a/library/std/src/sys/pal/sgx/libunwind_integration.rs +++ /dev/null @@ -1,46 +0,0 @@ -//! The functions in this module are needed by libunwind. These symbols are named -//! in pre-link args for the target specification, so keep that in sync. - -#![cfg(not(test))] - -use crate::sys::sync::RwLock; - -// Verify that the byte pattern libunwind uses to initialize an RwLock is -// equivalent to the value of RwLock::new(). If the value changes, -// `src/UnwindRustSgx.h` in libunwind needs to be changed too. -const _: () = unsafe { - let bits_rust: usize = crate::mem::transmute(RwLock::new()); - assert!(bits_rust == 0); -}; - -const EINVAL: i32 = 22; - -#[no_mangle] -pub unsafe extern "C" fn __rust_rwlock_rdlock(p: *mut RwLock) -> i32 { - if p.is_null() { - return EINVAL; - } - - // We cannot differentiate between reads an writes in unlock and therefore - // always use a write-lock. Unwinding isn't really in the hot path anyway. - unsafe { (*p).write() }; - return 0; -} - -#[no_mangle] -pub unsafe extern "C" fn __rust_rwlock_wrlock(p: *mut RwLock) -> i32 { - if p.is_null() { - return EINVAL; - } - unsafe { (*p).write() }; - return 0; -} - -#[no_mangle] -pub unsafe extern "C" fn __rust_rwlock_unlock(p: *mut RwLock) -> i32 { - if p.is_null() { - return EINVAL; - } - unsafe { (*p).write_unlock() }; - return 0; -} diff --git a/library/std/src/sys/pal/sgx/mod.rs b/library/std/src/sys/pal/sgx/mod.rs deleted file mode 100644 index d30976ec15149..0000000000000 --- a/library/std/src/sys/pal/sgx/mod.rs +++ /dev/null @@ -1,159 +0,0 @@ -//! System bindings for the Fortanix SGX platform -//! -//! This module contains the facade (aka platform-specific) implementations of -//! OS level functionality for Fortanix SGX. -#![deny(unsafe_op_in_unsafe_fn)] -#![allow(fuzzy_provenance_casts)] // FIXME: this entire module systematically confuses pointers and integers - -use crate::io::ErrorKind; -use crate::sync::atomic::{AtomicBool, Ordering}; - -pub mod abi; -pub mod alloc; -pub mod args; -pub mod env; -pub mod fd; -#[path = "../unsupported/fs.rs"] -pub mod fs; -#[path = "../unsupported/io.rs"] -pub mod io; -mod libunwind_integration; -pub mod net; -pub mod os; -#[path = "../unsupported/pipe.rs"] -pub mod pipe; -#[path = "../unsupported/process.rs"] -pub mod process; -pub mod stdio; -pub mod thread; -pub mod thread_local_key; -pub mod thread_parking; -pub mod time; -pub mod waitqueue; - -// SAFETY: must be called only once during runtime initialization. -// NOTE: this is not guaranteed to run, for example when Rust code is called externally. -pub unsafe fn init(argc: isize, argv: *const *const u8, _sigpipe: u8) { - unsafe { - args::init(argc, argv); - } -} - -// SAFETY: must be called only once during runtime cleanup. -// NOTE: this is not guaranteed to run, for example when the program aborts. -pub unsafe fn cleanup() {} - -/// This function is used to implement functionality that simply doesn't exist. -/// Programs relying on this functionality will need to deal with the error. -pub fn unsupported() -> crate::io::Result { - Err(unsupported_err()) -} - -pub fn unsupported_err() -> crate::io::Error { - crate::io::const_io_error!(ErrorKind::Unsupported, "operation not supported on SGX yet") -} - -/// This function is used to implement various functions that doesn't exist, -/// but the lack of which might not be reason for error. If no error is -/// returned, the program might very well be able to function normally. This is -/// what happens when `SGX_INEFFECTIVE_ERROR` is set to `true`. If it is -/// `false`, the behavior is the same as `unsupported`. -pub fn sgx_ineffective(v: T) -> crate::io::Result { - static SGX_INEFFECTIVE_ERROR: AtomicBool = AtomicBool::new(false); - if SGX_INEFFECTIVE_ERROR.load(Ordering::Relaxed) { - Err(crate::io::const_io_error!( - ErrorKind::Uncategorized, - "operation can't be trusted to have any effect on SGX", - )) - } else { - Ok(v) - } -} - -#[inline] -pub fn is_interrupted(code: i32) -> bool { - use fortanix_sgx_abi::Error; - code == Error::Interrupted as _ -} - -pub fn decode_error_kind(code: i32) -> ErrorKind { - use fortanix_sgx_abi::Error; - - // FIXME: not sure how to make sure all variants of Error are covered - if code == Error::NotFound as _ { - ErrorKind::NotFound - } else if code == Error::PermissionDenied as _ { - ErrorKind::PermissionDenied - } else if code == Error::ConnectionRefused as _ { - ErrorKind::ConnectionRefused - } else if code == Error::ConnectionReset as _ { - ErrorKind::ConnectionReset - } else if code == Error::ConnectionAborted as _ { - ErrorKind::ConnectionAborted - } else if code == Error::NotConnected as _ { - ErrorKind::NotConnected - } else if code == Error::AddrInUse as _ { - ErrorKind::AddrInUse - } else if code == Error::AddrNotAvailable as _ { - ErrorKind::AddrNotAvailable - } else if code == Error::BrokenPipe as _ { - ErrorKind::BrokenPipe - } else if code == Error::AlreadyExists as _ { - ErrorKind::AlreadyExists - } else if code == Error::WouldBlock as _ { - ErrorKind::WouldBlock - } else if code == Error::InvalidInput as _ { - ErrorKind::InvalidInput - } else if code == Error::InvalidData as _ { - ErrorKind::InvalidData - } else if code == Error::TimedOut as _ { - ErrorKind::TimedOut - } else if code == Error::WriteZero as _ { - ErrorKind::WriteZero - } else if code == Error::Interrupted as _ { - ErrorKind::Interrupted - } else if code == Error::Other as _ { - ErrorKind::Uncategorized - } else if code == Error::UnexpectedEof as _ { - ErrorKind::UnexpectedEof - } else { - ErrorKind::Uncategorized - } -} - -pub fn abort_internal() -> ! { - abi::usercalls::exit(true) -} - -// This function is needed by the panic runtime. The symbol is named in -// pre-link args for the target specification, so keep that in sync. -#[cfg(not(test))] -#[no_mangle] -// NB. used by both libunwind and libpanic_abort -pub extern "C" fn __rust_abort() { - abort_internal(); -} - -pub mod rand { - pub fn rdrand64() -> u64 { - unsafe { - let mut ret: u64 = 0; - for _ in 0..10 { - if crate::arch::x86_64::_rdrand64_step(&mut ret) == 1 { - return ret; - } - } - rtabort!("Failed to obtain random data"); - } - } -} - -pub fn hashmap_random_keys() -> (u64, u64) { - (self::rand::rdrand64(), self::rand::rdrand64()) -} - -pub use crate::sys_common::{AsInner, FromInner, IntoInner}; - -pub trait TryIntoInner: Sized { - fn try_into_inner(self) -> Result; -} diff --git a/library/std/src/sys/pal/sgx/net.rs b/library/std/src/sys/pal/sgx/net.rs deleted file mode 100644 index 68a2d5eded2da..0000000000000 --- a/library/std/src/sys/pal/sgx/net.rs +++ /dev/null @@ -1,538 +0,0 @@ -use crate::error; -use crate::fmt; -use crate::io::{self, BorrowedCursor, IoSlice, IoSliceMut}; -use crate::net::{Ipv4Addr, Ipv6Addr, Shutdown, SocketAddr, ToSocketAddrs}; -use crate::sync::Arc; -use crate::sys::fd::FileDesc; -use crate::sys::{sgx_ineffective, unsupported, AsInner, FromInner, IntoInner, TryIntoInner}; -use crate::time::Duration; - -use super::abi::usercalls; - -const DEFAULT_FAKE_TTL: u32 = 64; - -#[derive(Debug, Clone)] -pub struct Socket { - inner: Arc, - local_addr: Option, -} - -impl Socket { - fn new(fd: usercalls::raw::Fd, local_addr: String) -> Socket { - Socket { inner: Arc::new(FileDesc::new(fd)), local_addr: Some(local_addr) } - } -} - -impl AsInner for Socket { - #[inline] - fn as_inner(&self) -> &FileDesc { - &self.inner - } -} - -impl TryIntoInner for Socket { - fn try_into_inner(self) -> Result { - let Socket { inner, local_addr } = self; - Arc::try_unwrap(inner).map_err(|inner| Socket { inner, local_addr }) - } -} - -impl FromInner<(FileDesc, Option)> for Socket { - fn from_inner((inner, local_addr): (FileDesc, Option)) -> Socket { - Socket { inner: Arc::new(inner), local_addr } - } -} - -#[derive(Clone)] -pub struct TcpStream { - inner: Socket, - peer_addr: Option, -} - -impl fmt::Debug for TcpStream { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let mut res = f.debug_struct("TcpStream"); - - if let Some(ref addr) = self.inner.local_addr { - res.field("addr", addr); - } - - if let Some(ref peer) = self.peer_addr { - res.field("peer", peer); - } - - res.field("fd", &self.inner.inner.as_inner()).finish() - } -} - -fn io_err_to_addr(result: io::Result<&SocketAddr>) -> io::Result { - match result { - Ok(saddr) => Ok(saddr.to_string()), - // need to downcast twice because io::Error::into_inner doesn't return the original - // value if the conversion fails - Err(e) => { - if e.get_ref().and_then(|e| e.downcast_ref::()).is_some() { - Ok(e.into_inner().unwrap().downcast::().unwrap().host) - } else { - Err(e) - } - } - } -} - -fn addr_to_sockaddr(addr: &Option) -> io::Result { - addr.as_ref() - .ok_or(io::ErrorKind::AddrNotAvailable)? - .to_socket_addrs() - // unwrap OK: if an iterator is returned, we're guaranteed to get exactly one entry - .map(|mut it| it.next().unwrap()) -} - -impl TcpStream { - pub fn connect(addr: io::Result<&SocketAddr>) -> io::Result { - let addr = io_err_to_addr(addr)?; - let (fd, local_addr, peer_addr) = usercalls::connect_stream(&addr)?; - Ok(TcpStream { inner: Socket::new(fd, local_addr), peer_addr: Some(peer_addr) }) - } - - pub fn connect_timeout(addr: &SocketAddr, dur: Duration) -> io::Result { - if dur == Duration::default() { - return Err(io::Error::ZERO_TIMEOUT); - } - Self::connect(Ok(addr)) // FIXME: ignoring timeout - } - - pub fn set_read_timeout(&self, dur: Option) -> io::Result<()> { - match dur { - Some(dur) if dur == Duration::default() => { - return Err(io::Error::ZERO_TIMEOUT); - } - _ => sgx_ineffective(()), - } - } - - pub fn set_write_timeout(&self, dur: Option) -> io::Result<()> { - match dur { - Some(dur) if dur == Duration::default() => { - return Err(io::Error::ZERO_TIMEOUT); - } - _ => sgx_ineffective(()), - } - } - - pub fn read_timeout(&self) -> io::Result> { - sgx_ineffective(None) - } - - pub fn write_timeout(&self) -> io::Result> { - sgx_ineffective(None) - } - - pub fn peek(&self, _: &mut [u8]) -> io::Result { - Ok(0) - } - - pub fn read(&self, buf: &mut [u8]) -> io::Result { - self.inner.inner.read(buf) - } - - pub fn read_buf(&self, buf: BorrowedCursor<'_>) -> io::Result<()> { - self.inner.inner.read_buf(buf) - } - - pub fn read_vectored(&self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - self.inner.inner.read_vectored(bufs) - } - - #[inline] - pub fn is_read_vectored(&self) -> bool { - self.inner.inner.is_read_vectored() - } - - pub fn write(&self, buf: &[u8]) -> io::Result { - self.inner.inner.write(buf) - } - - pub fn write_vectored(&self, bufs: &[IoSlice<'_>]) -> io::Result { - self.inner.inner.write_vectored(bufs) - } - - #[inline] - pub fn is_write_vectored(&self) -> bool { - self.inner.inner.is_write_vectored() - } - - pub fn peer_addr(&self) -> io::Result { - addr_to_sockaddr(&self.peer_addr) - } - - pub fn socket_addr(&self) -> io::Result { - addr_to_sockaddr(&self.inner.local_addr) - } - - pub fn shutdown(&self, _: Shutdown) -> io::Result<()> { - sgx_ineffective(()) - } - - pub fn duplicate(&self) -> io::Result { - Ok(self.clone()) - } - - pub fn set_linger(&self, _: Option) -> io::Result<()> { - sgx_ineffective(()) - } - - pub fn linger(&self) -> io::Result> { - sgx_ineffective(None) - } - - pub fn set_nodelay(&self, _: bool) -> io::Result<()> { - sgx_ineffective(()) - } - - pub fn nodelay(&self) -> io::Result { - sgx_ineffective(false) - } - - pub fn set_ttl(&self, _: u32) -> io::Result<()> { - sgx_ineffective(()) - } - - pub fn ttl(&self) -> io::Result { - sgx_ineffective(DEFAULT_FAKE_TTL) - } - - pub fn take_error(&self) -> io::Result> { - Ok(None) - } - - pub fn set_nonblocking(&self, _: bool) -> io::Result<()> { - sgx_ineffective(()) - } -} - -impl AsInner for TcpStream { - #[inline] - fn as_inner(&self) -> &Socket { - &self.inner - } -} - -// `Inner` includes `peer_addr` so that a `TcpStream` maybe correctly -// reconstructed if `Socket::try_into_inner` fails. -impl IntoInner<(Socket, Option)> for TcpStream { - fn into_inner(self) -> (Socket, Option) { - (self.inner, self.peer_addr) - } -} - -impl FromInner<(Socket, Option)> for TcpStream { - fn from_inner((inner, peer_addr): (Socket, Option)) -> TcpStream { - TcpStream { inner, peer_addr } - } -} - -#[derive(Clone)] -pub struct TcpListener { - inner: Socket, -} - -impl fmt::Debug for TcpListener { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let mut res = f.debug_struct("TcpListener"); - - if let Some(ref addr) = self.inner.local_addr { - res.field("addr", addr); - } - - res.field("fd", &self.inner.inner.as_inner()).finish() - } -} - -impl TcpListener { - pub fn bind(addr: io::Result<&SocketAddr>) -> io::Result { - let addr = io_err_to_addr(addr)?; - let (fd, local_addr) = usercalls::bind_stream(&addr)?; - Ok(TcpListener { inner: Socket::new(fd, local_addr) }) - } - - pub fn socket_addr(&self) -> io::Result { - addr_to_sockaddr(&self.inner.local_addr) - } - - pub fn accept(&self) -> io::Result<(TcpStream, SocketAddr)> { - let (fd, local_addr, peer_addr) = usercalls::accept_stream(self.inner.inner.raw())?; - let peer_addr = Some(peer_addr); - let ret_peer = addr_to_sockaddr(&peer_addr).unwrap_or_else(|_| ([0; 4], 0).into()); - Ok((TcpStream { inner: Socket::new(fd, local_addr), peer_addr }, ret_peer)) - } - - pub fn duplicate(&self) -> io::Result { - Ok(self.clone()) - } - - pub fn set_ttl(&self, _: u32) -> io::Result<()> { - sgx_ineffective(()) - } - - pub fn ttl(&self) -> io::Result { - sgx_ineffective(DEFAULT_FAKE_TTL) - } - - pub fn set_only_v6(&self, _: bool) -> io::Result<()> { - sgx_ineffective(()) - } - - pub fn only_v6(&self) -> io::Result { - sgx_ineffective(false) - } - - pub fn take_error(&self) -> io::Result> { - Ok(None) - } - - pub fn set_nonblocking(&self, _: bool) -> io::Result<()> { - sgx_ineffective(()) - } -} - -impl AsInner for TcpListener { - #[inline] - fn as_inner(&self) -> &Socket { - &self.inner - } -} - -impl IntoInner for TcpListener { - fn into_inner(self) -> Socket { - self.inner - } -} - -impl FromInner for TcpListener { - fn from_inner(inner: Socket) -> TcpListener { - TcpListener { inner } - } -} - -pub struct UdpSocket(!); - -impl UdpSocket { - pub fn bind(_: io::Result<&SocketAddr>) -> io::Result { - unsupported() - } - - pub fn peer_addr(&self) -> io::Result { - self.0 - } - - pub fn socket_addr(&self) -> io::Result { - self.0 - } - - pub fn recv_from(&self, _: &mut [u8]) -> io::Result<(usize, SocketAddr)> { - self.0 - } - - pub fn peek_from(&self, _: &mut [u8]) -> io::Result<(usize, SocketAddr)> { - self.0 - } - - pub fn send_to(&self, _: &[u8], _: &SocketAddr) -> io::Result { - self.0 - } - - pub fn duplicate(&self) -> io::Result { - self.0 - } - - pub fn set_read_timeout(&self, _: Option) -> io::Result<()> { - self.0 - } - - pub fn set_write_timeout(&self, _: Option) -> io::Result<()> { - self.0 - } - - pub fn read_timeout(&self) -> io::Result> { - self.0 - } - - pub fn write_timeout(&self) -> io::Result> { - self.0 - } - - pub fn set_broadcast(&self, _: bool) -> io::Result<()> { - self.0 - } - - pub fn broadcast(&self) -> io::Result { - self.0 - } - - pub fn set_multicast_loop_v4(&self, _: bool) -> io::Result<()> { - self.0 - } - - pub fn multicast_loop_v4(&self) -> io::Result { - self.0 - } - - pub fn set_multicast_ttl_v4(&self, _: u32) -> io::Result<()> { - self.0 - } - - pub fn multicast_ttl_v4(&self) -> io::Result { - self.0 - } - - pub fn set_multicast_loop_v6(&self, _: bool) -> io::Result<()> { - self.0 - } - - pub fn multicast_loop_v6(&self) -> io::Result { - self.0 - } - - pub fn join_multicast_v4(&self, _: &Ipv4Addr, _: &Ipv4Addr) -> io::Result<()> { - self.0 - } - - pub fn join_multicast_v6(&self, _: &Ipv6Addr, _: u32) -> io::Result<()> { - self.0 - } - - pub fn leave_multicast_v4(&self, _: &Ipv4Addr, _: &Ipv4Addr) -> io::Result<()> { - self.0 - } - - pub fn leave_multicast_v6(&self, _: &Ipv6Addr, _: u32) -> io::Result<()> { - self.0 - } - - pub fn set_ttl(&self, _: u32) -> io::Result<()> { - self.0 - } - - pub fn ttl(&self) -> io::Result { - self.0 - } - - pub fn take_error(&self) -> io::Result> { - self.0 - } - - pub fn set_nonblocking(&self, _: bool) -> io::Result<()> { - self.0 - } - - pub fn recv(&self, _: &mut [u8]) -> io::Result { - self.0 - } - - pub fn peek(&self, _: &mut [u8]) -> io::Result { - self.0 - } - - pub fn send(&self, _: &[u8]) -> io::Result { - self.0 - } - - pub fn connect(&self, _: io::Result<&SocketAddr>) -> io::Result<()> { - self.0 - } -} - -impl fmt::Debug for UdpSocket { - fn fmt(&self, _f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0 - } -} - -#[derive(Debug)] -pub struct NonIpSockAddr { - host: String, -} - -impl error::Error for NonIpSockAddr { - #[allow(deprecated)] - fn description(&self) -> &str { - "Failed to convert address to SocketAddr" - } -} - -impl fmt::Display for NonIpSockAddr { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "Failed to convert address to SocketAddr: {}", self.host) - } -} - -pub struct LookupHost(!); - -impl LookupHost { - fn new(host: String) -> io::Result { - Err(io::Error::new(io::ErrorKind::Uncategorized, NonIpSockAddr { host })) - } - - pub fn port(&self) -> u16 { - self.0 - } -} - -impl Iterator for LookupHost { - type Item = SocketAddr; - fn next(&mut self) -> Option { - self.0 - } -} - -impl TryFrom<&str> for LookupHost { - type Error = io::Error; - - fn try_from(v: &str) -> io::Result { - LookupHost::new(v.to_owned()) - } -} - -impl<'a> TryFrom<(&'a str, u16)> for LookupHost { - type Error = io::Error; - - fn try_from((host, port): (&'a str, u16)) -> io::Result { - LookupHost::new(format!("{host}:{port}")) - } -} - -#[allow(bad_style)] -pub mod netc { - pub const AF_INET: u8 = 0; - pub const AF_INET6: u8 = 1; - pub type sa_family_t = u8; - - #[derive(Copy, Clone)] - pub struct in_addr { - pub s_addr: u32, - } - - #[derive(Copy, Clone)] - pub struct sockaddr_in { - #[allow(dead_code)] - pub sin_family: sa_family_t, - pub sin_port: u16, - pub sin_addr: in_addr, - } - - #[derive(Copy, Clone)] - pub struct in6_addr { - pub s6_addr: [u8; 16], - } - - #[derive(Copy, Clone)] - pub struct sockaddr_in6 { - #[allow(dead_code)] - pub sin6_family: sa_family_t, - pub sin6_port: u16, - pub sin6_addr: in6_addr, - pub sin6_flowinfo: u32, - pub sin6_scope_id: u32, - } -} diff --git a/library/std/src/sys/pal/sgx/os.rs b/library/std/src/sys/pal/sgx/os.rs deleted file mode 100644 index 86f4c7d3d56d6..0000000000000 --- a/library/std/src/sys/pal/sgx/os.rs +++ /dev/null @@ -1,187 +0,0 @@ -use fortanix_sgx_abi::{Error, RESULT_SUCCESS}; - -use crate::collections::HashMap; -use crate::error::Error as StdError; -use crate::ffi::{OsStr, OsString}; -use crate::fmt; -use crate::io; -use crate::marker::PhantomData; -use crate::path::{self, PathBuf}; -use crate::str; -use crate::sync::atomic::{AtomicUsize, Ordering}; -use crate::sync::Mutex; -use crate::sync::Once; -use crate::sys::{decode_error_kind, sgx_ineffective, unsupported}; -use crate::vec; - -pub fn errno() -> i32 { - RESULT_SUCCESS -} - -pub fn error_string(errno: i32) -> String { - if errno == RESULT_SUCCESS { - "operation successful".into() - } else if ((Error::UserRangeStart as _)..=(Error::UserRangeEnd as _)).contains(&errno) { - format!("user-specified error {errno:08x}") - } else { - decode_error_kind(errno).as_str().into() - } -} - -pub fn getcwd() -> io::Result { - unsupported() -} - -pub fn chdir(_: &path::Path) -> io::Result<()> { - sgx_ineffective(()) -} - -pub struct SplitPaths<'a>(!, PhantomData<&'a ()>); - -pub fn split_paths(_unparsed: &OsStr) -> SplitPaths<'_> { - panic!("unsupported") -} - -impl<'a> Iterator for SplitPaths<'a> { - type Item = PathBuf; - fn next(&mut self) -> Option { - self.0 - } -} - -#[derive(Debug)] -pub struct JoinPathsError; - -pub fn join_paths(_paths: I) -> Result -where - I: Iterator, - T: AsRef, -{ - Err(JoinPathsError) -} - -impl fmt::Display for JoinPathsError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - "not supported in SGX yet".fmt(f) - } -} - -impl StdError for JoinPathsError { - #[allow(deprecated)] - fn description(&self) -> &str { - "not supported in SGX yet" - } -} - -pub fn current_exe() -> io::Result { - unsupported() -} - -#[cfg_attr(test, linkage = "available_externally")] -#[export_name = "_ZN16__rust_internals3std3sys3sgx2os3ENVE"] -static ENV: AtomicUsize = AtomicUsize::new(0); -#[cfg_attr(test, linkage = "available_externally")] -#[export_name = "_ZN16__rust_internals3std3sys3sgx2os8ENV_INITE"] -static ENV_INIT: Once = Once::new(); -type EnvStore = Mutex>; - -fn get_env_store() -> Option<&'static EnvStore> { - unsafe { (ENV.load(Ordering::Relaxed) as *const EnvStore).as_ref() } -} - -fn create_env_store() -> &'static EnvStore { - ENV_INIT.call_once(|| { - ENV.store(Box::into_raw(Box::new(EnvStore::default())) as _, Ordering::Relaxed) - }); - unsafe { &*(ENV.load(Ordering::Relaxed) as *const EnvStore) } -} - -pub struct Env { - iter: vec::IntoIter<(OsString, OsString)>, -} - -// FIXME(https://github.com/rust-lang/rust/issues/114583): Remove this when ::fmt matches ::fmt. -pub struct EnvStrDebug<'a> { - slice: &'a [(OsString, OsString)], -} - -impl fmt::Debug for EnvStrDebug<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let Self { slice } = self; - f.debug_list() - .entries(slice.iter().map(|(a, b)| (a.to_str().unwrap(), b.to_str().unwrap()))) - .finish() - } -} - -impl Env { - pub fn str_debug(&self) -> impl fmt::Debug + '_ { - let Self { iter } = self; - EnvStrDebug { slice: iter.as_slice() } - } -} - -impl fmt::Debug for Env { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let Self { iter } = self; - f.debug_list().entries(iter.as_slice()).finish() - } -} - -impl !Send for Env {} -impl !Sync for Env {} - -impl Iterator for Env { - type Item = (OsString, OsString); - fn next(&mut self) -> Option<(OsString, OsString)> { - self.iter.next() - } - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } -} - -pub fn env() -> Env { - let clone_to_vec = |map: &HashMap| -> Vec<_> { - map.iter().map(|(k, v)| (k.clone(), v.clone())).collect() - }; - - let iter = get_env_store() - .map(|env| clone_to_vec(&env.lock().unwrap())) - .unwrap_or_default() - .into_iter(); - Env { iter } -} - -pub fn getenv(k: &OsStr) -> Option { - get_env_store().and_then(|s| s.lock().unwrap().get(k).cloned()) -} - -pub fn setenv(k: &OsStr, v: &OsStr) -> io::Result<()> { - let (k, v) = (k.to_owned(), v.to_owned()); - create_env_store().lock().unwrap().insert(k, v); - Ok(()) -} - -pub fn unsetenv(k: &OsStr) -> io::Result<()> { - if let Some(env) = get_env_store() { - env.lock().unwrap().remove(k); - } - Ok(()) -} - -pub fn temp_dir() -> PathBuf { - panic!("no filesystem in SGX") -} - -pub fn home_dir() -> Option { - None -} - -pub fn exit(code: i32) -> ! { - super::abi::exit_with_code(code as _) -} - -pub fn getpid() -> u32 { - panic!("no pids in SGX") -} diff --git a/library/std/src/sys/pal/sgx/stdio.rs b/library/std/src/sys/pal/sgx/stdio.rs deleted file mode 100644 index 2e680e740fde3..0000000000000 --- a/library/std/src/sys/pal/sgx/stdio.rs +++ /dev/null @@ -1,88 +0,0 @@ -use fortanix_sgx_abi as abi; - -use crate::io; -#[cfg(not(test))] -use crate::slice; -#[cfg(not(test))] -use crate::str; -use crate::sys::fd::FileDesc; - -pub struct Stdin(()); -pub struct Stdout(()); -pub struct Stderr(()); - -fn with_std_fd R, R>(fd: abi::Fd, f: F) -> R { - let fd = FileDesc::new(fd); - let ret = f(&fd); - fd.into_raw(); - ret -} - -impl Stdin { - pub const fn new() -> Stdin { - Stdin(()) - } -} - -impl io::Read for Stdin { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - with_std_fd(abi::FD_STDIN, |fd| fd.read(buf)) - } -} - -impl Stdout { - pub const fn new() -> Stdout { - Stdout(()) - } -} - -impl io::Write for Stdout { - fn write(&mut self, buf: &[u8]) -> io::Result { - with_std_fd(abi::FD_STDOUT, |fd| fd.write(buf)) - } - - fn flush(&mut self) -> io::Result<()> { - with_std_fd(abi::FD_STDOUT, |fd| fd.flush()) - } -} - -impl Stderr { - pub const fn new() -> Stderr { - Stderr(()) - } -} - -impl io::Write for Stderr { - fn write(&mut self, buf: &[u8]) -> io::Result { - with_std_fd(abi::FD_STDERR, |fd| fd.write(buf)) - } - - fn flush(&mut self) -> io::Result<()> { - with_std_fd(abi::FD_STDERR, |fd| fd.flush()) - } -} - -pub const STDIN_BUF_SIZE: usize = crate::sys_common::io::DEFAULT_BUF_SIZE; - -pub fn is_ebadf(err: &io::Error) -> bool { - // FIXME: Rust normally maps Unix EBADF to `Uncategorized` - err.raw_os_error() == Some(abi::Error::BrokenPipe as _) -} - -pub fn panic_output() -> Option { - super::abi::panic::SgxPanicOutput::new() -} - -// This function is needed by libunwind. The symbol is named in pre-link args -// for the target specification, so keep that in sync. -#[cfg(not(test))] -#[no_mangle] -pub unsafe extern "C" fn __rust_print_err(m: *mut u8, s: i32) { - if s < 0 { - return; - } - let buf = unsafe { slice::from_raw_parts(m as *const u8, s as _) }; - if let Ok(s) = str::from_utf8(&buf[..buf.iter().position(|&b| b == 0).unwrap_or(buf.len())]) { - eprint!("{s}"); - } -} diff --git a/library/std/src/sys/pal/sgx/thread.rs b/library/std/src/sys/pal/sgx/thread.rs deleted file mode 100644 index 7d271e6d2b65d..0000000000000 --- a/library/std/src/sys/pal/sgx/thread.rs +++ /dev/null @@ -1,147 +0,0 @@ -#![cfg_attr(test, allow(dead_code))] // why is this necessary? -use super::unsupported; -use crate::ffi::CStr; -use crate::io; -use crate::num::NonZero; -use crate::time::Duration; - -use super::abi::usercalls; - -pub struct Thread(task_queue::JoinHandle); - -pub const DEFAULT_MIN_STACK_SIZE: usize = 4096; - -pub use self::task_queue::JoinNotifier; - -mod task_queue { - use super::wait_notify; - use crate::sync::{Mutex, MutexGuard, Once}; - - pub type JoinHandle = wait_notify::Waiter; - - pub struct JoinNotifier(Option); - - impl Drop for JoinNotifier { - fn drop(&mut self) { - self.0.take().unwrap().notify(); - } - } - - pub(super) struct Task { - p: Box, - done: JoinNotifier, - } - - impl Task { - pub(super) fn new(p: Box) -> (Task, JoinHandle) { - let (done, recv) = wait_notify::new(); - let done = JoinNotifier(Some(done)); - (Task { p, done }, recv) - } - - pub(super) fn run(self) -> JoinNotifier { - (self.p)(); - self.done - } - } - - #[cfg_attr(test, linkage = "available_externally")] - #[export_name = "_ZN16__rust_internals3std3sys3sgx6thread15TASK_QUEUE_INITE"] - static TASK_QUEUE_INIT: Once = Once::new(); - #[cfg_attr(test, linkage = "available_externally")] - #[export_name = "_ZN16__rust_internals3std3sys3sgx6thread10TASK_QUEUEE"] - static mut TASK_QUEUE: Option>> = None; - - pub(super) fn lock() -> MutexGuard<'static, Vec> { - unsafe { - TASK_QUEUE_INIT.call_once(|| TASK_QUEUE = Some(Default::default())); - TASK_QUEUE.as_ref().unwrap().lock().unwrap() - } - } -} - -/// This module provides a synchronization primitive that does not use thread -/// local variables. This is needed for signaling that a thread has finished -/// execution. The signal is sent once all TLS destructors have finished at -/// which point no new thread locals should be created. -pub mod wait_notify { - use crate::pin::Pin; - use crate::sync::Arc; - use crate::sys::sync::Parker; - - pub struct Notifier(Arc); - - impl Notifier { - /// Notify the waiter. The waiter is either notified right away (if - /// currently blocked in `Waiter::wait()`) or later when it calls the - /// `Waiter::wait()` method. - pub fn notify(self) { - Pin::new(&*self.0).unpark() - } - } - - pub struct Waiter(Arc); - - impl Waiter { - /// Wait for a notification. If `Notifier::notify()` has already been - /// called, this will return immediately, otherwise the current thread - /// is blocked until notified. - pub fn wait(self) { - // SAFETY: - // This is only ever called on one thread. - unsafe { Pin::new(&*self.0).park() } - } - } - - pub fn new() -> (Notifier, Waiter) { - let inner = Arc::new(Parker::new()); - (Notifier(inner.clone()), Waiter(inner)) - } -} - -impl Thread { - // unsafe: see thread::Builder::spawn_unchecked for safety requirements - pub unsafe fn new(_stack: usize, p: Box) -> io::Result { - let mut queue_lock = task_queue::lock(); - unsafe { usercalls::launch_thread()? }; - let (task, handle) = task_queue::Task::new(p); - queue_lock.push(task); - Ok(Thread(handle)) - } - - pub(super) fn entry() -> JoinNotifier { - let mut pending_tasks = task_queue::lock(); - let task = rtunwrap!(Some, pending_tasks.pop()); - drop(pending_tasks); // make sure to not hold the task queue lock longer than necessary - task.run() - } - - pub fn yield_now() { - let wait_error = rtunwrap!(Err, usercalls::wait(0, usercalls::raw::WAIT_NO)); - rtassert!(wait_error.kind() == io::ErrorKind::WouldBlock); - } - - /// SGX should protect in-enclave data from the outside (attacker), - /// so there should be no data leakage to the OS, - /// and therefore also no 1-1 mapping between SGX thread names and OS thread names. - /// - /// This is why the method is intentionally No-Op. - pub fn set_name(_name: &CStr) { - // Note that the internally visible SGX thread name is already provided - // by the platform-agnostic (target-agnostic) Rust thread code. - // This can be observed in the [`std::thread::tests::test_named_thread`] test, - // which succeeds as-is with the SGX target. - } - - pub fn sleep(dur: Duration) { - usercalls::wait_timeout(0, dur, || true); - } - - pub fn join(self) { - self.0.wait(); - } -} - -pub fn available_parallelism() -> io::Result> { - unsupported() -} diff --git a/library/std/src/sys/pal/sgx/thread_local_key.rs b/library/std/src/sys/pal/sgx/thread_local_key.rs deleted file mode 100644 index c7a57d3a3d47e..0000000000000 --- a/library/std/src/sys/pal/sgx/thread_local_key.rs +++ /dev/null @@ -1,23 +0,0 @@ -use super::abi::tls::{Key as AbiKey, Tls}; - -pub type Key = usize; - -#[inline] -pub unsafe fn create(dtor: Option) -> Key { - Tls::create(dtor).as_usize() -} - -#[inline] -pub unsafe fn set(key: Key, value: *mut u8) { - Tls::set(AbiKey::from_usize(key), value) -} - -#[inline] -pub unsafe fn get(key: Key) -> *mut u8 { - Tls::get(AbiKey::from_usize(key)) -} - -#[inline] -pub unsafe fn destroy(key: Key) { - Tls::destroy(AbiKey::from_usize(key)) -} diff --git a/library/std/src/sys/pal/sgx/thread_parking.rs b/library/std/src/sys/pal/sgx/thread_parking.rs deleted file mode 100644 index 0006cd4f1be25..0000000000000 --- a/library/std/src/sys/pal/sgx/thread_parking.rs +++ /dev/null @@ -1,23 +0,0 @@ -use super::abi::usercalls; -use crate::io::ErrorKind; -use crate::time::Duration; -use fortanix_sgx_abi::{EV_UNPARK, WAIT_INDEFINITE}; - -pub type ThreadId = fortanix_sgx_abi::Tcs; - -pub use super::abi::thread::current; - -pub fn park(_hint: usize) { - usercalls::wait(EV_UNPARK, WAIT_INDEFINITE).unwrap(); -} - -pub fn park_timeout(dur: Duration, _hint: usize) { - let timeout = u128::min(dur.as_nanos(), WAIT_INDEFINITE as u128 - 1) as u64; - if let Err(e) = usercalls::wait(EV_UNPARK, timeout) { - assert!(matches!(e.kind(), ErrorKind::TimedOut | ErrorKind::WouldBlock)) - } -} - -pub fn unpark(tid: ThreadId, _hint: usize) { - let _ = usercalls::send(EV_UNPARK, Some(tid)); -} diff --git a/library/std/src/sys/pal/sgx/time.rs b/library/std/src/sys/pal/sgx/time.rs deleted file mode 100644 index db4cf2804bf13..0000000000000 --- a/library/std/src/sys/pal/sgx/time.rs +++ /dev/null @@ -1,46 +0,0 @@ -use super::abi::usercalls; -use crate::time::Duration; - -#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)] -pub struct Instant(Duration); - -#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)] -pub struct SystemTime(Duration); - -pub const UNIX_EPOCH: SystemTime = SystemTime(Duration::from_secs(0)); - -impl Instant { - pub fn now() -> Instant { - Instant(usercalls::insecure_time()) - } - - pub fn checked_sub_instant(&self, other: &Instant) -> Option { - self.0.checked_sub(other.0) - } - - pub fn checked_add_duration(&self, other: &Duration) -> Option { - Some(Instant(self.0.checked_add(*other)?)) - } - - pub fn checked_sub_duration(&self, other: &Duration) -> Option { - Some(Instant(self.0.checked_sub(*other)?)) - } -} - -impl SystemTime { - pub fn now() -> SystemTime { - SystemTime(usercalls::insecure_time()) - } - - pub fn sub_time(&self, other: &SystemTime) -> Result { - self.0.checked_sub(other.0).ok_or_else(|| other.0 - self.0) - } - - pub fn checked_add_duration(&self, other: &Duration) -> Option { - Some(SystemTime(self.0.checked_add(*other)?)) - } - - pub fn checked_sub_duration(&self, other: &Duration) -> Option { - Some(SystemTime(self.0.checked_sub(*other)?)) - } -} diff --git a/library/std/src/sys/pal/sgx/waitqueue/mod.rs b/library/std/src/sys/pal/sgx/waitqueue/mod.rs deleted file mode 100644 index f5668a9493fb5..0000000000000 --- a/library/std/src/sys/pal/sgx/waitqueue/mod.rs +++ /dev/null @@ -1,244 +0,0 @@ -//! A simple queue implementation for synchronization primitives. -//! -//! This queue is used to implement condition variable and mutexes. -//! -//! Users of this API are expected to use the `WaitVariable` type. Since -//! that type is not `Sync`, it needs to be protected by e.g., a `SpinMutex` to -//! allow shared access. -//! -//! Since userspace may send spurious wake-ups, the wakeup event state is -//! recorded in the enclave. The wakeup event state is protected by a spinlock. -//! The queue and associated wait state are stored in a `WaitVariable`. - -#[cfg(test)] -mod tests; - -mod spin_mutex; -mod unsafe_list; - -use crate::num::NonZero; -use crate::ops::{Deref, DerefMut}; -use crate::panic::{self, AssertUnwindSafe}; -use crate::time::Duration; - -use super::abi::thread; -use super::abi::usercalls; -use fortanix_sgx_abi::{Tcs, EV_UNPARK, WAIT_INDEFINITE}; - -pub use self::spin_mutex::{try_lock_or_false, SpinMutex, SpinMutexGuard}; -use self::unsafe_list::{UnsafeList, UnsafeListEntry}; - -/// An queue entry in a `WaitQueue`. -struct WaitEntry { - /// TCS address of the thread that is waiting - tcs: Tcs, - /// Whether this thread has been notified to be awoken - wake: bool, -} - -/// Data stored with a `WaitQueue` alongside it. This ensures accesses to the -/// queue and the data are synchronized, since the type itself is not `Sync`. -/// -/// Consumers of this API should use a synchronization primitive for shared -/// access, such as `SpinMutex`. -#[derive(Default)] -pub struct WaitVariable { - queue: WaitQueue, - lock: T, -} - -impl WaitVariable { - pub const fn new(var: T) -> Self { - WaitVariable { queue: WaitQueue::new(), lock: var } - } - - pub fn lock_var(&self) -> &T { - &self.lock - } - - pub fn lock_var_mut(&mut self) -> &mut T { - &mut self.lock - } -} - -#[derive(Copy, Clone)] -pub enum NotifiedTcs { - Single(Tcs), - All { _count: NonZero }, -} - -/// An RAII guard that will notify a set of target threads as well as unlock -/// a mutex on drop. -pub struct WaitGuard<'a, T: 'a> { - mutex_guard: Option>>, - notified_tcs: NotifiedTcs, -} - -/// A queue of threads that are waiting on some synchronization primitive. -/// -/// `UnsafeList` entries are allocated on the waiting thread's stack. This -/// avoids any global locking that might happen in the heap allocator. This is -/// safe because the waiting thread will not return from that stack frame until -/// after it is notified. The notifying thread ensures to clean up any -/// references to the list entries before sending the wakeup event. -pub struct WaitQueue { - // We use an inner Mutex here to protect the data in the face of spurious - // wakeups. - inner: UnsafeList>, -} -unsafe impl Send for WaitQueue {} - -impl Default for WaitQueue { - fn default() -> Self { - Self::new() - } -} - -impl<'a, T> Deref for WaitGuard<'a, T> { - type Target = SpinMutexGuard<'a, WaitVariable>; - - fn deref(&self) -> &Self::Target { - self.mutex_guard.as_ref().unwrap() - } -} - -impl<'a, T> DerefMut for WaitGuard<'a, T> { - fn deref_mut(&mut self) -> &mut Self::Target { - self.mutex_guard.as_mut().unwrap() - } -} - -impl<'a, T> Drop for WaitGuard<'a, T> { - fn drop(&mut self) { - drop(self.mutex_guard.take()); - let target_tcs = match self.notified_tcs { - NotifiedTcs::Single(tcs) => Some(tcs), - NotifiedTcs::All { .. } => None, - }; - rtunwrap!(Ok, usercalls::send(EV_UNPARK, target_tcs)); - } -} - -impl WaitQueue { - pub const fn new() -> Self { - WaitQueue { inner: UnsafeList::new() } - } - - /// Adds the calling thread to the `WaitVariable`'s wait queue, then wait - /// until a wakeup event. - /// - /// This function does not return until this thread has been awoken. When `before_wait` panics, - /// this function will abort. - pub fn wait(mut guard: SpinMutexGuard<'_, WaitVariable>, before_wait: F) { - // very unsafe: check requirements of UnsafeList::push - unsafe { - let mut entry = UnsafeListEntry::new(SpinMutex::new(WaitEntry { - tcs: thread::current(), - wake: false, - })); - let entry = guard.queue.inner.push(&mut entry); - drop(guard); - if let Err(_e) = panic::catch_unwind(AssertUnwindSafe(|| before_wait())) { - rtabort!("Panic before wait on wakeup event") - } - while !entry.lock().wake { - // `entry.wake` is only set in `notify_one` and `notify_all` functions. Both ensure - // the entry is removed from the queue _before_ setting this bool. There are no - // other references to `entry`. - // don't panic, this would invalidate `entry` during unwinding - let eventset = rtunwrap!(Ok, usercalls::wait(EV_UNPARK, WAIT_INDEFINITE)); - rtassert!(eventset & EV_UNPARK == EV_UNPARK); - } - } - } - - /// Adds the calling thread to the `WaitVariable`'s wait queue, then wait - /// until a wakeup event or timeout. If event was observed, returns true. - /// If not, it will remove the calling thread from the wait queue. - /// When `before_wait` panics, this function will abort. - pub fn wait_timeout( - lock: &SpinMutex>, - timeout: Duration, - before_wait: F, - ) -> bool { - // very unsafe: check requirements of UnsafeList::push - unsafe { - let mut entry = UnsafeListEntry::new(SpinMutex::new(WaitEntry { - tcs: thread::current(), - wake: false, - })); - let entry_lock = lock.lock().queue.inner.push(&mut entry); - if let Err(_e) = panic::catch_unwind(AssertUnwindSafe(|| before_wait())) { - rtabort!("Panic before wait on wakeup event or timeout") - } - usercalls::wait_timeout(EV_UNPARK, timeout, || entry_lock.lock().wake); - // acquire the wait queue's lock first to avoid deadlock - // and ensure no other function can simultaneously access the list - // (e.g., `notify_one` or `notify_all`) - let mut guard = lock.lock(); - let success = entry_lock.lock().wake; - if !success { - // nobody is waking us up, so remove our entry from the wait queue. - guard.queue.inner.remove(&mut entry); - } - success - } - } - - /// Either find the next waiter on the wait queue, or return the mutex - /// guard unchanged. - /// - /// If a waiter is found, a `WaitGuard` is returned which will notify the - /// waiter when it is dropped. - pub fn notify_one( - mut guard: SpinMutexGuard<'_, WaitVariable>, - ) -> Result, SpinMutexGuard<'_, WaitVariable>> { - // SAFETY: lifetime of the pop() return value is limited to the map - // closure (The closure return value is 'static). The underlying - // stack frame won't be freed until after the lock on the queue is released - // (i.e., `guard` is dropped). - unsafe { - let tcs = guard.queue.inner.pop().map(|entry| -> Tcs { - let mut entry_guard = entry.lock(); - entry_guard.wake = true; - entry_guard.tcs - }); - - if let Some(tcs) = tcs { - Ok(WaitGuard { mutex_guard: Some(guard), notified_tcs: NotifiedTcs::Single(tcs) }) - } else { - Err(guard) - } - } - } - - /// Either find any and all waiters on the wait queue, or return the mutex - /// guard unchanged. - /// - /// If at least one waiter is found, a `WaitGuard` is returned which will - /// notify all waiters when it is dropped. - pub fn notify_all( - mut guard: SpinMutexGuard<'_, WaitVariable>, - ) -> Result, SpinMutexGuard<'_, WaitVariable>> { - // SAFETY: lifetime of the pop() return values are limited to the - // while loop body. The underlying stack frames won't be freed until - // after the lock on the queue is released (i.e., `guard` is dropped). - unsafe { - let mut count = 0; - while let Some(entry) = guard.queue.inner.pop() { - count += 1; - let mut entry_guard = entry.lock(); - entry_guard.wake = true; - } - - if let Some(count) = NonZero::new(count) { - Ok(WaitGuard { - mutex_guard: Some(guard), - notified_tcs: NotifiedTcs::All { _count: count }, - }) - } else { - Err(guard) - } - } - } -} diff --git a/library/std/src/sys/pal/sgx/waitqueue/spin_mutex.rs b/library/std/src/sys/pal/sgx/waitqueue/spin_mutex.rs deleted file mode 100644 index f6e851ccaddfa..0000000000000 --- a/library/std/src/sys/pal/sgx/waitqueue/spin_mutex.rs +++ /dev/null @@ -1,80 +0,0 @@ -//! Trivial spinlock-based implementation of `sync::Mutex`. -// FIXME: Perhaps use Intel TSX to avoid locking? - -#[cfg(test)] -mod tests; - -use crate::cell::UnsafeCell; -use crate::hint; -use crate::ops::{Deref, DerefMut}; -use crate::sync::atomic::{AtomicBool, Ordering}; - -#[derive(Default)] -pub struct SpinMutex { - value: UnsafeCell, - lock: AtomicBool, -} - -unsafe impl Send for SpinMutex {} -unsafe impl Sync for SpinMutex {} - -pub struct SpinMutexGuard<'a, T: 'a> { - mutex: &'a SpinMutex, -} - -impl<'a, T> !Send for SpinMutexGuard<'a, T> {} -unsafe impl<'a, T: Sync> Sync for SpinMutexGuard<'a, T> {} - -impl SpinMutex { - pub const fn new(value: T) -> Self { - SpinMutex { value: UnsafeCell::new(value), lock: AtomicBool::new(false) } - } - - #[inline(always)] - pub fn lock(&self) -> SpinMutexGuard<'_, T> { - loop { - match self.try_lock() { - None => { - while self.lock.load(Ordering::Relaxed) { - hint::spin_loop() - } - } - Some(guard) => return guard, - } - } - } - - #[inline(always)] - pub fn try_lock(&self) -> Option> { - if self.lock.compare_exchange(false, true, Ordering::Acquire, Ordering::Acquire).is_ok() { - Some(SpinMutexGuard { mutex: self }) - } else { - None - } - } -} - -/// Lock the Mutex or return false. -pub macro try_lock_or_false($e:expr) { - if let Some(v) = $e.try_lock() { v } else { return false } -} - -impl<'a, T> Deref for SpinMutexGuard<'a, T> { - type Target = T; - - fn deref(&self) -> &T { - unsafe { &*self.mutex.value.get() } - } -} - -impl<'a, T> DerefMut for SpinMutexGuard<'a, T> { - fn deref_mut(&mut self) -> &mut T { - unsafe { &mut *self.mutex.value.get() } - } -} - -impl<'a, T> Drop for SpinMutexGuard<'a, T> { - fn drop(&mut self) { - self.mutex.lock.store(false, Ordering::Release) - } -} diff --git a/library/std/src/sys/pal/sgx/waitqueue/spin_mutex/tests.rs b/library/std/src/sys/pal/sgx/waitqueue/spin_mutex/tests.rs deleted file mode 100644 index 4c5994bea61f7..0000000000000 --- a/library/std/src/sys/pal/sgx/waitqueue/spin_mutex/tests.rs +++ /dev/null @@ -1,23 +0,0 @@ -#![allow(deprecated)] - -use super::*; -use crate::sync::Arc; -use crate::thread; -use crate::time::Duration; - -#[test] -fn sleep() { - let mutex = Arc::new(SpinMutex::::default()); - let mutex2 = mutex.clone(); - let guard = mutex.lock(); - let t1 = thread::spawn(move || { - *mutex2.lock() = 1; - }); - - thread::sleep(Duration::from_millis(50)); - - assert_eq!(*guard, 0); - drop(guard); - t1.join().unwrap(); - assert_eq!(*mutex.lock(), 1); -} diff --git a/library/std/src/sys/pal/sgx/waitqueue/tests.rs b/library/std/src/sys/pal/sgx/waitqueue/tests.rs deleted file mode 100644 index bf91fdd08ed54..0000000000000 --- a/library/std/src/sys/pal/sgx/waitqueue/tests.rs +++ /dev/null @@ -1,20 +0,0 @@ -use super::*; -use crate::sync::Arc; -use crate::thread; - -#[test] -fn queue() { - let wq = Arc::new(SpinMutex::>::default()); - let wq2 = wq.clone(); - - let locked = wq.lock(); - - let t1 = thread::spawn(move || { - // if we obtain the lock, the main thread should be waiting - assert!(WaitQueue::notify_one(wq2.lock()).is_ok()); - }); - - WaitQueue::wait(locked, || {}); - - t1.join().unwrap(); -} diff --git a/library/std/src/sys/pal/sgx/waitqueue/unsafe_list.rs b/library/std/src/sys/pal/sgx/waitqueue/unsafe_list.rs deleted file mode 100644 index c736cab576e4d..0000000000000 --- a/library/std/src/sys/pal/sgx/waitqueue/unsafe_list.rs +++ /dev/null @@ -1,156 +0,0 @@ -//! A doubly-linked list where callers are in charge of memory allocation -//! of the nodes in the list. - -#[cfg(test)] -mod tests; - -use crate::mem; -use crate::ptr::NonNull; - -pub struct UnsafeListEntry { - next: NonNull>, - prev: NonNull>, - value: Option, -} - -impl UnsafeListEntry { - fn dummy() -> Self { - UnsafeListEntry { next: NonNull::dangling(), prev: NonNull::dangling(), value: None } - } - - pub fn new(value: T) -> Self { - UnsafeListEntry { value: Some(value), ..Self::dummy() } - } -} - -// WARNING: self-referential struct! -pub struct UnsafeList { - head_tail: NonNull>, - head_tail_entry: Option>, -} - -impl UnsafeList { - pub const fn new() -> Self { - unsafe { UnsafeList { head_tail: NonNull::new_unchecked(1 as _), head_tail_entry: None } } - } - - /// # Safety - unsafe fn init(&mut self) { - if self.head_tail_entry.is_none() { - self.head_tail_entry = Some(UnsafeListEntry::dummy()); - // SAFETY: `head_tail_entry` must be non-null, which it is because we assign it above. - self.head_tail = - unsafe { NonNull::new_unchecked(self.head_tail_entry.as_mut().unwrap()) }; - // SAFETY: `self.head_tail` must meet all requirements for a mutable reference. - unsafe { self.head_tail.as_mut() }.next = self.head_tail; - unsafe { self.head_tail.as_mut() }.prev = self.head_tail; - } - } - - pub fn is_empty(&self) -> bool { - if self.head_tail_entry.is_some() { - let first = unsafe { self.head_tail.as_ref() }.next; - if first == self.head_tail { - // ,-------> /---------\ next ---, - // | |head_tail| | - // `--- prev \---------/ <-------` - // SAFETY: `self.head_tail` must meet all requirements for a reference. - unsafe { rtassert!(self.head_tail.as_ref().prev == first) }; - true - } else { - false - } - } else { - true - } - } - - /// Pushes an entry onto the back of the list. - /// - /// # Safety - /// - /// The entry must remain allocated until the entry is removed from the - /// list AND the caller who popped is done using the entry. Special - /// care must be taken in the caller of `push` to ensure unwinding does - /// not destroy the stack frame containing the entry. - pub unsafe fn push<'a>(&mut self, entry: &'a mut UnsafeListEntry) -> &'a T { - unsafe { self.init() }; - - // BEFORE: - // /---------\ next ---> /---------\ - // ... |prev_tail| |head_tail| ... - // \---------/ <--- prev \---------/ - // - // AFTER: - // /---------\ next ---> /-----\ next ---> /---------\ - // ... |prev_tail| |entry| |head_tail| ... - // \---------/ <--- prev \-----/ <--- prev \---------/ - let mut entry = unsafe { NonNull::new_unchecked(entry) }; - let mut prev_tail = mem::replace(&mut unsafe { self.head_tail.as_mut() }.prev, entry); - // SAFETY: `entry` must meet all requirements for a mutable reference. - unsafe { entry.as_mut() }.prev = prev_tail; - unsafe { entry.as_mut() }.next = self.head_tail; - // SAFETY: `prev_tail` must meet all requirements for a mutable reference. - unsafe { prev_tail.as_mut() }.next = entry; - // unwrap ok: always `Some` on non-dummy entries - unsafe { (*entry.as_ptr()).value.as_ref() }.unwrap() - } - - /// Pops an entry from the front of the list. - /// - /// # Safety - /// - /// The caller must make sure to synchronize ending the borrow of the - /// return value and deallocation of the containing entry. - pub unsafe fn pop<'a>(&mut self) -> Option<&'a T> { - unsafe { self.init() }; - - if self.is_empty() { - None - } else { - // BEFORE: - // /---------\ next ---> /-----\ next ---> /------\ - // ... |head_tail| |first| |second| ... - // \---------/ <--- prev \-----/ <--- prev \------/ - // - // AFTER: - // /---------\ next ---> /------\ - // ... |head_tail| |second| ... - // \---------/ <--- prev \------/ - let mut first = unsafe { self.head_tail.as_mut() }.next; - let mut second = unsafe { first.as_mut() }.next; - unsafe { self.head_tail.as_mut() }.next = second; - unsafe { second.as_mut() }.prev = self.head_tail; - unsafe { first.as_mut() }.next = NonNull::dangling(); - unsafe { first.as_mut() }.prev = NonNull::dangling(); - // unwrap ok: always `Some` on non-dummy entries - Some(unsafe { (*first.as_ptr()).value.as_ref() }.unwrap()) - } - } - - /// Removes an entry from the list. - /// - /// # Safety - /// - /// The caller must ensure that `entry` has been pushed onto `self` - /// prior to this call and has not moved since then. - pub unsafe fn remove(&mut self, entry: &mut UnsafeListEntry) { - rtassert!(!self.is_empty()); - // BEFORE: - // /----\ next ---> /-----\ next ---> /----\ - // ... |prev| |entry| |next| ... - // \----/ <--- prev \-----/ <--- prev \----/ - // - // AFTER: - // /----\ next ---> /----\ - // ... |prev| |next| ... - // \----/ <--- prev \----/ - let mut prev = entry.prev; - let mut next = entry.next; - // SAFETY: `prev` and `next` must meet all requirements for a mutable reference.entry - unsafe { prev.as_mut() }.next = next; - unsafe { next.as_mut() }.prev = prev; - entry.next = NonNull::dangling(); - entry.prev = NonNull::dangling(); - } -} diff --git a/library/std/src/sys/pal/sgx/waitqueue/unsafe_list/tests.rs b/library/std/src/sys/pal/sgx/waitqueue/unsafe_list/tests.rs deleted file mode 100644 index c653dee17bc36..0000000000000 --- a/library/std/src/sys/pal/sgx/waitqueue/unsafe_list/tests.rs +++ /dev/null @@ -1,105 +0,0 @@ -use super::*; -use crate::cell::Cell; - -/// # Safety -/// List must be valid. -unsafe fn assert_empty(list: &mut UnsafeList) { - assert!(unsafe { list.pop() }.is_none(), "assertion failed: list is not empty"); -} - -#[test] -fn init_empty() { - unsafe { - assert_empty(&mut UnsafeList::::new()); - } -} - -#[test] -fn push_pop() { - unsafe { - let mut node = UnsafeListEntry::new(1234); - let mut list = UnsafeList::new(); - assert_eq!(list.push(&mut node), &1234); - assert_eq!(list.pop().unwrap(), &1234); - assert_empty(&mut list); - } -} - -#[test] -fn push_remove() { - unsafe { - let mut node = UnsafeListEntry::new(1234); - let mut list = UnsafeList::new(); - assert_eq!(list.push(&mut node), &1234); - list.remove(&mut node); - assert_empty(&mut list); - } -} - -#[test] -fn push_remove_pop() { - unsafe { - let mut node1 = UnsafeListEntry::new(11); - let mut node2 = UnsafeListEntry::new(12); - let mut node3 = UnsafeListEntry::new(13); - let mut node4 = UnsafeListEntry::new(14); - let mut node5 = UnsafeListEntry::new(15); - let mut list = UnsafeList::new(); - assert_eq!(list.push(&mut node1), &11); - assert_eq!(list.push(&mut node2), &12); - assert_eq!(list.push(&mut node3), &13); - assert_eq!(list.push(&mut node4), &14); - assert_eq!(list.push(&mut node5), &15); - - list.remove(&mut node1); - assert_eq!(list.pop().unwrap(), &12); - list.remove(&mut node3); - assert_eq!(list.pop().unwrap(), &14); - list.remove(&mut node5); - assert_empty(&mut list); - - assert_eq!(list.push(&mut node1), &11); - assert_eq!(list.pop().unwrap(), &11); - assert_empty(&mut list); - - assert_eq!(list.push(&mut node3), &13); - assert_eq!(list.push(&mut node4), &14); - list.remove(&mut node3); - list.remove(&mut node4); - assert_empty(&mut list); - } -} - -#[test] -fn complex_pushes_pops() { - unsafe { - let mut node1 = UnsafeListEntry::new(1234); - let mut node2 = UnsafeListEntry::new(4567); - let mut node3 = UnsafeListEntry::new(9999); - let mut node4 = UnsafeListEntry::new(8642); - let mut list = UnsafeList::new(); - list.push(&mut node1); - list.push(&mut node2); - assert_eq!(list.pop().unwrap(), &1234); - list.push(&mut node3); - assert_eq!(list.pop().unwrap(), &4567); - assert_eq!(list.pop().unwrap(), &9999); - assert_empty(&mut list); - list.push(&mut node4); - assert_eq!(list.pop().unwrap(), &8642); - assert_empty(&mut list); - } -} - -#[test] -fn cell() { - unsafe { - let mut node = UnsafeListEntry::new(Cell::new(0)); - let mut list = UnsafeList::new(); - let noderef = list.push(&mut node); - assert_eq!(noderef.get(), 0); - list.pop().unwrap().set(1); - assert_empty(&mut list); - assert_eq!(noderef.get(), 1); - } -} diff --git a/library/std/src/sys/pal/solid/abi/fs.rs b/library/std/src/sys/pal/solid/abi/fs.rs deleted file mode 100644 index 49526f4c9cd4d..0000000000000 --- a/library/std/src/sys/pal/solid/abi/fs.rs +++ /dev/null @@ -1,52 +0,0 @@ -//! `solid_fs.h` -use crate::os::raw::{c_char, c_int, c_uchar}; -pub use libc::{ - ino_t, off_t, stat, time_t, O_APPEND, O_CREAT, O_EXCL, O_RDONLY, O_RDWR, O_TRUNC, O_WRONLY, - SEEK_CUR, SEEK_END, SEEK_SET, S_IFBLK, S_IFCHR, S_IFDIR, S_IFIFO, S_IFMT, S_IFREG, S_IWRITE, -}; - -pub const O_ACCMODE: c_int = 0x3; - -pub const SOLID_MAX_PATH: usize = 256; - -#[repr(C)] -#[derive(Copy, Clone)] -pub struct dirent { - pub d_ino: ino_t, - pub d_type: c_uchar, - pub d_name: [c_char; 256usize], -} - -pub const DT_UNKNOWN: c_uchar = 0; -pub const DT_FIFO: c_uchar = 1; -pub const DT_CHR: c_uchar = 2; -pub const DT_DIR: c_uchar = 4; -pub const DT_BLK: c_uchar = 6; -pub const DT_REG: c_uchar = 8; -pub const DT_LNK: c_uchar = 10; -pub const DT_SOCK: c_uchar = 12; -pub const DT_WHT: c_uchar = 14; - -pub type S_DIR = c_int; - -extern "C" { - pub fn SOLID_FS_Open(fd: *mut c_int, path: *const c_char, mode: c_int) -> c_int; - pub fn SOLID_FS_Close(fd: c_int) -> c_int; - pub fn SOLID_FS_Read(fd: c_int, buf: *mut u8, size: usize, result: *mut usize) -> c_int; - pub fn SOLID_FS_Write(fd: c_int, buf: *const u8, size: usize, result: *mut usize) -> c_int; - pub fn SOLID_FS_Lseek(fd: c_int, offset: off_t, whence: c_int) -> c_int; - pub fn SOLID_FS_Sync(fd: c_int) -> c_int; - pub fn SOLID_FS_Ftell(fd: c_int, result: *mut off_t) -> c_int; - pub fn SOLID_FS_Feof(fd: c_int, result: *mut c_int) -> c_int; - pub fn SOLID_FS_Fsize(fd: c_int, result: *mut usize) -> c_int; - pub fn SOLID_FS_Truncate(path: *const c_char, size: off_t) -> c_int; - pub fn SOLID_FS_OpenDir(path: *const c_char, pDir: *mut S_DIR) -> c_int; - pub fn SOLID_FS_CloseDir(dir: S_DIR) -> c_int; - pub fn SOLID_FS_ReadDir(dir: S_DIR, dirp: *mut dirent) -> c_int; - pub fn SOLID_FS_Stat(path: *const c_char, buf: *mut stat) -> c_int; - pub fn SOLID_FS_Unlink(path: *const c_char) -> c_int; - pub fn SOLID_FS_Rename(oldpath: *const c_char, newpath: *const c_char) -> c_int; - pub fn SOLID_FS_Chmod(path: *const c_char, mode: c_int) -> c_int; - pub fn SOLID_FS_Utime(path: *const c_char, time: time_t) -> c_int; - pub fn SOLID_FS_Mkdir(path: *const c_char) -> c_int; -} diff --git a/library/std/src/sys/pal/solid/abi/mod.rs b/library/std/src/sys/pal/solid/abi/mod.rs deleted file mode 100644 index 8440d572cfbd3..0000000000000 --- a/library/std/src/sys/pal/solid/abi/mod.rs +++ /dev/null @@ -1,65 +0,0 @@ -use crate::os::raw::c_int; - -mod fs; -pub mod sockets; -pub use self::fs::*; - -// `solid_types.h` -pub use super::itron::abi::{ER, ER_ID, E_TMOUT, ID}; - -pub const SOLID_ERR_NOTFOUND: ER = -1000; -pub const SOLID_ERR_NOTSUPPORTED: ER = -1001; -pub const SOLID_ERR_EBADF: ER = -1002; -pub const SOLID_ERR_INVALIDCONTENT: ER = -1003; -pub const SOLID_ERR_NOTUSED: ER = -1004; -pub const SOLID_ERR_ALREADYUSED: ER = -1005; -pub const SOLID_ERR_OUTOFBOUND: ER = -1006; -pub const SOLID_ERR_BADSEQUENCE: ER = -1007; -pub const SOLID_ERR_UNKNOWNDEVICE: ER = -1008; -pub const SOLID_ERR_BUSY: ER = -1009; -pub const SOLID_ERR_TIMEOUT: ER = -1010; -pub const SOLID_ERR_INVALIDACCESS: ER = -1011; -pub const SOLID_ERR_NOTREADY: ER = -1012; - -// `solid_rtc.h` -#[repr(C)] -#[derive(Debug, Copy, Clone)] -pub struct SOLID_RTC_TIME { - pub tm_sec: c_int, - pub tm_min: c_int, - pub tm_hour: c_int, - pub tm_mday: c_int, - pub tm_mon: c_int, - pub tm_year: c_int, - pub tm_wday: c_int, -} - -extern "C" { - pub fn SOLID_RTC_ReadTime(time: *mut SOLID_RTC_TIME) -> c_int; -} - -// `solid_log.h` -extern "C" { - pub fn SOLID_LOG_write(s: *const u8, l: usize); -} - -// `solid_mem.h` -extern "C" { - pub fn SOLID_TLS_AddDestructor(id: i32, dtor: unsafe extern "C" fn(*mut u8)); -} - -// `solid_rng.h` -extern "C" { - pub fn SOLID_RNG_SampleRandomBytes(buffer: *mut u8, length: usize) -> c_int; -} - -// `rwlock.h` -extern "C" { - pub fn rwl_loc_rdl(id: ID) -> ER; - pub fn rwl_loc_wrl(id: ID) -> ER; - pub fn rwl_ploc_rdl(id: ID) -> ER; - pub fn rwl_ploc_wrl(id: ID) -> ER; - pub fn rwl_unl_rwl(id: ID) -> ER; - pub fn rwl_acre_rwl() -> ER_ID; - pub fn rwl_del_rwl(id: ID) -> ER; -} diff --git a/library/std/src/sys/pal/solid/abi/sockets.rs b/library/std/src/sys/pal/solid/abi/sockets.rs deleted file mode 100644 index 11c430360ce88..0000000000000 --- a/library/std/src/sys/pal/solid/abi/sockets.rs +++ /dev/null @@ -1,277 +0,0 @@ -use crate::os::raw::{c_char, c_uint, c_void}; -pub use libc::{c_int, c_long, size_t, ssize_t, timeval}; - -pub const SOLID_NET_ERR_BASE: c_int = -2000; -pub const EINPROGRESS: c_int = SOLID_NET_ERR_BASE - libc::EINPROGRESS; - -pub const AF_INET6: i32 = 10; -pub const AF_INET: i32 = 2; -pub const IPPROTO_IP: i32 = 0; -pub const IPPROTO_IPV6: i32 = 41; -pub const IPPROTO_TCP: i32 = 6; -pub const IPV6_ADD_MEMBERSHIP: i32 = 12; -pub const IPV6_DROP_MEMBERSHIP: i32 = 13; -pub const IPV6_MULTICAST_LOOP: i32 = 19; -pub const IPV6_V6ONLY: i32 = 27; -pub const IP_TTL: i32 = 2; -pub const IP_MULTICAST_TTL: i32 = 5; -pub const IP_MULTICAST_LOOP: i32 = 7; -pub const IP_ADD_MEMBERSHIP: i32 = 3; -pub const IP_DROP_MEMBERSHIP: i32 = 4; -pub const SHUT_RD: i32 = 0; -pub const SHUT_RDWR: i32 = 2; -pub const SHUT_WR: i32 = 1; -pub const SOCK_DGRAM: i32 = 2; -pub const SOCK_STREAM: i32 = 1; -pub const SOL_SOCKET: i32 = 4095; -pub const SO_BROADCAST: i32 = 32; -pub const SO_ERROR: i32 = 4103; -pub const SO_RCVTIMEO: i32 = 4102; -pub const SO_REUSEADDR: i32 = 4; -pub const SO_SNDTIMEO: i32 = 4101; -pub const SO_LINGER: i32 = 128; -pub const TCP_NODELAY: i32 = 1; -pub const MSG_PEEK: c_int = 1; -pub const FIONBIO: c_long = 0x8008667eu32 as c_long; -pub const EAI_NONAME: i32 = -2200; -pub const EAI_SERVICE: i32 = -2201; -pub const EAI_FAIL: i32 = -2202; -pub const EAI_MEMORY: i32 = -2203; -pub const EAI_FAMILY: i32 = -2204; - -pub type sa_family_t = u8; -pub type socklen_t = u32; -pub type in_addr_t = u32; -pub type in_port_t = u16; - -#[repr(C)] -#[derive(Debug, Copy, Clone)] -pub struct in_addr { - pub s_addr: in_addr_t, -} - -#[repr(C)] -#[derive(Debug, Copy, Clone)] -pub struct in6_addr { - pub s6_addr: [u8; 16], -} - -#[repr(C)] -#[derive(Debug, Copy, Clone)] -pub struct ip_mreq { - pub imr_multiaddr: in_addr, - pub imr_interface: in_addr, -} - -#[repr(C)] -#[derive(Debug, Copy, Clone)] -pub struct ipv6_mreq { - pub ipv6mr_multiaddr: in6_addr, - pub ipv6mr_interface: c_uint, -} - -#[repr(C)] -#[derive(Debug, Copy, Clone)] -pub struct msghdr { - pub msg_name: *mut c_void, - pub msg_namelen: socklen_t, - pub msg_iov: *mut iovec, - pub msg_iovlen: c_int, - pub msg_control: *mut c_void, - pub msg_controllen: socklen_t, - pub msg_flags: c_int, -} - -#[repr(C)] -#[derive(Debug, Copy, Clone)] -pub struct sockaddr { - pub sa_len: u8, - pub sa_family: sa_family_t, - pub sa_data: [c_char; 14usize], -} - -#[repr(C)] -#[derive(Debug, Copy, Clone)] -pub struct sockaddr_in { - pub sin_len: u8, - pub sin_family: sa_family_t, - pub sin_port: in_port_t, - pub sin_addr: in_addr, - pub sin_zero: [c_char; 8usize], -} - -#[repr(C)] -#[derive(Copy, Clone)] -pub struct sockaddr_in6 { - pub sin6_len: u8, - pub sin6_family: sa_family_t, - pub sin6_port: in_port_t, - pub sin6_flowinfo: u32, - pub sin6_addr: in6_addr, - pub sin6_scope_id: u32, -} - -#[repr(C)] -#[derive(Debug, Copy, Clone)] -pub struct sockaddr_storage { - pub s2_len: u8, - pub ss_family: sa_family_t, - pub s2_data1: [c_char; 2usize], - pub s2_data2: [u32; 3usize], -} - -#[repr(C)] -#[derive(Debug, Copy, Clone)] -pub struct addrinfo { - pub ai_flags: c_int, - pub ai_family: c_int, - pub ai_socktype: c_int, - pub ai_protocol: c_int, - pub ai_addrlen: socklen_t, - pub ai_addr: *mut sockaddr, - pub ai_canonname: *mut c_char, - pub ai_next: *mut addrinfo, -} - -#[repr(C)] -#[derive(Debug, Copy, Clone)] -pub struct linger { - pub l_onoff: c_int, - pub l_linger: c_int, -} - -#[repr(C)] -#[derive(Debug, Copy, Clone)] -pub struct iovec { - pub iov_base: *mut c_void, - pub iov_len: usize, -} - -/// This value can be chosen by an application -pub const SOLID_NET_FD_SETSIZE: usize = 1; - -#[repr(C)] -#[derive(Debug, Copy, Clone)] -pub struct fd_set { - pub num_fds: usize, - pub fds: [c_int; SOLID_NET_FD_SETSIZE], -} - -extern "C" { - #[link_name = "SOLID_NET_StrError"] - pub fn strerror(errnum: c_int) -> *const c_char; - - pub fn SOLID_NET_GetLastError() -> c_int; - - #[link_name = "SOLID_NET_Accept"] - pub fn accept(s: c_int, addr: *mut sockaddr, addrlen: *mut socklen_t) -> c_int; - - #[link_name = "SOLID_NET_Bind"] - pub fn bind(s: c_int, name: *const sockaddr, namelen: socklen_t) -> c_int; - - #[link_name = "SOLID_NET_Connect"] - pub fn connect(s: c_int, name: *const sockaddr, namelen: socklen_t) -> c_int; - - #[link_name = "SOLID_NET_Close"] - pub fn close(s: c_int) -> c_int; - - #[link_name = "SOLID_NET_Dup"] - pub fn dup(s: c_int) -> c_int; - - #[link_name = "SOLID_NET_GetPeerName"] - pub fn getpeername(s: c_int, name: *mut sockaddr, namelen: *mut socklen_t) -> c_int; - - #[link_name = "SOLID_NET_GetSockName"] - pub fn getsockname(s: c_int, name: *mut sockaddr, namelen: *mut socklen_t) -> c_int; - - #[link_name = "SOLID_NET_GetSockOpt"] - pub fn getsockopt( - s: c_int, - level: c_int, - optname: c_int, - optval: *mut c_void, - optlen: *mut socklen_t, - ) -> c_int; - - #[link_name = "SOLID_NET_SetSockOpt"] - pub fn setsockopt( - s: c_int, - level: c_int, - optname: c_int, - optval: *const c_void, - optlen: socklen_t, - ) -> c_int; - - #[link_name = "SOLID_NET_Ioctl"] - pub fn ioctl(s: c_int, cmd: c_long, argp: *mut c_void) -> c_int; - - #[link_name = "SOLID_NET_Listen"] - pub fn listen(s: c_int, backlog: c_int) -> c_int; - - #[link_name = "SOLID_NET_Recv"] - pub fn recv(s: c_int, mem: *mut c_void, len: size_t, flags: c_int) -> ssize_t; - - #[link_name = "SOLID_NET_Read"] - pub fn read(s: c_int, mem: *mut c_void, len: size_t) -> ssize_t; - - #[link_name = "SOLID_NET_Readv"] - pub fn readv(s: c_int, bufs: *const iovec, bufcnt: c_int) -> ssize_t; - - #[link_name = "SOLID_NET_RecvFrom"] - pub fn recvfrom( - s: c_int, - mem: *mut c_void, - len: size_t, - flags: c_int, - from: *mut sockaddr, - fromlen: *mut socklen_t, - ) -> ssize_t; - - #[link_name = "SOLID_NET_Send"] - pub fn send(s: c_int, mem: *const c_void, len: size_t, flags: c_int) -> ssize_t; - - #[link_name = "SOLID_NET_SendMsg"] - pub fn sendmsg(s: c_int, message: *const msghdr, flags: c_int) -> ssize_t; - - #[link_name = "SOLID_NET_SendTo"] - pub fn sendto( - s: c_int, - mem: *const c_void, - len: size_t, - flags: c_int, - to: *const sockaddr, - tolen: socklen_t, - ) -> ssize_t; - - #[link_name = "SOLID_NET_Shutdown"] - pub fn shutdown(s: c_int, how: c_int) -> c_int; - - #[link_name = "SOLID_NET_Socket"] - pub fn socket(domain: c_int, type_: c_int, protocol: c_int) -> c_int; - - #[link_name = "SOLID_NET_Write"] - pub fn write(s: c_int, mem: *const c_void, len: size_t) -> ssize_t; - - #[link_name = "SOLID_NET_Writev"] - pub fn writev(s: c_int, bufs: *const iovec, bufcnt: c_int) -> ssize_t; - - #[link_name = "SOLID_NET_FreeAddrInfo"] - pub fn freeaddrinfo(ai: *mut addrinfo); - - #[link_name = "SOLID_NET_GetAddrInfo"] - pub fn getaddrinfo( - nodename: *const c_char, - servname: *const c_char, - hints: *const addrinfo, - res: *mut *mut addrinfo, - ) -> c_int; - - #[link_name = "SOLID_NET_Select"] - pub fn select( - maxfdp1: c_int, - readset: *mut fd_set, - writeset: *mut fd_set, - exceptset: *mut fd_set, - timeout: *mut timeval, - ) -> c_int; -} diff --git a/library/std/src/sys/pal/solid/alloc.rs b/library/std/src/sys/pal/solid/alloc.rs deleted file mode 100644 index d013bd8761003..0000000000000 --- a/library/std/src/sys/pal/solid/alloc.rs +++ /dev/null @@ -1,32 +0,0 @@ -use crate::{ - alloc::{GlobalAlloc, Layout, System}, - sys::common::alloc::{realloc_fallback, MIN_ALIGN}, -}; - -#[stable(feature = "alloc_system_type", since = "1.28.0")] -unsafe impl GlobalAlloc for System { - #[inline] - unsafe fn alloc(&self, layout: Layout) -> *mut u8 { - if layout.align() <= MIN_ALIGN && layout.align() <= layout.size() { - unsafe { libc::malloc(layout.size()) as *mut u8 } - } else { - unsafe { libc::memalign(layout.align(), layout.size()) as *mut u8 } - } - } - - #[inline] - unsafe fn dealloc(&self, ptr: *mut u8, _layout: Layout) { - unsafe { libc::free(ptr as *mut libc::c_void) } - } - - #[inline] - unsafe fn realloc(&self, ptr: *mut u8, layout: Layout, new_size: usize) -> *mut u8 { - unsafe { - if layout.align() <= MIN_ALIGN && layout.align() <= new_size { - libc::realloc(ptr as *mut libc::c_void, new_size) as *mut u8 - } else { - realloc_fallback(self, ptr, layout, new_size) - } - } - } -} diff --git a/library/std/src/sys/pal/solid/env.rs b/library/std/src/sys/pal/solid/env.rs deleted file mode 100644 index 6855c113b2893..0000000000000 --- a/library/std/src/sys/pal/solid/env.rs +++ /dev/null @@ -1,9 +0,0 @@ -pub mod os { - pub const FAMILY: &str = "itron"; - pub const OS: &str = "solid"; - pub const DLL_PREFIX: &str = ""; - pub const DLL_SUFFIX: &str = ".so"; - pub const DLL_EXTENSION: &str = "so"; - pub const EXE_SUFFIX: &str = ""; - pub const EXE_EXTENSION: &str = ""; -} diff --git a/library/std/src/sys/pal/solid/error.rs b/library/std/src/sys/pal/solid/error.rs deleted file mode 100644 index 547b4f3a9840e..0000000000000 --- a/library/std/src/sys/pal/solid/error.rs +++ /dev/null @@ -1,55 +0,0 @@ -use super::{abi, itron, net}; -use crate::io::ErrorKind; - -pub use self::itron::error::{expect_success, ItronError as SolidError}; - -/// Describe the specified SOLID error code. Returns `None` if it's an -/// undefined error code. -/// -/// The SOLID error codes are a superset of μITRON error codes. -pub fn error_name(er: abi::ER) -> Option<&'static str> { - match er { - // Success - er if er >= 0 => None, - er if er < abi::sockets::SOLID_NET_ERR_BASE => net::error_name(er), - - abi::SOLID_ERR_NOTFOUND => Some("not found"), - abi::SOLID_ERR_NOTSUPPORTED => Some("not supported"), - abi::SOLID_ERR_EBADF => Some("bad flags"), - abi::SOLID_ERR_INVALIDCONTENT => Some("invalid content"), - abi::SOLID_ERR_NOTUSED => Some("not used"), - abi::SOLID_ERR_ALREADYUSED => Some("already used"), - abi::SOLID_ERR_OUTOFBOUND => Some("out of bounds"), - abi::SOLID_ERR_BADSEQUENCE => Some("bad sequence"), - abi::SOLID_ERR_UNKNOWNDEVICE => Some("unknown device"), - abi::SOLID_ERR_BUSY => Some("busy"), - abi::SOLID_ERR_TIMEOUT => Some("operation timed out"), - abi::SOLID_ERR_INVALIDACCESS => Some("invalid access"), - abi::SOLID_ERR_NOTREADY => Some("not ready"), - - _ => itron::error::error_name(er), - } -} - -pub fn decode_error_kind(er: abi::ER) -> ErrorKind { - match er { - // Success - er if er >= 0 => ErrorKind::Uncategorized, - er if er < abi::sockets::SOLID_NET_ERR_BASE => net::decode_error_kind(er), - - abi::SOLID_ERR_NOTFOUND => ErrorKind::NotFound, - abi::SOLID_ERR_NOTSUPPORTED => ErrorKind::Unsupported, - abi::SOLID_ERR_EBADF => ErrorKind::InvalidInput, - abi::SOLID_ERR_INVALIDCONTENT => ErrorKind::InvalidData, - // abi::SOLID_ERR_NOTUSED - // abi::SOLID_ERR_ALREADYUSED - abi::SOLID_ERR_OUTOFBOUND => ErrorKind::InvalidInput, - // abi::SOLID_ERR_BADSEQUENCE - abi::SOLID_ERR_UNKNOWNDEVICE => ErrorKind::NotFound, - // abi::SOLID_ERR_BUSY - abi::SOLID_ERR_TIMEOUT => ErrorKind::TimedOut, - // abi::SOLID_ERR_INVALIDACCESS - // abi::SOLID_ERR_NOTREADY - _ => itron::error::decode_error_kind(er), - } -} diff --git a/library/std/src/sys/pal/solid/fs.rs b/library/std/src/sys/pal/solid/fs.rs deleted file mode 100644 index a6c1336109ad7..0000000000000 --- a/library/std/src/sys/pal/solid/fs.rs +++ /dev/null @@ -1,588 +0,0 @@ -use super::{abi, error}; -use crate::{ - ffi::{CStr, CString, OsStr, OsString}, - fmt, - io::{self, BorrowedCursor, IoSlice, IoSliceMut, SeekFrom}, - mem::MaybeUninit, - os::raw::{c_int, c_short}, - os::solid::ffi::OsStrExt, - path::{Path, PathBuf}, - sync::Arc, - sys::time::SystemTime, - sys::unsupported, -}; - -pub use crate::sys_common::fs::try_exists; - -/// A file descriptor. -#[derive(Clone, Copy)] -#[rustc_layout_scalar_valid_range_start(0)] -// libstd/os/raw/mod.rs assures me that every libstd-supported platform has a -// 32-bit c_int. Below is -2, in two's complement, but that only works out -// because c_int is 32 bits. -#[rustc_layout_scalar_valid_range_end(0xFF_FF_FF_FE)] -struct FileDesc { - fd: c_int, -} - -impl FileDesc { - #[inline] - fn new(fd: c_int) -> FileDesc { - assert_ne!(fd, -1i32); - // Safety: we just asserted that the value is in the valid range and - // isn't `-1` (the only value bigger than `0xFF_FF_FF_FE` unsigned) - unsafe { FileDesc { fd } } - } - - #[inline] - fn raw(&self) -> c_int { - self.fd - } -} - -pub struct File { - fd: FileDesc, -} - -#[derive(Clone)] -pub struct FileAttr { - stat: abi::stat, -} - -// all DirEntry's will have a reference to this struct -struct InnerReadDir { - dirp: abi::S_DIR, - root: PathBuf, -} - -pub struct ReadDir { - inner: Arc, -} - -pub struct DirEntry { - entry: abi::dirent, - inner: Arc, -} - -#[derive(Clone, Debug)] -pub struct OpenOptions { - // generic - read: bool, - write: bool, - append: bool, - truncate: bool, - create: bool, - create_new: bool, - // system-specific - custom_flags: i32, -} - -#[derive(Copy, Clone, Debug, Default)] -pub struct FileTimes {} - -#[derive(Clone, PartialEq, Eq, Debug)] -pub struct FilePermissions(c_short); - -#[derive(Copy, Clone, PartialEq, Eq, Hash, Debug)] -pub struct FileType(c_short); - -#[derive(Debug)] -pub struct DirBuilder {} - -impl FileAttr { - pub fn size(&self) -> u64 { - self.stat.st_size as u64 - } - - pub fn perm(&self) -> FilePermissions { - FilePermissions(self.stat.st_mode) - } - - pub fn file_type(&self) -> FileType { - FileType(self.stat.st_mode) - } - - pub fn modified(&self) -> io::Result { - Ok(SystemTime::from_time_t(self.stat.st_mtime)) - } - - pub fn accessed(&self) -> io::Result { - Ok(SystemTime::from_time_t(self.stat.st_atime)) - } - - pub fn created(&self) -> io::Result { - Ok(SystemTime::from_time_t(self.stat.st_ctime)) - } -} - -impl FilePermissions { - pub fn readonly(&self) -> bool { - (self.0 & abi::S_IWRITE) == 0 - } - - pub fn set_readonly(&mut self, readonly: bool) { - if readonly { - self.0 &= !abi::S_IWRITE; - } else { - self.0 |= abi::S_IWRITE; - } - } -} - -impl FileTimes { - pub fn set_accessed(&mut self, _t: SystemTime) {} - pub fn set_modified(&mut self, _t: SystemTime) {} -} - -impl FileType { - pub fn is_dir(&self) -> bool { - self.is(abi::S_IFDIR) - } - pub fn is_file(&self) -> bool { - self.is(abi::S_IFREG) - } - pub fn is_symlink(&self) -> bool { - false - } - - pub fn is(&self, mode: c_short) -> bool { - self.0 & abi::S_IFMT == mode - } -} - -pub fn readdir(p: &Path) -> io::Result { - unsafe { - let mut dir = MaybeUninit::uninit(); - error::SolidError::err_if_negative(abi::SOLID_FS_OpenDir( - cstr(p)?.as_ptr(), - dir.as_mut_ptr(), - )) - .map_err(|e| e.as_io_error())?; - let inner = Arc::new(InnerReadDir { dirp: dir.assume_init(), root: p.to_owned() }); - Ok(ReadDir { inner }) - } -} - -impl fmt::Debug for ReadDir { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - // This will only be called from std::fs::ReadDir, which will add a "ReadDir()" frame. - // Thus the result will be e g 'ReadDir("/home")' - fmt::Debug::fmt(&*self.inner.root, f) - } -} - -impl Iterator for ReadDir { - type Item = io::Result; - - fn next(&mut self) -> Option> { - let entry = unsafe { - let mut out_entry = MaybeUninit::uninit(); - match error::SolidError::err_if_negative(abi::SOLID_FS_ReadDir( - self.inner.dirp, - out_entry.as_mut_ptr(), - )) { - Ok(_) => out_entry.assume_init(), - Err(e) if e.as_raw() == abi::SOLID_ERR_NOTFOUND => return None, - Err(e) => return Some(Err(e.as_io_error())), - } - }; - - (entry.d_name[0] != 0).then(|| Ok(DirEntry { entry, inner: Arc::clone(&self.inner) })) - } -} - -impl Drop for InnerReadDir { - fn drop(&mut self) { - unsafe { abi::SOLID_FS_CloseDir(self.dirp) }; - } -} - -impl DirEntry { - pub fn path(&self) -> PathBuf { - self.inner.root.join(OsStr::from_bytes( - unsafe { CStr::from_ptr(self.entry.d_name.as_ptr()) }.to_bytes(), - )) - } - - pub fn file_name(&self) -> OsString { - OsStr::from_bytes(unsafe { CStr::from_ptr(self.entry.d_name.as_ptr()) }.to_bytes()) - .to_os_string() - } - - pub fn metadata(&self) -> io::Result { - lstat(&self.path()) - } - - pub fn file_type(&self) -> io::Result { - match self.entry.d_type { - abi::DT_CHR => Ok(FileType(abi::S_IFCHR)), - abi::DT_FIFO => Ok(FileType(abi::S_IFIFO)), - abi::DT_REG => Ok(FileType(abi::S_IFREG)), - abi::DT_DIR => Ok(FileType(abi::S_IFDIR)), - abi::DT_BLK => Ok(FileType(abi::S_IFBLK)), - _ => lstat(&self.path()).map(|m| m.file_type()), - } - } -} - -impl OpenOptions { - pub fn new() -> OpenOptions { - OpenOptions { - // generic - read: false, - write: false, - append: false, - truncate: false, - create: false, - create_new: false, - // system-specific - custom_flags: 0, - } - } - - pub fn read(&mut self, read: bool) { - self.read = read; - } - pub fn write(&mut self, write: bool) { - self.write = write; - } - pub fn append(&mut self, append: bool) { - self.append = append; - } - pub fn truncate(&mut self, truncate: bool) { - self.truncate = truncate; - } - pub fn create(&mut self, create: bool) { - self.create = create; - } - pub fn create_new(&mut self, create_new: bool) { - self.create_new = create_new; - } - - pub fn custom_flags(&mut self, flags: i32) { - self.custom_flags = flags; - } - pub fn mode(&mut self, _mode: u32) {} - - fn get_access_mode(&self) -> io::Result { - match (self.read, self.write, self.append) { - (true, false, false) => Ok(abi::O_RDONLY), - (false, true, false) => Ok(abi::O_WRONLY), - (true, true, false) => Ok(abi::O_RDWR), - (false, _, true) => Ok(abi::O_WRONLY | abi::O_APPEND), - (true, _, true) => Ok(abi::O_RDWR | abi::O_APPEND), - (false, false, false) => Err(io::Error::from_raw_os_error(libc::EINVAL)), - } - } - - fn get_creation_mode(&self) -> io::Result { - match (self.write, self.append) { - (true, false) => {} - (false, false) => { - if self.truncate || self.create || self.create_new { - return Err(io::Error::from_raw_os_error(libc::EINVAL)); - } - } - (_, true) => { - if self.truncate && !self.create_new { - return Err(io::Error::from_raw_os_error(libc::EINVAL)); - } - } - } - - Ok(match (self.create, self.truncate, self.create_new) { - (false, false, false) => 0, - (true, false, false) => abi::O_CREAT, - (false, true, false) => abi::O_TRUNC, - (true, true, false) => abi::O_CREAT | abi::O_TRUNC, - (_, _, true) => abi::O_CREAT | abi::O_EXCL, - }) - } -} - -fn cstr(path: &Path) -> io::Result { - let path = path.as_os_str().as_bytes(); - - if !path.starts_with(br"\") { - // Relative paths aren't supported - return Err(crate::io::const_io_error!( - crate::io::ErrorKind::Unsupported, - "relative path is not supported on this platform", - )); - } - - // Apply the thread-safety wrapper - const SAFE_PREFIX: &[u8] = br"\TS"; - let wrapped_path = [SAFE_PREFIX, &path, &[0]].concat(); - - CString::from_vec_with_nul(wrapped_path).map_err(|_| { - crate::io::const_io_error!( - io::ErrorKind::InvalidInput, - "path provided contains a nul byte", - ) - }) -} - -impl File { - pub fn open(path: &Path, opts: &OpenOptions) -> io::Result { - let flags = opts.get_access_mode()? - | opts.get_creation_mode()? - | (opts.custom_flags as c_int & !abi::O_ACCMODE); - unsafe { - let mut fd = MaybeUninit::uninit(); - error::SolidError::err_if_negative(abi::SOLID_FS_Open( - fd.as_mut_ptr(), - cstr(path)?.as_ptr(), - flags, - )) - .map_err(|e| e.as_io_error())?; - Ok(File { fd: FileDesc::new(fd.assume_init()) }) - } - } - - pub fn file_attr(&self) -> io::Result { - unsupported() - } - - pub fn fsync(&self) -> io::Result<()> { - self.flush() - } - - pub fn datasync(&self) -> io::Result<()> { - self.flush() - } - - pub fn truncate(&self, _size: u64) -> io::Result<()> { - unsupported() - } - - pub fn read(&self, buf: &mut [u8]) -> io::Result { - unsafe { - let mut out_num_bytes = MaybeUninit::uninit(); - error::SolidError::err_if_negative(abi::SOLID_FS_Read( - self.fd.raw(), - buf.as_mut_ptr(), - buf.len(), - out_num_bytes.as_mut_ptr(), - )) - .map_err(|e| e.as_io_error())?; - Ok(out_num_bytes.assume_init()) - } - } - - pub fn read_buf(&self, mut cursor: BorrowedCursor<'_>) -> io::Result<()> { - unsafe { - let len = cursor.capacity(); - let mut out_num_bytes = MaybeUninit::uninit(); - error::SolidError::err_if_negative(abi::SOLID_FS_Read( - self.fd.raw(), - cursor.as_mut().as_mut_ptr() as *mut u8, - len, - out_num_bytes.as_mut_ptr(), - )) - .map_err(|e| e.as_io_error())?; - - // Safety: `out_num_bytes` is filled by the successful call to - // `SOLID_FS_Read` - let num_bytes_read = out_num_bytes.assume_init(); - - // Safety: `num_bytes_read` bytes were written to the unfilled - // portion of the buffer - cursor.advance_unchecked(num_bytes_read); - - Ok(()) - } - } - - pub fn read_vectored(&self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - crate::io::default_read_vectored(|buf| self.read(buf), bufs) - } - - pub fn is_read_vectored(&self) -> bool { - false - } - - pub fn write(&self, buf: &[u8]) -> io::Result { - unsafe { - let mut out_num_bytes = MaybeUninit::uninit(); - error::SolidError::err_if_negative(abi::SOLID_FS_Write( - self.fd.raw(), - buf.as_ptr(), - buf.len(), - out_num_bytes.as_mut_ptr(), - )) - .map_err(|e| e.as_io_error())?; - Ok(out_num_bytes.assume_init()) - } - } - - pub fn write_vectored(&self, bufs: &[IoSlice<'_>]) -> io::Result { - crate::io::default_write_vectored(|buf| self.write(buf), bufs) - } - - pub fn is_write_vectored(&self) -> bool { - false - } - - pub fn flush(&self) -> io::Result<()> { - error::SolidError::err_if_negative(unsafe { abi::SOLID_FS_Sync(self.fd.raw()) }) - .map_err(|e| e.as_io_error())?; - Ok(()) - } - - pub fn seek(&self, pos: SeekFrom) -> io::Result { - let (whence, pos) = match pos { - // Casting to `i64` is fine, too large values will end up as - // negative which will cause an error in `SOLID_FS_Lseek`. - SeekFrom::Start(off) => (abi::SEEK_SET, off as i64), - SeekFrom::End(off) => (abi::SEEK_END, off), - SeekFrom::Current(off) => (abi::SEEK_CUR, off), - }; - error::SolidError::err_if_negative(unsafe { - abi::SOLID_FS_Lseek(self.fd.raw(), pos, whence) - }) - .map_err(|e| e.as_io_error())?; - - // Get the new offset - unsafe { - let mut out_offset = MaybeUninit::uninit(); - error::SolidError::err_if_negative(abi::SOLID_FS_Ftell( - self.fd.raw(), - out_offset.as_mut_ptr(), - )) - .map_err(|e| e.as_io_error())?; - Ok(out_offset.assume_init() as u64) - } - } - - pub fn duplicate(&self) -> io::Result { - unsupported() - } - - pub fn set_permissions(&self, _perm: FilePermissions) -> io::Result<()> { - unsupported() - } - - pub fn set_times(&self, _times: FileTimes) -> io::Result<()> { - unsupported() - } -} - -impl Drop for File { - fn drop(&mut self) { - unsafe { abi::SOLID_FS_Close(self.fd.raw()) }; - } -} - -impl DirBuilder { - pub fn new() -> DirBuilder { - DirBuilder {} - } - - pub fn mkdir(&self, p: &Path) -> io::Result<()> { - error::SolidError::err_if_negative(unsafe { abi::SOLID_FS_Mkdir(cstr(p)?.as_ptr()) }) - .map_err(|e| e.as_io_error())?; - Ok(()) - } -} - -impl fmt::Debug for File { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("File").field("fd", &self.fd.raw()).finish() - } -} - -pub fn unlink(p: &Path) -> io::Result<()> { - if stat(p)?.file_type().is_dir() { - Err(io::const_io_error!(io::ErrorKind::IsADirectory, "is a directory")) - } else { - error::SolidError::err_if_negative(unsafe { abi::SOLID_FS_Unlink(cstr(p)?.as_ptr()) }) - .map_err(|e| e.as_io_error())?; - Ok(()) - } -} - -pub fn rename(old: &Path, new: &Path) -> io::Result<()> { - error::SolidError::err_if_negative(unsafe { - abi::SOLID_FS_Rename(cstr(old)?.as_ptr(), cstr(new)?.as_ptr()) - }) - .map_err(|e| e.as_io_error())?; - Ok(()) -} - -pub fn set_perm(p: &Path, perm: FilePermissions) -> io::Result<()> { - error::SolidError::err_if_negative(unsafe { - abi::SOLID_FS_Chmod(cstr(p)?.as_ptr(), perm.0.into()) - }) - .map_err(|e| e.as_io_error())?; - Ok(()) -} - -pub fn rmdir(p: &Path) -> io::Result<()> { - if stat(p)?.file_type().is_dir() { - error::SolidError::err_if_negative(unsafe { abi::SOLID_FS_Unlink(cstr(p)?.as_ptr()) }) - .map_err(|e| e.as_io_error())?; - Ok(()) - } else { - Err(io::const_io_error!(io::ErrorKind::NotADirectory, "not a directory")) - } -} - -pub fn remove_dir_all(path: &Path) -> io::Result<()> { - for child in readdir(path)? { - let child = child?; - let child_type = child.file_type()?; - if child_type.is_dir() { - remove_dir_all(&child.path())?; - } else { - unlink(&child.path())?; - } - } - rmdir(path) -} - -pub fn readlink(p: &Path) -> io::Result { - // This target doesn't support symlinks - stat(p)?; - Err(io::const_io_error!(io::ErrorKind::InvalidInput, "not a symbolic link")) -} - -pub fn symlink(_original: &Path, _link: &Path) -> io::Result<()> { - // This target doesn't support symlinks - unsupported() -} - -pub fn link(_src: &Path, _dst: &Path) -> io::Result<()> { - // This target doesn't support symlinks - unsupported() -} - -pub fn stat(p: &Path) -> io::Result { - // This target doesn't support symlinks - lstat(p) -} - -pub fn lstat(p: &Path) -> io::Result { - unsafe { - let mut out_stat = MaybeUninit::uninit(); - error::SolidError::err_if_negative(abi::SOLID_FS_Stat( - cstr(p)?.as_ptr(), - out_stat.as_mut_ptr(), - )) - .map_err(|e| e.as_io_error())?; - Ok(FileAttr { stat: out_stat.assume_init() }) - } -} - -pub fn canonicalize(_p: &Path) -> io::Result { - unsupported() -} - -pub fn copy(from: &Path, to: &Path) -> io::Result { - use crate::fs::File; - - let mut reader = File::open(from)?; - let mut writer = File::create(to)?; - - io::copy(&mut reader, &mut writer) -} diff --git a/library/std/src/sys/pal/solid/io.rs b/library/std/src/sys/pal/solid/io.rs deleted file mode 100644 index a862bb7870264..0000000000000 --- a/library/std/src/sys/pal/solid/io.rs +++ /dev/null @@ -1,81 +0,0 @@ -use crate::marker::PhantomData; -use crate::slice; - -use super::abi::sockets::iovec; -use libc::c_void; - -#[derive(Copy, Clone)] -#[repr(transparent)] -pub struct IoSlice<'a> { - vec: iovec, - _p: PhantomData<&'a [u8]>, -} - -impl<'a> IoSlice<'a> { - #[inline] - pub fn new(buf: &'a [u8]) -> IoSlice<'a> { - IoSlice { - vec: iovec { iov_base: buf.as_ptr() as *mut u8 as *mut c_void, iov_len: buf.len() }, - _p: PhantomData, - } - } - - #[inline] - pub fn advance(&mut self, n: usize) { - if self.vec.iov_len < n { - panic!("advancing IoSlice beyond its length"); - } - - unsafe { - self.vec.iov_len -= n; - self.vec.iov_base = self.vec.iov_base.add(n); - } - } - - #[inline] - pub fn as_slice(&self) -> &[u8] { - unsafe { slice::from_raw_parts(self.vec.iov_base as *mut u8, self.vec.iov_len) } - } -} - -#[repr(transparent)] -pub struct IoSliceMut<'a> { - vec: iovec, - _p: PhantomData<&'a mut [u8]>, -} - -impl<'a> IoSliceMut<'a> { - #[inline] - pub fn new(buf: &'a mut [u8]) -> IoSliceMut<'a> { - IoSliceMut { - vec: iovec { iov_base: buf.as_mut_ptr() as *mut c_void, iov_len: buf.len() }, - _p: PhantomData, - } - } - - #[inline] - pub fn advance(&mut self, n: usize) { - if self.vec.iov_len < n { - panic!("advancing IoSliceMut beyond its length"); - } - - unsafe { - self.vec.iov_len -= n; - self.vec.iov_base = self.vec.iov_base.add(n); - } - } - - #[inline] - pub fn as_slice(&self) -> &[u8] { - unsafe { slice::from_raw_parts(self.vec.iov_base as *mut u8, self.vec.iov_len) } - } - - #[inline] - pub fn as_mut_slice(&mut self) -> &mut [u8] { - unsafe { slice::from_raw_parts_mut(self.vec.iov_base as *mut u8, self.vec.iov_len) } - } -} - -pub fn is_terminal(_: &T) -> bool { - false -} diff --git a/library/std/src/sys/pal/solid/mod.rs b/library/std/src/sys/pal/solid/mod.rs deleted file mode 100644 index 3f6ff37903ac6..0000000000000 --- a/library/std/src/sys/pal/solid/mod.rs +++ /dev/null @@ -1,78 +0,0 @@ -#![allow(dead_code)] -#![allow(missing_docs, nonstandard_style)] -#![deny(unsafe_op_in_unsafe_fn)] - -pub mod abi; - -#[path = "../itron"] -pub mod itron { - pub mod abi; - pub mod error; - pub mod spin; - pub mod task; - pub mod thread; - pub mod thread_parking; - pub mod time; - use super::unsupported; -} - -pub mod alloc; -#[path = "../unsupported/args.rs"] -pub mod args; -pub mod env; -// `error` is `pub(crate)` so that it can be accessed by `itron/error.rs` as -// `crate::sys::error` -pub(crate) mod error; -pub mod fs; -pub mod io; -pub mod net; -pub mod os; -#[path = "../unsupported/pipe.rs"] -pub mod pipe; -#[path = "../unsupported/process.rs"] -pub mod process; -pub mod stdio; -pub use self::itron::thread; -pub mod thread_local_dtor; -pub mod thread_local_key; -pub use self::itron::thread_parking; -pub mod time; - -// SAFETY: must be called only once during runtime initialization. -// NOTE: this is not guaranteed to run, for example when Rust code is called externally. -pub unsafe fn init(_argc: isize, _argv: *const *const u8, _sigpipe: u8) {} - -// SAFETY: must be called only once during runtime cleanup. -pub unsafe fn cleanup() {} - -pub fn unsupported() -> crate::io::Result { - Err(unsupported_err()) -} - -pub fn unsupported_err() -> crate::io::Error { - crate::io::Error::UNSUPPORTED_PLATFORM -} - -#[inline] -pub fn is_interrupted(code: i32) -> bool { - net::is_interrupted(code) -} - -pub fn decode_error_kind(code: i32) -> crate::io::ErrorKind { - error::decode_error_kind(code) -} - -#[inline] -pub fn abort_internal() -> ! { - unsafe { libc::abort() } -} - -pub fn hashmap_random_keys() -> (u64, u64) { - unsafe { - let mut out = crate::mem::MaybeUninit::<[u64; 2]>::uninit(); - let result = abi::SOLID_RNG_SampleRandomBytes(out.as_mut_ptr() as *mut u8, 16); - assert_eq!(result, 0, "SOLID_RNG_SampleRandomBytes failed: {result}"); - let [x1, x2] = out.assume_init(); - (x1, x2) - } -} diff --git a/library/std/src/sys/pal/solid/net.rs b/library/std/src/sys/pal/solid/net.rs deleted file mode 100644 index 5bd339849e9dc..0000000000000 --- a/library/std/src/sys/pal/solid/net.rs +++ /dev/null @@ -1,429 +0,0 @@ -use super::abi; -use crate::{ - cmp, - ffi::CStr, - io::{self, BorrowedBuf, BorrowedCursor, ErrorKind, IoSlice, IoSliceMut}, - mem, - net::{Shutdown, SocketAddr}, - os::solid::io::{AsFd, AsRawFd, BorrowedFd, FromRawFd, IntoRawFd, OwnedFd}, - ptr, str, - sys_common::net::{getsockopt, setsockopt, sockaddr_to_addr}, - sys_common::{FromInner, IntoInner}, - time::Duration, -}; - -use self::netc::{sockaddr, socklen_t, MSG_PEEK}; -use libc::{c_int, c_void, size_t}; - -pub mod netc { - pub use super::super::abi::sockets::*; -} - -pub type wrlen_t = size_t; - -const READ_LIMIT: usize = libc::ssize_t::MAX as usize; - -const fn max_iov() -> usize { - // Judging by the source code, it's unlimited, but specify a lower - // value just in case. - 1024 -} - -#[doc(hidden)] -pub trait IsMinusOne { - fn is_minus_one(&self) -> bool; -} - -macro_rules! impl_is_minus_one { - ($($t:ident)*) => ($(impl IsMinusOne for $t { - fn is_minus_one(&self) -> bool { - *self == -1 - } - })*) -} - -impl_is_minus_one! { i8 i16 i32 i64 isize } - -pub fn cvt(t: T) -> io::Result { - if t.is_minus_one() { Err(last_error()) } else { Ok(t) } -} - -/// A variant of `cvt` for `getaddrinfo` which return 0 for a success. -pub fn cvt_gai(err: c_int) -> io::Result<()> { - if err == 0 { - Ok(()) - } else { - let msg: &dyn crate::fmt::Display = match err { - netc::EAI_NONAME => &"name or service not known", - netc::EAI_SERVICE => &"service not supported", - netc::EAI_FAIL => &"non-recoverable failure in name resolution", - netc::EAI_MEMORY => &"memory allocation failure", - netc::EAI_FAMILY => &"family not supported", - _ => &err, - }; - Err(io::Error::new( - io::ErrorKind::Uncategorized, - &format!("failed to lookup address information: {msg}")[..], - )) - } -} - -/// Just to provide the same interface as sys/pal/unix/net.rs -pub fn cvt_r(mut f: F) -> io::Result -where - T: IsMinusOne, - F: FnMut() -> T, -{ - cvt(f()) -} - -/// Returns the last error from the network subsystem. -fn last_error() -> io::Error { - io::Error::from_raw_os_error(unsafe { netc::SOLID_NET_GetLastError() }) -} - -pub(super) fn error_name(er: abi::ER) -> Option<&'static str> { - unsafe { CStr::from_ptr(netc::strerror(er)) }.to_str().ok() -} - -#[inline] -pub fn is_interrupted(er: abi::ER) -> bool { - er == netc::SOLID_NET_ERR_BASE - libc::EINTR -} - -pub(super) fn decode_error_kind(er: abi::ER) -> ErrorKind { - let errno = netc::SOLID_NET_ERR_BASE - er; - match errno as libc::c_int { - libc::ECONNREFUSED => ErrorKind::ConnectionRefused, - libc::ECONNRESET => ErrorKind::ConnectionReset, - libc::EPERM | libc::EACCES => ErrorKind::PermissionDenied, - libc::EPIPE => ErrorKind::BrokenPipe, - libc::ENOTCONN => ErrorKind::NotConnected, - libc::ECONNABORTED => ErrorKind::ConnectionAborted, - libc::EADDRNOTAVAIL => ErrorKind::AddrNotAvailable, - libc::EADDRINUSE => ErrorKind::AddrInUse, - libc::ENOENT => ErrorKind::NotFound, - libc::EINTR => ErrorKind::Interrupted, - libc::EINVAL => ErrorKind::InvalidInput, - libc::ETIMEDOUT => ErrorKind::TimedOut, - libc::EEXIST => ErrorKind::AlreadyExists, - libc::ENOSYS => ErrorKind::Unsupported, - libc::ENOMEM => ErrorKind::OutOfMemory, - libc::EAGAIN => ErrorKind::WouldBlock, - - _ => ErrorKind::Uncategorized, - } -} - -pub fn init() {} - -pub struct Socket(OwnedFd); - -impl Socket { - pub fn new(addr: &SocketAddr, ty: c_int) -> io::Result { - let fam = match *addr { - SocketAddr::V4(..) => netc::AF_INET, - SocketAddr::V6(..) => netc::AF_INET6, - }; - Socket::new_raw(fam, ty) - } - - pub fn new_raw(fam: c_int, ty: c_int) -> io::Result { - unsafe { - let fd = cvt(netc::socket(fam, ty, 0))?; - Ok(Self::from_raw_fd(fd)) - } - } - - pub fn connect(&self, addr: &SocketAddr) -> io::Result<()> { - let (addr, len) = addr.into_inner(); - cvt(unsafe { netc::connect(self.as_raw_fd(), addr.as_ptr(), len) })?; - Ok(()) - } - - pub fn connect_timeout(&self, addr: &SocketAddr, timeout: Duration) -> io::Result<()> { - self.set_nonblocking(true)?; - let r = self.connect(addr); - self.set_nonblocking(false)?; - - match r { - Ok(_) => return Ok(()), - // there's no ErrorKind for EINPROGRESS - Err(ref e) if e.raw_os_error() == Some(netc::EINPROGRESS) => {} - Err(e) => return Err(e), - } - - if timeout.as_secs() == 0 && timeout.subsec_nanos() == 0 { - return Err(io::Error::ZERO_TIMEOUT); - } - - let mut timeout = - netc::timeval { tv_sec: timeout.as_secs() as _, tv_usec: timeout.subsec_micros() as _ }; - if timeout.tv_sec == 0 && timeout.tv_usec == 0 { - timeout.tv_usec = 1; - } - - let fds = netc::fd_set { num_fds: 1, fds: [self.as_raw_fd()] }; - - let mut writefds = fds; - let mut errorfds = fds; - - let n = unsafe { - cvt(netc::select( - self.as_raw_fd() + 1, - ptr::null_mut(), - &mut writefds, - &mut errorfds, - &mut timeout, - ))? - }; - - match n { - 0 => Err(io::const_io_error!(io::ErrorKind::TimedOut, "connection timed out")), - _ => { - let can_write = writefds.num_fds != 0; - if !can_write { - if let Some(e) = self.take_error()? { - return Err(e); - } - } - Ok(()) - } - } - } - - pub fn accept(&self, storage: *mut sockaddr, len: *mut socklen_t) -> io::Result { - let fd = cvt_r(|| unsafe { netc::accept(self.as_raw_fd(), storage, len) })?; - unsafe { Ok(Self::from_raw_fd(fd)) } - } - - pub fn duplicate(&self) -> io::Result { - Ok(Self(self.0.try_clone()?)) - } - - fn recv_with_flags(&self, mut buf: BorrowedCursor<'_>, flags: c_int) -> io::Result<()> { - let ret = cvt(unsafe { - netc::recv(self.as_raw_fd(), buf.as_mut().as_mut_ptr().cast(), buf.capacity(), flags) - })?; - unsafe { - buf.advance_unchecked(ret as usize); - } - Ok(()) - } - - pub fn read(&self, buf: &mut [u8]) -> io::Result { - let mut buf = BorrowedBuf::from(buf); - self.recv_with_flags(buf.unfilled(), 0)?; - Ok(buf.len()) - } - - pub fn peek(&self, buf: &mut [u8]) -> io::Result { - let mut buf = BorrowedBuf::from(buf); - self.recv_with_flags(buf.unfilled(), MSG_PEEK)?; - Ok(buf.len()) - } - - pub fn read_buf(&self, buf: BorrowedCursor<'_>) -> io::Result<()> { - self.recv_with_flags(buf, 0) - } - - pub fn read_vectored(&self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - let ret = cvt(unsafe { - netc::readv( - self.as_raw_fd(), - bufs.as_ptr() as *const netc::iovec, - cmp::min(bufs.len(), max_iov()) as c_int, - ) - })?; - Ok(ret as usize) - } - - #[inline] - pub fn is_read_vectored(&self) -> bool { - true - } - - fn recv_from_with_flags( - &self, - buf: &mut [u8], - flags: c_int, - ) -> io::Result<(usize, SocketAddr)> { - let mut storage: netc::sockaddr_storage = unsafe { mem::zeroed() }; - let mut addrlen = mem::size_of_val(&storage) as netc::socklen_t; - - let n = cvt(unsafe { - netc::recvfrom( - self.as_raw_fd(), - buf.as_mut_ptr() as *mut c_void, - buf.len(), - flags, - &mut storage as *mut _ as *mut _, - &mut addrlen, - ) - })?; - Ok((n as usize, sockaddr_to_addr(&storage, addrlen as usize)?)) - } - - pub fn recv_from(&self, buf: &mut [u8]) -> io::Result<(usize, SocketAddr)> { - self.recv_from_with_flags(buf, 0) - } - - pub fn peek_from(&self, buf: &mut [u8]) -> io::Result<(usize, SocketAddr)> { - self.recv_from_with_flags(buf, MSG_PEEK) - } - - pub fn write(&self, buf: &[u8]) -> io::Result { - let ret = cvt(unsafe { - netc::write( - self.as_raw_fd(), - buf.as_ptr() as *const c_void, - cmp::min(buf.len(), READ_LIMIT), - ) - })?; - Ok(ret as usize) - } - - pub fn write_vectored(&self, bufs: &[IoSlice<'_>]) -> io::Result { - let ret = cvt(unsafe { - netc::writev( - self.as_raw_fd(), - bufs.as_ptr() as *const netc::iovec, - cmp::min(bufs.len(), max_iov()) as c_int, - ) - })?; - Ok(ret as usize) - } - - #[inline] - pub fn is_write_vectored(&self) -> bool { - true - } - - pub fn set_timeout(&self, dur: Option, kind: c_int) -> io::Result<()> { - let timeout = match dur { - Some(dur) => { - if dur.as_secs() == 0 && dur.subsec_nanos() == 0 { - return Err(io::Error::ZERO_TIMEOUT); - } - - let secs = if dur.as_secs() > netc::c_long::MAX as u64 { - netc::c_long::MAX - } else { - dur.as_secs() as netc::c_long - }; - let mut timeout = netc::timeval { tv_sec: secs, tv_usec: dur.subsec_micros() as _ }; - if timeout.tv_sec == 0 && timeout.tv_usec == 0 { - timeout.tv_usec = 1; - } - timeout - } - None => netc::timeval { tv_sec: 0, tv_usec: 0 }, - }; - setsockopt(self, netc::SOL_SOCKET, kind, timeout) - } - - pub fn timeout(&self, kind: c_int) -> io::Result> { - let raw: netc::timeval = getsockopt(self, netc::SOL_SOCKET, kind)?; - if raw.tv_sec == 0 && raw.tv_usec == 0 { - Ok(None) - } else { - let sec = raw.tv_sec as u64; - let nsec = (raw.tv_usec as u32) * 1000; - Ok(Some(Duration::new(sec, nsec))) - } - } - - pub fn shutdown(&self, how: Shutdown) -> io::Result<()> { - let how = match how { - Shutdown::Write => netc::SHUT_WR, - Shutdown::Read => netc::SHUT_RD, - Shutdown::Both => netc::SHUT_RDWR, - }; - cvt(unsafe { netc::shutdown(self.as_raw_fd(), how) })?; - Ok(()) - } - - pub fn set_linger(&self, linger: Option) -> io::Result<()> { - let linger = netc::linger { - l_onoff: linger.is_some() as netc::c_int, - l_linger: linger.unwrap_or_default().as_secs() as netc::c_int, - }; - - setsockopt(self, netc::SOL_SOCKET, netc::SO_LINGER, linger) - } - - pub fn linger(&self) -> io::Result> { - let val: netc::linger = getsockopt(self, netc::SOL_SOCKET, netc::SO_LINGER)?; - - Ok((val.l_onoff != 0).then(|| Duration::from_secs(val.l_linger as u64))) - } - - pub fn set_nodelay(&self, nodelay: bool) -> io::Result<()> { - setsockopt(self, netc::IPPROTO_TCP, netc::TCP_NODELAY, nodelay as c_int) - } - - pub fn nodelay(&self) -> io::Result { - let raw: c_int = getsockopt(self, netc::IPPROTO_TCP, netc::TCP_NODELAY)?; - Ok(raw != 0) - } - - pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> { - let mut nonblocking = nonblocking as c_int; - cvt(unsafe { - netc::ioctl(self.as_raw_fd(), netc::FIONBIO, (&mut nonblocking) as *mut c_int as _) - }) - .map(drop) - } - - pub fn take_error(&self) -> io::Result> { - let raw: c_int = getsockopt(self, netc::SOL_SOCKET, netc::SO_ERROR)?; - if raw == 0 { Ok(None) } else { Ok(Some(io::Error::from_raw_os_error(raw as i32))) } - } - - // This method is used by sys_common code to abstract over targets. - pub fn as_raw(&self) -> c_int { - self.as_raw_fd() - } -} - -impl FromInner for Socket { - #[inline] - fn from_inner(sock: OwnedFd) -> Socket { - Socket(sock) - } -} - -impl IntoInner for Socket { - #[inline] - fn into_inner(self) -> OwnedFd { - self.0 - } -} - -impl AsFd for Socket { - #[inline] - fn as_fd(&self) -> BorrowedFd<'_> { - self.0.as_fd() - } -} - -impl AsRawFd for Socket { - #[inline] - fn as_raw_fd(&self) -> c_int { - self.0.as_raw_fd() - } -} - -impl FromRawFd for Socket { - #[inline] - unsafe fn from_raw_fd(fd: c_int) -> Socket { - unsafe { Self(FromRawFd::from_raw_fd(fd)) } - } -} - -impl IntoRawFd for Socket { - #[inline] - fn into_raw_fd(self) -> c_int { - self.0.into_raw_fd() - } -} diff --git a/library/std/src/sys/pal/solid/os.rs b/library/std/src/sys/pal/solid/os.rs deleted file mode 100644 index ef35d8788a236..0000000000000 --- a/library/std/src/sys/pal/solid/os.rs +++ /dev/null @@ -1,230 +0,0 @@ -use super::unsupported; -use crate::error::Error as StdError; -use crate::ffi::{CStr, OsStr, OsString}; -use crate::fmt; -use crate::io; -use crate::os::{ - raw::{c_char, c_int}, - solid::ffi::{OsStrExt, OsStringExt}, -}; -use crate::path::{self, PathBuf}; -use crate::sync::{PoisonError, RwLock}; -use crate::sys::common::small_c_string::run_with_cstr; -use crate::vec; - -use super::{error, itron}; - -use core::slice::memchr; - -// `solid` directly maps `errno`s to μITRON error codes. -impl itron::error::ItronError { - #[inline] - pub(crate) fn as_io_error(self) -> crate::io::Error { - crate::io::Error::from_raw_os_error(self.as_raw()) - } -} - -pub fn errno() -> i32 { - 0 -} - -pub fn error_string(errno: i32) -> String { - if let Some(name) = error::error_name(errno) { name.to_owned() } else { format!("{errno}") } -} - -pub fn getcwd() -> io::Result { - unsupported() -} - -pub fn chdir(_: &path::Path) -> io::Result<()> { - unsupported() -} - -pub struct SplitPaths<'a>(&'a !); - -pub fn split_paths(_unparsed: &OsStr) -> SplitPaths<'_> { - panic!("unsupported") -} - -impl<'a> Iterator for SplitPaths<'a> { - type Item = PathBuf; - fn next(&mut self) -> Option { - *self.0 - } -} - -#[derive(Debug)] -pub struct JoinPathsError; - -pub fn join_paths(_paths: I) -> Result -where - I: Iterator, - T: AsRef, -{ - Err(JoinPathsError) -} - -impl fmt::Display for JoinPathsError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - "not supported on this platform yet".fmt(f) - } -} - -impl StdError for JoinPathsError { - #[allow(deprecated)] - fn description(&self) -> &str { - "not supported on this platform yet" - } -} - -pub fn current_exe() -> io::Result { - unsupported() -} - -static ENV_LOCK: RwLock<()> = RwLock::new(()); - -pub fn env_read_lock() -> impl Drop { - ENV_LOCK.read().unwrap_or_else(PoisonError::into_inner) -} - -pub struct Env { - iter: vec::IntoIter<(OsString, OsString)>, -} - -// FIXME(https://github.com/rust-lang/rust/issues/114583): Remove this when ::fmt matches ::fmt. -pub struct EnvStrDebug<'a> { - slice: &'a [(OsString, OsString)], -} - -impl fmt::Debug for EnvStrDebug<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let Self { slice } = self; - f.debug_list() - .entries(slice.iter().map(|(a, b)| (a.to_str().unwrap(), b.to_str().unwrap()))) - .finish() - } -} - -impl Env { - pub fn str_debug(&self) -> impl fmt::Debug + '_ { - let Self { iter } = self; - EnvStrDebug { slice: iter.as_slice() } - } -} - -impl fmt::Debug for Env { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let Self { iter } = self; - f.debug_list().entries(iter.as_slice()).finish() - } -} - -impl !Send for Env {} -impl !Sync for Env {} - -impl Iterator for Env { - type Item = (OsString, OsString); - fn next(&mut self) -> Option<(OsString, OsString)> { - self.iter.next() - } - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } -} - -/// Returns a vector of (variable, value) byte-vector pairs for all the -/// environment variables of the current process. -pub fn env() -> Env { - extern "C" { - static mut environ: *const *const c_char; - } - - unsafe { - let _guard = env_read_lock(); - let mut result = Vec::new(); - if !environ.is_null() { - while !(*environ).is_null() { - if let Some(key_value) = parse(CStr::from_ptr(*environ).to_bytes()) { - result.push(key_value); - } - environ = environ.add(1); - } - } - return Env { iter: result.into_iter() }; - } - - fn parse(input: &[u8]) -> Option<(OsString, OsString)> { - // Strategy (copied from glibc): Variable name and value are separated - // by an ASCII equals sign '='. Since a variable name must not be - // empty, allow variable names starting with an equals sign. Skip all - // malformed lines. - if input.is_empty() { - return None; - } - let pos = memchr::memchr(b'=', &input[1..]).map(|p| p + 1); - pos.map(|p| { - ( - OsStringExt::from_vec(input[..p].to_vec()), - OsStringExt::from_vec(input[p + 1..].to_vec()), - ) - }) - } -} - -pub fn getenv(k: &OsStr) -> Option { - // environment variables with a nul byte can't be set, so their value is - // always None as well - run_with_cstr(k.as_bytes(), &|k| { - let _guard = env_read_lock(); - let v = unsafe { libc::getenv(k.as_ptr()) } as *const libc::c_char; - - if v.is_null() { - Ok(None) - } else { - // SAFETY: `v` cannot be mutated while executing this line since we've a read lock - let bytes = unsafe { CStr::from_ptr(v) }.to_bytes().to_vec(); - - Ok(Some(OsStringExt::from_vec(bytes))) - } - }) - .ok() - .flatten() -} - -pub fn setenv(k: &OsStr, v: &OsStr) -> io::Result<()> { - run_with_cstr(k.as_bytes(), &|k| { - run_with_cstr(v.as_bytes(), &|v| { - let _guard = ENV_LOCK.write(); - cvt_env(unsafe { libc::setenv(k.as_ptr(), v.as_ptr(), 1) }).map(drop) - }) - }) -} - -pub fn unsetenv(n: &OsStr) -> io::Result<()> { - run_with_cstr(n.as_bytes(), &|nbuf| { - let _guard = ENV_LOCK.write(); - cvt_env(unsafe { libc::unsetenv(nbuf.as_ptr()) }).map(drop) - }) -} - -/// In kmclib, `setenv` and `unsetenv` don't always set `errno`, so this -/// function just returns a generic error. -fn cvt_env(t: c_int) -> io::Result { - if t == -1 { Err(io::const_io_error!(io::ErrorKind::Uncategorized, "failure")) } else { Ok(t) } -} - -pub fn temp_dir() -> PathBuf { - panic!("no standard temporary directory on this platform") -} - -pub fn home_dir() -> Option { - None -} - -pub fn exit(code: i32) -> ! { - rtabort!("exit({}) called", code); -} - -pub fn getpid() -> u32 { - panic!("no pids on this platform") -} diff --git a/library/std/src/sys/pal/solid/stdio.rs b/library/std/src/sys/pal/solid/stdio.rs deleted file mode 100644 index 50f0176967b2d..0000000000000 --- a/library/std/src/sys/pal/solid/stdio.rs +++ /dev/null @@ -1,80 +0,0 @@ -use super::abi; -use crate::io; - -pub struct Stdin; -pub struct Stdout; -pub struct Stderr; -struct PanicOutput; - -impl Stdin { - pub const fn new() -> Stdin { - Stdin - } -} - -impl io::Read for Stdin { - fn read(&mut self, _buf: &mut [u8]) -> io::Result { - Ok(0) - } -} - -impl Stdout { - pub const fn new() -> Stdout { - Stdout - } -} - -impl io::Write for Stdout { - fn write(&mut self, buf: &[u8]) -> io::Result { - unsafe { abi::SOLID_LOG_write(buf.as_ptr(), buf.len()) }; - Ok(buf.len()) - } - - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -impl Stderr { - pub const fn new() -> Stderr { - Stderr - } -} - -impl io::Write for Stderr { - fn write(&mut self, buf: &[u8]) -> io::Result { - unsafe { abi::SOLID_LOG_write(buf.as_ptr(), buf.len()) }; - Ok(buf.len()) - } - - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -impl PanicOutput { - pub const fn new() -> PanicOutput { - PanicOutput - } -} - -impl io::Write for PanicOutput { - fn write(&mut self, buf: &[u8]) -> io::Result { - unsafe { abi::SOLID_LOG_write(buf.as_ptr(), buf.len()) }; - Ok(buf.len()) - } - - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -pub const STDIN_BUF_SIZE: usize = 0; - -pub fn is_ebadf(_err: &io::Error) -> bool { - true -} - -pub fn panic_output() -> Option { - Some(PanicOutput::new()) -} diff --git a/library/std/src/sys/pal/solid/thread_local_dtor.rs b/library/std/src/sys/pal/solid/thread_local_dtor.rs deleted file mode 100644 index 26918a4fcb012..0000000000000 --- a/library/std/src/sys/pal/solid/thread_local_dtor.rs +++ /dev/null @@ -1,43 +0,0 @@ -#![cfg(target_thread_local)] -#![unstable(feature = "thread_local_internals", issue = "none")] - -// Simplify dtor registration by using a list of destructors. - -use super::{abi, itron::task}; -use crate::cell::{Cell, RefCell}; - -#[thread_local] -static REGISTERED: Cell = Cell::new(false); - -#[thread_local] -static DTORS: RefCell> = RefCell::new(Vec::new()); - -pub unsafe fn register_dtor(t: *mut u8, dtor: unsafe extern "C" fn(*mut u8)) { - if !REGISTERED.get() { - let tid = task::current_task_id_aborting(); - // Register `tls_dtor` to make sure the TLS destructors are called - // for tasks created by other means than `std::thread` - unsafe { abi::SOLID_TLS_AddDestructor(tid as i32, tls_dtor) }; - REGISTERED.set(true); - } - - match DTORS.try_borrow_mut() { - Ok(mut dtors) => dtors.push((t, dtor)), - Err(_) => rtabort!("global allocator may not use TLS"), - } -} - -pub unsafe fn run_dtors() { - let mut list = DTORS.take(); - while !list.is_empty() { - for (ptr, dtor) in list { - unsafe { dtor(ptr) }; - } - - list = DTORS.take(); - } -} - -unsafe extern "C" fn tls_dtor(_unused: *mut u8) { - unsafe { run_dtors() }; -} diff --git a/library/std/src/sys/pal/solid/thread_local_key.rs b/library/std/src/sys/pal/solid/thread_local_key.rs deleted file mode 100644 index b37bf99969887..0000000000000 --- a/library/std/src/sys/pal/solid/thread_local_key.rs +++ /dev/null @@ -1,21 +0,0 @@ -pub type Key = usize; - -#[inline] -pub unsafe fn create(_dtor: Option) -> Key { - panic!("should not be used on the solid target"); -} - -#[inline] -pub unsafe fn set(_key: Key, _value: *mut u8) { - panic!("should not be used on the solid target"); -} - -#[inline] -pub unsafe fn get(_key: Key) -> *mut u8 { - panic!("should not be used on the solid target"); -} - -#[inline] -pub unsafe fn destroy(_key: Key) { - panic!("should not be used on the solid target"); -} diff --git a/library/std/src/sys/pal/solid/time.rs b/library/std/src/sys/pal/solid/time.rs deleted file mode 100644 index f83f1644fe854..0000000000000 --- a/library/std/src/sys/pal/solid/time.rs +++ /dev/null @@ -1,56 +0,0 @@ -use super::{abi, error::expect_success}; -use crate::{mem::MaybeUninit, time::Duration}; - -pub use super::itron::time::Instant; - -#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)] -pub struct SystemTime(abi::time_t); - -pub const UNIX_EPOCH: SystemTime = SystemTime(0); - -impl SystemTime { - pub fn now() -> SystemTime { - let rtc = unsafe { - let mut out = MaybeUninit::zeroed(); - expect_success(abi::SOLID_RTC_ReadTime(out.as_mut_ptr()), &"SOLID_RTC_ReadTime"); - out.assume_init() - }; - let t = unsafe { - libc::mktime(&mut libc::tm { - tm_sec: rtc.tm_sec, - tm_min: rtc.tm_min, - tm_hour: rtc.tm_hour, - tm_mday: rtc.tm_mday, - tm_mon: rtc.tm_mon - 1, - tm_year: rtc.tm_year, - tm_wday: rtc.tm_wday, - tm_yday: 0, - tm_isdst: 0, - tm_gmtoff: 0, - tm_zone: crate::ptr::null_mut(), - }) - }; - assert_ne!(t, -1, "mktime failed"); - SystemTime(t) - } - - pub(super) fn from_time_t(t: abi::time_t) -> Self { - Self(t) - } - - pub fn sub_time(&self, other: &SystemTime) -> Result { - if self.0 >= other.0 { - Ok(Duration::from_secs((self.0 as u64).wrapping_sub(other.0 as u64))) - } else { - Err(Duration::from_secs((other.0 as u64).wrapping_sub(self.0 as u64))) - } - } - - pub fn checked_add_duration(&self, other: &Duration) -> Option { - Some(SystemTime(self.0.checked_add_unsigned(other.as_secs())?)) - } - - pub fn checked_sub_duration(&self, other: &Duration) -> Option { - Some(SystemTime(self.0.checked_sub_unsigned(other.as_secs())?)) - } -} diff --git a/library/std/src/sys/pal/teeos/alloc.rs b/library/std/src/sys/pal/teeos/alloc.rs deleted file mode 100644 index e236819aa2388..0000000000000 --- a/library/std/src/sys/pal/teeos/alloc.rs +++ /dev/null @@ -1,57 +0,0 @@ -use crate::alloc::{GlobalAlloc, Layout, System}; -use crate::ptr; -use crate::sys::common::alloc::{realloc_fallback, MIN_ALIGN}; - -#[stable(feature = "alloc_system_type", since = "1.28.0")] -unsafe impl GlobalAlloc for System { - #[inline] - unsafe fn alloc(&self, layout: Layout) -> *mut u8 { - // jemalloc provides alignment less than MIN_ALIGN for small allocations. - // So only rely on MIN_ALIGN if size >= align. - // Also see and - // . - if layout.align() <= MIN_ALIGN && layout.align() <= layout.size() { - libc::malloc(layout.size()) as *mut u8 - } else { - aligned_malloc(&layout) - } - } - - #[inline] - unsafe fn alloc_zeroed(&self, layout: Layout) -> *mut u8 { - // See the comment above in `alloc` for why this check looks the way it does. - if layout.align() <= MIN_ALIGN && layout.align() <= layout.size() { - libc::calloc(layout.size(), 1) as *mut u8 - } else { - let ptr = self.alloc(layout); - if !ptr.is_null() { - ptr::write_bytes(ptr, 0, layout.size()); - } - ptr - } - } - - #[inline] - unsafe fn dealloc(&self, ptr: *mut u8, _layout: Layout) { - libc::free(ptr as *mut libc::c_void) - } - - #[inline] - unsafe fn realloc(&self, ptr: *mut u8, layout: Layout, new_size: usize) -> *mut u8 { - if layout.align() <= MIN_ALIGN && layout.align() <= new_size { - libc::realloc(ptr as *mut libc::c_void, new_size) as *mut u8 - } else { - realloc_fallback(self, ptr, layout, new_size) - } - } -} - -#[inline] -unsafe fn aligned_malloc(layout: &Layout) -> *mut u8 { - let mut out = ptr::null_mut(); - // posix_memalign requires that the alignment be a multiple of `sizeof(void*)`. - // Since these are all powers of 2, we can just use max. - let align = layout.align().max(crate::mem::size_of::()); - let ret = libc::posix_memalign(&mut out, align, layout.size()); - if ret != 0 { ptr::null_mut() } else { out as *mut u8 } -} diff --git a/library/std/src/sys/pal/teeos/mod.rs b/library/std/src/sys/pal/teeos/mod.rs deleted file mode 100644 index 6dd465a12ed49..0000000000000 --- a/library/std/src/sys/pal/teeos/mod.rs +++ /dev/null @@ -1,154 +0,0 @@ -//! System bindings for the Teeos platform -//! -//! This module contains the facade (aka platform-specific) implementations of -//! OS level functionality for Teeos. -#![allow(unsafe_op_in_unsafe_fn)] -#![allow(unused_variables)] -#![allow(dead_code)] - -pub use self::rand::hashmap_random_keys; - -pub mod alloc; -#[path = "../unsupported/args.rs"] -pub mod args; -#[path = "../unsupported/env.rs"] -pub mod env; -//pub mod fd; -#[path = "../unsupported/fs.rs"] -pub mod fs; -#[path = "../unsupported/io.rs"] -pub mod io; -pub mod net; -pub mod os; -#[path = "../unsupported/pipe.rs"] -pub mod pipe; -#[path = "../unsupported/process.rs"] -pub mod process; -mod rand; -pub mod stdio; -pub mod thread; -pub mod thread_local_dtor; -#[path = "../unix/thread_local_key.rs"] -pub mod thread_local_key; -#[allow(non_upper_case_globals)] -#[path = "../unix/time.rs"] -pub mod time; - -use crate::io::ErrorKind; - -pub fn abort_internal() -> ! { - unsafe { libc::abort() } -} - -// Trusted Applications are loaded as dynamic libraries on Teeos, -// so this should never be called. -pub fn init(argc: isize, argv: *const *const u8, sigpipe: u8) {} - -// SAFETY: must be called only once during runtime cleanup. -// this is not guaranteed to run, for example when the program aborts. -pub unsafe fn cleanup() { - unimplemented!() - // We do NOT have stack overflow handler, because TEE OS will kill TA when it happens. - // So cleanup is commented - // stack_overflow::cleanup(); -} - -#[inline] -pub(crate) fn is_interrupted(errno: i32) -> bool { - errno == libc::EINTR -} - -// Note: code below is 1:1 copied from unix/mod.rs -pub fn decode_error_kind(errno: i32) -> ErrorKind { - use ErrorKind::*; - match errno as libc::c_int { - libc::E2BIG => ArgumentListTooLong, - libc::EADDRINUSE => AddrInUse, - libc::EADDRNOTAVAIL => AddrNotAvailable, - libc::EBUSY => ResourceBusy, - libc::ECONNABORTED => ConnectionAborted, - libc::ECONNREFUSED => ConnectionRefused, - libc::ECONNRESET => ConnectionReset, - libc::EDEADLK => Deadlock, - libc::EDQUOT => FilesystemQuotaExceeded, - libc::EEXIST => AlreadyExists, - libc::EFBIG => FileTooLarge, - libc::EHOSTUNREACH => HostUnreachable, - libc::EINTR => Interrupted, - libc::EINVAL => InvalidInput, - libc::EISDIR => IsADirectory, - libc::ELOOP => FilesystemLoop, - libc::ENOENT => NotFound, - libc::ENOMEM => OutOfMemory, - libc::ENOSPC => StorageFull, - libc::ENOSYS => Unsupported, - libc::EMLINK => TooManyLinks, - libc::ENAMETOOLONG => InvalidFilename, - libc::ENETDOWN => NetworkDown, - libc::ENETUNREACH => NetworkUnreachable, - libc::ENOTCONN => NotConnected, - libc::ENOTDIR => NotADirectory, - libc::ENOTEMPTY => DirectoryNotEmpty, - libc::EPIPE => BrokenPipe, - libc::EROFS => ReadOnlyFilesystem, - libc::ESPIPE => NotSeekable, - libc::ESTALE => StaleNetworkFileHandle, - libc::ETIMEDOUT => TimedOut, - libc::ETXTBSY => ExecutableFileBusy, - libc::EXDEV => CrossesDevices, - - libc::EACCES | libc::EPERM => PermissionDenied, - - // These two constants can have the same value on some systems, - // but different values on others, so we can't use a match - // clause - x if x == libc::EAGAIN || x == libc::EWOULDBLOCK => WouldBlock, - - _ => Uncategorized, - } -} - -#[doc(hidden)] -pub trait IsMinusOne { - fn is_minus_one(&self) -> bool; -} - -macro_rules! impl_is_minus_one { - ($($t:ident)*) => ($(impl IsMinusOne for $t { - fn is_minus_one(&self) -> bool { - *self == -1 - } - })*) -} - -impl_is_minus_one! { i8 i16 i32 i64 isize } - -pub fn cvt(t: T) -> crate::io::Result { - if t.is_minus_one() { Err(crate::io::Error::last_os_error()) } else { Ok(t) } -} - -pub fn cvt_r(mut f: F) -> crate::io::Result -where - T: IsMinusOne, - F: FnMut() -> T, -{ - loop { - match cvt(f()) { - Err(ref e) if e.kind() == ErrorKind::Interrupted => {} - other => return other, - } - } -} - -pub fn cvt_nz(error: libc::c_int) -> crate::io::Result<()> { - if error == 0 { Ok(()) } else { Err(crate::io::Error::from_raw_os_error(error)) } -} - -use crate::io as std_io; -pub fn unsupported() -> std_io::Result { - Err(unsupported_err()) -} - -pub fn unsupported_err() -> std_io::Error { - std_io::Error::new(std_io::ErrorKind::Unsupported, "operation not supported on this platform") -} diff --git a/library/std/src/sys/pal/teeos/net.rs b/library/std/src/sys/pal/teeos/net.rs deleted file mode 100644 index fed95205027a7..0000000000000 --- a/library/std/src/sys/pal/teeos/net.rs +++ /dev/null @@ -1,369 +0,0 @@ -use crate::fmt; -use crate::io::{self, BorrowedCursor, IoSlice, IoSliceMut}; -use crate::net::{Ipv4Addr, Ipv6Addr, Shutdown, SocketAddr}; -use crate::sys::unsupported; -use crate::time::Duration; - -pub struct TcpStream(!); - -impl TcpStream { - pub fn connect(_: io::Result<&SocketAddr>) -> io::Result { - unsupported() - } - - pub fn connect_timeout(_: &SocketAddr, _: Duration) -> io::Result { - unsupported() - } - - pub fn set_read_timeout(&self, _: Option) -> io::Result<()> { - self.0 - } - - pub fn set_write_timeout(&self, _: Option) -> io::Result<()> { - self.0 - } - - pub fn read_timeout(&self) -> io::Result> { - self.0 - } - - pub fn write_timeout(&self) -> io::Result> { - self.0 - } - - pub fn peek(&self, _: &mut [u8]) -> io::Result { - self.0 - } - - pub fn read(&self, _: &mut [u8]) -> io::Result { - self.0 - } - - pub fn read_buf(&self, _buf: BorrowedCursor<'_>) -> io::Result<()> { - self.0 - } - - pub fn read_vectored(&self, _: &mut [IoSliceMut<'_>]) -> io::Result { - self.0 - } - - pub fn is_read_vectored(&self) -> bool { - self.0 - } - - pub fn write(&self, _: &[u8]) -> io::Result { - self.0 - } - - pub fn write_vectored(&self, _: &[IoSlice<'_>]) -> io::Result { - self.0 - } - - pub fn is_write_vectored(&self) -> bool { - self.0 - } - - pub fn peer_addr(&self) -> io::Result { - self.0 - } - - pub fn socket_addr(&self) -> io::Result { - self.0 - } - - pub fn shutdown(&self, _: Shutdown) -> io::Result<()> { - self.0 - } - - pub fn duplicate(&self) -> io::Result { - self.0 - } - - pub fn set_linger(&self, _: Option) -> io::Result<()> { - self.0 - } - - pub fn linger(&self) -> io::Result> { - self.0 - } - - pub fn set_nodelay(&self, _: bool) -> io::Result<()> { - self.0 - } - - pub fn nodelay(&self) -> io::Result { - self.0 - } - - pub fn set_ttl(&self, _: u32) -> io::Result<()> { - self.0 - } - - pub fn ttl(&self) -> io::Result { - self.0 - } - - pub fn take_error(&self) -> io::Result> { - self.0 - } - - pub fn set_nonblocking(&self, _: bool) -> io::Result<()> { - self.0 - } -} - -impl fmt::Debug for TcpStream { - fn fmt(&self, _f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0 - } -} - -pub struct TcpListener(!); - -impl TcpListener { - pub fn bind(_: io::Result<&SocketAddr>) -> io::Result { - unsupported() - } - - pub fn socket_addr(&self) -> io::Result { - self.0 - } - - pub fn accept(&self) -> io::Result<(TcpStream, SocketAddr)> { - self.0 - } - - pub fn duplicate(&self) -> io::Result { - self.0 - } - - pub fn set_ttl(&self, _: u32) -> io::Result<()> { - self.0 - } - - pub fn ttl(&self) -> io::Result { - self.0 - } - - pub fn set_only_v6(&self, _: bool) -> io::Result<()> { - self.0 - } - - pub fn only_v6(&self) -> io::Result { - self.0 - } - - pub fn take_error(&self) -> io::Result> { - self.0 - } - - pub fn set_nonblocking(&self, _: bool) -> io::Result<()> { - self.0 - } -} - -impl fmt::Debug for TcpListener { - fn fmt(&self, _f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0 - } -} - -pub struct UdpSocket(!); - -impl UdpSocket { - pub fn bind(_: io::Result<&SocketAddr>) -> io::Result { - unsupported() - } - - pub fn peer_addr(&self) -> io::Result { - self.0 - } - - pub fn socket_addr(&self) -> io::Result { - self.0 - } - - pub fn recv_from(&self, _: &mut [u8]) -> io::Result<(usize, SocketAddr)> { - self.0 - } - - pub fn peek_from(&self, _: &mut [u8]) -> io::Result<(usize, SocketAddr)> { - self.0 - } - - pub fn send_to(&self, _: &[u8], _: &SocketAddr) -> io::Result { - self.0 - } - - pub fn duplicate(&self) -> io::Result { - self.0 - } - - pub fn set_read_timeout(&self, _: Option) -> io::Result<()> { - self.0 - } - - pub fn set_write_timeout(&self, _: Option) -> io::Result<()> { - self.0 - } - - pub fn read_timeout(&self) -> io::Result> { - self.0 - } - - pub fn write_timeout(&self) -> io::Result> { - self.0 - } - - pub fn set_broadcast(&self, _: bool) -> io::Result<()> { - self.0 - } - - pub fn broadcast(&self) -> io::Result { - self.0 - } - - pub fn set_multicast_loop_v4(&self, _: bool) -> io::Result<()> { - self.0 - } - - pub fn multicast_loop_v4(&self) -> io::Result { - self.0 - } - - pub fn set_multicast_ttl_v4(&self, _: u32) -> io::Result<()> { - self.0 - } - - pub fn multicast_ttl_v4(&self) -> io::Result { - self.0 - } - - pub fn set_multicast_loop_v6(&self, _: bool) -> io::Result<()> { - self.0 - } - - pub fn multicast_loop_v6(&self) -> io::Result { - self.0 - } - - pub fn join_multicast_v4(&self, _: &Ipv4Addr, _: &Ipv4Addr) -> io::Result<()> { - self.0 - } - - pub fn join_multicast_v6(&self, _: &Ipv6Addr, _: u32) -> io::Result<()> { - self.0 - } - - pub fn leave_multicast_v4(&self, _: &Ipv4Addr, _: &Ipv4Addr) -> io::Result<()> { - self.0 - } - - pub fn leave_multicast_v6(&self, _: &Ipv6Addr, _: u32) -> io::Result<()> { - self.0 - } - - pub fn set_ttl(&self, _: u32) -> io::Result<()> { - self.0 - } - - pub fn ttl(&self) -> io::Result { - self.0 - } - - pub fn take_error(&self) -> io::Result> { - self.0 - } - - pub fn set_nonblocking(&self, _: bool) -> io::Result<()> { - self.0 - } - - pub fn recv(&self, _: &mut [u8]) -> io::Result { - self.0 - } - - pub fn peek(&self, _: &mut [u8]) -> io::Result { - self.0 - } - - pub fn send(&self, _: &[u8]) -> io::Result { - self.0 - } - - pub fn connect(&self, _: io::Result<&SocketAddr>) -> io::Result<()> { - self.0 - } -} - -impl fmt::Debug for UdpSocket { - fn fmt(&self, _f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0 - } -} - -pub struct LookupHost(!); - -impl LookupHost { - pub fn port(&self) -> u16 { - self.0 - } -} - -impl Iterator for LookupHost { - type Item = SocketAddr; - fn next(&mut self) -> Option { - self.0 - } -} - -impl TryFrom<&str> for LookupHost { - type Error = io::Error; - - fn try_from(_v: &str) -> io::Result { - unsupported() - } -} - -impl<'a> TryFrom<(&'a str, u16)> for LookupHost { - type Error = io::Error; - - fn try_from(_v: (&'a str, u16)) -> io::Result { - unsupported() - } -} - -#[allow(nonstandard_style)] -pub mod netc { - pub const AF_INET: u8 = 0; - pub const AF_INET6: u8 = 1; - pub type sa_family_t = u8; - - #[derive(Copy, Clone)] - pub struct in_addr { - pub s_addr: u32, - } - - #[derive(Copy, Clone)] - pub struct sockaddr_in { - pub sin_family: sa_family_t, - pub sin_port: u16, - pub sin_addr: in_addr, - } - - #[derive(Copy, Clone)] - pub struct in6_addr { - pub s6_addr: [u8; 16], - } - - #[derive(Copy, Clone)] - pub struct sockaddr_in6 { - pub sin6_family: sa_family_t, - pub sin6_port: u16, - pub sin6_addr: in6_addr, - pub sin6_flowinfo: u32, - pub sin6_scope_id: u32, - } -} - -pub type Socket = UdpSocket; diff --git a/library/std/src/sys/pal/teeos/os.rs b/library/std/src/sys/pal/teeos/os.rs deleted file mode 100644 index e54a92f01f86b..0000000000000 --- a/library/std/src/sys/pal/teeos/os.rs +++ /dev/null @@ -1,134 +0,0 @@ -//! Implementation of `std::os` functionality for teeos - -use core::marker::PhantomData; - -use crate::error::Error as StdError; -use crate::ffi::{OsStr, OsString}; -use crate::fmt; -use crate::io; -use crate::path; -use crate::path::PathBuf; - -use super::unsupported; - -pub fn errno() -> i32 { - unsafe { (*libc::__errno_location()) as i32 } -} - -// Hardcoded to return 4096, since `sysconf` is only implemented as a stub. -pub fn page_size() -> usize { - // unsafe { libc::sysconf(libc::_SC_PAGESIZE) as usize }; - 4096 -} - -// Everything below are stubs and copied from unsupported.rs - -pub fn error_string(_errno: i32) -> String { - "error string unimplemented".to_string() -} - -pub fn getcwd() -> io::Result { - unsupported() -} - -pub fn chdir(_: &path::Path) -> io::Result<()> { - unsupported() -} - -pub struct SplitPaths<'a>(!, PhantomData<&'a ()>); - -pub fn split_paths(_unparsed: &OsStr) -> SplitPaths<'_> { - panic!("unsupported") -} - -impl<'a> Iterator for SplitPaths<'a> { - type Item = PathBuf; - fn next(&mut self) -> Option { - self.0 - } -} - -#[derive(Debug)] -pub struct JoinPathsError; - -pub fn join_paths(_paths: I) -> Result -where - I: Iterator, - T: AsRef, -{ - Err(JoinPathsError) -} - -impl fmt::Display for JoinPathsError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - "not supported on this platform yet".fmt(f) - } -} - -impl StdError for JoinPathsError { - #[allow(deprecated)] - fn description(&self) -> &str { - "not supported on this platform yet" - } -} - -pub fn current_exe() -> io::Result { - unsupported() -} - -pub struct Env(!); - -impl Env { - // FIXME(https://github.com/rust-lang/rust/issues/114583): Remove this when ::fmt matches ::fmt. - pub fn str_debug(&self) -> impl fmt::Debug + '_ { - let Self(inner) = self; - match *inner {} - } -} - -impl fmt::Debug for Env { - fn fmt(&self, _: &mut fmt::Formatter<'_>) -> fmt::Result { - let Self(inner) = self; - match *inner {} - } -} - -impl Iterator for Env { - type Item = (OsString, OsString); - fn next(&mut self) -> Option<(OsString, OsString)> { - let Self(inner) = self; - match *inner {} - } -} - -pub fn env() -> Env { - panic!("not supported on this platform") -} - -pub fn getenv(_: &OsStr) -> Option { - None -} - -pub fn setenv(_: &OsStr, _: &OsStr) -> io::Result<()> { - Err(io::Error::new(io::ErrorKind::Unsupported, "cannot set env vars on this platform")) -} - -pub fn unsetenv(_: &OsStr) -> io::Result<()> { - Err(io::Error::new(io::ErrorKind::Unsupported, "cannot unset env vars on this platform")) -} - -pub fn temp_dir() -> PathBuf { - panic!("no filesystem on this platform") -} - -pub fn home_dir() -> Option { - None -} - -pub fn exit(_code: i32) -> ! { - panic!("TA should not call `exit`") -} - -pub fn getpid() -> u32 { - panic!("no pids on this platform") -} diff --git a/library/std/src/sys/pal/teeos/rand.rs b/library/std/src/sys/pal/teeos/rand.rs deleted file mode 100644 index b45c3bb40e782..0000000000000 --- a/library/std/src/sys/pal/teeos/rand.rs +++ /dev/null @@ -1,21 +0,0 @@ -pub fn hashmap_random_keys() -> (u64, u64) { - const KEY_LEN: usize = core::mem::size_of::(); - - let mut v = [0u8; KEY_LEN * 2]; - imp::fill_bytes(&mut v); - - let key1 = v[0..KEY_LEN].try_into().unwrap(); - let key2 = v[KEY_LEN..].try_into().unwrap(); - - (u64::from_ne_bytes(key1), u64::from_ne_bytes(key2)) -} - -mod imp { - extern "C" { - fn TEE_GenerateRandom(randomBuffer: *mut core::ffi::c_void, randomBufferLen: libc::size_t); - } - - pub fn fill_bytes(v: &mut [u8]) { - unsafe { TEE_GenerateRandom(v.as_mut_ptr() as _, v.len() * crate::mem::size_of::()) } - } -} diff --git a/library/std/src/sys/pal/teeos/stdio.rs b/library/std/src/sys/pal/teeos/stdio.rs deleted file mode 100644 index 9ca04f2927323..0000000000000 --- a/library/std/src/sys/pal/teeos/stdio.rs +++ /dev/null @@ -1,88 +0,0 @@ -#![deny(unsafe_op_in_unsafe_fn)] - -use crate::io; -use core::arch::asm; - -pub struct Stdin; -pub struct Stdout; -pub struct Stderr; - -const KCALL_DEBUG_CMD_PUT_BYTES: i64 = 2; - -unsafe fn debug_call(cap_ref: u64, call_no: i64, arg1: u64, arg2: u64) -> i32 { - let ret: u64; - unsafe { - asm!( - "svc #99", - inout("x0") cap_ref => ret, - in("x1") call_no, - in("x2") arg1, - in("x3") arg2, - ); - } - - ret as i32 -} - -fn print_buf(s: &[u8]) -> io::Result { - // Corresponds to `HM_DEBUG_PUT_BYTES_LIMIT`. - const MAX_LEN: usize = 512; - let len = if s.len() > MAX_LEN { MAX_LEN } else { s.len() }; - let result = unsafe { debug_call(0, KCALL_DEBUG_CMD_PUT_BYTES, s.as_ptr() as u64, len as u64) }; - - if result == 0 { Ok(len) } else { Err(io::Error::from(io::ErrorKind::InvalidInput)) } -} - -impl Stdin { - pub const fn new() -> Stdin { - Stdin - } -} - -impl io::Read for Stdin { - fn read(&mut self, _buf: &mut [u8]) -> io::Result { - Ok(0) - } -} - -impl Stdout { - pub const fn new() -> Stdout { - Stdout - } -} - -impl io::Write for Stdout { - fn write(&mut self, buf: &[u8]) -> io::Result { - print_buf(buf) - } - - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -impl Stderr { - pub const fn new() -> Stderr { - Stderr - } -} - -impl io::Write for Stderr { - fn write(&mut self, buf: &[u8]) -> io::Result { - print_buf(buf) - } - - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -pub const STDIN_BUF_SIZE: usize = 0; - -pub fn is_ebadf(err: &io::Error) -> bool { - err.raw_os_error() == Some(libc::EBADF as i32) -} - -pub fn panic_output() -> Option { - Some(Stderr::new()) -} diff --git a/library/std/src/sys/pal/teeos/thread.rs b/library/std/src/sys/pal/teeos/thread.rs deleted file mode 100644 index f4723b2ea46bf..0000000000000 --- a/library/std/src/sys/pal/teeos/thread.rs +++ /dev/null @@ -1,149 +0,0 @@ -use core::convert::TryInto; - -use crate::cmp; -use crate::ffi::CStr; -use crate::io; -use crate::mem; -use crate::num::NonZero; -use crate::ptr; -use crate::sys::os; -use crate::time::Duration; - -pub const DEFAULT_MIN_STACK_SIZE: usize = 8 * 1024; - -pub struct Thread { - id: libc::pthread_t, -} - -// Some platforms may have pthread_t as a pointer in which case we still want -// a thread to be Send/Sync -unsafe impl Send for Thread {} -unsafe impl Sync for Thread {} - -extern "C" { - pub fn TEE_Wait(timeout: u32) -> u32; -} - -impl Thread { - // unsafe: see thread::Builder::spawn_unchecked for safety requirements - pub unsafe fn new(stack: usize, p: Box) -> io::Result { - let p = Box::into_raw(Box::new(p)); - let mut native: libc::pthread_t = mem::zeroed(); - let mut attr: libc::pthread_attr_t = mem::zeroed(); - assert_eq!(libc::pthread_attr_init(&mut attr), 0); - assert_eq!( - libc::pthread_attr_settee( - &mut attr, - libc::TEESMP_THREAD_ATTR_CA_INHERIT, - libc::TEESMP_THREAD_ATTR_TASK_ID_INHERIT, - libc::TEESMP_THREAD_ATTR_HAS_SHADOW, - ), - 0, - ); - - let stack_size = cmp::max(stack, min_stack_size(&attr)); - - match libc::pthread_attr_setstacksize(&mut attr, stack_size) { - 0 => {} - n => { - assert_eq!(n, libc::EINVAL); - // EINVAL means |stack_size| is either too small or not a - // multiple of the system page size. Because it's definitely - // >= PTHREAD_STACK_MIN, it must be an alignment issue. - // Round up to the nearest page and try again. - let page_size = os::page_size(); - let stack_size = - (stack_size + page_size - 1) & (-(page_size as isize - 1) as usize - 1); - assert_eq!(libc::pthread_attr_setstacksize(&mut attr, stack_size), 0); - } - }; - - let ret = libc::pthread_create(&mut native, &attr, thread_start, p as *mut _); - // Note: if the thread creation fails and this assert fails, then p will - // be leaked. However, an alternative design could cause double-free - // which is clearly worse. - assert_eq!(libc::pthread_attr_destroy(&mut attr), 0); - - return if ret != 0 { - // The thread failed to start and as a result p was not consumed. Therefore, it is - // safe to reconstruct the box so that it gets deallocated. - drop(Box::from_raw(p)); - Err(io::Error::from_raw_os_error(ret)) - } else { - // The new thread will start running earliest after the next yield. - // We add a yield here, so that the user does not have to. - Thread::yield_now(); - Ok(Thread { id: native }) - }; - - extern "C" fn thread_start(main: *mut libc::c_void) -> *mut libc::c_void { - unsafe { - // Next, set up our stack overflow handler which may get triggered if we run - // out of stack. - // this is not necessary in TEE. - //let _handler = stack_overflow::Handler::new(); - // Finally, let's run some code. - Box::from_raw(main as *mut Box)(); - } - ptr::null_mut() - } - } - - pub fn yield_now() { - let ret = unsafe { libc::sched_yield() }; - debug_assert_eq!(ret, 0); - } - - /// This does not do anything on teeos - pub fn set_name(_name: &CStr) { - // Both pthread_setname_np and prctl are not available to the TA, - // so we can't implement this currently. If the need arises please - // contact the teeos rustzone team. - } - - /// only main thread could wait for sometime in teeos - pub fn sleep(dur: Duration) { - let sleep_millis = dur.as_millis(); - let final_sleep: u32 = - if sleep_millis >= u32::MAX as u128 { u32::MAX } else { sleep_millis as u32 }; - unsafe { - let _ = TEE_Wait(final_sleep); - } - } - - /// must join, because no pthread_detach supported - pub fn join(self) { - unsafe { - let ret = libc::pthread_join(self.id, ptr::null_mut()); - mem::forget(self); - assert!(ret == 0, "failed to join thread: {}", io::Error::from_raw_os_error(ret)); - } - } - - pub fn id(&self) -> libc::pthread_t { - self.id - } - - pub fn into_id(self) -> libc::pthread_t { - let id = self.id; - mem::forget(self); - id - } -} - -impl Drop for Thread { - fn drop(&mut self) { - // we can not call detach, so just panic if thread spawn without join - panic!("thread must join, detach is not supported!"); - } -} - -// Note: Both `sched_getaffinity` and `sysconf` are available but not functional on -// teeos, so this function always returns an Error! -pub fn available_parallelism() -> io::Result> { - Err(io::Error::UNKNOWN_THREAD_COUNT) -} - -fn min_stack_size(_: *const libc::pthread_attr_t) -> usize { - libc::PTHREAD_STACK_MIN.try_into().expect("Infallible") -} diff --git a/library/std/src/sys/pal/teeos/thread_local_dtor.rs b/library/std/src/sys/pal/teeos/thread_local_dtor.rs deleted file mode 100644 index 5c6bc4d675011..0000000000000 --- a/library/std/src/sys/pal/teeos/thread_local_dtor.rs +++ /dev/null @@ -1,4 +0,0 @@ -pub unsafe fn register_dtor(t: *mut u8, dtor: unsafe extern "C" fn(*mut u8)) { - use crate::sys_common::thread_local_dtor::register_dtor_fallback; - register_dtor_fallback(t, dtor); -} diff --git a/library/std/src/sys/pal/uefi/alloc.rs b/library/std/src/sys/pal/uefi/alloc.rs deleted file mode 100644 index 15404ac3ea696..0000000000000 --- a/library/std/src/sys/pal/uefi/alloc.rs +++ /dev/null @@ -1,49 +0,0 @@ -//! Global Allocator for UEFI. -//! Uses [r-efi-alloc](https://crates.io/crates/r-efi-alloc) - -use r_efi::protocols::loaded_image; - -use super::helpers; -use crate::alloc::{GlobalAlloc, Layout, System}; -use crate::sync::OnceLock; - -#[stable(feature = "alloc_system_type", since = "1.28.0")] -unsafe impl GlobalAlloc for System { - unsafe fn alloc(&self, layout: Layout) -> *mut u8 { - static EFI_MEMORY_TYPE: OnceLock = OnceLock::new(); - - // Return null pointer if boot services are not available - if crate::os::uefi::env::boot_services().is_none() { - return crate::ptr::null_mut(); - } - - // If boot services is valid then SystemTable is not null. - let system_table = crate::os::uefi::env::system_table().as_ptr().cast(); - - // Each loaded image has an image handle that supports `EFI_LOADED_IMAGE_PROTOCOL`. Thus, this - // will never fail. - let mem_type = EFI_MEMORY_TYPE.get_or_init(|| { - let protocol = helpers::image_handle_protocol::( - loaded_image::PROTOCOL_GUID, - ) - .unwrap(); - // Gives allocations the memory type that the data sections were loaded as. - unsafe { (*protocol.as_ptr()).image_data_type } - }); - - // The caller must ensure non-0 layout - unsafe { r_efi_alloc::raw::alloc(system_table, layout, *mem_type) } - } - - unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) { - // Do nothing if boot services are not available - if crate::os::uefi::env::boot_services().is_none() { - return; - } - - // If boot services is valid then SystemTable is not null. - let system_table = crate::os::uefi::env::system_table().as_ptr().cast(); - // The caller must ensure non-0 layout - unsafe { r_efi_alloc::raw::dealloc(system_table, ptr, layout) } - } -} diff --git a/library/std/src/sys/pal/uefi/args.rs b/library/std/src/sys/pal/uefi/args.rs deleted file mode 100644 index 18a69afa7d91b..0000000000000 --- a/library/std/src/sys/pal/uefi/args.rs +++ /dev/null @@ -1,158 +0,0 @@ -use r_efi::protocols::loaded_image; - -use super::helpers; -use crate::env::current_exe; -use crate::ffi::OsString; -use crate::fmt; -use crate::iter::Iterator; -use crate::mem::size_of; -use crate::vec; - -pub struct Args { - parsed_args_list: vec::IntoIter, -} - -pub fn args() -> Args { - let lazy_current_exe = || Vec::from([current_exe().map(Into::into).unwrap_or_default()]); - - // Each loaded image has an image handle that supports `EFI_LOADED_IMAGE_PROTOCOL`. Thus, this - // will never fail. - let protocol = - helpers::image_handle_protocol::(loaded_image::PROTOCOL_GUID) - .unwrap(); - - let lp_size = unsafe { (*protocol.as_ptr()).load_options_size } as usize; - // Break if we are sure that it cannot be UTF-16 - if lp_size < size_of::() || lp_size % size_of::() != 0 { - return Args { parsed_args_list: lazy_current_exe().into_iter() }; - } - let lp_size = lp_size / size_of::(); - - let lp_cmd_line = unsafe { (*protocol.as_ptr()).load_options as *const u16 }; - if !lp_cmd_line.is_aligned() { - return Args { parsed_args_list: lazy_current_exe().into_iter() }; - } - let lp_cmd_line = unsafe { crate::slice::from_raw_parts(lp_cmd_line, lp_size) }; - - Args { - parsed_args_list: parse_lp_cmd_line(lp_cmd_line) - .unwrap_or_else(lazy_current_exe) - .into_iter(), - } -} - -impl fmt::Debug for Args { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.parsed_args_list.as_slice().fmt(f) - } -} - -impl Iterator for Args { - type Item = OsString; - - fn next(&mut self) -> Option { - self.parsed_args_list.next() - } - - fn size_hint(&self) -> (usize, Option) { - self.parsed_args_list.size_hint() - } -} - -impl ExactSizeIterator for Args { - fn len(&self) -> usize { - self.parsed_args_list.len() - } -} - -impl DoubleEndedIterator for Args { - fn next_back(&mut self) -> Option { - self.parsed_args_list.next_back() - } -} - -/// Implements the UEFI command-line argument parsing algorithm. -/// -/// This implementation is based on what is defined in Section 3.4 of -/// [UEFI Shell Specification](https://uefi.org/sites/default/files/resources/UEFI_Shell_Spec_2_0.pdf) -/// -/// Return None in the following cases: -/// - Invalid UTF-16 (unpaired surrogate) -/// - Empty/improper arguments -fn parse_lp_cmd_line(code_units: &[u16]) -> Option> { - const QUOTE: char = '"'; - const SPACE: char = ' '; - const CARET: char = '^'; - const NULL: char = '\0'; - - let mut ret_val = Vec::new(); - let mut code_units_iter = char::decode_utf16(code_units.iter().cloned()).peekable(); - - // The executable name at the beginning is special. - let mut in_quotes = false; - let mut cur = String::new(); - while let Some(w) = code_units_iter.next() { - let w = w.ok()?; - match w { - // break on NULL - NULL => break, - // A quote mark always toggles `in_quotes` no matter what because - // there are no escape characters when parsing the executable name. - QUOTE => in_quotes = !in_quotes, - // If not `in_quotes` then whitespace ends argv[0]. - SPACE if !in_quotes => break, - // In all other cases the code unit is taken literally. - _ => cur.push(w), - } - } - - // If exe name is missing, the cli args are invalid - if cur.is_empty() { - return None; - } - - ret_val.push(OsString::from(cur)); - // Skip whitespace. - while code_units_iter.next_if_eq(&Ok(SPACE)).is_some() {} - - // Parse the arguments according to these rules: - // * All code units are taken literally except space, quote and caret. - // * When not `in_quotes`, space separate arguments. Consecutive spaces are - // treated as a single separator. - // * A space `in_quotes` is taken literally. - // * A quote toggles `in_quotes` mode unless it's escaped. An escaped quote is taken literally. - // * A quote can be escaped if preceded by caret. - // * A caret can be escaped if preceded by caret. - let mut cur = String::new(); - let mut in_quotes = false; - while let Some(w) = code_units_iter.next() { - let w = w.ok()?; - match w { - // break on NULL - NULL => break, - // If not `in_quotes`, a space or tab ends the argument. - SPACE if !in_quotes => { - ret_val.push(OsString::from(&cur[..])); - cur.truncate(0); - - // Skip whitespace. - while code_units_iter.next_if_eq(&Ok(SPACE)).is_some() {} - } - // Caret can escape quotes or carets - CARET if in_quotes => { - if let Some(x) = code_units_iter.next() { - cur.push(x.ok()?); - } - } - // If quote then flip `in_quotes` - QUOTE => in_quotes = !in_quotes, - // Everything else is always taken literally. - _ => cur.push(w), - } - } - // Push the final argument, if any. - if !cur.is_empty() || in_quotes { - ret_val.push(OsString::from(cur)); - } - Some(ret_val) -} diff --git a/library/std/src/sys/pal/uefi/env.rs b/library/std/src/sys/pal/uefi/env.rs deleted file mode 100644 index c106d5fed3e1d..0000000000000 --- a/library/std/src/sys/pal/uefi/env.rs +++ /dev/null @@ -1,9 +0,0 @@ -pub mod os { - pub const FAMILY: &str = ""; - pub const OS: &str = "uefi"; - pub const DLL_PREFIX: &str = ""; - pub const DLL_SUFFIX: &str = ""; - pub const DLL_EXTENSION: &str = ""; - pub const EXE_SUFFIX: &str = ".efi"; - pub const EXE_EXTENSION: &str = "efi"; -} diff --git a/library/std/src/sys/pal/uefi/helpers.rs b/library/std/src/sys/pal/uefi/helpers.rs deleted file mode 100644 index 23aa4da14a763..0000000000000 --- a/library/std/src/sys/pal/uefi/helpers.rs +++ /dev/null @@ -1,223 +0,0 @@ -//! Contains most of the shared UEFI specific stuff. Some of this might be moved to `std::os::uefi` -//! if needed but no point in adding extra public API when there is not Std support for UEFI in the -//! first place -//! -//! Some Nomenclature -//! * Protocol: -//! - Protocols serve to enable communication between separately built modules, including drivers. -//! - Every protocol has a GUID associated with it. The GUID serves as the name for the protocol. -//! - Protocols are produced and consumed. -//! - More information about protocols can be found [here](https://edk2-docs.gitbook.io/edk-ii-uefi-driver-writer-s-guide/3_foundation/36_protocols_and_handles) - -use r_efi::efi::{self, Guid}; -use r_efi::protocols::{device_path, device_path_to_text}; - -use crate::ffi::OsString; -use crate::io::{self, const_io_error}; -use crate::mem::{size_of, MaybeUninit}; -use crate::os::uefi::{self, env::boot_services, ffi::OsStringExt}; -use crate::ptr::NonNull; -use crate::slice; -use crate::sync::atomic::{AtomicPtr, Ordering}; -use crate::sys_common::wstr::WStrUnits; - -const BOOT_SERVICES_UNAVAILABLE: io::Error = - const_io_error!(io::ErrorKind::Other, "Boot Services are no longer available"); - -/// Locate Handles with a particular Protocol GUID -/// Implemented using `EFI_BOOT_SERVICES.LocateHandles()` -/// -/// Returns an array of [Handles](r_efi::efi::Handle) that support a specified protocol. -pub(crate) fn locate_handles(mut guid: Guid) -> io::Result>> { - fn inner( - guid: &mut Guid, - boot_services: NonNull, - buf_size: &mut usize, - buf: *mut r_efi::efi::Handle, - ) -> io::Result<()> { - let r = unsafe { - ((*boot_services.as_ptr()).locate_handle)( - r_efi::efi::BY_PROTOCOL, - guid, - crate::ptr::null_mut(), - buf_size, - buf, - ) - }; - - if r.is_error() { Err(crate::io::Error::from_raw_os_error(r.as_usize())) } else { Ok(()) } - } - - let boot_services = boot_services().ok_or(BOOT_SERVICES_UNAVAILABLE)?.cast(); - let mut buf_len = 0usize; - - // This should always fail since the size of buffer is 0. This call should update the buf_len - // variable with the required buffer length - match inner(&mut guid, boot_services, &mut buf_len, crate::ptr::null_mut()) { - Ok(()) => unreachable!(), - Err(e) => match e.kind() { - io::ErrorKind::FileTooLarge => {} - _ => return Err(e), - }, - } - - // The returned buf_len is in bytes - assert_eq!(buf_len % size_of::(), 0); - let num_of_handles = buf_len / size_of::(); - let mut buf: Vec = Vec::with_capacity(num_of_handles); - match inner(&mut guid, boot_services, &mut buf_len, buf.as_mut_ptr()) { - Ok(()) => { - // This is safe because the call will succeed only if buf_len >= required length. - // Also, on success, the `buf_len` is updated with the size of bufferv (in bytes) written - unsafe { buf.set_len(num_of_handles) }; - Ok(buf.into_iter().filter_map(|x| NonNull::new(x)).collect()) - } - Err(e) => Err(e), - } -} - -/// Open Protocol on a handle. -/// Internally just a call to `EFI_BOOT_SERVICES.OpenProtocol()`. -/// -/// Queries a handle to determine if it supports a specified protocol. If the protocol is -/// supported by the handle, it opens the protocol on behalf of the calling agent. -pub(crate) fn open_protocol( - handle: NonNull, - mut protocol_guid: Guid, -) -> io::Result> { - let boot_services: NonNull = - boot_services().ok_or(BOOT_SERVICES_UNAVAILABLE)?.cast(); - let system_handle = uefi::env::image_handle(); - let mut protocol: MaybeUninit<*mut T> = MaybeUninit::uninit(); - - let r = unsafe { - ((*boot_services.as_ptr()).open_protocol)( - handle.as_ptr(), - &mut protocol_guid, - protocol.as_mut_ptr().cast(), - system_handle.as_ptr(), - crate::ptr::null_mut(), - r_efi::system::OPEN_PROTOCOL_GET_PROTOCOL, - ) - }; - - if r.is_error() { - Err(crate::io::Error::from_raw_os_error(r.as_usize())) - } else { - NonNull::new(unsafe { protocol.assume_init() }) - .ok_or(const_io_error!(io::ErrorKind::Other, "null protocol")) - } -} - -pub(crate) fn create_event( - signal: u32, - tpl: efi::Tpl, - handler: Option, - context: *mut crate::ffi::c_void, -) -> io::Result> { - let boot_services: NonNull = - boot_services().ok_or(BOOT_SERVICES_UNAVAILABLE)?.cast(); - let mut event: r_efi::efi::Event = crate::ptr::null_mut(); - let r = unsafe { - let create_event = (*boot_services.as_ptr()).create_event; - (create_event)(signal, tpl, handler, context, &mut event) - }; - if r.is_error() { - Err(crate::io::Error::from_raw_os_error(r.as_usize())) - } else { - NonNull::new(event).ok_or(const_io_error!(io::ErrorKind::Other, "null protocol")) - } -} - -/// # SAFETY -/// - The supplied event must be valid -pub(crate) unsafe fn close_event(evt: NonNull) -> io::Result<()> { - let boot_services: NonNull = - boot_services().ok_or(BOOT_SERVICES_UNAVAILABLE)?.cast(); - let r = unsafe { - let close_event = (*boot_services.as_ptr()).close_event; - (close_event)(evt.as_ptr()) - }; - - if r.is_error() { Err(crate::io::Error::from_raw_os_error(r.as_usize())) } else { Ok(()) } -} - -/// Get the Protocol for current system handle. -/// Note: Some protocols need to be manually freed. It is the callers responsibility to do so. -pub(crate) fn image_handle_protocol(protocol_guid: Guid) -> io::Result> { - let system_handle = uefi::env::try_image_handle().ok_or(io::const_io_error!( - io::ErrorKind::NotFound, - "Protocol not found in Image handle" - ))?; - open_protocol(system_handle, protocol_guid) -} - -pub(crate) fn device_path_to_text(path: NonNull) -> io::Result { - fn path_to_text( - protocol: NonNull, - path: NonNull, - ) -> io::Result { - let path_ptr: *mut r_efi::efi::Char16 = unsafe { - ((*protocol.as_ptr()).convert_device_path_to_text)( - path.as_ptr(), - // DisplayOnly - r_efi::efi::Boolean::FALSE, - // AllowShortcuts - r_efi::efi::Boolean::FALSE, - ) - }; - - // SAFETY: `convert_device_path_to_text` returns a pointer to a null-terminated UTF-16 - // string, and that string cannot be deallocated prior to dropping the `WStrUnits`, so - // it's safe for `WStrUnits` to use. - let path_len = unsafe { - WStrUnits::new(path_ptr) - .ok_or(io::const_io_error!(io::ErrorKind::InvalidData, "Invalid path"))? - .count() - }; - - let path = OsString::from_wide(unsafe { slice::from_raw_parts(path_ptr.cast(), path_len) }); - - if let Some(boot_services) = crate::os::uefi::env::boot_services() { - let boot_services: NonNull = boot_services.cast(); - unsafe { - ((*boot_services.as_ptr()).free_pool)(path_ptr.cast()); - } - } - - Ok(path) - } - - static LAST_VALID_HANDLE: AtomicPtr = - AtomicPtr::new(crate::ptr::null_mut()); - - if let Some(handle) = NonNull::new(LAST_VALID_HANDLE.load(Ordering::Acquire)) { - if let Ok(protocol) = open_protocol::( - handle, - device_path_to_text::PROTOCOL_GUID, - ) { - return path_to_text(protocol, path); - } - } - - let device_path_to_text_handles = locate_handles(device_path_to_text::PROTOCOL_GUID)?; - for handle in device_path_to_text_handles { - if let Ok(protocol) = open_protocol::( - handle, - device_path_to_text::PROTOCOL_GUID, - ) { - LAST_VALID_HANDLE.store(handle.as_ptr(), Ordering::Release); - return path_to_text(protocol, path); - } - } - - Err(io::const_io_error!(io::ErrorKind::NotFound, "No device path to text protocol found")) -} - -/// Get RuntimeServices -pub(crate) fn runtime_services() -> Option> { - let system_table: NonNull = - crate::os::uefi::env::try_system_table()?.cast(); - let runtime_services = unsafe { (*system_table.as_ptr()).runtime_services }; - NonNull::new(runtime_services) -} diff --git a/library/std/src/sys/pal/uefi/mod.rs b/library/std/src/sys/pal/uefi/mod.rs deleted file mode 100644 index 48b74df138439..0000000000000 --- a/library/std/src/sys/pal/uefi/mod.rs +++ /dev/null @@ -1,225 +0,0 @@ -//! Platform-specific extensions to `std` for UEFI platforms. -//! -//! Provides access to platform-level information on UEFI platforms, and -//! exposes UEFI-specific functions that would otherwise be inappropriate as -//! part of the core `std` library. -//! -//! It exposes more ways to deal with platform-specific strings ([`OsStr`], -//! [`OsString`]), allows to set permissions more granularly, extract low-level -//! file descriptors from files and sockets, and has platform-specific helpers -//! for spawning processes. -//! -//! [`OsStr`]: crate::ffi::OsStr -//! [`OsString`]: crate::ffi::OsString - -pub mod alloc; -pub mod args; -pub mod env; -#[path = "../unsupported/fs.rs"] -pub mod fs; -#[path = "../unsupported/io.rs"] -pub mod io; -#[path = "../unsupported/net.rs"] -pub mod net; -pub mod os; -#[path = "../unsupported/pipe.rs"] -pub mod pipe; -#[path = "../unsupported/process.rs"] -pub mod process; -pub mod stdio; -pub mod thread; -#[path = "../unsupported/thread_local_key.rs"] -pub mod thread_local_key; -pub mod time; - -mod helpers; - -#[cfg(test)] -mod tests; - -pub type RawOsError = usize; - -use crate::io as std_io; -use crate::os::uefi; -use crate::ptr::NonNull; -use crate::sync::atomic::{AtomicPtr, Ordering}; - -static EXIT_BOOT_SERVICE_EVENT: AtomicPtr = - AtomicPtr::new(crate::ptr::null_mut()); - -/// # SAFETY -/// - must be called only once during runtime initialization. -/// - argc must be 2. -/// - argv must be &[Handle, *mut SystemTable]. -pub(crate) unsafe fn init(argc: isize, argv: *const *const u8, _sigpipe: u8) { - assert_eq!(argc, 2); - let image_handle = unsafe { NonNull::new(*argv as *mut crate::ffi::c_void).unwrap() }; - let system_table = unsafe { NonNull::new(*argv.add(1) as *mut crate::ffi::c_void).unwrap() }; - unsafe { uefi::env::init_globals(image_handle, system_table) }; - - // Register exit boot services handler - match helpers::create_event( - r_efi::efi::EVT_SIGNAL_EXIT_BOOT_SERVICES, - r_efi::efi::TPL_NOTIFY, - Some(exit_boot_service_handler), - crate::ptr::null_mut(), - ) { - Ok(x) => { - if EXIT_BOOT_SERVICE_EVENT - .compare_exchange( - crate::ptr::null_mut(), - x.as_ptr(), - Ordering::Release, - Ordering::Acquire, - ) - .is_err() - { - abort_internal(); - }; - } - Err(_) => abort_internal(), - } -} - -/// # SAFETY -/// this is not guaranteed to run, for example when the program aborts. -/// - must be called only once during runtime cleanup. -pub unsafe fn cleanup() { - if let Some(exit_boot_service_event) = - NonNull::new(EXIT_BOOT_SERVICE_EVENT.swap(crate::ptr::null_mut(), Ordering::Acquire)) - { - let _ = unsafe { helpers::close_event(exit_boot_service_event) }; - } -} - -#[inline] -pub const fn unsupported() -> std_io::Result { - Err(unsupported_err()) -} - -#[inline] -pub const fn unsupported_err() -> std_io::Error { - std_io::const_io_error!(std_io::ErrorKind::Unsupported, "operation not supported on UEFI",) -} - -pub fn decode_error_kind(code: RawOsError) -> crate::io::ErrorKind { - use crate::io::ErrorKind; - use r_efi::efi::Status; - - match r_efi::efi::Status::from_usize(code) { - Status::ALREADY_STARTED - | Status::COMPROMISED_DATA - | Status::CONNECTION_FIN - | Status::CRC_ERROR - | Status::DEVICE_ERROR - | Status::END_OF_MEDIA - | Status::HTTP_ERROR - | Status::ICMP_ERROR - | Status::INCOMPATIBLE_VERSION - | Status::LOAD_ERROR - | Status::MEDIA_CHANGED - | Status::NO_MAPPING - | Status::NO_MEDIA - | Status::NOT_STARTED - | Status::PROTOCOL_ERROR - | Status::PROTOCOL_UNREACHABLE - | Status::TFTP_ERROR - | Status::VOLUME_CORRUPTED => ErrorKind::Other, - Status::BAD_BUFFER_SIZE | Status::INVALID_LANGUAGE => ErrorKind::InvalidData, - Status::ABORTED => ErrorKind::ConnectionAborted, - Status::ACCESS_DENIED => ErrorKind::PermissionDenied, - Status::BUFFER_TOO_SMALL => ErrorKind::FileTooLarge, - Status::CONNECTION_REFUSED => ErrorKind::ConnectionRefused, - Status::CONNECTION_RESET => ErrorKind::ConnectionReset, - Status::END_OF_FILE => ErrorKind::UnexpectedEof, - Status::HOST_UNREACHABLE => ErrorKind::HostUnreachable, - Status::INVALID_PARAMETER => ErrorKind::InvalidInput, - Status::IP_ADDRESS_CONFLICT => ErrorKind::AddrInUse, - Status::NETWORK_UNREACHABLE => ErrorKind::NetworkUnreachable, - Status::NO_RESPONSE => ErrorKind::HostUnreachable, - Status::NOT_FOUND => ErrorKind::NotFound, - Status::NOT_READY => ErrorKind::ResourceBusy, - Status::OUT_OF_RESOURCES => ErrorKind::OutOfMemory, - Status::SECURITY_VIOLATION => ErrorKind::PermissionDenied, - Status::TIMEOUT => ErrorKind::TimedOut, - Status::UNSUPPORTED => ErrorKind::Unsupported, - Status::VOLUME_FULL => ErrorKind::StorageFull, - Status::WRITE_PROTECTED => ErrorKind::ReadOnlyFilesystem, - _ => ErrorKind::Uncategorized, - } -} - -pub fn abort_internal() -> ! { - if let Some(exit_boot_service_event) = - NonNull::new(EXIT_BOOT_SERVICE_EVENT.load(Ordering::Acquire)) - { - let _ = unsafe { helpers::close_event(exit_boot_service_event) }; - } - - if let (Some(boot_services), Some(handle)) = - (uefi::env::boot_services(), uefi::env::try_image_handle()) - { - let boot_services: NonNull = boot_services.cast(); - let _ = unsafe { - ((*boot_services.as_ptr()).exit)( - handle.as_ptr(), - r_efi::efi::Status::ABORTED, - 0, - crate::ptr::null_mut(), - ) - }; - } - - // In case SystemTable and ImageHandle cannot be reached, use `core::intrinsics::abort` - core::intrinsics::abort(); -} - -// This function is needed by the panic runtime. The symbol is named in -// pre-link args for the target specification, so keep that in sync. -#[cfg(not(test))] -#[no_mangle] -pub extern "C" fn __rust_abort() { - abort_internal(); -} - -#[inline] -pub fn hashmap_random_keys() -> (u64, u64) { - get_random().unwrap() -} - -fn get_random() -> Option<(u64, u64)> { - use r_efi::protocols::rng; - - let mut buf = [0u8; 16]; - let handles = helpers::locate_handles(rng::PROTOCOL_GUID).ok()?; - for handle in handles { - if let Ok(protocol) = helpers::open_protocol::(handle, rng::PROTOCOL_GUID) { - let r = unsafe { - ((*protocol.as_ptr()).get_rng)( - protocol.as_ptr(), - crate::ptr::null_mut(), - buf.len(), - buf.as_mut_ptr(), - ) - }; - if r.is_error() { - continue; - } else { - return Some(( - u64::from_le_bytes(buf[..8].try_into().ok()?), - u64::from_le_bytes(buf[8..].try_into().ok()?), - )); - } - } - } - None -} - -/// Disable access to BootServices if `EVT_SIGNAL_EXIT_BOOT_SERVICES` is signaled -extern "efiapi" fn exit_boot_service_handler(_e: r_efi::efi::Event, _ctx: *mut crate::ffi::c_void) { - uefi::env::disable_boot_services(); -} - -pub fn is_interrupted(_code: RawOsError) -> bool { - false -} diff --git a/library/std/src/sys/pal/uefi/os.rs b/library/std/src/sys/pal/uefi/os.rs deleted file mode 100644 index 58838c5876ebd..0000000000000 --- a/library/std/src/sys/pal/uefi/os.rs +++ /dev/null @@ -1,241 +0,0 @@ -use super::{helpers, unsupported, RawOsError}; -use crate::error::Error as StdError; -use crate::ffi::{OsStr, OsString}; -use crate::fmt; -use crate::io; -use crate::marker::PhantomData; -use crate::os::uefi; -use crate::path::{self, PathBuf}; -use crate::ptr::NonNull; -use r_efi::efi::protocols::{device_path, loaded_image_device_path}; -use r_efi::efi::Status; - -pub fn errno() -> RawOsError { - 0 -} - -pub fn error_string(errno: RawOsError) -> String { - // Keep the List in Alphabetical Order - // The Messages are taken from UEFI Specification Appendix D - Status Codes - match r_efi::efi::Status::from_usize(errno) { - Status::ABORTED => "The operation was aborted.".to_owned(), - Status::ACCESS_DENIED => "Access was denied.".to_owned(), - Status::ALREADY_STARTED => "The protocol has already been started.".to_owned(), - Status::BAD_BUFFER_SIZE => "The buffer was not the proper size for the request.".to_owned(), - Status::BUFFER_TOO_SMALL => { - "The buffer is not large enough to hold the requested data. The required buffer size is returned in the appropriate parameter when this error occurs.".to_owned() - } - Status::COMPROMISED_DATA => { - "The security status of the data is unknown or compromised and the data must be updated or replaced to restore a valid security status.".to_owned() - } - Status::CONNECTION_FIN => { - "The receiving operation fails because the communication peer has closed the connection and there is no more data in the receive buffer of the instance.".to_owned() - } - Status::CONNECTION_REFUSED => { - "The receiving or transmission operation fails because this connection is refused.".to_owned() - } - Status::CONNECTION_RESET => { - "The connect fails because the connection is reset either by instance itself or the communication peer.".to_owned() - } - Status::CRC_ERROR => "A CRC error was detected.".to_owned(), - Status::DEVICE_ERROR => "The physical device reported an error while attempting the operation.".to_owned() - , - Status::END_OF_FILE => { - "The end of the file was reached.".to_owned() - } - Status::END_OF_MEDIA => { - "Beginning or end of media was reached".to_owned() - } - Status::HOST_UNREACHABLE => { - "The remote host is not reachable.".to_owned() - } - Status::HTTP_ERROR => { - "A HTTP error occurred during the network operation.".to_owned() - } - Status::ICMP_ERROR => { - "An ICMP error occurred during the network operation.".to_owned() - } - Status::INCOMPATIBLE_VERSION => { - "The function encountered an internal version that was incompatible with a version requested by the caller.".to_owned() - } - Status::INVALID_LANGUAGE => { - "The language specified was invalid.".to_owned() - } - Status::INVALID_PARAMETER => { - "A parameter was incorrect.".to_owned() - } - Status::IP_ADDRESS_CONFLICT => { - "There is an address conflict address allocation".to_owned() - } - Status::LOAD_ERROR => { - "The image failed to load.".to_owned() - } - Status::MEDIA_CHANGED => { - "The medium in the device has changed since the last access.".to_owned() - } - Status::NETWORK_UNREACHABLE => { - "The network containing the remote host is not reachable.".to_owned() - } - Status::NO_MAPPING => { - "A mapping to a device does not exist.".to_owned() - } - Status::NO_MEDIA => { - "The device does not contain any medium to perform the operation.".to_owned() - } - Status::NO_RESPONSE => { - "The server was not found or did not respond to the request.".to_owned() - } - Status::NOT_FOUND => "The item was not found.".to_owned(), - Status::NOT_READY => { - "There is no data pending upon return.".to_owned() - } - Status::NOT_STARTED => { - "The protocol has not been started.".to_owned() - } - Status::OUT_OF_RESOURCES => { - "A resource has run out.".to_owned() - } - Status::PROTOCOL_ERROR => { - "A protocol error occurred during the network operation.".to_owned() - } - Status::PROTOCOL_UNREACHABLE => { - "An ICMP protocol unreachable error is received.".to_owned() - } - Status::SECURITY_VIOLATION => { - "The function was not performed due to a security violation.".to_owned() - } - Status::TFTP_ERROR => { - "A TFTP error occurred during the network operation.".to_owned() - } - Status::TIMEOUT => "The timeout time expired.".to_owned(), - Status::UNSUPPORTED => { - "The operation is not supported.".to_owned() - } - Status::VOLUME_FULL => { - "There is no more space on the file system.".to_owned() - } - Status::VOLUME_CORRUPTED => { - "An inconstancy was detected on the file system causing the operating to fail.".to_owned() - } - Status::WRITE_PROTECTED => { - "The device cannot be written to.".to_owned() - } - _ => format!("Status: {}", errno), - } -} - -pub fn getcwd() -> io::Result { - unsupported() -} - -pub fn chdir(_: &path::Path) -> io::Result<()> { - unsupported() -} - -pub struct SplitPaths<'a>(!, PhantomData<&'a ()>); - -pub fn split_paths(_unparsed: &OsStr) -> SplitPaths<'_> { - panic!("unsupported") -} - -impl<'a> Iterator for SplitPaths<'a> { - type Item = PathBuf; - fn next(&mut self) -> Option { - self.0 - } -} - -#[derive(Debug)] -pub struct JoinPathsError; - -pub fn join_paths(_paths: I) -> Result -where - I: Iterator, - T: AsRef, -{ - Err(JoinPathsError) -} - -impl fmt::Display for JoinPathsError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - "not supported on this platform yet".fmt(f) - } -} - -impl StdError for JoinPathsError {} - -pub fn current_exe() -> io::Result { - let protocol = helpers::image_handle_protocol::( - loaded_image_device_path::PROTOCOL_GUID, - )?; - helpers::device_path_to_text(protocol).map(PathBuf::from) -} - -pub struct Env(!); - -impl Env { - // FIXME(https://github.com/rust-lang/rust/issues/114583): Remove this when ::fmt matches ::fmt. - pub fn str_debug(&self) -> impl fmt::Debug + '_ { - let Self(inner) = self; - match *inner {} - } -} - -impl Iterator for Env { - type Item = (OsString, OsString); - fn next(&mut self) -> Option<(OsString, OsString)> { - self.0 - } -} - -impl fmt::Debug for Env { - fn fmt(&self, _: &mut fmt::Formatter<'_>) -> fmt::Result { - let Self(inner) = self; - match *inner {} - } -} - -pub fn env() -> Env { - panic!("not supported on this platform") -} - -pub fn getenv(_: &OsStr) -> Option { - None -} - -pub fn setenv(_: &OsStr, _: &OsStr) -> io::Result<()> { - Err(io::const_io_error!(io::ErrorKind::Unsupported, "cannot set env vars on this platform")) -} - -pub fn unsetenv(_: &OsStr) -> io::Result<()> { - Err(io::const_io_error!(io::ErrorKind::Unsupported, "cannot unset env vars on this platform")) -} - -pub fn temp_dir() -> PathBuf { - panic!("no filesystem on this platform") -} - -pub fn home_dir() -> Option { - None -} - -pub fn exit(code: i32) -> ! { - if let (Some(boot_services), Some(handle)) = - (uefi::env::boot_services(), uefi::env::try_image_handle()) - { - let boot_services: NonNull = boot_services.cast(); - let _ = unsafe { - ((*boot_services.as_ptr()).exit)( - handle.as_ptr(), - Status::from_usize(code as usize), - 0, - crate::ptr::null_mut(), - ) - }; - } - crate::intrinsics::abort() -} - -pub fn getpid() -> u32 { - panic!("no pids on this platform") -} diff --git a/library/std/src/sys/pal/uefi/stdio.rs b/library/std/src/sys/pal/uefi/stdio.rs deleted file mode 100644 index 703e8ba8e5710..0000000000000 --- a/library/std/src/sys/pal/uefi/stdio.rs +++ /dev/null @@ -1,219 +0,0 @@ -use crate::io; -use crate::iter::Iterator; -use crate::mem::MaybeUninit; -use crate::os::uefi; -use crate::ptr::NonNull; - -pub struct Stdin { - surrogate: Option, - incomplete_utf8: IncompleteUtf8, -} - -struct IncompleteUtf8 { - bytes: [u8; 4], - len: u8, -} - -impl IncompleteUtf8 { - pub const fn new() -> IncompleteUtf8 { - IncompleteUtf8 { bytes: [0; 4], len: 0 } - } - - // Implemented for use in Stdin::read. - fn read(&mut self, buf: &mut [u8]) -> usize { - // Write to buffer until the buffer is full or we run out of bytes. - let to_write = crate::cmp::min(buf.len(), self.len as usize); - buf[..to_write].copy_from_slice(&self.bytes[..to_write]); - - // Rotate the remaining bytes if not enough remaining space in buffer. - if usize::from(self.len) > buf.len() { - self.bytes.copy_within(to_write.., 0); - self.len -= to_write as u8; - } else { - self.len = 0; - } - - to_write - } -} - -pub struct Stdout; -pub struct Stderr; - -impl Stdin { - pub const fn new() -> Stdin { - Stdin { surrogate: None, incomplete_utf8: IncompleteUtf8::new() } - } -} - -impl io::Read for Stdin { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - // If there are bytes in the incomplete utf-8, start with those. - // (No-op if there is nothing in the buffer.) - let mut bytes_copied = self.incomplete_utf8.read(buf); - - let stdin: *mut r_efi::protocols::simple_text_input::Protocol = unsafe { - let st: NonNull = uefi::env::system_table().cast(); - (*st.as_ptr()).con_in - }; - - if bytes_copied == buf.len() { - return Ok(bytes_copied); - } - - let ch = simple_text_input_read(stdin)?; - // Only 1 character should be returned. - let mut ch: Vec> = - if let Some(x) = self.surrogate.take() { - char::decode_utf16([x, ch]).collect() - } else { - char::decode_utf16([ch]).collect() - }; - - if ch.len() > 1 { - return Err(io::Error::new(io::ErrorKind::InvalidData, "invalid utf-16 sequence")); - } - - match ch.pop().unwrap() { - Err(e) => { - self.surrogate = Some(e.unpaired_surrogate()); - } - Ok(x) => { - // This will always be > 0 - let buf_free_count = buf.len() - bytes_copied; - assert!(buf_free_count > 0); - - if buf_free_count >= x.len_utf8() { - // There is enough space in the buffer for the character. - bytes_copied += x.encode_utf8(&mut buf[bytes_copied..]).len(); - } else { - // There is not enough space in the buffer for the character. - // Store the character in the incomplete buffer. - self.incomplete_utf8.len = - x.encode_utf8(&mut self.incomplete_utf8.bytes).len() as u8; - // write partial character to buffer. - bytes_copied += self.incomplete_utf8.read(buf); - } - } - } - - Ok(bytes_copied) - } -} - -impl Stdout { - pub const fn new() -> Stdout { - Stdout - } -} - -impl io::Write for Stdout { - fn write(&mut self, buf: &[u8]) -> io::Result { - let st: NonNull = uefi::env::system_table().cast(); - let stdout = unsafe { (*st.as_ptr()).con_out }; - - write(stdout, buf) - } - - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -impl Stderr { - pub const fn new() -> Stderr { - Stderr - } -} - -impl io::Write for Stderr { - fn write(&mut self, buf: &[u8]) -> io::Result { - let st: NonNull = uefi::env::system_table().cast(); - let stderr = unsafe { (*st.as_ptr()).std_err }; - - write(stderr, buf) - } - - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -// UTF-16 character should occupy 4 bytes at most in UTF-8 -pub const STDIN_BUF_SIZE: usize = 4; - -pub fn is_ebadf(_err: &io::Error) -> bool { - false -} - -pub fn panic_output() -> Option { - uefi::env::try_system_table().map(|_| Stderr::new()) -} - -fn write( - protocol: *mut r_efi::protocols::simple_text_output::Protocol, - buf: &[u8], -) -> io::Result { - // Get valid UTF-8 buffer - let utf8 = match crate::str::from_utf8(buf) { - Ok(x) => x, - Err(e) => unsafe { crate::str::from_utf8_unchecked(&buf[..e.valid_up_to()]) }, - }; - - let mut utf16: Vec = utf8.encode_utf16().collect(); - // NULL terminate the string - utf16.push(0); - - unsafe { simple_text_output(protocol, &mut utf16) }?; - - Ok(utf8.len()) -} - -unsafe fn simple_text_output( - protocol: *mut r_efi::protocols::simple_text_output::Protocol, - buf: &mut [u16], -) -> io::Result<()> { - let res = unsafe { ((*protocol).output_string)(protocol, buf.as_mut_ptr()) }; - if res.is_error() { Err(io::Error::from_raw_os_error(res.as_usize())) } else { Ok(()) } -} - -fn simple_text_input_read( - stdin: *mut r_efi::protocols::simple_text_input::Protocol, -) -> io::Result { - loop { - match read_key_stroke(stdin) { - Ok(x) => return Ok(x.unicode_char), - Err(e) if e == r_efi::efi::Status::NOT_READY => wait_stdin(stdin)?, - Err(e) => return Err(io::Error::from_raw_os_error(e.as_usize())), - } - } -} - -fn wait_stdin(stdin: *mut r_efi::protocols::simple_text_input::Protocol) -> io::Result<()> { - let boot_services: NonNull = - uefi::env::boot_services().unwrap().cast(); - let wait_for_event = unsafe { (*boot_services.as_ptr()).wait_for_event }; - let wait_for_key_event = unsafe { (*stdin).wait_for_key }; - - let r = { - let mut x: usize = 0; - (wait_for_event)(1, [wait_for_key_event].as_mut_ptr(), &mut x) - }; - if r.is_error() { Err(io::Error::from_raw_os_error(r.as_usize())) } else { Ok(()) } -} - -fn read_key_stroke( - stdin: *mut r_efi::protocols::simple_text_input::Protocol, -) -> Result { - let mut input_key: MaybeUninit = - MaybeUninit::uninit(); - - let r = unsafe { ((*stdin).read_key_stroke)(stdin, input_key.as_mut_ptr()) }; - - if r.is_error() { - Err(r) - } else { - let input_key = unsafe { input_key.assume_init() }; - Ok(input_key) - } -} diff --git a/library/std/src/sys/pal/uefi/tests.rs b/library/std/src/sys/pal/uefi/tests.rs deleted file mode 100644 index 5eb36da922b54..0000000000000 --- a/library/std/src/sys/pal/uefi/tests.rs +++ /dev/null @@ -1,41 +0,0 @@ -use super::alloc::*; -use super::time::*; -use crate::time::Duration; - -#[test] -fn align() { - // UEFI ABI specifies that allocation alignment minimum is always 8. So this can be - // statically verified. - assert_eq!(POOL_ALIGNMENT, 8); - - // Loop over allocation-request sizes from 0-256 and alignments from 1-128, and verify - // that in case of overalignment there is at least space for one additional pointer to - // store in the allocation. - for i in 0..256 { - for j in &[1, 2, 4, 8, 16, 32, 64, 128] { - if *j <= 8 { - assert_eq!(align_size(i, *j), i); - } else { - assert!(align_size(i, *j) > i + std::mem::size_of::<*mut ()>()); - } - } - } -} - -#[test] -fn epoch() { - let t = r_efi::system::Time { - year: 1970, - month: 1, - day: 1, - hour: 0, - minute: 0, - second: 0, - nanosecond: 0, - timezone: r_efi::efi::UNSPECIFIED_TIMEZONE, - daylight: 0, - pad1: 0, - pad2: 0, - }; - assert_eq!(system_time_internal::uefi_time_to_duration(t), Duration::new(0, 0)); -} diff --git a/library/std/src/sys/pal/uefi/thread.rs b/library/std/src/sys/pal/uefi/thread.rs deleted file mode 100644 index edc736978a123..0000000000000 --- a/library/std/src/sys/pal/uefi/thread.rs +++ /dev/null @@ -1,50 +0,0 @@ -use super::unsupported; -use crate::ffi::CStr; -use crate::io; -use crate::num::NonZero; -use crate::ptr::NonNull; -use crate::time::Duration; - -pub struct Thread(!); - -pub const DEFAULT_MIN_STACK_SIZE: usize = 4096; - -impl Thread { - // unsafe: see thread::Builder::spawn_unchecked for safety requirements - pub unsafe fn new(_stack: usize, _p: Box) -> io::Result { - unsupported() - } - - pub fn yield_now() { - // do nothing - } - - pub fn set_name(_name: &CStr) { - // nope - } - - pub fn sleep(dur: Duration) { - let boot_services: NonNull = - crate::os::uefi::env::boot_services().expect("can't sleep").cast(); - let mut dur_ms = dur.as_micros(); - // ceil up to the nearest microsecond - if dur.subsec_nanos() % 1000 > 0 { - dur_ms += 1; - } - - while dur_ms > 0 { - let ms = crate::cmp::min(dur_ms, usize::MAX as u128); - let _ = unsafe { ((*boot_services.as_ptr()).stall)(ms as usize) }; - dur_ms -= ms; - } - } - - pub fn join(self) { - self.0 - } -} - -pub fn available_parallelism() -> io::Result> { - // UEFI is single threaded - Ok(NonZero::new(1).unwrap()) -} diff --git a/library/std/src/sys/pal/uefi/time.rs b/library/std/src/sys/pal/uefi/time.rs deleted file mode 100644 index 76562cf9f51c0..0000000000000 --- a/library/std/src/sys/pal/uefi/time.rs +++ /dev/null @@ -1,221 +0,0 @@ -use crate::time::Duration; - -const SECS_IN_MINUTE: u64 = 60; -const SECS_IN_HOUR: u64 = SECS_IN_MINUTE * 60; -const SECS_IN_DAY: u64 = SECS_IN_HOUR * 24; - -#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)] -pub struct Instant(Duration); - -#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)] -pub struct SystemTime(Duration); - -pub const UNIX_EPOCH: SystemTime = SystemTime(Duration::from_secs(0)); - -impl Instant { - pub fn now() -> Instant { - // If we have a timestamp protocol, use it. - if let Some(x) = instant_internal::timestamp_protocol() { - return x; - } - - if let Some(x) = instant_internal::platform_specific() { - return x; - } - - panic!("time not implemented on this platform") - } - - pub fn checked_sub_instant(&self, other: &Instant) -> Option { - self.0.checked_sub(other.0) - } - - pub fn checked_add_duration(&self, other: &Duration) -> Option { - Some(Instant(self.0.checked_add(*other)?)) - } - - pub fn checked_sub_duration(&self, other: &Duration) -> Option { - Some(Instant(self.0.checked_sub(*other)?)) - } -} - -impl SystemTime { - pub fn now() -> SystemTime { - system_time_internal::now() - .unwrap_or_else(|| panic!("time not implemented on this platform")) - } - - pub fn sub_time(&self, other: &SystemTime) -> Result { - self.0.checked_sub(other.0).ok_or_else(|| other.0 - self.0) - } - - pub fn checked_add_duration(&self, other: &Duration) -> Option { - Some(SystemTime(self.0.checked_add(*other)?)) - } - - pub fn checked_sub_duration(&self, other: &Duration) -> Option { - Some(SystemTime(self.0.checked_sub(*other)?)) - } -} - -pub(crate) mod system_time_internal { - use super::super::helpers; - use super::*; - use crate::mem::MaybeUninit; - use crate::ptr::NonNull; - use r_efi::efi::{RuntimeServices, Time}; - - pub fn now() -> Option { - let runtime_services: NonNull = helpers::runtime_services()?; - let mut t: MaybeUninit

() <= MIN_ALIGN); - assert!(mem::align_of::
() <= MIN_ALIGN); -} diff --git a/library/std/src/sys/pal/windows/api.rs b/library/std/src/sys/pal/windows/api.rs deleted file mode 100644 index 555ad581b8568..0000000000000 --- a/library/std/src/sys/pal/windows/api.rs +++ /dev/null @@ -1,253 +0,0 @@ -//! # Safe(r) wrappers around Windows API functions. -//! -//! This module contains fairly thin wrappers around Windows API functions, -//! aimed at centralising safety instead of having unsafe blocks spread -//! throughout higher level code. This makes it much easier to audit FFI safety. -//! -//! Not all functions can be made completely safe without more context but in -//! such cases we should still endeavour to reduce the caller's burden of safety -//! as much as possible. -//! -//! ## Guidelines for wrappers -//! -//! Items here should be named similarly to their raw Windows API name, except -//! that they follow Rust's case conventions. E.g. function names are -//! lower_snake_case. The idea here is that it should be easy for a Windows -//! C/C++ programmer to identify the underlying function that's being wrapped -//! while not looking too out of place in Rust code. -//! -//! Every use of an `unsafe` block must have a related SAFETY comment, even if -//! it's trivially safe (for example, see `get_last_error`). Public unsafe -//! functions must document what the caller has to do to call them safely. -//! -//! Avoid unchecked `as` casts. For integers, either assert that the integer -//! is in range or use `try_into` instead. For pointers, prefer to use -//! `ptr.cast::()` when possible. -//! -//! This module must only depend on core and not on std types as the eventual -//! hope is to have std depend on sys and not the other way around. -//! However, some amount of glue code may currently be necessary so such code -//! should go in sys/pal/windows/mod.rs rather than here. See `IoResult` as an example. - -use core::ffi::c_void; -use core::ptr::addr_of; - -use super::c; - -/// Creates a null-terminated UTF-16 string from a str. -pub macro wide_str($str:literal) {{ - const _: () = { - if core::slice::memchr::memchr(0, $str.as_bytes()).is_some() { - panic!("null terminated strings cannot contain interior nulls"); - } - }; - crate::sys::pal::windows::api::utf16!(concat!($str, '\0')) -}} - -/// Creates a UTF-16 string from a str without null termination. -pub macro utf16($str:expr) {{ - const UTF8: &str = $str; - const UTF16_LEN: usize = crate::sys::pal::windows::api::utf16_len(UTF8); - const UTF16: [u16; UTF16_LEN] = crate::sys::pal::windows::api::to_utf16(UTF8); - &UTF16 -}} - -#[cfg(test)] -mod tests; - -/// Gets the UTF-16 length of a UTF-8 string, for use in the wide_str macro. -pub const fn utf16_len(s: &str) -> usize { - let s = s.as_bytes(); - let mut i = 0; - let mut len = 0; - while i < s.len() { - // the length of a UTF-8 encoded code-point is given by the number of - // leading ones, except in the case of ASCII. - let utf8_len = match s[i].leading_ones() { - 0 => 1, - n => n as usize, - }; - i += utf8_len; - // Note that UTF-16 surrogates (U+D800 to U+DFFF) are not encodable as UTF-8, - // so (unlike with WTF-8) we don't have to worry about how they'll get re-encoded. - len += if utf8_len < 4 { 1 } else { 2 }; - } - len -} - -/// Const convert UTF-8 to UTF-16, for use in the wide_str macro. -/// -/// Note that this is designed for use in const contexts so is not optimized. -pub const fn to_utf16(s: &str) -> [u16; UTF16_LEN] { - let mut output = [0_u16; UTF16_LEN]; - let mut pos = 0; - let s = s.as_bytes(); - let mut i = 0; - while i < s.len() { - match s[i].leading_ones() { - // Decode UTF-8 based on its length. - // See https://en.wikipedia.org/wiki/UTF-8 - 0 => { - // ASCII is the same in both encodings - output[pos] = s[i] as u16; - i += 1; - pos += 1; - } - 2 => { - // Bits: 110xxxxx 10xxxxxx - output[pos] = ((s[i] as u16 & 0b11111) << 6) | (s[i + 1] as u16 & 0b111111); - i += 2; - pos += 1; - } - 3 => { - // Bits: 1110xxxx 10xxxxxx 10xxxxxx - output[pos] = ((s[i] as u16 & 0b1111) << 12) - | ((s[i + 1] as u16 & 0b111111) << 6) - | (s[i + 2] as u16 & 0b111111); - i += 3; - pos += 1; - } - 4 => { - // Bits: 11110xxx 10xxxxxx 10xxxxxx 10xxxxxx - let mut c = ((s[i] as u32 & 0b111) << 18) - | ((s[i + 1] as u32 & 0b111111) << 12) - | ((s[i + 2] as u32 & 0b111111) << 6) - | (s[i + 3] as u32 & 0b111111); - // re-encode as UTF-16 (see https://en.wikipedia.org/wiki/UTF-16) - // - Subtract 0x10000 from the code point - // - For the high surrogate, shift right by 10 then add 0xD800 - // - For the low surrogate, take the low 10 bits then add 0xDC00 - c -= 0x10000; - output[pos] = ((c >> 10) + 0xD800) as u16; - output[pos + 1] = ((c & 0b1111111111) + 0xDC00) as u16; - i += 4; - pos += 2; - } - // valid UTF-8 cannot have any other values - _ => unreachable!(), - } - } - output -} - -/// Helper method for getting the size of `T` as a u32. -/// Errors at compile time if the size would overflow. -/// -/// While a type larger than u32::MAX is unlikely, it is possible if only because of a bug. -/// However, one key motivation for this function is to avoid the temptation to -/// use frequent `as` casts. This is risky because they are too powerful. -/// For example, the following will compile today: -/// -/// `std::mem::size_of:: as u32` -/// -/// Note that `size_of` is never actually called, instead a function pointer is -/// converted to a `u32`. Clippy would warn about this but, alas, it's not run -/// on the standard library. -const fn win32_size_of() -> u32 { - // Const assert that the size does not exceed u32::MAX. - // Uses a trait to workaround restriction on using generic types in inner items. - trait Win32SizeOf: Sized { - const WIN32_SIZE_OF: u32 = { - let size = core::mem::size_of::(); - assert!(size <= u32::MAX as usize); - size as u32 - }; - } - impl Win32SizeOf for T {} - - T::WIN32_SIZE_OF -} - -/// The `SetFileInformationByHandle` function takes a generic parameter by -/// making the user specify the type (class), a pointer to the data and its -/// size. This trait allows attaching that information to a Rust type so that -/// [`set_file_information_by_handle`] can be called safely. -/// -/// This trait is designed so that it can support variable sized types. -/// However, currently Rust's std only uses fixed sized structures. -/// -/// # Safety -/// -/// * `as_ptr` must return a pointer to memory that is readable up to `size` bytes. -/// * `CLASS` must accurately reflect the type pointed to by `as_ptr`. E.g. -/// the `FILE_BASIC_INFO` structure has the class `FileBasicInfo`. -pub unsafe trait SetFileInformation { - /// The type of information to set. - const CLASS: i32; - /// A pointer to the file information to set. - fn as_ptr(&self) -> *const c_void; - /// The size of the type pointed to by `as_ptr`. - fn size(&self) -> u32; -} -/// Helper trait for implementing `SetFileInformation` for statically sized types. -unsafe trait SizedSetFileInformation: Sized { - const CLASS: i32; -} -unsafe impl SetFileInformation for T { - const CLASS: i32 = T::CLASS; - fn as_ptr(&self) -> *const c_void { - addr_of!(*self).cast::() - } - fn size(&self) -> u32 { - win32_size_of::() - } -} - -// SAFETY: FILE_BASIC_INFO, FILE_END_OF_FILE_INFO, FILE_ALLOCATION_INFO, -// FILE_DISPOSITION_INFO, FILE_DISPOSITION_INFO_EX and FILE_IO_PRIORITY_HINT_INFO -// are all plain `repr(C)` structs that only contain primitive types. -// The given information classes correctly match with the struct. -unsafe impl SizedSetFileInformation for c::FILE_BASIC_INFO { - const CLASS: i32 = c::FileBasicInfo; -} -unsafe impl SizedSetFileInformation for c::FILE_END_OF_FILE_INFO { - const CLASS: i32 = c::FileEndOfFileInfo; -} -unsafe impl SizedSetFileInformation for c::FILE_ALLOCATION_INFO { - const CLASS: i32 = c::FileAllocationInfo; -} -unsafe impl SizedSetFileInformation for c::FILE_DISPOSITION_INFO { - const CLASS: i32 = c::FileDispositionInfo; -} -unsafe impl SizedSetFileInformation for c::FILE_DISPOSITION_INFO_EX { - const CLASS: i32 = c::FileDispositionInfoEx; -} -unsafe impl SizedSetFileInformation for c::FILE_IO_PRIORITY_HINT_INFO { - const CLASS: i32 = c::FileIoPriorityHintInfo; -} - -#[inline] -pub fn set_file_information_by_handle( - handle: c::HANDLE, - info: &T, -) -> Result<(), WinError> { - unsafe fn set_info( - handle: c::HANDLE, - class: i32, - info: *const c_void, - size: u32, - ) -> Result<(), WinError> { - let result = c::SetFileInformationByHandle(handle, class, info, size); - (result != 0).then_some(()).ok_or_else(get_last_error) - } - // SAFETY: The `SetFileInformation` trait ensures that this is safe. - unsafe { set_info(handle, T::CLASS, info.as_ptr(), info.size()) } -} - -/// Gets the error from the last function. -/// This must be called immediately after the function that sets the error to -/// avoid the risk of another function overwriting it. -pub fn get_last_error() -> WinError { - // SAFETY: This just returns a thread-local u32 and has no other effects. - unsafe { WinError { code: c::GetLastError() } } -} - -/// An error code as returned by [`get_last_error`]. -/// -/// This is usually a 16-bit Win32 error code but may be a 32-bit HRESULT or NTSTATUS. -/// Check the documentation of the Windows API function being called for expected errors. -#[derive(Clone, Copy, PartialEq, Eq)] -#[repr(transparent)] -pub struct WinError { - pub code: u32, -} diff --git a/library/std/src/sys/pal/windows/api/tests.rs b/library/std/src/sys/pal/windows/api/tests.rs deleted file mode 100644 index fab022c7b93d8..0000000000000 --- a/library/std/src/sys/pal/windows/api/tests.rs +++ /dev/null @@ -1,16 +0,0 @@ -use crate::sys::pal::windows::api::{utf16, wide_str}; - -macro_rules! check_utf16 { - ($str:literal) => {{ - assert!(wide_str!($str).iter().copied().eq($str.encode_utf16().chain([0]))); - assert!(utf16!($str).iter().copied().eq($str.encode_utf16())); - }}; -} - -#[test] -fn test_utf16_macros() { - check_utf16!("hello world"); - check_utf16!("€4.50"); - check_utf16!("𨉟呐㗂越"); - check_utf16!("Pchnąć w tę łódź jeża lub ośm skrzyń fig"); -} diff --git a/library/std/src/sys/pal/windows/args.rs b/library/std/src/sys/pal/windows/args.rs deleted file mode 100644 index 5098c05196e25..0000000000000 --- a/library/std/src/sys/pal/windows/args.rs +++ /dev/null @@ -1,460 +0,0 @@ -//! The Windows command line is just a string -//! -//! -//! This module implements the parsing necessary to turn that string into a list of arguments. - -#[cfg(test)] -mod tests; - -use super::os::current_exe; -use crate::ffi::{OsStr, OsString}; -use crate::fmt; -use crate::io; -use crate::num::NonZero; -use crate::os::windows::prelude::*; -use crate::path::{Path, PathBuf}; -use crate::sys::path::get_long_path; -use crate::sys::process::ensure_no_nuls; -use crate::sys::{c, to_u16s}; -use crate::sys_common::wstr::WStrUnits; -use crate::sys_common::AsInner; -use crate::vec; - -use crate::iter; - -/// This is the const equivalent to `NonZero::new(n).unwrap()` -/// -/// FIXME: This can be removed once `Option::unwrap` is stably const. -/// See the `const_option` feature (#67441). -const fn non_zero_u16(n: u16) -> NonZero { - match NonZero::new(n) { - Some(n) => n, - None => panic!("called `unwrap` on a `None` value"), - } -} - -pub fn args() -> Args { - // SAFETY: `GetCommandLineW` returns a pointer to a null terminated UTF-16 - // string so it's safe for `WStrUnits` to use. - unsafe { - let lp_cmd_line = c::GetCommandLineW(); - let parsed_args_list = parse_lp_cmd_line(WStrUnits::new(lp_cmd_line), || { - current_exe().map(PathBuf::into_os_string).unwrap_or_else(|_| OsString::new()) - }); - - Args { parsed_args_list: parsed_args_list.into_iter() } - } -} - -/// Implements the Windows command-line argument parsing algorithm. -/// -/// Microsoft's documentation for the Windows CLI argument format can be found at -/// -/// -/// A more in-depth explanation is here: -/// -/// -/// Windows includes a function to do command line parsing in shell32.dll. -/// However, this is not used for two reasons: -/// -/// 1. Linking with that DLL causes the process to be registered as a GUI application. -/// GUI applications add a bunch of overhead, even if no windows are drawn. See -/// . -/// -/// 2. It does not follow the modern C/C++ argv rules outlined in the first two links above. -/// -/// This function was tested for equivalence to the C/C++ parsing rules using an -/// extensive test suite available at -/// . -fn parse_lp_cmd_line<'a, F: Fn() -> OsString>( - lp_cmd_line: Option>, - exe_name: F, -) -> Vec { - const BACKSLASH: NonZero = non_zero_u16(b'\\' as u16); - const QUOTE: NonZero = non_zero_u16(b'"' as u16); - const TAB: NonZero = non_zero_u16(b'\t' as u16); - const SPACE: NonZero = non_zero_u16(b' ' as u16); - - let mut ret_val = Vec::new(); - // If the cmd line pointer is null or it points to an empty string then - // return the name of the executable as argv[0]. - if lp_cmd_line.as_ref().and_then(|cmd| cmd.peek()).is_none() { - ret_val.push(exe_name()); - return ret_val; - } - let mut code_units = lp_cmd_line.unwrap(); - - // The executable name at the beginning is special. - let mut in_quotes = false; - let mut cur = Vec::new(); - for w in &mut code_units { - match w { - // A quote mark always toggles `in_quotes` no matter what because - // there are no escape characters when parsing the executable name. - QUOTE => in_quotes = !in_quotes, - // If not `in_quotes` then whitespace ends argv[0]. - SPACE | TAB if !in_quotes => break, - // In all other cases the code unit is taken literally. - _ => cur.push(w.get()), - } - } - // Skip whitespace. - code_units.advance_while(|w| w == SPACE || w == TAB); - ret_val.push(OsString::from_wide(&cur)); - - // Parse the arguments according to these rules: - // * All code units are taken literally except space, tab, quote and backslash. - // * When not `in_quotes`, space and tab separate arguments. Consecutive spaces and tabs are - // treated as a single separator. - // * A space or tab `in_quotes` is taken literally. - // * A quote toggles `in_quotes` mode unless it's escaped. An escaped quote is taken literally. - // * A quote can be escaped if preceded by an odd number of backslashes. - // * If any number of backslashes is immediately followed by a quote then the number of - // backslashes is halved (rounding down). - // * Backslashes not followed by a quote are all taken literally. - // * If `in_quotes` then a quote can also be escaped using another quote - // (i.e. two consecutive quotes become one literal quote). - let mut cur = Vec::new(); - let mut in_quotes = false; - while let Some(w) = code_units.next() { - match w { - // If not `in_quotes`, a space or tab ends the argument. - SPACE | TAB if !in_quotes => { - ret_val.push(OsString::from_wide(&cur[..])); - cur.truncate(0); - - // Skip whitespace. - code_units.advance_while(|w| w == SPACE || w == TAB); - } - // Backslashes can escape quotes or backslashes but only if consecutive backslashes are followed by a quote. - BACKSLASH => { - let backslash_count = code_units.advance_while(|w| w == BACKSLASH) + 1; - if code_units.peek() == Some(QUOTE) { - cur.extend(iter::repeat(BACKSLASH.get()).take(backslash_count / 2)); - // The quote is escaped if there are an odd number of backslashes. - if backslash_count % 2 == 1 { - code_units.next(); - cur.push(QUOTE.get()); - } - } else { - // If there is no quote on the end then there is no escaping. - cur.extend(iter::repeat(BACKSLASH.get()).take(backslash_count)); - } - } - // If `in_quotes` and not backslash escaped (see above) then a quote either - // unsets `in_quote` or is escaped by another quote. - QUOTE if in_quotes => match code_units.peek() { - // Two consecutive quotes when `in_quotes` produces one literal quote. - Some(QUOTE) => { - cur.push(QUOTE.get()); - code_units.next(); - } - // Otherwise set `in_quotes`. - Some(_) => in_quotes = false, - // The end of the command line. - // Push `cur` even if empty, which we do by breaking while `in_quotes` is still set. - None => break, - }, - // If not `in_quotes` and not BACKSLASH escaped (see above) then a quote sets `in_quote`. - QUOTE => in_quotes = true, - // Everything else is always taken literally. - _ => cur.push(w.get()), - } - } - // Push the final argument, if any. - if !cur.is_empty() || in_quotes { - ret_val.push(OsString::from_wide(&cur[..])); - } - ret_val -} - -pub struct Args { - parsed_args_list: vec::IntoIter, -} - -impl fmt::Debug for Args { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.parsed_args_list.as_slice().fmt(f) - } -} - -impl Iterator for Args { - type Item = OsString; - fn next(&mut self) -> Option { - self.parsed_args_list.next() - } - fn size_hint(&self) -> (usize, Option) { - self.parsed_args_list.size_hint() - } -} - -impl DoubleEndedIterator for Args { - fn next_back(&mut self) -> Option { - self.parsed_args_list.next_back() - } -} - -impl ExactSizeIterator for Args { - fn len(&self) -> usize { - self.parsed_args_list.len() - } -} - -#[derive(Debug)] -pub(crate) enum Arg { - /// Add quotes (if needed) - Regular(OsString), - /// Append raw string without quoting - Raw(OsString), -} - -enum Quote { - // Every arg is quoted - Always, - // Whitespace and empty args are quoted - Auto, - // Arg appended without any changes (#29494) - Never, -} - -pub(crate) fn append_arg(cmd: &mut Vec, arg: &Arg, force_quotes: bool) -> io::Result<()> { - let (arg, quote) = match arg { - Arg::Regular(arg) => (arg, if force_quotes { Quote::Always } else { Quote::Auto }), - Arg::Raw(arg) => (arg, Quote::Never), - }; - - // If an argument has 0 characters then we need to quote it to ensure - // that it actually gets passed through on the command line or otherwise - // it will be dropped entirely when parsed on the other end. - ensure_no_nuls(arg)?; - let arg_bytes = arg.as_encoded_bytes(); - let (quote, escape) = match quote { - Quote::Always => (true, true), - Quote::Auto => { - (arg_bytes.iter().any(|c| *c == b' ' || *c == b'\t') || arg_bytes.is_empty(), true) - } - Quote::Never => (false, false), - }; - if quote { - cmd.push('"' as u16); - } - - let mut backslashes: usize = 0; - for x in arg.encode_wide() { - if escape { - if x == '\\' as u16 { - backslashes += 1; - } else { - if x == '"' as u16 { - // Add n+1 backslashes to total 2n+1 before internal '"'. - cmd.extend((0..=backslashes).map(|_| '\\' as u16)); - } - backslashes = 0; - } - } - cmd.push(x); - } - - if quote { - // Add n backslashes to total 2n before ending '"'. - cmd.extend((0..backslashes).map(|_| '\\' as u16)); - cmd.push('"' as u16); - } - Ok(()) -} - -fn append_bat_arg(cmd: &mut Vec, arg: &OsStr, mut quote: bool) -> io::Result<()> { - ensure_no_nuls(arg)?; - // If an argument has 0 characters then we need to quote it to ensure - // that it actually gets passed through on the command line or otherwise - // it will be dropped entirely when parsed on the other end. - // - // We also need to quote the argument if it ends with `\` to guard against - // bat usage such as `"%~2"` (i.e. force quote arguments) otherwise a - // trailing slash will escape the closing quote. - if arg.is_empty() || arg.as_encoded_bytes().last() == Some(&b'\\') { - quote = true; - } - for cp in arg.as_inner().inner.code_points() { - if let Some(cp) = cp.to_char() { - // Rather than trying to find every ascii symbol that must be quoted, - // we assume that all ascii symbols must be quoted unless they're known to be good. - // We also quote Unicode control blocks for good measure. - // Note an unquoted `\` is fine so long as the argument isn't otherwise quoted. - static UNQUOTED: &str = r"#$*+-./:?@\_"; - let ascii_needs_quotes = - cp.is_ascii() && !(cp.is_ascii_alphanumeric() || UNQUOTED.contains(cp)); - if ascii_needs_quotes || cp.is_control() { - quote = true; - } - } - } - - if quote { - cmd.push('"' as u16); - } - // Loop through the string, escaping `\` only if followed by `"`. - // And escaping `"` by doubling them. - let mut backslashes: usize = 0; - for x in arg.encode_wide() { - if x == '\\' as u16 { - backslashes += 1; - } else { - if x == '"' as u16 { - // Add n backslashes to total 2n before internal `"`. - cmd.extend((0..backslashes).map(|_| '\\' as u16)); - // Appending an additional double-quote acts as an escape. - cmd.push(b'"' as u16) - } else if x == '%' as u16 || x == '\r' as u16 { - // yt-dlp hack: replaces `%` with `%%cd:~,%` to stop %VAR% being expanded as an environment variable. - // - // # Explanation - // - // cmd supports extracting a substring from a variable using the following syntax: - // %variable:~start_index,end_index% - // - // In the above command `cd` is used as the variable and the start_index and end_index are left blank. - // `cd` is a built-in variable that dynamically expands to the current directory so it's always available. - // Explicitly omitting both the start and end index creates a zero-length substring. - // - // Therefore it all resolves to nothing. However, by doing this no-op we distract cmd.exe - // from potentially expanding %variables% in the argument. - cmd.extend_from_slice(&[ - '%' as u16, '%' as u16, 'c' as u16, 'd' as u16, ':' as u16, '~' as u16, - ',' as u16, - ]); - } - backslashes = 0; - } - cmd.push(x); - } - if quote { - // Add n backslashes to total 2n before ending `"`. - cmd.extend((0..backslashes).map(|_| '\\' as u16)); - cmd.push('"' as u16); - } - Ok(()) -} - -pub(crate) fn make_bat_command_line( - script: &[u16], - args: &[Arg], - force_quotes: bool, -) -> io::Result> { - const INVALID_ARGUMENT_ERROR: io::Error = - io::const_io_error!(io::ErrorKind::InvalidInput, r#"batch file arguments are invalid"#); - // Set the start of the command line to `cmd.exe /c "` - // It is necessary to surround the command in an extra pair of quotes, - // hence the trailing quote here. It will be closed after all arguments - // have been added. - // Using /e:ON enables "command extensions" which is essential for the `%` hack to work. - let mut cmd: Vec = "cmd.exe /e:ON /v:OFF /d /c \"".encode_utf16().collect(); - - // Push the script name surrounded by its quote pair. - cmd.push(b'"' as u16); - // Windows file names cannot contain a `"` character or end with `\\`. - // If the script name does then return an error. - if script.contains(&(b'"' as u16)) || script.last() == Some(&(b'\\' as u16)) { - return Err(io::const_io_error!( - io::ErrorKind::InvalidInput, - "Windows file names may not contain `\"` or end with `\\`" - )); - } - cmd.extend_from_slice(script.strip_suffix(&[0]).unwrap_or(script)); - cmd.push(b'"' as u16); - - // Append the arguments. - // FIXME: This needs tests to ensure that the arguments are properly - // reconstructed by the batch script by default. - for arg in args { - cmd.push(' ' as u16); - match arg { - Arg::Regular(arg_os) => { - let arg_bytes = arg_os.as_encoded_bytes(); - // Disallow \r and \n as they may truncate the arguments. - const DISALLOWED: &[u8] = b"\r\n"; - if arg_bytes.iter().any(|c| DISALLOWED.contains(c)) { - return Err(INVALID_ARGUMENT_ERROR); - } - append_bat_arg(&mut cmd, arg_os, force_quotes)?; - } - _ => { - // Raw arguments are passed on as-is. - // It's the user's responsibility to properly handle arguments in this case. - append_arg(&mut cmd, arg, force_quotes)?; - } - }; - } - - // Close the quote we left opened earlier. - cmd.push(b'"' as u16); - - Ok(cmd) -} - -/// Takes a path and tries to return a non-verbatim path. -/// -/// This is necessary because cmd.exe does not support verbatim paths. -pub(crate) fn to_user_path(path: &Path) -> io::Result> { - from_wide_to_user_path(to_u16s(path)?) -} -pub(crate) fn from_wide_to_user_path(mut path: Vec) -> io::Result> { - use super::fill_utf16_buf; - use crate::ptr; - - // UTF-16 encoded code points, used in parsing and building UTF-16 paths. - // All of these are in the ASCII range so they can be cast directly to `u16`. - const SEP: u16 = b'\\' as _; - const QUERY: u16 = b'?' as _; - const COLON: u16 = b':' as _; - const U: u16 = b'U' as _; - const N: u16 = b'N' as _; - const C: u16 = b'C' as _; - - // Early return if the path is too long to remove the verbatim prefix. - const LEGACY_MAX_PATH: usize = 260; - if path.len() > LEGACY_MAX_PATH { - return Ok(path); - } - - match &path[..] { - // `\\?\C:\...` => `C:\...` - [SEP, SEP, QUERY, SEP, _, COLON, SEP, ..] => unsafe { - let lpfilename = path[4..].as_ptr(); - fill_utf16_buf( - |buffer, size| c::GetFullPathNameW(lpfilename, size, buffer, ptr::null_mut()), - |full_path: &[u16]| { - if full_path == &path[4..path.len() - 1] { - let mut path: Vec = full_path.into(); - path.push(0); - path - } else { - path - } - }, - ) - }, - // `\\?\UNC\...` => `\\...` - [SEP, SEP, QUERY, SEP, U, N, C, SEP, ..] => unsafe { - // Change the `C` in `UNC\` to `\` so we can get a slice that starts with `\\`. - path[6] = b'\\' as u16; - let lpfilename = path[6..].as_ptr(); - fill_utf16_buf( - |buffer, size| c::GetFullPathNameW(lpfilename, size, buffer, ptr::null_mut()), - |full_path: &[u16]| { - if full_path == &path[6..path.len() - 1] { - let mut path: Vec = full_path.into(); - path.push(0); - path - } else { - // Restore the 'C' in "UNC". - path[6] = b'C' as u16; - path - } - }, - ) - }, - // For everything else, leave the path unchanged. - _ => get_long_path(path, false), - } -} diff --git a/library/std/src/sys/pal/windows/args/tests.rs b/library/std/src/sys/pal/windows/args/tests.rs deleted file mode 100644 index 484a90ab056df..0000000000000 --- a/library/std/src/sys/pal/windows/args/tests.rs +++ /dev/null @@ -1,91 +0,0 @@ -use super::*; -use crate::ffi::OsString; - -fn chk(string: &str, parts: &[&str]) { - let mut wide: Vec = OsString::from(string).encode_wide().collect(); - wide.push(0); - let parsed = - unsafe { parse_lp_cmd_line(WStrUnits::new(wide.as_ptr()), || OsString::from("TEST.EXE")) }; - let expected: Vec = parts.iter().map(|k| OsString::from(k)).collect(); - assert_eq!(parsed.as_slice(), expected.as_slice(), "{:?}", string); -} - -#[test] -fn empty() { - chk("", &["TEST.EXE"]); - chk("\0", &["TEST.EXE"]); -} - -#[test] -fn single_words() { - chk("EXE one_word", &["EXE", "one_word"]); - chk("EXE a", &["EXE", "a"]); - chk("EXE 😅", &["EXE", "😅"]); - chk("EXE 😅🤦", &["EXE", "😅🤦"]); -} - -#[test] -fn official_examples() { - chk(r#"EXE "abc" d e"#, &["EXE", "abc", "d", "e"]); - chk(r#"EXE a\\\b d"e f"g h"#, &["EXE", r"a\\\b", "de fg", "h"]); - chk(r#"EXE a\\\"b c d"#, &["EXE", r#"a\"b"#, "c", "d"]); - chk(r#"EXE a\\\\"b c" d e"#, &["EXE", r"a\\b c", "d", "e"]); -} - -#[test] -fn whitespace_behavior() { - chk(" test", &["", "test"]); - chk(" test", &["", "test"]); - chk(" test test2", &["", "test", "test2"]); - chk(" test test2", &["", "test", "test2"]); - chk("test test2 ", &["test", "test2"]); - chk("test test2 ", &["test", "test2"]); - chk("test ", &["test"]); -} - -#[test] -fn genius_quotes() { - chk(r#"EXE "" """#, &["EXE", "", ""]); - chk(r#"EXE "" """"#, &["EXE", "", r#"""#]); - chk( - r#"EXE "this is """all""" in the same argument""#, - &["EXE", r#"this is "all" in the same argument"#], - ); - chk(r#"EXE "a"""#, &["EXE", r#"a""#]); - chk(r#"EXE "a"" a"#, &["EXE", r#"a" a"#]); - // quotes cannot be escaped in command names - chk(r#""EXE" check"#, &["EXE", "check"]); - chk(r#""EXE check""#, &["EXE check"]); - chk(r#""EXE """for""" check"#, &["EXE for check"]); - chk(r#""EXE \"for\" check"#, &[r"EXE \for\ check"]); - chk(r#""EXE \" for \" check"#, &[r"EXE \", "for", r#"""#, "check"]); - chk(r#"E"X"E test"#, &["EXE", "test"]); - chk(r#"EX""E test"#, &["EXE", "test"]); -} - -// from https://daviddeley.com/autohotkey/parameters/parameters.htm#WINCRULESEX -#[test] -fn post_2008() { - chk("EXE CallMeIshmael", &["EXE", "CallMeIshmael"]); - chk(r#"EXE "Call Me Ishmael""#, &["EXE", "Call Me Ishmael"]); - chk(r#"EXE Cal"l Me I"shmael"#, &["EXE", "Call Me Ishmael"]); - chk(r#"EXE CallMe\"Ishmael"#, &["EXE", r#"CallMe"Ishmael"#]); - chk(r#"EXE "CallMe\"Ishmael""#, &["EXE", r#"CallMe"Ishmael"#]); - chk(r#"EXE "Call Me Ishmael\\""#, &["EXE", r"Call Me Ishmael\"]); - chk(r#"EXE "CallMe\\\"Ishmael""#, &["EXE", r#"CallMe\"Ishmael"#]); - chk(r#"EXE a\\\b"#, &["EXE", r"a\\\b"]); - chk(r#"EXE "a\\\b""#, &["EXE", r"a\\\b"]); - chk(r#"EXE "\"Call Me Ishmael\"""#, &["EXE", r#""Call Me Ishmael""#]); - chk(r#"EXE "C:\TEST A\\""#, &["EXE", r"C:\TEST A\"]); - chk(r#"EXE "\"C:\TEST A\\\"""#, &["EXE", r#""C:\TEST A\""#]); - chk(r#"EXE "a b c" d e"#, &["EXE", "a b c", "d", "e"]); - chk(r#"EXE "ab\"c" "\\" d"#, &["EXE", r#"ab"c"#, r"\", "d"]); - chk(r#"EXE a\\\b d"e f"g h"#, &["EXE", r"a\\\b", "de fg", "h"]); - chk(r#"EXE a\\\"b c d"#, &["EXE", r#"a\"b"#, "c", "d"]); - chk(r#"EXE a\\\\"b c" d e"#, &["EXE", r"a\\b c", "d", "e"]); - // Double Double Quotes - chk(r#"EXE "a b c"""#, &["EXE", r#"a b c""#]); - chk(r#"EXE """CallMeIshmael""" b c"#, &["EXE", r#""CallMeIshmael""#, "b", "c"]); - chk(r#"EXE """Call Me Ishmael""""#, &["EXE", r#""Call Me Ishmael""#]); - chk(r#"EXE """"Call Me Ishmael"" b c"#, &["EXE", r#""Call"#, "Me", "Ishmael", "b", "c"]); -} diff --git a/library/std/src/sys/pal/windows/c.rs b/library/std/src/sys/pal/windows/c.rs deleted file mode 100644 index 9d58ce05f018b..0000000000000 --- a/library/std/src/sys/pal/windows/c.rs +++ /dev/null @@ -1,521 +0,0 @@ -//! C definitions used by libnative that don't belong in liblibc - -#![allow(nonstandard_style)] -#![cfg_attr(test, allow(dead_code))] -#![unstable(issue = "none", feature = "windows_c")] -#![allow(clippy::style)] - -use crate::ffi::CStr; -use crate::mem; -use crate::num::NonZero; -pub use crate::os::raw::c_int; -use crate::os::raw::{c_char, c_long, c_longlong, c_uint, c_ulong, c_ushort, c_void}; -use crate::os::windows::io::{AsRawHandle, BorrowedHandle}; -use crate::ptr; - -mod windows_sys; -pub use windows_sys::*; - -pub type DWORD = c_ulong; -pub type NonZeroDWORD = NonZero; -pub type LARGE_INTEGER = c_longlong; -#[cfg_attr(target_vendor = "uwp", allow(unused))] -pub type LONG = c_long; -pub type UINT = c_uint; -pub type WCHAR = u16; -pub type USHORT = c_ushort; -pub type SIZE_T = usize; -pub type CHAR = c_char; -pub type ULONG = c_ulong; - -pub type LPCVOID = *const c_void; -pub type LPOVERLAPPED = *mut OVERLAPPED; -pub type LPSECURITY_ATTRIBUTES = *mut SECURITY_ATTRIBUTES; -pub type LPVOID = *mut c_void; -pub type LPWCH = *mut WCHAR; -pub type LPWSTR = *mut WCHAR; - -#[cfg(target_vendor = "win7")] -pub type PSRWLOCK = *mut SRWLOCK; - -pub type socklen_t = c_int; -pub type ADDRESS_FAMILY = USHORT; -pub use FD_SET as fd_set; -pub use LINGER as linger; -pub use TIMEVAL as timeval; - -pub const INVALID_HANDLE_VALUE: HANDLE = ::core::ptr::without_provenance_mut(-1i32 as _); - -// https://learn.microsoft.com/en-us/cpp/c-runtime-library/exit-success-exit-failure?view=msvc-170 -pub const EXIT_SUCCESS: u32 = 0; -pub const EXIT_FAILURE: u32 = 1; - -#[cfg(target_vendor = "win7")] -pub const CONDITION_VARIABLE_INIT: CONDITION_VARIABLE = CONDITION_VARIABLE { Ptr: ptr::null_mut() }; -#[cfg(target_vendor = "win7")] -pub const SRWLOCK_INIT: SRWLOCK = SRWLOCK { Ptr: ptr::null_mut() }; -pub const INIT_ONCE_STATIC_INIT: INIT_ONCE = INIT_ONCE { Ptr: ptr::null_mut() }; - -// Some windows_sys types have different signs than the types we use. -pub const OBJ_DONT_REPARSE: u32 = windows_sys::OBJ_DONT_REPARSE as u32; -pub const FRS_ERR_SYSVOL_POPULATE_TIMEOUT: u32 = - windows_sys::FRS_ERR_SYSVOL_POPULATE_TIMEOUT as u32; -pub const AF_INET: c_int = windows_sys::AF_INET as c_int; -pub const AF_INET6: c_int = windows_sys::AF_INET6 as c_int; - -#[repr(C)] -pub struct ip_mreq { - pub imr_multiaddr: in_addr, - pub imr_interface: in_addr, -} - -#[repr(C)] -pub struct ipv6_mreq { - pub ipv6mr_multiaddr: in6_addr, - pub ipv6mr_interface: c_uint, -} - -// Equivalent to the `NT_SUCCESS` C preprocessor macro. -// See: https://docs.microsoft.com/en-us/windows-hardware/drivers/kernel/using-ntstatus-values -pub fn nt_success(status: NTSTATUS) -> bool { - status >= 0 -} - -impl UNICODE_STRING { - pub fn from_ref(slice: &[u16]) -> Self { - let len = mem::size_of_val(slice); - Self { Length: len as _, MaximumLength: len as _, Buffer: slice.as_ptr() as _ } - } -} - -impl Default for OBJECT_ATTRIBUTES { - fn default() -> Self { - Self { - Length: mem::size_of::() as _, - RootDirectory: ptr::null_mut(), - ObjectName: ptr::null_mut(), - Attributes: 0, - SecurityDescriptor: ptr::null_mut(), - SecurityQualityOfService: ptr::null_mut(), - } - } -} - -impl IO_STATUS_BLOCK { - pub const PENDING: Self = - IO_STATUS_BLOCK { Anonymous: IO_STATUS_BLOCK_0 { Status: STATUS_PENDING }, Information: 0 }; - pub fn status(&self) -> NTSTATUS { - // SAFETY: If `self.Anonymous.Status` was set then this is obviously safe. - // If `self.Anonymous.Pointer` was set then this is the equivalent to converting - // the pointer to an integer, which is also safe. - // Currently the only safe way to construct `IO_STATUS_BLOCK` outside of - // this module is to call the `default` method, which sets the `Status`. - unsafe { self.Anonymous.Status } - } -} - -/// NB: Use carefully! In general using this as a reference is likely to get the -/// provenance wrong for the `rest` field! -#[repr(C)] -pub struct REPARSE_DATA_BUFFER { - pub ReparseTag: c_uint, - pub ReparseDataLength: c_ushort, - pub Reserved: c_ushort, - pub rest: (), -} - -/// NB: Use carefully! In general using this as a reference is likely to get the -/// provenance wrong for the `PathBuffer` field! -#[repr(C)] -pub struct SYMBOLIC_LINK_REPARSE_BUFFER { - pub SubstituteNameOffset: c_ushort, - pub SubstituteNameLength: c_ushort, - pub PrintNameOffset: c_ushort, - pub PrintNameLength: c_ushort, - pub Flags: c_ulong, - pub PathBuffer: WCHAR, -} - -#[repr(C)] -pub struct MOUNT_POINT_REPARSE_BUFFER { - pub SubstituteNameOffset: c_ushort, - pub SubstituteNameLength: c_ushort, - pub PrintNameOffset: c_ushort, - pub PrintNameLength: c_ushort, - pub PathBuffer: WCHAR, -} - -#[repr(C)] -pub struct SOCKADDR_STORAGE_LH { - pub ss_family: ADDRESS_FAMILY, - pub __ss_pad1: [CHAR; 6], - pub __ss_align: i64, - pub __ss_pad2: [CHAR; 112], -} - -#[repr(C)] -#[derive(Copy, Clone)] -pub struct sockaddr_in { - pub sin_family: ADDRESS_FAMILY, - pub sin_port: USHORT, - pub sin_addr: in_addr, - pub sin_zero: [CHAR; 8], -} - -#[repr(C)] -#[derive(Copy, Clone)] -pub struct sockaddr_in6 { - pub sin6_family: ADDRESS_FAMILY, - pub sin6_port: USHORT, - pub sin6_flowinfo: c_ulong, - pub sin6_addr: in6_addr, - pub sin6_scope_id: c_ulong, -} - -#[repr(C)] -#[derive(Copy, Clone)] -pub struct in_addr { - pub s_addr: u32, -} - -#[repr(C)] -#[derive(Copy, Clone)] -pub struct in6_addr { - pub s6_addr: [u8; 16], -} - -// Desktop specific functions & types -cfg_if::cfg_if! { -if #[cfg(not(target_vendor = "uwp"))] { - pub const EXCEPTION_CONTINUE_SEARCH: i32 = 0; -} -} - -pub unsafe extern "system" fn WriteFileEx( - hFile: BorrowedHandle<'_>, - lpBuffer: *mut ::core::ffi::c_void, - nNumberOfBytesToWrite: u32, - lpOverlapped: *mut OVERLAPPED, - lpCompletionRoutine: LPOVERLAPPED_COMPLETION_ROUTINE, -) -> BOOL { - windows_sys::WriteFileEx( - hFile.as_raw_handle(), - lpBuffer.cast::(), - nNumberOfBytesToWrite, - lpOverlapped, - lpCompletionRoutine, - ) -} - -pub unsafe extern "system" fn ReadFileEx( - hFile: BorrowedHandle<'_>, - lpBuffer: *mut ::core::ffi::c_void, - nNumberOfBytesToRead: u32, - lpOverlapped: *mut OVERLAPPED, - lpCompletionRoutine: LPOVERLAPPED_COMPLETION_ROUTINE, -) -> BOOL { - windows_sys::ReadFileEx( - hFile.as_raw_handle(), - lpBuffer.cast::(), - nNumberOfBytesToRead, - lpOverlapped, - lpCompletionRoutine, - ) -} - -// POSIX compatibility shims. -pub unsafe fn recv(socket: SOCKET, buf: *mut c_void, len: c_int, flags: c_int) -> c_int { - windows_sys::recv(socket, buf.cast::(), len, flags) -} -pub unsafe fn send(socket: SOCKET, buf: *const c_void, len: c_int, flags: c_int) -> c_int { - windows_sys::send(socket, buf.cast::(), len, flags) -} -pub unsafe fn recvfrom( - socket: SOCKET, - buf: *mut c_void, - len: c_int, - flags: c_int, - addr: *mut SOCKADDR, - addrlen: *mut c_int, -) -> c_int { - windows_sys::recvfrom(socket, buf.cast::(), len, flags, addr, addrlen) -} -pub unsafe fn sendto( - socket: SOCKET, - buf: *const c_void, - len: c_int, - flags: c_int, - addr: *const SOCKADDR, - addrlen: c_int, -) -> c_int { - windows_sys::sendto(socket, buf.cast::(), len, flags, addr, addrlen) -} -pub unsafe fn getaddrinfo( - node: *const c_char, - service: *const c_char, - hints: *const ADDRINFOA, - res: *mut *mut ADDRINFOA, -) -> c_int { - windows_sys::getaddrinfo(node.cast::(), service.cast::(), hints, res) -} - -cfg_if::cfg_if! { -if #[cfg(not(target_vendor = "uwp"))] { -pub unsafe fn NtReadFile( - filehandle: BorrowedHandle<'_>, - event: HANDLE, - apcroutine: PIO_APC_ROUTINE, - apccontext: *mut c_void, - iostatusblock: &mut IO_STATUS_BLOCK, - buffer: *mut crate::mem::MaybeUninit, - length: ULONG, - byteoffset: Option<&LARGE_INTEGER>, - key: Option<&ULONG>, -) -> NTSTATUS { - windows_sys::NtReadFile( - filehandle.as_raw_handle(), - event, - apcroutine, - apccontext, - iostatusblock, - buffer.cast::(), - length, - byteoffset.map(|o| o as *const i64).unwrap_or(ptr::null()), - key.map(|k| k as *const u32).unwrap_or(ptr::null()), - ) -} -pub unsafe fn NtWriteFile( - filehandle: BorrowedHandle<'_>, - event: HANDLE, - apcroutine: PIO_APC_ROUTINE, - apccontext: *mut c_void, - iostatusblock: &mut IO_STATUS_BLOCK, - buffer: *const u8, - length: ULONG, - byteoffset: Option<&LARGE_INTEGER>, - key: Option<&ULONG>, -) -> NTSTATUS { - windows_sys::NtWriteFile( - filehandle.as_raw_handle(), - event, - apcroutine, - apccontext, - iostatusblock, - buffer.cast::(), - length, - byteoffset.map(|o| o as *const i64).unwrap_or(ptr::null()), - key.map(|k| k as *const u32).unwrap_or(ptr::null()), - ) -} -} -} - -// Use raw-dylib to import ProcessPrng as we can't rely on there being an import library. -cfg_if::cfg_if! { -if #[cfg(not(target_vendor = "win7"))] { - #[cfg(target_arch = "x86")] - #[link(name = "bcryptprimitives", kind = "raw-dylib", import_name_type = "undecorated")] - extern "system" { - pub fn ProcessPrng(pbdata: *mut u8, cbdata: usize) -> BOOL; - } - #[cfg(not(target_arch = "x86"))] - #[link(name = "bcryptprimitives", kind = "raw-dylib")] - extern "system" { - pub fn ProcessPrng(pbdata: *mut u8, cbdata: usize) -> BOOL; - } -}} - -// Functions that aren't available on every version of Windows that we support, -// but we still use them and just provide some form of a fallback implementation. -compat_fn_with_fallback! { - pub static KERNEL32: &CStr = c"kernel32"; - - // >= Win10 1607 - // https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-setthreaddescription - pub fn SetThreadDescription(hthread: HANDLE, lpthreaddescription: PCWSTR) -> HRESULT { - SetLastError(ERROR_CALL_NOT_IMPLEMENTED as DWORD); E_NOTIMPL - } - - // >= Win10 1607 - // https://docs.microsoft.com/en-us/windows/win32/api/processthreadsapi/nf-processthreadsapi-getthreaddescription - pub fn GetThreadDescription(hthread: HANDLE, lpthreaddescription: *mut PWSTR) -> HRESULT { - SetLastError(ERROR_CALL_NOT_IMPLEMENTED as DWORD); E_NOTIMPL - } - - // >= Win8 / Server 2012 - // https://docs.microsoft.com/en-us/windows/win32/api/sysinfoapi/nf-sysinfoapi-getsystemtimepreciseasfiletime - #[cfg(target_vendor = "win7")] - pub fn GetSystemTimePreciseAsFileTime(lpsystemtimeasfiletime: *mut FILETIME) -> () { - GetSystemTimeAsFileTime(lpsystemtimeasfiletime) - } - - // >= Win11 / Server 2022 - // https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-gettemppath2a - pub fn GetTempPath2W(bufferlength: u32, buffer: PWSTR) -> u32 { - GetTempPathW(bufferlength, buffer) - } -} - -#[cfg(not(target_vendor = "win7"))] -// Use raw-dylib to import synchronization functions to workaround issues with the older mingw import library. -#[cfg_attr( - target_arch = "x86", - link( - name = "api-ms-win-core-synch-l1-2-0", - kind = "raw-dylib", - import_name_type = "undecorated" - ) -)] -#[cfg_attr( - not(target_arch = "x86"), - link(name = "api-ms-win-core-synch-l1-2-0", kind = "raw-dylib") -)] -extern "system" { - pub fn WaitOnAddress( - address: *const c_void, - compareaddress: *const c_void, - addresssize: usize, - dwmilliseconds: u32, - ) -> BOOL; - pub fn WakeByAddressSingle(address: *const c_void); - pub fn WakeByAddressAll(address: *const c_void); -} - -#[cfg(target_vendor = "win7")] -compat_fn_optional! { - crate::sys::compat::load_synch_functions(); - pub fn WaitOnAddress( - address: *const ::core::ffi::c_void, - compareaddress: *const ::core::ffi::c_void, - addresssize: usize, - dwmilliseconds: u32 - ) -> BOOL; - pub fn WakeByAddressSingle(address: *const ::core::ffi::c_void); -} - -#[cfg(any(target_vendor = "win7", target_vendor = "uwp"))] -compat_fn_with_fallback! { - pub static NTDLL: &CStr = c"ntdll"; - - #[cfg(target_vendor = "win7")] - pub fn NtCreateKeyedEvent( - KeyedEventHandle: *mut HANDLE, - DesiredAccess: DWORD, - ObjectAttributes: LPVOID, - Flags: ULONG - ) -> NTSTATUS { - panic!("keyed events not available") - } - #[cfg(target_vendor = "win7")] - pub fn NtReleaseKeyedEvent( - EventHandle: HANDLE, - Key: LPVOID, - Alertable: BOOLEAN, - Timeout: *mut c_longlong - ) -> NTSTATUS { - panic!("keyed events not available") - } - #[cfg(target_vendor = "win7")] - pub fn NtWaitForKeyedEvent( - EventHandle: HANDLE, - Key: LPVOID, - Alertable: BOOLEAN, - Timeout: *mut c_longlong - ) -> NTSTATUS { - panic!("keyed events not available") - } - - // These functions are available on UWP when lazily loaded. They will fail WACK if loaded statically. - #[cfg(target_vendor = "uwp")] - pub fn NtCreateFile( - filehandle: *mut HANDLE, - desiredaccess: FILE_ACCESS_RIGHTS, - objectattributes: *const OBJECT_ATTRIBUTES, - iostatusblock: *mut IO_STATUS_BLOCK, - allocationsize: *const i64, - fileattributes: FILE_FLAGS_AND_ATTRIBUTES, - shareaccess: FILE_SHARE_MODE, - createdisposition: NTCREATEFILE_CREATE_DISPOSITION, - createoptions: NTCREATEFILE_CREATE_OPTIONS, - eabuffer: *const ::core::ffi::c_void, - ealength: u32 - ) -> NTSTATUS { - STATUS_NOT_IMPLEMENTED - } - #[cfg(target_vendor = "uwp")] - pub fn NtReadFile( - filehandle: BorrowedHandle<'_>, - event: HANDLE, - apcroutine: PIO_APC_ROUTINE, - apccontext: *mut c_void, - iostatusblock: &mut IO_STATUS_BLOCK, - buffer: *mut crate::mem::MaybeUninit, - length: ULONG, - byteoffset: Option<&LARGE_INTEGER>, - key: Option<&ULONG> - ) -> NTSTATUS { - STATUS_NOT_IMPLEMENTED - } - #[cfg(target_vendor = "uwp")] - pub fn NtWriteFile( - filehandle: BorrowedHandle<'_>, - event: HANDLE, - apcroutine: PIO_APC_ROUTINE, - apccontext: *mut c_void, - iostatusblock: &mut IO_STATUS_BLOCK, - buffer: *const u8, - length: ULONG, - byteoffset: Option<&LARGE_INTEGER>, - key: Option<&ULONG> - ) -> NTSTATUS { - STATUS_NOT_IMPLEMENTED - } - #[cfg(target_vendor = "uwp")] - pub fn RtlNtStatusToDosError(Status: NTSTATUS) -> u32 { - Status as u32 - } -} - -// # Arm32 shim -// -// AddVectoredExceptionHandler and WSAStartup use platform-specific types. -// However, Microsoft no longer supports thumbv7a so definitions for those targets -// are not included in the win32 metadata. We work around that by defining them here. -// -// Where possible, these definitions should be kept in sync with https://docs.rs/windows-sys -cfg_if::cfg_if! { -if #[cfg(not(target_vendor = "uwp"))] { - #[link(name = "kernel32")] - extern "system" { - pub fn AddVectoredExceptionHandler( - first: u32, - handler: PVECTORED_EXCEPTION_HANDLER, - ) -> *mut c_void; - } - pub type PVECTORED_EXCEPTION_HANDLER = Option< - unsafe extern "system" fn(exceptioninfo: *mut EXCEPTION_POINTERS) -> i32, - >; - #[repr(C)] - pub struct EXCEPTION_POINTERS { - pub ExceptionRecord: *mut EXCEPTION_RECORD, - pub ContextRecord: *mut CONTEXT, - } - #[cfg(target_arch = "arm")] - pub enum CONTEXT {} -}} - -#[link(name = "ws2_32")] -extern "system" { - pub fn WSAStartup(wversionrequested: u16, lpwsadata: *mut WSADATA) -> i32; -} -#[cfg(target_arch = "arm")] -#[repr(C)] -pub struct WSADATA { - pub wVersion: u16, - pub wHighVersion: u16, - pub szDescription: [u8; 257], - pub szSystemStatus: [u8; 129], - pub iMaxSockets: u16, - pub iMaxUdpDg: u16, - pub lpVendorInfo: PSTR, -} diff --git a/library/std/src/sys/pal/windows/c/README.md b/library/std/src/sys/pal/windows/c/README.md deleted file mode 100644 index d458e55efbcdd..0000000000000 --- a/library/std/src/sys/pal/windows/c/README.md +++ /dev/null @@ -1,9 +0,0 @@ -The `windows_sys.rs` file is autogenerated from `bindings.txt` and must not -be edited manually. - -To add bindings, edit `bindings.txt` then regenerate using the following command: - - ./x run generate-windows-sys && ./x fmt library/std - -If you need to override generated functions or types then add them to -`library/std/src/sys/pal/windows/c.rs`. diff --git a/library/std/src/sys/pal/windows/c/bindings.txt b/library/std/src/sys/pal/windows/c/bindings.txt deleted file mode 100644 index 849e64ac59135..0000000000000 --- a/library/std/src/sys/pal/windows/c/bindings.txt +++ /dev/null @@ -1,2592 +0,0 @@ ---out windows_sys.rs ---config flatten std ---filter -!Windows.Win32.Foundation.INVALID_HANDLE_VALUE -Windows.Wdk.Storage.FileSystem.FILE_COMPLETE_IF_OPLOCKED -Windows.Wdk.Storage.FileSystem.FILE_CONTAINS_EXTENDED_CREATE_INFORMATION -Windows.Wdk.Storage.FileSystem.FILE_CREATE -Windows.Wdk.Storage.FileSystem.FILE_CREATE_TREE_CONNECTION -Windows.Wdk.Storage.FileSystem.FILE_DELETE_ON_CLOSE -Windows.Wdk.Storage.FileSystem.FILE_DIRECTORY_FILE -Windows.Wdk.Storage.FileSystem.FILE_DISALLOW_EXCLUSIVE -Windows.Wdk.Storage.FileSystem.FILE_NO_COMPRESSION -Windows.Wdk.Storage.FileSystem.FILE_NO_EA_KNOWLEDGE -Windows.Wdk.Storage.FileSystem.FILE_NO_INTERMEDIATE_BUFFERING -Windows.Wdk.Storage.FileSystem.FILE_NON_DIRECTORY_FILE -Windows.Wdk.Storage.FileSystem.FILE_OPEN -Windows.Wdk.Storage.FileSystem.FILE_OPEN_BY_FILE_ID -Windows.Wdk.Storage.FileSystem.FILE_OPEN_FOR_BACKUP_INTENT -Windows.Wdk.Storage.FileSystem.FILE_OPEN_FOR_FREE_SPACE_QUERY -Windows.Wdk.Storage.FileSystem.FILE_OPEN_IF -Windows.Wdk.Storage.FileSystem.FILE_OPEN_NO_RECALL -Windows.Wdk.Storage.FileSystem.FILE_OPEN_REPARSE_POINT -Windows.Wdk.Storage.FileSystem.FILE_OPEN_REQUIRING_OPLOCK -Windows.Wdk.Storage.FileSystem.FILE_OVERWRITE -Windows.Wdk.Storage.FileSystem.FILE_OVERWRITE_IF -Windows.Wdk.Storage.FileSystem.FILE_RANDOM_ACCESS -Windows.Wdk.Storage.FileSystem.FILE_RESERVE_OPFILTER -Windows.Wdk.Storage.FileSystem.FILE_SEQUENTIAL_ONLY -Windows.Wdk.Storage.FileSystem.FILE_SESSION_AWARE -Windows.Wdk.Storage.FileSystem.FILE_SUPERSEDE -Windows.Wdk.Storage.FileSystem.FILE_SYNCHRONOUS_IO_ALERT -Windows.Wdk.Storage.FileSystem.FILE_SYNCHRONOUS_IO_NONALERT -Windows.Wdk.Storage.FileSystem.FILE_WRITE_THROUGH -Windows.Wdk.Storage.FileSystem.NtCreateFile -Windows.Wdk.Storage.FileSystem.NTCREATEFILE_CREATE_DISPOSITION -Windows.Wdk.Storage.FileSystem.NTCREATEFILE_CREATE_OPTIONS -Windows.Wdk.Storage.FileSystem.NtReadFile -Windows.Wdk.Storage.FileSystem.NtWriteFile -Windows.Wdk.Storage.FileSystem.SYMLINK_FLAG_RELATIVE -Windows.Win32.Foundation.BOOL -Windows.Win32.Foundation.BOOLEAN -Windows.Win32.Foundation.CloseHandle -Windows.Win32.Foundation.DNS_ERROR_ADDRESS_REQUIRED -Windows.Win32.Foundation.DNS_ERROR_ALIAS_LOOP -Windows.Win32.Foundation.DNS_ERROR_AUTOZONE_ALREADY_EXISTS -Windows.Win32.Foundation.DNS_ERROR_AXFR -Windows.Win32.Foundation.DNS_ERROR_BACKGROUND_LOADING -Windows.Win32.Foundation.DNS_ERROR_BAD_KEYMASTER -Windows.Win32.Foundation.DNS_ERROR_BAD_PACKET -Windows.Win32.Foundation.DNS_ERROR_CANNOT_FIND_ROOT_HINTS -Windows.Win32.Foundation.DNS_ERROR_CLIENT_SUBNET_ALREADY_EXISTS -Windows.Win32.Foundation.DNS_ERROR_CLIENT_SUBNET_DOES_NOT_EXIST -Windows.Win32.Foundation.DNS_ERROR_CLIENT_SUBNET_IS_ACCESSED -Windows.Win32.Foundation.DNS_ERROR_CNAME_COLLISION -Windows.Win32.Foundation.DNS_ERROR_CNAME_LOOP -Windows.Win32.Foundation.DNS_ERROR_DATAFILE_OPEN_FAILURE -Windows.Win32.Foundation.DNS_ERROR_DATAFILE_PARSING -Windows.Win32.Foundation.DNS_ERROR_DEFAULT_SCOPE -Windows.Win32.Foundation.DNS_ERROR_DEFAULT_VIRTUALIZATION_INSTANCE -Windows.Win32.Foundation.DNS_ERROR_DEFAULT_ZONESCOPE -Windows.Win32.Foundation.DNS_ERROR_DELEGATION_REQUIRED -Windows.Win32.Foundation.DNS_ERROR_DNAME_COLLISION -Windows.Win32.Foundation.DNS_ERROR_DNSSEC_IS_DISABLED -Windows.Win32.Foundation.DNS_ERROR_DP_ALREADY_ENLISTED -Windows.Win32.Foundation.DNS_ERROR_DP_ALREADY_EXISTS -Windows.Win32.Foundation.DNS_ERROR_DP_DOES_NOT_EXIST -Windows.Win32.Foundation.DNS_ERROR_DP_FSMO_ERROR -Windows.Win32.Foundation.DNS_ERROR_DP_NOT_AVAILABLE -Windows.Win32.Foundation.DNS_ERROR_DP_NOT_ENLISTED -Windows.Win32.Foundation.DNS_ERROR_DS_UNAVAILABLE -Windows.Win32.Foundation.DNS_ERROR_DS_ZONE_ALREADY_EXISTS -Windows.Win32.Foundation.DNS_ERROR_DWORD_VALUE_TOO_LARGE -Windows.Win32.Foundation.DNS_ERROR_DWORD_VALUE_TOO_SMALL -Windows.Win32.Foundation.DNS_ERROR_FILE_WRITEBACK_FAILED -Windows.Win32.Foundation.DNS_ERROR_FORWARDER_ALREADY_EXISTS -Windows.Win32.Foundation.DNS_ERROR_INCONSISTENT_ROOT_HINTS -Windows.Win32.Foundation.DNS_ERROR_INVAILD_VIRTUALIZATION_INSTANCE_NAME -Windows.Win32.Foundation.DNS_ERROR_INVALID_CLIENT_SUBNET_NAME -Windows.Win32.Foundation.DNS_ERROR_INVALID_DATA -Windows.Win32.Foundation.DNS_ERROR_INVALID_DATAFILE_NAME -Windows.Win32.Foundation.DNS_ERROR_INVALID_INITIAL_ROLLOVER_OFFSET -Windows.Win32.Foundation.DNS_ERROR_INVALID_IP_ADDRESS -Windows.Win32.Foundation.DNS_ERROR_INVALID_KEY_SIZE -Windows.Win32.Foundation.DNS_ERROR_INVALID_NAME -Windows.Win32.Foundation.DNS_ERROR_INVALID_NAME_CHAR -Windows.Win32.Foundation.DNS_ERROR_INVALID_NSEC3_ITERATION_COUNT -Windows.Win32.Foundation.DNS_ERROR_INVALID_POLICY_TABLE -Windows.Win32.Foundation.DNS_ERROR_INVALID_PROPERTY -Windows.Win32.Foundation.DNS_ERROR_INVALID_ROLLOVER_PERIOD -Windows.Win32.Foundation.DNS_ERROR_INVALID_SCOPE_NAME -Windows.Win32.Foundation.DNS_ERROR_INVALID_SCOPE_OPERATION -Windows.Win32.Foundation.DNS_ERROR_INVALID_SIGNATURE_VALIDITY_PERIOD -Windows.Win32.Foundation.DNS_ERROR_INVALID_TYPE -Windows.Win32.Foundation.DNS_ERROR_INVALID_XML -Windows.Win32.Foundation.DNS_ERROR_INVALID_ZONE_OPERATION -Windows.Win32.Foundation.DNS_ERROR_INVALID_ZONE_TYPE -Windows.Win32.Foundation.DNS_ERROR_INVALID_ZONESCOPE_NAME -Windows.Win32.Foundation.DNS_ERROR_KEYMASTER_REQUIRED -Windows.Win32.Foundation.DNS_ERROR_KSP_DOES_NOT_SUPPORT_PROTECTION -Windows.Win32.Foundation.DNS_ERROR_KSP_NOT_ACCESSIBLE -Windows.Win32.Foundation.DNS_ERROR_LOAD_ZONESCOPE_FAILED -Windows.Win32.Foundation.DNS_ERROR_NAME_DOES_NOT_EXIST -Windows.Win32.Foundation.DNS_ERROR_NAME_NOT_IN_ZONE -Windows.Win32.Foundation.DNS_ERROR_NBSTAT_INIT_FAILED -Windows.Win32.Foundation.DNS_ERROR_NEED_SECONDARY_ADDRESSES -Windows.Win32.Foundation.DNS_ERROR_NEED_WINS_SERVERS -Windows.Win32.Foundation.DNS_ERROR_NO_BOOTFILE_IF_DS_ZONE -Windows.Win32.Foundation.DNS_ERROR_NO_CREATE_CACHE_DATA -Windows.Win32.Foundation.DNS_ERROR_NO_DNS_SERVERS -Windows.Win32.Foundation.DNS_ERROR_NO_MEMORY -Windows.Win32.Foundation.DNS_ERROR_NO_PACKET -Windows.Win32.Foundation.DNS_ERROR_NO_TCPIP -Windows.Win32.Foundation.DNS_ERROR_NO_VALID_TRUST_ANCHORS -Windows.Win32.Foundation.DNS_ERROR_NO_ZONE_INFO -Windows.Win32.Foundation.DNS_ERROR_NODE_CREATION_FAILED -Windows.Win32.Foundation.DNS_ERROR_NODE_IS_CNAME -Windows.Win32.Foundation.DNS_ERROR_NODE_IS_DNAME -Windows.Win32.Foundation.DNS_ERROR_NON_RFC_NAME -Windows.Win32.Foundation.DNS_ERROR_NOT_ALLOWED_ON_ACTIVE_SKD -Windows.Win32.Foundation.DNS_ERROR_NOT_ALLOWED_ON_RODC -Windows.Win32.Foundation.DNS_ERROR_NOT_ALLOWED_ON_ROOT_SERVER -Windows.Win32.Foundation.DNS_ERROR_NOT_ALLOWED_ON_SIGNED_ZONE -Windows.Win32.Foundation.DNS_ERROR_NOT_ALLOWED_ON_UNSIGNED_ZONE -Windows.Win32.Foundation.DNS_ERROR_NOT_ALLOWED_ON_ZSK -Windows.Win32.Foundation.DNS_ERROR_NOT_ALLOWED_UNDER_DELEGATION -Windows.Win32.Foundation.DNS_ERROR_NOT_ALLOWED_UNDER_DNAME -Windows.Win32.Foundation.DNS_ERROR_NOT_ALLOWED_WITH_ZONESCOPES -Windows.Win32.Foundation.DNS_ERROR_NOT_ENOUGH_SIGNING_KEY_DESCRIPTORS -Windows.Win32.Foundation.DNS_ERROR_NOT_UNIQUE -Windows.Win32.Foundation.DNS_ERROR_NSEC3_INCOMPATIBLE_WITH_RSA_SHA1 -Windows.Win32.Foundation.DNS_ERROR_NSEC3_NAME_COLLISION -Windows.Win32.Foundation.DNS_ERROR_NSEC_INCOMPATIBLE_WITH_NSEC3_RSA_SHA1 -Windows.Win32.Foundation.DNS_ERROR_NUMERIC_NAME -Windows.Win32.Foundation.DNS_ERROR_POLICY_ALREADY_EXISTS -Windows.Win32.Foundation.DNS_ERROR_POLICY_DOES_NOT_EXIST -Windows.Win32.Foundation.DNS_ERROR_POLICY_INVALID_CRITERIA -Windows.Win32.Foundation.DNS_ERROR_POLICY_INVALID_CRITERIA_CLIENT_SUBNET -Windows.Win32.Foundation.DNS_ERROR_POLICY_INVALID_CRITERIA_FQDN -Windows.Win32.Foundation.DNS_ERROR_POLICY_INVALID_CRITERIA_INTERFACE -Windows.Win32.Foundation.DNS_ERROR_POLICY_INVALID_CRITERIA_NETWORK_PROTOCOL -Windows.Win32.Foundation.DNS_ERROR_POLICY_INVALID_CRITERIA_QUERY_TYPE -Windows.Win32.Foundation.DNS_ERROR_POLICY_INVALID_CRITERIA_TIME_OF_DAY -Windows.Win32.Foundation.DNS_ERROR_POLICY_INVALID_CRITERIA_TRANSPORT_PROTOCOL -Windows.Win32.Foundation.DNS_ERROR_POLICY_INVALID_NAME -Windows.Win32.Foundation.DNS_ERROR_POLICY_INVALID_SETTINGS -Windows.Win32.Foundation.DNS_ERROR_POLICY_INVALID_WEIGHT -Windows.Win32.Foundation.DNS_ERROR_POLICY_LOCKED -Windows.Win32.Foundation.DNS_ERROR_POLICY_MISSING_CRITERIA -Windows.Win32.Foundation.DNS_ERROR_POLICY_PROCESSING_ORDER_INVALID -Windows.Win32.Foundation.DNS_ERROR_POLICY_SCOPE_MISSING -Windows.Win32.Foundation.DNS_ERROR_POLICY_SCOPE_NOT_ALLOWED -Windows.Win32.Foundation.DNS_ERROR_PRIMARY_REQUIRES_DATAFILE -Windows.Win32.Foundation.DNS_ERROR_RCODE -Windows.Win32.Foundation.DNS_ERROR_RCODE_BADKEY -Windows.Win32.Foundation.DNS_ERROR_RCODE_BADSIG -Windows.Win32.Foundation.DNS_ERROR_RCODE_BADTIME -Windows.Win32.Foundation.DNS_ERROR_RCODE_FORMAT_ERROR -Windows.Win32.Foundation.DNS_ERROR_RCODE_NAME_ERROR -Windows.Win32.Foundation.DNS_ERROR_RCODE_NOT_IMPLEMENTED -Windows.Win32.Foundation.DNS_ERROR_RCODE_NOTAUTH -Windows.Win32.Foundation.DNS_ERROR_RCODE_NOTZONE -Windows.Win32.Foundation.DNS_ERROR_RCODE_NXRRSET -Windows.Win32.Foundation.DNS_ERROR_RCODE_REFUSED -Windows.Win32.Foundation.DNS_ERROR_RCODE_SERVER_FAILURE -Windows.Win32.Foundation.DNS_ERROR_RCODE_YXDOMAIN -Windows.Win32.Foundation.DNS_ERROR_RCODE_YXRRSET -Windows.Win32.Foundation.DNS_ERROR_RECORD_ALREADY_EXISTS -Windows.Win32.Foundation.DNS_ERROR_RECORD_DOES_NOT_EXIST -Windows.Win32.Foundation.DNS_ERROR_RECORD_FORMAT -Windows.Win32.Foundation.DNS_ERROR_RECORD_ONLY_AT_ZONE_ROOT -Windows.Win32.Foundation.DNS_ERROR_RECORD_TIMED_OUT -Windows.Win32.Foundation.DNS_ERROR_ROLLOVER_ALREADY_QUEUED -Windows.Win32.Foundation.DNS_ERROR_ROLLOVER_IN_PROGRESS -Windows.Win32.Foundation.DNS_ERROR_ROLLOVER_NOT_POKEABLE -Windows.Win32.Foundation.DNS_ERROR_RRL_INVALID_IPV4_PREFIX -Windows.Win32.Foundation.DNS_ERROR_RRL_INVALID_IPV6_PREFIX -Windows.Win32.Foundation.DNS_ERROR_RRL_INVALID_LEAK_RATE -Windows.Win32.Foundation.DNS_ERROR_RRL_INVALID_TC_RATE -Windows.Win32.Foundation.DNS_ERROR_RRL_INVALID_WINDOW_SIZE -Windows.Win32.Foundation.DNS_ERROR_RRL_LEAK_RATE_LESSTHAN_TC_RATE -Windows.Win32.Foundation.DNS_ERROR_RRL_NOT_ENABLED -Windows.Win32.Foundation.DNS_ERROR_SCOPE_ALREADY_EXISTS -Windows.Win32.Foundation.DNS_ERROR_SCOPE_DOES_NOT_EXIST -Windows.Win32.Foundation.DNS_ERROR_SCOPE_LOCKED -Windows.Win32.Foundation.DNS_ERROR_SECONDARY_DATA -Windows.Win32.Foundation.DNS_ERROR_SECONDARY_REQUIRES_MASTER_IP -Windows.Win32.Foundation.DNS_ERROR_SERVERSCOPE_IS_REFERENCED -Windows.Win32.Foundation.DNS_ERROR_SIGNING_KEY_NOT_ACCESSIBLE -Windows.Win32.Foundation.DNS_ERROR_SOA_DELETE_INVALID -Windows.Win32.Foundation.DNS_ERROR_STANDBY_KEY_NOT_PRESENT -Windows.Win32.Foundation.DNS_ERROR_SUBNET_ALREADY_EXISTS -Windows.Win32.Foundation.DNS_ERROR_SUBNET_DOES_NOT_EXIST -Windows.Win32.Foundation.DNS_ERROR_TOO_MANY_SKDS -Windows.Win32.Foundation.DNS_ERROR_TRY_AGAIN_LATER -Windows.Win32.Foundation.DNS_ERROR_UNEXPECTED_CNG_ERROR -Windows.Win32.Foundation.DNS_ERROR_UNEXPECTED_DATA_PROTECTION_ERROR -Windows.Win32.Foundation.DNS_ERROR_UNKNOWN_RECORD_TYPE -Windows.Win32.Foundation.DNS_ERROR_UNKNOWN_SIGNING_PARAMETER_VERSION -Windows.Win32.Foundation.DNS_ERROR_UNSECURE_PACKET -Windows.Win32.Foundation.DNS_ERROR_UNSUPPORTED_ALGORITHM -Windows.Win32.Foundation.DNS_ERROR_VIRTUALIZATION_INSTANCE_ALREADY_EXISTS -Windows.Win32.Foundation.DNS_ERROR_VIRTUALIZATION_INSTANCE_DOES_NOT_EXIST -Windows.Win32.Foundation.DNS_ERROR_VIRTUALIZATION_TREE_LOCKED -Windows.Win32.Foundation.DNS_ERROR_WINS_INIT_FAILED -Windows.Win32.Foundation.DNS_ERROR_ZONE_ALREADY_EXISTS -Windows.Win32.Foundation.DNS_ERROR_ZONE_CONFIGURATION_ERROR -Windows.Win32.Foundation.DNS_ERROR_ZONE_CREATION_FAILED -Windows.Win32.Foundation.DNS_ERROR_ZONE_DOES_NOT_EXIST -Windows.Win32.Foundation.DNS_ERROR_ZONE_HAS_NO_NS_RECORDS -Windows.Win32.Foundation.DNS_ERROR_ZONE_HAS_NO_SOA_RECORD -Windows.Win32.Foundation.DNS_ERROR_ZONE_IS_SHUTDOWN -Windows.Win32.Foundation.DNS_ERROR_ZONE_LOCKED -Windows.Win32.Foundation.DNS_ERROR_ZONE_LOCKED_FOR_SIGNING -Windows.Win32.Foundation.DNS_ERROR_ZONE_NOT_SECONDARY -Windows.Win32.Foundation.DNS_ERROR_ZONE_REQUIRES_MASTER_IP -Windows.Win32.Foundation.DNS_ERROR_ZONESCOPE_ALREADY_EXISTS -Windows.Win32.Foundation.DNS_ERROR_ZONESCOPE_DOES_NOT_EXIST -Windows.Win32.Foundation.DNS_ERROR_ZONESCOPE_FILE_WRITEBACK_FAILED -Windows.Win32.Foundation.DNS_ERROR_ZONESCOPE_IS_REFERENCED -Windows.Win32.Foundation.DUPLICATE_CLOSE_SOURCE -Windows.Win32.Foundation.DUPLICATE_HANDLE_OPTIONS -Windows.Win32.Foundation.DUPLICATE_SAME_ACCESS -Windows.Win32.Foundation.DuplicateHandle -Windows.Win32.Foundation.E_NOTIMPL -Windows.Win32.Foundation.ERROR_ABANDON_HIBERFILE -Windows.Win32.Foundation.ERROR_ABANDONED_WAIT_0 -Windows.Win32.Foundation.ERROR_ABANDONED_WAIT_63 -Windows.Win32.Foundation.ERROR_ABIOS_ERROR -Windows.Win32.Foundation.ERROR_ACCESS_AUDIT_BY_POLICY -Windows.Win32.Foundation.ERROR_ACCESS_DENIED -Windows.Win32.Foundation.ERROR_ACCESS_DENIED_APPDATA -Windows.Win32.Foundation.ERROR_ACCESS_DISABLED_BY_POLICY -Windows.Win32.Foundation.ERROR_ACCESS_DISABLED_NO_SAFER_UI_BY_POLICY -Windows.Win32.Foundation.ERROR_ACCESS_DISABLED_WEBBLADE -Windows.Win32.Foundation.ERROR_ACCESS_DISABLED_WEBBLADE_TAMPER -Windows.Win32.Foundation.ERROR_ACCOUNT_DISABLED -Windows.Win32.Foundation.ERROR_ACCOUNT_EXPIRED -Windows.Win32.Foundation.ERROR_ACCOUNT_LOCKED_OUT -Windows.Win32.Foundation.ERROR_ACCOUNT_RESTRICTION -Windows.Win32.Foundation.ERROR_ACPI_ERROR -Windows.Win32.Foundation.ERROR_ACTIVE_CONNECTIONS -Windows.Win32.Foundation.ERROR_ADAP_HDW_ERR -Windows.Win32.Foundation.ERROR_ADDRESS_ALREADY_ASSOCIATED -Windows.Win32.Foundation.ERROR_ADDRESS_NOT_ASSOCIATED -Windows.Win32.Foundation.ERROR_ALERTED -Windows.Win32.Foundation.ERROR_ALIAS_EXISTS -Windows.Win32.Foundation.ERROR_ALL_USER_TRUST_QUOTA_EXCEEDED -Windows.Win32.Foundation.ERROR_ALLOCATE_BUCKET -Windows.Win32.Foundation.ERROR_ALLOTTED_SPACE_EXCEEDED -Windows.Win32.Foundation.ERROR_ALREADY_ASSIGNED -Windows.Win32.Foundation.ERROR_ALREADY_EXISTS -Windows.Win32.Foundation.ERROR_ALREADY_FIBER -Windows.Win32.Foundation.ERROR_ALREADY_HAS_STREAM_ID -Windows.Win32.Foundation.ERROR_ALREADY_INITIALIZED -Windows.Win32.Foundation.ERROR_ALREADY_REGISTERED -Windows.Win32.Foundation.ERROR_ALREADY_RUNNING_LKG -Windows.Win32.Foundation.ERROR_ALREADY_THREAD -Windows.Win32.Foundation.ERROR_ALREADY_WAITING -Windows.Win32.Foundation.ERROR_ALREADY_WIN32 -Windows.Win32.Foundation.ERROR_API_UNAVAILABLE -Windows.Win32.Foundation.ERROR_APP_HANG -Windows.Win32.Foundation.ERROR_APP_INIT_FAILURE -Windows.Win32.Foundation.ERROR_APP_WRONG_OS -Windows.Win32.Foundation.ERROR_APPCONTAINER_REQUIRED -Windows.Win32.Foundation.ERROR_APPEXEC_APP_COMPAT_BLOCK -Windows.Win32.Foundation.ERROR_APPEXEC_CALLER_WAIT_TIMEOUT -Windows.Win32.Foundation.ERROR_APPEXEC_CALLER_WAIT_TIMEOUT_LICENSING -Windows.Win32.Foundation.ERROR_APPEXEC_CALLER_WAIT_TIMEOUT_RESOURCES -Windows.Win32.Foundation.ERROR_APPEXEC_CALLER_WAIT_TIMEOUT_TERMINATION -Windows.Win32.Foundation.ERROR_APPEXEC_CONDITION_NOT_SATISFIED -Windows.Win32.Foundation.ERROR_APPEXEC_HANDLE_INVALIDATED -Windows.Win32.Foundation.ERROR_APPEXEC_HOST_ID_MISMATCH -Windows.Win32.Foundation.ERROR_APPEXEC_INVALID_HOST_GENERATION -Windows.Win32.Foundation.ERROR_APPEXEC_INVALID_HOST_STATE -Windows.Win32.Foundation.ERROR_APPEXEC_NO_DONOR -Windows.Win32.Foundation.ERROR_APPEXEC_UNEXPECTED_PROCESS_REGISTRATION -Windows.Win32.Foundation.ERROR_APPEXEC_UNKNOWN_USER -Windows.Win32.Foundation.ERROR_APPHELP_BLOCK -Windows.Win32.Foundation.ERROR_APPX_FILE_NOT_ENCRYPTED -Windows.Win32.Foundation.ERROR_ARBITRATION_UNHANDLED -Windows.Win32.Foundation.ERROR_ARENA_TRASHED -Windows.Win32.Foundation.ERROR_ARITHMETIC_OVERFLOW -Windows.Win32.Foundation.ERROR_ASSERTION_FAILURE -Windows.Win32.Foundation.ERROR_ATOMIC_LOCKS_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_AUDIT_FAILED -Windows.Win32.Foundation.ERROR_AUTHENTICATION_FIREWALL_FAILED -Windows.Win32.Foundation.ERROR_AUTHIP_FAILURE -Windows.Win32.Foundation.ERROR_AUTODATASEG_EXCEEDS_64k -Windows.Win32.Foundation.ERROR_BACKUP_CONTROLLER -Windows.Win32.Foundation.ERROR_BAD_ACCESSOR_FLAGS -Windows.Win32.Foundation.ERROR_BAD_ARGUMENTS -Windows.Win32.Foundation.ERROR_BAD_COMMAND -Windows.Win32.Foundation.ERROR_BAD_COMPRESSION_BUFFER -Windows.Win32.Foundation.ERROR_BAD_CONFIGURATION -Windows.Win32.Foundation.ERROR_BAD_CURRENT_DIRECTORY -Windows.Win32.Foundation.ERROR_BAD_DESCRIPTOR_FORMAT -Windows.Win32.Foundation.ERROR_BAD_DEV_TYPE -Windows.Win32.Foundation.ERROR_BAD_DEVICE -Windows.Win32.Foundation.ERROR_BAD_DEVICE_PATH -Windows.Win32.Foundation.ERROR_BAD_DLL_ENTRYPOINT -Windows.Win32.Foundation.ERROR_BAD_DRIVER_LEVEL -Windows.Win32.Foundation.ERROR_BAD_ENVIRONMENT -Windows.Win32.Foundation.ERROR_BAD_EXE_FORMAT -Windows.Win32.Foundation.ERROR_BAD_FILE_TYPE -Windows.Win32.Foundation.ERROR_BAD_FORMAT -Windows.Win32.Foundation.ERROR_BAD_FUNCTION_TABLE -Windows.Win32.Foundation.ERROR_BAD_IMPERSONATION_LEVEL -Windows.Win32.Foundation.ERROR_BAD_INHERITANCE_ACL -Windows.Win32.Foundation.ERROR_BAD_LENGTH -Windows.Win32.Foundation.ERROR_BAD_LOGON_SESSION_STATE -Windows.Win32.Foundation.ERROR_BAD_MCFG_TABLE -Windows.Win32.Foundation.ERROR_BAD_NET_NAME -Windows.Win32.Foundation.ERROR_BAD_NET_RESP -Windows.Win32.Foundation.ERROR_BAD_NETPATH -Windows.Win32.Foundation.ERROR_BAD_PATHNAME -Windows.Win32.Foundation.ERROR_BAD_PIPE -Windows.Win32.Foundation.ERROR_BAD_PROFILE -Windows.Win32.Foundation.ERROR_BAD_PROVIDER -Windows.Win32.Foundation.ERROR_BAD_QUERY_SYNTAX -Windows.Win32.Foundation.ERROR_BAD_RECOVERY_POLICY -Windows.Win32.Foundation.ERROR_BAD_REM_ADAP -Windows.Win32.Foundation.ERROR_BAD_SERVICE_ENTRYPOINT -Windows.Win32.Foundation.ERROR_BAD_STACK -Windows.Win32.Foundation.ERROR_BAD_THREADID_ADDR -Windows.Win32.Foundation.ERROR_BAD_TOKEN_TYPE -Windows.Win32.Foundation.ERROR_BAD_UNIT -Windows.Win32.Foundation.ERROR_BAD_USER_PROFILE -Windows.Win32.Foundation.ERROR_BAD_USERNAME -Windows.Win32.Foundation.ERROR_BAD_VALIDATION_CLASS -Windows.Win32.Foundation.ERROR_BADDB -Windows.Win32.Foundation.ERROR_BADKEY -Windows.Win32.Foundation.ERROR_BADSTARTPOSITION -Windows.Win32.Foundation.ERROR_BEGINNING_OF_MEDIA -Windows.Win32.Foundation.ERROR_BEYOND_VDL -Windows.Win32.Foundation.ERROR_BIOS_FAILED_TO_CONNECT_INTERRUPT -Windows.Win32.Foundation.ERROR_BLOCK_SHARED -Windows.Win32.Foundation.ERROR_BLOCK_SOURCE_WEAK_REFERENCE_INVALID -Windows.Win32.Foundation.ERROR_BLOCK_TARGET_WEAK_REFERENCE_INVALID -Windows.Win32.Foundation.ERROR_BLOCK_TOO_MANY_REFERENCES -Windows.Win32.Foundation.ERROR_BLOCK_WEAK_REFERENCE_INVALID -Windows.Win32.Foundation.ERROR_BLOCKED_BY_PARENTAL_CONTROLS -Windows.Win32.Foundation.ERROR_BOOT_ALREADY_ACCEPTED -Windows.Win32.Foundation.ERROR_BROKEN_PIPE -Windows.Win32.Foundation.ERROR_BUFFER_ALL_ZEROS -Windows.Win32.Foundation.ERROR_BUFFER_OVERFLOW -Windows.Win32.Foundation.ERROR_BUS_RESET -Windows.Win32.Foundation.ERROR_BUSY -Windows.Win32.Foundation.ERROR_BUSY_DRIVE -Windows.Win32.Foundation.ERROR_BYPASSIO_FLT_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_CACHE_PAGE_LOCKED -Windows.Win32.Foundation.ERROR_CALL_NOT_IMPLEMENTED -Windows.Win32.Foundation.ERROR_CALLBACK_INVOKE_INLINE -Windows.Win32.Foundation.ERROR_CALLBACK_POP_STACK -Windows.Win32.Foundation.ERROR_CALLBACK_SUPPLIED_INVALID_DATA -Windows.Win32.Foundation.ERROR_CAN_NOT_COMPLETE -Windows.Win32.Foundation.ERROR_CANCEL_VIOLATION -Windows.Win32.Foundation.ERROR_CANCELLED -Windows.Win32.Foundation.ERROR_CANNOT_BREAK_OPLOCK -Windows.Win32.Foundation.ERROR_CANNOT_COPY -Windows.Win32.Foundation.ERROR_CANNOT_DETECT_DRIVER_FAILURE -Windows.Win32.Foundation.ERROR_CANNOT_DETECT_PROCESS_ABORT -Windows.Win32.Foundation.ERROR_CANNOT_FIND_WND_CLASS -Windows.Win32.Foundation.ERROR_CANNOT_GRANT_REQUESTED_OPLOCK -Windows.Win32.Foundation.ERROR_CANNOT_IMPERSONATE -Windows.Win32.Foundation.ERROR_CANNOT_LOAD_REGISTRY_FILE -Windows.Win32.Foundation.ERROR_CANNOT_MAKE -Windows.Win32.Foundation.ERROR_CANNOT_OPEN_PROFILE -Windows.Win32.Foundation.ERROR_CANT_ACCESS_DOMAIN_INFO -Windows.Win32.Foundation.ERROR_CANT_ACCESS_FILE -Windows.Win32.Foundation.ERROR_CANT_CLEAR_ENCRYPTION_FLAG -Windows.Win32.Foundation.ERROR_CANT_DISABLE_MANDATORY -Windows.Win32.Foundation.ERROR_CANT_ENABLE_DENY_ONLY -Windows.Win32.Foundation.ERROR_CANT_OPEN_ANONYMOUS -Windows.Win32.Foundation.ERROR_CANT_RESOLVE_FILENAME -Windows.Win32.Foundation.ERROR_CANT_TERMINATE_SELF -Windows.Win32.Foundation.ERROR_CANT_WAIT -Windows.Win32.Foundation.ERROR_CANTFETCHBACKWARDS -Windows.Win32.Foundation.ERROR_CANTOPEN -Windows.Win32.Foundation.ERROR_CANTREAD -Windows.Win32.Foundation.ERROR_CANTSCROLLBACKWARDS -Windows.Win32.Foundation.ERROR_CANTWRITE -Windows.Win32.Foundation.ERROR_CAPAUTHZ_CHANGE_TYPE -Windows.Win32.Foundation.ERROR_CAPAUTHZ_DB_CORRUPTED -Windows.Win32.Foundation.ERROR_CAPAUTHZ_NO_POLICY -Windows.Win32.Foundation.ERROR_CAPAUTHZ_NOT_AUTHORIZED -Windows.Win32.Foundation.ERROR_CAPAUTHZ_NOT_DEVUNLOCKED -Windows.Win32.Foundation.ERROR_CAPAUTHZ_NOT_PROVISIONED -Windows.Win32.Foundation.ERROR_CAPAUTHZ_SCCD_DEV_MODE_REQUIRED -Windows.Win32.Foundation.ERROR_CAPAUTHZ_SCCD_INVALID_CATALOG -Windows.Win32.Foundation.ERROR_CAPAUTHZ_SCCD_NO_AUTH_ENTITY -Windows.Win32.Foundation.ERROR_CAPAUTHZ_SCCD_NO_CAPABILITY_MATCH -Windows.Win32.Foundation.ERROR_CAPAUTHZ_SCCD_PARSE_ERROR -Windows.Win32.Foundation.ERROR_CARDBUS_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_CASE_DIFFERING_NAMES_IN_DIR -Windows.Win32.Foundation.ERROR_CASE_SENSITIVE_PATH -Windows.Win32.Foundation.ERROR_CERTIFICATE_VALIDATION_PREFERENCE_CONFLICT -Windows.Win32.Foundation.ERROR_CHECKING_FILE_SYSTEM -Windows.Win32.Foundation.ERROR_CHECKOUT_REQUIRED -Windows.Win32.Foundation.ERROR_CHILD_MUST_BE_VOLATILE -Windows.Win32.Foundation.ERROR_CHILD_NOT_COMPLETE -Windows.Win32.Foundation.ERROR_CHILD_PROCESS_BLOCKED -Windows.Win32.Foundation.ERROR_CHILD_WINDOW_MENU -Windows.Win32.Foundation.ERROR_CIMFS_IMAGE_CORRUPT -Windows.Win32.Foundation.ERROR_CIMFS_IMAGE_VERSION_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_CIRCULAR_DEPENDENCY -Windows.Win32.Foundation.ERROR_CLASS_ALREADY_EXISTS -Windows.Win32.Foundation.ERROR_CLASS_DOES_NOT_EXIST -Windows.Win32.Foundation.ERROR_CLASS_HAS_WINDOWS -Windows.Win32.Foundation.ERROR_CLIENT_SERVER_PARAMETERS_INVALID -Windows.Win32.Foundation.ERROR_CLIPBOARD_NOT_OPEN -Windows.Win32.Foundation.ERROR_CLOUD_FILE_ACCESS_DENIED -Windows.Win32.Foundation.ERROR_CLOUD_FILE_ALREADY_CONNECTED -Windows.Win32.Foundation.ERROR_CLOUD_FILE_AUTHENTICATION_FAILED -Windows.Win32.Foundation.ERROR_CLOUD_FILE_CONNECTED_PROVIDER_ONLY -Windows.Win32.Foundation.ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED -Windows.Win32.Foundation.ERROR_CLOUD_FILE_IN_USE -Windows.Win32.Foundation.ERROR_CLOUD_FILE_INCOMPATIBLE_HARDLINKS -Windows.Win32.Foundation.ERROR_CLOUD_FILE_INSUFFICIENT_RESOURCES -Windows.Win32.Foundation.ERROR_CLOUD_FILE_INVALID_REQUEST -Windows.Win32.Foundation.ERROR_CLOUD_FILE_METADATA_CORRUPT -Windows.Win32.Foundation.ERROR_CLOUD_FILE_METADATA_TOO_LARGE -Windows.Win32.Foundation.ERROR_CLOUD_FILE_NETWORK_UNAVAILABLE -Windows.Win32.Foundation.ERROR_CLOUD_FILE_NOT_IN_SYNC -Windows.Win32.Foundation.ERROR_CLOUD_FILE_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_CLOUD_FILE_NOT_UNDER_SYNC_ROOT -Windows.Win32.Foundation.ERROR_CLOUD_FILE_PINNED -Windows.Win32.Foundation.ERROR_CLOUD_FILE_PROPERTY_BLOB_CHECKSUM_MISMATCH -Windows.Win32.Foundation.ERROR_CLOUD_FILE_PROPERTY_BLOB_TOO_LARGE -Windows.Win32.Foundation.ERROR_CLOUD_FILE_PROPERTY_CORRUPT -Windows.Win32.Foundation.ERROR_CLOUD_FILE_PROPERTY_LOCK_CONFLICT -Windows.Win32.Foundation.ERROR_CLOUD_FILE_PROPERTY_VERSION_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_CLOUD_FILE_PROVIDER_NOT_RUNNING -Windows.Win32.Foundation.ERROR_CLOUD_FILE_PROVIDER_TERMINATED -Windows.Win32.Foundation.ERROR_CLOUD_FILE_READ_ONLY_VOLUME -Windows.Win32.Foundation.ERROR_CLOUD_FILE_REQUEST_ABORTED -Windows.Win32.Foundation.ERROR_CLOUD_FILE_REQUEST_CANCELED -Windows.Win32.Foundation.ERROR_CLOUD_FILE_REQUEST_TIMEOUT -Windows.Win32.Foundation.ERROR_CLOUD_FILE_SYNC_ROOT_METADATA_CORRUPT -Windows.Win32.Foundation.ERROR_CLOUD_FILE_TOO_MANY_PROPERTY_BLOBS -Windows.Win32.Foundation.ERROR_CLOUD_FILE_UNSUCCESSFUL -Windows.Win32.Foundation.ERROR_CLOUD_FILE_US_MESSAGE_TIMEOUT -Windows.Win32.Foundation.ERROR_CLOUD_FILE_VALIDATION_FAILED -Windows.Win32.Foundation.ERROR_COMMITMENT_LIMIT -Windows.Win32.Foundation.ERROR_COMMITMENT_MINIMUM -Windows.Win32.Foundation.ERROR_COMPRESSED_FILE_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_COMPRESSION_DISABLED -Windows.Win32.Foundation.ERROR_COMPRESSION_NOT_BENEFICIAL -Windows.Win32.Foundation.ERROR_CONNECTED_OTHER_PASSWORD -Windows.Win32.Foundation.ERROR_CONNECTED_OTHER_PASSWORD_DEFAULT -Windows.Win32.Foundation.ERROR_CONNECTION_ABORTED -Windows.Win32.Foundation.ERROR_CONNECTION_ACTIVE -Windows.Win32.Foundation.ERROR_CONNECTION_COUNT_LIMIT -Windows.Win32.Foundation.ERROR_CONNECTION_INVALID -Windows.Win32.Foundation.ERROR_CONNECTION_REFUSED -Windows.Win32.Foundation.ERROR_CONNECTION_UNAVAIL -Windows.Win32.Foundation.ERROR_CONTAINER_ASSIGNED -Windows.Win32.Foundation.ERROR_CONTENT_BLOCKED -Windows.Win32.Foundation.ERROR_CONTEXT_EXPIRED -Windows.Win32.Foundation.ERROR_CONTINUE -Windows.Win32.Foundation.ERROR_CONTROL_C_EXIT -Windows.Win32.Foundation.ERROR_CONTROL_ID_NOT_FOUND -Windows.Win32.Foundation.ERROR_CONVERT_TO_LARGE -Windows.Win32.Foundation.ERROR_CORRUPT_LOG_CLEARED -Windows.Win32.Foundation.ERROR_CORRUPT_LOG_CORRUPTED -Windows.Win32.Foundation.ERROR_CORRUPT_LOG_DELETED_FULL -Windows.Win32.Foundation.ERROR_CORRUPT_LOG_OVERFULL -Windows.Win32.Foundation.ERROR_CORRUPT_LOG_UNAVAILABLE -Windows.Win32.Foundation.ERROR_CORRUPT_SYSTEM_FILE -Windows.Win32.Foundation.ERROR_COULD_NOT_INTERPRET -Windows.Win32.Foundation.ERROR_COUNTER_TIMEOUT -Windows.Win32.Foundation.ERROR_CPU_SET_INVALID -Windows.Win32.Foundation.ERROR_CRASH_DUMP -Windows.Win32.Foundation.ERROR_CRC -Windows.Win32.Foundation.ERROR_CREATE_FAILED -Windows.Win32.Foundation.ERROR_CROSS_PARTITION_VIOLATION -Windows.Win32.Foundation.ERROR_CS_ENCRYPTION_EXISTING_ENCRYPTED_FILE -Windows.Win32.Foundation.ERROR_CS_ENCRYPTION_FILE_NOT_CSE -Windows.Win32.Foundation.ERROR_CS_ENCRYPTION_INVALID_SERVER_RESPONSE -Windows.Win32.Foundation.ERROR_CS_ENCRYPTION_NEW_ENCRYPTED_FILE -Windows.Win32.Foundation.ERROR_CS_ENCRYPTION_UNSUPPORTED_SERVER -Windows.Win32.Foundation.ERROR_CSCSHARE_OFFLINE -Windows.Win32.Foundation.ERROR_CTX_CLIENT_QUERY_TIMEOUT -Windows.Win32.Foundation.ERROR_CTX_MODEM_RESPONSE_TIMEOUT -Windows.Win32.Foundation.ERROR_CURRENT_DIRECTORY -Windows.Win32.Foundation.ERROR_CURRENT_DOMAIN_NOT_ALLOWED -Windows.Win32.Foundation.ERROR_DATA_CHECKSUM_ERROR -Windows.Win32.Foundation.ERROR_DATA_NOT_ACCEPTED -Windows.Win32.Foundation.ERROR_DATABASE_DOES_NOT_EXIST -Windows.Win32.Foundation.ERROR_DATATYPE_MISMATCH -Windows.Win32.Foundation.ERROR_DAX_MAPPING_EXISTS -Windows.Win32.Foundation.ERROR_DBG_COMMAND_EXCEPTION -Windows.Win32.Foundation.ERROR_DBG_CONTINUE -Windows.Win32.Foundation.ERROR_DBG_CONTROL_BREAK -Windows.Win32.Foundation.ERROR_DBG_CONTROL_C -Windows.Win32.Foundation.ERROR_DBG_EXCEPTION_HANDLED -Windows.Win32.Foundation.ERROR_DBG_EXCEPTION_NOT_HANDLED -Windows.Win32.Foundation.ERROR_DBG_PRINTEXCEPTION_C -Windows.Win32.Foundation.ERROR_DBG_REPLY_LATER -Windows.Win32.Foundation.ERROR_DBG_RIPEXCEPTION -Windows.Win32.Foundation.ERROR_DBG_TERMINATE_PROCESS -Windows.Win32.Foundation.ERROR_DBG_TERMINATE_THREAD -Windows.Win32.Foundation.ERROR_DBG_UNABLE_TO_PROVIDE_HANDLE -Windows.Win32.Foundation.ERROR_DC_NOT_FOUND -Windows.Win32.Foundation.ERROR_DDE_FAIL -Windows.Win32.Foundation.ERROR_DEBUG_ATTACH_FAILED -Windows.Win32.Foundation.ERROR_DEBUGGER_INACTIVE -Windows.Win32.Foundation.ERROR_DECRYPTION_FAILED -Windows.Win32.Foundation.ERROR_DELAY_LOAD_FAILED -Windows.Win32.Foundation.ERROR_DELETE_PENDING -Windows.Win32.Foundation.ERROR_DEPENDENT_SERVICES_RUNNING -Windows.Win32.Foundation.ERROR_DESTINATION_ELEMENT_FULL -Windows.Win32.Foundation.ERROR_DESTROY_OBJECT_OF_OTHER_THREAD -Windows.Win32.Foundation.ERROR_DEV_NOT_EXIST -Windows.Win32.Foundation.ERROR_DEVICE_ALREADY_ATTACHED -Windows.Win32.Foundation.ERROR_DEVICE_ALREADY_REMEMBERED -Windows.Win32.Foundation.ERROR_DEVICE_DOOR_OPEN -Windows.Win32.Foundation.ERROR_DEVICE_ENUMERATION_ERROR -Windows.Win32.Foundation.ERROR_DEVICE_FEATURE_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_DEVICE_HARDWARE_ERROR -Windows.Win32.Foundation.ERROR_DEVICE_HINT_NAME_BUFFER_TOO_SMALL -Windows.Win32.Foundation.ERROR_DEVICE_IN_MAINTENANCE -Windows.Win32.Foundation.ERROR_DEVICE_IN_USE -Windows.Win32.Foundation.ERROR_DEVICE_NO_RESOURCES -Windows.Win32.Foundation.ERROR_DEVICE_NOT_CONNECTED -Windows.Win32.Foundation.ERROR_DEVICE_NOT_PARTITIONED -Windows.Win32.Foundation.ERROR_DEVICE_REINITIALIZATION_NEEDED -Windows.Win32.Foundation.ERROR_DEVICE_REMOVED -Windows.Win32.Foundation.ERROR_DEVICE_REQUIRES_CLEANING -Windows.Win32.Foundation.ERROR_DEVICE_RESET_REQUIRED -Windows.Win32.Foundation.ERROR_DEVICE_SUPPORT_IN_PROGRESS -Windows.Win32.Foundation.ERROR_DEVICE_UNREACHABLE -Windows.Win32.Foundation.ERROR_DHCP_ADDRESS_CONFLICT -Windows.Win32.Foundation.ERROR_DIFFERENT_SERVICE_ACCOUNT -Windows.Win32.Foundation.ERROR_DIR_EFS_DISALLOWED -Windows.Win32.Foundation.ERROR_DIR_NOT_EMPTY -Windows.Win32.Foundation.ERROR_DIR_NOT_ROOT -Windows.Win32.Foundation.ERROR_DIRECT_ACCESS_HANDLE -Windows.Win32.Foundation.ERROR_DIRECTORY -Windows.Win32.Foundation.ERROR_DIRECTORY_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_DISCARDED -Windows.Win32.Foundation.ERROR_DISK_CHANGE -Windows.Win32.Foundation.ERROR_DISK_CORRUPT -Windows.Win32.Foundation.ERROR_DISK_FULL -Windows.Win32.Foundation.ERROR_DISK_OPERATION_FAILED -Windows.Win32.Foundation.ERROR_DISK_QUOTA_EXCEEDED -Windows.Win32.Foundation.ERROR_DISK_RECALIBRATE_FAILED -Windows.Win32.Foundation.ERROR_DISK_REPAIR_DISABLED -Windows.Win32.Foundation.ERROR_DISK_REPAIR_REDIRECTED -Windows.Win32.Foundation.ERROR_DISK_REPAIR_UNSUCCESSFUL -Windows.Win32.Foundation.ERROR_DISK_RESET_FAILED -Windows.Win32.Foundation.ERROR_DISK_RESOURCES_EXHAUSTED -Windows.Win32.Foundation.ERROR_DISK_TOO_FRAGMENTED -Windows.Win32.Foundation.ERROR_DLL_INIT_FAILED -Windows.Win32.Foundation.ERROR_DLL_INIT_FAILED_LOGOFF -Windows.Win32.Foundation.ERROR_DLL_MIGHT_BE_INCOMPATIBLE -Windows.Win32.Foundation.ERROR_DLL_MIGHT_BE_INSECURE -Windows.Win32.Foundation.ERROR_DLL_NOT_FOUND -Windows.Win32.Foundation.ERROR_DLP_POLICY_DENIES_OPERATION -Windows.Win32.Foundation.ERROR_DLP_POLICY_SILENTLY_FAIL -Windows.Win32.Foundation.ERROR_DLP_POLICY_WARNS_AGAINST_OPERATION -Windows.Win32.Foundation.ERROR_DOMAIN_CONTROLLER_EXISTS -Windows.Win32.Foundation.ERROR_DOMAIN_CONTROLLER_NOT_FOUND -Windows.Win32.Foundation.ERROR_DOMAIN_CTRLR_CONFIG_ERROR -Windows.Win32.Foundation.ERROR_DOMAIN_EXISTS -Windows.Win32.Foundation.ERROR_DOMAIN_LIMIT_EXCEEDED -Windows.Win32.Foundation.ERROR_DOMAIN_SID_SAME_AS_LOCAL_WORKSTATION -Windows.Win32.Foundation.ERROR_DOMAIN_TRUST_INCONSISTENT -Windows.Win32.Foundation.ERROR_DOWNGRADE_DETECTED -Windows.Win32.Foundation.ERROR_DPL_NOT_SUPPORTED_FOR_USER -Windows.Win32.Foundation.ERROR_DRIVE_LOCKED -Windows.Win32.Foundation.ERROR_DRIVER_BLOCKED -Windows.Win32.Foundation.ERROR_DRIVER_CANCEL_TIMEOUT -Windows.Win32.Foundation.ERROR_DRIVER_DATABASE_ERROR -Windows.Win32.Foundation.ERROR_DRIVER_FAILED_PRIOR_UNLOAD -Windows.Win32.Foundation.ERROR_DRIVER_FAILED_SLEEP -Windows.Win32.Foundation.ERROR_DRIVER_PROCESS_TERMINATED -Windows.Win32.Foundation.ERROR_DRIVERS_LEAKING_LOCKED_PAGES -Windows.Win32.Foundation.ERROR_DS_ADD_REPLICA_INHIBITED -Windows.Win32.Foundation.ERROR_DS_ADMIN_LIMIT_EXCEEDED -Windows.Win32.Foundation.ERROR_DS_AFFECTS_MULTIPLE_DSAS -Windows.Win32.Foundation.ERROR_DS_AG_CANT_HAVE_UNIVERSAL_MEMBER -Windows.Win32.Foundation.ERROR_DS_ALIAS_DEREF_PROBLEM -Windows.Win32.Foundation.ERROR_DS_ALIAS_POINTS_TO_ALIAS -Windows.Win32.Foundation.ERROR_DS_ALIAS_PROBLEM -Windows.Win32.Foundation.ERROR_DS_ALIASED_OBJ_MISSING -Windows.Win32.Foundation.ERROR_DS_ATT_ALREADY_EXISTS -Windows.Win32.Foundation.ERROR_DS_ATT_IS_NOT_ON_OBJ -Windows.Win32.Foundation.ERROR_DS_ATT_NOT_DEF_FOR_CLASS -Windows.Win32.Foundation.ERROR_DS_ATT_NOT_DEF_IN_SCHEMA -Windows.Win32.Foundation.ERROR_DS_ATT_SCHEMA_REQ_ID -Windows.Win32.Foundation.ERROR_DS_ATT_SCHEMA_REQ_SYNTAX -Windows.Win32.Foundation.ERROR_DS_ATT_VAL_ALREADY_EXISTS -Windows.Win32.Foundation.ERROR_DS_ATTRIBUTE_OR_VALUE_EXISTS -Windows.Win32.Foundation.ERROR_DS_ATTRIBUTE_OWNED_BY_SAM -Windows.Win32.Foundation.ERROR_DS_ATTRIBUTE_TYPE_UNDEFINED -Windows.Win32.Foundation.ERROR_DS_AUDIT_FAILURE -Windows.Win32.Foundation.ERROR_DS_AUTH_METHOD_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_DS_AUTH_UNKNOWN -Windows.Win32.Foundation.ERROR_DS_AUTHORIZATION_FAILED -Windows.Win32.Foundation.ERROR_DS_AUX_CLS_TEST_FAIL -Windows.Win32.Foundation.ERROR_DS_BACKLINK_WITHOUT_LINK -Windows.Win32.Foundation.ERROR_DS_BAD_ATT_SCHEMA_SYNTAX -Windows.Win32.Foundation.ERROR_DS_BAD_HIERARCHY_FILE -Windows.Win32.Foundation.ERROR_DS_BAD_INSTANCE_TYPE -Windows.Win32.Foundation.ERROR_DS_BAD_NAME_SYNTAX -Windows.Win32.Foundation.ERROR_DS_BAD_RDN_ATT_ID_SYNTAX -Windows.Win32.Foundation.ERROR_DS_BUILD_HIERARCHY_TABLE_FAILED -Windows.Win32.Foundation.ERROR_DS_BUSY -Windows.Win32.Foundation.ERROR_DS_CANT_ACCESS_REMOTE_PART_OF_AD -Windows.Win32.Foundation.ERROR_DS_CANT_ADD_ATT_VALUES -Windows.Win32.Foundation.ERROR_DS_CANT_ADD_SYSTEM_ONLY -Windows.Win32.Foundation.ERROR_DS_CANT_ADD_TO_GC -Windows.Win32.Foundation.ERROR_DS_CANT_CACHE_ATT -Windows.Win32.Foundation.ERROR_DS_CANT_CACHE_CLASS -Windows.Win32.Foundation.ERROR_DS_CANT_CREATE_IN_NONDOMAIN_NC -Windows.Win32.Foundation.ERROR_DS_CANT_CREATE_UNDER_SCHEMA -Windows.Win32.Foundation.ERROR_DS_CANT_DEL_MASTER_CROSSREF -Windows.Win32.Foundation.ERROR_DS_CANT_DELETE -Windows.Win32.Foundation.ERROR_DS_CANT_DELETE_DSA_OBJ -Windows.Win32.Foundation.ERROR_DS_CANT_DEMOTE_WITH_WRITEABLE_NC -Windows.Win32.Foundation.ERROR_DS_CANT_DEREF_ALIAS -Windows.Win32.Foundation.ERROR_DS_CANT_DERIVE_SPN_FOR_DELETED_DOMAIN -Windows.Win32.Foundation.ERROR_DS_CANT_DERIVE_SPN_WITHOUT_SERVER_REF -Windows.Win32.Foundation.ERROR_DS_CANT_FIND_DC_FOR_SRC_DOMAIN -Windows.Win32.Foundation.ERROR_DS_CANT_FIND_DSA_OBJ -Windows.Win32.Foundation.ERROR_DS_CANT_FIND_EXPECTED_NC -Windows.Win32.Foundation.ERROR_DS_CANT_FIND_NC_IN_CACHE -Windows.Win32.Foundation.ERROR_DS_CANT_MIX_MASTER_AND_REPS -Windows.Win32.Foundation.ERROR_DS_CANT_MOD_OBJ_CLASS -Windows.Win32.Foundation.ERROR_DS_CANT_MOD_PRIMARYGROUPID -Windows.Win32.Foundation.ERROR_DS_CANT_MOD_SYSTEM_ONLY -Windows.Win32.Foundation.ERROR_DS_CANT_MOVE_ACCOUNT_GROUP -Windows.Win32.Foundation.ERROR_DS_CANT_MOVE_APP_BASIC_GROUP -Windows.Win32.Foundation.ERROR_DS_CANT_MOVE_APP_QUERY_GROUP -Windows.Win32.Foundation.ERROR_DS_CANT_MOVE_DELETED_OBJECT -Windows.Win32.Foundation.ERROR_DS_CANT_MOVE_RESOURCE_GROUP -Windows.Win32.Foundation.ERROR_DS_CANT_ON_NON_LEAF -Windows.Win32.Foundation.ERROR_DS_CANT_ON_RDN -Windows.Win32.Foundation.ERROR_DS_CANT_REM_MISSING_ATT -Windows.Win32.Foundation.ERROR_DS_CANT_REM_MISSING_ATT_VAL -Windows.Win32.Foundation.ERROR_DS_CANT_REMOVE_ATT_CACHE -Windows.Win32.Foundation.ERROR_DS_CANT_REMOVE_CLASS_CACHE -Windows.Win32.Foundation.ERROR_DS_CANT_REPLACE_HIDDEN_REC -Windows.Win32.Foundation.ERROR_DS_CANT_RETRIEVE_ATTS -Windows.Win32.Foundation.ERROR_DS_CANT_RETRIEVE_CHILD -Windows.Win32.Foundation.ERROR_DS_CANT_RETRIEVE_DN -Windows.Win32.Foundation.ERROR_DS_CANT_RETRIEVE_INSTANCE -Windows.Win32.Foundation.ERROR_DS_CANT_RETRIEVE_SD -Windows.Win32.Foundation.ERROR_DS_CANT_START -Windows.Win32.Foundation.ERROR_DS_CANT_TREE_DELETE_CRITICAL_OBJ -Windows.Win32.Foundation.ERROR_DS_CANT_WITH_ACCT_GROUP_MEMBERSHPS -Windows.Win32.Foundation.ERROR_DS_CHILDREN_EXIST -Windows.Win32.Foundation.ERROR_DS_CLASS_MUST_BE_CONCRETE -Windows.Win32.Foundation.ERROR_DS_CLASS_NOT_DSA -Windows.Win32.Foundation.ERROR_DS_CLIENT_LOOP -Windows.Win32.Foundation.ERROR_DS_CODE_INCONSISTENCY -Windows.Win32.Foundation.ERROR_DS_COMPARE_FALSE -Windows.Win32.Foundation.ERROR_DS_COMPARE_TRUE -Windows.Win32.Foundation.ERROR_DS_CONFIDENTIALITY_REQUIRED -Windows.Win32.Foundation.ERROR_DS_CONFIG_PARAM_MISSING -Windows.Win32.Foundation.ERROR_DS_CONSTRAINT_VIOLATION -Windows.Win32.Foundation.ERROR_DS_CONSTRUCTED_ATT_MOD -Windows.Win32.Foundation.ERROR_DS_CONTROL_NOT_FOUND -Windows.Win32.Foundation.ERROR_DS_COULDNT_CONTACT_FSMO -Windows.Win32.Foundation.ERROR_DS_COULDNT_IDENTIFY_OBJECTS_FOR_TREE_DELETE -Windows.Win32.Foundation.ERROR_DS_COULDNT_LOCK_TREE_FOR_DELETE -Windows.Win32.Foundation.ERROR_DS_COULDNT_UPDATE_SPNS -Windows.Win32.Foundation.ERROR_DS_COUNTING_AB_INDICES_FAILED -Windows.Win32.Foundation.ERROR_DS_CR_IMPOSSIBLE_TO_VALIDATE -Windows.Win32.Foundation.ERROR_DS_CR_IMPOSSIBLE_TO_VALIDATE_V2 -Windows.Win32.Foundation.ERROR_DS_CROSS_DOM_MOVE_ERROR -Windows.Win32.Foundation.ERROR_DS_CROSS_DOMAIN_CLEANUP_REQD -Windows.Win32.Foundation.ERROR_DS_CROSS_NC_DN_RENAME -Windows.Win32.Foundation.ERROR_DS_CROSS_REF_BUSY -Windows.Win32.Foundation.ERROR_DS_CROSS_REF_EXISTS -Windows.Win32.Foundation.ERROR_DS_DATABASE_ERROR -Windows.Win32.Foundation.ERROR_DS_DECODING_ERROR -Windows.Win32.Foundation.ERROR_DS_DESTINATION_AUDITING_NOT_ENABLED -Windows.Win32.Foundation.ERROR_DS_DESTINATION_DOMAIN_NOT_IN_FOREST -Windows.Win32.Foundation.ERROR_DS_DIFFERENT_REPL_EPOCHS -Windows.Win32.Foundation.ERROR_DS_DISALLOWED_IN_SYSTEM_CONTAINER -Windows.Win32.Foundation.ERROR_DS_DISALLOWED_NC_REDIRECT -Windows.Win32.Foundation.ERROR_DS_DNS_LOOKUP_FAILURE -Windows.Win32.Foundation.ERROR_DS_DOMAIN_NAME_EXISTS_IN_FOREST -Windows.Win32.Foundation.ERROR_DS_DOMAIN_RENAME_IN_PROGRESS -Windows.Win32.Foundation.ERROR_DS_DOMAIN_VERSION_TOO_HIGH -Windows.Win32.Foundation.ERROR_DS_DOMAIN_VERSION_TOO_LOW -Windows.Win32.Foundation.ERROR_DS_DRA_ABANDON_SYNC -Windows.Win32.Foundation.ERROR_DS_DRA_ACCESS_DENIED -Windows.Win32.Foundation.ERROR_DS_DRA_BAD_DN -Windows.Win32.Foundation.ERROR_DS_DRA_BAD_INSTANCE_TYPE -Windows.Win32.Foundation.ERROR_DS_DRA_BAD_NC -Windows.Win32.Foundation.ERROR_DS_DRA_BUSY -Windows.Win32.Foundation.ERROR_DS_DRA_CONNECTION_FAILED -Windows.Win32.Foundation.ERROR_DS_DRA_CORRUPT_UTD_VECTOR -Windows.Win32.Foundation.ERROR_DS_DRA_DB_ERROR -Windows.Win32.Foundation.ERROR_DS_DRA_DN_EXISTS -Windows.Win32.Foundation.ERROR_DS_DRA_EARLIER_SCHEMA_CONFLICT -Windows.Win32.Foundation.ERROR_DS_DRA_EXTN_CONNECTION_FAILED -Windows.Win32.Foundation.ERROR_DS_DRA_GENERIC -Windows.Win32.Foundation.ERROR_DS_DRA_INCOMPATIBLE_PARTIAL_SET -Windows.Win32.Foundation.ERROR_DS_DRA_INCONSISTENT_DIT -Windows.Win32.Foundation.ERROR_DS_DRA_INTERNAL_ERROR -Windows.Win32.Foundation.ERROR_DS_DRA_INVALID_PARAMETER -Windows.Win32.Foundation.ERROR_DS_DRA_MAIL_PROBLEM -Windows.Win32.Foundation.ERROR_DS_DRA_MISSING_KRBTGT_SECRET -Windows.Win32.Foundation.ERROR_DS_DRA_MISSING_PARENT -Windows.Win32.Foundation.ERROR_DS_DRA_NAME_COLLISION -Windows.Win32.Foundation.ERROR_DS_DRA_NO_REPLICA -Windows.Win32.Foundation.ERROR_DS_DRA_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_DS_DRA_OBJ_IS_REP_SOURCE -Windows.Win32.Foundation.ERROR_DS_DRA_OBJ_NC_MISMATCH -Windows.Win32.Foundation.ERROR_DS_DRA_OUT_OF_MEM -Windows.Win32.Foundation.ERROR_DS_DRA_OUT_SCHEDULE_WINDOW -Windows.Win32.Foundation.ERROR_DS_DRA_PREEMPTED -Windows.Win32.Foundation.ERROR_DS_DRA_RECYCLED_TARGET -Windows.Win32.Foundation.ERROR_DS_DRA_REF_ALREADY_EXISTS -Windows.Win32.Foundation.ERROR_DS_DRA_REF_NOT_FOUND -Windows.Win32.Foundation.ERROR_DS_DRA_REPL_PENDING -Windows.Win32.Foundation.ERROR_DS_DRA_RPC_CANCELLED -Windows.Win32.Foundation.ERROR_DS_DRA_SCHEMA_CONFLICT -Windows.Win32.Foundation.ERROR_DS_DRA_SCHEMA_INFO_SHIP -Windows.Win32.Foundation.ERROR_DS_DRA_SCHEMA_MISMATCH -Windows.Win32.Foundation.ERROR_DS_DRA_SECRETS_DENIED -Windows.Win32.Foundation.ERROR_DS_DRA_SHUTDOWN -Windows.Win32.Foundation.ERROR_DS_DRA_SINK_DISABLED -Windows.Win32.Foundation.ERROR_DS_DRA_SOURCE_DISABLED -Windows.Win32.Foundation.ERROR_DS_DRA_SOURCE_IS_PARTIAL_REPLICA -Windows.Win32.Foundation.ERROR_DS_DRA_SOURCE_REINSTALLED -Windows.Win32.Foundation.ERROR_DS_DRS_EXTENSIONS_CHANGED -Windows.Win32.Foundation.ERROR_DS_DS_REQUIRED -Windows.Win32.Foundation.ERROR_DS_DSA_MUST_BE_INT_MASTER -Windows.Win32.Foundation.ERROR_DS_DST_DOMAIN_NOT_NATIVE -Windows.Win32.Foundation.ERROR_DS_DST_NC_MISMATCH -Windows.Win32.Foundation.ERROR_DS_DUP_LDAP_DISPLAY_NAME -Windows.Win32.Foundation.ERROR_DS_DUP_LINK_ID -Windows.Win32.Foundation.ERROR_DS_DUP_MAPI_ID -Windows.Win32.Foundation.ERROR_DS_DUP_MSDS_INTID -Windows.Win32.Foundation.ERROR_DS_DUP_OID -Windows.Win32.Foundation.ERROR_DS_DUP_RDN -Windows.Win32.Foundation.ERROR_DS_DUP_SCHEMA_ID_GUID -Windows.Win32.Foundation.ERROR_DS_DUPLICATE_ID_FOUND -Windows.Win32.Foundation.ERROR_DS_ENCODING_ERROR -Windows.Win32.Foundation.ERROR_DS_EPOCH_MISMATCH -Windows.Win32.Foundation.ERROR_DS_EXISTING_AD_CHILD_NC -Windows.Win32.Foundation.ERROR_DS_EXISTS_IN_AUX_CLS -Windows.Win32.Foundation.ERROR_DS_EXISTS_IN_MAY_HAVE -Windows.Win32.Foundation.ERROR_DS_EXISTS_IN_MUST_HAVE -Windows.Win32.Foundation.ERROR_DS_EXISTS_IN_POSS_SUP -Windows.Win32.Foundation.ERROR_DS_EXISTS_IN_RDNATTID -Windows.Win32.Foundation.ERROR_DS_EXISTS_IN_SUB_CLS -Windows.Win32.Foundation.ERROR_DS_FILTER_UNKNOWN -Windows.Win32.Foundation.ERROR_DS_FILTER_USES_CONTRUCTED_ATTRS -Windows.Win32.Foundation.ERROR_DS_FLAT_NAME_EXISTS_IN_FOREST -Windows.Win32.Foundation.ERROR_DS_FOREST_VERSION_TOO_HIGH -Windows.Win32.Foundation.ERROR_DS_FOREST_VERSION_TOO_LOW -Windows.Win32.Foundation.ERROR_DS_GC_NOT_AVAILABLE -Windows.Win32.Foundation.ERROR_DS_GC_REQUIRED -Windows.Win32.Foundation.ERROR_DS_GCVERIFY_ERROR -Windows.Win32.Foundation.ERROR_DS_GENERIC_ERROR -Windows.Win32.Foundation.ERROR_DS_GLOBAL_CANT_HAVE_CROSSDOMAIN_MEMBER -Windows.Win32.Foundation.ERROR_DS_GLOBAL_CANT_HAVE_LOCAL_MEMBER -Windows.Win32.Foundation.ERROR_DS_GLOBAL_CANT_HAVE_UNIVERSAL_MEMBER -Windows.Win32.Foundation.ERROR_DS_GOVERNSID_MISSING -Windows.Win32.Foundation.ERROR_DS_GROUP_CONVERSION_ERROR -Windows.Win32.Foundation.ERROR_DS_HAVE_PRIMARY_MEMBERS -Windows.Win32.Foundation.ERROR_DS_HIERARCHY_TABLE_MALLOC_FAILED -Windows.Win32.Foundation.ERROR_DS_HIERARCHY_TABLE_TOO_DEEP -Windows.Win32.Foundation.ERROR_DS_HIGH_ADLDS_FFL -Windows.Win32.Foundation.ERROR_DS_HIGH_DSA_VERSION -Windows.Win32.Foundation.ERROR_DS_ILLEGAL_BASE_SCHEMA_MOD -Windows.Win32.Foundation.ERROR_DS_ILLEGAL_MOD_OPERATION -Windows.Win32.Foundation.ERROR_DS_ILLEGAL_SUPERIOR -Windows.Win32.Foundation.ERROR_DS_ILLEGAL_XDOM_MOVE_OPERATION -Windows.Win32.Foundation.ERROR_DS_INAPPROPRIATE_AUTH -Windows.Win32.Foundation.ERROR_DS_INAPPROPRIATE_MATCHING -Windows.Win32.Foundation.ERROR_DS_INCOMPATIBLE_CONTROLS_USED -Windows.Win32.Foundation.ERROR_DS_INCOMPATIBLE_VERSION -Windows.Win32.Foundation.ERROR_DS_INCORRECT_ROLE_OWNER -Windows.Win32.Foundation.ERROR_DS_INIT_FAILURE -Windows.Win32.Foundation.ERROR_DS_INIT_FAILURE_CONSOLE -Windows.Win32.Foundation.ERROR_DS_INSTALL_NO_SCH_VERSION_IN_INIFILE -Windows.Win32.Foundation.ERROR_DS_INSTALL_NO_SRC_SCH_VERSION -Windows.Win32.Foundation.ERROR_DS_INSTALL_SCHEMA_MISMATCH -Windows.Win32.Foundation.ERROR_DS_INSUFF_ACCESS_RIGHTS -Windows.Win32.Foundation.ERROR_DS_INSUFFICIENT_ATTR_TO_CREATE_OBJECT -Windows.Win32.Foundation.ERROR_DS_INTERNAL_FAILURE -Windows.Win32.Foundation.ERROR_DS_INVALID_ATTRIBUTE_SYNTAX -Windows.Win32.Foundation.ERROR_DS_INVALID_DMD -Windows.Win32.Foundation.ERROR_DS_INVALID_DN_SYNTAX -Windows.Win32.Foundation.ERROR_DS_INVALID_GROUP_TYPE -Windows.Win32.Foundation.ERROR_DS_INVALID_LDAP_DISPLAY_NAME -Windows.Win32.Foundation.ERROR_DS_INVALID_NAME_FOR_SPN -Windows.Win32.Foundation.ERROR_DS_INVALID_ROLE_OWNER -Windows.Win32.Foundation.ERROR_DS_INVALID_SCRIPT -Windows.Win32.Foundation.ERROR_DS_INVALID_SEARCH_FLAG -Windows.Win32.Foundation.ERROR_DS_INVALID_SEARCH_FLAG_SUBTREE -Windows.Win32.Foundation.ERROR_DS_INVALID_SEARCH_FLAG_TUPLE -Windows.Win32.Foundation.ERROR_DS_IS_LEAF -Windows.Win32.Foundation.ERROR_DS_KEY_NOT_UNIQUE -Windows.Win32.Foundation.ERROR_DS_LDAP_SEND_QUEUE_FULL -Windows.Win32.Foundation.ERROR_DS_LINK_ID_NOT_AVAILABLE -Windows.Win32.Foundation.ERROR_DS_LOCAL_CANT_HAVE_CROSSDOMAIN_LOCAL_MEMBER -Windows.Win32.Foundation.ERROR_DS_LOCAL_ERROR -Windows.Win32.Foundation.ERROR_DS_LOCAL_MEMBER_OF_LOCAL_ONLY -Windows.Win32.Foundation.ERROR_DS_LOOP_DETECT -Windows.Win32.Foundation.ERROR_DS_LOW_ADLDS_FFL -Windows.Win32.Foundation.ERROR_DS_LOW_DSA_VERSION -Windows.Win32.Foundation.ERROR_DS_MACHINE_ACCOUNT_CREATED_PRENT4 -Windows.Win32.Foundation.ERROR_DS_MACHINE_ACCOUNT_QUOTA_EXCEEDED -Windows.Win32.Foundation.ERROR_DS_MAPI_ID_NOT_AVAILABLE -Windows.Win32.Foundation.ERROR_DS_MASTERDSA_REQUIRED -Windows.Win32.Foundation.ERROR_DS_MAX_OBJ_SIZE_EXCEEDED -Windows.Win32.Foundation.ERROR_DS_MEMBERSHIP_EVALUATED_LOCALLY -Windows.Win32.Foundation.ERROR_DS_MISSING_EXPECTED_ATT -Windows.Win32.Foundation.ERROR_DS_MISSING_FOREST_TRUST -Windows.Win32.Foundation.ERROR_DS_MISSING_FSMO_SETTINGS -Windows.Win32.Foundation.ERROR_DS_MISSING_INFRASTRUCTURE_CONTAINER -Windows.Win32.Foundation.ERROR_DS_MISSING_REQUIRED_ATT -Windows.Win32.Foundation.ERROR_DS_MISSING_SUPREF -Windows.Win32.Foundation.ERROR_DS_MODIFYDN_DISALLOWED_BY_FLAG -Windows.Win32.Foundation.ERROR_DS_MODIFYDN_DISALLOWED_BY_INSTANCE_TYPE -Windows.Win32.Foundation.ERROR_DS_MODIFYDN_WRONG_GRANDPARENT -Windows.Win32.Foundation.ERROR_DS_MUST_BE_RUN_ON_DST_DC -Windows.Win32.Foundation.ERROR_DS_NAME_ERROR_DOMAIN_ONLY -Windows.Win32.Foundation.ERROR_DS_NAME_ERROR_NO_MAPPING -Windows.Win32.Foundation.ERROR_DS_NAME_ERROR_NO_SYNTACTICAL_MAPPING -Windows.Win32.Foundation.ERROR_DS_NAME_ERROR_NOT_FOUND -Windows.Win32.Foundation.ERROR_DS_NAME_ERROR_NOT_UNIQUE -Windows.Win32.Foundation.ERROR_DS_NAME_ERROR_RESOLVING -Windows.Win32.Foundation.ERROR_DS_NAME_ERROR_TRUST_REFERRAL -Windows.Win32.Foundation.ERROR_DS_NAME_NOT_UNIQUE -Windows.Win32.Foundation.ERROR_DS_NAME_REFERENCE_INVALID -Windows.Win32.Foundation.ERROR_DS_NAME_TOO_LONG -Windows.Win32.Foundation.ERROR_DS_NAME_TOO_MANY_PARTS -Windows.Win32.Foundation.ERROR_DS_NAME_TYPE_UNKNOWN -Windows.Win32.Foundation.ERROR_DS_NAME_UNPARSEABLE -Windows.Win32.Foundation.ERROR_DS_NAME_VALUE_TOO_LONG -Windows.Win32.Foundation.ERROR_DS_NAMING_MASTER_GC -Windows.Win32.Foundation.ERROR_DS_NAMING_VIOLATION -Windows.Win32.Foundation.ERROR_DS_NC_MUST_HAVE_NC_PARENT -Windows.Win32.Foundation.ERROR_DS_NC_STILL_HAS_DSAS -Windows.Win32.Foundation.ERROR_DS_NCNAME_MISSING_CR_REF -Windows.Win32.Foundation.ERROR_DS_NCNAME_MUST_BE_NC -Windows.Win32.Foundation.ERROR_DS_NO_ATTRIBUTE_OR_VALUE -Windows.Win32.Foundation.ERROR_DS_NO_BEHAVIOR_VERSION_IN_MIXEDDOMAIN -Windows.Win32.Foundation.ERROR_DS_NO_CHAINED_EVAL -Windows.Win32.Foundation.ERROR_DS_NO_CHAINING -Windows.Win32.Foundation.ERROR_DS_NO_CHECKPOINT_WITH_PDC -Windows.Win32.Foundation.ERROR_DS_NO_CROSSREF_FOR_NC -Windows.Win32.Foundation.ERROR_DS_NO_DELETED_NAME -Windows.Win32.Foundation.ERROR_DS_NO_FPO_IN_UNIVERSAL_GROUPS -Windows.Win32.Foundation.ERROR_DS_NO_MORE_RIDS -Windows.Win32.Foundation.ERROR_DS_NO_MSDS_INTID -Windows.Win32.Foundation.ERROR_DS_NO_NEST_GLOBALGROUP_IN_MIXEDDOMAIN -Windows.Win32.Foundation.ERROR_DS_NO_NEST_LOCALGROUP_IN_MIXEDDOMAIN -Windows.Win32.Foundation.ERROR_DS_NO_NTDSA_OBJECT -Windows.Win32.Foundation.ERROR_DS_NO_OBJECT_MOVE_IN_SCHEMA_NC -Windows.Win32.Foundation.ERROR_DS_NO_PARENT_OBJECT -Windows.Win32.Foundation.ERROR_DS_NO_PKT_PRIVACY_ON_CONNECTION -Windows.Win32.Foundation.ERROR_DS_NO_RDN_DEFINED_IN_SCHEMA -Windows.Win32.Foundation.ERROR_DS_NO_REF_DOMAIN -Windows.Win32.Foundation.ERROR_DS_NO_REQUESTED_ATTS_FOUND -Windows.Win32.Foundation.ERROR_DS_NO_RESULTS_RETURNED -Windows.Win32.Foundation.ERROR_DS_NO_RIDS_ALLOCATED -Windows.Win32.Foundation.ERROR_DS_NO_SERVER_OBJECT -Windows.Win32.Foundation.ERROR_DS_NO_SUCH_OBJECT -Windows.Win32.Foundation.ERROR_DS_NO_TREE_DELETE_ABOVE_NC -Windows.Win32.Foundation.ERROR_DS_NON_ASQ_SEARCH -Windows.Win32.Foundation.ERROR_DS_NON_BASE_SEARCH -Windows.Win32.Foundation.ERROR_DS_NONEXISTENT_MAY_HAVE -Windows.Win32.Foundation.ERROR_DS_NONEXISTENT_MUST_HAVE -Windows.Win32.Foundation.ERROR_DS_NONEXISTENT_POSS_SUP -Windows.Win32.Foundation.ERROR_DS_NONSAFE_SCHEMA_CHANGE -Windows.Win32.Foundation.ERROR_DS_NOT_AN_OBJECT -Windows.Win32.Foundation.ERROR_DS_NOT_AUTHORITIVE_FOR_DST_NC -Windows.Win32.Foundation.ERROR_DS_NOT_CLOSEST -Windows.Win32.Foundation.ERROR_DS_NOT_INSTALLED -Windows.Win32.Foundation.ERROR_DS_NOT_ON_BACKLINK -Windows.Win32.Foundation.ERROR_DS_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_DS_NOT_SUPPORTED_SORT_ORDER -Windows.Win32.Foundation.ERROR_DS_NOTIFY_FILTER_TOO_COMPLEX -Windows.Win32.Foundation.ERROR_DS_NTDSCRIPT_PROCESS_ERROR -Windows.Win32.Foundation.ERROR_DS_NTDSCRIPT_SYNTAX_ERROR -Windows.Win32.Foundation.ERROR_DS_OBJ_CLASS_NOT_DEFINED -Windows.Win32.Foundation.ERROR_DS_OBJ_CLASS_NOT_SUBCLASS -Windows.Win32.Foundation.ERROR_DS_OBJ_CLASS_VIOLATION -Windows.Win32.Foundation.ERROR_DS_OBJ_GUID_EXISTS -Windows.Win32.Foundation.ERROR_DS_OBJ_NOT_FOUND -Windows.Win32.Foundation.ERROR_DS_OBJ_STRING_NAME_EXISTS -Windows.Win32.Foundation.ERROR_DS_OBJ_TOO_LARGE -Windows.Win32.Foundation.ERROR_DS_OBJECT_BEING_REMOVED -Windows.Win32.Foundation.ERROR_DS_OBJECT_CLASS_REQUIRED -Windows.Win32.Foundation.ERROR_DS_OBJECT_RESULTS_TOO_LARGE -Windows.Win32.Foundation.ERROR_DS_OFFSET_RANGE_ERROR -Windows.Win32.Foundation.ERROR_DS_OID_MAPPED_GROUP_CANT_HAVE_MEMBERS -Windows.Win32.Foundation.ERROR_DS_OID_NOT_FOUND -Windows.Win32.Foundation.ERROR_DS_OPERATIONS_ERROR -Windows.Win32.Foundation.ERROR_DS_OUT_OF_SCOPE -Windows.Win32.Foundation.ERROR_DS_OUT_OF_VERSION_STORE -Windows.Win32.Foundation.ERROR_DS_PARAM_ERROR -Windows.Win32.Foundation.ERROR_DS_PARENT_IS_AN_ALIAS -Windows.Win32.Foundation.ERROR_DS_PDC_OPERATION_IN_PROGRESS -Windows.Win32.Foundation.ERROR_DS_PER_ATTRIBUTE_AUTHZ_FAILED_DURING_ADD -Windows.Win32.Foundation.ERROR_DS_POLICY_NOT_KNOWN -Windows.Win32.Foundation.ERROR_DS_PROTOCOL_ERROR -Windows.Win32.Foundation.ERROR_DS_RANGE_CONSTRAINT -Windows.Win32.Foundation.ERROR_DS_RDN_DOESNT_MATCH_SCHEMA -Windows.Win32.Foundation.ERROR_DS_RECALCSCHEMA_FAILED -Windows.Win32.Foundation.ERROR_DS_REFERRAL -Windows.Win32.Foundation.ERROR_DS_REFERRAL_LIMIT_EXCEEDED -Windows.Win32.Foundation.ERROR_DS_REFUSING_FSMO_ROLES -Windows.Win32.Foundation.ERROR_DS_REMOTE_CROSSREF_OP_FAILED -Windows.Win32.Foundation.ERROR_DS_REPL_LIFETIME_EXCEEDED -Windows.Win32.Foundation.ERROR_DS_REPLICA_SET_CHANGE_NOT_ALLOWED_ON_DISABLED_CR -Windows.Win32.Foundation.ERROR_DS_REPLICATOR_ONLY -Windows.Win32.Foundation.ERROR_DS_RESERVED_LINK_ID -Windows.Win32.Foundation.ERROR_DS_RESERVED_MAPI_ID -Windows.Win32.Foundation.ERROR_DS_RIDMGR_DISABLED -Windows.Win32.Foundation.ERROR_DS_RIDMGR_INIT_ERROR -Windows.Win32.Foundation.ERROR_DS_ROLE_NOT_VERIFIED -Windows.Win32.Foundation.ERROR_DS_ROOT_CANT_BE_SUBREF -Windows.Win32.Foundation.ERROR_DS_ROOT_MUST_BE_NC -Windows.Win32.Foundation.ERROR_DS_ROOT_REQUIRES_CLASS_TOP -Windows.Win32.Foundation.ERROR_DS_SAM_INIT_FAILURE -Windows.Win32.Foundation.ERROR_DS_SAM_INIT_FAILURE_CONSOLE -Windows.Win32.Foundation.ERROR_DS_SAM_NEED_BOOTKEY_FLOPPY -Windows.Win32.Foundation.ERROR_DS_SAM_NEED_BOOTKEY_PASSWORD -Windows.Win32.Foundation.ERROR_DS_SCHEMA_ALLOC_FAILED -Windows.Win32.Foundation.ERROR_DS_SCHEMA_NOT_LOADED -Windows.Win32.Foundation.ERROR_DS_SCHEMA_UPDATE_DISALLOWED -Windows.Win32.Foundation.ERROR_DS_SEC_DESC_INVALID -Windows.Win32.Foundation.ERROR_DS_SEC_DESC_TOO_SHORT -Windows.Win32.Foundation.ERROR_DS_SECURITY_CHECKING_ERROR -Windows.Win32.Foundation.ERROR_DS_SECURITY_ILLEGAL_MODIFY -Windows.Win32.Foundation.ERROR_DS_SEMANTIC_ATT_TEST -Windows.Win32.Foundation.ERROR_DS_SENSITIVE_GROUP_VIOLATION -Windows.Win32.Foundation.ERROR_DS_SERVER_DOWN -Windows.Win32.Foundation.ERROR_DS_SHUTTING_DOWN -Windows.Win32.Foundation.ERROR_DS_SINGLE_USER_MODE_FAILED -Windows.Win32.Foundation.ERROR_DS_SINGLE_VALUE_CONSTRAINT -Windows.Win32.Foundation.ERROR_DS_SIZELIMIT_EXCEEDED -Windows.Win32.Foundation.ERROR_DS_SORT_CONTROL_MISSING -Windows.Win32.Foundation.ERROR_DS_SOURCE_AUDITING_NOT_ENABLED -Windows.Win32.Foundation.ERROR_DS_SOURCE_DOMAIN_IN_FOREST -Windows.Win32.Foundation.ERROR_DS_SPN_VALUE_NOT_UNIQUE_IN_FOREST -Windows.Win32.Foundation.ERROR_DS_SRC_AND_DST_NC_IDENTICAL -Windows.Win32.Foundation.ERROR_DS_SRC_AND_DST_OBJECT_CLASS_MISMATCH -Windows.Win32.Foundation.ERROR_DS_SRC_DC_MUST_BE_SP4_OR_GREATER -Windows.Win32.Foundation.ERROR_DS_SRC_GUID_MISMATCH -Windows.Win32.Foundation.ERROR_DS_SRC_NAME_MISMATCH -Windows.Win32.Foundation.ERROR_DS_SRC_OBJ_NOT_GROUP_OR_USER -Windows.Win32.Foundation.ERROR_DS_SRC_SID_EXISTS_IN_FOREST -Windows.Win32.Foundation.ERROR_DS_STRING_SD_CONVERSION_FAILED -Windows.Win32.Foundation.ERROR_DS_STRONG_AUTH_REQUIRED -Windows.Win32.Foundation.ERROR_DS_SUB_CLS_TEST_FAIL -Windows.Win32.Foundation.ERROR_DS_SUBREF_MUST_HAVE_PARENT -Windows.Win32.Foundation.ERROR_DS_SUBTREE_NOTIFY_NOT_NC_HEAD -Windows.Win32.Foundation.ERROR_DS_SYNTAX_MISMATCH -Windows.Win32.Foundation.ERROR_DS_THREAD_LIMIT_EXCEEDED -Windows.Win32.Foundation.ERROR_DS_TIMELIMIT_EXCEEDED -Windows.Win32.Foundation.ERROR_DS_TREE_DELETE_NOT_FINISHED -Windows.Win32.Foundation.ERROR_DS_UNABLE_TO_SURRENDER_ROLES -Windows.Win32.Foundation.ERROR_DS_UNAVAILABLE -Windows.Win32.Foundation.ERROR_DS_UNAVAILABLE_CRIT_EXTENSION -Windows.Win32.Foundation.ERROR_DS_UNDELETE_SAM_VALIDATION_FAILED -Windows.Win32.Foundation.ERROR_DS_UNICODEPWD_NOT_IN_QUOTES -Windows.Win32.Foundation.ERROR_DS_UNIVERSAL_CANT_HAVE_LOCAL_MEMBER -Windows.Win32.Foundation.ERROR_DS_UNKNOWN_ERROR -Windows.Win32.Foundation.ERROR_DS_UNKNOWN_OPERATION -Windows.Win32.Foundation.ERROR_DS_UNWILLING_TO_PERFORM -Windows.Win32.Foundation.ERROR_DS_UPN_VALUE_NOT_UNIQUE_IN_FOREST -Windows.Win32.Foundation.ERROR_DS_USER_BUFFER_TO_SMALL -Windows.Win32.Foundation.ERROR_DS_VALUE_KEY_NOT_UNIQUE -Windows.Win32.Foundation.ERROR_DS_VERSION_CHECK_FAILURE -Windows.Win32.Foundation.ERROR_DS_WKO_CONTAINER_CANNOT_BE_SPECIAL -Windows.Win32.Foundation.ERROR_DS_WRONG_LINKED_ATT_SYNTAX -Windows.Win32.Foundation.ERROR_DS_WRONG_OM_OBJ_CLASS -Windows.Win32.Foundation.ERROR_DUP_DOMAINNAME -Windows.Win32.Foundation.ERROR_DUP_NAME -Windows.Win32.Foundation.ERROR_DUPLICATE_PRIVILEGES -Windows.Win32.Foundation.ERROR_DUPLICATE_SERVICE_NAME -Windows.Win32.Foundation.ERROR_DYNAMIC_CODE_BLOCKED -Windows.Win32.Foundation.ERROR_DYNLINK_FROM_INVALID_RING -Windows.Win32.Foundation.ERROR_EA_ACCESS_DENIED -Windows.Win32.Foundation.ERROR_EA_FILE_CORRUPT -Windows.Win32.Foundation.ERROR_EA_LIST_INCONSISTENT -Windows.Win32.Foundation.ERROR_EA_TABLE_FULL -Windows.Win32.Foundation.ERROR_EAS_DIDNT_FIT -Windows.Win32.Foundation.ERROR_EAS_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_EDP_DPL_POLICY_CANT_BE_SATISFIED -Windows.Win32.Foundation.ERROR_EDP_POLICY_DENIES_OPERATION -Windows.Win32.Foundation.ERROR_EFS_ALG_BLOB_TOO_BIG -Windows.Win32.Foundation.ERROR_EFS_DISABLED -Windows.Win32.Foundation.ERROR_EFS_SERVER_NOT_TRUSTED -Windows.Win32.Foundation.ERROR_EFS_VERSION_NOT_SUPPORT -Windows.Win32.Foundation.ERROR_ELEVATION_REQUIRED -Windows.Win32.Foundation.ERROR_ENCLAVE_FAILURE -Windows.Win32.Foundation.ERROR_ENCLAVE_NOT_TERMINATED -Windows.Win32.Foundation.ERROR_ENCLAVE_VIOLATION -Windows.Win32.Foundation.ERROR_ENCRYPTED_FILE_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_ENCRYPTED_IO_NOT_POSSIBLE -Windows.Win32.Foundation.ERROR_ENCRYPTING_METADATA_DISALLOWED -Windows.Win32.Foundation.ERROR_ENCRYPTION_DISABLED -Windows.Win32.Foundation.ERROR_ENCRYPTION_FAILED -Windows.Win32.Foundation.ERROR_ENCRYPTION_POLICY_DENIES_OPERATION -Windows.Win32.Foundation.ERROR_END_OF_MEDIA -Windows.Win32.Foundation.ERROR_ENVVAR_NOT_FOUND -Windows.Win32.Foundation.ERROR_EOM_OVERFLOW -Windows.Win32.Foundation.ERROR_ERRORS_ENCOUNTERED -Windows.Win32.Foundation.ERROR_EVALUATION_EXPIRATION -Windows.Win32.Foundation.ERROR_EVENT_DONE -Windows.Win32.Foundation.ERROR_EVENT_PENDING -Windows.Win32.Foundation.ERROR_EVENTLOG_CANT_START -Windows.Win32.Foundation.ERROR_EVENTLOG_FILE_CHANGED -Windows.Win32.Foundation.ERROR_EVENTLOG_FILE_CORRUPT -Windows.Win32.Foundation.ERROR_EXCEPTION_IN_SERVICE -Windows.Win32.Foundation.ERROR_EXCL_SEM_ALREADY_OWNED -Windows.Win32.Foundation.ERROR_EXE_CANNOT_MODIFY_SIGNED_BINARY -Windows.Win32.Foundation.ERROR_EXE_CANNOT_MODIFY_STRONG_SIGNED_BINARY -Windows.Win32.Foundation.ERROR_EXE_MACHINE_TYPE_MISMATCH -Windows.Win32.Foundation.ERROR_EXE_MARKED_INVALID -Windows.Win32.Foundation.ERROR_EXTENDED_ERROR -Windows.Win32.Foundation.ERROR_EXTERNAL_BACKING_PROVIDER_UNKNOWN -Windows.Win32.Foundation.ERROR_EXTERNAL_SYSKEY_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_EXTRANEOUS_INFORMATION -Windows.Win32.Foundation.ERROR_FAIL_FAST_EXCEPTION -Windows.Win32.Foundation.ERROR_FAIL_I24 -Windows.Win32.Foundation.ERROR_FAIL_NOACTION_REBOOT -Windows.Win32.Foundation.ERROR_FAIL_RESTART -Windows.Win32.Foundation.ERROR_FAIL_SHUTDOWN -Windows.Win32.Foundation.ERROR_FAILED_DRIVER_ENTRY -Windows.Win32.Foundation.ERROR_FAILED_SERVICE_CONTROLLER_CONNECT -Windows.Win32.Foundation.ERROR_FATAL_APP_EXIT -Windows.Win32.Foundation.ERROR_FILE_CHECKED_OUT -Windows.Win32.Foundation.ERROR_FILE_CORRUPT -Windows.Win32.Foundation.ERROR_FILE_ENCRYPTED -Windows.Win32.Foundation.ERROR_FILE_EXISTS -Windows.Win32.Foundation.ERROR_FILE_HANDLE_REVOKED -Windows.Win32.Foundation.ERROR_FILE_INVALID -Windows.Win32.Foundation.ERROR_FILE_LEVEL_TRIM_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_FILE_METADATA_OPTIMIZATION_IN_PROGRESS -Windows.Win32.Foundation.ERROR_FILE_NOT_ENCRYPTED -Windows.Win32.Foundation.ERROR_FILE_NOT_FOUND -Windows.Win32.Foundation.ERROR_FILE_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_FILE_OFFLINE -Windows.Win32.Foundation.ERROR_FILE_PROTECTED_UNDER_DPL -Windows.Win32.Foundation.ERROR_FILE_READ_ONLY -Windows.Win32.Foundation.ERROR_FILE_SNAP_IN_PROGRESS -Windows.Win32.Foundation.ERROR_FILE_SNAP_INVALID_PARAMETER -Windows.Win32.Foundation.ERROR_FILE_SNAP_IO_NOT_COORDINATED -Windows.Win32.Foundation.ERROR_FILE_SNAP_MODIFY_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_FILE_SNAP_UNEXPECTED_ERROR -Windows.Win32.Foundation.ERROR_FILE_SNAP_USER_SECTION_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_FILE_SYSTEM_LIMITATION -Windows.Win32.Foundation.ERROR_FILE_SYSTEM_VIRTUALIZATION_BUSY -Windows.Win32.Foundation.ERROR_FILE_SYSTEM_VIRTUALIZATION_INVALID_OPERATION -Windows.Win32.Foundation.ERROR_FILE_SYSTEM_VIRTUALIZATION_METADATA_CORRUPT -Windows.Win32.Foundation.ERROR_FILE_SYSTEM_VIRTUALIZATION_PROVIDER_UNKNOWN -Windows.Win32.Foundation.ERROR_FILE_SYSTEM_VIRTUALIZATION_UNAVAILABLE -Windows.Win32.Foundation.ERROR_FILE_TOO_LARGE -Windows.Win32.Foundation.ERROR_FILEMARK_DETECTED -Windows.Win32.Foundation.ERROR_FILENAME_EXCED_RANGE -Windows.Win32.Foundation.ERROR_FIRMWARE_UPDATED -Windows.Win32.Foundation.ERROR_FLOAT_MULTIPLE_FAULTS -Windows.Win32.Foundation.ERROR_FLOAT_MULTIPLE_TRAPS -Windows.Win32.Foundation.ERROR_FLOPPY_BAD_REGISTERS -Windows.Win32.Foundation.ERROR_FLOPPY_ID_MARK_NOT_FOUND -Windows.Win32.Foundation.ERROR_FLOPPY_UNKNOWN_ERROR -Windows.Win32.Foundation.ERROR_FLOPPY_VOLUME -Windows.Win32.Foundation.ERROR_FLOPPY_WRONG_CYLINDER -Windows.Win32.Foundation.ERROR_FORMS_AUTH_REQUIRED -Windows.Win32.Foundation.ERROR_FOUND_OUT_OF_SCOPE -Windows.Win32.Foundation.ERROR_FS_DRIVER_REQUIRED -Windows.Win32.Foundation.ERROR_FS_METADATA_INCONSISTENT -Windows.Win32.Foundation.ERROR_FSFILTER_OP_COMPLETED_SUCCESSFULLY -Windows.Win32.Foundation.ERROR_FT_DI_SCAN_REQUIRED -Windows.Win32.Foundation.ERROR_FT_READ_FAILURE -Windows.Win32.Foundation.ERROR_FT_READ_FROM_COPY_FAILURE -Windows.Win32.Foundation.ERROR_FT_READ_RECOVERY_FROM_BACKUP -Windows.Win32.Foundation.ERROR_FT_WRITE_FAILURE -Windows.Win32.Foundation.ERROR_FT_WRITE_RECOVERY -Windows.Win32.Foundation.ERROR_FULLSCREEN_MODE -Windows.Win32.Foundation.ERROR_FUNCTION_FAILED -Windows.Win32.Foundation.ERROR_FUNCTION_NOT_CALLED -Windows.Win32.Foundation.ERROR_GDI_HANDLE_LEAK -Windows.Win32.Foundation.ERROR_GEN_FAILURE -Windows.Win32.Foundation.ERROR_GENERIC_NOT_MAPPED -Windows.Win32.Foundation.ERROR_GLOBAL_ONLY_HOOK -Windows.Win32.Foundation.ERROR_GRACEFUL_DISCONNECT -Windows.Win32.Foundation.ERROR_GROUP_EXISTS -Windows.Win32.Foundation.ERROR_GUID_SUBSTITUTION_MADE -Windows.Win32.Foundation.ERROR_HANDLE_DISK_FULL -Windows.Win32.Foundation.ERROR_HANDLE_EOF -Windows.Win32.Foundation.ERROR_HANDLE_REVOKED -Windows.Win32.Foundation.ERROR_HANDLES_CLOSED -Windows.Win32.Foundation.ERROR_HAS_SYSTEM_CRITICAL_FILES -Windows.Win32.Foundation.ERROR_HIBERNATED -Windows.Win32.Foundation.ERROR_HIBERNATION_FAILURE -Windows.Win32.Foundation.ERROR_HOOK_NEEDS_HMOD -Windows.Win32.Foundation.ERROR_HOOK_NOT_INSTALLED -Windows.Win32.Foundation.ERROR_HOOK_TYPE_NOT_ALLOWED -Windows.Win32.Foundation.ERROR_HOST_DOWN -Windows.Win32.Foundation.ERROR_HOST_UNREACHABLE -Windows.Win32.Foundation.ERROR_HOTKEY_ALREADY_REGISTERED -Windows.Win32.Foundation.ERROR_HOTKEY_NOT_REGISTERED -Windows.Win32.Foundation.ERROR_HWNDS_HAVE_DIFF_PARENT -Windows.Win32.Foundation.ERROR_ILL_FORMED_PASSWORD -Windows.Win32.Foundation.ERROR_ILLEGAL_CHARACTER -Windows.Win32.Foundation.ERROR_ILLEGAL_DLL_RELOCATION -Windows.Win32.Foundation.ERROR_ILLEGAL_ELEMENT_ADDRESS -Windows.Win32.Foundation.ERROR_ILLEGAL_FLOAT_CONTEXT -Windows.Win32.Foundation.ERROR_IMAGE_AT_DIFFERENT_BASE -Windows.Win32.Foundation.ERROR_IMAGE_MACHINE_TYPE_MISMATCH -Windows.Win32.Foundation.ERROR_IMAGE_MACHINE_TYPE_MISMATCH_EXE -Windows.Win32.Foundation.ERROR_IMAGE_NOT_AT_BASE -Windows.Win32.Foundation.ERROR_IMAGE_SUBSYSTEM_NOT_PRESENT -Windows.Win32.Foundation.ERROR_IMPLEMENTATION_LIMIT -Windows.Win32.Foundation.ERROR_INCOMPATIBLE_SERVICE_PRIVILEGE -Windows.Win32.Foundation.ERROR_INCOMPATIBLE_SERVICE_SID_TYPE -Windows.Win32.Foundation.ERROR_INCOMPATIBLE_WITH_GLOBAL_SHORT_NAME_REGISTRY_SETTING -Windows.Win32.Foundation.ERROR_INCORRECT_ACCOUNT_TYPE -Windows.Win32.Foundation.ERROR_INCORRECT_ADDRESS -Windows.Win32.Foundation.ERROR_INCORRECT_SIZE -Windows.Win32.Foundation.ERROR_INDEX_ABSENT -Windows.Win32.Foundation.ERROR_INDEX_OUT_OF_BOUNDS -Windows.Win32.Foundation.ERROR_INFLOOP_IN_RELOC_CHAIN -Windows.Win32.Foundation.ERROR_INSTALL_ALREADY_RUNNING -Windows.Win32.Foundation.ERROR_INSTALL_FAILURE -Windows.Win32.Foundation.ERROR_INSTALL_LANGUAGE_UNSUPPORTED -Windows.Win32.Foundation.ERROR_INSTALL_LOG_FAILURE -Windows.Win32.Foundation.ERROR_INSTALL_NOTUSED -Windows.Win32.Foundation.ERROR_INSTALL_PACKAGE_INVALID -Windows.Win32.Foundation.ERROR_INSTALL_PACKAGE_OPEN_FAILED -Windows.Win32.Foundation.ERROR_INSTALL_PACKAGE_REJECTED -Windows.Win32.Foundation.ERROR_INSTALL_PACKAGE_VERSION -Windows.Win32.Foundation.ERROR_INSTALL_PLATFORM_UNSUPPORTED -Windows.Win32.Foundation.ERROR_INSTALL_REJECTED -Windows.Win32.Foundation.ERROR_INSTALL_REMOTE_DISALLOWED -Windows.Win32.Foundation.ERROR_INSTALL_REMOTE_PROHIBITED -Windows.Win32.Foundation.ERROR_INSTALL_SERVICE_FAILURE -Windows.Win32.Foundation.ERROR_INSTALL_SERVICE_SAFEBOOT -Windows.Win32.Foundation.ERROR_INSTALL_SOURCE_ABSENT -Windows.Win32.Foundation.ERROR_INSTALL_SUSPEND -Windows.Win32.Foundation.ERROR_INSTALL_TEMP_UNWRITABLE -Windows.Win32.Foundation.ERROR_INSTALL_TRANSFORM_FAILURE -Windows.Win32.Foundation.ERROR_INSTALL_TRANSFORM_REJECTED -Windows.Win32.Foundation.ERROR_INSTALL_UI_FAILURE -Windows.Win32.Foundation.ERROR_INSTALL_USEREXIT -Windows.Win32.Foundation.ERROR_INSTRUCTION_MISALIGNMENT -Windows.Win32.Foundation.ERROR_INSUFFICIENT_BUFFER -Windows.Win32.Foundation.ERROR_INSUFFICIENT_LOGON_INFO -Windows.Win32.Foundation.ERROR_INSUFFICIENT_POWER -Windows.Win32.Foundation.ERROR_INSUFFICIENT_RESOURCE_FOR_SPECIFIED_SHARED_SECTION_SIZE -Windows.Win32.Foundation.ERROR_INSUFFICIENT_VIRTUAL_ADDR_RESOURCES -Windows.Win32.Foundation.ERROR_INTERMIXED_KERNEL_EA_OPERATION -Windows.Win32.Foundation.ERROR_INTERNAL_DB_CORRUPTION -Windows.Win32.Foundation.ERROR_INTERNAL_DB_ERROR -Windows.Win32.Foundation.ERROR_INTERNAL_ERROR -Windows.Win32.Foundation.ERROR_INTERRUPT_STILL_CONNECTED -Windows.Win32.Foundation.ERROR_INTERRUPT_VECTOR_ALREADY_CONNECTED -Windows.Win32.Foundation.ERROR_INVALID_ACCEL_HANDLE -Windows.Win32.Foundation.ERROR_INVALID_ACCESS -Windows.Win32.Foundation.ERROR_INVALID_ACCOUNT_NAME -Windows.Win32.Foundation.ERROR_INVALID_ACE_CONDITION -Windows.Win32.Foundation.ERROR_INVALID_ACL -Windows.Win32.Foundation.ERROR_INVALID_ADDRESS -Windows.Win32.Foundation.ERROR_INVALID_AT_INTERRUPT_TIME -Windows.Win32.Foundation.ERROR_INVALID_BLOCK -Windows.Win32.Foundation.ERROR_INVALID_BLOCK_LENGTH -Windows.Win32.Foundation.ERROR_INVALID_CAP -Windows.Win32.Foundation.ERROR_INVALID_CATEGORY -Windows.Win32.Foundation.ERROR_INVALID_COMBOBOX_MESSAGE -Windows.Win32.Foundation.ERROR_INVALID_COMMAND_LINE -Windows.Win32.Foundation.ERROR_INVALID_COMPUTERNAME -Windows.Win32.Foundation.ERROR_INVALID_CRUNTIME_PARAMETER -Windows.Win32.Foundation.ERROR_INVALID_CURSOR_HANDLE -Windows.Win32.Foundation.ERROR_INVALID_DATA -Windows.Win32.Foundation.ERROR_INVALID_DATATYPE -Windows.Win32.Foundation.ERROR_INVALID_DEVICE_OBJECT_PARAMETER -Windows.Win32.Foundation.ERROR_INVALID_DLL -Windows.Win32.Foundation.ERROR_INVALID_DOMAIN_ROLE -Windows.Win32.Foundation.ERROR_INVALID_DOMAIN_STATE -Windows.Win32.Foundation.ERROR_INVALID_DOMAINNAME -Windows.Win32.Foundation.ERROR_INVALID_DRIVE -Windows.Win32.Foundation.ERROR_INVALID_DWP_HANDLE -Windows.Win32.Foundation.ERROR_INVALID_EA_HANDLE -Windows.Win32.Foundation.ERROR_INVALID_EA_NAME -Windows.Win32.Foundation.ERROR_INVALID_EDIT_HEIGHT -Windows.Win32.Foundation.ERROR_INVALID_ENVIRONMENT -Windows.Win32.Foundation.ERROR_INVALID_EVENT_COUNT -Windows.Win32.Foundation.ERROR_INVALID_EVENTNAME -Windows.Win32.Foundation.ERROR_INVALID_EXCEPTION_HANDLER -Windows.Win32.Foundation.ERROR_INVALID_EXE_SIGNATURE -Windows.Win32.Foundation.ERROR_INVALID_FIELD -Windows.Win32.Foundation.ERROR_INVALID_FIELD_IN_PARAMETER_LIST -Windows.Win32.Foundation.ERROR_INVALID_FILTER_PROC -Windows.Win32.Foundation.ERROR_INVALID_FLAG_NUMBER -Windows.Win32.Foundation.ERROR_INVALID_FLAGS -Windows.Win32.Foundation.ERROR_INVALID_FORM_NAME -Windows.Win32.Foundation.ERROR_INVALID_FORM_SIZE -Windows.Win32.Foundation.ERROR_INVALID_FUNCTION -Windows.Win32.Foundation.ERROR_INVALID_GROUP_ATTRIBUTES -Windows.Win32.Foundation.ERROR_INVALID_GROUPNAME -Windows.Win32.Foundation.ERROR_INVALID_GW_COMMAND -Windows.Win32.Foundation.ERROR_INVALID_HANDLE -Windows.Win32.Foundation.ERROR_INVALID_HANDLE_STATE -Windows.Win32.Foundation.ERROR_INVALID_HOOK_FILTER -Windows.Win32.Foundation.ERROR_INVALID_HOOK_HANDLE -Windows.Win32.Foundation.ERROR_INVALID_HW_PROFILE -Windows.Win32.Foundation.ERROR_INVALID_ICON_HANDLE -Windows.Win32.Foundation.ERROR_INVALID_ID_AUTHORITY -Windows.Win32.Foundation.ERROR_INVALID_IMAGE_HASH -Windows.Win32.Foundation.ERROR_INVALID_IMPORT_OF_NON_DLL -Windows.Win32.Foundation.ERROR_INVALID_INDEX -Windows.Win32.Foundation.ERROR_INVALID_KERNEL_INFO_VERSION -Windows.Win32.Foundation.ERROR_INVALID_KEYBOARD_HANDLE -Windows.Win32.Foundation.ERROR_INVALID_LABEL -Windows.Win32.Foundation.ERROR_INVALID_LB_MESSAGE -Windows.Win32.Foundation.ERROR_INVALID_LDT_DESCRIPTOR -Windows.Win32.Foundation.ERROR_INVALID_LDT_OFFSET -Windows.Win32.Foundation.ERROR_INVALID_LDT_SIZE -Windows.Win32.Foundation.ERROR_INVALID_LEVEL -Windows.Win32.Foundation.ERROR_INVALID_LIST_FORMAT -Windows.Win32.Foundation.ERROR_INVALID_LOCK_RANGE -Windows.Win32.Foundation.ERROR_INVALID_LOGON_HOURS -Windows.Win32.Foundation.ERROR_INVALID_LOGON_TYPE -Windows.Win32.Foundation.ERROR_INVALID_MEMBER -Windows.Win32.Foundation.ERROR_INVALID_MENU_HANDLE -Windows.Win32.Foundation.ERROR_INVALID_MESSAGE -Windows.Win32.Foundation.ERROR_INVALID_MESSAGEDEST -Windows.Win32.Foundation.ERROR_INVALID_MESSAGENAME -Windows.Win32.Foundation.ERROR_INVALID_MINALLOCSIZE -Windows.Win32.Foundation.ERROR_INVALID_MODULETYPE -Windows.Win32.Foundation.ERROR_INVALID_MONITOR_HANDLE -Windows.Win32.Foundation.ERROR_INVALID_MSGBOX_STYLE -Windows.Win32.Foundation.ERROR_INVALID_NAME -Windows.Win32.Foundation.ERROR_INVALID_NETNAME -Windows.Win32.Foundation.ERROR_INVALID_OPLOCK_PROTOCOL -Windows.Win32.Foundation.ERROR_INVALID_ORDINAL -Windows.Win32.Foundation.ERROR_INVALID_OWNER -Windows.Win32.Foundation.ERROR_INVALID_PACKAGE_SID_LENGTH -Windows.Win32.Foundation.ERROR_INVALID_PARAMETER -Windows.Win32.Foundation.ERROR_INVALID_PASSWORD -Windows.Win32.Foundation.ERROR_INVALID_PASSWORDNAME -Windows.Win32.Foundation.ERROR_INVALID_PATCH_XML -Windows.Win32.Foundation.ERROR_INVALID_PEP_INFO_VERSION -Windows.Win32.Foundation.ERROR_INVALID_PLUGPLAY_DEVICE_PATH -Windows.Win32.Foundation.ERROR_INVALID_PORT_ATTRIBUTES -Windows.Win32.Foundation.ERROR_INVALID_PRIMARY_GROUP -Windows.Win32.Foundation.ERROR_INVALID_PRINTER_COMMAND -Windows.Win32.Foundation.ERROR_INVALID_PRINTER_NAME -Windows.Win32.Foundation.ERROR_INVALID_PRINTER_STATE -Windows.Win32.Foundation.ERROR_INVALID_PRIORITY -Windows.Win32.Foundation.ERROR_INVALID_QUOTA_LOWER -Windows.Win32.Foundation.ERROR_INVALID_REPARSE_DATA -Windows.Win32.Foundation.ERROR_INVALID_SCROLLBAR_RANGE -Windows.Win32.Foundation.ERROR_INVALID_SECURITY_DESCR -Windows.Win32.Foundation.ERROR_INVALID_SEGDPL -Windows.Win32.Foundation.ERROR_INVALID_SEGMENT_NUMBER -Windows.Win32.Foundation.ERROR_INVALID_SEPARATOR_FILE -Windows.Win32.Foundation.ERROR_INVALID_SERVER_STATE -Windows.Win32.Foundation.ERROR_INVALID_SERVICE_ACCOUNT -Windows.Win32.Foundation.ERROR_INVALID_SERVICE_CONTROL -Windows.Win32.Foundation.ERROR_INVALID_SERVICE_LOCK -Windows.Win32.Foundation.ERROR_INVALID_SERVICENAME -Windows.Win32.Foundation.ERROR_INVALID_SHARENAME -Windows.Win32.Foundation.ERROR_INVALID_SHOWWIN_COMMAND -Windows.Win32.Foundation.ERROR_INVALID_SID -Windows.Win32.Foundation.ERROR_INVALID_SIGNAL_NUMBER -Windows.Win32.Foundation.ERROR_INVALID_SPI_VALUE -Windows.Win32.Foundation.ERROR_INVALID_STACKSEG -Windows.Win32.Foundation.ERROR_INVALID_STARTING_CODESEG -Windows.Win32.Foundation.ERROR_INVALID_SUB_AUTHORITY -Windows.Win32.Foundation.ERROR_INVALID_TABLE -Windows.Win32.Foundation.ERROR_INVALID_TARGET_HANDLE -Windows.Win32.Foundation.ERROR_INVALID_TASK_INDEX -Windows.Win32.Foundation.ERROR_INVALID_TASK_NAME -Windows.Win32.Foundation.ERROR_INVALID_THREAD_ID -Windows.Win32.Foundation.ERROR_INVALID_TIME -Windows.Win32.Foundation.ERROR_INVALID_TOKEN -Windows.Win32.Foundation.ERROR_INVALID_UNWIND_TARGET -Windows.Win32.Foundation.ERROR_INVALID_USER_BUFFER -Windows.Win32.Foundation.ERROR_INVALID_USER_PRINCIPAL_NAME -Windows.Win32.Foundation.ERROR_INVALID_VARIANT -Windows.Win32.Foundation.ERROR_INVALID_VERIFY_SWITCH -Windows.Win32.Foundation.ERROR_INVALID_WINDOW_HANDLE -Windows.Win32.Foundation.ERROR_INVALID_WORKSTATION -Windows.Win32.Foundation.ERROR_IO_DEVICE -Windows.Win32.Foundation.ERROR_IO_INCOMPLETE -Windows.Win32.Foundation.ERROR_IO_PENDING -Windows.Win32.Foundation.ERROR_IO_PRIVILEGE_FAILED -Windows.Win32.Foundation.ERROR_IO_REISSUE_AS_CACHED -Windows.Win32.Foundation.ERROR_IOPL_NOT_ENABLED -Windows.Win32.Foundation.ERROR_IP_ADDRESS_CONFLICT1 -Windows.Win32.Foundation.ERROR_IP_ADDRESS_CONFLICT2 -Windows.Win32.Foundation.ERROR_IPSEC_IKE_TIMED_OUT -Windows.Win32.Foundation.ERROR_IRQ_BUSY -Windows.Win32.Foundation.ERROR_IS_JOIN_PATH -Windows.Win32.Foundation.ERROR_IS_JOIN_TARGET -Windows.Win32.Foundation.ERROR_IS_JOINED -Windows.Win32.Foundation.ERROR_IS_SUBST_PATH -Windows.Win32.Foundation.ERROR_IS_SUBST_TARGET -Windows.Win32.Foundation.ERROR_IS_SUBSTED -Windows.Win32.Foundation.ERROR_ITERATED_DATA_EXCEEDS_64k -Windows.Win32.Foundation.ERROR_JOB_NO_CONTAINER -Windows.Win32.Foundation.ERROR_JOIN_TO_JOIN -Windows.Win32.Foundation.ERROR_JOIN_TO_SUBST -Windows.Win32.Foundation.ERROR_JOURNAL_DELETE_IN_PROGRESS -Windows.Win32.Foundation.ERROR_JOURNAL_ENTRY_DELETED -Windows.Win32.Foundation.ERROR_JOURNAL_HOOK_SET -Windows.Win32.Foundation.ERROR_JOURNAL_NOT_ACTIVE -Windows.Win32.Foundation.ERROR_KERNEL_APC -Windows.Win32.Foundation.ERROR_KEY_DELETED -Windows.Win32.Foundation.ERROR_KEY_HAS_CHILDREN -Windows.Win32.Foundation.ERROR_KM_DRIVER_BLOCKED -Windows.Win32.Foundation.ERROR_LABEL_TOO_LONG -Windows.Win32.Foundation.ERROR_LAST_ADMIN -Windows.Win32.Foundation.ERROR_LB_WITHOUT_TABSTOPS -Windows.Win32.Foundation.ERROR_LICENSE_QUOTA_EXCEEDED -Windows.Win32.Foundation.ERROR_LINUX_SUBSYSTEM_NOT_PRESENT -Windows.Win32.Foundation.ERROR_LINUX_SUBSYSTEM_UPDATE_REQUIRED -Windows.Win32.Foundation.ERROR_LISTBOX_ID_NOT_FOUND -Windows.Win32.Foundation.ERROR_LM_CROSS_ENCRYPTION_REQUIRED -Windows.Win32.Foundation.ERROR_LOCAL_POLICY_MODIFICATION_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_LOCAL_USER_SESSION_KEY -Windows.Win32.Foundation.ERROR_LOCK_FAILED -Windows.Win32.Foundation.ERROR_LOCK_VIOLATION -Windows.Win32.Foundation.ERROR_LOCKED -Windows.Win32.Foundation.ERROR_LOG_FILE_FULL -Windows.Win32.Foundation.ERROR_LOG_HARD_ERROR -Windows.Win32.Foundation.ERROR_LOGIN_TIME_RESTRICTION -Windows.Win32.Foundation.ERROR_LOGIN_WKSTA_RESTRICTION -Windows.Win32.Foundation.ERROR_LOGON_FAILURE -Windows.Win32.Foundation.ERROR_LOGON_NOT_GRANTED -Windows.Win32.Foundation.ERROR_LOGON_SERVER_CONFLICT -Windows.Win32.Foundation.ERROR_LOGON_SESSION_COLLISION -Windows.Win32.Foundation.ERROR_LOGON_SESSION_EXISTS -Windows.Win32.Foundation.ERROR_LOGON_TYPE_NOT_GRANTED -Windows.Win32.Foundation.ERROR_LONGJUMP -Windows.Win32.Foundation.ERROR_LOST_MODE_LOGON_RESTRICTION -Windows.Win32.Foundation.ERROR_LOST_WRITEBEHIND_DATA -Windows.Win32.Foundation.ERROR_LOST_WRITEBEHIND_DATA_LOCAL_DISK_ERROR -Windows.Win32.Foundation.ERROR_LOST_WRITEBEHIND_DATA_NETWORK_DISCONNECTED -Windows.Win32.Foundation.ERROR_LOST_WRITEBEHIND_DATA_NETWORK_SERVER_ERROR -Windows.Win32.Foundation.ERROR_LUIDS_EXHAUSTED -Windows.Win32.Foundation.ERROR_MACHINE_LOCKED -Windows.Win32.Foundation.ERROR_MAGAZINE_NOT_PRESENT -Windows.Win32.Foundation.ERROR_MAPPED_ALIGNMENT -Windows.Win32.Foundation.ERROR_MARKED_TO_DISALLOW_WRITES -Windows.Win32.Foundation.ERROR_MARSHALL_OVERFLOW -Windows.Win32.Foundation.ERROR_MAX_SESSIONS_REACHED -Windows.Win32.Foundation.ERROR_MAX_THRDS_REACHED -Windows.Win32.Foundation.ERROR_MCA_EXCEPTION -Windows.Win32.Foundation.ERROR_MCA_OCCURED -Windows.Win32.Foundation.ERROR_MEDIA_CHANGED -Windows.Win32.Foundation.ERROR_MEDIA_CHECK -Windows.Win32.Foundation.ERROR_MEMBER_IN_ALIAS -Windows.Win32.Foundation.ERROR_MEMBER_IN_GROUP -Windows.Win32.Foundation.ERROR_MEMBER_NOT_IN_ALIAS -Windows.Win32.Foundation.ERROR_MEMBER_NOT_IN_GROUP -Windows.Win32.Foundation.ERROR_MEMBERS_PRIMARY_GROUP -Windows.Win32.Foundation.ERROR_MEMORY_HARDWARE -Windows.Win32.Foundation.ERROR_MENU_ITEM_NOT_FOUND -Windows.Win32.Foundation.ERROR_MESSAGE_SYNC_ONLY -Windows.Win32.Foundation.ERROR_META_EXPANSION_TOO_LONG -Windows.Win32.Foundation.ERROR_MISSING_SYSTEMFILE -Windows.Win32.Foundation.ERROR_MOD_NOT_FOUND -Windows.Win32.Foundation.ERROR_MORE_DATA -Windows.Win32.Foundation.ERROR_MORE_WRITES -Windows.Win32.Foundation.ERROR_MOUNT_POINT_NOT_RESOLVED -Windows.Win32.Foundation.ERROR_MP_PROCESSOR_MISMATCH -Windows.Win32.Foundation.ERROR_MR_MID_NOT_FOUND -Windows.Win32.Foundation.ERROR_MULTIPLE_FAULT_VIOLATION -Windows.Win32.Foundation.ERROR_MUTANT_LIMIT_EXCEEDED -Windows.Win32.Foundation.ERROR_MUTUAL_AUTH_FAILED -Windows.Win32.Foundation.ERROR_NEGATIVE_SEEK -Windows.Win32.Foundation.ERROR_NESTING_NOT_ALLOWED -Windows.Win32.Foundation.ERROR_NET_OPEN_FAILED -Windows.Win32.Foundation.ERROR_NET_WRITE_FAULT -Windows.Win32.Foundation.ERROR_NETLOGON_NOT_STARTED -Windows.Win32.Foundation.ERROR_NETNAME_DELETED -Windows.Win32.Foundation.ERROR_NETWORK_ACCESS_DENIED -Windows.Win32.Foundation.ERROR_NETWORK_ACCESS_DENIED_EDP -Windows.Win32.Foundation.ERROR_NETWORK_BUSY -Windows.Win32.Foundation.ERROR_NETWORK_UNREACHABLE -Windows.Win32.Foundation.ERROR_NO_ACE_CONDITION -Windows.Win32.Foundation.ERROR_NO_ASSOCIATION -Windows.Win32.Foundation.ERROR_NO_BYPASSIO_DRIVER_SUPPORT -Windows.Win32.Foundation.ERROR_NO_CALLBACK_ACTIVE -Windows.Win32.Foundation.ERROR_NO_DATA -Windows.Win32.Foundation.ERROR_NO_DATA_DETECTED -Windows.Win32.Foundation.ERROR_NO_EFS -Windows.Win32.Foundation.ERROR_NO_EVENT_PAIR -Windows.Win32.Foundation.ERROR_NO_GUID_TRANSLATION -Windows.Win32.Foundation.ERROR_NO_IMPERSONATION_TOKEN -Windows.Win32.Foundation.ERROR_NO_INHERITANCE -Windows.Win32.Foundation.ERROR_NO_LOG_SPACE -Windows.Win32.Foundation.ERROR_NO_LOGON_SERVERS -Windows.Win32.Foundation.ERROR_NO_MATCH -Windows.Win32.Foundation.ERROR_NO_MEDIA_IN_DRIVE -Windows.Win32.Foundation.ERROR_NO_MORE_DEVICES -Windows.Win32.Foundation.ERROR_NO_MORE_FILES -Windows.Win32.Foundation.ERROR_NO_MORE_ITEMS -Windows.Win32.Foundation.ERROR_NO_MORE_MATCHES -Windows.Win32.Foundation.ERROR_NO_MORE_SEARCH_HANDLES -Windows.Win32.Foundation.ERROR_NO_MORE_USER_HANDLES -Windows.Win32.Foundation.ERROR_NO_NET_OR_BAD_PATH -Windows.Win32.Foundation.ERROR_NO_NETWORK -Windows.Win32.Foundation.ERROR_NO_NVRAM_RESOURCES -Windows.Win32.Foundation.ERROR_NO_PAGEFILE -Windows.Win32.Foundation.ERROR_NO_PHYSICALLY_ALIGNED_FREE_SPACE_FOUND -Windows.Win32.Foundation.ERROR_NO_PROC_SLOTS -Windows.Win32.Foundation.ERROR_NO_PROMOTION_ACTIVE -Windows.Win32.Foundation.ERROR_NO_QUOTAS_FOR_ACCOUNT -Windows.Win32.Foundation.ERROR_NO_RANGES_PROCESSED -Windows.Win32.Foundation.ERROR_NO_RECOVERY_POLICY -Windows.Win32.Foundation.ERROR_NO_RECOVERY_PROGRAM -Windows.Win32.Foundation.ERROR_NO_SCROLLBARS -Windows.Win32.Foundation.ERROR_NO_SECRETS -Windows.Win32.Foundation.ERROR_NO_SECURITY_ON_OBJECT -Windows.Win32.Foundation.ERROR_NO_SHUTDOWN_IN_PROGRESS -Windows.Win32.Foundation.ERROR_NO_SIGNAL_SENT -Windows.Win32.Foundation.ERROR_NO_SITE_SETTINGS_OBJECT -Windows.Win32.Foundation.ERROR_NO_SITENAME -Windows.Win32.Foundation.ERROR_NO_SPOOL_SPACE -Windows.Win32.Foundation.ERROR_NO_SUCH_ALIAS -Windows.Win32.Foundation.ERROR_NO_SUCH_DEVICE -Windows.Win32.Foundation.ERROR_NO_SUCH_DOMAIN -Windows.Win32.Foundation.ERROR_NO_SUCH_GROUP -Windows.Win32.Foundation.ERROR_NO_SUCH_LOGON_SESSION -Windows.Win32.Foundation.ERROR_NO_SUCH_MEMBER -Windows.Win32.Foundation.ERROR_NO_SUCH_PACKAGE -Windows.Win32.Foundation.ERROR_NO_SUCH_PRIVILEGE -Windows.Win32.Foundation.ERROR_NO_SUCH_SITE -Windows.Win32.Foundation.ERROR_NO_SUCH_USER -Windows.Win32.Foundation.ERROR_NO_SYSTEM_MENU -Windows.Win32.Foundation.ERROR_NO_SYSTEM_RESOURCES -Windows.Win32.Foundation.ERROR_NO_TASK_QUEUE -Windows.Win32.Foundation.ERROR_NO_TOKEN -Windows.Win32.Foundation.ERROR_NO_TRACKING_SERVICE -Windows.Win32.Foundation.ERROR_NO_TRUST_LSA_SECRET -Windows.Win32.Foundation.ERROR_NO_TRUST_SAM_ACCOUNT -Windows.Win32.Foundation.ERROR_NO_UNICODE_TRANSLATION -Windows.Win32.Foundation.ERROR_NO_USER_KEYS -Windows.Win32.Foundation.ERROR_NO_USER_SESSION_KEY -Windows.Win32.Foundation.ERROR_NO_VOLUME_ID -Windows.Win32.Foundation.ERROR_NO_VOLUME_LABEL -Windows.Win32.Foundation.ERROR_NO_WILDCARD_CHARACTERS -Windows.Win32.Foundation.ERROR_NO_WORK_DONE -Windows.Win32.Foundation.ERROR_NO_WRITABLE_DC_FOUND -Windows.Win32.Foundation.ERROR_NO_YIELD_PERFORMED -Windows.Win32.Foundation.ERROR_NOACCESS -Windows.Win32.Foundation.ERROR_NOINTERFACE -Windows.Win32.Foundation.ERROR_NOLOGON_INTERDOMAIN_TRUST_ACCOUNT -Windows.Win32.Foundation.ERROR_NOLOGON_SERVER_TRUST_ACCOUNT -Windows.Win32.Foundation.ERROR_NOLOGON_WORKSTATION_TRUST_ACCOUNT -Windows.Win32.Foundation.ERROR_NON_ACCOUNT_SID -Windows.Win32.Foundation.ERROR_NON_DOMAIN_SID -Windows.Win32.Foundation.ERROR_NON_MDICHILD_WINDOW -Windows.Win32.Foundation.ERROR_NONE_MAPPED -Windows.Win32.Foundation.ERROR_NONPAGED_SYSTEM_RESOURCES -Windows.Win32.Foundation.ERROR_NOT_A_CLOUD_FILE -Windows.Win32.Foundation.ERROR_NOT_A_CLOUD_SYNC_ROOT -Windows.Win32.Foundation.ERROR_NOT_A_DAX_VOLUME -Windows.Win32.Foundation.ERROR_NOT_A_REPARSE_POINT -Windows.Win32.Foundation.ERROR_NOT_ALL_ASSIGNED -Windows.Win32.Foundation.ERROR_NOT_ALLOWED_ON_SYSTEM_FILE -Windows.Win32.Foundation.ERROR_NOT_APPCONTAINER -Windows.Win32.Foundation.ERROR_NOT_AUTHENTICATED -Windows.Win32.Foundation.ERROR_NOT_CAPABLE -Windows.Win32.Foundation.ERROR_NOT_CHILD_WINDOW -Windows.Win32.Foundation.ERROR_NOT_CONNECTED -Windows.Win32.Foundation.ERROR_NOT_CONTAINER -Windows.Win32.Foundation.ERROR_NOT_DAX_MAPPABLE -Windows.Win32.Foundation.ERROR_NOT_DOS_DISK -Windows.Win32.Foundation.ERROR_NOT_ENOUGH_MEMORY -Windows.Win32.Foundation.ERROR_NOT_ENOUGH_QUOTA -Windows.Win32.Foundation.ERROR_NOT_ENOUGH_SERVER_MEMORY -Windows.Win32.Foundation.ERROR_NOT_EXPORT_FORMAT -Windows.Win32.Foundation.ERROR_NOT_FOUND -Windows.Win32.Foundation.ERROR_NOT_GUI_PROCESS -Windows.Win32.Foundation.ERROR_NOT_JOINED -Windows.Win32.Foundation.ERROR_NOT_LOCKED -Windows.Win32.Foundation.ERROR_NOT_LOGGED_ON -Windows.Win32.Foundation.ERROR_NOT_LOGON_PROCESS -Windows.Win32.Foundation.ERROR_NOT_OWNER -Windows.Win32.Foundation.ERROR_NOT_READ_FROM_COPY -Windows.Win32.Foundation.ERROR_NOT_READY -Windows.Win32.Foundation.ERROR_NOT_REDUNDANT_STORAGE -Windows.Win32.Foundation.ERROR_NOT_REGISTRY_FILE -Windows.Win32.Foundation.ERROR_NOT_SAFE_MODE_DRIVER -Windows.Win32.Foundation.ERROR_NOT_SAFEBOOT_SERVICE -Windows.Win32.Foundation.ERROR_NOT_SAME_DEVICE -Windows.Win32.Foundation.ERROR_NOT_SAME_OBJECT -Windows.Win32.Foundation.ERROR_NOT_SUBSTED -Windows.Win32.Foundation.ERROR_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_NOT_SUPPORTED_IN_APPCONTAINER -Windows.Win32.Foundation.ERROR_NOT_SUPPORTED_ON_DAX -Windows.Win32.Foundation.ERROR_NOT_SUPPORTED_ON_SBS -Windows.Win32.Foundation.ERROR_NOT_SUPPORTED_ON_STANDARD_SERVER -Windows.Win32.Foundation.ERROR_NOT_SUPPORTED_WITH_AUDITING -Windows.Win32.Foundation.ERROR_NOT_SUPPORTED_WITH_BTT -Windows.Win32.Foundation.ERROR_NOT_SUPPORTED_WITH_BYPASSIO -Windows.Win32.Foundation.ERROR_NOT_SUPPORTED_WITH_CACHED_HANDLE -Windows.Win32.Foundation.ERROR_NOT_SUPPORTED_WITH_COMPRESSION -Windows.Win32.Foundation.ERROR_NOT_SUPPORTED_WITH_DEDUPLICATION -Windows.Win32.Foundation.ERROR_NOT_SUPPORTED_WITH_ENCRYPTION -Windows.Win32.Foundation.ERROR_NOT_SUPPORTED_WITH_MONITORING -Windows.Win32.Foundation.ERROR_NOT_SUPPORTED_WITH_REPLICATION -Windows.Win32.Foundation.ERROR_NOT_SUPPORTED_WITH_SNAPSHOT -Windows.Win32.Foundation.ERROR_NOT_SUPPORTED_WITH_VIRTUALIZATION -Windows.Win32.Foundation.ERROR_NOT_TINY_STREAM -Windows.Win32.Foundation.ERROR_NOTHING_TO_TERMINATE -Windows.Win32.Foundation.ERROR_NOTIFICATION_GUID_ALREADY_DEFINED -Windows.Win32.Foundation.ERROR_NOTIFY_CLEANUP -Windows.Win32.Foundation.ERROR_NOTIFY_ENUM_DIR -Windows.Win32.Foundation.ERROR_NT_CROSS_ENCRYPTION_REQUIRED -Windows.Win32.Foundation.ERROR_NTLM_BLOCKED -Windows.Win32.Foundation.ERROR_NULL_LM_PASSWORD -Windows.Win32.Foundation.ERROR_OBJECT_IS_IMMUTABLE -Windows.Win32.Foundation.ERROR_OBJECT_NAME_EXISTS -Windows.Win32.Foundation.ERROR_OBJECT_NOT_EXTERNALLY_BACKED -Windows.Win32.Foundation.ERROR_OFFLOAD_READ_FILE_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_OFFLOAD_READ_FLT_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_OFFLOAD_WRITE_FILE_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_OFFLOAD_WRITE_FLT_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_OFFSET_ALIGNMENT_VIOLATION -Windows.Win32.Foundation.ERROR_OLD_WIN_VERSION -Windows.Win32.Foundation.ERROR_ONLY_IF_CONNECTED -Windows.Win32.Foundation.ERROR_OPEN_FAILED -Windows.Win32.Foundation.ERROR_OPEN_FILES -Windows.Win32.Foundation.ERROR_OPERATION_ABORTED -Windows.Win32.Foundation.ERROR_OPERATION_IN_PROGRESS -Windows.Win32.Foundation.ERROR_OPLOCK_BREAK_IN_PROGRESS -Windows.Win32.Foundation.ERROR_OPLOCK_HANDLE_CLOSED -Windows.Win32.Foundation.ERROR_OPLOCK_NOT_GRANTED -Windows.Win32.Foundation.ERROR_OPLOCK_SWITCHED_TO_NEW_HANDLE -Windows.Win32.Foundation.ERROR_ORPHAN_NAME_EXHAUSTED -Windows.Win32.Foundation.ERROR_OUT_OF_PAPER -Windows.Win32.Foundation.ERROR_OUT_OF_STRUCTURES -Windows.Win32.Foundation.ERROR_OUTOFMEMORY -Windows.Win32.Foundation.ERROR_OVERRIDE_NOCHANGES -Windows.Win32.Foundation.ERROR_PAGE_FAULT_COPY_ON_WRITE -Windows.Win32.Foundation.ERROR_PAGE_FAULT_DEMAND_ZERO -Windows.Win32.Foundation.ERROR_PAGE_FAULT_GUARD_PAGE -Windows.Win32.Foundation.ERROR_PAGE_FAULT_PAGING_FILE -Windows.Win32.Foundation.ERROR_PAGE_FAULT_TRANSITION -Windows.Win32.Foundation.ERROR_PAGED_SYSTEM_RESOURCES -Windows.Win32.Foundation.ERROR_PAGEFILE_CREATE_FAILED -Windows.Win32.Foundation.ERROR_PAGEFILE_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_PAGEFILE_QUOTA -Windows.Win32.Foundation.ERROR_PAGEFILE_QUOTA_EXCEEDED -Windows.Win32.Foundation.ERROR_PARAMETER_QUOTA_EXCEEDED -Windows.Win32.Foundation.ERROR_PARTIAL_COPY -Windows.Win32.Foundation.ERROR_PARTITION_FAILURE -Windows.Win32.Foundation.ERROR_PARTITION_TERMINATING -Windows.Win32.Foundation.ERROR_PASSWORD_CHANGE_REQUIRED -Windows.Win32.Foundation.ERROR_PASSWORD_EXPIRED -Windows.Win32.Foundation.ERROR_PASSWORD_MUST_CHANGE -Windows.Win32.Foundation.ERROR_PASSWORD_RESTRICTION -Windows.Win32.Foundation.ERROR_PATCH_MANAGED_ADVERTISED_PRODUCT -Windows.Win32.Foundation.ERROR_PATCH_NO_SEQUENCE -Windows.Win32.Foundation.ERROR_PATCH_PACKAGE_INVALID -Windows.Win32.Foundation.ERROR_PATCH_PACKAGE_OPEN_FAILED -Windows.Win32.Foundation.ERROR_PATCH_PACKAGE_REJECTED -Windows.Win32.Foundation.ERROR_PATCH_PACKAGE_UNSUPPORTED -Windows.Win32.Foundation.ERROR_PATCH_REMOVAL_DISALLOWED -Windows.Win32.Foundation.ERROR_PATCH_REMOVAL_UNSUPPORTED -Windows.Win32.Foundation.ERROR_PATCH_TARGET_NOT_FOUND -Windows.Win32.Foundation.ERROR_PATH_BUSY -Windows.Win32.Foundation.ERROR_PATH_NOT_FOUND -Windows.Win32.Foundation.ERROR_PER_USER_TRUST_QUOTA_EXCEEDED -Windows.Win32.Foundation.ERROR_PIPE_BUSY -Windows.Win32.Foundation.ERROR_PIPE_CONNECTED -Windows.Win32.Foundation.ERROR_PIPE_LISTENING -Windows.Win32.Foundation.ERROR_PIPE_LOCAL -Windows.Win32.Foundation.ERROR_PIPE_NOT_CONNECTED -Windows.Win32.Foundation.ERROR_PKINIT_FAILURE -Windows.Win32.Foundation.ERROR_PLUGPLAY_QUERY_VETOED -Windows.Win32.Foundation.ERROR_PNP_BAD_MPS_TABLE -Windows.Win32.Foundation.ERROR_PNP_INVALID_ID -Windows.Win32.Foundation.ERROR_PNP_IRQ_TRANSLATION_FAILED -Windows.Win32.Foundation.ERROR_PNP_QUERY_REMOVE_DEVICE_TIMEOUT -Windows.Win32.Foundation.ERROR_PNP_QUERY_REMOVE_RELATED_DEVICE_TIMEOUT -Windows.Win32.Foundation.ERROR_PNP_QUERY_REMOVE_UNRELATED_DEVICE_TIMEOUT -Windows.Win32.Foundation.ERROR_PNP_REBOOT_REQUIRED -Windows.Win32.Foundation.ERROR_PNP_RESTART_ENUMERATION -Windows.Win32.Foundation.ERROR_PNP_TRANSLATION_FAILED -Windows.Win32.Foundation.ERROR_POINT_NOT_FOUND -Windows.Win32.Foundation.ERROR_POLICY_OBJECT_NOT_FOUND -Windows.Win32.Foundation.ERROR_POLICY_ONLY_IN_DS -Windows.Win32.Foundation.ERROR_POPUP_ALREADY_ACTIVE -Windows.Win32.Foundation.ERROR_PORT_MESSAGE_TOO_LONG -Windows.Win32.Foundation.ERROR_PORT_NOT_SET -Windows.Win32.Foundation.ERROR_PORT_UNREACHABLE -Windows.Win32.Foundation.ERROR_POSSIBLE_DEADLOCK -Windows.Win32.Foundation.ERROR_POTENTIAL_FILE_FOUND -Windows.Win32.Foundation.ERROR_PREDEFINED_HANDLE -Windows.Win32.Foundation.ERROR_PRIMARY_TRANSPORT_CONNECT_FAILED -Windows.Win32.Foundation.ERROR_PRINT_CANCELLED -Windows.Win32.Foundation.ERROR_PRINTER_ALREADY_EXISTS -Windows.Win32.Foundation.ERROR_PRINTER_DELETED -Windows.Win32.Foundation.ERROR_PRINTER_DRIVER_ALREADY_INSTALLED -Windows.Win32.Foundation.ERROR_PRINTQ_FULL -Windows.Win32.Foundation.ERROR_PRIVATE_DIALOG_INDEX -Windows.Win32.Foundation.ERROR_PRIVILEGE_NOT_HELD -Windows.Win32.Foundation.ERROR_PROC_NOT_FOUND -Windows.Win32.Foundation.ERROR_PROCESS_ABORTED -Windows.Win32.Foundation.ERROR_PROCESS_IN_JOB -Windows.Win32.Foundation.ERROR_PROCESS_IS_PROTECTED -Windows.Win32.Foundation.ERROR_PROCESS_MODE_ALREADY_BACKGROUND -Windows.Win32.Foundation.ERROR_PROCESS_MODE_NOT_BACKGROUND -Windows.Win32.Foundation.ERROR_PROCESS_NOT_IN_JOB -Windows.Win32.Foundation.ERROR_PRODUCT_UNINSTALLED -Windows.Win32.Foundation.ERROR_PRODUCT_VERSION -Windows.Win32.Foundation.ERROR_PROFILING_AT_LIMIT -Windows.Win32.Foundation.ERROR_PROFILING_NOT_STARTED -Windows.Win32.Foundation.ERROR_PROFILING_NOT_STOPPED -Windows.Win32.Foundation.ERROR_PROMOTION_ACTIVE -Windows.Win32.Foundation.ERROR_PROTOCOL_UNREACHABLE -Windows.Win32.Foundation.ERROR_PWD_HISTORY_CONFLICT -Windows.Win32.Foundation.ERROR_PWD_TOO_LONG -Windows.Win32.Foundation.ERROR_PWD_TOO_RECENT -Windows.Win32.Foundation.ERROR_PWD_TOO_SHORT -Windows.Win32.Foundation.ERROR_QUOTA_ACTIVITY -Windows.Win32.Foundation.ERROR_QUOTA_LIST_INCONSISTENT -Windows.Win32.Foundation.ERROR_RANGE_LIST_CONFLICT -Windows.Win32.Foundation.ERROR_RANGE_NOT_FOUND -Windows.Win32.Foundation.ERROR_READ_FAULT -Windows.Win32.Foundation.ERROR_RECEIVE_EXPEDITED -Windows.Win32.Foundation.ERROR_RECEIVE_PARTIAL -Windows.Win32.Foundation.ERROR_RECEIVE_PARTIAL_EXPEDITED -Windows.Win32.Foundation.ERROR_RECOVERY_FAILURE -Windows.Win32.Foundation.ERROR_REDIR_PAUSED -Windows.Win32.Foundation.ERROR_REDIRECTOR_HAS_OPEN_HANDLES -Windows.Win32.Foundation.ERROR_REG_NAT_CONSUMPTION -Windows.Win32.Foundation.ERROR_REGISTRY_CORRUPT -Windows.Win32.Foundation.ERROR_REGISTRY_HIVE_RECOVERED -Windows.Win32.Foundation.ERROR_REGISTRY_IO_FAILED -Windows.Win32.Foundation.ERROR_REGISTRY_QUOTA_LIMIT -Windows.Win32.Foundation.ERROR_REGISTRY_RECOVERED -Windows.Win32.Foundation.ERROR_RELOC_CHAIN_XEEDS_SEGLIM -Windows.Win32.Foundation.ERROR_REM_NOT_LIST -Windows.Win32.Foundation.ERROR_REMOTE_PRINT_CONNECTIONS_BLOCKED -Windows.Win32.Foundation.ERROR_REMOTE_SESSION_LIMIT_EXCEEDED -Windows.Win32.Foundation.ERROR_REMOTE_STORAGE_MEDIA_ERROR -Windows.Win32.Foundation.ERROR_REMOTE_STORAGE_NOT_ACTIVE -Windows.Win32.Foundation.ERROR_REPARSE -Windows.Win32.Foundation.ERROR_REPARSE_ATTRIBUTE_CONFLICT -Windows.Win32.Foundation.ERROR_REPARSE_OBJECT -Windows.Win32.Foundation.ERROR_REPARSE_POINT_ENCOUNTERED -Windows.Win32.Foundation.ERROR_REPARSE_TAG_INVALID -Windows.Win32.Foundation.ERROR_REPARSE_TAG_MISMATCH -Windows.Win32.Foundation.ERROR_REPLY_MESSAGE_MISMATCH -Windows.Win32.Foundation.ERROR_REQ_NOT_ACCEP -Windows.Win32.Foundation.ERROR_REQUEST_ABORTED -Windows.Win32.Foundation.ERROR_REQUEST_OUT_OF_SEQUENCE -Windows.Win32.Foundation.ERROR_REQUEST_PAUSED -Windows.Win32.Foundation.ERROR_REQUIRES_INTERACTIVE_WINDOWSTATION -Windows.Win32.Foundation.ERROR_RESIDENT_FILE_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_RESOURCE_CALL_TIMED_OUT -Windows.Win32.Foundation.ERROR_RESOURCE_DATA_NOT_FOUND -Windows.Win32.Foundation.ERROR_RESOURCE_LANG_NOT_FOUND -Windows.Win32.Foundation.ERROR_RESOURCE_NAME_NOT_FOUND -Windows.Win32.Foundation.ERROR_RESOURCE_REQUIREMENTS_CHANGED -Windows.Win32.Foundation.ERROR_RESOURCE_TYPE_NOT_FOUND -Windows.Win32.Foundation.ERROR_RESTART_APPLICATION -Windows.Win32.Foundation.ERROR_RESUME_HIBERNATION -Windows.Win32.Foundation.ERROR_RETRY -Windows.Win32.Foundation.ERROR_RETURN_ADDRESS_HIJACK_ATTEMPT -Windows.Win32.Foundation.ERROR_REVISION_MISMATCH -Windows.Win32.Foundation.ERROR_RING2_STACK_IN_USE -Windows.Win32.Foundation.ERROR_RING2SEG_MUST_BE_MOVABLE -Windows.Win32.Foundation.ERROR_RMODE_APP -Windows.Win32.Foundation.ERROR_ROWSNOTRELEASED -Windows.Win32.Foundation.ERROR_RUNLEVEL_SWITCH_AGENT_TIMEOUT -Windows.Win32.Foundation.ERROR_RUNLEVEL_SWITCH_TIMEOUT -Windows.Win32.Foundation.ERROR_RWRAW_ENCRYPTED_FILE_NOT_ENCRYPTED -Windows.Win32.Foundation.ERROR_RWRAW_ENCRYPTED_INVALID_EDATAINFO_FILEOFFSET -Windows.Win32.Foundation.ERROR_RWRAW_ENCRYPTED_INVALID_EDATAINFO_FILERANGE -Windows.Win32.Foundation.ERROR_RWRAW_ENCRYPTED_INVALID_EDATAINFO_PARAMETER -Windows.Win32.Foundation.ERROR_RXACT_COMMIT_FAILURE -Windows.Win32.Foundation.ERROR_RXACT_COMMIT_NECESSARY -Windows.Win32.Foundation.ERROR_RXACT_COMMITTED -Windows.Win32.Foundation.ERROR_RXACT_INVALID_STATE -Windows.Win32.Foundation.ERROR_RXACT_STATE_CREATED -Windows.Win32.Foundation.ERROR_SAM_INIT_FAILURE -Windows.Win32.Foundation.ERROR_SAME_DRIVE -Windows.Win32.Foundation.ERROR_SCOPE_NOT_FOUND -Windows.Win32.Foundation.ERROR_SCREEN_ALREADY_LOCKED -Windows.Win32.Foundation.ERROR_SCRUB_DATA_DISABLED -Windows.Win32.Foundation.ERROR_SECRET_TOO_LONG -Windows.Win32.Foundation.ERROR_SECTION_DIRECT_MAP_ONLY -Windows.Win32.Foundation.ERROR_SECTOR_NOT_FOUND -Windows.Win32.Foundation.ERROR_SECURITY_DENIES_OPERATION -Windows.Win32.Foundation.ERROR_SECURITY_STREAM_IS_INCONSISTENT -Windows.Win32.Foundation.ERROR_SEEK -Windows.Win32.Foundation.ERROR_SEEK_ON_DEVICE -Windows.Win32.Foundation.ERROR_SEGMENT_NOTIFICATION -Windows.Win32.Foundation.ERROR_SEM_IS_SET -Windows.Win32.Foundation.ERROR_SEM_NOT_FOUND -Windows.Win32.Foundation.ERROR_SEM_OWNER_DIED -Windows.Win32.Foundation.ERROR_SEM_TIMEOUT -Windows.Win32.Foundation.ERROR_SEM_USER_LIMIT -Windows.Win32.Foundation.ERROR_SERIAL_NO_DEVICE -Windows.Win32.Foundation.ERROR_SERVER_DISABLED -Windows.Win32.Foundation.ERROR_SERVER_HAS_OPEN_HANDLES -Windows.Win32.Foundation.ERROR_SERVER_NOT_DISABLED -Windows.Win32.Foundation.ERROR_SERVER_SHUTDOWN_IN_PROGRESS -Windows.Win32.Foundation.ERROR_SERVER_SID_MISMATCH -Windows.Win32.Foundation.ERROR_SERVER_TRANSPORT_CONFLICT -Windows.Win32.Foundation.ERROR_SERVICE_ALREADY_RUNNING -Windows.Win32.Foundation.ERROR_SERVICE_CANNOT_ACCEPT_CTRL -Windows.Win32.Foundation.ERROR_SERVICE_DATABASE_LOCKED -Windows.Win32.Foundation.ERROR_SERVICE_DEPENDENCY_DELETED -Windows.Win32.Foundation.ERROR_SERVICE_DEPENDENCY_FAIL -Windows.Win32.Foundation.ERROR_SERVICE_DISABLED -Windows.Win32.Foundation.ERROR_SERVICE_DOES_NOT_EXIST -Windows.Win32.Foundation.ERROR_SERVICE_EXISTS -Windows.Win32.Foundation.ERROR_SERVICE_LOGON_FAILED -Windows.Win32.Foundation.ERROR_SERVICE_MARKED_FOR_DELETE -Windows.Win32.Foundation.ERROR_SERVICE_NEVER_STARTED -Windows.Win32.Foundation.ERROR_SERVICE_NO_THREAD -Windows.Win32.Foundation.ERROR_SERVICE_NOT_ACTIVE -Windows.Win32.Foundation.ERROR_SERVICE_NOT_FOUND -Windows.Win32.Foundation.ERROR_SERVICE_NOT_IN_EXE -Windows.Win32.Foundation.ERROR_SERVICE_NOTIFICATION -Windows.Win32.Foundation.ERROR_SERVICE_NOTIFY_CLIENT_LAGGING -Windows.Win32.Foundation.ERROR_SERVICE_REQUEST_TIMEOUT -Windows.Win32.Foundation.ERROR_SERVICE_SPECIFIC_ERROR -Windows.Win32.Foundation.ERROR_SERVICE_START_HANG -Windows.Win32.Foundation.ERROR_SESSION_CREDENTIAL_CONFLICT -Windows.Win32.Foundation.ERROR_SESSION_KEY_TOO_SHORT -Windows.Win32.Foundation.ERROR_SET_CONTEXT_DENIED -Windows.Win32.Foundation.ERROR_SET_NOT_FOUND -Windows.Win32.Foundation.ERROR_SET_POWER_STATE_FAILED -Windows.Win32.Foundation.ERROR_SET_POWER_STATE_VETOED -Windows.Win32.Foundation.ERROR_SETCOUNT_ON_BAD_LB -Windows.Win32.Foundation.ERROR_SETMARK_DETECTED -Windows.Win32.Foundation.ERROR_SHARED_POLICY -Windows.Win32.Foundation.ERROR_SHARING_BUFFER_EXCEEDED -Windows.Win32.Foundation.ERROR_SHARING_PAUSED -Windows.Win32.Foundation.ERROR_SHARING_VIOLATION -Windows.Win32.Foundation.ERROR_SHORT_NAMES_NOT_ENABLED_ON_VOLUME -Windows.Win32.Foundation.ERROR_SHUTDOWN_DISKS_NOT_IN_MAINTENANCE_MODE -Windows.Win32.Foundation.ERROR_SHUTDOWN_IN_PROGRESS -Windows.Win32.Foundation.ERROR_SHUTDOWN_IS_SCHEDULED -Windows.Win32.Foundation.ERROR_SHUTDOWN_USERS_LOGGED_ON -Windows.Win32.Foundation.ERROR_SIGNAL_PENDING -Windows.Win32.Foundation.ERROR_SIGNAL_REFUSED -Windows.Win32.Foundation.ERROR_SINGLE_INSTANCE_APP -Windows.Win32.Foundation.ERROR_SMARTCARD_SUBSYSTEM_FAILURE -Windows.Win32.Foundation.ERROR_SMB1_NOT_AVAILABLE -Windows.Win32.Foundation.ERROR_SMB_GUEST_LOGON_BLOCKED -Windows.Win32.Foundation.ERROR_SMR_GARBAGE_COLLECTION_REQUIRED -Windows.Win32.Foundation.ERROR_SOME_NOT_MAPPED -Windows.Win32.Foundation.ERROR_SOURCE_ELEMENT_EMPTY -Windows.Win32.Foundation.ERROR_SPARSE_FILE_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_SPECIAL_ACCOUNT -Windows.Win32.Foundation.ERROR_SPECIAL_GROUP -Windows.Win32.Foundation.ERROR_SPECIAL_USER -Windows.Win32.Foundation.ERROR_SRC_SRV_DLL_LOAD_FAILED -Windows.Win32.Foundation.ERROR_STACK_BUFFER_OVERRUN -Windows.Win32.Foundation.ERROR_STACK_OVERFLOW -Windows.Win32.Foundation.ERROR_STACK_OVERFLOW_READ -Windows.Win32.Foundation.ERROR_STOPPED_ON_SYMLINK -Windows.Win32.Foundation.ERROR_STORAGE_LOST_DATA_PERSISTENCE -Windows.Win32.Foundation.ERROR_STORAGE_RESERVE_ALREADY_EXISTS -Windows.Win32.Foundation.ERROR_STORAGE_RESERVE_DOES_NOT_EXIST -Windows.Win32.Foundation.ERROR_STORAGE_RESERVE_ID_INVALID -Windows.Win32.Foundation.ERROR_STORAGE_RESERVE_NOT_EMPTY -Windows.Win32.Foundation.ERROR_STORAGE_STACK_ACCESS_DENIED -Windows.Win32.Foundation.ERROR_STORAGE_TOPOLOGY_ID_MISMATCH -Windows.Win32.Foundation.ERROR_STRICT_CFG_VIOLATION -Windows.Win32.Foundation.ERROR_SUBST_TO_JOIN -Windows.Win32.Foundation.ERROR_SUBST_TO_SUBST -Windows.Win32.Foundation.ERROR_SUCCESS -Windows.Win32.Foundation.ERROR_SUCCESS_REBOOT_INITIATED -Windows.Win32.Foundation.ERROR_SWAPERROR -Windows.Win32.Foundation.ERROR_SYMLINK_CLASS_DISABLED -Windows.Win32.Foundation.ERROR_SYMLINK_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_SYNC_FOREGROUND_REFRESH_REQUIRED -Windows.Win32.Foundation.ERROR_SYNCHRONIZATION_REQUIRED -Windows.Win32.Foundation.ERROR_SYSTEM_HIVE_TOO_LARGE -Windows.Win32.Foundation.ERROR_SYSTEM_IMAGE_BAD_SIGNATURE -Windows.Win32.Foundation.ERROR_SYSTEM_POWERSTATE_COMPLEX_TRANSITION -Windows.Win32.Foundation.ERROR_SYSTEM_POWERSTATE_TRANSITION -Windows.Win32.Foundation.ERROR_SYSTEM_PROCESS_TERMINATED -Windows.Win32.Foundation.ERROR_SYSTEM_SHUTDOWN -Windows.Win32.Foundation.ERROR_SYSTEM_TRACE -Windows.Win32.Foundation.ERROR_THREAD_1_INACTIVE -Windows.Win32.Foundation.ERROR_THREAD_ALREADY_IN_TASK -Windows.Win32.Foundation.ERROR_THREAD_MODE_ALREADY_BACKGROUND -Windows.Win32.Foundation.ERROR_THREAD_MODE_NOT_BACKGROUND -Windows.Win32.Foundation.ERROR_THREAD_NOT_IN_PROCESS -Windows.Win32.Foundation.ERROR_THREAD_WAS_SUSPENDED -Windows.Win32.Foundation.ERROR_TIME_SENSITIVE_THREAD -Windows.Win32.Foundation.ERROR_TIME_SKEW -Windows.Win32.Foundation.ERROR_TIMEOUT -Windows.Win32.Foundation.ERROR_TIMER_NOT_CANCELED -Windows.Win32.Foundation.ERROR_TIMER_RESOLUTION_NOT_SET -Windows.Win32.Foundation.ERROR_TIMER_RESUME_IGNORED -Windows.Win32.Foundation.ERROR_TLW_WITH_WSCHILD -Windows.Win32.Foundation.ERROR_TOKEN_ALREADY_IN_USE -Windows.Win32.Foundation.ERROR_TOO_MANY_CMDS -Windows.Win32.Foundation.ERROR_TOO_MANY_CONTEXT_IDS -Windows.Win32.Foundation.ERROR_TOO_MANY_DESCRIPTORS -Windows.Win32.Foundation.ERROR_TOO_MANY_LINKS -Windows.Win32.Foundation.ERROR_TOO_MANY_LUIDS_REQUESTED -Windows.Win32.Foundation.ERROR_TOO_MANY_MODULES -Windows.Win32.Foundation.ERROR_TOO_MANY_MUXWAITERS -Windows.Win32.Foundation.ERROR_TOO_MANY_NAMES -Windows.Win32.Foundation.ERROR_TOO_MANY_OPEN_FILES -Windows.Win32.Foundation.ERROR_TOO_MANY_POSTS -Windows.Win32.Foundation.ERROR_TOO_MANY_SECRETS -Windows.Win32.Foundation.ERROR_TOO_MANY_SEM_REQUESTS -Windows.Win32.Foundation.ERROR_TOO_MANY_SEMAPHORES -Windows.Win32.Foundation.ERROR_TOO_MANY_SESS -Windows.Win32.Foundation.ERROR_TOO_MANY_SIDS -Windows.Win32.Foundation.ERROR_TOO_MANY_TCBS -Windows.Win32.Foundation.ERROR_TOO_MANY_THREADS -Windows.Win32.Foundation.ERROR_TRANSLATION_COMPLETE -Windows.Win32.Foundation.ERROR_TRUST_FAILURE -Windows.Win32.Foundation.ERROR_TRUSTED_DOMAIN_FAILURE -Windows.Win32.Foundation.ERROR_TRUSTED_RELATIONSHIP_FAILURE -Windows.Win32.Foundation.ERROR_UNABLE_TO_LOCK_MEDIA -Windows.Win32.Foundation.ERROR_UNABLE_TO_MOVE_REPLACEMENT -Windows.Win32.Foundation.ERROR_UNABLE_TO_MOVE_REPLACEMENT_2 -Windows.Win32.Foundation.ERROR_UNABLE_TO_REMOVE_REPLACED -Windows.Win32.Foundation.ERROR_UNABLE_TO_UNLOAD_MEDIA -Windows.Win32.Foundation.ERROR_UNDEFINED_CHARACTER -Windows.Win32.Foundation.ERROR_UNDEFINED_SCOPE -Windows.Win32.Foundation.ERROR_UNEXP_NET_ERR -Windows.Win32.Foundation.ERROR_UNEXPECTED_MM_CREATE_ERR -Windows.Win32.Foundation.ERROR_UNEXPECTED_MM_EXTEND_ERR -Windows.Win32.Foundation.ERROR_UNEXPECTED_MM_MAP_ERROR -Windows.Win32.Foundation.ERROR_UNEXPECTED_NTCACHEMANAGER_ERROR -Windows.Win32.Foundation.ERROR_UNHANDLED_EXCEPTION -Windows.Win32.Foundation.ERROR_UNIDENTIFIED_ERROR -Windows.Win32.Foundation.ERROR_UNKNOWN_COMPONENT -Windows.Win32.Foundation.ERROR_UNKNOWN_FEATURE -Windows.Win32.Foundation.ERROR_UNKNOWN_PATCH -Windows.Win32.Foundation.ERROR_UNKNOWN_PORT -Windows.Win32.Foundation.ERROR_UNKNOWN_PRINTER_DRIVER -Windows.Win32.Foundation.ERROR_UNKNOWN_PRINTPROCESSOR -Windows.Win32.Foundation.ERROR_UNKNOWN_PRODUCT -Windows.Win32.Foundation.ERROR_UNKNOWN_PROPERTY -Windows.Win32.Foundation.ERROR_UNKNOWN_REVISION -Windows.Win32.Foundation.ERROR_UNRECOGNIZED_MEDIA -Windows.Win32.Foundation.ERROR_UNRECOGNIZED_VOLUME -Windows.Win32.Foundation.ERROR_UNSATISFIED_DEPENDENCIES -Windows.Win32.Foundation.ERROR_UNSUPPORTED_COMPRESSION -Windows.Win32.Foundation.ERROR_UNSUPPORTED_TYPE -Windows.Win32.Foundation.ERROR_UNTRUSTED_MOUNT_POINT -Windows.Win32.Foundation.ERROR_UNWIND -Windows.Win32.Foundation.ERROR_UNWIND_CONSOLIDATE -Windows.Win32.Foundation.ERROR_USER_APC -Windows.Win32.Foundation.ERROR_USER_DELETE_TRUST_QUOTA_EXCEEDED -Windows.Win32.Foundation.ERROR_USER_EXISTS -Windows.Win32.Foundation.ERROR_USER_MAPPED_FILE -Windows.Win32.Foundation.ERROR_USER_PROFILE_LOAD -Windows.Win32.Foundation.ERROR_VALIDATE_CONTINUE -Windows.Win32.Foundation.ERROR_VC_DISCONNECTED -Windows.Win32.Foundation.ERROR_VDM_DISALLOWED -Windows.Win32.Foundation.ERROR_VDM_HARD_ERROR -Windows.Win32.Foundation.ERROR_VERIFIER_STOP -Windows.Win32.Foundation.ERROR_VERSION_PARSE_ERROR -Windows.Win32.Foundation.ERROR_VIRUS_DELETED -Windows.Win32.Foundation.ERROR_VIRUS_INFECTED -Windows.Win32.Foundation.ERROR_VOLSNAP_HIBERNATE_READY -Windows.Win32.Foundation.ERROR_VOLSNAP_PREPARE_HIBERNATE -Windows.Win32.Foundation.ERROR_VOLUME_MOUNTED -Windows.Win32.Foundation.ERROR_VOLUME_NOT_CLUSTER_ALIGNED -Windows.Win32.Foundation.ERROR_VOLUME_NOT_SIS_ENABLED -Windows.Win32.Foundation.ERROR_VOLUME_NOT_SUPPORT_EFS -Windows.Win32.Foundation.ERROR_VOLUME_NOT_SUPPORTED -Windows.Win32.Foundation.ERROR_VOLUME_WRITE_ACCESS_DENIED -Windows.Win32.Foundation.ERROR_WAIT_1 -Windows.Win32.Foundation.ERROR_WAIT_2 -Windows.Win32.Foundation.ERROR_WAIT_3 -Windows.Win32.Foundation.ERROR_WAIT_63 -Windows.Win32.Foundation.ERROR_WAIT_FOR_OPLOCK -Windows.Win32.Foundation.ERROR_WAIT_NO_CHILDREN -Windows.Win32.Foundation.ERROR_WAKE_SYSTEM -Windows.Win32.Foundation.ERROR_WAKE_SYSTEM_DEBUGGER -Windows.Win32.Foundation.ERROR_WAS_LOCKED -Windows.Win32.Foundation.ERROR_WAS_UNLOCKED -Windows.Win32.Foundation.ERROR_WEAK_WHFBKEY_BLOCKED -Windows.Win32.Foundation.ERROR_WINDOW_NOT_COMBOBOX -Windows.Win32.Foundation.ERROR_WINDOW_NOT_DIALOG -Windows.Win32.Foundation.ERROR_WINDOW_OF_OTHER_THREAD -Windows.Win32.Foundation.ERROR_WIP_ENCRYPTION_FAILED -Windows.Win32.Foundation.ERROR_WOF_FILE_RESOURCE_TABLE_CORRUPT -Windows.Win32.Foundation.ERROR_WOF_WIM_HEADER_CORRUPT -Windows.Win32.Foundation.ERROR_WOF_WIM_RESOURCE_TABLE_CORRUPT -Windows.Win32.Foundation.ERROR_WORKING_SET_QUOTA -Windows.Win32.Foundation.ERROR_WOW_ASSERTION -Windows.Win32.Foundation.ERROR_WRITE_FAULT -Windows.Win32.Foundation.ERROR_WRITE_PROTECT -Windows.Win32.Foundation.ERROR_WRONG_COMPARTMENT -Windows.Win32.Foundation.ERROR_WRONG_DISK -Windows.Win32.Foundation.ERROR_WRONG_EFS -Windows.Win32.Foundation.ERROR_WRONG_PASSWORD -Windows.Win32.Foundation.ERROR_WRONG_TARGET_NAME -Windows.Win32.Foundation.ERROR_WX86_ERROR -Windows.Win32.Foundation.ERROR_WX86_WARNING -Windows.Win32.Foundation.ERROR_XML_PARSE_ERROR -Windows.Win32.Foundation.ERROR_XMLDSIG_ERROR -Windows.Win32.Foundation.EXCEPTION_STACK_OVERFLOW -Windows.Win32.Foundation.FALSE -Windows.Win32.Foundation.FARPROC -Windows.Win32.Foundation.FILETIME -Windows.Win32.Foundation.FRS_ERR_SYSVOL_POPULATE_TIMEOUT -Windows.Win32.Foundation.GENERIC_ACCESS_RIGHTS -Windows.Win32.Foundation.GENERIC_ALL -Windows.Win32.Foundation.GENERIC_EXECUTE -Windows.Win32.Foundation.GENERIC_READ -Windows.Win32.Foundation.GENERIC_WRITE -Windows.Win32.Foundation.GetLastError -Windows.Win32.Foundation.HANDLE -Windows.Win32.Foundation.HANDLE_FLAG_INHERIT -Windows.Win32.Foundation.HANDLE_FLAG_PROTECT_FROM_CLOSE -Windows.Win32.Foundation.HANDLE_FLAGS -Windows.Win32.Foundation.HMODULE -Windows.Win32.Foundation.LocalFree -Windows.Win32.Foundation.MAX_PATH -Windows.Win32.Foundation.NO_ERROR -Windows.Win32.Foundation.NTSTATUS -Windows.Win32.Foundation.RtlNtStatusToDosError -Windows.Win32.Foundation.SetHandleInformation -Windows.Win32.Foundation.SetLastError -Windows.Win32.Foundation.STATUS_DELETE_PENDING -Windows.Win32.Foundation.STATUS_END_OF_FILE -Windows.Win32.Foundation.STATUS_INVALID_PARAMETER -Windows.Win32.Foundation.STATUS_NOT_IMPLEMENTED -Windows.Win32.Foundation.STATUS_PENDING -Windows.Win32.Foundation.STATUS_SUCCESS -Windows.Win32.Foundation.TRUE -Windows.Win32.Foundation.UNICODE_STRING -Windows.Win32.Foundation.WAIT_ABANDONED -Windows.Win32.Foundation.WAIT_ABANDONED_0 -Windows.Win32.Foundation.WAIT_FAILED -Windows.Win32.Foundation.WAIT_IO_COMPLETION -Windows.Win32.Foundation.WAIT_OBJECT_0 -Windows.Win32.Foundation.WAIT_TIMEOUT -Windows.Win32.Foundation.WIN32_ERROR -Windows.Win32.Globalization.COMPARESTRING_RESULT -Windows.Win32.Globalization.CompareStringOrdinal -Windows.Win32.Globalization.CP_UTF8 -Windows.Win32.Globalization.CSTR_EQUAL -Windows.Win32.Globalization.CSTR_GREATER_THAN -Windows.Win32.Globalization.CSTR_LESS_THAN -Windows.Win32.Globalization.MB_COMPOSITE -Windows.Win32.Globalization.MB_ERR_INVALID_CHARS -Windows.Win32.Globalization.MB_PRECOMPOSED -Windows.Win32.Globalization.MB_USEGLYPHCHARS -Windows.Win32.Globalization.MULTI_BYTE_TO_WIDE_CHAR_FLAGS -Windows.Win32.Globalization.MultiByteToWideChar -Windows.Win32.Globalization.WC_ERR_INVALID_CHARS -Windows.Win32.Globalization.WideCharToMultiByte -Windows.Win32.Networking.WinSock.accept -Windows.Win32.Networking.WinSock.ADDRESS_FAMILY -Windows.Win32.Networking.WinSock.ADDRINFOA -Windows.Win32.Networking.WinSock.AF_INET -Windows.Win32.Networking.WinSock.AF_INET6 -Windows.Win32.Networking.WinSock.AF_UNIX -Windows.Win32.Networking.WinSock.AF_UNSPEC -Windows.Win32.Networking.WinSock.bind -Windows.Win32.Networking.WinSock.closesocket -Windows.Win32.Networking.WinSock.connect -Windows.Win32.Networking.WinSock.FD_SET -Windows.Win32.Networking.WinSock.FIONBIO -Windows.Win32.Networking.WinSock.freeaddrinfo -Windows.Win32.Networking.WinSock.getaddrinfo -Windows.Win32.Networking.WinSock.getpeername -Windows.Win32.Networking.WinSock.getsockname -Windows.Win32.Networking.WinSock.getsockopt -Windows.Win32.Networking.WinSock.IN6_ADDR -Windows.Win32.Networking.WinSock.IN_ADDR -Windows.Win32.Networking.WinSock.INVALID_SOCKET -Windows.Win32.Networking.WinSock.ioctlsocket -Windows.Win32.Networking.WinSock.IP_ADD_MEMBERSHIP -Windows.Win32.Networking.WinSock.IP_DROP_MEMBERSHIP -Windows.Win32.Networking.WinSock.IP_MREQ -Windows.Win32.Networking.WinSock.IP_MULTICAST_LOOP -Windows.Win32.Networking.WinSock.IP_MULTICAST_TTL -Windows.Win32.Networking.WinSock.IP_TTL -Windows.Win32.Networking.WinSock.IPPROTO -Windows.Win32.Networking.WinSock.IPPROTO_AH -Windows.Win32.Networking.WinSock.IPPROTO_CBT -Windows.Win32.Networking.WinSock.IPPROTO_DSTOPTS -Windows.Win32.Networking.WinSock.IPPROTO_EGP -Windows.Win32.Networking.WinSock.IPPROTO_ESP -Windows.Win32.Networking.WinSock.IPPROTO_FRAGMENT -Windows.Win32.Networking.WinSock.IPPROTO_GGP -Windows.Win32.Networking.WinSock.IPPROTO_HOPOPTS -Windows.Win32.Networking.WinSock.IPPROTO_ICLFXBM -Windows.Win32.Networking.WinSock.IPPROTO_ICMP -Windows.Win32.Networking.WinSock.IPPROTO_ICMPV6 -Windows.Win32.Networking.WinSock.IPPROTO_IDP -Windows.Win32.Networking.WinSock.IPPROTO_IGMP -Windows.Win32.Networking.WinSock.IPPROTO_IGP -Windows.Win32.Networking.WinSock.IPPROTO_IP -Windows.Win32.Networking.WinSock.IPPROTO_IPV4 -Windows.Win32.Networking.WinSock.IPPROTO_IPV6 -Windows.Win32.Networking.WinSock.IPPROTO_L2TP -Windows.Win32.Networking.WinSock.IPPROTO_MAX -Windows.Win32.Networking.WinSock.IPPROTO_ND -Windows.Win32.Networking.WinSock.IPPROTO_NONE -Windows.Win32.Networking.WinSock.IPPROTO_PGM -Windows.Win32.Networking.WinSock.IPPROTO_PIM -Windows.Win32.Networking.WinSock.IPPROTO_PUP -Windows.Win32.Networking.WinSock.IPPROTO_RAW -Windows.Win32.Networking.WinSock.IPPROTO_RDP -Windows.Win32.Networking.WinSock.IPPROTO_RESERVED_IPSEC -Windows.Win32.Networking.WinSock.IPPROTO_RESERVED_IPSECOFFLOAD -Windows.Win32.Networking.WinSock.IPPROTO_RESERVED_MAX -Windows.Win32.Networking.WinSock.IPPROTO_RESERVED_RAW -Windows.Win32.Networking.WinSock.IPPROTO_RESERVED_WNV -Windows.Win32.Networking.WinSock.IPPROTO_RM -Windows.Win32.Networking.WinSock.IPPROTO_ROUTING -Windows.Win32.Networking.WinSock.IPPROTO_SCTP -Windows.Win32.Networking.WinSock.IPPROTO_ST -Windows.Win32.Networking.WinSock.IPPROTO_TCP -Windows.Win32.Networking.WinSock.IPPROTO_UDP -Windows.Win32.Networking.WinSock.IPV6_ADD_MEMBERSHIP -Windows.Win32.Networking.WinSock.IPV6_DROP_MEMBERSHIP -Windows.Win32.Networking.WinSock.IPV6_MREQ -Windows.Win32.Networking.WinSock.IPV6_MULTICAST_LOOP -Windows.Win32.Networking.WinSock.IPV6_V6ONLY -Windows.Win32.Networking.WinSock.LINGER -Windows.Win32.Networking.WinSock.listen -Windows.Win32.Networking.WinSock.LPWSAOVERLAPPED_COMPLETION_ROUTINE -Windows.Win32.Networking.WinSock.MSG_DONTROUTE -Windows.Win32.Networking.WinSock.MSG_OOB -Windows.Win32.Networking.WinSock.MSG_PEEK -Windows.Win32.Networking.WinSock.MSG_PUSH_IMMEDIATE -Windows.Win32.Networking.WinSock.MSG_WAITALL -Windows.Win32.Networking.WinSock.recv -Windows.Win32.Networking.WinSock.recvfrom -Windows.Win32.Networking.WinSock.SD_BOTH -Windows.Win32.Networking.WinSock.SD_RECEIVE -Windows.Win32.Networking.WinSock.SD_SEND -Windows.Win32.Networking.WinSock.select -Windows.Win32.Networking.WinSock.send -Windows.Win32.Networking.WinSock.SEND_RECV_FLAGS -Windows.Win32.Networking.WinSock.sendto -Windows.Win32.Networking.WinSock.setsockopt -Windows.Win32.Networking.WinSock.shutdown -Windows.Win32.Networking.WinSock.SO_BROADCAST -Windows.Win32.Networking.WinSock.SO_ERROR -Windows.Win32.Networking.WinSock.SO_LINGER -Windows.Win32.Networking.WinSock.SO_RCVTIMEO -Windows.Win32.Networking.WinSock.SO_SNDTIMEO -Windows.Win32.Networking.WinSock.SOCK_DGRAM -Windows.Win32.Networking.WinSock.SOCK_RAW -Windows.Win32.Networking.WinSock.SOCK_RDM -Windows.Win32.Networking.WinSock.SOCK_SEQPACKET -Windows.Win32.Networking.WinSock.SOCK_STREAM -Windows.Win32.Networking.WinSock.SOCKADDR -Windows.Win32.Networking.WinSock.SOCKADDR_UN -Windows.Win32.Networking.WinSock.SOCKET -Windows.Win32.Networking.WinSock.SOCKET_ERROR -Windows.Win32.Networking.WinSock.SOL_SOCKET -Windows.Win32.Networking.WinSock.TCP_NODELAY -Windows.Win32.Networking.WinSock.TIMEVAL -Windows.Win32.Networking.WinSock.WINSOCK_SHUTDOWN_HOW -Windows.Win32.Networking.WinSock.WINSOCK_SOCKET_TYPE -Windows.Win32.Networking.WinSock.WSA_E_CANCELLED -Windows.Win32.Networking.WinSock.WSA_E_NO_MORE -Windows.Win32.Networking.WinSock.WSA_ERROR -Windows.Win32.Networking.WinSock.WSA_FLAG_NO_HANDLE_INHERIT -Windows.Win32.Networking.WinSock.WSA_FLAG_OVERLAPPED -Windows.Win32.Networking.WinSock.WSA_INVALID_HANDLE -Windows.Win32.Networking.WinSock.WSA_INVALID_PARAMETER -Windows.Win32.Networking.WinSock.WSA_IO_INCOMPLETE -Windows.Win32.Networking.WinSock.WSA_IO_PENDING -Windows.Win32.Networking.WinSock.WSA_IPSEC_NAME_POLICY_ERROR -Windows.Win32.Networking.WinSock.WSA_NOT_ENOUGH_MEMORY -Windows.Win32.Networking.WinSock.WSA_OPERATION_ABORTED -Windows.Win32.Networking.WinSock.WSA_QOS_ADMISSION_FAILURE -Windows.Win32.Networking.WinSock.WSA_QOS_BAD_OBJECT -Windows.Win32.Networking.WinSock.WSA_QOS_BAD_STYLE -Windows.Win32.Networking.WinSock.WSA_QOS_EFILTERCOUNT -Windows.Win32.Networking.WinSock.WSA_QOS_EFILTERSTYLE -Windows.Win32.Networking.WinSock.WSA_QOS_EFILTERTYPE -Windows.Win32.Networking.WinSock.WSA_QOS_EFLOWCOUNT -Windows.Win32.Networking.WinSock.WSA_QOS_EFLOWDESC -Windows.Win32.Networking.WinSock.WSA_QOS_EFLOWSPEC -Windows.Win32.Networking.WinSock.WSA_QOS_EOBJLENGTH -Windows.Win32.Networking.WinSock.WSA_QOS_EPOLICYOBJ -Windows.Win32.Networking.WinSock.WSA_QOS_EPROVSPECBUF -Windows.Win32.Networking.WinSock.WSA_QOS_EPSFILTERSPEC -Windows.Win32.Networking.WinSock.WSA_QOS_EPSFLOWSPEC -Windows.Win32.Networking.WinSock.WSA_QOS_ESDMODEOBJ -Windows.Win32.Networking.WinSock.WSA_QOS_ESERVICETYPE -Windows.Win32.Networking.WinSock.WSA_QOS_ESHAPERATEOBJ -Windows.Win32.Networking.WinSock.WSA_QOS_EUNKOWNPSOBJ -Windows.Win32.Networking.WinSock.WSA_QOS_GENERIC_ERROR -Windows.Win32.Networking.WinSock.WSA_QOS_NO_RECEIVERS -Windows.Win32.Networking.WinSock.WSA_QOS_NO_SENDERS -Windows.Win32.Networking.WinSock.WSA_QOS_POLICY_FAILURE -Windows.Win32.Networking.WinSock.WSA_QOS_RECEIVERS -Windows.Win32.Networking.WinSock.WSA_QOS_REQUEST_CONFIRMED -Windows.Win32.Networking.WinSock.WSA_QOS_RESERVED_PETYPE -Windows.Win32.Networking.WinSock.WSA_QOS_SENDERS -Windows.Win32.Networking.WinSock.WSA_QOS_TRAFFIC_CTRL_ERROR -Windows.Win32.Networking.WinSock.WSA_SECURE_HOST_NOT_FOUND -Windows.Win32.Networking.WinSock.WSA_WAIT_EVENT_0 -Windows.Win32.Networking.WinSock.WSA_WAIT_IO_COMPLETION -Windows.Win32.Networking.WinSock.WSABASEERR -Windows.Win32.Networking.WinSock.WSABUF -Windows.Win32.Networking.WinSock.WSACleanup -Windows.Win32.Networking.WinSock.WSADATA -Windows.Win32.Networking.WinSock.WSADuplicateSocketW -Windows.Win32.Networking.WinSock.WSAEACCES -Windows.Win32.Networking.WinSock.WSAEADDRINUSE -Windows.Win32.Networking.WinSock.WSAEADDRNOTAVAIL -Windows.Win32.Networking.WinSock.WSAEAFNOSUPPORT -Windows.Win32.Networking.WinSock.WSAEALREADY -Windows.Win32.Networking.WinSock.WSAEBADF -Windows.Win32.Networking.WinSock.WSAECANCELLED -Windows.Win32.Networking.WinSock.WSAECONNABORTED -Windows.Win32.Networking.WinSock.WSAECONNREFUSED -Windows.Win32.Networking.WinSock.WSAECONNRESET -Windows.Win32.Networking.WinSock.WSAEDESTADDRREQ -Windows.Win32.Networking.WinSock.WSAEDISCON -Windows.Win32.Networking.WinSock.WSAEDQUOT -Windows.Win32.Networking.WinSock.WSAEFAULT -Windows.Win32.Networking.WinSock.WSAEHOSTDOWN -Windows.Win32.Networking.WinSock.WSAEHOSTUNREACH -Windows.Win32.Networking.WinSock.WSAEINPROGRESS -Windows.Win32.Networking.WinSock.WSAEINTR -Windows.Win32.Networking.WinSock.WSAEINVAL -Windows.Win32.Networking.WinSock.WSAEINVALIDPROCTABLE -Windows.Win32.Networking.WinSock.WSAEINVALIDPROVIDER -Windows.Win32.Networking.WinSock.WSAEISCONN -Windows.Win32.Networking.WinSock.WSAELOOP -Windows.Win32.Networking.WinSock.WSAEMFILE -Windows.Win32.Networking.WinSock.WSAEMSGSIZE -Windows.Win32.Networking.WinSock.WSAENAMETOOLONG -Windows.Win32.Networking.WinSock.WSAENETDOWN -Windows.Win32.Networking.WinSock.WSAENETRESET -Windows.Win32.Networking.WinSock.WSAENETUNREACH -Windows.Win32.Networking.WinSock.WSAENOBUFS -Windows.Win32.Networking.WinSock.WSAENOMORE -Windows.Win32.Networking.WinSock.WSAENOPROTOOPT -Windows.Win32.Networking.WinSock.WSAENOTCONN -Windows.Win32.Networking.WinSock.WSAENOTEMPTY -Windows.Win32.Networking.WinSock.WSAENOTSOCK -Windows.Win32.Networking.WinSock.WSAEOPNOTSUPP -Windows.Win32.Networking.WinSock.WSAEPFNOSUPPORT -Windows.Win32.Networking.WinSock.WSAEPROCLIM -Windows.Win32.Networking.WinSock.WSAEPROTONOSUPPORT -Windows.Win32.Networking.WinSock.WSAEPROTOTYPE -Windows.Win32.Networking.WinSock.WSAEPROVIDERFAILEDINIT -Windows.Win32.Networking.WinSock.WSAEREFUSED -Windows.Win32.Networking.WinSock.WSAEREMOTE -Windows.Win32.Networking.WinSock.WSAESHUTDOWN -Windows.Win32.Networking.WinSock.WSAESOCKTNOSUPPORT -Windows.Win32.Networking.WinSock.WSAESTALE -Windows.Win32.Networking.WinSock.WSAETIMEDOUT -Windows.Win32.Networking.WinSock.WSAETOOMANYREFS -Windows.Win32.Networking.WinSock.WSAEUSERS -Windows.Win32.Networking.WinSock.WSAEWOULDBLOCK -Windows.Win32.Networking.WinSock.WSAGetLastError -Windows.Win32.Networking.WinSock.WSAHOST_NOT_FOUND -Windows.Win32.Networking.WinSock.WSANO_DATA -Windows.Win32.Networking.WinSock.WSANO_RECOVERY -Windows.Win32.Networking.WinSock.WSANOTINITIALISED -Windows.Win32.Networking.WinSock.WSAPROTOCOL_INFOW -Windows.Win32.Networking.WinSock.WSAPROTOCOLCHAIN -Windows.Win32.Networking.WinSock.WSARecv -Windows.Win32.Networking.WinSock.WSASend -Windows.Win32.Networking.WinSock.WSASERVICE_NOT_FOUND -Windows.Win32.Networking.WinSock.WSASocketW -Windows.Win32.Networking.WinSock.WSASYSCALLFAILURE -Windows.Win32.Networking.WinSock.WSASYSNOTREADY -Windows.Win32.Networking.WinSock.WSATRY_AGAIN -Windows.Win32.Networking.WinSock.WSATYPE_NOT_FOUND -Windows.Win32.Networking.WinSock.WSAVERNOTSUPPORTED -Windows.Win32.Security.Authentication.Identity.RtlGenRandom -Windows.Win32.Security.SECURITY_ATTRIBUTES -Windows.Win32.Security.TOKEN_ACCESS_MASK -Windows.Win32.Security.TOKEN_ACCESS_PSEUDO_HANDLE -Windows.Win32.Security.TOKEN_ACCESS_PSEUDO_HANDLE_WIN8 -Windows.Win32.Security.TOKEN_ACCESS_SYSTEM_SECURITY -Windows.Win32.Security.TOKEN_ADJUST_DEFAULT -Windows.Win32.Security.TOKEN_ADJUST_GROUPS -Windows.Win32.Security.TOKEN_ADJUST_PRIVILEGES -Windows.Win32.Security.TOKEN_ADJUST_SESSIONID -Windows.Win32.Security.TOKEN_ALL_ACCESS -Windows.Win32.Security.TOKEN_ASSIGN_PRIMARY -Windows.Win32.Security.TOKEN_DELETE -Windows.Win32.Security.TOKEN_DUPLICATE -Windows.Win32.Security.TOKEN_EXECUTE -Windows.Win32.Security.TOKEN_IMPERSONATE -Windows.Win32.Security.TOKEN_QUERY -Windows.Win32.Security.TOKEN_QUERY_SOURCE -Windows.Win32.Security.TOKEN_READ -Windows.Win32.Security.TOKEN_READ_CONTROL -Windows.Win32.Security.TOKEN_TRUST_CONSTRAINT_MASK -Windows.Win32.Security.TOKEN_WRITE -Windows.Win32.Security.TOKEN_WRITE_DAC -Windows.Win32.Security.TOKEN_WRITE_OWNER -Windows.Win32.Storage.FileSystem.BY_HANDLE_FILE_INFORMATION -Windows.Win32.Storage.FileSystem.CALLBACK_CHUNK_FINISHED -Windows.Win32.Storage.FileSystem.CALLBACK_STREAM_SWITCH -Windows.Win32.Storage.FileSystem.CopyFileExW -Windows.Win32.Storage.FileSystem.CREATE_ALWAYS -Windows.Win32.Storage.FileSystem.CREATE_NEW -Windows.Win32.Storage.FileSystem.CreateDirectoryW -Windows.Win32.Storage.FileSystem.CreateFileW -Windows.Win32.Storage.FileSystem.CreateHardLinkW -Windows.Win32.Storage.FileSystem.CreateSymbolicLinkW -Windows.Win32.Storage.FileSystem.DELETE -Windows.Win32.Storage.FileSystem.DeleteFileW -Windows.Win32.Storage.FileSystem.FILE_ACCESS_RIGHTS -Windows.Win32.Storage.FileSystem.FILE_ADD_FILE -Windows.Win32.Storage.FileSystem.FILE_ADD_SUBDIRECTORY -Windows.Win32.Storage.FileSystem.FILE_ALL_ACCESS -Windows.Win32.Storage.FileSystem.FILE_ALLOCATION_INFO -Windows.Win32.Storage.FileSystem.FILE_APPEND_DATA -Windows.Win32.Storage.FileSystem.FILE_ATTRIBUTE_ARCHIVE -Windows.Win32.Storage.FileSystem.FILE_ATTRIBUTE_COMPRESSED -Windows.Win32.Storage.FileSystem.FILE_ATTRIBUTE_DEVICE -Windows.Win32.Storage.FileSystem.FILE_ATTRIBUTE_DIRECTORY -Windows.Win32.Storage.FileSystem.FILE_ATTRIBUTE_EA -Windows.Win32.Storage.FileSystem.FILE_ATTRIBUTE_ENCRYPTED -Windows.Win32.Storage.FileSystem.FILE_ATTRIBUTE_HIDDEN -Windows.Win32.Storage.FileSystem.FILE_ATTRIBUTE_INTEGRITY_STREAM -Windows.Win32.Storage.FileSystem.FILE_ATTRIBUTE_NO_SCRUB_DATA -Windows.Win32.Storage.FileSystem.FILE_ATTRIBUTE_NORMAL -Windows.Win32.Storage.FileSystem.FILE_ATTRIBUTE_NOT_CONTENT_INDEXED -Windows.Win32.Storage.FileSystem.FILE_ATTRIBUTE_OFFLINE -Windows.Win32.Storage.FileSystem.FILE_ATTRIBUTE_PINNED -Windows.Win32.Storage.FileSystem.FILE_ATTRIBUTE_READONLY -Windows.Win32.Storage.FileSystem.FILE_ATTRIBUTE_RECALL_ON_DATA_ACCESS -Windows.Win32.Storage.FileSystem.FILE_ATTRIBUTE_RECALL_ON_OPEN -Windows.Win32.Storage.FileSystem.FILE_ATTRIBUTE_REPARSE_POINT -Windows.Win32.Storage.FileSystem.FILE_ATTRIBUTE_SPARSE_FILE -Windows.Win32.Storage.FileSystem.FILE_ATTRIBUTE_SYSTEM -Windows.Win32.Storage.FileSystem.FILE_ATTRIBUTE_TAG_INFO -Windows.Win32.Storage.FileSystem.FILE_ATTRIBUTE_TEMPORARY -Windows.Win32.Storage.FileSystem.FILE_ATTRIBUTE_UNPINNED -Windows.Win32.Storage.FileSystem.FILE_ATTRIBUTE_VIRTUAL -Windows.Win32.Storage.FileSystem.FILE_BASIC_INFO -Windows.Win32.Storage.FileSystem.FILE_BEGIN -Windows.Win32.Storage.FileSystem.FILE_CREATE_PIPE_INSTANCE -Windows.Win32.Storage.FileSystem.FILE_CREATION_DISPOSITION -Windows.Win32.Storage.FileSystem.FILE_CURRENT -Windows.Win32.Storage.FileSystem.FILE_DELETE_CHILD -Windows.Win32.Storage.FileSystem.FILE_DISPOSITION_FLAG_DELETE -Windows.Win32.Storage.FileSystem.FILE_DISPOSITION_FLAG_DO_NOT_DELETE -Windows.Win32.Storage.FileSystem.FILE_DISPOSITION_FLAG_FORCE_IMAGE_SECTION_CHECK -Windows.Win32.Storage.FileSystem.FILE_DISPOSITION_FLAG_IGNORE_READONLY_ATTRIBUTE -Windows.Win32.Storage.FileSystem.FILE_DISPOSITION_FLAG_ON_CLOSE -Windows.Win32.Storage.FileSystem.FILE_DISPOSITION_FLAG_POSIX_SEMANTICS -Windows.Win32.Storage.FileSystem.FILE_DISPOSITION_INFO -Windows.Win32.Storage.FileSystem.FILE_DISPOSITION_INFO_EX -Windows.Win32.Storage.FileSystem.FILE_DISPOSITION_INFO_EX_FLAGS -Windows.Win32.Storage.FileSystem.FILE_END -Windows.Win32.Storage.FileSystem.FILE_END_OF_FILE_INFO -Windows.Win32.Storage.FileSystem.FILE_EXECUTE -Windows.Win32.Storage.FileSystem.FILE_FLAG_BACKUP_SEMANTICS -Windows.Win32.Storage.FileSystem.FILE_FLAG_DELETE_ON_CLOSE -Windows.Win32.Storage.FileSystem.FILE_FLAG_FIRST_PIPE_INSTANCE -Windows.Win32.Storage.FileSystem.FILE_FLAG_NO_BUFFERING -Windows.Win32.Storage.FileSystem.FILE_FLAG_OPEN_NO_RECALL -Windows.Win32.Storage.FileSystem.FILE_FLAG_OPEN_REPARSE_POINT -Windows.Win32.Storage.FileSystem.FILE_FLAG_OVERLAPPED -Windows.Win32.Storage.FileSystem.FILE_FLAG_POSIX_SEMANTICS -Windows.Win32.Storage.FileSystem.FILE_FLAG_RANDOM_ACCESS -Windows.Win32.Storage.FileSystem.FILE_FLAG_SEQUENTIAL_SCAN -Windows.Win32.Storage.FileSystem.FILE_FLAG_SESSION_AWARE -Windows.Win32.Storage.FileSystem.FILE_FLAG_WRITE_THROUGH -Windows.Win32.Storage.FileSystem.FILE_FLAGS_AND_ATTRIBUTES -Windows.Win32.Storage.FileSystem.FILE_GENERIC_EXECUTE -Windows.Win32.Storage.FileSystem.FILE_GENERIC_READ -Windows.Win32.Storage.FileSystem.FILE_GENERIC_WRITE -Windows.Win32.Storage.FileSystem.FILE_ID_BOTH_DIR_INFO -Windows.Win32.Storage.FileSystem.FILE_INFO_BY_HANDLE_CLASS -Windows.Win32.Storage.FileSystem.FILE_IO_PRIORITY_HINT_INFO -Windows.Win32.Storage.FileSystem.FILE_LIST_DIRECTORY -Windows.Win32.Storage.FileSystem.FILE_NAME_NORMALIZED -Windows.Win32.Storage.FileSystem.FILE_NAME_OPENED -Windows.Win32.Storage.FileSystem.FILE_READ_ATTRIBUTES -Windows.Win32.Storage.FileSystem.FILE_READ_DATA -Windows.Win32.Storage.FileSystem.FILE_READ_EA -Windows.Win32.Storage.FileSystem.FILE_SHARE_DELETE -Windows.Win32.Storage.FileSystem.FILE_SHARE_MODE -Windows.Win32.Storage.FileSystem.FILE_SHARE_NONE -Windows.Win32.Storage.FileSystem.FILE_SHARE_READ -Windows.Win32.Storage.FileSystem.FILE_SHARE_WRITE -Windows.Win32.Storage.FileSystem.FILE_STANDARD_INFO -Windows.Win32.Storage.FileSystem.FILE_TRAVERSE -Windows.Win32.Storage.FileSystem.FILE_TYPE -Windows.Win32.Storage.FileSystem.FILE_TYPE_CHAR -Windows.Win32.Storage.FileSystem.FILE_TYPE_DISK -Windows.Win32.Storage.FileSystem.FILE_TYPE_PIPE -Windows.Win32.Storage.FileSystem.FILE_TYPE_REMOTE -Windows.Win32.Storage.FileSystem.FILE_TYPE_UNKNOWN -Windows.Win32.Storage.FileSystem.FILE_WRITE_ATTRIBUTES -Windows.Win32.Storage.FileSystem.FILE_WRITE_DATA -Windows.Win32.Storage.FileSystem.FILE_WRITE_EA -Windows.Win32.Storage.FileSystem.FileAlignmentInfo -Windows.Win32.Storage.FileSystem.FileAllocationInfo -Windows.Win32.Storage.FileSystem.FileAttributeTagInfo -Windows.Win32.Storage.FileSystem.FileBasicInfo -Windows.Win32.Storage.FileSystem.FileCaseSensitiveInfo -Windows.Win32.Storage.FileSystem.FileCompressionInfo -Windows.Win32.Storage.FileSystem.FileDispositionInfo -Windows.Win32.Storage.FileSystem.FileDispositionInfoEx -Windows.Win32.Storage.FileSystem.FileEndOfFileInfo -Windows.Win32.Storage.FileSystem.FileFullDirectoryInfo -Windows.Win32.Storage.FileSystem.FileFullDirectoryRestartInfo -Windows.Win32.Storage.FileSystem.FileIdBothDirectoryInfo -Windows.Win32.Storage.FileSystem.FileIdBothDirectoryRestartInfo -Windows.Win32.Storage.FileSystem.FileIdExtdDirectoryInfo -Windows.Win32.Storage.FileSystem.FileIdExtdDirectoryRestartInfo -Windows.Win32.Storage.FileSystem.FileIdInfo -Windows.Win32.Storage.FileSystem.FileIoPriorityHintInfo -Windows.Win32.Storage.FileSystem.FileNameInfo -Windows.Win32.Storage.FileSystem.FileNormalizedNameInfo -Windows.Win32.Storage.FileSystem.FileRemoteProtocolInfo -Windows.Win32.Storage.FileSystem.FileRenameInfo -Windows.Win32.Storage.FileSystem.FileRenameInfoEx -Windows.Win32.Storage.FileSystem.FileStandardInfo -Windows.Win32.Storage.FileSystem.FileStorageInfo -Windows.Win32.Storage.FileSystem.FileStreamInfo -Windows.Win32.Storage.FileSystem.FindClose -Windows.Win32.Storage.FileSystem.FindFirstFileW -Windows.Win32.Storage.FileSystem.FindNextFileW -Windows.Win32.Storage.FileSystem.FlushFileBuffers -Windows.Win32.Storage.FileSystem.GetFileAttributesW -Windows.Win32.Storage.FileSystem.GetFileInformationByHandle -Windows.Win32.Storage.FileSystem.GetFileInformationByHandleEx -Windows.Win32.Storage.FileSystem.GetFileType -Windows.Win32.Storage.FileSystem.GETFINALPATHNAMEBYHANDLE_FLAGS -Windows.Win32.Storage.FileSystem.GetFinalPathNameByHandleW -Windows.Win32.Storage.FileSystem.GetFullPathNameW -Windows.Win32.Storage.FileSystem.GetTempPathW -Windows.Win32.Storage.FileSystem.INVALID_FILE_ATTRIBUTES -Windows.Win32.Storage.FileSystem.LPPROGRESS_ROUTINE -Windows.Win32.Storage.FileSystem.LPPROGRESS_ROUTINE_CALLBACK_REASON -Windows.Win32.Storage.FileSystem.MAXIMUM_REPARSE_DATA_BUFFER_SIZE -Windows.Win32.Storage.FileSystem.MaximumFileInfoByHandleClass -Windows.Win32.Storage.FileSystem.MOVE_FILE_FLAGS -Windows.Win32.Storage.FileSystem.MOVEFILE_COPY_ALLOWED -Windows.Win32.Storage.FileSystem.MOVEFILE_CREATE_HARDLINK -Windows.Win32.Storage.FileSystem.MOVEFILE_DELAY_UNTIL_REBOOT -Windows.Win32.Storage.FileSystem.MOVEFILE_FAIL_IF_NOT_TRACKABLE -Windows.Win32.Storage.FileSystem.MOVEFILE_REPLACE_EXISTING -Windows.Win32.Storage.FileSystem.MOVEFILE_WRITE_THROUGH -Windows.Win32.Storage.FileSystem.MoveFileExW -Windows.Win32.Storage.FileSystem.OPEN_ALWAYS -Windows.Win32.Storage.FileSystem.OPEN_EXISTING -Windows.Win32.Storage.FileSystem.PIPE_ACCESS_DUPLEX -Windows.Win32.Storage.FileSystem.PIPE_ACCESS_INBOUND -Windows.Win32.Storage.FileSystem.PIPE_ACCESS_OUTBOUND -Windows.Win32.Storage.FileSystem.READ_CONTROL -Windows.Win32.Storage.FileSystem.ReadFile -Windows.Win32.Storage.FileSystem.ReadFileEx -Windows.Win32.Storage.FileSystem.RemoveDirectoryW -Windows.Win32.Storage.FileSystem.SECURITY_ANONYMOUS -Windows.Win32.Storage.FileSystem.SECURITY_CONTEXT_TRACKING -Windows.Win32.Storage.FileSystem.SECURITY_DELEGATION -Windows.Win32.Storage.FileSystem.SECURITY_EFFECTIVE_ONLY -Windows.Win32.Storage.FileSystem.SECURITY_IDENTIFICATION -Windows.Win32.Storage.FileSystem.SECURITY_IMPERSONATION -Windows.Win32.Storage.FileSystem.SECURITY_SQOS_PRESENT -Windows.Win32.Storage.FileSystem.SECURITY_VALID_SQOS_FLAGS -Windows.Win32.Storage.FileSystem.SET_FILE_POINTER_MOVE_METHOD -Windows.Win32.Storage.FileSystem.SetFileAttributesW -Windows.Win32.Storage.FileSystem.SetFileInformationByHandle -Windows.Win32.Storage.FileSystem.SetFilePointerEx -Windows.Win32.Storage.FileSystem.SetFileTime -Windows.Win32.Storage.FileSystem.SPECIFIC_RIGHTS_ALL -Windows.Win32.Storage.FileSystem.STANDARD_RIGHTS_ALL -Windows.Win32.Storage.FileSystem.STANDARD_RIGHTS_EXECUTE -Windows.Win32.Storage.FileSystem.STANDARD_RIGHTS_READ -Windows.Win32.Storage.FileSystem.STANDARD_RIGHTS_REQUIRED -Windows.Win32.Storage.FileSystem.STANDARD_RIGHTS_WRITE -Windows.Win32.Storage.FileSystem.SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE -Windows.Win32.Storage.FileSystem.SYMBOLIC_LINK_FLAG_DIRECTORY -Windows.Win32.Storage.FileSystem.SYMBOLIC_LINK_FLAGS -Windows.Win32.Storage.FileSystem.SYNCHRONIZE -Windows.Win32.Storage.FileSystem.TRUNCATE_EXISTING -Windows.Win32.Storage.FileSystem.VOLUME_NAME_DOS -Windows.Win32.Storage.FileSystem.VOLUME_NAME_GUID -Windows.Win32.Storage.FileSystem.VOLUME_NAME_NONE -Windows.Win32.Storage.FileSystem.WIN32_FIND_DATAW -Windows.Win32.Storage.FileSystem.WRITE_DAC -Windows.Win32.Storage.FileSystem.WRITE_OWNER -Windows.Win32.Storage.FileSystem.WriteFileEx -Windows.Win32.System.Console.CONSOLE_MODE -Windows.Win32.System.Console.CONSOLE_READCONSOLE_CONTROL -Windows.Win32.System.Console.DISABLE_NEWLINE_AUTO_RETURN -Windows.Win32.System.Console.ENABLE_AUTO_POSITION -Windows.Win32.System.Console.ENABLE_ECHO_INPUT -Windows.Win32.System.Console.ENABLE_EXTENDED_FLAGS -Windows.Win32.System.Console.ENABLE_INSERT_MODE -Windows.Win32.System.Console.ENABLE_LINE_INPUT -Windows.Win32.System.Console.ENABLE_LVB_GRID_WORLDWIDE -Windows.Win32.System.Console.ENABLE_MOUSE_INPUT -Windows.Win32.System.Console.ENABLE_PROCESSED_INPUT -Windows.Win32.System.Console.ENABLE_PROCESSED_OUTPUT -Windows.Win32.System.Console.ENABLE_QUICK_EDIT_MODE -Windows.Win32.System.Console.ENABLE_VIRTUAL_TERMINAL_INPUT -Windows.Win32.System.Console.ENABLE_VIRTUAL_TERMINAL_PROCESSING -Windows.Win32.System.Console.ENABLE_WINDOW_INPUT -Windows.Win32.System.Console.ENABLE_WRAP_AT_EOL_OUTPUT -Windows.Win32.System.Console.GetConsoleMode -Windows.Win32.System.Console.GetStdHandle -Windows.Win32.System.Console.ReadConsoleW -Windows.Win32.System.Console.STD_ERROR_HANDLE -Windows.Win32.System.Console.STD_HANDLE -Windows.Win32.System.Console.STD_INPUT_HANDLE -Windows.Win32.System.Console.STD_OUTPUT_HANDLE -Windows.Win32.System.Console.WriteConsoleW -Windows.Win32.System.Diagnostics.Debug.ARM64_NT_NEON128 -Windows.Win32.System.Diagnostics.Debug.CONTEXT -Windows.Win32.System.Diagnostics.Debug.EXCEPTION_RECORD -Windows.Win32.System.Diagnostics.Debug.FACILITY_CODE -Windows.Win32.System.Diagnostics.Debug.FACILITY_NT_BIT -Windows.Win32.System.Diagnostics.Debug.FORMAT_MESSAGE_ALLOCATE_BUFFER -Windows.Win32.System.Diagnostics.Debug.FORMAT_MESSAGE_ARGUMENT_ARRAY -Windows.Win32.System.Diagnostics.Debug.FORMAT_MESSAGE_FROM_HMODULE -Windows.Win32.System.Diagnostics.Debug.FORMAT_MESSAGE_FROM_STRING -Windows.Win32.System.Diagnostics.Debug.FORMAT_MESSAGE_FROM_SYSTEM -Windows.Win32.System.Diagnostics.Debug.FORMAT_MESSAGE_IGNORE_INSERTS -Windows.Win32.System.Diagnostics.Debug.FORMAT_MESSAGE_OPTIONS -Windows.Win32.System.Diagnostics.Debug.FormatMessageW -Windows.Win32.System.Diagnostics.Debug.M128A -Windows.Win32.System.Diagnostics.Debug.XSAVE_FORMAT -Windows.Win32.System.Environment.FreeEnvironmentStringsW -Windows.Win32.System.Environment.GetCommandLineW -Windows.Win32.System.Environment.GetCurrentDirectoryW -Windows.Win32.System.Environment.GetEnvironmentStringsW -Windows.Win32.System.Environment.GetEnvironmentVariableW -Windows.Win32.System.Environment.SetCurrentDirectoryW -Windows.Win32.System.Environment.SetEnvironmentVariableW -Windows.Win32.System.IO.CancelIo -Windows.Win32.System.IO.DeviceIoControl -Windows.Win32.System.IO.GetOverlappedResult -Windows.Win32.System.IO.LPOVERLAPPED_COMPLETION_ROUTINE -Windows.Win32.System.IO.OVERLAPPED -Windows.Win32.System.Ioctl.FSCTL_GET_REPARSE_POINT -Windows.Win32.System.Ioctl.FSCTL_SET_REPARSE_POINT -Windows.Win32.System.Kernel.EXCEPTION_DISPOSITION -Windows.Win32.System.Kernel.ExceptionCollidedUnwind -Windows.Win32.System.Kernel.ExceptionContinueExecution -Windows.Win32.System.Kernel.ExceptionContinueSearch -Windows.Win32.System.Kernel.ExceptionNestedException -Windows.Win32.System.Kernel.FLOATING_SAVE_AREA -Windows.Win32.System.Kernel.OBJ_DONT_REPARSE -Windows.Win32.System.LibraryLoader.GetModuleFileNameW -Windows.Win32.System.LibraryLoader.GetModuleHandleA -Windows.Win32.System.LibraryLoader.GetModuleHandleW -Windows.Win32.System.LibraryLoader.GetProcAddress -Windows.Win32.System.Performance.QueryPerformanceCounter -Windows.Win32.System.Performance.QueryPerformanceFrequency -Windows.Win32.System.Pipes.CreateNamedPipeW -Windows.Win32.System.Pipes.NAMED_PIPE_MODE -Windows.Win32.System.Pipes.PIPE_ACCEPT_REMOTE_CLIENTS -Windows.Win32.System.Pipes.PIPE_CLIENT_END -Windows.Win32.System.Pipes.PIPE_NOWAIT -Windows.Win32.System.Pipes.PIPE_READMODE_BYTE -Windows.Win32.System.Pipes.PIPE_READMODE_MESSAGE -Windows.Win32.System.Pipes.PIPE_REJECT_REMOTE_CLIENTS -Windows.Win32.System.Pipes.PIPE_SERVER_END -Windows.Win32.System.Pipes.PIPE_TYPE_BYTE -Windows.Win32.System.Pipes.PIPE_TYPE_MESSAGE -Windows.Win32.System.Pipes.PIPE_WAIT -Windows.Win32.System.SystemInformation.GetSystemDirectoryW -Windows.Win32.System.SystemInformation.GetSystemInfo -Windows.Win32.System.SystemInformation.GetSystemTimeAsFileTime -Windows.Win32.System.SystemInformation.GetSystemTimePreciseAsFileTime -Windows.Win32.System.SystemInformation.GetWindowsDirectoryW -Windows.Win32.System.SystemInformation.PROCESSOR_ARCHITECTURE -Windows.Win32.System.SystemInformation.SYSTEM_INFO -Windows.Win32.System.SystemServices.DLL_PROCESS_DETACH -Windows.Win32.System.SystemServices.DLL_THREAD_DETACH -Windows.Win32.System.SystemServices.EXCEPTION_MAXIMUM_PARAMETERS -Windows.Win32.System.SystemServices.FAST_FAIL_FATAL_APP_EXIT -Windows.Win32.System.SystemServices.IO_REPARSE_TAG_MOUNT_POINT -Windows.Win32.System.SystemServices.IO_REPARSE_TAG_SYMLINK -Windows.Win32.System.Threading.ABOVE_NORMAL_PRIORITY_CLASS -Windows.Win32.System.Threading.AcquireSRWLockExclusive -Windows.Win32.System.Threading.AcquireSRWLockShared -Windows.Win32.System.Threading.ALL_PROCESSOR_GROUPS -Windows.Win32.System.Threading.BELOW_NORMAL_PRIORITY_CLASS -Windows.Win32.System.Threading.CREATE_BREAKAWAY_FROM_JOB -Windows.Win32.System.Threading.CREATE_DEFAULT_ERROR_MODE -Windows.Win32.System.Threading.CREATE_FORCEDOS -Windows.Win32.System.Threading.CREATE_IGNORE_SYSTEM_DEFAULT -Windows.Win32.System.Threading.CREATE_NEW_CONSOLE -Windows.Win32.System.Threading.CREATE_NEW_PROCESS_GROUP -Windows.Win32.System.Threading.CREATE_NO_WINDOW -Windows.Win32.System.Threading.CREATE_PRESERVE_CODE_AUTHZ_LEVEL -Windows.Win32.System.Threading.CREATE_PROTECTED_PROCESS -Windows.Win32.System.Threading.CREATE_SECURE_PROCESS -Windows.Win32.System.Threading.CREATE_SEPARATE_WOW_VDM -Windows.Win32.System.Threading.CREATE_SHARED_WOW_VDM -Windows.Win32.System.Threading.CREATE_SUSPENDED -Windows.Win32.System.Threading.CREATE_UNICODE_ENVIRONMENT -Windows.Win32.System.Threading.CREATE_WAITABLE_TIMER_HIGH_RESOLUTION -Windows.Win32.System.Threading.CREATE_WAITABLE_TIMER_MANUAL_RESET -Windows.Win32.System.Threading.CreateEventW -Windows.Win32.System.Threading.CreateProcessW -Windows.Win32.System.Threading.CreateThread -Windows.Win32.System.Threading.CreateWaitableTimerExW -Windows.Win32.System.Threading.DEBUG_ONLY_THIS_PROCESS -Windows.Win32.System.Threading.DEBUG_PROCESS -Windows.Win32.System.Threading.DeleteProcThreadAttributeList -Windows.Win32.System.Threading.DETACHED_PROCESS -Windows.Win32.System.Threading.ExitProcess -Windows.Win32.System.Threading.EXTENDED_STARTUPINFO_PRESENT -Windows.Win32.System.Threading.GetActiveProcessorCount -Windows.Win32.System.Threading.GetCurrentProcess -Windows.Win32.System.Threading.GetCurrentProcessId -Windows.Win32.System.Threading.GetCurrentThread -Windows.Win32.System.Threading.GetExitCodeProcess -Windows.Win32.System.Threading.GetProcessId -Windows.Win32.System.Threading.HIGH_PRIORITY_CLASS -Windows.Win32.System.Threading.IDLE_PRIORITY_CLASS -Windows.Win32.System.Threading.INFINITE -Windows.Win32.System.Threading.INHERIT_CALLER_PRIORITY -Windows.Win32.System.Threading.INHERIT_PARENT_AFFINITY -Windows.Win32.System.Threading.INIT_ONCE_INIT_FAILED -Windows.Win32.System.Threading.InitializeProcThreadAttributeList -Windows.Win32.System.Threading.InitOnceBeginInitialize -Windows.Win32.System.Threading.InitOnceComplete -Windows.Win32.System.Threading.LPPROC_THREAD_ATTRIBUTE_LIST -Windows.Win32.System.Threading.LPTHREAD_START_ROUTINE -Windows.Win32.System.Threading.NORMAL_PRIORITY_CLASS -Windows.Win32.System.Threading.OpenProcessToken -Windows.Win32.System.Threading.PROCESS_CREATION_FLAGS -Windows.Win32.System.Threading.PROCESS_INFORMATION -Windows.Win32.System.Threading.PROCESS_MODE_BACKGROUND_BEGIN -Windows.Win32.System.Threading.PROCESS_MODE_BACKGROUND_END -Windows.Win32.System.Threading.PROFILE_KERNEL -Windows.Win32.System.Threading.PROFILE_SERVER -Windows.Win32.System.Threading.PROFILE_USER -Windows.Win32.System.Threading.REALTIME_PRIORITY_CLASS -Windows.Win32.System.Threading.ReleaseSRWLockExclusive -Windows.Win32.System.Threading.ReleaseSRWLockShared -Windows.Win32.System.Threading.SetThreadStackGuarantee -Windows.Win32.System.Threading.SetWaitableTimer -Windows.Win32.System.Threading.Sleep -Windows.Win32.System.Threading.SleepConditionVariableSRW -Windows.Win32.System.Threading.SleepEx -Windows.Win32.System.Threading.STACK_SIZE_PARAM_IS_A_RESERVATION -Windows.Win32.System.Threading.STARTF_FORCEOFFFEEDBACK -Windows.Win32.System.Threading.STARTF_FORCEONFEEDBACK -Windows.Win32.System.Threading.STARTF_PREVENTPINNING -Windows.Win32.System.Threading.STARTF_RUNFULLSCREEN -Windows.Win32.System.Threading.STARTF_TITLEISAPPID -Windows.Win32.System.Threading.STARTF_TITLEISLINKNAME -Windows.Win32.System.Threading.STARTF_UNTRUSTEDSOURCE -Windows.Win32.System.Threading.STARTF_USECOUNTCHARS -Windows.Win32.System.Threading.STARTF_USEFILLATTRIBUTE -Windows.Win32.System.Threading.STARTF_USEHOTKEY -Windows.Win32.System.Threading.STARTF_USEPOSITION -Windows.Win32.System.Threading.STARTF_USESHOWWINDOW -Windows.Win32.System.Threading.STARTF_USESIZE -Windows.Win32.System.Threading.STARTF_USESTDHANDLES -Windows.Win32.System.Threading.STARTUPINFOEXW -Windows.Win32.System.Threading.STARTUPINFOW -Windows.Win32.System.Threading.STARTUPINFOW_FLAGS -Windows.Win32.System.Threading.SwitchToThread -Windows.Win32.System.Threading.TerminateProcess -Windows.Win32.System.Threading.THREAD_CREATE_RUN_IMMEDIATELY -Windows.Win32.System.Threading.THREAD_CREATE_SUSPENDED -Windows.Win32.System.Threading.THREAD_CREATION_FLAGS -Windows.Win32.System.Threading.TIMER_ALL_ACCESS -Windows.Win32.System.Threading.TIMER_MODIFY_STATE -Windows.Win32.System.Threading.TLS_OUT_OF_INDEXES -Windows.Win32.System.Threading.TlsAlloc -Windows.Win32.System.Threading.TlsFree -Windows.Win32.System.Threading.TlsGetValue -Windows.Win32.System.Threading.TlsSetValue -Windows.Win32.System.Threading.TryAcquireSRWLockExclusive -Windows.Win32.System.Threading.TryAcquireSRWLockShared -Windows.Win32.System.Threading.UpdateProcThreadAttribute -Windows.Win32.System.Threading.WaitForMultipleObjects -Windows.Win32.System.Threading.WaitForSingleObject -Windows.Win32.System.Threading.WakeAllConditionVariable -Windows.Win32.System.Threading.WakeConditionVariable -Windows.Win32.System.WindowsProgramming.PROGRESS_CONTINUE -Windows.Win32.UI.Shell.GetUserProfileDirectoryW diff --git a/library/std/src/sys/pal/windows/c/windows_sys.rs b/library/std/src/sys/pal/windows/c/windows_sys.rs deleted file mode 100644 index 1da8871ae44eb..0000000000000 --- a/library/std/src/sys/pal/windows/c/windows_sys.rs +++ /dev/null @@ -1,4344 +0,0 @@ -// Bindings generated by `windows-bindgen` 0.56.0 - -#![allow(non_snake_case, non_upper_case_globals, non_camel_case_types, dead_code, clippy::all)] -#[link(name = "advapi32")] -extern "system" { - pub fn OpenProcessToken( - processhandle: HANDLE, - desiredaccess: TOKEN_ACCESS_MASK, - tokenhandle: *mut HANDLE, - ) -> BOOL; -} -#[link(name = "advapi32")] -extern "system" { - #[link_name = "SystemFunction036"] - pub fn RtlGenRandom(randombuffer: *mut core::ffi::c_void, randombufferlength: u32) -> BOOLEAN; -} -#[link(name = "kernel32")] -extern "system" { - pub fn AcquireSRWLockExclusive(srwlock: *mut SRWLOCK); -} -#[link(name = "kernel32")] -extern "system" { - pub fn AcquireSRWLockShared(srwlock: *mut SRWLOCK); -} -#[link(name = "kernel32")] -extern "system" { - pub fn CancelIo(hfile: HANDLE) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn CloseHandle(hobject: HANDLE) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn CompareStringOrdinal( - lpstring1: PCWSTR, - cchcount1: i32, - lpstring2: PCWSTR, - cchcount2: i32, - bignorecase: BOOL, - ) -> COMPARESTRING_RESULT; -} -#[link(name = "kernel32")] -extern "system" { - pub fn CopyFileExW( - lpexistingfilename: PCWSTR, - lpnewfilename: PCWSTR, - lpprogressroutine: LPPROGRESS_ROUTINE, - lpdata: *const core::ffi::c_void, - pbcancel: *mut BOOL, - dwcopyflags: u32, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn CreateDirectoryW( - lppathname: PCWSTR, - lpsecurityattributes: *const SECURITY_ATTRIBUTES, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn CreateEventW( - lpeventattributes: *const SECURITY_ATTRIBUTES, - bmanualreset: BOOL, - binitialstate: BOOL, - lpname: PCWSTR, - ) -> HANDLE; -} -#[link(name = "kernel32")] -extern "system" { - pub fn CreateFileW( - lpfilename: PCWSTR, - dwdesiredaccess: u32, - dwsharemode: FILE_SHARE_MODE, - lpsecurityattributes: *const SECURITY_ATTRIBUTES, - dwcreationdisposition: FILE_CREATION_DISPOSITION, - dwflagsandattributes: FILE_FLAGS_AND_ATTRIBUTES, - htemplatefile: HANDLE, - ) -> HANDLE; -} -#[link(name = "kernel32")] -extern "system" { - pub fn CreateHardLinkW( - lpfilename: PCWSTR, - lpexistingfilename: PCWSTR, - lpsecurityattributes: *const SECURITY_ATTRIBUTES, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn CreateNamedPipeW( - lpname: PCWSTR, - dwopenmode: FILE_FLAGS_AND_ATTRIBUTES, - dwpipemode: NAMED_PIPE_MODE, - nmaxinstances: u32, - noutbuffersize: u32, - ninbuffersize: u32, - ndefaulttimeout: u32, - lpsecurityattributes: *const SECURITY_ATTRIBUTES, - ) -> HANDLE; -} -#[link(name = "kernel32")] -extern "system" { - pub fn CreateProcessW( - lpapplicationname: PCWSTR, - lpcommandline: PWSTR, - lpprocessattributes: *const SECURITY_ATTRIBUTES, - lpthreadattributes: *const SECURITY_ATTRIBUTES, - binherithandles: BOOL, - dwcreationflags: PROCESS_CREATION_FLAGS, - lpenvironment: *const core::ffi::c_void, - lpcurrentdirectory: PCWSTR, - lpstartupinfo: *const STARTUPINFOW, - lpprocessinformation: *mut PROCESS_INFORMATION, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn CreateSymbolicLinkW( - lpsymlinkfilename: PCWSTR, - lptargetfilename: PCWSTR, - dwflags: SYMBOLIC_LINK_FLAGS, - ) -> BOOLEAN; -} -#[link(name = "kernel32")] -extern "system" { - pub fn CreateThread( - lpthreadattributes: *const SECURITY_ATTRIBUTES, - dwstacksize: usize, - lpstartaddress: LPTHREAD_START_ROUTINE, - lpparameter: *const core::ffi::c_void, - dwcreationflags: THREAD_CREATION_FLAGS, - lpthreadid: *mut u32, - ) -> HANDLE; -} -#[link(name = "kernel32")] -extern "system" { - pub fn CreateWaitableTimerExW( - lptimerattributes: *const SECURITY_ATTRIBUTES, - lptimername: PCWSTR, - dwflags: u32, - dwdesiredaccess: u32, - ) -> HANDLE; -} -#[link(name = "kernel32")] -extern "system" { - pub fn DeleteFileW(lpfilename: PCWSTR) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn DeleteProcThreadAttributeList(lpattributelist: LPPROC_THREAD_ATTRIBUTE_LIST); -} -#[link(name = "kernel32")] -extern "system" { - pub fn DeviceIoControl( - hdevice: HANDLE, - dwiocontrolcode: u32, - lpinbuffer: *const core::ffi::c_void, - ninbuffersize: u32, - lpoutbuffer: *mut core::ffi::c_void, - noutbuffersize: u32, - lpbytesreturned: *mut u32, - lpoverlapped: *mut OVERLAPPED, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn DuplicateHandle( - hsourceprocesshandle: HANDLE, - hsourcehandle: HANDLE, - htargetprocesshandle: HANDLE, - lptargethandle: *mut HANDLE, - dwdesiredaccess: u32, - binherithandle: BOOL, - dwoptions: DUPLICATE_HANDLE_OPTIONS, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn ExitProcess(uexitcode: u32) -> !; -} -#[link(name = "kernel32")] -extern "system" { - pub fn FindClose(hfindfile: HANDLE) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn FindFirstFileW(lpfilename: PCWSTR, lpfindfiledata: *mut WIN32_FIND_DATAW) -> HANDLE; -} -#[link(name = "kernel32")] -extern "system" { - pub fn FindNextFileW(hfindfile: HANDLE, lpfindfiledata: *mut WIN32_FIND_DATAW) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn FlushFileBuffers(hfile: HANDLE) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn FormatMessageW( - dwflags: FORMAT_MESSAGE_OPTIONS, - lpsource: *const core::ffi::c_void, - dwmessageid: u32, - dwlanguageid: u32, - lpbuffer: PWSTR, - nsize: u32, - arguments: *const *const i8, - ) -> u32; -} -#[link(name = "kernel32")] -extern "system" { - pub fn FreeEnvironmentStringsW(penv: PCWSTR) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetActiveProcessorCount(groupnumber: u16) -> u32; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetCommandLineW() -> PCWSTR; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetConsoleMode(hconsolehandle: HANDLE, lpmode: *mut CONSOLE_MODE) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetCurrentDirectoryW(nbufferlength: u32, lpbuffer: PWSTR) -> u32; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetCurrentProcess() -> HANDLE; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetCurrentProcessId() -> u32; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetCurrentThread() -> HANDLE; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetEnvironmentStringsW() -> PWSTR; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetEnvironmentVariableW(lpname: PCWSTR, lpbuffer: PWSTR, nsize: u32) -> u32; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetExitCodeProcess(hprocess: HANDLE, lpexitcode: *mut u32) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetFileAttributesW(lpfilename: PCWSTR) -> u32; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetFileInformationByHandle( - hfile: HANDLE, - lpfileinformation: *mut BY_HANDLE_FILE_INFORMATION, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetFileInformationByHandleEx( - hfile: HANDLE, - fileinformationclass: FILE_INFO_BY_HANDLE_CLASS, - lpfileinformation: *mut core::ffi::c_void, - dwbuffersize: u32, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetFileType(hfile: HANDLE) -> FILE_TYPE; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetFinalPathNameByHandleW( - hfile: HANDLE, - lpszfilepath: PWSTR, - cchfilepath: u32, - dwflags: GETFINALPATHNAMEBYHANDLE_FLAGS, - ) -> u32; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetFullPathNameW( - lpfilename: PCWSTR, - nbufferlength: u32, - lpbuffer: PWSTR, - lpfilepart: *mut PWSTR, - ) -> u32; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetLastError() -> WIN32_ERROR; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetModuleFileNameW(hmodule: HMODULE, lpfilename: PWSTR, nsize: u32) -> u32; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetModuleHandleA(lpmodulename: PCSTR) -> HMODULE; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetModuleHandleW(lpmodulename: PCWSTR) -> HMODULE; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetOverlappedResult( - hfile: HANDLE, - lpoverlapped: *const OVERLAPPED, - lpnumberofbytestransferred: *mut u32, - bwait: BOOL, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetProcAddress(hmodule: HMODULE, lpprocname: PCSTR) -> FARPROC; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetProcessId(process: HANDLE) -> u32; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetStdHandle(nstdhandle: STD_HANDLE) -> HANDLE; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetSystemDirectoryW(lpbuffer: PWSTR, usize: u32) -> u32; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetSystemInfo(lpsysteminfo: *mut SYSTEM_INFO); -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetSystemTimeAsFileTime(lpsystemtimeasfiletime: *mut FILETIME); -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetSystemTimePreciseAsFileTime(lpsystemtimeasfiletime: *mut FILETIME); -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetTempPathW(nbufferlength: u32, lpbuffer: PWSTR) -> u32; -} -#[link(name = "kernel32")] -extern "system" { - pub fn GetWindowsDirectoryW(lpbuffer: PWSTR, usize: u32) -> u32; -} -#[link(name = "kernel32")] -extern "system" { - pub fn InitOnceBeginInitialize( - lpinitonce: *mut INIT_ONCE, - dwflags: u32, - fpending: *mut BOOL, - lpcontext: *mut *mut core::ffi::c_void, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn InitOnceComplete( - lpinitonce: *mut INIT_ONCE, - dwflags: u32, - lpcontext: *const core::ffi::c_void, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn InitializeProcThreadAttributeList( - lpattributelist: LPPROC_THREAD_ATTRIBUTE_LIST, - dwattributecount: u32, - dwflags: u32, - lpsize: *mut usize, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn LocalFree(hmem: HLOCAL) -> HLOCAL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn MoveFileExW( - lpexistingfilename: PCWSTR, - lpnewfilename: PCWSTR, - dwflags: MOVE_FILE_FLAGS, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn MultiByteToWideChar( - codepage: u32, - dwflags: MULTI_BYTE_TO_WIDE_CHAR_FLAGS, - lpmultibytestr: PCSTR, - cbmultibyte: i32, - lpwidecharstr: PWSTR, - cchwidechar: i32, - ) -> i32; -} -#[link(name = "kernel32")] -extern "system" { - pub fn QueryPerformanceCounter(lpperformancecount: *mut i64) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn QueryPerformanceFrequency(lpfrequency: *mut i64) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn ReadConsoleW( - hconsoleinput: HANDLE, - lpbuffer: *mut core::ffi::c_void, - nnumberofcharstoread: u32, - lpnumberofcharsread: *mut u32, - pinputcontrol: *const CONSOLE_READCONSOLE_CONTROL, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn ReadFile( - hfile: HANDLE, - lpbuffer: *mut u8, - nnumberofbytestoread: u32, - lpnumberofbytesread: *mut u32, - lpoverlapped: *mut OVERLAPPED, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn ReadFileEx( - hfile: HANDLE, - lpbuffer: *mut u8, - nnumberofbytestoread: u32, - lpoverlapped: *mut OVERLAPPED, - lpcompletionroutine: LPOVERLAPPED_COMPLETION_ROUTINE, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn ReleaseSRWLockExclusive(srwlock: *mut SRWLOCK); -} -#[link(name = "kernel32")] -extern "system" { - pub fn ReleaseSRWLockShared(srwlock: *mut SRWLOCK); -} -#[link(name = "kernel32")] -extern "system" { - pub fn RemoveDirectoryW(lppathname: PCWSTR) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn SetCurrentDirectoryW(lppathname: PCWSTR) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn SetEnvironmentVariableW(lpname: PCWSTR, lpvalue: PCWSTR) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn SetFileAttributesW( - lpfilename: PCWSTR, - dwfileattributes: FILE_FLAGS_AND_ATTRIBUTES, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn SetFileInformationByHandle( - hfile: HANDLE, - fileinformationclass: FILE_INFO_BY_HANDLE_CLASS, - lpfileinformation: *const core::ffi::c_void, - dwbuffersize: u32, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn SetFilePointerEx( - hfile: HANDLE, - lidistancetomove: i64, - lpnewfilepointer: *mut i64, - dwmovemethod: SET_FILE_POINTER_MOVE_METHOD, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn SetFileTime( - hfile: HANDLE, - lpcreationtime: *const FILETIME, - lplastaccesstime: *const FILETIME, - lplastwritetime: *const FILETIME, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn SetHandleInformation(hobject: HANDLE, dwmask: u32, dwflags: HANDLE_FLAGS) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn SetLastError(dwerrcode: WIN32_ERROR); -} -#[link(name = "kernel32")] -extern "system" { - pub fn SetThreadStackGuarantee(stacksizeinbytes: *mut u32) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn SetWaitableTimer( - htimer: HANDLE, - lpduetime: *const i64, - lperiod: i32, - pfncompletionroutine: PTIMERAPCROUTINE, - lpargtocompletionroutine: *const core::ffi::c_void, - fresume: BOOL, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn Sleep(dwmilliseconds: u32); -} -#[link(name = "kernel32")] -extern "system" { - pub fn SleepConditionVariableSRW( - conditionvariable: *mut CONDITION_VARIABLE, - srwlock: *mut SRWLOCK, - dwmilliseconds: u32, - flags: u32, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn SleepEx(dwmilliseconds: u32, balertable: BOOL) -> u32; -} -#[link(name = "kernel32")] -extern "system" { - pub fn SwitchToThread() -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn TerminateProcess(hprocess: HANDLE, uexitcode: u32) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn TlsAlloc() -> u32; -} -#[link(name = "kernel32")] -extern "system" { - pub fn TlsFree(dwtlsindex: u32) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn TlsGetValue(dwtlsindex: u32) -> *mut core::ffi::c_void; -} -#[link(name = "kernel32")] -extern "system" { - pub fn TlsSetValue(dwtlsindex: u32, lptlsvalue: *const core::ffi::c_void) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn TryAcquireSRWLockExclusive(srwlock: *mut SRWLOCK) -> BOOLEAN; -} -#[link(name = "kernel32")] -extern "system" { - pub fn TryAcquireSRWLockShared(srwlock: *mut SRWLOCK) -> BOOLEAN; -} -#[link(name = "kernel32")] -extern "system" { - pub fn UpdateProcThreadAttribute( - lpattributelist: LPPROC_THREAD_ATTRIBUTE_LIST, - dwflags: u32, - attribute: usize, - lpvalue: *const core::ffi::c_void, - cbsize: usize, - lppreviousvalue: *mut core::ffi::c_void, - lpreturnsize: *const usize, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn WaitForMultipleObjects( - ncount: u32, - lphandles: *const HANDLE, - bwaitall: BOOL, - dwmilliseconds: u32, - ) -> WAIT_EVENT; -} -#[link(name = "kernel32")] -extern "system" { - pub fn WaitForSingleObject(hhandle: HANDLE, dwmilliseconds: u32) -> WAIT_EVENT; -} -#[link(name = "kernel32")] -extern "system" { - pub fn WakeAllConditionVariable(conditionvariable: *mut CONDITION_VARIABLE); -} -#[link(name = "kernel32")] -extern "system" { - pub fn WakeConditionVariable(conditionvariable: *mut CONDITION_VARIABLE); -} -#[link(name = "kernel32")] -extern "system" { - pub fn WideCharToMultiByte( - codepage: u32, - dwflags: u32, - lpwidecharstr: PCWSTR, - cchwidechar: i32, - lpmultibytestr: PSTR, - cbmultibyte: i32, - lpdefaultchar: PCSTR, - lpuseddefaultchar: *mut BOOL, - ) -> i32; -} -#[link(name = "kernel32")] -extern "system" { - pub fn WriteConsoleW( - hconsoleoutput: HANDLE, - lpbuffer: *const core::ffi::c_void, - nnumberofcharstowrite: u32, - lpnumberofcharswritten: *mut u32, - lpreserved: *const core::ffi::c_void, - ) -> BOOL; -} -#[link(name = "kernel32")] -extern "system" { - pub fn WriteFileEx( - hfile: HANDLE, - lpbuffer: *const u8, - nnumberofbytestowrite: u32, - lpoverlapped: *mut OVERLAPPED, - lpcompletionroutine: LPOVERLAPPED_COMPLETION_ROUTINE, - ) -> BOOL; -} -#[link(name = "ntdll")] -extern "system" { - pub fn NtCreateFile( - filehandle: *mut HANDLE, - desiredaccess: FILE_ACCESS_RIGHTS, - objectattributes: *const OBJECT_ATTRIBUTES, - iostatusblock: *mut IO_STATUS_BLOCK, - allocationsize: *const i64, - fileattributes: FILE_FLAGS_AND_ATTRIBUTES, - shareaccess: FILE_SHARE_MODE, - createdisposition: NTCREATEFILE_CREATE_DISPOSITION, - createoptions: NTCREATEFILE_CREATE_OPTIONS, - eabuffer: *const core::ffi::c_void, - ealength: u32, - ) -> NTSTATUS; -} -#[link(name = "ntdll")] -extern "system" { - pub fn NtReadFile( - filehandle: HANDLE, - event: HANDLE, - apcroutine: PIO_APC_ROUTINE, - apccontext: *const core::ffi::c_void, - iostatusblock: *mut IO_STATUS_BLOCK, - buffer: *mut core::ffi::c_void, - length: u32, - byteoffset: *const i64, - key: *const u32, - ) -> NTSTATUS; -} -#[link(name = "ntdll")] -extern "system" { - pub fn NtWriteFile( - filehandle: HANDLE, - event: HANDLE, - apcroutine: PIO_APC_ROUTINE, - apccontext: *const core::ffi::c_void, - iostatusblock: *mut IO_STATUS_BLOCK, - buffer: *const core::ffi::c_void, - length: u32, - byteoffset: *const i64, - key: *const u32, - ) -> NTSTATUS; -} -#[link(name = "ntdll")] -extern "system" { - pub fn RtlNtStatusToDosError(status: NTSTATUS) -> u32; -} -#[link(name = "userenv")] -extern "system" { - pub fn GetUserProfileDirectoryW( - htoken: HANDLE, - lpprofiledir: PWSTR, - lpcchsize: *mut u32, - ) -> BOOL; -} -#[link(name = "ws2_32")] -extern "system" { - pub fn WSACleanup() -> i32; -} -#[link(name = "ws2_32")] -extern "system" { - pub fn WSADuplicateSocketW( - s: SOCKET, - dwprocessid: u32, - lpprotocolinfo: *mut WSAPROTOCOL_INFOW, - ) -> i32; -} -#[link(name = "ws2_32")] -extern "system" { - pub fn WSAGetLastError() -> WSA_ERROR; -} -#[link(name = "ws2_32")] -extern "system" { - pub fn WSARecv( - s: SOCKET, - lpbuffers: *const WSABUF, - dwbuffercount: u32, - lpnumberofbytesrecvd: *mut u32, - lpflags: *mut u32, - lpoverlapped: *mut OVERLAPPED, - lpcompletionroutine: LPWSAOVERLAPPED_COMPLETION_ROUTINE, - ) -> i32; -} -#[link(name = "ws2_32")] -extern "system" { - pub fn WSASend( - s: SOCKET, - lpbuffers: *const WSABUF, - dwbuffercount: u32, - lpnumberofbytessent: *mut u32, - dwflags: u32, - lpoverlapped: *mut OVERLAPPED, - lpcompletionroutine: LPWSAOVERLAPPED_COMPLETION_ROUTINE, - ) -> i32; -} -#[link(name = "ws2_32")] -extern "system" { - pub fn WSASocketW( - af: i32, - r#type: i32, - protocol: i32, - lpprotocolinfo: *const WSAPROTOCOL_INFOW, - g: u32, - dwflags: u32, - ) -> SOCKET; -} -#[link(name = "ws2_32")] -extern "system" { - pub fn accept(s: SOCKET, addr: *mut SOCKADDR, addrlen: *mut i32) -> SOCKET; -} -#[link(name = "ws2_32")] -extern "system" { - pub fn bind(s: SOCKET, name: *const SOCKADDR, namelen: i32) -> i32; -} -#[link(name = "ws2_32")] -extern "system" { - pub fn closesocket(s: SOCKET) -> i32; -} -#[link(name = "ws2_32")] -extern "system" { - pub fn connect(s: SOCKET, name: *const SOCKADDR, namelen: i32) -> i32; -} -#[link(name = "ws2_32")] -extern "system" { - pub fn freeaddrinfo(paddrinfo: *const ADDRINFOA); -} -#[link(name = "ws2_32")] -extern "system" { - pub fn getaddrinfo( - pnodename: PCSTR, - pservicename: PCSTR, - phints: *const ADDRINFOA, - ppresult: *mut *mut ADDRINFOA, - ) -> i32; -} -#[link(name = "ws2_32")] -extern "system" { - pub fn getpeername(s: SOCKET, name: *mut SOCKADDR, namelen: *mut i32) -> i32; -} -#[link(name = "ws2_32")] -extern "system" { - pub fn getsockname(s: SOCKET, name: *mut SOCKADDR, namelen: *mut i32) -> i32; -} -#[link(name = "ws2_32")] -extern "system" { - pub fn getsockopt(s: SOCKET, level: i32, optname: i32, optval: PSTR, optlen: *mut i32) -> i32; -} -#[link(name = "ws2_32")] -extern "system" { - pub fn ioctlsocket(s: SOCKET, cmd: i32, argp: *mut u32) -> i32; -} -#[link(name = "ws2_32")] -extern "system" { - pub fn listen(s: SOCKET, backlog: i32) -> i32; -} -#[link(name = "ws2_32")] -extern "system" { - pub fn recv(s: SOCKET, buf: PSTR, len: i32, flags: SEND_RECV_FLAGS) -> i32; -} -#[link(name = "ws2_32")] -extern "system" { - pub fn recvfrom( - s: SOCKET, - buf: PSTR, - len: i32, - flags: i32, - from: *mut SOCKADDR, - fromlen: *mut i32, - ) -> i32; -} -#[link(name = "ws2_32")] -extern "system" { - pub fn select( - nfds: i32, - readfds: *mut FD_SET, - writefds: *mut FD_SET, - exceptfds: *mut FD_SET, - timeout: *const TIMEVAL, - ) -> i32; -} -#[link(name = "ws2_32")] -extern "system" { - pub fn send(s: SOCKET, buf: PCSTR, len: i32, flags: SEND_RECV_FLAGS) -> i32; -} -#[link(name = "ws2_32")] -extern "system" { - pub fn sendto( - s: SOCKET, - buf: PCSTR, - len: i32, - flags: i32, - to: *const SOCKADDR, - tolen: i32, - ) -> i32; -} -#[link(name = "ws2_32")] -extern "system" { - pub fn setsockopt(s: SOCKET, level: i32, optname: i32, optval: PCSTR, optlen: i32) -> i32; -} -#[link(name = "ws2_32")] -extern "system" { - pub fn shutdown(s: SOCKET, how: WINSOCK_SHUTDOWN_HOW) -> i32; -} -pub const ABOVE_NORMAL_PRIORITY_CLASS: PROCESS_CREATION_FLAGS = 32768u32; -pub type ADDRESS_FAMILY = u16; -#[repr(C)] -pub struct ADDRINFOA { - pub ai_flags: i32, - pub ai_family: i32, - pub ai_socktype: i32, - pub ai_protocol: i32, - pub ai_addrlen: usize, - pub ai_canonname: PSTR, - pub ai_addr: *mut SOCKADDR, - pub ai_next: *mut ADDRINFOA, -} -impl Copy for ADDRINFOA {} -impl Clone for ADDRINFOA { - fn clone(&self) -> Self { - *self - } -} -pub const AF_INET: ADDRESS_FAMILY = 2u16; -pub const AF_INET6: ADDRESS_FAMILY = 23u16; -pub const AF_UNIX: u16 = 1u16; -pub const AF_UNSPEC: ADDRESS_FAMILY = 0u16; -pub const ALL_PROCESSOR_GROUPS: u16 = 65535u16; -#[repr(C)] -pub union ARM64_NT_NEON128 { - pub Anonymous: ARM64_NT_NEON128_0, - pub D: [f64; 2], - pub S: [f32; 4], - pub H: [u16; 8], - pub B: [u8; 16], -} -impl Copy for ARM64_NT_NEON128 {} -impl Clone for ARM64_NT_NEON128 { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -pub struct ARM64_NT_NEON128_0 { - pub Low: u64, - pub High: i64, -} -impl Copy for ARM64_NT_NEON128_0 {} -impl Clone for ARM64_NT_NEON128_0 { - fn clone(&self) -> Self { - *self - } -} -pub const BELOW_NORMAL_PRIORITY_CLASS: PROCESS_CREATION_FLAGS = 16384u32; -pub type BOOL = i32; -pub type BOOLEAN = u8; -#[repr(C)] -pub struct BY_HANDLE_FILE_INFORMATION { - pub dwFileAttributes: u32, - pub ftCreationTime: FILETIME, - pub ftLastAccessTime: FILETIME, - pub ftLastWriteTime: FILETIME, - pub dwVolumeSerialNumber: u32, - pub nFileSizeHigh: u32, - pub nFileSizeLow: u32, - pub nNumberOfLinks: u32, - pub nFileIndexHigh: u32, - pub nFileIndexLow: u32, -} -impl Copy for BY_HANDLE_FILE_INFORMATION {} -impl Clone for BY_HANDLE_FILE_INFORMATION { - fn clone(&self) -> Self { - *self - } -} -pub const CALLBACK_CHUNK_FINISHED: LPPROGRESS_ROUTINE_CALLBACK_REASON = 0u32; -pub const CALLBACK_STREAM_SWITCH: LPPROGRESS_ROUTINE_CALLBACK_REASON = 1u32; -pub type COMPARESTRING_RESULT = i32; -#[repr(C)] -pub struct CONDITION_VARIABLE { - pub Ptr: *mut core::ffi::c_void, -} -impl Copy for CONDITION_VARIABLE {} -impl Clone for CONDITION_VARIABLE { - fn clone(&self) -> Self { - *self - } -} -pub type CONSOLE_MODE = u32; -#[repr(C)] -pub struct CONSOLE_READCONSOLE_CONTROL { - pub nLength: u32, - pub nInitialChars: u32, - pub dwCtrlWakeupMask: u32, - pub dwControlKeyState: u32, -} -impl Copy for CONSOLE_READCONSOLE_CONTROL {} -impl Clone for CONSOLE_READCONSOLE_CONTROL { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -#[cfg(target_arch = "aarch64")] -pub struct CONTEXT { - pub ContextFlags: CONTEXT_FLAGS, - pub Cpsr: u32, - pub Anonymous: CONTEXT_0, - pub Sp: u64, - pub Pc: u64, - pub V: [ARM64_NT_NEON128; 32], - pub Fpcr: u32, - pub Fpsr: u32, - pub Bcr: [u32; 8], - pub Bvr: [u64; 8], - pub Wcr: [u32; 2], - pub Wvr: [u64; 2], -} -#[cfg(target_arch = "aarch64")] -impl Copy for CONTEXT {} -#[cfg(target_arch = "aarch64")] -impl Clone for CONTEXT { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -#[cfg(target_arch = "aarch64")] -pub union CONTEXT_0 { - pub Anonymous: CONTEXT_0_0, - pub X: [u64; 31], -} -#[cfg(target_arch = "aarch64")] -impl Copy for CONTEXT_0 {} -#[cfg(target_arch = "aarch64")] -impl Clone for CONTEXT_0 { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -#[cfg(target_arch = "aarch64")] -pub struct CONTEXT_0_0 { - pub X0: u64, - pub X1: u64, - pub X2: u64, - pub X3: u64, - pub X4: u64, - pub X5: u64, - pub X6: u64, - pub X7: u64, - pub X8: u64, - pub X9: u64, - pub X10: u64, - pub X11: u64, - pub X12: u64, - pub X13: u64, - pub X14: u64, - pub X15: u64, - pub X16: u64, - pub X17: u64, - pub X18: u64, - pub X19: u64, - pub X20: u64, - pub X21: u64, - pub X22: u64, - pub X23: u64, - pub X24: u64, - pub X25: u64, - pub X26: u64, - pub X27: u64, - pub X28: u64, - pub Fp: u64, - pub Lr: u64, -} -#[cfg(target_arch = "aarch64")] -impl Copy for CONTEXT_0_0 {} -#[cfg(target_arch = "aarch64")] -impl Clone for CONTEXT_0_0 { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -#[cfg(any(target_arch = "arm64ec", target_arch = "x86_64"))] -pub struct CONTEXT { - pub P1Home: u64, - pub P2Home: u64, - pub P3Home: u64, - pub P4Home: u64, - pub P5Home: u64, - pub P6Home: u64, - pub ContextFlags: CONTEXT_FLAGS, - pub MxCsr: u32, - pub SegCs: u16, - pub SegDs: u16, - pub SegEs: u16, - pub SegFs: u16, - pub SegGs: u16, - pub SegSs: u16, - pub EFlags: u32, - pub Dr0: u64, - pub Dr1: u64, - pub Dr2: u64, - pub Dr3: u64, - pub Dr6: u64, - pub Dr7: u64, - pub Rax: u64, - pub Rcx: u64, - pub Rdx: u64, - pub Rbx: u64, - pub Rsp: u64, - pub Rbp: u64, - pub Rsi: u64, - pub Rdi: u64, - pub R8: u64, - pub R9: u64, - pub R10: u64, - pub R11: u64, - pub R12: u64, - pub R13: u64, - pub R14: u64, - pub R15: u64, - pub Rip: u64, - pub Anonymous: CONTEXT_0, - pub VectorRegister: [M128A; 26], - pub VectorControl: u64, - pub DebugControl: u64, - pub LastBranchToRip: u64, - pub LastBranchFromRip: u64, - pub LastExceptionToRip: u64, - pub LastExceptionFromRip: u64, -} -#[cfg(any(target_arch = "arm64ec", target_arch = "x86_64"))] -impl Copy for CONTEXT {} -#[cfg(any(target_arch = "arm64ec", target_arch = "x86_64"))] -impl Clone for CONTEXT { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -#[cfg(any(target_arch = "arm64ec", target_arch = "x86_64"))] -pub union CONTEXT_0 { - pub FltSave: XSAVE_FORMAT, - pub Anonymous: CONTEXT_0_0, -} -#[cfg(any(target_arch = "arm64ec", target_arch = "x86_64"))] -impl Copy for CONTEXT_0 {} -#[cfg(any(target_arch = "arm64ec", target_arch = "x86_64"))] -impl Clone for CONTEXT_0 { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -#[cfg(any(target_arch = "arm64ec", target_arch = "x86_64"))] -pub struct CONTEXT_0_0 { - pub Header: [M128A; 2], - pub Legacy: [M128A; 8], - pub Xmm0: M128A, - pub Xmm1: M128A, - pub Xmm2: M128A, - pub Xmm3: M128A, - pub Xmm4: M128A, - pub Xmm5: M128A, - pub Xmm6: M128A, - pub Xmm7: M128A, - pub Xmm8: M128A, - pub Xmm9: M128A, - pub Xmm10: M128A, - pub Xmm11: M128A, - pub Xmm12: M128A, - pub Xmm13: M128A, - pub Xmm14: M128A, - pub Xmm15: M128A, -} -#[cfg(any(target_arch = "arm64ec", target_arch = "x86_64"))] -impl Copy for CONTEXT_0_0 {} -#[cfg(any(target_arch = "arm64ec", target_arch = "x86_64"))] -impl Clone for CONTEXT_0_0 { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -#[cfg(target_arch = "x86")] -pub struct CONTEXT { - pub ContextFlags: CONTEXT_FLAGS, - pub Dr0: u32, - pub Dr1: u32, - pub Dr2: u32, - pub Dr3: u32, - pub Dr6: u32, - pub Dr7: u32, - pub FloatSave: FLOATING_SAVE_AREA, - pub SegGs: u32, - pub SegFs: u32, - pub SegEs: u32, - pub SegDs: u32, - pub Edi: u32, - pub Esi: u32, - pub Ebx: u32, - pub Edx: u32, - pub Ecx: u32, - pub Eax: u32, - pub Ebp: u32, - pub Eip: u32, - pub SegCs: u32, - pub EFlags: u32, - pub Esp: u32, - pub SegSs: u32, - pub ExtendedRegisters: [u8; 512], -} -#[cfg(target_arch = "x86")] -impl Copy for CONTEXT {} -#[cfg(target_arch = "x86")] -impl Clone for CONTEXT { - fn clone(&self) -> Self { - *self - } -} -pub type CONTEXT_FLAGS = u32; -pub const CP_UTF8: u32 = 65001u32; -pub const CREATE_ALWAYS: FILE_CREATION_DISPOSITION = 2u32; -pub const CREATE_BREAKAWAY_FROM_JOB: PROCESS_CREATION_FLAGS = 16777216u32; -pub const CREATE_DEFAULT_ERROR_MODE: PROCESS_CREATION_FLAGS = 67108864u32; -pub const CREATE_FORCEDOS: PROCESS_CREATION_FLAGS = 8192u32; -pub const CREATE_IGNORE_SYSTEM_DEFAULT: PROCESS_CREATION_FLAGS = 2147483648u32; -pub const CREATE_NEW: FILE_CREATION_DISPOSITION = 1u32; -pub const CREATE_NEW_CONSOLE: PROCESS_CREATION_FLAGS = 16u32; -pub const CREATE_NEW_PROCESS_GROUP: PROCESS_CREATION_FLAGS = 512u32; -pub const CREATE_NO_WINDOW: PROCESS_CREATION_FLAGS = 134217728u32; -pub const CREATE_PRESERVE_CODE_AUTHZ_LEVEL: PROCESS_CREATION_FLAGS = 33554432u32; -pub const CREATE_PROTECTED_PROCESS: PROCESS_CREATION_FLAGS = 262144u32; -pub const CREATE_SECURE_PROCESS: PROCESS_CREATION_FLAGS = 4194304u32; -pub const CREATE_SEPARATE_WOW_VDM: PROCESS_CREATION_FLAGS = 2048u32; -pub const CREATE_SHARED_WOW_VDM: PROCESS_CREATION_FLAGS = 4096u32; -pub const CREATE_SUSPENDED: PROCESS_CREATION_FLAGS = 4u32; -pub const CREATE_UNICODE_ENVIRONMENT: PROCESS_CREATION_FLAGS = 1024u32; -pub const CREATE_WAITABLE_TIMER_HIGH_RESOLUTION: u32 = 2u32; -pub const CREATE_WAITABLE_TIMER_MANUAL_RESET: u32 = 1u32; -pub const CSTR_EQUAL: COMPARESTRING_RESULT = 2i32; -pub const CSTR_GREATER_THAN: COMPARESTRING_RESULT = 3i32; -pub const CSTR_LESS_THAN: COMPARESTRING_RESULT = 1i32; -pub const DEBUG_ONLY_THIS_PROCESS: PROCESS_CREATION_FLAGS = 2u32; -pub const DEBUG_PROCESS: PROCESS_CREATION_FLAGS = 1u32; -pub const DELETE: FILE_ACCESS_RIGHTS = 65536u32; -pub const DETACHED_PROCESS: PROCESS_CREATION_FLAGS = 8u32; -pub const DISABLE_NEWLINE_AUTO_RETURN: CONSOLE_MODE = 8u32; -pub const DLL_PROCESS_DETACH: u32 = 0u32; -pub const DLL_THREAD_DETACH: u32 = 3u32; -pub const DNS_ERROR_ADDRESS_REQUIRED: WIN32_ERROR = 9573u32; -pub const DNS_ERROR_ALIAS_LOOP: WIN32_ERROR = 9722u32; -pub const DNS_ERROR_AUTOZONE_ALREADY_EXISTS: WIN32_ERROR = 9610u32; -pub const DNS_ERROR_AXFR: WIN32_ERROR = 9752u32; -pub const DNS_ERROR_BACKGROUND_LOADING: WIN32_ERROR = 9568u32; -pub const DNS_ERROR_BAD_KEYMASTER: WIN32_ERROR = 9122u32; -pub const DNS_ERROR_BAD_PACKET: WIN32_ERROR = 9502u32; -pub const DNS_ERROR_CANNOT_FIND_ROOT_HINTS: WIN32_ERROR = 9564u32; -pub const DNS_ERROR_CLIENT_SUBNET_ALREADY_EXISTS: WIN32_ERROR = 9977u32; -pub const DNS_ERROR_CLIENT_SUBNET_DOES_NOT_EXIST: WIN32_ERROR = 9976u32; -pub const DNS_ERROR_CLIENT_SUBNET_IS_ACCESSED: WIN32_ERROR = 9975u32; -pub const DNS_ERROR_CNAME_COLLISION: WIN32_ERROR = 9709u32; -pub const DNS_ERROR_CNAME_LOOP: WIN32_ERROR = 9707u32; -pub const DNS_ERROR_DATAFILE_OPEN_FAILURE: WIN32_ERROR = 9653u32; -pub const DNS_ERROR_DATAFILE_PARSING: WIN32_ERROR = 9655u32; -pub const DNS_ERROR_DEFAULT_SCOPE: WIN32_ERROR = 9960u32; -pub const DNS_ERROR_DEFAULT_VIRTUALIZATION_INSTANCE: WIN32_ERROR = 9925u32; -pub const DNS_ERROR_DEFAULT_ZONESCOPE: WIN32_ERROR = 9953u32; -pub const DNS_ERROR_DELEGATION_REQUIRED: WIN32_ERROR = 9571u32; -pub const DNS_ERROR_DNAME_COLLISION: WIN32_ERROR = 9721u32; -pub const DNS_ERROR_DNSSEC_IS_DISABLED: WIN32_ERROR = 9125u32; -pub const DNS_ERROR_DP_ALREADY_ENLISTED: WIN32_ERROR = 9904u32; -pub const DNS_ERROR_DP_ALREADY_EXISTS: WIN32_ERROR = 9902u32; -pub const DNS_ERROR_DP_DOES_NOT_EXIST: WIN32_ERROR = 9901u32; -pub const DNS_ERROR_DP_FSMO_ERROR: WIN32_ERROR = 9906u32; -pub const DNS_ERROR_DP_NOT_AVAILABLE: WIN32_ERROR = 9905u32; -pub const DNS_ERROR_DP_NOT_ENLISTED: WIN32_ERROR = 9903u32; -pub const DNS_ERROR_DS_UNAVAILABLE: WIN32_ERROR = 9717u32; -pub const DNS_ERROR_DS_ZONE_ALREADY_EXISTS: WIN32_ERROR = 9718u32; -pub const DNS_ERROR_DWORD_VALUE_TOO_LARGE: WIN32_ERROR = 9567u32; -pub const DNS_ERROR_DWORD_VALUE_TOO_SMALL: WIN32_ERROR = 9566u32; -pub const DNS_ERROR_FILE_WRITEBACK_FAILED: WIN32_ERROR = 9654u32; -pub const DNS_ERROR_FORWARDER_ALREADY_EXISTS: WIN32_ERROR = 9619u32; -pub const DNS_ERROR_INCONSISTENT_ROOT_HINTS: WIN32_ERROR = 9565u32; -pub const DNS_ERROR_INVAILD_VIRTUALIZATION_INSTANCE_NAME: WIN32_ERROR = 9924u32; -pub const DNS_ERROR_INVALID_CLIENT_SUBNET_NAME: WIN32_ERROR = 9984u32; -pub const DNS_ERROR_INVALID_DATA: WIN32_ERROR = 13u32; -pub const DNS_ERROR_INVALID_DATAFILE_NAME: WIN32_ERROR = 9652u32; -pub const DNS_ERROR_INVALID_INITIAL_ROLLOVER_OFFSET: WIN32_ERROR = 9115u32; -pub const DNS_ERROR_INVALID_IP_ADDRESS: WIN32_ERROR = 9552u32; -pub const DNS_ERROR_INVALID_KEY_SIZE: WIN32_ERROR = 9106u32; -pub const DNS_ERROR_INVALID_NAME: WIN32_ERROR = 123u32; -pub const DNS_ERROR_INVALID_NAME_CHAR: WIN32_ERROR = 9560u32; -pub const DNS_ERROR_INVALID_NSEC3_ITERATION_COUNT: WIN32_ERROR = 9124u32; -pub const DNS_ERROR_INVALID_POLICY_TABLE: WIN32_ERROR = 9572u32; -pub const DNS_ERROR_INVALID_PROPERTY: WIN32_ERROR = 9553u32; -pub const DNS_ERROR_INVALID_ROLLOVER_PERIOD: WIN32_ERROR = 9114u32; -pub const DNS_ERROR_INVALID_SCOPE_NAME: WIN32_ERROR = 9958u32; -pub const DNS_ERROR_INVALID_SCOPE_OPERATION: WIN32_ERROR = 9961u32; -pub const DNS_ERROR_INVALID_SIGNATURE_VALIDITY_PERIOD: WIN32_ERROR = 9123u32; -pub const DNS_ERROR_INVALID_TYPE: WIN32_ERROR = 9551u32; -pub const DNS_ERROR_INVALID_XML: WIN32_ERROR = 9126u32; -pub const DNS_ERROR_INVALID_ZONESCOPE_NAME: WIN32_ERROR = 9954u32; -pub const DNS_ERROR_INVALID_ZONE_OPERATION: WIN32_ERROR = 9603u32; -pub const DNS_ERROR_INVALID_ZONE_TYPE: WIN32_ERROR = 9611u32; -pub const DNS_ERROR_KEYMASTER_REQUIRED: WIN32_ERROR = 9101u32; -pub const DNS_ERROR_KSP_DOES_NOT_SUPPORT_PROTECTION: WIN32_ERROR = 9108u32; -pub const DNS_ERROR_KSP_NOT_ACCESSIBLE: WIN32_ERROR = 9112u32; -pub const DNS_ERROR_LOAD_ZONESCOPE_FAILED: WIN32_ERROR = 9956u32; -pub const DNS_ERROR_NAME_DOES_NOT_EXIST: WIN32_ERROR = 9714u32; -pub const DNS_ERROR_NAME_NOT_IN_ZONE: WIN32_ERROR = 9706u32; -pub const DNS_ERROR_NBSTAT_INIT_FAILED: WIN32_ERROR = 9617u32; -pub const DNS_ERROR_NEED_SECONDARY_ADDRESSES: WIN32_ERROR = 9614u32; -pub const DNS_ERROR_NEED_WINS_SERVERS: WIN32_ERROR = 9616u32; -pub const DNS_ERROR_NODE_CREATION_FAILED: WIN32_ERROR = 9703u32; -pub const DNS_ERROR_NODE_IS_CNAME: WIN32_ERROR = 9708u32; -pub const DNS_ERROR_NODE_IS_DNAME: WIN32_ERROR = 9720u32; -pub const DNS_ERROR_NON_RFC_NAME: WIN32_ERROR = 9556u32; -pub const DNS_ERROR_NOT_ALLOWED_ON_ACTIVE_SKD: WIN32_ERROR = 9119u32; -pub const DNS_ERROR_NOT_ALLOWED_ON_RODC: WIN32_ERROR = 9569u32; -pub const DNS_ERROR_NOT_ALLOWED_ON_ROOT_SERVER: WIN32_ERROR = 9562u32; -pub const DNS_ERROR_NOT_ALLOWED_ON_SIGNED_ZONE: WIN32_ERROR = 9102u32; -pub const DNS_ERROR_NOT_ALLOWED_ON_UNSIGNED_ZONE: WIN32_ERROR = 9121u32; -pub const DNS_ERROR_NOT_ALLOWED_ON_ZSK: WIN32_ERROR = 9118u32; -pub const DNS_ERROR_NOT_ALLOWED_UNDER_DELEGATION: WIN32_ERROR = 9563u32; -pub const DNS_ERROR_NOT_ALLOWED_UNDER_DNAME: WIN32_ERROR = 9570u32; -pub const DNS_ERROR_NOT_ALLOWED_WITH_ZONESCOPES: WIN32_ERROR = 9955u32; -pub const DNS_ERROR_NOT_ENOUGH_SIGNING_KEY_DESCRIPTORS: WIN32_ERROR = 9104u32; -pub const DNS_ERROR_NOT_UNIQUE: WIN32_ERROR = 9555u32; -pub const DNS_ERROR_NO_BOOTFILE_IF_DS_ZONE: WIN32_ERROR = 9719u32; -pub const DNS_ERROR_NO_CREATE_CACHE_DATA: WIN32_ERROR = 9713u32; -pub const DNS_ERROR_NO_DNS_SERVERS: WIN32_ERROR = 9852u32; -pub const DNS_ERROR_NO_MEMORY: WIN32_ERROR = 14u32; -pub const DNS_ERROR_NO_PACKET: WIN32_ERROR = 9503u32; -pub const DNS_ERROR_NO_TCPIP: WIN32_ERROR = 9851u32; -pub const DNS_ERROR_NO_VALID_TRUST_ANCHORS: WIN32_ERROR = 9127u32; -pub const DNS_ERROR_NO_ZONE_INFO: WIN32_ERROR = 9602u32; -pub const DNS_ERROR_NSEC3_INCOMPATIBLE_WITH_RSA_SHA1: WIN32_ERROR = 9103u32; -pub const DNS_ERROR_NSEC3_NAME_COLLISION: WIN32_ERROR = 9129u32; -pub const DNS_ERROR_NSEC_INCOMPATIBLE_WITH_NSEC3_RSA_SHA1: WIN32_ERROR = 9130u32; -pub const DNS_ERROR_NUMERIC_NAME: WIN32_ERROR = 9561u32; -pub const DNS_ERROR_POLICY_ALREADY_EXISTS: WIN32_ERROR = 9971u32; -pub const DNS_ERROR_POLICY_DOES_NOT_EXIST: WIN32_ERROR = 9972u32; -pub const DNS_ERROR_POLICY_INVALID_CRITERIA: WIN32_ERROR = 9973u32; -pub const DNS_ERROR_POLICY_INVALID_CRITERIA_CLIENT_SUBNET: WIN32_ERROR = 9990u32; -pub const DNS_ERROR_POLICY_INVALID_CRITERIA_FQDN: WIN32_ERROR = 9994u32; -pub const DNS_ERROR_POLICY_INVALID_CRITERIA_INTERFACE: WIN32_ERROR = 9993u32; -pub const DNS_ERROR_POLICY_INVALID_CRITERIA_NETWORK_PROTOCOL: WIN32_ERROR = 9992u32; -pub const DNS_ERROR_POLICY_INVALID_CRITERIA_QUERY_TYPE: WIN32_ERROR = 9995u32; -pub const DNS_ERROR_POLICY_INVALID_CRITERIA_TIME_OF_DAY: WIN32_ERROR = 9996u32; -pub const DNS_ERROR_POLICY_INVALID_CRITERIA_TRANSPORT_PROTOCOL: WIN32_ERROR = 9991u32; -pub const DNS_ERROR_POLICY_INVALID_NAME: WIN32_ERROR = 9982u32; -pub const DNS_ERROR_POLICY_INVALID_SETTINGS: WIN32_ERROR = 9974u32; -pub const DNS_ERROR_POLICY_INVALID_WEIGHT: WIN32_ERROR = 9981u32; -pub const DNS_ERROR_POLICY_LOCKED: WIN32_ERROR = 9980u32; -pub const DNS_ERROR_POLICY_MISSING_CRITERIA: WIN32_ERROR = 9983u32; -pub const DNS_ERROR_POLICY_PROCESSING_ORDER_INVALID: WIN32_ERROR = 9985u32; -pub const DNS_ERROR_POLICY_SCOPE_MISSING: WIN32_ERROR = 9986u32; -pub const DNS_ERROR_POLICY_SCOPE_NOT_ALLOWED: WIN32_ERROR = 9987u32; -pub const DNS_ERROR_PRIMARY_REQUIRES_DATAFILE: WIN32_ERROR = 9651u32; -pub const DNS_ERROR_RCODE: WIN32_ERROR = 9504u32; -pub const DNS_ERROR_RCODE_BADKEY: WIN32_ERROR = 9017u32; -pub const DNS_ERROR_RCODE_BADSIG: WIN32_ERROR = 9016u32; -pub const DNS_ERROR_RCODE_BADTIME: WIN32_ERROR = 9018u32; -pub const DNS_ERROR_RCODE_FORMAT_ERROR: WIN32_ERROR = 9001u32; -pub const DNS_ERROR_RCODE_NAME_ERROR: WIN32_ERROR = 9003u32; -pub const DNS_ERROR_RCODE_NOTAUTH: WIN32_ERROR = 9009u32; -pub const DNS_ERROR_RCODE_NOTZONE: WIN32_ERROR = 9010u32; -pub const DNS_ERROR_RCODE_NOT_IMPLEMENTED: WIN32_ERROR = 9004u32; -pub const DNS_ERROR_RCODE_NXRRSET: WIN32_ERROR = 9008u32; -pub const DNS_ERROR_RCODE_REFUSED: WIN32_ERROR = 9005u32; -pub const DNS_ERROR_RCODE_SERVER_FAILURE: WIN32_ERROR = 9002u32; -pub const DNS_ERROR_RCODE_YXDOMAIN: WIN32_ERROR = 9006u32; -pub const DNS_ERROR_RCODE_YXRRSET: WIN32_ERROR = 9007u32; -pub const DNS_ERROR_RECORD_ALREADY_EXISTS: WIN32_ERROR = 9711u32; -pub const DNS_ERROR_RECORD_DOES_NOT_EXIST: WIN32_ERROR = 9701u32; -pub const DNS_ERROR_RECORD_FORMAT: WIN32_ERROR = 9702u32; -pub const DNS_ERROR_RECORD_ONLY_AT_ZONE_ROOT: WIN32_ERROR = 9710u32; -pub const DNS_ERROR_RECORD_TIMED_OUT: WIN32_ERROR = 9705u32; -pub const DNS_ERROR_ROLLOVER_ALREADY_QUEUED: WIN32_ERROR = 9120u32; -pub const DNS_ERROR_ROLLOVER_IN_PROGRESS: WIN32_ERROR = 9116u32; -pub const DNS_ERROR_ROLLOVER_NOT_POKEABLE: WIN32_ERROR = 9128u32; -pub const DNS_ERROR_RRL_INVALID_IPV4_PREFIX: WIN32_ERROR = 9913u32; -pub const DNS_ERROR_RRL_INVALID_IPV6_PREFIX: WIN32_ERROR = 9914u32; -pub const DNS_ERROR_RRL_INVALID_LEAK_RATE: WIN32_ERROR = 9916u32; -pub const DNS_ERROR_RRL_INVALID_TC_RATE: WIN32_ERROR = 9915u32; -pub const DNS_ERROR_RRL_INVALID_WINDOW_SIZE: WIN32_ERROR = 9912u32; -pub const DNS_ERROR_RRL_LEAK_RATE_LESSTHAN_TC_RATE: WIN32_ERROR = 9917u32; -pub const DNS_ERROR_RRL_NOT_ENABLED: WIN32_ERROR = 9911u32; -pub const DNS_ERROR_SCOPE_ALREADY_EXISTS: WIN32_ERROR = 9963u32; -pub const DNS_ERROR_SCOPE_DOES_NOT_EXIST: WIN32_ERROR = 9959u32; -pub const DNS_ERROR_SCOPE_LOCKED: WIN32_ERROR = 9962u32; -pub const DNS_ERROR_SECONDARY_DATA: WIN32_ERROR = 9712u32; -pub const DNS_ERROR_SECONDARY_REQUIRES_MASTER_IP: WIN32_ERROR = 9612u32; -pub const DNS_ERROR_SERVERSCOPE_IS_REFERENCED: WIN32_ERROR = 9988u32; -pub const DNS_ERROR_SIGNING_KEY_NOT_ACCESSIBLE: WIN32_ERROR = 9107u32; -pub const DNS_ERROR_SOA_DELETE_INVALID: WIN32_ERROR = 9618u32; -pub const DNS_ERROR_STANDBY_KEY_NOT_PRESENT: WIN32_ERROR = 9117u32; -pub const DNS_ERROR_SUBNET_ALREADY_EXISTS: WIN32_ERROR = 9979u32; -pub const DNS_ERROR_SUBNET_DOES_NOT_EXIST: WIN32_ERROR = 9978u32; -pub const DNS_ERROR_TOO_MANY_SKDS: WIN32_ERROR = 9113u32; -pub const DNS_ERROR_TRY_AGAIN_LATER: WIN32_ERROR = 9554u32; -pub const DNS_ERROR_UNEXPECTED_CNG_ERROR: WIN32_ERROR = 9110u32; -pub const DNS_ERROR_UNEXPECTED_DATA_PROTECTION_ERROR: WIN32_ERROR = 9109u32; -pub const DNS_ERROR_UNKNOWN_RECORD_TYPE: WIN32_ERROR = 9704u32; -pub const DNS_ERROR_UNKNOWN_SIGNING_PARAMETER_VERSION: WIN32_ERROR = 9111u32; -pub const DNS_ERROR_UNSECURE_PACKET: WIN32_ERROR = 9505u32; -pub const DNS_ERROR_UNSUPPORTED_ALGORITHM: WIN32_ERROR = 9105u32; -pub const DNS_ERROR_VIRTUALIZATION_INSTANCE_ALREADY_EXISTS: WIN32_ERROR = 9921u32; -pub const DNS_ERROR_VIRTUALIZATION_INSTANCE_DOES_NOT_EXIST: WIN32_ERROR = 9922u32; -pub const DNS_ERROR_VIRTUALIZATION_TREE_LOCKED: WIN32_ERROR = 9923u32; -pub const DNS_ERROR_WINS_INIT_FAILED: WIN32_ERROR = 9615u32; -pub const DNS_ERROR_ZONESCOPE_ALREADY_EXISTS: WIN32_ERROR = 9951u32; -pub const DNS_ERROR_ZONESCOPE_DOES_NOT_EXIST: WIN32_ERROR = 9952u32; -pub const DNS_ERROR_ZONESCOPE_FILE_WRITEBACK_FAILED: WIN32_ERROR = 9957u32; -pub const DNS_ERROR_ZONESCOPE_IS_REFERENCED: WIN32_ERROR = 9989u32; -pub const DNS_ERROR_ZONE_ALREADY_EXISTS: WIN32_ERROR = 9609u32; -pub const DNS_ERROR_ZONE_CONFIGURATION_ERROR: WIN32_ERROR = 9604u32; -pub const DNS_ERROR_ZONE_CREATION_FAILED: WIN32_ERROR = 9608u32; -pub const DNS_ERROR_ZONE_DOES_NOT_EXIST: WIN32_ERROR = 9601u32; -pub const DNS_ERROR_ZONE_HAS_NO_NS_RECORDS: WIN32_ERROR = 9606u32; -pub const DNS_ERROR_ZONE_HAS_NO_SOA_RECORD: WIN32_ERROR = 9605u32; -pub const DNS_ERROR_ZONE_IS_SHUTDOWN: WIN32_ERROR = 9621u32; -pub const DNS_ERROR_ZONE_LOCKED: WIN32_ERROR = 9607u32; -pub const DNS_ERROR_ZONE_LOCKED_FOR_SIGNING: WIN32_ERROR = 9622u32; -pub const DNS_ERROR_ZONE_NOT_SECONDARY: WIN32_ERROR = 9613u32; -pub const DNS_ERROR_ZONE_REQUIRES_MASTER_IP: WIN32_ERROR = 9620u32; -pub const DUPLICATE_CLOSE_SOURCE: DUPLICATE_HANDLE_OPTIONS = 1u32; -pub type DUPLICATE_HANDLE_OPTIONS = u32; -pub const DUPLICATE_SAME_ACCESS: DUPLICATE_HANDLE_OPTIONS = 2u32; -pub const ENABLE_AUTO_POSITION: CONSOLE_MODE = 256u32; -pub const ENABLE_ECHO_INPUT: CONSOLE_MODE = 4u32; -pub const ENABLE_EXTENDED_FLAGS: CONSOLE_MODE = 128u32; -pub const ENABLE_INSERT_MODE: CONSOLE_MODE = 32u32; -pub const ENABLE_LINE_INPUT: CONSOLE_MODE = 2u32; -pub const ENABLE_LVB_GRID_WORLDWIDE: CONSOLE_MODE = 16u32; -pub const ENABLE_MOUSE_INPUT: CONSOLE_MODE = 16u32; -pub const ENABLE_PROCESSED_INPUT: CONSOLE_MODE = 1u32; -pub const ENABLE_PROCESSED_OUTPUT: CONSOLE_MODE = 1u32; -pub const ENABLE_QUICK_EDIT_MODE: CONSOLE_MODE = 64u32; -pub const ENABLE_VIRTUAL_TERMINAL_INPUT: CONSOLE_MODE = 512u32; -pub const ENABLE_VIRTUAL_TERMINAL_PROCESSING: CONSOLE_MODE = 4u32; -pub const ENABLE_WINDOW_INPUT: CONSOLE_MODE = 8u32; -pub const ENABLE_WRAP_AT_EOL_OUTPUT: CONSOLE_MODE = 2u32; -pub const ERROR_ABANDONED_WAIT_0: WIN32_ERROR = 735u32; -pub const ERROR_ABANDONED_WAIT_63: WIN32_ERROR = 736u32; -pub const ERROR_ABANDON_HIBERFILE: WIN32_ERROR = 787u32; -pub const ERROR_ABIOS_ERROR: WIN32_ERROR = 538u32; -pub const ERROR_ACCESS_AUDIT_BY_POLICY: WIN32_ERROR = 785u32; -pub const ERROR_ACCESS_DENIED: WIN32_ERROR = 5u32; -pub const ERROR_ACCESS_DENIED_APPDATA: WIN32_ERROR = 502u32; -pub const ERROR_ACCESS_DISABLED_BY_POLICY: WIN32_ERROR = 1260u32; -pub const ERROR_ACCESS_DISABLED_NO_SAFER_UI_BY_POLICY: WIN32_ERROR = 786u32; -pub const ERROR_ACCESS_DISABLED_WEBBLADE: WIN32_ERROR = 1277u32; -pub const ERROR_ACCESS_DISABLED_WEBBLADE_TAMPER: WIN32_ERROR = 1278u32; -pub const ERROR_ACCOUNT_DISABLED: WIN32_ERROR = 1331u32; -pub const ERROR_ACCOUNT_EXPIRED: WIN32_ERROR = 1793u32; -pub const ERROR_ACCOUNT_LOCKED_OUT: WIN32_ERROR = 1909u32; -pub const ERROR_ACCOUNT_RESTRICTION: WIN32_ERROR = 1327u32; -pub const ERROR_ACPI_ERROR: WIN32_ERROR = 669u32; -pub const ERROR_ACTIVE_CONNECTIONS: WIN32_ERROR = 2402u32; -pub const ERROR_ADAP_HDW_ERR: WIN32_ERROR = 57u32; -pub const ERROR_ADDRESS_ALREADY_ASSOCIATED: WIN32_ERROR = 1227u32; -pub const ERROR_ADDRESS_NOT_ASSOCIATED: WIN32_ERROR = 1228u32; -pub const ERROR_ALERTED: WIN32_ERROR = 739u32; -pub const ERROR_ALIAS_EXISTS: WIN32_ERROR = 1379u32; -pub const ERROR_ALLOCATE_BUCKET: WIN32_ERROR = 602u32; -pub const ERROR_ALLOTTED_SPACE_EXCEEDED: WIN32_ERROR = 1344u32; -pub const ERROR_ALL_USER_TRUST_QUOTA_EXCEEDED: WIN32_ERROR = 1933u32; -pub const ERROR_ALREADY_ASSIGNED: WIN32_ERROR = 85u32; -pub const ERROR_ALREADY_EXISTS: WIN32_ERROR = 183u32; -pub const ERROR_ALREADY_FIBER: WIN32_ERROR = 1280u32; -pub const ERROR_ALREADY_HAS_STREAM_ID: WIN32_ERROR = 4444u32; -pub const ERROR_ALREADY_INITIALIZED: WIN32_ERROR = 1247u32; -pub const ERROR_ALREADY_REGISTERED: WIN32_ERROR = 1242u32; -pub const ERROR_ALREADY_RUNNING_LKG: WIN32_ERROR = 1074u32; -pub const ERROR_ALREADY_THREAD: WIN32_ERROR = 1281u32; -pub const ERROR_ALREADY_WAITING: WIN32_ERROR = 1904u32; -pub const ERROR_ALREADY_WIN32: WIN32_ERROR = 719u32; -pub const ERROR_API_UNAVAILABLE: WIN32_ERROR = 15841u32; -pub const ERROR_APPCONTAINER_REQUIRED: WIN32_ERROR = 4251u32; -pub const ERROR_APPEXEC_APP_COMPAT_BLOCK: WIN32_ERROR = 3068u32; -pub const ERROR_APPEXEC_CALLER_WAIT_TIMEOUT: WIN32_ERROR = 3069u32; -pub const ERROR_APPEXEC_CALLER_WAIT_TIMEOUT_LICENSING: WIN32_ERROR = 3071u32; -pub const ERROR_APPEXEC_CALLER_WAIT_TIMEOUT_RESOURCES: WIN32_ERROR = 3072u32; -pub const ERROR_APPEXEC_CALLER_WAIT_TIMEOUT_TERMINATION: WIN32_ERROR = 3070u32; -pub const ERROR_APPEXEC_CONDITION_NOT_SATISFIED: WIN32_ERROR = 3060u32; -pub const ERROR_APPEXEC_HANDLE_INVALIDATED: WIN32_ERROR = 3061u32; -pub const ERROR_APPEXEC_HOST_ID_MISMATCH: WIN32_ERROR = 3066u32; -pub const ERROR_APPEXEC_INVALID_HOST_GENERATION: WIN32_ERROR = 3062u32; -pub const ERROR_APPEXEC_INVALID_HOST_STATE: WIN32_ERROR = 3064u32; -pub const ERROR_APPEXEC_NO_DONOR: WIN32_ERROR = 3065u32; -pub const ERROR_APPEXEC_UNEXPECTED_PROCESS_REGISTRATION: WIN32_ERROR = 3063u32; -pub const ERROR_APPEXEC_UNKNOWN_USER: WIN32_ERROR = 3067u32; -pub const ERROR_APPHELP_BLOCK: WIN32_ERROR = 1259u32; -pub const ERROR_APPX_FILE_NOT_ENCRYPTED: WIN32_ERROR = 409u32; -pub const ERROR_APP_HANG: WIN32_ERROR = 1298u32; -pub const ERROR_APP_INIT_FAILURE: WIN32_ERROR = 575u32; -pub const ERROR_APP_WRONG_OS: WIN32_ERROR = 1151u32; -pub const ERROR_ARBITRATION_UNHANDLED: WIN32_ERROR = 723u32; -pub const ERROR_ARENA_TRASHED: WIN32_ERROR = 7u32; -pub const ERROR_ARITHMETIC_OVERFLOW: WIN32_ERROR = 534u32; -pub const ERROR_ASSERTION_FAILURE: WIN32_ERROR = 668u32; -pub const ERROR_ATOMIC_LOCKS_NOT_SUPPORTED: WIN32_ERROR = 174u32; -pub const ERROR_AUDIT_FAILED: WIN32_ERROR = 606u32; -pub const ERROR_AUTHENTICATION_FIREWALL_FAILED: WIN32_ERROR = 1935u32; -pub const ERROR_AUTHIP_FAILURE: WIN32_ERROR = 1469u32; -pub const ERROR_AUTODATASEG_EXCEEDS_64k: WIN32_ERROR = 199u32; -pub const ERROR_BACKUP_CONTROLLER: WIN32_ERROR = 586u32; -pub const ERROR_BADDB: WIN32_ERROR = 1009u32; -pub const ERROR_BADKEY: WIN32_ERROR = 1010u32; -pub const ERROR_BADSTARTPOSITION: WIN32_ERROR = 778u32; -pub const ERROR_BAD_ACCESSOR_FLAGS: WIN32_ERROR = 773u32; -pub const ERROR_BAD_ARGUMENTS: WIN32_ERROR = 160u32; -pub const ERROR_BAD_COMMAND: WIN32_ERROR = 22u32; -pub const ERROR_BAD_COMPRESSION_BUFFER: WIN32_ERROR = 605u32; -pub const ERROR_BAD_CONFIGURATION: WIN32_ERROR = 1610u32; -pub const ERROR_BAD_CURRENT_DIRECTORY: WIN32_ERROR = 703u32; -pub const ERROR_BAD_DESCRIPTOR_FORMAT: WIN32_ERROR = 1361u32; -pub const ERROR_BAD_DEVICE: WIN32_ERROR = 1200u32; -pub const ERROR_BAD_DEVICE_PATH: WIN32_ERROR = 330u32; -pub const ERROR_BAD_DEV_TYPE: WIN32_ERROR = 66u32; -pub const ERROR_BAD_DLL_ENTRYPOINT: WIN32_ERROR = 609u32; -pub const ERROR_BAD_DRIVER_LEVEL: WIN32_ERROR = 119u32; -pub const ERROR_BAD_ENVIRONMENT: WIN32_ERROR = 10u32; -pub const ERROR_BAD_EXE_FORMAT: WIN32_ERROR = 193u32; -pub const ERROR_BAD_FILE_TYPE: WIN32_ERROR = 222u32; -pub const ERROR_BAD_FORMAT: WIN32_ERROR = 11u32; -pub const ERROR_BAD_FUNCTION_TABLE: WIN32_ERROR = 559u32; -pub const ERROR_BAD_IMPERSONATION_LEVEL: WIN32_ERROR = 1346u32; -pub const ERROR_BAD_INHERITANCE_ACL: WIN32_ERROR = 1340u32; -pub const ERROR_BAD_LENGTH: WIN32_ERROR = 24u32; -pub const ERROR_BAD_LOGON_SESSION_STATE: WIN32_ERROR = 1365u32; -pub const ERROR_BAD_MCFG_TABLE: WIN32_ERROR = 791u32; -pub const ERROR_BAD_NETPATH: WIN32_ERROR = 53u32; -pub const ERROR_BAD_NET_NAME: WIN32_ERROR = 67u32; -pub const ERROR_BAD_NET_RESP: WIN32_ERROR = 58u32; -pub const ERROR_BAD_PATHNAME: WIN32_ERROR = 161u32; -pub const ERROR_BAD_PIPE: WIN32_ERROR = 230u32; -pub const ERROR_BAD_PROFILE: WIN32_ERROR = 1206u32; -pub const ERROR_BAD_PROVIDER: WIN32_ERROR = 1204u32; -pub const ERROR_BAD_QUERY_SYNTAX: WIN32_ERROR = 1615u32; -pub const ERROR_BAD_RECOVERY_POLICY: WIN32_ERROR = 6012u32; -pub const ERROR_BAD_REM_ADAP: WIN32_ERROR = 60u32; -pub const ERROR_BAD_SERVICE_ENTRYPOINT: WIN32_ERROR = 610u32; -pub const ERROR_BAD_STACK: WIN32_ERROR = 543u32; -pub const ERROR_BAD_THREADID_ADDR: WIN32_ERROR = 159u32; -pub const ERROR_BAD_TOKEN_TYPE: WIN32_ERROR = 1349u32; -pub const ERROR_BAD_UNIT: WIN32_ERROR = 20u32; -pub const ERROR_BAD_USERNAME: WIN32_ERROR = 2202u32; -pub const ERROR_BAD_USER_PROFILE: WIN32_ERROR = 1253u32; -pub const ERROR_BAD_VALIDATION_CLASS: WIN32_ERROR = 1348u32; -pub const ERROR_BEGINNING_OF_MEDIA: WIN32_ERROR = 1102u32; -pub const ERROR_BEYOND_VDL: WIN32_ERROR = 1289u32; -pub const ERROR_BIOS_FAILED_TO_CONNECT_INTERRUPT: WIN32_ERROR = 585u32; -pub const ERROR_BLOCKED_BY_PARENTAL_CONTROLS: WIN32_ERROR = 346u32; -pub const ERROR_BLOCK_SHARED: WIN32_ERROR = 514u32; -pub const ERROR_BLOCK_SOURCE_WEAK_REFERENCE_INVALID: WIN32_ERROR = 512u32; -pub const ERROR_BLOCK_TARGET_WEAK_REFERENCE_INVALID: WIN32_ERROR = 513u32; -pub const ERROR_BLOCK_TOO_MANY_REFERENCES: WIN32_ERROR = 347u32; -pub const ERROR_BLOCK_WEAK_REFERENCE_INVALID: WIN32_ERROR = 511u32; -pub const ERROR_BOOT_ALREADY_ACCEPTED: WIN32_ERROR = 1076u32; -pub const ERROR_BROKEN_PIPE: WIN32_ERROR = 109u32; -pub const ERROR_BUFFER_ALL_ZEROS: WIN32_ERROR = 754u32; -pub const ERROR_BUFFER_OVERFLOW: WIN32_ERROR = 111u32; -pub const ERROR_BUSY: WIN32_ERROR = 170u32; -pub const ERROR_BUSY_DRIVE: WIN32_ERROR = 142u32; -pub const ERROR_BUS_RESET: WIN32_ERROR = 1111u32; -pub const ERROR_BYPASSIO_FLT_NOT_SUPPORTED: WIN32_ERROR = 506u32; -pub const ERROR_CACHE_PAGE_LOCKED: WIN32_ERROR = 752u32; -pub const ERROR_CALLBACK_INVOKE_INLINE: WIN32_ERROR = 812u32; -pub const ERROR_CALLBACK_POP_STACK: WIN32_ERROR = 768u32; -pub const ERROR_CALLBACK_SUPPLIED_INVALID_DATA: WIN32_ERROR = 1273u32; -pub const ERROR_CALL_NOT_IMPLEMENTED: WIN32_ERROR = 120u32; -pub const ERROR_CANCELLED: WIN32_ERROR = 1223u32; -pub const ERROR_CANCEL_VIOLATION: WIN32_ERROR = 173u32; -pub const ERROR_CANNOT_BREAK_OPLOCK: WIN32_ERROR = 802u32; -pub const ERROR_CANNOT_COPY: WIN32_ERROR = 266u32; -pub const ERROR_CANNOT_DETECT_DRIVER_FAILURE: WIN32_ERROR = 1080u32; -pub const ERROR_CANNOT_DETECT_PROCESS_ABORT: WIN32_ERROR = 1081u32; -pub const ERROR_CANNOT_FIND_WND_CLASS: WIN32_ERROR = 1407u32; -pub const ERROR_CANNOT_GRANT_REQUESTED_OPLOCK: WIN32_ERROR = 801u32; -pub const ERROR_CANNOT_IMPERSONATE: WIN32_ERROR = 1368u32; -pub const ERROR_CANNOT_LOAD_REGISTRY_FILE: WIN32_ERROR = 589u32; -pub const ERROR_CANNOT_MAKE: WIN32_ERROR = 82u32; -pub const ERROR_CANNOT_OPEN_PROFILE: WIN32_ERROR = 1205u32; -pub const ERROR_CANTFETCHBACKWARDS: WIN32_ERROR = 770u32; -pub const ERROR_CANTOPEN: WIN32_ERROR = 1011u32; -pub const ERROR_CANTREAD: WIN32_ERROR = 1012u32; -pub const ERROR_CANTSCROLLBACKWARDS: WIN32_ERROR = 771u32; -pub const ERROR_CANTWRITE: WIN32_ERROR = 1013u32; -pub const ERROR_CANT_ACCESS_DOMAIN_INFO: WIN32_ERROR = 1351u32; -pub const ERROR_CANT_ACCESS_FILE: WIN32_ERROR = 1920u32; -pub const ERROR_CANT_CLEAR_ENCRYPTION_FLAG: WIN32_ERROR = 432u32; -pub const ERROR_CANT_DISABLE_MANDATORY: WIN32_ERROR = 1310u32; -pub const ERROR_CANT_ENABLE_DENY_ONLY: WIN32_ERROR = 629u32; -pub const ERROR_CANT_OPEN_ANONYMOUS: WIN32_ERROR = 1347u32; -pub const ERROR_CANT_RESOLVE_FILENAME: WIN32_ERROR = 1921u32; -pub const ERROR_CANT_TERMINATE_SELF: WIN32_ERROR = 555u32; -pub const ERROR_CANT_WAIT: WIN32_ERROR = 554u32; -pub const ERROR_CAN_NOT_COMPLETE: WIN32_ERROR = 1003u32; -pub const ERROR_CAPAUTHZ_CHANGE_TYPE: WIN32_ERROR = 451u32; -pub const ERROR_CAPAUTHZ_DB_CORRUPTED: WIN32_ERROR = 455u32; -pub const ERROR_CAPAUTHZ_NOT_AUTHORIZED: WIN32_ERROR = 453u32; -pub const ERROR_CAPAUTHZ_NOT_DEVUNLOCKED: WIN32_ERROR = 450u32; -pub const ERROR_CAPAUTHZ_NOT_PROVISIONED: WIN32_ERROR = 452u32; -pub const ERROR_CAPAUTHZ_NO_POLICY: WIN32_ERROR = 454u32; -pub const ERROR_CAPAUTHZ_SCCD_DEV_MODE_REQUIRED: WIN32_ERROR = 459u32; -pub const ERROR_CAPAUTHZ_SCCD_INVALID_CATALOG: WIN32_ERROR = 456u32; -pub const ERROR_CAPAUTHZ_SCCD_NO_AUTH_ENTITY: WIN32_ERROR = 457u32; -pub const ERROR_CAPAUTHZ_SCCD_NO_CAPABILITY_MATCH: WIN32_ERROR = 460u32; -pub const ERROR_CAPAUTHZ_SCCD_PARSE_ERROR: WIN32_ERROR = 458u32; -pub const ERROR_CARDBUS_NOT_SUPPORTED: WIN32_ERROR = 724u32; -pub const ERROR_CASE_DIFFERING_NAMES_IN_DIR: WIN32_ERROR = 424u32; -pub const ERROR_CASE_SENSITIVE_PATH: WIN32_ERROR = 442u32; -pub const ERROR_CERTIFICATE_VALIDATION_PREFERENCE_CONFLICT: WIN32_ERROR = 817u32; -pub const ERROR_CHECKING_FILE_SYSTEM: WIN32_ERROR = 712u32; -pub const ERROR_CHECKOUT_REQUIRED: WIN32_ERROR = 221u32; -pub const ERROR_CHILD_MUST_BE_VOLATILE: WIN32_ERROR = 1021u32; -pub const ERROR_CHILD_NOT_COMPLETE: WIN32_ERROR = 129u32; -pub const ERROR_CHILD_PROCESS_BLOCKED: WIN32_ERROR = 367u32; -pub const ERROR_CHILD_WINDOW_MENU: WIN32_ERROR = 1436u32; -pub const ERROR_CIMFS_IMAGE_CORRUPT: WIN32_ERROR = 470u32; -pub const ERROR_CIMFS_IMAGE_VERSION_NOT_SUPPORTED: WIN32_ERROR = 471u32; -pub const ERROR_CIRCULAR_DEPENDENCY: WIN32_ERROR = 1059u32; -pub const ERROR_CLASS_ALREADY_EXISTS: WIN32_ERROR = 1410u32; -pub const ERROR_CLASS_DOES_NOT_EXIST: WIN32_ERROR = 1411u32; -pub const ERROR_CLASS_HAS_WINDOWS: WIN32_ERROR = 1412u32; -pub const ERROR_CLIENT_SERVER_PARAMETERS_INVALID: WIN32_ERROR = 597u32; -pub const ERROR_CLIPBOARD_NOT_OPEN: WIN32_ERROR = 1418u32; -pub const ERROR_CLOUD_FILE_ACCESS_DENIED: WIN32_ERROR = 395u32; -pub const ERROR_CLOUD_FILE_ALREADY_CONNECTED: WIN32_ERROR = 378u32; -pub const ERROR_CLOUD_FILE_AUTHENTICATION_FAILED: WIN32_ERROR = 386u32; -pub const ERROR_CLOUD_FILE_CONNECTED_PROVIDER_ONLY: WIN32_ERROR = 382u32; -pub const ERROR_CLOUD_FILE_DEHYDRATION_DISALLOWED: WIN32_ERROR = 434u32; -pub const ERROR_CLOUD_FILE_INCOMPATIBLE_HARDLINKS: WIN32_ERROR = 396u32; -pub const ERROR_CLOUD_FILE_INSUFFICIENT_RESOURCES: WIN32_ERROR = 387u32; -pub const ERROR_CLOUD_FILE_INVALID_REQUEST: WIN32_ERROR = 380u32; -pub const ERROR_CLOUD_FILE_IN_USE: WIN32_ERROR = 391u32; -pub const ERROR_CLOUD_FILE_METADATA_CORRUPT: WIN32_ERROR = 363u32; -pub const ERROR_CLOUD_FILE_METADATA_TOO_LARGE: WIN32_ERROR = 364u32; -pub const ERROR_CLOUD_FILE_NETWORK_UNAVAILABLE: WIN32_ERROR = 388u32; -pub const ERROR_CLOUD_FILE_NOT_IN_SYNC: WIN32_ERROR = 377u32; -pub const ERROR_CLOUD_FILE_NOT_SUPPORTED: WIN32_ERROR = 379u32; -pub const ERROR_CLOUD_FILE_NOT_UNDER_SYNC_ROOT: WIN32_ERROR = 390u32; -pub const ERROR_CLOUD_FILE_PINNED: WIN32_ERROR = 392u32; -pub const ERROR_CLOUD_FILE_PROPERTY_BLOB_CHECKSUM_MISMATCH: WIN32_ERROR = 366u32; -pub const ERROR_CLOUD_FILE_PROPERTY_BLOB_TOO_LARGE: WIN32_ERROR = 365u32; -pub const ERROR_CLOUD_FILE_PROPERTY_CORRUPT: WIN32_ERROR = 394u32; -pub const ERROR_CLOUD_FILE_PROPERTY_LOCK_CONFLICT: WIN32_ERROR = 397u32; -pub const ERROR_CLOUD_FILE_PROPERTY_VERSION_NOT_SUPPORTED: WIN32_ERROR = 375u32; -pub const ERROR_CLOUD_FILE_PROVIDER_NOT_RUNNING: WIN32_ERROR = 362u32; -pub const ERROR_CLOUD_FILE_PROVIDER_TERMINATED: WIN32_ERROR = 404u32; -pub const ERROR_CLOUD_FILE_READ_ONLY_VOLUME: WIN32_ERROR = 381u32; -pub const ERROR_CLOUD_FILE_REQUEST_ABORTED: WIN32_ERROR = 393u32; -pub const ERROR_CLOUD_FILE_REQUEST_CANCELED: WIN32_ERROR = 398u32; -pub const ERROR_CLOUD_FILE_REQUEST_TIMEOUT: WIN32_ERROR = 426u32; -pub const ERROR_CLOUD_FILE_SYNC_ROOT_METADATA_CORRUPT: WIN32_ERROR = 358u32; -pub const ERROR_CLOUD_FILE_TOO_MANY_PROPERTY_BLOBS: WIN32_ERROR = 374u32; -pub const ERROR_CLOUD_FILE_UNSUCCESSFUL: WIN32_ERROR = 389u32; -pub const ERROR_CLOUD_FILE_US_MESSAGE_TIMEOUT: WIN32_ERROR = 475u32; -pub const ERROR_CLOUD_FILE_VALIDATION_FAILED: WIN32_ERROR = 383u32; -pub const ERROR_COMMITMENT_LIMIT: WIN32_ERROR = 1455u32; -pub const ERROR_COMMITMENT_MINIMUM: WIN32_ERROR = 635u32; -pub const ERROR_COMPRESSED_FILE_NOT_SUPPORTED: WIN32_ERROR = 335u32; -pub const ERROR_COMPRESSION_DISABLED: WIN32_ERROR = 769u32; -pub const ERROR_COMPRESSION_NOT_BENEFICIAL: WIN32_ERROR = 344u32; -pub const ERROR_CONNECTED_OTHER_PASSWORD: WIN32_ERROR = 2108u32; -pub const ERROR_CONNECTED_OTHER_PASSWORD_DEFAULT: WIN32_ERROR = 2109u32; -pub const ERROR_CONNECTION_ABORTED: WIN32_ERROR = 1236u32; -pub const ERROR_CONNECTION_ACTIVE: WIN32_ERROR = 1230u32; -pub const ERROR_CONNECTION_COUNT_LIMIT: WIN32_ERROR = 1238u32; -pub const ERROR_CONNECTION_INVALID: WIN32_ERROR = 1229u32; -pub const ERROR_CONNECTION_REFUSED: WIN32_ERROR = 1225u32; -pub const ERROR_CONNECTION_UNAVAIL: WIN32_ERROR = 1201u32; -pub const ERROR_CONTAINER_ASSIGNED: WIN32_ERROR = 1504u32; -pub const ERROR_CONTENT_BLOCKED: WIN32_ERROR = 1296u32; -pub const ERROR_CONTEXT_EXPIRED: WIN32_ERROR = 1931u32; -pub const ERROR_CONTINUE: WIN32_ERROR = 1246u32; -pub const ERROR_CONTROL_C_EXIT: WIN32_ERROR = 572u32; -pub const ERROR_CONTROL_ID_NOT_FOUND: WIN32_ERROR = 1421u32; -pub const ERROR_CONVERT_TO_LARGE: WIN32_ERROR = 600u32; -pub const ERROR_CORRUPT_LOG_CLEARED: WIN32_ERROR = 798u32; -pub const ERROR_CORRUPT_LOG_CORRUPTED: WIN32_ERROR = 795u32; -pub const ERROR_CORRUPT_LOG_DELETED_FULL: WIN32_ERROR = 797u32; -pub const ERROR_CORRUPT_LOG_OVERFULL: WIN32_ERROR = 794u32; -pub const ERROR_CORRUPT_LOG_UNAVAILABLE: WIN32_ERROR = 796u32; -pub const ERROR_CORRUPT_SYSTEM_FILE: WIN32_ERROR = 634u32; -pub const ERROR_COULD_NOT_INTERPRET: WIN32_ERROR = 552u32; -pub const ERROR_COUNTER_TIMEOUT: WIN32_ERROR = 1121u32; -pub const ERROR_CPU_SET_INVALID: WIN32_ERROR = 813u32; -pub const ERROR_CRASH_DUMP: WIN32_ERROR = 753u32; -pub const ERROR_CRC: WIN32_ERROR = 23u32; -pub const ERROR_CREATE_FAILED: WIN32_ERROR = 1631u32; -pub const ERROR_CROSS_PARTITION_VIOLATION: WIN32_ERROR = 1661u32; -pub const ERROR_CSCSHARE_OFFLINE: WIN32_ERROR = 1262u32; -pub const ERROR_CS_ENCRYPTION_EXISTING_ENCRYPTED_FILE: WIN32_ERROR = 6019u32; -pub const ERROR_CS_ENCRYPTION_FILE_NOT_CSE: WIN32_ERROR = 6021u32; -pub const ERROR_CS_ENCRYPTION_INVALID_SERVER_RESPONSE: WIN32_ERROR = 6017u32; -pub const ERROR_CS_ENCRYPTION_NEW_ENCRYPTED_FILE: WIN32_ERROR = 6020u32; -pub const ERROR_CS_ENCRYPTION_UNSUPPORTED_SERVER: WIN32_ERROR = 6018u32; -pub const ERROR_CTX_CLIENT_QUERY_TIMEOUT: WIN32_ERROR = 7040u32; -pub const ERROR_CTX_MODEM_RESPONSE_TIMEOUT: WIN32_ERROR = 7012u32; -pub const ERROR_CURRENT_DIRECTORY: WIN32_ERROR = 16u32; -pub const ERROR_CURRENT_DOMAIN_NOT_ALLOWED: WIN32_ERROR = 1399u32; -pub const ERROR_DATABASE_DOES_NOT_EXIST: WIN32_ERROR = 1065u32; -pub const ERROR_DATATYPE_MISMATCH: WIN32_ERROR = 1629u32; -pub const ERROR_DATA_CHECKSUM_ERROR: WIN32_ERROR = 323u32; -pub const ERROR_DATA_NOT_ACCEPTED: WIN32_ERROR = 592u32; -pub const ERROR_DAX_MAPPING_EXISTS: WIN32_ERROR = 361u32; -pub const ERROR_DBG_COMMAND_EXCEPTION: WIN32_ERROR = 697u32; -pub const ERROR_DBG_CONTINUE: WIN32_ERROR = 767u32; -pub const ERROR_DBG_CONTROL_BREAK: WIN32_ERROR = 696u32; -pub const ERROR_DBG_CONTROL_C: WIN32_ERROR = 693u32; -pub const ERROR_DBG_EXCEPTION_HANDLED: WIN32_ERROR = 766u32; -pub const ERROR_DBG_EXCEPTION_NOT_HANDLED: WIN32_ERROR = 688u32; -pub const ERROR_DBG_PRINTEXCEPTION_C: WIN32_ERROR = 694u32; -pub const ERROR_DBG_REPLY_LATER: WIN32_ERROR = 689u32; -pub const ERROR_DBG_RIPEXCEPTION: WIN32_ERROR = 695u32; -pub const ERROR_DBG_TERMINATE_PROCESS: WIN32_ERROR = 692u32; -pub const ERROR_DBG_TERMINATE_THREAD: WIN32_ERROR = 691u32; -pub const ERROR_DBG_UNABLE_TO_PROVIDE_HANDLE: WIN32_ERROR = 690u32; -pub const ERROR_DC_NOT_FOUND: WIN32_ERROR = 1425u32; -pub const ERROR_DDE_FAIL: WIN32_ERROR = 1156u32; -pub const ERROR_DEBUGGER_INACTIVE: WIN32_ERROR = 1284u32; -pub const ERROR_DEBUG_ATTACH_FAILED: WIN32_ERROR = 590u32; -pub const ERROR_DECRYPTION_FAILED: WIN32_ERROR = 6001u32; -pub const ERROR_DELAY_LOAD_FAILED: WIN32_ERROR = 1285u32; -pub const ERROR_DELETE_PENDING: WIN32_ERROR = 303u32; -pub const ERROR_DEPENDENT_SERVICES_RUNNING: WIN32_ERROR = 1051u32; -pub const ERROR_DESTINATION_ELEMENT_FULL: WIN32_ERROR = 1161u32; -pub const ERROR_DESTROY_OBJECT_OF_OTHER_THREAD: WIN32_ERROR = 1435u32; -pub const ERROR_DEVICE_ALREADY_ATTACHED: WIN32_ERROR = 548u32; -pub const ERROR_DEVICE_ALREADY_REMEMBERED: WIN32_ERROR = 1202u32; -pub const ERROR_DEVICE_DOOR_OPEN: WIN32_ERROR = 1166u32; -pub const ERROR_DEVICE_ENUMERATION_ERROR: WIN32_ERROR = 648u32; -pub const ERROR_DEVICE_FEATURE_NOT_SUPPORTED: WIN32_ERROR = 316u32; -pub const ERROR_DEVICE_HARDWARE_ERROR: WIN32_ERROR = 483u32; -pub const ERROR_DEVICE_HINT_NAME_BUFFER_TOO_SMALL: WIN32_ERROR = 355u32; -pub const ERROR_DEVICE_IN_MAINTENANCE: WIN32_ERROR = 359u32; -pub const ERROR_DEVICE_IN_USE: WIN32_ERROR = 2404u32; -pub const ERROR_DEVICE_NOT_CONNECTED: WIN32_ERROR = 1167u32; -pub const ERROR_DEVICE_NOT_PARTITIONED: WIN32_ERROR = 1107u32; -pub const ERROR_DEVICE_NO_RESOURCES: WIN32_ERROR = 322u32; -pub const ERROR_DEVICE_REINITIALIZATION_NEEDED: WIN32_ERROR = 1164u32; -pub const ERROR_DEVICE_REMOVED: WIN32_ERROR = 1617u32; -pub const ERROR_DEVICE_REQUIRES_CLEANING: WIN32_ERROR = 1165u32; -pub const ERROR_DEVICE_RESET_REQUIRED: WIN32_ERROR = 507u32; -pub const ERROR_DEVICE_SUPPORT_IN_PROGRESS: WIN32_ERROR = 171u32; -pub const ERROR_DEVICE_UNREACHABLE: WIN32_ERROR = 321u32; -pub const ERROR_DEV_NOT_EXIST: WIN32_ERROR = 55u32; -pub const ERROR_DHCP_ADDRESS_CONFLICT: WIN32_ERROR = 4100u32; -pub const ERROR_DIFFERENT_SERVICE_ACCOUNT: WIN32_ERROR = 1079u32; -pub const ERROR_DIRECTORY: WIN32_ERROR = 267u32; -pub const ERROR_DIRECTORY_NOT_SUPPORTED: WIN32_ERROR = 336u32; -pub const ERROR_DIRECT_ACCESS_HANDLE: WIN32_ERROR = 130u32; -pub const ERROR_DIR_EFS_DISALLOWED: WIN32_ERROR = 6010u32; -pub const ERROR_DIR_NOT_EMPTY: WIN32_ERROR = 145u32; -pub const ERROR_DIR_NOT_ROOT: WIN32_ERROR = 144u32; -pub const ERROR_DISCARDED: WIN32_ERROR = 157u32; -pub const ERROR_DISK_CHANGE: WIN32_ERROR = 107u32; -pub const ERROR_DISK_CORRUPT: WIN32_ERROR = 1393u32; -pub const ERROR_DISK_FULL: WIN32_ERROR = 112u32; -pub const ERROR_DISK_OPERATION_FAILED: WIN32_ERROR = 1127u32; -pub const ERROR_DISK_QUOTA_EXCEEDED: WIN32_ERROR = 1295u32; -pub const ERROR_DISK_RECALIBRATE_FAILED: WIN32_ERROR = 1126u32; -pub const ERROR_DISK_REPAIR_DISABLED: WIN32_ERROR = 780u32; -pub const ERROR_DISK_REPAIR_REDIRECTED: WIN32_ERROR = 792u32; -pub const ERROR_DISK_REPAIR_UNSUCCESSFUL: WIN32_ERROR = 793u32; -pub const ERROR_DISK_RESET_FAILED: WIN32_ERROR = 1128u32; -pub const ERROR_DISK_RESOURCES_EXHAUSTED: WIN32_ERROR = 314u32; -pub const ERROR_DISK_TOO_FRAGMENTED: WIN32_ERROR = 302u32; -pub const ERROR_DLL_INIT_FAILED: WIN32_ERROR = 1114u32; -pub const ERROR_DLL_INIT_FAILED_LOGOFF: WIN32_ERROR = 624u32; -pub const ERROR_DLL_MIGHT_BE_INCOMPATIBLE: WIN32_ERROR = 687u32; -pub const ERROR_DLL_MIGHT_BE_INSECURE: WIN32_ERROR = 686u32; -pub const ERROR_DLL_NOT_FOUND: WIN32_ERROR = 1157u32; -pub const ERROR_DLP_POLICY_DENIES_OPERATION: WIN32_ERROR = 446u32; -pub const ERROR_DLP_POLICY_SILENTLY_FAIL: WIN32_ERROR = 449u32; -pub const ERROR_DLP_POLICY_WARNS_AGAINST_OPERATION: WIN32_ERROR = 445u32; -pub const ERROR_DOMAIN_CONTROLLER_EXISTS: WIN32_ERROR = 1250u32; -pub const ERROR_DOMAIN_CONTROLLER_NOT_FOUND: WIN32_ERROR = 1908u32; -pub const ERROR_DOMAIN_CTRLR_CONFIG_ERROR: WIN32_ERROR = 581u32; -pub const ERROR_DOMAIN_EXISTS: WIN32_ERROR = 1356u32; -pub const ERROR_DOMAIN_LIMIT_EXCEEDED: WIN32_ERROR = 1357u32; -pub const ERROR_DOMAIN_SID_SAME_AS_LOCAL_WORKSTATION: WIN32_ERROR = 8644u32; -pub const ERROR_DOMAIN_TRUST_INCONSISTENT: WIN32_ERROR = 1810u32; -pub const ERROR_DOWNGRADE_DETECTED: WIN32_ERROR = 1265u32; -pub const ERROR_DPL_NOT_SUPPORTED_FOR_USER: WIN32_ERROR = 423u32; -pub const ERROR_DRIVERS_LEAKING_LOCKED_PAGES: WIN32_ERROR = 729u32; -pub const ERROR_DRIVER_BLOCKED: WIN32_ERROR = 1275u32; -pub const ERROR_DRIVER_CANCEL_TIMEOUT: WIN32_ERROR = 594u32; -pub const ERROR_DRIVER_DATABASE_ERROR: WIN32_ERROR = 652u32; -pub const ERROR_DRIVER_FAILED_PRIOR_UNLOAD: WIN32_ERROR = 654u32; -pub const ERROR_DRIVER_FAILED_SLEEP: WIN32_ERROR = 633u32; -pub const ERROR_DRIVER_PROCESS_TERMINATED: WIN32_ERROR = 1291u32; -pub const ERROR_DRIVE_LOCKED: WIN32_ERROR = 108u32; -pub const ERROR_DS_ADD_REPLICA_INHIBITED: WIN32_ERROR = 8302u32; -pub const ERROR_DS_ADMIN_LIMIT_EXCEEDED: WIN32_ERROR = 8228u32; -pub const ERROR_DS_AFFECTS_MULTIPLE_DSAS: WIN32_ERROR = 8249u32; -pub const ERROR_DS_AG_CANT_HAVE_UNIVERSAL_MEMBER: WIN32_ERROR = 8578u32; -pub const ERROR_DS_ALIASED_OBJ_MISSING: WIN32_ERROR = 8334u32; -pub const ERROR_DS_ALIAS_DEREF_PROBLEM: WIN32_ERROR = 8244u32; -pub const ERROR_DS_ALIAS_POINTS_TO_ALIAS: WIN32_ERROR = 8336u32; -pub const ERROR_DS_ALIAS_PROBLEM: WIN32_ERROR = 8241u32; -pub const ERROR_DS_ATTRIBUTE_OR_VALUE_EXISTS: WIN32_ERROR = 8205u32; -pub const ERROR_DS_ATTRIBUTE_OWNED_BY_SAM: WIN32_ERROR = 8346u32; -pub const ERROR_DS_ATTRIBUTE_TYPE_UNDEFINED: WIN32_ERROR = 8204u32; -pub const ERROR_DS_ATT_ALREADY_EXISTS: WIN32_ERROR = 8318u32; -pub const ERROR_DS_ATT_IS_NOT_ON_OBJ: WIN32_ERROR = 8310u32; -pub const ERROR_DS_ATT_NOT_DEF_FOR_CLASS: WIN32_ERROR = 8317u32; -pub const ERROR_DS_ATT_NOT_DEF_IN_SCHEMA: WIN32_ERROR = 8303u32; -pub const ERROR_DS_ATT_SCHEMA_REQ_ID: WIN32_ERROR = 8399u32; -pub const ERROR_DS_ATT_SCHEMA_REQ_SYNTAX: WIN32_ERROR = 8416u32; -pub const ERROR_DS_ATT_VAL_ALREADY_EXISTS: WIN32_ERROR = 8323u32; -pub const ERROR_DS_AUDIT_FAILURE: WIN32_ERROR = 8625u32; -pub const ERROR_DS_AUTHORIZATION_FAILED: WIN32_ERROR = 8599u32; -pub const ERROR_DS_AUTH_METHOD_NOT_SUPPORTED: WIN32_ERROR = 8231u32; -pub const ERROR_DS_AUTH_UNKNOWN: WIN32_ERROR = 8234u32; -pub const ERROR_DS_AUX_CLS_TEST_FAIL: WIN32_ERROR = 8389u32; -pub const ERROR_DS_BACKLINK_WITHOUT_LINK: WIN32_ERROR = 8482u32; -pub const ERROR_DS_BAD_ATT_SCHEMA_SYNTAX: WIN32_ERROR = 8400u32; -pub const ERROR_DS_BAD_HIERARCHY_FILE: WIN32_ERROR = 8425u32; -pub const ERROR_DS_BAD_INSTANCE_TYPE: WIN32_ERROR = 8313u32; -pub const ERROR_DS_BAD_NAME_SYNTAX: WIN32_ERROR = 8335u32; -pub const ERROR_DS_BAD_RDN_ATT_ID_SYNTAX: WIN32_ERROR = 8392u32; -pub const ERROR_DS_BUILD_HIERARCHY_TABLE_FAILED: WIN32_ERROR = 8426u32; -pub const ERROR_DS_BUSY: WIN32_ERROR = 8206u32; -pub const ERROR_DS_CANT_ACCESS_REMOTE_PART_OF_AD: WIN32_ERROR = 8585u32; -pub const ERROR_DS_CANT_ADD_ATT_VALUES: WIN32_ERROR = 8320u32; -pub const ERROR_DS_CANT_ADD_SYSTEM_ONLY: WIN32_ERROR = 8358u32; -pub const ERROR_DS_CANT_ADD_TO_GC: WIN32_ERROR = 8550u32; -pub const ERROR_DS_CANT_CACHE_ATT: WIN32_ERROR = 8401u32; -pub const ERROR_DS_CANT_CACHE_CLASS: WIN32_ERROR = 8402u32; -pub const ERROR_DS_CANT_CREATE_IN_NONDOMAIN_NC: WIN32_ERROR = 8553u32; -pub const ERROR_DS_CANT_CREATE_UNDER_SCHEMA: WIN32_ERROR = 8510u32; -pub const ERROR_DS_CANT_DELETE: WIN32_ERROR = 8398u32; -pub const ERROR_DS_CANT_DELETE_DSA_OBJ: WIN32_ERROR = 8340u32; -pub const ERROR_DS_CANT_DEL_MASTER_CROSSREF: WIN32_ERROR = 8375u32; -pub const ERROR_DS_CANT_DEMOTE_WITH_WRITEABLE_NC: WIN32_ERROR = 8604u32; -pub const ERROR_DS_CANT_DEREF_ALIAS: WIN32_ERROR = 8337u32; -pub const ERROR_DS_CANT_DERIVE_SPN_FOR_DELETED_DOMAIN: WIN32_ERROR = 8603u32; -pub const ERROR_DS_CANT_DERIVE_SPN_WITHOUT_SERVER_REF: WIN32_ERROR = 8589u32; -pub const ERROR_DS_CANT_FIND_DC_FOR_SRC_DOMAIN: WIN32_ERROR = 8537u32; -pub const ERROR_DS_CANT_FIND_DSA_OBJ: WIN32_ERROR = 8419u32; -pub const ERROR_DS_CANT_FIND_EXPECTED_NC: WIN32_ERROR = 8420u32; -pub const ERROR_DS_CANT_FIND_NC_IN_CACHE: WIN32_ERROR = 8421u32; -pub const ERROR_DS_CANT_MIX_MASTER_AND_REPS: WIN32_ERROR = 8331u32; -pub const ERROR_DS_CANT_MOD_OBJ_CLASS: WIN32_ERROR = 8215u32; -pub const ERROR_DS_CANT_MOD_PRIMARYGROUPID: WIN32_ERROR = 8506u32; -pub const ERROR_DS_CANT_MOD_SYSTEM_ONLY: WIN32_ERROR = 8369u32; -pub const ERROR_DS_CANT_MOVE_ACCOUNT_GROUP: WIN32_ERROR = 8498u32; -pub const ERROR_DS_CANT_MOVE_APP_BASIC_GROUP: WIN32_ERROR = 8608u32; -pub const ERROR_DS_CANT_MOVE_APP_QUERY_GROUP: WIN32_ERROR = 8609u32; -pub const ERROR_DS_CANT_MOVE_DELETED_OBJECT: WIN32_ERROR = 8489u32; -pub const ERROR_DS_CANT_MOVE_RESOURCE_GROUP: WIN32_ERROR = 8499u32; -pub const ERROR_DS_CANT_ON_NON_LEAF: WIN32_ERROR = 8213u32; -pub const ERROR_DS_CANT_ON_RDN: WIN32_ERROR = 8214u32; -pub const ERROR_DS_CANT_REMOVE_ATT_CACHE: WIN32_ERROR = 8403u32; -pub const ERROR_DS_CANT_REMOVE_CLASS_CACHE: WIN32_ERROR = 8404u32; -pub const ERROR_DS_CANT_REM_MISSING_ATT: WIN32_ERROR = 8324u32; -pub const ERROR_DS_CANT_REM_MISSING_ATT_VAL: WIN32_ERROR = 8325u32; -pub const ERROR_DS_CANT_REPLACE_HIDDEN_REC: WIN32_ERROR = 8424u32; -pub const ERROR_DS_CANT_RETRIEVE_ATTS: WIN32_ERROR = 8481u32; -pub const ERROR_DS_CANT_RETRIEVE_CHILD: WIN32_ERROR = 8422u32; -pub const ERROR_DS_CANT_RETRIEVE_DN: WIN32_ERROR = 8405u32; -pub const ERROR_DS_CANT_RETRIEVE_INSTANCE: WIN32_ERROR = 8407u32; -pub const ERROR_DS_CANT_RETRIEVE_SD: WIN32_ERROR = 8526u32; -pub const ERROR_DS_CANT_START: WIN32_ERROR = 8531u32; -pub const ERROR_DS_CANT_TREE_DELETE_CRITICAL_OBJ: WIN32_ERROR = 8560u32; -pub const ERROR_DS_CANT_WITH_ACCT_GROUP_MEMBERSHPS: WIN32_ERROR = 8493u32; -pub const ERROR_DS_CHILDREN_EXIST: WIN32_ERROR = 8332u32; -pub const ERROR_DS_CLASS_MUST_BE_CONCRETE: WIN32_ERROR = 8359u32; -pub const ERROR_DS_CLASS_NOT_DSA: WIN32_ERROR = 8343u32; -pub const ERROR_DS_CLIENT_LOOP: WIN32_ERROR = 8259u32; -pub const ERROR_DS_CODE_INCONSISTENCY: WIN32_ERROR = 8408u32; -pub const ERROR_DS_COMPARE_FALSE: WIN32_ERROR = 8229u32; -pub const ERROR_DS_COMPARE_TRUE: WIN32_ERROR = 8230u32; -pub const ERROR_DS_CONFIDENTIALITY_REQUIRED: WIN32_ERROR = 8237u32; -pub const ERROR_DS_CONFIG_PARAM_MISSING: WIN32_ERROR = 8427u32; -pub const ERROR_DS_CONSTRAINT_VIOLATION: WIN32_ERROR = 8239u32; -pub const ERROR_DS_CONSTRUCTED_ATT_MOD: WIN32_ERROR = 8475u32; -pub const ERROR_DS_CONTROL_NOT_FOUND: WIN32_ERROR = 8258u32; -pub const ERROR_DS_COULDNT_CONTACT_FSMO: WIN32_ERROR = 8367u32; -pub const ERROR_DS_COULDNT_IDENTIFY_OBJECTS_FOR_TREE_DELETE: WIN32_ERROR = 8503u32; -pub const ERROR_DS_COULDNT_LOCK_TREE_FOR_DELETE: WIN32_ERROR = 8502u32; -pub const ERROR_DS_COULDNT_UPDATE_SPNS: WIN32_ERROR = 8525u32; -pub const ERROR_DS_COUNTING_AB_INDICES_FAILED: WIN32_ERROR = 8428u32; -pub const ERROR_DS_CROSS_DOMAIN_CLEANUP_REQD: WIN32_ERROR = 8491u32; -pub const ERROR_DS_CROSS_DOM_MOVE_ERROR: WIN32_ERROR = 8216u32; -pub const ERROR_DS_CROSS_NC_DN_RENAME: WIN32_ERROR = 8368u32; -pub const ERROR_DS_CROSS_REF_BUSY: WIN32_ERROR = 8602u32; -pub const ERROR_DS_CROSS_REF_EXISTS: WIN32_ERROR = 8374u32; -pub const ERROR_DS_CR_IMPOSSIBLE_TO_VALIDATE: WIN32_ERROR = 8495u32; -pub const ERROR_DS_CR_IMPOSSIBLE_TO_VALIDATE_V2: WIN32_ERROR = 8586u32; -pub const ERROR_DS_DATABASE_ERROR: WIN32_ERROR = 8409u32; -pub const ERROR_DS_DECODING_ERROR: WIN32_ERROR = 8253u32; -pub const ERROR_DS_DESTINATION_AUDITING_NOT_ENABLED: WIN32_ERROR = 8536u32; -pub const ERROR_DS_DESTINATION_DOMAIN_NOT_IN_FOREST: WIN32_ERROR = 8535u32; -pub const ERROR_DS_DIFFERENT_REPL_EPOCHS: WIN32_ERROR = 8593u32; -pub const ERROR_DS_DISALLOWED_IN_SYSTEM_CONTAINER: WIN32_ERROR = 8615u32; -pub const ERROR_DS_DISALLOWED_NC_REDIRECT: WIN32_ERROR = 8640u32; -pub const ERROR_DS_DNS_LOOKUP_FAILURE: WIN32_ERROR = 8524u32; -pub const ERROR_DS_DOMAIN_NAME_EXISTS_IN_FOREST: WIN32_ERROR = 8634u32; -pub const ERROR_DS_DOMAIN_RENAME_IN_PROGRESS: WIN32_ERROR = 8612u32; -pub const ERROR_DS_DOMAIN_VERSION_TOO_HIGH: WIN32_ERROR = 8564u32; -pub const ERROR_DS_DOMAIN_VERSION_TOO_LOW: WIN32_ERROR = 8566u32; -pub const ERROR_DS_DRA_ABANDON_SYNC: WIN32_ERROR = 8462u32; -pub const ERROR_DS_DRA_ACCESS_DENIED: WIN32_ERROR = 8453u32; -pub const ERROR_DS_DRA_BAD_DN: WIN32_ERROR = 8439u32; -pub const ERROR_DS_DRA_BAD_INSTANCE_TYPE: WIN32_ERROR = 8445u32; -pub const ERROR_DS_DRA_BAD_NC: WIN32_ERROR = 8440u32; -pub const ERROR_DS_DRA_BUSY: WIN32_ERROR = 8438u32; -pub const ERROR_DS_DRA_CONNECTION_FAILED: WIN32_ERROR = 8444u32; -pub const ERROR_DS_DRA_CORRUPT_UTD_VECTOR: WIN32_ERROR = 8629u32; -pub const ERROR_DS_DRA_DB_ERROR: WIN32_ERROR = 8451u32; -pub const ERROR_DS_DRA_DN_EXISTS: WIN32_ERROR = 8441u32; -pub const ERROR_DS_DRA_EARLIER_SCHEMA_CONFLICT: WIN32_ERROR = 8544u32; -pub const ERROR_DS_DRA_EXTN_CONNECTION_FAILED: WIN32_ERROR = 8466u32; -pub const ERROR_DS_DRA_GENERIC: WIN32_ERROR = 8436u32; -pub const ERROR_DS_DRA_INCOMPATIBLE_PARTIAL_SET: WIN32_ERROR = 8464u32; -pub const ERROR_DS_DRA_INCONSISTENT_DIT: WIN32_ERROR = 8443u32; -pub const ERROR_DS_DRA_INTERNAL_ERROR: WIN32_ERROR = 8442u32; -pub const ERROR_DS_DRA_INVALID_PARAMETER: WIN32_ERROR = 8437u32; -pub const ERROR_DS_DRA_MAIL_PROBLEM: WIN32_ERROR = 8447u32; -pub const ERROR_DS_DRA_MISSING_KRBTGT_SECRET: WIN32_ERROR = 8633u32; -pub const ERROR_DS_DRA_MISSING_PARENT: WIN32_ERROR = 8460u32; -pub const ERROR_DS_DRA_NAME_COLLISION: WIN32_ERROR = 8458u32; -pub const ERROR_DS_DRA_NOT_SUPPORTED: WIN32_ERROR = 8454u32; -pub const ERROR_DS_DRA_NO_REPLICA: WIN32_ERROR = 8452u32; -pub const ERROR_DS_DRA_OBJ_IS_REP_SOURCE: WIN32_ERROR = 8450u32; -pub const ERROR_DS_DRA_OBJ_NC_MISMATCH: WIN32_ERROR = 8545u32; -pub const ERROR_DS_DRA_OUT_OF_MEM: WIN32_ERROR = 8446u32; -pub const ERROR_DS_DRA_OUT_SCHEDULE_WINDOW: WIN32_ERROR = 8617u32; -pub const ERROR_DS_DRA_PREEMPTED: WIN32_ERROR = 8461u32; -pub const ERROR_DS_DRA_RECYCLED_TARGET: WIN32_ERROR = 8639u32; -pub const ERROR_DS_DRA_REF_ALREADY_EXISTS: WIN32_ERROR = 8448u32; -pub const ERROR_DS_DRA_REF_NOT_FOUND: WIN32_ERROR = 8449u32; -pub const ERROR_DS_DRA_REPL_PENDING: WIN32_ERROR = 8477u32; -pub const ERROR_DS_DRA_RPC_CANCELLED: WIN32_ERROR = 8455u32; -pub const ERROR_DS_DRA_SCHEMA_CONFLICT: WIN32_ERROR = 8543u32; -pub const ERROR_DS_DRA_SCHEMA_INFO_SHIP: WIN32_ERROR = 8542u32; -pub const ERROR_DS_DRA_SCHEMA_MISMATCH: WIN32_ERROR = 8418u32; -pub const ERROR_DS_DRA_SECRETS_DENIED: WIN32_ERROR = 8630u32; -pub const ERROR_DS_DRA_SHUTDOWN: WIN32_ERROR = 8463u32; -pub const ERROR_DS_DRA_SINK_DISABLED: WIN32_ERROR = 8457u32; -pub const ERROR_DS_DRA_SOURCE_DISABLED: WIN32_ERROR = 8456u32; -pub const ERROR_DS_DRA_SOURCE_IS_PARTIAL_REPLICA: WIN32_ERROR = 8465u32; -pub const ERROR_DS_DRA_SOURCE_REINSTALLED: WIN32_ERROR = 8459u32; -pub const ERROR_DS_DRS_EXTENSIONS_CHANGED: WIN32_ERROR = 8594u32; -pub const ERROR_DS_DSA_MUST_BE_INT_MASTER: WIN32_ERROR = 8342u32; -pub const ERROR_DS_DST_DOMAIN_NOT_NATIVE: WIN32_ERROR = 8496u32; -pub const ERROR_DS_DST_NC_MISMATCH: WIN32_ERROR = 8486u32; -pub const ERROR_DS_DS_REQUIRED: WIN32_ERROR = 8478u32; -pub const ERROR_DS_DUPLICATE_ID_FOUND: WIN32_ERROR = 8605u32; -pub const ERROR_DS_DUP_LDAP_DISPLAY_NAME: WIN32_ERROR = 8382u32; -pub const ERROR_DS_DUP_LINK_ID: WIN32_ERROR = 8468u32; -pub const ERROR_DS_DUP_MAPI_ID: WIN32_ERROR = 8380u32; -pub const ERROR_DS_DUP_MSDS_INTID: WIN32_ERROR = 8597u32; -pub const ERROR_DS_DUP_OID: WIN32_ERROR = 8379u32; -pub const ERROR_DS_DUP_RDN: WIN32_ERROR = 8378u32; -pub const ERROR_DS_DUP_SCHEMA_ID_GUID: WIN32_ERROR = 8381u32; -pub const ERROR_DS_ENCODING_ERROR: WIN32_ERROR = 8252u32; -pub const ERROR_DS_EPOCH_MISMATCH: WIN32_ERROR = 8483u32; -pub const ERROR_DS_EXISTING_AD_CHILD_NC: WIN32_ERROR = 8613u32; -pub const ERROR_DS_EXISTS_IN_AUX_CLS: WIN32_ERROR = 8393u32; -pub const ERROR_DS_EXISTS_IN_MAY_HAVE: WIN32_ERROR = 8386u32; -pub const ERROR_DS_EXISTS_IN_MUST_HAVE: WIN32_ERROR = 8385u32; -pub const ERROR_DS_EXISTS_IN_POSS_SUP: WIN32_ERROR = 8395u32; -pub const ERROR_DS_EXISTS_IN_RDNATTID: WIN32_ERROR = 8598u32; -pub const ERROR_DS_EXISTS_IN_SUB_CLS: WIN32_ERROR = 8394u32; -pub const ERROR_DS_FILTER_UNKNOWN: WIN32_ERROR = 8254u32; -pub const ERROR_DS_FILTER_USES_CONTRUCTED_ATTRS: WIN32_ERROR = 8555u32; -pub const ERROR_DS_FLAT_NAME_EXISTS_IN_FOREST: WIN32_ERROR = 8635u32; -pub const ERROR_DS_FOREST_VERSION_TOO_HIGH: WIN32_ERROR = 8563u32; -pub const ERROR_DS_FOREST_VERSION_TOO_LOW: WIN32_ERROR = 8565u32; -pub const ERROR_DS_GCVERIFY_ERROR: WIN32_ERROR = 8417u32; -pub const ERROR_DS_GC_NOT_AVAILABLE: WIN32_ERROR = 8217u32; -pub const ERROR_DS_GC_REQUIRED: WIN32_ERROR = 8547u32; -pub const ERROR_DS_GENERIC_ERROR: WIN32_ERROR = 8341u32; -pub const ERROR_DS_GLOBAL_CANT_HAVE_CROSSDOMAIN_MEMBER: WIN32_ERROR = 8519u32; -pub const ERROR_DS_GLOBAL_CANT_HAVE_LOCAL_MEMBER: WIN32_ERROR = 8516u32; -pub const ERROR_DS_GLOBAL_CANT_HAVE_UNIVERSAL_MEMBER: WIN32_ERROR = 8517u32; -pub const ERROR_DS_GOVERNSID_MISSING: WIN32_ERROR = 8410u32; -pub const ERROR_DS_GROUP_CONVERSION_ERROR: WIN32_ERROR = 8607u32; -pub const ERROR_DS_HAVE_PRIMARY_MEMBERS: WIN32_ERROR = 8521u32; -pub const ERROR_DS_HIERARCHY_TABLE_MALLOC_FAILED: WIN32_ERROR = 8429u32; -pub const ERROR_DS_HIERARCHY_TABLE_TOO_DEEP: WIN32_ERROR = 8628u32; -pub const ERROR_DS_HIGH_ADLDS_FFL: WIN32_ERROR = 8641u32; -pub const ERROR_DS_HIGH_DSA_VERSION: WIN32_ERROR = 8642u32; -pub const ERROR_DS_ILLEGAL_BASE_SCHEMA_MOD: WIN32_ERROR = 8507u32; -pub const ERROR_DS_ILLEGAL_MOD_OPERATION: WIN32_ERROR = 8311u32; -pub const ERROR_DS_ILLEGAL_SUPERIOR: WIN32_ERROR = 8345u32; -pub const ERROR_DS_ILLEGAL_XDOM_MOVE_OPERATION: WIN32_ERROR = 8492u32; -pub const ERROR_DS_INAPPROPRIATE_AUTH: WIN32_ERROR = 8233u32; -pub const ERROR_DS_INAPPROPRIATE_MATCHING: WIN32_ERROR = 8238u32; -pub const ERROR_DS_INCOMPATIBLE_CONTROLS_USED: WIN32_ERROR = 8574u32; -pub const ERROR_DS_INCOMPATIBLE_VERSION: WIN32_ERROR = 8567u32; -pub const ERROR_DS_INCORRECT_ROLE_OWNER: WIN32_ERROR = 8210u32; -pub const ERROR_DS_INIT_FAILURE: WIN32_ERROR = 8532u32; -pub const ERROR_DS_INIT_FAILURE_CONSOLE: WIN32_ERROR = 8561u32; -pub const ERROR_DS_INSTALL_NO_SCH_VERSION_IN_INIFILE: WIN32_ERROR = 8512u32; -pub const ERROR_DS_INSTALL_NO_SRC_SCH_VERSION: WIN32_ERROR = 8511u32; -pub const ERROR_DS_INSTALL_SCHEMA_MISMATCH: WIN32_ERROR = 8467u32; -pub const ERROR_DS_INSUFFICIENT_ATTR_TO_CREATE_OBJECT: WIN32_ERROR = 8606u32; -pub const ERROR_DS_INSUFF_ACCESS_RIGHTS: WIN32_ERROR = 8344u32; -pub const ERROR_DS_INTERNAL_FAILURE: WIN32_ERROR = 8430u32; -pub const ERROR_DS_INVALID_ATTRIBUTE_SYNTAX: WIN32_ERROR = 8203u32; -pub const ERROR_DS_INVALID_DMD: WIN32_ERROR = 8360u32; -pub const ERROR_DS_INVALID_DN_SYNTAX: WIN32_ERROR = 8242u32; -pub const ERROR_DS_INVALID_GROUP_TYPE: WIN32_ERROR = 8513u32; -pub const ERROR_DS_INVALID_LDAP_DISPLAY_NAME: WIN32_ERROR = 8479u32; -pub const ERROR_DS_INVALID_NAME_FOR_SPN: WIN32_ERROR = 8554u32; -pub const ERROR_DS_INVALID_ROLE_OWNER: WIN32_ERROR = 8366u32; -pub const ERROR_DS_INVALID_SCRIPT: WIN32_ERROR = 8600u32; -pub const ERROR_DS_INVALID_SEARCH_FLAG: WIN32_ERROR = 8500u32; -pub const ERROR_DS_INVALID_SEARCH_FLAG_SUBTREE: WIN32_ERROR = 8626u32; -pub const ERROR_DS_INVALID_SEARCH_FLAG_TUPLE: WIN32_ERROR = 8627u32; -pub const ERROR_DS_IS_LEAF: WIN32_ERROR = 8243u32; -pub const ERROR_DS_KEY_NOT_UNIQUE: WIN32_ERROR = 8527u32; -pub const ERROR_DS_LDAP_SEND_QUEUE_FULL: WIN32_ERROR = 8616u32; -pub const ERROR_DS_LINK_ID_NOT_AVAILABLE: WIN32_ERROR = 8577u32; -pub const ERROR_DS_LOCAL_CANT_HAVE_CROSSDOMAIN_LOCAL_MEMBER: WIN32_ERROR = 8520u32; -pub const ERROR_DS_LOCAL_ERROR: WIN32_ERROR = 8251u32; -pub const ERROR_DS_LOCAL_MEMBER_OF_LOCAL_ONLY: WIN32_ERROR = 8548u32; -pub const ERROR_DS_LOOP_DETECT: WIN32_ERROR = 8246u32; -pub const ERROR_DS_LOW_ADLDS_FFL: WIN32_ERROR = 8643u32; -pub const ERROR_DS_LOW_DSA_VERSION: WIN32_ERROR = 8568u32; -pub const ERROR_DS_MACHINE_ACCOUNT_CREATED_PRENT4: WIN32_ERROR = 8572u32; -pub const ERROR_DS_MACHINE_ACCOUNT_QUOTA_EXCEEDED: WIN32_ERROR = 8557u32; -pub const ERROR_DS_MAPI_ID_NOT_AVAILABLE: WIN32_ERROR = 8632u32; -pub const ERROR_DS_MASTERDSA_REQUIRED: WIN32_ERROR = 8314u32; -pub const ERROR_DS_MAX_OBJ_SIZE_EXCEEDED: WIN32_ERROR = 8304u32; -pub const ERROR_DS_MEMBERSHIP_EVALUATED_LOCALLY: WIN32_ERROR = 8201u32; -pub const ERROR_DS_MISSING_EXPECTED_ATT: WIN32_ERROR = 8411u32; -pub const ERROR_DS_MISSING_FOREST_TRUST: WIN32_ERROR = 8649u32; -pub const ERROR_DS_MISSING_FSMO_SETTINGS: WIN32_ERROR = 8434u32; -pub const ERROR_DS_MISSING_INFRASTRUCTURE_CONTAINER: WIN32_ERROR = 8497u32; -pub const ERROR_DS_MISSING_REQUIRED_ATT: WIN32_ERROR = 8316u32; -pub const ERROR_DS_MISSING_SUPREF: WIN32_ERROR = 8406u32; -pub const ERROR_DS_MODIFYDN_DISALLOWED_BY_FLAG: WIN32_ERROR = 8581u32; -pub const ERROR_DS_MODIFYDN_DISALLOWED_BY_INSTANCE_TYPE: WIN32_ERROR = 8579u32; -pub const ERROR_DS_MODIFYDN_WRONG_GRANDPARENT: WIN32_ERROR = 8582u32; -pub const ERROR_DS_MUST_BE_RUN_ON_DST_DC: WIN32_ERROR = 8558u32; -pub const ERROR_DS_NAME_ERROR_DOMAIN_ONLY: WIN32_ERROR = 8473u32; -pub const ERROR_DS_NAME_ERROR_NOT_FOUND: WIN32_ERROR = 8470u32; -pub const ERROR_DS_NAME_ERROR_NOT_UNIQUE: WIN32_ERROR = 8471u32; -pub const ERROR_DS_NAME_ERROR_NO_MAPPING: WIN32_ERROR = 8472u32; -pub const ERROR_DS_NAME_ERROR_NO_SYNTACTICAL_MAPPING: WIN32_ERROR = 8474u32; -pub const ERROR_DS_NAME_ERROR_RESOLVING: WIN32_ERROR = 8469u32; -pub const ERROR_DS_NAME_ERROR_TRUST_REFERRAL: WIN32_ERROR = 8583u32; -pub const ERROR_DS_NAME_NOT_UNIQUE: WIN32_ERROR = 8571u32; -pub const ERROR_DS_NAME_REFERENCE_INVALID: WIN32_ERROR = 8373u32; -pub const ERROR_DS_NAME_TOO_LONG: WIN32_ERROR = 8348u32; -pub const ERROR_DS_NAME_TOO_MANY_PARTS: WIN32_ERROR = 8347u32; -pub const ERROR_DS_NAME_TYPE_UNKNOWN: WIN32_ERROR = 8351u32; -pub const ERROR_DS_NAME_UNPARSEABLE: WIN32_ERROR = 8350u32; -pub const ERROR_DS_NAME_VALUE_TOO_LONG: WIN32_ERROR = 8349u32; -pub const ERROR_DS_NAMING_MASTER_GC: WIN32_ERROR = 8523u32; -pub const ERROR_DS_NAMING_VIOLATION: WIN32_ERROR = 8247u32; -pub const ERROR_DS_NCNAME_MISSING_CR_REF: WIN32_ERROR = 8412u32; -pub const ERROR_DS_NCNAME_MUST_BE_NC: WIN32_ERROR = 8357u32; -pub const ERROR_DS_NC_MUST_HAVE_NC_PARENT: WIN32_ERROR = 8494u32; -pub const ERROR_DS_NC_STILL_HAS_DSAS: WIN32_ERROR = 8546u32; -pub const ERROR_DS_NONEXISTENT_MAY_HAVE: WIN32_ERROR = 8387u32; -pub const ERROR_DS_NONEXISTENT_MUST_HAVE: WIN32_ERROR = 8388u32; -pub const ERROR_DS_NONEXISTENT_POSS_SUP: WIN32_ERROR = 8390u32; -pub const ERROR_DS_NONSAFE_SCHEMA_CHANGE: WIN32_ERROR = 8508u32; -pub const ERROR_DS_NON_ASQ_SEARCH: WIN32_ERROR = 8624u32; -pub const ERROR_DS_NON_BASE_SEARCH: WIN32_ERROR = 8480u32; -pub const ERROR_DS_NOTIFY_FILTER_TOO_COMPLEX: WIN32_ERROR = 8377u32; -pub const ERROR_DS_NOT_AN_OBJECT: WIN32_ERROR = 8352u32; -pub const ERROR_DS_NOT_AUTHORITIVE_FOR_DST_NC: WIN32_ERROR = 8487u32; -pub const ERROR_DS_NOT_CLOSEST: WIN32_ERROR = 8588u32; -pub const ERROR_DS_NOT_INSTALLED: WIN32_ERROR = 8200u32; -pub const ERROR_DS_NOT_ON_BACKLINK: WIN32_ERROR = 8362u32; -pub const ERROR_DS_NOT_SUPPORTED: WIN32_ERROR = 8256u32; -pub const ERROR_DS_NOT_SUPPORTED_SORT_ORDER: WIN32_ERROR = 8570u32; -pub const ERROR_DS_NO_ATTRIBUTE_OR_VALUE: WIN32_ERROR = 8202u32; -pub const ERROR_DS_NO_BEHAVIOR_VERSION_IN_MIXEDDOMAIN: WIN32_ERROR = 8569u32; -pub const ERROR_DS_NO_CHAINED_EVAL: WIN32_ERROR = 8328u32; -pub const ERROR_DS_NO_CHAINING: WIN32_ERROR = 8327u32; -pub const ERROR_DS_NO_CHECKPOINT_WITH_PDC: WIN32_ERROR = 8551u32; -pub const ERROR_DS_NO_CROSSREF_FOR_NC: WIN32_ERROR = 8363u32; -pub const ERROR_DS_NO_DELETED_NAME: WIN32_ERROR = 8355u32; -pub const ERROR_DS_NO_FPO_IN_UNIVERSAL_GROUPS: WIN32_ERROR = 8549u32; -pub const ERROR_DS_NO_MORE_RIDS: WIN32_ERROR = 8209u32; -pub const ERROR_DS_NO_MSDS_INTID: WIN32_ERROR = 8596u32; -pub const ERROR_DS_NO_NEST_GLOBALGROUP_IN_MIXEDDOMAIN: WIN32_ERROR = 8514u32; -pub const ERROR_DS_NO_NEST_LOCALGROUP_IN_MIXEDDOMAIN: WIN32_ERROR = 8515u32; -pub const ERROR_DS_NO_NTDSA_OBJECT: WIN32_ERROR = 8623u32; -pub const ERROR_DS_NO_OBJECT_MOVE_IN_SCHEMA_NC: WIN32_ERROR = 8580u32; -pub const ERROR_DS_NO_PARENT_OBJECT: WIN32_ERROR = 8329u32; -pub const ERROR_DS_NO_PKT_PRIVACY_ON_CONNECTION: WIN32_ERROR = 8533u32; -pub const ERROR_DS_NO_RDN_DEFINED_IN_SCHEMA: WIN32_ERROR = 8306u32; -pub const ERROR_DS_NO_REF_DOMAIN: WIN32_ERROR = 8575u32; -pub const ERROR_DS_NO_REQUESTED_ATTS_FOUND: WIN32_ERROR = 8308u32; -pub const ERROR_DS_NO_RESULTS_RETURNED: WIN32_ERROR = 8257u32; -pub const ERROR_DS_NO_RIDS_ALLOCATED: WIN32_ERROR = 8208u32; -pub const ERROR_DS_NO_SERVER_OBJECT: WIN32_ERROR = 8622u32; -pub const ERROR_DS_NO_SUCH_OBJECT: WIN32_ERROR = 8240u32; -pub const ERROR_DS_NO_TREE_DELETE_ABOVE_NC: WIN32_ERROR = 8501u32; -pub const ERROR_DS_NTDSCRIPT_PROCESS_ERROR: WIN32_ERROR = 8592u32; -pub const ERROR_DS_NTDSCRIPT_SYNTAX_ERROR: WIN32_ERROR = 8591u32; -pub const ERROR_DS_OBJECT_BEING_REMOVED: WIN32_ERROR = 8339u32; -pub const ERROR_DS_OBJECT_CLASS_REQUIRED: WIN32_ERROR = 8315u32; -pub const ERROR_DS_OBJECT_RESULTS_TOO_LARGE: WIN32_ERROR = 8248u32; -pub const ERROR_DS_OBJ_CLASS_NOT_DEFINED: WIN32_ERROR = 8371u32; -pub const ERROR_DS_OBJ_CLASS_NOT_SUBCLASS: WIN32_ERROR = 8372u32; -pub const ERROR_DS_OBJ_CLASS_VIOLATION: WIN32_ERROR = 8212u32; -pub const ERROR_DS_OBJ_GUID_EXISTS: WIN32_ERROR = 8361u32; -pub const ERROR_DS_OBJ_NOT_FOUND: WIN32_ERROR = 8333u32; -pub const ERROR_DS_OBJ_STRING_NAME_EXISTS: WIN32_ERROR = 8305u32; -pub const ERROR_DS_OBJ_TOO_LARGE: WIN32_ERROR = 8312u32; -pub const ERROR_DS_OFFSET_RANGE_ERROR: WIN32_ERROR = 8262u32; -pub const ERROR_DS_OID_MAPPED_GROUP_CANT_HAVE_MEMBERS: WIN32_ERROR = 8637u32; -pub const ERROR_DS_OID_NOT_FOUND: WIN32_ERROR = 8638u32; -pub const ERROR_DS_OPERATIONS_ERROR: WIN32_ERROR = 8224u32; -pub const ERROR_DS_OUT_OF_SCOPE: WIN32_ERROR = 8338u32; -pub const ERROR_DS_OUT_OF_VERSION_STORE: WIN32_ERROR = 8573u32; -pub const ERROR_DS_PARAM_ERROR: WIN32_ERROR = 8255u32; -pub const ERROR_DS_PARENT_IS_AN_ALIAS: WIN32_ERROR = 8330u32; -pub const ERROR_DS_PDC_OPERATION_IN_PROGRESS: WIN32_ERROR = 8490u32; -pub const ERROR_DS_PER_ATTRIBUTE_AUTHZ_FAILED_DURING_ADD: WIN32_ERROR = 8652u32; -pub const ERROR_DS_POLICY_NOT_KNOWN: WIN32_ERROR = 8618u32; -pub const ERROR_DS_PROTOCOL_ERROR: WIN32_ERROR = 8225u32; -pub const ERROR_DS_RANGE_CONSTRAINT: WIN32_ERROR = 8322u32; -pub const ERROR_DS_RDN_DOESNT_MATCH_SCHEMA: WIN32_ERROR = 8307u32; -pub const ERROR_DS_RECALCSCHEMA_FAILED: WIN32_ERROR = 8396u32; -pub const ERROR_DS_REFERRAL: WIN32_ERROR = 8235u32; -pub const ERROR_DS_REFERRAL_LIMIT_EXCEEDED: WIN32_ERROR = 8260u32; -pub const ERROR_DS_REFUSING_FSMO_ROLES: WIN32_ERROR = 8433u32; -pub const ERROR_DS_REMOTE_CROSSREF_OP_FAILED: WIN32_ERROR = 8601u32; -pub const ERROR_DS_REPLICATOR_ONLY: WIN32_ERROR = 8370u32; -pub const ERROR_DS_REPLICA_SET_CHANGE_NOT_ALLOWED_ON_DISABLED_CR: WIN32_ERROR = 8595u32; -pub const ERROR_DS_REPL_LIFETIME_EXCEEDED: WIN32_ERROR = 8614u32; -pub const ERROR_DS_RESERVED_LINK_ID: WIN32_ERROR = 8576u32; -pub const ERROR_DS_RESERVED_MAPI_ID: WIN32_ERROR = 8631u32; -pub const ERROR_DS_RIDMGR_DISABLED: WIN32_ERROR = 8263u32; -pub const ERROR_DS_RIDMGR_INIT_ERROR: WIN32_ERROR = 8211u32; -pub const ERROR_DS_ROLE_NOT_VERIFIED: WIN32_ERROR = 8610u32; -pub const ERROR_DS_ROOT_CANT_BE_SUBREF: WIN32_ERROR = 8326u32; -pub const ERROR_DS_ROOT_MUST_BE_NC: WIN32_ERROR = 8301u32; -pub const ERROR_DS_ROOT_REQUIRES_CLASS_TOP: WIN32_ERROR = 8432u32; -pub const ERROR_DS_SAM_INIT_FAILURE: WIN32_ERROR = 8504u32; -pub const ERROR_DS_SAM_INIT_FAILURE_CONSOLE: WIN32_ERROR = 8562u32; -pub const ERROR_DS_SAM_NEED_BOOTKEY_FLOPPY: WIN32_ERROR = 8530u32; -pub const ERROR_DS_SAM_NEED_BOOTKEY_PASSWORD: WIN32_ERROR = 8529u32; -pub const ERROR_DS_SCHEMA_ALLOC_FAILED: WIN32_ERROR = 8415u32; -pub const ERROR_DS_SCHEMA_NOT_LOADED: WIN32_ERROR = 8414u32; -pub const ERROR_DS_SCHEMA_UPDATE_DISALLOWED: WIN32_ERROR = 8509u32; -pub const ERROR_DS_SECURITY_CHECKING_ERROR: WIN32_ERROR = 8413u32; -pub const ERROR_DS_SECURITY_ILLEGAL_MODIFY: WIN32_ERROR = 8423u32; -pub const ERROR_DS_SEC_DESC_INVALID: WIN32_ERROR = 8354u32; -pub const ERROR_DS_SEC_DESC_TOO_SHORT: WIN32_ERROR = 8353u32; -pub const ERROR_DS_SEMANTIC_ATT_TEST: WIN32_ERROR = 8383u32; -pub const ERROR_DS_SENSITIVE_GROUP_VIOLATION: WIN32_ERROR = 8505u32; -pub const ERROR_DS_SERVER_DOWN: WIN32_ERROR = 8250u32; -pub const ERROR_DS_SHUTTING_DOWN: WIN32_ERROR = 8364u32; -pub const ERROR_DS_SINGLE_USER_MODE_FAILED: WIN32_ERROR = 8590u32; -pub const ERROR_DS_SINGLE_VALUE_CONSTRAINT: WIN32_ERROR = 8321u32; -pub const ERROR_DS_SIZELIMIT_EXCEEDED: WIN32_ERROR = 8227u32; -pub const ERROR_DS_SORT_CONTROL_MISSING: WIN32_ERROR = 8261u32; -pub const ERROR_DS_SOURCE_AUDITING_NOT_ENABLED: WIN32_ERROR = 8552u32; -pub const ERROR_DS_SOURCE_DOMAIN_IN_FOREST: WIN32_ERROR = 8534u32; -pub const ERROR_DS_SPN_VALUE_NOT_UNIQUE_IN_FOREST: WIN32_ERROR = 8647u32; -pub const ERROR_DS_SRC_AND_DST_NC_IDENTICAL: WIN32_ERROR = 8485u32; -pub const ERROR_DS_SRC_AND_DST_OBJECT_CLASS_MISMATCH: WIN32_ERROR = 8540u32; -pub const ERROR_DS_SRC_DC_MUST_BE_SP4_OR_GREATER: WIN32_ERROR = 8559u32; -pub const ERROR_DS_SRC_GUID_MISMATCH: WIN32_ERROR = 8488u32; -pub const ERROR_DS_SRC_NAME_MISMATCH: WIN32_ERROR = 8484u32; -pub const ERROR_DS_SRC_OBJ_NOT_GROUP_OR_USER: WIN32_ERROR = 8538u32; -pub const ERROR_DS_SRC_SID_EXISTS_IN_FOREST: WIN32_ERROR = 8539u32; -pub const ERROR_DS_STRING_SD_CONVERSION_FAILED: WIN32_ERROR = 8522u32; -pub const ERROR_DS_STRONG_AUTH_REQUIRED: WIN32_ERROR = 8232u32; -pub const ERROR_DS_SUBREF_MUST_HAVE_PARENT: WIN32_ERROR = 8356u32; -pub const ERROR_DS_SUBTREE_NOTIFY_NOT_NC_HEAD: WIN32_ERROR = 8376u32; -pub const ERROR_DS_SUB_CLS_TEST_FAIL: WIN32_ERROR = 8391u32; -pub const ERROR_DS_SYNTAX_MISMATCH: WIN32_ERROR = 8384u32; -pub const ERROR_DS_THREAD_LIMIT_EXCEEDED: WIN32_ERROR = 8587u32; -pub const ERROR_DS_TIMELIMIT_EXCEEDED: WIN32_ERROR = 8226u32; -pub const ERROR_DS_TREE_DELETE_NOT_FINISHED: WIN32_ERROR = 8397u32; -pub const ERROR_DS_UNABLE_TO_SURRENDER_ROLES: WIN32_ERROR = 8435u32; -pub const ERROR_DS_UNAVAILABLE: WIN32_ERROR = 8207u32; -pub const ERROR_DS_UNAVAILABLE_CRIT_EXTENSION: WIN32_ERROR = 8236u32; -pub const ERROR_DS_UNDELETE_SAM_VALIDATION_FAILED: WIN32_ERROR = 8645u32; -pub const ERROR_DS_UNICODEPWD_NOT_IN_QUOTES: WIN32_ERROR = 8556u32; -pub const ERROR_DS_UNIVERSAL_CANT_HAVE_LOCAL_MEMBER: WIN32_ERROR = 8518u32; -pub const ERROR_DS_UNKNOWN_ERROR: WIN32_ERROR = 8431u32; -pub const ERROR_DS_UNKNOWN_OPERATION: WIN32_ERROR = 8365u32; -pub const ERROR_DS_UNWILLING_TO_PERFORM: WIN32_ERROR = 8245u32; -pub const ERROR_DS_UPN_VALUE_NOT_UNIQUE_IN_FOREST: WIN32_ERROR = 8648u32; -pub const ERROR_DS_USER_BUFFER_TO_SMALL: WIN32_ERROR = 8309u32; -pub const ERROR_DS_VALUE_KEY_NOT_UNIQUE: WIN32_ERROR = 8650u32; -pub const ERROR_DS_VERSION_CHECK_FAILURE: WIN32_ERROR = 643u32; -pub const ERROR_DS_WKO_CONTAINER_CANNOT_BE_SPECIAL: WIN32_ERROR = 8611u32; -pub const ERROR_DS_WRONG_LINKED_ATT_SYNTAX: WIN32_ERROR = 8528u32; -pub const ERROR_DS_WRONG_OM_OBJ_CLASS: WIN32_ERROR = 8476u32; -pub const ERROR_DUPLICATE_PRIVILEGES: WIN32_ERROR = 311u32; -pub const ERROR_DUPLICATE_SERVICE_NAME: WIN32_ERROR = 1078u32; -pub const ERROR_DUP_DOMAINNAME: WIN32_ERROR = 1221u32; -pub const ERROR_DUP_NAME: WIN32_ERROR = 52u32; -pub const ERROR_DYNAMIC_CODE_BLOCKED: WIN32_ERROR = 1655u32; -pub const ERROR_DYNLINK_FROM_INVALID_RING: WIN32_ERROR = 196u32; -pub const ERROR_EAS_DIDNT_FIT: WIN32_ERROR = 275u32; -pub const ERROR_EAS_NOT_SUPPORTED: WIN32_ERROR = 282u32; -pub const ERROR_EA_ACCESS_DENIED: WIN32_ERROR = 994u32; -pub const ERROR_EA_FILE_CORRUPT: WIN32_ERROR = 276u32; -pub const ERROR_EA_LIST_INCONSISTENT: WIN32_ERROR = 255u32; -pub const ERROR_EA_TABLE_FULL: WIN32_ERROR = 277u32; -pub const ERROR_EDP_DPL_POLICY_CANT_BE_SATISFIED: WIN32_ERROR = 357u32; -pub const ERROR_EDP_POLICY_DENIES_OPERATION: WIN32_ERROR = 356u32; -pub const ERROR_EFS_ALG_BLOB_TOO_BIG: WIN32_ERROR = 6013u32; -pub const ERROR_EFS_DISABLED: WIN32_ERROR = 6015u32; -pub const ERROR_EFS_SERVER_NOT_TRUSTED: WIN32_ERROR = 6011u32; -pub const ERROR_EFS_VERSION_NOT_SUPPORT: WIN32_ERROR = 6016u32; -pub const ERROR_ELEVATION_REQUIRED: WIN32_ERROR = 740u32; -pub const ERROR_ENCLAVE_FAILURE: WIN32_ERROR = 349u32; -pub const ERROR_ENCLAVE_NOT_TERMINATED: WIN32_ERROR = 814u32; -pub const ERROR_ENCLAVE_VIOLATION: WIN32_ERROR = 815u32; -pub const ERROR_ENCRYPTED_FILE_NOT_SUPPORTED: WIN32_ERROR = 489u32; -pub const ERROR_ENCRYPTED_IO_NOT_POSSIBLE: WIN32_ERROR = 808u32; -pub const ERROR_ENCRYPTING_METADATA_DISALLOWED: WIN32_ERROR = 431u32; -pub const ERROR_ENCRYPTION_DISABLED: WIN32_ERROR = 430u32; -pub const ERROR_ENCRYPTION_FAILED: WIN32_ERROR = 6000u32; -pub const ERROR_ENCRYPTION_POLICY_DENIES_OPERATION: WIN32_ERROR = 6022u32; -pub const ERROR_END_OF_MEDIA: WIN32_ERROR = 1100u32; -pub const ERROR_ENVVAR_NOT_FOUND: WIN32_ERROR = 203u32; -pub const ERROR_EOM_OVERFLOW: WIN32_ERROR = 1129u32; -pub const ERROR_ERRORS_ENCOUNTERED: WIN32_ERROR = 774u32; -pub const ERROR_EVALUATION_EXPIRATION: WIN32_ERROR = 622u32; -pub const ERROR_EVENTLOG_CANT_START: WIN32_ERROR = 1501u32; -pub const ERROR_EVENTLOG_FILE_CHANGED: WIN32_ERROR = 1503u32; -pub const ERROR_EVENTLOG_FILE_CORRUPT: WIN32_ERROR = 1500u32; -pub const ERROR_EVENT_DONE: WIN32_ERROR = 710u32; -pub const ERROR_EVENT_PENDING: WIN32_ERROR = 711u32; -pub const ERROR_EXCEPTION_IN_SERVICE: WIN32_ERROR = 1064u32; -pub const ERROR_EXCL_SEM_ALREADY_OWNED: WIN32_ERROR = 101u32; -pub const ERROR_EXE_CANNOT_MODIFY_SIGNED_BINARY: WIN32_ERROR = 217u32; -pub const ERROR_EXE_CANNOT_MODIFY_STRONG_SIGNED_BINARY: WIN32_ERROR = 218u32; -pub const ERROR_EXE_MACHINE_TYPE_MISMATCH: WIN32_ERROR = 216u32; -pub const ERROR_EXE_MARKED_INVALID: WIN32_ERROR = 192u32; -pub const ERROR_EXTENDED_ERROR: WIN32_ERROR = 1208u32; -pub const ERROR_EXTERNAL_BACKING_PROVIDER_UNKNOWN: WIN32_ERROR = 343u32; -pub const ERROR_EXTERNAL_SYSKEY_NOT_SUPPORTED: WIN32_ERROR = 399u32; -pub const ERROR_EXTRANEOUS_INFORMATION: WIN32_ERROR = 677u32; -pub const ERROR_FAILED_DRIVER_ENTRY: WIN32_ERROR = 647u32; -pub const ERROR_FAILED_SERVICE_CONTROLLER_CONNECT: WIN32_ERROR = 1063u32; -pub const ERROR_FAIL_FAST_EXCEPTION: WIN32_ERROR = 1653u32; -pub const ERROR_FAIL_I24: WIN32_ERROR = 83u32; -pub const ERROR_FAIL_NOACTION_REBOOT: WIN32_ERROR = 350u32; -pub const ERROR_FAIL_RESTART: WIN32_ERROR = 352u32; -pub const ERROR_FAIL_SHUTDOWN: WIN32_ERROR = 351u32; -pub const ERROR_FATAL_APP_EXIT: WIN32_ERROR = 713u32; -pub const ERROR_FILEMARK_DETECTED: WIN32_ERROR = 1101u32; -pub const ERROR_FILENAME_EXCED_RANGE: WIN32_ERROR = 206u32; -pub const ERROR_FILE_CHECKED_OUT: WIN32_ERROR = 220u32; -pub const ERROR_FILE_CORRUPT: WIN32_ERROR = 1392u32; -pub const ERROR_FILE_ENCRYPTED: WIN32_ERROR = 6002u32; -pub const ERROR_FILE_EXISTS: WIN32_ERROR = 80u32; -pub const ERROR_FILE_HANDLE_REVOKED: WIN32_ERROR = 806u32; -pub const ERROR_FILE_INVALID: WIN32_ERROR = 1006u32; -pub const ERROR_FILE_LEVEL_TRIM_NOT_SUPPORTED: WIN32_ERROR = 326u32; -pub const ERROR_FILE_METADATA_OPTIMIZATION_IN_PROGRESS: WIN32_ERROR = 809u32; -pub const ERROR_FILE_NOT_ENCRYPTED: WIN32_ERROR = 6007u32; -pub const ERROR_FILE_NOT_FOUND: WIN32_ERROR = 2u32; -pub const ERROR_FILE_NOT_SUPPORTED: WIN32_ERROR = 425u32; -pub const ERROR_FILE_OFFLINE: WIN32_ERROR = 4350u32; -pub const ERROR_FILE_PROTECTED_UNDER_DPL: WIN32_ERROR = 406u32; -pub const ERROR_FILE_READ_ONLY: WIN32_ERROR = 6009u32; -pub const ERROR_FILE_SNAP_INVALID_PARAMETER: WIN32_ERROR = 440u32; -pub const ERROR_FILE_SNAP_IN_PROGRESS: WIN32_ERROR = 435u32; -pub const ERROR_FILE_SNAP_IO_NOT_COORDINATED: WIN32_ERROR = 438u32; -pub const ERROR_FILE_SNAP_MODIFY_NOT_SUPPORTED: WIN32_ERROR = 437u32; -pub const ERROR_FILE_SNAP_UNEXPECTED_ERROR: WIN32_ERROR = 439u32; -pub const ERROR_FILE_SNAP_USER_SECTION_NOT_SUPPORTED: WIN32_ERROR = 436u32; -pub const ERROR_FILE_SYSTEM_LIMITATION: WIN32_ERROR = 665u32; -pub const ERROR_FILE_SYSTEM_VIRTUALIZATION_BUSY: WIN32_ERROR = 371u32; -pub const ERROR_FILE_SYSTEM_VIRTUALIZATION_INVALID_OPERATION: WIN32_ERROR = 385u32; -pub const ERROR_FILE_SYSTEM_VIRTUALIZATION_METADATA_CORRUPT: WIN32_ERROR = 370u32; -pub const ERROR_FILE_SYSTEM_VIRTUALIZATION_PROVIDER_UNKNOWN: WIN32_ERROR = 372u32; -pub const ERROR_FILE_SYSTEM_VIRTUALIZATION_UNAVAILABLE: WIN32_ERROR = 369u32; -pub const ERROR_FILE_TOO_LARGE: WIN32_ERROR = 223u32; -pub const ERROR_FIRMWARE_UPDATED: WIN32_ERROR = 728u32; -pub const ERROR_FLOAT_MULTIPLE_FAULTS: WIN32_ERROR = 630u32; -pub const ERROR_FLOAT_MULTIPLE_TRAPS: WIN32_ERROR = 631u32; -pub const ERROR_FLOPPY_BAD_REGISTERS: WIN32_ERROR = 1125u32; -pub const ERROR_FLOPPY_ID_MARK_NOT_FOUND: WIN32_ERROR = 1122u32; -pub const ERROR_FLOPPY_UNKNOWN_ERROR: WIN32_ERROR = 1124u32; -pub const ERROR_FLOPPY_VOLUME: WIN32_ERROR = 584u32; -pub const ERROR_FLOPPY_WRONG_CYLINDER: WIN32_ERROR = 1123u32; -pub const ERROR_FORMS_AUTH_REQUIRED: WIN32_ERROR = 224u32; -pub const ERROR_FOUND_OUT_OF_SCOPE: WIN32_ERROR = 601u32; -pub const ERROR_FSFILTER_OP_COMPLETED_SUCCESSFULLY: WIN32_ERROR = 762u32; -pub const ERROR_FS_DRIVER_REQUIRED: WIN32_ERROR = 588u32; -pub const ERROR_FS_METADATA_INCONSISTENT: WIN32_ERROR = 510u32; -pub const ERROR_FT_DI_SCAN_REQUIRED: WIN32_ERROR = 339u32; -pub const ERROR_FT_READ_FAILURE: WIN32_ERROR = 415u32; -pub const ERROR_FT_READ_FROM_COPY_FAILURE: WIN32_ERROR = 818u32; -pub const ERROR_FT_READ_RECOVERY_FROM_BACKUP: WIN32_ERROR = 704u32; -pub const ERROR_FT_WRITE_FAILURE: WIN32_ERROR = 338u32; -pub const ERROR_FT_WRITE_RECOVERY: WIN32_ERROR = 705u32; -pub const ERROR_FULLSCREEN_MODE: WIN32_ERROR = 1007u32; -pub const ERROR_FUNCTION_FAILED: WIN32_ERROR = 1627u32; -pub const ERROR_FUNCTION_NOT_CALLED: WIN32_ERROR = 1626u32; -pub const ERROR_GDI_HANDLE_LEAK: WIN32_ERROR = 373u32; -pub const ERROR_GENERIC_NOT_MAPPED: WIN32_ERROR = 1360u32; -pub const ERROR_GEN_FAILURE: WIN32_ERROR = 31u32; -pub const ERROR_GLOBAL_ONLY_HOOK: WIN32_ERROR = 1429u32; -pub const ERROR_GRACEFUL_DISCONNECT: WIN32_ERROR = 1226u32; -pub const ERROR_GROUP_EXISTS: WIN32_ERROR = 1318u32; -pub const ERROR_GUID_SUBSTITUTION_MADE: WIN32_ERROR = 680u32; -pub const ERROR_HANDLES_CLOSED: WIN32_ERROR = 676u32; -pub const ERROR_HANDLE_DISK_FULL: WIN32_ERROR = 39u32; -pub const ERROR_HANDLE_EOF: WIN32_ERROR = 38u32; -pub const ERROR_HANDLE_REVOKED: WIN32_ERROR = 811u32; -pub const ERROR_HAS_SYSTEM_CRITICAL_FILES: WIN32_ERROR = 488u32; -pub const ERROR_HIBERNATED: WIN32_ERROR = 726u32; -pub const ERROR_HIBERNATION_FAILURE: WIN32_ERROR = 656u32; -pub const ERROR_HOOK_NEEDS_HMOD: WIN32_ERROR = 1428u32; -pub const ERROR_HOOK_NOT_INSTALLED: WIN32_ERROR = 1431u32; -pub const ERROR_HOOK_TYPE_NOT_ALLOWED: WIN32_ERROR = 1458u32; -pub const ERROR_HOST_DOWN: WIN32_ERROR = 1256u32; -pub const ERROR_HOST_UNREACHABLE: WIN32_ERROR = 1232u32; -pub const ERROR_HOTKEY_ALREADY_REGISTERED: WIN32_ERROR = 1409u32; -pub const ERROR_HOTKEY_NOT_REGISTERED: WIN32_ERROR = 1419u32; -pub const ERROR_HWNDS_HAVE_DIFF_PARENT: WIN32_ERROR = 1441u32; -pub const ERROR_ILLEGAL_CHARACTER: WIN32_ERROR = 582u32; -pub const ERROR_ILLEGAL_DLL_RELOCATION: WIN32_ERROR = 623u32; -pub const ERROR_ILLEGAL_ELEMENT_ADDRESS: WIN32_ERROR = 1162u32; -pub const ERROR_ILLEGAL_FLOAT_CONTEXT: WIN32_ERROR = 579u32; -pub const ERROR_ILL_FORMED_PASSWORD: WIN32_ERROR = 1324u32; -pub const ERROR_IMAGE_AT_DIFFERENT_BASE: WIN32_ERROR = 807u32; -pub const ERROR_IMAGE_MACHINE_TYPE_MISMATCH: WIN32_ERROR = 706u32; -pub const ERROR_IMAGE_MACHINE_TYPE_MISMATCH_EXE: WIN32_ERROR = 720u32; -pub const ERROR_IMAGE_NOT_AT_BASE: WIN32_ERROR = 700u32; -pub const ERROR_IMAGE_SUBSYSTEM_NOT_PRESENT: WIN32_ERROR = 308u32; -pub const ERROR_IMPLEMENTATION_LIMIT: WIN32_ERROR = 1292u32; -pub const ERROR_INCOMPATIBLE_SERVICE_PRIVILEGE: WIN32_ERROR = 1297u32; -pub const ERROR_INCOMPATIBLE_SERVICE_SID_TYPE: WIN32_ERROR = 1290u32; -pub const ERROR_INCOMPATIBLE_WITH_GLOBAL_SHORT_NAME_REGISTRY_SETTING: WIN32_ERROR = 304u32; -pub const ERROR_INCORRECT_ACCOUNT_TYPE: WIN32_ERROR = 8646u32; -pub const ERROR_INCORRECT_ADDRESS: WIN32_ERROR = 1241u32; -pub const ERROR_INCORRECT_SIZE: WIN32_ERROR = 1462u32; -pub const ERROR_INDEX_ABSENT: WIN32_ERROR = 1611u32; -pub const ERROR_INDEX_OUT_OF_BOUNDS: WIN32_ERROR = 474u32; -pub const ERROR_INFLOOP_IN_RELOC_CHAIN: WIN32_ERROR = 202u32; -pub const ERROR_INSTALL_ALREADY_RUNNING: WIN32_ERROR = 1618u32; -pub const ERROR_INSTALL_FAILURE: WIN32_ERROR = 1603u32; -pub const ERROR_INSTALL_LANGUAGE_UNSUPPORTED: WIN32_ERROR = 1623u32; -pub const ERROR_INSTALL_LOG_FAILURE: WIN32_ERROR = 1622u32; -pub const ERROR_INSTALL_NOTUSED: WIN32_ERROR = 1634u32; -pub const ERROR_INSTALL_PACKAGE_INVALID: WIN32_ERROR = 1620u32; -pub const ERROR_INSTALL_PACKAGE_OPEN_FAILED: WIN32_ERROR = 1619u32; -pub const ERROR_INSTALL_PACKAGE_REJECTED: WIN32_ERROR = 1625u32; -pub const ERROR_INSTALL_PACKAGE_VERSION: WIN32_ERROR = 1613u32; -pub const ERROR_INSTALL_PLATFORM_UNSUPPORTED: WIN32_ERROR = 1633u32; -pub const ERROR_INSTALL_REJECTED: WIN32_ERROR = 1654u32; -pub const ERROR_INSTALL_REMOTE_DISALLOWED: WIN32_ERROR = 1640u32; -pub const ERROR_INSTALL_REMOTE_PROHIBITED: WIN32_ERROR = 1645u32; -pub const ERROR_INSTALL_SERVICE_FAILURE: WIN32_ERROR = 1601u32; -pub const ERROR_INSTALL_SERVICE_SAFEBOOT: WIN32_ERROR = 1652u32; -pub const ERROR_INSTALL_SOURCE_ABSENT: WIN32_ERROR = 1612u32; -pub const ERROR_INSTALL_SUSPEND: WIN32_ERROR = 1604u32; -pub const ERROR_INSTALL_TEMP_UNWRITABLE: WIN32_ERROR = 1632u32; -pub const ERROR_INSTALL_TRANSFORM_FAILURE: WIN32_ERROR = 1624u32; -pub const ERROR_INSTALL_TRANSFORM_REJECTED: WIN32_ERROR = 1644u32; -pub const ERROR_INSTALL_UI_FAILURE: WIN32_ERROR = 1621u32; -pub const ERROR_INSTALL_USEREXIT: WIN32_ERROR = 1602u32; -pub const ERROR_INSTRUCTION_MISALIGNMENT: WIN32_ERROR = 549u32; -pub const ERROR_INSUFFICIENT_BUFFER: WIN32_ERROR = 122u32; -pub const ERROR_INSUFFICIENT_LOGON_INFO: WIN32_ERROR = 608u32; -pub const ERROR_INSUFFICIENT_POWER: WIN32_ERROR = 639u32; -pub const ERROR_INSUFFICIENT_RESOURCE_FOR_SPECIFIED_SHARED_SECTION_SIZE: WIN32_ERROR = 781u32; -pub const ERROR_INSUFFICIENT_VIRTUAL_ADDR_RESOURCES: WIN32_ERROR = 473u32; -pub const ERROR_INTERMIXED_KERNEL_EA_OPERATION: WIN32_ERROR = 324u32; -pub const ERROR_INTERNAL_DB_CORRUPTION: WIN32_ERROR = 1358u32; -pub const ERROR_INTERNAL_DB_ERROR: WIN32_ERROR = 1383u32; -pub const ERROR_INTERNAL_ERROR: WIN32_ERROR = 1359u32; -pub const ERROR_INTERRUPT_STILL_CONNECTED: WIN32_ERROR = 764u32; -pub const ERROR_INTERRUPT_VECTOR_ALREADY_CONNECTED: WIN32_ERROR = 763u32; -pub const ERROR_INVALID_ACCEL_HANDLE: WIN32_ERROR = 1403u32; -pub const ERROR_INVALID_ACCESS: WIN32_ERROR = 12u32; -pub const ERROR_INVALID_ACCOUNT_NAME: WIN32_ERROR = 1315u32; -pub const ERROR_INVALID_ACE_CONDITION: WIN32_ERROR = 805u32; -pub const ERROR_INVALID_ACL: WIN32_ERROR = 1336u32; -pub const ERROR_INVALID_ADDRESS: WIN32_ERROR = 487u32; -pub const ERROR_INVALID_AT_INTERRUPT_TIME: WIN32_ERROR = 104u32; -pub const ERROR_INVALID_BLOCK: WIN32_ERROR = 9u32; -pub const ERROR_INVALID_BLOCK_LENGTH: WIN32_ERROR = 1106u32; -pub const ERROR_INVALID_CAP: WIN32_ERROR = 320u32; -pub const ERROR_INVALID_CATEGORY: WIN32_ERROR = 117u32; -pub const ERROR_INVALID_COMBOBOX_MESSAGE: WIN32_ERROR = 1422u32; -pub const ERROR_INVALID_COMMAND_LINE: WIN32_ERROR = 1639u32; -pub const ERROR_INVALID_COMPUTERNAME: WIN32_ERROR = 1210u32; -pub const ERROR_INVALID_CRUNTIME_PARAMETER: WIN32_ERROR = 1288u32; -pub const ERROR_INVALID_CURSOR_HANDLE: WIN32_ERROR = 1402u32; -pub const ERROR_INVALID_DATA: WIN32_ERROR = 13u32; -pub const ERROR_INVALID_DATATYPE: WIN32_ERROR = 1804u32; -pub const ERROR_INVALID_DEVICE_OBJECT_PARAMETER: WIN32_ERROR = 650u32; -pub const ERROR_INVALID_DLL: WIN32_ERROR = 1154u32; -pub const ERROR_INVALID_DOMAINNAME: WIN32_ERROR = 1212u32; -pub const ERROR_INVALID_DOMAIN_ROLE: WIN32_ERROR = 1354u32; -pub const ERROR_INVALID_DOMAIN_STATE: WIN32_ERROR = 1353u32; -pub const ERROR_INVALID_DRIVE: WIN32_ERROR = 15u32; -pub const ERROR_INVALID_DWP_HANDLE: WIN32_ERROR = 1405u32; -pub const ERROR_INVALID_EA_HANDLE: WIN32_ERROR = 278u32; -pub const ERROR_INVALID_EA_NAME: WIN32_ERROR = 254u32; -pub const ERROR_INVALID_EDIT_HEIGHT: WIN32_ERROR = 1424u32; -pub const ERROR_INVALID_ENVIRONMENT: WIN32_ERROR = 1805u32; -pub const ERROR_INVALID_EVENTNAME: WIN32_ERROR = 1211u32; -pub const ERROR_INVALID_EVENT_COUNT: WIN32_ERROR = 151u32; -pub const ERROR_INVALID_EXCEPTION_HANDLER: WIN32_ERROR = 310u32; -pub const ERROR_INVALID_EXE_SIGNATURE: WIN32_ERROR = 191u32; -pub const ERROR_INVALID_FIELD: WIN32_ERROR = 1616u32; -pub const ERROR_INVALID_FIELD_IN_PARAMETER_LIST: WIN32_ERROR = 328u32; -pub const ERROR_INVALID_FILTER_PROC: WIN32_ERROR = 1427u32; -pub const ERROR_INVALID_FLAGS: WIN32_ERROR = 1004u32; -pub const ERROR_INVALID_FLAG_NUMBER: WIN32_ERROR = 186u32; -pub const ERROR_INVALID_FORM_NAME: WIN32_ERROR = 1902u32; -pub const ERROR_INVALID_FORM_SIZE: WIN32_ERROR = 1903u32; -pub const ERROR_INVALID_FUNCTION: WIN32_ERROR = 1u32; -pub const ERROR_INVALID_GROUPNAME: WIN32_ERROR = 1209u32; -pub const ERROR_INVALID_GROUP_ATTRIBUTES: WIN32_ERROR = 1345u32; -pub const ERROR_INVALID_GW_COMMAND: WIN32_ERROR = 1443u32; -pub const ERROR_INVALID_HANDLE: WIN32_ERROR = 6u32; -pub const ERROR_INVALID_HANDLE_STATE: WIN32_ERROR = 1609u32; -pub const ERROR_INVALID_HOOK_FILTER: WIN32_ERROR = 1426u32; -pub const ERROR_INVALID_HOOK_HANDLE: WIN32_ERROR = 1404u32; -pub const ERROR_INVALID_HW_PROFILE: WIN32_ERROR = 619u32; -pub const ERROR_INVALID_ICON_HANDLE: WIN32_ERROR = 1414u32; -pub const ERROR_INVALID_ID_AUTHORITY: WIN32_ERROR = 1343u32; -pub const ERROR_INVALID_IMAGE_HASH: WIN32_ERROR = 577u32; -pub const ERROR_INVALID_IMPORT_OF_NON_DLL: WIN32_ERROR = 1276u32; -pub const ERROR_INVALID_INDEX: WIN32_ERROR = 1413u32; -pub const ERROR_INVALID_KERNEL_INFO_VERSION: WIN32_ERROR = 340u32; -pub const ERROR_INVALID_KEYBOARD_HANDLE: WIN32_ERROR = 1457u32; -pub const ERROR_INVALID_LABEL: WIN32_ERROR = 1299u32; -pub const ERROR_INVALID_LB_MESSAGE: WIN32_ERROR = 1432u32; -pub const ERROR_INVALID_LDT_DESCRIPTOR: WIN32_ERROR = 564u32; -pub const ERROR_INVALID_LDT_OFFSET: WIN32_ERROR = 563u32; -pub const ERROR_INVALID_LDT_SIZE: WIN32_ERROR = 561u32; -pub const ERROR_INVALID_LEVEL: WIN32_ERROR = 124u32; -pub const ERROR_INVALID_LIST_FORMAT: WIN32_ERROR = 153u32; -pub const ERROR_INVALID_LOCK_RANGE: WIN32_ERROR = 307u32; -pub const ERROR_INVALID_LOGON_HOURS: WIN32_ERROR = 1328u32; -pub const ERROR_INVALID_LOGON_TYPE: WIN32_ERROR = 1367u32; -pub const ERROR_INVALID_MEMBER: WIN32_ERROR = 1388u32; -pub const ERROR_INVALID_MENU_HANDLE: WIN32_ERROR = 1401u32; -pub const ERROR_INVALID_MESSAGE: WIN32_ERROR = 1002u32; -pub const ERROR_INVALID_MESSAGEDEST: WIN32_ERROR = 1218u32; -pub const ERROR_INVALID_MESSAGENAME: WIN32_ERROR = 1217u32; -pub const ERROR_INVALID_MINALLOCSIZE: WIN32_ERROR = 195u32; -pub const ERROR_INVALID_MODULETYPE: WIN32_ERROR = 190u32; -pub const ERROR_INVALID_MONITOR_HANDLE: WIN32_ERROR = 1461u32; -pub const ERROR_INVALID_MSGBOX_STYLE: WIN32_ERROR = 1438u32; -pub const ERROR_INVALID_NAME: WIN32_ERROR = 123u32; -pub const ERROR_INVALID_NETNAME: WIN32_ERROR = 1214u32; -pub const ERROR_INVALID_OPLOCK_PROTOCOL: WIN32_ERROR = 301u32; -pub const ERROR_INVALID_ORDINAL: WIN32_ERROR = 182u32; -pub const ERROR_INVALID_OWNER: WIN32_ERROR = 1307u32; -pub const ERROR_INVALID_PACKAGE_SID_LENGTH: WIN32_ERROR = 4253u32; -pub const ERROR_INVALID_PARAMETER: WIN32_ERROR = 87u32; -pub const ERROR_INVALID_PASSWORD: WIN32_ERROR = 86u32; -pub const ERROR_INVALID_PASSWORDNAME: WIN32_ERROR = 1216u32; -pub const ERROR_INVALID_PATCH_XML: WIN32_ERROR = 1650u32; -pub const ERROR_INVALID_PEP_INFO_VERSION: WIN32_ERROR = 341u32; -pub const ERROR_INVALID_PLUGPLAY_DEVICE_PATH: WIN32_ERROR = 620u32; -pub const ERROR_INVALID_PORT_ATTRIBUTES: WIN32_ERROR = 545u32; -pub const ERROR_INVALID_PRIMARY_GROUP: WIN32_ERROR = 1308u32; -pub const ERROR_INVALID_PRINTER_COMMAND: WIN32_ERROR = 1803u32; -pub const ERROR_INVALID_PRINTER_NAME: WIN32_ERROR = 1801u32; -pub const ERROR_INVALID_PRINTER_STATE: WIN32_ERROR = 1906u32; -pub const ERROR_INVALID_PRIORITY: WIN32_ERROR = 1800u32; -pub const ERROR_INVALID_QUOTA_LOWER: WIN32_ERROR = 547u32; -pub const ERROR_INVALID_REPARSE_DATA: WIN32_ERROR = 4392u32; -pub const ERROR_INVALID_SCROLLBAR_RANGE: WIN32_ERROR = 1448u32; -pub const ERROR_INVALID_SECURITY_DESCR: WIN32_ERROR = 1338u32; -pub const ERROR_INVALID_SEGDPL: WIN32_ERROR = 198u32; -pub const ERROR_INVALID_SEGMENT_NUMBER: WIN32_ERROR = 180u32; -pub const ERROR_INVALID_SEPARATOR_FILE: WIN32_ERROR = 1799u32; -pub const ERROR_INVALID_SERVER_STATE: WIN32_ERROR = 1352u32; -pub const ERROR_INVALID_SERVICENAME: WIN32_ERROR = 1213u32; -pub const ERROR_INVALID_SERVICE_ACCOUNT: WIN32_ERROR = 1057u32; -pub const ERROR_INVALID_SERVICE_CONTROL: WIN32_ERROR = 1052u32; -pub const ERROR_INVALID_SERVICE_LOCK: WIN32_ERROR = 1071u32; -pub const ERROR_INVALID_SHARENAME: WIN32_ERROR = 1215u32; -pub const ERROR_INVALID_SHOWWIN_COMMAND: WIN32_ERROR = 1449u32; -pub const ERROR_INVALID_SID: WIN32_ERROR = 1337u32; -pub const ERROR_INVALID_SIGNAL_NUMBER: WIN32_ERROR = 209u32; -pub const ERROR_INVALID_SPI_VALUE: WIN32_ERROR = 1439u32; -pub const ERROR_INVALID_STACKSEG: WIN32_ERROR = 189u32; -pub const ERROR_INVALID_STARTING_CODESEG: WIN32_ERROR = 188u32; -pub const ERROR_INVALID_SUB_AUTHORITY: WIN32_ERROR = 1335u32; -pub const ERROR_INVALID_TABLE: WIN32_ERROR = 1628u32; -pub const ERROR_INVALID_TARGET_HANDLE: WIN32_ERROR = 114u32; -pub const ERROR_INVALID_TASK_INDEX: WIN32_ERROR = 1551u32; -pub const ERROR_INVALID_TASK_NAME: WIN32_ERROR = 1550u32; -pub const ERROR_INVALID_THREAD_ID: WIN32_ERROR = 1444u32; -pub const ERROR_INVALID_TIME: WIN32_ERROR = 1901u32; -pub const ERROR_INVALID_TOKEN: WIN32_ERROR = 315u32; -pub const ERROR_INVALID_UNWIND_TARGET: WIN32_ERROR = 544u32; -pub const ERROR_INVALID_USER_BUFFER: WIN32_ERROR = 1784u32; -pub const ERROR_INVALID_USER_PRINCIPAL_NAME: WIN32_ERROR = 8636u32; -pub const ERROR_INVALID_VARIANT: WIN32_ERROR = 604u32; -pub const ERROR_INVALID_VERIFY_SWITCH: WIN32_ERROR = 118u32; -pub const ERROR_INVALID_WINDOW_HANDLE: WIN32_ERROR = 1400u32; -pub const ERROR_INVALID_WORKSTATION: WIN32_ERROR = 1329u32; -pub const ERROR_IOPL_NOT_ENABLED: WIN32_ERROR = 197u32; -pub const ERROR_IO_DEVICE: WIN32_ERROR = 1117u32; -pub const ERROR_IO_INCOMPLETE: WIN32_ERROR = 996u32; -pub const ERROR_IO_PENDING: WIN32_ERROR = 997u32; -pub const ERROR_IO_PRIVILEGE_FAILED: WIN32_ERROR = 571u32; -pub const ERROR_IO_REISSUE_AS_CACHED: WIN32_ERROR = 3950u32; -pub const ERROR_IPSEC_IKE_TIMED_OUT: WIN32_ERROR = 13805u32; -pub const ERROR_IP_ADDRESS_CONFLICT1: WIN32_ERROR = 611u32; -pub const ERROR_IP_ADDRESS_CONFLICT2: WIN32_ERROR = 612u32; -pub const ERROR_IRQ_BUSY: WIN32_ERROR = 1119u32; -pub const ERROR_IS_JOINED: WIN32_ERROR = 134u32; -pub const ERROR_IS_JOIN_PATH: WIN32_ERROR = 147u32; -pub const ERROR_IS_JOIN_TARGET: WIN32_ERROR = 133u32; -pub const ERROR_IS_SUBSTED: WIN32_ERROR = 135u32; -pub const ERROR_IS_SUBST_PATH: WIN32_ERROR = 146u32; -pub const ERROR_IS_SUBST_TARGET: WIN32_ERROR = 149u32; -pub const ERROR_ITERATED_DATA_EXCEEDS_64k: WIN32_ERROR = 194u32; -pub const ERROR_JOB_NO_CONTAINER: WIN32_ERROR = 1505u32; -pub const ERROR_JOIN_TO_JOIN: WIN32_ERROR = 138u32; -pub const ERROR_JOIN_TO_SUBST: WIN32_ERROR = 140u32; -pub const ERROR_JOURNAL_DELETE_IN_PROGRESS: WIN32_ERROR = 1178u32; -pub const ERROR_JOURNAL_ENTRY_DELETED: WIN32_ERROR = 1181u32; -pub const ERROR_JOURNAL_HOOK_SET: WIN32_ERROR = 1430u32; -pub const ERROR_JOURNAL_NOT_ACTIVE: WIN32_ERROR = 1179u32; -pub const ERROR_KERNEL_APC: WIN32_ERROR = 738u32; -pub const ERROR_KEY_DELETED: WIN32_ERROR = 1018u32; -pub const ERROR_KEY_HAS_CHILDREN: WIN32_ERROR = 1020u32; -pub const ERROR_KM_DRIVER_BLOCKED: WIN32_ERROR = 1930u32; -pub const ERROR_LABEL_TOO_LONG: WIN32_ERROR = 154u32; -pub const ERROR_LAST_ADMIN: WIN32_ERROR = 1322u32; -pub const ERROR_LB_WITHOUT_TABSTOPS: WIN32_ERROR = 1434u32; -pub const ERROR_LICENSE_QUOTA_EXCEEDED: WIN32_ERROR = 1395u32; -pub const ERROR_LINUX_SUBSYSTEM_NOT_PRESENT: WIN32_ERROR = 414u32; -pub const ERROR_LINUX_SUBSYSTEM_UPDATE_REQUIRED: WIN32_ERROR = 444u32; -pub const ERROR_LISTBOX_ID_NOT_FOUND: WIN32_ERROR = 1416u32; -pub const ERROR_LM_CROSS_ENCRYPTION_REQUIRED: WIN32_ERROR = 1390u32; -pub const ERROR_LOCAL_POLICY_MODIFICATION_NOT_SUPPORTED: WIN32_ERROR = 8653u32; -pub const ERROR_LOCAL_USER_SESSION_KEY: WIN32_ERROR = 1303u32; -pub const ERROR_LOCKED: WIN32_ERROR = 212u32; -pub const ERROR_LOCK_FAILED: WIN32_ERROR = 167u32; -pub const ERROR_LOCK_VIOLATION: WIN32_ERROR = 33u32; -pub const ERROR_LOGIN_TIME_RESTRICTION: WIN32_ERROR = 1239u32; -pub const ERROR_LOGIN_WKSTA_RESTRICTION: WIN32_ERROR = 1240u32; -pub const ERROR_LOGON_FAILURE: WIN32_ERROR = 1326u32; -pub const ERROR_LOGON_NOT_GRANTED: WIN32_ERROR = 1380u32; -pub const ERROR_LOGON_SERVER_CONFLICT: WIN32_ERROR = 568u32; -pub const ERROR_LOGON_SESSION_COLLISION: WIN32_ERROR = 1366u32; -pub const ERROR_LOGON_SESSION_EXISTS: WIN32_ERROR = 1363u32; -pub const ERROR_LOGON_TYPE_NOT_GRANTED: WIN32_ERROR = 1385u32; -pub const ERROR_LOG_FILE_FULL: WIN32_ERROR = 1502u32; -pub const ERROR_LOG_HARD_ERROR: WIN32_ERROR = 718u32; -pub const ERROR_LONGJUMP: WIN32_ERROR = 682u32; -pub const ERROR_LOST_MODE_LOGON_RESTRICTION: WIN32_ERROR = 1939u32; -pub const ERROR_LOST_WRITEBEHIND_DATA: WIN32_ERROR = 596u32; -pub const ERROR_LOST_WRITEBEHIND_DATA_LOCAL_DISK_ERROR: WIN32_ERROR = 790u32; -pub const ERROR_LOST_WRITEBEHIND_DATA_NETWORK_DISCONNECTED: WIN32_ERROR = 788u32; -pub const ERROR_LOST_WRITEBEHIND_DATA_NETWORK_SERVER_ERROR: WIN32_ERROR = 789u32; -pub const ERROR_LUIDS_EXHAUSTED: WIN32_ERROR = 1334u32; -pub const ERROR_MACHINE_LOCKED: WIN32_ERROR = 1271u32; -pub const ERROR_MAGAZINE_NOT_PRESENT: WIN32_ERROR = 1163u32; -pub const ERROR_MAPPED_ALIGNMENT: WIN32_ERROR = 1132u32; -pub const ERROR_MARKED_TO_DISALLOW_WRITES: WIN32_ERROR = 348u32; -pub const ERROR_MARSHALL_OVERFLOW: WIN32_ERROR = 603u32; -pub const ERROR_MAX_SESSIONS_REACHED: WIN32_ERROR = 353u32; -pub const ERROR_MAX_THRDS_REACHED: WIN32_ERROR = 164u32; -pub const ERROR_MCA_EXCEPTION: WIN32_ERROR = 784u32; -pub const ERROR_MCA_OCCURED: WIN32_ERROR = 651u32; -pub const ERROR_MEDIA_CHANGED: WIN32_ERROR = 1110u32; -pub const ERROR_MEDIA_CHECK: WIN32_ERROR = 679u32; -pub const ERROR_MEMBERS_PRIMARY_GROUP: WIN32_ERROR = 1374u32; -pub const ERROR_MEMBER_IN_ALIAS: WIN32_ERROR = 1378u32; -pub const ERROR_MEMBER_IN_GROUP: WIN32_ERROR = 1320u32; -pub const ERROR_MEMBER_NOT_IN_ALIAS: WIN32_ERROR = 1377u32; -pub const ERROR_MEMBER_NOT_IN_GROUP: WIN32_ERROR = 1321u32; -pub const ERROR_MEMORY_HARDWARE: WIN32_ERROR = 779u32; -pub const ERROR_MENU_ITEM_NOT_FOUND: WIN32_ERROR = 1456u32; -pub const ERROR_MESSAGE_SYNC_ONLY: WIN32_ERROR = 1159u32; -pub const ERROR_META_EXPANSION_TOO_LONG: WIN32_ERROR = 208u32; -pub const ERROR_MISSING_SYSTEMFILE: WIN32_ERROR = 573u32; -pub const ERROR_MOD_NOT_FOUND: WIN32_ERROR = 126u32; -pub const ERROR_MORE_DATA: WIN32_ERROR = 234u32; -pub const ERROR_MORE_WRITES: WIN32_ERROR = 1120u32; -pub const ERROR_MOUNT_POINT_NOT_RESOLVED: WIN32_ERROR = 649u32; -pub const ERROR_MP_PROCESSOR_MISMATCH: WIN32_ERROR = 725u32; -pub const ERROR_MR_MID_NOT_FOUND: WIN32_ERROR = 317u32; -pub const ERROR_MULTIPLE_FAULT_VIOLATION: WIN32_ERROR = 640u32; -pub const ERROR_MUTANT_LIMIT_EXCEEDED: WIN32_ERROR = 587u32; -pub const ERROR_MUTUAL_AUTH_FAILED: WIN32_ERROR = 1397u32; -pub const ERROR_NEGATIVE_SEEK: WIN32_ERROR = 131u32; -pub const ERROR_NESTING_NOT_ALLOWED: WIN32_ERROR = 215u32; -pub const ERROR_NETLOGON_NOT_STARTED: WIN32_ERROR = 1792u32; -pub const ERROR_NETNAME_DELETED: WIN32_ERROR = 64u32; -pub const ERROR_NETWORK_ACCESS_DENIED: WIN32_ERROR = 65u32; -pub const ERROR_NETWORK_ACCESS_DENIED_EDP: WIN32_ERROR = 354u32; -pub const ERROR_NETWORK_BUSY: WIN32_ERROR = 54u32; -pub const ERROR_NETWORK_UNREACHABLE: WIN32_ERROR = 1231u32; -pub const ERROR_NET_OPEN_FAILED: WIN32_ERROR = 570u32; -pub const ERROR_NET_WRITE_FAULT: WIN32_ERROR = 88u32; -pub const ERROR_NOACCESS: WIN32_ERROR = 998u32; -pub const ERROR_NOINTERFACE: WIN32_ERROR = 632u32; -pub const ERROR_NOLOGON_INTERDOMAIN_TRUST_ACCOUNT: WIN32_ERROR = 1807u32; -pub const ERROR_NOLOGON_SERVER_TRUST_ACCOUNT: WIN32_ERROR = 1809u32; -pub const ERROR_NOLOGON_WORKSTATION_TRUST_ACCOUNT: WIN32_ERROR = 1808u32; -pub const ERROR_NONE_MAPPED: WIN32_ERROR = 1332u32; -pub const ERROR_NONPAGED_SYSTEM_RESOURCES: WIN32_ERROR = 1451u32; -pub const ERROR_NON_ACCOUNT_SID: WIN32_ERROR = 1257u32; -pub const ERROR_NON_DOMAIN_SID: WIN32_ERROR = 1258u32; -pub const ERROR_NON_MDICHILD_WINDOW: WIN32_ERROR = 1445u32; -pub const ERROR_NOTHING_TO_TERMINATE: WIN32_ERROR = 758u32; -pub const ERROR_NOTIFICATION_GUID_ALREADY_DEFINED: WIN32_ERROR = 309u32; -pub const ERROR_NOTIFY_CLEANUP: WIN32_ERROR = 745u32; -pub const ERROR_NOTIFY_ENUM_DIR: WIN32_ERROR = 1022u32; -pub const ERROR_NOT_ALLOWED_ON_SYSTEM_FILE: WIN32_ERROR = 313u32; -pub const ERROR_NOT_ALL_ASSIGNED: WIN32_ERROR = 1300u32; -pub const ERROR_NOT_APPCONTAINER: WIN32_ERROR = 4250u32; -pub const ERROR_NOT_AUTHENTICATED: WIN32_ERROR = 1244u32; -pub const ERROR_NOT_A_CLOUD_FILE: WIN32_ERROR = 376u32; -pub const ERROR_NOT_A_CLOUD_SYNC_ROOT: WIN32_ERROR = 405u32; -pub const ERROR_NOT_A_DAX_VOLUME: WIN32_ERROR = 420u32; -pub const ERROR_NOT_A_REPARSE_POINT: WIN32_ERROR = 4390u32; -pub const ERROR_NOT_CAPABLE: WIN32_ERROR = 775u32; -pub const ERROR_NOT_CHILD_WINDOW: WIN32_ERROR = 1442u32; -pub const ERROR_NOT_CONNECTED: WIN32_ERROR = 2250u32; -pub const ERROR_NOT_CONTAINER: WIN32_ERROR = 1207u32; -pub const ERROR_NOT_DAX_MAPPABLE: WIN32_ERROR = 421u32; -pub const ERROR_NOT_DOS_DISK: WIN32_ERROR = 26u32; -pub const ERROR_NOT_ENOUGH_MEMORY: WIN32_ERROR = 8u32; -pub const ERROR_NOT_ENOUGH_QUOTA: WIN32_ERROR = 1816u32; -pub const ERROR_NOT_ENOUGH_SERVER_MEMORY: WIN32_ERROR = 1130u32; -pub const ERROR_NOT_EXPORT_FORMAT: WIN32_ERROR = 6008u32; -pub const ERROR_NOT_FOUND: WIN32_ERROR = 1168u32; -pub const ERROR_NOT_GUI_PROCESS: WIN32_ERROR = 1471u32; -pub const ERROR_NOT_JOINED: WIN32_ERROR = 136u32; -pub const ERROR_NOT_LOCKED: WIN32_ERROR = 158u32; -pub const ERROR_NOT_LOGGED_ON: WIN32_ERROR = 1245u32; -pub const ERROR_NOT_LOGON_PROCESS: WIN32_ERROR = 1362u32; -pub const ERROR_NOT_OWNER: WIN32_ERROR = 288u32; -pub const ERROR_NOT_READY: WIN32_ERROR = 21u32; -pub const ERROR_NOT_READ_FROM_COPY: WIN32_ERROR = 337u32; -pub const ERROR_NOT_REDUNDANT_STORAGE: WIN32_ERROR = 333u32; -pub const ERROR_NOT_REGISTRY_FILE: WIN32_ERROR = 1017u32; -pub const ERROR_NOT_SAFEBOOT_SERVICE: WIN32_ERROR = 1084u32; -pub const ERROR_NOT_SAFE_MODE_DRIVER: WIN32_ERROR = 646u32; -pub const ERROR_NOT_SAME_DEVICE: WIN32_ERROR = 17u32; -pub const ERROR_NOT_SAME_OBJECT: WIN32_ERROR = 1656u32; -pub const ERROR_NOT_SUBSTED: WIN32_ERROR = 137u32; -pub const ERROR_NOT_SUPPORTED: WIN32_ERROR = 50u32; -pub const ERROR_NOT_SUPPORTED_IN_APPCONTAINER: WIN32_ERROR = 4252u32; -pub const ERROR_NOT_SUPPORTED_ON_DAX: WIN32_ERROR = 360u32; -pub const ERROR_NOT_SUPPORTED_ON_SBS: WIN32_ERROR = 1254u32; -pub const ERROR_NOT_SUPPORTED_ON_STANDARD_SERVER: WIN32_ERROR = 8584u32; -pub const ERROR_NOT_SUPPORTED_WITH_AUDITING: WIN32_ERROR = 499u32; -pub const ERROR_NOT_SUPPORTED_WITH_BTT: WIN32_ERROR = 429u32; -pub const ERROR_NOT_SUPPORTED_WITH_BYPASSIO: WIN32_ERROR = 493u32; -pub const ERROR_NOT_SUPPORTED_WITH_CACHED_HANDLE: WIN32_ERROR = 509u32; -pub const ERROR_NOT_SUPPORTED_WITH_COMPRESSION: WIN32_ERROR = 496u32; -pub const ERROR_NOT_SUPPORTED_WITH_DEDUPLICATION: WIN32_ERROR = 498u32; -pub const ERROR_NOT_SUPPORTED_WITH_ENCRYPTION: WIN32_ERROR = 495u32; -pub const ERROR_NOT_SUPPORTED_WITH_MONITORING: WIN32_ERROR = 503u32; -pub const ERROR_NOT_SUPPORTED_WITH_REPLICATION: WIN32_ERROR = 497u32; -pub const ERROR_NOT_SUPPORTED_WITH_SNAPSHOT: WIN32_ERROR = 504u32; -pub const ERROR_NOT_SUPPORTED_WITH_VIRTUALIZATION: WIN32_ERROR = 505u32; -pub const ERROR_NOT_TINY_STREAM: WIN32_ERROR = 598u32; -pub const ERROR_NO_ACE_CONDITION: WIN32_ERROR = 804u32; -pub const ERROR_NO_ASSOCIATION: WIN32_ERROR = 1155u32; -pub const ERROR_NO_BYPASSIO_DRIVER_SUPPORT: WIN32_ERROR = 494u32; -pub const ERROR_NO_CALLBACK_ACTIVE: WIN32_ERROR = 614u32; -pub const ERROR_NO_DATA: WIN32_ERROR = 232u32; -pub const ERROR_NO_DATA_DETECTED: WIN32_ERROR = 1104u32; -pub const ERROR_NO_EFS: WIN32_ERROR = 6004u32; -pub const ERROR_NO_EVENT_PAIR: WIN32_ERROR = 580u32; -pub const ERROR_NO_GUID_TRANSLATION: WIN32_ERROR = 560u32; -pub const ERROR_NO_IMPERSONATION_TOKEN: WIN32_ERROR = 1309u32; -pub const ERROR_NO_INHERITANCE: WIN32_ERROR = 1391u32; -pub const ERROR_NO_LOGON_SERVERS: WIN32_ERROR = 1311u32; -pub const ERROR_NO_LOG_SPACE: WIN32_ERROR = 1019u32; -pub const ERROR_NO_MATCH: WIN32_ERROR = 1169u32; -pub const ERROR_NO_MEDIA_IN_DRIVE: WIN32_ERROR = 1112u32; -pub const ERROR_NO_MORE_DEVICES: WIN32_ERROR = 1248u32; -pub const ERROR_NO_MORE_FILES: WIN32_ERROR = 18u32; -pub const ERROR_NO_MORE_ITEMS: WIN32_ERROR = 259u32; -pub const ERROR_NO_MORE_MATCHES: WIN32_ERROR = 626u32; -pub const ERROR_NO_MORE_SEARCH_HANDLES: WIN32_ERROR = 113u32; -pub const ERROR_NO_MORE_USER_HANDLES: WIN32_ERROR = 1158u32; -pub const ERROR_NO_NETWORK: WIN32_ERROR = 1222u32; -pub const ERROR_NO_NET_OR_BAD_PATH: WIN32_ERROR = 1203u32; -pub const ERROR_NO_NVRAM_RESOURCES: WIN32_ERROR = 1470u32; -pub const ERROR_NO_PAGEFILE: WIN32_ERROR = 578u32; -pub const ERROR_NO_PHYSICALLY_ALIGNED_FREE_SPACE_FOUND: WIN32_ERROR = 408u32; -pub const ERROR_NO_PROC_SLOTS: WIN32_ERROR = 89u32; -pub const ERROR_NO_PROMOTION_ACTIVE: WIN32_ERROR = 8222u32; -pub const ERROR_NO_QUOTAS_FOR_ACCOUNT: WIN32_ERROR = 1302u32; -pub const ERROR_NO_RANGES_PROCESSED: WIN32_ERROR = 312u32; -pub const ERROR_NO_RECOVERY_POLICY: WIN32_ERROR = 6003u32; -pub const ERROR_NO_RECOVERY_PROGRAM: WIN32_ERROR = 1082u32; -pub const ERROR_NO_SCROLLBARS: WIN32_ERROR = 1447u32; -pub const ERROR_NO_SECRETS: WIN32_ERROR = 8620u32; -pub const ERROR_NO_SECURITY_ON_OBJECT: WIN32_ERROR = 1350u32; -pub const ERROR_NO_SHUTDOWN_IN_PROGRESS: WIN32_ERROR = 1116u32; -pub const ERROR_NO_SIGNAL_SENT: WIN32_ERROR = 205u32; -pub const ERROR_NO_SITENAME: WIN32_ERROR = 1919u32; -pub const ERROR_NO_SITE_SETTINGS_OBJECT: WIN32_ERROR = 8619u32; -pub const ERROR_NO_SPOOL_SPACE: WIN32_ERROR = 62u32; -pub const ERROR_NO_SUCH_ALIAS: WIN32_ERROR = 1376u32; -pub const ERROR_NO_SUCH_DEVICE: WIN32_ERROR = 433u32; -pub const ERROR_NO_SUCH_DOMAIN: WIN32_ERROR = 1355u32; -pub const ERROR_NO_SUCH_GROUP: WIN32_ERROR = 1319u32; -pub const ERROR_NO_SUCH_LOGON_SESSION: WIN32_ERROR = 1312u32; -pub const ERROR_NO_SUCH_MEMBER: WIN32_ERROR = 1387u32; -pub const ERROR_NO_SUCH_PACKAGE: WIN32_ERROR = 1364u32; -pub const ERROR_NO_SUCH_PRIVILEGE: WIN32_ERROR = 1313u32; -pub const ERROR_NO_SUCH_SITE: WIN32_ERROR = 1249u32; -pub const ERROR_NO_SUCH_USER: WIN32_ERROR = 1317u32; -pub const ERROR_NO_SYSTEM_MENU: WIN32_ERROR = 1437u32; -pub const ERROR_NO_SYSTEM_RESOURCES: WIN32_ERROR = 1450u32; -pub const ERROR_NO_TASK_QUEUE: WIN32_ERROR = 427u32; -pub const ERROR_NO_TOKEN: WIN32_ERROR = 1008u32; -pub const ERROR_NO_TRACKING_SERVICE: WIN32_ERROR = 1172u32; -pub const ERROR_NO_TRUST_LSA_SECRET: WIN32_ERROR = 1786u32; -pub const ERROR_NO_TRUST_SAM_ACCOUNT: WIN32_ERROR = 1787u32; -pub const ERROR_NO_UNICODE_TRANSLATION: WIN32_ERROR = 1113u32; -pub const ERROR_NO_USER_KEYS: WIN32_ERROR = 6006u32; -pub const ERROR_NO_USER_SESSION_KEY: WIN32_ERROR = 1394u32; -pub const ERROR_NO_VOLUME_ID: WIN32_ERROR = 1173u32; -pub const ERROR_NO_VOLUME_LABEL: WIN32_ERROR = 125u32; -pub const ERROR_NO_WILDCARD_CHARACTERS: WIN32_ERROR = 1417u32; -pub const ERROR_NO_WORK_DONE: WIN32_ERROR = 235u32; -pub const ERROR_NO_WRITABLE_DC_FOUND: WIN32_ERROR = 8621u32; -pub const ERROR_NO_YIELD_PERFORMED: WIN32_ERROR = 721u32; -pub const ERROR_NTLM_BLOCKED: WIN32_ERROR = 1937u32; -pub const ERROR_NT_CROSS_ENCRYPTION_REQUIRED: WIN32_ERROR = 1386u32; -pub const ERROR_NULL_LM_PASSWORD: WIN32_ERROR = 1304u32; -pub const ERROR_OBJECT_IS_IMMUTABLE: WIN32_ERROR = 4449u32; -pub const ERROR_OBJECT_NAME_EXISTS: WIN32_ERROR = 698u32; -pub const ERROR_OBJECT_NOT_EXTERNALLY_BACKED: WIN32_ERROR = 342u32; -pub const ERROR_OFFLOAD_READ_FILE_NOT_SUPPORTED: WIN32_ERROR = 4442u32; -pub const ERROR_OFFLOAD_READ_FLT_NOT_SUPPORTED: WIN32_ERROR = 4440u32; -pub const ERROR_OFFLOAD_WRITE_FILE_NOT_SUPPORTED: WIN32_ERROR = 4443u32; -pub const ERROR_OFFLOAD_WRITE_FLT_NOT_SUPPORTED: WIN32_ERROR = 4441u32; -pub const ERROR_OFFSET_ALIGNMENT_VIOLATION: WIN32_ERROR = 327u32; -pub const ERROR_OLD_WIN_VERSION: WIN32_ERROR = 1150u32; -pub const ERROR_ONLY_IF_CONNECTED: WIN32_ERROR = 1251u32; -pub const ERROR_OPEN_FAILED: WIN32_ERROR = 110u32; -pub const ERROR_OPEN_FILES: WIN32_ERROR = 2401u32; -pub const ERROR_OPERATION_ABORTED: WIN32_ERROR = 995u32; -pub const ERROR_OPERATION_IN_PROGRESS: WIN32_ERROR = 329u32; -pub const ERROR_OPLOCK_BREAK_IN_PROGRESS: WIN32_ERROR = 742u32; -pub const ERROR_OPLOCK_HANDLE_CLOSED: WIN32_ERROR = 803u32; -pub const ERROR_OPLOCK_NOT_GRANTED: WIN32_ERROR = 300u32; -pub const ERROR_OPLOCK_SWITCHED_TO_NEW_HANDLE: WIN32_ERROR = 800u32; -pub const ERROR_ORPHAN_NAME_EXHAUSTED: WIN32_ERROR = 799u32; -pub const ERROR_OUTOFMEMORY: WIN32_ERROR = 14u32; -pub const ERROR_OUT_OF_PAPER: WIN32_ERROR = 28u32; -pub const ERROR_OUT_OF_STRUCTURES: WIN32_ERROR = 84u32; -pub const ERROR_OVERRIDE_NOCHANGES: WIN32_ERROR = 1252u32; -pub const ERROR_PAGED_SYSTEM_RESOURCES: WIN32_ERROR = 1452u32; -pub const ERROR_PAGEFILE_CREATE_FAILED: WIN32_ERROR = 576u32; -pub const ERROR_PAGEFILE_NOT_SUPPORTED: WIN32_ERROR = 491u32; -pub const ERROR_PAGEFILE_QUOTA: WIN32_ERROR = 1454u32; -pub const ERROR_PAGEFILE_QUOTA_EXCEEDED: WIN32_ERROR = 567u32; -pub const ERROR_PAGE_FAULT_COPY_ON_WRITE: WIN32_ERROR = 749u32; -pub const ERROR_PAGE_FAULT_DEMAND_ZERO: WIN32_ERROR = 748u32; -pub const ERROR_PAGE_FAULT_GUARD_PAGE: WIN32_ERROR = 750u32; -pub const ERROR_PAGE_FAULT_PAGING_FILE: WIN32_ERROR = 751u32; -pub const ERROR_PAGE_FAULT_TRANSITION: WIN32_ERROR = 747u32; -pub const ERROR_PARAMETER_QUOTA_EXCEEDED: WIN32_ERROR = 1283u32; -pub const ERROR_PARTIAL_COPY: WIN32_ERROR = 299u32; -pub const ERROR_PARTITION_FAILURE: WIN32_ERROR = 1105u32; -pub const ERROR_PARTITION_TERMINATING: WIN32_ERROR = 1184u32; -pub const ERROR_PASSWORD_CHANGE_REQUIRED: WIN32_ERROR = 1938u32; -pub const ERROR_PASSWORD_EXPIRED: WIN32_ERROR = 1330u32; -pub const ERROR_PASSWORD_MUST_CHANGE: WIN32_ERROR = 1907u32; -pub const ERROR_PASSWORD_RESTRICTION: WIN32_ERROR = 1325u32; -pub const ERROR_PATCH_MANAGED_ADVERTISED_PRODUCT: WIN32_ERROR = 1651u32; -pub const ERROR_PATCH_NO_SEQUENCE: WIN32_ERROR = 1648u32; -pub const ERROR_PATCH_PACKAGE_INVALID: WIN32_ERROR = 1636u32; -pub const ERROR_PATCH_PACKAGE_OPEN_FAILED: WIN32_ERROR = 1635u32; -pub const ERROR_PATCH_PACKAGE_REJECTED: WIN32_ERROR = 1643u32; -pub const ERROR_PATCH_PACKAGE_UNSUPPORTED: WIN32_ERROR = 1637u32; -pub const ERROR_PATCH_REMOVAL_DISALLOWED: WIN32_ERROR = 1649u32; -pub const ERROR_PATCH_REMOVAL_UNSUPPORTED: WIN32_ERROR = 1646u32; -pub const ERROR_PATCH_TARGET_NOT_FOUND: WIN32_ERROR = 1642u32; -pub const ERROR_PATH_BUSY: WIN32_ERROR = 148u32; -pub const ERROR_PATH_NOT_FOUND: WIN32_ERROR = 3u32; -pub const ERROR_PER_USER_TRUST_QUOTA_EXCEEDED: WIN32_ERROR = 1932u32; -pub const ERROR_PIPE_BUSY: WIN32_ERROR = 231u32; -pub const ERROR_PIPE_CONNECTED: WIN32_ERROR = 535u32; -pub const ERROR_PIPE_LISTENING: WIN32_ERROR = 536u32; -pub const ERROR_PIPE_LOCAL: WIN32_ERROR = 229u32; -pub const ERROR_PIPE_NOT_CONNECTED: WIN32_ERROR = 233u32; -pub const ERROR_PKINIT_FAILURE: WIN32_ERROR = 1263u32; -pub const ERROR_PLUGPLAY_QUERY_VETOED: WIN32_ERROR = 683u32; -pub const ERROR_PNP_BAD_MPS_TABLE: WIN32_ERROR = 671u32; -pub const ERROR_PNP_INVALID_ID: WIN32_ERROR = 674u32; -pub const ERROR_PNP_IRQ_TRANSLATION_FAILED: WIN32_ERROR = 673u32; -pub const ERROR_PNP_QUERY_REMOVE_DEVICE_TIMEOUT: WIN32_ERROR = 480u32; -pub const ERROR_PNP_QUERY_REMOVE_RELATED_DEVICE_TIMEOUT: WIN32_ERROR = 481u32; -pub const ERROR_PNP_QUERY_REMOVE_UNRELATED_DEVICE_TIMEOUT: WIN32_ERROR = 482u32; -pub const ERROR_PNP_REBOOT_REQUIRED: WIN32_ERROR = 638u32; -pub const ERROR_PNP_RESTART_ENUMERATION: WIN32_ERROR = 636u32; -pub const ERROR_PNP_TRANSLATION_FAILED: WIN32_ERROR = 672u32; -pub const ERROR_POINT_NOT_FOUND: WIN32_ERROR = 1171u32; -pub const ERROR_POLICY_OBJECT_NOT_FOUND: WIN32_ERROR = 8219u32; -pub const ERROR_POLICY_ONLY_IN_DS: WIN32_ERROR = 8220u32; -pub const ERROR_POPUP_ALREADY_ACTIVE: WIN32_ERROR = 1446u32; -pub const ERROR_PORT_MESSAGE_TOO_LONG: WIN32_ERROR = 546u32; -pub const ERROR_PORT_NOT_SET: WIN32_ERROR = 642u32; -pub const ERROR_PORT_UNREACHABLE: WIN32_ERROR = 1234u32; -pub const ERROR_POSSIBLE_DEADLOCK: WIN32_ERROR = 1131u32; -pub const ERROR_POTENTIAL_FILE_FOUND: WIN32_ERROR = 1180u32; -pub const ERROR_PREDEFINED_HANDLE: WIN32_ERROR = 714u32; -pub const ERROR_PRIMARY_TRANSPORT_CONNECT_FAILED: WIN32_ERROR = 746u32; -pub const ERROR_PRINTER_ALREADY_EXISTS: WIN32_ERROR = 1802u32; -pub const ERROR_PRINTER_DELETED: WIN32_ERROR = 1905u32; -pub const ERROR_PRINTER_DRIVER_ALREADY_INSTALLED: WIN32_ERROR = 1795u32; -pub const ERROR_PRINTQ_FULL: WIN32_ERROR = 61u32; -pub const ERROR_PRINT_CANCELLED: WIN32_ERROR = 63u32; -pub const ERROR_PRIVATE_DIALOG_INDEX: WIN32_ERROR = 1415u32; -pub const ERROR_PRIVILEGE_NOT_HELD: WIN32_ERROR = 1314u32; -pub const ERROR_PROCESS_ABORTED: WIN32_ERROR = 1067u32; -pub const ERROR_PROCESS_IN_JOB: WIN32_ERROR = 760u32; -pub const ERROR_PROCESS_IS_PROTECTED: WIN32_ERROR = 1293u32; -pub const ERROR_PROCESS_MODE_ALREADY_BACKGROUND: WIN32_ERROR = 402u32; -pub const ERROR_PROCESS_MODE_NOT_BACKGROUND: WIN32_ERROR = 403u32; -pub const ERROR_PROCESS_NOT_IN_JOB: WIN32_ERROR = 759u32; -pub const ERROR_PROC_NOT_FOUND: WIN32_ERROR = 127u32; -pub const ERROR_PRODUCT_UNINSTALLED: WIN32_ERROR = 1614u32; -pub const ERROR_PRODUCT_VERSION: WIN32_ERROR = 1638u32; -pub const ERROR_PROFILING_AT_LIMIT: WIN32_ERROR = 553u32; -pub const ERROR_PROFILING_NOT_STARTED: WIN32_ERROR = 550u32; -pub const ERROR_PROFILING_NOT_STOPPED: WIN32_ERROR = 551u32; -pub const ERROR_PROMOTION_ACTIVE: WIN32_ERROR = 8221u32; -pub const ERROR_PROTOCOL_UNREACHABLE: WIN32_ERROR = 1233u32; -pub const ERROR_PWD_HISTORY_CONFLICT: WIN32_ERROR = 617u32; -pub const ERROR_PWD_TOO_LONG: WIN32_ERROR = 657u32; -pub const ERROR_PWD_TOO_RECENT: WIN32_ERROR = 616u32; -pub const ERROR_PWD_TOO_SHORT: WIN32_ERROR = 615u32; -pub const ERROR_QUOTA_ACTIVITY: WIN32_ERROR = 810u32; -pub const ERROR_QUOTA_LIST_INCONSISTENT: WIN32_ERROR = 621u32; -pub const ERROR_RANGE_LIST_CONFLICT: WIN32_ERROR = 627u32; -pub const ERROR_RANGE_NOT_FOUND: WIN32_ERROR = 644u32; -pub const ERROR_READ_FAULT: WIN32_ERROR = 30u32; -pub const ERROR_RECEIVE_EXPEDITED: WIN32_ERROR = 708u32; -pub const ERROR_RECEIVE_PARTIAL: WIN32_ERROR = 707u32; -pub const ERROR_RECEIVE_PARTIAL_EXPEDITED: WIN32_ERROR = 709u32; -pub const ERROR_RECOVERY_FAILURE: WIN32_ERROR = 1279u32; -pub const ERROR_REDIRECTOR_HAS_OPEN_HANDLES: WIN32_ERROR = 1794u32; -pub const ERROR_REDIR_PAUSED: WIN32_ERROR = 72u32; -pub const ERROR_REGISTRY_CORRUPT: WIN32_ERROR = 1015u32; -pub const ERROR_REGISTRY_HIVE_RECOVERED: WIN32_ERROR = 685u32; -pub const ERROR_REGISTRY_IO_FAILED: WIN32_ERROR = 1016u32; -pub const ERROR_REGISTRY_QUOTA_LIMIT: WIN32_ERROR = 613u32; -pub const ERROR_REGISTRY_RECOVERED: WIN32_ERROR = 1014u32; -pub const ERROR_REG_NAT_CONSUMPTION: WIN32_ERROR = 1261u32; -pub const ERROR_RELOC_CHAIN_XEEDS_SEGLIM: WIN32_ERROR = 201u32; -pub const ERROR_REMOTE_PRINT_CONNECTIONS_BLOCKED: WIN32_ERROR = 1936u32; -pub const ERROR_REMOTE_SESSION_LIMIT_EXCEEDED: WIN32_ERROR = 1220u32; -pub const ERROR_REMOTE_STORAGE_MEDIA_ERROR: WIN32_ERROR = 4352u32; -pub const ERROR_REMOTE_STORAGE_NOT_ACTIVE: WIN32_ERROR = 4351u32; -pub const ERROR_REM_NOT_LIST: WIN32_ERROR = 51u32; -pub const ERROR_REPARSE: WIN32_ERROR = 741u32; -pub const ERROR_REPARSE_ATTRIBUTE_CONFLICT: WIN32_ERROR = 4391u32; -pub const ERROR_REPARSE_OBJECT: WIN32_ERROR = 755u32; -pub const ERROR_REPARSE_POINT_ENCOUNTERED: WIN32_ERROR = 4395u32; -pub const ERROR_REPARSE_TAG_INVALID: WIN32_ERROR = 4393u32; -pub const ERROR_REPARSE_TAG_MISMATCH: WIN32_ERROR = 4394u32; -pub const ERROR_REPLY_MESSAGE_MISMATCH: WIN32_ERROR = 595u32; -pub const ERROR_REQUEST_ABORTED: WIN32_ERROR = 1235u32; -pub const ERROR_REQUEST_OUT_OF_SEQUENCE: WIN32_ERROR = 776u32; -pub const ERROR_REQUEST_PAUSED: WIN32_ERROR = 3050u32; -pub const ERROR_REQUIRES_INTERACTIVE_WINDOWSTATION: WIN32_ERROR = 1459u32; -pub const ERROR_REQ_NOT_ACCEP: WIN32_ERROR = 71u32; -pub const ERROR_RESIDENT_FILE_NOT_SUPPORTED: WIN32_ERROR = 334u32; -pub const ERROR_RESOURCE_CALL_TIMED_OUT: WIN32_ERROR = 5910u32; -pub const ERROR_RESOURCE_DATA_NOT_FOUND: WIN32_ERROR = 1812u32; -pub const ERROR_RESOURCE_LANG_NOT_FOUND: WIN32_ERROR = 1815u32; -pub const ERROR_RESOURCE_NAME_NOT_FOUND: WIN32_ERROR = 1814u32; -pub const ERROR_RESOURCE_REQUIREMENTS_CHANGED: WIN32_ERROR = 756u32; -pub const ERROR_RESOURCE_TYPE_NOT_FOUND: WIN32_ERROR = 1813u32; -pub const ERROR_RESTART_APPLICATION: WIN32_ERROR = 1467u32; -pub const ERROR_RESUME_HIBERNATION: WIN32_ERROR = 727u32; -pub const ERROR_RETRY: WIN32_ERROR = 1237u32; -pub const ERROR_RETURN_ADDRESS_HIJACK_ATTEMPT: WIN32_ERROR = 1662u32; -pub const ERROR_REVISION_MISMATCH: WIN32_ERROR = 1306u32; -pub const ERROR_RING2SEG_MUST_BE_MOVABLE: WIN32_ERROR = 200u32; -pub const ERROR_RING2_STACK_IN_USE: WIN32_ERROR = 207u32; -pub const ERROR_RMODE_APP: WIN32_ERROR = 1153u32; -pub const ERROR_ROWSNOTRELEASED: WIN32_ERROR = 772u32; -pub const ERROR_RUNLEVEL_SWITCH_AGENT_TIMEOUT: WIN32_ERROR = 15403u32; -pub const ERROR_RUNLEVEL_SWITCH_TIMEOUT: WIN32_ERROR = 15402u32; -pub const ERROR_RWRAW_ENCRYPTED_FILE_NOT_ENCRYPTED: WIN32_ERROR = 410u32; -pub const ERROR_RWRAW_ENCRYPTED_INVALID_EDATAINFO_FILEOFFSET: WIN32_ERROR = 411u32; -pub const ERROR_RWRAW_ENCRYPTED_INVALID_EDATAINFO_FILERANGE: WIN32_ERROR = 412u32; -pub const ERROR_RWRAW_ENCRYPTED_INVALID_EDATAINFO_PARAMETER: WIN32_ERROR = 413u32; -pub const ERROR_RXACT_COMMITTED: WIN32_ERROR = 744u32; -pub const ERROR_RXACT_COMMIT_FAILURE: WIN32_ERROR = 1370u32; -pub const ERROR_RXACT_COMMIT_NECESSARY: WIN32_ERROR = 678u32; -pub const ERROR_RXACT_INVALID_STATE: WIN32_ERROR = 1369u32; -pub const ERROR_RXACT_STATE_CREATED: WIN32_ERROR = 701u32; -pub const ERROR_SAME_DRIVE: WIN32_ERROR = 143u32; -pub const ERROR_SAM_INIT_FAILURE: WIN32_ERROR = 8541u32; -pub const ERROR_SCOPE_NOT_FOUND: WIN32_ERROR = 318u32; -pub const ERROR_SCREEN_ALREADY_LOCKED: WIN32_ERROR = 1440u32; -pub const ERROR_SCRUB_DATA_DISABLED: WIN32_ERROR = 332u32; -pub const ERROR_SECRET_TOO_LONG: WIN32_ERROR = 1382u32; -pub const ERROR_SECTION_DIRECT_MAP_ONLY: WIN32_ERROR = 819u32; -pub const ERROR_SECTOR_NOT_FOUND: WIN32_ERROR = 27u32; -pub const ERROR_SECURITY_DENIES_OPERATION: WIN32_ERROR = 447u32; -pub const ERROR_SECURITY_STREAM_IS_INCONSISTENT: WIN32_ERROR = 306u32; -pub const ERROR_SEEK: WIN32_ERROR = 25u32; -pub const ERROR_SEEK_ON_DEVICE: WIN32_ERROR = 132u32; -pub const ERROR_SEGMENT_NOTIFICATION: WIN32_ERROR = 702u32; -pub const ERROR_SEM_IS_SET: WIN32_ERROR = 102u32; -pub const ERROR_SEM_NOT_FOUND: WIN32_ERROR = 187u32; -pub const ERROR_SEM_OWNER_DIED: WIN32_ERROR = 105u32; -pub const ERROR_SEM_TIMEOUT: WIN32_ERROR = 121u32; -pub const ERROR_SEM_USER_LIMIT: WIN32_ERROR = 106u32; -pub const ERROR_SERIAL_NO_DEVICE: WIN32_ERROR = 1118u32; -pub const ERROR_SERVER_DISABLED: WIN32_ERROR = 1341u32; -pub const ERROR_SERVER_HAS_OPEN_HANDLES: WIN32_ERROR = 1811u32; -pub const ERROR_SERVER_NOT_DISABLED: WIN32_ERROR = 1342u32; -pub const ERROR_SERVER_SHUTDOWN_IN_PROGRESS: WIN32_ERROR = 1255u32; -pub const ERROR_SERVER_SID_MISMATCH: WIN32_ERROR = 628u32; -pub const ERROR_SERVER_TRANSPORT_CONFLICT: WIN32_ERROR = 816u32; -pub const ERROR_SERVICE_ALREADY_RUNNING: WIN32_ERROR = 1056u32; -pub const ERROR_SERVICE_CANNOT_ACCEPT_CTRL: WIN32_ERROR = 1061u32; -pub const ERROR_SERVICE_DATABASE_LOCKED: WIN32_ERROR = 1055u32; -pub const ERROR_SERVICE_DEPENDENCY_DELETED: WIN32_ERROR = 1075u32; -pub const ERROR_SERVICE_DEPENDENCY_FAIL: WIN32_ERROR = 1068u32; -pub const ERROR_SERVICE_DISABLED: WIN32_ERROR = 1058u32; -pub const ERROR_SERVICE_DOES_NOT_EXIST: WIN32_ERROR = 1060u32; -pub const ERROR_SERVICE_EXISTS: WIN32_ERROR = 1073u32; -pub const ERROR_SERVICE_LOGON_FAILED: WIN32_ERROR = 1069u32; -pub const ERROR_SERVICE_MARKED_FOR_DELETE: WIN32_ERROR = 1072u32; -pub const ERROR_SERVICE_NEVER_STARTED: WIN32_ERROR = 1077u32; -pub const ERROR_SERVICE_NOTIFICATION: WIN32_ERROR = 716u32; -pub const ERROR_SERVICE_NOTIFY_CLIENT_LAGGING: WIN32_ERROR = 1294u32; -pub const ERROR_SERVICE_NOT_ACTIVE: WIN32_ERROR = 1062u32; -pub const ERROR_SERVICE_NOT_FOUND: WIN32_ERROR = 1243u32; -pub const ERROR_SERVICE_NOT_IN_EXE: WIN32_ERROR = 1083u32; -pub const ERROR_SERVICE_NO_THREAD: WIN32_ERROR = 1054u32; -pub const ERROR_SERVICE_REQUEST_TIMEOUT: WIN32_ERROR = 1053u32; -pub const ERROR_SERVICE_SPECIFIC_ERROR: WIN32_ERROR = 1066u32; -pub const ERROR_SERVICE_START_HANG: WIN32_ERROR = 1070u32; -pub const ERROR_SESSION_CREDENTIAL_CONFLICT: WIN32_ERROR = 1219u32; -pub const ERROR_SESSION_KEY_TOO_SHORT: WIN32_ERROR = 501u32; -pub const ERROR_SETCOUNT_ON_BAD_LB: WIN32_ERROR = 1433u32; -pub const ERROR_SETMARK_DETECTED: WIN32_ERROR = 1103u32; -pub const ERROR_SET_CONTEXT_DENIED: WIN32_ERROR = 1660u32; -pub const ERROR_SET_NOT_FOUND: WIN32_ERROR = 1170u32; -pub const ERROR_SET_POWER_STATE_FAILED: WIN32_ERROR = 1141u32; -pub const ERROR_SET_POWER_STATE_VETOED: WIN32_ERROR = 1140u32; -pub const ERROR_SHARED_POLICY: WIN32_ERROR = 8218u32; -pub const ERROR_SHARING_BUFFER_EXCEEDED: WIN32_ERROR = 36u32; -pub const ERROR_SHARING_PAUSED: WIN32_ERROR = 70u32; -pub const ERROR_SHARING_VIOLATION: WIN32_ERROR = 32u32; -pub const ERROR_SHORT_NAMES_NOT_ENABLED_ON_VOLUME: WIN32_ERROR = 305u32; -pub const ERROR_SHUTDOWN_DISKS_NOT_IN_MAINTENANCE_MODE: WIN32_ERROR = 1192u32; -pub const ERROR_SHUTDOWN_IN_PROGRESS: WIN32_ERROR = 1115u32; -pub const ERROR_SHUTDOWN_IS_SCHEDULED: WIN32_ERROR = 1190u32; -pub const ERROR_SHUTDOWN_USERS_LOGGED_ON: WIN32_ERROR = 1191u32; -pub const ERROR_SIGNAL_PENDING: WIN32_ERROR = 162u32; -pub const ERROR_SIGNAL_REFUSED: WIN32_ERROR = 156u32; -pub const ERROR_SINGLE_INSTANCE_APP: WIN32_ERROR = 1152u32; -pub const ERROR_SMARTCARD_SUBSYSTEM_FAILURE: WIN32_ERROR = 1264u32; -pub const ERROR_SMB1_NOT_AVAILABLE: WIN32_ERROR = 384u32; -pub const ERROR_SMB_GUEST_LOGON_BLOCKED: WIN32_ERROR = 1272u32; -pub const ERROR_SMR_GARBAGE_COLLECTION_REQUIRED: WIN32_ERROR = 4445u32; -pub const ERROR_SOME_NOT_MAPPED: WIN32_ERROR = 1301u32; -pub const ERROR_SOURCE_ELEMENT_EMPTY: WIN32_ERROR = 1160u32; -pub const ERROR_SPARSE_FILE_NOT_SUPPORTED: WIN32_ERROR = 490u32; -pub const ERROR_SPECIAL_ACCOUNT: WIN32_ERROR = 1371u32; -pub const ERROR_SPECIAL_GROUP: WIN32_ERROR = 1372u32; -pub const ERROR_SPECIAL_USER: WIN32_ERROR = 1373u32; -pub const ERROR_SRC_SRV_DLL_LOAD_FAILED: WIN32_ERROR = 428u32; -pub const ERROR_STACK_BUFFER_OVERRUN: WIN32_ERROR = 1282u32; -pub const ERROR_STACK_OVERFLOW: WIN32_ERROR = 1001u32; -pub const ERROR_STACK_OVERFLOW_READ: WIN32_ERROR = 599u32; -pub const ERROR_STOPPED_ON_SYMLINK: WIN32_ERROR = 681u32; -pub const ERROR_STORAGE_LOST_DATA_PERSISTENCE: WIN32_ERROR = 368u32; -pub const ERROR_STORAGE_RESERVE_ALREADY_EXISTS: WIN32_ERROR = 418u32; -pub const ERROR_STORAGE_RESERVE_DOES_NOT_EXIST: WIN32_ERROR = 417u32; -pub const ERROR_STORAGE_RESERVE_ID_INVALID: WIN32_ERROR = 416u32; -pub const ERROR_STORAGE_RESERVE_NOT_EMPTY: WIN32_ERROR = 419u32; -pub const ERROR_STORAGE_STACK_ACCESS_DENIED: WIN32_ERROR = 472u32; -pub const ERROR_STORAGE_TOPOLOGY_ID_MISMATCH: WIN32_ERROR = 345u32; -pub const ERROR_STRICT_CFG_VIOLATION: WIN32_ERROR = 1657u32; -pub const ERROR_SUBST_TO_JOIN: WIN32_ERROR = 141u32; -pub const ERROR_SUBST_TO_SUBST: WIN32_ERROR = 139u32; -pub const ERROR_SUCCESS: WIN32_ERROR = 0u32; -pub const ERROR_SUCCESS_REBOOT_INITIATED: WIN32_ERROR = 1641u32; -pub const ERROR_SWAPERROR: WIN32_ERROR = 999u32; -pub const ERROR_SYMLINK_CLASS_DISABLED: WIN32_ERROR = 1463u32; -pub const ERROR_SYMLINK_NOT_SUPPORTED: WIN32_ERROR = 1464u32; -pub const ERROR_SYNCHRONIZATION_REQUIRED: WIN32_ERROR = 569u32; -pub const ERROR_SYNC_FOREGROUND_REFRESH_REQUIRED: WIN32_ERROR = 1274u32; -pub const ERROR_SYSTEM_HIVE_TOO_LARGE: WIN32_ERROR = 653u32; -pub const ERROR_SYSTEM_IMAGE_BAD_SIGNATURE: WIN32_ERROR = 637u32; -pub const ERROR_SYSTEM_POWERSTATE_COMPLEX_TRANSITION: WIN32_ERROR = 783u32; -pub const ERROR_SYSTEM_POWERSTATE_TRANSITION: WIN32_ERROR = 782u32; -pub const ERROR_SYSTEM_PROCESS_TERMINATED: WIN32_ERROR = 591u32; -pub const ERROR_SYSTEM_SHUTDOWN: WIN32_ERROR = 641u32; -pub const ERROR_SYSTEM_TRACE: WIN32_ERROR = 150u32; -pub const ERROR_THREAD_1_INACTIVE: WIN32_ERROR = 210u32; -pub const ERROR_THREAD_ALREADY_IN_TASK: WIN32_ERROR = 1552u32; -pub const ERROR_THREAD_MODE_ALREADY_BACKGROUND: WIN32_ERROR = 400u32; -pub const ERROR_THREAD_MODE_NOT_BACKGROUND: WIN32_ERROR = 401u32; -pub const ERROR_THREAD_NOT_IN_PROCESS: WIN32_ERROR = 566u32; -pub const ERROR_THREAD_WAS_SUSPENDED: WIN32_ERROR = 699u32; -pub const ERROR_TIMEOUT: WIN32_ERROR = 1460u32; -pub const ERROR_TIMER_NOT_CANCELED: WIN32_ERROR = 541u32; -pub const ERROR_TIMER_RESOLUTION_NOT_SET: WIN32_ERROR = 607u32; -pub const ERROR_TIMER_RESUME_IGNORED: WIN32_ERROR = 722u32; -pub const ERROR_TIME_SENSITIVE_THREAD: WIN32_ERROR = 422u32; -pub const ERROR_TIME_SKEW: WIN32_ERROR = 1398u32; -pub const ERROR_TLW_WITH_WSCHILD: WIN32_ERROR = 1406u32; -pub const ERROR_TOKEN_ALREADY_IN_USE: WIN32_ERROR = 1375u32; -pub const ERROR_TOO_MANY_CMDS: WIN32_ERROR = 56u32; -pub const ERROR_TOO_MANY_CONTEXT_IDS: WIN32_ERROR = 1384u32; -pub const ERROR_TOO_MANY_DESCRIPTORS: WIN32_ERROR = 331u32; -pub const ERROR_TOO_MANY_LINKS: WIN32_ERROR = 1142u32; -pub const ERROR_TOO_MANY_LUIDS_REQUESTED: WIN32_ERROR = 1333u32; -pub const ERROR_TOO_MANY_MODULES: WIN32_ERROR = 214u32; -pub const ERROR_TOO_MANY_MUXWAITERS: WIN32_ERROR = 152u32; -pub const ERROR_TOO_MANY_NAMES: WIN32_ERROR = 68u32; -pub const ERROR_TOO_MANY_OPEN_FILES: WIN32_ERROR = 4u32; -pub const ERROR_TOO_MANY_POSTS: WIN32_ERROR = 298u32; -pub const ERROR_TOO_MANY_SECRETS: WIN32_ERROR = 1381u32; -pub const ERROR_TOO_MANY_SEMAPHORES: WIN32_ERROR = 100u32; -pub const ERROR_TOO_MANY_SEM_REQUESTS: WIN32_ERROR = 103u32; -pub const ERROR_TOO_MANY_SESS: WIN32_ERROR = 69u32; -pub const ERROR_TOO_MANY_SIDS: WIN32_ERROR = 1389u32; -pub const ERROR_TOO_MANY_TCBS: WIN32_ERROR = 155u32; -pub const ERROR_TOO_MANY_THREADS: WIN32_ERROR = 565u32; -pub const ERROR_TRANSLATION_COMPLETE: WIN32_ERROR = 757u32; -pub const ERROR_TRUSTED_DOMAIN_FAILURE: WIN32_ERROR = 1788u32; -pub const ERROR_TRUSTED_RELATIONSHIP_FAILURE: WIN32_ERROR = 1789u32; -pub const ERROR_TRUST_FAILURE: WIN32_ERROR = 1790u32; -pub const ERROR_UNABLE_TO_LOCK_MEDIA: WIN32_ERROR = 1108u32; -pub const ERROR_UNABLE_TO_MOVE_REPLACEMENT: WIN32_ERROR = 1176u32; -pub const ERROR_UNABLE_TO_MOVE_REPLACEMENT_2: WIN32_ERROR = 1177u32; -pub const ERROR_UNABLE_TO_REMOVE_REPLACED: WIN32_ERROR = 1175u32; -pub const ERROR_UNABLE_TO_UNLOAD_MEDIA: WIN32_ERROR = 1109u32; -pub const ERROR_UNDEFINED_CHARACTER: WIN32_ERROR = 583u32; -pub const ERROR_UNDEFINED_SCOPE: WIN32_ERROR = 319u32; -pub const ERROR_UNEXPECTED_MM_CREATE_ERR: WIN32_ERROR = 556u32; -pub const ERROR_UNEXPECTED_MM_EXTEND_ERR: WIN32_ERROR = 558u32; -pub const ERROR_UNEXPECTED_MM_MAP_ERROR: WIN32_ERROR = 557u32; -pub const ERROR_UNEXPECTED_NTCACHEMANAGER_ERROR: WIN32_ERROR = 443u32; -pub const ERROR_UNEXP_NET_ERR: WIN32_ERROR = 59u32; -pub const ERROR_UNHANDLED_EXCEPTION: WIN32_ERROR = 574u32; -pub const ERROR_UNIDENTIFIED_ERROR: WIN32_ERROR = 1287u32; -pub const ERROR_UNKNOWN_COMPONENT: WIN32_ERROR = 1607u32; -pub const ERROR_UNKNOWN_FEATURE: WIN32_ERROR = 1606u32; -pub const ERROR_UNKNOWN_PATCH: WIN32_ERROR = 1647u32; -pub const ERROR_UNKNOWN_PORT: WIN32_ERROR = 1796u32; -pub const ERROR_UNKNOWN_PRINTER_DRIVER: WIN32_ERROR = 1797u32; -pub const ERROR_UNKNOWN_PRINTPROCESSOR: WIN32_ERROR = 1798u32; -pub const ERROR_UNKNOWN_PRODUCT: WIN32_ERROR = 1605u32; -pub const ERROR_UNKNOWN_PROPERTY: WIN32_ERROR = 1608u32; -pub const ERROR_UNKNOWN_REVISION: WIN32_ERROR = 1305u32; -pub const ERROR_UNRECOGNIZED_MEDIA: WIN32_ERROR = 1785u32; -pub const ERROR_UNRECOGNIZED_VOLUME: WIN32_ERROR = 1005u32; -pub const ERROR_UNSATISFIED_DEPENDENCIES: WIN32_ERROR = 441u32; -pub const ERROR_UNSUPPORTED_COMPRESSION: WIN32_ERROR = 618u32; -pub const ERROR_UNSUPPORTED_TYPE: WIN32_ERROR = 1630u32; -pub const ERROR_UNTRUSTED_MOUNT_POINT: WIN32_ERROR = 448u32; -pub const ERROR_UNWIND: WIN32_ERROR = 542u32; -pub const ERROR_UNWIND_CONSOLIDATE: WIN32_ERROR = 684u32; -pub const ERROR_USER_APC: WIN32_ERROR = 737u32; -pub const ERROR_USER_DELETE_TRUST_QUOTA_EXCEEDED: WIN32_ERROR = 1934u32; -pub const ERROR_USER_EXISTS: WIN32_ERROR = 1316u32; -pub const ERROR_USER_MAPPED_FILE: WIN32_ERROR = 1224u32; -pub const ERROR_USER_PROFILE_LOAD: WIN32_ERROR = 500u32; -pub const ERROR_VALIDATE_CONTINUE: WIN32_ERROR = 625u32; -pub const ERROR_VC_DISCONNECTED: WIN32_ERROR = 240u32; -pub const ERROR_VDM_DISALLOWED: WIN32_ERROR = 1286u32; -pub const ERROR_VDM_HARD_ERROR: WIN32_ERROR = 593u32; -pub const ERROR_VERIFIER_STOP: WIN32_ERROR = 537u32; -pub const ERROR_VERSION_PARSE_ERROR: WIN32_ERROR = 777u32; -pub const ERROR_VIRUS_DELETED: WIN32_ERROR = 226u32; -pub const ERROR_VIRUS_INFECTED: WIN32_ERROR = 225u32; -pub const ERROR_VOLSNAP_HIBERNATE_READY: WIN32_ERROR = 761u32; -pub const ERROR_VOLSNAP_PREPARE_HIBERNATE: WIN32_ERROR = 655u32; -pub const ERROR_VOLUME_MOUNTED: WIN32_ERROR = 743u32; -pub const ERROR_VOLUME_NOT_CLUSTER_ALIGNED: WIN32_ERROR = 407u32; -pub const ERROR_VOLUME_NOT_SIS_ENABLED: WIN32_ERROR = 4500u32; -pub const ERROR_VOLUME_NOT_SUPPORTED: WIN32_ERROR = 492u32; -pub const ERROR_VOLUME_NOT_SUPPORT_EFS: WIN32_ERROR = 6014u32; -pub const ERROR_VOLUME_WRITE_ACCESS_DENIED: WIN32_ERROR = 508u32; -pub const ERROR_WAIT_1: WIN32_ERROR = 731u32; -pub const ERROR_WAIT_2: WIN32_ERROR = 732u32; -pub const ERROR_WAIT_3: WIN32_ERROR = 733u32; -pub const ERROR_WAIT_63: WIN32_ERROR = 734u32; -pub const ERROR_WAIT_FOR_OPLOCK: WIN32_ERROR = 765u32; -pub const ERROR_WAIT_NO_CHILDREN: WIN32_ERROR = 128u32; -pub const ERROR_WAKE_SYSTEM: WIN32_ERROR = 730u32; -pub const ERROR_WAKE_SYSTEM_DEBUGGER: WIN32_ERROR = 675u32; -pub const ERROR_WAS_LOCKED: WIN32_ERROR = 717u32; -pub const ERROR_WAS_UNLOCKED: WIN32_ERROR = 715u32; -pub const ERROR_WEAK_WHFBKEY_BLOCKED: WIN32_ERROR = 8651u32; -pub const ERROR_WINDOW_NOT_COMBOBOX: WIN32_ERROR = 1423u32; -pub const ERROR_WINDOW_NOT_DIALOG: WIN32_ERROR = 1420u32; -pub const ERROR_WINDOW_OF_OTHER_THREAD: WIN32_ERROR = 1408u32; -pub const ERROR_WIP_ENCRYPTION_FAILED: WIN32_ERROR = 6023u32; -pub const ERROR_WOF_FILE_RESOURCE_TABLE_CORRUPT: WIN32_ERROR = 4448u32; -pub const ERROR_WOF_WIM_HEADER_CORRUPT: WIN32_ERROR = 4446u32; -pub const ERROR_WOF_WIM_RESOURCE_TABLE_CORRUPT: WIN32_ERROR = 4447u32; -pub const ERROR_WORKING_SET_QUOTA: WIN32_ERROR = 1453u32; -pub const ERROR_WOW_ASSERTION: WIN32_ERROR = 670u32; -pub const ERROR_WRITE_FAULT: WIN32_ERROR = 29u32; -pub const ERROR_WRITE_PROTECT: WIN32_ERROR = 19u32; -pub const ERROR_WRONG_COMPARTMENT: WIN32_ERROR = 1468u32; -pub const ERROR_WRONG_DISK: WIN32_ERROR = 34u32; -pub const ERROR_WRONG_EFS: WIN32_ERROR = 6005u32; -pub const ERROR_WRONG_PASSWORD: WIN32_ERROR = 1323u32; -pub const ERROR_WRONG_TARGET_NAME: WIN32_ERROR = 1396u32; -pub const ERROR_WX86_ERROR: WIN32_ERROR = 540u32; -pub const ERROR_WX86_WARNING: WIN32_ERROR = 539u32; -pub const ERROR_XMLDSIG_ERROR: WIN32_ERROR = 1466u32; -pub const ERROR_XML_PARSE_ERROR: WIN32_ERROR = 1465u32; -pub type EXCEPTION_DISPOSITION = i32; -pub const EXCEPTION_MAXIMUM_PARAMETERS: u32 = 15u32; -#[repr(C)] -pub struct EXCEPTION_RECORD { - pub ExceptionCode: NTSTATUS, - pub ExceptionFlags: u32, - pub ExceptionRecord: *mut EXCEPTION_RECORD, - pub ExceptionAddress: *mut core::ffi::c_void, - pub NumberParameters: u32, - pub ExceptionInformation: [usize; 15], -} -impl Copy for EXCEPTION_RECORD {} -impl Clone for EXCEPTION_RECORD { - fn clone(&self) -> Self { - *self - } -} -pub const EXCEPTION_STACK_OVERFLOW: NTSTATUS = 0xC00000FD_u32 as _; -pub const EXTENDED_STARTUPINFO_PRESENT: PROCESS_CREATION_FLAGS = 524288u32; -pub const E_NOTIMPL: HRESULT = 0x80004001_u32 as _; -pub const ExceptionCollidedUnwind: EXCEPTION_DISPOSITION = 3i32; -pub const ExceptionContinueExecution: EXCEPTION_DISPOSITION = 0i32; -pub const ExceptionContinueSearch: EXCEPTION_DISPOSITION = 1i32; -pub const ExceptionNestedException: EXCEPTION_DISPOSITION = 2i32; -pub type FACILITY_CODE = u32; -pub const FACILITY_NT_BIT: FACILITY_CODE = 268435456u32; -pub const FALSE: BOOL = 0i32; -pub type FARPROC = Option isize>; -pub const FAST_FAIL_FATAL_APP_EXIT: u32 = 7u32; -#[repr(C)] -pub struct FD_SET { - pub fd_count: u32, - pub fd_array: [SOCKET; 64], -} -impl Copy for FD_SET {} -impl Clone for FD_SET { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -pub struct FILETIME { - pub dwLowDateTime: u32, - pub dwHighDateTime: u32, -} -impl Copy for FILETIME {} -impl Clone for FILETIME { - fn clone(&self) -> Self { - *self - } -} -pub type FILE_ACCESS_RIGHTS = u32; -pub const FILE_ADD_FILE: FILE_ACCESS_RIGHTS = 2u32; -pub const FILE_ADD_SUBDIRECTORY: FILE_ACCESS_RIGHTS = 4u32; -#[repr(C)] -pub struct FILE_ALLOCATION_INFO { - pub AllocationSize: i64, -} -impl Copy for FILE_ALLOCATION_INFO {} -impl Clone for FILE_ALLOCATION_INFO { - fn clone(&self) -> Self { - *self - } -} -pub const FILE_ALL_ACCESS: FILE_ACCESS_RIGHTS = 2032127u32; -pub const FILE_APPEND_DATA: FILE_ACCESS_RIGHTS = 4u32; -pub const FILE_ATTRIBUTE_ARCHIVE: FILE_FLAGS_AND_ATTRIBUTES = 32u32; -pub const FILE_ATTRIBUTE_COMPRESSED: FILE_FLAGS_AND_ATTRIBUTES = 2048u32; -pub const FILE_ATTRIBUTE_DEVICE: FILE_FLAGS_AND_ATTRIBUTES = 64u32; -pub const FILE_ATTRIBUTE_DIRECTORY: FILE_FLAGS_AND_ATTRIBUTES = 16u32; -pub const FILE_ATTRIBUTE_EA: FILE_FLAGS_AND_ATTRIBUTES = 262144u32; -pub const FILE_ATTRIBUTE_ENCRYPTED: FILE_FLAGS_AND_ATTRIBUTES = 16384u32; -pub const FILE_ATTRIBUTE_HIDDEN: FILE_FLAGS_AND_ATTRIBUTES = 2u32; -pub const FILE_ATTRIBUTE_INTEGRITY_STREAM: FILE_FLAGS_AND_ATTRIBUTES = 32768u32; -pub const FILE_ATTRIBUTE_NORMAL: FILE_FLAGS_AND_ATTRIBUTES = 128u32; -pub const FILE_ATTRIBUTE_NOT_CONTENT_INDEXED: FILE_FLAGS_AND_ATTRIBUTES = 8192u32; -pub const FILE_ATTRIBUTE_NO_SCRUB_DATA: FILE_FLAGS_AND_ATTRIBUTES = 131072u32; -pub const FILE_ATTRIBUTE_OFFLINE: FILE_FLAGS_AND_ATTRIBUTES = 4096u32; -pub const FILE_ATTRIBUTE_PINNED: FILE_FLAGS_AND_ATTRIBUTES = 524288u32; -pub const FILE_ATTRIBUTE_READONLY: FILE_FLAGS_AND_ATTRIBUTES = 1u32; -pub const FILE_ATTRIBUTE_RECALL_ON_DATA_ACCESS: FILE_FLAGS_AND_ATTRIBUTES = 4194304u32; -pub const FILE_ATTRIBUTE_RECALL_ON_OPEN: FILE_FLAGS_AND_ATTRIBUTES = 262144u32; -pub const FILE_ATTRIBUTE_REPARSE_POINT: FILE_FLAGS_AND_ATTRIBUTES = 1024u32; -pub const FILE_ATTRIBUTE_SPARSE_FILE: FILE_FLAGS_AND_ATTRIBUTES = 512u32; -pub const FILE_ATTRIBUTE_SYSTEM: FILE_FLAGS_AND_ATTRIBUTES = 4u32; -#[repr(C)] -pub struct FILE_ATTRIBUTE_TAG_INFO { - pub FileAttributes: u32, - pub ReparseTag: u32, -} -impl Copy for FILE_ATTRIBUTE_TAG_INFO {} -impl Clone for FILE_ATTRIBUTE_TAG_INFO { - fn clone(&self) -> Self { - *self - } -} -pub const FILE_ATTRIBUTE_TEMPORARY: FILE_FLAGS_AND_ATTRIBUTES = 256u32; -pub const FILE_ATTRIBUTE_UNPINNED: FILE_FLAGS_AND_ATTRIBUTES = 1048576u32; -pub const FILE_ATTRIBUTE_VIRTUAL: FILE_FLAGS_AND_ATTRIBUTES = 65536u32; -#[repr(C)] -pub struct FILE_BASIC_INFO { - pub CreationTime: i64, - pub LastAccessTime: i64, - pub LastWriteTime: i64, - pub ChangeTime: i64, - pub FileAttributes: u32, -} -impl Copy for FILE_BASIC_INFO {} -impl Clone for FILE_BASIC_INFO { - fn clone(&self) -> Self { - *self - } -} -pub const FILE_BEGIN: SET_FILE_POINTER_MOVE_METHOD = 0u32; -pub const FILE_COMPLETE_IF_OPLOCKED: NTCREATEFILE_CREATE_OPTIONS = 256u32; -pub const FILE_CONTAINS_EXTENDED_CREATE_INFORMATION: NTCREATEFILE_CREATE_OPTIONS = 268435456u32; -pub const FILE_CREATE: NTCREATEFILE_CREATE_DISPOSITION = 2u32; -pub const FILE_CREATE_PIPE_INSTANCE: FILE_ACCESS_RIGHTS = 4u32; -pub const FILE_CREATE_TREE_CONNECTION: NTCREATEFILE_CREATE_OPTIONS = 128u32; -pub type FILE_CREATION_DISPOSITION = u32; -pub const FILE_CURRENT: SET_FILE_POINTER_MOVE_METHOD = 1u32; -pub const FILE_DELETE_CHILD: FILE_ACCESS_RIGHTS = 64u32; -pub const FILE_DELETE_ON_CLOSE: NTCREATEFILE_CREATE_OPTIONS = 4096u32; -pub const FILE_DIRECTORY_FILE: NTCREATEFILE_CREATE_OPTIONS = 1u32; -pub const FILE_DISALLOW_EXCLUSIVE: NTCREATEFILE_CREATE_OPTIONS = 131072u32; -pub const FILE_DISPOSITION_FLAG_DELETE: FILE_DISPOSITION_INFO_EX_FLAGS = 1u32; -pub const FILE_DISPOSITION_FLAG_DO_NOT_DELETE: FILE_DISPOSITION_INFO_EX_FLAGS = 0u32; -pub const FILE_DISPOSITION_FLAG_FORCE_IMAGE_SECTION_CHECK: FILE_DISPOSITION_INFO_EX_FLAGS = 4u32; -pub const FILE_DISPOSITION_FLAG_IGNORE_READONLY_ATTRIBUTE: FILE_DISPOSITION_INFO_EX_FLAGS = 16u32; -pub const FILE_DISPOSITION_FLAG_ON_CLOSE: FILE_DISPOSITION_INFO_EX_FLAGS = 8u32; -pub const FILE_DISPOSITION_FLAG_POSIX_SEMANTICS: FILE_DISPOSITION_INFO_EX_FLAGS = 2u32; -#[repr(C)] -pub struct FILE_DISPOSITION_INFO { - pub DeleteFile: BOOLEAN, -} -impl Copy for FILE_DISPOSITION_INFO {} -impl Clone for FILE_DISPOSITION_INFO { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -pub struct FILE_DISPOSITION_INFO_EX { - pub Flags: FILE_DISPOSITION_INFO_EX_FLAGS, -} -impl Copy for FILE_DISPOSITION_INFO_EX {} -impl Clone for FILE_DISPOSITION_INFO_EX { - fn clone(&self) -> Self { - *self - } -} -pub type FILE_DISPOSITION_INFO_EX_FLAGS = u32; -pub const FILE_END: SET_FILE_POINTER_MOVE_METHOD = 2u32; -#[repr(C)] -pub struct FILE_END_OF_FILE_INFO { - pub EndOfFile: i64, -} -impl Copy for FILE_END_OF_FILE_INFO {} -impl Clone for FILE_END_OF_FILE_INFO { - fn clone(&self) -> Self { - *self - } -} -pub const FILE_EXECUTE: FILE_ACCESS_RIGHTS = 32u32; -pub type FILE_FLAGS_AND_ATTRIBUTES = u32; -pub const FILE_FLAG_BACKUP_SEMANTICS: FILE_FLAGS_AND_ATTRIBUTES = 33554432u32; -pub const FILE_FLAG_DELETE_ON_CLOSE: FILE_FLAGS_AND_ATTRIBUTES = 67108864u32; -pub const FILE_FLAG_FIRST_PIPE_INSTANCE: FILE_FLAGS_AND_ATTRIBUTES = 524288u32; -pub const FILE_FLAG_NO_BUFFERING: FILE_FLAGS_AND_ATTRIBUTES = 536870912u32; -pub const FILE_FLAG_OPEN_NO_RECALL: FILE_FLAGS_AND_ATTRIBUTES = 1048576u32; -pub const FILE_FLAG_OPEN_REPARSE_POINT: FILE_FLAGS_AND_ATTRIBUTES = 2097152u32; -pub const FILE_FLAG_OVERLAPPED: FILE_FLAGS_AND_ATTRIBUTES = 1073741824u32; -pub const FILE_FLAG_POSIX_SEMANTICS: FILE_FLAGS_AND_ATTRIBUTES = 16777216u32; -pub const FILE_FLAG_RANDOM_ACCESS: FILE_FLAGS_AND_ATTRIBUTES = 268435456u32; -pub const FILE_FLAG_SEQUENTIAL_SCAN: FILE_FLAGS_AND_ATTRIBUTES = 134217728u32; -pub const FILE_FLAG_SESSION_AWARE: FILE_FLAGS_AND_ATTRIBUTES = 8388608u32; -pub const FILE_FLAG_WRITE_THROUGH: FILE_FLAGS_AND_ATTRIBUTES = 2147483648u32; -pub const FILE_GENERIC_EXECUTE: FILE_ACCESS_RIGHTS = 1179808u32; -pub const FILE_GENERIC_READ: FILE_ACCESS_RIGHTS = 1179785u32; -pub const FILE_GENERIC_WRITE: FILE_ACCESS_RIGHTS = 1179926u32; -#[repr(C)] -pub struct FILE_ID_BOTH_DIR_INFO { - pub NextEntryOffset: u32, - pub FileIndex: u32, - pub CreationTime: i64, - pub LastAccessTime: i64, - pub LastWriteTime: i64, - pub ChangeTime: i64, - pub EndOfFile: i64, - pub AllocationSize: i64, - pub FileAttributes: u32, - pub FileNameLength: u32, - pub EaSize: u32, - pub ShortNameLength: i8, - pub ShortName: [u16; 12], - pub FileId: i64, - pub FileName: [u16; 1], -} -impl Copy for FILE_ID_BOTH_DIR_INFO {} -impl Clone for FILE_ID_BOTH_DIR_INFO { - fn clone(&self) -> Self { - *self - } -} -pub type FILE_INFO_BY_HANDLE_CLASS = i32; -#[repr(C)] -pub struct FILE_IO_PRIORITY_HINT_INFO { - pub PriorityHint: PRIORITY_HINT, -} -impl Copy for FILE_IO_PRIORITY_HINT_INFO {} -impl Clone for FILE_IO_PRIORITY_HINT_INFO { - fn clone(&self) -> Self { - *self - } -} -pub const FILE_LIST_DIRECTORY: FILE_ACCESS_RIGHTS = 1u32; -pub const FILE_NAME_NORMALIZED: GETFINALPATHNAMEBYHANDLE_FLAGS = 0u32; -pub const FILE_NAME_OPENED: GETFINALPATHNAMEBYHANDLE_FLAGS = 8u32; -pub const FILE_NON_DIRECTORY_FILE: NTCREATEFILE_CREATE_OPTIONS = 64u32; -pub const FILE_NO_COMPRESSION: NTCREATEFILE_CREATE_OPTIONS = 32768u32; -pub const FILE_NO_EA_KNOWLEDGE: NTCREATEFILE_CREATE_OPTIONS = 512u32; -pub const FILE_NO_INTERMEDIATE_BUFFERING: NTCREATEFILE_CREATE_OPTIONS = 8u32; -pub const FILE_OPEN: NTCREATEFILE_CREATE_DISPOSITION = 1u32; -pub const FILE_OPEN_BY_FILE_ID: NTCREATEFILE_CREATE_OPTIONS = 8192u32; -pub const FILE_OPEN_FOR_BACKUP_INTENT: NTCREATEFILE_CREATE_OPTIONS = 16384u32; -pub const FILE_OPEN_FOR_FREE_SPACE_QUERY: NTCREATEFILE_CREATE_OPTIONS = 8388608u32; -pub const FILE_OPEN_IF: NTCREATEFILE_CREATE_DISPOSITION = 3u32; -pub const FILE_OPEN_NO_RECALL: NTCREATEFILE_CREATE_OPTIONS = 4194304u32; -pub const FILE_OPEN_REPARSE_POINT: NTCREATEFILE_CREATE_OPTIONS = 2097152u32; -pub const FILE_OPEN_REQUIRING_OPLOCK: NTCREATEFILE_CREATE_OPTIONS = 65536u32; -pub const FILE_OVERWRITE: NTCREATEFILE_CREATE_DISPOSITION = 4u32; -pub const FILE_OVERWRITE_IF: NTCREATEFILE_CREATE_DISPOSITION = 5u32; -pub const FILE_RANDOM_ACCESS: NTCREATEFILE_CREATE_OPTIONS = 2048u32; -pub const FILE_READ_ATTRIBUTES: FILE_ACCESS_RIGHTS = 128u32; -pub const FILE_READ_DATA: FILE_ACCESS_RIGHTS = 1u32; -pub const FILE_READ_EA: FILE_ACCESS_RIGHTS = 8u32; -pub const FILE_RESERVE_OPFILTER: NTCREATEFILE_CREATE_OPTIONS = 1048576u32; -pub const FILE_SEQUENTIAL_ONLY: NTCREATEFILE_CREATE_OPTIONS = 4u32; -pub const FILE_SESSION_AWARE: NTCREATEFILE_CREATE_OPTIONS = 262144u32; -pub const FILE_SHARE_DELETE: FILE_SHARE_MODE = 4u32; -pub type FILE_SHARE_MODE = u32; -pub const FILE_SHARE_NONE: FILE_SHARE_MODE = 0u32; -pub const FILE_SHARE_READ: FILE_SHARE_MODE = 1u32; -pub const FILE_SHARE_WRITE: FILE_SHARE_MODE = 2u32; -#[repr(C)] -pub struct FILE_STANDARD_INFO { - pub AllocationSize: i64, - pub EndOfFile: i64, - pub NumberOfLinks: u32, - pub DeletePending: BOOLEAN, - pub Directory: BOOLEAN, -} -impl Copy for FILE_STANDARD_INFO {} -impl Clone for FILE_STANDARD_INFO { - fn clone(&self) -> Self { - *self - } -} -pub const FILE_SUPERSEDE: NTCREATEFILE_CREATE_DISPOSITION = 0u32; -pub const FILE_SYNCHRONOUS_IO_ALERT: NTCREATEFILE_CREATE_OPTIONS = 16u32; -pub const FILE_SYNCHRONOUS_IO_NONALERT: NTCREATEFILE_CREATE_OPTIONS = 32u32; -pub const FILE_TRAVERSE: FILE_ACCESS_RIGHTS = 32u32; -pub type FILE_TYPE = u32; -pub const FILE_TYPE_CHAR: FILE_TYPE = 2u32; -pub const FILE_TYPE_DISK: FILE_TYPE = 1u32; -pub const FILE_TYPE_PIPE: FILE_TYPE = 3u32; -pub const FILE_TYPE_REMOTE: FILE_TYPE = 32768u32; -pub const FILE_TYPE_UNKNOWN: FILE_TYPE = 0u32; -pub const FILE_WRITE_ATTRIBUTES: FILE_ACCESS_RIGHTS = 256u32; -pub const FILE_WRITE_DATA: FILE_ACCESS_RIGHTS = 2u32; -pub const FILE_WRITE_EA: FILE_ACCESS_RIGHTS = 16u32; -pub const FILE_WRITE_THROUGH: NTCREATEFILE_CREATE_OPTIONS = 2u32; -pub const FIONBIO: i32 = -2147195266i32; -#[repr(C)] -#[cfg(any(target_arch = "aarch64", target_arch = "arm64ec", target_arch = "x86_64"))] -pub struct FLOATING_SAVE_AREA { - pub ControlWord: u32, - pub StatusWord: u32, - pub TagWord: u32, - pub ErrorOffset: u32, - pub ErrorSelector: u32, - pub DataOffset: u32, - pub DataSelector: u32, - pub RegisterArea: [u8; 80], - pub Cr0NpxState: u32, -} -#[cfg(any(target_arch = "aarch64", target_arch = "arm64ec", target_arch = "x86_64"))] -impl Copy for FLOATING_SAVE_AREA {} -#[cfg(any(target_arch = "aarch64", target_arch = "arm64ec", target_arch = "x86_64"))] -impl Clone for FLOATING_SAVE_AREA { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -#[cfg(target_arch = "x86")] -pub struct FLOATING_SAVE_AREA { - pub ControlWord: u32, - pub StatusWord: u32, - pub TagWord: u32, - pub ErrorOffset: u32, - pub ErrorSelector: u32, - pub DataOffset: u32, - pub DataSelector: u32, - pub RegisterArea: [u8; 80], - pub Spare0: u32, -} -#[cfg(target_arch = "x86")] -impl Copy for FLOATING_SAVE_AREA {} -#[cfg(target_arch = "x86")] -impl Clone for FLOATING_SAVE_AREA { - fn clone(&self) -> Self { - *self - } -} -pub const FORMAT_MESSAGE_ALLOCATE_BUFFER: FORMAT_MESSAGE_OPTIONS = 256u32; -pub const FORMAT_MESSAGE_ARGUMENT_ARRAY: FORMAT_MESSAGE_OPTIONS = 8192u32; -pub const FORMAT_MESSAGE_FROM_HMODULE: FORMAT_MESSAGE_OPTIONS = 2048u32; -pub const FORMAT_MESSAGE_FROM_STRING: FORMAT_MESSAGE_OPTIONS = 1024u32; -pub const FORMAT_MESSAGE_FROM_SYSTEM: FORMAT_MESSAGE_OPTIONS = 4096u32; -pub const FORMAT_MESSAGE_IGNORE_INSERTS: FORMAT_MESSAGE_OPTIONS = 512u32; -pub type FORMAT_MESSAGE_OPTIONS = u32; -pub const FRS_ERR_SYSVOL_POPULATE_TIMEOUT: i32 = 8014i32; -pub const FSCTL_GET_REPARSE_POINT: u32 = 589992u32; -pub const FSCTL_SET_REPARSE_POINT: u32 = 589988u32; -pub const FileAlignmentInfo: FILE_INFO_BY_HANDLE_CLASS = 17i32; -pub const FileAllocationInfo: FILE_INFO_BY_HANDLE_CLASS = 5i32; -pub const FileAttributeTagInfo: FILE_INFO_BY_HANDLE_CLASS = 9i32; -pub const FileBasicInfo: FILE_INFO_BY_HANDLE_CLASS = 0i32; -pub const FileCaseSensitiveInfo: FILE_INFO_BY_HANDLE_CLASS = 23i32; -pub const FileCompressionInfo: FILE_INFO_BY_HANDLE_CLASS = 8i32; -pub const FileDispositionInfo: FILE_INFO_BY_HANDLE_CLASS = 4i32; -pub const FileDispositionInfoEx: FILE_INFO_BY_HANDLE_CLASS = 21i32; -pub const FileEndOfFileInfo: FILE_INFO_BY_HANDLE_CLASS = 6i32; -pub const FileFullDirectoryInfo: FILE_INFO_BY_HANDLE_CLASS = 14i32; -pub const FileFullDirectoryRestartInfo: FILE_INFO_BY_HANDLE_CLASS = 15i32; -pub const FileIdBothDirectoryInfo: FILE_INFO_BY_HANDLE_CLASS = 10i32; -pub const FileIdBothDirectoryRestartInfo: FILE_INFO_BY_HANDLE_CLASS = 11i32; -pub const FileIdExtdDirectoryInfo: FILE_INFO_BY_HANDLE_CLASS = 19i32; -pub const FileIdExtdDirectoryRestartInfo: FILE_INFO_BY_HANDLE_CLASS = 20i32; -pub const FileIdInfo: FILE_INFO_BY_HANDLE_CLASS = 18i32; -pub const FileIoPriorityHintInfo: FILE_INFO_BY_HANDLE_CLASS = 12i32; -pub const FileNameInfo: FILE_INFO_BY_HANDLE_CLASS = 2i32; -pub const FileNormalizedNameInfo: FILE_INFO_BY_HANDLE_CLASS = 24i32; -pub const FileRemoteProtocolInfo: FILE_INFO_BY_HANDLE_CLASS = 13i32; -pub const FileRenameInfo: FILE_INFO_BY_HANDLE_CLASS = 3i32; -pub const FileRenameInfoEx: FILE_INFO_BY_HANDLE_CLASS = 22i32; -pub const FileStandardInfo: FILE_INFO_BY_HANDLE_CLASS = 1i32; -pub const FileStorageInfo: FILE_INFO_BY_HANDLE_CLASS = 16i32; -pub const FileStreamInfo: FILE_INFO_BY_HANDLE_CLASS = 7i32; -pub type GENERIC_ACCESS_RIGHTS = u32; -pub const GENERIC_ALL: GENERIC_ACCESS_RIGHTS = 268435456u32; -pub const GENERIC_EXECUTE: GENERIC_ACCESS_RIGHTS = 536870912u32; -pub const GENERIC_READ: GENERIC_ACCESS_RIGHTS = 2147483648u32; -pub const GENERIC_WRITE: GENERIC_ACCESS_RIGHTS = 1073741824u32; -pub type GETFINALPATHNAMEBYHANDLE_FLAGS = u32; -#[repr(C)] -pub struct GUID { - pub data1: u32, - pub data2: u16, - pub data3: u16, - pub data4: [u8; 8], -} -impl Copy for GUID {} -impl Clone for GUID { - fn clone(&self) -> Self { - *self - } -} -impl GUID { - pub const fn from_u128(uuid: u128) -> Self { - Self { - data1: (uuid >> 96) as u32, - data2: (uuid >> 80 & 0xffff) as u16, - data3: (uuid >> 64 & 0xffff) as u16, - data4: (uuid as u64).to_be_bytes(), - } - } -} -pub type HANDLE = *mut core::ffi::c_void; -pub type HANDLE_FLAGS = u32; -pub const HANDLE_FLAG_INHERIT: HANDLE_FLAGS = 1u32; -pub const HANDLE_FLAG_PROTECT_FROM_CLOSE: HANDLE_FLAGS = 2u32; -pub const HIGH_PRIORITY_CLASS: PROCESS_CREATION_FLAGS = 128u32; -pub type HLOCAL = *mut core::ffi::c_void; -pub type HMODULE = *mut core::ffi::c_void; -pub type HRESULT = i32; -pub const IDLE_PRIORITY_CLASS: PROCESS_CREATION_FLAGS = 64u32; -#[repr(C)] -pub struct IN6_ADDR { - pub u: IN6_ADDR_0, -} -impl Copy for IN6_ADDR {} -impl Clone for IN6_ADDR { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -pub union IN6_ADDR_0 { - pub Byte: [u8; 16], - pub Word: [u16; 8], -} -impl Copy for IN6_ADDR_0 {} -impl Clone for IN6_ADDR_0 { - fn clone(&self) -> Self { - *self - } -} -pub const INFINITE: u32 = 4294967295u32; -pub const INHERIT_CALLER_PRIORITY: PROCESS_CREATION_FLAGS = 131072u32; -pub const INHERIT_PARENT_AFFINITY: PROCESS_CREATION_FLAGS = 65536u32; -#[repr(C)] -pub union INIT_ONCE { - pub Ptr: *mut core::ffi::c_void, -} -impl Copy for INIT_ONCE {} -impl Clone for INIT_ONCE { - fn clone(&self) -> Self { - *self - } -} -pub const INIT_ONCE_INIT_FAILED: u32 = 4u32; -pub const INVALID_FILE_ATTRIBUTES: u32 = 4294967295u32; -pub const INVALID_SOCKET: SOCKET = -1i32 as _; -#[repr(C)] -pub struct IN_ADDR { - pub S_un: IN_ADDR_0, -} -impl Copy for IN_ADDR {} -impl Clone for IN_ADDR { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -pub union IN_ADDR_0 { - pub S_un_b: IN_ADDR_0_0, - pub S_un_w: IN_ADDR_0_1, - pub S_addr: u32, -} -impl Copy for IN_ADDR_0 {} -impl Clone for IN_ADDR_0 { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -pub struct IN_ADDR_0_0 { - pub s_b1: u8, - pub s_b2: u8, - pub s_b3: u8, - pub s_b4: u8, -} -impl Copy for IN_ADDR_0_0 {} -impl Clone for IN_ADDR_0_0 { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -pub struct IN_ADDR_0_1 { - pub s_w1: u16, - pub s_w2: u16, -} -impl Copy for IN_ADDR_0_1 {} -impl Clone for IN_ADDR_0_1 { - fn clone(&self) -> Self { - *self - } -} -pub const IO_REPARSE_TAG_MOUNT_POINT: u32 = 2684354563u32; -pub const IO_REPARSE_TAG_SYMLINK: u32 = 2684354572u32; -#[repr(C)] -pub struct IO_STATUS_BLOCK { - pub Anonymous: IO_STATUS_BLOCK_0, - pub Information: usize, -} -impl Copy for IO_STATUS_BLOCK {} -impl Clone for IO_STATUS_BLOCK { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -pub union IO_STATUS_BLOCK_0 { - pub Status: NTSTATUS, - pub Pointer: *mut core::ffi::c_void, -} -impl Copy for IO_STATUS_BLOCK_0 {} -impl Clone for IO_STATUS_BLOCK_0 { - fn clone(&self) -> Self { - *self - } -} -pub type IPPROTO = i32; -pub const IPPROTO_AH: IPPROTO = 51i32; -pub const IPPROTO_CBT: IPPROTO = 7i32; -pub const IPPROTO_DSTOPTS: IPPROTO = 60i32; -pub const IPPROTO_EGP: IPPROTO = 8i32; -pub const IPPROTO_ESP: IPPROTO = 50i32; -pub const IPPROTO_FRAGMENT: IPPROTO = 44i32; -pub const IPPROTO_GGP: IPPROTO = 3i32; -pub const IPPROTO_HOPOPTS: IPPROTO = 0i32; -pub const IPPROTO_ICLFXBM: IPPROTO = 78i32; -pub const IPPROTO_ICMP: IPPROTO = 1i32; -pub const IPPROTO_ICMPV6: IPPROTO = 58i32; -pub const IPPROTO_IDP: IPPROTO = 22i32; -pub const IPPROTO_IGMP: IPPROTO = 2i32; -pub const IPPROTO_IGP: IPPROTO = 9i32; -pub const IPPROTO_IP: IPPROTO = 0i32; -pub const IPPROTO_IPV4: IPPROTO = 4i32; -pub const IPPROTO_IPV6: IPPROTO = 41i32; -pub const IPPROTO_L2TP: IPPROTO = 115i32; -pub const IPPROTO_MAX: IPPROTO = 256i32; -pub const IPPROTO_ND: IPPROTO = 77i32; -pub const IPPROTO_NONE: IPPROTO = 59i32; -pub const IPPROTO_PGM: IPPROTO = 113i32; -pub const IPPROTO_PIM: IPPROTO = 103i32; -pub const IPPROTO_PUP: IPPROTO = 12i32; -pub const IPPROTO_RAW: IPPROTO = 255i32; -pub const IPPROTO_RDP: IPPROTO = 27i32; -pub const IPPROTO_RESERVED_IPSEC: IPPROTO = 258i32; -pub const IPPROTO_RESERVED_IPSECOFFLOAD: IPPROTO = 259i32; -pub const IPPROTO_RESERVED_MAX: IPPROTO = 261i32; -pub const IPPROTO_RESERVED_RAW: IPPROTO = 257i32; -pub const IPPROTO_RESERVED_WNV: IPPROTO = 260i32; -pub const IPPROTO_RM: IPPROTO = 113i32; -pub const IPPROTO_ROUTING: IPPROTO = 43i32; -pub const IPPROTO_SCTP: IPPROTO = 132i32; -pub const IPPROTO_ST: IPPROTO = 5i32; -pub const IPPROTO_TCP: IPPROTO = 6i32; -pub const IPPROTO_UDP: IPPROTO = 17i32; -pub const IPV6_ADD_MEMBERSHIP: i32 = 12i32; -pub const IPV6_DROP_MEMBERSHIP: i32 = 13i32; -#[repr(C)] -pub struct IPV6_MREQ { - pub ipv6mr_multiaddr: IN6_ADDR, - pub ipv6mr_interface: u32, -} -impl Copy for IPV6_MREQ {} -impl Clone for IPV6_MREQ { - fn clone(&self) -> Self { - *self - } -} -pub const IPV6_MULTICAST_LOOP: i32 = 11i32; -pub const IPV6_V6ONLY: i32 = 27i32; -pub const IP_ADD_MEMBERSHIP: i32 = 12i32; -pub const IP_DROP_MEMBERSHIP: i32 = 13i32; -#[repr(C)] -pub struct IP_MREQ { - pub imr_multiaddr: IN_ADDR, - pub imr_interface: IN_ADDR, -} -impl Copy for IP_MREQ {} -impl Clone for IP_MREQ { - fn clone(&self) -> Self { - *self - } -} -pub const IP_MULTICAST_LOOP: i32 = 11i32; -pub const IP_MULTICAST_TTL: i32 = 10i32; -pub const IP_TTL: i32 = 4i32; -#[repr(C)] -pub struct LINGER { - pub l_onoff: u16, - pub l_linger: u16, -} -impl Copy for LINGER {} -impl Clone for LINGER { - fn clone(&self) -> Self { - *self - } -} -pub type LPOVERLAPPED_COMPLETION_ROUTINE = Option< - unsafe extern "system" fn( - dwerrorcode: u32, - dwnumberofbytestransfered: u32, - lpoverlapped: *mut OVERLAPPED, - ), ->; -pub type LPPROC_THREAD_ATTRIBUTE_LIST = *mut core::ffi::c_void; -pub type LPPROGRESS_ROUTINE = Option< - unsafe extern "system" fn( - totalfilesize: i64, - totalbytestransferred: i64, - streamsize: i64, - streambytestransferred: i64, - dwstreamnumber: u32, - dwcallbackreason: LPPROGRESS_ROUTINE_CALLBACK_REASON, - hsourcefile: HANDLE, - hdestinationfile: HANDLE, - lpdata: *const core::ffi::c_void, - ) -> u32, ->; -pub type LPPROGRESS_ROUTINE_CALLBACK_REASON = u32; -pub type LPTHREAD_START_ROUTINE = - Option u32>; -pub type LPWSAOVERLAPPED_COMPLETION_ROUTINE = Option< - unsafe extern "system" fn( - dwerror: u32, - cbtransferred: u32, - lpoverlapped: *mut OVERLAPPED, - dwflags: u32, - ), ->; -#[repr(C)] -pub struct M128A { - pub Low: u64, - pub High: i64, -} -impl Copy for M128A {} -impl Clone for M128A { - fn clone(&self) -> Self { - *self - } -} -pub const MAXIMUM_REPARSE_DATA_BUFFER_SIZE: u32 = 16384u32; -pub const MAX_PATH: u32 = 260u32; -pub const MB_COMPOSITE: MULTI_BYTE_TO_WIDE_CHAR_FLAGS = 2u32; -pub const MB_ERR_INVALID_CHARS: MULTI_BYTE_TO_WIDE_CHAR_FLAGS = 8u32; -pub const MB_PRECOMPOSED: MULTI_BYTE_TO_WIDE_CHAR_FLAGS = 1u32; -pub const MB_USEGLYPHCHARS: MULTI_BYTE_TO_WIDE_CHAR_FLAGS = 4u32; -pub const MOVEFILE_COPY_ALLOWED: MOVE_FILE_FLAGS = 2u32; -pub const MOVEFILE_CREATE_HARDLINK: MOVE_FILE_FLAGS = 16u32; -pub const MOVEFILE_DELAY_UNTIL_REBOOT: MOVE_FILE_FLAGS = 4u32; -pub const MOVEFILE_FAIL_IF_NOT_TRACKABLE: MOVE_FILE_FLAGS = 32u32; -pub const MOVEFILE_REPLACE_EXISTING: MOVE_FILE_FLAGS = 1u32; -pub const MOVEFILE_WRITE_THROUGH: MOVE_FILE_FLAGS = 8u32; -pub type MOVE_FILE_FLAGS = u32; -pub const MSG_DONTROUTE: SEND_RECV_FLAGS = 4i32; -pub const MSG_OOB: SEND_RECV_FLAGS = 1i32; -pub const MSG_PEEK: SEND_RECV_FLAGS = 2i32; -pub const MSG_PUSH_IMMEDIATE: SEND_RECV_FLAGS = 32i32; -pub const MSG_WAITALL: SEND_RECV_FLAGS = 8i32; -pub type MULTI_BYTE_TO_WIDE_CHAR_FLAGS = u32; -pub const MaximumFileInfoByHandleClass: FILE_INFO_BY_HANDLE_CLASS = 25i32; -pub type NAMED_PIPE_MODE = u32; -pub const NORMAL_PRIORITY_CLASS: PROCESS_CREATION_FLAGS = 32u32; -pub const NO_ERROR: WIN32_ERROR = 0u32; -pub type NTCREATEFILE_CREATE_DISPOSITION = u32; -pub type NTCREATEFILE_CREATE_OPTIONS = u32; -pub type NTSTATUS = i32; -#[repr(C)] -pub struct OBJECT_ATTRIBUTES { - pub Length: u32, - pub RootDirectory: HANDLE, - pub ObjectName: *const UNICODE_STRING, - pub Attributes: u32, - pub SecurityDescriptor: *const core::ffi::c_void, - pub SecurityQualityOfService: *const core::ffi::c_void, -} -impl Copy for OBJECT_ATTRIBUTES {} -impl Clone for OBJECT_ATTRIBUTES { - fn clone(&self) -> Self { - *self - } -} -pub const OBJ_DONT_REPARSE: i32 = 4096i32; -pub const OPEN_ALWAYS: FILE_CREATION_DISPOSITION = 4u32; -pub const OPEN_EXISTING: FILE_CREATION_DISPOSITION = 3u32; -#[repr(C)] -pub struct OVERLAPPED { - pub Internal: usize, - pub InternalHigh: usize, - pub Anonymous: OVERLAPPED_0, - pub hEvent: HANDLE, -} -impl Copy for OVERLAPPED {} -impl Clone for OVERLAPPED { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -pub union OVERLAPPED_0 { - pub Anonymous: OVERLAPPED_0_0, - pub Pointer: *mut core::ffi::c_void, -} -impl Copy for OVERLAPPED_0 {} -impl Clone for OVERLAPPED_0 { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -pub struct OVERLAPPED_0_0 { - pub Offset: u32, - pub OffsetHigh: u32, -} -impl Copy for OVERLAPPED_0_0 {} -impl Clone for OVERLAPPED_0_0 { - fn clone(&self) -> Self { - *self - } -} -pub type PCSTR = *const u8; -pub type PCWSTR = *const u16; -pub type PIO_APC_ROUTINE = Option< - unsafe extern "system" fn( - apccontext: *mut core::ffi::c_void, - iostatusblock: *mut IO_STATUS_BLOCK, - reserved: u32, - ), ->; -pub const PIPE_ACCEPT_REMOTE_CLIENTS: NAMED_PIPE_MODE = 0u32; -pub const PIPE_ACCESS_DUPLEX: FILE_FLAGS_AND_ATTRIBUTES = 3u32; -pub const PIPE_ACCESS_INBOUND: FILE_FLAGS_AND_ATTRIBUTES = 1u32; -pub const PIPE_ACCESS_OUTBOUND: FILE_FLAGS_AND_ATTRIBUTES = 2u32; -pub const PIPE_CLIENT_END: NAMED_PIPE_MODE = 0u32; -pub const PIPE_NOWAIT: NAMED_PIPE_MODE = 1u32; -pub const PIPE_READMODE_BYTE: NAMED_PIPE_MODE = 0u32; -pub const PIPE_READMODE_MESSAGE: NAMED_PIPE_MODE = 2u32; -pub const PIPE_REJECT_REMOTE_CLIENTS: NAMED_PIPE_MODE = 8u32; -pub const PIPE_SERVER_END: NAMED_PIPE_MODE = 1u32; -pub const PIPE_TYPE_BYTE: NAMED_PIPE_MODE = 0u32; -pub const PIPE_TYPE_MESSAGE: NAMED_PIPE_MODE = 4u32; -pub const PIPE_WAIT: NAMED_PIPE_MODE = 0u32; -pub type PRIORITY_HINT = i32; -pub type PROCESSOR_ARCHITECTURE = u16; -pub type PROCESS_CREATION_FLAGS = u32; -#[repr(C)] -pub struct PROCESS_INFORMATION { - pub hProcess: HANDLE, - pub hThread: HANDLE, - pub dwProcessId: u32, - pub dwThreadId: u32, -} -impl Copy for PROCESS_INFORMATION {} -impl Clone for PROCESS_INFORMATION { - fn clone(&self) -> Self { - *self - } -} -pub const PROCESS_MODE_BACKGROUND_BEGIN: PROCESS_CREATION_FLAGS = 1048576u32; -pub const PROCESS_MODE_BACKGROUND_END: PROCESS_CREATION_FLAGS = 2097152u32; -pub const PROFILE_KERNEL: PROCESS_CREATION_FLAGS = 536870912u32; -pub const PROFILE_SERVER: PROCESS_CREATION_FLAGS = 1073741824u32; -pub const PROFILE_USER: PROCESS_CREATION_FLAGS = 268435456u32; -pub const PROGRESS_CONTINUE: u32 = 0u32; -pub type PSTR = *mut u8; -pub type PTIMERAPCROUTINE = Option< - unsafe extern "system" fn( - lpargtocompletionroutine: *const core::ffi::c_void, - dwtimerlowvalue: u32, - dwtimerhighvalue: u32, - ), ->; -pub type PWSTR = *mut u16; -pub const READ_CONTROL: FILE_ACCESS_RIGHTS = 131072u32; -pub const REALTIME_PRIORITY_CLASS: PROCESS_CREATION_FLAGS = 256u32; -pub const SD_BOTH: WINSOCK_SHUTDOWN_HOW = 2i32; -pub const SD_RECEIVE: WINSOCK_SHUTDOWN_HOW = 0i32; -pub const SD_SEND: WINSOCK_SHUTDOWN_HOW = 1i32; -pub const SECURITY_ANONYMOUS: FILE_FLAGS_AND_ATTRIBUTES = 0u32; -#[repr(C)] -pub struct SECURITY_ATTRIBUTES { - pub nLength: u32, - pub lpSecurityDescriptor: *mut core::ffi::c_void, - pub bInheritHandle: BOOL, -} -impl Copy for SECURITY_ATTRIBUTES {} -impl Clone for SECURITY_ATTRIBUTES { - fn clone(&self) -> Self { - *self - } -} -pub const SECURITY_CONTEXT_TRACKING: FILE_FLAGS_AND_ATTRIBUTES = 262144u32; -pub const SECURITY_DELEGATION: FILE_FLAGS_AND_ATTRIBUTES = 196608u32; -pub const SECURITY_EFFECTIVE_ONLY: FILE_FLAGS_AND_ATTRIBUTES = 524288u32; -pub const SECURITY_IDENTIFICATION: FILE_FLAGS_AND_ATTRIBUTES = 65536u32; -pub const SECURITY_IMPERSONATION: FILE_FLAGS_AND_ATTRIBUTES = 131072u32; -pub const SECURITY_SQOS_PRESENT: FILE_FLAGS_AND_ATTRIBUTES = 1048576u32; -pub const SECURITY_VALID_SQOS_FLAGS: FILE_FLAGS_AND_ATTRIBUTES = 2031616u32; -pub type SEND_RECV_FLAGS = i32; -pub type SET_FILE_POINTER_MOVE_METHOD = u32; -#[repr(C)] -pub struct SOCKADDR { - pub sa_family: ADDRESS_FAMILY, - pub sa_data: [i8; 14], -} -impl Copy for SOCKADDR {} -impl Clone for SOCKADDR { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -pub struct SOCKADDR_UN { - pub sun_family: ADDRESS_FAMILY, - pub sun_path: [i8; 108], -} -impl Copy for SOCKADDR_UN {} -impl Clone for SOCKADDR_UN { - fn clone(&self) -> Self { - *self - } -} -pub type SOCKET = usize; -pub const SOCKET_ERROR: i32 = -1i32; -pub const SOCK_DGRAM: WINSOCK_SOCKET_TYPE = 2i32; -pub const SOCK_RAW: WINSOCK_SOCKET_TYPE = 3i32; -pub const SOCK_RDM: WINSOCK_SOCKET_TYPE = 4i32; -pub const SOCK_SEQPACKET: WINSOCK_SOCKET_TYPE = 5i32; -pub const SOCK_STREAM: WINSOCK_SOCKET_TYPE = 1i32; -pub const SOL_SOCKET: i32 = 65535i32; -pub const SO_BROADCAST: i32 = 32i32; -pub const SO_ERROR: i32 = 4103i32; -pub const SO_LINGER: i32 = 128i32; -pub const SO_RCVTIMEO: i32 = 4102i32; -pub const SO_SNDTIMEO: i32 = 4101i32; -pub const SPECIFIC_RIGHTS_ALL: FILE_ACCESS_RIGHTS = 65535u32; -#[repr(C)] -pub struct SRWLOCK { - pub Ptr: *mut core::ffi::c_void, -} -impl Copy for SRWLOCK {} -impl Clone for SRWLOCK { - fn clone(&self) -> Self { - *self - } -} -pub const STACK_SIZE_PARAM_IS_A_RESERVATION: THREAD_CREATION_FLAGS = 65536u32; -pub const STANDARD_RIGHTS_ALL: FILE_ACCESS_RIGHTS = 2031616u32; -pub const STANDARD_RIGHTS_EXECUTE: FILE_ACCESS_RIGHTS = 131072u32; -pub const STANDARD_RIGHTS_READ: FILE_ACCESS_RIGHTS = 131072u32; -pub const STANDARD_RIGHTS_REQUIRED: FILE_ACCESS_RIGHTS = 983040u32; -pub const STANDARD_RIGHTS_WRITE: FILE_ACCESS_RIGHTS = 131072u32; -pub const STARTF_FORCEOFFFEEDBACK: STARTUPINFOW_FLAGS = 128u32; -pub const STARTF_FORCEONFEEDBACK: STARTUPINFOW_FLAGS = 64u32; -pub const STARTF_PREVENTPINNING: STARTUPINFOW_FLAGS = 8192u32; -pub const STARTF_RUNFULLSCREEN: STARTUPINFOW_FLAGS = 32u32; -pub const STARTF_TITLEISAPPID: STARTUPINFOW_FLAGS = 4096u32; -pub const STARTF_TITLEISLINKNAME: STARTUPINFOW_FLAGS = 2048u32; -pub const STARTF_UNTRUSTEDSOURCE: STARTUPINFOW_FLAGS = 32768u32; -pub const STARTF_USECOUNTCHARS: STARTUPINFOW_FLAGS = 8u32; -pub const STARTF_USEFILLATTRIBUTE: STARTUPINFOW_FLAGS = 16u32; -pub const STARTF_USEHOTKEY: STARTUPINFOW_FLAGS = 512u32; -pub const STARTF_USEPOSITION: STARTUPINFOW_FLAGS = 4u32; -pub const STARTF_USESHOWWINDOW: STARTUPINFOW_FLAGS = 1u32; -pub const STARTF_USESIZE: STARTUPINFOW_FLAGS = 2u32; -pub const STARTF_USESTDHANDLES: STARTUPINFOW_FLAGS = 256u32; -#[repr(C)] -pub struct STARTUPINFOEXW { - pub StartupInfo: STARTUPINFOW, - pub lpAttributeList: LPPROC_THREAD_ATTRIBUTE_LIST, -} -impl Copy for STARTUPINFOEXW {} -impl Clone for STARTUPINFOEXW { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -pub struct STARTUPINFOW { - pub cb: u32, - pub lpReserved: PWSTR, - pub lpDesktop: PWSTR, - pub lpTitle: PWSTR, - pub dwX: u32, - pub dwY: u32, - pub dwXSize: u32, - pub dwYSize: u32, - pub dwXCountChars: u32, - pub dwYCountChars: u32, - pub dwFillAttribute: u32, - pub dwFlags: STARTUPINFOW_FLAGS, - pub wShowWindow: u16, - pub cbReserved2: u16, - pub lpReserved2: *mut u8, - pub hStdInput: HANDLE, - pub hStdOutput: HANDLE, - pub hStdError: HANDLE, -} -impl Copy for STARTUPINFOW {} -impl Clone for STARTUPINFOW { - fn clone(&self) -> Self { - *self - } -} -pub type STARTUPINFOW_FLAGS = u32; -pub const STATUS_DELETE_PENDING: NTSTATUS = 0xC0000056_u32 as _; -pub const STATUS_END_OF_FILE: NTSTATUS = 0xC0000011_u32 as _; -pub const STATUS_INVALID_PARAMETER: NTSTATUS = 0xC000000D_u32 as _; -pub const STATUS_NOT_IMPLEMENTED: NTSTATUS = 0xC0000002_u32 as _; -pub const STATUS_PENDING: NTSTATUS = 0x103_u32 as _; -pub const STATUS_SUCCESS: NTSTATUS = 0x0_u32 as _; -pub const STD_ERROR_HANDLE: STD_HANDLE = 4294967284u32; -pub type STD_HANDLE = u32; -pub const STD_INPUT_HANDLE: STD_HANDLE = 4294967286u32; -pub const STD_OUTPUT_HANDLE: STD_HANDLE = 4294967285u32; -pub type SYMBOLIC_LINK_FLAGS = u32; -pub const SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE: SYMBOLIC_LINK_FLAGS = 2u32; -pub const SYMBOLIC_LINK_FLAG_DIRECTORY: SYMBOLIC_LINK_FLAGS = 1u32; -pub const SYMLINK_FLAG_RELATIVE: u32 = 1u32; -pub type SYNCHRONIZATION_ACCESS_RIGHTS = u32; -pub const SYNCHRONIZE: FILE_ACCESS_RIGHTS = 1048576u32; -#[repr(C)] -pub struct SYSTEM_INFO { - pub Anonymous: SYSTEM_INFO_0, - pub dwPageSize: u32, - pub lpMinimumApplicationAddress: *mut core::ffi::c_void, - pub lpMaximumApplicationAddress: *mut core::ffi::c_void, - pub dwActiveProcessorMask: usize, - pub dwNumberOfProcessors: u32, - pub dwProcessorType: u32, - pub dwAllocationGranularity: u32, - pub wProcessorLevel: u16, - pub wProcessorRevision: u16, -} -impl Copy for SYSTEM_INFO {} -impl Clone for SYSTEM_INFO { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -pub union SYSTEM_INFO_0 { - pub dwOemId: u32, - pub Anonymous: SYSTEM_INFO_0_0, -} -impl Copy for SYSTEM_INFO_0 {} -impl Clone for SYSTEM_INFO_0 { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -pub struct SYSTEM_INFO_0_0 { - pub wProcessorArchitecture: PROCESSOR_ARCHITECTURE, - pub wReserved: u16, -} -impl Copy for SYSTEM_INFO_0_0 {} -impl Clone for SYSTEM_INFO_0_0 { - fn clone(&self) -> Self { - *self - } -} -pub const TCP_NODELAY: i32 = 1i32; -pub const THREAD_CREATE_RUN_IMMEDIATELY: THREAD_CREATION_FLAGS = 0u32; -pub const THREAD_CREATE_SUSPENDED: THREAD_CREATION_FLAGS = 4u32; -pub type THREAD_CREATION_FLAGS = u32; -pub const TIMER_ALL_ACCESS: SYNCHRONIZATION_ACCESS_RIGHTS = 2031619u32; -pub const TIMER_MODIFY_STATE: SYNCHRONIZATION_ACCESS_RIGHTS = 2u32; -#[repr(C)] -pub struct TIMEVAL { - pub tv_sec: i32, - pub tv_usec: i32, -} -impl Copy for TIMEVAL {} -impl Clone for TIMEVAL { - fn clone(&self) -> Self { - *self - } -} -pub const TLS_OUT_OF_INDEXES: u32 = 4294967295u32; -pub type TOKEN_ACCESS_MASK = u32; -pub const TOKEN_ACCESS_PSEUDO_HANDLE: TOKEN_ACCESS_MASK = 24u32; -pub const TOKEN_ACCESS_PSEUDO_HANDLE_WIN8: TOKEN_ACCESS_MASK = 24u32; -pub const TOKEN_ACCESS_SYSTEM_SECURITY: TOKEN_ACCESS_MASK = 16777216u32; -pub const TOKEN_ADJUST_DEFAULT: TOKEN_ACCESS_MASK = 128u32; -pub const TOKEN_ADJUST_GROUPS: TOKEN_ACCESS_MASK = 64u32; -pub const TOKEN_ADJUST_PRIVILEGES: TOKEN_ACCESS_MASK = 32u32; -pub const TOKEN_ADJUST_SESSIONID: TOKEN_ACCESS_MASK = 256u32; -pub const TOKEN_ALL_ACCESS: TOKEN_ACCESS_MASK = 983551u32; -pub const TOKEN_ASSIGN_PRIMARY: TOKEN_ACCESS_MASK = 1u32; -pub const TOKEN_DELETE: TOKEN_ACCESS_MASK = 65536u32; -pub const TOKEN_DUPLICATE: TOKEN_ACCESS_MASK = 2u32; -pub const TOKEN_EXECUTE: TOKEN_ACCESS_MASK = 131072u32; -pub const TOKEN_IMPERSONATE: TOKEN_ACCESS_MASK = 4u32; -pub const TOKEN_QUERY: TOKEN_ACCESS_MASK = 8u32; -pub const TOKEN_QUERY_SOURCE: TOKEN_ACCESS_MASK = 16u32; -pub const TOKEN_READ: TOKEN_ACCESS_MASK = 131080u32; -pub const TOKEN_READ_CONTROL: TOKEN_ACCESS_MASK = 131072u32; -pub const TOKEN_TRUST_CONSTRAINT_MASK: TOKEN_ACCESS_MASK = 131096u32; -pub const TOKEN_WRITE: TOKEN_ACCESS_MASK = 131296u32; -pub const TOKEN_WRITE_DAC: TOKEN_ACCESS_MASK = 262144u32; -pub const TOKEN_WRITE_OWNER: TOKEN_ACCESS_MASK = 524288u32; -pub const TRUE: BOOL = 1i32; -pub const TRUNCATE_EXISTING: FILE_CREATION_DISPOSITION = 5u32; -#[repr(C)] -pub struct UNICODE_STRING { - pub Length: u16, - pub MaximumLength: u16, - pub Buffer: PWSTR, -} -impl Copy for UNICODE_STRING {} -impl Clone for UNICODE_STRING { - fn clone(&self) -> Self { - *self - } -} -pub const VOLUME_NAME_DOS: GETFINALPATHNAMEBYHANDLE_FLAGS = 0u32; -pub const VOLUME_NAME_GUID: GETFINALPATHNAMEBYHANDLE_FLAGS = 1u32; -pub const VOLUME_NAME_NONE: GETFINALPATHNAMEBYHANDLE_FLAGS = 4u32; -pub const WAIT_ABANDONED: WAIT_EVENT = 128u32; -pub const WAIT_ABANDONED_0: WAIT_EVENT = 128u32; -pub type WAIT_EVENT = u32; -pub const WAIT_FAILED: WAIT_EVENT = 4294967295u32; -pub const WAIT_IO_COMPLETION: WAIT_EVENT = 192u32; -pub const WAIT_OBJECT_0: WAIT_EVENT = 0u32; -pub const WAIT_TIMEOUT: WAIT_EVENT = 258u32; -pub const WC_ERR_INVALID_CHARS: u32 = 128u32; -pub type WIN32_ERROR = u32; -#[repr(C)] -pub struct WIN32_FIND_DATAW { - pub dwFileAttributes: u32, - pub ftCreationTime: FILETIME, - pub ftLastAccessTime: FILETIME, - pub ftLastWriteTime: FILETIME, - pub nFileSizeHigh: u32, - pub nFileSizeLow: u32, - pub dwReserved0: u32, - pub dwReserved1: u32, - pub cFileName: [u16; 260], - pub cAlternateFileName: [u16; 14], -} -impl Copy for WIN32_FIND_DATAW {} -impl Clone for WIN32_FIND_DATAW { - fn clone(&self) -> Self { - *self - } -} -pub type WINSOCK_SHUTDOWN_HOW = i32; -pub type WINSOCK_SOCKET_TYPE = i32; -pub const WRITE_DAC: FILE_ACCESS_RIGHTS = 262144u32; -pub const WRITE_OWNER: FILE_ACCESS_RIGHTS = 524288u32; -pub const WSABASEERR: WSA_ERROR = 10000i32; -#[repr(C)] -pub struct WSABUF { - pub len: u32, - pub buf: PSTR, -} -impl Copy for WSABUF {} -impl Clone for WSABUF { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -#[cfg(any(target_arch = "aarch64", target_arch = "arm64ec", target_arch = "x86_64"))] -pub struct WSADATA { - pub wVersion: u16, - pub wHighVersion: u16, - pub iMaxSockets: u16, - pub iMaxUdpDg: u16, - pub lpVendorInfo: PSTR, - pub szDescription: [i8; 257], - pub szSystemStatus: [i8; 129], -} -#[cfg(any(target_arch = "aarch64", target_arch = "arm64ec", target_arch = "x86_64"))] -impl Copy for WSADATA {} -#[cfg(any(target_arch = "aarch64", target_arch = "arm64ec", target_arch = "x86_64"))] -impl Clone for WSADATA { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -#[cfg(target_arch = "x86")] -pub struct WSADATA { - pub wVersion: u16, - pub wHighVersion: u16, - pub szDescription: [i8; 257], - pub szSystemStatus: [i8; 129], - pub iMaxSockets: u16, - pub iMaxUdpDg: u16, - pub lpVendorInfo: PSTR, -} -#[cfg(target_arch = "x86")] -impl Copy for WSADATA {} -#[cfg(target_arch = "x86")] -impl Clone for WSADATA { - fn clone(&self) -> Self { - *self - } -} -pub const WSAEACCES: WSA_ERROR = 10013i32; -pub const WSAEADDRINUSE: WSA_ERROR = 10048i32; -pub const WSAEADDRNOTAVAIL: WSA_ERROR = 10049i32; -pub const WSAEAFNOSUPPORT: WSA_ERROR = 10047i32; -pub const WSAEALREADY: WSA_ERROR = 10037i32; -pub const WSAEBADF: WSA_ERROR = 10009i32; -pub const WSAECANCELLED: WSA_ERROR = 10103i32; -pub const WSAECONNABORTED: WSA_ERROR = 10053i32; -pub const WSAECONNREFUSED: WSA_ERROR = 10061i32; -pub const WSAECONNRESET: WSA_ERROR = 10054i32; -pub const WSAEDESTADDRREQ: WSA_ERROR = 10039i32; -pub const WSAEDISCON: WSA_ERROR = 10101i32; -pub const WSAEDQUOT: WSA_ERROR = 10069i32; -pub const WSAEFAULT: WSA_ERROR = 10014i32; -pub const WSAEHOSTDOWN: WSA_ERROR = 10064i32; -pub const WSAEHOSTUNREACH: WSA_ERROR = 10065i32; -pub const WSAEINPROGRESS: WSA_ERROR = 10036i32; -pub const WSAEINTR: WSA_ERROR = 10004i32; -pub const WSAEINVAL: WSA_ERROR = 10022i32; -pub const WSAEINVALIDPROCTABLE: WSA_ERROR = 10104i32; -pub const WSAEINVALIDPROVIDER: WSA_ERROR = 10105i32; -pub const WSAEISCONN: WSA_ERROR = 10056i32; -pub const WSAELOOP: WSA_ERROR = 10062i32; -pub const WSAEMFILE: WSA_ERROR = 10024i32; -pub const WSAEMSGSIZE: WSA_ERROR = 10040i32; -pub const WSAENAMETOOLONG: WSA_ERROR = 10063i32; -pub const WSAENETDOWN: WSA_ERROR = 10050i32; -pub const WSAENETRESET: WSA_ERROR = 10052i32; -pub const WSAENETUNREACH: WSA_ERROR = 10051i32; -pub const WSAENOBUFS: WSA_ERROR = 10055i32; -pub const WSAENOMORE: WSA_ERROR = 10102i32; -pub const WSAENOPROTOOPT: WSA_ERROR = 10042i32; -pub const WSAENOTCONN: WSA_ERROR = 10057i32; -pub const WSAENOTEMPTY: WSA_ERROR = 10066i32; -pub const WSAENOTSOCK: WSA_ERROR = 10038i32; -pub const WSAEOPNOTSUPP: WSA_ERROR = 10045i32; -pub const WSAEPFNOSUPPORT: WSA_ERROR = 10046i32; -pub const WSAEPROCLIM: WSA_ERROR = 10067i32; -pub const WSAEPROTONOSUPPORT: WSA_ERROR = 10043i32; -pub const WSAEPROTOTYPE: WSA_ERROR = 10041i32; -pub const WSAEPROVIDERFAILEDINIT: WSA_ERROR = 10106i32; -pub const WSAEREFUSED: WSA_ERROR = 10112i32; -pub const WSAEREMOTE: WSA_ERROR = 10071i32; -pub const WSAESHUTDOWN: WSA_ERROR = 10058i32; -pub const WSAESOCKTNOSUPPORT: WSA_ERROR = 10044i32; -pub const WSAESTALE: WSA_ERROR = 10070i32; -pub const WSAETIMEDOUT: WSA_ERROR = 10060i32; -pub const WSAETOOMANYREFS: WSA_ERROR = 10059i32; -pub const WSAEUSERS: WSA_ERROR = 10068i32; -pub const WSAEWOULDBLOCK: WSA_ERROR = 10035i32; -pub const WSAHOST_NOT_FOUND: WSA_ERROR = 11001i32; -pub const WSANOTINITIALISED: WSA_ERROR = 10093i32; -pub const WSANO_DATA: WSA_ERROR = 11004i32; -pub const WSANO_RECOVERY: WSA_ERROR = 11003i32; -#[repr(C)] -pub struct WSAPROTOCOLCHAIN { - pub ChainLen: i32, - pub ChainEntries: [u32; 7], -} -impl Copy for WSAPROTOCOLCHAIN {} -impl Clone for WSAPROTOCOLCHAIN { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -pub struct WSAPROTOCOL_INFOW { - pub dwServiceFlags1: u32, - pub dwServiceFlags2: u32, - pub dwServiceFlags3: u32, - pub dwServiceFlags4: u32, - pub dwProviderFlags: u32, - pub ProviderId: GUID, - pub dwCatalogEntryId: u32, - pub ProtocolChain: WSAPROTOCOLCHAIN, - pub iVersion: i32, - pub iAddressFamily: i32, - pub iMaxSockAddr: i32, - pub iMinSockAddr: i32, - pub iSocketType: i32, - pub iProtocol: i32, - pub iProtocolMaxOffset: i32, - pub iNetworkByteOrder: i32, - pub iSecurityScheme: i32, - pub dwMessageSize: u32, - pub dwProviderReserved: u32, - pub szProtocol: [u16; 256], -} -impl Copy for WSAPROTOCOL_INFOW {} -impl Clone for WSAPROTOCOL_INFOW { - fn clone(&self) -> Self { - *self - } -} -pub const WSASERVICE_NOT_FOUND: WSA_ERROR = 10108i32; -pub const WSASYSCALLFAILURE: WSA_ERROR = 10107i32; -pub const WSASYSNOTREADY: WSA_ERROR = 10091i32; -pub const WSATRY_AGAIN: WSA_ERROR = 11002i32; -pub const WSATYPE_NOT_FOUND: WSA_ERROR = 10109i32; -pub const WSAVERNOTSUPPORTED: WSA_ERROR = 10092i32; -pub type WSA_ERROR = i32; -pub const WSA_E_CANCELLED: WSA_ERROR = 10111i32; -pub const WSA_E_NO_MORE: WSA_ERROR = 10110i32; -pub const WSA_FLAG_NO_HANDLE_INHERIT: u32 = 128u32; -pub const WSA_FLAG_OVERLAPPED: u32 = 1u32; -pub const WSA_INVALID_HANDLE: WSA_ERROR = 6i32; -pub const WSA_INVALID_PARAMETER: WSA_ERROR = 87i32; -pub const WSA_IO_INCOMPLETE: WSA_ERROR = 996i32; -pub const WSA_IO_PENDING: WSA_ERROR = 997i32; -pub const WSA_IPSEC_NAME_POLICY_ERROR: WSA_ERROR = 11033i32; -pub const WSA_NOT_ENOUGH_MEMORY: WSA_ERROR = 8i32; -pub const WSA_OPERATION_ABORTED: WSA_ERROR = 995i32; -pub const WSA_QOS_ADMISSION_FAILURE: WSA_ERROR = 11010i32; -pub const WSA_QOS_BAD_OBJECT: WSA_ERROR = 11013i32; -pub const WSA_QOS_BAD_STYLE: WSA_ERROR = 11012i32; -pub const WSA_QOS_EFILTERCOUNT: WSA_ERROR = 11021i32; -pub const WSA_QOS_EFILTERSTYLE: WSA_ERROR = 11019i32; -pub const WSA_QOS_EFILTERTYPE: WSA_ERROR = 11020i32; -pub const WSA_QOS_EFLOWCOUNT: WSA_ERROR = 11023i32; -pub const WSA_QOS_EFLOWDESC: WSA_ERROR = 11026i32; -pub const WSA_QOS_EFLOWSPEC: WSA_ERROR = 11017i32; -pub const WSA_QOS_EOBJLENGTH: WSA_ERROR = 11022i32; -pub const WSA_QOS_EPOLICYOBJ: WSA_ERROR = 11025i32; -pub const WSA_QOS_EPROVSPECBUF: WSA_ERROR = 11018i32; -pub const WSA_QOS_EPSFILTERSPEC: WSA_ERROR = 11028i32; -pub const WSA_QOS_EPSFLOWSPEC: WSA_ERROR = 11027i32; -pub const WSA_QOS_ESDMODEOBJ: WSA_ERROR = 11029i32; -pub const WSA_QOS_ESERVICETYPE: WSA_ERROR = 11016i32; -pub const WSA_QOS_ESHAPERATEOBJ: WSA_ERROR = 11030i32; -pub const WSA_QOS_EUNKOWNPSOBJ: WSA_ERROR = 11024i32; -pub const WSA_QOS_GENERIC_ERROR: WSA_ERROR = 11015i32; -pub const WSA_QOS_NO_RECEIVERS: WSA_ERROR = 11008i32; -pub const WSA_QOS_NO_SENDERS: WSA_ERROR = 11007i32; -pub const WSA_QOS_POLICY_FAILURE: WSA_ERROR = 11011i32; -pub const WSA_QOS_RECEIVERS: WSA_ERROR = 11005i32; -pub const WSA_QOS_REQUEST_CONFIRMED: WSA_ERROR = 11009i32; -pub const WSA_QOS_RESERVED_PETYPE: WSA_ERROR = 11031i32; -pub const WSA_QOS_SENDERS: WSA_ERROR = 11006i32; -pub const WSA_QOS_TRAFFIC_CTRL_ERROR: WSA_ERROR = 11014i32; -pub const WSA_SECURE_HOST_NOT_FOUND: WSA_ERROR = 11032i32; -pub const WSA_WAIT_EVENT_0: WSA_ERROR = 0i32; -pub const WSA_WAIT_IO_COMPLETION: WSA_ERROR = 192i32; -#[repr(C)] -#[cfg(any(target_arch = "aarch64", target_arch = "arm64ec", target_arch = "x86_64"))] -pub struct XSAVE_FORMAT { - pub ControlWord: u16, - pub StatusWord: u16, - pub TagWord: u8, - pub Reserved1: u8, - pub ErrorOpcode: u16, - pub ErrorOffset: u32, - pub ErrorSelector: u16, - pub Reserved2: u16, - pub DataOffset: u32, - pub DataSelector: u16, - pub Reserved3: u16, - pub MxCsr: u32, - pub MxCsr_Mask: u32, - pub FloatRegisters: [M128A; 8], - pub XmmRegisters: [M128A; 16], - pub Reserved4: [u8; 96], -} -#[cfg(any(target_arch = "aarch64", target_arch = "arm64ec", target_arch = "x86_64"))] -impl Copy for XSAVE_FORMAT {} -#[cfg(any(target_arch = "aarch64", target_arch = "arm64ec", target_arch = "x86_64"))] -impl Clone for XSAVE_FORMAT { - fn clone(&self) -> Self { - *self - } -} -#[repr(C)] -#[cfg(target_arch = "x86")] -pub struct XSAVE_FORMAT { - pub ControlWord: u16, - pub StatusWord: u16, - pub TagWord: u8, - pub Reserved1: u8, - pub ErrorOpcode: u16, - pub ErrorOffset: u32, - pub ErrorSelector: u16, - pub Reserved2: u16, - pub DataOffset: u32, - pub DataSelector: u16, - pub Reserved3: u16, - pub MxCsr: u32, - pub MxCsr_Mask: u32, - pub FloatRegisters: [M128A; 8], - pub XmmRegisters: [M128A; 8], - pub Reserved4: [u8; 224], -} -#[cfg(target_arch = "x86")] -impl Copy for XSAVE_FORMAT {} -#[cfg(target_arch = "x86")] -impl Clone for XSAVE_FORMAT { - fn clone(&self) -> Self { - *self - } -} -// ignore-tidy-filelength diff --git a/library/std/src/sys/pal/windows/compat.rs b/library/std/src/sys/pal/windows/compat.rs deleted file mode 100644 index f5d57a28db69a..0000000000000 --- a/library/std/src/sys/pal/windows/compat.rs +++ /dev/null @@ -1,253 +0,0 @@ -//! A "compatibility layer" for supporting older versions of Windows -//! -//! The standard library uses some Windows API functions that are not present -//! on older versions of Windows. (Note that the oldest version of Windows -//! that Rust supports is Windows 7 (client) and Windows Server 2008 (server).) -//! This module implements a form of delayed DLL import binding, using -//! `GetModuleHandle` and `GetProcAddress` to look up DLL entry points at -//! runtime. -//! -//! This is implemented simply by storing a function pointer in an atomic. -//! Loading and calling this function will have little or no overhead -//! compared with calling any other dynamically imported function. -//! -//! The stored function pointer starts out as an importer function which will -//! swap itself with the real function when it's called for the first time. If -//! the real function can't be imported then a fallback function is used in its -//! place. While this is low cost for the happy path (where the function is -//! already loaded) it does mean there's some overhead the first time the -//! function is called. In the worst case, multiple threads may all end up -//! importing the same function unnecessarily. - -use crate::ffi::{c_void, CStr}; -use crate::ptr::NonNull; -use crate::sys::c; - -// This uses a static initializer to preload some imported functions. -// The CRT (C runtime) executes static initializers before `main` -// is called (for binaries) and before `DllMain` is called (for DLLs). -// -// It works by contributing a global symbol to the `.CRT$XCT` section. -// The linker builds a table of all static initializer functions. -// The CRT startup code then iterates that table, calling each -// initializer function. -// -// NOTE: User code should instead use .CRT$XCU to reliably run after std's initializer. -// If you're reading this and would like a guarantee here, please -// file an issue for discussion; currently we don't guarantee any functionality -// before main. -// See https://docs.microsoft.com/en-us/cpp/c-runtime-library/crt-initialization?view=msvc-170 -#[cfg(target_vendor = "win7")] -#[used] -#[link_section = ".CRT$XCT"] -static INIT_TABLE_ENTRY: unsafe extern "C" fn() = init; - -/// Preload some imported functions. -/// -/// Note that any functions included here will be unconditionally loaded in -/// the final binary, regardless of whether or not they're actually used. -/// -/// Therefore, this should be limited to `compat_fn_optional` functions which -/// must be preloaded or any functions where lazier loading demonstrates a -/// negative performance impact in practical situations. -/// -/// Currently we only preload `WaitOnAddress` and `WakeByAddressSingle`. -#[cfg(target_vendor = "win7")] -unsafe extern "C" fn init() { - // In an exe this code is executed before main() so is single threaded. - // In a DLL the system's loader lock will be held thereby synchronizing - // access. So the same best practices apply here as they do to running in DllMain: - // https://docs.microsoft.com/en-us/windows/win32/dlls/dynamic-link-library-best-practices - // - // DO NOT do anything interesting or complicated in this function! DO NOT call - // any Rust functions or CRT functions if those functions touch any global state, - // because this function runs during global initialization. For example, DO NOT - // do any dynamic allocation, don't call LoadLibrary, etc. - - // Attempt to preload the synch functions. - load_synch_functions(); -} - -/// Helper macro for creating CStrs from literals and symbol names. -macro_rules! ansi_str { - (sym $ident:ident) => {{ crate::sys::compat::const_cstr_from_bytes(concat!(stringify!($ident), "\0").as_bytes()) }}; - ($lit:literal) => {{ crate::sys::compat::const_cstr_from_bytes(concat!($lit, "\0").as_bytes()) }}; -} - -/// Creates a C string wrapper from a byte slice, in a constant context. -/// -/// This is a utility function used by the [`ansi_str`] macro. -/// -/// # Panics -/// -/// Panics if the slice is not null terminated or contains nulls, except as the last item -pub(crate) const fn const_cstr_from_bytes(bytes: &'static [u8]) -> &'static CStr { - if !matches!(bytes.last(), Some(&0)) { - panic!("A CStr must be null terminated"); - } - let mut i = 0; - // At this point `len()` is at least 1. - while i < bytes.len() - 1 { - if bytes[i] == 0 { - panic!("A CStr must not have interior nulls") - } - i += 1; - } - // SAFETY: The safety is ensured by the above checks. - unsafe { crate::ffi::CStr::from_bytes_with_nul_unchecked(bytes) } -} - -/// Represents a loaded module. -/// -/// Note that the modules std depends on must not be unloaded. -/// Therefore a `Module` is always valid for the lifetime of std. -#[derive(Copy, Clone)] -pub(in crate::sys) struct Module(NonNull); -impl Module { - /// Try to get a handle to a loaded module. - /// - /// # SAFETY - /// - /// This should only be use for modules that exist for the lifetime of std - /// (e.g. kernel32 and ntdll). - pub unsafe fn new(name: &CStr) -> Option { - // SAFETY: A CStr is always null terminated. - let module = c::GetModuleHandleA(name.as_ptr().cast::()); - NonNull::new(module).map(Self) - } - - // Try to get the address of a function. - pub fn proc_address(self, name: &CStr) -> Option> { - unsafe { - // SAFETY: - // `self.0` will always be a valid module. - // A CStr is always null terminated. - let proc = c::GetProcAddress(self.0.as_ptr(), name.as_ptr().cast::()); - // SAFETY: `GetProcAddress` returns None on null. - proc.map(|p| NonNull::new_unchecked(p as *mut c_void)) - } - } -} - -/// Load a function or use a fallback implementation if that fails. -macro_rules! compat_fn_with_fallback { - (pub static $module:ident: &CStr = $name:expr; $( - $(#[$meta:meta])* - $vis:vis fn $symbol:ident($($argname:ident: $argtype:ty),*) -> $rettype:ty $fallback_body:block - )*) => ( - pub static $module: &CStr = $name; - $( - $(#[$meta])* - pub mod $symbol { - #[allow(unused_imports)] - use super::*; - use crate::mem; - use crate::ffi::CStr; - use crate::sync::atomic::{AtomicPtr, Ordering}; - use crate::sys::compat::Module; - - type F = unsafe extern "system" fn($($argtype),*) -> $rettype; - - /// `PTR` contains a function pointer to one of three functions. - /// It starts with the `load` function. - /// When that is called it attempts to load the requested symbol. - /// If it succeeds, `PTR` is set to the address of that symbol. - /// If it fails, then `PTR` is set to `fallback`. - static PTR: AtomicPtr = AtomicPtr::new(load as *mut _); - - unsafe extern "system" fn load($($argname: $argtype),*) -> $rettype { - let func = load_from_module(Module::new($module)); - func($($argname),*) - } - - fn load_from_module(module: Option) -> F { - unsafe { - static SYMBOL_NAME: &CStr = ansi_str!(sym $symbol); - if let Some(f) = module.and_then(|m| m.proc_address(SYMBOL_NAME)) { - PTR.store(f.as_ptr(), Ordering::Relaxed); - mem::transmute(f) - } else { - PTR.store(fallback as *mut _, Ordering::Relaxed); - fallback - } - } - } - - #[allow(unused_variables)] - unsafe extern "system" fn fallback($($argname: $argtype),*) -> $rettype { - $fallback_body - } - - #[inline(always)] - pub unsafe fn call($($argname: $argtype),*) -> $rettype { - let func: F = mem::transmute(PTR.load(Ordering::Relaxed)); - func($($argname),*) - } - } - #[allow(unused)] - $(#[$meta])* - $vis use $symbol::call as $symbol; - )*) -} - -/// Optionally loaded functions. -/// -/// Actual loading of the function defers to $load_functions. -#[cfg(target_vendor = "win7")] -macro_rules! compat_fn_optional { - ($load_functions:expr; - $( - $(#[$meta:meta])* - $vis:vis fn $symbol:ident($($argname:ident: $argtype:ty),*) $(-> $rettype:ty)?; - )+) => ( - $( - pub mod $symbol { - #[allow(unused_imports)] - use super::*; - use crate::ffi::c_void; - use crate::mem; - use crate::ptr::{self, NonNull}; - use crate::sync::atomic::{AtomicPtr, Ordering}; - - pub(in crate::sys) static PTR: AtomicPtr = AtomicPtr::new(ptr::null_mut()); - - type F = unsafe extern "system" fn($($argtype),*) $(-> $rettype)?; - - #[inline(always)] - pub fn option() -> Option { - // Miri does not understand the way we do preloading - // therefore load the function here instead. - #[cfg(miri)] $load_functions; - NonNull::new(PTR.load(Ordering::Relaxed)).map(|f| unsafe { mem::transmute(f) }) - } - } - #[inline] - pub unsafe extern "system" fn $symbol($($argname: $argtype),*) $(-> $rettype)? { - $symbol::option().unwrap()($($argname),*) - } - )+ - ) -} - -/// Load all needed functions from "api-ms-win-core-synch-l1-2-0". -#[cfg(target_vendor = "win7")] -pub(super) fn load_synch_functions() { - fn try_load() -> Option<()> { - use crate::sync::atomic::Ordering; - const MODULE_NAME: &CStr = c"api-ms-win-core-synch-l1-2-0"; - const WAIT_ON_ADDRESS: &CStr = c"WaitOnAddress"; - const WAKE_BY_ADDRESS_SINGLE: &CStr = c"WakeByAddressSingle"; - - // Try loading the library and all the required functions. - // If any step fails, then they all fail. - let library = unsafe { Module::new(MODULE_NAME) }?; - let wait_on_address = library.proc_address(WAIT_ON_ADDRESS)?; - let wake_by_address_single = library.proc_address(WAKE_BY_ADDRESS_SINGLE)?; - - c::WaitOnAddress::PTR.store(wait_on_address.as_ptr(), Ordering::Relaxed); - c::WakeByAddressSingle::PTR.store(wake_by_address_single.as_ptr(), Ordering::Relaxed); - Some(()) - } - - try_load(); -} diff --git a/library/std/src/sys/pal/windows/env.rs b/library/std/src/sys/pal/windows/env.rs deleted file mode 100644 index f0a99d6200cac..0000000000000 --- a/library/std/src/sys/pal/windows/env.rs +++ /dev/null @@ -1,9 +0,0 @@ -pub mod os { - pub const FAMILY: &str = "windows"; - pub const OS: &str = "windows"; - pub const DLL_PREFIX: &str = ""; - pub const DLL_SUFFIX: &str = ".dll"; - pub const DLL_EXTENSION: &str = "dll"; - pub const EXE_SUFFIX: &str = ".exe"; - pub const EXE_EXTENSION: &str = "exe"; -} diff --git a/library/std/src/sys/pal/windows/fs.rs b/library/std/src/sys/pal/windows/fs.rs deleted file mode 100644 index e92c5e80eac9c..0000000000000 --- a/library/std/src/sys/pal/windows/fs.rs +++ /dev/null @@ -1,1566 +0,0 @@ -use core::ptr::addr_of; - -use crate::os::windows::prelude::*; - -use crate::borrow::Cow; -use crate::ffi::{c_void, OsStr, OsString}; -use crate::fmt; -use crate::io::{self, BorrowedCursor, Error, IoSlice, IoSliceMut, SeekFrom}; -use crate::mem::{self, MaybeUninit}; -use crate::os::windows::io::{AsHandle, BorrowedHandle}; -use crate::path::{Path, PathBuf}; -use crate::ptr; -use crate::slice; -use crate::sync::Arc; -use crate::sys::handle::Handle; -use crate::sys::time::SystemTime; -use crate::sys::{c, cvt, Align8}; -use crate::sys_common::{AsInner, FromInner, IntoInner}; -use crate::thread; - -use super::{api, to_u16s, IoResult}; -use crate::sys::path::maybe_verbatim; - -pub struct File { - handle: Handle, -} - -#[derive(Clone)] -pub struct FileAttr { - attributes: c::DWORD, - creation_time: c::FILETIME, - last_access_time: c::FILETIME, - last_write_time: c::FILETIME, - file_size: u64, - reparse_tag: c::DWORD, - volume_serial_number: Option, - number_of_links: Option, - file_index: Option, -} - -#[derive(Copy, Clone, PartialEq, Eq, Hash, Debug)] -pub struct FileType { - attributes: c::DWORD, - reparse_tag: c::DWORD, -} - -pub struct ReadDir { - handle: FindNextFileHandle, - root: Arc, - first: Option, -} - -struct FindNextFileHandle(c::HANDLE); - -unsafe impl Send for FindNextFileHandle {} -unsafe impl Sync for FindNextFileHandle {} - -pub struct DirEntry { - root: Arc, - data: c::WIN32_FIND_DATAW, -} - -unsafe impl Send for OpenOptions {} -unsafe impl Sync for OpenOptions {} - -#[derive(Clone, Debug)] -pub struct OpenOptions { - // generic - read: bool, - write: bool, - append: bool, - truncate: bool, - create: bool, - create_new: bool, - // system-specific - custom_flags: u32, - access_mode: Option, - attributes: c::DWORD, - share_mode: c::DWORD, - security_qos_flags: c::DWORD, - security_attributes: c::LPSECURITY_ATTRIBUTES, -} - -#[derive(Clone, PartialEq, Eq, Debug)] -pub struct FilePermissions { - attrs: c::DWORD, -} - -#[derive(Copy, Clone, Debug, Default)] -pub struct FileTimes { - accessed: Option, - modified: Option, - created: Option, -} - -impl fmt::Debug for c::FILETIME { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let time = ((self.dwHighDateTime as u64) << 32) | self.dwLowDateTime as u64; - f.debug_tuple("FILETIME").field(&time).finish() - } -} - -#[derive(Debug)] -pub struct DirBuilder; - -impl fmt::Debug for ReadDir { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - // This will only be called from std::fs::ReadDir, which will add a "ReadDir()" frame. - // Thus the result will be e g 'ReadDir("C:\")' - fmt::Debug::fmt(&*self.root, f) - } -} - -impl Iterator for ReadDir { - type Item = io::Result; - fn next(&mut self) -> Option> { - if self.handle.0 == c::INVALID_HANDLE_VALUE { - // This iterator was initialized with an `INVALID_HANDLE_VALUE` as its handle. - // Simply return `None` because this is only the case when `FindFirstFileW` in - // the construction of this iterator returns `ERROR_FILE_NOT_FOUND` which means - // no matchhing files can be found. - return None; - } - if let Some(first) = self.first.take() { - if let Some(e) = DirEntry::new(&self.root, &first) { - return Some(Ok(e)); - } - } - unsafe { - let mut wfd = mem::zeroed(); - loop { - if c::FindNextFileW(self.handle.0, &mut wfd) == 0 { - if api::get_last_error().code == c::ERROR_NO_MORE_FILES { - return None; - } else { - return Some(Err(Error::last_os_error())); - } - } - if let Some(e) = DirEntry::new(&self.root, &wfd) { - return Some(Ok(e)); - } - } - } - } -} - -impl Drop for FindNextFileHandle { - fn drop(&mut self) { - let r = unsafe { c::FindClose(self.0) }; - debug_assert!(r != 0); - } -} - -impl DirEntry { - fn new(root: &Arc, wfd: &c::WIN32_FIND_DATAW) -> Option { - match &wfd.cFileName[0..3] { - // check for '.' and '..' - &[46, 0, ..] | &[46, 46, 0, ..] => return None, - _ => {} - } - - Some(DirEntry { root: root.clone(), data: *wfd }) - } - - pub fn path(&self) -> PathBuf { - self.root.join(self.file_name()) - } - - pub fn file_name(&self) -> OsString { - let filename = super::truncate_utf16_at_nul(&self.data.cFileName); - OsString::from_wide(filename) - } - - pub fn file_type(&self) -> io::Result { - Ok(FileType::new( - self.data.dwFileAttributes, - /* reparse_tag = */ self.data.dwReserved0, - )) - } - - pub fn metadata(&self) -> io::Result { - Ok(self.data.into()) - } -} - -impl OpenOptions { - pub fn new() -> OpenOptions { - OpenOptions { - // generic - read: false, - write: false, - append: false, - truncate: false, - create: false, - create_new: false, - // system-specific - custom_flags: 0, - access_mode: None, - share_mode: c::FILE_SHARE_READ | c::FILE_SHARE_WRITE | c::FILE_SHARE_DELETE, - attributes: 0, - security_qos_flags: 0, - security_attributes: ptr::null_mut(), - } - } - - pub fn read(&mut self, read: bool) { - self.read = read; - } - pub fn write(&mut self, write: bool) { - self.write = write; - } - pub fn append(&mut self, append: bool) { - self.append = append; - } - pub fn truncate(&mut self, truncate: bool) { - self.truncate = truncate; - } - pub fn create(&mut self, create: bool) { - self.create = create; - } - pub fn create_new(&mut self, create_new: bool) { - self.create_new = create_new; - } - - pub fn custom_flags(&mut self, flags: u32) { - self.custom_flags = flags; - } - pub fn access_mode(&mut self, access_mode: u32) { - self.access_mode = Some(access_mode); - } - pub fn share_mode(&mut self, share_mode: u32) { - self.share_mode = share_mode; - } - pub fn attributes(&mut self, attrs: u32) { - self.attributes = attrs; - } - pub fn security_qos_flags(&mut self, flags: u32) { - // We have to set `SECURITY_SQOS_PRESENT` here, because one of the valid flags we can - // receive is `SECURITY_ANONYMOUS = 0x0`, which we can't check for later on. - self.security_qos_flags = flags | c::SECURITY_SQOS_PRESENT; - } - pub fn security_attributes(&mut self, attrs: c::LPSECURITY_ATTRIBUTES) { - self.security_attributes = attrs; - } - - fn get_access_mode(&self) -> io::Result { - const ERROR_INVALID_PARAMETER: i32 = 87; - - match (self.read, self.write, self.append, self.access_mode) { - (.., Some(mode)) => Ok(mode), - (true, false, false, None) => Ok(c::GENERIC_READ), - (false, true, false, None) => Ok(c::GENERIC_WRITE), - (true, true, false, None) => Ok(c::GENERIC_READ | c::GENERIC_WRITE), - (false, _, true, None) => Ok(c::FILE_GENERIC_WRITE & !c::FILE_WRITE_DATA), - (true, _, true, None) => { - Ok(c::GENERIC_READ | (c::FILE_GENERIC_WRITE & !c::FILE_WRITE_DATA)) - } - (false, false, false, None) => Err(Error::from_raw_os_error(ERROR_INVALID_PARAMETER)), - } - } - - fn get_creation_mode(&self) -> io::Result { - const ERROR_INVALID_PARAMETER: i32 = 87; - - match (self.write, self.append) { - (true, false) => {} - (false, false) => { - if self.truncate || self.create || self.create_new { - return Err(Error::from_raw_os_error(ERROR_INVALID_PARAMETER)); - } - } - (_, true) => { - if self.truncate && !self.create_new { - return Err(Error::from_raw_os_error(ERROR_INVALID_PARAMETER)); - } - } - } - - Ok(match (self.create, self.truncate, self.create_new) { - (false, false, false) => c::OPEN_EXISTING, - (true, false, false) => c::OPEN_ALWAYS, - (false, true, false) => c::TRUNCATE_EXISTING, - // `CREATE_ALWAYS` has weird semantics so we emulate it using - // `OPEN_ALWAYS` and a manual truncation step. See #115745. - (true, true, false) => c::OPEN_ALWAYS, - (_, _, true) => c::CREATE_NEW, - }) - } - - fn get_flags_and_attributes(&self) -> c::DWORD { - self.custom_flags - | self.attributes - | self.security_qos_flags - | if self.create_new { c::FILE_FLAG_OPEN_REPARSE_POINT } else { 0 } - } -} - -impl File { - pub fn open(path: &Path, opts: &OpenOptions) -> io::Result { - let path = maybe_verbatim(path)?; - let creation = opts.get_creation_mode()?; - let handle = unsafe { - c::CreateFileW( - path.as_ptr(), - opts.get_access_mode()?, - opts.share_mode, - opts.security_attributes, - creation, - opts.get_flags_and_attributes(), - ptr::null_mut(), - ) - }; - let handle = unsafe { HandleOrInvalid::from_raw_handle(handle) }; - if let Ok(handle) = OwnedHandle::try_from(handle) { - // Manual truncation. See #115745. - if opts.truncate - && creation == c::OPEN_ALWAYS - && unsafe { c::GetLastError() } == c::ERROR_ALREADY_EXISTS - { - unsafe { - // This originally used `FileAllocationInfo` instead of - // `FileEndOfFileInfo` but that wasn't supported by WINE. - // It's arguable which fits the semantics of `OpenOptions` - // better so let's just use the more widely supported method. - let eof = c::FILE_END_OF_FILE_INFO { EndOfFile: 0 }; - let result = c::SetFileInformationByHandle( - handle.as_raw_handle(), - c::FileEndOfFileInfo, - ptr::addr_of!(eof).cast::(), - mem::size_of::() as u32, - ); - if result == 0 { - return Err(io::Error::last_os_error()); - } - } - } - Ok(File { handle: Handle::from_inner(handle) }) - } else { - Err(Error::last_os_error()) - } - } - - pub fn fsync(&self) -> io::Result<()> { - cvt(unsafe { c::FlushFileBuffers(self.handle.as_raw_handle()) })?; - Ok(()) - } - - pub fn datasync(&self) -> io::Result<()> { - self.fsync() - } - - pub fn truncate(&self, size: u64) -> io::Result<()> { - let info = c::FILE_END_OF_FILE_INFO { EndOfFile: size as i64 }; - api::set_file_information_by_handle(self.handle.as_raw_handle(), &info).io_result() - } - - #[cfg(not(target_vendor = "uwp"))] - pub fn file_attr(&self) -> io::Result { - unsafe { - let mut info: c::BY_HANDLE_FILE_INFORMATION = mem::zeroed(); - cvt(c::GetFileInformationByHandle(self.handle.as_raw_handle(), &mut info))?; - let mut reparse_tag = 0; - if info.dwFileAttributes & c::FILE_ATTRIBUTE_REPARSE_POINT != 0 { - let mut attr_tag: c::FILE_ATTRIBUTE_TAG_INFO = mem::zeroed(); - cvt(c::GetFileInformationByHandleEx( - self.handle.as_raw_handle(), - c::FileAttributeTagInfo, - ptr::addr_of_mut!(attr_tag).cast(), - mem::size_of::().try_into().unwrap(), - ))?; - if attr_tag.FileAttributes & c::FILE_ATTRIBUTE_REPARSE_POINT != 0 { - reparse_tag = attr_tag.ReparseTag; - } - } - Ok(FileAttr { - attributes: info.dwFileAttributes, - creation_time: info.ftCreationTime, - last_access_time: info.ftLastAccessTime, - last_write_time: info.ftLastWriteTime, - file_size: (info.nFileSizeLow as u64) | ((info.nFileSizeHigh as u64) << 32), - reparse_tag, - volume_serial_number: Some(info.dwVolumeSerialNumber), - number_of_links: Some(info.nNumberOfLinks), - file_index: Some( - (info.nFileIndexLow as u64) | ((info.nFileIndexHigh as u64) << 32), - ), - }) - } - } - - #[cfg(target_vendor = "uwp")] - pub fn file_attr(&self) -> io::Result { - unsafe { - let mut info: c::FILE_BASIC_INFO = mem::zeroed(); - let size = mem::size_of_val(&info); - cvt(c::GetFileInformationByHandleEx( - self.handle.as_raw_handle(), - c::FileBasicInfo, - core::ptr::addr_of_mut!(info) as *mut c_void, - size as c::DWORD, - ))?; - let mut attr = FileAttr { - attributes: info.FileAttributes, - creation_time: c::FILETIME { - dwLowDateTime: info.CreationTime as c::DWORD, - dwHighDateTime: (info.CreationTime >> 32) as c::DWORD, - }, - last_access_time: c::FILETIME { - dwLowDateTime: info.LastAccessTime as c::DWORD, - dwHighDateTime: (info.LastAccessTime >> 32) as c::DWORD, - }, - last_write_time: c::FILETIME { - dwLowDateTime: info.LastWriteTime as c::DWORD, - dwHighDateTime: (info.LastWriteTime >> 32) as c::DWORD, - }, - file_size: 0, - reparse_tag: 0, - volume_serial_number: None, - number_of_links: None, - file_index: None, - }; - let mut info: c::FILE_STANDARD_INFO = mem::zeroed(); - let size = mem::size_of_val(&info); - cvt(c::GetFileInformationByHandleEx( - self.handle.as_raw_handle(), - c::FileStandardInfo, - core::ptr::addr_of_mut!(info) as *mut c_void, - size as c::DWORD, - ))?; - attr.file_size = info.AllocationSize as u64; - attr.number_of_links = Some(info.NumberOfLinks); - if attr.file_type().is_reparse_point() { - let mut attr_tag: c::FILE_ATTRIBUTE_TAG_INFO = mem::zeroed(); - cvt(c::GetFileInformationByHandleEx( - self.handle.as_raw_handle(), - c::FileAttributeTagInfo, - ptr::addr_of_mut!(attr_tag).cast(), - mem::size_of::().try_into().unwrap(), - ))?; - if attr_tag.FileAttributes & c::FILE_ATTRIBUTE_REPARSE_POINT != 0 { - attr.reparse_tag = attr_tag.ReparseTag; - } - } - Ok(attr) - } - } - - pub fn read(&self, buf: &mut [u8]) -> io::Result { - self.handle.read(buf) - } - - pub fn read_vectored(&self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - self.handle.read_vectored(bufs) - } - - #[inline] - pub fn is_read_vectored(&self) -> bool { - self.handle.is_read_vectored() - } - - pub fn read_at(&self, buf: &mut [u8], offset: u64) -> io::Result { - self.handle.read_at(buf, offset) - } - - pub fn read_buf(&self, cursor: BorrowedCursor<'_>) -> io::Result<()> { - self.handle.read_buf(cursor) - } - - pub fn write(&self, buf: &[u8]) -> io::Result { - self.handle.write(buf) - } - - pub fn write_vectored(&self, bufs: &[IoSlice<'_>]) -> io::Result { - self.handle.write_vectored(bufs) - } - - #[inline] - pub fn is_write_vectored(&self) -> bool { - self.handle.is_write_vectored() - } - - pub fn write_at(&self, buf: &[u8], offset: u64) -> io::Result { - self.handle.write_at(buf, offset) - } - - pub fn flush(&self) -> io::Result<()> { - Ok(()) - } - - pub fn seek(&self, pos: SeekFrom) -> io::Result { - let (whence, pos) = match pos { - // Casting to `i64` is fine, `SetFilePointerEx` reinterprets this - // integer as `u64`. - SeekFrom::Start(n) => (c::FILE_BEGIN, n as i64), - SeekFrom::End(n) => (c::FILE_END, n), - SeekFrom::Current(n) => (c::FILE_CURRENT, n), - }; - let pos = pos as c::LARGE_INTEGER; - let mut newpos = 0; - cvt(unsafe { c::SetFilePointerEx(self.handle.as_raw_handle(), pos, &mut newpos, whence) })?; - Ok(newpos as u64) - } - - pub fn duplicate(&self) -> io::Result { - Ok(Self { handle: self.handle.try_clone()? }) - } - - // NB: returned pointer is derived from `space`, and has provenance to - // match. A raw pointer is returned rather than a reference in order to - // avoid narrowing provenance to the actual `REPARSE_DATA_BUFFER`. - fn reparse_point( - &self, - space: &mut Align8<[MaybeUninit]>, - ) -> io::Result<(c::DWORD, *mut c::REPARSE_DATA_BUFFER)> { - unsafe { - let mut bytes = 0; - cvt({ - // Grab this in advance to avoid it invalidating the pointer - // we get from `space.0.as_mut_ptr()`. - let len = space.0.len(); - c::DeviceIoControl( - self.handle.as_raw_handle(), - c::FSCTL_GET_REPARSE_POINT, - ptr::null_mut(), - 0, - space.0.as_mut_ptr().cast(), - len as c::DWORD, - &mut bytes, - ptr::null_mut(), - ) - })?; - const _: () = assert!(core::mem::align_of::() <= 8); - Ok((bytes, space.0.as_mut_ptr().cast::())) - } - } - - fn readlink(&self) -> io::Result { - let mut space = - Align8([MaybeUninit::::uninit(); c::MAXIMUM_REPARSE_DATA_BUFFER_SIZE as usize]); - let (_bytes, buf) = self.reparse_point(&mut space)?; - unsafe { - let (path_buffer, subst_off, subst_len, relative) = match (*buf).ReparseTag { - c::IO_REPARSE_TAG_SYMLINK => { - let info: *mut c::SYMBOLIC_LINK_REPARSE_BUFFER = - ptr::addr_of_mut!((*buf).rest).cast(); - assert!(info.is_aligned()); - ( - ptr::addr_of_mut!((*info).PathBuffer).cast::(), - (*info).SubstituteNameOffset / 2, - (*info).SubstituteNameLength / 2, - (*info).Flags & c::SYMLINK_FLAG_RELATIVE != 0, - ) - } - c::IO_REPARSE_TAG_MOUNT_POINT => { - let info: *mut c::MOUNT_POINT_REPARSE_BUFFER = - ptr::addr_of_mut!((*buf).rest).cast(); - assert!(info.is_aligned()); - ( - ptr::addr_of_mut!((*info).PathBuffer).cast::(), - (*info).SubstituteNameOffset / 2, - (*info).SubstituteNameLength / 2, - false, - ) - } - _ => { - return Err(io::const_io_error!( - io::ErrorKind::Uncategorized, - "Unsupported reparse point type", - )); - } - }; - let subst_ptr = path_buffer.add(subst_off.into()); - let subst = slice::from_raw_parts_mut(subst_ptr, subst_len as usize); - // Absolute paths start with an NT internal namespace prefix `\??\` - // We should not let it leak through. - if !relative && subst.starts_with(&[92u16, 63u16, 63u16, 92u16]) { - // Turn `\??\` into `\\?\` (a verbatim path). - subst[1] = b'\\' as u16; - // Attempt to convert to a more user-friendly path. - let user = super::args::from_wide_to_user_path( - subst.iter().copied().chain([0]).collect(), - )?; - Ok(PathBuf::from(OsString::from_wide(user.strip_suffix(&[0]).unwrap_or(&user)))) - } else { - Ok(PathBuf::from(OsString::from_wide(subst))) - } - } - } - - pub fn set_permissions(&self, perm: FilePermissions) -> io::Result<()> { - let info = c::FILE_BASIC_INFO { - CreationTime: 0, - LastAccessTime: 0, - LastWriteTime: 0, - ChangeTime: 0, - FileAttributes: perm.attrs, - }; - api::set_file_information_by_handle(self.handle.as_raw_handle(), &info).io_result() - } - - pub fn set_times(&self, times: FileTimes) -> io::Result<()> { - let is_zero = |t: c::FILETIME| t.dwLowDateTime == 0 && t.dwHighDateTime == 0; - if times.accessed.map_or(false, is_zero) - || times.modified.map_or(false, is_zero) - || times.created.map_or(false, is_zero) - { - return Err(io::const_io_error!( - io::ErrorKind::InvalidInput, - "Cannot set file timestamp to 0", - )); - } - let is_max = - |t: c::FILETIME| t.dwLowDateTime == c::DWORD::MAX && t.dwHighDateTime == c::DWORD::MAX; - if times.accessed.map_or(false, is_max) - || times.modified.map_or(false, is_max) - || times.created.map_or(false, is_max) - { - return Err(io::const_io_error!( - io::ErrorKind::InvalidInput, - "Cannot set file timestamp to 0xFFFF_FFFF_FFFF_FFFF", - )); - } - cvt(unsafe { - let created = - times.created.as_ref().map(|a| a as *const c::FILETIME).unwrap_or(ptr::null()); - let accessed = - times.accessed.as_ref().map(|a| a as *const c::FILETIME).unwrap_or(ptr::null()); - let modified = - times.modified.as_ref().map(|a| a as *const c::FILETIME).unwrap_or(ptr::null()); - c::SetFileTime(self.as_raw_handle(), created, accessed, modified) - })?; - Ok(()) - } - - /// Get only basic file information such as attributes and file times. - fn basic_info(&self) -> io::Result { - unsafe { - let mut info: c::FILE_BASIC_INFO = mem::zeroed(); - let size = mem::size_of_val(&info); - cvt(c::GetFileInformationByHandleEx( - self.handle.as_raw_handle(), - c::FileBasicInfo, - core::ptr::addr_of_mut!(info) as *mut c_void, - size as c::DWORD, - ))?; - Ok(info) - } - } - /// Delete using POSIX semantics. - /// - /// Files will be deleted as soon as the handle is closed. This is supported - /// for Windows 10 1607 (aka RS1) and later. However some filesystem - /// drivers will not support it even then, e.g. FAT32. - /// - /// If the operation is not supported for this filesystem or OS version - /// then errors will be `ERROR_NOT_SUPPORTED` or `ERROR_INVALID_PARAMETER`. - fn posix_delete(&self) -> io::Result<()> { - let info = c::FILE_DISPOSITION_INFO_EX { - Flags: c::FILE_DISPOSITION_FLAG_DELETE - | c::FILE_DISPOSITION_FLAG_POSIX_SEMANTICS - | c::FILE_DISPOSITION_FLAG_IGNORE_READONLY_ATTRIBUTE, - }; - api::set_file_information_by_handle(self.handle.as_raw_handle(), &info).io_result() - } - - /// Delete a file using win32 semantics. The file won't actually be deleted - /// until all file handles are closed. However, marking a file for deletion - /// will prevent anyone from opening a new handle to the file. - fn win32_delete(&self) -> io::Result<()> { - let info = c::FILE_DISPOSITION_INFO { DeleteFile: c::TRUE as _ }; - api::set_file_information_by_handle(self.handle.as_raw_handle(), &info).io_result() - } - - /// Fill the given buffer with as many directory entries as will fit. - /// This will remember its position and continue from the last call unless - /// `restart` is set to `true`. - /// - /// The returned bool indicates if there are more entries or not. - /// It is an error if `self` is not a directory. - /// - /// # Symlinks and other reparse points - /// - /// On Windows a file is either a directory or a non-directory. - /// A symlink directory is simply an empty directory with some "reparse" metadata attached. - /// So if you open a link (not its target) and iterate the directory, - /// you will always iterate an empty directory regardless of the target. - fn fill_dir_buff(&self, buffer: &mut DirBuff, restart: bool) -> io::Result { - let class = - if restart { c::FileIdBothDirectoryRestartInfo } else { c::FileIdBothDirectoryInfo }; - - unsafe { - let result = cvt(c::GetFileInformationByHandleEx( - self.handle.as_raw_handle(), - class, - buffer.as_mut_ptr().cast(), - buffer.capacity() as _, - )); - match result { - Ok(_) => Ok(true), - Err(e) if e.raw_os_error() == Some(c::ERROR_NO_MORE_FILES as _) => Ok(false), - Err(e) => Err(e), - } - } - } -} - -/// A buffer for holding directory entries. -struct DirBuff { - buffer: Box; Self::BUFFER_SIZE]>>, -} -impl DirBuff { - const BUFFER_SIZE: usize = 1024; - fn new() -> Self { - Self { - // Safety: `Align8<[MaybeUninit; N]>` does not need - // initialization. - buffer: unsafe { Box::new_uninit().assume_init() }, - } - } - fn capacity(&self) -> usize { - self.buffer.0.len() - } - fn as_mut_ptr(&mut self) -> *mut u8 { - self.buffer.0.as_mut_ptr().cast() - } - /// Returns a `DirBuffIter`. - fn iter(&self) -> DirBuffIter<'_> { - DirBuffIter::new(self) - } -} -impl AsRef<[MaybeUninit]> for DirBuff { - fn as_ref(&self) -> &[MaybeUninit] { - &self.buffer.0 - } -} - -/// An iterator over entries stored in a `DirBuff`. -/// -/// Currently only returns file names (UTF-16 encoded). -struct DirBuffIter<'a> { - buffer: Option<&'a [MaybeUninit]>, - cursor: usize, -} -impl<'a> DirBuffIter<'a> { - fn new(buffer: &'a DirBuff) -> Self { - Self { buffer: Some(buffer.as_ref()), cursor: 0 } - } -} -impl<'a> Iterator for DirBuffIter<'a> { - type Item = (Cow<'a, [u16]>, bool); - fn next(&mut self) -> Option { - use crate::mem::size_of; - let buffer = &self.buffer?[self.cursor..]; - - // Get the name and next entry from the buffer. - // SAFETY: - // - The buffer contains a `FILE_ID_BOTH_DIR_INFO` struct but the last - // field (the file name) is unsized. So an offset has to be used to - // get the file name slice. - // - The OS has guaranteed initialization of the fields of - // `FILE_ID_BOTH_DIR_INFO` and the trailing filename (for at least - // `FileNameLength` bytes) - let (name, is_directory, next_entry) = unsafe { - let info = buffer.as_ptr().cast::(); - // While this is guaranteed to be aligned in documentation for - // https://docs.microsoft.com/en-us/windows/win32/api/winbase/ns-winbase-file_id_both_dir_info - // it does not seem that reality is so kind, and assuming this - // caused crashes in some cases (https://github.com/rust-lang/rust/issues/104530) - // presumably, this can be blamed on buggy filesystem drivers, but who knows. - let next_entry = ptr::addr_of!((*info).NextEntryOffset).read_unaligned() as usize; - let length = ptr::addr_of!((*info).FileNameLength).read_unaligned() as usize; - let attrs = ptr::addr_of!((*info).FileAttributes).read_unaligned(); - let name = from_maybe_unaligned( - ptr::addr_of!((*info).FileName).cast::(), - length / size_of::(), - ); - let is_directory = (attrs & c::FILE_ATTRIBUTE_DIRECTORY) != 0; - - (name, is_directory, next_entry) - }; - - if next_entry == 0 { - self.buffer = None - } else { - self.cursor += next_entry - } - - // Skip `.` and `..` pseudo entries. - const DOT: u16 = b'.' as u16; - match &name[..] { - [DOT] | [DOT, DOT] => self.next(), - _ => Some((name, is_directory)), - } - } -} - -unsafe fn from_maybe_unaligned<'a>(p: *const u16, len: usize) -> Cow<'a, [u16]> { - if p.is_aligned() { - Cow::Borrowed(crate::slice::from_raw_parts(p, len)) - } else { - Cow::Owned((0..len).map(|i| p.add(i).read_unaligned()).collect()) - } -} - -/// Open a link relative to the parent directory, ensure no symlinks are followed. -fn open_link_no_reparse(parent: &File, name: &[u16], access: u32) -> io::Result { - // This is implemented using the lower level `NtCreateFile` function as - // unfortunately opening a file relative to a parent is not supported by - // win32 functions. It is however a fundamental feature of the NT kernel. - // - // See https://docs.microsoft.com/en-us/windows/win32/api/winternl/nf-winternl-ntcreatefile - unsafe { - let mut handle = ptr::null_mut(); - let mut io_status = c::IO_STATUS_BLOCK::PENDING; - let mut name_str = c::UNICODE_STRING::from_ref(name); - use crate::sync::atomic::{AtomicU32, Ordering}; - // The `OBJ_DONT_REPARSE` attribute ensures that we haven't been - // tricked into following a symlink. However, it may not be available in - // earlier versions of Windows. - static ATTRIBUTES: AtomicU32 = AtomicU32::new(c::OBJ_DONT_REPARSE); - let object = c::OBJECT_ATTRIBUTES { - ObjectName: &mut name_str, - RootDirectory: parent.as_raw_handle(), - Attributes: ATTRIBUTES.load(Ordering::Relaxed), - ..c::OBJECT_ATTRIBUTES::default() - }; - let status = c::NtCreateFile( - &mut handle, - access, - &object, - &mut io_status, - crate::ptr::null_mut(), - 0, - c::FILE_SHARE_DELETE | c::FILE_SHARE_READ | c::FILE_SHARE_WRITE, - c::FILE_OPEN, - // If `name` is a symlink then open the link rather than the target. - c::FILE_OPEN_REPARSE_POINT, - crate::ptr::null_mut(), - 0, - ); - // Convert an NTSTATUS to the more familiar Win32 error codes (aka "DosError") - if c::nt_success(status) { - Ok(File::from_raw_handle(handle)) - } else if status == c::STATUS_DELETE_PENDING { - // We make a special exception for `STATUS_DELETE_PENDING` because - // otherwise this will be mapped to `ERROR_ACCESS_DENIED` which is - // very unhelpful. - Err(io::Error::from_raw_os_error(c::ERROR_DELETE_PENDING as _)) - } else if status == c::STATUS_INVALID_PARAMETER - && ATTRIBUTES.load(Ordering::Relaxed) == c::OBJ_DONT_REPARSE - { - // Try without `OBJ_DONT_REPARSE`. See above. - ATTRIBUTES.store(0, Ordering::Relaxed); - open_link_no_reparse(parent, name, access) - } else { - Err(io::Error::from_raw_os_error(c::RtlNtStatusToDosError(status) as _)) - } - } -} - -impl AsInner for File { - #[inline] - fn as_inner(&self) -> &Handle { - &self.handle - } -} - -impl IntoInner for File { - fn into_inner(self) -> Handle { - self.handle - } -} - -impl FromInner for File { - fn from_inner(handle: Handle) -> File { - File { handle } - } -} - -impl AsHandle for File { - fn as_handle(&self) -> BorrowedHandle<'_> { - self.as_inner().as_handle() - } -} - -impl AsRawHandle for File { - fn as_raw_handle(&self) -> RawHandle { - self.as_inner().as_raw_handle() - } -} - -impl IntoRawHandle for File { - fn into_raw_handle(self) -> RawHandle { - self.into_inner().into_raw_handle() - } -} - -impl FromRawHandle for File { - unsafe fn from_raw_handle(raw_handle: RawHandle) -> Self { - Self { handle: FromInner::from_inner(FromRawHandle::from_raw_handle(raw_handle)) } - } -} - -impl fmt::Debug for File { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - // FIXME(#24570): add more info here (e.g., mode) - let mut b = f.debug_struct("File"); - b.field("handle", &self.handle.as_raw_handle()); - if let Ok(path) = get_path(self) { - b.field("path", &path); - } - b.finish() - } -} - -impl FileAttr { - pub fn size(&self) -> u64 { - self.file_size - } - - pub fn perm(&self) -> FilePermissions { - FilePermissions { attrs: self.attributes } - } - - pub fn attrs(&self) -> u32 { - self.attributes - } - - pub fn file_type(&self) -> FileType { - FileType::new(self.attributes, self.reparse_tag) - } - - pub fn modified(&self) -> io::Result { - Ok(SystemTime::from(self.last_write_time)) - } - - pub fn accessed(&self) -> io::Result { - Ok(SystemTime::from(self.last_access_time)) - } - - pub fn created(&self) -> io::Result { - Ok(SystemTime::from(self.creation_time)) - } - - pub fn modified_u64(&self) -> u64 { - to_u64(&self.last_write_time) - } - - pub fn accessed_u64(&self) -> u64 { - to_u64(&self.last_access_time) - } - - pub fn created_u64(&self) -> u64 { - to_u64(&self.creation_time) - } - - pub fn volume_serial_number(&self) -> Option { - self.volume_serial_number - } - - pub fn number_of_links(&self) -> Option { - self.number_of_links - } - - pub fn file_index(&self) -> Option { - self.file_index - } -} -impl From for FileAttr { - fn from(wfd: c::WIN32_FIND_DATAW) -> Self { - FileAttr { - attributes: wfd.dwFileAttributes, - creation_time: wfd.ftCreationTime, - last_access_time: wfd.ftLastAccessTime, - last_write_time: wfd.ftLastWriteTime, - file_size: ((wfd.nFileSizeHigh as u64) << 32) | (wfd.nFileSizeLow as u64), - reparse_tag: if wfd.dwFileAttributes & c::FILE_ATTRIBUTE_REPARSE_POINT != 0 { - // reserved unless this is a reparse point - wfd.dwReserved0 - } else { - 0 - }, - volume_serial_number: None, - number_of_links: None, - file_index: None, - } - } -} - -fn to_u64(ft: &c::FILETIME) -> u64 { - (ft.dwLowDateTime as u64) | ((ft.dwHighDateTime as u64) << 32) -} - -impl FilePermissions { - pub fn readonly(&self) -> bool { - self.attrs & c::FILE_ATTRIBUTE_READONLY != 0 - } - - pub fn set_readonly(&mut self, readonly: bool) { - if readonly { - self.attrs |= c::FILE_ATTRIBUTE_READONLY; - } else { - self.attrs &= !c::FILE_ATTRIBUTE_READONLY; - } - } -} - -impl FileTimes { - pub fn set_accessed(&mut self, t: SystemTime) { - self.accessed = Some(t.into_inner()); - } - - pub fn set_modified(&mut self, t: SystemTime) { - self.modified = Some(t.into_inner()); - } - - pub fn set_created(&mut self, t: SystemTime) { - self.created = Some(t.into_inner()); - } -} - -impl FileType { - fn new(attrs: c::DWORD, reparse_tag: c::DWORD) -> FileType { - FileType { attributes: attrs, reparse_tag } - } - pub fn is_dir(&self) -> bool { - !self.is_symlink() && self.is_directory() - } - pub fn is_file(&self) -> bool { - !self.is_symlink() && !self.is_directory() - } - pub fn is_symlink(&self) -> bool { - self.is_reparse_point() && self.is_reparse_tag_name_surrogate() - } - pub fn is_symlink_dir(&self) -> bool { - self.is_symlink() && self.is_directory() - } - pub fn is_symlink_file(&self) -> bool { - self.is_symlink() && !self.is_directory() - } - fn is_directory(&self) -> bool { - self.attributes & c::FILE_ATTRIBUTE_DIRECTORY != 0 - } - fn is_reparse_point(&self) -> bool { - self.attributes & c::FILE_ATTRIBUTE_REPARSE_POINT != 0 - } - fn is_reparse_tag_name_surrogate(&self) -> bool { - self.reparse_tag & 0x20000000 != 0 - } -} - -impl DirBuilder { - pub fn new() -> DirBuilder { - DirBuilder - } - - pub fn mkdir(&self, p: &Path) -> io::Result<()> { - let p = maybe_verbatim(p)?; - cvt(unsafe { c::CreateDirectoryW(p.as_ptr(), ptr::null_mut()) })?; - Ok(()) - } -} - -pub fn readdir(p: &Path) -> io::Result { - // We push a `*` to the end of the path which cause the empty path to be - // treated as the current directory. So, for consistency with other platforms, - // we explicitly error on the empty path. - if p.as_os_str().is_empty() { - // Return an error code consistent with other ways of opening files. - // E.g. fs::metadata or File::open. - return Err(io::Error::from_raw_os_error(c::ERROR_PATH_NOT_FOUND as i32)); - } - let root = p.to_path_buf(); - let star = p.join("*"); - let path = maybe_verbatim(&star)?; - - unsafe { - let mut wfd = mem::zeroed(); - let find_handle = c::FindFirstFileW(path.as_ptr(), &mut wfd); - - if find_handle != c::INVALID_HANDLE_VALUE { - Ok(ReadDir { - handle: FindNextFileHandle(find_handle), - root: Arc::new(root), - first: Some(wfd), - }) - } else { - // The status `ERROR_FILE_NOT_FOUND` is returned by the `FindFirstFileW` function - // if no matching files can be found, but not necessarily that the path to find the - // files in does not exist. - // - // Hence, a check for whether the path to search in exists is added when the last - // os error returned by Windows is `ERROR_FILE_NOT_FOUND` to handle this scenario. - // If that is the case, an empty `ReadDir` iterator is returned as it returns `None` - // in the initial `.next()` invocation because `ERROR_NO_MORE_FILES` would have been - // returned by the `FindNextFileW` function. - // - // See issue #120040: https://github.com/rust-lang/rust/issues/120040. - let last_error = api::get_last_error(); - if last_error.code == c::ERROR_FILE_NOT_FOUND { - return Ok(ReadDir { - handle: FindNextFileHandle(find_handle), - root: Arc::new(root), - first: None, - }); - } - - // Just return the error constructed from the raw OS error if the above is not the case. - // - // Note: `ERROR_PATH_NOT_FOUND` would have been returned by the `FindFirstFileW` function - // when the path to search in does not exist in the first place. - Err(Error::from_raw_os_error(last_error.code as i32)) - } - } -} - -pub fn unlink(p: &Path) -> io::Result<()> { - let p_u16s = maybe_verbatim(p)?; - cvt(unsafe { c::DeleteFileW(p_u16s.as_ptr()) })?; - Ok(()) -} - -pub fn rename(old: &Path, new: &Path) -> io::Result<()> { - let old = maybe_verbatim(old)?; - let new = maybe_verbatim(new)?; - cvt(unsafe { c::MoveFileExW(old.as_ptr(), new.as_ptr(), c::MOVEFILE_REPLACE_EXISTING) })?; - Ok(()) -} - -pub fn rmdir(p: &Path) -> io::Result<()> { - let p = maybe_verbatim(p)?; - cvt(unsafe { c::RemoveDirectoryW(p.as_ptr()) })?; - Ok(()) -} - -/// Open a file or directory without following symlinks. -fn open_link(path: &Path, access_mode: u32) -> io::Result { - let mut opts = OpenOptions::new(); - opts.access_mode(access_mode); - // `FILE_FLAG_BACKUP_SEMANTICS` allows opening directories. - // `FILE_FLAG_OPEN_REPARSE_POINT` opens a link instead of its target. - opts.custom_flags(c::FILE_FLAG_BACKUP_SEMANTICS | c::FILE_FLAG_OPEN_REPARSE_POINT); - File::open(path, &opts) -} - -pub fn remove_dir_all(path: &Path) -> io::Result<()> { - let file = open_link(path, c::DELETE | c::FILE_LIST_DIRECTORY)?; - - // Test if the file is not a directory or a symlink to a directory. - if (file.basic_info()?.FileAttributes & c::FILE_ATTRIBUTE_DIRECTORY) == 0 { - return Err(io::Error::from_raw_os_error(c::ERROR_DIRECTORY as _)); - } - - match remove_dir_all_iterative(&file, File::posix_delete) { - Err(e) => { - if let Some(code) = e.raw_os_error() { - match code as u32 { - // If POSIX delete is not supported for this filesystem then fallback to win32 delete. - c::ERROR_NOT_SUPPORTED - | c::ERROR_INVALID_FUNCTION - | c::ERROR_INVALID_PARAMETER => { - remove_dir_all_iterative(&file, File::win32_delete) - } - _ => Err(e), - } - } else { - Err(e) - } - } - ok => ok, - } -} - -fn remove_dir_all_iterative(f: &File, delete: fn(&File) -> io::Result<()>) -> io::Result<()> { - // When deleting files we may loop this many times when certain error conditions occur. - // This allows remove_dir_all to succeed when the error is temporary. - const MAX_RETRIES: u32 = 10; - - let mut buffer = DirBuff::new(); - let mut dirlist = vec![f.duplicate()?]; - - // FIXME: This is a hack so we can push to the dirlist vec after borrowing from it. - fn copy_handle(f: &File) -> mem::ManuallyDrop { - unsafe { mem::ManuallyDrop::new(File::from_raw_handle(f.as_raw_handle())) } - } - - let mut restart = true; - while let Some(dir) = dirlist.last() { - let dir = copy_handle(dir); - - // Fill the buffer and iterate the entries. - let more_data = dir.fill_dir_buff(&mut buffer, restart)?; - restart = false; - for (name, is_directory) in buffer.iter() { - if is_directory { - let child_dir = open_link_no_reparse( - &dir, - &name, - c::SYNCHRONIZE | c::DELETE | c::FILE_LIST_DIRECTORY, - ); - // On success, add the handle to the queue. - // If opening the directory fails we treat it the same as a file - if let Ok(child_dir) = child_dir { - dirlist.push(child_dir); - continue; - } - } - for i in 1..=MAX_RETRIES { - let result = open_link_no_reparse(&dir, &name, c::SYNCHRONIZE | c::DELETE); - match result { - Ok(f) => delete(&f)?, - // Already deleted, so skip. - Err(e) if e.kind() == io::ErrorKind::NotFound => break, - // Retry a few times if the file is locked or a delete is already in progress. - Err(e) - if i < MAX_RETRIES - && (e.raw_os_error() == Some(c::ERROR_DELETE_PENDING as _) - || e.raw_os_error() == Some(c::ERROR_SHARING_VIOLATION as _)) => {} - // Otherwise return the error. - Err(e) => return Err(e), - } - thread::yield_now(); - } - } - // If there were no more files then delete the directory. - if !more_data { - if let Some(dir) = dirlist.pop() { - // Retry deleting a few times in case we need to wait for a file to be deleted. - for i in 1..=MAX_RETRIES { - let result = delete(&dir); - if let Err(e) = result { - if i == MAX_RETRIES || e.kind() != io::ErrorKind::DirectoryNotEmpty { - return Err(e); - } - thread::yield_now(); - } else { - break; - } - } - } - } - } - Ok(()) -} - -pub fn readlink(path: &Path) -> io::Result { - // Open the link with no access mode, instead of generic read. - // By default FILE_LIST_DIRECTORY is denied for the junction "C:\Documents and Settings", so - // this is needed for a common case. - let mut opts = OpenOptions::new(); - opts.access_mode(0); - opts.custom_flags(c::FILE_FLAG_OPEN_REPARSE_POINT | c::FILE_FLAG_BACKUP_SEMANTICS); - let file = File::open(path, &opts)?; - file.readlink() -} - -pub fn symlink(original: &Path, link: &Path) -> io::Result<()> { - symlink_inner(original, link, false) -} - -pub fn symlink_inner(original: &Path, link: &Path, dir: bool) -> io::Result<()> { - let original = to_u16s(original)?; - let link = maybe_verbatim(link)?; - let flags = if dir { c::SYMBOLIC_LINK_FLAG_DIRECTORY } else { 0 }; - // Formerly, symlink creation required the SeCreateSymbolicLink privilege. For the Windows 10 - // Creators Update, Microsoft loosened this to allow unprivileged symlink creation if the - // computer is in Developer Mode, but SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE must be - // added to dwFlags to opt into this behaviour. - let result = cvt(unsafe { - c::CreateSymbolicLinkW( - link.as_ptr(), - original.as_ptr(), - flags | c::SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE, - ) as c::BOOL - }); - if let Err(err) = result { - if err.raw_os_error() == Some(c::ERROR_INVALID_PARAMETER as i32) { - // Older Windows objects to SYMBOLIC_LINK_FLAG_ALLOW_UNPRIVILEGED_CREATE, - // so if we encounter ERROR_INVALID_PARAMETER, retry without that flag. - cvt(unsafe { - c::CreateSymbolicLinkW(link.as_ptr(), original.as_ptr(), flags) as c::BOOL - })?; - } else { - return Err(err); - } - } - Ok(()) -} - -#[cfg(not(target_vendor = "uwp"))] -pub fn link(original: &Path, link: &Path) -> io::Result<()> { - let original = maybe_verbatim(original)?; - let link = maybe_verbatim(link)?; - cvt(unsafe { c::CreateHardLinkW(link.as_ptr(), original.as_ptr(), ptr::null_mut()) })?; - Ok(()) -} - -#[cfg(target_vendor = "uwp")] -pub fn link(_original: &Path, _link: &Path) -> io::Result<()> { - return Err(io::const_io_error!( - io::ErrorKind::Unsupported, - "hard link are not supported on UWP", - )); -} - -pub fn stat(path: &Path) -> io::Result { - match metadata(path, ReparsePoint::Follow) { - Err(err) if err.raw_os_error() == Some(c::ERROR_CANT_ACCESS_FILE as i32) => { - if let Ok(attrs) = lstat(path) { - if !attrs.file_type().is_symlink() { - return Ok(attrs); - } - } - Err(err) - } - result => result, - } -} - -pub fn lstat(path: &Path) -> io::Result { - metadata(path, ReparsePoint::Open) -} - -#[repr(u32)] -#[derive(Clone, Copy, PartialEq, Eq)] -enum ReparsePoint { - Follow = 0, - Open = c::FILE_FLAG_OPEN_REPARSE_POINT, -} -impl ReparsePoint { - fn as_flag(self) -> u32 { - self as u32 - } -} - -fn metadata(path: &Path, reparse: ReparsePoint) -> io::Result { - let mut opts = OpenOptions::new(); - // No read or write permissions are necessary - opts.access_mode(0); - opts.custom_flags(c::FILE_FLAG_BACKUP_SEMANTICS | reparse.as_flag()); - - // Attempt to open the file normally. - // If that fails with `ERROR_SHARING_VIOLATION` then retry using `FindFirstFileW`. - // If the fallback fails for any reason we return the original error. - match File::open(path, &opts) { - Ok(file) => file.file_attr(), - Err(e) - if [Some(c::ERROR_SHARING_VIOLATION as _), Some(c::ERROR_ACCESS_DENIED as _)] - .contains(&e.raw_os_error()) => - { - // `ERROR_ACCESS_DENIED` is returned when the user doesn't have permission for the resource. - // One such example is `System Volume Information` as default but can be created as well - // `ERROR_SHARING_VIOLATION` will almost never be returned. - // Usually if a file is locked you can still read some metadata. - // However, there are special system files, such as - // `C:\hiberfil.sys`, that are locked in a way that denies even that. - unsafe { - let path = maybe_verbatim(path)?; - - // `FindFirstFileW` accepts wildcard file names. - // Fortunately wildcards are not valid file names and - // `ERROR_SHARING_VIOLATION` means the file exists (but is locked) - // therefore it's safe to assume the file name given does not - // include wildcards. - let mut wfd = mem::zeroed(); - let handle = c::FindFirstFileW(path.as_ptr(), &mut wfd); - - if handle == c::INVALID_HANDLE_VALUE { - // This can fail if the user does not have read access to the - // directory. - Err(e) - } else { - // We no longer need the find handle. - c::FindClose(handle); - - // `FindFirstFileW` reads the cached file information from the - // directory. The downside is that this metadata may be outdated. - let attrs = FileAttr::from(wfd); - if reparse == ReparsePoint::Follow && attrs.file_type().is_symlink() { - Err(e) - } else { - Ok(attrs) - } - } - } - } - Err(e) => Err(e), - } -} - -pub fn set_perm(p: &Path, perm: FilePermissions) -> io::Result<()> { - let p = maybe_verbatim(p)?; - unsafe { - cvt(c::SetFileAttributesW(p.as_ptr(), perm.attrs))?; - Ok(()) - } -} - -fn get_path(f: &File) -> io::Result { - super::fill_utf16_buf( - |buf, sz| unsafe { - c::GetFinalPathNameByHandleW(f.handle.as_raw_handle(), buf, sz, c::VOLUME_NAME_DOS) - }, - |buf| PathBuf::from(OsString::from_wide(buf)), - ) -} - -pub fn canonicalize(p: &Path) -> io::Result { - let mut opts = OpenOptions::new(); - // No read or write permissions are necessary - opts.access_mode(0); - // This flag is so we can open directories too - opts.custom_flags(c::FILE_FLAG_BACKUP_SEMANTICS); - let f = File::open(p, &opts)?; - get_path(&f) -} - -pub fn copy(from: &Path, to: &Path) -> io::Result { - unsafe extern "system" fn callback( - _TotalFileSize: c::LARGE_INTEGER, - _TotalBytesTransferred: c::LARGE_INTEGER, - _StreamSize: c::LARGE_INTEGER, - StreamBytesTransferred: c::LARGE_INTEGER, - dwStreamNumber: c::DWORD, - _dwCallbackReason: c::DWORD, - _hSourceFile: c::HANDLE, - _hDestinationFile: c::HANDLE, - lpData: c::LPCVOID, - ) -> c::DWORD { - if dwStreamNumber == 1 { - *(lpData as *mut i64) = StreamBytesTransferred; - } - c::PROGRESS_CONTINUE - } - let pfrom = maybe_verbatim(from)?; - let pto = maybe_verbatim(to)?; - let mut size = 0i64; - cvt(unsafe { - c::CopyFileExW( - pfrom.as_ptr(), - pto.as_ptr(), - Some(callback), - core::ptr::addr_of_mut!(size) as *mut _, - ptr::null_mut(), - 0, - ) - })?; - Ok(size as u64) -} - -pub fn junction_point(original: &Path, link: &Path) -> io::Result<()> { - // Create and open a new directory in one go. - let mut opts = OpenOptions::new(); - opts.create_new(true); - opts.write(true); - opts.custom_flags(c::FILE_FLAG_BACKUP_SEMANTICS | c::FILE_FLAG_POSIX_SEMANTICS); - opts.attributes(c::FILE_ATTRIBUTE_DIRECTORY); - - let d = File::open(link, &opts)?; - - // We need to get an absolute, NT-style path. - let path_bytes = original.as_os_str().as_encoded_bytes(); - let abs_path: Vec = if path_bytes.starts_with(br"\\?\") || path_bytes.starts_with(br"\??\") - { - // It's already an absolute path, we just need to convert the prefix to `\??\` - let bytes = unsafe { OsStr::from_encoded_bytes_unchecked(&path_bytes[4..]) }; - r"\??\".encode_utf16().chain(bytes.encode_wide()).collect() - } else { - // Get an absolute path and then convert the prefix to `\??\` - let abs_path = crate::path::absolute(original)?.into_os_string().into_encoded_bytes(); - if abs_path.len() > 0 && abs_path[1..].starts_with(br":\") { - let bytes = unsafe { OsStr::from_encoded_bytes_unchecked(&abs_path) }; - r"\??\".encode_utf16().chain(bytes.encode_wide()).collect() - } else if abs_path.starts_with(br"\\.\") { - let bytes = unsafe { OsStr::from_encoded_bytes_unchecked(&abs_path[4..]) }; - r"\??\".encode_utf16().chain(bytes.encode_wide()).collect() - } else if abs_path.starts_with(br"\\") { - let bytes = unsafe { OsStr::from_encoded_bytes_unchecked(&abs_path[2..]) }; - r"\??\UNC\".encode_utf16().chain(bytes.encode_wide()).collect() - } else { - return Err(io::const_io_error!(io::ErrorKind::InvalidInput, "path is not valid")); - } - }; - // Defined inline so we don't have to mess about with variable length buffer. - #[repr(C)] - pub struct MountPointBuffer { - ReparseTag: u32, - ReparseDataLength: u16, - Reserved: u16, - SubstituteNameOffset: u16, - SubstituteNameLength: u16, - PrintNameOffset: u16, - PrintNameLength: u16, - PathBuffer: [MaybeUninit; c::MAXIMUM_REPARSE_DATA_BUFFER_SIZE as usize], - } - let data_len = 12 + (abs_path.len() * 2); - if data_len > u16::MAX as usize { - return Err(io::const_io_error!( - io::ErrorKind::InvalidInput, - "`original` path is too long" - )); - } - let data_len = data_len as u16; - let mut header = MountPointBuffer { - ReparseTag: c::IO_REPARSE_TAG_MOUNT_POINT, - ReparseDataLength: data_len, - Reserved: 0, - SubstituteNameOffset: 0, - SubstituteNameLength: (abs_path.len() * 2) as u16, - PrintNameOffset: ((abs_path.len() + 1) * 2) as u16, - PrintNameLength: 0, - PathBuffer: [MaybeUninit::uninit(); c::MAXIMUM_REPARSE_DATA_BUFFER_SIZE as usize], - }; - unsafe { - let ptr = header.PathBuffer.as_mut_ptr(); - ptr.copy_from(abs_path.as_ptr().cast::>(), abs_path.len()); - - let mut ret = 0; - cvt(c::DeviceIoControl( - d.as_raw_handle(), - c::FSCTL_SET_REPARSE_POINT, - addr_of!(header).cast::(), - data_len as u32 + 8, - ptr::null_mut(), - 0, - &mut ret, - ptr::null_mut(), - )) - .map(drop) - } -} - -// Try to see if a file exists but, unlike `exists`, report I/O errors. -pub fn try_exists(path: &Path) -> io::Result { - // Open the file to ensure any symlinks are followed to their target. - let mut opts = OpenOptions::new(); - // No read, write, etc access rights are needed. - opts.access_mode(0); - // Backup semantics enables opening directories as well as files. - opts.custom_flags(c::FILE_FLAG_BACKUP_SEMANTICS); - match File::open(path, &opts) { - Err(e) => match e.kind() { - // The file definitely does not exist - io::ErrorKind::NotFound => Ok(false), - - // `ERROR_SHARING_VIOLATION` means that the file has been locked by - // another process. This is often temporary so we simply report it - // as the file existing. - _ if e.raw_os_error() == Some(c::ERROR_SHARING_VIOLATION as i32) => Ok(true), - - // `ERROR_CANT_ACCESS_FILE` means that a file exists but that the - // reparse point could not be handled by `CreateFile`. - // This can happen for special files such as: - // * Unix domain sockets which you need to `connect` to - // * App exec links which require using `CreateProcess` - _ if e.raw_os_error() == Some(c::ERROR_CANT_ACCESS_FILE as i32) => Ok(true), - - // Other errors such as `ERROR_ACCESS_DENIED` may indicate that the - // file exists. However, these types of errors are usually more - // permanent so we report them here. - _ => Err(e), - }, - // The file was opened successfully therefore it must exist, - Ok(_) => Ok(true), - } -} diff --git a/library/std/src/sys/pal/windows/futex.rs b/library/std/src/sys/pal/windows/futex.rs deleted file mode 100644 index bc19c402d9c12..0000000000000 --- a/library/std/src/sys/pal/windows/futex.rs +++ /dev/null @@ -1,85 +0,0 @@ -use super::api; -use crate::sys::c; -use crate::sys::dur2timeout; -use core::ffi::c_void; -use core::mem; -use core::ptr; -use core::sync::atomic::{ - AtomicBool, AtomicI16, AtomicI32, AtomicI64, AtomicI8, AtomicIsize, AtomicPtr, AtomicU16, - AtomicU32, AtomicU64, AtomicU8, AtomicUsize, -}; -use core::time::Duration; - -pub unsafe trait Waitable { - type Atomic; -} -macro_rules! unsafe_waitable_int { - ($(($int:ty, $atomic:ty)),*$(,)?) => { - $( - unsafe impl Waitable for $int { - type Atomic = $atomic; - } - )* - }; -} -unsafe_waitable_int! { - (bool, AtomicBool), - (i8, AtomicI8), - (i16, AtomicI16), - (i32, AtomicI32), - (i64, AtomicI64), - (isize, AtomicIsize), - (u8, AtomicU8), - (u16, AtomicU16), - (u32, AtomicU32), - (u64, AtomicU64), - (usize, AtomicUsize), -} -unsafe impl Waitable for *const T { - type Atomic = AtomicPtr; -} -unsafe impl Waitable for *mut T { - type Atomic = AtomicPtr; -} - -pub fn wait_on_address( - address: &W::Atomic, - compare: W, - timeout: Option, -) -> bool { - unsafe { - let addr = ptr::from_ref(address).cast::(); - let size = mem::size_of::(); - let compare_addr = ptr::addr_of!(compare).cast::(); - let timeout = timeout.map(dur2timeout).unwrap_or(c::INFINITE); - c::WaitOnAddress(addr, compare_addr, size, timeout) == c::TRUE - } -} - -pub fn wake_by_address_single(address: &T) { - unsafe { - let addr = ptr::from_ref(address).cast::(); - c::WakeByAddressSingle(addr); - } -} - -pub fn wake_by_address_all(address: &T) { - unsafe { - let addr = ptr::from_ref(address).cast::(); - c::WakeByAddressAll(addr); - } -} - -pub fn futex_wait(futex: &W::Atomic, expected: W, timeout: Option) -> bool { - // return false only on timeout - wait_on_address(futex, expected, timeout) || api::get_last_error().code != c::ERROR_TIMEOUT -} - -pub fn futex_wake(futex: &T) -> bool { - wake_by_address_single(futex); - false -} - -pub fn futex_wake_all(futex: &T) { - wake_by_address_all(futex) -} diff --git a/library/std/src/sys/pal/windows/handle.rs b/library/std/src/sys/pal/windows/handle.rs deleted file mode 100644 index 3f85bb0a099a9..0000000000000 --- a/library/std/src/sys/pal/windows/handle.rs +++ /dev/null @@ -1,338 +0,0 @@ -#![unstable(issue = "none", feature = "windows_handle")] - -#[cfg(test)] -mod tests; - -use crate::cmp; -use crate::io::{self, BorrowedCursor, ErrorKind, IoSlice, IoSliceMut, Read}; -use crate::mem; -use crate::os::windows::io::{ - AsHandle, AsRawHandle, BorrowedHandle, FromRawHandle, IntoRawHandle, OwnedHandle, RawHandle, -}; -use crate::ptr; -use crate::sys::c; -use crate::sys::cvt; -use crate::sys_common::{AsInner, FromInner, IntoInner}; - -/// An owned container for `HANDLE` object, closing them on Drop. -/// -/// All methods are inherited through a `Deref` impl to `RawHandle` -pub struct Handle(OwnedHandle); - -impl Handle { - pub fn new_event(manual: bool, init: bool) -> io::Result { - unsafe { - let event = - c::CreateEventW(ptr::null_mut(), manual as c::BOOL, init as c::BOOL, ptr::null()); - if event.is_null() { - Err(io::Error::last_os_error()) - } else { - Ok(Handle::from_raw_handle(event)) - } - } - } -} - -impl AsInner for Handle { - #[inline] - fn as_inner(&self) -> &OwnedHandle { - &self.0 - } -} - -impl IntoInner for Handle { - fn into_inner(self) -> OwnedHandle { - self.0 - } -} - -impl FromInner for Handle { - fn from_inner(file_desc: OwnedHandle) -> Self { - Self(file_desc) - } -} - -impl AsHandle for Handle { - fn as_handle(&self) -> BorrowedHandle<'_> { - self.0.as_handle() - } -} - -impl AsRawHandle for Handle { - fn as_raw_handle(&self) -> RawHandle { - self.0.as_raw_handle() - } -} - -impl IntoRawHandle for Handle { - fn into_raw_handle(self) -> RawHandle { - self.0.into_raw_handle() - } -} - -impl FromRawHandle for Handle { - unsafe fn from_raw_handle(raw_handle: RawHandle) -> Self { - Self(FromRawHandle::from_raw_handle(raw_handle)) - } -} - -impl Handle { - pub fn read(&self, buf: &mut [u8]) -> io::Result { - let res = unsafe { self.synchronous_read(buf.as_mut_ptr().cast(), buf.len(), None) }; - - match res { - Ok(read) => Ok(read), - - // The special treatment of BrokenPipe is to deal with Windows - // pipe semantics, which yields this error when *reading* from - // a pipe after the other end has closed; we interpret that as - // EOF on the pipe. - Err(ref e) if e.kind() == ErrorKind::BrokenPipe => Ok(0), - - Err(e) => Err(e), - } - } - - pub fn read_vectored(&self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - crate::io::default_read_vectored(|buf| self.read(buf), bufs) - } - - #[inline] - pub fn is_read_vectored(&self) -> bool { - false - } - - pub fn read_at(&self, buf: &mut [u8], offset: u64) -> io::Result { - let res = - unsafe { self.synchronous_read(buf.as_mut_ptr().cast(), buf.len(), Some(offset)) }; - - match res { - Ok(read) => Ok(read), - Err(ref e) if e.raw_os_error() == Some(c::ERROR_HANDLE_EOF as i32) => Ok(0), - Err(e) => Err(e), - } - } - - pub fn read_buf(&self, mut cursor: BorrowedCursor<'_>) -> io::Result<()> { - let res = - unsafe { self.synchronous_read(cursor.as_mut().as_mut_ptr(), cursor.capacity(), None) }; - - match res { - Ok(read) => { - // Safety: `read` bytes were written to the initialized portion of the buffer - unsafe { - cursor.advance_unchecked(read); - } - Ok(()) - } - - // The special treatment of BrokenPipe is to deal with Windows - // pipe semantics, which yields this error when *reading* from - // a pipe after the other end has closed; we interpret that as - // EOF on the pipe. - Err(ref e) if e.kind() == ErrorKind::BrokenPipe => Ok(()), - - Err(e) => Err(e), - } - } - - pub unsafe fn read_overlapped( - &self, - buf: &mut [u8], - overlapped: *mut c::OVERLAPPED, - ) -> io::Result> { - let len = cmp::min(buf.len(), ::MAX as usize) as c::DWORD; - let mut amt = 0; - let res = - cvt(c::ReadFile(self.as_raw_handle(), buf.as_mut_ptr(), len, &mut amt, overlapped)); - match res { - Ok(_) => Ok(Some(amt as usize)), - Err(e) => { - if e.raw_os_error() == Some(c::ERROR_IO_PENDING as i32) { - Ok(None) - } else if e.raw_os_error() == Some(c::ERROR_BROKEN_PIPE as i32) { - Ok(Some(0)) - } else { - Err(e) - } - } - } - } - - pub fn overlapped_result( - &self, - overlapped: *mut c::OVERLAPPED, - wait: bool, - ) -> io::Result { - unsafe { - let mut bytes = 0; - let wait = if wait { c::TRUE } else { c::FALSE }; - let res = - cvt(c::GetOverlappedResult(self.as_raw_handle(), overlapped, &mut bytes, wait)); - match res { - Ok(_) => Ok(bytes as usize), - Err(e) => { - if e.raw_os_error() == Some(c::ERROR_HANDLE_EOF as i32) - || e.raw_os_error() == Some(c::ERROR_BROKEN_PIPE as i32) - { - Ok(0) - } else { - Err(e) - } - } - } - } - } - - pub fn cancel_io(&self) -> io::Result<()> { - unsafe { cvt(c::CancelIo(self.as_raw_handle())).map(drop) } - } - - pub fn write(&self, buf: &[u8]) -> io::Result { - self.synchronous_write(buf, None) - } - - pub fn write_vectored(&self, bufs: &[IoSlice<'_>]) -> io::Result { - crate::io::default_write_vectored(|buf| self.write(buf), bufs) - } - - #[inline] - pub fn is_write_vectored(&self) -> bool { - false - } - - pub fn write_at(&self, buf: &[u8], offset: u64) -> io::Result { - self.synchronous_write(buf, Some(offset)) - } - - pub fn try_clone(&self) -> io::Result { - Ok(Self(self.0.try_clone()?)) - } - - pub fn duplicate( - &self, - access: c::DWORD, - inherit: bool, - options: c::DWORD, - ) -> io::Result { - Ok(Self(self.0.as_handle().duplicate(access, inherit, options)?)) - } - - /// Performs a synchronous read. - /// - /// If the handle is opened for asynchronous I/O then this abort the process. - /// See #81357. - /// - /// If `offset` is `None` then the current file position is used. - unsafe fn synchronous_read( - &self, - buf: *mut mem::MaybeUninit, - len: usize, - offset: Option, - ) -> io::Result { - let mut io_status = c::IO_STATUS_BLOCK::PENDING; - - // The length is clamped at u32::MAX. - let len = cmp::min(len, c::DWORD::MAX as usize) as c::DWORD; - let status = c::NtReadFile( - self.as_handle(), - ptr::null_mut(), - None, - ptr::null_mut(), - &mut io_status, - buf, - len, - offset.map(|n| n as _).as_ref(), - None, - ); - - let status = if status == c::STATUS_PENDING { - c::WaitForSingleObject(self.as_raw_handle(), c::INFINITE); - io_status.status() - } else { - status - }; - match status { - // If the operation has not completed then abort the process. - // Doing otherwise means that the buffer and stack may be written to - // after this function returns. - c::STATUS_PENDING => rtabort!("I/O error: operation failed to complete synchronously"), - - // Return `Ok(0)` when there's nothing more to read. - c::STATUS_END_OF_FILE => Ok(0), - - // Success! - status if c::nt_success(status) => Ok(io_status.Information), - - status => { - let error = c::RtlNtStatusToDosError(status); - Err(io::Error::from_raw_os_error(error as _)) - } - } - } - - /// Performs a synchronous write. - /// - /// If the handle is opened for asynchronous I/O then this abort the process. - /// See #81357. - /// - /// If `offset` is `None` then the current file position is used. - fn synchronous_write(&self, buf: &[u8], offset: Option) -> io::Result { - let mut io_status = c::IO_STATUS_BLOCK::PENDING; - - // The length is clamped at u32::MAX. - let len = cmp::min(buf.len(), c::DWORD::MAX as usize) as c::DWORD; - let status = unsafe { - c::NtWriteFile( - self.as_handle(), - ptr::null_mut(), - None, - ptr::null_mut(), - &mut io_status, - buf.as_ptr(), - len, - offset.map(|n| n as _).as_ref(), - None, - ) - }; - let status = if status == c::STATUS_PENDING { - unsafe { c::WaitForSingleObject(self.as_raw_handle(), c::INFINITE) }; - io_status.status() - } else { - status - }; - match status { - // If the operation has not completed then abort the process. - // Doing otherwise means that the buffer may be read and the stack - // written to after this function returns. - c::STATUS_PENDING => rtabort!("I/O error: operation failed to complete synchronously"), - - // Success! - status if c::nt_success(status) => Ok(io_status.Information), - - status => { - let error = unsafe { c::RtlNtStatusToDosError(status) }; - Err(io::Error::from_raw_os_error(error as _)) - } - } - } -} - -impl<'a> Read for &'a Handle { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - (**self).read(buf) - } - - fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> io::Result<()> { - (**self).read_buf(buf) - } - - fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - (**self).read_vectored(bufs) - } - - #[inline] - fn is_read_vectored(&self) -> bool { - (**self).is_read_vectored() - } -} diff --git a/library/std/src/sys/pal/windows/handle/tests.rs b/library/std/src/sys/pal/windows/handle/tests.rs deleted file mode 100644 index d836dae4c305b..0000000000000 --- a/library/std/src/sys/pal/windows/handle/tests.rs +++ /dev/null @@ -1,22 +0,0 @@ -use crate::sys::pipe::{anon_pipe, Pipes}; -use crate::{thread, time}; - -/// Test the synchronous fallback for overlapped I/O. -#[test] -fn overlapped_handle_fallback() { - // Create some pipes. `ours` will be asynchronous. - let Pipes { ours, theirs } = anon_pipe(true, false).unwrap(); - - let async_readable = ours.into_handle(); - let sync_writeable = theirs.into_handle(); - - thread::scope(|_| { - thread::sleep(time::Duration::from_millis(100)); - sync_writeable.write(b"hello world!").unwrap(); - }); - - // The pipe buffer starts empty so reading won't complete synchronously unless - // our fallback path works. - let mut buffer = [0u8; 1024]; - async_readable.read(&mut buffer).unwrap(); -} diff --git a/library/std/src/sys/pal/windows/io.rs b/library/std/src/sys/pal/windows/io.rs deleted file mode 100644 index 77b8f3c410eb8..0000000000000 --- a/library/std/src/sys/pal/windows/io.rs +++ /dev/null @@ -1,147 +0,0 @@ -use crate::marker::PhantomData; -use crate::mem::size_of; -use crate::os::windows::io::{AsHandle, AsRawHandle, BorrowedHandle}; -use crate::slice; -use crate::sys::c; -use core::ffi::c_void; - -#[derive(Copy, Clone)] -#[repr(transparent)] -pub struct IoSlice<'a> { - vec: c::WSABUF, - _p: PhantomData<&'a [u8]>, -} - -impl<'a> IoSlice<'a> { - #[inline] - pub fn new(buf: &'a [u8]) -> IoSlice<'a> { - assert!(buf.len() <= c::ULONG::MAX as usize); - IoSlice { - vec: c::WSABUF { len: buf.len() as c::ULONG, buf: buf.as_ptr() as *mut u8 }, - _p: PhantomData, - } - } - - #[inline] - pub fn advance(&mut self, n: usize) { - if (self.vec.len as usize) < n { - panic!("advancing IoSlice beyond its length"); - } - - unsafe { - self.vec.len -= n as c::ULONG; - self.vec.buf = self.vec.buf.add(n); - } - } - - #[inline] - pub fn as_slice(&self) -> &[u8] { - unsafe { slice::from_raw_parts(self.vec.buf, self.vec.len as usize) } - } -} - -#[repr(transparent)] -pub struct IoSliceMut<'a> { - vec: c::WSABUF, - _p: PhantomData<&'a mut [u8]>, -} - -impl<'a> IoSliceMut<'a> { - #[inline] - pub fn new(buf: &'a mut [u8]) -> IoSliceMut<'a> { - assert!(buf.len() <= c::ULONG::MAX as usize); - IoSliceMut { - vec: c::WSABUF { len: buf.len() as c::ULONG, buf: buf.as_mut_ptr() }, - _p: PhantomData, - } - } - - #[inline] - pub fn advance(&mut self, n: usize) { - if (self.vec.len as usize) < n { - panic!("advancing IoSliceMut beyond its length"); - } - - unsafe { - self.vec.len -= n as c::ULONG; - self.vec.buf = self.vec.buf.add(n); - } - } - - #[inline] - pub fn as_slice(&self) -> &[u8] { - unsafe { slice::from_raw_parts(self.vec.buf, self.vec.len as usize) } - } - - #[inline] - pub fn as_mut_slice(&mut self) -> &mut [u8] { - unsafe { slice::from_raw_parts_mut(self.vec.buf, self.vec.len as usize) } - } -} - -pub fn is_terminal(h: &impl AsHandle) -> bool { - unsafe { handle_is_console(h.as_handle()) } -} - -unsafe fn handle_is_console(handle: BorrowedHandle<'_>) -> bool { - let handle = handle.as_raw_handle(); - - // A null handle means the process has no console. - if handle.is_null() { - return false; - } - - let mut out = 0; - if c::GetConsoleMode(handle, &mut out) != 0 { - // False positives aren't possible. If we got a console then we definitely have a console. - return true; - } - - // Otherwise, we fall back to an msys hack to see if we can detect the presence of a pty. - msys_tty_on(handle) -} - -unsafe fn msys_tty_on(handle: c::HANDLE) -> bool { - // Early return if the handle is not a pipe. - if c::GetFileType(handle) != c::FILE_TYPE_PIPE { - return false; - } - - /// Mirrors [`FILE_NAME_INFO`], giving it a fixed length that we can stack - /// allocate - /// - /// [`FILE_NAME_INFO`]: https://learn.microsoft.com/en-us/windows/win32/api/winbase/ns-winbase-file_name_info - #[repr(C)] - #[allow(non_snake_case)] - struct FILE_NAME_INFO { - FileNameLength: u32, - FileName: [u16; c::MAX_PATH as usize], - } - let mut name_info = FILE_NAME_INFO { FileNameLength: 0, FileName: [0; c::MAX_PATH as usize] }; - // Safety: buffer length is fixed. - let res = c::GetFileInformationByHandleEx( - handle, - c::FileNameInfo, - core::ptr::addr_of_mut!(name_info) as *mut c_void, - size_of::() as u32, - ); - if res == 0 { - return false; - } - - // Use `get` because `FileNameLength` can be out of range. - let s = match name_info.FileName.get(..name_info.FileNameLength as usize / 2) { - None => return false, - Some(s) => s, - }; - let name = String::from_utf16_lossy(s); - // Get the file name only. - let name = name.rsplit('\\').next().unwrap_or(&name); - // This checks whether 'pty' exists in the file name, which indicates that - // a pseudo-terminal is attached. To mitigate against false positives - // (e.g., an actual file name that contains 'pty'), we also require that - // the file name begins with either the strings 'msys-' or 'cygwin-'.) - let is_msys = name.starts_with("msys-") || name.starts_with("cygwin-"); - let is_pty = name.contains("-pty"); - is_msys && is_pty -} diff --git a/library/std/src/sys/pal/windows/mod.rs b/library/std/src/sys/pal/windows/mod.rs deleted file mode 100644 index 402a205977b07..0000000000000 --- a/library/std/src/sys/pal/windows/mod.rs +++ /dev/null @@ -1,362 +0,0 @@ -#![allow(missing_docs, nonstandard_style)] - -use crate::ffi::{OsStr, OsString}; -use crate::io::ErrorKind; -use crate::mem::MaybeUninit; -use crate::os::windows::ffi::{OsStrExt, OsStringExt}; -use crate::path::PathBuf; -use crate::sys::pal::windows::api::wide_str; -use crate::time::Duration; - -pub use self::rand::hashmap_random_keys; - -#[macro_use] -pub mod compat; - -mod api; - -pub mod alloc; -pub mod args; -pub mod c; -pub mod env; -pub mod fs; -#[cfg(not(target_vendor = "win7"))] -pub mod futex; -pub mod handle; -pub mod io; -pub mod net; -pub mod os; -pub mod pipe; -pub mod process; -pub mod rand; -pub mod stdio; -pub mod thread; -pub mod thread_local_dtor; -pub mod thread_local_key; -pub mod time; -cfg_if::cfg_if! { - if #[cfg(not(target_vendor = "uwp"))] { - pub mod stack_overflow; - } else { - pub mod stack_overflow_uwp; - pub use self::stack_overflow_uwp as stack_overflow; - } -} - -/// Map a Result to io::Result. -trait IoResult { - fn io_result(self) -> crate::io::Result; -} -impl IoResult for Result { - fn io_result(self) -> crate::io::Result { - self.map_err(|e| crate::io::Error::from_raw_os_error(e.code as i32)) - } -} - -// SAFETY: must be called only once during runtime initialization. -// NOTE: this is not guaranteed to run, for example when Rust code is called externally. -pub unsafe fn init(_argc: isize, _argv: *const *const u8, _sigpipe: u8) { - stack_overflow::init(); - - // Normally, `thread::spawn` will call `Thread::set_name` but since this thread already - // exists, we have to call it ourselves. - thread::Thread::set_name_wide(wide_str!("main")); -} - -// SAFETY: must be called only once during runtime cleanup. -// NOTE: this is not guaranteed to run, for example when the program aborts. -pub unsafe fn cleanup() { - net::cleanup(); -} - -#[inline] -pub fn is_interrupted(_errno: i32) -> bool { - false -} - -pub fn decode_error_kind(errno: i32) -> ErrorKind { - use ErrorKind::*; - - match errno as c::DWORD { - c::ERROR_ACCESS_DENIED => return PermissionDenied, - c::ERROR_ALREADY_EXISTS => return AlreadyExists, - c::ERROR_FILE_EXISTS => return AlreadyExists, - c::ERROR_BROKEN_PIPE => return BrokenPipe, - c::ERROR_FILE_NOT_FOUND - | c::ERROR_PATH_NOT_FOUND - | c::ERROR_INVALID_DRIVE - | c::ERROR_BAD_NETPATH - | c::ERROR_BAD_NET_NAME => return NotFound, - c::ERROR_NO_DATA => return BrokenPipe, - c::ERROR_INVALID_NAME | c::ERROR_BAD_PATHNAME => return InvalidFilename, - c::ERROR_INVALID_PARAMETER => return InvalidInput, - c::ERROR_NOT_ENOUGH_MEMORY | c::ERROR_OUTOFMEMORY => return OutOfMemory, - c::ERROR_SEM_TIMEOUT - | c::WAIT_TIMEOUT - | c::ERROR_DRIVER_CANCEL_TIMEOUT - | c::ERROR_OPERATION_ABORTED - | c::ERROR_SERVICE_REQUEST_TIMEOUT - | c::ERROR_COUNTER_TIMEOUT - | c::ERROR_TIMEOUT - | c::ERROR_RESOURCE_CALL_TIMED_OUT - | c::ERROR_CTX_MODEM_RESPONSE_TIMEOUT - | c::ERROR_CTX_CLIENT_QUERY_TIMEOUT - | c::FRS_ERR_SYSVOL_POPULATE_TIMEOUT - | c::ERROR_DS_TIMELIMIT_EXCEEDED - | c::DNS_ERROR_RECORD_TIMED_OUT - | c::ERROR_IPSEC_IKE_TIMED_OUT - | c::ERROR_RUNLEVEL_SWITCH_TIMEOUT - | c::ERROR_RUNLEVEL_SWITCH_AGENT_TIMEOUT => return TimedOut, - c::ERROR_CALL_NOT_IMPLEMENTED => return Unsupported, - c::ERROR_HOST_UNREACHABLE => return HostUnreachable, - c::ERROR_NETWORK_UNREACHABLE => return NetworkUnreachable, - c::ERROR_DIRECTORY => return NotADirectory, - c::ERROR_DIRECTORY_NOT_SUPPORTED => return IsADirectory, - c::ERROR_DIR_NOT_EMPTY => return DirectoryNotEmpty, - c::ERROR_WRITE_PROTECT => return ReadOnlyFilesystem, - c::ERROR_DISK_FULL | c::ERROR_HANDLE_DISK_FULL => return StorageFull, - c::ERROR_SEEK_ON_DEVICE => return NotSeekable, - c::ERROR_DISK_QUOTA_EXCEEDED => return FilesystemQuotaExceeded, - c::ERROR_FILE_TOO_LARGE => return FileTooLarge, - c::ERROR_BUSY => return ResourceBusy, - c::ERROR_POSSIBLE_DEADLOCK => return Deadlock, - c::ERROR_NOT_SAME_DEVICE => return CrossesDevices, - c::ERROR_TOO_MANY_LINKS => return TooManyLinks, - c::ERROR_FILENAME_EXCED_RANGE => return InvalidFilename, - _ => {} - } - - match errno { - c::WSAEACCES => PermissionDenied, - c::WSAEADDRINUSE => AddrInUse, - c::WSAEADDRNOTAVAIL => AddrNotAvailable, - c::WSAECONNABORTED => ConnectionAborted, - c::WSAECONNREFUSED => ConnectionRefused, - c::WSAECONNRESET => ConnectionReset, - c::WSAEINVAL => InvalidInput, - c::WSAENOTCONN => NotConnected, - c::WSAEWOULDBLOCK => WouldBlock, - c::WSAETIMEDOUT => TimedOut, - c::WSAEHOSTUNREACH => HostUnreachable, - c::WSAENETDOWN => NetworkDown, - c::WSAENETUNREACH => NetworkUnreachable, - - _ => Uncategorized, - } -} - -pub fn unrolled_find_u16s(needle: u16, haystack: &[u16]) -> Option { - let ptr = haystack.as_ptr(); - let mut start = haystack; - - // For performance reasons unfold the loop eight times. - while start.len() >= 8 { - macro_rules! if_return { - ($($n:literal,)+) => { - $( - if start[$n] == needle { - return Some(((&start[$n] as *const u16).addr() - ptr.addr()) / 2); - } - )+ - } - } - - if_return!(0, 1, 2, 3, 4, 5, 6, 7,); - - start = &start[8..]; - } - - for c in start { - if *c == needle { - return Some(((c as *const u16).addr() - ptr.addr()) / 2); - } - } - None -} - -pub fn to_u16s>(s: S) -> crate::io::Result> { - fn inner(s: &OsStr) -> crate::io::Result> { - // Most paths are ASCII, so reserve capacity for as much as there are bytes - // in the OsStr plus one for the null-terminating character. We are not - // wasting bytes here as paths created by this function are primarily used - // in an ephemeral fashion. - let mut maybe_result = Vec::with_capacity(s.len() + 1); - maybe_result.extend(s.encode_wide()); - - if unrolled_find_u16s(0, &maybe_result).is_some() { - return Err(crate::io::const_io_error!( - ErrorKind::InvalidInput, - "strings passed to WinAPI cannot contain NULs", - )); - } - maybe_result.push(0); - Ok(maybe_result) - } - inner(s.as_ref()) -} - -// Many Windows APIs follow a pattern of where we hand a buffer and then they -// will report back to us how large the buffer should be or how many bytes -// currently reside in the buffer. This function is an abstraction over these -// functions by making them easier to call. -// -// The first callback, `f1`, is passed a (pointer, len) pair which can be -// passed to a syscall. The `ptr` is valid for `len` items (u16 in this case). -// The closure is expected to: -// - On success, return the actual length of the written data *without* the null terminator. -// This can be 0. In this case the last_error must be left unchanged. -// - On insufficient buffer space, -// - either return the required length *with* the null terminator, -// - or set the last-error to ERROR_INSUFFICIENT_BUFFER and return `len`. -// - On other failure, return 0 and set last_error. -// -// This is how most but not all syscalls indicate the required buffer space. -// Other syscalls may need translation to match this protocol. -// -// Once the syscall has completed (errors bail out early) the second closure is -// passed the data which has been read from the syscall. The return value -// from this closure is then the return value of the function. -pub fn fill_utf16_buf(mut f1: F1, f2: F2) -> crate::io::Result -where - F1: FnMut(*mut u16, c::DWORD) -> c::DWORD, - F2: FnOnce(&[u16]) -> T, -{ - // Start off with a stack buf but then spill over to the heap if we end up - // needing more space. - // - // This initial size also works around `GetFullPathNameW` returning - // incorrect size hints for some short paths: - // https://github.com/dylni/normpath/issues/5 - let mut stack_buf: [MaybeUninit; 512] = MaybeUninit::uninit_array(); - let mut heap_buf: Vec> = Vec::new(); - unsafe { - let mut n = stack_buf.len(); - loop { - let buf = if n <= stack_buf.len() { - &mut stack_buf[..] - } else { - let extra = n - heap_buf.len(); - heap_buf.reserve(extra); - // We used `reserve` and not `reserve_exact`, so in theory we - // may have gotten more than requested. If so, we'd like to use - // it... so long as we won't cause overflow. - n = heap_buf.capacity().min(c::DWORD::MAX as usize); - // Safety: MaybeUninit does not need initialization - heap_buf.set_len(n); - &mut heap_buf[..] - }; - - // This function is typically called on windows API functions which - // will return the correct length of the string, but these functions - // also return the `0` on error. In some cases, however, the - // returned "correct length" may actually be 0! - // - // To handle this case we call `SetLastError` to reset it to 0 and - // then check it again if we get the "0 error value". If the "last - // error" is still 0 then we interpret it as a 0 length buffer and - // not an actual error. - c::SetLastError(0); - let k = match f1(buf.as_mut_ptr().cast::(), n as c::DWORD) { - 0 if api::get_last_error().code == 0 => 0, - 0 => return Err(crate::io::Error::last_os_error()), - n => n, - } as usize; - if k == n && api::get_last_error().code == c::ERROR_INSUFFICIENT_BUFFER { - n = n.saturating_mul(2).min(c::DWORD::MAX as usize); - } else if k > n { - n = k; - } else if k == n { - // It is impossible to reach this point. - // On success, k is the returned string length excluding the null. - // On failure, k is the required buffer length including the null. - // Therefore k never equals n. - unreachable!(); - } else { - // Safety: First `k` values are initialized. - let slice: &[u16] = MaybeUninit::slice_assume_init_ref(&buf[..k]); - return Ok(f2(slice)); - } - } - } -} - -pub fn os2path(s: &[u16]) -> PathBuf { - PathBuf::from(OsString::from_wide(s)) -} - -pub fn truncate_utf16_at_nul(v: &[u16]) -> &[u16] { - match unrolled_find_u16s(0, v) { - // don't include the 0 - Some(i) => &v[..i], - None => v, - } -} - -pub trait IsZero { - fn is_zero(&self) -> bool; -} - -macro_rules! impl_is_zero { - ($($t:ident)*) => ($(impl IsZero for $t { - fn is_zero(&self) -> bool { - *self == 0 - } - })*) -} - -impl_is_zero! { i8 i16 i32 i64 isize u8 u16 u32 u64 usize } - -pub fn cvt(i: I) -> crate::io::Result { - if i.is_zero() { Err(crate::io::Error::last_os_error()) } else { Ok(i) } -} - -pub fn dur2timeout(dur: Duration) -> c::DWORD { - // Note that a duration is a (u64, u32) (seconds, nanoseconds) pair, and the - // timeouts in windows APIs are typically u32 milliseconds. To translate, we - // have two pieces to take care of: - // - // * Nanosecond precision is rounded up - // * Greater than u32::MAX milliseconds (50 days) is rounded up to INFINITE - // (never time out). - dur.as_secs() - .checked_mul(1000) - .and_then(|ms| ms.checked_add((dur.subsec_nanos() as u64) / 1_000_000)) - .and_then(|ms| ms.checked_add(if dur.subsec_nanos() % 1_000_000 > 0 { 1 } else { 0 })) - .map(|ms| if ms > ::MAX as u64 { c::INFINITE } else { ms as c::DWORD }) - .unwrap_or(c::INFINITE) -} - -/// Use `__fastfail` to abort the process -/// -/// This is the same implementation as in libpanic_abort's `__rust_start_panic`. See -/// that function for more information on `__fastfail` -#[cfg(not(miri))] // inline assembly does not work in Miri -pub fn abort_internal() -> ! { - unsafe { - cfg_if::cfg_if! { - if #[cfg(any(target_arch = "x86", target_arch = "x86_64"))] { - core::arch::asm!("int $$0x29", in("ecx") c::FAST_FAIL_FATAL_APP_EXIT, options(noreturn, nostack)); - } else if #[cfg(all(target_arch = "arm", target_feature = "thumb-mode"))] { - core::arch::asm!(".inst 0xDEFB", in("r0") c::FAST_FAIL_FATAL_APP_EXIT, options(noreturn, nostack)); - } else if #[cfg(any(target_arch = "aarch64", target_arch = "arm64ec"))] { - core::arch::asm!("brk 0xF003", in("x0") c::FAST_FAIL_FATAL_APP_EXIT, options(noreturn, nostack)); - } else { - core::intrinsics::abort(); - } - } - } -} - -// miri is sensitive to changes here so check that miri is happy if touching this -#[cfg(miri)] -pub fn abort_internal() -> ! { - crate::intrinsics::abort(); -} - -/// Align the inner value to 8 bytes. -/// -/// This is enough for almost all of the buffers we're likely to work with in -/// the Windows APIs we use. -#[repr(C, align(8))] -#[derive(Copy, Clone)] -pub(crate) struct Align8(pub T); diff --git a/library/std/src/sys/pal/windows/net.rs b/library/std/src/sys/pal/windows/net.rs deleted file mode 100644 index 9e15b15a3513a..0000000000000 --- a/library/std/src/sys/pal/windows/net.rs +++ /dev/null @@ -1,491 +0,0 @@ -#![unstable(issue = "none", feature = "windows_net")] - -use crate::cmp; -use crate::io::{self, BorrowedBuf, BorrowedCursor, IoSlice, IoSliceMut, Read}; -use crate::mem; -use crate::net::{Shutdown, SocketAddr}; -use crate::os::windows::io::{ - AsRawSocket, AsSocket, BorrowedSocket, FromRawSocket, IntoRawSocket, OwnedSocket, RawSocket, -}; -use crate::ptr; -use crate::sync::OnceLock; -use crate::sys; -use crate::sys::c; -use crate::sys_common::net; -use crate::sys_common::{AsInner, FromInner, IntoInner}; -use crate::time::Duration; - -use core::ffi::{c_int, c_long, c_ulong, c_ushort}; - -pub type wrlen_t = i32; - -pub mod netc { - pub use crate::sys::c::ADDRESS_FAMILY as sa_family_t; - pub use crate::sys::c::ADDRINFOA as addrinfo; - pub use crate::sys::c::SOCKADDR as sockaddr; - pub use crate::sys::c::SOCKADDR_STORAGE_LH as sockaddr_storage; - pub use crate::sys::c::*; -} - -pub struct Socket(OwnedSocket); - -static WSA_CLEANUP: OnceLock i32> = OnceLock::new(); - -/// Checks whether the Windows socket interface has been started already, and -/// if not, starts it. -pub fn init() { - let _ = WSA_CLEANUP.get_or_init(|| unsafe { - let mut data: c::WSADATA = mem::zeroed(); - let ret = c::WSAStartup( - 0x202, // version 2.2 - &mut data, - ); - assert_eq!(ret, 0); - - // Only register `WSACleanup` if `WSAStartup` is actually ever called. - // Workaround to prevent linking to `WS2_32.dll` when no network functionality is used. - // See issue #85441. - c::WSACleanup - }); -} - -pub fn cleanup() { - // only perform cleanup if network functionality was actually initialized - if let Some(cleanup) = WSA_CLEANUP.get() { - unsafe { - cleanup(); - } - } -} - -/// Returns the last error from the Windows socket interface. -fn last_error() -> io::Error { - io::Error::from_raw_os_error(unsafe { c::WSAGetLastError() }) -} - -#[doc(hidden)] -pub trait IsMinusOne { - fn is_minus_one(&self) -> bool; -} - -macro_rules! impl_is_minus_one { - ($($t:ident)*) => ($(impl IsMinusOne for $t { - fn is_minus_one(&self) -> bool { - *self == -1 - } - })*) -} - -impl_is_minus_one! { i8 i16 i32 i64 isize } - -/// Checks if the signed integer is the Windows constant `SOCKET_ERROR` (-1) -/// and if so, returns the last error from the Windows socket interface. This -/// function must be called before another call to the socket API is made. -pub fn cvt(t: T) -> io::Result { - if t.is_minus_one() { Err(last_error()) } else { Ok(t) } -} - -/// A variant of `cvt` for `getaddrinfo` which return 0 for a success. -pub fn cvt_gai(err: c_int) -> io::Result<()> { - if err == 0 { Ok(()) } else { Err(last_error()) } -} - -/// Just to provide the same interface as sys/pal/unix/net.rs -pub fn cvt_r(mut f: F) -> io::Result -where - T: IsMinusOne, - F: FnMut() -> T, -{ - cvt(f()) -} - -impl Socket { - pub fn new(addr: &SocketAddr, ty: c_int) -> io::Result { - let family = match *addr { - SocketAddr::V4(..) => c::AF_INET, - SocketAddr::V6(..) => c::AF_INET6, - }; - let socket = unsafe { - c::WSASocketW( - family, - ty, - 0, - ptr::null_mut(), - 0, - c::WSA_FLAG_OVERLAPPED | c::WSA_FLAG_NO_HANDLE_INHERIT, - ) - }; - - if socket != c::INVALID_SOCKET { - unsafe { Ok(Self::from_raw(socket)) } - } else { - let error = unsafe { c::WSAGetLastError() }; - - if error != c::WSAEPROTOTYPE && error != c::WSAEINVAL { - return Err(io::Error::from_raw_os_error(error)); - } - - let socket = - unsafe { c::WSASocketW(family, ty, 0, ptr::null_mut(), 0, c::WSA_FLAG_OVERLAPPED) }; - - if socket == c::INVALID_SOCKET { - return Err(last_error()); - } - - unsafe { - let socket = Self::from_raw(socket); - socket.0.set_no_inherit()?; - Ok(socket) - } - } - } - - pub fn connect(&self, addr: &SocketAddr) -> io::Result<()> { - let (addr, len) = addr.into_inner(); - let result = unsafe { c::connect(self.as_raw(), addr.as_ptr(), len) }; - cvt(result).map(drop) - } - - pub fn connect_timeout(&self, addr: &SocketAddr, timeout: Duration) -> io::Result<()> { - self.set_nonblocking(true)?; - let result = self.connect(addr); - self.set_nonblocking(false)?; - - match result { - Err(ref error) if error.kind() == io::ErrorKind::WouldBlock => { - if timeout.as_secs() == 0 && timeout.subsec_nanos() == 0 { - return Err(io::Error::ZERO_TIMEOUT); - } - - let mut timeout = c::timeval { - tv_sec: cmp::min(timeout.as_secs(), c_long::MAX as u64) as c_long, - tv_usec: timeout.subsec_micros() as c_long, - }; - - if timeout.tv_sec == 0 && timeout.tv_usec == 0 { - timeout.tv_usec = 1; - } - - let fds = { - let mut fds = unsafe { mem::zeroed::() }; - fds.fd_count = 1; - fds.fd_array[0] = self.as_raw(); - fds - }; - - let mut writefds = fds; - let mut errorfds = fds; - - let count = { - let result = unsafe { - c::select(1, ptr::null_mut(), &mut writefds, &mut errorfds, &timeout) - }; - cvt(result)? - }; - - match count { - 0 => Err(io::const_io_error!(io::ErrorKind::TimedOut, "connection timed out")), - _ => { - if writefds.fd_count != 1 { - if let Some(e) = self.take_error()? { - return Err(e); - } - } - - Ok(()) - } - } - } - _ => result, - } - } - - pub fn accept(&self, storage: *mut c::SOCKADDR, len: *mut c_int) -> io::Result { - let socket = unsafe { c::accept(self.as_raw(), storage, len) }; - - match socket { - c::INVALID_SOCKET => Err(last_error()), - _ => unsafe { Ok(Self::from_raw(socket)) }, - } - } - - pub fn duplicate(&self) -> io::Result { - Ok(Self(self.0.try_clone()?)) - } - - fn recv_with_flags(&self, mut buf: BorrowedCursor<'_>, flags: c_int) -> io::Result<()> { - // On unix when a socket is shut down all further reads return 0, so we - // do the same on windows to map a shut down socket to returning EOF. - let length = cmp::min(buf.capacity(), i32::MAX as usize) as i32; - let result = - unsafe { c::recv(self.as_raw(), buf.as_mut().as_mut_ptr() as *mut _, length, flags) }; - - match result { - c::SOCKET_ERROR => { - let error = unsafe { c::WSAGetLastError() }; - - if error == c::WSAESHUTDOWN { - Ok(()) - } else { - Err(io::Error::from_raw_os_error(error)) - } - } - _ => { - unsafe { buf.advance_unchecked(result as usize) }; - Ok(()) - } - } - } - - pub fn read(&self, buf: &mut [u8]) -> io::Result { - let mut buf = BorrowedBuf::from(buf); - self.recv_with_flags(buf.unfilled(), 0)?; - Ok(buf.len()) - } - - pub fn read_buf(&self, buf: BorrowedCursor<'_>) -> io::Result<()> { - self.recv_with_flags(buf, 0) - } - - pub fn read_vectored(&self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - // On unix when a socket is shut down all further reads return 0, so we - // do the same on windows to map a shut down socket to returning EOF. - let length = cmp::min(bufs.len(), c::DWORD::MAX as usize) as c::DWORD; - let mut nread = 0; - let mut flags = 0; - let result = unsafe { - c::WSARecv( - self.as_raw(), - bufs.as_mut_ptr() as *mut c::WSABUF, - length, - &mut nread, - &mut flags, - ptr::null_mut(), - None, - ) - }; - - match result { - 0 => Ok(nread as usize), - _ => { - let error = unsafe { c::WSAGetLastError() }; - - if error == c::WSAESHUTDOWN { - Ok(0) - } else { - Err(io::Error::from_raw_os_error(error)) - } - } - } - } - - #[inline] - pub fn is_read_vectored(&self) -> bool { - true - } - - pub fn peek(&self, buf: &mut [u8]) -> io::Result { - let mut buf = BorrowedBuf::from(buf); - self.recv_with_flags(buf.unfilled(), c::MSG_PEEK)?; - Ok(buf.len()) - } - - fn recv_from_with_flags( - &self, - buf: &mut [u8], - flags: c_int, - ) -> io::Result<(usize, SocketAddr)> { - let mut storage = unsafe { mem::zeroed::() }; - let mut addrlen = mem::size_of_val(&storage) as c::socklen_t; - let length = cmp::min(buf.len(), ::MAX as usize) as wrlen_t; - - // On unix when a socket is shut down all further reads return 0, so we - // do the same on windows to map a shut down socket to returning EOF. - let result = unsafe { - c::recvfrom( - self.as_raw(), - buf.as_mut_ptr() as *mut _, - length, - flags, - core::ptr::addr_of_mut!(storage) as *mut _, - &mut addrlen, - ) - }; - - match result { - c::SOCKET_ERROR => { - let error = unsafe { c::WSAGetLastError() }; - - if error == c::WSAESHUTDOWN { - Ok((0, net::sockaddr_to_addr(&storage, addrlen as usize)?)) - } else { - Err(io::Error::from_raw_os_error(error)) - } - } - _ => Ok((result as usize, net::sockaddr_to_addr(&storage, addrlen as usize)?)), - } - } - - pub fn recv_from(&self, buf: &mut [u8]) -> io::Result<(usize, SocketAddr)> { - self.recv_from_with_flags(buf, 0) - } - - pub fn peek_from(&self, buf: &mut [u8]) -> io::Result<(usize, SocketAddr)> { - self.recv_from_with_flags(buf, c::MSG_PEEK) - } - - pub fn write_vectored(&self, bufs: &[IoSlice<'_>]) -> io::Result { - let length = cmp::min(bufs.len(), c::DWORD::MAX as usize) as c::DWORD; - let mut nwritten = 0; - let result = unsafe { - c::WSASend( - self.as_raw(), - bufs.as_ptr() as *const c::WSABUF as *mut _, - length, - &mut nwritten, - 0, - ptr::null_mut(), - None, - ) - }; - cvt(result).map(|_| nwritten as usize) - } - - #[inline] - pub fn is_write_vectored(&self) -> bool { - true - } - - pub fn set_timeout(&self, dur: Option, kind: c_int) -> io::Result<()> { - let timeout = match dur { - Some(dur) => { - let timeout = sys::dur2timeout(dur); - if timeout == 0 { - return Err(io::Error::ZERO_TIMEOUT); - } - timeout - } - None => 0, - }; - net::setsockopt(self, c::SOL_SOCKET, kind, timeout) - } - - pub fn timeout(&self, kind: c_int) -> io::Result> { - let raw: c::DWORD = net::getsockopt(self, c::SOL_SOCKET, kind)?; - if raw == 0 { - Ok(None) - } else { - let secs = raw / 1000; - let nsec = (raw % 1000) * 1000000; - Ok(Some(Duration::new(secs as u64, nsec as u32))) - } - } - - pub fn shutdown(&self, how: Shutdown) -> io::Result<()> { - let how = match how { - Shutdown::Write => c::SD_SEND, - Shutdown::Read => c::SD_RECEIVE, - Shutdown::Both => c::SD_BOTH, - }; - let result = unsafe { c::shutdown(self.as_raw(), how) }; - cvt(result).map(drop) - } - - pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> { - let mut nonblocking = nonblocking as c_ulong; - let result = - unsafe { c::ioctlsocket(self.as_raw(), c::FIONBIO as c_int, &mut nonblocking) }; - cvt(result).map(drop) - } - - pub fn set_linger(&self, linger: Option) -> io::Result<()> { - let linger = c::linger { - l_onoff: linger.is_some() as c_ushort, - l_linger: linger.unwrap_or_default().as_secs() as c_ushort, - }; - - net::setsockopt(self, c::SOL_SOCKET, c::SO_LINGER, linger) - } - - pub fn linger(&self) -> io::Result> { - let val: c::linger = net::getsockopt(self, c::SOL_SOCKET, c::SO_LINGER)?; - - Ok((val.l_onoff != 0).then(|| Duration::from_secs(val.l_linger as u64))) - } - - pub fn set_nodelay(&self, nodelay: bool) -> io::Result<()> { - net::setsockopt(self, c::IPPROTO_TCP, c::TCP_NODELAY, nodelay as c::BOOL) - } - - pub fn nodelay(&self) -> io::Result { - let raw: c::BOOL = net::getsockopt(self, c::IPPROTO_TCP, c::TCP_NODELAY)?; - Ok(raw != 0) - } - - pub fn take_error(&self) -> io::Result> { - let raw: c_int = net::getsockopt(self, c::SOL_SOCKET, c::SO_ERROR)?; - if raw == 0 { Ok(None) } else { Ok(Some(io::Error::from_raw_os_error(raw as i32))) } - } - - // This is used by sys_common code to abstract over Windows and Unix. - pub fn as_raw(&self) -> c::SOCKET { - debug_assert_eq!(mem::size_of::(), mem::size_of::()); - debug_assert_eq!(mem::align_of::(), mem::align_of::()); - self.as_inner().as_raw_socket() as c::SOCKET - } - pub unsafe fn from_raw(raw: c::SOCKET) -> Self { - debug_assert_eq!(mem::size_of::(), mem::size_of::()); - debug_assert_eq!(mem::align_of::(), mem::align_of::()); - Self::from_raw_socket(raw as RawSocket) - } -} - -#[unstable(reason = "not public", issue = "none", feature = "fd_read")] -impl<'a> Read for &'a Socket { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - (**self).read(buf) - } -} - -impl AsInner for Socket { - #[inline] - fn as_inner(&self) -> &OwnedSocket { - &self.0 - } -} - -impl FromInner for Socket { - fn from_inner(sock: OwnedSocket) -> Socket { - Socket(sock) - } -} - -impl IntoInner for Socket { - fn into_inner(self) -> OwnedSocket { - self.0 - } -} - -impl AsSocket for Socket { - fn as_socket(&self) -> BorrowedSocket<'_> { - self.0.as_socket() - } -} - -impl AsRawSocket for Socket { - fn as_raw_socket(&self) -> RawSocket { - self.0.as_raw_socket() - } -} - -impl IntoRawSocket for Socket { - fn into_raw_socket(self) -> RawSocket { - self.0.into_raw_socket() - } -} - -impl FromRawSocket for Socket { - unsafe fn from_raw_socket(raw_socket: RawSocket) -> Self { - Self(FromRawSocket::from_raw_socket(raw_socket)) - } -} diff --git a/library/std/src/sys/pal/windows/os.rs b/library/std/src/sys/pal/windows/os.rs deleted file mode 100644 index 64d8b72aed282..0000000000000 --- a/library/std/src/sys/pal/windows/os.rs +++ /dev/null @@ -1,390 +0,0 @@ -//! Implementation of `std::os` functionality for Windows. - -#![allow(nonstandard_style)] - -#[cfg(test)] -mod tests; - -use crate::os::windows::prelude::*; - -use crate::error::Error as StdError; -use crate::ffi::{OsStr, OsString}; -use crate::fmt; -use crate::io; -use crate::os::windows::ffi::EncodeWide; -use crate::path::{self, PathBuf}; -use crate::ptr; -use crate::slice; -use crate::sys::{c, cvt}; - -use super::{api, to_u16s}; - -pub fn errno() -> i32 { - api::get_last_error().code as i32 -} - -/// Gets a detailed string description for the given error number. -pub fn error_string(mut errnum: i32) -> String { - let mut buf = [0 as c::WCHAR; 2048]; - - unsafe { - let mut module = ptr::null_mut(); - let mut flags = 0; - - // NTSTATUS errors may be encoded as HRESULT, which may returned from - // GetLastError. For more information about Windows error codes, see - // `[MS-ERREF]`: https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-erref/0642cb2f-2075-4469-918c-4441e69c548a - if (errnum & c::FACILITY_NT_BIT as i32) != 0 { - // format according to https://support.microsoft.com/en-us/help/259693 - const NTDLL_DLL: &[u16] = &[ - 'N' as _, 'T' as _, 'D' as _, 'L' as _, 'L' as _, '.' as _, 'D' as _, 'L' as _, - 'L' as _, 0, - ]; - module = c::GetModuleHandleW(NTDLL_DLL.as_ptr()); - - if !module.is_null() { - errnum ^= c::FACILITY_NT_BIT as i32; - flags = c::FORMAT_MESSAGE_FROM_HMODULE; - } - } - - let res = c::FormatMessageW( - flags | c::FORMAT_MESSAGE_FROM_SYSTEM | c::FORMAT_MESSAGE_IGNORE_INSERTS, - module, - errnum as c::DWORD, - 0, - buf.as_mut_ptr(), - buf.len() as c::DWORD, - ptr::null(), - ) as usize; - if res == 0 { - // Sometimes FormatMessageW can fail e.g., system doesn't like 0 as langId, - let fm_err = errno(); - return format!("OS Error {errnum} (FormatMessageW() returned error {fm_err})"); - } - - match String::from_utf16(&buf[..res]) { - Ok(mut msg) => { - // Trim trailing CRLF inserted by FormatMessageW - let len = msg.trim_end().len(); - msg.truncate(len); - msg - } - Err(..) => format!( - "OS Error {} (FormatMessageW() returned \ - invalid UTF-16)", - errnum - ), - } - } -} - -pub struct Env { - base: c::LPWCH, - iter: EnvIterator, -} - -// FIXME(https://github.com/rust-lang/rust/issues/114583): Remove this when ::fmt matches ::fmt. -pub struct EnvStrDebug<'a> { - iter: &'a EnvIterator, -} - -impl fmt::Debug for EnvStrDebug<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let Self { iter } = self; - let iter: EnvIterator = (*iter).clone(); - let mut list = f.debug_list(); - for (a, b) in iter { - list.entry(&(a.to_str().unwrap(), b.to_str().unwrap())); - } - list.finish() - } -} - -impl Env { - pub fn str_debug(&self) -> impl fmt::Debug + '_ { - let Self { base: _, iter } = self; - EnvStrDebug { iter } - } -} - -impl fmt::Debug for Env { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let Self { base: _, iter } = self; - f.debug_list().entries(iter.clone()).finish() - } -} - -impl Iterator for Env { - type Item = (OsString, OsString); - - fn next(&mut self) -> Option<(OsString, OsString)> { - let Self { base: _, iter } = self; - iter.next() - } -} - -#[derive(Clone)] -struct EnvIterator(c::LPWCH); - -impl Iterator for EnvIterator { - type Item = (OsString, OsString); - - fn next(&mut self) -> Option<(OsString, OsString)> { - let Self(cur) = self; - loop { - unsafe { - if **cur == 0 { - return None; - } - let p = *cur as *const u16; - let mut len = 0; - while *p.add(len) != 0 { - len += 1; - } - let s = slice::from_raw_parts(p, len); - *cur = cur.add(len + 1); - - // Windows allows environment variables to start with an equals - // symbol (in any other position, this is the separator between - // variable name and value). Since`s` has at least length 1 at - // this point (because the empty string terminates the array of - // environment variables), we can safely slice. - let pos = match s[1..].iter().position(|&u| u == b'=' as u16).map(|p| p + 1) { - Some(p) => p, - None => continue, - }; - return Some(( - OsStringExt::from_wide(&s[..pos]), - OsStringExt::from_wide(&s[pos + 1..]), - )); - } - } - } -} - -impl Drop for Env { - fn drop(&mut self) { - unsafe { - c::FreeEnvironmentStringsW(self.base); - } - } -} - -pub fn env() -> Env { - unsafe { - let ch = c::GetEnvironmentStringsW(); - if ch.is_null() { - panic!("failure getting env string from OS: {}", io::Error::last_os_error()); - } - Env { base: ch, iter: EnvIterator(ch) } - } -} - -pub struct SplitPaths<'a> { - data: EncodeWide<'a>, - must_yield: bool, -} - -pub fn split_paths(unparsed: &OsStr) -> SplitPaths<'_> { - SplitPaths { data: unparsed.encode_wide(), must_yield: true } -} - -impl<'a> Iterator for SplitPaths<'a> { - type Item = PathBuf; - fn next(&mut self) -> Option { - // On Windows, the PATH environment variable is semicolon separated. - // Double quotes are used as a way of introducing literal semicolons - // (since c:\some;dir is a valid Windows path). Double quotes are not - // themselves permitted in path names, so there is no way to escape a - // double quote. Quoted regions can appear in arbitrary locations, so - // - // c:\foo;c:\som"e;di"r;c:\bar - // - // Should parse as [c:\foo, c:\some;dir, c:\bar]. - // - // (The above is based on testing; there is no clear reference available - // for the grammar.) - - let must_yield = self.must_yield; - self.must_yield = false; - - let mut in_progress = Vec::new(); - let mut in_quote = false; - for b in self.data.by_ref() { - if b == '"' as u16 { - in_quote = !in_quote; - } else if b == ';' as u16 && !in_quote { - self.must_yield = true; - break; - } else { - in_progress.push(b) - } - } - - if !must_yield && in_progress.is_empty() { - None - } else { - Some(super::os2path(&in_progress)) - } - } -} - -#[derive(Debug)] -pub struct JoinPathsError; - -pub fn join_paths(paths: I) -> Result -where - I: Iterator, - T: AsRef, -{ - let mut joined = Vec::new(); - let sep = b';' as u16; - - for (i, path) in paths.enumerate() { - let path = path.as_ref(); - if i > 0 { - joined.push(sep) - } - let v = path.encode_wide().collect::>(); - if v.contains(&(b'"' as u16)) { - return Err(JoinPathsError); - } else if v.contains(&sep) { - joined.push(b'"' as u16); - joined.extend_from_slice(&v[..]); - joined.push(b'"' as u16); - } else { - joined.extend_from_slice(&v[..]); - } - } - - Ok(OsStringExt::from_wide(&joined[..])) -} - -impl fmt::Display for JoinPathsError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - "path segment contains `\"`".fmt(f) - } -} - -impl StdError for JoinPathsError { - #[allow(deprecated)] - fn description(&self) -> &str { - "failed to join paths" - } -} - -pub fn current_exe() -> io::Result { - super::fill_utf16_buf( - |buf, sz| unsafe { c::GetModuleFileNameW(ptr::null_mut(), buf, sz) }, - super::os2path, - ) -} - -pub fn getcwd() -> io::Result { - super::fill_utf16_buf(|buf, sz| unsafe { c::GetCurrentDirectoryW(sz, buf) }, super::os2path) -} - -pub fn chdir(p: &path::Path) -> io::Result<()> { - let p: &OsStr = p.as_ref(); - let mut p = p.encode_wide().collect::>(); - p.push(0); - - cvt(unsafe { c::SetCurrentDirectoryW(p.as_ptr()) }).map(drop) -} - -pub fn getenv(k: &OsStr) -> Option { - let k = to_u16s(k).ok()?; - super::fill_utf16_buf( - |buf, sz| unsafe { c::GetEnvironmentVariableW(k.as_ptr(), buf, sz) }, - OsStringExt::from_wide, - ) - .ok() -} - -pub fn setenv(k: &OsStr, v: &OsStr) -> io::Result<()> { - let k = to_u16s(k)?; - let v = to_u16s(v)?; - - cvt(unsafe { c::SetEnvironmentVariableW(k.as_ptr(), v.as_ptr()) }).map(drop) -} - -pub fn unsetenv(n: &OsStr) -> io::Result<()> { - let v = to_u16s(n)?; - cvt(unsafe { c::SetEnvironmentVariableW(v.as_ptr(), ptr::null()) }).map(drop) -} - -pub fn temp_dir() -> PathBuf { - super::fill_utf16_buf(|buf, sz| unsafe { c::GetTempPath2W(sz, buf) }, super::os2path).unwrap() -} - -#[cfg(all(not(target_vendor = "uwp"), not(target_vendor = "win7")))] -fn home_dir_crt() -> Option { - unsafe { - // Defined in processthreadsapi.h. - const CURRENT_PROCESS_TOKEN: usize = -4_isize as usize; - - super::fill_utf16_buf( - |buf, mut sz| { - // GetUserProfileDirectoryW does not quite use the usual protocol for - // negotiating the buffer size, so we have to translate. - match c::GetUserProfileDirectoryW( - ptr::without_provenance_mut(CURRENT_PROCESS_TOKEN), - buf, - &mut sz, - ) { - 0 if api::get_last_error().code != c::ERROR_INSUFFICIENT_BUFFER => 0, - 0 => sz, - _ => sz - 1, // sz includes the null terminator - } - }, - super::os2path, - ) - .ok() - } -} - -#[cfg(target_vendor = "win7")] -fn home_dir_crt() -> Option { - unsafe { - use crate::sys::handle::Handle; - - let me = c::GetCurrentProcess(); - let mut token = ptr::null_mut(); - if c::OpenProcessToken(me, c::TOKEN_READ, &mut token) == 0 { - return None; - } - let _handle = Handle::from_raw_handle(token); - super::fill_utf16_buf( - |buf, mut sz| { - match c::GetUserProfileDirectoryW(token, buf, &mut sz) { - 0 if api::get_last_error().code != c::ERROR_INSUFFICIENT_BUFFER => 0, - 0 => sz, - _ => sz - 1, // sz includes the null terminator - } - }, - super::os2path, - ) - .ok() - } -} - -#[cfg(target_vendor = "uwp")] -fn home_dir_crt() -> Option { - None -} - -pub fn home_dir() -> Option { - crate::env::var_os("HOME") - .or_else(|| crate::env::var_os("USERPROFILE")) - .map(PathBuf::from) - .or_else(home_dir_crt) -} - -pub fn exit(code: i32) -> ! { - unsafe { c::ExitProcess(code as c::UINT) } -} - -pub fn getpid() -> u32 { - unsafe { c::GetCurrentProcessId() } -} diff --git a/library/std/src/sys/pal/windows/os/tests.rs b/library/std/src/sys/pal/windows/os/tests.rs deleted file mode 100644 index 458d6e11c2098..0000000000000 --- a/library/std/src/sys/pal/windows/os/tests.rs +++ /dev/null @@ -1,13 +0,0 @@ -use crate::io::Error; -use crate::sys::c; - -// tests `error_string` above -#[test] -fn ntstatus_error() { - const STATUS_UNSUCCESSFUL: u32 = 0xc000_0001; - assert!( - !Error::from_raw_os_error((STATUS_UNSUCCESSFUL | c::FACILITY_NT_BIT) as _) - .to_string() - .contains("FormatMessageW() returned error") - ); -} diff --git a/library/std/src/sys/pal/windows/pipe.rs b/library/std/src/sys/pal/windows/pipe.rs deleted file mode 100644 index dfa938d4d5769..0000000000000 --- a/library/std/src/sys/pal/windows/pipe.rs +++ /dev/null @@ -1,571 +0,0 @@ -use crate::os::windows::prelude::*; - -use crate::ffi::OsStr; -use crate::io::{self, BorrowedCursor, IoSlice, IoSliceMut, Read}; -use crate::mem; -use crate::path::Path; -use crate::ptr; -use crate::slice; -use crate::sync::atomic::AtomicUsize; -use crate::sync::atomic::Ordering::Relaxed; -use crate::sys::c; -use crate::sys::fs::{File, OpenOptions}; -use crate::sys::handle::Handle; -use crate::sys::hashmap_random_keys; -use crate::sys_common::{FromInner, IntoInner}; - -//////////////////////////////////////////////////////////////////////////////// -// Anonymous pipes -//////////////////////////////////////////////////////////////////////////////// - -pub struct AnonPipe { - inner: Handle, -} - -impl IntoInner for AnonPipe { - fn into_inner(self) -> Handle { - self.inner - } -} - -impl FromInner for AnonPipe { - fn from_inner(inner: Handle) -> AnonPipe { - Self { inner } - } -} - -pub struct Pipes { - pub ours: AnonPipe, - pub theirs: AnonPipe, -} - -/// Although this looks similar to `anon_pipe` in the Unix module it's actually -/// subtly different. Here we'll return two pipes in the `Pipes` return value, -/// but one is intended for "us" where as the other is intended for "someone -/// else". -/// -/// Currently the only use case for this function is pipes for stdio on -/// processes in the standard library, so "ours" is the one that'll stay in our -/// process whereas "theirs" will be inherited to a child. -/// -/// The ours/theirs pipes are *not* specifically readable or writable. Each -/// one only supports a read or a write, but which is which depends on the -/// boolean flag given. If `ours_readable` is `true`, then `ours` is readable and -/// `theirs` is writable. Conversely, if `ours_readable` is `false`, then `ours` -/// is writable and `theirs` is readable. -/// -/// Also note that the `ours` pipe is always a handle opened up in overlapped -/// mode. This means that technically speaking it should only ever be used -/// with `OVERLAPPED` instances, but also works out ok if it's only ever used -/// once at a time (which we do indeed guarantee). -pub fn anon_pipe(ours_readable: bool, their_handle_inheritable: bool) -> io::Result { - // A 64kb pipe capacity is the same as a typical Linux default. - const PIPE_BUFFER_CAPACITY: u32 = 64 * 1024; - - // Note that we specifically do *not* use `CreatePipe` here because - // unfortunately the anonymous pipes returned do not support overlapped - // operations. Instead, we create a "hopefully unique" name and create a - // named pipe which has overlapped operations enabled. - // - // Once we do this, we connect do it as usual via `CreateFileW`, and then - // we return those reader/writer halves. Note that the `ours` pipe return - // value is always the named pipe, whereas `theirs` is just the normal file. - // This should hopefully shield us from child processes which assume their - // stdout is a named pipe, which would indeed be odd! - unsafe { - let ours; - let mut name; - let mut tries = 0; - let mut reject_remote_clients_flag = c::PIPE_REJECT_REMOTE_CLIENTS; - loop { - tries += 1; - name = format!( - r"\\.\pipe\__rust_anonymous_pipe1__.{}.{}", - c::GetCurrentProcessId(), - random_number() - ); - let wide_name = OsStr::new(&name).encode_wide().chain(Some(0)).collect::>(); - let mut flags = c::FILE_FLAG_FIRST_PIPE_INSTANCE | c::FILE_FLAG_OVERLAPPED; - if ours_readable { - flags |= c::PIPE_ACCESS_INBOUND; - } else { - flags |= c::PIPE_ACCESS_OUTBOUND; - } - - let handle = c::CreateNamedPipeW( - wide_name.as_ptr(), - flags, - c::PIPE_TYPE_BYTE - | c::PIPE_READMODE_BYTE - | c::PIPE_WAIT - | reject_remote_clients_flag, - 1, - PIPE_BUFFER_CAPACITY, - PIPE_BUFFER_CAPACITY, - 0, - ptr::null_mut(), - ); - - // We pass the `FILE_FLAG_FIRST_PIPE_INSTANCE` flag above, and we're - // also just doing a best effort at selecting a unique name. If - // `ERROR_ACCESS_DENIED` is returned then it could mean that we - // accidentally conflicted with an already existing pipe, so we try - // again. - // - // Don't try again too much though as this could also perhaps be a - // legit error. - // If `ERROR_INVALID_PARAMETER` is returned, this probably means we're - // running on pre-Vista version where `PIPE_REJECT_REMOTE_CLIENTS` is - // not supported, so we continue retrying without it. This implies - // reduced security on Windows versions older than Vista by allowing - // connections to this pipe from remote machines. - // Proper fix would increase the number of FFI imports and introduce - // significant amount of Windows XP specific code with no clean - // testing strategy - // For more info, see https://github.com/rust-lang/rust/pull/37677. - if handle == c::INVALID_HANDLE_VALUE { - let err = io::Error::last_os_error(); - let raw_os_err = err.raw_os_error(); - if tries < 10 { - if raw_os_err == Some(c::ERROR_ACCESS_DENIED as i32) { - continue; - } else if reject_remote_clients_flag != 0 - && raw_os_err == Some(c::ERROR_INVALID_PARAMETER as i32) - { - reject_remote_clients_flag = 0; - tries -= 1; - continue; - } - } - return Err(err); - } - ours = Handle::from_raw_handle(handle); - break; - } - - // Connect to the named pipe we just created. This handle is going to be - // returned in `theirs`, so if `ours` is readable we want this to be - // writable, otherwise if `ours` is writable we want this to be - // readable. - // - // Additionally we don't enable overlapped mode on this because most - // client processes aren't enabled to work with that. - let mut opts = OpenOptions::new(); - opts.write(ours_readable); - opts.read(!ours_readable); - opts.share_mode(0); - let size = mem::size_of::(); - let mut sa = c::SECURITY_ATTRIBUTES { - nLength: size as c::DWORD, - lpSecurityDescriptor: ptr::null_mut(), - bInheritHandle: their_handle_inheritable as i32, - }; - opts.security_attributes(&mut sa); - let theirs = File::open(Path::new(&name), &opts)?; - let theirs = AnonPipe { inner: theirs.into_inner() }; - - Ok(Pipes { - ours: AnonPipe { inner: ours }, - theirs: AnonPipe { inner: theirs.into_inner() }, - }) - } -} - -/// Takes an asynchronous source pipe and returns a synchronous pipe suitable -/// for sending to a child process. -/// -/// This is achieved by creating a new set of pipes and spawning a thread that -/// relays messages between the source and the synchronous pipe. -pub fn spawn_pipe_relay( - source: &AnonPipe, - ours_readable: bool, - their_handle_inheritable: bool, -) -> io::Result { - // We need this handle to live for the lifetime of the thread spawned below. - let source = source.duplicate()?; - - // create a new pair of anon pipes. - let Pipes { theirs, ours } = anon_pipe(ours_readable, their_handle_inheritable)?; - - // Spawn a thread that passes messages from one pipe to the other. - // Any errors will simply cause the thread to exit. - let (reader, writer) = if ours_readable { (ours, source) } else { (source, ours) }; - crate::thread::spawn(move || { - let mut buf = [0_u8; 4096]; - 'reader: while let Ok(len) = reader.read(&mut buf) { - if len == 0 { - break; - } - let mut start = 0; - while let Ok(written) = writer.write(&buf[start..len]) { - start += written; - if start == len { - continue 'reader; - } - } - break; - } - }); - - // Return the pipe that should be sent to the child process. - Ok(theirs) -} - -fn random_number() -> usize { - static N: AtomicUsize = AtomicUsize::new(0); - loop { - if N.load(Relaxed) != 0 { - return N.fetch_add(1, Relaxed); - } - - N.store(hashmap_random_keys().0 as usize, Relaxed); - } -} - -// Abstracts over `ReadFileEx` and `WriteFileEx` -type AlertableIoFn = unsafe extern "system" fn( - BorrowedHandle<'_>, - c::LPVOID, - c::DWORD, - c::LPOVERLAPPED, - c::LPOVERLAPPED_COMPLETION_ROUTINE, -) -> c::BOOL; - -impl AnonPipe { - pub fn handle(&self) -> &Handle { - &self.inner - } - pub fn into_handle(self) -> Handle { - self.inner - } - fn duplicate(&self) -> io::Result { - self.inner.duplicate(0, false, c::DUPLICATE_SAME_ACCESS).map(|inner| AnonPipe { inner }) - } - - pub fn read(&self, buf: &mut [u8]) -> io::Result { - let result = unsafe { - let len = crate::cmp::min(buf.len(), c::DWORD::MAX as usize) as c::DWORD; - self.alertable_io_internal(c::ReadFileEx, buf.as_mut_ptr() as _, len) - }; - - match result { - // The special treatment of BrokenPipe is to deal with Windows - // pipe semantics, which yields this error when *reading* from - // a pipe after the other end has closed; we interpret that as - // EOF on the pipe. - Err(ref e) if e.kind() == io::ErrorKind::BrokenPipe => Ok(0), - _ => result, - } - } - - pub fn read_buf(&self, mut buf: BorrowedCursor<'_>) -> io::Result<()> { - let result = unsafe { - let len = crate::cmp::min(buf.capacity(), c::DWORD::MAX as usize) as c::DWORD; - self.alertable_io_internal(c::ReadFileEx, buf.as_mut().as_mut_ptr() as _, len) - }; - - match result { - // The special treatment of BrokenPipe is to deal with Windows - // pipe semantics, which yields this error when *reading* from - // a pipe after the other end has closed; we interpret that as - // EOF on the pipe. - Err(ref e) if e.kind() == io::ErrorKind::BrokenPipe => Ok(()), - Err(e) => Err(e), - Ok(n) => { - unsafe { - buf.advance_unchecked(n); - } - Ok(()) - } - } - } - - pub fn read_vectored(&self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - self.inner.read_vectored(bufs) - } - - #[inline] - pub fn is_read_vectored(&self) -> bool { - self.inner.is_read_vectored() - } - - pub fn read_to_end(&self, buf: &mut Vec) -> io::Result { - self.handle().read_to_end(buf) - } - - pub fn write(&self, buf: &[u8]) -> io::Result { - unsafe { - let len = crate::cmp::min(buf.len(), c::DWORD::MAX as usize) as c::DWORD; - self.alertable_io_internal(c::WriteFileEx, buf.as_ptr() as _, len) - } - } - - pub fn write_vectored(&self, bufs: &[IoSlice<'_>]) -> io::Result { - self.inner.write_vectored(bufs) - } - - #[inline] - pub fn is_write_vectored(&self) -> bool { - self.inner.is_write_vectored() - } - - /// Synchronizes asynchronous reads or writes using our anonymous pipe. - /// - /// This is a wrapper around [`ReadFileEx`] or [`WriteFileEx`] that uses - /// [Asynchronous Procedure Call] (APC) to synchronize reads or writes. - /// - /// Note: This should not be used for handles we don't create. - /// - /// # Safety - /// - /// `buf` must be a pointer to a buffer that's valid for reads or writes - /// up to `len` bytes. The `AlertableIoFn` must be either `ReadFileEx` or `WriteFileEx` - /// - /// [`ReadFileEx`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-readfileex - /// [`WriteFileEx`]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-writefileex - /// [Asynchronous Procedure Call]: https://docs.microsoft.com/en-us/windows/win32/sync/asynchronous-procedure-calls - unsafe fn alertable_io_internal( - &self, - io: AlertableIoFn, - buf: c::LPVOID, - len: c::DWORD, - ) -> io::Result { - // Use "alertable I/O" to synchronize the pipe I/O. - // This has four steps. - // - // STEP 1: Start the asynchronous I/O operation. - // This simply calls either `ReadFileEx` or `WriteFileEx`, - // giving it a pointer to the buffer and callback function. - // - // STEP 2: Enter an alertable state. - // The callback set in step 1 will not be called until the thread - // enters an "alertable" state. This can be done using `SleepEx`. - // - // STEP 3: The callback - // Once the I/O is complete and the thread is in an alertable state, - // the callback will be run on the same thread as the call to - // `ReadFileEx` or `WriteFileEx` done in step 1. - // In the callback we simply set the result of the async operation. - // - // STEP 4: Return the result. - // At this point we'll have a result from the callback function - // and can simply return it. Note that we must not return earlier, - // while the I/O is still in progress. - - // The result that will be set from the asynchronous callback. - let mut async_result: Option = None; - struct AsyncResult { - error: u32, - transferred: u32, - } - - // STEP 3: The callback. - unsafe extern "system" fn callback( - dwErrorCode: u32, - dwNumberOfBytesTransferred: u32, - lpOverlapped: *mut c::OVERLAPPED, - ) { - // Set `async_result` using a pointer smuggled through `hEvent`. - let result = - AsyncResult { error: dwErrorCode, transferred: dwNumberOfBytesTransferred }; - *(*lpOverlapped).hEvent.cast::>() = Some(result); - } - - // STEP 1: Start the I/O operation. - let mut overlapped: c::OVERLAPPED = crate::mem::zeroed(); - // `hEvent` is unused by `ReadFileEx` and `WriteFileEx`. - // Therefore the documentation suggests using it to smuggle a pointer to the callback. - overlapped.hEvent = core::ptr::addr_of_mut!(async_result) as *mut _; - - // Asynchronous read of the pipe. - // If successful, `callback` will be called once it completes. - let result = io(self.inner.as_handle(), buf, len, &mut overlapped, Some(callback)); - if result == c::FALSE { - // We can return here because the call failed. - // After this we must not return until the I/O completes. - return Err(io::Error::last_os_error()); - } - - // Wait indefinitely for the result. - let result = loop { - // STEP 2: Enter an alertable state. - // The second parameter of `SleepEx` is used to make this sleep alertable. - c::SleepEx(c::INFINITE, c::TRUE); - if let Some(result) = async_result { - break result; - } - }; - // STEP 4: Return the result. - // `async_result` is always `Some` at this point - match result.error { - c::ERROR_SUCCESS => Ok(result.transferred as usize), - error => Err(io::Error::from_raw_os_error(error as _)), - } - } -} - -pub fn read2(p1: AnonPipe, v1: &mut Vec, p2: AnonPipe, v2: &mut Vec) -> io::Result<()> { - let p1 = p1.into_handle(); - let p2 = p2.into_handle(); - - let mut p1 = AsyncPipe::new(p1, v1)?; - let mut p2 = AsyncPipe::new(p2, v2)?; - let objs = [p1.event.as_raw_handle(), p2.event.as_raw_handle()]; - - // In a loop we wait for either pipe's scheduled read operation to complete. - // If the operation completes with 0 bytes, that means EOF was reached, in - // which case we just finish out the other pipe entirely. - // - // Note that overlapped I/O is in general super unsafe because we have to - // be careful to ensure that all pointers in play are valid for the entire - // duration of the I/O operation (where tons of operations can also fail). - // The destructor for `AsyncPipe` ends up taking care of most of this. - loop { - let res = unsafe { c::WaitForMultipleObjects(2, objs.as_ptr(), c::FALSE, c::INFINITE) }; - if res == c::WAIT_OBJECT_0 { - if !p1.result()? || !p1.schedule_read()? { - return p2.finish(); - } - } else if res == c::WAIT_OBJECT_0 + 1 { - if !p2.result()? || !p2.schedule_read()? { - return p1.finish(); - } - } else { - return Err(io::Error::last_os_error()); - } - } -} - -struct AsyncPipe<'a> { - pipe: Handle, - event: Handle, - overlapped: Box, // needs a stable address - dst: &'a mut Vec, - state: State, -} - -#[derive(PartialEq, Debug)] -enum State { - NotReading, - Reading, - Read(usize), -} - -impl<'a> AsyncPipe<'a> { - fn new(pipe: Handle, dst: &'a mut Vec) -> io::Result> { - // Create an event which we'll use to coordinate our overlapped - // operations, this event will be used in WaitForMultipleObjects - // and passed as part of the OVERLAPPED handle. - // - // Note that we do a somewhat clever thing here by flagging the - // event as being manually reset and setting it initially to the - // signaled state. This means that we'll naturally fall through the - // WaitForMultipleObjects call above for pipes created initially, - // and the only time an even will go back to "unset" will be once an - // I/O operation is successfully scheduled (what we want). - let event = Handle::new_event(true, true)?; - let mut overlapped: Box = unsafe { Box::new(mem::zeroed()) }; - overlapped.hEvent = event.as_raw_handle(); - Ok(AsyncPipe { pipe, overlapped, event, dst, state: State::NotReading }) - } - - /// Executes an overlapped read operation. - /// - /// Must not currently be reading, and returns whether the pipe is currently - /// at EOF or not. If the pipe is not at EOF then `result()` must be called - /// to complete the read later on (may block), but if the pipe is at EOF - /// then `result()` should not be called as it will just block forever. - fn schedule_read(&mut self) -> io::Result { - assert_eq!(self.state, State::NotReading); - let amt = unsafe { - let slice = slice_to_end(self.dst); - self.pipe.read_overlapped(slice, &mut *self.overlapped)? - }; - - // If this read finished immediately then our overlapped event will - // remain signaled (it was signaled coming in here) and we'll progress - // down to the method below. - // - // Otherwise the I/O operation is scheduled and the system set our event - // to not signaled, so we flag ourselves into the reading state and move - // on. - self.state = match amt { - Some(0) => return Ok(false), - Some(amt) => State::Read(amt), - None => State::Reading, - }; - Ok(true) - } - - /// Wait for the result of the overlapped operation previously executed. - /// - /// Takes a parameter `wait` which indicates if this pipe is currently being - /// read whether the function should block waiting for the read to complete. - /// - /// Returns values: - /// - /// * `true` - finished any pending read and the pipe is not at EOF (keep - /// going) - /// * `false` - finished any pending read and pipe is at EOF (stop issuing - /// reads) - fn result(&mut self) -> io::Result { - let amt = match self.state { - State::NotReading => return Ok(true), - State::Reading => self.pipe.overlapped_result(&mut *self.overlapped, true)?, - State::Read(amt) => amt, - }; - self.state = State::NotReading; - unsafe { - let len = self.dst.len(); - self.dst.set_len(len + amt); - } - Ok(amt != 0) - } - - /// Finishes out reading this pipe entirely. - /// - /// Waits for any pending and schedule read, and then calls `read_to_end` - /// if necessary to read all the remaining information. - fn finish(&mut self) -> io::Result<()> { - while self.result()? && self.schedule_read()? { - // ... - } - Ok(()) - } -} - -impl<'a> Drop for AsyncPipe<'a> { - fn drop(&mut self) { - match self.state { - State::Reading => {} - _ => return, - } - - // If we have a pending read operation, then we have to make sure that - // it's *done* before we actually drop this type. The kernel requires - // that the `OVERLAPPED` and buffer pointers are valid for the entire - // I/O operation. - // - // To do that, we call `CancelIo` to cancel any pending operation, and - // if that succeeds we wait for the overlapped result. - // - // If anything here fails, there's not really much we can do, so we leak - // the buffer/OVERLAPPED pointers to ensure we're at least memory safe. - if self.pipe.cancel_io().is_err() || self.result().is_err() { - let buf = mem::take(self.dst); - let overlapped = Box::new(unsafe { mem::zeroed() }); - let overlapped = mem::replace(&mut self.overlapped, overlapped); - mem::forget((buf, overlapped)); - } - } -} - -unsafe fn slice_to_end(v: &mut Vec) -> &mut [u8] { - if v.capacity() == 0 { - v.reserve(16); - } - if v.capacity() == v.len() { - v.reserve(1); - } - slice::from_raw_parts_mut(v.as_mut_ptr().add(v.len()), v.capacity() - v.len()) -} diff --git a/library/std/src/sys/pal/windows/process.rs b/library/std/src/sys/pal/windows/process.rs deleted file mode 100644 index e4ab2ca7da1ce..0000000000000 --- a/library/std/src/sys/pal/windows/process.rs +++ /dev/null @@ -1,984 +0,0 @@ -#![unstable(feature = "process_internals", issue = "none")] - -#[cfg(test)] -mod tests; - -use crate::cmp; -use crate::collections::BTreeMap; -use crate::env; -use crate::env::consts::{EXE_EXTENSION, EXE_SUFFIX}; -use crate::ffi::{OsStr, OsString}; -use crate::fmt; -use crate::io::{self, Error, ErrorKind}; -use crate::mem; -use crate::mem::MaybeUninit; -use crate::num::NonZero; -use crate::os::windows::ffi::{OsStrExt, OsStringExt}; -use crate::os::windows::io::{AsHandle, AsRawHandle, BorrowedHandle, FromRawHandle, IntoRawHandle}; -use crate::path::{Path, PathBuf}; -use crate::ptr; -use crate::sync::Mutex; -use crate::sys::args::{self, Arg}; -use crate::sys::c::{self, NonZeroDWORD, EXIT_FAILURE, EXIT_SUCCESS}; -use crate::sys::cvt; -use crate::sys::fs::{File, OpenOptions}; -use crate::sys::handle::Handle; -use crate::sys::path; -use crate::sys::pipe::{self, AnonPipe}; -use crate::sys::stdio; -use crate::sys_common::process::{CommandEnv, CommandEnvs}; -use crate::sys_common::IntoInner; - -use core::ffi::c_void; - -//////////////////////////////////////////////////////////////////////////////// -// Command -//////////////////////////////////////////////////////////////////////////////// - -#[derive(Clone, Debug, Eq)] -#[doc(hidden)] -pub struct EnvKey { - os_string: OsString, - // This stores a UTF-16 encoded string to workaround the mismatch between - // Rust's OsString (WTF-8) and the Windows API string type (UTF-16). - // Normally converting on every API call is acceptable but here - // `c::CompareStringOrdinal` will be called for every use of `==`. - utf16: Vec, -} - -impl EnvKey { - fn new>(key: T) -> Self { - EnvKey::from(key.into()) - } -} - -// Comparing Windows environment variable keys[1] are behaviourally the -// composition of two operations[2]: -// -// 1. Case-fold both strings. This is done using a language-independent -// uppercase mapping that's unique to Windows (albeit based on data from an -// older Unicode spec). It only operates on individual UTF-16 code units so -// surrogates are left unchanged. This uppercase mapping can potentially change -// between Windows versions. -// -// 2. Perform an ordinal comparison of the strings. A comparison using ordinal -// is just a comparison based on the numerical value of each UTF-16 code unit[3]. -// -// Because the case-folding mapping is unique to Windows and not guaranteed to -// be stable, we ask the OS to compare the strings for us. This is done by -// calling `CompareStringOrdinal`[4] with `bIgnoreCase` set to `TRUE`. -// -// [1] https://docs.microsoft.com/en-us/dotnet/standard/base-types/best-practices-strings#choosing-a-stringcomparison-member-for-your-method-call -// [2] https://docs.microsoft.com/en-us/dotnet/standard/base-types/best-practices-strings#stringtoupper-and-stringtolower -// [3] https://docs.microsoft.com/en-us/dotnet/api/system.stringcomparison?view=net-5.0#System_StringComparison_Ordinal -// [4] https://docs.microsoft.com/en-us/windows/win32/api/stringapiset/nf-stringapiset-comparestringordinal -impl Ord for EnvKey { - fn cmp(&self, other: &Self) -> cmp::Ordering { - unsafe { - let result = c::CompareStringOrdinal( - self.utf16.as_ptr(), - self.utf16.len() as _, - other.utf16.as_ptr(), - other.utf16.len() as _, - c::TRUE, - ); - match result { - c::CSTR_LESS_THAN => cmp::Ordering::Less, - c::CSTR_EQUAL => cmp::Ordering::Equal, - c::CSTR_GREATER_THAN => cmp::Ordering::Greater, - // `CompareStringOrdinal` should never fail so long as the parameters are correct. - _ => panic!("comparing environment keys failed: {}", Error::last_os_error()), - } - } - } -} -impl PartialOrd for EnvKey { - fn partial_cmp(&self, other: &Self) -> Option { - Some(self.cmp(other)) - } -} -impl PartialEq for EnvKey { - fn eq(&self, other: &Self) -> bool { - if self.utf16.len() != other.utf16.len() { - false - } else { - self.cmp(other) == cmp::Ordering::Equal - } - } -} -impl PartialOrd for EnvKey { - fn partial_cmp(&self, other: &str) -> Option { - Some(self.cmp(&EnvKey::new(other))) - } -} -impl PartialEq for EnvKey { - fn eq(&self, other: &str) -> bool { - if self.os_string.len() != other.len() { - false - } else { - self.cmp(&EnvKey::new(other)) == cmp::Ordering::Equal - } - } -} - -// Environment variable keys should preserve their original case even though -// they are compared using a caseless string mapping. -impl From for EnvKey { - fn from(k: OsString) -> Self { - EnvKey { utf16: k.encode_wide().collect(), os_string: k } - } -} - -impl From for OsString { - fn from(k: EnvKey) -> Self { - k.os_string - } -} - -impl From<&OsStr> for EnvKey { - fn from(k: &OsStr) -> Self { - Self::from(k.to_os_string()) - } -} - -impl AsRef for EnvKey { - fn as_ref(&self) -> &OsStr { - &self.os_string - } -} - -pub(crate) fn ensure_no_nuls>(str: T) -> io::Result { - if str.as_ref().encode_wide().any(|b| b == 0) { - Err(io::const_io_error!(ErrorKind::InvalidInput, "nul byte found in provided data")) - } else { - Ok(str) - } -} - -pub struct Command { - program: OsString, - args: Vec, - env: CommandEnv, - cwd: Option, - flags: u32, - detach: bool, // not currently exposed in std::process - stdin: Option, - stdout: Option, - stderr: Option, - force_quotes_enabled: bool, - proc_thread_attributes: BTreeMap, -} - -pub enum Stdio { - Inherit, - InheritSpecific { from_stdio_id: c::DWORD }, - Null, - MakePipe, - Pipe(AnonPipe), - Handle(Handle), -} - -pub struct StdioPipes { - pub stdin: Option, - pub stdout: Option, - pub stderr: Option, -} - -impl Command { - pub fn new(program: &OsStr) -> Command { - Command { - program: program.to_os_string(), - args: Vec::new(), - env: Default::default(), - cwd: None, - flags: 0, - detach: false, - stdin: None, - stdout: None, - stderr: None, - force_quotes_enabled: false, - proc_thread_attributes: Default::default(), - } - } - - pub fn arg(&mut self, arg: &OsStr) { - self.args.push(Arg::Regular(arg.to_os_string())) - } - pub fn env_mut(&mut self) -> &mut CommandEnv { - &mut self.env - } - pub fn cwd(&mut self, dir: &OsStr) { - self.cwd = Some(dir.to_os_string()) - } - pub fn stdin(&mut self, stdin: Stdio) { - self.stdin = Some(stdin); - } - pub fn stdout(&mut self, stdout: Stdio) { - self.stdout = Some(stdout); - } - pub fn stderr(&mut self, stderr: Stdio) { - self.stderr = Some(stderr); - } - pub fn creation_flags(&mut self, flags: u32) { - self.flags = flags; - } - - pub fn force_quotes(&mut self, enabled: bool) { - self.force_quotes_enabled = enabled; - } - - pub fn raw_arg(&mut self, command_str_to_append: &OsStr) { - self.args.push(Arg::Raw(command_str_to_append.to_os_string())) - } - - pub fn get_program(&self) -> &OsStr { - &self.program - } - - pub fn get_args(&self) -> CommandArgs<'_> { - let iter = self.args.iter(); - CommandArgs { iter } - } - - pub fn get_envs(&self) -> CommandEnvs<'_> { - self.env.iter() - } - - pub fn get_current_dir(&self) -> Option<&Path> { - self.cwd.as_ref().map(Path::new) - } - - pub unsafe fn raw_attribute( - &mut self, - attribute: usize, - value: T, - ) { - self.proc_thread_attributes.insert( - attribute, - ProcThreadAttributeValue { size: mem::size_of::(), data: Box::new(value) }, - ); - } - - pub fn spawn( - &mut self, - default: Stdio, - needs_stdin: bool, - ) -> io::Result<(Process, StdioPipes)> { - let maybe_env = self.env.capture_if_changed(); - - let child_paths = if let Some(env) = maybe_env.as_ref() { - env.get(&EnvKey::new("PATH")).map(|s| s.as_os_str()) - } else { - None - }; - let program = resolve_exe(&self.program, || env::var_os("PATH"), child_paths)?; - // Case insensitive "ends_with" of UTF-16 encoded ".bat" or ".cmd" - let is_batch_file = matches!( - program.len().checked_sub(5).and_then(|i| program.get(i..)), - Some([46, 98 | 66, 97 | 65, 116 | 84, 0] | [46, 99 | 67, 109 | 77, 100 | 68, 0]) - ); - let (program, mut cmd_str) = if is_batch_file { - ( - command_prompt()?, - args::make_bat_command_line(&program, &self.args, self.force_quotes_enabled)?, - ) - } else { - let cmd_str = make_command_line(&self.program, &self.args, self.force_quotes_enabled)?; - (program, cmd_str) - }; - cmd_str.push(0); // add null terminator - - // stolen from the libuv code. - let mut flags = self.flags | c::CREATE_UNICODE_ENVIRONMENT; - if self.detach { - flags |= c::DETACHED_PROCESS | c::CREATE_NEW_PROCESS_GROUP; - } - - let (envp, _data) = make_envp(maybe_env)?; - let (dirp, _data) = make_dirp(self.cwd.as_ref())?; - let mut pi = zeroed_process_information(); - - // Prepare all stdio handles to be inherited by the child. This - // currently involves duplicating any existing ones with the ability to - // be inherited by child processes. Note, however, that once an - // inheritable handle is created, *any* spawned child will inherit that - // handle. We only want our own child to inherit this handle, so we wrap - // the remaining portion of this spawn in a mutex. - // - // For more information, msdn also has an article about this race: - // https://support.microsoft.com/kb/315939 - static CREATE_PROCESS_LOCK: Mutex<()> = Mutex::new(()); - - let _guard = CREATE_PROCESS_LOCK.lock(); - - let mut pipes = StdioPipes { stdin: None, stdout: None, stderr: None }; - let null = Stdio::Null; - let default_stdin = if needs_stdin { &default } else { &null }; - let stdin = self.stdin.as_ref().unwrap_or(default_stdin); - let stdout = self.stdout.as_ref().unwrap_or(&default); - let stderr = self.stderr.as_ref().unwrap_or(&default); - let stdin = stdin.to_handle(c::STD_INPUT_HANDLE, &mut pipes.stdin)?; - let stdout = stdout.to_handle(c::STD_OUTPUT_HANDLE, &mut pipes.stdout)?; - let stderr = stderr.to_handle(c::STD_ERROR_HANDLE, &mut pipes.stderr)?; - - let mut si = zeroed_startupinfo(); - - // If at least one of stdin, stdout or stderr are set (i.e. are non null) - // then set the `hStd` fields in `STARTUPINFO`. - // Otherwise skip this and allow the OS to apply its default behaviour. - // This provides more consistent behaviour between Win7 and Win8+. - let is_set = |stdio: &Handle| !stdio.as_raw_handle().is_null(); - if is_set(&stderr) || is_set(&stdout) || is_set(&stdin) { - si.dwFlags |= c::STARTF_USESTDHANDLES; - si.hStdInput = stdin.as_raw_handle(); - si.hStdOutput = stdout.as_raw_handle(); - si.hStdError = stderr.as_raw_handle(); - } - - let si_ptr: *mut c::STARTUPINFOW; - - let mut proc_thread_attribute_list; - let mut si_ex; - - if !self.proc_thread_attributes.is_empty() { - si.cb = mem::size_of::() as u32; - flags |= c::EXTENDED_STARTUPINFO_PRESENT; - - proc_thread_attribute_list = - make_proc_thread_attribute_list(&self.proc_thread_attributes)?; - si_ex = c::STARTUPINFOEXW { - StartupInfo: si, - lpAttributeList: proc_thread_attribute_list.0.as_mut_ptr() as _, - }; - si_ptr = core::ptr::addr_of_mut!(si_ex) as _; - } else { - si.cb = mem::size_of::() as c::DWORD; - si_ptr = core::ptr::addr_of_mut!(si) as _; - } - - unsafe { - cvt(c::CreateProcessW( - program.as_ptr(), - cmd_str.as_mut_ptr(), - ptr::null_mut(), - ptr::null_mut(), - c::TRUE, - flags, - envp, - dirp, - si_ptr, - &mut pi, - )) - }?; - - unsafe { - Ok(( - Process { - handle: Handle::from_raw_handle(pi.hProcess), - main_thread_handle: Handle::from_raw_handle(pi.hThread), - }, - pipes, - )) - } - } - - pub fn output(&mut self) -> io::Result<(ExitStatus, Vec, Vec)> { - let (proc, pipes) = self.spawn(Stdio::MakePipe, false)?; - crate::sys_common::process::wait_with_output(proc, pipes) - } -} - -impl fmt::Debug for Command { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.program.fmt(f)?; - for arg in &self.args { - f.write_str(" ")?; - match arg { - Arg::Regular(s) => s.fmt(f), - Arg::Raw(s) => f.write_str(&s.to_string_lossy()), - }?; - } - Ok(()) - } -} - -// Resolve `exe_path` to the executable name. -// -// * If the path is simply a file name then use the paths given by `search_paths` to find the executable. -// * Otherwise use the `exe_path` as given. -// -// This function may also append `.exe` to the name. The rationale for doing so is as follows: -// -// It is a very strong convention that Windows executables have the `exe` extension. -// In Rust, it is common to omit this extension. -// Therefore this functions first assumes `.exe` was intended. -// It falls back to the plain file name if a full path is given and the extension is omitted -// or if only a file name is given and it already contains an extension. -fn resolve_exe<'a>( - exe_path: &'a OsStr, - parent_paths: impl FnOnce() -> Option, - child_paths: Option<&OsStr>, -) -> io::Result> { - // Early return if there is no filename. - if exe_path.is_empty() || path::has_trailing_slash(exe_path) { - return Err(io::const_io_error!( - io::ErrorKind::InvalidInput, - "program path has no file name", - )); - } - // Test if the file name has the `exe` extension. - // This does a case-insensitive `ends_with`. - let has_exe_suffix = if exe_path.len() >= EXE_SUFFIX.len() { - exe_path.as_encoded_bytes()[exe_path.len() - EXE_SUFFIX.len()..] - .eq_ignore_ascii_case(EXE_SUFFIX.as_bytes()) - } else { - false - }; - - // If `exe_path` is an absolute path or a sub-path then don't search `PATH` for it. - if !path::is_file_name(exe_path) { - if has_exe_suffix { - // The application name is a path to a `.exe` file. - // Let `CreateProcessW` figure out if it exists or not. - return args::to_user_path(Path::new(exe_path)); - } - let mut path = PathBuf::from(exe_path); - - // Append `.exe` if not already there. - path = path::append_suffix(path, EXE_SUFFIX.as_ref()); - if let Some(path) = program_exists(&path) { - return Ok(path); - } else { - // It's ok to use `set_extension` here because the intent is to - // remove the extension that was just added. - path.set_extension(""); - return args::to_user_path(&path); - } - } else { - ensure_no_nuls(exe_path)?; - // From the `CreateProcessW` docs: - // > If the file name does not contain an extension, .exe is appended. - // Note that this rule only applies when searching paths. - let has_extension = exe_path.as_encoded_bytes().contains(&b'.'); - - // Search the directories given by `search_paths`. - let result = search_paths(parent_paths, child_paths, |mut path| { - path.push(exe_path); - if !has_extension { - path.set_extension(EXE_EXTENSION); - } - program_exists(&path) - }); - if let Some(path) = result { - return Ok(path); - } - } - // If we get here then the executable cannot be found. - Err(io::const_io_error!(io::ErrorKind::NotFound, "program not found")) -} - -// Calls `f` for every path that should be used to find an executable. -// Returns once `f` returns the path to an executable or all paths have been searched. -fn search_paths( - parent_paths: Paths, - child_paths: Option<&OsStr>, - mut exists: Exists, -) -> Option> -where - Paths: FnOnce() -> Option, - Exists: FnMut(PathBuf) -> Option>, -{ - // 1. Child paths - // This is for consistency with Rust's historic behaviour. - if let Some(paths) = child_paths { - for path in env::split_paths(paths).filter(|p| !p.as_os_str().is_empty()) { - if let Some(path) = exists(path) { - return Some(path); - } - } - } - - // 2. Application path - if let Ok(mut app_path) = env::current_exe() { - app_path.pop(); - if let Some(path) = exists(app_path) { - return Some(path); - } - } - - // 3 & 4. System paths - // SAFETY: This uses `fill_utf16_buf` to safely call the OS functions. - unsafe { - if let Ok(Some(path)) = super::fill_utf16_buf( - |buf, size| c::GetSystemDirectoryW(buf, size), - |buf| exists(PathBuf::from(OsString::from_wide(buf))), - ) { - return Some(path); - } - #[cfg(not(target_vendor = "uwp"))] - { - if let Ok(Some(path)) = super::fill_utf16_buf( - |buf, size| c::GetWindowsDirectoryW(buf, size), - |buf| exists(PathBuf::from(OsString::from_wide(buf))), - ) { - return Some(path); - } - } - } - - // 5. Parent paths - if let Some(parent_paths) = parent_paths() { - for path in env::split_paths(&parent_paths).filter(|p| !p.as_os_str().is_empty()) { - if let Some(path) = exists(path) { - return Some(path); - } - } - } - None -} - -/// Check if a file exists without following symlinks. -fn program_exists(path: &Path) -> Option> { - unsafe { - let path = args::to_user_path(path).ok()?; - // Getting attributes using `GetFileAttributesW` does not follow symlinks - // and it will almost always be successful if the link exists. - // There are some exceptions for special system files (e.g. the pagefile) - // but these are not executable. - if c::GetFileAttributesW(path.as_ptr()) == c::INVALID_FILE_ATTRIBUTES { - None - } else { - Some(path) - } - } -} - -impl Stdio { - fn to_handle(&self, stdio_id: c::DWORD, pipe: &mut Option) -> io::Result { - let use_stdio_id = |stdio_id| match stdio::get_handle(stdio_id) { - Ok(io) => unsafe { - let io = Handle::from_raw_handle(io); - let ret = io.duplicate(0, true, c::DUPLICATE_SAME_ACCESS); - io.into_raw_handle(); - ret - }, - // If no stdio handle is available, then propagate the null value. - Err(..) => unsafe { Ok(Handle::from_raw_handle(ptr::null_mut())) }, - }; - match *self { - Stdio::Inherit => use_stdio_id(stdio_id), - Stdio::InheritSpecific { from_stdio_id } => use_stdio_id(from_stdio_id), - - Stdio::MakePipe => { - let ours_readable = stdio_id != c::STD_INPUT_HANDLE; - let pipes = pipe::anon_pipe(ours_readable, true)?; - *pipe = Some(pipes.ours); - Ok(pipes.theirs.into_handle()) - } - - Stdio::Pipe(ref source) => { - let ours_readable = stdio_id != c::STD_INPUT_HANDLE; - pipe::spawn_pipe_relay(source, ours_readable, true).map(AnonPipe::into_handle) - } - - Stdio::Handle(ref handle) => handle.duplicate(0, true, c::DUPLICATE_SAME_ACCESS), - - // Open up a reference to NUL with appropriate read/write - // permissions as well as the ability to be inherited to child - // processes (as this is about to be inherited). - Stdio::Null => { - let size = mem::size_of::(); - let mut sa = c::SECURITY_ATTRIBUTES { - nLength: size as c::DWORD, - lpSecurityDescriptor: ptr::null_mut(), - bInheritHandle: 1, - }; - let mut opts = OpenOptions::new(); - opts.read(stdio_id == c::STD_INPUT_HANDLE); - opts.write(stdio_id != c::STD_INPUT_HANDLE); - opts.security_attributes(&mut sa); - File::open(Path::new(r"\\.\NUL"), &opts).map(|file| file.into_inner()) - } - } - } -} - -impl From for Stdio { - fn from(pipe: AnonPipe) -> Stdio { - Stdio::Pipe(pipe) - } -} - -impl From for Stdio { - fn from(file: File) -> Stdio { - Stdio::Handle(file.into_inner()) - } -} - -impl From for Stdio { - fn from(_: io::Stdout) -> Stdio { - Stdio::InheritSpecific { from_stdio_id: c::STD_OUTPUT_HANDLE } - } -} - -impl From for Stdio { - fn from(_: io::Stderr) -> Stdio { - Stdio::InheritSpecific { from_stdio_id: c::STD_ERROR_HANDLE } - } -} - -//////////////////////////////////////////////////////////////////////////////// -// Processes -//////////////////////////////////////////////////////////////////////////////// - -/// A value representing a child process. -/// -/// The lifetime of this value is linked to the lifetime of the actual -/// process - the Process destructor calls self.finish() which waits -/// for the process to terminate. -pub struct Process { - handle: Handle, - main_thread_handle: Handle, -} - -impl Process { - pub fn kill(&mut self) -> io::Result<()> { - let result = unsafe { c::TerminateProcess(self.handle.as_raw_handle(), 1) }; - if result == c::FALSE { - let error = unsafe { c::GetLastError() }; - // TerminateProcess returns ERROR_ACCESS_DENIED if the process has already been - // terminated (by us, or for any other reason). So check if the process was actually - // terminated, and if so, do not return an error. - if error != c::ERROR_ACCESS_DENIED || self.try_wait().is_err() { - return Err(crate::io::Error::from_raw_os_error(error as i32)); - } - } - Ok(()) - } - - pub fn id(&self) -> u32 { - unsafe { c::GetProcessId(self.handle.as_raw_handle()) } - } - - pub fn main_thread_handle(&self) -> BorrowedHandle<'_> { - self.main_thread_handle.as_handle() - } - - pub fn wait(&mut self) -> io::Result { - unsafe { - let res = c::WaitForSingleObject(self.handle.as_raw_handle(), c::INFINITE); - if res != c::WAIT_OBJECT_0 { - return Err(Error::last_os_error()); - } - let mut status = 0; - cvt(c::GetExitCodeProcess(self.handle.as_raw_handle(), &mut status))?; - Ok(ExitStatus(status)) - } - } - - pub fn try_wait(&mut self) -> io::Result> { - unsafe { - match c::WaitForSingleObject(self.handle.as_raw_handle(), 0) { - c::WAIT_OBJECT_0 => {} - c::WAIT_TIMEOUT => { - return Ok(None); - } - _ => return Err(io::Error::last_os_error()), - } - let mut status = 0; - cvt(c::GetExitCodeProcess(self.handle.as_raw_handle(), &mut status))?; - Ok(Some(ExitStatus(status))) - } - } - - pub fn handle(&self) -> &Handle { - &self.handle - } - - pub fn into_handle(self) -> Handle { - self.handle - } -} - -#[derive(PartialEq, Eq, Clone, Copy, Debug, Default)] -pub struct ExitStatus(c::DWORD); - -impl ExitStatus { - pub fn exit_ok(&self) -> Result<(), ExitStatusError> { - match NonZeroDWORD::try_from(self.0) { - /* was nonzero */ Ok(failure) => Err(ExitStatusError(failure)), - /* was zero, couldn't convert */ Err(_) => Ok(()), - } - } - pub fn code(&self) -> Option { - Some(self.0 as i32) - } -} - -/// Converts a raw `c::DWORD` to a type-safe `ExitStatus` by wrapping it without copying. -impl From for ExitStatus { - fn from(u: c::DWORD) -> ExitStatus { - ExitStatus(u) - } -} - -impl fmt::Display for ExitStatus { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - // Windows exit codes with the high bit set typically mean some form of - // unhandled exception or warning. In this scenario printing the exit - // code in decimal doesn't always make sense because it's a very large - // and somewhat gibberish number. The hex code is a bit more - // recognizable and easier to search for, so print that. - if self.0 & 0x80000000 != 0 { - write!(f, "exit code: {:#x}", self.0) - } else { - write!(f, "exit code: {}", self.0) - } - } -} - -#[derive(PartialEq, Eq, Clone, Copy, Debug)] -pub struct ExitStatusError(c::NonZeroDWORD); - -impl Into for ExitStatusError { - fn into(self) -> ExitStatus { - ExitStatus(self.0.into()) - } -} - -impl ExitStatusError { - pub fn code(self) -> Option> { - Some((u32::from(self.0) as i32).try_into().unwrap()) - } -} - -#[derive(PartialEq, Eq, Clone, Copy, Debug)] -pub struct ExitCode(c::DWORD); - -impl ExitCode { - pub const SUCCESS: ExitCode = ExitCode(EXIT_SUCCESS as _); - pub const FAILURE: ExitCode = ExitCode(EXIT_FAILURE as _); - - #[inline] - pub fn as_i32(&self) -> i32 { - self.0 as i32 - } -} - -impl From for ExitCode { - fn from(code: u8) -> Self { - ExitCode(c::DWORD::from(code)) - } -} - -impl From for ExitCode { - fn from(code: u32) -> Self { - ExitCode(c::DWORD::from(code)) - } -} - -fn zeroed_startupinfo() -> c::STARTUPINFOW { - c::STARTUPINFOW { - cb: 0, - lpReserved: ptr::null_mut(), - lpDesktop: ptr::null_mut(), - lpTitle: ptr::null_mut(), - dwX: 0, - dwY: 0, - dwXSize: 0, - dwYSize: 0, - dwXCountChars: 0, - dwYCountChars: 0, - dwFillAttribute: 0, - dwFlags: 0, - wShowWindow: 0, - cbReserved2: 0, - lpReserved2: ptr::null_mut(), - hStdInput: ptr::null_mut(), - hStdOutput: ptr::null_mut(), - hStdError: ptr::null_mut(), - } -} - -fn zeroed_process_information() -> c::PROCESS_INFORMATION { - c::PROCESS_INFORMATION { - hProcess: ptr::null_mut(), - hThread: ptr::null_mut(), - dwProcessId: 0, - dwThreadId: 0, - } -} - -// Produces a wide string *without terminating null*; returns an error if -// `prog` or any of the `args` contain a nul. -fn make_command_line(argv0: &OsStr, args: &[Arg], force_quotes: bool) -> io::Result> { - // Encode the command and arguments in a command line string such - // that the spawned process may recover them using CommandLineToArgvW. - let mut cmd: Vec = Vec::new(); - - // Always quote the program name so CreateProcess to avoid ambiguity when - // the child process parses its arguments. - // Note that quotes aren't escaped here because they can't be used in arg0. - // But that's ok because file paths can't contain quotes. - cmd.push(b'"' as u16); - cmd.extend(argv0.encode_wide()); - cmd.push(b'"' as u16); - - for arg in args { - cmd.push(' ' as u16); - args::append_arg(&mut cmd, arg, force_quotes)?; - } - Ok(cmd) -} - -// Get `cmd.exe` for use with bat scripts, encoded as a UTF-16 string. -fn command_prompt() -> io::Result> { - let mut system: Vec = super::fill_utf16_buf( - |buf, size| unsafe { c::GetSystemDirectoryW(buf, size) }, - |buf| buf.into(), - )?; - system.extend("\\cmd.exe".encode_utf16().chain([0])); - Ok(system) -} - -fn make_envp(maybe_env: Option>) -> io::Result<(*mut c_void, Vec)> { - // On Windows we pass an "environment block" which is not a char**, but - // rather a concatenation of null-terminated k=v\0 sequences, with a final - // \0 to terminate. - if let Some(env) = maybe_env { - let mut blk = Vec::new(); - - // If there are no environment variables to set then signal this by - // pushing a null. - if env.is_empty() { - blk.push(0); - } - - for (k, v) in env { - ensure_no_nuls(k.os_string)?; - blk.extend(k.utf16); - blk.push('=' as u16); - blk.extend(ensure_no_nuls(v)?.encode_wide()); - blk.push(0); - } - blk.push(0); - Ok((blk.as_mut_ptr() as *mut c_void, blk)) - } else { - Ok((ptr::null_mut(), Vec::new())) - } -} - -fn make_dirp(d: Option<&OsString>) -> io::Result<(*const u16, Vec)> { - match d { - Some(dir) => { - let mut dir_str: Vec = ensure_no_nuls(dir)?.encode_wide().collect(); - dir_str.push(0); - Ok((dir_str.as_ptr(), dir_str)) - } - None => Ok((ptr::null(), Vec::new())), - } -} - -struct ProcThreadAttributeList(Box<[MaybeUninit]>); - -impl Drop for ProcThreadAttributeList { - fn drop(&mut self) { - let lp_attribute_list = self.0.as_mut_ptr() as _; - unsafe { c::DeleteProcThreadAttributeList(lp_attribute_list) } - } -} - -/// Wrapper around the value data to be used as a Process Thread Attribute. -struct ProcThreadAttributeValue { - data: Box, - size: usize, -} - -fn make_proc_thread_attribute_list( - attributes: &BTreeMap, -) -> io::Result { - // To initialize our ProcThreadAttributeList, we need to determine - // how many bytes to allocate for it. The Windows API simplifies this process - // by allowing us to call `InitializeProcThreadAttributeList` with - // a null pointer to retrieve the required size. - let mut required_size = 0; - let Ok(attribute_count) = attributes.len().try_into() else { - return Err(io::const_io_error!( - ErrorKind::InvalidInput, - "maximum number of ProcThreadAttributes exceeded", - )); - }; - unsafe { - c::InitializeProcThreadAttributeList( - ptr::null_mut(), - attribute_count, - 0, - &mut required_size, - ) - }; - - let mut proc_thread_attribute_list = - ProcThreadAttributeList(vec![MaybeUninit::uninit(); required_size].into_boxed_slice()); - - // Once we've allocated the necessary memory, it's safe to invoke - // `InitializeProcThreadAttributeList` to properly initialize the list. - cvt(unsafe { - c::InitializeProcThreadAttributeList( - proc_thread_attribute_list.0.as_mut_ptr() as *mut _, - attribute_count, - 0, - &mut required_size, - ) - })?; - - // # Add our attributes to the buffer. - // It's theoretically possible for the attribute count to exceed a u32 value. - // Therefore, we ensure that we don't add more attributes than the buffer was initialized for. - for (&attribute, value) in attributes.iter().take(attribute_count as usize) { - let value_ptr = core::ptr::addr_of!(*value.data) as _; - cvt(unsafe { - c::UpdateProcThreadAttribute( - proc_thread_attribute_list.0.as_mut_ptr() as _, - 0, - attribute, - value_ptr, - value.size, - ptr::null_mut(), - ptr::null_mut(), - ) - })?; - } - - Ok(proc_thread_attribute_list) -} - -pub struct CommandArgs<'a> { - iter: crate::slice::Iter<'a, Arg>, -} - -impl<'a> Iterator for CommandArgs<'a> { - type Item = &'a OsStr; - fn next(&mut self) -> Option<&'a OsStr> { - self.iter.next().map(|arg| match arg { - Arg::Regular(s) | Arg::Raw(s) => s.as_ref(), - }) - } - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } -} - -impl<'a> ExactSizeIterator for CommandArgs<'a> { - fn len(&self) -> usize { - self.iter.len() - } - fn is_empty(&self) -> bool { - self.iter.is_empty() - } -} - -impl<'a> fmt::Debug for CommandArgs<'a> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.iter.clone()).finish() - } -} diff --git a/library/std/src/sys/pal/windows/process/tests.rs b/library/std/src/sys/pal/windows/process/tests.rs deleted file mode 100644 index 3fc0c75240c33..0000000000000 --- a/library/std/src/sys/pal/windows/process/tests.rs +++ /dev/null @@ -1,222 +0,0 @@ -use super::make_command_line; -use super::Arg; -use crate::env; -use crate::ffi::{OsStr, OsString}; -use crate::process::Command; - -#[test] -fn test_raw_args() { - let command_line = &make_command_line( - OsStr::new("quoted exe"), - &[ - Arg::Regular(OsString::from("quote me")), - Arg::Raw(OsString::from("quote me *not*")), - Arg::Raw(OsString::from("\t\\")), - Arg::Raw(OsString::from("internal \\\"backslash-\"quote")), - Arg::Regular(OsString::from("optional-quotes")), - ], - false, - ) - .unwrap(); - assert_eq!( - String::from_utf16(command_line).unwrap(), - "\"quoted exe\" \"quote me\" quote me *not* \t\\ internal \\\"backslash-\"quote optional-quotes" - ); -} - -#[test] -fn test_thread_handle() { - use crate::os::windows::io::BorrowedHandle; - use crate::os::windows::process::{ChildExt, CommandExt}; - const CREATE_SUSPENDED: u32 = 0x00000004; - - let p = Command::new("cmd").args(&["/C", "exit 0"]).creation_flags(CREATE_SUSPENDED).spawn(); - assert!(p.is_ok()); - let mut p = p.unwrap(); - - extern "system" { - fn ResumeThread(_: BorrowedHandle<'_>) -> u32; - } - unsafe { - ResumeThread(p.main_thread_handle()); - } - - crate::thread::sleep(crate::time::Duration::from_millis(100)); - - let res = p.try_wait(); - assert!(res.is_ok()); - assert!(res.unwrap().is_some()); - assert!(p.try_wait().unwrap().unwrap().success()); -} - -#[test] -fn test_make_command_line() { - fn test_wrapper(prog: &str, args: &[&str], force_quotes: bool) -> String { - let command_line = &make_command_line( - OsStr::new(prog), - &args.iter().map(|a| Arg::Regular(OsString::from(a))).collect::>(), - force_quotes, - ) - .unwrap(); - String::from_utf16(command_line).unwrap() - } - - assert_eq!(test_wrapper("prog", &["aaa", "bbb", "ccc"], false), "\"prog\" aaa bbb ccc"); - - assert_eq!(test_wrapper("prog", &[r"C:\"], false), r#""prog" C:\"#); - assert_eq!(test_wrapper("prog", &[r"2slashes\\"], false), r#""prog" 2slashes\\"#); - assert_eq!(test_wrapper("prog", &[r" C:\"], false), r#""prog" " C:\\""#); - assert_eq!(test_wrapper("prog", &[r" 2slashes\\"], false), r#""prog" " 2slashes\\\\""#); - - assert_eq!( - test_wrapper("C:\\Program Files\\blah\\blah.exe", &["aaa"], false), - "\"C:\\Program Files\\blah\\blah.exe\" aaa" - ); - assert_eq!( - test_wrapper("C:\\Program Files\\blah\\blah.exe", &["aaa", "v*"], false), - "\"C:\\Program Files\\blah\\blah.exe\" aaa v*" - ); - assert_eq!( - test_wrapper("C:\\Program Files\\blah\\blah.exe", &["aaa", "v*"], true), - "\"C:\\Program Files\\blah\\blah.exe\" \"aaa\" \"v*\"" - ); - assert_eq!( - test_wrapper("C:\\Program Files\\test", &["aa\"bb"], false), - "\"C:\\Program Files\\test\" aa\\\"bb" - ); - assert_eq!(test_wrapper("echo", &["a b c"], false), "\"echo\" \"a b c\""); - assert_eq!( - test_wrapper("echo", &["\" \\\" \\", "\\"], false), - "\"echo\" \"\\\" \\\\\\\" \\\\\" \\" - ); - assert_eq!( - test_wrapper("\u{03c0}\u{042f}\u{97f3}\u{00e6}\u{221e}", &[], false), - "\"\u{03c0}\u{042f}\u{97f3}\u{00e6}\u{221e}\"" - ); -} - -// On Windows, environment args are case preserving but comparisons are case-insensitive. -// See: #85242 -#[test] -fn windows_env_unicode_case() { - let test_cases = [ - ("ä", "Ä"), - ("ß", "SS"), - ("Ä", "Ö"), - ("Ä", "Ö"), - ("I", "İ"), - ("I", "i"), - ("I", "ı"), - ("i", "I"), - ("i", "İ"), - ("i", "ı"), - ("İ", "I"), - ("İ", "i"), - ("İ", "ı"), - ("ı", "I"), - ("ı", "i"), - ("ı", "İ"), - ("ä", "Ä"), - ("ß", "SS"), - ("Ä", "Ö"), - ("Ä", "Ö"), - ("I", "İ"), - ("I", "i"), - ("I", "ı"), - ("i", "I"), - ("i", "İ"), - ("i", "ı"), - ("İ", "I"), - ("İ", "i"), - ("İ", "ı"), - ("ı", "I"), - ("ı", "i"), - ("ı", "İ"), - ]; - // Test that `cmd.env` matches `env::set_var` when setting two strings that - // may (or may not) be case-folded when compared. - for (a, b) in test_cases.iter() { - let mut cmd = Command::new("cmd"); - cmd.env(a, "1"); - cmd.env(b, "2"); - env::set_var(a, "1"); - env::set_var(b, "2"); - - for (key, value) in cmd.get_envs() { - assert_eq!( - env::var(key).ok(), - value.map(|s| s.to_string_lossy().into_owned()), - "command environment mismatch: {a} {b}", - ); - } - } -} - -// UWP applications run in a restricted environment which means this test may not work. -#[cfg(not(target_vendor = "uwp"))] -#[test] -fn windows_exe_resolver() { - use super::resolve_exe; - use crate::io; - use crate::sys::fs::symlink; - use crate::sys_common::io::test::tmpdir; - - let env_paths = || env::var_os("PATH"); - - // Test a full path, with and without the `exe` extension. - let mut current_exe = env::current_exe().unwrap(); - assert!(resolve_exe(current_exe.as_ref(), env_paths, None).is_ok()); - current_exe.set_extension(""); - assert!(resolve_exe(current_exe.as_ref(), env_paths, None).is_ok()); - - // Test lone file names. - assert!(resolve_exe(OsStr::new("cmd"), env_paths, None).is_ok()); - assert!(resolve_exe(OsStr::new("cmd.exe"), env_paths, None).is_ok()); - assert!(resolve_exe(OsStr::new("cmd.EXE"), env_paths, None).is_ok()); - assert!(resolve_exe(OsStr::new("fc"), env_paths, None).is_ok()); - - // Invalid file names should return InvalidInput. - assert_eq!( - resolve_exe(OsStr::new(""), env_paths, None).unwrap_err().kind(), - io::ErrorKind::InvalidInput - ); - assert_eq!( - resolve_exe(OsStr::new("\0"), env_paths, None).unwrap_err().kind(), - io::ErrorKind::InvalidInput - ); - // Trailing slash, therefore there's no file name component. - assert_eq!( - resolve_exe(OsStr::new(r"C:\Path\to\"), env_paths, None).unwrap_err().kind(), - io::ErrorKind::InvalidInput - ); - - /* - Some of the following tests may need to be changed if you are deliberately - changing the behaviour of `resolve_exe`. - */ - - let empty_paths = || None; - - // The resolver looks in system directories even when `PATH` is empty. - assert!(resolve_exe(OsStr::new("cmd.exe"), empty_paths, None).is_ok()); - - // The application's directory is also searched. - let current_exe = env::current_exe().unwrap(); - assert!(resolve_exe(current_exe.file_name().unwrap().as_ref(), empty_paths, None).is_ok()); - - // Create a temporary path and add a broken symlink. - let temp = tmpdir(); - let mut exe_path = temp.path().to_owned(); - exe_path.push("exists.exe"); - - // A broken symlink should still be resolved. - // Skip this check if not in CI and creating symlinks isn't possible. - let is_ci = env::var("CI").is_ok(); - let result = symlink("".as_ref(), &exe_path); - if is_ci || result.is_ok() { - result.unwrap(); - assert!( - resolve_exe(OsStr::new("exists.exe"), empty_paths, Some(temp.path().as_ref())).is_ok() - ); - } -} diff --git a/library/std/src/sys/pal/windows/rand.rs b/library/std/src/sys/pal/windows/rand.rs deleted file mode 100644 index e427546222aea..0000000000000 --- a/library/std/src/sys/pal/windows/rand.rs +++ /dev/null @@ -1,27 +0,0 @@ -use crate::sys::c; -use core::mem; -use core::ptr; - -#[cfg(not(target_vendor = "win7"))] -#[inline] -pub fn hashmap_random_keys() -> (u64, u64) { - let mut v = (0, 0); - let ret = unsafe { c::ProcessPrng(ptr::addr_of_mut!(v).cast::(), mem::size_of_val(&v)) }; - // ProcessPrng is documented as always returning `TRUE`. - // https://learn.microsoft.com/en-us/windows/win32/seccng/processprng#return-value - debug_assert_eq!(ret, c::TRUE); - v -} - -#[cfg(target_vendor = "win7")] -pub fn hashmap_random_keys() -> (u64, u64) { - use crate::ffi::c_void; - use crate::io; - - let mut v = (0, 0); - let ret = unsafe { - c::RtlGenRandom(ptr::addr_of_mut!(v).cast::(), mem::size_of_val(&v) as c::ULONG) - }; - - if ret != 0 { v } else { panic!("RNG broken: {}", io::Error::last_os_error()) } -} diff --git a/library/std/src/sys/pal/windows/stack_overflow.rs b/library/std/src/sys/pal/windows/stack_overflow.rs deleted file mode 100644 index f93f31026f818..0000000000000 --- a/library/std/src/sys/pal/windows/stack_overflow.rs +++ /dev/null @@ -1,36 +0,0 @@ -#![cfg_attr(test, allow(dead_code))] - -use crate::sys::c; -use crate::thread; - -/// Reserve stack space for use in stack overflow exceptions. -pub unsafe fn reserve_stack() { - let result = c::SetThreadStackGuarantee(&mut 0x5000); - // Reserving stack space is not critical so we allow it to fail in the released build of libstd. - // We still use debug assert here so that CI will test that we haven't made a mistake calling the function. - debug_assert_ne!(result, 0, "failed to reserve stack space for exception handling"); -} - -unsafe extern "system" fn vectored_handler(ExceptionInfo: *mut c::EXCEPTION_POINTERS) -> c::LONG { - unsafe { - let rec = &(*(*ExceptionInfo).ExceptionRecord); - let code = rec.ExceptionCode; - - if code == c::EXCEPTION_STACK_OVERFLOW { - rtprintpanic!( - "\nthread '{}' has overflowed its stack\n", - thread::current().name().unwrap_or("") - ); - } - c::EXCEPTION_CONTINUE_SEARCH - } -} - -pub unsafe fn init() { - let result = c::AddVectoredExceptionHandler(0, Some(vectored_handler)); - // Similar to the above, adding the stack overflow handler is allowed to fail - // but a debug assert is used so CI will still test that it normally works. - debug_assert!(!result.is_null(), "failed to install exception handler"); - // Set the thread stack guarantee for the main thread. - reserve_stack(); -} diff --git a/library/std/src/sys/pal/windows/stack_overflow_uwp.rs b/library/std/src/sys/pal/windows/stack_overflow_uwp.rs deleted file mode 100644 index 9e9b3efaf1b14..0000000000000 --- a/library/std/src/sys/pal/windows/stack_overflow_uwp.rs +++ /dev/null @@ -1,4 +0,0 @@ -#![cfg_attr(test, allow(dead_code))] - -pub unsafe fn reserve_stack() {} -pub unsafe fn init() {} diff --git a/library/std/src/sys/pal/windows/stdio.rs b/library/std/src/sys/pal/windows/stdio.rs deleted file mode 100644 index 96c23f82aec2e..0000000000000 --- a/library/std/src/sys/pal/windows/stdio.rs +++ /dev/null @@ -1,462 +0,0 @@ -#![unstable(issue = "none", feature = "windows_stdio")] - -use super::api; -use crate::cmp; -use crate::io; -use crate::mem::MaybeUninit; -use crate::os::windows::io::{FromRawHandle, IntoRawHandle}; -use crate::ptr; -use crate::str; -use crate::sys::c; -use crate::sys::cvt; -use crate::sys::handle::Handle; -use core::str::utf8_char_width; - -#[cfg(test)] -mod tests; - -// Don't cache handles but get them fresh for every read/write. This allows us to track changes to -// the value over time (such as if a process calls `SetStdHandle` while it's running). See #40490. -pub struct Stdin { - surrogate: u16, - incomplete_utf8: IncompleteUtf8, -} - -pub struct Stdout { - incomplete_utf8: IncompleteUtf8, -} - -pub struct Stderr { - incomplete_utf8: IncompleteUtf8, -} - -struct IncompleteUtf8 { - bytes: [u8; 4], - len: u8, -} - -impl IncompleteUtf8 { - // Implemented for use in Stdin::read. - fn read(&mut self, buf: &mut [u8]) -> usize { - // Write to buffer until the buffer is full or we run out of bytes. - let to_write = cmp::min(buf.len(), self.len as usize); - buf[..to_write].copy_from_slice(&self.bytes[..to_write]); - - // Rotate the remaining bytes if not enough remaining space in buffer. - if usize::from(self.len) > buf.len() { - self.bytes.copy_within(to_write.., 0); - self.len -= to_write as u8; - } else { - self.len = 0; - } - - to_write - } -} - -// Apparently Windows doesn't handle large reads on stdin or writes to stdout/stderr well (see -// #13304 for details). -// -// From MSDN (2011): "The storage for this buffer is allocated from a shared heap for the -// process that is 64 KB in size. The maximum size of the buffer will depend on heap usage." -// -// We choose the cap at 8 KiB because libuv does the same, and it seems to be acceptable so far. -const MAX_BUFFER_SIZE: usize = 8192; - -// The standard buffer size of BufReader for Stdin should be able to hold 3x more bytes than there -// are `u16`'s in MAX_BUFFER_SIZE. This ensures the read data can always be completely decoded from -// UTF-16 to UTF-8. -pub const STDIN_BUF_SIZE: usize = MAX_BUFFER_SIZE / 2 * 3; - -pub fn get_handle(handle_id: c::DWORD) -> io::Result { - let handle = unsafe { c::GetStdHandle(handle_id) }; - if handle == c::INVALID_HANDLE_VALUE { - Err(io::Error::last_os_error()) - } else if handle.is_null() { - Err(io::Error::from_raw_os_error(c::ERROR_INVALID_HANDLE as i32)) - } else { - Ok(handle) - } -} - -fn is_console(handle: c::HANDLE) -> bool { - // `GetConsoleMode` will return false (0) if this is a pipe (we don't care about the reported - // mode). This will only detect Windows Console, not other terminals connected to a pipe like - // MSYS. Which is exactly what we need, as only Windows Console needs a conversion to UTF-16. - let mut mode = 0; - unsafe { c::GetConsoleMode(handle, &mut mode) != 0 } -} - -fn write( - handle_id: c::DWORD, - data: &[u8], - incomplete_utf8: &mut IncompleteUtf8, -) -> io::Result { - if data.is_empty() { - return Ok(0); - } - - let handle = get_handle(handle_id)?; - if !is_console(handle) { - unsafe { - let handle = Handle::from_raw_handle(handle); - let ret = handle.write(data); - handle.into_raw_handle(); // Don't close the handle - return ret; - } - } - - if incomplete_utf8.len > 0 { - assert!( - incomplete_utf8.len < 4, - "Unexpected number of bytes for incomplete UTF-8 codepoint." - ); - if data[0] >> 6 != 0b10 { - // not a continuation byte - reject - incomplete_utf8.len = 0; - return Err(io::const_io_error!( - io::ErrorKind::InvalidData, - "Windows stdio in console mode does not support writing non-UTF-8 byte sequences", - )); - } - incomplete_utf8.bytes[incomplete_utf8.len as usize] = data[0]; - incomplete_utf8.len += 1; - let char_width = utf8_char_width(incomplete_utf8.bytes[0]); - if (incomplete_utf8.len as usize) < char_width { - // more bytes needed - return Ok(1); - } - let s = str::from_utf8(&incomplete_utf8.bytes[0..incomplete_utf8.len as usize]); - incomplete_utf8.len = 0; - match s { - Ok(s) => { - assert_eq!(char_width, s.len()); - let written = write_valid_utf8_to_console(handle, s)?; - assert_eq!(written, s.len()); // guaranteed by write_valid_utf8_to_console() for single codepoint writes - return Ok(1); - } - Err(_) => { - return Err(io::const_io_error!( - io::ErrorKind::InvalidData, - "Windows stdio in console mode does not support writing non-UTF-8 byte sequences", - )); - } - } - } - - // As the console is meant for presenting text, we assume bytes of `data` are encoded as UTF-8, - // which needs to be encoded as UTF-16. - // - // If the data is not valid UTF-8 we write out as many bytes as are valid. - // If the first byte is invalid it is either first byte of a multi-byte sequence but the - // provided byte slice is too short or it is the first byte of an invalid multi-byte sequence. - let len = cmp::min(data.len(), MAX_BUFFER_SIZE / 2); - let utf8 = match str::from_utf8(&data[..len]) { - Ok(s) => s, - Err(ref e) if e.valid_up_to() == 0 => { - let first_byte_char_width = utf8_char_width(data[0]); - if first_byte_char_width > 1 && data.len() < first_byte_char_width { - incomplete_utf8.bytes[0] = data[0]; - incomplete_utf8.len = 1; - return Ok(1); - } else { - return Err(io::const_io_error!( - io::ErrorKind::InvalidData, - "Windows stdio in console mode does not support writing non-UTF-8 byte sequences", - )); - } - } - Err(e) => str::from_utf8(&data[..e.valid_up_to()]).unwrap(), - }; - - write_valid_utf8_to_console(handle, utf8) -} - -fn write_valid_utf8_to_console(handle: c::HANDLE, utf8: &str) -> io::Result { - debug_assert!(!utf8.is_empty()); - - let mut utf16 = [MaybeUninit::::uninit(); MAX_BUFFER_SIZE / 2]; - let utf8 = &utf8[..utf8.floor_char_boundary(utf16.len())]; - - let utf16: &[u16] = unsafe { - // Note that this theoretically checks validity twice in the (most common) case - // where the underlying byte sequence is valid utf-8 (given the check in `write()`). - let result = c::MultiByteToWideChar( - c::CP_UTF8, // CodePage - c::MB_ERR_INVALID_CHARS, // dwFlags - utf8.as_ptr(), // lpMultiByteStr - utf8.len() as c::c_int, // cbMultiByte - utf16.as_mut_ptr() as c::LPWSTR, // lpWideCharStr - utf16.len() as c::c_int, // cchWideChar - ); - assert!(result != 0, "Unexpected error in MultiByteToWideChar"); - - // Safety: MultiByteToWideChar initializes `result` values. - MaybeUninit::slice_assume_init_ref(&utf16[..result as usize]) - }; - - let mut written = write_u16s(handle, utf16)?; - - // Figure out how many bytes of as UTF-8 were written away as UTF-16. - if written == utf16.len() { - Ok(utf8.len()) - } else { - // Make sure we didn't end up writing only half of a surrogate pair (even though the chance - // is tiny). Because it is not possible for user code to re-slice `data` in such a way that - // a missing surrogate can be produced (and also because of the UTF-8 validation above), - // write the missing surrogate out now. - // Buffering it would mean we have to lie about the number of bytes written. - let first_code_unit_remaining = utf16[written]; - if matches!(first_code_unit_remaining, 0xDCEE..=0xDFFF) { - // low surrogate - // We just hope this works, and give up otherwise - let _ = write_u16s(handle, &utf16[written..written + 1]); - written += 1; - } - // Calculate the number of bytes of `utf8` that were actually written. - let mut count = 0; - for ch in utf16[..written].iter() { - count += match ch { - 0x0000..=0x007F => 1, - 0x0080..=0x07FF => 2, - 0xDCEE..=0xDFFF => 1, // Low surrogate. We already counted 3 bytes for the other. - _ => 3, - }; - } - debug_assert!(String::from_utf16(&utf16[..written]).unwrap() == utf8[..count]); - Ok(count) - } -} - -fn write_u16s(handle: c::HANDLE, data: &[u16]) -> io::Result { - debug_assert!(data.len() < u32::MAX as usize); - let mut written = 0; - cvt(unsafe { - c::WriteConsoleW( - handle, - data.as_ptr() as c::LPCVOID, - data.len() as u32, - &mut written, - ptr::null_mut(), - ) - })?; - Ok(written as usize) -} - -impl Stdin { - pub const fn new() -> Stdin { - Stdin { surrogate: 0, incomplete_utf8: IncompleteUtf8::new() } - } -} - -impl io::Read for Stdin { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - let handle = get_handle(c::STD_INPUT_HANDLE)?; - if !is_console(handle) { - unsafe { - let handle = Handle::from_raw_handle(handle); - let ret = handle.read(buf); - handle.into_raw_handle(); // Don't close the handle - return ret; - } - } - - // If there are bytes in the incomplete utf-8, start with those. - // (No-op if there is nothing in the buffer.) - let mut bytes_copied = self.incomplete_utf8.read(buf); - - if bytes_copied == buf.len() { - Ok(bytes_copied) - } else if buf.len() - bytes_copied < 4 { - // Not enough space to get a UTF-8 byte. We will use the incomplete UTF8. - let mut utf16_buf = [MaybeUninit::new(0); 1]; - // Read one u16 character. - let read = read_u16s_fixup_surrogates(handle, &mut utf16_buf, 1, &mut self.surrogate)?; - // Read bytes, using the (now-empty) self.incomplete_utf8 as extra space. - let read_bytes = utf16_to_utf8( - unsafe { MaybeUninit::slice_assume_init_ref(&utf16_buf[..read]) }, - &mut self.incomplete_utf8.bytes, - )?; - - // Read in the bytes from incomplete_utf8 until the buffer is full. - self.incomplete_utf8.len = read_bytes as u8; - // No-op if no bytes. - bytes_copied += self.incomplete_utf8.read(&mut buf[bytes_copied..]); - Ok(bytes_copied) - } else { - let mut utf16_buf = [MaybeUninit::::uninit(); MAX_BUFFER_SIZE / 2]; - - // In the worst case, a UTF-8 string can take 3 bytes for every `u16` of a UTF-16. So - // we can read at most a third of `buf.len()` chars and uphold the guarantee no data gets - // lost. - let amount = cmp::min(buf.len() / 3, utf16_buf.len()); - let read = - read_u16s_fixup_surrogates(handle, &mut utf16_buf, amount, &mut self.surrogate)?; - // Safety `read_u16s_fixup_surrogates` returns the number of items - // initialized. - let utf16s = unsafe { MaybeUninit::slice_assume_init_ref(&utf16_buf[..read]) }; - match utf16_to_utf8(utf16s, buf) { - Ok(value) => return Ok(bytes_copied + value), - Err(e) => return Err(e), - } - } - } -} - -// We assume that if the last `u16` is an unpaired surrogate they got sliced apart by our -// buffer size, and keep it around for the next read hoping to put them together. -// This is a best effort, and might not work if we are not the only reader on Stdin. -fn read_u16s_fixup_surrogates( - handle: c::HANDLE, - buf: &mut [MaybeUninit], - mut amount: usize, - surrogate: &mut u16, -) -> io::Result { - // Insert possibly remaining unpaired surrogate from last read. - let mut start = 0; - if *surrogate != 0 { - buf[0] = MaybeUninit::new(*surrogate); - *surrogate = 0; - start = 1; - if amount == 1 { - // Special case: `Stdin::read` guarantees we can always read at least one new `u16` - // and combine it with an unpaired surrogate, because the UTF-8 buffer is at least - // 4 bytes. - amount = 2; - } - } - let mut amount = read_u16s(handle, &mut buf[start..amount])? + start; - - if amount > 0 { - // Safety: The returned `amount` is the number of values initialized, - // and it is not 0, so we know that `buf[amount - 1]` have been - // initialized. - let last_char = unsafe { buf[amount - 1].assume_init() }; - if matches!(last_char, 0xD800..=0xDBFF) { - // high surrogate - *surrogate = last_char; - amount -= 1; - } - } - Ok(amount) -} - -// Returns `Ok(n)` if it initialized `n` values in `buf`. -fn read_u16s(handle: c::HANDLE, buf: &mut [MaybeUninit]) -> io::Result { - // Configure the `pInputControl` parameter to not only return on `\r\n` but also Ctrl-Z, the - // traditional DOS method to indicate end of character stream / user input (SUB). - // See #38274 and https://stackoverflow.com/questions/43836040/win-api-readconsole. - const CTRL_Z: u16 = 0x1A; - const CTRL_Z_MASK: c::ULONG = 1 << CTRL_Z; - let input_control = c::CONSOLE_READCONSOLE_CONTROL { - nLength: crate::mem::size_of::() as c::ULONG, - nInitialChars: 0, - dwCtrlWakeupMask: CTRL_Z_MASK, - dwControlKeyState: 0, - }; - - let mut amount = 0; - loop { - cvt(unsafe { - c::SetLastError(0); - c::ReadConsoleW( - handle, - buf.as_mut_ptr() as c::LPVOID, - buf.len() as u32, - &mut amount, - &input_control, - ) - })?; - - // ReadConsoleW returns success with ERROR_OPERATION_ABORTED for Ctrl-C or Ctrl-Break. - // Explicitly check for that case here and try again. - if amount == 0 && api::get_last_error().code == c::ERROR_OPERATION_ABORTED { - continue; - } - break; - } - // Safety: if `amount > 0`, then that many bytes were written, so - // `buf[amount as usize - 1]` has been initialized. - if amount > 0 && unsafe { buf[amount as usize - 1].assume_init() } == CTRL_Z { - amount -= 1; - } - Ok(amount as usize) -} - -fn utf16_to_utf8(utf16: &[u16], utf8: &mut [u8]) -> io::Result { - debug_assert!(utf16.len() <= c::c_int::MAX as usize); - debug_assert!(utf8.len() <= c::c_int::MAX as usize); - - if utf16.is_empty() { - return Ok(0); - } - - let result = unsafe { - c::WideCharToMultiByte( - c::CP_UTF8, // CodePage - c::WC_ERR_INVALID_CHARS, // dwFlags - utf16.as_ptr(), // lpWideCharStr - utf16.len() as c::c_int, // cchWideChar - utf8.as_mut_ptr(), // lpMultiByteStr - utf8.len() as c::c_int, // cbMultiByte - ptr::null(), // lpDefaultChar - ptr::null_mut(), // lpUsedDefaultChar - ) - }; - if result == 0 { - // We can't really do any better than forget all data and return an error. - Err(io::const_io_error!( - io::ErrorKind::InvalidData, - "Windows stdin in console mode does not support non-UTF-16 input; \ - encountered unpaired surrogate", - )) - } else { - Ok(result as usize) - } -} - -impl IncompleteUtf8 { - pub const fn new() -> IncompleteUtf8 { - IncompleteUtf8 { bytes: [0; 4], len: 0 } - } -} - -impl Stdout { - pub const fn new() -> Stdout { - Stdout { incomplete_utf8: IncompleteUtf8::new() } - } -} - -impl io::Write for Stdout { - fn write(&mut self, buf: &[u8]) -> io::Result { - write(c::STD_OUTPUT_HANDLE, buf, &mut self.incomplete_utf8) - } - - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -impl Stderr { - pub const fn new() -> Stderr { - Stderr { incomplete_utf8: IncompleteUtf8::new() } - } -} - -impl io::Write for Stderr { - fn write(&mut self, buf: &[u8]) -> io::Result { - write(c::STD_ERROR_HANDLE, buf, &mut self.incomplete_utf8) - } - - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -pub fn is_ebadf(err: &io::Error) -> bool { - err.raw_os_error() == Some(c::ERROR_INVALID_HANDLE as i32) -} - -pub fn panic_output() -> Option { - Some(Stderr::new()) -} diff --git a/library/std/src/sys/pal/windows/stdio/tests.rs b/library/std/src/sys/pal/windows/stdio/tests.rs deleted file mode 100644 index 1e53e0bee6369..0000000000000 --- a/library/std/src/sys/pal/windows/stdio/tests.rs +++ /dev/null @@ -1,6 +0,0 @@ -use super::utf16_to_utf8; - -#[test] -fn zero_size_read() { - assert_eq!(utf16_to_utf8(&[], &mut []).unwrap(), 0); -} diff --git a/library/std/src/sys/pal/windows/thread.rs b/library/std/src/sys/pal/windows/thread.rs deleted file mode 100644 index 70099e0a3b560..0000000000000 --- a/library/std/src/sys/pal/windows/thread.rs +++ /dev/null @@ -1,124 +0,0 @@ -use crate::ffi::CStr; -use crate::io; -use crate::num::NonZero; -use crate::os::windows::io::AsRawHandle; -use crate::os::windows::io::HandleOrNull; -use crate::ptr; -use crate::sys::c; -use crate::sys::handle::Handle; -use crate::sys::stack_overflow; -use crate::sys_common::FromInner; -use crate::time::Duration; -use core::ffi::c_void; - -use super::time::WaitableTimer; -use super::to_u16s; - -pub const DEFAULT_MIN_STACK_SIZE: usize = 2 * 1024 * 1024; - -pub struct Thread { - handle: Handle, -} - -impl Thread { - // unsafe: see thread::Builder::spawn_unchecked for safety requirements - pub unsafe fn new(stack: usize, p: Box) -> io::Result { - let p = Box::into_raw(Box::new(p)); - - // CreateThread rounds up values for the stack size to the nearest page size (at least 4kb). - // If a value of zero is given then the default stack size is used instead. - let ret = c::CreateThread( - ptr::null_mut(), - stack, - Some(thread_start), - p as *mut _, - c::STACK_SIZE_PARAM_IS_A_RESERVATION, - ptr::null_mut(), - ); - let ret = HandleOrNull::from_raw_handle(ret); - return if let Ok(handle) = ret.try_into() { - Ok(Thread { handle: Handle::from_inner(handle) }) - } else { - // The thread failed to start and as a result p was not consumed. Therefore, it is - // safe to reconstruct the box so that it gets deallocated. - drop(Box::from_raw(p)); - Err(io::Error::last_os_error()) - }; - - unsafe extern "system" fn thread_start(main: *mut c_void) -> c::DWORD { - // Next, reserve some stack space for if we otherwise run out of stack. - stack_overflow::reserve_stack(); - // Finally, let's run some code. - Box::from_raw(main as *mut Box)(); - 0 - } - } - - pub fn set_name(name: &CStr) { - if let Ok(utf8) = name.to_str() { - if let Ok(utf16) = to_u16s(utf8) { - unsafe { - // SAFETY: the vec returned by `to_u16s` ends with a zero value - Self::set_name_wide(&utf16) - } - }; - }; - } - - /// # Safety - /// - /// `name` must end with a zero value - pub unsafe fn set_name_wide(name: &[u16]) { - c::SetThreadDescription(c::GetCurrentThread(), name.as_ptr()); - } - - pub fn join(self) { - let rc = unsafe { c::WaitForSingleObject(self.handle.as_raw_handle(), c::INFINITE) }; - if rc == c::WAIT_FAILED { - panic!("failed to join on thread: {}", io::Error::last_os_error()); - } - } - - pub fn yield_now() { - // This function will return 0 if there are no other threads to execute, - // but this also means that the yield was useless so this isn't really a - // case that needs to be worried about. - unsafe { - c::SwitchToThread(); - } - } - - pub fn sleep(dur: Duration) { - fn high_precision_sleep(dur: Duration) -> Result<(), ()> { - let timer = WaitableTimer::high_resolution()?; - timer.set(dur)?; - timer.wait() - } - // Attempt to use high-precision sleep (Windows 10, version 1803+). - // On error fallback to the standard `Sleep` function. - // Also preserves the zero duration behaviour of `Sleep`. - if dur.is_zero() || high_precision_sleep(dur).is_err() { - unsafe { c::Sleep(super::dur2timeout(dur)) } - } - } - - pub fn handle(&self) -> &Handle { - &self.handle - } - - pub fn into_handle(self) -> Handle { - self.handle - } -} - -pub fn available_parallelism() -> io::Result> { - let res = unsafe { - let mut sysinfo: c::SYSTEM_INFO = crate::mem::zeroed(); - c::GetSystemInfo(&mut sysinfo); - sysinfo.dwNumberOfProcessors as usize - }; - match res { - 0 => Err(io::Error::UNKNOWN_THREAD_COUNT), - cpus => Ok(unsafe { NonZero::new_unchecked(cpus) }), - } -} diff --git a/library/std/src/sys/pal/windows/thread_local_dtor.rs b/library/std/src/sys/pal/windows/thread_local_dtor.rs deleted file mode 100644 index cf542d2bfb838..0000000000000 --- a/library/std/src/sys/pal/windows/thread_local_dtor.rs +++ /dev/null @@ -1,7 +0,0 @@ -//! Implements thread-local destructors that are not associated with any -//! particular data. - -#![unstable(feature = "thread_local_internals", issue = "none")] -#![cfg(target_thread_local)] - -pub use super::thread_local_key::register_keyless_dtor as register_dtor; diff --git a/library/std/src/sys/pal/windows/thread_local_key.rs b/library/std/src/sys/pal/windows/thread_local_key.rs deleted file mode 100644 index e5ba619fc6ba4..0000000000000 --- a/library/std/src/sys/pal/windows/thread_local_key.rs +++ /dev/null @@ -1,351 +0,0 @@ -use crate::cell::UnsafeCell; -use crate::ptr; -use crate::sync::atomic::{ - AtomicPtr, AtomicU32, - Ordering::{AcqRel, Acquire, Relaxed, Release}, -}; -use crate::sys::c; - -#[cfg(test)] -mod tests; - -// Using a per-thread list avoids the problems in synchronizing global state. -#[thread_local] -#[cfg(target_thread_local)] -static DESTRUCTORS: crate::cell::RefCell> = - crate::cell::RefCell::new(Vec::new()); - -// Ensure this can never be inlined because otherwise this may break in dylibs. -// See #44391. -#[inline(never)] -#[cfg(target_thread_local)] -pub unsafe fn register_keyless_dtor(t: *mut u8, dtor: unsafe extern "C" fn(*mut u8)) { - dtors_used(); - match DESTRUCTORS.try_borrow_mut() { - Ok(mut dtors) => dtors.push((t, dtor)), - Err(_) => rtabort!("global allocator may not use TLS"), - } -} - -#[inline(never)] // See comment above -#[cfg(target_thread_local)] -/// Runs destructors. This should not be called until thread exit. -unsafe fn run_keyless_dtors() { - // Drop all the destructors. - // - // Note: While this is potentially an infinite loop, it *should* be - // the case that this loop always terminates because we provide the - // guarantee that a TLS key cannot be set after it is flagged for - // destruction. - loop { - // Use a let-else binding to ensure the `RefCell` guard is dropped - // immediately. Otherwise, a panic would occur if a TLS destructor - // tries to access the list. - let Some((ptr, dtor)) = DESTRUCTORS.borrow_mut().pop() else { - break; - }; - (dtor)(ptr); - } - // We're done so free the memory. - DESTRUCTORS.replace(Vec::new()); -} - -type Key = c::DWORD; -type Dtor = unsafe extern "C" fn(*mut u8); - -// Turns out, like pretty much everything, Windows is pretty close the -// functionality that Unix provides, but slightly different! In the case of -// TLS, Windows does not provide an API to provide a destructor for a TLS -// variable. This ends up being pretty crucial to this implementation, so we -// need a way around this. -// -// The solution here ended up being a little obscure, but fear not, the -// internet has informed me [1][2] that this solution is not unique (no way -// I could have thought of it as well!). The key idea is to insert some hook -// somewhere to run arbitrary code on thread termination. With this in place -// we'll be able to run anything we like, including all TLS destructors! -// -// To accomplish this feat, we perform a number of threads, all contained -// within this module: -// -// * All TLS destructors are tracked by *us*, not the Windows runtime. This -// means that we have a global list of destructors for each TLS key that -// we know about. -// * When a thread exits, we run over the entire list and run dtors for all -// non-null keys. This attempts to match Unix semantics in this regard. -// -// For more details and nitty-gritty, see the code sections below! -// -// [1]: https://www.codeproject.com/Articles/8113/Thread-Local-Storage-The-C-Way -// [2]: https://github.com/ChromiumWebApps/chromium/blob/master/base/threading/thread_local_storage_win.cc#L42 - -pub struct StaticKey { - /// The key value shifted up by one. Since TLS_OUT_OF_INDEXES == DWORD::MAX - /// is not a valid key value, this allows us to use zero as sentinel value - /// without risking overflow. - key: AtomicU32, - dtor: Option, - next: AtomicPtr, - /// Currently, destructors cannot be unregistered, so we cannot use racy - /// initialization for keys. Instead, we need synchronize initialization. - /// Use the Windows-provided `Once` since it does not require TLS. - once: UnsafeCell, -} - -impl StaticKey { - #[inline] - pub const fn new(dtor: Option) -> StaticKey { - StaticKey { - key: AtomicU32::new(0), - dtor, - next: AtomicPtr::new(ptr::null_mut()), - once: UnsafeCell::new(c::INIT_ONCE_STATIC_INIT), - } - } - - #[inline] - pub unsafe fn set(&'static self, val: *mut u8) { - let r = c::TlsSetValue(self.key(), val.cast()); - debug_assert_eq!(r, c::TRUE); - } - - #[inline] - pub unsafe fn get(&'static self) -> *mut u8 { - c::TlsGetValue(self.key()).cast() - } - - #[inline] - unsafe fn key(&'static self) -> Key { - match self.key.load(Acquire) { - 0 => self.init(), - key => key - 1, - } - } - - #[cold] - unsafe fn init(&'static self) -> Key { - if self.dtor.is_some() { - dtors_used(); - let mut pending = c::FALSE; - let r = c::InitOnceBeginInitialize(self.once.get(), 0, &mut pending, ptr::null_mut()); - assert_eq!(r, c::TRUE); - - if pending == c::FALSE { - // Some other thread initialized the key, load it. - self.key.load(Relaxed) - 1 - } else { - let key = c::TlsAlloc(); - if key == c::TLS_OUT_OF_INDEXES { - // Wakeup the waiting threads before panicking to avoid deadlock. - c::InitOnceComplete(self.once.get(), c::INIT_ONCE_INIT_FAILED, ptr::null_mut()); - panic!("out of TLS indexes"); - } - - register_dtor(self); - - // Release-storing the key needs to be the last thing we do. - // This is because in `fn key()`, other threads will do an acquire load of the key, - // and if that sees this write then it will entirely bypass the `InitOnce`. We thus - // need to establish synchronization through `key`. In particular that acquire load - // must happen-after the register_dtor above, to ensure the dtor actually runs! - self.key.store(key + 1, Release); - - let r = c::InitOnceComplete(self.once.get(), 0, ptr::null_mut()); - debug_assert_eq!(r, c::TRUE); - - key - } - } else { - // If there is no destructor to clean up, we can use racy initialization. - - let key = c::TlsAlloc(); - assert_ne!(key, c::TLS_OUT_OF_INDEXES, "out of TLS indexes"); - - match self.key.compare_exchange(0, key + 1, AcqRel, Acquire) { - Ok(_) => key, - Err(new) => { - // Some other thread completed initialization first, so destroy - // our key and use theirs. - let r = c::TlsFree(key); - debug_assert_eq!(r, c::TRUE); - new - 1 - } - } - } - } -} - -unsafe impl Send for StaticKey {} -unsafe impl Sync for StaticKey {} - -// ------------------------------------------------------------------------- -// Dtor registration -// -// Windows has no native support for running destructors so we manage our own -// list of destructors to keep track of how to destroy keys. We then install a -// callback later to get invoked whenever a thread exits, running all -// appropriate destructors. -// -// Currently unregistration from this list is not supported. A destructor can be -// registered but cannot be unregistered. There's various simplifying reasons -// for doing this, the big ones being: -// -// 1. Currently we don't even support deallocating TLS keys, so normal operation -// doesn't need to deallocate a destructor. -// 2. There is no point in time where we know we can unregister a destructor -// because it could always be getting run by some remote thread. -// -// Typically processes have a statically known set of TLS keys which is pretty -// small, and we'd want to keep this memory alive for the whole process anyway -// really. - -static DTORS: AtomicPtr = AtomicPtr::new(ptr::null_mut()); - -/// Should only be called once per key, otherwise loops or breaks may occur in -/// the linked list. -unsafe fn register_dtor(key: &'static StaticKey) { - // Ensure this is never run when native thread locals are available. - assert_eq!(false, cfg!(target_thread_local)); - let this = <*const StaticKey>::cast_mut(key); - // Use acquire ordering to pass along the changes done by the previously - // registered keys when we store the new head with release ordering. - let mut head = DTORS.load(Acquire); - loop { - key.next.store(head, Relaxed); - match DTORS.compare_exchange_weak(head, this, Release, Acquire) { - Ok(_) => break, - Err(new) => head = new, - } - } -} - -// ------------------------------------------------------------------------- -// Where the Magic (TM) Happens -// -// If you're looking at this code, and wondering "what is this doing?", -// you're not alone! I'll try to break this down step by step: -// -// # What's up with CRT$XLB? -// -// For anything about TLS destructors to work on Windows, we have to be able -// to run *something* when a thread exits. To do so, we place a very special -// static in a very special location. If this is encoded in just the right -// way, the kernel's loader is apparently nice enough to run some function -// of ours whenever a thread exits! How nice of the kernel! -// -// Lots of detailed information can be found in source [1] above, but the -// gist of it is that this is leveraging a feature of Microsoft's PE format -// (executable format) which is not actually used by any compilers today. -// This apparently translates to any callbacks in the ".CRT$XLB" section -// being run on certain events. -// -// So after all that, we use the compiler's #[link_section] feature to place -// a callback pointer into the magic section so it ends up being called. -// -// # What's up with this callback? -// -// The callback specified receives a number of parameters from... someone! -// (the kernel? the runtime? I'm not quite sure!) There are a few events that -// this gets invoked for, but we're currently only interested on when a -// thread or a process "detaches" (exits). The process part happens for the -// last thread and the thread part happens for any normal thread. -// -// # Ok, what's up with running all these destructors? -// -// This will likely need to be improved over time, but this function -// attempts a "poor man's" destructor callback system. Once we've got a list -// of what to run, we iterate over all keys, check their values, and then run -// destructors if the values turn out to be non null (setting them to null just -// beforehand). We do this a few times in a loop to basically match Unix -// semantics. If we don't reach a fixed point after a short while then we just -// inevitably leak something most likely. -// -// # The article mentions weird stuff about "/INCLUDE"? -// -// It sure does! Specifically we're talking about this quote: -// -// The Microsoft run-time library facilitates this process by defining a -// memory image of the TLS Directory and giving it the special name -// “__tls_used” (Intel x86 platforms) or “_tls_used” (other platforms). The -// linker looks for this memory image and uses the data there to create the -// TLS Directory. Other compilers that support TLS and work with the -// Microsoft linker must use this same technique. -// -// Basically what this means is that if we want support for our TLS -// destructors/our hook being called then we need to make sure the linker does -// not omit this symbol. Otherwise it will omit it and our callback won't be -// wired up. -// -// We don't actually use the `/INCLUDE` linker flag here like the article -// mentions because the Rust compiler doesn't propagate linker flags, but -// instead we use a shim function which performs a volatile 1-byte load from -// the address of the symbol to ensure it sticks around. - -#[link_section = ".CRT$XLB"] -#[cfg_attr(miri, used)] // Miri only considers explicitly `#[used]` statics for `lookup_link_section` -pub static p_thread_callback: unsafe extern "system" fn(c::LPVOID, c::DWORD, c::LPVOID) = - on_tls_callback; - -fn dtors_used() { - // we don't want LLVM eliminating p_thread_callback when destructors are used. - // when the symbol makes it to the linker the linker will take over - unsafe { crate::intrinsics::volatile_load(&p_thread_callback) }; -} - -unsafe extern "system" fn on_tls_callback(_h: c::LPVOID, dwReason: c::DWORD, _pv: c::LPVOID) { - if dwReason == c::DLL_THREAD_DETACH || dwReason == c::DLL_PROCESS_DETACH { - #[cfg(not(target_thread_local))] - run_dtors(); - #[cfg(target_thread_local)] - run_keyless_dtors(); - } - - // See comments above for what this is doing. Note that we don't need this - // trickery on GNU windows, just on MSVC. - #[cfg(all(target_env = "msvc", not(target_thread_local)))] - { - extern "C" { - static _tls_used: u8; - } - crate::intrinsics::volatile_load(&_tls_used); - } -} - -#[cfg(not(target_thread_local))] -unsafe fn run_dtors() { - for _ in 0..5 { - let mut any_run = false; - - // Use acquire ordering to observe key initialization. - let mut cur = DTORS.load(Acquire); - while !cur.is_null() { - let pre_key = (*cur).key.load(Acquire); - let dtor = (*cur).dtor.unwrap(); - cur = (*cur).next.load(Relaxed); - - // In StaticKey::init, we register the dtor before setting `key`. - // So if one thread's `run_dtors` races with another thread executing `init` on the same - // `StaticKey`, we can encounter a key of 0 here. That means this key was never - // initialized in this thread so we can safely skip it. - if pre_key == 0 { - continue; - } - // If this is non-zero, then via the `Acquire` load above we synchronized with - // everything relevant for this key. (It's not clear that this is needed, since the - // release-acquire pair on DTORS also establishes synchronization, but better safe than - // sorry.) - let key = pre_key - 1; - - let ptr = c::TlsGetValue(key); - if !ptr.is_null() { - c::TlsSetValue(key, ptr::null_mut()); - dtor(ptr as *mut _); - any_run = true; - } - } - - if !any_run { - break; - } - } -} diff --git a/library/std/src/sys/pal/windows/thread_local_key/tests.rs b/library/std/src/sys/pal/windows/thread_local_key/tests.rs deleted file mode 100644 index 4119f99096842..0000000000000 --- a/library/std/src/sys/pal/windows/thread_local_key/tests.rs +++ /dev/null @@ -1,57 +0,0 @@ -// This file only tests the thread local key fallback. -// Windows targets with native thread local support do not use this. -#![cfg(not(target_thread_local))] - -use super::StaticKey; -use crate::ptr; - -#[test] -fn smoke() { - static K1: StaticKey = StaticKey::new(None); - static K2: StaticKey = StaticKey::new(None); - - unsafe { - assert!(K1.get().is_null()); - assert!(K2.get().is_null()); - K1.set(ptr::without_provenance_mut(1)); - K2.set(ptr::without_provenance_mut(2)); - assert_eq!(K1.get() as usize, 1); - assert_eq!(K2.get() as usize, 2); - } -} - -#[test] -fn destructors() { - use crate::mem::ManuallyDrop; - use crate::sync::Arc; - use crate::thread; - - unsafe extern "C" fn destruct(ptr: *mut u8) { - drop(Arc::from_raw(ptr as *const ())); - } - - static KEY: StaticKey = StaticKey::new(Some(destruct)); - - let shared1 = Arc::new(()); - let shared2 = Arc::clone(&shared1); - - unsafe { - assert!(KEY.get().is_null()); - KEY.set(Arc::into_raw(shared1) as *mut u8); - } - - thread::spawn(move || unsafe { - assert!(KEY.get().is_null()); - KEY.set(Arc::into_raw(shared2) as *mut u8); - }) - .join() - .unwrap(); - - // Leak the Arc, let the TLS destructor clean it up. - let shared1 = unsafe { ManuallyDrop::new(Arc::from_raw(KEY.get() as *const ())) }; - assert_eq!( - Arc::strong_count(&shared1), - 1, - "destructor should have dropped the other reference on thread exit" - ); -} diff --git a/library/std/src/sys/pal/windows/time.rs b/library/std/src/sys/pal/windows/time.rs deleted file mode 100644 index 09e78a29304f9..0000000000000 --- a/library/std/src/sys/pal/windows/time.rs +++ /dev/null @@ -1,262 +0,0 @@ -use crate::cmp::Ordering; -use crate::fmt; -use crate::mem; -use crate::ptr::null; -use crate::sys::c; -use crate::sys_common::IntoInner; -use crate::time::Duration; - -use core::hash::{Hash, Hasher}; -use core::ops::Neg; - -const NANOS_PER_SEC: u64 = 1_000_000_000; -const INTERVALS_PER_SEC: u64 = NANOS_PER_SEC / 100; - -#[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Debug, Hash)] -pub struct Instant { - // This duration is relative to an arbitrary microsecond epoch - // from the winapi QueryPerformanceCounter function. - t: Duration, -} - -#[derive(Copy, Clone)] -pub struct SystemTime { - t: c::FILETIME, -} - -const INTERVALS_TO_UNIX_EPOCH: u64 = 11_644_473_600 * INTERVALS_PER_SEC; - -pub const UNIX_EPOCH: SystemTime = SystemTime { - t: c::FILETIME { - dwLowDateTime: INTERVALS_TO_UNIX_EPOCH as u32, - dwHighDateTime: (INTERVALS_TO_UNIX_EPOCH >> 32) as u32, - }, -}; - -impl Instant { - pub fn now() -> Instant { - // High precision timing on windows operates in "Performance Counter" - // units, as returned by the WINAPI QueryPerformanceCounter function. - // These relate to seconds by a factor of QueryPerformanceFrequency. - // In order to keep unit conversions out of normal interval math, we - // measure in QPC units and immediately convert to nanoseconds. - perf_counter::PerformanceCounterInstant::now().into() - } - - pub fn checked_sub_instant(&self, other: &Instant) -> Option { - // On windows there's a threshold below which we consider two timestamps - // equivalent due to measurement error. For more details + doc link, - // check the docs on epsilon. - let epsilon = perf_counter::PerformanceCounterInstant::epsilon(); - if other.t > self.t && other.t - self.t <= epsilon { - Some(Duration::new(0, 0)) - } else { - self.t.checked_sub(other.t) - } - } - - pub fn checked_add_duration(&self, other: &Duration) -> Option { - Some(Instant { t: self.t.checked_add(*other)? }) - } - - pub fn checked_sub_duration(&self, other: &Duration) -> Option { - Some(Instant { t: self.t.checked_sub(*other)? }) - } -} - -impl SystemTime { - pub fn now() -> SystemTime { - unsafe { - let mut t: SystemTime = mem::zeroed(); - c::GetSystemTimePreciseAsFileTime(&mut t.t); - t - } - } - - fn from_intervals(intervals: i64) -> SystemTime { - SystemTime { - t: c::FILETIME { - dwLowDateTime: intervals as c::DWORD, - dwHighDateTime: (intervals >> 32) as c::DWORD, - }, - } - } - - fn intervals(&self) -> i64 { - (self.t.dwLowDateTime as i64) | ((self.t.dwHighDateTime as i64) << 32) - } - - pub fn sub_time(&self, other: &SystemTime) -> Result { - let me = self.intervals(); - let other = other.intervals(); - if me >= other { - Ok(intervals2dur((me - other) as u64)) - } else { - Err(intervals2dur((other - me) as u64)) - } - } - - pub fn checked_add_duration(&self, other: &Duration) -> Option { - let intervals = self.intervals().checked_add(checked_dur2intervals(other)?)?; - Some(SystemTime::from_intervals(intervals)) - } - - pub fn checked_sub_duration(&self, other: &Duration) -> Option { - let intervals = self.intervals().checked_sub(checked_dur2intervals(other)?)?; - Some(SystemTime::from_intervals(intervals)) - } -} - -impl PartialEq for SystemTime { - fn eq(&self, other: &SystemTime) -> bool { - self.intervals() == other.intervals() - } -} - -impl Eq for SystemTime {} - -impl PartialOrd for SystemTime { - fn partial_cmp(&self, other: &SystemTime) -> Option { - Some(self.cmp(other)) - } -} - -impl Ord for SystemTime { - fn cmp(&self, other: &SystemTime) -> Ordering { - self.intervals().cmp(&other.intervals()) - } -} - -impl fmt::Debug for SystemTime { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("SystemTime").field("intervals", &self.intervals()).finish() - } -} - -impl From for SystemTime { - fn from(t: c::FILETIME) -> SystemTime { - SystemTime { t } - } -} - -impl IntoInner for SystemTime { - fn into_inner(self) -> c::FILETIME { - self.t - } -} - -impl Hash for SystemTime { - fn hash(&self, state: &mut H) { - self.intervals().hash(state) - } -} - -fn checked_dur2intervals(dur: &Duration) -> Option { - dur.as_secs() - .checked_mul(INTERVALS_PER_SEC)? - .checked_add(dur.subsec_nanos() as u64 / 100)? - .try_into() - .ok() -} - -fn intervals2dur(intervals: u64) -> Duration { - Duration::new(intervals / INTERVALS_PER_SEC, ((intervals % INTERVALS_PER_SEC) * 100) as u32) -} - -mod perf_counter { - use super::NANOS_PER_SEC; - use crate::sync::atomic::{AtomicU64, Ordering}; - use crate::sys::c; - use crate::sys::cvt; - use crate::sys_common::mul_div_u64; - use crate::time::Duration; - - pub struct PerformanceCounterInstant { - ts: c::LARGE_INTEGER, - } - impl PerformanceCounterInstant { - pub fn now() -> Self { - Self { ts: query() } - } - - // Per microsoft docs, the margin of error for cross-thread time comparisons - // using QueryPerformanceCounter is 1 "tick" -- defined as 1/frequency(). - // Reference: https://docs.microsoft.com/en-us/windows/desktop/SysInfo - // /acquiring-high-resolution-time-stamps - pub fn epsilon() -> Duration { - let epsilon = NANOS_PER_SEC / (frequency() as u64); - Duration::from_nanos(epsilon) - } - } - impl From for super::Instant { - fn from(other: PerformanceCounterInstant) -> Self { - let freq = frequency() as u64; - let instant_nsec = mul_div_u64(other.ts as u64, NANOS_PER_SEC, freq); - Self { t: Duration::from_nanos(instant_nsec) } - } - } - - fn frequency() -> c::LARGE_INTEGER { - // Either the cached result of `QueryPerformanceFrequency` or `0` for - // uninitialized. Storing this as a single `AtomicU64` allows us to use - // `Relaxed` operations, as we are only interested in the effects on a - // single memory location. - static FREQUENCY: AtomicU64 = AtomicU64::new(0); - - let cached = FREQUENCY.load(Ordering::Relaxed); - // If a previous thread has filled in this global state, use that. - if cached != 0 { - return cached as c::LARGE_INTEGER; - } - // ... otherwise learn for ourselves ... - let mut frequency = 0; - unsafe { - cvt(c::QueryPerformanceFrequency(&mut frequency)).unwrap(); - } - - FREQUENCY.store(frequency as u64, Ordering::Relaxed); - frequency - } - - fn query() -> c::LARGE_INTEGER { - let mut qpc_value: c::LARGE_INTEGER = 0; - cvt(unsafe { c::QueryPerformanceCounter(&mut qpc_value) }).unwrap(); - qpc_value - } -} - -/// A timer you can wait on. -pub(super) struct WaitableTimer { - handle: c::HANDLE, -} -impl WaitableTimer { - /// Create a high-resolution timer. Will fail before Windows 10, version 1803. - pub fn high_resolution() -> Result { - let handle = unsafe { - c::CreateWaitableTimerExW( - null(), - null(), - c::CREATE_WAITABLE_TIMER_HIGH_RESOLUTION, - c::TIMER_ALL_ACCESS, - ) - }; - if !handle.is_null() { Ok(Self { handle }) } else { Err(()) } - } - pub fn set(&self, duration: Duration) -> Result<(), ()> { - // Convert the Duration to a format similar to FILETIME. - // Negative values are relative times whereas positive values are absolute. - // Therefore we negate the relative duration. - let time = checked_dur2intervals(&duration).ok_or(())?.neg(); - let result = unsafe { c::SetWaitableTimer(self.handle, &time, 0, None, null(), c::FALSE) }; - if result != 0 { Ok(()) } else { Err(()) } - } - pub fn wait(&self) -> Result<(), ()> { - let result = unsafe { c::WaitForSingleObject(self.handle, c::INFINITE) }; - if result != c::WAIT_FAILED { Ok(()) } else { Err(()) } - } -} -impl Drop for WaitableTimer { - fn drop(&mut self) { - unsafe { c::CloseHandle(self.handle) }; - } -} diff --git a/library/std/src/sys/pal/xous/alloc.rs b/library/std/src/sys/pal/xous/alloc.rs deleted file mode 100644 index 601411173aacb..0000000000000 --- a/library/std/src/sys/pal/xous/alloc.rs +++ /dev/null @@ -1,73 +0,0 @@ -use crate::alloc::{GlobalAlloc, Layout, System}; - -#[cfg(not(test))] -#[export_name = "_ZN16__rust_internals3std3sys4xous5alloc8DLMALLOCE"] -static mut DLMALLOC: dlmalloc::Dlmalloc = dlmalloc::Dlmalloc::new(); - -#[cfg(test)] -extern "Rust" { - #[link_name = "_ZN16__rust_internals3std3sys4xous5alloc8DLMALLOCE"] - static mut DLMALLOC: dlmalloc::Dlmalloc; -} - -#[stable(feature = "alloc_system_type", since = "1.28.0")] -unsafe impl GlobalAlloc for System { - #[inline] - unsafe fn alloc(&self, layout: Layout) -> *mut u8 { - // SAFETY: DLMALLOC access is guaranteed to be safe because the lock gives us unique and non-reentrant access. - // Calling malloc() is safe because preconditions on this function match the trait method preconditions. - let _lock = lock::lock(); - unsafe { DLMALLOC.malloc(layout.size(), layout.align()) } - } - - #[inline] - unsafe fn alloc_zeroed(&self, layout: Layout) -> *mut u8 { - // SAFETY: DLMALLOC access is guaranteed to be safe because the lock gives us unique and non-reentrant access. - // Calling calloc() is safe because preconditions on this function match the trait method preconditions. - let _lock = lock::lock(); - unsafe { DLMALLOC.calloc(layout.size(), layout.align()) } - } - - #[inline] - unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout) { - // SAFETY: DLMALLOC access is guaranteed to be safe because the lock gives us unique and non-reentrant access. - // Calling free() is safe because preconditions on this function match the trait method preconditions. - let _lock = lock::lock(); - unsafe { DLMALLOC.free(ptr, layout.size(), layout.align()) } - } - - #[inline] - unsafe fn realloc(&self, ptr: *mut u8, layout: Layout, new_size: usize) -> *mut u8 { - // SAFETY: DLMALLOC access is guaranteed to be safe because the lock gives us unique and non-reentrant access. - // Calling realloc() is safe because preconditions on this function match the trait method preconditions. - let _lock = lock::lock(); - unsafe { DLMALLOC.realloc(ptr, layout.size(), layout.align(), new_size) } - } -} - -mod lock { - use crate::sync::atomic::{ - AtomicI32, - Ordering::{Acquire, Release}, - }; - - static LOCKED: AtomicI32 = AtomicI32::new(0); - - pub struct DropLock; - - pub fn lock() -> DropLock { - loop { - if LOCKED.swap(1, Acquire) == 0 { - return DropLock; - } - crate::os::xous::ffi::do_yield(); - } - } - - impl Drop for DropLock { - fn drop(&mut self) { - let r = LOCKED.swap(0, Release); - debug_assert_eq!(r, 1); - } - } -} diff --git a/library/std/src/sys/pal/xous/mod.rs b/library/std/src/sys/pal/xous/mod.rs deleted file mode 100644 index 68189bcc2e377..0000000000000 --- a/library/std/src/sys/pal/xous/mod.rs +++ /dev/null @@ -1,25 +0,0 @@ -#![deny(unsafe_op_in_unsafe_fn)] - -pub mod alloc; -#[path = "../unsupported/args.rs"] -pub mod args; -#[path = "../unsupported/env.rs"] -pub mod env; -#[path = "../unsupported/fs.rs"] -pub mod fs; -#[path = "../unsupported/io.rs"] -pub mod io; -pub mod net; -pub mod os; -#[path = "../unsupported/pipe.rs"] -pub mod pipe; -#[path = "../unsupported/process.rs"] -pub mod process; -pub mod stdio; -pub mod thread; -pub mod thread_local_key; -pub mod time; - -#[path = "../unsupported/common.rs"] -mod common; -pub use common::*; diff --git a/library/std/src/sys/pal/xous/net/dns.rs b/library/std/src/sys/pal/xous/net/dns.rs deleted file mode 100644 index 63056324bfbd9..0000000000000 --- a/library/std/src/sys/pal/xous/net/dns.rs +++ /dev/null @@ -1,127 +0,0 @@ -use crate::io; -use crate::net::{Ipv4Addr, SocketAddr, SocketAddrV4, SocketAddrV6}; -use crate::os::xous::ffi::lend_mut; -use crate::os::xous::services::{dns_server, DnsLendMut}; -use core::convert::{TryFrom, TryInto}; - -pub struct DnsError { - pub code: u8, -} - -#[repr(C, align(4096))] -struct LookupHostQuery([u8; 4096]); - -pub struct LookupHost { - data: LookupHostQuery, - port: u16, - offset: usize, - count: usize, -} - -impl LookupHost { - pub fn port(&self) -> u16 { - self.port - } -} - -impl Iterator for LookupHost { - type Item = SocketAddr; - fn next(&mut self) -> Option { - if self.offset >= self.data.0.len() { - return None; - } - match self.data.0.get(self.offset) { - Some(&4) => { - self.offset += 1; - if self.offset + 4 > self.data.0.len() { - return None; - } - let result = Some(SocketAddr::V4(SocketAddrV4::new( - Ipv4Addr::new( - self.data.0[self.offset], - self.data.0[self.offset + 1], - self.data.0[self.offset + 2], - self.data.0[self.offset + 3], - ), - self.port, - ))); - self.offset += 4; - result - } - Some(&6) => { - self.offset += 1; - if self.offset + 16 > self.data.0.len() { - return None; - } - let mut new_addr = [0u8; 16]; - for (src, octet) in self.data.0[(self.offset + 1)..(self.offset + 16 + 1)] - .iter() - .zip(new_addr.iter_mut()) - { - *octet = *src; - } - let result = - Some(SocketAddr::V6(SocketAddrV6::new(new_addr.into(), self.port, 0, 0))); - self.offset += 16; - result - } - _ => None, - } - } -} - -pub fn lookup(query: &str, port: u16) -> Result { - let mut result = LookupHost { data: LookupHostQuery([0u8; 4096]), offset: 0, count: 0, port }; - - // Copy the query into the message that gets sent to the DNS server - for (query_byte, result_byte) in query.as_bytes().iter().zip(result.data.0.iter_mut()) { - *result_byte = *query_byte; - } - - lend_mut( - dns_server(), - DnsLendMut::RawLookup.into(), - &mut result.data.0, - 0, - query.as_bytes().len(), - ) - .unwrap(); - if result.data.0[0] != 0 { - return Err(DnsError { code: result.data.0[1] }); - } - assert_eq!(result.offset, 0); - result.count = result.data.0[1] as usize; - - // Advance the offset to the first record - result.offset = 2; - Ok(result) -} - -impl TryFrom<&str> for LookupHost { - type Error = io::Error; - - fn try_from(s: &str) -> io::Result { - macro_rules! try_opt { - ($e:expr, $msg:expr) => { - match $e { - Some(r) => r, - None => return Err(io::const_io_error!(io::ErrorKind::InvalidInput, &$msg)), - } - }; - } - - // split the string by ':' and convert the second part to u16 - let (host, port_str) = try_opt!(s.rsplit_once(':'), "invalid socket address"); - let port: u16 = try_opt!(port_str.parse().ok(), "invalid port value"); - (host, port).try_into() - } -} - -impl TryFrom<(&str, u16)> for LookupHost { - type Error = io::Error; - - fn try_from(v: (&str, u16)) -> io::Result { - lookup(v.0, v.1) - .map_err(|_e| io::const_io_error!(io::ErrorKind::InvalidInput, &"DNS failure")) - } -} diff --git a/library/std/src/sys/pal/xous/net/mod.rs b/library/std/src/sys/pal/xous/net/mod.rs deleted file mode 100644 index dd8b765aa74ae..0000000000000 --- a/library/std/src/sys/pal/xous/net/mod.rs +++ /dev/null @@ -1,81 +0,0 @@ -mod dns; - -mod tcpstream; -pub use tcpstream::*; - -mod tcplistener; -pub use tcplistener::*; - -mod udp; -pub use udp::*; - -// this structure needs to be synchronized with what's in net/src/api.rs -#[repr(C)] -#[derive(Debug)] -enum NetError { - // Ok = 0, - Unaddressable = 1, - SocketInUse = 2, - // AccessDenied = 3, - Invalid = 4, - // Finished = 5, - LibraryError = 6, - // AlreadyUsed = 7, - TimedOut = 8, - WouldBlock = 9, -} - -#[repr(C, align(4096))] -struct ConnectRequest { - raw: [u8; 4096], -} - -#[repr(C, align(4096))] -struct SendData { - raw: [u8; 4096], -} - -#[repr(C, align(4096))] -pub struct ReceiveData { - raw: [u8; 4096], -} - -#[repr(C, align(4096))] -pub struct GetAddress { - raw: [u8; 4096], -} - -pub use dns::LookupHost; - -#[allow(nonstandard_style)] -pub mod netc { - pub const AF_INET: u8 = 0; - pub const AF_INET6: u8 = 1; - pub type sa_family_t = u8; - - #[derive(Copy, Clone)] - pub struct in_addr { - pub s_addr: u32, - } - - #[derive(Copy, Clone)] - pub struct sockaddr_in { - pub sin_family: sa_family_t, - pub sin_port: u16, - pub sin_addr: in_addr, - } - - #[derive(Copy, Clone)] - pub struct in6_addr { - pub s6_addr: [u8; 16], - } - - #[derive(Copy, Clone)] - pub struct sockaddr_in6 { - pub sin6_family: sa_family_t, - pub sin6_port: u16, - pub sin6_addr: in6_addr, - pub sin6_flowinfo: u32, - pub sin6_scope_id: u32, - } -} diff --git a/library/std/src/sys/pal/xous/net/tcplistener.rs b/library/std/src/sys/pal/xous/net/tcplistener.rs deleted file mode 100644 index 47305013083c8..0000000000000 --- a/library/std/src/sys/pal/xous/net/tcplistener.rs +++ /dev/null @@ -1,247 +0,0 @@ -use super::*; -use crate::fmt; -use crate::io; -use crate::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr}; -use crate::os::xous::services; -use crate::sync::Arc; -use core::convert::TryInto; -use core::sync::atomic::{AtomicBool, AtomicU16, AtomicUsize, Ordering}; - -macro_rules! unimpl { - () => { - return Err(io::const_io_error!( - io::ErrorKind::Unsupported, - &"This function is not yet implemented", - )); - }; -} - -#[derive(Clone)] -pub struct TcpListener { - fd: Arc, - local: SocketAddr, - handle_count: Arc, - nonblocking: Arc, -} - -impl TcpListener { - pub fn bind(socketaddr: io::Result<&SocketAddr>) -> io::Result { - let mut addr = *socketaddr?; - - let fd = TcpListener::bind_inner(&mut addr)?; - return Ok(TcpListener { - fd: Arc::new(AtomicU16::new(fd)), - local: addr, - handle_count: Arc::new(AtomicUsize::new(1)), - nonblocking: Arc::new(AtomicBool::new(false)), - }); - } - - /// This returns the raw fd of a Listener, so that it can also be used by the - /// accept routine to replenish the Listener object after its handle has been converted into - /// a TcpStream object. - fn bind_inner(addr: &mut SocketAddr) -> io::Result { - // Construct the request - let mut connect_request = ConnectRequest { raw: [0u8; 4096] }; - - // Serialize the StdUdpBind structure. This is done "manually" because we don't want to - // make an auto-serdes (like bincode or rkyv) crate a dependency of Xous. - let port_bytes = addr.port().to_le_bytes(); - connect_request.raw[0] = port_bytes[0]; - connect_request.raw[1] = port_bytes[1]; - match addr.ip() { - IpAddr::V4(addr) => { - connect_request.raw[2] = 4; - for (dest, src) in connect_request.raw[3..].iter_mut().zip(addr.octets()) { - *dest = src; - } - } - IpAddr::V6(addr) => { - connect_request.raw[2] = 6; - for (dest, src) in connect_request.raw[3..].iter_mut().zip(addr.octets()) { - *dest = src; - } - } - } - - let Ok((_, valid)) = crate::os::xous::ffi::lend_mut( - services::net_server(), - services::NetLendMut::StdTcpListen.into(), - &mut connect_request.raw, - 0, - 4096, - ) else { - return Err(io::const_io_error!(io::ErrorKind::InvalidInput, &"Invalid response")); - }; - - // The first four bytes should be zero upon success, and will be nonzero - // for an error. - let response = connect_request.raw; - if response[0] != 0 || valid == 0 { - let errcode = response[1]; - if errcode == NetError::SocketInUse as u8 { - return Err(io::const_io_error!(io::ErrorKind::ResourceBusy, &"Socket in use")); - } else if errcode == NetError::Invalid as u8 { - return Err(io::const_io_error!( - io::ErrorKind::AddrNotAvailable, - &"Invalid address" - )); - } else if errcode == NetError::LibraryError as u8 { - return Err(io::const_io_error!(io::ErrorKind::Other, &"Library error")); - } else { - return Err(io::const_io_error!( - io::ErrorKind::Other, - &"Unable to connect or internal error" - )); - } - } - let fd = response[1] as usize; - if addr.port() == 0 { - // oddly enough, this is a valid port and it means "give me something valid, up to you what that is" - let assigned_port = u16::from_le_bytes(response[2..4].try_into().unwrap()); - addr.set_port(assigned_port); - } - // println!("TcpListening with file handle of {}\r\n", fd); - Ok(fd.try_into().unwrap()) - } - - pub fn socket_addr(&self) -> io::Result { - Ok(self.local) - } - - pub fn accept(&self) -> io::Result<(TcpStream, SocketAddr)> { - let mut receive_request = ReceiveData { raw: [0u8; 4096] }; - - if self.nonblocking.load(Ordering::Relaxed) { - // nonblocking - receive_request.raw[0] = 0; - } else { - // blocking - receive_request.raw[0] = 1; - } - - if let Ok((_offset, _valid)) = crate::os::xous::ffi::lend_mut( - services::net_server(), - services::NetLendMut::StdTcpAccept(self.fd.load(Ordering::Relaxed)).into(), - &mut receive_request.raw, - 0, - 0, - ) { - if receive_request.raw[0] != 0 { - // error case - if receive_request.raw[1] == NetError::TimedOut as u8 { - return Err(io::const_io_error!(io::ErrorKind::TimedOut, &"accept timed out",)); - } else if receive_request.raw[1] == NetError::WouldBlock as u8 { - return Err(io::const_io_error!( - io::ErrorKind::WouldBlock, - &"accept would block", - )); - } else if receive_request.raw[1] == NetError::LibraryError as u8 { - return Err(io::const_io_error!(io::ErrorKind::Other, &"Library error")); - } else { - return Err(io::const_io_error!(io::ErrorKind::Other, &"library error",)); - } - } else { - // accept successful - let rr = &receive_request.raw; - let stream_fd = u16::from_le_bytes(rr[1..3].try_into().unwrap()); - let port = u16::from_le_bytes(rr[20..22].try_into().unwrap()); - let addr = if rr[3] == 4 { - SocketAddr::new(IpAddr::V4(Ipv4Addr::new(rr[4], rr[5], rr[6], rr[7])), port) - } else if rr[3] == 6 { - SocketAddr::new( - IpAddr::V6(Ipv6Addr::new( - u16::from_be_bytes(rr[4..6].try_into().unwrap()), - u16::from_be_bytes(rr[6..8].try_into().unwrap()), - u16::from_be_bytes(rr[8..10].try_into().unwrap()), - u16::from_be_bytes(rr[10..12].try_into().unwrap()), - u16::from_be_bytes(rr[12..14].try_into().unwrap()), - u16::from_be_bytes(rr[14..16].try_into().unwrap()), - u16::from_be_bytes(rr[16..18].try_into().unwrap()), - u16::from_be_bytes(rr[18..20].try_into().unwrap()), - )), - port, - ) - } else { - return Err(io::const_io_error!(io::ErrorKind::Other, &"library error",)); - }; - - // replenish the listener - let mut local_copy = self.local.clone(); // port is non-0 by this time, but the method signature needs a mut - let new_fd = TcpListener::bind_inner(&mut local_copy)?; - self.fd.store(new_fd, Ordering::Relaxed); - - // now return a stream converted from the old stream's fd - Ok((TcpStream::from_listener(stream_fd, self.local.port(), port, addr), addr)) - } - } else { - Err(io::const_io_error!(io::ErrorKind::InvalidInput, &"Unable to accept")) - } - } - - pub fn duplicate(&self) -> io::Result { - self.handle_count.fetch_add(1, Ordering::Relaxed); - Ok(self.clone()) - } - - pub fn set_ttl(&self, ttl: u32) -> io::Result<()> { - if ttl > 255 { - return Err(io::Error::new(io::ErrorKind::InvalidInput, "TTL must be less than 256")); - } - crate::os::xous::ffi::blocking_scalar( - services::net_server(), - services::NetBlockingScalar::StdSetTtlTcp(self.fd.load(Ordering::Relaxed), ttl).into(), - ) - .or(Err(io::const_io_error!(io::ErrorKind::InvalidInput, &"Unexpected return value"))) - .map(|_| ()) - } - - pub fn ttl(&self) -> io::Result { - Ok(crate::os::xous::ffi::blocking_scalar( - services::net_server(), - services::NetBlockingScalar::StdGetTtlTcp(self.fd.load(Ordering::Relaxed)).into(), - ) - .or(Err(io::const_io_error!(io::ErrorKind::InvalidInput, &"Unexpected return value"))) - .map(|res| res[0] as _)?) - } - - pub fn set_only_v6(&self, _: bool) -> io::Result<()> { - unimpl!(); - } - - pub fn only_v6(&self) -> io::Result { - unimpl!(); - } - - pub fn take_error(&self) -> io::Result> { - // this call doesn't have a meaning on our platform, but we can at least not panic if it's used. - Ok(None) - } - - pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> { - self.nonblocking.store(nonblocking, Ordering::Relaxed); - Ok(()) - } -} - -impl fmt::Debug for TcpListener { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "TCP listening on {:?}", self.local) - } -} - -impl Drop for TcpListener { - fn drop(&mut self) { - if self.handle_count.fetch_sub(1, Ordering::Relaxed) == 1 { - // only drop if we're the last clone - crate::os::xous::ffi::blocking_scalar( - services::net_server(), - crate::os::xous::services::NetBlockingScalar::StdTcpClose( - self.fd.load(Ordering::Relaxed), - ) - .into(), - ) - .unwrap(); - } - } -} diff --git a/library/std/src/sys/pal/xous/net/tcpstream.rs b/library/std/src/sys/pal/xous/net/tcpstream.rs deleted file mode 100644 index 0ad8811071111..0000000000000 --- a/library/std/src/sys/pal/xous/net/tcpstream.rs +++ /dev/null @@ -1,429 +0,0 @@ -use super::*; -use crate::fmt; -use crate::io::{self, BorrowedCursor, IoSlice, IoSliceMut}; -use crate::net::{IpAddr, Ipv4Addr, Shutdown, SocketAddr, SocketAddrV4, SocketAddrV6}; -use crate::os::xous::services; -use crate::sync::Arc; -use crate::time::Duration; -use core::sync::atomic::{AtomicBool, AtomicU32, AtomicUsize, Ordering}; - -macro_rules! unimpl { - () => { - return Err(io::const_io_error!( - io::ErrorKind::Unsupported, - &"This function is not yet implemented", - )); - }; -} - -enum ReadOrPeek { - Read, - Peek, -} - -#[derive(Clone)] -pub struct TcpStream { - fd: u16, - local_port: u16, - remote_port: u16, - peer_addr: SocketAddr, - // milliseconds - read_timeout: Arc, - // milliseconds - write_timeout: Arc, - handle_count: Arc, - nonblocking: Arc, -} - -fn sockaddr_to_buf(duration: Duration, addr: &SocketAddr, buf: &mut [u8]) { - // Construct the request. - let port_bytes = addr.port().to_le_bytes(); - buf[0] = port_bytes[0]; - buf[1] = port_bytes[1]; - for (dest, src) in buf[2..].iter_mut().zip((duration.as_millis() as u64).to_le_bytes()) { - *dest = src; - } - match addr.ip() { - IpAddr::V4(addr) => { - buf[10] = 4; - for (dest, src) in buf[11..].iter_mut().zip(addr.octets()) { - *dest = src; - } - } - IpAddr::V6(addr) => { - buf[10] = 6; - for (dest, src) in buf[11..].iter_mut().zip(addr.octets()) { - *dest = src; - } - } - } -} - -impl TcpStream { - pub(crate) fn from_listener( - fd: u16, - local_port: u16, - remote_port: u16, - peer_addr: SocketAddr, - ) -> TcpStream { - TcpStream { - fd, - local_port, - remote_port, - peer_addr, - read_timeout: Arc::new(AtomicU32::new(0)), - write_timeout: Arc::new(AtomicU32::new(0)), - handle_count: Arc::new(AtomicUsize::new(1)), - nonblocking: Arc::new(AtomicBool::new(false)), - } - } - - pub fn connect(socketaddr: io::Result<&SocketAddr>) -> io::Result { - Self::connect_timeout(socketaddr?, Duration::ZERO) - } - - pub fn connect_timeout(addr: &SocketAddr, duration: Duration) -> io::Result { - let mut connect_request = ConnectRequest { raw: [0u8; 4096] }; - - // Construct the request. - sockaddr_to_buf(duration, &addr, &mut connect_request.raw); - - let Ok((_, valid)) = crate::os::xous::ffi::lend_mut( - services::net_server(), - services::NetLendMut::StdTcpConnect.into(), - &mut connect_request.raw, - 0, - 4096, - ) else { - return Err(io::const_io_error!(io::ErrorKind::InvalidInput, &"Invalid response")); - }; - - // The first four bytes should be zero upon success, and will be nonzero - // for an error. - let response = connect_request.raw; - if response[0] != 0 || valid == 0 { - // errcode is a u8 but stuck in a u16 where the upper byte is invalid. Mask & decode accordingly. - let errcode = response[0]; - if errcode == NetError::SocketInUse as u8 { - return Err(io::const_io_error!(io::ErrorKind::ResourceBusy, &"Socket in use",)); - } else if errcode == NetError::Unaddressable as u8 { - return Err(io::const_io_error!( - io::ErrorKind::AddrNotAvailable, - &"Invalid address", - )); - } else { - return Err(io::const_io_error!( - io::ErrorKind::InvalidInput, - &"Unable to connect or internal error", - )); - } - } - let fd = u16::from_le_bytes([response[2], response[3]]); - let local_port = u16::from_le_bytes([response[4], response[5]]); - let remote_port = u16::from_le_bytes([response[6], response[7]]); - // println!( - // "Connected with local port of {}, remote port of {}, file handle of {}", - // local_port, remote_port, fd - // ); - Ok(TcpStream { - fd, - local_port, - remote_port, - peer_addr: *addr, - read_timeout: Arc::new(AtomicU32::new(0)), - write_timeout: Arc::new(AtomicU32::new(0)), - handle_count: Arc::new(AtomicUsize::new(1)), - nonblocking: Arc::new(AtomicBool::new(false)), - }) - } - - pub fn set_read_timeout(&self, timeout: Option) -> io::Result<()> { - if let Some(to) = timeout { - if to.is_zero() { - return Err(io::Error::ZERO_TIMEOUT); - } - } - self.read_timeout.store( - timeout.map(|t| t.as_millis().min(u32::MAX as u128) as u32).unwrap_or_default(), - Ordering::Relaxed, - ); - Ok(()) - } - - pub fn set_write_timeout(&self, timeout: Option) -> io::Result<()> { - if let Some(to) = timeout { - if to.is_zero() { - return Err(io::Error::ZERO_TIMEOUT); - } - } - self.write_timeout.store( - timeout.map(|t| t.as_millis().min(u32::MAX as u128) as u32).unwrap_or_default(), - Ordering::Relaxed, - ); - Ok(()) - } - - pub fn read_timeout(&self) -> io::Result> { - match self.read_timeout.load(Ordering::Relaxed) { - 0 => Ok(None), - t => Ok(Some(Duration::from_millis(t as u64))), - } - } - - pub fn write_timeout(&self) -> io::Result> { - match self.write_timeout.load(Ordering::Relaxed) { - 0 => Ok(None), - t => Ok(Some(Duration::from_millis(t as u64))), - } - } - - fn read_or_peek(&self, buf: &mut [u8], op: ReadOrPeek) -> io::Result { - let mut receive_request = ReceiveData { raw: [0u8; 4096] }; - let data_to_read = buf.len().min(receive_request.raw.len()); - - let opcode = match op { - ReadOrPeek::Read => { - services::NetLendMut::StdTcpRx(self.fd, self.nonblocking.load(Ordering::Relaxed)) - } - ReadOrPeek::Peek => { - services::NetLendMut::StdTcpPeek(self.fd, self.nonblocking.load(Ordering::Relaxed)) - } - }; - - let Ok((offset, length)) = crate::os::xous::ffi::lend_mut( - services::net_server(), - opcode.into(), - &mut receive_request.raw, - // Reuse the `offset` as the read timeout - self.read_timeout.load(Ordering::Relaxed) as usize, - data_to_read, - ) else { - return Err(io::const_io_error!( - io::ErrorKind::InvalidInput, - &"Library failure: wrong message type or messaging error" - )); - }; - - if offset != 0 { - for (dest, src) in buf.iter_mut().zip(receive_request.raw[..length].iter()) { - *dest = *src; - } - Ok(length) - } else { - let result = receive_request.raw; - if result[0] != 0 { - if result[1] == 8 { - // timed out - return Err(io::const_io_error!(io::ErrorKind::TimedOut, &"Timeout",)); - } - if result[1] == 9 { - // would block - return Err(io::const_io_error!(io::ErrorKind::WouldBlock, &"Would block",)); - } - } - Err(io::const_io_error!(io::ErrorKind::Other, &"recv_slice failure")) - } - } - - pub fn peek(&self, buf: &mut [u8]) -> io::Result { - self.read_or_peek(buf, ReadOrPeek::Peek) - } - - pub fn read(&self, buf: &mut [u8]) -> io::Result { - self.read_or_peek(buf, ReadOrPeek::Read) - } - - pub fn read_vectored(&self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - crate::io::default_read_vectored(|b| self.read(b), bufs) - } - - pub fn read_buf(&self, cursor: BorrowedCursor<'_>) -> io::Result<()> { - crate::io::default_read_buf(|buf| self.read(buf), cursor) - } - - pub fn is_read_vectored(&self) -> bool { - false - } - - pub fn write(&self, buf: &[u8]) -> io::Result { - let mut send_request = SendData { raw: [0u8; 4096] }; - for (dest, src) in send_request.raw.iter_mut().zip(buf) { - *dest = *src; - } - let buf_len = send_request.raw.len().min(buf.len()); - - let (_offset, _valid) = crate::os::xous::ffi::lend_mut( - services::net_server(), - services::NetLendMut::StdTcpTx(self.fd).into(), - &mut send_request.raw, - // Reuse the offset as the timeout - self.write_timeout.load(Ordering::Relaxed) as usize, - buf_len, - ) - .or(Err(io::const_io_error!(io::ErrorKind::InvalidInput, &"Internal error")))?; - - if send_request.raw[0] != 0 { - if send_request.raw[4] == 8 { - // timed out - return Err(io::const_io_error!( - io::ErrorKind::BrokenPipe, - &"Timeout or connection closed", - )); - } else if send_request.raw[4] == 9 { - // would block - return Err(io::const_io_error!(io::ErrorKind::WouldBlock, &"Would block",)); - } else { - return Err(io::const_io_error!( - io::ErrorKind::InvalidInput, - &"Error when sending", - )); - } - } - Ok(u32::from_le_bytes([ - send_request.raw[4], - send_request.raw[5], - send_request.raw[6], - send_request.raw[7], - ]) as usize) - } - - pub fn write_vectored(&self, bufs: &[IoSlice<'_>]) -> io::Result { - crate::io::default_write_vectored(|b| self.write(b), bufs) - } - - pub fn is_write_vectored(&self) -> bool { - false - } - - pub fn peer_addr(&self) -> io::Result { - Ok(self.peer_addr) - } - - pub fn socket_addr(&self) -> io::Result { - let mut get_addr = GetAddress { raw: [0u8; 4096] }; - - let Ok((_offset, _valid)) = crate::os::xous::ffi::lend_mut( - services::net_server(), - services::NetLendMut::StdGetAddress(self.fd).into(), - &mut get_addr.raw, - 0, - 0, - ) else { - return Err(io::const_io_error!(io::ErrorKind::InvalidInput, &"Internal error")); - }; - let mut i = get_addr.raw.iter(); - match *i.next().unwrap() { - 4 => Ok(SocketAddr::V4(SocketAddrV4::new( - Ipv4Addr::new( - *i.next().unwrap(), - *i.next().unwrap(), - *i.next().unwrap(), - *i.next().unwrap(), - ), - self.local_port, - ))), - 6 => { - let mut new_addr = [0u8; 16]; - for (src, octet) in i.zip(new_addr.iter_mut()) { - *octet = *src; - } - Ok(SocketAddr::V6(SocketAddrV6::new(new_addr.into(), self.local_port, 0, 0))) - } - _ => Err(io::const_io_error!(io::ErrorKind::InvalidInput, &"Internal error")), - } - } - - pub fn shutdown(&self, how: Shutdown) -> io::Result<()> { - crate::os::xous::ffi::blocking_scalar( - services::net_server(), - services::NetBlockingScalar::StdTcpStreamShutdown(self.fd, how).into(), - ) - .or(Err(io::const_io_error!(io::ErrorKind::InvalidInput, &"Unexpected return value"))) - .map(|_| ()) - } - - pub fn duplicate(&self) -> io::Result { - self.handle_count.fetch_add(1, Ordering::Relaxed); - Ok(self.clone()) - } - - pub fn set_linger(&self, _: Option) -> io::Result<()> { - unimpl!(); - } - - pub fn linger(&self) -> io::Result> { - unimpl!(); - } - - pub fn set_nodelay(&self, enabled: bool) -> io::Result<()> { - crate::os::xous::ffi::blocking_scalar( - services::net_server(), - services::NetBlockingScalar::StdSetNodelay(self.fd, enabled).into(), - ) - .or(Err(io::const_io_error!(io::ErrorKind::InvalidInput, &"Unexpected return value"))) - .map(|_| ()) - } - - pub fn nodelay(&self) -> io::Result { - Ok(crate::os::xous::ffi::blocking_scalar( - services::net_server(), - services::NetBlockingScalar::StdGetNodelay(self.fd).into(), - ) - .or(Err(io::const_io_error!(io::ErrorKind::InvalidInput, &"Unexpected return value"))) - .map(|res| res[0] != 0)?) - } - - pub fn set_ttl(&self, ttl: u32) -> io::Result<()> { - if ttl > 255 { - return Err(io::Error::new(io::ErrorKind::InvalidInput, "TTL must be less than 256")); - } - crate::os::xous::ffi::blocking_scalar( - services::net_server(), - services::NetBlockingScalar::StdSetTtlTcp(self.fd, ttl).into(), - ) - .or(Err(io::const_io_error!(io::ErrorKind::InvalidInput, &"Unexpected return value"))) - .map(|_| ()) - } - - pub fn ttl(&self) -> io::Result { - Ok(crate::os::xous::ffi::blocking_scalar( - services::net_server(), - services::NetBlockingScalar::StdGetTtlTcp(self.fd).into(), - ) - .or(Err(io::const_io_error!(io::ErrorKind::InvalidInput, &"Unexpected return value"))) - .map(|res| res[0] as _)?) - } - - pub fn take_error(&self) -> io::Result> { - // this call doesn't have a meaning on our platform, but we can at least not panic if it's used. - Ok(None) - } - - pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> { - self.nonblocking.store(nonblocking, Ordering::Relaxed); - Ok(()) - } -} - -impl fmt::Debug for TcpStream { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!( - f, - "TCP connection to {:?} port {} to local port {}", - self.peer_addr, self.remote_port, self.local_port - ) - } -} - -impl Drop for TcpStream { - fn drop(&mut self) { - if self.handle_count.fetch_sub(1, Ordering::Relaxed) == 1 { - // only drop if we're the last clone - crate::os::xous::ffi::blocking_scalar( - services::net_server(), - services::NetBlockingScalar::StdTcpClose(self.fd).into(), - ) - .unwrap(); - } - } -} diff --git a/library/std/src/sys/pal/xous/net/udp.rs b/library/std/src/sys/pal/xous/net/udp.rs deleted file mode 100644 index 3d0522b25f3fb..0000000000000 --- a/library/std/src/sys/pal/xous/net/udp.rs +++ /dev/null @@ -1,465 +0,0 @@ -use super::*; -use crate::cell::Cell; -use crate::fmt; -use crate::io; -use crate::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr}; -use crate::os::xous::services; -use crate::sync::Arc; -use crate::time::Duration; -use core::convert::TryInto; -use core::sync::atomic::{AtomicUsize, Ordering}; - -macro_rules! unimpl { - () => { - return Err(io::const_io_error!( - io::ErrorKind::Unsupported, - &"This function is not yet implemented", - )); - }; -} - -#[derive(Clone)] -pub struct UdpSocket { - fd: u16, - local: SocketAddr, - remote: Cell>, - // in milliseconds. The setting applies only to `recv` calls after the timeout is set. - read_timeout: Cell, - // in milliseconds. The setting applies only to `send` calls after the timeout is set. - write_timeout: Cell, - handle_count: Arc, - nonblocking: Cell, -} - -impl UdpSocket { - pub fn bind(socketaddr: io::Result<&SocketAddr>) -> io::Result { - let addr = socketaddr?; - // Construct the request - let mut connect_request = ConnectRequest { raw: [0u8; 4096] }; - - // Serialize the StdUdpBind structure. This is done "manually" because we don't want to - // make an auto-serdes (like bincode or rkyv) crate a dependency of Xous. - let port_bytes = addr.port().to_le_bytes(); - connect_request.raw[0] = port_bytes[0]; - connect_request.raw[1] = port_bytes[1]; - match addr.ip() { - IpAddr::V4(addr) => { - connect_request.raw[2] = 4; - for (dest, src) in connect_request.raw[3..].iter_mut().zip(addr.octets()) { - *dest = src; - } - } - IpAddr::V6(addr) => { - connect_request.raw[2] = 6; - for (dest, src) in connect_request.raw[3..].iter_mut().zip(addr.octets()) { - *dest = src; - } - } - } - - let response = crate::os::xous::ffi::lend_mut( - services::net_server(), - services::NetLendMut::StdUdpBind.into(), - &mut connect_request.raw, - 0, - 4096, - ); - - if let Ok((_, valid)) = response { - // The first four bytes should be zero upon success, and will be nonzero - // for an error. - let response = connect_request.raw; - if response[0] != 0 || valid == 0 { - let errcode = response[1]; - if errcode == NetError::SocketInUse as u8 { - return Err(io::const_io_error!(io::ErrorKind::ResourceBusy, &"Socket in use")); - } else if errcode == NetError::Invalid as u8 { - return Err(io::const_io_error!( - io::ErrorKind::InvalidInput, - &"Port can't be 0 or invalid address" - )); - } else if errcode == NetError::LibraryError as u8 { - return Err(io::const_io_error!(io::ErrorKind::Other, &"Library error")); - } else { - return Err(io::const_io_error!( - io::ErrorKind::Other, - &"Unable to connect or internal error" - )); - } - } - let fd = response[1] as u16; - return Ok(UdpSocket { - fd, - local: *addr, - remote: Cell::new(None), - read_timeout: Cell::new(0), - write_timeout: Cell::new(0), - handle_count: Arc::new(AtomicUsize::new(1)), - nonblocking: Cell::new(false), - }); - } - Err(io::const_io_error!(io::ErrorKind::InvalidInput, &"Invalid response")) - } - - pub fn peer_addr(&self) -> io::Result { - match self.remote.get() { - Some(dest) => Ok(dest), - None => Err(io::const_io_error!(io::ErrorKind::NotConnected, &"No peer specified")), - } - } - - pub fn socket_addr(&self) -> io::Result { - Ok(self.local) - } - - fn recv_inner(&self, buf: &mut [u8], do_peek: bool) -> io::Result<(usize, SocketAddr)> { - let mut receive_request = ReceiveData { raw: [0u8; 4096] }; - - if self.nonblocking.get() { - // nonblocking - receive_request.raw[0] = 0; - } else { - // blocking - receive_request.raw[0] = 1; - for (&s, d) in self - .read_timeout - .get() - .to_le_bytes() - .iter() - .zip(receive_request.raw[1..9].iter_mut()) - { - *d = s; - } - } - if let Ok((_offset, _valid)) = crate::os::xous::ffi::lend_mut( - services::net_server(), - services::NetLendMut::StdUdpRx(self.fd).into(), - &mut receive_request.raw, - if do_peek { 1 } else { 0 }, - 0, - ) { - if receive_request.raw[0] != 0 { - // error case - if receive_request.raw[1] == NetError::TimedOut as u8 { - return Err(io::const_io_error!(io::ErrorKind::TimedOut, &"recv timed out",)); - } else if receive_request.raw[1] == NetError::WouldBlock as u8 { - return Err(io::const_io_error!( - io::ErrorKind::WouldBlock, - &"recv would block", - )); - } else if receive_request.raw[1] == NetError::LibraryError as u8 { - return Err(io::const_io_error!(io::ErrorKind::Other, &"Library error")); - } else { - return Err(io::const_io_error!(io::ErrorKind::Other, &"library error",)); - } - } else { - let rr = &receive_request.raw; - let rxlen = u16::from_le_bytes(rr[1..3].try_into().unwrap()); - let port = u16::from_le_bytes(rr[20..22].try_into().unwrap()); - let addr = if rr[3] == 4 { - SocketAddr::new(IpAddr::V4(Ipv4Addr::new(rr[4], rr[5], rr[6], rr[7])), port) - } else if rr[3] == 6 { - SocketAddr::new( - IpAddr::V6(Ipv6Addr::new( - u16::from_be_bytes(rr[4..6].try_into().unwrap()), - u16::from_be_bytes(rr[6..8].try_into().unwrap()), - u16::from_be_bytes(rr[8..10].try_into().unwrap()), - u16::from_be_bytes(rr[10..12].try_into().unwrap()), - u16::from_be_bytes(rr[12..14].try_into().unwrap()), - u16::from_be_bytes(rr[14..16].try_into().unwrap()), - u16::from_be_bytes(rr[16..18].try_into().unwrap()), - u16::from_be_bytes(rr[18..20].try_into().unwrap()), - )), - port, - ) - } else { - return Err(io::const_io_error!(io::ErrorKind::Other, &"library error",)); - }; - for (&s, d) in rr[22..22 + rxlen as usize].iter().zip(buf.iter_mut()) { - *d = s; - } - Ok((rxlen as usize, addr)) - } - } else { - Err(io::const_io_error!(io::ErrorKind::InvalidInput, &"Unable to recv")) - } - } - - pub fn recv_from(&self, buf: &mut [u8]) -> io::Result<(usize, SocketAddr)> { - self.recv_inner(buf, false) - } - - pub fn recv(&self, buf: &mut [u8]) -> io::Result { - self.recv_from(buf).map(|(len, _addr)| len) - } - - pub fn peek_from(&self, buf: &mut [u8]) -> io::Result<(usize, SocketAddr)> { - self.recv_inner(buf, true) - } - - pub fn peek(&self, buf: &mut [u8]) -> io::Result { - self.peek_from(buf).map(|(len, _addr)| len) - } - - pub fn connect(&self, maybe_addr: io::Result<&SocketAddr>) -> io::Result<()> { - let addr = maybe_addr?; - self.remote.set(Some(*addr)); - Ok(()) - } - - pub fn send(&self, buf: &[u8]) -> io::Result { - if let Some(addr) = self.remote.get() { - self.send_to(buf, &addr) - } else { - Err(io::const_io_error!(io::ErrorKind::NotConnected, &"No remote specified")) - } - } - - pub fn send_to(&self, buf: &[u8], addr: &SocketAddr) -> io::Result { - let mut tx_req = SendData { raw: [0u8; 4096] }; - - // Construct the request. - let port_bytes = addr.port().to_le_bytes(); - tx_req.raw[0] = port_bytes[0]; - tx_req.raw[1] = port_bytes[1]; - match addr.ip() { - IpAddr::V4(addr) => { - tx_req.raw[2] = 4; - for (dest, src) in tx_req.raw[3..].iter_mut().zip(addr.octets()) { - *dest = src; - } - } - IpAddr::V6(addr) => { - tx_req.raw[2] = 6; - for (dest, src) in tx_req.raw[3..].iter_mut().zip(addr.octets()) { - *dest = src; - } - } - } - let len = buf.len() as u16; - let len_bytes = len.to_le_bytes(); - tx_req.raw[19] = len_bytes[0]; - tx_req.raw[20] = len_bytes[1]; - for (&s, d) in buf.iter().zip(tx_req.raw[21..].iter_mut()) { - *d = s; - } - - // let buf = unsafe { - // xous::MemoryRange::new( - // &mut tx_req as *mut SendData as usize, - // core::mem::size_of::(), - // ) - // .unwrap() - // }; - - // write time-outs are implemented on the caller side. Basically, if the Net crate server - // is too busy to take the call immediately: retry, until the timeout is reached. - let now = crate::time::Instant::now(); - let write_timeout = if self.nonblocking.get() { - // nonblocking - core::time::Duration::ZERO - } else { - // blocking - if self.write_timeout.get() == 0 { - // forever - core::time::Duration::from_millis(u64::MAX) - } else { - // or this amount of time - core::time::Duration::from_millis(self.write_timeout.get()) - } - }; - loop { - let response = crate::os::xous::ffi::try_lend_mut( - services::net_server(), - services::NetLendMut::StdUdpTx(self.fd).into(), - &mut tx_req.raw, - 0, - 4096, - ); - match response { - Ok((_, valid)) => { - let response = &tx_req.raw; - if response[0] != 0 || valid == 0 { - let errcode = response[1]; - if errcode == NetError::SocketInUse as u8 { - return Err(io::const_io_error!( - io::ErrorKind::ResourceBusy, - &"Socket in use" - )); - } else if errcode == NetError::Invalid as u8 { - return Err(io::const_io_error!( - io::ErrorKind::InvalidInput, - &"Socket not valid" - )); - } else if errcode == NetError::LibraryError as u8 { - return Err(io::const_io_error!( - io::ErrorKind::Other, - &"Library error" - )); - } else { - return Err(io::const_io_error!( - io::ErrorKind::Other, - &"Unable to connect" - )); - } - } else { - // no error - return Ok(len as usize); - } - } - Err(crate::os::xous::ffi::Error::ServerQueueFull) => { - if now.elapsed() >= write_timeout { - return Err(io::const_io_error!( - io::ErrorKind::WouldBlock, - &"Write timed out" - )); - } else { - // question: do we want to do something a bit more gentle than immediately retrying? - crate::thread::yield_now(); - } - } - _ => return Err(io::const_io_error!(io::ErrorKind::Other, &"Library error")), - } - } - } - - pub fn duplicate(&self) -> io::Result { - self.handle_count.fetch_add(1, Ordering::Relaxed); - Ok(self.clone()) - } - - pub fn set_read_timeout(&self, timeout: Option) -> io::Result<()> { - if let Some(d) = timeout { - if d.is_zero() { - return Err(io::Error::ZERO_TIMEOUT); - } - } - self.read_timeout - .set(timeout.map(|t| t.as_millis().min(u64::MAX as u128) as u64).unwrap_or_default()); - Ok(()) - } - - pub fn set_write_timeout(&self, timeout: Option) -> io::Result<()> { - if let Some(d) = timeout { - if d.is_zero() { - return Err(io::Error::ZERO_TIMEOUT); - } - } - self.write_timeout - .set(timeout.map(|t| t.as_millis().min(u64::MAX as u128) as u64).unwrap_or_default()); - Ok(()) - } - - pub fn read_timeout(&self) -> io::Result> { - match self.read_timeout.get() { - 0 => Ok(None), - t => Ok(Some(Duration::from_millis(t as u64))), - } - } - - pub fn write_timeout(&self) -> io::Result> { - match self.write_timeout.get() { - 0 => Ok(None), - t => Ok(Some(Duration::from_millis(t as u64))), - } - } - - pub fn set_ttl(&self, ttl: u32) -> io::Result<()> { - if ttl > 255 { - return Err(io::Error::new(io::ErrorKind::InvalidInput, "TTL must be less than 256")); - } - crate::os::xous::ffi::blocking_scalar( - services::net_server(), - services::NetBlockingScalar::StdSetTtlUdp(self.fd, ttl).into(), - ) - .or(Err(io::const_io_error!(io::ErrorKind::InvalidInput, &"Unexpected return value"))) - .map(|_| ()) - } - - pub fn ttl(&self) -> io::Result { - Ok(crate::os::xous::ffi::blocking_scalar( - services::net_server(), - services::NetBlockingScalar::StdGetTtlUdp(self.fd).into(), - ) - .or(Err(io::const_io_error!(io::ErrorKind::InvalidInput, &"Unexpected return value"))) - .map(|res| res[0] as _)?) - } - - pub fn take_error(&self) -> io::Result> { - // this call doesn't have a meaning on our platform, but we can at least not panic if it's used. - Ok(None) - } - - pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> { - self.nonblocking.set(nonblocking); - Ok(()) - } - - // ------------- smoltcp base stack does not have multicast or broadcast support --------------- - pub fn set_broadcast(&self, _: bool) -> io::Result<()> { - unimpl!(); - } - - pub fn broadcast(&self) -> io::Result { - unimpl!(); - } - - pub fn set_multicast_loop_v4(&self, _: bool) -> io::Result<()> { - unimpl!(); - } - - pub fn multicast_loop_v4(&self) -> io::Result { - unimpl!(); - } - - pub fn set_multicast_ttl_v4(&self, _: u32) -> io::Result<()> { - unimpl!(); - } - - pub fn multicast_ttl_v4(&self) -> io::Result { - unimpl!(); - } - - pub fn set_multicast_loop_v6(&self, _: bool) -> io::Result<()> { - unimpl!(); - } - - pub fn multicast_loop_v6(&self) -> io::Result { - unimpl!(); - } - - pub fn join_multicast_v4(&self, _: &Ipv4Addr, _: &Ipv4Addr) -> io::Result<()> { - unimpl!(); - } - - pub fn join_multicast_v6(&self, _: &Ipv6Addr, _: u32) -> io::Result<()> { - unimpl!(); - } - - pub fn leave_multicast_v4(&self, _: &Ipv4Addr, _: &Ipv4Addr) -> io::Result<()> { - unimpl!(); - } - - pub fn leave_multicast_v6(&self, _: &Ipv6Addr, _: u32) -> io::Result<()> { - unimpl!(); - } -} - -impl fmt::Debug for UdpSocket { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "UDP listening on {:?} to {:?}", self.local, self.remote.get(),) - } -} - -impl Drop for UdpSocket { - fn drop(&mut self) { - if self.handle_count.fetch_sub(1, Ordering::Relaxed) == 1 { - // only drop if we're the last clone - crate::os::xous::ffi::blocking_scalar( - services::net_server(), - services::NetBlockingScalar::StdUdpClose(self.fd).into(), - ) - .unwrap(); - } - } -} diff --git a/library/std/src/sys/pal/xous/os.rs b/library/std/src/sys/pal/xous/os.rs deleted file mode 100644 index 8d2eaee8aa617..0000000000000 --- a/library/std/src/sys/pal/xous/os.rs +++ /dev/null @@ -1,174 +0,0 @@ -use super::unsupported; -use crate::error::Error as StdError; -use crate::ffi::{OsStr, OsString}; -use crate::fmt; -use crate::io; -use crate::marker::PhantomData; -use crate::os::xous::ffi::Error as XousError; -use crate::path::{self, PathBuf}; - -#[cfg(not(test))] -#[cfg(feature = "panic_unwind")] -mod eh_unwinding { - pub(crate) struct EhFrameFinder(usize /* eh_frame */); - pub(crate) static mut EH_FRAME_SETTINGS: EhFrameFinder = EhFrameFinder(0); - impl EhFrameFinder { - pub(crate) unsafe fn init(&mut self, eh_frame: usize) { - unsafe { - EH_FRAME_SETTINGS.0 = eh_frame; - } - } - } - unsafe impl unwind::EhFrameFinder for EhFrameFinder { - fn find(&self, _pc: usize) -> Option { - Some(unwind::FrameInfo { - text_base: None, - kind: unwind::FrameInfoKind::EhFrame(self.0), - }) - } - } -} - -#[cfg(not(test))] -mod c_compat { - use crate::os::xous::ffi::exit; - extern "C" { - fn main() -> u32; - } - - #[no_mangle] - pub extern "C" fn abort() { - exit(1); - } - - #[no_mangle] - pub extern "C" fn _start(eh_frame: usize) { - #[cfg(feature = "panic_unwind")] - unsafe { - super::eh_unwinding::EH_FRAME_SETTINGS.init(eh_frame); - unwind::set_custom_eh_frame_finder(&super::eh_unwinding::EH_FRAME_SETTINGS).ok(); - } - exit(unsafe { main() }); - } - - // This function is needed by the panic runtime. The symbol is named in - // pre-link args for the target specification, so keep that in sync. - #[no_mangle] - // NB. used by both libunwind and libpanic_abort - pub extern "C" fn __rust_abort() -> ! { - exit(101); - } -} - -pub fn errno() -> i32 { - 0 -} - -pub fn error_string(errno: i32) -> String { - Into::::into(errno).to_string() -} - -pub fn getcwd() -> io::Result { - unsupported() -} - -pub fn chdir(_: &path::Path) -> io::Result<()> { - unsupported() -} - -pub struct SplitPaths<'a>(!, PhantomData<&'a ()>); - -pub fn split_paths(_unparsed: &OsStr) -> SplitPaths<'_> { - panic!("unsupported") -} - -impl<'a> Iterator for SplitPaths<'a> { - type Item = PathBuf; - fn next(&mut self) -> Option { - self.0 - } -} - -#[derive(Debug)] -pub struct JoinPathsError; - -pub fn join_paths(_paths: I) -> Result -where - I: Iterator, - T: AsRef, -{ - Err(JoinPathsError) -} - -impl fmt::Display for JoinPathsError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - "not supported on this platform yet".fmt(f) - } -} - -impl StdError for JoinPathsError { - #[allow(deprecated)] - fn description(&self) -> &str { - "not supported on this platform yet" - } -} - -pub fn current_exe() -> io::Result { - unsupported() -} - -pub struct Env(!); - -impl Env { - // FIXME(https://github.com/rust-lang/rust/issues/114583): Remove this when ::fmt matches ::fmt. - pub fn str_debug(&self) -> impl fmt::Debug + '_ { - let Self(inner) = self; - match *inner {} - } -} - -impl fmt::Debug for Env { - fn fmt(&self, _: &mut fmt::Formatter<'_>) -> fmt::Result { - let Self(inner) = self; - match *inner {} - } -} - -impl Iterator for Env { - type Item = (OsString, OsString); - fn next(&mut self) -> Option<(OsString, OsString)> { - self.0 - } -} - -pub fn env() -> Env { - panic!("not supported on this platform") -} - -pub fn getenv(_: &OsStr) -> Option { - None -} - -pub fn setenv(_: &OsStr, _: &OsStr) -> io::Result<()> { - Err(io::const_io_error!(io::ErrorKind::Unsupported, "cannot set env vars on this platform")) -} - -pub fn unsetenv(_: &OsStr) -> io::Result<()> { - Err(io::const_io_error!(io::ErrorKind::Unsupported, "cannot unset env vars on this platform")) -} - -pub fn temp_dir() -> PathBuf { - panic!("no filesystem on this platform") -} - -pub fn home_dir() -> Option { - None -} - -pub fn exit(code: i32) -> ! { - crate::os::xous::ffi::exit(code as u32); -} - -pub fn getpid() -> u32 { - panic!("no pids on this platform") -} diff --git a/library/std/src/sys/pal/xous/stdio.rs b/library/std/src/sys/pal/xous/stdio.rs deleted file mode 100644 index 11608964b52e6..0000000000000 --- a/library/std/src/sys/pal/xous/stdio.rs +++ /dev/null @@ -1,133 +0,0 @@ -use crate::io; - -pub struct Stdin; -pub struct Stdout {} -pub struct Stderr; - -use crate::os::xous::ffi::{lend, try_lend, try_scalar, Connection}; -use crate::os::xous::services::{log_server, try_connect, LogLend, LogScalar}; - -impl Stdin { - pub const fn new() -> Stdin { - Stdin - } -} - -impl io::Read for Stdin { - fn read(&mut self, _buf: &mut [u8]) -> io::Result { - Ok(0) - } -} - -impl Stdout { - pub const fn new() -> Stdout { - Stdout {} - } -} - -impl io::Write for Stdout { - fn write(&mut self, buf: &[u8]) -> io::Result { - #[repr(C, align(4096))] - struct LendBuffer([u8; 4096]); - let mut lend_buffer = LendBuffer([0u8; 4096]); - let connection = log_server(); - for chunk in buf.chunks(lend_buffer.0.len()) { - for (dest, src) in lend_buffer.0.iter_mut().zip(chunk) { - *dest = *src; - } - lend(connection, LogLend::StandardOutput.into(), &lend_buffer.0, 0, chunk.len()) - .unwrap(); - } - Ok(buf.len()) - } - - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -impl Stderr { - pub const fn new() -> Stderr { - Stderr - } -} - -impl io::Write for Stderr { - fn write(&mut self, buf: &[u8]) -> io::Result { - #[repr(C, align(4096))] - struct LendBuffer([u8; 4096]); - let mut lend_buffer = LendBuffer([0u8; 4096]); - let connection = log_server(); - for chunk in buf.chunks(lend_buffer.0.len()) { - for (dest, src) in lend_buffer.0.iter_mut().zip(chunk) { - *dest = *src; - } - lend(connection, LogLend::StandardError.into(), &lend_buffer.0, 0, chunk.len()) - .unwrap(); - } - Ok(buf.len()) - } - - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -pub const STDIN_BUF_SIZE: usize = 0; - -pub fn is_ebadf(_err: &io::Error) -> bool { - true -} - -#[derive(Copy, Clone)] -pub struct PanicWriter { - log: Connection, - gfx: Option, -} - -impl io::Write for PanicWriter { - fn write(&mut self, s: &[u8]) -> core::result::Result { - for c in s.chunks(core::mem::size_of::() * 4) { - // Text is grouped into 4x `usize` words. The id is 1100 plus - // the number of characters in this message. - // Ignore errors since we're already panicking. - try_scalar(self.log, LogScalar::AppendPanicMessage(&c).into()).ok(); - } - - // Serialize the text to the graphics panic handler, only if we were able - // to acquire a connection to it. Text length is encoded in the `valid` field, - // the data itself in the buffer. Typically several messages are require to - // fully transmit the entire panic message. - if let Some(gfx) = self.gfx { - #[repr(C, align(4096))] - struct Request([u8; 4096]); - let mut request = Request([0u8; 4096]); - for (&s, d) in s.iter().zip(request.0.iter_mut()) { - *d = s; - } - try_lend(gfx, 0 /* AppendPanicText */, &request.0, 0, s.len()).ok(); - } - Ok(s.len()) - } - - // Tests show that this does not seem to be reliably called at the end of a panic - // print, so, we can't rely on this to e.g. trigger a graphics update. - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -pub fn panic_output() -> Option { - // Generally this won't fail because every server has already connected, so - // this is likely to succeed. - let log = log_server(); - - // Send the "We're panicking" message (1000). - try_scalar(log, LogScalar::BeginPanic.into()).ok(); - - // This is will fail in the case that the connection table is full, or if the - // graphics server is not running. Most servers do not already have this connection. - let gfx = try_connect("panic-to-screen!"); - - Some(PanicWriter { log, gfx }) -} diff --git a/library/std/src/sys/pal/xous/thread.rs b/library/std/src/sys/pal/xous/thread.rs deleted file mode 100644 index da7d722cc7082..0000000000000 --- a/library/std/src/sys/pal/xous/thread.rs +++ /dev/null @@ -1,138 +0,0 @@ -use crate::ffi::CStr; -use crate::io; -use crate::num::NonZero; -use crate::os::xous::ffi::{ - blocking_scalar, create_thread, do_yield, join_thread, map_memory, update_memory_flags, - MemoryFlags, Syscall, ThreadId, -}; -use crate::os::xous::services::{ticktimer_server, TicktimerScalar}; -use crate::time::Duration; -use core::arch::asm; - -pub struct Thread { - tid: ThreadId, -} - -pub const DEFAULT_MIN_STACK_SIZE: usize = 131072; -const MIN_STACK_SIZE: usize = 4096; -pub const GUARD_PAGE_SIZE: usize = 4096; - -impl Thread { - // unsafe: see thread::Builder::spawn_unchecked for safety requirements - pub unsafe fn new(stack: usize, p: Box) -> io::Result { - let p = Box::into_raw(Box::new(p)); - let mut stack_size = crate::cmp::max(stack, MIN_STACK_SIZE); - - if (stack_size & 4095) != 0 { - stack_size = (stack_size + 4095) & !4095; - } - - // Allocate the whole thing, then divide it up after the fact. This ensures that - // even if there's a context switch during this function, the whole stack plus - // guard pages will remain contiguous. - let stack_plus_guard_pages: &mut [u8] = unsafe { - map_memory( - None, - None, - GUARD_PAGE_SIZE + stack_size + GUARD_PAGE_SIZE, - MemoryFlags::R | MemoryFlags::W | MemoryFlags::X, - ) - } - .map_err(|code| io::Error::from_raw_os_error(code as i32))?; - - // No access to this page. Note: Write-only pages are illegal, and will - // cause an access violation. - unsafe { - update_memory_flags(&mut stack_plus_guard_pages[0..GUARD_PAGE_SIZE], MemoryFlags::W) - .map_err(|code| io::Error::from_raw_os_error(code as i32))? - }; - - // No access to this page. Note: Write-only pages are illegal, and will - // cause an access violation. - unsafe { - update_memory_flags( - &mut stack_plus_guard_pages[(GUARD_PAGE_SIZE + stack_size)..], - MemoryFlags::W, - ) - .map_err(|code| io::Error::from_raw_os_error(code as i32))? - }; - - let guard_page_pre = stack_plus_guard_pages.as_ptr() as usize; - let tid = create_thread( - thread_start as *mut usize, - &mut stack_plus_guard_pages[GUARD_PAGE_SIZE..(stack_size + GUARD_PAGE_SIZE)], - p as usize, - guard_page_pre, - stack_size, - 0, - ) - .map_err(|code| io::Error::from_raw_os_error(code as i32))?; - - extern "C" fn thread_start( - main: *mut usize, - guard_page_pre: usize, - stack_size: usize, - ) -> ! { - unsafe { - // Run the contents of the new thread. - Box::from_raw(main as *mut Box)(); - } - - // Destroy TLS, which will free the TLS page and call the destructor for - // any thread local storage (if any). - unsafe { - crate::sys::thread_local_key::destroy_tls(); - } - - // Deallocate the stack memory, along with the guard pages. Afterwards, - // exit the thread by returning to the magic address 0xff80_3000usize, - // which tells the kernel to deallocate this thread. - let mapped_memory_base = guard_page_pre; - let mapped_memory_length = GUARD_PAGE_SIZE + stack_size + GUARD_PAGE_SIZE; - unsafe { - asm!( - "ecall", - "ret", - in("a0") Syscall::UnmapMemory as usize, - in("a1") mapped_memory_base, - in("a2") mapped_memory_length, - in("ra") 0xff80_3000usize, - options(nomem, nostack, noreturn) - ); - } - } - - Ok(Thread { tid }) - } - - pub fn yield_now() { - do_yield(); - } - - pub fn set_name(_name: &CStr) { - // nope - } - - pub fn sleep(dur: Duration) { - // Because the sleep server works on units of `usized milliseconds`, split - // the messages up into these chunks. This means we may run into issues - // if you try to sleep a thread for more than 49 days on a 32-bit system. - let mut millis = dur.as_millis(); - while millis > 0 { - let sleep_duration = - if millis > (usize::MAX as _) { usize::MAX } else { millis as usize }; - blocking_scalar(ticktimer_server(), TicktimerScalar::SleepMs(sleep_duration).into()) - .expect("failed to send message to ticktimer server"); - millis -= sleep_duration as u128; - } - } - - pub fn join(self) { - join_thread(self.tid).unwrap(); - } -} - -pub fn available_parallelism() -> io::Result> { - // We're unicore right now. - Ok(unsafe { NonZero::new_unchecked(1) }) -} diff --git a/library/std/src/sys/pal/xous/thread_local_key.rs b/library/std/src/sys/pal/xous/thread_local_key.rs deleted file mode 100644 index 6c29813c79dfd..0000000000000 --- a/library/std/src/sys/pal/xous/thread_local_key.rs +++ /dev/null @@ -1,215 +0,0 @@ -use crate::mem::ManuallyDrop; -use crate::ptr; -use crate::sync::atomic::AtomicPtr; -use crate::sync::atomic::AtomicUsize; -use crate::sync::atomic::Ordering::{Acquire, Relaxed, Release}; -use core::arch::asm; - -use crate::os::xous::ffi::{map_memory, unmap_memory, MemoryFlags}; - -/// Thread Local Storage -/// -/// Currently, we are limited to 1023 TLS entries. The entries -/// live in a page of memory that's unique per-process, and is -/// stored in the `$tp` register. If this register is 0, then -/// TLS has not been initialized and thread cleanup can be skipped. -/// -/// The index into this register is the `key`. This key is identical -/// between all threads, but indexes a different offset within this -/// pointer. -pub type Key = usize; - -pub type Dtor = unsafe extern "C" fn(*mut u8); - -const TLS_MEMORY_SIZE: usize = 4096; - -/// TLS keys start at `1`. Index `0` is unused -#[cfg(not(test))] -#[export_name = "_ZN16__rust_internals3std3sys4xous16thread_local_key13TLS_KEY_INDEXE"] -static TLS_KEY_INDEX: AtomicUsize = AtomicUsize::new(1); - -#[cfg(not(test))] -#[export_name = "_ZN16__rust_internals3std3sys4xous16thread_local_key9DTORSE"] -static DTORS: AtomicPtr = AtomicPtr::new(ptr::null_mut()); - -#[cfg(test)] -extern "Rust" { - #[link_name = "_ZN16__rust_internals3std3sys4xous16thread_local_key13TLS_KEY_INDEXE"] - static TLS_KEY_INDEX: AtomicUsize; - - #[link_name = "_ZN16__rust_internals3std3sys4xous16thread_local_key9DTORSE"] - static DTORS: AtomicPtr; -} - -fn tls_ptr_addr() -> *mut *mut u8 { - let mut tp: usize; - unsafe { - asm!( - "mv {}, tp", - out(reg) tp, - ); - } - core::ptr::with_exposed_provenance_mut::<*mut u8>(tp) -} - -/// Create an area of memory that's unique per thread. This area will -/// contain all thread local pointers. -fn tls_table() -> &'static mut [*mut u8] { - let tp = tls_ptr_addr(); - - if !tp.is_null() { - return unsafe { - core::slice::from_raw_parts_mut(tp, TLS_MEMORY_SIZE / core::mem::size_of::<*mut u8>()) - }; - } - // If the TP register is `0`, then this thread hasn't initialized - // its TLS yet. Allocate a new page to store this memory. - let tp = unsafe { - map_memory( - None, - None, - TLS_MEMORY_SIZE / core::mem::size_of::<*mut u8>(), - MemoryFlags::R | MemoryFlags::W, - ) - .expect("Unable to allocate memory for thread local storage") - }; - - for val in tp.iter() { - assert!(*val as usize == 0); - } - - unsafe { - // Set the thread's `$tp` register - asm!( - "mv tp, {}", - in(reg) tp.as_mut_ptr() as usize, - ); - } - tp -} - -#[inline] -pub unsafe fn create(dtor: Option) -> Key { - // Allocate a new TLS key. These keys are shared among all threads. - #[allow(unused_unsafe)] - let key = unsafe { TLS_KEY_INDEX.fetch_add(1, Relaxed) }; - if let Some(f) = dtor { - unsafe { register_dtor(key, f) }; - } - key -} - -#[inline] -pub unsafe fn set(key: Key, value: *mut u8) { - assert!((key < 1022) && (key >= 1)); - let table = tls_table(); - table[key] = value; -} - -#[inline] -pub unsafe fn get(key: Key) -> *mut u8 { - assert!((key < 1022) && (key >= 1)); - tls_table()[key] -} - -#[inline] -pub unsafe fn destroy(_key: Key) { - // Just leak the key. Probably not great on long-running systems that create - // lots of TLS variables, but in practice that's not an issue. -} - -// ------------------------------------------------------------------------- -// Dtor registration (stolen from Windows) -// -// Xous has no native support for running destructors so we manage our own -// list of destructors to keep track of how to destroy keys. We then install a -// callback later to get invoked whenever a thread exits, running all -// appropriate destructors. -// -// Currently unregistration from this list is not supported. A destructor can be -// registered but cannot be unregistered. There's various simplifying reasons -// for doing this, the big ones being: -// -// 1. Currently we don't even support deallocating TLS keys, so normal operation -// doesn't need to deallocate a destructor. -// 2. There is no point in time where we know we can unregister a destructor -// because it could always be getting run by some remote thread. -// -// Typically processes have a statically known set of TLS keys which is pretty -// small, and we'd want to keep this memory alive for the whole process anyway -// really. -// -// Perhaps one day we can fold the `Box` here into a static allocation, -// expanding the `StaticKey` structure to contain not only a slot for the TLS -// key but also a slot for the destructor queue on windows. An optimization for -// another day! - -struct Node { - dtor: Dtor, - key: Key, - next: *mut Node, -} - -unsafe fn register_dtor(key: Key, dtor: Dtor) { - let mut node = ManuallyDrop::new(Box::new(Node { key, dtor, next: ptr::null_mut() })); - - #[allow(unused_unsafe)] - let mut head = unsafe { DTORS.load(Acquire) }; - loop { - node.next = head; - #[allow(unused_unsafe)] - match unsafe { DTORS.compare_exchange(head, &mut **node, Release, Acquire) } { - Ok(_) => return, // nothing to drop, we successfully added the node to the list - Err(cur) => head = cur, - } - } -} - -pub unsafe fn destroy_tls() { - let tp = tls_ptr_addr(); - - // If the pointer address is 0, then this thread has no TLS. - if tp.is_null() { - return; - } - - unsafe { run_dtors() }; - - // Finally, free the TLS array - unsafe { - unmap_memory(core::slice::from_raw_parts_mut( - tp, - TLS_MEMORY_SIZE / core::mem::size_of::(), - )) - .unwrap() - }; -} - -unsafe fn run_dtors() { - let mut any_run = true; - - // Run the destructor "some" number of times. This is 5x on Windows, - // so we copy it here. This allows TLS variables to create new - // TLS variables upon destruction that will also get destroyed. - // Keep going until we run out of tries or until we have nothing - // left to destroy. - for _ in 0..5 { - if !any_run { - break; - } - any_run = false; - #[allow(unused_unsafe)] - let mut cur = unsafe { DTORS.load(Acquire) }; - while !cur.is_null() { - let ptr = unsafe { get((*cur).key) }; - - if !ptr.is_null() { - unsafe { set((*cur).key, ptr::null_mut()) }; - unsafe { ((*cur).dtor)(ptr as *mut _) }; - any_run = true; - } - - unsafe { cur = (*cur).next }; - } - } -} diff --git a/library/std/src/sys/pal/xous/time.rs b/library/std/src/sys/pal/xous/time.rs deleted file mode 100644 index 4e4ae67efffa2..0000000000000 --- a/library/std/src/sys/pal/xous/time.rs +++ /dev/null @@ -1,57 +0,0 @@ -use crate::os::xous::ffi::blocking_scalar; -use crate::os::xous::services::{ - systime_server, ticktimer_server, SystimeScalar::GetUtcTimeMs, TicktimerScalar::ElapsedMs, -}; -use crate::time::Duration; - -#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)] -pub struct Instant(Duration); - -#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)] -pub struct SystemTime(Duration); - -pub const UNIX_EPOCH: SystemTime = SystemTime(Duration::from_secs(0)); - -impl Instant { - pub fn now() -> Instant { - let result = blocking_scalar(ticktimer_server(), ElapsedMs.into()) - .expect("failed to request elapsed_ms"); - let lower = result[0]; - let upper = result[1]; - Instant { 0: Duration::from_millis(lower as u64 | (upper as u64) << 32) } - } - - pub fn checked_sub_instant(&self, other: &Instant) -> Option { - self.0.checked_sub(other.0) - } - - pub fn checked_add_duration(&self, other: &Duration) -> Option { - self.0.checked_add(*other).map(Instant) - } - - pub fn checked_sub_duration(&self, other: &Duration) -> Option { - self.0.checked_sub(*other).map(Instant) - } -} - -impl SystemTime { - pub fn now() -> SystemTime { - let result = blocking_scalar(systime_server(), GetUtcTimeMs.into()) - .expect("failed to request utc time in ms"); - let lower = result[0]; - let upper = result[1]; - SystemTime { 0: Duration::from_millis((upper as u64) << 32 | lower as u64) } - } - - pub fn sub_time(&self, other: &SystemTime) -> Result { - self.0.checked_sub(other.0).ok_or_else(|| other.0 - self.0) - } - - pub fn checked_add_duration(&self, other: &Duration) -> Option { - Some(SystemTime(self.0.checked_add(*other)?)) - } - - pub fn checked_sub_duration(&self, other: &Duration) -> Option { - Some(SystemTime(self.0.checked_sub(*other)?)) - } -} diff --git a/library/std/src/sys/pal/zkvm/abi.rs b/library/std/src/sys/pal/zkvm/abi.rs deleted file mode 100644 index 53332d90e02c0..0000000000000 --- a/library/std/src/sys/pal/zkvm/abi.rs +++ /dev/null @@ -1,55 +0,0 @@ -//! ABI definitions for symbols exported by risc0-zkvm-platform. - -// Included here so we don't have to depend on risc0-zkvm-platform. -// -// FIXME: Should we move this to the "libc" crate? It seems like other -// architectures put a lot of this kind of stuff there. But there's -// currently no risc0 fork of the libc crate, so we'd either have to -// fork it or upstream it. - -#![allow(dead_code)] -pub const DIGEST_WORDS: usize = 8; - -/// Standard IO file descriptors for use with sys_read and sys_write. -pub mod fileno { - pub const STDIN: u32 = 0; - pub const STDOUT: u32 = 1; - pub const STDERR: u32 = 2; - pub const JOURNAL: u32 = 3; -} - -extern "C" { - // Wrappers around syscalls provided by risc0-zkvm-platform: - pub fn sys_halt(); - pub fn sys_output(output_id: u32, output_value: u32); - pub fn sys_sha_compress( - out_state: *mut [u32; DIGEST_WORDS], - in_state: *const [u32; DIGEST_WORDS], - block1_ptr: *const [u32; DIGEST_WORDS], - block2_ptr: *const [u32; DIGEST_WORDS], - ); - pub fn sys_sha_buffer( - out_state: *mut [u32; DIGEST_WORDS], - in_state: *const [u32; DIGEST_WORDS], - buf: *const u8, - count: u32, - ); - pub fn sys_rand(recv_buf: *mut u32, words: usize); - pub fn sys_panic(msg_ptr: *const u8, len: usize) -> !; - pub fn sys_log(msg_ptr: *const u8, len: usize); - pub fn sys_cycle_count() -> usize; - pub fn sys_read(fd: u32, recv_buf: *mut u8, nrequested: usize) -> usize; - pub fn sys_write(fd: u32, write_buf: *const u8, nbytes: usize); - pub fn sys_getenv( - recv_buf: *mut u32, - words: usize, - varname: *const u8, - varname_len: usize, - ) -> usize; - pub fn sys_argc() -> usize; - pub fn sys_argv(out_words: *mut u32, out_nwords: usize, arg_index: usize) -> usize; - - // Allocate memory from global HEAP. - pub fn sys_alloc_words(nwords: usize) -> *mut u32; - pub fn sys_alloc_aligned(nwords: usize, align: usize) -> *mut u8; -} diff --git a/library/std/src/sys/pal/zkvm/alloc.rs b/library/std/src/sys/pal/zkvm/alloc.rs deleted file mode 100644 index fd333f1215150..0000000000000 --- a/library/std/src/sys/pal/zkvm/alloc.rs +++ /dev/null @@ -1,15 +0,0 @@ -use super::abi; -use crate::alloc::{GlobalAlloc, Layout, System}; - -#[stable(feature = "alloc_system_type", since = "1.28.0")] -unsafe impl GlobalAlloc for System { - #[inline] - unsafe fn alloc(&self, layout: Layout) -> *mut u8 { - abi::sys_alloc_aligned(layout.size(), layout.align()) - } - - #[inline] - unsafe fn dealloc(&self, _ptr: *mut u8, _layout: Layout) { - // this allocator never deallocates memory - } -} diff --git a/library/std/src/sys/pal/zkvm/args.rs b/library/std/src/sys/pal/zkvm/args.rs deleted file mode 100644 index 583c16e3a4721..0000000000000 --- a/library/std/src/sys/pal/zkvm/args.rs +++ /dev/null @@ -1,81 +0,0 @@ -use super::{abi, WORD_SIZE}; -use crate::ffi::OsString; -use crate::fmt; -use crate::sys::os_str; -use crate::sys_common::FromInner; - -pub struct Args { - i_forward: usize, - i_back: usize, - count: usize, -} - -pub fn args() -> Args { - let count = unsafe { abi::sys_argc() }; - Args { i_forward: 0, i_back: 0, count } -} - -impl Args { - /// Use sys_argv to get the arg at the requested index. Does not check that i is less than argc - /// and will not return if the index is out of bounds. - fn argv(i: usize) -> OsString { - let arg_len = unsafe { abi::sys_argv(crate::ptr::null_mut(), 0, i) }; - - let arg_len_words = (arg_len + WORD_SIZE - 1) / WORD_SIZE; - let words = unsafe { abi::sys_alloc_words(arg_len_words) }; - - let arg_len2 = unsafe { abi::sys_argv(words, arg_len_words, i) }; - debug_assert_eq!(arg_len, arg_len2); - - // Convert to OsString. - // - // FIXME: We can probably get rid of the extra copy here if we - // reimplement "os_str" instead of just using the generic unix - // "os_str". - let arg_bytes: &[u8] = - unsafe { crate::slice::from_raw_parts(words.cast() as *const u8, arg_len) }; - OsString::from_inner(os_str::Buf { inner: arg_bytes.to_vec() }) - } -} - -impl fmt::Debug for Args { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().finish() - } -} - -impl Iterator for Args { - type Item = OsString; - - fn next(&mut self) -> Option { - if self.i_forward >= self.count - self.i_back { - None - } else { - let arg = Self::argv(self.i_forward); - self.i_forward += 1; - Some(arg) - } - } - - fn size_hint(&self) -> (usize, Option) { - (self.count, Some(self.count)) - } -} - -impl ExactSizeIterator for Args { - fn len(&self) -> usize { - self.count - } -} - -impl DoubleEndedIterator for Args { - fn next_back(&mut self) -> Option { - if self.i_back >= self.count - self.i_forward { - None - } else { - let arg = Self::argv(self.count - 1 - self.i_back); - self.i_back += 1; - Some(arg) - } - } -} diff --git a/library/std/src/sys/pal/zkvm/env.rs b/library/std/src/sys/pal/zkvm/env.rs deleted file mode 100644 index b85153642b1c9..0000000000000 --- a/library/std/src/sys/pal/zkvm/env.rs +++ /dev/null @@ -1,9 +0,0 @@ -pub mod os { - pub const FAMILY: &str = ""; - pub const OS: &str = ""; - pub const DLL_PREFIX: &str = ""; - pub const DLL_SUFFIX: &str = ".elf"; - pub const DLL_EXTENSION: &str = "elf"; - pub const EXE_SUFFIX: &str = ".elf"; - pub const EXE_EXTENSION: &str = "elf"; -} diff --git a/library/std/src/sys/pal/zkvm/mod.rs b/library/std/src/sys/pal/zkvm/mod.rs deleted file mode 100644 index 0b22eabca6d82..0000000000000 --- a/library/std/src/sys/pal/zkvm/mod.rs +++ /dev/null @@ -1,73 +0,0 @@ -//! System bindings for the risc0 zkvm platform -//! -//! This module contains the facade (aka platform-specific) implementations of -//! OS level functionality for zkvm. -//! -//! This is all super highly experimental and not actually intended for -//! wide/production use yet, it's still all in the experimental category. This -//! will likely change over time. - -const WORD_SIZE: usize = core::mem::size_of::(); - -pub mod alloc; -#[path = "../zkvm/args.rs"] -pub mod args; -pub mod env; -#[path = "../unsupported/fs.rs"] -pub mod fs; -#[path = "../unsupported/io.rs"] -pub mod io; -#[path = "../unsupported/net.rs"] -pub mod net; -pub mod os; -#[path = "../unsupported/pipe.rs"] -pub mod pipe; -#[path = "../unsupported/process.rs"] -pub mod process; -pub mod stdio; -pub mod thread_local_key; -#[path = "../unsupported/time.rs"] -pub mod time; - -#[path = "../unsupported/thread.rs"] -pub mod thread; - -mod abi; - -use crate::io as std_io; - -// SAFETY: must be called only once during runtime initialization. -// NOTE: this is not guaranteed to run, for example when Rust code is called externally. -pub unsafe fn init(_argc: isize, _argv: *const *const u8, _sigpipe: u8) {} - -// SAFETY: must be called only once during runtime cleanup. -// NOTE: this is not guaranteed to run, for example when the program aborts. -pub unsafe fn cleanup() {} - -pub fn unsupported() -> std_io::Result { - Err(unsupported_err()) -} - -pub fn unsupported_err() -> std_io::Error { - std_io::Error::UNSUPPORTED_PLATFORM -} - -pub fn is_interrupted(_code: i32) -> bool { - false -} - -pub fn decode_error_kind(_code: i32) -> crate::io::ErrorKind { - crate::io::ErrorKind::Uncategorized -} - -pub fn abort_internal() -> ! { - core::intrinsics::abort(); -} - -pub fn hashmap_random_keys() -> (u64, u64) { - let mut buf = [0u32; 4]; - unsafe { - abi::sys_rand(buf.as_mut_ptr(), 4); - }; - ((buf[0] as u64) << 32 + buf[1] as u64, (buf[2] as u64) << 32 + buf[3] as u64) -} diff --git a/library/std/src/sys/pal/zkvm/os.rs b/library/std/src/sys/pal/zkvm/os.rs deleted file mode 100644 index 759beb2d306b9..0000000000000 --- a/library/std/src/sys/pal/zkvm/os.rs +++ /dev/null @@ -1,140 +0,0 @@ -use super::{abi, unsupported, WORD_SIZE}; -use crate::error::Error as StdError; -use crate::ffi::{OsStr, OsString}; -use crate::fmt; -use crate::io; -use crate::marker::PhantomData; -use crate::path::{self, PathBuf}; -use crate::sys::os_str; -use crate::sys_common::FromInner; - -pub fn errno() -> i32 { - 0 -} - -pub fn error_string(_errno: i32) -> String { - "operation successful".to_string() -} - -pub fn getcwd() -> io::Result { - unsupported() -} - -pub fn chdir(_: &path::Path) -> io::Result<()> { - unsupported() -} - -pub struct SplitPaths<'a>(!, PhantomData<&'a ()>); - -pub fn split_paths(_unparsed: &OsStr) -> SplitPaths<'_> { - panic!("unsupported") -} - -impl<'a> Iterator for SplitPaths<'a> { - type Item = PathBuf; - fn next(&mut self) -> Option { - self.0 - } -} - -#[derive(Debug)] -pub struct JoinPathsError; - -pub fn join_paths(_paths: I) -> Result -where - I: Iterator, - T: AsRef, -{ - Err(JoinPathsError) -} - -impl fmt::Display for JoinPathsError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - "not supported on this platform yet".fmt(f) - } -} - -impl StdError for JoinPathsError { - #[allow(deprecated)] - fn description(&self) -> &str { - "not supported on this platform yet" - } -} - -pub fn current_exe() -> io::Result { - unsupported() -} - -pub struct Env(!); - -impl Iterator for Env { - type Item = (OsString, OsString); - fn next(&mut self) -> Option<(OsString, OsString)> { - self.0 - } -} - -pub fn env() -> Env { - panic!("not supported on this platform") -} - -impl Env { - pub fn str_debug(&self) -> impl fmt::Debug + '_ { - let Self(inner) = self; - match *inner {} - } -} - -impl fmt::Debug for Env { - fn fmt(&self, _: &mut fmt::Formatter<'_>) -> fmt::Result { - let Self(inner) = self; - match *inner {} - } -} - -pub fn getenv(varname: &OsStr) -> Option { - let varname = varname.as_encoded_bytes(); - let nbytes = - unsafe { abi::sys_getenv(crate::ptr::null_mut(), 0, varname.as_ptr(), varname.len()) }; - if nbytes == usize::MAX { - return None; - } - - let nwords = (nbytes + WORD_SIZE - 1) / WORD_SIZE; - let words = unsafe { abi::sys_alloc_words(nwords) }; - - let nbytes2 = unsafe { abi::sys_getenv(words, nwords, varname.as_ptr(), varname.len()) }; - debug_assert_eq!(nbytes, nbytes2); - - // Convert to OsString. - // - // FIXME: We can probably get rid of the extra copy here if we - // reimplement "os_str" instead of just using the generic unix - // "os_str". - let u8s: &[u8] = unsafe { crate::slice::from_raw_parts(words.cast() as *const u8, nbytes) }; - Some(OsString::from_inner(os_str::Buf { inner: u8s.to_vec() })) -} - -pub fn setenv(_: &OsStr, _: &OsStr) -> io::Result<()> { - Err(io::const_io_error!(io::ErrorKind::Unsupported, "cannot set env vars on this platform")) -} - -pub fn unsetenv(_: &OsStr) -> io::Result<()> { - Err(io::const_io_error!(io::ErrorKind::Unsupported, "cannot unset env vars on this platform")) -} - -pub fn temp_dir() -> PathBuf { - panic!("no filesystem on this platform") -} - -pub fn home_dir() -> Option { - None -} - -pub fn exit(_code: i32) -> ! { - crate::intrinsics::abort() -} - -pub fn getpid() -> u32 { - panic!("no pids on this platform") -} diff --git a/library/std/src/sys/pal/zkvm/stdio.rs b/library/std/src/sys/pal/zkvm/stdio.rs deleted file mode 100644 index e771ed0de28db..0000000000000 --- a/library/std/src/sys/pal/zkvm/stdio.rs +++ /dev/null @@ -1,64 +0,0 @@ -use super::{abi, abi::fileno}; -use crate::io; - -pub struct Stdin; -pub struct Stdout; -pub struct Stderr; - -impl Stdin { - pub const fn new() -> Stdin { - Stdin - } -} - -impl io::Read for Stdin { - fn read(&mut self, buf: &mut [u8]) -> io::Result { - Ok(unsafe { abi::sys_read(fileno::STDIN, buf.as_mut_ptr(), buf.len()) }) - } -} - -impl Stdout { - pub const fn new() -> Stdout { - Stdout - } -} - -impl io::Write for Stdout { - fn write(&mut self, buf: &[u8]) -> io::Result { - unsafe { abi::sys_write(fileno::STDOUT, buf.as_ptr(), buf.len()) } - - Ok(buf.len()) - } - - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -impl Stderr { - pub const fn new() -> Stderr { - Stderr - } -} - -impl io::Write for Stderr { - fn write(&mut self, buf: &[u8]) -> io::Result { - unsafe { abi::sys_write(fileno::STDERR, buf.as_ptr(), buf.len()) } - - Ok(buf.len()) - } - - fn flush(&mut self) -> io::Result<()> { - Ok(()) - } -} - -pub const STDIN_BUF_SIZE: usize = crate::sys_common::io::DEFAULT_BUF_SIZE; - -pub fn is_ebadf(_err: &io::Error) -> bool { - true -} - -pub fn panic_output() -> Option { - Some(Stderr::new()) -} diff --git a/library/std/src/sys/pal/zkvm/thread_local_key.rs b/library/std/src/sys/pal/zkvm/thread_local_key.rs deleted file mode 100644 index 2f67924c61823..0000000000000 --- a/library/std/src/sys/pal/zkvm/thread_local_key.rs +++ /dev/null @@ -1,23 +0,0 @@ -use crate::alloc::{alloc, Layout}; - -pub type Key = usize; - -#[inline] -pub unsafe fn create(_dtor: Option) -> Key { - alloc(Layout::new::<*mut u8>()) as _ -} - -#[inline] -pub unsafe fn set(key: Key, value: *mut u8) { - let key: *mut *mut u8 = core::ptr::with_exposed_provenance_mut(key); - *key = value; -} - -#[inline] -pub unsafe fn get(key: Key) -> *mut u8 { - let key: *mut *mut u8 = core::ptr::with_exposed_provenance_mut(key); - *key -} - -#[inline] -pub unsafe fn destroy(_key: Key) {} diff --git a/library/std/src/sys/path/mod.rs b/library/std/src/sys/path/mod.rs deleted file mode 100644 index 24a94ec782824..0000000000000 --- a/library/std/src/sys/path/mod.rs +++ /dev/null @@ -1,18 +0,0 @@ -cfg_if::cfg_if! { - if #[cfg(target_os = "windows")] { - mod windows; - pub use windows::*; - } else if #[cfg(all(target_vendor = "fortanix", target_env = "sgx"))] { - mod sgx; - pub use sgx::*; - } else if #[cfg(any( - target_os = "uefi", - target_os = "solid_asp3", - ))] { - mod unsupported_backslash; - pub use unsupported_backslash::*; - } else { - mod unix; - pub use unix::*; - } -} diff --git a/library/std/src/sys/path/sgx.rs b/library/std/src/sys/path/sgx.rs deleted file mode 100644 index c805c15e70245..0000000000000 --- a/library/std/src/sys/path/sgx.rs +++ /dev/null @@ -1,25 +0,0 @@ -use crate::ffi::OsStr; -use crate::io; -use crate::path::{Path, PathBuf, Prefix}; -use crate::sys::unsupported; - -#[inline] -pub fn is_sep_byte(b: u8) -> bool { - b == b'/' -} - -#[inline] -pub fn is_verbatim_sep(b: u8) -> bool { - b == b'/' -} - -pub fn parse_prefix(_: &OsStr) -> Option> { - None -} - -pub const MAIN_SEP_STR: &str = "/"; -pub const MAIN_SEP: char = '/'; - -pub(crate) fn absolute(_path: &Path) -> io::Result { - unsupported() -} diff --git a/library/std/src/sys/path/unix.rs b/library/std/src/sys/path/unix.rs deleted file mode 100644 index 837f68d3eaff7..0000000000000 --- a/library/std/src/sys/path/unix.rs +++ /dev/null @@ -1,63 +0,0 @@ -use crate::env; -use crate::ffi::OsStr; -use crate::io; -use crate::path::{Path, PathBuf, Prefix}; - -#[inline] -pub fn is_sep_byte(b: u8) -> bool { - b == b'/' -} - -#[inline] -pub fn is_verbatim_sep(b: u8) -> bool { - b == b'/' -} - -#[inline] -pub fn parse_prefix(_: &OsStr) -> Option> { - None -} - -pub const MAIN_SEP_STR: &str = "/"; -pub const MAIN_SEP: char = '/'; - -/// Make a POSIX path absolute without changing its semantics. -pub(crate) fn absolute(path: &Path) -> io::Result { - // This is mostly a wrapper around collecting `Path::components`, with - // exceptions made where this conflicts with the POSIX specification. - // See 4.13 Pathname Resolution, IEEE Std 1003.1-2017 - // https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap04.html#tag_04_13 - - // Get the components, skipping the redundant leading "." component if it exists. - let mut components = path.strip_prefix(".").unwrap_or(path).components(); - let path_os = path.as_os_str().as_encoded_bytes(); - - let mut normalized = if path.is_absolute() { - // "If a pathname begins with two successive characters, the - // first component following the leading characters may be - // interpreted in an implementation-defined manner, although more than - // two leading characters shall be treated as a single - // character." - if path_os.starts_with(b"//") && !path_os.starts_with(b"///") { - components.next(); - PathBuf::from("//") - } else { - PathBuf::new() - } - } else { - env::current_dir()? - }; - normalized.extend(components); - - // "Interfaces using pathname resolution may specify additional constraints - // when a pathname that does not name an existing directory contains at - // least one non- character and contains one or more trailing - // characters". - // A trailing is also meaningful if "a symbolic link is - // encountered during pathname resolution". - if path_os.ends_with(b"/") { - normalized.push(""); - } - - Ok(normalized) -} diff --git a/library/std/src/sys/path/unsupported_backslash.rs b/library/std/src/sys/path/unsupported_backslash.rs deleted file mode 100644 index 7045c9be25b08..0000000000000 --- a/library/std/src/sys/path/unsupported_backslash.rs +++ /dev/null @@ -1,25 +0,0 @@ -use crate::ffi::OsStr; -use crate::io; -use crate::path::{Path, PathBuf, Prefix}; -use crate::sys::unsupported; - -#[inline] -pub fn is_sep_byte(b: u8) -> bool { - b == b'\\' -} - -#[inline] -pub fn is_verbatim_sep(b: u8) -> bool { - b == b'\\' -} - -pub fn parse_prefix(_: &OsStr) -> Option> { - None -} - -pub const MAIN_SEP_STR: &str = "\\"; -pub const MAIN_SEP: char = '\\'; - -pub(crate) fn absolute(_path: &Path) -> io::Result { - unsupported() -} diff --git a/library/std/src/sys/path/windows.rs b/library/std/src/sys/path/windows.rs deleted file mode 100644 index cebc791023115..0000000000000 --- a/library/std/src/sys/path/windows.rs +++ /dev/null @@ -1,344 +0,0 @@ -use crate::ffi::{OsStr, OsString}; -use crate::io; -use crate::path::{Path, PathBuf, Prefix}; -use crate::ptr; -use crate::sys::pal::{c, fill_utf16_buf, os2path, to_u16s}; - -#[cfg(test)] -mod tests; - -pub const MAIN_SEP_STR: &str = "\\"; -pub const MAIN_SEP: char = '\\'; - -#[inline] -pub fn is_sep_byte(b: u8) -> bool { - b == b'/' || b == b'\\' -} - -#[inline] -pub fn is_verbatim_sep(b: u8) -> bool { - b == b'\\' -} - -/// Returns true if `path` looks like a lone filename. -pub(crate) fn is_file_name(path: &OsStr) -> bool { - !path.as_encoded_bytes().iter().copied().any(is_sep_byte) -} -pub(crate) fn has_trailing_slash(path: &OsStr) -> bool { - let is_verbatim = path.as_encoded_bytes().starts_with(br"\\?\"); - let is_separator = if is_verbatim { is_verbatim_sep } else { is_sep_byte }; - if let Some(&c) = path.as_encoded_bytes().last() { is_separator(c) } else { false } -} - -/// Appends a suffix to a path. -/// -/// Can be used to append an extension without removing an existing extension. -pub(crate) fn append_suffix(path: PathBuf, suffix: &OsStr) -> PathBuf { - let mut path = OsString::from(path); - path.push(suffix); - path.into() -} - -struct PrefixParser<'a, const LEN: usize> { - path: &'a OsStr, - prefix: [u8; LEN], -} - -impl<'a, const LEN: usize> PrefixParser<'a, LEN> { - #[inline] - fn get_prefix(path: &OsStr) -> [u8; LEN] { - let mut prefix = [0; LEN]; - // SAFETY: Only ASCII characters are modified. - for (i, &ch) in path.as_encoded_bytes().iter().take(LEN).enumerate() { - prefix[i] = if ch == b'/' { b'\\' } else { ch }; - } - prefix - } - - fn new(path: &'a OsStr) -> Self { - Self { path, prefix: Self::get_prefix(path) } - } - - fn as_slice(&self) -> PrefixParserSlice<'a, '_> { - PrefixParserSlice { - path: self.path, - prefix: &self.prefix[..LEN.min(self.path.len())], - index: 0, - } - } -} - -struct PrefixParserSlice<'a, 'b> { - path: &'a OsStr, - prefix: &'b [u8], - index: usize, -} - -impl<'a> PrefixParserSlice<'a, '_> { - fn strip_prefix(&self, prefix: &str) -> Option { - self.prefix[self.index..] - .starts_with(prefix.as_bytes()) - .then_some(Self { index: self.index + prefix.len(), ..*self }) - } - - fn prefix_bytes(&self) -> &'a [u8] { - &self.path.as_encoded_bytes()[..self.index] - } - - fn finish(self) -> &'a OsStr { - // SAFETY: The unsafety here stems from converting between &OsStr and - // &[u8] and back. This is safe to do because (1) we only look at ASCII - // contents of the encoding and (2) new &OsStr values are produced only - // from ASCII-bounded slices of existing &OsStr values. - unsafe { OsStr::from_encoded_bytes_unchecked(&self.path.as_encoded_bytes()[self.index..]) } - } -} - -pub fn parse_prefix(path: &OsStr) -> Option> { - use Prefix::{DeviceNS, Disk, Verbatim, VerbatimDisk, VerbatimUNC, UNC}; - - let parser = PrefixParser::<8>::new(path); - let parser = parser.as_slice(); - if let Some(parser) = parser.strip_prefix(r"\\") { - // \\ - - // The meaning of verbatim paths can change when they use a different - // separator. - if let Some(parser) = parser.strip_prefix(r"?\") - && !parser.prefix_bytes().iter().any(|&x| x == b'/') - { - // \\?\ - if let Some(parser) = parser.strip_prefix(r"UNC\") { - // \\?\UNC\server\share - - let path = parser.finish(); - let (server, path) = parse_next_component(path, true); - let (share, _) = parse_next_component(path, true); - - Some(VerbatimUNC(server, share)) - } else { - let path = parser.finish(); - - // in verbatim paths only recognize an exact drive prefix - if let Some(drive) = parse_drive_exact(path) { - // \\?\C: - Some(VerbatimDisk(drive)) - } else { - // \\?\prefix - let (prefix, _) = parse_next_component(path, true); - Some(Verbatim(prefix)) - } - } - } else if let Some(parser) = parser.strip_prefix(r".\") { - // \\.\COM42 - let path = parser.finish(); - let (prefix, _) = parse_next_component(path, false); - Some(DeviceNS(prefix)) - } else { - let path = parser.finish(); - let (server, path) = parse_next_component(path, false); - let (share, _) = parse_next_component(path, false); - - if !server.is_empty() && !share.is_empty() { - // \\server\share - Some(UNC(server, share)) - } else { - // no valid prefix beginning with "\\" recognized - None - } - } - } else { - // If it has a drive like `C:` then it's a disk. - // Otherwise there is no prefix. - parse_drive(path).map(Disk) - } -} - -// Parses a drive prefix, e.g. "C:" and "C:\whatever" -fn parse_drive(path: &OsStr) -> Option { - // In most DOS systems, it is not possible to have more than 26 drive letters. - // See . - fn is_valid_drive_letter(drive: &u8) -> bool { - drive.is_ascii_alphabetic() - } - - match path.as_encoded_bytes() { - [drive, b':', ..] if is_valid_drive_letter(drive) => Some(drive.to_ascii_uppercase()), - _ => None, - } -} - -// Parses a drive prefix exactly, e.g. "C:" -fn parse_drive_exact(path: &OsStr) -> Option { - // only parse two bytes: the drive letter and the drive separator - if path.as_encoded_bytes().get(2).map(|&x| is_sep_byte(x)).unwrap_or(true) { - parse_drive(path) - } else { - None - } -} - -// Parse the next path component. -// -// Returns the next component and the rest of the path excluding the component and separator. -// Does not recognize `/` as a separator character if `verbatim` is true. -fn parse_next_component(path: &OsStr, verbatim: bool) -> (&OsStr, &OsStr) { - let separator = if verbatim { is_verbatim_sep } else { is_sep_byte }; - - match path.as_encoded_bytes().iter().position(|&x| separator(x)) { - Some(separator_start) => { - let separator_end = separator_start + 1; - - let component = &path.as_encoded_bytes()[..separator_start]; - - // Panic safe - // The max `separator_end` is `bytes.len()` and `bytes[bytes.len()..]` is a valid index. - let path = &path.as_encoded_bytes()[separator_end..]; - - // SAFETY: `path` is a valid wtf8 encoded slice and each of the separators ('/', '\') - // is encoded in a single byte, therefore `bytes[separator_start]` and - // `bytes[separator_end]` must be code point boundaries and thus - // `bytes[..separator_start]` and `bytes[separator_end..]` are valid wtf8 slices. - unsafe { - ( - OsStr::from_encoded_bytes_unchecked(component), - OsStr::from_encoded_bytes_unchecked(path), - ) - } - } - None => (path, OsStr::new("")), - } -} - -/// Returns a UTF-16 encoded path capable of bypassing the legacy `MAX_PATH` limits. -/// -/// This path may or may not have a verbatim prefix. -pub(crate) fn maybe_verbatim(path: &Path) -> io::Result> { - let path = to_u16s(path)?; - get_long_path(path, true) -} - -/// Get a normalized absolute path that can bypass path length limits. -/// -/// Setting prefer_verbatim to true suggests a stronger preference for verbatim -/// paths even when not strictly necessary. This allows the Windows API to avoid -/// repeating our work. However, if the path may be given back to users or -/// passed to other application then it's preferable to use non-verbatim paths -/// when possible. Non-verbatim paths are better understood by users and handled -/// by more software. -pub(crate) fn get_long_path(mut path: Vec, prefer_verbatim: bool) -> io::Result> { - // Normally the MAX_PATH is 260 UTF-16 code units (including the NULL). - // However, for APIs such as CreateDirectory[1], the limit is 248. - // - // [1]: https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-createdirectorya#parameters - const LEGACY_MAX_PATH: usize = 248; - // UTF-16 encoded code points, used in parsing and building UTF-16 paths. - // All of these are in the ASCII range so they can be cast directly to `u16`. - const SEP: u16 = b'\\' as _; - const ALT_SEP: u16 = b'/' as _; - const QUERY: u16 = b'?' as _; - const COLON: u16 = b':' as _; - const DOT: u16 = b'.' as _; - const U: u16 = b'U' as _; - const N: u16 = b'N' as _; - const C: u16 = b'C' as _; - - // \\?\ - const VERBATIM_PREFIX: &[u16] = &[SEP, SEP, QUERY, SEP]; - // \??\ - const NT_PREFIX: &[u16] = &[SEP, QUERY, QUERY, SEP]; - // \\?\UNC\ - const UNC_PREFIX: &[u16] = &[SEP, SEP, QUERY, SEP, U, N, C, SEP]; - - if path.starts_with(VERBATIM_PREFIX) || path.starts_with(NT_PREFIX) || path == [0] { - // Early return for paths that are already verbatim or empty. - return Ok(path); - } else if path.len() < LEGACY_MAX_PATH { - // Early return if an absolute path is less < 260 UTF-16 code units. - // This is an optimization to avoid calling `GetFullPathNameW` unnecessarily. - match path.as_slice() { - // Starts with `D:`, `D:\`, `D:/`, etc. - // Does not match if the path starts with a `\` or `/`. - [drive, COLON, 0] | [drive, COLON, SEP | ALT_SEP, ..] - if *drive != SEP && *drive != ALT_SEP => - { - return Ok(path); - } - // Starts with `\\`, `//`, etc - [SEP | ALT_SEP, SEP | ALT_SEP, ..] => return Ok(path), - _ => {} - } - } - - // Firstly, get the absolute path using `GetFullPathNameW`. - // https://docs.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-getfullpathnamew - let lpfilename = path.as_ptr(); - fill_utf16_buf( - // SAFETY: `fill_utf16_buf` ensures the `buffer` and `size` are valid. - // `lpfilename` is a pointer to a null terminated string that is not - // invalidated until after `GetFullPathNameW` returns successfully. - |buffer, size| unsafe { c::GetFullPathNameW(lpfilename, size, buffer, ptr::null_mut()) }, - |mut absolute| { - path.clear(); - - // Only prepend the prefix if needed. - if prefer_verbatim || absolute.len() + 1 >= LEGACY_MAX_PATH { - // Secondly, add the verbatim prefix. This is easier here because we know the - // path is now absolute and fully normalized (e.g. `/` has been changed to `\`). - let prefix = match absolute { - // C:\ => \\?\C:\ - [_, COLON, SEP, ..] => VERBATIM_PREFIX, - // \\.\ => \\?\ - [SEP, SEP, DOT, SEP, ..] => { - absolute = &absolute[4..]; - VERBATIM_PREFIX - } - // Leave \\?\ and \??\ as-is. - [SEP, SEP, QUERY, SEP, ..] | [SEP, QUERY, QUERY, SEP, ..] => &[], - // \\ => \\?\UNC\ - [SEP, SEP, ..] => { - absolute = &absolute[2..]; - UNC_PREFIX - } - // Anything else we leave alone. - _ => &[], - }; - - path.reserve_exact(prefix.len() + absolute.len() + 1); - path.extend_from_slice(prefix); - } else { - path.reserve_exact(absolute.len() + 1); - } - path.extend_from_slice(absolute); - path.push(0); - }, - )?; - Ok(path) -} - -/// Make a Windows path absolute. -pub(crate) fn absolute(path: &Path) -> io::Result { - let path = path.as_os_str(); - let prefix = parse_prefix(path); - // Verbatim paths should not be modified. - if prefix.map(|x| x.is_verbatim()).unwrap_or(false) { - // NULs in verbatim paths are rejected for consistency. - if path.as_encoded_bytes().contains(&0) { - return Err(io::const_io_error!( - io::ErrorKind::InvalidInput, - "strings passed to WinAPI cannot contain NULs", - )); - } - return Ok(path.to_owned().into()); - } - - let path = to_u16s(path)?; - let lpfilename = path.as_ptr(); - fill_utf16_buf( - // SAFETY: `fill_utf16_buf` ensures the `buffer` and `size` are valid. - // `lpfilename` is a pointer to a null terminated string that is not - // invalidated until after `GetFullPathNameW` returns successfully. - |buffer, size| unsafe { c::GetFullPathNameW(lpfilename, size, buffer, ptr::null_mut()) }, - os2path, - ) -} diff --git a/library/std/src/sys/path/windows/tests.rs b/library/std/src/sys/path/windows/tests.rs deleted file mode 100644 index 623c6236166da..0000000000000 --- a/library/std/src/sys/path/windows/tests.rs +++ /dev/null @@ -1,137 +0,0 @@ -use super::*; - -#[test] -fn test_parse_next_component() { - assert_eq!( - parse_next_component(OsStr::new(r"server\share"), true), - (OsStr::new(r"server"), OsStr::new(r"share")) - ); - - assert_eq!( - parse_next_component(OsStr::new(r"server/share"), true), - (OsStr::new(r"server/share"), OsStr::new(r"")) - ); - - assert_eq!( - parse_next_component(OsStr::new(r"server/share"), false), - (OsStr::new(r"server"), OsStr::new(r"share")) - ); - - assert_eq!( - parse_next_component(OsStr::new(r"server\"), false), - (OsStr::new(r"server"), OsStr::new(r"")) - ); - - assert_eq!( - parse_next_component(OsStr::new(r"\server\"), false), - (OsStr::new(r""), OsStr::new(r"server\")) - ); - - assert_eq!( - parse_next_component(OsStr::new(r"servershare"), false), - (OsStr::new(r"servershare"), OsStr::new("")) - ); -} - -#[test] -fn verbatim() { - use crate::path::Path; - fn check(path: &str, expected: &str) { - let verbatim = maybe_verbatim(Path::new(path)).unwrap(); - let verbatim = String::from_utf16_lossy(verbatim.strip_suffix(&[0]).unwrap()); - assert_eq!(&verbatim, expected, "{}", path); - } - - // Ensure long paths are correctly prefixed. - check( - r"C:\Program Files\Rust\aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\foo.txt", - r"\\?\C:\Program Files\Rust\aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\foo.txt", - ); - check( - r"\\server\share\aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\foo.txt", - r"\\?\UNC\server\share\aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\foo.txt", - ); - check( - r"\\.\PIPE\aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\foo.txt", - r"\\?\PIPE\aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\foo.txt", - ); - // `\\?\` prefixed paths are left unchanged... - check( - r"\\?\verbatim.\aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\foo.txt", - r"\\?\verbatim.\aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\foo.txt", - ); - // But `//?/` is not a verbatim prefix so it will be normalized. - check( - r"//?/E:/verbatim.\aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\foo.txt", - r"\\?\E:\verbatim\aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\foo.txt", - ); - - // For performance, short absolute paths are left unchanged. - check(r"C:\Program Files\Rust", r"C:\Program Files\Rust"); - check(r"\\server\share", r"\\server\share"); - check(r"\\.\COM1", r"\\.\COM1"); - - // Check that paths of length 247 are converted to verbatim. - // This is necessary for `CreateDirectory`. - check( - r"C:\aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", - r"\\?\C:\aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", - ); - - // Make sure opening a drive will work. - check("Z:", "Z:"); - - // A path that contains null is not a valid path. - assert!(maybe_verbatim(Path::new("\0")).is_err()); -} - -fn parse_prefix(path: &str) -> Option> { - super::parse_prefix(OsStr::new(path)) -} - -#[test] -fn test_parse_prefix_verbatim() { - let prefix = Some(Prefix::VerbatimDisk(b'C')); - assert_eq!(prefix, parse_prefix(r"\\?\C:/windows/system32/notepad.exe")); - assert_eq!(prefix, parse_prefix(r"\\?\C:\windows\system32\notepad.exe")); -} - -#[test] -fn test_parse_prefix_verbatim_device() { - let prefix = Some(Prefix::UNC(OsStr::new("?"), OsStr::new("C:"))); - assert_eq!(prefix, parse_prefix(r"//?/C:/windows/system32/notepad.exe")); - assert_eq!(prefix, parse_prefix(r"//?/C:\windows\system32\notepad.exe")); - assert_eq!(prefix, parse_prefix(r"/\?\C:\windows\system32\notepad.exe")); - assert_eq!(prefix, parse_prefix(r"\\?/C:\windows\system32\notepad.exe")); -} - -// See #93586 for more information. -#[test] -fn test_windows_prefix_components() { - use crate::path::Path; - - let path = Path::new("C:"); - let mut components = path.components(); - let drive = components.next().expect("drive is expected here"); - assert_eq!(drive.as_os_str(), OsStr::new("C:")); - assert_eq!(components.as_path(), Path::new("")); -} - -/// See #101358. -/// -/// Note that the exact behaviour here may change in the future. -/// In which case this test will need to adjusted. -#[test] -fn broken_unc_path() { - use crate::path::Component; - - let mut components = Path::new(r"\\foo\\bar\\").components(); - assert_eq!(components.next(), Some(Component::RootDir)); - assert_eq!(components.next(), Some(Component::Normal("foo".as_ref()))); - assert_eq!(components.next(), Some(Component::Normal("bar".as_ref()))); - - let mut components = Path::new("//foo//bar//").components(); - assert_eq!(components.next(), Some(Component::RootDir)); - assert_eq!(components.next(), Some(Component::Normal("foo".as_ref()))); - assert_eq!(components.next(), Some(Component::Normal("bar".as_ref()))); -} diff --git a/library/std/src/sys/personality/dwarf/eh.rs b/library/std/src/sys/personality/dwarf/eh.rs deleted file mode 100644 index ff88ef4e0e1d0..0000000000000 --- a/library/std/src/sys/personality/dwarf/eh.rs +++ /dev/null @@ -1,264 +0,0 @@ -//! Parsing of GCC-style Language-Specific Data Area (LSDA) -//! For details see: -//! * -//! * -//! * -//! * -//! * -//! -//! A reference implementation may be found in the GCC source tree -//! (`/libgcc/unwind-c.c` as of this writing). - -#![allow(non_upper_case_globals)] -#![allow(unused)] - -use super::DwarfReader; -use core::mem; -use core::ptr; - -pub const DW_EH_PE_omit: u8 = 0xFF; -pub const DW_EH_PE_absptr: u8 = 0x00; - -pub const DW_EH_PE_uleb128: u8 = 0x01; -pub const DW_EH_PE_udata2: u8 = 0x02; -pub const DW_EH_PE_udata4: u8 = 0x03; -pub const DW_EH_PE_udata8: u8 = 0x04; -pub const DW_EH_PE_sleb128: u8 = 0x09; -pub const DW_EH_PE_sdata2: u8 = 0x0A; -pub const DW_EH_PE_sdata4: u8 = 0x0B; -pub const DW_EH_PE_sdata8: u8 = 0x0C; - -pub const DW_EH_PE_pcrel: u8 = 0x10; -pub const DW_EH_PE_textrel: u8 = 0x20; -pub const DW_EH_PE_datarel: u8 = 0x30; -pub const DW_EH_PE_funcrel: u8 = 0x40; -pub const DW_EH_PE_aligned: u8 = 0x50; - -pub const DW_EH_PE_indirect: u8 = 0x80; - -#[derive(Copy, Clone)] -pub struct EHContext<'a> { - pub ip: *const u8, // Current instruction pointer - pub func_start: *const u8, // Pointer to the current function - pub get_text_start: &'a dyn Fn() -> *const u8, // Get pointer to the code section - pub get_data_start: &'a dyn Fn() -> *const u8, // Get pointer to the data section -} - -/// Landing pad. -type LPad = *const u8; -pub enum EHAction { - None, - Cleanup(LPad), - Catch(LPad), - Filter(LPad), - Terminate, -} - -/// 32-bit Apple ARM uses SjLj exceptions, except for watchOS. -/// -/// I.e. iOS and tvOS, as those are the only Apple OSes that used 32-bit ARM -/// devices. -/// -/// -pub const USING_SJLJ_EXCEPTIONS: bool = - cfg!(all(target_vendor = "apple", not(target_os = "watchos"), target_arch = "arm")); - -pub unsafe fn find_eh_action(lsda: *const u8, context: &EHContext<'_>) -> Result { - if lsda.is_null() { - return Ok(EHAction::None); - } - - let func_start = context.func_start; - let mut reader = DwarfReader::new(lsda); - - let start_encoding = reader.read::(); - // base address for landing pad offsets - let lpad_base = if start_encoding != DW_EH_PE_omit { - read_encoded_pointer(&mut reader, context, start_encoding)? - } else { - func_start - }; - - let ttype_encoding = reader.read::(); - if ttype_encoding != DW_EH_PE_omit { - // Rust doesn't analyze exception types, so we don't care about the type table - reader.read_uleb128(); - } - - let call_site_encoding = reader.read::(); - let call_site_table_length = reader.read_uleb128(); - let action_table = reader.ptr.add(call_site_table_length as usize); - let ip = context.ip; - - if !USING_SJLJ_EXCEPTIONS { - // read the callsite table - while reader.ptr < action_table { - // these are offsets rather than pointers; - let cs_start = read_encoded_offset(&mut reader, call_site_encoding)?; - let cs_len = read_encoded_offset(&mut reader, call_site_encoding)?; - let cs_lpad = read_encoded_offset(&mut reader, call_site_encoding)?; - let cs_action_entry = reader.read_uleb128(); - // Callsite table is sorted by cs_start, so if we've passed the ip, we - // may stop searching. - if ip < func_start.wrapping_add(cs_start) { - break; - } - if ip < func_start.wrapping_add(cs_start + cs_len) { - if cs_lpad == 0 { - return Ok(EHAction::None); - } else { - let lpad = lpad_base.wrapping_add(cs_lpad); - return Ok(interpret_cs_action(action_table, cs_action_entry, lpad)); - } - } - } - // Ip is not present in the table. This indicates a nounwind call. - Ok(EHAction::Terminate) - } else { - // SjLj version: - // The "IP" is an index into the call-site table, with two exceptions: - // -1 means 'no-action', and 0 means 'terminate'. - match ip.addr() as isize { - -1 => return Ok(EHAction::None), - 0 => return Ok(EHAction::Terminate), - _ => (), - } - let mut idx = ip.addr(); - loop { - let cs_lpad = reader.read_uleb128(); - let cs_action_entry = reader.read_uleb128(); - idx -= 1; - if idx == 0 { - // Can never have null landing pad for sjlj -- that would have - // been indicated by a -1 call site index. - // FIXME(strict provenance) - let lpad = ptr::with_exposed_provenance((cs_lpad + 1) as usize); - return Ok(interpret_cs_action(action_table, cs_action_entry, lpad)); - } - } - } -} - -unsafe fn interpret_cs_action( - action_table: *const u8, - cs_action_entry: u64, - lpad: LPad, -) -> EHAction { - if cs_action_entry == 0 { - // If cs_action_entry is 0 then this is a cleanup (Drop::drop). We run these - // for both Rust panics and foreign exceptions. - EHAction::Cleanup(lpad) - } else { - // If lpad != 0 and cs_action_entry != 0, we have to check ttype_index. - // If ttype_index == 0 under the condition, we take cleanup action. - let action_record = action_table.offset(cs_action_entry as isize - 1); - let mut action_reader = DwarfReader::new(action_record); - let ttype_index = action_reader.read_sleb128(); - if ttype_index == 0 { - EHAction::Cleanup(lpad) - } else if ttype_index > 0 { - // Stop unwinding Rust panics at catch_unwind. - EHAction::Catch(lpad) - } else { - EHAction::Filter(lpad) - } - } -} - -#[inline] -fn round_up(unrounded: usize, align: usize) -> Result { - if align.is_power_of_two() { Ok((unrounded + align - 1) & !(align - 1)) } else { Err(()) } -} - -/// Read a offset (`usize`) from `reader` whose encoding is described by `encoding`. -/// -/// `encoding` must be a [DWARF Exception Header Encoding as described by the LSB spec][LSB-dwarf-ext]. -/// In addition the upper ("application") part must be zero. -/// -/// # Errors -/// Returns `Err` if `encoding` -/// * is not a valid DWARF Exception Header Encoding, -/// * is `DW_EH_PE_omit`, or -/// * has a non-zero application part. -/// -/// [LSB-dwarf-ext]: https://refspecs.linuxfoundation.org/LSB_5.0.0/LSB-Core-generic/LSB-Core-generic/dwarfext.html -unsafe fn read_encoded_offset(reader: &mut DwarfReader, encoding: u8) -> Result { - if encoding == DW_EH_PE_omit || encoding & 0xF0 != 0 { - return Err(()); - } - let result = match encoding & 0x0F { - // despite the name, LLVM also uses absptr for offsets instead of pointers - DW_EH_PE_absptr => reader.read::(), - DW_EH_PE_uleb128 => reader.read_uleb128() as usize, - DW_EH_PE_udata2 => reader.read::() as usize, - DW_EH_PE_udata4 => reader.read::() as usize, - DW_EH_PE_udata8 => reader.read::() as usize, - DW_EH_PE_sleb128 => reader.read_sleb128() as usize, - DW_EH_PE_sdata2 => reader.read::() as usize, - DW_EH_PE_sdata4 => reader.read::() as usize, - DW_EH_PE_sdata8 => reader.read::() as usize, - _ => return Err(()), - }; - Ok(result) -} - -/// Read a pointer from `reader` whose encoding is described by `encoding`. -/// -/// `encoding` must be a [DWARF Exception Header Encoding as described by the LSB spec][LSB-dwarf-ext]. -/// -/// # Errors -/// Returns `Err` if `encoding` -/// * is not a valid DWARF Exception Header Encoding, -/// * is `DW_EH_PE_omit`, or -/// * combines `DW_EH_PE_absptr` or `DW_EH_PE_aligned` application part with an integer encoding -/// (not `DW_EH_PE_absptr`) in the value format part. -/// -/// [LSB-dwarf-ext]: https://refspecs.linuxfoundation.org/LSB_5.0.0/LSB-Core-generic/LSB-Core-generic/dwarfext.html -unsafe fn read_encoded_pointer( - reader: &mut DwarfReader, - context: &EHContext<'_>, - encoding: u8, -) -> Result<*const u8, ()> { - if encoding == DW_EH_PE_omit { - return Err(()); - } - - let base_ptr = match encoding & 0x70 { - DW_EH_PE_absptr => core::ptr::null(), - // relative to address of the encoded value, despite the name - DW_EH_PE_pcrel => reader.ptr, - DW_EH_PE_funcrel => { - if context.func_start.is_null() { - return Err(()); - } - context.func_start - } - DW_EH_PE_textrel => (*context.get_text_start)(), - DW_EH_PE_datarel => (*context.get_data_start)(), - // aligned means the value is aligned to the size of a pointer - DW_EH_PE_aligned => { - reader.ptr = - reader.ptr.with_addr(round_up(reader.ptr.addr(), mem::size_of::<*const u8>())?); - core::ptr::null() - } - _ => return Err(()), - }; - - let mut ptr = if base_ptr.is_null() { - // any value encoding other than absptr would be nonsensical here; - // there would be no source of pointer provenance - if encoding & 0x0F != DW_EH_PE_absptr { - return Err(()); - } - reader.read::<*const u8>() - } else { - let offset = read_encoded_offset(reader, encoding & 0x0F)?; - base_ptr.wrapping_add(offset) - }; - - if encoding & DW_EH_PE_indirect != 0 { - ptr = *(ptr.cast::<*const u8>()); - } - - Ok(ptr) -} diff --git a/library/std/src/sys/personality/dwarf/mod.rs b/library/std/src/sys/personality/dwarf/mod.rs deleted file mode 100644 index 652fbe95a14d1..0000000000000 --- a/library/std/src/sys/personality/dwarf/mod.rs +++ /dev/null @@ -1,73 +0,0 @@ -//! Utilities for parsing DWARF-encoded data streams. -//! See , -//! DWARF-4 standard, Section 7 - "Data Representation" - -// This module is used only by x86_64-pc-windows-gnu for now, but we -// are compiling it everywhere to avoid regressions. -#![allow(unused)] - -#[cfg(test)] -mod tests; - -pub mod eh; - -use core::mem; - -pub struct DwarfReader { - pub ptr: *const u8, -} - -#[repr(C, packed)] -struct Unaligned(T); - -impl DwarfReader { - pub fn new(ptr: *const u8) -> DwarfReader { - DwarfReader { ptr } - } - - // DWARF streams are packed, so e.g., a u32 would not necessarily be aligned - // on a 4-byte boundary. This may cause problems on platforms with strict - // alignment requirements. By wrapping data in a "packed" struct, we are - // telling the backend to generate "misalignment-safe" code. - pub unsafe fn read(&mut self) -> T { - let Unaligned(result) = *(self.ptr as *const Unaligned); - self.ptr = self.ptr.add(mem::size_of::()); - result - } - - // ULEB128 and SLEB128 encodings are defined in Section 7.6 - "Variable - // Length Data". - pub unsafe fn read_uleb128(&mut self) -> u64 { - let mut shift: usize = 0; - let mut result: u64 = 0; - let mut byte: u8; - loop { - byte = self.read::(); - result |= ((byte & 0x7F) as u64) << shift; - shift += 7; - if byte & 0x80 == 0 { - break; - } - } - result - } - - pub unsafe fn read_sleb128(&mut self) -> i64 { - let mut shift: u32 = 0; - let mut result: u64 = 0; - let mut byte: u8; - loop { - byte = self.read::(); - result |= ((byte & 0x7F) as u64) << shift; - shift += 7; - if byte & 0x80 == 0 { - break; - } - } - // sign-extend - if shift < u64::BITS && (byte & 0x40) != 0 { - result |= (!0 as u64) << shift; - } - result as i64 - } -} diff --git a/library/std/src/sys/personality/dwarf/tests.rs b/library/std/src/sys/personality/dwarf/tests.rs deleted file mode 100644 index 1644f37083a5b..0000000000000 --- a/library/std/src/sys/personality/dwarf/tests.rs +++ /dev/null @@ -1,19 +0,0 @@ -use super::*; - -#[test] -fn dwarf_reader() { - let encoded: &[u8] = &[1, 2, 3, 4, 5, 6, 7, 0xE5, 0x8E, 0x26, 0x9B, 0xF1, 0x59, 0xFF, 0xFF]; - - let mut reader = DwarfReader::new(encoded.as_ptr()); - - unsafe { - assert!(reader.read::() == u8::to_be(1u8)); - assert!(reader.read::() == u16::to_be(0x0203)); - assert!(reader.read::() == u32::to_be(0x04050607)); - - assert!(reader.read_uleb128() == 624485); - assert!(reader.read_sleb128() == -624485); - - assert!(reader.read::() == i8::to_be(-1)); - } -} diff --git a/library/std/src/sys/personality/emcc.rs b/library/std/src/sys/personality/emcc.rs deleted file mode 100644 index cb52ae89b1911..0000000000000 --- a/library/std/src/sys/personality/emcc.rs +++ /dev/null @@ -1,20 +0,0 @@ -//! On Emscripten Rust panics are wrapped in C++ exceptions, so we just forward -//! to `__gxx_personality_v0` which is provided by Emscripten. - -use crate::ffi::c_int; -use unwind as uw; - -// This is required by the compiler to exist (e.g., it's a lang item), but it's -// never actually called by the compiler. Emscripten EH doesn't use a -// personality function at all, it instead uses __cxa_find_matching_catch. -// Wasm error handling would use __gxx_personality_wasm0. -#[lang = "eh_personality"] -unsafe extern "C" fn rust_eh_personality( - _version: c_int, - _actions: uw::_Unwind_Action, - _exception_class: uw::_Unwind_Exception_Class, - _exception_object: *mut uw::_Unwind_Exception, - _context: *mut uw::_Unwind_Context, -) -> uw::_Unwind_Reason_Code { - core::intrinsics::abort() -} diff --git a/library/std/src/sys/personality/gcc.rs b/library/std/src/sys/personality/gcc.rs deleted file mode 100644 index 0dc53550ca943..0000000000000 --- a/library/std/src/sys/personality/gcc.rs +++ /dev/null @@ -1,294 +0,0 @@ -//! Implementation of panics backed by libgcc/libunwind (in some form). -//! -//! For background on exception handling and stack unwinding please see -//! "Exception Handling in LLVM" (llvm.org/docs/ExceptionHandling.html) and -//! documents linked from it. -//! These are also good reads: -//! * -//! * -//! * -//! -//! ## A brief summary -//! -//! Exception handling happens in two phases: a search phase and a cleanup -//! phase. -//! -//! In both phases the unwinder walks stack frames from top to bottom using -//! information from the stack frame unwind sections of the current process's -//! modules ("module" here refers to an OS module, i.e., an executable or a -//! dynamic library). -//! -//! For each stack frame, it invokes the associated "personality routine", whose -//! address is also stored in the unwind info section. -//! -//! In the search phase, the job of a personality routine is to examine -//! exception object being thrown, and to decide whether it should be caught at -//! that stack frame. Once the handler frame has been identified, cleanup phase -//! begins. -//! -//! In the cleanup phase, the unwinder invokes each personality routine again. -//! This time it decides which (if any) cleanup code needs to be run for -//! the current stack frame. If so, the control is transferred to a special -//! branch in the function body, the "landing pad", which invokes destructors, -//! frees memory, etc. At the end of the landing pad, control is transferred -//! back to the unwinder and unwinding resumes. -//! -//! Once stack has been unwound down to the handler frame level, unwinding stops -//! and the last personality routine transfers control to the catch block. - -use super::dwarf::eh::{self, EHAction, EHContext}; -use crate::ffi::c_int; -use unwind as uw; - -// Register ids were lifted from LLVM's TargetLowering::getExceptionPointerRegister() -// and TargetLowering::getExceptionSelectorRegister() for each architecture, -// then mapped to DWARF register numbers via register definition tables -// (typically RegisterInfo.td, search for "DwarfRegNum"). -// See also https://llvm.org/docs/WritingAnLLVMBackend.html#defining-a-register. - -#[cfg(target_arch = "x86")] -const UNWIND_DATA_REG: (i32, i32) = (0, 2); // EAX, EDX - -#[cfg(target_arch = "x86_64")] -const UNWIND_DATA_REG: (i32, i32) = (0, 1); // RAX, RDX - -#[cfg(any(target_arch = "arm", target_arch = "aarch64"))] -const UNWIND_DATA_REG: (i32, i32) = (0, 1); // R0, R1 / X0, X1 - -#[cfg(target_arch = "m68k")] -const UNWIND_DATA_REG: (i32, i32) = (0, 1); // D0, D1 - -#[cfg(any( - target_arch = "mips", - target_arch = "mips32r6", - target_arch = "mips64", - target_arch = "mips64r6" -))] -const UNWIND_DATA_REG: (i32, i32) = (4, 5); // A0, A1 - -#[cfg(target_arch = "csky")] -const UNWIND_DATA_REG: (i32, i32) = (0, 1); // R0, R1 - -#[cfg(any(target_arch = "powerpc", target_arch = "powerpc64"))] -const UNWIND_DATA_REG: (i32, i32) = (3, 4); // R3, R4 / X3, X4 - -#[cfg(target_arch = "s390x")] -const UNWIND_DATA_REG: (i32, i32) = (6, 7); // R6, R7 - -#[cfg(any(target_arch = "sparc", target_arch = "sparc64"))] -const UNWIND_DATA_REG: (i32, i32) = (24, 25); // I0, I1 - -#[cfg(target_arch = "hexagon")] -const UNWIND_DATA_REG: (i32, i32) = (0, 1); // R0, R1 - -#[cfg(any(target_arch = "riscv64", target_arch = "riscv32"))] -const UNWIND_DATA_REG: (i32, i32) = (10, 11); // x10, x11 - -#[cfg(target_arch = "loongarch64")] -const UNWIND_DATA_REG: (i32, i32) = (4, 5); // a0, a1 - -// The following code is based on GCC's C and C++ personality routines. For reference, see: -// https://github.com/gcc-mirror/gcc/blob/master/libstdc++-v3/libsupc++/eh_personality.cc -// https://github.com/gcc-mirror/gcc/blob/trunk/libgcc/unwind-c.c - -cfg_if::cfg_if! { - if #[cfg(all(not(all(target_vendor = "apple", not(target_os = "watchos"))), target_arch = "arm", not(target_os = "netbsd")))] { - // ARM EHABI personality routine. - // https://web.archive.org/web/20190728160938/https://infocenter.arm.com/help/topic/com.arm.doc.ihi0038b/IHI0038B_ehabi.pdf - // - // Apple 32-bit ARM (but not watchOS) uses the default routine instead - // since it uses SjLj unwinding. - #[lang = "eh_personality"] - unsafe extern "C" fn rust_eh_personality( - state: uw::_Unwind_State, - exception_object: *mut uw::_Unwind_Exception, - context: *mut uw::_Unwind_Context, - ) -> uw::_Unwind_Reason_Code { - let state = state as c_int; - let action = state & uw::_US_ACTION_MASK as c_int; - let search_phase = if action == uw::_US_VIRTUAL_UNWIND_FRAME as c_int { - // Backtraces on ARM will call the personality routine with - // state == _US_VIRTUAL_UNWIND_FRAME | _US_FORCE_UNWIND. In those cases - // we want to continue unwinding the stack, otherwise all our backtraces - // would end at __rust_try - if state & uw::_US_FORCE_UNWIND as c_int != 0 { - return continue_unwind(exception_object, context); - } - true - } else if action == uw::_US_UNWIND_FRAME_STARTING as c_int { - false - } else if action == uw::_US_UNWIND_FRAME_RESUME as c_int { - return continue_unwind(exception_object, context); - } else { - return uw::_URC_FAILURE; - }; - - // The DWARF unwinder assumes that _Unwind_Context holds things like the function - // and LSDA pointers, however ARM EHABI places them into the exception object. - // To preserve signatures of functions like _Unwind_GetLanguageSpecificData(), which - // take only the context pointer, GCC personality routines stash a pointer to - // exception_object in the context, using location reserved for ARM's - // "scratch register" (r12). - uw::_Unwind_SetGR(context, uw::UNWIND_POINTER_REG, exception_object as uw::_Unwind_Ptr); - // ...A more principled approach would be to provide the full definition of ARM's - // _Unwind_Context in our libunwind bindings and fetch the required data from there - // directly, bypassing DWARF compatibility functions. - - let eh_action = match find_eh_action(context) { - Ok(action) => action, - Err(_) => return uw::_URC_FAILURE, - }; - if search_phase { - match eh_action { - EHAction::None | EHAction::Cleanup(_) => { - return continue_unwind(exception_object, context); - } - EHAction::Catch(_) | EHAction::Filter(_) => { - // EHABI requires the personality routine to update the - // SP value in the barrier cache of the exception object. - (*exception_object).private[5] = - uw::_Unwind_GetGR(context, uw::UNWIND_SP_REG); - return uw::_URC_HANDLER_FOUND; - } - EHAction::Terminate => return uw::_URC_FAILURE, - } - } else { - match eh_action { - EHAction::None => return continue_unwind(exception_object, context), - EHAction::Filter(_) if state & uw::_US_FORCE_UNWIND as c_int != 0 => return continue_unwind(exception_object, context), - EHAction::Cleanup(lpad) | EHAction::Catch(lpad) | EHAction::Filter(lpad) => { - uw::_Unwind_SetGR( - context, - UNWIND_DATA_REG.0, - exception_object as uw::_Unwind_Ptr, - ); - uw::_Unwind_SetGR(context, UNWIND_DATA_REG.1, core::ptr::null()); - uw::_Unwind_SetIP(context, lpad); - return uw::_URC_INSTALL_CONTEXT; - } - EHAction::Terminate => return uw::_URC_FAILURE, - } - } - - // On ARM EHABI the personality routine is responsible for actually - // unwinding a single stack frame before returning (ARM EHABI Sec. 6.1). - unsafe fn continue_unwind( - exception_object: *mut uw::_Unwind_Exception, - context: *mut uw::_Unwind_Context, - ) -> uw::_Unwind_Reason_Code { - if __gnu_unwind_frame(exception_object, context) == uw::_URC_NO_REASON { - uw::_URC_CONTINUE_UNWIND - } else { - uw::_URC_FAILURE - } - } - // defined in libgcc - extern "C" { - fn __gnu_unwind_frame( - exception_object: *mut uw::_Unwind_Exception, - context: *mut uw::_Unwind_Context, - ) -> uw::_Unwind_Reason_Code; - } - } - } else { - // Default personality routine, which is used directly on most targets - // and indirectly on Windows x86_64 via SEH. - unsafe extern "C" fn rust_eh_personality_impl( - version: c_int, - actions: uw::_Unwind_Action, - _exception_class: uw::_Unwind_Exception_Class, - exception_object: *mut uw::_Unwind_Exception, - context: *mut uw::_Unwind_Context, - ) -> uw::_Unwind_Reason_Code { - if version != 1 { - return uw::_URC_FATAL_PHASE1_ERROR; - } - let eh_action = match find_eh_action(context) { - Ok(action) => action, - Err(_) => return uw::_URC_FATAL_PHASE1_ERROR, - }; - if actions as i32 & uw::_UA_SEARCH_PHASE as i32 != 0 { - match eh_action { - EHAction::None | EHAction::Cleanup(_) => uw::_URC_CONTINUE_UNWIND, - EHAction::Catch(_) | EHAction::Filter(_) => uw::_URC_HANDLER_FOUND, - EHAction::Terminate => uw::_URC_FATAL_PHASE1_ERROR, - } - } else { - match eh_action { - EHAction::None => uw::_URC_CONTINUE_UNWIND, - // Forced unwinding hits a terminate action. - EHAction::Filter(_) if actions as i32 & uw::_UA_FORCE_UNWIND as i32 != 0 => uw::_URC_CONTINUE_UNWIND, - EHAction::Cleanup(lpad) | EHAction::Catch(lpad) | EHAction::Filter(lpad) => { - uw::_Unwind_SetGR( - context, - UNWIND_DATA_REG.0, - exception_object.cast(), - ); - uw::_Unwind_SetGR(context, UNWIND_DATA_REG.1, core::ptr::null()); - uw::_Unwind_SetIP(context, lpad); - uw::_URC_INSTALL_CONTEXT - } - EHAction::Terminate => uw::_URC_FATAL_PHASE2_ERROR, - } - } - } - - cfg_if::cfg_if! { - if #[cfg(all(windows, any(target_arch = "aarch64", target_arch = "x86_64"), target_env = "gnu"))] { - // On x86_64 MinGW targets, the unwinding mechanism is SEH however the unwind - // handler data (aka LSDA) uses GCC-compatible encoding. - #[lang = "eh_personality"] - #[allow(nonstandard_style)] - unsafe extern "C" fn rust_eh_personality( - exceptionRecord: *mut uw::EXCEPTION_RECORD, - establisherFrame: uw::LPVOID, - contextRecord: *mut uw::CONTEXT, - dispatcherContext: *mut uw::DISPATCHER_CONTEXT, - ) -> uw::EXCEPTION_DISPOSITION { - uw::_GCC_specific_handler( - exceptionRecord, - establisherFrame, - contextRecord, - dispatcherContext, - rust_eh_personality_impl, - ) - } - } else { - // The personality routine for most of our targets. - #[lang = "eh_personality"] - unsafe extern "C" fn rust_eh_personality( - version: c_int, - actions: uw::_Unwind_Action, - exception_class: uw::_Unwind_Exception_Class, - exception_object: *mut uw::_Unwind_Exception, - context: *mut uw::_Unwind_Context, - ) -> uw::_Unwind_Reason_Code { - rust_eh_personality_impl( - version, - actions, - exception_class, - exception_object, - context, - ) - } - } - } - } -} - -unsafe fn find_eh_action(context: *mut uw::_Unwind_Context) -> Result { - let lsda = uw::_Unwind_GetLanguageSpecificData(context) as *const u8; - let mut ip_before_instr: c_int = 0; - let ip = uw::_Unwind_GetIPInfo(context, &mut ip_before_instr); - let eh_context = EHContext { - // The return address points 1 byte past the call instruction, - // which could be in the next IP range in LSDA range table. - // - // `ip = -1` has special meaning, so use wrapping sub to allow for that - ip: if ip_before_instr != 0 { ip } else { ip.wrapping_sub(1) }, - func_start: uw::_Unwind_GetRegionStart(context), - get_text_start: &|| uw::_Unwind_GetTextRelBase(context), - get_data_start: &|| uw::_Unwind_GetDataRelBase(context), - }; - eh::find_eh_action(lsda, &eh_context) -} diff --git a/library/std/src/sys/personality/mod.rs b/library/std/src/sys/personality/mod.rs deleted file mode 100644 index 1a6ea1dafcb53..0000000000000 --- a/library/std/src/sys/personality/mod.rs +++ /dev/null @@ -1,47 +0,0 @@ -//! This module contains the implementation of the `eh_personality` lang item. -//! -//! The actual implementation is heavily dependent on the target since Rust -//! tries to use the native stack unwinding mechanism whenever possible. -//! -//! This personality function is still required with `-C panic=abort` because -//! it is used to catch foreign exceptions from `extern "C-unwind"` and turn -//! them into aborts. -//! -//! Additionally, ARM EHABI uses the personality function when generating -//! backtraces. - -mod dwarf; - -#[cfg(not(any(test, doctest)))] -cfg_if::cfg_if! { - if #[cfg(target_os = "emscripten")] { - mod emcc; - } else if #[cfg(any(target_env = "msvc", target_family = "wasm"))] { - // This is required by the compiler to exist (e.g., it's a lang item), - // but it's never actually called by the compiler because - // __CxxFrameHandler3 (msvc) / __gxx_wasm_personality_v0 (wasm) is the - // personality function that is always used. Hence this is just an - // aborting stub. - #[lang = "eh_personality"] - fn rust_eh_personality() { - core::intrinsics::abort() - } - } else if #[cfg(any( - all(target_family = "windows", target_env = "gnu"), - target_os = "psp", - target_os = "xous", - target_os = "solid_asp3", - all(target_family = "unix", not(target_os = "espidf"), not(target_os = "l4re")), - all(target_vendor = "fortanix", target_env = "sgx"), - ))] { - mod gcc; - } else { - // Targets that don't support unwinding. - // - os=none ("bare metal" targets) - // - os=uefi - // - os=espidf - // - os=hermit - // - nvptx64-nvidia-cuda - // - arch=avr - } -} diff --git a/library/std/src/sys/sync/condvar/futex.rs b/library/std/src/sys/sync/condvar/futex.rs deleted file mode 100644 index 4586d0fd941a7..0000000000000 --- a/library/std/src/sys/sync/condvar/futex.rs +++ /dev/null @@ -1,56 +0,0 @@ -use crate::sync::atomic::{AtomicU32, Ordering::Relaxed}; -use crate::sys::futex::{futex_wait, futex_wake, futex_wake_all}; -use crate::sys::sync::Mutex; -use crate::time::Duration; - -pub struct Condvar { - // The value of this atomic is simply incremented on every notification. - // This is used by `.wait()` to not miss any notifications after - // unlocking the mutex and before waiting for notifications. - futex: AtomicU32, -} - -impl Condvar { - #[inline] - pub const fn new() -> Self { - Self { futex: AtomicU32::new(0) } - } - - // All the memory orderings here are `Relaxed`, - // because synchronization is done by unlocking and locking the mutex. - - pub fn notify_one(&self) { - self.futex.fetch_add(1, Relaxed); - futex_wake(&self.futex); - } - - pub fn notify_all(&self) { - self.futex.fetch_add(1, Relaxed); - futex_wake_all(&self.futex); - } - - pub unsafe fn wait(&self, mutex: &Mutex) { - self.wait_optional_timeout(mutex, None); - } - - pub unsafe fn wait_timeout(&self, mutex: &Mutex, timeout: Duration) -> bool { - self.wait_optional_timeout(mutex, Some(timeout)) - } - - unsafe fn wait_optional_timeout(&self, mutex: &Mutex, timeout: Option) -> bool { - // Examine the notification counter _before_ we unlock the mutex. - let futex_value = self.futex.load(Relaxed); - - // Unlock the mutex before going to sleep. - mutex.unlock(); - - // Wait, but only if there hasn't been any - // notification since we unlocked the mutex. - let r = futex_wait(&self.futex, futex_value, timeout); - - // Lock the mutex again. - mutex.lock(); - - r - } -} diff --git a/library/std/src/sys/sync/condvar/itron.rs b/library/std/src/sys/sync/condvar/itron.rs deleted file mode 100644 index 9b64d241efd12..0000000000000 --- a/library/std/src/sys/sync/condvar/itron.rs +++ /dev/null @@ -1,294 +0,0 @@ -//! POSIX conditional variable implementation based on user-space wait queues. -use crate::sys::pal::itron::{ - abi, error::expect_success_aborting, spin::SpinMutex, task, time::with_tmos_strong, -}; -use crate::{mem::replace, ptr::NonNull, sys::sync::Mutex, time::Duration}; - -// The implementation is inspired by the queue-based implementation shown in -// Andrew D. Birrell's paper "Implementing Condition Variables with Semaphores" - -pub struct Condvar { - waiters: SpinMutex, -} - -unsafe impl Send for Condvar {} -unsafe impl Sync for Condvar {} - -impl Condvar { - #[inline] - pub const fn new() -> Condvar { - Condvar { waiters: SpinMutex::new(waiter_queue::WaiterQueue::new()) } - } - - pub fn notify_one(&self) { - self.waiters.with_locked(|waiters| { - if let Some(task) = waiters.pop_front() { - // Unpark the task - match unsafe { abi::wup_tsk(task) } { - // The task already has a token. - abi::E_QOVR => {} - // Can't undo the effect; abort the program on failure - er => { - expect_success_aborting(er, &"wup_tsk"); - } - } - } - }); - } - - pub fn notify_all(&self) { - self.waiters.with_locked(|waiters| { - while let Some(task) = waiters.pop_front() { - // Unpark the task - match unsafe { abi::wup_tsk(task) } { - // The task already has a token. - abi::E_QOVR => {} - // Can't undo the effect; abort the program on failure - er => { - expect_success_aborting(er, &"wup_tsk"); - } - } - } - }); - } - - pub unsafe fn wait(&self, mutex: &Mutex) { - // Construct `Waiter`. - let mut waiter = waiter_queue::Waiter::new(); - let waiter = NonNull::from(&mut waiter); - - self.waiters.with_locked(|waiters| unsafe { - waiters.insert(waiter); - }); - - unsafe { mutex.unlock() }; - - // Wait until `waiter` is removed from the queue - loop { - // Park the current task - expect_success_aborting(unsafe { abi::slp_tsk() }, &"slp_tsk"); - - if !self.waiters.with_locked(|waiters| unsafe { waiters.is_queued(waiter) }) { - break; - } - } - - mutex.lock(); - } - - pub unsafe fn wait_timeout(&self, mutex: &Mutex, dur: Duration) -> bool { - // Construct and pin `Waiter` - let mut waiter = waiter_queue::Waiter::new(); - let waiter = NonNull::from(&mut waiter); - - self.waiters.with_locked(|waiters| unsafe { - waiters.insert(waiter); - }); - - unsafe { mutex.unlock() }; - - // Park the current task and do not wake up until the timeout elapses - // or the task gets woken up by `notify_*` - match with_tmos_strong(dur, |tmo| { - let er = unsafe { abi::tslp_tsk(tmo) }; - if er == 0 { - // We were unparked. Are we really dequeued? - if self.waiters.with_locked(|waiters| unsafe { waiters.is_queued(waiter) }) { - // No we are not. Continue waiting. - return abi::E_TMOUT; - } - } - er - }) { - abi::E_TMOUT => {} - er => { - expect_success_aborting(er, &"tslp_tsk"); - } - } - - // Remove `waiter` from `self.waiters`. If `waiter` is still in - // `waiters`, it means we woke up because of a timeout. Otherwise, - // we woke up because of `notify_*`. - let success = self.waiters.with_locked(|waiters| unsafe { !waiters.remove(waiter) }); - - mutex.lock(); - success - } -} - -mod waiter_queue { - use super::*; - - pub struct WaiterQueue { - head: Option, - } - - #[derive(Copy, Clone)] - struct ListHead { - first: NonNull, - last: NonNull, - } - - unsafe impl Send for ListHead {} - unsafe impl Sync for ListHead {} - - pub struct Waiter { - // These fields are only accessed through `&[mut] WaiterQueue`. - /// The waiting task's ID. Will be zeroed when the task is woken up - /// and removed from a queue. - task: abi::ID, - priority: abi::PRI, - prev: Option>, - next: Option>, - } - - unsafe impl Send for Waiter {} - unsafe impl Sync for Waiter {} - - impl Waiter { - #[inline] - pub fn new() -> Self { - let task = task::current_task_id(); - let priority = task::task_priority(abi::TSK_SELF); - - // Zeroness of `Waiter::task` indicates whether the `Waiter` is - // linked to a queue or not. This invariant is important for - // the correctness. - debug_assert_ne!(task, 0); - - Self { task, priority, prev: None, next: None } - } - } - - impl WaiterQueue { - #[inline] - pub const fn new() -> Self { - Self { head: None } - } - - /// # Safety - /// - /// - The caller must own `*waiter_ptr`. The caller will lose the - /// ownership until `*waiter_ptr` is removed from `self`. - /// - /// - `*waiter_ptr` must be valid until it's removed from the queue. - /// - /// - `*waiter_ptr` must not have been previously inserted to a `WaiterQueue`. - /// - pub unsafe fn insert(&mut self, mut waiter_ptr: NonNull) { - unsafe { - let waiter = waiter_ptr.as_mut(); - - debug_assert!(waiter.prev.is_none()); - debug_assert!(waiter.next.is_none()); - - if let Some(head) = &mut self.head { - // Find the insertion position and insert `waiter` - let insert_after = { - let mut cursor = head.last; - loop { - if waiter.priority >= cursor.as_ref().priority { - // `cursor` and all previous waiters have the same or higher - // priority than `current_task_priority`. Insert the new - // waiter right after `cursor`. - break Some(cursor); - } - cursor = if let Some(prev) = cursor.as_ref().prev { - prev - } else { - break None; - }; - } - }; - - if let Some(mut insert_after) = insert_after { - // Insert `waiter` after `insert_after` - let insert_before = insert_after.as_ref().next; - - waiter.prev = Some(insert_after); - insert_after.as_mut().next = Some(waiter_ptr); - - waiter.next = insert_before; - if let Some(mut insert_before) = insert_before { - insert_before.as_mut().prev = Some(waiter_ptr); - } else { - head.last = waiter_ptr; - } - } else { - // Insert `waiter` to the front - waiter.next = Some(head.first); - head.first.as_mut().prev = Some(waiter_ptr); - head.first = waiter_ptr; - } - } else { - // `waiter` is the only element - self.head = Some(ListHead { first: waiter_ptr, last: waiter_ptr }); - } - } - } - - /// Given a `Waiter` that was previously inserted to `self`, remove - /// it from `self` if it's still there. - #[inline] - pub unsafe fn remove(&mut self, mut waiter_ptr: NonNull) -> bool { - unsafe { - let waiter = waiter_ptr.as_mut(); - if waiter.task != 0 { - let head = self.head.as_mut().unwrap(); - - match (waiter.prev, waiter.next) { - (Some(mut prev), Some(mut next)) => { - prev.as_mut().next = Some(next); - next.as_mut().prev = Some(prev); - } - (None, Some(mut next)) => { - head.first = next; - next.as_mut().prev = None; - } - (Some(mut prev), None) => { - prev.as_mut().next = None; - head.last = prev; - } - (None, None) => { - self.head = None; - } - } - - waiter.task = 0; - - true - } else { - false - } - } - } - - /// Given a `Waiter` that was previously inserted to `self`, return a - /// flag indicating whether it's still in `self`. - #[inline] - pub unsafe fn is_queued(&self, waiter: NonNull) -> bool { - unsafe { waiter.as_ref().task != 0 } - } - - #[inline] - pub fn pop_front(&mut self) -> Option { - unsafe { - let head = self.head.as_mut()?; - let waiter = head.first.as_mut(); - - // Get the ID - let id = replace(&mut waiter.task, 0); - - // Unlink the waiter - if let Some(mut next) = waiter.next { - head.first = next; - next.as_mut().prev = None; - } else { - self.head = None; - } - - Some(id) - } - } - } -} diff --git a/library/std/src/sys/sync/condvar/mod.rs b/library/std/src/sys/sync/condvar/mod.rs deleted file mode 100644 index 6849cacf88e76..0000000000000 --- a/library/std/src/sys/sync/condvar/mod.rs +++ /dev/null @@ -1,37 +0,0 @@ -cfg_if::cfg_if! { - if #[cfg(any( - all(target_os = "windows", not(target_vendor="win7")), - target_os = "linux", - target_os = "android", - target_os = "freebsd", - target_os = "openbsd", - target_os = "dragonfly", - target_os = "fuchsia", - all(target_family = "wasm", target_feature = "atomics"), - target_os = "hermit", - ))] { - mod futex; - pub use futex::Condvar; - } else if #[cfg(target_family = "unix")] { - mod pthread; - pub use pthread::Condvar; - } else if #[cfg(all(target_os = "windows", target_vendor = "win7"))] { - mod windows7; - pub use windows7::Condvar; - } else if #[cfg(all(target_vendor = "fortanix", target_env = "sgx"))] { - mod sgx; - pub use sgx::Condvar; - } else if #[cfg(target_os = "solid_asp3")] { - mod itron; - pub use itron::Condvar; - } else if #[cfg(target_os = "teeos")] { - mod teeos; - pub use teeos::Condvar; - } else if #[cfg(target_os = "xous")] { - mod xous; - pub use xous::Condvar; - } else { - mod no_threads; - pub use no_threads::Condvar; - } -} diff --git a/library/std/src/sys/sync/condvar/no_threads.rs b/library/std/src/sys/sync/condvar/no_threads.rs deleted file mode 100644 index 36b89c5f5bef7..0000000000000 --- a/library/std/src/sys/sync/condvar/no_threads.rs +++ /dev/null @@ -1,26 +0,0 @@ -use crate::sys::sync::Mutex; -use crate::time::Duration; - -pub struct Condvar {} - -impl Condvar { - #[inline] - #[rustc_const_stable(feature = "const_locks", since = "1.63.0")] - pub const fn new() -> Condvar { - Condvar {} - } - - #[inline] - pub fn notify_one(&self) {} - - #[inline] - pub fn notify_all(&self) {} - - pub unsafe fn wait(&self, _mutex: &Mutex) { - panic!("condvar wait not supported") - } - - pub unsafe fn wait_timeout(&self, _mutex: &Mutex, _dur: Duration) -> bool { - panic!("condvar wait not supported"); - } -} diff --git a/library/std/src/sys/sync/condvar/pthread.rs b/library/std/src/sys/sync/condvar/pthread.rs deleted file mode 100644 index a2a96410d932c..0000000000000 --- a/library/std/src/sys/sync/condvar/pthread.rs +++ /dev/null @@ -1,197 +0,0 @@ -use crate::cell::UnsafeCell; -use crate::ptr; -use crate::sync::atomic::{AtomicPtr, Ordering::Relaxed}; -use crate::sys::sync::{mutex, Mutex}; -#[cfg(not(target_os = "nto"))] -use crate::sys::time::TIMESPEC_MAX; -#[cfg(target_os = "nto")] -use crate::sys::time::TIMESPEC_MAX_CAPPED; -use crate::sys_common::lazy_box::{LazyBox, LazyInit}; -use crate::time::Duration; - -struct AllocatedCondvar(UnsafeCell); - -pub struct Condvar { - inner: LazyBox, - mutex: AtomicPtr, -} - -#[inline] -fn raw(c: &Condvar) -> *mut libc::pthread_cond_t { - c.inner.0.get() -} - -unsafe impl Send for AllocatedCondvar {} -unsafe impl Sync for AllocatedCondvar {} - -impl LazyInit for AllocatedCondvar { - fn init() -> Box { - let condvar = Box::new(AllocatedCondvar(UnsafeCell::new(libc::PTHREAD_COND_INITIALIZER))); - - cfg_if::cfg_if! { - if #[cfg(any( - target_os = "l4re", - target_os = "android", - target_os = "redox", - target_vendor = "apple", - ))] { - // `pthread_condattr_setclock` is unfortunately not supported on these platforms. - } else if #[cfg(any(target_os = "espidf", target_os = "horizon"))] { - // NOTE: ESP-IDF's PTHREAD_COND_INITIALIZER support is not released yet - // So on that platform, init() should always be called - // Moreover, that platform does not have pthread_condattr_setclock support, - // hence that initialization should be skipped as well - // - // Similar story for the 3DS (horizon). - let r = unsafe { libc::pthread_cond_init(condvar.0.get(), crate::ptr::null()) }; - assert_eq!(r, 0); - } else { - use crate::mem::MaybeUninit; - let mut attr = MaybeUninit::::uninit(); - let r = unsafe { libc::pthread_condattr_init(attr.as_mut_ptr()) }; - assert_eq!(r, 0); - let r = unsafe { libc::pthread_condattr_setclock(attr.as_mut_ptr(), libc::CLOCK_MONOTONIC) }; - assert_eq!(r, 0); - let r = unsafe { libc::pthread_cond_init(condvar.0.get(), attr.as_ptr()) }; - assert_eq!(r, 0); - let r = unsafe { libc::pthread_condattr_destroy(attr.as_mut_ptr()) }; - assert_eq!(r, 0); - } - } - - condvar - } -} - -impl Drop for AllocatedCondvar { - #[inline] - fn drop(&mut self) { - let r = unsafe { libc::pthread_cond_destroy(self.0.get()) }; - if cfg!(target_os = "dragonfly") { - // On DragonFly pthread_cond_destroy() returns EINVAL if called on - // a condvar that was just initialized with - // libc::PTHREAD_COND_INITIALIZER. Once it is used or - // pthread_cond_init() is called, this behaviour no longer occurs. - debug_assert!(r == 0 || r == libc::EINVAL); - } else { - debug_assert_eq!(r, 0); - } - } -} - -impl Condvar { - pub const fn new() -> Condvar { - Condvar { inner: LazyBox::new(), mutex: AtomicPtr::new(ptr::null_mut()) } - } - - #[inline] - fn verify(&self, mutex: *mut libc::pthread_mutex_t) { - // Relaxed is okay here because we never read through `self.addr`, and only use it to - // compare addresses. - match self.mutex.compare_exchange(ptr::null_mut(), mutex, Relaxed, Relaxed) { - Ok(_) => {} // Stored the address - Err(n) if n == mutex => {} // Lost a race to store the same address - _ => panic!("attempted to use a condition variable with two mutexes"), - } - } - - #[inline] - pub fn notify_one(&self) { - let r = unsafe { libc::pthread_cond_signal(raw(self)) }; - debug_assert_eq!(r, 0); - } - - #[inline] - pub fn notify_all(&self) { - let r = unsafe { libc::pthread_cond_broadcast(raw(self)) }; - debug_assert_eq!(r, 0); - } - - #[inline] - pub unsafe fn wait(&self, mutex: &Mutex) { - let mutex = mutex::raw(mutex); - self.verify(mutex); - let r = libc::pthread_cond_wait(raw(self), mutex); - debug_assert_eq!(r, 0); - } - - // This implementation is used on systems that support pthread_condattr_setclock - // where we configure condition variable to use monotonic clock (instead of - // default system clock). This approach avoids all problems that result - // from changes made to the system time. - #[cfg(not(any( - target_os = "android", - target_os = "espidf", - target_os = "horizon", - target_vendor = "apple", - )))] - pub unsafe fn wait_timeout(&self, mutex: &Mutex, dur: Duration) -> bool { - use crate::sys::time::Timespec; - - let mutex = mutex::raw(mutex); - self.verify(mutex); - - #[cfg(not(target_os = "nto"))] - let timeout = Timespec::now(libc::CLOCK_MONOTONIC) - .checked_add_duration(&dur) - .and_then(|t| t.to_timespec()) - .unwrap_or(TIMESPEC_MAX); - - #[cfg(target_os = "nto")] - let timeout = Timespec::now(libc::CLOCK_MONOTONIC) - .checked_add_duration(&dur) - .and_then(|t| t.to_timespec_capped()) - .unwrap_or(TIMESPEC_MAX_CAPPED); - - let r = libc::pthread_cond_timedwait(raw(self), mutex, &timeout); - assert!(r == libc::ETIMEDOUT || r == 0); - r == 0 - } - - // This implementation is modeled after libcxx's condition_variable - // https://github.com/llvm-mirror/libcxx/blob/release_35/src/condition_variable.cpp#L46 - // https://github.com/llvm-mirror/libcxx/blob/release_35/include/__mutex_base#L367 - #[cfg(any( - target_os = "android", - target_os = "espidf", - target_os = "horizon", - target_vendor = "apple", - ))] - pub unsafe fn wait_timeout(&self, mutex: &Mutex, dur: Duration) -> bool { - use crate::sys::time::SystemTime; - use crate::time::Instant; - - let mutex = mutex::raw(mutex); - self.verify(mutex); - - // OSX implementation of `pthread_cond_timedwait` is buggy - // with super long durations. When duration is greater than - // 0x100_0000_0000_0000 seconds, `pthread_cond_timedwait` - // in macOS Sierra returns error 316. - // - // This program demonstrates the issue: - // https://gist.github.com/stepancheg/198db4623a20aad2ad7cddb8fda4a63c - // - // To work around this issue, and possible bugs of other OSes, timeout - // is clamped to 1000 years, which is allowable per the API of `wait_timeout` - // because of spurious wakeups. - let dur = Duration::min(dur, Duration::from_secs(1000 * 365 * 86400)); - - // pthread_cond_timedwait uses system time, but we want to report timeout - // based on stable time. - let now = Instant::now(); - - let timeout = SystemTime::now() - .t - .checked_add_duration(&dur) - .and_then(|t| t.to_timespec()) - .unwrap_or(TIMESPEC_MAX); - - let r = libc::pthread_cond_timedwait(raw(self), mutex, &timeout); - debug_assert!(r == libc::ETIMEDOUT || r == 0); - - // ETIMEDOUT is not a totally reliable method of determining timeout due - // to clock shifts, so do the check ourselves - now.elapsed() < dur - } -} diff --git a/library/std/src/sys/sync/condvar/sgx.rs b/library/std/src/sys/sync/condvar/sgx.rs deleted file mode 100644 index ecb5872f60d90..0000000000000 --- a/library/std/src/sys/sync/condvar/sgx.rs +++ /dev/null @@ -1,45 +0,0 @@ -use crate::sys::pal::waitqueue::{SpinMutex, WaitQueue, WaitVariable}; -use crate::sys::sync::Mutex; -use crate::sys_common::lazy_box::{LazyBox, LazyInit}; -use crate::time::Duration; - -/// FIXME: `UnsafeList` is not movable. -struct AllocatedCondvar(SpinMutex>); - -pub struct Condvar { - inner: LazyBox, -} - -impl LazyInit for AllocatedCondvar { - fn init() -> Box { - Box::new(AllocatedCondvar(SpinMutex::new(WaitVariable::new(())))) - } -} - -impl Condvar { - pub const fn new() -> Condvar { - Condvar { inner: LazyBox::new() } - } - - #[inline] - pub fn notify_one(&self) { - let _ = WaitQueue::notify_one(self.inner.0.lock()); - } - - #[inline] - pub fn notify_all(&self) { - let _ = WaitQueue::notify_all(self.inner.0.lock()); - } - - pub unsafe fn wait(&self, mutex: &Mutex) { - let guard = self.inner.0.lock(); - WaitQueue::wait(guard, || unsafe { mutex.unlock() }); - mutex.lock() - } - - pub unsafe fn wait_timeout(&self, mutex: &Mutex, dur: Duration) -> bool { - let success = WaitQueue::wait_timeout(&self.inner.0, dur, || unsafe { mutex.unlock() }); - mutex.lock(); - success - } -} diff --git a/library/std/src/sys/sync/condvar/teeos.rs b/library/std/src/sys/sync/condvar/teeos.rs deleted file mode 100644 index 0a931f407d2fa..0000000000000 --- a/library/std/src/sys/sync/condvar/teeos.rs +++ /dev/null @@ -1,100 +0,0 @@ -use crate::cell::UnsafeCell; -use crate::ptr; -use crate::sync::atomic::{AtomicPtr, Ordering::Relaxed}; -use crate::sys::sync::mutex::{self, Mutex}; -use crate::sys::time::TIMESPEC_MAX; -use crate::sys_common::lazy_box::{LazyBox, LazyInit}; -use crate::time::Duration; - -extern "C" { - pub fn pthread_cond_timedwait( - cond: *mut libc::pthread_cond_t, - lock: *mut libc::pthread_mutex_t, - adstime: *const libc::timespec, - ) -> libc::c_int; -} - -struct AllocatedCondvar(UnsafeCell); - -pub struct Condvar { - inner: LazyBox, - mutex: AtomicPtr, -} - -#[inline] -fn raw(c: &Condvar) -> *mut libc::pthread_cond_t { - c.inner.0.get() -} - -unsafe impl Send for AllocatedCondvar {} -unsafe impl Sync for AllocatedCondvar {} - -impl LazyInit for AllocatedCondvar { - fn init() -> Box { - let condvar = Box::new(AllocatedCondvar(UnsafeCell::new(libc::PTHREAD_COND_INITIALIZER))); - - let r = unsafe { libc::pthread_cond_init(condvar.0.get(), crate::ptr::null()) }; - assert_eq!(r, 0); - - condvar - } -} - -impl Drop for AllocatedCondvar { - #[inline] - fn drop(&mut self) { - let r = unsafe { libc::pthread_cond_destroy(self.0.get()) }; - debug_assert_eq!(r, 0); - } -} - -impl Condvar { - pub const fn new() -> Condvar { - Condvar { inner: LazyBox::new(), mutex: AtomicPtr::new(ptr::null_mut()) } - } - - #[inline] - fn verify(&self, mutex: *mut libc::pthread_mutex_t) { - match self.mutex.compare_exchange(ptr::null_mut(), mutex, Relaxed, Relaxed) { - Ok(_) => {} // Stored the address - Err(n) if n == mutex => {} // Lost a race to store the same address - _ => panic!("attempted to use a condition variable with two mutexes"), - } - } - - #[inline] - pub fn notify_one(&self) { - let r = unsafe { libc::pthread_cond_signal(raw(self)) }; - debug_assert_eq!(r, 0); - } - - #[inline] - pub fn notify_all(&self) { - let r = unsafe { libc::pthread_cond_broadcast(raw(self)) }; - debug_assert_eq!(r, 0); - } - - #[inline] - pub unsafe fn wait(&self, mutex: &Mutex) { - let mutex = mutex::raw(mutex); - self.verify(mutex); - let r = libc::pthread_cond_wait(raw(self), mutex); - debug_assert_eq!(r, 0); - } - - pub unsafe fn wait_timeout(&self, mutex: &Mutex, dur: Duration) -> bool { - use crate::sys::time::Timespec; - - let mutex = mutex::raw(mutex); - self.verify(mutex); - - let timeout = Timespec::now(libc::CLOCK_MONOTONIC) - .checked_add_duration(&dur) - .and_then(|t| t.to_timespec()) - .unwrap_or(TIMESPEC_MAX); - - let r = pthread_cond_timedwait(raw(self), mutex, &timeout); - assert!(r == libc::ETIMEDOUT || r == 0); - r == 0 - } -} diff --git a/library/std/src/sys/sync/condvar/windows7.rs b/library/std/src/sys/sync/condvar/windows7.rs deleted file mode 100644 index 07fa5fdd698ee..0000000000000 --- a/library/std/src/sys/sync/condvar/windows7.rs +++ /dev/null @@ -1,50 +0,0 @@ -use crate::cell::UnsafeCell; -use crate::sys::c; -use crate::sys::os; -use crate::sys::sync::{mutex, Mutex}; -use crate::time::Duration; - -pub struct Condvar { - inner: UnsafeCell, -} - -unsafe impl Send for Condvar {} -unsafe impl Sync for Condvar {} - -impl Condvar { - #[inline] - pub const fn new() -> Condvar { - Condvar { inner: UnsafeCell::new(c::CONDITION_VARIABLE_INIT) } - } - - #[inline] - pub unsafe fn wait(&self, mutex: &Mutex) { - let r = c::SleepConditionVariableSRW(self.inner.get(), mutex::raw(mutex), c::INFINITE, 0); - debug_assert!(r != 0); - } - - pub unsafe fn wait_timeout(&self, mutex: &Mutex, dur: Duration) -> bool { - let r = c::SleepConditionVariableSRW( - self.inner.get(), - mutex::raw(mutex), - crate::sys::pal::dur2timeout(dur), - 0, - ); - if r == 0 { - debug_assert_eq!(os::errno() as usize, c::ERROR_TIMEOUT as usize); - false - } else { - true - } - } - - #[inline] - pub fn notify_one(&self) { - unsafe { c::WakeConditionVariable(self.inner.get()) } - } - - #[inline] - pub fn notify_all(&self) { - unsafe { c::WakeAllConditionVariable(self.inner.get()) } - } -} diff --git a/library/std/src/sys/sync/condvar/xous.rs b/library/std/src/sys/sync/condvar/xous.rs deleted file mode 100644 index 7b218818ef8ef..0000000000000 --- a/library/std/src/sys/sync/condvar/xous.rs +++ /dev/null @@ -1,148 +0,0 @@ -use crate::os::xous::ffi::{blocking_scalar, scalar}; -use crate::os::xous::services::{ticktimer_server, TicktimerScalar}; -use crate::sys::sync::Mutex; -use crate::time::Duration; -use core::sync::atomic::{AtomicUsize, Ordering}; - -// The implementation is inspired by Andrew D. Birrell's paper -// "Implementing Condition Variables with Semaphores" - -const NOTIFY_TRIES: usize = 3; - -pub struct Condvar { - counter: AtomicUsize, - timed_out: AtomicUsize, -} - -unsafe impl Send for Condvar {} -unsafe impl Sync for Condvar {} - -impl Condvar { - #[inline] - #[rustc_const_stable(feature = "const_locks", since = "1.63.0")] - pub const fn new() -> Condvar { - Condvar { counter: AtomicUsize::new(0), timed_out: AtomicUsize::new(0) } - } - - fn notify_some(&self, to_notify: usize) { - // Assumption: The Mutex protecting this condvar is locked throughout the - // entirety of this call, preventing calls to `wait` and `wait_timeout`. - - // Logic check: Ensure that there aren't any missing waiters. Remove any that - // timed-out, ensuring the counter doesn't underflow. - assert!(self.timed_out.load(Ordering::Relaxed) <= self.counter.load(Ordering::Relaxed)); - self.counter.fetch_sub(self.timed_out.swap(0, Ordering::Relaxed), Ordering::Relaxed); - - // Figure out how many threads to notify. Note that it is impossible for `counter` - // to increase during this operation because Mutex is locked. However, it is - // possible for `counter` to decrease due to a condvar timing out, in which - // case the corresponding `timed_out` will increase accordingly. - let Ok(waiter_count) = - self.counter.fetch_update(Ordering::Relaxed, Ordering::Relaxed, |counter| { - if counter == 0 { - return None; - } else { - Some(counter - counter.min(to_notify)) - } - }) - else { - // No threads are waiting on this condvar - return; - }; - - let mut remaining_to_wake = waiter_count.min(to_notify); - if remaining_to_wake == 0 { - return; - } - for _wake_tries in 0..NOTIFY_TRIES { - let result = blocking_scalar( - ticktimer_server(), - TicktimerScalar::NotifyCondition(self.index(), remaining_to_wake).into(), - ) - .expect("failure to send NotifyCondition command"); - - // Remove the list of waiters that were notified - remaining_to_wake -= result[0]; - - // Also remove the number of waiters that timed out. Clamp it to 0 in order to - // ensure we don't wait forever in case the waiter woke up between the time - // we counted the remaining waiters and now. - remaining_to_wake = - remaining_to_wake.saturating_sub(self.timed_out.swap(0, Ordering::Relaxed)); - if remaining_to_wake == 0 { - return; - } - crate::thread::yield_now(); - } - } - - pub fn notify_one(&self) { - self.notify_some(1) - } - - pub fn notify_all(&self) { - self.notify_some(self.counter.load(Ordering::Relaxed)) - } - - fn index(&self) -> usize { - core::ptr::from_ref(self).addr() - } - - /// Unlock the given Mutex and wait for the notification. Wait at most - /// `ms` milliseconds, or pass `0` to wait forever. - /// - /// Returns `true` if the condition was received, `false` if it timed out - fn wait_ms(&self, mutex: &Mutex, ms: usize) -> bool { - self.counter.fetch_add(1, Ordering::Relaxed); - unsafe { mutex.unlock() }; - - // Threading concern: There is a chance that the `notify` thread wakes up here before - // we have a chance to wait for the condition. This is fine because we've recorded - // the fact that we're waiting by incrementing the counter. - let result = blocking_scalar( - ticktimer_server(), - TicktimerScalar::WaitForCondition(self.index(), ms).into(), - ); - let awoken = result.expect("Ticktimer: failure to send WaitForCondition command")[0] == 0; - - // If we awoke due to a timeout, increment the `timed_out` counter so that the - // main loop of `notify` knows there's a timeout. - // - // This is done with the Mutex still unlocked, because the Mutex might still - // be locked by the `notify` process above. - if !awoken { - self.timed_out.fetch_add(1, Ordering::Relaxed); - } - - unsafe { mutex.lock() }; - awoken - } - - pub unsafe fn wait(&self, mutex: &Mutex) { - // Wait for 0 ms, which is a special case to "wait forever" - self.wait_ms(mutex, 0); - } - - pub unsafe fn wait_timeout(&self, mutex: &Mutex, dur: Duration) -> bool { - let mut millis = dur.as_millis() as usize; - // Ensure we don't wait for 0 ms, which would cause us to wait forever - if millis == 0 { - millis = 1; - } - self.wait_ms(mutex, millis) - } -} - -impl Drop for Condvar { - fn drop(&mut self) { - let remaining_count = self.counter.load(Ordering::Relaxed); - let timed_out = self.timed_out.load(Ordering::Relaxed); - assert!( - remaining_count - timed_out == 0, - "counter was {} and timed_out was {} not 0", - remaining_count, - timed_out - ); - scalar(ticktimer_server(), TicktimerScalar::FreeCondition(self.index()).into()).ok(); - } -} diff --git a/library/std/src/sys/sync/mod.rs b/library/std/src/sys/sync/mod.rs deleted file mode 100644 index 52fac5902a296..0000000000000 --- a/library/std/src/sys/sync/mod.rs +++ /dev/null @@ -1,11 +0,0 @@ -mod condvar; -mod mutex; -mod once; -mod rwlock; -mod thread_parking; - -pub use condvar::Condvar; -pub use mutex::Mutex; -pub use once::{Once, OnceState}; -pub use rwlock::RwLock; -pub use thread_parking::Parker; diff --git a/library/std/src/sys/sync/mutex/fuchsia.rs b/library/std/src/sys/sync/mutex/fuchsia.rs deleted file mode 100644 index 5d89e5a13fd36..0000000000000 --- a/library/std/src/sys/sync/mutex/fuchsia.rs +++ /dev/null @@ -1,164 +0,0 @@ -//! A priority inheriting mutex for Fuchsia. -//! -//! This is a port of the [mutex in Fuchsia's libsync]. Contrary to the original, -//! it does not abort the process when reentrant locking is detected, but deadlocks. -//! -//! Priority inheritance is achieved by storing the owning thread's handle in an -//! atomic variable. Fuchsia's futex operations support setting an owner thread -//! for a futex, which can boost that thread's priority while the futex is waited -//! upon. -//! -//! libsync is licenced under the following BSD-style licence: -//! -//! Copyright 2016 The Fuchsia Authors. -//! -//! Redistribution and use in source and binary forms, with or without -//! modification, are permitted provided that the following conditions are -//! met: -//! -//! * Redistributions of source code must retain the above copyright -//! notice, this list of conditions and the following disclaimer. -//! * Redistributions in binary form must reproduce the above -//! copyright notice, this list of conditions and the following -//! disclaimer in the documentation and/or other materials provided -//! with the distribution. -//! -//! THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS -//! "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT -//! LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR -//! A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT -//! OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, -//! SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT -//! LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, -//! DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY -//! THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT -//! (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE -//! OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -//! -//! [mutex in Fuchsia's libsync]: https://cs.opensource.google/fuchsia/fuchsia/+/main:zircon/system/ulib/sync/mutex.c - -use crate::sync::atomic::{ - AtomicU32, - Ordering::{Acquire, Relaxed, Release}, -}; -use crate::sys::futex::zircon::{ - zx_futex_wait, zx_futex_wake_single_owner, zx_handle_t, zx_thread_self, ZX_ERR_BAD_HANDLE, - ZX_ERR_BAD_STATE, ZX_ERR_INVALID_ARGS, ZX_ERR_TIMED_OUT, ZX_ERR_WRONG_TYPE, ZX_OK, - ZX_TIME_INFINITE, -}; - -// The lowest two bits of a `zx_handle_t` are always set, so the lowest bit is used to mark the -// mutex as contested by clearing it. -const CONTESTED_BIT: u32 = 1; -// This can never be a valid `zx_handle_t`. -const UNLOCKED: u32 = 0; - -pub struct Mutex { - futex: AtomicU32, -} - -#[inline] -fn to_state(owner: zx_handle_t) -> u32 { - owner -} - -#[inline] -fn to_owner(state: u32) -> zx_handle_t { - state | CONTESTED_BIT -} - -#[inline] -fn is_contested(state: u32) -> bool { - state & CONTESTED_BIT == 0 -} - -#[inline] -fn mark_contested(state: u32) -> u32 { - state & !CONTESTED_BIT -} - -impl Mutex { - #[inline] - pub const fn new() -> Mutex { - Mutex { futex: AtomicU32::new(UNLOCKED) } - } - - #[inline] - pub fn try_lock(&self) -> bool { - let thread_self = unsafe { zx_thread_self() }; - self.futex.compare_exchange(UNLOCKED, to_state(thread_self), Acquire, Relaxed).is_ok() - } - - #[inline] - pub fn lock(&self) { - let thread_self = unsafe { zx_thread_self() }; - if let Err(state) = - self.futex.compare_exchange(UNLOCKED, to_state(thread_self), Acquire, Relaxed) - { - unsafe { - self.lock_contested(state, thread_self); - } - } - } - - /// # Safety - /// `thread_self` must be the handle for the current thread. - #[cold] - unsafe fn lock_contested(&self, mut state: u32, thread_self: zx_handle_t) { - let owned_state = mark_contested(to_state(thread_self)); - loop { - // Mark the mutex as contested if it is not already. - let contested = mark_contested(state); - if is_contested(state) - || self.futex.compare_exchange(state, contested, Relaxed, Relaxed).is_ok() - { - // The mutex has been marked as contested, wait for the state to change. - unsafe { - match zx_futex_wait( - &self.futex, - AtomicU32::new(contested), - to_owner(state), - ZX_TIME_INFINITE, - ) { - ZX_OK | ZX_ERR_BAD_STATE | ZX_ERR_TIMED_OUT => (), - // Note that if a thread handle is reused after its associated thread - // exits without unlocking the mutex, an arbitrary thread's priority - // could be boosted by the wait, but there is currently no way to - // prevent that. - ZX_ERR_INVALID_ARGS | ZX_ERR_BAD_HANDLE | ZX_ERR_WRONG_TYPE => { - panic!( - "either the current thread is trying to lock a mutex it has - already locked, or the previous owner did not unlock the mutex - before exiting" - ) - } - error => panic!("unexpected error in zx_futex_wait: {error}"), - } - } - } - - // The state has changed or a wakeup occurred, try to lock the mutex. - match self.futex.compare_exchange(UNLOCKED, owned_state, Acquire, Relaxed) { - Ok(_) => return, - Err(updated) => state = updated, - } - } - } - - #[inline] - pub unsafe fn unlock(&self) { - if is_contested(self.futex.swap(UNLOCKED, Release)) { - // The woken thread will mark the mutex as contested again, - // and return here, waking until there are no waiters left, - // in which case this is a noop. - self.wake(); - } - } - - #[cold] - fn wake(&self) { - unsafe { - zx_futex_wake_single_owner(&self.futex); - } - } -} diff --git a/library/std/src/sys/sync/mutex/futex.rs b/library/std/src/sys/sync/mutex/futex.rs deleted file mode 100644 index 7427cae94d68a..0000000000000 --- a/library/std/src/sys/sync/mutex/futex.rs +++ /dev/null @@ -1,108 +0,0 @@ -use crate::sync::atomic::{ - self, - Ordering::{Acquire, Relaxed, Release}, -}; -use crate::sys::futex::{futex_wait, futex_wake}; - -cfg_if::cfg_if! { -if #[cfg(windows)] { - // On Windows we can have a smol futex - type Atomic = atomic::AtomicU8; - type State = u8; -} else { - type Atomic = atomic::AtomicU32; - type State = u32; -} -} - -pub struct Mutex { - futex: Atomic, -} - -const UNLOCKED: State = 0; -const LOCKED: State = 1; // locked, no other threads waiting -const CONTENDED: State = 2; // locked, and other threads waiting (contended) - -impl Mutex { - #[inline] - pub const fn new() -> Self { - Self { futex: Atomic::new(UNLOCKED) } - } - - #[inline] - pub fn try_lock(&self) -> bool { - self.futex.compare_exchange(UNLOCKED, LOCKED, Acquire, Relaxed).is_ok() - } - - #[inline] - pub fn lock(&self) { - if self.futex.compare_exchange(UNLOCKED, LOCKED, Acquire, Relaxed).is_err() { - self.lock_contended(); - } - } - - #[cold] - fn lock_contended(&self) { - // Spin first to speed things up if the lock is released quickly. - let mut state = self.spin(); - - // If it's unlocked now, attempt to take the lock - // without marking it as contended. - if state == UNLOCKED { - match self.futex.compare_exchange(UNLOCKED, LOCKED, Acquire, Relaxed) { - Ok(_) => return, // Locked! - Err(s) => state = s, - } - } - - loop { - // Put the lock in contended state. - // We avoid an unnecessary write if it as already set to CONTENDED, - // to be friendlier for the caches. - if state != CONTENDED && self.futex.swap(CONTENDED, Acquire) == UNLOCKED { - // We changed it from UNLOCKED to CONTENDED, so we just successfully locked it. - return; - } - - // Wait for the futex to change state, assuming it is still CONTENDED. - futex_wait(&self.futex, CONTENDED, None); - - // Spin again after waking up. - state = self.spin(); - } - } - - fn spin(&self) -> State { - let mut spin = 100; - loop { - // We only use `load` (and not `swap` or `compare_exchange`) - // while spinning, to be easier on the caches. - let state = self.futex.load(Relaxed); - - // We stop spinning when the mutex is UNLOCKED, - // but also when it's CONTENDED. - if state != LOCKED || spin == 0 { - return state; - } - - crate::hint::spin_loop(); - spin -= 1; - } - } - - #[inline] - pub unsafe fn unlock(&self) { - if self.futex.swap(UNLOCKED, Release) == CONTENDED { - // We only wake up one thread. When that thread locks the mutex, it - // will mark the mutex as CONTENDED (see lock_contended above), - // which makes sure that any other waiting threads will also be - // woken up eventually. - self.wake(); - } - } - - #[cold] - fn wake(&self) { - futex_wake(&self.futex); - } -} diff --git a/library/std/src/sys/sync/mutex/itron.rs b/library/std/src/sys/sync/mutex/itron.rs deleted file mode 100644 index a134eb2d1beca..0000000000000 --- a/library/std/src/sys/sync/mutex/itron.rs +++ /dev/null @@ -1,68 +0,0 @@ -//! Mutex implementation backed by μITRON mutexes. Assumes `acre_mtx` and -//! `TA_INHERIT` are available. -use crate::sys::pal::itron::{ - abi, - error::{expect_success, expect_success_aborting, fail, ItronError}, - spin::SpinIdOnceCell, -}; - -pub struct Mutex { - /// The ID of the underlying mutex object - mtx: SpinIdOnceCell<()>, -} - -/// Create a mutex object. This function never panics. -fn new_mtx() -> Result { - ItronError::err_if_negative(unsafe { - abi::acre_mtx(&abi::T_CMTX { - // Priority inheritance mutex - mtxatr: abi::TA_INHERIT, - // Unused - ceilpri: 0, - }) - }) -} - -impl Mutex { - #[inline] - pub const fn new() -> Mutex { - Mutex { mtx: SpinIdOnceCell::new() } - } - - /// Get the inner mutex's ID, which is lazily created. - fn raw(&self) -> abi::ID { - match self.mtx.get_or_try_init(|| new_mtx().map(|id| (id, ()))) { - Ok((id, ())) => id, - Err(e) => fail(e, &"acre_mtx"), - } - } - - pub fn lock(&self) { - let mtx = self.raw(); - expect_success(unsafe { abi::loc_mtx(mtx) }, &"loc_mtx"); - } - - pub unsafe fn unlock(&self) { - let mtx = unsafe { self.mtx.get_unchecked().0 }; - expect_success_aborting(unsafe { abi::unl_mtx(mtx) }, &"unl_mtx"); - } - - pub fn try_lock(&self) -> bool { - let mtx = self.raw(); - match unsafe { abi::ploc_mtx(mtx) } { - abi::E_TMOUT => false, - er => { - expect_success(er, &"ploc_mtx"); - true - } - } - } -} - -impl Drop for Mutex { - fn drop(&mut self) { - if let Some(mtx) = self.mtx.get().map(|x| x.0) { - expect_success_aborting(unsafe { abi::del_mtx(mtx) }, &"del_mtx"); - } - } -} diff --git a/library/std/src/sys/sync/mutex/mod.rs b/library/std/src/sys/sync/mutex/mod.rs deleted file mode 100644 index 73d9bd273de17..0000000000000 --- a/library/std/src/sys/sync/mutex/mod.rs +++ /dev/null @@ -1,39 +0,0 @@ -cfg_if::cfg_if! { - if #[cfg(any( - all(target_os = "windows", not(target_vendor = "win7")), - target_os = "linux", - target_os = "android", - target_os = "freebsd", - target_os = "openbsd", - target_os = "dragonfly", - all(target_family = "wasm", target_feature = "atomics"), - target_os = "hermit", - ))] { - mod futex; - pub use futex::Mutex; - } else if #[cfg(target_os = "fuchsia")] { - mod fuchsia; - pub use fuchsia::Mutex; - } else if #[cfg(any( - target_family = "unix", - target_os = "teeos", - ))] { - mod pthread; - pub use pthread::{Mutex, raw}; - } else if #[cfg(all(target_os = "windows", target_vendor = "win7"))] { - mod windows7; - pub use windows7::{Mutex, raw}; - } else if #[cfg(all(target_vendor = "fortanix", target_env = "sgx"))] { - mod sgx; - pub use sgx::Mutex; - } else if #[cfg(target_os = "solid_asp3")] { - mod itron; - pub use itron::Mutex; - } else if #[cfg(target_os = "xous")] { - mod xous; - pub use xous::Mutex; - } else { - mod no_threads; - pub use no_threads::Mutex; - } -} diff --git a/library/std/src/sys/sync/mutex/no_threads.rs b/library/std/src/sys/sync/mutex/no_threads.rs deleted file mode 100644 index 4a13c55fb8bec..0000000000000 --- a/library/std/src/sys/sync/mutex/no_threads.rs +++ /dev/null @@ -1,32 +0,0 @@ -use crate::cell::Cell; - -pub struct Mutex { - // This platform has no threads, so we can use a Cell here. - locked: Cell, -} - -unsafe impl Send for Mutex {} -unsafe impl Sync for Mutex {} // no threads on this platform - -impl Mutex { - #[inline] - #[rustc_const_stable(feature = "const_locks", since = "1.63.0")] - pub const fn new() -> Mutex { - Mutex { locked: Cell::new(false) } - } - - #[inline] - pub fn lock(&self) { - assert_eq!(self.locked.replace(true), false, "cannot recursively acquire mutex"); - } - - #[inline] - pub unsafe fn unlock(&self) { - self.locked.set(false); - } - - #[inline] - pub fn try_lock(&self) -> bool { - self.locked.replace(true) == false - } -} diff --git a/library/std/src/sys/sync/mutex/pthread.rs b/library/std/src/sys/sync/mutex/pthread.rs deleted file mode 100644 index ee0794334fbe3..0000000000000 --- a/library/std/src/sys/sync/mutex/pthread.rs +++ /dev/null @@ -1,148 +0,0 @@ -use crate::cell::UnsafeCell; -use crate::io::Error; -use crate::mem::{forget, MaybeUninit}; -use crate::sys::cvt_nz; -use crate::sys_common::lazy_box::{LazyBox, LazyInit}; - -struct AllocatedMutex(UnsafeCell); - -pub struct Mutex { - inner: LazyBox, -} - -#[inline] -pub unsafe fn raw(m: &Mutex) -> *mut libc::pthread_mutex_t { - m.inner.0.get() -} - -unsafe impl Send for AllocatedMutex {} -unsafe impl Sync for AllocatedMutex {} - -impl LazyInit for AllocatedMutex { - fn init() -> Box { - let mutex = Box::new(AllocatedMutex(UnsafeCell::new(libc::PTHREAD_MUTEX_INITIALIZER))); - - // Issue #33770 - // - // A pthread mutex initialized with PTHREAD_MUTEX_INITIALIZER will have - // a type of PTHREAD_MUTEX_DEFAULT, which has undefined behavior if you - // try to re-lock it from the same thread when you already hold a lock - // (https://pubs.opengroup.org/onlinepubs/9699919799/functions/pthread_mutex_init.html). - // This is the case even if PTHREAD_MUTEX_DEFAULT == PTHREAD_MUTEX_NORMAL - // (https://github.com/rust-lang/rust/issues/33770#issuecomment-220847521) -- in that - // case, `pthread_mutexattr_settype(PTHREAD_MUTEX_DEFAULT)` will of course be the same - // as setting it to `PTHREAD_MUTEX_NORMAL`, but not setting any mode will result in - // a Mutex where re-locking is UB. - // - // In practice, glibc takes advantage of this undefined behavior to - // implement hardware lock elision, which uses hardware transactional - // memory to avoid acquiring the lock. While a transaction is in - // progress, the lock appears to be unlocked. This isn't a problem for - // other threads since the transactional memory will abort if a conflict - // is detected, however no abort is generated when re-locking from the - // same thread. - // - // Since locking the same mutex twice will result in two aliasing &mut - // references, we instead create the mutex with type - // PTHREAD_MUTEX_NORMAL which is guaranteed to deadlock if we try to - // re-lock it from the same thread, thus avoiding undefined behavior. - unsafe { - let mut attr = MaybeUninit::::uninit(); - cvt_nz(libc::pthread_mutexattr_init(attr.as_mut_ptr())).unwrap(); - let attr = PthreadMutexAttr(&mut attr); - cvt_nz(libc::pthread_mutexattr_settype( - attr.0.as_mut_ptr(), - libc::PTHREAD_MUTEX_NORMAL, - )) - .unwrap(); - cvt_nz(libc::pthread_mutex_init(mutex.0.get(), attr.0.as_ptr())).unwrap(); - } - - mutex - } - - fn destroy(mutex: Box) { - // We're not allowed to pthread_mutex_destroy a locked mutex, - // so check first if it's unlocked. - if unsafe { libc::pthread_mutex_trylock(mutex.0.get()) == 0 } { - unsafe { libc::pthread_mutex_unlock(mutex.0.get()) }; - drop(mutex); - } else { - // The mutex is locked. This happens if a MutexGuard is leaked. - // In this case, we just leak the Mutex too. - forget(mutex); - } - } - - fn cancel_init(_: Box) { - // In this case, we can just drop it without any checks, - // since it cannot have been locked yet. - } -} - -impl Drop for AllocatedMutex { - #[inline] - fn drop(&mut self) { - let r = unsafe { libc::pthread_mutex_destroy(self.0.get()) }; - if cfg!(target_os = "dragonfly") { - // On DragonFly pthread_mutex_destroy() returns EINVAL if called on a - // mutex that was just initialized with libc::PTHREAD_MUTEX_INITIALIZER. - // Once it is used (locked/unlocked) or pthread_mutex_init() is called, - // this behaviour no longer occurs. - debug_assert!(r == 0 || r == libc::EINVAL); - } else { - debug_assert_eq!(r, 0); - } - } -} - -impl Mutex { - #[inline] - pub const fn new() -> Mutex { - Mutex { inner: LazyBox::new() } - } - - #[inline] - pub unsafe fn lock(&self) { - #[cold] - #[inline(never)] - fn fail(r: i32) -> ! { - let error = Error::from_raw_os_error(r); - panic!("failed to lock mutex: {error}"); - } - - let r = libc::pthread_mutex_lock(raw(self)); - // As we set the mutex type to `PTHREAD_MUTEX_NORMAL` above, we expect - // the lock call to never fail. Unfortunately however, some platforms - // (Solaris) do not conform to the standard, and instead always provide - // deadlock detection. How kind of them! Unfortunately that means that - // we need to check the error code here. To save us from UB on other - // less well-behaved platforms in the future, we do it even on "good" - // platforms like macOS. See #120147 for more context. - if r != 0 { - fail(r) - } - } - - #[inline] - pub unsafe fn unlock(&self) { - let r = libc::pthread_mutex_unlock(raw(self)); - debug_assert_eq!(r, 0); - } - - #[inline] - pub unsafe fn try_lock(&self) -> bool { - libc::pthread_mutex_trylock(raw(self)) == 0 - } -} - -pub(super) struct PthreadMutexAttr<'a>(pub &'a mut MaybeUninit); - -impl Drop for PthreadMutexAttr<'_> { - fn drop(&mut self) { - unsafe { - let result = libc::pthread_mutexattr_destroy(self.0.as_mut_ptr()); - debug_assert_eq!(result, 0); - } - } -} diff --git a/library/std/src/sys/sync/mutex/sgx.rs b/library/std/src/sys/sync/mutex/sgx.rs deleted file mode 100644 index d37bd02adf8dd..0000000000000 --- a/library/std/src/sys/sync/mutex/sgx.rs +++ /dev/null @@ -1,59 +0,0 @@ -use crate::sys::pal::waitqueue::{try_lock_or_false, SpinMutex, WaitQueue, WaitVariable}; -use crate::sys_common::lazy_box::{LazyBox, LazyInit}; - -/// FIXME: `UnsafeList` is not movable. -struct AllocatedMutex(SpinMutex>); - -pub struct Mutex { - inner: LazyBox, -} - -impl LazyInit for AllocatedMutex { - fn init() -> Box { - Box::new(AllocatedMutex(SpinMutex::new(WaitVariable::new(false)))) - } -} - -// Implementation according to “Operating Systems: Three Easy Pieces”, chapter 28 -impl Mutex { - pub const fn new() -> Mutex { - Mutex { inner: LazyBox::new() } - } - - #[inline] - pub fn lock(&self) { - let mut guard = self.inner.0.lock(); - if *guard.lock_var() { - // Another thread has the lock, wait - WaitQueue::wait(guard, || {}) - // Another thread has passed the lock to us - } else { - // We are just now obtaining the lock - *guard.lock_var_mut() = true; - } - } - - #[inline] - pub unsafe fn unlock(&self) { - let guard = self.inner.0.lock(); - if let Err(mut guard) = WaitQueue::notify_one(guard) { - // No other waiters, unlock - *guard.lock_var_mut() = false; - } else { - // There was a thread waiting, just pass the lock - } - } - - #[inline] - pub fn try_lock(&self) -> bool { - let mut guard = try_lock_or_false!(self.inner.0); - if *guard.lock_var() { - // Another thread has the lock - false - } else { - // We are just now obtaining the lock - *guard.lock_var_mut() = true; - true - } - } -} diff --git a/library/std/src/sys/sync/mutex/windows7.rs b/library/std/src/sys/sync/mutex/windows7.rs deleted file mode 100644 index ef2f84082cd5c..0000000000000 --- a/library/std/src/sys/sync/mutex/windows7.rs +++ /dev/null @@ -1,54 +0,0 @@ -//! System Mutexes -//! -//! The Windows implementation of mutexes is a little odd and it might not be -//! immediately obvious what's going on. The primary oddness is that SRWLock is -//! used instead of CriticalSection, and this is done because: -//! -//! 1. SRWLock is several times faster than CriticalSection according to -//! benchmarks performed on both Windows 8 and Windows 7. -//! -//! 2. CriticalSection allows recursive locking while SRWLock deadlocks. The -//! Unix implementation deadlocks so consistency is preferred. See #19962 for -//! more details. -//! -//! 3. While CriticalSection is fair and SRWLock is not, the current Rust policy -//! is that there are no guarantees of fairness. - -use crate::cell::UnsafeCell; -use crate::sys::c; - -pub struct Mutex { - srwlock: UnsafeCell, -} - -unsafe impl Send for Mutex {} -unsafe impl Sync for Mutex {} - -#[inline] -pub unsafe fn raw(m: &Mutex) -> c::PSRWLOCK { - m.srwlock.get() -} - -impl Mutex { - #[inline] - pub const fn new() -> Mutex { - Mutex { srwlock: UnsafeCell::new(c::SRWLOCK_INIT) } - } - - #[inline] - pub fn lock(&self) { - unsafe { - c::AcquireSRWLockExclusive(raw(self)); - } - } - - #[inline] - pub fn try_lock(&self) -> bool { - unsafe { c::TryAcquireSRWLockExclusive(raw(self)) != 0 } - } - - #[inline] - pub unsafe fn unlock(&self) { - c::ReleaseSRWLockExclusive(raw(self)); - } -} diff --git a/library/std/src/sys/sync/mutex/xous.rs b/library/std/src/sys/sync/mutex/xous.rs deleted file mode 100644 index 1426e48f8b7af..0000000000000 --- a/library/std/src/sys/sync/mutex/xous.rs +++ /dev/null @@ -1,113 +0,0 @@ -use crate::os::xous::ffi::{blocking_scalar, do_yield}; -use crate::os::xous::services::{ticktimer_server, TicktimerScalar}; -use crate::sync::atomic::{ - AtomicBool, AtomicUsize, - Ordering::{Acquire, Relaxed, Release}, -}; - -pub struct Mutex { - /// The "locked" value indicates how many threads are waiting on this - /// Mutex. Possible values are: - /// 0: The lock is unlocked - /// 1: The lock is locked and uncontended - /// >=2: The lock is locked and contended - /// - /// A lock is "contended" when there is more than one thread waiting - /// for a lock, or it is locked for long periods of time. Rather than - /// spinning, these locks send a Message to the ticktimer server - /// requesting that they be woken up when a lock is unlocked. - locked: AtomicUsize, - - /// Whether this Mutex ever was contended, and therefore made a trip - /// to the ticktimer server. If this was never set, then we were never - /// on the slow path and can skip deregistering the mutex. - contended: AtomicBool, -} - -impl Mutex { - #[inline] - #[rustc_const_stable(feature = "const_locks", since = "1.63.0")] - pub const fn new() -> Mutex { - Mutex { locked: AtomicUsize::new(0), contended: AtomicBool::new(false) } - } - - fn index(&self) -> usize { - core::ptr::from_ref(self).addr() - } - - #[inline] - pub unsafe fn lock(&self) { - // Try multiple times to acquire the lock without resorting to the ticktimer - // server. For locks that are held for a short amount of time, this will - // result in the ticktimer server never getting invoked. The `locked` value - // will be either 0 or 1. - for _attempts in 0..3 { - if unsafe { self.try_lock() } { - return; - } - do_yield(); - } - - // Try one more time to lock. If the lock is released between the previous code and - // here, then the inner `locked` value will be 1 at the end of this. If it was not - // locked, then the value will be more than 1, for example if there are multiple other - // threads waiting on this lock. - if unsafe { self.try_lock_or_poison() } { - return; - } - - // When this mutex is dropped, we will need to deregister it with the server. - self.contended.store(true, Relaxed); - - // The lock is now "contended". When the lock is released, a Message will get sent to the - // ticktimer server to wake it up. Note that this may already have happened, so the actual - // value of `lock` may be anything (0, 1, 2, ...). - blocking_scalar( - ticktimer_server(), - crate::os::xous::services::TicktimerScalar::LockMutex(self.index()).into(), - ) - .expect("failure to send LockMutex command"); - } - - #[inline] - pub unsafe fn unlock(&self) { - let prev = self.locked.fetch_sub(1, Release); - - // If the previous value was 1, then this was a "fast path" unlock, so no - // need to involve the Ticktimer server - if prev == 1 { - return; - } - - // If it was 0, then something has gone seriously wrong and the counter - // has just wrapped around. - if prev == 0 { - panic!("mutex lock count underflowed"); - } - - // Unblock one thread that is waiting on this message. - blocking_scalar(ticktimer_server(), TicktimerScalar::UnlockMutex(self.index()).into()) - .expect("failure to send UnlockMutex command"); - } - - #[inline] - pub unsafe fn try_lock(&self) -> bool { - self.locked.compare_exchange(0, 1, Acquire, Relaxed).is_ok() - } - - #[inline] - pub unsafe fn try_lock_or_poison(&self) -> bool { - self.locked.fetch_add(1, Acquire) == 0 - } -} - -impl Drop for Mutex { - fn drop(&mut self) { - // If there was Mutex contention, then we involved the ticktimer. Free - // the resources associated with this Mutex as it is deallocated. - if self.contended.load(Relaxed) { - blocking_scalar(ticktimer_server(), TicktimerScalar::FreeMutex(self.index()).into()) - .ok(); - } - } -} diff --git a/library/std/src/sys/sync/once/futex.rs b/library/std/src/sys/sync/once/futex.rs deleted file mode 100644 index 609085dcd4712..0000000000000 --- a/library/std/src/sys/sync/once/futex.rs +++ /dev/null @@ -1,146 +0,0 @@ -use crate::cell::Cell; -use crate::sync as public; -use crate::sync::atomic::{ - AtomicU32, - Ordering::{Acquire, Relaxed, Release}, -}; -use crate::sync::once::ExclusiveState; -use crate::sys::futex::{futex_wait, futex_wake_all}; - -// On some platforms, the OS is very nice and handles the waiter queue for us. -// This means we only need one atomic value with 5 states: - -/// No initialization has run yet, and no thread is currently using the Once. -const INCOMPLETE: u32 = 0; -/// Some thread has previously attempted to initialize the Once, but it panicked, -/// so the Once is now poisoned. There are no other threads currently accessing -/// this Once. -const POISONED: u32 = 1; -/// Some thread is currently attempting to run initialization. It may succeed, -/// so all future threads need to wait for it to finish. -const RUNNING: u32 = 2; -/// Some thread is currently attempting to run initialization and there are threads -/// waiting for it to finish. -const QUEUED: u32 = 3; -/// Initialization has completed and all future calls should finish immediately. -const COMPLETE: u32 = 4; - -// Threads wait by setting the state to QUEUED and calling `futex_wait` on the state -// variable. When the running thread finishes, it will wake all waiting threads using -// `futex_wake_all`. - -pub struct OnceState { - poisoned: bool, - set_state_to: Cell, -} - -impl OnceState { - #[inline] - pub fn is_poisoned(&self) -> bool { - self.poisoned - } - - #[inline] - pub fn poison(&self) { - self.set_state_to.set(POISONED); - } -} - -struct CompletionGuard<'a> { - state: &'a AtomicU32, - set_state_on_drop_to: u32, -} - -impl<'a> Drop for CompletionGuard<'a> { - fn drop(&mut self) { - // Use release ordering to propagate changes to all threads checking - // up on the Once. `futex_wake_all` does its own synchronization, hence - // we do not need `AcqRel`. - if self.state.swap(self.set_state_on_drop_to, Release) == QUEUED { - futex_wake_all(&self.state); - } - } -} - -pub struct Once { - state: AtomicU32, -} - -impl Once { - #[inline] - pub const fn new() -> Once { - Once { state: AtomicU32::new(INCOMPLETE) } - } - - #[inline] - pub fn is_completed(&self) -> bool { - // Use acquire ordering to make all initialization changes visible to the - // current thread. - self.state.load(Acquire) == COMPLETE - } - - #[inline] - pub(crate) fn state(&mut self) -> ExclusiveState { - match *self.state.get_mut() { - INCOMPLETE => ExclusiveState::Incomplete, - POISONED => ExclusiveState::Poisoned, - COMPLETE => ExclusiveState::Complete, - _ => unreachable!("invalid Once state"), - } - } - - // This uses FnMut to match the API of the generic implementation. As this - // implementation is quite light-weight, it is generic over the closure and - // so avoids the cost of dynamic dispatch. - #[cold] - #[track_caller] - pub fn call(&self, ignore_poisoning: bool, f: &mut impl FnMut(&public::OnceState)) { - let mut state = self.state.load(Acquire); - loop { - match state { - POISONED if !ignore_poisoning => { - // Panic to propagate the poison. - panic!("Once instance has previously been poisoned"); - } - INCOMPLETE | POISONED => { - // Try to register the current thread as the one running. - if let Err(new) = - self.state.compare_exchange_weak(state, RUNNING, Acquire, Acquire) - { - state = new; - continue; - } - // `waiter_queue` will manage other waiting threads, and - // wake them up on drop. - let mut waiter_queue = - CompletionGuard { state: &self.state, set_state_on_drop_to: POISONED }; - // Run the function, letting it know if we're poisoned or not. - let f_state = public::OnceState { - inner: OnceState { - poisoned: state == POISONED, - set_state_to: Cell::new(COMPLETE), - }, - }; - f(&f_state); - waiter_queue.set_state_on_drop_to = f_state.inner.set_state_to.get(); - return; - } - RUNNING | QUEUED => { - // Set the state to QUEUED if it is not already. - if state == RUNNING - && let Err(new) = - self.state.compare_exchange_weak(RUNNING, QUEUED, Relaxed, Acquire) - { - state = new; - continue; - } - - futex_wait(&self.state, QUEUED, None); - state = self.state.load(Acquire); - } - COMPLETE => return, - _ => unreachable!("state is never set to invalid values"), - } - } - } -} diff --git a/library/std/src/sys/sync/once/mod.rs b/library/std/src/sys/sync/once/mod.rs deleted file mode 100644 index 61b29713fa1a9..0000000000000 --- a/library/std/src/sys/sync/once/mod.rs +++ /dev/null @@ -1,36 +0,0 @@ -// A "once" is a relatively simple primitive, and it's also typically provided -// by the OS as well (see `pthread_once` or `InitOnceExecuteOnce`). The OS -// primitives, however, tend to have surprising restrictions, such as the Unix -// one doesn't allow an argument to be passed to the function. -// -// As a result, we end up implementing it ourselves in the standard library. -// This also gives us the opportunity to optimize the implementation a bit which -// should help the fast path on call sites. - -cfg_if::cfg_if! { - if #[cfg(any( - target_os = "linux", - target_os = "android", - all(target_arch = "wasm32", target_feature = "atomics"), - target_os = "freebsd", - target_os = "openbsd", - target_os = "dragonfly", - target_os = "fuchsia", - target_os = "hermit", - ))] { - mod futex; - pub use futex::{Once, OnceState}; - } else if #[cfg(any( - windows, - target_family = "unix", - all(target_vendor = "fortanix", target_env = "sgx"), - target_os = "solid_asp3", - target_os = "xous", - ))] { - mod queue; - pub use queue::{Once, OnceState}; - } else { - mod no_threads; - pub use no_threads::{Once, OnceState}; - } -} diff --git a/library/std/src/sys/sync/once/no_threads.rs b/library/std/src/sys/sync/once/no_threads.rs deleted file mode 100644 index 11fde1888ba7c..0000000000000 --- a/library/std/src/sys/sync/once/no_threads.rs +++ /dev/null @@ -1,100 +0,0 @@ -use crate::cell::Cell; -use crate::sync as public; -use crate::sync::once::ExclusiveState; - -pub struct Once { - state: Cell, -} - -pub struct OnceState { - poisoned: bool, - set_state_to: Cell, -} - -#[derive(Clone, Copy, PartialEq, Eq)] -enum State { - Incomplete, - Poisoned, - Running, - Complete, -} - -struct CompletionGuard<'a> { - state: &'a Cell, - set_state_on_drop_to: State, -} - -impl<'a> Drop for CompletionGuard<'a> { - fn drop(&mut self) { - self.state.set(self.set_state_on_drop_to); - } -} - -// Safety: threads are not supported on this platform. -unsafe impl Sync for Once {} - -impl Once { - #[inline] - #[rustc_const_stable(feature = "const_once_new", since = "1.32.0")] - pub const fn new() -> Once { - Once { state: Cell::new(State::Incomplete) } - } - - #[inline] - pub fn is_completed(&self) -> bool { - self.state.get() == State::Complete - } - - #[inline] - pub(crate) fn state(&mut self) -> ExclusiveState { - match self.state.get() { - State::Incomplete => ExclusiveState::Incomplete, - State::Poisoned => ExclusiveState::Poisoned, - State::Complete => ExclusiveState::Complete, - _ => unreachable!("invalid Once state"), - } - } - - #[cold] - #[track_caller] - pub fn call(&self, ignore_poisoning: bool, f: &mut impl FnMut(&public::OnceState)) { - let state = self.state.get(); - match state { - State::Poisoned if !ignore_poisoning => { - // Panic to propagate the poison. - panic!("Once instance has previously been poisoned"); - } - State::Incomplete | State::Poisoned => { - self.state.set(State::Running); - // `guard` will set the new state on drop. - let mut guard = - CompletionGuard { state: &self.state, set_state_on_drop_to: State::Poisoned }; - // Run the function, letting it know if we're poisoned or not. - let f_state = public::OnceState { - inner: OnceState { - poisoned: state == State::Poisoned, - set_state_to: Cell::new(State::Complete), - }, - }; - f(&f_state); - guard.set_state_on_drop_to = f_state.inner.set_state_to.get(); - } - State::Running => { - panic!("one-time initialization may not be performed recursively"); - } - State::Complete => {} - } - } -} - -impl OnceState { - #[inline] - pub fn is_poisoned(&self) -> bool { - self.poisoned - } - - #[inline] - pub fn poison(&self) { - self.set_state_to.set(State::Poisoned) - } -} diff --git a/library/std/src/sys/sync/once/queue.rs b/library/std/src/sys/sync/once/queue.rs deleted file mode 100644 index 730cdb768bd27..0000000000000 --- a/library/std/src/sys/sync/once/queue.rs +++ /dev/null @@ -1,294 +0,0 @@ -// Each `Once` has one word of atomic state, and this state is CAS'd on to -// determine what to do. There are four possible state of a `Once`: -// -// * Incomplete - no initialization has run yet, and no thread is currently -// using the Once. -// * Poisoned - some thread has previously attempted to initialize the Once, but -// it panicked, so the Once is now poisoned. There are no other -// threads currently accessing this Once. -// * Running - some thread is currently attempting to run initialization. It may -// succeed, so all future threads need to wait for it to finish. -// Note that this state is accompanied with a payload, described -// below. -// * Complete - initialization has completed and all future calls should finish -// immediately. -// -// With 4 states we need 2 bits to encode this, and we use the remaining bits -// in the word we have allocated as a queue of threads waiting for the thread -// responsible for entering the RUNNING state. This queue is just a linked list -// of Waiter nodes which is monotonically increasing in size. Each node is -// allocated on the stack, and whenever the running closure finishes it will -// consume the entire queue and notify all waiters they should try again. -// -// You'll find a few more details in the implementation, but that's the gist of -// it! -// -// Atomic orderings: -// When running `Once` we deal with multiple atomics: -// `Once.state_and_queue` and an unknown number of `Waiter.signaled`. -// * `state_and_queue` is used (1) as a state flag, (2) for synchronizing the -// result of the `Once`, and (3) for synchronizing `Waiter` nodes. -// - At the end of the `call` function we have to make sure the result -// of the `Once` is acquired. So every load which can be the only one to -// load COMPLETED must have at least acquire ordering, which means all -// three of them. -// - `WaiterQueue::drop` is the only place that may store COMPLETED, and -// must do so with release ordering to make the result available. -// - `wait` inserts `Waiter` nodes as a pointer in `state_and_queue`, and -// needs to make the nodes available with release ordering. The load in -// its `compare_exchange` can be relaxed because it only has to compare -// the atomic, not to read other data. -// - `WaiterQueue::drop` must see the `Waiter` nodes, so it must load -// `state_and_queue` with acquire ordering. -// - There is just one store where `state_and_queue` is used only as a -// state flag, without having to synchronize data: switching the state -// from INCOMPLETE to RUNNING in `call`. This store can be Relaxed, -// but the read has to be Acquire because of the requirements mentioned -// above. -// * `Waiter.signaled` is both used as a flag, and to protect a field with -// interior mutability in `Waiter`. `Waiter.thread` is changed in -// `WaiterQueue::drop` which then sets `signaled` with release ordering. -// After `wait` loads `signaled` with acquire ordering and sees it is true, -// it needs to see the changes to drop the `Waiter` struct correctly. -// * There is one place where the two atomics `Once.state_and_queue` and -// `Waiter.signaled` come together, and might be reordered by the compiler or -// processor. Because both use acquire ordering such a reordering is not -// allowed, so no need for `SeqCst`. - -use crate::cell::Cell; -use crate::fmt; -use crate::ptr; -use crate::sync as public; -use crate::sync::atomic::{AtomicBool, AtomicPtr, Ordering}; -use crate::sync::once::ExclusiveState; -use crate::thread::{self, Thread}; - -type Masked = (); - -pub struct Once { - state_and_queue: AtomicPtr, -} - -pub struct OnceState { - poisoned: bool, - set_state_on_drop_to: Cell<*mut Masked>, -} - -// Four states that a Once can be in, encoded into the lower bits of -// `state_and_queue` in the Once structure. -const INCOMPLETE: usize = 0x0; -const POISONED: usize = 0x1; -const RUNNING: usize = 0x2; -const COMPLETE: usize = 0x3; - -// Mask to learn about the state. All other bits are the queue of waiters if -// this is in the RUNNING state. -const STATE_MASK: usize = 0x3; - -// Representation of a node in the linked list of waiters, used while in the -// RUNNING state. -// Note: `Waiter` can't hold a mutable pointer to the next thread, because then -// `wait` would both hand out a mutable reference to its `Waiter` node, and keep -// a shared reference to check `signaled`. Instead we hold shared references and -// use interior mutability. -#[repr(align(4))] // Ensure the two lower bits are free to use as state bits. -struct Waiter { - thread: Cell>, - signaled: AtomicBool, - next: *const Waiter, -} - -// Head of a linked list of waiters. -// Every node is a struct on the stack of a waiting thread. -// Will wake up the waiters when it gets dropped, i.e. also on panic. -struct WaiterQueue<'a> { - state_and_queue: &'a AtomicPtr, - set_state_on_drop_to: *mut Masked, -} - -impl Once { - #[inline] - #[rustc_const_stable(feature = "const_once_new", since = "1.32.0")] - pub const fn new() -> Once { - Once { state_and_queue: AtomicPtr::new(ptr::without_provenance_mut(INCOMPLETE)) } - } - - #[inline] - pub fn is_completed(&self) -> bool { - // An `Acquire` load is enough because that makes all the initialization - // operations visible to us, and, this being a fast path, weaker - // ordering helps with performance. This `Acquire` synchronizes with - // `Release` operations on the slow path. - self.state_and_queue.load(Ordering::Acquire).addr() == COMPLETE - } - - #[inline] - pub(crate) fn state(&mut self) -> ExclusiveState { - match self.state_and_queue.get_mut().addr() { - INCOMPLETE => ExclusiveState::Incomplete, - POISONED => ExclusiveState::Poisoned, - COMPLETE => ExclusiveState::Complete, - _ => unreachable!("invalid Once state"), - } - } - - // This is a non-generic function to reduce the monomorphization cost of - // using `call_once` (this isn't exactly a trivial or small implementation). - // - // Additionally, this is tagged with `#[cold]` as it should indeed be cold - // and it helps let LLVM know that calls to this function should be off the - // fast path. Essentially, this should help generate more straight line code - // in LLVM. - // - // Finally, this takes an `FnMut` instead of a `FnOnce` because there's - // currently no way to take an `FnOnce` and call it via virtual dispatch - // without some allocation overhead. - #[cold] - #[track_caller] - pub fn call(&self, ignore_poisoning: bool, init: &mut dyn FnMut(&public::OnceState)) { - let mut state_and_queue = self.state_and_queue.load(Ordering::Acquire); - loop { - match state_and_queue.addr() { - COMPLETE => break, - POISONED if !ignore_poisoning => { - // Panic to propagate the poison. - panic!("Once instance has previously been poisoned"); - } - POISONED | INCOMPLETE => { - // Try to register this thread as the one RUNNING. - let exchange_result = self.state_and_queue.compare_exchange( - state_and_queue, - ptr::without_provenance_mut(RUNNING), - Ordering::Acquire, - Ordering::Acquire, - ); - if let Err(old) = exchange_result { - state_and_queue = old; - continue; - } - // `waiter_queue` will manage other waiting threads, and - // wake them up on drop. - let mut waiter_queue = WaiterQueue { - state_and_queue: &self.state_and_queue, - set_state_on_drop_to: ptr::without_provenance_mut(POISONED), - }; - // Run the initialization function, letting it know if we're - // poisoned or not. - let init_state = public::OnceState { - inner: OnceState { - poisoned: state_and_queue.addr() == POISONED, - set_state_on_drop_to: Cell::new(ptr::without_provenance_mut(COMPLETE)), - }, - }; - init(&init_state); - waiter_queue.set_state_on_drop_to = init_state.inner.set_state_on_drop_to.get(); - break; - } - _ => { - // All other values must be RUNNING with possibly a - // pointer to the waiter queue in the more significant bits. - assert!(state_and_queue.addr() & STATE_MASK == RUNNING); - wait(&self.state_and_queue, state_and_queue); - state_and_queue = self.state_and_queue.load(Ordering::Acquire); - } - } - } - } -} - -fn wait(state_and_queue: &AtomicPtr, mut current_state: *mut Masked) { - // Note: the following code was carefully written to avoid creating a - // mutable reference to `node` that gets aliased. - loop { - // Don't queue this thread if the status is no longer running, - // otherwise we will not be woken up. - if current_state.addr() & STATE_MASK != RUNNING { - return; - } - - // Create the node for our current thread. - let node = Waiter { - thread: Cell::new(Some(thread::current())), - signaled: AtomicBool::new(false), - next: current_state.with_addr(current_state.addr() & !STATE_MASK) as *const Waiter, - }; - let me = core::ptr::addr_of!(node) as *const Masked as *mut Masked; - - // Try to slide in the node at the head of the linked list, making sure - // that another thread didn't just replace the head of the linked list. - let exchange_result = state_and_queue.compare_exchange( - current_state, - me.with_addr(me.addr() | RUNNING), - Ordering::Release, - Ordering::Relaxed, - ); - if let Err(old) = exchange_result { - current_state = old; - continue; - } - - // We have enqueued ourselves, now lets wait. - // It is important not to return before being signaled, otherwise we - // would drop our `Waiter` node and leave a hole in the linked list - // (and a dangling reference). Guard against spurious wakeups by - // reparking ourselves until we are signaled. - while !node.signaled.load(Ordering::Acquire) { - // If the managing thread happens to signal and unpark us before we - // can park ourselves, the result could be this thread never gets - // unparked. Luckily `park` comes with the guarantee that if it got - // an `unpark` just before on an unparked thread it does not park. - thread::park(); - } - break; - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for Once { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Once").finish_non_exhaustive() - } -} - -impl Drop for WaiterQueue<'_> { - fn drop(&mut self) { - // Swap out our state with however we finished. - let state_and_queue = - self.state_and_queue.swap(self.set_state_on_drop_to, Ordering::AcqRel); - - // We should only ever see an old state which was RUNNING. - assert_eq!(state_and_queue.addr() & STATE_MASK, RUNNING); - - // Walk the entire linked list of waiters and wake them up (in lifo - // order, last to register is first to wake up). - unsafe { - // Right after setting `node.signaled = true` the other thread may - // free `node` if there happens to be has a spurious wakeup. - // So we have to take out the `thread` field and copy the pointer to - // `next` first. - let mut queue = - state_and_queue.with_addr(state_and_queue.addr() & !STATE_MASK) as *const Waiter; - while !queue.is_null() { - let next = (*queue).next; - let thread = (*queue).thread.take().unwrap(); - (*queue).signaled.store(true, Ordering::Release); - // ^- FIXME (maybe): This is another case of issue #55005 - // `store()` has a potentially dangling ref to `signaled`. - queue = next; - thread.unpark(); - } - } - } -} - -impl OnceState { - #[inline] - pub fn is_poisoned(&self) -> bool { - self.poisoned - } - - #[inline] - pub fn poison(&self) { - self.set_state_on_drop_to.set(ptr::without_provenance_mut(POISONED)); - } -} diff --git a/library/std/src/sys/sync/rwlock/futex.rs b/library/std/src/sys/sync/rwlock/futex.rs deleted file mode 100644 index aa0de900238f5..0000000000000 --- a/library/std/src/sys/sync/rwlock/futex.rs +++ /dev/null @@ -1,320 +0,0 @@ -use crate::sync::atomic::{ - AtomicU32, - Ordering::{Acquire, Relaxed, Release}, -}; -use crate::sys::futex::{futex_wait, futex_wake, futex_wake_all}; - -pub struct RwLock { - // The state consists of a 30-bit reader counter, a 'readers waiting' flag, and a 'writers waiting' flag. - // Bits 0..30: - // 0: Unlocked - // 1..=0x3FFF_FFFE: Locked by N readers - // 0x3FFF_FFFF: Write locked - // Bit 30: Readers are waiting on this futex. - // Bit 31: Writers are waiting on the writer_notify futex. - state: AtomicU32, - // The 'condition variable' to notify writers through. - // Incremented on every signal. - writer_notify: AtomicU32, -} - -const READ_LOCKED: u32 = 1; -const MASK: u32 = (1 << 30) - 1; -const WRITE_LOCKED: u32 = MASK; -const MAX_READERS: u32 = MASK - 1; -const READERS_WAITING: u32 = 1 << 30; -const WRITERS_WAITING: u32 = 1 << 31; - -#[inline] -fn is_unlocked(state: u32) -> bool { - state & MASK == 0 -} - -#[inline] -fn is_write_locked(state: u32) -> bool { - state & MASK == WRITE_LOCKED -} - -#[inline] -fn has_readers_waiting(state: u32) -> bool { - state & READERS_WAITING != 0 -} - -#[inline] -fn has_writers_waiting(state: u32) -> bool { - state & WRITERS_WAITING != 0 -} - -#[inline] -fn is_read_lockable(state: u32) -> bool { - // This also returns false if the counter could overflow if we tried to read lock it. - // - // We don't allow read-locking if there's readers waiting, even if the lock is unlocked - // and there's no writers waiting. The only situation when this happens is after unlocking, - // at which point the unlocking thread might be waking up writers, which have priority over readers. - // The unlocking thread will clear the readers waiting bit and wake up readers, if necessary. - state & MASK < MAX_READERS && !has_readers_waiting(state) && !has_writers_waiting(state) -} - -#[inline] -fn has_reached_max_readers(state: u32) -> bool { - state & MASK == MAX_READERS -} - -impl RwLock { - #[inline] - pub const fn new() -> Self { - Self { state: AtomicU32::new(0), writer_notify: AtomicU32::new(0) } - } - - #[inline] - pub fn try_read(&self) -> bool { - self.state - .fetch_update(Acquire, Relaxed, |s| is_read_lockable(s).then(|| s + READ_LOCKED)) - .is_ok() - } - - #[inline] - pub fn read(&self) { - let state = self.state.load(Relaxed); - if !is_read_lockable(state) - || self - .state - .compare_exchange_weak(state, state + READ_LOCKED, Acquire, Relaxed) - .is_err() - { - self.read_contended(); - } - } - - #[inline] - pub unsafe fn read_unlock(&self) { - let state = self.state.fetch_sub(READ_LOCKED, Release) - READ_LOCKED; - - // It's impossible for a reader to be waiting on a read-locked RwLock, - // except if there is also a writer waiting. - debug_assert!(!has_readers_waiting(state) || has_writers_waiting(state)); - - // Wake up a writer if we were the last reader and there's a writer waiting. - if is_unlocked(state) && has_writers_waiting(state) { - self.wake_writer_or_readers(state); - } - } - - #[cold] - fn read_contended(&self) { - let mut state = self.spin_read(); - - loop { - // If we can lock it, lock it. - if is_read_lockable(state) { - match self.state.compare_exchange_weak(state, state + READ_LOCKED, Acquire, Relaxed) - { - Ok(_) => return, // Locked! - Err(s) => { - state = s; - continue; - } - } - } - - // Check for overflow. - if has_reached_max_readers(state) { - panic!("too many active read locks on RwLock"); - } - - // Make sure the readers waiting bit is set before we go to sleep. - if !has_readers_waiting(state) { - if let Err(s) = - self.state.compare_exchange(state, state | READERS_WAITING, Relaxed, Relaxed) - { - state = s; - continue; - } - } - - // Wait for the state to change. - futex_wait(&self.state, state | READERS_WAITING, None); - - // Spin again after waking up. - state = self.spin_read(); - } - } - - #[inline] - pub fn try_write(&self) -> bool { - self.state - .fetch_update(Acquire, Relaxed, |s| is_unlocked(s).then(|| s + WRITE_LOCKED)) - .is_ok() - } - - #[inline] - pub fn write(&self) { - if self.state.compare_exchange_weak(0, WRITE_LOCKED, Acquire, Relaxed).is_err() { - self.write_contended(); - } - } - - #[inline] - pub unsafe fn write_unlock(&self) { - let state = self.state.fetch_sub(WRITE_LOCKED, Release) - WRITE_LOCKED; - - debug_assert!(is_unlocked(state)); - - if has_writers_waiting(state) || has_readers_waiting(state) { - self.wake_writer_or_readers(state); - } - } - - #[cold] - fn write_contended(&self) { - let mut state = self.spin_write(); - - let mut other_writers_waiting = 0; - - loop { - // If it's unlocked, we try to lock it. - if is_unlocked(state) { - match self.state.compare_exchange_weak( - state, - state | WRITE_LOCKED | other_writers_waiting, - Acquire, - Relaxed, - ) { - Ok(_) => return, // Locked! - Err(s) => { - state = s; - continue; - } - } - } - - // Set the waiting bit indicating that we're waiting on it. - if !has_writers_waiting(state) { - if let Err(s) = - self.state.compare_exchange(state, state | WRITERS_WAITING, Relaxed, Relaxed) - { - state = s; - continue; - } - } - - // Other writers might be waiting now too, so we should make sure - // we keep that bit on once we manage lock it. - other_writers_waiting = WRITERS_WAITING; - - // Examine the notification counter before we check if `state` has changed, - // to make sure we don't miss any notifications. - let seq = self.writer_notify.load(Acquire); - - // Don't go to sleep if the lock has become available, - // or if the writers waiting bit is no longer set. - state = self.state.load(Relaxed); - if is_unlocked(state) || !has_writers_waiting(state) { - continue; - } - - // Wait for the state to change. - futex_wait(&self.writer_notify, seq, None); - - // Spin again after waking up. - state = self.spin_write(); - } - } - - /// Wake up waiting threads after unlocking. - /// - /// If both are waiting, this will wake up only one writer, but will fall - /// back to waking up readers if there was no writer to wake up. - #[cold] - fn wake_writer_or_readers(&self, mut state: u32) { - assert!(is_unlocked(state)); - - // The readers waiting bit might be turned on at any point now, - // since readers will block when there's anything waiting. - // Writers will just lock the lock though, regardless of the waiting bits, - // so we don't have to worry about the writer waiting bit. - // - // If the lock gets locked in the meantime, we don't have to do - // anything, because then the thread that locked the lock will take - // care of waking up waiters when it unlocks. - - // If only writers are waiting, wake one of them up. - if state == WRITERS_WAITING { - match self.state.compare_exchange(state, 0, Relaxed, Relaxed) { - Ok(_) => { - self.wake_writer(); - return; - } - Err(s) => { - // Maybe some readers are now waiting too. So, continue to the next `if`. - state = s; - } - } - } - - // If both writers and readers are waiting, leave the readers waiting - // and only wake up one writer. - if state == READERS_WAITING + WRITERS_WAITING { - if self.state.compare_exchange(state, READERS_WAITING, Relaxed, Relaxed).is_err() { - // The lock got locked. Not our problem anymore. - return; - } - if self.wake_writer() { - return; - } - // No writers were actually blocked on futex_wait, so we continue - // to wake up readers instead, since we can't be sure if we notified a writer. - state = READERS_WAITING; - } - - // If readers are waiting, wake them all up. - if state == READERS_WAITING { - if self.state.compare_exchange(state, 0, Relaxed, Relaxed).is_ok() { - futex_wake_all(&self.state); - } - } - } - - /// This wakes one writer and returns true if we woke up a writer that was - /// blocked on futex_wait. - /// - /// If this returns false, it might still be the case that we notified a - /// writer that was about to go to sleep. - fn wake_writer(&self) -> bool { - self.writer_notify.fetch_add(1, Release); - futex_wake(&self.writer_notify) - // Note that FreeBSD and DragonFlyBSD don't tell us whether they woke - // up any threads or not, and always return `false` here. That still - // results in correct behaviour: it just means readers get woken up as - // well in case both readers and writers were waiting. - } - - /// Spin for a while, but stop directly at the given condition. - #[inline] - fn spin_until(&self, f: impl Fn(u32) -> bool) -> u32 { - let mut spin = 100; // Chosen by fair dice roll. - loop { - let state = self.state.load(Relaxed); - if f(state) || spin == 0 { - return state; - } - crate::hint::spin_loop(); - spin -= 1; - } - } - - #[inline] - fn spin_write(&self) -> u32 { - // Stop spinning when it's unlocked or when there's waiting writers, to keep things somewhat fair. - self.spin_until(|state| is_unlocked(state) || has_writers_waiting(state)) - } - - #[inline] - fn spin_read(&self) -> u32 { - // Stop spinning when it's unlocked or read locked, or when there's waiting threads. - self.spin_until(|state| { - !is_write_locked(state) || has_readers_waiting(state) || has_writers_waiting(state) - }) - } -} diff --git a/library/std/src/sys/sync/rwlock/mod.rs b/library/std/src/sys/sync/rwlock/mod.rs deleted file mode 100644 index 70ba6bf38ef55..0000000000000 --- a/library/std/src/sys/sync/rwlock/mod.rs +++ /dev/null @@ -1,33 +0,0 @@ -cfg_if::cfg_if! { - if #[cfg(any( - all(target_os = "windows", not(target_vendor = "win7")), - target_os = "linux", - target_os = "android", - target_os = "freebsd", - target_os = "openbsd", - target_os = "dragonfly", - target_os = "fuchsia", - all(target_family = "wasm", target_feature = "atomics"), - target_os = "hermit", - ))] { - mod futex; - pub use futex::RwLock; - } else if #[cfg(any( - target_family = "unix", - all(target_os = "windows", target_vendor = "win7"), - all(target_vendor = "fortanix", target_env = "sgx"), - target_os = "xous", - ))] { - mod queue; - pub use queue::RwLock; - } else if #[cfg(target_os = "solid_asp3")] { - mod solid; - pub use solid::RwLock; - } else if #[cfg(target_os = "teeos")] { - mod teeos; - pub use teeos::RwLock; - } else { - mod no_threads; - pub use no_threads::RwLock; - } -} diff --git a/library/std/src/sys/sync/rwlock/no_threads.rs b/library/std/src/sys/sync/rwlock/no_threads.rs deleted file mode 100644 index 789ef9b29e52a..0000000000000 --- a/library/std/src/sys/sync/rwlock/no_threads.rs +++ /dev/null @@ -1,65 +0,0 @@ -use crate::cell::Cell; - -pub struct RwLock { - // This platform has no threads, so we can use a Cell here. - mode: Cell, -} - -unsafe impl Send for RwLock {} -unsafe impl Sync for RwLock {} // no threads on this platform - -impl RwLock { - #[inline] - #[rustc_const_stable(feature = "const_locks", since = "1.63.0")] - pub const fn new() -> RwLock { - RwLock { mode: Cell::new(0) } - } - - #[inline] - pub fn read(&self) { - let m = self.mode.get(); - if m >= 0 { - self.mode.set(m + 1); - } else { - rtabort!("rwlock locked for writing"); - } - } - - #[inline] - pub fn try_read(&self) -> bool { - let m = self.mode.get(); - if m >= 0 { - self.mode.set(m + 1); - true - } else { - false - } - } - - #[inline] - pub fn write(&self) { - if self.mode.replace(-1) != 0 { - rtabort!("rwlock locked for reading") - } - } - - #[inline] - pub fn try_write(&self) -> bool { - if self.mode.get() == 0 { - self.mode.set(-1); - true - } else { - false - } - } - - #[inline] - pub unsafe fn read_unlock(&self) { - self.mode.set(self.mode.get() - 1); - } - - #[inline] - pub unsafe fn write_unlock(&self) { - assert_eq!(self.mode.replace(0), -1); - } -} diff --git a/library/std/src/sys/sync/rwlock/queue.rs b/library/std/src/sys/sync/rwlock/queue.rs deleted file mode 100644 index 337cc6c2ca094..0000000000000 --- a/library/std/src/sys/sync/rwlock/queue.rs +++ /dev/null @@ -1,555 +0,0 @@ -//! Efficient read-write locking without `pthread_rwlock_t`. -//! -//! The readers-writer lock provided by the `pthread` library has a number of -//! problems which make it a suboptimal choice for `std`: -//! -//! * It is non-movable, so it needs to be allocated (lazily, to make the -//! constructor `const`). -//! * `pthread` is an external library, meaning the fast path of acquiring an -//! uncontended lock cannot be inlined. -//! * Some platforms (at least glibc before version 2.25) have buggy implementations -//! that can easily lead to undefined behaviour in safe Rust code when not properly -//! guarded against. -//! * On some platforms (e.g. macOS), the lock is very slow. -//! -//! Therefore, we implement our own `RwLock`! Naively, one might reach for a -//! spinlock, but those [can be quite problematic] when the lock is contended. -//! Instead, this readers-writer lock copies its implementation strategy from -//! the Windows [SRWLOCK] and the [usync] library. Spinning is still used for the -//! fast path, but it is bounded: after spinning fails, threads will locklessly -//! add an information structure containing a [`Thread`] handle into a queue of -//! waiters associated with the lock. The lock owner, upon releasing the lock, -//! will scan through the queue and wake up threads as appropriate, which will -//! then again try to acquire the lock. The resulting [`RwLock`] is: -//! -//! * adaptive, since it spins before doing any heavywheight parking operations -//! * allocation-free, modulo the per-thread [`Thread`] handle, which is -//! allocated regardless when using threads created by `std` -//! * writer-preferring, even if some readers may still slip through -//! * unfair, which reduces context-switching and thus drastically improves -//! performance -//! -//! and also quite fast in most cases. -//! -//! [can be quite problematic]: https://matklad.github.io/2020/01/02/spinlocks-considered-harmful.html -//! [SRWLOCK]: https://learn.microsoft.com/en-us/windows/win32/sync/slim-reader-writer--srw--locks -//! [usync]: https://crates.io/crates/usync -//! -//! # Implementation -//! -//! ## State -//! -//! A single [`AtomicPtr`] is used as state variable. The lowest three bits are used -//! to indicate the meaning of the remaining bits: -//! -//! | [`LOCKED`] | [`QUEUED`] | [`QUEUE_LOCKED`] | Remaining | | -//! |:-----------|:-----------|:-----------------|:-------------|:----------------------------------------------------------------------------------------------------------------------------| -//! | 0 | 0 | 0 | 0 | The lock is unlocked, no threads are waiting | -//! | 1 | 0 | 0 | 0 | The lock is write-locked, no threads waiting | -//! | 1 | 0 | 0 | n > 0 | The lock is read-locked with n readers | -//! | 0 | 1 | * | `*mut Node` | The lock is unlocked, but some threads are waiting. Only writers may lock the lock | -//! | 1 | 1 | * | `*mut Node` | The lock is locked, but some threads are waiting. If the lock is read-locked, the last queue node contains the reader count | -//! -//! ## Waiter queue -//! -//! When threads are waiting on the lock (`QUEUE` is set), the lock state -//! points to a queue of waiters, which is implemented as a linked list of -//! nodes stored on the stack to avoid memory allocation. To enable lockless -//! enqueuing of new nodes to the queue, the linked list is single-linked upon -//! creation. Since when the lock is read-locked, the lock count is stored in -//! the last link of the queue, threads have to traverse the queue to find the -//! last element upon releasing the lock. To avoid having to traverse the whole -//! list again and again, a pointer to the found tail is cached in the (current) -//! first element of the queue. -//! -//! Also, while the lock is unfair for performance reasons, it is still best to -//! wake the tail node first, which requires backlinks to previous nodes to be -//! created. This is done at the same time as finding the tail, and thus a set -//! tail field indicates the remaining portion of the queue is initialized. -//! -//! TLDR: Here's a diagram of what the queue looks like: -//! -//! ```text -//! state -//! │ -//! ▼ -//! ╭───────╮ next ╭───────╮ next ╭───────╮ next ╭───────╮ -//! │ ├─────►│ ├─────►│ ├─────►│ count │ -//! │ │ │ │ │ │ │ │ -//! │ │ │ │◄─────┤ │◄─────┤ │ -//! ╰───────╯ ╰───────╯ prev ╰───────╯ prev ╰───────╯ -//! │ ▲ -//! └───────────────────────────┘ -//! tail -//! ``` -//! -//! Invariants: -//! 1. At least one node must contain a non-null, current `tail` field. -//! 2. The first non-null `tail` field must be valid and current. -//! 3. All nodes preceding this node must have a correct, non-null `next` field. -//! 4. All nodes following this node must have a correct, non-null `prev` field. -//! -//! Access to the queue is controlled by the `QUEUE_LOCKED` bit, which threads -//! try to set both after enqueuing themselves to eagerly add backlinks to the -//! queue, which drastically improves performance, and after unlocking the lock -//! to wake the next waiter(s). This is done atomically at the same time as the -//! enqueuing/unlocking operation. The thread releasing the `QUEUE_LOCK` bit -//! will check the state of the lock and wake up waiters as appropriate. This -//! guarantees forward-progress even if the unlocking thread could not acquire -//! the queue lock. -//! -//! ## Memory orderings -//! -//! To properly synchronize changes to the data protected by the lock, the lock -//! is acquired and released with [`Acquire`] and [`Release`] ordering, respectively. -//! To propagate the initialization of nodes, changes to the queue lock are also -//! performed using these orderings. - -#![forbid(unsafe_op_in_unsafe_fn)] - -use crate::cell::OnceCell; -use crate::hint::spin_loop; -use crate::mem; -use crate::ptr::{self, null_mut, without_provenance_mut, NonNull}; -use crate::sync::atomic::{ - AtomicBool, AtomicPtr, - Ordering::{AcqRel, Acquire, Relaxed, Release}, -}; -use crate::thread::{self, Thread}; - -// Locking uses exponential backoff. `SPIN_COUNT` indicates how many times the -// locking operation will be retried. -// `spin_loop` will be called `2.pow(SPIN_COUNT) - 1` times. -const SPIN_COUNT: usize = 7; - -type State = *mut (); -type AtomicState = AtomicPtr<()>; - -const UNLOCKED: State = without_provenance_mut(0); -const LOCKED: usize = 1; -const QUEUED: usize = 2; -const QUEUE_LOCKED: usize = 4; -const SINGLE: usize = 8; -const MASK: usize = !(QUEUE_LOCKED | QUEUED | LOCKED); - -/// Marks the state as write-locked, if possible. -#[inline] -fn write_lock(state: State) -> Option { - let state = state.wrapping_byte_add(LOCKED); - if state.addr() & LOCKED == LOCKED { Some(state) } else { None } -} - -/// Marks the state as read-locked, if possible. -#[inline] -fn read_lock(state: State) -> Option { - if state.addr() & QUEUED == 0 && state.addr() != LOCKED { - Some(without_provenance_mut(state.addr().checked_add(SINGLE)? | LOCKED)) - } else { - None - } -} - -/// Masks the state, assuming it points to a queue node. -/// -/// # Safety -/// The state must contain a valid pointer to a queue node. -#[inline] -unsafe fn to_node(state: State) -> NonNull { - unsafe { NonNull::new_unchecked(state.mask(MASK)).cast() } -} - -/// An atomic node pointer with relaxed operations. -struct AtomicLink(AtomicPtr); - -impl AtomicLink { - fn new(v: Option>) -> AtomicLink { - AtomicLink(AtomicPtr::new(v.map_or(null_mut(), NonNull::as_ptr))) - } - - fn get(&self) -> Option> { - NonNull::new(self.0.load(Relaxed)) - } - - fn set(&self, v: Option>) { - self.0.store(v.map_or(null_mut(), NonNull::as_ptr), Relaxed); - } -} - -#[repr(align(8))] -struct Node { - next: AtomicLink, - prev: AtomicLink, - tail: AtomicLink, - write: bool, - thread: OnceCell, - completed: AtomicBool, -} - -impl Node { - /// Create a new queue node. - fn new(write: bool) -> Node { - Node { - next: AtomicLink::new(None), - prev: AtomicLink::new(None), - tail: AtomicLink::new(None), - write, - thread: OnceCell::new(), - completed: AtomicBool::new(false), - } - } - - /// Prepare this node for waiting. - fn prepare(&mut self) { - // Fall back to creating an unnamed `Thread` handle to allow locking in - // TLS destructors. - self.thread.get_or_init(|| thread::try_current().unwrap_or_else(Thread::new_unnamed)); - self.completed = AtomicBool::new(false); - } - - /// Wait until this node is marked as completed. - /// - /// # Safety - /// May only be called from the thread that created the node. - unsafe fn wait(&self) { - while !self.completed.load(Acquire) { - unsafe { - self.thread.get().unwrap().park(); - } - } - } - - /// Atomically mark this node as completed. The node may not outlive this call. - unsafe fn complete(this: NonNull) { - // Since the node may be destroyed immediately after the completed flag - // is set, clone the thread handle before that. - let thread = unsafe { this.as_ref().thread.get().unwrap().clone() }; - unsafe { - this.as_ref().completed.store(true, Release); - } - thread.unpark(); - } -} - -struct PanicGuard; - -impl Drop for PanicGuard { - fn drop(&mut self) { - rtabort!("tried to drop node in intrusive list."); - } -} - -/// Add backlinks to the queue, returning the tail. -/// -/// May be called from multiple threads at the same time, while the queue is not -/// modified (this happens when unlocking multiple readers). -/// -/// # Safety -/// * `head` must point to a node in a valid queue. -/// * `head` must be or be in front of the head of the queue at the time of the -/// last removal. -/// * The part of the queue starting with `head` must not be modified during this -/// call. -unsafe fn add_backlinks_and_find_tail(head: NonNull) -> NonNull { - let mut current = head; - let tail = loop { - let c = unsafe { current.as_ref() }; - match c.tail.get() { - Some(tail) => break tail, - // SAFETY: - // All `next` fields before the first node with a `set` tail are - // non-null and valid (invariant 3). - None => unsafe { - let next = c.next.get().unwrap_unchecked(); - next.as_ref().prev.set(Some(current)); - current = next; - }, - } - }; - - unsafe { - head.as_ref().tail.set(Some(tail)); - tail - } -} - -pub struct RwLock { - state: AtomicState, -} - -impl RwLock { - #[inline] - pub const fn new() -> RwLock { - RwLock { state: AtomicPtr::new(UNLOCKED) } - } - - #[inline] - pub fn try_read(&self) -> bool { - self.state.fetch_update(Acquire, Relaxed, read_lock).is_ok() - } - - #[inline] - pub fn read(&self) { - if !self.try_read() { - self.lock_contended(false) - } - } - - #[inline] - pub fn try_write(&self) -> bool { - // Atomically set the `LOCKED` bit. This is lowered to a single atomic - // instruction on most modern processors (e.g. "lock bts" on x86 and - // "ldseta" on modern AArch64), and therefore is more efficient than - // `fetch_update(lock(true))`, which can spuriously fail if a new node - // is appended to the queue. - self.state.fetch_or(LOCKED, Acquire).addr() & LOCKED == 0 - } - - #[inline] - pub fn write(&self) { - if !self.try_write() { - self.lock_contended(true) - } - } - - #[cold] - fn lock_contended(&self, write: bool) { - let update = if write { write_lock } else { read_lock }; - let mut node = Node::new(write); - let mut state = self.state.load(Relaxed); - let mut count = 0; - loop { - if let Some(next) = update(state) { - // The lock is available, try locking it. - match self.state.compare_exchange_weak(state, next, Acquire, Relaxed) { - Ok(_) => return, - Err(new) => state = new, - } - } else if state.addr() & QUEUED == 0 && count < SPIN_COUNT { - // If the lock is not available and no threads are queued, spin - // for a while, using exponential backoff to decrease cache - // contention. - for _ in 0..(1 << count) { - spin_loop(); - } - state = self.state.load(Relaxed); - count += 1; - } else { - // Fall back to parking. First, prepare the node. - node.prepare(); - - // If there are threads queued, set the `next` field to a - // pointer to the next node in the queue. Otherwise set it to - // the lock count if the state is read-locked or to zero if it - // is write-locked. - node.next.0 = AtomicPtr::new(state.mask(MASK).cast()); - node.prev = AtomicLink::new(None); - let mut next = ptr::from_ref(&node) - .map_addr(|addr| addr | QUEUED | (state.addr() & LOCKED)) - as State; - - if state.addr() & QUEUED == 0 { - // If this is the first node in the queue, set the tail field to - // the node itself to ensure there is a current `tail` field in - // the queue (invariants 1 and 2). This needs to use `set` to - // avoid invalidating the new pointer. - node.tail.set(Some(NonNull::from(&node))); - } else { - // Otherwise, the tail of the queue is not known. - node.tail.set(None); - // Try locking the queue to eagerly add backlinks. - next = next.map_addr(|addr| addr | QUEUE_LOCKED); - } - - // Register the node, using release ordering to propagate our - // changes to the waking thread. - if let Err(new) = self.state.compare_exchange_weak(state, next, AcqRel, Relaxed) { - // The state has changed, just try again. - state = new; - continue; - } - - // The node is registered, so the structure must not be - // mutably accessed or destroyed while other threads may - // be accessing it. Guard against unwinds using a panic - // guard that aborts when dropped. - let guard = PanicGuard; - - // If the current thread locked the queue, unlock it again, - // linking it in the process. - if state.addr() & (QUEUE_LOCKED | QUEUED) == QUEUED { - unsafe { - self.unlock_queue(next); - } - } - - // Wait until the node is removed from the queue. - // SAFETY: the node was created by the current thread. - unsafe { - node.wait(); - } - - // The node was removed from the queue, disarm the guard. - mem::forget(guard); - - // Reload the state and try again. - state = self.state.load(Relaxed); - count = 0; - } - } - } - - #[inline] - pub unsafe fn read_unlock(&self) { - match self.state.fetch_update(Release, Acquire, |state| { - if state.addr() & QUEUED == 0 { - let count = state.addr() - (SINGLE | LOCKED); - Some(if count > 0 { without_provenance_mut(count | LOCKED) } else { UNLOCKED }) - } else { - None - } - }) { - Ok(_) => {} - // There are waiters queued and the lock count was moved to the - // tail of the queue. - Err(state) => unsafe { self.read_unlock_contended(state) }, - } - } - - #[cold] - unsafe fn read_unlock_contended(&self, state: State) { - // The state was observed with acquire ordering above, so the current - // thread will observe all node initializations. - - // SAFETY: - // Because new read-locks cannot be acquired while threads are queued, - // all queue-lock owners will observe the set `LOCKED` bit. Because they - // do not modify the queue while there is a lock owner, the queue will - // not be removed from here. - let tail = unsafe { add_backlinks_and_find_tail(to_node(state)).as_ref() }; - // The lock count is stored in the `next` field of `tail`. - // Decrement it, making sure to observe all changes made to the queue - // by the other lock owners by using acquire-release ordering. - let was_last = tail.next.0.fetch_byte_sub(SINGLE, AcqRel).addr() - SINGLE == 0; - if was_last { - // SAFETY: - // Other threads cannot read-lock while threads are queued. Also, - // the `LOCKED` bit is still set, so there are no writers. Therefore, - // the current thread exclusively owns the lock. - unsafe { self.unlock_contended(state) } - } - } - - #[inline] - pub unsafe fn write_unlock(&self) { - if let Err(state) = - self.state.compare_exchange(without_provenance_mut(LOCKED), UNLOCKED, Release, Relaxed) - { - // SAFETY: - // Since other threads cannot acquire the lock, the state can only - // have changed because there are threads queued on the lock. - unsafe { self.unlock_contended(state) } - } - } - - /// # Safety - /// * The lock must be exclusively owned by this thread. - /// * There must be threads queued on the lock. - #[cold] - unsafe fn unlock_contended(&self, mut state: State) { - loop { - // Atomically release the lock and try to acquire the queue lock. - let next = state.map_addr(|a| (a & !LOCKED) | QUEUE_LOCKED); - match self.state.compare_exchange_weak(state, next, AcqRel, Relaxed) { - // The queue lock was acquired. Release it, waking up the next - // waiter in the process. - Ok(_) if state.addr() & QUEUE_LOCKED == 0 => unsafe { - return self.unlock_queue(next); - }, - // Another thread already holds the queue lock, leave waking up - // waiters to it. - Ok(_) => return, - Err(new) => state = new, - } - } - } - - /// Unlocks the queue. If the lock is unlocked, wakes up the next eligible - /// thread(s). - /// - /// # Safety - /// The queue lock must be held by the current thread. - unsafe fn unlock_queue(&self, mut state: State) { - debug_assert_eq!(state.addr() & (QUEUED | QUEUE_LOCKED), QUEUED | QUEUE_LOCKED); - - loop { - let tail = unsafe { add_backlinks_and_find_tail(to_node(state)) }; - - if state.addr() & LOCKED == LOCKED { - // Another thread has locked the lock. Leave waking up waiters - // to them by releasing the queue lock. - match self.state.compare_exchange_weak( - state, - state.mask(!QUEUE_LOCKED), - Release, - Acquire, - ) { - Ok(_) => return, - Err(new) => { - state = new; - continue; - } - } - } - - let is_writer = unsafe { tail.as_ref().write }; - if is_writer && let Some(prev) = unsafe { tail.as_ref().prev.get() } { - // `tail` is a writer and there is a node before `tail`. - // Split off `tail`. - - // There are no set `tail` links before the node pointed to by - // `state`, so the first non-null tail field will be current - // (invariant 2). Invariant 4 is fullfilled since `find_tail` - // was called on this node, which ensures all backlinks are set. - unsafe { - to_node(state).as_ref().tail.set(Some(prev)); - } - - // Release the queue lock. Doing this by subtraction is more - // efficient on modern processors since it is a single instruction - // instead of an update loop, which will fail if new threads are - // added to the list. - self.state.fetch_byte_sub(QUEUE_LOCKED, Release); - - // The tail was split off and the lock released. Mark the node as - // completed. - unsafe { - return Node::complete(tail); - } - } else { - // The next waiter is a reader or the queue only consists of one - // waiter. Just wake all threads. - - // The lock cannot be locked (checked above), so mark it as - // unlocked to reset the queue. - if let Err(new) = - self.state.compare_exchange_weak(state, UNLOCKED, Release, Acquire) - { - state = new; - continue; - } - - let mut current = tail; - loop { - let prev = unsafe { current.as_ref().prev.get() }; - unsafe { - Node::complete(current); - } - match prev { - Some(prev) => current = prev, - None => return, - } - } - } - } - } -} diff --git a/library/std/src/sys/sync/rwlock/solid.rs b/library/std/src/sys/sync/rwlock/solid.rs deleted file mode 100644 index 9bf6f5dbb731e..0000000000000 --- a/library/std/src/sys/sync/rwlock/solid.rs +++ /dev/null @@ -1,93 +0,0 @@ -//! A readers-writer lock implementation backed by the SOLID kernel extension. -use crate::sys::pal::{ - abi, - itron::{ - error::{expect_success, expect_success_aborting, fail, ItronError}, - spin::SpinIdOnceCell, - }, -}; - -pub struct RwLock { - /// The ID of the underlying mutex object - rwl: SpinIdOnceCell<()>, -} - -// Safety: `num_readers` is protected by `mtx_num_readers` -unsafe impl Send for RwLock {} -unsafe impl Sync for RwLock {} - -fn new_rwl() -> Result { - ItronError::err_if_negative(unsafe { abi::rwl_acre_rwl() }) -} - -impl RwLock { - #[inline] - pub const fn new() -> RwLock { - RwLock { rwl: SpinIdOnceCell::new() } - } - - /// Get the inner mutex's ID, which is lazily created. - fn raw(&self) -> abi::ID { - match self.rwl.get_or_try_init(|| new_rwl().map(|id| (id, ()))) { - Ok((id, ())) => id, - Err(e) => fail(e, &"rwl_acre_rwl"), - } - } - - #[inline] - pub fn read(&self) { - let rwl = self.raw(); - expect_success(unsafe { abi::rwl_loc_rdl(rwl) }, &"rwl_loc_rdl"); - } - - #[inline] - pub fn try_read(&self) -> bool { - let rwl = self.raw(); - match unsafe { abi::rwl_ploc_rdl(rwl) } { - abi::E_TMOUT => false, - er => { - expect_success(er, &"rwl_ploc_rdl"); - true - } - } - } - - #[inline] - pub fn write(&self) { - let rwl = self.raw(); - expect_success(unsafe { abi::rwl_loc_wrl(rwl) }, &"rwl_loc_wrl"); - } - - #[inline] - pub fn try_write(&self) -> bool { - let rwl = self.raw(); - match unsafe { abi::rwl_ploc_wrl(rwl) } { - abi::E_TMOUT => false, - er => { - expect_success(er, &"rwl_ploc_wrl"); - true - } - } - } - - #[inline] - pub unsafe fn read_unlock(&self) { - let rwl = self.raw(); - expect_success_aborting(unsafe { abi::rwl_unl_rwl(rwl) }, &"rwl_unl_rwl"); - } - - #[inline] - pub unsafe fn write_unlock(&self) { - let rwl = self.raw(); - expect_success_aborting(unsafe { abi::rwl_unl_rwl(rwl) }, &"rwl_unl_rwl"); - } -} - -impl Drop for RwLock { - #[inline] - fn drop(&mut self) { - if let Some(rwl) = self.rwl.get().map(|x| x.0) { - expect_success_aborting(unsafe { abi::rwl_del_rwl(rwl) }, &"rwl_del_rwl"); - } - } -} diff --git a/library/std/src/sys/sync/rwlock/teeos.rs b/library/std/src/sys/sync/rwlock/teeos.rs deleted file mode 100644 index ef9b1ab51546c..0000000000000 --- a/library/std/src/sys/sync/rwlock/teeos.rs +++ /dev/null @@ -1,44 +0,0 @@ -use crate::sys::sync::mutex::Mutex; - -/// we do not supported rwlock, so use mutex to simulate rwlock. -/// it's useful because so many code in std will use rwlock. -pub struct RwLock { - inner: Mutex, -} - -impl RwLock { - #[inline] - pub const fn new() -> RwLock { - RwLock { inner: Mutex::new() } - } - - #[inline] - pub fn read(&self) { - unsafe { self.inner.lock() }; - } - - #[inline] - pub fn try_read(&self) -> bool { - unsafe { self.inner.try_lock() } - } - - #[inline] - pub fn write(&self) { - unsafe { self.inner.lock() }; - } - - #[inline] - pub unsafe fn try_write(&self) -> bool { - unsafe { self.inner.try_lock() } - } - - #[inline] - pub unsafe fn read_unlock(&self) { - unsafe { self.inner.unlock() }; - } - - #[inline] - pub unsafe fn write_unlock(&self) { - unsafe { self.inner.unlock() }; - } -} diff --git a/library/std/src/sys/sync/thread_parking/darwin.rs b/library/std/src/sys/sync/thread_parking/darwin.rs deleted file mode 100644 index 973c08f03171e..0000000000000 --- a/library/std/src/sys/sync/thread_parking/darwin.rs +++ /dev/null @@ -1,132 +0,0 @@ -//! Thread parking for Darwin-based systems. -//! -//! Darwin actually has futex syscalls (`__ulock_wait`/`__ulock_wake`), but they -//! cannot be used in `std` because they are non-public (their use will lead to -//! rejection from the App Store). -//! -//! Therefore, we need to look for other synchronization primitives. Luckily, Darwin -//! supports semaphores, which allow us to implement the behaviour we need with -//! only one primitive (as opposed to a mutex-condvar pair). We use the semaphore -//! provided by libdispatch, as the underlying Mach semaphore is only dubiously -//! public. - -#![allow(non_camel_case_types)] - -use crate::pin::Pin; -use crate::sync::atomic::{ - AtomicI8, - Ordering::{Acquire, Release}, -}; -use crate::time::Duration; - -type dispatch_semaphore_t = *mut crate::ffi::c_void; -type dispatch_time_t = u64; - -const DISPATCH_TIME_NOW: dispatch_time_t = 0; -const DISPATCH_TIME_FOREVER: dispatch_time_t = !0; - -// Contained in libSystem.dylib, which is linked by default. -extern "C" { - fn dispatch_time(when: dispatch_time_t, delta: i64) -> dispatch_time_t; - fn dispatch_semaphore_create(val: isize) -> dispatch_semaphore_t; - fn dispatch_semaphore_wait(dsema: dispatch_semaphore_t, timeout: dispatch_time_t) -> isize; - fn dispatch_semaphore_signal(dsema: dispatch_semaphore_t) -> isize; - fn dispatch_release(object: *mut crate::ffi::c_void); -} - -const EMPTY: i8 = 0; -const NOTIFIED: i8 = 1; -const PARKED: i8 = -1; - -pub struct Parker { - semaphore: dispatch_semaphore_t, - state: AtomicI8, -} - -unsafe impl Sync for Parker {} -unsafe impl Send for Parker {} - -impl Parker { - pub unsafe fn new_in_place(parker: *mut Parker) { - let semaphore = dispatch_semaphore_create(0); - assert!( - !semaphore.is_null(), - "failed to create dispatch semaphore for thread synchronization" - ); - parker.write(Parker { semaphore, state: AtomicI8::new(EMPTY) }) - } - - // Does not need `Pin`, but other implementation do. - pub unsafe fn park(self: Pin<&Self>) { - // The semaphore counter must be zero at this point, because unparking - // threads will not actually increase it until we signalled that we - // are waiting. - - // Change NOTIFIED to EMPTY and EMPTY to PARKED. - if self.state.fetch_sub(1, Acquire) == NOTIFIED { - return; - } - - // Another thread may increase the semaphore counter from this point on. - // If it is faster than us, we will decrement it again immediately below. - // If we are faster, we wait. - - // Ensure that the semaphore counter has actually been decremented, even - // if the call timed out for some reason. - while dispatch_semaphore_wait(self.semaphore, DISPATCH_TIME_FOREVER) != 0 {} - - // At this point, the semaphore counter is zero again. - - // We were definitely woken up, so we don't need to check the state. - // Still, we need to reset the state using a swap to observe the state - // change with acquire ordering. - self.state.swap(EMPTY, Acquire); - } - - // Does not need `Pin`, but other implementation do. - pub unsafe fn park_timeout(self: Pin<&Self>, dur: Duration) { - if self.state.fetch_sub(1, Acquire) == NOTIFIED { - return; - } - - let nanos = dur.as_nanos().try_into().unwrap_or(i64::MAX); - let timeout = dispatch_time(DISPATCH_TIME_NOW, nanos); - - let timeout = dispatch_semaphore_wait(self.semaphore, timeout) != 0; - - let state = self.state.swap(EMPTY, Acquire); - if state == NOTIFIED && timeout { - // If the state was NOTIFIED but semaphore_wait returned without - // decrementing the count because of a timeout, it means another - // thread is about to call semaphore_signal. We must wait for that - // to happen to ensure the semaphore count is reset. - while dispatch_semaphore_wait(self.semaphore, DISPATCH_TIME_FOREVER) != 0 {} - } else { - // Either a timeout occurred and we reset the state before any thread - // tried to wake us up, or we were woken up and reset the state, - // making sure to observe the state change with acquire ordering. - // Either way, the semaphore counter is now zero again. - } - } - - // Does not need `Pin`, but other implementation do. - pub fn unpark(self: Pin<&Self>) { - let state = self.state.swap(NOTIFIED, Release); - if state == PARKED { - unsafe { - dispatch_semaphore_signal(self.semaphore); - } - } - } -} - -impl Drop for Parker { - fn drop(&mut self) { - // SAFETY: - // We always ensure that the semaphore count is reset, so this will - // never cause an exception. - unsafe { - dispatch_release(self.semaphore); - } - } -} diff --git a/library/std/src/sys/sync/thread_parking/futex.rs b/library/std/src/sys/sync/thread_parking/futex.rs deleted file mode 100644 index 588e7b27826f6..0000000000000 --- a/library/std/src/sys/sync/thread_parking/futex.rs +++ /dev/null @@ -1,97 +0,0 @@ -use crate::pin::Pin; -use crate::sync::atomic::AtomicU32; -use crate::sync::atomic::Ordering::{Acquire, Release}; -use crate::sys::futex::{futex_wait, futex_wake}; -use crate::time::Duration; - -const PARKED: u32 = u32::MAX; -const EMPTY: u32 = 0; -const NOTIFIED: u32 = 1; - -pub struct Parker { - state: AtomicU32, -} - -// Notes about memory ordering: -// -// Memory ordering is only relevant for the relative ordering of operations -// between different variables. Even Ordering::Relaxed guarantees a -// monotonic/consistent order when looking at just a single atomic variable. -// -// So, since this parker is just a single atomic variable, we only need to look -// at the ordering guarantees we need to provide to the 'outside world'. -// -// The only memory ordering guarantee that parking and unparking provide, is -// that things which happened before unpark() are visible on the thread -// returning from park() afterwards. Otherwise, it was effectively unparked -// before unpark() was called while still consuming the 'token'. -// -// In other words, unpark() needs to synchronize with the part of park() that -// consumes the token and returns. -// -// This is done with a release-acquire synchronization, by using -// Ordering::Release when writing NOTIFIED (the 'token') in unpark(), and using -// Ordering::Acquire when checking for this state in park(). -impl Parker { - /// Construct the futex parker. The UNIX parker implementation - /// requires this to happen in-place. - pub unsafe fn new_in_place(parker: *mut Parker) { - parker.write(Self { state: AtomicU32::new(EMPTY) }); - } - - // Assumes this is only called by the thread that owns the Parker, - // which means that `self.state != PARKED`. - pub unsafe fn park(self: Pin<&Self>) { - // Change NOTIFIED=>EMPTY or EMPTY=>PARKED, and directly return in the - // first case. - if self.state.fetch_sub(1, Acquire) == NOTIFIED { - return; - } - loop { - // Wait for something to happen, assuming it's still set to PARKED. - futex_wait(&self.state, PARKED, None); - // Change NOTIFIED=>EMPTY and return in that case. - if self.state.compare_exchange(NOTIFIED, EMPTY, Acquire, Acquire).is_ok() { - return; - } else { - // Spurious wake up. We loop to try again. - } - } - } - - // Assumes this is only called by the thread that owns the Parker, - // which means that `self.state != PARKED`. This implementation doesn't - // require `Pin`, but other implementations do. - pub unsafe fn park_timeout(self: Pin<&Self>, timeout: Duration) { - // Change NOTIFIED=>EMPTY or EMPTY=>PARKED, and directly return in the - // first case. - if self.state.fetch_sub(1, Acquire) == NOTIFIED { - return; - } - // Wait for something to happen, assuming it's still set to PARKED. - futex_wait(&self.state, PARKED, Some(timeout)); - // This is not just a store, because we need to establish a - // release-acquire ordering with unpark(). - if self.state.swap(EMPTY, Acquire) == NOTIFIED { - // Woke up because of unpark(). - } else { - // Timeout or spurious wake up. - // We return either way, because we can't easily tell if it was the - // timeout or not. - } - } - - // This implementation doesn't require `Pin`, but other implementations do. - #[inline] - pub fn unpark(self: Pin<&Self>) { - // Change PARKED=>NOTIFIED, EMPTY=>NOTIFIED, or NOTIFIED=>NOTIFIED, and - // wake the thread in the first case. - // - // Note that even NOTIFIED=>NOTIFIED results in a write. This is on - // purpose, to make sure every unpark() has a release-acquire ordering - // with park(). - if self.state.swap(NOTIFIED, Release) == PARKED { - futex_wake(&self.state); - } - } -} diff --git a/library/std/src/sys/sync/thread_parking/id.rs b/library/std/src/sys/sync/thread_parking/id.rs deleted file mode 100644 index 0466743966034..0000000000000 --- a/library/std/src/sys/sync/thread_parking/id.rs +++ /dev/null @@ -1,103 +0,0 @@ -//! Thread parking using thread ids. -//! -//! Some platforms (notably NetBSD) have thread parking primitives whose semantics -//! match those offered by `thread::park`, with the difference that the thread to -//! be unparked is referenced by a platform-specific thread id. Since the thread -//! parker is constructed before that id is known, an atomic state variable is used -//! to manage the park state and propagate the thread id. This also avoids platform -//! calls in the case where `unpark` is called before `park`. - -use crate::cell::UnsafeCell; -use crate::pin::Pin; -use crate::sync::atomic::{ - fence, AtomicI8, - Ordering::{Acquire, Relaxed, Release}, -}; -use crate::sys::thread_parking::{current, park, park_timeout, unpark, ThreadId}; -use crate::time::Duration; - -pub struct Parker { - state: AtomicI8, - tid: UnsafeCell>, -} - -const PARKED: i8 = -1; -const EMPTY: i8 = 0; -const NOTIFIED: i8 = 1; - -impl Parker { - pub fn new() -> Parker { - Parker { state: AtomicI8::new(EMPTY), tid: UnsafeCell::new(None) } - } - - /// Create a new thread parker. UNIX requires this to happen in-place. - pub unsafe fn new_in_place(parker: *mut Parker) { - parker.write(Parker::new()) - } - - /// # Safety - /// * must always be called from the same thread - /// * must be called before the state is set to PARKED - unsafe fn init_tid(&self) { - // The field is only ever written to from this thread, so we don't need - // synchronization to read it here. - if self.tid.get().read().is_none() { - // Because this point is only reached once, before the state is set - // to PARKED for the first time, the non-atomic write here can not - // conflict with reads by other threads. - self.tid.get().write(Some(current())); - // Ensure that the write can be observed by all threads reading the - // state. Synchronizes with the acquire barrier in `unpark`. - fence(Release); - } - } - - pub unsafe fn park(self: Pin<&Self>) { - self.init_tid(); - - // Changes NOTIFIED to EMPTY and EMPTY to PARKED. - let state = self.state.fetch_sub(1, Acquire); - if state == EMPTY { - // Loop to guard against spurious wakeups. - // The state must be reset with acquire ordering to ensure that all - // calls to `unpark` synchronize with this thread. - while self.state.compare_exchange(NOTIFIED, EMPTY, Acquire, Relaxed).is_err() { - park(self.state.as_ptr().addr()); - } - } - } - - pub unsafe fn park_timeout(self: Pin<&Self>, dur: Duration) { - self.init_tid(); - - let state = self.state.fetch_sub(1, Acquire).wrapping_sub(1); - if state == PARKED { - park_timeout(dur, self.state.as_ptr().addr()); - // Swap to ensure that we observe all state changes with acquire - // ordering. - self.state.swap(EMPTY, Acquire); - } - } - - pub fn unpark(self: Pin<&Self>) { - let state = self.state.swap(NOTIFIED, Release); - if state == PARKED { - // Synchronize with the release fence in `init_tid` to observe the - // write to `tid`. - fence(Acquire); - // # Safety - // The thread id is initialized before the state is set to `PARKED` - // for the first time and is not written to from that point on - // (negating the need for an atomic read). - let tid = unsafe { self.tid.get().read().unwrap_unchecked() }; - // It is possible that the waiting thread woke up because of a timeout - // and terminated before this call is made. This call then returns an - // error or wakes up an unrelated thread. The platform API and - // environment does allow this, however. - unpark(tid, self.state.as_ptr().addr()); - } - } -} - -unsafe impl Send for Parker {} -unsafe impl Sync for Parker {} diff --git a/library/std/src/sys/sync/thread_parking/mod.rs b/library/std/src/sys/sync/thread_parking/mod.rs deleted file mode 100644 index ed1a6437faaaf..0000000000000 --- a/library/std/src/sys/sync/thread_parking/mod.rs +++ /dev/null @@ -1,37 +0,0 @@ -cfg_if::cfg_if! { - if #[cfg(any( - target_os = "linux", - target_os = "android", - all(target_arch = "wasm32", target_feature = "atomics"), - target_os = "freebsd", - target_os = "openbsd", - target_os = "dragonfly", - target_os = "fuchsia", - target_os = "hermit", - ))] { - mod futex; - pub use futex::Parker; - } else if #[cfg(any( - target_os = "netbsd", - all(target_vendor = "fortanix", target_env = "sgx"), - target_os = "solid_asp3", - ))] { - mod id; - pub use id::Parker; - } else if #[cfg(target_os = "windows")] { - mod windows; - pub use windows::Parker; - } else if #[cfg(all(target_vendor = "apple", not(miri)))] { - mod darwin; - pub use darwin::Parker; - } else if #[cfg(target_os = "xous")] { - mod xous; - pub use xous::Parker; - } else if #[cfg(target_family = "unix")] { - mod pthread; - pub use pthread::Parker; - } else { - mod unsupported; - pub use unsupported::Parker; - } -} diff --git a/library/std/src/sys/sync/thread_parking/pthread.rs b/library/std/src/sys/sync/thread_parking/pthread.rs deleted file mode 100644 index fdac1096dbfc1..0000000000000 --- a/library/std/src/sys/sync/thread_parking/pthread.rs +++ /dev/null @@ -1,269 +0,0 @@ -//! Thread parking without `futex` using the `pthread` synchronization primitives. - -use crate::cell::UnsafeCell; -use crate::marker::PhantomPinned; -use crate::pin::Pin; -use crate::ptr::addr_of_mut; -use crate::sync::atomic::AtomicUsize; -use crate::sync::atomic::Ordering::{Acquire, Relaxed, Release}; -#[cfg(not(target_os = "nto"))] -use crate::sys::time::TIMESPEC_MAX; -#[cfg(target_os = "nto")] -use crate::sys::time::TIMESPEC_MAX_CAPPED; -use crate::time::Duration; - -const EMPTY: usize = 0; -const PARKED: usize = 1; -const NOTIFIED: usize = 2; - -unsafe fn lock(lock: *mut libc::pthread_mutex_t) { - let r = libc::pthread_mutex_lock(lock); - debug_assert_eq!(r, 0); -} - -unsafe fn unlock(lock: *mut libc::pthread_mutex_t) { - let r = libc::pthread_mutex_unlock(lock); - debug_assert_eq!(r, 0); -} - -unsafe fn notify_one(cond: *mut libc::pthread_cond_t) { - let r = libc::pthread_cond_signal(cond); - debug_assert_eq!(r, 0); -} - -unsafe fn wait(cond: *mut libc::pthread_cond_t, lock: *mut libc::pthread_mutex_t) { - let r = libc::pthread_cond_wait(cond, lock); - debug_assert_eq!(r, 0); -} - -unsafe fn wait_timeout( - cond: *mut libc::pthread_cond_t, - lock: *mut libc::pthread_mutex_t, - dur: Duration, -) { - // Use the system clock on systems that do not support pthread_condattr_setclock. - // This unfortunately results in problems when the system time changes. - #[cfg(any(target_os = "espidf", target_os = "horizon", target_vendor = "apple"))] - let (now, dur) = { - use crate::cmp::min; - use crate::sys::time::SystemTime; - - // OSX implementation of `pthread_cond_timedwait` is buggy - // with super long durations. When duration is greater than - // 0x100_0000_0000_0000 seconds, `pthread_cond_timedwait` - // in macOS Sierra return error 316. - // - // This program demonstrates the issue: - // https://gist.github.com/stepancheg/198db4623a20aad2ad7cddb8fda4a63c - // - // To work around this issue, and possible bugs of other OSes, timeout - // is clamped to 1000 years, which is allowable per the API of `park_timeout` - // because of spurious wakeups. - let dur = min(dur, Duration::from_secs(1000 * 365 * 86400)); - let now = SystemTime::now().t; - (now, dur) - }; - // Use the monotonic clock on other systems. - #[cfg(not(any(target_os = "espidf", target_os = "horizon", target_vendor = "apple")))] - let (now, dur) = { - use crate::sys::time::Timespec; - - (Timespec::now(libc::CLOCK_MONOTONIC), dur) - }; - - #[cfg(not(target_os = "nto"))] - let timeout = - now.checked_add_duration(&dur).and_then(|t| t.to_timespec()).unwrap_or(TIMESPEC_MAX); - #[cfg(target_os = "nto")] - let timeout = now - .checked_add_duration(&dur) - .and_then(|t| t.to_timespec_capped()) - .unwrap_or(TIMESPEC_MAX_CAPPED); - let r = libc::pthread_cond_timedwait(cond, lock, &timeout); - debug_assert!(r == libc::ETIMEDOUT || r == 0); -} - -pub struct Parker { - state: AtomicUsize, - lock: UnsafeCell, - cvar: UnsafeCell, - // The `pthread` primitives require a stable address, so make this struct `!Unpin`. - _pinned: PhantomPinned, -} - -impl Parker { - /// Construct the UNIX parker in-place. - /// - /// # Safety - /// The constructed parker must never be moved. - pub unsafe fn new_in_place(parker: *mut Parker) { - // Use the default mutex implementation to allow for simpler initialization. - // This could lead to undefined behaviour when deadlocking. This is avoided - // by not deadlocking. Note in particular the unlocking operation before any - // panic, as code after the panic could try to park again. - addr_of_mut!((*parker).state).write(AtomicUsize::new(EMPTY)); - addr_of_mut!((*parker).lock).write(UnsafeCell::new(libc::PTHREAD_MUTEX_INITIALIZER)); - - cfg_if::cfg_if! { - if #[cfg(any( - target_os = "l4re", - target_os = "android", - target_os = "redox", - target_os = "vita", - target_vendor = "apple", - ))] { - addr_of_mut!((*parker).cvar).write(UnsafeCell::new(libc::PTHREAD_COND_INITIALIZER)); - } else if #[cfg(any(target_os = "espidf", target_os = "horizon"))] { - let r = libc::pthread_cond_init(addr_of_mut!((*parker).cvar).cast(), crate::ptr::null()); - assert_eq!(r, 0); - } else { - use crate::mem::MaybeUninit; - let mut attr = MaybeUninit::::uninit(); - let r = libc::pthread_condattr_init(attr.as_mut_ptr()); - assert_eq!(r, 0); - let r = libc::pthread_condattr_setclock(attr.as_mut_ptr(), libc::CLOCK_MONOTONIC); - assert_eq!(r, 0); - let r = libc::pthread_cond_init(addr_of_mut!((*parker).cvar).cast(), attr.as_ptr()); - assert_eq!(r, 0); - let r = libc::pthread_condattr_destroy(attr.as_mut_ptr()); - assert_eq!(r, 0); - } - } - } - - // This implementation doesn't require `unsafe`, but other implementations - // may assume this is only called by the thread that owns the Parker. - // - // For memory ordering, see futex.rs - pub unsafe fn park(self: Pin<&Self>) { - // If we were previously notified then we consume this notification and - // return quickly. - if self.state.compare_exchange(NOTIFIED, EMPTY, Acquire, Relaxed).is_ok() { - return; - } - - // Otherwise we need to coordinate going to sleep - lock(self.lock.get()); - match self.state.compare_exchange(EMPTY, PARKED, Relaxed, Relaxed) { - Ok(_) => {} - Err(NOTIFIED) => { - // We must read here, even though we know it will be `NOTIFIED`. - // This is because `unpark` may have been called again since we read - // `NOTIFIED` in the `compare_exchange` above. We must perform an - // acquire operation that synchronizes with that `unpark` to observe - // any writes it made before the call to unpark. To do that we must - // read from the write it made to `state`. - let old = self.state.swap(EMPTY, Acquire); - - unlock(self.lock.get()); - - assert_eq!(old, NOTIFIED, "park state changed unexpectedly"); - return; - } // should consume this notification, so prohibit spurious wakeups in next park. - Err(_) => { - unlock(self.lock.get()); - - panic!("inconsistent park state") - } - } - - loop { - wait(self.cvar.get(), self.lock.get()); - - match self.state.compare_exchange(NOTIFIED, EMPTY, Acquire, Relaxed) { - Ok(_) => break, // got a notification - Err(_) => {} // spurious wakeup, go back to sleep - } - } - - unlock(self.lock.get()); - } - - // This implementation doesn't require `unsafe`, but other implementations - // may assume this is only called by the thread that owns the Parker. Use - // `Pin` to guarantee a stable address for the mutex and condition variable. - pub unsafe fn park_timeout(self: Pin<&Self>, dur: Duration) { - // Like `park` above we have a fast path for an already-notified thread, and - // afterwards we start coordinating for a sleep. - // return quickly. - if self.state.compare_exchange(NOTIFIED, EMPTY, Acquire, Relaxed).is_ok() { - return; - } - - lock(self.lock.get()); - match self.state.compare_exchange(EMPTY, PARKED, Relaxed, Relaxed) { - Ok(_) => {} - Err(NOTIFIED) => { - // We must read again here, see `park`. - let old = self.state.swap(EMPTY, Acquire); - unlock(self.lock.get()); - - assert_eq!(old, NOTIFIED, "park state changed unexpectedly"); - return; - } // should consume this notification, so prohibit spurious wakeups in next park. - Err(_) => { - unlock(self.lock.get()); - panic!("inconsistent park_timeout state") - } - } - - // Wait with a timeout, and if we spuriously wake up or otherwise wake up - // from a notification we just want to unconditionally set the state back to - // empty, either consuming a notification or un-flagging ourselves as - // parked. - wait_timeout(self.cvar.get(), self.lock.get(), dur); - - match self.state.swap(EMPTY, Acquire) { - NOTIFIED => unlock(self.lock.get()), // got a notification, hurray! - PARKED => unlock(self.lock.get()), // no notification, alas - n => { - unlock(self.lock.get()); - panic!("inconsistent park_timeout state: {n}") - } - } - } - - pub fn unpark(self: Pin<&Self>) { - // To ensure the unparked thread will observe any writes we made - // before this call, we must perform a release operation that `park` - // can synchronize with. To do that we must write `NOTIFIED` even if - // `state` is already `NOTIFIED`. That is why this must be a swap - // rather than a compare-and-swap that returns if it reads `NOTIFIED` - // on failure. - match self.state.swap(NOTIFIED, Release) { - EMPTY => return, // no one was waiting - NOTIFIED => return, // already unparked - PARKED => {} // gotta go wake someone up - _ => panic!("inconsistent state in unpark"), - } - - // There is a period between when the parked thread sets `state` to - // `PARKED` (or last checked `state` in the case of a spurious wake - // up) and when it actually waits on `cvar`. If we were to notify - // during this period it would be ignored and then when the parked - // thread went to sleep it would never wake up. Fortunately, it has - // `lock` locked at this stage so we can acquire `lock` to wait until - // it is ready to receive the notification. - // - // Releasing `lock` before the call to `notify_one` means that when the - // parked thread wakes it doesn't get woken only to have to wait for us - // to release `lock`. - unsafe { - lock(self.lock.get()); - unlock(self.lock.get()); - notify_one(self.cvar.get()); - } - } -} - -impl Drop for Parker { - fn drop(&mut self) { - unsafe { - libc::pthread_cond_destroy(self.cvar.get_mut()); - libc::pthread_mutex_destroy(self.lock.get_mut()); - } - } -} - -unsafe impl Sync for Parker {} -unsafe impl Send for Parker {} diff --git a/library/std/src/sys/sync/thread_parking/unsupported.rs b/library/std/src/sys/sync/thread_parking/unsupported.rs deleted file mode 100644 index 197078bb18673..0000000000000 --- a/library/std/src/sys/sync/thread_parking/unsupported.rs +++ /dev/null @@ -1,11 +0,0 @@ -use crate::pin::Pin; -use crate::time::Duration; - -pub struct Parker {} - -impl Parker { - pub unsafe fn new_in_place(_parker: *mut Parker) {} - pub unsafe fn park(self: Pin<&Self>) {} - pub unsafe fn park_timeout(self: Pin<&Self>, _dur: Duration) {} - pub fn unpark(self: Pin<&Self>) {} -} diff --git a/library/std/src/sys/sync/thread_parking/windows.rs b/library/std/src/sys/sync/thread_parking/windows.rs deleted file mode 100644 index 4b8102d505a1f..0000000000000 --- a/library/std/src/sys/sync/thread_parking/windows.rs +++ /dev/null @@ -1,278 +0,0 @@ -// Thread parker implementation for Windows. -// -// This uses WaitOnAddress and WakeByAddressSingle if available (Windows 8+). -// This modern API is exactly the same as the futex syscalls the Linux thread -// parker uses. When These APIs are available, the implementation of this -// thread parker matches the Linux thread parker exactly. -// -// However, when the modern API is not available, this implementation falls -// back to NT Keyed Events, which are similar, but have some important -// differences. These are available since Windows XP. -// -// WaitOnAddress first checks the state of the thread parker to make sure it no -// WakeByAddressSingle calls can be missed between updating the parker state -// and calling the function. -// -// NtWaitForKeyedEvent does not have this option, and unconditionally blocks -// without checking the parker state first. Instead, NtReleaseKeyedEvent -// (unlike WakeByAddressSingle) *blocks* until it woke up a thread waiting for -// it by NtWaitForKeyedEvent. This way, we can be sure no events are missed, -// but we need to be careful not to block unpark() if park_timeout() was woken -// up by a timeout instead of unpark(). -// -// Unlike WaitOnAddress, NtWaitForKeyedEvent/NtReleaseKeyedEvent operate on a -// HANDLE (created with NtCreateKeyedEvent). This means that we can be sure -// a successfully awoken park() was awoken by unpark() and not a -// NtReleaseKeyedEvent call from some other code, as these events are not only -// matched by the key (address of the parker (state)), but also by this HANDLE. -// We lazily allocate this handle the first time it is needed. -// -// The fast path (calling park() after unpark() was already called) and the -// possible states are the same for both implementations. This is used here to -// make sure the fast path does not even check which API to use, but can return -// right away, independent of the used API. Only the slow paths (which will -// actually block/wake a thread) check which API is available and have -// different implementations. -// -// Unfortunately, NT Keyed Events are an undocumented Windows API. However: -// - This API is relatively simple with obvious behaviour, and there are -// several (unofficial) articles documenting the details. [1] -// - `parking_lot` has been using this API for years (on Windows versions -// before Windows 8). [2] Many big projects extensively use parking_lot, -// such as servo and the Rust compiler itself. -// - It is the underlying API used by Windows SRW locks and Windows critical -// sections. [3] [4] -// - The source code of the implementations of Wine, ReactOs, and Windows XP -// are available and match the expected behaviour. -// - The main risk with an undocumented API is that it might change in the -// future. But since we only use it for older versions of Windows, that's not -// a problem. -// - Even if these functions do not block or wake as we expect (which is -// unlikely, see all previous points), this implementation would still be -// memory safe. The NT Keyed Events API is only used to sleep/block in the -// right place. -// -// [1]: http://www.locklessinc.com/articles/keyed_events/ -// [2]: https://github.com/Amanieu/parking_lot/commit/43abbc964e -// [3]: https://docs.microsoft.com/en-us/archive/msdn-magazine/2012/november/windows-with-c-the-evolution-of-synchronization-in-windows-and-c -// [4]: Windows Internals, Part 1, ISBN 9780735671300 - -use crate::pin::Pin; -use crate::sync::atomic::{ - AtomicI8, - Ordering::{Acquire, Release}, -}; -use crate::sys::{c, dur2timeout}; -use crate::time::Duration; - -pub struct Parker { - state: AtomicI8, -} - -const PARKED: i8 = -1; -const EMPTY: i8 = 0; -const NOTIFIED: i8 = 1; - -// Notes about memory ordering: -// -// Memory ordering is only relevant for the relative ordering of operations -// between different variables. Even Ordering::Relaxed guarantees a -// monotonic/consistent order when looking at just a single atomic variable. -// -// So, since this parker is just a single atomic variable, we only need to look -// at the ordering guarantees we need to provide to the 'outside world'. -// -// The only memory ordering guarantee that parking and unparking provide, is -// that things which happened before unpark() are visible on the thread -// returning from park() afterwards. Otherwise, it was effectively unparked -// before unpark() was called while still consuming the 'token'. -// -// In other words, unpark() needs to synchronize with the part of park() that -// consumes the token and returns. -// -// This is done with a release-acquire synchronization, by using -// Ordering::Release when writing NOTIFIED (the 'token') in unpark(), and using -// Ordering::Acquire when reading this state in park() after waking up. -impl Parker { - /// Construct the Windows parker. The UNIX parker implementation - /// requires this to happen in-place. - pub unsafe fn new_in_place(parker: *mut Parker) { - parker.write(Self { state: AtomicI8::new(EMPTY) }); - } - - // Assumes this is only called by the thread that owns the Parker, - // which means that `self.state != PARKED`. This implementation doesn't require `Pin`, - // but other implementations do. - pub unsafe fn park(self: Pin<&Self>) { - // Change NOTIFIED=>EMPTY or EMPTY=>PARKED, and directly return in the - // first case. - if self.state.fetch_sub(1, Acquire) == NOTIFIED { - return; - } - - #[cfg(target_vendor = "win7")] - if c::WaitOnAddress::option().is_none() { - return keyed_events::park(self); - } - - loop { - // Wait for something to happen, assuming it's still set to PARKED. - c::WaitOnAddress(self.ptr(), &PARKED as *const _ as c::LPVOID, 1, c::INFINITE); - // Change NOTIFIED=>EMPTY but leave PARKED alone. - if self.state.compare_exchange(NOTIFIED, EMPTY, Acquire, Acquire).is_ok() { - // Actually woken up by unpark(). - return; - } else { - // Spurious wake up. We loop to try again. - } - } - } - - // Assumes this is only called by the thread that owns the Parker, - // which means that `self.state != PARKED`. This implementation doesn't require `Pin`, - // but other implementations do. - pub unsafe fn park_timeout(self: Pin<&Self>, timeout: Duration) { - // Change NOTIFIED=>EMPTY or EMPTY=>PARKED, and directly return in the - // first case. - if self.state.fetch_sub(1, Acquire) == NOTIFIED { - return; - } - - #[cfg(target_vendor = "win7")] - if c::WaitOnAddress::option().is_none() { - return keyed_events::park_timeout(self, timeout); - } - - // Wait for something to happen, assuming it's still set to PARKED. - c::WaitOnAddress(self.ptr(), &PARKED as *const _ as c::LPVOID, 1, dur2timeout(timeout)); - // Set the state back to EMPTY (from either PARKED or NOTIFIED). - // Note that we don't just write EMPTY, but use swap() to also - // include an acquire-ordered read to synchronize with unpark()'s - // release-ordered write. - if self.state.swap(EMPTY, Acquire) == NOTIFIED { - // Actually woken up by unpark(). - } else { - // Timeout or spurious wake up. - // We return either way, because we can't easily tell if it was the - // timeout or not. - } - } - - // This implementation doesn't require `Pin`, but other implementations do. - pub fn unpark(self: Pin<&Self>) { - // Change PARKED=>NOTIFIED, EMPTY=>NOTIFIED, or NOTIFIED=>NOTIFIED, and - // wake the thread in the first case. - // - // Note that even NOTIFIED=>NOTIFIED results in a write. This is on - // purpose, to make sure every unpark() has a release-acquire ordering - // with park(). - if self.state.swap(NOTIFIED, Release) == PARKED { - unsafe { - #[cfg(target_vendor = "win7")] - if c::WakeByAddressSingle::option().is_none() { - return keyed_events::unpark(self); - } - c::WakeByAddressSingle(self.ptr()); - } - } - } - - fn ptr(&self) -> c::LPVOID { - core::ptr::addr_of!(self.state) as c::LPVOID - } -} - -#[cfg(target_vendor = "win7")] -mod keyed_events { - use super::{Parker, EMPTY, NOTIFIED}; - use crate::sys::c; - use core::pin::Pin; - use core::ptr; - use core::sync::atomic::{ - AtomicPtr, - Ordering::{Acquire, Relaxed}, - }; - use core::time::Duration; - - pub unsafe fn park(parker: Pin<&Parker>) { - // Wait for unpark() to produce this event. - c::NtWaitForKeyedEvent(keyed_event_handle(), parker.ptr(), 0, ptr::null_mut()); - // Set the state back to EMPTY (from either PARKED or NOTIFIED). - // Note that we don't just write EMPTY, but use swap() to also - // include an acquire-ordered read to synchronize with unpark()'s - // release-ordered write. - parker.state.swap(EMPTY, Acquire); - return; - } - pub unsafe fn park_timeout(parker: Pin<&Parker>, timeout: Duration) { - // Need to wait for unpark() using NtWaitForKeyedEvent. - let handle = keyed_event_handle(); - - // NtWaitForKeyedEvent uses a unit of 100ns, and uses negative - // values to indicate a relative time on the monotonic clock. - // This is documented here for the underlying KeWaitForSingleObject function: - // https://docs.microsoft.com/en-us/windows-hardware/drivers/ddi/wdm/nf-wdm-kewaitforsingleobject - let mut timeout = match i64::try_from((timeout.as_nanos() + 99) / 100) { - Ok(t) => -t, - Err(_) => i64::MIN, - }; - - // Wait for unpark() to produce this event. - let unparked = - c::NtWaitForKeyedEvent(handle, parker.ptr(), 0, &mut timeout) == c::STATUS_SUCCESS; - - // Set the state back to EMPTY (from either PARKED or NOTIFIED). - let prev_state = parker.state.swap(EMPTY, Acquire); - - if !unparked && prev_state == NOTIFIED { - // We were awoken by a timeout, not by unpark(), but the state - // was set to NOTIFIED, which means we *just* missed an - // unpark(), which is now blocked on us to wait for it. - // Wait for it to consume the event and unblock that thread. - c::NtWaitForKeyedEvent(handle, parker.ptr(), 0, ptr::null_mut()); - } - } - pub unsafe fn unpark(parker: Pin<&Parker>) { - // If we run NtReleaseKeyedEvent before the waiting thread runs - // NtWaitForKeyedEvent, this (shortly) blocks until we can wake it up. - // If the waiting thread wakes up before we run NtReleaseKeyedEvent - // (e.g. due to a timeout), this blocks until we do wake up a thread. - // To prevent this thread from blocking indefinitely in that case, - // park_impl() will, after seeing the state set to NOTIFIED after - // waking up, call NtWaitForKeyedEvent again to unblock us. - c::NtReleaseKeyedEvent(keyed_event_handle(), parker.ptr(), 0, ptr::null_mut()); - } - - fn keyed_event_handle() -> c::HANDLE { - const INVALID: c::HANDLE = ptr::without_provenance_mut(!0); - static HANDLE: AtomicPtr = AtomicPtr::new(INVALID); - match HANDLE.load(Relaxed) { - INVALID => { - let mut handle = c::INVALID_HANDLE_VALUE; - unsafe { - match c::NtCreateKeyedEvent( - &mut handle, - c::GENERIC_READ | c::GENERIC_WRITE, - ptr::null_mut(), - 0, - ) { - c::STATUS_SUCCESS => {} - r => panic!("Unable to create keyed event handle: error {r}"), - } - } - match HANDLE.compare_exchange(INVALID, handle, Relaxed, Relaxed) { - Ok(_) => handle, - Err(h) => { - // Lost the race to another thread initializing HANDLE before we did. - // Closing our handle and using theirs instead. - unsafe { - c::CloseHandle(handle); - } - h - } - } - } - handle => handle, - } - } -} diff --git a/library/std/src/sys/sync/thread_parking/xous.rs b/library/std/src/sys/sync/thread_parking/xous.rs deleted file mode 100644 index 0bd0462d77d35..0000000000000 --- a/library/std/src/sys/sync/thread_parking/xous.rs +++ /dev/null @@ -1,112 +0,0 @@ -use crate::os::xous::ffi::{blocking_scalar, scalar}; -use crate::os::xous::services::{ticktimer_server, TicktimerScalar}; -use crate::pin::Pin; -use crate::ptr; -use crate::sync::atomic::{ - AtomicI8, - Ordering::{Acquire, Release}, -}; -use crate::time::Duration; - -const NOTIFIED: i8 = 1; -const EMPTY: i8 = 0; -const PARKED: i8 = -1; - -pub struct Parker { - state: AtomicI8, -} - -impl Parker { - pub unsafe fn new_in_place(parker: *mut Parker) { - unsafe { parker.write(Parker { state: AtomicI8::new(EMPTY) }) } - } - - fn index(&self) -> usize { - ptr::from_ref(self).addr() - } - - pub unsafe fn park(self: Pin<&Self>) { - // Change NOTIFIED to EMPTY and EMPTY to PARKED. - let state = self.state.fetch_sub(1, Acquire); - if state == NOTIFIED { - // The state has gone from NOTIFIED (1) to EMPTY (0) - return; - } - // The state has gone from EMPTY (0) to PARKED (-1) - assert!(state == EMPTY); - - // The state is now PARKED (-1). Wait until the `unpark` wakes us up. - blocking_scalar( - ticktimer_server(), - TicktimerScalar::WaitForCondition(self.index(), 0).into(), - ) - .expect("failed to send WaitForCondition command"); - - let state = self.state.swap(EMPTY, Acquire); - assert!(state == NOTIFIED || state == PARKED); - } - - pub unsafe fn park_timeout(self: Pin<&Self>, timeout: Duration) { - // Change NOTIFIED to EMPTY and EMPTY to PARKED. - let state = self.state.fetch_sub(1, Acquire); - if state == NOTIFIED { - // The state has gone from NOTIFIED (1) to EMPTY (0) - return; - } - // The state has gone from EMPTY (0) to PARKED (-1) - assert!(state == EMPTY); - - // A value of zero indicates an indefinite wait. Clamp the number of - // milliseconds to the allowed range. - let millis = usize::max(timeout.as_millis().try_into().unwrap_or(usize::MAX), 1); - - // The state is now PARKED (-1). Wait until the `unpark` wakes us up, - // or things time out. - let _was_timeout = blocking_scalar( - ticktimer_server(), - TicktimerScalar::WaitForCondition(self.index(), millis).into(), - ) - .expect("failed to send WaitForCondition command")[0] - != 0; - - let state = self.state.swap(EMPTY, Acquire); - assert!(state == PARKED || state == NOTIFIED); - } - - pub fn unpark(self: Pin<&Self>) { - // If the state is already `NOTIFIED`, then another thread has - // indicated it wants to wake up the target thread. - // - // If the state is `EMPTY` then there is nothing to wake up, and - // the target thread will immediately exit from `park()` the - // next time that function is called. - if self.state.swap(NOTIFIED, Release) != PARKED { - return; - } - - // The thread is parked, wake it up. Keep trying until we wake something up. - // This will happen when the `NotifyCondition` call returns the fact that - // 1 condition was notified. - // Alternately, keep going until the state is seen as `EMPTY`, indicating - // the thread woke up and kept going. This can happen when the Park - // times out before we can send the NotifyCondition message. - while blocking_scalar( - ticktimer_server(), - TicktimerScalar::NotifyCondition(self.index(), 1).into(), - ) - .expect("failed to send NotifyCondition command")[0] - == 0 - && self.state.load(Acquire) != EMPTY - { - // The target thread hasn't yet hit the `WaitForCondition` call. - // Yield to let the target thread run some more. - crate::thread::yield_now(); - } - } -} - -impl Drop for Parker { - fn drop(&mut self) { - scalar(ticktimer_server(), TicktimerScalar::FreeCondition(self.index()).into()).ok(); - } -} diff --git a/library/std/src/sys/thread_local/fast_local/eager.rs b/library/std/src/sys/thread_local/fast_local/eager.rs deleted file mode 100644 index c2bc580530ba4..0000000000000 --- a/library/std/src/sys/thread_local/fast_local/eager.rs +++ /dev/null @@ -1,82 +0,0 @@ -use crate::cell::{Cell, UnsafeCell}; -use crate::ptr::{self, drop_in_place}; -use crate::sys::thread_local::abort_on_dtor_unwind; -use crate::sys::thread_local_dtor::register_dtor; - -#[derive(Clone, Copy)] -enum State { - Initial, - Alive, - Destroyed, -} - -#[allow(missing_debug_implementations)] -pub struct Storage { - state: Cell, - val: UnsafeCell, -} - -impl Storage { - pub const fn new(val: T) -> Storage { - Storage { state: Cell::new(State::Initial), val: UnsafeCell::new(val) } - } - - /// Get a reference to the TLS value. If the TLS variable has been destroyed, - /// `None` is returned. - /// - /// # Safety - /// * The `self` reference must remain valid until the TLS destructor has been - /// run. - /// * The returned reference may only be used until thread destruction occurs - /// and may not be used after reentrant initialization has occurred. - /// - // FIXME(#110897): return NonNull instead of lying about the lifetime. - #[inline] - pub unsafe fn get(&self) -> Option<&'static T> { - match self.state.get() { - // SAFETY: as the state is not `Destroyed`, the value cannot have - // been destroyed yet. The reference fulfills the terms outlined - // above. - State::Alive => unsafe { Some(&*self.val.get()) }, - State::Destroyed => None, - State::Initial => unsafe { self.initialize() }, - } - } - - #[cold] - unsafe fn initialize(&self) -> Option<&'static T> { - // Register the destructor - - // SAFETY: - // * the destructor will be called at thread destruction. - // * the caller guarantees that `self` will be valid until that time. - unsafe { - register_dtor(ptr::from_ref(self).cast_mut().cast(), destroy::); - } - self.state.set(State::Alive); - // SAFETY: as the state is not `Destroyed`, the value cannot have - // been destroyed yet. The reference fulfills the terms outlined - // above. - unsafe { Some(&*self.val.get()) } - } -} - -/// Transition an `Alive` TLS variable into the `Destroyed` state, dropping its -/// value. -/// -/// # Safety -/// * Must only be called at thread destruction. -/// * `ptr` must point to an instance of `Storage` with `Alive` state and be -/// valid for accessing that instance. -unsafe extern "C" fn destroy(ptr: *mut u8) { - // Print a nice abort message if a panic occurs. - abort_on_dtor_unwind(|| { - let storage = unsafe { &*(ptr as *const Storage) }; - // Update the state before running the destructor as it may attempt to - // access the variable. - storage.state.set(State::Destroyed); - unsafe { - drop_in_place(storage.val.get()); - } - }) -} diff --git a/library/std/src/sys/thread_local/fast_local/lazy.rs b/library/std/src/sys/thread_local/fast_local/lazy.rs deleted file mode 100644 index c2e9a17145468..0000000000000 --- a/library/std/src/sys/thread_local/fast_local/lazy.rs +++ /dev/null @@ -1,121 +0,0 @@ -use crate::cell::UnsafeCell; -use crate::hint::unreachable_unchecked; -use crate::ptr; -use crate::sys::thread_local::abort_on_dtor_unwind; -use crate::sys::thread_local_dtor::register_dtor; - -pub unsafe trait DestroyedState: Sized { - fn register_dtor(s: &Storage); -} - -unsafe impl DestroyedState for ! { - fn register_dtor(_: &Storage) {} -} - -unsafe impl DestroyedState for () { - fn register_dtor(s: &Storage) { - unsafe { - register_dtor(ptr::from_ref(s).cast_mut().cast(), destroy::); - } - } -} - -enum State { - Initial, - Alive(T), - Destroyed(D), -} - -#[allow(missing_debug_implementations)] -pub struct Storage { - state: UnsafeCell>, -} - -impl Storage -where - D: DestroyedState, -{ - pub const fn new() -> Storage { - Storage { state: UnsafeCell::new(State::Initial) } - } - - /// Get a reference to the TLS value, potentially initializing it with the - /// provided parameters. If the TLS variable has been destroyed, `None` is - /// returned. - /// - /// # Safety - /// * The `self` reference must remain valid until the TLS destructor is run, - /// at which point the returned reference is invalidated. - /// * The returned reference may only be used until thread destruction occurs - /// and may not be used after reentrant initialization has occurred. - /// - // FIXME(#110897): return NonNull instead of lying about the lifetime. - #[inline] - pub unsafe fn get_or_init( - &self, - i: Option<&mut Option>, - f: impl FnOnce() -> T, - ) -> Option<&'static T> { - // SAFETY: - // No mutable reference to the inner value exists outside the calls to - // `replace`. The lifetime of the returned reference fulfills the terms - // outlined above. - let state = unsafe { &*self.state.get() }; - match state { - State::Alive(v) => Some(v), - State::Destroyed(_) => None, - State::Initial => unsafe { self.initialize(i, f) }, - } - } - - #[cold] - unsafe fn initialize( - &self, - i: Option<&mut Option>, - f: impl FnOnce() -> T, - ) -> Option<&'static T> { - // Perform initialization - - let v = i.and_then(Option::take).unwrap_or_else(f); - - // SAFETY: - // If references to the inner value exist, they were created in `f` - // and are invalidated here. The caller promises to never use them - // after this. - let old = unsafe { self.state.get().replace(State::Alive(v)) }; - match old { - // If the variable is not being recursively initialized, register - // the destructor. This might be a noop if the value does not need - // destruction. - State::Initial => D::register_dtor(self), - // Else, drop the old value. This might be changed to a panic. - val => drop(val), - } - - // SAFETY: - // Initialization was completed and the state was set to `Alive`, so the - // reference fulfills the terms outlined above. - unsafe { - let State::Alive(v) = &*self.state.get() else { unreachable_unchecked() }; - Some(v) - } - } -} - -/// Transition an `Alive` TLS variable into the `Destroyed` state, dropping its -/// value. -/// -/// # Safety -/// * Must only be called at thread destruction. -/// * `ptr` must point to an instance of `Storage` and be valid for -/// accessing that instance. -unsafe extern "C" fn destroy(ptr: *mut u8) { - // Print a nice abort message if a panic occurs. - abort_on_dtor_unwind(|| { - let storage = unsafe { &*(ptr as *const Storage) }; - // Update the state before running the destructor as it may attempt to - // access the variable. - let val = unsafe { storage.state.get().replace(State::Destroyed(())) }; - drop(val); - }) -} diff --git a/library/std/src/sys/thread_local/fast_local/mod.rs b/library/std/src/sys/thread_local/fast_local/mod.rs deleted file mode 100644 index 25379071cb7a6..0000000000000 --- a/library/std/src/sys/thread_local/fast_local/mod.rs +++ /dev/null @@ -1,122 +0,0 @@ -//! Thread local support for platforms with native TLS. -//! -//! To achieve the best performance, we choose from four different types for -//! the TLS variable, depending from the method of initialization used (`const` -//! or lazy) and the drop requirements of the stored type: -//! -//! | | `Drop` | `!Drop` | -//! |--------:|:--------------------:|:-------------------:| -//! | `const` | `EagerStorage` | `T` | -//! | lazy | `LazyStorage` | `LazyStorage` | -//! -//! For `const` initialization and `!Drop` types, we simply use `T` directly, -//! but for other situations, we implement a state machine to handle -//! initialization of the variable and its destructor and destruction. -//! Upon accessing the TLS variable, the current state is compared: -//! -//! 1. If the state is `Initial`, initialize the storage, transition the state -//! to `Alive` and (if applicable) register the destructor, and return a -//! reference to the value. -//! 2. If the state is `Alive`, initialization was previously completed, so -//! return a reference to the value. -//! 3. If the state is `Destroyed`, the destructor has been run already, so -//! return [`None`]. -//! -//! The TLS destructor sets the state to `Destroyed` and drops the current value. -//! -//! To simplify the code, we make `LazyStorage` generic over the destroyed state -//! and use the `!` type (never type) as type parameter for `!Drop` types. This -//! eliminates the `Destroyed` state for these values, which can allow more niche -//! optimizations to occur for the `State` enum. For `Drop` types, `()` is used. - -#![deny(unsafe_op_in_unsafe_fn)] - -mod eager; -mod lazy; - -pub use eager::Storage as EagerStorage; -pub use lazy::Storage as LazyStorage; - -#[doc(hidden)] -#[allow_internal_unstable( - thread_local_internals, - cfg_target_thread_local, - thread_local, - never_type -)] -#[allow_internal_unsafe] -#[unstable(feature = "thread_local_internals", issue = "none")] -#[rustc_macro_transparency = "semitransparent"] -pub macro thread_local_inner { - // used to generate the `LocalKey` value for const-initialized thread locals - (@key $t:ty, const $init:expr) => {{ - const __INIT: $t = $init; - - #[inline] - #[deny(unsafe_op_in_unsafe_fn)] - unsafe fn __getit( - _init: $crate::option::Option<&mut $crate::option::Option<$t>>, - ) -> $crate::option::Option<&'static $t> { - use $crate::thread::local_impl::EagerStorage; - use $crate::mem::needs_drop; - use $crate::ptr::addr_of; - - if needs_drop::<$t>() { - #[thread_local] - static VAL: EagerStorage<$t> = EagerStorage::new(__INIT); - unsafe { - VAL.get() - } - } else { - #[thread_local] - static VAL: $t = __INIT; - unsafe { - $crate::option::Option::Some(&*addr_of!(VAL)) - } - } - } - - unsafe { - $crate::thread::LocalKey::new(__getit) - } - }}, - - // used to generate the `LocalKey` value for `thread_local!` - (@key $t:ty, $init:expr) => {{ - #[inline] - fn __init() -> $t { - $init - } - - #[inline] - #[deny(unsafe_op_in_unsafe_fn)] - unsafe fn __getit( - init: $crate::option::Option<&mut $crate::option::Option<$t>>, - ) -> $crate::option::Option<&'static $t> { - use $crate::thread::local_impl::LazyStorage; - use $crate::mem::needs_drop; - - if needs_drop::<$t>() { - #[thread_local] - static VAL: LazyStorage<$t, ()> = LazyStorage::new(); - unsafe { - VAL.get_or_init(init, __init) - } - } else { - #[thread_local] - static VAL: LazyStorage<$t, !> = LazyStorage::new(); - unsafe { - VAL.get_or_init(init, __init) - } - } - } - - unsafe { - $crate::thread::LocalKey::new(__getit) - } - }}, - ($(#[$attr:meta])* $vis:vis $name:ident, $t:ty, $($init:tt)*) => { - $(#[$attr])* $vis const $name: $crate::thread::LocalKey<$t> = - $crate::thread::local_impl::thread_local_inner!(@key $t, $($init)*); - }, -} diff --git a/library/std/src/sys/thread_local/mod.rs b/library/std/src/sys/thread_local/mod.rs deleted file mode 100644 index 0a78a1a1cf02d..0000000000000 --- a/library/std/src/sys/thread_local/mod.rs +++ /dev/null @@ -1,48 +0,0 @@ -#![unstable(feature = "thread_local_internals", reason = "should not be necessary", issue = "none")] -#![cfg_attr(test, allow(unused))] - -// There are three thread-local implementations: "static", "fast", "OS". -// The "OS" thread local key type is accessed via platform-specific API calls and is slow, while the -// "fast" key type is accessed via code generated via LLVM, where TLS keys are set up by the linker. -// "static" is for single-threaded platforms where a global static is sufficient. - -cfg_if::cfg_if! { - if #[cfg(any(all(target_family = "wasm", not(target_feature = "atomics")), target_os = "uefi"))] { - #[doc(hidden)] - mod static_local; - #[doc(hidden)] - pub use static_local::{EagerStorage, LazyStorage, thread_local_inner}; - } else if #[cfg(target_thread_local)] { - #[doc(hidden)] - mod fast_local; - #[doc(hidden)] - pub use fast_local::{EagerStorage, LazyStorage, thread_local_inner}; - } else { - #[doc(hidden)] - mod os_local; - #[doc(hidden)] - pub use os_local::{Key, thread_local_inner}; - } -} - -/// Run a callback in a scenario which must not unwind (such as a `extern "C" -/// fn` declared in a user crate). If the callback unwinds anyway, then -/// `rtabort` with a message about thread local panicking on drop. -#[inline] -#[allow(dead_code)] -fn abort_on_dtor_unwind(f: impl FnOnce()) { - // Using a guard like this is lower cost. - let guard = DtorUnwindGuard; - f(); - core::mem::forget(guard); - - struct DtorUnwindGuard; - impl Drop for DtorUnwindGuard { - #[inline] - fn drop(&mut self) { - // This is not terribly descriptive, but it doesn't need to be as we'll - // already have printed a panic message at this point. - rtabort!("thread local panicked on drop"); - } - } -} diff --git a/library/std/src/sys/thread_local/os_local.rs b/library/std/src/sys/thread_local/os_local.rs deleted file mode 100644 index d6ddbb78a9c86..0000000000000 --- a/library/std/src/sys/thread_local/os_local.rs +++ /dev/null @@ -1,143 +0,0 @@ -use super::abort_on_dtor_unwind; -use crate::cell::Cell; -use crate::marker::PhantomData; -use crate::ptr; -use crate::sys_common::thread_local_key::StaticKey as OsKey; - -#[doc(hidden)] -#[allow_internal_unstable(thread_local_internals)] -#[allow_internal_unsafe] -#[unstable(feature = "thread_local_internals", issue = "none")] -#[rustc_macro_transparency = "semitransparent"] -pub macro thread_local_inner { - // used to generate the `LocalKey` value for const-initialized thread locals - (@key $t:ty, const $init:expr) => { - $crate::thread::local_impl::thread_local_inner!(@key $t, { const INIT_EXPR: $t = $init; INIT_EXPR }) - }, - - // used to generate the `LocalKey` value for `thread_local!` - (@key $t:ty, $init:expr) => { - { - #[inline] - fn __init() -> $t { $init } - - // `#[inline] does not work on windows-gnu due to linking errors around dllimports. - // See https://github.com/rust-lang/rust/issues/109797. - #[cfg_attr(not(windows), inline)] - unsafe fn __getit( - init: $crate::option::Option<&mut $crate::option::Option<$t>>, - ) -> $crate::option::Option<&'static $t> { - use $crate::thread::local_impl::Key; - - static __KEY: Key<$t> = Key::new(); - unsafe { - __KEY.get(init, __init) - } - } - - unsafe { - $crate::thread::LocalKey::new(__getit) - } - } - }, - ($(#[$attr:meta])* $vis:vis $name:ident, $t:ty, $($init:tt)*) => { - $(#[$attr])* $vis const $name: $crate::thread::LocalKey<$t> = - $crate::thread::local_impl::thread_local_inner!(@key $t, $($init)*); - }, -} - -/// Use a regular global static to store this key; the state provided will then be -/// thread-local. -#[allow(missing_debug_implementations)] -pub struct Key { - os: OsKey, - marker: PhantomData>, -} - -unsafe impl Sync for Key {} - -struct Value { - value: T, - key: &'static Key, -} - -impl Key { - #[rustc_const_unstable(feature = "thread_local_internals", issue = "none")] - pub const fn new() -> Key { - Key { os: OsKey::new(Some(destroy_value::)), marker: PhantomData } - } - - /// Get the value associated with this key, initializating it if necessary. - /// - /// # Safety - /// * the returned reference must not be used after recursive initialization - /// or thread destruction occurs. - pub unsafe fn get( - &'static self, - i: Option<&mut Option>, - f: impl FnOnce() -> T, - ) -> Option<&'static T> { - // SAFETY: (FIXME: get should actually be safe) - let ptr = unsafe { self.os.get() as *mut Value }; - if ptr.addr() > 1 { - // SAFETY: the check ensured the pointer is safe (its destructor - // is not running) + it is coming from a trusted source (self). - unsafe { Some(&(*ptr).value) } - } else { - // SAFETY: At this point we are sure we have no value and so - // initializing (or trying to) is safe. - unsafe { self.try_initialize(ptr, i, f) } - } - } - - unsafe fn try_initialize( - &'static self, - ptr: *mut Value, - i: Option<&mut Option>, - f: impl FnOnce() -> T, - ) -> Option<&'static T> { - if ptr.addr() == 1 { - // destructor is running - return None; - } - - let value = i.and_then(Option::take).unwrap_or_else(f); - let ptr = Box::into_raw(Box::new(Value { value, key: self })); - // SAFETY: (FIXME: get should actually be safe) - let old = unsafe { self.os.get() as *mut Value }; - // SAFETY: `ptr` is a correct pointer that can be destroyed by the key destructor. - unsafe { - self.os.set(ptr as *mut u8); - } - if !old.is_null() { - // If the variable was recursively initialized, drop the old value. - // SAFETY: We cannot be inside a `LocalKey::with` scope, as the - // initializer has already returned and the next scope only starts - // after we return the pointer. Therefore, there can be no references - // to the old value. - drop(unsafe { Box::from_raw(old) }); - } - - // SAFETY: We just created this value above. - unsafe { Some(&(*ptr).value) } - } -} - -unsafe extern "C" fn destroy_value(ptr: *mut u8) { - // SAFETY: - // - // The OS TLS ensures that this key contains a null value when this - // destructor starts to run. We set it back to a sentinel value of 1 to - // ensure that any future calls to `get` for this thread will return - // `None`. - // - // Note that to prevent an infinite loop we reset it back to null right - // before we return from the destructor ourselves. - abort_on_dtor_unwind(|| { - let ptr = unsafe { Box::from_raw(ptr as *mut Value) }; - let key = ptr.key; - unsafe { key.os.set(ptr::without_provenance_mut(1)) }; - drop(ptr); - unsafe { key.os.set(ptr::null_mut()) }; - }); -} diff --git a/library/std/src/sys/thread_local/static_local.rs b/library/std/src/sys/thread_local/static_local.rs deleted file mode 100644 index 6beda2e718802..0000000000000 --- a/library/std/src/sys/thread_local/static_local.rs +++ /dev/null @@ -1,112 +0,0 @@ -//! On some targets like wasm there's no threads, so no need to generate -//! thread locals and we can instead just use plain statics! - -use crate::cell::UnsafeCell; - -#[doc(hidden)] -#[allow_internal_unstable(thread_local_internals)] -#[allow_internal_unsafe] -#[unstable(feature = "thread_local_internals", issue = "none")] -#[rustc_macro_transparency = "semitransparent"] -pub macro thread_local_inner { - // used to generate the `LocalKey` value for const-initialized thread locals - (@key $t:ty, const $init:expr) => {{ - const __INIT: $t = $init; - - #[inline] - #[deny(unsafe_op_in_unsafe_fn)] - unsafe fn __getit( - _init: $crate::option::Option<&mut $crate::option::Option<$t>>, - ) -> $crate::option::Option<&'static $t> { - use $crate::thread::local_impl::EagerStorage; - - static VAL: EagerStorage<$t> = EagerStorage { value: __INIT }; - $crate::option::Option::Some(&VAL.value) - } - - unsafe { - $crate::thread::LocalKey::new(__getit) - } - }}, - - // used to generate the `LocalKey` value for `thread_local!` - (@key $t:ty, $init:expr) => {{ - #[inline] - fn __init() -> $t { $init } - - #[inline] - #[deny(unsafe_op_in_unsafe_fn)] - unsafe fn __getit( - init: $crate::option::Option<&mut $crate::option::Option<$t>>, - ) -> $crate::option::Option<&'static $t> { - use $crate::thread::local_impl::LazyStorage; - - static VAL: LazyStorage<$t> = LazyStorage::new(); - unsafe { $crate::option::Option::Some(VAL.get(init, __init)) } - } - - unsafe { - $crate::thread::LocalKey::new(__getit) - } - }}, - ($(#[$attr:meta])* $vis:vis $name:ident, $t:ty, $($init:tt)*) => { - $(#[$attr])* $vis const $name: $crate::thread::LocalKey<$t> = - $crate::thread::local_impl::thread_local_inner!(@key $t, $($init)*); - }, -} - -#[allow(missing_debug_implementations)] -pub struct EagerStorage { - pub value: T, -} - -// SAFETY: the target doesn't have threads. -unsafe impl Sync for EagerStorage {} - -#[allow(missing_debug_implementations)] -pub struct LazyStorage { - value: UnsafeCell>, -} - -impl LazyStorage { - pub const fn new() -> LazyStorage { - LazyStorage { value: UnsafeCell::new(None) } - } - - /// Gets a reference to the contained value, initializing it if necessary. - /// - /// # Safety - /// The returned reference may not be used after reentrant initialization has occurred. - #[inline] - pub unsafe fn get( - &'static self, - i: Option<&mut Option>, - f: impl FnOnce() -> T, - ) -> &'static T { - let value = unsafe { &*self.value.get() }; - match value { - Some(v) => v, - None => self.initialize(i, f), - } - } - - #[cold] - unsafe fn initialize( - &'static self, - i: Option<&mut Option>, - f: impl FnOnce() -> T, - ) -> &'static T { - let value = i.and_then(Option::take).unwrap_or_else(f); - // Destroy the old value, after updating the TLS variable as the - // destructor might reference it. - // FIXME(#110897): maybe panic on recursive initialization. - unsafe { - self.value.get().replace(Some(value)); - } - // SAFETY: we just set this to `Some`. - unsafe { (*self.value.get()).as_ref().unwrap_unchecked() } - } -} - -// SAFETY: the target doesn't have threads. -unsafe impl Sync for LazyStorage {} diff --git a/library/std/src/sys_common/backtrace.rs b/library/std/src/sys_common/backtrace.rs deleted file mode 100644 index 67711dbd5bc75..0000000000000 --- a/library/std/src/sys_common/backtrace.rs +++ /dev/null @@ -1,227 +0,0 @@ -use crate::backtrace_rs::{self, BacktraceFmt, BytesOrWideString, PrintFmt}; -use crate::borrow::Cow; -/// Common code for printing the backtrace in the same way across the different -/// supported platforms. -use crate::env; -use crate::fmt; -use crate::io; -use crate::io::prelude::*; -use crate::path::{self, Path, PathBuf}; -use crate::sync::{Mutex, PoisonError}; - -/// Max number of frames to print. -const MAX_NB_FRAMES: usize = 100; - -pub fn lock() -> impl Drop { - static LOCK: Mutex<()> = Mutex::new(()); - LOCK.lock().unwrap_or_else(PoisonError::into_inner) -} - -/// Prints the current backtrace. -pub fn print(w: &mut dyn Write, format: PrintFmt) -> io::Result<()> { - // There are issues currently linking libbacktrace into tests, and in - // general during std's own unit tests we're not testing this path. In - // test mode immediately return here to optimize away any references to the - // libbacktrace symbols - if cfg!(test) { - return Ok(()); - } - - // Use a lock to prevent mixed output in multithreading context. - // Some platforms also requires it, like `SymFromAddr` on Windows. - unsafe { - let _lock = lock(); - _print(w, format) - } -} - -unsafe fn _print(w: &mut dyn Write, format: PrintFmt) -> io::Result<()> { - struct DisplayBacktrace { - format: PrintFmt, - } - impl fmt::Display for DisplayBacktrace { - fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { - unsafe { _print_fmt(fmt, self.format) } - } - } - write!(w, "{}", DisplayBacktrace { format }) -} - -unsafe fn _print_fmt(fmt: &mut fmt::Formatter<'_>, print_fmt: PrintFmt) -> fmt::Result { - // Always 'fail' to get the cwd when running under Miri - - // this allows Miri to display backtraces in isolation mode - let cwd = if !cfg!(miri) { env::current_dir().ok() } else { None }; - - let mut print_path = move |fmt: &mut fmt::Formatter<'_>, bows: BytesOrWideString<'_>| { - output_filename(fmt, bows, print_fmt, cwd.as_ref()) - }; - writeln!(fmt, "stack backtrace:")?; - let mut bt_fmt = BacktraceFmt::new(fmt, print_fmt, &mut print_path); - bt_fmt.add_context()?; - let mut idx = 0; - let mut res = Ok(()); - let mut omitted_count: usize = 0; - let mut first_omit = true; - // Start immediately if we're not using a short backtrace. - let mut start = print_fmt != PrintFmt::Short; - set_image_base(); - backtrace_rs::trace_unsynchronized(|frame| { - if print_fmt == PrintFmt::Short && idx > MAX_NB_FRAMES { - return false; - } - - let mut hit = false; - backtrace_rs::resolve_frame_unsynchronized(frame, |symbol| { - hit = true; - - // Any frames between `__rust_begin_short_backtrace` and `__rust_end_short_backtrace` - // are omitted from the backtrace in short mode, `__rust_end_short_backtrace` will be - // called before the panic hook, so we won't ignore any frames if there is no - // invoke of `__rust_begin_short_backtrace`. - if print_fmt == PrintFmt::Short { - if let Some(sym) = symbol.name().and_then(|s| s.as_str()) { - if start && sym.contains("__rust_begin_short_backtrace") { - start = false; - return; - } - if sym.contains("__rust_end_short_backtrace") { - start = true; - return; - } - if !start { - omitted_count += 1; - } - } - } - - if start { - if omitted_count > 0 { - debug_assert!(print_fmt == PrintFmt::Short); - // only print the message between the middle of frames - if !first_omit { - let _ = writeln!( - bt_fmt.formatter(), - " [... omitted {} frame{} ...]", - omitted_count, - if omitted_count > 1 { "s" } else { "" } - ); - } - first_omit = false; - omitted_count = 0; - } - res = bt_fmt.frame().symbol(frame, symbol); - } - }); - #[cfg(target_os = "nto")] - if libc::__my_thread_exit as *mut libc::c_void == frame.ip() { - if !hit && start { - use crate::backtrace_rs::SymbolName; - res = bt_fmt.frame().print_raw( - frame.ip(), - Some(SymbolName::new("__my_thread_exit".as_bytes())), - None, - None, - ); - } - return false; - } - if !hit && start { - res = bt_fmt.frame().print_raw(frame.ip(), None, None, None); - } - - idx += 1; - res.is_ok() - }); - res?; - bt_fmt.finish()?; - if print_fmt == PrintFmt::Short { - writeln!( - fmt, - "note: Some details are omitted, \ - run with `RUST_BACKTRACE=full` for a verbose backtrace." - )?; - } - Ok(()) -} - -/// Fixed frame used to clean the backtrace with `RUST_BACKTRACE=1`. Note that -/// this is only inline(never) when backtraces in std are enabled, otherwise -/// it's fine to optimize away. -#[cfg_attr(feature = "backtrace", inline(never))] -pub fn __rust_begin_short_backtrace(f: F) -> T -where - F: FnOnce() -> T, -{ - let result = f(); - - // prevent this frame from being tail-call optimised away - crate::hint::black_box(()); - - result -} - -/// Fixed frame used to clean the backtrace with `RUST_BACKTRACE=1`. Note that -/// this is only inline(never) when backtraces in std are enabled, otherwise -/// it's fine to optimize away. -#[cfg_attr(feature = "backtrace", inline(never))] -pub fn __rust_end_short_backtrace(f: F) -> T -where - F: FnOnce() -> T, -{ - let result = f(); - - // prevent this frame from being tail-call optimised away - crate::hint::black_box(()); - - result -} - -/// Prints the filename of the backtrace frame. -/// -/// See also `output`. -pub fn output_filename( - fmt: &mut fmt::Formatter<'_>, - bows: BytesOrWideString<'_>, - print_fmt: PrintFmt, - cwd: Option<&PathBuf>, -) -> fmt::Result { - let file: Cow<'_, Path> = match bows { - #[cfg(unix)] - BytesOrWideString::Bytes(bytes) => { - use crate::os::unix::prelude::*; - Path::new(crate::ffi::OsStr::from_bytes(bytes)).into() - } - #[cfg(not(unix))] - BytesOrWideString::Bytes(bytes) => { - Path::new(crate::str::from_utf8(bytes).unwrap_or("")).into() - } - #[cfg(windows)] - BytesOrWideString::Wide(wide) => { - use crate::os::windows::prelude::*; - Cow::Owned(crate::ffi::OsString::from_wide(wide).into()) - } - #[cfg(not(windows))] - BytesOrWideString::Wide(_wide) => Path::new("").into(), - }; - if print_fmt == PrintFmt::Short && file.is_absolute() { - if let Some(cwd) = cwd { - if let Ok(stripped) = file.strip_prefix(&cwd) { - if let Some(s) = stripped.to_str() { - return write!(fmt, ".{}{s}", path::MAIN_SEPARATOR); - } - } - } - } - fmt::Display::fmt(&file.display(), fmt) -} - -#[cfg(all(target_vendor = "fortanix", target_env = "sgx"))] -pub fn set_image_base() { - let image_base = crate::os::fortanix_sgx::mem::image_base(); - backtrace_rs::set_image_base(crate::ptr::without_provenance_mut(image_base as _)); -} - -#[cfg(not(all(target_vendor = "fortanix", target_env = "sgx")))] -pub fn set_image_base() { - // nothing to do for platforms other than SGX -} diff --git a/library/std/src/sys_common/fs.rs b/library/std/src/sys_common/fs.rs deleted file mode 100644 index 617ac52e51ca8..0000000000000 --- a/library/std/src/sys_common/fs.rs +++ /dev/null @@ -1,51 +0,0 @@ -#![allow(dead_code)] // not used on all platforms - -use crate::fs; -use crate::io::{self, Error, ErrorKind}; -use crate::path::Path; - -pub(crate) const NOT_FILE_ERROR: Error = io::const_io_error!( - ErrorKind::InvalidInput, - "the source path is neither a regular file nor a symlink to a regular file", -); - -pub fn copy(from: &Path, to: &Path) -> io::Result { - let mut reader = fs::File::open(from)?; - let metadata = reader.metadata()?; - - if !metadata.is_file() { - return Err(NOT_FILE_ERROR); - } - - let mut writer = fs::File::create(to)?; - let perm = metadata.permissions(); - - let ret = io::copy(&mut reader, &mut writer)?; - writer.set_permissions(perm)?; - Ok(ret) -} - -pub fn remove_dir_all(path: &Path) -> io::Result<()> { - let filetype = fs::symlink_metadata(path)?.file_type(); - if filetype.is_symlink() { fs::remove_file(path) } else { remove_dir_all_recursive(path) } -} - -fn remove_dir_all_recursive(path: &Path) -> io::Result<()> { - for child in fs::read_dir(path)? { - let child = child?; - if child.file_type()?.is_dir() { - remove_dir_all_recursive(&child.path())?; - } else { - fs::remove_file(&child.path())?; - } - } - fs::remove_dir(path) -} - -pub fn try_exists(path: &Path) -> io::Result { - match fs::metadata(path) { - Ok(_) => Ok(true), - Err(error) if error.kind() == io::ErrorKind::NotFound => Ok(false), - Err(error) => Err(error), - } -} diff --git a/library/std/src/sys_common/io.rs b/library/std/src/sys_common/io.rs deleted file mode 100644 index 4a42ff3c618ce..0000000000000 --- a/library/std/src/sys_common/io.rs +++ /dev/null @@ -1,50 +0,0 @@ -// Bare metal platforms usually have very small amounts of RAM -// (in the order of hundreds of KB) -pub const DEFAULT_BUF_SIZE: usize = if cfg!(target_os = "espidf") { 512 } else { 8 * 1024 }; - -#[cfg(test)] -#[allow(dead_code)] // not used on emscripten -pub mod test { - use crate::env; - use crate::fs; - use crate::path::{Path, PathBuf}; - use crate::thread; - use rand::RngCore; - - pub struct TempDir(PathBuf); - - impl TempDir { - pub fn join(&self, path: &str) -> PathBuf { - let TempDir(ref p) = *self; - p.join(path) - } - - pub fn path(&self) -> &Path { - let TempDir(ref p) = *self; - p - } - } - - impl Drop for TempDir { - fn drop(&mut self) { - // Gee, seeing how we're testing the fs module I sure hope that we - // at least implement this correctly! - let TempDir(ref p) = *self; - let result = fs::remove_dir_all(p); - // Avoid panicking while panicking as this causes the process to - // immediately abort, without displaying test results. - if !thread::panicking() { - result.unwrap(); - } - } - } - - #[track_caller] // for `test_rng` - pub fn tmpdir() -> TempDir { - let p = env::temp_dir(); - let mut r = crate::test_helpers::test_rng(); - let ret = p.join(&format!("rust-{}", r.next_u32())); - fs::create_dir(&ret).unwrap(); - TempDir(ret) - } -} diff --git a/library/std/src/sys_common/lazy_box.rs b/library/std/src/sys_common/lazy_box.rs deleted file mode 100644 index 63c3316bdeb28..0000000000000 --- a/library/std/src/sys_common/lazy_box.rs +++ /dev/null @@ -1,90 +0,0 @@ -#![allow(dead_code)] // Only used on some platforms. - -// This is used to wrap pthread {Mutex, Condvar, RwLock} in. - -use crate::marker::PhantomData; -use crate::ops::{Deref, DerefMut}; -use crate::ptr::null_mut; -use crate::sync::atomic::{ - AtomicPtr, - Ordering::{AcqRel, Acquire}, -}; - -pub(crate) struct LazyBox { - ptr: AtomicPtr, - _phantom: PhantomData, -} - -pub(crate) trait LazyInit { - /// This is called before the box is allocated, to provide the value to - /// move into the new box. - /// - /// It might be called more than once per LazyBox, as multiple threads - /// might race to initialize it concurrently, each constructing and initializing - /// their own box. All but one of them will be passed to `cancel_init` right after. - fn init() -> Box; - - /// Any surplus boxes from `init()` that lost the initialization race - /// are passed to this function for disposal. - /// - /// The default implementation calls destroy(). - fn cancel_init(x: Box) { - Self::destroy(x); - } - - /// This is called to destroy a used box. - /// - /// The default implementation just drops it. - fn destroy(_: Box) {} -} - -impl LazyBox { - #[inline] - pub const fn new() -> Self { - Self { ptr: AtomicPtr::new(null_mut()), _phantom: PhantomData } - } - - #[inline] - fn get_pointer(&self) -> *mut T { - let ptr = self.ptr.load(Acquire); - if ptr.is_null() { self.initialize() } else { ptr } - } - - #[cold] - fn initialize(&self) -> *mut T { - let new_ptr = Box::into_raw(T::init()); - match self.ptr.compare_exchange(null_mut(), new_ptr, AcqRel, Acquire) { - Ok(_) => new_ptr, - Err(ptr) => { - // Lost the race to another thread. - // Drop the box we created, and use the one from the other thread instead. - T::cancel_init(unsafe { Box::from_raw(new_ptr) }); - ptr - } - } - } -} - -impl Deref for LazyBox { - type Target = T; - #[inline] - fn deref(&self) -> &T { - unsafe { &*self.get_pointer() } - } -} - -impl DerefMut for LazyBox { - #[inline] - fn deref_mut(&mut self) -> &mut T { - unsafe { &mut *self.get_pointer() } - } -} - -impl Drop for LazyBox { - fn drop(&mut self) { - let ptr = *self.ptr.get_mut(); - if !ptr.is_null() { - T::destroy(unsafe { Box::from_raw(ptr) }); - } - } -} diff --git a/library/std/src/sys_common/mod.rs b/library/std/src/sys_common/mod.rs deleted file mode 100644 index 3a38ba1100f01..0000000000000 --- a/library/std/src/sys_common/mod.rs +++ /dev/null @@ -1,92 +0,0 @@ -//! Platform-independent platform abstraction -//! -//! This is the platform-independent portion of the standard library's -//! platform abstraction layer, whereas `std::sys` is the -//! platform-specific portion. -//! -//! The relationship between `std::sys_common`, `std::sys` and the -//! rest of `std` is complex, with dependencies going in all -//! directions: `std` depending on `sys_common`, `sys_common` -//! depending on `sys`, and `sys` depending on `sys_common` and `std`. -//! This is because `sys_common` not only contains platform-independent code, -//! but also code that is shared between the different platforms in `sys`. -//! Ideally all that shared code should be moved to `sys::common`, -//! and the dependencies between `std`, `sys_common` and `sys` all would form a dag. -//! Progress on this is tracked in #84187. - -#![allow(missing_docs)] -#![allow(missing_debug_implementations)] - -#[cfg(test)] -mod tests; - -pub mod backtrace; -pub mod fs; -pub mod io; -pub mod lazy_box; -pub mod process; -pub mod thread_local_dtor; -pub mod wstr; -pub mod wtf8; - -cfg_if::cfg_if! { - if #[cfg(target_os = "windows")] { - pub use crate::sys::thread_local_key; - } else { - pub mod thread_local_key; - } -} - -cfg_if::cfg_if! { - if #[cfg(any( - all(unix, not(target_os = "l4re")), - windows, - target_os = "hermit", - target_os = "solid_asp3" - ))] { - pub mod net; - } else { - pub use crate::sys::net; - } -} - -// common error constructors - -/// A trait for viewing representations from std types -#[doc(hidden)] -#[allow(dead_code)] // not used on all platforms -pub trait AsInner { - fn as_inner(&self) -> &Inner; -} - -/// A trait for viewing representations from std types -#[doc(hidden)] -#[allow(dead_code)] // not used on all platforms -pub trait AsInnerMut { - fn as_inner_mut(&mut self) -> &mut Inner; -} - -/// A trait for extracting representations from std types -#[doc(hidden)] -pub trait IntoInner { - fn into_inner(self) -> Inner; -} - -/// A trait for creating std types from internal representations -#[doc(hidden)] -pub trait FromInner { - fn from_inner(inner: Inner) -> Self; -} - -// Computes (value*numer)/denom without overflow, as long as both -// (numer*denom) and the overall result fit into i64 (which is the case -// for our time conversions). -#[allow(dead_code)] // not used on all platforms -pub fn mul_div_u64(value: u64, numer: u64, denom: u64) -> u64 { - let q = value / denom; - let r = value % denom; - // Decompose value as (value/denom*denom + value%denom), - // substitute into (value*numer)/denom and simplify. - // r < denom, so (denom*numer) is the upper bound of (r*numer) - q * numer + r * numer / denom -} diff --git a/library/std/src/sys_common/net.rs b/library/std/src/sys_common/net.rs deleted file mode 100644 index 95ca67fc2e0b6..0000000000000 --- a/library/std/src/sys_common/net.rs +++ /dev/null @@ -1,763 +0,0 @@ -#[cfg(test)] -mod tests; - -use crate::cmp; -use crate::fmt; -use crate::io::{self, BorrowedCursor, ErrorKind, IoSlice, IoSliceMut}; -use crate::mem; -use crate::net::{Ipv4Addr, Ipv6Addr, Shutdown, SocketAddr}; -use crate::ptr; -use crate::sys::common::small_c_string::run_with_cstr; -use crate::sys::net::netc as c; -use crate::sys::net::{cvt, cvt_gai, cvt_r, init, wrlen_t, Socket}; -use crate::sys_common::{AsInner, FromInner, IntoInner}; -use crate::time::Duration; - -use crate::ffi::{c_int, c_void}; - -cfg_if::cfg_if! { - if #[cfg(any( - target_os = "dragonfly", - target_os = "freebsd", - target_os = "openbsd", - target_os = "netbsd", - target_os = "illumos", - target_os = "solaris", - target_os = "haiku", - target_os = "l4re", - target_os = "nto", - target_vendor = "apple", - ))] { - use crate::sys::net::netc::IPV6_JOIN_GROUP as IPV6_ADD_MEMBERSHIP; - use crate::sys::net::netc::IPV6_LEAVE_GROUP as IPV6_DROP_MEMBERSHIP; - } else { - use crate::sys::net::netc::IPV6_ADD_MEMBERSHIP; - use crate::sys::net::netc::IPV6_DROP_MEMBERSHIP; - } -} - -cfg_if::cfg_if! { - if #[cfg(any( - target_os = "linux", target_os = "android", - target_os = "hurd", - target_os = "dragonfly", target_os = "freebsd", - target_os = "openbsd", target_os = "netbsd", - target_os = "haiku", target_os = "nto"))] { - use libc::MSG_NOSIGNAL; - } else { - const MSG_NOSIGNAL: c_int = 0x0; - } -} - -cfg_if::cfg_if! { - if #[cfg(any( - target_os = "dragonfly", target_os = "freebsd", - target_os = "openbsd", target_os = "netbsd", - target_os = "solaris", target_os = "illumos", - target_os = "nto"))] { - use crate::ffi::c_uchar; - type IpV4MultiCastType = c_uchar; - } else { - type IpV4MultiCastType = c_int; - } -} - -//////////////////////////////////////////////////////////////////////////////// -// sockaddr and misc bindings -//////////////////////////////////////////////////////////////////////////////// - -pub fn setsockopt( - sock: &Socket, - level: c_int, - option_name: c_int, - option_value: T, -) -> io::Result<()> { - unsafe { - cvt(c::setsockopt( - sock.as_raw(), - level, - option_name, - core::ptr::addr_of!(option_value) as *const _, - mem::size_of::() as c::socklen_t, - ))?; - Ok(()) - } -} - -pub fn getsockopt(sock: &Socket, level: c_int, option_name: c_int) -> io::Result { - unsafe { - let mut option_value: T = mem::zeroed(); - let mut option_len = mem::size_of::() as c::socklen_t; - cvt(c::getsockopt( - sock.as_raw(), - level, - option_name, - core::ptr::addr_of_mut!(option_value) as *mut _, - &mut option_len, - ))?; - Ok(option_value) - } -} - -fn sockname(f: F) -> io::Result -where - F: FnOnce(*mut c::sockaddr, *mut c::socklen_t) -> c_int, -{ - unsafe { - let mut storage: c::sockaddr_storage = mem::zeroed(); - let mut len = mem::size_of_val(&storage) as c::socklen_t; - cvt(f(core::ptr::addr_of_mut!(storage) as *mut _, &mut len))?; - sockaddr_to_addr(&storage, len as usize) - } -} - -pub fn sockaddr_to_addr(storage: &c::sockaddr_storage, len: usize) -> io::Result { - match storage.ss_family as c_int { - c::AF_INET => { - assert!(len >= mem::size_of::()); - Ok(SocketAddr::V4(FromInner::from_inner(unsafe { - *(storage as *const _ as *const c::sockaddr_in) - }))) - } - c::AF_INET6 => { - assert!(len >= mem::size_of::()); - Ok(SocketAddr::V6(FromInner::from_inner(unsafe { - *(storage as *const _ as *const c::sockaddr_in6) - }))) - } - _ => Err(io::const_io_error!(ErrorKind::InvalidInput, "invalid argument")), - } -} - -#[cfg(target_os = "android")] -fn to_ipv6mr_interface(value: u32) -> c_int { - value as c_int -} - -#[cfg(not(target_os = "android"))] -fn to_ipv6mr_interface(value: u32) -> crate::ffi::c_uint { - value as crate::ffi::c_uint -} - -//////////////////////////////////////////////////////////////////////////////// -// get_host_addresses -//////////////////////////////////////////////////////////////////////////////// - -pub struct LookupHost { - original: *mut c::addrinfo, - cur: *mut c::addrinfo, - port: u16, -} - -impl LookupHost { - pub fn port(&self) -> u16 { - self.port - } -} - -impl Iterator for LookupHost { - type Item = SocketAddr; - fn next(&mut self) -> Option { - loop { - unsafe { - let cur = self.cur.as_ref()?; - self.cur = cur.ai_next; - match sockaddr_to_addr(mem::transmute(cur.ai_addr), cur.ai_addrlen as usize) { - Ok(addr) => return Some(addr), - Err(_) => continue, - } - } - } - } -} - -unsafe impl Sync for LookupHost {} -unsafe impl Send for LookupHost {} - -impl Drop for LookupHost { - fn drop(&mut self) { - unsafe { c::freeaddrinfo(self.original) } - } -} - -impl TryFrom<&str> for LookupHost { - type Error = io::Error; - - fn try_from(s: &str) -> io::Result { - macro_rules! try_opt { - ($e:expr, $msg:expr) => { - match $e { - Some(r) => r, - None => return Err(io::const_io_error!(io::ErrorKind::InvalidInput, $msg)), - } - }; - } - - // split the string by ':' and convert the second part to u16 - let (host, port_str) = try_opt!(s.rsplit_once(':'), "invalid socket address"); - let port: u16 = try_opt!(port_str.parse().ok(), "invalid port value"); - (host, port).try_into() - } -} - -impl<'a> TryFrom<(&'a str, u16)> for LookupHost { - type Error = io::Error; - - fn try_from((host, port): (&'a str, u16)) -> io::Result { - init(); - - run_with_cstr(host.as_bytes(), &|c_host| { - let mut hints: c::addrinfo = unsafe { mem::zeroed() }; - hints.ai_socktype = c::SOCK_STREAM; - let mut res = ptr::null_mut(); - unsafe { - cvt_gai(c::getaddrinfo(c_host.as_ptr(), ptr::null(), &hints, &mut res)) - .map(|_| LookupHost { original: res, cur: res, port }) - } - }) - } -} - -//////////////////////////////////////////////////////////////////////////////// -// TCP streams -//////////////////////////////////////////////////////////////////////////////// - -pub struct TcpStream { - inner: Socket, -} - -impl TcpStream { - pub fn connect(addr: io::Result<&SocketAddr>) -> io::Result { - let addr = addr?; - - init(); - - let sock = Socket::new(addr, c::SOCK_STREAM)?; - sock.connect(addr)?; - Ok(TcpStream { inner: sock }) - } - - pub fn connect_timeout(addr: &SocketAddr, timeout: Duration) -> io::Result { - init(); - - let sock = Socket::new(addr, c::SOCK_STREAM)?; - sock.connect_timeout(addr, timeout)?; - Ok(TcpStream { inner: sock }) - } - - #[inline] - pub fn socket(&self) -> &Socket { - &self.inner - } - - pub fn into_socket(self) -> Socket { - self.inner - } - - pub fn set_read_timeout(&self, dur: Option) -> io::Result<()> { - self.inner.set_timeout(dur, c::SO_RCVTIMEO) - } - - pub fn set_write_timeout(&self, dur: Option) -> io::Result<()> { - self.inner.set_timeout(dur, c::SO_SNDTIMEO) - } - - pub fn read_timeout(&self) -> io::Result> { - self.inner.timeout(c::SO_RCVTIMEO) - } - - pub fn write_timeout(&self) -> io::Result> { - self.inner.timeout(c::SO_SNDTIMEO) - } - - pub fn peek(&self, buf: &mut [u8]) -> io::Result { - self.inner.peek(buf) - } - - pub fn read(&self, buf: &mut [u8]) -> io::Result { - self.inner.read(buf) - } - - pub fn read_buf(&self, buf: BorrowedCursor<'_>) -> io::Result<()> { - self.inner.read_buf(buf) - } - - pub fn read_vectored(&self, bufs: &mut [IoSliceMut<'_>]) -> io::Result { - self.inner.read_vectored(bufs) - } - - #[inline] - pub fn is_read_vectored(&self) -> bool { - self.inner.is_read_vectored() - } - - pub fn write(&self, buf: &[u8]) -> io::Result { - let len = cmp::min(buf.len(), ::MAX as usize) as wrlen_t; - let ret = cvt(unsafe { - c::send(self.inner.as_raw(), buf.as_ptr() as *const c_void, len, MSG_NOSIGNAL) - })?; - Ok(ret as usize) - } - - pub fn write_vectored(&self, bufs: &[IoSlice<'_>]) -> io::Result { - self.inner.write_vectored(bufs) - } - - #[inline] - pub fn is_write_vectored(&self) -> bool { - self.inner.is_write_vectored() - } - - pub fn peer_addr(&self) -> io::Result { - sockname(|buf, len| unsafe { c::getpeername(self.inner.as_raw(), buf, len) }) - } - - pub fn socket_addr(&self) -> io::Result { - sockname(|buf, len| unsafe { c::getsockname(self.inner.as_raw(), buf, len) }) - } - - pub fn shutdown(&self, how: Shutdown) -> io::Result<()> { - self.inner.shutdown(how) - } - - pub fn duplicate(&self) -> io::Result { - self.inner.duplicate().map(|s| TcpStream { inner: s }) - } - - pub fn set_linger(&self, linger: Option) -> io::Result<()> { - self.inner.set_linger(linger) - } - - pub fn linger(&self) -> io::Result> { - self.inner.linger() - } - - pub fn set_nodelay(&self, nodelay: bool) -> io::Result<()> { - self.inner.set_nodelay(nodelay) - } - - pub fn nodelay(&self) -> io::Result { - self.inner.nodelay() - } - - pub fn set_ttl(&self, ttl: u32) -> io::Result<()> { - setsockopt(&self.inner, c::IPPROTO_IP, c::IP_TTL, ttl as c_int) - } - - pub fn ttl(&self) -> io::Result { - let raw: c_int = getsockopt(&self.inner, c::IPPROTO_IP, c::IP_TTL)?; - Ok(raw as u32) - } - - pub fn take_error(&self) -> io::Result> { - self.inner.take_error() - } - - pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> { - self.inner.set_nonblocking(nonblocking) - } -} - -impl AsInner for TcpStream { - #[inline] - fn as_inner(&self) -> &Socket { - &self.inner - } -} - -impl FromInner for TcpStream { - fn from_inner(socket: Socket) -> TcpStream { - TcpStream { inner: socket } - } -} - -impl fmt::Debug for TcpStream { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let mut res = f.debug_struct("TcpStream"); - - if let Ok(addr) = self.socket_addr() { - res.field("addr", &addr); - } - - if let Ok(peer) = self.peer_addr() { - res.field("peer", &peer); - } - - let name = if cfg!(windows) { "socket" } else { "fd" }; - res.field(name, &self.inner.as_raw()).finish() - } -} - -//////////////////////////////////////////////////////////////////////////////// -// TCP listeners -//////////////////////////////////////////////////////////////////////////////// - -pub struct TcpListener { - inner: Socket, -} - -impl TcpListener { - pub fn bind(addr: io::Result<&SocketAddr>) -> io::Result { - let addr = addr?; - - init(); - - let sock = Socket::new(addr, c::SOCK_STREAM)?; - - // On platforms with Berkeley-derived sockets, this allows to quickly - // rebind a socket, without needing to wait for the OS to clean up the - // previous one. - // - // On Windows, this allows rebinding sockets which are actively in use, - // which allows “socket hijacking”, so we explicitly don't set it here. - // https://docs.microsoft.com/en-us/windows/win32/winsock/using-so-reuseaddr-and-so-exclusiveaddruse - #[cfg(not(windows))] - setsockopt(&sock, c::SOL_SOCKET, c::SO_REUSEADDR, 1 as c_int)?; - - // Bind our new socket - let (addr, len) = addr.into_inner(); - cvt(unsafe { c::bind(sock.as_raw(), addr.as_ptr(), len as _) })?; - - cfg_if::cfg_if! { - if #[cfg(target_os = "horizon")] { - // The 3DS doesn't support a big connection backlog. Sometimes - // it allows up to about 37, but other times it doesn't even - // accept 32. There may be a global limitation causing this. - let backlog = 20; - } else if #[cfg(target_os = "haiku")] { - // Haiku does not support a queue length > 32 - // https://github.com/haiku/haiku/blob/979a0bc487864675517fb2fab28f87dc8bf43041/headers/posix/sys/socket.h#L81 - let backlog = 32; - } else { - // The default for all other platforms - let backlog = 128; - } - } - - // Start listening - cvt(unsafe { c::listen(sock.as_raw(), backlog) })?; - Ok(TcpListener { inner: sock }) - } - - #[inline] - pub fn socket(&self) -> &Socket { - &self.inner - } - - pub fn into_socket(self) -> Socket { - self.inner - } - - pub fn socket_addr(&self) -> io::Result { - sockname(|buf, len| unsafe { c::getsockname(self.inner.as_raw(), buf, len) }) - } - - pub fn accept(&self) -> io::Result<(TcpStream, SocketAddr)> { - let mut storage: c::sockaddr_storage = unsafe { mem::zeroed() }; - let mut len = mem::size_of_val(&storage) as c::socklen_t; - let sock = self.inner.accept(core::ptr::addr_of_mut!(storage) as *mut _, &mut len)?; - let addr = sockaddr_to_addr(&storage, len as usize)?; - Ok((TcpStream { inner: sock }, addr)) - } - - pub fn duplicate(&self) -> io::Result { - self.inner.duplicate().map(|s| TcpListener { inner: s }) - } - - pub fn set_ttl(&self, ttl: u32) -> io::Result<()> { - setsockopt(&self.inner, c::IPPROTO_IP, c::IP_TTL, ttl as c_int) - } - - pub fn ttl(&self) -> io::Result { - let raw: c_int = getsockopt(&self.inner, c::IPPROTO_IP, c::IP_TTL)?; - Ok(raw as u32) - } - - pub fn set_only_v6(&self, only_v6: bool) -> io::Result<()> { - setsockopt(&self.inner, c::IPPROTO_IPV6, c::IPV6_V6ONLY, only_v6 as c_int) - } - - pub fn only_v6(&self) -> io::Result { - let raw: c_int = getsockopt(&self.inner, c::IPPROTO_IPV6, c::IPV6_V6ONLY)?; - Ok(raw != 0) - } - - pub fn take_error(&self) -> io::Result> { - self.inner.take_error() - } - - pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> { - self.inner.set_nonblocking(nonblocking) - } -} - -impl FromInner for TcpListener { - fn from_inner(socket: Socket) -> TcpListener { - TcpListener { inner: socket } - } -} - -impl fmt::Debug for TcpListener { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let mut res = f.debug_struct("TcpListener"); - - if let Ok(addr) = self.socket_addr() { - res.field("addr", &addr); - } - - let name = if cfg!(windows) { "socket" } else { "fd" }; - res.field(name, &self.inner.as_raw()).finish() - } -} - -//////////////////////////////////////////////////////////////////////////////// -// UDP -//////////////////////////////////////////////////////////////////////////////// - -pub struct UdpSocket { - inner: Socket, -} - -impl UdpSocket { - pub fn bind(addr: io::Result<&SocketAddr>) -> io::Result { - let addr = addr?; - - init(); - - let sock = Socket::new(addr, c::SOCK_DGRAM)?; - let (addr, len) = addr.into_inner(); - cvt(unsafe { c::bind(sock.as_raw(), addr.as_ptr(), len as _) })?; - Ok(UdpSocket { inner: sock }) - } - - #[inline] - pub fn socket(&self) -> &Socket { - &self.inner - } - - pub fn into_socket(self) -> Socket { - self.inner - } - - pub fn peer_addr(&self) -> io::Result { - sockname(|buf, len| unsafe { c::getpeername(self.inner.as_raw(), buf, len) }) - } - - pub fn socket_addr(&self) -> io::Result { - sockname(|buf, len| unsafe { c::getsockname(self.inner.as_raw(), buf, len) }) - } - - pub fn recv_from(&self, buf: &mut [u8]) -> io::Result<(usize, SocketAddr)> { - self.inner.recv_from(buf) - } - - pub fn peek_from(&self, buf: &mut [u8]) -> io::Result<(usize, SocketAddr)> { - self.inner.peek_from(buf) - } - - pub fn send_to(&self, buf: &[u8], dst: &SocketAddr) -> io::Result { - let len = cmp::min(buf.len(), ::MAX as usize) as wrlen_t; - let (dst, dstlen) = dst.into_inner(); - let ret = cvt(unsafe { - c::sendto( - self.inner.as_raw(), - buf.as_ptr() as *const c_void, - len, - MSG_NOSIGNAL, - dst.as_ptr(), - dstlen, - ) - })?; - Ok(ret as usize) - } - - pub fn duplicate(&self) -> io::Result { - self.inner.duplicate().map(|s| UdpSocket { inner: s }) - } - - pub fn set_read_timeout(&self, dur: Option) -> io::Result<()> { - self.inner.set_timeout(dur, c::SO_RCVTIMEO) - } - - pub fn set_write_timeout(&self, dur: Option) -> io::Result<()> { - self.inner.set_timeout(dur, c::SO_SNDTIMEO) - } - - pub fn read_timeout(&self) -> io::Result> { - self.inner.timeout(c::SO_RCVTIMEO) - } - - pub fn write_timeout(&self) -> io::Result> { - self.inner.timeout(c::SO_SNDTIMEO) - } - - pub fn set_broadcast(&self, broadcast: bool) -> io::Result<()> { - setsockopt(&self.inner, c::SOL_SOCKET, c::SO_BROADCAST, broadcast as c_int) - } - - pub fn broadcast(&self) -> io::Result { - let raw: c_int = getsockopt(&self.inner, c::SOL_SOCKET, c::SO_BROADCAST)?; - Ok(raw != 0) - } - - pub fn set_multicast_loop_v4(&self, multicast_loop_v4: bool) -> io::Result<()> { - setsockopt( - &self.inner, - c::IPPROTO_IP, - c::IP_MULTICAST_LOOP, - multicast_loop_v4 as IpV4MultiCastType, - ) - } - - pub fn multicast_loop_v4(&self) -> io::Result { - let raw: IpV4MultiCastType = getsockopt(&self.inner, c::IPPROTO_IP, c::IP_MULTICAST_LOOP)?; - Ok(raw != 0) - } - - pub fn set_multicast_ttl_v4(&self, multicast_ttl_v4: u32) -> io::Result<()> { - setsockopt( - &self.inner, - c::IPPROTO_IP, - c::IP_MULTICAST_TTL, - multicast_ttl_v4 as IpV4MultiCastType, - ) - } - - pub fn multicast_ttl_v4(&self) -> io::Result { - let raw: IpV4MultiCastType = getsockopt(&self.inner, c::IPPROTO_IP, c::IP_MULTICAST_TTL)?; - Ok(raw as u32) - } - - pub fn set_multicast_loop_v6(&self, multicast_loop_v6: bool) -> io::Result<()> { - setsockopt(&self.inner, c::IPPROTO_IPV6, c::IPV6_MULTICAST_LOOP, multicast_loop_v6 as c_int) - } - - pub fn multicast_loop_v6(&self) -> io::Result { - let raw: c_int = getsockopt(&self.inner, c::IPPROTO_IPV6, c::IPV6_MULTICAST_LOOP)?; - Ok(raw != 0) - } - - pub fn join_multicast_v4(&self, multiaddr: &Ipv4Addr, interface: &Ipv4Addr) -> io::Result<()> { - let mreq = c::ip_mreq { - imr_multiaddr: multiaddr.into_inner(), - imr_interface: interface.into_inner(), - }; - setsockopt(&self.inner, c::IPPROTO_IP, c::IP_ADD_MEMBERSHIP, mreq) - } - - pub fn join_multicast_v6(&self, multiaddr: &Ipv6Addr, interface: u32) -> io::Result<()> { - let mreq = c::ipv6_mreq { - ipv6mr_multiaddr: multiaddr.into_inner(), - ipv6mr_interface: to_ipv6mr_interface(interface), - }; - setsockopt(&self.inner, c::IPPROTO_IPV6, IPV6_ADD_MEMBERSHIP, mreq) - } - - pub fn leave_multicast_v4(&self, multiaddr: &Ipv4Addr, interface: &Ipv4Addr) -> io::Result<()> { - let mreq = c::ip_mreq { - imr_multiaddr: multiaddr.into_inner(), - imr_interface: interface.into_inner(), - }; - setsockopt(&self.inner, c::IPPROTO_IP, c::IP_DROP_MEMBERSHIP, mreq) - } - - pub fn leave_multicast_v6(&self, multiaddr: &Ipv6Addr, interface: u32) -> io::Result<()> { - let mreq = c::ipv6_mreq { - ipv6mr_multiaddr: multiaddr.into_inner(), - ipv6mr_interface: to_ipv6mr_interface(interface), - }; - setsockopt(&self.inner, c::IPPROTO_IPV6, IPV6_DROP_MEMBERSHIP, mreq) - } - - pub fn set_ttl(&self, ttl: u32) -> io::Result<()> { - setsockopt(&self.inner, c::IPPROTO_IP, c::IP_TTL, ttl as c_int) - } - - pub fn ttl(&self) -> io::Result { - let raw: c_int = getsockopt(&self.inner, c::IPPROTO_IP, c::IP_TTL)?; - Ok(raw as u32) - } - - pub fn take_error(&self) -> io::Result> { - self.inner.take_error() - } - - pub fn set_nonblocking(&self, nonblocking: bool) -> io::Result<()> { - self.inner.set_nonblocking(nonblocking) - } - - pub fn recv(&self, buf: &mut [u8]) -> io::Result { - self.inner.read(buf) - } - - pub fn peek(&self, buf: &mut [u8]) -> io::Result { - self.inner.peek(buf) - } - - pub fn send(&self, buf: &[u8]) -> io::Result { - let len = cmp::min(buf.len(), ::MAX as usize) as wrlen_t; - let ret = cvt(unsafe { - c::send(self.inner.as_raw(), buf.as_ptr() as *const c_void, len, MSG_NOSIGNAL) - })?; - Ok(ret as usize) - } - - pub fn connect(&self, addr: io::Result<&SocketAddr>) -> io::Result<()> { - let (addr, len) = addr?.into_inner(); - cvt_r(|| unsafe { c::connect(self.inner.as_raw(), addr.as_ptr(), len) }).map(drop) - } -} - -impl FromInner for UdpSocket { - fn from_inner(socket: Socket) -> UdpSocket { - UdpSocket { inner: socket } - } -} - -impl fmt::Debug for UdpSocket { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let mut res = f.debug_struct("UdpSocket"); - - if let Ok(addr) = self.socket_addr() { - res.field("addr", &addr); - } - - let name = if cfg!(windows) { "socket" } else { "fd" }; - res.field(name, &self.inner.as_raw()).finish() - } -} - -//////////////////////////////////////////////////////////////////////////////// -// Converting SocketAddr to libc representation -//////////////////////////////////////////////////////////////////////////////// - -/// A type with the same memory layout as `c::sockaddr`. Used in converting Rust level -/// SocketAddr* types into their system representation. The benefit of this specific -/// type over using `c::sockaddr_storage` is that this type is exactly as large as it -/// needs to be and not a lot larger. And it can be initialized more cleanly from Rust. -#[repr(C)] -pub(crate) union SocketAddrCRepr { - v4: c::sockaddr_in, - v6: c::sockaddr_in6, -} - -impl SocketAddrCRepr { - pub fn as_ptr(&self) -> *const c::sockaddr { - self as *const _ as *const c::sockaddr - } -} - -impl<'a> IntoInner<(SocketAddrCRepr, c::socklen_t)> for &'a SocketAddr { - fn into_inner(self) -> (SocketAddrCRepr, c::socklen_t) { - match *self { - SocketAddr::V4(ref a) => { - let sockaddr = SocketAddrCRepr { v4: a.into_inner() }; - (sockaddr, mem::size_of::() as c::socklen_t) - } - SocketAddr::V6(ref a) => { - let sockaddr = SocketAddrCRepr { v6: a.into_inner() }; - (sockaddr, mem::size_of::() as c::socklen_t) - } - } - } -} diff --git a/library/std/src/sys_common/net/tests.rs b/library/std/src/sys_common/net/tests.rs deleted file mode 100644 index fc236b8027b67..0000000000000 --- a/library/std/src/sys_common/net/tests.rs +++ /dev/null @@ -1,19 +0,0 @@ -use super::*; -use crate::collections::HashMap; - -#[test] -fn no_lookup_host_duplicates() { - let mut addrs = HashMap::new(); - let lh = match LookupHost::try_from(("localhost", 0)) { - Ok(lh) => lh, - Err(e) => panic!("couldn't resolve `localhost`: {e}"), - }; - for sa in lh { - *addrs.entry(sa).or_insert(0) += 1; - } - assert_eq!( - addrs.iter().filter(|&(_, &v)| v > 1).collect::>(), - vec![], - "There should be no duplicate localhost entries" - ); -} diff --git a/library/std/src/sys_common/process.rs b/library/std/src/sys_common/process.rs deleted file mode 100644 index 4d295cf0f09d5..0000000000000 --- a/library/std/src/sys_common/process.rs +++ /dev/null @@ -1,161 +0,0 @@ -#![allow(dead_code)] -#![unstable(feature = "process_internals", issue = "none")] - -use crate::collections::BTreeMap; -use crate::env; -use crate::ffi::{OsStr, OsString}; -use crate::fmt; -use crate::io; -use crate::sys::pipe::read2; -use crate::sys::process::{EnvKey, ExitStatus, Process, StdioPipes}; - -// Stores a set of changes to an environment -#[derive(Clone)] -pub struct CommandEnv { - clear: bool, - saw_path: bool, - vars: BTreeMap>, -} - -impl Default for CommandEnv { - fn default() -> Self { - CommandEnv { clear: false, saw_path: false, vars: Default::default() } - } -} - -impl fmt::Debug for CommandEnv { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - let mut debug_command_env = f.debug_struct("CommandEnv"); - debug_command_env.field("clear", &self.clear).field("vars", &self.vars); - debug_command_env.finish() - } -} - -impl CommandEnv { - // Capture the current environment with these changes applied - pub fn capture(&self) -> BTreeMap { - let mut result = BTreeMap::::new(); - if !self.clear { - for (k, v) in env::vars_os() { - result.insert(k.into(), v); - } - } - for (k, maybe_v) in &self.vars { - if let &Some(ref v) = maybe_v { - result.insert(k.clone(), v.clone()); - } else { - result.remove(k); - } - } - result - } - - pub fn is_unchanged(&self) -> bool { - !self.clear && self.vars.is_empty() - } - - pub fn capture_if_changed(&self) -> Option> { - if self.is_unchanged() { None } else { Some(self.capture()) } - } - - // The following functions build up changes - pub fn set(&mut self, key: &OsStr, value: &OsStr) { - let key = EnvKey::from(key); - self.maybe_saw_path(&key); - self.vars.insert(key, Some(value.to_owned())); - } - - pub fn remove(&mut self, key: &OsStr) { - let key = EnvKey::from(key); - self.maybe_saw_path(&key); - if self.clear { - self.vars.remove(&key); - } else { - self.vars.insert(key, None); - } - } - - pub fn clear(&mut self) { - self.clear = true; - self.vars.clear(); - } - - pub fn does_clear(&self) -> bool { - self.clear - } - - pub fn have_changed_path(&self) -> bool { - self.saw_path || self.clear - } - - fn maybe_saw_path(&mut self, key: &EnvKey) { - if !self.saw_path && key == "PATH" { - self.saw_path = true; - } - } - - pub fn iter(&self) -> CommandEnvs<'_> { - let iter = self.vars.iter(); - CommandEnvs { iter } - } -} - -/// An iterator over the command environment variables. -/// -/// This struct is created by -/// [`Command::get_envs`][crate::process::Command::get_envs]. See its -/// documentation for more. -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "command_access", since = "1.57.0")] -#[derive(Debug)] -pub struct CommandEnvs<'a> { - iter: crate::collections::btree_map::Iter<'a, EnvKey, Option>, -} - -#[stable(feature = "command_access", since = "1.57.0")] -impl<'a> Iterator for CommandEnvs<'a> { - type Item = (&'a OsStr, Option<&'a OsStr>); - fn next(&mut self) -> Option { - self.iter.next().map(|(key, value)| (key.as_ref(), value.as_deref())) - } - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } -} - -#[stable(feature = "command_access", since = "1.57.0")] -impl<'a> ExactSizeIterator for CommandEnvs<'a> { - fn len(&self) -> usize { - self.iter.len() - } - fn is_empty(&self) -> bool { - self.iter.is_empty() - } -} - -pub fn wait_with_output( - mut process: Process, - mut pipes: StdioPipes, -) -> io::Result<(ExitStatus, Vec, Vec)> { - drop(pipes.stdin.take()); - - let (mut stdout, mut stderr) = (Vec::new(), Vec::new()); - match (pipes.stdout.take(), pipes.stderr.take()) { - (None, None) => {} - (Some(out), None) => { - let res = out.read_to_end(&mut stdout); - res.unwrap(); - } - (None, Some(err)) => { - let res = err.read_to_end(&mut stderr); - res.unwrap(); - } - (Some(out), Some(err)) => { - let res = read2(out, &mut stdout, err, &mut stderr); - res.unwrap(); - } - } - - let status = process.wait()?; - Ok((status, stdout, stderr)) -} diff --git a/library/std/src/sys_common/tests.rs b/library/std/src/sys_common/tests.rs deleted file mode 100644 index 1b6446db52d4b..0000000000000 --- a/library/std/src/sys_common/tests.rs +++ /dev/null @@ -1,6 +0,0 @@ -use super::mul_div_u64; - -#[test] -fn test_muldiv() { - assert_eq!(mul_div_u64(1_000_000_000_001, 1_000_000_000, 1_000_000), 1_000_000_000_001_000); -} diff --git a/library/std/src/sys_common/thread_local_dtor.rs b/library/std/src/sys_common/thread_local_dtor.rs deleted file mode 100644 index 98382fc6acc23..0000000000000 --- a/library/std/src/sys_common/thread_local_dtor.rs +++ /dev/null @@ -1,56 +0,0 @@ -//! Thread-local destructor -//! -//! Besides thread-local "keys" (pointer-sized non-addressable thread-local store -//! with an associated destructor), many platforms also provide thread-local -//! destructors that are not associated with any particular data. These are -//! often more efficient. -//! -//! This module provides a fallback implementation for that interface, based -//! on the less efficient thread-local "keys". Each platform provides -//! a `thread_local_dtor` module which will either re-export the fallback, -//! or implement something more efficient. - -#![unstable(feature = "thread_local_internals", issue = "none")] -#![allow(dead_code)] - -use crate::cell::RefCell; -use crate::ptr; -use crate::sys_common::thread_local_key::StaticKey; - -pub unsafe fn register_dtor_fallback(t: *mut u8, dtor: unsafe extern "C" fn(*mut u8)) { - // The fallback implementation uses a vanilla OS-based TLS key to track - // the list of destructors that need to be run for this thread. The key - // then has its own destructor which runs all the other destructors. - // - // The destructor for DTORS is a little special in that it has a `while` - // loop to continuously drain the list of registered destructors. It - // *should* be the case that this loop always terminates because we - // provide the guarantee that a TLS key cannot be set after it is - // flagged for destruction. - - static DTORS: StaticKey = StaticKey::new(Some(run_dtors)); - // FIXME(joboet): integrate RefCell into pointer to avoid infinite recursion - // when the global allocator tries to register a destructor and just panic - // instead. - type List = RefCell>; - if DTORS.get().is_null() { - let v: Box = Box::new(RefCell::new(Vec::new())); - DTORS.set(Box::into_raw(v) as *mut u8); - } - let list = &*(DTORS.get() as *const List); - match list.try_borrow_mut() { - Ok(mut dtors) => dtors.push((t, dtor)), - Err(_) => rtabort!("global allocator may not use TLS"), - } - - unsafe extern "C" fn run_dtors(mut ptr: *mut u8) { - while !ptr.is_null() { - let list = Box::from_raw(ptr as *mut List).into_inner(); - for (ptr, dtor) in list.into_iter() { - dtor(ptr); - } - ptr = DTORS.get(); - DTORS.set(ptr::null_mut()); - } - } -} diff --git a/library/std/src/sys_common/thread_local_key.rs b/library/std/src/sys_common/thread_local_key.rs deleted file mode 100644 index a9cd26389cd41..0000000000000 --- a/library/std/src/sys_common/thread_local_key.rs +++ /dev/null @@ -1,174 +0,0 @@ -//! OS-based thread local storage for non-Windows systems -//! -//! This module provides an implementation of OS-based thread local storage, -//! using the native OS-provided facilities (think `TlsAlloc` or -//! `pthread_setspecific`). The interface of this differs from the other types -//! of thread-local-storage provided in this crate in that OS-based TLS can only -//! get/set pointer-sized data, possibly with an associated destructor. -//! -//! This module also provides two flavors of TLS. One is intended for static -//! initialization, and does not contain a `Drop` implementation to deallocate -//! the OS-TLS key. The other is a type which does implement `Drop` and hence -//! has a safe interface. -//! -//! Windows doesn't use this module at all; `sys::pal::windows::thread_local_key` -//! gets imported in its stead. -//! -//! # Usage -//! -//! This module should likely not be used directly unless other primitives are -//! being built on. Types such as `thread_local::spawn::Key` are likely much -//! more useful in practice than this OS-based version which likely requires -//! unsafe code to interoperate with. -//! -//! # Examples -//! -//! Using a dynamically allocated TLS key. Note that this key can be shared -//! among many threads via an `Arc`. -//! -//! ```ignore (cannot-doctest-private-modules) -//! let key = Key::new(None); -//! assert!(key.get().is_null()); -//! key.set(1 as *mut u8); -//! assert!(!key.get().is_null()); -//! -//! drop(key); // deallocate this TLS slot. -//! ``` -//! -//! Sometimes a statically allocated key is either required or easier to work -//! with, however. -//! -//! ```ignore (cannot-doctest-private-modules) -//! static KEY: StaticKey = INIT; -//! -//! unsafe { -//! assert!(KEY.get().is_null()); -//! KEY.set(1 as *mut u8); -//! } -//! ``` - -#![allow(non_camel_case_types)] -#![unstable(feature = "thread_local_internals", issue = "none")] -#![allow(dead_code)] - -#[cfg(test)] -mod tests; - -use crate::sync::atomic::{self, AtomicUsize, Ordering}; -use crate::sys::thread_local_key as imp; - -/// A type for TLS keys that are statically allocated. -/// -/// This type is entirely `unsafe` to use as it does not protect against -/// use-after-deallocation or use-during-deallocation. -/// -/// The actual OS-TLS key is lazily allocated when this is used for the first -/// time. The key is also deallocated when the Rust runtime exits or `destroy` -/// is called, whichever comes first. -/// -/// # Examples -/// -/// ```ignore (cannot-doctest-private-modules) -/// use tls::os::{StaticKey, INIT}; -/// -/// // Use a regular global static to store the key. -/// static KEY: StaticKey = INIT; -/// -/// // The state provided via `get` and `set` is thread-local. -/// unsafe { -/// assert!(KEY.get().is_null()); -/// KEY.set(1 as *mut u8); -/// } -/// ``` -pub struct StaticKey { - /// Inner static TLS key (internals). - key: AtomicUsize, - /// Destructor for the TLS value. - /// - /// See `Key::new` for information about when the destructor runs and how - /// it runs. - dtor: Option, -} - -/// Constant initialization value for static TLS keys. -/// -/// This value specifies no destructor by default. -pub const INIT: StaticKey = StaticKey::new(None); - -// Define a sentinel value that is likely not to be returned -// as a TLS key. -#[cfg(not(target_os = "nto"))] -const KEY_SENTVAL: usize = 0; -// On QNX Neutrino, 0 is always returned when currently not in use. -// Using 0 would mean to always create two keys and remote the first -// one (with value of 0) immediately afterwards. -#[cfg(target_os = "nto")] -const KEY_SENTVAL: usize = libc::PTHREAD_KEYS_MAX + 1; - -impl StaticKey { - #[rustc_const_unstable(feature = "thread_local_internals", issue = "none")] - pub const fn new(dtor: Option) -> StaticKey { - StaticKey { key: atomic::AtomicUsize::new(KEY_SENTVAL), dtor } - } - - /// Gets the value associated with this TLS key - /// - /// This will lazily allocate a TLS key from the OS if one has not already - /// been allocated. - #[inline] - pub unsafe fn get(&self) -> *mut u8 { - imp::get(self.key()) - } - - /// Sets this TLS key to a new value. - /// - /// This will lazily allocate a TLS key from the OS if one has not already - /// been allocated. - #[inline] - pub unsafe fn set(&self, val: *mut u8) { - imp::set(self.key(), val) - } - - #[inline] - unsafe fn key(&self) -> imp::Key { - match self.key.load(Ordering::Acquire) { - KEY_SENTVAL => self.lazy_init() as imp::Key, - n => n as imp::Key, - } - } - - unsafe fn lazy_init(&self) -> usize { - // POSIX allows the key created here to be KEY_SENTVAL, but the compare_exchange - // below relies on using KEY_SENTVAL as a sentinel value to check who won the - // race to set the shared TLS key. As far as I know, there is no - // guaranteed value that cannot be returned as a posix_key_create key, - // so there is no value we can initialize the inner key with to - // prove that it has not yet been set. As such, we'll continue using a - // value of KEY_SENTVAL, but with some gyrations to make sure we have a non-KEY_SENTVAL - // value returned from the creation routine. - // FIXME: this is clearly a hack, and should be cleaned up. - let key1 = imp::create(self.dtor); - let key = if key1 as usize != KEY_SENTVAL { - key1 - } else { - let key2 = imp::create(self.dtor); - imp::destroy(key1); - key2 - }; - rtassert!(key as usize != KEY_SENTVAL); - match self.key.compare_exchange( - KEY_SENTVAL, - key as usize, - Ordering::Release, - Ordering::Acquire, - ) { - // The CAS succeeded, so we've created the actual key - Ok(_) => key as usize, - // If someone beat us to the punch, use their key instead - Err(n) => { - imp::destroy(key); - n - } - } - } -} diff --git a/library/std/src/sys_common/thread_local_key/tests.rs b/library/std/src/sys_common/thread_local_key/tests.rs deleted file mode 100644 index 48bed31af517c..0000000000000 --- a/library/std/src/sys_common/thread_local_key/tests.rs +++ /dev/null @@ -1,17 +0,0 @@ -use super::StaticKey; -use core::ptr; - -#[test] -fn statik() { - static K1: StaticKey = StaticKey::new(None); - static K2: StaticKey = StaticKey::new(None); - - unsafe { - assert!(K1.get().is_null()); - assert!(K2.get().is_null()); - K1.set(ptr::without_provenance_mut(1)); - K2.set(ptr::without_provenance_mut(2)); - assert_eq!(K1.get() as usize, 1); - assert_eq!(K2.get() as usize, 2); - } -} diff --git a/library/std/src/sys_common/wstr.rs b/library/std/src/sys_common/wstr.rs deleted file mode 100644 index 8eae160648502..0000000000000 --- a/library/std/src/sys_common/wstr.rs +++ /dev/null @@ -1,60 +0,0 @@ -//! This module contains constructs to work with 16-bit characters (UCS-2 or UTF-16) -#![allow(dead_code)] - -use crate::marker::PhantomData; -use crate::num::NonZero; -use crate::ptr::NonNull; - -/// A safe iterator over a LPWSTR -/// (aka a pointer to a series of UTF-16 code units terminated by a NULL). -pub struct WStrUnits<'a> { - // The pointer must never be null... - lpwstr: NonNull, - // ...and the memory it points to must be valid for this lifetime. - lifetime: PhantomData<&'a [u16]>, -} - -impl WStrUnits<'_> { - /// Create the iterator. Returns `None` if `lpwstr` is null. - /// - /// SAFETY: `lpwstr` must point to a null-terminated wide string that lives - /// at least as long as the lifetime of this struct. - pub unsafe fn new(lpwstr: *const u16) -> Option { - Some(Self { lpwstr: NonNull::new(lpwstr as _)?, lifetime: PhantomData }) - } - - pub fn peek(&self) -> Option> { - // SAFETY: It's always safe to read the current item because we don't - // ever move out of the array's bounds. - unsafe { NonZero::new(*self.lpwstr.as_ptr()) } - } - - /// Advance the iterator while `predicate` returns true. - /// Returns the number of items it advanced by. - pub fn advance_while) -> bool>(&mut self, mut predicate: P) -> usize { - let mut counter = 0; - while let Some(w) = self.peek() { - if !predicate(w) { - break; - } - counter += 1; - self.next(); - } - counter - } -} - -impl Iterator for WStrUnits<'_> { - // This can never return zero as that marks the end of the string. - type Item = NonZero; - - fn next(&mut self) -> Option { - // SAFETY: If NULL is reached we immediately return. - // Therefore it's safe to advance the pointer after that. - unsafe { - let next = self.peek()?; - self.lpwstr = NonNull::new_unchecked(self.lpwstr.as_ptr().add(1)); - Some(next) - } - } -} diff --git a/library/std/src/sys_common/wtf8.rs b/library/std/src/sys_common/wtf8.rs deleted file mode 100644 index 38e15f9f54960..0000000000000 --- a/library/std/src/sys_common/wtf8.rs +++ /dev/null @@ -1,1038 +0,0 @@ -//! Implementation of [the WTF-8 encoding](https://simonsapin.github.io/wtf-8/). -//! -//! This library uses Rust’s type system to maintain -//! [well-formedness](https://simonsapin.github.io/wtf-8/#well-formed), -//! like the `String` and `&str` types do for UTF-8. -//! -//! Since [WTF-8 must not be used -//! for interchange](https://simonsapin.github.io/wtf-8/#intended-audience), -//! this library deliberately does not provide access to the underlying bytes -//! of WTF-8 strings, -//! nor can it decode WTF-8 from arbitrary bytes. -//! WTF-8 strings can be obtained from UTF-8, UTF-16, or code points. - -// this module is imported from @SimonSapin's repo and has tons of dead code on -// unix (it's mostly used on windows), so don't worry about dead code here. -#![allow(dead_code)] - -#[cfg(test)] -mod tests; - -use core::char::{encode_utf16_raw, encode_utf8_raw}; -use core::str::next_code_point; - -use crate::borrow::Cow; -use crate::collections::TryReserveError; -use crate::fmt; -use crate::hash::{Hash, Hasher}; -use crate::iter::FusedIterator; -use crate::mem; -use crate::ops; -use crate::rc::Rc; -use crate::slice; -use crate::str; -use crate::sync::Arc; -use crate::sys_common::AsInner; - -const UTF8_REPLACEMENT_CHARACTER: &str = "\u{FFFD}"; - -/// A Unicode code point: from U+0000 to U+10FFFF. -/// -/// Compares with the `char` type, -/// which represents a Unicode scalar value: -/// a code point that is not a surrogate (U+D800 to U+DFFF). -#[derive(Eq, PartialEq, Ord, PartialOrd, Clone, Copy)] -pub struct CodePoint { - value: u32, -} - -/// Format the code point as `U+` followed by four to six hexadecimal digits. -/// Example: `U+1F4A9` -impl fmt::Debug for CodePoint { - #[inline] - fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(formatter, "U+{:04X}", self.value) - } -} - -impl CodePoint { - /// Unsafely creates a new `CodePoint` without checking the value. - /// - /// Only use when `value` is known to be less than or equal to 0x10FFFF. - #[inline] - pub unsafe fn from_u32_unchecked(value: u32) -> CodePoint { - CodePoint { value } - } - - /// Creates a new `CodePoint` if the value is a valid code point. - /// - /// Returns `None` if `value` is above 0x10FFFF. - #[inline] - pub fn from_u32(value: u32) -> Option { - match value { - 0..=0x10FFFF => Some(CodePoint { value }), - _ => None, - } - } - - /// Creates a new `CodePoint` from a `char`. - /// - /// Since all Unicode scalar values are code points, this always succeeds. - #[inline] - pub fn from_char(value: char) -> CodePoint { - CodePoint { value: value as u32 } - } - - /// Returns the numeric value of the code point. - #[inline] - pub fn to_u32(&self) -> u32 { - self.value - } - - /// Returns the numeric value of the code point if it is a leading surrogate. - #[inline] - pub fn to_lead_surrogate(&self) -> Option { - match self.value { - lead @ 0xD800..=0xDBFF => Some(lead as u16), - _ => None, - } - } - - /// Returns the numeric value of the code point if it is a trailing surrogate. - #[inline] - pub fn to_trail_surrogate(&self) -> Option { - match self.value { - trail @ 0xDC00..=0xDFFF => Some(trail as u16), - _ => None, - } - } - - /// Optionally returns a Unicode scalar value for the code point. - /// - /// Returns `None` if the code point is a surrogate (from U+D800 to U+DFFF). - #[inline] - pub fn to_char(&self) -> Option { - match self.value { - 0xD800..=0xDFFF => None, - _ => Some(unsafe { char::from_u32_unchecked(self.value) }), - } - } - - /// Returns a Unicode scalar value for the code point. - /// - /// Returns `'\u{FFFD}'` (the replacement character “�”) - /// if the code point is a surrogate (from U+D800 to U+DFFF). - #[inline] - pub fn to_char_lossy(&self) -> char { - self.to_char().unwrap_or('\u{FFFD}') - } -} - -/// An owned, growable string of well-formed WTF-8 data. -/// -/// Similar to `String`, but can additionally contain surrogate code points -/// if they’re not in a surrogate pair. -#[derive(Eq, PartialEq, Ord, PartialOrd, Clone)] -pub struct Wtf8Buf { - bytes: Vec, - - /// Do we know that `bytes` holds a valid UTF-8 encoding? We can easily - /// know this if we're constructed from a `String` or `&str`. - /// - /// It is possible for `bytes` to have valid UTF-8 without this being - /// set, such as when we're concatenating `&Wtf8`'s and surrogates become - /// paired, as we don't bother to rescan the entire string. - is_known_utf8: bool, -} - -impl ops::Deref for Wtf8Buf { - type Target = Wtf8; - - fn deref(&self) -> &Wtf8 { - self.as_slice() - } -} - -impl ops::DerefMut for Wtf8Buf { - fn deref_mut(&mut self) -> &mut Wtf8 { - self.as_mut_slice() - } -} - -/// Format the string with double quotes, -/// and surrogates as `\u` followed by four hexadecimal digits. -/// Example: `"a\u{D800}"` for a string with code points [U+0061, U+D800] -impl fmt::Debug for Wtf8Buf { - #[inline] - fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&**self, formatter) - } -} - -impl Wtf8Buf { - /// Creates a new, empty WTF-8 string. - #[inline] - pub fn new() -> Wtf8Buf { - Wtf8Buf { bytes: Vec::new(), is_known_utf8: true } - } - - /// Creates a new, empty WTF-8 string with pre-allocated capacity for `capacity` bytes. - #[inline] - pub fn with_capacity(capacity: usize) -> Wtf8Buf { - Wtf8Buf { bytes: Vec::with_capacity(capacity), is_known_utf8: true } - } - - /// Creates a WTF-8 string from a WTF-8 byte vec. - /// - /// Since the byte vec is not checked for valid WTF-8, this functions is - /// marked unsafe. - #[inline] - pub unsafe fn from_bytes_unchecked(value: Vec) -> Wtf8Buf { - Wtf8Buf { bytes: value, is_known_utf8: false } - } - - /// Creates a WTF-8 string from a UTF-8 `String`. - /// - /// This takes ownership of the `String` and does not copy. - /// - /// Since WTF-8 is a superset of UTF-8, this always succeeds. - #[inline] - pub fn from_string(string: String) -> Wtf8Buf { - Wtf8Buf { bytes: string.into_bytes(), is_known_utf8: true } - } - - /// Creates a WTF-8 string from a UTF-8 `&str` slice. - /// - /// This copies the content of the slice. - /// - /// Since WTF-8 is a superset of UTF-8, this always succeeds. - #[inline] - pub fn from_str(str: &str) -> Wtf8Buf { - Wtf8Buf { bytes: <[_]>::to_vec(str.as_bytes()), is_known_utf8: true } - } - - pub fn clear(&mut self) { - self.bytes.clear(); - self.is_known_utf8 = true; - } - - /// Creates a WTF-8 string from a potentially ill-formed UTF-16 slice of 16-bit code units. - /// - /// This is lossless: calling `.encode_wide()` on the resulting string - /// will always return the original code units. - pub fn from_wide(v: &[u16]) -> Wtf8Buf { - let mut string = Wtf8Buf::with_capacity(v.len()); - for item in char::decode_utf16(v.iter().cloned()) { - match item { - Ok(ch) => string.push_char(ch), - Err(surrogate) => { - let surrogate = surrogate.unpaired_surrogate(); - // Surrogates are known to be in the code point range. - let code_point = unsafe { CodePoint::from_u32_unchecked(surrogate as u32) }; - // The string will now contain an unpaired surrogate. - string.is_known_utf8 = false; - // Skip the WTF-8 concatenation check, - // surrogate pairs are already decoded by decode_utf16 - string.push_code_point_unchecked(code_point); - } - } - } - string - } - - /// Copied from String::push - /// This does **not** include the WTF-8 concatenation check or `is_known_utf8` check. - fn push_code_point_unchecked(&mut self, code_point: CodePoint) { - let mut bytes = [0; 4]; - let bytes = encode_utf8_raw(code_point.value, &mut bytes); - self.bytes.extend_from_slice(bytes) - } - - #[inline] - pub fn as_slice(&self) -> &Wtf8 { - unsafe { Wtf8::from_bytes_unchecked(&self.bytes) } - } - - #[inline] - pub fn as_mut_slice(&mut self) -> &mut Wtf8 { - // Safety: `Wtf8` doesn't expose any way to mutate the bytes that would - // cause them to change from well-formed UTF-8 to ill-formed UTF-8, - // which would break the assumptions of the `is_known_utf8` field. - unsafe { Wtf8::from_mut_bytes_unchecked(&mut self.bytes) } - } - - /// Reserves capacity for at least `additional` more bytes to be inserted - /// in the given `Wtf8Buf`. - /// The collection may reserve more space to avoid frequent reallocations. - /// - /// # Panics - /// - /// Panics if the new capacity overflows `usize`. - #[inline] - pub fn reserve(&mut self, additional: usize) { - self.bytes.reserve(additional) - } - - /// Tries to reserve capacity for at least `additional` more length units - /// in the given `Wtf8Buf`. The `Wtf8Buf` may reserve more space to avoid - /// frequent reallocations. After calling `try_reserve`, capacity will be - /// greater than or equal to `self.len() + additional`. Does nothing if - /// capacity is already sufficient. This method preserves the contents even - /// if an error occurs. - /// - /// # Errors - /// - /// If the capacity overflows, or the allocator reports a failure, then an error - /// is returned. - #[inline] - pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> { - self.bytes.try_reserve(additional) - } - - #[inline] - pub fn reserve_exact(&mut self, additional: usize) { - self.bytes.reserve_exact(additional) - } - - /// Tries to reserve the minimum capacity for exactly `additional` - /// length units in the given `Wtf8Buf`. After calling - /// `try_reserve_exact`, capacity will be greater than or equal to - /// `self.len() + additional` if it returns `Ok(())`. - /// Does nothing if the capacity is already sufficient. - /// - /// Note that the allocator may give the `Wtf8Buf` more space than it - /// requests. Therefore, capacity can not be relied upon to be precisely - /// minimal. Prefer [`try_reserve`] if future insertions are expected. - /// - /// [`try_reserve`]: Wtf8Buf::try_reserve - /// - /// # Errors - /// - /// If the capacity overflows, or the allocator reports a failure, then an error - /// is returned. - #[inline] - pub fn try_reserve_exact(&mut self, additional: usize) -> Result<(), TryReserveError> { - self.bytes.try_reserve_exact(additional) - } - - #[inline] - pub fn shrink_to_fit(&mut self) { - self.bytes.shrink_to_fit() - } - - #[inline] - pub fn shrink_to(&mut self, min_capacity: usize) { - self.bytes.shrink_to(min_capacity) - } - - /// Returns the number of bytes that this string buffer can hold without reallocating. - #[inline] - pub fn capacity(&self) -> usize { - self.bytes.capacity() - } - - /// Append a UTF-8 slice at the end of the string. - #[inline] - pub fn push_str(&mut self, other: &str) { - self.bytes.extend_from_slice(other.as_bytes()) - } - - /// Append a WTF-8 slice at the end of the string. - /// - /// This replaces newly paired surrogates at the boundary - /// with a supplementary code point, - /// like concatenating ill-formed UTF-16 strings effectively would. - #[inline] - pub fn push_wtf8(&mut self, other: &Wtf8) { - match ((&*self).final_lead_surrogate(), other.initial_trail_surrogate()) { - // Replace newly paired surrogates by a supplementary code point. - (Some(lead), Some(trail)) => { - let len_without_lead_surrogate = self.len() - 3; - self.bytes.truncate(len_without_lead_surrogate); - let other_without_trail_surrogate = &other.bytes[3..]; - // 4 bytes for the supplementary code point - self.bytes.reserve(4 + other_without_trail_surrogate.len()); - self.push_char(decode_surrogate_pair(lead, trail)); - self.bytes.extend_from_slice(other_without_trail_surrogate); - } - _ => { - // If we'll be pushing a string containing a surrogate, we may - // no longer have UTF-8. - if other.next_surrogate(0).is_some() { - self.is_known_utf8 = false; - } - - self.bytes.extend_from_slice(&other.bytes); - } - } - } - - /// Append a Unicode scalar value at the end of the string. - #[inline] - pub fn push_char(&mut self, c: char) { - self.push_code_point_unchecked(CodePoint::from_char(c)) - } - - /// Append a code point at the end of the string. - /// - /// This replaces newly paired surrogates at the boundary - /// with a supplementary code point, - /// like concatenating ill-formed UTF-16 strings effectively would. - #[inline] - pub fn push(&mut self, code_point: CodePoint) { - if let Some(trail) = code_point.to_trail_surrogate() { - if let Some(lead) = (&*self).final_lead_surrogate() { - let len_without_lead_surrogate = self.len() - 3; - self.bytes.truncate(len_without_lead_surrogate); - self.push_char(decode_surrogate_pair(lead, trail)); - return; - } - - // We're pushing a trailing surrogate. - self.is_known_utf8 = false; - } else if code_point.to_lead_surrogate().is_some() { - // We're pushing a leading surrogate. - self.is_known_utf8 = false; - } - - // No newly paired surrogates at the boundary. - self.push_code_point_unchecked(code_point) - } - - /// Shortens a string to the specified length. - /// - /// # Panics - /// - /// Panics if `new_len` > current length, - /// or if `new_len` is not a code point boundary. - #[inline] - pub fn truncate(&mut self, new_len: usize) { - assert!(is_code_point_boundary(self, new_len)); - self.bytes.truncate(new_len) - } - - /// Consumes the WTF-8 string and tries to convert it to a vec of bytes. - #[inline] - pub fn into_bytes(self) -> Vec { - self.bytes - } - - /// Consumes the WTF-8 string and tries to convert it to UTF-8. - /// - /// This does not copy the data. - /// - /// If the contents are not well-formed UTF-8 - /// (that is, if the string contains surrogates), - /// the original WTF-8 string is returned instead. - pub fn into_string(self) -> Result { - if self.is_known_utf8 || self.next_surrogate(0).is_none() { - Ok(unsafe { String::from_utf8_unchecked(self.bytes) }) - } else { - Err(self) - } - } - - /// Consumes the WTF-8 string and converts it lossily to UTF-8. - /// - /// This does not copy the data (but may overwrite parts of it in place). - /// - /// Surrogates are replaced with `"\u{FFFD}"` (the replacement character “�”) - pub fn into_string_lossy(mut self) -> String { - // Fast path: If we already have UTF-8, we can return it immediately. - if self.is_known_utf8 { - return unsafe { String::from_utf8_unchecked(self.bytes) }; - } - - let mut pos = 0; - loop { - match self.next_surrogate(pos) { - Some((surrogate_pos, _)) => { - pos = surrogate_pos + 3; - self.bytes[surrogate_pos..pos] - .copy_from_slice(UTF8_REPLACEMENT_CHARACTER.as_bytes()); - } - None => return unsafe { String::from_utf8_unchecked(self.bytes) }, - } - } - } - - /// Converts this `Wtf8Buf` into a boxed `Wtf8`. - #[inline] - pub fn into_box(self) -> Box { - // SAFETY: relies on `Wtf8` being `repr(transparent)`. - unsafe { mem::transmute(self.bytes.into_boxed_slice()) } - } - - /// Converts a `Box` into a `Wtf8Buf`. - pub fn from_box(boxed: Box) -> Wtf8Buf { - let bytes: Box<[u8]> = unsafe { mem::transmute(boxed) }; - Wtf8Buf { bytes: bytes.into_vec(), is_known_utf8: false } - } - - /// Part of a hack to make PathBuf::push/pop more efficient. - #[inline] - pub(crate) fn as_mut_vec_for_path_buf(&mut self) -> &mut Vec { - &mut self.bytes - } -} - -/// Creates a new WTF-8 string from an iterator of code points. -/// -/// This replaces surrogate code point pairs with supplementary code points, -/// like concatenating ill-formed UTF-16 strings effectively would. -impl FromIterator for Wtf8Buf { - fn from_iter>(iter: T) -> Wtf8Buf { - let mut string = Wtf8Buf::new(); - string.extend(iter); - string - } -} - -/// Append code points from an iterator to the string. -/// -/// This replaces surrogate code point pairs with supplementary code points, -/// like concatenating ill-formed UTF-16 strings effectively would. -impl Extend for Wtf8Buf { - fn extend>(&mut self, iter: T) { - let iterator = iter.into_iter(); - let (low, _high) = iterator.size_hint(); - // Lower bound of one byte per code point (ASCII only) - self.bytes.reserve(low); - iterator.for_each(move |code_point| self.push(code_point)); - } - - #[inline] - fn extend_one(&mut self, code_point: CodePoint) { - self.push(code_point); - } - - #[inline] - fn extend_reserve(&mut self, additional: usize) { - // Lower bound of one byte per code point (ASCII only) - self.bytes.reserve(additional); - } -} - -/// A borrowed slice of well-formed WTF-8 data. -/// -/// Similar to `&str`, but can additionally contain surrogate code points -/// if they’re not in a surrogate pair. -#[derive(Eq, Ord, PartialEq, PartialOrd)] -#[repr(transparent)] -pub struct Wtf8 { - bytes: [u8], -} - -impl AsInner<[u8]> for Wtf8 { - #[inline] - fn as_inner(&self) -> &[u8] { - &self.bytes - } -} - -/// Format the slice with double quotes, -/// and surrogates as `\u` followed by four hexadecimal digits. -/// Example: `"a\u{D800}"` for a slice with code points [U+0061, U+D800] -impl fmt::Debug for Wtf8 { - fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - fn write_str_escaped(f: &mut fmt::Formatter<'_>, s: &str) -> fmt::Result { - use crate::fmt::Write; - for c in s.chars().flat_map(|c| c.escape_debug()) { - f.write_char(c)? - } - Ok(()) - } - - formatter.write_str("\"")?; - let mut pos = 0; - while let Some((surrogate_pos, surrogate)) = self.next_surrogate(pos) { - write_str_escaped(formatter, unsafe { - str::from_utf8_unchecked(&self.bytes[pos..surrogate_pos]) - })?; - write!(formatter, "\\u{{{:x}}}", surrogate)?; - pos = surrogate_pos + 3; - } - write_str_escaped(formatter, unsafe { str::from_utf8_unchecked(&self.bytes[pos..]) })?; - formatter.write_str("\"") - } -} - -impl fmt::Display for Wtf8 { - fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result { - let wtf8_bytes = &self.bytes; - let mut pos = 0; - loop { - match self.next_surrogate(pos) { - Some((surrogate_pos, _)) => { - formatter.write_str(unsafe { - str::from_utf8_unchecked(&wtf8_bytes[pos..surrogate_pos]) - })?; - formatter.write_str(UTF8_REPLACEMENT_CHARACTER)?; - pos = surrogate_pos + 3; - } - None => { - let s = unsafe { str::from_utf8_unchecked(&wtf8_bytes[pos..]) }; - if pos == 0 { return s.fmt(formatter) } else { return formatter.write_str(s) } - } - } - } - } -} - -impl Wtf8 { - /// Creates a WTF-8 slice from a UTF-8 `&str` slice. - /// - /// Since WTF-8 is a superset of UTF-8, this always succeeds. - #[inline] - pub fn from_str(value: &str) -> &Wtf8 { - unsafe { Wtf8::from_bytes_unchecked(value.as_bytes()) } - } - - /// Creates a WTF-8 slice from a WTF-8 byte slice. - /// - /// Since the byte slice is not checked for valid WTF-8, this functions is - /// marked unsafe. - #[inline] - pub unsafe fn from_bytes_unchecked(value: &[u8]) -> &Wtf8 { - mem::transmute(value) - } - - /// Creates a mutable WTF-8 slice from a mutable WTF-8 byte slice. - /// - /// Since the byte slice is not checked for valid WTF-8, this functions is - /// marked unsafe. - #[inline] - unsafe fn from_mut_bytes_unchecked(value: &mut [u8]) -> &mut Wtf8 { - mem::transmute(value) - } - - /// Returns the length, in WTF-8 bytes. - #[inline] - pub fn len(&self) -> usize { - self.bytes.len() - } - - #[inline] - pub fn is_empty(&self) -> bool { - self.bytes.is_empty() - } - - /// Returns the code point at `position` if it is in the ASCII range, - /// or `b'\xFF'` otherwise. - /// - /// # Panics - /// - /// Panics if `position` is beyond the end of the string. - #[inline] - pub fn ascii_byte_at(&self, position: usize) -> u8 { - match self.bytes[position] { - ascii_byte @ 0x00..=0x7F => ascii_byte, - _ => 0xFF, - } - } - - /// Returns an iterator for the string’s code points. - #[inline] - pub fn code_points(&self) -> Wtf8CodePoints<'_> { - Wtf8CodePoints { bytes: self.bytes.iter() } - } - - /// Access raw bytes of WTF-8 data - #[inline] - pub fn as_bytes(&self) -> &[u8] { - &self.bytes - } - - /// Tries to convert the string to UTF-8 and return a `&str` slice. - /// - /// Returns `None` if the string contains surrogates. - /// - /// This does not copy the data. - #[inline] - pub fn as_str(&self) -> Result<&str, str::Utf8Error> { - str::from_utf8(&self.bytes) - } - - /// Creates an owned `Wtf8Buf` from a borrowed `Wtf8`. - pub fn to_owned(&self) -> Wtf8Buf { - Wtf8Buf { bytes: self.bytes.to_vec(), is_known_utf8: false } - } - - /// Lossily converts the string to UTF-8. - /// Returns a UTF-8 `&str` slice if the contents are well-formed in UTF-8. - /// - /// Surrogates are replaced with `"\u{FFFD}"` (the replacement character “�”). - /// - /// This only copies the data if necessary (if it contains any surrogate). - pub fn to_string_lossy(&self) -> Cow<'_, str> { - let surrogate_pos = match self.next_surrogate(0) { - None => return Cow::Borrowed(unsafe { str::from_utf8_unchecked(&self.bytes) }), - Some((pos, _)) => pos, - }; - let wtf8_bytes = &self.bytes; - let mut utf8_bytes = Vec::with_capacity(self.len()); - utf8_bytes.extend_from_slice(&wtf8_bytes[..surrogate_pos]); - utf8_bytes.extend_from_slice(UTF8_REPLACEMENT_CHARACTER.as_bytes()); - let mut pos = surrogate_pos + 3; - loop { - match self.next_surrogate(pos) { - Some((surrogate_pos, _)) => { - utf8_bytes.extend_from_slice(&wtf8_bytes[pos..surrogate_pos]); - utf8_bytes.extend_from_slice(UTF8_REPLACEMENT_CHARACTER.as_bytes()); - pos = surrogate_pos + 3; - } - None => { - utf8_bytes.extend_from_slice(&wtf8_bytes[pos..]); - return Cow::Owned(unsafe { String::from_utf8_unchecked(utf8_bytes) }); - } - } - } - } - - /// Converts the WTF-8 string to potentially ill-formed UTF-16 - /// and return an iterator of 16-bit code units. - /// - /// This is lossless: - /// calling `Wtf8Buf::from_ill_formed_utf16` on the resulting code units - /// would always return the original WTF-8 string. - #[inline] - pub fn encode_wide(&self) -> EncodeWide<'_> { - EncodeWide { code_points: self.code_points(), extra: 0 } - } - - #[inline] - fn next_surrogate(&self, mut pos: usize) -> Option<(usize, u16)> { - let mut iter = self.bytes[pos..].iter(); - loop { - let b = *iter.next()?; - if b < 0x80 { - pos += 1; - } else if b < 0xE0 { - iter.next(); - pos += 2; - } else if b == 0xED { - match (iter.next(), iter.next()) { - (Some(&b2), Some(&b3)) if b2 >= 0xA0 => { - return Some((pos, decode_surrogate(b2, b3))); - } - _ => pos += 3, - } - } else if b < 0xF0 { - iter.next(); - iter.next(); - pos += 3; - } else { - iter.next(); - iter.next(); - iter.next(); - pos += 4; - } - } - } - - #[inline] - fn final_lead_surrogate(&self) -> Option { - match self.bytes { - [.., 0xED, b2 @ 0xA0..=0xAF, b3] => Some(decode_surrogate(b2, b3)), - _ => None, - } - } - - #[inline] - fn initial_trail_surrogate(&self) -> Option { - match self.bytes { - [0xED, b2 @ 0xB0..=0xBF, b3, ..] => Some(decode_surrogate(b2, b3)), - _ => None, - } - } - - pub fn clone_into(&self, buf: &mut Wtf8Buf) { - buf.is_known_utf8 = false; - self.bytes.clone_into(&mut buf.bytes); - } - - /// Boxes this `Wtf8`. - #[inline] - pub fn into_box(&self) -> Box { - let boxed: Box<[u8]> = self.bytes.into(); - unsafe { mem::transmute(boxed) } - } - - /// Creates a boxed, empty `Wtf8`. - pub fn empty_box() -> Box { - let boxed: Box<[u8]> = Default::default(); - unsafe { mem::transmute(boxed) } - } - - #[inline] - pub fn into_arc(&self) -> Arc { - let arc: Arc<[u8]> = Arc::from(&self.bytes); - unsafe { Arc::from_raw(Arc::into_raw(arc) as *const Wtf8) } - } - - #[inline] - pub fn into_rc(&self) -> Rc { - let rc: Rc<[u8]> = Rc::from(&self.bytes); - unsafe { Rc::from_raw(Rc::into_raw(rc) as *const Wtf8) } - } - - #[inline] - pub fn make_ascii_lowercase(&mut self) { - self.bytes.make_ascii_lowercase() - } - - #[inline] - pub fn make_ascii_uppercase(&mut self) { - self.bytes.make_ascii_uppercase() - } - - #[inline] - pub fn to_ascii_lowercase(&self) -> Wtf8Buf { - Wtf8Buf { bytes: self.bytes.to_ascii_lowercase(), is_known_utf8: false } - } - - #[inline] - pub fn to_ascii_uppercase(&self) -> Wtf8Buf { - Wtf8Buf { bytes: self.bytes.to_ascii_uppercase(), is_known_utf8: false } - } - - #[inline] - pub fn is_ascii(&self) -> bool { - self.bytes.is_ascii() - } - - #[inline] - pub fn eq_ignore_ascii_case(&self, other: &Self) -> bool { - self.bytes.eq_ignore_ascii_case(&other.bytes) - } -} - -/// Returns a slice of the given string for the byte range \[`begin`..`end`). -/// -/// # Panics -/// -/// Panics when `begin` and `end` do not point to code point boundaries, -/// or point beyond the end of the string. -impl ops::Index> for Wtf8 { - type Output = Wtf8; - - #[inline] - fn index(&self, range: ops::Range) -> &Wtf8 { - // is_code_point_boundary checks that the index is in [0, .len()] - if range.start <= range.end - && is_code_point_boundary(self, range.start) - && is_code_point_boundary(self, range.end) - { - unsafe { slice_unchecked(self, range.start, range.end) } - } else { - slice_error_fail(self, range.start, range.end) - } - } -} - -/// Returns a slice of the given string from byte `begin` to its end. -/// -/// # Panics -/// -/// Panics when `begin` is not at a code point boundary, -/// or is beyond the end of the string. -impl ops::Index> for Wtf8 { - type Output = Wtf8; - - #[inline] - fn index(&self, range: ops::RangeFrom) -> &Wtf8 { - // is_code_point_boundary checks that the index is in [0, .len()] - if is_code_point_boundary(self, range.start) { - unsafe { slice_unchecked(self, range.start, self.len()) } - } else { - slice_error_fail(self, range.start, self.len()) - } - } -} - -/// Returns a slice of the given string from its beginning to byte `end`. -/// -/// # Panics -/// -/// Panics when `end` is not at a code point boundary, -/// or is beyond the end of the string. -impl ops::Index> for Wtf8 { - type Output = Wtf8; - - #[inline] - fn index(&self, range: ops::RangeTo) -> &Wtf8 { - // is_code_point_boundary checks that the index is in [0, .len()] - if is_code_point_boundary(self, range.end) { - unsafe { slice_unchecked(self, 0, range.end) } - } else { - slice_error_fail(self, 0, range.end) - } - } -} - -impl ops::Index for Wtf8 { - type Output = Wtf8; - - #[inline] - fn index(&self, _range: ops::RangeFull) -> &Wtf8 { - self - } -} - -#[inline] -fn decode_surrogate(second_byte: u8, third_byte: u8) -> u16 { - // The first byte is assumed to be 0xED - 0xD800 | (second_byte as u16 & 0x3F) << 6 | third_byte as u16 & 0x3F -} - -#[inline] -fn decode_surrogate_pair(lead: u16, trail: u16) -> char { - let code_point = 0x10000 + ((((lead - 0xD800) as u32) << 10) | (trail - 0xDC00) as u32); - unsafe { char::from_u32_unchecked(code_point) } -} - -/// Copied from str::is_char_boundary -#[inline] -pub fn is_code_point_boundary(slice: &Wtf8, index: usize) -> bool { - if index == 0 { - return true; - } - match slice.bytes.get(index) { - None => index == slice.len(), - Some(&b) => (b as i8) >= -0x40, - } -} - -/// Verify that `index` is at the edge of either a valid UTF-8 codepoint -/// (i.e. a codepoint that's not a surrogate) or of the whole string. -/// -/// These are the cases currently permitted by `OsStr::slice_encoded_bytes`. -/// Splitting between surrogates is valid as far as WTF-8 is concerned, but -/// we do not permit it in the public API because WTF-8 is considered an -/// implementation detail. -#[track_caller] -#[inline] -pub fn check_utf8_boundary(slice: &Wtf8, index: usize) { - if index == 0 { - return; - } - match slice.bytes.get(index) { - Some(0xED) => (), // Might be a surrogate - Some(&b) if (b as i8) >= -0x40 => return, - Some(_) => panic!("byte index {index} is not a codepoint boundary"), - None if index == slice.len() => return, - None => panic!("byte index {index} is out of bounds"), - } - if slice.bytes[index + 1] >= 0xA0 { - // There's a surrogate after index. Now check before index. - if index >= 3 && slice.bytes[index - 3] == 0xED && slice.bytes[index - 2] >= 0xA0 { - panic!("byte index {index} lies between surrogate codepoints"); - } - } -} - -/// Copied from core::str::raw::slice_unchecked -#[inline] -pub unsafe fn slice_unchecked(s: &Wtf8, begin: usize, end: usize) -> &Wtf8 { - // memory layout of a &[u8] and &Wtf8 are the same - Wtf8::from_bytes_unchecked(slice::from_raw_parts(s.bytes.as_ptr().add(begin), end - begin)) -} - -/// Copied from core::str::raw::slice_error_fail -#[inline(never)] -pub fn slice_error_fail(s: &Wtf8, begin: usize, end: usize) -> ! { - assert!(begin <= end); - panic!("index {begin} and/or {end} in `{s:?}` do not lie on character boundary"); -} - -/// Iterator for the code points of a WTF-8 string. -/// -/// Created with the method `.code_points()`. -#[derive(Clone)] -pub struct Wtf8CodePoints<'a> { - bytes: slice::Iter<'a, u8>, -} - -impl<'a> Iterator for Wtf8CodePoints<'a> { - type Item = CodePoint; - - #[inline] - fn next(&mut self) -> Option { - // SAFETY: `self.bytes` has been created from a WTF-8 string - unsafe { next_code_point(&mut self.bytes).map(|c| CodePoint { value: c }) } - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let len = self.bytes.len(); - (len.saturating_add(3) / 4, Some(len)) - } -} - -/// Generates a wide character sequence for potentially ill-formed UTF-16. -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Clone)] -pub struct EncodeWide<'a> { - code_points: Wtf8CodePoints<'a>, - extra: u16, -} - -// Copied from libunicode/u_str.rs -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a> Iterator for EncodeWide<'a> { - type Item = u16; - - #[inline] - fn next(&mut self) -> Option { - if self.extra != 0 { - let tmp = self.extra; - self.extra = 0; - return Some(tmp); - } - - let mut buf = [0; 2]; - self.code_points.next().map(|code_point| { - let n = encode_utf16_raw(code_point.value, &mut buf).len(); - if n == 2 { - self.extra = buf[1]; - } - buf[0] - }) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let (low, high) = self.code_points.size_hint(); - let ext = (self.extra != 0) as usize; - // every code point gets either one u16 or two u16, - // so this iterator is between 1 or 2 times as - // long as the underlying iterator. - (low + ext, high.and_then(|n| n.checked_mul(2)).and_then(|n| n.checked_add(ext))) - } -} - -#[stable(feature = "encode_wide_fused_iterator", since = "1.62.0")] -impl FusedIterator for EncodeWide<'_> {} - -impl Hash for CodePoint { - #[inline] - fn hash(&self, state: &mut H) { - self.value.hash(state) - } -} - -impl Hash for Wtf8Buf { - #[inline] - fn hash(&self, state: &mut H) { - state.write(&self.bytes); - 0xfeu8.hash(state) - } -} - -impl Hash for Wtf8 { - #[inline] - fn hash(&self, state: &mut H) { - state.write(&self.bytes); - 0xfeu8.hash(state) - } -} diff --git a/library/std/src/sys_common/wtf8/tests.rs b/library/std/src/sys_common/wtf8/tests.rs deleted file mode 100644 index 6a1cc41a8fb04..0000000000000 --- a/library/std/src/sys_common/wtf8/tests.rs +++ /dev/null @@ -1,727 +0,0 @@ -use super::*; - -#[test] -fn code_point_from_u32() { - assert!(CodePoint::from_u32(0).is_some()); - assert!(CodePoint::from_u32(0xD800).is_some()); - assert!(CodePoint::from_u32(0x10FFFF).is_some()); - assert!(CodePoint::from_u32(0x110000).is_none()); -} - -#[test] -fn code_point_to_u32() { - fn c(value: u32) -> CodePoint { - CodePoint::from_u32(value).unwrap() - } - assert_eq!(c(0).to_u32(), 0); - assert_eq!(c(0xD800).to_u32(), 0xD800); - assert_eq!(c(0x10FFFF).to_u32(), 0x10FFFF); -} - -#[test] -fn code_point_to_lead_surrogate() { - fn c(value: u32) -> CodePoint { - CodePoint::from_u32(value).unwrap() - } - assert_eq!(c(0).to_lead_surrogate(), None); - assert_eq!(c(0xE9).to_lead_surrogate(), None); - assert_eq!(c(0xD800).to_lead_surrogate(), Some(0xD800)); - assert_eq!(c(0xDBFF).to_lead_surrogate(), Some(0xDBFF)); - assert_eq!(c(0xDC00).to_lead_surrogate(), None); - assert_eq!(c(0xDFFF).to_lead_surrogate(), None); - assert_eq!(c(0x1F4A9).to_lead_surrogate(), None); - assert_eq!(c(0x10FFFF).to_lead_surrogate(), None); -} - -#[test] -fn code_point_to_trail_surrogate() { - fn c(value: u32) -> CodePoint { - CodePoint::from_u32(value).unwrap() - } - assert_eq!(c(0).to_trail_surrogate(), None); - assert_eq!(c(0xE9).to_trail_surrogate(), None); - assert_eq!(c(0xD800).to_trail_surrogate(), None); - assert_eq!(c(0xDBFF).to_trail_surrogate(), None); - assert_eq!(c(0xDC00).to_trail_surrogate(), Some(0xDC00)); - assert_eq!(c(0xDFFF).to_trail_surrogate(), Some(0xDFFF)); - assert_eq!(c(0x1F4A9).to_trail_surrogate(), None); - assert_eq!(c(0x10FFFF).to_trail_surrogate(), None); -} - -#[test] -fn code_point_from_char() { - assert_eq!(CodePoint::from_char('a').to_u32(), 0x61); - assert_eq!(CodePoint::from_char('💩').to_u32(), 0x1F4A9); -} - -#[test] -fn code_point_to_string() { - assert_eq!(format!("{:?}", CodePoint::from_char('a')), "U+0061"); - assert_eq!(format!("{:?}", CodePoint::from_char('💩')), "U+1F4A9"); -} - -#[test] -fn code_point_to_char() { - fn c(value: u32) -> CodePoint { - CodePoint::from_u32(value).unwrap() - } - assert_eq!(c(0x61).to_char(), Some('a')); - assert_eq!(c(0x1F4A9).to_char(), Some('💩')); - assert_eq!(c(0xD800).to_char(), None); -} - -#[test] -fn code_point_to_char_lossy() { - fn c(value: u32) -> CodePoint { - CodePoint::from_u32(value).unwrap() - } - assert_eq!(c(0x61).to_char_lossy(), 'a'); - assert_eq!(c(0x1F4A9).to_char_lossy(), '💩'); - assert_eq!(c(0xD800).to_char_lossy(), '\u{FFFD}'); -} - -#[test] -fn wtf8buf_new() { - assert_eq!(Wtf8Buf::new().bytes, b""); -} - -#[test] -fn wtf8buf_from_str() { - assert_eq!(Wtf8Buf::from_str("").bytes, b""); - assert_eq!(Wtf8Buf::from_str("aé 💩").bytes, b"a\xC3\xA9 \xF0\x9F\x92\xA9"); -} - -#[test] -fn wtf8buf_from_string() { - assert_eq!(Wtf8Buf::from_string(String::from("")).bytes, b""); - assert_eq!(Wtf8Buf::from_string(String::from("aé 💩")).bytes, b"a\xC3\xA9 \xF0\x9F\x92\xA9"); -} - -#[test] -fn wtf8buf_from_wide() { - let buf = Wtf8Buf::from_wide(&[]); - assert_eq!(buf.bytes, b""); - assert!(buf.is_known_utf8); - - let buf = Wtf8Buf::from_wide(&[0x61, 0xE9, 0x20, 0xD83D, 0xDCA9]); - assert_eq!(buf.bytes, b"a\xC3\xA9 \xF0\x9F\x92\xA9"); - assert!(buf.is_known_utf8); - - let buf = Wtf8Buf::from_wide(&[0x61, 0xE9, 0x20, 0xD83D, 0xD83D, 0xDCA9]); - assert_eq!(buf.bytes, b"a\xC3\xA9 \xED\xA0\xBD\xF0\x9F\x92\xA9"); - assert!(!buf.is_known_utf8); - - let buf = Wtf8Buf::from_wide(&[0xD800]); - assert_eq!(buf.bytes, b"\xED\xA0\x80"); - assert!(!buf.is_known_utf8); - - let buf = Wtf8Buf::from_wide(&[0xDBFF]); - assert_eq!(buf.bytes, b"\xED\xAF\xBF"); - assert!(!buf.is_known_utf8); - - let buf = Wtf8Buf::from_wide(&[0xDC00]); - assert_eq!(buf.bytes, b"\xED\xB0\x80"); - assert!(!buf.is_known_utf8); - - let buf = Wtf8Buf::from_wide(&[0xDFFF]); - assert_eq!(buf.bytes, b"\xED\xBF\xBF"); - assert!(!buf.is_known_utf8); -} - -#[test] -fn wtf8buf_push_str() { - let mut string = Wtf8Buf::new(); - assert_eq!(string.bytes, b""); - assert!(string.is_known_utf8); - - string.push_str("aé 💩"); - assert_eq!(string.bytes, b"a\xC3\xA9 \xF0\x9F\x92\xA9"); - assert!(string.is_known_utf8); -} - -#[test] -fn wtf8buf_push_char() { - let mut string = Wtf8Buf::from_str("aé "); - assert_eq!(string.bytes, b"a\xC3\xA9 "); - assert!(string.is_known_utf8); - - string.push_char('💩'); - assert_eq!(string.bytes, b"a\xC3\xA9 \xF0\x9F\x92\xA9"); - assert!(string.is_known_utf8); -} - -#[test] -fn wtf8buf_push() { - let mut string = Wtf8Buf::from_str("aé "); - assert_eq!(string.bytes, b"a\xC3\xA9 "); - assert!(string.is_known_utf8); - - string.push(CodePoint::from_char('💩')); - assert_eq!(string.bytes, b"a\xC3\xA9 \xF0\x9F\x92\xA9"); - assert!(string.is_known_utf8); - - fn c(value: u32) -> CodePoint { - CodePoint::from_u32(value).unwrap() - } - - let mut string = Wtf8Buf::new(); - string.push(c(0xD83D)); // lead - assert!(!string.is_known_utf8); - string.push(c(0xDCA9)); // trail - assert_eq!(string.bytes, b"\xF0\x9F\x92\xA9"); // Magic! - - let mut string = Wtf8Buf::new(); - string.push(c(0xD83D)); // lead - assert!(!string.is_known_utf8); - string.push(c(0x20)); // not surrogate - string.push(c(0xDCA9)); // trail - assert_eq!(string.bytes, b"\xED\xA0\xBD \xED\xB2\xA9"); - - let mut string = Wtf8Buf::new(); - string.push(c(0xD800)); // lead - assert!(!string.is_known_utf8); - string.push(c(0xDBFF)); // lead - assert_eq!(string.bytes, b"\xED\xA0\x80\xED\xAF\xBF"); - - let mut string = Wtf8Buf::new(); - string.push(c(0xD800)); // lead - assert!(!string.is_known_utf8); - string.push(c(0xE000)); // not surrogate - assert_eq!(string.bytes, b"\xED\xA0\x80\xEE\x80\x80"); - - let mut string = Wtf8Buf::new(); - string.push(c(0xD7FF)); // not surrogate - assert!(string.is_known_utf8); - string.push(c(0xDC00)); // trail - assert!(!string.is_known_utf8); - assert_eq!(string.bytes, b"\xED\x9F\xBF\xED\xB0\x80"); - - let mut string = Wtf8Buf::new(); - string.push(c(0x61)); // not surrogate, < 3 bytes - assert!(string.is_known_utf8); - string.push(c(0xDC00)); // trail - assert!(!string.is_known_utf8); - assert_eq!(string.bytes, b"\x61\xED\xB0\x80"); - - let mut string = Wtf8Buf::new(); - string.push(c(0xDC00)); // trail - assert!(!string.is_known_utf8); - assert_eq!(string.bytes, b"\xED\xB0\x80"); -} - -#[test] -fn wtf8buf_push_wtf8() { - let mut string = Wtf8Buf::from_str("aé"); - assert_eq!(string.bytes, b"a\xC3\xA9"); - string.push_wtf8(Wtf8::from_str(" 💩")); - assert_eq!(string.bytes, b"a\xC3\xA9 \xF0\x9F\x92\xA9"); - assert!(string.is_known_utf8); - - fn w(v: &[u8]) -> &Wtf8 { - unsafe { Wtf8::from_bytes_unchecked(v) } - } - - let mut string = Wtf8Buf::new(); - string.push_wtf8(w(b"\xED\xA0\xBD")); // lead - string.push_wtf8(w(b"\xED\xB2\xA9")); // trail - assert_eq!(string.bytes, b"\xF0\x9F\x92\xA9"); // Magic! - - let mut string = Wtf8Buf::new(); - string.push_wtf8(w(b"\xED\xA0\xBD")); // lead - string.push_wtf8(w(b" ")); // not surrogate - string.push_wtf8(w(b"\xED\xB2\xA9")); // trail - assert_eq!(string.bytes, b"\xED\xA0\xBD \xED\xB2\xA9"); - assert!(!string.is_known_utf8); - - let mut string = Wtf8Buf::new(); - string.push_wtf8(w(b"\xED\xA0\x80")); // lead - string.push_wtf8(w(b"\xED\xAF\xBF")); // lead - assert_eq!(string.bytes, b"\xED\xA0\x80\xED\xAF\xBF"); - assert!(!string.is_known_utf8); - - let mut string = Wtf8Buf::new(); - string.push_wtf8(w(b"\xED\xA0\x80")); // lead - string.push_wtf8(w(b"\xEE\x80\x80")); // not surrogate - assert_eq!(string.bytes, b"\xED\xA0\x80\xEE\x80\x80"); - assert!(!string.is_known_utf8); - - let mut string = Wtf8Buf::new(); - string.push_wtf8(w(b"\xED\x9F\xBF")); // not surrogate - string.push_wtf8(w(b"\xED\xB0\x80")); // trail - assert_eq!(string.bytes, b"\xED\x9F\xBF\xED\xB0\x80"); - assert!(!string.is_known_utf8); - - let mut string = Wtf8Buf::new(); - string.push_wtf8(w(b"a")); // not surrogate, < 3 bytes - string.push_wtf8(w(b"\xED\xB0\x80")); // trail - assert_eq!(string.bytes, b"\x61\xED\xB0\x80"); - assert!(!string.is_known_utf8); - - let mut string = Wtf8Buf::new(); - string.push_wtf8(w(b"\xED\xB0\x80")); // trail - assert_eq!(string.bytes, b"\xED\xB0\x80"); - assert!(!string.is_known_utf8); -} - -#[test] -fn wtf8buf_truncate() { - let mut string = Wtf8Buf::from_str("aé"); - assert!(string.is_known_utf8); - - string.truncate(3); - assert_eq!(string.bytes, b"a\xC3\xA9"); - assert!(string.is_known_utf8); - - string.truncate(1); - assert_eq!(string.bytes, b"a"); - assert!(string.is_known_utf8); - - string.truncate(0); - assert_eq!(string.bytes, b""); - assert!(string.is_known_utf8); -} - -#[test] -fn wtf8buf_truncate_around_non_bmp() { - let mut string = Wtf8Buf::from_str("💩"); - assert!(string.is_known_utf8); - - string.truncate(4); - assert_eq!(string.bytes, b"\xF0\x9F\x92\xA9"); - assert!(string.is_known_utf8); - - string.truncate(0); - assert_eq!(string.bytes, b""); - assert!(string.is_known_utf8); -} - -#[test] -#[should_panic] -fn wtf8buf_truncate_fail_code_point_boundary() { - let mut string = Wtf8Buf::from_str("aé"); - string.truncate(2); -} - -#[test] -#[should_panic] -fn wtf8buf_truncate_fail_longer() { - let mut string = Wtf8Buf::from_str("aé"); - string.truncate(4); -} - -#[test] -#[should_panic] -fn wtf8buf_truncate_splitting_non_bmp3() { - let mut string = Wtf8Buf::from_str("💩"); - assert!(string.is_known_utf8); - string.truncate(3); -} - -#[test] -#[should_panic] -fn wtf8buf_truncate_splitting_non_bmp2() { - let mut string = Wtf8Buf::from_str("💩"); - assert!(string.is_known_utf8); - string.truncate(2); -} - -#[test] -#[should_panic] -fn wtf8buf_truncate_splitting_non_bmp1() { - let mut string = Wtf8Buf::from_str("💩"); - assert!(string.is_known_utf8); - string.truncate(1); -} - -#[test] -fn wtf8buf_into_string() { - let mut string = Wtf8Buf::from_str("aé 💩"); - assert!(string.is_known_utf8); - assert_eq!(string.clone().into_string(), Ok(String::from("aé 💩"))); - string.push(CodePoint::from_u32(0xD800).unwrap()); - assert!(!string.is_known_utf8); - assert_eq!(string.clone().into_string(), Err(string)); -} - -#[test] -fn wtf8buf_into_string_lossy() { - let mut string = Wtf8Buf::from_str("aé 💩"); - assert_eq!(string.clone().into_string_lossy(), String::from("aé 💩")); - string.push(CodePoint::from_u32(0xD800).unwrap()); - assert_eq!(string.clone().into_string_lossy(), String::from("aé 💩�")); -} - -#[test] -fn wtf8buf_from_iterator() { - fn f(values: &[u32]) -> Wtf8Buf { - values.iter().map(|&c| CodePoint::from_u32(c).unwrap()).collect::() - } - assert_eq!( - f(&[0x61, 0xE9, 0x20, 0x1F4A9]), - Wtf8Buf { bytes: b"a\xC3\xA9 \xF0\x9F\x92\xA9".to_vec(), is_known_utf8: true } - ); - - assert_eq!(f(&[0xD83D, 0xDCA9]).bytes, b"\xF0\x9F\x92\xA9"); // Magic! - assert_eq!( - f(&[0xD83D, 0x20, 0xDCA9]), - Wtf8Buf { bytes: b"\xED\xA0\xBD \xED\xB2\xA9".to_vec(), is_known_utf8: false } - ); - assert_eq!( - f(&[0xD800, 0xDBFF]), - Wtf8Buf { bytes: b"\xED\xA0\x80\xED\xAF\xBF".to_vec(), is_known_utf8: false } - ); - assert_eq!( - f(&[0xD800, 0xE000]), - Wtf8Buf { bytes: b"\xED\xA0\x80\xEE\x80\x80".to_vec(), is_known_utf8: false } - ); - assert_eq!( - f(&[0xD7FF, 0xDC00]), - Wtf8Buf { bytes: b"\xED\x9F\xBF\xED\xB0\x80".to_vec(), is_known_utf8: false } - ); - assert_eq!( - f(&[0x61, 0xDC00]), - Wtf8Buf { bytes: b"\x61\xED\xB0\x80".to_vec(), is_known_utf8: false } - ); - assert_eq!(f(&[0xDC00]), Wtf8Buf { bytes: b"\xED\xB0\x80".to_vec(), is_known_utf8: false }); -} - -#[test] -fn wtf8buf_extend() { - fn e(initial: &[u32], extended: &[u32]) -> Wtf8Buf { - fn c(value: &u32) -> CodePoint { - CodePoint::from_u32(*value).unwrap() - } - let mut string = initial.iter().map(c).collect::(); - string.extend(extended.iter().map(c)); - string - } - - assert_eq!( - e(&[0x61, 0xE9], &[0x20, 0x1F4A9]), - Wtf8Buf { bytes: b"a\xC3\xA9 \xF0\x9F\x92\xA9".to_vec(), is_known_utf8: true } - ); - - assert_eq!(e(&[0xD83D], &[0xDCA9]).bytes, b"\xF0\x9F\x92\xA9"); // Magic! - assert_eq!( - e(&[0xD83D, 0x20], &[0xDCA9]), - Wtf8Buf { bytes: b"\xED\xA0\xBD \xED\xB2\xA9".to_vec(), is_known_utf8: false } - ); - assert_eq!( - e(&[0xD800], &[0xDBFF]), - Wtf8Buf { bytes: b"\xED\xA0\x80\xED\xAF\xBF".to_vec(), is_known_utf8: false } - ); - assert_eq!( - e(&[0xD800], &[0xE000]), - Wtf8Buf { bytes: b"\xED\xA0\x80\xEE\x80\x80".to_vec(), is_known_utf8: false } - ); - assert_eq!( - e(&[0xD7FF], &[0xDC00]), - Wtf8Buf { bytes: b"\xED\x9F\xBF\xED\xB0\x80".to_vec(), is_known_utf8: false } - ); - assert_eq!( - e(&[0x61], &[0xDC00]), - Wtf8Buf { bytes: b"\x61\xED\xB0\x80".to_vec(), is_known_utf8: false } - ); - assert_eq!( - e(&[], &[0xDC00]), - Wtf8Buf { bytes: b"\xED\xB0\x80".to_vec(), is_known_utf8: false } - ); -} - -#[test] -fn wtf8buf_show() { - let mut string = Wtf8Buf::from_str("a\té \u{7f}💩\r"); - string.push(CodePoint::from_u32(0xD800).unwrap()); - assert_eq!(format!("{string:?}"), "\"a\\té \\u{7f}\u{1f4a9}\\r\\u{d800}\""); -} - -#[test] -fn wtf8buf_as_slice() { - assert_eq!(Wtf8Buf::from_str("aé").as_slice(), Wtf8::from_str("aé")); -} - -#[test] -fn wtf8buf_show_str() { - let text = "a\té 💩\r"; - let string = Wtf8Buf::from_str(text); - assert_eq!(format!("{text:?}"), format!("{string:?}")); -} - -#[test] -fn wtf8_from_str() { - assert_eq!(&Wtf8::from_str("").bytes, b""); - assert_eq!(&Wtf8::from_str("aé 💩").bytes, b"a\xC3\xA9 \xF0\x9F\x92\xA9"); -} - -#[test] -fn wtf8_len() { - assert_eq!(Wtf8::from_str("").len(), 0); - assert_eq!(Wtf8::from_str("aé 💩").len(), 8); -} - -#[test] -fn wtf8_slice() { - assert_eq!(&Wtf8::from_str("aé 💩")[1..4].bytes, b"\xC3\xA9 "); -} - -#[test] -#[should_panic] -fn wtf8_slice_not_code_point_boundary() { - let _ = &Wtf8::from_str("aé 💩")[2..4]; -} - -#[test] -fn wtf8_slice_from() { - assert_eq!(&Wtf8::from_str("aé 💩")[1..].bytes, b"\xC3\xA9 \xF0\x9F\x92\xA9"); -} - -#[test] -#[should_panic] -fn wtf8_slice_from_not_code_point_boundary() { - let _ = &Wtf8::from_str("aé 💩")[2..]; -} - -#[test] -fn wtf8_slice_to() { - assert_eq!(&Wtf8::from_str("aé 💩")[..4].bytes, b"a\xC3\xA9 "); -} - -#[test] -#[should_panic] -fn wtf8_slice_to_not_code_point_boundary() { - let _ = &Wtf8::from_str("aé 💩")[5..]; -} - -#[test] -fn wtf8_ascii_byte_at() { - let slice = Wtf8::from_str("aé 💩"); - assert_eq!(slice.ascii_byte_at(0), b'a'); - assert_eq!(slice.ascii_byte_at(1), b'\xFF'); - assert_eq!(slice.ascii_byte_at(2), b'\xFF'); - assert_eq!(slice.ascii_byte_at(3), b' '); - assert_eq!(slice.ascii_byte_at(4), b'\xFF'); -} - -#[test] -fn wtf8_code_points() { - fn c(value: u32) -> CodePoint { - CodePoint::from_u32(value).unwrap() - } - fn cp(string: &Wtf8Buf) -> Vec> { - string.code_points().map(|c| c.to_char()).collect::>() - } - let mut string = Wtf8Buf::from_str("é "); - assert_eq!(cp(&string), [Some('é'), Some(' ')]); - string.push(c(0xD83D)); - assert_eq!(cp(&string), [Some('é'), Some(' '), None]); - string.push(c(0xDCA9)); - assert_eq!(cp(&string), [Some('é'), Some(' '), Some('💩')]); -} - -#[test] -fn wtf8_as_str() { - assert_eq!(Wtf8::from_str("").as_str(), Ok("")); - assert_eq!(Wtf8::from_str("aé 💩").as_str(), Ok("aé 💩")); - let mut string = Wtf8Buf::new(); - string.push(CodePoint::from_u32(0xD800).unwrap()); - assert!(string.as_str().is_err()); -} - -#[test] -fn wtf8_to_string_lossy() { - assert_eq!(Wtf8::from_str("").to_string_lossy(), Cow::Borrowed("")); - assert_eq!(Wtf8::from_str("aé 💩").to_string_lossy(), Cow::Borrowed("aé 💩")); - let mut string = Wtf8Buf::from_str("aé 💩"); - string.push(CodePoint::from_u32(0xD800).unwrap()); - let expected: Cow<'_, str> = Cow::Owned(String::from("aé 💩�")); - assert_eq!(string.to_string_lossy(), expected); -} - -#[test] -fn wtf8_display() { - fn d(b: &[u8]) -> String { - (&unsafe { Wtf8::from_bytes_unchecked(b) }).to_string() - } - - assert_eq!("", d("".as_bytes())); - assert_eq!("aé 💩", d("aé 💩".as_bytes())); - - let mut string = Wtf8Buf::from_str("aé 💩"); - string.push(CodePoint::from_u32(0xD800).unwrap()); - assert_eq!("aé 💩�", d(string.as_inner())); -} - -#[test] -fn wtf8_encode_wide() { - let mut string = Wtf8Buf::from_str("aé "); - string.push(CodePoint::from_u32(0xD83D).unwrap()); - string.push_char('💩'); - assert_eq!( - string.encode_wide().collect::>(), - vec![0x61, 0xE9, 0x20, 0xD83D, 0xD83D, 0xDCA9] - ); -} - -#[test] -fn wtf8_encode_wide_size_hint() { - let string = Wtf8Buf::from_str("\u{12345}"); - let mut iter = string.encode_wide(); - assert_eq!((1, Some(8)), iter.size_hint()); - iter.next().unwrap(); - assert_eq!((1, Some(1)), iter.size_hint()); - iter.next().unwrap(); - assert_eq!((0, Some(0)), iter.size_hint()); - assert!(iter.next().is_none()); -} - -#[test] -fn wtf8_clone_into() { - let mut string = Wtf8Buf::new(); - Wtf8::from_str("green").clone_into(&mut string); - assert_eq!(string.bytes, b"green"); - - let mut string = Wtf8Buf::from_str("green"); - Wtf8::from_str("").clone_into(&mut string); - assert_eq!(string.bytes, b""); - - let mut string = Wtf8Buf::from_str("red"); - Wtf8::from_str("green").clone_into(&mut string); - assert_eq!(string.bytes, b"green"); - - let mut string = Wtf8Buf::from_str("green"); - Wtf8::from_str("red").clone_into(&mut string); - assert_eq!(string.bytes, b"red"); - - let mut string = Wtf8Buf::from_str("green"); - assert!(string.is_known_utf8); - unsafe { Wtf8::from_bytes_unchecked(b"\xED\xA0\x80").clone_into(&mut string) }; - assert_eq!(string.bytes, b"\xED\xA0\x80"); - assert!(!string.is_known_utf8); -} - -#[test] -fn wtf8_to_ascii_lowercase() { - let lowercase = Wtf8::from_str("").to_ascii_lowercase(); - assert_eq!(lowercase.bytes, b""); - - let lowercase = Wtf8::from_str("GrEeN gRaPeS! 🍇").to_ascii_lowercase(); - assert_eq!(lowercase.bytes, b"green grapes! \xf0\x9f\x8d\x87"); - - let lowercase = unsafe { Wtf8::from_bytes_unchecked(b"\xED\xA0\x80").to_ascii_lowercase() }; - assert_eq!(lowercase.bytes, b"\xED\xA0\x80"); - assert!(!lowercase.is_known_utf8); -} - -#[test] -fn wtf8_to_ascii_uppercase() { - let uppercase = Wtf8::from_str("").to_ascii_uppercase(); - assert_eq!(uppercase.bytes, b""); - - let uppercase = Wtf8::from_str("GrEeN gRaPeS! 🍇").to_ascii_uppercase(); - assert_eq!(uppercase.bytes, b"GREEN GRAPES! \xf0\x9f\x8d\x87"); - - let uppercase = unsafe { Wtf8::from_bytes_unchecked(b"\xED\xA0\x80").to_ascii_uppercase() }; - assert_eq!(uppercase.bytes, b"\xED\xA0\x80"); - assert!(!uppercase.is_known_utf8); -} - -#[test] -fn wtf8_make_ascii_lowercase() { - let mut lowercase = Wtf8Buf::from_str(""); - lowercase.make_ascii_lowercase(); - assert_eq!(lowercase.bytes, b""); - - let mut lowercase = Wtf8Buf::from_str("GrEeN gRaPeS! 🍇"); - lowercase.make_ascii_lowercase(); - assert_eq!(lowercase.bytes, b"green grapes! \xf0\x9f\x8d\x87"); - - let mut lowercase = unsafe { Wtf8::from_bytes_unchecked(b"\xED\xA0\x80").to_owned() }; - lowercase.make_ascii_lowercase(); - assert_eq!(lowercase.bytes, b"\xED\xA0\x80"); - assert!(!lowercase.is_known_utf8); -} - -#[test] -fn wtf8_make_ascii_uppercase() { - let mut uppercase = Wtf8Buf::from_str(""); - uppercase.make_ascii_uppercase(); - assert_eq!(uppercase.bytes, b""); - - let mut uppercase = Wtf8Buf::from_str("GrEeN gRaPeS! 🍇"); - uppercase.make_ascii_uppercase(); - assert_eq!(uppercase.bytes, b"GREEN GRAPES! \xf0\x9f\x8d\x87"); - - let mut uppercase = unsafe { Wtf8::from_bytes_unchecked(b"\xED\xA0\x80").to_owned() }; - uppercase.make_ascii_uppercase(); - assert_eq!(uppercase.bytes, b"\xED\xA0\x80"); - assert!(!uppercase.is_known_utf8); -} - -#[test] -fn wtf8_to_owned() { - let string = unsafe { Wtf8::from_bytes_unchecked(b"\xED\xA0\x80").to_owned() }; - assert_eq!(string.bytes, b"\xED\xA0\x80"); - assert!(!string.is_known_utf8); -} - -#[test] -fn wtf8_valid_utf8_boundaries() { - let mut string = Wtf8Buf::from_str("aé 💩"); - string.push(CodePoint::from_u32(0xD800).unwrap()); - string.push(CodePoint::from_u32(0xD800).unwrap()); - check_utf8_boundary(&string, 0); - check_utf8_boundary(&string, 1); - check_utf8_boundary(&string, 3); - check_utf8_boundary(&string, 4); - check_utf8_boundary(&string, 8); - check_utf8_boundary(&string, 14); - assert_eq!(string.len(), 14); - - string.push_char('a'); - check_utf8_boundary(&string, 14); - check_utf8_boundary(&string, 15); - - let mut string = Wtf8Buf::from_str("a"); - string.push(CodePoint::from_u32(0xD800).unwrap()); - check_utf8_boundary(&string, 1); - - let mut string = Wtf8Buf::from_str("\u{D7FF}"); - string.push(CodePoint::from_u32(0xD800).unwrap()); - check_utf8_boundary(&string, 3); - - let mut string = Wtf8Buf::new(); - string.push(CodePoint::from_u32(0xD800).unwrap()); - string.push_char('\u{D7FF}'); - check_utf8_boundary(&string, 3); -} - -#[test] -#[should_panic(expected = "byte index 4 is out of bounds")] -fn wtf8_utf8_boundary_out_of_bounds() { - let string = Wtf8::from_str("aé"); - check_utf8_boundary(&string, 4); -} - -#[test] -#[should_panic(expected = "byte index 1 is not a codepoint boundary")] -fn wtf8_utf8_boundary_inside_codepoint() { - let string = Wtf8::from_str("é"); - check_utf8_boundary(&string, 1); -} - -#[test] -#[should_panic(expected = "byte index 1 is not a codepoint boundary")] -fn wtf8_utf8_boundary_inside_surrogate() { - let mut string = Wtf8Buf::new(); - string.push(CodePoint::from_u32(0xD800).unwrap()); - check_utf8_boundary(&string, 1); -} - -#[test] -#[should_panic(expected = "byte index 3 lies between surrogate codepoints")] -fn wtf8_utf8_boundary_between_surrogates() { - let mut string = Wtf8Buf::new(); - string.push(CodePoint::from_u32(0xD800).unwrap()); - string.push(CodePoint::from_u32(0xD800).unwrap()); - check_utf8_boundary(&string, 3); -} diff --git a/library/std/src/thread/local.rs b/library/std/src/thread/local.rs deleted file mode 100644 index c1b4440e56088..0000000000000 --- a/library/std/src/thread/local.rs +++ /dev/null @@ -1,616 +0,0 @@ -//! Thread local storage - -#![unstable(feature = "thread_local_internals", issue = "none")] - -#[cfg(all(test, not(target_os = "emscripten")))] -mod tests; - -#[cfg(test)] -mod dynamic_tests; - -use crate::cell::{Cell, RefCell}; -use crate::error::Error; -use crate::fmt; - -/// A thread local storage key which owns its contents. -/// -/// This key uses the fastest possible implementation available to it for the -/// target platform. It is instantiated with the [`thread_local!`] macro and the -/// primary method is the [`with`] method, though there are helpers to make -/// working with [`Cell`] types easier. -/// -/// The [`with`] method yields a reference to the contained value which cannot -/// outlive the current thread or escape the given closure. -/// -/// [`thread_local!`]: crate::thread_local -/// -/// # Initialization and Destruction -/// -/// Initialization is dynamically performed on the first call to a setter (e.g. -/// [`with`]) within a thread, and values that implement [`Drop`] get -/// destructed when a thread exits. Some caveats apply, which are explained below. -/// -/// A `LocalKey`'s initializer cannot recursively depend on itself. Using a -/// `LocalKey` in this way may cause panics, aborts or infinite recursion on -/// the first call to `with`. -/// -/// # Single-thread Synchronization -/// -/// Though there is no potential race with other threads, it is still possible to -/// obtain multiple references to the thread-local data in different places on -/// the call stack. For this reason, only shared (`&T`) references may be obtained. -/// -/// To allow obtaining an exclusive mutable reference (`&mut T`), typically a -/// [`Cell`] or [`RefCell`] is used (see the [`std::cell`] for more information -/// on how exactly this works). To make this easier there are specialized -/// implementations for [`LocalKey>`] and [`LocalKey>`]. -/// -/// [`std::cell`]: `crate::cell` -/// [`LocalKey>`]: struct.LocalKey.html#impl-LocalKey> -/// [`LocalKey>`]: struct.LocalKey.html#impl-LocalKey> -/// -/// -/// # Examples -/// -/// ``` -/// use std::cell::Cell; -/// use std::thread; -/// -/// thread_local!(static FOO: Cell = Cell::new(1)); -/// -/// assert_eq!(FOO.get(), 1); -/// FOO.set(2); -/// -/// // each thread starts out with the initial value of 1 -/// let t = thread::spawn(move|| { -/// assert_eq!(FOO.get(), 1); -/// FOO.set(3); -/// }); -/// -/// // wait for the thread to complete and bail out on panic -/// t.join().unwrap(); -/// -/// // we retain our original value of 2 despite the child thread -/// assert_eq!(FOO.get(), 2); -/// ``` -/// -/// # Platform-specific behavior -/// -/// Note that a "best effort" is made to ensure that destructors for types -/// stored in thread local storage are run, but not all platforms can guarantee -/// that destructors will be run for all types in thread local storage. For -/// example, there are a number of known caveats where destructors are not run: -/// -/// 1. On Unix systems when pthread-based TLS is being used, destructors will -/// not be run for TLS values on the main thread when it exits. Note that the -/// application will exit immediately after the main thread exits as well. -/// 2. On all platforms it's possible for TLS to re-initialize other TLS slots -/// during destruction. Some platforms ensure that this cannot happen -/// infinitely by preventing re-initialization of any slot that has been -/// destroyed, but not all platforms have this guard. Those platforms that do -/// not guard typically have a synthetic limit after which point no more -/// destructors are run. -/// 3. When the process exits on Windows systems, TLS destructors may only be -/// run on the thread that causes the process to exit. This is because the -/// other threads may be forcibly terminated. -/// -/// ## Synchronization in thread-local destructors -/// -/// On Windows, synchronization operations (such as [`JoinHandle::join`]) in -/// thread local destructors are prone to deadlocks and so should be avoided. -/// This is because the [loader lock] is held while a destructor is run. The -/// lock is acquired whenever a thread starts or exits or when a DLL is loaded -/// or unloaded. Therefore these events are blocked for as long as a thread -/// local destructor is running. -/// -/// [loader lock]: https://docs.microsoft.com/en-us/windows/win32/dlls/dynamic-link-library-best-practices -/// [`JoinHandle::join`]: crate::thread::JoinHandle::join -/// [`with`]: LocalKey::with -#[cfg_attr(not(test), rustc_diagnostic_item = "LocalKey")] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct LocalKey { - // This outer `LocalKey` type is what's going to be stored in statics, - // but actual data inside will sometimes be tagged with #[thread_local]. - // It's not valid for a true static to reference a #[thread_local] static, - // so we get around that by exposing an accessor through a layer of function - // indirection (this thunk). - // - // Note that the thunk is itself unsafe because the returned lifetime of the - // slot where data lives, `'static`, is not actually valid. The lifetime - // here is actually slightly shorter than the currently running thread! - // - // Although this is an extra layer of indirection, it should in theory be - // trivially devirtualizable by LLVM because the value of `inner` never - // changes and the constant should be readonly within a crate. This mainly - // only runs into problems when TLS statics are exported across crates. - inner: unsafe fn(Option<&mut Option>) -> Option<&'static T>, -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for LocalKey { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("LocalKey").finish_non_exhaustive() - } -} - -/// Declare a new thread local storage key of type [`std::thread::LocalKey`]. -/// -/// # Syntax -/// -/// The macro wraps any number of static declarations and makes them thread local. -/// Publicity and attributes for each static are allowed. Example: -/// -/// ``` -/// use std::cell::{Cell, RefCell}; -/// -/// thread_local! { -/// pub static FOO: Cell = Cell::new(1); -/// -/// static BAR: RefCell> = RefCell::new(vec![1.0, 2.0]); -/// } -/// -/// assert_eq!(FOO.get(), 1); -/// BAR.with_borrow(|v| assert_eq!(v[1], 2.0)); -/// ``` -/// -/// Note that only shared references (`&T`) to the inner data may be obtained, so a -/// type such as [`Cell`] or [`RefCell`] is typically used to allow mutating access. -/// -/// This macro supports a special `const {}` syntax that can be used -/// when the initialization expression can be evaluated as a constant. -/// This can enable a more efficient thread local implementation that -/// can avoid lazy initialization. For types that do not -/// [need to be dropped][crate::mem::needs_drop], this can enable an -/// even more efficient implementation that does not need to -/// track any additional state. -/// -/// ``` -/// use std::cell::RefCell; -/// -/// thread_local! { -/// pub static FOO: RefCell> = const { RefCell::new(Vec::new()) }; -/// } -/// -/// FOO.with_borrow(|v| assert_eq!(v.len(), 0)); -/// ``` -/// -/// See [`LocalKey` documentation][`std::thread::LocalKey`] for more -/// information. -/// -/// [`std::thread::LocalKey`]: crate::thread::LocalKey -#[macro_export] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "thread_local_macro")] -#[allow_internal_unstable(thread_local_internals)] -macro_rules! thread_local { - // empty (base case for the recursion) - () => {}; - - ($(#[$attr:meta])* $vis:vis static $name:ident: $t:ty = const $init:block; $($rest:tt)*) => ( - $crate::thread::local_impl::thread_local_inner!($(#[$attr])* $vis $name, $t, const $init); - $crate::thread_local!($($rest)*); - ); - - ($(#[$attr:meta])* $vis:vis static $name:ident: $t:ty = const $init:block) => ( - $crate::thread::local_impl::thread_local_inner!($(#[$attr])* $vis $name, $t, const $init); - ); - - // process multiple declarations - ($(#[$attr:meta])* $vis:vis static $name:ident: $t:ty = $init:expr; $($rest:tt)*) => ( - $crate::thread::local_impl::thread_local_inner!($(#[$attr])* $vis $name, $t, $init); - $crate::thread_local!($($rest)*); - ); - - // handle a single declaration - ($(#[$attr:meta])* $vis:vis static $name:ident: $t:ty = $init:expr) => ( - $crate::thread::local_impl::thread_local_inner!($(#[$attr])* $vis $name, $t, $init); - ); -} - -/// An error returned by [`LocalKey::try_with`](struct.LocalKey.html#method.try_with). -#[stable(feature = "thread_local_try_with", since = "1.26.0")] -#[non_exhaustive] -#[derive(Clone, Copy, Eq, PartialEq)] -pub struct AccessError; - -#[stable(feature = "thread_local_try_with", since = "1.26.0")] -impl fmt::Debug for AccessError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("AccessError").finish() - } -} - -#[stable(feature = "thread_local_try_with", since = "1.26.0")] -impl fmt::Display for AccessError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt("already destroyed", f) - } -} - -#[stable(feature = "thread_local_try_with", since = "1.26.0")] -impl Error for AccessError {} - -impl LocalKey { - #[doc(hidden)] - #[unstable( - feature = "thread_local_internals", - reason = "recently added to create a key", - issue = "none" - )] - #[rustc_const_unstable(feature = "thread_local_internals", issue = "none")] - pub const unsafe fn new( - inner: unsafe fn(Option<&mut Option>) -> Option<&'static T>, - ) -> LocalKey { - LocalKey { inner } - } - - /// Acquires a reference to the value in this TLS key. - /// - /// This will lazily initialize the value if this thread has not referenced - /// this key yet. - /// - /// # Panics - /// - /// This function will `panic!()` if the key currently has its - /// destructor running, and it **may** panic if the destructor has - /// previously been run for this thread. - #[stable(feature = "rust1", since = "1.0.0")] - pub fn with(&'static self, f: F) -> R - where - F: FnOnce(&T) -> R, - { - self.try_with(f).expect( - "cannot access a Thread Local Storage value \ - during or after destruction", - ) - } - - /// Acquires a reference to the value in this TLS key. - /// - /// This will lazily initialize the value if this thread has not referenced - /// this key yet. If the key has been destroyed (which may happen if this is called - /// in a destructor), this function will return an [`AccessError`]. - /// - /// # Panics - /// - /// This function will still `panic!()` if the key is uninitialized and the - /// key's initializer panics. - #[stable(feature = "thread_local_try_with", since = "1.26.0")] - #[inline] - pub fn try_with(&'static self, f: F) -> Result - where - F: FnOnce(&T) -> R, - { - // SAFETY: `inner` is safe to call within the lifetime of the thread - let thread_local = unsafe { (self.inner)(None).ok_or(AccessError)? }; - Ok(f(thread_local)) - } - - /// Acquires a reference to the value in this TLS key, initializing it with - /// `init` if it wasn't already initialized on this thread. - /// - /// If `init` was used to initialize the thread local variable, `None` is - /// passed as the first argument to `f`. If it was already initialized, - /// `Some(init)` is passed to `f`. - /// - /// # Panics - /// - /// This function will panic if the key currently has its destructor - /// running, and it **may** panic if the destructor has previously been run - /// for this thread. - fn initialize_with(&'static self, init: T, f: F) -> R - where - F: FnOnce(Option, &T) -> R, - { - let mut init = Some(init); - - // SAFETY: `inner` is safe to call within the lifetime of the thread - let reference = unsafe { - (self.inner)(Some(&mut init)).expect( - "cannot access a Thread Local Storage value \ - during or after destruction", - ) - }; - - f(init, reference) - } -} - -impl LocalKey> { - /// Sets or initializes the contained value. - /// - /// Unlike the other methods, this will *not* run the lazy initializer of - /// the thread local. Instead, it will be directly initialized with the - /// given value if it wasn't initialized yet. - /// - /// # Panics - /// - /// Panics if the key currently has its destructor running, - /// and it **may** panic if the destructor has previously been run for this thread. - /// - /// # Examples - /// - /// ``` - /// use std::cell::Cell; - /// - /// thread_local! { - /// static X: Cell = panic!("!"); - /// } - /// - /// // Calling X.get() here would result in a panic. - /// - /// X.set(123); // But X.set() is fine, as it skips the initializer above. - /// - /// assert_eq!(X.get(), 123); - /// ``` - #[stable(feature = "local_key_cell_methods", since = "1.73.0")] - pub fn set(&'static self, value: T) { - self.initialize_with(Cell::new(value), |value, cell| { - if let Some(value) = value { - // The cell was already initialized, so `value` wasn't used to - // initialize it. So we overwrite the current value with the - // new one instead. - cell.set(value.into_inner()); - } - }); - } - - /// Returns a copy of the contained value. - /// - /// This will lazily initialize the value if this thread has not referenced - /// this key yet. - /// - /// # Panics - /// - /// Panics if the key currently has its destructor running, - /// and it **may** panic if the destructor has previously been run for this thread. - /// - /// # Examples - /// - /// ``` - /// use std::cell::Cell; - /// - /// thread_local! { - /// static X: Cell = Cell::new(1); - /// } - /// - /// assert_eq!(X.get(), 1); - /// ``` - #[stable(feature = "local_key_cell_methods", since = "1.73.0")] - pub fn get(&'static self) -> T - where - T: Copy, - { - self.with(Cell::get) - } - - /// Takes the contained value, leaving `Default::default()` in its place. - /// - /// This will lazily initialize the value if this thread has not referenced - /// this key yet. - /// - /// # Panics - /// - /// Panics if the key currently has its destructor running, - /// and it **may** panic if the destructor has previously been run for this thread. - /// - /// # Examples - /// - /// ``` - /// use std::cell::Cell; - /// - /// thread_local! { - /// static X: Cell> = Cell::new(Some(1)); - /// } - /// - /// assert_eq!(X.take(), Some(1)); - /// assert_eq!(X.take(), None); - /// ``` - #[stable(feature = "local_key_cell_methods", since = "1.73.0")] - pub fn take(&'static self) -> T - where - T: Default, - { - self.with(Cell::take) - } - - /// Replaces the contained value, returning the old value. - /// - /// This will lazily initialize the value if this thread has not referenced - /// this key yet. - /// - /// # Panics - /// - /// Panics if the key currently has its destructor running, - /// and it **may** panic if the destructor has previously been run for this thread. - /// - /// # Examples - /// - /// ``` - /// use std::cell::Cell; - /// - /// thread_local! { - /// static X: Cell = Cell::new(1); - /// } - /// - /// assert_eq!(X.replace(2), 1); - /// assert_eq!(X.replace(3), 2); - /// ``` - #[stable(feature = "local_key_cell_methods", since = "1.73.0")] - #[rustc_confusables("swap")] - pub fn replace(&'static self, value: T) -> T { - self.with(|cell| cell.replace(value)) - } -} - -impl LocalKey> { - /// Acquires a reference to the contained value. - /// - /// This will lazily initialize the value if this thread has not referenced - /// this key yet. - /// - /// # Panics - /// - /// Panics if the value is currently mutably borrowed. - /// - /// Panics if the key currently has its destructor running, - /// and it **may** panic if the destructor has previously been run for this thread. - /// - /// # Example - /// - /// ``` - /// use std::cell::RefCell; - /// - /// thread_local! { - /// static X: RefCell> = RefCell::new(Vec::new()); - /// } - /// - /// X.with_borrow(|v| assert!(v.is_empty())); - /// ``` - #[stable(feature = "local_key_cell_methods", since = "1.73.0")] - pub fn with_borrow(&'static self, f: F) -> R - where - F: FnOnce(&T) -> R, - { - self.with(|cell| f(&cell.borrow())) - } - - /// Acquires a mutable reference to the contained value. - /// - /// This will lazily initialize the value if this thread has not referenced - /// this key yet. - /// - /// # Panics - /// - /// Panics if the value is currently borrowed. - /// - /// Panics if the key currently has its destructor running, - /// and it **may** panic if the destructor has previously been run for this thread. - /// - /// # Example - /// - /// ``` - /// use std::cell::RefCell; - /// - /// thread_local! { - /// static X: RefCell> = RefCell::new(Vec::new()); - /// } - /// - /// X.with_borrow_mut(|v| v.push(1)); - /// - /// X.with_borrow(|v| assert_eq!(*v, vec![1])); - /// ``` - #[stable(feature = "local_key_cell_methods", since = "1.73.0")] - pub fn with_borrow_mut(&'static self, f: F) -> R - where - F: FnOnce(&mut T) -> R, - { - self.with(|cell| f(&mut cell.borrow_mut())) - } - - /// Sets or initializes the contained value. - /// - /// Unlike the other methods, this will *not* run the lazy initializer of - /// the thread local. Instead, it will be directly initialized with the - /// given value if it wasn't initialized yet. - /// - /// # Panics - /// - /// Panics if the value is currently borrowed. - /// - /// Panics if the key currently has its destructor running, - /// and it **may** panic if the destructor has previously been run for this thread. - /// - /// # Examples - /// - /// ``` - /// use std::cell::RefCell; - /// - /// thread_local! { - /// static X: RefCell> = panic!("!"); - /// } - /// - /// // Calling X.with() here would result in a panic. - /// - /// X.set(vec![1, 2, 3]); // But X.set() is fine, as it skips the initializer above. - /// - /// X.with_borrow(|v| assert_eq!(*v, vec![1, 2, 3])); - /// ``` - #[stable(feature = "local_key_cell_methods", since = "1.73.0")] - pub fn set(&'static self, value: T) { - self.initialize_with(RefCell::new(value), |value, cell| { - if let Some(value) = value { - // The cell was already initialized, so `value` wasn't used to - // initialize it. So we overwrite the current value with the - // new one instead. - *cell.borrow_mut() = value.into_inner(); - } - }); - } - - /// Takes the contained value, leaving `Default::default()` in its place. - /// - /// This will lazily initialize the value if this thread has not referenced - /// this key yet. - /// - /// # Panics - /// - /// Panics if the value is currently borrowed. - /// - /// Panics if the key currently has its destructor running, - /// and it **may** panic if the destructor has previously been run for this thread. - /// - /// # Examples - /// - /// ``` - /// use std::cell::RefCell; - /// - /// thread_local! { - /// static X: RefCell> = RefCell::new(Vec::new()); - /// } - /// - /// X.with_borrow_mut(|v| v.push(1)); - /// - /// let a = X.take(); - /// - /// assert_eq!(a, vec![1]); - /// - /// X.with_borrow(|v| assert!(v.is_empty())); - /// ``` - #[stable(feature = "local_key_cell_methods", since = "1.73.0")] - pub fn take(&'static self) -> T - where - T: Default, - { - self.with(RefCell::take) - } - - /// Replaces the contained value, returning the old value. - /// - /// # Panics - /// - /// Panics if the value is currently borrowed. - /// - /// Panics if the key currently has its destructor running, - /// and it **may** panic if the destructor has previously been run for this thread. - /// - /// # Examples - /// - /// ``` - /// use std::cell::RefCell; - /// - /// thread_local! { - /// static X: RefCell> = RefCell::new(Vec::new()); - /// } - /// - /// let prev = X.replace(vec![1, 2, 3]); - /// assert!(prev.is_empty()); - /// - /// X.with_borrow(|v| assert_eq!(*v, vec![1, 2, 3])); - /// ``` - #[stable(feature = "local_key_cell_methods", since = "1.73.0")] - #[rustc_confusables("swap")] - pub fn replace(&'static self, value: T) -> T { - self.with(|cell| cell.replace(value)) - } -} diff --git a/library/std/src/thread/local/dynamic_tests.rs b/library/std/src/thread/local/dynamic_tests.rs deleted file mode 100644 index dd18004164824..0000000000000 --- a/library/std/src/thread/local/dynamic_tests.rs +++ /dev/null @@ -1,40 +0,0 @@ -use crate::cell::RefCell; -use crate::collections::HashMap; -use crate::thread_local; - -#[test] -fn smoke() { - fn square(i: i32) -> i32 { - i * i - } - thread_local!(static FOO: i32 = square(3)); - - FOO.with(|f| { - assert_eq!(*f, 9); - }); -} - -#[test] -fn hashmap() { - fn map() -> RefCell> { - let mut m = HashMap::new(); - m.insert(1, 2); - RefCell::new(m) - } - thread_local!(static FOO: RefCell> = map()); - - FOO.with(|map| { - assert_eq!(map.borrow()[&1], 2); - }); -} - -#[test] -fn refcell_vec() { - thread_local!(static FOO: RefCell> = RefCell::new(vec![1, 2, 3])); - - FOO.with(|vec| { - assert_eq!(vec.borrow().len(), 3); - vec.borrow_mut().push(4); - assert_eq!(vec.borrow()[3], 4); - }); -} diff --git a/library/std/src/thread/local/tests.rs b/library/std/src/thread/local/tests.rs deleted file mode 100644 index 25019b554bb6a..0000000000000 --- a/library/std/src/thread/local/tests.rs +++ /dev/null @@ -1,342 +0,0 @@ -use crate::cell::{Cell, UnsafeCell}; -use crate::sync::atomic::{AtomicU8, Ordering}; -use crate::sync::{Arc, Condvar, Mutex}; -use crate::thread::{self, LocalKey}; -use crate::thread_local; - -#[derive(Clone, Default)] -struct Signal(Arc<(Mutex, Condvar)>); - -impl Signal { - fn notify(&self) { - let (set, cvar) = &*self.0; - *set.lock().unwrap() = true; - cvar.notify_one(); - } - - fn wait(&self) { - let (set, cvar) = &*self.0; - let mut set = set.lock().unwrap(); - while !*set { - set = cvar.wait(set).unwrap(); - } - } -} - -struct NotifyOnDrop(Signal); - -impl Drop for NotifyOnDrop { - fn drop(&mut self) { - let NotifyOnDrop(ref f) = *self; - f.notify(); - } -} - -#[test] -fn smoke_no_dtor() { - thread_local!(static FOO: Cell = Cell::new(1)); - run(&FOO); - thread_local!(static FOO2: Cell = const { Cell::new(1) }); - run(&FOO2); - - fn run(key: &'static LocalKey>) { - key.with(|f| { - assert_eq!(f.get(), 1); - f.set(2); - }); - let t = thread::spawn(move || { - key.with(|f| { - assert_eq!(f.get(), 1); - }); - }); - t.join().unwrap(); - - key.with(|f| { - assert_eq!(f.get(), 2); - }); - } -} - -#[test] -fn states() { - struct Foo(&'static LocalKey); - impl Drop for Foo { - fn drop(&mut self) { - assert!(self.0.try_with(|_| ()).is_err()); - } - } - - thread_local!(static FOO: Foo = Foo(&FOO)); - run(&FOO); - thread_local!(static FOO2: Foo = const { Foo(&FOO2) }); - run(&FOO2); - - fn run(foo: &'static LocalKey) { - thread::spawn(move || { - assert!(foo.try_with(|_| ()).is_ok()); - }) - .join() - .unwrap(); - } -} - -#[test] -fn smoke_dtor() { - thread_local!(static FOO: UnsafeCell> = UnsafeCell::new(None)); - run(&FOO); - thread_local!(static FOO2: UnsafeCell> = const { UnsafeCell::new(None) }); - run(&FOO2); - - fn run(key: &'static LocalKey>>) { - let signal = Signal::default(); - let signal2 = signal.clone(); - let t = thread::spawn(move || unsafe { - let mut signal = Some(signal2); - key.with(|f| { - *f.get() = Some(NotifyOnDrop(signal.take().unwrap())); - }); - }); - signal.wait(); - t.join().unwrap(); - } -} - -#[test] -fn circular() { - struct S1(&'static LocalKey>>, &'static LocalKey>>); - struct S2(&'static LocalKey>>, &'static LocalKey>>); - thread_local!(static K1: UnsafeCell> = UnsafeCell::new(None)); - thread_local!(static K2: UnsafeCell> = UnsafeCell::new(None)); - thread_local!(static K3: UnsafeCell> = const { UnsafeCell::new(None) }); - thread_local!(static K4: UnsafeCell> = const { UnsafeCell::new(None) }); - static mut HITS: usize = 0; - - impl Drop for S1 { - fn drop(&mut self) { - unsafe { - HITS += 1; - if self.1.try_with(|_| ()).is_err() { - assert_eq!(HITS, 3); - } else { - if HITS == 1 { - self.1.with(|s| *s.get() = Some(S2(self.0, self.1))); - } else { - assert_eq!(HITS, 3); - } - } - } - } - } - impl Drop for S2 { - fn drop(&mut self) { - unsafe { - HITS += 1; - assert!(self.0.try_with(|_| ()).is_ok()); - assert_eq!(HITS, 2); - self.0.with(|s| *s.get() = Some(S1(self.0, self.1))); - } - } - } - - thread::spawn(move || { - drop(S1(&K1, &K2)); - }) - .join() - .unwrap(); - - unsafe { - HITS = 0; - } - - thread::spawn(move || { - drop(S1(&K3, &K4)); - }) - .join() - .unwrap(); -} - -#[test] -fn self_referential() { - struct S1(&'static LocalKey>>); - - thread_local!(static K1: UnsafeCell> = UnsafeCell::new(None)); - thread_local!(static K2: UnsafeCell> = const { UnsafeCell::new(None) }); - - impl Drop for S1 { - fn drop(&mut self) { - assert!(self.0.try_with(|_| ()).is_err()); - } - } - - thread::spawn(move || unsafe { - K1.with(|s| *s.get() = Some(S1(&K1))); - }) - .join() - .unwrap(); - - thread::spawn(move || unsafe { - K2.with(|s| *s.get() = Some(S1(&K2))); - }) - .join() - .unwrap(); -} - -// Note that this test will deadlock if TLS destructors aren't run (this -// requires the destructor to be run to pass the test). -#[test] -fn dtors_in_dtors_in_dtors() { - struct S1(Signal); - thread_local!(static K1: UnsafeCell> = UnsafeCell::new(None)); - thread_local!(static K2: UnsafeCell> = UnsafeCell::new(None)); - - impl Drop for S1 { - fn drop(&mut self) { - let S1(ref signal) = *self; - unsafe { - let _ = K2.try_with(|s| *s.get() = Some(NotifyOnDrop(signal.clone()))); - } - } - } - - let signal = Signal::default(); - let signal2 = signal.clone(); - let _t = thread::spawn(move || unsafe { - let mut signal = Some(signal2); - K1.with(|s| *s.get() = Some(S1(signal.take().unwrap()))); - }); - signal.wait(); -} - -#[test] -fn dtors_in_dtors_in_dtors_const_init() { - struct S1(Signal); - thread_local!(static K1: UnsafeCell> = const { UnsafeCell::new(None) }); - thread_local!(static K2: UnsafeCell> = const { UnsafeCell::new(None) }); - - impl Drop for S1 { - fn drop(&mut self) { - let S1(ref signal) = *self; - unsafe { - let _ = K2.try_with(|s| *s.get() = Some(NotifyOnDrop(signal.clone()))); - } - } - } - - let signal = Signal::default(); - let signal2 = signal.clone(); - let _t = thread::spawn(move || unsafe { - let mut signal = Some(signal2); - K1.with(|s| *s.get() = Some(S1(signal.take().unwrap()))); - }); - signal.wait(); -} - -// This test tests that TLS destructors have run before the thread joins. The -// test has no false positives (meaning: if the test fails, there's actually -// an ordering problem). It may have false negatives, where the test passes but -// join is not guaranteed to be after the TLS destructors. However, false -// negatives should be exceedingly rare due to judicious use of -// thread::yield_now and running the test several times. -#[test] -fn join_orders_after_tls_destructors() { - // We emulate a synchronous MPSC rendezvous channel using only atomics and - // thread::yield_now. We can't use std::mpsc as the implementation itself - // may rely on thread locals. - // - // The basic state machine for an SPSC rendezvous channel is: - // FRESH -> THREAD1_WAITING -> MAIN_THREAD_RENDEZVOUS - // where the first transition is done by the “receiving” thread and the 2nd - // transition is done by the “sending” thread. - // - // We add an additional state `THREAD2_LAUNCHED` between `FRESH` and - // `THREAD1_WAITING` to block until all threads are actually running. - // - // A thread that joins on the “receiving” thread completion should never - // observe the channel in the `THREAD1_WAITING` state. If this does occur, - // we switch to the “poison” state `THREAD2_JOINED` and panic all around. - // (This is equivalent to “sending” from an alternate producer thread.) - // - // Relaxed memory ordering is fine because and spawn()/join() already provide all the - // synchronization we need here. - const FRESH: u8 = 0; - const THREAD2_LAUNCHED: u8 = 1; - const THREAD1_WAITING: u8 = 2; - const MAIN_THREAD_RENDEZVOUS: u8 = 3; - const THREAD2_JOINED: u8 = 4; - static SYNC_STATE: AtomicU8 = AtomicU8::new(FRESH); - - for _ in 0..10 { - SYNC_STATE.store(FRESH, Ordering::Relaxed); - - let jh = thread::Builder::new() - .name("thread1".into()) - .spawn(move || { - struct TlDrop; - - impl Drop for TlDrop { - fn drop(&mut self) { - let mut sync_state = SYNC_STATE.swap(THREAD1_WAITING, Ordering::Relaxed); - loop { - match sync_state { - THREAD2_LAUNCHED | THREAD1_WAITING => thread::yield_now(), - MAIN_THREAD_RENDEZVOUS => break, - THREAD2_JOINED => panic!( - "Thread 1 still running after thread 2 joined on thread 1" - ), - v => unreachable!("sync state: {}", v), - } - sync_state = SYNC_STATE.load(Ordering::Relaxed); - } - } - } - - thread_local! { - static TL_DROP: TlDrop = TlDrop; - } - - TL_DROP.with(|_| {}); - - loop { - match SYNC_STATE.load(Ordering::Relaxed) { - FRESH => thread::yield_now(), - THREAD2_LAUNCHED => break, - v => unreachable!("sync state: {}", v), - } - } - }) - .unwrap(); - - let jh2 = thread::Builder::new() - .name("thread2".into()) - .spawn(move || { - assert_eq!(SYNC_STATE.swap(THREAD2_LAUNCHED, Ordering::Relaxed), FRESH); - jh.join().unwrap(); - match SYNC_STATE.swap(THREAD2_JOINED, Ordering::Relaxed) { - MAIN_THREAD_RENDEZVOUS => return, - THREAD2_LAUNCHED | THREAD1_WAITING => { - panic!("Thread 2 running after thread 1 join before main thread rendezvous") - } - v => unreachable!("sync state: {:?}", v), - } - }) - .unwrap(); - - loop { - match SYNC_STATE.compare_exchange( - THREAD1_WAITING, - MAIN_THREAD_RENDEZVOUS, - Ordering::Relaxed, - Ordering::Relaxed, - ) { - Ok(_) => break, - Err(FRESH) => thread::yield_now(), - Err(THREAD2_LAUNCHED) => thread::yield_now(), - Err(THREAD2_JOINED) => { - panic!("Main thread rendezvous after thread 2 joined thread 1") - } - v => unreachable!("sync state: {:?}", v), - } - } - jh2.join().unwrap(); - } -} diff --git a/library/std/src/thread/mod.rs b/library/std/src/thread/mod.rs deleted file mode 100644 index 22215873933d6..0000000000000 --- a/library/std/src/thread/mod.rs +++ /dev/null @@ -1,1855 +0,0 @@ -//! Native threads. -//! -//! ## The threading model -//! -//! An executing Rust program consists of a collection of native OS threads, -//! each with their own stack and local state. Threads can be named, and -//! provide some built-in support for low-level synchronization. -//! -//! Communication between threads can be done through -//! [channels], Rust's message-passing types, along with [other forms of thread -//! synchronization](../../std/sync/index.html) and shared-memory data -//! structures. In particular, types that are guaranteed to be -//! threadsafe are easily shared between threads using the -//! atomically-reference-counted container, [`Arc`]. -//! -//! Fatal logic errors in Rust cause *thread panic*, during which -//! a thread will unwind the stack, running destructors and freeing -//! owned resources. While not meant as a 'try/catch' mechanism, panics -//! in Rust can nonetheless be caught (unless compiling with `panic=abort`) with -//! [`catch_unwind`](../../std/panic/fn.catch_unwind.html) and recovered -//! from, or alternatively be resumed with -//! [`resume_unwind`](../../std/panic/fn.resume_unwind.html). If the panic -//! is not caught the thread will exit, but the panic may optionally be -//! detected from a different thread with [`join`]. If the main thread panics -//! without the panic being caught, the application will exit with a -//! non-zero exit code. -//! -//! When the main thread of a Rust program terminates, the entire program shuts -//! down, even if other threads are still running. However, this module provides -//! convenient facilities for automatically waiting for the termination of a -//! thread (i.e., join). -//! -//! ## Spawning a thread -//! -//! A new thread can be spawned using the [`thread::spawn`][`spawn`] function: -//! -//! ```rust -//! use std::thread; -//! -//! thread::spawn(move || { -//! // some work here -//! }); -//! ``` -//! -//! In this example, the spawned thread is "detached," which means that there is -//! no way for the program to learn when the spawned thread completes or otherwise -//! terminates. -//! -//! To learn when a thread completes, it is necessary to capture the [`JoinHandle`] -//! object that is returned by the call to [`spawn`], which provides -//! a `join` method that allows the caller to wait for the completion of the -//! spawned thread: -//! -//! ```rust -//! use std::thread; -//! -//! let thread_join_handle = thread::spawn(move || { -//! // some work here -//! }); -//! // some work here -//! let res = thread_join_handle.join(); -//! ``` -//! -//! The [`join`] method returns a [`thread::Result`] containing [`Ok`] of the final -//! value produced by the spawned thread, or [`Err`] of the value given to -//! a call to [`panic!`] if the thread panicked. -//! -//! Note that there is no parent/child relationship between a thread that spawns a -//! new thread and the thread being spawned. In particular, the spawned thread may or -//! may not outlive the spawning thread, unless the spawning thread is the main thread. -//! -//! ## Configuring threads -//! -//! A new thread can be configured before it is spawned via the [`Builder`] type, -//! which currently allows you to set the name and stack size for the thread: -//! -//! ```rust -//! # #![allow(unused_must_use)] -//! use std::thread; -//! -//! thread::Builder::new().name("thread1".to_string()).spawn(move || { -//! println!("Hello, world!"); -//! }); -//! ``` -//! -//! ## The `Thread` type -//! -//! Threads are represented via the [`Thread`] type, which you can get in one of -//! two ways: -//! -//! * By spawning a new thread, e.g., using the [`thread::spawn`][`spawn`] -//! function, and calling [`thread`][`JoinHandle::thread`] on the [`JoinHandle`]. -//! * By requesting the current thread, using the [`thread::current`] function. -//! -//! The [`thread::current`] function is available even for threads not spawned -//! by the APIs of this module. -//! -//! ## Thread-local storage -//! -//! This module also provides an implementation of thread-local storage for Rust -//! programs. Thread-local storage is a method of storing data into a global -//! variable that each thread in the program will have its own copy of. -//! Threads do not share this data, so accesses do not need to be synchronized. -//! -//! A thread-local key owns the value it contains and will destroy the value when the -//! thread exits. It is created with the [`thread_local!`] macro and can contain any -//! value that is `'static` (no borrowed pointers). It provides an accessor function, -//! [`with`], that yields a shared reference to the value to the specified -//! closure. Thread-local keys allow only shared access to values, as there would be no -//! way to guarantee uniqueness if mutable borrows were allowed. Most values -//! will want to make use of some form of **interior mutability** through the -//! [`Cell`] or [`RefCell`] types. -//! -//! ## Naming threads -//! -//! Threads are able to have associated names for identification purposes. By default, spawned -//! threads are unnamed. To specify a name for a thread, build the thread with [`Builder`] and pass -//! the desired thread name to [`Builder::name`]. To retrieve the thread name from within the -//! thread, use [`Thread::name`]. A couple of examples where the name of a thread gets used: -//! -//! * If a panic occurs in a named thread, the thread name will be printed in the panic message. -//! * The thread name is provided to the OS where applicable (e.g., `pthread_setname_np` in -//! unix-like platforms). -//! -//! ## Stack size -//! -//! The default stack size is platform-dependent and subject to change. -//! Currently, it is 2 MiB on all Tier-1 platforms. -//! -//! There are two ways to manually specify the stack size for spawned threads: -//! -//! * Build the thread with [`Builder`] and pass the desired stack size to [`Builder::stack_size`]. -//! * Set the `RUST_MIN_STACK` environment variable to an integer representing the desired stack -//! size (in bytes). Note that setting [`Builder::stack_size`] will override this. Be aware that -//! changes to `RUST_MIN_STACK` may be ignored after program start. -//! -//! Note that the stack size of the main thread is *not* determined by Rust. -//! -//! [channels]: crate::sync::mpsc -//! [`join`]: JoinHandle::join -//! [`Result`]: crate::result::Result -//! [`Ok`]: crate::result::Result::Ok -//! [`Err`]: crate::result::Result::Err -//! [`thread::current`]: current -//! [`thread::Result`]: Result -//! [`unpark`]: Thread::unpark -//! [`thread::park_timeout`]: park_timeout -//! [`Cell`]: crate::cell::Cell -//! [`RefCell`]: crate::cell::RefCell -//! [`with`]: LocalKey::with -//! [`thread_local!`]: crate::thread_local - -#![stable(feature = "rust1", since = "1.0.0")] -#![deny(unsafe_op_in_unsafe_fn)] -// Under `test`, `__FastLocalKeyInner` seems unused. -#![cfg_attr(test, allow(dead_code))] - -#[cfg(all(test, not(target_os = "emscripten")))] -mod tests; - -use crate::any::Any; -use crate::cell::{OnceCell, UnsafeCell}; -use crate::env; -use crate::ffi::{CStr, CString}; -use crate::fmt; -use crate::io; -use crate::marker::PhantomData; -use crate::mem::{self, forget}; -use crate::num::NonZero; -use crate::panic; -use crate::panicking; -use crate::pin::Pin; -use crate::ptr::addr_of_mut; -use crate::str; -use crate::sync::atomic::{AtomicUsize, Ordering}; -use crate::sync::Arc; -use crate::sys::sync::Parker; -use crate::sys::thread as imp; -use crate::sys_common::{AsInner, IntoInner}; -use crate::time::{Duration, Instant}; - -#[stable(feature = "scoped_threads", since = "1.63.0")] -mod scoped; - -#[stable(feature = "scoped_threads", since = "1.63.0")] -pub use scoped::{scope, Scope, ScopedJoinHandle}; - -//////////////////////////////////////////////////////////////////////////////// -// Thread-local storage -//////////////////////////////////////////////////////////////////////////////// - -#[macro_use] -mod local; - -cfg_if::cfg_if! { - if #[cfg(test)] { - // Avoid duplicating the global state associated with thread-locals between this crate and - // realstd. Miri relies on this. - pub use realstd::thread::{local_impl, AccessError, LocalKey}; - } else { - #[stable(feature = "rust1", since = "1.0.0")] - pub use self::local::{AccessError, LocalKey}; - - // Implementation details used by the thread_local!{} macro. - #[doc(hidden)] - #[unstable(feature = "thread_local_internals", issue = "none")] - pub mod local_impl { - pub use crate::sys::thread_local::*; - } - } -} - -//////////////////////////////////////////////////////////////////////////////// -// Builder -//////////////////////////////////////////////////////////////////////////////// - -/// Thread factory, which can be used in order to configure the properties of -/// a new thread. -/// -/// Methods can be chained on it in order to configure it. -/// -/// The two configurations available are: -/// -/// - [`name`]: specifies an [associated name for the thread][naming-threads] -/// - [`stack_size`]: specifies the [desired stack size for the thread][stack-size] -/// -/// The [`spawn`] method will take ownership of the builder and create an -/// [`io::Result`] to the thread handle with the given configuration. -/// -/// The [`thread::spawn`] free function uses a `Builder` with default -/// configuration and [`unwrap`]s its return value. -/// -/// You may want to use [`spawn`] instead of [`thread::spawn`], when you want -/// to recover from a failure to launch a thread, indeed the free function will -/// panic where the `Builder` method will return a [`io::Result`]. -/// -/// # Examples -/// -/// ``` -/// use std::thread; -/// -/// let builder = thread::Builder::new(); -/// -/// let handler = builder.spawn(|| { -/// // thread code -/// }).unwrap(); -/// -/// handler.join().unwrap(); -/// ``` -/// -/// [`stack_size`]: Builder::stack_size -/// [`name`]: Builder::name -/// [`spawn`]: Builder::spawn -/// [`thread::spawn`]: spawn -/// [`io::Result`]: crate::io::Result -/// [`unwrap`]: crate::result::Result::unwrap -/// [naming-threads]: ./index.html#naming-threads -/// [stack-size]: ./index.html#stack-size -#[must_use = "must eventually spawn the thread"] -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Debug)] -pub struct Builder { - // A name for the thread-to-be, for identification in panic messages - name: Option, - // The size of the stack for the spawned thread in bytes - stack_size: Option, -} - -impl Builder { - /// Generates the base configuration for spawning a thread, from which - /// configuration methods can be chained. - /// - /// # Examples - /// - /// ``` - /// use std::thread; - /// - /// let builder = thread::Builder::new() - /// .name("foo".into()) - /// .stack_size(32 * 1024); - /// - /// let handler = builder.spawn(|| { - /// // thread code - /// }).unwrap(); - /// - /// handler.join().unwrap(); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn new() -> Builder { - Builder { name: None, stack_size: None } - } - - /// Names the thread-to-be. Currently the name is used for identification - /// only in panic messages. - /// - /// The name must not contain null bytes (`\0`). - /// - /// For more information about named threads, see - /// [this module-level documentation][naming-threads]. - /// - /// # Examples - /// - /// ``` - /// use std::thread; - /// - /// let builder = thread::Builder::new() - /// .name("foo".into()); - /// - /// let handler = builder.spawn(|| { - /// assert_eq!(thread::current().name(), Some("foo")) - /// }).unwrap(); - /// - /// handler.join().unwrap(); - /// ``` - /// - /// [naming-threads]: ./index.html#naming-threads - #[stable(feature = "rust1", since = "1.0.0")] - pub fn name(mut self, name: String) -> Builder { - self.name = Some(name); - self - } - - /// Sets the size of the stack (in bytes) for the new thread. - /// - /// The actual stack size may be greater than this value if - /// the platform specifies a minimal stack size. - /// - /// For more information about the stack size for threads, see - /// [this module-level documentation][stack-size]. - /// - /// # Examples - /// - /// ``` - /// use std::thread; - /// - /// let builder = thread::Builder::new().stack_size(32 * 1024); - /// ``` - /// - /// [stack-size]: ./index.html#stack-size - #[stable(feature = "rust1", since = "1.0.0")] - pub fn stack_size(mut self, size: usize) -> Builder { - self.stack_size = Some(size); - self - } - - /// Spawns a new thread by taking ownership of the `Builder`, and returns an - /// [`io::Result`] to its [`JoinHandle`]. - /// - /// The spawned thread may outlive the caller (unless the caller thread - /// is the main thread; the whole process is terminated when the main - /// thread finishes). The join handle can be used to block on - /// termination of the spawned thread, including recovering its panics. - /// - /// For a more complete documentation see [`thread::spawn`][`spawn`]. - /// - /// # Errors - /// - /// Unlike the [`spawn`] free function, this method yields an - /// [`io::Result`] to capture any failure to create the thread at - /// the OS level. - /// - /// [`io::Result`]: crate::io::Result - /// - /// # Panics - /// - /// Panics if a thread name was set and it contained null bytes. - /// - /// # Examples - /// - /// ``` - /// use std::thread; - /// - /// let builder = thread::Builder::new(); - /// - /// let handler = builder.spawn(|| { - /// // thread code - /// }).unwrap(); - /// - /// handler.join().unwrap(); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn spawn(self, f: F) -> io::Result> - where - F: FnOnce() -> T, - F: Send + 'static, - T: Send + 'static, - { - unsafe { self.spawn_unchecked(f) } - } - - /// Spawns a new thread without any lifetime restrictions by taking ownership - /// of the `Builder`, and returns an [`io::Result`] to its [`JoinHandle`]. - /// - /// The spawned thread may outlive the caller (unless the caller thread - /// is the main thread; the whole process is terminated when the main - /// thread finishes). The join handle can be used to block on - /// termination of the spawned thread, including recovering its panics. - /// - /// This method is identical to [`thread::Builder::spawn`][`Builder::spawn`], - /// except for the relaxed lifetime bounds, which render it unsafe. - /// For a more complete documentation see [`thread::spawn`][`spawn`]. - /// - /// # Errors - /// - /// Unlike the [`spawn`] free function, this method yields an - /// [`io::Result`] to capture any failure to create the thread at - /// the OS level. - /// - /// # Panics - /// - /// Panics if a thread name was set and it contained null bytes. - /// - /// # Safety - /// - /// The caller has to ensure that the spawned thread does not outlive any - /// references in the supplied thread closure and its return type. - /// This can be guaranteed in two ways: - /// - /// - ensure that [`join`][`JoinHandle::join`] is called before any referenced - /// data is dropped - /// - use only types with `'static` lifetime bounds, i.e., those with no or only - /// `'static` references (both [`thread::Builder::spawn`][`Builder::spawn`] - /// and [`thread::spawn`][`spawn`] enforce this property statically) - /// - /// # Examples - /// - /// ``` - /// #![feature(thread_spawn_unchecked)] - /// use std::thread; - /// - /// let builder = thread::Builder::new(); - /// - /// let x = 1; - /// let thread_x = &x; - /// - /// let handler = unsafe { - /// builder.spawn_unchecked(move || { - /// println!("x = {}", *thread_x); - /// }).unwrap() - /// }; - /// - /// // caller has to ensure `join()` is called, otherwise - /// // it is possible to access freed memory if `x` gets - /// // dropped before the thread closure is executed! - /// handler.join().unwrap(); - /// ``` - /// - /// [`io::Result`]: crate::io::Result - #[unstable(feature = "thread_spawn_unchecked", issue = "55132")] - pub unsafe fn spawn_unchecked<'a, F, T>(self, f: F) -> io::Result> - where - F: FnOnce() -> T, - F: Send + 'a, - T: Send + 'a, - { - Ok(JoinHandle(unsafe { self.spawn_unchecked_(f, None) }?)) - } - - unsafe fn spawn_unchecked_<'a, 'scope, F, T>( - self, - f: F, - scope_data: Option>, - ) -> io::Result> - where - F: FnOnce() -> T, - F: Send + 'a, - T: Send + 'a, - 'scope: 'a, - { - let Builder { name, stack_size } = self; - - let stack_size = stack_size.unwrap_or_else(|| { - static MIN: AtomicUsize = AtomicUsize::new(0); - - match MIN.load(Ordering::Relaxed) { - 0 => {} - n => return n - 1, - } - - let amt = env::var_os("RUST_MIN_STACK") - .and_then(|s| s.to_str().and_then(|s| s.parse().ok())) - .unwrap_or(imp::DEFAULT_MIN_STACK_SIZE); - - // 0 is our sentinel value, so ensure that we'll never see 0 after - // initialization has run - MIN.store(amt + 1, Ordering::Relaxed); - amt - }); - - let my_thread = name.map_or_else(Thread::new_unnamed, |name| unsafe { - Thread::new( - CString::new(name).expect("thread name may not contain interior null bytes"), - ) - }); - let their_thread = my_thread.clone(); - - let my_packet: Arc> = Arc::new(Packet { - scope: scope_data, - result: UnsafeCell::new(None), - _marker: PhantomData, - }); - let their_packet = my_packet.clone(); - - let output_capture = crate::io::set_output_capture(None); - crate::io::set_output_capture(output_capture.clone()); - - // Pass `f` in `MaybeUninit` because actually that closure might *run longer than the lifetime of `F`*. - // See for more details. - // To prevent leaks we use a wrapper that drops its contents. - #[repr(transparent)] - struct MaybeDangling(mem::MaybeUninit); - impl MaybeDangling { - fn new(x: T) -> Self { - MaybeDangling(mem::MaybeUninit::new(x)) - } - fn into_inner(self) -> T { - // SAFETY: we are always initialized. - let ret = unsafe { self.0.assume_init_read() }; - // Make sure we don't drop. - mem::forget(self); - ret - } - } - impl Drop for MaybeDangling { - fn drop(&mut self) { - // SAFETY: we are always initialized. - unsafe { self.0.assume_init_drop() }; - } - } - - let f = MaybeDangling::new(f); - let main = move || { - if let Some(name) = their_thread.cname() { - imp::Thread::set_name(name); - } - - crate::io::set_output_capture(output_capture); - - let f = f.into_inner(); - set_current(their_thread); - let try_result = panic::catch_unwind(panic::AssertUnwindSafe(|| { - crate::sys_common::backtrace::__rust_begin_short_backtrace(f) - })); - // SAFETY: `their_packet` as been built just above and moved by the - // closure (it is an Arc<...>) and `my_packet` will be stored in the - // same `JoinInner` as this closure meaning the mutation will be - // safe (not modify it and affect a value far away). - unsafe { *their_packet.result.get() = Some(try_result) }; - // Here `their_packet` gets dropped, and if this is the last `Arc` for that packet that - // will call `decrement_num_running_threads` and therefore signal that this thread is - // done. - drop(their_packet); - // Here, the lifetime `'a` and even `'scope` can end. `main` keeps running for a bit - // after that before returning itself. - }; - - if let Some(scope_data) = &my_packet.scope { - scope_data.increment_num_running_threads(); - } - - let main = Box::new(main); - // SAFETY: dynamic size and alignment of the Box remain the same. See below for why the - // lifetime change is justified. - let main = unsafe { Box::from_raw(Box::into_raw(main) as *mut (dyn FnOnce() + 'static)) }; - - Ok(JoinInner { - // SAFETY: - // - // `imp::Thread::new` takes a closure with a `'static` lifetime, since it's passed - // through FFI or otherwise used with low-level threading primitives that have no - // notion of or way to enforce lifetimes. - // - // As mentioned in the `Safety` section of this function's documentation, the caller of - // this function needs to guarantee that the passed-in lifetime is sufficiently long - // for the lifetime of the thread. - // - // Similarly, the `sys` implementation must guarantee that no references to the closure - // exist after the thread has terminated, which is signaled by `Thread::join` - // returning. - native: unsafe { imp::Thread::new(stack_size, main)? }, - thread: my_thread, - packet: my_packet, - }) - } -} - -//////////////////////////////////////////////////////////////////////////////// -// Free functions -//////////////////////////////////////////////////////////////////////////////// - -/// Spawns a new thread, returning a [`JoinHandle`] for it. -/// -/// The join handle provides a [`join`] method that can be used to join the spawned -/// thread. If the spawned thread panics, [`join`] will return an [`Err`] containing -/// the argument given to [`panic!`]. -/// -/// If the join handle is dropped, the spawned thread will implicitly be *detached*. -/// In this case, the spawned thread may no longer be joined. -/// (It is the responsibility of the program to either eventually join threads it -/// creates or detach them; otherwise, a resource leak will result.) -/// -/// This call will create a thread using default parameters of [`Builder`], if you -/// want to specify the stack size or the name of the thread, use this API -/// instead. -/// -/// As you can see in the signature of `spawn` there are two constraints on -/// both the closure given to `spawn` and its return value, let's explain them: -/// -/// - The `'static` constraint means that the closure and its return value -/// must have a lifetime of the whole program execution. The reason for this -/// is that threads can outlive the lifetime they have been created in. -/// -/// Indeed if the thread, and by extension its return value, can outlive their -/// caller, we need to make sure that they will be valid afterwards, and since -/// we *can't* know when it will return we need to have them valid as long as -/// possible, that is until the end of the program, hence the `'static` -/// lifetime. -/// - The [`Send`] constraint is because the closure will need to be passed -/// *by value* from the thread where it is spawned to the new thread. Its -/// return value will need to be passed from the new thread to the thread -/// where it is `join`ed. -/// As a reminder, the [`Send`] marker trait expresses that it is safe to be -/// passed from thread to thread. [`Sync`] expresses that it is safe to have a -/// reference be passed from thread to thread. -/// -/// # Panics -/// -/// Panics if the OS fails to create a thread; use [`Builder::spawn`] -/// to recover from such errors. -/// -/// # Examples -/// -/// Creating a thread. -/// -/// ``` -/// use std::thread; -/// -/// let handler = thread::spawn(|| { -/// // thread code -/// }); -/// -/// handler.join().unwrap(); -/// ``` -/// -/// As mentioned in the module documentation, threads are usually made to -/// communicate using [`channels`], here is how it usually looks. -/// -/// This example also shows how to use `move`, in order to give ownership -/// of values to a thread. -/// -/// ``` -/// use std::thread; -/// use std::sync::mpsc::channel; -/// -/// let (tx, rx) = channel(); -/// -/// let sender = thread::spawn(move || { -/// tx.send("Hello, thread".to_owned()) -/// .expect("Unable to send on channel"); -/// }); -/// -/// let receiver = thread::spawn(move || { -/// let value = rx.recv().expect("Unable to receive from channel"); -/// println!("{value}"); -/// }); -/// -/// sender.join().expect("The sender thread has panicked"); -/// receiver.join().expect("The receiver thread has panicked"); -/// ``` -/// -/// A thread can also return a value through its [`JoinHandle`], you can use -/// this to make asynchronous computations (futures might be more appropriate -/// though). -/// -/// ``` -/// use std::thread; -/// -/// let computation = thread::spawn(|| { -/// // Some expensive computation. -/// 42 -/// }); -/// -/// let result = computation.join().unwrap(); -/// println!("{result}"); -/// ``` -/// -/// [`channels`]: crate::sync::mpsc -/// [`join`]: JoinHandle::join -/// [`Err`]: crate::result::Result::Err -#[stable(feature = "rust1", since = "1.0.0")] -pub fn spawn(f: F) -> JoinHandle -where - F: FnOnce() -> T, - F: Send + 'static, - T: Send + 'static, -{ - Builder::new().spawn(f).expect("failed to spawn thread") -} - -thread_local! { - static CURRENT: OnceCell = const { OnceCell::new() }; -} - -/// Sets the thread handle for the current thread. -/// -/// Aborts if the handle has been set already to reduce code size. -pub(crate) fn set_current(thread: Thread) { - // Using `unwrap` here can add ~3kB to the binary size. We have complete - // control over where this is called, so just abort if there is a bug. - CURRENT.with(|current| match current.set(thread) { - Ok(()) => {} - Err(_) => rtabort!("thread::set_current should only be called once per thread"), - }); -} - -/// Gets a handle to the thread that invokes it. -/// -/// In contrast to the public `current` function, this will not panic if called -/// from inside a TLS destructor. -pub(crate) fn try_current() -> Option { - CURRENT.try_with(|current| current.get_or_init(|| Thread::new_unnamed()).clone()).ok() -} - -/// Gets a handle to the thread that invokes it. -/// -/// # Examples -/// -/// Getting a handle to the current thread with `thread::current()`: -/// -/// ``` -/// use std::thread; -/// -/// let handler = thread::Builder::new() -/// .name("named thread".into()) -/// .spawn(|| { -/// let handle = thread::current(); -/// assert_eq!(handle.name(), Some("named thread")); -/// }) -/// .unwrap(); -/// -/// handler.join().unwrap(); -/// ``` -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -pub fn current() -> Thread { - try_current().expect( - "use of std::thread::current() is not possible \ - after the thread's local data has been destroyed", - ) -} - -/// Cooperatively gives up a timeslice to the OS scheduler. -/// -/// This calls the underlying OS scheduler's yield primitive, signaling -/// that the calling thread is willing to give up its remaining timeslice -/// so that the OS may schedule other threads on the CPU. -/// -/// A drawback of yielding in a loop is that if the OS does not have any -/// other ready threads to run on the current CPU, the thread will effectively -/// busy-wait, which wastes CPU time and energy. -/// -/// Therefore, when waiting for events of interest, a programmer's first -/// choice should be to use synchronization devices such as [`channel`]s, -/// [`Condvar`]s, [`Mutex`]es or [`join`] since these primitives are -/// implemented in a blocking manner, giving up the CPU until the event -/// of interest has occurred which avoids repeated yielding. -/// -/// `yield_now` should thus be used only rarely, mostly in situations where -/// repeated polling is required because there is no other suitable way to -/// learn when an event of interest has occurred. -/// -/// # Examples -/// -/// ``` -/// use std::thread; -/// -/// thread::yield_now(); -/// ``` -/// -/// [`channel`]: crate::sync::mpsc -/// [`join`]: JoinHandle::join -/// [`Condvar`]: crate::sync::Condvar -/// [`Mutex`]: crate::sync::Mutex -#[stable(feature = "rust1", since = "1.0.0")] -pub fn yield_now() { - imp::Thread::yield_now() -} - -/// Determines whether the current thread is unwinding because of panic. -/// -/// A common use of this feature is to poison shared resources when writing -/// unsafe code, by checking `panicking` when the `drop` is called. -/// -/// This is usually not needed when writing safe code, as [`Mutex`es][Mutex] -/// already poison themselves when a thread panics while holding the lock. -/// -/// This can also be used in multithreaded applications, in order to send a -/// message to other threads warning that a thread has panicked (e.g., for -/// monitoring purposes). -/// -/// # Examples -/// -/// ```should_panic -/// use std::thread; -/// -/// struct SomeStruct; -/// -/// impl Drop for SomeStruct { -/// fn drop(&mut self) { -/// if thread::panicking() { -/// println!("dropped while unwinding"); -/// } else { -/// println!("dropped while not unwinding"); -/// } -/// } -/// } -/// -/// { -/// print!("a: "); -/// let a = SomeStruct; -/// } -/// -/// { -/// print!("b: "); -/// let b = SomeStruct; -/// panic!() -/// } -/// ``` -/// -/// [Mutex]: crate::sync::Mutex -#[inline] -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -pub fn panicking() -> bool { - panicking::panicking() -} - -/// Use [`sleep`]. -/// -/// Puts the current thread to sleep for at least the specified amount of time. -/// -/// The thread may sleep longer than the duration specified due to scheduling -/// specifics or platform-dependent functionality. It will never sleep less. -/// -/// This function is blocking, and should not be used in `async` functions. -/// -/// # Platform-specific behavior -/// -/// On Unix platforms, the underlying syscall may be interrupted by a -/// spurious wakeup or signal handler. To ensure the sleep occurs for at least -/// the specified duration, this function may invoke that system call multiple -/// times. -/// -/// # Examples -/// -/// ```no_run -/// use std::thread; -/// -/// // Let's sleep for 2 seconds: -/// thread::sleep_ms(2000); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "1.6.0", note = "replaced by `std::thread::sleep`")] -pub fn sleep_ms(ms: u32) { - sleep(Duration::from_millis(ms as u64)) -} - -/// Puts the current thread to sleep for at least the specified amount of time. -/// -/// The thread may sleep longer than the duration specified due to scheduling -/// specifics or platform-dependent functionality. It will never sleep less. -/// -/// This function is blocking, and should not be used in `async` functions. -/// -/// # Platform-specific behavior -/// -/// On Unix platforms, the underlying syscall may be interrupted by a -/// spurious wakeup or signal handler. To ensure the sleep occurs for at least -/// the specified duration, this function may invoke that system call multiple -/// times. -/// Platforms which do not support nanosecond precision for sleeping will -/// have `dur` rounded up to the nearest granularity of time they can sleep for. -/// -/// Currently, specifying a zero duration on Unix platforms returns immediately -/// without invoking the underlying [`nanosleep`] syscall, whereas on Windows -/// platforms the underlying [`Sleep`] syscall is always invoked. -/// If the intention is to yield the current time-slice you may want to use -/// [`yield_now`] instead. -/// -/// [`nanosleep`]: https://linux.die.net/man/2/nanosleep -/// [`Sleep`]: https://docs.microsoft.com/en-us/windows/win32/api/synchapi/nf-synchapi-sleep -/// -/// # Examples -/// -/// ```no_run -/// use std::{thread, time}; -/// -/// let ten_millis = time::Duration::from_millis(10); -/// let now = time::Instant::now(); -/// -/// thread::sleep(ten_millis); -/// -/// assert!(now.elapsed() >= ten_millis); -/// ``` -#[stable(feature = "thread_sleep", since = "1.4.0")] -pub fn sleep(dur: Duration) { - imp::Thread::sleep(dur) -} - -/// Puts the current thread to sleep until the specified deadline has passed. -/// -/// The thread may still be asleep after the deadline specified due to -/// scheduling specifics or platform-dependent functionality. It will never -/// wake before. -/// -/// This function is blocking, and should not be used in `async` functions. -/// -/// # Platform-specific behavior -/// -/// This function uses [`sleep`] internally, see its platform-specific behaviour. -/// -/// -/// # Examples -/// -/// A simple game loop that limits the game to 60 frames per second. -/// -/// ```no_run -/// #![feature(thread_sleep_until)] -/// # use std::time::{Duration, Instant}; -/// # use std::thread; -/// # -/// # fn update() {} -/// # fn render() {} -/// # -/// let max_fps = 60.0; -/// let frame_time = Duration::from_secs_f32(1.0/max_fps); -/// let mut next_frame = Instant::now(); -/// loop { -/// thread::sleep_until(next_frame); -/// next_frame += frame_time; -/// update(); -/// render(); -/// } -/// ``` -/// -/// A slow api we must not call too fast and which takes a few -/// tries before succeeding. By using `sleep_until` the time the -/// api call takes does not influence when we retry or when we give up -/// -/// ```no_run -/// #![feature(thread_sleep_until)] -/// # use std::time::{Duration, Instant}; -/// # use std::thread; -/// # -/// # enum Status { -/// # Ready(usize), -/// # Waiting, -/// # } -/// # fn slow_web_api_call() -> Status { Status::Ready(42) } -/// # -/// # const MAX_DURATION: Duration = Duration::from_secs(10); -/// # -/// # fn try_api_call() -> Result { -/// let deadline = Instant::now() + MAX_DURATION; -/// let delay = Duration::from_millis(250); -/// let mut next_attempt = Instant::now(); -/// loop { -/// if Instant::now() > deadline { -/// break Err(()); -/// } -/// if let Status::Ready(data) = slow_web_api_call() { -/// break Ok(data); -/// } -/// -/// next_attempt = deadline.min(next_attempt + delay); -/// thread::sleep_until(next_attempt); -/// } -/// # } -/// # let _data = try_api_call(); -/// ``` -#[unstable(feature = "thread_sleep_until", issue = "113752")] -pub fn sleep_until(deadline: Instant) { - let now = Instant::now(); - - if let Some(delay) = deadline.checked_duration_since(now) { - sleep(delay); - } -} - -/// Used to ensure that `park` and `park_timeout` do not unwind, as that can -/// cause undefined behaviour if not handled correctly (see #102398 for context). -struct PanicGuard; - -impl Drop for PanicGuard { - fn drop(&mut self) { - rtabort!("an irrecoverable error occurred while synchronizing threads") - } -} - -/// Blocks unless or until the current thread's token is made available. -/// -/// A call to `park` does not guarantee that the thread will remain parked -/// forever, and callers should be prepared for this possibility. However, -/// it is guaranteed that this function will not panic (it may abort the -/// process if the implementation encounters some rare errors). -/// -/// # `park` and `unpark` -/// -/// Every thread is equipped with some basic low-level blocking support, via the -/// [`thread::park`][`park`] function and [`thread::Thread::unpark`][`unpark`] -/// method. [`park`] blocks the current thread, which can then be resumed from -/// another thread by calling the [`unpark`] method on the blocked thread's -/// handle. -/// -/// Conceptually, each [`Thread`] handle has an associated token, which is -/// initially not present: -/// -/// * The [`thread::park`][`park`] function blocks the current thread unless or -/// until the token is available for its thread handle, at which point it -/// atomically consumes the token. It may also return *spuriously*, without -/// consuming the token. [`thread::park_timeout`] does the same, but allows -/// specifying a maximum time to block the thread for. -/// -/// * The [`unpark`] method on a [`Thread`] atomically makes the token available -/// if it wasn't already. Because the token is initially absent, [`unpark`] -/// followed by [`park`] will result in the second call returning immediately. -/// -/// The API is typically used by acquiring a handle to the current thread, -/// placing that handle in a shared data structure so that other threads can -/// find it, and then `park`ing in a loop. When some desired condition is met, another -/// thread calls [`unpark`] on the handle. -/// -/// The motivation for this design is twofold: -/// -/// * It avoids the need to allocate mutexes and condvars when building new -/// synchronization primitives; the threads already provide basic -/// blocking/signaling. -/// -/// * It can be implemented very efficiently on many platforms. -/// -/// # Memory Ordering -/// -/// Calls to `park` _synchronize-with_ calls to `unpark`, meaning that memory -/// operations performed before a call to `unpark` are made visible to the thread that -/// consumes the token and returns from `park`. Note that all `park` and `unpark` -/// operations for a given thread form a total order and `park` synchronizes-with -/// _all_ prior `unpark` operations. -/// -/// In atomic ordering terms, `unpark` performs a `Release` operation and `park` -/// performs the corresponding `Acquire` operation. Calls to `unpark` for the same -/// thread form a [release sequence]. -/// -/// Note that being unblocked does not imply a call was made to `unpark`, because -/// wakeups can also be spurious. For example, a valid, but inefficient, -/// implementation could have `park` and `unpark` return immediately without doing anything, -/// making *all* wakeups spurious. -/// -/// # Examples -/// -/// ``` -/// use std::thread; -/// use std::sync::{Arc, atomic::{Ordering, AtomicBool}}; -/// use std::time::Duration; -/// -/// let flag = Arc::new(AtomicBool::new(false)); -/// let flag2 = Arc::clone(&flag); -/// -/// let parked_thread = thread::spawn(move || { -/// // We want to wait until the flag is set. We *could* just spin, but using -/// // park/unpark is more efficient. -/// while !flag2.load(Ordering::Relaxed) { -/// println!("Parking thread"); -/// thread::park(); -/// // We *could* get here spuriously, i.e., way before the 10ms below are over! -/// // But that is no problem, we are in a loop until the flag is set anyway. -/// println!("Thread unparked"); -/// } -/// println!("Flag received"); -/// }); -/// -/// // Let some time pass for the thread to be spawned. -/// thread::sleep(Duration::from_millis(10)); -/// -/// // Set the flag, and let the thread wake up. -/// // There is no race condition here, if `unpark` -/// // happens first, `park` will return immediately. -/// // Hence there is no risk of a deadlock. -/// flag.store(true, Ordering::Relaxed); -/// println!("Unpark the thread"); -/// parked_thread.thread().unpark(); -/// -/// parked_thread.join().unwrap(); -/// ``` -/// -/// [`unpark`]: Thread::unpark -/// [`thread::park_timeout`]: park_timeout -/// [release sequence]: https://en.cppreference.com/w/cpp/atomic/memory_order#Release_sequence -#[stable(feature = "rust1", since = "1.0.0")] -pub fn park() { - let guard = PanicGuard; - // SAFETY: park_timeout is called on the parker owned by this thread. - unsafe { - current().park(); - } - // No panic occurred, do not abort. - forget(guard); -} - -/// Use [`park_timeout`]. -/// -/// Blocks unless or until the current thread's token is made available or -/// the specified duration has been reached (may wake spuriously). -/// -/// The semantics of this function are equivalent to [`park`] except -/// that the thread will be blocked for roughly no longer than `dur`. This -/// method should not be used for precise timing due to anomalies such as -/// preemption or platform differences that might not cause the maximum -/// amount of time waited to be precisely `ms` long. -/// -/// See the [park documentation][`park`] for more detail. -#[stable(feature = "rust1", since = "1.0.0")] -#[deprecated(since = "1.6.0", note = "replaced by `std::thread::park_timeout`")] -pub fn park_timeout_ms(ms: u32) { - park_timeout(Duration::from_millis(ms as u64)) -} - -/// Blocks unless or until the current thread's token is made available or -/// the specified duration has been reached (may wake spuriously). -/// -/// The semantics of this function are equivalent to [`park`][park] except -/// that the thread will be blocked for roughly no longer than `dur`. This -/// method should not be used for precise timing due to anomalies such as -/// preemption or platform differences that might not cause the maximum -/// amount of time waited to be precisely `dur` long. -/// -/// See the [park documentation][park] for more details. -/// -/// # Platform-specific behavior -/// -/// Platforms which do not support nanosecond precision for sleeping will have -/// `dur` rounded up to the nearest granularity of time they can sleep for. -/// -/// # Examples -/// -/// Waiting for the complete expiration of the timeout: -/// -/// ```rust,no_run -/// use std::thread::park_timeout; -/// use std::time::{Instant, Duration}; -/// -/// let timeout = Duration::from_secs(2); -/// let beginning_park = Instant::now(); -/// -/// let mut timeout_remaining = timeout; -/// loop { -/// park_timeout(timeout_remaining); -/// let elapsed = beginning_park.elapsed(); -/// if elapsed >= timeout { -/// break; -/// } -/// println!("restarting park_timeout after {elapsed:?}"); -/// timeout_remaining = timeout - elapsed; -/// } -/// ``` -#[stable(feature = "park_timeout", since = "1.4.0")] -pub fn park_timeout(dur: Duration) { - let guard = PanicGuard; - // SAFETY: park_timeout is called on the parker owned by this thread. - unsafe { - current().inner.as_ref().parker().park_timeout(dur); - } - // No panic occurred, do not abort. - forget(guard); -} - -//////////////////////////////////////////////////////////////////////////////// -// ThreadId -//////////////////////////////////////////////////////////////////////////////// - -/// A unique identifier for a running thread. -/// -/// A `ThreadId` is an opaque object that uniquely identifies each thread -/// created during the lifetime of a process. `ThreadId`s are guaranteed not to -/// be reused, even when a thread terminates. `ThreadId`s are under the control -/// of Rust's standard library and there may not be any relationship between -/// `ThreadId` and the underlying platform's notion of a thread identifier -- -/// the two concepts cannot, therefore, be used interchangeably. A `ThreadId` -/// can be retrieved from the [`id`] method on a [`Thread`]. -/// -/// # Examples -/// -/// ``` -/// use std::thread; -/// -/// let other_thread = thread::spawn(|| { -/// thread::current().id() -/// }); -/// -/// let other_thread_id = other_thread.join().unwrap(); -/// assert!(thread::current().id() != other_thread_id); -/// ``` -/// -/// [`id`]: Thread::id -#[stable(feature = "thread_id", since = "1.19.0")] -#[derive(Eq, PartialEq, Clone, Copy, Hash, Debug)] -pub struct ThreadId(NonZero); - -impl ThreadId { - // Generate a new unique thread ID. - fn new() -> ThreadId { - #[cold] - fn exhausted() -> ! { - panic!("failed to generate unique thread ID: bitspace exhausted") - } - - cfg_if::cfg_if! { - if #[cfg(target_has_atomic = "64")] { - use crate::sync::atomic::AtomicU64; - - static COUNTER: AtomicU64 = AtomicU64::new(0); - - let mut last = COUNTER.load(Ordering::Relaxed); - loop { - let Some(id) = last.checked_add(1) else { - exhausted(); - }; - - match COUNTER.compare_exchange_weak(last, id, Ordering::Relaxed, Ordering::Relaxed) { - Ok(_) => return ThreadId(NonZero::new(id).unwrap()), - Err(id) => last = id, - } - } - } else { - use crate::sync::{Mutex, PoisonError}; - - static COUNTER: Mutex = Mutex::new(0); - - let mut counter = COUNTER.lock().unwrap_or_else(PoisonError::into_inner); - let Some(id) = counter.checked_add(1) else { - // in case the panic handler ends up calling `ThreadId::new()`, - // avoid reentrant lock acquire. - drop(counter); - exhausted(); - }; - - *counter = id; - drop(counter); - ThreadId(NonZero::new(id).unwrap()) - } - } - } - - /// This returns a numeric identifier for the thread identified by this - /// `ThreadId`. - /// - /// As noted in the documentation for the type itself, it is essentially an - /// opaque ID, but is guaranteed to be unique for each thread. The returned - /// value is entirely opaque -- only equality testing is stable. Note that - /// it is not guaranteed which values new threads will return, and this may - /// change across Rust versions. - #[must_use] - #[unstable(feature = "thread_id_value", issue = "67939")] - pub fn as_u64(&self) -> NonZero { - self.0 - } -} - -//////////////////////////////////////////////////////////////////////////////// -// Thread -//////////////////////////////////////////////////////////////////////////////// - -/// The internal representation of a `Thread`'s name. -enum ThreadName { - Main, - Other(CString), - Unnamed, -} - -/// The internal representation of a `Thread` handle -struct Inner { - name: ThreadName, // Guaranteed to be UTF-8 - id: ThreadId, - parker: Parker, -} - -impl Inner { - fn parker(self: Pin<&Self>) -> Pin<&Parker> { - unsafe { Pin::map_unchecked(self, |inner| &inner.parker) } - } -} - -#[derive(Clone)] -#[stable(feature = "rust1", since = "1.0.0")] -/// A handle to a thread. -/// -/// Threads are represented via the `Thread` type, which you can get in one of -/// two ways: -/// -/// * By spawning a new thread, e.g., using the [`thread::spawn`][`spawn`] -/// function, and calling [`thread`][`JoinHandle::thread`] on the -/// [`JoinHandle`]. -/// * By requesting the current thread, using the [`thread::current`] function. -/// -/// The [`thread::current`] function is available even for threads not spawned -/// by the APIs of this module. -/// -/// There is usually no need to create a `Thread` struct yourself, one -/// should instead use a function like `spawn` to create new threads, see the -/// docs of [`Builder`] and [`spawn`] for more details. -/// -/// [`thread::current`]: current -pub struct Thread { - inner: Pin>, -} - -impl Thread { - /// Used only internally to construct a thread object without spawning. - /// - /// # Safety - /// `name` must be valid UTF-8. - pub(crate) unsafe fn new(name: CString) -> Thread { - unsafe { Self::new_inner(ThreadName::Other(name)) } - } - - pub(crate) fn new_unnamed() -> Thread { - unsafe { Self::new_inner(ThreadName::Unnamed) } - } - - // Used in runtime to construct main thread - pub(crate) fn new_main() -> Thread { - unsafe { Self::new_inner(ThreadName::Main) } - } - - /// # Safety - /// If `name` is `ThreadName::Other(_)`, the contained string must be valid UTF-8. - unsafe fn new_inner(name: ThreadName) -> Thread { - // We have to use `unsafe` here to construct the `Parker` in-place, - // which is required for the UNIX implementation. - // - // SAFETY: We pin the Arc immediately after creation, so its address never - // changes. - let inner = unsafe { - let mut arc = Arc::::new_uninit(); - let ptr = Arc::get_mut_unchecked(&mut arc).as_mut_ptr(); - addr_of_mut!((*ptr).name).write(name); - addr_of_mut!((*ptr).id).write(ThreadId::new()); - Parker::new_in_place(addr_of_mut!((*ptr).parker)); - Pin::new_unchecked(arc.assume_init()) - }; - - Thread { inner } - } - - /// Like the public [`park`], but callable on any handle. This is used to - /// allow parking in TLS destructors. - /// - /// # Safety - /// May only be called from the thread to which this handle belongs. - pub(crate) unsafe fn park(&self) { - unsafe { self.inner.as_ref().parker().park() } - } - - /// Atomically makes the handle's token available if it is not already. - /// - /// Every thread is equipped with some basic low-level blocking support, via - /// the [`park`][park] function and the `unpark()` method. These can be - /// used as a more CPU-efficient implementation of a spinlock. - /// - /// See the [park documentation][park] for more details. - /// - /// # Examples - /// - /// ``` - /// use std::thread; - /// use std::time::Duration; - /// - /// let parked_thread = thread::Builder::new() - /// .spawn(|| { - /// println!("Parking thread"); - /// thread::park(); - /// println!("Thread unparked"); - /// }) - /// .unwrap(); - /// - /// // Let some time pass for the thread to be spawned. - /// thread::sleep(Duration::from_millis(10)); - /// - /// println!("Unpark the thread"); - /// parked_thread.thread().unpark(); - /// - /// parked_thread.join().unwrap(); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn unpark(&self) { - self.inner.as_ref().parker().unpark(); - } - - /// Gets the thread's unique identifier. - /// - /// # Examples - /// - /// ``` - /// use std::thread; - /// - /// let other_thread = thread::spawn(|| { - /// thread::current().id() - /// }); - /// - /// let other_thread_id = other_thread.join().unwrap(); - /// assert!(thread::current().id() != other_thread_id); - /// ``` - #[stable(feature = "thread_id", since = "1.19.0")] - #[must_use] - pub fn id(&self) -> ThreadId { - self.inner.id - } - - /// Gets the thread's name. - /// - /// For more information about named threads, see - /// [this module-level documentation][naming-threads]. - /// - /// # Examples - /// - /// Threads by default have no name specified: - /// - /// ``` - /// use std::thread; - /// - /// let builder = thread::Builder::new(); - /// - /// let handler = builder.spawn(|| { - /// assert!(thread::current().name().is_none()); - /// }).unwrap(); - /// - /// handler.join().unwrap(); - /// ``` - /// - /// Thread with a specified name: - /// - /// ``` - /// use std::thread; - /// - /// let builder = thread::Builder::new() - /// .name("foo".into()); - /// - /// let handler = builder.spawn(|| { - /// assert_eq!(thread::current().name(), Some("foo")) - /// }).unwrap(); - /// - /// handler.join().unwrap(); - /// ``` - /// - /// [naming-threads]: ./index.html#naming-threads - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - pub fn name(&self) -> Option<&str> { - self.cname().map(|s| unsafe { str::from_utf8_unchecked(s.to_bytes()) }) - } - - fn cname(&self) -> Option<&CStr> { - match &self.inner.name { - ThreadName::Main => Some(c"main"), - ThreadName::Other(other) => Some(&other), - ThreadName::Unnamed => None, - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for Thread { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Thread") - .field("id", &self.id()) - .field("name", &self.name()) - .finish_non_exhaustive() - } -} - -//////////////////////////////////////////////////////////////////////////////// -// JoinHandle -//////////////////////////////////////////////////////////////////////////////// - -/// A specialized [`Result`] type for threads. -/// -/// Indicates the manner in which a thread exited. -/// -/// The value contained in the `Result::Err` variant -/// is the value the thread panicked with; -/// that is, the argument the `panic!` macro was called with. -/// Unlike with normal errors, this value doesn't implement -/// the [`Error`](crate::error::Error) trait. -/// -/// Thus, a sensible way to handle a thread panic is to either: -/// -/// 1. propagate the panic with [`std::panic::resume_unwind`] -/// 2. or in case the thread is intended to be a subsystem boundary -/// that is supposed to isolate system-level failures, -/// match on the `Err` variant and handle the panic in an appropriate way -/// -/// A thread that completes without panicking is considered to exit successfully. -/// -/// # Examples -/// -/// Matching on the result of a joined thread: -/// -/// ```no_run -/// use std::{fs, thread, panic}; -/// -/// fn copy_in_thread() -> thread::Result<()> { -/// thread::spawn(|| { -/// fs::copy("foo.txt", "bar.txt").unwrap(); -/// }).join() -/// } -/// -/// fn main() { -/// match copy_in_thread() { -/// Ok(_) => println!("copy succeeded"), -/// Err(e) => panic::resume_unwind(e), -/// } -/// } -/// ``` -/// -/// [`Result`]: crate::result::Result -/// [`std::panic::resume_unwind`]: crate::panic::resume_unwind -#[stable(feature = "rust1", since = "1.0.0")] -pub type Result = crate::result::Result>; - -// This packet is used to communicate the return value between the spawned -// thread and the rest of the program. It is shared through an `Arc` and -// there's no need for a mutex here because synchronization happens with `join()` -// (the caller will never read this packet until the thread has exited). -// -// An Arc to the packet is stored into a `JoinInner` which in turns is placed -// in `JoinHandle`. -struct Packet<'scope, T> { - scope: Option>, - result: UnsafeCell>>, - _marker: PhantomData>, -} - -// Due to the usage of `UnsafeCell` we need to manually implement Sync. -// The type `T` should already always be Send (otherwise the thread could not -// have been created) and the Packet is Sync because all access to the -// `UnsafeCell` synchronized (by the `join()` boundary), and `ScopeData` is Sync. -unsafe impl<'scope, T: Sync> Sync for Packet<'scope, T> {} - -impl<'scope, T> Drop for Packet<'scope, T> { - fn drop(&mut self) { - // If this packet was for a thread that ran in a scope, the thread - // panicked, and nobody consumed the panic payload, we make sure - // the scope function will panic. - let unhandled_panic = matches!(self.result.get_mut(), Some(Err(_))); - // Drop the result without causing unwinding. - // This is only relevant for threads that aren't join()ed, as - // join() will take the `result` and set it to None, such that - // there is nothing left to drop here. - // If this panics, we should handle that, because we're outside the - // outermost `catch_unwind` of our thread. - // We just abort in that case, since there's nothing else we can do. - // (And even if we tried to handle it somehow, we'd also need to handle - // the case where the panic payload we get out of it also panics on - // drop, and so on. See issue #86027.) - if let Err(_) = panic::catch_unwind(panic::AssertUnwindSafe(|| { - *self.result.get_mut() = None; - })) { - rtabort!("thread result panicked on drop"); - } - // Book-keeping so the scope knows when it's done. - if let Some(scope) = &self.scope { - // Now that there will be no more user code running on this thread - // that can use 'scope, mark the thread as 'finished'. - // It's important we only do this after the `result` has been dropped, - // since dropping it might still use things it borrowed from 'scope. - scope.decrement_num_running_threads(unhandled_panic); - } - } -} - -/// Inner representation for JoinHandle -struct JoinInner<'scope, T> { - native: imp::Thread, - thread: Thread, - packet: Arc>, -} - -impl<'scope, T> JoinInner<'scope, T> { - fn join(mut self) -> Result { - self.native.join(); - Arc::get_mut(&mut self.packet).unwrap().result.get_mut().take().unwrap() - } -} - -/// An owned permission to join on a thread (block on its termination). -/// -/// A `JoinHandle` *detaches* the associated thread when it is dropped, which -/// means that there is no longer any handle to the thread and no way to `join` -/// on it. -/// -/// Due to platform restrictions, it is not possible to [`Clone`] this -/// handle: the ability to join a thread is a uniquely-owned permission. -/// -/// This `struct` is created by the [`thread::spawn`] function and the -/// [`thread::Builder::spawn`] method. -/// -/// # Examples -/// -/// Creation from [`thread::spawn`]: -/// -/// ``` -/// use std::thread; -/// -/// let join_handle: thread::JoinHandle<_> = thread::spawn(|| { -/// // some work here -/// }); -/// ``` -/// -/// Creation from [`thread::Builder::spawn`]: -/// -/// ``` -/// use std::thread; -/// -/// let builder = thread::Builder::new(); -/// -/// let join_handle: thread::JoinHandle<_> = builder.spawn(|| { -/// // some work here -/// }).unwrap(); -/// ``` -/// -/// A thread being detached and outliving the thread that spawned it: -/// -/// ```no_run -/// use std::thread; -/// use std::time::Duration; -/// -/// let original_thread = thread::spawn(|| { -/// let _detached_thread = thread::spawn(|| { -/// // Here we sleep to make sure that the first thread returns before. -/// thread::sleep(Duration::from_millis(10)); -/// // This will be called, even though the JoinHandle is dropped. -/// println!("♫ Still alive ♫"); -/// }); -/// }); -/// -/// original_thread.join().expect("The thread being joined has panicked"); -/// println!("Original thread is joined."); -/// -/// // We make sure that the new thread has time to run, before the main -/// // thread returns. -/// -/// thread::sleep(Duration::from_millis(1000)); -/// ``` -/// -/// [`thread::Builder::spawn`]: Builder::spawn -/// [`thread::spawn`]: spawn -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(target_os = "teeos", must_use)] -pub struct JoinHandle(JoinInner<'static, T>); - -#[stable(feature = "joinhandle_impl_send_sync", since = "1.29.0")] -unsafe impl Send for JoinHandle {} -#[stable(feature = "joinhandle_impl_send_sync", since = "1.29.0")] -unsafe impl Sync for JoinHandle {} - -impl JoinHandle { - /// Extracts a handle to the underlying thread. - /// - /// # Examples - /// - /// ``` - /// use std::thread; - /// - /// let builder = thread::Builder::new(); - /// - /// let join_handle: thread::JoinHandle<_> = builder.spawn(|| { - /// // some work here - /// }).unwrap(); - /// - /// let thread = join_handle.thread(); - /// println!("thread id: {:?}", thread.id()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - pub fn thread(&self) -> &Thread { - &self.0.thread - } - - /// Waits for the associated thread to finish. - /// - /// This function will return immediately if the associated thread has already finished. - /// - /// In terms of [atomic memory orderings], the completion of the associated - /// thread synchronizes with this function returning. In other words, all - /// operations performed by that thread [happen - /// before](https://doc.rust-lang.org/nomicon/atomics.html#data-accesses) all - /// operations that happen after `join` returns. - /// - /// If the associated thread panics, [`Err`] is returned with the parameter given - /// to [`panic!`]. - /// - /// [`Err`]: crate::result::Result::Err - /// [atomic memory orderings]: crate::sync::atomic - /// - /// # Panics - /// - /// This function may panic on some platforms if a thread attempts to join - /// itself or otherwise may create a deadlock with joining threads. - /// - /// # Examples - /// - /// ``` - /// use std::thread; - /// - /// let builder = thread::Builder::new(); - /// - /// let join_handle: thread::JoinHandle<_> = builder.spawn(|| { - /// // some work here - /// }).unwrap(); - /// join_handle.join().expect("Couldn't join on the associated thread"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn join(self) -> Result { - self.0.join() - } - - /// Checks if the associated thread has finished running its main function. - /// - /// `is_finished` supports implementing a non-blocking join operation, by checking - /// `is_finished`, and calling `join` if it returns `true`. This function does not block. To - /// block while waiting on the thread to finish, use [`join`][Self::join]. - /// - /// This might return `true` for a brief moment after the thread's main - /// function has returned, but before the thread itself has stopped running. - /// However, once this returns `true`, [`join`][Self::join] can be expected - /// to return quickly, without blocking for any significant amount of time. - #[stable(feature = "thread_is_running", since = "1.61.0")] - pub fn is_finished(&self) -> bool { - Arc::strong_count(&self.0.packet) == 1 - } -} - -impl AsInner for JoinHandle { - fn as_inner(&self) -> &imp::Thread { - &self.0.native - } -} - -impl IntoInner for JoinHandle { - fn into_inner(self) -> imp::Thread { - self.0.native - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for JoinHandle { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("JoinHandle").finish_non_exhaustive() - } -} - -fn _assert_sync_and_send() { - fn _assert_both() {} - _assert_both::>(); - _assert_both::(); -} - -/// Returns an estimate of the default amount of parallelism a program should use. -/// -/// Parallelism is a resource. A given machine provides a certain capacity for -/// parallelism, i.e., a bound on the number of computations it can perform -/// simultaneously. This number often corresponds to the amount of CPUs a -/// computer has, but it may diverge in various cases. -/// -/// Host environments such as VMs or container orchestrators may want to -/// restrict the amount of parallelism made available to programs in them. This -/// is often done to limit the potential impact of (unintentionally) -/// resource-intensive programs on other programs running on the same machine. -/// -/// # Limitations -/// -/// The purpose of this API is to provide an easy and portable way to query -/// the default amount of parallelism the program should use. Among other things it -/// does not expose information on NUMA regions, does not account for -/// differences in (co)processor capabilities or current system load, -/// and will not modify the program's global state in order to more accurately -/// query the amount of available parallelism. -/// -/// Where both fixed steady-state and burst limits are available the steady-state -/// capacity will be used to ensure more predictable latencies. -/// -/// Resource limits can be changed during the runtime of a program, therefore the value is -/// not cached and instead recomputed every time this function is called. It should not be -/// called from hot code. -/// -/// The value returned by this function should be considered a simplified -/// approximation of the actual amount of parallelism available at any given -/// time. To get a more detailed or precise overview of the amount of -/// parallelism available to the program, you may wish to use -/// platform-specific APIs as well. The following platform limitations currently -/// apply to `available_parallelism`: -/// -/// On Windows: -/// - It may undercount the amount of parallelism available on systems with more -/// than 64 logical CPUs. However, programs typically need specific support to -/// take advantage of more than 64 logical CPUs, and in the absence of such -/// support, the number returned by this function accurately reflects the -/// number of logical CPUs the program can use by default. -/// - It may overcount the amount of parallelism available on systems limited by -/// process-wide affinity masks, or job object limitations. -/// -/// On Linux: -/// - It may overcount the amount of parallelism available when limited by a -/// process-wide affinity mask or cgroup quotas and `sched_getaffinity()` or cgroup fs can't be -/// queried, e.g. due to sandboxing. -/// - It may undercount the amount of parallelism if the current thread's affinity mask -/// does not reflect the process' cpuset, e.g. due to pinned threads. -/// - If the process is in a cgroup v1 cpu controller, this may need to -/// scan mountpoints to find the corresponding cgroup v1 controller, -/// which may take time on systems with large numbers of mountpoints. -/// (This does not apply to cgroup v2, or to processes not in a -/// cgroup.) -/// -/// On all targets: -/// - It may overcount the amount of parallelism available when running in a VM -/// with CPU usage limits (e.g. an overcommitted host). -/// -/// # Errors -/// -/// This function will, but is not limited to, return errors in the following -/// cases: -/// -/// - If the amount of parallelism is not known for the target platform. -/// - If the program lacks permission to query the amount of parallelism made -/// available to it. -/// -/// # Examples -/// -/// ``` -/// # #![allow(dead_code)] -/// use std::{io, thread}; -/// -/// fn main() -> io::Result<()> { -/// let count = thread::available_parallelism()?.get(); -/// assert!(count >= 1_usize); -/// Ok(()) -/// } -/// ``` -#[doc(alias = "available_concurrency")] // Alias for a previous name we gave this API on unstable. -#[doc(alias = "hardware_concurrency")] // Alias for C++ `std::thread::hardware_concurrency`. -#[doc(alias = "num_cpus")] // Alias for a popular ecosystem crate which provides similar functionality. -#[stable(feature = "available_parallelism", since = "1.59.0")] -pub fn available_parallelism() -> io::Result> { - imp::available_parallelism() -} diff --git a/library/std/src/thread/scoped.rs b/library/std/src/thread/scoped.rs deleted file mode 100644 index e2e22e5194f4a..0000000000000 --- a/library/std/src/thread/scoped.rs +++ /dev/null @@ -1,349 +0,0 @@ -use super::{current, park, Builder, JoinInner, Result, Thread}; -use crate::fmt; -use crate::io; -use crate::marker::PhantomData; -use crate::panic::{catch_unwind, resume_unwind, AssertUnwindSafe}; -use crate::sync::atomic::{AtomicBool, AtomicUsize, Ordering}; -use crate::sync::Arc; - -/// A scope to spawn scoped threads in. -/// -/// See [`scope`] for details. -#[stable(feature = "scoped_threads", since = "1.63.0")] -pub struct Scope<'scope, 'env: 'scope> { - data: Arc, - /// Invariance over 'scope, to make sure 'scope cannot shrink, - /// which is necessary for soundness. - /// - /// Without invariance, this would compile fine but be unsound: - /// - /// ```compile_fail,E0373 - /// std::thread::scope(|s| { - /// s.spawn(|| { - /// let a = String::from("abcd"); - /// s.spawn(|| println!("{a:?}")); // might run after `a` is dropped - /// }); - /// }); - /// ``` - scope: PhantomData<&'scope mut &'scope ()>, - env: PhantomData<&'env mut &'env ()>, -} - -/// An owned permission to join on a scoped thread (block on its termination). -/// -/// See [`Scope::spawn`] for details. -#[stable(feature = "scoped_threads", since = "1.63.0")] -pub struct ScopedJoinHandle<'scope, T>(JoinInner<'scope, T>); - -pub(super) struct ScopeData { - num_running_threads: AtomicUsize, - a_thread_panicked: AtomicBool, - main_thread: Thread, -} - -impl ScopeData { - pub(super) fn increment_num_running_threads(&self) { - // We check for 'overflow' with usize::MAX / 2, to make sure there's no - // chance it overflows to 0, which would result in unsoundness. - if self.num_running_threads.fetch_add(1, Ordering::Relaxed) > usize::MAX / 2 { - // This can only reasonably happen by mem::forget()'ing a lot of ScopedJoinHandles. - self.overflow(); - } - } - - #[cold] - fn overflow(&self) { - self.decrement_num_running_threads(false); - panic!("too many running threads in thread scope"); - } - - pub(super) fn decrement_num_running_threads(&self, panic: bool) { - if panic { - self.a_thread_panicked.store(true, Ordering::Relaxed); - } - if self.num_running_threads.fetch_sub(1, Ordering::Release) == 1 { - self.main_thread.unpark(); - } - } -} - -/// Create a scope for spawning scoped threads. -/// -/// The function passed to `scope` will be provided a [`Scope`] object, -/// through which scoped threads can be [spawned][`Scope::spawn`]. -/// -/// Unlike non-scoped threads, scoped threads can borrow non-`'static` data, -/// as the scope guarantees all threads will be joined at the end of the scope. -/// -/// All threads spawned within the scope that haven't been manually joined -/// will be automatically joined before this function returns. -/// -/// # Panics -/// -/// If any of the automatically joined threads panicked, this function will panic. -/// -/// If you want to handle panics from spawned threads, -/// [`join`][ScopedJoinHandle::join] them before the end of the scope. -/// -/// # Example -/// -/// ``` -/// use std::thread; -/// -/// let mut a = vec![1, 2, 3]; -/// let mut x = 0; -/// -/// thread::scope(|s| { -/// s.spawn(|| { -/// println!("hello from the first scoped thread"); -/// // We can borrow `a` here. -/// dbg!(&a); -/// }); -/// s.spawn(|| { -/// println!("hello from the second scoped thread"); -/// // We can even mutably borrow `x` here, -/// // because no other threads are using it. -/// x += a[0] + a[2]; -/// }); -/// println!("hello from the main thread"); -/// }); -/// -/// // After the scope, we can modify and access our variables again: -/// a.push(4); -/// assert_eq!(x, a.len()); -/// ``` -/// -/// # Lifetimes -/// -/// Scoped threads involve two lifetimes: `'scope` and `'env`. -/// -/// The `'scope` lifetime represents the lifetime of the scope itself. -/// That is: the time during which new scoped threads may be spawned, -/// and also the time during which they might still be running. -/// Once this lifetime ends, all scoped threads are joined. -/// This lifetime starts within the `scope` function, before `f` (the argument to `scope`) starts. -/// It ends after `f` returns and all scoped threads have been joined, but before `scope` returns. -/// -/// The `'env` lifetime represents the lifetime of whatever is borrowed by the scoped threads. -/// This lifetime must outlast the call to `scope`, and thus cannot be smaller than `'scope`. -/// It can be as small as the call to `scope`, meaning that anything that outlives this call, -/// such as local variables defined right before the scope, can be borrowed by the scoped threads. -/// -/// The `'env: 'scope` bound is part of the definition of the `Scope` type. -#[track_caller] -#[stable(feature = "scoped_threads", since = "1.63.0")] -pub fn scope<'env, F, T>(f: F) -> T -where - F: for<'scope> FnOnce(&'scope Scope<'scope, 'env>) -> T, -{ - // We put the `ScopeData` into an `Arc` so that other threads can finish their - // `decrement_num_running_threads` even after this function returns. - let scope = Scope { - data: Arc::new(ScopeData { - num_running_threads: AtomicUsize::new(0), - main_thread: current(), - a_thread_panicked: AtomicBool::new(false), - }), - env: PhantomData, - scope: PhantomData, - }; - - // Run `f`, but catch panics so we can make sure to wait for all the threads to join. - let result = catch_unwind(AssertUnwindSafe(|| f(&scope))); - - // Wait until all the threads are finished. - while scope.data.num_running_threads.load(Ordering::Acquire) != 0 { - park(); - } - - // Throw any panic from `f`, or the return value of `f` if no thread panicked. - match result { - Err(e) => resume_unwind(e), - Ok(_) if scope.data.a_thread_panicked.load(Ordering::Relaxed) => { - panic!("a scoped thread panicked") - } - Ok(result) => result, - } -} - -impl<'scope, 'env> Scope<'scope, 'env> { - /// Spawns a new thread within a scope, returning a [`ScopedJoinHandle`] for it. - /// - /// Unlike non-scoped threads, threads spawned with this function may - /// borrow non-`'static` data from the outside the scope. See [`scope`] for - /// details. - /// - /// The join handle provides a [`join`] method that can be used to join the spawned - /// thread. If the spawned thread panics, [`join`] will return an [`Err`] containing - /// the panic payload. - /// - /// If the join handle is dropped, the spawned thread will implicitly joined at the - /// end of the scope. In that case, if the spawned thread panics, [`scope`] will - /// panic after all threads are joined. - /// - /// This call will create a thread using default parameters of [`Builder`]. - /// If you want to specify the stack size or the name of the thread, use - /// [`Builder::spawn_scoped`] instead. - /// - /// # Panics - /// - /// Panics if the OS fails to create a thread; use [`Builder::spawn_scoped`] - /// to recover from such errors. - /// - /// [`join`]: ScopedJoinHandle::join - #[stable(feature = "scoped_threads", since = "1.63.0")] - pub fn spawn(&'scope self, f: F) -> ScopedJoinHandle<'scope, T> - where - F: FnOnce() -> T + Send + 'scope, - T: Send + 'scope, - { - Builder::new().spawn_scoped(self, f).expect("failed to spawn thread") - } -} - -impl Builder { - /// Spawns a new scoped thread using the settings set through this `Builder`. - /// - /// Unlike [`Scope::spawn`], this method yields an [`io::Result`] to - /// capture any failure to create the thread at the OS level. - /// - /// [`io::Result`]: crate::io::Result - /// - /// # Panics - /// - /// Panics if a thread name was set and it contained null bytes. - /// - /// # Example - /// - /// ``` - /// use std::thread; - /// - /// let mut a = vec![1, 2, 3]; - /// let mut x = 0; - /// - /// thread::scope(|s| { - /// thread::Builder::new() - /// .name("first".to_string()) - /// .spawn_scoped(s, || - /// { - /// println!("hello from the {:?} scoped thread", thread::current().name()); - /// // We can borrow `a` here. - /// dbg!(&a); - /// }) - /// .unwrap(); - /// thread::Builder::new() - /// .name("second".to_string()) - /// .spawn_scoped(s, || - /// { - /// println!("hello from the {:?} scoped thread", thread::current().name()); - /// // We can even mutably borrow `x` here, - /// // because no other threads are using it. - /// x += a[0] + a[2]; - /// }) - /// .unwrap(); - /// println!("hello from the main thread"); - /// }); - /// - /// // After the scope, we can modify and access our variables again: - /// a.push(4); - /// assert_eq!(x, a.len()); - /// ``` - #[stable(feature = "scoped_threads", since = "1.63.0")] - pub fn spawn_scoped<'scope, 'env, F, T>( - self, - scope: &'scope Scope<'scope, 'env>, - f: F, - ) -> io::Result> - where - F: FnOnce() -> T + Send + 'scope, - T: Send + 'scope, - { - Ok(ScopedJoinHandle(unsafe { self.spawn_unchecked_(f, Some(scope.data.clone())) }?)) - } -} - -impl<'scope, T> ScopedJoinHandle<'scope, T> { - /// Extracts a handle to the underlying thread. - /// - /// # Examples - /// - /// ``` - /// use std::thread; - /// - /// thread::scope(|s| { - /// let t = s.spawn(|| { - /// println!("hello"); - /// }); - /// println!("thread id: {:?}", t.thread().id()); - /// }); - /// ``` - #[must_use] - #[stable(feature = "scoped_threads", since = "1.63.0")] - pub fn thread(&self) -> &Thread { - &self.0.thread - } - - /// Waits for the associated thread to finish. - /// - /// This function will return immediately if the associated thread has already finished. - /// - /// In terms of [atomic memory orderings], the completion of the associated - /// thread synchronizes with this function returning. - /// In other words, all operations performed by that thread - /// [happen before](https://doc.rust-lang.org/nomicon/atomics.html#data-accesses) - /// all operations that happen after `join` returns. - /// - /// If the associated thread panics, [`Err`] is returned with the panic payload. - /// - /// [atomic memory orderings]: crate::sync::atomic - /// - /// # Examples - /// - /// ``` - /// use std::thread; - /// - /// thread::scope(|s| { - /// let t = s.spawn(|| { - /// panic!("oh no"); - /// }); - /// assert!(t.join().is_err()); - /// }); - /// ``` - #[stable(feature = "scoped_threads", since = "1.63.0")] - pub fn join(self) -> Result { - self.0.join() - } - - /// Checks if the associated thread has finished running its main function. - /// - /// `is_finished` supports implementing a non-blocking join operation, by checking - /// `is_finished`, and calling `join` if it returns `true`. This function does not block. To - /// block while waiting on the thread to finish, use [`join`][Self::join]. - /// - /// This might return `true` for a brief moment after the thread's main - /// function has returned, but before the thread itself has stopped running. - /// However, once this returns `true`, [`join`][Self::join] can be expected - /// to return quickly, without blocking for any significant amount of time. - #[stable(feature = "scoped_threads", since = "1.63.0")] - pub fn is_finished(&self) -> bool { - Arc::strong_count(&self.0.packet) == 1 - } -} - -#[stable(feature = "scoped_threads", since = "1.63.0")] -impl fmt::Debug for Scope<'_, '_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Scope") - .field("num_running_threads", &self.data.num_running_threads.load(Ordering::Relaxed)) - .field("a_thread_panicked", &self.data.a_thread_panicked.load(Ordering::Relaxed)) - .field("main_thread", &self.data.main_thread) - .finish_non_exhaustive() - } -} - -#[stable(feature = "scoped_threads", since = "1.63.0")] -impl<'scope, T> fmt::Debug for ScopedJoinHandle<'scope, T> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("ScopedJoinHandle").finish_non_exhaustive() - } -} diff --git a/library/std/src/thread/tests.rs b/library/std/src/thread/tests.rs deleted file mode 100644 index 1fb1333be0e45..0000000000000 --- a/library/std/src/thread/tests.rs +++ /dev/null @@ -1,416 +0,0 @@ -use super::Builder; -use crate::any::Any; -use crate::mem; -use crate::panic::panic_any; -use crate::result; -use crate::sync::{ - atomic::{AtomicBool, Ordering}, - mpsc::{channel, Sender}, - Arc, Barrier, -}; -use crate::thread::{self, Scope, ThreadId}; -use crate::time::Duration; -use crate::time::Instant; - -// !!! These tests are dangerous. If something is buggy, they will hang, !!! -// !!! instead of exiting cleanly. This might wedge the buildbots. !!! - -#[test] -fn test_unnamed_thread() { - thread::spawn(move || { - assert!(thread::current().name().is_none()); - }) - .join() - .ok() - .expect("thread panicked"); -} - -#[test] -fn test_named_thread() { - Builder::new() - .name("ada lovelace".to_string()) - .spawn(move || { - assert!(thread::current().name().unwrap() == "ada lovelace".to_string()); - }) - .unwrap() - .join() - .unwrap(); -} - -#[cfg(any( - // Note: musl didn't add pthread_getname_np until 1.2.3 - all(target_os = "linux", target_env = "gnu"), - target_vendor = "apple", -))] -#[test] -fn test_named_thread_truncation() { - use crate::ffi::CStr; - - let long_name = crate::iter::once("test_named_thread_truncation") - .chain(crate::iter::repeat(" yada").take(100)) - .collect::(); - - let result = Builder::new().name(long_name.clone()).spawn(move || { - // Rust remembers the full thread name itself. - assert_eq!(thread::current().name(), Some(long_name.as_str())); - - // But the system is limited -- make sure we successfully set a truncation. - let mut buf = vec![0u8; long_name.len() + 1]; - unsafe { - libc::pthread_getname_np(libc::pthread_self(), buf.as_mut_ptr().cast(), buf.len()); - } - let cstr = CStr::from_bytes_until_nul(&buf).unwrap(); - assert!(cstr.to_bytes().len() > 0); - assert!(long_name.as_bytes().starts_with(cstr.to_bytes())); - }); - result.unwrap().join().unwrap(); -} - -#[test] -#[should_panic] -fn test_invalid_named_thread() { - let _ = Builder::new().name("ada l\0velace".to_string()).spawn(|| {}); -} - -#[test] -fn test_run_basic() { - let (tx, rx) = channel(); - thread::spawn(move || { - tx.send(()).unwrap(); - }); - rx.recv().unwrap(); -} - -#[test] -fn test_is_finished() { - let b = Arc::new(Barrier::new(2)); - let t = thread::spawn({ - let b = b.clone(); - move || { - b.wait(); - 1234 - } - }); - - // Thread is definitely running here, since it's still waiting for the barrier. - assert_eq!(t.is_finished(), false); - - // Unblock the barrier. - b.wait(); - - // Now check that t.is_finished() becomes true within a reasonable time. - let start = Instant::now(); - while !t.is_finished() { - assert!(start.elapsed() < Duration::from_secs(2)); - thread::sleep(Duration::from_millis(15)); - } - - // Joining the thread should not block for a significant time now. - let join_time = Instant::now(); - assert_eq!(t.join().unwrap(), 1234); - assert!(join_time.elapsed() < Duration::from_secs(2)); -} - -#[test] -fn test_join_panic() { - match thread::spawn(move || panic!()).join() { - result::Result::Err(_) => (), - result::Result::Ok(()) => panic!(), - } -} - -#[test] -fn test_spawn_sched() { - let (tx, rx) = channel(); - - fn f(i: i32, tx: Sender<()>) { - let tx = tx.clone(); - thread::spawn(move || { - if i == 0 { - tx.send(()).unwrap(); - } else { - f(i - 1, tx); - } - }); - } - f(10, tx); - rx.recv().unwrap(); -} - -#[test] -fn test_spawn_sched_childs_on_default_sched() { - let (tx, rx) = channel(); - - thread::spawn(move || { - thread::spawn(move || { - tx.send(()).unwrap(); - }); - }); - - rx.recv().unwrap(); -} - -fn avoid_copying_the_body(spawnfn: F) -where - F: FnOnce(Box), -{ - let (tx, rx) = channel(); - - let x: Box<_> = Box::new(1); - let x_in_parent = (&*x) as *const i32 as usize; - - spawnfn(Box::new(move || { - let x_in_child = (&*x) as *const i32 as usize; - tx.send(x_in_child).unwrap(); - })); - - let x_in_child = rx.recv().unwrap(); - assert_eq!(x_in_parent, x_in_child); -} - -#[test] -fn test_avoid_copying_the_body_spawn() { - avoid_copying_the_body(|v| { - thread::spawn(move || v()); - }); -} - -#[test] -fn test_avoid_copying_the_body_thread_spawn() { - avoid_copying_the_body(|f| { - thread::spawn(move || { - f(); - }); - }) -} - -#[test] -fn test_avoid_copying_the_body_join() { - avoid_copying_the_body(|f| { - let _ = thread::spawn(move || f()).join(); - }) -} - -#[test] -fn test_child_doesnt_ref_parent() { - // If the child refcounts the parent thread, this will stack overflow when - // climbing the thread tree to dereference each ancestor. (See #1789) - // (well, it would if the constant were 8000+ - I lowered it to be more - // valgrind-friendly. try this at home, instead..!) - const GENERATIONS: u32 = 16; - fn child_no(x: u32) -> Box { - return Box::new(move || { - if x < GENERATIONS { - thread::spawn(move || child_no(x + 1)()); - } - }); - } - thread::spawn(|| child_no(0)()); -} - -#[test] -fn test_simple_newsched_spawn() { - thread::spawn(move || {}); -} - -#[test] -fn test_try_panic_message_string_literal() { - match thread::spawn(move || { - panic!("static string"); - }) - .join() - { - Err(e) => { - type T = &'static str; - assert!(e.is::()); - assert_eq!(*e.downcast::().unwrap(), "static string"); - } - Ok(()) => panic!(), - } -} - -#[test] -fn test_try_panic_any_message_owned_str() { - match thread::spawn(move || { - panic_any("owned string".to_string()); - }) - .join() - { - Err(e) => { - type T = String; - assert!(e.is::()); - assert_eq!(*e.downcast::().unwrap(), "owned string".to_string()); - } - Ok(()) => panic!(), - } -} - -#[test] -fn test_try_panic_any_message_any() { - match thread::spawn(move || { - panic_any(Box::new(413u16) as Box); - }) - .join() - { - Err(e) => { - type T = Box; - assert!(e.is::()); - let any = e.downcast::().unwrap(); - assert!(any.is::()); - assert_eq!(*any.downcast::().unwrap(), 413); - } - Ok(()) => panic!(), - } -} - -#[test] -fn test_try_panic_any_message_unit_struct() { - struct Juju; - - match thread::spawn(move || panic_any(Juju)).join() { - Err(ref e) if e.is::() => {} - Err(_) | Ok(()) => panic!(), - } -} - -#[test] -fn test_park_unpark_before() { - for _ in 0..10 { - thread::current().unpark(); - thread::park(); - } -} - -#[test] -fn test_park_unpark_called_other_thread() { - for _ in 0..10 { - let th = thread::current(); - - let _guard = thread::spawn(move || { - super::sleep(Duration::from_millis(50)); - th.unpark(); - }); - - thread::park(); - } -} - -#[test] -fn test_park_timeout_unpark_before() { - for _ in 0..10 { - thread::current().unpark(); - thread::park_timeout(Duration::from_millis(u32::MAX as u64)); - } -} - -#[test] -fn test_park_timeout_unpark_not_called() { - for _ in 0..10 { - thread::park_timeout(Duration::from_millis(10)); - } -} - -#[test] -fn test_park_timeout_unpark_called_other_thread() { - for _ in 0..10 { - let th = thread::current(); - - let _guard = thread::spawn(move || { - super::sleep(Duration::from_millis(50)); - th.unpark(); - }); - - thread::park_timeout(Duration::from_millis(u32::MAX as u64)); - } -} - -#[test] -fn sleep_ms_smoke() { - thread::sleep(Duration::from_millis(2)); -} - -#[test] -fn test_size_of_option_thread_id() { - assert_eq!(mem::size_of::>(), mem::size_of::()); -} - -#[test] -fn test_thread_id_equal() { - assert!(thread::current().id() == thread::current().id()); -} - -#[test] -fn test_thread_id_not_equal() { - let spawned_id = thread::spawn(|| thread::current().id()).join().unwrap(); - assert!(thread::current().id() != spawned_id); -} - -#[test] -fn test_scoped_threads_drop_result_before_join() { - let actually_finished = &AtomicBool::new(false); - struct X<'scope, 'env>(&'scope Scope<'scope, 'env>, &'env AtomicBool); - impl Drop for X<'_, '_> { - fn drop(&mut self) { - thread::sleep(Duration::from_millis(20)); - let actually_finished = self.1; - self.0.spawn(move || { - thread::sleep(Duration::from_millis(20)); - actually_finished.store(true, Ordering::Relaxed); - }); - } - } - thread::scope(|s| { - s.spawn(move || { - thread::sleep(Duration::from_millis(20)); - X(s, actually_finished) - }); - }); - assert!(actually_finished.load(Ordering::Relaxed)); -} - -#[test] -fn test_scoped_threads_nll() { - // this is mostly a *compilation test* for this exact function: - fn foo(x: &u8) { - thread::scope(|s| { - s.spawn(|| match x { - _ => (), - }); - }); - } - // let's also run it for good measure - let x = 42_u8; - foo(&x); -} - -// Regression test for https://github.com/rust-lang/rust/issues/98498. -#[test] -#[cfg(miri)] // relies on Miri's data race detector -fn scope_join_race() { - for _ in 0..100 { - let a_bool = AtomicBool::new(false); - - thread::scope(|s| { - for _ in 0..5 { - s.spawn(|| a_bool.load(Ordering::Relaxed)); - } - - for _ in 0..5 { - s.spawn(|| a_bool.load(Ordering::Relaxed)); - } - }); - } -} - -// Test that the smallest value for stack_size works on Windows. -#[cfg(windows)] -#[test] -fn test_minimal_thread_stack() { - use crate::sync::atomic::AtomicU8; - static COUNT: AtomicU8 = AtomicU8::new(0); - - let builder = thread::Builder::new().stack_size(1); - let before = builder.spawn(|| COUNT.fetch_add(1, Ordering::Relaxed)).unwrap().join().unwrap(); - assert_eq!(before, 0); - assert_eq!(COUNT.load(Ordering::Relaxed), 1); -} diff --git a/library/std/src/time.rs b/library/std/src/time.rs deleted file mode 100644 index 6f1a354d28a85..0000000000000 --- a/library/std/src/time.rs +++ /dev/null @@ -1,719 +0,0 @@ -//! Temporal quantification. -//! -//! # Examples -//! -//! There are multiple ways to create a new [`Duration`]: -//! -//! ``` -//! # use std::time::Duration; -//! let five_seconds = Duration::from_secs(5); -//! assert_eq!(five_seconds, Duration::from_millis(5_000)); -//! assert_eq!(five_seconds, Duration::from_micros(5_000_000)); -//! assert_eq!(five_seconds, Duration::from_nanos(5_000_000_000)); -//! -//! let ten_seconds = Duration::from_secs(10); -//! let seven_nanos = Duration::from_nanos(7); -//! let total = ten_seconds + seven_nanos; -//! assert_eq!(total, Duration::new(10, 7)); -//! ``` -//! -//! Using [`Instant`] to calculate how long a function took to run: -//! -//! ```ignore (incomplete) -//! let now = Instant::now(); -//! -//! // Calling a slow function, it may take a while -//! slow_function(); -//! -//! let elapsed_time = now.elapsed(); -//! println!("Running slow_function() took {} seconds.", elapsed_time.as_secs()); -//! ``` - -#![stable(feature = "time", since = "1.3.0")] - -#[cfg(test)] -mod tests; - -use crate::error::Error; -use crate::fmt; -use crate::ops::{Add, AddAssign, Sub, SubAssign}; -use crate::sys::time; -use crate::sys_common::{FromInner, IntoInner}; - -#[stable(feature = "time", since = "1.3.0")] -pub use core::time::Duration; - -#[stable(feature = "duration_checked_float", since = "1.66.0")] -pub use core::time::TryFromFloatSecsError; - -/// A measurement of a monotonically nondecreasing clock. -/// Opaque and useful only with [`Duration`]. -/// -/// Instants are always guaranteed, barring [platform bugs], to be no less than any previously -/// measured instant when created, and are often useful for tasks such as measuring -/// benchmarks or timing how long an operation takes. -/// -/// Note, however, that instants are **not** guaranteed to be **steady**. In other -/// words, each tick of the underlying clock might not be the same length (e.g. -/// some seconds may be longer than others). An instant may jump forwards or -/// experience time dilation (slow down or speed up), but it will never go -/// backwards. -/// As part of this non-guarantee it is also not specified whether system suspends count as -/// elapsed time or not. The behavior varies across platforms and Rust versions. -/// -/// Instants are opaque types that can only be compared to one another. There is -/// no method to get "the number of seconds" from an instant. Instead, it only -/// allows measuring the duration between two instants (or comparing two -/// instants). -/// -/// The size of an `Instant` struct may vary depending on the target operating -/// system. -/// -/// Example: -/// -/// ```no_run -/// use std::time::{Duration, Instant}; -/// use std::thread::sleep; -/// -/// fn main() { -/// let now = Instant::now(); -/// -/// // we sleep for 2 seconds -/// sleep(Duration::new(2, 0)); -/// // it prints '2' -/// println!("{}", now.elapsed().as_secs()); -/// } -/// ``` -/// -/// [platform bugs]: Instant#monotonicity -/// -/// # OS-specific behaviors -/// -/// An `Instant` is a wrapper around system-specific types and it may behave -/// differently depending on the underlying operating system. For example, -/// the following snippet is fine on Linux but panics on macOS: -/// -/// ```no_run -/// use std::time::{Instant, Duration}; -/// -/// let now = Instant::now(); -/// let max_seconds = u64::MAX / 1_000_000_000; -/// let duration = Duration::new(max_seconds, 0); -/// println!("{:?}", now + duration); -/// ``` -/// -/// # Underlying System calls -/// -/// The following system calls are [currently] being used by `now()` to find out -/// the current time: -/// -/// | Platform | System call | -/// |-----------|----------------------------------------------------------------------| -/// | SGX | [`insecure_time` usercall]. More information on [timekeeping in SGX] | -/// | UNIX | [clock_gettime (Monotonic Clock)] | -/// | Darwin | [clock_gettime (Monotonic Clock)] | -/// | VXWorks | [clock_gettime (Monotonic Clock)] | -/// | SOLID | `get_tim` | -/// | WASI | [__wasi_clock_time_get (Monotonic Clock)] | -/// | Windows | [QueryPerformanceCounter] | -/// -/// [currently]: crate::io#platform-specific-behavior -/// [QueryPerformanceCounter]: https://docs.microsoft.com/en-us/windows/win32/api/profileapi/nf-profileapi-queryperformancecounter -/// [`insecure_time` usercall]: https://edp.fortanix.com/docs/api/fortanix_sgx_abi/struct.Usercalls.html#method.insecure_time -/// [timekeeping in SGX]: https://edp.fortanix.com/docs/concepts/rust-std/#codestdtimecode -/// [__wasi_clock_time_get (Monotonic Clock)]: https://github.com/WebAssembly/WASI/blob/main/legacy/preview1/docs.md#clock_time_get -/// [clock_gettime (Monotonic Clock)]: https://linux.die.net/man/3/clock_gettime -/// -/// **Disclaimer:** These system calls might change over time. -/// -/// > Note: mathematical operations like [`add`] may panic if the underlying -/// > structure cannot represent the new point in time. -/// -/// [`add`]: Instant::add -/// -/// ## Monotonicity -/// -/// On all platforms `Instant` will try to use an OS API that guarantees monotonic behavior -/// if available, which is the case for all [tier 1] platforms. -/// In practice such guarantees are – under rare circumstances – broken by hardware, virtualization -/// or operating system bugs. To work around these bugs and platforms not offering monotonic clocks -/// [`duration_since`], [`elapsed`] and [`sub`] saturate to zero. In older Rust versions this -/// lead to a panic instead. [`checked_duration_since`] can be used to detect and handle situations -/// where monotonicity is violated, or `Instant`s are subtracted in the wrong order. -/// -/// This workaround obscures programming errors where earlier and later instants are accidentally -/// swapped. For this reason future Rust versions may reintroduce panics. -/// -/// [tier 1]: https://doc.rust-lang.org/rustc/platform-support.html -/// [`duration_since`]: Instant::duration_since -/// [`elapsed`]: Instant::elapsed -/// [`sub`]: Instant::sub -/// [`checked_duration_since`]: Instant::checked_duration_since -/// -#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] -#[stable(feature = "time2", since = "1.8.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "Instant")] -pub struct Instant(time::Instant); - -/// A measurement of the system clock, useful for talking to -/// external entities like the file system or other processes. -/// -/// Distinct from the [`Instant`] type, this time measurement **is not -/// monotonic**. This means that you can save a file to the file system, then -/// save another file to the file system, **and the second file has a -/// `SystemTime` measurement earlier than the first**. In other words, an -/// operation that happens after another operation in real time may have an -/// earlier `SystemTime`! -/// -/// Consequently, comparing two `SystemTime` instances to learn about the -/// duration between them returns a [`Result`] instead of an infallible [`Duration`] -/// to indicate that this sort of time drift may happen and needs to be handled. -/// -/// Although a `SystemTime` cannot be directly inspected, the [`UNIX_EPOCH`] -/// constant is provided in this module as an anchor in time to learn -/// information about a `SystemTime`. By calculating the duration from this -/// fixed point in time, a `SystemTime` can be converted to a human-readable time, -/// or perhaps some other string representation. -/// -/// The size of a `SystemTime` struct may vary depending on the target operating -/// system. -/// -/// A `SystemTime` does not count leap seconds. -/// `SystemTime::now()`'s behaviour around a leap second -/// is the same as the operating system's wall clock. -/// The precise behaviour near a leap second -/// (e.g. whether the clock appears to run slow or fast, or stop, or jump) -/// depends on platform and configuration, -/// so should not be relied on. -/// -/// Example: -/// -/// ```no_run -/// use std::time::{Duration, SystemTime}; -/// use std::thread::sleep; -/// -/// fn main() { -/// let now = SystemTime::now(); -/// -/// // we sleep for 2 seconds -/// sleep(Duration::new(2, 0)); -/// match now.elapsed() { -/// Ok(elapsed) => { -/// // it prints '2' -/// println!("{}", elapsed.as_secs()); -/// } -/// Err(e) => { -/// // an error occurred! -/// println!("Error: {e:?}"); -/// } -/// } -/// } -/// ``` -/// -/// # Platform-specific behavior -/// -/// The precision of `SystemTime` can depend on the underlying OS-specific time format. -/// For example, on Windows the time is represented in 100 nanosecond intervals whereas Linux -/// can represent nanosecond intervals. -/// -/// The following system calls are [currently] being used by `now()` to find out -/// the current time: -/// -/// | Platform | System call | -/// |-----------|----------------------------------------------------------------------| -/// | SGX | [`insecure_time` usercall]. More information on [timekeeping in SGX] | -/// | UNIX | [clock_gettime (Realtime Clock)] | -/// | Darwin | [clock_gettime (Realtime Clock)] | -/// | VXWorks | [clock_gettime (Realtime Clock)] | -/// | SOLID | `SOLID_RTC_ReadTime` | -/// | WASI | [__wasi_clock_time_get (Realtime Clock)] | -/// | Windows | [GetSystemTimePreciseAsFileTime] / [GetSystemTimeAsFileTime] | -/// -/// [currently]: crate::io#platform-specific-behavior -/// [`insecure_time` usercall]: https://edp.fortanix.com/docs/api/fortanix_sgx_abi/struct.Usercalls.html#method.insecure_time -/// [timekeeping in SGX]: https://edp.fortanix.com/docs/concepts/rust-std/#codestdtimecode -/// [clock_gettime (Realtime Clock)]: https://linux.die.net/man/3/clock_gettime -/// [__wasi_clock_time_get (Realtime Clock)]: https://github.com/WebAssembly/WASI/blob/main/legacy/preview1/docs.md#clock_time_get -/// [GetSystemTimePreciseAsFileTime]: https://docs.microsoft.com/en-us/windows/win32/api/sysinfoapi/nf-sysinfoapi-getsystemtimepreciseasfiletime -/// [GetSystemTimeAsFileTime]: https://docs.microsoft.com/en-us/windows/win32/api/sysinfoapi/nf-sysinfoapi-getsystemtimeasfiletime -/// -/// **Disclaimer:** These system calls might change over time. -/// -/// > Note: mathematical operations like [`add`] may panic if the underlying -/// > structure cannot represent the new point in time. -/// -/// [`add`]: SystemTime::add -#[derive(Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)] -#[stable(feature = "time2", since = "1.8.0")] -pub struct SystemTime(time::SystemTime); - -/// An error returned from the `duration_since` and `elapsed` methods on -/// `SystemTime`, used to learn how far in the opposite direction a system time -/// lies. -/// -/// # Examples -/// -/// ```no_run -/// use std::thread::sleep; -/// use std::time::{Duration, SystemTime}; -/// -/// let sys_time = SystemTime::now(); -/// sleep(Duration::from_secs(1)); -/// let new_sys_time = SystemTime::now(); -/// match sys_time.duration_since(new_sys_time) { -/// Ok(_) => {} -/// Err(e) => println!("SystemTimeError difference: {:?}", e.duration()), -/// } -/// ``` -#[derive(Clone, Debug)] -#[stable(feature = "time2", since = "1.8.0")] -pub struct SystemTimeError(Duration); - -impl Instant { - /// Returns an instant corresponding to "now". - /// - /// # Examples - /// - /// ``` - /// use std::time::Instant; - /// - /// let now = Instant::now(); - /// ``` - #[must_use] - #[stable(feature = "time2", since = "1.8.0")] - pub fn now() -> Instant { - Instant(time::Instant::now()) - } - - /// Returns the amount of time elapsed from another instant to this one, - /// or zero duration if that instant is later than this one. - /// - /// # Panics - /// - /// Previous Rust versions panicked when `earlier` was later than `self`. Currently this - /// method saturates. Future versions may reintroduce the panic in some circumstances. - /// See [Monotonicity]. - /// - /// [Monotonicity]: Instant#monotonicity - /// - /// # Examples - /// - /// ```no_run - /// use std::time::{Duration, Instant}; - /// use std::thread::sleep; - /// - /// let now = Instant::now(); - /// sleep(Duration::new(1, 0)); - /// let new_now = Instant::now(); - /// println!("{:?}", new_now.duration_since(now)); - /// println!("{:?}", now.duration_since(new_now)); // 0ns - /// ``` - #[must_use] - #[stable(feature = "time2", since = "1.8.0")] - pub fn duration_since(&self, earlier: Instant) -> Duration { - self.checked_duration_since(earlier).unwrap_or_default() - } - - /// Returns the amount of time elapsed from another instant to this one, - /// or None if that instant is later than this one. - /// - /// Due to [monotonicity bugs], even under correct logical ordering of the passed `Instant`s, - /// this method can return `None`. - /// - /// [monotonicity bugs]: Instant#monotonicity - /// - /// # Examples - /// - /// ```no_run - /// use std::time::{Duration, Instant}; - /// use std::thread::sleep; - /// - /// let now = Instant::now(); - /// sleep(Duration::new(1, 0)); - /// let new_now = Instant::now(); - /// println!("{:?}", new_now.checked_duration_since(now)); - /// println!("{:?}", now.checked_duration_since(new_now)); // None - /// ``` - #[must_use] - #[stable(feature = "checked_duration_since", since = "1.39.0")] - pub fn checked_duration_since(&self, earlier: Instant) -> Option { - self.0.checked_sub_instant(&earlier.0) - } - - /// Returns the amount of time elapsed from another instant to this one, - /// or zero duration if that instant is later than this one. - /// - /// # Examples - /// - /// ```no_run - /// use std::time::{Duration, Instant}; - /// use std::thread::sleep; - /// - /// let now = Instant::now(); - /// sleep(Duration::new(1, 0)); - /// let new_now = Instant::now(); - /// println!("{:?}", new_now.saturating_duration_since(now)); - /// println!("{:?}", now.saturating_duration_since(new_now)); // 0ns - /// ``` - #[must_use] - #[stable(feature = "checked_duration_since", since = "1.39.0")] - pub fn saturating_duration_since(&self, earlier: Instant) -> Duration { - self.checked_duration_since(earlier).unwrap_or_default() - } - - /// Returns the amount of time elapsed since this instant. - /// - /// # Panics - /// - /// Previous Rust versions panicked when the current time was earlier than self. Currently this - /// method returns a Duration of zero in that case. Future versions may reintroduce the panic. - /// See [Monotonicity]. - /// - /// [Monotonicity]: Instant#monotonicity - /// - /// # Examples - /// - /// ```no_run - /// use std::thread::sleep; - /// use std::time::{Duration, Instant}; - /// - /// let instant = Instant::now(); - /// let three_secs = Duration::from_secs(3); - /// sleep(three_secs); - /// assert!(instant.elapsed() >= three_secs); - /// ``` - #[must_use] - #[stable(feature = "time2", since = "1.8.0")] - pub fn elapsed(&self) -> Duration { - Instant::now() - *self - } - - /// Returns `Some(t)` where `t` is the time `self + duration` if `t` can be represented as - /// `Instant` (which means it's inside the bounds of the underlying data structure), `None` - /// otherwise. - #[stable(feature = "time_checked_add", since = "1.34.0")] - pub fn checked_add(&self, duration: Duration) -> Option { - self.0.checked_add_duration(&duration).map(Instant) - } - - /// Returns `Some(t)` where `t` is the time `self - duration` if `t` can be represented as - /// `Instant` (which means it's inside the bounds of the underlying data structure), `None` - /// otherwise. - #[stable(feature = "time_checked_add", since = "1.34.0")] - pub fn checked_sub(&self, duration: Duration) -> Option { - self.0.checked_sub_duration(&duration).map(Instant) - } -} - -#[stable(feature = "time2", since = "1.8.0")] -impl Add for Instant { - type Output = Instant; - - /// # Panics - /// - /// This function may panic if the resulting point in time cannot be represented by the - /// underlying data structure. See [`Instant::checked_add`] for a version without panic. - fn add(self, other: Duration) -> Instant { - self.checked_add(other).expect("overflow when adding duration to instant") - } -} - -#[stable(feature = "time_augmented_assignment", since = "1.9.0")] -impl AddAssign for Instant { - fn add_assign(&mut self, other: Duration) { - *self = *self + other; - } -} - -#[stable(feature = "time2", since = "1.8.0")] -impl Sub for Instant { - type Output = Instant; - - fn sub(self, other: Duration) -> Instant { - self.checked_sub(other).expect("overflow when subtracting duration from instant") - } -} - -#[stable(feature = "time_augmented_assignment", since = "1.9.0")] -impl SubAssign for Instant { - fn sub_assign(&mut self, other: Duration) { - *self = *self - other; - } -} - -#[stable(feature = "time2", since = "1.8.0")] -impl Sub for Instant { - type Output = Duration; - - /// Returns the amount of time elapsed from another instant to this one, - /// or zero duration if that instant is later than this one. - /// - /// # Panics - /// - /// Previous Rust versions panicked when `other` was later than `self`. Currently this - /// method saturates. Future versions may reintroduce the panic in some circumstances. - /// See [Monotonicity]. - /// - /// [Monotonicity]: Instant#monotonicity - fn sub(self, other: Instant) -> Duration { - self.duration_since(other) - } -} - -#[stable(feature = "time2", since = "1.8.0")] -impl fmt::Debug for Instant { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0.fmt(f) - } -} - -impl SystemTime { - /// An anchor in time which can be used to create new `SystemTime` instances or - /// learn about where in time a `SystemTime` lies. - // - // NOTE! this documentation is duplicated, here and in std::time::UNIX_EPOCH. - // The two copies are not quite identical, because of the difference in naming. - /// - /// This constant is defined to be "1970-01-01 00:00:00 UTC" on all systems with - /// respect to the system clock. Using `duration_since` on an existing - /// `SystemTime` instance can tell how far away from this point in time a - /// measurement lies, and using `UNIX_EPOCH + duration` can be used to create a - /// `SystemTime` instance to represent another fixed point in time. - /// - /// `duration_since(UNIX_EPOCH).unwrap().as_secs()` returns - /// the number of non-leap seconds since the start of 1970 UTC. - /// This is a POSIX `time_t` (as a `u64`), - /// and is the same time representation as used in many Internet protocols. - /// - /// # Examples - /// - /// ```no_run - /// use std::time::SystemTime; - /// - /// match SystemTime::now().duration_since(SystemTime::UNIX_EPOCH) { - /// Ok(n) => println!("1970-01-01 00:00:00 UTC was {} seconds ago!", n.as_secs()), - /// Err(_) => panic!("SystemTime before UNIX EPOCH!"), - /// } - /// ``` - #[stable(feature = "assoc_unix_epoch", since = "1.28.0")] - pub const UNIX_EPOCH: SystemTime = UNIX_EPOCH; - - /// Returns the system time corresponding to "now". - /// - /// # Examples - /// - /// ``` - /// use std::time::SystemTime; - /// - /// let sys_time = SystemTime::now(); - /// ``` - #[must_use] - #[stable(feature = "time2", since = "1.8.0")] - pub fn now() -> SystemTime { - SystemTime(time::SystemTime::now()) - } - - /// Returns the amount of time elapsed from an earlier point in time. - /// - /// This function may fail because measurements taken earlier are not - /// guaranteed to always be before later measurements (due to anomalies such - /// as the system clock being adjusted either forwards or backwards). - /// [`Instant`] can be used to measure elapsed time without this risk of failure. - /// - /// If successful, [Ok]\([Duration]) is returned where the duration represents - /// the amount of time elapsed from the specified measurement to this one. - /// - /// Returns an [`Err`] if `earlier` is later than `self`, and the error - /// contains how far from `self` the time is. - /// - /// # Examples - /// - /// ```no_run - /// use std::time::SystemTime; - /// - /// let sys_time = SystemTime::now(); - /// let new_sys_time = SystemTime::now(); - /// let difference = new_sys_time.duration_since(sys_time) - /// .expect("Clock may have gone backwards"); - /// println!("{difference:?}"); - /// ``` - #[stable(feature = "time2", since = "1.8.0")] - pub fn duration_since(&self, earlier: SystemTime) -> Result { - self.0.sub_time(&earlier.0).map_err(SystemTimeError) - } - - /// Returns the difference from this system time to the - /// current clock time. - /// - /// This function may fail as the underlying system clock is susceptible to - /// drift and updates (e.g., the system clock could go backwards), so this - /// function might not always succeed. If successful, [Ok]\([Duration]) is - /// returned where the duration represents the amount of time elapsed from - /// this time measurement to the current time. - /// - /// To measure elapsed time reliably, use [`Instant`] instead. - /// - /// Returns an [`Err`] if `self` is later than the current system time, and - /// the error contains how far from the current system time `self` is. - /// - /// # Examples - /// - /// ```no_run - /// use std::thread::sleep; - /// use std::time::{Duration, SystemTime}; - /// - /// let sys_time = SystemTime::now(); - /// let one_sec = Duration::from_secs(1); - /// sleep(one_sec); - /// assert!(sys_time.elapsed().unwrap() >= one_sec); - /// ``` - #[stable(feature = "time2", since = "1.8.0")] - pub fn elapsed(&self) -> Result { - SystemTime::now().duration_since(*self) - } - - /// Returns `Some(t)` where `t` is the time `self + duration` if `t` can be represented as - /// `SystemTime` (which means it's inside the bounds of the underlying data structure), `None` - /// otherwise. - #[stable(feature = "time_checked_add", since = "1.34.0")] - pub fn checked_add(&self, duration: Duration) -> Option { - self.0.checked_add_duration(&duration).map(SystemTime) - } - - /// Returns `Some(t)` where `t` is the time `self - duration` if `t` can be represented as - /// `SystemTime` (which means it's inside the bounds of the underlying data structure), `None` - /// otherwise. - #[stable(feature = "time_checked_add", since = "1.34.0")] - pub fn checked_sub(&self, duration: Duration) -> Option { - self.0.checked_sub_duration(&duration).map(SystemTime) - } -} - -#[stable(feature = "time2", since = "1.8.0")] -impl Add for SystemTime { - type Output = SystemTime; - - /// # Panics - /// - /// This function may panic if the resulting point in time cannot be represented by the - /// underlying data structure. See [`SystemTime::checked_add`] for a version without panic. - fn add(self, dur: Duration) -> SystemTime { - self.checked_add(dur).expect("overflow when adding duration to instant") - } -} - -#[stable(feature = "time_augmented_assignment", since = "1.9.0")] -impl AddAssign for SystemTime { - fn add_assign(&mut self, other: Duration) { - *self = *self + other; - } -} - -#[stable(feature = "time2", since = "1.8.0")] -impl Sub for SystemTime { - type Output = SystemTime; - - fn sub(self, dur: Duration) -> SystemTime { - self.checked_sub(dur).expect("overflow when subtracting duration from instant") - } -} - -#[stable(feature = "time_augmented_assignment", since = "1.9.0")] -impl SubAssign for SystemTime { - fn sub_assign(&mut self, other: Duration) { - *self = *self - other; - } -} - -#[stable(feature = "time2", since = "1.8.0")] -impl fmt::Debug for SystemTime { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.0.fmt(f) - } -} - -/// An anchor in time which can be used to create new `SystemTime` instances or -/// learn about where in time a `SystemTime` lies. -// -// NOTE! this documentation is duplicated, here and in SystemTime::UNIX_EPOCH. -// The two copies are not quite identical, because of the difference in naming. -/// -/// This constant is defined to be "1970-01-01 00:00:00 UTC" on all systems with -/// respect to the system clock. Using `duration_since` on an existing -/// [`SystemTime`] instance can tell how far away from this point in time a -/// measurement lies, and using `UNIX_EPOCH + duration` can be used to create a -/// [`SystemTime`] instance to represent another fixed point in time. -/// -/// `duration_since(UNIX_EPOCH).unwrap().as_secs()` returns -/// the number of non-leap seconds since the start of 1970 UTC. -/// This is a POSIX `time_t` (as a `u64`), -/// and is the same time representation as used in many Internet protocols. -/// -/// # Examples -/// -/// ```no_run -/// use std::time::{SystemTime, UNIX_EPOCH}; -/// -/// match SystemTime::now().duration_since(UNIX_EPOCH) { -/// Ok(n) => println!("1970-01-01 00:00:00 UTC was {} seconds ago!", n.as_secs()), -/// Err(_) => panic!("SystemTime before UNIX EPOCH!"), -/// } -/// ``` -#[stable(feature = "time2", since = "1.8.0")] -pub const UNIX_EPOCH: SystemTime = SystemTime(time::UNIX_EPOCH); - -impl SystemTimeError { - /// Returns the positive duration which represents how far forward the - /// second system time was from the first. - /// - /// A `SystemTimeError` is returned from the [`SystemTime::duration_since`] - /// and [`SystemTime::elapsed`] methods whenever the second system time - /// represents a point later in time than the `self` of the method call. - /// - /// # Examples - /// - /// ```no_run - /// use std::thread::sleep; - /// use std::time::{Duration, SystemTime}; - /// - /// let sys_time = SystemTime::now(); - /// sleep(Duration::from_secs(1)); - /// let new_sys_time = SystemTime::now(); - /// match sys_time.duration_since(new_sys_time) { - /// Ok(_) => {} - /// Err(e) => println!("SystemTimeError difference: {:?}", e.duration()), - /// } - /// ``` - #[must_use] - #[stable(feature = "time2", since = "1.8.0")] - pub fn duration(&self) -> Duration { - self.0 - } -} - -#[stable(feature = "time2", since = "1.8.0")] -impl Error for SystemTimeError { - #[allow(deprecated)] - fn description(&self) -> &str { - "other time was not earlier than self" - } -} - -#[stable(feature = "time2", since = "1.8.0")] -impl fmt::Display for SystemTimeError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "second time provided was later than self") - } -} - -impl FromInner for SystemTime { - fn from_inner(time: time::SystemTime) -> SystemTime { - SystemTime(time) - } -} - -impl IntoInner for SystemTime { - fn into_inner(self) -> time::SystemTime { - self.0 - } -} diff --git a/library/std/src/time/tests.rs b/library/std/src/time/tests.rs deleted file mode 100644 index 6ed84806e6d37..0000000000000 --- a/library/std/src/time/tests.rs +++ /dev/null @@ -1,272 +0,0 @@ -use super::{Duration, Instant, SystemTime, UNIX_EPOCH}; -use core::fmt::Debug; -#[cfg(not(target_arch = "wasm32"))] -use test::{black_box, Bencher}; - -macro_rules! assert_almost_eq { - ($a:expr, $b:expr) => {{ - let (a, b) = ($a, $b); - if a != b { - let (a, b) = if a > b { (a, b) } else { (b, a) }; - assert!(a - Duration::from_micros(1) <= b, "{:?} is not almost equal to {:?}", a, b); - } - }}; -} - -#[test] -fn instant_monotonic() { - let a = Instant::now(); - loop { - let b = Instant::now(); - assert!(b >= a); - if b > a { - break; - } - } -} - -#[test] -#[cfg(not(target_arch = "wasm32"))] -fn instant_monotonic_concurrent() -> crate::thread::Result<()> { - let threads: Vec<_> = (0..8) - .map(|_| { - crate::thread::spawn(|| { - let mut old = Instant::now(); - let count = if cfg!(miri) { 1_000 } else { 5_000_000 }; - for _ in 0..count { - let new = Instant::now(); - assert!(new >= old); - old = new; - } - }) - }) - .collect(); - for t in threads { - t.join()?; - } - Ok(()) -} - -#[test] -fn instant_elapsed() { - let a = Instant::now(); - let _ = a.elapsed(); -} - -#[test] -fn instant_math() { - let a = Instant::now(); - let b = Instant::now(); - println!("a: {a:?}"); - println!("b: {b:?}"); - let dur = b.duration_since(a); - println!("dur: {dur:?}"); - assert_almost_eq!(b - dur, a); - assert_almost_eq!(a + dur, b); - - let second = Duration::SECOND; - assert_almost_eq!(a - second + second, a); - assert_almost_eq!(a.checked_sub(second).unwrap().checked_add(second).unwrap(), a); - - // checked_add_duration will not panic on overflow - let mut maybe_t = Some(Instant::now()); - let max_duration = Duration::from_secs(u64::MAX); - // in case `Instant` can store `>= now + max_duration`. - for _ in 0..2 { - maybe_t = maybe_t.and_then(|t| t.checked_add(max_duration)); - } - assert_eq!(maybe_t, None); - - // checked_add_duration calculates the right time and will work for another year - let year = Duration::from_secs(60 * 60 * 24 * 365); - assert_eq!(a + year, a.checked_add(year).unwrap()); -} - -#[test] -fn instant_math_is_associative() { - let now = Instant::now(); - let offset = Duration::from_millis(5); - // Changing the order of instant math shouldn't change the results, - // especially when the expression reduces to X + identity. - assert_eq!((now + offset) - now, (now - now) + offset); - - // On any platform, `Instant` should have the same resolution as `Duration` (e.g. 1 nanosecond) - // or better. Otherwise, math will be non-associative (see #91417). - let now = Instant::now(); - let provided_offset = Duration::from_nanos(1); - let later = now + provided_offset; - let measured_offset = later - now; - assert_eq!(measured_offset, provided_offset); -} - -#[test] -fn instant_duration_since_saturates() { - let a = Instant::now(); - assert_eq!((a - Duration::SECOND).duration_since(a), Duration::ZERO); -} - -#[test] -fn instant_checked_duration_since_nopanic() { - let now = Instant::now(); - let earlier = now - Duration::SECOND; - let later = now + Duration::SECOND; - assert_eq!(earlier.checked_duration_since(now), None); - assert_eq!(later.checked_duration_since(now), Some(Duration::SECOND)); - assert_eq!(now.checked_duration_since(now), Some(Duration::ZERO)); -} - -#[test] -fn instant_saturating_duration_since_nopanic() { - let a = Instant::now(); - #[allow(deprecated, deprecated_in_future)] - let ret = (a - Duration::SECOND).saturating_duration_since(a); - assert_eq!(ret, Duration::ZERO); -} - -#[test] -fn system_time_math() { - let a = SystemTime::now(); - let b = SystemTime::now(); - match b.duration_since(a) { - Ok(Duration::ZERO) => { - assert_almost_eq!(a, b); - } - Ok(dur) => { - assert!(b > a); - assert_almost_eq!(b - dur, a); - assert_almost_eq!(a + dur, b); - } - Err(dur) => { - let dur = dur.duration(); - assert!(a > b); - assert_almost_eq!(b + dur, a); - assert_almost_eq!(a - dur, b); - } - } - - let second = Duration::SECOND; - assert_almost_eq!(a.duration_since(a - second).unwrap(), second); - assert_almost_eq!(a.duration_since(a + second).unwrap_err().duration(), second); - - assert_almost_eq!(a - second + second, a); - assert_almost_eq!(a.checked_sub(second).unwrap().checked_add(second).unwrap(), a); - - let one_second_from_epoch = UNIX_EPOCH + Duration::SECOND; - let one_second_from_epoch2 = - UNIX_EPOCH + Duration::from_millis(500) + Duration::from_millis(500); - assert_eq!(one_second_from_epoch, one_second_from_epoch2); - - // checked_add_duration will not panic on overflow - let mut maybe_t = Some(SystemTime::UNIX_EPOCH); - let max_duration = Duration::from_secs(u64::MAX); - // in case `SystemTime` can store `>= UNIX_EPOCH + max_duration`. - for _ in 0..2 { - maybe_t = maybe_t.and_then(|t| t.checked_add(max_duration)); - } - assert_eq!(maybe_t, None); - - // checked_add_duration calculates the right time and will work for another year - let year = Duration::from_secs(60 * 60 * 24 * 365); - assert_eq!(a + year, a.checked_add(year).unwrap()); -} - -#[test] -fn system_time_elapsed() { - let a = SystemTime::now(); - drop(a.elapsed()); -} - -#[test] -fn since_epoch() { - let ts = SystemTime::now(); - let a = ts.duration_since(UNIX_EPOCH + Duration::SECOND).unwrap(); - let b = ts.duration_since(UNIX_EPOCH).unwrap(); - assert!(b > a); - assert_eq!(b - a, Duration::SECOND); - - let thirty_years = Duration::SECOND * 60 * 60 * 24 * 365 * 30; - - // Right now for CI this test is run in an emulator, and apparently the - // aarch64 emulator's sense of time is that we're still living in the - // 70s. This is also true for riscv (also qemu) - // - // Otherwise let's assume that we're all running computers later than - // 2000. - if !cfg!(target_arch = "aarch64") && !cfg!(target_arch = "riscv64") { - assert!(a > thirty_years); - } - - // let's assume that we're all running computers earlier than 2090. - // Should give us ~70 years to fix this! - let hundred_twenty_years = thirty_years * 4; - assert!(a < hundred_twenty_years); -} - -#[test] -fn big_math() { - // Check that the same result occurs when adding/subtracting each duration one at a time as when - // adding/subtracting them all at once. - #[track_caller] - fn check(start: Option, op: impl Fn(&T, Duration) -> Option) { - const DURATIONS: [Duration; 2] = - [Duration::from_secs(i64::MAX as _), Duration::from_secs(50)]; - if let Some(start) = start { - assert_eq!( - op(&start, DURATIONS.into_iter().sum()), - DURATIONS.into_iter().try_fold(start, |t, d| op(&t, d)) - ) - } - } - - check(SystemTime::UNIX_EPOCH.checked_sub(Duration::from_secs(100)), SystemTime::checked_add); - check(SystemTime::UNIX_EPOCH.checked_add(Duration::from_secs(100)), SystemTime::checked_sub); - - let instant = Instant::now(); - check(instant.checked_sub(Duration::from_secs(100)), Instant::checked_add); - check(instant.checked_sub(Duration::from_secs(i64::MAX as _)), Instant::checked_add); - check(instant.checked_add(Duration::from_secs(100)), Instant::checked_sub); - check(instant.checked_add(Duration::from_secs(i64::MAX as _)), Instant::checked_sub); -} - -macro_rules! bench_instant_threaded { - ($bench_name:ident, $thread_count:expr) => { - #[bench] - #[cfg(not(target_arch = "wasm32"))] - fn $bench_name(b: &mut Bencher) -> crate::thread::Result<()> { - use crate::sync::atomic::{AtomicBool, Ordering}; - use crate::sync::Arc; - - let running = Arc::new(AtomicBool::new(true)); - - let threads: Vec<_> = (0..$thread_count) - .map(|_| { - let flag = Arc::clone(&running); - crate::thread::spawn(move || { - while flag.load(Ordering::Relaxed) { - black_box(Instant::now()); - } - }) - }) - .collect(); - - b.iter(|| { - let a = Instant::now(); - let b = Instant::now(); - assert!(b >= a); - }); - - running.store(false, Ordering::Relaxed); - - for t in threads { - t.join()?; - } - Ok(()) - } - }; -} - -bench_instant_threaded!(instant_contention_01_threads, 0); -bench_instant_threaded!(instant_contention_02_threads, 1); -bench_instant_threaded!(instant_contention_04_threads, 3); -bench_instant_threaded!(instant_contention_08_threads, 7); -bench_instant_threaded!(instant_contention_16_threads, 15); diff --git a/library/std/tests/builtin-clone.rs b/library/std/tests/builtin-clone.rs deleted file mode 100644 index 66b57130c954b..0000000000000 --- a/library/std/tests/builtin-clone.rs +++ /dev/null @@ -1,33 +0,0 @@ -// Test that `Clone` is correctly implemented for builtin types. -// Also test that cloning an array or a tuple is done right, i.e. -// each component is cloned. - -fn test_clone(arg: T) { - let _ = arg.clone(); -} - -fn foo() {} - -#[derive(Debug, PartialEq, Eq)] -struct S(i32); - -impl Clone for S { - fn clone(&self) -> Self { - S(self.0 + 1) - } -} - -#[test] -fn builtin_clone() { - test_clone(foo); - test_clone([1; 56]); - test_clone((1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1)); - - let a = [S(0), S(1), S(2)]; - let b = [S(1), S(2), S(3)]; - assert_eq!(b, a.clone()); - - let a = ((S(1), S(0)), ((S(0), S(0), S(1)), S(0))); - let b = ((S(2), S(1)), ((S(1), S(1), S(2)), S(1))); - assert_eq!(b, a.clone()); -} diff --git a/library/std/tests/common/mod.rs b/library/std/tests/common/mod.rs deleted file mode 100644 index 1aad6549e76c3..0000000000000 --- a/library/std/tests/common/mod.rs +++ /dev/null @@ -1,58 +0,0 @@ -#![allow(unused)] - -use rand::RngCore; -use std::env; -use std::fs; -use std::path::{Path, PathBuf}; -use std::thread; - -/// Copied from `std::test_helpers::test_rng`, since these tests rely on the -/// seed not being the same for every RNG invocation too. -#[track_caller] -pub(crate) fn test_rng() -> rand_xorshift::XorShiftRng { - use core::hash::{BuildHasher, Hash, Hasher}; - let mut hasher = std::hash::RandomState::new().build_hasher(); - core::panic::Location::caller().hash(&mut hasher); - let hc64 = hasher.finish(); - let seed_vec = hc64.to_le_bytes().into_iter().chain(0u8..8).collect::>(); - let seed: [u8; 16] = seed_vec.as_slice().try_into().unwrap(); - rand::SeedableRng::from_seed(seed) -} - -// Copied from std::sys_common::io -pub(crate) struct TempDir(PathBuf); - -impl TempDir { - pub(crate) fn join(&self, path: &str) -> PathBuf { - let TempDir(ref p) = *self; - p.join(path) - } - - pub(crate) fn path(&self) -> &Path { - let TempDir(ref p) = *self; - p - } -} - -impl Drop for TempDir { - fn drop(&mut self) { - // Gee, seeing how we're testing the fs module I sure hope that we - // at least implement this correctly! - let TempDir(ref p) = *self; - let result = fs::remove_dir_all(p); - // Avoid panicking while panicking as this causes the process to - // immediately abort, without displaying test results. - if !thread::panicking() { - result.unwrap(); - } - } -} - -#[track_caller] // for `test_rng` -pub(crate) fn tmpdir() -> TempDir { - let p = env::temp_dir(); - let mut r = test_rng(); - let ret = p.join(&format!("rust-{}", r.next_u32())); - fs::create_dir(&ret).unwrap(); - TempDir(ret) -} diff --git a/library/std/tests/create_dir_all_bare.rs b/library/std/tests/create_dir_all_bare.rs deleted file mode 100644 index fd2a7f906f839..0000000000000 --- a/library/std/tests/create_dir_all_bare.rs +++ /dev/null @@ -1,40 +0,0 @@ -#![cfg(all(test, not(any(target_os = "emscripten", target_env = "sgx"))))] - -//! Note that this test changes the current directory so -//! should not be in the same process as other tests. -use std::env; -use std::fs; -use std::path::{Path, PathBuf}; - -mod common; - -// On some platforms, setting the current directory will prevent deleting it. -// So this helper ensures the current directory is reset. -struct CurrentDir(PathBuf); -impl CurrentDir { - fn new() -> Self { - Self(env::current_dir().unwrap()) - } - fn set(&self, path: &Path) { - env::set_current_dir(path).unwrap(); - } - fn with(path: &Path, f: impl FnOnce()) { - let current_dir = Self::new(); - current_dir.set(path); - f(); - } -} -impl Drop for CurrentDir { - fn drop(&mut self) { - env::set_current_dir(&self.0).unwrap(); - } -} - -#[test] -#[cfg_attr(all(miri, windows), ignore)] // File system access on Windows not supported by Miri -fn create_dir_all_bare() { - let tmpdir = common::tmpdir(); - CurrentDir::with(tmpdir.path(), || { - fs::create_dir_all("create-dir-all-bare").unwrap(); - }); -} diff --git a/library/std/tests/env.rs b/library/std/tests/env.rs deleted file mode 100644 index a1ca85c2145f5..0000000000000 --- a/library/std/tests/env.rs +++ /dev/null @@ -1,162 +0,0 @@ -use std::env::*; -use std::ffi::{OsStr, OsString}; - -use rand::distributions::{Alphanumeric, DistString}; - -mod common; -use common::test_rng; -use std::thread; - -#[track_caller] -fn make_rand_name() -> OsString { - let n = format!("TEST{}", Alphanumeric.sample_string(&mut test_rng(), 10)); - let n = OsString::from(n); - assert!(var_os(&n).is_none()); - n -} - -fn eq(a: Option, b: Option<&str>) { - assert_eq!(a.as_ref().map(|s| &**s), b.map(OsStr::new).map(|s| &*s)); -} - -#[test] -fn test_set_var() { - let n = make_rand_name(); - set_var(&n, "VALUE"); - eq(var_os(&n), Some("VALUE")); -} - -#[test] -fn test_remove_var() { - let n = make_rand_name(); - set_var(&n, "VALUE"); - remove_var(&n); - eq(var_os(&n), None); -} - -#[test] -fn test_set_var_overwrite() { - let n = make_rand_name(); - set_var(&n, "1"); - set_var(&n, "2"); - eq(var_os(&n), Some("2")); - set_var(&n, ""); - eq(var_os(&n), Some("")); -} - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn test_var_big() { - let mut s = "".to_string(); - let mut i = 0; - while i < 100 { - s.push_str("aaaaaaaaaa"); - i += 1; - } - let n = make_rand_name(); - set_var(&n, &s); - eq(var_os(&n), Some(&s)); -} - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn test_env_set_get_huge() { - let n = make_rand_name(); - let s = "x".repeat(10000); - set_var(&n, &s); - eq(var_os(&n), Some(&s)); - remove_var(&n); - eq(var_os(&n), None); -} - -#[test] -fn test_env_set_var() { - let n = make_rand_name(); - - let mut e = vars_os(); - set_var(&n, "VALUE"); - assert!(!e.any(|(k, v)| { &*k == &*n && &*v == "VALUE" })); - - assert!(vars_os().any(|(k, v)| { &*k == &*n && &*v == "VALUE" })); -} - -#[test] -#[cfg_attr(not(any(unix, windows)), ignore, allow(unused))] -#[allow(deprecated)] -fn env_home_dir() { - use std::path::PathBuf; - - fn var_to_os_string(var: Result) -> Option { - match var { - Ok(var) => Some(OsString::from(var)), - Err(VarError::NotUnicode(var)) => Some(var), - _ => None, - } - } - - cfg_if::cfg_if! { - if #[cfg(unix)] { - let oldhome = var_to_os_string(var("HOME")); - - set_var("HOME", "/home/MountainView"); - assert_eq!(home_dir(), Some(PathBuf::from("/home/MountainView"))); - - remove_var("HOME"); - if cfg!(target_os = "android") { - assert!(home_dir().is_none()); - } else { - // When HOME is not set, some platforms return `None`, - // but others return `Some` with a default. - // Just check that it is not "/home/MountainView". - assert_ne!(home_dir(), Some(PathBuf::from("/home/MountainView"))); - } - - if let Some(oldhome) = oldhome { set_var("HOME", oldhome); } - } else if #[cfg(windows)] { - let oldhome = var_to_os_string(var("HOME")); - let olduserprofile = var_to_os_string(var("USERPROFILE")); - - remove_var("HOME"); - remove_var("USERPROFILE"); - - assert!(home_dir().is_some()); - - set_var("HOME", "/home/MountainView"); - assert_eq!(home_dir(), Some(PathBuf::from("/home/MountainView"))); - - remove_var("HOME"); - - set_var("USERPROFILE", "/home/MountainView"); - assert_eq!(home_dir(), Some(PathBuf::from("/home/MountainView"))); - - set_var("HOME", "/home/MountainView"); - set_var("USERPROFILE", "/home/PaloAlto"); - assert_eq!(home_dir(), Some(PathBuf::from("/home/MountainView"))); - - remove_var("HOME"); - remove_var("USERPROFILE"); - - if let Some(oldhome) = oldhome { set_var("HOME", oldhome); } - if let Some(olduserprofile) = olduserprofile { set_var("USERPROFILE", olduserprofile); } - } - } -} - -#[test] // miri shouldn't detect any data race in this fn -#[cfg_attr(any(not(miri), target_os = "emscripten"), ignore)] -fn test_env_get_set_multithreaded() { - let getter = thread::spawn(|| { - for _ in 0..100 { - let _ = var_os("foo"); - } - }); - - let setter = thread::spawn(|| { - for _ in 0..100 { - set_var("foo", "bar"); - } - }); - - let _ = getter.join(); - let _ = setter.join(); -} diff --git a/library/std/tests/eq-multidispatch.rs b/library/std/tests/eq-multidispatch.rs deleted file mode 100644 index 96e440f85e0ac..0000000000000 --- a/library/std/tests/eq-multidispatch.rs +++ /dev/null @@ -1,51 +0,0 @@ -#[derive(PartialEq, Debug)] -struct Bar; -#[derive(Debug)] -struct Baz; -#[derive(Debug)] -struct Foo; -#[derive(Debug)] -struct Fu; - -impl PartialEq for Baz { - fn eq(&self, _: &Baz) -> bool { - true - } -} - -impl PartialEq for Foo { - fn eq(&self, _: &Fu) -> bool { - true - } -} - -impl PartialEq for Fu { - fn eq(&self, _: &Foo) -> bool { - true - } -} - -impl PartialEq for Foo { - fn eq(&self, _: &Bar) -> bool { - false - } -} - -impl PartialEq for Bar { - fn eq(&self, _: &Foo) -> bool { - false - } -} - -#[test] -fn eq_multidispatch() { - assert!(Bar != Foo); - assert!(Foo != Bar); - - assert_eq!(Bar, Bar); - - assert_eq!(Baz, Baz); - - assert_eq!(Foo, Fu); - assert_eq!(Fu, Foo); -} diff --git a/library/std/tests/istr.rs b/library/std/tests/istr.rs deleted file mode 100644 index 9a127ae803e77..0000000000000 --- a/library/std/tests/istr.rs +++ /dev/null @@ -1,48 +0,0 @@ -#[test] -fn test_stack_assign() { - let s: String = "a".to_string(); - println!("{}", s.clone()); - let t: String = "a".to_string(); - assert_eq!(s, t); - let u: String = "b".to_string(); - assert!((s != u)); -} - -#[test] -fn test_heap_lit() { - "a big string".to_string(); -} - -#[test] -fn test_heap_assign() { - let s: String = "a big ol' string".to_string(); - let t: String = "a big ol' string".to_string(); - assert_eq!(s, t); - let u: String = "a bad ol' string".to_string(); - assert!((s != u)); -} - -#[test] -fn test_heap_log() { - let s = "a big ol' string".to_string(); - println!("{}", s); -} - -#[test] -fn test_append() { - let mut s = String::new(); - s.push_str("a"); - assert_eq!(s, "a"); - - let mut s = String::from("a"); - s.push_str("b"); - println!("{}", s.clone()); - assert_eq!(s, "ab"); - - let mut s = String::from("c"); - s.push_str("offee"); - assert_eq!(s, "coffee"); - - s.push_str("&tea"); - assert_eq!(s, "coffee&tea"); -} diff --git a/library/std/tests/log-knows-the-names-of-variants-in-std.rs b/library/std/tests/log-knows-the-names-of-variants-in-std.rs deleted file mode 100644 index 118bee620185c..0000000000000 --- a/library/std/tests/log-knows-the-names-of-variants-in-std.rs +++ /dev/null @@ -1,27 +0,0 @@ -#![allow(non_camel_case_types)] -#![allow(dead_code)] - -#[derive(Clone, Debug)] -enum foo { - a(usize), - b(String), -} - -fn check_log(exp: String, v: T) { - assert_eq!(exp, format!("{:?}", v)); -} - -#[test] -fn log_knows_the_names_of_variants_in_std() { - let mut x = Some(foo::a(22)); - let exp = "Some(a(22))".to_string(); - let act = format!("{:?}", x); - assert_eq!(act, exp); - check_log(exp, x); - - x = None; - let exp = "None".to_string(); - let act = format!("{:?}", x); - assert_eq!(act, exp); - check_log(exp, x); -} diff --git a/library/std/tests/minmax-stability-issue-23687.rs b/library/std/tests/minmax-stability-issue-23687.rs deleted file mode 100644 index 119c520de8f05..0000000000000 --- a/library/std/tests/minmax-stability-issue-23687.rs +++ /dev/null @@ -1,63 +0,0 @@ -use std::cmp::{self, Ordering}; -use std::fmt::Debug; - -#[derive(Debug, Copy, Clone, PartialEq, Eq)] -struct Foo { - n: u8, - name: &'static str, -} - -impl PartialOrd for Foo { - fn partial_cmp(&self, other: &Foo) -> Option { - Some(self.cmp(other)) - } -} - -impl Ord for Foo { - fn cmp(&self, other: &Foo) -> Ordering { - self.n.cmp(&other.n) - } -} - -#[test] -fn minmax_stability() { - let a = Foo { n: 4, name: "a" }; - let b = Foo { n: 4, name: "b" }; - let c = Foo { n: 8, name: "c" }; - let d = Foo { n: 8, name: "d" }; - let e = Foo { n: 22, name: "e" }; - let f = Foo { n: 22, name: "f" }; - - let data = [a, b, c, d, e, f]; - - // `min` should return the left when the values are equal - assert_eq!(data.iter().min(), Some(&a)); - assert_eq!(data.iter().min_by_key(|a| a.n), Some(&a)); - assert_eq!(cmp::min(a, b), a); - assert_eq!(cmp::min(b, a), b); - - // `max` should return the right when the values are equal - assert_eq!(data.iter().max(), Some(&f)); - assert_eq!(data.iter().max_by_key(|a| a.n), Some(&f)); - assert_eq!(cmp::max(e, f), f); - assert_eq!(cmp::max(f, e), e); - - let mut presorted = data.to_vec(); - presorted.sort(); - assert_stable(&presorted); - - let mut presorted = data.to_vec(); - presorted.sort_by(|a, b| a.cmp(b)); - assert_stable(&presorted); - - // Assert that sorted and min/max are the same - fn assert_stable(presorted: &[T]) { - for slice in presorted.windows(2) { - let a = &slice[0]; - let b = &slice[1]; - - assert_eq!(a, cmp::min(a, b)); - assert_eq!(b, cmp::max(a, b)); - } - } -} diff --git a/library/std/tests/process_spawning.rs b/library/std/tests/process_spawning.rs deleted file mode 100644 index c56c111c37ded..0000000000000 --- a/library/std/tests/process_spawning.rs +++ /dev/null @@ -1,39 +0,0 @@ -#![cfg(not(target_env = "sgx"))] - -use std::env; -use std::fs; -use std::process; -use std::str; - -mod common; - -#[test] -#[cfg_attr(miri, ignore)] // Process spawning not supported by Miri -fn issue_15149() { - // If we're the parent, copy our own binary to a new directory. - let my_path = env::current_exe().unwrap(); - - let temp = common::tmpdir(); - let child_dir = temp.join("issue-15140-child"); - fs::create_dir_all(&child_dir).unwrap(); - - let child_path = child_dir.join(&format!("mytest{}", env::consts::EXE_SUFFIX)); - fs::copy(&my_path, &child_path).unwrap(); - - // Append the new directory to our own PATH. - let path = { - let mut paths: Vec<_> = env::split_paths(&env::var_os("PATH").unwrap()).collect(); - paths.push(child_dir.to_path_buf()); - env::join_paths(paths).unwrap() - }; - - let child_output = - process::Command::new("mytest").env("PATH", &path).arg("child").output().unwrap(); - - assert!( - child_output.status.success(), - "child assertion failed\n child stdout:\n {}\n child stderr:\n {}", - str::from_utf8(&child_output.stdout).unwrap(), - str::from_utf8(&child_output.stderr).unwrap() - ); -} diff --git a/library/std/tests/run-time-detect.rs b/library/std/tests/run-time-detect.rs deleted file mode 100644 index c9b9c54e3d49c..0000000000000 --- a/library/std/tests/run-time-detect.rs +++ /dev/null @@ -1,165 +0,0 @@ -//! These tests just check that the macros are available in std. - -#![cfg_attr( - all(target_arch = "arm", any(target_os = "linux", target_os = "android")), - feature(stdarch_arm_feature_detection) -)] -#![cfg_attr( - all(target_arch = "powerpc", target_os = "linux"), - feature(stdarch_powerpc_feature_detection) -)] -#![cfg_attr( - all(target_arch = "powerpc64", target_os = "linux"), - feature(stdarch_powerpc_feature_detection) -)] - -#[test] -#[cfg(all(target_arch = "arm", any(target_os = "linux", target_os = "android")))] -fn arm_linux() { - use std::arch::is_arm_feature_detected; - // tidy-alphabetical-start - println!("aes: {}", is_arm_feature_detected!("aes")); - println!("crc: {}", is_arm_feature_detected!("crc")); - println!("neon: {}", is_arm_feature_detected!("neon")); - println!("pmull: {}", is_arm_feature_detected!("pmull")); - println!("sha2: {}", is_arm_feature_detected!("sha2")); - // tidy-alphabetical-end -} - -#[test] -#[cfg(all(target_arch = "aarch64", any(target_os = "linux", target_os = "android")))] -fn aarch64_linux() { - use std::arch::is_aarch64_feature_detected; - // tidy-alphabetical-start - println!("aes: {}", is_aarch64_feature_detected!("aes")); - println!("asimd: {}", is_aarch64_feature_detected!("asimd")); - println!("bf16: {}", is_aarch64_feature_detected!("bf16")); - println!("bti: {}", is_aarch64_feature_detected!("bti")); - println!("crc: {}", is_aarch64_feature_detected!("crc")); - println!("dit: {}", is_aarch64_feature_detected!("dit")); - println!("dotprod: {}", is_aarch64_feature_detected!("dotprod")); - println!("dpb2: {}", is_aarch64_feature_detected!("dpb2")); - println!("dpb: {}", is_aarch64_feature_detected!("dpb")); - println!("f32mm: {}", is_aarch64_feature_detected!("f32mm")); - println!("f64mm: {}", is_aarch64_feature_detected!("f64mm")); - println!("fcma: {}", is_aarch64_feature_detected!("fcma")); - println!("fhm: {}", is_aarch64_feature_detected!("fhm")); - println!("flagm: {}", is_aarch64_feature_detected!("flagm")); - println!("fp16: {}", is_aarch64_feature_detected!("fp16")); - println!("frintts: {}", is_aarch64_feature_detected!("frintts")); - println!("i8mm: {}", is_aarch64_feature_detected!("i8mm")); - println!("jsconv: {}", is_aarch64_feature_detected!("jsconv")); - println!("lse2: {}", is_aarch64_feature_detected!("lse2")); - println!("lse: {}", is_aarch64_feature_detected!("lse")); - println!("mte: {}", is_aarch64_feature_detected!("mte")); - println!("neon: {}", is_aarch64_feature_detected!("neon")); - println!("paca: {}", is_aarch64_feature_detected!("paca")); - println!("pacg: {}", is_aarch64_feature_detected!("pacg")); - println!("pmull: {}", is_aarch64_feature_detected!("pmull")); - println!("rand: {}", is_aarch64_feature_detected!("rand")); - println!("rcpc2: {}", is_aarch64_feature_detected!("rcpc2")); - println!("rcpc: {}", is_aarch64_feature_detected!("rcpc")); - println!("rdm: {}", is_aarch64_feature_detected!("rdm")); - println!("sb: {}", is_aarch64_feature_detected!("sb")); - println!("sha2: {}", is_aarch64_feature_detected!("sha2")); - println!("sha3: {}", is_aarch64_feature_detected!("sha3")); - println!("sm4: {}", is_aarch64_feature_detected!("sm4")); - println!("ssbs: {}", is_aarch64_feature_detected!("ssbs")); - println!("sve2-aes: {}", is_aarch64_feature_detected!("sve2-aes")); - println!("sve2-bitperm: {}", is_aarch64_feature_detected!("sve2-bitperm")); - println!("sve2-sha3: {}", is_aarch64_feature_detected!("sve2-sha3")); - println!("sve2-sm4: {}", is_aarch64_feature_detected!("sve2-sm4")); - println!("sve2: {}", is_aarch64_feature_detected!("sve2")); - println!("sve: {}", is_aarch64_feature_detected!("sve")); - println!("tme: {}", is_aarch64_feature_detected!("tme")); - // tidy-alphabetical-end -} - -#[test] -#[cfg(all(target_arch = "powerpc", target_os = "linux"))] -fn powerpc_linux() { - use std::arch::is_powerpc_feature_detected; - // tidy-alphabetical-start - println!("altivec: {}", is_powerpc_feature_detected!("altivec")); - println!("power8: {}", is_powerpc_feature_detected!("power8")); - println!("vsx: {}", is_powerpc_feature_detected!("vsx")); - // tidy-alphabetical-end -} - -#[test] -#[cfg(all(target_arch = "powerpc64", target_os = "linux"))] -fn powerpc64_linux() { - use std::arch::is_powerpc64_feature_detected; - // tidy-alphabetical-start - println!("altivec: {}", is_powerpc64_feature_detected!("altivec")); - println!("power8: {}", is_powerpc64_feature_detected!("power8")); - println!("vsx: {}", is_powerpc64_feature_detected!("vsx")); - // tidy-alphabetical-end -} - -#[test] -#[cfg(any(target_arch = "x86", target_arch = "x86_64"))] -fn x86_all() { - use std::arch::is_x86_feature_detected; - - // the below is the set of features we can test at runtime, but don't actually - // use to gate anything and are thus not part of the X86_ALLOWED_FEATURES list - - println!("abm: {:?}", is_x86_feature_detected!("abm")); // this is a synonym for lzcnt but we test it anyways - println!("mmx: {:?}", is_x86_feature_detected!("mmx")); - println!("tsc: {:?}", is_x86_feature_detected!("tsc")); - - // the below is in alphabetical order and matches - // the order of X86_ALLOWED_FEATURES in rustc_codegen_ssa's target_features.rs - - // tidy-alphabetical-start - println!("adx: {:?}", is_x86_feature_detected!("adx")); - println!("aes: {:?}", is_x86_feature_detected!("aes")); - println!("avx2: {:?}", is_x86_feature_detected!("avx2")); - println!("avx512bf16: {:?}", is_x86_feature_detected!("avx512bf16")); - println!("avx512bitalg: {:?}", is_x86_feature_detected!("avx512bitalg")); - println!("avx512bw: {:?}", is_x86_feature_detected!("avx512bw")); - println!("avx512cd: {:?}", is_x86_feature_detected!("avx512cd")); - println!("avx512dq: {:?}", is_x86_feature_detected!("avx512dq")); - println!("avx512er: {:?}", is_x86_feature_detected!("avx512er")); - println!("avx512f: {:?}", is_x86_feature_detected!("avx512f")); - println!("avx512ifma: {:?}", is_x86_feature_detected!("avx512ifma")); - println!("avx512pf: {:?}", is_x86_feature_detected!("avx512pf")); - println!("avx512vbmi2: {:?}", is_x86_feature_detected!("avx512vbmi2")); - println!("avx512vbmi: {:?}", is_x86_feature_detected!("avx512vbmi")); - println!("avx512vl: {:?}", is_x86_feature_detected!("avx512vl")); - println!("avx512vnni: {:?}", is_x86_feature_detected!("avx512vnni")); - println!("avx512vp2intersect: {:?}", is_x86_feature_detected!("avx512vp2intersect")); - println!("avx512vpopcntdq: {:?}", is_x86_feature_detected!("avx512vpopcntdq")); - println!("avx: {:?}", is_x86_feature_detected!("avx")); - println!("bmi1: {:?}", is_x86_feature_detected!("bmi1")); - println!("bmi2: {:?}", is_x86_feature_detected!("bmi2")); - println!("cmpxchg16b: {:?}", is_x86_feature_detected!("cmpxchg16b")); - println!("f16c: {:?}", is_x86_feature_detected!("f16c")); - println!("fma: {:?}", is_x86_feature_detected!("fma")); - println!("fxsr: {:?}", is_x86_feature_detected!("fxsr")); - println!("gfni: {:?}", is_x86_feature_detected!("gfni")); - println!("lzcnt: {:?}", is_x86_feature_detected!("lzcnt")); - //println!("movbe: {:?}", is_x86_feature_detected!("movbe")); // movbe is unsupported as a target feature - println!("pclmulqdq: {:?}", is_x86_feature_detected!("pclmulqdq")); - println!("popcnt: {:?}", is_x86_feature_detected!("popcnt")); - println!("rdrand: {:?}", is_x86_feature_detected!("rdrand")); - println!("rdseed: {:?}", is_x86_feature_detected!("rdseed")); - println!("rtm: {:?}", is_x86_feature_detected!("rtm")); - println!("sha: {:?}", is_x86_feature_detected!("sha")); - println!("sse2: {:?}", is_x86_feature_detected!("sse2")); - println!("sse3: {:?}", is_x86_feature_detected!("sse3")); - println!("sse4.1: {:?}", is_x86_feature_detected!("sse4.1")); - println!("sse4.2: {:?}", is_x86_feature_detected!("sse4.2")); - println!("sse4a: {:?}", is_x86_feature_detected!("sse4a")); - println!("sse: {:?}", is_x86_feature_detected!("sse")); - println!("ssse3: {:?}", is_x86_feature_detected!("ssse3")); - println!("tbm: {:?}", is_x86_feature_detected!("tbm")); - println!("vaes: {:?}", is_x86_feature_detected!("vaes")); - println!("vpclmulqdq: {:?}", is_x86_feature_detected!("vpclmulqdq")); - println!("xsave: {:?}", is_x86_feature_detected!("xsave")); - println!("xsavec: {:?}", is_x86_feature_detected!("xsavec")); - println!("xsaveopt: {:?}", is_x86_feature_detected!("xsaveopt")); - println!("xsaves: {:?}", is_x86_feature_detected!("xsaves")); - // tidy-alphabetical-end -} diff --git a/library/std/tests/seq-compare.rs b/library/std/tests/seq-compare.rs deleted file mode 100644 index 221f1c7cabde5..0000000000000 --- a/library/std/tests/seq-compare.rs +++ /dev/null @@ -1,15 +0,0 @@ -#[test] -fn seq_compare() { - assert!(("hello".to_string() < "hellr".to_string())); - assert!(("hello ".to_string() > "hello".to_string())); - assert!(("hello".to_string() != "there".to_string())); - assert!((vec![1, 2, 3, 4] > vec![1, 2, 3])); - assert!((vec![1, 2, 3] < vec![1, 2, 3, 4])); - assert!((vec![1, 2, 4, 4] > vec![1, 2, 3, 4])); - assert!((vec![1, 2, 3, 4] < vec![1, 2, 4, 4])); - assert!((vec![1, 2, 3] <= vec![1, 2, 3])); - assert!((vec![1, 2, 3] <= vec![1, 2, 3, 3])); - assert!((vec![1, 2, 3, 4] > vec![1, 2, 3])); - assert_eq!(vec![1, 2, 3], vec![1, 2, 3]); - assert!((vec![1, 2, 3] != vec![1, 1, 3])); -} diff --git a/library/std/tests/slice-from-array-issue-113238.rs b/library/std/tests/slice-from-array-issue-113238.rs deleted file mode 100644 index 97aba4fec01e0..0000000000000 --- a/library/std/tests/slice-from-array-issue-113238.rs +++ /dev/null @@ -1,8 +0,0 @@ -// This intends to use the unsizing coercion from array to slice, but it only -// works if we resolve `<&[u8]>::from` as the reflexive `From for T`. In -// #113238, we found that gimli had added its own `From for &[u8]` -// that affected all `std/backtrace` users. -#[test] -fn slice_from_array() { - let _ = <&[u8]>::from(&[]); -} diff --git a/library/std/tests/switch-stdout.rs b/library/std/tests/switch-stdout.rs deleted file mode 100644 index 0afe18088fa5f..0000000000000 --- a/library/std/tests/switch-stdout.rs +++ /dev/null @@ -1,72 +0,0 @@ -#![cfg(any(target_family = "unix", target_family = "windows"))] - -use std::fs::File; -use std::io::{Read, Write}; - -mod common; - -#[cfg(windows)] -use std::os::windows::io::OwnedHandle; - -#[cfg(unix)] -use std::os::fd::OwnedFd; - -#[cfg(unix)] -fn switch_stdout_to(file: OwnedFd) -> OwnedFd { - use std::os::unix::prelude::*; - - extern "C" { - fn dup(old: i32) -> i32; - fn dup2(old: i32, new: i32) -> i32; - } - - unsafe { - let orig_fd = dup(1); - assert_ne!(orig_fd, -1); - let res = OwnedFd::from_raw_fd(orig_fd); - assert_eq!(dup2(file.as_raw_fd(), 1), 1); - res - } -} - -#[cfg(windows)] -fn switch_stdout_to(file: OwnedHandle) -> OwnedHandle { - use std::os::windows::prelude::*; - - extern "system" { - fn GetStdHandle(nStdHandle: u32) -> *mut u8; - fn SetStdHandle(nStdHandle: u32, handle: *mut u8) -> i32; - } - - const STD_OUTPUT_HANDLE: u32 = (-11i32) as u32; - const INVALID_HANDLE_VALUE: *mut u8 = !0 as *mut u8; - - unsafe { - let orig_hdl = GetStdHandle(STD_OUTPUT_HANDLE); - assert!(!orig_hdl.is_null() && orig_hdl != INVALID_HANDLE_VALUE); - let rc = SetStdHandle(STD_OUTPUT_HANDLE, file.into_raw_handle() as *mut _); - assert!(rc != 0); - OwnedHandle::from_raw_handle(orig_hdl as _) - } -} - -#[test] -#[cfg_attr(miri, ignore)] // dup/SetStdHandle not supported by Miri -fn switch_stdout() { - let temp = common::tmpdir(); - let path = temp.join("switch-stdout-output"); - let f = File::create(&path).unwrap(); - - let mut stdout = std::io::stdout(); - stdout.write(b"foo\n").unwrap(); - stdout.flush().unwrap(); - let orig_hdl = switch_stdout_to(f.into()); - stdout.write(b"bar\n").unwrap(); - stdout.flush().unwrap(); - - switch_stdout_to(orig_hdl); - - let mut contents = String::new(); - File::open(&path).unwrap().read_to_string(&mut contents).unwrap(); - assert_eq!(contents, "bar\n"); -} diff --git a/library/std/tests/thread.rs b/library/std/tests/thread.rs deleted file mode 100644 index 79a981d0b0d18..0000000000000 --- a/library/std/tests/thread.rs +++ /dev/null @@ -1,39 +0,0 @@ -use std::cell::{Cell, RefCell}; -use std::sync::{Arc, Mutex}; -use std::thread; -use std::time::Duration; - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -#[cfg_attr(miri, ignore)] // Miri does not like the thread leak -fn sleep_very_long() { - let finished = Arc::new(Mutex::new(false)); - let t_finished = finished.clone(); - thread::spawn(move || { - thread::sleep(Duration::new(u64::MAX, 0)); - *t_finished.lock().unwrap() = true; - }); - thread::sleep(Duration::from_millis(100)); - assert_eq!(*finished.lock().unwrap(), false); -} - -#[test] -fn thread_local_containing_const_statements() { - // This exercises the `const $init:block` cases of the thread_local macro. - // Despite overlapping with expression syntax, the `const { ... }` is not - // parsed as `$init:expr`. - thread_local! { - static CELL: Cell = const { - let value = 1; - Cell::new(value) - }; - - static REFCELL: RefCell = const { - let value = 1; - RefCell::new(value) - }; - } - - assert_eq!(CELL.get(), 1); - assert_eq!(REFCELL.take(), 1); -} diff --git a/library/std/tests/type-name-unsized.rs b/library/std/tests/type-name-unsized.rs deleted file mode 100644 index 2974668b2ce71..0000000000000 --- a/library/std/tests/type-name-unsized.rs +++ /dev/null @@ -1,70 +0,0 @@ -#![allow(dead_code)] - -use std::fmt::Debug; - -struct NT(str); - -struct DST { - a: u32, - b: str, -} - -macro_rules! check { - (val: $ty_of:expr, $expected:expr) => { - assert_eq!(type_name_of_val($ty_of), $expected); - }; - ($ty:ty, $expected:expr) => { - assert_eq!(std::any::type_name::<$ty>(), $expected); - }; -} - -/// Tests that [`std::any::type_name`] supports unsized types. -#[test] -fn type_name_unsized() { - check!([u8], "[u8]"); - check!(str, "str"); - check!(dyn Send, "dyn core::marker::Send"); - check!(NT, "type_name_unsized::NT"); - check!(DST, "type_name_unsized::DST"); - check!(&i32, "&i32"); - check!(&'static i32, "&i32"); - check!((i32, u32), "(i32, u32)"); - check!(val: foo(), "type_name_unsized::Foo"); - check!(val: Foo::new, "type_name_unsized::Foo::new"); - check!(val: - ::fmt, - "::fmt" - ); - check!(val: || {}, "type_name_unsized::type_name_unsized::{{closure}}"); - bar::(); -} - -trait Trait { - type Assoc; -} - -impl Trait for i32 { - type Assoc = String; -} - -fn bar() { - check!(T::Assoc, "alloc::string::String"); - check!(T, "i32"); -} - -fn type_name_of_val(_: T) -> &'static str { - std::any::type_name::() -} - -#[derive(Debug)] -struct Foo; - -impl Foo { - fn new() -> Self { - Foo - } -} - -fn foo() -> impl Debug { - Foo -} diff --git a/library/std/tests/volatile-fat-ptr.rs b/library/std/tests/volatile-fat-ptr.rs deleted file mode 100644 index b005c12c6187b..0000000000000 --- a/library/std/tests/volatile-fat-ptr.rs +++ /dev/null @@ -1,15 +0,0 @@ -#![allow(stable_features)] -#![feature(volatile)] - -use std::ptr::{read_volatile, write_volatile}; - -#[test] -fn volatile_fat_ptr() { - let mut x: &'static str = "test"; - unsafe { - let a = read_volatile(&x); - assert_eq!(a, "test"); - write_volatile(&mut x, "foo"); - assert_eq!(x, "foo"); - } -} diff --git a/library/stdarch b/library/stdarch deleted file mode 160000 index df3618d9f3516..0000000000000 --- a/library/stdarch +++ /dev/null @@ -1 +0,0 @@ -Subproject commit df3618d9f35165f4bc548114e511c49c29e1fd9b diff --git a/library/sysroot/Cargo.toml b/library/sysroot/Cargo.toml deleted file mode 100644 index 1ddacd92e6b94..0000000000000 --- a/library/sysroot/Cargo.toml +++ /dev/null @@ -1,29 +0,0 @@ -[package] -name = "sysroot" -version = "0.0.0" -edition = "2021" - -# this is a dummy crate to ensure that all required crates appear in the sysroot -[dependencies] -proc_macro = { path = "../proc_macro" } -std = { path = "../std" } -test = { path = "../test" } - -# Forward features to the `std` crate as necessary -[features] -default = ["std_detect_file_io", "std_detect_dlsym_getauxval", "panic-unwind"] -backtrace = ["std/backtrace"] -compiler-builtins-c = ["std/compiler-builtins-c"] -compiler-builtins-mem = ["std/compiler-builtins-mem"] -compiler-builtins-no-asm = ["std/compiler-builtins-no-asm"] -compiler-builtins-mangled-names = ["std/compiler-builtins-mangled-names"] -compiler-builtins-weak-intrinsics = ["std/compiler-builtins-weak-intrinsics"] -llvm-libunwind = ["std/llvm-libunwind"] -system-llvm-libunwind = ["std/system-llvm-libunwind"] -panic-unwind = ["std/panic_unwind"] -panic_immediate_abort = ["std/panic_immediate_abort"] -optimize_for_size = ["std/optimize_for_size"] -profiler = ["std/profiler"] -std_detect_file_io = ["std/std_detect_file_io"] -std_detect_dlsym_getauxval = ["std/std_detect_dlsym_getauxval"] -std_detect_env_override = ["std/std_detect_env_override"] diff --git a/library/sysroot/src/lib.rs b/library/sysroot/src/lib.rs deleted file mode 100644 index 71ceb580a40c3..0000000000000 --- a/library/sysroot/src/lib.rs +++ /dev/null @@ -1 +0,0 @@ -// This is intentionally empty since this crate is only used to depend on other library crates. diff --git a/library/test/Cargo.toml b/library/test/Cargo.toml deleted file mode 100644 index 0e2409f63ab1a..0000000000000 --- a/library/test/Cargo.toml +++ /dev/null @@ -1,14 +0,0 @@ -[package] -name = "test" -version = "0.0.0" -edition = "2021" - -[dependencies] -getopts = { version = "0.2.21", features = ['rustc-dep-of-std'] } -std = { path = "../std" } -core = { path = "../core" } -panic_unwind = { path = "../panic_unwind" } -panic_abort = { path = "../panic_abort" } - -[target.'cfg(not(all(windows, target_env = "msvc")))'.dependencies] -libc = { version = "0.2.150", default-features = false } diff --git a/library/test/src/bench.rs b/library/test/src/bench.rs deleted file mode 100644 index 64ca13c0d4ed3..0000000000000 --- a/library/test/src/bench.rs +++ /dev/null @@ -1,246 +0,0 @@ -//! Benchmarking module. -use super::{ - event::CompletedTest, - options::BenchMode, - test_result::TestResult, - types::{TestDesc, TestId}, - Sender, -}; - -use crate::stats; -use std::cmp; -use std::io; -use std::panic::{catch_unwind, AssertUnwindSafe}; -use std::sync::{Arc, Mutex}; -use std::time::{Duration, Instant}; - -/// An identity function that *__hints__* to the compiler to be maximally pessimistic about what -/// `black_box` could do. -/// -/// See [`std::hint::black_box`] for details. -#[inline(always)] -pub fn black_box(dummy: T) -> T { - std::hint::black_box(dummy) -} - -/// Manager of the benchmarking runs. -/// -/// This is fed into functions marked with `#[bench]` to allow for -/// set-up & tear-down before running a piece of code repeatedly via a -/// call to `iter`. -#[derive(Clone)] -pub struct Bencher { - mode: BenchMode, - summary: Option, - pub bytes: u64, -} - -impl Bencher { - /// Callback for benchmark functions to run in their body. - pub fn iter(&mut self, mut inner: F) - where - F: FnMut() -> T, - { - if self.mode == BenchMode::Single { - ns_iter_inner(&mut inner, 1); - return; - } - - self.summary = Some(iter(&mut inner)); - } - - pub fn bench(&mut self, mut f: F) -> Result, String> - where - F: FnMut(&mut Bencher) -> Result<(), String>, - { - let result = f(self); - result.map(|_| self.summary) - } -} - -#[derive(Debug, Clone, PartialEq)] -pub struct BenchSamples { - pub ns_iter_summ: stats::Summary, - pub mb_s: usize, -} - -pub fn fmt_bench_samples(bs: &BenchSamples) -> String { - use std::fmt::Write; - let mut output = String::new(); - - let median = bs.ns_iter_summ.median; - let deviation = bs.ns_iter_summ.max - bs.ns_iter_summ.min; - - write!( - output, - "{:>14} ns/iter (+/- {})", - fmt_thousands_sep(median, ','), - fmt_thousands_sep(deviation, ',') - ) - .unwrap(); - if bs.mb_s != 0 { - write!(output, " = {} MB/s", bs.mb_s).unwrap(); - } - output -} - -// Format a number with thousands separators -fn fmt_thousands_sep(mut n: f64, sep: char) -> String { - use std::fmt::Write; - let mut output = String::new(); - let mut trailing = false; - for &pow in &[9, 6, 3, 0] { - let base = 10_usize.pow(pow); - if pow == 0 || trailing || n / base as f64 >= 1.0 { - match (pow, trailing) { - // modern CPUs can execute multiple instructions per nanosecond - // e.g. benching an ADD takes about 0.25ns. - (0, true) => write!(output, "{:06.2}", n / base as f64).unwrap(), - (0, false) => write!(output, "{:.2}", n / base as f64).unwrap(), - (_, true) => write!(output, "{:03}", n as usize / base).unwrap(), - _ => write!(output, "{}", n as usize / base).unwrap(), - } - if pow != 0 { - output.push(sep); - } - trailing = true; - } - n %= base as f64; - } - - output -} - -fn ns_iter_inner(inner: &mut F, k: u64) -> u64 -where - F: FnMut() -> T, -{ - let start = Instant::now(); - for _ in 0..k { - black_box(inner()); - } - start.elapsed().as_nanos() as u64 -} - -pub fn iter(inner: &mut F) -> stats::Summary -where - F: FnMut() -> T, -{ - // Initial bench run to get ballpark figure. - let ns_single = ns_iter_inner(inner, 1); - - // Try to estimate iter count for 1ms falling back to 1m - // iterations if first run took < 1ns. - let ns_target_total = 1_000_000; // 1ms - let mut n = ns_target_total / cmp::max(1, ns_single); - - // if the first run took more than 1ms we don't want to just - // be left doing 0 iterations on every loop. The unfortunate - // side effect of not being able to do as many runs is - // automatically handled by the statistical analysis below - // (i.e., larger error bars). - n = cmp::max(1, n); - - let mut total_run = Duration::new(0, 0); - let samples: &mut [f64] = &mut [0.0_f64; 50]; - loop { - let loop_start = Instant::now(); - - for p in &mut *samples { - *p = ns_iter_inner(inner, n) as f64 / n as f64; - } - - stats::winsorize(samples, 5.0); - let summ = stats::Summary::new(samples); - - for p in &mut *samples { - let ns = ns_iter_inner(inner, 5 * n); - *p = ns as f64 / (5 * n) as f64; - } - - stats::winsorize(samples, 5.0); - let summ5 = stats::Summary::new(samples); - - let loop_run = loop_start.elapsed(); - - // If we've run for 100ms and seem to have converged to a - // stable median. - if loop_run > Duration::from_millis(100) - && summ.median_abs_dev_pct < 1.0 - && summ.median - summ5.median < summ5.median_abs_dev - { - return summ5; - } - - total_run += loop_run; - // Longest we ever run for is 3s. - if total_run > Duration::from_secs(3) { - return summ5; - } - - // If we overflow here just return the results so far. We check a - // multiplier of 10 because we're about to multiply by 2 and the - // next iteration of the loop will also multiply by 5 (to calculate - // the summ5 result) - n = match n.checked_mul(10) { - Some(_) => n * 2, - None => { - return summ5; - } - }; - } -} - -pub fn benchmark( - id: TestId, - desc: TestDesc, - monitor_ch: Sender, - nocapture: bool, - f: F, -) where - F: FnMut(&mut Bencher) -> Result<(), String>, -{ - let mut bs = Bencher { mode: BenchMode::Auto, summary: None, bytes: 0 }; - - let data = Arc::new(Mutex::new(Vec::new())); - - if !nocapture { - io::set_output_capture(Some(data.clone())); - } - - let result = catch_unwind(AssertUnwindSafe(|| bs.bench(f))); - - io::set_output_capture(None); - - let test_result = match result { - //bs.bench(f) { - Ok(Ok(Some(ns_iter_summ))) => { - let ns_iter = cmp::max(ns_iter_summ.median as u64, 1); - let mb_s = bs.bytes * 1000 / ns_iter; - - let bs = BenchSamples { ns_iter_summ, mb_s: mb_s as usize }; - TestResult::TrBench(bs) - } - Ok(Ok(None)) => { - // iter not called, so no data. - // FIXME: error in this case? - let samples: &mut [f64] = &mut [0.0_f64; 1]; - let bs = BenchSamples { ns_iter_summ: stats::Summary::new(samples), mb_s: 0 }; - TestResult::TrBench(bs) - } - Err(_) => TestResult::TrFailed, - Ok(Err(_)) => TestResult::TrFailed, - }; - - let stdout = data.lock().unwrap().to_vec(); - let message = CompletedTest::new(id, desc, test_result, None, stdout); - monitor_ch.send(message).unwrap(); -} - -pub fn run_once(f: F) -> Result<(), String> -where - F: FnMut(&mut Bencher) -> Result<(), String>, -{ - let mut bs = Bencher { mode: BenchMode::Single, summary: None, bytes: 0 }; - bs.bench(f).map(|_| ()) -} diff --git a/library/test/src/cli.rs b/library/test/src/cli.rs deleted file mode 100644 index 6ac3b3eaa797b..0000000000000 --- a/library/test/src/cli.rs +++ /dev/null @@ -1,495 +0,0 @@ -//! Module converting command-line arguments into test configuration. - -use std::env; -use std::path::PathBuf; - -use super::options::{ColorConfig, Options, OutputFormat, RunIgnored}; -use super::time::TestTimeOptions; -use std::io::{self, IsTerminal}; - -#[derive(Debug)] -pub struct TestOpts { - pub list: bool, - pub filters: Vec, - pub filter_exact: bool, - pub force_run_in_process: bool, - pub exclude_should_panic: bool, - pub run_ignored: RunIgnored, - pub run_tests: bool, - pub bench_benchmarks: bool, - pub logfile: Option, - pub nocapture: bool, - pub color: ColorConfig, - pub format: OutputFormat, - pub shuffle: bool, - pub shuffle_seed: Option, - pub test_threads: Option, - pub skip: Vec, - pub time_options: Option, - /// Stop at first failing test. - /// May run a few more tests due to threading, but will - /// abort as soon as possible. - pub fail_fast: bool, - pub options: Options, -} - -impl TestOpts { - pub fn use_color(&self) -> bool { - match self.color { - ColorConfig::AutoColor => !self.nocapture && io::stdout().is_terminal(), - ColorConfig::AlwaysColor => true, - ColorConfig::NeverColor => false, - } - } -} - -/// Result of parsing the options. -pub type OptRes = Result; -/// Result of parsing the option part. -type OptPartRes = Result; - -fn optgroups() -> getopts::Options { - let mut opts = getopts::Options::new(); - opts.optflag("", "include-ignored", "Run ignored and not ignored tests") - .optflag("", "ignored", "Run only ignored tests") - .optflag("", "force-run-in-process", "Forces tests to run in-process when panic=abort") - .optflag("", "exclude-should-panic", "Excludes tests marked as should_panic") - .optflag("", "test", "Run tests and not benchmarks") - .optflag("", "bench", "Run benchmarks instead of tests") - .optflag("", "list", "List all tests and benchmarks") - .optflag("h", "help", "Display this message") - .optopt("", "logfile", "Write logs to the specified file", "PATH") - .optflag( - "", - "nocapture", - "don't capture stdout/stderr of each \ - task, allow printing directly", - ) - .optopt( - "", - "test-threads", - "Number of threads used for running tests \ - in parallel", - "n_threads", - ) - .optmulti( - "", - "skip", - "Skip tests whose names contain FILTER (this flag can \ - be used multiple times)", - "FILTER", - ) - .optflag( - "q", - "quiet", - "Display one character per test instead of one line. \ - Alias to --format=terse", - ) - .optflag("", "exact", "Exactly match filters rather than by substring") - .optopt( - "", - "color", - "Configure coloring of output: - auto = colorize if stdout is a tty and tests are run on serially (default); - always = always colorize output; - never = never colorize output;", - "auto|always|never", - ) - .optopt( - "", - "format", - "Configure formatting of output: - pretty = Print verbose output; - terse = Display one character per test; - json = Output a json document; - junit = Output a JUnit document", - "pretty|terse|json|junit", - ) - .optflag("", "show-output", "Show captured stdout of successful tests") - .optopt( - "Z", - "", - "Enable nightly-only flags: - unstable-options = Allow use of experimental features", - "unstable-options", - ) - .optflag( - "", - "report-time", - "Show execution time of each test. - - Threshold values for colorized output can be configured via - `RUST_TEST_TIME_UNIT`, `RUST_TEST_TIME_INTEGRATION` and - `RUST_TEST_TIME_DOCTEST` environment variables. - - Expected format of environment variable is `VARIABLE=WARN_TIME,CRITICAL_TIME`. - Durations must be specified in milliseconds, e.g. `500,2000` means that the warn time - is 0.5 seconds, and the critical time is 2 seconds. - - Not available for --format=terse", - ) - .optflag( - "", - "ensure-time", - "Treat excess of the test execution time limit as error. - - Threshold values for this option can be configured via - `RUST_TEST_TIME_UNIT`, `RUST_TEST_TIME_INTEGRATION` and - `RUST_TEST_TIME_DOCTEST` environment variables. - - Expected format of environment variable is `VARIABLE=WARN_TIME,CRITICAL_TIME`. - - `CRITICAL_TIME` here means the limit that should not be exceeded by test. - ", - ) - .optflag("", "shuffle", "Run tests in random order") - .optopt( - "", - "shuffle-seed", - "Run tests in random order; seed the random number generator with SEED", - "SEED", - ); - opts -} - -fn usage(binary: &str, options: &getopts::Options) { - let message = format!("Usage: {binary} [OPTIONS] [FILTERS...]"); - println!( - r#"{usage} - -The FILTER string is tested against the name of all tests, and only those -tests whose names contain the filter are run. Multiple filter strings may -be passed, which will run all tests matching any of the filters. - -By default, all tests are run in parallel. This can be altered with the ---test-threads flag or the RUST_TEST_THREADS environment variable when running -tests (set it to 1). - -By default, the tests are run in alphabetical order. Use --shuffle or set -RUST_TEST_SHUFFLE to run the tests in random order. Pass the generated -"shuffle seed" to --shuffle-seed (or set RUST_TEST_SHUFFLE_SEED) to run the -tests in the same order again. Note that --shuffle and --shuffle-seed do not -affect whether the tests are run in parallel. - -All tests have their standard output and standard error captured by default. -This can be overridden with the --nocapture flag or setting RUST_TEST_NOCAPTURE -environment variable to a value other than "0". Logging is not captured by default. - -Test Attributes: - - `#[test]` - Indicates a function is a test to be run. This function - takes no arguments. - `#[bench]` - Indicates a function is a benchmark to be run. This - function takes one argument (test::Bencher). - `#[should_panic]` - This function (also labeled with `#[test]`) will only pass if - the code causes a panic (an assertion failure or panic!) - A message may be provided, which the failure string must - contain: #[should_panic(expected = "foo")]. - `#[ignore]` - When applied to a function which is already attributed as a - test, then the test runner will ignore these tests during - normal test runs. Running with --ignored or --include-ignored will run - these tests."#, - usage = options.usage(&message) - ); -} - -/// Parses command line arguments into test options. -/// Returns `None` if help was requested (since we only show help message and don't run tests), -/// returns `Some(Err(..))` if provided arguments are incorrect, -/// otherwise creates a `TestOpts` object and returns it. -pub fn parse_opts(args: &[String]) -> Option { - // Parse matches. - let opts = optgroups(); - let binary = args.get(0).map(|c| &**c).unwrap_or("..."); - let args = args.get(1..).unwrap_or(args); - let matches = match opts.parse(args) { - Ok(m) => m, - Err(f) => return Some(Err(f.to_string())), - }; - - // Check if help was requested. - if matches.opt_present("h") { - // Show help and do nothing more. - usage(binary, &opts); - return None; - } - - // Actually parse the opts. - let opts_result = parse_opts_impl(matches); - - Some(opts_result) -} - -// Gets the option value and checks if unstable features are enabled. -macro_rules! unstable_optflag { - ($matches:ident, $allow_unstable:ident, $option_name:literal) => {{ - let opt = $matches.opt_present($option_name); - if !$allow_unstable && opt { - return Err(format!( - "The \"{}\" flag is only accepted on the nightly compiler with -Z unstable-options", - $option_name - )); - } - - opt - }}; -} - -// Gets the option value and checks if unstable features are enabled. -macro_rules! unstable_optopt { - ($matches:ident, $allow_unstable:ident, $option_name:literal) => {{ - let opt = $matches.opt_str($option_name); - if !$allow_unstable && opt.is_some() { - return Err(format!( - "The \"{}\" option is only accepted on the nightly compiler with -Z unstable-options", - $option_name - )); - } - - opt - }}; -} - -// Implementation of `parse_opts` that doesn't care about help message -// and returns a `Result`. -fn parse_opts_impl(matches: getopts::Matches) -> OptRes { - let allow_unstable = get_allow_unstable(&matches)?; - - // Unstable flags - let force_run_in_process = unstable_optflag!(matches, allow_unstable, "force-run-in-process"); - let exclude_should_panic = unstable_optflag!(matches, allow_unstable, "exclude-should-panic"); - let time_options = get_time_options(&matches, allow_unstable)?; - let shuffle = get_shuffle(&matches, allow_unstable)?; - let shuffle_seed = get_shuffle_seed(&matches, allow_unstable)?; - - let include_ignored = matches.opt_present("include-ignored"); - let quiet = matches.opt_present("quiet"); - let exact = matches.opt_present("exact"); - let list = matches.opt_present("list"); - let skip = matches.opt_strs("skip"); - - let bench_benchmarks = matches.opt_present("bench"); - let run_tests = !bench_benchmarks || matches.opt_present("test"); - - let logfile = get_log_file(&matches)?; - let run_ignored = get_run_ignored(&matches, include_ignored)?; - let filters = matches.free.clone(); - let nocapture = get_nocapture(&matches)?; - let test_threads = get_test_threads(&matches)?; - let color = get_color_config(&matches)?; - let format = get_format(&matches, quiet, allow_unstable)?; - - let options = Options::new().display_output(matches.opt_present("show-output")); - - let test_opts = TestOpts { - list, - filters, - filter_exact: exact, - force_run_in_process, - exclude_should_panic, - run_ignored, - run_tests, - bench_benchmarks, - logfile, - nocapture, - color, - format, - shuffle, - shuffle_seed, - test_threads, - skip, - time_options, - options, - fail_fast: false, - }; - - Ok(test_opts) -} - -// FIXME: Copied from librustc_ast until linkage errors are resolved. Issue #47566 -fn is_nightly() -> bool { - // Whether this is a feature-staged build, i.e., on the beta or stable channel - let disable_unstable_features = - option_env!("CFG_DISABLE_UNSTABLE_FEATURES").map(|s| s != "0").unwrap_or(false); - // Whether we should enable unstable features for bootstrapping - let bootstrap = env::var("RUSTC_BOOTSTRAP").is_ok(); - - bootstrap || !disable_unstable_features -} - -// Gets the CLI options associated with `report-time` feature. -fn get_time_options( - matches: &getopts::Matches, - allow_unstable: bool, -) -> OptPartRes> { - let report_time = unstable_optflag!(matches, allow_unstable, "report-time"); - let ensure_test_time = unstable_optflag!(matches, allow_unstable, "ensure-time"); - - // If `ensure-test-time` option is provided, time output is enforced, - // so user won't be confused if any of tests will silently fail. - let options = if report_time || ensure_test_time { - Some(TestTimeOptions::new_from_env(ensure_test_time)) - } else { - None - }; - - Ok(options) -} - -fn get_shuffle(matches: &getopts::Matches, allow_unstable: bool) -> OptPartRes { - let mut shuffle = unstable_optflag!(matches, allow_unstable, "shuffle"); - if !shuffle && allow_unstable { - shuffle = match env::var("RUST_TEST_SHUFFLE") { - Ok(val) => &val != "0", - Err(_) => false, - }; - } - - Ok(shuffle) -} - -fn get_shuffle_seed(matches: &getopts::Matches, allow_unstable: bool) -> OptPartRes> { - let mut shuffle_seed = match unstable_optopt!(matches, allow_unstable, "shuffle-seed") { - Some(n_str) => match n_str.parse::() { - Ok(n) => Some(n), - Err(e) => { - return Err(format!( - "argument for --shuffle-seed must be a number \ - (error: {e})" - )); - } - }, - None => None, - }; - - if shuffle_seed.is_none() && allow_unstable { - shuffle_seed = match env::var("RUST_TEST_SHUFFLE_SEED") { - Ok(val) => match val.parse::() { - Ok(n) => Some(n), - Err(_) => panic!("RUST_TEST_SHUFFLE_SEED is `{val}`, should be a number."), - }, - Err(_) => None, - }; - } - - Ok(shuffle_seed) -} - -fn get_test_threads(matches: &getopts::Matches) -> OptPartRes> { - let test_threads = match matches.opt_str("test-threads") { - Some(n_str) => match n_str.parse::() { - Ok(0) => return Err("argument for --test-threads must not be 0".to_string()), - Ok(n) => Some(n), - Err(e) => { - return Err(format!( - "argument for --test-threads must be a number > 0 \ - (error: {e})" - )); - } - }, - None => None, - }; - - Ok(test_threads) -} - -fn get_format( - matches: &getopts::Matches, - quiet: bool, - allow_unstable: bool, -) -> OptPartRes { - let format = match matches.opt_str("format").as_deref() { - None if quiet => OutputFormat::Terse, - Some("pretty") | None => OutputFormat::Pretty, - Some("terse") => OutputFormat::Terse, - Some("json") => { - if !allow_unstable { - return Err("The \"json\" format is only accepted on the nightly compiler with -Z unstable-options".into()); - } - OutputFormat::Json - } - Some("junit") => { - if !allow_unstable { - return Err("The \"junit\" format is only accepted on the nightly compiler with -Z unstable-options".into()); - } - OutputFormat::Junit - } - Some(v) => { - return Err(format!( - "argument for --format must be pretty, terse, json or junit (was \ - {v})" - )); - } - }; - - Ok(format) -} - -fn get_color_config(matches: &getopts::Matches) -> OptPartRes { - let color = match matches.opt_str("color").as_deref() { - Some("auto") | None => ColorConfig::AutoColor, - Some("always") => ColorConfig::AlwaysColor, - Some("never") => ColorConfig::NeverColor, - - Some(v) => { - return Err(format!( - "argument for --color must be auto, always, or never (was \ - {v})" - )); - } - }; - - Ok(color) -} - -fn get_nocapture(matches: &getopts::Matches) -> OptPartRes { - let mut nocapture = matches.opt_present("nocapture"); - if !nocapture { - nocapture = match env::var("RUST_TEST_NOCAPTURE") { - Ok(val) => &val != "0", - Err(_) => false, - }; - } - - Ok(nocapture) -} - -fn get_run_ignored(matches: &getopts::Matches, include_ignored: bool) -> OptPartRes { - let run_ignored = match (include_ignored, matches.opt_present("ignored")) { - (true, true) => { - return Err("the options --include-ignored and --ignored are mutually exclusive".into()); - } - (true, false) => RunIgnored::Yes, - (false, true) => RunIgnored::Only, - (false, false) => RunIgnored::No, - }; - - Ok(run_ignored) -} - -fn get_allow_unstable(matches: &getopts::Matches) -> OptPartRes { - let mut allow_unstable = false; - - if let Some(opt) = matches.opt_str("Z") { - if !is_nightly() { - return Err("the option `Z` is only accepted on the nightly compiler".into()); - } - - match &*opt { - "unstable-options" => { - allow_unstable = true; - } - _ => { - return Err("Unrecognized option to `Z`".into()); - } - } - }; - - Ok(allow_unstable) -} - -fn get_log_file(matches: &getopts::Matches) -> OptPartRes> { - let logfile = matches.opt_str("logfile").map(|s| PathBuf::from(&s)); - - Ok(logfile) -} diff --git a/library/test/src/console.rs b/library/test/src/console.rs deleted file mode 100644 index 7e224d60d9dc5..0000000000000 --- a/library/test/src/console.rs +++ /dev/null @@ -1,336 +0,0 @@ -//! Module providing interface for running tests in the console. - -use std::fs::File; -use std::io; -use std::io::prelude::Write; -use std::time::Instant; - -use super::{ - bench::fmt_bench_samples, - cli::TestOpts, - event::{CompletedTest, TestEvent}, - filter_tests, - formatters::{JsonFormatter, JunitFormatter, OutputFormatter, PrettyFormatter, TerseFormatter}, - helpers::{concurrency::get_concurrency, metrics::MetricMap}, - options::{Options, OutputFormat}, - run_tests, term, - test_result::TestResult, - time::{TestExecTime, TestSuiteExecTime}, - types::{NamePadding, TestDesc, TestDescAndFn}, -}; - -/// Generic wrapper over stdout. -pub enum OutputLocation { - Pretty(Box), - Raw(T), -} - -impl Write for OutputLocation { - fn write(&mut self, buf: &[u8]) -> io::Result { - match *self { - OutputLocation::Pretty(ref mut term) => term.write(buf), - OutputLocation::Raw(ref mut stdout) => stdout.write(buf), - } - } - - fn flush(&mut self) -> io::Result<()> { - match *self { - OutputLocation::Pretty(ref mut term) => term.flush(), - OutputLocation::Raw(ref mut stdout) => stdout.flush(), - } - } -} - -pub struct ConsoleTestDiscoveryState { - pub log_out: Option, - pub tests: usize, - pub benchmarks: usize, - pub ignored: usize, -} - -impl ConsoleTestDiscoveryState { - pub fn new(opts: &TestOpts) -> io::Result { - let log_out = match opts.logfile { - Some(ref path) => Some(File::create(path)?), - None => None, - }; - - Ok(ConsoleTestDiscoveryState { log_out, tests: 0, benchmarks: 0, ignored: 0 }) - } - - pub fn write_log(&mut self, msg: F) -> io::Result<()> - where - S: AsRef, - F: FnOnce() -> S, - { - match self.log_out { - None => Ok(()), - Some(ref mut o) => { - let msg = msg(); - let msg = msg.as_ref(); - o.write_all(msg.as_bytes()) - } - } - } -} - -pub struct ConsoleTestState { - pub log_out: Option, - pub total: usize, - pub passed: usize, - pub failed: usize, - pub ignored: usize, - pub filtered_out: usize, - pub measured: usize, - pub exec_time: Option, - pub metrics: MetricMap, - pub failures: Vec<(TestDesc, Vec)>, - pub not_failures: Vec<(TestDesc, Vec)>, - pub ignores: Vec<(TestDesc, Vec)>, - pub time_failures: Vec<(TestDesc, Vec)>, - pub options: Options, -} - -impl ConsoleTestState { - pub fn new(opts: &TestOpts) -> io::Result { - let log_out = match opts.logfile { - Some(ref path) => Some(File::create(path)?), - None => None, - }; - - Ok(ConsoleTestState { - log_out, - total: 0, - passed: 0, - failed: 0, - ignored: 0, - filtered_out: 0, - measured: 0, - exec_time: None, - metrics: MetricMap::new(), - failures: Vec::new(), - not_failures: Vec::new(), - ignores: Vec::new(), - time_failures: Vec::new(), - options: opts.options, - }) - } - - pub fn write_log(&mut self, msg: F) -> io::Result<()> - where - S: AsRef, - F: FnOnce() -> S, - { - match self.log_out { - None => Ok(()), - Some(ref mut o) => { - let msg = msg(); - let msg = msg.as_ref(); - o.write_all(msg.as_bytes()) - } - } - } - - pub fn write_log_result( - &mut self, - test: &TestDesc, - result: &TestResult, - exec_time: Option<&TestExecTime>, - ) -> io::Result<()> { - self.write_log(|| { - let TestDesc { name, ignore_message, .. } = test; - format!( - "{} {}", - match *result { - TestResult::TrOk => "ok".to_owned(), - TestResult::TrFailed => "failed".to_owned(), - TestResult::TrFailedMsg(ref msg) => format!("failed: {msg}"), - TestResult::TrIgnored => { - if let Some(msg) = ignore_message { - format!("ignored: {msg}") - } else { - "ignored".to_owned() - } - } - TestResult::TrBench(ref bs) => fmt_bench_samples(bs), - TestResult::TrTimedFail => "failed (time limit exceeded)".to_owned(), - }, - name, - ) - })?; - if let Some(exec_time) = exec_time { - self.write_log(|| format!(" <{exec_time}>"))?; - } - self.write_log(|| "\n") - } - - fn current_test_count(&self) -> usize { - self.passed + self.failed + self.ignored + self.measured - } -} - -// List the tests to console, and optionally to logfile. Filters are honored. -pub fn list_tests_console(opts: &TestOpts, tests: Vec) -> io::Result<()> { - let output = match term::stdout() { - None => OutputLocation::Raw(io::stdout().lock()), - Some(t) => OutputLocation::Pretty(t), - }; - - let mut out: Box = match opts.format { - OutputFormat::Pretty | OutputFormat::Junit => { - Box::new(PrettyFormatter::new(output, false, 0, false, None)) - } - OutputFormat::Terse => Box::new(TerseFormatter::new(output, false, 0, false)), - OutputFormat::Json => Box::new(JsonFormatter::new(output)), - }; - let mut st = ConsoleTestDiscoveryState::new(opts)?; - - out.write_discovery_start()?; - for test in filter_tests(opts, tests).into_iter() { - use crate::TestFn::*; - - let TestDescAndFn { desc, testfn } = test; - - let fntype = match testfn { - StaticTestFn(..) | DynTestFn(..) | StaticBenchAsTestFn(..) | DynBenchAsTestFn(..) => { - st.tests += 1; - "test" - } - StaticBenchFn(..) | DynBenchFn(..) => { - st.benchmarks += 1; - "benchmark" - } - }; - - st.ignored += if desc.ignore { 1 } else { 0 }; - - out.write_test_discovered(&desc, fntype)?; - st.write_log(|| format!("{fntype} {}\n", desc.name))?; - } - - out.write_discovery_finish(&st) -} - -// Updates `ConsoleTestState` depending on result of the test execution. -fn handle_test_result(st: &mut ConsoleTestState, completed_test: CompletedTest) { - let test = completed_test.desc; - let stdout = completed_test.stdout; - match completed_test.result { - TestResult::TrOk => { - st.passed += 1; - st.not_failures.push((test, stdout)); - } - TestResult::TrIgnored => { - st.ignored += 1; - st.ignores.push((test, stdout)); - } - TestResult::TrBench(bs) => { - st.metrics.insert_metric( - test.name.as_slice(), - bs.ns_iter_summ.median, - bs.ns_iter_summ.max - bs.ns_iter_summ.min, - ); - st.measured += 1 - } - TestResult::TrFailed => { - st.failed += 1; - st.failures.push((test, stdout)); - } - TestResult::TrFailedMsg(msg) => { - st.failed += 1; - let mut stdout = stdout; - stdout.extend_from_slice(format!("note: {msg}").as_bytes()); - st.failures.push((test, stdout)); - } - TestResult::TrTimedFail => { - st.failed += 1; - st.time_failures.push((test, stdout)); - } - } -} - -// Handler for events that occur during test execution. -// It is provided as a callback to the `run_tests` function. -fn on_test_event( - event: &TestEvent, - st: &mut ConsoleTestState, - out: &mut dyn OutputFormatter, -) -> io::Result<()> { - match (*event).clone() { - TestEvent::TeFiltered(filtered_tests, shuffle_seed) => { - st.total = filtered_tests; - out.write_run_start(filtered_tests, shuffle_seed)?; - } - TestEvent::TeFilteredOut(filtered_out) => { - st.filtered_out = filtered_out; - } - TestEvent::TeWait(ref test) => out.write_test_start(test)?, - TestEvent::TeTimeout(ref test) => out.write_timeout(test)?, - TestEvent::TeResult(completed_test) => { - let test = &completed_test.desc; - let result = &completed_test.result; - let exec_time = &completed_test.exec_time; - let stdout = &completed_test.stdout; - - st.write_log_result(test, result, exec_time.as_ref())?; - out.write_result(test, result, exec_time.as_ref(), stdout, st)?; - handle_test_result(st, completed_test); - } - } - - Ok(()) -} - -/// A simple console test runner. -/// Runs provided tests reporting process and results to the stdout. -pub fn run_tests_console(opts: &TestOpts, tests: Vec) -> io::Result { - let output = match term::stdout() { - None => OutputLocation::Raw(io::stdout()), - Some(t) => OutputLocation::Pretty(t), - }; - - let max_name_len = tests - .iter() - .max_by_key(|t| len_if_padded(t)) - .map(|t| t.desc.name.as_slice().len()) - .unwrap_or(0); - - let is_multithreaded = opts.test_threads.unwrap_or_else(get_concurrency) > 1; - - let mut out: Box = match opts.format { - OutputFormat::Pretty => Box::new(PrettyFormatter::new( - output, - opts.use_color(), - max_name_len, - is_multithreaded, - opts.time_options, - )), - OutputFormat::Terse => { - Box::new(TerseFormatter::new(output, opts.use_color(), max_name_len, is_multithreaded)) - } - OutputFormat::Json => Box::new(JsonFormatter::new(output)), - OutputFormat::Junit => Box::new(JunitFormatter::new(output)), - }; - let mut st = ConsoleTestState::new(opts)?; - - // Prevent the usage of `Instant` in some cases: - // - It's currently not supported for wasm targets. - let is_instant_unsupported = - (cfg!(target_family = "wasm") && !cfg!(target_os = "wasi")) || cfg!(target_os = "zkvm"); - - let start_time = (!is_instant_unsupported).then(Instant::now); - run_tests(opts, tests, |x| on_test_event(&x, &mut st, &mut *out))?; - st.exec_time = start_time.map(|t| TestSuiteExecTime(t.elapsed())); - - assert!(opts.fail_fast || st.current_test_count() == st.total); - - out.write_run_finish(&st) -} - -// Calculates padding for given test description. -fn len_if_padded(t: &TestDescAndFn) -> usize { - match t.testfn.padding() { - NamePadding::PadNone => 0, - NamePadding::PadOnRight => t.desc.name.as_slice().len(), - } -} diff --git a/library/test/src/event.rs b/library/test/src/event.rs deleted file mode 100644 index 80281ebd2d4cd..0000000000000 --- a/library/test/src/event.rs +++ /dev/null @@ -1,36 +0,0 @@ -//! Module containing different events that can occur -//! during tests execution process. - -use super::test_result::TestResult; -use super::time::TestExecTime; -use super::types::{TestDesc, TestId}; - -#[derive(Debug, Clone)] -pub struct CompletedTest { - pub id: TestId, - pub desc: TestDesc, - pub result: TestResult, - pub exec_time: Option, - pub stdout: Vec, -} - -impl CompletedTest { - pub fn new( - id: TestId, - desc: TestDesc, - result: TestResult, - exec_time: Option, - stdout: Vec, - ) -> Self { - Self { id, desc, result, exec_time, stdout } - } -} - -#[derive(Debug, Clone)] -pub enum TestEvent { - TeFiltered(usize, Option), - TeWait(TestDesc), - TeResult(CompletedTest), - TeTimeout(TestDesc), - TeFilteredOut(usize), -} diff --git a/library/test/src/formatters/json.rs b/library/test/src/formatters/json.rs deleted file mode 100644 index 6245aae17c4d7..0000000000000 --- a/library/test/src/formatters/json.rs +++ /dev/null @@ -1,285 +0,0 @@ -use std::{borrow::Cow, io, io::prelude::Write}; - -use super::OutputFormatter; -use crate::{ - console::{ConsoleTestDiscoveryState, ConsoleTestState, OutputLocation}, - test_result::TestResult, - time, - types::TestDesc, -}; - -pub(crate) struct JsonFormatter { - out: OutputLocation, -} - -impl JsonFormatter { - pub fn new(out: OutputLocation) -> Self { - Self { out } - } - - fn writeln_message(&mut self, s: &str) -> io::Result<()> { - // self.out will take a lock, but that lock is released when write_all returns. This - // results in a race condition and json output may not end with a new line. We avoid this - // by issuing `write_all` calls line-by-line. - assert_eq!(s.chars().last(), Some('\n')); - - self.out.write_all(s.as_ref()) - } - - fn write_event( - &mut self, - ty: &str, - name: &str, - event: &str, - exec_time: Option<&time::TestExecTime>, - stdout: Option>, - extra: Option<&str>, - ) -> io::Result<()> { - // A doc test's name includes a filename which must be escaped for correct json. - let name = EscapedString(name); - let exec_time_json = if let Some(exec_time) = exec_time { - format!(r#", "exec_time": {}"#, exec_time.0.as_secs_f64()) - } else { - String::from("") - }; - let stdout_json = if let Some(stdout) = stdout { - format!(r#", "stdout": "{}""#, EscapedString(stdout)) - } else { - String::from("") - }; - let extra_json = - if let Some(extra) = extra { format!(r#", {extra}"#) } else { String::from("") }; - let newline = "\n"; - - self.writeln_message(&format!( - r#"{{ "type": "{ty}", "name": "{name}", "event": "{event}"{exec_time_json}{stdout_json}{extra_json} }}{newline}"#)) - } -} - -impl OutputFormatter for JsonFormatter { - fn write_discovery_start(&mut self) -> io::Result<()> { - self.writeln_message(concat!(r#"{ "type": "suite", "event": "discovery" }"#, "\n")) - } - - fn write_test_discovered(&mut self, desc: &TestDesc, test_type: &str) -> io::Result<()> { - let TestDesc { - name, - ignore, - ignore_message, - source_file, - start_line, - start_col, - end_line, - end_col, - .. - } = desc; - - let name = EscapedString(name.as_slice()); - let ignore_message = ignore_message.unwrap_or(""); - let source_path = EscapedString(source_file); - let newline = "\n"; - - self.writeln_message(&format!( - r#"{{ "type": "{test_type}", "event": "discovered", "name": "{name}", "ignore": {ignore}, "ignore_message": "{ignore_message}", "source_path": "{source_path}", "start_line": {start_line}, "start_col": {start_col}, "end_line": {end_line}, "end_col": {end_col} }}{newline}"# - )) - } - - fn write_discovery_finish(&mut self, state: &ConsoleTestDiscoveryState) -> io::Result<()> { - let ConsoleTestDiscoveryState { tests, benchmarks, ignored, .. } = state; - - let total = tests + benchmarks; - let newline = "\n"; - self.writeln_message(&format!( - r#"{{ "type": "suite", "event": "completed", "tests": {tests}, "benchmarks": {benchmarks}, "total": {total}, "ignored": {ignored} }}{newline}"# - )) - } - - fn write_run_start(&mut self, test_count: usize, shuffle_seed: Option) -> io::Result<()> { - let shuffle_seed_json = if let Some(shuffle_seed) = shuffle_seed { - format!(r#", "shuffle_seed": {shuffle_seed}"#) - } else { - String::new() - }; - let newline = "\n"; - self.writeln_message(&format!( - r#"{{ "type": "suite", "event": "started", "test_count": {test_count}{shuffle_seed_json} }}{newline}"# - )) - } - - fn write_test_start(&mut self, desc: &TestDesc) -> io::Result<()> { - let name = EscapedString(desc.name.as_slice()); - let newline = "\n"; - self.writeln_message(&format!( - r#"{{ "type": "test", "event": "started", "name": "{name}" }}{newline}"# - )) - } - - fn write_result( - &mut self, - desc: &TestDesc, - result: &TestResult, - exec_time: Option<&time::TestExecTime>, - stdout: &[u8], - state: &ConsoleTestState, - ) -> io::Result<()> { - let display_stdout = state.options.display_output || *result != TestResult::TrOk; - let stdout = if display_stdout && !stdout.is_empty() { - Some(String::from_utf8_lossy(stdout)) - } else { - None - }; - match *result { - TestResult::TrOk => { - self.write_event("test", desc.name.as_slice(), "ok", exec_time, stdout, None) - } - - TestResult::TrFailed => { - self.write_event("test", desc.name.as_slice(), "failed", exec_time, stdout, None) - } - - TestResult::TrTimedFail => self.write_event( - "test", - desc.name.as_slice(), - "failed", - exec_time, - stdout, - Some(r#""reason": "time limit exceeded""#), - ), - - TestResult::TrFailedMsg(ref m) => self.write_event( - "test", - desc.name.as_slice(), - "failed", - exec_time, - stdout, - Some(&*format!(r#""message": "{}""#, EscapedString(m))), - ), - - TestResult::TrIgnored => self.write_event( - "test", - desc.name.as_slice(), - "ignored", - exec_time, - stdout, - desc.ignore_message - .map(|msg| format!(r#""message": "{}""#, EscapedString(msg))) - .as_deref(), - ), - - TestResult::TrBench(ref bs) => { - let median = bs.ns_iter_summ.median; - let deviation = bs.ns_iter_summ.max - bs.ns_iter_summ.min; - - let mbps = if bs.mb_s == 0 { - String::new() - } else { - format!(r#", "mib_per_second": {}"#, bs.mb_s) - }; - let name = EscapedString(desc.name.as_slice()); - - self.writeln_message(&format!( - "{{ \"type\": \"bench\", \ - \"name\": \"{name}\", \ - \"median\": {median}, \ - \"deviation\": {deviation}{mbps} }}\n", - )) - } - } - } - - fn write_timeout(&mut self, desc: &TestDesc) -> io::Result<()> { - let name = EscapedString(desc.name.as_slice()); - let newline = "\n"; - self.writeln_message(&format!( - r#"{{ "type": "test", "event": "timeout", "name": "{name}" }}{newline}"#, - )) - } - - fn write_run_finish(&mut self, state: &ConsoleTestState) -> io::Result { - let event = if state.failed == 0 { "ok" } else { "failed" }; - let passed = state.passed; - let failed = state.failed; - let ignored = state.ignored; - let measured = state.measured; - let filtered_out = state.filtered_out; - let exec_time_json = if let Some(ref exec_time) = state.exec_time { - format!(r#", "exec_time": {}"#, exec_time.0.as_secs_f64()) - } else { - String::from("") - }; - let newline = "\n"; - - self.writeln_message(&format!( - r#"{{ "type": "suite", "event": "{event}", "passed": {passed}, "failed": {failed}, "ignored": {ignored}, "measured": {measured}, "filtered_out": {filtered_out}{exec_time_json} }}{newline}"# - ))?; - - Ok(state.failed == 0) - } -} - -/// A formatting utility used to print strings with characters in need of escaping. -/// Base code taken form `libserialize::json::escape_str` -struct EscapedString>(S); - -impl> std::fmt::Display for EscapedString { - fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> ::std::fmt::Result { - let mut start = 0; - - for (i, byte) in self.0.as_ref().bytes().enumerate() { - let escaped = match byte { - b'"' => "\\\"", - b'\\' => "\\\\", - b'\x00' => "\\u0000", - b'\x01' => "\\u0001", - b'\x02' => "\\u0002", - b'\x03' => "\\u0003", - b'\x04' => "\\u0004", - b'\x05' => "\\u0005", - b'\x06' => "\\u0006", - b'\x07' => "\\u0007", - b'\x08' => "\\b", - b'\t' => "\\t", - b'\n' => "\\n", - b'\x0b' => "\\u000b", - b'\x0c' => "\\f", - b'\r' => "\\r", - b'\x0e' => "\\u000e", - b'\x0f' => "\\u000f", - b'\x10' => "\\u0010", - b'\x11' => "\\u0011", - b'\x12' => "\\u0012", - b'\x13' => "\\u0013", - b'\x14' => "\\u0014", - b'\x15' => "\\u0015", - b'\x16' => "\\u0016", - b'\x17' => "\\u0017", - b'\x18' => "\\u0018", - b'\x19' => "\\u0019", - b'\x1a' => "\\u001a", - b'\x1b' => "\\u001b", - b'\x1c' => "\\u001c", - b'\x1d' => "\\u001d", - b'\x1e' => "\\u001e", - b'\x1f' => "\\u001f", - b'\x7f' => "\\u007f", - _ => { - continue; - } - }; - - if start < i { - f.write_str(&self.0.as_ref()[start..i])?; - } - - f.write_str(escaped)?; - - start = i + 1; - } - - if start != self.0.as_ref().len() { - f.write_str(&self.0.as_ref()[start..])?; - } - - Ok(()) - } -} diff --git a/library/test/src/formatters/junit.rs b/library/test/src/formatters/junit.rs deleted file mode 100644 index a211ebf1ded16..0000000000000 --- a/library/test/src/formatters/junit.rs +++ /dev/null @@ -1,222 +0,0 @@ -use std::io::{self, prelude::Write}; -use std::time::Duration; - -use super::OutputFormatter; -use crate::{ - console::{ConsoleTestDiscoveryState, ConsoleTestState, OutputLocation}, - test_result::TestResult, - time, - types::{TestDesc, TestType}, -}; - -pub struct JunitFormatter { - out: OutputLocation, - results: Vec<(TestDesc, TestResult, Duration, Vec)>, -} - -impl JunitFormatter { - pub fn new(out: OutputLocation) -> Self { - Self { out, results: Vec::new() } - } - - fn write_message(&mut self, s: &str) -> io::Result<()> { - assert!(!s.contains('\n')); - - self.out.write_all(s.as_ref()) - } -} - -fn str_to_cdata(s: &str) -> String { - // Drop the stdout in a cdata. Unfortunately, you can't put either of `]]>` or - // `", "]]]]>"); - let escaped_output = escaped_output.replace(" ", ""); - format!("", escaped_output) -} - -impl OutputFormatter for JunitFormatter { - fn write_discovery_start(&mut self) -> io::Result<()> { - Err(io::Error::new(io::ErrorKind::NotFound, "Not yet implemented!")) - } - - fn write_test_discovered(&mut self, _desc: &TestDesc, _test_type: &str) -> io::Result<()> { - Err(io::Error::new(io::ErrorKind::NotFound, "Not yet implemented!")) - } - - fn write_discovery_finish(&mut self, _state: &ConsoleTestDiscoveryState) -> io::Result<()> { - Err(io::Error::new(io::ErrorKind::NotFound, "Not yet implemented!")) - } - - fn write_run_start( - &mut self, - _test_count: usize, - _shuffle_seed: Option, - ) -> io::Result<()> { - // We write xml header on run start - self.write_message("") - } - - fn write_test_start(&mut self, _desc: &TestDesc) -> io::Result<()> { - // We do not output anything on test start. - Ok(()) - } - - fn write_timeout(&mut self, _desc: &TestDesc) -> io::Result<()> { - // We do not output anything on test timeout. - Ok(()) - } - - fn write_result( - &mut self, - desc: &TestDesc, - result: &TestResult, - exec_time: Option<&time::TestExecTime>, - stdout: &[u8], - _state: &ConsoleTestState, - ) -> io::Result<()> { - // Because the testsuite node holds some of the information as attributes, we can't write it - // until all of the tests have finished. Instead of writing every result as they come in, we add - // them to a Vec and write them all at once when run is complete. - let duration = exec_time.map(|t| t.0).unwrap_or_default(); - self.results.push((desc.clone(), result.clone(), duration, stdout.to_vec())); - Ok(()) - } - fn write_run_finish(&mut self, state: &ConsoleTestState) -> io::Result { - self.write_message("")?; - - self.write_message(&format!( - "", - state.failed, state.total, state.ignored - ))?; - for (desc, result, duration, stdout) in std::mem::take(&mut self.results) { - let (class_name, test_name) = parse_class_name(&desc); - match result { - TestResult::TrIgnored => { /* no-op */ } - TestResult::TrFailed => { - self.write_message(&format!( - "", - class_name, - test_name, - duration.as_secs_f64() - ))?; - self.write_message("")?; - if !stdout.is_empty() { - self.write_message("")?; - self.write_message(&str_to_cdata(&String::from_utf8_lossy(&stdout)))?; - self.write_message("")?; - } - self.write_message("")?; - } - - TestResult::TrFailedMsg(ref m) => { - self.write_message(&format!( - "", - class_name, - test_name, - duration.as_secs_f64() - ))?; - self.write_message(&format!(""))?; - if !stdout.is_empty() { - self.write_message("")?; - self.write_message(&str_to_cdata(&String::from_utf8_lossy(&stdout)))?; - self.write_message("")?; - } - self.write_message("")?; - } - - TestResult::TrTimedFail => { - self.write_message(&format!( - "", - class_name, - test_name, - duration.as_secs_f64() - ))?; - self.write_message("")?; - self.write_message("")?; - } - - TestResult::TrBench(ref b) => { - self.write_message(&format!( - "", - class_name, test_name, b.ns_iter_summ.sum - ))?; - } - - TestResult::TrOk => { - self.write_message(&format!( - "")?; - } else { - self.write_message(">")?; - self.write_message(&str_to_cdata(&String::from_utf8_lossy(&stdout)))?; - self.write_message("")?; - self.write_message("")?; - } - } - } - } - self.write_message("")?; - self.write_message("")?; - self.write_message("")?; - self.write_message("")?; - - self.out.write_all(b"\n")?; - - Ok(state.failed == 0) - } -} - -fn parse_class_name(desc: &TestDesc) -> (String, String) { - match desc.test_type { - TestType::UnitTest => parse_class_name_unit(desc), - TestType::DocTest => parse_class_name_doc(desc), - TestType::IntegrationTest => parse_class_name_integration(desc), - TestType::Unknown => (String::from("unknown"), String::from(desc.name.as_slice())), - } -} - -fn parse_class_name_unit(desc: &TestDesc) -> (String, String) { - // Module path => classname - // Function name => name - let module_segments: Vec<&str> = desc.name.as_slice().split("::").collect(); - let (class_name, test_name) = match module_segments[..] { - [test] => (String::from("crate"), String::from(test)), - [ref path @ .., test] => (path.join("::"), String::from(test)), - [..] => unreachable!(), - }; - (class_name, test_name) -} - -fn parse_class_name_doc(desc: &TestDesc) -> (String, String) { - // File path => classname - // Line # => test name - let segments: Vec<&str> = desc.name.as_slice().split(" - ").collect(); - let (class_name, test_name) = match segments[..] { - [file, line] => (String::from(file.trim()), String::from(line.trim())), - [..] => unreachable!(), - }; - (class_name, test_name) -} - -fn parse_class_name_integration(desc: &TestDesc) -> (String, String) { - (String::from("integration"), String::from(desc.name.as_slice())) -} diff --git a/library/test/src/formatters/mod.rs b/library/test/src/formatters/mod.rs deleted file mode 100644 index bc6ffebc1d3b2..0000000000000 --- a/library/test/src/formatters/mod.rs +++ /dev/null @@ -1,46 +0,0 @@ -use std::{io, io::prelude::Write}; - -use crate::{ - console::{ConsoleTestDiscoveryState, ConsoleTestState}, - test_result::TestResult, - time, - types::{TestDesc, TestName}, -}; - -mod json; -mod junit; -mod pretty; -mod terse; - -pub(crate) use self::json::JsonFormatter; -pub(crate) use self::junit::JunitFormatter; -pub(crate) use self::pretty::PrettyFormatter; -pub(crate) use self::terse::TerseFormatter; - -pub(crate) trait OutputFormatter { - fn write_discovery_start(&mut self) -> io::Result<()>; - fn write_test_discovered(&mut self, desc: &TestDesc, test_type: &str) -> io::Result<()>; - fn write_discovery_finish(&mut self, state: &ConsoleTestDiscoveryState) -> io::Result<()>; - - fn write_run_start(&mut self, test_count: usize, shuffle_seed: Option) -> io::Result<()>; - fn write_test_start(&mut self, desc: &TestDesc) -> io::Result<()>; - fn write_timeout(&mut self, desc: &TestDesc) -> io::Result<()>; - fn write_result( - &mut self, - desc: &TestDesc, - result: &TestResult, - exec_time: Option<&time::TestExecTime>, - stdout: &[u8], - state: &ConsoleTestState, - ) -> io::Result<()>; - fn write_run_finish(&mut self, state: &ConsoleTestState) -> io::Result; -} - -pub(crate) fn write_stderr_delimiter(test_output: &mut Vec, test_name: &TestName) { - match test_output.last() { - Some(b'\n') => (), - Some(_) => test_output.push(b'\n'), - None => (), - } - writeln!(test_output, "---- {test_name} stderr ----").unwrap(); -} diff --git a/library/test/src/formatters/pretty.rs b/library/test/src/formatters/pretty.rs deleted file mode 100644 index 22654a3400b44..0000000000000 --- a/library/test/src/formatters/pretty.rs +++ /dev/null @@ -1,308 +0,0 @@ -use std::{io, io::prelude::Write}; - -use super::OutputFormatter; -use crate::{ - bench::fmt_bench_samples, - console::{ConsoleTestDiscoveryState, ConsoleTestState, OutputLocation}, - term, - test_result::TestResult, - time, - types::TestDesc, -}; - -pub(crate) struct PrettyFormatter { - out: OutputLocation, - use_color: bool, - time_options: Option, - - /// Number of columns to fill when aligning names - max_name_len: usize, - - is_multithreaded: bool, -} - -impl PrettyFormatter { - pub fn new( - out: OutputLocation, - use_color: bool, - max_name_len: usize, - is_multithreaded: bool, - time_options: Option, - ) -> Self { - PrettyFormatter { out, use_color, max_name_len, is_multithreaded, time_options } - } - - #[cfg(test)] - pub fn output_location(&self) -> &OutputLocation { - &self.out - } - - pub fn write_ok(&mut self) -> io::Result<()> { - self.write_short_result("ok", term::color::GREEN) - } - - pub fn write_failed(&mut self) -> io::Result<()> { - self.write_short_result("FAILED", term::color::RED) - } - - pub fn write_ignored(&mut self, message: Option<&'static str>) -> io::Result<()> { - if let Some(message) = message { - self.write_short_result(&format!("ignored, {message}"), term::color::YELLOW) - } else { - self.write_short_result("ignored", term::color::YELLOW) - } - } - - pub fn write_time_failed(&mut self) -> io::Result<()> { - self.write_short_result("FAILED (time limit exceeded)", term::color::RED) - } - - pub fn write_bench(&mut self) -> io::Result<()> { - self.write_pretty("bench", term::color::CYAN) - } - - pub fn write_short_result( - &mut self, - result: &str, - color: term::color::Color, - ) -> io::Result<()> { - self.write_pretty(result, color) - } - - pub fn write_pretty(&mut self, word: &str, color: term::color::Color) -> io::Result<()> { - match self.out { - OutputLocation::Pretty(ref mut term) => { - if self.use_color { - term.fg(color)?; - } - term.write_all(word.as_bytes())?; - if self.use_color { - term.reset()?; - } - term.flush() - } - OutputLocation::Raw(ref mut stdout) => { - stdout.write_all(word.as_bytes())?; - stdout.flush() - } - } - } - - pub fn write_plain>(&mut self, s: S) -> io::Result<()> { - let s = s.as_ref(); - self.out.write_all(s.as_bytes())?; - self.out.flush() - } - - fn write_time( - &mut self, - desc: &TestDesc, - exec_time: Option<&time::TestExecTime>, - ) -> io::Result<()> { - if let (Some(opts), Some(time)) = (self.time_options, exec_time) { - let time_str = format!(" <{time}>"); - - let color = if self.use_color { - if opts.is_critical(desc, time) { - Some(term::color::RED) - } else if opts.is_warn(desc, time) { - Some(term::color::YELLOW) - } else { - None - } - } else { - None - }; - - match color { - Some(color) => self.write_pretty(&time_str, color)?, - None => self.write_plain(&time_str)?, - } - } - - Ok(()) - } - - fn write_results( - &mut self, - inputs: &Vec<(TestDesc, Vec)>, - results_type: &str, - ) -> io::Result<()> { - let results_out_str = format!("\n{results_type}:\n"); - - self.write_plain(&results_out_str)?; - - let mut results = Vec::new(); - let mut stdouts = String::new(); - for (f, stdout) in inputs { - results.push(f.name.to_string()); - if !stdout.is_empty() { - stdouts.push_str(&format!("---- {} stdout ----\n", f.name)); - let output = String::from_utf8_lossy(stdout); - stdouts.push_str(&output); - stdouts.push('\n'); - } - } - if !stdouts.is_empty() { - self.write_plain("\n")?; - self.write_plain(&stdouts)?; - } - - self.write_plain(&results_out_str)?; - results.sort(); - for name in &results { - self.write_plain(&format!(" {name}\n"))?; - } - Ok(()) - } - - pub fn write_successes(&mut self, state: &ConsoleTestState) -> io::Result<()> { - self.write_results(&state.not_failures, "successes") - } - - pub fn write_failures(&mut self, state: &ConsoleTestState) -> io::Result<()> { - self.write_results(&state.failures, "failures") - } - - pub fn write_time_failures(&mut self, state: &ConsoleTestState) -> io::Result<()> { - self.write_results(&state.time_failures, "failures (time limit exceeded)") - } - - fn write_test_name(&mut self, desc: &TestDesc) -> io::Result<()> { - let name = desc.padded_name(self.max_name_len, desc.name.padding()); - if let Some(test_mode) = desc.test_mode() { - self.write_plain(format!("test {name} - {test_mode} ... "))?; - } else { - self.write_plain(format!("test {name} ... "))?; - } - - Ok(()) - } -} - -impl OutputFormatter for PrettyFormatter { - fn write_discovery_start(&mut self) -> io::Result<()> { - Ok(()) - } - - fn write_test_discovered(&mut self, desc: &TestDesc, test_type: &str) -> io::Result<()> { - self.write_plain(format!("{}: {test_type}\n", desc.name)) - } - - fn write_discovery_finish(&mut self, state: &ConsoleTestDiscoveryState) -> io::Result<()> { - fn plural(count: usize, s: &str) -> String { - match count { - 1 => format!("1 {s}"), - n => format!("{n} {s}s"), - } - } - - if state.tests != 0 || state.benchmarks != 0 { - self.write_plain("\n")?; - } - - self.write_plain(format!( - "{}, {}\n", - plural(state.tests, "test"), - plural(state.benchmarks, "benchmark") - )) - } - - fn write_run_start(&mut self, test_count: usize, shuffle_seed: Option) -> io::Result<()> { - let noun = if test_count != 1 { "tests" } else { "test" }; - let shuffle_seed_msg = if let Some(shuffle_seed) = shuffle_seed { - format!(" (shuffle seed: {shuffle_seed})") - } else { - String::new() - }; - self.write_plain(format!("\nrunning {test_count} {noun}{shuffle_seed_msg}\n")) - } - - fn write_test_start(&mut self, desc: &TestDesc) -> io::Result<()> { - // When running tests concurrently, we should not print - // the test's name as the result will be mis-aligned. - // When running the tests serially, we print the name here so - // that the user can see which test hangs. - if !self.is_multithreaded { - self.write_test_name(desc)?; - } - - Ok(()) - } - - fn write_result( - &mut self, - desc: &TestDesc, - result: &TestResult, - exec_time: Option<&time::TestExecTime>, - _: &[u8], - _: &ConsoleTestState, - ) -> io::Result<()> { - if self.is_multithreaded { - self.write_test_name(desc)?; - } - - match *result { - TestResult::TrOk => self.write_ok()?, - TestResult::TrFailed | TestResult::TrFailedMsg(_) => self.write_failed()?, - TestResult::TrIgnored => self.write_ignored(desc.ignore_message)?, - TestResult::TrBench(ref bs) => { - self.write_bench()?; - self.write_plain(format!(": {}", fmt_bench_samples(bs)))?; - } - TestResult::TrTimedFail => self.write_time_failed()?, - } - - self.write_time(desc, exec_time)?; - self.write_plain("\n") - } - - fn write_timeout(&mut self, desc: &TestDesc) -> io::Result<()> { - self.write_plain(format!( - "test {} has been running for over {} seconds\n", - desc.name, - time::TEST_WARN_TIMEOUT_S - )) - } - - fn write_run_finish(&mut self, state: &ConsoleTestState) -> io::Result { - if state.options.display_output { - self.write_successes(state)?; - } - let success = state.failed == 0; - if !success { - if !state.failures.is_empty() { - self.write_failures(state)?; - } - - if !state.time_failures.is_empty() { - self.write_time_failures(state)?; - } - } - - self.write_plain("\ntest result: ")?; - - if success { - // There's no parallelism at this point so it's safe to use color - self.write_pretty("ok", term::color::GREEN)?; - } else { - self.write_pretty("FAILED", term::color::RED)?; - } - - let s = format!( - ". {} passed; {} failed; {} ignored; {} measured; {} filtered out", - state.passed, state.failed, state.ignored, state.measured, state.filtered_out - ); - - self.write_plain(s)?; - - if let Some(ref exec_time) = state.exec_time { - let time_str = format!("; finished in {exec_time}"); - self.write_plain(time_str)?; - } - - self.write_plain("\n\n")?; - - Ok(success) - } -} diff --git a/library/test/src/formatters/terse.rs b/library/test/src/formatters/terse.rs deleted file mode 100644 index 875c66e5fa32c..0000000000000 --- a/library/test/src/formatters/terse.rs +++ /dev/null @@ -1,301 +0,0 @@ -use std::{io, io::prelude::Write}; - -use super::OutputFormatter; -use crate::{ - bench::fmt_bench_samples, - console::{ConsoleTestDiscoveryState, ConsoleTestState, OutputLocation}, - term, - test_result::TestResult, - time, - types::NamePadding, - types::TestDesc, -}; - -// We insert a '\n' when the output hits 100 columns in quiet mode. 88 test -// result chars leaves 12 chars for a progress count like " 11704/12853". -const QUIET_MODE_MAX_COLUMN: usize = 88; - -pub(crate) struct TerseFormatter { - out: OutputLocation, - use_color: bool, - is_multithreaded: bool, - /// Number of columns to fill when aligning names - max_name_len: usize, - - test_count: usize, - test_column: usize, - total_test_count: usize, -} - -impl TerseFormatter { - pub fn new( - out: OutputLocation, - use_color: bool, - max_name_len: usize, - is_multithreaded: bool, - ) -> Self { - TerseFormatter { - out, - use_color, - max_name_len, - is_multithreaded, - test_count: 0, - test_column: 0, - total_test_count: 0, // initialized later, when write_run_start is called - } - } - - pub fn write_ok(&mut self) -> io::Result<()> { - self.write_short_result(".", term::color::GREEN) - } - - pub fn write_failed(&mut self, name: &str) -> io::Result<()> { - // Put failed tests on their own line and include the test name, so that it's faster - // to see which test failed without having to wait for them all to run. - - // normally, we write the progress unconditionally, even if the previous line was cut short. - // but if this is the very first column, no short results will have been printed and we'll end up with *only* the progress on the line. - // avoid this. - if self.test_column != 0 { - self.write_progress()?; - } - self.test_count += 1; - self.write_plain(format!("{name} --- "))?; - self.write_pretty("FAILED", term::color::RED)?; - self.write_plain("\n") - } - - pub fn write_ignored(&mut self) -> io::Result<()> { - self.write_short_result("i", term::color::YELLOW) - } - - pub fn write_bench(&mut self) -> io::Result<()> { - self.write_pretty("bench", term::color::CYAN) - } - - pub fn write_short_result( - &mut self, - result: &str, - color: term::color::Color, - ) -> io::Result<()> { - self.write_pretty(result, color)?; - self.test_count += 1; - self.test_column += 1; - if self.test_column % QUIET_MODE_MAX_COLUMN == QUIET_MODE_MAX_COLUMN - 1 { - // We insert a new line regularly in order to flush the - // screen when dealing with line-buffered output (e.g., piping to - // `stamp` in the Rust CI). - self.write_progress()?; - } - - Ok(()) - } - - fn write_progress(&mut self) -> io::Result<()> { - let out = format!(" {}/{}\n", self.test_count, self.total_test_count); - self.write_plain(out)?; - self.test_column = 0; - Ok(()) - } - - pub fn write_pretty(&mut self, word: &str, color: term::color::Color) -> io::Result<()> { - match self.out { - OutputLocation::Pretty(ref mut term) => { - if self.use_color { - term.fg(color)?; - } - term.write_all(word.as_bytes())?; - if self.use_color { - term.reset()?; - } - term.flush() - } - OutputLocation::Raw(ref mut stdout) => { - stdout.write_all(word.as_bytes())?; - stdout.flush() - } - } - } - - pub fn write_plain>(&mut self, s: S) -> io::Result<()> { - let s = s.as_ref(); - self.out.write_all(s.as_bytes())?; - self.out.flush() - } - - pub fn write_outputs(&mut self, state: &ConsoleTestState) -> io::Result<()> { - self.write_plain("\nsuccesses:\n")?; - let mut successes = Vec::new(); - let mut stdouts = String::new(); - for (f, stdout) in &state.not_failures { - successes.push(f.name.to_string()); - if !stdout.is_empty() { - stdouts.push_str(&format!("---- {} stdout ----\n", f.name)); - let output = String::from_utf8_lossy(stdout); - stdouts.push_str(&output); - stdouts.push('\n'); - } - } - if !stdouts.is_empty() { - self.write_plain("\n")?; - self.write_plain(&stdouts)?; - } - - self.write_plain("\nsuccesses:\n")?; - successes.sort(); - for name in &successes { - self.write_plain(&format!(" {name}\n"))?; - } - Ok(()) - } - - pub fn write_failures(&mut self, state: &ConsoleTestState) -> io::Result<()> { - self.write_plain("\nfailures:\n")?; - let mut failures = Vec::new(); - let mut fail_out = String::new(); - for (f, stdout) in &state.failures { - failures.push(f.name.to_string()); - if !stdout.is_empty() { - fail_out.push_str(&format!("---- {} stdout ----\n", f.name)); - let output = String::from_utf8_lossy(stdout); - fail_out.push_str(&output); - fail_out.push('\n'); - } - } - if !fail_out.is_empty() { - self.write_plain("\n")?; - self.write_plain(&fail_out)?; - } - - self.write_plain("\nfailures:\n")?; - failures.sort(); - for name in &failures { - self.write_plain(&format!(" {name}\n"))?; - } - Ok(()) - } - - fn write_test_name(&mut self, desc: &TestDesc) -> io::Result<()> { - let name = desc.padded_name(self.max_name_len, desc.name.padding()); - if let Some(test_mode) = desc.test_mode() { - self.write_plain(format!("test {name} - {test_mode} ... "))?; - } else { - self.write_plain(format!("test {name} ... "))?; - } - - Ok(()) - } -} - -impl OutputFormatter for TerseFormatter { - fn write_discovery_start(&mut self) -> io::Result<()> { - Ok(()) - } - - fn write_test_discovered(&mut self, desc: &TestDesc, test_type: &str) -> io::Result<()> { - self.write_plain(format!("{}: {test_type}\n", desc.name)) - } - - fn write_discovery_finish(&mut self, _state: &ConsoleTestDiscoveryState) -> io::Result<()> { - Ok(()) - } - - fn write_run_start(&mut self, test_count: usize, shuffle_seed: Option) -> io::Result<()> { - self.total_test_count = test_count; - let noun = if test_count != 1 { "tests" } else { "test" }; - let shuffle_seed_msg = if let Some(shuffle_seed) = shuffle_seed { - format!(" (shuffle seed: {shuffle_seed})") - } else { - String::new() - }; - self.write_plain(format!("\nrunning {test_count} {noun}{shuffle_seed_msg}\n")) - } - - fn write_test_start(&mut self, desc: &TestDesc) -> io::Result<()> { - // Remnants from old libtest code that used the padding value - // in order to indicate benchmarks. - // When running benchmarks, terse-mode should still print their name as if - // it is the Pretty formatter. - if !self.is_multithreaded && desc.name.padding() == NamePadding::PadOnRight { - self.write_test_name(desc)?; - } - - Ok(()) - } - - fn write_result( - &mut self, - desc: &TestDesc, - result: &TestResult, - _: Option<&time::TestExecTime>, - _: &[u8], - _: &ConsoleTestState, - ) -> io::Result<()> { - match *result { - TestResult::TrOk => self.write_ok(), - TestResult::TrFailed | TestResult::TrFailedMsg(_) | TestResult::TrTimedFail => { - self.write_failed(desc.name.as_slice()) - } - TestResult::TrIgnored => self.write_ignored(), - TestResult::TrBench(ref bs) => { - if self.is_multithreaded { - self.write_test_name(desc)?; - } - self.write_bench()?; - self.write_plain(format!(": {}\n", fmt_bench_samples(bs))) - } - } - } - - fn write_timeout(&mut self, desc: &TestDesc) -> io::Result<()> { - self.write_plain(format!( - "test {} has been running for over {} seconds\n", - desc.name, - time::TEST_WARN_TIMEOUT_S - )) - } - - fn write_run_finish(&mut self, state: &ConsoleTestState) -> io::Result { - if state.options.display_output { - self.write_outputs(state)?; - } - let success = state.failed == 0; - if !success { - self.write_failures(state)?; - } - - self.write_plain("\ntest result: ")?; - - if success { - // There's no parallelism at this point so it's safe to use color - self.write_pretty("ok", term::color::GREEN)?; - } else { - self.write_pretty("FAILED", term::color::RED)?; - } - - let s = format!( - ". {} passed; {} failed; {} ignored; {} measured; {} filtered out", - state.passed, state.failed, state.ignored, state.measured, state.filtered_out - ); - - self.write_plain(s)?; - - if let Some(ref exec_time) = state.exec_time { - let time_str = format!("; finished in {exec_time}"); - self.write_plain(time_str)?; - } - - self.write_plain("\n\n")?; - - // Custom handling of cases where there is only 1 test to execute and that test was ignored. - // We want to show more detailed information(why was the test ignored) for investigation purposes. - if self.total_test_count == 1 && state.ignores.len() == 1 { - let test_desc = &state.ignores[0].0; - if let Some(im) = test_desc.ignore_message { - self.write_plain(format!("test: {}, ignore_message: {}\n\n", test_desc.name, im))?; - } - } - - Ok(success) - } -} diff --git a/library/test/src/helpers/concurrency.rs b/library/test/src/helpers/concurrency.rs deleted file mode 100644 index b395adcf885ce..0000000000000 --- a/library/test/src/helpers/concurrency.rs +++ /dev/null @@ -1,14 +0,0 @@ -//! Helper module which helps to determine amount of threads to be used -//! during tests execution. -use std::{env, num::NonZero, thread}; - -pub fn get_concurrency() -> usize { - if let Ok(value) = env::var("RUST_TEST_THREADS") { - match value.parse::>().ok() { - Some(n) => n.get(), - _ => panic!("RUST_TEST_THREADS is `{value}`, should be a positive integer."), - } - } else { - thread::available_parallelism().map(|n| n.get()).unwrap_or(1) - } -} diff --git a/library/test/src/helpers/metrics.rs b/library/test/src/helpers/metrics.rs deleted file mode 100644 index f77a23e6875b2..0000000000000 --- a/library/test/src/helpers/metrics.rs +++ /dev/null @@ -1,50 +0,0 @@ -//! Benchmark metrics. -use std::collections::BTreeMap; - -#[derive(Clone, PartialEq, Debug, Copy)] -pub struct Metric { - value: f64, - noise: f64, -} - -impl Metric { - pub fn new(value: f64, noise: f64) -> Metric { - Metric { value, noise } - } -} - -#[derive(Clone, PartialEq)] -pub struct MetricMap(BTreeMap); - -impl MetricMap { - pub fn new() -> MetricMap { - MetricMap(BTreeMap::new()) - } - - /// Insert a named `value` (+/- `noise`) metric into the map. The value - /// must be non-negative. The `noise` indicates the uncertainty of the - /// metric, which doubles as the "noise range" of acceptable - /// pairwise-regressions on this named value, when comparing from one - /// metric to the next using `compare_to_old`. - /// - /// If `noise` is positive, then it means this metric is of a value - /// you want to see grow smaller, so a change larger than `noise` in the - /// positive direction represents a regression. - /// - /// If `noise` is negative, then it means this metric is of a value - /// you want to see grow larger, so a change larger than `noise` in the - /// negative direction represents a regression. - pub fn insert_metric(&mut self, name: &str, value: f64, noise: f64) { - let m = Metric { value, noise }; - self.0.insert(name.to_owned(), m); - } - - pub fn fmt_metrics(&self) -> String { - let v = self - .0 - .iter() - .map(|(k, v)| format!("{}: {} (+/- {})", *k, v.value, v.noise)) - .collect::>(); - v.join(", ") - } -} diff --git a/library/test/src/helpers/mod.rs b/library/test/src/helpers/mod.rs deleted file mode 100644 index 3c79b90b16754..0000000000000 --- a/library/test/src/helpers/mod.rs +++ /dev/null @@ -1,6 +0,0 @@ -//! Module with common helpers not directly related to tests -//! but used in `libtest`. - -pub mod concurrency; -pub mod metrics; -pub mod shuffle; diff --git a/library/test/src/helpers/shuffle.rs b/library/test/src/helpers/shuffle.rs deleted file mode 100644 index 2ac3bfbd4d6f2..0000000000000 --- a/library/test/src/helpers/shuffle.rs +++ /dev/null @@ -1,66 +0,0 @@ -use crate::cli::TestOpts; -use crate::types::{TestDescAndFn, TestId, TestName}; -use std::hash::{DefaultHasher, Hasher}; -use std::time::{SystemTime, UNIX_EPOCH}; - -pub fn get_shuffle_seed(opts: &TestOpts) -> Option { - opts.shuffle_seed.or_else(|| { - if opts.shuffle { - Some( - SystemTime::now() - .duration_since(UNIX_EPOCH) - .expect("Failed to get system time") - .as_nanos() as u64, - ) - } else { - None - } - }) -} - -pub fn shuffle_tests(shuffle_seed: u64, tests: &mut [(TestId, TestDescAndFn)]) { - let test_names: Vec<&TestName> = tests.iter().map(|test| &test.1.desc.name).collect(); - let test_names_hash = calculate_hash(&test_names); - let mut rng = Rng::new(shuffle_seed, test_names_hash); - shuffle(&mut rng, tests); -} - -// `shuffle` is from `rust-analyzer/src/cli/analysis_stats.rs`. -fn shuffle(rng: &mut Rng, slice: &mut [T]) { - for i in 0..slice.len() { - randomize_first(rng, &mut slice[i..]); - } - - fn randomize_first(rng: &mut Rng, slice: &mut [T]) { - assert!(!slice.is_empty()); - let idx = rng.rand_range(0..slice.len() as u64) as usize; - slice.swap(0, idx); - } -} - -struct Rng { - state: u64, - extra: u64, -} - -impl Rng { - fn new(seed: u64, extra: u64) -> Self { - Self { state: seed, extra } - } - - fn rand_range(&mut self, range: core::ops::Range) -> u64 { - self.rand_u64() % (range.end - range.start) + range.start - } - - fn rand_u64(&mut self) -> u64 { - self.state = calculate_hash(&(self.state, self.extra)); - self.state - } -} - -// `calculate_hash` is from `core/src/hash/mod.rs`. -fn calculate_hash(t: &T) -> u64 { - let mut s = DefaultHasher::new(); - t.hash(&mut s); - s.finish() -} diff --git a/library/test/src/lib.rs b/library/test/src/lib.rs deleted file mode 100644 index 7bd08a0605f83..0000000000000 --- a/library/test/src/lib.rs +++ /dev/null @@ -1,758 +0,0 @@ -//! Support code for rustc's built in unit-test and micro-benchmarking -//! framework. -//! -//! Almost all user code will only be interested in `Bencher` and -//! `black_box`. All other interactions (such as writing tests and -//! benchmarks themselves) should be done via the `#[test]` and -//! `#[bench]` attributes. -//! -//! See the [Testing Chapter](../book/ch11-00-testing.html) of the book for more -//! details. - -// Currently, not much of this is meant for users. It is intended to -// support the simplest interface possible for representing and -// running tests while providing a base that other test frameworks may -// build off of. - -#![unstable(feature = "test", issue = "50297")] -#![doc(test(attr(deny(warnings))))] -#![doc(rust_logo)] -#![feature(rustdoc_internals)] -#![feature(internal_output_capture)] -#![feature(staged_api)] -#![feature(process_exitcode_internals)] -#![feature(panic_can_unwind)] -#![feature(test)] -#![allow(internal_features)] - -// Public reexports -pub use self::bench::{black_box, Bencher}; -pub use self::console::run_tests_console; -pub use self::options::{ColorConfig, Options, OutputFormat, RunIgnored, ShouldPanic}; -pub use self::types::TestName::*; -pub use self::types::*; -pub use self::ColorConfig::*; -pub use cli::TestOpts; - -// Module to be used by rustc to compile tests in libtest -pub mod test { - pub use crate::{ - assert_test_result, - bench::Bencher, - cli::{parse_opts, TestOpts}, - filter_tests, - helpers::metrics::{Metric, MetricMap}, - options::{Options, RunIgnored, RunStrategy, ShouldPanic}, - run_test, test_main, test_main_static, - test_result::{TestResult, TrFailed, TrFailedMsg, TrIgnored, TrOk}, - time::{TestExecTime, TestTimeOptions}, - types::{ - DynTestFn, DynTestName, StaticBenchFn, StaticTestFn, StaticTestName, TestDesc, - TestDescAndFn, TestId, TestName, TestType, - }, - }; -} - -use std::{ - collections::VecDeque, - env, io, - io::prelude::Write, - mem::ManuallyDrop, - panic::{self, catch_unwind, AssertUnwindSafe, PanicInfo}, - process::{self, Command, Termination}, - sync::mpsc::{channel, Sender}, - sync::{Arc, Mutex}, - thread, - time::{Duration, Instant}, -}; - -pub mod bench; -mod cli; -mod console; -mod event; -mod formatters; -mod helpers; -mod options; -pub mod stats; -mod term; -mod test_result; -mod time; -mod types; - -#[cfg(test)] -mod tests; - -use core::any::Any; -use event::{CompletedTest, TestEvent}; -use helpers::concurrency::get_concurrency; -use helpers::shuffle::{get_shuffle_seed, shuffle_tests}; -use options::RunStrategy; -use test_result::*; -use time::TestExecTime; - -// Process exit code to be used to indicate test failures. -const ERROR_EXIT_CODE: i32 = 101; - -const SECONDARY_TEST_INVOKER_VAR: &str = "__RUST_TEST_INVOKE"; -const SECONDARY_TEST_BENCH_BENCHMARKS_VAR: &str = "__RUST_TEST_BENCH_BENCHMARKS"; - -// The default console test runner. It accepts the command line -// arguments and a vector of test_descs. -pub fn test_main(args: &[String], tests: Vec, options: Option) { - let mut opts = match cli::parse_opts(args) { - Some(Ok(o)) => o, - Some(Err(msg)) => { - eprintln!("error: {msg}"); - process::exit(ERROR_EXIT_CODE); - } - None => return, - }; - if let Some(options) = options { - opts.options = options; - } - if opts.list { - if let Err(e) = console::list_tests_console(&opts, tests) { - eprintln!("error: io error when listing tests: {e:?}"); - process::exit(ERROR_EXIT_CODE); - } - } else { - if !opts.nocapture { - // If we encounter a non-unwinding panic, flush any captured output from the current test, - // and stop capturing output to ensure that the non-unwinding panic message is visible. - // We also acquire the locks for both output streams to prevent output from other threads - // from interleaving with the panic message or appearing after it. - let builtin_panic_hook = panic::take_hook(); - let hook = Box::new({ - move |info: &'_ PanicInfo<'_>| { - if !info.can_unwind() { - std::mem::forget(std::io::stderr().lock()); - let mut stdout = ManuallyDrop::new(std::io::stdout().lock()); - if let Some(captured) = io::set_output_capture(None) { - if let Ok(data) = captured.lock() { - let _ = stdout.write_all(&data); - let _ = stdout.flush(); - } - } - } - builtin_panic_hook(info); - } - }); - panic::set_hook(hook); - } - let res = console::run_tests_console(&opts, tests); - // Prevent Valgrind from reporting reachable blocks in users' unit tests. - drop(panic::take_hook()); - match res { - Ok(true) => {} - Ok(false) => process::exit(ERROR_EXIT_CODE), - Err(e) => { - eprintln!("error: io error when listing tests: {e:?}"); - process::exit(ERROR_EXIT_CODE); - } - } - } -} - -/// A variant optimized for invocation with a static test vector. -/// This will panic (intentionally) when fed any dynamic tests. -/// -/// This is the entry point for the main function generated by `rustc --test` -/// when panic=unwind. -pub fn test_main_static(tests: &[&TestDescAndFn]) { - let args = env::args().collect::>(); - let owned_tests: Vec<_> = tests.iter().map(make_owned_test).collect(); - test_main(&args, owned_tests, None) -} - -/// A variant optimized for invocation with a static test vector. -/// This will panic (intentionally) when fed any dynamic tests. -/// -/// Runs tests in panic=abort mode, which involves spawning subprocesses for -/// tests. -/// -/// This is the entry point for the main function generated by `rustc --test` -/// when panic=abort. -pub fn test_main_static_abort(tests: &[&TestDescAndFn]) { - // If we're being run in SpawnedSecondary mode, run the test here. run_test - // will then exit the process. - if let Ok(name) = env::var(SECONDARY_TEST_INVOKER_VAR) { - env::remove_var(SECONDARY_TEST_INVOKER_VAR); - - // Convert benchmarks to tests if we're not benchmarking. - let mut tests = tests.iter().map(make_owned_test).collect::>(); - if env::var(SECONDARY_TEST_BENCH_BENCHMARKS_VAR).is_ok() { - env::remove_var(SECONDARY_TEST_BENCH_BENCHMARKS_VAR); - } else { - tests = convert_benchmarks_to_tests(tests); - }; - - let test = tests - .into_iter() - .find(|test| test.desc.name.as_slice() == name) - .unwrap_or_else(|| panic!("couldn't find a test with the provided name '{name}'")); - let TestDescAndFn { desc, testfn } = test; - match testfn.into_runnable() { - Runnable::Test(runnable_test) => { - if runnable_test.is_dynamic() { - panic!("only static tests are supported"); - } - run_test_in_spawned_subprocess(desc, runnable_test); - } - Runnable::Bench(_) => { - panic!("benchmarks should not be executed into child processes") - } - } - } - - let args = env::args().collect::>(); - let owned_tests: Vec<_> = tests.iter().map(make_owned_test).collect(); - test_main(&args, owned_tests, Some(Options::new().panic_abort(true))) -} - -/// Clones static values for putting into a dynamic vector, which test_main() -/// needs to hand out ownership of tests to parallel test runners. -/// -/// This will panic when fed any dynamic tests, because they cannot be cloned. -fn make_owned_test(test: &&TestDescAndFn) -> TestDescAndFn { - match test.testfn { - StaticTestFn(f) => TestDescAndFn { testfn: StaticTestFn(f), desc: test.desc.clone() }, - StaticBenchFn(f) => TestDescAndFn { testfn: StaticBenchFn(f), desc: test.desc.clone() }, - _ => panic!("non-static tests passed to test::test_main_static"), - } -} - -/// Invoked when unit tests terminate. Returns `Result::Err` if the test is -/// considered a failure. By default, invokes `report()` and checks for a `0` -/// result. -pub fn assert_test_result(result: T) -> Result<(), String> { - let code = result.report().to_i32(); - if code == 0 { - Ok(()) - } else { - Err(format!( - "the test returned a termination value with a non-zero status code \ - ({code}) which indicates a failure" - )) - } -} - -struct FilteredTests { - tests: Vec<(TestId, TestDescAndFn)>, - benches: Vec<(TestId, TestDescAndFn)>, - next_id: usize, -} - -impl FilteredTests { - fn add_bench(&mut self, desc: TestDesc, testfn: TestFn) { - let test = TestDescAndFn { desc, testfn }; - self.benches.push((TestId(self.next_id), test)); - self.next_id += 1; - } - fn add_test(&mut self, desc: TestDesc, testfn: TestFn) { - let test = TestDescAndFn { desc, testfn }; - self.tests.push((TestId(self.next_id), test)); - self.next_id += 1; - } - fn total_len(&self) -> usize { - self.tests.len() + self.benches.len() - } -} - -pub fn run_tests( - opts: &TestOpts, - tests: Vec, - mut notify_about_test_event: F, -) -> io::Result<()> -where - F: FnMut(TestEvent) -> io::Result<()>, -{ - use std::collections::HashMap; - use std::hash::{BuildHasherDefault, DefaultHasher}; - use std::sync::mpsc::RecvTimeoutError; - - struct RunningTest { - join_handle: Option>, - } - - impl RunningTest { - fn join(self, completed_test: &mut CompletedTest) { - if let Some(join_handle) = self.join_handle { - if let Err(_) = join_handle.join() { - if let TrOk = completed_test.result { - completed_test.result = - TrFailedMsg("panicked after reporting success".to_string()); - } - } - } - } - } - - // Use a deterministic hasher - type TestMap = HashMap>; - - struct TimeoutEntry { - id: TestId, - desc: TestDesc, - timeout: Instant, - } - - let tests_len = tests.len(); - - let mut filtered = FilteredTests { tests: Vec::new(), benches: Vec::new(), next_id: 0 }; - - let mut filtered_tests = filter_tests(opts, tests); - if !opts.bench_benchmarks { - filtered_tests = convert_benchmarks_to_tests(filtered_tests); - } - - for test in filtered_tests { - let mut desc = test.desc; - desc.name = desc.name.with_padding(test.testfn.padding()); - - match test.testfn { - DynBenchFn(_) | StaticBenchFn(_) => { - filtered.add_bench(desc, test.testfn); - } - testfn => { - filtered.add_test(desc, testfn); - } - }; - } - - let filtered_out = tests_len - filtered.total_len(); - let event = TestEvent::TeFilteredOut(filtered_out); - notify_about_test_event(event)?; - - let shuffle_seed = get_shuffle_seed(opts); - - let event = TestEvent::TeFiltered(filtered.total_len(), shuffle_seed); - notify_about_test_event(event)?; - - let concurrency = opts.test_threads.unwrap_or_else(get_concurrency); - - let mut remaining = filtered.tests; - if let Some(shuffle_seed) = shuffle_seed { - shuffle_tests(shuffle_seed, &mut remaining); - } - // Store the tests in a VecDeque so we can efficiently remove the first element to run the - // tests in the order they were passed (unless shuffled). - let mut remaining = VecDeque::from(remaining); - let mut pending = 0; - - let (tx, rx) = channel::(); - let run_strategy = if opts.options.panic_abort && !opts.force_run_in_process { - RunStrategy::SpawnPrimary - } else { - RunStrategy::InProcess - }; - - let mut running_tests: TestMap = HashMap::default(); - let mut timeout_queue: VecDeque = VecDeque::new(); - - fn get_timed_out_tests( - running_tests: &TestMap, - timeout_queue: &mut VecDeque, - ) -> Vec { - let now = Instant::now(); - let mut timed_out = Vec::new(); - while let Some(timeout_entry) = timeout_queue.front() { - if now < timeout_entry.timeout { - break; - } - let timeout_entry = timeout_queue.pop_front().unwrap(); - if running_tests.contains_key(&timeout_entry.id) { - timed_out.push(timeout_entry.desc); - } - } - timed_out - } - - fn calc_timeout(timeout_queue: &VecDeque) -> Option { - timeout_queue.front().map(|&TimeoutEntry { timeout: next_timeout, .. }| { - let now = Instant::now(); - if next_timeout >= now { next_timeout - now } else { Duration::new(0, 0) } - }) - } - - if concurrency == 1 { - while !remaining.is_empty() { - let (id, test) = remaining.pop_front().unwrap(); - let event = TestEvent::TeWait(test.desc.clone()); - notify_about_test_event(event)?; - let join_handle = run_test(opts, !opts.run_tests, id, test, run_strategy, tx.clone()); - // Wait for the test to complete. - let mut completed_test = rx.recv().unwrap(); - RunningTest { join_handle }.join(&mut completed_test); - - let fail_fast = match completed_test.result { - TrIgnored | TrOk | TrBench(_) => false, - TrFailed | TrFailedMsg(_) | TrTimedFail => opts.fail_fast, - }; - - let event = TestEvent::TeResult(completed_test); - notify_about_test_event(event)?; - - if fail_fast { - return Ok(()); - } - } - } else { - while pending > 0 || !remaining.is_empty() { - while pending < concurrency && !remaining.is_empty() { - let (id, test) = remaining.pop_front().unwrap(); - let timeout = time::get_default_test_timeout(); - let desc = test.desc.clone(); - - let event = TestEvent::TeWait(desc.clone()); - notify_about_test_event(event)?; //here no pad - let join_handle = - run_test(opts, !opts.run_tests, id, test, run_strategy, tx.clone()); - running_tests.insert(id, RunningTest { join_handle }); - timeout_queue.push_back(TimeoutEntry { id, desc, timeout }); - pending += 1; - } - - let mut res; - loop { - if let Some(timeout) = calc_timeout(&timeout_queue) { - res = rx.recv_timeout(timeout); - for test in get_timed_out_tests(&running_tests, &mut timeout_queue) { - let event = TestEvent::TeTimeout(test); - notify_about_test_event(event)?; - } - - match res { - Err(RecvTimeoutError::Timeout) => { - // Result is not yet ready, continue waiting. - } - _ => { - // We've got a result, stop the loop. - break; - } - } - } else { - res = rx.recv().map_err(|_| RecvTimeoutError::Disconnected); - break; - } - } - - let mut completed_test = res.unwrap(); - let running_test = running_tests.remove(&completed_test.id).unwrap(); - running_test.join(&mut completed_test); - - let fail_fast = match completed_test.result { - TrIgnored | TrOk | TrBench(_) => false, - TrFailed | TrFailedMsg(_) | TrTimedFail => opts.fail_fast, - }; - - let event = TestEvent::TeResult(completed_test); - notify_about_test_event(event)?; - pending -= 1; - - if fail_fast { - // Prevent remaining test threads from panicking - std::mem::forget(rx); - return Ok(()); - } - } - } - - if opts.bench_benchmarks { - // All benchmarks run at the end, in serial. - for (id, b) in filtered.benches { - let event = TestEvent::TeWait(b.desc.clone()); - notify_about_test_event(event)?; - let join_handle = run_test(opts, false, id, b, run_strategy, tx.clone()); - // Wait for the test to complete. - let mut completed_test = rx.recv().unwrap(); - RunningTest { join_handle }.join(&mut completed_test); - - let event = TestEvent::TeResult(completed_test); - notify_about_test_event(event)?; - } - } - Ok(()) -} - -pub fn filter_tests(opts: &TestOpts, tests: Vec) -> Vec { - let mut filtered = tests; - let matches_filter = |test: &TestDescAndFn, filter: &str| { - let test_name = test.desc.name.as_slice(); - - match opts.filter_exact { - true => test_name == filter, - false => test_name.contains(filter), - } - }; - - // Remove tests that don't match the test filter - if !opts.filters.is_empty() { - filtered.retain(|test| opts.filters.iter().any(|filter| matches_filter(test, filter))); - } - - // Skip tests that match any of the skip filters - if !opts.skip.is_empty() { - filtered.retain(|test| !opts.skip.iter().any(|sf| matches_filter(test, sf))); - } - - // Excludes #[should_panic] tests - if opts.exclude_should_panic { - filtered.retain(|test| test.desc.should_panic == ShouldPanic::No); - } - - // maybe unignore tests - match opts.run_ignored { - RunIgnored::Yes => { - filtered.iter_mut().for_each(|test| test.desc.ignore = false); - } - RunIgnored::Only => { - filtered.retain(|test| test.desc.ignore); - filtered.iter_mut().for_each(|test| test.desc.ignore = false); - } - RunIgnored::No => {} - } - - filtered -} - -pub fn convert_benchmarks_to_tests(tests: Vec) -> Vec { - // convert benchmarks to tests, if we're not benchmarking them - tests - .into_iter() - .map(|x| { - let testfn = match x.testfn { - DynBenchFn(benchfn) => DynBenchAsTestFn(benchfn), - StaticBenchFn(benchfn) => StaticBenchAsTestFn(benchfn), - f => f, - }; - TestDescAndFn { desc: x.desc, testfn } - }) - .collect() -} - -pub fn run_test( - opts: &TestOpts, - force_ignore: bool, - id: TestId, - test: TestDescAndFn, - strategy: RunStrategy, - monitor_ch: Sender, -) -> Option> { - let TestDescAndFn { desc, testfn } = test; - - // Emscripten can catch panics but other wasm targets cannot - let ignore_because_no_process_support = desc.should_panic != ShouldPanic::No - && (cfg!(target_family = "wasm") || cfg!(target_os = "zkvm")) - && !cfg!(target_os = "emscripten"); - - if force_ignore || desc.ignore || ignore_because_no_process_support { - let message = CompletedTest::new(id, desc, TrIgnored, None, Vec::new()); - monitor_ch.send(message).unwrap(); - return None; - } - - match testfn.into_runnable() { - Runnable::Test(runnable_test) => { - if runnable_test.is_dynamic() { - match strategy { - RunStrategy::InProcess => (), - _ => panic!("Cannot run dynamic test fn out-of-process"), - }; - } - - let name = desc.name.clone(); - let nocapture = opts.nocapture; - let time_options = opts.time_options; - let bench_benchmarks = opts.bench_benchmarks; - - let runtest = move || match strategy { - RunStrategy::InProcess => run_test_in_process( - id, - desc, - nocapture, - time_options.is_some(), - runnable_test, - monitor_ch, - time_options, - ), - RunStrategy::SpawnPrimary => spawn_test_subprocess( - id, - desc, - nocapture, - time_options.is_some(), - monitor_ch, - time_options, - bench_benchmarks, - ), - }; - - // If the platform is single-threaded we're just going to run - // the test synchronously, regardless of the concurrency - // level. - let supports_threads = !cfg!(target_os = "emscripten") - && !cfg!(target_family = "wasm") - && !cfg!(target_os = "zkvm"); - if supports_threads { - let cfg = thread::Builder::new().name(name.as_slice().to_owned()); - let mut runtest = Arc::new(Mutex::new(Some(runtest))); - let runtest2 = runtest.clone(); - match cfg.spawn(move || runtest2.lock().unwrap().take().unwrap()()) { - Ok(handle) => Some(handle), - Err(e) if e.kind() == io::ErrorKind::WouldBlock => { - // `ErrorKind::WouldBlock` means hitting the thread limit on some - // platforms, so run the test synchronously here instead. - Arc::get_mut(&mut runtest).unwrap().get_mut().unwrap().take().unwrap()(); - None - } - Err(e) => panic!("failed to spawn thread to run test: {e}"), - } - } else { - runtest(); - None - } - } - Runnable::Bench(runnable_bench) => { - // Benchmarks aren't expected to panic, so we run them all in-process. - runnable_bench.run(id, &desc, &monitor_ch, opts.nocapture); - None - } - } -} - -/// Fixed frame used to clean the backtrace with `RUST_BACKTRACE=1`. -#[inline(never)] -fn __rust_begin_short_backtrace T>(f: F) -> T { - let result = f(); - - // prevent this frame from being tail-call optimised away - black_box(result) -} - -fn run_test_in_process( - id: TestId, - desc: TestDesc, - nocapture: bool, - report_time: bool, - runnable_test: RunnableTest, - monitor_ch: Sender, - time_opts: Option, -) { - // Buffer for capturing standard I/O - let data = Arc::new(Mutex::new(Vec::new())); - - if !nocapture { - io::set_output_capture(Some(data.clone())); - } - - let start = report_time.then(Instant::now); - let result = fold_err(catch_unwind(AssertUnwindSafe(|| runnable_test.run()))); - let exec_time = start.map(|start| { - let duration = start.elapsed(); - TestExecTime(duration) - }); - - io::set_output_capture(None); - - let test_result = match result { - Ok(()) => calc_result(&desc, Ok(()), &time_opts, &exec_time), - Err(e) => calc_result(&desc, Err(e.as_ref()), &time_opts, &exec_time), - }; - let stdout = data.lock().unwrap_or_else(|e| e.into_inner()).to_vec(); - let message = CompletedTest::new(id, desc, test_result, exec_time, stdout); - monitor_ch.send(message).unwrap(); -} - -fn fold_err( - result: Result, Box>, -) -> Result> -where - E: Send + 'static, -{ - match result { - Ok(Err(e)) => Err(Box::new(e)), - Ok(Ok(v)) => Ok(v), - Err(e) => Err(e), - } -} - -fn spawn_test_subprocess( - id: TestId, - desc: TestDesc, - nocapture: bool, - report_time: bool, - monitor_ch: Sender, - time_opts: Option, - bench_benchmarks: bool, -) { - let (result, test_output, exec_time) = (|| { - let args = env::args().collect::>(); - let current_exe = &args[0]; - - let mut command = Command::new(current_exe); - command.env(SECONDARY_TEST_INVOKER_VAR, desc.name.as_slice()); - if bench_benchmarks { - command.env(SECONDARY_TEST_BENCH_BENCHMARKS_VAR, "1"); - } - if nocapture { - command.stdout(process::Stdio::inherit()); - command.stderr(process::Stdio::inherit()); - } - - let start = report_time.then(Instant::now); - let output = match command.output() { - Ok(out) => out, - Err(e) => { - let err = format!("Failed to spawn {} as child for test: {:?}", args[0], e); - return (TrFailed, err.into_bytes(), None); - } - }; - let exec_time = start.map(|start| { - let duration = start.elapsed(); - TestExecTime(duration) - }); - - let std::process::Output { stdout, stderr, status } = output; - let mut test_output = stdout; - formatters::write_stderr_delimiter(&mut test_output, &desc.name); - test_output.extend_from_slice(&stderr); - - let result = get_result_from_exit_code(&desc, status, &time_opts, &exec_time); - (result, test_output, exec_time) - })(); - - let message = CompletedTest::new(id, desc, result, exec_time, test_output); - monitor_ch.send(message).unwrap(); -} - -fn run_test_in_spawned_subprocess(desc: TestDesc, runnable_test: RunnableTest) -> ! { - let builtin_panic_hook = panic::take_hook(); - let record_result = Arc::new(move |panic_info: Option<&'_ PanicInfo<'_>>| { - let test_result = match panic_info { - Some(info) => calc_result(&desc, Err(info.payload()), &None, &None), - None => calc_result(&desc, Ok(()), &None, &None), - }; - - // We don't support serializing TrFailedMsg, so just - // print the message out to stderr. - if let TrFailedMsg(msg) = &test_result { - eprintln!("{msg}"); - } - - if let Some(info) = panic_info { - builtin_panic_hook(info); - } - - if let TrOk = test_result { - process::exit(test_result::TR_OK); - } else { - process::abort(); - } - }); - let record_result2 = record_result.clone(); - panic::set_hook(Box::new(move |info| record_result2(Some(info)))); - if let Err(message) = runnable_test.run() { - panic!("{}", message); - } - record_result(None); - unreachable!("panic=abort callback should have exited the process") -} diff --git a/library/test/src/options.rs b/library/test/src/options.rs deleted file mode 100644 index 3eaad59474a12..0000000000000 --- a/library/test/src/options.rs +++ /dev/null @@ -1,84 +0,0 @@ -//! Enums denoting options for test execution. - -/// Number of times to run a benchmarked function -#[derive(Clone, PartialEq, Eq)] -pub enum BenchMode { - Auto, - Single, -} - -/// Whether test is expected to panic or not -#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)] -pub enum ShouldPanic { - No, - Yes, - YesWithMessage(&'static str), -} - -/// Whether should console output be colored or not -#[derive(Copy, Clone, Default, Debug)] -pub enum ColorConfig { - #[default] - AutoColor, - AlwaysColor, - NeverColor, -} - -/// Format of the test results output -#[derive(Copy, Clone, Debug, Default, PartialEq, Eq)] -pub enum OutputFormat { - /// Verbose output - Pretty, - /// Quiet output - #[default] - Terse, - /// JSON output - Json, - /// JUnit output - Junit, -} - -/// Whether ignored test should be run or not -#[derive(Copy, Clone, Debug, PartialEq, Eq)] -pub enum RunIgnored { - Yes, - No, - /// Run only ignored tests - Only, -} - -#[derive(Clone, Copy)] -pub enum RunStrategy { - /// Runs the test in the current process, and sends the result back over the - /// supplied channel. - InProcess, - - /// Spawns a subprocess to run the test, and sends the result back over the - /// supplied channel. Requires `argv[0]` to exist and point to the binary - /// that's currently running. - SpawnPrimary, -} - -/// Options for the test run defined by the caller (instead of CLI arguments). -/// In case we want to add other options as well, just add them in this struct. -#[derive(Copy, Clone, Debug)] -pub struct Options { - pub display_output: bool, - pub panic_abort: bool, -} - -impl Options { - pub fn new() -> Options { - Options { display_output: false, panic_abort: false } - } - - pub fn display_output(mut self, display_output: bool) -> Options { - self.display_output = display_output; - self - } - - pub fn panic_abort(mut self, panic_abort: bool) -> Options { - self.panic_abort = panic_abort; - self - } -} diff --git a/library/test/src/stats.rs b/library/test/src/stats.rs deleted file mode 100644 index b33b080126131..0000000000000 --- a/library/test/src/stats.rs +++ /dev/null @@ -1,302 +0,0 @@ -#![allow(missing_docs)] - -use std::mem; - -#[cfg(test)] -mod tests; - -fn local_sort(v: &mut [f64]) { - v.sort_by(|x: &f64, y: &f64| x.total_cmp(y)); -} - -/// Trait that provides simple descriptive statistics on a univariate set of numeric samples. -pub trait Stats { - /// Sum of the samples. - /// - /// Note: this method sacrifices performance at the altar of accuracy - /// Depends on IEEE 754 arithmetic guarantees. See proof of correctness at: - /// ["Adaptive Precision Floating-Point Arithmetic and Fast Robust Geometric - /// Predicates"][paper] - /// - /// [paper]: https://www.cs.cmu.edu/~quake-papers/robust-arithmetic.ps - fn sum(&self) -> f64; - - /// Minimum value of the samples. - fn min(&self) -> f64; - - /// Maximum value of the samples. - fn max(&self) -> f64; - - /// Arithmetic mean (average) of the samples: sum divided by sample-count. - /// - /// See: - fn mean(&self) -> f64; - - /// Median of the samples: value separating the lower half of the samples from the higher half. - /// Equal to `self.percentile(50.0)`. - /// - /// See: - fn median(&self) -> f64; - - /// Variance of the samples: bias-corrected mean of the squares of the differences of each - /// sample from the sample mean. Note that this calculates the _sample variance_ rather than the - /// population variance, which is assumed to be unknown. It therefore corrects the `(n-1)/n` - /// bias that would appear if we calculated a population variance, by dividing by `(n-1)` rather - /// than `n`. - /// - /// See: - fn var(&self) -> f64; - - /// Standard deviation: the square root of the sample variance. - /// - /// Note: this is not a robust statistic for non-normal distributions. Prefer the - /// `median_abs_dev` for unknown distributions. - /// - /// See: - fn std_dev(&self) -> f64; - - /// Standard deviation as a percent of the mean value. See `std_dev` and `mean`. - /// - /// Note: this is not a robust statistic for non-normal distributions. Prefer the - /// `median_abs_dev_pct` for unknown distributions. - fn std_dev_pct(&self) -> f64; - - /// Scaled median of the absolute deviations of each sample from the sample median. This is a - /// robust (distribution-agnostic) estimator of sample variability. Use this in preference to - /// `std_dev` if you cannot assume your sample is normally distributed. Note that this is scaled - /// by the constant `1.4826` to allow its use as a consistent estimator for the standard - /// deviation. - /// - /// See: - fn median_abs_dev(&self) -> f64; - - /// Median absolute deviation as a percent of the median. See `median_abs_dev` and `median`. - fn median_abs_dev_pct(&self) -> f64; - - /// Percentile: the value below which `pct` percent of the values in `self` fall. For example, - /// percentile(95.0) will return the value `v` such that 95% of the samples `s` in `self` - /// satisfy `s <= v`. - /// - /// Calculated by linear interpolation between closest ranks. - /// - /// See: - fn percentile(&self, pct: f64) -> f64; - - /// Quartiles of the sample: three values that divide the sample into four equal groups, each - /// with 1/4 of the data. The middle value is the median. See `median` and `percentile`. This - /// function may calculate the 3 quartiles more efficiently than 3 calls to `percentile`, but - /// is otherwise equivalent. - /// - /// See also: - fn quartiles(&self) -> (f64, f64, f64); - - /// Inter-quartile range: the difference between the 25th percentile (1st quartile) and the 75th - /// percentile (3rd quartile). See `quartiles`. - /// - /// See also: - fn iqr(&self) -> f64; -} - -/// Extracted collection of all the summary statistics of a sample set. -#[derive(Debug, Clone, PartialEq, Copy)] -#[allow(missing_docs)] -pub struct Summary { - pub sum: f64, - pub min: f64, - pub max: f64, - pub mean: f64, - pub median: f64, - pub var: f64, - pub std_dev: f64, - pub std_dev_pct: f64, - pub median_abs_dev: f64, - pub median_abs_dev_pct: f64, - pub quartiles: (f64, f64, f64), - pub iqr: f64, -} - -impl Summary { - /// Construct a new summary of a sample set. - pub fn new(samples: &[f64]) -> Summary { - Summary { - sum: samples.sum(), - min: samples.min(), - max: samples.max(), - mean: samples.mean(), - median: samples.median(), - var: samples.var(), - std_dev: samples.std_dev(), - std_dev_pct: samples.std_dev_pct(), - median_abs_dev: samples.median_abs_dev(), - median_abs_dev_pct: samples.median_abs_dev_pct(), - quartiles: samples.quartiles(), - iqr: samples.iqr(), - } - } -} - -impl Stats for [f64] { - // FIXME #11059 handle NaN, inf and overflow - fn sum(&self) -> f64 { - let mut partials = vec![]; - - for &x in self { - let mut x = x; - let mut j = 0; - // This inner loop applies `hi`/`lo` summation to each - // partial so that the list of partial sums remains exact. - for i in 0..partials.len() { - let mut y: f64 = partials[i]; - if x.abs() < y.abs() { - mem::swap(&mut x, &mut y); - } - // Rounded `x+y` is stored in `hi` with round-off stored in - // `lo`. Together `hi+lo` are exactly equal to `x+y`. - let hi = x + y; - let lo = y - (hi - x); - if lo != 0.0 { - partials[j] = lo; - j += 1; - } - x = hi; - } - if j >= partials.len() { - partials.push(x); - } else { - partials[j] = x; - partials.truncate(j + 1); - } - } - let zero: f64 = 0.0; - partials.iter().fold(zero, |p, q| p + *q) - } - - fn min(&self) -> f64 { - assert!(!self.is_empty()); - self.iter().fold(self[0], |p, q| p.min(*q)) - } - - fn max(&self) -> f64 { - assert!(!self.is_empty()); - self.iter().fold(self[0], |p, q| p.max(*q)) - } - - fn mean(&self) -> f64 { - assert!(!self.is_empty()); - self.sum() / (self.len() as f64) - } - - fn median(&self) -> f64 { - self.percentile(50_f64) - } - - fn var(&self) -> f64 { - if self.len() < 2 { - 0.0 - } else { - let mean = self.mean(); - let mut v: f64 = 0.0; - for s in self { - let x = *s - mean; - v += x * x; - } - // N.B., this is _supposed to be_ len-1, not len. If you - // change it back to len, you will be calculating a - // population variance, not a sample variance. - let denom = (self.len() - 1) as f64; - v / denom - } - } - - fn std_dev(&self) -> f64 { - self.var().sqrt() - } - - fn std_dev_pct(&self) -> f64 { - let hundred = 100_f64; - (self.std_dev() / self.mean()) * hundred - } - - fn median_abs_dev(&self) -> f64 { - let med = self.median(); - let abs_devs: Vec = self.iter().map(|&v| (med - v).abs()).collect(); - // This constant is derived by smarter statistics brains than me, but it is - // consistent with how R and other packages treat the MAD. - let number = 1.4826; - abs_devs.median() * number - } - - fn median_abs_dev_pct(&self) -> f64 { - let hundred = 100_f64; - (self.median_abs_dev() / self.median()) * hundred - } - - fn percentile(&self, pct: f64) -> f64 { - let mut tmp = self.to_vec(); - local_sort(&mut tmp); - percentile_of_sorted(&tmp, pct) - } - - fn quartiles(&self) -> (f64, f64, f64) { - let mut tmp = self.to_vec(); - local_sort(&mut tmp); - let first = 25_f64; - let a = percentile_of_sorted(&tmp, first); - let second = 50_f64; - let b = percentile_of_sorted(&tmp, second); - let third = 75_f64; - let c = percentile_of_sorted(&tmp, third); - (a, b, c) - } - - fn iqr(&self) -> f64 { - let (a, _, c) = self.quartiles(); - c - a - } -} - -// Helper function: extract a value representing the `pct` percentile of a sorted sample-set, using -// linear interpolation. If samples are not sorted, return nonsensical value. -fn percentile_of_sorted(sorted_samples: &[f64], pct: f64) -> f64 { - assert!(!sorted_samples.is_empty()); - if sorted_samples.len() == 1 { - return sorted_samples[0]; - } - let zero: f64 = 0.0; - assert!(zero <= pct); - let hundred = 100_f64; - assert!(pct <= hundred); - if pct == hundred { - return sorted_samples[sorted_samples.len() - 1]; - } - let length = (sorted_samples.len() - 1) as f64; - let rank = (pct / hundred) * length; - let lrank = rank.floor(); - let d = rank - lrank; - let n = lrank as usize; - let lo = sorted_samples[n]; - let hi = sorted_samples[n + 1]; - lo + (hi - lo) * d -} - -/// Winsorize a set of samples, replacing values above the `100-pct` percentile -/// and below the `pct` percentile with those percentiles themselves. This is a -/// way of minimizing the effect of outliers, at the cost of biasing the sample. -/// It differs from trimming in that it does not change the number of samples, -/// just changes the values of those that are outliers. -/// -/// See: -pub fn winsorize(samples: &mut [f64], pct: f64) { - let mut tmp = samples.to_vec(); - local_sort(&mut tmp); - let lo = percentile_of_sorted(&tmp, pct); - let hundred = 100_f64; - let hi = percentile_of_sorted(&tmp, hundred - pct); - for samp in samples { - if *samp > hi { - *samp = hi - } else if *samp < lo { - *samp = lo - } - } -} diff --git a/library/test/src/stats/tests.rs b/library/test/src/stats/tests.rs deleted file mode 100644 index 3a6e8401bf1ab..0000000000000 --- a/library/test/src/stats/tests.rs +++ /dev/null @@ -1,591 +0,0 @@ -use super::*; - -extern crate test; -use self::test::test::Bencher; -use std::io; -use std::io::prelude::*; - -// Test vectors generated from R, using the script src/etc/stat-test-vectors.r. - -macro_rules! assert_approx_eq { - ($a: expr, $b: expr) => {{ - let (a, b) = (&$a, &$b); - assert!((*a - *b).abs() < 1.0e-6, "{} is not approximately equal to {}", *a, *b); - }}; -} - -fn check(samples: &[f64], summ: &Summary) { - let summ2 = Summary::new(samples); - - let mut w = io::sink(); - let w = &mut w; - (write!(w, "\n")).unwrap(); - - assert_eq!(summ.sum, summ2.sum); - assert_eq!(summ.min, summ2.min); - assert_eq!(summ.max, summ2.max); - assert_eq!(summ.mean, summ2.mean); - assert_eq!(summ.median, summ2.median); - - // We needed a few more digits to get exact equality on these - // but they're within float epsilon, which is 1.0e-6. - assert_approx_eq!(summ.var, summ2.var); - assert_approx_eq!(summ.std_dev, summ2.std_dev); - assert_approx_eq!(summ.std_dev_pct, summ2.std_dev_pct); - assert_approx_eq!(summ.median_abs_dev, summ2.median_abs_dev); - assert_approx_eq!(summ.median_abs_dev_pct, summ2.median_abs_dev_pct); - - assert_eq!(summ.quartiles, summ2.quartiles); - assert_eq!(summ.iqr, summ2.iqr); -} - -#[test] -fn test_min_max_nan() { - let xs = &[1.0, 2.0, f64::NAN, 3.0, 4.0]; - let summary = Summary::new(xs); - assert_eq!(summary.min, 1.0); - assert_eq!(summary.max, 4.0); -} - -#[test] -fn test_norm2() { - let val = &[958.0000000000, 924.0000000000]; - let summ = &Summary { - sum: 1882.0000000000, - min: 924.0000000000, - max: 958.0000000000, - mean: 941.0000000000, - median: 941.0000000000, - var: 578.0000000000, - std_dev: 24.0416305603, - std_dev_pct: 2.5549022912, - median_abs_dev: 25.2042000000, - median_abs_dev_pct: 2.6784484591, - quartiles: (932.5000000000, 941.0000000000, 949.5000000000), - iqr: 17.0000000000, - }; - check(val, summ); -} -#[test] -fn test_norm10narrow() { - let val = &[ - 966.0000000000, - 985.0000000000, - 1110.0000000000, - 848.0000000000, - 821.0000000000, - 975.0000000000, - 962.0000000000, - 1157.0000000000, - 1217.0000000000, - 955.0000000000, - ]; - let summ = &Summary { - sum: 9996.0000000000, - min: 821.0000000000, - max: 1217.0000000000, - mean: 999.6000000000, - median: 970.5000000000, - var: 16050.7111111111, - std_dev: 126.6914010938, - std_dev_pct: 12.6742097933, - median_abs_dev: 102.2994000000, - median_abs_dev_pct: 10.5408964451, - quartiles: (956.7500000000, 970.5000000000, 1078.7500000000), - iqr: 122.0000000000, - }; - check(val, summ); -} -#[test] -fn test_norm10medium() { - let val = &[ - 954.0000000000, - 1064.0000000000, - 855.0000000000, - 1000.0000000000, - 743.0000000000, - 1084.0000000000, - 704.0000000000, - 1023.0000000000, - 357.0000000000, - 869.0000000000, - ]; - let summ = &Summary { - sum: 8653.0000000000, - min: 357.0000000000, - max: 1084.0000000000, - mean: 865.3000000000, - median: 911.5000000000, - var: 48628.4555555556, - std_dev: 220.5186059170, - std_dev_pct: 25.4846418487, - median_abs_dev: 195.7032000000, - median_abs_dev_pct: 21.4704552935, - quartiles: (771.0000000000, 911.5000000000, 1017.2500000000), - iqr: 246.2500000000, - }; - check(val, summ); -} -#[test] -fn test_norm10wide() { - let val = &[ - 505.0000000000, - 497.0000000000, - 1591.0000000000, - 887.0000000000, - 1026.0000000000, - 136.0000000000, - 1580.0000000000, - 940.0000000000, - 754.0000000000, - 1433.0000000000, - ]; - let summ = &Summary { - sum: 9349.0000000000, - min: 136.0000000000, - max: 1591.0000000000, - mean: 934.9000000000, - median: 913.5000000000, - var: 239208.9888888889, - std_dev: 489.0899599142, - std_dev_pct: 52.3146817750, - median_abs_dev: 611.5725000000, - median_abs_dev_pct: 66.9482758621, - quartiles: (567.2500000000, 913.5000000000, 1331.2500000000), - iqr: 764.0000000000, - }; - check(val, summ); -} -#[test] -fn test_norm25verynarrow() { - let val = &[ - 991.0000000000, - 1018.0000000000, - 998.0000000000, - 1013.0000000000, - 974.0000000000, - 1007.0000000000, - 1014.0000000000, - 999.0000000000, - 1011.0000000000, - 978.0000000000, - 985.0000000000, - 999.0000000000, - 983.0000000000, - 982.0000000000, - 1015.0000000000, - 1002.0000000000, - 977.0000000000, - 948.0000000000, - 1040.0000000000, - 974.0000000000, - 996.0000000000, - 989.0000000000, - 1015.0000000000, - 994.0000000000, - 1024.0000000000, - ]; - let summ = &Summary { - sum: 24926.0000000000, - min: 948.0000000000, - max: 1040.0000000000, - mean: 997.0400000000, - median: 998.0000000000, - var: 393.2066666667, - std_dev: 19.8294393937, - std_dev_pct: 1.9888308788, - median_abs_dev: 22.2390000000, - median_abs_dev_pct: 2.2283567134, - quartiles: (983.0000000000, 998.0000000000, 1013.0000000000), - iqr: 30.0000000000, - }; - check(val, summ); -} -#[test] -fn test_exp10a() { - let val = &[ - 23.0000000000, - 11.0000000000, - 2.0000000000, - 57.0000000000, - 4.0000000000, - 12.0000000000, - 5.0000000000, - 29.0000000000, - 3.0000000000, - 21.0000000000, - ]; - let summ = &Summary { - sum: 167.0000000000, - min: 2.0000000000, - max: 57.0000000000, - mean: 16.7000000000, - median: 11.5000000000, - var: 287.7888888889, - std_dev: 16.9643416875, - std_dev_pct: 101.5828843560, - median_abs_dev: 13.3434000000, - median_abs_dev_pct: 116.0295652174, - quartiles: (4.2500000000, 11.5000000000, 22.5000000000), - iqr: 18.2500000000, - }; - check(val, summ); -} -#[test] -fn test_exp10b() { - let val = &[ - 24.0000000000, - 17.0000000000, - 6.0000000000, - 38.0000000000, - 25.0000000000, - 7.0000000000, - 51.0000000000, - 2.0000000000, - 61.0000000000, - 32.0000000000, - ]; - let summ = &Summary { - sum: 263.0000000000, - min: 2.0000000000, - max: 61.0000000000, - mean: 26.3000000000, - median: 24.5000000000, - var: 383.5666666667, - std_dev: 19.5848580967, - std_dev_pct: 74.4671410520, - median_abs_dev: 22.9803000000, - median_abs_dev_pct: 93.7971428571, - quartiles: (9.5000000000, 24.5000000000, 36.5000000000), - iqr: 27.0000000000, - }; - check(val, summ); -} -#[test] -fn test_exp10c() { - let val = &[ - 71.0000000000, - 2.0000000000, - 32.0000000000, - 1.0000000000, - 6.0000000000, - 28.0000000000, - 13.0000000000, - 37.0000000000, - 16.0000000000, - 36.0000000000, - ]; - let summ = &Summary { - sum: 242.0000000000, - min: 1.0000000000, - max: 71.0000000000, - mean: 24.2000000000, - median: 22.0000000000, - var: 458.1777777778, - std_dev: 21.4050876611, - std_dev_pct: 88.4507754589, - median_abs_dev: 21.4977000000, - median_abs_dev_pct: 97.7168181818, - quartiles: (7.7500000000, 22.0000000000, 35.0000000000), - iqr: 27.2500000000, - }; - check(val, summ); -} -#[test] -fn test_exp25() { - let val = &[ - 3.0000000000, - 24.0000000000, - 1.0000000000, - 19.0000000000, - 7.0000000000, - 5.0000000000, - 30.0000000000, - 39.0000000000, - 31.0000000000, - 13.0000000000, - 25.0000000000, - 48.0000000000, - 1.0000000000, - 6.0000000000, - 42.0000000000, - 63.0000000000, - 2.0000000000, - 12.0000000000, - 108.0000000000, - 26.0000000000, - 1.0000000000, - 7.0000000000, - 44.0000000000, - 25.0000000000, - 11.0000000000, - ]; - let summ = &Summary { - sum: 593.0000000000, - min: 1.0000000000, - max: 108.0000000000, - mean: 23.7200000000, - median: 19.0000000000, - var: 601.0433333333, - std_dev: 24.5161851301, - std_dev_pct: 103.3565983562, - median_abs_dev: 19.2738000000, - median_abs_dev_pct: 101.4410526316, - quartiles: (6.0000000000, 19.0000000000, 31.0000000000), - iqr: 25.0000000000, - }; - check(val, summ); -} -#[test] -fn test_binom25() { - let val = &[ - 18.0000000000, - 17.0000000000, - 27.0000000000, - 15.0000000000, - 21.0000000000, - 25.0000000000, - 17.0000000000, - 24.0000000000, - 25.0000000000, - 24.0000000000, - 26.0000000000, - 26.0000000000, - 23.0000000000, - 15.0000000000, - 23.0000000000, - 17.0000000000, - 18.0000000000, - 18.0000000000, - 21.0000000000, - 16.0000000000, - 15.0000000000, - 31.0000000000, - 20.0000000000, - 17.0000000000, - 15.0000000000, - ]; - let summ = &Summary { - sum: 514.0000000000, - min: 15.0000000000, - max: 31.0000000000, - mean: 20.5600000000, - median: 20.0000000000, - var: 20.8400000000, - std_dev: 4.5650848842, - std_dev_pct: 22.2037202539, - median_abs_dev: 5.9304000000, - median_abs_dev_pct: 29.6520000000, - quartiles: (17.0000000000, 20.0000000000, 24.0000000000), - iqr: 7.0000000000, - }; - check(val, summ); -} -#[test] -fn test_pois25lambda30() { - let val = &[ - 27.0000000000, - 33.0000000000, - 34.0000000000, - 34.0000000000, - 24.0000000000, - 39.0000000000, - 28.0000000000, - 27.0000000000, - 31.0000000000, - 28.0000000000, - 38.0000000000, - 21.0000000000, - 33.0000000000, - 36.0000000000, - 29.0000000000, - 37.0000000000, - 32.0000000000, - 34.0000000000, - 31.0000000000, - 39.0000000000, - 25.0000000000, - 31.0000000000, - 32.0000000000, - 40.0000000000, - 24.0000000000, - ]; - let summ = &Summary { - sum: 787.0000000000, - min: 21.0000000000, - max: 40.0000000000, - mean: 31.4800000000, - median: 32.0000000000, - var: 26.5933333333, - std_dev: 5.1568724372, - std_dev_pct: 16.3814245145, - median_abs_dev: 5.9304000000, - median_abs_dev_pct: 18.5325000000, - quartiles: (28.0000000000, 32.0000000000, 34.0000000000), - iqr: 6.0000000000, - }; - check(val, summ); -} -#[test] -fn test_pois25lambda40() { - let val = &[ - 42.0000000000, - 50.0000000000, - 42.0000000000, - 46.0000000000, - 34.0000000000, - 45.0000000000, - 34.0000000000, - 49.0000000000, - 39.0000000000, - 28.0000000000, - 40.0000000000, - 35.0000000000, - 37.0000000000, - 39.0000000000, - 46.0000000000, - 44.0000000000, - 32.0000000000, - 45.0000000000, - 42.0000000000, - 37.0000000000, - 48.0000000000, - 42.0000000000, - 33.0000000000, - 42.0000000000, - 48.0000000000, - ]; - let summ = &Summary { - sum: 1019.0000000000, - min: 28.0000000000, - max: 50.0000000000, - mean: 40.7600000000, - median: 42.0000000000, - var: 34.4400000000, - std_dev: 5.8685603004, - std_dev_pct: 14.3978417577, - median_abs_dev: 5.9304000000, - median_abs_dev_pct: 14.1200000000, - quartiles: (37.0000000000, 42.0000000000, 45.0000000000), - iqr: 8.0000000000, - }; - check(val, summ); -} -#[test] -fn test_pois25lambda50() { - let val = &[ - 45.0000000000, - 43.0000000000, - 44.0000000000, - 61.0000000000, - 51.0000000000, - 53.0000000000, - 59.0000000000, - 52.0000000000, - 49.0000000000, - 51.0000000000, - 51.0000000000, - 50.0000000000, - 49.0000000000, - 56.0000000000, - 42.0000000000, - 52.0000000000, - 51.0000000000, - 43.0000000000, - 48.0000000000, - 48.0000000000, - 50.0000000000, - 42.0000000000, - 43.0000000000, - 42.0000000000, - 60.0000000000, - ]; - let summ = &Summary { - sum: 1235.0000000000, - min: 42.0000000000, - max: 61.0000000000, - mean: 49.4000000000, - median: 50.0000000000, - var: 31.6666666667, - std_dev: 5.6273143387, - std_dev_pct: 11.3913245723, - median_abs_dev: 4.4478000000, - median_abs_dev_pct: 8.8956000000, - quartiles: (44.0000000000, 50.0000000000, 52.0000000000), - iqr: 8.0000000000, - }; - check(val, summ); -} -#[test] -fn test_unif25() { - let val = &[ - 99.0000000000, - 55.0000000000, - 92.0000000000, - 79.0000000000, - 14.0000000000, - 2.0000000000, - 33.0000000000, - 49.0000000000, - 3.0000000000, - 32.0000000000, - 84.0000000000, - 59.0000000000, - 22.0000000000, - 86.0000000000, - 76.0000000000, - 31.0000000000, - 29.0000000000, - 11.0000000000, - 41.0000000000, - 53.0000000000, - 45.0000000000, - 44.0000000000, - 98.0000000000, - 98.0000000000, - 7.0000000000, - ]; - let summ = &Summary { - sum: 1242.0000000000, - min: 2.0000000000, - max: 99.0000000000, - mean: 49.6800000000, - median: 45.0000000000, - var: 1015.6433333333, - std_dev: 31.8691595957, - std_dev_pct: 64.1488719719, - median_abs_dev: 45.9606000000, - median_abs_dev_pct: 102.1346666667, - quartiles: (29.0000000000, 45.0000000000, 79.0000000000), - iqr: 50.0000000000, - }; - check(val, summ); -} - -#[test] -fn test_sum_f64s() { - assert_eq!([0.5f64, 3.2321f64, 1.5678f64].sum(), 5.2999); -} -#[test] -fn test_sum_f64_between_ints_that_sum_to_0() { - assert_eq!([1e30f64, 1.2f64, -1e30f64].sum(), 1.2); -} - -#[bench] -pub fn sum_three_items(b: &mut Bencher) { - b.iter(|| { - [1e20f64, 1.5f64, -1e20f64].sum(); - }) -} -#[bench] -pub fn sum_many_f64(b: &mut Bencher) { - let nums = [-1e30f64, 1e60, 1e30, 1.0, -1e60]; - let v = (0..500).map(|i| nums[i % 5]).collect::>(); - - b.iter(|| { - v.sum(); - }) -} - -#[bench] -pub fn no_iter(_: &mut Bencher) {} diff --git a/library/test/src/term.rs b/library/test/src/term.rs deleted file mode 100644 index a14b0d4f5a962..0000000000000 --- a/library/test/src/term.rs +++ /dev/null @@ -1,85 +0,0 @@ -//! Terminal formatting module. -//! -//! This module provides the `Terminal` trait, which abstracts over an [ANSI -//! Terminal][ansi] to provide color printing, among other things. There are two -//! implementations, the `TerminfoTerminal`, which uses control characters from -//! a [terminfo][ti] database, and `WinConsole`, which uses the [Win32 Console -//! API][win]. -//! -//! [ansi]: https://en.wikipedia.org/wiki/ANSI_escape_code -//! [win]: https://docs.microsoft.com/en-us/windows/console/character-mode-applications -//! [ti]: https://en.wikipedia.org/wiki/Terminfo - -#![deny(missing_docs)] - -use std::io::{self, prelude::*}; - -pub(crate) use terminfo::TerminfoTerminal; -#[cfg(windows)] -pub(crate) use win::WinConsole; - -pub(crate) mod terminfo; - -#[cfg(windows)] -mod win; - -/// Alias for stdout terminals. -pub(crate) type StdoutTerminal = dyn Terminal + Send; - -#[cfg(not(windows))] -/// Returns a Terminal wrapping stdout, or None if a terminal couldn't be -/// opened. -pub(crate) fn stdout() -> Option> { - TerminfoTerminal::new(io::stdout()).map(|t| Box::new(t) as Box) -} - -#[cfg(windows)] -/// Returns a Terminal wrapping stdout, or None if a terminal couldn't be -/// opened. -pub(crate) fn stdout() -> Option> { - TerminfoTerminal::new(io::stdout()) - .map(|t| Box::new(t) as Box) - .or_else(|| Some(Box::new(WinConsole::new(io::stdout())) as Box)) -} - -/// Terminal color definitions -#[allow(missing_docs)] -#[cfg_attr(not(windows), allow(dead_code))] -pub(crate) mod color { - /// Number for a terminal color - pub(crate) type Color = u32; - - pub(crate) const BLACK: Color = 0; - pub(crate) const RED: Color = 1; - pub(crate) const GREEN: Color = 2; - pub(crate) const YELLOW: Color = 3; - pub(crate) const BLUE: Color = 4; - pub(crate) const MAGENTA: Color = 5; - pub(crate) const CYAN: Color = 6; - pub(crate) const WHITE: Color = 7; -} - -/// A terminal with similar capabilities to an ANSI Terminal -/// (foreground/background colors etc). -pub trait Terminal: Write { - /// Sets the foreground color to the given color. - /// - /// If the color is a bright color, but the terminal only supports 8 colors, - /// the corresponding normal color will be used instead. - /// - /// Returns `Ok(true)` if the color was set, `Ok(false)` otherwise, and `Err(e)` - /// if there was an I/O error. - fn fg(&mut self, color: color::Color) -> io::Result; - - /// Resets all terminal attributes and colors to their defaults. - /// - /// Returns `Ok(true)` if the terminal was reset, `Ok(false)` otherwise, and `Err(e)` if there - /// was an I/O error. - /// - /// *Note: This does not flush.* - /// - /// That means the reset command may get buffered so, if you aren't planning on doing anything - /// else that might flush stdout's buffer (e.g., writing a line of text), you should flush after - /// calling reset. - fn reset(&mut self) -> io::Result; -} diff --git a/library/test/src/term/terminfo/mod.rs b/library/test/src/term/terminfo/mod.rs deleted file mode 100644 index 67ba89410cd99..0000000000000 --- a/library/test/src/term/terminfo/mod.rs +++ /dev/null @@ -1,205 +0,0 @@ -//! Terminfo database interface. - -use std::collections::HashMap; -use std::env; -use std::error; -use std::fmt; -use std::fs::File; -use std::io::{self, prelude::*, BufReader}; -use std::path::Path; - -use super::color; -use super::Terminal; - -use parm::{expand, Param, Variables}; -use parser::compiled::{msys_terminfo, parse}; -use searcher::get_dbpath_for_term; - -/// A parsed terminfo database entry. -#[allow(unused)] -#[derive(Debug)] -pub(crate) struct TermInfo { - /// Names for the terminal - pub(crate) names: Vec, - /// Map of capability name to boolean value - pub(crate) bools: HashMap, - /// Map of capability name to numeric value - pub(crate) numbers: HashMap, - /// Map of capability name to raw (unexpanded) string - pub(crate) strings: HashMap>, -} - -/// A terminfo creation error. -#[derive(Debug)] -pub(crate) enum Error { - /// TermUnset Indicates that the environment doesn't include enough information to find - /// the terminfo entry. - TermUnset, - /// MalformedTerminfo indicates that parsing the terminfo entry failed. - MalformedTerminfo(String), - /// io::Error forwards any io::Errors encountered when finding or reading the terminfo entry. - IoError(io::Error), -} - -impl error::Error for Error { - fn source(&self) -> Option<&(dyn error::Error + 'static)> { - use Error::*; - match self { - IoError(e) => Some(e), - _ => None, - } - } -} - -impl fmt::Display for Error { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - use Error::*; - match *self { - TermUnset => Ok(()), - MalformedTerminfo(ref e) => e.fmt(f), - IoError(ref e) => e.fmt(f), - } - } -} - -impl TermInfo { - /// Creates a TermInfo based on current environment. - pub(crate) fn from_env() -> Result { - let term = match env::var("TERM") { - Ok(name) => TermInfo::from_name(&name), - Err(..) => return Err(Error::TermUnset), - }; - - if term.is_err() && env::var("MSYSCON").map_or(false, |s| "mintty.exe" == s) { - // msys terminal - Ok(msys_terminfo()) - } else { - term - } - } - - /// Creates a TermInfo for the named terminal. - pub(crate) fn from_name(name: &str) -> Result { - if cfg!(miri) { - // Avoid all the work of parsing the terminfo (it's pretty slow under Miri), and just - // assume that the standard color codes work (like e.g. the 'colored' crate). - return Ok(TermInfo { - names: Default::default(), - bools: Default::default(), - numbers: Default::default(), - strings: Default::default(), - }); - } - - get_dbpath_for_term(name) - .ok_or_else(|| { - Error::IoError(io::Error::new(io::ErrorKind::NotFound, "terminfo file not found")) - }) - .and_then(|p| TermInfo::from_path(&(*p))) - } - - /// Parse the given TermInfo. - pub(crate) fn from_path>(path: P) -> Result { - Self::_from_path(path.as_ref()) - } - // Keep the metadata small - fn _from_path(path: &Path) -> Result { - let file = File::open(path).map_err(Error::IoError)?; - let mut reader = BufReader::new(file); - parse(&mut reader, false).map_err(Error::MalformedTerminfo) - } -} - -pub(crate) mod searcher; - -/// TermInfo format parsing. -pub(crate) mod parser { - //! ncurses-compatible compiled terminfo format parsing (term(5)) - pub(crate) mod compiled; -} -pub(crate) mod parm; - -/// A Terminal that knows how many colors it supports, with a reference to its -/// parsed Terminfo database record. -pub(crate) struct TerminfoTerminal { - num_colors: u32, - out: T, - ti: TermInfo, -} - -impl Terminal for TerminfoTerminal { - fn fg(&mut self, color: color::Color) -> io::Result { - let color = self.dim_if_necessary(color); - if cfg!(miri) && color < 8 { - // The Miri logic for this only works for the most basic 8 colors, which we just assume - // the terminal will support. (`num_colors` is always 0 in Miri, so higher colors will - // just fail. But libtest doesn't use any higher colors anyway.) - return write!(self.out, "\x1B[3{color}m").and(Ok(true)); - } - if self.num_colors > color { - return self.apply_cap("setaf", &[Param::Number(color as i32)]); - } - Ok(false) - } - - fn reset(&mut self) -> io::Result { - if cfg!(miri) { - return write!(self.out, "\x1B[0m").and(Ok(true)); - } - // are there any terminals that have color/attrs and not sgr0? - // Try falling back to sgr, then op - let cmd = match ["sgr0", "sgr", "op"].iter().find_map(|cap| self.ti.strings.get(*cap)) { - Some(op) => match expand(op, &[], &mut Variables::new()) { - Ok(cmd) => cmd, - Err(e) => return Err(io::Error::new(io::ErrorKind::InvalidData, e)), - }, - None => return Ok(false), - }; - self.out.write_all(&cmd).and(Ok(true)) - } -} - -impl TerminfoTerminal { - /// Creates a new TerminfoTerminal with the given TermInfo and Write. - pub(crate) fn new_with_terminfo(out: T, terminfo: TermInfo) -> TerminfoTerminal { - let nc = if terminfo.strings.contains_key("setaf") && terminfo.strings.contains_key("setab") - { - terminfo.numbers.get("colors").map_or(0, |&n| n) - } else { - 0 - }; - - TerminfoTerminal { out, ti: terminfo, num_colors: nc } - } - - /// Creates a new TerminfoTerminal for the current environment with the given Write. - /// - /// Returns `None` when the terminfo cannot be found or parsed. - pub(crate) fn new(out: T) -> Option> { - TermInfo::from_env().map(move |ti| TerminfoTerminal::new_with_terminfo(out, ti)).ok() - } - - fn dim_if_necessary(&self, color: color::Color) -> color::Color { - if color >= self.num_colors && (8..16).contains(&color) { color - 8 } else { color } - } - - fn apply_cap(&mut self, cmd: &str, params: &[Param]) -> io::Result { - match self.ti.strings.get(cmd) { - Some(cmd) => match expand(cmd, params, &mut Variables::new()) { - Ok(s) => self.out.write_all(&s).and(Ok(true)), - Err(e) => Err(io::Error::new(io::ErrorKind::InvalidData, e)), - }, - None => Ok(false), - } - } -} - -impl Write for TerminfoTerminal { - fn write(&mut self, buf: &[u8]) -> io::Result { - self.out.write(buf) - } - - fn flush(&mut self) -> io::Result<()> { - self.out.flush() - } -} diff --git a/library/test/src/term/terminfo/parm.rs b/library/test/src/term/terminfo/parm.rs deleted file mode 100644 index 2815f6cfc77fe..0000000000000 --- a/library/test/src/term/terminfo/parm.rs +++ /dev/null @@ -1,532 +0,0 @@ -//! Parameterized string expansion - -use self::Param::*; -use self::States::*; - -use std::iter::repeat; - -#[cfg(test)] -mod tests; - -#[derive(Clone, Copy, PartialEq)] -enum States { - Nothing, - Percent, - SetVar, - GetVar, - PushParam, - CharConstant, - CharClose, - IntConstant(i32), - FormatPattern(Flags, FormatState), - SeekIfElse(usize), - SeekIfElsePercent(usize), - SeekIfEnd(usize), - SeekIfEndPercent(usize), -} - -#[derive(Copy, PartialEq, Clone)] -enum FormatState { - Flags, - Width, - Precision, -} - -/// Types of parameters a capability can use -#[allow(missing_docs)] -#[derive(Clone)] -pub(crate) enum Param { - Number(i32), -} - -/// Container for static and dynamic variable arrays -pub(crate) struct Variables { - /// Static variables A-Z - sta_va: [Param; 26], - /// Dynamic variables a-z - dyn_va: [Param; 26], -} - -impl Variables { - /// Returns a new zero-initialized Variables - pub(crate) fn new() -> Variables { - Variables { - sta_va: [ - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - ], - dyn_va: [ - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - ], - } - } -} - -/// Expand a parameterized capability -/// -/// # Arguments -/// * `cap` - string to expand -/// * `params` - vector of params for %p1 etc -/// * `vars` - Variables struct for %Pa etc -/// -/// To be compatible with ncurses, `vars` should be the same between calls to `expand` for -/// multiple capabilities for the same terminal. -pub(crate) fn expand( - cap: &[u8], - params: &[Param], - vars: &mut Variables, -) -> Result, String> { - let mut state = Nothing; - - // expanded cap will only rarely be larger than the cap itself - let mut output = Vec::with_capacity(cap.len()); - - let mut stack: Vec = Vec::new(); - - // Copy parameters into a local vector for mutability - let mut mparams = [ - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - Number(0), - ]; - for (dst, src) in mparams.iter_mut().zip(params.iter()) { - *dst = (*src).clone(); - } - - for &c in cap.iter() { - let cur = c as char; - let mut old_state = state; - match state { - Nothing => { - if cur == '%' { - state = Percent; - } else { - output.push(c); - } - } - Percent => { - match cur { - '%' => { - output.push(c); - state = Nothing - } - 'c' => { - match stack.pop() { - // if c is 0, use 0200 (128) for ncurses compatibility - Some(Number(0)) => output.push(128u8), - // Don't check bounds. ncurses just casts and truncates. - Some(Number(c)) => output.push(c as u8), - None => return Err("stack is empty".to_string()), - } - } - 'p' => state = PushParam, - 'P' => state = SetVar, - 'g' => state = GetVar, - '\'' => state = CharConstant, - '{' => state = IntConstant(0), - 'l' => match stack.pop() { - Some(_) => return Err("a non-str was used with %l".to_string()), - None => return Err("stack is empty".to_string()), - }, - '+' | '-' | '/' | '*' | '^' | '&' | '|' | 'm' => { - match (stack.pop(), stack.pop()) { - (Some(Number(y)), Some(Number(x))) => stack.push(Number(match cur { - '+' => x + y, - '-' => x - y, - '*' => x * y, - '/' => x / y, - '|' => x | y, - '&' => x & y, - '^' => x ^ y, - 'm' => x % y, - _ => unreachable!("All cases handled"), - })), - _ => return Err("stack is empty".to_string()), - } - } - '=' | '>' | '<' | 'A' | 'O' => match (stack.pop(), stack.pop()) { - (Some(Number(y)), Some(Number(x))) => stack.push(Number( - if match cur { - '=' => x == y, - '<' => x < y, - '>' => x > y, - 'A' => x > 0 && y > 0, - 'O' => x > 0 || y > 0, - _ => unreachable!(), - } { - 1 - } else { - 0 - }, - )), - _ => return Err("stack is empty".to_string()), - }, - '!' | '~' => match stack.pop() { - Some(Number(x)) => stack.push(Number(match cur { - '!' if x > 0 => 0, - '!' => 1, - '~' => !x, - _ => unreachable!(), - })), - None => return Err("stack is empty".to_string()), - }, - 'i' => match (&mparams[0], &mparams[1]) { - (&Number(x), &Number(y)) => { - mparams[0] = Number(x + 1); - mparams[1] = Number(y + 1); - } - }, - - // printf-style support for %doxXs - 'd' | 'o' | 'x' | 'X' | 's' => { - if let Some(arg) = stack.pop() { - let flags = Flags::new(); - let res = format(arg, FormatOp::from_char(cur), flags)?; - output.extend(res.iter().cloned()); - } else { - return Err("stack is empty".to_string()); - } - } - ':' | '#' | ' ' | '.' | '0'..='9' => { - let mut flags = Flags::new(); - let mut fstate = FormatState::Flags; - match cur { - ':' => (), - '#' => flags.alternate = true, - ' ' => flags.space = true, - '.' => fstate = FormatState::Precision, - '0'..='9' => { - flags.width = cur as usize - '0' as usize; - fstate = FormatState::Width; - } - _ => unreachable!(), - } - state = FormatPattern(flags, fstate); - } - - // conditionals - '?' => (), - 't' => match stack.pop() { - Some(Number(0)) => state = SeekIfElse(0), - Some(Number(_)) => (), - None => return Err("stack is empty".to_string()), - }, - 'e' => state = SeekIfEnd(0), - ';' => (), - _ => return Err(format!("unrecognized format option {cur}")), - } - } - PushParam => { - // params are 1-indexed - stack.push( - mparams[match cur.to_digit(10) { - Some(d) => d as usize - 1, - None => return Err("bad param number".to_string()), - }] - .clone(), - ); - } - SetVar => { - if cur.is_ascii_uppercase() { - if let Some(arg) = stack.pop() { - let idx = (cur as u8) - b'A'; - vars.sta_va[idx as usize] = arg; - } else { - return Err("stack is empty".to_string()); - } - } else if cur.is_ascii_lowercase() { - if let Some(arg) = stack.pop() { - let idx = (cur as u8) - b'a'; - vars.dyn_va[idx as usize] = arg; - } else { - return Err("stack is empty".to_string()); - } - } else { - return Err("bad variable name in %P".to_string()); - } - } - GetVar => { - if cur.is_ascii_uppercase() { - let idx = (cur as u8) - b'A'; - stack.push(vars.sta_va[idx as usize].clone()); - } else if cur.is_ascii_lowercase() { - let idx = (cur as u8) - b'a'; - stack.push(vars.dyn_va[idx as usize].clone()); - } else { - return Err("bad variable name in %g".to_string()); - } - } - CharConstant => { - stack.push(Number(c as i32)); - state = CharClose; - } - CharClose => { - if cur != '\'' { - return Err("malformed character constant".to_string()); - } - } - IntConstant(i) => { - if cur == '}' { - stack.push(Number(i)); - state = Nothing; - } else if let Some(digit) = cur.to_digit(10) { - match i.checked_mul(10).and_then(|i_ten| i_ten.checked_add(digit as i32)) { - Some(i) => { - state = IntConstant(i); - old_state = Nothing; - } - None => return Err("int constant too large".to_string()), - } - } else { - return Err("bad int constant".to_string()); - } - } - FormatPattern(ref mut flags, ref mut fstate) => { - old_state = Nothing; - match (*fstate, cur) { - (_, 'd') | (_, 'o') | (_, 'x') | (_, 'X') | (_, 's') => { - if let Some(arg) = stack.pop() { - let res = format(arg, FormatOp::from_char(cur), *flags)?; - output.extend(res.iter().cloned()); - // will cause state to go to Nothing - old_state = FormatPattern(*flags, *fstate); - } else { - return Err("stack is empty".to_string()); - } - } - (FormatState::Flags, '#') => { - flags.alternate = true; - } - (FormatState::Flags, '-') => { - flags.left = true; - } - (FormatState::Flags, '+') => { - flags.sign = true; - } - (FormatState::Flags, ' ') => { - flags.space = true; - } - (FormatState::Flags, '0'..='9') => { - flags.width = cur as usize - '0' as usize; - *fstate = FormatState::Width; - } - (FormatState::Flags, '.') => { - *fstate = FormatState::Precision; - } - (FormatState::Width, '0'..='9') => { - let old = flags.width; - flags.width = flags.width * 10 + (cur as usize - '0' as usize); - if flags.width < old { - return Err("format width overflow".to_string()); - } - } - (FormatState::Width, '.') => { - *fstate = FormatState::Precision; - } - (FormatState::Precision, '0'..='9') => { - let old = flags.precision; - flags.precision = flags.precision * 10 + (cur as usize - '0' as usize); - if flags.precision < old { - return Err("format precision overflow".to_string()); - } - } - _ => return Err("invalid format specifier".to_string()), - } - } - SeekIfElse(level) => { - if cur == '%' { - state = SeekIfElsePercent(level); - } - old_state = Nothing; - } - SeekIfElsePercent(level) => { - if cur == ';' { - if level == 0 { - state = Nothing; - } else { - state = SeekIfElse(level - 1); - } - } else if cur == 'e' && level == 0 { - state = Nothing; - } else if cur == '?' { - state = SeekIfElse(level + 1); - } else { - state = SeekIfElse(level); - } - } - SeekIfEnd(level) => { - if cur == '%' { - state = SeekIfEndPercent(level); - } - old_state = Nothing; - } - SeekIfEndPercent(level) => { - if cur == ';' { - if level == 0 { - state = Nothing; - } else { - state = SeekIfEnd(level - 1); - } - } else if cur == '?' { - state = SeekIfEnd(level + 1); - } else { - state = SeekIfEnd(level); - } - } - } - if state == old_state { - state = Nothing; - } - } - Ok(output) -} - -#[derive(Copy, PartialEq, Clone)] -struct Flags { - width: usize, - precision: usize, - alternate: bool, - left: bool, - sign: bool, - space: bool, -} - -impl Flags { - fn new() -> Flags { - Flags { width: 0, precision: 0, alternate: false, left: false, sign: false, space: false } - } -} - -#[derive(Copy, Clone)] -enum FormatOp { - Digit, - Octal, - LowerHex, - UpperHex, - String, -} - -impl FormatOp { - fn from_char(c: char) -> FormatOp { - match c { - 'd' => FormatOp::Digit, - 'o' => FormatOp::Octal, - 'x' => FormatOp::LowerHex, - 'X' => FormatOp::UpperHex, - 's' => FormatOp::String, - _ => panic!("bad FormatOp char"), - } - } -} - -fn format(val: Param, op: FormatOp, flags: Flags) -> Result, String> { - let mut s = match val { - Number(d) => { - match op { - FormatOp::Digit => { - if flags.sign { - format!("{:+01$}", d, flags.precision) - } else if d < 0 { - // C doesn't take sign into account in precision calculation. - format!("{:01$}", d, flags.precision + 1) - } else if flags.space { - format!(" {:01$}", d, flags.precision) - } else { - format!("{:01$}", d, flags.precision) - } - } - FormatOp::Octal => { - if flags.alternate { - // Leading octal zero counts against precision. - format!("0{:01$o}", d, flags.precision.saturating_sub(1)) - } else { - format!("{:01$o}", d, flags.precision) - } - } - FormatOp::LowerHex => { - if flags.alternate && d != 0 { - format!("0x{:01$x}", d, flags.precision) - } else { - format!("{:01$x}", d, flags.precision) - } - } - FormatOp::UpperHex => { - if flags.alternate && d != 0 { - format!("0X{:01$X}", d, flags.precision) - } else { - format!("{:01$X}", d, flags.precision) - } - } - FormatOp::String => return Err("non-number on stack with %s".to_string()), - } - .into_bytes() - } - }; - if flags.width > s.len() { - let n = flags.width - s.len(); - if flags.left { - s.extend(repeat(b' ').take(n)); - } else { - let mut s_ = Vec::with_capacity(flags.width); - s_.extend(repeat(b' ').take(n)); - s_.extend(s.into_iter()); - s = s_; - } - } - Ok(s) -} diff --git a/library/test/src/term/terminfo/parm/tests.rs b/library/test/src/term/terminfo/parm/tests.rs deleted file mode 100644 index e785d84f3fd7d..0000000000000 --- a/library/test/src/term/terminfo/parm/tests.rs +++ /dev/null @@ -1,122 +0,0 @@ -use super::*; - -#[test] -fn test_basic_setabf() { - let s = b"\\E[48;5;%p1%dm"; - assert_eq!( - expand(s, &[Number(1)], &mut Variables::new()).unwrap(), - "\\E[48;5;1m".bytes().collect::>() - ); -} - -#[test] -fn test_multiple_int_constants() { - assert_eq!( - expand(b"%{1}%{2}%d%d", &[], &mut Variables::new()).unwrap(), - "21".bytes().collect::>() - ); -} - -#[test] -fn test_op_i() { - let mut vars = Variables::new(); - assert_eq!( - expand(b"%p1%d%p2%d%p3%d%i%p1%d%p2%d%p3%d", &[Number(1), Number(2), Number(3)], &mut vars), - Ok("123233".bytes().collect::>()) - ); - assert_eq!( - expand(b"%p1%d%p2%d%i%p1%d%p2%d", &[], &mut vars), - Ok("0011".bytes().collect::>()) - ); -} - -#[test] -fn test_param_stack_failure_conditions() { - let mut varstruct = Variables::new(); - let vars = &mut varstruct; - fn get_res( - fmt: &str, - cap: &str, - params: &[Param], - vars: &mut Variables, - ) -> Result, String> { - let mut u8v: Vec<_> = fmt.bytes().collect(); - u8v.extend(cap.as_bytes().iter().map(|&b| b)); - expand(&u8v, params, vars) - } - - let caps = ["%d", "%c", "%s", "%Pa", "%l", "%!", "%~"]; - for &cap in caps.iter() { - let res = get_res("", cap, &[], vars); - assert!(res.is_err(), "Op {} succeeded incorrectly with 0 stack entries", cap); - if cap == "%s" || cap == "%l" { - continue; - } - let p = Number(97); - let res = get_res("%p1", cap, &[p], vars); - assert!(res.is_ok(), "Op {} failed with 1 stack entry: {}", cap, res.unwrap_err()); - } - let caps = ["%+", "%-", "%*", "%/", "%m", "%&", "%|", "%A", "%O"]; - for &cap in caps.iter() { - let res = expand(cap.as_bytes(), &[], vars); - assert!(res.is_err(), "Binop {} succeeded incorrectly with 0 stack entries", cap); - let res = get_res("%{1}", cap, &[], vars); - assert!(res.is_err(), "Binop {} succeeded incorrectly with 1 stack entry", cap); - let res = get_res("%{1}%{2}", cap, &[], vars); - assert!(res.is_ok(), "Binop {} failed with 2 stack entries: {}", cap, res.unwrap_err()); - } -} - -#[test] -fn test_push_bad_param() { - assert!(expand(b"%pa", &[], &mut Variables::new()).is_err()); -} - -#[test] -fn test_comparison_ops() { - let v = [('<', [1u8, 0u8, 0u8]), ('=', [0u8, 1u8, 0u8]), ('>', [0u8, 0u8, 1u8])]; - for &(op, bs) in v.iter() { - let s = format!("%{{1}}%{{2}}%{op}%d"); - let res = expand(s.as_bytes(), &[], &mut Variables::new()); - assert!(res.is_ok(), "{}", res.unwrap_err()); - assert_eq!(res.unwrap(), vec![b'0' + bs[0]]); - let s = format!("%{{1}}%{{1}}%{op}%d"); - let res = expand(s.as_bytes(), &[], &mut Variables::new()); - assert!(res.is_ok(), "{}", res.unwrap_err()); - assert_eq!(res.unwrap(), vec![b'0' + bs[1]]); - let s = format!("%{{2}}%{{1}}%{op}%d"); - let res = expand(s.as_bytes(), &[], &mut Variables::new()); - assert!(res.is_ok(), "{}", res.unwrap_err()); - assert_eq!(res.unwrap(), vec![b'0' + bs[2]]); - } -} - -#[test] -fn test_conditionals() { - let mut vars = Variables::new(); - let s = b"\\E[%?%p1%{8}%<%t3%p1%d%e%p1%{16}%<%t9%p1%{8}%-%d%e38;5;%p1%d%;m"; - let res = expand(s, &[Number(1)], &mut vars); - assert!(res.is_ok(), "{}", res.unwrap_err()); - assert_eq!(res.unwrap(), "\\E[31m".bytes().collect::>()); - let res = expand(s, &[Number(8)], &mut vars); - assert!(res.is_ok(), "{}", res.unwrap_err()); - assert_eq!(res.unwrap(), "\\E[90m".bytes().collect::>()); - let res = expand(s, &[Number(42)], &mut vars); - assert!(res.is_ok(), "{}", res.unwrap_err()); - assert_eq!(res.unwrap(), "\\E[38;5;42m".bytes().collect::>()); -} - -#[test] -fn test_format() { - let mut varstruct = Variables::new(); - let vars = &mut varstruct; - - assert_eq!( - expand(b"%p1%d%p1%.3d%p1%5d%p1%:+d", &[Number(1)], vars), - Ok("1001 1+1".bytes().collect::>()) - ); - assert_eq!( - expand(b"%p1%o%p1%#o%p2%6.4x%p2%#6.4X", &[Number(15), Number(27)], vars), - Ok("17017 001b0X001B".bytes().collect::>()) - ); -} diff --git a/library/test/src/term/terminfo/parser/compiled.rs b/library/test/src/term/terminfo/parser/compiled.rs deleted file mode 100644 index 5d40b7988b52d..0000000000000 --- a/library/test/src/term/terminfo/parser/compiled.rs +++ /dev/null @@ -1,336 +0,0 @@ -#![allow(non_upper_case_globals, missing_docs)] - -//! ncurses-compatible compiled terminfo format parsing (term(5)) - -use super::super::TermInfo; -use std::collections::HashMap; -use std::io; -use std::io::prelude::*; - -#[cfg(test)] -mod tests; - -// These are the orders ncurses uses in its compiled format (as of 5.9). Not sure if portable. - -#[rustfmt::skip] -pub(crate) static boolfnames: &[&str] = &["auto_left_margin", "auto_right_margin", - "no_esc_ctlc", "ceol_standout_glitch", "eat_newline_glitch", "erase_overstrike", "generic_type", - "hard_copy", "has_meta_key", "has_status_line", "insert_null_glitch", "memory_above", - "memory_below", "move_insert_mode", "move_standout_mode", "over_strike", "status_line_esc_ok", - "dest_tabs_magic_smso", "tilde_glitch", "transparent_underline", "xon_xoff", "needs_xon_xoff", - "prtr_silent", "hard_cursor", "non_rev_rmcup", "no_pad_char", "non_dest_scroll_region", - "can_change", "back_color_erase", "hue_lightness_saturation", "col_addr_glitch", - "cr_cancels_micro_mode", "has_print_wheel", "row_addr_glitch", "semi_auto_right_margin", - "cpi_changes_res", "lpi_changes_res", "backspaces_with_bs", "crt_no_scrolling", - "no_correctly_working_cr", "gnu_has_meta_key", "linefeed_is_newline", "has_hardware_tabs", - "return_does_clr_eol"]; - -#[rustfmt::skip] -pub(crate) static boolnames: &[&str] = &["bw", "am", "xsb", "xhp", "xenl", "eo", - "gn", "hc", "km", "hs", "in", "db", "da", "mir", "msgr", "os", "eslok", "xt", "hz", "ul", "xon", - "nxon", "mc5i", "chts", "nrrmc", "npc", "ndscr", "ccc", "bce", "hls", "xhpa", "crxm", "daisy", - "xvpa", "sam", "cpix", "lpix", "OTbs", "OTns", "OTnc", "OTMT", "OTNL", "OTpt", "OTxr"]; - -#[rustfmt::skip] -pub(crate) static numfnames: &[&str] = &[ "columns", "init_tabs", "lines", - "lines_of_memory", "magic_cookie_glitch", "padding_baud_rate", "virtual_terminal", - "width_status_line", "num_labels", "label_height", "label_width", "max_attributes", - "maximum_windows", "max_colors", "max_pairs", "no_color_video", "buffer_capacity", - "dot_vert_spacing", "dot_horz_spacing", "max_micro_address", "max_micro_jump", "micro_col_size", - "micro_line_size", "number_of_pins", "output_res_char", "output_res_line", - "output_res_horz_inch", "output_res_vert_inch", "print_rate", "wide_char_size", "buttons", - "bit_image_entwining", "bit_image_type", "magic_cookie_glitch_ul", "carriage_return_delay", - "new_line_delay", "backspace_delay", "horizontal_tab_delay", "number_of_function_keys"]; - -#[rustfmt::skip] -pub(crate) static numnames: &[&str] = &[ "cols", "it", "lines", "lm", "xmc", "pb", - "vt", "wsl", "nlab", "lh", "lw", "ma", "wnum", "colors", "pairs", "ncv", "bufsz", "spinv", - "spinh", "maddr", "mjump", "mcs", "mls", "npins", "orc", "orl", "orhi", "orvi", "cps", "widcs", - "btns", "bitwin", "bitype", "UTug", "OTdC", "OTdN", "OTdB", "OTdT", "OTkn"]; - -#[rustfmt::skip] -pub(crate) static stringfnames: &[&str] = &[ "back_tab", "bell", "carriage_return", - "change_scroll_region", "clear_all_tabs", "clear_screen", "clr_eol", "clr_eos", - "column_address", "command_character", "cursor_address", "cursor_down", "cursor_home", - "cursor_invisible", "cursor_left", "cursor_mem_address", "cursor_normal", "cursor_right", - "cursor_to_ll", "cursor_up", "cursor_visible", "delete_character", "delete_line", - "dis_status_line", "down_half_line", "enter_alt_charset_mode", "enter_blink_mode", - "enter_bold_mode", "enter_ca_mode", "enter_delete_mode", "enter_dim_mode", "enter_insert_mode", - "enter_secure_mode", "enter_protected_mode", "enter_reverse_mode", "enter_standout_mode", - "enter_underline_mode", "erase_chars", "exit_alt_charset_mode", "exit_attribute_mode", - "exit_ca_mode", "exit_delete_mode", "exit_insert_mode", "exit_standout_mode", - "exit_underline_mode", "flash_screen", "form_feed", "from_status_line", "init_1string", - "init_2string", "init_3string", "init_file", "insert_character", "insert_line", - "insert_padding", "key_backspace", "key_catab", "key_clear", "key_ctab", "key_dc", "key_dl", - "key_down", "key_eic", "key_eol", "key_eos", "key_f0", "key_f1", "key_f10", "key_f2", "key_f3", - "key_f4", "key_f5", "key_f6", "key_f7", "key_f8", "key_f9", "key_home", "key_ic", "key_il", - "key_left", "key_ll", "key_npage", "key_ppage", "key_right", "key_sf", "key_sr", "key_stab", - "key_up", "keypad_local", "keypad_xmit", "lab_f0", "lab_f1", "lab_f10", "lab_f2", "lab_f3", - "lab_f4", "lab_f5", "lab_f6", "lab_f7", "lab_f8", "lab_f9", "meta_off", "meta_on", "newline", - "pad_char", "parm_dch", "parm_delete_line", "parm_down_cursor", "parm_ich", "parm_index", - "parm_insert_line", "parm_left_cursor", "parm_right_cursor", "parm_rindex", "parm_up_cursor", - "pkey_key", "pkey_local", "pkey_xmit", "print_screen", "prtr_off", "prtr_on", "repeat_char", - "reset_1string", "reset_2string", "reset_3string", "reset_file", "restore_cursor", - "row_address", "save_cursor", "scroll_forward", "scroll_reverse", "set_attributes", "set_tab", - "set_window", "tab", "to_status_line", "underline_char", "up_half_line", "init_prog", "key_a1", - "key_a3", "key_b2", "key_c1", "key_c3", "prtr_non", "char_padding", "acs_chars", "plab_norm", - "key_btab", "enter_xon_mode", "exit_xon_mode", "enter_am_mode", "exit_am_mode", "xon_character", - "xoff_character", "ena_acs", "label_on", "label_off", "key_beg", "key_cancel", "key_close", - "key_command", "key_copy", "key_create", "key_end", "key_enter", "key_exit", "key_find", - "key_help", "key_mark", "key_message", "key_move", "key_next", "key_open", "key_options", - "key_previous", "key_print", "key_redo", "key_reference", "key_refresh", "key_replace", - "key_restart", "key_resume", "key_save", "key_suspend", "key_undo", "key_sbeg", "key_scancel", - "key_scommand", "key_scopy", "key_screate", "key_sdc", "key_sdl", "key_select", "key_send", - "key_seol", "key_sexit", "key_sfind", "key_shelp", "key_shome", "key_sic", "key_sleft", - "key_smessage", "key_smove", "key_snext", "key_soptions", "key_sprevious", "key_sprint", - "key_sredo", "key_sreplace", "key_sright", "key_srsume", "key_ssave", "key_ssuspend", - "key_sundo", "req_for_input", "key_f11", "key_f12", "key_f13", "key_f14", "key_f15", "key_f16", - "key_f17", "key_f18", "key_f19", "key_f20", "key_f21", "key_f22", "key_f23", "key_f24", - "key_f25", "key_f26", "key_f27", "key_f28", "key_f29", "key_f30", "key_f31", "key_f32", - "key_f33", "key_f34", "key_f35", "key_f36", "key_f37", "key_f38", "key_f39", "key_f40", - "key_f41", "key_f42", "key_f43", "key_f44", "key_f45", "key_f46", "key_f47", "key_f48", - "key_f49", "key_f50", "key_f51", "key_f52", "key_f53", "key_f54", "key_f55", "key_f56", - "key_f57", "key_f58", "key_f59", "key_f60", "key_f61", "key_f62", "key_f63", "clr_bol", - "clear_margins", "set_left_margin", "set_right_margin", "label_format", "set_clock", - "display_clock", "remove_clock", "create_window", "goto_window", "hangup", "dial_phone", - "quick_dial", "tone", "pulse", "flash_hook", "fixed_pause", "wait_tone", "user0", "user1", - "user2", "user3", "user4", "user5", "user6", "user7", "user8", "user9", "orig_pair", - "orig_colors", "initialize_color", "initialize_pair", "set_color_pair", "set_foreground", - "set_background", "change_char_pitch", "change_line_pitch", "change_res_horz", - "change_res_vert", "define_char", "enter_doublewide_mode", "enter_draft_quality", - "enter_italics_mode", "enter_leftward_mode", "enter_micro_mode", "enter_near_letter_quality", - "enter_normal_quality", "enter_shadow_mode", "enter_subscript_mode", "enter_superscript_mode", - "enter_upward_mode", "exit_doublewide_mode", "exit_italics_mode", "exit_leftward_mode", - "exit_micro_mode", "exit_shadow_mode", "exit_subscript_mode", "exit_superscript_mode", - "exit_upward_mode", "micro_column_address", "micro_down", "micro_left", "micro_right", - "micro_row_address", "micro_up", "order_of_pins", "parm_down_micro", "parm_left_micro", - "parm_right_micro", "parm_up_micro", "select_char_set", "set_bottom_margin", - "set_bottom_margin_parm", "set_left_margin_parm", "set_right_margin_parm", "set_top_margin", - "set_top_margin_parm", "start_bit_image", "start_char_set_def", "stop_bit_image", - "stop_char_set_def", "subscript_characters", "superscript_characters", "these_cause_cr", - "zero_motion", "char_set_names", "key_mouse", "mouse_info", "req_mouse_pos", "get_mouse", - "set_a_foreground", "set_a_background", "pkey_plab", "device_type", "code_set_init", - "set0_des_seq", "set1_des_seq", "set2_des_seq", "set3_des_seq", "set_lr_margin", - "set_tb_margin", "bit_image_repeat", "bit_image_newline", "bit_image_carriage_return", - "color_names", "define_bit_image_region", "end_bit_image_region", "set_color_band", - "set_page_length", "display_pc_char", "enter_pc_charset_mode", "exit_pc_charset_mode", - "enter_scancode_mode", "exit_scancode_mode", "pc_term_options", "scancode_escape", - "alt_scancode_esc", "enter_horizontal_hl_mode", "enter_left_hl_mode", "enter_low_hl_mode", - "enter_right_hl_mode", "enter_top_hl_mode", "enter_vertical_hl_mode", "set_a_attributes", - "set_pglen_inch", "termcap_init2", "termcap_reset", "linefeed_if_not_lf", "backspace_if_not_bs", - "other_non_function_keys", "arrow_key_map", "acs_ulcorner", "acs_llcorner", "acs_urcorner", - "acs_lrcorner", "acs_ltee", "acs_rtee", "acs_btee", "acs_ttee", "acs_hline", "acs_vline", - "acs_plus", "memory_lock", "memory_unlock", "box_chars_1"]; - -#[rustfmt::skip] -pub(crate) static stringnames: &[&str] = &[ "cbt", "_", "cr", "csr", "tbc", "clear", - "_", "_", "hpa", "cmdch", "cup", "cud1", "home", "civis", "cub1", "mrcup", "cnorm", "cuf1", - "ll", "cuu1", "cvvis", "dch1", "dl1", "dsl", "hd", "smacs", "blink", "bold", "smcup", "smdc", - "dim", "smir", "invis", "prot", "rev", "smso", "smul", "ech", "rmacs", "sgr0", "rmcup", "rmdc", - "rmir", "rmso", "rmul", "flash", "ff", "fsl", "is1", "is2", "is3", "if", "ich1", "il1", "ip", - "kbs", "ktbc", "kclr", "kctab", "_", "_", "kcud1", "_", "_", "_", "_", "_", "_", "_", "_", "_", - "_", "_", "_", "_", "_", "khome", "_", "_", "kcub1", "_", "knp", "kpp", "kcuf1", "_", "_", - "khts", "_", "rmkx", "smkx", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "rmm", "_", - "_", "pad", "dch", "dl", "cud", "ich", "indn", "il", "cub", "cuf", "rin", "cuu", "pfkey", - "pfloc", "pfx", "mc0", "mc4", "_", "rep", "rs1", "rs2", "rs3", "rf", "rc", "vpa", "sc", "ind", - "ri", "sgr", "_", "wind", "_", "tsl", "uc", "hu", "iprog", "_", "_", "_", "_", "_", "mc5p", - "rmp", "acsc", "pln", "kcbt", "smxon", "rmxon", "smam", "rmam", "xonc", "xoffc", "_", "smln", - "rmln", "_", "kcan", "kclo", "kcmd", "kcpy", "kcrt", "_", "kent", "kext", "kfnd", "khlp", - "kmrk", "kmsg", "kmov", "knxt", "kopn", "kopt", "kprv", "kprt", "krdo", "kref", "krfr", "krpl", - "krst", "kres", "ksav", "kspd", "kund", "kBEG", "kCAN", "kCMD", "kCPY", "kCRT", "_", "_", - "kslt", "kEND", "kEOL", "kEXT", "kFND", "kHLP", "kHOM", "_", "kLFT", "kMSG", "kMOV", "kNXT", - "kOPT", "kPRV", "kPRT", "kRDO", "kRPL", "kRIT", "kRES", "kSAV", "kSPD", "kUND", "rfi", "_", "_", - "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", - "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", - "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", "_", - "dclk", "rmclk", "cwin", "wingo", "_", "dial", "qdial", "_", "_", "hook", "pause", "wait", "_", - "_", "_", "_", "_", "_", "_", "_", "_", "_", "op", "oc", "initc", "initp", "scp", "setf", - "setb", "cpi", "lpi", "chr", "cvr", "defc", "swidm", "sdrfq", "sitm", "slm", "smicm", "snlq", - "snrmq", "sshm", "ssubm", "ssupm", "sum", "rwidm", "ritm", "rlm", "rmicm", "rshm", "rsubm", - "rsupm", "rum", "mhpa", "mcud1", "mcub1", "mcuf1", "mvpa", "mcuu1", "porder", "mcud", "mcub", - "mcuf", "mcuu", "scs", "smgb", "smgbp", "smglp", "smgrp", "smgt", "smgtp", "sbim", "scsd", - "rbim", "rcsd", "subcs", "supcs", "docr", "zerom", "csnm", "kmous", "minfo", "reqmp", "getm", - "setaf", "setab", "pfxl", "devt", "csin", "s0ds", "s1ds", "s2ds", "s3ds", "smglr", "smgtb", - "birep", "binel", "bicr", "colornm", "defbi", "endbi", "setcolor", "slines", "dispc", "smpch", - "rmpch", "smsc", "rmsc", "pctrm", "scesc", "scesa", "ehhlm", "elhlm", "elohlm", "erhlm", - "ethlm", "evhlm", "sgr1", "slength", "OTi2", "OTrs", "OTnl", "OTbs", "OTko", "OTma", "OTG2", - "OTG3", "OTG1", "OTG4", "OTGR", "OTGL", "OTGU", "OTGD", "OTGH", "OTGV", "OTGC", "meml", "memu", - "box1"]; - -fn read_le_u16(r: &mut dyn io::Read) -> io::Result { - let mut b = [0; 2]; - r.read_exact(&mut b)?; - Ok((b[0] as u16) | ((b[1] as u16) << 8)) -} - -fn read_le_u32(r: &mut dyn io::Read) -> io::Result { - let mut b = [0; 4]; - r.read_exact(&mut b)?; - Ok((b[0] as u32) | ((b[1] as u32) << 8) | ((b[2] as u32) << 16) | ((b[3] as u32) << 24)) -} - -fn read_byte(r: &mut dyn io::Read) -> io::Result { - match r.bytes().next() { - Some(s) => s, - None => Err(io::Error::new(io::ErrorKind::Other, "end of file")), - } -} - -/// Parse a compiled terminfo entry, using long capability names if `longnames` -/// is true -pub(crate) fn parse(file: &mut dyn io::Read, longnames: bool) -> Result { - macro_rules! t( ($e:expr) => ( - match $e { - Ok(e) => e, - Err(e) => return Err(e.to_string()) - } - ) ); - - let (bnames, snames, nnames) = if longnames { - (boolfnames, stringfnames, numfnames) - } else { - (boolnames, stringnames, numnames) - }; - - // Check magic number - let magic = t!(read_le_u16(file)); - - let extended = match magic { - 0o0432 => false, - 0o01036 => true, - _ => return Err(format!("invalid magic number, found {magic:o}")), - }; - - // According to the spec, these fields must be >= -1 where -1 means that the feature is not - // supported. Using 0 instead of -1 works because we skip sections with length 0. - macro_rules! read_nonneg { - () => {{ - match t!(read_le_u16(file)) as i16 { - n if n >= 0 => n as usize, - -1 => 0, - _ => return Err("incompatible file: length fields must be >= -1".to_string()), - } - }}; - } - - let names_bytes = read_nonneg!(); - let bools_bytes = read_nonneg!(); - let numbers_count = read_nonneg!(); - let string_offsets_count = read_nonneg!(); - let string_table_bytes = read_nonneg!(); - - if names_bytes == 0 { - return Err("incompatible file: names field must be at least 1 byte wide".to_string()); - } - - if bools_bytes > boolnames.len() { - return Err("incompatible file: more booleans than expected".to_string()); - } - - if numbers_count > numnames.len() { - return Err("incompatible file: more numbers than expected".to_string()); - } - - if string_offsets_count > stringnames.len() { - return Err("incompatible file: more string offsets than expected".to_string()); - } - - // don't read NUL - let mut bytes = Vec::new(); - t!(file.take((names_bytes - 1) as u64).read_to_end(&mut bytes)); - let names_str = match String::from_utf8(bytes) { - Ok(s) => s, - Err(_) => return Err("input not utf-8".to_string()), - }; - - let term_names: Vec = names_str.split('|').map(|s| s.to_string()).collect(); - // consume NUL - if t!(read_byte(file)) != b'\0' { - return Err("incompatible file: missing null terminator for names section".to_string()); - } - - let bools_map: HashMap = t! { - (0..bools_bytes).filter_map(|i| match read_byte(file) { - Err(e) => Some(Err(e)), - Ok(1) => Some(Ok((bnames[i].to_string(), true))), - Ok(_) => None - }).collect() - }; - - if (bools_bytes + names_bytes) % 2 == 1 { - t!(read_byte(file)); // compensate for padding - } - - let numbers_map: HashMap = t! { - (0..numbers_count).filter_map(|i| { - let number = if extended { read_le_u32(file) } else { read_le_u16(file).map(Into::into) }; - - match number { - Ok(0xFFFF) => None, - Ok(n) => Some(Ok((nnames[i].to_string(), n))), - Err(e) => Some(Err(e)) - } - }).collect() - }; - - let string_map: HashMap> = if string_offsets_count > 0 { - let string_offsets: Vec = - t!((0..string_offsets_count).map(|_| read_le_u16(file)).collect()); - - let mut string_table = Vec::new(); - t!(file.take(string_table_bytes as u64).read_to_end(&mut string_table)); - - t!(string_offsets - .into_iter() - .enumerate() - .filter(|&(_, offset)| { - // non-entry - offset != 0xFFFF - }) - .map(|(i, offset)| { - let offset = offset as usize; - - let name = if snames[i] == "_" { stringfnames[i] } else { snames[i] }; - - if offset == 0xFFFE { - // undocumented: FFFE indicates cap@, which means the capability is not present - // unsure if the handling for this is correct - return Ok((name.to_string(), Vec::new())); - } - - // Find the offset of the NUL we want to go to - let nulpos = string_table[offset..string_table_bytes].iter().position(|&b| b == 0); - match nulpos { - Some(len) => { - Ok((name.to_string(), string_table[offset..offset + len].to_vec())) - } - None => Err("invalid file: missing NUL in string_table".to_string()), - } - }) - .collect()) - } else { - HashMap::new() - }; - - // And that's all there is to it - Ok(TermInfo { names: term_names, bools: bools_map, numbers: numbers_map, strings: string_map }) -} - -/// Creates a dummy TermInfo struct for msys terminals -pub(crate) fn msys_terminfo() -> TermInfo { - let mut strings = HashMap::new(); - strings.insert("sgr0".to_string(), b"\x1B[0m".to_vec()); - strings.insert("bold".to_string(), b"\x1B[1m".to_vec()); - strings.insert("setaf".to_string(), b"\x1B[3%p1%dm".to_vec()); - strings.insert("setab".to_string(), b"\x1B[4%p1%dm".to_vec()); - - let mut numbers = HashMap::new(); - numbers.insert("colors".to_string(), 8); - - TermInfo { - names: vec!["cygwin".to_string()], // msys is a fork of an older cygwin version - bools: HashMap::new(), - numbers, - strings, - } -} diff --git a/library/test/src/term/terminfo/parser/compiled/tests.rs b/library/test/src/term/terminfo/parser/compiled/tests.rs deleted file mode 100644 index 8a9187b0495cc..0000000000000 --- a/library/test/src/term/terminfo/parser/compiled/tests.rs +++ /dev/null @@ -1,8 +0,0 @@ -use super::*; - -#[test] -fn test_veclens() { - assert_eq!(boolfnames.len(), boolnames.len()); - assert_eq!(numfnames.len(), numnames.len()); - assert_eq!(stringfnames.len(), stringnames.len()); -} diff --git a/library/test/src/term/terminfo/searcher.rs b/library/test/src/term/terminfo/searcher.rs deleted file mode 100644 index 3e8ccc91ab051..0000000000000 --- a/library/test/src/term/terminfo/searcher.rs +++ /dev/null @@ -1,69 +0,0 @@ -//! ncurses-compatible database discovery. -//! -//! Does not support hashed database, only filesystem! - -use std::env; -use std::fs; -use std::path::PathBuf; - -#[cfg(test)] -mod tests; - -/// Return path to database entry for `term` -#[allow(deprecated)] -pub(crate) fn get_dbpath_for_term(term: &str) -> Option { - let mut dirs_to_search = Vec::new(); - let first_char = term.chars().next()?; - - // Find search directory - if let Some(dir) = env::var_os("TERMINFO") { - dirs_to_search.push(PathBuf::from(dir)); - } - - if let Ok(dirs) = env::var("TERMINFO_DIRS") { - for i in dirs.split(':') { - if i.is_empty() { - dirs_to_search.push(PathBuf::from("/usr/share/terminfo")); - } else { - dirs_to_search.push(PathBuf::from(i)); - } - } - } else { - // Found nothing in TERMINFO_DIRS, use the default paths: - // According to /etc/terminfo/README, after looking at - // ~/.terminfo, ncurses will search /etc/terminfo, then - // /lib/terminfo, and eventually /usr/share/terminfo. - // On Haiku the database can be found at /boot/system/data/terminfo - if let Some(mut homedir) = env::home_dir() { - homedir.push(".terminfo"); - dirs_to_search.push(homedir) - } - - dirs_to_search.push(PathBuf::from("/etc/terminfo")); - dirs_to_search.push(PathBuf::from("/lib/terminfo")); - dirs_to_search.push(PathBuf::from("/usr/share/terminfo")); - dirs_to_search.push(PathBuf::from("/boot/system/data/terminfo")); - } - - // Look for the terminal in all of the search directories - for mut p in dirs_to_search { - if fs::metadata(&p).is_ok() { - p.push(&first_char.to_string()); - p.push(term); - if fs::metadata(&p).is_ok() { - return Some(p); - } - p.pop(); - p.pop(); - - // on some installations the dir is named after the hex of the char - // (e.g., macOS) - p.push(&format!("{:x}", first_char as usize)); - p.push(term); - if fs::metadata(&p).is_ok() { - return Some(p); - } - } - } - None -} diff --git a/library/test/src/term/terminfo/searcher/tests.rs b/library/test/src/term/terminfo/searcher/tests.rs deleted file mode 100644 index e1edd3b25cf4b..0000000000000 --- a/library/test/src/term/terminfo/searcher/tests.rs +++ /dev/null @@ -1,17 +0,0 @@ -use super::*; - -#[test] -#[ignore = "buildbots don't have ncurses installed and I can't mock everything I need"] -fn test_get_dbpath_for_term() { - // woefully inadequate test coverage - // note: current tests won't work with non-standard terminfo hierarchies (e.g., macOS's) - use std::env; - fn x(t: &str) -> PathBuf { - get_dbpath_for_term(t).expect(&format!("no terminfo entry found for {t:?}")) - } - assert_eq!(x("screen"), PathBuf::from("/usr/share/terminfo/s/screen")); - assert_eq!(get_dbpath_for_term(""), None); - env::set_var("TERMINFO_DIRS", ":"); - assert_eq!(x("screen"), PathBuf::from("/usr/share/terminfo/s/screen")); - env::remove_var("TERMINFO_DIRS"); -} diff --git a/library/test/src/term/win.rs b/library/test/src/term/win.rs deleted file mode 100644 index 55020141a827d..0000000000000 --- a/library/test/src/term/win.rs +++ /dev/null @@ -1,169 +0,0 @@ -//! Windows console handling - -// FIXME (#13400): this is only a tiny fraction of the Windows console api - -use std::io; -use std::io::prelude::*; - -use super::color; -use super::Terminal; - -/// A Terminal implementation that uses the Win32 Console API. -pub(crate) struct WinConsole { - buf: T, - def_foreground: color::Color, - def_background: color::Color, - foreground: color::Color, - background: color::Color, -} - -type SHORT = i16; -type WORD = u16; -type DWORD = u32; -type BOOL = i32; -type HANDLE = *mut u8; - -#[allow(non_snake_case)] -#[repr(C)] -struct SMALL_RECT { - Left: SHORT, - Top: SHORT, - Right: SHORT, - Bottom: SHORT, -} - -#[allow(non_snake_case)] -#[repr(C)] -struct COORD { - X: SHORT, - Y: SHORT, -} - -#[allow(non_snake_case)] -#[repr(C)] -struct CONSOLE_SCREEN_BUFFER_INFO { - dwSize: COORD, - dwCursorPosition: COORD, - wAttributes: WORD, - srWindow: SMALL_RECT, - dwMaximumWindowSize: COORD, -} - -#[allow(non_snake_case)] -#[link(name = "kernel32")] -extern "system" { - fn SetConsoleTextAttribute(handle: HANDLE, attr: WORD) -> BOOL; - fn GetStdHandle(which: DWORD) -> HANDLE; - fn GetConsoleScreenBufferInfo(handle: HANDLE, info: *mut CONSOLE_SCREEN_BUFFER_INFO) -> BOOL; -} - -fn color_to_bits(color: color::Color) -> u16 { - // magic numbers from mingw-w64's wincon.h - - let bits = match color % 8 { - color::BLACK => 0, - color::BLUE => 0x1, - color::GREEN => 0x2, - color::RED => 0x4, - color::YELLOW => 0x2 | 0x4, - color::MAGENTA => 0x1 | 0x4, - color::CYAN => 0x1 | 0x2, - color::WHITE => 0x1 | 0x2 | 0x4, - _ => unreachable!(), - }; - - if color >= 8 { bits | 0x8 } else { bits } -} - -fn bits_to_color(bits: u16) -> color::Color { - let color = match bits & 0x7 { - 0 => color::BLACK, - 0x1 => color::BLUE, - 0x2 => color::GREEN, - 0x4 => color::RED, - 0x6 => color::YELLOW, - 0x5 => color::MAGENTA, - 0x3 => color::CYAN, - 0x7 => color::WHITE, - _ => unreachable!(), - }; - - color | (u32::from(bits) & 0x8) // copy the hi-intensity bit -} - -impl WinConsole { - fn apply(&mut self) { - let _unused = self.buf.flush(); - let mut accum: WORD = 0; - accum |= color_to_bits(self.foreground); - accum |= color_to_bits(self.background) << 4; - - unsafe { - // Magic -11 means stdout, from - // https://docs.microsoft.com/en-us/windows/console/getstdhandle - // - // You may be wondering, "but what about stderr?", and the answer - // to that is that setting terminal attributes on the stdout - // handle also sets them for stderr, since they go to the same - // terminal! Admittedly, this is fragile, since stderr could be - // redirected to a different console. This is good enough for - // rustc though. See #13400. - let out = GetStdHandle(-11i32 as DWORD); - SetConsoleTextAttribute(out, accum); - } - } - - pub(crate) fn new(out: T) -> WinConsole { - use std::mem::MaybeUninit; - - let fg; - let bg; - unsafe { - let mut buffer_info = MaybeUninit::::uninit(); - if GetConsoleScreenBufferInfo(GetStdHandle(-11i32 as DWORD), buffer_info.as_mut_ptr()) - != 0 - { - let buffer_info = buffer_info.assume_init(); - fg = bits_to_color(buffer_info.wAttributes); - bg = bits_to_color(buffer_info.wAttributes >> 4); - } else { - fg = color::WHITE; - bg = color::BLACK; - } - } - WinConsole { - buf: out, - def_foreground: fg, - def_background: bg, - foreground: fg, - background: bg, - } - } -} - -impl Write for WinConsole { - fn write(&mut self, buf: &[u8]) -> io::Result { - self.buf.write(buf) - } - - fn flush(&mut self) -> io::Result<()> { - self.buf.flush() - } -} - -impl Terminal for WinConsole { - fn fg(&mut self, color: color::Color) -> io::Result { - self.foreground = color; - self.apply(); - - Ok(true) - } - - fn reset(&mut self) -> io::Result { - self.foreground = self.def_foreground; - self.background = self.def_background; - self.apply(); - - Ok(true) - } -} diff --git a/library/test/src/test_result.rs b/library/test/src/test_result.rs deleted file mode 100644 index bb32c70d66311..0000000000000 --- a/library/test/src/test_result.rs +++ /dev/null @@ -1,129 +0,0 @@ -use std::any::Any; -use std::process::ExitStatus; - -#[cfg(unix)] -use std::os::unix::process::ExitStatusExt; - -use super::bench::BenchSamples; -use super::options::ShouldPanic; -use super::time; -use super::types::TestDesc; - -pub use self::TestResult::*; - -// Return code for secondary process. -// Start somewhere other than 0 so we know the return code means what we think -// it means. -pub const TR_OK: i32 = 50; - -// On Windows we use __fastfail to abort, which is documented to use this -// exception code. -#[cfg(windows)] -const STATUS_ABORTED: i32 = 0xC0000409u32 as i32; - -#[derive(Debug, Clone, PartialEq)] -pub enum TestResult { - TrOk, - TrFailed, - TrFailedMsg(String), - TrIgnored, - TrBench(BenchSamples), - TrTimedFail, -} - -/// Creates a `TestResult` depending on the raw result of test execution -/// and associated data. -pub fn calc_result<'a>( - desc: &TestDesc, - task_result: Result<(), &'a (dyn Any + 'static + Send)>, - time_opts: &Option, - exec_time: &Option, -) -> TestResult { - let result = match (&desc.should_panic, task_result) { - (&ShouldPanic::No, Ok(())) | (&ShouldPanic::Yes, Err(_)) => TestResult::TrOk, - (&ShouldPanic::YesWithMessage(msg), Err(err)) => { - let maybe_panic_str = err - .downcast_ref::() - .map(|e| &**e) - .or_else(|| err.downcast_ref::<&'static str>().copied()); - - if maybe_panic_str.map(|e| e.contains(msg)).unwrap_or(false) { - TestResult::TrOk - } else if let Some(panic_str) = maybe_panic_str { - TestResult::TrFailedMsg(format!( - r#"panic did not contain expected string - panic message: `{panic_str:?}`, - expected substring: `{msg:?}`"# - )) - } else { - TestResult::TrFailedMsg(format!( - r#"expected panic with string value, - found non-string value: `{:?}` - expected substring: `{:?}`"#, - (*err).type_id(), - msg - )) - } - } - (&ShouldPanic::Yes, Ok(())) | (&ShouldPanic::YesWithMessage(_), Ok(())) => { - TestResult::TrFailedMsg("test did not panic as expected".to_string()) - } - _ => TestResult::TrFailed, - }; - - // If test is already failed (or allowed to fail), do not change the result. - if result != TestResult::TrOk { - return result; - } - - // Check if test is failed due to timeout. - if let (Some(opts), Some(time)) = (time_opts, exec_time) { - if opts.error_on_excess && opts.is_critical(desc, time) { - return TestResult::TrTimedFail; - } - } - - result -} - -/// Creates a `TestResult` depending on the exit code of test subprocess. -pub fn get_result_from_exit_code( - desc: &TestDesc, - status: ExitStatus, - time_opts: &Option, - exec_time: &Option, -) -> TestResult { - let result = match status.code() { - Some(TR_OK) => TestResult::TrOk, - #[cfg(windows)] - Some(STATUS_ABORTED) => TestResult::TrFailed, - #[cfg(unix)] - None => match status.signal() { - Some(libc::SIGABRT) => TestResult::TrFailed, - Some(signal) => { - TestResult::TrFailedMsg(format!("child process exited with signal {signal}")) - } - None => unreachable!("status.code() returned None but status.signal() was None"), - }, - #[cfg(not(unix))] - None => TestResult::TrFailedMsg(format!("unknown return code")), - #[cfg(any(windows, unix))] - Some(code) => TestResult::TrFailedMsg(format!("got unexpected return code {code}")), - #[cfg(not(any(windows, unix)))] - Some(_) => TestResult::TrFailed, - }; - - // If test is already failed (or allowed to fail), do not change the result. - if result != TestResult::TrOk { - return result; - } - - // Check if test is failed due to timeout. - if let (Some(opts), Some(time)) = (time_opts, exec_time) { - if opts.error_on_excess && opts.is_critical(desc, time) { - return TestResult::TrTimedFail; - } - } - - result -} diff --git a/library/test/src/tests.rs b/library/test/src/tests.rs deleted file mode 100644 index 43a906ad298d1..0000000000000 --- a/library/test/src/tests.rs +++ /dev/null @@ -1,924 +0,0 @@ -use super::*; - -use crate::{ - console::OutputLocation, - formatters::PrettyFormatter, - test::{ - parse_opts, - MetricMap, - // FIXME (introduced by #65251) - // ShouldPanic, StaticTestName, TestDesc, TestDescAndFn, TestOpts, TestTimeOptions, - // TestType, TrFailedMsg, TrIgnored, TrOk, - }, - time::{TestTimeOptions, TimeThreshold}, -}; - -impl TestOpts { - fn new() -> TestOpts { - TestOpts { - list: false, - filters: vec![], - filter_exact: false, - force_run_in_process: false, - exclude_should_panic: false, - run_ignored: RunIgnored::No, - run_tests: false, - bench_benchmarks: false, - logfile: None, - nocapture: false, - color: AutoColor, - format: OutputFormat::Pretty, - shuffle: false, - shuffle_seed: None, - test_threads: None, - skip: vec![], - time_options: None, - options: Options::new(), - fail_fast: false, - } - } -} - -fn one_ignored_one_unignored_test() -> Vec { - vec![ - TestDescAndFn { - desc: TestDesc { - name: StaticTestName("1"), - ignore: true, - ignore_message: None, - source_file: "", - start_line: 0, - start_col: 0, - end_line: 0, - end_col: 0, - should_panic: ShouldPanic::No, - compile_fail: false, - no_run: false, - test_type: TestType::Unknown, - }, - testfn: DynTestFn(Box::new(move || Ok(()))), - }, - TestDescAndFn { - desc: TestDesc { - name: StaticTestName("2"), - ignore: false, - ignore_message: None, - source_file: "", - start_line: 0, - start_col: 0, - end_line: 0, - end_col: 0, - should_panic: ShouldPanic::No, - compile_fail: false, - no_run: false, - test_type: TestType::Unknown, - }, - testfn: DynTestFn(Box::new(move || Ok(()))), - }, - ] -} - -#[test] -pub fn do_not_run_ignored_tests() { - fn f() -> Result<(), String> { - panic!(); - } - let desc = TestDescAndFn { - desc: TestDesc { - name: StaticTestName("whatever"), - ignore: true, - ignore_message: None, - source_file: "", - start_line: 0, - start_col: 0, - end_line: 0, - end_col: 0, - should_panic: ShouldPanic::No, - compile_fail: false, - no_run: false, - test_type: TestType::Unknown, - }, - testfn: DynTestFn(Box::new(f)), - }; - let (tx, rx) = channel(); - run_test(&TestOpts::new(), false, TestId(0), desc, RunStrategy::InProcess, tx); - let result = rx.recv().unwrap().result; - assert_ne!(result, TrOk); -} - -#[test] -pub fn ignored_tests_result_in_ignored() { - fn f() -> Result<(), String> { - Ok(()) - } - let desc = TestDescAndFn { - desc: TestDesc { - name: StaticTestName("whatever"), - ignore: true, - ignore_message: None, - source_file: "", - start_line: 0, - start_col: 0, - end_line: 0, - end_col: 0, - should_panic: ShouldPanic::No, - compile_fail: false, - no_run: false, - test_type: TestType::Unknown, - }, - testfn: DynTestFn(Box::new(f)), - }; - let (tx, rx) = channel(); - run_test(&TestOpts::new(), false, TestId(0), desc, RunStrategy::InProcess, tx); - let result = rx.recv().unwrap().result; - assert_eq!(result, TrIgnored); -} - -// FIXME: Re-enable emscripten once it can catch panics again (introduced by #65251) -#[test] -#[cfg(not(target_os = "emscripten"))] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_should_panic() { - fn f() -> Result<(), String> { - panic!(); - } - let desc = TestDescAndFn { - desc: TestDesc { - name: StaticTestName("whatever"), - ignore: false, - ignore_message: None, - source_file: "", - start_line: 0, - start_col: 0, - end_line: 0, - end_col: 0, - should_panic: ShouldPanic::Yes, - compile_fail: false, - no_run: false, - test_type: TestType::Unknown, - }, - testfn: DynTestFn(Box::new(f)), - }; - let (tx, rx) = channel(); - run_test(&TestOpts::new(), false, TestId(0), desc, RunStrategy::InProcess, tx); - let result = rx.recv().unwrap().result; - assert_eq!(result, TrOk); -} - -// FIXME: Re-enable emscripten once it can catch panics again (introduced by #65251) -#[test] -#[cfg(not(target_os = "emscripten"))] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_should_panic_good_message() { - fn f() -> Result<(), String> { - panic!("an error message"); - } - let desc = TestDescAndFn { - desc: TestDesc { - name: StaticTestName("whatever"), - ignore: false, - ignore_message: None, - source_file: "", - start_line: 0, - start_col: 0, - end_line: 0, - end_col: 0, - should_panic: ShouldPanic::YesWithMessage("error message"), - compile_fail: false, - no_run: false, - test_type: TestType::Unknown, - }, - testfn: DynTestFn(Box::new(f)), - }; - let (tx, rx) = channel(); - run_test(&TestOpts::new(), false, TestId(0), desc, RunStrategy::InProcess, tx); - let result = rx.recv().unwrap().result; - assert_eq!(result, TrOk); -} - -// FIXME: Re-enable emscripten once it can catch panics again (introduced by #65251) -#[test] -#[cfg(not(target_os = "emscripten"))] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_should_panic_bad_message() { - use crate::tests::TrFailedMsg; - fn f() -> Result<(), String> { - panic!("an error message"); - } - let expected = "foobar"; - let failed_msg = r#"panic did not contain expected string - panic message: `"an error message"`, - expected substring: `"foobar"`"#; - let desc = TestDescAndFn { - desc: TestDesc { - name: StaticTestName("whatever"), - ignore: false, - ignore_message: None, - source_file: "", - start_line: 0, - start_col: 0, - end_line: 0, - end_col: 0, - should_panic: ShouldPanic::YesWithMessage(expected), - compile_fail: false, - no_run: false, - test_type: TestType::Unknown, - }, - testfn: DynTestFn(Box::new(f)), - }; - let (tx, rx) = channel(); - run_test(&TestOpts::new(), false, TestId(0), desc, RunStrategy::InProcess, tx); - let result = rx.recv().unwrap().result; - assert_eq!(result, TrFailedMsg(failed_msg.to_string())); -} - -// FIXME: Re-enable emscripten once it can catch panics again (introduced by #65251) -#[test] -#[cfg(not(target_os = "emscripten"))] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_should_panic_non_string_message_type() { - use crate::tests::TrFailedMsg; - use std::any::TypeId; - fn f() -> Result<(), String> { - std::panic::panic_any(1i32); - } - let expected = "foobar"; - let failed_msg = format!( - r#"expected panic with string value, - found non-string value: `{:?}` - expected substring: `"foobar"`"#, - TypeId::of::() - ); - let desc = TestDescAndFn { - desc: TestDesc { - name: StaticTestName("whatever"), - ignore: false, - ignore_message: None, - source_file: "", - start_line: 0, - start_col: 0, - end_line: 0, - end_col: 0, - should_panic: ShouldPanic::YesWithMessage(expected), - compile_fail: false, - no_run: false, - test_type: TestType::Unknown, - }, - testfn: DynTestFn(Box::new(f)), - }; - let (tx, rx) = channel(); - run_test(&TestOpts::new(), false, TestId(0), desc, RunStrategy::InProcess, tx); - let result = rx.recv().unwrap().result; - assert_eq!(result, TrFailedMsg(failed_msg)); -} - -// FIXME: Re-enable emscripten once it can catch panics again (introduced by #65251) -#[test] -#[cfg(not(target_os = "emscripten"))] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_should_panic_but_succeeds() { - let should_panic_variants = [ShouldPanic::Yes, ShouldPanic::YesWithMessage("error message")]; - - for &should_panic in should_panic_variants.iter() { - fn f() -> Result<(), String> { - Ok(()) - } - let desc = TestDescAndFn { - desc: TestDesc { - name: StaticTestName("whatever"), - ignore: false, - ignore_message: None, - source_file: "", - start_line: 0, - start_col: 0, - end_line: 0, - end_col: 0, - should_panic, - compile_fail: false, - no_run: false, - test_type: TestType::Unknown, - }, - testfn: DynTestFn(Box::new(f)), - }; - let (tx, rx) = channel(); - run_test(&TestOpts::new(), false, TestId(0), desc, RunStrategy::InProcess, tx); - let result = rx.recv().unwrap().result; - assert_eq!( - result, - TrFailedMsg("test did not panic as expected".to_string()), - "should_panic == {:?}", - should_panic - ); - } -} - -fn report_time_test_template(report_time: bool) -> Option { - fn f() -> Result<(), String> { - Ok(()) - } - let desc = TestDescAndFn { - desc: TestDesc { - name: StaticTestName("whatever"), - ignore: false, - ignore_message: None, - source_file: "", - start_line: 0, - start_col: 0, - end_line: 0, - end_col: 0, - should_panic: ShouldPanic::No, - compile_fail: false, - no_run: false, - test_type: TestType::Unknown, - }, - testfn: DynTestFn(Box::new(f)), - }; - let time_options = if report_time { Some(TestTimeOptions::default()) } else { None }; - - let test_opts = TestOpts { time_options, ..TestOpts::new() }; - let (tx, rx) = channel(); - run_test(&test_opts, false, TestId(0), desc, RunStrategy::InProcess, tx); - let exec_time = rx.recv().unwrap().exec_time; - exec_time -} - -#[test] -fn test_should_not_report_time() { - let exec_time = report_time_test_template(false); - assert!(exec_time.is_none()); -} - -#[test] -fn test_should_report_time() { - let exec_time = report_time_test_template(true); - assert!(exec_time.is_some()); -} - -fn time_test_failure_template(test_type: TestType) -> TestResult { - fn f() -> Result<(), String> { - Ok(()) - } - let desc = TestDescAndFn { - desc: TestDesc { - name: StaticTestName("whatever"), - ignore: false, - ignore_message: None, - source_file: "", - start_line: 0, - start_col: 0, - end_line: 0, - end_col: 0, - should_panic: ShouldPanic::No, - compile_fail: false, - no_run: false, - test_type, - }, - testfn: DynTestFn(Box::new(f)), - }; - // `Default` will initialize all the thresholds to 0 milliseconds. - let mut time_options = TestTimeOptions::default(); - time_options.error_on_excess = true; - - let test_opts = TestOpts { time_options: Some(time_options), ..TestOpts::new() }; - let (tx, rx) = channel(); - run_test(&test_opts, false, TestId(0), desc, RunStrategy::InProcess, tx); - let result = rx.recv().unwrap().result; - - result -} - -#[test] -fn test_error_on_exceed() { - let types = [TestType::UnitTest, TestType::IntegrationTest, TestType::DocTest]; - - for test_type in types.iter() { - let result = time_test_failure_template(*test_type); - - assert_eq!(result, TestResult::TrTimedFail); - } - - // Check that for unknown tests thresholds aren't applied. - let result = time_test_failure_template(TestType::Unknown); - assert_eq!(result, TestResult::TrOk); -} - -fn typed_test_desc(test_type: TestType) -> TestDesc { - TestDesc { - name: StaticTestName("whatever"), - ignore: false, - ignore_message: None, - source_file: "", - start_line: 0, - start_col: 0, - end_line: 0, - end_col: 0, - should_panic: ShouldPanic::No, - compile_fail: false, - no_run: false, - test_type, - } -} - -fn test_exec_time(millis: u64) -> TestExecTime { - TestExecTime(Duration::from_millis(millis)) -} - -#[test] -fn test_time_options_threshold() { - let unit = TimeThreshold::new(Duration::from_millis(50), Duration::from_millis(100)); - let integration = TimeThreshold::new(Duration::from_millis(500), Duration::from_millis(1000)); - let doc = TimeThreshold::new(Duration::from_millis(5000), Duration::from_millis(10000)); - - let options = TestTimeOptions { - error_on_excess: false, - unit_threshold: unit.clone(), - integration_threshold: integration.clone(), - doctest_threshold: doc.clone(), - }; - - let test_vector = [ - (TestType::UnitTest, unit.warn.as_millis() - 1, false, false), - (TestType::UnitTest, unit.warn.as_millis(), true, false), - (TestType::UnitTest, unit.critical.as_millis(), true, true), - (TestType::IntegrationTest, integration.warn.as_millis() - 1, false, false), - (TestType::IntegrationTest, integration.warn.as_millis(), true, false), - (TestType::IntegrationTest, integration.critical.as_millis(), true, true), - (TestType::DocTest, doc.warn.as_millis() - 1, false, false), - (TestType::DocTest, doc.warn.as_millis(), true, false), - (TestType::DocTest, doc.critical.as_millis(), true, true), - ]; - - for (test_type, time, expected_warn, expected_critical) in test_vector.iter() { - let test_desc = typed_test_desc(*test_type); - let exec_time = test_exec_time(*time as u64); - - assert_eq!(options.is_warn(&test_desc, &exec_time), *expected_warn); - assert_eq!(options.is_critical(&test_desc, &exec_time), *expected_critical); - } -} - -#[test] -fn parse_ignored_flag() { - let args = vec!["progname".to_string(), "filter".to_string(), "--ignored".to_string()]; - let opts = parse_opts(&args).unwrap().unwrap(); - assert_eq!(opts.run_ignored, RunIgnored::Only); -} - -#[test] -fn parse_show_output_flag() { - let args = vec!["progname".to_string(), "filter".to_string(), "--show-output".to_string()]; - let opts = parse_opts(&args).unwrap().unwrap(); - assert!(opts.options.display_output); -} - -#[test] -fn parse_include_ignored_flag() { - let args = vec!["progname".to_string(), "filter".to_string(), "--include-ignored".to_string()]; - let opts = parse_opts(&args).unwrap().unwrap(); - assert_eq!(opts.run_ignored, RunIgnored::Yes); -} - -#[test] -pub fn filter_for_ignored_option() { - // When we run ignored tests the test filter should filter out all the - // unignored tests and flip the ignore flag on the rest to false - - let mut opts = TestOpts::new(); - opts.run_tests = true; - opts.run_ignored = RunIgnored::Only; - - let tests = one_ignored_one_unignored_test(); - let filtered = filter_tests(&opts, tests); - - assert_eq!(filtered.len(), 1); - assert_eq!(filtered[0].desc.name.to_string(), "1"); - assert!(!filtered[0].desc.ignore); -} - -#[test] -pub fn run_include_ignored_option() { - // When we "--include-ignored" tests, the ignore flag should be set to false on - // all tests and no test filtered out - - let mut opts = TestOpts::new(); - opts.run_tests = true; - opts.run_ignored = RunIgnored::Yes; - - let tests = one_ignored_one_unignored_test(); - let filtered = filter_tests(&opts, tests); - - assert_eq!(filtered.len(), 2); - assert!(!filtered[0].desc.ignore); - assert!(!filtered[1].desc.ignore); -} - -#[test] -pub fn exclude_should_panic_option() { - let mut opts = TestOpts::new(); - opts.run_tests = true; - opts.exclude_should_panic = true; - - let mut tests = one_ignored_one_unignored_test(); - tests.push(TestDescAndFn { - desc: TestDesc { - name: StaticTestName("3"), - ignore: false, - ignore_message: None, - source_file: "", - start_line: 0, - start_col: 0, - end_line: 0, - end_col: 0, - should_panic: ShouldPanic::Yes, - compile_fail: false, - no_run: false, - test_type: TestType::Unknown, - }, - testfn: DynTestFn(Box::new(move || Ok(()))), - }); - - let filtered = filter_tests(&opts, tests); - - assert_eq!(filtered.len(), 2); - assert!(filtered.iter().all(|test| test.desc.should_panic == ShouldPanic::No)); -} - -#[test] -pub fn exact_filter_match() { - fn tests() -> Vec { - ["base", "base::test", "base::test1", "base::test2"] - .into_iter() - .map(|name| TestDescAndFn { - desc: TestDesc { - name: StaticTestName(name), - ignore: false, - ignore_message: None, - source_file: "", - start_line: 0, - start_col: 0, - end_line: 0, - end_col: 0, - should_panic: ShouldPanic::No, - compile_fail: false, - no_run: false, - test_type: TestType::Unknown, - }, - testfn: DynTestFn(Box::new(move || Ok(()))), - }) - .collect() - } - - let substr = - filter_tests(&TestOpts { filters: vec!["base".into()], ..TestOpts::new() }, tests()); - assert_eq!(substr.len(), 4); - - let substr = - filter_tests(&TestOpts { filters: vec!["bas".into()], ..TestOpts::new() }, tests()); - assert_eq!(substr.len(), 4); - - let substr = - filter_tests(&TestOpts { filters: vec!["::test".into()], ..TestOpts::new() }, tests()); - assert_eq!(substr.len(), 3); - - let substr = - filter_tests(&TestOpts { filters: vec!["base::test".into()], ..TestOpts::new() }, tests()); - assert_eq!(substr.len(), 3); - - let substr = filter_tests( - &TestOpts { filters: vec!["test1".into(), "test2".into()], ..TestOpts::new() }, - tests(), - ); - assert_eq!(substr.len(), 2); - - let exact = filter_tests( - &TestOpts { filters: vec!["base".into()], filter_exact: true, ..TestOpts::new() }, - tests(), - ); - assert_eq!(exact.len(), 1); - - let exact = filter_tests( - &TestOpts { filters: vec!["bas".into()], filter_exact: true, ..TestOpts::new() }, - tests(), - ); - assert_eq!(exact.len(), 0); - - let exact = filter_tests( - &TestOpts { filters: vec!["::test".into()], filter_exact: true, ..TestOpts::new() }, - tests(), - ); - assert_eq!(exact.len(), 0); - - let exact = filter_tests( - &TestOpts { filters: vec!["base::test".into()], filter_exact: true, ..TestOpts::new() }, - tests(), - ); - assert_eq!(exact.len(), 1); - - let exact = filter_tests( - &TestOpts { - filters: vec!["base".into(), "base::test".into()], - filter_exact: true, - ..TestOpts::new() - }, - tests(), - ); - assert_eq!(exact.len(), 2); -} - -fn sample_tests() -> Vec { - let names = vec![ - "sha1::test".to_string(), - "isize::test_to_str".to_string(), - "isize::test_pow".to_string(), - "test::do_not_run_ignored_tests".to_string(), - "test::ignored_tests_result_in_ignored".to_string(), - "test::first_free_arg_should_be_a_filter".to_string(), - "test::parse_ignored_flag".to_string(), - "test::parse_include_ignored_flag".to_string(), - "test::filter_for_ignored_option".to_string(), - "test::run_include_ignored_option".to_string(), - "test::sort_tests".to_string(), - ]; - fn testfn() -> Result<(), String> { - Ok(()) - } - let mut tests = Vec::new(); - for name in &names { - let test = TestDescAndFn { - desc: TestDesc { - name: DynTestName((*name).clone()), - ignore: false, - ignore_message: None, - source_file: "", - start_line: 0, - start_col: 0, - end_line: 0, - end_col: 0, - should_panic: ShouldPanic::No, - compile_fail: false, - no_run: false, - test_type: TestType::Unknown, - }, - testfn: DynTestFn(Box::new(testfn)), - }; - tests.push(test); - } - tests -} - -#[test] -pub fn shuffle_tests() { - let mut opts = TestOpts::new(); - opts.shuffle = true; - - let shuffle_seed = get_shuffle_seed(&opts).unwrap(); - - let left = - sample_tests().into_iter().enumerate().map(|(i, e)| (TestId(i), e)).collect::>(); - let mut right = - sample_tests().into_iter().enumerate().map(|(i, e)| (TestId(i), e)).collect::>(); - - assert!(left.iter().zip(&right).all(|(a, b)| a.1.desc.name == b.1.desc.name)); - - helpers::shuffle::shuffle_tests(shuffle_seed, right.as_mut_slice()); - - assert!(left.iter().zip(right).any(|(a, b)| a.1.desc.name != b.1.desc.name)); -} - -#[test] -pub fn shuffle_tests_with_seed() { - let mut opts = TestOpts::new(); - opts.shuffle = true; - - let shuffle_seed = get_shuffle_seed(&opts).unwrap(); - - let mut left = - sample_tests().into_iter().enumerate().map(|(i, e)| (TestId(i), e)).collect::>(); - let mut right = - sample_tests().into_iter().enumerate().map(|(i, e)| (TestId(i), e)).collect::>(); - - helpers::shuffle::shuffle_tests(shuffle_seed, left.as_mut_slice()); - helpers::shuffle::shuffle_tests(shuffle_seed, right.as_mut_slice()); - - assert!(left.iter().zip(right).all(|(a, b)| a.1.desc.name == b.1.desc.name)); -} - -#[test] -pub fn order_depends_on_more_than_seed() { - let mut opts = TestOpts::new(); - opts.shuffle = true; - - let shuffle_seed = get_shuffle_seed(&opts).unwrap(); - - let mut left_tests = sample_tests(); - let mut right_tests = sample_tests(); - - left_tests.pop(); - right_tests.remove(0); - - let mut left = - left_tests.into_iter().enumerate().map(|(i, e)| (TestId(i), e)).collect::>(); - let mut right = - right_tests.into_iter().enumerate().map(|(i, e)| (TestId(i), e)).collect::>(); - - assert_eq!(left.len(), right.len()); - - assert!(left.iter().zip(&right).all(|(a, b)| a.0 == b.0)); - - helpers::shuffle::shuffle_tests(shuffle_seed, left.as_mut_slice()); - helpers::shuffle::shuffle_tests(shuffle_seed, right.as_mut_slice()); - - assert!(left.iter().zip(right).any(|(a, b)| a.0 != b.0)); -} - -#[test] -pub fn test_metricmap_compare() { - let mut m1 = MetricMap::new(); - let mut m2 = MetricMap::new(); - m1.insert_metric("in-both-noise", 1000.0, 200.0); - m2.insert_metric("in-both-noise", 1100.0, 200.0); - - m1.insert_metric("in-first-noise", 1000.0, 2.0); - m2.insert_metric("in-second-noise", 1000.0, 2.0); - - m1.insert_metric("in-both-want-downwards-but-regressed", 1000.0, 10.0); - m2.insert_metric("in-both-want-downwards-but-regressed", 2000.0, 10.0); - - m1.insert_metric("in-both-want-downwards-and-improved", 2000.0, 10.0); - m2.insert_metric("in-both-want-downwards-and-improved", 1000.0, 10.0); - - m1.insert_metric("in-both-want-upwards-but-regressed", 2000.0, -10.0); - m2.insert_metric("in-both-want-upwards-but-regressed", 1000.0, -10.0); - - m1.insert_metric("in-both-want-upwards-and-improved", 1000.0, -10.0); - m2.insert_metric("in-both-want-upwards-and-improved", 2000.0, -10.0); -} - -#[test] -pub fn test_bench_once_no_iter() { - fn f(_: &mut Bencher) -> Result<(), String> { - Ok(()) - } - bench::run_once(f).unwrap(); -} - -#[test] -pub fn test_bench_once_iter() { - fn f(b: &mut Bencher) -> Result<(), String> { - b.iter(|| {}); - Ok(()) - } - bench::run_once(f).unwrap(); -} - -#[test] -pub fn test_bench_no_iter() { - fn f(_: &mut Bencher) -> Result<(), String> { - Ok(()) - } - - let (tx, rx) = channel(); - - let desc = TestDesc { - name: StaticTestName("f"), - ignore: false, - ignore_message: None, - source_file: "", - start_line: 0, - start_col: 0, - end_line: 0, - end_col: 0, - should_panic: ShouldPanic::No, - compile_fail: false, - no_run: false, - test_type: TestType::Unknown, - }; - - crate::bench::benchmark(TestId(0), desc, tx, true, f); - rx.recv().unwrap(); -} - -#[test] -pub fn test_bench_iter() { - fn f(b: &mut Bencher) -> Result<(), String> { - b.iter(|| {}); - Ok(()) - } - - let (tx, rx) = channel(); - - let desc = TestDesc { - name: StaticTestName("f"), - ignore: false, - ignore_message: None, - source_file: "", - start_line: 0, - start_col: 0, - end_line: 0, - end_col: 0, - should_panic: ShouldPanic::No, - compile_fail: false, - no_run: false, - test_type: TestType::Unknown, - }; - - crate::bench::benchmark(TestId(0), desc, tx, true, f); - rx.recv().unwrap(); -} - -#[test] -fn should_sort_failures_before_printing_them() { - let test_a = TestDesc { - name: StaticTestName("a"), - ignore: false, - ignore_message: None, - source_file: "", - start_line: 0, - start_col: 0, - end_line: 0, - end_col: 0, - should_panic: ShouldPanic::No, - compile_fail: false, - no_run: false, - test_type: TestType::Unknown, - }; - - let test_b = TestDesc { - name: StaticTestName("b"), - ignore: false, - ignore_message: None, - source_file: "", - start_line: 0, - start_col: 0, - end_line: 0, - end_col: 0, - should_panic: ShouldPanic::No, - compile_fail: false, - no_run: false, - test_type: TestType::Unknown, - }; - - let mut out = PrettyFormatter::new(OutputLocation::Raw(Vec::new()), false, 10, false, None); - - let st = console::ConsoleTestState { - log_out: None, - total: 0, - passed: 0, - failed: 0, - ignored: 0, - filtered_out: 0, - measured: 0, - exec_time: None, - metrics: MetricMap::new(), - failures: vec![(test_b, Vec::new()), (test_a, Vec::new())], - options: Options::new(), - not_failures: Vec::new(), - ignores: Vec::new(), - time_failures: Vec::new(), - }; - - out.write_failures(&st).unwrap(); - let s = match out.output_location() { - &OutputLocation::Raw(ref m) => String::from_utf8_lossy(&m[..]), - &OutputLocation::Pretty(_) => unreachable!(), - }; - - let apos = s.find("a").unwrap(); - let bpos = s.find("b").unwrap(); - assert!(apos < bpos); -} - -#[test] -#[cfg(not(target_os = "emscripten"))] -fn test_dyn_bench_returning_err_fails_when_run_as_test() { - fn f(_: &mut Bencher) -> Result<(), String> { - Result::Err("An error".into()) - } - let desc = TestDescAndFn { - desc: TestDesc { - name: StaticTestName("whatever"), - ignore: false, - ignore_message: None, - source_file: "", - start_line: 0, - start_col: 0, - end_line: 0, - end_col: 0, - should_panic: ShouldPanic::No, - compile_fail: false, - no_run: false, - test_type: TestType::Unknown, - }, - testfn: DynBenchFn(Box::new(f)), - }; - let (tx, rx) = channel(); - let notify = move |event: TestEvent| { - if let TestEvent::TeResult(result) = event { - tx.send(result).unwrap(); - } - Ok(()) - }; - run_tests(&TestOpts { run_tests: true, ..TestOpts::new() }, vec![desc], notify).unwrap(); - let result = rx.recv().unwrap().result; - assert_eq!(result, TrFailed); -} diff --git a/library/test/src/time.rs b/library/test/src/time.rs deleted file mode 100644 index 7fd69d7f7e73c..0000000000000 --- a/library/test/src/time.rs +++ /dev/null @@ -1,195 +0,0 @@ -//! Module `time` contains everything related to the time measurement of unit tests -//! execution. -//! The purposes of this module: -//! - Check whether test is timed out. -//! - Provide helpers for `report-time` and `measure-time` options. -//! - Provide newtypes for executions times. - -use std::env; -use std::fmt; -use std::str::FromStr; -use std::time::{Duration, Instant}; - -use super::types::{TestDesc, TestType}; - -pub const TEST_WARN_TIMEOUT_S: u64 = 60; - -/// This small module contains constants used by `report-time` option. -/// Those constants values will be used if corresponding environment variables are not set. -/// -/// To override values for unit-tests, use a constant `RUST_TEST_TIME_UNIT`, -/// To override values for integration tests, use a constant `RUST_TEST_TIME_INTEGRATION`, -/// To override values for doctests, use a constant `RUST_TEST_TIME_DOCTEST`. -/// -/// Example of the expected format is `RUST_TEST_TIME_xxx=100,200`, where 100 means -/// warn time, and 200 means critical time. -pub mod time_constants { - use super::TEST_WARN_TIMEOUT_S; - use std::time::Duration; - - /// Environment variable for overriding default threshold for unit-tests. - pub const UNIT_ENV_NAME: &str = "RUST_TEST_TIME_UNIT"; - - // Unit tests are supposed to be really quick. - pub const UNIT_WARN: Duration = Duration::from_millis(50); - pub const UNIT_CRITICAL: Duration = Duration::from_millis(100); - - /// Environment variable for overriding default threshold for unit-tests. - pub const INTEGRATION_ENV_NAME: &str = "RUST_TEST_TIME_INTEGRATION"; - - // Integration tests may have a lot of work, so they can take longer to execute. - pub const INTEGRATION_WARN: Duration = Duration::from_millis(500); - pub const INTEGRATION_CRITICAL: Duration = Duration::from_millis(1000); - - /// Environment variable for overriding default threshold for unit-tests. - pub const DOCTEST_ENV_NAME: &str = "RUST_TEST_TIME_DOCTEST"; - - // Doctests are similar to integration tests, because they can include a lot of - // initialization code. - pub const DOCTEST_WARN: Duration = INTEGRATION_WARN; - pub const DOCTEST_CRITICAL: Duration = INTEGRATION_CRITICAL; - - // Do not suppose anything about unknown tests, base limits on the - // `TEST_WARN_TIMEOUT_S` constant. - pub const UNKNOWN_WARN: Duration = Duration::from_secs(TEST_WARN_TIMEOUT_S); - pub const UNKNOWN_CRITICAL: Duration = Duration::from_secs(TEST_WARN_TIMEOUT_S * 2); -} - -/// Returns an `Instance` object denoting when the test should be considered -/// timed out. -pub fn get_default_test_timeout() -> Instant { - Instant::now() + Duration::from_secs(TEST_WARN_TIMEOUT_S) -} - -/// The measured execution time of a unit test. -#[derive(Debug, Clone, PartialEq)] -pub struct TestExecTime(pub Duration); - -impl fmt::Display for TestExecTime { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "{:.3}s", self.0.as_secs_f64()) - } -} - -/// The measured execution time of the whole test suite. -#[derive(Debug, Clone, Default, PartialEq)] -pub struct TestSuiteExecTime(pub Duration); - -impl fmt::Display for TestSuiteExecTime { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "{:.2}s", self.0.as_secs_f64()) - } -} - -/// Structure denoting time limits for test execution. -#[derive(Copy, Clone, Debug, Default, PartialEq, Eq)] -pub struct TimeThreshold { - pub warn: Duration, - pub critical: Duration, -} - -impl TimeThreshold { - /// Creates a new `TimeThreshold` instance with provided durations. - pub fn new(warn: Duration, critical: Duration) -> Self { - Self { warn, critical } - } - - /// Attempts to create a `TimeThreshold` instance with values obtained - /// from the environment variable, and returns `None` if the variable - /// is not set. - /// Environment variable format is expected to match `\d+,\d+`. - /// - /// # Panics - /// - /// Panics if variable with provided name is set but contains inappropriate - /// value. - pub fn from_env_var(env_var_name: &str) -> Option { - let durations_str = env::var(env_var_name).ok()?; - let (warn_str, critical_str) = durations_str.split_once(',').unwrap_or_else(|| { - panic!( - "Duration variable {env_var_name} expected to have 2 numbers separated by comma, but got {durations_str}" - ) - }); - - let parse_u64 = |v| { - u64::from_str(v).unwrap_or_else(|_| { - panic!( - "Duration value in variable {env_var_name} is expected to be a number, but got {v}" - ) - }) - }; - - let warn = parse_u64(warn_str); - let critical = parse_u64(critical_str); - if warn > critical { - panic!("Test execution warn time should be less or equal to the critical time"); - } - - Some(Self::new(Duration::from_millis(warn), Duration::from_millis(critical))) - } -} - -/// Structure with parameters for calculating test execution time. -#[derive(Copy, Clone, Debug, Default, PartialEq, Eq)] -pub struct TestTimeOptions { - /// Denotes if the test critical execution time limit excess should be considered - /// a test failure. - pub error_on_excess: bool, - pub unit_threshold: TimeThreshold, - pub integration_threshold: TimeThreshold, - pub doctest_threshold: TimeThreshold, -} - -impl TestTimeOptions { - pub fn new_from_env(error_on_excess: bool) -> Self { - let unit_threshold = TimeThreshold::from_env_var(time_constants::UNIT_ENV_NAME) - .unwrap_or_else(Self::default_unit); - - let integration_threshold = - TimeThreshold::from_env_var(time_constants::INTEGRATION_ENV_NAME) - .unwrap_or_else(Self::default_integration); - - let doctest_threshold = TimeThreshold::from_env_var(time_constants::DOCTEST_ENV_NAME) - .unwrap_or_else(Self::default_doctest); - - Self { error_on_excess, unit_threshold, integration_threshold, doctest_threshold } - } - - pub fn is_warn(&self, test: &TestDesc, exec_time: &TestExecTime) -> bool { - exec_time.0 >= self.warn_time(test) - } - - pub fn is_critical(&self, test: &TestDesc, exec_time: &TestExecTime) -> bool { - exec_time.0 >= self.critical_time(test) - } - - fn warn_time(&self, test: &TestDesc) -> Duration { - match test.test_type { - TestType::UnitTest => self.unit_threshold.warn, - TestType::IntegrationTest => self.integration_threshold.warn, - TestType::DocTest => self.doctest_threshold.warn, - TestType::Unknown => time_constants::UNKNOWN_WARN, - } - } - - fn critical_time(&self, test: &TestDesc) -> Duration { - match test.test_type { - TestType::UnitTest => self.unit_threshold.critical, - TestType::IntegrationTest => self.integration_threshold.critical, - TestType::DocTest => self.doctest_threshold.critical, - TestType::Unknown => time_constants::UNKNOWN_CRITICAL, - } - } - - fn default_unit() -> TimeThreshold { - TimeThreshold::new(time_constants::UNIT_WARN, time_constants::UNIT_CRITICAL) - } - - fn default_integration() -> TimeThreshold { - TimeThreshold::new(time_constants::INTEGRATION_WARN, time_constants::INTEGRATION_CRITICAL) - } - - fn default_doctest() -> TimeThreshold { - TimeThreshold::new(time_constants::DOCTEST_WARN, time_constants::DOCTEST_CRITICAL) - } -} diff --git a/library/test/src/types.rs b/library/test/src/types.rs deleted file mode 100644 index 6a7035a8e2918..0000000000000 --- a/library/test/src/types.rs +++ /dev/null @@ -1,253 +0,0 @@ -//! Common types used by `libtest`. - -use std::borrow::Cow; -use std::fmt; -use std::sync::mpsc::Sender; - -use super::__rust_begin_short_backtrace; -use super::bench::Bencher; -use super::event::CompletedTest; -use super::options; - -pub use NamePadding::*; -pub use TestFn::*; -pub use TestName::*; - -/// Type of the test according to the [Rust book](https://doc.rust-lang.org/cargo/guide/tests.html) -/// conventions. -#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)] -pub enum TestType { - /// Unit-tests are expected to be in the `src` folder of the crate. - UnitTest, - /// Integration-style tests are expected to be in the `tests` folder of the crate. - IntegrationTest, - /// Doctests are created by the `librustdoc` manually, so it's a different type of test. - DocTest, - /// Tests for the sources that don't follow the project layout convention - /// (e.g. tests in raw `main.rs` compiled by calling `rustc --test` directly). - Unknown, -} - -#[derive(Clone, Copy, PartialEq, Eq, Hash, Debug)] -pub enum NamePadding { - PadNone, - PadOnRight, -} - -// The name of a test. By convention this follows the rules for rust -// paths; i.e., it should be a series of identifiers separated by double -// colons. This way if some test runner wants to arrange the tests -// hierarchically it may. -#[derive(Clone, PartialEq, Eq, Hash, Debug)] -pub enum TestName { - StaticTestName(&'static str), - DynTestName(String), - AlignedTestName(Cow<'static, str>, NamePadding), -} - -impl TestName { - pub fn as_slice(&self) -> &str { - match *self { - StaticTestName(s) => s, - DynTestName(ref s) => s, - AlignedTestName(ref s, _) => s, - } - } - - pub fn padding(&self) -> NamePadding { - match self { - &AlignedTestName(_, p) => p, - _ => PadNone, - } - } - - pub fn with_padding(&self, padding: NamePadding) -> TestName { - let name = match *self { - TestName::StaticTestName(name) => Cow::Borrowed(name), - TestName::DynTestName(ref name) => Cow::Owned(name.clone()), - TestName::AlignedTestName(ref name, _) => name.clone(), - }; - - TestName::AlignedTestName(name, padding) - } -} -impl fmt::Display for TestName { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt(self.as_slice(), f) - } -} - -// A function that runs a test. If the function returns successfully, -// the test succeeds; if the function panics or returns Result::Err -// then the test fails. We may need to come up with a more clever -// definition of test in order to support isolation of tests into -// threads. -pub enum TestFn { - StaticTestFn(fn() -> Result<(), String>), - StaticBenchFn(fn(&mut Bencher) -> Result<(), String>), - StaticBenchAsTestFn(fn(&mut Bencher) -> Result<(), String>), - DynTestFn(Box Result<(), String> + Send>), - DynBenchFn(Box Result<(), String> + Send>), - DynBenchAsTestFn(Box Result<(), String> + Send>), -} - -impl TestFn { - pub fn padding(&self) -> NamePadding { - match *self { - StaticTestFn(..) => PadNone, - StaticBenchFn(..) => PadOnRight, - StaticBenchAsTestFn(..) => PadNone, - DynTestFn(..) => PadNone, - DynBenchFn(..) => PadOnRight, - DynBenchAsTestFn(..) => PadNone, - } - } - - pub(crate) fn into_runnable(self) -> Runnable { - match self { - StaticTestFn(f) => Runnable::Test(RunnableTest::Static(f)), - StaticBenchFn(f) => Runnable::Bench(RunnableBench::Static(f)), - StaticBenchAsTestFn(f) => Runnable::Test(RunnableTest::StaticBenchAsTest(f)), - DynTestFn(f) => Runnable::Test(RunnableTest::Dynamic(f)), - DynBenchFn(f) => Runnable::Bench(RunnableBench::Dynamic(f)), - DynBenchAsTestFn(f) => Runnable::Test(RunnableTest::DynamicBenchAsTest(f)), - } - } -} - -impl fmt::Debug for TestFn { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str(match *self { - StaticTestFn(..) => "StaticTestFn(..)", - StaticBenchFn(..) => "StaticBenchFn(..)", - StaticBenchAsTestFn(..) => "StaticBenchAsTestFn(..)", - DynTestFn(..) => "DynTestFn(..)", - DynBenchFn(..) => "DynBenchFn(..)", - DynBenchAsTestFn(..) => "DynBenchAsTestFn(..)", - }) - } -} - -pub(crate) enum Runnable { - Test(RunnableTest), - Bench(RunnableBench), -} - -pub(crate) enum RunnableTest { - Static(fn() -> Result<(), String>), - Dynamic(Box Result<(), String> + Send>), - StaticBenchAsTest(fn(&mut Bencher) -> Result<(), String>), - DynamicBenchAsTest(Box Result<(), String> + Send>), -} - -impl RunnableTest { - pub(crate) fn run(self) -> Result<(), String> { - match self { - RunnableTest::Static(f) => __rust_begin_short_backtrace(f), - RunnableTest::Dynamic(f) => __rust_begin_short_backtrace(f), - RunnableTest::StaticBenchAsTest(f) => { - crate::bench::run_once(|b| __rust_begin_short_backtrace(|| f(b))) - } - RunnableTest::DynamicBenchAsTest(f) => { - crate::bench::run_once(|b| __rust_begin_short_backtrace(|| f(b))) - } - } - } - - pub(crate) fn is_dynamic(&self) -> bool { - match self { - RunnableTest::Static(_) => false, - RunnableTest::StaticBenchAsTest(_) => false, - RunnableTest::Dynamic(_) => true, - RunnableTest::DynamicBenchAsTest(_) => true, - } - } -} - -pub(crate) enum RunnableBench { - Static(fn(&mut Bencher) -> Result<(), String>), - Dynamic(Box Result<(), String> + Send>), -} - -impl RunnableBench { - pub(crate) fn run( - self, - id: TestId, - desc: &TestDesc, - monitor_ch: &Sender, - nocapture: bool, - ) { - match self { - RunnableBench::Static(f) => { - crate::bench::benchmark(id, desc.clone(), monitor_ch.clone(), nocapture, f) - } - RunnableBench::Dynamic(f) => { - crate::bench::benchmark(id, desc.clone(), monitor_ch.clone(), nocapture, f) - } - } - } -} - -// A unique integer associated with each test. -#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)] -pub struct TestId(pub usize); - -// The definition of a single test. A test runner will run a list of -// these. -#[derive(Clone, Debug)] -pub struct TestDesc { - pub name: TestName, - pub ignore: bool, - pub ignore_message: Option<&'static str>, - pub source_file: &'static str, - pub start_line: usize, - pub start_col: usize, - pub end_line: usize, - pub end_col: usize, - pub should_panic: options::ShouldPanic, - pub compile_fail: bool, - pub no_run: bool, - pub test_type: TestType, -} - -impl TestDesc { - pub fn padded_name(&self, column_count: usize, align: NamePadding) -> String { - let mut name = String::from(self.name.as_slice()); - let fill = column_count.saturating_sub(name.len()); - let pad = " ".repeat(fill); - match align { - PadNone => name, - PadOnRight => { - name.push_str(&pad); - name - } - } - } - - /// Returns None for ignored test or tests that are just run, otherwise returns a description of the type of test. - /// Descriptions include "should panic", "compile fail" and "compile". - pub fn test_mode(&self) -> Option<&'static str> { - if self.ignore { - return None; - } - match self.should_panic { - options::ShouldPanic::Yes | options::ShouldPanic::YesWithMessage(_) => { - return Some("should panic"); - } - options::ShouldPanic::No => {} - } - if self.compile_fail { - return Some("compile fail"); - } - if self.no_run { - return Some("compile"); - } - None - } -} - -#[derive(Debug)] -pub struct TestDescAndFn { - pub desc: TestDesc, - pub testfn: TestFn, -} diff --git a/library/unwind/Cargo.toml b/library/unwind/Cargo.toml deleted file mode 100644 index bbd1db8dfa57f..0000000000000 --- a/library/unwind/Cargo.toml +++ /dev/null @@ -1,36 +0,0 @@ -[package] -name = "unwind" -version = "0.0.0" -license = "MIT OR Apache-2.0" -repository = "https://github.com/rust-lang/rust.git" -edition = "2021" -include = [ - '/libunwind/*', -] - -[lib] -test = false -bench = false -doc = false - -[dependencies] -core = { path = "../core" } -compiler_builtins = "0.1.0" -cfg-if = "1.0" - -[target.'cfg(not(all(windows, target_env = "msvc")))'.dependencies] -libc = { version = "0.2.140", features = ['rustc-dep-of-std'], default-features = false } - -[target.'cfg(target_os = "xous")'.dependencies] -unwinding = { version = "0.2.1", features = ['rustc-dep-of-std', 'unwinder', 'fde-custom'], default-features = false } - -[features] - -# Only applies for Linux and Fuchsia targets -# Static link to the in-tree build of llvm libunwind -llvm-libunwind = [] - -# Only applies for Linux and Fuchsia targets -# If crt-static is enabled, static link to `libunwind.a` provided by system -# If crt-static is disabled, dynamic link to `libunwind.so` provided by system -system-llvm-libunwind = [] diff --git a/library/unwind/src/lib.rs b/library/unwind/src/lib.rs deleted file mode 100644 index 544d9fbf1ae0f..0000000000000 --- a/library/unwind/src/lib.rs +++ /dev/null @@ -1,174 +0,0 @@ -#![no_std] -#![unstable(feature = "panic_unwind", issue = "32837")] -#![feature(link_cfg)] -#![feature(staged_api)] -#![feature(c_unwind)] -#![feature(strict_provenance)] -#![cfg_attr(target_arch = "wasm64", feature(simd_wasm64))] -#![cfg_attr(not(target_env = "msvc"), feature(libc))] -#![cfg_attr( - all(target_family = "wasm", not(target_os = "emscripten")), - feature(link_llvm_intrinsics) -)] -#![allow(internal_features)] - -// Force libc to be included even if unused. This is required by many platforms. -#[cfg(not(all(windows, target_env = "msvc")))] -extern crate libc as _; - -cfg_if::cfg_if! { - if #[cfg(target_env = "msvc")] { - // Windows MSVC no extra unwinder support needed - } else if #[cfg(any( - target_os = "l4re", - target_os = "none", - target_os = "espidf", - ))] { - // These "unix" family members do not have unwinder. - } else if #[cfg(any( - unix, - windows, - target_os = "psp", - target_os = "solid_asp3", - all(target_vendor = "fortanix", target_env = "sgx"), - ))] { - mod libunwind; - pub use libunwind::*; - } else if #[cfg(target_os = "xous")] { - mod unwinding; - pub use unwinding::*; - } else if #[cfg(target_family = "wasm")] { - mod wasm; - pub use wasm::*; - } else { - // no unwinder on the system! - // - os=none ("bare metal" targets) - // - os=hermit - // - os=uefi - // - os=cuda - // - nvptx64-nvidia-cuda - // - Any new targets not listed above. - } -} - -#[cfg(target_env = "musl")] -cfg_if::cfg_if! { - if #[cfg(all(feature = "llvm-libunwind", feature = "system-llvm-libunwind"))] { - compile_error!("`llvm-libunwind` and `system-llvm-libunwind` cannot be enabled at the same time"); - } else if #[cfg(feature = "llvm-libunwind")] { - #[link(name = "unwind", kind = "static", modifiers = "-bundle")] - extern "C" {} - } else if #[cfg(feature = "system-llvm-libunwind")] { - #[link(name = "unwind", kind = "static", modifiers = "-bundle", cfg(target_feature = "crt-static"))] - #[link(name = "unwind", cfg(not(target_feature = "crt-static")))] - extern "C" {} - } else { - #[link(name = "unwind", kind = "static", modifiers = "-bundle", cfg(target_feature = "crt-static"))] - #[link(name = "gcc_s", cfg(not(target_feature = "crt-static")))] - extern "C" {} - } -} - -// This is the same as musl except that we default to using the system libunwind -// instead of libgcc. -#[cfg(target_env = "ohos")] -cfg_if::cfg_if! { - if #[cfg(all(feature = "llvm-libunwind", feature = "system-llvm-libunwind"))] { - compile_error!("`llvm-libunwind` and `system-llvm-libunwind` cannot be enabled at the same time"); - } else if #[cfg(feature = "llvm-libunwind")] { - #[link(name = "unwind", kind = "static", modifiers = "-bundle")] - extern "C" {} - } else { - #[link(name = "unwind", kind = "static", modifiers = "-bundle", cfg(target_feature = "crt-static"))] - #[link(name = "unwind", cfg(not(target_feature = "crt-static")))] - extern "C" {} - } -} - -#[cfg(target_os = "android")] -cfg_if::cfg_if! { - if #[cfg(feature = "llvm-libunwind")] { - compile_error!("`llvm-libunwind` is not supported for Android targets"); - } else { - #[link(name = "unwind", kind = "static", modifiers = "-bundle", cfg(target_feature = "crt-static"))] - #[link(name = "unwind", cfg(not(target_feature = "crt-static")))] - extern "C" {} - } -} -// Android's unwinding library depends on dl_iterate_phdr in `libdl`. -#[cfg(target_os = "android")] -#[link(name = "dl", kind = "static", modifiers = "-bundle", cfg(target_feature = "crt-static"))] -#[link(name = "dl", cfg(not(target_feature = "crt-static")))] -extern "C" {} - -// When building with crt-static, we get `gcc_eh` from the `libc` crate, since -// glibc needs it, and needs it listed later on the linker command line. We -// don't want to duplicate it here. -#[cfg(all( - target_os = "linux", - any(target_env = "gnu", target_env = "uclibc"), - not(feature = "llvm-libunwind"), - not(feature = "system-llvm-libunwind") -))] -#[link(name = "gcc_s", cfg(not(target_feature = "crt-static")))] -extern "C" {} - -#[cfg(all( - target_os = "linux", - any(target_env = "gnu", target_env = "uclibc"), - not(feature = "llvm-libunwind"), - feature = "system-llvm-libunwind" -))] -#[link(name = "unwind", cfg(not(target_feature = "crt-static")))] -extern "C" {} - -#[cfg(target_os = "redox")] -#[link(name = "gcc_eh", kind = "static", modifiers = "-bundle", cfg(target_feature = "crt-static"))] -#[link(name = "gcc_s", cfg(not(target_feature = "crt-static")))] -extern "C" {} - -#[cfg(all(target_vendor = "fortanix", target_env = "sgx"))] -#[link(name = "unwind", kind = "static", modifiers = "-bundle")] -extern "C" {} - -#[cfg(target_os = "netbsd")] -#[link(name = "gcc_s")] -extern "C" {} - -#[cfg(target_os = "freebsd")] -#[link(name = "gcc", kind = "static", modifiers = "-bundle", cfg(target_feature = "crt-static"))] -#[link(name = "gcc_eh", kind = "static", modifiers = "-bundle", cfg(target_feature = "crt-static"))] -#[link(name = "gcc_s", cfg(not(target_feature = "crt-static")))] -extern "C" {} - -#[cfg(all(target_os = "openbsd", target_arch = "sparc64"))] -#[link(name = "gcc")] -extern "C" {} - -#[cfg(all(target_os = "openbsd", not(target_arch = "sparc64")))] -#[link(name = "c++abi")] -extern "C" {} - -#[cfg(any(target_os = "solaris", target_os = "illumos"))] -#[link(name = "gcc_s")] -extern "C" {} - -#[cfg(target_os = "dragonfly")] -#[link(name = "gcc_pic")] -extern "C" {} - -#[cfg(target_os = "haiku")] -#[link(name = "gcc_s")] -extern "C" {} - -#[cfg(target_os = "aix")] -#[link(name = "unwind")] -extern "C" {} - -#[cfg(target_os = "nto")] -#[link(name = "gcc_s")] -extern "C" {} - -#[cfg(target_os = "hurd")] -#[link(name = "gcc_s")] -extern "C" {} diff --git a/library/unwind/src/libunwind.rs b/library/unwind/src/libunwind.rs deleted file mode 100644 index e5e28f32e4dbf..0000000000000 --- a/library/unwind/src/libunwind.rs +++ /dev/null @@ -1,314 +0,0 @@ -#![allow(nonstandard_style)] - -use core::ffi::{c_int, c_void}; - -#[repr(C)] -#[derive(Debug, Copy, Clone, PartialEq)] -pub enum _Unwind_Reason_Code { - _URC_NO_REASON = 0, - _URC_FOREIGN_EXCEPTION_CAUGHT = 1, - _URC_FATAL_PHASE2_ERROR = 2, - _URC_FATAL_PHASE1_ERROR = 3, - _URC_NORMAL_STOP = 4, - _URC_END_OF_STACK = 5, - _URC_HANDLER_FOUND = 6, - _URC_INSTALL_CONTEXT = 7, - _URC_CONTINUE_UNWIND = 8, - _URC_FAILURE = 9, // used only by ARM EHABI -} -pub use _Unwind_Reason_Code::*; - -pub type _Unwind_Exception_Class = u64; -pub type _Unwind_Word = *const u8; -pub type _Unwind_Ptr = *const u8; -pub type _Unwind_Trace_Fn = - extern "C" fn(ctx: *mut _Unwind_Context, arg: *mut c_void) -> _Unwind_Reason_Code; - -#[cfg(target_arch = "x86")] -pub const unwinder_private_data_size: usize = 5; - -#[cfg(all(target_arch = "x86_64", not(target_os = "windows")))] -pub const unwinder_private_data_size: usize = 2; - -#[cfg(all(target_arch = "x86_64", target_os = "windows"))] -pub const unwinder_private_data_size: usize = 6; - -#[cfg(all(target_arch = "arm", not(all(target_vendor = "apple", not(target_os = "watchos")))))] -pub const unwinder_private_data_size: usize = 20; - -#[cfg(all(target_arch = "arm", all(target_vendor = "apple", not(target_os = "watchos"))))] -pub const unwinder_private_data_size: usize = 5; - -#[cfg(all(target_arch = "aarch64", target_pointer_width = "64", not(target_os = "windows")))] -pub const unwinder_private_data_size: usize = 2; - -#[cfg(all(target_arch = "aarch64", target_pointer_width = "64", target_os = "windows"))] -pub const unwinder_private_data_size: usize = 6; - -#[cfg(all(target_arch = "aarch64", target_pointer_width = "32"))] -pub const unwinder_private_data_size: usize = 5; - -#[cfg(target_arch = "m68k")] -pub const unwinder_private_data_size: usize = 2; - -#[cfg(any(target_arch = "mips", target_arch = "mips32r6"))] -pub const unwinder_private_data_size: usize = 2; - -#[cfg(target_arch = "csky")] -pub const unwinder_private_data_size: usize = 2; - -#[cfg(any(target_arch = "mips64", target_arch = "mips64r6"))] -pub const unwinder_private_data_size: usize = 2; - -#[cfg(any(target_arch = "powerpc", target_arch = "powerpc64"))] -pub const unwinder_private_data_size: usize = 2; - -#[cfg(target_arch = "s390x")] -pub const unwinder_private_data_size: usize = 2; - -#[cfg(any(target_arch = "sparc", target_arch = "sparc64"))] -pub const unwinder_private_data_size: usize = 2; - -#[cfg(any(target_arch = "riscv64", target_arch = "riscv32"))] -pub const unwinder_private_data_size: usize = 2; - -#[cfg(target_os = "emscripten")] -pub const unwinder_private_data_size: usize = 20; - -#[cfg(all(target_arch = "hexagon", target_os = "linux"))] -pub const unwinder_private_data_size: usize = 35; - -#[cfg(target_arch = "loongarch64")] -pub const unwinder_private_data_size: usize = 2; - -#[repr(C)] -pub struct _Unwind_Exception { - pub exception_class: _Unwind_Exception_Class, - pub exception_cleanup: _Unwind_Exception_Cleanup_Fn, - pub private: [_Unwind_Word; unwinder_private_data_size], -} - -pub enum _Unwind_Context {} - -pub type _Unwind_Exception_Cleanup_Fn = - Option; - -// FIXME: The `#[link]` attributes on `extern "C"` block marks those symbols declared in -// the block are reexported in dylib build of std. This is needed when build rustc with -// feature `llvm-libunwind`, as no other cdylib will provided those _Unwind_* symbols. -// However the `link` attribute is duplicated multiple times and does not just export symbol, -// a better way to manually export symbol would be another attribute like `#[export]`. -// See the logic in function rustc_codegen_ssa::src::back::exported_symbols, module -// rustc_codegen_ssa::src::back::symbol_export, rustc_middle::middle::exported_symbols -// and RFC 2841 -#[cfg_attr( - any( - all( - feature = "llvm-libunwind", - any(target_os = "fuchsia", target_os = "linux", target_os = "xous") - ), - all(target_os = "windows", target_env = "gnu", target_abi = "llvm") - ), - link(name = "unwind", kind = "static", modifiers = "-bundle") -)] -extern "C-unwind" { - pub fn _Unwind_Resume(exception: *mut _Unwind_Exception) -> !; -} -extern "C" { - pub fn _Unwind_DeleteException(exception: *mut _Unwind_Exception); - pub fn _Unwind_GetLanguageSpecificData(ctx: *mut _Unwind_Context) -> *mut c_void; - pub fn _Unwind_GetRegionStart(ctx: *mut _Unwind_Context) -> _Unwind_Ptr; - pub fn _Unwind_GetTextRelBase(ctx: *mut _Unwind_Context) -> _Unwind_Ptr; - pub fn _Unwind_GetDataRelBase(ctx: *mut _Unwind_Context) -> _Unwind_Ptr; -} - -cfg_if::cfg_if! { -if #[cfg(any(all(target_vendor = "apple", not(target_os = "watchos")), target_os = "netbsd", not(target_arch = "arm")))] { - // Not ARM EHABI - #[repr(C)] - #[derive(Copy, Clone, PartialEq)] - pub enum _Unwind_Action { - _UA_SEARCH_PHASE = 1, - _UA_CLEANUP_PHASE = 2, - _UA_HANDLER_FRAME = 4, - _UA_FORCE_UNWIND = 8, - _UA_END_OF_STACK = 16, - } - pub use _Unwind_Action::*; - - #[cfg_attr( - all(feature = "llvm-libunwind", any(target_os = "fuchsia", target_os = "linux", target_os = "xous")), - link(name = "unwind", kind = "static", modifiers = "-bundle") - )] - extern "C" { - pub fn _Unwind_GetGR(ctx: *mut _Unwind_Context, reg_index: c_int) -> _Unwind_Word; - pub fn _Unwind_SetGR(ctx: *mut _Unwind_Context, reg_index: c_int, value: _Unwind_Word); - pub fn _Unwind_GetIP(ctx: *mut _Unwind_Context) -> _Unwind_Word; - pub fn _Unwind_SetIP(ctx: *mut _Unwind_Context, value: _Unwind_Word); - pub fn _Unwind_GetIPInfo(ctx: *mut _Unwind_Context, ip_before_insn: *mut c_int) - -> _Unwind_Word; - pub fn _Unwind_FindEnclosingFunction(pc: *mut c_void) -> *mut c_void; - } - -} else { - // ARM EHABI - #[repr(C)] - #[derive(Copy, Clone, PartialEq)] - pub enum _Unwind_State { - _US_VIRTUAL_UNWIND_FRAME = 0, - _US_UNWIND_FRAME_STARTING = 1, - _US_UNWIND_FRAME_RESUME = 2, - _US_ACTION_MASK = 3, - _US_FORCE_UNWIND = 8, - _US_END_OF_STACK = 16, - } - pub use _Unwind_State::*; - - #[repr(C)] - enum _Unwind_VRS_Result { - _UVRSR_OK = 0, - _UVRSR_NOT_IMPLEMENTED = 1, - _UVRSR_FAILED = 2, - } - #[repr(C)] - enum _Unwind_VRS_RegClass { - _UVRSC_CORE = 0, - _UVRSC_VFP = 1, - _UVRSC_FPA = 2, - _UVRSC_WMMXD = 3, - _UVRSC_WMMXC = 4, - } - use _Unwind_VRS_RegClass::*; - #[repr(C)] - enum _Unwind_VRS_DataRepresentation { - _UVRSD_UINT32 = 0, - _UVRSD_VFPX = 1, - _UVRSD_FPAX = 2, - _UVRSD_UINT64 = 3, - _UVRSD_FLOAT = 4, - _UVRSD_DOUBLE = 5, - } - use _Unwind_VRS_DataRepresentation::*; - - pub const UNWIND_POINTER_REG: c_int = 12; - pub const UNWIND_SP_REG: c_int = 13; - pub const UNWIND_IP_REG: c_int = 15; - - #[cfg_attr( - all(feature = "llvm-libunwind", any(target_os = "fuchsia", target_os = "linux", target_os = "xous")), - link(name = "unwind", kind = "static", modifiers = "-bundle") - )] - extern "C" { - fn _Unwind_VRS_Get(ctx: *mut _Unwind_Context, - regclass: _Unwind_VRS_RegClass, - regno: _Unwind_Word, - repr: _Unwind_VRS_DataRepresentation, - data: *mut c_void) - -> _Unwind_VRS_Result; - - fn _Unwind_VRS_Set(ctx: *mut _Unwind_Context, - regclass: _Unwind_VRS_RegClass, - regno: _Unwind_Word, - repr: _Unwind_VRS_DataRepresentation, - data: *mut c_void) - -> _Unwind_VRS_Result; - } - - // On Android or ARM/Linux, these are implemented as macros: - - pub unsafe fn _Unwind_GetGR(ctx: *mut _Unwind_Context, reg_index: c_int) -> _Unwind_Word { - let mut val: _Unwind_Word = core::ptr::null(); - _Unwind_VRS_Get(ctx, _UVRSC_CORE, reg_index as _Unwind_Word, _UVRSD_UINT32, - core::ptr::addr_of_mut!(val) as *mut c_void); - val - } - - pub unsafe fn _Unwind_SetGR(ctx: *mut _Unwind_Context, reg_index: c_int, value: _Unwind_Word) { - let mut value = value; - _Unwind_VRS_Set(ctx, _UVRSC_CORE, reg_index as _Unwind_Word, _UVRSD_UINT32, - core::ptr::addr_of_mut!(value) as *mut c_void); - } - - pub unsafe fn _Unwind_GetIP(ctx: *mut _Unwind_Context) - -> _Unwind_Word { - let val = _Unwind_GetGR(ctx, UNWIND_IP_REG); - val.map_addr(|v| v & !1) - } - - pub unsafe fn _Unwind_SetIP(ctx: *mut _Unwind_Context, - value: _Unwind_Word) { - // Propagate thumb bit to instruction pointer - let thumb_state = _Unwind_GetGR(ctx, UNWIND_IP_REG).addr() & 1; - let value = value.map_addr(|v| v | thumb_state); - _Unwind_SetGR(ctx, UNWIND_IP_REG, value); - } - - pub unsafe fn _Unwind_GetIPInfo(ctx: *mut _Unwind_Context, - ip_before_insn: *mut c_int) - -> _Unwind_Word { - *ip_before_insn = 0; - _Unwind_GetIP(ctx) - } - - // This function also doesn't exist on Android or ARM/Linux, so make it a no-op - pub unsafe fn _Unwind_FindEnclosingFunction(pc: *mut c_void) -> *mut c_void { - pc - } -} -} // cfg_if! - -cfg_if::cfg_if! { -if #[cfg(all(target_vendor = "apple", not(target_os = "watchos"), target_arch = "arm"))] { - // 32-bit ARM Apple (except for watchOS) uses SjLj and does not provide - // _Unwind_Backtrace() - extern "C-unwind" { - pub fn _Unwind_SjLj_RaiseException(e: *mut _Unwind_Exception) -> _Unwind_Reason_Code; - } - - pub use _Unwind_SjLj_RaiseException as _Unwind_RaiseException; -} else { - #[cfg_attr( - all(feature = "llvm-libunwind", any(target_os = "fuchsia", target_os = "linux", target_os = "xous")), - link(name = "unwind", kind = "static", modifiers = "-bundle") - )] - extern "C-unwind" { - pub fn _Unwind_RaiseException(exception: *mut _Unwind_Exception) -> _Unwind_Reason_Code; - } - #[cfg_attr( - all(feature = "llvm-libunwind", any(target_os = "fuchsia", target_os = "linux", target_os = "xous")), - link(name = "unwind", kind = "static", modifiers = "-bundle") - )] - extern "C" { - pub fn _Unwind_Backtrace(trace: _Unwind_Trace_Fn, - trace_argument: *mut c_void) - -> _Unwind_Reason_Code; - } -} -} // cfg_if! - -cfg_if::cfg_if! { -if #[cfg(all(windows, any(target_arch = "aarch64", target_arch = "x86_64"), target_env = "gnu"))] { - // We declare these as opaque types. This is fine since you just need to - // pass them to _GCC_specific_handler and forget about them. - pub enum EXCEPTION_RECORD {} - pub type LPVOID = *mut c_void; - pub enum CONTEXT {} - pub enum DISPATCHER_CONTEXT {} - pub type EXCEPTION_DISPOSITION = c_int; - type PersonalityFn = unsafe extern "C" fn(version: c_int, - actions: _Unwind_Action, - exception_class: _Unwind_Exception_Class, - exception_object: *mut _Unwind_Exception, - context: *mut _Unwind_Context) - -> _Unwind_Reason_Code; - - extern "C" { - pub fn _GCC_specific_handler(exceptionRecord: *mut EXCEPTION_RECORD, - establisherFrame: LPVOID, - contextRecord: *mut CONTEXT, - dispatcherContext: *mut DISPATCHER_CONTEXT, - personality: PersonalityFn) - -> EXCEPTION_DISPOSITION; - } -} -} // cfg_if! diff --git a/library/unwind/src/unwinding.rs b/library/unwind/src/unwinding.rs deleted file mode 100644 index 083acaeb56af2..0000000000000 --- a/library/unwind/src/unwinding.rs +++ /dev/null @@ -1,105 +0,0 @@ -#![allow(nonstandard_style)] - -use core::ffi::{c_int, c_void}; - -#[repr(C)] -#[derive(Copy, Clone, PartialEq)] -pub enum _Unwind_Action { - _UA_SEARCH_PHASE = 1, - _UA_CLEANUP_PHASE = 2, - _UA_HANDLER_FRAME = 4, - _UA_FORCE_UNWIND = 8, - _UA_END_OF_STACK = 16, -} -pub use _Unwind_Action::*; - -#[repr(C)] -#[derive(Debug, Copy, Clone, PartialEq)] -pub enum _Unwind_Reason_Code { - _URC_NO_REASON = 0, - _URC_FOREIGN_EXCEPTION_CAUGHT = 1, - _URC_FATAL_PHASE2_ERROR = 2, - _URC_FATAL_PHASE1_ERROR = 3, - _URC_NORMAL_STOP = 4, - _URC_END_OF_STACK = 5, - _URC_HANDLER_FOUND = 6, - _URC_INSTALL_CONTEXT = 7, - _URC_CONTINUE_UNWIND = 8, - _URC_FAILURE = 9, // used only by ARM EHABI -} -pub use _Unwind_Reason_Code::*; - -pub use unwinding::abi::UnwindContext; -pub use unwinding::abi::UnwindException; -pub enum _Unwind_Context {} - -pub use unwinding::custom_eh_frame_finder::{ - set_custom_eh_frame_finder, EhFrameFinder, FrameInfo, FrameInfoKind, -}; - -pub type _Unwind_Exception_Class = u64; -pub type _Unwind_Word = *const u8; -pub type _Unwind_Ptr = *const u8; - -pub const unwinder_private_data_size: usize = core::mem::size_of::() - - core::mem::size_of::<_Unwind_Exception_Class>() - - core::mem::size_of::<_Unwind_Exception_Cleanup_Fn>(); - -pub type _Unwind_Exception_Cleanup_Fn = - Option; - -#[repr(C)] -pub struct _Unwind_Exception { - pub exception_class: _Unwind_Exception_Class, - pub exception_cleanup: _Unwind_Exception_Cleanup_Fn, - pub private: [_Unwind_Word; unwinder_private_data_size], -} - -pub unsafe fn _Unwind_GetDataRelBase(ctx: *mut _Unwind_Context) -> _Unwind_Ptr { - let ctx = unsafe { &mut *(ctx as *mut UnwindContext<'_>) }; - unwinding::abi::_Unwind_GetDataRelBase(ctx) as _Unwind_Ptr -} - -pub unsafe fn _Unwind_GetTextRelBase(ctx: *mut _Unwind_Context) -> _Unwind_Ptr { - let ctx = unsafe { &mut *(ctx as *mut UnwindContext<'_>) }; - unwinding::abi::_Unwind_GetTextRelBase(ctx) as _Unwind_Ptr -} - -pub unsafe fn _Unwind_GetRegionStart(ctx: *mut _Unwind_Context) -> _Unwind_Ptr { - let ctx = unsafe { &mut *(ctx as *mut UnwindContext<'_>) }; - unwinding::abi::_Unwind_GetRegionStart(ctx) as _Unwind_Ptr -} - -pub unsafe fn _Unwind_SetGR(ctx: *mut _Unwind_Context, reg_index: c_int, value: _Unwind_Word) { - let ctx = unsafe { &mut *(ctx as *mut UnwindContext<'_>) }; - unwinding::abi::_Unwind_SetGR(ctx, reg_index, value as usize) -} - -pub unsafe fn _Unwind_SetIP(ctx: *mut _Unwind_Context, value: _Unwind_Word) { - let ctx = unsafe { &mut *(ctx as *mut UnwindContext<'_>) }; - unwinding::abi::_Unwind_SetIP(ctx, value as usize) -} - -pub unsafe fn _Unwind_GetIPInfo( - ctx: *mut _Unwind_Context, - ip_before_insn: *mut c_int, -) -> _Unwind_Word { - let ctx = unsafe { &mut *(ctx as *mut UnwindContext<'_>) }; - let ip_before_insn = unsafe { &mut *(ip_before_insn as *mut c_int) }; - unsafe { &*(unwinding::abi::_Unwind_GetIPInfo(ctx, ip_before_insn) as _Unwind_Word) } -} - -pub unsafe fn _Unwind_GetLanguageSpecificData(ctx: *mut _Unwind_Context) -> *mut c_void { - let ctx = unsafe { &mut *(ctx as *mut UnwindContext<'_>) }; - unwinding::abi::_Unwind_GetLanguageSpecificData(ctx) -} - -pub unsafe fn _Unwind_RaiseException(exception: *mut _Unwind_Exception) -> _Unwind_Reason_Code { - let exception = unsafe { &mut *(exception as *mut UnwindException) }; - unsafe { core::mem::transmute(unwinding::abi::_Unwind_RaiseException(exception)) } -} - -pub unsafe fn _Unwind_DeleteException(exception: *mut _Unwind_Exception) { - let exception = unsafe { &mut *(exception as *mut UnwindException) }; - unsafe { unwinding::abi::_Unwind_DeleteException(exception) } -} diff --git a/library/unwind/src/wasm.rs b/library/unwind/src/wasm.rs deleted file mode 100644 index f4ffac1ba16da..0000000000000 --- a/library/unwind/src/wasm.rs +++ /dev/null @@ -1,68 +0,0 @@ -//! A shim for libunwind implemented in terms of the native wasm `throw` instruction. - -#![allow(nonstandard_style)] - -#[repr(C)] -#[derive(Debug, Copy, Clone, PartialEq)] -pub enum _Unwind_Reason_Code { - _URC_NO_REASON = 0, - _URC_FOREIGN_EXCEPTION_CAUGHT = 1, - _URC_FATAL_PHASE2_ERROR = 2, - _URC_FATAL_PHASE1_ERROR = 3, - _URC_NORMAL_STOP = 4, - _URC_END_OF_STACK = 5, - _URC_HANDLER_FOUND = 6, - _URC_INSTALL_CONTEXT = 7, - _URC_CONTINUE_UNWIND = 8, - _URC_FAILURE = 9, // used only by ARM EHABI -} -pub use _Unwind_Reason_Code::*; - -pub type _Unwind_Exception_Class = u64; -pub type _Unwind_Word = *const u8; - -pub const unwinder_private_data_size: usize = 2; - -#[repr(C)] -pub struct _Unwind_Exception { - pub exception_class: _Unwind_Exception_Class, - pub exception_cleanup: _Unwind_Exception_Cleanup_Fn, - pub private: [_Unwind_Word; unwinder_private_data_size], -} - -pub type _Unwind_Exception_Cleanup_Fn = - Option; - -pub unsafe fn _Unwind_DeleteException(exception: *mut _Unwind_Exception) { - if let Some(exception_cleanup) = unsafe { (*exception).exception_cleanup } { - exception_cleanup(_URC_FOREIGN_EXCEPTION_CAUGHT, exception); - } -} - -pub unsafe fn _Unwind_RaiseException(exception: *mut _Unwind_Exception) -> _Unwind_Reason_Code { - #[cfg(panic = "unwind")] - extern "C" { - /// LLVM lowers this intrinsic to the `throw` instruction. - // FIXME(coolreader18): move to stdarch - #[link_name = "llvm.wasm.throw"] - fn wasm_throw(tag: i32, ptr: *mut u8) -> !; - } - - // The wasm `throw` instruction takes a "tag", which differentiates certain - // types of exceptions from others. LLVM currently just identifies these - // via integers, with 0 corresponding to C++ exceptions and 1 to C setjmp()/longjmp(). - // Ideally, we'd be able to choose something unique for Rust, but for now, - // we pretend to be C++ and implement the Itanium exception-handling ABI. - cfg_if::cfg_if! { - // for now, unless we're -Zbuild-std with panic=unwind, never codegen a throw. - if #[cfg(panic = "unwind")] { - wasm_throw(0, exception.cast()) - } else { - let _ = exception; - #[cfg(target_arch = "wasm32")] - core::arch::wasm32::unreachable(); - #[cfg(target_arch = "wasm64")] - core::arch::wasm64::unreachable(); - } - } -}

(&self, mut pred: P) -> usize - where - P: FnMut(&T) -> bool, - { - let (front, back) = self.as_slices(); - - if let Some(true) = back.first().map(|v| pred(v)) { - back.partition_point(pred) + front.len() - } else { - front.partition_point(pred) - } - } -} - -impl VecDeque { - /// Modifies the deque in-place so that `len()` is equal to new_len, - /// either by removing excess elements from the back or by appending clones of `value` - /// to the back. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let mut buf = VecDeque::new(); - /// buf.push_back(5); - /// buf.push_back(10); - /// buf.push_back(15); - /// assert_eq!(buf, [5, 10, 15]); - /// - /// buf.resize(2, 0); - /// assert_eq!(buf, [5, 10]); - /// - /// buf.resize(5, 20); - /// assert_eq!(buf, [5, 10, 20, 20, 20]); - /// ``` - #[stable(feature = "deque_extras", since = "1.16.0")] - pub fn resize(&mut self, new_len: usize, value: T) { - if new_len > self.len() { - let extra = new_len - self.len(); - self.extend(repeat_n(value, extra)) - } else { - self.truncate(new_len); - } - } -} - -/// Returns the index in the underlying buffer for a given logical element index. -#[inline] -fn wrap_index(logical_index: usize, capacity: usize) -> usize { - debug_assert!( - (logical_index == 0 && capacity == 0) - || logical_index < capacity - || (logical_index - capacity) < capacity - ); - if logical_index >= capacity { logical_index - capacity } else { logical_index } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for VecDeque { - fn eq(&self, other: &Self) -> bool { - if self.len != other.len() { - return false; - } - let (sa, sb) = self.as_slices(); - let (oa, ob) = other.as_slices(); - if sa.len() == oa.len() { - sa == oa && sb == ob - } else if sa.len() < oa.len() { - // Always divisible in three sections, for example: - // self: [a b c|d e f] - // other: [0 1 2 3|4 5] - // front = 3, mid = 1, - // [a b c] == [0 1 2] && [d] == [3] && [e f] == [4 5] - let front = sa.len(); - let mid = oa.len() - front; - - let (oa_front, oa_mid) = oa.split_at(front); - let (sb_mid, sb_back) = sb.split_at(mid); - debug_assert_eq!(sa.len(), oa_front.len()); - debug_assert_eq!(sb_mid.len(), oa_mid.len()); - debug_assert_eq!(sb_back.len(), ob.len()); - sa == oa_front && sb_mid == oa_mid && sb_back == ob - } else { - let front = oa.len(); - let mid = sa.len() - front; - - let (sa_front, sa_mid) = sa.split_at(front); - let (ob_mid, ob_back) = ob.split_at(mid); - debug_assert_eq!(sa_front.len(), oa.len()); - debug_assert_eq!(sa_mid.len(), ob_mid.len()); - debug_assert_eq!(sb.len(), ob_back.len()); - sa_front == oa && sa_mid == ob_mid && sb == ob_back - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Eq for VecDeque {} - -__impl_slice_eq1! { [] VecDeque, Vec, } -__impl_slice_eq1! { [] VecDeque, &[U], } -__impl_slice_eq1! { [] VecDeque, &mut [U], } -__impl_slice_eq1! { [const N: usize] VecDeque, [U; N], } -__impl_slice_eq1! { [const N: usize] VecDeque, &[U; N], } -__impl_slice_eq1! { [const N: usize] VecDeque, &mut [U; N], } - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialOrd for VecDeque { - fn partial_cmp(&self, other: &Self) -> Option { - self.iter().partial_cmp(other.iter()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for VecDeque { - #[inline] - fn cmp(&self, other: &Self) -> Ordering { - self.iter().cmp(other.iter()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Hash for VecDeque { - fn hash(&self, state: &mut H) { - state.write_length_prefix(self.len); - // It's not possible to use Hash::hash_slice on slices - // returned by as_slices method as their length can vary - // in otherwise identical deques. - // - // Hasher only guarantees equivalence for the exact same - // set of calls to its methods. - self.iter().for_each(|elem| elem.hash(state)); - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Index for VecDeque { - type Output = T; - - #[inline] - fn index(&self, index: usize) -> &T { - self.get(index).expect("Out of bounds access") - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl IndexMut for VecDeque { - #[inline] - fn index_mut(&mut self, index: usize) -> &mut T { - self.get_mut(index).expect("Out of bounds access") - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl FromIterator for VecDeque { - fn from_iter>(iter: I) -> VecDeque { - SpecFromIter::spec_from_iter(iter.into_iter()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl IntoIterator for VecDeque { - type Item = T; - type IntoIter = IntoIter; - - /// Consumes the deque into a front-to-back iterator yielding elements by - /// value. - fn into_iter(self) -> IntoIter { - IntoIter::new(self) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T, A: Allocator> IntoIterator for &'a VecDeque { - type Item = &'a T; - type IntoIter = Iter<'a, T>; - - fn into_iter(self) -> Iter<'a, T> { - self.iter() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T, A: Allocator> IntoIterator for &'a mut VecDeque { - type Item = &'a mut T; - type IntoIter = IterMut<'a, T>; - - fn into_iter(self) -> IterMut<'a, T> { - self.iter_mut() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Extend for VecDeque { - fn extend>(&mut self, iter: I) { - >::spec_extend(self, iter.into_iter()); - } - - #[inline] - fn extend_one(&mut self, elem: T) { - self.push_back(elem); - } - - #[inline] - fn extend_reserve(&mut self, additional: usize) { - self.reserve(additional); - } -} - -#[stable(feature = "extend_ref", since = "1.2.0")] -impl<'a, T: 'a + Copy, A: Allocator> Extend<&'a T> for VecDeque { - fn extend>(&mut self, iter: I) { - self.spec_extend(iter.into_iter()); - } - - #[inline] - fn extend_one(&mut self, &elem: &'a T) { - self.push_back(elem); - } - - #[inline] - fn extend_reserve(&mut self, additional: usize) { - self.reserve(additional); - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for VecDeque { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_list().entries(self.iter()).finish() - } -} - -#[stable(feature = "vecdeque_vec_conversions", since = "1.10.0")] -impl From> for VecDeque { - /// Turn a [`Vec`] into a [`VecDeque`]. - /// - /// [`Vec`]: crate::vec::Vec - /// [`VecDeque`]: crate::collections::VecDeque - /// - /// This conversion is guaranteed to run in *O*(1) time - /// and to not re-allocate the `Vec`'s buffer or allocate - /// any additional memory. - #[inline] - fn from(other: Vec) -> Self { - let (ptr, len, cap, alloc) = other.into_raw_parts_with_alloc(); - Self { head: 0, len, buf: unsafe { RawVec::from_raw_parts_in(ptr, cap, alloc) } } - } -} - -#[stable(feature = "vecdeque_vec_conversions", since = "1.10.0")] -impl From> for Vec { - /// Turn a [`VecDeque`] into a [`Vec`]. - /// - /// [`Vec`]: crate::vec::Vec - /// [`VecDeque`]: crate::collections::VecDeque - /// - /// This never needs to re-allocate, but does need to do *O*(*n*) data movement if - /// the circular buffer doesn't happen to be at the beginning of the allocation. - /// - /// # Examples - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// // This one is *O*(1). - /// let deque: VecDeque<_> = (1..5).collect(); - /// let ptr = deque.as_slices().0.as_ptr(); - /// let vec = Vec::from(deque); - /// assert_eq!(vec, [1, 2, 3, 4]); - /// assert_eq!(vec.as_ptr(), ptr); - /// - /// // This one needs data rearranging. - /// let mut deque: VecDeque<_> = (1..5).collect(); - /// deque.push_front(9); - /// deque.push_front(8); - /// let ptr = deque.as_slices().1.as_ptr(); - /// let vec = Vec::from(deque); - /// assert_eq!(vec, [8, 9, 1, 2, 3, 4]); - /// assert_eq!(vec.as_ptr(), ptr); - /// ``` - fn from(mut other: VecDeque) -> Self { - other.make_contiguous(); - - unsafe { - let other = ManuallyDrop::new(other); - let buf = other.buf.ptr(); - let len = other.len(); - let cap = other.capacity(); - let alloc = ptr::read(other.allocator()); - - if other.head != 0 { - ptr::copy(buf.add(other.head), buf, len); - } - Vec::from_raw_parts_in(buf, len, cap, alloc) - } - } -} - -#[stable(feature = "std_collections_from_array", since = "1.56.0")] -impl From<[T; N]> for VecDeque { - /// Converts a `[T; N]` into a `VecDeque`. - /// - /// ``` - /// use std::collections::VecDeque; - /// - /// let deq1 = VecDeque::from([1, 2, 3, 4]); - /// let deq2: VecDeque<_> = [1, 2, 3, 4].into(); - /// assert_eq!(deq1, deq2); - /// ``` - fn from(arr: [T; N]) -> Self { - let mut deq = VecDeque::with_capacity(N); - let arr = ManuallyDrop::new(arr); - if !::IS_ZST { - // SAFETY: VecDeque::with_capacity ensures that there is enough capacity. - unsafe { - ptr::copy_nonoverlapping(arr.as_ptr(), deq.ptr(), N); - } - } - deq.head = 0; - deq.len = N; - deq - } -} diff --git a/library/alloc/src/collections/vec_deque/spec_extend.rs b/library/alloc/src/collections/vec_deque/spec_extend.rs deleted file mode 100644 index dccf40ccb38aa..0000000000000 --- a/library/alloc/src/collections/vec_deque/spec_extend.rs +++ /dev/null @@ -1,123 +0,0 @@ -use crate::alloc::Allocator; -use crate::vec; -use core::iter::TrustedLen; -use core::slice; - -use super::VecDeque; - -// Specialization trait used for VecDeque::extend -pub(super) trait SpecExtend { - fn spec_extend(&mut self, iter: I); -} - -impl SpecExtend for VecDeque -where - I: Iterator, -{ - default fn spec_extend(&mut self, mut iter: I) { - // This function should be the moral equivalent of: - // - // for item in iter { - // self.push_back(item); - // } - - // May only be called if `deque.len() < deque.capacity()` - unsafe fn push_unchecked(deque: &mut VecDeque, element: T) { - // SAFETY: Because of the precondition, it's guaranteed that there is space - // in the logical array after the last element. - unsafe { deque.buffer_write(deque.to_physical_idx(deque.len), element) }; - // This can't overflow because `deque.len() < deque.capacity() <= usize::MAX`. - deque.len += 1; - } - - while let Some(element) = iter.next() { - let (lower, _) = iter.size_hint(); - self.reserve(lower.saturating_add(1)); - - // SAFETY: We just reserved space for at least one element. - unsafe { push_unchecked(self, element) }; - - // Inner loop to avoid repeatedly calling `reserve`. - while self.len < self.capacity() { - let Some(element) = iter.next() else { - return; - }; - // SAFETY: The loop condition guarantees that `self.len() < self.capacity()`. - unsafe { push_unchecked(self, element) }; - } - } - } -} - -impl SpecExtend for VecDeque -where - I: TrustedLen, -{ - default fn spec_extend(&mut self, iter: I) { - // This is the case for a TrustedLen iterator. - let (low, high) = iter.size_hint(); - if let Some(additional) = high { - debug_assert_eq!( - low, - additional, - "TrustedLen iterator's size hint is not exact: {:?}", - (low, high) - ); - self.reserve(additional); - - let written = unsafe { - self.write_iter_wrapping(self.to_physical_idx(self.len), iter, additional) - }; - - debug_assert_eq!( - additional, written, - "The number of items written to VecDeque doesn't match the TrustedLen size hint" - ); - } else { - // Per TrustedLen contract a `None` upper bound means that the iterator length - // truly exceeds usize::MAX, which would eventually lead to a capacity overflow anyway. - // Since the other branch already panics eagerly (via `reserve()`) we do the same here. - // This avoids additional codegen for a fallback code path which would eventually - // panic anyway. - panic!("capacity overflow"); - } - } -} - -impl SpecExtend> for VecDeque { - fn spec_extend(&mut self, mut iterator: vec::IntoIter) { - let slice = iterator.as_slice(); - self.reserve(slice.len()); - - unsafe { - self.copy_slice(self.to_physical_idx(self.len), slice); - self.len += slice.len(); - } - iterator.forget_remaining_elements(); - } -} - -impl<'a, T: 'a, I, A: Allocator> SpecExtend<&'a T, I> for VecDeque -where - I: Iterator, - T: Copy, -{ - default fn spec_extend(&mut self, iterator: I) { - self.spec_extend(iterator.copied()) - } -} - -impl<'a, T: 'a, A: Allocator> SpecExtend<&'a T, slice::Iter<'a, T>> for VecDeque -where - T: Copy, -{ - fn spec_extend(&mut self, iterator: slice::Iter<'a, T>) { - let slice = iterator.as_slice(); - self.reserve(slice.len()); - - unsafe { - self.copy_slice(self.to_physical_idx(self.len), slice); - self.len += slice.len(); - } - } -} diff --git a/library/alloc/src/collections/vec_deque/spec_from_iter.rs b/library/alloc/src/collections/vec_deque/spec_from_iter.rs deleted file mode 100644 index 2708c7fe10259..0000000000000 --- a/library/alloc/src/collections/vec_deque/spec_from_iter.rs +++ /dev/null @@ -1,33 +0,0 @@ -use super::{IntoIter, VecDeque}; - -/// Specialization trait used for `VecDeque::from_iter` -pub(super) trait SpecFromIter { - fn spec_from_iter(iter: I) -> Self; -} - -impl SpecFromIter for VecDeque -where - I: Iterator, -{ - default fn spec_from_iter(iterator: I) -> Self { - // Since converting is O(1) now, just re-use the `Vec` logic for - // anything where we can't do something extra-special for `VecDeque`, - // especially as that could save us some monomorphization work - // if one uses the same iterators (like slice ones) with both. - crate::vec::Vec::from_iter(iterator).into() - } -} - -impl SpecFromIter> for VecDeque { - #[inline] - fn spec_from_iter(iterator: crate::vec::IntoIter) -> Self { - iterator.into_vecdeque() - } -} - -impl SpecFromIter> for VecDeque { - #[inline] - fn spec_from_iter(iterator: IntoIter) -> Self { - iterator.into_vecdeque() - } -} diff --git a/library/alloc/src/collections/vec_deque/tests.rs b/library/alloc/src/collections/vec_deque/tests.rs deleted file mode 100644 index f8ce4ca97884e..0000000000000 --- a/library/alloc/src/collections/vec_deque/tests.rs +++ /dev/null @@ -1,1174 +0,0 @@ -use core::iter::TrustedLen; - -use super::*; - -#[bench] -fn bench_push_back_100(b: &mut test::Bencher) { - let mut deq = VecDeque::with_capacity(101); - b.iter(|| { - for i in 0..100 { - deq.push_back(i); - } - deq.head = 0; - deq.len = 0; - }) -} - -#[bench] -fn bench_push_front_100(b: &mut test::Bencher) { - let mut deq = VecDeque::with_capacity(101); - b.iter(|| { - for i in 0..100 { - deq.push_front(i); - } - deq.head = 0; - deq.len = 0; - }) -} - -#[bench] -fn bench_pop_back_100(b: &mut test::Bencher) { - let size = 100; - let mut deq = VecDeque::::with_capacity(size + 1); - // We'll mess with private state to pretend like `deq` is filled. - // Make sure the buffer is initialized so that we don't read uninit memory. - unsafe { deq.ptr().write_bytes(0u8, size + 1) }; - - b.iter(|| { - deq.head = 0; - deq.len = 100; - while !deq.is_empty() { - test::black_box(deq.pop_back()); - } - }) -} - -#[bench] -fn bench_retain_whole_10000(b: &mut test::Bencher) { - let size = if cfg!(miri) { 1000 } else { 100000 }; - let v = (1..size).collect::>(); - - b.iter(|| { - let mut v = v.clone(); - v.retain(|x| *x > 0) - }) -} - -#[bench] -fn bench_retain_odd_10000(b: &mut test::Bencher) { - let size = if cfg!(miri) { 1000 } else { 100000 }; - let v = (1..size).collect::>(); - - b.iter(|| { - let mut v = v.clone(); - v.retain(|x| x & 1 == 0) - }) -} - -#[bench] -fn bench_retain_half_10000(b: &mut test::Bencher) { - let size = if cfg!(miri) { 1000 } else { 100000 }; - let v = (1..size).collect::>(); - - b.iter(|| { - let mut v = v.clone(); - v.retain(|x| *x > size / 2) - }) -} - -#[bench] -fn bench_pop_front_100(b: &mut test::Bencher) { - let size = 100; - let mut deq = VecDeque::::with_capacity(size + 1); - // We'll mess with private state to pretend like `deq` is filled. - // Make sure the buffer is initialized so that we don't read uninit memory. - unsafe { deq.ptr().write_bytes(0u8, size + 1) }; - - b.iter(|| { - deq.head = 0; - deq.len = 100; - while !deq.is_empty() { - test::black_box(deq.pop_front()); - } - }) -} - -#[test] -fn test_swap_front_back_remove() { - fn test(back: bool) { - // This test checks that every single combination of tail position and length is tested. - // Capacity 15 should be large enough to cover every case. - let mut tester = VecDeque::with_capacity(15); - let usable_cap = tester.capacity(); - let final_len = usable_cap / 2; - - for len in 0..final_len { - let expected: VecDeque<_> = - if back { (0..len).collect() } else { (0..len).rev().collect() }; - for head_pos in 0..usable_cap { - tester.head = head_pos; - tester.len = 0; - if back { - for i in 0..len * 2 { - tester.push_front(i); - } - for i in 0..len { - assert_eq!(tester.swap_remove_back(i), Some(len * 2 - 1 - i)); - } - } else { - for i in 0..len * 2 { - tester.push_back(i); - } - for i in 0..len { - let idx = tester.len() - 1 - i; - assert_eq!(tester.swap_remove_front(idx), Some(len * 2 - 1 - i)); - } - } - assert!(tester.head <= tester.capacity()); - assert!(tester.len <= tester.capacity()); - assert_eq!(tester, expected); - } - } - } - test(true); - test(false); -} - -#[test] -fn test_insert() { - // This test checks that every single combination of tail position, length, and - // insertion position is tested. Capacity 15 should be large enough to cover every case. - - let mut tester = VecDeque::with_capacity(15); - // can't guarantee we got 15, so have to get what we got. - // 15 would be great, but we will definitely get 2^k - 1, for k >= 4, or else - // this test isn't covering what it wants to - let cap = tester.capacity(); - - // len is the length *after* insertion - let minlen = if cfg!(miri) { cap - 1 } else { 1 }; // Miri is too slow - for len in minlen..cap { - // 0, 1, 2, .., len - 1 - let expected = (0..).take(len).collect::>(); - for head_pos in 0..cap { - for to_insert in 0..len { - tester.head = head_pos; - tester.len = 0; - for i in 0..len { - if i != to_insert { - tester.push_back(i); - } - } - tester.insert(to_insert, to_insert); - assert!(tester.head <= tester.capacity()); - assert!(tester.len <= tester.capacity()); - assert_eq!(tester, expected); - } - } - } -} - -#[test] -fn test_get() { - let mut tester = VecDeque::new(); - tester.push_back(1); - tester.push_back(2); - tester.push_back(3); - - assert_eq!(tester.len(), 3); - - assert_eq!(tester.get(1), Some(&2)); - assert_eq!(tester.get(2), Some(&3)); - assert_eq!(tester.get(0), Some(&1)); - assert_eq!(tester.get(3), None); - - tester.remove(0); - - assert_eq!(tester.len(), 2); - assert_eq!(tester.get(0), Some(&2)); - assert_eq!(tester.get(1), Some(&3)); - assert_eq!(tester.get(2), None); -} - -#[test] -fn test_get_mut() { - let mut tester = VecDeque::new(); - tester.push_back(1); - tester.push_back(2); - tester.push_back(3); - - assert_eq!(tester.len(), 3); - - if let Some(elem) = tester.get_mut(0) { - assert_eq!(*elem, 1); - *elem = 10; - } - - if let Some(elem) = tester.get_mut(2) { - assert_eq!(*elem, 3); - *elem = 30; - } - - assert_eq!(tester.get(0), Some(&10)); - assert_eq!(tester.get(2), Some(&30)); - assert_eq!(tester.get_mut(3), None); - - tester.remove(2); - - assert_eq!(tester.len(), 2); - assert_eq!(tester.get(0), Some(&10)); - assert_eq!(tester.get(1), Some(&2)); - assert_eq!(tester.get(2), None); -} - -#[test] -fn test_swap() { - let mut tester = VecDeque::new(); - tester.push_back(1); - tester.push_back(2); - tester.push_back(3); - - assert_eq!(tester, [1, 2, 3]); - - tester.swap(0, 0); - assert_eq!(tester, [1, 2, 3]); - tester.swap(0, 1); - assert_eq!(tester, [2, 1, 3]); - tester.swap(2, 1); - assert_eq!(tester, [2, 3, 1]); - tester.swap(1, 2); - assert_eq!(tester, [2, 1, 3]); - tester.swap(0, 2); - assert_eq!(tester, [3, 1, 2]); - tester.swap(2, 2); - assert_eq!(tester, [3, 1, 2]); -} - -#[test] -#[should_panic = "assertion failed: j < self.len()"] -fn test_swap_panic() { - let mut tester = VecDeque::new(); - tester.push_back(1); - tester.push_back(2); - tester.push_back(3); - tester.swap(2, 3); -} - -#[test] -fn test_reserve_exact() { - let mut tester: VecDeque = VecDeque::with_capacity(1); - assert_eq!(tester.capacity(), 1); - tester.reserve_exact(50); - assert_eq!(tester.capacity(), 50); - tester.reserve_exact(40); - // reserving won't shrink the buffer - assert_eq!(tester.capacity(), 50); - tester.reserve_exact(200); - assert_eq!(tester.capacity(), 200); -} - -#[test] -#[should_panic = "capacity overflow"] -fn test_reserve_exact_panic() { - let mut tester: VecDeque = VecDeque::new(); - tester.reserve_exact(usize::MAX); -} - -#[test] -fn test_try_reserve_exact() { - let mut tester: VecDeque = VecDeque::with_capacity(1); - assert!(tester.capacity() == 1); - assert_eq!(tester.try_reserve_exact(100), Ok(())); - assert!(tester.capacity() >= 100); - assert_eq!(tester.try_reserve_exact(50), Ok(())); - assert!(tester.capacity() >= 100); - assert_eq!(tester.try_reserve_exact(200), Ok(())); - assert!(tester.capacity() >= 200); - assert_eq!(tester.try_reserve_exact(0), Ok(())); - assert!(tester.capacity() >= 200); - assert!(tester.try_reserve_exact(usize::MAX).is_err()); -} - -#[test] -fn test_try_reserve() { - let mut tester: VecDeque = VecDeque::with_capacity(1); - assert!(tester.capacity() == 1); - assert_eq!(tester.try_reserve(100), Ok(())); - assert!(tester.capacity() >= 100); - assert_eq!(tester.try_reserve(50), Ok(())); - assert!(tester.capacity() >= 100); - assert_eq!(tester.try_reserve(200), Ok(())); - assert!(tester.capacity() >= 200); - assert_eq!(tester.try_reserve(0), Ok(())); - assert!(tester.capacity() >= 200); - assert!(tester.try_reserve(usize::MAX).is_err()); -} - -#[test] -fn test_contains() { - let mut tester = VecDeque::new(); - tester.push_back(1); - tester.push_back(2); - tester.push_back(3); - - assert!(tester.contains(&1)); - assert!(tester.contains(&3)); - assert!(!tester.contains(&0)); - assert!(!tester.contains(&4)); - tester.remove(0); - assert!(!tester.contains(&1)); - assert!(tester.contains(&2)); - assert!(tester.contains(&3)); -} - -#[test] -fn test_rotate_left_right() { - let mut tester: VecDeque<_> = (1..=10).collect(); - tester.reserve(1); - - assert_eq!(tester.len(), 10); - - tester.rotate_left(0); - assert_eq!(tester, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); - - tester.rotate_right(0); - assert_eq!(tester, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); - - tester.rotate_left(3); - assert_eq!(tester, [4, 5, 6, 7, 8, 9, 10, 1, 2, 3]); - - tester.rotate_right(5); - assert_eq!(tester, [9, 10, 1, 2, 3, 4, 5, 6, 7, 8]); - - tester.rotate_left(tester.len()); - assert_eq!(tester, [9, 10, 1, 2, 3, 4, 5, 6, 7, 8]); - - tester.rotate_right(tester.len()); - assert_eq!(tester, [9, 10, 1, 2, 3, 4, 5, 6, 7, 8]); - - tester.rotate_left(1); - assert_eq!(tester, [10, 1, 2, 3, 4, 5, 6, 7, 8, 9]); -} - -#[test] -#[should_panic = "assertion failed: n <= self.len()"] -fn test_rotate_left_panic() { - let mut tester: VecDeque<_> = (1..=10).collect(); - tester.rotate_left(tester.len() + 1); -} - -#[test] -#[should_panic = "assertion failed: n <= self.len()"] -fn test_rotate_right_panic() { - let mut tester: VecDeque<_> = (1..=10).collect(); - tester.rotate_right(tester.len() + 1); -} - -#[test] -fn test_binary_search() { - // If the givin VecDeque is not sorted, the returned result is unspecified and meaningless, - // as this method performs a binary search. - - let tester: VecDeque<_> = [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55].into(); - - assert_eq!(tester.binary_search(&0), Ok(0)); - assert_eq!(tester.binary_search(&5), Ok(5)); - assert_eq!(tester.binary_search(&55), Ok(10)); - assert_eq!(tester.binary_search(&4), Err(5)); - assert_eq!(tester.binary_search(&-1), Err(0)); - assert!(matches!(tester.binary_search(&1), Ok(1..=2))); - - let tester: VecDeque<_> = [1, 2, 2, 2, 2, 3, 3, 3, 3, 3, 3, 3, 3, 3].into(); - assert_eq!(tester.binary_search(&1), Ok(0)); - assert!(matches!(tester.binary_search(&2), Ok(1..=4))); - assert!(matches!(tester.binary_search(&3), Ok(5..=13))); - assert_eq!(tester.binary_search(&-2), Err(0)); - assert_eq!(tester.binary_search(&0), Err(0)); - assert_eq!(tester.binary_search(&4), Err(14)); - assert_eq!(tester.binary_search(&5), Err(14)); -} - -#[test] -fn test_binary_search_by() { - // If the givin VecDeque is not sorted, the returned result is unspecified and meaningless, - // as this method performs a binary search. - - let tester: VecDeque<_> = [0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55].into(); - - assert_eq!(tester.binary_search_by(|x| x.cmp(&0)), Ok(0)); - assert_eq!(tester.binary_search_by(|x| x.cmp(&5)), Ok(5)); - assert_eq!(tester.binary_search_by(|x| x.cmp(&55)), Ok(10)); - assert_eq!(tester.binary_search_by(|x| x.cmp(&4)), Err(5)); - assert_eq!(tester.binary_search_by(|x| x.cmp(&-1)), Err(0)); - assert!(matches!(tester.binary_search_by(|x| x.cmp(&1)), Ok(1..=2))); -} - -#[test] -fn test_binary_search_key() { - // If the givin VecDeque is not sorted, the returned result is unspecified and meaningless, - // as this method performs a binary search. - - let tester: VecDeque<_> = [ - (-1, 0), - (2, 10), - (6, 5), - (7, 1), - (8, 10), - (10, 2), - (20, 3), - (24, 5), - (25, 18), - (28, 13), - (31, 21), - (32, 4), - (54, 25), - ] - .into(); - - assert_eq!(tester.binary_search_by_key(&-1, |&(a, _b)| a), Ok(0)); - assert_eq!(tester.binary_search_by_key(&8, |&(a, _b)| a), Ok(4)); - assert_eq!(tester.binary_search_by_key(&25, |&(a, _b)| a), Ok(8)); - assert_eq!(tester.binary_search_by_key(&54, |&(a, _b)| a), Ok(12)); - assert_eq!(tester.binary_search_by_key(&-2, |&(a, _b)| a), Err(0)); - assert_eq!(tester.binary_search_by_key(&1, |&(a, _b)| a), Err(1)); - assert_eq!(tester.binary_search_by_key(&4, |&(a, _b)| a), Err(2)); - assert_eq!(tester.binary_search_by_key(&13, |&(a, _b)| a), Err(6)); - assert_eq!(tester.binary_search_by_key(&55, |&(a, _b)| a), Err(13)); - assert_eq!(tester.binary_search_by_key(&100, |&(a, _b)| a), Err(13)); - - let tester: VecDeque<_> = [ - (0, 0), - (2, 1), - (6, 1), - (5, 1), - (3, 1), - (1, 2), - (2, 3), - (4, 5), - (5, 8), - (8, 13), - (1, 21), - (2, 34), - (4, 55), - ] - .into(); - - assert_eq!(tester.binary_search_by_key(&0, |&(_a, b)| b), Ok(0)); - assert!(matches!(tester.binary_search_by_key(&1, |&(_a, b)| b), Ok(1..=4))); - assert_eq!(tester.binary_search_by_key(&8, |&(_a, b)| b), Ok(8)); - assert_eq!(tester.binary_search_by_key(&13, |&(_a, b)| b), Ok(9)); - assert_eq!(tester.binary_search_by_key(&55, |&(_a, b)| b), Ok(12)); - assert_eq!(tester.binary_search_by_key(&-1, |&(_a, b)| b), Err(0)); - assert_eq!(tester.binary_search_by_key(&4, |&(_a, b)| b), Err(7)); - assert_eq!(tester.binary_search_by_key(&56, |&(_a, b)| b), Err(13)); - assert_eq!(tester.binary_search_by_key(&100, |&(_a, b)| b), Err(13)); -} - -#[test] -fn make_contiguous_big_head() { - let mut tester = VecDeque::with_capacity(15); - - for i in 0..3 { - tester.push_back(i); - } - - for i in 3..10 { - tester.push_front(i); - } - - // 012......9876543 - assert_eq!(tester.capacity(), 15); - assert_eq!((&[9, 8, 7, 6, 5, 4, 3] as &[_], &[0, 1, 2] as &[_]), tester.as_slices()); - - let expected_start = tester.as_slices().1.len(); - tester.make_contiguous(); - assert_eq!(tester.head, expected_start); - assert_eq!((&[9, 8, 7, 6, 5, 4, 3, 0, 1, 2] as &[_], &[] as &[_]), tester.as_slices()); -} - -#[test] -fn make_contiguous_big_tail() { - let mut tester = VecDeque::with_capacity(15); - - for i in 0..8 { - tester.push_back(i); - } - - for i in 8..10 { - tester.push_front(i); - } - - // 01234567......98 - let expected_start = 0; - tester.make_contiguous(); - assert_eq!(tester.head, expected_start); - assert_eq!((&[9, 8, 0, 1, 2, 3, 4, 5, 6, 7] as &[_], &[] as &[_]), tester.as_slices()); -} - -#[test] -fn make_contiguous_small_free() { - let mut tester = VecDeque::with_capacity(16); - - for i in b'A'..b'I' { - tester.push_back(i as char); - } - - for i in b'I'..b'N' { - tester.push_front(i as char); - } - - assert_eq!(tester, ['M', 'L', 'K', 'J', 'I', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H']); - - // ABCDEFGH...MLKJI - let expected_start = 0; - tester.make_contiguous(); - assert_eq!(tester.head, expected_start); - assert_eq!( - (&['M', 'L', 'K', 'J', 'I', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H'] as &[_], &[] as &[_]), - tester.as_slices() - ); - - tester.clear(); - for i in b'I'..b'N' { - tester.push_back(i as char); - } - - for i in b'A'..b'I' { - tester.push_front(i as char); - } - - // IJKLM...HGFEDCBA - let expected_start = 3; - tester.make_contiguous(); - assert_eq!(tester.head, expected_start); - assert_eq!( - (&['H', 'G', 'F', 'E', 'D', 'C', 'B', 'A', 'I', 'J', 'K', 'L', 'M'] as &[_], &[] as &[_]), - tester.as_slices() - ); -} - -#[test] -fn make_contiguous_head_to_end() { - let mut tester = VecDeque::with_capacity(16); - - for i in b'A'..b'L' { - tester.push_back(i as char); - } - - for i in b'L'..b'Q' { - tester.push_front(i as char); - } - - assert_eq!( - tester, - ['P', 'O', 'N', 'M', 'L', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K'] - ); - - // ABCDEFGHIJKPONML - let expected_start = 0; - tester.make_contiguous(); - assert_eq!(tester.head, expected_start); - assert_eq!( - ( - &['P', 'O', 'N', 'M', 'L', 'A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K'] - as &[_], - &[] as &[_] - ), - tester.as_slices() - ); - - tester.clear(); - for i in b'L'..b'Q' { - tester.push_back(i as char); - } - - for i in b'A'..b'L' { - tester.push_front(i as char); - } - - // LMNOPKJIHGFEDCBA - let expected_start = 0; - tester.make_contiguous(); - assert_eq!(tester.head, expected_start); - assert_eq!( - ( - &['K', 'J', 'I', 'H', 'G', 'F', 'E', 'D', 'C', 'B', 'A', 'L', 'M', 'N', 'O', 'P'] - as &[_], - &[] as &[_] - ), - tester.as_slices() - ); -} - -#[test] -fn make_contiguous_head_to_end_2() { - // Another test case for #79808, taken from #80293. - - let mut dq = VecDeque::from_iter(0..6); - dq.pop_front(); - dq.pop_front(); - dq.push_back(6); - dq.push_back(7); - dq.push_back(8); - dq.make_contiguous(); - let collected: Vec<_> = dq.iter().copied().collect(); - assert_eq!(dq.as_slices(), (&collected[..], &[] as &[_])); -} - -#[test] -fn test_remove() { - // This test checks that every single combination of tail position, length, and - // removal position is tested. Capacity 15 should be large enough to cover every case. - - let mut tester = VecDeque::with_capacity(15); - // can't guarantee we got 15, so have to get what we got. - // 15 would be great, but we will definitely get 2^k - 1, for k >= 4, or else - // this test isn't covering what it wants to - let cap = tester.capacity(); - - // len is the length *after* removal - let minlen = if cfg!(miri) { cap - 2 } else { 0 }; // Miri is too slow - for len in minlen..cap - 1 { - // 0, 1, 2, .., len - 1 - let expected = (0..).take(len).collect::>(); - for head_pos in 0..cap { - for to_remove in 0..=len { - tester.head = head_pos; - tester.len = 0; - for i in 0..len { - if i == to_remove { - tester.push_back(1234); - } - tester.push_back(i); - } - if to_remove == len { - tester.push_back(1234); - } - tester.remove(to_remove); - assert!(tester.head <= tester.capacity()); - assert!(tester.len <= tester.capacity()); - assert_eq!(tester, expected); - } - } - } -} - -#[test] -fn test_range() { - let mut tester: VecDeque = VecDeque::with_capacity(7); - - let cap = tester.capacity(); - let minlen = if cfg!(miri) { cap - 1 } else { 0 }; // Miri is too slow - for len in minlen..=cap { - for head in 0..=cap { - for start in 0..=len { - for end in start..=len { - tester.head = head; - tester.len = 0; - for i in 0..len { - tester.push_back(i); - } - - // Check that we iterate over the correct values - let range: VecDeque<_> = tester.range(start..end).copied().collect(); - let expected: VecDeque<_> = (start..end).collect(); - assert_eq!(range, expected); - } - } - } - } -} - -#[test] -fn test_range_mut() { - let mut tester: VecDeque = VecDeque::with_capacity(7); - - let cap = tester.capacity(); - for len in 0..=cap { - for head in 0..=cap { - for start in 0..=len { - for end in start..=len { - tester.head = head; - tester.len = 0; - for i in 0..len { - tester.push_back(i); - } - - let head_was = tester.head; - let len_was = tester.len; - - // Check that we iterate over the correct values - let range: VecDeque<_> = tester.range_mut(start..end).map(|v| *v).collect(); - let expected: VecDeque<_> = (start..end).collect(); - assert_eq!(range, expected); - - // We shouldn't have changed the capacity or made the - // head or tail out of bounds - assert_eq!(tester.capacity(), cap); - assert_eq!(tester.head, head_was); - assert_eq!(tester.len, len_was); - } - } - } - } -} - -#[test] -fn test_drain() { - let mut tester: VecDeque = VecDeque::with_capacity(7); - - let cap = tester.capacity(); - for len in 0..=cap { - for head in 0..cap { - for drain_start in 0..=len { - for drain_end in drain_start..=len { - tester.head = head; - tester.len = 0; - for i in 0..len { - tester.push_back(i); - } - - // Check that we drain the correct values - let drained: VecDeque<_> = tester.drain(drain_start..drain_end).collect(); - let drained_expected: VecDeque<_> = (drain_start..drain_end).collect(); - assert_eq!(drained, drained_expected); - - // We shouldn't have changed the capacity or made the - // head or tail out of bounds - assert_eq!(tester.capacity(), cap); - assert!(tester.head <= tester.capacity()); - assert!(tester.len <= tester.capacity()); - - // We should see the correct values in the VecDeque - let expected: VecDeque<_> = (0..drain_start).chain(drain_end..len).collect(); - assert_eq!(expected, tester); - } - } - } - } -} - -#[test] -fn issue_108453() { - let mut deque = VecDeque::with_capacity(10); - - deque.push_back(1u8); - deque.push_back(2); - deque.push_back(3); - - deque.push_front(10); - deque.push_front(9); - - deque.shrink_to(9); - - assert_eq!(deque.into_iter().collect::>(), vec![9, 10, 1, 2, 3]); -} - -#[test] -fn test_shrink_to() { - // test deques with capacity 16 with all possible head positions, lengths and target capacities. - let cap = 16; - - for len in 0..cap { - for head in 0..cap { - let expected = (1..=len).collect::>(); - - for target_cap in len..cap { - let mut deque = VecDeque::with_capacity(cap); - // currently, `with_capacity` always allocates the exact capacity if it's greater than 8. - assert_eq!(deque.capacity(), cap); - - // we can let the head point anywhere in the buffer since the deque is empty. - deque.head = head; - deque.extend(1..=len); - - deque.shrink_to(target_cap); - - assert_eq!(deque, expected); - } - } - } -} - -#[test] -fn test_shrink_to_fit() { - // This test checks that every single combination of head and tail position, - // is tested. Capacity 15 should be large enough to cover every case. - - let mut tester = VecDeque::with_capacity(15); - // can't guarantee we got 15, so have to get what we got. - // 15 would be great, but we will definitely get 2^k - 1, for k >= 4, or else - // this test isn't covering what it wants to - let cap = tester.capacity(); - tester.reserve(63); - let max_cap = tester.capacity(); - - for len in 0..=cap { - // 0, 1, 2, .., len - 1 - let expected = (0..).take(len).collect::>(); - for head_pos in 0..=max_cap { - tester.reserve(head_pos); - tester.head = head_pos; - tester.len = 0; - tester.reserve(63); - for i in 0..len { - tester.push_back(i); - } - tester.shrink_to_fit(); - assert!(tester.capacity() <= cap); - assert!(tester.head <= tester.capacity()); - assert!(tester.len <= tester.capacity()); - assert_eq!(tester, expected); - } - } -} - -#[test] -fn test_split_off() { - // This test checks that every single combination of tail position, length, and - // split position is tested. Capacity 15 should be large enough to cover every case. - - let mut tester = VecDeque::with_capacity(15); - // can't guarantee we got 15, so have to get what we got. - // 15 would be great, but we will definitely get 2^k - 1, for k >= 4, or else - // this test isn't covering what it wants to - let cap = tester.capacity(); - - // len is the length *before* splitting - let minlen = if cfg!(miri) { cap - 1 } else { 0 }; // Miri is too slow - for len in minlen..cap { - // index to split at - for at in 0..=len { - // 0, 1, 2, .., at - 1 (may be empty) - let expected_self = (0..).take(at).collect::>(); - // at, at + 1, .., len - 1 (may be empty) - let expected_other = (at..).take(len - at).collect::>(); - - for head_pos in 0..cap { - tester.head = head_pos; - tester.len = 0; - for i in 0..len { - tester.push_back(i); - } - let result = tester.split_off(at); - assert!(tester.head <= tester.capacity()); - assert!(tester.len <= tester.capacity()); - assert!(result.head <= result.capacity()); - assert!(result.len <= result.capacity()); - assert_eq!(tester, expected_self); - assert_eq!(result, expected_other); - } - } - } -} - -#[test] -fn test_from_vec() { - use crate::vec::Vec; - for cap in 0..35 { - for len in 0..=cap { - let mut vec = Vec::with_capacity(cap); - vec.extend(0..len); - - let vd = VecDeque::from(vec.clone()); - assert_eq!(vd.len(), vec.len()); - assert!(vd.into_iter().eq(vec)); - } - } -} - -#[test] -fn test_extend_basic() { - test_extend_impl(false); -} - -#[test] -fn test_extend_trusted_len() { - test_extend_impl(true); -} - -fn test_extend_impl(trusted_len: bool) { - struct VecDequeTester { - test: VecDeque, - expected: VecDeque, - trusted_len: bool, - } - - impl VecDequeTester { - fn new(trusted_len: bool) -> Self { - Self { test: VecDeque::new(), expected: VecDeque::new(), trusted_len } - } - - fn test_extend(&mut self, iter: I) - where - I: Iterator + TrustedLen + Clone, - { - struct BasicIterator(I); - impl Iterator for BasicIterator - where - I: Iterator, - { - type Item = usize; - - fn next(&mut self) -> Option { - self.0.next() - } - } - - if self.trusted_len { - self.test.extend(iter.clone()); - } else { - self.test.extend(BasicIterator(iter.clone())); - } - - for item in iter { - self.expected.push_back(item) - } - - assert_eq!(self.test, self.expected); - } - - fn drain + Clone>(&mut self, range: R) { - self.test.drain(range.clone()); - self.expected.drain(range); - - assert_eq!(self.test, self.expected); - } - - fn clear(&mut self) { - self.test.clear(); - self.expected.clear(); - } - - fn remaining_capacity(&self) -> usize { - self.test.capacity() - self.test.len() - } - } - - let mut tester = VecDequeTester::new(trusted_len); - - // Initial capacity - tester.test_extend(0..tester.remaining_capacity()); - - // Grow - tester.test_extend(1024..2048); - - // Wrap around - tester.drain(..128); - - tester.test_extend(0..tester.remaining_capacity()); - - // Continue - tester.drain(256..); - tester.test_extend(4096..8196); - - tester.clear(); - - // Start again - tester.test_extend(0..32); -} - -#[test] -fn test_from_array() { - fn test() { - let mut array: [usize; N] = [0; N]; - - for i in 0..N { - array[i] = i; - } - - let deq: VecDeque<_> = array.into(); - - for i in 0..N { - assert_eq!(deq[i], i); - } - - assert_eq!(deq.len(), N); - } - test::<0>(); - test::<1>(); - test::<2>(); - test::<32>(); - test::<35>(); -} - -#[test] -fn test_vec_from_vecdeque() { - use crate::vec::Vec; - - fn create_vec_and_test_convert(capacity: usize, offset: usize, len: usize) { - let mut vd = VecDeque::with_capacity(capacity); - for _ in 0..offset { - vd.push_back(0); - vd.pop_front(); - } - vd.extend(0..len); - - let vec: Vec<_> = Vec::from(vd.clone()); - assert_eq!(vec.len(), vd.len()); - assert!(vec.into_iter().eq(vd)); - } - - // Miri is too slow - let max_pwr = if cfg!(miri) { 5 } else { 7 }; - - for cap_pwr in 0..max_pwr { - // Make capacity as a (2^x)-1, so that the ring size is 2^x - let cap = (2i32.pow(cap_pwr) - 1) as usize; - - // In these cases there is enough free space to solve it with copies - for len in 0..((cap + 1) / 2) { - // Test contiguous cases - for offset in 0..(cap - len) { - create_vec_and_test_convert(cap, offset, len) - } - - // Test cases where block at end of buffer is bigger than block at start - for offset in (cap - len)..(cap - (len / 2)) { - create_vec_and_test_convert(cap, offset, len) - } - - // Test cases where block at start of buffer is bigger than block at end - for offset in (cap - (len / 2))..cap { - create_vec_and_test_convert(cap, offset, len) - } - } - - // Now there's not (necessarily) space to straighten the ring with simple copies, - // the ring will use swapping when: - // (cap + 1 - offset) > (cap + 1 - len) && (len - (cap + 1 - offset)) > (cap + 1 - len)) - // right block size > free space && left block size > free space - for len in ((cap + 1) / 2)..cap { - // Test contiguous cases - for offset in 0..(cap - len) { - create_vec_and_test_convert(cap, offset, len) - } - - // Test cases where block at end of buffer is bigger than block at start - for offset in (cap - len)..(cap - (len / 2)) { - create_vec_and_test_convert(cap, offset, len) - } - - // Test cases where block at start of buffer is bigger than block at end - for offset in (cap - (len / 2))..cap { - create_vec_and_test_convert(cap, offset, len) - } - } - } -} - -#[test] -fn test_clone_from() { - let m = vec![1; 8]; - let n = vec![2; 12]; - let limit = if cfg!(miri) { 4 } else { 8 }; // Miri is too slow - for pfv in 0..limit { - for pfu in 0..limit { - for longer in 0..2 { - let (vr, ur) = if longer == 0 { (&m, &n) } else { (&n, &m) }; - let mut v = VecDeque::from(vr.clone()); - for _ in 0..pfv { - v.push_front(1); - } - let mut u = VecDeque::from(ur.clone()); - for _ in 0..pfu { - u.push_front(2); - } - v.clone_from(&u); - assert_eq!(&v, &u); - } - } - } -} - -#[test] -fn test_vec_deque_truncate_drop() { - static mut DROPS: u32 = 0; - #[derive(Clone)] - struct Elem(#[allow(dead_code)] i32); - impl Drop for Elem { - fn drop(&mut self) { - unsafe { - DROPS += 1; - } - } - } - - let v = vec![Elem(1), Elem(2), Elem(3), Elem(4), Elem(5)]; - for push_front in 0..=v.len() { - let v = v.clone(); - let mut tester = VecDeque::with_capacity(5); - for (index, elem) in v.into_iter().enumerate() { - if index < push_front { - tester.push_front(elem); - } else { - tester.push_back(elem); - } - } - assert_eq!(unsafe { DROPS }, 0); - tester.truncate(3); - assert_eq!(unsafe { DROPS }, 2); - tester.truncate(0); - assert_eq!(unsafe { DROPS }, 5); - unsafe { - DROPS = 0; - } - } -} - -#[test] -fn issue_53529() { - use crate::boxed::Box; - - let mut dst = VecDeque::new(); - dst.push_front(Box::new(1)); - dst.push_front(Box::new(2)); - assert_eq!(*dst.pop_back().unwrap(), 1); - - let mut src = VecDeque::new(); - src.push_front(Box::new(2)); - dst.append(&mut src); - for a in dst { - assert_eq!(*a, 2); - } -} - -#[test] -fn issue_80303() { - use core::iter; - use core::num::Wrapping; - - // This is a valid, albeit rather bad hash function implementation. - struct SimpleHasher(Wrapping); - - impl Hasher for SimpleHasher { - fn finish(&self) -> u64 { - self.0.0 - } - - fn write(&mut self, bytes: &[u8]) { - // This particular implementation hashes value 24 in addition to bytes. - // Such an implementation is valid as Hasher only guarantees equivalence - // for the exact same set of calls to its methods. - for &v in iter::once(&24).chain(bytes) { - self.0 = Wrapping(31) * self.0 + Wrapping(u64::from(v)); - } - } - } - - fn hash_code(value: impl Hash) -> u64 { - let mut hasher = SimpleHasher(Wrapping(1)); - value.hash(&mut hasher); - hasher.finish() - } - - // This creates two deques for which values returned by as_slices - // method differ. - let vda: VecDeque = (0..10).collect(); - let mut vdb = VecDeque::with_capacity(10); - vdb.extend(5..10); - (0..5).rev().for_each(|elem| vdb.push_front(elem)); - assert_ne!(vda.as_slices(), vdb.as_slices()); - assert_eq!(vda, vdb); - assert_eq!(hash_code(vda), hash_code(vdb)); -} diff --git a/library/alloc/src/ffi/c_str.rs b/library/alloc/src/ffi/c_str.rs deleted file mode 100644 index b13af93d06c57..0000000000000 --- a/library/alloc/src/ffi/c_str.rs +++ /dev/null @@ -1,1153 +0,0 @@ -//! [`CString`] and its related types. - -#[cfg(test)] -mod tests; - -use crate::borrow::{Cow, ToOwned}; -use crate::boxed::Box; -use crate::rc::Rc; -use crate::slice::hack::into_vec; -use crate::string::String; -use crate::vec::Vec; -use core::borrow::Borrow; -use core::ffi::{c_char, CStr}; -use core::fmt; -use core::mem; -use core::num::NonZero; -use core::ops; -use core::ptr; -use core::slice; -use core::slice::memchr; -use core::str::{self, Utf8Error}; - -#[cfg(target_has_atomic = "ptr")] -use crate::sync::Arc; - -/// A type representing an owned, C-compatible, nul-terminated string with no nul bytes in the -/// middle. -/// -/// This type serves the purpose of being able to safely generate a -/// C-compatible string from a Rust byte slice or vector. An instance of this -/// type is a static guarantee that the underlying bytes contain no interior 0 -/// bytes ("nul characters") and that the final byte is 0 ("nul terminator"). -/// -/// `CString` is to &[CStr] as [`String`] is to &[str]: the former -/// in each pair are owned strings; the latter are borrowed -/// references. -/// -/// # Creating a `CString` -/// -/// A `CString` is created from either a byte slice or a byte vector, -/// or anything that implements [Into]<[Vec]<[u8]>> (for -/// example, you can build a `CString` straight out of a [`String`] or -/// a &[str], since both implement that trait). -/// You can create a `CString` from a literal with `CString::from(c"Text")`. -/// -/// The [`CString::new`] method will actually check that the provided &[[u8]] -/// does not have 0 bytes in the middle, and return an error if it -/// finds one. -/// -/// # Extracting a raw pointer to the whole C string -/// -/// `CString` implements an [`as_ptr`][`CStr::as_ptr`] method through the [`Deref`] -/// trait. This method will give you a `*const c_char` which you can -/// feed directly to extern functions that expect a nul-terminated -/// string, like C's `strdup()`. Notice that [`as_ptr`][`CStr::as_ptr`] returns a -/// read-only pointer; if the C code writes to it, that causes -/// undefined behavior. -/// -/// # Extracting a slice of the whole C string -/// -/// Alternatively, you can obtain a &[[u8]] slice from a -/// `CString` with the [`CString::as_bytes`] method. Slices produced in this -/// way do *not* contain the trailing nul terminator. This is useful -/// when you will be calling an extern function that takes a `*const -/// u8` argument which is not necessarily nul-terminated, plus another -/// argument with the length of the string — like C's `strndup()`. -/// You can of course get the slice's length with its -/// [`len`][slice::len] method. -/// -/// If you need a &[[u8]] slice *with* the nul terminator, you -/// can use [`CString::as_bytes_with_nul`] instead. -/// -/// Once you have the kind of slice you need (with or without a nul -/// terminator), you can call the slice's own -/// [`as_ptr`][slice::as_ptr] method to get a read-only raw pointer to pass to -/// extern functions. See the documentation for that function for a -/// discussion on ensuring the lifetime of the raw pointer. -/// -/// [str]: prim@str "str" -/// [`Deref`]: ops::Deref -/// -/// # Examples -/// -/// ```ignore (extern-declaration) -/// # fn main() { -/// use std::ffi::CString; -/// use std::os::raw::c_char; -/// -/// extern "C" { -/// fn my_printer(s: *const c_char); -/// } -/// -/// // We are certain that our string doesn't have 0 bytes in the middle, -/// // so we can .expect() -/// let c_to_print = CString::new("Hello, world!").expect("CString::new failed"); -/// unsafe { -/// my_printer(c_to_print.as_ptr()); -/// } -/// # } -/// ``` -/// -/// # Safety -/// -/// `CString` is intended for working with traditional C-style strings -/// (a sequence of non-nul bytes terminated by a single nul byte); the -/// primary use case for these kinds of strings is interoperating with C-like -/// code. Often you will need to transfer ownership to/from that external -/// code. It is strongly recommended that you thoroughly read through the -/// documentation of `CString` before use, as improper ownership management -/// of `CString` instances can lead to invalid memory accesses, memory leaks, -/// and other memory errors. -#[derive(PartialEq, PartialOrd, Eq, Ord, Hash, Clone)] -#[cfg_attr(not(test), rustc_diagnostic_item = "cstring_type")] -#[stable(feature = "alloc_c_string", since = "1.64.0")] -pub struct CString { - // Invariant 1: the slice ends with a zero byte and has a length of at least one. - // Invariant 2: the slice contains only one zero byte. - // Improper usage of unsafe function can break Invariant 2, but not Invariant 1. - inner: Box<[u8]>, -} - -/// An error indicating that an interior nul byte was found. -/// -/// While Rust strings may contain nul bytes in the middle, C strings -/// can't, as that byte would effectively truncate the string. -/// -/// This error is created by the [`new`][`CString::new`] method on -/// [`CString`]. See its documentation for more. -/// -/// # Examples -/// -/// ``` -/// use std::ffi::{CString, NulError}; -/// -/// let _: NulError = CString::new(b"f\0oo".to_vec()).unwrap_err(); -/// ``` -#[derive(Clone, PartialEq, Eq, Debug)] -#[stable(feature = "alloc_c_string", since = "1.64.0")] -pub struct NulError(usize, Vec); - -#[derive(Clone, PartialEq, Eq, Debug)] -enum FromBytesWithNulErrorKind { - InteriorNul(usize), - NotNulTerminated, -} - -/// An error indicating that a nul byte was not in the expected position. -/// -/// The vector used to create a [`CString`] must have one and only one nul byte, -/// positioned at the end. -/// -/// This error is created by the [`CString::from_vec_with_nul`] method. -/// See its documentation for more. -/// -/// # Examples -/// -/// ``` -/// use std::ffi::{CString, FromVecWithNulError}; -/// -/// let _: FromVecWithNulError = CString::from_vec_with_nul(b"f\0oo".to_vec()).unwrap_err(); -/// ``` -#[derive(Clone, PartialEq, Eq, Debug)] -#[stable(feature = "alloc_c_string", since = "1.64.0")] -pub struct FromVecWithNulError { - error_kind: FromBytesWithNulErrorKind, - bytes: Vec, -} - -#[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")] -impl FromVecWithNulError { - /// Returns a slice of [`u8`]s bytes that were attempted to convert to a [`CString`]. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::ffi::CString; - /// - /// // Some invalid bytes in a vector - /// let bytes = b"f\0oo".to_vec(); - /// - /// let value = CString::from_vec_with_nul(bytes.clone()); - /// - /// assert_eq!(&bytes[..], value.unwrap_err().as_bytes()); - /// ``` - #[must_use] - #[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")] - pub fn as_bytes(&self) -> &[u8] { - &self.bytes[..] - } - - /// Returns the bytes that were attempted to convert to a [`CString`]. - /// - /// This method is carefully constructed to avoid allocation. It will - /// consume the error, moving out the bytes, so that a copy of the bytes - /// does not need to be made. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// use std::ffi::CString; - /// - /// // Some invalid bytes in a vector - /// let bytes = b"f\0oo".to_vec(); - /// - /// let value = CString::from_vec_with_nul(bytes.clone()); - /// - /// assert_eq!(bytes, value.unwrap_err().into_bytes()); - /// ``` - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")] - pub fn into_bytes(self) -> Vec { - self.bytes - } -} - -/// An error indicating invalid UTF-8 when converting a [`CString`] into a [`String`]. -/// -/// `CString` is just a wrapper over a buffer of bytes with a nul terminator; -/// [`CString::into_string`] performs UTF-8 validation on those bytes and may -/// return this error. -/// -/// This `struct` is created by [`CString::into_string()`]. See -/// its documentation for more. -#[derive(Clone, PartialEq, Eq, Debug)] -#[stable(feature = "alloc_c_string", since = "1.64.0")] -pub struct IntoStringError { - inner: CString, - error: Utf8Error, -} - -impl CString { - /// Creates a new C-compatible string from a container of bytes. - /// - /// This function will consume the provided data and use the - /// underlying bytes to construct a new string, ensuring that - /// there is a trailing 0 byte. This trailing 0 byte will be - /// appended by this function; the provided data should *not* - /// contain any 0 bytes in it. - /// - /// # Examples - /// - /// ```ignore (extern-declaration) - /// use std::ffi::CString; - /// use std::os::raw::c_char; - /// - /// extern "C" { fn puts(s: *const c_char); } - /// - /// let to_print = CString::new("Hello!").expect("CString::new failed"); - /// unsafe { - /// puts(to_print.as_ptr()); - /// } - /// ``` - /// - /// # Errors - /// - /// This function will return an error if the supplied bytes contain an - /// internal 0 byte. The [`NulError`] returned will contain the bytes as well as - /// the position of the nul byte. - #[stable(feature = "rust1", since = "1.0.0")] - pub fn new>>(t: T) -> Result { - trait SpecNewImpl { - fn spec_new_impl(self) -> Result; - } - - impl>> SpecNewImpl for T { - default fn spec_new_impl(self) -> Result { - let bytes: Vec = self.into(); - match memchr::memchr(0, &bytes) { - Some(i) => Err(NulError(i, bytes)), - None => Ok(unsafe { CString::_from_vec_unchecked(bytes) }), - } - } - } - - // Specialization for avoiding reallocation - #[inline(always)] // Without that it is not inlined into specializations - fn spec_new_impl_bytes(bytes: &[u8]) -> Result { - // We cannot have such large slice that we would overflow here - // but using `checked_add` allows LLVM to assume that capacity never overflows - // and generate twice shorter code. - // `saturating_add` doesn't help for some reason. - let capacity = bytes.len().checked_add(1).unwrap(); - - // Allocate before validation to avoid duplication of allocation code. - // We still need to allocate and copy memory even if we get an error. - let mut buffer = Vec::with_capacity(capacity); - buffer.extend(bytes); - - // Check memory of self instead of new buffer. - // This allows better optimizations if lto enabled. - match memchr::memchr(0, bytes) { - Some(i) => Err(NulError(i, buffer)), - None => Ok(unsafe { CString::_from_vec_unchecked(buffer) }), - } - } - - impl SpecNewImpl for &'_ [u8] { - fn spec_new_impl(self) -> Result { - spec_new_impl_bytes(self) - } - } - - impl SpecNewImpl for &'_ str { - fn spec_new_impl(self) -> Result { - spec_new_impl_bytes(self.as_bytes()) - } - } - - impl SpecNewImpl for &'_ mut [u8] { - fn spec_new_impl(self) -> Result { - spec_new_impl_bytes(self) - } - } - - t.spec_new_impl() - } - - /// Creates a C-compatible string by consuming a byte vector, - /// without checking for interior 0 bytes. - /// - /// Trailing 0 byte will be appended by this function. - /// - /// This method is equivalent to [`CString::new`] except that no runtime - /// assertion is made that `v` contains no 0 bytes, and it requires an - /// actual byte vector, not anything that can be converted to one with Into. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::CString; - /// - /// let raw = b"foo".to_vec(); - /// unsafe { - /// let c_string = CString::from_vec_unchecked(raw); - /// } - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub unsafe fn from_vec_unchecked(v: Vec) -> Self { - debug_assert!(memchr::memchr(0, &v).is_none()); - unsafe { Self::_from_vec_unchecked(v) } - } - - unsafe fn _from_vec_unchecked(mut v: Vec) -> Self { - v.reserve_exact(1); - v.push(0); - Self { inner: v.into_boxed_slice() } - } - - /// Retakes ownership of a `CString` that was transferred to C via - /// [`CString::into_raw`]. - /// - /// Additionally, the length of the string will be recalculated from the pointer. - /// - /// # Safety - /// - /// This should only ever be called with a pointer that was earlier - /// obtained by calling [`CString::into_raw`]. Other usage (e.g., trying to take - /// ownership of a string that was allocated by foreign code) is likely to lead - /// to undefined behavior or allocator corruption. - /// - /// It should be noted that the length isn't just "recomputed," but that - /// the recomputed length must match the original length from the - /// [`CString::into_raw`] call. This means the [`CString::into_raw`]/`from_raw` - /// methods should not be used when passing the string to C functions that can - /// modify the string's length. - /// - /// > **Note:** If you need to borrow a string that was allocated by - /// > foreign code, use [`CStr`]. If you need to take ownership of - /// > a string that was allocated by foreign code, you will need to - /// > make your own provisions for freeing it appropriately, likely - /// > with the foreign code's API to do that. - /// - /// # Examples - /// - /// Creates a `CString`, pass ownership to an `extern` function (via raw pointer), then retake - /// ownership with `from_raw`: - /// - /// ```ignore (extern-declaration) - /// use std::ffi::CString; - /// use std::os::raw::c_char; - /// - /// extern "C" { - /// fn some_extern_function(s: *mut c_char); - /// } - /// - /// let c_string = CString::new("Hello!").expect("CString::new failed"); - /// let raw = c_string.into_raw(); - /// unsafe { - /// some_extern_function(raw); - /// let c_string = CString::from_raw(raw); - /// } - /// ``` - #[must_use = "call `drop(from_raw(ptr))` if you intend to drop the `CString`"] - #[stable(feature = "cstr_memory", since = "1.4.0")] - pub unsafe fn from_raw(ptr: *mut c_char) -> CString { - // SAFETY: This is called with a pointer that was obtained from a call - // to `CString::into_raw` and the length has not been modified. As such, - // we know there is a NUL byte (and only one) at the end and that the - // information about the size of the allocation is correct on Rust's - // side. - unsafe { - extern "C" { - /// Provided by libc or compiler_builtins. - fn strlen(s: *const c_char) -> usize; - } - let len = strlen(ptr) + 1; // Including the NUL byte - let slice = slice::from_raw_parts_mut(ptr, len); - CString { inner: Box::from_raw(slice as *mut [c_char] as *mut [u8]) } - } - } - - /// Consumes the `CString` and transfers ownership of the string to a C caller. - /// - /// The pointer which this function returns must be returned to Rust and reconstituted using - /// [`CString::from_raw`] to be properly deallocated. Specifically, one - /// should *not* use the standard C `free()` function to deallocate - /// this string. - /// - /// Failure to call [`CString::from_raw`] will lead to a memory leak. - /// - /// The C side must **not** modify the length of the string (by writing a - /// nul byte somewhere inside the string or removing the final one) before - /// it makes it back into Rust using [`CString::from_raw`]. See the safety section - /// in [`CString::from_raw`]. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::CString; - /// - /// let c_string = CString::new("foo").expect("CString::new failed"); - /// - /// let ptr = c_string.into_raw(); - /// - /// unsafe { - /// assert_eq!(b'f', *ptr as u8); - /// assert_eq!(b'o', *ptr.add(1) as u8); - /// assert_eq!(b'o', *ptr.add(2) as u8); - /// assert_eq!(b'\0', *ptr.add(3) as u8); - /// - /// // retake pointer to free memory - /// let _ = CString::from_raw(ptr); - /// } - /// ``` - #[inline] - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "cstr_memory", since = "1.4.0")] - pub fn into_raw(self) -> *mut c_char { - Box::into_raw(self.into_inner()) as *mut c_char - } - - /// Converts the `CString` into a [`String`] if it contains valid UTF-8 data. - /// - /// On failure, ownership of the original `CString` is returned. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::CString; - /// - /// let valid_utf8 = vec![b'f', b'o', b'o']; - /// let cstring = CString::new(valid_utf8).expect("CString::new failed"); - /// assert_eq!(cstring.into_string().expect("into_string() call failed"), "foo"); - /// - /// let invalid_utf8 = vec![b'f', 0xff, b'o', b'o']; - /// let cstring = CString::new(invalid_utf8).expect("CString::new failed"); - /// let err = cstring.into_string().err().expect("into_string().err() failed"); - /// assert_eq!(err.utf8_error().valid_up_to(), 1); - /// ``` - #[stable(feature = "cstring_into", since = "1.7.0")] - pub fn into_string(self) -> Result { - String::from_utf8(self.into_bytes()).map_err(|e| IntoStringError { - error: e.utf8_error(), - inner: unsafe { Self::_from_vec_unchecked(e.into_bytes()) }, - }) - } - - /// Consumes the `CString` and returns the underlying byte buffer. - /// - /// The returned buffer does **not** contain the trailing nul - /// terminator, and it is guaranteed to not have any interior nul - /// bytes. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::CString; - /// - /// let c_string = CString::new("foo").expect("CString::new failed"); - /// let bytes = c_string.into_bytes(); - /// assert_eq!(bytes, vec![b'f', b'o', b'o']); - /// ``` - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "cstring_into", since = "1.7.0")] - pub fn into_bytes(self) -> Vec { - let mut vec = into_vec(self.into_inner()); - let _nul = vec.pop(); - debug_assert_eq!(_nul, Some(0u8)); - vec - } - - /// Equivalent to [`CString::into_bytes()`] except that the - /// returned vector includes the trailing nul terminator. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::CString; - /// - /// let c_string = CString::new("foo").expect("CString::new failed"); - /// let bytes = c_string.into_bytes_with_nul(); - /// assert_eq!(bytes, vec![b'f', b'o', b'o', b'\0']); - /// ``` - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "cstring_into", since = "1.7.0")] - pub fn into_bytes_with_nul(self) -> Vec { - into_vec(self.into_inner()) - } - - /// Returns the contents of this `CString` as a slice of bytes. - /// - /// The returned slice does **not** contain the trailing nul - /// terminator, and it is guaranteed to not have any interior nul - /// bytes. If you need the nul terminator, use - /// [`CString::as_bytes_with_nul`] instead. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::CString; - /// - /// let c_string = CString::new("foo").expect("CString::new failed"); - /// let bytes = c_string.as_bytes(); - /// assert_eq!(bytes, &[b'f', b'o', b'o']); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn as_bytes(&self) -> &[u8] { - // SAFETY: CString has a length at least 1 - unsafe { self.inner.get_unchecked(..self.inner.len() - 1) } - } - - /// Equivalent to [`CString::as_bytes()`] except that the - /// returned slice includes the trailing nul terminator. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::CString; - /// - /// let c_string = CString::new("foo").expect("CString::new failed"); - /// let bytes = c_string.as_bytes_with_nul(); - /// assert_eq!(bytes, &[b'f', b'o', b'o', b'\0']); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn as_bytes_with_nul(&self) -> &[u8] { - &self.inner - } - - /// Extracts a [`CStr`] slice containing the entire string. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::{CString, CStr}; - /// - /// let c_string = CString::new(b"foo".to_vec()).expect("CString::new failed"); - /// let cstr = c_string.as_c_str(); - /// assert_eq!(cstr, - /// CStr::from_bytes_with_nul(b"foo\0").expect("CStr::from_bytes_with_nul failed")); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "as_c_str", since = "1.20.0")] - pub fn as_c_str(&self) -> &CStr { - &*self - } - - /// Converts this `CString` into a boxed [`CStr`]. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::{CString, CStr}; - /// - /// let c_string = CString::new(b"foo".to_vec()).expect("CString::new failed"); - /// let boxed = c_string.into_boxed_c_str(); - /// assert_eq!(&*boxed, - /// CStr::from_bytes_with_nul(b"foo\0").expect("CStr::from_bytes_with_nul failed")); - /// ``` - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "into_boxed_c_str", since = "1.20.0")] - pub fn into_boxed_c_str(self) -> Box { - unsafe { Box::from_raw(Box::into_raw(self.into_inner()) as *mut CStr) } - } - - /// Bypass "move out of struct which implements [`Drop`] trait" restriction. - #[inline] - fn into_inner(self) -> Box<[u8]> { - // Rationale: `mem::forget(self)` invalidates the previous call to `ptr::read(&self.inner)` - // so we use `ManuallyDrop` to ensure `self` is not dropped. - // Then we can return the box directly without invalidating it. - // See https://github.com/rust-lang/rust/issues/62553. - let this = mem::ManuallyDrop::new(self); - unsafe { ptr::read(&this.inner) } - } - - /// Converts a [Vec]<[u8]> to a [`CString`] without checking the - /// invariants on the given [`Vec`]. - /// - /// # Safety - /// - /// The given [`Vec`] **must** have one nul byte as its last element. - /// This means it cannot be empty nor have any other nul byte anywhere else. - /// - /// # Example - /// - /// ``` - /// use std::ffi::CString; - /// assert_eq!( - /// unsafe { CString::from_vec_with_nul_unchecked(b"abc\0".to_vec()) }, - /// unsafe { CString::from_vec_unchecked(b"abc".to_vec()) } - /// ); - /// ``` - #[must_use] - #[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")] - pub unsafe fn from_vec_with_nul_unchecked(v: Vec) -> Self { - debug_assert!(memchr::memchr(0, &v).unwrap() + 1 == v.len()); - unsafe { Self::_from_vec_with_nul_unchecked(v) } - } - - unsafe fn _from_vec_with_nul_unchecked(v: Vec) -> Self { - Self { inner: v.into_boxed_slice() } - } - - /// Attempts to converts a [Vec]<[u8]> to a [`CString`]. - /// - /// Runtime checks are present to ensure there is only one nul byte in the - /// [`Vec`], its last element. - /// - /// # Errors - /// - /// If a nul byte is present and not the last element or no nul bytes - /// is present, an error will be returned. - /// - /// # Examples - /// - /// A successful conversion will produce the same result as [`CString::new`] - /// when called without the ending nul byte. - /// - /// ``` - /// use std::ffi::CString; - /// assert_eq!( - /// CString::from_vec_with_nul(b"abc\0".to_vec()) - /// .expect("CString::from_vec_with_nul failed"), - /// CString::new(b"abc".to_vec()).expect("CString::new failed") - /// ); - /// ``` - /// - /// An incorrectly formatted [`Vec`] will produce an error. - /// - /// ``` - /// use std::ffi::{CString, FromVecWithNulError}; - /// // Interior nul byte - /// let _: FromVecWithNulError = CString::from_vec_with_nul(b"a\0bc".to_vec()).unwrap_err(); - /// // No nul byte - /// let _: FromVecWithNulError = CString::from_vec_with_nul(b"abc".to_vec()).unwrap_err(); - /// ``` - #[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")] - pub fn from_vec_with_nul(v: Vec) -> Result { - let nul_pos = memchr::memchr(0, &v); - match nul_pos { - Some(nul_pos) if nul_pos + 1 == v.len() => { - // SAFETY: We know there is only one nul byte, at the end - // of the vec. - Ok(unsafe { Self::_from_vec_with_nul_unchecked(v) }) - } - Some(nul_pos) => Err(FromVecWithNulError { - error_kind: FromBytesWithNulErrorKind::InteriorNul(nul_pos), - bytes: v, - }), - None => Err(FromVecWithNulError { - error_kind: FromBytesWithNulErrorKind::NotNulTerminated, - bytes: v, - }), - } - } -} - -// Turns this `CString` into an empty string to prevent -// memory-unsafe code from working by accident. Inline -// to prevent LLVM from optimizing it away in debug builds. -#[stable(feature = "cstring_drop", since = "1.13.0")] -impl Drop for CString { - #[inline] - fn drop(&mut self) { - unsafe { - *self.inner.get_unchecked_mut(0) = 0; - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ops::Deref for CString { - type Target = CStr; - - #[inline] - fn deref(&self) -> &CStr { - unsafe { CStr::from_bytes_with_nul_unchecked(self.as_bytes_with_nul()) } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for CString { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&**self, f) - } -} - -#[stable(feature = "cstring_into", since = "1.7.0")] -impl From for Vec { - /// Converts a [`CString`] into a [Vec]<[u8]>. - /// - /// The conversion consumes the [`CString`], and removes the terminating NUL byte. - #[inline] - fn from(s: CString) -> Vec { - s.into_bytes() - } -} - -#[stable(feature = "cstr_default", since = "1.10.0")] -impl Default for CString { - /// Creates an empty `CString`. - fn default() -> CString { - let a: &CStr = Default::default(); - a.to_owned() - } -} - -#[stable(feature = "cstr_borrow", since = "1.3.0")] -impl Borrow for CString { - #[inline] - fn borrow(&self) -> &CStr { - self - } -} - -#[stable(feature = "cstring_from_cow_cstr", since = "1.28.0")] -impl<'a> From> for CString { - /// Converts a `Cow<'a, CStr>` into a `CString`, by copying the contents if they are - /// borrowed. - #[inline] - fn from(s: Cow<'a, CStr>) -> Self { - s.into_owned() - } -} - -#[cfg(not(test))] -#[stable(feature = "box_from_c_str", since = "1.17.0")] -impl From<&CStr> for Box { - /// Converts a `&CStr` into a `Box`, - /// by copying the contents into a newly allocated [`Box`]. - fn from(s: &CStr) -> Box { - let boxed: Box<[u8]> = Box::from(s.to_bytes_with_nul()); - unsafe { Box::from_raw(Box::into_raw(boxed) as *mut CStr) } - } -} - -#[stable(feature = "box_from_cow", since = "1.45.0")] -impl From> for Box { - /// Converts a `Cow<'a, CStr>` into a `Box`, - /// by copying the contents if they are borrowed. - #[inline] - fn from(cow: Cow<'_, CStr>) -> Box { - match cow { - Cow::Borrowed(s) => Box::from(s), - Cow::Owned(s) => Box::from(s), - } - } -} - -#[stable(feature = "c_string_from_box", since = "1.18.0")] -impl From> for CString { - /// Converts a [Box]<[CStr]> into a [`CString`] without copying or allocating. - #[inline] - fn from(s: Box) -> CString { - let raw = Box::into_raw(s) as *mut [u8]; - CString { inner: unsafe { Box::from_raw(raw) } } - } -} - -#[stable(feature = "cstring_from_vec_of_nonzerou8", since = "1.43.0")] -impl From>> for CString { - /// Converts a [Vec]<[NonZero]<[u8]>> into a [`CString`] without - /// copying nor checking for inner nul bytes. - #[inline] - fn from(v: Vec>) -> CString { - unsafe { - // Transmute `Vec>` to `Vec`. - let v: Vec = { - // SAFETY: - // - transmuting between `NonZero` and `u8` is sound; - // - `alloc::Layout> == alloc::Layout`. - let (ptr, len, cap): (*mut NonZero, _, _) = Vec::into_raw_parts(v); - Vec::from_raw_parts(ptr.cast::(), len, cap) - }; - // SAFETY: `v` cannot contain nul bytes, given the type-level - // invariant of `NonZero`. - Self::_from_vec_unchecked(v) - } - } -} - -#[cfg(not(test))] -#[stable(feature = "more_box_slice_clone", since = "1.29.0")] -impl Clone for Box { - #[inline] - fn clone(&self) -> Self { - (**self).into() - } -} - -#[stable(feature = "box_from_c_string", since = "1.20.0")] -impl From for Box { - /// Converts a [`CString`] into a [Box]<[CStr]> without copying or allocating. - #[inline] - fn from(s: CString) -> Box { - s.into_boxed_c_str() - } -} - -#[stable(feature = "cow_from_cstr", since = "1.28.0")] -impl<'a> From for Cow<'a, CStr> { - /// Converts a [`CString`] into an owned [`Cow`] without copying or allocating. - #[inline] - fn from(s: CString) -> Cow<'a, CStr> { - Cow::Owned(s) - } -} - -#[stable(feature = "cow_from_cstr", since = "1.28.0")] -impl<'a> From<&'a CStr> for Cow<'a, CStr> { - /// Converts a [`CStr`] into a borrowed [`Cow`] without copying or allocating. - #[inline] - fn from(s: &'a CStr) -> Cow<'a, CStr> { - Cow::Borrowed(s) - } -} - -#[stable(feature = "cow_from_cstr", since = "1.28.0")] -impl<'a> From<&'a CString> for Cow<'a, CStr> { - /// Converts a `&`[`CString`] into a borrowed [`Cow`] without copying or allocating. - #[inline] - fn from(s: &'a CString) -> Cow<'a, CStr> { - Cow::Borrowed(s.as_c_str()) - } -} - -#[cfg(target_has_atomic = "ptr")] -#[stable(feature = "shared_from_slice2", since = "1.24.0")] -impl From for Arc { - /// Converts a [`CString`] into an [Arc]<[CStr]> by moving the [`CString`] - /// data into a new [`Arc`] buffer. - #[inline] - fn from(s: CString) -> Arc { - let arc: Arc<[u8]> = Arc::from(s.into_inner()); - unsafe { Arc::from_raw(Arc::into_raw(arc) as *const CStr) } - } -} - -#[cfg(target_has_atomic = "ptr")] -#[stable(feature = "shared_from_slice2", since = "1.24.0")] -impl From<&CStr> for Arc { - /// Converts a `&CStr` into a `Arc`, - /// by copying the contents into a newly allocated [`Arc`]. - #[inline] - fn from(s: &CStr) -> Arc { - let arc: Arc<[u8]> = Arc::from(s.to_bytes_with_nul()); - unsafe { Arc::from_raw(Arc::into_raw(arc) as *const CStr) } - } -} - -#[stable(feature = "shared_from_slice2", since = "1.24.0")] -impl From for Rc { - /// Converts a [`CString`] into an [Rc]<[CStr]> by moving the [`CString`] - /// data into a new [`Rc`] buffer. - #[inline] - fn from(s: CString) -> Rc { - let rc: Rc<[u8]> = Rc::from(s.into_inner()); - unsafe { Rc::from_raw(Rc::into_raw(rc) as *const CStr) } - } -} - -#[stable(feature = "shared_from_slice2", since = "1.24.0")] -impl From<&CStr> for Rc { - /// Converts a `&CStr` into a `Rc`, - /// by copying the contents into a newly allocated [`Rc`]. - #[inline] - fn from(s: &CStr) -> Rc { - let rc: Rc<[u8]> = Rc::from(s.to_bytes_with_nul()); - unsafe { Rc::from_raw(Rc::into_raw(rc) as *const CStr) } - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "more_rc_default_impls", since = "CURRENT_RUSTC_VERSION")] -impl Default for Rc { - /// Creates an empty CStr inside an Rc - /// - /// This may or may not share an allocation with other Rcs on the same thread. - #[inline] - fn default() -> Self { - let c_str: &CStr = Default::default(); - Rc::from(c_str) - } -} - -#[cfg(not(test))] -#[stable(feature = "default_box_extra", since = "1.17.0")] -impl Default for Box { - fn default() -> Box { - let boxed: Box<[u8]> = Box::from([0]); - unsafe { Box::from_raw(Box::into_raw(boxed) as *mut CStr) } - } -} - -impl NulError { - /// Returns the position of the nul byte in the slice that caused - /// [`CString::new`] to fail. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::CString; - /// - /// let nul_error = CString::new("foo\0bar").unwrap_err(); - /// assert_eq!(nul_error.nul_position(), 3); - /// - /// let nul_error = CString::new("foo bar\0").unwrap_err(); - /// assert_eq!(nul_error.nul_position(), 7); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn nul_position(&self) -> usize { - self.0 - } - - /// Consumes this error, returning the underlying vector of bytes which - /// generated the error in the first place. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::CString; - /// - /// let nul_error = CString::new("foo\0bar").unwrap_err(); - /// assert_eq!(nul_error.into_vec(), b"foo\0bar"); - /// ``` - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn into_vec(self) -> Vec { - self.1 - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for NulError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "nul byte found in provided data at position: {}", self.0) - } -} - -#[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")] -impl fmt::Display for FromVecWithNulError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - match self.error_kind { - FromBytesWithNulErrorKind::InteriorNul(pos) => { - write!(f, "data provided contains an interior nul byte at pos {pos}") - } - FromBytesWithNulErrorKind::NotNulTerminated => { - write!(f, "data provided is not nul terminated") - } - } - } -} - -impl IntoStringError { - /// Consumes this error, returning original [`CString`] which generated the - /// error. - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "cstring_into", since = "1.7.0")] - pub fn into_cstring(self) -> CString { - self.inner - } - - /// Access the underlying UTF-8 error that was the cause of this error. - #[must_use] - #[stable(feature = "cstring_into", since = "1.7.0")] - pub fn utf8_error(&self) -> Utf8Error { - self.error - } -} - -impl IntoStringError { - fn description(&self) -> &str { - "C string contained non-utf8 bytes" - } -} - -#[stable(feature = "cstring_into", since = "1.7.0")] -impl fmt::Display for IntoStringError { - #[allow(deprecated, deprecated_in_future)] - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - self.description().fmt(f) - } -} - -#[stable(feature = "cstr_borrow", since = "1.3.0")] -impl ToOwned for CStr { - type Owned = CString; - - fn to_owned(&self) -> CString { - CString { inner: self.to_bytes_with_nul().into() } - } - - fn clone_into(&self, target: &mut CString) { - let mut b = into_vec(mem::take(&mut target.inner)); - self.to_bytes_with_nul().clone_into(&mut b); - target.inner = b.into_boxed_slice(); - } -} - -#[stable(feature = "cstring_asref", since = "1.7.0")] -impl From<&CStr> for CString { - /// Converts a &[CStr] into a [`CString`] - /// by copying the contents into a new allocation. - fn from(s: &CStr) -> CString { - s.to_owned() - } -} - -#[stable(feature = "cstring_asref", since = "1.7.0")] -impl ops::Index for CString { - type Output = CStr; - - #[inline] - fn index(&self, _index: ops::RangeFull) -> &CStr { - self - } -} - -#[stable(feature = "cstring_asref", since = "1.7.0")] -impl AsRef for CString { - #[inline] - fn as_ref(&self) -> &CStr { - self - } -} - -#[cfg(not(test))] -impl CStr { - /// Converts a `CStr` into a [Cow]<[str]>. - /// - /// If the contents of the `CStr` are valid UTF-8 data, this - /// function will return a [Cow]::[Borrowed]\(&[str]) - /// with the corresponding &[str] slice. Otherwise, it will - /// replace any invalid UTF-8 sequences with - /// [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD] and return a - /// [Cow]::[Owned]\(&[str]) with the result. - /// - /// [str]: prim@str "str" - /// [Borrowed]: Cow::Borrowed - /// [Owned]: Cow::Owned - /// [U+FFFD]: core::char::REPLACEMENT_CHARACTER "std::char::REPLACEMENT_CHARACTER" - /// - /// # Examples - /// - /// Calling `to_string_lossy` on a `CStr` containing valid UTF-8. The leading - /// `c` on the string literal denotes a `CStr`. - /// - /// ``` - /// use std::borrow::Cow; - /// - /// assert_eq!(c"Hello World".to_string_lossy(), Cow::Borrowed("Hello World")); - /// ``` - /// - /// Calling `to_string_lossy` on a `CStr` containing invalid UTF-8: - /// - /// ``` - /// use std::borrow::Cow; - /// - /// assert_eq!( - /// c"Hello \xF0\x90\x80World".to_string_lossy(), - /// Cow::Owned(String::from("Hello �World")) as Cow<'_, str> - /// ); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "this returns the result of the operation, \ - without modifying the original"] - #[stable(feature = "cstr_to_str", since = "1.4.0")] - pub fn to_string_lossy(&self) -> Cow<'_, str> { - String::from_utf8_lossy(self.to_bytes()) - } - - /// Converts a [Box]<[CStr]> into a [`CString`] without copying or allocating. - /// - /// # Examples - /// - /// ``` - /// use std::ffi::CString; - /// - /// let c_string = CString::new(b"foo".to_vec()).expect("CString::new failed"); - /// let boxed = c_string.into_boxed_c_str(); - /// assert_eq!(boxed.into_c_string(), CString::new("foo").expect("CString::new failed")); - /// ``` - #[rustc_allow_incoherent_impl] - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "into_boxed_c_str", since = "1.20.0")] - pub fn into_c_string(self: Box) -> CString { - CString::from(self) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl core::error::Error for NulError { - #[allow(deprecated)] - fn description(&self) -> &str { - "nul byte found in data" - } -} - -#[stable(feature = "cstring_from_vec_with_nul", since = "1.58.0")] -impl core::error::Error for FromVecWithNulError {} - -#[stable(feature = "cstring_into", since = "1.7.0")] -impl core::error::Error for IntoStringError { - #[allow(deprecated)] - fn description(&self) -> &str { - "C string contained non-utf8 bytes" - } - - fn source(&self) -> Option<&(dyn core::error::Error + 'static)> { - Some(&self.error) - } -} diff --git a/library/alloc/src/ffi/c_str/tests.rs b/library/alloc/src/ffi/c_str/tests.rs deleted file mode 100644 index 9f51e17a427f5..0000000000000 --- a/library/alloc/src/ffi/c_str/tests.rs +++ /dev/null @@ -1,226 +0,0 @@ -use super::*; -use core::assert_matches::assert_matches; -use core::ffi::FromBytesUntilNulError; -use core::hash::{Hash, Hasher}; - -#[allow(deprecated)] -use core::hash::SipHasher13 as DefaultHasher; - -#[test] -fn c_to_rust() { - let data = b"123\0"; - let ptr = data.as_ptr() as *const c_char; - unsafe { - assert_eq!(CStr::from_ptr(ptr).to_bytes(), b"123"); - assert_eq!(CStr::from_ptr(ptr).to_bytes_with_nul(), b"123\0"); - } -} - -#[test] -fn simple() { - let s = CString::new("1234").unwrap(); - assert_eq!(s.as_bytes(), b"1234"); - assert_eq!(s.as_bytes_with_nul(), b"1234\0"); -} - -#[test] -fn build_with_zero1() { - assert!(CString::new(&b"\0"[..]).is_err()); -} -#[test] -fn build_with_zero2() { - assert!(CString::new(vec![0]).is_err()); -} - -#[test] -fn formatted() { - let s = CString::new(&b"abc\x01\x02\n\xE2\x80\xA6\xFF"[..]).unwrap(); - assert_eq!(format!("{s:?}"), r#""abc\x01\x02\n\xe2\x80\xa6\xff""#); -} - -#[test] -fn borrowed() { - unsafe { - let s = CStr::from_ptr(b"12\0".as_ptr() as *const _); - assert_eq!(s.to_bytes(), b"12"); - assert_eq!(s.to_bytes_with_nul(), b"12\0"); - } -} - -#[test] -fn to_owned() { - let data = b"123\0"; - let ptr = data.as_ptr() as *const c_char; - - let owned = unsafe { CStr::from_ptr(ptr).to_owned() }; - assert_eq!(owned.as_bytes_with_nul(), data); -} - -#[test] -fn equal_hash() { - let data = b"123\xE2\xFA\xA6\0"; - let ptr = data.as_ptr() as *const c_char; - let cstr: &'static CStr = unsafe { CStr::from_ptr(ptr) }; - - #[allow(deprecated)] - let mut s = DefaultHasher::new(); - cstr.hash(&mut s); - let cstr_hash = s.finish(); - #[allow(deprecated)] - let mut s = DefaultHasher::new(); - CString::new(&data[..data.len() - 1]).unwrap().hash(&mut s); - let cstring_hash = s.finish(); - - assert_eq!(cstr_hash, cstring_hash); -} - -#[test] -fn from_bytes_with_nul() { - let data = b"123\0"; - let cstr = CStr::from_bytes_with_nul(data); - assert_eq!(cstr.map(CStr::to_bytes), Ok(&b"123"[..])); - let cstr = CStr::from_bytes_with_nul(data); - assert_eq!(cstr.map(CStr::to_bytes_with_nul), Ok(&b"123\0"[..])); - - unsafe { - let cstr = CStr::from_bytes_with_nul(data); - let cstr_unchecked = CStr::from_bytes_with_nul_unchecked(data); - assert_eq!(cstr, Ok(cstr_unchecked)); - } -} - -#[test] -fn from_bytes_with_nul_unterminated() { - let data = b"123"; - let cstr = CStr::from_bytes_with_nul(data); - assert!(cstr.is_err()); -} - -#[test] -fn from_bytes_with_nul_interior() { - let data = b"1\023\0"; - let cstr = CStr::from_bytes_with_nul(data); - assert!(cstr.is_err()); -} - -#[test] -fn cstr_from_bytes_until_nul() { - // Test an empty slice. This should fail because it - // does not contain a nul byte. - let b = b""; - assert_matches!(CStr::from_bytes_until_nul(&b[..]), Err(FromBytesUntilNulError { .. })); - - // Test a non-empty slice, that does not contain a nul byte. - let b = b"hello"; - assert_matches!(CStr::from_bytes_until_nul(&b[..]), Err(FromBytesUntilNulError { .. })); - - // Test an empty nul-terminated string - let b = b"\0"; - let r = CStr::from_bytes_until_nul(&b[..]).unwrap(); - assert_eq!(r.to_bytes(), b""); - - // Test a slice with the nul byte in the middle - let b = b"hello\0world!"; - let r = CStr::from_bytes_until_nul(&b[..]).unwrap(); - assert_eq!(r.to_bytes(), b"hello"); - - // Test a slice with the nul byte at the end - let b = b"hello\0"; - let r = CStr::from_bytes_until_nul(&b[..]).unwrap(); - assert_eq!(r.to_bytes(), b"hello"); - - // Test a slice with two nul bytes at the end - let b = b"hello\0\0"; - let r = CStr::from_bytes_until_nul(&b[..]).unwrap(); - assert_eq!(r.to_bytes(), b"hello"); - - // Test a slice containing lots of nul bytes - let b = b"\0\0\0\0"; - let r = CStr::from_bytes_until_nul(&b[..]).unwrap(); - assert_eq!(r.to_bytes(), b""); -} - -#[test] -fn into_boxed() { - let orig: &[u8] = b"Hello, world!\0"; - let cstr = CStr::from_bytes_with_nul(orig).unwrap(); - let boxed: Box = Box::from(cstr); - let cstring = cstr.to_owned().into_boxed_c_str().into_c_string(); - assert_eq!(cstr, &*boxed); - assert_eq!(&*boxed, &*cstring); - assert_eq!(&*cstring, cstr); -} - -#[test] -fn boxed_default() { - let boxed = >::default(); - assert_eq!(boxed.to_bytes_with_nul(), &[0]); -} - -#[test] -fn test_c_str_clone_into() { - let mut c_string = CString::new("lorem").unwrap(); - let c_ptr = c_string.as_ptr(); - let c_str = CStr::from_bytes_with_nul(b"ipsum\0").unwrap(); - c_str.clone_into(&mut c_string); - assert_eq!(c_str, c_string.as_c_str()); - // The exact same size shouldn't have needed to move its allocation - assert_eq!(c_ptr, c_string.as_ptr()); -} - -#[test] -fn into_rc() { - let orig: &[u8] = b"Hello, world!\0"; - let cstr = CStr::from_bytes_with_nul(orig).unwrap(); - let rc: Rc = Rc::from(cstr); - let arc: Arc = Arc::from(cstr); - - assert_eq!(&*rc, cstr); - assert_eq!(&*arc, cstr); - - let rc2: Rc = Rc::from(cstr.to_owned()); - let arc2: Arc = Arc::from(cstr.to_owned()); - - assert_eq!(&*rc2, cstr); - assert_eq!(&*arc2, cstr); -} - -#[test] -fn cstr_const_constructor() { - const CSTR: &CStr = unsafe { CStr::from_bytes_with_nul_unchecked(b"Hello, world!\0") }; - - assert_eq!(CSTR.to_str().unwrap(), "Hello, world!"); -} - -#[test] -fn cstr_index_from() { - let original = b"Hello, world!\0"; - let cstr = CStr::from_bytes_with_nul(original).unwrap(); - let result = CStr::from_bytes_with_nul(&original[7..]).unwrap(); - - assert_eq!(&cstr[7..], result); -} - -#[test] -#[should_panic] -fn cstr_index_from_empty() { - let original = b"Hello, world!\0"; - let cstr = CStr::from_bytes_with_nul(original).unwrap(); - let _ = &cstr[original.len()..]; -} - -#[test] -fn c_string_from_empty_string() { - let original = ""; - let cstring = CString::new(original).unwrap(); - assert_eq!(original.as_bytes(), cstring.as_bytes()); - assert_eq!([b'\0'], cstring.as_bytes_with_nul()); -} - -#[test] -fn c_str_from_empty_string() { - let original = b"\0"; - let cstr = CStr::from_bytes_with_nul(original).unwrap(); - assert_eq!([] as [u8; 0], cstr.to_bytes()); - assert_eq!([b'\0'], cstr.to_bytes_with_nul()); -} diff --git a/library/alloc/src/ffi/mod.rs b/library/alloc/src/ffi/mod.rs deleted file mode 100644 index 9fc1acc231bff..0000000000000 --- a/library/alloc/src/ffi/mod.rs +++ /dev/null @@ -1,92 +0,0 @@ -//! Utilities related to FFI bindings. -//! -//! This module provides utilities to handle data across non-Rust -//! interfaces, like other programming languages and the underlying -//! operating system. It is mainly of use for FFI (Foreign Function -//! Interface) bindings and code that needs to exchange C-like strings -//! with other languages. -//! -//! # Overview -//! -//! Rust represents owned strings with the [`String`] type, and -//! borrowed slices of strings with the [`str`] primitive. Both are -//! always in UTF-8 encoding, and may contain nul bytes in the middle, -//! i.e., if you look at the bytes that make up the string, there may -//! be a `\0` among them. Both `String` and `str` store their length -//! explicitly; there are no nul terminators at the end of strings -//! like in C. -//! -//! C strings are different from Rust strings: -//! -//! * **Encodings** - Rust strings are UTF-8, but C strings may use -//! other encodings. If you are using a string from C, you should -//! check its encoding explicitly, rather than just assuming that it -//! is UTF-8 like you can do in Rust. -//! -//! * **Character size** - C strings may use `char` or `wchar_t`-sized -//! characters; please **note** that C's `char` is different from Rust's. -//! The C standard leaves the actual sizes of those types open to -//! interpretation, but defines different APIs for strings made up of -//! each character type. Rust strings are always UTF-8, so different -//! Unicode characters will be encoded in a variable number of bytes -//! each. The Rust type [`char`] represents a '[Unicode scalar -//! value]', which is similar to, but not the same as, a '[Unicode -//! code point]'. -//! -//! * **Nul terminators and implicit string lengths** - Often, C -//! strings are nul-terminated, i.e., they have a `\0` character at the -//! end. The length of a string buffer is not stored, but has to be -//! calculated; to compute the length of a string, C code must -//! manually call a function like `strlen()` for `char`-based strings, -//! or `wcslen()` for `wchar_t`-based ones. Those functions return -//! the number of characters in the string excluding the nul -//! terminator, so the buffer length is really `len+1` characters. -//! Rust strings don't have a nul terminator; their length is always -//! stored and does not need to be calculated. While in Rust -//! accessing a string's length is an *O*(1) operation (because the -//! length is stored); in C it is an *O*(*n*) operation because the -//! length needs to be computed by scanning the string for the nul -//! terminator. -//! -//! * **Internal nul characters** - When C strings have a nul -//! terminator character, this usually means that they cannot have nul -//! characters in the middle — a nul character would essentially -//! truncate the string. Rust strings *can* have nul characters in -//! the middle, because nul does not have to mark the end of the -//! string in Rust. -//! -//! # Representations of non-Rust strings -//! -//! [`CString`] and [`CStr`] are useful when you need to transfer -//! UTF-8 strings to and from languages with a C ABI, like Python. -//! -//! * **From Rust to C:** [`CString`] represents an owned, C-friendly -//! string: it is nul-terminated, and has no internal nul characters. -//! Rust code can create a [`CString`] out of a normal string (provided -//! that the string doesn't have nul characters in the middle), and -//! then use a variety of methods to obtain a raw \*mut [u8] that can -//! then be passed as an argument to functions which use the C -//! conventions for strings. -//! -//! * **From C to Rust:** [`CStr`] represents a borrowed C string; it -//! is what you would use to wrap a raw \*const [u8] that you got from -//! a C function. A [`CStr`] is guaranteed to be a nul-terminated array -//! of bytes. Once you have a [`CStr`], you can convert it to a Rust -//! &[str] if it's valid UTF-8, or lossily convert it by adding -//! replacement characters. -//! -//! [`String`]: crate::string::String -//! [`CStr`]: core::ffi::CStr - -#![stable(feature = "alloc_ffi", since = "1.64.0")] - -#[doc(no_inline)] -#[stable(feature = "alloc_c_string", since = "1.64.0")] -pub use self::c_str::{FromVecWithNulError, IntoStringError, NulError}; - -#[doc(inline)] -#[stable(feature = "alloc_c_string", since = "1.64.0")] -pub use self::c_str::CString; - -#[unstable(feature = "c_str_module", issue = "112134")] -pub mod c_str; diff --git a/library/alloc/src/fmt.rs b/library/alloc/src/fmt.rs deleted file mode 100644 index ae44cab8131b5..0000000000000 --- a/library/alloc/src/fmt.rs +++ /dev/null @@ -1,640 +0,0 @@ -//! Utilities for formatting and printing `String`s. -//! -//! This module contains the runtime support for the [`format!`] syntax extension. -//! This macro is implemented in the compiler to emit calls to this module in -//! order to format arguments at runtime into strings. -//! -//! # Usage -//! -//! The [`format!`] macro is intended to be familiar to those coming from C's -//! `printf`/`fprintf` functions or Python's `str.format` function. -//! -//! Some examples of the [`format!`] extension are: -//! -//! ``` -//! format!("Hello"); // => "Hello" -//! format!("Hello, {}!", "world"); // => "Hello, world!" -//! format!("The number is {}", 1); // => "The number is 1" -//! format!("{:?}", (3, 4)); // => "(3, 4)" -//! format!("{value}", value=4); // => "4" -//! let people = "Rustaceans"; -//! format!("Hello {people}!"); // => "Hello Rustaceans!" -//! format!("{} {}", 1, 2); // => "1 2" -//! format!("{:04}", 42); // => "0042" with leading zeros -//! format!("{:#?}", (100, 200)); // => "( -//! // 100, -//! // 200, -//! // )" -//! ``` -//! -//! From these, you can see that the first argument is a format string. It is -//! required by the compiler for this to be a string literal; it cannot be a -//! variable passed in (in order to perform validity checking). The compiler -//! will then parse the format string and determine if the list of arguments -//! provided is suitable to pass to this format string. -//! -//! To convert a single value to a string, use the [`to_string`] method. This -//! will use the [`Display`] formatting trait. -//! -//! ## Positional parameters -//! -//! Each formatting argument is allowed to specify which value argument it's -//! referencing, and if omitted it is assumed to be "the next argument". For -//! example, the format string `{} {} {}` would take three parameters, and they -//! would be formatted in the same order as they're given. The format string -//! `{2} {1} {0}`, however, would format arguments in reverse order. -//! -//! Things can get a little tricky once you start intermingling the two types of -//! positional specifiers. The "next argument" specifier can be thought of as an -//! iterator over the argument. Each time a "next argument" specifier is seen, -//! the iterator advances. This leads to behavior like this: -//! -//! ``` -//! format!("{1} {} {0} {}", 1, 2); // => "2 1 1 2" -//! ``` -//! -//! The internal iterator over the argument has not been advanced by the time -//! the first `{}` is seen, so it prints the first argument. Then upon reaching -//! the second `{}`, the iterator has advanced forward to the second argument. -//! Essentially, parameters that explicitly name their argument do not affect -//! parameters that do not name an argument in terms of positional specifiers. -//! -//! A format string is required to use all of its arguments, otherwise it is a -//! compile-time error. You may refer to the same argument more than once in the -//! format string. -//! -//! ## Named parameters -//! -//! Rust itself does not have a Python-like equivalent of named parameters to a -//! function, but the [`format!`] macro is a syntax extension that allows it to -//! leverage named parameters. Named parameters are listed at the end of the -//! argument list and have the syntax: -//! -//! ```text -//! identifier '=' expression -//! ``` -//! -//! For example, the following [`format!`] expressions all use named arguments: -//! -//! ``` -//! format!("{argument}", argument = "test"); // => "test" -//! format!("{name} {}", 1, name = 2); // => "2 1" -//! format!("{a} {c} {b}", a="a", b='b', c=3); // => "a 3 b" -//! ``` -//! -//! If a named parameter does not appear in the argument list, `format!` will -//! reference a variable with that name in the current scope. -//! -//! ``` -//! let argument = 2 + 2; -//! format!("{argument}"); // => "4" -//! -//! fn make_string(a: u32, b: &str) -> String { -//! format!("{b} {a}") -//! } -//! make_string(927, "label"); // => "label 927" -//! ``` -//! -//! It is not valid to put positional parameters (those without names) after -//! arguments that have names. Like with positional parameters, it is not -//! valid to provide named parameters that are unused by the format string. -//! -//! # Formatting Parameters -//! -//! Each argument being formatted can be transformed by a number of formatting -//! parameters (corresponding to `format_spec` in [the syntax](#syntax)). These -//! parameters affect the string representation of what's being formatted. -//! -//! ## Width -//! -//! ``` -//! // All of these print "Hello x !" -//! println!("Hello {:5}!", "x"); -//! println!("Hello {:1$}!", "x", 5); -//! println!("Hello {1:0$}!", 5, "x"); -//! println!("Hello {:width$}!", "x", width = 5); -//! let width = 5; -//! println!("Hello {:width$}!", "x"); -//! ``` -//! -//! This is a parameter for the "minimum width" that the format should take up. -//! If the value's string does not fill up this many characters, then the -//! padding specified by fill/alignment will be used to take up the required -//! space (see below). -//! -//! The value for the width can also be provided as a [`usize`] in the list of -//! parameters by adding a postfix `$`, indicating that the second argument is -//! a [`usize`] specifying the width. -//! -//! Referring to an argument with the dollar syntax does not affect the "next -//! argument" counter, so it's usually a good idea to refer to arguments by -//! position, or use named arguments. -//! -//! ## Fill/Alignment -//! -//! ``` -//! assert_eq!(format!("Hello {:<5}!", "x"), "Hello x !"); -//! assert_eq!(format!("Hello {:-<5}!", "x"), "Hello x----!"); -//! assert_eq!(format!("Hello {:^5}!", "x"), "Hello x !"); -//! assert_eq!(format!("Hello {:>5}!", "x"), "Hello x!"); -//! ``` -//! -//! The optional fill character and alignment is provided normally in conjunction with the -//! [`width`](#width) parameter. It must be defined before `width`, right after the `:`. -//! This indicates that if the value being formatted is smaller than -//! `width` some extra characters will be printed around it. -//! Filling comes in the following variants for different alignments: -//! -//! * `[fill]<` - the argument is left-aligned in `width` columns -//! * `[fill]^` - the argument is center-aligned in `width` columns -//! * `[fill]>` - the argument is right-aligned in `width` columns -//! -//! The default [fill/alignment](#fillalignment) for non-numerics is a space and -//! left-aligned. The -//! default for numeric formatters is also a space character but with right-alignment. If -//! the `0` flag (see below) is specified for numerics, then the implicit fill character is -//! `0`. -//! -//! Note that alignment might not be implemented by some types. In particular, it -//! is not generally implemented for the `Debug` trait. A good way to ensure -//! padding is applied is to format your input, then pad this resulting string -//! to obtain your output: -//! -//! ``` -//! println!("Hello {:^15}!", format!("{:?}", Some("hi"))); // => "Hello Some("hi") !" -//! ``` -//! -//! ## Sign/`#`/`0` -//! -//! ``` -//! assert_eq!(format!("Hello {:+}!", 5), "Hello +5!"); -//! assert_eq!(format!("{:#x}!", 27), "0x1b!"); -//! assert_eq!(format!("Hello {:05}!", 5), "Hello 00005!"); -//! assert_eq!(format!("Hello {:05}!", -5), "Hello -0005!"); -//! assert_eq!(format!("{:#010x}!", 27), "0x0000001b!"); -//! ``` -//! -//! These are all flags altering the behavior of the formatter. -//! -//! * `+` - This is intended for numeric types and indicates that the sign -//! should always be printed. By default only the negative sign of signed values -//! is printed, and the sign of positive or unsigned values is omitted. -//! This flag indicates that the correct sign (`+` or `-`) should always be printed. -//! * `-` - Currently not used -//! * `#` - This flag indicates that the "alternate" form of printing should -//! be used. The alternate forms are: -//! * `#?` - pretty-print the [`Debug`] formatting (adds linebreaks and indentation) -//! * `#x` - precedes the argument with a `0x` -//! * `#X` - precedes the argument with a `0x` -//! * `#b` - precedes the argument with a `0b` -//! * `#o` - precedes the argument with a `0o` -//! -//! See [Formatting traits](#formatting-traits) for a description of what the `?`, `x`, `X`, -//! `b`, and `o` flags do. -//! -//! * `0` - This is used to indicate for integer formats that the padding to `width` should -//! both be done with a `0` character as well as be sign-aware. A format -//! like `{:08}` would yield `00000001` for the integer `1`, while the -//! same format would yield `-0000001` for the integer `-1`. Notice that -//! the negative version has one fewer zero than the positive version. -//! Note that padding zeros are always placed after the sign (if any) -//! and before the digits. When used together with the `#` flag, a similar -//! rule applies: padding zeros are inserted after the prefix but before -//! the digits. The prefix is included in the total width. -//! This flag overrides the [fill character and alignment flag](#fillalignment). -//! -//! ## Precision -//! -//! For non-numeric types, this can be considered a "maximum width". If the resulting string is -//! longer than this width, then it is truncated down to this many characters and that truncated -//! value is emitted with proper `fill`, `alignment` and `width` if those parameters are set. -//! -//! For integral types, this is ignored. -//! -//! For floating-point types, this indicates how many digits after the decimal point should be -//! printed. -//! -//! There are three possible ways to specify the desired `precision`: -//! -//! 1. An integer `.N`: -//! -//! the integer `N` itself is the precision. -//! -//! 2. An integer or name followed by dollar sign `.N$`: -//! -//! use format *argument* `N` (which must be a `usize`) as the precision. -//! -//! 3. An asterisk `.*`: -//! -//! `.*` means that this `{...}` is associated with *two* format inputs rather than one: -//! - If a format string in the fashion of `{:.*}` is used, then the first input holds -//! the `usize` precision, and the second holds the value to print. -//! - If a format string in the fashion of `{:.*}` is used, then the `` part -//! refers to the value to print, and the `precision` is taken like it was specified with an -//! omitted positional parameter (`{}` instead of `{:}`). -//! -//! For example, the following calls all print the same thing `Hello x is 0.01000`: -//! -//! ``` -//! // Hello {arg 0 ("x")} is {arg 1 (0.01) with precision specified inline (5)} -//! println!("Hello {0} is {1:.5}", "x", 0.01); -//! -//! // Hello {arg 1 ("x")} is {arg 2 (0.01) with precision specified in arg 0 (5)} -//! println!("Hello {1} is {2:.0$}", 5, "x", 0.01); -//! -//! // Hello {arg 0 ("x")} is {arg 2 (0.01) with precision specified in arg 1 (5)} -//! println!("Hello {0} is {2:.1$}", "x", 5, 0.01); -//! -//! // Hello {next arg -> arg 0 ("x")} is {second of next two args -> arg 2 (0.01) with precision -//! // specified in first of next two args -> arg 1 (5)} -//! println!("Hello {} is {:.*}", "x", 5, 0.01); -//! -//! // Hello {arg 1 ("x")} is {arg 2 (0.01) with precision -//! // specified in next arg -> arg 0 (5)} -//! println!("Hello {1} is {2:.*}", 5, "x", 0.01); -//! -//! // Hello {next arg -> arg 0 ("x")} is {arg 2 (0.01) with precision -//! // specified in next arg -> arg 1 (5)} -//! println!("Hello {} is {2:.*}", "x", 5, 0.01); -//! -//! // Hello {next arg -> arg 0 ("x")} is {arg "number" (0.01) with precision specified -//! // in arg "prec" (5)} -//! println!("Hello {} is {number:.prec$}", "x", prec = 5, number = 0.01); -//! ``` -//! -//! While these: -//! -//! ``` -//! println!("{}, `{name:.*}` has 3 fractional digits", "Hello", 3, name=1234.56); -//! println!("{}, `{name:.*}` has 3 characters", "Hello", 3, name="1234.56"); -//! println!("{}, `{name:>8.*}` has 3 right-aligned characters", "Hello", 3, name="1234.56"); -//! ``` -//! -//! print three significantly different things: -//! -//! ```text -//! Hello, `1234.560` has 3 fractional digits -//! Hello, `123` has 3 characters -//! Hello, ` 123` has 3 right-aligned characters -//! ``` -//! -//! When truncating these values, Rust uses [round half-to-even](https://en.wikipedia.org/wiki/Rounding#Rounding_half_to_even), -//! which is the default rounding mode in IEEE 754. -//! For example, -//! -//! ``` -//! print!("{0:.1$e}", 12345, 3); -//! print!("{0:.1$e}", 12355, 3); -//! ``` -//! -//! Would return: -//! -//! ```text -//! 1.234e4 -//! 1.236e4 -//! ``` -//! -//! ## Localization -//! -//! In some programming languages, the behavior of string formatting functions -//! depends on the operating system's locale setting. The format functions -//! provided by Rust's standard library do not have any concept of locale and -//! will produce the same results on all systems regardless of user -//! configuration. -//! -//! For example, the following code will always print `1.5` even if the system -//! locale uses a decimal separator other than a dot. -//! -//! ``` -//! println!("The value is {}", 1.5); -//! ``` -//! -//! # Escaping -//! -//! The literal characters `{` and `}` may be included in a string by preceding -//! them with the same character. For example, the `{` character is escaped with -//! `{{` and the `}` character is escaped with `}}`. -//! -//! ``` -//! assert_eq!(format!("Hello {{}}"), "Hello {}"); -//! assert_eq!(format!("{{ Hello"), "{ Hello"); -//! ``` -//! -//! # Syntax -//! -//! To summarize, here you can find the full grammar of format strings. -//! The syntax for the formatting language used is drawn from other languages, -//! so it should not be too alien. Arguments are formatted with Python-like -//! syntax, meaning that arguments are surrounded by `{}` instead of the C-like -//! `%`. The actual grammar for the formatting syntax is: -//! -//! ```text -//! format_string := text [ maybe_format text ] * -//! maybe_format := '{' '{' | '}' '}' | format -//! format := '{' [ argument ] [ ':' format_spec ] [ ws ] * '}' -//! argument := integer | identifier -//! -//! format_spec := [[fill]align][sign]['#']['0'][width]['.' precision]type -//! fill := character -//! align := '<' | '^' | '>' -//! sign := '+' | '-' -//! width := count -//! precision := count | '*' -//! type := '' | '?' | 'x?' | 'X?' | identifier -//! count := parameter | integer -//! parameter := argument '$' -//! ``` -//! In the above grammar, -//! - `text` must not contain any `'{'` or `'}'` characters, -//! - `ws` is any character for which [`char::is_whitespace`] returns `true`, has no semantic -//! meaning and is completely optional, -//! - `integer` is a decimal integer that may contain leading zeroes and must fit into an `usize` and -//! - `identifier` is an `IDENTIFIER_OR_KEYWORD` (not an `IDENTIFIER`) as defined by the [Rust language reference](https://doc.rust-lang.org/reference/identifiers.html). -//! -//! # Formatting traits -//! -//! When requesting that an argument be formatted with a particular type, you -//! are actually requesting that an argument ascribes to a particular trait. -//! This allows multiple actual types to be formatted via `{:x}` (like [`i8`] as -//! well as [`isize`]). The current mapping of types to traits is: -//! -//! * *nothing* ⇒ [`Display`] -//! * `?` ⇒ [`Debug`] -//! * `x?` ⇒ [`Debug`] with lower-case hexadecimal integers -//! * `X?` ⇒ [`Debug`] with upper-case hexadecimal integers -//! * `o` ⇒ [`Octal`] -//! * `x` ⇒ [`LowerHex`] -//! * `X` ⇒ [`UpperHex`] -//! * `p` ⇒ [`Pointer`] -//! * `b` ⇒ [`Binary`] -//! * `e` ⇒ [`LowerExp`] -//! * `E` ⇒ [`UpperExp`] -//! -//! What this means is that any type of argument which implements the -//! [`fmt::Binary`][`Binary`] trait can then be formatted with `{:b}`. Implementations -//! are provided for these traits for a number of primitive types by the -//! standard library as well. If no format is specified (as in `{}` or `{:6}`), -//! then the format trait used is the [`Display`] trait. -//! -//! When implementing a format trait for your own type, you will have to -//! implement a method of the signature: -//! -//! ``` -//! # #![allow(dead_code)] -//! # use std::fmt; -//! # struct Foo; // our custom type -//! # impl fmt::Display for Foo { -//! fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { -//! # write!(f, "testing, testing") -//! # } } -//! ``` -//! -//! Your type will be passed as `self` by-reference, and then the function -//! should emit output into the Formatter `f` which implements `fmt::Write`. It is up to each -//! format trait implementation to correctly adhere to the requested formatting parameters. -//! The values of these parameters can be accessed with methods of the -//! [`Formatter`] struct. In order to help with this, the [`Formatter`] struct also -//! provides some helper methods. -//! -//! Additionally, the return value of this function is [`fmt::Result`] which is a -//! type alias of [Result]<(), [std::fmt::Error]>. Formatting implementations -//! should ensure that they propagate errors from the [`Formatter`] (e.g., when -//! calling [`write!`]). However, they should never return errors spuriously. That -//! is, a formatting implementation must and may only return an error if the -//! passed-in [`Formatter`] returns an error. This is because, contrary to what -//! the function signature might suggest, string formatting is an infallible -//! operation. This function only returns a [`Result`] because writing to the -//! underlying stream might fail and it must provide a way to propagate the fact -//! that an error has occurred back up the stack. -//! -//! An example of implementing the formatting traits would look -//! like: -//! -//! ``` -//! use std::fmt; -//! -//! #[derive(Debug)] -//! struct Vector2D { -//! x: isize, -//! y: isize, -//! } -//! -//! impl fmt::Display for Vector2D { -//! fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { -//! // The `f` value implements the `Write` trait, which is what the -//! // write! macro is expecting. Note that this formatting ignores the -//! // various flags provided to format strings. -//! write!(f, "({}, {})", self.x, self.y) -//! } -//! } -//! -//! // Different traits allow different forms of output of a type. The meaning -//! // of this format is to print the magnitude of a vector. -//! impl fmt::Binary for Vector2D { -//! fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { -//! let magnitude = (self.x * self.x + self.y * self.y) as f64; -//! let magnitude = magnitude.sqrt(); -//! -//! // Respect the formatting flags by using the helper method -//! // `pad_integral` on the Formatter object. See the method -//! // documentation for details, and the function `pad` can be used -//! // to pad strings. -//! let decimals = f.precision().unwrap_or(3); -//! let string = format!("{magnitude:.decimals$}"); -//! f.pad_integral(true, "", &string) -//! } -//! } -//! -//! fn main() { -//! let myvector = Vector2D { x: 3, y: 4 }; -//! -//! println!("{myvector}"); // => "(3, 4)" -//! println!("{myvector:?}"); // => "Vector2D {x: 3, y:4}" -//! println!("{myvector:10.3b}"); // => " 5.000" -//! } -//! ``` -//! -//! ### `fmt::Display` vs `fmt::Debug` -//! -//! These two formatting traits have distinct purposes: -//! -//! - [`fmt::Display`][`Display`] implementations assert that the type can be faithfully -//! represented as a UTF-8 string at all times. It is **not** expected that -//! all types implement the [`Display`] trait. -//! - [`fmt::Debug`][`Debug`] implementations should be implemented for **all** public types. -//! Output will typically represent the internal state as faithfully as possible. -//! The purpose of the [`Debug`] trait is to facilitate debugging Rust code. In -//! most cases, using `#[derive(Debug)]` is sufficient and recommended. -//! -//! Some examples of the output from both traits: -//! -//! ``` -//! assert_eq!(format!("{} {:?}", 3, 4), "3 4"); -//! assert_eq!(format!("{} {:?}", 'a', 'b'), "a 'b'"); -//! assert_eq!(format!("{} {:?}", "foo\n", "bar\n"), "foo\n \"bar\\n\""); -//! ``` -//! -//! # Related macros -//! -//! There are a number of related macros in the [`format!`] family. The ones that -//! are currently implemented are: -//! -//! ```ignore (only-for-syntax-highlight) -//! format! // described above -//! write! // first argument is either a &mut io::Write or a &mut fmt::Write, the destination -//! writeln! // same as write but appends a newline -//! print! // the format string is printed to the standard output -//! println! // same as print but appends a newline -//! eprint! // the format string is printed to the standard error -//! eprintln! // same as eprint but appends a newline -//! format_args! // described below. -//! ``` -//! -//! ### `write!` -//! -//! [`write!`] and [`writeln!`] are two macros which are used to emit the format string -//! to a specified stream. This is used to prevent intermediate allocations of -//! format strings and instead directly write the output. Under the hood, this -//! function is actually invoking the [`write_fmt`] function defined on the -//! [`std::io::Write`] and the [`std::fmt::Write`] trait. Example usage is: -//! -//! ``` -//! # #![allow(unused_must_use)] -//! use std::io::Write; -//! let mut w = Vec::new(); -//! write!(&mut w, "Hello {}!", "world"); -//! ``` -//! -//! ### `print!` -//! -//! This and [`println!`] emit their output to stdout. Similarly to the [`write!`] -//! macro, the goal of these macros is to avoid intermediate allocations when -//! printing output. Example usage is: -//! -//! ``` -//! print!("Hello {}!", "world"); -//! println!("I have a newline {}", "character at the end"); -//! ``` -//! ### `eprint!` -//! -//! The [`eprint!`] and [`eprintln!`] macros are identical to -//! [`print!`] and [`println!`], respectively, except they emit their -//! output to stderr. -//! -//! ### `format_args!` -//! -//! [`format_args!`] is a curious macro used to safely pass around -//! an opaque object describing the format string. This object -//! does not require any heap allocations to create, and it only -//! references information on the stack. Under the hood, all of -//! the related macros are implemented in terms of this. First -//! off, some example usage is: -//! -//! ``` -//! # #![allow(unused_must_use)] -//! use std::fmt; -//! use std::io::{self, Write}; -//! -//! let mut some_writer = io::stdout(); -//! write!(&mut some_writer, "{}", format_args!("print with a {}", "macro")); -//! -//! fn my_fmt_fn(args: fmt::Arguments<'_>) { -//! write!(&mut io::stdout(), "{args}"); -//! } -//! my_fmt_fn(format_args!(", or a {} too", "function")); -//! ``` -//! -//! The result of the [`format_args!`] macro is a value of type [`fmt::Arguments`]. -//! This structure can then be passed to the [`write`] and [`format`] functions -//! inside this module in order to process the format string. -//! The goal of this macro is to even further prevent intermediate allocations -//! when dealing with formatting strings. -//! -//! For example, a logging library could use the standard formatting syntax, but -//! it would internally pass around this structure until it has been determined -//! where output should go to. -//! -//! [`fmt::Result`]: Result "fmt::Result" -//! [Result]: core::result::Result "std::result::Result" -//! [std::fmt::Error]: Error "fmt::Error" -//! [`write`]: write() "fmt::write" -//! [`to_string`]: crate::string::ToString::to_string "ToString::to_string" -//! [`write_fmt`]: ../../std/io/trait.Write.html#method.write_fmt -//! [`std::io::Write`]: ../../std/io/trait.Write.html -//! [`std::fmt::Write`]: ../../std/fmt/trait.Write.html -//! [`print!`]: ../../std/macro.print.html "print!" -//! [`println!`]: ../../std/macro.println.html "println!" -//! [`eprint!`]: ../../std/macro.eprint.html "eprint!" -//! [`eprintln!`]: ../../std/macro.eprintln.html "eprintln!" -//! [`format_args!`]: ../../std/macro.format_args.html "format_args!" -//! [`fmt::Arguments`]: Arguments "fmt::Arguments" -//! [`format`]: format() "fmt::format" - -#![stable(feature = "rust1", since = "1.0.0")] - -#[stable(feature = "fmt_flags_align", since = "1.28.0")] -pub use core::fmt::Alignment; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::fmt::Error; -#[unstable(feature = "debug_closure_helpers", issue = "117729")] -pub use core::fmt::FormatterFn; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::fmt::{write, Arguments}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::fmt::{Binary, Octal}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::fmt::{Debug, Display}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::fmt::{DebugList, DebugMap, DebugSet, DebugStruct, DebugTuple}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::fmt::{Formatter, Result, Write}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::fmt::{LowerExp, UpperExp}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::fmt::{LowerHex, Pointer, UpperHex}; - -#[cfg(not(no_global_oom_handling))] -use crate::string; - -/// The `format` function takes an [`Arguments`] struct and returns the resulting -/// formatted string. -/// -/// The [`Arguments`] instance can be created with the [`format_args!`] macro. -/// -/// # Examples -/// -/// Basic usage: -/// -/// ``` -/// use std::fmt; -/// -/// let s = fmt::format(format_args!("Hello, {}!", "world")); -/// assert_eq!(s, "Hello, world!"); -/// ``` -/// -/// Please note that using [`format!`] might be preferable. -/// Example: -/// -/// ``` -/// let s = format!("Hello, {}!", "world"); -/// assert_eq!(s, "Hello, world!"); -/// ``` -/// -/// [`format_args!`]: core::format_args -/// [`format!`]: crate::format -#[cfg(not(no_global_oom_handling))] -#[must_use] -#[stable(feature = "rust1", since = "1.0.0")] -#[inline] -pub fn format(args: Arguments<'_>) -> string::String { - fn format_inner(args: Arguments<'_>) -> string::String { - let capacity = args.estimated_capacity(); - let mut output = string::String::with_capacity(capacity); - output - .write_fmt(args) - .expect("a formatting trait implementation returned an error when the underlying stream did not"); - output - } - - args.as_str().map_or_else(|| format_inner(args), crate::borrow::ToOwned::to_owned) -} diff --git a/library/alloc/src/lib.miri.rs b/library/alloc/src/lib.miri.rs deleted file mode 100644 index 89d7f49f55d2e..0000000000000 --- a/library/alloc/src/lib.miri.rs +++ /dev/null @@ -1,4 +0,0 @@ -//! Grep bootstrap for `MIRI_REPLACE_LIBRS_IF_NOT_TEST` to learn what this is about. -#![no_std] -extern crate alloc as realalloc; -pub use realalloc::*; diff --git a/library/alloc/src/lib.rs b/library/alloc/src/lib.rs deleted file mode 100644 index 4ac0c9b15be7a..0000000000000 --- a/library/alloc/src/lib.rs +++ /dev/null @@ -1,280 +0,0 @@ -//! # The Rust core allocation and collections library -//! -//! This library provides smart pointers and collections for managing -//! heap-allocated values. -//! -//! This library, like core, normally doesn’t need to be used directly -//! since its contents are re-exported in the [`std` crate](../std/index.html). -//! Crates that use the `#![no_std]` attribute however will typically -//! not depend on `std`, so they’d use this crate instead. -//! -//! ## Boxed values -//! -//! The [`Box`] type is a smart pointer type. There can only be one owner of a -//! [`Box`], and the owner can decide to mutate the contents, which live on the -//! heap. -//! -//! This type can be sent among threads efficiently as the size of a `Box` value -//! is the same as that of a pointer. Tree-like data structures are often built -//! with boxes because each node often has only one owner, the parent. -//! -//! ## Reference counted pointers -//! -//! The [`Rc`] type is a non-threadsafe reference-counted pointer type intended -//! for sharing memory within a thread. An [`Rc`] pointer wraps a type, `T`, and -//! only allows access to `&T`, a shared reference. -//! -//! This type is useful when inherited mutability (such as using [`Box`]) is too -//! constraining for an application, and is often paired with the [`Cell`] or -//! [`RefCell`] types in order to allow mutation. -//! -//! ## Atomically reference counted pointers -//! -//! The [`Arc`] type is the threadsafe equivalent of the [`Rc`] type. It -//! provides all the same functionality of [`Rc`], except it requires that the -//! contained type `T` is shareable. Additionally, [`Arc`][`Arc`] is itself -//! sendable while [`Rc`][`Rc`] is not. -//! -//! This type allows for shared access to the contained data, and is often -//! paired with synchronization primitives such as mutexes to allow mutation of -//! shared resources. -//! -//! ## Collections -//! -//! Implementations of the most common general purpose data structures are -//! defined in this library. They are re-exported through the -//! [standard collections library](../std/collections/index.html). -//! -//! ## Heap interfaces -//! -//! The [`alloc`](alloc/index.html) module defines the low-level interface to the -//! default global allocator. It is not compatible with the libc allocator API. -//! -//! [`Arc`]: sync -//! [`Box`]: boxed -//! [`Cell`]: core::cell -//! [`Rc`]: rc -//! [`RefCell`]: core::cell - -#![allow(unused_attributes)] -#![stable(feature = "alloc", since = "1.36.0")] -#![doc( - html_playground_url = "https://play.rust-lang.org/", - issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/", - test(no_crate_inject, attr(allow(unused_variables), deny(warnings))) -)] -#![doc(cfg_hide( - not(test), - not(any(test, bootstrap)), - no_global_oom_handling, - not(no_global_oom_handling), - not(no_rc), - not(no_sync), - target_has_atomic = "ptr" -))] -#![doc(rust_logo)] -#![feature(rustdoc_internals)] -#![no_std] -#![needs_allocator] -// Lints: -#![deny(unsafe_op_in_unsafe_fn)] -#![deny(fuzzy_provenance_casts)] -#![warn(deprecated_in_future)] -#![warn(missing_debug_implementations)] -#![warn(missing_docs)] -#![allow(explicit_outlives_requirements)] -#![warn(multiple_supertrait_upcastable)] -#![allow(internal_features)] -#![allow(rustdoc::redundant_explicit_links)] -#![deny(ffi_unwind_calls)] -// -// Library features: -// tidy-alphabetical-start -#![cfg_attr(not(no_global_oom_handling), feature(const_alloc_error))] -#![cfg_attr(not(no_global_oom_handling), feature(const_btree_len))] -#![cfg_attr(test, feature(is_sorted))] -#![cfg_attr(test, feature(new_uninit))] -#![feature(alloc_layout_extra)] -#![feature(allocator_api)] -#![feature(array_chunks)] -#![feature(array_into_iter_constructors)] -#![feature(array_windows)] -#![feature(ascii_char)] -#![feature(assert_matches)] -#![feature(async_fn_traits)] -#![feature(async_iterator)] -#![feature(coerce_unsized)] -#![feature(const_align_of_val)] -#![feature(const_box)] -#![feature(const_cow_is_borrowed)] -#![feature(const_eval_select)] -#![feature(const_heap)] -#![feature(const_maybe_uninit_as_mut_ptr)] -#![feature(const_maybe_uninit_write)] -#![feature(const_option)] -#![feature(const_pin)] -#![feature(const_refs_to_cell)] -#![feature(const_size_of_val)] -#![feature(const_waker)] -#![feature(core_intrinsics)] -#![feature(deprecated_suggestion)] -#![feature(deref_pure_trait)] -#![feature(dispatch_from_dyn)] -#![feature(error_generic_member_access)] -#![feature(error_in_core)] -#![feature(exact_size_is_empty)] -#![feature(extend_one)] -#![feature(fmt_internals)] -#![feature(fn_traits)] -#![feature(hasher_prefixfree_extras)] -#![feature(hint_assert_unchecked)] -#![feature(inplace_iteration)] -#![feature(iter_advance_by)] -#![feature(iter_next_chunk)] -#![feature(iter_repeat_n)] -#![feature(layout_for_ptr)] -#![feature(local_waker)] -#![feature(maybe_uninit_slice)] -#![feature(maybe_uninit_uninit_array)] -#![feature(maybe_uninit_uninit_array_transpose)] -#![feature(panic_internals)] -#![feature(pattern)] -#![feature(ptr_internals)] -#![feature(ptr_metadata)] -#![feature(ptr_sub_ptr)] -#![feature(receiver_trait)] -#![feature(set_ptr_value)] -#![feature(sized_type_properties)] -#![feature(slice_from_ptr_range)] -#![feature(slice_index_methods)] -#![feature(slice_ptr_get)] -#![feature(slice_range)] -#![feature(std_internals)] -#![feature(str_internals)] -#![feature(strict_provenance)] -#![feature(trusted_fused)] -#![feature(trusted_len)] -#![feature(trusted_random_access)] -#![feature(try_trait_v2)] -#![feature(try_with_capacity)] -#![feature(tuple_trait)] -#![feature(unicode_internals)] -#![feature(unsize)] -#![feature(unwrap_infallible)] -#![feature(vec_pop_if)] -// tidy-alphabetical-end -// -// Language features: -// tidy-alphabetical-start -#![cfg_attr(bootstrap, feature(exclusive_range_pattern))] -#![cfg_attr(not(test), feature(coroutine_trait))] -#![cfg_attr(test, feature(panic_update_hook))] -#![cfg_attr(test, feature(test))] -#![feature(allocator_internals)] -#![feature(allow_internal_unstable)] -#![feature(c_unwind)] -#![feature(cfg_sanitize)] -#![feature(const_mut_refs)] -#![feature(const_precise_live_drops)] -#![feature(const_ptr_write)] -#![feature(const_trait_impl)] -#![feature(const_try)] -#![feature(decl_macro)] -#![feature(dropck_eyepatch)] -#![feature(fundamental)] -#![feature(hashmap_internals)] -#![feature(lang_items)] -#![feature(min_specialization)] -#![feature(multiple_supertrait_upcastable)] -#![feature(negative_impls)] -#![feature(never_type)] -#![feature(rustc_allow_const_fn_unstable)] -#![feature(rustc_attrs)] -#![feature(slice_internals)] -#![feature(staged_api)] -#![feature(stmt_expr_attributes)] -#![feature(unboxed_closures)] -#![feature(unsized_fn_params)] -#![feature(with_negative_coherence)] -#![rustc_preserve_ub_checks] -// tidy-alphabetical-end -// -// Rustdoc features: -#![feature(doc_cfg)] -#![feature(doc_cfg_hide)] -// Technically, this is a bug in rustdoc: rustdoc sees the documentation on `#[lang = slice_alloc]` -// blocks is for `&[T]`, which also has documentation using this feature in `core`, and gets mad -// that the feature-gate isn't enabled. Ideally, it wouldn't check for the feature gate for docs -// from other crates, but since this can only appear for lang items, it doesn't seem worth fixing. -#![feature(intra_doc_pointers)] - -// Allow testing this library -#[cfg(test)] -#[macro_use] -extern crate std; -#[cfg(test)] -extern crate test; -#[cfg(test)] -mod testing; - -// Module with internal macros used by other modules (needs to be included before other modules). -#[macro_use] -mod macros; - -mod raw_vec; - -// Heaps provided for low-level allocation strategies - -pub mod alloc; - -// Primitive types using the heaps above - -// Need to conditionally define the mod from `boxed.rs` to avoid -// duplicating the lang-items when building in test cfg; but also need -// to allow code to have `use boxed::Box;` declarations. -#[cfg(not(test))] -pub mod boxed; -#[cfg(test)] -mod boxed { - pub use std::boxed::Box; -} -pub mod borrow; -pub mod collections; -#[cfg(all(not(no_rc), not(no_sync), not(no_global_oom_handling)))] -pub mod ffi; -pub mod fmt; -#[cfg(not(no_rc))] -pub mod rc; -pub mod slice; -pub mod str; -pub mod string; -#[cfg(all(not(no_rc), not(no_sync), target_has_atomic = "ptr"))] -pub mod sync; -#[cfg(all(not(no_global_oom_handling), not(no_rc), not(no_sync)))] -pub mod task; -#[cfg(test)] -mod tests; -pub mod vec; - -#[doc(hidden)] -#[unstable(feature = "liballoc_internals", issue = "none", reason = "implementation detail")] -pub mod __export { - pub use core::format_args; -} - -#[cfg(test)] -#[allow(dead_code)] // Not used in all configurations -pub(crate) mod test_helpers { - /// Copied from `std::test_helpers::test_rng`, since these tests rely on the - /// seed not being the same for every RNG invocation too. - pub(crate) fn test_rng() -> rand_xorshift::XorShiftRng { - use std::hash::{BuildHasher, Hash, Hasher}; - let mut hasher = std::hash::RandomState::new().build_hasher(); - std::panic::Location::caller().hash(&mut hasher); - let hc64 = hasher.finish(); - let seed_vec = - hc64.to_le_bytes().into_iter().chain(0u8..8).collect::>(); - let seed: [u8; 16] = seed_vec.as_slice().try_into().unwrap(); - rand::SeedableRng::from_seed(seed) - } -} diff --git a/library/alloc/src/macros.rs b/library/alloc/src/macros.rs deleted file mode 100644 index 0f767df6063a3..0000000000000 --- a/library/alloc/src/macros.rs +++ /dev/null @@ -1,138 +0,0 @@ -/// Creates a [`Vec`] containing the arguments. -/// -/// `vec!` allows `Vec`s to be defined with the same syntax as array expressions. -/// There are two forms of this macro: -/// -/// - Create a [`Vec`] containing a given list of elements: -/// -/// ``` -/// let v = vec![1, 2, 3]; -/// assert_eq!(v[0], 1); -/// assert_eq!(v[1], 2); -/// assert_eq!(v[2], 3); -/// ``` -/// -/// - Create a [`Vec`] from a given element and size: -/// -/// ``` -/// let v = vec![1; 3]; -/// assert_eq!(v, [1, 1, 1]); -/// ``` -/// -/// Note that unlike array expressions this syntax supports all elements -/// which implement [`Clone`] and the number of elements doesn't have to be -/// a constant. -/// -/// This will use `clone` to duplicate an expression, so one should be careful -/// using this with types having a nonstandard `Clone` implementation. For -/// example, `vec![Rc::new(1); 5]` will create a vector of five references -/// to the same boxed integer value, not five references pointing to independently -/// boxed integers. -/// -/// Also, note that `vec![expr; 0]` is allowed, and produces an empty vector. -/// This will still evaluate `expr`, however, and immediately drop the resulting value, so -/// be mindful of side effects. -/// -/// [`Vec`]: crate::vec::Vec -#[cfg(all(not(no_global_oom_handling), not(test)))] -#[macro_export] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_diagnostic_item = "vec_macro"] -#[allow_internal_unstable(rustc_attrs, liballoc_internals)] -macro_rules! vec { - () => ( - $crate::__rust_force_expr!($crate::vec::Vec::new()) - ); - ($elem:expr; $n:expr) => ( - $crate::__rust_force_expr!($crate::vec::from_elem($elem, $n)) - ); - ($($x:expr),+ $(,)?) => ( - $crate::__rust_force_expr!(<[_]>::into_vec( - // This rustc_box is not required, but it produces a dramatic improvement in compile - // time when constructing arrays with many elements. - #[rustc_box] - $crate::boxed::Box::new([$($x),+]) - )) - ); -} - -// HACK(japaric): with cfg(test) the inherent `[T]::into_vec` method, which is -// required for this macro definition, is not available. Instead use the -// `slice::into_vec` function which is only available with cfg(test) -// NB see the slice::hack module in slice.rs for more information -#[cfg(all(not(no_global_oom_handling), test))] -#[allow(unused_macro_rules)] -macro_rules! vec { - () => ( - $crate::vec::Vec::new() - ); - ($elem:expr; $n:expr) => ( - $crate::vec::from_elem($elem, $n) - ); - ($($x:expr),*) => ( - $crate::slice::into_vec($crate::boxed::Box::new([$($x),*])) - ); - ($($x:expr,)*) => (vec![$($x),*]) -} - -/// Creates a `String` using interpolation of runtime expressions. -/// -/// The first argument `format!` receives is a format string. This must be a string -/// literal. The power of the formatting string is in the `{}`s contained. -/// Additional parameters passed to `format!` replace the `{}`s within the -/// formatting string in the order given unless named or positional parameters -/// are used. -/// -/// See [the formatting syntax documentation in `std::fmt`](../std/fmt/index.html) -/// for details. -/// -/// A common use for `format!` is concatenation and interpolation of strings. -/// The same convention is used with [`print!`] and [`write!`] macros, -/// depending on the intended destination of the string; all these macros internally use [`format_args!`]. -/// -/// To convert a single value to a string, use the [`to_string`] method. This -/// will use the [`Display`] formatting trait. -/// -/// To concatenate literals into a `&'static str`, use the [`concat!`] macro. -/// -/// [`print!`]: ../std/macro.print.html -/// [`write!`]: core::write -/// [`format_args!`]: core::format_args -/// [`to_string`]: crate::string::ToString -/// [`Display`]: core::fmt::Display -/// [`concat!`]: core::concat -/// -/// # Panics -/// -/// `format!` panics if a formatting trait implementation returns an error. -/// This indicates an incorrect implementation -/// since `fmt::Write for String` never returns an error itself. -/// -/// # Examples -/// -/// ``` -/// format!("test"); // => "test" -/// format!("hello {}", "world!"); // => "hello world!" -/// format!("x = {}, y = {val}", 10, val = 30); // => "x = 10, y = 30" -/// let (x, y) = (1, 2); -/// format!("{x} + {y} = 3"); // => "1 + 2 = 3" -/// ``` -#[macro_export] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "format_macro")] -macro_rules! format { - ($($arg:tt)*) => {{ - let res = $crate::fmt::format($crate::__export::format_args!($($arg)*)); - res - }} -} - -/// Force AST node to an expression to improve diagnostics in pattern position. -#[doc(hidden)] -#[macro_export] -#[unstable(feature = "liballoc_internals", issue = "none", reason = "implementation detail")] -macro_rules! __rust_force_expr { - ($e:expr) => { - $e - }; -} diff --git a/library/alloc/src/raw_vec.rs b/library/alloc/src/raw_vec.rs deleted file mode 100644 index 1134c7f833e2b..0000000000000 --- a/library/alloc/src/raw_vec.rs +++ /dev/null @@ -1,613 +0,0 @@ -#![unstable(feature = "raw_vec_internals", reason = "unstable const warnings", issue = "none")] - -use core::alloc::LayoutError; -use core::cmp; -use core::hint; -use core::mem::{self, ManuallyDrop, MaybeUninit, SizedTypeProperties}; -use core::ptr::{self, NonNull, Unique}; - -#[cfg(not(no_global_oom_handling))] -use crate::alloc::handle_alloc_error; -use crate::alloc::{Allocator, Global, Layout}; -use crate::boxed::Box; -use crate::collections::TryReserveError; -use crate::collections::TryReserveErrorKind::*; - -#[cfg(test)] -mod tests; - -// One central function responsible for reporting capacity overflows. This'll -// ensure that the code generation related to these panics is minimal as there's -// only one location which panics rather than a bunch throughout the module. -#[cfg(not(no_global_oom_handling))] -#[cfg_attr(not(feature = "panic_immediate_abort"), inline(never))] -fn capacity_overflow() -> ! { - panic!("capacity overflow"); -} - -enum AllocInit { - /// The contents of the new memory are uninitialized. - Uninitialized, - #[cfg(not(no_global_oom_handling))] - /// The new memory is guaranteed to be zeroed. - Zeroed, -} - -#[repr(transparent)] -#[cfg_attr(target_pointer_width = "16", rustc_layout_scalar_valid_range_end(0x7fff))] -#[cfg_attr(target_pointer_width = "32", rustc_layout_scalar_valid_range_end(0x7fff_ffff))] -#[cfg_attr(target_pointer_width = "64", rustc_layout_scalar_valid_range_end(0x7fff_ffff_ffff_ffff))] -struct Cap(usize); - -impl Cap { - const ZERO: Cap = unsafe { Cap(0) }; -} - -/// A low-level utility for more ergonomically allocating, reallocating, and deallocating -/// a buffer of memory on the heap without having to worry about all the corner cases -/// involved. This type is excellent for building your own data structures like Vec and VecDeque. -/// In particular: -/// -/// * Produces `Unique::dangling()` on zero-sized types. -/// * Produces `Unique::dangling()` on zero-length allocations. -/// * Avoids freeing `Unique::dangling()`. -/// * Catches all overflows in capacity computations (promotes them to "capacity overflow" panics). -/// * Guards against 32-bit systems allocating more than isize::MAX bytes. -/// * Guards against overflowing your length. -/// * Calls `handle_alloc_error` for fallible allocations. -/// * Contains a `ptr::Unique` and thus endows the user with all related benefits. -/// * Uses the excess returned from the allocator to use the largest available capacity. -/// -/// This type does not in anyway inspect the memory that it manages. When dropped it *will* -/// free its memory, but it *won't* try to drop its contents. It is up to the user of `RawVec` -/// to handle the actual things *stored* inside of a `RawVec`. -/// -/// Note that the excess of a zero-sized types is always infinite, so `capacity()` always returns -/// `usize::MAX`. This means that you need to be careful when round-tripping this type with a -/// `Box<[T]>`, since `capacity()` won't yield the length. -#[allow(missing_debug_implementations)] -pub(crate) struct RawVec { - ptr: Unique, - /// Never used for ZSTs; it's `capacity()`'s responsibility to return usize::MAX in that case. - /// - /// # Safety - /// - /// `cap` must be in the `0..=isize::MAX` range. - cap: Cap, - alloc: A, -} - -impl RawVec { - /// HACK(Centril): This exists because stable `const fn` can only call stable `const fn`, so - /// they cannot call `Self::new()`. - /// - /// If you change `RawVec::new` or dependencies, please take care to not introduce anything - /// that would truly const-call something unstable. - pub const NEW: Self = Self::new(); - - /// Creates the biggest possible `RawVec` (on the system heap) - /// without allocating. If `T` has positive size, then this makes a - /// `RawVec` with capacity `0`. If `T` is zero-sized, then it makes a - /// `RawVec` with capacity `usize::MAX`. Useful for implementing - /// delayed allocation. - #[must_use] - pub const fn new() -> Self { - Self::new_in(Global) - } - - /// Creates a `RawVec` (on the system heap) with exactly the - /// capacity and alignment requirements for a `[T; capacity]`. This is - /// equivalent to calling `RawVec::new` when `capacity` is `0` or `T` is - /// zero-sized. Note that if `T` is zero-sized this means you will - /// *not* get a `RawVec` with the requested capacity. - /// - /// Non-fallible version of `try_with_capacity` - /// - /// # Panics - /// - /// Panics if the requested capacity exceeds `isize::MAX` bytes. - /// - /// # Aborts - /// - /// Aborts on OOM. - #[cfg(not(any(no_global_oom_handling, test)))] - #[must_use] - #[inline] - pub fn with_capacity(capacity: usize) -> Self { - match Self::try_allocate_in(capacity, AllocInit::Uninitialized, Global) { - Ok(res) => res, - Err(err) => handle_error(err), - } - } - - /// Like `with_capacity`, but guarantees the buffer is zeroed. - #[cfg(not(any(no_global_oom_handling, test)))] - #[must_use] - #[inline] - pub fn with_capacity_zeroed(capacity: usize) -> Self { - Self::with_capacity_zeroed_in(capacity, Global) - } -} - -impl RawVec { - // Tiny Vecs are dumb. Skip to: - // - 8 if the element size is 1, because any heap allocators is likely - // to round up a request of less than 8 bytes to at least 8 bytes. - // - 4 if elements are moderate-sized (<= 1 KiB). - // - 1 otherwise, to avoid wasting too much space for very short Vecs. - pub(crate) const MIN_NON_ZERO_CAP: usize = if mem::size_of::() == 1 { - 8 - } else if mem::size_of::() <= 1024 { - 4 - } else { - 1 - }; - - /// Like `new`, but parameterized over the choice of allocator for - /// the returned `RawVec`. - pub const fn new_in(alloc: A) -> Self { - // `cap: 0` means "unallocated". zero-sized types are ignored. - Self { ptr: Unique::dangling(), cap: Cap::ZERO, alloc } - } - - /// Like `with_capacity`, but parameterized over the choice of - /// allocator for the returned `RawVec`. - #[cfg(not(no_global_oom_handling))] - #[inline] - pub fn with_capacity_in(capacity: usize, alloc: A) -> Self { - match Self::try_allocate_in(capacity, AllocInit::Uninitialized, alloc) { - Ok(res) => res, - Err(err) => handle_error(err), - } - } - - /// Like `try_with_capacity`, but parameterized over the choice of - /// allocator for the returned `RawVec`. - #[inline] - pub fn try_with_capacity_in(capacity: usize, alloc: A) -> Result { - Self::try_allocate_in(capacity, AllocInit::Uninitialized, alloc) - } - - /// Like `with_capacity_zeroed`, but parameterized over the choice - /// of allocator for the returned `RawVec`. - #[cfg(not(no_global_oom_handling))] - #[inline] - pub fn with_capacity_zeroed_in(capacity: usize, alloc: A) -> Self { - match Self::try_allocate_in(capacity, AllocInit::Zeroed, alloc) { - Ok(res) => res, - Err(err) => handle_error(err), - } - } - - /// Converts the entire buffer into `Box<[MaybeUninit]>` with the specified `len`. - /// - /// Note that this will correctly reconstitute any `cap` changes - /// that may have been performed. (See description of type for details.) - /// - /// # Safety - /// - /// * `len` must be greater than or equal to the most recently requested capacity, and - /// * `len` must be less than or equal to `self.capacity()`. - /// - /// Note, that the requested capacity and `self.capacity()` could differ, as - /// an allocator could overallocate and return a greater memory block than requested. - pub unsafe fn into_box(self, len: usize) -> Box<[MaybeUninit], A> { - // Sanity-check one half of the safety requirement (we cannot check the other half). - debug_assert!( - len <= self.capacity(), - "`len` must be smaller than or equal to `self.capacity()`" - ); - - let me = ManuallyDrop::new(self); - unsafe { - let slice = ptr::slice_from_raw_parts_mut(me.ptr() as *mut MaybeUninit, len); - Box::from_raw_in(slice, ptr::read(&me.alloc)) - } - } - - fn try_allocate_in( - capacity: usize, - init: AllocInit, - alloc: A, - ) -> Result { - // Don't allocate here because `Drop` will not deallocate when `capacity` is 0. - - if T::IS_ZST || capacity == 0 { - Ok(Self::new_in(alloc)) - } else { - // We avoid `unwrap_or_else` here because it bloats the amount of - // LLVM IR generated. - let layout = match Layout::array::(capacity) { - Ok(layout) => layout, - Err(_) => return Err(CapacityOverflow.into()), - }; - - if let Err(err) = alloc_guard(layout.size()) { - return Err(err); - } - - let result = match init { - AllocInit::Uninitialized => alloc.allocate(layout), - #[cfg(not(no_global_oom_handling))] - AllocInit::Zeroed => alloc.allocate_zeroed(layout), - }; - let ptr = match result { - Ok(ptr) => ptr, - Err(_) => return Err(AllocError { layout, non_exhaustive: () }.into()), - }; - - // Allocators currently return a `NonNull<[u8]>` whose length - // matches the size requested. If that ever changes, the capacity - // here should change to `ptr.len() / mem::size_of::()`. - Ok(Self { ptr: Unique::from(ptr.cast()), cap: unsafe { Cap(capacity) }, alloc }) - } - } - - /// Reconstitutes a `RawVec` from a pointer, capacity, and allocator. - /// - /// # Safety - /// - /// The `ptr` must be allocated (via the given allocator `alloc`), and with the given - /// `capacity`. - /// The `capacity` cannot exceed `isize::MAX` for sized types. (only a concern on 32-bit - /// systems). For ZSTs capacity is ignored. - /// If the `ptr` and `capacity` come from a `RawVec` created via `alloc`, then this is - /// guaranteed. - #[inline] - pub unsafe fn from_raw_parts_in(ptr: *mut T, capacity: usize, alloc: A) -> Self { - let cap = if T::IS_ZST { Cap::ZERO } else { unsafe { Cap(capacity) } }; - Self { ptr: unsafe { Unique::new_unchecked(ptr) }, cap, alloc } - } - - /// A convenience method for hoisting the non-null precondition out of [`RawVec::from_raw_parts_in`]. - /// - /// # Safety - /// - /// See [`RawVec::from_raw_parts_in`]. - #[inline] - pub(crate) unsafe fn from_nonnull_in(ptr: NonNull, capacity: usize, alloc: A) -> Self { - let cap = if T::IS_ZST { Cap::ZERO } else { unsafe { Cap(capacity) } }; - Self { ptr: Unique::from(ptr), cap, alloc } - } - - /// Gets a raw pointer to the start of the allocation. Note that this is - /// `Unique::dangling()` if `capacity == 0` or `T` is zero-sized. In the former case, you must - /// be careful. - #[inline] - pub fn ptr(&self) -> *mut T { - self.ptr.as_ptr() - } - - #[inline] - pub fn non_null(&self) -> NonNull { - NonNull::from(self.ptr) - } - - /// Gets the capacity of the allocation. - /// - /// This will always be `usize::MAX` if `T` is zero-sized. - #[inline(always)] - pub fn capacity(&self) -> usize { - if T::IS_ZST { usize::MAX } else { self.cap.0 } - } - - /// Returns a shared reference to the allocator backing this `RawVec`. - pub fn allocator(&self) -> &A { - &self.alloc - } - - fn current_memory(&self) -> Option<(NonNull, Layout)> { - if T::IS_ZST || self.cap.0 == 0 { - None - } else { - // We could use Layout::array here which ensures the absence of isize and usize overflows - // and could hypothetically handle differences between stride and size, but this memory - // has already been allocated so we know it can't overflow and currently Rust does not - // support such types. So we can do better by skipping some checks and avoid an unwrap. - const { assert!(mem::size_of::() % mem::align_of::() == 0) }; - unsafe { - let align = mem::align_of::(); - let size = mem::size_of::().unchecked_mul(self.cap.0); - let layout = Layout::from_size_align_unchecked(size, align); - Some((self.ptr.cast().into(), layout)) - } - } - } - - /// Ensures that the buffer contains at least enough space to hold `len + - /// additional` elements. If it doesn't already have enough capacity, will - /// reallocate enough space plus comfortable slack space to get amortized - /// *O*(1) behavior. Will limit this behavior if it would needlessly cause - /// itself to panic. - /// - /// If `len` exceeds `self.capacity()`, this may fail to actually allocate - /// the requested space. This is not really unsafe, but the unsafe - /// code *you* write that relies on the behavior of this function may break. - /// - /// This is ideal for implementing a bulk-push operation like `extend`. - /// - /// # Panics - /// - /// Panics if the new capacity exceeds `isize::MAX` _bytes_. - /// - /// # Aborts - /// - /// Aborts on OOM. - #[cfg(not(no_global_oom_handling))] - #[inline] - pub fn reserve(&mut self, len: usize, additional: usize) { - // Callers expect this function to be very cheap when there is already sufficient capacity. - // Therefore, we move all the resizing and error-handling logic from grow_amortized and - // handle_reserve behind a call, while making sure that this function is likely to be - // inlined as just a comparison and a call if the comparison fails. - #[cold] - fn do_reserve_and_handle( - slf: &mut RawVec, - len: usize, - additional: usize, - ) { - if let Err(err) = slf.grow_amortized(len, additional) { - handle_error(err); - } - } - - if self.needs_to_grow(len, additional) { - do_reserve_and_handle(self, len, additional); - } - } - - /// A specialized version of `self.reserve(len, 1)` which requires the - /// caller to ensure `len == self.capacity()`. - #[cfg(not(no_global_oom_handling))] - #[inline(never)] - pub fn grow_one(&mut self) { - if let Err(err) = self.grow_amortized(self.cap.0, 1) { - handle_error(err); - } - } - - /// The same as `reserve`, but returns on errors instead of panicking or aborting. - pub fn try_reserve(&mut self, len: usize, additional: usize) -> Result<(), TryReserveError> { - if self.needs_to_grow(len, additional) { - self.grow_amortized(len, additional)?; - } - unsafe { - // Inform the optimizer that the reservation has succeeded or wasn't needed - hint::assert_unchecked(!self.needs_to_grow(len, additional)); - } - Ok(()) - } - - /// Ensures that the buffer contains at least enough space to hold `len + - /// additional` elements. If it doesn't already, will reallocate the - /// minimum possible amount of memory necessary. Generally this will be - /// exactly the amount of memory necessary, but in principle the allocator - /// is free to give back more than we asked for. - /// - /// If `len` exceeds `self.capacity()`, this may fail to actually allocate - /// the requested space. This is not really unsafe, but the unsafe code - /// *you* write that relies on the behavior of this function may break. - /// - /// # Panics - /// - /// Panics if the new capacity exceeds `isize::MAX` _bytes_. - /// - /// # Aborts - /// - /// Aborts on OOM. - #[cfg(not(no_global_oom_handling))] - pub fn reserve_exact(&mut self, len: usize, additional: usize) { - if let Err(err) = self.try_reserve_exact(len, additional) { - handle_error(err); - } - } - - /// The same as `reserve_exact`, but returns on errors instead of panicking or aborting. - pub fn try_reserve_exact( - &mut self, - len: usize, - additional: usize, - ) -> Result<(), TryReserveError> { - if self.needs_to_grow(len, additional) { - self.grow_exact(len, additional)?; - } - unsafe { - // Inform the optimizer that the reservation has succeeded or wasn't needed - hint::assert_unchecked(!self.needs_to_grow(len, additional)); - } - Ok(()) - } - - /// Shrinks the buffer down to the specified capacity. If the given amount - /// is 0, actually completely deallocates. - /// - /// # Panics - /// - /// Panics if the given amount is *larger* than the current capacity. - /// - /// # Aborts - /// - /// Aborts on OOM. - #[cfg(not(no_global_oom_handling))] - pub fn shrink_to_fit(&mut self, cap: usize) { - if let Err(err) = self.shrink(cap) { - handle_error(err); - } - } -} - -impl RawVec { - /// Returns if the buffer needs to grow to fulfill the needed extra capacity. - /// Mainly used to make inlining reserve-calls possible without inlining `grow`. - fn needs_to_grow(&self, len: usize, additional: usize) -> bool { - additional > self.capacity().wrapping_sub(len) - } - - /// # Safety: - /// - /// `cap` must not exceed `isize::MAX`. - unsafe fn set_ptr_and_cap(&mut self, ptr: NonNull<[u8]>, cap: usize) { - // Allocators currently return a `NonNull<[u8]>` whose length matches - // the size requested. If that ever changes, the capacity here should - // change to `ptr.len() / mem::size_of::()`. - self.ptr = Unique::from(ptr.cast()); - self.cap = unsafe { Cap(cap) }; - } - - // This method is usually instantiated many times. So we want it to be as - // small as possible, to improve compile times. But we also want as much of - // its contents to be statically computable as possible, to make the - // generated code run faster. Therefore, this method is carefully written - // so that all of the code that depends on `T` is within it, while as much - // of the code that doesn't depend on `T` as possible is in functions that - // are non-generic over `T`. - fn grow_amortized(&mut self, len: usize, additional: usize) -> Result<(), TryReserveError> { - // This is ensured by the calling contexts. - debug_assert!(additional > 0); - - if T::IS_ZST { - // Since we return a capacity of `usize::MAX` when `elem_size` is - // 0, getting to here necessarily means the `RawVec` is overfull. - return Err(CapacityOverflow.into()); - } - - // Nothing we can really do about these checks, sadly. - let required_cap = len.checked_add(additional).ok_or(CapacityOverflow)?; - - // This guarantees exponential growth. The doubling cannot overflow - // because `cap <= isize::MAX` and the type of `cap` is `usize`. - let cap = cmp::max(self.cap.0 * 2, required_cap); - let cap = cmp::max(Self::MIN_NON_ZERO_CAP, cap); - - let new_layout = Layout::array::(cap); - - // `finish_grow` is non-generic over `T`. - let ptr = finish_grow(new_layout, self.current_memory(), &mut self.alloc)?; - // SAFETY: finish_grow would have resulted in a capacity overflow if we tried to allocate more than isize::MAX items - unsafe { self.set_ptr_and_cap(ptr, cap) }; - Ok(()) - } - - // The constraints on this method are much the same as those on - // `grow_amortized`, but this method is usually instantiated less often so - // it's less critical. - fn grow_exact(&mut self, len: usize, additional: usize) -> Result<(), TryReserveError> { - if T::IS_ZST { - // Since we return a capacity of `usize::MAX` when the type size is - // 0, getting to here necessarily means the `RawVec` is overfull. - return Err(CapacityOverflow.into()); - } - - let cap = len.checked_add(additional).ok_or(CapacityOverflow)?; - let new_layout = Layout::array::(cap); - - // `finish_grow` is non-generic over `T`. - let ptr = finish_grow(new_layout, self.current_memory(), &mut self.alloc)?; - // SAFETY: finish_grow would have resulted in a capacity overflow if we tried to allocate more than isize::MAX items - unsafe { - self.set_ptr_and_cap(ptr, cap); - } - Ok(()) - } - - #[cfg(not(no_global_oom_handling))] - fn shrink(&mut self, cap: usize) -> Result<(), TryReserveError> { - assert!(cap <= self.capacity(), "Tried to shrink to a larger capacity"); - - let (ptr, layout) = if let Some(mem) = self.current_memory() { mem } else { return Ok(()) }; - // See current_memory() why this assert is here - const { assert!(mem::size_of::() % mem::align_of::() == 0) }; - - // If shrinking to 0, deallocate the buffer. We don't reach this point - // for the T::IS_ZST case since current_memory() will have returned - // None. - if cap == 0 { - unsafe { self.alloc.deallocate(ptr, layout) }; - self.ptr = Unique::dangling(); - self.cap = Cap::ZERO; - } else { - let ptr = unsafe { - // `Layout::array` cannot overflow here because it would have - // overflowed earlier when capacity was larger. - let new_size = mem::size_of::().unchecked_mul(cap); - let new_layout = Layout::from_size_align_unchecked(new_size, layout.align()); - self.alloc - .shrink(ptr, layout, new_layout) - .map_err(|_| AllocError { layout: new_layout, non_exhaustive: () })? - }; - // SAFETY: if the allocation is valid, then the capacity is too - unsafe { - self.set_ptr_and_cap(ptr, cap); - } - } - Ok(()) - } -} - -// This function is outside `RawVec` to minimize compile times. See the comment -// above `RawVec::grow_amortized` for details. (The `A` parameter isn't -// significant, because the number of different `A` types seen in practice is -// much smaller than the number of `T` types.) -#[inline(never)] -fn finish_grow( - new_layout: Result, - current_memory: Option<(NonNull, Layout)>, - alloc: &mut A, -) -> Result, TryReserveError> -where - A: Allocator, -{ - // Check for the error here to minimize the size of `RawVec::grow_*`. - let new_layout = new_layout.map_err(|_| CapacityOverflow)?; - - alloc_guard(new_layout.size())?; - - let memory = if let Some((ptr, old_layout)) = current_memory { - debug_assert_eq!(old_layout.align(), new_layout.align()); - unsafe { - // The allocator checks for alignment equality - hint::assert_unchecked(old_layout.align() == new_layout.align()); - alloc.grow(ptr, old_layout, new_layout) - } - } else { - alloc.allocate(new_layout) - }; - - memory.map_err(|_| AllocError { layout: new_layout, non_exhaustive: () }.into()) -} - -unsafe impl<#[may_dangle] T, A: Allocator> Drop for RawVec { - /// Frees the memory owned by the `RawVec` *without* trying to drop its contents. - fn drop(&mut self) { - if let Some((ptr, layout)) = self.current_memory() { - unsafe { self.alloc.deallocate(ptr, layout) } - } - } -} - -// Central function for reserve error handling. -#[cfg(not(no_global_oom_handling))] -#[cold] -fn handle_error(e: TryReserveError) -> ! { - match e.kind() { - CapacityOverflow => capacity_overflow(), - AllocError { layout, .. } => handle_alloc_error(layout), - } -} - -// We need to guarantee the following: -// * We don't ever allocate `> isize::MAX` byte-size objects. -// * We don't overflow `usize::MAX` and actually allocate too little. -// -// On 64-bit we just need to check for overflow since trying to allocate -// `> isize::MAX` bytes will surely fail. On 32-bit and 16-bit we need to add -// an extra guard for this in case we're running on a platform which can use -// all 4GB in user-space, e.g., PAE or x32. -#[inline] -fn alloc_guard(alloc_size: usize) -> Result<(), TryReserveError> { - if usize::BITS < 64 && alloc_size > isize::MAX as usize { - Err(CapacityOverflow.into()) - } else { - Ok(()) - } -} diff --git a/library/alloc/src/raw_vec/tests.rs b/library/alloc/src/raw_vec/tests.rs deleted file mode 100644 index 4194be530612d..0000000000000 --- a/library/alloc/src/raw_vec/tests.rs +++ /dev/null @@ -1,173 +0,0 @@ -use super::*; -use core::mem::size_of; -use std::cell::Cell; - -#[test] -fn allocator_param() { - use crate::alloc::AllocError; - - // Writing a test of integration between third-party - // allocators and `RawVec` is a little tricky because the `RawVec` - // API does not expose fallible allocation methods, so we - // cannot check what happens when allocator is exhausted - // (beyond detecting a panic). - // - // Instead, this just checks that the `RawVec` methods do at - // least go through the Allocator API when it reserves - // storage. - - // A dumb allocator that consumes a fixed amount of fuel - // before allocation attempts start failing. - struct BoundedAlloc { - fuel: Cell, - } - unsafe impl Allocator for BoundedAlloc { - fn allocate(&self, layout: Layout) -> Result, AllocError> { - let size = layout.size(); - if size > self.fuel.get() { - return Err(AllocError); - } - match Global.allocate(layout) { - ok @ Ok(_) => { - self.fuel.set(self.fuel.get() - size); - ok - } - err @ Err(_) => err, - } - } - unsafe fn deallocate(&self, ptr: NonNull, layout: Layout) { - unsafe { Global.deallocate(ptr, layout) } - } - } - - let a = BoundedAlloc { fuel: Cell::new(500) }; - let mut v: RawVec = RawVec::with_capacity_in(50, a); - assert_eq!(v.alloc.fuel.get(), 450); - v.reserve(50, 150); // (causes a realloc, thus using 50 + 150 = 200 units of fuel) - assert_eq!(v.alloc.fuel.get(), 250); -} - -#[test] -fn reserve_does_not_overallocate() { - { - let mut v: RawVec = RawVec::new(); - // First, `reserve` allocates like `reserve_exact`. - v.reserve(0, 9); - assert_eq!(9, v.capacity()); - } - - { - let mut v: RawVec = RawVec::new(); - v.reserve(0, 7); - assert_eq!(7, v.capacity()); - // 97 is more than double of 7, so `reserve` should work - // like `reserve_exact`. - v.reserve(7, 90); - assert_eq!(97, v.capacity()); - } - - { - let mut v: RawVec = RawVec::new(); - v.reserve(0, 12); - assert_eq!(12, v.capacity()); - v.reserve(12, 3); - // 3 is less than half of 12, so `reserve` must grow - // exponentially. At the time of writing this test grow - // factor is 2, so new capacity is 24, however, grow factor - // of 1.5 is OK too. Hence `>= 18` in assert. - assert!(v.capacity() >= 12 + 12 / 2); - } -} - -struct ZST; - -// A `RawVec` holding zero-sized elements should always look like this. -fn zst_sanity(v: &RawVec) { - assert_eq!(v.capacity(), usize::MAX); - assert_eq!(v.ptr(), core::ptr::Unique::::dangling().as_ptr()); - assert_eq!(v.current_memory(), None); -} - -#[test] -fn zst() { - let cap_err = Err(crate::collections::TryReserveErrorKind::CapacityOverflow.into()); - - assert_eq!(std::mem::size_of::(), 0); - - // All these different ways of creating the RawVec produce the same thing. - - let v: RawVec = RawVec::new(); - zst_sanity(&v); - - let v: RawVec = RawVec::with_capacity_in(100, Global); - zst_sanity(&v); - - let v: RawVec = RawVec::with_capacity_in(100, Global); - zst_sanity(&v); - - let v: RawVec = RawVec::try_allocate_in(0, AllocInit::Uninitialized, Global).unwrap(); - zst_sanity(&v); - - let v: RawVec = RawVec::try_allocate_in(100, AllocInit::Uninitialized, Global).unwrap(); - zst_sanity(&v); - - let mut v: RawVec = - RawVec::try_allocate_in(usize::MAX, AllocInit::Uninitialized, Global).unwrap(); - zst_sanity(&v); - - // Check all these operations work as expected with zero-sized elements. - - assert!(!v.needs_to_grow(100, usize::MAX - 100)); - assert!(v.needs_to_grow(101, usize::MAX - 100)); - zst_sanity(&v); - - v.reserve(100, usize::MAX - 100); - //v.reserve(101, usize::MAX - 100); // panics, in `zst_reserve_panic` below - zst_sanity(&v); - - v.reserve_exact(100, usize::MAX - 100); - //v.reserve_exact(101, usize::MAX - 100); // panics, in `zst_reserve_exact_panic` below - zst_sanity(&v); - - assert_eq!(v.try_reserve(100, usize::MAX - 100), Ok(())); - assert_eq!(v.try_reserve(101, usize::MAX - 100), cap_err); - zst_sanity(&v); - - assert_eq!(v.try_reserve_exact(100, usize::MAX - 100), Ok(())); - assert_eq!(v.try_reserve_exact(101, usize::MAX - 100), cap_err); - zst_sanity(&v); - - assert_eq!(v.grow_amortized(100, usize::MAX - 100), cap_err); - assert_eq!(v.grow_amortized(101, usize::MAX - 100), cap_err); - zst_sanity(&v); - - assert_eq!(v.grow_exact(100, usize::MAX - 100), cap_err); - assert_eq!(v.grow_exact(101, usize::MAX - 100), cap_err); - zst_sanity(&v); -} - -#[test] -#[should_panic(expected = "capacity overflow")] -fn zst_reserve_panic() { - let mut v: RawVec = RawVec::new(); - zst_sanity(&v); - - v.reserve(101, usize::MAX - 100); -} - -#[test] -#[should_panic(expected = "capacity overflow")] -fn zst_reserve_exact_panic() { - let mut v: RawVec = RawVec::new(); - zst_sanity(&v); - - v.reserve_exact(101, usize::MAX - 100); -} - -#[test] -fn niches() { - let baseline = size_of::>(); - assert_eq!(size_of::>>(), baseline); - assert_eq!(size_of::>>>(), baseline); - assert_eq!(size_of::>>>>(), baseline); -} diff --git a/library/alloc/src/rc.rs b/library/alloc/src/rc.rs deleted file mode 100644 index 875c24c28e4a9..0000000000000 --- a/library/alloc/src/rc.rs +++ /dev/null @@ -1,3655 +0,0 @@ -//! Single-threaded reference-counting pointers. 'Rc' stands for 'Reference -//! Counted'. -//! -//! The type [`Rc`][`Rc`] provides shared ownership of a value of type `T`, -//! allocated in the heap. Invoking [`clone`][clone] on [`Rc`] produces a new -//! pointer to the same allocation in the heap. When the last [`Rc`] pointer to a -//! given allocation is destroyed, the value stored in that allocation (often -//! referred to as "inner value") is also dropped. -//! -//! Shared references in Rust disallow mutation by default, and [`Rc`] -//! is no exception: you cannot generally obtain a mutable reference to -//! something inside an [`Rc`]. If you need mutability, put a [`Cell`] -//! or [`RefCell`] inside the [`Rc`]; see [an example of mutability -//! inside an `Rc`][mutability]. -//! -//! [`Rc`] uses non-atomic reference counting. This means that overhead is very -//! low, but an [`Rc`] cannot be sent between threads, and consequently [`Rc`] -//! does not implement [`Send`]. As a result, the Rust compiler -//! will check *at compile time* that you are not sending [`Rc`]s between -//! threads. If you need multi-threaded, atomic reference counting, use -//! [`sync::Arc`][arc]. -//! -//! The [`downgrade`][downgrade] method can be used to create a non-owning -//! [`Weak`] pointer. A [`Weak`] pointer can be [`upgrade`][upgrade]d -//! to an [`Rc`], but this will return [`None`] if the value stored in the allocation has -//! already been dropped. In other words, `Weak` pointers do not keep the value -//! inside the allocation alive; however, they *do* keep the allocation -//! (the backing store for the inner value) alive. -//! -//! A cycle between [`Rc`] pointers will never be deallocated. For this reason, -//! [`Weak`] is used to break cycles. For example, a tree could have strong -//! [`Rc`] pointers from parent nodes to children, and [`Weak`] pointers from -//! children back to their parents. -//! -//! `Rc` automatically dereferences to `T` (via the [`Deref`] trait), -//! so you can call `T`'s methods on a value of type [`Rc`][`Rc`]. To avoid name -//! clashes with `T`'s methods, the methods of [`Rc`][`Rc`] itself are associated -//! functions, called using [fully qualified syntax]: -//! -//! ``` -//! use std::rc::Rc; -//! -//! let my_rc = Rc::new(()); -//! let my_weak = Rc::downgrade(&my_rc); -//! ``` -//! -//! `Rc`'s implementations of traits like `Clone` may also be called using -//! fully qualified syntax. Some people prefer to use fully qualified syntax, -//! while others prefer using method-call syntax. -//! -//! ``` -//! use std::rc::Rc; -//! -//! let rc = Rc::new(()); -//! // Method-call syntax -//! let rc2 = rc.clone(); -//! // Fully qualified syntax -//! let rc3 = Rc::clone(&rc); -//! ``` -//! -//! [`Weak`][`Weak`] does not auto-dereference to `T`, because the inner value may have -//! already been dropped. -//! -//! # Cloning references -//! -//! Creating a new reference to the same allocation as an existing reference counted pointer -//! is done using the `Clone` trait implemented for [`Rc`][`Rc`] and [`Weak`][`Weak`]. -//! -//! ``` -//! use std::rc::Rc; -//! -//! let foo = Rc::new(vec![1.0, 2.0, 3.0]); -//! // The two syntaxes below are equivalent. -//! let a = foo.clone(); -//! let b = Rc::clone(&foo); -//! // a and b both point to the same memory location as foo. -//! ``` -//! -//! The `Rc::clone(&from)` syntax is the most idiomatic because it conveys more explicitly -//! the meaning of the code. In the example above, this syntax makes it easier to see that -//! this code is creating a new reference rather than copying the whole content of foo. -//! -//! # Examples -//! -//! Consider a scenario where a set of `Gadget`s are owned by a given `Owner`. -//! We want to have our `Gadget`s point to their `Owner`. We can't do this with -//! unique ownership, because more than one gadget may belong to the same -//! `Owner`. [`Rc`] allows us to share an `Owner` between multiple `Gadget`s, -//! and have the `Owner` remain allocated as long as any `Gadget` points at it. -//! -//! ``` -//! use std::rc::Rc; -//! -//! struct Owner { -//! name: String, -//! // ...other fields -//! } -//! -//! struct Gadget { -//! id: i32, -//! owner: Rc, -//! // ...other fields -//! } -//! -//! fn main() { -//! // Create a reference-counted `Owner`. -//! let gadget_owner: Rc = Rc::new( -//! Owner { -//! name: "Gadget Man".to_string(), -//! } -//! ); -//! -//! // Create `Gadget`s belonging to `gadget_owner`. Cloning the `Rc` -//! // gives us a new pointer to the same `Owner` allocation, incrementing -//! // the reference count in the process. -//! let gadget1 = Gadget { -//! id: 1, -//! owner: Rc::clone(&gadget_owner), -//! }; -//! let gadget2 = Gadget { -//! id: 2, -//! owner: Rc::clone(&gadget_owner), -//! }; -//! -//! // Dispose of our local variable `gadget_owner`. -//! drop(gadget_owner); -//! -//! // Despite dropping `gadget_owner`, we're still able to print out the name -//! // of the `Owner` of the `Gadget`s. This is because we've only dropped a -//! // single `Rc`, not the `Owner` it points to. As long as there are -//! // other `Rc` pointing at the same `Owner` allocation, it will remain -//! // live. The field projection `gadget1.owner.name` works because -//! // `Rc` automatically dereferences to `Owner`. -//! println!("Gadget {} owned by {}", gadget1.id, gadget1.owner.name); -//! println!("Gadget {} owned by {}", gadget2.id, gadget2.owner.name); -//! -//! // At the end of the function, `gadget1` and `gadget2` are destroyed, and -//! // with them the last counted references to our `Owner`. Gadget Man now -//! // gets destroyed as well. -//! } -//! ``` -//! -//! If our requirements change, and we also need to be able to traverse from -//! `Owner` to `Gadget`, we will run into problems. An [`Rc`] pointer from `Owner` -//! to `Gadget` introduces a cycle. This means that their -//! reference counts can never reach 0, and the allocation will never be destroyed: -//! a memory leak. In order to get around this, we can use [`Weak`] -//! pointers. -//! -//! Rust actually makes it somewhat difficult to produce this loop in the first -//! place. In order to end up with two values that point at each other, one of -//! them needs to be mutable. This is difficult because [`Rc`] enforces -//! memory safety by only giving out shared references to the value it wraps, -//! and these don't allow direct mutation. We need to wrap the part of the -//! value we wish to mutate in a [`RefCell`], which provides *interior -//! mutability*: a method to achieve mutability through a shared reference. -//! [`RefCell`] enforces Rust's borrowing rules at runtime. -//! -//! ``` -//! use std::rc::Rc; -//! use std::rc::Weak; -//! use std::cell::RefCell; -//! -//! struct Owner { -//! name: String, -//! gadgets: RefCell>>, -//! // ...other fields -//! } -//! -//! struct Gadget { -//! id: i32, -//! owner: Rc, -//! // ...other fields -//! } -//! -//! fn main() { -//! // Create a reference-counted `Owner`. Note that we've put the `Owner`'s -//! // vector of `Gadget`s inside a `RefCell` so that we can mutate it through -//! // a shared reference. -//! let gadget_owner: Rc = Rc::new( -//! Owner { -//! name: "Gadget Man".to_string(), -//! gadgets: RefCell::new(vec![]), -//! } -//! ); -//! -//! // Create `Gadget`s belonging to `gadget_owner`, as before. -//! let gadget1 = Rc::new( -//! Gadget { -//! id: 1, -//! owner: Rc::clone(&gadget_owner), -//! } -//! ); -//! let gadget2 = Rc::new( -//! Gadget { -//! id: 2, -//! owner: Rc::clone(&gadget_owner), -//! } -//! ); -//! -//! // Add the `Gadget`s to their `Owner`. -//! { -//! let mut gadgets = gadget_owner.gadgets.borrow_mut(); -//! gadgets.push(Rc::downgrade(&gadget1)); -//! gadgets.push(Rc::downgrade(&gadget2)); -//! -//! // `RefCell` dynamic borrow ends here. -//! } -//! -//! // Iterate over our `Gadget`s, printing their details out. -//! for gadget_weak in gadget_owner.gadgets.borrow().iter() { -//! -//! // `gadget_weak` is a `Weak`. Since `Weak` pointers can't -//! // guarantee the allocation still exists, we need to call -//! // `upgrade`, which returns an `Option>`. -//! // -//! // In this case we know the allocation still exists, so we simply -//! // `unwrap` the `Option`. In a more complicated program, you might -//! // need graceful error handling for a `None` result. -//! -//! let gadget = gadget_weak.upgrade().unwrap(); -//! println!("Gadget {} owned by {}", gadget.id, gadget.owner.name); -//! } -//! -//! // At the end of the function, `gadget_owner`, `gadget1`, and `gadget2` -//! // are destroyed. There are now no strong (`Rc`) pointers to the -//! // gadgets, so they are destroyed. This zeroes the reference count on -//! // Gadget Man, so he gets destroyed as well. -//! } -//! ``` -//! -//! [clone]: Clone::clone -//! [`Cell`]: core::cell::Cell -//! [`RefCell`]: core::cell::RefCell -//! [arc]: crate::sync::Arc -//! [`Deref`]: core::ops::Deref -//! [downgrade]: Rc::downgrade -//! [upgrade]: Weak::upgrade -//! [mutability]: core::cell#introducing-mutability-inside-of-something-immutable -//! [fully qualified syntax]: https://doc.rust-lang.org/book/ch19-03-advanced-traits.html#fully-qualified-syntax-for-disambiguation-calling-methods-with-the-same-name - -#![stable(feature = "rust1", since = "1.0.0")] - -#[cfg(not(test))] -use crate::boxed::Box; -#[cfg(test)] -use std::boxed::Box; - -use core::any::Any; -use core::borrow; -use core::cell::Cell; -use core::cmp::Ordering; -use core::fmt; -use core::hash::{Hash, Hasher}; -use core::hint; -use core::intrinsics::abort; -#[cfg(not(no_global_oom_handling))] -use core::iter; -use core::marker::{PhantomData, Unsize}; -#[cfg(not(no_global_oom_handling))] -use core::mem::size_of_val; -use core::mem::{self, align_of_val_raw, forget, ManuallyDrop}; -use core::ops::{CoerceUnsized, Deref, DerefMut, DerefPure, DispatchFromDyn, Receiver}; -use core::panic::{RefUnwindSafe, UnwindSafe}; -#[cfg(not(no_global_oom_handling))] -use core::pin::Pin; -use core::ptr::{self, drop_in_place, NonNull}; -#[cfg(not(no_global_oom_handling))] -use core::slice::from_raw_parts_mut; - -#[cfg(not(no_global_oom_handling))] -use crate::alloc::handle_alloc_error; -#[cfg(not(no_global_oom_handling))] -use crate::alloc::WriteCloneIntoRaw; -use crate::alloc::{AllocError, Allocator, Global, Layout}; -use crate::borrow::{Cow, ToOwned}; -#[cfg(not(no_global_oom_handling))] -use crate::string::String; -#[cfg(not(no_global_oom_handling))] -use crate::vec::Vec; - -#[cfg(test)] -mod tests; - -// This is repr(C) to future-proof against possible field-reordering, which -// would interfere with otherwise safe [into|from]_raw() of transmutable -// inner types. -#[repr(C)] -struct RcBox { - strong: Cell, - weak: Cell, - value: T, -} - -/// Calculate layout for `RcBox` using the inner value's layout -fn rcbox_layout_for_value_layout(layout: Layout) -> Layout { - // Calculate layout using the given value layout. - // Previously, layout was calculated on the expression - // `&*(ptr as *const RcBox)`, but this created a misaligned - // reference (see #54908). - Layout::new::>().extend(layout).unwrap().0.pad_to_align() -} - -/// A single-threaded reference-counting pointer. 'Rc' stands for 'Reference -/// Counted'. -/// -/// See the [module-level documentation](./index.html) for more details. -/// -/// The inherent methods of `Rc` are all associated functions, which means -/// that you have to call them as e.g., [`Rc::get_mut(&mut value)`][get_mut] instead of -/// `value.get_mut()`. This avoids conflicts with methods of the inner type `T`. -/// -/// [get_mut]: Rc::get_mut -#[cfg_attr(not(test), rustc_diagnostic_item = "Rc")] -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_insignificant_dtor] -pub struct Rc< - T: ?Sized, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, -> { - ptr: NonNull>, - phantom: PhantomData>, - alloc: A, -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl !Send for Rc {} - -// Note that this negative impl isn't strictly necessary for correctness, -// as `Rc` transitively contains a `Cell`, which is itself `!Sync`. -// However, given how important `Rc`'s `!Sync`-ness is, -// having an explicit negative impl is nice for documentation purposes -// and results in nicer error messages. -#[stable(feature = "rust1", since = "1.0.0")] -impl !Sync for Rc {} - -#[stable(feature = "catch_unwind", since = "1.9.0")] -impl UnwindSafe for Rc {} -#[stable(feature = "rc_ref_unwind_safe", since = "1.58.0")] -impl RefUnwindSafe for Rc {} - -#[unstable(feature = "coerce_unsized", issue = "18598")] -impl, U: ?Sized, A: Allocator> CoerceUnsized> for Rc {} - -#[unstable(feature = "dispatch_from_dyn", issue = "none")] -impl, U: ?Sized> DispatchFromDyn> for Rc {} - -impl Rc { - #[inline] - unsafe fn from_inner(ptr: NonNull>) -> Self { - unsafe { Self::from_inner_in(ptr, Global) } - } - - #[inline] - unsafe fn from_ptr(ptr: *mut RcBox) -> Self { - unsafe { Self::from_inner(NonNull::new_unchecked(ptr)) } - } -} - -impl Rc { - #[inline(always)] - fn inner(&self) -> &RcBox { - // This unsafety is ok because while this Rc is alive we're guaranteed - // that the inner pointer is valid. - unsafe { self.ptr.as_ref() } - } - - #[inline] - fn into_inner_with_allocator(this: Self) -> (NonNull>, A) { - let this = mem::ManuallyDrop::new(this); - (this.ptr, unsafe { ptr::read(&this.alloc) }) - } - - #[inline] - unsafe fn from_inner_in(ptr: NonNull>, alloc: A) -> Self { - Self { ptr, phantom: PhantomData, alloc } - } - - #[inline] - unsafe fn from_ptr_in(ptr: *mut RcBox, alloc: A) -> Self { - unsafe { Self::from_inner_in(NonNull::new_unchecked(ptr), alloc) } - } -} - -impl Rc { - /// Constructs a new `Rc`. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let five = Rc::new(5); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn new(value: T) -> Rc { - // There is an implicit weak pointer owned by all the strong - // pointers, which ensures that the weak destructor never frees - // the allocation while the strong destructor is running, even - // if the weak pointer is stored inside the strong one. - unsafe { - Self::from_inner( - Box::leak(Box::new(RcBox { strong: Cell::new(1), weak: Cell::new(1), value })) - .into(), - ) - } - } - - /// Constructs a new `Rc` while giving you a `Weak` to the allocation, - /// to allow you to construct a `T` which holds a weak pointer to itself. - /// - /// Generally, a structure circularly referencing itself, either directly or - /// indirectly, should not hold a strong reference to itself to prevent a memory leak. - /// Using this function, you get access to the weak pointer during the - /// initialization of `T`, before the `Rc` is created, such that you can - /// clone and store it inside the `T`. - /// - /// `new_cyclic` first allocates the managed allocation for the `Rc`, - /// then calls your closure, giving it a `Weak` to this allocation, - /// and only afterwards completes the construction of the `Rc` by placing - /// the `T` returned from your closure into the allocation. - /// - /// Since the new `Rc` is not fully-constructed until `Rc::new_cyclic` - /// returns, calling [`upgrade`] on the weak reference inside your closure will - /// fail and result in a `None` value. - /// - /// # Panics - /// - /// If `data_fn` panics, the panic is propagated to the caller, and the - /// temporary [`Weak`] is dropped normally. - /// - /// # Examples - /// - /// ``` - /// # #![allow(dead_code)] - /// use std::rc::{Rc, Weak}; - /// - /// struct Gadget { - /// me: Weak, - /// } - /// - /// impl Gadget { - /// /// Construct a reference counted Gadget. - /// fn new() -> Rc { - /// // `me` is a `Weak` pointing at the new allocation of the - /// // `Rc` we're constructing. - /// Rc::new_cyclic(|me| { - /// // Create the actual struct here. - /// Gadget { me: me.clone() } - /// }) - /// } - /// - /// /// Return a reference counted pointer to Self. - /// fn me(&self) -> Rc { - /// self.me.upgrade().unwrap() - /// } - /// } - /// ``` - /// [`upgrade`]: Weak::upgrade - #[cfg(not(no_global_oom_handling))] - #[stable(feature = "arc_new_cyclic", since = "1.60.0")] - pub fn new_cyclic(data_fn: F) -> Rc - where - F: FnOnce(&Weak) -> T, - { - // Construct the inner in the "uninitialized" state with a single - // weak reference. - let uninit_ptr: NonNull<_> = Box::leak(Box::new(RcBox { - strong: Cell::new(0), - weak: Cell::new(1), - value: mem::MaybeUninit::::uninit(), - })) - .into(); - - let init_ptr: NonNull> = uninit_ptr.cast(); - - let weak = Weak { ptr: init_ptr, alloc: Global }; - - // It's important we don't give up ownership of the weak pointer, or - // else the memory might be freed by the time `data_fn` returns. If - // we really wanted to pass ownership, we could create an additional - // weak pointer for ourselves, but this would result in additional - // updates to the weak reference count which might not be necessary - // otherwise. - let data = data_fn(&weak); - - let strong = unsafe { - let inner = init_ptr.as_ptr(); - ptr::write(ptr::addr_of_mut!((*inner).value), data); - - let prev_value = (*inner).strong.get(); - debug_assert_eq!(prev_value, 0, "No prior strong references should exist"); - (*inner).strong.set(1); - - Rc::from_inner(init_ptr) - }; - - // Strong references should collectively own a shared weak reference, - // so don't run the destructor for our old weak reference. - mem::forget(weak); - strong - } - - /// Constructs a new `Rc` with uninitialized contents. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// #![feature(get_mut_unchecked)] - /// - /// use std::rc::Rc; - /// - /// let mut five = Rc::::new_uninit(); - /// - /// // Deferred initialization: - /// Rc::get_mut(&mut five).unwrap().write(5); - /// - /// let five = unsafe { five.assume_init() }; - /// - /// assert_eq!(*five, 5) - /// ``` - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "new_uninit", issue = "63291")] - #[must_use] - pub fn new_uninit() -> Rc> { - unsafe { - Rc::from_ptr(Rc::allocate_for_layout( - Layout::new::(), - |layout| Global.allocate(layout), - <*mut u8>::cast, - )) - } - } - - /// Constructs a new `Rc` with uninitialized contents, with the memory - /// being filled with `0` bytes. - /// - /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and - /// incorrect usage of this method. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// - /// use std::rc::Rc; - /// - /// let zero = Rc::::new_zeroed(); - /// let zero = unsafe { zero.assume_init() }; - /// - /// assert_eq!(*zero, 0) - /// ``` - /// - /// [zeroed]: mem::MaybeUninit::zeroed - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "new_uninit", issue = "63291")] - #[must_use] - pub fn new_zeroed() -> Rc> { - unsafe { - Rc::from_ptr(Rc::allocate_for_layout( - Layout::new::(), - |layout| Global.allocate_zeroed(layout), - <*mut u8>::cast, - )) - } - } - - /// Constructs a new `Rc`, returning an error if the allocation fails - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// use std::rc::Rc; - /// - /// let five = Rc::try_new(5); - /// # Ok::<(), std::alloc::AllocError>(()) - /// ``` - #[unstable(feature = "allocator_api", issue = "32838")] - pub fn try_new(value: T) -> Result, AllocError> { - // There is an implicit weak pointer owned by all the strong - // pointers, which ensures that the weak destructor never frees - // the allocation while the strong destructor is running, even - // if the weak pointer is stored inside the strong one. - unsafe { - Ok(Self::from_inner( - Box::leak(Box::try_new(RcBox { strong: Cell::new(1), weak: Cell::new(1), value })?) - .into(), - )) - } - } - - /// Constructs a new `Rc` with uninitialized contents, returning an error if the allocation fails - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api, new_uninit)] - /// #![feature(get_mut_unchecked)] - /// - /// use std::rc::Rc; - /// - /// let mut five = Rc::::try_new_uninit()?; - /// - /// // Deferred initialization: - /// Rc::get_mut(&mut five).unwrap().write(5); - /// - /// let five = unsafe { five.assume_init() }; - /// - /// assert_eq!(*five, 5); - /// # Ok::<(), std::alloc::AllocError>(()) - /// ``` - #[unstable(feature = "allocator_api", issue = "32838")] - // #[unstable(feature = "new_uninit", issue = "63291")] - pub fn try_new_uninit() -> Result>, AllocError> { - unsafe { - Ok(Rc::from_ptr(Rc::try_allocate_for_layout( - Layout::new::(), - |layout| Global.allocate(layout), - <*mut u8>::cast, - )?)) - } - } - - /// Constructs a new `Rc` with uninitialized contents, with the memory - /// being filled with `0` bytes, returning an error if the allocation fails - /// - /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and - /// incorrect usage of this method. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api, new_uninit)] - /// - /// use std::rc::Rc; - /// - /// let zero = Rc::::try_new_zeroed()?; - /// let zero = unsafe { zero.assume_init() }; - /// - /// assert_eq!(*zero, 0); - /// # Ok::<(), std::alloc::AllocError>(()) - /// ``` - /// - /// [zeroed]: mem::MaybeUninit::zeroed - #[unstable(feature = "allocator_api", issue = "32838")] - //#[unstable(feature = "new_uninit", issue = "63291")] - pub fn try_new_zeroed() -> Result>, AllocError> { - unsafe { - Ok(Rc::from_ptr(Rc::try_allocate_for_layout( - Layout::new::(), - |layout| Global.allocate_zeroed(layout), - <*mut u8>::cast, - )?)) - } - } - /// Constructs a new `Pin>`. If `T` does not implement `Unpin`, then - /// `value` will be pinned in memory and unable to be moved. - #[cfg(not(no_global_oom_handling))] - #[stable(feature = "pin", since = "1.33.0")] - #[must_use] - pub fn pin(value: T) -> Pin> { - unsafe { Pin::new_unchecked(Rc::new(value)) } - } -} - -impl Rc { - /// Returns a reference to the underlying allocator. - /// - /// Note: this is an associated function, which means that you have - /// to call it as `Rc::allocator(&r)` instead of `r.allocator()`. This - /// is so that there is no conflict with a method on the inner type. - #[inline] - #[unstable(feature = "allocator_api", issue = "32838")] - pub fn allocator(this: &Self) -> &A { - &this.alloc - } - /// Constructs a new `Rc` in the provided allocator. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// use std::rc::Rc; - /// use std::alloc::System; - /// - /// let five = Rc::new_in(5, System); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "allocator_api", issue = "32838")] - #[inline] - pub fn new_in(value: T, alloc: A) -> Rc { - // NOTE: Prefer match over unwrap_or_else since closure sometimes not inlineable. - // That would make code size bigger. - match Self::try_new_in(value, alloc) { - Ok(m) => m, - Err(_) => handle_alloc_error(Layout::new::>()), - } - } - - /// Constructs a new `Rc` with uninitialized contents in the provided allocator. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// #![feature(get_mut_unchecked)] - /// #![feature(allocator_api)] - /// - /// use std::rc::Rc; - /// use std::alloc::System; - /// - /// let mut five = Rc::::new_uninit_in(System); - /// - /// let five = unsafe { - /// // Deferred initialization: - /// Rc::get_mut_unchecked(&mut five).as_mut_ptr().write(5); - /// - /// five.assume_init() - /// }; - /// - /// assert_eq!(*five, 5) - /// ``` - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "allocator_api", issue = "32838")] - // #[unstable(feature = "new_uninit", issue = "63291")] - #[inline] - pub fn new_uninit_in(alloc: A) -> Rc, A> { - unsafe { - Rc::from_ptr_in( - Rc::allocate_for_layout( - Layout::new::(), - |layout| alloc.allocate(layout), - <*mut u8>::cast, - ), - alloc, - ) - } - } - - /// Constructs a new `Rc` with uninitialized contents, with the memory - /// being filled with `0` bytes, in the provided allocator. - /// - /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and - /// incorrect usage of this method. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// #![feature(allocator_api)] - /// - /// use std::rc::Rc; - /// use std::alloc::System; - /// - /// let zero = Rc::::new_zeroed_in(System); - /// let zero = unsafe { zero.assume_init() }; - /// - /// assert_eq!(*zero, 0) - /// ``` - /// - /// [zeroed]: mem::MaybeUninit::zeroed - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "allocator_api", issue = "32838")] - // #[unstable(feature = "new_uninit", issue = "63291")] - #[inline] - pub fn new_zeroed_in(alloc: A) -> Rc, A> { - unsafe { - Rc::from_ptr_in( - Rc::allocate_for_layout( - Layout::new::(), - |layout| alloc.allocate_zeroed(layout), - <*mut u8>::cast, - ), - alloc, - ) - } - } - - /// Constructs a new `Rc` in the provided allocator, returning an error if the allocation - /// fails - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// use std::rc::Rc; - /// use std::alloc::System; - /// - /// let five = Rc::try_new_in(5, System); - /// # Ok::<(), std::alloc::AllocError>(()) - /// ``` - #[unstable(feature = "allocator_api", issue = "32838")] - #[inline] - pub fn try_new_in(value: T, alloc: A) -> Result { - // There is an implicit weak pointer owned by all the strong - // pointers, which ensures that the weak destructor never frees - // the allocation while the strong destructor is running, even - // if the weak pointer is stored inside the strong one. - let (ptr, alloc) = Box::into_unique(Box::try_new_in( - RcBox { strong: Cell::new(1), weak: Cell::new(1), value }, - alloc, - )?); - Ok(unsafe { Self::from_inner_in(ptr.into(), alloc) }) - } - - /// Constructs a new `Rc` with uninitialized contents, in the provided allocator, returning an - /// error if the allocation fails - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api, new_uninit)] - /// #![feature(get_mut_unchecked)] - /// - /// use std::rc::Rc; - /// use std::alloc::System; - /// - /// let mut five = Rc::::try_new_uninit_in(System)?; - /// - /// let five = unsafe { - /// // Deferred initialization: - /// Rc::get_mut_unchecked(&mut five).as_mut_ptr().write(5); - /// - /// five.assume_init() - /// }; - /// - /// assert_eq!(*five, 5); - /// # Ok::<(), std::alloc::AllocError>(()) - /// ``` - #[unstable(feature = "allocator_api", issue = "32838")] - // #[unstable(feature = "new_uninit", issue = "63291")] - #[inline] - pub fn try_new_uninit_in(alloc: A) -> Result, A>, AllocError> { - unsafe { - Ok(Rc::from_ptr_in( - Rc::try_allocate_for_layout( - Layout::new::(), - |layout| alloc.allocate(layout), - <*mut u8>::cast, - )?, - alloc, - )) - } - } - - /// Constructs a new `Rc` with uninitialized contents, with the memory - /// being filled with `0` bytes, in the provided allocator, returning an error if the allocation - /// fails - /// - /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and - /// incorrect usage of this method. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api, new_uninit)] - /// - /// use std::rc::Rc; - /// use std::alloc::System; - /// - /// let zero = Rc::::try_new_zeroed_in(System)?; - /// let zero = unsafe { zero.assume_init() }; - /// - /// assert_eq!(*zero, 0); - /// # Ok::<(), std::alloc::AllocError>(()) - /// ``` - /// - /// [zeroed]: mem::MaybeUninit::zeroed - #[unstable(feature = "allocator_api", issue = "32838")] - //#[unstable(feature = "new_uninit", issue = "63291")] - #[inline] - pub fn try_new_zeroed_in(alloc: A) -> Result, A>, AllocError> { - unsafe { - Ok(Rc::from_ptr_in( - Rc::try_allocate_for_layout( - Layout::new::(), - |layout| alloc.allocate_zeroed(layout), - <*mut u8>::cast, - )?, - alloc, - )) - } - } - - /// Constructs a new `Pin>` in the provided allocator. If `T` does not implement `Unpin`, then - /// `value` will be pinned in memory and unable to be moved. - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "allocator_api", issue = "32838")] - #[inline] - pub fn pin_in(value: T, alloc: A) -> Pin - where - A: 'static, - { - unsafe { Pin::new_unchecked(Rc::new_in(value, alloc)) } - } - - /// Returns the inner value, if the `Rc` has exactly one strong reference. - /// - /// Otherwise, an [`Err`] is returned with the same `Rc` that was - /// passed in. - /// - /// This will succeed even if there are outstanding weak references. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let x = Rc::new(3); - /// assert_eq!(Rc::try_unwrap(x), Ok(3)); - /// - /// let x = Rc::new(4); - /// let _y = Rc::clone(&x); - /// assert_eq!(*Rc::try_unwrap(x).unwrap_err(), 4); - /// ``` - #[inline] - #[stable(feature = "rc_unique", since = "1.4.0")] - pub fn try_unwrap(this: Self) -> Result { - if Rc::strong_count(&this) == 1 { - unsafe { - let val = ptr::read(&*this); // copy the contained object - let alloc = ptr::read(&this.alloc); // copy the allocator - - // Indicate to Weaks that they can't be promoted by decrementing - // the strong count, and then remove the implicit "strong weak" - // pointer while also handling drop logic by just crafting a - // fake Weak. - this.inner().dec_strong(); - let _weak = Weak { ptr: this.ptr, alloc }; - forget(this); - Ok(val) - } - } else { - Err(this) - } - } - - /// Returns the inner value, if the `Rc` has exactly one strong reference. - /// - /// Otherwise, [`None`] is returned and the `Rc` is dropped. - /// - /// This will succeed even if there are outstanding weak references. - /// - /// If `Rc::into_inner` is called on every clone of this `Rc`, - /// it is guaranteed that exactly one of the calls returns the inner value. - /// This means in particular that the inner value is not dropped. - /// - /// [`Rc::try_unwrap`] is conceptually similar to `Rc::into_inner`. - /// And while they are meant for different use-cases, `Rc::into_inner(this)` - /// is in fact equivalent to [Rc::try_unwrap]\(this).[ok][Result::ok](). - /// (Note that the same kind of equivalence does **not** hold true for - /// [`Arc`](crate::sync::Arc), due to race conditions that do not apply to `Rc`!) - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let x = Rc::new(3); - /// assert_eq!(Rc::into_inner(x), Some(3)); - /// - /// let x = Rc::new(4); - /// let y = Rc::clone(&x); - /// - /// assert_eq!(Rc::into_inner(y), None); - /// assert_eq!(Rc::into_inner(x), Some(4)); - /// ``` - #[inline] - #[stable(feature = "rc_into_inner", since = "1.70.0")] - pub fn into_inner(this: Self) -> Option { - Rc::try_unwrap(this).ok() - } -} - -impl Rc<[T]> { - /// Constructs a new reference-counted slice with uninitialized contents. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// #![feature(get_mut_unchecked)] - /// - /// use std::rc::Rc; - /// - /// let mut values = Rc::<[u32]>::new_uninit_slice(3); - /// - /// // Deferred initialization: - /// let data = Rc::get_mut(&mut values).unwrap(); - /// data[0].write(1); - /// data[1].write(2); - /// data[2].write(3); - /// - /// let values = unsafe { values.assume_init() }; - /// - /// assert_eq!(*values, [1, 2, 3]) - /// ``` - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "new_uninit", issue = "63291")] - #[must_use] - pub fn new_uninit_slice(len: usize) -> Rc<[mem::MaybeUninit]> { - unsafe { Rc::from_ptr(Rc::allocate_for_slice(len)) } - } - - /// Constructs a new reference-counted slice with uninitialized contents, with the memory being - /// filled with `0` bytes. - /// - /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and - /// incorrect usage of this method. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// - /// use std::rc::Rc; - /// - /// let values = Rc::<[u32]>::new_zeroed_slice(3); - /// let values = unsafe { values.assume_init() }; - /// - /// assert_eq!(*values, [0, 0, 0]) - /// ``` - /// - /// [zeroed]: mem::MaybeUninit::zeroed - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "new_uninit", issue = "63291")] - #[must_use] - pub fn new_zeroed_slice(len: usize) -> Rc<[mem::MaybeUninit]> { - unsafe { - Rc::from_ptr(Rc::allocate_for_layout( - Layout::array::(len).unwrap(), - |layout| Global.allocate_zeroed(layout), - |mem| { - ptr::slice_from_raw_parts_mut(mem.cast::(), len) - as *mut RcBox<[mem::MaybeUninit]> - }, - )) - } - } -} - -impl Rc<[T], A> { - /// Constructs a new reference-counted slice with uninitialized contents. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// #![feature(get_mut_unchecked)] - /// #![feature(allocator_api)] - /// - /// use std::rc::Rc; - /// use std::alloc::System; - /// - /// let mut values = Rc::<[u32], _>::new_uninit_slice_in(3, System); - /// - /// let values = unsafe { - /// // Deferred initialization: - /// Rc::get_mut_unchecked(&mut values)[0].as_mut_ptr().write(1); - /// Rc::get_mut_unchecked(&mut values)[1].as_mut_ptr().write(2); - /// Rc::get_mut_unchecked(&mut values)[2].as_mut_ptr().write(3); - /// - /// values.assume_init() - /// }; - /// - /// assert_eq!(*values, [1, 2, 3]) - /// ``` - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "allocator_api", issue = "32838")] - // #[unstable(feature = "new_uninit", issue = "63291")] - #[inline] - pub fn new_uninit_slice_in(len: usize, alloc: A) -> Rc<[mem::MaybeUninit], A> { - unsafe { Rc::from_ptr_in(Rc::allocate_for_slice_in(len, &alloc), alloc) } - } - - /// Constructs a new reference-counted slice with uninitialized contents, with the memory being - /// filled with `0` bytes. - /// - /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and - /// incorrect usage of this method. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// #![feature(allocator_api)] - /// - /// use std::rc::Rc; - /// use std::alloc::System; - /// - /// let values = Rc::<[u32], _>::new_zeroed_slice_in(3, System); - /// let values = unsafe { values.assume_init() }; - /// - /// assert_eq!(*values, [0, 0, 0]) - /// ``` - /// - /// [zeroed]: mem::MaybeUninit::zeroed - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "allocator_api", issue = "32838")] - // #[unstable(feature = "new_uninit", issue = "63291")] - #[inline] - pub fn new_zeroed_slice_in(len: usize, alloc: A) -> Rc<[mem::MaybeUninit], A> { - unsafe { - Rc::from_ptr_in( - Rc::allocate_for_layout( - Layout::array::(len).unwrap(), - |layout| alloc.allocate_zeroed(layout), - |mem| { - ptr::slice_from_raw_parts_mut(mem.cast::(), len) - as *mut RcBox<[mem::MaybeUninit]> - }, - ), - alloc, - ) - } - } -} - -impl Rc, A> { - /// Converts to `Rc`. - /// - /// # Safety - /// - /// As with [`MaybeUninit::assume_init`], - /// it is up to the caller to guarantee that the inner value - /// really is in an initialized state. - /// Calling this when the content is not yet fully initialized - /// causes immediate undefined behavior. - /// - /// [`MaybeUninit::assume_init`]: mem::MaybeUninit::assume_init - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// #![feature(get_mut_unchecked)] - /// - /// use std::rc::Rc; - /// - /// let mut five = Rc::::new_uninit(); - /// - /// // Deferred initialization: - /// Rc::get_mut(&mut five).unwrap().write(5); - /// - /// let five = unsafe { five.assume_init() }; - /// - /// assert_eq!(*five, 5) - /// ``` - #[unstable(feature = "new_uninit", issue = "63291")] - #[inline] - pub unsafe fn assume_init(self) -> Rc { - let (ptr, alloc) = Rc::into_inner_with_allocator(self); - unsafe { Rc::from_inner_in(ptr.cast(), alloc) } - } -} - -impl Rc<[mem::MaybeUninit], A> { - /// Converts to `Rc<[T]>`. - /// - /// # Safety - /// - /// As with [`MaybeUninit::assume_init`], - /// it is up to the caller to guarantee that the inner value - /// really is in an initialized state. - /// Calling this when the content is not yet fully initialized - /// causes immediate undefined behavior. - /// - /// [`MaybeUninit::assume_init`]: mem::MaybeUninit::assume_init - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// #![feature(get_mut_unchecked)] - /// - /// use std::rc::Rc; - /// - /// let mut values = Rc::<[u32]>::new_uninit_slice(3); - /// - /// // Deferred initialization: - /// let data = Rc::get_mut(&mut values).unwrap(); - /// data[0].write(1); - /// data[1].write(2); - /// data[2].write(3); - /// - /// let values = unsafe { values.assume_init() }; - /// - /// assert_eq!(*values, [1, 2, 3]) - /// ``` - #[unstable(feature = "new_uninit", issue = "63291")] - #[inline] - pub unsafe fn assume_init(self) -> Rc<[T], A> { - let (ptr, alloc) = Rc::into_inner_with_allocator(self); - unsafe { Rc::from_ptr_in(ptr.as_ptr() as _, alloc) } - } -} - -impl Rc { - /// Constructs an `Rc` from a raw pointer. - /// - /// The raw pointer must have been previously returned by a call to - /// [`Rc::into_raw`][into_raw] with the following requirements: - /// - /// * If `U` is sized, it must have the same size and alignment as `T`. This - /// is trivially true if `U` is `T`. - /// * If `U` is unsized, its data pointer must have the same size and - /// alignment as `T`. This is trivially true if `Rc` was constructed - /// through `Rc` and then converted to `Rc` through an [unsized - /// coercion]. - /// - /// Note that if `U` or `U`'s data pointer is not `T` but has the same size - /// and alignment, this is basically like transmuting references of - /// different types. See [`mem::transmute`][transmute] for more information - /// on what restrictions apply in this case. - /// - /// The raw pointer must point to a block of memory allocated by the global allocator - /// - /// The user of `from_raw` has to make sure a specific value of `T` is only - /// dropped once. - /// - /// This function is unsafe because improper use may lead to memory unsafety, - /// even if the returned `Rc` is never accessed. - /// - /// [into_raw]: Rc::into_raw - /// [transmute]: core::mem::transmute - /// [unsized coercion]: https://doc.rust-lang.org/reference/type-coercions.html#unsized-coercions - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let x = Rc::new("hello".to_owned()); - /// let x_ptr = Rc::into_raw(x); - /// - /// unsafe { - /// // Convert back to an `Rc` to prevent leak. - /// let x = Rc::from_raw(x_ptr); - /// assert_eq!(&*x, "hello"); - /// - /// // Further calls to `Rc::from_raw(x_ptr)` would be memory-unsafe. - /// } - /// - /// // The memory was freed when `x` went out of scope above, so `x_ptr` is now dangling! - /// ``` - /// - /// Convert a slice back into its original array: - /// - /// ``` - /// use std::rc::Rc; - /// - /// let x: Rc<[u32]> = Rc::new([1, 2, 3]); - /// let x_ptr: *const [u32] = Rc::into_raw(x); - /// - /// unsafe { - /// let x: Rc<[u32; 3]> = Rc::from_raw(x_ptr.cast::<[u32; 3]>()); - /// assert_eq!(&*x, &[1, 2, 3]); - /// } - /// ``` - #[inline] - #[stable(feature = "rc_raw", since = "1.17.0")] - pub unsafe fn from_raw(ptr: *const T) -> Self { - unsafe { Self::from_raw_in(ptr, Global) } - } - - /// Increments the strong reference count on the `Rc` associated with the - /// provided pointer by one. - /// - /// # Safety - /// - /// The pointer must have been obtained through `Rc::into_raw`, the - /// associated `Rc` instance must be valid (i.e. the strong count must be at - /// least 1) for the duration of this method, and `ptr` must point to a block of memory - /// allocated by the global allocator. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let five = Rc::new(5); - /// - /// unsafe { - /// let ptr = Rc::into_raw(five); - /// Rc::increment_strong_count(ptr); - /// - /// let five = Rc::from_raw(ptr); - /// assert_eq!(2, Rc::strong_count(&five)); - /// } - /// ``` - #[inline] - #[stable(feature = "rc_mutate_strong_count", since = "1.53.0")] - pub unsafe fn increment_strong_count(ptr: *const T) { - unsafe { Self::increment_strong_count_in(ptr, Global) } - } - - /// Decrements the strong reference count on the `Rc` associated with the - /// provided pointer by one. - /// - /// # Safety - /// - /// The pointer must have been obtained through `Rc::into_raw`, the - /// associated `Rc` instance must be valid (i.e. the strong count must be at - /// least 1) when invoking this method, and `ptr` must point to a block of memory - /// allocated by the global allocator. This method can be used to release the final `Rc` and - /// backing storage, but **should not** be called after the final `Rc` has been released. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let five = Rc::new(5); - /// - /// unsafe { - /// let ptr = Rc::into_raw(five); - /// Rc::increment_strong_count(ptr); - /// - /// let five = Rc::from_raw(ptr); - /// assert_eq!(2, Rc::strong_count(&five)); - /// Rc::decrement_strong_count(ptr); - /// assert_eq!(1, Rc::strong_count(&five)); - /// } - /// ``` - #[inline] - #[stable(feature = "rc_mutate_strong_count", since = "1.53.0")] - pub unsafe fn decrement_strong_count(ptr: *const T) { - unsafe { Self::decrement_strong_count_in(ptr, Global) } - } -} - -impl Rc { - /// Consumes the `Rc`, returning the wrapped pointer. - /// - /// To avoid a memory leak the pointer must be converted back to an `Rc` using - /// [`Rc::from_raw`]. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let x = Rc::new("hello".to_owned()); - /// let x_ptr = Rc::into_raw(x); - /// assert_eq!(unsafe { &*x_ptr }, "hello"); - /// ``` - #[must_use = "losing the pointer will leak memory"] - #[stable(feature = "rc_raw", since = "1.17.0")] - #[rustc_never_returns_null_ptr] - pub fn into_raw(this: Self) -> *const T { - let ptr = Self::as_ptr(&this); - mem::forget(this); - ptr - } - - /// Consumes the `Rc`, returning the wrapped pointer and allocator. - /// - /// To avoid a memory leak the pointer must be converted back to an `Rc` using - /// [`Rc::from_raw_in`]. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// use std::rc::Rc; - /// use std::alloc::System; - /// - /// let x = Rc::new_in("hello".to_owned(), System); - /// let (ptr, alloc) = Rc::into_raw_with_allocator(x); - /// assert_eq!(unsafe { &*ptr }, "hello"); - /// let x = unsafe { Rc::from_raw_in(ptr, alloc) }; - /// assert_eq!(&*x, "hello"); - /// ``` - #[unstable(feature = "allocator_api", issue = "32838")] - pub fn into_raw_with_allocator(this: Self) -> (*const T, A) { - let this = mem::ManuallyDrop::new(this); - let ptr = Self::as_ptr(&this); - // Safety: `this` is ManuallyDrop so the allocator will not be double-dropped - let alloc = unsafe { ptr::read(&this.alloc) }; - (ptr, alloc) - } - - /// Provides a raw pointer to the data. - /// - /// The counts are not affected in any way and the `Rc` is not consumed. The pointer is valid - /// for as long there are strong counts in the `Rc`. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let x = Rc::new("hello".to_owned()); - /// let y = Rc::clone(&x); - /// let x_ptr = Rc::as_ptr(&x); - /// assert_eq!(x_ptr, Rc::as_ptr(&y)); - /// assert_eq!(unsafe { &*x_ptr }, "hello"); - /// ``` - #[stable(feature = "weak_into_raw", since = "1.45.0")] - #[rustc_never_returns_null_ptr] - pub fn as_ptr(this: &Self) -> *const T { - let ptr: *mut RcBox = NonNull::as_ptr(this.ptr); - - // SAFETY: This cannot go through Deref::deref or Rc::inner because - // this is required to retain raw/mut provenance such that e.g. `get_mut` can - // write through the pointer after the Rc is recovered through `from_raw`. - unsafe { ptr::addr_of_mut!((*ptr).value) } - } - - /// Constructs an `Rc` from a raw pointer in the provided allocator. - /// - /// The raw pointer must have been previously returned by a call to [`Rc::into_raw`][into_raw] with the following requirements: - /// - /// * If `U` is sized, it must have the same size and alignment as `T`. This - /// is trivially true if `U` is `T`. - /// * If `U` is unsized, its data pointer must have the same size and - /// alignment as `T`. This is trivially true if `Rc` was constructed - /// through `Rc` and then converted to `Rc` through an [unsized - /// coercion]. - /// - /// Note that if `U` or `U`'s data pointer is not `T` but has the same size - /// and alignment, this is basically like transmuting references of - /// different types. See [`mem::transmute`][transmute] for more information - /// on what restrictions apply in this case. - /// - /// The raw pointer must point to a block of memory allocated by `alloc` - /// - /// The user of `from_raw` has to make sure a specific value of `T` is only - /// dropped once. - /// - /// This function is unsafe because improper use may lead to memory unsafety, - /// even if the returned `Rc` is never accessed. - /// - /// [into_raw]: Rc::into_raw - /// [transmute]: core::mem::transmute - /// [unsized coercion]: https://doc.rust-lang.org/reference/type-coercions.html#unsized-coercions - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// - /// use std::rc::Rc; - /// use std::alloc::System; - /// - /// let x = Rc::new_in("hello".to_owned(), System); - /// let x_ptr = Rc::into_raw(x); - /// - /// unsafe { - /// // Convert back to an `Rc` to prevent leak. - /// let x = Rc::from_raw_in(x_ptr, System); - /// assert_eq!(&*x, "hello"); - /// - /// // Further calls to `Rc::from_raw(x_ptr)` would be memory-unsafe. - /// } - /// - /// // The memory was freed when `x` went out of scope above, so `x_ptr` is now dangling! - /// ``` - /// - /// Convert a slice back into its original array: - /// - /// ``` - /// #![feature(allocator_api)] - /// - /// use std::rc::Rc; - /// use std::alloc::System; - /// - /// let x: Rc<[u32], _> = Rc::new_in([1, 2, 3], System); - /// let x_ptr: *const [u32] = Rc::into_raw(x); - /// - /// unsafe { - /// let x: Rc<[u32; 3], _> = Rc::from_raw_in(x_ptr.cast::<[u32; 3]>(), System); - /// assert_eq!(&*x, &[1, 2, 3]); - /// } - /// ``` - #[unstable(feature = "allocator_api", issue = "32838")] - pub unsafe fn from_raw_in(ptr: *const T, alloc: A) -> Self { - let offset = unsafe { data_offset(ptr) }; - - // Reverse the offset to find the original RcBox. - let rc_ptr = unsafe { ptr.byte_sub(offset) as *mut RcBox }; - - unsafe { Self::from_ptr_in(rc_ptr, alloc) } - } - - /// Creates a new [`Weak`] pointer to this allocation. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let five = Rc::new(5); - /// - /// let weak_five = Rc::downgrade(&five); - /// ``` - #[must_use = "this returns a new `Weak` pointer, \ - without modifying the original `Rc`"] - #[stable(feature = "rc_weak", since = "1.4.0")] - pub fn downgrade(this: &Self) -> Weak - where - A: Clone, - { - this.inner().inc_weak(); - // Make sure we do not create a dangling Weak - debug_assert!(!is_dangling(this.ptr.as_ptr())); - Weak { ptr: this.ptr, alloc: this.alloc.clone() } - } - - /// Gets the number of [`Weak`] pointers to this allocation. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let five = Rc::new(5); - /// let _weak_five = Rc::downgrade(&five); - /// - /// assert_eq!(1, Rc::weak_count(&five)); - /// ``` - #[inline] - #[stable(feature = "rc_counts", since = "1.15.0")] - pub fn weak_count(this: &Self) -> usize { - this.inner().weak() - 1 - } - - /// Gets the number of strong (`Rc`) pointers to this allocation. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let five = Rc::new(5); - /// let _also_five = Rc::clone(&five); - /// - /// assert_eq!(2, Rc::strong_count(&five)); - /// ``` - #[inline] - #[stable(feature = "rc_counts", since = "1.15.0")] - pub fn strong_count(this: &Self) -> usize { - this.inner().strong() - } - - /// Increments the strong reference count on the `Rc` associated with the - /// provided pointer by one. - /// - /// # Safety - /// - /// The pointer must have been obtained through `Rc::into_raw`, the - /// associated `Rc` instance must be valid (i.e. the strong count must be at - /// least 1) for the duration of this method, and `ptr` must point to a block of memory - /// allocated by `alloc` - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// - /// use std::rc::Rc; - /// use std::alloc::System; - /// - /// let five = Rc::new_in(5, System); - /// - /// unsafe { - /// let ptr = Rc::into_raw(five); - /// Rc::increment_strong_count_in(ptr, System); - /// - /// let five = Rc::from_raw_in(ptr, System); - /// assert_eq!(2, Rc::strong_count(&five)); - /// } - /// ``` - #[inline] - #[unstable(feature = "allocator_api", issue = "32838")] - pub unsafe fn increment_strong_count_in(ptr: *const T, alloc: A) - where - A: Clone, - { - // Retain Rc, but don't touch refcount by wrapping in ManuallyDrop - let rc = unsafe { mem::ManuallyDrop::new(Rc::::from_raw_in(ptr, alloc)) }; - // Now increase refcount, but don't drop new refcount either - let _rc_clone: mem::ManuallyDrop<_> = rc.clone(); - } - - /// Decrements the strong reference count on the `Rc` associated with the - /// provided pointer by one. - /// - /// # Safety - /// - /// The pointer must have been obtained through `Rc::into_raw`, the - /// associated `Rc` instance must be valid (i.e. the strong count must be at - /// least 1) when invoking this method, and `ptr` must point to a block of memory - /// allocated by `alloc`. This method can be used to release the final `Rc` and backing storage, - /// but **should not** be called after the final `Rc` has been released. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// - /// use std::rc::Rc; - /// use std::alloc::System; - /// - /// let five = Rc::new_in(5, System); - /// - /// unsafe { - /// let ptr = Rc::into_raw(five); - /// Rc::increment_strong_count_in(ptr, System); - /// - /// let five = Rc::from_raw_in(ptr, System); - /// assert_eq!(2, Rc::strong_count(&five)); - /// Rc::decrement_strong_count_in(ptr, System); - /// assert_eq!(1, Rc::strong_count(&five)); - /// } - /// ``` - #[inline] - #[unstable(feature = "allocator_api", issue = "32838")] - pub unsafe fn decrement_strong_count_in(ptr: *const T, alloc: A) { - unsafe { drop(Rc::from_raw_in(ptr, alloc)) }; - } - - /// Returns `true` if there are no other `Rc` or [`Weak`] pointers to - /// this allocation. - #[inline] - fn is_unique(this: &Self) -> bool { - Rc::weak_count(this) == 0 && Rc::strong_count(this) == 1 - } - - /// Returns a mutable reference into the given `Rc`, if there are - /// no other `Rc` or [`Weak`] pointers to the same allocation. - /// - /// Returns [`None`] otherwise, because it is not safe to - /// mutate a shared value. - /// - /// See also [`make_mut`][make_mut], which will [`clone`][clone] - /// the inner value when there are other `Rc` pointers. - /// - /// [make_mut]: Rc::make_mut - /// [clone]: Clone::clone - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let mut x = Rc::new(3); - /// *Rc::get_mut(&mut x).unwrap() = 4; - /// assert_eq!(*x, 4); - /// - /// let _y = Rc::clone(&x); - /// assert!(Rc::get_mut(&mut x).is_none()); - /// ``` - #[inline] - #[stable(feature = "rc_unique", since = "1.4.0")] - pub fn get_mut(this: &mut Self) -> Option<&mut T> { - if Rc::is_unique(this) { unsafe { Some(Rc::get_mut_unchecked(this)) } } else { None } - } - - /// Returns a mutable reference into the given `Rc`, - /// without any check. - /// - /// See also [`get_mut`], which is safe and does appropriate checks. - /// - /// [`get_mut`]: Rc::get_mut - /// - /// # Safety - /// - /// If any other `Rc` or [`Weak`] pointers to the same allocation exist, then - /// they must not be dereferenced or have active borrows for the duration - /// of the returned borrow, and their inner type must be exactly the same as the - /// inner type of this Rc (including lifetimes). This is trivially the case if no - /// such pointers exist, for example immediately after `Rc::new`. - /// - /// # Examples - /// - /// ``` - /// #![feature(get_mut_unchecked)] - /// - /// use std::rc::Rc; - /// - /// let mut x = Rc::new(String::new()); - /// unsafe { - /// Rc::get_mut_unchecked(&mut x).push_str("foo") - /// } - /// assert_eq!(*x, "foo"); - /// ``` - /// Other `Rc` pointers to the same allocation must be to the same type. - /// ```no_run - /// #![feature(get_mut_unchecked)] - /// - /// use std::rc::Rc; - /// - /// let x: Rc = Rc::from("Hello, world!"); - /// let mut y: Rc<[u8]> = x.clone().into(); - /// unsafe { - /// // this is Undefined Behavior, because x's inner type is str, not [u8] - /// Rc::get_mut_unchecked(&mut y).fill(0xff); // 0xff is invalid in UTF-8 - /// } - /// println!("{}", &*x); // Invalid UTF-8 in a str - /// ``` - /// Other `Rc` pointers to the same allocation must be to the exact same type, including lifetimes. - /// ```no_run - /// #![feature(get_mut_unchecked)] - /// - /// use std::rc::Rc; - /// - /// let x: Rc<&str> = Rc::new("Hello, world!"); - /// { - /// let s = String::from("Oh, no!"); - /// let mut y: Rc<&str> = x.clone().into(); - /// unsafe { - /// // this is Undefined Behavior, because x's inner type - /// // is &'long str, not &'short str - /// *Rc::get_mut_unchecked(&mut y) = &s; - /// } - /// } - /// println!("{}", &*x); // Use-after-free - /// ``` - #[inline] - #[unstable(feature = "get_mut_unchecked", issue = "63292")] - pub unsafe fn get_mut_unchecked(this: &mut Self) -> &mut T { - // We are careful to *not* create a reference covering the "count" fields, as - // this would conflict with accesses to the reference counts (e.g. by `Weak`). - unsafe { &mut (*this.ptr.as_ptr()).value } - } - - #[inline] - #[stable(feature = "ptr_eq", since = "1.17.0")] - /// Returns `true` if the two `Rc`s point to the same allocation in a vein similar to - /// [`ptr::eq`]. This function ignores the metadata of `dyn Trait` pointers. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let five = Rc::new(5); - /// let same_five = Rc::clone(&five); - /// let other_five = Rc::new(5); - /// - /// assert!(Rc::ptr_eq(&five, &same_five)); - /// assert!(!Rc::ptr_eq(&five, &other_five)); - /// ``` - pub fn ptr_eq(this: &Self, other: &Self) -> bool { - ptr::addr_eq(this.ptr.as_ptr(), other.ptr.as_ptr()) - } -} - -impl Rc { - /// Makes a mutable reference into the given `Rc`. - /// - /// If there are other `Rc` pointers to the same allocation, then `make_mut` will - /// [`clone`] the inner value to a new allocation to ensure unique ownership. This is also - /// referred to as clone-on-write. - /// - /// However, if there are no other `Rc` pointers to this allocation, but some [`Weak`] - /// pointers, then the [`Weak`] pointers will be disassociated and the inner value will not - /// be cloned. - /// - /// See also [`get_mut`], which will fail rather than cloning the inner value - /// or disassociating [`Weak`] pointers. - /// - /// [`clone`]: Clone::clone - /// [`get_mut`]: Rc::get_mut - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let mut data = Rc::new(5); - /// - /// *Rc::make_mut(&mut data) += 1; // Won't clone anything - /// let mut other_data = Rc::clone(&data); // Won't clone inner data - /// *Rc::make_mut(&mut data) += 1; // Clones inner data - /// *Rc::make_mut(&mut data) += 1; // Won't clone anything - /// *Rc::make_mut(&mut other_data) *= 2; // Won't clone anything - /// - /// // Now `data` and `other_data` point to different allocations. - /// assert_eq!(*data, 8); - /// assert_eq!(*other_data, 12); - /// ``` - /// - /// [`Weak`] pointers will be disassociated: - /// - /// ``` - /// use std::rc::Rc; - /// - /// let mut data = Rc::new(75); - /// let weak = Rc::downgrade(&data); - /// - /// assert!(75 == *data); - /// assert!(75 == *weak.upgrade().unwrap()); - /// - /// *Rc::make_mut(&mut data) += 1; - /// - /// assert!(76 == *data); - /// assert!(weak.upgrade().is_none()); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[inline] - #[stable(feature = "rc_unique", since = "1.4.0")] - pub fn make_mut(this: &mut Self) -> &mut T { - if Rc::strong_count(this) != 1 { - // Gotta clone the data, there are other Rcs. - // Pre-allocate memory to allow writing the cloned value directly. - let mut rc = Self::new_uninit_in(this.alloc.clone()); - unsafe { - let data = Rc::get_mut_unchecked(&mut rc); - (**this).write_clone_into_raw(data.as_mut_ptr()); - *this = rc.assume_init(); - } - } else if Rc::weak_count(this) != 0 { - // Can just steal the data, all that's left is Weaks - let mut rc = Self::new_uninit_in(this.alloc.clone()); - unsafe { - let data = Rc::get_mut_unchecked(&mut rc); - data.as_mut_ptr().copy_from_nonoverlapping(&**this, 1); - - this.inner().dec_strong(); - // Remove implicit strong-weak ref (no need to craft a fake - // Weak here -- we know other Weaks can clean up for us) - this.inner().dec_weak(); - ptr::write(this, rc.assume_init()); - } - } - // This unsafety is ok because we're guaranteed that the pointer - // returned is the *only* pointer that will ever be returned to T. Our - // reference count is guaranteed to be 1 at this point, and we required - // the `Rc` itself to be `mut`, so we're returning the only possible - // reference to the allocation. - unsafe { &mut this.ptr.as_mut().value } - } -} - -impl Rc { - /// If we have the only reference to `T` then unwrap it. Otherwise, clone `T` and return the - /// clone. - /// - /// Assuming `rc_t` is of type `Rc`, this function is functionally equivalent to - /// `(*rc_t).clone()`, but will avoid cloning the inner value where possible. - /// - /// # Examples - /// - /// ``` - /// # use std::{ptr, rc::Rc}; - /// let inner = String::from("test"); - /// let ptr = inner.as_ptr(); - /// - /// let rc = Rc::new(inner); - /// let inner = Rc::unwrap_or_clone(rc); - /// // The inner value was not cloned - /// assert!(ptr::eq(ptr, inner.as_ptr())); - /// - /// let rc = Rc::new(inner); - /// let rc2 = rc.clone(); - /// let inner = Rc::unwrap_or_clone(rc); - /// // Because there were 2 references, we had to clone the inner value. - /// assert!(!ptr::eq(ptr, inner.as_ptr())); - /// // `rc2` is the last reference, so when we unwrap it we get back - /// // the original `String`. - /// let inner = Rc::unwrap_or_clone(rc2); - /// assert!(ptr::eq(ptr, inner.as_ptr())); - /// ``` - #[inline] - #[stable(feature = "arc_unwrap_or_clone", since = "1.76.0")] - pub fn unwrap_or_clone(this: Self) -> T { - Rc::try_unwrap(this).unwrap_or_else(|rc| (*rc).clone()) - } -} - -impl Rc { - /// Attempt to downcast the `Rc` to a concrete type. - /// - /// # Examples - /// - /// ``` - /// use std::any::Any; - /// use std::rc::Rc; - /// - /// fn print_if_string(value: Rc) { - /// if let Ok(string) = value.downcast::() { - /// println!("String ({}): {}", string.len(), string); - /// } - /// } - /// - /// let my_string = "Hello World".to_string(); - /// print_if_string(Rc::new(my_string)); - /// print_if_string(Rc::new(0i8)); - /// ``` - #[inline] - #[stable(feature = "rc_downcast", since = "1.29.0")] - pub fn downcast(self) -> Result, Self> { - if (*self).is::() { - unsafe { - let (ptr, alloc) = Rc::into_inner_with_allocator(self); - Ok(Rc::from_inner_in(ptr.cast(), alloc)) - } - } else { - Err(self) - } - } - - /// Downcasts the `Rc` to a concrete type. - /// - /// For a safe alternative see [`downcast`]. - /// - /// # Examples - /// - /// ``` - /// #![feature(downcast_unchecked)] - /// - /// use std::any::Any; - /// use std::rc::Rc; - /// - /// let x: Rc = Rc::new(1_usize); - /// - /// unsafe { - /// assert_eq!(*x.downcast_unchecked::(), 1); - /// } - /// ``` - /// - /// # Safety - /// - /// The contained value must be of type `T`. Calling this method - /// with the incorrect type is *undefined behavior*. - /// - /// - /// [`downcast`]: Self::downcast - #[inline] - #[unstable(feature = "downcast_unchecked", issue = "90850")] - pub unsafe fn downcast_unchecked(self) -> Rc { - unsafe { - let (ptr, alloc) = Rc::into_inner_with_allocator(self); - Rc::from_inner_in(ptr.cast(), alloc) - } - } -} - -impl Rc { - /// Allocates an `RcBox` with sufficient space for - /// a possibly-unsized inner value where the value has the layout provided. - /// - /// The function `mem_to_rcbox` is called with the data pointer - /// and must return back a (potentially fat)-pointer for the `RcBox`. - #[cfg(not(no_global_oom_handling))] - unsafe fn allocate_for_layout( - value_layout: Layout, - allocate: impl FnOnce(Layout) -> Result, AllocError>, - mem_to_rcbox: impl FnOnce(*mut u8) -> *mut RcBox, - ) -> *mut RcBox { - let layout = rcbox_layout_for_value_layout(value_layout); - unsafe { - Rc::try_allocate_for_layout(value_layout, allocate, mem_to_rcbox) - .unwrap_or_else(|_| handle_alloc_error(layout)) - } - } - - /// Allocates an `RcBox` with sufficient space for - /// a possibly-unsized inner value where the value has the layout provided, - /// returning an error if allocation fails. - /// - /// The function `mem_to_rcbox` is called with the data pointer - /// and must return back a (potentially fat)-pointer for the `RcBox`. - #[inline] - unsafe fn try_allocate_for_layout( - value_layout: Layout, - allocate: impl FnOnce(Layout) -> Result, AllocError>, - mem_to_rcbox: impl FnOnce(*mut u8) -> *mut RcBox, - ) -> Result<*mut RcBox, AllocError> { - let layout = rcbox_layout_for_value_layout(value_layout); - - // Allocate for the layout. - let ptr = allocate(layout)?; - - // Initialize the RcBox - let inner = mem_to_rcbox(ptr.as_non_null_ptr().as_ptr()); - unsafe { - debug_assert_eq!(Layout::for_value_raw(inner), layout); - - ptr::addr_of_mut!((*inner).strong).write(Cell::new(1)); - ptr::addr_of_mut!((*inner).weak).write(Cell::new(1)); - } - - Ok(inner) - } -} - -impl Rc { - /// Allocates an `RcBox` with sufficient space for an unsized inner value - #[cfg(not(no_global_oom_handling))] - unsafe fn allocate_for_ptr_in(ptr: *const T, alloc: &A) -> *mut RcBox { - // Allocate for the `RcBox` using the given value. - unsafe { - Rc::::allocate_for_layout( - Layout::for_value_raw(ptr), - |layout| alloc.allocate(layout), - |mem| mem.with_metadata_of(ptr as *const RcBox), - ) - } - } - - #[cfg(not(no_global_oom_handling))] - fn from_box_in(src: Box) -> Rc { - unsafe { - let value_size = size_of_val(&*src); - let ptr = Self::allocate_for_ptr_in(&*src, Box::allocator(&src)); - - // Copy value as bytes - ptr::copy_nonoverlapping( - core::ptr::addr_of!(*src) as *const u8, - ptr::addr_of_mut!((*ptr).value) as *mut u8, - value_size, - ); - - // Free the allocation without dropping its contents - let (bptr, alloc) = Box::into_raw_with_allocator(src); - let src = Box::from_raw_in(bptr as *mut mem::ManuallyDrop, alloc.by_ref()); - drop(src); - - Self::from_ptr_in(ptr, alloc) - } - } -} - -impl Rc<[T]> { - /// Allocates an `RcBox<[T]>` with the given length. - #[cfg(not(no_global_oom_handling))] - unsafe fn allocate_for_slice(len: usize) -> *mut RcBox<[T]> { - unsafe { - Self::allocate_for_layout( - Layout::array::(len).unwrap(), - |layout| Global.allocate(layout), - |mem| ptr::slice_from_raw_parts_mut(mem.cast::(), len) as *mut RcBox<[T]>, - ) - } - } - - /// Copy elements from slice into newly allocated `Rc<[T]>` - /// - /// Unsafe because the caller must either take ownership or bind `T: Copy` - #[cfg(not(no_global_oom_handling))] - unsafe fn copy_from_slice(v: &[T]) -> Rc<[T]> { - unsafe { - let ptr = Self::allocate_for_slice(v.len()); - ptr::copy_nonoverlapping( - v.as_ptr(), - ptr::addr_of_mut!((*ptr).value) as *mut T, - v.len(), - ); - Self::from_ptr(ptr) - } - } - - /// Constructs an `Rc<[T]>` from an iterator known to be of a certain size. - /// - /// Behavior is undefined should the size be wrong. - #[cfg(not(no_global_oom_handling))] - unsafe fn from_iter_exact(iter: impl Iterator, len: usize) -> Rc<[T]> { - // Panic guard while cloning T elements. - // In the event of a panic, elements that have been written - // into the new RcBox will be dropped, then the memory freed. - struct Guard { - mem: NonNull, - elems: *mut T, - layout: Layout, - n_elems: usize, - } - - impl Drop for Guard { - fn drop(&mut self) { - unsafe { - let slice = from_raw_parts_mut(self.elems, self.n_elems); - ptr::drop_in_place(slice); - - Global.deallocate(self.mem, self.layout); - } - } - } - - unsafe { - let ptr = Self::allocate_for_slice(len); - - let mem = ptr as *mut _ as *mut u8; - let layout = Layout::for_value_raw(ptr); - - // Pointer to first element - let elems = ptr::addr_of_mut!((*ptr).value) as *mut T; - - let mut guard = Guard { mem: NonNull::new_unchecked(mem), elems, layout, n_elems: 0 }; - - for (i, item) in iter.enumerate() { - ptr::write(elems.add(i), item); - guard.n_elems += 1; - } - - // All clear. Forget the guard so it doesn't free the new RcBox. - forget(guard); - - Self::from_ptr(ptr) - } - } -} - -impl Rc<[T], A> { - /// Allocates an `RcBox<[T]>` with the given length. - #[inline] - #[cfg(not(no_global_oom_handling))] - unsafe fn allocate_for_slice_in(len: usize, alloc: &A) -> *mut RcBox<[T]> { - unsafe { - Rc::<[T]>::allocate_for_layout( - Layout::array::(len).unwrap(), - |layout| alloc.allocate(layout), - |mem| ptr::slice_from_raw_parts_mut(mem.cast::(), len) as *mut RcBox<[T]>, - ) - } - } -} - -#[cfg(not(no_global_oom_handling))] -/// Specialization trait used for `From<&[T]>`. -trait RcFromSlice { - fn from_slice(slice: &[T]) -> Self; -} - -#[cfg(not(no_global_oom_handling))] -impl RcFromSlice for Rc<[T]> { - #[inline] - default fn from_slice(v: &[T]) -> Self { - unsafe { Self::from_iter_exact(v.iter().cloned(), v.len()) } - } -} - -#[cfg(not(no_global_oom_handling))] -impl RcFromSlice for Rc<[T]> { - #[inline] - fn from_slice(v: &[T]) -> Self { - unsafe { Rc::copy_from_slice(v) } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Deref for Rc { - type Target = T; - - #[inline(always)] - fn deref(&self) -> &T { - &self.inner().value - } -} - -#[unstable(feature = "deref_pure_trait", issue = "87121")] -unsafe impl DerefPure for Rc {} - -#[unstable(feature = "receiver_trait", issue = "none")] -impl Receiver for Rc {} - -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl<#[may_dangle] T: ?Sized, A: Allocator> Drop for Rc { - /// Drops the `Rc`. - /// - /// This will decrement the strong reference count. If the strong reference - /// count reaches zero then the only other references (if any) are - /// [`Weak`], so we `drop` the inner value. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// struct Foo; - /// - /// impl Drop for Foo { - /// fn drop(&mut self) { - /// println!("dropped!"); - /// } - /// } - /// - /// let foo = Rc::new(Foo); - /// let foo2 = Rc::clone(&foo); - /// - /// drop(foo); // Doesn't print anything - /// drop(foo2); // Prints "dropped!" - /// ``` - fn drop(&mut self) { - unsafe { - self.inner().dec_strong(); - if self.inner().strong() == 0 { - // destroy the contained object - ptr::drop_in_place(Self::get_mut_unchecked(self)); - - // remove the implicit "strong weak" pointer now that we've - // destroyed the contents. - self.inner().dec_weak(); - - if self.inner().weak() == 0 { - self.alloc - .deallocate(self.ptr.cast(), Layout::for_value_raw(self.ptr.as_ptr())); - } - } - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Rc { - /// Makes a clone of the `Rc` pointer. - /// - /// This creates another pointer to the same allocation, increasing the - /// strong reference count. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let five = Rc::new(5); - /// - /// let _ = Rc::clone(&five); - /// ``` - #[inline] - fn clone(&self) -> Self { - unsafe { - self.inner().inc_strong(); - Self::from_inner_in(self.ptr, self.alloc.clone()) - } - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl Default for Rc { - /// Creates a new `Rc`, with the `Default` value for `T`. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let x: Rc = Default::default(); - /// assert_eq!(*x, 0); - /// ``` - #[inline] - fn default() -> Rc { - Rc::new(Default::default()) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "more_rc_default_impls", since = "CURRENT_RUSTC_VERSION")] -impl Default for Rc { - /// Creates an empty str inside an Rc - /// - /// This may or may not share an allocation with other Rcs on the same thread. - #[inline] - fn default() -> Self { - Rc::from("") - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "more_rc_default_impls", since = "CURRENT_RUSTC_VERSION")] -impl Default for Rc<[T]> { - /// Creates an empty `[T]` inside an Rc - /// - /// This may or may not share an allocation with other Rcs on the same thread. - #[inline] - fn default() -> Self { - let arr: [T; 0] = []; - Rc::from(arr) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -trait RcEqIdent { - fn eq(&self, other: &Rc) -> bool; - fn ne(&self, other: &Rc) -> bool; -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl RcEqIdent for Rc { - #[inline] - default fn eq(&self, other: &Rc) -> bool { - **self == **other - } - - #[inline] - default fn ne(&self, other: &Rc) -> bool { - **self != **other - } -} - -// Hack to allow specializing on `Eq` even though `Eq` has a method. -#[rustc_unsafe_specialization_marker] -pub(crate) trait MarkerEq: PartialEq {} - -impl MarkerEq for T {} - -/// We're doing this specialization here, and not as a more general optimization on `&T`, because it -/// would otherwise add a cost to all equality checks on refs. We assume that `Rc`s are used to -/// store large values, that are slow to clone, but also heavy to check for equality, causing this -/// cost to pay off more easily. It's also more likely to have two `Rc` clones, that point to -/// the same value, than two `&T`s. -/// -/// We can only do this when `T: Eq` as a `PartialEq` might be deliberately irreflexive. -#[stable(feature = "rust1", since = "1.0.0")] -impl RcEqIdent for Rc { - #[inline] - fn eq(&self, other: &Rc) -> bool { - Rc::ptr_eq(self, other) || **self == **other - } - - #[inline] - fn ne(&self, other: &Rc) -> bool { - !Rc::ptr_eq(self, other) && **self != **other - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for Rc { - /// Equality for two `Rc`s. - /// - /// Two `Rc`s are equal if their inner values are equal, even if they are - /// stored in different allocation. - /// - /// If `T` also implements `Eq` (implying reflexivity of equality), - /// two `Rc`s that point to the same allocation are - /// always equal. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let five = Rc::new(5); - /// - /// assert!(five == Rc::new(5)); - /// ``` - #[inline] - fn eq(&self, other: &Rc) -> bool { - RcEqIdent::eq(self, other) - } - - /// Inequality for two `Rc`s. - /// - /// Two `Rc`s are not equal if their inner values are not equal. - /// - /// If `T` also implements `Eq` (implying reflexivity of equality), - /// two `Rc`s that point to the same allocation are - /// always equal. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let five = Rc::new(5); - /// - /// assert!(five != Rc::new(6)); - /// ``` - #[inline] - fn ne(&self, other: &Rc) -> bool { - RcEqIdent::ne(self, other) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Eq for Rc {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialOrd for Rc { - /// Partial comparison for two `Rc`s. - /// - /// The two are compared by calling `partial_cmp()` on their inner values. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// use std::cmp::Ordering; - /// - /// let five = Rc::new(5); - /// - /// assert_eq!(Some(Ordering::Less), five.partial_cmp(&Rc::new(6))); - /// ``` - #[inline(always)] - fn partial_cmp(&self, other: &Rc) -> Option { - (**self).partial_cmp(&**other) - } - - /// Less-than comparison for two `Rc`s. - /// - /// The two are compared by calling `<` on their inner values. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let five = Rc::new(5); - /// - /// assert!(five < Rc::new(6)); - /// ``` - #[inline(always)] - fn lt(&self, other: &Rc) -> bool { - **self < **other - } - - /// 'Less than or equal to' comparison for two `Rc`s. - /// - /// The two are compared by calling `<=` on their inner values. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let five = Rc::new(5); - /// - /// assert!(five <= Rc::new(5)); - /// ``` - #[inline(always)] - fn le(&self, other: &Rc) -> bool { - **self <= **other - } - - /// Greater-than comparison for two `Rc`s. - /// - /// The two are compared by calling `>` on their inner values. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let five = Rc::new(5); - /// - /// assert!(five > Rc::new(4)); - /// ``` - #[inline(always)] - fn gt(&self, other: &Rc) -> bool { - **self > **other - } - - /// 'Greater than or equal to' comparison for two `Rc`s. - /// - /// The two are compared by calling `>=` on their inner values. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let five = Rc::new(5); - /// - /// assert!(five >= Rc::new(5)); - /// ``` - #[inline(always)] - fn ge(&self, other: &Rc) -> bool { - **self >= **other - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for Rc { - /// Comparison for two `Rc`s. - /// - /// The two are compared by calling `cmp()` on their inner values. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// use std::cmp::Ordering; - /// - /// let five = Rc::new(5); - /// - /// assert_eq!(Ordering::Less, five.cmp(&Rc::new(6))); - /// ``` - #[inline] - fn cmp(&self, other: &Rc) -> Ordering { - (**self).cmp(&**other) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Hash for Rc { - fn hash(&self, state: &mut H) { - (**self).hash(state); - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for Rc { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt(&**self, f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for Rc { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&**self, f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Pointer for Rc { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Pointer::fmt(&core::ptr::addr_of!(**self), f) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "from_for_ptrs", since = "1.6.0")] -impl From for Rc { - /// Converts a generic type `T` into an `Rc` - /// - /// The conversion allocates on the heap and moves `t` - /// from the stack into it. - /// - /// # Example - /// ```rust - /// # use std::rc::Rc; - /// let x = 5; - /// let rc = Rc::new(5); - /// - /// assert_eq!(Rc::from(x), rc); - /// ``` - fn from(t: T) -> Self { - Rc::new(t) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "shared_from_array", since = "1.74.0")] -impl From<[T; N]> for Rc<[T]> { - /// Converts a [`[T; N]`](prim@array) into an `Rc<[T]>`. - /// - /// The conversion moves the array into a newly allocated `Rc`. - /// - /// # Example - /// - /// ``` - /// # use std::rc::Rc; - /// let original: [i32; 3] = [1, 2, 3]; - /// let shared: Rc<[i32]> = Rc::from(original); - /// assert_eq!(&[1, 2, 3], &shared[..]); - /// ``` - #[inline] - fn from(v: [T; N]) -> Rc<[T]> { - Rc::<[T; N]>::from(v) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "shared_from_slice", since = "1.21.0")] -impl From<&[T]> for Rc<[T]> { - /// Allocate a reference-counted slice and fill it by cloning `v`'s items. - /// - /// # Example - /// - /// ``` - /// # use std::rc::Rc; - /// let original: &[i32] = &[1, 2, 3]; - /// let shared: Rc<[i32]> = Rc::from(original); - /// assert_eq!(&[1, 2, 3], &shared[..]); - /// ``` - #[inline] - fn from(v: &[T]) -> Rc<[T]> { - >::from_slice(v) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "shared_from_slice", since = "1.21.0")] -impl From<&str> for Rc { - /// Allocate a reference-counted string slice and copy `v` into it. - /// - /// # Example - /// - /// ``` - /// # use std::rc::Rc; - /// let shared: Rc = Rc::from("statue"); - /// assert_eq!("statue", &shared[..]); - /// ``` - #[inline] - fn from(v: &str) -> Rc { - let rc = Rc::<[u8]>::from(v.as_bytes()); - unsafe { Rc::from_raw(Rc::into_raw(rc) as *const str) } - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "shared_from_slice", since = "1.21.0")] -impl From for Rc { - /// Allocate a reference-counted string slice and copy `v` into it. - /// - /// # Example - /// - /// ``` - /// # use std::rc::Rc; - /// let original: String = "statue".to_owned(); - /// let shared: Rc = Rc::from(original); - /// assert_eq!("statue", &shared[..]); - /// ``` - #[inline] - fn from(v: String) -> Rc { - Rc::from(&v[..]) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "shared_from_slice", since = "1.21.0")] -impl From> for Rc { - /// Move a boxed object to a new, reference counted, allocation. - /// - /// # Example - /// - /// ``` - /// # use std::rc::Rc; - /// let original: Box = Box::new(1); - /// let shared: Rc = Rc::from(original); - /// assert_eq!(1, *shared); - /// ``` - #[inline] - fn from(v: Box) -> Rc { - Rc::from_box_in(v) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "shared_from_slice", since = "1.21.0")] -impl From> for Rc<[T], A> { - /// Allocate a reference-counted slice and move `v`'s items into it. - /// - /// # Example - /// - /// ``` - /// # use std::rc::Rc; - /// let unique: Vec = vec![1, 2, 3]; - /// let shared: Rc<[i32]> = Rc::from(unique); - /// assert_eq!(&[1, 2, 3], &shared[..]); - /// ``` - #[inline] - fn from(v: Vec) -> Rc<[T], A> { - unsafe { - let (vec_ptr, len, cap, alloc) = v.into_raw_parts_with_alloc(); - - let rc_ptr = Self::allocate_for_slice_in(len, &alloc); - ptr::copy_nonoverlapping(vec_ptr, ptr::addr_of_mut!((*rc_ptr).value) as *mut T, len); - - // Create a `Vec` with length 0, to deallocate the buffer - // without dropping its contents or the allocator - let _ = Vec::from_raw_parts_in(vec_ptr, 0, cap, &alloc); - - Self::from_ptr_in(rc_ptr, alloc) - } - } -} - -#[stable(feature = "shared_from_cow", since = "1.45.0")] -impl<'a, B> From> for Rc -where - B: ToOwned + ?Sized, - Rc: From<&'a B> + From, -{ - /// Create a reference-counted pointer from - /// a clone-on-write pointer by copying its content. - /// - /// # Example - /// - /// ```rust - /// # use std::rc::Rc; - /// # use std::borrow::Cow; - /// let cow: Cow<'_, str> = Cow::Borrowed("eggplant"); - /// let shared: Rc = Rc::from(cow); - /// assert_eq!("eggplant", &shared[..]); - /// ``` - #[inline] - fn from(cow: Cow<'a, B>) -> Rc { - match cow { - Cow::Borrowed(s) => Rc::from(s), - Cow::Owned(s) => Rc::from(s), - } - } -} - -#[stable(feature = "shared_from_str", since = "1.62.0")] -impl From> for Rc<[u8]> { - /// Converts a reference-counted string slice into a byte slice. - /// - /// # Example - /// - /// ``` - /// # use std::rc::Rc; - /// let string: Rc = Rc::from("eggplant"); - /// let bytes: Rc<[u8]> = Rc::from(string); - /// assert_eq!("eggplant".as_bytes(), bytes.as_ref()); - /// ``` - #[inline] - fn from(rc: Rc) -> Self { - // SAFETY: `str` has the same layout as `[u8]`. - unsafe { Rc::from_raw(Rc::into_raw(rc) as *const [u8]) } - } -} - -#[stable(feature = "boxed_slice_try_from", since = "1.43.0")] -impl TryFrom> for Rc<[T; N], A> { - type Error = Rc<[T], A>; - - fn try_from(boxed_slice: Rc<[T], A>) -> Result { - if boxed_slice.len() == N { - let (ptr, alloc) = Rc::into_inner_with_allocator(boxed_slice); - Ok(unsafe { Rc::from_inner_in(ptr.cast(), alloc) }) - } else { - Err(boxed_slice) - } - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "shared_from_iter", since = "1.37.0")] -impl FromIterator for Rc<[T]> { - /// Takes each element in the `Iterator` and collects it into an `Rc<[T]>`. - /// - /// # Performance characteristics - /// - /// ## The general case - /// - /// In the general case, collecting into `Rc<[T]>` is done by first - /// collecting into a `Vec`. That is, when writing the following: - /// - /// ```rust - /// # use std::rc::Rc; - /// let evens: Rc<[u8]> = (0..10).filter(|&x| x % 2 == 0).collect(); - /// # assert_eq!(&*evens, &[0, 2, 4, 6, 8]); - /// ``` - /// - /// this behaves as if we wrote: - /// - /// ```rust - /// # use std::rc::Rc; - /// let evens: Rc<[u8]> = (0..10).filter(|&x| x % 2 == 0) - /// .collect::>() // The first set of allocations happens here. - /// .into(); // A second allocation for `Rc<[T]>` happens here. - /// # assert_eq!(&*evens, &[0, 2, 4, 6, 8]); - /// ``` - /// - /// This will allocate as many times as needed for constructing the `Vec` - /// and then it will allocate once for turning the `Vec` into the `Rc<[T]>`. - /// - /// ## Iterators of known length - /// - /// When your `Iterator` implements `TrustedLen` and is of an exact size, - /// a single allocation will be made for the `Rc<[T]>`. For example: - /// - /// ```rust - /// # use std::rc::Rc; - /// let evens: Rc<[u8]> = (0..10).collect(); // Just a single allocation happens here. - /// # assert_eq!(&*evens, &*(0..10).collect::>()); - /// ``` - fn from_iter>(iter: I) -> Self { - ToRcSlice::to_rc_slice(iter.into_iter()) - } -} - -/// Specialization trait used for collecting into `Rc<[T]>`. -#[cfg(not(no_global_oom_handling))] -trait ToRcSlice: Iterator + Sized { - fn to_rc_slice(self) -> Rc<[T]>; -} - -#[cfg(not(no_global_oom_handling))] -impl> ToRcSlice for I { - default fn to_rc_slice(self) -> Rc<[T]> { - self.collect::>().into() - } -} - -#[cfg(not(no_global_oom_handling))] -impl> ToRcSlice for I { - fn to_rc_slice(self) -> Rc<[T]> { - // This is the case for a `TrustedLen` iterator. - let (low, high) = self.size_hint(); - if let Some(high) = high { - debug_assert_eq!( - low, - high, - "TrustedLen iterator's size hint is not exact: {:?}", - (low, high) - ); - - unsafe { - // SAFETY: We need to ensure that the iterator has an exact length and we have. - Rc::from_iter_exact(self, low) - } - } else { - // TrustedLen contract guarantees that `upper_bound == None` implies an iterator - // length exceeding `usize::MAX`. - // The default implementation would collect into a vec which would panic. - // Thus we panic here immediately without invoking `Vec` code. - panic!("capacity overflow"); - } - } -} - -/// `Weak` is a version of [`Rc`] that holds a non-owning reference to the -/// managed allocation. The allocation is accessed by calling [`upgrade`] on the `Weak` -/// pointer, which returns an [Option]<[Rc]\>. -/// -/// Since a `Weak` reference does not count towards ownership, it will not -/// prevent the value stored in the allocation from being dropped, and `Weak` itself makes no -/// guarantees about the value still being present. Thus it may return [`None`] -/// when [`upgrade`]d. Note however that a `Weak` reference *does* prevent the allocation -/// itself (the backing store) from being deallocated. -/// -/// A `Weak` pointer is useful for keeping a temporary reference to the allocation -/// managed by [`Rc`] without preventing its inner value from being dropped. It is also used to -/// prevent circular references between [`Rc`] pointers, since mutual owning references -/// would never allow either [`Rc`] to be dropped. For example, a tree could -/// have strong [`Rc`] pointers from parent nodes to children, and `Weak` -/// pointers from children back to their parents. -/// -/// The typical way to obtain a `Weak` pointer is to call [`Rc::downgrade`]. -/// -/// [`upgrade`]: Weak::upgrade -#[stable(feature = "rc_weak", since = "1.4.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "RcWeak")] -pub struct Weak< - T: ?Sized, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, -> { - // This is a `NonNull` to allow optimizing the size of this type in enums, - // but it is not necessarily a valid pointer. - // `Weak::new` sets this to `usize::MAX` so that it doesn’t need - // to allocate space on the heap. That's not a value a real pointer - // will ever have because RcBox has alignment at least 2. - // This is only possible when `T: Sized`; unsized `T` never dangle. - ptr: NonNull>, - alloc: A, -} - -#[stable(feature = "rc_weak", since = "1.4.0")] -impl !Send for Weak {} -#[stable(feature = "rc_weak", since = "1.4.0")] -impl !Sync for Weak {} - -#[unstable(feature = "coerce_unsized", issue = "18598")] -impl, U: ?Sized, A: Allocator> CoerceUnsized> for Weak {} - -#[unstable(feature = "dispatch_from_dyn", issue = "none")] -impl, U: ?Sized> DispatchFromDyn> for Weak {} - -impl Weak { - /// Constructs a new `Weak`, without allocating any memory. - /// Calling [`upgrade`] on the return value always gives [`None`]. - /// - /// [`upgrade`]: Weak::upgrade - /// - /// # Examples - /// - /// ``` - /// use std::rc::Weak; - /// - /// let empty: Weak = Weak::new(); - /// assert!(empty.upgrade().is_none()); - /// ``` - #[inline] - #[stable(feature = "downgraded_weak", since = "1.10.0")] - #[rustc_const_stable(feature = "const_weak_new", since = "1.73.0")] - #[must_use] - pub const fn new() -> Weak { - Weak { - ptr: unsafe { - NonNull::new_unchecked(ptr::without_provenance_mut::>(usize::MAX)) - }, - alloc: Global, - } - } -} - -impl Weak { - /// Constructs a new `Weak`, without allocating any memory, technically in the provided - /// allocator. - /// Calling [`upgrade`] on the return value always gives [`None`]. - /// - /// [`upgrade`]: Weak::upgrade - /// - /// # Examples - /// - /// ``` - /// use std::rc::Weak; - /// - /// let empty: Weak = Weak::new(); - /// assert!(empty.upgrade().is_none()); - /// ``` - #[inline] - #[unstable(feature = "allocator_api", issue = "32838")] - pub fn new_in(alloc: A) -> Weak { - Weak { - ptr: unsafe { - NonNull::new_unchecked(ptr::without_provenance_mut::>(usize::MAX)) - }, - alloc, - } - } -} - -pub(crate) fn is_dangling(ptr: *const T) -> bool { - (ptr.cast::<()>()).addr() == usize::MAX -} - -/// Helper type to allow accessing the reference counts without -/// making any assertions about the data field. -struct WeakInner<'a> { - weak: &'a Cell, - strong: &'a Cell, -} - -impl Weak { - /// Converts a raw pointer previously created by [`into_raw`] back into `Weak`. - /// - /// This can be used to safely get a strong reference (by calling [`upgrade`] - /// later) or to deallocate the weak count by dropping the `Weak`. - /// - /// It takes ownership of one weak reference (with the exception of pointers created by [`new`], - /// as these don't own anything; the method still works on them). - /// - /// # Safety - /// - /// The pointer must have originated from the [`into_raw`] and must still own its potential - /// weak reference, and `ptr` must point to a block of memory allocated by the global allocator. - /// - /// It is allowed for the strong count to be 0 at the time of calling this. Nevertheless, this - /// takes ownership of one weak reference currently represented as a raw pointer (the weak - /// count is not modified by this operation) and therefore it must be paired with a previous - /// call to [`into_raw`]. - /// - /// # Examples - /// - /// ``` - /// use std::rc::{Rc, Weak}; - /// - /// let strong = Rc::new("hello".to_owned()); - /// - /// let raw_1 = Rc::downgrade(&strong).into_raw(); - /// let raw_2 = Rc::downgrade(&strong).into_raw(); - /// - /// assert_eq!(2, Rc::weak_count(&strong)); - /// - /// assert_eq!("hello", &*unsafe { Weak::from_raw(raw_1) }.upgrade().unwrap()); - /// assert_eq!(1, Rc::weak_count(&strong)); - /// - /// drop(strong); - /// - /// // Decrement the last weak count. - /// assert!(unsafe { Weak::from_raw(raw_2) }.upgrade().is_none()); - /// ``` - /// - /// [`into_raw`]: Weak::into_raw - /// [`upgrade`]: Weak::upgrade - /// [`new`]: Weak::new - #[inline] - #[stable(feature = "weak_into_raw", since = "1.45.0")] - pub unsafe fn from_raw(ptr: *const T) -> Self { - unsafe { Self::from_raw_in(ptr, Global) } - } -} - -impl Weak { - /// Returns a raw pointer to the object `T` pointed to by this `Weak`. - /// - /// The pointer is valid only if there are some strong references. The pointer may be dangling, - /// unaligned or even [`null`] otherwise. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// use std::ptr; - /// - /// let strong = Rc::new("hello".to_owned()); - /// let weak = Rc::downgrade(&strong); - /// // Both point to the same object - /// assert!(ptr::eq(&*strong, weak.as_ptr())); - /// // The strong here keeps it alive, so we can still access the object. - /// assert_eq!("hello", unsafe { &*weak.as_ptr() }); - /// - /// drop(strong); - /// // But not any more. We can do weak.as_ptr(), but accessing the pointer would lead to - /// // undefined behaviour. - /// // assert_eq!("hello", unsafe { &*weak.as_ptr() }); - /// ``` - /// - /// [`null`]: ptr::null - #[must_use] - #[stable(feature = "rc_as_ptr", since = "1.45.0")] - pub fn as_ptr(&self) -> *const T { - let ptr: *mut RcBox = NonNull::as_ptr(self.ptr); - - if is_dangling(ptr) { - // If the pointer is dangling, we return the sentinel directly. This cannot be - // a valid payload address, as the payload is at least as aligned as RcBox (usize). - ptr as *const T - } else { - // SAFETY: if is_dangling returns false, then the pointer is dereferenceable. - // The payload may be dropped at this point, and we have to maintain provenance, - // so use raw pointer manipulation. - unsafe { ptr::addr_of_mut!((*ptr).value) } - } - } - - /// Consumes the `Weak` and turns it into a raw pointer. - /// - /// This converts the weak pointer into a raw pointer, while still preserving the ownership of - /// one weak reference (the weak count is not modified by this operation). It can be turned - /// back into the `Weak` with [`from_raw`]. - /// - /// The same restrictions of accessing the target of the pointer as with - /// [`as_ptr`] apply. - /// - /// # Examples - /// - /// ``` - /// use std::rc::{Rc, Weak}; - /// - /// let strong = Rc::new("hello".to_owned()); - /// let weak = Rc::downgrade(&strong); - /// let raw = weak.into_raw(); - /// - /// assert_eq!(1, Rc::weak_count(&strong)); - /// assert_eq!("hello", unsafe { &*raw }); - /// - /// drop(unsafe { Weak::from_raw(raw) }); - /// assert_eq!(0, Rc::weak_count(&strong)); - /// ``` - /// - /// [`from_raw`]: Weak::from_raw - /// [`as_ptr`]: Weak::as_ptr - #[must_use = "losing the pointer will leak memory"] - #[stable(feature = "weak_into_raw", since = "1.45.0")] - pub fn into_raw(self) -> *const T { - let result = self.as_ptr(); - mem::forget(self); - result - } - - /// Consumes the `Weak`, returning the wrapped pointer and allocator. - /// - /// This converts the weak pointer into a raw pointer, while still preserving the ownership of - /// one weak reference (the weak count is not modified by this operation). It can be turned - /// back into the `Weak` with [`from_raw_in`]. - /// - /// The same restrictions of accessing the target of the pointer as with - /// [`as_ptr`] apply. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// use std::rc::{Rc, Weak}; - /// use std::alloc::System; - /// - /// let strong = Rc::new_in("hello".to_owned(), System); - /// let weak = Rc::downgrade(&strong); - /// let (raw, alloc) = weak.into_raw_with_allocator(); - /// - /// assert_eq!(1, Rc::weak_count(&strong)); - /// assert_eq!("hello", unsafe { &*raw }); - /// - /// drop(unsafe { Weak::from_raw_in(raw, alloc) }); - /// assert_eq!(0, Rc::weak_count(&strong)); - /// ``` - /// - /// [`from_raw_in`]: Weak::from_raw_in - /// [`as_ptr`]: Weak::as_ptr - #[inline] - #[unstable(feature = "allocator_api", issue = "32838")] - pub fn into_raw_with_allocator(self) -> (*const T, A) { - let this = mem::ManuallyDrop::new(self); - let result = this.as_ptr(); - // Safety: `this` is ManuallyDrop so the allocator will not be double-dropped - let alloc = unsafe { ptr::read(&this.alloc) }; - (result, alloc) - } - - /// Converts a raw pointer previously created by [`into_raw`] back into `Weak`. - /// - /// This can be used to safely get a strong reference (by calling [`upgrade`] - /// later) or to deallocate the weak count by dropping the `Weak`. - /// - /// It takes ownership of one weak reference (with the exception of pointers created by [`new`], - /// as these don't own anything; the method still works on them). - /// - /// # Safety - /// - /// The pointer must have originated from the [`into_raw`] and must still own its potential - /// weak reference, and `ptr` must point to a block of memory allocated by `alloc`. - /// - /// It is allowed for the strong count to be 0 at the time of calling this. Nevertheless, this - /// takes ownership of one weak reference currently represented as a raw pointer (the weak - /// count is not modified by this operation) and therefore it must be paired with a previous - /// call to [`into_raw`]. - /// - /// # Examples - /// - /// ``` - /// use std::rc::{Rc, Weak}; - /// - /// let strong = Rc::new("hello".to_owned()); - /// - /// let raw_1 = Rc::downgrade(&strong).into_raw(); - /// let raw_2 = Rc::downgrade(&strong).into_raw(); - /// - /// assert_eq!(2, Rc::weak_count(&strong)); - /// - /// assert_eq!("hello", &*unsafe { Weak::from_raw(raw_1) }.upgrade().unwrap()); - /// assert_eq!(1, Rc::weak_count(&strong)); - /// - /// drop(strong); - /// - /// // Decrement the last weak count. - /// assert!(unsafe { Weak::from_raw(raw_2) }.upgrade().is_none()); - /// ``` - /// - /// [`into_raw`]: Weak::into_raw - /// [`upgrade`]: Weak::upgrade - /// [`new`]: Weak::new - #[inline] - #[unstable(feature = "allocator_api", issue = "32838")] - pub unsafe fn from_raw_in(ptr: *const T, alloc: A) -> Self { - // See Weak::as_ptr for context on how the input pointer is derived. - - let ptr = if is_dangling(ptr) { - // This is a dangling Weak. - ptr as *mut RcBox - } else { - // Otherwise, we're guaranteed the pointer came from a nondangling Weak. - // SAFETY: data_offset is safe to call, as ptr references a real (potentially dropped) T. - let offset = unsafe { data_offset(ptr) }; - // Thus, we reverse the offset to get the whole RcBox. - // SAFETY: the pointer originated from a Weak, so this offset is safe. - unsafe { ptr.byte_sub(offset) as *mut RcBox } - }; - - // SAFETY: we now have recovered the original Weak pointer, so can create the Weak. - Weak { ptr: unsafe { NonNull::new_unchecked(ptr) }, alloc } - } - - /// Attempts to upgrade the `Weak` pointer to an [`Rc`], delaying - /// dropping of the inner value if successful. - /// - /// Returns [`None`] if the inner value has since been dropped. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let five = Rc::new(5); - /// - /// let weak_five = Rc::downgrade(&five); - /// - /// let strong_five: Option> = weak_five.upgrade(); - /// assert!(strong_five.is_some()); - /// - /// // Destroy all strong pointers. - /// drop(strong_five); - /// drop(five); - /// - /// assert!(weak_five.upgrade().is_none()); - /// ``` - #[must_use = "this returns a new `Rc`, \ - without modifying the original weak pointer"] - #[stable(feature = "rc_weak", since = "1.4.0")] - pub fn upgrade(&self) -> Option> - where - A: Clone, - { - let inner = self.inner()?; - - if inner.strong() == 0 { - None - } else { - unsafe { - inner.inc_strong(); - Some(Rc::from_inner_in(self.ptr, self.alloc.clone())) - } - } - } - - /// Gets the number of strong (`Rc`) pointers pointing to this allocation. - /// - /// If `self` was created using [`Weak::new`], this will return 0. - #[must_use] - #[stable(feature = "weak_counts", since = "1.41.0")] - pub fn strong_count(&self) -> usize { - if let Some(inner) = self.inner() { inner.strong() } else { 0 } - } - - /// Gets the number of `Weak` pointers pointing to this allocation. - /// - /// If no strong pointers remain, this will return zero. - #[must_use] - #[stable(feature = "weak_counts", since = "1.41.0")] - pub fn weak_count(&self) -> usize { - if let Some(inner) = self.inner() { - if inner.strong() > 0 { - inner.weak() - 1 // subtract the implicit weak ptr - } else { - 0 - } - } else { - 0 - } - } - - /// Returns `None` when the pointer is dangling and there is no allocated `RcBox`, - /// (i.e., when this `Weak` was created by `Weak::new`). - #[inline] - fn inner(&self) -> Option> { - if is_dangling(self.ptr.as_ptr()) { - None - } else { - // We are careful to *not* create a reference covering the "data" field, as - // the field may be mutated concurrently (for example, if the last `Rc` - // is dropped, the data field will be dropped in-place). - Some(unsafe { - let ptr = self.ptr.as_ptr(); - WeakInner { strong: &(*ptr).strong, weak: &(*ptr).weak } - }) - } - } - - /// Returns `true` if the two `Weak`s point to the same allocation similar to [`ptr::eq`], or if - /// both don't point to any allocation (because they were created with `Weak::new()`). However, - /// this function ignores the metadata of `dyn Trait` pointers. - /// - /// # Notes - /// - /// Since this compares pointers it means that `Weak::new()` will equal each - /// other, even though they don't point to any allocation. - /// - /// # Examples - /// - /// ``` - /// use std::rc::Rc; - /// - /// let first_rc = Rc::new(5); - /// let first = Rc::downgrade(&first_rc); - /// let second = Rc::downgrade(&first_rc); - /// - /// assert!(first.ptr_eq(&second)); - /// - /// let third_rc = Rc::new(5); - /// let third = Rc::downgrade(&third_rc); - /// - /// assert!(!first.ptr_eq(&third)); - /// ``` - /// - /// Comparing `Weak::new`. - /// - /// ``` - /// use std::rc::{Rc, Weak}; - /// - /// let first = Weak::new(); - /// let second = Weak::new(); - /// assert!(first.ptr_eq(&second)); - /// - /// let third_rc = Rc::new(()); - /// let third = Rc::downgrade(&third_rc); - /// assert!(!first.ptr_eq(&third)); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "weak_ptr_eq", since = "1.39.0")] - pub fn ptr_eq(&self, other: &Self) -> bool { - ptr::addr_eq(self.ptr.as_ptr(), other.ptr.as_ptr()) - } -} - -#[stable(feature = "rc_weak", since = "1.4.0")] -unsafe impl<#[may_dangle] T: ?Sized, A: Allocator> Drop for Weak { - /// Drops the `Weak` pointer. - /// - /// # Examples - /// - /// ``` - /// use std::rc::{Rc, Weak}; - /// - /// struct Foo; - /// - /// impl Drop for Foo { - /// fn drop(&mut self) { - /// println!("dropped!"); - /// } - /// } - /// - /// let foo = Rc::new(Foo); - /// let weak_foo = Rc::downgrade(&foo); - /// let other_weak_foo = Weak::clone(&weak_foo); - /// - /// drop(weak_foo); // Doesn't print anything - /// drop(foo); // Prints "dropped!" - /// - /// assert!(other_weak_foo.upgrade().is_none()); - /// ``` - fn drop(&mut self) { - let inner = if let Some(inner) = self.inner() { inner } else { return }; - - inner.dec_weak(); - // the weak count starts at 1, and will only go to zero if all - // the strong pointers have disappeared. - if inner.weak() == 0 { - unsafe { - self.alloc.deallocate(self.ptr.cast(), Layout::for_value_raw(self.ptr.as_ptr())); - } - } - } -} - -#[stable(feature = "rc_weak", since = "1.4.0")] -impl Clone for Weak { - /// Makes a clone of the `Weak` pointer that points to the same allocation. - /// - /// # Examples - /// - /// ``` - /// use std::rc::{Rc, Weak}; - /// - /// let weak_five = Rc::downgrade(&Rc::new(5)); - /// - /// let _ = Weak::clone(&weak_five); - /// ``` - #[inline] - fn clone(&self) -> Weak { - if let Some(inner) = self.inner() { - inner.inc_weak() - } - Weak { ptr: self.ptr, alloc: self.alloc.clone() } - } -} - -#[stable(feature = "rc_weak", since = "1.4.0")] -impl fmt::Debug for Weak { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "(Weak)") - } -} - -#[stable(feature = "downgraded_weak", since = "1.10.0")] -impl Default for Weak { - /// Constructs a new `Weak`, without allocating any memory. - /// Calling [`upgrade`] on the return value always gives [`None`]. - /// - /// [`upgrade`]: Weak::upgrade - /// - /// # Examples - /// - /// ``` - /// use std::rc::Weak; - /// - /// let empty: Weak = Default::default(); - /// assert!(empty.upgrade().is_none()); - /// ``` - fn default() -> Weak { - Weak::new() - } -} - -// NOTE: We checked_add here to deal with mem::forget safely. In particular -// if you mem::forget Rcs (or Weaks), the ref-count can overflow, and then -// you can free the allocation while outstanding Rcs (or Weaks) exist. -// We abort because this is such a degenerate scenario that we don't care about -// what happens -- no real program should ever experience this. -// -// This should have negligible overhead since you don't actually need to -// clone these much in Rust thanks to ownership and move-semantics. - -#[doc(hidden)] -trait RcInnerPtr { - fn weak_ref(&self) -> &Cell; - fn strong_ref(&self) -> &Cell; - - #[inline] - fn strong(&self) -> usize { - self.strong_ref().get() - } - - #[inline] - fn inc_strong(&self) { - let strong = self.strong(); - - // We insert an `assume` here to hint LLVM at an otherwise - // missed optimization. - // SAFETY: The reference count will never be zero when this is - // called. - unsafe { - hint::assert_unchecked(strong != 0); - } - - let strong = strong.wrapping_add(1); - self.strong_ref().set(strong); - - // We want to abort on overflow instead of dropping the value. - // Checking for overflow after the store instead of before - // allows for slightly better code generation. - if core::intrinsics::unlikely(strong == 0) { - abort(); - } - } - - #[inline] - fn dec_strong(&self) { - self.strong_ref().set(self.strong() - 1); - } - - #[inline] - fn weak(&self) -> usize { - self.weak_ref().get() - } - - #[inline] - fn inc_weak(&self) { - let weak = self.weak(); - - // We insert an `assume` here to hint LLVM at an otherwise - // missed optimization. - // SAFETY: The reference count will never be zero when this is - // called. - unsafe { - hint::assert_unchecked(weak != 0); - } - - let weak = weak.wrapping_add(1); - self.weak_ref().set(weak); - - // We want to abort on overflow instead of dropping the value. - // Checking for overflow after the store instead of before - // allows for slightly better code generation. - if core::intrinsics::unlikely(weak == 0) { - abort(); - } - } - - #[inline] - fn dec_weak(&self) { - self.weak_ref().set(self.weak() - 1); - } -} - -impl RcInnerPtr for RcBox { - #[inline(always)] - fn weak_ref(&self) -> &Cell { - &self.weak - } - - #[inline(always)] - fn strong_ref(&self) -> &Cell { - &self.strong - } -} - -impl<'a> RcInnerPtr for WeakInner<'a> { - #[inline(always)] - fn weak_ref(&self) -> &Cell { - self.weak - } - - #[inline(always)] - fn strong_ref(&self) -> &Cell { - self.strong - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl borrow::Borrow for Rc { - fn borrow(&self) -> &T { - &**self - } -} - -#[stable(since = "1.5.0", feature = "smart_ptr_as_ref")] -impl AsRef for Rc { - fn as_ref(&self) -> &T { - &**self - } -} - -#[stable(feature = "pin", since = "1.33.0")] -impl Unpin for Rc {} - -/// Get the offset within an `RcBox` for the payload behind a pointer. -/// -/// # Safety -/// -/// The pointer must point to (and have valid metadata for) a previously -/// valid instance of T, but the T is allowed to be dropped. -unsafe fn data_offset(ptr: *const T) -> usize { - // Align the unsized value to the end of the RcBox. - // Because RcBox is repr(C), it will always be the last field in memory. - // SAFETY: since the only unsized types possible are slices, trait objects, - // and extern types, the input safety requirement is currently enough to - // satisfy the requirements of align_of_val_raw; this is an implementation - // detail of the language that must not be relied upon outside of std. - unsafe { data_offset_align(align_of_val_raw(ptr)) } -} - -#[inline] -fn data_offset_align(align: usize) -> usize { - let layout = Layout::new::>(); - layout.size() + layout.padding_needed_for(align) -} - -/// A uniquely owned `Rc` -/// -/// This represents an `Rc` that is known to be uniquely owned -- that is, have exactly one strong -/// reference. Multiple weak pointers can be created, but attempts to upgrade those to strong -/// references will fail unless the `UniqueRc` they point to has been converted into a regular `Rc`. -/// -/// Because they are uniquely owned, the contents of a `UniqueRc` can be freely mutated. A common -/// use case is to have an object be mutable during its initialization phase but then have it become -/// immutable and converted to a normal `Rc`. -/// -/// This can be used as a flexible way to create cyclic data structures, as in the example below. -/// -/// ``` -/// #![feature(unique_rc_arc)] -/// use std::rc::{Rc, Weak, UniqueRc}; -/// -/// struct Gadget { -/// #[allow(dead_code)] -/// me: Weak, -/// } -/// -/// fn create_gadget() -> Option> { -/// let mut rc = UniqueRc::new(Gadget { -/// me: Weak::new(), -/// }); -/// rc.me = UniqueRc::downgrade(&rc); -/// Some(UniqueRc::into_rc(rc)) -/// } -/// -/// create_gadget().unwrap(); -/// ``` -/// -/// An advantage of using `UniqueRc` over [`Rc::new_cyclic`] to build cyclic data structures is that -/// [`Rc::new_cyclic`]'s `data_fn` parameter cannot be async or return a [`Result`]. As shown in the -/// previous example, `UniqueRc` allows for more flexibility in the construction of cyclic data, -/// including fallible or async constructors. -#[unstable(feature = "unique_rc_arc", issue = "112566")] -#[derive(Debug)] -pub struct UniqueRc { - ptr: NonNull>, - phantom: PhantomData>, -} - -impl UniqueRc { - /// Creates a new `UniqueRc` - /// - /// Weak references to this `UniqueRc` can be created with [`UniqueRc::downgrade`]. Upgrading - /// these weak references will fail before the `UniqueRc` has been converted into an [`Rc`]. - /// After converting the `UniqueRc` into an [`Rc`], any weak references created beforehand will - /// point to the new [`Rc`]. - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "unique_rc_arc", issue = "112566")] - pub fn new(value: T) -> Self { - Self { - ptr: Box::leak(Box::new(RcBox { - strong: Cell::new(0), - // keep one weak reference so if all the weak pointers that are created are dropped - // the UniqueRc still stays valid. - weak: Cell::new(1), - value, - })) - .into(), - phantom: PhantomData, - } - } - - /// Creates a new weak reference to the `UniqueRc` - /// - /// Attempting to upgrade this weak reference will fail before the `UniqueRc` has been converted - /// to a [`Rc`] using [`UniqueRc::into_rc`]. - #[unstable(feature = "unique_rc_arc", issue = "112566")] - pub fn downgrade(this: &Self) -> Weak { - // SAFETY: This pointer was allocated at creation time and we guarantee that we only have - // one strong reference before converting to a regular Rc. - unsafe { - this.ptr.as_ref().inc_weak(); - } - Weak { ptr: this.ptr, alloc: Global } - } - - /// Converts the `UniqueRc` into a regular [`Rc`] - /// - /// This consumes the `UniqueRc` and returns a regular [`Rc`] that contains the `value` that - /// is passed to `into_rc`. - /// - /// Any weak references created before this method is called can now be upgraded to strong - /// references. - #[unstable(feature = "unique_rc_arc", issue = "112566")] - pub fn into_rc(this: Self) -> Rc { - let mut this = ManuallyDrop::new(this); - // SAFETY: This pointer was allocated at creation time so we know it is valid. - unsafe { - // Convert our weak reference into a strong reference - this.ptr.as_mut().strong.set(1); - Rc::from_inner(this.ptr) - } - } -} - -#[unstable(feature = "unique_rc_arc", issue = "112566")] -impl Deref for UniqueRc { - type Target = T; - - fn deref(&self) -> &T { - // SAFETY: This pointer was allocated at creation time so we know it is valid. - unsafe { &self.ptr.as_ref().value } - } -} - -#[unstable(feature = "unique_rc_arc", issue = "112566")] -impl DerefMut for UniqueRc { - fn deref_mut(&mut self) -> &mut T { - // SAFETY: This pointer was allocated at creation time so we know it is valid. We know we - // have unique ownership and therefore it's safe to make a mutable reference because - // `UniqueRc` owns the only strong reference to itself. - unsafe { &mut (*self.ptr.as_ptr()).value } - } -} - -#[unstable(feature = "unique_rc_arc", issue = "112566")] -unsafe impl<#[may_dangle] T> Drop for UniqueRc { - fn drop(&mut self) { - unsafe { - // destroy the contained object - drop_in_place(DerefMut::deref_mut(self)); - - // remove the implicit "strong weak" pointer now that we've destroyed the contents. - self.ptr.as_ref().dec_weak(); - - if self.ptr.as_ref().weak() == 0 { - Global.deallocate(self.ptr.cast(), Layout::for_value_raw(self.ptr.as_ptr())); - } - } - } -} diff --git a/library/alloc/src/rc/tests.rs b/library/alloc/src/rc/tests.rs deleted file mode 100644 index c8a40603d9db2..0000000000000 --- a/library/alloc/src/rc/tests.rs +++ /dev/null @@ -1,616 +0,0 @@ -use super::*; - -use std::cell::RefCell; -use std::clone::Clone; - -#[test] -fn test_clone() { - let x = Rc::new(RefCell::new(5)); - let y = x.clone(); - *x.borrow_mut() = 20; - assert_eq!(*y.borrow(), 20); -} - -#[test] -fn test_simple() { - let x = Rc::new(5); - assert_eq!(*x, 5); -} - -#[test] -fn test_simple_clone() { - let x = Rc::new(5); - let y = x.clone(); - assert_eq!(*x, 5); - assert_eq!(*y, 5); -} - -#[test] -fn test_destructor() { - let x: Rc> = Rc::new(Box::new(5)); - assert_eq!(**x, 5); -} - -#[test] -fn test_live() { - let x = Rc::new(5); - let y = Rc::downgrade(&x); - assert!(y.upgrade().is_some()); -} - -#[test] -fn test_dead() { - let x = Rc::new(5); - let y = Rc::downgrade(&x); - drop(x); - assert!(y.upgrade().is_none()); -} - -#[test] -fn weak_self_cyclic() { - struct Cycle { - x: RefCell>>, - } - - let a = Rc::new(Cycle { x: RefCell::new(None) }); - let b = Rc::downgrade(&a.clone()); - *a.x.borrow_mut() = Some(b); - - // hopefully we don't double-free (or leak)... -} - -#[test] -fn is_unique() { - let x = Rc::new(3); - assert!(Rc::is_unique(&x)); - let y = x.clone(); - assert!(!Rc::is_unique(&x)); - drop(y); - assert!(Rc::is_unique(&x)); - let w = Rc::downgrade(&x); - assert!(!Rc::is_unique(&x)); - drop(w); - assert!(Rc::is_unique(&x)); -} - -#[test] -fn test_strong_count() { - let a = Rc::new(0); - assert!(Rc::strong_count(&a) == 1); - let w = Rc::downgrade(&a); - assert!(Rc::strong_count(&a) == 1); - let b = w.upgrade().expect("upgrade of live rc failed"); - assert!(Rc::strong_count(&b) == 2); - assert!(Rc::strong_count(&a) == 2); - drop(w); - drop(a); - assert!(Rc::strong_count(&b) == 1); - let c = b.clone(); - assert!(Rc::strong_count(&b) == 2); - assert!(Rc::strong_count(&c) == 2); -} - -#[test] -fn test_weak_count() { - let a = Rc::new(0); - assert!(Rc::strong_count(&a) == 1); - assert!(Rc::weak_count(&a) == 0); - let w = Rc::downgrade(&a); - assert!(Rc::strong_count(&a) == 1); - assert!(Rc::weak_count(&a) == 1); - drop(w); - assert!(Rc::strong_count(&a) == 1); - assert!(Rc::weak_count(&a) == 0); - let c = a.clone(); - assert!(Rc::strong_count(&a) == 2); - assert!(Rc::weak_count(&a) == 0); - drop(c); -} - -#[test] -fn weak_counts() { - assert_eq!(Weak::weak_count(&Weak::::new()), 0); - assert_eq!(Weak::strong_count(&Weak::::new()), 0); - - let a = Rc::new(0); - let w = Rc::downgrade(&a); - assert_eq!(Weak::strong_count(&w), 1); - assert_eq!(Weak::weak_count(&w), 1); - let w2 = w.clone(); - assert_eq!(Weak::strong_count(&w), 1); - assert_eq!(Weak::weak_count(&w), 2); - assert_eq!(Weak::strong_count(&w2), 1); - assert_eq!(Weak::weak_count(&w2), 2); - drop(w); - assert_eq!(Weak::strong_count(&w2), 1); - assert_eq!(Weak::weak_count(&w2), 1); - let a2 = a.clone(); - assert_eq!(Weak::strong_count(&w2), 2); - assert_eq!(Weak::weak_count(&w2), 1); - drop(a2); - drop(a); - assert_eq!(Weak::strong_count(&w2), 0); - assert_eq!(Weak::weak_count(&w2), 0); - drop(w2); -} - -#[test] -fn try_unwrap() { - let x = Rc::new(3); - assert_eq!(Rc::try_unwrap(x), Ok(3)); - let x = Rc::new(4); - let _y = x.clone(); - assert_eq!(Rc::try_unwrap(x), Err(Rc::new(4))); - let x = Rc::new(5); - let _w = Rc::downgrade(&x); - assert_eq!(Rc::try_unwrap(x), Ok(5)); -} - -#[test] -fn into_inner() { - let x = Rc::new(3); - assert_eq!(Rc::into_inner(x), Some(3)); - - let x = Rc::new(4); - let y = Rc::clone(&x); - assert_eq!(Rc::into_inner(x), None); - assert_eq!(Rc::into_inner(y), Some(4)); - - let x = Rc::new(5); - let _w = Rc::downgrade(&x); - assert_eq!(Rc::into_inner(x), Some(5)); -} - -#[test] -fn into_from_raw() { - let x = Rc::new(Box::new("hello")); - let y = x.clone(); - - let x_ptr = Rc::into_raw(x); - drop(y); - unsafe { - assert_eq!(**x_ptr, "hello"); - - let x = Rc::from_raw(x_ptr); - assert_eq!(**x, "hello"); - - assert_eq!(Rc::try_unwrap(x).map(|x| *x), Ok("hello")); - } -} - -#[test] -fn test_into_from_raw_unsized() { - use std::fmt::Display; - use std::string::ToString; - - let rc: Rc = Rc::from("foo"); - - let ptr = Rc::into_raw(rc.clone()); - let rc2 = unsafe { Rc::from_raw(ptr) }; - - assert_eq!(unsafe { &*ptr }, "foo"); - assert_eq!(rc, rc2); - - let rc: Rc = Rc::new(123); - - let ptr = Rc::into_raw(rc.clone()); - let rc2 = unsafe { Rc::from_raw(ptr) }; - - assert_eq!(unsafe { &*ptr }.to_string(), "123"); - assert_eq!(rc2.to_string(), "123"); -} - -#[test] -fn into_from_weak_raw() { - let x = Rc::new(Box::new("hello")); - let y = Rc::downgrade(&x); - - let y_ptr = Weak::into_raw(y); - unsafe { - assert_eq!(**y_ptr, "hello"); - - let y = Weak::from_raw(y_ptr); - let y_up = Weak::upgrade(&y).unwrap(); - assert_eq!(**y_up, "hello"); - drop(y_up); - - assert_eq!(Rc::try_unwrap(x).map(|x| *x), Ok("hello")); - } -} - -#[test] -fn test_into_from_weak_raw_unsized() { - use std::fmt::Display; - use std::string::ToString; - - let arc: Rc = Rc::from("foo"); - let weak: Weak = Rc::downgrade(&arc); - - let ptr = Weak::into_raw(weak.clone()); - let weak2 = unsafe { Weak::from_raw(ptr) }; - - assert_eq!(unsafe { &*ptr }, "foo"); - assert!(weak.ptr_eq(&weak2)); - - let arc: Rc = Rc::new(123); - let weak: Weak = Rc::downgrade(&arc); - - let ptr = Weak::into_raw(weak.clone()); - let weak2 = unsafe { Weak::from_raw(ptr) }; - - assert_eq!(unsafe { &*ptr }.to_string(), "123"); - assert!(weak.ptr_eq(&weak2)); -} - -#[test] -fn get_mut() { - let mut x = Rc::new(3); - *Rc::get_mut(&mut x).unwrap() = 4; - assert_eq!(*x, 4); - let y = x.clone(); - assert!(Rc::get_mut(&mut x).is_none()); - drop(y); - assert!(Rc::get_mut(&mut x).is_some()); - let _w = Rc::downgrade(&x); - assert!(Rc::get_mut(&mut x).is_none()); -} - -#[test] -fn test_cowrc_clone_make_unique() { - let mut cow0 = Rc::new(75); - let mut cow1 = cow0.clone(); - let mut cow2 = cow1.clone(); - - assert!(75 == *Rc::make_mut(&mut cow0)); - assert!(75 == *Rc::make_mut(&mut cow1)); - assert!(75 == *Rc::make_mut(&mut cow2)); - - *Rc::make_mut(&mut cow0) += 1; - *Rc::make_mut(&mut cow1) += 2; - *Rc::make_mut(&mut cow2) += 3; - - assert!(76 == *cow0); - assert!(77 == *cow1); - assert!(78 == *cow2); - - // none should point to the same backing memory - assert!(*cow0 != *cow1); - assert!(*cow0 != *cow2); - assert!(*cow1 != *cow2); -} - -#[test] -fn test_cowrc_clone_unique2() { - let mut cow0 = Rc::new(75); - let cow1 = cow0.clone(); - let cow2 = cow1.clone(); - - assert!(75 == *cow0); - assert!(75 == *cow1); - assert!(75 == *cow2); - - *Rc::make_mut(&mut cow0) += 1; - - assert!(76 == *cow0); - assert!(75 == *cow1); - assert!(75 == *cow2); - - // cow1 and cow2 should share the same contents - // cow0 should have a unique reference - assert!(*cow0 != *cow1); - assert!(*cow0 != *cow2); - assert!(*cow1 == *cow2); -} - -#[test] -fn test_cowrc_clone_weak() { - let mut cow0 = Rc::new(75); - let cow1_weak = Rc::downgrade(&cow0); - - assert!(75 == *cow0); - assert!(75 == *cow1_weak.upgrade().unwrap()); - - *Rc::make_mut(&mut cow0) += 1; - - assert!(76 == *cow0); - assert!(cow1_weak.upgrade().is_none()); -} - -#[test] -fn test_show() { - let foo = Rc::new(75); - assert_eq!(format!("{foo:?}"), "75"); -} - -#[test] -fn test_unsized() { - let foo: Rc<[i32]> = Rc::new([1, 2, 3]); - assert_eq!(foo, foo.clone()); -} - -#[test] -fn test_maybe_thin_unsized() { - // If/when custom thin DSTs exist, this test should be updated to use one - use std::ffi::{CStr, CString}; - - let x: Rc = Rc::from(CString::new("swordfish").unwrap().into_boxed_c_str()); - assert_eq!(format!("{x:?}"), "\"swordfish\""); - let y: Weak = Rc::downgrade(&x); - drop(x); - - // At this point, the weak points to a dropped DST - assert!(y.upgrade().is_none()); - // But we still need to be able to get the alloc layout to drop. - // CStr has no drop glue, but custom DSTs might, and need to work. - drop(y); -} - -#[test] -fn test_from_owned() { - let foo = 123; - let foo_rc = Rc::from(foo); - assert!(123 == *foo_rc); -} - -#[test] -fn test_new_weak() { - let foo: Weak = Weak::new(); - assert!(foo.upgrade().is_none()); -} - -#[test] -fn test_ptr_eq() { - let five = Rc::new(5); - let same_five = five.clone(); - let other_five = Rc::new(5); - - assert!(Rc::ptr_eq(&five, &same_five)); - assert!(!Rc::ptr_eq(&five, &other_five)); -} - -#[test] -fn test_from_str() { - let r: Rc = Rc::from("foo"); - - assert_eq!(&r[..], "foo"); -} - -#[test] -fn test_copy_from_slice() { - let s: &[u32] = &[1, 2, 3]; - let r: Rc<[u32]> = Rc::from(s); - - assert_eq!(&r[..], [1, 2, 3]); -} - -#[test] -fn test_clone_from_slice() { - #[derive(Clone, Debug, Eq, PartialEq)] - struct X(u32); - - let s: &[X] = &[X(1), X(2), X(3)]; - let r: Rc<[X]> = Rc::from(s); - - assert_eq!(&r[..], s); -} - -#[test] -#[should_panic] -fn test_clone_from_slice_panic() { - use std::string::{String, ToString}; - - struct Fail(u32, String); - - impl Clone for Fail { - fn clone(&self) -> Fail { - if self.0 == 2 { - panic!(); - } - Fail(self.0, self.1.clone()) - } - } - - let s: &[Fail] = - &[Fail(0, "foo".to_string()), Fail(1, "bar".to_string()), Fail(2, "baz".to_string())]; - - // Should panic, but not cause memory corruption - let _r: Rc<[Fail]> = Rc::from(s); -} - -#[test] -fn test_from_box() { - let b: Box = Box::new(123); - let r: Rc = Rc::from(b); - - assert_eq!(*r, 123); -} - -#[test] -fn test_from_box_str() { - use std::string::String; - - let s = String::from("foo").into_boxed_str(); - let r: Rc = Rc::from(s); - - assert_eq!(&r[..], "foo"); -} - -#[test] -fn test_from_box_slice() { - let s = vec![1, 2, 3].into_boxed_slice(); - let r: Rc<[u32]> = Rc::from(s); - - assert_eq!(&r[..], [1, 2, 3]); -} - -#[test] -fn test_from_box_trait() { - use std::fmt::Display; - use std::string::ToString; - - let b: Box = Box::new(123); - let r: Rc = Rc::from(b); - - assert_eq!(r.to_string(), "123"); -} - -#[test] -fn test_from_box_trait_zero_sized() { - use std::fmt::Debug; - - let b: Box = Box::new(()); - let r: Rc = Rc::from(b); - - assert_eq!(format!("{r:?}"), "()"); -} - -#[test] -fn test_from_vec() { - let v = vec![1, 2, 3]; - let r: Rc<[u32]> = Rc::from(v); - - assert_eq!(&r[..], [1, 2, 3]); -} - -#[test] -fn test_downcast() { - use std::any::Any; - - let r1: Rc = Rc::new(i32::MAX); - let r2: Rc = Rc::new("abc"); - - assert!(r1.clone().downcast::().is_err()); - - let r1i32 = r1.downcast::(); - assert!(r1i32.is_ok()); - assert_eq!(r1i32.unwrap(), Rc::new(i32::MAX)); - - assert!(r2.clone().downcast::().is_err()); - - let r2str = r2.downcast::<&'static str>(); - assert!(r2str.is_ok()); - assert_eq!(r2str.unwrap(), Rc::new("abc")); -} - -#[test] -fn test_array_from_slice() { - let v = vec![1, 2, 3]; - let r: Rc<[u32]> = Rc::from(v); - - let a: Result, _> = r.clone().try_into(); - assert!(a.is_ok()); - - let a: Result, _> = r.clone().try_into(); - assert!(a.is_err()); -} - -#[test] -fn test_rc_cyclic_with_zero_refs() { - struct ZeroRefs { - inner: Weak, - } - - let zero_refs = Rc::new_cyclic(|inner| { - assert_eq!(inner.strong_count(), 0); - assert!(inner.upgrade().is_none()); - ZeroRefs { inner: Weak::new() } - }); - - assert_eq!(Rc::strong_count(&zero_refs), 1); - assert_eq!(Rc::weak_count(&zero_refs), 0); - assert_eq!(zero_refs.inner.strong_count(), 0); - assert_eq!(zero_refs.inner.weak_count(), 0); -} - -#[test] -fn test_rc_cyclic_with_one_ref() { - struct OneRef { - inner: Weak, - } - - let one_ref = Rc::new_cyclic(|inner| { - assert_eq!(inner.strong_count(), 0); - assert!(inner.upgrade().is_none()); - OneRef { inner: inner.clone() } - }); - - assert_eq!(Rc::strong_count(&one_ref), 1); - assert_eq!(Rc::weak_count(&one_ref), 1); - - let one_ref2 = Weak::upgrade(&one_ref.inner).unwrap(); - assert!(Rc::ptr_eq(&one_ref, &one_ref2)); - - assert_eq!(one_ref.inner.strong_count(), 2); - assert_eq!(one_ref.inner.weak_count(), 1); -} - -#[test] -fn test_rc_cyclic_with_two_ref() { - struct TwoRefs { - inner: Weak, - inner1: Weak, - } - - let two_refs = Rc::new_cyclic(|inner| { - assert_eq!(inner.strong_count(), 0); - assert!(inner.upgrade().is_none()); - TwoRefs { inner: inner.clone(), inner1: inner.clone() } - }); - - assert_eq!(Rc::strong_count(&two_refs), 1); - assert_eq!(Rc::weak_count(&two_refs), 2); - - let two_ref3 = Weak::upgrade(&two_refs.inner).unwrap(); - assert!(Rc::ptr_eq(&two_refs, &two_ref3)); - - let two_ref2 = Weak::upgrade(&two_refs.inner1).unwrap(); - assert!(Rc::ptr_eq(&two_refs, &two_ref2)); - - assert_eq!(Rc::strong_count(&two_refs), 3); - assert_eq!(Rc::weak_count(&two_refs), 2); -} - -#[test] -fn test_unique_rc_weak() { - let rc = UniqueRc::new(42); - let weak = UniqueRc::downgrade(&rc); - assert!(weak.upgrade().is_none()); - - let _rc = UniqueRc::into_rc(rc); - assert_eq!(*weak.upgrade().unwrap(), 42); -} - -#[test] -fn test_unique_rc_drop_weak() { - let rc = UniqueRc::new(42); - let weak = UniqueRc::downgrade(&rc); - mem::drop(weak); - - let rc = UniqueRc::into_rc(rc); - assert_eq!(*rc, 42); -} - -#[test] -fn test_unique_rc_drops_contents() { - let mut dropped = false; - struct DropMe<'a>(&'a mut bool); - impl Drop for DropMe<'_> { - fn drop(&mut self) { - *self.0 = true; - } - } - { - let rc = UniqueRc::new(DropMe(&mut dropped)); - drop(rc); - } - assert!(dropped); -} - -#[test] -fn test_unique_rc_weak_clone_holding_ref() { - let mut v = UniqueRc::new(0u8); - let w = UniqueRc::downgrade(&v); - let r = &mut *v; - let _ = w.clone(); // touch weak count - *r = 123; -} diff --git a/library/alloc/src/slice.rs b/library/alloc/src/slice.rs deleted file mode 100644 index ebe6f7e7caa9b..0000000000000 --- a/library/alloc/src/slice.rs +++ /dev/null @@ -1,888 +0,0 @@ -//! Utilities for the slice primitive type. -//! -//! *[See also the slice primitive type](slice).* -//! -//! Most of the structs in this module are iterator types which can only be created -//! using a certain function. For example, `slice.iter()` yields an [`Iter`]. -//! -//! A few functions are provided to create a slice from a value reference -//! or from a raw pointer. -#![stable(feature = "rust1", since = "1.0.0")] -// Many of the usings in this module are only used in the test configuration. -// It's cleaner to just turn off the unused_imports warning than to fix them. -#![cfg_attr(test, allow(unused_imports, dead_code))] - -use core::borrow::{Borrow, BorrowMut}; -#[cfg(not(no_global_oom_handling))] -use core::cmp::Ordering::{self, Less}; -#[cfg(not(no_global_oom_handling))] -use core::mem::{self, SizedTypeProperties}; -#[cfg(not(no_global_oom_handling))] -use core::ptr; -#[cfg(not(no_global_oom_handling))] -use core::slice::sort; - -use crate::alloc::Allocator; -#[cfg(not(no_global_oom_handling))] -use crate::alloc::{self, Global}; -#[cfg(not(no_global_oom_handling))] -use crate::borrow::ToOwned; -use crate::boxed::Box; -use crate::vec::Vec; - -#[cfg(test)] -mod tests; - -#[unstable(feature = "array_chunks", issue = "74985")] -pub use core::slice::ArrayChunks; -#[unstable(feature = "array_chunks", issue = "74985")] -pub use core::slice::ArrayChunksMut; -#[unstable(feature = "array_windows", issue = "75027")] -pub use core::slice::ArrayWindows; -#[stable(feature = "inherent_ascii_escape", since = "1.60.0")] -pub use core::slice::EscapeAscii; -#[stable(feature = "slice_get_slice", since = "1.28.0")] -pub use core::slice::SliceIndex; -#[stable(feature = "from_ref", since = "1.28.0")] -pub use core::slice::{from_mut, from_ref}; -#[unstable(feature = "slice_from_ptr_range", issue = "89792")] -pub use core::slice::{from_mut_ptr_range, from_ptr_range}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::slice::{from_raw_parts, from_raw_parts_mut}; -#[unstable(feature = "slice_range", issue = "76393")] -pub use core::slice::{range, try_range}; -#[stable(feature = "slice_group_by", since = "1.77.0")] -pub use core::slice::{ChunkBy, ChunkByMut}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::slice::{Chunks, Windows}; -#[stable(feature = "chunks_exact", since = "1.31.0")] -pub use core::slice::{ChunksExact, ChunksExactMut}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::slice::{ChunksMut, Split, SplitMut}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::slice::{Iter, IterMut}; -#[stable(feature = "rchunks", since = "1.31.0")] -pub use core::slice::{RChunks, RChunksExact, RChunksExactMut, RChunksMut}; -#[stable(feature = "slice_rsplit", since = "1.27.0")] -pub use core::slice::{RSplit, RSplitMut}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::slice::{RSplitN, RSplitNMut, SplitN, SplitNMut}; -#[stable(feature = "split_inclusive", since = "1.51.0")] -pub use core::slice::{SplitInclusive, SplitInclusiveMut}; - -//////////////////////////////////////////////////////////////////////////////// -// Basic slice extension methods -//////////////////////////////////////////////////////////////////////////////// - -// HACK(japaric) needed for the implementation of `vec!` macro during testing -// N.B., see the `hack` module in this file for more details. -#[cfg(test)] -pub use hack::into_vec; - -// HACK(japaric) needed for the implementation of `Vec::clone` during testing -// N.B., see the `hack` module in this file for more details. -#[cfg(test)] -pub use hack::to_vec; - -// HACK(japaric): With cfg(test) `impl [T]` is not available, these three -// functions are actually methods that are in `impl [T]` but not in -// `core::slice::SliceExt` - we need to supply these functions for the -// `test_permutations` test -pub(crate) mod hack { - use core::alloc::Allocator; - - use crate::boxed::Box; - use crate::vec::Vec; - - // We shouldn't add inline attribute to this since this is used in - // `vec!` macro mostly and causes perf regression. See #71204 for - // discussion and perf results. - pub fn into_vec(b: Box<[T], A>) -> Vec { - unsafe { - let len = b.len(); - let (b, alloc) = Box::into_raw_with_allocator(b); - Vec::from_raw_parts_in(b as *mut T, len, len, alloc) - } - } - - #[cfg(not(no_global_oom_handling))] - #[inline] - pub fn to_vec(s: &[T], alloc: A) -> Vec { - T::to_vec(s, alloc) - } - - #[cfg(not(no_global_oom_handling))] - pub trait ConvertVec { - fn to_vec(s: &[Self], alloc: A) -> Vec - where - Self: Sized; - } - - #[cfg(not(no_global_oom_handling))] - impl ConvertVec for T { - #[inline] - default fn to_vec(s: &[Self], alloc: A) -> Vec { - struct DropGuard<'a, T, A: Allocator> { - vec: &'a mut Vec, - num_init: usize, - } - impl<'a, T, A: Allocator> Drop for DropGuard<'a, T, A> { - #[inline] - fn drop(&mut self) { - // SAFETY: - // items were marked initialized in the loop below - unsafe { - self.vec.set_len(self.num_init); - } - } - } - let mut vec = Vec::with_capacity_in(s.len(), alloc); - let mut guard = DropGuard { vec: &mut vec, num_init: 0 }; - let slots = guard.vec.spare_capacity_mut(); - // .take(slots.len()) is necessary for LLVM to remove bounds checks - // and has better codegen than zip. - for (i, b) in s.iter().enumerate().take(slots.len()) { - guard.num_init = i; - slots[i].write(b.clone()); - } - core::mem::forget(guard); - // SAFETY: - // the vec was allocated and initialized above to at least this length. - unsafe { - vec.set_len(s.len()); - } - vec - } - } - - #[cfg(not(no_global_oom_handling))] - impl ConvertVec for T { - #[inline] - fn to_vec(s: &[Self], alloc: A) -> Vec { - let mut v = Vec::with_capacity_in(s.len(), alloc); - // SAFETY: - // allocated above with the capacity of `s`, and initialize to `s.len()` in - // ptr::copy_to_non_overlapping below. - unsafe { - s.as_ptr().copy_to_nonoverlapping(v.as_mut_ptr(), s.len()); - v.set_len(s.len()); - } - v - } - } -} - -#[cfg(not(test))] -impl [T] { - /// Sorts the slice. - /// - /// This sort is stable (i.e., does not reorder equal elements) and *O*(*n* \* log(*n*)) worst-case. - /// - /// When applicable, unstable sorting is preferred because it is generally faster than stable - /// sorting and it doesn't allocate auxiliary memory. - /// See [`sort_unstable`](slice::sort_unstable). - /// - /// # Current implementation - /// - /// The current algorithm is an adaptive, iterative merge sort inspired by - /// [timsort](https://en.wikipedia.org/wiki/Timsort). - /// It is designed to be very fast in cases where the slice is nearly sorted, or consists of - /// two or more sorted sequences concatenated one after another. - /// - /// Also, it allocates temporary storage half the size of `self`, but for short slices a - /// non-allocating insertion sort is used instead. - /// - /// # Examples - /// - /// ``` - /// let mut v = [-5, 4, 1, -3, 2]; - /// - /// v.sort(); - /// assert!(v == [-5, -3, 1, 2, 4]); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[rustc_allow_incoherent_impl] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn sort(&mut self) - where - T: Ord, - { - stable_sort(self, T::lt); - } - - /// Sorts the slice with a comparator function. - /// - /// This sort is stable (i.e., does not reorder equal elements) and *O*(*n* \* log(*n*)) worst-case. - /// - /// The comparator function must define a total ordering for the elements in the slice. If - /// the ordering is not total, the order of the elements is unspecified. An order is a - /// total order if it is (for all `a`, `b` and `c`): - /// - /// * total and antisymmetric: exactly one of `a < b`, `a == b` or `a > b` is true, and - /// * transitive, `a < b` and `b < c` implies `a < c`. The same must hold for both `==` and `>`. - /// - /// For example, while [`f64`] doesn't implement [`Ord`] because `NaN != NaN`, we can use - /// `partial_cmp` as our sort function when we know the slice doesn't contain a `NaN`. - /// - /// ``` - /// let mut floats = [5f64, 4.0, 1.0, 3.0, 2.0]; - /// floats.sort_by(|a, b| a.partial_cmp(b).unwrap()); - /// assert_eq!(floats, [1.0, 2.0, 3.0, 4.0, 5.0]); - /// ``` - /// - /// When applicable, unstable sorting is preferred because it is generally faster than stable - /// sorting and it doesn't allocate auxiliary memory. - /// See [`sort_unstable_by`](slice::sort_unstable_by). - /// - /// # Current implementation - /// - /// The current algorithm is an adaptive, iterative merge sort inspired by - /// [timsort](https://en.wikipedia.org/wiki/Timsort). - /// It is designed to be very fast in cases where the slice is nearly sorted, or consists of - /// two or more sorted sequences concatenated one after another. - /// - /// Also, it allocates temporary storage half the size of `self`, but for short slices a - /// non-allocating insertion sort is used instead. - /// - /// # Examples - /// - /// ``` - /// let mut v = [5, 4, 1, 3, 2]; - /// v.sort_by(|a, b| a.cmp(b)); - /// assert!(v == [1, 2, 3, 4, 5]); - /// - /// // reverse sorting - /// v.sort_by(|a, b| b.cmp(a)); - /// assert!(v == [5, 4, 3, 2, 1]); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[rustc_allow_incoherent_impl] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn sort_by(&mut self, mut compare: F) - where - F: FnMut(&T, &T) -> Ordering, - { - stable_sort(self, |a, b| compare(a, b) == Less); - } - - /// Sorts the slice with a key extraction function. - /// - /// This sort is stable (i.e., does not reorder equal elements) and *O*(*m* \* *n* \* log(*n*)) - /// worst-case, where the key function is *O*(*m*). - /// - /// For expensive key functions (e.g. functions that are not simple property accesses or - /// basic operations), [`sort_by_cached_key`](slice::sort_by_cached_key) is likely to be - /// significantly faster, as it does not recompute element keys. - /// - /// When applicable, unstable sorting is preferred because it is generally faster than stable - /// sorting and it doesn't allocate auxiliary memory. - /// See [`sort_unstable_by_key`](slice::sort_unstable_by_key). - /// - /// # Current implementation - /// - /// The current algorithm is an adaptive, iterative merge sort inspired by - /// [timsort](https://en.wikipedia.org/wiki/Timsort). - /// It is designed to be very fast in cases where the slice is nearly sorted, or consists of - /// two or more sorted sequences concatenated one after another. - /// - /// Also, it allocates temporary storage half the size of `self`, but for short slices a - /// non-allocating insertion sort is used instead. - /// - /// # Examples - /// - /// ``` - /// let mut v = [-5i32, 4, 1, -3, 2]; - /// - /// v.sort_by_key(|k| k.abs()); - /// assert!(v == [1, 2, -3, 4, -5]); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[rustc_allow_incoherent_impl] - #[stable(feature = "slice_sort_by_key", since = "1.7.0")] - #[inline] - pub fn sort_by_key(&mut self, mut f: F) - where - F: FnMut(&T) -> K, - K: Ord, - { - stable_sort(self, |a, b| f(a).lt(&f(b))); - } - - /// Sorts the slice with a key extraction function. - /// - /// During sorting, the key function is called at most once per element, by using - /// temporary storage to remember the results of key evaluation. - /// The order of calls to the key function is unspecified and may change in future versions - /// of the standard library. - /// - /// This sort is stable (i.e., does not reorder equal elements) and *O*(*m* \* *n* + *n* \* log(*n*)) - /// worst-case, where the key function is *O*(*m*). - /// - /// For simple key functions (e.g., functions that are property accesses or - /// basic operations), [`sort_by_key`](slice::sort_by_key) is likely to be - /// faster. - /// - /// # Current implementation - /// - /// The current algorithm is based on [pattern-defeating quicksort][pdqsort] by Orson Peters, - /// which combines the fast average case of randomized quicksort with the fast worst case of - /// heapsort, while achieving linear time on slices with certain patterns. It uses some - /// randomization to avoid degenerate cases, but with a fixed seed to always provide - /// deterministic behavior. - /// - /// In the worst case, the algorithm allocates temporary storage in a `Vec<(K, usize)>` the - /// length of the slice. - /// - /// # Examples - /// - /// ``` - /// let mut v = [-5i32, 4, 32, -3, 2]; - /// - /// v.sort_by_cached_key(|k| k.to_string()); - /// assert!(v == [-3, -5, 2, 32, 4]); - /// ``` - /// - /// [pdqsort]: https://github.com/orlp/pdqsort - #[cfg(not(no_global_oom_handling))] - #[rustc_allow_incoherent_impl] - #[stable(feature = "slice_sort_by_cached_key", since = "1.34.0")] - #[inline] - pub fn sort_by_cached_key(&mut self, f: F) - where - F: FnMut(&T) -> K, - K: Ord, - { - // Helper macro for indexing our vector by the smallest possible type, to reduce allocation. - macro_rules! sort_by_key { - ($t:ty, $slice:ident, $f:ident) => {{ - let mut indices: Vec<_> = - $slice.iter().map($f).enumerate().map(|(i, k)| (k, i as $t)).collect(); - // The elements of `indices` are unique, as they are indexed, so any sort will be - // stable with respect to the original slice. We use `sort_unstable` here because - // it requires less memory allocation. - indices.sort_unstable(); - for i in 0..$slice.len() { - let mut index = indices[i].1; - while (index as usize) < i { - index = indices[index as usize].1; - } - indices[i].1 = index; - $slice.swap(i, index as usize); - } - }}; - } - - let sz_u8 = mem::size_of::<(K, u8)>(); - let sz_u16 = mem::size_of::<(K, u16)>(); - let sz_u32 = mem::size_of::<(K, u32)>(); - let sz_usize = mem::size_of::<(K, usize)>(); - - let len = self.len(); - if len < 2 { - return; - } - if sz_u8 < sz_u16 && len <= (u8::MAX as usize) { - return sort_by_key!(u8, self, f); - } - if sz_u16 < sz_u32 && len <= (u16::MAX as usize) { - return sort_by_key!(u16, self, f); - } - if sz_u32 < sz_usize && len <= (u32::MAX as usize) { - return sort_by_key!(u32, self, f); - } - sort_by_key!(usize, self, f) - } - - /// Copies `self` into a new `Vec`. - /// - /// # Examples - /// - /// ``` - /// let s = [10, 40, 30]; - /// let x = s.to_vec(); - /// // Here, `s` and `x` can be modified independently. - /// ``` - #[cfg(not(no_global_oom_handling))] - #[rustc_allow_incoherent_impl] - #[rustc_conversion_suggestion] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn to_vec(&self) -> Vec - where - T: Clone, - { - self.to_vec_in(Global) - } - - /// Copies `self` into a new `Vec` with an allocator. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// - /// use std::alloc::System; - /// - /// let s = [10, 40, 30]; - /// let x = s.to_vec_in(System); - /// // Here, `s` and `x` can be modified independently. - /// ``` - #[cfg(not(no_global_oom_handling))] - #[rustc_allow_incoherent_impl] - #[inline] - #[unstable(feature = "allocator_api", issue = "32838")] - pub fn to_vec_in(&self, alloc: A) -> Vec - where - T: Clone, - { - // N.B., see the `hack` module in this file for more details. - hack::to_vec(self, alloc) - } - - /// Converts `self` into a vector without clones or allocation. - /// - /// The resulting vector can be converted back into a box via - /// `Vec`'s `into_boxed_slice` method. - /// - /// # Examples - /// - /// ``` - /// let s: Box<[i32]> = Box::new([10, 40, 30]); - /// let x = s.into_vec(); - /// // `s` cannot be used anymore because it has been converted into `x`. - /// - /// assert_eq!(x, vec![10, 40, 30]); - /// ``` - #[rustc_allow_incoherent_impl] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn into_vec(self: Box) -> Vec { - // N.B., see the `hack` module in this file for more details. - hack::into_vec(self) - } - - /// Creates a vector by copying a slice `n` times. - /// - /// # Panics - /// - /// This function will panic if the capacity would overflow. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// assert_eq!([1, 2].repeat(3), vec![1, 2, 1, 2, 1, 2]); - /// ``` - /// - /// A panic upon overflow: - /// - /// ```should_panic - /// // this will panic at runtime - /// b"0123456789abcdef".repeat(usize::MAX); - /// ``` - #[rustc_allow_incoherent_impl] - #[cfg(not(no_global_oom_handling))] - #[stable(feature = "repeat_generic_slice", since = "1.40.0")] - pub fn repeat(&self, n: usize) -> Vec - where - T: Copy, - { - if n == 0 { - return Vec::new(); - } - - // If `n` is larger than zero, it can be split as - // `n = 2^expn + rem (2^expn > rem, expn >= 0, rem >= 0)`. - // `2^expn` is the number represented by the leftmost '1' bit of `n`, - // and `rem` is the remaining part of `n`. - - // Using `Vec` to access `set_len()`. - let capacity = self.len().checked_mul(n).expect("capacity overflow"); - let mut buf = Vec::with_capacity(capacity); - - // `2^expn` repetition is done by doubling `buf` `expn`-times. - buf.extend(self); - { - let mut m = n >> 1; - // If `m > 0`, there are remaining bits up to the leftmost '1'. - while m > 0 { - // `buf.extend(buf)`: - unsafe { - ptr::copy_nonoverlapping::( - buf.as_ptr(), - (buf.as_mut_ptr()).add(buf.len()), - buf.len(), - ); - // `buf` has capacity of `self.len() * n`. - let buf_len = buf.len(); - buf.set_len(buf_len * 2); - } - - m >>= 1; - } - } - - // `rem` (`= n - 2^expn`) repetition is done by copying - // first `rem` repetitions from `buf` itself. - let rem_len = capacity - buf.len(); // `self.len() * rem` - if rem_len > 0 { - // `buf.extend(buf[0 .. rem_len])`: - unsafe { - // This is non-overlapping since `2^expn > rem`. - ptr::copy_nonoverlapping::( - buf.as_ptr(), - (buf.as_mut_ptr()).add(buf.len()), - rem_len, - ); - // `buf.len() + rem_len` equals to `buf.capacity()` (`= self.len() * n`). - buf.set_len(capacity); - } - } - buf - } - - /// Flattens a slice of `T` into a single value `Self::Output`. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(["hello", "world"].concat(), "helloworld"); - /// assert_eq!([[1, 2], [3, 4]].concat(), [1, 2, 3, 4]); - /// ``` - #[rustc_allow_incoherent_impl] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn concat(&self) -> >::Output - where - Self: Concat, - { - Concat::concat(self) - } - - /// Flattens a slice of `T` into a single value `Self::Output`, placing a - /// given separator between each. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(["hello", "world"].join(" "), "hello world"); - /// assert_eq!([[1, 2], [3, 4]].join(&0), [1, 2, 0, 3, 4]); - /// assert_eq!([[1, 2], [3, 4]].join(&[0, 0][..]), [1, 2, 0, 0, 3, 4]); - /// ``` - #[rustc_allow_incoherent_impl] - #[stable(feature = "rename_connect_to_join", since = "1.3.0")] - pub fn join(&self, sep: Separator) -> >::Output - where - Self: Join, - { - Join::join(self, sep) - } - - /// Flattens a slice of `T` into a single value `Self::Output`, placing a - /// given separator between each. - /// - /// # Examples - /// - /// ``` - /// # #![allow(deprecated)] - /// assert_eq!(["hello", "world"].connect(" "), "hello world"); - /// assert_eq!([[1, 2], [3, 4]].connect(&0), [1, 2, 0, 3, 4]); - /// ``` - #[rustc_allow_incoherent_impl] - #[stable(feature = "rust1", since = "1.0.0")] - #[deprecated(since = "1.3.0", note = "renamed to join", suggestion = "join")] - pub fn connect(&self, sep: Separator) -> >::Output - where - Self: Join, - { - Join::join(self, sep) - } -} - -#[cfg(not(test))] -impl [u8] { - /// Returns a vector containing a copy of this slice where each byte - /// is mapped to its ASCII upper case equivalent. - /// - /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', - /// but non-ASCII letters are unchanged. - /// - /// To uppercase the value in-place, use [`make_ascii_uppercase`]. - /// - /// [`make_ascii_uppercase`]: slice::make_ascii_uppercase - #[cfg(not(no_global_oom_handling))] - #[rustc_allow_incoherent_impl] - #[must_use = "this returns the uppercase bytes as a new Vec, \ - without modifying the original"] - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[inline] - pub fn to_ascii_uppercase(&self) -> Vec { - let mut me = self.to_vec(); - me.make_ascii_uppercase(); - me - } - - /// Returns a vector containing a copy of this slice where each byte - /// is mapped to its ASCII lower case equivalent. - /// - /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', - /// but non-ASCII letters are unchanged. - /// - /// To lowercase the value in-place, use [`make_ascii_lowercase`]. - /// - /// [`make_ascii_lowercase`]: slice::make_ascii_lowercase - #[cfg(not(no_global_oom_handling))] - #[rustc_allow_incoherent_impl] - #[must_use = "this returns the lowercase bytes as a new Vec, \ - without modifying the original"] - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[inline] - pub fn to_ascii_lowercase(&self) -> Vec { - let mut me = self.to_vec(); - me.make_ascii_lowercase(); - me - } -} - -//////////////////////////////////////////////////////////////////////////////// -// Extension traits for slices over specific kinds of data -//////////////////////////////////////////////////////////////////////////////// - -/// Helper trait for [`[T]::concat`](slice::concat). -/// -/// Note: the `Item` type parameter is not used in this trait, -/// but it allows impls to be more generic. -/// Without it, we get this error: -/// -/// ```error -/// error[E0207]: the type parameter `T` is not constrained by the impl trait, self type, or predica -/// --> library/alloc/src/slice.rs:608:6 -/// | -/// 608 | impl> Concat for [V] { -/// | ^ unconstrained type parameter -/// ``` -/// -/// This is because there could exist `V` types with multiple `Borrow<[_]>` impls, -/// such that multiple `T` types would apply: -/// -/// ``` -/// # #[allow(dead_code)] -/// pub struct Foo(Vec, Vec); -/// -/// impl std::borrow::Borrow<[u32]> for Foo { -/// fn borrow(&self) -> &[u32] { &self.0 } -/// } -/// -/// impl std::borrow::Borrow<[String]> for Foo { -/// fn borrow(&self) -> &[String] { &self.1 } -/// } -/// ``` -#[unstable(feature = "slice_concat_trait", issue = "27747")] -pub trait Concat { - #[unstable(feature = "slice_concat_trait", issue = "27747")] - /// The resulting type after concatenation - type Output; - - /// Implementation of [`[T]::concat`](slice::concat) - #[unstable(feature = "slice_concat_trait", issue = "27747")] - fn concat(slice: &Self) -> Self::Output; -} - -/// Helper trait for [`[T]::join`](slice::join) -#[unstable(feature = "slice_concat_trait", issue = "27747")] -pub trait Join { - #[unstable(feature = "slice_concat_trait", issue = "27747")] - /// The resulting type after concatenation - type Output; - - /// Implementation of [`[T]::join`](slice::join) - #[unstable(feature = "slice_concat_trait", issue = "27747")] - fn join(slice: &Self, sep: Separator) -> Self::Output; -} - -#[cfg(not(no_global_oom_handling))] -#[unstable(feature = "slice_concat_ext", issue = "27747")] -impl> Concat for [V] { - type Output = Vec; - - fn concat(slice: &Self) -> Vec { - let size = slice.iter().map(|slice| slice.borrow().len()).sum(); - let mut result = Vec::with_capacity(size); - for v in slice { - result.extend_from_slice(v.borrow()) - } - result - } -} - -#[cfg(not(no_global_oom_handling))] -#[unstable(feature = "slice_concat_ext", issue = "27747")] -impl> Join<&T> for [V] { - type Output = Vec; - - fn join(slice: &Self, sep: &T) -> Vec { - let mut iter = slice.iter(); - let first = match iter.next() { - Some(first) => first, - None => return vec![], - }; - let size = slice.iter().map(|v| v.borrow().len()).sum::() + slice.len() - 1; - let mut result = Vec::with_capacity(size); - result.extend_from_slice(first.borrow()); - - for v in iter { - result.push(sep.clone()); - result.extend_from_slice(v.borrow()) - } - result - } -} - -#[cfg(not(no_global_oom_handling))] -#[unstable(feature = "slice_concat_ext", issue = "27747")] -impl> Join<&[T]> for [V] { - type Output = Vec; - - fn join(slice: &Self, sep: &[T]) -> Vec { - let mut iter = slice.iter(); - let first = match iter.next() { - Some(first) => first, - None => return vec![], - }; - let size = - slice.iter().map(|v| v.borrow().len()).sum::() + sep.len() * (slice.len() - 1); - let mut result = Vec::with_capacity(size); - result.extend_from_slice(first.borrow()); - - for v in iter { - result.extend_from_slice(sep); - result.extend_from_slice(v.borrow()) - } - result - } -} - -//////////////////////////////////////////////////////////////////////////////// -// Standard trait implementations for slices -//////////////////////////////////////////////////////////////////////////////// - -#[stable(feature = "rust1", since = "1.0.0")] -impl Borrow<[T]> for Vec { - fn borrow(&self) -> &[T] { - &self[..] - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl BorrowMut<[T]> for Vec { - fn borrow_mut(&mut self) -> &mut [T] { - &mut self[..] - } -} - -// Specializable trait for implementing ToOwned::clone_into. This is -// public in the crate and has the Allocator parameter so that -// vec::clone_from use it too. -#[cfg(not(no_global_oom_handling))] -pub(crate) trait SpecCloneIntoVec { - fn clone_into(&self, target: &mut Vec); -} - -#[cfg(not(no_global_oom_handling))] -impl SpecCloneIntoVec for [T] { - default fn clone_into(&self, target: &mut Vec) { - // drop anything in target that will not be overwritten - target.truncate(self.len()); - - // target.len <= self.len due to the truncate above, so the - // slices here are always in-bounds. - let (init, tail) = self.split_at(target.len()); - - // reuse the contained values' allocations/resources. - target.clone_from_slice(init); - target.extend_from_slice(tail); - } -} - -#[cfg(not(no_global_oom_handling))] -impl SpecCloneIntoVec for [T] { - fn clone_into(&self, target: &mut Vec) { - target.clear(); - target.extend_from_slice(self); - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl ToOwned for [T] { - type Owned = Vec; - #[cfg(not(test))] - fn to_owned(&self) -> Vec { - self.to_vec() - } - - #[cfg(test)] - fn to_owned(&self) -> Vec { - hack::to_vec(self, Global) - } - - fn clone_into(&self, target: &mut Vec) { - SpecCloneIntoVec::clone_into(self, target); - } -} - -//////////////////////////////////////////////////////////////////////////////// -// Sorting -//////////////////////////////////////////////////////////////////////////////// - -#[inline] -#[cfg(not(no_global_oom_handling))] -fn stable_sort(v: &mut [T], mut is_less: F) -where - F: FnMut(&T, &T) -> bool, -{ - if T::IS_ZST { - // Sorting has no meaningful behavior on zero-sized types. Do nothing. - return; - } - - let elem_alloc_fn = |len: usize| -> *mut T { - // SAFETY: Creating the layout is safe as long as merge_sort never calls this with len > - // v.len(). Alloc in general will only be used as 'shadow-region' to store temporary swap - // elements. - unsafe { alloc::alloc(alloc::Layout::array::(len).unwrap_unchecked()) as *mut T } - }; - - let elem_dealloc_fn = |buf_ptr: *mut T, len: usize| { - // SAFETY: Creating the layout is safe as long as merge_sort never calls this with len > - // v.len(). The caller must ensure that buf_ptr was created by elem_alloc_fn with the same - // len. - unsafe { - alloc::dealloc(buf_ptr as *mut u8, alloc::Layout::array::(len).unwrap_unchecked()); - } - }; - - let run_alloc_fn = |len: usize| -> *mut sort::TimSortRun { - // SAFETY: Creating the layout is safe as long as merge_sort never calls this with an - // obscene length or 0. - unsafe { - alloc::alloc(alloc::Layout::array::(len).unwrap_unchecked()) - as *mut sort::TimSortRun - } - }; - - let run_dealloc_fn = |buf_ptr: *mut sort::TimSortRun, len: usize| { - // SAFETY: The caller must ensure that buf_ptr was created by elem_alloc_fn with the same - // len. - unsafe { - alloc::dealloc( - buf_ptr as *mut u8, - alloc::Layout::array::(len).unwrap_unchecked(), - ); - } - }; - - sort::merge_sort(v, &mut is_less, elem_alloc_fn, elem_dealloc_fn, run_alloc_fn, run_dealloc_fn); -} diff --git a/library/alloc/src/slice/tests.rs b/library/alloc/src/slice/tests.rs deleted file mode 100644 index 54bc4e77b16f0..0000000000000 --- a/library/alloc/src/slice/tests.rs +++ /dev/null @@ -1,360 +0,0 @@ -use crate::borrow::ToOwned; -use crate::rc::Rc; -use crate::string::ToString; -use crate::test_helpers::test_rng; -use crate::vec::Vec; - -use core::cell::Cell; -use core::cmp::Ordering::{self, Equal, Greater, Less}; -use core::convert::identity; -use core::fmt; -use core::mem; -use core::sync::atomic::{AtomicUsize, Ordering::Relaxed}; -use rand::{distributions::Standard, prelude::*, Rng, RngCore}; -use std::panic; - -macro_rules! do_test { - ($input:ident, $func:ident) => { - let len = $input.len(); - - // Work out the total number of comparisons required to sort - // this array... - let mut count = 0usize; - $input.to_owned().$func(|a, b| { - count += 1; - a.cmp(b) - }); - - // ... and then panic on each and every single one. - for panic_countdown in 0..count { - // Refresh the counters. - VERSIONS.store(0, Relaxed); - for i in 0..len { - DROP_COUNTS[i].store(0, Relaxed); - } - - let v = $input.to_owned(); - let _ = std::panic::catch_unwind(move || { - let mut v = v; - let mut panic_countdown = panic_countdown; - v.$func(|a, b| { - if panic_countdown == 0 { - SILENCE_PANIC.with(|s| s.set(true)); - panic!(); - } - panic_countdown -= 1; - a.cmp(b) - }) - }); - - // Check that the number of things dropped is exactly - // what we expect (i.e., the contents of `v`). - for (i, c) in DROP_COUNTS.iter().enumerate().take(len) { - let count = c.load(Relaxed); - assert!(count == 1, "found drop count == {} for i == {}, len == {}", count, i, len); - } - - // Check that the most recent versions of values were dropped. - assert_eq!(VERSIONS.load(Relaxed), 0); - } - }; -} - -const MAX_LEN: usize = 80; - -static DROP_COUNTS: [AtomicUsize; MAX_LEN] = [ - // FIXME(RFC 1109): AtomicUsize is not Copy. - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), - AtomicUsize::new(0), -]; - -static VERSIONS: AtomicUsize = AtomicUsize::new(0); - -#[derive(Clone, Eq)] -struct DropCounter { - x: u32, - id: usize, - version: Cell, -} - -impl PartialEq for DropCounter { - fn eq(&self, other: &Self) -> bool { - self.partial_cmp(other) == Some(Ordering::Equal) - } -} - -impl PartialOrd for DropCounter { - fn partial_cmp(&self, other: &Self) -> Option { - self.version.set(self.version.get() + 1); - other.version.set(other.version.get() + 1); - VERSIONS.fetch_add(2, Relaxed); - self.x.partial_cmp(&other.x) - } -} - -impl Ord for DropCounter { - fn cmp(&self, other: &Self) -> Ordering { - self.partial_cmp(other).unwrap() - } -} - -impl Drop for DropCounter { - fn drop(&mut self) { - DROP_COUNTS[self.id].fetch_add(1, Relaxed); - VERSIONS.fetch_sub(self.version.get(), Relaxed); - } -} - -std::thread_local!(static SILENCE_PANIC: Cell = Cell::new(false)); - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] // no threads -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn panic_safe() { - panic::update_hook(move |prev, info| { - if !SILENCE_PANIC.with(|s| s.get()) { - prev(info); - } - }); - - let mut rng = test_rng(); - - // Miri is too slow (but still need to `chain` to make the types match) - let lens = if cfg!(miri) { (1..10).chain(0..0) } else { (1..20).chain(70..MAX_LEN) }; - let moduli: &[u32] = if cfg!(miri) { &[5] } else { &[5, 20, 50] }; - - for len in lens { - for &modulus in moduli { - for &has_runs in &[false, true] { - let mut input = (0..len) - .map(|id| DropCounter { - x: rng.next_u32() % modulus, - id: id, - version: Cell::new(0), - }) - .collect::>(); - - if has_runs { - for c in &mut input { - c.x = c.id as u32; - } - - for _ in 0..5 { - let a = rng.gen::() % len; - let b = rng.gen::() % len; - if a < b { - input[a..b].reverse(); - } else { - input.swap(a, b); - } - } - } - - do_test!(input, sort_by); - do_test!(input, sort_unstable_by); - } - } - } - - // Set default panic hook again. - drop(panic::take_hook()); -} - -#[test] -#[cfg_attr(miri, ignore)] // Miri is too slow -fn test_sort() { - let mut rng = test_rng(); - - for len in (2..25).chain(500..510) { - for &modulus in &[5, 10, 100, 1000] { - for _ in 0..10 { - let orig: Vec<_> = (&mut rng) - .sample_iter::(&Standard) - .map(|x| x % modulus) - .take(len) - .collect(); - - // Sort in default order. - let mut v = orig.clone(); - v.sort(); - assert!(v.windows(2).all(|w| w[0] <= w[1])); - - // Sort in ascending order. - let mut v = orig.clone(); - v.sort_by(|a, b| a.cmp(b)); - assert!(v.windows(2).all(|w| w[0] <= w[1])); - - // Sort in descending order. - let mut v = orig.clone(); - v.sort_by(|a, b| b.cmp(a)); - assert!(v.windows(2).all(|w| w[0] >= w[1])); - - // Sort in lexicographic order. - let mut v1 = orig.clone(); - let mut v2 = orig.clone(); - v1.sort_by_key(|x| x.to_string()); - v2.sort_by_cached_key(|x| x.to_string()); - assert!(v1.windows(2).all(|w| w[0].to_string() <= w[1].to_string())); - assert!(v1 == v2); - - // Sort with many pre-sorted runs. - let mut v = orig.clone(); - v.sort(); - v.reverse(); - for _ in 0..5 { - let a = rng.gen::() % len; - let b = rng.gen::() % len; - if a < b { - v[a..b].reverse(); - } else { - v.swap(a, b); - } - } - v.sort(); - assert!(v.windows(2).all(|w| w[0] <= w[1])); - } - } - } - - // Sort using a completely random comparison function. - // This will reorder the elements *somehow*, but won't panic. - let mut v = [0; 500]; - for i in 0..v.len() { - v[i] = i as i32; - } - v.sort_by(|_, _| *[Less, Equal, Greater].choose(&mut rng).unwrap()); - v.sort(); - for i in 0..v.len() { - assert_eq!(v[i], i as i32); - } - - // Should not panic. - [0i32; 0].sort(); - [(); 10].sort(); - [(); 100].sort(); - - let mut v = [0xDEADBEEFu64]; - v.sort(); - assert!(v == [0xDEADBEEF]); -} - -#[test] -fn test_sort_stability() { - // Miri is too slow - let large_range = if cfg!(miri) { 0..0 } else { 500..510 }; - let rounds = if cfg!(miri) { 1 } else { 10 }; - - let mut rng = test_rng(); - for len in (2..25).chain(large_range) { - for _ in 0..rounds { - let mut counts = [0; 10]; - - // create a vector like [(6, 1), (5, 1), (6, 2), ...], - // where the first item of each tuple is random, but - // the second item represents which occurrence of that - // number this element is, i.e., the second elements - // will occur in sorted order. - let orig: Vec<_> = (0..len) - .map(|_| { - let n = rng.gen::() % 10; - counts[n] += 1; - (n, counts[n]) - }) - .collect(); - - let mut v = orig.clone(); - // Only sort on the first element, so an unstable sort - // may mix up the counts. - v.sort_by(|&(a, _), &(b, _)| a.cmp(&b)); - - // This comparison includes the count (the second item - // of the tuple), so elements with equal first items - // will need to be ordered with increasing - // counts... i.e., exactly asserting that this sort is - // stable. - assert!(v.windows(2).all(|w| w[0] <= w[1])); - - let mut v = orig.clone(); - v.sort_by_cached_key(|&(x, _)| x); - assert!(v.windows(2).all(|w| w[0] <= w[1])); - } - } -} diff --git a/library/alloc/src/str.rs b/library/alloc/src/str.rs deleted file mode 100644 index 3e23612d0c13c..0000000000000 --- a/library/alloc/src/str.rs +++ /dev/null @@ -1,664 +0,0 @@ -//! Utilities for the `str` primitive type. -//! -//! *[See also the `str` primitive type](str).* - -#![stable(feature = "rust1", since = "1.0.0")] -// Many of the usings in this module are only used in the test configuration. -// It's cleaner to just turn off the unused_imports warning than to fix them. -#![allow(unused_imports)] - -use core::borrow::{Borrow, BorrowMut}; -use core::iter::FusedIterator; -use core::mem; -use core::ptr; -use core::str::pattern::{DoubleEndedSearcher, Pattern, ReverseSearcher, Searcher}; -use core::unicode::conversions; - -use crate::borrow::ToOwned; -use crate::boxed::Box; -use crate::slice::{Concat, Join, SliceIndex}; -use crate::string::String; -use crate::vec::Vec; - -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::str::pattern; -#[stable(feature = "encode_utf16", since = "1.8.0")] -pub use core::str::EncodeUtf16; -#[stable(feature = "split_ascii_whitespace", since = "1.34.0")] -pub use core::str::SplitAsciiWhitespace; -#[stable(feature = "split_inclusive", since = "1.51.0")] -pub use core::str::SplitInclusive; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::str::SplitWhitespace; -#[unstable(feature = "str_from_raw_parts", issue = "119206")] -pub use core::str::{from_raw_parts, from_raw_parts_mut}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::str::{from_utf8, from_utf8_mut, Bytes, CharIndices, Chars}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::str::{from_utf8_unchecked, from_utf8_unchecked_mut, ParseBoolError}; -#[stable(feature = "str_escape", since = "1.34.0")] -pub use core::str::{EscapeDebug, EscapeDefault, EscapeUnicode}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::str::{FromStr, Utf8Error}; -#[allow(deprecated)] -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::str::{Lines, LinesAny}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::str::{MatchIndices, RMatchIndices}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::str::{Matches, RMatches}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::str::{RSplit, Split}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::str::{RSplitN, SplitN}; -#[stable(feature = "rust1", since = "1.0.0")] -pub use core::str::{RSplitTerminator, SplitTerminator}; -#[stable(feature = "utf8_chunks", since = "1.79.0")] -pub use core::str::{Utf8Chunk, Utf8Chunks}; - -/// Note: `str` in `Concat` is not meaningful here. -/// This type parameter of the trait only exists to enable another impl. -#[cfg(not(no_global_oom_handling))] -#[unstable(feature = "slice_concat_ext", issue = "27747")] -impl> Concat for [S] { - type Output = String; - - fn concat(slice: &Self) -> String { - Join::join(slice, "") - } -} - -#[cfg(not(no_global_oom_handling))] -#[unstable(feature = "slice_concat_ext", issue = "27747")] -impl> Join<&str> for [S] { - type Output = String; - - fn join(slice: &Self, sep: &str) -> String { - unsafe { String::from_utf8_unchecked(join_generic_copy(slice, sep.as_bytes())) } - } -} - -#[cfg(not(no_global_oom_handling))] -macro_rules! specialize_for_lengths { - ($separator:expr, $target:expr, $iter:expr; $($num:expr),*) => {{ - let mut target = $target; - let iter = $iter; - let sep_bytes = $separator; - match $separator.len() { - $( - // loops with hardcoded sizes run much faster - // specialize the cases with small separator lengths - $num => { - for s in iter { - copy_slice_and_advance!(target, sep_bytes); - let content_bytes = s.borrow().as_ref(); - copy_slice_and_advance!(target, content_bytes); - } - }, - )* - _ => { - // arbitrary non-zero size fallback - for s in iter { - copy_slice_and_advance!(target, sep_bytes); - let content_bytes = s.borrow().as_ref(); - copy_slice_and_advance!(target, content_bytes); - } - } - } - target - }} -} - -#[cfg(not(no_global_oom_handling))] -macro_rules! copy_slice_and_advance { - ($target:expr, $bytes:expr) => { - let len = $bytes.len(); - let (head, tail) = { $target }.split_at_mut(len); - head.copy_from_slice($bytes); - $target = tail; - }; -} - -// Optimized join implementation that works for both Vec (T: Copy) and String's inner vec -// Currently (2018-05-13) there is a bug with type inference and specialization (see issue #36262) -// For this reason SliceConcat is not specialized for T: Copy and SliceConcat is the -// only user of this function. It is left in place for the time when that is fixed. -// -// the bounds for String-join are S: Borrow and for Vec-join Borrow<[T]> -// [T] and str both impl AsRef<[T]> for some T -// => s.borrow().as_ref() and we always have slices -#[cfg(not(no_global_oom_handling))] -fn join_generic_copy(slice: &[S], sep: &[T]) -> Vec -where - T: Copy, - B: AsRef<[T]> + ?Sized, - S: Borrow, -{ - let sep_len = sep.len(); - let mut iter = slice.iter(); - - // the first slice is the only one without a separator preceding it - let first = match iter.next() { - Some(first) => first, - None => return vec![], - }; - - // compute the exact total length of the joined Vec - // if the `len` calculation overflows, we'll panic - // we would have run out of memory anyway and the rest of the function requires - // the entire Vec pre-allocated for safety - let reserved_len = sep_len - .checked_mul(iter.len()) - .and_then(|n| { - slice.iter().map(|s| s.borrow().as_ref().len()).try_fold(n, usize::checked_add) - }) - .expect("attempt to join into collection with len > usize::MAX"); - - // prepare an uninitialized buffer - let mut result = Vec::with_capacity(reserved_len); - debug_assert!(result.capacity() >= reserved_len); - - result.extend_from_slice(first.borrow().as_ref()); - - unsafe { - let pos = result.len(); - let target = result.spare_capacity_mut().get_unchecked_mut(..reserved_len - pos); - - // Convert the separator and slices to slices of MaybeUninit - // to simplify implementation in specialize_for_lengths - let sep_uninit = core::slice::from_raw_parts(sep.as_ptr().cast(), sep.len()); - let iter_uninit = iter.map(|it| { - let it = it.borrow().as_ref(); - core::slice::from_raw_parts(it.as_ptr().cast(), it.len()) - }); - - // copy separator and slices over without bounds checks - // generate loops with hardcoded offsets for small separators - // massive improvements possible (~ x2) - let remain = specialize_for_lengths!(sep_uninit, target, iter_uninit; 0, 1, 2, 3, 4); - - // A weird borrow implementation may return different - // slices for the length calculation and the actual copy. - // Make sure we don't expose uninitialized bytes to the caller. - let result_len = reserved_len - remain.len(); - result.set_len(result_len); - } - result -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Borrow for String { - #[inline] - fn borrow(&self) -> &str { - &self[..] - } -} - -#[stable(feature = "string_borrow_mut", since = "1.36.0")] -impl BorrowMut for String { - #[inline] - fn borrow_mut(&mut self) -> &mut str { - &mut self[..] - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl ToOwned for str { - type Owned = String; - #[inline] - fn to_owned(&self) -> String { - unsafe { String::from_utf8_unchecked(self.as_bytes().to_owned()) } - } - - fn clone_into(&self, target: &mut String) { - let mut b = mem::take(target).into_bytes(); - self.as_bytes().clone_into(&mut b); - *target = unsafe { String::from_utf8_unchecked(b) } - } -} - -/// Methods for string slices. -#[cfg(not(test))] -impl str { - /// Converts a `Box` into a `Box<[u8]>` without copying or allocating. - /// - /// # Examples - /// - /// ``` - /// let s = "this is a string"; - /// let boxed_str = s.to_owned().into_boxed_str(); - /// let boxed_bytes = boxed_str.into_boxed_bytes(); - /// assert_eq!(*boxed_bytes, *s.as_bytes()); - /// ``` - #[rustc_allow_incoherent_impl] - #[stable(feature = "str_box_extras", since = "1.20.0")] - #[must_use = "`self` will be dropped if the result is not used"] - #[inline] - pub fn into_boxed_bytes(self: Box) -> Box<[u8]> { - self.into() - } - - /// Replaces all matches of a pattern with another string. - /// - /// `replace` creates a new [`String`], and copies the data from this string slice into it. - /// While doing so, it attempts to find matches of a pattern. If it finds any, it - /// replaces them with the replacement string slice. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let s = "this is old"; - /// - /// assert_eq!("this is new", s.replace("old", "new")); - /// assert_eq!("than an old", s.replace("is", "an")); - /// ``` - /// - /// When the pattern doesn't match, it returns this string slice as [`String`]: - /// - /// ``` - /// let s = "this is old"; - /// assert_eq!(s, s.replace("cookie monster", "little lamb")); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[rustc_allow_incoherent_impl] - #[must_use = "this returns the replaced string as a new allocation, \ - without modifying the original"] - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn replace<'a, P: Pattern<'a>>(&'a self, from: P, to: &str) -> String { - let mut result = String::new(); - let mut last_end = 0; - for (start, part) in self.match_indices(from) { - result.push_str(unsafe { self.get_unchecked(last_end..start) }); - result.push_str(to); - last_end = start + part.len(); - } - result.push_str(unsafe { self.get_unchecked(last_end..self.len()) }); - result - } - - /// Replaces first N matches of a pattern with another string. - /// - /// `replacen` creates a new [`String`], and copies the data from this string slice into it. - /// While doing so, it attempts to find matches of a pattern. If it finds any, it - /// replaces them with the replacement string slice at most `count` times. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let s = "foo foo 123 foo"; - /// assert_eq!("new new 123 foo", s.replacen("foo", "new", 2)); - /// assert_eq!("faa fao 123 foo", s.replacen('o', "a", 3)); - /// assert_eq!("foo foo new23 foo", s.replacen(char::is_numeric, "new", 1)); - /// ``` - /// - /// When the pattern doesn't match, it returns this string slice as [`String`]: - /// - /// ``` - /// let s = "this is old"; - /// assert_eq!(s, s.replacen("cookie monster", "little lamb", 10)); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[rustc_allow_incoherent_impl] - #[must_use = "this returns the replaced string as a new allocation, \ - without modifying the original"] - #[stable(feature = "str_replacen", since = "1.16.0")] - pub fn replacen<'a, P: Pattern<'a>>(&'a self, pat: P, to: &str, count: usize) -> String { - // Hope to reduce the times of re-allocation - let mut result = String::with_capacity(32); - let mut last_end = 0; - for (start, part) in self.match_indices(pat).take(count) { - result.push_str(unsafe { self.get_unchecked(last_end..start) }); - result.push_str(to); - last_end = start + part.len(); - } - result.push_str(unsafe { self.get_unchecked(last_end..self.len()) }); - result - } - - /// Returns the lowercase equivalent of this string slice, as a new [`String`]. - /// - /// 'Lowercase' is defined according to the terms of the Unicode Derived Core Property - /// `Lowercase`. - /// - /// Since some characters can expand into multiple characters when changing - /// the case, this function returns a [`String`] instead of modifying the - /// parameter in-place. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let s = "HELLO"; - /// - /// assert_eq!("hello", s.to_lowercase()); - /// ``` - /// - /// A tricky example, with sigma: - /// - /// ``` - /// let sigma = "Σ"; - /// - /// assert_eq!("σ", sigma.to_lowercase()); - /// - /// // but at the end of a word, it's ς, not σ: - /// let odysseus = "ὈΔΥΣΣΕΎΣ"; - /// - /// assert_eq!("ὀδυσσεύς", odysseus.to_lowercase()); - /// ``` - /// - /// Languages without case are not changed: - /// - /// ``` - /// let new_year = "农历新年"; - /// - /// assert_eq!(new_year, new_year.to_lowercase()); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[rustc_allow_incoherent_impl] - #[must_use = "this returns the lowercase string as a new String, \ - without modifying the original"] - #[stable(feature = "unicode_case_mapping", since = "1.2.0")] - pub fn to_lowercase(&self) -> String { - let out = convert_while_ascii(self.as_bytes(), u8::to_ascii_lowercase); - - // Safety: we know this is a valid char boundary since - // out.len() is only progressed if ascii bytes are found - let rest = unsafe { self.get_unchecked(out.len()..) }; - - // Safety: We have written only valid ASCII to our vec - let mut s = unsafe { String::from_utf8_unchecked(out) }; - - for (i, c) in rest.char_indices() { - if c == 'Σ' { - // Σ maps to σ, except at the end of a word where it maps to ς. - // This is the only conditional (contextual) but language-independent mapping - // in `SpecialCasing.txt`, - // so hard-code it rather than have a generic "condition" mechanism. - // See https://github.com/rust-lang/rust/issues/26035 - let out_len = self.len() - rest.len(); - let sigma_lowercase = map_uppercase_sigma(&self, i + out_len); - s.push(sigma_lowercase); - } else { - match conversions::to_lower(c) { - [a, '\0', _] => s.push(a), - [a, b, '\0'] => { - s.push(a); - s.push(b); - } - [a, b, c] => { - s.push(a); - s.push(b); - s.push(c); - } - } - } - } - return s; - - fn map_uppercase_sigma(from: &str, i: usize) -> char { - // See https://www.unicode.org/versions/Unicode7.0.0/ch03.pdf#G33992 - // for the definition of `Final_Sigma`. - debug_assert!('Σ'.len_utf8() == 2); - let is_word_final = case_ignorable_then_cased(from[..i].chars().rev()) - && !case_ignorable_then_cased(from[i + 2..].chars()); - if is_word_final { 'ς' } else { 'σ' } - } - - fn case_ignorable_then_cased>(iter: I) -> bool { - use core::unicode::{Case_Ignorable, Cased}; - match iter.skip_while(|&c| Case_Ignorable(c)).next() { - Some(c) => Cased(c), - None => false, - } - } - } - - /// Returns the uppercase equivalent of this string slice, as a new [`String`]. - /// - /// 'Uppercase' is defined according to the terms of the Unicode Derived Core Property - /// `Uppercase`. - /// - /// Since some characters can expand into multiple characters when changing - /// the case, this function returns a [`String`] instead of modifying the - /// parameter in-place. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let s = "hello"; - /// - /// assert_eq!("HELLO", s.to_uppercase()); - /// ``` - /// - /// Scripts without case are not changed: - /// - /// ``` - /// let new_year = "农历新年"; - /// - /// assert_eq!(new_year, new_year.to_uppercase()); - /// ``` - /// - /// One character can become multiple: - /// ``` - /// let s = "tschüß"; - /// - /// assert_eq!("TSCHÜSS", s.to_uppercase()); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[rustc_allow_incoherent_impl] - #[must_use = "this returns the uppercase string as a new String, \ - without modifying the original"] - #[stable(feature = "unicode_case_mapping", since = "1.2.0")] - pub fn to_uppercase(&self) -> String { - let out = convert_while_ascii(self.as_bytes(), u8::to_ascii_uppercase); - - // Safety: we know this is a valid char boundary since - // out.len() is only progressed if ascii bytes are found - let rest = unsafe { self.get_unchecked(out.len()..) }; - - // Safety: We have written only valid ASCII to our vec - let mut s = unsafe { String::from_utf8_unchecked(out) }; - - for c in rest.chars() { - match conversions::to_upper(c) { - [a, '\0', _] => s.push(a), - [a, b, '\0'] => { - s.push(a); - s.push(b); - } - [a, b, c] => { - s.push(a); - s.push(b); - s.push(c); - } - } - } - s - } - - /// Converts a [`Box`] into a [`String`] without copying or allocating. - /// - /// # Examples - /// - /// ``` - /// let string = String::from("birthday gift"); - /// let boxed_str = string.clone().into_boxed_str(); - /// - /// assert_eq!(boxed_str.into_string(), string); - /// ``` - #[stable(feature = "box_str", since = "1.4.0")] - #[rustc_allow_incoherent_impl] - #[must_use = "`self` will be dropped if the result is not used"] - #[inline] - pub fn into_string(self: Box) -> String { - let slice = Box::<[u8]>::from(self); - unsafe { String::from_utf8_unchecked(slice.into_vec()) } - } - - /// Creates a new [`String`] by repeating a string `n` times. - /// - /// # Panics - /// - /// This function will panic if the capacity would overflow. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// assert_eq!("abc".repeat(4), String::from("abcabcabcabc")); - /// ``` - /// - /// A panic upon overflow: - /// - /// ```should_panic - /// // this will panic at runtime - /// let huge = "0123456789abcdef".repeat(usize::MAX); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[rustc_allow_incoherent_impl] - #[must_use] - #[stable(feature = "repeat_str", since = "1.16.0")] - pub fn repeat(&self, n: usize) -> String { - unsafe { String::from_utf8_unchecked(self.as_bytes().repeat(n)) } - } - - /// Returns a copy of this string where each character is mapped to its - /// ASCII upper case equivalent. - /// - /// ASCII letters 'a' to 'z' are mapped to 'A' to 'Z', - /// but non-ASCII letters are unchanged. - /// - /// To uppercase the value in-place, use [`make_ascii_uppercase`]. - /// - /// To uppercase ASCII characters in addition to non-ASCII characters, use - /// [`to_uppercase`]. - /// - /// # Examples - /// - /// ``` - /// let s = "Grüße, Jürgen ❤"; - /// - /// assert_eq!("GRüßE, JüRGEN ❤", s.to_ascii_uppercase()); - /// ``` - /// - /// [`make_ascii_uppercase`]: str::make_ascii_uppercase - /// [`to_uppercase`]: #method.to_uppercase - #[cfg(not(no_global_oom_handling))] - #[rustc_allow_incoherent_impl] - #[must_use = "to uppercase the value in-place, use `make_ascii_uppercase()`"] - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[inline] - pub fn to_ascii_uppercase(&self) -> String { - let mut s = self.to_owned(); - s.make_ascii_uppercase(); - s - } - - /// Returns a copy of this string where each character is mapped to its - /// ASCII lower case equivalent. - /// - /// ASCII letters 'A' to 'Z' are mapped to 'a' to 'z', - /// but non-ASCII letters are unchanged. - /// - /// To lowercase the value in-place, use [`make_ascii_lowercase`]. - /// - /// To lowercase ASCII characters in addition to non-ASCII characters, use - /// [`to_lowercase`]. - /// - /// # Examples - /// - /// ``` - /// let s = "Grüße, Jürgen ❤"; - /// - /// assert_eq!("grüße, jürgen ❤", s.to_ascii_lowercase()); - /// ``` - /// - /// [`make_ascii_lowercase`]: str::make_ascii_lowercase - /// [`to_lowercase`]: #method.to_lowercase - #[cfg(not(no_global_oom_handling))] - #[rustc_allow_incoherent_impl] - #[must_use = "to lowercase the value in-place, use `make_ascii_lowercase()`"] - #[stable(feature = "ascii_methods_on_intrinsics", since = "1.23.0")] - #[inline] - pub fn to_ascii_lowercase(&self) -> String { - let mut s = self.to_owned(); - s.make_ascii_lowercase(); - s - } -} - -/// Converts a boxed slice of bytes to a boxed string slice without checking -/// that the string contains valid UTF-8. -/// -/// # Examples -/// -/// ``` -/// let smile_utf8 = Box::new([226, 152, 186]); -/// let smile = unsafe { std::str::from_boxed_utf8_unchecked(smile_utf8) }; -/// -/// assert_eq!("☺", &*smile); -/// ``` -#[stable(feature = "str_box_extras", since = "1.20.0")] -#[must_use] -#[inline] -pub unsafe fn from_boxed_utf8_unchecked(v: Box<[u8]>) -> Box { - unsafe { Box::from_raw(Box::into_raw(v) as *mut str) } -} - -/// Converts the bytes while the bytes are still ascii. -/// For better average performance, this happens in chunks of `2*size_of::()`. -/// Returns a vec with the converted bytes. -#[inline] -#[cfg(not(test))] -#[cfg(not(no_global_oom_handling))] -fn convert_while_ascii(b: &[u8], convert: fn(&u8) -> u8) -> Vec { - let mut out = Vec::with_capacity(b.len()); - - const USIZE_SIZE: usize = mem::size_of::(); - const MAGIC_UNROLL: usize = 2; - const N: usize = USIZE_SIZE * MAGIC_UNROLL; - const NONASCII_MASK: usize = usize::from_ne_bytes([0x80; USIZE_SIZE]); - - let mut i = 0; - unsafe { - while i + N <= b.len() { - // Safety: we have checks the sizes `b` and `out` to know that our - let in_chunk = b.get_unchecked(i..i + N); - let out_chunk = out.spare_capacity_mut().get_unchecked_mut(i..i + N); - - let mut bits = 0; - for j in 0..MAGIC_UNROLL { - // read the bytes 1 usize at a time (unaligned since we haven't checked the alignment) - // safety: in_chunk is valid bytes in the range - bits |= in_chunk.as_ptr().cast::().add(j).read_unaligned(); - } - // if our chunks aren't ascii, then return only the prior bytes as init - if bits & NONASCII_MASK != 0 { - break; - } - - // perform the case conversions on N bytes (gets heavily autovec'd) - for j in 0..N { - // safety: in_chunk and out_chunk is valid bytes in the range - let out = out_chunk.get_unchecked_mut(j); - out.write(convert(in_chunk.get_unchecked(j))); - } - - // mark these bytes as initialised - i += N; - } - out.set_len(i); - } - - out -} diff --git a/library/alloc/src/string.rs b/library/alloc/src/string.rs deleted file mode 100644 index 36078da7c35a6..0000000000000 --- a/library/alloc/src/string.rs +++ /dev/null @@ -1,3054 +0,0 @@ -//! A UTF-8–encoded, growable string. -//! -//! This module contains the [`String`] type, the [`ToString`] trait for -//! converting to strings, and several error types that may result from -//! working with [`String`]s. -//! -//! # Examples -//! -//! There are multiple ways to create a new [`String`] from a string literal: -//! -//! ``` -//! let s = "Hello".to_string(); -//! -//! let s = String::from("world"); -//! let s: String = "also this".into(); -//! ``` -//! -//! You can create a new [`String`] from an existing one by concatenating with -//! `+`: -//! -//! ``` -//! let s = "Hello".to_string(); -//! -//! let message = s + " world!"; -//! ``` -//! -//! If you have a vector of valid UTF-8 bytes, you can make a [`String`] out of -//! it. You can do the reverse too. -//! -//! ``` -//! let sparkle_heart = vec![240, 159, 146, 150]; -//! -//! // We know these bytes are valid, so we'll use `unwrap()`. -//! let sparkle_heart = String::from_utf8(sparkle_heart).unwrap(); -//! -//! assert_eq!("💖", sparkle_heart); -//! -//! let bytes = sparkle_heart.into_bytes(); -//! -//! assert_eq!(bytes, [240, 159, 146, 150]); -//! ``` - -#![stable(feature = "rust1", since = "1.0.0")] - -use core::error::Error; -use core::fmt; -use core::hash; -#[cfg(not(no_global_oom_handling))] -use core::iter::from_fn; -use core::iter::FusedIterator; -#[cfg(not(no_global_oom_handling))] -use core::ops::Add; -#[cfg(not(no_global_oom_handling))] -use core::ops::AddAssign; -#[cfg(not(no_global_oom_handling))] -use core::ops::Bound::{Excluded, Included, Unbounded}; -use core::ops::{self, Range, RangeBounds}; -use core::ptr; -use core::slice; -use core::str::pattern::Pattern; - -#[cfg(not(no_global_oom_handling))] -use crate::alloc::Allocator; -#[cfg(not(no_global_oom_handling))] -use crate::borrow::{Cow, ToOwned}; -use crate::boxed::Box; -use crate::collections::TryReserveError; -use crate::str::{self, from_utf8_unchecked_mut, Chars, Utf8Error}; -#[cfg(not(no_global_oom_handling))] -use crate::str::{from_boxed_utf8_unchecked, FromStr}; -use crate::vec::Vec; - -/// A UTF-8–encoded, growable string. -/// -/// `String` is the most common string type. It has ownership over the contents -/// of the string, stored in a heap-allocated buffer (see [Representation](#representation)). -/// It is closely related to its borrowed counterpart, the primitive [`str`]. -/// -/// # Examples -/// -/// You can create a `String` from [a literal string][`&str`] with [`String::from`]: -/// -/// [`String::from`]: From::from -/// -/// ``` -/// let hello = String::from("Hello, world!"); -/// ``` -/// -/// You can append a [`char`] to a `String` with the [`push`] method, and -/// append a [`&str`] with the [`push_str`] method: -/// -/// ``` -/// let mut hello = String::from("Hello, "); -/// -/// hello.push('w'); -/// hello.push_str("orld!"); -/// ``` -/// -/// [`push`]: String::push -/// [`push_str`]: String::push_str -/// -/// If you have a vector of UTF-8 bytes, you can create a `String` from it with -/// the [`from_utf8`] method: -/// -/// ``` -/// // some bytes, in a vector -/// let sparkle_heart = vec![240, 159, 146, 150]; -/// -/// // We know these bytes are valid, so we'll use `unwrap()`. -/// let sparkle_heart = String::from_utf8(sparkle_heart).unwrap(); -/// -/// assert_eq!("💖", sparkle_heart); -/// ``` -/// -/// [`from_utf8`]: String::from_utf8 -/// -/// # UTF-8 -/// -/// `String`s are always valid UTF-8. If you need a non-UTF-8 string, consider -/// [`OsString`]. It is similar, but without the UTF-8 constraint. Because UTF-8 -/// is a variable width encoding, `String`s are typically smaller than an array of -/// the same `chars`: -/// -/// ``` -/// use std::mem; -/// -/// // `s` is ASCII which represents each `char` as one byte -/// let s = "hello"; -/// assert_eq!(s.len(), 5); -/// -/// // A `char` array with the same contents would be longer because -/// // every `char` is four bytes -/// let s = ['h', 'e', 'l', 'l', 'o']; -/// let size: usize = s.into_iter().map(|c| mem::size_of_val(&c)).sum(); -/// assert_eq!(size, 20); -/// -/// // However, for non-ASCII strings, the difference will be smaller -/// // and sometimes they are the same -/// let s = "💖💖💖💖💖"; -/// assert_eq!(s.len(), 20); -/// -/// let s = ['💖', '💖', '💖', '💖', '💖']; -/// let size: usize = s.into_iter().map(|c| mem::size_of_val(&c)).sum(); -/// assert_eq!(size, 20); -/// ``` -/// -/// This raises interesting questions as to how `s[i]` should work. -/// What should `i` be here? Several options include byte indices and -/// `char` indices but, because of UTF-8 encoding, only byte indices -/// would provide constant time indexing. Getting the `i`th `char`, for -/// example, is available using [`chars`]: -/// -/// ``` -/// let s = "hello"; -/// let third_character = s.chars().nth(2); -/// assert_eq!(third_character, Some('l')); -/// -/// let s = "💖💖💖💖💖"; -/// let third_character = s.chars().nth(2); -/// assert_eq!(third_character, Some('💖')); -/// ``` -/// -/// Next, what should `s[i]` return? Because indexing returns a reference -/// to underlying data it could be `&u8`, `&[u8]`, or something else similar. -/// Since we're only providing one index, `&u8` makes the most sense but that -/// might not be what the user expects and can be explicitly achieved with -/// [`as_bytes()`]: -/// -/// ``` -/// // The first byte is 104 - the byte value of `'h'` -/// let s = "hello"; -/// assert_eq!(s.as_bytes()[0], 104); -/// // or -/// assert_eq!(s.as_bytes()[0], b'h'); -/// -/// // The first byte is 240 which isn't obviously useful -/// let s = "💖💖💖💖💖"; -/// assert_eq!(s.as_bytes()[0], 240); -/// ``` -/// -/// Due to these ambiguities/restrictions, indexing with a `usize` is simply -/// forbidden: -/// -/// ```compile_fail,E0277 -/// let s = "hello"; -/// -/// // The following will not compile! -/// println!("The first letter of s is {}", s[0]); -/// ``` -/// -/// It is more clear, however, how `&s[i..j]` should work (that is, -/// indexing with a range). It should accept byte indices (to be constant-time) -/// and return a `&str` which is UTF-8 encoded. This is also called "string slicing". -/// Note this will panic if the byte indices provided are not character -/// boundaries - see [`is_char_boundary`] for more details. See the implementations -/// for [`SliceIndex`] for more details on string slicing. For a non-panicking -/// version of string slicing, see [`get`]. -/// -/// [`OsString`]: ../../std/ffi/struct.OsString.html "ffi::OsString" -/// [`SliceIndex`]: core::slice::SliceIndex -/// [`as_bytes()`]: str::as_bytes -/// [`get`]: str::get -/// [`is_char_boundary`]: str::is_char_boundary -/// -/// The [`bytes`] and [`chars`] methods return iterators over the bytes and -/// codepoints of the string, respectively. To iterate over codepoints along -/// with byte indices, use [`char_indices`]. -/// -/// [`bytes`]: str::bytes -/// [`chars`]: str::chars -/// [`char_indices`]: str::char_indices -/// -/// # Deref -/// -/// `String` implements [Deref], and so inherits all of [`str`]'s -/// methods. In addition, this means that you can pass a `String` to a -/// function which takes a [`&str`] by using an ampersand (`&`): -/// -/// ``` -/// fn takes_str(s: &str) { } -/// -/// let s = String::from("Hello"); -/// -/// takes_str(&s); -/// ``` -/// -/// This will create a [`&str`] from the `String` and pass it in. This -/// conversion is very inexpensive, and so generally, functions will accept -/// [`&str`]s as arguments unless they need a `String` for some specific -/// reason. -/// -/// In certain cases Rust doesn't have enough information to make this -/// conversion, known as [`Deref`] coercion. In the following example a string -/// slice [`&'a str`][`&str`] implements the trait `TraitExample`, and the function -/// `example_func` takes anything that implements the trait. In this case Rust -/// would need to make two implicit conversions, which Rust doesn't have the -/// means to do. For that reason, the following example will not compile. -/// -/// ```compile_fail,E0277 -/// trait TraitExample {} -/// -/// impl<'a> TraitExample for &'a str {} -/// -/// fn example_func(example_arg: A) {} -/// -/// let example_string = String::from("example_string"); -/// example_func(&example_string); -/// ``` -/// -/// There are two options that would work instead. The first would be to -/// change the line `example_func(&example_string);` to -/// `example_func(example_string.as_str());`, using the method [`as_str()`] -/// to explicitly extract the string slice containing the string. The second -/// way changes `example_func(&example_string);` to -/// `example_func(&*example_string);`. In this case we are dereferencing a -/// `String` to a [`str`], then referencing the [`str`] back to -/// [`&str`]. The second way is more idiomatic, however both work to do the -/// conversion explicitly rather than relying on the implicit conversion. -/// -/// # Representation -/// -/// A `String` is made up of three components: a pointer to some bytes, a -/// length, and a capacity. The pointer points to the internal buffer which `String` -/// uses to store its data. The length is the number of bytes currently stored -/// in the buffer, and the capacity is the size of the buffer in bytes. As such, -/// the length will always be less than or equal to the capacity. -/// -/// This buffer is always stored on the heap. -/// -/// You can look at these with the [`as_ptr`], [`len`], and [`capacity`] -/// methods: -/// -/// ``` -/// use std::mem; -/// -/// let story = String::from("Once upon a time..."); -/// -// FIXME Update this when vec_into_raw_parts is stabilized -/// // Prevent automatically dropping the String's data -/// let mut story = mem::ManuallyDrop::new(story); -/// -/// let ptr = story.as_mut_ptr(); -/// let len = story.len(); -/// let capacity = story.capacity(); -/// -/// // story has nineteen bytes -/// assert_eq!(19, len); -/// -/// // We can re-build a String out of ptr, len, and capacity. This is all -/// // unsafe because we are responsible for making sure the components are -/// // valid: -/// let s = unsafe { String::from_raw_parts(ptr, len, capacity) } ; -/// -/// assert_eq!(String::from("Once upon a time..."), s); -/// ``` -/// -/// [`as_ptr`]: str::as_ptr -/// [`len`]: String::len -/// [`capacity`]: String::capacity -/// -/// If a `String` has enough capacity, adding elements to it will not -/// re-allocate. For example, consider this program: -/// -/// ``` -/// let mut s = String::new(); -/// -/// println!("{}", s.capacity()); -/// -/// for _ in 0..5 { -/// s.push_str("hello"); -/// println!("{}", s.capacity()); -/// } -/// ``` -/// -/// This will output the following: -/// -/// ```text -/// 0 -/// 8 -/// 16 -/// 16 -/// 32 -/// 32 -/// ``` -/// -/// At first, we have no memory allocated at all, but as we append to the -/// string, it increases its capacity appropriately. If we instead use the -/// [`with_capacity`] method to allocate the correct capacity initially: -/// -/// ``` -/// let mut s = String::with_capacity(25); -/// -/// println!("{}", s.capacity()); -/// -/// for _ in 0..5 { -/// s.push_str("hello"); -/// println!("{}", s.capacity()); -/// } -/// ``` -/// -/// [`with_capacity`]: String::with_capacity -/// -/// We end up with a different output: -/// -/// ```text -/// 25 -/// 25 -/// 25 -/// 25 -/// 25 -/// 25 -/// ``` -/// -/// Here, there's no need to allocate more memory inside the loop. -/// -/// [str]: prim@str "str" -/// [`str`]: prim@str "str" -/// [`&str`]: prim@str "&str" -/// [Deref]: core::ops::Deref "ops::Deref" -/// [`Deref`]: core::ops::Deref "ops::Deref" -/// [`as_str()`]: String::as_str -#[derive(PartialEq, PartialOrd, Eq, Ord)] -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), lang = "String")] -pub struct String { - vec: Vec, -} - -/// A possible error value when converting a `String` from a UTF-8 byte vector. -/// -/// This type is the error type for the [`from_utf8`] method on [`String`]. It -/// is designed in such a way to carefully avoid reallocations: the -/// [`into_bytes`] method will give back the byte vector that was used in the -/// conversion attempt. -/// -/// [`from_utf8`]: String::from_utf8 -/// [`into_bytes`]: FromUtf8Error::into_bytes -/// -/// The [`Utf8Error`] type provided by [`std::str`] represents an error that may -/// occur when converting a slice of [`u8`]s to a [`&str`]. In this sense, it's -/// an analogue to `FromUtf8Error`, and you can get one from a `FromUtf8Error` -/// through the [`utf8_error`] method. -/// -/// [`Utf8Error`]: str::Utf8Error "std::str::Utf8Error" -/// [`std::str`]: core::str "std::str" -/// [`&str`]: prim@str "&str" -/// [`utf8_error`]: FromUtf8Error::utf8_error -/// -/// # Examples -/// -/// ``` -/// // some invalid bytes, in a vector -/// let bytes = vec![0, 159]; -/// -/// let value = String::from_utf8(bytes); -/// -/// assert!(value.is_err()); -/// assert_eq!(vec![0, 159], value.unwrap_err().into_bytes()); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(no_global_oom_handling), derive(Clone))] -#[derive(Debug, PartialEq, Eq)] -pub struct FromUtf8Error { - bytes: Vec, - error: Utf8Error, -} - -/// A possible error value when converting a `String` from a UTF-16 byte slice. -/// -/// This type is the error type for the [`from_utf16`] method on [`String`]. -/// -/// [`from_utf16`]: String::from_utf16 -/// -/// # Examples -/// -/// ``` -/// // 𝄞muic -/// let v = &[0xD834, 0xDD1E, 0x006d, 0x0075, -/// 0xD800, 0x0069, 0x0063]; -/// -/// assert!(String::from_utf16(v).is_err()); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Debug)] -pub struct FromUtf16Error(()); - -impl String { - /// Creates a new empty `String`. - /// - /// Given that the `String` is empty, this will not allocate any initial - /// buffer. While that means that this initial operation is very - /// inexpensive, it may cause excessive allocation later when you add - /// data. If you have an idea of how much data the `String` will hold, - /// consider the [`with_capacity`] method to prevent excessive - /// re-allocation. - /// - /// [`with_capacity`]: String::with_capacity - /// - /// # Examples - /// - /// ``` - /// let s = String::new(); - /// ``` - #[inline] - #[rustc_const_stable(feature = "const_string_new", since = "1.39.0")] - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - pub const fn new() -> String { - String { vec: Vec::new() } - } - - /// Creates a new empty `String` with at least the specified capacity. - /// - /// `String`s have an internal buffer to hold their data. The capacity is - /// the length of that buffer, and can be queried with the [`capacity`] - /// method. This method creates an empty `String`, but one with an initial - /// buffer that can hold at least `capacity` bytes. This is useful when you - /// may be appending a bunch of data to the `String`, reducing the number of - /// reallocations it needs to do. - /// - /// [`capacity`]: String::capacity - /// - /// If the given capacity is `0`, no allocation will occur, and this method - /// is identical to the [`new`] method. - /// - /// [`new`]: String::new - /// - /// # Examples - /// - /// ``` - /// let mut s = String::with_capacity(10); - /// - /// // The String contains no chars, even though it has capacity for more - /// assert_eq!(s.len(), 0); - /// - /// // These are all done without reallocating... - /// let cap = s.capacity(); - /// for _ in 0..10 { - /// s.push('a'); - /// } - /// - /// assert_eq!(s.capacity(), cap); - /// - /// // ...but this may make the string reallocate - /// s.push('a'); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - pub fn with_capacity(capacity: usize) -> String { - String { vec: Vec::with_capacity(capacity) } - } - - /// Creates a new empty `String` with at least the specified capacity. - /// - /// # Errors - /// - /// Returns [`Err`] if the capacity exceeds `isize::MAX` bytes, - /// or if the memory allocator reports failure. - /// - #[inline] - #[unstable(feature = "try_with_capacity", issue = "91913")] - pub fn try_with_capacity(capacity: usize) -> Result { - Ok(String { vec: Vec::try_with_capacity(capacity)? }) - } - - // HACK(japaric): with cfg(test) the inherent `[T]::to_vec` method, which is - // required for this method definition, is not available. Since we don't - // require this method for testing purposes, I'll just stub it - // NB see the slice::hack module in slice.rs for more information - #[inline] - #[cfg(test)] - pub fn from_str(_: &str) -> String { - panic!("not available with cfg(test)"); - } - - /// Converts a vector of bytes to a `String`. - /// - /// A string ([`String`]) is made of bytes ([`u8`]), and a vector of bytes - /// ([`Vec`]) is made of bytes, so this function converts between the - /// two. Not all byte slices are valid `String`s, however: `String` - /// requires that it is valid UTF-8. `from_utf8()` checks to ensure that - /// the bytes are valid UTF-8, and then does the conversion. - /// - /// If you are sure that the byte slice is valid UTF-8, and you don't want - /// to incur the overhead of the validity check, there is an unsafe version - /// of this function, [`from_utf8_unchecked`], which has the same behavior - /// but skips the check. - /// - /// This method will take care to not copy the vector, for efficiency's - /// sake. - /// - /// If you need a [`&str`] instead of a `String`, consider - /// [`str::from_utf8`]. - /// - /// The inverse of this method is [`into_bytes`]. - /// - /// # Errors - /// - /// Returns [`Err`] if the slice is not UTF-8 with a description as to why the - /// provided bytes are not UTF-8. The vector you moved in is also included. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// // some bytes, in a vector - /// let sparkle_heart = vec![240, 159, 146, 150]; - /// - /// // We know these bytes are valid, so we'll use `unwrap()`. - /// let sparkle_heart = String::from_utf8(sparkle_heart).unwrap(); - /// - /// assert_eq!("💖", sparkle_heart); - /// ``` - /// - /// Incorrect bytes: - /// - /// ``` - /// // some invalid bytes, in a vector - /// let sparkle_heart = vec![0, 159, 146, 150]; - /// - /// assert!(String::from_utf8(sparkle_heart).is_err()); - /// ``` - /// - /// See the docs for [`FromUtf8Error`] for more details on what you can do - /// with this error. - /// - /// [`from_utf8_unchecked`]: String::from_utf8_unchecked - /// [`Vec`]: crate::vec::Vec "Vec" - /// [`&str`]: prim@str "&str" - /// [`into_bytes`]: String::into_bytes - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn from_utf8(vec: Vec) -> Result { - match str::from_utf8(&vec) { - Ok(..) => Ok(String { vec }), - Err(e) => Err(FromUtf8Error { bytes: vec, error: e }), - } - } - - /// Converts a slice of bytes to a string, including invalid characters. - /// - /// Strings are made of bytes ([`u8`]), and a slice of bytes - /// ([`&[u8]`][byteslice]) is made of bytes, so this function converts - /// between the two. Not all byte slices are valid strings, however: strings - /// are required to be valid UTF-8. During this conversion, - /// `from_utf8_lossy()` will replace any invalid UTF-8 sequences with - /// [`U+FFFD REPLACEMENT CHARACTER`][U+FFFD], which looks like this: � - /// - /// [byteslice]: prim@slice - /// [U+FFFD]: core::char::REPLACEMENT_CHARACTER - /// - /// If you are sure that the byte slice is valid UTF-8, and you don't want - /// to incur the overhead of the conversion, there is an unsafe version - /// of this function, [`from_utf8_unchecked`], which has the same behavior - /// but skips the checks. - /// - /// [`from_utf8_unchecked`]: String::from_utf8_unchecked - /// - /// This function returns a [`Cow<'a, str>`]. If our byte slice is invalid - /// UTF-8, then we need to insert the replacement characters, which will - /// change the size of the string, and hence, require a `String`. But if - /// it's already valid UTF-8, we don't need a new allocation. This return - /// type allows us to handle both cases. - /// - /// [`Cow<'a, str>`]: crate::borrow::Cow "borrow::Cow" - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// // some bytes, in a vector - /// let sparkle_heart = vec![240, 159, 146, 150]; - /// - /// let sparkle_heart = String::from_utf8_lossy(&sparkle_heart); - /// - /// assert_eq!("💖", sparkle_heart); - /// ``` - /// - /// Incorrect bytes: - /// - /// ``` - /// // some invalid bytes - /// let input = b"Hello \xF0\x90\x80World"; - /// let output = String::from_utf8_lossy(input); - /// - /// assert_eq!("Hello �World", output); - /// ``` - #[must_use] - #[cfg(not(no_global_oom_handling))] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn from_utf8_lossy(v: &[u8]) -> Cow<'_, str> { - let mut iter = v.utf8_chunks(); - - let first_valid = if let Some(chunk) = iter.next() { - let valid = chunk.valid(); - if chunk.invalid().is_empty() { - debug_assert_eq!(valid.len(), v.len()); - return Cow::Borrowed(valid); - } - valid - } else { - return Cow::Borrowed(""); - }; - - const REPLACEMENT: &str = "\u{FFFD}"; - - let mut res = String::with_capacity(v.len()); - res.push_str(first_valid); - res.push_str(REPLACEMENT); - - for chunk in iter { - res.push_str(chunk.valid()); - if !chunk.invalid().is_empty() { - res.push_str(REPLACEMENT); - } - } - - Cow::Owned(res) - } - - /// Decode a UTF-16–encoded vector `v` into a `String`, returning [`Err`] - /// if `v` contains any invalid data. - /// - /// # Examples - /// - /// ``` - /// // 𝄞music - /// let v = &[0xD834, 0xDD1E, 0x006d, 0x0075, - /// 0x0073, 0x0069, 0x0063]; - /// assert_eq!(String::from("𝄞music"), - /// String::from_utf16(v).unwrap()); - /// - /// // 𝄞muic - /// let v = &[0xD834, 0xDD1E, 0x006d, 0x0075, - /// 0xD800, 0x0069, 0x0063]; - /// assert!(String::from_utf16(v).is_err()); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn from_utf16(v: &[u16]) -> Result { - // This isn't done via collect::>() for performance reasons. - // FIXME: the function can be simplified again when #48994 is closed. - let mut ret = String::with_capacity(v.len()); - for c in char::decode_utf16(v.iter().cloned()) { - if let Ok(c) = c { - ret.push(c); - } else { - return Err(FromUtf16Error(())); - } - } - Ok(ret) - } - - /// Decode a UTF-16–encoded slice `v` into a `String`, replacing - /// invalid data with [the replacement character (`U+FFFD`)][U+FFFD]. - /// - /// Unlike [`from_utf8_lossy`] which returns a [`Cow<'a, str>`], - /// `from_utf16_lossy` returns a `String` since the UTF-16 to UTF-8 - /// conversion requires a memory allocation. - /// - /// [`from_utf8_lossy`]: String::from_utf8_lossy - /// [`Cow<'a, str>`]: crate::borrow::Cow "borrow::Cow" - /// [U+FFFD]: core::char::REPLACEMENT_CHARACTER - /// - /// # Examples - /// - /// ``` - /// // 𝄞music - /// let v = &[0xD834, 0xDD1E, 0x006d, 0x0075, - /// 0x0073, 0xDD1E, 0x0069, 0x0063, - /// 0xD834]; - /// - /// assert_eq!(String::from("𝄞mus\u{FFFD}ic\u{FFFD}"), - /// String::from_utf16_lossy(v)); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[must_use] - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn from_utf16_lossy(v: &[u16]) -> String { - char::decode_utf16(v.iter().cloned()) - .map(|r| r.unwrap_or(char::REPLACEMENT_CHARACTER)) - .collect() - } - - /// Decode a UTF-16LE–encoded vector `v` into a `String`, returning [`Err`] - /// if `v` contains any invalid data. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(str_from_utf16_endian)] - /// // 𝄞music - /// let v = &[0x34, 0xD8, 0x1E, 0xDD, 0x6d, 0x00, 0x75, 0x00, - /// 0x73, 0x00, 0x69, 0x00, 0x63, 0x00]; - /// assert_eq!(String::from("𝄞music"), - /// String::from_utf16le(v).unwrap()); - /// - /// // 𝄞muic - /// let v = &[0x34, 0xD8, 0x1E, 0xDD, 0x6d, 0x00, 0x75, 0x00, - /// 0x00, 0xD8, 0x69, 0x00, 0x63, 0x00]; - /// assert!(String::from_utf16le(v).is_err()); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "str_from_utf16_endian", issue = "116258")] - pub fn from_utf16le(v: &[u8]) -> Result { - if v.len() % 2 != 0 { - return Err(FromUtf16Error(())); - } - match (cfg!(target_endian = "little"), unsafe { v.align_to::() }) { - (true, ([], v, [])) => Self::from_utf16(v), - _ => char::decode_utf16(v.array_chunks::<2>().copied().map(u16::from_le_bytes)) - .collect::>() - .map_err(|_| FromUtf16Error(())), - } - } - - /// Decode a UTF-16LE–encoded slice `v` into a `String`, replacing - /// invalid data with [the replacement character (`U+FFFD`)][U+FFFD]. - /// - /// Unlike [`from_utf8_lossy`] which returns a [`Cow<'a, str>`], - /// `from_utf16le_lossy` returns a `String` since the UTF-16 to UTF-8 - /// conversion requires a memory allocation. - /// - /// [`from_utf8_lossy`]: String::from_utf8_lossy - /// [`Cow<'a, str>`]: crate::borrow::Cow "borrow::Cow" - /// [U+FFFD]: core::char::REPLACEMENT_CHARACTER - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(str_from_utf16_endian)] - /// // 𝄞music - /// let v = &[0x34, 0xD8, 0x1E, 0xDD, 0x6d, 0x00, 0x75, 0x00, - /// 0x73, 0x00, 0x1E, 0xDD, 0x69, 0x00, 0x63, 0x00, - /// 0x34, 0xD8]; - /// - /// assert_eq!(String::from("𝄞mus\u{FFFD}ic\u{FFFD}"), - /// String::from_utf16le_lossy(v)); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "str_from_utf16_endian", issue = "116258")] - pub fn from_utf16le_lossy(v: &[u8]) -> String { - match (cfg!(target_endian = "little"), unsafe { v.align_to::() }) { - (true, ([], v, [])) => Self::from_utf16_lossy(v), - (true, ([], v, [_remainder])) => Self::from_utf16_lossy(v) + "\u{FFFD}", - _ => { - let mut iter = v.array_chunks::<2>(); - let string = char::decode_utf16(iter.by_ref().copied().map(u16::from_le_bytes)) - .map(|r| r.unwrap_or(char::REPLACEMENT_CHARACTER)) - .collect(); - if iter.remainder().is_empty() { string } else { string + "\u{FFFD}" } - } - } - } - - /// Decode a UTF-16BE–encoded vector `v` into a `String`, returning [`Err`] - /// if `v` contains any invalid data. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(str_from_utf16_endian)] - /// // 𝄞music - /// let v = &[0xD8, 0x34, 0xDD, 0x1E, 0x00, 0x6d, 0x00, 0x75, - /// 0x00, 0x73, 0x00, 0x69, 0x00, 0x63]; - /// assert_eq!(String::from("𝄞music"), - /// String::from_utf16be(v).unwrap()); - /// - /// // 𝄞muic - /// let v = &[0xD8, 0x34, 0xDD, 0x1E, 0x00, 0x6d, 0x00, 0x75, - /// 0xD8, 0x00, 0x00, 0x69, 0x00, 0x63]; - /// assert!(String::from_utf16be(v).is_err()); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "str_from_utf16_endian", issue = "116258")] - pub fn from_utf16be(v: &[u8]) -> Result { - if v.len() % 2 != 0 { - return Err(FromUtf16Error(())); - } - match (cfg!(target_endian = "big"), unsafe { v.align_to::() }) { - (true, ([], v, [])) => Self::from_utf16(v), - _ => char::decode_utf16(v.array_chunks::<2>().copied().map(u16::from_be_bytes)) - .collect::>() - .map_err(|_| FromUtf16Error(())), - } - } - - /// Decode a UTF-16BE–encoded slice `v` into a `String`, replacing - /// invalid data with [the replacement character (`U+FFFD`)][U+FFFD]. - /// - /// Unlike [`from_utf8_lossy`] which returns a [`Cow<'a, str>`], - /// `from_utf16le_lossy` returns a `String` since the UTF-16 to UTF-8 - /// conversion requires a memory allocation. - /// - /// [`from_utf8_lossy`]: String::from_utf8_lossy - /// [`Cow<'a, str>`]: crate::borrow::Cow "borrow::Cow" - /// [U+FFFD]: core::char::REPLACEMENT_CHARACTER - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// #![feature(str_from_utf16_endian)] - /// // 𝄞music - /// let v = &[0xD8, 0x34, 0xDD, 0x1E, 0x00, 0x6d, 0x00, 0x75, - /// 0x00, 0x73, 0xDD, 0x1E, 0x00, 0x69, 0x00, 0x63, - /// 0xD8, 0x34]; - /// - /// assert_eq!(String::from("𝄞mus\u{FFFD}ic\u{FFFD}"), - /// String::from_utf16be_lossy(v)); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "str_from_utf16_endian", issue = "116258")] - pub fn from_utf16be_lossy(v: &[u8]) -> String { - match (cfg!(target_endian = "big"), unsafe { v.align_to::() }) { - (true, ([], v, [])) => Self::from_utf16_lossy(v), - (true, ([], v, [_remainder])) => Self::from_utf16_lossy(v) + "\u{FFFD}", - _ => { - let mut iter = v.array_chunks::<2>(); - let string = char::decode_utf16(iter.by_ref().copied().map(u16::from_be_bytes)) - .map(|r| r.unwrap_or(char::REPLACEMENT_CHARACTER)) - .collect(); - if iter.remainder().is_empty() { string } else { string + "\u{FFFD}" } - } - } - } - - /// Decomposes a `String` into its raw components: `(pointer, length, capacity)`. - /// - /// Returns the raw pointer to the underlying data, the length of - /// the string (in bytes), and the allocated capacity of the data - /// (in bytes). These are the same arguments in the same order as - /// the arguments to [`from_raw_parts`]. - /// - /// After calling this function, the caller is responsible for the - /// memory previously managed by the `String`. The only way to do - /// this is to convert the raw pointer, length, and capacity back - /// into a `String` with the [`from_raw_parts`] function, allowing - /// the destructor to perform the cleanup. - /// - /// [`from_raw_parts`]: String::from_raw_parts - /// - /// # Examples - /// - /// ``` - /// #![feature(vec_into_raw_parts)] - /// let s = String::from("hello"); - /// - /// let (ptr, len, cap) = s.into_raw_parts(); - /// - /// let rebuilt = unsafe { String::from_raw_parts(ptr, len, cap) }; - /// assert_eq!(rebuilt, "hello"); - /// ``` - #[must_use = "`self` will be dropped if the result is not used"] - #[unstable(feature = "vec_into_raw_parts", reason = "new API", issue = "65816")] - pub fn into_raw_parts(self) -> (*mut u8, usize, usize) { - self.vec.into_raw_parts() - } - - /// Creates a new `String` from a pointer, a length and a capacity. - /// - /// # Safety - /// - /// This is highly unsafe, due to the number of invariants that aren't - /// checked: - /// - /// * The memory at `buf` needs to have been previously allocated by the - /// same allocator the standard library uses, with a required alignment of exactly 1. - /// * `length` needs to be less than or equal to `capacity`. - /// * `capacity` needs to be the correct value. - /// * The first `length` bytes at `buf` need to be valid UTF-8. - /// - /// Violating these may cause problems like corrupting the allocator's - /// internal data structures. For example, it is normally **not** safe to - /// build a `String` from a pointer to a C `char` array containing UTF-8 - /// _unless_ you are certain that array was originally allocated by the - /// Rust standard library's allocator. - /// - /// The ownership of `buf` is effectively transferred to the - /// `String` which may then deallocate, reallocate or change the - /// contents of memory pointed to by the pointer at will. Ensure - /// that nothing else uses the pointer after calling this - /// function. - /// - /// # Examples - /// - /// ``` - /// use std::mem; - /// - /// unsafe { - /// let s = String::from("hello"); - /// - // FIXME Update this when vec_into_raw_parts is stabilized - /// // Prevent automatically dropping the String's data - /// let mut s = mem::ManuallyDrop::new(s); - /// - /// let ptr = s.as_mut_ptr(); - /// let len = s.len(); - /// let capacity = s.capacity(); - /// - /// let s = String::from_raw_parts(ptr, len, capacity); - /// - /// assert_eq!(String::from("hello"), s); - /// } - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub unsafe fn from_raw_parts(buf: *mut u8, length: usize, capacity: usize) -> String { - unsafe { String { vec: Vec::from_raw_parts(buf, length, capacity) } } - } - - /// Converts a vector of bytes to a `String` without checking that the - /// string contains valid UTF-8. - /// - /// See the safe version, [`from_utf8`], for more details. - /// - /// [`from_utf8`]: String::from_utf8 - /// - /// # Safety - /// - /// This function is unsafe because it does not check that the bytes passed - /// to it are valid UTF-8. If this constraint is violated, it may cause - /// memory unsafety issues with future users of the `String`, as the rest of - /// the standard library assumes that `String`s are valid UTF-8. - /// - /// # Examples - /// - /// ``` - /// // some bytes, in a vector - /// let sparkle_heart = vec![240, 159, 146, 150]; - /// - /// let sparkle_heart = unsafe { - /// String::from_utf8_unchecked(sparkle_heart) - /// }; - /// - /// assert_eq!("💖", sparkle_heart); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub unsafe fn from_utf8_unchecked(bytes: Vec) -> String { - String { vec: bytes } - } - - /// Converts a `String` into a byte vector. - /// - /// This consumes the `String`, so we do not need to copy its contents. - /// - /// # Examples - /// - /// ``` - /// let s = String::from("hello"); - /// let bytes = s.into_bytes(); - /// - /// assert_eq!(&[104, 101, 108, 108, 111][..], &bytes[..]); - /// ``` - #[inline] - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn into_bytes(self) -> Vec { - self.vec - } - - /// Extracts a string slice containing the entire `String`. - /// - /// # Examples - /// - /// ``` - /// let s = String::from("foo"); - /// - /// assert_eq!("foo", s.as_str()); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "string_as_str", since = "1.7.0")] - pub fn as_str(&self) -> &str { - self - } - - /// Converts a `String` into a mutable string slice. - /// - /// # Examples - /// - /// ``` - /// let mut s = String::from("foobar"); - /// let s_mut_str = s.as_mut_str(); - /// - /// s_mut_str.make_ascii_uppercase(); - /// - /// assert_eq!("FOOBAR", s_mut_str); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "string_as_str", since = "1.7.0")] - pub fn as_mut_str(&mut self) -> &mut str { - self - } - - /// Appends a given string slice onto the end of this `String`. - /// - /// # Examples - /// - /// ``` - /// let mut s = String::from("foo"); - /// - /// s.push_str("bar"); - /// - /// assert_eq!("foobar", s); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("append", "push")] - pub fn push_str(&mut self, string: &str) { - self.vec.extend_from_slice(string.as_bytes()) - } - - /// Copies elements from `src` range to the end of the string. - /// - /// # Panics - /// - /// Panics if the starting point or end point do not lie on a [`char`] - /// boundary, or if they're out of bounds. - /// - /// # Examples - /// - /// ``` - /// #![feature(string_extend_from_within)] - /// let mut string = String::from("abcde"); - /// - /// string.extend_from_within(2..); - /// assert_eq!(string, "abcdecde"); - /// - /// string.extend_from_within(..2); - /// assert_eq!(string, "abcdecdeab"); - /// - /// string.extend_from_within(4..8); - /// assert_eq!(string, "abcdecdeabecde"); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "string_extend_from_within", issue = "103806")] - pub fn extend_from_within(&mut self, src: R) - where - R: RangeBounds, - { - let src @ Range { start, end } = slice::range(src, ..self.len()); - - assert!(self.is_char_boundary(start)); - assert!(self.is_char_boundary(end)); - - self.vec.extend_from_within(src); - } - - /// Returns this `String`'s capacity, in bytes. - /// - /// # Examples - /// - /// ``` - /// let s = String::with_capacity(10); - /// - /// assert!(s.capacity() >= 10); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn capacity(&self) -> usize { - self.vec.capacity() - } - - /// Reserves capacity for at least `additional` bytes more than the - /// current length. The allocator may reserve more space to speculatively - /// avoid frequent allocations. After calling `reserve`, - /// capacity will be greater than or equal to `self.len() + additional`. - /// Does nothing if capacity is already sufficient. - /// - /// # Panics - /// - /// Panics if the new capacity overflows [`usize`]. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let mut s = String::new(); - /// - /// s.reserve(10); - /// - /// assert!(s.capacity() >= 10); - /// ``` - /// - /// This might not actually increase the capacity: - /// - /// ``` - /// let mut s = String::with_capacity(10); - /// s.push('a'); - /// s.push('b'); - /// - /// // s now has a length of 2 and a capacity of at least 10 - /// let capacity = s.capacity(); - /// assert_eq!(2, s.len()); - /// assert!(capacity >= 10); - /// - /// // Since we already have at least an extra 8 capacity, calling this... - /// s.reserve(8); - /// - /// // ... doesn't actually increase. - /// assert_eq!(capacity, s.capacity()); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn reserve(&mut self, additional: usize) { - self.vec.reserve(additional) - } - - /// Reserves the minimum capacity for at least `additional` bytes more than - /// the current length. Unlike [`reserve`], this will not - /// deliberately over-allocate to speculatively avoid frequent allocations. - /// After calling `reserve_exact`, capacity will be greater than or equal to - /// `self.len() + additional`. Does nothing if the capacity is already - /// sufficient. - /// - /// [`reserve`]: String::reserve - /// - /// # Panics - /// - /// Panics if the new capacity overflows [`usize`]. - /// - /// # Examples - /// - /// Basic usage: - /// - /// ``` - /// let mut s = String::new(); - /// - /// s.reserve_exact(10); - /// - /// assert!(s.capacity() >= 10); - /// ``` - /// - /// This might not actually increase the capacity: - /// - /// ``` - /// let mut s = String::with_capacity(10); - /// s.push('a'); - /// s.push('b'); - /// - /// // s now has a length of 2 and a capacity of at least 10 - /// let capacity = s.capacity(); - /// assert_eq!(2, s.len()); - /// assert!(capacity >= 10); - /// - /// // Since we already have at least an extra 8 capacity, calling this... - /// s.reserve_exact(8); - /// - /// // ... doesn't actually increase. - /// assert_eq!(capacity, s.capacity()); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn reserve_exact(&mut self, additional: usize) { - self.vec.reserve_exact(additional) - } - - /// Tries to reserve capacity for at least `additional` bytes more than the - /// current length. The allocator may reserve more space to speculatively - /// avoid frequent allocations. After calling `try_reserve`, capacity will be - /// greater than or equal to `self.len() + additional` if it returns - /// `Ok(())`. Does nothing if capacity is already sufficient. This method - /// preserves the contents even if an error occurs. - /// - /// # Errors - /// - /// If the capacity overflows, or the allocator reports a failure, then an error - /// is returned. - /// - /// # Examples - /// - /// ``` - /// use std::collections::TryReserveError; - /// - /// fn process_data(data: &str) -> Result { - /// let mut output = String::new(); - /// - /// // Pre-reserve the memory, exiting if we can't - /// output.try_reserve(data.len())?; - /// - /// // Now we know this can't OOM in the middle of our complex work - /// output.push_str(data); - /// - /// Ok(output) - /// } - /// # process_data("rust").expect("why is the test harness OOMing on 4 bytes?"); - /// ``` - #[stable(feature = "try_reserve", since = "1.57.0")] - pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> { - self.vec.try_reserve(additional) - } - - /// Tries to reserve the minimum capacity for at least `additional` bytes - /// more than the current length. Unlike [`try_reserve`], this will not - /// deliberately over-allocate to speculatively avoid frequent allocations. - /// After calling `try_reserve_exact`, capacity will be greater than or - /// equal to `self.len() + additional` if it returns `Ok(())`. - /// Does nothing if the capacity is already sufficient. - /// - /// Note that the allocator may give the collection more space than it - /// requests. Therefore, capacity can not be relied upon to be precisely - /// minimal. Prefer [`try_reserve`] if future insertions are expected. - /// - /// [`try_reserve`]: String::try_reserve - /// - /// # Errors - /// - /// If the capacity overflows, or the allocator reports a failure, then an error - /// is returned. - /// - /// # Examples - /// - /// ``` - /// use std::collections::TryReserveError; - /// - /// fn process_data(data: &str) -> Result { - /// let mut output = String::new(); - /// - /// // Pre-reserve the memory, exiting if we can't - /// output.try_reserve_exact(data.len())?; - /// - /// // Now we know this can't OOM in the middle of our complex work - /// output.push_str(data); - /// - /// Ok(output) - /// } - /// # process_data("rust").expect("why is the test harness OOMing on 4 bytes?"); - /// ``` - #[stable(feature = "try_reserve", since = "1.57.0")] - pub fn try_reserve_exact(&mut self, additional: usize) -> Result<(), TryReserveError> { - self.vec.try_reserve_exact(additional) - } - - /// Shrinks the capacity of this `String` to match its length. - /// - /// # Examples - /// - /// ``` - /// let mut s = String::from("foo"); - /// - /// s.reserve(100); - /// assert!(s.capacity() >= 100); - /// - /// s.shrink_to_fit(); - /// assert_eq!(3, s.capacity()); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn shrink_to_fit(&mut self) { - self.vec.shrink_to_fit() - } - - /// Shrinks the capacity of this `String` with a lower bound. - /// - /// The capacity will remain at least as large as both the length - /// and the supplied value. - /// - /// If the current capacity is less than the lower limit, this is a no-op. - /// - /// # Examples - /// - /// ``` - /// let mut s = String::from("foo"); - /// - /// s.reserve(100); - /// assert!(s.capacity() >= 100); - /// - /// s.shrink_to(10); - /// assert!(s.capacity() >= 10); - /// s.shrink_to(0); - /// assert!(s.capacity() >= 3); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[inline] - #[stable(feature = "shrink_to", since = "1.56.0")] - pub fn shrink_to(&mut self, min_capacity: usize) { - self.vec.shrink_to(min_capacity) - } - - /// Appends the given [`char`] to the end of this `String`. - /// - /// # Examples - /// - /// ``` - /// let mut s = String::from("abc"); - /// - /// s.push('1'); - /// s.push('2'); - /// s.push('3'); - /// - /// assert_eq!("abc123", s); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn push(&mut self, ch: char) { - match ch.len_utf8() { - 1 => self.vec.push(ch as u8), - _ => self.vec.extend_from_slice(ch.encode_utf8(&mut [0; 4]).as_bytes()), - } - } - - /// Returns a byte slice of this `String`'s contents. - /// - /// The inverse of this method is [`from_utf8`]. - /// - /// [`from_utf8`]: String::from_utf8 - /// - /// # Examples - /// - /// ``` - /// let s = String::from("hello"); - /// - /// assert_eq!(&[104, 101, 108, 108, 111], s.as_bytes()); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn as_bytes(&self) -> &[u8] { - &self.vec - } - - /// Shortens this `String` to the specified length. - /// - /// If `new_len` is greater than or equal to the string's current length, this has no - /// effect. - /// - /// Note that this method has no effect on the allocated capacity - /// of the string - /// - /// # Panics - /// - /// Panics if `new_len` does not lie on a [`char`] boundary. - /// - /// # Examples - /// - /// ``` - /// let mut s = String::from("hello"); - /// - /// s.truncate(2); - /// - /// assert_eq!("he", s); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn truncate(&mut self, new_len: usize) { - if new_len <= self.len() { - assert!(self.is_char_boundary(new_len)); - self.vec.truncate(new_len) - } - } - - /// Removes the last character from the string buffer and returns it. - /// - /// Returns [`None`] if this `String` is empty. - /// - /// # Examples - /// - /// ``` - /// let mut s = String::from("abč"); - /// - /// assert_eq!(s.pop(), Some('č')); - /// assert_eq!(s.pop(), Some('b')); - /// assert_eq!(s.pop(), Some('a')); - /// - /// assert_eq!(s.pop(), None); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn pop(&mut self) -> Option { - let ch = self.chars().rev().next()?; - let newlen = self.len() - ch.len_utf8(); - unsafe { - self.vec.set_len(newlen); - } - Some(ch) - } - - /// Removes a [`char`] from this `String` at a byte position and returns it. - /// - /// This is an *O*(*n*) operation, as it requires copying every element in the - /// buffer. - /// - /// # Panics - /// - /// Panics if `idx` is larger than or equal to the `String`'s length, - /// or if it does not lie on a [`char`] boundary. - /// - /// # Examples - /// - /// ``` - /// let mut s = String::from("abç"); - /// - /// assert_eq!(s.remove(0), 'a'); - /// assert_eq!(s.remove(1), 'ç'); - /// assert_eq!(s.remove(0), 'b'); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("delete", "take")] - pub fn remove(&mut self, idx: usize) -> char { - let ch = match self[idx..].chars().next() { - Some(ch) => ch, - None => panic!("cannot remove a char from the end of a string"), - }; - - let next = idx + ch.len_utf8(); - let len = self.len(); - unsafe { - ptr::copy(self.vec.as_ptr().add(next), self.vec.as_mut_ptr().add(idx), len - next); - self.vec.set_len(len - (next - idx)); - } - ch - } - - /// Remove all matches of pattern `pat` in the `String`. - /// - /// # Examples - /// - /// ``` - /// #![feature(string_remove_matches)] - /// let mut s = String::from("Trees are not green, the sky is not blue."); - /// s.remove_matches("not "); - /// assert_eq!("Trees are green, the sky is blue.", s); - /// ``` - /// - /// Matches will be detected and removed iteratively, so in cases where - /// patterns overlap, only the first pattern will be removed: - /// - /// ``` - /// #![feature(string_remove_matches)] - /// let mut s = String::from("banana"); - /// s.remove_matches("ana"); - /// assert_eq!("bna", s); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "string_remove_matches", reason = "new API", issue = "72826")] - pub fn remove_matches<'a, P>(&'a mut self, pat: P) - where - P: for<'x> Pattern<'x>, - { - use core::str::pattern::Searcher; - - let rejections = { - let mut searcher = pat.into_searcher(self); - // Per Searcher::next: - // - // A Match result needs to contain the whole matched pattern, - // however Reject results may be split up into arbitrary many - // adjacent fragments. Both ranges may have zero length. - // - // In practice the implementation of Searcher::next_match tends to - // be more efficient, so we use it here and do some work to invert - // matches into rejections since that's what we want to copy below. - let mut front = 0; - let rejections: Vec<_> = from_fn(|| { - let (start, end) = searcher.next_match()?; - let prev_front = front; - front = end; - Some((prev_front, start)) - }) - .collect(); - rejections.into_iter().chain(core::iter::once((front, self.len()))) - }; - - let mut len = 0; - let ptr = self.vec.as_mut_ptr(); - - for (start, end) in rejections { - let count = end - start; - if start != len { - // SAFETY: per Searcher::next: - // - // The stream of Match and Reject values up to a Done will - // contain index ranges that are adjacent, non-overlapping, - // covering the whole haystack, and laying on utf8 - // boundaries. - unsafe { - ptr::copy(ptr.add(start), ptr.add(len), count); - } - } - len += count; - } - - unsafe { - self.vec.set_len(len); - } - } - - /// Retains only the characters specified by the predicate. - /// - /// In other words, remove all characters `c` such that `f(c)` returns `false`. - /// This method operates in place, visiting each character exactly once in the - /// original order, and preserves the order of the retained characters. - /// - /// # Examples - /// - /// ``` - /// let mut s = String::from("f_o_ob_ar"); - /// - /// s.retain(|c| c != '_'); - /// - /// assert_eq!(s, "foobar"); - /// ``` - /// - /// Because the elements are visited exactly once in the original order, - /// external state may be used to decide which elements to keep. - /// - /// ``` - /// let mut s = String::from("abcde"); - /// let keep = [false, true, true, false, true]; - /// let mut iter = keep.iter(); - /// s.retain(|_| *iter.next().unwrap()); - /// assert_eq!(s, "bce"); - /// ``` - #[inline] - #[stable(feature = "string_retain", since = "1.26.0")] - pub fn retain(&mut self, mut f: F) - where - F: FnMut(char) -> bool, - { - struct SetLenOnDrop<'a> { - s: &'a mut String, - idx: usize, - del_bytes: usize, - } - - impl<'a> Drop for SetLenOnDrop<'a> { - fn drop(&mut self) { - let new_len = self.idx - self.del_bytes; - debug_assert!(new_len <= self.s.len()); - unsafe { self.s.vec.set_len(new_len) }; - } - } - - let len = self.len(); - let mut guard = SetLenOnDrop { s: self, idx: 0, del_bytes: 0 }; - - while guard.idx < len { - let ch = - // SAFETY: `guard.idx` is positive-or-zero and less that len so the `get_unchecked` - // is in bound. `self` is valid UTF-8 like string and the returned slice starts at - // a unicode code point so the `Chars` always return one character. - unsafe { guard.s.get_unchecked(guard.idx..len).chars().next().unwrap_unchecked() }; - let ch_len = ch.len_utf8(); - - if !f(ch) { - guard.del_bytes += ch_len; - } else if guard.del_bytes > 0 { - // SAFETY: `guard.idx` is in bound and `guard.del_bytes` represent the number of - // bytes that are erased from the string so the resulting `guard.idx - - // guard.del_bytes` always represent a valid unicode code point. - // - // `guard.del_bytes` >= `ch.len_utf8()`, so taking a slice with `ch.len_utf8()` len - // is safe. - ch.encode_utf8(unsafe { - crate::slice::from_raw_parts_mut( - guard.s.as_mut_ptr().add(guard.idx - guard.del_bytes), - ch.len_utf8(), - ) - }); - } - - // Point idx to the next char - guard.idx += ch_len; - } - - drop(guard); - } - - /// Inserts a character into this `String` at a byte position. - /// - /// This is an *O*(*n*) operation as it requires copying every element in the - /// buffer. - /// - /// # Panics - /// - /// Panics if `idx` is larger than the `String`'s length, or if it does not - /// lie on a [`char`] boundary. - /// - /// # Examples - /// - /// ``` - /// let mut s = String::with_capacity(3); - /// - /// s.insert(0, 'f'); - /// s.insert(1, 'o'); - /// s.insert(2, 'o'); - /// - /// assert_eq!("foo", s); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("set")] - pub fn insert(&mut self, idx: usize, ch: char) { - assert!(self.is_char_boundary(idx)); - let mut bits = [0; 4]; - let bits = ch.encode_utf8(&mut bits).as_bytes(); - - unsafe { - self.insert_bytes(idx, bits); - } - } - - #[cfg(not(no_global_oom_handling))] - unsafe fn insert_bytes(&mut self, idx: usize, bytes: &[u8]) { - let len = self.len(); - let amt = bytes.len(); - self.vec.reserve(amt); - - unsafe { - ptr::copy(self.vec.as_ptr().add(idx), self.vec.as_mut_ptr().add(idx + amt), len - idx); - ptr::copy_nonoverlapping(bytes.as_ptr(), self.vec.as_mut_ptr().add(idx), amt); - self.vec.set_len(len + amt); - } - } - - /// Inserts a string slice into this `String` at a byte position. - /// - /// This is an *O*(*n*) operation as it requires copying every element in the - /// buffer. - /// - /// # Panics - /// - /// Panics if `idx` is larger than the `String`'s length, or if it does not - /// lie on a [`char`] boundary. - /// - /// # Examples - /// - /// ``` - /// let mut s = String::from("bar"); - /// - /// s.insert_str(0, "foo"); - /// - /// assert_eq!("foobar", s); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[inline] - #[stable(feature = "insert_str", since = "1.16.0")] - pub fn insert_str(&mut self, idx: usize, string: &str) { - assert!(self.is_char_boundary(idx)); - - unsafe { - self.insert_bytes(idx, string.as_bytes()); - } - } - - /// Returns a mutable reference to the contents of this `String`. - /// - /// # Safety - /// - /// This function is unsafe because the returned `&mut Vec` allows writing - /// bytes which are not valid UTF-8. If this constraint is violated, using - /// the original `String` after dropping the `&mut Vec` may violate memory - /// safety, as the rest of the standard library assumes that `String`s are - /// valid UTF-8. - /// - /// # Examples - /// - /// ``` - /// let mut s = String::from("hello"); - /// - /// unsafe { - /// let vec = s.as_mut_vec(); - /// assert_eq!(&[104, 101, 108, 108, 111][..], &vec[..]); - /// - /// vec.reverse(); - /// } - /// assert_eq!(s, "olleh"); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub unsafe fn as_mut_vec(&mut self) -> &mut Vec { - &mut self.vec - } - - /// Returns the length of this `String`, in bytes, not [`char`]s or - /// graphemes. In other words, it might not be what a human considers the - /// length of the string. - /// - /// # Examples - /// - /// ``` - /// let a = String::from("foo"); - /// assert_eq!(a.len(), 3); - /// - /// let fancy_f = String::from("ƒoo"); - /// assert_eq!(fancy_f.len(), 4); - /// assert_eq!(fancy_f.chars().count(), 3); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("length", "size")] - pub fn len(&self) -> usize { - self.vec.len() - } - - /// Returns `true` if this `String` has a length of zero, and `false` otherwise. - /// - /// # Examples - /// - /// ``` - /// let mut v = String::new(); - /// assert!(v.is_empty()); - /// - /// v.push('a'); - /// assert!(!v.is_empty()); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn is_empty(&self) -> bool { - self.len() == 0 - } - - /// Splits the string into two at the given byte index. - /// - /// Returns a newly allocated `String`. `self` contains bytes `[0, at)`, and - /// the returned `String` contains bytes `[at, len)`. `at` must be on the - /// boundary of a UTF-8 code point. - /// - /// Note that the capacity of `self` does not change. - /// - /// # Panics - /// - /// Panics if `at` is not on a `UTF-8` code point boundary, or if it is beyond the last - /// code point of the string. - /// - /// # Examples - /// - /// ``` - /// # fn main() { - /// let mut hello = String::from("Hello, World!"); - /// let world = hello.split_off(7); - /// assert_eq!(hello, "Hello, "); - /// assert_eq!(world, "World!"); - /// # } - /// ``` - #[cfg(not(no_global_oom_handling))] - #[inline] - #[stable(feature = "string_split_off", since = "1.16.0")] - #[must_use = "use `.truncate()` if you don't need the other half"] - pub fn split_off(&mut self, at: usize) -> String { - assert!(self.is_char_boundary(at)); - let other = self.vec.split_off(at); - unsafe { String::from_utf8_unchecked(other) } - } - - /// Truncates this `String`, removing all contents. - /// - /// While this means the `String` will have a length of zero, it does not - /// touch its capacity. - /// - /// # Examples - /// - /// ``` - /// let mut s = String::from("foo"); - /// - /// s.clear(); - /// - /// assert!(s.is_empty()); - /// assert_eq!(0, s.len()); - /// assert_eq!(3, s.capacity()); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn clear(&mut self) { - self.vec.clear() - } - - /// Removes the specified range from the string in bulk, returning all - /// removed characters as an iterator. - /// - /// The returned iterator keeps a mutable borrow on the string to optimize - /// its implementation. - /// - /// # Panics - /// - /// Panics if the starting point or end point do not lie on a [`char`] - /// boundary, or if they're out of bounds. - /// - /// # Leaking - /// - /// If the returned iterator goes out of scope without being dropped (due to - /// [`core::mem::forget`], for example), the string may still contain a copy - /// of any drained characters, or may have lost characters arbitrarily, - /// including characters outside the range. - /// - /// # Examples - /// - /// ``` - /// let mut s = String::from("α is alpha, β is beta"); - /// let beta_offset = s.find('β').unwrap_or(s.len()); - /// - /// // Remove the range up until the β from the string - /// let t: String = s.drain(..beta_offset).collect(); - /// assert_eq!(t, "α is alpha, "); - /// assert_eq!(s, "β is beta"); - /// - /// // A full range clears the string, like `clear()` does - /// s.drain(..); - /// assert_eq!(s, ""); - /// ``` - #[stable(feature = "drain", since = "1.6.0")] - pub fn drain(&mut self, range: R) -> Drain<'_> - where - R: RangeBounds, - { - // Memory safety - // - // The String version of Drain does not have the memory safety issues - // of the vector version. The data is just plain bytes. - // Because the range removal happens in Drop, if the Drain iterator is leaked, - // the removal will not happen. - let Range { start, end } = slice::range(range, ..self.len()); - assert!(self.is_char_boundary(start)); - assert!(self.is_char_boundary(end)); - - // Take out two simultaneous borrows. The &mut String won't be accessed - // until iteration is over, in Drop. - let self_ptr = self as *mut _; - // SAFETY: `slice::range` and `is_char_boundary` do the appropriate bounds checks. - let chars_iter = unsafe { self.get_unchecked(start..end) }.chars(); - - Drain { start, end, iter: chars_iter, string: self_ptr } - } - - /// Removes the specified range in the string, - /// and replaces it with the given string. - /// The given string doesn't need to be the same length as the range. - /// - /// # Panics - /// - /// Panics if the starting point or end point do not lie on a [`char`] - /// boundary, or if they're out of bounds. - /// - /// # Examples - /// - /// ``` - /// let mut s = String::from("α is alpha, β is beta"); - /// let beta_offset = s.find('β').unwrap_or(s.len()); - /// - /// // Replace the range up until the β from the string - /// s.replace_range(..beta_offset, "Α is capital alpha; "); - /// assert_eq!(s, "Α is capital alpha; β is beta"); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[stable(feature = "splice", since = "1.27.0")] - pub fn replace_range(&mut self, range: R, replace_with: &str) - where - R: RangeBounds, - { - // Memory safety - // - // Replace_range does not have the memory safety issues of a vector Splice. - // of the vector version. The data is just plain bytes. - - // WARNING: Inlining this variable would be unsound (#81138) - let start = range.start_bound(); - match start { - Included(&n) => assert!(self.is_char_boundary(n)), - Excluded(&n) => assert!(self.is_char_boundary(n + 1)), - Unbounded => {} - }; - // WARNING: Inlining this variable would be unsound (#81138) - let end = range.end_bound(); - match end { - Included(&n) => assert!(self.is_char_boundary(n + 1)), - Excluded(&n) => assert!(self.is_char_boundary(n)), - Unbounded => {} - }; - - // Using `range` again would be unsound (#81138) - // We assume the bounds reported by `range` remain the same, but - // an adversarial implementation could change between calls - unsafe { self.as_mut_vec() }.splice((start, end), replace_with.bytes()); - } - - /// Converts this `String` into a [Box]<[str]>. - /// - /// Before doing the conversion, this method discards excess capacity like [`shrink_to_fit`]. - /// Note that this call may reallocate and copy the bytes of the string. - /// - /// [`shrink_to_fit`]: String::shrink_to_fit - /// [str]: prim@str "str" - /// - /// # Examples - /// - /// ``` - /// let s = String::from("hello"); - /// - /// let b = s.into_boxed_str(); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[stable(feature = "box_str", since = "1.4.0")] - #[must_use = "`self` will be dropped if the result is not used"] - #[inline] - pub fn into_boxed_str(self) -> Box { - let slice = self.vec.into_boxed_slice(); - unsafe { from_boxed_utf8_unchecked(slice) } - } - - /// Consumes and leaks the `String`, returning a mutable reference to the contents, - /// `&'a mut str`. - /// - /// The caller has free choice over the returned lifetime, including `'static`. Indeed, - /// this function is ideally used for data that lives for the remainder of the program's life, - /// as dropping the returned reference will cause a memory leak. - /// - /// It does not reallocate or shrink the `String`, so the leaked allocation may include unused - /// capacity that is not part of the returned slice. If you want to discard excess capacity, - /// call [`into_boxed_str`], and then [`Box::leak`] instead. However, keep in mind that - /// trimming the capacity may result in a reallocation and copy. - /// - /// [`into_boxed_str`]: Self::into_boxed_str - /// - /// # Examples - /// - /// ``` - /// let x = String::from("bucket"); - /// let static_ref: &'static mut str = x.leak(); - /// assert_eq!(static_ref, "bucket"); - /// ``` - #[stable(feature = "string_leak", since = "1.72.0")] - #[inline] - pub fn leak<'a>(self) -> &'a mut str { - let slice = self.vec.leak(); - unsafe { from_utf8_unchecked_mut(slice) } - } -} - -impl FromUtf8Error { - /// Returns a slice of [`u8`]s bytes that were attempted to convert to a `String`. - /// - /// # Examples - /// - /// ``` - /// // some invalid bytes, in a vector - /// let bytes = vec![0, 159]; - /// - /// let value = String::from_utf8(bytes); - /// - /// assert_eq!(&[0, 159], value.unwrap_err().as_bytes()); - /// ``` - #[must_use] - #[stable(feature = "from_utf8_error_as_bytes", since = "1.26.0")] - pub fn as_bytes(&self) -> &[u8] { - &self.bytes[..] - } - - /// Returns the bytes that were attempted to convert to a `String`. - /// - /// This method is carefully constructed to avoid allocation. It will - /// consume the error, moving out the bytes, so that a copy of the bytes - /// does not need to be made. - /// - /// # Examples - /// - /// ``` - /// // some invalid bytes, in a vector - /// let bytes = vec![0, 159]; - /// - /// let value = String::from_utf8(bytes); - /// - /// assert_eq!(vec![0, 159], value.unwrap_err().into_bytes()); - /// ``` - #[must_use = "`self` will be dropped if the result is not used"] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn into_bytes(self) -> Vec { - self.bytes - } - - /// Fetch a `Utf8Error` to get more details about the conversion failure. - /// - /// The [`Utf8Error`] type provided by [`std::str`] represents an error that may - /// occur when converting a slice of [`u8`]s to a [`&str`]. In this sense, it's - /// an analogue to `FromUtf8Error`. See its documentation for more details - /// on using it. - /// - /// [`std::str`]: core::str "std::str" - /// [`&str`]: prim@str "&str" - /// - /// # Examples - /// - /// ``` - /// // some invalid bytes, in a vector - /// let bytes = vec![0, 159]; - /// - /// let error = String::from_utf8(bytes).unwrap_err().utf8_error(); - /// - /// // the first byte is invalid here - /// assert_eq!(1, error.valid_up_to()); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn utf8_error(&self) -> Utf8Error { - self.error - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for FromUtf8Error { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt(&self.error, f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for FromUtf16Error { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt("invalid utf-16: lone surrogate found", f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Error for FromUtf8Error { - #[allow(deprecated)] - fn description(&self) -> &str { - "invalid utf-8" - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Error for FromUtf16Error { - #[allow(deprecated)] - fn description(&self) -> &str { - "invalid utf-16" - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for String { - fn clone(&self) -> Self { - String { vec: self.vec.clone() } - } - - /// Clones the contents of `source` into `self`. - /// - /// This method is preferred over simply assigning `source.clone()` to `self`, - /// as it avoids reallocation if possible. - fn clone_from(&mut self, source: &Self) { - self.vec.clone_from(&source.vec); - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl FromIterator for String { - fn from_iter>(iter: I) -> String { - let mut buf = String::new(); - buf.extend(iter); - buf - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "string_from_iter_by_ref", since = "1.17.0")] -impl<'a> FromIterator<&'a char> for String { - fn from_iter>(iter: I) -> String { - let mut buf = String::new(); - buf.extend(iter); - buf - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a> FromIterator<&'a str> for String { - fn from_iter>(iter: I) -> String { - let mut buf = String::new(); - buf.extend(iter); - buf - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "extend_string", since = "1.4.0")] -impl FromIterator for String { - fn from_iter>(iter: I) -> String { - let mut iterator = iter.into_iter(); - - // Because we're iterating over `String`s, we can avoid at least - // one allocation by getting the first string from the iterator - // and appending to it all the subsequent strings. - match iterator.next() { - None => String::new(), - Some(mut buf) => { - buf.extend(iterator); - buf - } - } - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "box_str2", since = "1.45.0")] -impl FromIterator> for String { - fn from_iter>>(iter: I) -> String { - let mut buf = String::new(); - buf.extend(iter); - buf - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "herd_cows", since = "1.19.0")] -impl<'a> FromIterator> for String { - fn from_iter>>(iter: I) -> String { - let mut iterator = iter.into_iter(); - - // Because we're iterating over CoWs, we can (potentially) avoid at least - // one allocation by getting the first item and appending to it all the - // subsequent items. - match iterator.next() { - None => String::new(), - Some(cow) => { - let mut buf = cow.into_owned(); - buf.extend(iterator); - buf - } - } - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl Extend for String { - fn extend>(&mut self, iter: I) { - let iterator = iter.into_iter(); - let (lower_bound, _) = iterator.size_hint(); - self.reserve(lower_bound); - iterator.for_each(move |c| self.push(c)); - } - - #[inline] - fn extend_one(&mut self, c: char) { - self.push(c); - } - - #[inline] - fn extend_reserve(&mut self, additional: usize) { - self.reserve(additional); - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "extend_ref", since = "1.2.0")] -impl<'a> Extend<&'a char> for String { - fn extend>(&mut self, iter: I) { - self.extend(iter.into_iter().cloned()); - } - - #[inline] - fn extend_one(&mut self, &c: &'a char) { - self.push(c); - } - - #[inline] - fn extend_reserve(&mut self, additional: usize) { - self.reserve(additional); - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a> Extend<&'a str> for String { - fn extend>(&mut self, iter: I) { - iter.into_iter().for_each(move |s| self.push_str(s)); - } - - #[inline] - fn extend_one(&mut self, s: &'a str) { - self.push_str(s); - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "box_str2", since = "1.45.0")] -impl Extend> for String { - fn extend>>(&mut self, iter: I) { - iter.into_iter().for_each(move |s| self.push_str(&s)); - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "extend_string", since = "1.4.0")] -impl Extend for String { - fn extend>(&mut self, iter: I) { - iter.into_iter().for_each(move |s| self.push_str(&s)); - } - - #[inline] - fn extend_one(&mut self, s: String) { - self.push_str(&s); - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "herd_cows", since = "1.19.0")] -impl<'a> Extend> for String { - fn extend>>(&mut self, iter: I) { - iter.into_iter().for_each(move |s| self.push_str(&s)); - } - - #[inline] - fn extend_one(&mut self, s: Cow<'a, str>) { - self.push_str(&s); - } -} - -/// A convenience impl that delegates to the impl for `&str`. -/// -/// # Examples -/// -/// ``` -/// assert_eq!(String::from("Hello world").find("world"), Some(6)); -/// ``` -#[unstable( - feature = "pattern", - reason = "API not fully fleshed out and ready to be stabilized", - issue = "27721" -)] -impl<'a, 'b> Pattern<'a> for &'b String { - type Searcher = <&'b str as Pattern<'a>>::Searcher; - - fn into_searcher(self, haystack: &'a str) -> <&'b str as Pattern<'a>>::Searcher { - self[..].into_searcher(haystack) - } - - #[inline] - fn is_contained_in(self, haystack: &'a str) -> bool { - self[..].is_contained_in(haystack) - } - - #[inline] - fn is_prefix_of(self, haystack: &'a str) -> bool { - self[..].is_prefix_of(haystack) - } - - #[inline] - fn strip_prefix_of(self, haystack: &'a str) -> Option<&'a str> { - self[..].strip_prefix_of(haystack) - } - - #[inline] - fn is_suffix_of(self, haystack: &'a str) -> bool { - self[..].is_suffix_of(haystack) - } - - #[inline] - fn strip_suffix_of(self, haystack: &'a str) -> Option<&'a str> { - self[..].strip_suffix_of(haystack) - } -} - -macro_rules! impl_eq { - ($lhs:ty, $rhs: ty) => { - #[stable(feature = "rust1", since = "1.0.0")] - #[allow(unused_lifetimes)] - impl<'a, 'b> PartialEq<$rhs> for $lhs { - #[inline] - fn eq(&self, other: &$rhs) -> bool { - PartialEq::eq(&self[..], &other[..]) - } - #[inline] - fn ne(&self, other: &$rhs) -> bool { - PartialEq::ne(&self[..], &other[..]) - } - } - - #[stable(feature = "rust1", since = "1.0.0")] - #[allow(unused_lifetimes)] - impl<'a, 'b> PartialEq<$lhs> for $rhs { - #[inline] - fn eq(&self, other: &$lhs) -> bool { - PartialEq::eq(&self[..], &other[..]) - } - #[inline] - fn ne(&self, other: &$lhs) -> bool { - PartialEq::ne(&self[..], &other[..]) - } - } - }; -} - -impl_eq! { String, str } -impl_eq! { String, &'a str } -#[cfg(not(no_global_oom_handling))] -impl_eq! { Cow<'a, str>, str } -#[cfg(not(no_global_oom_handling))] -impl_eq! { Cow<'a, str>, &'b str } -#[cfg(not(no_global_oom_handling))] -impl_eq! { Cow<'a, str>, String } - -#[stable(feature = "rust1", since = "1.0.0")] -impl Default for String { - /// Creates an empty `String`. - #[inline] - fn default() -> String { - String::new() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for String { - #[inline] - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt(&**self, f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for String { - #[inline] - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&**self, f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl hash::Hash for String { - #[inline] - fn hash(&self, hasher: &mut H) { - (**self).hash(hasher) - } -} - -/// Implements the `+` operator for concatenating two strings. -/// -/// This consumes the `String` on the left-hand side and re-uses its buffer (growing it if -/// necessary). This is done to avoid allocating a new `String` and copying the entire contents on -/// every operation, which would lead to *O*(*n*^2) running time when building an *n*-byte string by -/// repeated concatenation. -/// -/// The string on the right-hand side is only borrowed; its contents are copied into the returned -/// `String`. -/// -/// # Examples -/// -/// Concatenating two `String`s takes the first by value and borrows the second: -/// -/// ``` -/// let a = String::from("hello"); -/// let b = String::from(" world"); -/// let c = a + &b; -/// // `a` is moved and can no longer be used here. -/// ``` -/// -/// If you want to keep using the first `String`, you can clone it and append to the clone instead: -/// -/// ``` -/// let a = String::from("hello"); -/// let b = String::from(" world"); -/// let c = a.clone() + &b; -/// // `a` is still valid here. -/// ``` -/// -/// Concatenating `&str` slices can be done by converting the first to a `String`: -/// -/// ``` -/// let a = "hello"; -/// let b = " world"; -/// let c = a.to_string() + b; -/// ``` -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl Add<&str> for String { - type Output = String; - - #[inline] - fn add(mut self, other: &str) -> String { - self.push_str(other); - self - } -} - -/// Implements the `+=` operator for appending to a `String`. -/// -/// This has the same behavior as the [`push_str`][String::push_str] method. -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "stringaddassign", since = "1.12.0")] -impl AddAssign<&str> for String { - #[inline] - fn add_assign(&mut self, other: &str) { - self.push_str(other); - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ops::Index for String -where - I: slice::SliceIndex, -{ - type Output = I::Output; - - #[inline] - fn index(&self, index: I) -> &I::Output { - index.index(self.as_str()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ops::IndexMut for String -where - I: slice::SliceIndex, -{ - #[inline] - fn index_mut(&mut self, index: I) -> &mut I::Output { - index.index_mut(self.as_mut_str()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ops::Deref for String { - type Target = str; - - #[inline] - fn deref(&self) -> &str { - unsafe { str::from_utf8_unchecked(&self.vec) } - } -} - -#[unstable(feature = "deref_pure_trait", issue = "87121")] -unsafe impl ops::DerefPure for String {} - -#[stable(feature = "derefmut_for_string", since = "1.3.0")] -impl ops::DerefMut for String { - #[inline] - fn deref_mut(&mut self) -> &mut str { - unsafe { str::from_utf8_unchecked_mut(&mut *self.vec) } - } -} - -/// A type alias for [`Infallible`]. -/// -/// This alias exists for backwards compatibility, and may be eventually deprecated. -/// -/// [`Infallible`]: core::convert::Infallible "convert::Infallible" -#[stable(feature = "str_parse_error", since = "1.5.0")] -pub type ParseError = core::convert::Infallible; - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl FromStr for String { - type Err = core::convert::Infallible; - #[inline] - fn from_str(s: &str) -> Result { - Ok(String::from(s)) - } -} - -/// A trait for converting a value to a `String`. -/// -/// This trait is automatically implemented for any type which implements the -/// [`Display`] trait. As such, `ToString` shouldn't be implemented directly: -/// [`Display`] should be implemented instead, and you get the `ToString` -/// implementation for free. -/// -/// [`Display`]: fmt::Display -#[cfg_attr(not(test), rustc_diagnostic_item = "ToString")] -#[stable(feature = "rust1", since = "1.0.0")] -pub trait ToString { - /// Converts the given value to a `String`. - /// - /// # Examples - /// - /// ``` - /// let i = 5; - /// let five = String::from("5"); - /// - /// assert_eq!(five, i.to_string()); - /// ``` - #[rustc_conversion_suggestion] - #[stable(feature = "rust1", since = "1.0.0")] - #[cfg_attr(not(test), rustc_diagnostic_item = "to_string_method")] - fn to_string(&self) -> String; -} - -/// # Panics -/// -/// In this implementation, the `to_string` method panics -/// if the `Display` implementation returns an error. -/// This indicates an incorrect `Display` implementation -/// since `fmt::Write for String` never returns an error itself. -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl ToString for T { - // A common guideline is to not inline generic functions. However, - // removing `#[inline]` from this method causes non-negligible regressions. - // See , the last attempt - // to try to remove it. - #[inline] - default fn to_string(&self) -> String { - let mut buf = String::new(); - let mut formatter = core::fmt::Formatter::new(&mut buf); - // Bypass format_args!() to avoid write_str with zero-length strs - fmt::Display::fmt(self, &mut formatter) - .expect("a Display implementation returned an error unexpectedly"); - buf - } -} - -#[doc(hidden)] -#[cfg(not(no_global_oom_handling))] -#[unstable(feature = "ascii_char", issue = "110998")] -impl ToString for core::ascii::Char { - #[inline] - fn to_string(&self) -> String { - self.as_str().to_owned() - } -} - -#[doc(hidden)] -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "char_to_string_specialization", since = "1.46.0")] -impl ToString for char { - #[inline] - fn to_string(&self) -> String { - String::from(self.encode_utf8(&mut [0; 4])) - } -} - -#[doc(hidden)] -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "bool_to_string_specialization", since = "1.68.0")] -impl ToString for bool { - #[inline] - fn to_string(&self) -> String { - String::from(if *self { "true" } else { "false" }) - } -} - -#[doc(hidden)] -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "u8_to_string_specialization", since = "1.54.0")] -impl ToString for u8 { - #[inline] - fn to_string(&self) -> String { - let mut buf = String::with_capacity(3); - let mut n = *self; - if n >= 10 { - if n >= 100 { - buf.push((b'0' + n / 100) as char); - n %= 100; - } - buf.push((b'0' + n / 10) as char); - n %= 10; - } - buf.push((b'0' + n) as char); - buf - } -} - -#[doc(hidden)] -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "i8_to_string_specialization", since = "1.54.0")] -impl ToString for i8 { - #[inline] - fn to_string(&self) -> String { - let mut buf = String::with_capacity(4); - if self.is_negative() { - buf.push('-'); - } - let mut n = self.unsigned_abs(); - if n >= 10 { - if n >= 100 { - buf.push('1'); - n -= 100; - } - buf.push((b'0' + n / 10) as char); - n %= 10; - } - buf.push((b'0' + n) as char); - buf - } -} - -#[doc(hidden)] -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "str_to_string_specialization", since = "1.9.0")] -impl ToString for str { - #[inline] - fn to_string(&self) -> String { - String::from(self) - } -} - -#[doc(hidden)] -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "cow_str_to_string_specialization", since = "1.17.0")] -impl ToString for Cow<'_, str> { - #[inline] - fn to_string(&self) -> String { - self[..].to_owned() - } -} - -#[doc(hidden)] -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "string_to_string_specialization", since = "1.17.0")] -impl ToString for String { - #[inline] - fn to_string(&self) -> String { - self.to_owned() - } -} - -#[doc(hidden)] -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "fmt_arguments_to_string_specialization", since = "1.71.0")] -impl ToString for fmt::Arguments<'_> { - #[inline] - fn to_string(&self) -> String { - crate::fmt::format(*self) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef for String { - #[inline] - fn as_ref(&self) -> &str { - self - } -} - -#[stable(feature = "string_as_mut", since = "1.43.0")] -impl AsMut for String { - #[inline] - fn as_mut(&mut self) -> &mut str { - self - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef<[u8]> for String { - #[inline] - fn as_ref(&self) -> &[u8] { - self.as_bytes() - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl From<&str> for String { - /// Converts a `&str` into a [`String`]. - /// - /// The result is allocated on the heap. - #[inline] - fn from(s: &str) -> String { - s.to_owned() - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "from_mut_str_for_string", since = "1.44.0")] -impl From<&mut str> for String { - /// Converts a `&mut str` into a [`String`]. - /// - /// The result is allocated on the heap. - #[inline] - fn from(s: &mut str) -> String { - s.to_owned() - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "from_ref_string", since = "1.35.0")] -impl From<&String> for String { - /// Converts a `&String` into a [`String`]. - /// - /// This clones `s` and returns the clone. - #[inline] - fn from(s: &String) -> String { - s.clone() - } -} - -// note: test pulls in std, which causes errors here -#[cfg(not(test))] -#[stable(feature = "string_from_box", since = "1.18.0")] -impl From> for String { - /// Converts the given boxed `str` slice to a [`String`]. - /// It is notable that the `str` slice is owned. - /// - /// # Examples - /// - /// ``` - /// let s1: String = String::from("hello world"); - /// let s2: Box = s1.into_boxed_str(); - /// let s3: String = String::from(s2); - /// - /// assert_eq!("hello world", s3) - /// ``` - fn from(s: Box) -> String { - s.into_string() - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "box_from_str", since = "1.20.0")] -impl From for Box { - /// Converts the given [`String`] to a boxed `str` slice that is owned. - /// - /// # Examples - /// - /// ``` - /// let s1: String = String::from("hello world"); - /// let s2: Box = Box::from(s1); - /// let s3: String = String::from(s2); - /// - /// assert_eq!("hello world", s3) - /// ``` - fn from(s: String) -> Box { - s.into_boxed_str() - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "string_from_cow_str", since = "1.14.0")] -impl<'a> From> for String { - /// Converts a clone-on-write string to an owned - /// instance of [`String`]. - /// - /// This extracts the owned string, - /// clones the string if it is not already owned. - /// - /// # Example - /// - /// ``` - /// # use std::borrow::Cow; - /// // If the string is not owned... - /// let cow: Cow<'_, str> = Cow::Borrowed("eggplant"); - /// // It will allocate on the heap and copy the string. - /// let owned: String = String::from(cow); - /// assert_eq!(&owned[..], "eggplant"); - /// ``` - fn from(s: Cow<'a, str>) -> String { - s.into_owned() - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a> From<&'a str> for Cow<'a, str> { - /// Converts a string slice into a [`Borrowed`] variant. - /// No heap allocation is performed, and the string - /// is not copied. - /// - /// # Example - /// - /// ``` - /// # use std::borrow::Cow; - /// assert_eq!(Cow::from("eggplant"), Cow::Borrowed("eggplant")); - /// ``` - /// - /// [`Borrowed`]: crate::borrow::Cow::Borrowed "borrow::Cow::Borrowed" - #[inline] - fn from(s: &'a str) -> Cow<'a, str> { - Cow::Borrowed(s) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a> From for Cow<'a, str> { - /// Converts a [`String`] into an [`Owned`] variant. - /// No heap allocation is performed, and the string - /// is not copied. - /// - /// # Example - /// - /// ``` - /// # use std::borrow::Cow; - /// let s = "eggplant".to_string(); - /// let s2 = "eggplant".to_string(); - /// assert_eq!(Cow::from(s), Cow::<'static, str>::Owned(s2)); - /// ``` - /// - /// [`Owned`]: crate::borrow::Cow::Owned "borrow::Cow::Owned" - #[inline] - fn from(s: String) -> Cow<'a, str> { - Cow::Owned(s) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "cow_from_string_ref", since = "1.28.0")] -impl<'a> From<&'a String> for Cow<'a, str> { - /// Converts a [`String`] reference into a [`Borrowed`] variant. - /// No heap allocation is performed, and the string - /// is not copied. - /// - /// # Example - /// - /// ``` - /// # use std::borrow::Cow; - /// let s = "eggplant".to_string(); - /// assert_eq!(Cow::from(&s), Cow::Borrowed("eggplant")); - /// ``` - /// - /// [`Borrowed`]: crate::borrow::Cow::Borrowed "borrow::Cow::Borrowed" - #[inline] - fn from(s: &'a String) -> Cow<'a, str> { - Cow::Borrowed(s.as_str()) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "cow_str_from_iter", since = "1.12.0")] -impl<'a> FromIterator for Cow<'a, str> { - fn from_iter>(it: I) -> Cow<'a, str> { - Cow::Owned(FromIterator::from_iter(it)) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "cow_str_from_iter", since = "1.12.0")] -impl<'a, 'b> FromIterator<&'b str> for Cow<'a, str> { - fn from_iter>(it: I) -> Cow<'a, str> { - Cow::Owned(FromIterator::from_iter(it)) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "cow_str_from_iter", since = "1.12.0")] -impl<'a> FromIterator for Cow<'a, str> { - fn from_iter>(it: I) -> Cow<'a, str> { - Cow::Owned(FromIterator::from_iter(it)) - } -} - -#[stable(feature = "from_string_for_vec_u8", since = "1.14.0")] -impl From for Vec { - /// Converts the given [`String`] to a vector [`Vec`] that holds values of type [`u8`]. - /// - /// # Examples - /// - /// ``` - /// let s1 = String::from("hello world"); - /// let v1 = Vec::from(s1); - /// - /// for b in v1 { - /// println!("{b}"); - /// } - /// ``` - fn from(string: String) -> Vec { - string.into_bytes() - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Write for String { - #[inline] - fn write_str(&mut self, s: &str) -> fmt::Result { - self.push_str(s); - Ok(()) - } - - #[inline] - fn write_char(&mut self, c: char) -> fmt::Result { - self.push(c); - Ok(()) - } -} - -/// A draining iterator for `String`. -/// -/// This struct is created by the [`drain`] method on [`String`]. See its -/// documentation for more. -/// -/// [`drain`]: String::drain -#[stable(feature = "drain", since = "1.6.0")] -pub struct Drain<'a> { - /// Will be used as &'a mut String in the destructor - string: *mut String, - /// Start of part to remove - start: usize, - /// End of part to remove - end: usize, - /// Current remaining range to remove - iter: Chars<'a>, -} - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl fmt::Debug for Drain<'_> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("Drain").field(&self.as_str()).finish() - } -} - -#[stable(feature = "drain", since = "1.6.0")] -unsafe impl Sync for Drain<'_> {} -#[stable(feature = "drain", since = "1.6.0")] -unsafe impl Send for Drain<'_> {} - -#[stable(feature = "drain", since = "1.6.0")] -impl Drop for Drain<'_> { - fn drop(&mut self) { - unsafe { - // Use Vec::drain. "Reaffirm" the bounds checks to avoid - // panic code being inserted again. - let self_vec = (*self.string).as_mut_vec(); - if self.start <= self.end && self.end <= self_vec.len() { - self_vec.drain(self.start..self.end); - } - } - } -} - -impl<'a> Drain<'a> { - /// Returns the remaining (sub)string of this iterator as a slice. - /// - /// # Examples - /// - /// ``` - /// let mut s = String::from("abc"); - /// let mut drain = s.drain(..); - /// assert_eq!(drain.as_str(), "abc"); - /// let _ = drain.next().unwrap(); - /// assert_eq!(drain.as_str(), "bc"); - /// ``` - #[must_use] - #[stable(feature = "string_drain_as_str", since = "1.55.0")] - pub fn as_str(&self) -> &str { - self.iter.as_str() - } -} - -#[stable(feature = "string_drain_as_str", since = "1.55.0")] -impl<'a> AsRef for Drain<'a> { - fn as_ref(&self) -> &str { - self.as_str() - } -} - -#[stable(feature = "string_drain_as_str", since = "1.55.0")] -impl<'a> AsRef<[u8]> for Drain<'a> { - fn as_ref(&self) -> &[u8] { - self.as_str().as_bytes() - } -} - -#[stable(feature = "drain", since = "1.6.0")] -impl Iterator for Drain<'_> { - type Item = char; - - #[inline] - fn next(&mut self) -> Option { - self.iter.next() - } - - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } - - #[inline] - fn last(mut self) -> Option { - self.next_back() - } -} - -#[stable(feature = "drain", since = "1.6.0")] -impl DoubleEndedIterator for Drain<'_> { - #[inline] - fn next_back(&mut self) -> Option { - self.iter.next_back() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Drain<'_> {} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "from_char_for_string", since = "1.46.0")] -impl From for String { - /// Allocates an owned [`String`] from a single character. - /// - /// # Example - /// ```rust - /// let c: char = 'a'; - /// let s: String = String::from(c); - /// assert_eq!("a", &s[..]); - /// ``` - #[inline] - fn from(c: char) -> Self { - c.to_string() - } -} diff --git a/library/alloc/src/sync.rs b/library/alloc/src/sync.rs deleted file mode 100644 index 7dcaa59dcd1c7..0000000000000 --- a/library/alloc/src/sync.rs +++ /dev/null @@ -1,3830 +0,0 @@ -#![stable(feature = "rust1", since = "1.0.0")] - -//! Thread-safe reference-counting pointers. -//! -//! See the [`Arc`][Arc] documentation for more details. -//! -//! **Note**: This module is only available on platforms that support atomic -//! loads and stores of pointers. This may be detected at compile time using -//! `#[cfg(target_has_atomic = "ptr")]`. - -use core::any::Any; -use core::borrow; -use core::cmp::Ordering; -use core::fmt; -use core::hash::{Hash, Hasher}; -use core::hint; -use core::intrinsics::abort; -#[cfg(not(no_global_oom_handling))] -use core::iter; -use core::marker::{PhantomData, Unsize}; -#[cfg(not(no_global_oom_handling))] -use core::mem::size_of_val; -use core::mem::{self, align_of_val_raw}; -use core::ops::{CoerceUnsized, Deref, DerefPure, DispatchFromDyn, Receiver}; -use core::panic::{RefUnwindSafe, UnwindSafe}; -use core::pin::Pin; -use core::ptr::{self, NonNull}; -#[cfg(not(no_global_oom_handling))] -use core::slice::from_raw_parts_mut; -use core::sync::atomic; -use core::sync::atomic::Ordering::{Acquire, Relaxed, Release}; - -#[cfg(not(no_global_oom_handling))] -use crate::alloc::handle_alloc_error; -#[cfg(not(no_global_oom_handling))] -use crate::alloc::WriteCloneIntoRaw; -use crate::alloc::{AllocError, Allocator, Global, Layout}; -use crate::borrow::{Cow, ToOwned}; -use crate::boxed::Box; -use crate::rc::is_dangling; -#[cfg(not(no_global_oom_handling))] -use crate::string::String; -#[cfg(not(no_global_oom_handling))] -use crate::vec::Vec; - -#[cfg(test)] -mod tests; - -/// A soft limit on the amount of references that may be made to an `Arc`. -/// -/// Going above this limit will abort your program (although not -/// necessarily) at _exactly_ `MAX_REFCOUNT + 1` references. -/// Trying to go above it might call a `panic` (if not actually going above it). -/// -/// This is a global invariant, and also applies when using a compare-exchange loop. -/// -/// See comment in `Arc::clone`. -const MAX_REFCOUNT: usize = (isize::MAX) as usize; - -/// The error in case either counter reaches above `MAX_REFCOUNT`, and we can `panic` safely. -const INTERNAL_OVERFLOW_ERROR: &str = "Arc counter overflow"; - -#[cfg(not(sanitize = "thread"))] -macro_rules! acquire { - ($x:expr) => { - atomic::fence(Acquire) - }; -} - -// ThreadSanitizer does not support memory fences. To avoid false positive -// reports in Arc / Weak implementation use atomic loads for synchronization -// instead. -#[cfg(sanitize = "thread")] -macro_rules! acquire { - ($x:expr) => { - $x.load(Acquire) - }; -} - -/// A thread-safe reference-counting pointer. 'Arc' stands for 'Atomically -/// Reference Counted'. -/// -/// The type `Arc` provides shared ownership of a value of type `T`, -/// allocated in the heap. Invoking [`clone`][clone] on `Arc` produces -/// a new `Arc` instance, which points to the same allocation on the heap as the -/// source `Arc`, while increasing a reference count. When the last `Arc` -/// pointer to a given allocation is destroyed, the value stored in that allocation (often -/// referred to as "inner value") is also dropped. -/// -/// Shared references in Rust disallow mutation by default, and `Arc` is no -/// exception: you cannot generally obtain a mutable reference to something -/// inside an `Arc`. If you need to mutate through an `Arc`, use -/// [`Mutex`][mutex], [`RwLock`][rwlock], or one of the [`Atomic`][atomic] -/// types. -/// -/// **Note**: This type is only available on platforms that support atomic -/// loads and stores of pointers, which includes all platforms that support -/// the `std` crate but not all those which only support [`alloc`](crate). -/// This may be detected at compile time using `#[cfg(target_has_atomic = "ptr")]`. -/// -/// ## Thread Safety -/// -/// Unlike [`Rc`], `Arc` uses atomic operations for its reference -/// counting. This means that it is thread-safe. The disadvantage is that -/// atomic operations are more expensive than ordinary memory accesses. If you -/// are not sharing reference-counted allocations between threads, consider using -/// [`Rc`] for lower overhead. [`Rc`] is a safe default, because the -/// compiler will catch any attempt to send an [`Rc`] between threads. -/// However, a library might choose `Arc` in order to give library consumers -/// more flexibility. -/// -/// `Arc` will implement [`Send`] and [`Sync`] as long as the `T` implements -/// [`Send`] and [`Sync`]. Why can't you put a non-thread-safe type `T` in an -/// `Arc` to make it thread-safe? This may be a bit counter-intuitive at -/// first: after all, isn't the point of `Arc` thread safety? The key is -/// this: `Arc` makes it thread safe to have multiple ownership of the same -/// data, but it doesn't add thread safety to its data. Consider -/// Arc<[RefCell\]>. [`RefCell`] isn't [`Sync`], and if `Arc` was always -/// [`Send`], Arc<[RefCell\]> would be as well. But then we'd have a problem: -/// [`RefCell`] is not thread safe; it keeps track of the borrowing count using -/// non-atomic operations. -/// -/// In the end, this means that you may need to pair `Arc` with some sort of -/// [`std::sync`] type, usually [`Mutex`][mutex]. -/// -/// ## Breaking cycles with `Weak` -/// -/// The [`downgrade`][downgrade] method can be used to create a non-owning -/// [`Weak`] pointer. A [`Weak`] pointer can be [`upgrade`][upgrade]d -/// to an `Arc`, but this will return [`None`] if the value stored in the allocation has -/// already been dropped. In other words, `Weak` pointers do not keep the value -/// inside the allocation alive; however, they *do* keep the allocation -/// (the backing store for the value) alive. -/// -/// A cycle between `Arc` pointers will never be deallocated. For this reason, -/// [`Weak`] is used to break cycles. For example, a tree could have -/// strong `Arc` pointers from parent nodes to children, and [`Weak`] -/// pointers from children back to their parents. -/// -/// # Cloning references -/// -/// Creating a new reference from an existing reference-counted pointer is done using the -/// `Clone` trait implemented for [`Arc`][Arc] and [`Weak`][Weak]. -/// -/// ``` -/// use std::sync::Arc; -/// let foo = Arc::new(vec![1.0, 2.0, 3.0]); -/// // The two syntaxes below are equivalent. -/// let a = foo.clone(); -/// let b = Arc::clone(&foo); -/// // a, b, and foo are all Arcs that point to the same memory location -/// ``` -/// -/// ## `Deref` behavior -/// -/// `Arc` automatically dereferences to `T` (via the [`Deref`] trait), -/// so you can call `T`'s methods on a value of type `Arc`. To avoid name -/// clashes with `T`'s methods, the methods of `Arc` itself are associated -/// functions, called using [fully qualified syntax]: -/// -/// ``` -/// use std::sync::Arc; -/// -/// let my_arc = Arc::new(()); -/// let my_weak = Arc::downgrade(&my_arc); -/// ``` -/// -/// `Arc`'s implementations of traits like `Clone` may also be called using -/// fully qualified syntax. Some people prefer to use fully qualified syntax, -/// while others prefer using method-call syntax. -/// -/// ``` -/// use std::sync::Arc; -/// -/// let arc = Arc::new(()); -/// // Method-call syntax -/// let arc2 = arc.clone(); -/// // Fully qualified syntax -/// let arc3 = Arc::clone(&arc); -/// ``` -/// -/// [`Weak`][Weak] does not auto-dereference to `T`, because the inner value may have -/// already been dropped. -/// -/// [`Rc`]: crate::rc::Rc -/// [clone]: Clone::clone -/// [mutex]: ../../std/sync/struct.Mutex.html -/// [rwlock]: ../../std/sync/struct.RwLock.html -/// [atomic]: core::sync::atomic -/// [downgrade]: Arc::downgrade -/// [upgrade]: Weak::upgrade -/// [RefCell\]: core::cell::RefCell -/// [`RefCell`]: core::cell::RefCell -/// [`std::sync`]: ../../std/sync/index.html -/// [`Arc::clone(&from)`]: Arc::clone -/// [fully qualified syntax]: https://doc.rust-lang.org/book/ch19-03-advanced-traits.html#fully-qualified-syntax-for-disambiguation-calling-methods-with-the-same-name -/// -/// # Examples -/// -/// Sharing some immutable data between threads: -/// -// Note that we **do not** run these tests here. The windows builders get super -// unhappy if a thread outlives the main thread and then exits at the same time -// (something deadlocks) so we just avoid this entirely by not running these -// tests. -/// ```no_run -/// use std::sync::Arc; -/// use std::thread; -/// -/// let five = Arc::new(5); -/// -/// for _ in 0..10 { -/// let five = Arc::clone(&five); -/// -/// thread::spawn(move || { -/// println!("{five:?}"); -/// }); -/// } -/// ``` -/// -/// Sharing a mutable [`AtomicUsize`]: -/// -/// [`AtomicUsize`]: core::sync::atomic::AtomicUsize "sync::atomic::AtomicUsize" -/// -/// ```no_run -/// use std::sync::Arc; -/// use std::sync::atomic::{AtomicUsize, Ordering}; -/// use std::thread; -/// -/// let val = Arc::new(AtomicUsize::new(5)); -/// -/// for _ in 0..10 { -/// let val = Arc::clone(&val); -/// -/// thread::spawn(move || { -/// let v = val.fetch_add(1, Ordering::Relaxed); -/// println!("{v:?}"); -/// }); -/// } -/// ``` -/// -/// See the [`rc` documentation][rc_examples] for more examples of reference -/// counting in general. -/// -/// [rc_examples]: crate::rc#examples -#[cfg_attr(not(test), rustc_diagnostic_item = "Arc")] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct Arc< - T: ?Sized, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, -> { - ptr: NonNull>, - phantom: PhantomData>, - alloc: A, -} - -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Send for Arc {} -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Sync for Arc {} - -#[stable(feature = "catch_unwind", since = "1.9.0")] -impl UnwindSafe for Arc {} - -#[unstable(feature = "coerce_unsized", issue = "18598")] -impl, U: ?Sized, A: Allocator> CoerceUnsized> for Arc {} - -#[unstable(feature = "dispatch_from_dyn", issue = "none")] -impl, U: ?Sized> DispatchFromDyn> for Arc {} - -impl Arc { - unsafe fn from_inner(ptr: NonNull>) -> Self { - unsafe { Self::from_inner_in(ptr, Global) } - } - - unsafe fn from_ptr(ptr: *mut ArcInner) -> Self { - unsafe { Self::from_ptr_in(ptr, Global) } - } -} - -impl Arc { - #[inline] - fn into_inner_with_allocator(this: Self) -> (NonNull>, A) { - let this = mem::ManuallyDrop::new(this); - (this.ptr, unsafe { ptr::read(&this.alloc) }) - } - - #[inline] - unsafe fn from_inner_in(ptr: NonNull>, alloc: A) -> Self { - Self { ptr, phantom: PhantomData, alloc } - } - - #[inline] - unsafe fn from_ptr_in(ptr: *mut ArcInner, alloc: A) -> Self { - unsafe { Self::from_inner_in(NonNull::new_unchecked(ptr), alloc) } - } -} - -/// `Weak` is a version of [`Arc`] that holds a non-owning reference to the -/// managed allocation. The allocation is accessed by calling [`upgrade`] on the `Weak` -/// pointer, which returns an [Option]<[Arc]\>. -/// -/// Since a `Weak` reference does not count towards ownership, it will not -/// prevent the value stored in the allocation from being dropped, and `Weak` itself makes no -/// guarantees about the value still being present. Thus it may return [`None`] -/// when [`upgrade`]d. Note however that a `Weak` reference *does* prevent the allocation -/// itself (the backing store) from being deallocated. -/// -/// A `Weak` pointer is useful for keeping a temporary reference to the allocation -/// managed by [`Arc`] without preventing its inner value from being dropped. It is also used to -/// prevent circular references between [`Arc`] pointers, since mutual owning references -/// would never allow either [`Arc`] to be dropped. For example, a tree could -/// have strong [`Arc`] pointers from parent nodes to children, and `Weak` -/// pointers from children back to their parents. -/// -/// The typical way to obtain a `Weak` pointer is to call [`Arc::downgrade`]. -/// -/// [`upgrade`]: Weak::upgrade -#[stable(feature = "arc_weak", since = "1.4.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "ArcWeak")] -pub struct Weak< - T: ?Sized, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, -> { - // This is a `NonNull` to allow optimizing the size of this type in enums, - // but it is not necessarily a valid pointer. - // `Weak::new` sets this to `usize::MAX` so that it doesn’t need - // to allocate space on the heap. That's not a value a real pointer - // will ever have because RcBox has alignment at least 2. - // This is only possible when `T: Sized`; unsized `T` never dangle. - ptr: NonNull>, - alloc: A, -} - -#[stable(feature = "arc_weak", since = "1.4.0")] -unsafe impl Send for Weak {} -#[stable(feature = "arc_weak", since = "1.4.0")] -unsafe impl Sync for Weak {} - -#[unstable(feature = "coerce_unsized", issue = "18598")] -impl, U: ?Sized, A: Allocator> CoerceUnsized> for Weak {} -#[unstable(feature = "dispatch_from_dyn", issue = "none")] -impl, U: ?Sized> DispatchFromDyn> for Weak {} - -#[stable(feature = "arc_weak", since = "1.4.0")] -impl fmt::Debug for Weak { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - write!(f, "(Weak)") - } -} - -// This is repr(C) to future-proof against possible field-reordering, which -// would interfere with otherwise safe [into|from]_raw() of transmutable -// inner types. -#[repr(C)] -struct ArcInner { - strong: atomic::AtomicUsize, - - // the value usize::MAX acts as a sentinel for temporarily "locking" the - // ability to upgrade weak pointers or downgrade strong ones; this is used - // to avoid races in `make_mut` and `get_mut`. - weak: atomic::AtomicUsize, - - data: T, -} - -/// Calculate layout for `ArcInner` using the inner value's layout -fn arcinner_layout_for_value_layout(layout: Layout) -> Layout { - // Calculate layout using the given value layout. - // Previously, layout was calculated on the expression - // `&*(ptr as *const ArcInner)`, but this created a misaligned - // reference (see #54908). - Layout::new::>().extend(layout).unwrap().0.pad_to_align() -} - -unsafe impl Send for ArcInner {} -unsafe impl Sync for ArcInner {} - -impl Arc { - /// Constructs a new `Arc`. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// let five = Arc::new(5); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn new(data: T) -> Arc { - // Start the weak pointer count as 1 which is the weak pointer that's - // held by all the strong pointers (kinda), see std/rc.rs for more info - let x: Box<_> = Box::new(ArcInner { - strong: atomic::AtomicUsize::new(1), - weak: atomic::AtomicUsize::new(1), - data, - }); - unsafe { Self::from_inner(Box::leak(x).into()) } - } - - /// Constructs a new `Arc` while giving you a `Weak` to the allocation, - /// to allow you to construct a `T` which holds a weak pointer to itself. - /// - /// Generally, a structure circularly referencing itself, either directly or - /// indirectly, should not hold a strong reference to itself to prevent a memory leak. - /// Using this function, you get access to the weak pointer during the - /// initialization of `T`, before the `Arc` is created, such that you can - /// clone and store it inside the `T`. - /// - /// `new_cyclic` first allocates the managed allocation for the `Arc`, - /// then calls your closure, giving it a `Weak` to this allocation, - /// and only afterwards completes the construction of the `Arc` by placing - /// the `T` returned from your closure into the allocation. - /// - /// Since the new `Arc` is not fully-constructed until `Arc::new_cyclic` - /// returns, calling [`upgrade`] on the weak reference inside your closure will - /// fail and result in a `None` value. - /// - /// # Panics - /// - /// If `data_fn` panics, the panic is propagated to the caller, and the - /// temporary [`Weak`] is dropped normally. - /// - /// # Example - /// - /// ``` - /// # #![allow(dead_code)] - /// use std::sync::{Arc, Weak}; - /// - /// struct Gadget { - /// me: Weak, - /// } - /// - /// impl Gadget { - /// /// Construct a reference counted Gadget. - /// fn new() -> Arc { - /// // `me` is a `Weak` pointing at the new allocation of the - /// // `Arc` we're constructing. - /// Arc::new_cyclic(|me| { - /// // Create the actual struct here. - /// Gadget { me: me.clone() } - /// }) - /// } - /// - /// /// Return a reference counted pointer to Self. - /// fn me(&self) -> Arc { - /// self.me.upgrade().unwrap() - /// } - /// } - /// ``` - /// [`upgrade`]: Weak::upgrade - #[cfg(not(no_global_oom_handling))] - #[inline] - #[stable(feature = "arc_new_cyclic", since = "1.60.0")] - pub fn new_cyclic(data_fn: F) -> Arc - where - F: FnOnce(&Weak) -> T, - { - // Construct the inner in the "uninitialized" state with a single - // weak reference. - let uninit_ptr: NonNull<_> = Box::leak(Box::new(ArcInner { - strong: atomic::AtomicUsize::new(0), - weak: atomic::AtomicUsize::new(1), - data: mem::MaybeUninit::::uninit(), - })) - .into(); - let init_ptr: NonNull> = uninit_ptr.cast(); - - let weak = Weak { ptr: init_ptr, alloc: Global }; - - // It's important we don't give up ownership of the weak pointer, or - // else the memory might be freed by the time `data_fn` returns. If - // we really wanted to pass ownership, we could create an additional - // weak pointer for ourselves, but this would result in additional - // updates to the weak reference count which might not be necessary - // otherwise. - let data = data_fn(&weak); - - // Now we can properly initialize the inner value and turn our weak - // reference into a strong reference. - let strong = unsafe { - let inner = init_ptr.as_ptr(); - ptr::write(ptr::addr_of_mut!((*inner).data), data); - - // The above write to the data field must be visible to any threads which - // observe a non-zero strong count. Therefore we need at least "Release" ordering - // in order to synchronize with the `compare_exchange_weak` in `Weak::upgrade`. - // - // "Acquire" ordering is not required. When considering the possible behaviours - // of `data_fn` we only need to look at what it could do with a reference to a - // non-upgradeable `Weak`: - // - It can *clone* the `Weak`, increasing the weak reference count. - // - It can drop those clones, decreasing the weak reference count (but never to zero). - // - // These side effects do not impact us in any way, and no other side effects are - // possible with safe code alone. - let prev_value = (*inner).strong.fetch_add(1, Release); - debug_assert_eq!(prev_value, 0, "No prior strong references should exist"); - - Arc::from_inner(init_ptr) - }; - - // Strong references should collectively own a shared weak reference, - // so don't run the destructor for our old weak reference. - mem::forget(weak); - strong - } - - /// Constructs a new `Arc` with uninitialized contents. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// #![feature(get_mut_unchecked)] - /// - /// use std::sync::Arc; - /// - /// let mut five = Arc::::new_uninit(); - /// - /// // Deferred initialization: - /// Arc::get_mut(&mut five).unwrap().write(5); - /// - /// let five = unsafe { five.assume_init() }; - /// - /// assert_eq!(*five, 5) - /// ``` - #[cfg(not(no_global_oom_handling))] - #[inline] - #[unstable(feature = "new_uninit", issue = "63291")] - #[must_use] - pub fn new_uninit() -> Arc> { - unsafe { - Arc::from_ptr(Arc::allocate_for_layout( - Layout::new::(), - |layout| Global.allocate(layout), - <*mut u8>::cast, - )) - } - } - - /// Constructs a new `Arc` with uninitialized contents, with the memory - /// being filled with `0` bytes. - /// - /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and incorrect usage - /// of this method. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// - /// use std::sync::Arc; - /// - /// let zero = Arc::::new_zeroed(); - /// let zero = unsafe { zero.assume_init() }; - /// - /// assert_eq!(*zero, 0) - /// ``` - /// - /// [zeroed]: mem::MaybeUninit::zeroed - #[cfg(not(no_global_oom_handling))] - #[inline] - #[unstable(feature = "new_uninit", issue = "63291")] - #[must_use] - pub fn new_zeroed() -> Arc> { - unsafe { - Arc::from_ptr(Arc::allocate_for_layout( - Layout::new::(), - |layout| Global.allocate_zeroed(layout), - <*mut u8>::cast, - )) - } - } - - /// Constructs a new `Pin>`. If `T` does not implement `Unpin`, then - /// `data` will be pinned in memory and unable to be moved. - #[cfg(not(no_global_oom_handling))] - #[stable(feature = "pin", since = "1.33.0")] - #[must_use] - pub fn pin(data: T) -> Pin> { - unsafe { Pin::new_unchecked(Arc::new(data)) } - } - - /// Constructs a new `Pin>`, return an error if allocation fails. - #[unstable(feature = "allocator_api", issue = "32838")] - #[inline] - pub fn try_pin(data: T) -> Result>, AllocError> { - unsafe { Ok(Pin::new_unchecked(Arc::try_new(data)?)) } - } - - /// Constructs a new `Arc`, returning an error if allocation fails. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// use std::sync::Arc; - /// - /// let five = Arc::try_new(5)?; - /// # Ok::<(), std::alloc::AllocError>(()) - /// ``` - #[unstable(feature = "allocator_api", issue = "32838")] - #[inline] - pub fn try_new(data: T) -> Result, AllocError> { - // Start the weak pointer count as 1 which is the weak pointer that's - // held by all the strong pointers (kinda), see std/rc.rs for more info - let x: Box<_> = Box::try_new(ArcInner { - strong: atomic::AtomicUsize::new(1), - weak: atomic::AtomicUsize::new(1), - data, - })?; - unsafe { Ok(Self::from_inner(Box::leak(x).into())) } - } - - /// Constructs a new `Arc` with uninitialized contents, returning an error - /// if allocation fails. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit, allocator_api)] - /// #![feature(get_mut_unchecked)] - /// - /// use std::sync::Arc; - /// - /// let mut five = Arc::::try_new_uninit()?; - /// - /// // Deferred initialization: - /// Arc::get_mut(&mut five).unwrap().write(5); - /// - /// let five = unsafe { five.assume_init() }; - /// - /// assert_eq!(*five, 5); - /// # Ok::<(), std::alloc::AllocError>(()) - /// ``` - #[unstable(feature = "allocator_api", issue = "32838")] - // #[unstable(feature = "new_uninit", issue = "63291")] - pub fn try_new_uninit() -> Result>, AllocError> { - unsafe { - Ok(Arc::from_ptr(Arc::try_allocate_for_layout( - Layout::new::(), - |layout| Global.allocate(layout), - <*mut u8>::cast, - )?)) - } - } - - /// Constructs a new `Arc` with uninitialized contents, with the memory - /// being filled with `0` bytes, returning an error if allocation fails. - /// - /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and incorrect usage - /// of this method. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit, allocator_api)] - /// - /// use std::sync::Arc; - /// - /// let zero = Arc::::try_new_zeroed()?; - /// let zero = unsafe { zero.assume_init() }; - /// - /// assert_eq!(*zero, 0); - /// # Ok::<(), std::alloc::AllocError>(()) - /// ``` - /// - /// [zeroed]: mem::MaybeUninit::zeroed - #[unstable(feature = "allocator_api", issue = "32838")] - // #[unstable(feature = "new_uninit", issue = "63291")] - pub fn try_new_zeroed() -> Result>, AllocError> { - unsafe { - Ok(Arc::from_ptr(Arc::try_allocate_for_layout( - Layout::new::(), - |layout| Global.allocate_zeroed(layout), - <*mut u8>::cast, - )?)) - } - } -} - -impl Arc { - /// Returns a reference to the underlying allocator. - /// - /// Note: this is an associated function, which means that you have - /// to call it as `Arc::allocator(&a)` instead of `a.allocator()`. This - /// is so that there is no conflict with a method on the inner type. - #[inline] - #[unstable(feature = "allocator_api", issue = "32838")] - pub fn allocator(this: &Self) -> &A { - &this.alloc - } - /// Constructs a new `Arc` in the provided allocator. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// - /// use std::sync::Arc; - /// use std::alloc::System; - /// - /// let five = Arc::new_in(5, System); - /// ``` - #[inline] - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "allocator_api", issue = "32838")] - pub fn new_in(data: T, alloc: A) -> Arc { - // Start the weak pointer count as 1 which is the weak pointer that's - // held by all the strong pointers (kinda), see std/rc.rs for more info - let x = Box::new_in( - ArcInner { - strong: atomic::AtomicUsize::new(1), - weak: atomic::AtomicUsize::new(1), - data, - }, - alloc, - ); - let (ptr, alloc) = Box::into_unique(x); - unsafe { Self::from_inner_in(ptr.into(), alloc) } - } - - /// Constructs a new `Arc` with uninitialized contents in the provided allocator. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// #![feature(get_mut_unchecked)] - /// #![feature(allocator_api)] - /// - /// use std::sync::Arc; - /// use std::alloc::System; - /// - /// let mut five = Arc::::new_uninit_in(System); - /// - /// let five = unsafe { - /// // Deferred initialization: - /// Arc::get_mut_unchecked(&mut five).as_mut_ptr().write(5); - /// - /// five.assume_init() - /// }; - /// - /// assert_eq!(*five, 5) - /// ``` - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "allocator_api", issue = "32838")] - // #[unstable(feature = "new_uninit", issue = "63291")] - #[inline] - pub fn new_uninit_in(alloc: A) -> Arc, A> { - unsafe { - Arc::from_ptr_in( - Arc::allocate_for_layout( - Layout::new::(), - |layout| alloc.allocate(layout), - <*mut u8>::cast, - ), - alloc, - ) - } - } - - /// Constructs a new `Arc` with uninitialized contents, with the memory - /// being filled with `0` bytes, in the provided allocator. - /// - /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and incorrect usage - /// of this method. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// #![feature(allocator_api)] - /// - /// use std::sync::Arc; - /// use std::alloc::System; - /// - /// let zero = Arc::::new_zeroed_in(System); - /// let zero = unsafe { zero.assume_init() }; - /// - /// assert_eq!(*zero, 0) - /// ``` - /// - /// [zeroed]: mem::MaybeUninit::zeroed - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "allocator_api", issue = "32838")] - // #[unstable(feature = "new_uninit", issue = "63291")] - #[inline] - pub fn new_zeroed_in(alloc: A) -> Arc, A> { - unsafe { - Arc::from_ptr_in( - Arc::allocate_for_layout( - Layout::new::(), - |layout| alloc.allocate_zeroed(layout), - <*mut u8>::cast, - ), - alloc, - ) - } - } - - /// Constructs a new `Pin>` in the provided allocator. If `T` does not implement `Unpin`, - /// then `data` will be pinned in memory and unable to be moved. - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "allocator_api", issue = "32838")] - #[inline] - pub fn pin_in(data: T, alloc: A) -> Pin> - where - A: 'static, - { - unsafe { Pin::new_unchecked(Arc::new_in(data, alloc)) } - } - - /// Constructs a new `Pin>` in the provided allocator, return an error if allocation - /// fails. - #[inline] - #[unstable(feature = "allocator_api", issue = "32838")] - pub fn try_pin_in(data: T, alloc: A) -> Result>, AllocError> - where - A: 'static, - { - unsafe { Ok(Pin::new_unchecked(Arc::try_new_in(data, alloc)?)) } - } - - /// Constructs a new `Arc` in the provided allocator, returning an error if allocation fails. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// - /// use std::sync::Arc; - /// use std::alloc::System; - /// - /// let five = Arc::try_new_in(5, System)?; - /// # Ok::<(), std::alloc::AllocError>(()) - /// ``` - #[inline] - #[unstable(feature = "allocator_api", issue = "32838")] - #[inline] - pub fn try_new_in(data: T, alloc: A) -> Result, AllocError> { - // Start the weak pointer count as 1 which is the weak pointer that's - // held by all the strong pointers (kinda), see std/rc.rs for more info - let x = Box::try_new_in( - ArcInner { - strong: atomic::AtomicUsize::new(1), - weak: atomic::AtomicUsize::new(1), - data, - }, - alloc, - )?; - let (ptr, alloc) = Box::into_unique(x); - Ok(unsafe { Self::from_inner_in(ptr.into(), alloc) }) - } - - /// Constructs a new `Arc` with uninitialized contents, in the provided allocator, returning an - /// error if allocation fails. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit, allocator_api)] - /// #![feature(get_mut_unchecked)] - /// - /// use std::sync::Arc; - /// use std::alloc::System; - /// - /// let mut five = Arc::::try_new_uninit_in(System)?; - /// - /// let five = unsafe { - /// // Deferred initialization: - /// Arc::get_mut_unchecked(&mut five).as_mut_ptr().write(5); - /// - /// five.assume_init() - /// }; - /// - /// assert_eq!(*five, 5); - /// # Ok::<(), std::alloc::AllocError>(()) - /// ``` - #[unstable(feature = "allocator_api", issue = "32838")] - // #[unstable(feature = "new_uninit", issue = "63291")] - #[inline] - pub fn try_new_uninit_in(alloc: A) -> Result, A>, AllocError> { - unsafe { - Ok(Arc::from_ptr_in( - Arc::try_allocate_for_layout( - Layout::new::(), - |layout| alloc.allocate(layout), - <*mut u8>::cast, - )?, - alloc, - )) - } - } - - /// Constructs a new `Arc` with uninitialized contents, with the memory - /// being filled with `0` bytes, in the provided allocator, returning an error if allocation - /// fails. - /// - /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and incorrect usage - /// of this method. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit, allocator_api)] - /// - /// use std::sync::Arc; - /// use std::alloc::System; - /// - /// let zero = Arc::::try_new_zeroed_in(System)?; - /// let zero = unsafe { zero.assume_init() }; - /// - /// assert_eq!(*zero, 0); - /// # Ok::<(), std::alloc::AllocError>(()) - /// ``` - /// - /// [zeroed]: mem::MaybeUninit::zeroed - #[unstable(feature = "allocator_api", issue = "32838")] - // #[unstable(feature = "new_uninit", issue = "63291")] - #[inline] - pub fn try_new_zeroed_in(alloc: A) -> Result, A>, AllocError> { - unsafe { - Ok(Arc::from_ptr_in( - Arc::try_allocate_for_layout( - Layout::new::(), - |layout| alloc.allocate_zeroed(layout), - <*mut u8>::cast, - )?, - alloc, - )) - } - } - /// Returns the inner value, if the `Arc` has exactly one strong reference. - /// - /// Otherwise, an [`Err`] is returned with the same `Arc` that was - /// passed in. - /// - /// This will succeed even if there are outstanding weak references. - /// - /// It is strongly recommended to use [`Arc::into_inner`] instead if you don't - /// want to keep the `Arc` in the [`Err`] case. - /// Immediately dropping the [`Err`] payload, like in the expression - /// `Arc::try_unwrap(this).ok()`, can still cause the strong count to - /// drop to zero and the inner value of the `Arc` to be dropped: - /// For instance if two threads each execute this expression in parallel, then - /// there is a race condition. The threads could first both check whether they - /// have the last clone of their `Arc` via `Arc::try_unwrap`, and then - /// both drop their `Arc` in the call to [`ok`][`Result::ok`], - /// taking the strong count from two down to zero. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// let x = Arc::new(3); - /// assert_eq!(Arc::try_unwrap(x), Ok(3)); - /// - /// let x = Arc::new(4); - /// let _y = Arc::clone(&x); - /// assert_eq!(*Arc::try_unwrap(x).unwrap_err(), 4); - /// ``` - #[inline] - #[stable(feature = "arc_unique", since = "1.4.0")] - pub fn try_unwrap(this: Self) -> Result { - if this.inner().strong.compare_exchange(1, 0, Relaxed, Relaxed).is_err() { - return Err(this); - } - - acquire!(this.inner().strong); - - unsafe { - let elem = ptr::read(&this.ptr.as_ref().data); - let alloc = ptr::read(&this.alloc); // copy the allocator - - // Make a weak pointer to clean up the implicit strong-weak reference - let _weak = Weak { ptr: this.ptr, alloc }; - mem::forget(this); - - Ok(elem) - } - } - - /// Returns the inner value, if the `Arc` has exactly one strong reference. - /// - /// Otherwise, [`None`] is returned and the `Arc` is dropped. - /// - /// This will succeed even if there are outstanding weak references. - /// - /// If `Arc::into_inner` is called on every clone of this `Arc`, - /// it is guaranteed that exactly one of the calls returns the inner value. - /// This means in particular that the inner value is not dropped. - /// - /// [`Arc::try_unwrap`] is conceptually similar to `Arc::into_inner`, but it - /// is meant for different use-cases. If used as a direct replacement - /// for `Arc::into_inner` anyway, such as with the expression - /// [Arc::try_unwrap]\(this).[ok][Result::ok](), then it does - /// **not** give the same guarantee as described in the previous paragraph. - /// For more information, see the examples below and read the documentation - /// of [`Arc::try_unwrap`]. - /// - /// # Examples - /// - /// Minimal example demonstrating the guarantee that `Arc::into_inner` gives. - /// ``` - /// use std::sync::Arc; - /// - /// let x = Arc::new(3); - /// let y = Arc::clone(&x); - /// - /// // Two threads calling `Arc::into_inner` on both clones of an `Arc`: - /// let x_thread = std::thread::spawn(|| Arc::into_inner(x)); - /// let y_thread = std::thread::spawn(|| Arc::into_inner(y)); - /// - /// let x_inner_value = x_thread.join().unwrap(); - /// let y_inner_value = y_thread.join().unwrap(); - /// - /// // One of the threads is guaranteed to receive the inner value: - /// assert!(matches!( - /// (x_inner_value, y_inner_value), - /// (None, Some(3)) | (Some(3), None) - /// )); - /// // The result could also be `(None, None)` if the threads called - /// // `Arc::try_unwrap(x).ok()` and `Arc::try_unwrap(y).ok()` instead. - /// ``` - /// - /// A more practical example demonstrating the need for `Arc::into_inner`: - /// ``` - /// use std::sync::Arc; - /// - /// // Definition of a simple singly linked list using `Arc`: - /// #[derive(Clone)] - /// struct LinkedList(Option>>); - /// struct Node(T, Option>>); - /// - /// // Dropping a long `LinkedList` relying on the destructor of `Arc` - /// // can cause a stack overflow. To prevent this, we can provide a - /// // manual `Drop` implementation that does the destruction in a loop: - /// impl Drop for LinkedList { - /// fn drop(&mut self) { - /// let mut link = self.0.take(); - /// while let Some(arc_node) = link.take() { - /// if let Some(Node(_value, next)) = Arc::into_inner(arc_node) { - /// link = next; - /// } - /// } - /// } - /// } - /// - /// // Implementation of `new` and `push` omitted - /// impl LinkedList { - /// /* ... */ - /// # fn new() -> Self { - /// # LinkedList(None) - /// # } - /// # fn push(&mut self, x: T) { - /// # self.0 = Some(Arc::new(Node(x, self.0.take()))); - /// # } - /// } - /// - /// // The following code could have still caused a stack overflow - /// // despite the manual `Drop` impl if that `Drop` impl had used - /// // `Arc::try_unwrap(arc).ok()` instead of `Arc::into_inner(arc)`. - /// - /// // Create a long list and clone it - /// let mut x = LinkedList::new(); - /// let size = 100000; - /// # let size = if cfg!(miri) { 100 } else { size }; - /// for i in 0..size { - /// x.push(i); // Adds i to the front of x - /// } - /// let y = x.clone(); - /// - /// // Drop the clones in parallel - /// let x_thread = std::thread::spawn(|| drop(x)); - /// let y_thread = std::thread::spawn(|| drop(y)); - /// x_thread.join().unwrap(); - /// y_thread.join().unwrap(); - /// ``` - #[inline] - #[stable(feature = "arc_into_inner", since = "1.70.0")] - pub fn into_inner(this: Self) -> Option { - // Make sure that the ordinary `Drop` implementation isn’t called as well - let mut this = mem::ManuallyDrop::new(this); - - // Following the implementation of `drop` and `drop_slow` - if this.inner().strong.fetch_sub(1, Release) != 1 { - return None; - } - - acquire!(this.inner().strong); - - // SAFETY: This mirrors the line - // - // unsafe { ptr::drop_in_place(Self::get_mut_unchecked(self)) }; - // - // in `drop_slow`. Instead of dropping the value behind the pointer, - // it is read and eventually returned; `ptr::read` has the same - // safety conditions as `ptr::drop_in_place`. - - let inner = unsafe { ptr::read(Self::get_mut_unchecked(&mut this)) }; - let alloc = unsafe { ptr::read(&this.alloc) }; - - drop(Weak { ptr: this.ptr, alloc }); - - Some(inner) - } -} - -impl Arc<[T]> { - /// Constructs a new atomically reference-counted slice with uninitialized contents. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// #![feature(get_mut_unchecked)] - /// - /// use std::sync::Arc; - /// - /// let mut values = Arc::<[u32]>::new_uninit_slice(3); - /// - /// // Deferred initialization: - /// let data = Arc::get_mut(&mut values).unwrap(); - /// data[0].write(1); - /// data[1].write(2); - /// data[2].write(3); - /// - /// let values = unsafe { values.assume_init() }; - /// - /// assert_eq!(*values, [1, 2, 3]) - /// ``` - #[cfg(not(no_global_oom_handling))] - #[inline] - #[unstable(feature = "new_uninit", issue = "63291")] - #[must_use] - pub fn new_uninit_slice(len: usize) -> Arc<[mem::MaybeUninit]> { - unsafe { Arc::from_ptr(Arc::allocate_for_slice(len)) } - } - - /// Constructs a new atomically reference-counted slice with uninitialized contents, with the memory being - /// filled with `0` bytes. - /// - /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and - /// incorrect usage of this method. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// - /// use std::sync::Arc; - /// - /// let values = Arc::<[u32]>::new_zeroed_slice(3); - /// let values = unsafe { values.assume_init() }; - /// - /// assert_eq!(*values, [0, 0, 0]) - /// ``` - /// - /// [zeroed]: mem::MaybeUninit::zeroed - #[cfg(not(no_global_oom_handling))] - #[inline] - #[unstable(feature = "new_uninit", issue = "63291")] - #[must_use] - pub fn new_zeroed_slice(len: usize) -> Arc<[mem::MaybeUninit]> { - unsafe { - Arc::from_ptr(Arc::allocate_for_layout( - Layout::array::(len).unwrap(), - |layout| Global.allocate_zeroed(layout), - |mem| { - ptr::slice_from_raw_parts_mut(mem as *mut T, len) - as *mut ArcInner<[mem::MaybeUninit]> - }, - )) - } - } -} - -impl Arc<[T], A> { - /// Constructs a new atomically reference-counted slice with uninitialized contents in the - /// provided allocator. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// #![feature(get_mut_unchecked)] - /// #![feature(allocator_api)] - /// - /// use std::sync::Arc; - /// use std::alloc::System; - /// - /// let mut values = Arc::<[u32], _>::new_uninit_slice_in(3, System); - /// - /// let values = unsafe { - /// // Deferred initialization: - /// Arc::get_mut_unchecked(&mut values)[0].as_mut_ptr().write(1); - /// Arc::get_mut_unchecked(&mut values)[1].as_mut_ptr().write(2); - /// Arc::get_mut_unchecked(&mut values)[2].as_mut_ptr().write(3); - /// - /// values.assume_init() - /// }; - /// - /// assert_eq!(*values, [1, 2, 3]) - /// ``` - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "new_uninit", issue = "63291")] - #[inline] - pub fn new_uninit_slice_in(len: usize, alloc: A) -> Arc<[mem::MaybeUninit], A> { - unsafe { Arc::from_ptr_in(Arc::allocate_for_slice_in(len, &alloc), alloc) } - } - - /// Constructs a new atomically reference-counted slice with uninitialized contents, with the memory being - /// filled with `0` bytes, in the provided allocator. - /// - /// See [`MaybeUninit::zeroed`][zeroed] for examples of correct and - /// incorrect usage of this method. - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// #![feature(allocator_api)] - /// - /// use std::sync::Arc; - /// use std::alloc::System; - /// - /// let values = Arc::<[u32], _>::new_zeroed_slice_in(3, System); - /// let values = unsafe { values.assume_init() }; - /// - /// assert_eq!(*values, [0, 0, 0]) - /// ``` - /// - /// [zeroed]: mem::MaybeUninit::zeroed - #[cfg(not(no_global_oom_handling))] - #[unstable(feature = "new_uninit", issue = "63291")] - #[inline] - pub fn new_zeroed_slice_in(len: usize, alloc: A) -> Arc<[mem::MaybeUninit], A> { - unsafe { - Arc::from_ptr_in( - Arc::allocate_for_layout( - Layout::array::(len).unwrap(), - |layout| alloc.allocate_zeroed(layout), - |mem| { - ptr::slice_from_raw_parts_mut(mem.cast::(), len) - as *mut ArcInner<[mem::MaybeUninit]> - }, - ), - alloc, - ) - } - } -} - -impl Arc, A> { - /// Converts to `Arc`. - /// - /// # Safety - /// - /// As with [`MaybeUninit::assume_init`], - /// it is up to the caller to guarantee that the inner value - /// really is in an initialized state. - /// Calling this when the content is not yet fully initialized - /// causes immediate undefined behavior. - /// - /// [`MaybeUninit::assume_init`]: mem::MaybeUninit::assume_init - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// #![feature(get_mut_unchecked)] - /// - /// use std::sync::Arc; - /// - /// let mut five = Arc::::new_uninit(); - /// - /// // Deferred initialization: - /// Arc::get_mut(&mut five).unwrap().write(5); - /// - /// let five = unsafe { five.assume_init() }; - /// - /// assert_eq!(*five, 5) - /// ``` - #[unstable(feature = "new_uninit", issue = "63291")] - #[must_use = "`self` will be dropped if the result is not used"] - #[inline] - pub unsafe fn assume_init(self) -> Arc { - let (ptr, alloc) = Arc::into_inner_with_allocator(self); - unsafe { Arc::from_inner_in(ptr.cast(), alloc) } - } -} - -impl Arc<[mem::MaybeUninit], A> { - /// Converts to `Arc<[T]>`. - /// - /// # Safety - /// - /// As with [`MaybeUninit::assume_init`], - /// it is up to the caller to guarantee that the inner value - /// really is in an initialized state. - /// Calling this when the content is not yet fully initialized - /// causes immediate undefined behavior. - /// - /// [`MaybeUninit::assume_init`]: mem::MaybeUninit::assume_init - /// - /// # Examples - /// - /// ``` - /// #![feature(new_uninit)] - /// #![feature(get_mut_unchecked)] - /// - /// use std::sync::Arc; - /// - /// let mut values = Arc::<[u32]>::new_uninit_slice(3); - /// - /// // Deferred initialization: - /// let data = Arc::get_mut(&mut values).unwrap(); - /// data[0].write(1); - /// data[1].write(2); - /// data[2].write(3); - /// - /// let values = unsafe { values.assume_init() }; - /// - /// assert_eq!(*values, [1, 2, 3]) - /// ``` - #[unstable(feature = "new_uninit", issue = "63291")] - #[must_use = "`self` will be dropped if the result is not used"] - #[inline] - pub unsafe fn assume_init(self) -> Arc<[T], A> { - let (ptr, alloc) = Arc::into_inner_with_allocator(self); - unsafe { Arc::from_ptr_in(ptr.as_ptr() as _, alloc) } - } -} - -impl Arc { - /// Constructs an `Arc` from a raw pointer. - /// - /// The raw pointer must have been previously returned by a call to - /// [`Arc::into_raw`][into_raw] with the following requirements: - /// - /// * If `U` is sized, it must have the same size and alignment as `T`. This - /// is trivially true if `U` is `T`. - /// * If `U` is unsized, its data pointer must have the same size and - /// alignment as `T`. This is trivially true if `Arc` was constructed - /// through `Arc` and then converted to `Arc` through an [unsized - /// coercion]. - /// - /// Note that if `U` or `U`'s data pointer is not `T` but has the same size - /// and alignment, this is basically like transmuting references of - /// different types. See [`mem::transmute`][transmute] for more information - /// on what restrictions apply in this case. - /// - /// The user of `from_raw` has to make sure a specific value of `T` is only - /// dropped once. - /// - /// This function is unsafe because improper use may lead to memory unsafety, - /// even if the returned `Arc` is never accessed. - /// - /// [into_raw]: Arc::into_raw - /// [transmute]: core::mem::transmute - /// [unsized coercion]: https://doc.rust-lang.org/reference/type-coercions.html#unsized-coercions - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// let x = Arc::new("hello".to_owned()); - /// let x_ptr = Arc::into_raw(x); - /// - /// unsafe { - /// // Convert back to an `Arc` to prevent leak. - /// let x = Arc::from_raw(x_ptr); - /// assert_eq!(&*x, "hello"); - /// - /// // Further calls to `Arc::from_raw(x_ptr)` would be memory-unsafe. - /// } - /// - /// // The memory was freed when `x` went out of scope above, so `x_ptr` is now dangling! - /// ``` - /// - /// Convert a slice back into its original array: - /// - /// ``` - /// use std::sync::Arc; - /// - /// let x: Arc<[u32]> = Arc::new([1, 2, 3]); - /// let x_ptr: *const [u32] = Arc::into_raw(x); - /// - /// unsafe { - /// let x: Arc<[u32; 3]> = Arc::from_raw(x_ptr.cast::<[u32; 3]>()); - /// assert_eq!(&*x, &[1, 2, 3]); - /// } - /// ``` - #[inline] - #[stable(feature = "rc_raw", since = "1.17.0")] - pub unsafe fn from_raw(ptr: *const T) -> Self { - unsafe { Arc::from_raw_in(ptr, Global) } - } - - /// Increments the strong reference count on the `Arc` associated with the - /// provided pointer by one. - /// - /// # Safety - /// - /// The pointer must have been obtained through `Arc::into_raw`, and the - /// associated `Arc` instance must be valid (i.e. the strong count must be at - /// least 1) for the duration of this method. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// let five = Arc::new(5); - /// - /// unsafe { - /// let ptr = Arc::into_raw(five); - /// Arc::increment_strong_count(ptr); - /// - /// // This assertion is deterministic because we haven't shared - /// // the `Arc` between threads. - /// let five = Arc::from_raw(ptr); - /// assert_eq!(2, Arc::strong_count(&five)); - /// } - /// ``` - #[inline] - #[stable(feature = "arc_mutate_strong_count", since = "1.51.0")] - pub unsafe fn increment_strong_count(ptr: *const T) { - unsafe { Arc::increment_strong_count_in(ptr, Global) } - } - - /// Decrements the strong reference count on the `Arc` associated with the - /// provided pointer by one. - /// - /// # Safety - /// - /// The pointer must have been obtained through `Arc::into_raw`, and the - /// associated `Arc` instance must be valid (i.e. the strong count must be at - /// least 1) when invoking this method. This method can be used to release the final - /// `Arc` and backing storage, but **should not** be called after the final `Arc` has been - /// released. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// let five = Arc::new(5); - /// - /// unsafe { - /// let ptr = Arc::into_raw(five); - /// Arc::increment_strong_count(ptr); - /// - /// // Those assertions are deterministic because we haven't shared - /// // the `Arc` between threads. - /// let five = Arc::from_raw(ptr); - /// assert_eq!(2, Arc::strong_count(&five)); - /// Arc::decrement_strong_count(ptr); - /// assert_eq!(1, Arc::strong_count(&five)); - /// } - /// ``` - #[inline] - #[stable(feature = "arc_mutate_strong_count", since = "1.51.0")] - pub unsafe fn decrement_strong_count(ptr: *const T) { - unsafe { Arc::decrement_strong_count_in(ptr, Global) } - } -} - -impl Arc { - /// Consumes the `Arc`, returning the wrapped pointer. - /// - /// To avoid a memory leak the pointer must be converted back to an `Arc` using - /// [`Arc::from_raw`]. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// let x = Arc::new("hello".to_owned()); - /// let x_ptr = Arc::into_raw(x); - /// assert_eq!(unsafe { &*x_ptr }, "hello"); - /// ``` - #[must_use = "losing the pointer will leak memory"] - #[stable(feature = "rc_raw", since = "1.17.0")] - #[rustc_never_returns_null_ptr] - pub fn into_raw(this: Self) -> *const T { - let ptr = Self::as_ptr(&this); - mem::forget(this); - ptr - } - - /// Consumes the `Arc`, returning the wrapped pointer and allocator. - /// - /// To avoid a memory leak the pointer must be converted back to an `Arc` using - /// [`Arc::from_raw_in`]. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// use std::sync::Arc; - /// use std::alloc::System; - /// - /// let x = Arc::new_in("hello".to_owned(), System); - /// let (ptr, alloc) = Arc::into_raw_with_allocator(x); - /// assert_eq!(unsafe { &*ptr }, "hello"); - /// let x = unsafe { Arc::from_raw_in(ptr, alloc) }; - /// assert_eq!(&*x, "hello"); - /// ``` - #[must_use = "losing the pointer will leak memory"] - #[unstable(feature = "allocator_api", issue = "32838")] - pub fn into_raw_with_allocator(this: Self) -> (*const T, A) { - let this = mem::ManuallyDrop::new(this); - let ptr = Self::as_ptr(&this); - // Safety: `this` is ManuallyDrop so the allocator will not be double-dropped - let alloc = unsafe { ptr::read(&this.alloc) }; - (ptr, alloc) - } - - /// Provides a raw pointer to the data. - /// - /// The counts are not affected in any way and the `Arc` is not consumed. The pointer is valid for - /// as long as there are strong counts in the `Arc`. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// let x = Arc::new("hello".to_owned()); - /// let y = Arc::clone(&x); - /// let x_ptr = Arc::as_ptr(&x); - /// assert_eq!(x_ptr, Arc::as_ptr(&y)); - /// assert_eq!(unsafe { &*x_ptr }, "hello"); - /// ``` - #[must_use] - #[stable(feature = "rc_as_ptr", since = "1.45.0")] - #[rustc_never_returns_null_ptr] - pub fn as_ptr(this: &Self) -> *const T { - let ptr: *mut ArcInner = NonNull::as_ptr(this.ptr); - - // SAFETY: This cannot go through Deref::deref or RcBoxPtr::inner because - // this is required to retain raw/mut provenance such that e.g. `get_mut` can - // write through the pointer after the Rc is recovered through `from_raw`. - unsafe { ptr::addr_of_mut!((*ptr).data) } - } - - /// Constructs an `Arc` from a raw pointer. - /// - /// The raw pointer must have been previously returned by a call to [`Arc::into_raw`][into_raw] with the following requirements: - /// - /// * If `U` is sized, it must have the same size and alignment as `T`. This - /// is trivially true if `U` is `T`. - /// * If `U` is unsized, its data pointer must have the same size and - /// alignment as `T`. This is trivially true if `Arc` was constructed - /// through `Arc` and then converted to `Arc` through an [unsized - /// coercion]. - /// - /// Note that if `U` or `U`'s data pointer is not `T` but has the same size - /// and alignment, this is basically like transmuting references of - /// different types. See [`mem::transmute`][transmute] for more information - /// on what restrictions apply in this case. - /// - /// The raw pointer must point to a block of memory allocated by `alloc` - /// - /// The user of `from_raw` has to make sure a specific value of `T` is only - /// dropped once. - /// - /// This function is unsafe because improper use may lead to memory unsafety, - /// even if the returned `Arc` is never accessed. - /// - /// [into_raw]: Arc::into_raw - /// [transmute]: core::mem::transmute - /// [unsized coercion]: https://doc.rust-lang.org/reference/type-coercions.html#unsized-coercions - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// - /// use std::sync::Arc; - /// use std::alloc::System; - /// - /// let x = Arc::new_in("hello".to_owned(), System); - /// let x_ptr = Arc::into_raw(x); - /// - /// unsafe { - /// // Convert back to an `Arc` to prevent leak. - /// let x = Arc::from_raw_in(x_ptr, System); - /// assert_eq!(&*x, "hello"); - /// - /// // Further calls to `Arc::from_raw(x_ptr)` would be memory-unsafe. - /// } - /// - /// // The memory was freed when `x` went out of scope above, so `x_ptr` is now dangling! - /// ``` - /// - /// Convert a slice back into its original array: - /// - /// ``` - /// #![feature(allocator_api)] - /// - /// use std::sync::Arc; - /// use std::alloc::System; - /// - /// let x: Arc<[u32], _> = Arc::new_in([1, 2, 3], System); - /// let x_ptr: *const [u32] = Arc::into_raw(x); - /// - /// unsafe { - /// let x: Arc<[u32; 3], _> = Arc::from_raw_in(x_ptr.cast::<[u32; 3]>(), System); - /// assert_eq!(&*x, &[1, 2, 3]); - /// } - /// ``` - #[inline] - #[unstable(feature = "allocator_api", issue = "32838")] - pub unsafe fn from_raw_in(ptr: *const T, alloc: A) -> Self { - unsafe { - let offset = data_offset(ptr); - - // Reverse the offset to find the original ArcInner. - let arc_ptr = ptr.byte_sub(offset) as *mut ArcInner; - - Self::from_ptr_in(arc_ptr, alloc) - } - } - - /// Creates a new [`Weak`] pointer to this allocation. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// let five = Arc::new(5); - /// - /// let weak_five = Arc::downgrade(&five); - /// ``` - #[must_use = "this returns a new `Weak` pointer, \ - without modifying the original `Arc`"] - #[stable(feature = "arc_weak", since = "1.4.0")] - pub fn downgrade(this: &Self) -> Weak - where - A: Clone, - { - // This Relaxed is OK because we're checking the value in the CAS - // below. - let mut cur = this.inner().weak.load(Relaxed); - - loop { - // check if the weak counter is currently "locked"; if so, spin. - if cur == usize::MAX { - hint::spin_loop(); - cur = this.inner().weak.load(Relaxed); - continue; - } - - // We can't allow the refcount to increase much past `MAX_REFCOUNT`. - assert!(cur <= MAX_REFCOUNT, "{}", INTERNAL_OVERFLOW_ERROR); - - // NOTE: this code currently ignores the possibility of overflow - // into usize::MAX; in general both Rc and Arc need to be adjusted - // to deal with overflow. - - // Unlike with Clone(), we need this to be an Acquire read to - // synchronize with the write coming from `is_unique`, so that the - // events prior to that write happen before this read. - match this.inner().weak.compare_exchange_weak(cur, cur + 1, Acquire, Relaxed) { - Ok(_) => { - // Make sure we do not create a dangling Weak - debug_assert!(!is_dangling(this.ptr.as_ptr())); - return Weak { ptr: this.ptr, alloc: this.alloc.clone() }; - } - Err(old) => cur = old, - } - } - } - - /// Gets the number of [`Weak`] pointers to this allocation. - /// - /// # Safety - /// - /// This method by itself is safe, but using it correctly requires extra care. - /// Another thread can change the weak count at any time, - /// including potentially between calling this method and acting on the result. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// let five = Arc::new(5); - /// let _weak_five = Arc::downgrade(&five); - /// - /// // This assertion is deterministic because we haven't shared - /// // the `Arc` or `Weak` between threads. - /// assert_eq!(1, Arc::weak_count(&five)); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "arc_counts", since = "1.15.0")] - pub fn weak_count(this: &Self) -> usize { - let cnt = this.inner().weak.load(Relaxed); - // If the weak count is currently locked, the value of the - // count was 0 just before taking the lock. - if cnt == usize::MAX { 0 } else { cnt - 1 } - } - - /// Gets the number of strong (`Arc`) pointers to this allocation. - /// - /// # Safety - /// - /// This method by itself is safe, but using it correctly requires extra care. - /// Another thread can change the strong count at any time, - /// including potentially between calling this method and acting on the result. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// let five = Arc::new(5); - /// let _also_five = Arc::clone(&five); - /// - /// // This assertion is deterministic because we haven't shared - /// // the `Arc` between threads. - /// assert_eq!(2, Arc::strong_count(&five)); - /// ``` - #[inline] - #[must_use] - #[stable(feature = "arc_counts", since = "1.15.0")] - pub fn strong_count(this: &Self) -> usize { - this.inner().strong.load(Relaxed) - } - - /// Increments the strong reference count on the `Arc` associated with the - /// provided pointer by one. - /// - /// # Safety - /// - /// The pointer must have been obtained through `Arc::into_raw`, and the - /// associated `Arc` instance must be valid (i.e. the strong count must be at - /// least 1) for the duration of this method,, and `ptr` must point to a block of memory - /// allocated by `alloc`. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// - /// use std::sync::Arc; - /// use std::alloc::System; - /// - /// let five = Arc::new_in(5, System); - /// - /// unsafe { - /// let ptr = Arc::into_raw(five); - /// Arc::increment_strong_count_in(ptr, System); - /// - /// // This assertion is deterministic because we haven't shared - /// // the `Arc` between threads. - /// let five = Arc::from_raw_in(ptr, System); - /// assert_eq!(2, Arc::strong_count(&five)); - /// } - /// ``` - #[inline] - #[unstable(feature = "allocator_api", issue = "32838")] - pub unsafe fn increment_strong_count_in(ptr: *const T, alloc: A) - where - A: Clone, - { - // Retain Arc, but don't touch refcount by wrapping in ManuallyDrop - let arc = unsafe { mem::ManuallyDrop::new(Arc::from_raw_in(ptr, alloc)) }; - // Now increase refcount, but don't drop new refcount either - let _arc_clone: mem::ManuallyDrop<_> = arc.clone(); - } - - /// Decrements the strong reference count on the `Arc` associated with the - /// provided pointer by one. - /// - /// # Safety - /// - /// The pointer must have been obtained through `Arc::into_raw`, the - /// associated `Arc` instance must be valid (i.e. the strong count must be at - /// least 1) when invoking this method, and `ptr` must point to a block of memory - /// allocated by `alloc`. This method can be used to release the final - /// `Arc` and backing storage, but **should not** be called after the final `Arc` has been - /// released. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// - /// use std::sync::Arc; - /// use std::alloc::System; - /// - /// let five = Arc::new_in(5, System); - /// - /// unsafe { - /// let ptr = Arc::into_raw(five); - /// Arc::increment_strong_count_in(ptr, System); - /// - /// // Those assertions are deterministic because we haven't shared - /// // the `Arc` between threads. - /// let five = Arc::from_raw_in(ptr, System); - /// assert_eq!(2, Arc::strong_count(&five)); - /// Arc::decrement_strong_count_in(ptr, System); - /// assert_eq!(1, Arc::strong_count(&five)); - /// } - /// ``` - #[inline] - #[unstable(feature = "allocator_api", issue = "32838")] - pub unsafe fn decrement_strong_count_in(ptr: *const T, alloc: A) { - unsafe { drop(Arc::from_raw_in(ptr, alloc)) }; - } - - #[inline] - fn inner(&self) -> &ArcInner { - // This unsafety is ok because while this arc is alive we're guaranteed - // that the inner pointer is valid. Furthermore, we know that the - // `ArcInner` structure itself is `Sync` because the inner data is - // `Sync` as well, so we're ok loaning out an immutable pointer to these - // contents. - unsafe { self.ptr.as_ref() } - } - - // Non-inlined part of `drop`. - #[inline(never)] - unsafe fn drop_slow(&mut self) { - // Destroy the data at this time, even though we must not free the box - // allocation itself (there might still be weak pointers lying around). - unsafe { ptr::drop_in_place(Self::get_mut_unchecked(self)) }; - - // Drop the weak ref collectively held by all strong references - // Take a reference to `self.alloc` instead of cloning because 1. it'll - // last long enough, and 2. you should be able to drop `Arc`s with - // unclonable allocators - drop(Weak { ptr: self.ptr, alloc: &self.alloc }); - } - - /// Returns `true` if the two `Arc`s point to the same allocation in a vein similar to - /// [`ptr::eq`]. This function ignores the metadata of `dyn Trait` pointers. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// let five = Arc::new(5); - /// let same_five = Arc::clone(&five); - /// let other_five = Arc::new(5); - /// - /// assert!(Arc::ptr_eq(&five, &same_five)); - /// assert!(!Arc::ptr_eq(&five, &other_five)); - /// ``` - /// - /// [`ptr::eq`]: core::ptr::eq "ptr::eq" - #[inline] - #[must_use] - #[stable(feature = "ptr_eq", since = "1.17.0")] - pub fn ptr_eq(this: &Self, other: &Self) -> bool { - ptr::addr_eq(this.ptr.as_ptr(), other.ptr.as_ptr()) - } -} - -impl Arc { - /// Allocates an `ArcInner` with sufficient space for - /// a possibly-unsized inner value where the value has the layout provided. - /// - /// The function `mem_to_arcinner` is called with the data pointer - /// and must return back a (potentially fat)-pointer for the `ArcInner`. - #[cfg(not(no_global_oom_handling))] - unsafe fn allocate_for_layout( - value_layout: Layout, - allocate: impl FnOnce(Layout) -> Result, AllocError>, - mem_to_arcinner: impl FnOnce(*mut u8) -> *mut ArcInner, - ) -> *mut ArcInner { - let layout = arcinner_layout_for_value_layout(value_layout); - - let ptr = allocate(layout).unwrap_or_else(|_| handle_alloc_error(layout)); - - unsafe { Self::initialize_arcinner(ptr, layout, mem_to_arcinner) } - } - - /// Allocates an `ArcInner` with sufficient space for - /// a possibly-unsized inner value where the value has the layout provided, - /// returning an error if allocation fails. - /// - /// The function `mem_to_arcinner` is called with the data pointer - /// and must return back a (potentially fat)-pointer for the `ArcInner`. - unsafe fn try_allocate_for_layout( - value_layout: Layout, - allocate: impl FnOnce(Layout) -> Result, AllocError>, - mem_to_arcinner: impl FnOnce(*mut u8) -> *mut ArcInner, - ) -> Result<*mut ArcInner, AllocError> { - let layout = arcinner_layout_for_value_layout(value_layout); - - let ptr = allocate(layout)?; - - let inner = unsafe { Self::initialize_arcinner(ptr, layout, mem_to_arcinner) }; - - Ok(inner) - } - - unsafe fn initialize_arcinner( - ptr: NonNull<[u8]>, - layout: Layout, - mem_to_arcinner: impl FnOnce(*mut u8) -> *mut ArcInner, - ) -> *mut ArcInner { - let inner = mem_to_arcinner(ptr.as_non_null_ptr().as_ptr()); - debug_assert_eq!(unsafe { Layout::for_value_raw(inner) }, layout); - - unsafe { - ptr::addr_of_mut!((*inner).strong).write(atomic::AtomicUsize::new(1)); - ptr::addr_of_mut!((*inner).weak).write(atomic::AtomicUsize::new(1)); - } - - inner - } -} - -impl Arc { - /// Allocates an `ArcInner` with sufficient space for an unsized inner value. - #[inline] - #[cfg(not(no_global_oom_handling))] - unsafe fn allocate_for_ptr_in(ptr: *const T, alloc: &A) -> *mut ArcInner { - // Allocate for the `ArcInner` using the given value. - unsafe { - Arc::allocate_for_layout( - Layout::for_value_raw(ptr), - |layout| alloc.allocate(layout), - |mem| mem.with_metadata_of(ptr as *const ArcInner), - ) - } - } - - #[cfg(not(no_global_oom_handling))] - fn from_box_in(src: Box) -> Arc { - unsafe { - let value_size = size_of_val(&*src); - let ptr = Self::allocate_for_ptr_in(&*src, Box::allocator(&src)); - - // Copy value as bytes - ptr::copy_nonoverlapping( - core::ptr::addr_of!(*src) as *const u8, - ptr::addr_of_mut!((*ptr).data) as *mut u8, - value_size, - ); - - // Free the allocation without dropping its contents - let (bptr, alloc) = Box::into_raw_with_allocator(src); - let src = Box::from_raw_in(bptr as *mut mem::ManuallyDrop, alloc.by_ref()); - drop(src); - - Self::from_ptr_in(ptr, alloc) - } - } -} - -impl Arc<[T]> { - /// Allocates an `ArcInner<[T]>` with the given length. - #[cfg(not(no_global_oom_handling))] - unsafe fn allocate_for_slice(len: usize) -> *mut ArcInner<[T]> { - unsafe { - Self::allocate_for_layout( - Layout::array::(len).unwrap(), - |layout| Global.allocate(layout), - |mem| ptr::slice_from_raw_parts_mut(mem.cast::(), len) as *mut ArcInner<[T]>, - ) - } - } - - /// Copy elements from slice into newly allocated `Arc<[T]>` - /// - /// Unsafe because the caller must either take ownership or bind `T: Copy`. - #[cfg(not(no_global_oom_handling))] - unsafe fn copy_from_slice(v: &[T]) -> Arc<[T]> { - unsafe { - let ptr = Self::allocate_for_slice(v.len()); - - ptr::copy_nonoverlapping(v.as_ptr(), ptr::addr_of_mut!((*ptr).data) as *mut T, v.len()); - - Self::from_ptr(ptr) - } - } - - /// Constructs an `Arc<[T]>` from an iterator known to be of a certain size. - /// - /// Behavior is undefined should the size be wrong. - #[cfg(not(no_global_oom_handling))] - unsafe fn from_iter_exact(iter: impl Iterator, len: usize) -> Arc<[T]> { - // Panic guard while cloning T elements. - // In the event of a panic, elements that have been written - // into the new ArcInner will be dropped, then the memory freed. - struct Guard { - mem: NonNull, - elems: *mut T, - layout: Layout, - n_elems: usize, - } - - impl Drop for Guard { - fn drop(&mut self) { - unsafe { - let slice = from_raw_parts_mut(self.elems, self.n_elems); - ptr::drop_in_place(slice); - - Global.deallocate(self.mem, self.layout); - } - } - } - - unsafe { - let ptr = Self::allocate_for_slice(len); - - let mem = ptr as *mut _ as *mut u8; - let layout = Layout::for_value_raw(ptr); - - // Pointer to first element - let elems = ptr::addr_of_mut!((*ptr).data) as *mut T; - - let mut guard = Guard { mem: NonNull::new_unchecked(mem), elems, layout, n_elems: 0 }; - - for (i, item) in iter.enumerate() { - ptr::write(elems.add(i), item); - guard.n_elems += 1; - } - - // All clear. Forget the guard so it doesn't free the new ArcInner. - mem::forget(guard); - - Self::from_ptr(ptr) - } - } -} - -impl Arc<[T], A> { - /// Allocates an `ArcInner<[T]>` with the given length. - #[inline] - #[cfg(not(no_global_oom_handling))] - unsafe fn allocate_for_slice_in(len: usize, alloc: &A) -> *mut ArcInner<[T]> { - unsafe { - Arc::allocate_for_layout( - Layout::array::(len).unwrap(), - |layout| alloc.allocate(layout), - |mem| ptr::slice_from_raw_parts_mut(mem.cast::(), len) as *mut ArcInner<[T]>, - ) - } - } -} - -/// Specialization trait used for `From<&[T]>`. -#[cfg(not(no_global_oom_handling))] -trait ArcFromSlice { - fn from_slice(slice: &[T]) -> Self; -} - -#[cfg(not(no_global_oom_handling))] -impl ArcFromSlice for Arc<[T]> { - #[inline] - default fn from_slice(v: &[T]) -> Self { - unsafe { Self::from_iter_exact(v.iter().cloned(), v.len()) } - } -} - -#[cfg(not(no_global_oom_handling))] -impl ArcFromSlice for Arc<[T]> { - #[inline] - fn from_slice(v: &[T]) -> Self { - unsafe { Arc::copy_from_slice(v) } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Arc { - /// Makes a clone of the `Arc` pointer. - /// - /// This creates another pointer to the same allocation, increasing the - /// strong reference count. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// let five = Arc::new(5); - /// - /// let _ = Arc::clone(&five); - /// ``` - #[inline] - fn clone(&self) -> Arc { - // Using a relaxed ordering is alright here, as knowledge of the - // original reference prevents other threads from erroneously deleting - // the object. - // - // As explained in the [Boost documentation][1], Increasing the - // reference counter can always be done with memory_order_relaxed: New - // references to an object can only be formed from an existing - // reference, and passing an existing reference from one thread to - // another must already provide any required synchronization. - // - // [1]: (www.boost.org/doc/libs/1_55_0/doc/html/atomic/usage_examples.html) - let old_size = self.inner().strong.fetch_add(1, Relaxed); - - // However we need to guard against massive refcounts in case someone is `mem::forget`ing - // Arcs. If we don't do this the count can overflow and users will use-after free. This - // branch will never be taken in any realistic program. We abort because such a program is - // incredibly degenerate, and we don't care to support it. - // - // This check is not 100% water-proof: we error when the refcount grows beyond `isize::MAX`. - // But we do that check *after* having done the increment, so there is a chance here that - // the worst already happened and we actually do overflow the `usize` counter. However, that - // requires the counter to grow from `isize::MAX` to `usize::MAX` between the increment - // above and the `abort` below, which seems exceedingly unlikely. - // - // This is a global invariant, and also applies when using a compare-exchange loop to increment - // counters in other methods. - // Otherwise, the counter could be brought to an almost-overflow using a compare-exchange loop, - // and then overflow using a few `fetch_add`s. - if old_size > MAX_REFCOUNT { - abort(); - } - - unsafe { Self::from_inner_in(self.ptr, self.alloc.clone()) } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Deref for Arc { - type Target = T; - - #[inline] - fn deref(&self) -> &T { - &self.inner().data - } -} - -#[unstable(feature = "deref_pure_trait", issue = "87121")] -unsafe impl DerefPure for Arc {} - -#[unstable(feature = "receiver_trait", issue = "none")] -impl Receiver for Arc {} - -impl Arc { - /// Makes a mutable reference into the given `Arc`. - /// - /// If there are other `Arc` pointers to the same allocation, then `make_mut` will - /// [`clone`] the inner value to a new allocation to ensure unique ownership. This is also - /// referred to as clone-on-write. - /// - /// However, if there are no other `Arc` pointers to this allocation, but some [`Weak`] - /// pointers, then the [`Weak`] pointers will be dissociated and the inner value will not - /// be cloned. - /// - /// See also [`get_mut`], which will fail rather than cloning the inner value - /// or dissociating [`Weak`] pointers. - /// - /// [`clone`]: Clone::clone - /// [`get_mut`]: Arc::get_mut - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// let mut data = Arc::new(5); - /// - /// *Arc::make_mut(&mut data) += 1; // Won't clone anything - /// let mut other_data = Arc::clone(&data); // Won't clone inner data - /// *Arc::make_mut(&mut data) += 1; // Clones inner data - /// *Arc::make_mut(&mut data) += 1; // Won't clone anything - /// *Arc::make_mut(&mut other_data) *= 2; // Won't clone anything - /// - /// // Now `data` and `other_data` point to different allocations. - /// assert_eq!(*data, 8); - /// assert_eq!(*other_data, 12); - /// ``` - /// - /// [`Weak`] pointers will be dissociated: - /// - /// ``` - /// use std::sync::Arc; - /// - /// let mut data = Arc::new(75); - /// let weak = Arc::downgrade(&data); - /// - /// assert!(75 == *data); - /// assert!(75 == *weak.upgrade().unwrap()); - /// - /// *Arc::make_mut(&mut data) += 1; - /// - /// assert!(76 == *data); - /// assert!(weak.upgrade().is_none()); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[inline] - #[stable(feature = "arc_unique", since = "1.4.0")] - pub fn make_mut(this: &mut Self) -> &mut T { - // Note that we hold both a strong reference and a weak reference. - // Thus, releasing our strong reference only will not, by itself, cause - // the memory to be deallocated. - // - // Use Acquire to ensure that we see any writes to `weak` that happen - // before release writes (i.e., decrements) to `strong`. Since we hold a - // weak count, there's no chance the ArcInner itself could be - // deallocated. - if this.inner().strong.compare_exchange(1, 0, Acquire, Relaxed).is_err() { - // Another strong pointer exists, so we must clone. - // Pre-allocate memory to allow writing the cloned value directly. - let mut arc = Self::new_uninit_in(this.alloc.clone()); - unsafe { - let data = Arc::get_mut_unchecked(&mut arc); - (**this).write_clone_into_raw(data.as_mut_ptr()); - *this = arc.assume_init(); - } - } else if this.inner().weak.load(Relaxed) != 1 { - // Relaxed suffices in the above because this is fundamentally an - // optimization: we are always racing with weak pointers being - // dropped. Worst case, we end up allocated a new Arc unnecessarily. - - // We removed the last strong ref, but there are additional weak - // refs remaining. We'll move the contents to a new Arc, and - // invalidate the other weak refs. - - // Note that it is not possible for the read of `weak` to yield - // usize::MAX (i.e., locked), since the weak count can only be - // locked by a thread with a strong reference. - - // Materialize our own implicit weak pointer, so that it can clean - // up the ArcInner as needed. - let _weak = Weak { ptr: this.ptr, alloc: this.alloc.clone() }; - - // Can just steal the data, all that's left is Weaks - let mut arc = Self::new_uninit_in(this.alloc.clone()); - unsafe { - let data = Arc::get_mut_unchecked(&mut arc); - data.as_mut_ptr().copy_from_nonoverlapping(&**this, 1); - ptr::write(this, arc.assume_init()); - } - } else { - // We were the sole reference of either kind; bump back up the - // strong ref count. - this.inner().strong.store(1, Release); - } - - // As with `get_mut()`, the unsafety is ok because our reference was - // either unique to begin with, or became one upon cloning the contents. - unsafe { Self::get_mut_unchecked(this) } - } -} - -impl Arc { - /// If we have the only reference to `T` then unwrap it. Otherwise, clone `T` and return the - /// clone. - /// - /// Assuming `arc_t` is of type `Arc`, this function is functionally equivalent to - /// `(*arc_t).clone()`, but will avoid cloning the inner value where possible. - /// - /// # Examples - /// - /// ``` - /// # use std::{ptr, sync::Arc}; - /// let inner = String::from("test"); - /// let ptr = inner.as_ptr(); - /// - /// let arc = Arc::new(inner); - /// let inner = Arc::unwrap_or_clone(arc); - /// // The inner value was not cloned - /// assert!(ptr::eq(ptr, inner.as_ptr())); - /// - /// let arc = Arc::new(inner); - /// let arc2 = arc.clone(); - /// let inner = Arc::unwrap_or_clone(arc); - /// // Because there were 2 references, we had to clone the inner value. - /// assert!(!ptr::eq(ptr, inner.as_ptr())); - /// // `arc2` is the last reference, so when we unwrap it we get back - /// // the original `String`. - /// let inner = Arc::unwrap_or_clone(arc2); - /// assert!(ptr::eq(ptr, inner.as_ptr())); - /// ``` - #[inline] - #[stable(feature = "arc_unwrap_or_clone", since = "1.76.0")] - pub fn unwrap_or_clone(this: Self) -> T { - Arc::try_unwrap(this).unwrap_or_else(|arc| (*arc).clone()) - } -} - -impl Arc { - /// Returns a mutable reference into the given `Arc`, if there are - /// no other `Arc` or [`Weak`] pointers to the same allocation. - /// - /// Returns [`None`] otherwise, because it is not safe to - /// mutate a shared value. - /// - /// See also [`make_mut`][make_mut], which will [`clone`][clone] - /// the inner value when there are other `Arc` pointers. - /// - /// [make_mut]: Arc::make_mut - /// [clone]: Clone::clone - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// let mut x = Arc::new(3); - /// *Arc::get_mut(&mut x).unwrap() = 4; - /// assert_eq!(*x, 4); - /// - /// let _y = Arc::clone(&x); - /// assert!(Arc::get_mut(&mut x).is_none()); - /// ``` - #[inline] - #[stable(feature = "arc_unique", since = "1.4.0")] - pub fn get_mut(this: &mut Self) -> Option<&mut T> { - if this.is_unique() { - // This unsafety is ok because we're guaranteed that the pointer - // returned is the *only* pointer that will ever be returned to T. Our - // reference count is guaranteed to be 1 at this point, and we required - // the Arc itself to be `mut`, so we're returning the only possible - // reference to the inner data. - unsafe { Some(Arc::get_mut_unchecked(this)) } - } else { - None - } - } - - /// Returns a mutable reference into the given `Arc`, - /// without any check. - /// - /// See also [`get_mut`], which is safe and does appropriate checks. - /// - /// [`get_mut`]: Arc::get_mut - /// - /// # Safety - /// - /// If any other `Arc` or [`Weak`] pointers to the same allocation exist, then - /// they must not be dereferenced or have active borrows for the duration - /// of the returned borrow, and their inner type must be exactly the same as the - /// inner type of this Rc (including lifetimes). This is trivially the case if no - /// such pointers exist, for example immediately after `Arc::new`. - /// - /// # Examples - /// - /// ``` - /// #![feature(get_mut_unchecked)] - /// - /// use std::sync::Arc; - /// - /// let mut x = Arc::new(String::new()); - /// unsafe { - /// Arc::get_mut_unchecked(&mut x).push_str("foo") - /// } - /// assert_eq!(*x, "foo"); - /// ``` - /// Other `Arc` pointers to the same allocation must be to the same type. - /// ```no_run - /// #![feature(get_mut_unchecked)] - /// - /// use std::sync::Arc; - /// - /// let x: Arc = Arc::from("Hello, world!"); - /// let mut y: Arc<[u8]> = x.clone().into(); - /// unsafe { - /// // this is Undefined Behavior, because x's inner type is str, not [u8] - /// Arc::get_mut_unchecked(&mut y).fill(0xff); // 0xff is invalid in UTF-8 - /// } - /// println!("{}", &*x); // Invalid UTF-8 in a str - /// ``` - /// Other `Arc` pointers to the same allocation must be to the exact same type, including lifetimes. - /// ```no_run - /// #![feature(get_mut_unchecked)] - /// - /// use std::sync::Arc; - /// - /// let x: Arc<&str> = Arc::new("Hello, world!"); - /// { - /// let s = String::from("Oh, no!"); - /// let mut y: Arc<&str> = x.clone().into(); - /// unsafe { - /// // this is Undefined Behavior, because x's inner type - /// // is &'long str, not &'short str - /// *Arc::get_mut_unchecked(&mut y) = &s; - /// } - /// } - /// println!("{}", &*x); // Use-after-free - /// ``` - #[inline] - #[unstable(feature = "get_mut_unchecked", issue = "63292")] - pub unsafe fn get_mut_unchecked(this: &mut Self) -> &mut T { - // We are careful to *not* create a reference covering the "count" fields, as - // this would alias with concurrent access to the reference counts (e.g. by `Weak`). - unsafe { &mut (*this.ptr.as_ptr()).data } - } - - /// Determine whether this is the unique reference (including weak refs) to - /// the underlying data. - /// - /// Note that this requires locking the weak ref count. - fn is_unique(&mut self) -> bool { - // lock the weak pointer count if we appear to be the sole weak pointer - // holder. - // - // The acquire label here ensures a happens-before relationship with any - // writes to `strong` (in particular in `Weak::upgrade`) prior to decrements - // of the `weak` count (via `Weak::drop`, which uses release). If the upgraded - // weak ref was never dropped, the CAS here will fail so we do not care to synchronize. - if self.inner().weak.compare_exchange(1, usize::MAX, Acquire, Relaxed).is_ok() { - // This needs to be an `Acquire` to synchronize with the decrement of the `strong` - // counter in `drop` -- the only access that happens when any but the last reference - // is being dropped. - let unique = self.inner().strong.load(Acquire) == 1; - - // The release write here synchronizes with a read in `downgrade`, - // effectively preventing the above read of `strong` from happening - // after the write. - self.inner().weak.store(1, Release); // release the lock - unique - } else { - false - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl<#[may_dangle] T: ?Sized, A: Allocator> Drop for Arc { - /// Drops the `Arc`. - /// - /// This will decrement the strong reference count. If the strong reference - /// count reaches zero then the only other references (if any) are - /// [`Weak`], so we `drop` the inner value. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// struct Foo; - /// - /// impl Drop for Foo { - /// fn drop(&mut self) { - /// println!("dropped!"); - /// } - /// } - /// - /// let foo = Arc::new(Foo); - /// let foo2 = Arc::clone(&foo); - /// - /// drop(foo); // Doesn't print anything - /// drop(foo2); // Prints "dropped!" - /// ``` - #[inline] - fn drop(&mut self) { - // Because `fetch_sub` is already atomic, we do not need to synchronize - // with other threads unless we are going to delete the object. This - // same logic applies to the below `fetch_sub` to the `weak` count. - if self.inner().strong.fetch_sub(1, Release) != 1 { - return; - } - - // This fence is needed to prevent reordering of use of the data and - // deletion of the data. Because it is marked `Release`, the decreasing - // of the reference count synchronizes with this `Acquire` fence. This - // means that use of the data happens before decreasing the reference - // count, which happens before this fence, which happens before the - // deletion of the data. - // - // As explained in the [Boost documentation][1], - // - // > It is important to enforce any possible access to the object in one - // > thread (through an existing reference) to *happen before* deleting - // > the object in a different thread. This is achieved by a "release" - // > operation after dropping a reference (any access to the object - // > through this reference must obviously happened before), and an - // > "acquire" operation before deleting the object. - // - // In particular, while the contents of an Arc are usually immutable, it's - // possible to have interior writes to something like a Mutex. Since a - // Mutex is not acquired when it is deleted, we can't rely on its - // synchronization logic to make writes in thread A visible to a destructor - // running in thread B. - // - // Also note that the Acquire fence here could probably be replaced with an - // Acquire load, which could improve performance in highly-contended - // situations. See [2]. - // - // [1]: (www.boost.org/doc/libs/1_55_0/doc/html/atomic/usage_examples.html) - // [2]: (https://github.com/rust-lang/rust/pull/41714) - acquire!(self.inner().strong); - - // Make sure we aren't trying to "drop" the shared static for empty slices - // used by Default::default. - debug_assert!( - !ptr::addr_eq(self.ptr.as_ptr(), &STATIC_INNER_SLICE.inner), - "Arcs backed by a static should never reach a strong count of 0. \ - Likely decrement_strong_count or from_raw were called too many times.", - ); - - unsafe { - self.drop_slow(); - } - } -} - -impl Arc { - /// Attempt to downcast the `Arc` to a concrete type. - /// - /// # Examples - /// - /// ``` - /// use std::any::Any; - /// use std::sync::Arc; - /// - /// fn print_if_string(value: Arc) { - /// if let Ok(string) = value.downcast::() { - /// println!("String ({}): {}", string.len(), string); - /// } - /// } - /// - /// let my_string = "Hello World".to_string(); - /// print_if_string(Arc::new(my_string)); - /// print_if_string(Arc::new(0i8)); - /// ``` - #[inline] - #[stable(feature = "rc_downcast", since = "1.29.0")] - pub fn downcast(self) -> Result, Self> - where - T: Any + Send + Sync, - { - if (*self).is::() { - unsafe { - let (ptr, alloc) = Arc::into_inner_with_allocator(self); - Ok(Arc::from_inner_in(ptr.cast(), alloc)) - } - } else { - Err(self) - } - } - - /// Downcasts the `Arc` to a concrete type. - /// - /// For a safe alternative see [`downcast`]. - /// - /// # Examples - /// - /// ``` - /// #![feature(downcast_unchecked)] - /// - /// use std::any::Any; - /// use std::sync::Arc; - /// - /// let x: Arc = Arc::new(1_usize); - /// - /// unsafe { - /// assert_eq!(*x.downcast_unchecked::(), 1); - /// } - /// ``` - /// - /// # Safety - /// - /// The contained value must be of type `T`. Calling this method - /// with the incorrect type is *undefined behavior*. - /// - /// - /// [`downcast`]: Self::downcast - #[inline] - #[unstable(feature = "downcast_unchecked", issue = "90850")] - pub unsafe fn downcast_unchecked(self) -> Arc - where - T: Any + Send + Sync, - { - unsafe { - let (ptr, alloc) = Arc::into_inner_with_allocator(self); - Arc::from_inner_in(ptr.cast(), alloc) - } - } -} - -impl Weak { - /// Constructs a new `Weak`, without allocating any memory. - /// Calling [`upgrade`] on the return value always gives [`None`]. - /// - /// [`upgrade`]: Weak::upgrade - /// - /// # Examples - /// - /// ``` - /// use std::sync::Weak; - /// - /// let empty: Weak = Weak::new(); - /// assert!(empty.upgrade().is_none()); - /// ``` - #[inline] - #[stable(feature = "downgraded_weak", since = "1.10.0")] - #[rustc_const_stable(feature = "const_weak_new", since = "1.73.0")] - #[must_use] - pub const fn new() -> Weak { - Weak { - ptr: unsafe { - NonNull::new_unchecked(ptr::without_provenance_mut::>(usize::MAX)) - }, - alloc: Global, - } - } -} - -impl Weak { - /// Constructs a new `Weak`, without allocating any memory, technically in the provided - /// allocator. - /// Calling [`upgrade`] on the return value always gives [`None`]. - /// - /// [`upgrade`]: Weak::upgrade - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// - /// use std::sync::Weak; - /// use std::alloc::System; - /// - /// let empty: Weak = Weak::new_in(System); - /// assert!(empty.upgrade().is_none()); - /// ``` - #[inline] - #[unstable(feature = "allocator_api", issue = "32838")] - pub fn new_in(alloc: A) -> Weak { - Weak { - ptr: unsafe { - NonNull::new_unchecked(ptr::without_provenance_mut::>(usize::MAX)) - }, - alloc, - } - } -} - -/// Helper type to allow accessing the reference counts without -/// making any assertions about the data field. -struct WeakInner<'a> { - weak: &'a atomic::AtomicUsize, - strong: &'a atomic::AtomicUsize, -} - -impl Weak { - /// Converts a raw pointer previously created by [`into_raw`] back into `Weak`. - /// - /// This can be used to safely get a strong reference (by calling [`upgrade`] - /// later) or to deallocate the weak count by dropping the `Weak`. - /// - /// It takes ownership of one weak reference (with the exception of pointers created by [`new`], - /// as these don't own anything; the method still works on them). - /// - /// # Safety - /// - /// The pointer must have originated from the [`into_raw`] and must still own its potential - /// weak reference. - /// - /// It is allowed for the strong count to be 0 at the time of calling this. Nevertheless, this - /// takes ownership of one weak reference currently represented as a raw pointer (the weak - /// count is not modified by this operation) and therefore it must be paired with a previous - /// call to [`into_raw`]. - /// # Examples - /// - /// ``` - /// use std::sync::{Arc, Weak}; - /// - /// let strong = Arc::new("hello".to_owned()); - /// - /// let raw_1 = Arc::downgrade(&strong).into_raw(); - /// let raw_2 = Arc::downgrade(&strong).into_raw(); - /// - /// assert_eq!(2, Arc::weak_count(&strong)); - /// - /// assert_eq!("hello", &*unsafe { Weak::from_raw(raw_1) }.upgrade().unwrap()); - /// assert_eq!(1, Arc::weak_count(&strong)); - /// - /// drop(strong); - /// - /// // Decrement the last weak count. - /// assert!(unsafe { Weak::from_raw(raw_2) }.upgrade().is_none()); - /// ``` - /// - /// [`new`]: Weak::new - /// [`into_raw`]: Weak::into_raw - /// [`upgrade`]: Weak::upgrade - #[inline] - #[stable(feature = "weak_into_raw", since = "1.45.0")] - pub unsafe fn from_raw(ptr: *const T) -> Self { - unsafe { Weak::from_raw_in(ptr, Global) } - } -} - -impl Weak { - /// Returns a raw pointer to the object `T` pointed to by this `Weak`. - /// - /// The pointer is valid only if there are some strong references. The pointer may be dangling, - /// unaligned or even [`null`] otherwise. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// use std::ptr; - /// - /// let strong = Arc::new("hello".to_owned()); - /// let weak = Arc::downgrade(&strong); - /// // Both point to the same object - /// assert!(ptr::eq(&*strong, weak.as_ptr())); - /// // The strong here keeps it alive, so we can still access the object. - /// assert_eq!("hello", unsafe { &*weak.as_ptr() }); - /// - /// drop(strong); - /// // But not any more. We can do weak.as_ptr(), but accessing the pointer would lead to - /// // undefined behaviour. - /// // assert_eq!("hello", unsafe { &*weak.as_ptr() }); - /// ``` - /// - /// [`null`]: core::ptr::null "ptr::null" - #[must_use] - #[stable(feature = "weak_into_raw", since = "1.45.0")] - pub fn as_ptr(&self) -> *const T { - let ptr: *mut ArcInner = NonNull::as_ptr(self.ptr); - - if is_dangling(ptr) { - // If the pointer is dangling, we return the sentinel directly. This cannot be - // a valid payload address, as the payload is at least as aligned as ArcInner (usize). - ptr as *const T - } else { - // SAFETY: if is_dangling returns false, then the pointer is dereferenceable. - // The payload may be dropped at this point, and we have to maintain provenance, - // so use raw pointer manipulation. - unsafe { ptr::addr_of_mut!((*ptr).data) } - } - } - - /// Consumes the `Weak` and turns it into a raw pointer. - /// - /// This converts the weak pointer into a raw pointer, while still preserving the ownership of - /// one weak reference (the weak count is not modified by this operation). It can be turned - /// back into the `Weak` with [`from_raw`]. - /// - /// The same restrictions of accessing the target of the pointer as with - /// [`as_ptr`] apply. - /// - /// # Examples - /// - /// ``` - /// use std::sync::{Arc, Weak}; - /// - /// let strong = Arc::new("hello".to_owned()); - /// let weak = Arc::downgrade(&strong); - /// let raw = weak.into_raw(); - /// - /// assert_eq!(1, Arc::weak_count(&strong)); - /// assert_eq!("hello", unsafe { &*raw }); - /// - /// drop(unsafe { Weak::from_raw(raw) }); - /// assert_eq!(0, Arc::weak_count(&strong)); - /// ``` - /// - /// [`from_raw`]: Weak::from_raw - /// [`as_ptr`]: Weak::as_ptr - #[must_use = "losing the pointer will leak memory"] - #[stable(feature = "weak_into_raw", since = "1.45.0")] - pub fn into_raw(self) -> *const T { - let result = self.as_ptr(); - mem::forget(self); - result - } - - /// Consumes the `Weak`, returning the wrapped pointer and allocator. - /// - /// This converts the weak pointer into a raw pointer, while still preserving the ownership of - /// one weak reference (the weak count is not modified by this operation). It can be turned - /// back into the `Weak` with [`from_raw_in`]. - /// - /// The same restrictions of accessing the target of the pointer as with - /// [`as_ptr`] apply. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// use std::sync::{Arc, Weak}; - /// use std::alloc::System; - /// - /// let strong = Arc::new_in("hello".to_owned(), System); - /// let weak = Arc::downgrade(&strong); - /// let (raw, alloc) = weak.into_raw_with_allocator(); - /// - /// assert_eq!(1, Arc::weak_count(&strong)); - /// assert_eq!("hello", unsafe { &*raw }); - /// - /// drop(unsafe { Weak::from_raw_in(raw, alloc) }); - /// assert_eq!(0, Arc::weak_count(&strong)); - /// ``` - /// - /// [`from_raw_in`]: Weak::from_raw_in - /// [`as_ptr`]: Weak::as_ptr - #[must_use = "losing the pointer will leak memory"] - #[unstable(feature = "allocator_api", issue = "32838")] - pub fn into_raw_with_allocator(self) -> (*const T, A) { - let this = mem::ManuallyDrop::new(self); - let result = this.as_ptr(); - // Safety: `this` is ManuallyDrop so the allocator will not be double-dropped - let alloc = unsafe { ptr::read(&this.alloc) }; - (result, alloc) - } - - /// Converts a raw pointer previously created by [`into_raw`] back into `Weak` in the provided - /// allocator. - /// - /// This can be used to safely get a strong reference (by calling [`upgrade`] - /// later) or to deallocate the weak count by dropping the `Weak`. - /// - /// It takes ownership of one weak reference (with the exception of pointers created by [`new`], - /// as these don't own anything; the method still works on them). - /// - /// # Safety - /// - /// The pointer must have originated from the [`into_raw`] and must still own its potential - /// weak reference, and must point to a block of memory allocated by `alloc`. - /// - /// It is allowed for the strong count to be 0 at the time of calling this. Nevertheless, this - /// takes ownership of one weak reference currently represented as a raw pointer (the weak - /// count is not modified by this operation) and therefore it must be paired with a previous - /// call to [`into_raw`]. - /// # Examples - /// - /// ``` - /// use std::sync::{Arc, Weak}; - /// - /// let strong = Arc::new("hello".to_owned()); - /// - /// let raw_1 = Arc::downgrade(&strong).into_raw(); - /// let raw_2 = Arc::downgrade(&strong).into_raw(); - /// - /// assert_eq!(2, Arc::weak_count(&strong)); - /// - /// assert_eq!("hello", &*unsafe { Weak::from_raw(raw_1) }.upgrade().unwrap()); - /// assert_eq!(1, Arc::weak_count(&strong)); - /// - /// drop(strong); - /// - /// // Decrement the last weak count. - /// assert!(unsafe { Weak::from_raw(raw_2) }.upgrade().is_none()); - /// ``` - /// - /// [`new`]: Weak::new - /// [`into_raw`]: Weak::into_raw - /// [`upgrade`]: Weak::upgrade - #[inline] - #[unstable(feature = "allocator_api", issue = "32838")] - pub unsafe fn from_raw_in(ptr: *const T, alloc: A) -> Self { - // See Weak::as_ptr for context on how the input pointer is derived. - - let ptr = if is_dangling(ptr) { - // This is a dangling Weak. - ptr as *mut ArcInner - } else { - // Otherwise, we're guaranteed the pointer came from a nondangling Weak. - // SAFETY: data_offset is safe to call, as ptr references a real (potentially dropped) T. - let offset = unsafe { data_offset(ptr) }; - // Thus, we reverse the offset to get the whole RcBox. - // SAFETY: the pointer originated from a Weak, so this offset is safe. - unsafe { ptr.byte_sub(offset) as *mut ArcInner } - }; - - // SAFETY: we now have recovered the original Weak pointer, so can create the Weak. - Weak { ptr: unsafe { NonNull::new_unchecked(ptr) }, alloc } - } -} - -impl Weak { - /// Attempts to upgrade the `Weak` pointer to an [`Arc`], delaying - /// dropping of the inner value if successful. - /// - /// Returns [`None`] if the inner value has since been dropped. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// let five = Arc::new(5); - /// - /// let weak_five = Arc::downgrade(&five); - /// - /// let strong_five: Option> = weak_five.upgrade(); - /// assert!(strong_five.is_some()); - /// - /// // Destroy all strong pointers. - /// drop(strong_five); - /// drop(five); - /// - /// assert!(weak_five.upgrade().is_none()); - /// ``` - #[must_use = "this returns a new `Arc`, \ - without modifying the original weak pointer"] - #[stable(feature = "arc_weak", since = "1.4.0")] - pub fn upgrade(&self) -> Option> - where - A: Clone, - { - #[inline] - fn checked_increment(n: usize) -> Option { - // Any write of 0 we can observe leaves the field in permanently zero state. - if n == 0 { - return None; - } - // See comments in `Arc::clone` for why we do this (for `mem::forget`). - assert!(n <= MAX_REFCOUNT, "{}", INTERNAL_OVERFLOW_ERROR); - Some(n + 1) - } - - // We use a CAS loop to increment the strong count instead of a - // fetch_add as this function should never take the reference count - // from zero to one. - // - // Relaxed is fine for the failure case because we don't have any expectations about the new state. - // Acquire is necessary for the success case to synchronise with `Arc::new_cyclic`, when the inner - // value can be initialized after `Weak` references have already been created. In that case, we - // expect to observe the fully initialized value. - if self.inner()?.strong.fetch_update(Acquire, Relaxed, checked_increment).is_ok() { - // SAFETY: pointer is not null, verified in checked_increment - unsafe { Some(Arc::from_inner_in(self.ptr, self.alloc.clone())) } - } else { - None - } - } - - /// Gets the number of strong (`Arc`) pointers pointing to this allocation. - /// - /// If `self` was created using [`Weak::new`], this will return 0. - #[must_use] - #[stable(feature = "weak_counts", since = "1.41.0")] - pub fn strong_count(&self) -> usize { - if let Some(inner) = self.inner() { inner.strong.load(Relaxed) } else { 0 } - } - - /// Gets an approximation of the number of `Weak` pointers pointing to this - /// allocation. - /// - /// If `self` was created using [`Weak::new`], or if there are no remaining - /// strong pointers, this will return 0. - /// - /// # Accuracy - /// - /// Due to implementation details, the returned value can be off by 1 in - /// either direction when other threads are manipulating any `Arc`s or - /// `Weak`s pointing to the same allocation. - #[must_use] - #[stable(feature = "weak_counts", since = "1.41.0")] - pub fn weak_count(&self) -> usize { - if let Some(inner) = self.inner() { - let weak = inner.weak.load(Acquire); - let strong = inner.strong.load(Relaxed); - if strong == 0 { - 0 - } else { - // Since we observed that there was at least one strong pointer - // after reading the weak count, we know that the implicit weak - // reference (present whenever any strong references are alive) - // was still around when we observed the weak count, and can - // therefore safely subtract it. - weak - 1 - } - } else { - 0 - } - } - - /// Returns `None` when the pointer is dangling and there is no allocated `ArcInner`, - /// (i.e., when this `Weak` was created by `Weak::new`). - #[inline] - fn inner(&self) -> Option> { - let ptr = self.ptr.as_ptr(); - if is_dangling(ptr) { - None - } else { - // We are careful to *not* create a reference covering the "data" field, as - // the field may be mutated concurrently (for example, if the last `Arc` - // is dropped, the data field will be dropped in-place). - Some(unsafe { WeakInner { strong: &(*ptr).strong, weak: &(*ptr).weak } }) - } - } - - /// Returns `true` if the two `Weak`s point to the same allocation similar to [`ptr::eq`], or if - /// both don't point to any allocation (because they were created with `Weak::new()`). However, - /// this function ignores the metadata of `dyn Trait` pointers. - /// - /// # Notes - /// - /// Since this compares pointers it means that `Weak::new()` will equal each - /// other, even though they don't point to any allocation. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// let first_rc = Arc::new(5); - /// let first = Arc::downgrade(&first_rc); - /// let second = Arc::downgrade(&first_rc); - /// - /// assert!(first.ptr_eq(&second)); - /// - /// let third_rc = Arc::new(5); - /// let third = Arc::downgrade(&third_rc); - /// - /// assert!(!first.ptr_eq(&third)); - /// ``` - /// - /// Comparing `Weak::new`. - /// - /// ``` - /// use std::sync::{Arc, Weak}; - /// - /// let first = Weak::new(); - /// let second = Weak::new(); - /// assert!(first.ptr_eq(&second)); - /// - /// let third_rc = Arc::new(()); - /// let third = Arc::downgrade(&third_rc); - /// assert!(!first.ptr_eq(&third)); - /// ``` - /// - /// [`ptr::eq`]: core::ptr::eq "ptr::eq" - #[inline] - #[must_use] - #[stable(feature = "weak_ptr_eq", since = "1.39.0")] - pub fn ptr_eq(&self, other: &Self) -> bool { - ptr::addr_eq(self.ptr.as_ptr(), other.ptr.as_ptr()) - } -} - -#[stable(feature = "arc_weak", since = "1.4.0")] -impl Clone for Weak { - /// Makes a clone of the `Weak` pointer that points to the same allocation. - /// - /// # Examples - /// - /// ``` - /// use std::sync::{Arc, Weak}; - /// - /// let weak_five = Arc::downgrade(&Arc::new(5)); - /// - /// let _ = Weak::clone(&weak_five); - /// ``` - #[inline] - fn clone(&self) -> Weak { - if let Some(inner) = self.inner() { - // See comments in Arc::clone() for why this is relaxed. This can use a - // fetch_add (ignoring the lock) because the weak count is only locked - // where are *no other* weak pointers in existence. (So we can't be - // running this code in that case). - let old_size = inner.weak.fetch_add(1, Relaxed); - - // See comments in Arc::clone() for why we do this (for mem::forget). - if old_size > MAX_REFCOUNT { - abort(); - } - } - - Weak { ptr: self.ptr, alloc: self.alloc.clone() } - } -} - -#[stable(feature = "downgraded_weak", since = "1.10.0")] -impl Default for Weak { - /// Constructs a new `Weak`, without allocating memory. - /// Calling [`upgrade`] on the return value always - /// gives [`None`]. - /// - /// [`upgrade`]: Weak::upgrade - /// - /// # Examples - /// - /// ``` - /// use std::sync::Weak; - /// - /// let empty: Weak = Default::default(); - /// assert!(empty.upgrade().is_none()); - /// ``` - fn default() -> Weak { - Weak::new() - } -} - -#[stable(feature = "arc_weak", since = "1.4.0")] -unsafe impl<#[may_dangle] T: ?Sized, A: Allocator> Drop for Weak { - /// Drops the `Weak` pointer. - /// - /// # Examples - /// - /// ``` - /// use std::sync::{Arc, Weak}; - /// - /// struct Foo; - /// - /// impl Drop for Foo { - /// fn drop(&mut self) { - /// println!("dropped!"); - /// } - /// } - /// - /// let foo = Arc::new(Foo); - /// let weak_foo = Arc::downgrade(&foo); - /// let other_weak_foo = Weak::clone(&weak_foo); - /// - /// drop(weak_foo); // Doesn't print anything - /// drop(foo); // Prints "dropped!" - /// - /// assert!(other_weak_foo.upgrade().is_none()); - /// ``` - fn drop(&mut self) { - // If we find out that we were the last weak pointer, then its time to - // deallocate the data entirely. See the discussion in Arc::drop() about - // the memory orderings - // - // It's not necessary to check for the locked state here, because the - // weak count can only be locked if there was precisely one weak ref, - // meaning that drop could only subsequently run ON that remaining weak - // ref, which can only happen after the lock is released. - let inner = if let Some(inner) = self.inner() { inner } else { return }; - - if inner.weak.fetch_sub(1, Release) == 1 { - acquire!(inner.weak); - - // Make sure we aren't trying to "deallocate" the shared static for empty slices - // used by Default::default. - debug_assert!( - !ptr::addr_eq(self.ptr.as_ptr(), &STATIC_INNER_SLICE.inner), - "Arc/Weaks backed by a static should never be deallocated. \ - Likely decrement_strong_count or from_raw were called too many times.", - ); - - unsafe { - self.alloc.deallocate(self.ptr.cast(), Layout::for_value_raw(self.ptr.as_ptr())) - } - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -trait ArcEqIdent { - fn eq(&self, other: &Arc) -> bool; - fn ne(&self, other: &Arc) -> bool; -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ArcEqIdent for Arc { - #[inline] - default fn eq(&self, other: &Arc) -> bool { - **self == **other - } - #[inline] - default fn ne(&self, other: &Arc) -> bool { - **self != **other - } -} - -/// We're doing this specialization here, and not as a more general optimization on `&T`, because it -/// would otherwise add a cost to all equality checks on refs. We assume that `Arc`s are used to -/// store large values, that are slow to clone, but also heavy to check for equality, causing this -/// cost to pay off more easily. It's also more likely to have two `Arc` clones, that point to -/// the same value, than two `&T`s. -/// -/// We can only do this when `T: Eq` as a `PartialEq` might be deliberately irreflexive. -#[stable(feature = "rust1", since = "1.0.0")] -impl ArcEqIdent for Arc { - #[inline] - fn eq(&self, other: &Arc) -> bool { - Arc::ptr_eq(self, other) || **self == **other - } - - #[inline] - fn ne(&self, other: &Arc) -> bool { - !Arc::ptr_eq(self, other) && **self != **other - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for Arc { - /// Equality for two `Arc`s. - /// - /// Two `Arc`s are equal if their inner values are equal, even if they are - /// stored in different allocation. - /// - /// If `T` also implements `Eq` (implying reflexivity of equality), - /// two `Arc`s that point to the same allocation are always equal. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// let five = Arc::new(5); - /// - /// assert!(five == Arc::new(5)); - /// ``` - #[inline] - fn eq(&self, other: &Arc) -> bool { - ArcEqIdent::eq(self, other) - } - - /// Inequality for two `Arc`s. - /// - /// Two `Arc`s are not equal if their inner values are not equal. - /// - /// If `T` also implements `Eq` (implying reflexivity of equality), - /// two `Arc`s that point to the same value are always equal. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// let five = Arc::new(5); - /// - /// assert!(five != Arc::new(6)); - /// ``` - #[inline] - fn ne(&self, other: &Arc) -> bool { - ArcEqIdent::ne(self, other) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialOrd for Arc { - /// Partial comparison for two `Arc`s. - /// - /// The two are compared by calling `partial_cmp()` on their inner values. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// use std::cmp::Ordering; - /// - /// let five = Arc::new(5); - /// - /// assert_eq!(Some(Ordering::Less), five.partial_cmp(&Arc::new(6))); - /// ``` - fn partial_cmp(&self, other: &Arc) -> Option { - (**self).partial_cmp(&**other) - } - - /// Less-than comparison for two `Arc`s. - /// - /// The two are compared by calling `<` on their inner values. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// let five = Arc::new(5); - /// - /// assert!(five < Arc::new(6)); - /// ``` - fn lt(&self, other: &Arc) -> bool { - *(*self) < *(*other) - } - - /// 'Less than or equal to' comparison for two `Arc`s. - /// - /// The two are compared by calling `<=` on their inner values. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// let five = Arc::new(5); - /// - /// assert!(five <= Arc::new(5)); - /// ``` - fn le(&self, other: &Arc) -> bool { - *(*self) <= *(*other) - } - - /// Greater-than comparison for two `Arc`s. - /// - /// The two are compared by calling `>` on their inner values. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// let five = Arc::new(5); - /// - /// assert!(five > Arc::new(4)); - /// ``` - fn gt(&self, other: &Arc) -> bool { - *(*self) > *(*other) - } - - /// 'Greater than or equal to' comparison for two `Arc`s. - /// - /// The two are compared by calling `>=` on their inner values. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// let five = Arc::new(5); - /// - /// assert!(five >= Arc::new(5)); - /// ``` - fn ge(&self, other: &Arc) -> bool { - *(*self) >= *(*other) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for Arc { - /// Comparison for two `Arc`s. - /// - /// The two are compared by calling `cmp()` on their inner values. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// use std::cmp::Ordering; - /// - /// let five = Arc::new(5); - /// - /// assert_eq!(Ordering::Less, five.cmp(&Arc::new(6))); - /// ``` - fn cmp(&self, other: &Arc) -> Ordering { - (**self).cmp(&**other) - } -} -#[stable(feature = "rust1", since = "1.0.0")] -impl Eq for Arc {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Display for Arc { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Display::fmt(&**self, f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for Arc { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&**self, f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Pointer for Arc { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Pointer::fmt(&core::ptr::addr_of!(**self), f) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl Default for Arc { - /// Creates a new `Arc`, with the `Default` value for `T`. - /// - /// # Examples - /// - /// ``` - /// use std::sync::Arc; - /// - /// let x: Arc = Default::default(); - /// assert_eq!(*x, 0); - /// ``` - fn default() -> Arc { - Arc::new(Default::default()) - } -} - -/// Struct to hold the static `ArcInner` used for empty `Arc` as -/// returned by `Default::default`. -/// -/// Layout notes: -/// * `repr(align(16))` so we can use it for `[T]` with `align_of::() <= 16`. -/// * `repr(C)` so `inner` is at offset 0 (and thus guaranteed to actually be aligned to 16). -/// * `[u8; 1]` (to be initialized with 0) so it can be used for `Arc`. -#[repr(C, align(16))] -struct SliceArcInnerForStatic { - inner: ArcInner<[u8; 1]>, -} -#[cfg(not(no_global_oom_handling))] -const MAX_STATIC_INNER_SLICE_ALIGNMENT: usize = 16; - -static STATIC_INNER_SLICE: SliceArcInnerForStatic = SliceArcInnerForStatic { - inner: ArcInner { - strong: atomic::AtomicUsize::new(1), - weak: atomic::AtomicUsize::new(1), - data: [0], - }, -}; - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "more_rc_default_impls", since = "CURRENT_RUSTC_VERSION")] -impl Default for Arc { - /// Creates an empty str inside an Arc - /// - /// This may or may not share an allocation with other Arcs. - #[inline] - fn default() -> Self { - let arc: Arc<[u8]> = Default::default(); - debug_assert!(core::str::from_utf8(&*arc).is_ok()); - let (ptr, alloc) = Arc::into_inner_with_allocator(arc); - unsafe { Arc::from_ptr_in(ptr.as_ptr() as *mut ArcInner, alloc) } - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "more_rc_default_impls", since = "CURRENT_RUSTC_VERSION")] -impl Default for Arc { - /// Creates an empty CStr inside an Arc - /// - /// This may or may not share an allocation with other Arcs. - #[inline] - fn default() -> Self { - use core::ffi::CStr; - let inner: NonNull> = NonNull::from(&STATIC_INNER_SLICE.inner); - let inner: NonNull> = - NonNull::new(inner.as_ptr() as *mut ArcInner).unwrap(); - // `this` semantically is the Arc "owned" by the static, so make sure not to drop it. - let this: mem::ManuallyDrop> = - unsafe { mem::ManuallyDrop::new(Arc::from_inner(inner)) }; - (*this).clone() - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "more_rc_default_impls", since = "CURRENT_RUSTC_VERSION")] -impl Default for Arc<[T]> { - /// Creates an empty `[T]` inside an Arc - /// - /// This may or may not share an allocation with other Arcs. - #[inline] - fn default() -> Self { - if mem::align_of::() <= MAX_STATIC_INNER_SLICE_ALIGNMENT { - // We take a reference to the whole struct instead of the ArcInner<[u8; 1]> inside it so - // we don't shrink the range of bytes the ptr is allowed to access under Stacked Borrows. - // (Miri complains on 32-bit targets with Arc<[Align16]> otherwise.) - // (Note that NonNull::from(&STATIC_INNER_SLICE.inner) is fine under Tree Borrows.) - let inner: NonNull = NonNull::from(&STATIC_INNER_SLICE); - let inner: NonNull> = inner.cast(); - // `this` semantically is the Arc "owned" by the static, so make sure not to drop it. - let this: mem::ManuallyDrop> = - unsafe { mem::ManuallyDrop::new(Arc::from_inner(inner)) }; - return (*this).clone(); - } - - // If T's alignment is too large for the static, make a new unique allocation. - let arr: [T; 0] = []; - Arc::from(arr) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Hash for Arc { - fn hash(&self, state: &mut H) { - (**self).hash(state) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "from_for_ptrs", since = "1.6.0")] -impl From for Arc { - /// Converts a `T` into an `Arc` - /// - /// The conversion moves the value into a - /// newly allocated `Arc`. It is equivalent to - /// calling `Arc::new(t)`. - /// - /// # Example - /// ```rust - /// # use std::sync::Arc; - /// let x = 5; - /// let arc = Arc::new(5); - /// - /// assert_eq!(Arc::from(x), arc); - /// ``` - fn from(t: T) -> Self { - Arc::new(t) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "shared_from_array", since = "1.74.0")] -impl From<[T; N]> for Arc<[T]> { - /// Converts a [`[T; N]`](prim@array) into an `Arc<[T]>`. - /// - /// The conversion moves the array into a newly allocated `Arc`. - /// - /// # Example - /// - /// ``` - /// # use std::sync::Arc; - /// let original: [i32; 3] = [1, 2, 3]; - /// let shared: Arc<[i32]> = Arc::from(original); - /// assert_eq!(&[1, 2, 3], &shared[..]); - /// ``` - #[inline] - fn from(v: [T; N]) -> Arc<[T]> { - Arc::<[T; N]>::from(v) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "shared_from_slice", since = "1.21.0")] -impl From<&[T]> for Arc<[T]> { - /// Allocate a reference-counted slice and fill it by cloning `v`'s items. - /// - /// # Example - /// - /// ``` - /// # use std::sync::Arc; - /// let original: &[i32] = &[1, 2, 3]; - /// let shared: Arc<[i32]> = Arc::from(original); - /// assert_eq!(&[1, 2, 3], &shared[..]); - /// ``` - #[inline] - fn from(v: &[T]) -> Arc<[T]> { - >::from_slice(v) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "shared_from_slice", since = "1.21.0")] -impl From<&str> for Arc { - /// Allocate a reference-counted `str` and copy `v` into it. - /// - /// # Example - /// - /// ``` - /// # use std::sync::Arc; - /// let shared: Arc = Arc::from("eggplant"); - /// assert_eq!("eggplant", &shared[..]); - /// ``` - #[inline] - fn from(v: &str) -> Arc { - let arc = Arc::<[u8]>::from(v.as_bytes()); - unsafe { Arc::from_raw(Arc::into_raw(arc) as *const str) } - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "shared_from_slice", since = "1.21.0")] -impl From for Arc { - /// Allocate a reference-counted `str` and copy `v` into it. - /// - /// # Example - /// - /// ``` - /// # use std::sync::Arc; - /// let unique: String = "eggplant".to_owned(); - /// let shared: Arc = Arc::from(unique); - /// assert_eq!("eggplant", &shared[..]); - /// ``` - #[inline] - fn from(v: String) -> Arc { - Arc::from(&v[..]) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "shared_from_slice", since = "1.21.0")] -impl From> for Arc { - /// Move a boxed object to a new, reference-counted allocation. - /// - /// # Example - /// - /// ``` - /// # use std::sync::Arc; - /// let unique: Box = Box::from("eggplant"); - /// let shared: Arc = Arc::from(unique); - /// assert_eq!("eggplant", &shared[..]); - /// ``` - #[inline] - fn from(v: Box) -> Arc { - Arc::from_box_in(v) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "shared_from_slice", since = "1.21.0")] -impl From> for Arc<[T], A> { - /// Allocate a reference-counted slice and move `v`'s items into it. - /// - /// # Example - /// - /// ``` - /// # use std::sync::Arc; - /// let unique: Vec = vec![1, 2, 3]; - /// let shared: Arc<[i32]> = Arc::from(unique); - /// assert_eq!(&[1, 2, 3], &shared[..]); - /// ``` - #[inline] - fn from(v: Vec) -> Arc<[T], A> { - unsafe { - let (vec_ptr, len, cap, alloc) = v.into_raw_parts_with_alloc(); - - let rc_ptr = Self::allocate_for_slice_in(len, &alloc); - ptr::copy_nonoverlapping(vec_ptr, ptr::addr_of_mut!((*rc_ptr).data) as *mut T, len); - - // Create a `Vec` with length 0, to deallocate the buffer - // without dropping its contents or the allocator - let _ = Vec::from_raw_parts_in(vec_ptr, 0, cap, &alloc); - - Self::from_ptr_in(rc_ptr, alloc) - } - } -} - -#[stable(feature = "shared_from_cow", since = "1.45.0")] -impl<'a, B> From> for Arc -where - B: ToOwned + ?Sized, - Arc: From<&'a B> + From, -{ - /// Create an atomically reference-counted pointer from - /// a clone-on-write pointer by copying its content. - /// - /// # Example - /// - /// ```rust - /// # use std::sync::Arc; - /// # use std::borrow::Cow; - /// let cow: Cow<'_, str> = Cow::Borrowed("eggplant"); - /// let shared: Arc = Arc::from(cow); - /// assert_eq!("eggplant", &shared[..]); - /// ``` - #[inline] - fn from(cow: Cow<'a, B>) -> Arc { - match cow { - Cow::Borrowed(s) => Arc::from(s), - Cow::Owned(s) => Arc::from(s), - } - } -} - -#[stable(feature = "shared_from_str", since = "1.62.0")] -impl From> for Arc<[u8]> { - /// Converts an atomically reference-counted string slice into a byte slice. - /// - /// # Example - /// - /// ``` - /// # use std::sync::Arc; - /// let string: Arc = Arc::from("eggplant"); - /// let bytes: Arc<[u8]> = Arc::from(string); - /// assert_eq!("eggplant".as_bytes(), bytes.as_ref()); - /// ``` - #[inline] - fn from(rc: Arc) -> Self { - // SAFETY: `str` has the same layout as `[u8]`. - unsafe { Arc::from_raw(Arc::into_raw(rc) as *const [u8]) } - } -} - -#[stable(feature = "boxed_slice_try_from", since = "1.43.0")] -impl TryFrom> for Arc<[T; N], A> { - type Error = Arc<[T], A>; - - fn try_from(boxed_slice: Arc<[T], A>) -> Result { - if boxed_slice.len() == N { - let (ptr, alloc) = Arc::into_inner_with_allocator(boxed_slice); - Ok(unsafe { Arc::from_inner_in(ptr.cast(), alloc) }) - } else { - Err(boxed_slice) - } - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "shared_from_iter", since = "1.37.0")] -impl FromIterator for Arc<[T]> { - /// Takes each element in the `Iterator` and collects it into an `Arc<[T]>`. - /// - /// # Performance characteristics - /// - /// ## The general case - /// - /// In the general case, collecting into `Arc<[T]>` is done by first - /// collecting into a `Vec`. That is, when writing the following: - /// - /// ```rust - /// # use std::sync::Arc; - /// let evens: Arc<[u8]> = (0..10).filter(|&x| x % 2 == 0).collect(); - /// # assert_eq!(&*evens, &[0, 2, 4, 6, 8]); - /// ``` - /// - /// this behaves as if we wrote: - /// - /// ```rust - /// # use std::sync::Arc; - /// let evens: Arc<[u8]> = (0..10).filter(|&x| x % 2 == 0) - /// .collect::>() // The first set of allocations happens here. - /// .into(); // A second allocation for `Arc<[T]>` happens here. - /// # assert_eq!(&*evens, &[0, 2, 4, 6, 8]); - /// ``` - /// - /// This will allocate as many times as needed for constructing the `Vec` - /// and then it will allocate once for turning the `Vec` into the `Arc<[T]>`. - /// - /// ## Iterators of known length - /// - /// When your `Iterator` implements `TrustedLen` and is of an exact size, - /// a single allocation will be made for the `Arc<[T]>`. For example: - /// - /// ```rust - /// # use std::sync::Arc; - /// let evens: Arc<[u8]> = (0..10).collect(); // Just a single allocation happens here. - /// # assert_eq!(&*evens, &*(0..10).collect::>()); - /// ``` - fn from_iter>(iter: I) -> Self { - ToArcSlice::to_arc_slice(iter.into_iter()) - } -} - -#[cfg(not(no_global_oom_handling))] -/// Specialization trait used for collecting into `Arc<[T]>`. -trait ToArcSlice: Iterator + Sized { - fn to_arc_slice(self) -> Arc<[T]>; -} - -#[cfg(not(no_global_oom_handling))] -impl> ToArcSlice for I { - default fn to_arc_slice(self) -> Arc<[T]> { - self.collect::>().into() - } -} - -#[cfg(not(no_global_oom_handling))] -impl> ToArcSlice for I { - fn to_arc_slice(self) -> Arc<[T]> { - // This is the case for a `TrustedLen` iterator. - let (low, high) = self.size_hint(); - if let Some(high) = high { - debug_assert_eq!( - low, - high, - "TrustedLen iterator's size hint is not exact: {:?}", - (low, high) - ); - - unsafe { - // SAFETY: We need to ensure that the iterator has an exact length and we have. - Arc::from_iter_exact(self, low) - } - } else { - // TrustedLen contract guarantees that `upper_bound == None` implies an iterator - // length exceeding `usize::MAX`. - // The default implementation would collect into a vec which would panic. - // Thus we panic here immediately without invoking `Vec` code. - panic!("capacity overflow"); - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl borrow::Borrow for Arc { - fn borrow(&self) -> &T { - &**self - } -} - -#[stable(since = "1.5.0", feature = "smart_ptr_as_ref")] -impl AsRef for Arc { - fn as_ref(&self) -> &T { - &**self - } -} - -#[stable(feature = "pin", since = "1.33.0")] -impl Unpin for Arc {} - -/// Get the offset within an `ArcInner` for the payload behind a pointer. -/// -/// # Safety -/// -/// The pointer must point to (and have valid metadata for) a previously -/// valid instance of T, but the T is allowed to be dropped. -unsafe fn data_offset(ptr: *const T) -> usize { - // Align the unsized value to the end of the ArcInner. - // Because RcBox is repr(C), it will always be the last field in memory. - // SAFETY: since the only unsized types possible are slices, trait objects, - // and extern types, the input safety requirement is currently enough to - // satisfy the requirements of align_of_val_raw; this is an implementation - // detail of the language that must not be relied upon outside of std. - unsafe { data_offset_align(align_of_val_raw(ptr)) } -} - -#[inline] -fn data_offset_align(align: usize) -> usize { - let layout = Layout::new::>(); - layout.size() + layout.padding_needed_for(align) -} - -#[stable(feature = "arc_error", since = "1.52.0")] -impl core::error::Error for Arc { - #[allow(deprecated, deprecated_in_future)] - fn description(&self) -> &str { - core::error::Error::description(&**self) - } - - #[allow(deprecated)] - fn cause(&self) -> Option<&dyn core::error::Error> { - core::error::Error::cause(&**self) - } - - fn source(&self) -> Option<&(dyn core::error::Error + 'static)> { - core::error::Error::source(&**self) - } - - fn provide<'a>(&'a self, req: &mut core::error::Request<'a>) { - core::error::Error::provide(&**self, req); - } -} diff --git a/library/alloc/src/sync/tests.rs b/library/alloc/src/sync/tests.rs deleted file mode 100644 index 49eae718c1690..0000000000000 --- a/library/alloc/src/sync/tests.rs +++ /dev/null @@ -1,717 +0,0 @@ -use super::*; - -use std::clone::Clone; -use std::mem::MaybeUninit; -use std::option::Option::None; -use std::sync::atomic::AtomicUsize; -use std::sync::atomic::Ordering::SeqCst; -use std::sync::mpsc::channel; -use std::sync::Mutex; -use std::thread; - -struct Canary(*mut AtomicUsize); - -impl Drop for Canary { - fn drop(&mut self) { - unsafe { - match *self { - Canary(c) => { - (*c).fetch_add(1, SeqCst); - } - } - } - } -} - -struct AllocCanary<'a>(&'a AtomicUsize); - -impl<'a> AllocCanary<'a> { - fn new(counter: &'a AtomicUsize) -> Self { - counter.fetch_add(1, SeqCst); - Self(counter) - } -} - -unsafe impl Allocator for AllocCanary<'_> { - fn allocate(&self, layout: Layout) -> Result, AllocError> { - std::alloc::Global.allocate(layout) - } - - unsafe fn deallocate(&self, ptr: NonNull, layout: Layout) { - unsafe { std::alloc::Global.deallocate(ptr, layout) } - } -} - -impl Clone for AllocCanary<'_> { - fn clone(&self) -> Self { - Self::new(self.0) - } -} - -impl Drop for AllocCanary<'_> { - fn drop(&mut self) { - self.0.fetch_sub(1, SeqCst); - } -} - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn manually_share_arc() { - let v = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; - let arc_v = Arc::new(v); - - let (tx, rx) = channel(); - - let _t = thread::spawn(move || { - let arc_v: Arc> = rx.recv().unwrap(); - assert_eq!((*arc_v)[3], 4); - }); - - tx.send(arc_v.clone()).unwrap(); - - assert_eq!((*arc_v)[2], 3); - assert_eq!((*arc_v)[4], 5); -} - -#[test] -fn test_arc_get_mut() { - let mut x = Arc::new(3); - *Arc::get_mut(&mut x).unwrap() = 4; - assert_eq!(*x, 4); - let y = x.clone(); - assert!(Arc::get_mut(&mut x).is_none()); - drop(y); - assert!(Arc::get_mut(&mut x).is_some()); - let _w = Arc::downgrade(&x); - assert!(Arc::get_mut(&mut x).is_none()); -} - -#[test] -fn weak_counts() { - assert_eq!(Weak::weak_count(&Weak::::new()), 0); - assert_eq!(Weak::strong_count(&Weak::::new()), 0); - - let a = Arc::new(0); - let w = Arc::downgrade(&a); - assert_eq!(Weak::strong_count(&w), 1); - assert_eq!(Weak::weak_count(&w), 1); - let w2 = w.clone(); - assert_eq!(Weak::strong_count(&w), 1); - assert_eq!(Weak::weak_count(&w), 2); - assert_eq!(Weak::strong_count(&w2), 1); - assert_eq!(Weak::weak_count(&w2), 2); - drop(w); - assert_eq!(Weak::strong_count(&w2), 1); - assert_eq!(Weak::weak_count(&w2), 1); - let a2 = a.clone(); - assert_eq!(Weak::strong_count(&w2), 2); - assert_eq!(Weak::weak_count(&w2), 1); - drop(a2); - drop(a); - assert_eq!(Weak::strong_count(&w2), 0); - assert_eq!(Weak::weak_count(&w2), 0); - drop(w2); -} - -#[test] -fn try_unwrap() { - let x = Arc::new(3); - assert_eq!(Arc::try_unwrap(x), Ok(3)); - let x = Arc::new(4); - let _y = x.clone(); - assert_eq!(Arc::try_unwrap(x), Err(Arc::new(4))); - let x = Arc::new(5); - let _w = Arc::downgrade(&x); - assert_eq!(Arc::try_unwrap(x), Ok(5)); -} - -#[test] -fn into_inner() { - for _ in 0..100 - // ^ Increase chances of hitting potential race conditions - { - let x = Arc::new(3); - let y = Arc::clone(&x); - let r_thread = std::thread::spawn(|| Arc::into_inner(x)); - let s_thread = std::thread::spawn(|| Arc::into_inner(y)); - let r = r_thread.join().expect("r_thread panicked"); - let s = s_thread.join().expect("s_thread panicked"); - assert!( - matches!((r, s), (None, Some(3)) | (Some(3), None)), - "assertion failed: unexpected result `{:?}`\ - \n expected `(None, Some(3))` or `(Some(3), None)`", - (r, s), - ); - } - - let x = Arc::new(3); - assert_eq!(Arc::into_inner(x), Some(3)); - - let x = Arc::new(4); - let y = Arc::clone(&x); - assert_eq!(Arc::into_inner(x), None); - assert_eq!(Arc::into_inner(y), Some(4)); - - let x = Arc::new(5); - let _w = Arc::downgrade(&x); - assert_eq!(Arc::into_inner(x), Some(5)); -} - -#[test] -fn into_from_raw() { - let x = Arc::new(Box::new("hello")); - let y = x.clone(); - - let x_ptr = Arc::into_raw(x); - drop(y); - unsafe { - assert_eq!(**x_ptr, "hello"); - - let x = Arc::from_raw(x_ptr); - assert_eq!(**x, "hello"); - - assert_eq!(Arc::try_unwrap(x).map(|x| *x), Ok("hello")); - } -} - -#[test] -fn test_into_from_raw_unsized() { - use std::fmt::Display; - use std::string::ToString; - - let arc: Arc = Arc::from("foo"); - - let ptr = Arc::into_raw(arc.clone()); - let arc2 = unsafe { Arc::from_raw(ptr) }; - - assert_eq!(unsafe { &*ptr }, "foo"); - assert_eq!(arc, arc2); - - let arc: Arc = Arc::new(123); - - let ptr = Arc::into_raw(arc.clone()); - let arc2 = unsafe { Arc::from_raw(ptr) }; - - assert_eq!(unsafe { &*ptr }.to_string(), "123"); - assert_eq!(arc2.to_string(), "123"); -} - -#[test] -fn into_from_weak_raw() { - let x = Arc::new(Box::new("hello")); - let y = Arc::downgrade(&x); - - let y_ptr = Weak::into_raw(y); - unsafe { - assert_eq!(**y_ptr, "hello"); - - let y = Weak::from_raw(y_ptr); - let y_up = Weak::upgrade(&y).unwrap(); - assert_eq!(**y_up, "hello"); - drop(y_up); - - assert_eq!(Arc::try_unwrap(x).map(|x| *x), Ok("hello")); - } -} - -#[test] -fn test_into_from_weak_raw_unsized() { - use std::fmt::Display; - use std::string::ToString; - - let arc: Arc = Arc::from("foo"); - let weak: Weak = Arc::downgrade(&arc); - - let ptr = Weak::into_raw(weak.clone()); - let weak2 = unsafe { Weak::from_raw(ptr) }; - - assert_eq!(unsafe { &*ptr }, "foo"); - assert!(weak.ptr_eq(&weak2)); - - let arc: Arc = Arc::new(123); - let weak: Weak = Arc::downgrade(&arc); - - let ptr = Weak::into_raw(weak.clone()); - let weak2 = unsafe { Weak::from_raw(ptr) }; - - assert_eq!(unsafe { &*ptr }.to_string(), "123"); - assert!(weak.ptr_eq(&weak2)); -} - -#[test] -fn test_cowarc_clone_make_mut() { - let mut cow0 = Arc::new(75); - let mut cow1 = cow0.clone(); - let mut cow2 = cow1.clone(); - - assert!(75 == *Arc::make_mut(&mut cow0)); - assert!(75 == *Arc::make_mut(&mut cow1)); - assert!(75 == *Arc::make_mut(&mut cow2)); - - *Arc::make_mut(&mut cow0) += 1; - *Arc::make_mut(&mut cow1) += 2; - *Arc::make_mut(&mut cow2) += 3; - - assert!(76 == *cow0); - assert!(77 == *cow1); - assert!(78 == *cow2); - - // none should point to the same backing memory - assert!(*cow0 != *cow1); - assert!(*cow0 != *cow2); - assert!(*cow1 != *cow2); -} - -#[test] -fn test_cowarc_clone_unique2() { - let mut cow0 = Arc::new(75); - let cow1 = cow0.clone(); - let cow2 = cow1.clone(); - - assert!(75 == *cow0); - assert!(75 == *cow1); - assert!(75 == *cow2); - - *Arc::make_mut(&mut cow0) += 1; - assert!(76 == *cow0); - assert!(75 == *cow1); - assert!(75 == *cow2); - - // cow1 and cow2 should share the same contents - // cow0 should have a unique reference - assert!(*cow0 != *cow1); - assert!(*cow0 != *cow2); - assert!(*cow1 == *cow2); -} - -#[test] -fn test_cowarc_clone_weak() { - let mut cow0 = Arc::new(75); - let cow1_weak = Arc::downgrade(&cow0); - - assert!(75 == *cow0); - assert!(75 == *cow1_weak.upgrade().unwrap()); - - *Arc::make_mut(&mut cow0) += 1; - - assert!(76 == *cow0); - assert!(cow1_weak.upgrade().is_none()); -} - -#[test] -fn test_live() { - let x = Arc::new(5); - let y = Arc::downgrade(&x); - assert!(y.upgrade().is_some()); -} - -#[test] -fn test_dead() { - let x = Arc::new(5); - let y = Arc::downgrade(&x); - drop(x); - assert!(y.upgrade().is_none()); -} - -#[test] -fn weak_self_cyclic() { - struct Cycle { - x: Mutex>>, - } - - let a = Arc::new(Cycle { x: Mutex::new(None) }); - let b = Arc::downgrade(&a.clone()); - *a.x.lock().unwrap() = Some(b); - - // hopefully we don't double-free (or leak)... -} - -#[test] -fn drop_arc() { - let mut canary = AtomicUsize::new(0); - let x = Arc::new(Canary(&mut canary as *mut AtomicUsize)); - drop(x); - assert!(canary.load(Acquire) == 1); -} - -#[test] -fn drop_arc_weak() { - let mut canary = AtomicUsize::new(0); - let arc = Arc::new(Canary(&mut canary as *mut AtomicUsize)); - let arc_weak = Arc::downgrade(&arc); - assert!(canary.load(Acquire) == 0); - drop(arc); - assert!(canary.load(Acquire) == 1); - drop(arc_weak); -} - -#[test] -fn test_strong_count() { - let a = Arc::new(0); - assert!(Arc::strong_count(&a) == 1); - let w = Arc::downgrade(&a); - assert!(Arc::strong_count(&a) == 1); - let b = w.upgrade().expect(""); - assert!(Arc::strong_count(&b) == 2); - assert!(Arc::strong_count(&a) == 2); - drop(w); - drop(a); - assert!(Arc::strong_count(&b) == 1); - let c = b.clone(); - assert!(Arc::strong_count(&b) == 2); - assert!(Arc::strong_count(&c) == 2); -} - -#[test] -fn test_weak_count() { - let a = Arc::new(0); - assert!(Arc::strong_count(&a) == 1); - assert!(Arc::weak_count(&a) == 0); - let w = Arc::downgrade(&a); - assert!(Arc::strong_count(&a) == 1); - assert!(Arc::weak_count(&a) == 1); - let x = w.clone(); - assert!(Arc::weak_count(&a) == 2); - drop(w); - drop(x); - assert!(Arc::strong_count(&a) == 1); - assert!(Arc::weak_count(&a) == 0); - let c = a.clone(); - assert!(Arc::strong_count(&a) == 2); - assert!(Arc::weak_count(&a) == 0); - let d = Arc::downgrade(&c); - assert!(Arc::weak_count(&c) == 1); - assert!(Arc::strong_count(&c) == 2); - - drop(a); - drop(c); - drop(d); -} - -#[test] -fn show_arc() { - let a = Arc::new(5); - assert_eq!(format!("{a:?}"), "5"); -} - -// Make sure deriving works with Arc -#[derive(Eq, Ord, PartialEq, PartialOrd, Clone, Debug, Default)] -struct Foo { - inner: Arc, -} - -#[test] -fn test_unsized() { - let x: Arc<[i32]> = Arc::new([1, 2, 3]); - assert_eq!(format!("{x:?}"), "[1, 2, 3]"); - let y = Arc::downgrade(&x.clone()); - drop(x); - assert!(y.upgrade().is_none()); -} - -#[test] -fn test_maybe_thin_unsized() { - // If/when custom thin DSTs exist, this test should be updated to use one - use std::ffi::{CStr, CString}; - - let x: Arc = Arc::from(CString::new("swordfish").unwrap().into_boxed_c_str()); - assert_eq!(format!("{x:?}"), "\"swordfish\""); - let y: Weak = Arc::downgrade(&x); - drop(x); - - // At this point, the weak points to a dropped DST - assert!(y.upgrade().is_none()); - // But we still need to be able to get the alloc layout to drop. - // CStr has no drop glue, but custom DSTs might, and need to work. - drop(y); -} - -#[test] -fn test_from_owned() { - let foo = 123; - let foo_arc = Arc::from(foo); - assert!(123 == *foo_arc); -} - -#[test] -fn test_new_weak() { - let foo: Weak = Weak::new(); - assert!(foo.upgrade().is_none()); -} - -#[test] -fn test_ptr_eq() { - let five = Arc::new(5); - let same_five = five.clone(); - let other_five = Arc::new(5); - - assert!(Arc::ptr_eq(&five, &same_five)); - assert!(!Arc::ptr_eq(&five, &other_five)); -} - -#[test] -#[cfg_attr(target_os = "emscripten", ignore)] -fn test_weak_count_locked() { - let mut a = Arc::new(atomic::AtomicBool::new(false)); - let a2 = a.clone(); - let t = thread::spawn(move || { - // Miri is too slow - let count = if cfg!(miri) { 1000 } else { 1000000 }; - for _i in 0..count { - Arc::get_mut(&mut a); - } - a.store(true, SeqCst); - }); - - while !a2.load(SeqCst) { - let n = Arc::weak_count(&a2); - assert!(n < 2, "bad weak count: {}", n); - #[cfg(miri)] // Miri's scheduler does not guarantee liveness, and thus needs this hint. - std::hint::spin_loop(); - } - t.join().unwrap(); -} - -#[test] -fn test_from_str() { - let r: Arc = Arc::from("foo"); - - assert_eq!(&r[..], "foo"); -} - -#[test] -fn test_copy_from_slice() { - let s: &[u32] = &[1, 2, 3]; - let r: Arc<[u32]> = Arc::from(s); - - assert_eq!(&r[..], [1, 2, 3]); -} - -#[test] -fn test_clone_from_slice() { - #[derive(Clone, Debug, Eq, PartialEq)] - struct X(u32); - - let s: &[X] = &[X(1), X(2), X(3)]; - let r: Arc<[X]> = Arc::from(s); - - assert_eq!(&r[..], s); -} - -#[test] -#[should_panic] -fn test_clone_from_slice_panic() { - use std::string::{String, ToString}; - - struct Fail(u32, String); - - impl Clone for Fail { - fn clone(&self) -> Fail { - if self.0 == 2 { - panic!(); - } - Fail(self.0, self.1.clone()) - } - } - - let s: &[Fail] = - &[Fail(0, "foo".to_string()), Fail(1, "bar".to_string()), Fail(2, "baz".to_string())]; - - // Should panic, but not cause memory corruption - let _r: Arc<[Fail]> = Arc::from(s); -} - -#[test] -fn test_from_box() { - let b: Box = Box::new(123); - let r: Arc = Arc::from(b); - - assert_eq!(*r, 123); -} - -#[test] -fn test_from_box_str() { - use std::string::String; - - let s = String::from("foo").into_boxed_str(); - let r: Arc = Arc::from(s); - - assert_eq!(&r[..], "foo"); -} - -#[test] -fn test_from_box_slice() { - let s = vec![1, 2, 3].into_boxed_slice(); - let r: Arc<[u32]> = Arc::from(s); - - assert_eq!(&r[..], [1, 2, 3]); -} - -#[test] -fn test_from_box_trait() { - use std::fmt::Display; - use std::string::ToString; - - let b: Box = Box::new(123); - let r: Arc = Arc::from(b); - - assert_eq!(r.to_string(), "123"); -} - -#[test] -fn test_from_box_trait_zero_sized() { - use std::fmt::Debug; - - let b: Box = Box::new(()); - let r: Arc = Arc::from(b); - - assert_eq!(format!("{r:?}"), "()"); -} - -#[test] -fn test_from_vec() { - let v = vec![1, 2, 3]; - let r: Arc<[u32]> = Arc::from(v); - - assert_eq!(&r[..], [1, 2, 3]); -} - -#[test] -fn test_downcast() { - use std::any::Any; - - let r1: Arc = Arc::new(i32::MAX); - let r2: Arc = Arc::new("abc"); - - assert!(r1.clone().downcast::().is_err()); - - let r1i32 = r1.downcast::(); - assert!(r1i32.is_ok()); - assert_eq!(r1i32.unwrap(), Arc::new(i32::MAX)); - - assert!(r2.clone().downcast::().is_err()); - - let r2str = r2.downcast::<&'static str>(); - assert!(r2str.is_ok()); - assert_eq!(r2str.unwrap(), Arc::new("abc")); -} - -#[test] -fn test_array_from_slice() { - let v = vec![1, 2, 3]; - let r: Arc<[u32]> = Arc::from(v); - - let a: Result, _> = r.clone().try_into(); - assert!(a.is_ok()); - - let a: Result, _> = r.clone().try_into(); - assert!(a.is_err()); -} - -#[test] -fn test_arc_cyclic_with_zero_refs() { - struct ZeroRefs { - inner: Weak, - } - let zero_refs = Arc::new_cyclic(|inner| { - assert_eq!(inner.strong_count(), 0); - assert!(inner.upgrade().is_none()); - ZeroRefs { inner: Weak::new() } - }); - - assert_eq!(Arc::strong_count(&zero_refs), 1); - assert_eq!(Arc::weak_count(&zero_refs), 0); - assert_eq!(zero_refs.inner.strong_count(), 0); - assert_eq!(zero_refs.inner.weak_count(), 0); -} - -#[test] -fn test_arc_new_cyclic_one_ref() { - struct OneRef { - inner: Weak, - } - let one_ref = Arc::new_cyclic(|inner| { - assert_eq!(inner.strong_count(), 0); - assert!(inner.upgrade().is_none()); - OneRef { inner: inner.clone() } - }); - - assert_eq!(Arc::strong_count(&one_ref), 1); - assert_eq!(Arc::weak_count(&one_ref), 1); - - let one_ref2 = Weak::upgrade(&one_ref.inner).unwrap(); - assert!(Arc::ptr_eq(&one_ref, &one_ref2)); - - assert_eq!(Arc::strong_count(&one_ref), 2); - assert_eq!(Arc::weak_count(&one_ref), 1); -} - -#[test] -fn test_arc_cyclic_two_refs() { - struct TwoRefs { - inner1: Weak, - inner2: Weak, - } - let two_refs = Arc::new_cyclic(|inner| { - assert_eq!(inner.strong_count(), 0); - assert!(inner.upgrade().is_none()); - - let inner1 = inner.clone(); - let inner2 = inner1.clone(); - - TwoRefs { inner1, inner2 } - }); - - assert_eq!(Arc::strong_count(&two_refs), 1); - assert_eq!(Arc::weak_count(&two_refs), 2); - - let two_refs1 = Weak::upgrade(&two_refs.inner1).unwrap(); - assert!(Arc::ptr_eq(&two_refs, &two_refs1)); - - let two_refs2 = Weak::upgrade(&two_refs.inner2).unwrap(); - assert!(Arc::ptr_eq(&two_refs, &two_refs2)); - - assert_eq!(Arc::strong_count(&two_refs), 3); - assert_eq!(Arc::weak_count(&two_refs), 2); -} - -/// Test for Arc::drop bug (https://github.com/rust-lang/rust/issues/55005) -#[test] -#[cfg(miri)] // relies on Stacked Borrows in Miri -fn arc_drop_dereferenceable_race() { - // The bug seems to take up to 700 iterations to reproduce with most seeds (tested 0-9). - for _ in 0..750 { - let arc_1 = Arc::new(()); - let arc_2 = arc_1.clone(); - let thread = thread::spawn(|| drop(arc_2)); - // Spin a bit; makes the race more likely to appear - let mut i = 0; - while i < 256 { - i += 1; - } - drop(arc_1); - thread.join().unwrap(); - } -} - -#[test] -fn arc_doesnt_leak_allocator() { - let counter = AtomicUsize::new(0); - - { - let arc: Arc = Arc::new_in(5usize, AllocCanary::new(&counter)); - drop(arc.downcast::().unwrap()); - - let arc: Arc = Arc::new_in(5usize, AllocCanary::new(&counter)); - drop(unsafe { arc.downcast_unchecked::() }); - - let arc = Arc::new_in(MaybeUninit::::new(5usize), AllocCanary::new(&counter)); - drop(unsafe { arc.assume_init() }); - - let arc: Arc<[MaybeUninit], _> = - Arc::new_zeroed_slice_in(5, AllocCanary::new(&counter)); - drop(unsafe { arc.assume_init() }); - } - - assert_eq!(counter.load(SeqCst), 0); -} diff --git a/library/alloc/src/task.rs b/library/alloc/src/task.rs deleted file mode 100644 index a3fa6585a37f8..0000000000000 --- a/library/alloc/src/task.rs +++ /dev/null @@ -1,349 +0,0 @@ -#![stable(feature = "wake_trait", since = "1.51.0")] - -//! Types and Traits for working with asynchronous tasks. -//! -//! **Note**: Some of the types in this module are only available -//! on platforms that support atomic loads and stores of pointers. -//! This may be detected at compile time using -//! `#[cfg(target_has_atomic = "ptr")]`. - -use crate::rc::Rc; -use core::mem::ManuallyDrop; -use core::task::{LocalWaker, RawWaker, RawWakerVTable}; - -#[cfg(target_has_atomic = "ptr")] -use crate::sync::Arc; -#[cfg(target_has_atomic = "ptr")] -use core::task::Waker; - -/// The implementation of waking a task on an executor. -/// -/// This trait can be used to create a [`Waker`]. An executor can define an -/// implementation of this trait, and use that to construct a [`Waker`] to pass -/// to the tasks that are executed on that executor. -/// -/// This trait is a memory-safe and ergonomic alternative to constructing a -/// [`RawWaker`]. It supports the common executor design in which the data used -/// to wake up a task is stored in an [`Arc`]. Some executors (especially -/// those for embedded systems) cannot use this API, which is why [`RawWaker`] -/// exists as an alternative for those systems. -/// -/// To construct a [`Waker`] from some type `W` implementing this trait, -/// wrap it in an [`Arc`](Arc) and call `Waker::from()` on that. -/// It is also possible to convert to [`RawWaker`] in the same way. -/// -/// -/// -/// # Examples -/// -/// A basic `block_on` function that takes a future and runs it to completion on -/// the current thread. -/// -/// **Note:** This example trades correctness for simplicity. In order to prevent -/// deadlocks, production-grade implementations will also need to handle -/// intermediate calls to `thread::unpark` as well as nested invocations. -/// -/// ```rust -/// use std::future::Future; -/// use std::sync::Arc; -/// use std::task::{Context, Poll, Wake}; -/// use std::thread::{self, Thread}; -/// use core::pin::pin; -/// -/// /// A waker that wakes up the current thread when called. -/// struct ThreadWaker(Thread); -/// -/// impl Wake for ThreadWaker { -/// fn wake(self: Arc) { -/// self.0.unpark(); -/// } -/// } -/// -/// /// Run a future to completion on the current thread. -/// fn block_on(fut: impl Future) -> T { -/// // Pin the future so it can be polled. -/// let mut fut = pin!(fut); -/// -/// // Create a new context to be passed to the future. -/// let t = thread::current(); -/// let waker = Arc::new(ThreadWaker(t)).into(); -/// let mut cx = Context::from_waker(&waker); -/// -/// // Run the future to completion. -/// loop { -/// match fut.as_mut().poll(&mut cx) { -/// Poll::Ready(res) => return res, -/// Poll::Pending => thread::park(), -/// } -/// } -/// } -/// -/// block_on(async { -/// println!("Hi from inside a future!"); -/// }); -/// ``` -#[cfg(target_has_atomic = "ptr")] -#[stable(feature = "wake_trait", since = "1.51.0")] -pub trait Wake { - /// Wake this task. - #[stable(feature = "wake_trait", since = "1.51.0")] - fn wake(self: Arc); - - /// Wake this task without consuming the waker. - /// - /// If an executor supports a cheaper way to wake without consuming the - /// waker, it should override this method. By default, it clones the - /// [`Arc`] and calls [`wake`] on the clone. - /// - /// [`wake`]: Wake::wake - #[stable(feature = "wake_trait", since = "1.51.0")] - fn wake_by_ref(self: &Arc) { - self.clone().wake(); - } -} -#[cfg(target_has_atomic = "ptr")] -#[stable(feature = "wake_trait", since = "1.51.0")] -impl From> for Waker { - /// Use a [`Wake`]-able type as a `Waker`. - /// - /// No heap allocations or atomic operations are used for this conversion. - fn from(waker: Arc) -> Waker { - // SAFETY: This is safe because raw_waker safely constructs - // a RawWaker from Arc. - unsafe { Waker::from_raw(raw_waker(waker)) } - } -} -#[cfg(target_has_atomic = "ptr")] -#[stable(feature = "wake_trait", since = "1.51.0")] -impl From> for RawWaker { - /// Use a `Wake`-able type as a `RawWaker`. - /// - /// No heap allocations or atomic operations are used for this conversion. - fn from(waker: Arc) -> RawWaker { - raw_waker(waker) - } -} - -// NB: This private function for constructing a RawWaker is used, rather than -// inlining this into the `From> for RawWaker` impl, to ensure that -// the safety of `From> for Waker` does not depend on the correct -// trait dispatch - instead both impls call this function directly and -// explicitly. -#[cfg(target_has_atomic = "ptr")] -#[inline(always)] -fn raw_waker(waker: Arc) -> RawWaker { - // Increment the reference count of the arc to clone it. - // - // The #[inline(always)] is to ensure that raw_waker and clone_waker are - // always generated in the same code generation unit as one another, and - // therefore that the structurally identical const-promoted RawWakerVTable - // within both functions is deduplicated at LLVM IR code generation time. - // This allows optimizing Waker::will_wake to a single pointer comparison of - // the vtable pointers, rather than comparing all four function pointers - // within the vtables. - #[inline(always)] - unsafe fn clone_waker(waker: *const ()) -> RawWaker { - unsafe { Arc::increment_strong_count(waker as *const W) }; - RawWaker::new( - waker, - &RawWakerVTable::new(clone_waker::, wake::, wake_by_ref::, drop_waker::), - ) - } - - // Wake by value, moving the Arc into the Wake::wake function - unsafe fn wake(waker: *const ()) { - let waker = unsafe { Arc::from_raw(waker as *const W) }; - ::wake(waker); - } - - // Wake by reference, wrap the waker in ManuallyDrop to avoid dropping it - unsafe fn wake_by_ref(waker: *const ()) { - let waker = unsafe { ManuallyDrop::new(Arc::from_raw(waker as *const W)) }; - ::wake_by_ref(&waker); - } - - // Decrement the reference count of the Arc on drop - unsafe fn drop_waker(waker: *const ()) { - unsafe { Arc::decrement_strong_count(waker as *const W) }; - } - - RawWaker::new( - Arc::into_raw(waker) as *const (), - &RawWakerVTable::new(clone_waker::, wake::, wake_by_ref::, drop_waker::), - ) -} - -/// An analogous trait to `Wake` but used to construct a `LocalWaker`. This API -/// works in exactly the same way as `Wake`, except that it uses an `Rc` instead -/// of an `Arc`, and the result is a `LocalWaker` instead of a `Waker`. -/// -/// The benefits of using `LocalWaker` over `Waker` are that it allows the local waker -/// to hold data that does not implement `Send` and `Sync`. Additionally, it saves calls -/// to `Arc::clone`, which requires atomic synchronization. -/// -/// -/// # Examples -/// -/// This is a simplified example of a `spawn` and a `block_on` function. The `spawn` function -/// is used to push new tasks onto the run queue, while the block on function will remove them -/// and poll them. When a task is woken, it will put itself back on the run queue to be polled -/// by the executor. -/// -/// **Note:** This example trades correctness for simplicity. A real world example would interleave -/// poll calls with calls to an io reactor to wait for events instead of spinning on a loop. -/// -/// ```rust -/// #![feature(local_waker)] -/// #![feature(noop_waker)] -/// use std::task::{LocalWake, ContextBuilder, LocalWaker, Waker}; -/// use std::future::Future; -/// use std::pin::Pin; -/// use std::rc::Rc; -/// use std::cell::RefCell; -/// use std::collections::VecDeque; -/// -/// -/// thread_local! { -/// // A queue containing all tasks ready to do progress -/// static RUN_QUEUE: RefCell>> = RefCell::default(); -/// } -/// -/// type BoxedFuture = Pin>>; -/// -/// struct Task(RefCell); -/// -/// impl LocalWake for Task { -/// fn wake(self: Rc) { -/// RUN_QUEUE.with_borrow_mut(|queue| { -/// queue.push_back(self) -/// }) -/// } -/// } -/// -/// fn spawn(future: F) -/// where -/// F: Future + 'static + Send + Sync -/// { -/// let task = RefCell::new(Box::pin(future)); -/// RUN_QUEUE.with_borrow_mut(|queue| { -/// queue.push_back(Rc::new(Task(task))); -/// }); -/// } -/// -/// fn block_on(future: F) -/// where -/// F: Future + 'static + Sync + Send -/// { -/// spawn(future); -/// loop { -/// let Some(task) = RUN_QUEUE.with_borrow_mut(|queue| queue.pop_front()) else { -/// // we exit, since there are no more tasks remaining on the queue -/// return; -/// }; -/// -/// // cast the Rc into a `LocalWaker` -/// let local_waker: LocalWaker = task.clone().into(); -/// // Build the context using `ContextBuilder` -/// let mut cx = ContextBuilder::from_waker(Waker::noop()) -/// .local_waker(&local_waker) -/// .build(); -/// -/// // Poll the task -/// let _ = task.0 -/// .borrow_mut() -/// .as_mut() -/// .poll(&mut cx); -/// } -/// } -/// -/// block_on(async { -/// println!("hello world"); -/// }); -/// ``` -/// -#[unstable(feature = "local_waker", issue = "118959")] -pub trait LocalWake { - /// Wake this task. - #[unstable(feature = "local_waker", issue = "118959")] - fn wake(self: Rc); - - /// Wake this task without consuming the local waker. - /// - /// If an executor supports a cheaper way to wake without consuming the - /// waker, it should override this method. By default, it clones the - /// [`Rc`] and calls [`wake`] on the clone. - /// - /// [`wake`]: LocalWaker::wake - #[unstable(feature = "local_waker", issue = "118959")] - fn wake_by_ref(self: &Rc) { - self.clone().wake(); - } -} - -#[unstable(feature = "local_waker", issue = "118959")] -impl From> for LocalWaker { - /// Use a `Wake`-able type as a `LocalWaker`. - /// - /// No heap allocations or atomic operations are used for this conversion. - fn from(waker: Rc) -> LocalWaker { - // SAFETY: This is safe because raw_waker safely constructs - // a RawWaker from Rc. - unsafe { LocalWaker::from_raw(local_raw_waker(waker)) } - } -} -#[allow(ineffective_unstable_trait_impl)] -#[unstable(feature = "local_waker", issue = "118959")] -impl From> for RawWaker { - /// Use a `Wake`-able type as a `RawWaker`. - /// - /// No heap allocations or atomic operations are used for this conversion. - fn from(waker: Rc) -> RawWaker { - local_raw_waker(waker) - } -} - -// NB: This private function for constructing a RawWaker is used, rather than -// inlining this into the `From> for RawWaker` impl, to ensure that -// the safety of `From> for Waker` does not depend on the correct -// trait dispatch - instead both impls call this function directly and -// explicitly. -#[inline(always)] -fn local_raw_waker(waker: Rc) -> RawWaker { - // Increment the reference count of the Rc to clone it. - // - // Refer to the comment on raw_waker's clone_waker regarding why this is - // always inline. - #[inline(always)] - unsafe fn clone_waker(waker: *const ()) -> RawWaker { - unsafe { Rc::increment_strong_count(waker as *const W) }; - RawWaker::new( - waker, - &RawWakerVTable::new(clone_waker::, wake::, wake_by_ref::, drop_waker::), - ) - } - - // Wake by value, moving the Rc into the LocalWake::wake function - unsafe fn wake(waker: *const ()) { - let waker = unsafe { Rc::from_raw(waker as *const W) }; - ::wake(waker); - } - - // Wake by reference, wrap the waker in ManuallyDrop to avoid dropping it - unsafe fn wake_by_ref(waker: *const ()) { - let waker = unsafe { ManuallyDrop::new(Rc::from_raw(waker as *const W)) }; - ::wake_by_ref(&waker); - } - - // Decrement the reference count of the Rc on drop - unsafe fn drop_waker(waker: *const ()) { - unsafe { Rc::decrement_strong_count(waker as *const W) }; - } - - RawWaker::new( - Rc::into_raw(waker) as *const (), - &RawWakerVTable::new(clone_waker::, wake::, wake_by_ref::, drop_waker::), - ) -} diff --git a/library/alloc/src/testing/crash_test.rs b/library/alloc/src/testing/crash_test.rs deleted file mode 100644 index bcf5f5f72510e..0000000000000 --- a/library/alloc/src/testing/crash_test.rs +++ /dev/null @@ -1,119 +0,0 @@ -// We avoid relying on anything else in the crate, apart from the `Debug` trait. -use crate::fmt::Debug; -use std::cmp::Ordering; -use std::sync::atomic::{AtomicUsize, Ordering::SeqCst}; - -/// A blueprint for crash test dummy instances that monitor particular events. -/// Some instances may be configured to panic at some point. -/// Events are `clone`, `drop` or some anonymous `query`. -/// -/// Crash test dummies are identified and ordered by an id, so they can be used -/// as keys in a BTreeMap. -#[derive(Debug)] -pub struct CrashTestDummy { - pub id: usize, - cloned: AtomicUsize, - dropped: AtomicUsize, - queried: AtomicUsize, -} - -impl CrashTestDummy { - /// Creates a crash test dummy design. The `id` determines order and equality of instances. - pub fn new(id: usize) -> CrashTestDummy { - CrashTestDummy { - id, - cloned: AtomicUsize::new(0), - dropped: AtomicUsize::new(0), - queried: AtomicUsize::new(0), - } - } - - /// Creates an instance of a crash test dummy that records what events it experiences - /// and optionally panics. - pub fn spawn(&self, panic: Panic) -> Instance<'_> { - Instance { origin: self, panic } - } - - /// Returns how many times instances of the dummy have been cloned. - pub fn cloned(&self) -> usize { - self.cloned.load(SeqCst) - } - - /// Returns how many times instances of the dummy have been dropped. - pub fn dropped(&self) -> usize { - self.dropped.load(SeqCst) - } - - /// Returns how many times instances of the dummy have had their `query` member invoked. - pub fn queried(&self) -> usize { - self.queried.load(SeqCst) - } -} - -#[derive(Debug)] -pub struct Instance<'a> { - origin: &'a CrashTestDummy, - panic: Panic, -} - -#[derive(Copy, Clone, Debug, PartialEq, Eq)] -pub enum Panic { - Never, - InClone, - InDrop, - InQuery, -} - -impl Instance<'_> { - pub fn id(&self) -> usize { - self.origin.id - } - - /// Some anonymous query, the result of which is already given. - pub fn query(&self, result: R) -> R { - self.origin.queried.fetch_add(1, SeqCst); - if self.panic == Panic::InQuery { - panic!("panic in `query`"); - } - result - } -} - -impl Clone for Instance<'_> { - fn clone(&self) -> Self { - self.origin.cloned.fetch_add(1, SeqCst); - if self.panic == Panic::InClone { - panic!("panic in `clone`"); - } - Self { origin: self.origin, panic: Panic::Never } - } -} - -impl Drop for Instance<'_> { - fn drop(&mut self) { - self.origin.dropped.fetch_add(1, SeqCst); - if self.panic == Panic::InDrop { - panic!("panic in `drop`"); - } - } -} - -impl PartialOrd for Instance<'_> { - fn partial_cmp(&self, other: &Self) -> Option { - self.id().partial_cmp(&other.id()) - } -} - -impl Ord for Instance<'_> { - fn cmp(&self, other: &Self) -> Ordering { - self.id().cmp(&other.id()) - } -} - -impl PartialEq for Instance<'_> { - fn eq(&self, other: &Self) -> bool { - self.id().eq(&other.id()) - } -} - -impl Eq for Instance<'_> {} diff --git a/library/alloc/src/testing/mod.rs b/library/alloc/src/testing/mod.rs deleted file mode 100644 index 7a094f8a59522..0000000000000 --- a/library/alloc/src/testing/mod.rs +++ /dev/null @@ -1,3 +0,0 @@ -pub mod crash_test; -pub mod ord_chaos; -pub mod rng; diff --git a/library/alloc/src/testing/ord_chaos.rs b/library/alloc/src/testing/ord_chaos.rs deleted file mode 100644 index 96ce7c1579046..0000000000000 --- a/library/alloc/src/testing/ord_chaos.rs +++ /dev/null @@ -1,81 +0,0 @@ -use std::cell::Cell; -use std::cmp::Ordering::{self, *}; -use std::ptr; - -// Minimal type with an `Ord` implementation violating transitivity. -#[derive(Debug)] -pub enum Cyclic3 { - A, - B, - C, -} -use Cyclic3::*; - -impl PartialOrd for Cyclic3 { - fn partial_cmp(&self, other: &Self) -> Option { - Some(self.cmp(other)) - } -} - -impl Ord for Cyclic3 { - fn cmp(&self, other: &Self) -> Ordering { - match (self, other) { - (A, A) | (B, B) | (C, C) => Equal, - (A, B) | (B, C) | (C, A) => Less, - (A, C) | (B, A) | (C, B) => Greater, - } - } -} - -impl PartialEq for Cyclic3 { - fn eq(&self, other: &Self) -> bool { - self.cmp(&other) == Equal - } -} - -impl Eq for Cyclic3 {} - -// Controls the ordering of values wrapped by `Governed`. -#[derive(Debug)] -pub struct Governor { - flipped: Cell, -} - -impl Governor { - pub fn new() -> Self { - Governor { flipped: Cell::new(false) } - } - - pub fn flip(&self) { - self.flipped.set(!self.flipped.get()); - } -} - -// Type with an `Ord` implementation that forms a total order at any moment -// (assuming that `T` respects total order), but can suddenly be made to invert -// that total order. -#[derive(Debug)] -pub struct Governed<'a, T>(pub T, pub &'a Governor); - -impl PartialOrd for Governed<'_, T> { - fn partial_cmp(&self, other: &Self) -> Option { - Some(self.cmp(other)) - } -} - -impl Ord for Governed<'_, T> { - fn cmp(&self, other: &Self) -> Ordering { - assert!(ptr::eq(self.1, other.1)); - let ord = self.0.cmp(&other.0); - if self.1.flipped.get() { ord.reverse() } else { ord } - } -} - -impl PartialEq for Governed<'_, T> { - fn eq(&self, other: &Self) -> bool { - assert!(ptr::eq(self.1, other.1)); - self.0.eq(&other.0) - } -} - -impl Eq for Governed<'_, T> {} diff --git a/library/alloc/src/testing/rng.rs b/library/alloc/src/testing/rng.rs deleted file mode 100644 index ecf543bee035a..0000000000000 --- a/library/alloc/src/testing/rng.rs +++ /dev/null @@ -1,28 +0,0 @@ -/// XorShiftRng -pub struct DeterministicRng { - count: usize, - x: u32, - y: u32, - z: u32, - w: u32, -} - -impl DeterministicRng { - pub fn new() -> Self { - DeterministicRng { count: 0, x: 0x193a6754, y: 0xa8a7d469, z: 0x97830e05, w: 0x113ba7bb } - } - - /// Guarantees that each returned number is unique. - pub fn next(&mut self) -> u32 { - self.count += 1; - assert!(self.count <= 70029); - let x = self.x; - let t = x ^ (x << 11); - self.x = self.y; - self.y = self.z; - self.z = self.w; - let w_ = self.w; - self.w = w_ ^ (w_ >> 19) ^ (t ^ (t >> 8)); - self.w - } -} diff --git a/library/alloc/src/tests.rs b/library/alloc/src/tests.rs deleted file mode 100644 index ab256ceaec353..0000000000000 --- a/library/alloc/src/tests.rs +++ /dev/null @@ -1,141 +0,0 @@ -//! Test for `boxed` mod. - -use core::any::Any; -use core::ops::Deref; - -use std::boxed::Box; - -#[test] -fn test_owned_clone() { - let a = Box::new(5); - let b: Box = a.clone(); - assert!(a == b); -} - -#[derive(Debug, PartialEq, Eq)] -struct Test; - -#[test] -fn any_move() { - let a = Box::new(8) as Box; - let b = Box::new(Test) as Box; - - let a: Box = a.downcast::().unwrap(); - assert_eq!(*a, 8); - - let b: Box = b.downcast::().unwrap(); - assert_eq!(*b, Test); - - let a = Box::new(8) as Box; - let b = Box::new(Test) as Box; - - assert!(a.downcast::>().is_err()); - assert!(b.downcast::>().is_err()); -} - -#[test] -fn test_show() { - let a = Box::new(8) as Box; - let b = Box::new(Test) as Box; - let a_str = format!("{a:?}"); - let b_str = format!("{b:?}"); - assert_eq!(a_str, "Any { .. }"); - assert_eq!(b_str, "Any { .. }"); - - static EIGHT: usize = 8; - static TEST: Test = Test; - let a = &EIGHT as &dyn Any; - let b = &TEST as &dyn Any; - let s = format!("{a:?}"); - assert_eq!(s, "Any { .. }"); - let s = format!("{b:?}"); - assert_eq!(s, "Any { .. }"); -} - -#[test] -fn deref() { - fn homura>(_: T) {} - homura(Box::new(765)); -} - -#[test] -fn raw_sized() { - let x = Box::new(17); - let p = Box::into_raw(x); - unsafe { - assert_eq!(17, *p); - *p = 19; - let y = Box::from_raw(p); - assert_eq!(19, *y); - } -} - -#[test] -fn raw_trait() { - trait Foo { - fn get(&self) -> u32; - fn set(&mut self, value: u32); - } - - struct Bar(u32); - - impl Foo for Bar { - fn get(&self) -> u32 { - self.0 - } - - fn set(&mut self, value: u32) { - self.0 = value; - } - } - - let x: Box = Box::new(Bar(17)); - let p = Box::into_raw(x); - unsafe { - assert_eq!(17, (*p).get()); - (*p).set(19); - let y: Box = Box::from_raw(p); - assert_eq!(19, y.get()); - } -} - -#[test] -fn f64_slice() { - let slice: &[f64] = &[-1.0, 0.0, 1.0, f64::INFINITY]; - let boxed: Box<[f64]> = Box::from(slice); - assert_eq!(&*boxed, slice) -} - -#[test] -fn i64_slice() { - let slice: &[i64] = &[i64::MIN, -2, -1, 0, 1, 2, i64::MAX]; - let boxed: Box<[i64]> = Box::from(slice); - assert_eq!(&*boxed, slice) -} - -#[test] -fn str_slice() { - let s = "Hello, world!"; - let boxed: Box = Box::from(s); - assert_eq!(&*boxed, s) -} - -#[test] -fn boxed_slice_from_iter() { - let iter = 0..100; - let boxed: Box<[u32]> = iter.collect(); - assert_eq!(boxed.len(), 100); - assert_eq!(boxed[7], 7); -} - -#[test] -fn test_array_from_slice() { - let v = vec![1, 2, 3]; - let r: Box<[u32]> = v.into_boxed_slice(); - - let a: Result, _> = r.clone().try_into(); - assert!(a.is_ok()); - - let a: Result, _> = r.clone().try_into(); - assert!(a.is_err()); -} diff --git a/library/alloc/src/vec/cow.rs b/library/alloc/src/vec/cow.rs deleted file mode 100644 index 3fe83242a30ad..0000000000000 --- a/library/alloc/src/vec/cow.rs +++ /dev/null @@ -1,65 +0,0 @@ -use crate::borrow::Cow; - -use super::Vec; - -#[stable(feature = "cow_from_vec", since = "1.8.0")] -impl<'a, T: Clone> From<&'a [T]> for Cow<'a, [T]> { - /// Creates a [`Borrowed`] variant of [`Cow`] - /// from a slice. - /// - /// This conversion does not allocate or clone the data. - /// - /// [`Borrowed`]: crate::borrow::Cow::Borrowed - fn from(s: &'a [T]) -> Cow<'a, [T]> { - Cow::Borrowed(s) - } -} - -#[stable(feature = "cow_from_array_ref", since = "1.77.0")] -impl<'a, T: Clone, const N: usize> From<&'a [T; N]> for Cow<'a, [T]> { - /// Creates a [`Borrowed`] variant of [`Cow`] - /// from a reference to an array. - /// - /// This conversion does not allocate or clone the data. - /// - /// [`Borrowed`]: crate::borrow::Cow::Borrowed - fn from(s: &'a [T; N]) -> Cow<'a, [T]> { - Cow::Borrowed(s as &[_]) - } -} - -#[stable(feature = "cow_from_vec", since = "1.8.0")] -impl<'a, T: Clone> From> for Cow<'a, [T]> { - /// Creates an [`Owned`] variant of [`Cow`] - /// from an owned instance of [`Vec`]. - /// - /// This conversion does not allocate or clone the data. - /// - /// [`Owned`]: crate::borrow::Cow::Owned - fn from(v: Vec) -> Cow<'a, [T]> { - Cow::Owned(v) - } -} - -#[stable(feature = "cow_from_vec_ref", since = "1.28.0")] -impl<'a, T: Clone> From<&'a Vec> for Cow<'a, [T]> { - /// Creates a [`Borrowed`] variant of [`Cow`] - /// from a reference to [`Vec`]. - /// - /// This conversion does not allocate or clone the data. - /// - /// [`Borrowed`]: crate::borrow::Cow::Borrowed - fn from(v: &'a Vec) -> Cow<'a, [T]> { - Cow::Borrowed(v.as_slice()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T> FromIterator for Cow<'a, [T]> -where - T: Clone, -{ - fn from_iter>(it: I) -> Cow<'a, [T]> { - Cow::Owned(FromIterator::from_iter(it)) - } -} diff --git a/library/alloc/src/vec/drain.rs b/library/alloc/src/vec/drain.rs deleted file mode 100644 index f0b63759ac70f..0000000000000 --- a/library/alloc/src/vec/drain.rs +++ /dev/null @@ -1,253 +0,0 @@ -use crate::alloc::{Allocator, Global}; -use core::fmt; -use core::iter::{FusedIterator, TrustedLen}; -use core::mem::{self, ManuallyDrop, SizedTypeProperties}; -use core::ptr::{self, NonNull}; -use core::slice::{self}; - -use super::Vec; - -/// A draining iterator for `Vec`. -/// -/// This `struct` is created by [`Vec::drain`]. -/// See its documentation for more. -/// -/// # Example -/// -/// ``` -/// let mut v = vec![0, 1, 2]; -/// let iter: std::vec::Drain<'_, _> = v.drain(..); -/// ``` -#[stable(feature = "drain", since = "1.6.0")] -pub struct Drain< - 'a, - T: 'a, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator + 'a = Global, -> { - /// Index of tail to preserve - pub(super) tail_start: usize, - /// Length of tail - pub(super) tail_len: usize, - /// Current remaining range to remove - pub(super) iter: slice::Iter<'a, T>, - pub(super) vec: NonNull>, -} - -#[stable(feature = "collection_debug", since = "1.17.0")] -impl fmt::Debug for Drain<'_, T, A> { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("Drain").field(&self.iter.as_slice()).finish() - } -} - -impl<'a, T, A: Allocator> Drain<'a, T, A> { - /// Returns the remaining items of this iterator as a slice. - /// - /// # Examples - /// - /// ``` - /// let mut vec = vec!['a', 'b', 'c']; - /// let mut drain = vec.drain(..); - /// assert_eq!(drain.as_slice(), &['a', 'b', 'c']); - /// let _ = drain.next().unwrap(); - /// assert_eq!(drain.as_slice(), &['b', 'c']); - /// ``` - #[must_use] - #[stable(feature = "vec_drain_as_slice", since = "1.46.0")] - pub fn as_slice(&self) -> &[T] { - self.iter.as_slice() - } - - /// Returns a reference to the underlying allocator. - #[unstable(feature = "allocator_api", issue = "32838")] - #[must_use] - #[inline] - pub fn allocator(&self) -> &A { - unsafe { self.vec.as_ref().allocator() } - } - - /// Keep unyielded elements in the source `Vec`. - /// - /// # Examples - /// - /// ``` - /// #![feature(drain_keep_rest)] - /// - /// let mut vec = vec!['a', 'b', 'c']; - /// let mut drain = vec.drain(..); - /// - /// assert_eq!(drain.next().unwrap(), 'a'); - /// - /// // This call keeps 'b' and 'c' in the vec. - /// drain.keep_rest(); - /// - /// // If we wouldn't call `keep_rest()`, - /// // `vec` would be empty. - /// assert_eq!(vec, ['b', 'c']); - /// ``` - #[unstable(feature = "drain_keep_rest", issue = "101122")] - pub fn keep_rest(self) { - // At this moment layout looks like this: - // - // [head] [yielded by next] [unyielded] [yielded by next_back] [tail] - // ^-- start \_________/-- unyielded_len \____/-- self.tail_len - // ^-- unyielded_ptr ^-- tail - // - // Normally `Drop` impl would drop [unyielded] and then move [tail] to the `start`. - // Here we want to - // 1. Move [unyielded] to `start` - // 2. Move [tail] to a new start at `start + len(unyielded)` - // 3. Update length of the original vec to `len(head) + len(unyielded) + len(tail)` - // a. In case of ZST, this is the only thing we want to do - // 4. Do *not* drop self, as everything is put in a consistent state already, there is nothing to do - let mut this = ManuallyDrop::new(self); - - unsafe { - let source_vec = this.vec.as_mut(); - - let start = source_vec.len(); - let tail = this.tail_start; - - let unyielded_len = this.iter.len(); - let unyielded_ptr = this.iter.as_slice().as_ptr(); - - // ZSTs have no identity, so we don't need to move them around. - if !T::IS_ZST { - let start_ptr = source_vec.as_mut_ptr().add(start); - - // memmove back unyielded elements - if unyielded_ptr != start_ptr { - let src = unyielded_ptr; - let dst = start_ptr; - - ptr::copy(src, dst, unyielded_len); - } - - // memmove back untouched tail - if tail != (start + unyielded_len) { - let src = source_vec.as_ptr().add(tail); - let dst = start_ptr.add(unyielded_len); - ptr::copy(src, dst, this.tail_len); - } - } - - source_vec.set_len(start + unyielded_len + this.tail_len); - } - } -} - -#[stable(feature = "vec_drain_as_slice", since = "1.46.0")] -impl<'a, T, A: Allocator> AsRef<[T]> for Drain<'a, T, A> { - fn as_ref(&self) -> &[T] { - self.as_slice() - } -} - -#[stable(feature = "drain", since = "1.6.0")] -unsafe impl Sync for Drain<'_, T, A> {} -#[stable(feature = "drain", since = "1.6.0")] -unsafe impl Send for Drain<'_, T, A> {} - -#[stable(feature = "drain", since = "1.6.0")] -impl Iterator for Drain<'_, T, A> { - type Item = T; - - #[inline] - fn next(&mut self) -> Option { - self.iter.next().map(|elt| unsafe { ptr::read(elt as *const _) }) - } - - fn size_hint(&self) -> (usize, Option) { - self.iter.size_hint() - } -} - -#[stable(feature = "drain", since = "1.6.0")] -impl DoubleEndedIterator for Drain<'_, T, A> { - #[inline] - fn next_back(&mut self) -> Option { - self.iter.next_back().map(|elt| unsafe { ptr::read(elt as *const _) }) - } -} - -#[stable(feature = "drain", since = "1.6.0")] -impl Drop for Drain<'_, T, A> { - fn drop(&mut self) { - /// Moves back the un-`Drain`ed elements to restore the original `Vec`. - struct DropGuard<'r, 'a, T, A: Allocator>(&'r mut Drain<'a, T, A>); - - impl<'r, 'a, T, A: Allocator> Drop for DropGuard<'r, 'a, T, A> { - fn drop(&mut self) { - if self.0.tail_len > 0 { - unsafe { - let source_vec = self.0.vec.as_mut(); - // memmove back untouched tail, update to new length - let start = source_vec.len(); - let tail = self.0.tail_start; - if tail != start { - let src = source_vec.as_ptr().add(tail); - let dst = source_vec.as_mut_ptr().add(start); - ptr::copy(src, dst, self.0.tail_len); - } - source_vec.set_len(start + self.0.tail_len); - } - } - } - } - - let iter = mem::take(&mut self.iter); - let drop_len = iter.len(); - - let mut vec = self.vec; - - if T::IS_ZST { - // ZSTs have no identity, so we don't need to move them around, we only need to drop the correct amount. - // this can be achieved by manipulating the Vec length instead of moving values out from `iter`. - unsafe { - let vec = vec.as_mut(); - let old_len = vec.len(); - vec.set_len(old_len + drop_len + self.tail_len); - vec.truncate(old_len + self.tail_len); - } - - return; - } - - // ensure elements are moved back into their appropriate places, even when drop_in_place panics - let _guard = DropGuard(self); - - if drop_len == 0 { - return; - } - - // as_slice() must only be called when iter.len() is > 0 because - // it also gets touched by vec::Splice which may turn it into a dangling pointer - // which would make it and the vec pointer point to different allocations which would - // lead to invalid pointer arithmetic below. - let drop_ptr = iter.as_slice().as_ptr(); - - unsafe { - // drop_ptr comes from a slice::Iter which only gives us a &[T] but for drop_in_place - // a pointer with mutable provenance is necessary. Therefore we must reconstruct - // it from the original vec but also avoid creating a &mut to the front since that could - // invalidate raw pointers to it which some unsafe code might rely on. - let vec_ptr = vec.as_mut().as_mut_ptr(); - let drop_offset = drop_ptr.sub_ptr(vec_ptr); - let to_drop = ptr::slice_from_raw_parts_mut(vec_ptr.add(drop_offset), drop_len); - ptr::drop_in_place(to_drop); - } - } -} - -#[stable(feature = "drain", since = "1.6.0")] -impl ExactSizeIterator for Drain<'_, T, A> { - fn is_empty(&self) -> bool { - self.iter.is_empty() - } -} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for Drain<'_, T, A> {} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for Drain<'_, T, A> {} diff --git a/library/alloc/src/vec/extract_if.rs b/library/alloc/src/vec/extract_if.rs deleted file mode 100644 index 118cfdb36b9c2..0000000000000 --- a/library/alloc/src/vec/extract_if.rs +++ /dev/null @@ -1,113 +0,0 @@ -use crate::alloc::{Allocator, Global}; -use core::ptr; -use core::slice; - -use super::Vec; - -/// An iterator which uses a closure to determine if an element should be removed. -/// -/// This struct is created by [`Vec::extract_if`]. -/// See its documentation for more. -/// -/// # Example -/// -/// ``` -/// #![feature(extract_if)] -/// -/// let mut v = vec![0, 1, 2]; -/// let iter: std::vec::ExtractIf<'_, _, _> = v.extract_if(|x| *x % 2 == 0); -/// ``` -#[unstable(feature = "extract_if", reason = "recently added", issue = "43244")] -#[derive(Debug)] -#[must_use = "iterators are lazy and do nothing unless consumed"] -pub struct ExtractIf< - 'a, - T, - F, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, -> where - F: FnMut(&mut T) -> bool, -{ - pub(super) vec: &'a mut Vec, - /// The index of the item that will be inspected by the next call to `next`. - pub(super) idx: usize, - /// The number of items that have been drained (removed) thus far. - pub(super) del: usize, - /// The original length of `vec` prior to draining. - pub(super) old_len: usize, - /// The filter test predicate. - pub(super) pred: F, -} - -impl ExtractIf<'_, T, F, A> -where - F: FnMut(&mut T) -> bool, -{ - /// Returns a reference to the underlying allocator. - #[unstable(feature = "allocator_api", issue = "32838")] - #[inline] - pub fn allocator(&self) -> &A { - self.vec.allocator() - } -} - -#[unstable(feature = "extract_if", reason = "recently added", issue = "43244")] -impl Iterator for ExtractIf<'_, T, F, A> -where - F: FnMut(&mut T) -> bool, -{ - type Item = T; - - fn next(&mut self) -> Option { - unsafe { - while self.idx < self.old_len { - let i = self.idx; - let v = slice::from_raw_parts_mut(self.vec.as_mut_ptr(), self.old_len); - let drained = (self.pred)(&mut v[i]); - // Update the index *after* the predicate is called. If the index - // is updated prior and the predicate panics, the element at this - // index would be leaked. - self.idx += 1; - if drained { - self.del += 1; - return Some(ptr::read(&v[i])); - } else if self.del > 0 { - let del = self.del; - let src: *const T = &v[i]; - let dst: *mut T = &mut v[i - del]; - ptr::copy_nonoverlapping(src, dst, 1); - } - } - None - } - } - - fn size_hint(&self) -> (usize, Option) { - (0, Some(self.old_len - self.idx)) - } -} - -#[unstable(feature = "extract_if", reason = "recently added", issue = "43244")] -impl Drop for ExtractIf<'_, T, F, A> -where - F: FnMut(&mut T) -> bool, -{ - fn drop(&mut self) { - unsafe { - if self.idx < self.old_len && self.del > 0 { - // This is a pretty messed up state, and there isn't really an - // obviously right thing to do. We don't want to keep trying - // to execute `pred`, so we just backshift all the unprocessed - // elements and tell the vec that they still exist. The backshift - // is required to prevent a double-drop of the last successfully - // drained item prior to a panic in the predicate. - let ptr = self.vec.as_mut_ptr(); - let src = ptr.add(self.idx); - let dst = src.sub(self.del); - let tail_len = self.old_len - self.idx; - src.copy_to(dst, tail_len); - } - self.vec.set_len(self.old_len - self.del); - } - } -} diff --git a/library/alloc/src/vec/in_place_collect.rs b/library/alloc/src/vec/in_place_collect.rs deleted file mode 100644 index 22541a2b9d82f..0000000000000 --- a/library/alloc/src/vec/in_place_collect.rs +++ /dev/null @@ -1,429 +0,0 @@ -//! Inplace iterate-and-collect specialization for `Vec` -//! -//! Note: This documents Vec internals, some of the following sections explain implementation -//! details and are best read together with the source of this module. -//! -//! The specialization in this module applies to iterators in the shape of -//! `source.adapter().adapter().adapter().collect::>()` -//! where `source` is an owning iterator obtained from [`Vec`], [`Box<[T]>`][box] (by conversion to `Vec`) -//! or [`BinaryHeap`], the adapters guarantee to consume enough items per step to make room -//! for the results (represented by [`InPlaceIterable`]), provide transitive access to `source` -//! (via [`SourceIter`]) and thus the underlying allocation. -//! And finally there are alignment and size constraints to consider, this is currently ensured via -//! const eval instead of trait bounds in the specialized [`SpecFromIter`] implementation. -//! -//! [`BinaryHeap`]: crate::collections::BinaryHeap -//! [box]: crate::boxed::Box -//! -//! By extension some other collections which use `collect::>()` internally in their -//! `FromIterator` implementation benefit from this too. -//! -//! Access to the underlying source goes through a further layer of indirection via the private -//! trait [`AsVecIntoIter`] to hide the implementation detail that other collections may use -//! `vec::IntoIter` internally. -//! -//! In-place iteration depends on the interaction of several unsafe traits, implementation -//! details of multiple parts in the iterator pipeline and often requires holistic reasoning -//! across multiple structs since iterators are executed cooperatively rather than having -//! a central evaluator/visitor struct executing all iterator components. -//! -//! # Reading from and writing to the same allocation -//! -//! By its nature collecting in place means that the reader and writer side of the iterator -//! use the same allocation. Since `try_fold()` (used in [`SpecInPlaceCollect`]) takes a -//! reference to the iterator for the duration of the iteration that means we can't interleave -//! the step of reading a value and getting a reference to write to. Instead raw pointers must be -//! used on the reader and writer side. -//! -//! That writes never clobber a yet-to-be-read items is ensured by the [`InPlaceIterable`] requirements. -//! -//! # Layout constraints -//! -//! When recycling an allocation between different types we must uphold the [`Allocator`] contract -//! which means that the input and output Layouts have to "fit". -//! -//! To complicate things further `InPlaceIterable` supports splitting or merging items into smaller/ -//! larger ones to enable (de)aggregation of arrays. -//! -//! Ultimately each step of the iterator must free up enough *bytes* in the source to make room -//! for the next output item. -//! If `T` and `U` have the same size no fixup is needed. -//! If `T`'s size is a multiple of `U`'s we can compensate by multiplying the capacity accordingly. -//! Otherwise the input capacity (and thus layout) in bytes may not be representable by the output -//! `Vec`. In that case `alloc.shrink()` is used to update the allocation's layout. -//! -//! Alignments of `T` must be the same or larger than `U`. Since alignments are always a power -//! of two _larger_ implies _is a multiple of_. -//! -//! See `in_place_collectible()` for the current conditions. -//! -//! Additionally this specialization doesn't make sense for ZSTs as there is no reallocation to -//! avoid and it would make pointer arithmetic more difficult. -//! -//! [`Allocator`]: core::alloc::Allocator -//! -//! # Drop- and panic-safety -//! -//! Iteration can panic, requiring dropping the already written parts but also the remainder of -//! the source. Iteration can also leave some source items unconsumed which must be dropped. -//! All those drops in turn can panic which then must either leak the allocation or abort to avoid -//! double-drops. -//! -//! This is handled by the [`InPlaceDrop`] guard for sink items (`U`) and by -//! [`vec::IntoIter::forget_allocation_drop_remaining()`] for remaining source items (`T`). -//! -//! If dropping any remaining source item (`T`) panics then [`InPlaceDstDataSrcBufDrop`] will handle dropping -//! the already collected sink items (`U`) and freeing the allocation. -//! -//! [`vec::IntoIter::forget_allocation_drop_remaining()`]: super::IntoIter::forget_allocation_drop_remaining() -//! -//! # O(1) collect -//! -//! The main iteration itself is further specialized when the iterator implements -//! [`TrustedRandomAccessNoCoerce`] to let the optimizer see that it is a counted loop with a single -//! [induction variable]. This can turn some iterators into a noop, i.e. it reduces them from O(n) to -//! O(1). This particular optimization is quite fickle and doesn't always work, see [#79308] -//! -//! [#79308]: https://github.com/rust-lang/rust/issues/79308 -//! [induction variable]: https://en.wikipedia.org/wiki/Induction_variable -//! -//! Since unchecked accesses through that trait do not advance the read pointer of `IntoIter` -//! this would interact unsoundly with the requirements about dropping the tail described above. -//! But since the normal `Drop` implementation of `IntoIter` would suffer from the same problem it -//! is only correct for `TrustedRandomAccessNoCoerce` to be implemented when the items don't -//! have a destructor. Thus that implicit requirement also makes the specialization safe to use for -//! in-place collection. -//! Note that this safety concern is about the correctness of `impl Drop for IntoIter`, -//! not the guarantees of `InPlaceIterable`. -//! -//! # Adapter implementations -//! -//! The invariants for adapters are documented in [`SourceIter`] and [`InPlaceIterable`], but -//! getting them right can be rather subtle for multiple, sometimes non-local reasons. -//! For example `InPlaceIterable` would be valid to implement for [`Peekable`], except -//! that it is stateful, cloneable and `IntoIter`'s clone implementation shortens the underlying -//! allocation which means if the iterator has been peeked and then gets cloned there no longer is -//! enough room, thus breaking an invariant ([#85322]). -//! -//! [#85322]: https://github.com/rust-lang/rust/issues/85322 -//! [`Peekable`]: core::iter::Peekable -//! -//! -//! # Examples -//! -//! Some cases that are optimized by this specialization, more can be found in the `Vec` -//! benchmarks: -//! -//! ```rust -//! # #[allow(dead_code)] -//! /// Converts a usize vec into an isize one. -//! pub fn cast(vec: Vec) -> Vec { -//! // Does not allocate, free or panic. On optlevel>=2 it does not loop. -//! // Of course this particular case could and should be written with `into_raw_parts` and -//! // `from_raw_parts` instead. -//! vec.into_iter().map(|u| u as isize).collect() -//! } -//! ``` -//! -//! ```rust -//! # #[allow(dead_code)] -//! /// Drops remaining items in `src` and if the layouts of `T` and `U` match it -//! /// returns an empty Vec backed by the original allocation. Otherwise it returns a new -//! /// empty vec. -//! pub fn recycle_allocation(src: Vec) -> Vec { -//! src.into_iter().filter_map(|_| None).collect() -//! } -//! ``` -//! -//! ```rust -//! let vec = vec![13usize; 1024]; -//! let _ = vec.into_iter() -//! .enumerate() -//! .filter_map(|(idx, val)| if idx % 2 == 0 { Some(val+idx) } else {None}) -//! .collect::>(); -//! -//! // is equivalent to the following, but doesn't require bounds checks -//! -//! let mut vec = vec![13usize; 1024]; -//! let mut write_idx = 0; -//! for idx in 0..vec.len() { -//! if idx % 2 == 0 { -//! vec[write_idx] = vec[idx] + idx; -//! write_idx += 1; -//! } -//! } -//! vec.truncate(write_idx); -//! ``` -use crate::alloc::{handle_alloc_error, Global}; -use core::alloc::Allocator; -use core::alloc::Layout; -use core::iter::{InPlaceIterable, SourceIter, TrustedRandomAccessNoCoerce}; -use core::marker::PhantomData; -use core::mem::{self, ManuallyDrop, SizedTypeProperties}; -use core::num::NonZero; -use core::ptr; - -use super::{InPlaceDrop, InPlaceDstDataSrcBufDrop, SpecFromIter, SpecFromIterNested, Vec}; - -const fn in_place_collectible( - step_merge: Option>, - step_expand: Option>, -) -> bool { - // Require matching alignments because an alignment-changing realloc is inefficient on many - // system allocators and better implementations would require the unstable Allocator trait. - if const { SRC::IS_ZST || DEST::IS_ZST || mem::align_of::() != mem::align_of::() } { - return false; - } - - match (step_merge, step_expand) { - (Some(step_merge), Some(step_expand)) => { - // At least N merged source items -> at most M expanded destination items - // e.g. - // - 1 x [u8; 4] -> 4x u8, via flatten - // - 4 x u8 -> 1x [u8; 4], via array_chunks - mem::size_of::() * step_merge.get() >= mem::size_of::() * step_expand.get() - } - // Fall back to other from_iter impls if an overflow occurred in the step merge/expansion - // tracking. - _ => false, - } -} - -const fn needs_realloc(src_cap: usize, dst_cap: usize) -> bool { - if const { mem::align_of::() != mem::align_of::() } { - // FIXME: use unreachable! once that works in const - panic!("in_place_collectible() prevents this"); - } - - // If src type size is an integer multiple of the destination type size then - // the caller will have calculated a `dst_cap` that is an integer multiple of - // `src_cap` without remainder. - if const { - let src_sz = mem::size_of::(); - let dest_sz = mem::size_of::(); - dest_sz != 0 && src_sz % dest_sz == 0 - } { - return false; - } - - // type layouts don't guarantee a fit, so do a runtime check to see if - // the allocations happen to match - return src_cap > 0 && src_cap * mem::size_of::() != dst_cap * mem::size_of::(); -} - -/// This provides a shorthand for the source type since local type aliases aren't a thing. -#[rustc_specialization_trait] -trait InPlaceCollect: SourceIter + InPlaceIterable { - type Src; -} - -impl InPlaceCollect for T -where - T: SourceIter + InPlaceIterable, -{ - type Src = <::Source as AsVecIntoIter>::Item; -} - -impl SpecFromIter for Vec -where - I: Iterator + InPlaceCollect, - ::Source: AsVecIntoIter, -{ - default fn from_iter(iterator: I) -> Self { - // Select the implementation in const eval to avoid codegen of the dead branch to improve compile times. - let fun: fn(I) -> Vec = const { - // See "Layout constraints" section in the module documentation. We use const conditions here - // since these conditions currently cannot be expressed as trait bounds - if in_place_collectible::(I::MERGE_BY, I::EXPAND_BY) { - from_iter_in_place - } else { - // fallback - SpecFromIterNested::::from_iter - } - }; - - fun(iterator) - } -} - -fn from_iter_in_place(mut iterator: I) -> Vec -where - I: Iterator + InPlaceCollect, - ::Source: AsVecIntoIter, -{ - let (src_buf, src_ptr, src_cap, mut dst_buf, dst_end, dst_cap) = unsafe { - let inner = iterator.as_inner().as_into_iter(); - ( - inner.buf, - inner.ptr, - inner.cap, - inner.buf.cast::(), - inner.end as *const T, - // SAFETY: the multiplication can not overflow, since `inner.cap * size_of::()` is the size of the allocation. - inner.cap.unchecked_mul(mem::size_of::()) / mem::size_of::(), - ) - }; - - // SAFETY: `dst_buf` and `dst_end` are the start and end of the buffer. - let len = unsafe { - SpecInPlaceCollect::collect_in_place(&mut iterator, dst_buf.as_ptr() as *mut T, dst_end) - }; - - let src = unsafe { iterator.as_inner().as_into_iter() }; - // check if SourceIter contract was upheld - // caveat: if they weren't we might not even make it to this point - debug_assert_eq!(src_buf, src.buf); - // check InPlaceIterable contract. This is only possible if the iterator advanced the - // source pointer at all. If it uses unchecked access via TrustedRandomAccess - // then the source pointer will stay in its initial position and we can't use it as reference - if src.ptr != src_ptr { - debug_assert!( - unsafe { dst_buf.add(len).cast() } <= src.ptr, - "InPlaceIterable contract violation, write pointer advanced beyond read pointer" - ); - } - - // The ownership of the source allocation and the new `T` values is temporarily moved into `dst_guard`. - // This is safe because - // * `forget_allocation_drop_remaining` immediately forgets the allocation - // before any panic can occur in order to avoid any double free, and then proceeds to drop - // any remaining values at the tail of the source. - // * the shrink either panics without invalidating the allocation, aborts or - // succeeds. In the last case we disarm the guard. - // - // Note: This access to the source wouldn't be allowed by the TrustedRandomIteratorNoCoerce - // contract (used by SpecInPlaceCollect below). But see the "O(1) collect" section in the - // module documentation why this is ok anyway. - let dst_guard = - InPlaceDstDataSrcBufDrop { ptr: dst_buf, len, src_cap, src: PhantomData:: }; - src.forget_allocation_drop_remaining(); - - // Adjust the allocation if the source had a capacity in bytes that wasn't a multiple - // of the destination type size. - // Since the discrepancy should generally be small this should only result in some - // bookkeeping updates and no memmove. - if needs_realloc::(src_cap, dst_cap) { - let alloc = Global; - debug_assert_ne!(src_cap, 0); - debug_assert_ne!(dst_cap, 0); - unsafe { - // The old allocation exists, therefore it must have a valid layout. - let src_align = mem::align_of::(); - let src_size = mem::size_of::().unchecked_mul(src_cap); - let old_layout = Layout::from_size_align_unchecked(src_size, src_align); - - // The allocation must be equal or smaller for in-place iteration to be possible - // therefore the new layout must be ≤ the old one and therefore valid. - let dst_align = mem::align_of::(); - let dst_size = mem::size_of::().unchecked_mul(dst_cap); - let new_layout = Layout::from_size_align_unchecked(dst_size, dst_align); - - let result = alloc.shrink(dst_buf.cast(), old_layout, new_layout); - let Ok(reallocated) = result else { handle_alloc_error(new_layout) }; - dst_buf = reallocated.cast::(); - } - } else { - debug_assert_eq!(src_cap * mem::size_of::(), dst_cap * mem::size_of::()); - } - - mem::forget(dst_guard); - - let vec = unsafe { Vec::from_nonnull(dst_buf, len, dst_cap) }; - - vec -} - -fn write_in_place_with_drop( - src_end: *const T, -) -> impl FnMut(InPlaceDrop, T) -> Result, !> { - move |mut sink, item| { - unsafe { - // the InPlaceIterable contract cannot be verified precisely here since - // try_fold has an exclusive reference to the source pointer - // all we can do is check if it's still in range - debug_assert!(sink.dst as *const _ <= src_end, "InPlaceIterable contract violation"); - ptr::write(sink.dst, item); - // Since this executes user code which can panic we have to bump the pointer - // after each step. - sink.dst = sink.dst.add(1); - } - Ok(sink) - } -} - -/// Helper trait to hold specialized implementations of the in-place iterate-collect loop -trait SpecInPlaceCollect: Iterator { - /// Collects an iterator (`self`) into the destination buffer (`dst`) and returns the number of items - /// collected. `end` is the last writable element of the allocation and used for bounds checks. - /// - /// This method is specialized and one of its implementations makes use of - /// `Iterator::__iterator_get_unchecked` calls with a `TrustedRandomAccessNoCoerce` bound - /// on `I` which means the caller of this method must take the safety conditions - /// of that trait into consideration. - unsafe fn collect_in_place(&mut self, dst: *mut T, end: *const T) -> usize; -} - -impl SpecInPlaceCollect for I -where - I: Iterator, -{ - #[inline] - default unsafe fn collect_in_place(&mut self, dst_buf: *mut T, end: *const T) -> usize { - // use try-fold since - // - it vectorizes better for some iterator adapters - // - unlike most internal iteration methods, it only takes a &mut self - // - it lets us thread the write pointer through its innards and get it back in the end - let sink = InPlaceDrop { inner: dst_buf, dst: dst_buf }; - let sink = - self.try_fold::<_, _, Result<_, !>>(sink, write_in_place_with_drop(end)).into_ok(); - // iteration succeeded, don't drop head - unsafe { ManuallyDrop::new(sink).dst.sub_ptr(dst_buf) } - } -} - -impl SpecInPlaceCollect for I -where - I: Iterator + TrustedRandomAccessNoCoerce, -{ - #[inline] - unsafe fn collect_in_place(&mut self, dst_buf: *mut T, end: *const T) -> usize { - let len = self.size(); - let mut drop_guard = InPlaceDrop { inner: dst_buf, dst: dst_buf }; - for i in 0..len { - // Safety: InplaceIterable contract guarantees that for every element we read - // one slot in the underlying storage will have been freed up and we can immediately - // write back the result. - unsafe { - let dst = dst_buf.add(i); - debug_assert!(dst as *const _ <= end, "InPlaceIterable contract violation"); - ptr::write(dst, self.__iterator_get_unchecked(i)); - // Since this executes user code which can panic we have to bump the pointer - // after each step. - drop_guard.dst = dst.add(1); - } - } - mem::forget(drop_guard); - len - } -} - -/// Internal helper trait for in-place iteration specialization. -/// -/// Currently this is only implemented by [`vec::IntoIter`] - returning a reference to itself - and -/// [`binary_heap::IntoIter`] which returns a reference to its inner representation. -/// -/// Since this is an internal trait it hides the implementation detail `binary_heap::IntoIter` -/// uses `vec::IntoIter` internally. -/// -/// [`vec::IntoIter`]: super::IntoIter -/// [`binary_heap::IntoIter`]: crate::collections::binary_heap::IntoIter -/// -/// # Safety -/// -/// In-place iteration relies on implementation details of `vec::IntoIter`, most importantly that -/// it does not create references to the whole allocation during iteration, only raw pointers -#[rustc_specialization_trait] -pub(crate) unsafe trait AsVecIntoIter { - type Item; - fn as_into_iter(&mut self) -> &mut super::IntoIter; -} diff --git a/library/alloc/src/vec/in_place_drop.rs b/library/alloc/src/vec/in_place_drop.rs deleted file mode 100644 index 4050c250130bb..0000000000000 --- a/library/alloc/src/vec/in_place_drop.rs +++ /dev/null @@ -1,50 +0,0 @@ -use core::marker::PhantomData; -use core::ptr::NonNull; -use core::ptr::{self, drop_in_place}; -use core::slice::{self}; - -use crate::alloc::Global; -use crate::raw_vec::RawVec; - -// A helper struct for in-place iteration that drops the destination slice of iteration, -// i.e. the head. The source slice (the tail) is dropped by IntoIter. -pub(super) struct InPlaceDrop { - pub(super) inner: *mut T, - pub(super) dst: *mut T, -} - -impl InPlaceDrop { - fn len(&self) -> usize { - unsafe { self.dst.sub_ptr(self.inner) } - } -} - -impl Drop for InPlaceDrop { - #[inline] - fn drop(&mut self) { - unsafe { - ptr::drop_in_place(slice::from_raw_parts_mut(self.inner, self.len())); - } - } -} - -// A helper struct for in-place collection that drops the destination items together with -// the source allocation - i.e. before the reallocation happened - to avoid leaking them -// if some other destructor panics. -pub(super) struct InPlaceDstDataSrcBufDrop { - pub(super) ptr: NonNull, - pub(super) len: usize, - pub(super) src_cap: usize, - pub(super) src: PhantomData, -} - -impl Drop for InPlaceDstDataSrcBufDrop { - #[inline] - fn drop(&mut self) { - unsafe { - let _drop_allocation = - RawVec::::from_nonnull_in(self.ptr.cast::(), self.src_cap, Global); - drop_in_place(core::ptr::slice_from_raw_parts_mut::(self.ptr.as_ptr(), self.len)); - }; - } -} diff --git a/library/alloc/src/vec/into_iter.rs b/library/alloc/src/vec/into_iter.rs deleted file mode 100644 index c47989337708f..0000000000000 --- a/library/alloc/src/vec/into_iter.rs +++ /dev/null @@ -1,531 +0,0 @@ -#[cfg(not(no_global_oom_handling))] -use super::AsVecIntoIter; -use crate::alloc::{Allocator, Global}; -#[cfg(not(no_global_oom_handling))] -use crate::collections::VecDeque; -use crate::raw_vec::RawVec; -use core::array; -use core::fmt; -use core::iter::{ - FusedIterator, InPlaceIterable, SourceIter, TrustedFused, TrustedLen, - TrustedRandomAccessNoCoerce, -}; -use core::marker::PhantomData; -use core::mem::{ManuallyDrop, MaybeUninit, SizedTypeProperties}; -use core::num::NonZero; -#[cfg(not(no_global_oom_handling))] -use core::ops::Deref; -use core::ptr::{self, NonNull}; -use core::slice::{self}; - -macro non_null { - (mut $place:expr, $t:ident) => {{ - #![allow(unused_unsafe)] // we're sometimes used within an unsafe block - unsafe { &mut *(ptr::addr_of_mut!($place) as *mut NonNull<$t>) } - }}, - ($place:expr, $t:ident) => {{ - #![allow(unused_unsafe)] // we're sometimes used within an unsafe block - unsafe { *(ptr::addr_of!($place) as *const NonNull<$t>) } - }}, -} - -/// An iterator that moves out of a vector. -/// -/// This `struct` is created by the `into_iter` method on [`Vec`](super::Vec) -/// (provided by the [`IntoIterator`] trait). -/// -/// # Example -/// -/// ``` -/// let v = vec![0, 1, 2]; -/// let iter: std::vec::IntoIter<_> = v.into_iter(); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_insignificant_dtor] -pub struct IntoIter< - T, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator = Global, -> { - pub(super) buf: NonNull, - pub(super) phantom: PhantomData, - pub(super) cap: usize, - // the drop impl reconstructs a RawVec from buf, cap and alloc - // to avoid dropping the allocator twice we need to wrap it into ManuallyDrop - pub(super) alloc: ManuallyDrop, - pub(super) ptr: NonNull, - /// If T is a ZST, this is actually ptr+len. This encoding is picked so that - /// ptr == end is a quick test for the Iterator being empty, that works - /// for both ZST and non-ZST. - /// For non-ZSTs the pointer is treated as `NonNull` - pub(super) end: *const T, -} - -#[stable(feature = "vec_intoiter_debug", since = "1.13.0")] -impl fmt::Debug for IntoIter { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_tuple("IntoIter").field(&self.as_slice()).finish() - } -} - -impl IntoIter { - /// Returns the remaining items of this iterator as a slice. - /// - /// # Examples - /// - /// ``` - /// let vec = vec!['a', 'b', 'c']; - /// let mut into_iter = vec.into_iter(); - /// assert_eq!(into_iter.as_slice(), &['a', 'b', 'c']); - /// let _ = into_iter.next().unwrap(); - /// assert_eq!(into_iter.as_slice(), &['b', 'c']); - /// ``` - #[stable(feature = "vec_into_iter_as_slice", since = "1.15.0")] - pub fn as_slice(&self) -> &[T] { - unsafe { slice::from_raw_parts(self.ptr.as_ptr(), self.len()) } - } - - /// Returns the remaining items of this iterator as a mutable slice. - /// - /// # Examples - /// - /// ``` - /// let vec = vec!['a', 'b', 'c']; - /// let mut into_iter = vec.into_iter(); - /// assert_eq!(into_iter.as_slice(), &['a', 'b', 'c']); - /// into_iter.as_mut_slice()[2] = 'z'; - /// assert_eq!(into_iter.next().unwrap(), 'a'); - /// assert_eq!(into_iter.next().unwrap(), 'b'); - /// assert_eq!(into_iter.next().unwrap(), 'z'); - /// ``` - #[stable(feature = "vec_into_iter_as_slice", since = "1.15.0")] - pub fn as_mut_slice(&mut self) -> &mut [T] { - unsafe { &mut *self.as_raw_mut_slice() } - } - - /// Returns a reference to the underlying allocator. - #[unstable(feature = "allocator_api", issue = "32838")] - #[inline] - pub fn allocator(&self) -> &A { - &self.alloc - } - - fn as_raw_mut_slice(&mut self) -> *mut [T] { - ptr::slice_from_raw_parts_mut(self.ptr.as_ptr(), self.len()) - } - - /// Drops remaining elements and relinquishes the backing allocation. - /// This method guarantees it won't panic before relinquishing - /// the backing allocation. - /// - /// This is roughly equivalent to the following, but more efficient - /// - /// ``` - /// # let mut into_iter = Vec::::with_capacity(10).into_iter(); - /// let mut into_iter = std::mem::replace(&mut into_iter, Vec::new().into_iter()); - /// (&mut into_iter).for_each(drop); - /// std::mem::forget(into_iter); - /// ``` - /// - /// This method is used by in-place iteration, refer to the vec::in_place_collect - /// documentation for an overview. - #[cfg(not(no_global_oom_handling))] - pub(super) fn forget_allocation_drop_remaining(&mut self) { - let remaining = self.as_raw_mut_slice(); - - // overwrite the individual fields instead of creating a new - // struct and then overwriting &mut self. - // this creates less assembly - self.cap = 0; - self.buf = RawVec::NEW.non_null(); - self.ptr = self.buf; - self.end = self.buf.as_ptr(); - - // Dropping the remaining elements can panic, so this needs to be - // done only after updating the other fields. - unsafe { - ptr::drop_in_place(remaining); - } - } - - /// Forgets to Drop the remaining elements while still allowing the backing allocation to be freed. - pub(crate) fn forget_remaining_elements(&mut self) { - // For the ZST case, it is crucial that we mutate `end` here, not `ptr`. - // `ptr` must stay aligned, while `end` may be unaligned. - self.end = self.ptr.as_ptr(); - } - - #[cfg(not(no_global_oom_handling))] - #[inline] - pub(crate) fn into_vecdeque(self) -> VecDeque { - // Keep our `Drop` impl from dropping the elements and the allocator - let mut this = ManuallyDrop::new(self); - - // SAFETY: This allocation originally came from a `Vec`, so it passes - // all those checks. We have `this.buf` ≤ `this.ptr` ≤ `this.end`, - // so the `sub_ptr`s below cannot wrap, and will produce a well-formed - // range. `end` ≤ `buf + cap`, so the range will be in-bounds. - // Taking `alloc` is ok because nothing else is going to look at it, - // since our `Drop` impl isn't going to run so there's no more code. - unsafe { - let buf = this.buf.as_ptr(); - let initialized = if T::IS_ZST { - // All the pointers are the same for ZSTs, so it's fine to - // say that they're all at the beginning of the "allocation". - 0..this.len() - } else { - this.ptr.sub_ptr(this.buf)..this.end.sub_ptr(buf) - }; - let cap = this.cap; - let alloc = ManuallyDrop::take(&mut this.alloc); - VecDeque::from_contiguous_raw_parts_in(buf, initialized, cap, alloc) - } - } -} - -#[stable(feature = "vec_intoiter_as_ref", since = "1.46.0")] -impl AsRef<[T]> for IntoIter { - fn as_ref(&self) -> &[T] { - self.as_slice() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Send for IntoIter {} -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl Sync for IntoIter {} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for IntoIter { - type Item = T; - - #[inline] - fn next(&mut self) -> Option { - let ptr = if T::IS_ZST { - if self.ptr.as_ptr() == self.end as *mut T { - return None; - } - // `ptr` has to stay where it is to remain aligned, so we reduce the length by 1 by - // reducing the `end`. - self.end = self.end.wrapping_byte_sub(1); - self.ptr - } else { - if self.ptr == non_null!(self.end, T) { - return None; - } - let old = self.ptr; - self.ptr = unsafe { old.add(1) }; - old - }; - Some(unsafe { ptr.read() }) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let exact = if T::IS_ZST { - self.end.addr().wrapping_sub(self.ptr.as_ptr().addr()) - } else { - unsafe { non_null!(self.end, T).sub_ptr(self.ptr) } - }; - (exact, Some(exact)) - } - - #[inline] - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - let step_size = self.len().min(n); - let to_drop = ptr::slice_from_raw_parts_mut(self.ptr.as_ptr(), step_size); - if T::IS_ZST { - // See `next` for why we sub `end` here. - self.end = self.end.wrapping_byte_sub(step_size); - } else { - // SAFETY: the min() above ensures that step_size is in bounds - self.ptr = unsafe { self.ptr.add(step_size) }; - } - // SAFETY: the min() above ensures that step_size is in bounds - unsafe { - ptr::drop_in_place(to_drop); - } - NonZero::new(n - step_size).map_or(Ok(()), Err) - } - - #[inline] - fn count(self) -> usize { - self.len() - } - - #[inline] - fn next_chunk(&mut self) -> Result<[T; N], core::array::IntoIter> { - let mut raw_ary = MaybeUninit::uninit_array(); - - let len = self.len(); - - if T::IS_ZST { - if len < N { - self.forget_remaining_elements(); - // Safety: ZSTs can be conjured ex nihilo, only the amount has to be correct - return Err(unsafe { array::IntoIter::new_unchecked(raw_ary, 0..len) }); - } - - self.end = self.end.wrapping_byte_sub(N); - // Safety: ditto - return Ok(unsafe { raw_ary.transpose().assume_init() }); - } - - if len < N { - // Safety: `len` indicates that this many elements are available and we just checked that - // it fits into the array. - unsafe { - ptr::copy_nonoverlapping(self.ptr.as_ptr(), raw_ary.as_mut_ptr() as *mut T, len); - self.forget_remaining_elements(); - return Err(array::IntoIter::new_unchecked(raw_ary, 0..len)); - } - } - - // Safety: `len` is larger than the array size. Copy a fixed amount here to fully initialize - // the array. - return unsafe { - ptr::copy_nonoverlapping(self.ptr.as_ptr(), raw_ary.as_mut_ptr() as *mut T, N); - self.ptr = self.ptr.add(N); - Ok(raw_ary.transpose().assume_init()) - }; - } - - fn fold(mut self, mut accum: B, mut f: F) -> B - where - F: FnMut(B, Self::Item) -> B, - { - if T::IS_ZST { - while self.ptr.as_ptr() != self.end.cast_mut() { - // SAFETY: we just checked that `self.ptr` is in bounds. - let tmp = unsafe { self.ptr.read() }; - // See `next` for why we subtract from `end` here. - self.end = self.end.wrapping_byte_sub(1); - accum = f(accum, tmp); - } - } else { - // SAFETY: `self.end` can only be null if `T` is a ZST. - while self.ptr != non_null!(self.end, T) { - // SAFETY: we just checked that `self.ptr` is in bounds. - let tmp = unsafe { self.ptr.read() }; - // SAFETY: the maximum this can be is `self.end`. - // Increment `self.ptr` first to avoid double dropping in the event of a panic. - self.ptr = unsafe { self.ptr.add(1) }; - accum = f(accum, tmp); - } - } - accum - } - - fn try_fold(&mut self, mut accum: B, mut f: F) -> R - where - Self: Sized, - F: FnMut(B, Self::Item) -> R, - R: core::ops::Try, - { - if T::IS_ZST { - while self.ptr.as_ptr() != self.end.cast_mut() { - // SAFETY: we just checked that `self.ptr` is in bounds. - let tmp = unsafe { self.ptr.read() }; - // See `next` for why we subtract from `end` here. - self.end = self.end.wrapping_byte_sub(1); - accum = f(accum, tmp)?; - } - } else { - // SAFETY: `self.end` can only be null if `T` is a ZST. - while self.ptr != non_null!(self.end, T) { - // SAFETY: we just checked that `self.ptr` is in bounds. - let tmp = unsafe { self.ptr.read() }; - // SAFETY: the maximum this can be is `self.end`. - // Increment `self.ptr` first to avoid double dropping in the event of a panic. - self.ptr = unsafe { self.ptr.add(1) }; - accum = f(accum, tmp)?; - } - } - R::from_output(accum) - } - - unsafe fn __iterator_get_unchecked(&mut self, i: usize) -> Self::Item - where - Self: TrustedRandomAccessNoCoerce, - { - // SAFETY: the caller must guarantee that `i` is in bounds of the - // `Vec`, so `i` cannot overflow an `isize`, and the `self.ptr.add(i)` - // is guaranteed to pointer to an element of the `Vec` and - // thus guaranteed to be valid to dereference. - // - // Also note the implementation of `Self: TrustedRandomAccess` requires - // that `T: Copy` so reading elements from the buffer doesn't invalidate - // them for `Drop`. - unsafe { self.ptr.add(i).read() } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DoubleEndedIterator for IntoIter { - #[inline] - fn next_back(&mut self) -> Option { - if T::IS_ZST { - if self.ptr.as_ptr() == self.end as *mut _ { - return None; - } - // See above for why 'ptr.offset' isn't used - self.end = self.end.wrapping_byte_sub(1); - // Note that even though this is next_back() we're reading from `self.ptr`, not - // `self.end`. We track our length using the byte offset from `self.ptr` to `self.end`, - // so the end pointer may not be suitably aligned for T. - Some(unsafe { ptr::read(self.ptr.as_ptr()) }) - } else { - if self.ptr == non_null!(self.end, T) { - return None; - } - unsafe { - self.end = self.end.sub(1); - Some(ptr::read(self.end)) - } - } - } - - #[inline] - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - let step_size = self.len().min(n); - if T::IS_ZST { - // SAFETY: same as for advance_by() - self.end = self.end.wrapping_byte_sub(step_size); - } else { - // SAFETY: same as for advance_by() - self.end = unsafe { self.end.sub(step_size) }; - } - let to_drop = ptr::slice_from_raw_parts_mut(self.end as *mut T, step_size); - // SAFETY: same as for advance_by() - unsafe { - ptr::drop_in_place(to_drop); - } - NonZero::new(n - step_size).map_or(Ok(()), Err) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for IntoIter { - fn is_empty(&self) -> bool { - if T::IS_ZST { - self.ptr.as_ptr() == self.end as *mut _ - } else { - self.ptr == non_null!(self.end, T) - } - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for IntoIter {} - -#[doc(hidden)] -#[unstable(issue = "none", feature = "trusted_fused")] -unsafe impl TrustedFused for IntoIter {} - -#[unstable(feature = "trusted_len", issue = "37572")] -unsafe impl TrustedLen for IntoIter {} - -#[stable(feature = "default_iters", since = "1.70.0")] -impl Default for IntoIter -where - A: Allocator + Default, -{ - /// Creates an empty `vec::IntoIter`. - /// - /// ``` - /// # use std::vec; - /// let iter: vec::IntoIter = Default::default(); - /// assert_eq!(iter.len(), 0); - /// assert_eq!(iter.as_slice(), &[]); - /// ``` - fn default() -> Self { - super::Vec::new_in(Default::default()).into_iter() - } -} - -#[doc(hidden)] -#[unstable(issue = "none", feature = "std_internals")] -#[rustc_unsafe_specialization_marker] -pub trait NonDrop {} - -// T: Copy as approximation for !Drop since get_unchecked does not advance self.ptr -// and thus we can't implement drop-handling -#[unstable(issue = "none", feature = "std_internals")] -impl NonDrop for T {} - -#[doc(hidden)] -#[unstable(issue = "none", feature = "std_internals")] -// TrustedRandomAccess (without NoCoerce) must not be implemented because -// subtypes/supertypes of `T` might not be `NonDrop` -unsafe impl TrustedRandomAccessNoCoerce for IntoIter -where - T: NonDrop, -{ - const MAY_HAVE_SIDE_EFFECT: bool = false; -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "vec_into_iter_clone", since = "1.8.0")] -impl Clone for IntoIter { - #[cfg(not(test))] - fn clone(&self) -> Self { - self.as_slice().to_vec_in(self.alloc.deref().clone()).into_iter() - } - #[cfg(test)] - fn clone(&self) -> Self { - crate::slice::to_vec(self.as_slice(), self.alloc.deref().clone()).into_iter() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl<#[may_dangle] T, A: Allocator> Drop for IntoIter { - fn drop(&mut self) { - struct DropGuard<'a, T, A: Allocator>(&'a mut IntoIter); - - impl Drop for DropGuard<'_, T, A> { - fn drop(&mut self) { - unsafe { - // `IntoIter::alloc` is not used anymore after this and will be dropped by RawVec - let alloc = ManuallyDrop::take(&mut self.0.alloc); - // RawVec handles deallocation - let _ = RawVec::from_nonnull_in(self.0.buf, self.0.cap, alloc); - } - } - } - - let guard = DropGuard(self); - // destroy the remaining elements - unsafe { - ptr::drop_in_place(guard.0.as_raw_mut_slice()); - } - // now `guard` will be dropped and do the rest - } -} - -// In addition to the SAFETY invariants of the following three unsafe traits -// also refer to the vec::in_place_collect module documentation to get an overview -#[unstable(issue = "none", feature = "inplace_iteration")] -#[doc(hidden)] -unsafe impl InPlaceIterable for IntoIter { - const EXPAND_BY: Option> = NonZero::new(1); - const MERGE_BY: Option> = NonZero::new(1); -} - -#[unstable(issue = "none", feature = "inplace_iteration")] -#[doc(hidden)] -unsafe impl SourceIter for IntoIter { - type Source = Self; - - #[inline] - unsafe fn as_inner(&mut self) -> &mut Self::Source { - self - } -} - -#[cfg(not(no_global_oom_handling))] -unsafe impl AsVecIntoIter for IntoIter { - type Item = T; - - fn as_into_iter(&mut self) -> &mut IntoIter { - self - } -} diff --git a/library/alloc/src/vec/is_zero.rs b/library/alloc/src/vec/is_zero.rs deleted file mode 100644 index bcc5bf4d65bb4..0000000000000 --- a/library/alloc/src/vec/is_zero.rs +++ /dev/null @@ -1,189 +0,0 @@ -use core::num::{NonZero, Saturating, Wrapping}; - -use crate::boxed::Box; - -#[rustc_specialization_trait] -pub(super) unsafe trait IsZero { - /// Whether this value's representation is all zeros, - /// or can be represented with all zeroes. - fn is_zero(&self) -> bool; -} - -macro_rules! impl_is_zero { - ($t:ty, $is_zero:expr) => { - unsafe impl IsZero for $t { - #[inline] - fn is_zero(&self) -> bool { - $is_zero(*self) - } - } - }; -} - -impl_is_zero!(i8, |x| x == 0); // It is needed to impl for arrays and tuples of i8. -impl_is_zero!(i16, |x| x == 0); -impl_is_zero!(i32, |x| x == 0); -impl_is_zero!(i64, |x| x == 0); -impl_is_zero!(i128, |x| x == 0); -impl_is_zero!(isize, |x| x == 0); - -impl_is_zero!(u8, |x| x == 0); // It is needed to impl for arrays and tuples of u8. -impl_is_zero!(u16, |x| x == 0); -impl_is_zero!(u32, |x| x == 0); -impl_is_zero!(u64, |x| x == 0); -impl_is_zero!(u128, |x| x == 0); -impl_is_zero!(usize, |x| x == 0); - -impl_is_zero!(bool, |x| x == false); -impl_is_zero!(char, |x| x == '\0'); - -impl_is_zero!(f32, |x: f32| x.to_bits() == 0); -impl_is_zero!(f64, |x: f64| x.to_bits() == 0); - -unsafe impl IsZero for *const T { - #[inline] - fn is_zero(&self) -> bool { - (*self).is_null() - } -} - -unsafe impl IsZero for *mut T { - #[inline] - fn is_zero(&self) -> bool { - (*self).is_null() - } -} - -unsafe impl IsZero for [T; N] { - #[inline] - fn is_zero(&self) -> bool { - // Because this is generated as a runtime check, it's not obvious that - // it's worth doing if the array is really long. The threshold here - // is largely arbitrary, but was picked because as of 2022-07-01 LLVM - // fails to const-fold the check in `vec![[1; 32]; n]` - // See https://github.com/rust-lang/rust/pull/97581#issuecomment-1166628022 - // Feel free to tweak if you have better evidence. - - N <= 16 && self.iter().all(IsZero::is_zero) - } -} - -// This is recursive macro. -macro_rules! impl_is_zero_tuples { - // Stopper - () => { - // No use for implementing for empty tuple because it is ZST. - }; - ($first_arg:ident $(,$rest:ident)*) => { - unsafe impl <$first_arg: IsZero, $($rest: IsZero,)*> IsZero for ($first_arg, $($rest,)*){ - #[inline] - fn is_zero(&self) -> bool{ - // Destructure tuple to N references - // Rust allows to hide generic params by local variable names. - #[allow(non_snake_case)] - let ($first_arg, $($rest,)*) = self; - - $first_arg.is_zero() - $( && $rest.is_zero() )* - } - } - - impl_is_zero_tuples!($($rest),*); - } -} - -impl_is_zero_tuples!(A, B, C, D, E, F, G, H); - -// `Option<&T>` and `Option>` are guaranteed to represent `None` as null. -// For fat pointers, the bytes that would be the pointer metadata in the `Some` -// variant are padding in the `None` variant, so ignoring them and -// zero-initializing instead is ok. -// `Option<&mut T>` never implements `Clone`, so there's no need for an impl of -// `SpecFromElem`. - -unsafe impl IsZero for Option<&T> { - #[inline] - fn is_zero(&self) -> bool { - self.is_none() - } -} - -unsafe impl IsZero for Option> { - #[inline] - fn is_zero(&self) -> bool { - self.is_none() - } -} - -// `Option>` and similar have a representation guarantee that -// they're the same size as the corresponding `u32` type, as well as a guarantee -// that transmuting between `NonZero` and `Option>` works. -// While the documentation officially makes it UB to transmute from `None`, -// we're the standard library so we can make extra inferences, and we know that -// the only niche available to represent `None` is the one that's all zeros. -macro_rules! impl_is_zero_option_of_nonzero_int { - ($($t:ty),+ $(,)?) => {$( - unsafe impl IsZero for Option> { - #[inline] - fn is_zero(&self) -> bool { - self.is_none() - } - } - )+}; -} - -impl_is_zero_option_of_nonzero_int!(u8, u16, u32, u64, u128, usize, i8, i16, i32, i64, i128, isize); - -macro_rules! impl_is_zero_option_of_int { - ($($t:ty),+ $(,)?) => {$( - unsafe impl IsZero for Option<$t> { - #[inline] - fn is_zero(&self) -> bool { - const { - let none: Self = unsafe { core::mem::MaybeUninit::zeroed().assume_init() }; - assert!(none.is_none()); - } - self.is_none() - } - } - )+}; -} - -impl_is_zero_option_of_int!(u8, u16, u32, u64, u128, i8, i16, i32, i64, i128, usize, isize); - -unsafe impl IsZero for Wrapping { - #[inline] - fn is_zero(&self) -> bool { - self.0.is_zero() - } -} - -unsafe impl IsZero for Saturating { - #[inline] - fn is_zero(&self) -> bool { - self.0.is_zero() - } -} - -macro_rules! impl_is_zero_option_of_bool { - ($($t:ty),+ $(,)?) => {$( - unsafe impl IsZero for $t { - #[inline] - fn is_zero(&self) -> bool { - // SAFETY: This is *not* a stable layout guarantee, but - // inside `core` we're allowed to rely on the current rustc - // behaviour that options of bools will be one byte with - // no padding, so long as they're nested less than 254 deep. - let raw: u8 = unsafe { core::mem::transmute(*self) }; - raw == 0 - } - } - )+}; -} - -impl_is_zero_option_of_bool! { - Option, - Option>, - Option>>, - // Could go further, but not worth the metadata overhead. -} diff --git a/library/alloc/src/vec/mod.rs b/library/alloc/src/vec/mod.rs deleted file mode 100644 index b2e22d8715a8b..0000000000000 --- a/library/alloc/src/vec/mod.rs +++ /dev/null @@ -1,3558 +0,0 @@ -//! A contiguous growable array type with heap-allocated contents, written -//! `Vec`. -//! -//! Vectors have *O*(1) indexing, amortized *O*(1) push (to the end) and -//! *O*(1) pop (from the end). -//! -//! Vectors ensure they never allocate more than `isize::MAX` bytes. -//! -//! # Examples -//! -//! You can explicitly create a [`Vec`] with [`Vec::new`]: -//! -//! ``` -//! let v: Vec = Vec::new(); -//! ``` -//! -//! ...or by using the [`vec!`] macro: -//! -//! ``` -//! let v: Vec = vec![]; -//! -//! let v = vec![1, 2, 3, 4, 5]; -//! -//! let v = vec![0; 10]; // ten zeroes -//! ``` -//! -//! You can [`push`] values onto the end of a vector (which will grow the vector -//! as needed): -//! -//! ``` -//! let mut v = vec![1, 2]; -//! -//! v.push(3); -//! ``` -//! -//! Popping values works in much the same way: -//! -//! ``` -//! let mut v = vec![1, 2]; -//! -//! let two = v.pop(); -//! ``` -//! -//! Vectors also support indexing (through the [`Index`] and [`IndexMut`] traits): -//! -//! ``` -//! let mut v = vec![1, 2, 3]; -//! let three = v[2]; -//! v[1] = v[1] + 5; -//! ``` -//! -//! [`push`]: Vec::push - -#![stable(feature = "rust1", since = "1.0.0")] - -#[cfg(not(no_global_oom_handling))] -use core::cmp; -use core::cmp::Ordering; -use core::fmt; -use core::hash::{Hash, Hasher}; -#[cfg(not(no_global_oom_handling))] -use core::iter; -use core::marker::PhantomData; -use core::mem::{self, ManuallyDrop, MaybeUninit, SizedTypeProperties}; -use core::ops::{self, Index, IndexMut, Range, RangeBounds}; -use core::ptr::{self, NonNull}; -use core::slice::{self, SliceIndex}; - -use crate::alloc::{Allocator, Global}; -use crate::borrow::{Cow, ToOwned}; -use crate::boxed::Box; -use crate::collections::TryReserveError; -use crate::raw_vec::RawVec; - -#[unstable(feature = "extract_if", reason = "recently added", issue = "43244")] -pub use self::extract_if::ExtractIf; - -mod extract_if; - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "vec_splice", since = "1.21.0")] -pub use self::splice::Splice; - -#[cfg(not(no_global_oom_handling))] -mod splice; - -#[stable(feature = "drain", since = "1.6.0")] -pub use self::drain::Drain; - -mod drain; - -#[cfg(not(no_global_oom_handling))] -mod cow; - -#[cfg(not(no_global_oom_handling))] -pub(crate) use self::in_place_collect::AsVecIntoIter; -#[stable(feature = "rust1", since = "1.0.0")] -pub use self::into_iter::IntoIter; - -mod into_iter; - -#[cfg(not(no_global_oom_handling))] -use self::is_zero::IsZero; - -#[cfg(not(no_global_oom_handling))] -mod is_zero; - -#[cfg(not(no_global_oom_handling))] -mod in_place_collect; - -mod partial_eq; - -#[cfg(not(no_global_oom_handling))] -use self::spec_from_elem::SpecFromElem; - -#[cfg(not(no_global_oom_handling))] -mod spec_from_elem; - -#[cfg(not(no_global_oom_handling))] -use self::set_len_on_drop::SetLenOnDrop; - -#[cfg(not(no_global_oom_handling))] -mod set_len_on_drop; - -#[cfg(not(no_global_oom_handling))] -use self::in_place_drop::{InPlaceDrop, InPlaceDstDataSrcBufDrop}; - -#[cfg(not(no_global_oom_handling))] -mod in_place_drop; - -#[cfg(not(no_global_oom_handling))] -use self::spec_from_iter_nested::SpecFromIterNested; - -#[cfg(not(no_global_oom_handling))] -mod spec_from_iter_nested; - -#[cfg(not(no_global_oom_handling))] -use self::spec_from_iter::SpecFromIter; - -#[cfg(not(no_global_oom_handling))] -mod spec_from_iter; - -#[cfg(not(no_global_oom_handling))] -use self::spec_extend::SpecExtend; - -#[cfg(not(no_global_oom_handling))] -mod spec_extend; - -/// A contiguous growable array type, written as `Vec`, short for 'vector'. -/// -/// # Examples -/// -/// ``` -/// let mut vec = Vec::new(); -/// vec.push(1); -/// vec.push(2); -/// -/// assert_eq!(vec.len(), 2); -/// assert_eq!(vec[0], 1); -/// -/// assert_eq!(vec.pop(), Some(2)); -/// assert_eq!(vec.len(), 1); -/// -/// vec[0] = 7; -/// assert_eq!(vec[0], 7); -/// -/// vec.extend([1, 2, 3]); -/// -/// for x in &vec { -/// println!("{x}"); -/// } -/// assert_eq!(vec, [7, 1, 2, 3]); -/// ``` -/// -/// The [`vec!`] macro is provided for convenient initialization: -/// -/// ``` -/// let mut vec1 = vec![1, 2, 3]; -/// vec1.push(4); -/// let vec2 = Vec::from([1, 2, 3, 4]); -/// assert_eq!(vec1, vec2); -/// ``` -/// -/// It can also initialize each element of a `Vec` with a given value. -/// This may be more efficient than performing allocation and initialization -/// in separate steps, especially when initializing a vector of zeros: -/// -/// ``` -/// let vec = vec![0; 5]; -/// assert_eq!(vec, [0, 0, 0, 0, 0]); -/// -/// // The following is equivalent, but potentially slower: -/// let mut vec = Vec::with_capacity(5); -/// vec.resize(5, 0); -/// assert_eq!(vec, [0, 0, 0, 0, 0]); -/// ``` -/// -/// For more information, see -/// [Capacity and Reallocation](#capacity-and-reallocation). -/// -/// Use a `Vec` as an efficient stack: -/// -/// ``` -/// let mut stack = Vec::new(); -/// -/// stack.push(1); -/// stack.push(2); -/// stack.push(3); -/// -/// while let Some(top) = stack.pop() { -/// // Prints 3, 2, 1 -/// println!("{top}"); -/// } -/// ``` -/// -/// # Indexing -/// -/// The `Vec` type allows access to values by index, because it implements the -/// [`Index`] trait. An example will be more explicit: -/// -/// ``` -/// let v = vec![0, 2, 4, 6]; -/// println!("{}", v[1]); // it will display '2' -/// ``` -/// -/// However be careful: if you try to access an index which isn't in the `Vec`, -/// your software will panic! You cannot do this: -/// -/// ```should_panic -/// let v = vec![0, 2, 4, 6]; -/// println!("{}", v[6]); // it will panic! -/// ``` -/// -/// Use [`get`] and [`get_mut`] if you want to check whether the index is in -/// the `Vec`. -/// -/// # Slicing -/// -/// A `Vec` can be mutable. On the other hand, slices are read-only objects. -/// To get a [slice][prim@slice], use [`&`]. Example: -/// -/// ``` -/// fn read_slice(slice: &[usize]) { -/// // ... -/// } -/// -/// let v = vec![0, 1]; -/// read_slice(&v); -/// -/// // ... and that's all! -/// // you can also do it like this: -/// let u: &[usize] = &v; -/// // or like this: -/// let u: &[_] = &v; -/// ``` -/// -/// In Rust, it's more common to pass slices as arguments rather than vectors -/// when you just want to provide read access. The same goes for [`String`] and -/// [`&str`]. -/// -/// # Capacity and reallocation -/// -/// The capacity of a vector is the amount of space allocated for any future -/// elements that will be added onto the vector. This is not to be confused with -/// the *length* of a vector, which specifies the number of actual elements -/// within the vector. If a vector's length exceeds its capacity, its capacity -/// will automatically be increased, but its elements will have to be -/// reallocated. -/// -/// For example, a vector with capacity 10 and length 0 would be an empty vector -/// with space for 10 more elements. Pushing 10 or fewer elements onto the -/// vector will not change its capacity or cause reallocation to occur. However, -/// if the vector's length is increased to 11, it will have to reallocate, which -/// can be slow. For this reason, it is recommended to use [`Vec::with_capacity`] -/// whenever possible to specify how big the vector is expected to get. -/// -/// # Guarantees -/// -/// Due to its incredibly fundamental nature, `Vec` makes a lot of guarantees -/// about its design. This ensures that it's as low-overhead as possible in -/// the general case, and can be correctly manipulated in primitive ways -/// by unsafe code. Note that these guarantees refer to an unqualified `Vec`. -/// If additional type parameters are added (e.g., to support custom allocators), -/// overriding their defaults may change the behavior. -/// -/// Most fundamentally, `Vec` is and always will be a (pointer, capacity, length) -/// triplet. No more, no less. The order of these fields is completely -/// unspecified, and you should use the appropriate methods to modify these. -/// The pointer will never be null, so this type is null-pointer-optimized. -/// -/// However, the pointer might not actually point to allocated memory. In particular, -/// if you construct a `Vec` with capacity 0 via [`Vec::new`], [`vec![]`][`vec!`], -/// [`Vec::with_capacity(0)`][`Vec::with_capacity`], or by calling [`shrink_to_fit`] -/// on an empty Vec, it will not allocate memory. Similarly, if you store zero-sized -/// types inside a `Vec`, it will not allocate space for them. *Note that in this case -/// the `Vec` might not report a [`capacity`] of 0*. `Vec` will allocate if and only -/// if [mem::size_of::\]\() * [capacity]\() > 0. In general, `Vec`'s allocation -/// details are very subtle --- if you intend to allocate memory using a `Vec` -/// and use it for something else (either to pass to unsafe code, or to build your -/// own memory-backed collection), be sure to deallocate this memory by using -/// `from_raw_parts` to recover the `Vec` and then dropping it. -/// -/// If a `Vec` *has* allocated memory, then the memory it points to is on the heap -/// (as defined by the allocator Rust is configured to use by default), and its -/// pointer points to [`len`] initialized, contiguous elements in order (what -/// you would see if you coerced it to a slice), followed by [capacity] - [len] -/// logically uninitialized, contiguous elements. -/// -/// A vector containing the elements `'a'` and `'b'` with capacity 4 can be -/// visualized as below. The top part is the `Vec` struct, it contains a -/// pointer to the head of the allocation in the heap, length and capacity. -/// The bottom part is the allocation on the heap, a contiguous memory block. -/// -/// ```text -/// ptr len capacity -/// +--------+--------+--------+ -/// | 0x0123 | 2 | 4 | -/// +--------+--------+--------+ -/// | -/// v -/// Heap +--------+--------+--------+--------+ -/// | 'a' | 'b' | uninit | uninit | -/// +--------+--------+--------+--------+ -/// ``` -/// -/// - **uninit** represents memory that is not initialized, see [`MaybeUninit`]. -/// - Note: the ABI is not stable and `Vec` makes no guarantees about its memory -/// layout (including the order of fields). -/// -/// `Vec` will never perform a "small optimization" where elements are actually -/// stored on the stack for two reasons: -/// -/// * It would make it more difficult for unsafe code to correctly manipulate -/// a `Vec`. The contents of a `Vec` wouldn't have a stable address if it were -/// only moved, and it would be more difficult to determine if a `Vec` had -/// actually allocated memory. -/// -/// * It would penalize the general case, incurring an additional branch -/// on every access. -/// -/// `Vec` will never automatically shrink itself, even if completely empty. This -/// ensures no unnecessary allocations or deallocations occur. Emptying a `Vec` -/// and then filling it back up to the same [`len`] should incur no calls to -/// the allocator. If you wish to free up unused memory, use -/// [`shrink_to_fit`] or [`shrink_to`]. -/// -/// [`push`] and [`insert`] will never (re)allocate if the reported capacity is -/// sufficient. [`push`] and [`insert`] *will* (re)allocate if -/// [len] == [capacity]. That is, the reported capacity is completely -/// accurate, and can be relied on. It can even be used to manually free the memory -/// allocated by a `Vec` if desired. Bulk insertion methods *may* reallocate, even -/// when not necessary. -/// -/// `Vec` does not guarantee any particular growth strategy when reallocating -/// when full, nor when [`reserve`] is called. The current strategy is basic -/// and it may prove desirable to use a non-constant growth factor. Whatever -/// strategy is used will of course guarantee *O*(1) amortized [`push`]. -/// -/// `vec![x; n]`, `vec![a, b, c, d]`, and -/// [`Vec::with_capacity(n)`][`Vec::with_capacity`], will all produce a `Vec` -/// with at least the requested capacity. If [len] == [capacity], -/// (as is the case for the [`vec!`] macro), then a `Vec` can be converted to -/// and from a [`Box<[T]>`][owned slice] without reallocating or moving the elements. -/// -/// `Vec` will not specifically overwrite any data that is removed from it, -/// but also won't specifically preserve it. Its uninitialized memory is -/// scratch space that it may use however it wants. It will generally just do -/// whatever is most efficient or otherwise easy to implement. Do not rely on -/// removed data to be erased for security purposes. Even if you drop a `Vec`, its -/// buffer may simply be reused by another allocation. Even if you zero a `Vec`'s memory -/// first, that might not actually happen because the optimizer does not consider -/// this a side-effect that must be preserved. There is one case which we will -/// not break, however: using `unsafe` code to write to the excess capacity, -/// and then increasing the length to match, is always valid. -/// -/// Currently, `Vec` does not guarantee the order in which elements are dropped. -/// The order has changed in the past and may change again. -/// -/// [`get`]: slice::get -/// [`get_mut`]: slice::get_mut -/// [`String`]: crate::string::String -/// [`&str`]: type@str -/// [`shrink_to_fit`]: Vec::shrink_to_fit -/// [`shrink_to`]: Vec::shrink_to -/// [capacity]: Vec::capacity -/// [`capacity`]: Vec::capacity -/// [mem::size_of::\]: core::mem::size_of -/// [len]: Vec::len -/// [`len`]: Vec::len -/// [`push`]: Vec::push -/// [`insert`]: Vec::insert -/// [`reserve`]: Vec::reserve -/// [`MaybeUninit`]: core::mem::MaybeUninit -/// [owned slice]: Box -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "Vec")] -#[rustc_insignificant_dtor] -pub struct Vec { - buf: RawVec, - len: usize, -} - -//////////////////////////////////////////////////////////////////////////////// -// Inherent methods -//////////////////////////////////////////////////////////////////////////////// - -impl Vec { - /// Constructs a new, empty `Vec`. - /// - /// The vector will not allocate until elements are pushed onto it. - /// - /// # Examples - /// - /// ``` - /// # #![allow(unused_mut)] - /// let mut vec: Vec = Vec::new(); - /// ``` - #[inline] - #[rustc_const_stable(feature = "const_vec_new", since = "1.39.0")] - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - pub const fn new() -> Self { - Vec { buf: RawVec::NEW, len: 0 } - } - - /// Constructs a new, empty `Vec` with at least the specified capacity. - /// - /// The vector will be able to hold at least `capacity` elements without - /// reallocating. This method is allowed to allocate for more elements than - /// `capacity`. If `capacity` is 0, the vector will not allocate. - /// - /// It is important to note that although the returned vector has the - /// minimum *capacity* specified, the vector will have a zero *length*. For - /// an explanation of the difference between length and capacity, see - /// *[Capacity and reallocation]*. - /// - /// If it is important to know the exact allocated capacity of a `Vec`, - /// always use the [`capacity`] method after construction. - /// - /// For `Vec` where `T` is a zero-sized type, there will be no allocation - /// and the capacity will always be `usize::MAX`. - /// - /// [Capacity and reallocation]: #capacity-and-reallocation - /// [`capacity`]: Vec::capacity - /// - /// # Panics - /// - /// Panics if the new capacity exceeds `isize::MAX` _bytes_. - /// - /// # Examples - /// - /// ``` - /// let mut vec = Vec::with_capacity(10); - /// - /// // The vector contains no items, even though it has capacity for more - /// assert_eq!(vec.len(), 0); - /// assert!(vec.capacity() >= 10); - /// - /// // These are all done without reallocating... - /// for i in 0..10 { - /// vec.push(i); - /// } - /// assert_eq!(vec.len(), 10); - /// assert!(vec.capacity() >= 10); - /// - /// // ...but this may make the vector reallocate - /// vec.push(11); - /// assert_eq!(vec.len(), 11); - /// assert!(vec.capacity() >= 11); - /// - /// // A vector of a zero-sized type will always over-allocate, since no - /// // allocation is necessary - /// let vec_units = Vec::<()>::with_capacity(10); - /// assert_eq!(vec_units.capacity(), usize::MAX); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[must_use] - pub fn with_capacity(capacity: usize) -> Self { - Self::with_capacity_in(capacity, Global) - } - - /// Constructs a new, empty `Vec` with at least the specified capacity. - /// - /// The vector will be able to hold at least `capacity` elements without - /// reallocating. This method is allowed to allocate for more elements than - /// `capacity`. If `capacity` is 0, the vector will not allocate. - /// - /// # Errors - /// - /// Returns an error if the capacity exceeds `isize::MAX` _bytes_, - /// or if the allocator reports allocation failure. - #[inline] - #[unstable(feature = "try_with_capacity", issue = "91913")] - pub fn try_with_capacity(capacity: usize) -> Result { - Self::try_with_capacity_in(capacity, Global) - } - - /// Creates a `Vec` directly from a pointer, a length, and a capacity. - /// - /// # Safety - /// - /// This is highly unsafe, due to the number of invariants that aren't - /// checked: - /// - /// * `ptr` must have been allocated using the global allocator, such as via - /// the [`alloc::alloc`] function. - /// * `T` needs to have the same alignment as what `ptr` was allocated with. - /// (`T` having a less strict alignment is not sufficient, the alignment really - /// needs to be equal to satisfy the [`dealloc`] requirement that memory must be - /// allocated and deallocated with the same layout.) - /// * The size of `T` times the `capacity` (ie. the allocated size in bytes) needs - /// to be the same size as the pointer was allocated with. (Because similar to - /// alignment, [`dealloc`] must be called with the same layout `size`.) - /// * `length` needs to be less than or equal to `capacity`. - /// * The first `length` values must be properly initialized values of type `T`. - /// * `capacity` needs to be the capacity that the pointer was allocated with. - /// * The allocated size in bytes must be no larger than `isize::MAX`. - /// See the safety documentation of [`pointer::offset`]. - /// - /// These requirements are always upheld by any `ptr` that has been allocated - /// via `Vec`. Other allocation sources are allowed if the invariants are - /// upheld. - /// - /// Violating these may cause problems like corrupting the allocator's - /// internal data structures. For example it is normally **not** safe - /// to build a `Vec` from a pointer to a C `char` array with length - /// `size_t`, doing so is only safe if the array was initially allocated by - /// a `Vec` or `String`. - /// It's also not safe to build one from a `Vec` and its length, because - /// the allocator cares about the alignment, and these two types have different - /// alignments. The buffer was allocated with alignment 2 (for `u16`), but after - /// turning it into a `Vec` it'll be deallocated with alignment 1. To avoid - /// these issues, it is often preferable to do casting/transmuting using - /// [`slice::from_raw_parts`] instead. - /// - /// The ownership of `ptr` is effectively transferred to the - /// `Vec` which may then deallocate, reallocate or change the - /// contents of memory pointed to by the pointer at will. Ensure - /// that nothing else uses the pointer after calling this - /// function. - /// - /// [`String`]: crate::string::String - /// [`alloc::alloc`]: crate::alloc::alloc - /// [`dealloc`]: crate::alloc::GlobalAlloc::dealloc - /// - /// # Examples - /// - /// ``` - /// use std::ptr; - /// use std::mem; - /// - /// let v = vec![1, 2, 3]; - /// - // FIXME Update this when vec_into_raw_parts is stabilized - /// // Prevent running `v`'s destructor so we are in complete control - /// // of the allocation. - /// let mut v = mem::ManuallyDrop::new(v); - /// - /// // Pull out the various important pieces of information about `v` - /// let p = v.as_mut_ptr(); - /// let len = v.len(); - /// let cap = v.capacity(); - /// - /// unsafe { - /// // Overwrite memory with 4, 5, 6 - /// for i in 0..len { - /// ptr::write(p.add(i), 4 + i); - /// } - /// - /// // Put everything back together into a Vec - /// let rebuilt = Vec::from_raw_parts(p, len, cap); - /// assert_eq!(rebuilt, [4, 5, 6]); - /// } - /// ``` - /// - /// Using memory that was allocated elsewhere: - /// - /// ```rust - /// use std::alloc::{alloc, Layout}; - /// - /// fn main() { - /// let layout = Layout::array::(16).expect("overflow cannot happen"); - /// - /// let vec = unsafe { - /// let mem = alloc(layout).cast::(); - /// if mem.is_null() { - /// return; - /// } - /// - /// mem.write(1_000_000); - /// - /// Vec::from_raw_parts(mem, 1, 16) - /// }; - /// - /// assert_eq!(vec, &[1_000_000]); - /// assert_eq!(vec.capacity(), 16); - /// } - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub unsafe fn from_raw_parts(ptr: *mut T, length: usize, capacity: usize) -> Self { - unsafe { Self::from_raw_parts_in(ptr, length, capacity, Global) } - } - - /// A convenience method for hoisting the non-null precondition out of [`Vec::from_raw_parts`]. - /// - /// # Safety - /// - /// See [`Vec::from_raw_parts`]. - #[inline] - #[cfg(not(no_global_oom_handling))] // required by tests/run-make/alloc-no-oom-handling - pub(crate) unsafe fn from_nonnull(ptr: NonNull, length: usize, capacity: usize) -> Self { - unsafe { Self::from_nonnull_in(ptr, length, capacity, Global) } - } -} - -impl Vec { - /// Constructs a new, empty `Vec`. - /// - /// The vector will not allocate until elements are pushed onto it. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// - /// use std::alloc::System; - /// - /// # #[allow(unused_mut)] - /// let mut vec: Vec = Vec::new_in(System); - /// ``` - #[inline] - #[unstable(feature = "allocator_api", issue = "32838")] - pub const fn new_in(alloc: A) -> Self { - Vec { buf: RawVec::new_in(alloc), len: 0 } - } - - /// Constructs a new, empty `Vec` with at least the specified capacity - /// with the provided allocator. - /// - /// The vector will be able to hold at least `capacity` elements without - /// reallocating. This method is allowed to allocate for more elements than - /// `capacity`. If `capacity` is 0, the vector will not allocate. - /// - /// It is important to note that although the returned vector has the - /// minimum *capacity* specified, the vector will have a zero *length*. For - /// an explanation of the difference between length and capacity, see - /// *[Capacity and reallocation]*. - /// - /// If it is important to know the exact allocated capacity of a `Vec`, - /// always use the [`capacity`] method after construction. - /// - /// For `Vec` where `T` is a zero-sized type, there will be no allocation - /// and the capacity will always be `usize::MAX`. - /// - /// [Capacity and reallocation]: #capacity-and-reallocation - /// [`capacity`]: Vec::capacity - /// - /// # Panics - /// - /// Panics if the new capacity exceeds `isize::MAX` _bytes_. - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// - /// use std::alloc::System; - /// - /// let mut vec = Vec::with_capacity_in(10, System); - /// - /// // The vector contains no items, even though it has capacity for more - /// assert_eq!(vec.len(), 0); - /// assert!(vec.capacity() >= 10); - /// - /// // These are all done without reallocating... - /// for i in 0..10 { - /// vec.push(i); - /// } - /// assert_eq!(vec.len(), 10); - /// assert!(vec.capacity() >= 10); - /// - /// // ...but this may make the vector reallocate - /// vec.push(11); - /// assert_eq!(vec.len(), 11); - /// assert!(vec.capacity() >= 11); - /// - /// // A vector of a zero-sized type will always over-allocate, since no - /// // allocation is necessary - /// let vec_units = Vec::<(), System>::with_capacity_in(10, System); - /// assert_eq!(vec_units.capacity(), usize::MAX); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[inline] - #[unstable(feature = "allocator_api", issue = "32838")] - pub fn with_capacity_in(capacity: usize, alloc: A) -> Self { - Vec { buf: RawVec::with_capacity_in(capacity, alloc), len: 0 } - } - - /// Constructs a new, empty `Vec` with at least the specified capacity - /// with the provided allocator. - /// - /// The vector will be able to hold at least `capacity` elements without - /// reallocating. This method is allowed to allocate for more elements than - /// `capacity`. If `capacity` is 0, the vector will not allocate. - /// - /// # Errors - /// - /// Returns an error if the capacity exceeds `isize::MAX` _bytes_, - /// or if the allocator reports allocation failure. - #[inline] - #[unstable(feature = "allocator_api", issue = "32838")] - // #[unstable(feature = "try_with_capacity", issue = "91913")] - pub fn try_with_capacity_in(capacity: usize, alloc: A) -> Result { - Ok(Vec { buf: RawVec::try_with_capacity_in(capacity, alloc)?, len: 0 }) - } - - /// Creates a `Vec` directly from a pointer, a length, a capacity, - /// and an allocator. - /// - /// # Safety - /// - /// This is highly unsafe, due to the number of invariants that aren't - /// checked: - /// - /// * `ptr` must be [*currently allocated*] via the given allocator `alloc`. - /// * `T` needs to have the same alignment as what `ptr` was allocated with. - /// (`T` having a less strict alignment is not sufficient, the alignment really - /// needs to be equal to satisfy the [`dealloc`] requirement that memory must be - /// allocated and deallocated with the same layout.) - /// * The size of `T` times the `capacity` (ie. the allocated size in bytes) needs - /// to be the same size as the pointer was allocated with. (Because similar to - /// alignment, [`dealloc`] must be called with the same layout `size`.) - /// * `length` needs to be less than or equal to `capacity`. - /// * The first `length` values must be properly initialized values of type `T`. - /// * `capacity` needs to [*fit*] the layout size that the pointer was allocated with. - /// * The allocated size in bytes must be no larger than `isize::MAX`. - /// See the safety documentation of [`pointer::offset`]. - /// - /// These requirements are always upheld by any `ptr` that has been allocated - /// via `Vec`. Other allocation sources are allowed if the invariants are - /// upheld. - /// - /// Violating these may cause problems like corrupting the allocator's - /// internal data structures. For example it is **not** safe - /// to build a `Vec` from a pointer to a C `char` array with length `size_t`. - /// It's also not safe to build one from a `Vec` and its length, because - /// the allocator cares about the alignment, and these two types have different - /// alignments. The buffer was allocated with alignment 2 (for `u16`), but after - /// turning it into a `Vec` it'll be deallocated with alignment 1. - /// - /// The ownership of `ptr` is effectively transferred to the - /// `Vec` which may then deallocate, reallocate or change the - /// contents of memory pointed to by the pointer at will. Ensure - /// that nothing else uses the pointer after calling this - /// function. - /// - /// [`String`]: crate::string::String - /// [`dealloc`]: crate::alloc::GlobalAlloc::dealloc - /// [*currently allocated*]: crate::alloc::Allocator#currently-allocated-memory - /// [*fit*]: crate::alloc::Allocator#memory-fitting - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api)] - /// - /// use std::alloc::System; - /// - /// use std::ptr; - /// use std::mem; - /// - /// let mut v = Vec::with_capacity_in(3, System); - /// v.push(1); - /// v.push(2); - /// v.push(3); - /// - // FIXME Update this when vec_into_raw_parts is stabilized - /// // Prevent running `v`'s destructor so we are in complete control - /// // of the allocation. - /// let mut v = mem::ManuallyDrop::new(v); - /// - /// // Pull out the various important pieces of information about `v` - /// let p = v.as_mut_ptr(); - /// let len = v.len(); - /// let cap = v.capacity(); - /// let alloc = v.allocator(); - /// - /// unsafe { - /// // Overwrite memory with 4, 5, 6 - /// for i in 0..len { - /// ptr::write(p.add(i), 4 + i); - /// } - /// - /// // Put everything back together into a Vec - /// let rebuilt = Vec::from_raw_parts_in(p, len, cap, alloc.clone()); - /// assert_eq!(rebuilt, [4, 5, 6]); - /// } - /// ``` - /// - /// Using memory that was allocated elsewhere: - /// - /// ```rust - /// #![feature(allocator_api)] - /// - /// use std::alloc::{AllocError, Allocator, Global, Layout}; - /// - /// fn main() { - /// let layout = Layout::array::(16).expect("overflow cannot happen"); - /// - /// let vec = unsafe { - /// let mem = match Global.allocate(layout) { - /// Ok(mem) => mem.cast::().as_ptr(), - /// Err(AllocError) => return, - /// }; - /// - /// mem.write(1_000_000); - /// - /// Vec::from_raw_parts_in(mem, 1, 16, Global) - /// }; - /// - /// assert_eq!(vec, &[1_000_000]); - /// assert_eq!(vec.capacity(), 16); - /// } - /// ``` - #[inline] - #[unstable(feature = "allocator_api", issue = "32838")] - pub unsafe fn from_raw_parts_in(ptr: *mut T, length: usize, capacity: usize, alloc: A) -> Self { - unsafe { Vec { buf: RawVec::from_raw_parts_in(ptr, capacity, alloc), len: length } } - } - - /// A convenience method for hoisting the non-null precondition out of [`Vec::from_raw_parts_in`]. - /// - /// # Safety - /// - /// See [`Vec::from_raw_parts_in`]. - #[inline] - #[cfg(not(no_global_oom_handling))] // required by tests/run-make/alloc-no-oom-handling - pub(crate) unsafe fn from_nonnull_in( - ptr: NonNull, - length: usize, - capacity: usize, - alloc: A, - ) -> Self { - unsafe { Vec { buf: RawVec::from_nonnull_in(ptr, capacity, alloc), len: length } } - } - - /// Decomposes a `Vec` into its raw components: `(pointer, length, capacity)`. - /// - /// Returns the raw pointer to the underlying data, the length of - /// the vector (in elements), and the allocated capacity of the - /// data (in elements). These are the same arguments in the same - /// order as the arguments to [`from_raw_parts`]. - /// - /// After calling this function, the caller is responsible for the - /// memory previously managed by the `Vec`. The only way to do - /// this is to convert the raw pointer, length, and capacity back - /// into a `Vec` with the [`from_raw_parts`] function, allowing - /// the destructor to perform the cleanup. - /// - /// [`from_raw_parts`]: Vec::from_raw_parts - /// - /// # Examples - /// - /// ``` - /// #![feature(vec_into_raw_parts)] - /// let v: Vec = vec![-1, 0, 1]; - /// - /// let (ptr, len, cap) = v.into_raw_parts(); - /// - /// let rebuilt = unsafe { - /// // We can now make changes to the components, such as - /// // transmuting the raw pointer to a compatible type. - /// let ptr = ptr as *mut u32; - /// - /// Vec::from_raw_parts(ptr, len, cap) - /// }; - /// assert_eq!(rebuilt, [4294967295, 0, 1]); - /// ``` - #[unstable(feature = "vec_into_raw_parts", reason = "new API", issue = "65816")] - pub fn into_raw_parts(self) -> (*mut T, usize, usize) { - let mut me = ManuallyDrop::new(self); - (me.as_mut_ptr(), me.len(), me.capacity()) - } - - /// Decomposes a `Vec` into its raw components: `(pointer, length, capacity, allocator)`. - /// - /// Returns the raw pointer to the underlying data, the length of the vector (in elements), - /// the allocated capacity of the data (in elements), and the allocator. These are the same - /// arguments in the same order as the arguments to [`from_raw_parts_in`]. - /// - /// After calling this function, the caller is responsible for the - /// memory previously managed by the `Vec`. The only way to do - /// this is to convert the raw pointer, length, and capacity back - /// into a `Vec` with the [`from_raw_parts_in`] function, allowing - /// the destructor to perform the cleanup. - /// - /// [`from_raw_parts_in`]: Vec::from_raw_parts_in - /// - /// # Examples - /// - /// ``` - /// #![feature(allocator_api, vec_into_raw_parts)] - /// - /// use std::alloc::System; - /// - /// let mut v: Vec = Vec::new_in(System); - /// v.push(-1); - /// v.push(0); - /// v.push(1); - /// - /// let (ptr, len, cap, alloc) = v.into_raw_parts_with_alloc(); - /// - /// let rebuilt = unsafe { - /// // We can now make changes to the components, such as - /// // transmuting the raw pointer to a compatible type. - /// let ptr = ptr as *mut u32; - /// - /// Vec::from_raw_parts_in(ptr, len, cap, alloc) - /// }; - /// assert_eq!(rebuilt, [4294967295, 0, 1]); - /// ``` - #[unstable(feature = "allocator_api", issue = "32838")] - // #[unstable(feature = "vec_into_raw_parts", reason = "new API", issue = "65816")] - pub fn into_raw_parts_with_alloc(self) -> (*mut T, usize, usize, A) { - let mut me = ManuallyDrop::new(self); - let len = me.len(); - let capacity = me.capacity(); - let ptr = me.as_mut_ptr(); - let alloc = unsafe { ptr::read(me.allocator()) }; - (ptr, len, capacity, alloc) - } - - /// Returns the total number of elements the vector can hold without - /// reallocating. - /// - /// # Examples - /// - /// ``` - /// let mut vec: Vec = Vec::with_capacity(10); - /// vec.push(42); - /// assert!(vec.capacity() >= 10); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn capacity(&self) -> usize { - self.buf.capacity() - } - - /// Reserves capacity for at least `additional` more elements to be inserted - /// in the given `Vec`. The collection may reserve more space to - /// speculatively avoid frequent reallocations. After calling `reserve`, - /// capacity will be greater than or equal to `self.len() + additional`. - /// Does nothing if capacity is already sufficient. - /// - /// # Panics - /// - /// Panics if the new capacity exceeds `isize::MAX` _bytes_. - /// - /// # Examples - /// - /// ``` - /// let mut vec = vec![1]; - /// vec.reserve(10); - /// assert!(vec.capacity() >= 11); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn reserve(&mut self, additional: usize) { - self.buf.reserve(self.len, additional); - } - - /// Reserves the minimum capacity for at least `additional` more elements to - /// be inserted in the given `Vec`. Unlike [`reserve`], this will not - /// deliberately over-allocate to speculatively avoid frequent allocations. - /// After calling `reserve_exact`, capacity will be greater than or equal to - /// `self.len() + additional`. Does nothing if the capacity is already - /// sufficient. - /// - /// Note that the allocator may give the collection more space than it - /// requests. Therefore, capacity can not be relied upon to be precisely - /// minimal. Prefer [`reserve`] if future insertions are expected. - /// - /// [`reserve`]: Vec::reserve - /// - /// # Panics - /// - /// Panics if the new capacity exceeds `isize::MAX` _bytes_. - /// - /// # Examples - /// - /// ``` - /// let mut vec = vec![1]; - /// vec.reserve_exact(10); - /// assert!(vec.capacity() >= 11); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn reserve_exact(&mut self, additional: usize) { - self.buf.reserve_exact(self.len, additional); - } - - /// Tries to reserve capacity for at least `additional` more elements to be inserted - /// in the given `Vec`. The collection may reserve more space to speculatively avoid - /// frequent reallocations. After calling `try_reserve`, capacity will be - /// greater than or equal to `self.len() + additional` if it returns - /// `Ok(())`. Does nothing if capacity is already sufficient. This method - /// preserves the contents even if an error occurs. - /// - /// # Errors - /// - /// If the capacity overflows, or the allocator reports a failure, then an error - /// is returned. - /// - /// # Examples - /// - /// ``` - /// use std::collections::TryReserveError; - /// - /// fn process_data(data: &[u32]) -> Result, TryReserveError> { - /// let mut output = Vec::new(); - /// - /// // Pre-reserve the memory, exiting if we can't - /// output.try_reserve(data.len())?; - /// - /// // Now we know this can't OOM in the middle of our complex work - /// output.extend(data.iter().map(|&val| { - /// val * 2 + 5 // very complicated - /// })); - /// - /// Ok(output) - /// } - /// # process_data(&[1, 2, 3]).expect("why is the test harness OOMing on 12 bytes?"); - /// ``` - #[stable(feature = "try_reserve", since = "1.57.0")] - pub fn try_reserve(&mut self, additional: usize) -> Result<(), TryReserveError> { - self.buf.try_reserve(self.len, additional) - } - - /// Tries to reserve the minimum capacity for at least `additional` - /// elements to be inserted in the given `Vec`. Unlike [`try_reserve`], - /// this will not deliberately over-allocate to speculatively avoid frequent - /// allocations. After calling `try_reserve_exact`, capacity will be greater - /// than or equal to `self.len() + additional` if it returns `Ok(())`. - /// Does nothing if the capacity is already sufficient. - /// - /// Note that the allocator may give the collection more space than it - /// requests. Therefore, capacity can not be relied upon to be precisely - /// minimal. Prefer [`try_reserve`] if future insertions are expected. - /// - /// [`try_reserve`]: Vec::try_reserve - /// - /// # Errors - /// - /// If the capacity overflows, or the allocator reports a failure, then an error - /// is returned. - /// - /// # Examples - /// - /// ``` - /// use std::collections::TryReserveError; - /// - /// fn process_data(data: &[u32]) -> Result, TryReserveError> { - /// let mut output = Vec::new(); - /// - /// // Pre-reserve the memory, exiting if we can't - /// output.try_reserve_exact(data.len())?; - /// - /// // Now we know this can't OOM in the middle of our complex work - /// output.extend(data.iter().map(|&val| { - /// val * 2 + 5 // very complicated - /// })); - /// - /// Ok(output) - /// } - /// # process_data(&[1, 2, 3]).expect("why is the test harness OOMing on 12 bytes?"); - /// ``` - #[stable(feature = "try_reserve", since = "1.57.0")] - pub fn try_reserve_exact(&mut self, additional: usize) -> Result<(), TryReserveError> { - self.buf.try_reserve_exact(self.len, additional) - } - - /// Shrinks the capacity of the vector as much as possible. - /// - /// The behavior of this method depends on the allocator, which may either shrink the vector - /// in-place or reallocate. The resulting vector might still have some excess capacity, just as - /// is the case for [`with_capacity`]. See [`Allocator::shrink`] for more details. - /// - /// [`with_capacity`]: Vec::with_capacity - /// - /// # Examples - /// - /// ``` - /// let mut vec = Vec::with_capacity(10); - /// vec.extend([1, 2, 3]); - /// assert!(vec.capacity() >= 10); - /// vec.shrink_to_fit(); - /// assert!(vec.capacity() >= 3); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn shrink_to_fit(&mut self) { - // The capacity is never less than the length, and there's nothing to do when - // they are equal, so we can avoid the panic case in `RawVec::shrink_to_fit` - // by only calling it with a greater capacity. - if self.capacity() > self.len { - self.buf.shrink_to_fit(self.len); - } - } - - /// Shrinks the capacity of the vector with a lower bound. - /// - /// The capacity will remain at least as large as both the length - /// and the supplied value. - /// - /// If the current capacity is less than the lower limit, this is a no-op. - /// - /// # Examples - /// - /// ``` - /// let mut vec = Vec::with_capacity(10); - /// vec.extend([1, 2, 3]); - /// assert!(vec.capacity() >= 10); - /// vec.shrink_to(4); - /// assert!(vec.capacity() >= 4); - /// vec.shrink_to(0); - /// assert!(vec.capacity() >= 3); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[stable(feature = "shrink_to", since = "1.56.0")] - pub fn shrink_to(&mut self, min_capacity: usize) { - if self.capacity() > min_capacity { - self.buf.shrink_to_fit(cmp::max(self.len, min_capacity)); - } - } - - /// Converts the vector into [`Box<[T]>`][owned slice]. - /// - /// Before doing the conversion, this method discards excess capacity like [`shrink_to_fit`]. - /// - /// [owned slice]: Box - /// [`shrink_to_fit`]: Vec::shrink_to_fit - /// - /// # Examples - /// - /// ``` - /// let v = vec![1, 2, 3]; - /// - /// let slice = v.into_boxed_slice(); - /// ``` - /// - /// Any excess capacity is removed: - /// - /// ``` - /// let mut vec = Vec::with_capacity(10); - /// vec.extend([1, 2, 3]); - /// - /// assert!(vec.capacity() >= 10); - /// let slice = vec.into_boxed_slice(); - /// assert_eq!(slice.into_vec().capacity(), 3); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn into_boxed_slice(mut self) -> Box<[T], A> { - unsafe { - self.shrink_to_fit(); - let me = ManuallyDrop::new(self); - let buf = ptr::read(&me.buf); - let len = me.len(); - buf.into_box(len).assume_init() - } - } - - /// Shortens the vector, keeping the first `len` elements and dropping - /// the rest. - /// - /// If `len` is greater or equal to the vector's current length, this has - /// no effect. - /// - /// The [`drain`] method can emulate `truncate`, but causes the excess - /// elements to be returned instead of dropped. - /// - /// Note that this method has no effect on the allocated capacity - /// of the vector. - /// - /// # Examples - /// - /// Truncating a five element vector to two elements: - /// - /// ``` - /// let mut vec = vec![1, 2, 3, 4, 5]; - /// vec.truncate(2); - /// assert_eq!(vec, [1, 2]); - /// ``` - /// - /// No truncation occurs when `len` is greater than the vector's current - /// length: - /// - /// ``` - /// let mut vec = vec![1, 2, 3]; - /// vec.truncate(8); - /// assert_eq!(vec, [1, 2, 3]); - /// ``` - /// - /// Truncating when `len == 0` is equivalent to calling the [`clear`] - /// method. - /// - /// ``` - /// let mut vec = vec![1, 2, 3]; - /// vec.truncate(0); - /// assert_eq!(vec, []); - /// ``` - /// - /// [`clear`]: Vec::clear - /// [`drain`]: Vec::drain - #[stable(feature = "rust1", since = "1.0.0")] - pub fn truncate(&mut self, len: usize) { - // This is safe because: - // - // * the slice passed to `drop_in_place` is valid; the `len > self.len` - // case avoids creating an invalid slice, and - // * the `len` of the vector is shrunk before calling `drop_in_place`, - // such that no value will be dropped twice in case `drop_in_place` - // were to panic once (if it panics twice, the program aborts). - unsafe { - // Note: It's intentional that this is `>` and not `>=`. - // Changing it to `>=` has negative performance - // implications in some cases. See #78884 for more. - if len > self.len { - return; - } - let remaining_len = self.len - len; - let s = ptr::slice_from_raw_parts_mut(self.as_mut_ptr().add(len), remaining_len); - self.len = len; - ptr::drop_in_place(s); - } - } - - /// Extracts a slice containing the entire vector. - /// - /// Equivalent to `&s[..]`. - /// - /// # Examples - /// - /// ``` - /// use std::io::{self, Write}; - /// let buffer = vec![1, 2, 3, 5, 8]; - /// io::sink().write(buffer.as_slice()).unwrap(); - /// ``` - #[inline] - #[stable(feature = "vec_as_slice", since = "1.7.0")] - pub fn as_slice(&self) -> &[T] { - self - } - - /// Extracts a mutable slice of the entire vector. - /// - /// Equivalent to `&mut s[..]`. - /// - /// # Examples - /// - /// ``` - /// use std::io::{self, Read}; - /// let mut buffer = vec![0; 3]; - /// io::repeat(0b101).read_exact(buffer.as_mut_slice()).unwrap(); - /// ``` - #[inline] - #[stable(feature = "vec_as_slice", since = "1.7.0")] - pub fn as_mut_slice(&mut self) -> &mut [T] { - self - } - - /// Returns a raw pointer to the vector's buffer, or a dangling raw pointer - /// valid for zero sized reads if the vector didn't allocate. - /// - /// The caller must ensure that the vector outlives the pointer this - /// function returns, or else it will end up pointing to garbage. - /// Modifying the vector may cause its buffer to be reallocated, - /// which would also make any pointers to it invalid. - /// - /// The caller must also ensure that the memory the pointer (non-transitively) points to - /// is never written to (except inside an `UnsafeCell`) using this pointer or any pointer - /// derived from it. If you need to mutate the contents of the slice, use [`as_mut_ptr`]. - /// - /// This method guarantees that for the purpose of the aliasing model, this method - /// does not materialize a reference to the underlying slice, and thus the returned pointer - /// will remain valid when mixed with other calls to [`as_ptr`] and [`as_mut_ptr`]. - /// Note that calling other methods that materialize mutable references to the slice, - /// or mutable references to specific elements you are planning on accessing through this pointer, - /// as well as writing to those elements, may still invalidate this pointer. - /// See the second example below for how this guarantee can be used. - /// - /// - /// # Examples - /// - /// ``` - /// let x = vec![1, 2, 4]; - /// let x_ptr = x.as_ptr(); - /// - /// unsafe { - /// for i in 0..x.len() { - /// assert_eq!(*x_ptr.add(i), 1 << i); - /// } - /// } - /// ``` - /// - /// Due to the aliasing guarantee, the following code is legal: - /// - /// ```rust - /// unsafe { - /// let mut v = vec![0, 1, 2]; - /// let ptr1 = v.as_ptr(); - /// let _ = ptr1.read(); - /// let ptr2 = v.as_mut_ptr().offset(2); - /// ptr2.write(2); - /// // Notably, the write to `ptr2` did *not* invalidate `ptr1` - /// // because it mutated a different element: - /// let _ = ptr1.read(); - /// } - /// ``` - /// - /// [`as_mut_ptr`]: Vec::as_mut_ptr - /// [`as_ptr`]: Vec::as_ptr - #[stable(feature = "vec_as_ptr", since = "1.37.0")] - #[rustc_never_returns_null_ptr] - #[inline] - pub fn as_ptr(&self) -> *const T { - // We shadow the slice method of the same name to avoid going through - // `deref`, which creates an intermediate reference. - self.buf.ptr() - } - - /// Returns an unsafe mutable pointer to the vector's buffer, or a dangling - /// raw pointer valid for zero sized reads if the vector didn't allocate. - /// - /// The caller must ensure that the vector outlives the pointer this - /// function returns, or else it will end up pointing to garbage. - /// Modifying the vector may cause its buffer to be reallocated, - /// which would also make any pointers to it invalid. - /// - /// This method guarantees that for the purpose of the aliasing model, this method - /// does not materialize a reference to the underlying slice, and thus the returned pointer - /// will remain valid when mixed with other calls to [`as_ptr`] and [`as_mut_ptr`]. - /// Note that calling other methods that materialize references to the slice, - /// or references to specific elements you are planning on accessing through this pointer, - /// may still invalidate this pointer. - /// See the second example below for how this guarantee can be used. - /// - /// - /// # Examples - /// - /// ``` - /// // Allocate vector big enough for 4 elements. - /// let size = 4; - /// let mut x: Vec = Vec::with_capacity(size); - /// let x_ptr = x.as_mut_ptr(); - /// - /// // Initialize elements via raw pointer writes, then set length. - /// unsafe { - /// for i in 0..size { - /// *x_ptr.add(i) = i as i32; - /// } - /// x.set_len(size); - /// } - /// assert_eq!(&*x, &[0, 1, 2, 3]); - /// ``` - /// - /// Due to the aliasing guarantee, the following code is legal: - /// - /// ```rust - /// unsafe { - /// let mut v = vec![0]; - /// let ptr1 = v.as_mut_ptr(); - /// ptr1.write(1); - /// let ptr2 = v.as_mut_ptr(); - /// ptr2.write(2); - /// // Notably, the write to `ptr2` did *not* invalidate `ptr1`: - /// ptr1.write(3); - /// } - /// ``` - /// - /// [`as_mut_ptr`]: Vec::as_mut_ptr - /// [`as_ptr`]: Vec::as_ptr - #[stable(feature = "vec_as_ptr", since = "1.37.0")] - #[rustc_never_returns_null_ptr] - #[inline] - pub fn as_mut_ptr(&mut self) -> *mut T { - // We shadow the slice method of the same name to avoid going through - // `deref_mut`, which creates an intermediate reference. - self.buf.ptr() - } - - /// Returns a reference to the underlying allocator. - #[unstable(feature = "allocator_api", issue = "32838")] - #[inline] - pub fn allocator(&self) -> &A { - self.buf.allocator() - } - - /// Forces the length of the vector to `new_len`. - /// - /// This is a low-level operation that maintains none of the normal - /// invariants of the type. Normally changing the length of a vector - /// is done using one of the safe operations instead, such as - /// [`truncate`], [`resize`], [`extend`], or [`clear`]. - /// - /// [`truncate`]: Vec::truncate - /// [`resize`]: Vec::resize - /// [`extend`]: Extend::extend - /// [`clear`]: Vec::clear - /// - /// # Safety - /// - /// - `new_len` must be less than or equal to [`capacity()`]. - /// - The elements at `old_len..new_len` must be initialized. - /// - /// [`capacity()`]: Vec::capacity - /// - /// # Examples - /// - /// This method can be useful for situations in which the vector - /// is serving as a buffer for other code, particularly over FFI: - /// - /// ```no_run - /// # #![allow(dead_code)] - /// # // This is just a minimal skeleton for the doc example; - /// # // don't use this as a starting point for a real library. - /// # pub struct StreamWrapper { strm: *mut std::ffi::c_void } - /// # const Z_OK: i32 = 0; - /// # extern "C" { - /// # fn deflateGetDictionary( - /// # strm: *mut std::ffi::c_void, - /// # dictionary: *mut u8, - /// # dictLength: *mut usize, - /// # ) -> i32; - /// # } - /// # impl StreamWrapper { - /// pub fn get_dictionary(&self) -> Option> { - /// // Per the FFI method's docs, "32768 bytes is always enough". - /// let mut dict = Vec::with_capacity(32_768); - /// let mut dict_length = 0; - /// // SAFETY: When `deflateGetDictionary` returns `Z_OK`, it holds that: - /// // 1. `dict_length` elements were initialized. - /// // 2. `dict_length` <= the capacity (32_768) - /// // which makes `set_len` safe to call. - /// unsafe { - /// // Make the FFI call... - /// let r = deflateGetDictionary(self.strm, dict.as_mut_ptr(), &mut dict_length); - /// if r == Z_OK { - /// // ...and update the length to what was initialized. - /// dict.set_len(dict_length); - /// Some(dict) - /// } else { - /// None - /// } - /// } - /// } - /// # } - /// ``` - /// - /// While the following example is sound, there is a memory leak since - /// the inner vectors were not freed prior to the `set_len` call: - /// - /// ``` - /// let mut vec = vec![vec![1, 0, 0], - /// vec![0, 1, 0], - /// vec![0, 0, 1]]; - /// // SAFETY: - /// // 1. `old_len..0` is empty so no elements need to be initialized. - /// // 2. `0 <= capacity` always holds whatever `capacity` is. - /// unsafe { - /// vec.set_len(0); - /// } - /// ``` - /// - /// Normally, here, one would use [`clear`] instead to correctly drop - /// the contents and thus not leak memory. - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub unsafe fn set_len(&mut self, new_len: usize) { - debug_assert!(new_len <= self.capacity()); - - self.len = new_len; - } - - /// Removes an element from the vector and returns it. - /// - /// The removed element is replaced by the last element of the vector. - /// - /// This does not preserve ordering of the remaining elements, but is *O*(1). - /// If you need to preserve the element order, use [`remove`] instead. - /// - /// [`remove`]: Vec::remove - /// - /// # Panics - /// - /// Panics if `index` is out of bounds. - /// - /// # Examples - /// - /// ``` - /// let mut v = vec!["foo", "bar", "baz", "qux"]; - /// - /// assert_eq!(v.swap_remove(1), "bar"); - /// assert_eq!(v, ["foo", "qux", "baz"]); - /// - /// assert_eq!(v.swap_remove(0), "foo"); - /// assert_eq!(v, ["baz", "qux"]); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn swap_remove(&mut self, index: usize) -> T { - #[cold] - #[cfg_attr(not(feature = "panic_immediate_abort"), inline(never))] - #[track_caller] - fn assert_failed(index: usize, len: usize) -> ! { - panic!("swap_remove index (is {index}) should be < len (is {len})"); - } - - let len = self.len(); - if index >= len { - assert_failed(index, len); - } - unsafe { - // We replace self[index] with the last element. Note that if the - // bounds check above succeeds there must be a last element (which - // can be self[index] itself). - let value = ptr::read(self.as_ptr().add(index)); - let base_ptr = self.as_mut_ptr(); - ptr::copy(base_ptr.add(len - 1), base_ptr.add(index), 1); - self.set_len(len - 1); - value - } - } - - /// Inserts an element at position `index` within the vector, shifting all - /// elements after it to the right. - /// - /// # Panics - /// - /// Panics if `index > len`. - /// - /// # Examples - /// - /// ``` - /// let mut vec = vec![1, 2, 3]; - /// vec.insert(1, 4); - /// assert_eq!(vec, [1, 4, 2, 3]); - /// vec.insert(4, 5); - /// assert_eq!(vec, [1, 4, 2, 3, 5]); - /// ``` - /// - /// # Time complexity - /// - /// Takes *O*([`Vec::len`]) time. All items after the insertion index must be - /// shifted to the right. In the worst case, all elements are shifted when - /// the insertion index is 0. - #[cfg(not(no_global_oom_handling))] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn insert(&mut self, index: usize, element: T) { - #[cold] - #[cfg_attr(not(feature = "panic_immediate_abort"), inline(never))] - #[track_caller] - fn assert_failed(index: usize, len: usize) -> ! { - panic!("insertion index (is {index}) should be <= len (is {len})"); - } - - let len = self.len(); - if index > len { - assert_failed(index, len); - } - - // space for the new element - if len == self.buf.capacity() { - self.buf.grow_one(); - } - - unsafe { - // infallible - // The spot to put the new value - { - let p = self.as_mut_ptr().add(index); - if index < len { - // Shift everything over to make space. (Duplicating the - // `index`th element into two consecutive places.) - ptr::copy(p, p.add(1), len - index); - } - // Write it in, overwriting the first copy of the `index`th - // element. - ptr::write(p, element); - } - self.set_len(len + 1); - } - } - - /// Removes and returns the element at position `index` within the vector, - /// shifting all elements after it to the left. - /// - /// Note: Because this shifts over the remaining elements, it has a - /// worst-case performance of *O*(*n*). If you don't need the order of elements - /// to be preserved, use [`swap_remove`] instead. If you'd like to remove - /// elements from the beginning of the `Vec`, consider using - /// [`VecDeque::pop_front`] instead. - /// - /// [`swap_remove`]: Vec::swap_remove - /// [`VecDeque::pop_front`]: crate::collections::VecDeque::pop_front - /// - /// # Panics - /// - /// Panics if `index` is out of bounds. - /// - /// # Examples - /// - /// ``` - /// let mut v = vec![1, 2, 3]; - /// assert_eq!(v.remove(1), 2); - /// assert_eq!(v, [1, 3]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[track_caller] - #[rustc_confusables("delete", "take")] - pub fn remove(&mut self, index: usize) -> T { - #[cold] - #[cfg_attr(not(feature = "panic_immediate_abort"), inline(never))] - #[track_caller] - fn assert_failed(index: usize, len: usize) -> ! { - panic!("removal index (is {index}) should be < len (is {len})"); - } - - let len = self.len(); - if index >= len { - assert_failed(index, len); - } - unsafe { - // infallible - let ret; - { - // the place we are taking from. - let ptr = self.as_mut_ptr().add(index); - // copy it out, unsafely having a copy of the value on - // the stack and in the vector at the same time. - ret = ptr::read(ptr); - - // Shift everything down to fill in that spot. - ptr::copy(ptr.add(1), ptr, len - index - 1); - } - self.set_len(len - 1); - ret - } - } - - /// Retains only the elements specified by the predicate. - /// - /// In other words, remove all elements `e` for which `f(&e)` returns `false`. - /// This method operates in place, visiting each element exactly once in the - /// original order, and preserves the order of the retained elements. - /// - /// # Examples - /// - /// ``` - /// let mut vec = vec![1, 2, 3, 4]; - /// vec.retain(|&x| x % 2 == 0); - /// assert_eq!(vec, [2, 4]); - /// ``` - /// - /// Because the elements are visited exactly once in the original order, - /// external state may be used to decide which elements to keep. - /// - /// ``` - /// let mut vec = vec![1, 2, 3, 4, 5]; - /// let keep = [false, true, true, false, true]; - /// let mut iter = keep.iter(); - /// vec.retain(|_| *iter.next().unwrap()); - /// assert_eq!(vec, [2, 3, 5]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn retain(&mut self, mut f: F) - where - F: FnMut(&T) -> bool, - { - self.retain_mut(|elem| f(elem)); - } - - /// Retains only the elements specified by the predicate, passing a mutable reference to it. - /// - /// In other words, remove all elements `e` such that `f(&mut e)` returns `false`. - /// This method operates in place, visiting each element exactly once in the - /// original order, and preserves the order of the retained elements. - /// - /// # Examples - /// - /// ``` - /// let mut vec = vec![1, 2, 3, 4]; - /// vec.retain_mut(|x| if *x <= 3 { - /// *x += 1; - /// true - /// } else { - /// false - /// }); - /// assert_eq!(vec, [2, 3, 4]); - /// ``` - #[stable(feature = "vec_retain_mut", since = "1.61.0")] - pub fn retain_mut(&mut self, mut f: F) - where - F: FnMut(&mut T) -> bool, - { - let original_len = self.len(); - // Avoid double drop if the drop guard is not executed, - // since we may make some holes during the process. - unsafe { self.set_len(0) }; - - // Vec: [Kept, Kept, Hole, Hole, Hole, Hole, Unchecked, Unchecked] - // |<- processed len ->| ^- next to check - // |<- deleted cnt ->| - // |<- original_len ->| - // Kept: Elements which predicate returns true on. - // Hole: Moved or dropped element slot. - // Unchecked: Unchecked valid elements. - // - // This drop guard will be invoked when predicate or `drop` of element panicked. - // It shifts unchecked elements to cover holes and `set_len` to the correct length. - // In cases when predicate and `drop` never panick, it will be optimized out. - struct BackshiftOnDrop<'a, T, A: Allocator> { - v: &'a mut Vec, - processed_len: usize, - deleted_cnt: usize, - original_len: usize, - } - - impl Drop for BackshiftOnDrop<'_, T, A> { - fn drop(&mut self) { - if self.deleted_cnt > 0 { - // SAFETY: Trailing unchecked items must be valid since we never touch them. - unsafe { - ptr::copy( - self.v.as_ptr().add(self.processed_len), - self.v.as_mut_ptr().add(self.processed_len - self.deleted_cnt), - self.original_len - self.processed_len, - ); - } - } - // SAFETY: After filling holes, all items are in contiguous memory. - unsafe { - self.v.set_len(self.original_len - self.deleted_cnt); - } - } - } - - let mut g = BackshiftOnDrop { v: self, processed_len: 0, deleted_cnt: 0, original_len }; - - fn process_loop( - original_len: usize, - f: &mut F, - g: &mut BackshiftOnDrop<'_, T, A>, - ) where - F: FnMut(&mut T) -> bool, - { - while g.processed_len != original_len { - // SAFETY: Unchecked element must be valid. - let cur = unsafe { &mut *g.v.as_mut_ptr().add(g.processed_len) }; - if !f(cur) { - // Advance early to avoid double drop if `drop_in_place` panicked. - g.processed_len += 1; - g.deleted_cnt += 1; - // SAFETY: We never touch this element again after dropped. - unsafe { ptr::drop_in_place(cur) }; - // We already advanced the counter. - if DELETED { - continue; - } else { - break; - } - } - if DELETED { - // SAFETY: `deleted_cnt` > 0, so the hole slot must not overlap with current element. - // We use copy for move, and never touch this element again. - unsafe { - let hole_slot = g.v.as_mut_ptr().add(g.processed_len - g.deleted_cnt); - ptr::copy_nonoverlapping(cur, hole_slot, 1); - } - } - g.processed_len += 1; - } - } - - // Stage 1: Nothing was deleted. - process_loop::(original_len, &mut f, &mut g); - - // Stage 2: Some elements were deleted. - process_loop::(original_len, &mut f, &mut g); - - // All item are processed. This can be optimized to `set_len` by LLVM. - drop(g); - } - - /// Removes all but the first of consecutive elements in the vector that resolve to the same - /// key. - /// - /// If the vector is sorted, this removes all duplicates. - /// - /// # Examples - /// - /// ``` - /// let mut vec = vec![10, 20, 21, 30, 20]; - /// - /// vec.dedup_by_key(|i| *i / 10); - /// - /// assert_eq!(vec, [10, 20, 30, 20]); - /// ``` - #[stable(feature = "dedup_by", since = "1.16.0")] - #[inline] - pub fn dedup_by_key(&mut self, mut key: F) - where - F: FnMut(&mut T) -> K, - K: PartialEq, - { - self.dedup_by(|a, b| key(a) == key(b)) - } - - /// Removes all but the first of consecutive elements in the vector satisfying a given equality - /// relation. - /// - /// The `same_bucket` function is passed references to two elements from the vector and - /// must determine if the elements compare equal. The elements are passed in opposite order - /// from their order in the slice, so if `same_bucket(a, b)` returns `true`, `a` is removed. - /// - /// If the vector is sorted, this removes all duplicates. - /// - /// # Examples - /// - /// ``` - /// let mut vec = vec!["foo", "bar", "Bar", "baz", "bar"]; - /// - /// vec.dedup_by(|a, b| a.eq_ignore_ascii_case(b)); - /// - /// assert_eq!(vec, ["foo", "bar", "baz", "bar"]); - /// ``` - #[stable(feature = "dedup_by", since = "1.16.0")] - pub fn dedup_by(&mut self, mut same_bucket: F) - where - F: FnMut(&mut T, &mut T) -> bool, - { - let len = self.len(); - if len <= 1 { - return; - } - - // Check if we ever want to remove anything. - // This allows to use copy_non_overlapping in next cycle. - // And avoids any memory writes if we don't need to remove anything. - let mut first_duplicate_idx: usize = 1; - let start = self.as_mut_ptr(); - while first_duplicate_idx != len { - let found_duplicate = unsafe { - // SAFETY: first_duplicate always in range [1..len) - // Note that we start iteration from 1 so we never overflow. - let prev = start.add(first_duplicate_idx.wrapping_sub(1)); - let current = start.add(first_duplicate_idx); - // We explicitly say in docs that references are reversed. - same_bucket(&mut *current, &mut *prev) - }; - if found_duplicate { - break; - } - first_duplicate_idx += 1; - } - // Don't need to remove anything. - // We cannot get bigger than len. - if first_duplicate_idx == len { - return; - } - - /* INVARIANT: vec.len() > read > write > write-1 >= 0 */ - struct FillGapOnDrop<'a, T, A: core::alloc::Allocator> { - /* Offset of the element we want to check if it is duplicate */ - read: usize, - - /* Offset of the place where we want to place the non-duplicate - * when we find it. */ - write: usize, - - /* The Vec that would need correction if `same_bucket` panicked */ - vec: &'a mut Vec, - } - - impl<'a, T, A: core::alloc::Allocator> Drop for FillGapOnDrop<'a, T, A> { - fn drop(&mut self) { - /* This code gets executed when `same_bucket` panics */ - - /* SAFETY: invariant guarantees that `read - write` - * and `len - read` never overflow and that the copy is always - * in-bounds. */ - unsafe { - let ptr = self.vec.as_mut_ptr(); - let len = self.vec.len(); - - /* How many items were left when `same_bucket` panicked. - * Basically vec[read..].len() */ - let items_left = len.wrapping_sub(self.read); - - /* Pointer to first item in vec[write..write+items_left] slice */ - let dropped_ptr = ptr.add(self.write); - /* Pointer to first item in vec[read..] slice */ - let valid_ptr = ptr.add(self.read); - - /* Copy `vec[read..]` to `vec[write..write+items_left]`. - * The slices can overlap, so `copy_nonoverlapping` cannot be used */ - ptr::copy(valid_ptr, dropped_ptr, items_left); - - /* How many items have been already dropped - * Basically vec[read..write].len() */ - let dropped = self.read.wrapping_sub(self.write); - - self.vec.set_len(len - dropped); - } - } - } - - /* Drop items while going through Vec, it should be more efficient than - * doing slice partition_dedup + truncate */ - - // Construct gap first and then drop item to avoid memory corruption if `T::drop` panics. - let mut gap = - FillGapOnDrop { read: first_duplicate_idx + 1, write: first_duplicate_idx, vec: self }; - unsafe { - // SAFETY: we checked that first_duplicate_idx in bounds before. - // If drop panics, `gap` would remove this item without drop. - ptr::drop_in_place(start.add(first_duplicate_idx)); - } - - /* SAFETY: Because of the invariant, read_ptr, prev_ptr and write_ptr - * are always in-bounds and read_ptr never aliases prev_ptr */ - unsafe { - while gap.read < len { - let read_ptr = start.add(gap.read); - let prev_ptr = start.add(gap.write.wrapping_sub(1)); - - // We explicitly say in docs that references are reversed. - let found_duplicate = same_bucket(&mut *read_ptr, &mut *prev_ptr); - if found_duplicate { - // Increase `gap.read` now since the drop may panic. - gap.read += 1; - /* We have found duplicate, drop it in-place */ - ptr::drop_in_place(read_ptr); - } else { - let write_ptr = start.add(gap.write); - - /* read_ptr cannot be equal to write_ptr because at this point - * we guaranteed to skip at least one element (before loop starts). - */ - ptr::copy_nonoverlapping(read_ptr, write_ptr, 1); - - /* We have filled that place, so go further */ - gap.write += 1; - gap.read += 1; - } - } - - /* Technically we could let `gap` clean up with its Drop, but - * when `same_bucket` is guaranteed to not panic, this bloats a little - * the codegen, so we just do it manually */ - gap.vec.set_len(gap.write); - mem::forget(gap); - } - } - - /// Appends an element to the back of a collection. - /// - /// # Panics - /// - /// Panics if the new capacity exceeds `isize::MAX` _bytes_. - /// - /// # Examples - /// - /// ``` - /// let mut vec = vec![1, 2]; - /// vec.push(3); - /// assert_eq!(vec, [1, 2, 3]); - /// ``` - /// - /// # Time complexity - /// - /// Takes amortized *O*(1) time. If the vector's length would exceed its - /// capacity after the push, *O*(*capacity*) time is taken to copy the - /// vector's elements to a larger allocation. This expensive operation is - /// offset by the *capacity* *O*(1) insertions it allows. - #[cfg(not(no_global_oom_handling))] - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("push_back", "put", "append")] - pub fn push(&mut self, value: T) { - // Inform codegen that the length does not change across grow_one(). - let len = self.len; - // This will panic or abort if we would allocate > isize::MAX bytes - // or if the length increment would overflow for zero-sized types. - if len == self.buf.capacity() { - self.buf.grow_one(); - } - unsafe { - let end = self.as_mut_ptr().add(len); - ptr::write(end, value); - self.len = len + 1; - } - } - - /// Appends an element if there is sufficient spare capacity, otherwise an error is returned - /// with the element. - /// - /// Unlike [`push`] this method will not reallocate when there's insufficient capacity. - /// The caller should use [`reserve`] or [`try_reserve`] to ensure that there is enough capacity. - /// - /// [`push`]: Vec::push - /// [`reserve`]: Vec::reserve - /// [`try_reserve`]: Vec::try_reserve - /// - /// # Examples - /// - /// A manual, panic-free alternative to [`FromIterator`]: - /// - /// ``` - /// #![feature(vec_push_within_capacity)] - /// - /// use std::collections::TryReserveError; - /// fn from_iter_fallible(iter: impl Iterator) -> Result, TryReserveError> { - /// let mut vec = Vec::new(); - /// for value in iter { - /// if let Err(value) = vec.push_within_capacity(value) { - /// vec.try_reserve(1)?; - /// // this cannot fail, the previous line either returned or added at least 1 free slot - /// let _ = vec.push_within_capacity(value); - /// } - /// } - /// Ok(vec) - /// } - /// assert_eq!(from_iter_fallible(0..100), Ok(Vec::from_iter(0..100))); - /// ``` - /// - /// # Time complexity - /// - /// Takes *O*(1) time. - #[inline] - #[unstable(feature = "vec_push_within_capacity", issue = "100486")] - pub fn push_within_capacity(&mut self, value: T) -> Result<(), T> { - if self.len == self.buf.capacity() { - return Err(value); - } - unsafe { - let end = self.as_mut_ptr().add(self.len); - ptr::write(end, value); - self.len += 1; - } - Ok(()) - } - - /// Removes the last element from a vector and returns it, or [`None`] if it - /// is empty. - /// - /// If you'd like to pop the first element, consider using - /// [`VecDeque::pop_front`] instead. - /// - /// [`VecDeque::pop_front`]: crate::collections::VecDeque::pop_front - /// - /// # Examples - /// - /// ``` - /// let mut vec = vec![1, 2, 3]; - /// assert_eq!(vec.pop(), Some(3)); - /// assert_eq!(vec, [1, 2]); - /// ``` - /// - /// # Time complexity - /// - /// Takes *O*(1) time. - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn pop(&mut self) -> Option { - if self.len == 0 { - None - } else { - unsafe { - self.len -= 1; - core::hint::assert_unchecked(self.len < self.capacity()); - Some(ptr::read(self.as_ptr().add(self.len()))) - } - } - } - - /// Removes and returns the last element in a vector if the predicate - /// returns `true`, or [`None`] if the predicate returns false or the vector - /// is empty. - /// - /// # Examples - /// - /// ``` - /// #![feature(vec_pop_if)] - /// - /// let mut vec = vec![1, 2, 3, 4]; - /// let pred = |x: &mut i32| *x % 2 == 0; - /// - /// assert_eq!(vec.pop_if(pred), Some(4)); - /// assert_eq!(vec, [1, 2, 3]); - /// assert_eq!(vec.pop_if(pred), None); - /// ``` - #[unstable(feature = "vec_pop_if", issue = "122741")] - pub fn pop_if(&mut self, f: F) -> Option - where - F: FnOnce(&mut T) -> bool, - { - let last = self.last_mut()?; - if f(last) { self.pop() } else { None } - } - - /// Moves all the elements of `other` into `self`, leaving `other` empty. - /// - /// # Panics - /// - /// Panics if the new capacity exceeds `isize::MAX` _bytes_. - /// - /// # Examples - /// - /// ``` - /// let mut vec = vec![1, 2, 3]; - /// let mut vec2 = vec![4, 5, 6]; - /// vec.append(&mut vec2); - /// assert_eq!(vec, [1, 2, 3, 4, 5, 6]); - /// assert_eq!(vec2, []); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[inline] - #[stable(feature = "append", since = "1.4.0")] - pub fn append(&mut self, other: &mut Self) { - unsafe { - self.append_elements(other.as_slice() as _); - other.set_len(0); - } - } - - /// Appends elements to `self` from other buffer. - #[cfg(not(no_global_oom_handling))] - #[inline] - unsafe fn append_elements(&mut self, other: *const [T]) { - let count = unsafe { (*other).len() }; - self.reserve(count); - let len = self.len(); - unsafe { ptr::copy_nonoverlapping(other as *const T, self.as_mut_ptr().add(len), count) }; - self.len += count; - } - - /// Removes the specified range from the vector in bulk, returning all - /// removed elements as an iterator. If the iterator is dropped before - /// being fully consumed, it drops the remaining removed elements. - /// - /// The returned iterator keeps a mutable borrow on the vector to optimize - /// its implementation. - /// - /// # Panics - /// - /// Panics if the starting point is greater than the end point or if - /// the end point is greater than the length of the vector. - /// - /// # Leaking - /// - /// If the returned iterator goes out of scope without being dropped (due to - /// [`mem::forget`], for example), the vector may have lost and leaked - /// elements arbitrarily, including elements outside the range. - /// - /// # Examples - /// - /// ``` - /// let mut v = vec![1, 2, 3]; - /// let u: Vec<_> = v.drain(1..).collect(); - /// assert_eq!(v, &[1]); - /// assert_eq!(u, &[2, 3]); - /// - /// // A full range clears the vector, like `clear()` does - /// v.drain(..); - /// assert_eq!(v, &[]); - /// ``` - #[stable(feature = "drain", since = "1.6.0")] - pub fn drain(&mut self, range: R) -> Drain<'_, T, A> - where - R: RangeBounds, - { - // Memory safety - // - // When the Drain is first created, it shortens the length of - // the source vector to make sure no uninitialized or moved-from elements - // are accessible at all if the Drain's destructor never gets to run. - // - // Drain will ptr::read out the values to remove. - // When finished, remaining tail of the vec is copied back to cover - // the hole, and the vector length is restored to the new length. - // - let len = self.len(); - let Range { start, end } = slice::range(range, ..len); - - unsafe { - // set self.vec length's to start, to be safe in case Drain is leaked - self.set_len(start); - let range_slice = slice::from_raw_parts(self.as_ptr().add(start), end - start); - Drain { - tail_start: end, - tail_len: len - end, - iter: range_slice.iter(), - vec: NonNull::from(self), - } - } - } - - /// Clears the vector, removing all values. - /// - /// Note that this method has no effect on the allocated capacity - /// of the vector. - /// - /// # Examples - /// - /// ``` - /// let mut v = vec![1, 2, 3]; - /// - /// v.clear(); - /// - /// assert!(v.is_empty()); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - pub fn clear(&mut self) { - let elems: *mut [T] = self.as_mut_slice(); - - // SAFETY: - // - `elems` comes directly from `as_mut_slice` and is therefore valid. - // - Setting `self.len` before calling `drop_in_place` means that, - // if an element's `Drop` impl panics, the vector's `Drop` impl will - // do nothing (leaking the rest of the elements) instead of dropping - // some twice. - unsafe { - self.len = 0; - ptr::drop_in_place(elems); - } - } - - /// Returns the number of elements in the vector, also referred to - /// as its 'length'. - /// - /// # Examples - /// - /// ``` - /// let a = vec![1, 2, 3]; - /// assert_eq!(a.len(), 3); - /// ``` - #[inline] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_confusables("length", "size")] - pub fn len(&self) -> usize { - self.len - } - - /// Returns `true` if the vector contains no elements. - /// - /// # Examples - /// - /// ``` - /// let mut v = Vec::new(); - /// assert!(v.is_empty()); - /// - /// v.push(1); - /// assert!(!v.is_empty()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - pub fn is_empty(&self) -> bool { - self.len() == 0 - } - - /// Splits the collection into two at the given index. - /// - /// Returns a newly allocated vector containing the elements in the range - /// `[at, len)`. After the call, the original vector will be left containing - /// the elements `[0, at)` with its previous capacity unchanged. - /// - /// - If you want to take ownership of the entire contents and capacity of - /// the vector, see [`mem::take`] or [`mem::replace`]. - /// - If you don't need the returned vector at all, see [`Vec::truncate`]. - /// - If you want to take ownership of an arbitrary subslice, or you don't - /// necessarily want to store the removed items in a vector, see [`Vec::drain`]. - /// - /// # Panics - /// - /// Panics if `at > len`. - /// - /// # Examples - /// - /// ``` - /// let mut vec = vec![1, 2, 3]; - /// let vec2 = vec.split_off(1); - /// assert_eq!(vec, [1]); - /// assert_eq!(vec2, [2, 3]); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[inline] - #[must_use = "use `.truncate()` if you don't need the other half"] - #[stable(feature = "split_off", since = "1.4.0")] - pub fn split_off(&mut self, at: usize) -> Self - where - A: Clone, - { - #[cold] - #[cfg_attr(not(feature = "panic_immediate_abort"), inline(never))] - #[track_caller] - fn assert_failed(at: usize, len: usize) -> ! { - panic!("`at` split index (is {at}) should be <= len (is {len})"); - } - - if at > self.len() { - assert_failed(at, self.len()); - } - - let other_len = self.len - at; - let mut other = Vec::with_capacity_in(other_len, self.allocator().clone()); - - // Unsafely `set_len` and copy items to `other`. - unsafe { - self.set_len(at); - other.set_len(other_len); - - ptr::copy_nonoverlapping(self.as_ptr().add(at), other.as_mut_ptr(), other.len()); - } - other - } - - /// Resizes the `Vec` in-place so that `len` is equal to `new_len`. - /// - /// If `new_len` is greater than `len`, the `Vec` is extended by the - /// difference, with each additional slot filled with the result of - /// calling the closure `f`. The return values from `f` will end up - /// in the `Vec` in the order they have been generated. - /// - /// If `new_len` is less than `len`, the `Vec` is simply truncated. - /// - /// This method uses a closure to create new values on every push. If - /// you'd rather [`Clone`] a given value, use [`Vec::resize`]. If you - /// want to use the [`Default`] trait to generate values, you can - /// pass [`Default::default`] as the second argument. - /// - /// # Examples - /// - /// ``` - /// let mut vec = vec![1, 2, 3]; - /// vec.resize_with(5, Default::default); - /// assert_eq!(vec, [1, 2, 3, 0, 0]); - /// - /// let mut vec = vec![]; - /// let mut p = 1; - /// vec.resize_with(4, || { p *= 2; p }); - /// assert_eq!(vec, [2, 4, 8, 16]); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[stable(feature = "vec_resize_with", since = "1.33.0")] - pub fn resize_with(&mut self, new_len: usize, f: F) - where - F: FnMut() -> T, - { - let len = self.len(); - if new_len > len { - self.extend_trusted(iter::repeat_with(f).take(new_len - len)); - } else { - self.truncate(new_len); - } - } - - /// Consumes and leaks the `Vec`, returning a mutable reference to the contents, - /// `&'a mut [T]`. Note that the type `T` must outlive the chosen lifetime - /// `'a`. If the type has only static references, or none at all, then this - /// may be chosen to be `'static`. - /// - /// As of Rust 1.57, this method does not reallocate or shrink the `Vec`, - /// so the leaked allocation may include unused capacity that is not part - /// of the returned slice. - /// - /// This function is mainly useful for data that lives for the remainder of - /// the program's life. Dropping the returned reference will cause a memory - /// leak. - /// - /// # Examples - /// - /// Simple usage: - /// - /// ``` - /// let x = vec![1, 2, 3]; - /// let static_ref: &'static mut [usize] = x.leak(); - /// static_ref[0] += 1; - /// assert_eq!(static_ref, &[2, 2, 3]); - /// ``` - #[stable(feature = "vec_leak", since = "1.47.0")] - #[inline] - pub fn leak<'a>(self) -> &'a mut [T] - where - A: 'a, - { - let mut me = ManuallyDrop::new(self); - unsafe { slice::from_raw_parts_mut(me.as_mut_ptr(), me.len) } - } - - /// Returns the remaining spare capacity of the vector as a slice of - /// `MaybeUninit`. - /// - /// The returned slice can be used to fill the vector with data (e.g. by - /// reading from a file) before marking the data as initialized using the - /// [`set_len`] method. - /// - /// [`set_len`]: Vec::set_len - /// - /// # Examples - /// - /// ``` - /// // Allocate vector big enough for 10 elements. - /// let mut v = Vec::with_capacity(10); - /// - /// // Fill in the first 3 elements. - /// let uninit = v.spare_capacity_mut(); - /// uninit[0].write(0); - /// uninit[1].write(1); - /// uninit[2].write(2); - /// - /// // Mark the first 3 elements of the vector as being initialized. - /// unsafe { - /// v.set_len(3); - /// } - /// - /// assert_eq!(&v, &[0, 1, 2]); - /// ``` - #[stable(feature = "vec_spare_capacity", since = "1.60.0")] - #[inline] - pub fn spare_capacity_mut(&mut self) -> &mut [MaybeUninit] { - // Note: - // This method is not implemented in terms of `split_at_spare_mut`, - // to prevent invalidation of pointers to the buffer. - unsafe { - slice::from_raw_parts_mut( - self.as_mut_ptr().add(self.len) as *mut MaybeUninit, - self.buf.capacity() - self.len, - ) - } - } - - /// Returns vector content as a slice of `T`, along with the remaining spare - /// capacity of the vector as a slice of `MaybeUninit`. - /// - /// The returned spare capacity slice can be used to fill the vector with data - /// (e.g. by reading from a file) before marking the data as initialized using - /// the [`set_len`] method. - /// - /// [`set_len`]: Vec::set_len - /// - /// Note that this is a low-level API, which should be used with care for - /// optimization purposes. If you need to append data to a `Vec` - /// you can use [`push`], [`extend`], [`extend_from_slice`], - /// [`extend_from_within`], [`insert`], [`append`], [`resize`] or - /// [`resize_with`], depending on your exact needs. - /// - /// [`push`]: Vec::push - /// [`extend`]: Vec::extend - /// [`extend_from_slice`]: Vec::extend_from_slice - /// [`extend_from_within`]: Vec::extend_from_within - /// [`insert`]: Vec::insert - /// [`append`]: Vec::append - /// [`resize`]: Vec::resize - /// [`resize_with`]: Vec::resize_with - /// - /// # Examples - /// - /// ``` - /// #![feature(vec_split_at_spare)] - /// - /// let mut v = vec![1, 1, 2]; - /// - /// // Reserve additional space big enough for 10 elements. - /// v.reserve(10); - /// - /// let (init, uninit) = v.split_at_spare_mut(); - /// let sum = init.iter().copied().sum::(); - /// - /// // Fill in the next 4 elements. - /// uninit[0].write(sum); - /// uninit[1].write(sum * 2); - /// uninit[2].write(sum * 3); - /// uninit[3].write(sum * 4); - /// - /// // Mark the 4 elements of the vector as being initialized. - /// unsafe { - /// let len = v.len(); - /// v.set_len(len + 4); - /// } - /// - /// assert_eq!(&v, &[1, 1, 2, 4, 8, 12, 16]); - /// ``` - #[unstable(feature = "vec_split_at_spare", issue = "81944")] - #[inline] - pub fn split_at_spare_mut(&mut self) -> (&mut [T], &mut [MaybeUninit]) { - // SAFETY: - // - len is ignored and so never changed - let (init, spare, _) = unsafe { self.split_at_spare_mut_with_len() }; - (init, spare) - } - - /// Safety: changing returned .2 (&mut usize) is considered the same as calling `.set_len(_)`. - /// - /// This method provides unique access to all vec parts at once in `extend_from_within`. - unsafe fn split_at_spare_mut_with_len( - &mut self, - ) -> (&mut [T], &mut [MaybeUninit], &mut usize) { - let ptr = self.as_mut_ptr(); - // SAFETY: - // - `ptr` is guaranteed to be valid for `self.len` elements - // - but the allocation extends out to `self.buf.capacity()` elements, possibly - // uninitialized - let spare_ptr = unsafe { ptr.add(self.len) }; - let spare_ptr = spare_ptr.cast::>(); - let spare_len = self.buf.capacity() - self.len; - - // SAFETY: - // - `ptr` is guaranteed to be valid for `self.len` elements - // - `spare_ptr` is pointing one element past the buffer, so it doesn't overlap with `initialized` - unsafe { - let initialized = slice::from_raw_parts_mut(ptr, self.len); - let spare = slice::from_raw_parts_mut(spare_ptr, spare_len); - - (initialized, spare, &mut self.len) - } - } -} - -impl Vec { - /// Resizes the `Vec` in-place so that `len` is equal to `new_len`. - /// - /// If `new_len` is greater than `len`, the `Vec` is extended by the - /// difference, with each additional slot filled with `value`. - /// If `new_len` is less than `len`, the `Vec` is simply truncated. - /// - /// This method requires `T` to implement [`Clone`], - /// in order to be able to clone the passed value. - /// If you need more flexibility (or want to rely on [`Default`] instead of - /// [`Clone`]), use [`Vec::resize_with`]. - /// If you only need to resize to a smaller size, use [`Vec::truncate`]. - /// - /// # Examples - /// - /// ``` - /// let mut vec = vec!["hello"]; - /// vec.resize(3, "world"); - /// assert_eq!(vec, ["hello", "world", "world"]); - /// - /// let mut vec = vec![1, 2, 3, 4]; - /// vec.resize(2, 0); - /// assert_eq!(vec, [1, 2]); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[stable(feature = "vec_resize", since = "1.5.0")] - pub fn resize(&mut self, new_len: usize, value: T) { - let len = self.len(); - - if new_len > len { - self.extend_with(new_len - len, value) - } else { - self.truncate(new_len); - } - } - - /// Clones and appends all elements in a slice to the `Vec`. - /// - /// Iterates over the slice `other`, clones each element, and then appends - /// it to this `Vec`. The `other` slice is traversed in-order. - /// - /// Note that this function is same as [`extend`] except that it is - /// specialized to work with slices instead. If and when Rust gets - /// specialization this function will likely be deprecated (but still - /// available). - /// - /// # Examples - /// - /// ``` - /// let mut vec = vec![1]; - /// vec.extend_from_slice(&[2, 3, 4]); - /// assert_eq!(vec, [1, 2, 3, 4]); - /// ``` - /// - /// [`extend`]: Vec::extend - #[cfg(not(no_global_oom_handling))] - #[stable(feature = "vec_extend_from_slice", since = "1.6.0")] - pub fn extend_from_slice(&mut self, other: &[T]) { - self.spec_extend(other.iter()) - } - - /// Copies elements from `src` range to the end of the vector. - /// - /// # Panics - /// - /// Panics if the starting point is greater than the end point or if - /// the end point is greater than the length of the vector. - /// - /// # Examples - /// - /// ``` - /// let mut vec = vec![0, 1, 2, 3, 4]; - /// - /// vec.extend_from_within(2..); - /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4]); - /// - /// vec.extend_from_within(..2); - /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1]); - /// - /// vec.extend_from_within(4..8); - /// assert_eq!(vec, [0, 1, 2, 3, 4, 2, 3, 4, 0, 1, 4, 2, 3, 4]); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[stable(feature = "vec_extend_from_within", since = "1.53.0")] - pub fn extend_from_within(&mut self, src: R) - where - R: RangeBounds, - { - let range = slice::range(src, ..self.len()); - self.reserve(range.len()); - - // SAFETY: - // - `slice::range` guarantees that the given range is valid for indexing self - unsafe { - self.spec_extend_from_within(range); - } - } -} - -impl Vec<[T; N], A> { - /// Takes a `Vec<[T; N]>` and flattens it into a `Vec`. - /// - /// # Panics - /// - /// Panics if the length of the resulting vector would overflow a `usize`. - /// - /// This is only possible when flattening a vector of arrays of zero-sized - /// types, and thus tends to be irrelevant in practice. If - /// `size_of::() > 0`, this will never panic. - /// - /// # Examples - /// - /// ``` - /// #![feature(slice_flatten)] - /// - /// let mut vec = vec![[1, 2, 3], [4, 5, 6], [7, 8, 9]]; - /// assert_eq!(vec.pop(), Some([7, 8, 9])); - /// - /// let mut flattened = vec.into_flattened(); - /// assert_eq!(flattened.pop(), Some(6)); - /// ``` - #[unstable(feature = "slice_flatten", issue = "95629")] - pub fn into_flattened(self) -> Vec { - let (ptr, len, cap, alloc) = self.into_raw_parts_with_alloc(); - let (new_len, new_cap) = if T::IS_ZST { - (len.checked_mul(N).expect("vec len overflow"), usize::MAX) - } else { - // SAFETY: - // - `cap * N` cannot overflow because the allocation is already in - // the address space. - // - Each `[T; N]` has `N` valid elements, so there are `len * N` - // valid elements in the allocation. - unsafe { (len.unchecked_mul(N), cap.unchecked_mul(N)) } - }; - // SAFETY: - // - `ptr` was allocated by `self` - // - `ptr` is well-aligned because `[T; N]` has the same alignment as `T`. - // - `new_cap` refers to the same sized allocation as `cap` because - // `new_cap * size_of::()` == `cap * size_of::<[T; N]>()` - // - `len` <= `cap`, so `len * N` <= `cap * N`. - unsafe { Vec::::from_raw_parts_in(ptr.cast(), new_len, new_cap, alloc) } - } -} - -impl Vec { - #[cfg(not(no_global_oom_handling))] - /// Extend the vector by `n` clones of value. - fn extend_with(&mut self, n: usize, value: T) { - self.reserve(n); - - unsafe { - let mut ptr = self.as_mut_ptr().add(self.len()); - // Use SetLenOnDrop to work around bug where compiler - // might not realize the store through `ptr` through self.set_len() - // don't alias. - let mut local_len = SetLenOnDrop::new(&mut self.len); - - // Write all elements except the last one - for _ in 1..n { - ptr::write(ptr, value.clone()); - ptr = ptr.add(1); - // Increment the length in every step in case clone() panics - local_len.increment_len(1); - } - - if n > 0 { - // We can write the last element directly without cloning needlessly - ptr::write(ptr, value); - local_len.increment_len(1); - } - - // len set by scope guard - } - } -} - -impl Vec { - /// Removes consecutive repeated elements in the vector according to the - /// [`PartialEq`] trait implementation. - /// - /// If the vector is sorted, this removes all duplicates. - /// - /// # Examples - /// - /// ``` - /// let mut vec = vec![1, 2, 2, 3, 2]; - /// - /// vec.dedup(); - /// - /// assert_eq!(vec, [1, 2, 3, 2]); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn dedup(&mut self) { - self.dedup_by(|a, b| a == b) - } -} - -//////////////////////////////////////////////////////////////////////////////// -// Internal methods and functions -//////////////////////////////////////////////////////////////////////////////// - -#[doc(hidden)] -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -pub fn from_elem(elem: T, n: usize) -> Vec { - ::from_elem(elem, n, Global) -} - -#[doc(hidden)] -#[cfg(not(no_global_oom_handling))] -#[unstable(feature = "allocator_api", issue = "32838")] -pub fn from_elem_in(elem: T, n: usize, alloc: A) -> Vec { - ::from_elem(elem, n, alloc) -} - -#[cfg(not(no_global_oom_handling))] -trait ExtendFromWithinSpec { - /// # Safety - /// - /// - `src` needs to be valid index - /// - `self.capacity() - self.len()` must be `>= src.len()` - unsafe fn spec_extend_from_within(&mut self, src: Range); -} - -#[cfg(not(no_global_oom_handling))] -impl ExtendFromWithinSpec for Vec { - default unsafe fn spec_extend_from_within(&mut self, src: Range) { - // SAFETY: - // - len is increased only after initializing elements - let (this, spare, len) = unsafe { self.split_at_spare_mut_with_len() }; - - // SAFETY: - // - caller guarantees that src is a valid index - let to_clone = unsafe { this.get_unchecked(src) }; - - iter::zip(to_clone, spare) - .map(|(src, dst)| dst.write(src.clone())) - // Note: - // - Element was just initialized with `MaybeUninit::write`, so it's ok to increase len - // - len is increased after each element to prevent leaks (see issue #82533) - .for_each(|_| *len += 1); - } -} - -#[cfg(not(no_global_oom_handling))] -impl ExtendFromWithinSpec for Vec { - unsafe fn spec_extend_from_within(&mut self, src: Range) { - let count = src.len(); - { - let (init, spare) = self.split_at_spare_mut(); - - // SAFETY: - // - caller guarantees that `src` is a valid index - let source = unsafe { init.get_unchecked(src) }; - - // SAFETY: - // - Both pointers are created from unique slice references (`&mut [_]`) - // so they are valid and do not overlap. - // - Elements are :Copy so it's OK to copy them, without doing - // anything with the original values - // - `count` is equal to the len of `source`, so source is valid for - // `count` reads - // - `.reserve(count)` guarantees that `spare.len() >= count` so spare - // is valid for `count` writes - unsafe { ptr::copy_nonoverlapping(source.as_ptr(), spare.as_mut_ptr() as _, count) }; - } - - // SAFETY: - // - The elements were just initialized by `copy_nonoverlapping` - self.len += count; - } -} - -//////////////////////////////////////////////////////////////////////////////// -// Common trait implementations for Vec -//////////////////////////////////////////////////////////////////////////////// - -#[stable(feature = "rust1", since = "1.0.0")] -impl ops::Deref for Vec { - type Target = [T]; - - #[inline] - fn deref(&self) -> &[T] { - unsafe { slice::from_raw_parts(self.as_ptr(), self.len) } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ops::DerefMut for Vec { - #[inline] - fn deref_mut(&mut self) -> &mut [T] { - unsafe { slice::from_raw_parts_mut(self.as_mut_ptr(), self.len) } - } -} - -#[unstable(feature = "deref_pure_trait", issue = "87121")] -unsafe impl ops::DerefPure for Vec {} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl Clone for Vec { - #[cfg(not(test))] - fn clone(&self) -> Self { - let alloc = self.allocator().clone(); - <[T]>::to_vec_in(&**self, alloc) - } - - // HACK(japaric): with cfg(test) the inherent `[T]::to_vec` method, which is - // required for this method definition, is not available. Instead use the - // `slice::to_vec` function which is only available with cfg(test) - // NB see the slice::hack module in slice.rs for more information - #[cfg(test)] - fn clone(&self) -> Self { - let alloc = self.allocator().clone(); - crate::slice::to_vec(&**self, alloc) - } - - /// Overwrites the contents of `self` with a clone of the contents of `source`. - /// - /// This method is preferred over simply assigning `source.clone()` to `self`, - /// as it avoids reallocation if possible. Additionally, if the element type - /// `T` overrides `clone_from()`, this will reuse the resources of `self`'s - /// elements as well. - /// - /// # Examples - /// - /// ``` - /// let x = vec![5, 6, 7]; - /// let mut y = vec![8, 9, 10]; - /// let yp: *const i32 = y.as_ptr(); - /// - /// y.clone_from(&x); - /// - /// // The value is the same - /// assert_eq!(x, y); - /// - /// // And no reallocation occurred - /// assert_eq!(yp, y.as_ptr()); - /// ``` - fn clone_from(&mut self, source: &Self) { - crate::slice::SpecCloneIntoVec::clone_into(source.as_slice(), self); - } -} - -/// The hash of a vector is the same as that of the corresponding slice, -/// as required by the `core::borrow::Borrow` implementation. -/// -/// ``` -/// use std::hash::BuildHasher; -/// -/// let b = std::hash::RandomState::new(); -/// let v: Vec = vec![0xa8, 0x3c, 0x09]; -/// let s: &[u8] = &[0xa8, 0x3c, 0x09]; -/// assert_eq!(b.hash_one(v), b.hash_one(s)); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -impl Hash for Vec { - #[inline] - fn hash(&self, state: &mut H) { - Hash::hash(&**self, state) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_on_unimplemented( - message = "vector indices are of type `usize` or ranges of `usize`", - label = "vector indices are of type `usize` or ranges of `usize`" -)] -impl, A: Allocator> Index for Vec { - type Output = I::Output; - - #[inline] - fn index(&self, index: I) -> &Self::Output { - Index::index(&**self, index) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -#[rustc_on_unimplemented( - message = "vector indices are of type `usize` or ranges of `usize`", - label = "vector indices are of type `usize` or ranges of `usize`" -)] -impl, A: Allocator> IndexMut for Vec { - #[inline] - fn index_mut(&mut self, index: I) -> &mut Self::Output { - IndexMut::index_mut(&mut **self, index) - } -} - -/// Collects an iterator into a Vec, commonly called via [`Iterator::collect()`] -/// -/// # Allocation behavior -/// -/// In general `Vec` does not guarantee any particular growth or allocation strategy. -/// That also applies to this trait impl. -/// -/// **Note:** This section covers implementation details and is therefore exempt from -/// stability guarantees. -/// -/// Vec may use any or none of the following strategies, -/// depending on the supplied iterator: -/// -/// * preallocate based on [`Iterator::size_hint()`] -/// * and panic if the number of items is outside the provided lower/upper bounds -/// * use an amortized growth strategy similar to `pushing` one item at a time -/// * perform the iteration in-place on the original allocation backing the iterator -/// -/// The last case warrants some attention. It is an optimization that in many cases reduces peak memory -/// consumption and improves cache locality. But when big, short-lived allocations are created, -/// only a small fraction of their items get collected, no further use is made of the spare capacity -/// and the resulting `Vec` is moved into a longer-lived structure, then this can lead to the large -/// allocations having their lifetimes unnecessarily extended which can result in increased memory -/// footprint. -/// -/// In cases where this is an issue, the excess capacity can be discarded with [`Vec::shrink_to()`], -/// [`Vec::shrink_to_fit()`] or by collecting into [`Box<[T]>`][owned slice] instead, which additionally reduces -/// the size of the long-lived struct. -/// -/// [owned slice]: Box -/// -/// ```rust -/// # use std::sync::Mutex; -/// static LONG_LIVED: Mutex>> = Mutex::new(Vec::new()); -/// -/// for i in 0..10 { -/// let big_temporary: Vec = (0..1024).collect(); -/// // discard most items -/// let mut result: Vec<_> = big_temporary.into_iter().filter(|i| i % 100 == 0).collect(); -/// // without this a lot of unused capacity might be moved into the global -/// result.shrink_to_fit(); -/// LONG_LIVED.lock().unwrap().push(result); -/// } -/// ``` -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl FromIterator for Vec { - #[inline] - fn from_iter>(iter: I) -> Vec { - >::from_iter(iter.into_iter()) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl IntoIterator for Vec { - type Item = T; - type IntoIter = IntoIter; - - /// Creates a consuming iterator, that is, one that moves each value out of - /// the vector (from start to end). The vector cannot be used after calling - /// this. - /// - /// # Examples - /// - /// ``` - /// let v = vec!["a".to_string(), "b".to_string()]; - /// let mut v_iter = v.into_iter(); - /// - /// let first_element: Option = v_iter.next(); - /// - /// assert_eq!(first_element, Some("a".to_string())); - /// assert_eq!(v_iter.next(), Some("b".to_string())); - /// assert_eq!(v_iter.next(), None); - /// ``` - #[inline] - fn into_iter(self) -> Self::IntoIter { - unsafe { - let me = ManuallyDrop::new(self); - let alloc = ManuallyDrop::new(ptr::read(me.allocator())); - let buf = me.buf.non_null(); - let begin = buf.as_ptr(); - let end = if T::IS_ZST { - begin.wrapping_byte_add(me.len()) - } else { - begin.add(me.len()) as *const T - }; - let cap = me.buf.capacity(); - IntoIter { buf, phantom: PhantomData, cap, alloc, ptr: buf, end } - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T, A: Allocator> IntoIterator for &'a Vec { - type Item = &'a T; - type IntoIter = slice::Iter<'a, T>; - - fn into_iter(self) -> Self::IntoIter { - self.iter() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T, A: Allocator> IntoIterator for &'a mut Vec { - type Item = &'a mut T; - type IntoIter = slice::IterMut<'a, T>; - - fn into_iter(self) -> Self::IntoIter { - self.iter_mut() - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl Extend for Vec { - #[inline] - fn extend>(&mut self, iter: I) { - >::spec_extend(self, iter.into_iter()) - } - - #[inline] - fn extend_one(&mut self, item: T) { - self.push(item); - } - - #[inline] - fn extend_reserve(&mut self, additional: usize) { - self.reserve(additional); - } -} - -impl Vec { - // leaf method to which various SpecFrom/SpecExtend implementations delegate when - // they have no further optimizations to apply - #[cfg(not(no_global_oom_handling))] - fn extend_desugared>(&mut self, mut iterator: I) { - // This is the case for a general iterator. - // - // This function should be the moral equivalent of: - // - // for item in iterator { - // self.push(item); - // } - while let Some(element) = iterator.next() { - let len = self.len(); - if len == self.capacity() { - let (lower, _) = iterator.size_hint(); - self.reserve(lower.saturating_add(1)); - } - unsafe { - ptr::write(self.as_mut_ptr().add(len), element); - // Since next() executes user code which can panic we have to bump the length - // after each step. - // NB can't overflow since we would have had to alloc the address space - self.set_len(len + 1); - } - } - } - - // specific extend for `TrustedLen` iterators, called both by the specializations - // and internal places where resolving specialization makes compilation slower - #[cfg(not(no_global_oom_handling))] - fn extend_trusted(&mut self, iterator: impl iter::TrustedLen) { - let (low, high) = iterator.size_hint(); - if let Some(additional) = high { - debug_assert_eq!( - low, - additional, - "TrustedLen iterator's size hint is not exact: {:?}", - (low, high) - ); - self.reserve(additional); - unsafe { - let ptr = self.as_mut_ptr(); - let mut local_len = SetLenOnDrop::new(&mut self.len); - iterator.for_each(move |element| { - ptr::write(ptr.add(local_len.current_len()), element); - // Since the loop executes user code which can panic we have to update - // the length every step to correctly drop what we've written. - // NB can't overflow since we would have had to alloc the address space - local_len.increment_len(1); - }); - } - } else { - // Per TrustedLen contract a `None` upper bound means that the iterator length - // truly exceeds usize::MAX, which would eventually lead to a capacity overflow anyway. - // Since the other branch already panics eagerly (via `reserve()`) we do the same here. - // This avoids additional codegen for a fallback code path which would eventually - // panic anyway. - panic!("capacity overflow"); - } - } - - /// Creates a splicing iterator that replaces the specified range in the vector - /// with the given `replace_with` iterator and yields the removed items. - /// `replace_with` does not need to be the same length as `range`. - /// - /// `range` is removed even if the iterator is not consumed until the end. - /// - /// It is unspecified how many elements are removed from the vector - /// if the `Splice` value is leaked. - /// - /// The input iterator `replace_with` is only consumed when the `Splice` value is dropped. - /// - /// This is optimal if: - /// - /// * The tail (elements in the vector after `range`) is empty, - /// * or `replace_with` yields fewer or equal elements than `range`’s length - /// * or the lower bound of its `size_hint()` is exact. - /// - /// Otherwise, a temporary vector is allocated and the tail is moved twice. - /// - /// # Panics - /// - /// Panics if the starting point is greater than the end point or if - /// the end point is greater than the length of the vector. - /// - /// # Examples - /// - /// ``` - /// let mut v = vec![1, 2, 3, 4]; - /// let new = [7, 8, 9]; - /// let u: Vec<_> = v.splice(1..3, new).collect(); - /// assert_eq!(v, &[1, 7, 8, 9, 4]); - /// assert_eq!(u, &[2, 3]); - /// ``` - #[cfg(not(no_global_oom_handling))] - #[inline] - #[stable(feature = "vec_splice", since = "1.21.0")] - pub fn splice(&mut self, range: R, replace_with: I) -> Splice<'_, I::IntoIter, A> - where - R: RangeBounds, - I: IntoIterator, - { - Splice { drain: self.drain(range), replace_with: replace_with.into_iter() } - } - - /// Creates an iterator which uses a closure to determine if an element should be removed. - /// - /// If the closure returns true, then the element is removed and yielded. - /// If the closure returns false, the element will remain in the vector and will not be yielded - /// by the iterator. - /// - /// If the returned `ExtractIf` is not exhausted, e.g. because it is dropped without iterating - /// or the iteration short-circuits, then the remaining elements will be retained. - /// Use [`retain`] with a negated predicate if you do not need the returned iterator. - /// - /// [`retain`]: Vec::retain - /// - /// Using this method is equivalent to the following code: - /// - /// ``` - /// # let some_predicate = |x: &mut i32| { *x == 2 || *x == 3 || *x == 6 }; - /// # let mut vec = vec![1, 2, 3, 4, 5, 6]; - /// let mut i = 0; - /// while i < vec.len() { - /// if some_predicate(&mut vec[i]) { - /// let val = vec.remove(i); - /// // your code here - /// } else { - /// i += 1; - /// } - /// } - /// - /// # assert_eq!(vec, vec![1, 4, 5]); - /// ``` - /// - /// But `extract_if` is easier to use. `extract_if` is also more efficient, - /// because it can backshift the elements of the array in bulk. - /// - /// Note that `extract_if` also lets you mutate every element in the filter closure, - /// regardless of whether you choose to keep or remove it. - /// - /// # Examples - /// - /// Splitting an array into evens and odds, reusing the original allocation: - /// - /// ``` - /// #![feature(extract_if)] - /// let mut numbers = vec![1, 2, 3, 4, 5, 6, 8, 9, 11, 13, 14, 15]; - /// - /// let evens = numbers.extract_if(|x| *x % 2 == 0).collect::>(); - /// let odds = numbers; - /// - /// assert_eq!(evens, vec![2, 4, 6, 8, 14]); - /// assert_eq!(odds, vec![1, 3, 5, 9, 11, 13, 15]); - /// ``` - #[unstable(feature = "extract_if", reason = "recently added", issue = "43244")] - pub fn extract_if(&mut self, filter: F) -> ExtractIf<'_, T, F, A> - where - F: FnMut(&mut T) -> bool, - { - let old_len = self.len(); - - // Guard against us getting leaked (leak amplification) - unsafe { - self.set_len(0); - } - - ExtractIf { vec: self, idx: 0, del: 0, old_len, pred: filter } - } -} - -/// Extend implementation that copies elements out of references before pushing them onto the Vec. -/// -/// This implementation is specialized for slice iterators, where it uses [`copy_from_slice`] to -/// append the entire slice at once. -/// -/// [`copy_from_slice`]: slice::copy_from_slice -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "extend_ref", since = "1.2.0")] -impl<'a, T: Copy + 'a, A: Allocator> Extend<&'a T> for Vec { - fn extend>(&mut self, iter: I) { - self.spec_extend(iter.into_iter()) - } - - #[inline] - fn extend_one(&mut self, &item: &'a T) { - self.push(item); - } - - #[inline] - fn extend_reserve(&mut self, additional: usize) { - self.reserve(additional); - } -} - -/// Implements comparison of vectors, [lexicographically](Ord#lexicographical-comparison). -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialOrd> for Vec -where - T: PartialOrd, - A1: Allocator, - A2: Allocator, -{ - #[inline] - fn partial_cmp(&self, other: &Vec) -> Option { - PartialOrd::partial_cmp(&**self, &**other) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Eq for Vec {} - -/// Implements ordering of vectors, [lexicographically](Ord#lexicographical-comparison). -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for Vec { - #[inline] - fn cmp(&self, other: &Self) -> Ordering { - Ord::cmp(&**self, &**other) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -unsafe impl<#[may_dangle] T, A: Allocator> Drop for Vec { - fn drop(&mut self) { - unsafe { - // use drop for [T] - // use a raw slice to refer to the elements of the vector as weakest necessary type; - // could avoid questions of validity in certain cases - ptr::drop_in_place(ptr::slice_from_raw_parts_mut(self.as_mut_ptr(), self.len)) - } - // RawVec handles deallocation - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Default for Vec { - /// Creates an empty `Vec`. - /// - /// The vector will not allocate until elements are pushed onto it. - fn default() -> Vec { - Vec::new() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for Vec { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&**self, f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef> for Vec { - fn as_ref(&self) -> &Vec { - self - } -} - -#[stable(feature = "vec_as_mut", since = "1.5.0")] -impl AsMut> for Vec { - fn as_mut(&mut self) -> &mut Vec { - self - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef<[T]> for Vec { - fn as_ref(&self) -> &[T] { - self - } -} - -#[stable(feature = "vec_as_mut", since = "1.5.0")] -impl AsMut<[T]> for Vec { - fn as_mut(&mut self) -> &mut [T] { - self - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl From<&[T]> for Vec { - /// Allocate a `Vec` and fill it by cloning `s`'s items. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(Vec::from(&[1, 2, 3][..]), vec![1, 2, 3]); - /// ``` - #[cfg(not(test))] - fn from(s: &[T]) -> Vec { - s.to_vec() - } - #[cfg(test)] - fn from(s: &[T]) -> Vec { - crate::slice::to_vec(s, Global) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "vec_from_mut", since = "1.19.0")] -impl From<&mut [T]> for Vec { - /// Allocate a `Vec` and fill it by cloning `s`'s items. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(Vec::from(&mut [1, 2, 3][..]), vec![1, 2, 3]); - /// ``` - #[cfg(not(test))] - fn from(s: &mut [T]) -> Vec { - s.to_vec() - } - #[cfg(test)] - fn from(s: &mut [T]) -> Vec { - crate::slice::to_vec(s, Global) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "vec_from_array_ref", since = "1.74.0")] -impl From<&[T; N]> for Vec { - /// Allocate a `Vec` and fill it by cloning `s`'s items. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(Vec::from(&[1, 2, 3]), vec![1, 2, 3]); - /// ``` - fn from(s: &[T; N]) -> Vec { - Self::from(s.as_slice()) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "vec_from_array_ref", since = "1.74.0")] -impl From<&mut [T; N]> for Vec { - /// Allocate a `Vec` and fill it by cloning `s`'s items. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(Vec::from(&mut [1, 2, 3]), vec![1, 2, 3]); - /// ``` - fn from(s: &mut [T; N]) -> Vec { - Self::from(s.as_mut_slice()) - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "vec_from_array", since = "1.44.0")] -impl From<[T; N]> for Vec { - /// Allocate a `Vec` and move `s`'s items into it. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(Vec::from([1, 2, 3]), vec![1, 2, 3]); - /// ``` - #[cfg(not(test))] - fn from(s: [T; N]) -> Vec { - <[T]>::into_vec(Box::new(s)) - } - - #[cfg(test)] - fn from(s: [T; N]) -> Vec { - crate::slice::into_vec(Box::new(s)) - } -} - -#[stable(feature = "vec_from_cow_slice", since = "1.14.0")] -impl<'a, T> From> for Vec -where - [T]: ToOwned>, -{ - /// Convert a clone-on-write slice into a vector. - /// - /// If `s` already owns a `Vec`, it will be returned directly. - /// If `s` is borrowing a slice, a new `Vec` will be allocated and - /// filled by cloning `s`'s items into it. - /// - /// # Examples - /// - /// ``` - /// # use std::borrow::Cow; - /// let o: Cow<'_, [i32]> = Cow::Owned(vec![1, 2, 3]); - /// let b: Cow<'_, [i32]> = Cow::Borrowed(&[1, 2, 3]); - /// assert_eq!(Vec::from(o), Vec::from(b)); - /// ``` - fn from(s: Cow<'a, [T]>) -> Vec { - s.into_owned() - } -} - -// note: test pulls in std, which causes errors here -#[cfg(not(test))] -#[stable(feature = "vec_from_box", since = "1.18.0")] -impl From> for Vec { - /// Convert a boxed slice into a vector by transferring ownership of - /// the existing heap allocation. - /// - /// # Examples - /// - /// ``` - /// let b: Box<[i32]> = vec![1, 2, 3].into_boxed_slice(); - /// assert_eq!(Vec::from(b), vec![1, 2, 3]); - /// ``` - fn from(s: Box<[T], A>) -> Self { - s.into_vec() - } -} - -// note: test pulls in std, which causes errors here -#[cfg(not(no_global_oom_handling))] -#[cfg(not(test))] -#[stable(feature = "box_from_vec", since = "1.20.0")] -impl From> for Box<[T], A> { - /// Convert a vector into a boxed slice. - /// - /// Before doing the conversion, this method discards excess capacity like [`Vec::shrink_to_fit`]. - /// - /// [owned slice]: Box - /// [`Vec::shrink_to_fit`]: Vec::shrink_to_fit - /// - /// # Examples - /// - /// ``` - /// assert_eq!(Box::from(vec![1, 2, 3]), vec![1, 2, 3].into_boxed_slice()); - /// ``` - /// - /// Any excess capacity is removed: - /// ``` - /// let mut vec = Vec::with_capacity(10); - /// vec.extend([1, 2, 3]); - /// - /// assert_eq!(Box::from(vec), vec![1, 2, 3].into_boxed_slice()); - /// ``` - fn from(v: Vec) -> Self { - v.into_boxed_slice() - } -} - -#[cfg(not(no_global_oom_handling))] -#[stable(feature = "rust1", since = "1.0.0")] -impl From<&str> for Vec { - /// Allocate a `Vec` and fill it with a UTF-8 string. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(Vec::from("123"), vec![b'1', b'2', b'3']); - /// ``` - fn from(s: &str) -> Vec { - From::from(s.as_bytes()) - } -} - -#[stable(feature = "array_try_from_vec", since = "1.48.0")] -impl TryFrom> for [T; N] { - type Error = Vec; - - /// Gets the entire contents of the `Vec` as an array, - /// if its size exactly matches that of the requested array. - /// - /// # Examples - /// - /// ``` - /// assert_eq!(vec![1, 2, 3].try_into(), Ok([1, 2, 3])); - /// assert_eq!(>::new().try_into(), Ok([])); - /// ``` - /// - /// If the length doesn't match, the input comes back in `Err`: - /// ``` - /// let r: Result<[i32; 4], _> = (0..10).collect::>().try_into(); - /// assert_eq!(r, Err(vec![0, 1, 2, 3, 4, 5, 6, 7, 8, 9])); - /// ``` - /// - /// If you're fine with just getting a prefix of the `Vec`, - /// you can call [`.truncate(N)`](Vec::truncate) first. - /// ``` - /// let mut v = String::from("hello world").into_bytes(); - /// v.sort(); - /// v.truncate(2); - /// let [a, b]: [_; 2] = v.try_into().unwrap(); - /// assert_eq!(a, b' '); - /// assert_eq!(b, b'd'); - /// ``` - fn try_from(mut vec: Vec) -> Result<[T; N], Vec> { - if vec.len() != N { - return Err(vec); - } - - // SAFETY: `.set_len(0)` is always sound. - unsafe { vec.set_len(0) }; - - // SAFETY: A `Vec`'s pointer is always aligned properly, and - // the alignment the array needs is the same as the items. - // We checked earlier that we have sufficient items. - // The items will not double-drop as the `set_len` - // tells the `Vec` not to also drop them. - let array = unsafe { ptr::read(vec.as_ptr() as *const [T; N]) }; - Ok(array) - } -} diff --git a/library/alloc/src/vec/partial_eq.rs b/library/alloc/src/vec/partial_eq.rs deleted file mode 100644 index b0cf72577a1be..0000000000000 --- a/library/alloc/src/vec/partial_eq.rs +++ /dev/null @@ -1,47 +0,0 @@ -use crate::alloc::Allocator; -#[cfg(not(no_global_oom_handling))] -use crate::borrow::Cow; - -use super::Vec; - -macro_rules! __impl_slice_eq1 { - ([$($vars:tt)*] $lhs:ty, $rhs:ty $(where $ty:ty: $bound:ident)?, #[$stability:meta]) => { - #[$stability] - impl PartialEq<$rhs> for $lhs - where - T: PartialEq, - $($ty: $bound)? - { - #[inline] - fn eq(&self, other: &$rhs) -> bool { self[..] == other[..] } - #[inline] - fn ne(&self, other: &$rhs) -> bool { self[..] != other[..] } - } - } -} - -__impl_slice_eq1! { [A1: Allocator, A2: Allocator] Vec, Vec, #[stable(feature = "rust1", since = "1.0.0")] } -__impl_slice_eq1! { [A: Allocator] Vec, &[U], #[stable(feature = "rust1", since = "1.0.0")] } -__impl_slice_eq1! { [A: Allocator] Vec, &mut [U], #[stable(feature = "rust1", since = "1.0.0")] } -__impl_slice_eq1! { [A: Allocator] &[T], Vec, #[stable(feature = "partialeq_vec_for_ref_slice", since = "1.46.0")] } -__impl_slice_eq1! { [A: Allocator] &mut [T], Vec, #[stable(feature = "partialeq_vec_for_ref_slice", since = "1.46.0")] } -__impl_slice_eq1! { [A: Allocator] Vec, [U], #[stable(feature = "partialeq_vec_for_slice", since = "1.48.0")] } -__impl_slice_eq1! { [A: Allocator] [T], Vec, #[stable(feature = "partialeq_vec_for_slice", since = "1.48.0")] } -#[cfg(not(no_global_oom_handling))] -__impl_slice_eq1! { [A: Allocator] Cow<'_, [T]>, Vec where T: Clone, #[stable(feature = "rust1", since = "1.0.0")] } -#[cfg(not(no_global_oom_handling))] -__impl_slice_eq1! { [] Cow<'_, [T]>, &[U] where T: Clone, #[stable(feature = "rust1", since = "1.0.0")] } -#[cfg(not(no_global_oom_handling))] -__impl_slice_eq1! { [] Cow<'_, [T]>, &mut [U] where T: Clone, #[stable(feature = "rust1", since = "1.0.0")] } -__impl_slice_eq1! { [A: Allocator, const N: usize] Vec, [U; N], #[stable(feature = "rust1", since = "1.0.0")] } -__impl_slice_eq1! { [A: Allocator, const N: usize] Vec, &[U; N], #[stable(feature = "rust1", since = "1.0.0")] } - -// NOTE: some less important impls are omitted to reduce code bloat -// FIXME(Centril): Reconsider this? -//__impl_slice_eq1! { [const N: usize] Vec, &mut [B; N], } -//__impl_slice_eq1! { [const N: usize] [A; N], Vec, } -//__impl_slice_eq1! { [const N: usize] &[A; N], Vec, } -//__impl_slice_eq1! { [const N: usize] &mut [A; N], Vec, } -//__impl_slice_eq1! { [const N: usize] Cow<'a, [A]>, [B; N], } -//__impl_slice_eq1! { [const N: usize] Cow<'a, [A]>, &[B; N], } -//__impl_slice_eq1! { [const N: usize] Cow<'a, [A]>, &mut [B; N], } diff --git a/library/alloc/src/vec/set_len_on_drop.rs b/library/alloc/src/vec/set_len_on_drop.rs deleted file mode 100644 index 6ce5a3a9f54eb..0000000000000 --- a/library/alloc/src/vec/set_len_on_drop.rs +++ /dev/null @@ -1,33 +0,0 @@ -// Set the length of the vec when the `SetLenOnDrop` value goes out of scope. -// -// The idea is: The length field in SetLenOnDrop is a local variable -// that the optimizer will see does not alias with any stores through the Vec's data -// pointer. This is a workaround for alias analysis issue #32155 -pub(super) struct SetLenOnDrop<'a> { - len: &'a mut usize, - local_len: usize, -} - -impl<'a> SetLenOnDrop<'a> { - #[inline] - pub(super) fn new(len: &'a mut usize) -> Self { - SetLenOnDrop { local_len: *len, len } - } - - #[inline] - pub(super) fn increment_len(&mut self, increment: usize) { - self.local_len += increment; - } - - #[inline] - pub(super) fn current_len(&self) -> usize { - self.local_len - } -} - -impl Drop for SetLenOnDrop<'_> { - #[inline] - fn drop(&mut self) { - *self.len = self.local_len; - } -} diff --git a/library/alloc/src/vec/spec_extend.rs b/library/alloc/src/vec/spec_extend.rs deleted file mode 100644 index e2f865d0f7167..0000000000000 --- a/library/alloc/src/vec/spec_extend.rs +++ /dev/null @@ -1,57 +0,0 @@ -use crate::alloc::Allocator; -use core::iter::TrustedLen; -use core::slice::{self}; - -use super::{IntoIter, Vec}; - -// Specialization trait used for Vec::extend -pub(super) trait SpecExtend { - fn spec_extend(&mut self, iter: I); -} - -impl SpecExtend for Vec -where - I: Iterator, -{ - default fn spec_extend(&mut self, iter: I) { - self.extend_desugared(iter) - } -} - -impl SpecExtend for Vec -where - I: TrustedLen, -{ - default fn spec_extend(&mut self, iterator: I) { - self.extend_trusted(iterator) - } -} - -impl SpecExtend> for Vec { - fn spec_extend(&mut self, mut iterator: IntoIter) { - unsafe { - self.append_elements(iterator.as_slice() as _); - } - iterator.forget_remaining_elements(); - } -} - -impl<'a, T: 'a, I, A: Allocator> SpecExtend<&'a T, I> for Vec -where - I: Iterator, - T: Clone, -{ - default fn spec_extend(&mut self, iterator: I) { - self.spec_extend(iterator.cloned()) - } -} - -impl<'a, T: 'a, A: Allocator> SpecExtend<&'a T, slice::Iter<'a, T>> for Vec -where - T: Copy, -{ - fn spec_extend(&mut self, iterator: slice::Iter<'a, T>) { - let slice = iterator.as_slice(); - unsafe { self.append_elements(slice) }; - } -} diff --git a/library/alloc/src/vec/spec_from_elem.rs b/library/alloc/src/vec/spec_from_elem.rs deleted file mode 100644 index 01a6db14474bb..0000000000000 --- a/library/alloc/src/vec/spec_from_elem.rs +++ /dev/null @@ -1,76 +0,0 @@ -use core::ptr; - -use crate::alloc::Allocator; -use crate::raw_vec::RawVec; - -use super::{IsZero, Vec}; - -// Specialization trait used for Vec::from_elem -pub(super) trait SpecFromElem: Sized { - fn from_elem(elem: Self, n: usize, alloc: A) -> Vec; -} - -impl SpecFromElem for T { - default fn from_elem(elem: Self, n: usize, alloc: A) -> Vec { - let mut v = Vec::with_capacity_in(n, alloc); - v.extend_with(n, elem); - v - } -} - -impl SpecFromElem for T { - #[inline] - default fn from_elem(elem: T, n: usize, alloc: A) -> Vec { - if elem.is_zero() { - return Vec { buf: RawVec::with_capacity_zeroed_in(n, alloc), len: n }; - } - let mut v = Vec::with_capacity_in(n, alloc); - v.extend_with(n, elem); - v - } -} - -impl SpecFromElem for i8 { - #[inline] - fn from_elem(elem: i8, n: usize, alloc: A) -> Vec { - if elem == 0 { - return Vec { buf: RawVec::with_capacity_zeroed_in(n, alloc), len: n }; - } - let mut v = Vec::with_capacity_in(n, alloc); - unsafe { - ptr::write_bytes(v.as_mut_ptr(), elem as u8, n); - v.set_len(n); - } - v - } -} - -impl SpecFromElem for u8 { - #[inline] - fn from_elem(elem: u8, n: usize, alloc: A) -> Vec { - if elem == 0 { - return Vec { buf: RawVec::with_capacity_zeroed_in(n, alloc), len: n }; - } - let mut v = Vec::with_capacity_in(n, alloc); - unsafe { - ptr::write_bytes(v.as_mut_ptr(), elem, n); - v.set_len(n); - } - v - } -} - -// A better way would be to implement this for all ZSTs which are `Copy` and have trivial `Clone` -// but the latter cannot be detected currently -impl SpecFromElem for () { - #[inline] - fn from_elem(_elem: (), n: usize, alloc: A) -> Vec<(), A> { - let mut v = Vec::with_capacity_in(n, alloc); - // SAFETY: the capacity has just been set to `n` - // and `()` is a ZST with trivial `Clone` implementation - unsafe { - v.set_len(n); - } - v - } -} diff --git a/library/alloc/src/vec/spec_from_iter.rs b/library/alloc/src/vec/spec_from_iter.rs deleted file mode 100644 index 6646ae7bccb7a..0000000000000 --- a/library/alloc/src/vec/spec_from_iter.rs +++ /dev/null @@ -1,64 +0,0 @@ -use core::mem::ManuallyDrop; -use core::ptr::{self}; - -use super::{IntoIter, SpecExtend, SpecFromIterNested, Vec}; - -/// Specialization trait used for Vec::from_iter -/// -/// ## The delegation graph: -/// -/// ```text -/// +-------------+ -/// |FromIterator | -/// +-+-----------+ -/// | -/// v -/// +-+---------------------------------+ +---------------------+ -/// |SpecFromIter +---->+SpecFromIterNested | -/// |where I: | | |where I: | -/// | Iterator (default)------------+ | | Iterator (default) | -/// | vec::IntoIter | | | TrustedLen | -/// | InPlaceCollect--(fallback to)-+ | +---------------------+ -/// +-----------------------------------+ -/// ``` -pub(super) trait SpecFromIter { - fn from_iter(iter: I) -> Self; -} - -impl SpecFromIter for Vec -where - I: Iterator, -{ - default fn from_iter(iterator: I) -> Self { - SpecFromIterNested::from_iter(iterator) - } -} - -impl SpecFromIter> for Vec { - fn from_iter(iterator: IntoIter) -> Self { - // A common case is passing a vector into a function which immediately - // re-collects into a vector. We can short circuit this if the IntoIter - // has not been advanced at all. - // When it has been advanced We can also reuse the memory and move the data to the front. - // But we only do so when the resulting Vec wouldn't have more unused capacity - // than creating it through the generic FromIterator implementation would. That limitation - // is not strictly necessary as Vec's allocation behavior is intentionally unspecified. - // But it is a conservative choice. - let has_advanced = iterator.buf != iterator.ptr; - if !has_advanced || iterator.len() >= iterator.cap / 2 { - unsafe { - let it = ManuallyDrop::new(iterator); - if has_advanced { - ptr::copy(it.ptr.as_ptr(), it.buf.as_ptr(), it.len()); - } - return Vec::from_nonnull(it.buf, it.len(), it.cap); - } - } - - let mut vec = Vec::new(); - // must delegate to spec_extend() since extend() itself delegates - // to spec_from for empty Vecs - vec.spec_extend(iterator); - vec - } -} diff --git a/library/alloc/src/vec/spec_from_iter_nested.rs b/library/alloc/src/vec/spec_from_iter_nested.rs deleted file mode 100644 index f915ebb86e5a5..0000000000000 --- a/library/alloc/src/vec/spec_from_iter_nested.rs +++ /dev/null @@ -1,65 +0,0 @@ -use core::cmp; -use core::iter::TrustedLen; -use core::ptr; - -use crate::raw_vec::RawVec; - -use super::{SpecExtend, Vec}; - -/// Another specialization trait for Vec::from_iter -/// necessary to manually prioritize overlapping specializations -/// see [`SpecFromIter`](super::SpecFromIter) for details. -pub(super) trait SpecFromIterNested { - fn from_iter(iter: I) -> Self; -} - -impl SpecFromIterNested for Vec -where - I: Iterator, -{ - default fn from_iter(mut iterator: I) -> Self { - // Unroll the first iteration, as the vector is going to be - // expanded on this iteration in every case when the iterable is not - // empty, but the loop in extend_desugared() is not going to see the - // vector being full in the few subsequent loop iterations. - // So we get better branch prediction. - let mut vector = match iterator.next() { - None => return Vec::new(), - Some(element) => { - let (lower, _) = iterator.size_hint(); - let initial_capacity = - cmp::max(RawVec::::MIN_NON_ZERO_CAP, lower.saturating_add(1)); - let mut vector = Vec::with_capacity(initial_capacity); - unsafe { - // SAFETY: We requested capacity at least 1 - ptr::write(vector.as_mut_ptr(), element); - vector.set_len(1); - } - vector - } - }; - // must delegate to spec_extend() since extend() itself delegates - // to spec_from for empty Vecs - as SpecExtend>::spec_extend(&mut vector, iterator); - vector - } -} - -impl SpecFromIterNested for Vec -where - I: TrustedLen, -{ - fn from_iter(iterator: I) -> Self { - let mut vector = match iterator.size_hint() { - (_, Some(upper)) => Vec::with_capacity(upper), - // TrustedLen contract guarantees that `size_hint() == (_, None)` means that there - // are more than `usize::MAX` elements. - // Since the previous branch would eagerly panic if the capacity is too large - // (via `with_capacity`) we do the same here. - _ => panic!("capacity overflow"), - }; - // reuse extend specialization for TrustedLen - vector.spec_extend(iterator); - vector - } -} diff --git a/library/alloc/src/vec/splice.rs b/library/alloc/src/vec/splice.rs deleted file mode 100644 index 852fdcc3f5ce7..0000000000000 --- a/library/alloc/src/vec/splice.rs +++ /dev/null @@ -1,139 +0,0 @@ -use crate::alloc::{Allocator, Global}; -use core::ptr::{self}; -use core::slice::{self}; - -use super::{Drain, Vec}; - -/// A splicing iterator for `Vec`. -/// -/// This struct is created by [`Vec::splice()`]. -/// See its documentation for more. -/// -/// # Example -/// -/// ``` -/// let mut v = vec![0, 1, 2]; -/// let new = [7, 8]; -/// let iter: std::vec::Splice<'_, _> = v.splice(1.., new); -/// ``` -#[derive(Debug)] -#[stable(feature = "vec_splice", since = "1.21.0")] -pub struct Splice< - 'a, - I: Iterator + 'a, - #[unstable(feature = "allocator_api", issue = "32838")] A: Allocator + 'a = Global, -> { - pub(super) drain: Drain<'a, I::Item, A>, - pub(super) replace_with: I, -} - -#[stable(feature = "vec_splice", since = "1.21.0")] -impl Iterator for Splice<'_, I, A> { - type Item = I::Item; - - fn next(&mut self) -> Option { - self.drain.next() - } - - fn size_hint(&self) -> (usize, Option) { - self.drain.size_hint() - } -} - -#[stable(feature = "vec_splice", since = "1.21.0")] -impl DoubleEndedIterator for Splice<'_, I, A> { - fn next_back(&mut self) -> Option { - self.drain.next_back() - } -} - -#[stable(feature = "vec_splice", since = "1.21.0")] -impl ExactSizeIterator for Splice<'_, I, A> {} - -#[stable(feature = "vec_splice", since = "1.21.0")] -impl Drop for Splice<'_, I, A> { - fn drop(&mut self) { - self.drain.by_ref().for_each(drop); - // At this point draining is done and the only remaining tasks are splicing - // and moving things into the final place. - // Which means we can replace the slice::Iter with pointers that won't point to deallocated - // memory, so that Drain::drop is still allowed to call iter.len(), otherwise it would break - // the ptr.sub_ptr contract. - self.drain.iter = (&[]).iter(); - - unsafe { - if self.drain.tail_len == 0 { - self.drain.vec.as_mut().extend(self.replace_with.by_ref()); - return; - } - - // First fill the range left by drain(). - if !self.drain.fill(&mut self.replace_with) { - return; - } - - // There may be more elements. Use the lower bound as an estimate. - // FIXME: Is the upper bound a better guess? Or something else? - let (lower_bound, _upper_bound) = self.replace_with.size_hint(); - if lower_bound > 0 { - self.drain.move_tail(lower_bound); - if !self.drain.fill(&mut self.replace_with) { - return; - } - } - - // Collect any remaining elements. - // This is a zero-length vector which does not allocate if `lower_bound` was exact. - let mut collected = self.replace_with.by_ref().collect::>().into_iter(); - // Now we have an exact count. - if collected.len() > 0 { - self.drain.move_tail(collected.len()); - let filled = self.drain.fill(&mut collected); - debug_assert!(filled); - debug_assert_eq!(collected.len(), 0); - } - } - // Let `Drain::drop` move the tail back if necessary and restore `vec.len`. - } -} - -/// Private helper methods for `Splice::drop` -impl Drain<'_, T, A> { - /// The range from `self.vec.len` to `self.tail_start` contains elements - /// that have been moved out. - /// Fill that range as much as possible with new elements from the `replace_with` iterator. - /// Returns `true` if we filled the entire range. (`replace_with.next()` didn’t return `None`.) - unsafe fn fill>(&mut self, replace_with: &mut I) -> bool { - let vec = unsafe { self.vec.as_mut() }; - let range_start = vec.len; - let range_end = self.tail_start; - let range_slice = unsafe { - slice::from_raw_parts_mut(vec.as_mut_ptr().add(range_start), range_end - range_start) - }; - - for place in range_slice { - if let Some(new_item) = replace_with.next() { - unsafe { ptr::write(place, new_item) }; - vec.len += 1; - } else { - return false; - } - } - true - } - - /// Makes room for inserting more elements before the tail. - unsafe fn move_tail(&mut self, additional: usize) { - let vec = unsafe { self.vec.as_mut() }; - let len = self.tail_start + self.tail_len; - vec.buf.reserve(len, additional); - - let new_tail_start = self.tail_start + additional; - unsafe { - let src = vec.as_ptr().add(self.tail_start); - let dst = vec.as_mut_ptr().add(new_tail_start); - ptr::copy(src, dst, self.tail_len); - } - self.tail_start = new_tail_start; - } -} diff --git a/library/alloc/tests/arc.rs b/library/alloc/tests/arc.rs deleted file mode 100644 index d564a30b10394..0000000000000 --- a/library/alloc/tests/arc.rs +++ /dev/null @@ -1,211 +0,0 @@ -use std::any::Any; -use std::cell::RefCell; -use std::iter::TrustedLen; -use std::mem; -use std::sync::{Arc, Weak}; - -#[test] -fn uninhabited() { - enum Void {} - let mut a = Weak::::new(); - a = a.clone(); - assert!(a.upgrade().is_none()); - - let mut a: Weak = a; // Unsizing - a = a.clone(); - assert!(a.upgrade().is_none()); -} - -#[test] -fn slice() { - let a: Arc<[u32; 3]> = Arc::new([3, 2, 1]); - let a: Arc<[u32]> = a; // Unsizing - let b: Arc<[u32]> = Arc::from(&[3, 2, 1][..]); // Conversion - assert_eq!(a, b); - - // Exercise is_dangling() with a DST - let mut a = Arc::downgrade(&a); - a = a.clone(); - assert!(a.upgrade().is_some()); -} - -#[test] -fn trait_object() { - let a: Arc = Arc::new(4); - let a: Arc = a; // Unsizing - - // Exercise is_dangling() with a DST - let mut a = Arc::downgrade(&a); - a = a.clone(); - assert!(a.upgrade().is_some()); - - let mut b = Weak::::new(); - b = b.clone(); - assert!(b.upgrade().is_none()); - let mut b: Weak = b; // Unsizing - b = b.clone(); - assert!(b.upgrade().is_none()); -} - -#[test] -fn float_nan_ne() { - let x = Arc::new(f32::NAN); - assert!(x != x); - assert!(!(x == x)); -} - -#[test] -fn partial_eq() { - struct TestPEq(RefCell); - impl PartialEq for TestPEq { - fn eq(&self, other: &TestPEq) -> bool { - *self.0.borrow_mut() += 1; - *other.0.borrow_mut() += 1; - true - } - } - let x = Arc::new(TestPEq(RefCell::new(0))); - assert!(x == x); - assert!(!(x != x)); - assert_eq!(*x.0.borrow(), 4); -} - -#[test] -fn eq() { - #[derive(Eq)] - struct TestEq(RefCell); - impl PartialEq for TestEq { - fn eq(&self, other: &TestEq) -> bool { - *self.0.borrow_mut() += 1; - *other.0.borrow_mut() += 1; - true - } - } - let x = Arc::new(TestEq(RefCell::new(0))); - assert!(x == x); - assert!(!(x != x)); - assert_eq!(*x.0.borrow(), 0); -} - -// The test code below is identical to that in `rc.rs`. -// For better maintainability we therefore define this type alias. -type Rc = Arc; - -const SHARED_ITER_MAX: u16 = 100; - -fn assert_trusted_len(_: &I) {} - -#[test] -fn shared_from_iter_normal() { - // Exercise the base implementation for non-`TrustedLen` iterators. - { - // `Filter` is never `TrustedLen` since we don't - // know statically how many elements will be kept: - let iter = (0..SHARED_ITER_MAX).filter(|x| x % 2 == 0).map(Box::new); - - // Collecting into a `Vec` or `Rc<[T]>` should make no difference: - let vec = iter.clone().collect::>(); - let rc = iter.collect::>(); - assert_eq!(&*vec, &*rc); - - // Clone a bit and let these get dropped. - { - let _rc_2 = rc.clone(); - let _rc_3 = rc.clone(); - let _rc_4 = Rc::downgrade(&_rc_3); - } - } // Drop what hasn't been here. -} - -#[test] -fn shared_from_iter_trustedlen_normal() { - // Exercise the `TrustedLen` implementation under normal circumstances - // where `size_hint()` matches `(_, Some(exact_len))`. - { - let iter = (0..SHARED_ITER_MAX).map(Box::new); - assert_trusted_len(&iter); - - // Collecting into a `Vec` or `Rc<[T]>` should make no difference: - let vec = iter.clone().collect::>(); - let rc = iter.collect::>(); - assert_eq!(&*vec, &*rc); - assert_eq!(mem::size_of::>() * SHARED_ITER_MAX as usize, mem::size_of_val(&*rc)); - - // Clone a bit and let these get dropped. - { - let _rc_2 = rc.clone(); - let _rc_3 = rc.clone(); - let _rc_4 = Rc::downgrade(&_rc_3); - } - } // Drop what hasn't been here. - - // Try a ZST to make sure it is handled well. - { - let iter = (0..SHARED_ITER_MAX).map(drop); - let vec = iter.clone().collect::>(); - let rc = iter.collect::>(); - assert_eq!(&*vec, &*rc); - assert_eq!(0, mem::size_of_val(&*rc)); - { - let _rc_2 = rc.clone(); - let _rc_3 = rc.clone(); - let _rc_4 = Rc::downgrade(&_rc_3); - } - } -} - -#[test] -#[should_panic = "I've almost got 99 problems."] -fn shared_from_iter_trustedlen_panic() { - // Exercise the `TrustedLen` implementation when `size_hint()` matches - // `(_, Some(exact_len))` but where `.next()` drops before the last iteration. - let iter = (0..SHARED_ITER_MAX).map(|val| match val { - 98 => panic!("I've almost got 99 problems."), - _ => Box::new(val), - }); - assert_trusted_len(&iter); - let _ = iter.collect::>(); - - panic!("I am unreachable."); -} - -#[test] -fn shared_from_iter_trustedlen_no_fuse() { - // Exercise the `TrustedLen` implementation when `size_hint()` matches - // `(_, Some(exact_len))` but where the iterator does not behave in a fused manner. - struct Iter(std::vec::IntoIter>>); - - unsafe impl TrustedLen for Iter {} - - impl Iterator for Iter { - fn size_hint(&self) -> (usize, Option) { - (2, Some(2)) - } - - type Item = Box; - - fn next(&mut self) -> Option { - self.0.next().flatten() - } - } - - let vec = vec![Some(Box::new(42)), Some(Box::new(24)), None, Some(Box::new(12))]; - let iter = Iter(vec.into_iter()); - assert_trusted_len(&iter); - assert_eq!(&[Box::new(42), Box::new(24)], &*iter.collect::>()); -} - -#[test] -fn weak_may_dangle() { - fn hmm<'a>(val: &'a mut Weak<&'a str>) -> Weak<&'a str> { - val.clone() - } - - // Without #[may_dangle] we get: - let mut val = Weak::new(); - hmm(&mut val); - // ~~~~~~~~ borrowed value does not live long enough - // - // `val` dropped here while still borrowed - // borrow might be used here, when `val` is dropped and runs the `Drop` code for type `std::sync::Weak` -} diff --git a/library/alloc/tests/autotraits.rs b/library/alloc/tests/autotraits.rs deleted file mode 100644 index 6b82deeac8acb..0000000000000 --- a/library/alloc/tests/autotraits.rs +++ /dev/null @@ -1,288 +0,0 @@ -fn require_sync(_: T) {} -fn require_send_sync(_: T) {} - -struct NotSend(#[allow(dead_code)] *const ()); -unsafe impl Sync for NotSend {} - -#[test] -fn test_btree_map() { - // Tests of this form are prone to https://github.com/rust-lang/rust/issues/64552. - // - // In theory the async block's future would be Send if the value we hold - // across the await point is Send, and Sync if the value we hold across the - // await point is Sync. - // - // We test autotraits in this convoluted way, instead of a straightforward - // `require_send_sync::()`, because the interaction with - // coroutines exposes some current limitations in rustc's ability to prove a - // lifetime bound on the erased coroutine witness types. See the above link. - // - // A typical way this would surface in real code is: - // - // fn spawn(_: T) {} - // - // async fn f() { - // let map = BTreeMap::>::new(); - // for _ in &map { - // async {}.await; - // } - // } - // - // fn main() { - // spawn(f()); - // } - // - // where with some unintentionally overconstrained Send impls in alloc's - // internals, the future might incorrectly not be Send even though every - // single type involved in the program is Send and Sync. - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - // Testing like this would not catch all issues that the above form catches. - require_send_sync(None::>); - - require_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::< - alloc::collections::btree_map::ExtractIf<'_, &u32, &u32, fn(&&u32, &mut &u32) -> bool>, - >; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); -} - -#[test] -fn test_btree_set() { - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None:: bool>>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); -} - -#[test] -fn test_binary_heap() { - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); -} - -#[test] -fn test_linked_list() { - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - // FIXME - /* - require_send_sync(async { - let _v = - None:: bool>>; - async {}.await; - }); - */ - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); -} - -#[test] -fn test_vec_deque() { - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); - - require_send_sync(async { - let _v = None::>; - async {}.await; - }); -} diff --git a/library/alloc/tests/borrow.rs b/library/alloc/tests/borrow.rs deleted file mode 100644 index af7efb7d78223..0000000000000 --- a/library/alloc/tests/borrow.rs +++ /dev/null @@ -1,60 +0,0 @@ -use std::borrow::Cow; -use std::ffi::{CStr, OsStr}; -use std::path::Path; -use std::rc::Rc; -use std::sync::Arc; - -macro_rules! test_from_cow { - ($value:ident => $($ty:ty),+) => {$( - let borrowed = <$ty>::from(Cow::Borrowed($value)); - let owned = <$ty>::from(Cow::Owned($value.to_owned())); - assert_eq!($value, &*borrowed); - assert_eq!($value, &*owned); - )+}; - ($value:ident : & $ty:ty) => { - test_from_cow!($value => Box<$ty>, Rc<$ty>, Arc<$ty>); - } -} - -#[test] -fn test_from_cow_slice() { - let slice: &[i32] = &[1, 2, 3]; - test_from_cow!(slice: &[i32]); -} - -#[test] -fn test_from_cow_str() { - let string = "hello"; - test_from_cow!(string: &str); -} - -#[test] -fn test_from_cow_c_str() { - let string = CStr::from_bytes_with_nul(b"hello\0").unwrap(); - test_from_cow!(string: &CStr); -} - -#[test] -fn test_from_cow_os_str() { - let string = OsStr::new("hello"); - test_from_cow!(string: &OsStr); -} - -#[test] -fn test_from_cow_path() { - let path = Path::new("hello"); - test_from_cow!(path: &Path); -} - -#[test] -fn cow_const() { - // test that the methods of `Cow` are usable in a const context - - const COW: Cow<'_, str> = Cow::Borrowed("moo"); - - const IS_BORROWED: bool = COW.is_borrowed(); - assert!(IS_BORROWED); - - const IS_OWNED: bool = COW.is_owned(); - assert!(!IS_OWNED); -} diff --git a/library/alloc/tests/boxed.rs b/library/alloc/tests/boxed.rs deleted file mode 100644 index 4cacee0414d7d..0000000000000 --- a/library/alloc/tests/boxed.rs +++ /dev/null @@ -1,181 +0,0 @@ -use core::alloc::{AllocError, Allocator, Layout}; -use core::cell::Cell; -use core::mem::MaybeUninit; -use core::ptr::NonNull; - -#[test] -fn uninitialized_zero_size_box() { - assert_eq!( - &*Box::<()>::new_uninit() as *const _, - NonNull::>::dangling().as_ptr(), - ); - assert_eq!( - Box::<[()]>::new_uninit_slice(4).as_ptr(), - NonNull::>::dangling().as_ptr(), - ); - assert_eq!( - Box::<[String]>::new_uninit_slice(0).as_ptr(), - NonNull::>::dangling().as_ptr(), - ); -} - -#[derive(Clone, PartialEq, Eq, Debug)] -struct Dummy { - _data: u8, -} - -#[test] -fn box_clone_and_clone_from_equivalence() { - for size in (0..8).map(|i| 2usize.pow(i)) { - let control = vec![Dummy { _data: 42 }; size].into_boxed_slice(); - let clone = control.clone(); - let mut copy = vec![Dummy { _data: 84 }; size].into_boxed_slice(); - copy.clone_from(&control); - assert_eq!(control, clone); - assert_eq!(control, copy); - } -} - -/// This test might give a false positive in case the box reallocates, -/// but the allocator keeps the original pointer. -/// -/// On the other hand, it won't give a false negative: If it fails, then the -/// memory was definitely not reused. -#[test] -fn box_clone_from_ptr_stability() { - for size in (0..8).map(|i| 2usize.pow(i)) { - let control = vec![Dummy { _data: 42 }; size].into_boxed_slice(); - let mut copy = vec![Dummy { _data: 84 }; size].into_boxed_slice(); - let copy_raw = copy.as_ptr() as usize; - copy.clone_from(&control); - assert_eq!(copy.as_ptr() as usize, copy_raw); - } -} - -#[test] -fn box_deref_lval() { - let x = Box::new(Cell::new(5)); - x.set(1000); - assert_eq!(x.get(), 1000); -} - -pub struct ConstAllocator; - -unsafe impl Allocator for ConstAllocator { - fn allocate(&self, layout: Layout) -> Result, AllocError> { - match layout.size() { - 0 => Ok(NonNull::slice_from_raw_parts(layout.dangling(), 0)), - _ => unsafe { - let ptr = core::intrinsics::const_allocate(layout.size(), layout.align()); - Ok(NonNull::new_unchecked(ptr as *mut [u8; 0] as *mut [u8])) - }, - } - } - - unsafe fn deallocate(&self, _ptr: NonNull, layout: Layout) { - match layout.size() { - 0 => { /* do nothing */ } - _ => { /* do nothing too */ } - } - } - - fn allocate_zeroed(&self, layout: Layout) -> Result, AllocError> { - let ptr = self.allocate(layout)?; - if layout.size() > 0 { - unsafe { - ptr.as_mut_ptr().write_bytes(0, layout.size()); - } - } - Ok(ptr) - } - - unsafe fn grow( - &self, - ptr: NonNull, - old_layout: Layout, - new_layout: Layout, - ) -> Result, AllocError> { - debug_assert!( - new_layout.size() >= old_layout.size(), - "`new_layout.size()` must be greater than or equal to `old_layout.size()`" - ); - - let new_ptr = self.allocate(new_layout)?; - if new_layout.size() > 0 { - // Safety: `new_ptr` is valid for writes and `ptr` for reads of - // `old_layout.size()`, because `new_layout.size() >= - // old_layout.size()` (which is an invariant that must be upheld by - // callers). - unsafe { - new_ptr.as_mut_ptr().copy_from_nonoverlapping(ptr.as_ptr(), old_layout.size()); - } - // Safety: `ptr` is never used again is also an invariant which must - // be upheld by callers. - unsafe { - self.deallocate(ptr, old_layout); - } - } - Ok(new_ptr) - } - - unsafe fn grow_zeroed( - &self, - ptr: NonNull, - old_layout: Layout, - new_layout: Layout, - ) -> Result, AllocError> { - // Safety: Invariants of `grow_zeroed` and `grow` are the same, and must - // be enforced by callers. - let new_ptr = unsafe { self.grow(ptr, old_layout, new_layout)? }; - if new_layout.size() > 0 { - let old_size = old_layout.size(); - let new_size = new_layout.size(); - let raw_ptr = new_ptr.as_mut_ptr(); - // Safety: - // - `grow` returned Ok, so the returned pointer must be valid for - // `new_size` bytes - // - `new_size` must be larger than `old_size`, which is an - // invariant which must be upheld by callers. - unsafe { - raw_ptr.add(old_size).write_bytes(0, new_size - old_size); - } - } - Ok(new_ptr) - } - - unsafe fn shrink( - &self, - ptr: NonNull, - old_layout: Layout, - new_layout: Layout, - ) -> Result, AllocError> { - debug_assert!( - new_layout.size() <= old_layout.size(), - "`new_layout.size()` must be smaller than or equal to `old_layout.size()`" - ); - - let new_ptr = self.allocate(new_layout)?; - if new_layout.size() > 0 { - // Safety: `new_ptr` and `ptr` are valid for reads/writes of - // `new_layout.size()` because of the invariants of shrink, which - // include `new_layout.size()` being smaller than (or equal to) - // `old_layout.size()`. - unsafe { - new_ptr.as_mut_ptr().copy_from_nonoverlapping(ptr.as_ptr(), new_layout.size()); - } - // Safety: `ptr` is never used again is also an invariant which must - // be upheld by callers. - unsafe { - self.deallocate(ptr, old_layout); - } - } - Ok(new_ptr) - } - - fn by_ref(&self) -> &Self - where - Self: Sized, - { - self - } -} diff --git a/library/alloc/tests/btree_set_hash.rs b/library/alloc/tests/btree_set_hash.rs deleted file mode 100644 index ab275ac4353ac..0000000000000 --- a/library/alloc/tests/btree_set_hash.rs +++ /dev/null @@ -1,29 +0,0 @@ -use crate::hash; -use std::collections::BTreeSet; - -#[test] -fn test_hash() { - let mut x = BTreeSet::new(); - let mut y = BTreeSet::new(); - - x.insert(1); - x.insert(2); - x.insert(3); - - y.insert(3); - y.insert(2); - y.insert(1); - - assert_eq!(hash(&x), hash(&y)); -} - -#[test] -fn test_prefix_free() { - let x = BTreeSet::from([1, 2, 3]); - let y = BTreeSet::::new(); - - // If hashed by iteration alone, `(x, y)` and `(y, x)` would visit the same - // order of elements, resulting in the same hash. But now that we also hash - // the length, they get distinct sequences of hashed data. - assert_ne!(hash(&(&x, &y)), hash(&(&y, &x))); -} diff --git a/library/alloc/tests/c_str.rs b/library/alloc/tests/c_str.rs deleted file mode 100644 index 4a5817939567b..0000000000000 --- a/library/alloc/tests/c_str.rs +++ /dev/null @@ -1,19 +0,0 @@ -use std::borrow::Cow::{Borrowed, Owned}; -use std::ffi::CStr; -use std::os::raw::c_char; - -#[test] -fn to_str() { - let data = b"123\xE2\x80\xA6\0"; - let ptr = data.as_ptr() as *const c_char; - unsafe { - assert_eq!(CStr::from_ptr(ptr).to_str(), Ok("123…")); - assert_eq!(CStr::from_ptr(ptr).to_string_lossy(), Borrowed("123…")); - } - let data = b"123\xE2\0"; - let ptr = data.as_ptr() as *const c_char; - unsafe { - assert!(CStr::from_ptr(ptr).to_str().is_err()); - assert_eq!(CStr::from_ptr(ptr).to_string_lossy(), Owned::(format!("123\u{FFFD}"))); - } -} diff --git a/library/alloc/tests/const_fns.rs b/library/alloc/tests/const_fns.rs deleted file mode 100644 index 4e7d7fc833ea1..0000000000000 --- a/library/alloc/tests/const_fns.rs +++ /dev/null @@ -1,38 +0,0 @@ -// Test const functions in the library - -pub const MY_VEC: Vec = Vec::new(); - -// FIXME(#110395) -// pub const MY_VEC2: Vec = Default::default(); - -pub const MY_STRING: String = String::new(); - -// pub const MY_STRING2: String = Default::default(); - -// pub const MY_BOXED_SLICE: Box<[usize]> = Default::default(); -// pub const MY_BOXED_STR: Box = Default::default(); - -use std::collections::{BTreeMap, BTreeSet}; - -pub const MY_BTREEMAP: BTreeMap = BTreeMap::new(); -pub const MAP: &'static BTreeMap = &MY_BTREEMAP; -pub const MAP_LEN: usize = MAP.len(); -pub const MAP_IS_EMPTY: bool = MAP.is_empty(); - -pub const MY_BTREESET: BTreeSet = BTreeSet::new(); -pub const SET: &'static BTreeSet = &MY_BTREESET; -pub const SET_LEN: usize = SET.len(); -pub const SET_IS_EMPTY: bool = SET.is_empty(); - -#[test] -fn test_const() { - assert_eq!(MY_VEC, /* MY_VEC */ vec![]); - assert_eq!(MY_STRING, /* MY_STRING2 */ String::default()); - - // assert_eq!(MY_VEC, *MY_BOXED_SLICE); - // assert_eq!(MY_STRING, *MY_BOXED_STR); - - assert_eq!(MAP_LEN, 0); - assert_eq!(SET_LEN, 0); - assert!(MAP_IS_EMPTY && SET_IS_EMPTY); -} diff --git a/library/alloc/tests/cow_str.rs b/library/alloc/tests/cow_str.rs deleted file mode 100644 index 62a5c245a5429..0000000000000 --- a/library/alloc/tests/cow_str.rs +++ /dev/null @@ -1,144 +0,0 @@ -use std::borrow::Cow; - -// check that Cow<'a, str> implements addition -#[test] -fn check_cow_add_cow() { - let borrowed1 = Cow::Borrowed("Hello, "); - let borrowed2 = Cow::Borrowed("World!"); - let borrow_empty = Cow::Borrowed(""); - - let owned1: Cow<'_, str> = Cow::Owned(String::from("Hi, ")); - let owned2: Cow<'_, str> = Cow::Owned(String::from("Rustaceans!")); - let owned_empty: Cow<'_, str> = Cow::Owned(String::new()); - - assert_eq!("Hello, World!", borrowed1.clone() + borrowed2.clone()); - assert_eq!("Hello, Rustaceans!", borrowed1.clone() + owned2.clone()); - - assert_eq!("Hi, World!", owned1.clone() + borrowed2.clone()); - assert_eq!("Hi, Rustaceans!", owned1.clone() + owned2.clone()); - - if let Cow::Owned(_) = borrowed1.clone() + borrow_empty.clone() { - panic!("Adding empty strings to a borrow should note allocate"); - } - if let Cow::Owned(_) = borrow_empty.clone() + borrowed1.clone() { - panic!("Adding empty strings to a borrow should note allocate"); - } - if let Cow::Owned(_) = borrowed1.clone() + owned_empty.clone() { - panic!("Adding empty strings to a borrow should note allocate"); - } - if let Cow::Owned(_) = owned_empty.clone() + borrowed1.clone() { - panic!("Adding empty strings to a borrow should note allocate"); - } -} - -#[test] -fn check_cow_add_str() { - let borrowed = Cow::Borrowed("Hello, "); - let borrow_empty = Cow::Borrowed(""); - - let owned: Cow<'_, str> = Cow::Owned(String::from("Hi, ")); - let owned_empty: Cow<'_, str> = Cow::Owned(String::new()); - - assert_eq!("Hello, World!", borrowed.clone() + "World!"); - - assert_eq!("Hi, World!", owned.clone() + "World!"); - - if let Cow::Owned(_) = borrowed.clone() + "" { - panic!("Adding empty strings to a borrow should note allocate"); - } - if let Cow::Owned(_) = borrow_empty.clone() + "Hello, " { - panic!("Adding empty strings to a borrow should note allocate"); - } - if let Cow::Owned(_) = owned_empty.clone() + "Hello, " { - panic!("Adding empty strings to a borrow should note allocate"); - } -} - -#[test] -fn check_cow_add_assign_cow() { - let mut borrowed1 = Cow::Borrowed("Hello, "); - let borrowed2 = Cow::Borrowed("World!"); - let borrow_empty = Cow::Borrowed(""); - - let mut owned1: Cow<'_, str> = Cow::Owned(String::from("Hi, ")); - let owned2: Cow<'_, str> = Cow::Owned(String::from("Rustaceans!")); - let owned_empty: Cow<'_, str> = Cow::Owned(String::new()); - - let mut s = borrowed1.clone(); - s += borrow_empty.clone(); - assert_eq!("Hello, ", s); - if let Cow::Owned(_) = s { - panic!("Adding empty strings to a borrow should note allocate"); - } - let mut s = borrow_empty.clone(); - s += borrowed1.clone(); - assert_eq!("Hello, ", s); - if let Cow::Owned(_) = s { - panic!("Adding empty strings to a borrow should note allocate"); - } - let mut s = borrowed1.clone(); - s += owned_empty.clone(); - assert_eq!("Hello, ", s); - if let Cow::Owned(_) = s { - panic!("Adding empty strings to a borrow should note allocate"); - } - let mut s = owned_empty.clone(); - s += borrowed1.clone(); - assert_eq!("Hello, ", s); - if let Cow::Owned(_) = s { - panic!("Adding empty strings to a borrow should note allocate"); - } - - owned1 += borrowed2; - borrowed1 += owned2; - - assert_eq!("Hi, World!", owned1); - assert_eq!("Hello, Rustaceans!", borrowed1); -} - -#[test] -fn check_cow_add_assign_str() { - let mut borrowed = Cow::Borrowed("Hello, "); - let borrow_empty = Cow::Borrowed(""); - - let mut owned: Cow<'_, str> = Cow::Owned(String::from("Hi, ")); - let owned_empty: Cow<'_, str> = Cow::Owned(String::new()); - - let mut s = borrowed.clone(); - s += ""; - assert_eq!("Hello, ", s); - if let Cow::Owned(_) = s { - panic!("Adding empty strings to a borrow should note allocate"); - } - let mut s = borrow_empty.clone(); - s += "World!"; - assert_eq!("World!", s); - if let Cow::Owned(_) = s { - panic!("Adding empty strings to a borrow should note allocate"); - } - let mut s = owned_empty.clone(); - s += "World!"; - assert_eq!("World!", s); - if let Cow::Owned(_) = s { - panic!("Adding empty strings to a borrow should note allocate"); - } - - owned += "World!"; - borrowed += "World!"; - - assert_eq!("Hi, World!", owned); - assert_eq!("Hello, World!", borrowed); -} - -#[test] -fn check_cow_clone_from() { - let mut c1: Cow<'_, str> = Cow::Owned(String::with_capacity(25)); - let s: String = "hi".to_string(); - assert!(s.capacity() < 25); - let c2: Cow<'_, str> = Cow::Owned(s); - c1.clone_from(&c2); - assert!(c1.into_owned().capacity() >= 25); - let mut c3: Cow<'_, str> = Cow::Borrowed("bye"); - c3.clone_from(&c2); - assert_eq!(c2, c3); -} diff --git a/library/alloc/tests/fmt.rs b/library/alloc/tests/fmt.rs deleted file mode 100644 index 379e09ab69a3c..0000000000000 --- a/library/alloc/tests/fmt.rs +++ /dev/null @@ -1,324 +0,0 @@ -#![deny(warnings)] - -use std::cell::RefCell; -use std::fmt::{self, Write}; -use std::ptr; - -#[test] -fn test_format() { - let s = fmt::format(format_args!("Hello, {}!", "world")); - assert_eq!(s, "Hello, world!"); -} - -struct A; -struct B; -struct C; -struct D; - -impl fmt::LowerHex for A { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str("aloha") - } -} -impl fmt::UpperHex for B { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str("adios") - } -} -impl fmt::Display for C { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.pad_integral(true, "☃", "123") - } -} -impl fmt::Binary for D { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str("aa")?; - f.write_char('☃')?; - f.write_str("bb") - } -} - -macro_rules! t { - ($a:expr, $b:expr) => { - assert_eq!($a, $b) - }; -} - -#[test] -fn test_format_macro_interface() { - // Various edge cases without formats - t!(format!(""), ""); - t!(format!("hello"), "hello"); - t!(format!("hello {{"), "hello {"); - - // default formatters should work - t!(format!("{}", 1.0f32), "1"); - t!(format!("{}", 1.0f64), "1"); - t!(format!("{}", "a"), "a"); - t!(format!("{}", "a".to_string()), "a"); - t!(format!("{}", false), "false"); - t!(format!("{}", 'a'), "a"); - - // At least exercise all the formats - t!(format!("{}", true), "true"); - t!(format!("{}", '☃'), "☃"); - t!(format!("{}", 10), "10"); - t!(format!("{}", 10_usize), "10"); - t!(format!("{:?}", '☃'), "'☃'"); - t!(format!("{:?}", 10), "10"); - t!(format!("{:?}", 10_usize), "10"); - t!(format!("{:?}", "true"), "\"true\""); - t!(format!("{:?}", "foo\nbar"), "\"foo\\nbar\""); - t!(format!("{:?}", "foo\n\"bar\"\r\n\'baz\'\t\\qux\\"), r#""foo\n\"bar\"\r\n'baz'\t\\qux\\""#); - t!(format!("{:?}", "foo\0bar\x01baz\u{7f}q\u{75}x"), r#""foo\0bar\u{1}baz\u{7f}qux""#); - t!(format!("{:o}", 10_usize), "12"); - t!(format!("{:x}", 10_usize), "a"); - t!(format!("{:X}", 10_usize), "A"); - t!(format!("{}", "foo"), "foo"); - t!(format!("{}", "foo".to_string()), "foo"); - if cfg!(target_pointer_width = "32") { - t!(format!("{:#p}", ptr::without_provenance::(0x1234)), "0x00001234"); - t!(format!("{:#p}", ptr::without_provenance_mut::(0x1234)), "0x00001234"); - } else { - t!(format!("{:#p}", ptr::without_provenance::(0x1234)), "0x0000000000001234"); - t!(format!("{:#p}", ptr::without_provenance_mut::(0x1234)), "0x0000000000001234"); - } - t!(format!("{:p}", ptr::without_provenance::(0x1234)), "0x1234"); - t!(format!("{:p}", ptr::without_provenance_mut::(0x1234)), "0x1234"); - t!(format!("{A:x}"), "aloha"); - t!(format!("{B:X}"), "adios"); - t!(format!("foo {} ☃☃☃☃☃☃", "bar"), "foo bar ☃☃☃☃☃☃"); - t!(format!("{1} {0}", 0, 1), "1 0"); - t!(format!("{foo} {bar}", foo = 0, bar = 1), "0 1"); - t!(format!("{foo} {1} {bar} {0}", 0, 1, foo = 2, bar = 3), "2 1 3 0"); - t!(format!("{} {0}", "a"), "a a"); - t!(format!("{_foo}", _foo = 6usize), "6"); - t!(format!("{foo_bar}", foo_bar = 1), "1"); - t!(format!("{}", 5 + 5), "10"); - t!(format!("{C:#4}"), "☃123"); - t!(format!("{D:b}"), "aa☃bb"); - - let a: &dyn fmt::Debug = &1; - t!(format!("{a:?}"), "1"); - - // Formatting strings and their arguments - t!(format!("{}", "a"), "a"); - t!(format!("{:4}", "a"), "a "); - t!(format!("{:4}", "☃"), "☃ "); - t!(format!("{:>4}", "a"), " a"); - t!(format!("{:<4}", "a"), "a "); - t!(format!("{:^5}", "a"), " a "); - t!(format!("{:^5}", "aa"), " aa "); - t!(format!("{:^4}", "a"), " a "); - t!(format!("{:^4}", "aa"), " aa "); - t!(format!("{:.4}", "a"), "a"); - t!(format!("{:4.4}", "a"), "a "); - t!(format!("{:4.4}", "aaaaaaaaaaaaaaaaaa"), "aaaa"); - t!(format!("{:<4.4}", "aaaaaaaaaaaaaaaaaa"), "aaaa"); - t!(format!("{:>4.4}", "aaaaaaaaaaaaaaaaaa"), "aaaa"); - t!(format!("{:^4.4}", "aaaaaaaaaaaaaaaaaa"), "aaaa"); - t!(format!("{:>10.4}", "aaaaaaaaaaaaaaaaaa"), " aaaa"); - t!(format!("{:2.4}", "aaaaa"), "aaaa"); - t!(format!("{:2.4}", "aaaa"), "aaaa"); - t!(format!("{:2.4}", "aaa"), "aaa"); - t!(format!("{:2.4}", "aa"), "aa"); - t!(format!("{:2.4}", "a"), "a "); - t!(format!("{:0>2}", "a"), "0a"); - t!(format!("{:.*}", 4, "aaaaaaaaaaaaaaaaaa"), "aaaa"); - t!(format!("{:.1$}", "aaaaaaaaaaaaaaaaaa", 4), "aaaa"); - t!(format!("{:.a$}", "aaaaaaaaaaaaaaaaaa", a = 4), "aaaa"); - t!(format!("{:._a$}", "aaaaaaaaaaaaaaaaaa", _a = 4), "aaaa"); - t!(format!("{:1$}", "a", 4), "a "); - t!(format!("{1:0$}", 4, "a"), "a "); - t!(format!("{:a$}", "a", a = 4), "a "); - t!(format!("{:-#}", "a"), "a"); - t!(format!("{:+#}", "a"), "a"); - t!(format!("{:/^10.8}", "1234567890"), "/12345678/"); - - // Some float stuff - t!(format!("{:}", 1.0f32), "1"); - t!(format!("{:}", 1.0f64), "1"); - t!(format!("{:.3}", 1.0f64), "1.000"); - t!(format!("{:10.3}", 1.0f64), " 1.000"); - t!(format!("{:+10.3}", 1.0f64), " +1.000"); - t!(format!("{:+10.3}", -1.0f64), " -1.000"); - - t!(format!("{:e}", 1.2345e6f32), "1.2345e6"); - t!(format!("{:e}", 1.2345e6f64), "1.2345e6"); - t!(format!("{:E}", 1.2345e6f64), "1.2345E6"); - t!(format!("{:.3e}", 1.2345e6f64), "1.234e6"); - t!(format!("{:10.3e}", 1.2345e6f64), " 1.234e6"); - t!(format!("{:+10.3e}", 1.2345e6f64), " +1.234e6"); - t!(format!("{:+10.3e}", -1.2345e6f64), " -1.234e6"); - - // Float edge cases - t!(format!("{}", -0.0), "-0"); - t!(format!("{:?}", 0.0), "0.0"); - - // sign aware zero padding - t!(format!("{:<3}", 1), "1 "); - t!(format!("{:>3}", 1), " 1"); - t!(format!("{:^3}", 1), " 1 "); - t!(format!("{:03}", 1), "001"); - t!(format!("{:<03}", 1), "001"); - t!(format!("{:>03}", 1), "001"); - t!(format!("{:^03}", 1), "001"); - t!(format!("{:+03}", 1), "+01"); - t!(format!("{:<+03}", 1), "+01"); - t!(format!("{:>+03}", 1), "+01"); - t!(format!("{:^+03}", 1), "+01"); - t!(format!("{:#05x}", 1), "0x001"); - t!(format!("{:<#05x}", 1), "0x001"); - t!(format!("{:>#05x}", 1), "0x001"); - t!(format!("{:^#05x}", 1), "0x001"); - t!(format!("{:05}", 1.2), "001.2"); - t!(format!("{:<05}", 1.2), "001.2"); - t!(format!("{:>05}", 1.2), "001.2"); - t!(format!("{:^05}", 1.2), "001.2"); - t!(format!("{:05}", -1.2), "-01.2"); - t!(format!("{:<05}", -1.2), "-01.2"); - t!(format!("{:>05}", -1.2), "-01.2"); - t!(format!("{:^05}", -1.2), "-01.2"); - t!(format!("{:+05}", 1.2), "+01.2"); - t!(format!("{:<+05}", 1.2), "+01.2"); - t!(format!("{:>+05}", 1.2), "+01.2"); - t!(format!("{:^+05}", 1.2), "+01.2"); - - // Ergonomic format_args! - t!(format!("{0:x} {0:X}", 15), "f F"); - t!(format!("{0:x} {0:X} {}", 15), "f F 15"); - t!(format!("{:x}{0:X}{a:x}{:X}{1:x}{a:X}", 13, 14, a = 15), "dDfEeF"); - t!(format!("{a:x} {a:X}", a = 15), "f F"); - - // And its edge cases - t!( - format!( - "{a:.0$} {b:.0$} {0:.0$}\n{a:.c$} {b:.c$} {c:.c$}", - 4, - a = "abcdefg", - b = "hijklmn", - c = 3 - ), - "abcd hijk 4\nabc hij 3" - ); - t!(format!("{a:.*} {0} {:.*}", 4, 3, "efgh", a = "abcdef"), "abcd 4 efg"); - t!(format!("{:.a$} {a} {a:#x}", "aaaaaa", a = 2), "aa 2 0x2"); - - // Test that pointers don't get truncated. - { - let val = usize::MAX; - let exp = format!("{val:#x}"); - t!(format!("{:p}", std::ptr::without_provenance::(val)), exp); - } - - // Escaping - t!(format!("{{"), "{"); - t!(format!("}}"), "}"); - - // make sure that format! doesn't move out of local variables - let a = Box::new(3); - format!("{a}"); - format!("{a}"); - - // make sure that format! doesn't cause spurious unused-unsafe warnings when - // it's inside of an outer unsafe block - unsafe { - let a: isize = ::std::mem::transmute(3_usize); - format!("{a}"); - } - - // test that trailing commas are acceptable - format!("{}", "test",); - format!("{foo}", foo = "test",); -} - -// Basic test to make sure that we can invoke the `write!` macro with an -// fmt::Write instance. -#[test] -fn test_write() { - let mut buf = String::new(); - let _ = write!(&mut buf, "{}", 3); - { - let w = &mut buf; - let _ = write!(w, "{foo}", foo = 4); - let _ = write!(w, "{}", "hello"); - let _ = writeln!(w, "{}", "line"); - let _ = writeln!(w, "{foo}", foo = "bar"); - let _ = w.write_char('☃'); - let _ = w.write_str("str"); - } - - t!(buf, "34helloline\nbar\n☃str"); -} - -// Just make sure that the macros are defined, there's not really a lot that we -// can do with them just yet (to test the output) -#[test] -fn test_print() { - print!("hi"); - print!("{:?}", vec![0u8]); - println!("hello"); - println!("this is a {}", "test"); - println!("{foo}", foo = "bar"); -} - -// Just make sure that the macros are defined, there's not really a lot that we -// can do with them just yet (to test the output) -#[test] -fn test_format_args() { - let mut buf = String::new(); - { - let w = &mut buf; - let _ = write!(w, "{}", format_args!("{}", 1)); - let _ = write!(w, "{}", format_args!("test")); - let _ = write!(w, "{}", format_args!("{test}", test = 3)); - } - let s = buf; - t!(s, "1test3"); - - let s = fmt::format(format_args!("hello {}", "world")); - t!(s, "hello world"); - let s = format!("{}: {}", "args were", format_args!("hello {}", "world")); - t!(s, "args were: hello world"); -} - -#[test] -fn test_order() { - // Make sure format!() arguments are always evaluated in a left-to-right - // ordering - fn foo() -> isize { - static mut FOO: isize = 0; - unsafe { - FOO += 1; - FOO - } - } - assert_eq!( - format!("{} {} {a} {b} {} {c}", foo(), foo(), foo(), a = foo(), b = foo(), c = foo()), - "1 2 4 5 3 6".to_string() - ); -} - -#[test] -fn test_once() { - // Make sure each argument are evaluated only once even though it may be - // formatted multiple times - fn foo() -> isize { - static mut FOO: isize = 0; - unsafe { - FOO += 1; - FOO - } - } - assert_eq!(format!("{0} {0} {0} {a} {a} {a}", foo(), a = foo()), "1 1 1 2 2 2".to_string()); -} - -#[test] -fn test_refcell() { - let refcell = RefCell::new(5); - assert_eq!(format!("{refcell:?}"), "RefCell { value: 5 }"); - let borrow = refcell.borrow_mut(); - assert_eq!(format!("{refcell:?}"), "RefCell { value: }"); - drop(borrow); - assert_eq!(format!("{refcell:?}"), "RefCell { value: 5 }"); -} diff --git a/library/alloc/tests/heap.rs b/library/alloc/tests/heap.rs deleted file mode 100644 index 246b341eeb387..0000000000000 --- a/library/alloc/tests/heap.rs +++ /dev/null @@ -1,44 +0,0 @@ -use std::alloc::{Allocator, Global, Layout, System}; - -/// Issue #45955 and #62251. -#[test] -fn alloc_system_overaligned_request() { - check_overalign_requests(System) -} - -#[test] -fn std_heap_overaligned_request() { - check_overalign_requests(Global) -} - -fn check_overalign_requests(allocator: T) { - for &align in &[4, 8, 16, 32] { - // less than and bigger than `MIN_ALIGN` - for &size in &[align / 2, align - 1] { - // size less than alignment - let iterations = 128; - unsafe { - let pointers: Vec<_> = (0..iterations) - .map(|_| { - allocator.allocate(Layout::from_size_align(size, align).unwrap()).unwrap() - }) - .collect(); - for &ptr in &pointers { - assert_eq!( - (ptr.as_non_null_ptr().as_ptr() as usize) % align, - 0, - "Got a pointer less aligned than requested" - ) - } - - // Clean up - for &ptr in &pointers { - allocator.deallocate( - ptr.as_non_null_ptr(), - Layout::from_size_align(size, align).unwrap(), - ) - } - } - } - } -} diff --git a/library/alloc/tests/lib.rs b/library/alloc/tests/lib.rs deleted file mode 100644 index 0eae4ca4b8ba3..0000000000000 --- a/library/alloc/tests/lib.rs +++ /dev/null @@ -1,91 +0,0 @@ -#![feature(allocator_api)] -#![feature(alloc_layout_extra)] -#![feature(iter_array_chunks)] -#![feature(assert_matches)] -#![feature(btree_extract_if)] -#![feature(cow_is_borrowed)] -#![feature(const_cow_is_borrowed)] -#![feature(const_heap)] -#![feature(const_mut_refs)] -#![feature(const_slice_from_raw_parts_mut)] -#![feature(const_ptr_write)] -#![feature(const_try)] -#![feature(core_intrinsics)] -#![feature(extract_if)] -#![feature(exact_size_is_empty)] -#![feature(linked_list_cursors)] -#![feature(map_try_insert)] -#![feature(new_uninit)] -#![feature(pattern)] -#![feature(trusted_len)] -#![feature(try_reserve_kind)] -#![feature(try_with_capacity)] -#![feature(unboxed_closures)] -#![feature(binary_heap_into_iter_sorted)] -#![feature(binary_heap_drain_sorted)] -#![feature(slice_ptr_get)] -#![feature(binary_heap_as_slice)] -#![feature(inplace_iteration)] -#![feature(iter_advance_by)] -#![feature(iter_next_chunk)] -#![feature(round_char_boundary)] -#![feature(slice_partition_dedup)] -#![feature(string_remove_matches)] -#![feature(const_btree_len)] -#![feature(const_trait_impl)] -#![feature(const_str_from_utf8)] -#![feature(panic_update_hook)] -#![feature(pointer_is_aligned_to)] -#![feature(slice_flatten)] -#![feature(thin_box)] -#![feature(strict_provenance)] -#![feature(drain_keep_rest)] -#![feature(local_waker)] -#![feature(vec_pop_if)] -#![allow(internal_features)] -#![deny(fuzzy_provenance_casts)] -#![deny(unsafe_op_in_unsafe_fn)] - -use std::hash::{DefaultHasher, Hash, Hasher}; - -mod arc; -mod autotraits; -mod borrow; -mod boxed; -mod btree_set_hash; -mod c_str; -mod const_fns; -mod cow_str; -mod fmt; -mod heap; -mod linked_list; -mod rc; -mod slice; -mod str; -mod string; -mod task; -mod thin_box; -mod vec; -mod vec_deque; - -fn hash(t: &T) -> u64 { - let mut s = DefaultHasher::new(); - t.hash(&mut s); - s.finish() -} - -// FIXME: Instantiated functions with i128 in the signature is not supported in Emscripten. -// See https://github.com/kripken/emscripten-fastcomp/issues/169 -#[cfg(not(target_os = "emscripten"))] -#[test] -fn test_boxed_hasher() { - let ordinary_hash = hash(&5u32); - - let mut hasher_1 = Box::new(DefaultHasher::new()); - 5u32.hash(&mut hasher_1); - assert_eq!(ordinary_hash, hasher_1.finish()); - - let mut hasher_2 = Box::new(DefaultHasher::new()) as Box; - 5u32.hash(&mut hasher_2); - assert_eq!(ordinary_hash, hasher_2.finish()); -} diff --git a/library/alloc/tests/linked_list.rs b/library/alloc/tests/linked_list.rs deleted file mode 100644 index 65b09cb00c45d..0000000000000 --- a/library/alloc/tests/linked_list.rs +++ /dev/null @@ -1,21 +0,0 @@ -use std::collections::LinkedList; - -#[test] -fn test_hash() { - use crate::hash; - - let mut x = LinkedList::new(); - let mut y = LinkedList::new(); - - assert!(hash(&x) == hash(&y)); - - x.push_back(1); - x.push_back(2); - x.push_back(3); - - y.push_front(3); - y.push_front(2); - y.push_front(1); - - assert!(hash(&x) == hash(&y)); -} diff --git a/library/alloc/tests/rc.rs b/library/alloc/tests/rc.rs deleted file mode 100644 index 499740e738ab0..0000000000000 --- a/library/alloc/tests/rc.rs +++ /dev/null @@ -1,207 +0,0 @@ -use std::any::Any; -use std::cell::RefCell; -use std::iter::TrustedLen; -use std::mem; -use std::rc::{Rc, Weak}; - -#[test] -fn uninhabited() { - enum Void {} - let mut a = Weak::::new(); - a = a.clone(); - assert!(a.upgrade().is_none()); - - let mut a: Weak = a; // Unsizing - a = a.clone(); - assert!(a.upgrade().is_none()); -} - -#[test] -fn slice() { - let a: Rc<[u32; 3]> = Rc::new([3, 2, 1]); - let a: Rc<[u32]> = a; // Unsizing - let b: Rc<[u32]> = Rc::from(&[3, 2, 1][..]); // Conversion - assert_eq!(a, b); - - // Exercise is_dangling() with a DST - let mut a = Rc::downgrade(&a); - a = a.clone(); - assert!(a.upgrade().is_some()); -} - -#[test] -fn trait_object() { - let a: Rc = Rc::new(4); - let a: Rc = a; // Unsizing - - // Exercise is_dangling() with a DST - let mut a = Rc::downgrade(&a); - a = a.clone(); - assert!(a.upgrade().is_some()); - - let mut b = Weak::::new(); - b = b.clone(); - assert!(b.upgrade().is_none()); - let mut b: Weak = b; // Unsizing - b = b.clone(); - assert!(b.upgrade().is_none()); -} - -#[test] -fn float_nan_ne() { - let x = Rc::new(f32::NAN); - assert!(x != x); - assert!(!(x == x)); -} - -#[test] -fn partial_eq() { - struct TestPEq(RefCell); - impl PartialEq for TestPEq { - fn eq(&self, other: &TestPEq) -> bool { - *self.0.borrow_mut() += 1; - *other.0.borrow_mut() += 1; - true - } - } - let x = Rc::new(TestPEq(RefCell::new(0))); - assert!(x == x); - assert!(!(x != x)); - assert_eq!(*x.0.borrow(), 4); -} - -#[test] -fn eq() { - #[derive(Eq)] - struct TestEq(RefCell); - impl PartialEq for TestEq { - fn eq(&self, other: &TestEq) -> bool { - *self.0.borrow_mut() += 1; - *other.0.borrow_mut() += 1; - true - } - } - let x = Rc::new(TestEq(RefCell::new(0))); - assert!(x == x); - assert!(!(x != x)); - assert_eq!(*x.0.borrow(), 0); -} - -const SHARED_ITER_MAX: u16 = 100; - -fn assert_trusted_len(_: &I) {} - -#[test] -fn shared_from_iter_normal() { - // Exercise the base implementation for non-`TrustedLen` iterators. - { - // `Filter` is never `TrustedLen` since we don't - // know statically how many elements will be kept: - let iter = (0..SHARED_ITER_MAX).filter(|x| x % 2 == 0).map(Box::new); - - // Collecting into a `Vec` or `Rc<[T]>` should make no difference: - let vec = iter.clone().collect::>(); - let rc = iter.collect::>(); - assert_eq!(&*vec, &*rc); - - // Clone a bit and let these get dropped. - { - let _rc_2 = rc.clone(); - let _rc_3 = rc.clone(); - let _rc_4 = Rc::downgrade(&_rc_3); - } - } // Drop what hasn't been here. -} - -#[test] -fn shared_from_iter_trustedlen_normal() { - // Exercise the `TrustedLen` implementation under normal circumstances - // where `size_hint()` matches `(_, Some(exact_len))`. - { - let iter = (0..SHARED_ITER_MAX).map(Box::new); - assert_trusted_len(&iter); - - // Collecting into a `Vec` or `Rc<[T]>` should make no difference: - let vec = iter.clone().collect::>(); - let rc = iter.collect::>(); - assert_eq!(&*vec, &*rc); - assert_eq!(mem::size_of::>() * SHARED_ITER_MAX as usize, mem::size_of_val(&*rc)); - - // Clone a bit and let these get dropped. - { - let _rc_2 = rc.clone(); - let _rc_3 = rc.clone(); - let _rc_4 = Rc::downgrade(&_rc_3); - } - } // Drop what hasn't been here. - - // Try a ZST to make sure it is handled well. - { - let iter = (0..SHARED_ITER_MAX).map(drop); - let vec = iter.clone().collect::>(); - let rc = iter.collect::>(); - assert_eq!(&*vec, &*rc); - assert_eq!(0, mem::size_of_val(&*rc)); - { - let _rc_2 = rc.clone(); - let _rc_3 = rc.clone(); - let _rc_4 = Rc::downgrade(&_rc_3); - } - } -} - -#[test] -#[should_panic = "I've almost got 99 problems."] -fn shared_from_iter_trustedlen_panic() { - // Exercise the `TrustedLen` implementation when `size_hint()` matches - // `(_, Some(exact_len))` but where `.next()` drops before the last iteration. - let iter = (0..SHARED_ITER_MAX).map(|val| match val { - 98 => panic!("I've almost got 99 problems."), - _ => Box::new(val), - }); - assert_trusted_len(&iter); - let _ = iter.collect::>(); - - panic!("I am unreachable."); -} - -#[test] -fn shared_from_iter_trustedlen_no_fuse() { - // Exercise the `TrustedLen` implementation when `size_hint()` matches - // `(_, Some(exact_len))` but where the iterator does not behave in a fused manner. - struct Iter(std::vec::IntoIter>>); - - unsafe impl TrustedLen for Iter {} - - impl Iterator for Iter { - fn size_hint(&self) -> (usize, Option) { - (2, Some(2)) - } - - type Item = Box; - - fn next(&mut self) -> Option { - self.0.next().flatten() - } - } - - let vec = vec![Some(Box::new(42)), Some(Box::new(24)), None, Some(Box::new(12))]; - let iter = Iter(vec.into_iter()); - assert_trusted_len(&iter); - assert_eq!(&[Box::new(42), Box::new(24)], &*iter.collect::>()); -} - -#[test] -fn weak_may_dangle() { - fn hmm<'a>(val: &'a mut Weak<&'a str>) -> Weak<&'a str> { - val.clone() - } - - // Without #[may_dangle] we get: - let mut val = Weak::new(); - hmm(&mut val); - // ~~~~~~~~ borrowed value does not live long enough - // - // `val` dropped here while still borrowed - // borrow might be used here, when `val` is dropped and runs the `Drop` code for type `std::rc::Weak` -} diff --git a/library/alloc/tests/slice.rs b/library/alloc/tests/slice.rs deleted file mode 100644 index c0f7a11a93e12..0000000000000 --- a/library/alloc/tests/slice.rs +++ /dev/null @@ -1,1672 +0,0 @@ -use std::cmp::Ordering::{Equal, Greater, Less}; -use std::convert::identity; -use std::fmt; -use std::mem; -use std::panic; -use std::rc::Rc; - -fn square(n: usize) -> usize { - n * n -} - -fn is_odd(n: &usize) -> bool { - *n % 2 == 1 -} - -#[test] -fn test_from_fn() { - // Test on-stack from_fn. - let mut v: Vec<_> = (0..3).map(square).collect(); - { - let v = v; - assert_eq!(v.len(), 3); - assert_eq!(v[0], 0); - assert_eq!(v[1], 1); - assert_eq!(v[2], 4); - } - - // Test on-heap from_fn. - v = (0..5).map(square).collect(); - { - let v = v; - assert_eq!(v.len(), 5); - assert_eq!(v[0], 0); - assert_eq!(v[1], 1); - assert_eq!(v[2], 4); - assert_eq!(v[3], 9); - assert_eq!(v[4], 16); - } -} - -#[test] -fn test_from_elem() { - // Test on-stack from_elem. - let mut v = vec![10, 10]; - { - let v = v; - assert_eq!(v.len(), 2); - assert_eq!(v[0], 10); - assert_eq!(v[1], 10); - } - - // Test on-heap from_elem. - v = vec![20; 6]; - { - let v = &v[..]; - assert_eq!(v[0], 20); - assert_eq!(v[1], 20); - assert_eq!(v[2], 20); - assert_eq!(v[3], 20); - assert_eq!(v[4], 20); - assert_eq!(v[5], 20); - } -} - -#[test] -fn test_is_empty() { - let xs: [i32; 0] = []; - assert!(xs.is_empty()); - assert!(![0].is_empty()); -} - -#[test] -fn test_len_divzero() { - type Z = [i8; 0]; - let v0: &[Z] = &[]; - let v1: &[Z] = &[[]]; - let v2: &[Z] = &[[], []]; - assert_eq!(mem::size_of::(), 0); - assert_eq!(v0.len(), 0); - assert_eq!(v1.len(), 1); - assert_eq!(v2.len(), 2); -} - -#[test] -fn test_get() { - let mut a = vec![11]; - assert_eq!(a.get(1), None); - a = vec![11, 12]; - assert_eq!(a.get(1).unwrap(), &12); - a = vec![11, 12, 13]; - assert_eq!(a.get(1).unwrap(), &12); -} - -#[test] -fn test_first() { - let mut a = vec![]; - assert_eq!(a.first(), None); - a = vec![11]; - assert_eq!(a.first().unwrap(), &11); - a = vec![11, 12]; - assert_eq!(a.first().unwrap(), &11); -} - -#[test] -fn test_first_mut() { - let mut a = vec![]; - assert_eq!(a.first_mut(), None); - a = vec![11]; - assert_eq!(*a.first_mut().unwrap(), 11); - a = vec![11, 12]; - assert_eq!(*a.first_mut().unwrap(), 11); -} - -#[test] -fn test_split_first() { - let mut a = vec![11]; - let b: &[i32] = &[]; - assert!(b.split_first().is_none()); - assert_eq!(a.split_first(), Some((&11, b))); - a = vec![11, 12]; - let b: &[i32] = &[12]; - assert_eq!(a.split_first(), Some((&11, b))); -} - -#[test] -fn test_split_first_mut() { - let mut a = vec![11]; - let b: &mut [i32] = &mut []; - assert!(b.split_first_mut().is_none()); - assert!(a.split_first_mut() == Some((&mut 11, b))); - a = vec![11, 12]; - let b: &mut [_] = &mut [12]; - assert!(a.split_first_mut() == Some((&mut 11, b))); -} - -#[test] -fn test_split_last() { - let mut a = vec![11]; - let b: &[i32] = &[]; - assert!(b.split_last().is_none()); - assert_eq!(a.split_last(), Some((&11, b))); - a = vec![11, 12]; - let b: &[_] = &[11]; - assert_eq!(a.split_last(), Some((&12, b))); -} - -#[test] -fn test_split_last_mut() { - let mut a = vec![11]; - let b: &mut [i32] = &mut []; - assert!(b.split_last_mut().is_none()); - assert!(a.split_last_mut() == Some((&mut 11, b))); - - a = vec![11, 12]; - let b: &mut [_] = &mut [11]; - assert!(a.split_last_mut() == Some((&mut 12, b))); -} - -#[test] -fn test_last() { - let mut a = vec![]; - assert_eq!(a.last(), None); - a = vec![11]; - assert_eq!(a.last().unwrap(), &11); - a = vec![11, 12]; - assert_eq!(a.last().unwrap(), &12); -} - -#[test] -fn test_last_mut() { - let mut a = vec![]; - assert_eq!(a.last_mut(), None); - a = vec![11]; - assert_eq!(*a.last_mut().unwrap(), 11); - a = vec![11, 12]; - assert_eq!(*a.last_mut().unwrap(), 12); -} - -#[test] -fn test_slice() { - // Test fixed length vector. - let vec_fixed = [1, 2, 3, 4]; - let v_a = vec_fixed[1..vec_fixed.len()].to_vec(); - assert_eq!(v_a.len(), 3); - - assert_eq!(v_a[0], 2); - assert_eq!(v_a[1], 3); - assert_eq!(v_a[2], 4); - - // Test on stack. - let vec_stack: &[_] = &[1, 2, 3]; - let v_b = vec_stack[1..3].to_vec(); - assert_eq!(v_b.len(), 2); - - assert_eq!(v_b[0], 2); - assert_eq!(v_b[1], 3); - - // Test `Box<[T]>` - let vec_unique = vec![1, 2, 3, 4, 5, 6]; - let v_d = vec_unique[1..6].to_vec(); - assert_eq!(v_d.len(), 5); - - assert_eq!(v_d[0], 2); - assert_eq!(v_d[1], 3); - assert_eq!(v_d[2], 4); - assert_eq!(v_d[3], 5); - assert_eq!(v_d[4], 6); -} - -#[test] -fn test_slice_from() { - let vec: &[_] = &[1, 2, 3, 4]; - assert_eq!(&vec[..], vec); - let b: &[_] = &[3, 4]; - assert_eq!(&vec[2..], b); - let b: &[_] = &[]; - assert_eq!(&vec[4..], b); -} - -#[test] -fn test_slice_to() { - let vec: &[_] = &[1, 2, 3, 4]; - assert_eq!(&vec[..4], vec); - let b: &[_] = &[1, 2]; - assert_eq!(&vec[..2], b); - let b: &[_] = &[]; - assert_eq!(&vec[..0], b); -} - -#[test] -fn test_pop() { - let mut v = vec![5]; - let e = v.pop(); - assert_eq!(v.len(), 0); - assert_eq!(e, Some(5)); - let f = v.pop(); - assert_eq!(f, None); - let g = v.pop(); - assert_eq!(g, None); -} - -#[test] -fn test_swap_remove() { - let mut v = vec![1, 2, 3, 4, 5]; - let mut e = v.swap_remove(0); - assert_eq!(e, 1); - assert_eq!(v, [5, 2, 3, 4]); - e = v.swap_remove(3); - assert_eq!(e, 4); - assert_eq!(v, [5, 2, 3]); -} - -#[test] -#[should_panic] -fn test_swap_remove_fail() { - let mut v = vec![1]; - let _ = v.swap_remove(0); - let _ = v.swap_remove(0); -} - -#[test] -fn test_swap_remove_noncopyable() { - // Tests that we don't accidentally run destructors twice. - let mut v: Vec> = Vec::new(); - v.push(Box::new(0)); - v.push(Box::new(0)); - v.push(Box::new(0)); - let mut _e = v.swap_remove(0); - assert_eq!(v.len(), 2); - _e = v.swap_remove(1); - assert_eq!(v.len(), 1); - _e = v.swap_remove(0); - assert_eq!(v.len(), 0); -} - -#[test] -fn test_push() { - // Test on-stack push(). - let mut v = vec![]; - v.push(1); - assert_eq!(v.len(), 1); - assert_eq!(v[0], 1); - - // Test on-heap push(). - v.push(2); - assert_eq!(v.len(), 2); - assert_eq!(v[0], 1); - assert_eq!(v[1], 2); -} - -#[test] -fn test_truncate() { - let mut v: Vec> = vec![Box::new(6), Box::new(5), Box::new(4)]; - v.truncate(1); - let v = v; - assert_eq!(v.len(), 1); - assert_eq!(*(v[0]), 6); - // If the unsafe block didn't drop things properly, we blow up here. -} - -#[test] -fn test_clear() { - let mut v: Vec> = vec![Box::new(6), Box::new(5), Box::new(4)]; - v.clear(); - assert_eq!(v.len(), 0); - // If the unsafe block didn't drop things properly, we blow up here. -} - -#[test] -fn test_retain() { - let mut v = vec![1, 2, 3, 4, 5]; - v.retain(is_odd); - assert_eq!(v, [1, 3, 5]); -} - -#[test] -fn test_binary_search() { - assert_eq!([1, 2, 3, 4, 5].binary_search(&5).ok(), Some(4)); - assert_eq!([1, 2, 3, 4, 5].binary_search(&4).ok(), Some(3)); - assert_eq!([1, 2, 3, 4, 5].binary_search(&3).ok(), Some(2)); - assert_eq!([1, 2, 3, 4, 5].binary_search(&2).ok(), Some(1)); - assert_eq!([1, 2, 3, 4, 5].binary_search(&1).ok(), Some(0)); - - assert_eq!([2, 4, 6, 8, 10].binary_search(&1).ok(), None); - assert_eq!([2, 4, 6, 8, 10].binary_search(&5).ok(), None); - assert_eq!([2, 4, 6, 8, 10].binary_search(&4).ok(), Some(1)); - assert_eq!([2, 4, 6, 8, 10].binary_search(&10).ok(), Some(4)); - - assert_eq!([2, 4, 6, 8].binary_search(&1).ok(), None); - assert_eq!([2, 4, 6, 8].binary_search(&5).ok(), None); - assert_eq!([2, 4, 6, 8].binary_search(&4).ok(), Some(1)); - assert_eq!([2, 4, 6, 8].binary_search(&8).ok(), Some(3)); - - assert_eq!([2, 4, 6].binary_search(&1).ok(), None); - assert_eq!([2, 4, 6].binary_search(&5).ok(), None); - assert_eq!([2, 4, 6].binary_search(&4).ok(), Some(1)); - assert_eq!([2, 4, 6].binary_search(&6).ok(), Some(2)); - - assert_eq!([2, 4].binary_search(&1).ok(), None); - assert_eq!([2, 4].binary_search(&5).ok(), None); - assert_eq!([2, 4].binary_search(&2).ok(), Some(0)); - assert_eq!([2, 4].binary_search(&4).ok(), Some(1)); - - assert_eq!([2].binary_search(&1).ok(), None); - assert_eq!([2].binary_search(&5).ok(), None); - assert_eq!([2].binary_search(&2).ok(), Some(0)); - - assert_eq!([].binary_search(&1).ok(), None); - assert_eq!([].binary_search(&5).ok(), None); - - assert!([1, 1, 1, 1, 1].binary_search(&1).ok() != None); - assert!([1, 1, 1, 1, 2].binary_search(&1).ok() != None); - assert!([1, 1, 1, 2, 2].binary_search(&1).ok() != None); - assert!([1, 1, 2, 2, 2].binary_search(&1).ok() != None); - assert_eq!([1, 2, 2, 2, 2].binary_search(&1).ok(), Some(0)); - - assert_eq!([1, 2, 3, 4, 5].binary_search(&6).ok(), None); - assert_eq!([1, 2, 3, 4, 5].binary_search(&0).ok(), None); -} - -#[test] -fn test_reverse() { - let mut v = vec![10, 20]; - assert_eq!(v[0], 10); - assert_eq!(v[1], 20); - v.reverse(); - assert_eq!(v[0], 20); - assert_eq!(v[1], 10); - - let mut v3 = Vec::::new(); - v3.reverse(); - assert!(v3.is_empty()); - - // check the 1-byte-types path - let mut v = (-50..51i8).collect::>(); - v.reverse(); - assert_eq!(v, (-50..51i8).rev().collect::>()); - - // check the 2-byte-types path - let mut v = (-50..51i16).collect::>(); - v.reverse(); - assert_eq!(v, (-50..51i16).rev().collect::>()); -} - -#[test] -fn test_rotate_left() { - let expected: Vec<_> = (0..13).collect(); - let mut v = Vec::new(); - - // no-ops - v.clone_from(&expected); - v.rotate_left(0); - assert_eq!(v, expected); - v.rotate_left(expected.len()); - assert_eq!(v, expected); - let mut zst_array = [(), (), ()]; - zst_array.rotate_left(2); - - // happy path - v = (5..13).chain(0..5).collect(); - v.rotate_left(8); - assert_eq!(v, expected); - - let expected: Vec<_> = (0..1000).collect(); - - // small rotations in large slice, uses ptr::copy - v = (2..1000).chain(0..2).collect(); - v.rotate_left(998); - assert_eq!(v, expected); - v = (998..1000).chain(0..998).collect(); - v.rotate_left(2); - assert_eq!(v, expected); - - // non-small prime rotation, has a few rounds of swapping - v = (389..1000).chain(0..389).collect(); - v.rotate_left(1000 - 389); - assert_eq!(v, expected); -} - -#[test] -fn test_rotate_right() { - let expected: Vec<_> = (0..13).collect(); - let mut v = Vec::new(); - - // no-ops - v.clone_from(&expected); - v.rotate_right(0); - assert_eq!(v, expected); - v.rotate_right(expected.len()); - assert_eq!(v, expected); - let mut zst_array = [(), (), ()]; - zst_array.rotate_right(2); - - // happy path - v = (5..13).chain(0..5).collect(); - v.rotate_right(5); - assert_eq!(v, expected); - - let expected: Vec<_> = (0..1000).collect(); - - // small rotations in large slice, uses ptr::copy - v = (2..1000).chain(0..2).collect(); - v.rotate_right(2); - assert_eq!(v, expected); - v = (998..1000).chain(0..998).collect(); - v.rotate_right(998); - assert_eq!(v, expected); - - // non-small prime rotation, has a few rounds of swapping - v = (389..1000).chain(0..389).collect(); - v.rotate_right(389); - assert_eq!(v, expected); -} - -#[test] -fn test_concat() { - let v: [Vec; 0] = []; - let c = v.concat(); - assert_eq!(c, []); - let d = [vec![1], vec![2, 3]].concat(); - assert_eq!(d, [1, 2, 3]); - - let v: &[&[_]] = &[&[1], &[2, 3]]; - assert_eq!(v.join(&0), [1, 0, 2, 3]); - let v: &[&[_]] = &[&[1], &[2], &[3]]; - assert_eq!(v.join(&0), [1, 0, 2, 0, 3]); -} - -#[test] -fn test_join() { - let v: [Vec; 0] = []; - assert_eq!(v.join(&0), []); - assert_eq!([vec![1], vec![2, 3]].join(&0), [1, 0, 2, 3]); - assert_eq!([vec![1], vec![2], vec![3]].join(&0), [1, 0, 2, 0, 3]); - - let v: [&[_]; 2] = [&[1], &[2, 3]]; - assert_eq!(v.join(&0), [1, 0, 2, 3]); - let v: [&[_]; 3] = [&[1], &[2], &[3]]; - assert_eq!(v.join(&0), [1, 0, 2, 0, 3]); -} - -#[test] -fn test_join_nocopy() { - let v: [String; 0] = []; - assert_eq!(v.join(","), ""); - assert_eq!(["a".to_string(), "ab".into()].join(","), "a,ab"); - assert_eq!(["a".to_string(), "ab".into(), "abc".into()].join(","), "a,ab,abc"); - assert_eq!(["a".to_string(), "ab".into(), "".into()].join(","), "a,ab,"); -} - -#[test] -fn test_insert() { - let mut a = vec![1, 2, 4]; - a.insert(2, 3); - assert_eq!(a, [1, 2, 3, 4]); - - let mut a = vec![1, 2, 3]; - a.insert(0, 0); - assert_eq!(a, [0, 1, 2, 3]); - - let mut a = vec![1, 2, 3]; - a.insert(3, 4); - assert_eq!(a, [1, 2, 3, 4]); - - let mut a = vec![]; - a.insert(0, 1); - assert_eq!(a, [1]); -} - -#[test] -#[should_panic] -fn test_insert_oob() { - let mut a = vec![1, 2, 3]; - a.insert(4, 5); -} - -#[test] -fn test_remove() { - let mut a = vec![1, 2, 3, 4]; - - assert_eq!(a.remove(2), 3); - assert_eq!(a, [1, 2, 4]); - - assert_eq!(a.remove(2), 4); - assert_eq!(a, [1, 2]); - - assert_eq!(a.remove(0), 1); - assert_eq!(a, [2]); - - assert_eq!(a.remove(0), 2); - assert_eq!(a, []); -} - -#[test] -#[should_panic] -fn test_remove_fail() { - let mut a = vec![1]; - let _ = a.remove(0); - let _ = a.remove(0); -} - -#[test] -fn test_capacity() { - let mut v = vec![0]; - v.reserve_exact(10); - assert!(v.capacity() >= 11); -} - -#[test] -fn test_slice_2() { - let v = vec![1, 2, 3, 4, 5]; - let v = &v[1..3]; - assert_eq!(v.len(), 2); - assert_eq!(v[0], 2); - assert_eq!(v[1], 3); -} - -macro_rules! assert_order { - (Greater, $a:expr, $b:expr) => { - assert_eq!($a.cmp($b), Greater); - assert!($a > $b); - }; - (Less, $a:expr, $b:expr) => { - assert_eq!($a.cmp($b), Less); - assert!($a < $b); - }; - (Equal, $a:expr, $b:expr) => { - assert_eq!($a.cmp($b), Equal); - assert_eq!($a, $b); - }; -} - -#[test] -fn test_total_ord_u8() { - let c = &[1u8, 2, 3]; - assert_order!(Greater, &[1u8, 2, 3, 4][..], &c[..]); - let c = &[1u8, 2, 3, 4]; - assert_order!(Less, &[1u8, 2, 3][..], &c[..]); - let c = &[1u8, 2, 3, 6]; - assert_order!(Equal, &[1u8, 2, 3, 6][..], &c[..]); - let c = &[1u8, 2, 3, 4, 5, 6]; - assert_order!(Less, &[1u8, 2, 3, 4, 5, 5, 5, 5][..], &c[..]); - let c = &[1u8, 2, 3, 4]; - assert_order!(Greater, &[2u8, 2][..], &c[..]); -} - -#[test] -fn test_total_ord_i32() { - let c = &[1, 2, 3]; - assert_order!(Greater, &[1, 2, 3, 4][..], &c[..]); - let c = &[1, 2, 3, 4]; - assert_order!(Less, &[1, 2, 3][..], &c[..]); - let c = &[1, 2, 3, 6]; - assert_order!(Equal, &[1, 2, 3, 6][..], &c[..]); - let c = &[1, 2, 3, 4, 5, 6]; - assert_order!(Less, &[1, 2, 3, 4, 5, 5, 5, 5][..], &c[..]); - let c = &[1, 2, 3, 4]; - assert_order!(Greater, &[2, 2][..], &c[..]); -} - -#[test] -fn test_iterator() { - let xs = [1, 2, 5, 10, 11]; - let mut it = xs.iter(); - assert_eq!(it.size_hint(), (5, Some(5))); - assert_eq!(it.next().unwrap(), &1); - assert_eq!(it.size_hint(), (4, Some(4))); - assert_eq!(it.next().unwrap(), &2); - assert_eq!(it.size_hint(), (3, Some(3))); - assert_eq!(it.next().unwrap(), &5); - assert_eq!(it.size_hint(), (2, Some(2))); - assert_eq!(it.next().unwrap(), &10); - assert_eq!(it.size_hint(), (1, Some(1))); - assert_eq!(it.next().unwrap(), &11); - assert_eq!(it.size_hint(), (0, Some(0))); - assert!(it.next().is_none()); -} - -#[test] -fn test_iter_size_hints() { - let mut xs = [1, 2, 5, 10, 11]; - assert_eq!(xs.iter().size_hint(), (5, Some(5))); - assert_eq!(xs.iter_mut().size_hint(), (5, Some(5))); -} - -#[test] -fn test_iter_as_slice() { - let xs = [1, 2, 5, 10, 11]; - let mut iter = xs.iter(); - assert_eq!(iter.as_slice(), &[1, 2, 5, 10, 11]); - iter.next(); - assert_eq!(iter.as_slice(), &[2, 5, 10, 11]); -} - -#[test] -fn test_iter_as_ref() { - let xs = [1, 2, 5, 10, 11]; - let mut iter = xs.iter(); - assert_eq!(iter.as_ref(), &[1, 2, 5, 10, 11]); - iter.next(); - assert_eq!(iter.as_ref(), &[2, 5, 10, 11]); -} - -#[test] -fn test_iter_clone() { - let xs = [1, 2, 5]; - let mut it = xs.iter(); - it.next(); - let mut jt = it.clone(); - assert_eq!(it.next(), jt.next()); - assert_eq!(it.next(), jt.next()); - assert_eq!(it.next(), jt.next()); -} - -#[test] -fn test_iter_is_empty() { - let xs = [1, 2, 5, 10, 11]; - for i in 0..xs.len() { - for j in i..xs.len() { - assert_eq!(xs[i..j].iter().is_empty(), xs[i..j].is_empty()); - } - } -} - -#[test] -fn test_mut_iterator() { - let mut xs = [1, 2, 3, 4, 5]; - for x in &mut xs { - *x += 1; - } - assert!(xs == [2, 3, 4, 5, 6]) -} - -#[test] -fn test_rev_iterator() { - let xs = [1, 2, 5, 10, 11]; - let ys = [11, 10, 5, 2, 1]; - let mut i = 0; - for &x in xs.iter().rev() { - assert_eq!(x, ys[i]); - i += 1; - } - assert_eq!(i, 5); -} - -#[test] -fn test_mut_rev_iterator() { - let mut xs = [1, 2, 3, 4, 5]; - for (i, x) in xs.iter_mut().rev().enumerate() { - *x += i; - } - assert!(xs == [5, 5, 5, 5, 5]) -} - -#[test] -fn test_move_iterator() { - let xs = vec![1, 2, 3, 4, 5]; - assert_eq!(xs.into_iter().fold(0, |a: usize, b: usize| 10 * a + b), 12345); -} - -#[test] -fn test_move_rev_iterator() { - let xs = vec![1, 2, 3, 4, 5]; - assert_eq!(xs.into_iter().rev().fold(0, |a: usize, b: usize| 10 * a + b), 54321); -} - -#[test] -fn test_split_iterator() { - let xs = &[1, 2, 3, 4, 5]; - - let splits: &[&[_]] = &[&[1], &[3], &[5]]; - assert_eq!(xs.split(|x| *x % 2 == 0).collect::>(), splits); - let splits: &[&[_]] = &[&[], &[2, 3, 4, 5]]; - assert_eq!(xs.split(|x| *x == 1).collect::>(), splits); - let splits: &[&[_]] = &[&[1, 2, 3, 4], &[]]; - assert_eq!(xs.split(|x| *x == 5).collect::>(), splits); - let splits: &[&[_]] = &[&[1, 2, 3, 4, 5]]; - assert_eq!(xs.split(|x| *x == 10).collect::>(), splits); - let splits: &[&[_]] = &[&[], &[], &[], &[], &[], &[]]; - assert_eq!(xs.split(|_| true).collect::>(), splits); - - let xs: &[i32] = &[]; - let splits: &[&[i32]] = &[&[]]; - assert_eq!(xs.split(|x| *x == 5).collect::>(), splits); -} - -#[test] -fn test_split_iterator_inclusive() { - let xs = &[1, 2, 3, 4, 5]; - - let splits: &[&[_]] = &[&[1, 2], &[3, 4], &[5]]; - assert_eq!(xs.split_inclusive(|x| *x % 2 == 0).collect::>(), splits); - let splits: &[&[_]] = &[&[1], &[2, 3, 4, 5]]; - assert_eq!(xs.split_inclusive(|x| *x == 1).collect::>(), splits); - let splits: &[&[_]] = &[&[1, 2, 3, 4, 5]]; - assert_eq!(xs.split_inclusive(|x| *x == 5).collect::>(), splits); - let splits: &[&[_]] = &[&[1, 2, 3, 4, 5]]; - assert_eq!(xs.split_inclusive(|x| *x == 10).collect::>(), splits); - let splits: &[&[_]] = &[&[1], &[2], &[3], &[4], &[5]]; - assert_eq!(xs.split_inclusive(|_| true).collect::>(), splits); - - let xs: &[i32] = &[]; - let splits: &[&[i32]] = &[]; - assert_eq!(xs.split_inclusive(|x| *x == 5).collect::>(), splits); -} - -#[test] -fn test_split_iterator_inclusive_reverse() { - let xs = &[1, 2, 3, 4, 5]; - - let splits: &[&[_]] = &[&[5], &[3, 4], &[1, 2]]; - assert_eq!(xs.split_inclusive(|x| *x % 2 == 0).rev().collect::>(), splits); - let splits: &[&[_]] = &[&[2, 3, 4, 5], &[1]]; - assert_eq!(xs.split_inclusive(|x| *x == 1).rev().collect::>(), splits); - let splits: &[&[_]] = &[&[1, 2, 3, 4, 5]]; - assert_eq!(xs.split_inclusive(|x| *x == 5).rev().collect::>(), splits); - let splits: &[&[_]] = &[&[1, 2, 3, 4, 5]]; - assert_eq!(xs.split_inclusive(|x| *x == 10).rev().collect::>(), splits); - let splits: &[&[_]] = &[&[5], &[4], &[3], &[2], &[1]]; - assert_eq!(xs.split_inclusive(|_| true).rev().collect::>(), splits); - - let xs: &[i32] = &[]; - let splits: &[&[i32]] = &[]; - assert_eq!(xs.split_inclusive(|x| *x == 5).rev().collect::>(), splits); -} - -#[test] -fn test_split_iterator_mut_inclusive() { - let xs = &mut [1, 2, 3, 4, 5]; - - let splits: &[&[_]] = &[&[1, 2], &[3, 4], &[5]]; - assert_eq!(xs.split_inclusive_mut(|x| *x % 2 == 0).collect::>(), splits); - let splits: &[&[_]] = &[&[1], &[2, 3, 4, 5]]; - assert_eq!(xs.split_inclusive_mut(|x| *x == 1).collect::>(), splits); - let splits: &[&[_]] = &[&[1, 2, 3, 4, 5]]; - assert_eq!(xs.split_inclusive_mut(|x| *x == 5).collect::>(), splits); - let splits: &[&[_]] = &[&[1, 2, 3, 4, 5]]; - assert_eq!(xs.split_inclusive_mut(|x| *x == 10).collect::>(), splits); - let splits: &[&[_]] = &[&[1], &[2], &[3], &[4], &[5]]; - assert_eq!(xs.split_inclusive_mut(|_| true).collect::>(), splits); - - let xs: &mut [i32] = &mut []; - let splits: &[&[i32]] = &[]; - assert_eq!(xs.split_inclusive_mut(|x| *x == 5).collect::>(), splits); -} - -#[test] -fn test_split_iterator_mut_inclusive_reverse() { - let xs = &mut [1, 2, 3, 4, 5]; - - let splits: &[&[_]] = &[&[5], &[3, 4], &[1, 2]]; - assert_eq!(xs.split_inclusive_mut(|x| *x % 2 == 0).rev().collect::>(), splits); - let splits: &[&[_]] = &[&[2, 3, 4, 5], &[1]]; - assert_eq!(xs.split_inclusive_mut(|x| *x == 1).rev().collect::>(), splits); - let splits: &[&[_]] = &[&[1, 2, 3, 4, 5]]; - assert_eq!(xs.split_inclusive_mut(|x| *x == 5).rev().collect::>(), splits); - let splits: &[&[_]] = &[&[1, 2, 3, 4, 5]]; - assert_eq!(xs.split_inclusive_mut(|x| *x == 10).rev().collect::>(), splits); - let splits: &[&[_]] = &[&[5], &[4], &[3], &[2], &[1]]; - assert_eq!(xs.split_inclusive_mut(|_| true).rev().collect::>(), splits); - - let xs: &mut [i32] = &mut []; - let splits: &[&[i32]] = &[]; - assert_eq!(xs.split_inclusive_mut(|x| *x == 5).rev().collect::>(), splits); -} - -#[test] -fn test_splitn_iterator() { - let xs = &[1, 2, 3, 4, 5]; - - let splits: &[&[_]] = &[&[1, 2, 3, 4, 5]]; - assert_eq!(xs.splitn(1, |x| *x % 2 == 0).collect::>(), splits); - let splits: &[&[_]] = &[&[1], &[3, 4, 5]]; - assert_eq!(xs.splitn(2, |x| *x % 2 == 0).collect::>(), splits); - let splits: &[&[_]] = &[&[], &[], &[], &[4, 5]]; - assert_eq!(xs.splitn(4, |_| true).collect::>(), splits); - - let xs: &[i32] = &[]; - let splits: &[&[i32]] = &[&[]]; - assert_eq!(xs.splitn(2, |x| *x == 5).collect::>(), splits); -} - -#[test] -fn test_splitn_iterator_mut() { - let xs = &mut [1, 2, 3, 4, 5]; - - let splits: &[&mut [_]] = &[&mut [1, 2, 3, 4, 5]]; - assert_eq!(xs.splitn_mut(1, |x| *x % 2 == 0).collect::>(), splits); - let splits: &[&mut [_]] = &[&mut [1], &mut [3, 4, 5]]; - assert_eq!(xs.splitn_mut(2, |x| *x % 2 == 0).collect::>(), splits); - let splits: &[&mut [_]] = &[&mut [], &mut [], &mut [], &mut [4, 5]]; - assert_eq!(xs.splitn_mut(4, |_| true).collect::>(), splits); - - let xs: &mut [i32] = &mut []; - let splits: &[&mut [i32]] = &[&mut []]; - assert_eq!(xs.splitn_mut(2, |x| *x == 5).collect::>(), splits); -} - -#[test] -fn test_rsplit_iterator() { - let xs = &[1, 2, 3, 4, 5]; - - let splits: &[&[_]] = &[&[5], &[3], &[1]]; - assert_eq!(xs.split(|x| *x % 2 == 0).rev().collect::>(), splits); - let splits: &[&[_]] = &[&[2, 3, 4, 5], &[]]; - assert_eq!(xs.split(|x| *x == 1).rev().collect::>(), splits); - let splits: &[&[_]] = &[&[], &[1, 2, 3, 4]]; - assert_eq!(xs.split(|x| *x == 5).rev().collect::>(), splits); - let splits: &[&[_]] = &[&[1, 2, 3, 4, 5]]; - assert_eq!(xs.split(|x| *x == 10).rev().collect::>(), splits); - - let xs: &[i32] = &[]; - let splits: &[&[i32]] = &[&[]]; - assert_eq!(xs.split(|x| *x == 5).rev().collect::>(), splits); -} - -#[test] -fn test_rsplitn_iterator() { - let xs = &[1, 2, 3, 4, 5]; - - let splits: &[&[_]] = &[&[1, 2, 3, 4, 5]]; - assert_eq!(xs.rsplitn(1, |x| *x % 2 == 0).collect::>(), splits); - let splits: &[&[_]] = &[&[5], &[1, 2, 3]]; - assert_eq!(xs.rsplitn(2, |x| *x % 2 == 0).collect::>(), splits); - let splits: &[&[_]] = &[&[], &[], &[], &[1, 2]]; - assert_eq!(xs.rsplitn(4, |_| true).collect::>(), splits); - - let xs: &[i32] = &[]; - let splits: &[&[i32]] = &[&[]]; - assert_eq!(xs.rsplitn(2, |x| *x == 5).collect::>(), splits); - assert!(xs.rsplitn(0, |x| *x % 2 == 0).next().is_none()); -} - -#[test] -fn test_split_iterators_size_hint() { - #[derive(Copy, Clone)] - enum Bounds { - Lower, - Upper, - } - fn assert_tight_size_hints(mut it: impl Iterator, which: Bounds, ctx: impl fmt::Display) { - match which { - Bounds::Lower => { - let mut lower_bounds = vec![it.size_hint().0]; - while let Some(_) = it.next() { - lower_bounds.push(it.size_hint().0); - } - let target: Vec<_> = (0..lower_bounds.len()).rev().collect(); - assert_eq!(lower_bounds, target, "lower bounds incorrect or not tight: {}", ctx); - } - Bounds::Upper => { - let mut upper_bounds = vec![it.size_hint().1]; - while let Some(_) = it.next() { - upper_bounds.push(it.size_hint().1); - } - let target: Vec<_> = (0..upper_bounds.len()).map(Some).rev().collect(); - assert_eq!(upper_bounds, target, "upper bounds incorrect or not tight: {}", ctx); - } - } - } - - for len in 0..=2 { - let mut v: Vec = (0..len).collect(); - - // p: predicate, b: bound selection - for (p, b) in [ - // with a predicate always returning false, the split*-iterators - // become maximally short, so the size_hint lower bounds are tight - ((|_| false) as fn(&_) -> _, Bounds::Lower), - // with a predicate always returning true, the split*-iterators - // become maximally long, so the size_hint upper bounds are tight - ((|_| true) as fn(&_) -> _, Bounds::Upper), - ] { - use assert_tight_size_hints as a; - use format_args as f; - - a(v.split(p), b, "split"); - a(v.split_mut(p), b, "split_mut"); - a(v.split_inclusive(p), b, "split_inclusive"); - a(v.split_inclusive_mut(p), b, "split_inclusive_mut"); - a(v.rsplit(p), b, "rsplit"); - a(v.rsplit_mut(p), b, "rsplit_mut"); - - for n in 0..=3 { - a(v.splitn(n, p), b, f!("splitn, n = {n}")); - a(v.splitn_mut(n, p), b, f!("splitn_mut, n = {n}")); - a(v.rsplitn(n, p), b, f!("rsplitn, n = {n}")); - a(v.rsplitn_mut(n, p), b, f!("rsplitn_mut, n = {n}")); - } - } - } -} - -#[test] -fn test_windows_iterator() { - let v = &[1, 2, 3, 4]; - - let wins: &[&[_]] = &[&[1, 2], &[2, 3], &[3, 4]]; - assert_eq!(v.windows(2).collect::>(), wins); - - let wins: &[&[_]] = &[&[1, 2, 3], &[2, 3, 4]]; - assert_eq!(v.windows(3).collect::>(), wins); - assert!(v.windows(6).next().is_none()); - - let wins: &[&[_]] = &[&[3, 4], &[2, 3], &[1, 2]]; - assert_eq!(v.windows(2).rev().collect::>(), wins); -} - -#[test] -#[should_panic] -fn test_windows_iterator_0() { - let v = &[1, 2, 3, 4]; - let _it = v.windows(0); -} - -#[test] -fn test_chunks_iterator() { - let v = &[1, 2, 3, 4, 5]; - - assert_eq!(v.chunks(2).len(), 3); - - let chunks: &[&[_]] = &[&[1, 2], &[3, 4], &[5]]; - assert_eq!(v.chunks(2).collect::>(), chunks); - let chunks: &[&[_]] = &[&[1, 2, 3], &[4, 5]]; - assert_eq!(v.chunks(3).collect::>(), chunks); - let chunks: &[&[_]] = &[&[1, 2, 3, 4, 5]]; - assert_eq!(v.chunks(6).collect::>(), chunks); - - let chunks: &[&[_]] = &[&[5], &[3, 4], &[1, 2]]; - assert_eq!(v.chunks(2).rev().collect::>(), chunks); -} - -#[test] -#[should_panic] -fn test_chunks_iterator_0() { - let v = &[1, 2, 3, 4]; - let _it = v.chunks(0); -} - -#[test] -fn test_chunks_exact_iterator() { - let v = &[1, 2, 3, 4, 5]; - - assert_eq!(v.chunks_exact(2).len(), 2); - - let chunks: &[&[_]] = &[&[1, 2], &[3, 4]]; - assert_eq!(v.chunks_exact(2).collect::>(), chunks); - let chunks: &[&[_]] = &[&[1, 2, 3]]; - assert_eq!(v.chunks_exact(3).collect::>(), chunks); - let chunks: &[&[_]] = &[]; - assert_eq!(v.chunks_exact(6).collect::>(), chunks); - - let chunks: &[&[_]] = &[&[3, 4], &[1, 2]]; - assert_eq!(v.chunks_exact(2).rev().collect::>(), chunks); -} - -#[test] -#[should_panic] -fn test_chunks_exact_iterator_0() { - let v = &[1, 2, 3, 4]; - let _it = v.chunks_exact(0); -} - -#[test] -fn test_rchunks_iterator() { - let v = &[1, 2, 3, 4, 5]; - - assert_eq!(v.rchunks(2).len(), 3); - - let chunks: &[&[_]] = &[&[4, 5], &[2, 3], &[1]]; - assert_eq!(v.rchunks(2).collect::>(), chunks); - let chunks: &[&[_]] = &[&[3, 4, 5], &[1, 2]]; - assert_eq!(v.rchunks(3).collect::>(), chunks); - let chunks: &[&[_]] = &[&[1, 2, 3, 4, 5]]; - assert_eq!(v.rchunks(6).collect::>(), chunks); - - let chunks: &[&[_]] = &[&[1], &[2, 3], &[4, 5]]; - assert_eq!(v.rchunks(2).rev().collect::>(), chunks); -} - -#[test] -#[should_panic] -fn test_rchunks_iterator_0() { - let v = &[1, 2, 3, 4]; - let _it = v.rchunks(0); -} - -#[test] -fn test_rchunks_exact_iterator() { - let v = &[1, 2, 3, 4, 5]; - - assert_eq!(v.rchunks_exact(2).len(), 2); - - let chunks: &[&[_]] = &[&[4, 5], &[2, 3]]; - assert_eq!(v.rchunks_exact(2).collect::>(), chunks); - let chunks: &[&[_]] = &[&[3, 4, 5]]; - assert_eq!(v.rchunks_exact(3).collect::>(), chunks); - let chunks: &[&[_]] = &[]; - assert_eq!(v.rchunks_exact(6).collect::>(), chunks); - - let chunks: &[&[_]] = &[&[2, 3], &[4, 5]]; - assert_eq!(v.rchunks_exact(2).rev().collect::>(), chunks); -} - -#[test] -#[should_panic] -fn test_rchunks_exact_iterator_0() { - let v = &[1, 2, 3, 4]; - let _it = v.rchunks_exact(0); -} - -#[test] -fn test_reverse_part() { - let mut values = [1, 2, 3, 4, 5]; - values[1..4].reverse(); - assert!(values == [1, 4, 3, 2, 5]); -} - -#[test] -fn test_show() { - macro_rules! test_show_vec { - ($x:expr, $x_str:expr) => {{ - let (x, x_str) = ($x, $x_str); - assert_eq!(format!("{x:?}"), x_str); - assert_eq!(format!("{x:?}"), x_str); - }}; - } - let empty = Vec::::new(); - test_show_vec!(empty, "[]"); - test_show_vec!(vec![1], "[1]"); - test_show_vec!(vec![1, 2, 3], "[1, 2, 3]"); - test_show_vec!(vec![vec![], vec![1], vec![1, 1]], "[[], [1], [1, 1]]"); - - let empty_mut: &mut [i32] = &mut []; - test_show_vec!(empty_mut, "[]"); - let v = &mut [1]; - test_show_vec!(v, "[1]"); - let v = &mut [1, 2, 3]; - test_show_vec!(v, "[1, 2, 3]"); - let v: &mut [&mut [_]] = &mut [&mut [], &mut [1], &mut [1, 1]]; - test_show_vec!(v, "[[], [1], [1, 1]]"); -} - -#[test] -fn test_vec_default() { - macro_rules! t { - ($ty:ty) => {{ - let v: $ty = Default::default(); - assert!(v.is_empty()); - }}; - } - - t!(&[i32]); - t!(Vec); -} - -#[test] -#[should_panic] -fn test_overflow_does_not_cause_segfault() { - let mut v = vec![]; - v.reserve_exact(!0); - v.push(1); - v.push(2); -} - -#[test] -#[should_panic] -fn test_overflow_does_not_cause_segfault_managed() { - let mut v = vec![Rc::new(1)]; - v.reserve_exact(!0); - v.push(Rc::new(2)); -} - -#[test] -fn test_mut_split_at() { - let mut values = [1, 2, 3, 4, 5]; - { - let (left, right) = values.split_at_mut(2); - { - let left: &[_] = left; - assert!(left[..left.len()] == [1, 2]); - } - for p in left { - *p += 1; - } - - { - let right: &[_] = right; - assert!(right[..right.len()] == [3, 4, 5]); - } - for p in right { - *p += 2; - } - } - - assert!(values == [2, 3, 5, 6, 7]); -} - -#[derive(Clone, PartialEq)] -struct Foo; - -#[test] -fn test_iter_zero_sized() { - let mut v = vec![Foo, Foo, Foo]; - assert_eq!(v.len(), 3); - let mut cnt = 0; - - for f in &v { - assert!(*f == Foo); - cnt += 1; - } - assert_eq!(cnt, 3); - - for f in &v[1..3] { - assert!(*f == Foo); - cnt += 1; - } - assert_eq!(cnt, 5); - - for f in &mut v { - assert!(*f == Foo); - cnt += 1; - } - assert_eq!(cnt, 8); - - for f in v { - assert!(f == Foo); - cnt += 1; - } - assert_eq!(cnt, 11); - - let xs: [Foo; 3] = [Foo, Foo, Foo]; - cnt = 0; - for f in &xs { - assert!(*f == Foo); - cnt += 1; - } - assert!(cnt == 3); -} - -#[test] -fn test_shrink_to_fit() { - let mut xs = vec![0, 1, 2, 3]; - for i in 4..100 { - xs.push(i) - } - assert_eq!(xs.capacity(), 128); - xs.shrink_to_fit(); - assert_eq!(xs.capacity(), 100); - assert_eq!(xs, (0..100).collect::>()); -} - -#[test] -fn test_starts_with() { - assert!(b"foobar".starts_with(b"foo")); - assert!(!b"foobar".starts_with(b"oob")); - assert!(!b"foobar".starts_with(b"bar")); - assert!(!b"foo".starts_with(b"foobar")); - assert!(!b"bar".starts_with(b"foobar")); - assert!(b"foobar".starts_with(b"foobar")); - let empty: &[u8] = &[]; - assert!(empty.starts_with(empty)); - assert!(!empty.starts_with(b"foo")); - assert!(b"foobar".starts_with(empty)); -} - -#[test] -fn test_ends_with() { - assert!(b"foobar".ends_with(b"bar")); - assert!(!b"foobar".ends_with(b"oba")); - assert!(!b"foobar".ends_with(b"foo")); - assert!(!b"foo".ends_with(b"foobar")); - assert!(!b"bar".ends_with(b"foobar")); - assert!(b"foobar".ends_with(b"foobar")); - let empty: &[u8] = &[]; - assert!(empty.ends_with(empty)); - assert!(!empty.ends_with(b"foo")); - assert!(b"foobar".ends_with(empty)); -} - -#[test] -fn test_mut_split_iterator() { - let mut xs = [0, 1, 0, 2, 3, 0, 0, 4, 5, 0]; - assert_eq!(xs.split_mut(|x| *x == 0).count(), 6); - for slice in xs.split_mut(|x| *x == 0) { - slice.reverse(); - } - assert!(xs == [0, 1, 0, 3, 2, 0, 0, 5, 4, 0]); - - let mut xs = [0, 1, 0, 2, 3, 0, 0, 4, 5, 0, 6, 7]; - for slice in xs.split_mut(|x| *x == 0).take(5) { - slice.reverse(); - } - assert!(xs == [0, 1, 0, 3, 2, 0, 0, 5, 4, 0, 6, 7]); -} - -#[test] -fn test_mut_split_iterator_rev() { - let mut xs = [1, 2, 0, 3, 4, 0, 0, 5, 6, 0]; - for slice in xs.split_mut(|x| *x == 0).rev().take(4) { - slice.reverse(); - } - assert!(xs == [1, 2, 0, 4, 3, 0, 0, 6, 5, 0]); -} - -#[test] -fn test_get_mut() { - let mut v = [0, 1, 2]; - assert_eq!(v.get_mut(3), None); - v.get_mut(1).map(|e| *e = 7); - assert_eq!(v[1], 7); - let mut x = 2; - assert_eq!(v.get_mut(2), Some(&mut x)); -} - -#[test] -fn test_mut_chunks() { - let mut v = [0, 1, 2, 3, 4, 5, 6]; - assert_eq!(v.chunks_mut(3).len(), 3); - for (i, chunk) in v.chunks_mut(3).enumerate() { - for x in chunk { - *x = i as u8; - } - } - let result = [0, 0, 0, 1, 1, 1, 2]; - assert_eq!(v, result); -} - -#[test] -fn test_mut_chunks_rev() { - let mut v = [0, 1, 2, 3, 4, 5, 6]; - for (i, chunk) in v.chunks_mut(3).rev().enumerate() { - for x in chunk { - *x = i as u8; - } - } - let result = [2, 2, 2, 1, 1, 1, 0]; - assert_eq!(v, result); -} - -#[test] -#[should_panic] -fn test_mut_chunks_0() { - let mut v = [1, 2, 3, 4]; - let _it = v.chunks_mut(0); -} - -#[test] -fn test_mut_chunks_exact() { - let mut v = [0, 1, 2, 3, 4, 5, 6]; - assert_eq!(v.chunks_exact_mut(3).len(), 2); - for (i, chunk) in v.chunks_exact_mut(3).enumerate() { - for x in chunk { - *x = i as u8; - } - } - let result = [0, 0, 0, 1, 1, 1, 6]; - assert_eq!(v, result); -} - -#[test] -fn test_mut_chunks_exact_rev() { - let mut v = [0, 1, 2, 3, 4, 5, 6]; - for (i, chunk) in v.chunks_exact_mut(3).rev().enumerate() { - for x in chunk { - *x = i as u8; - } - } - let result = [1, 1, 1, 0, 0, 0, 6]; - assert_eq!(v, result); -} - -#[test] -#[should_panic] -fn test_mut_chunks_exact_0() { - let mut v = [1, 2, 3, 4]; - let _it = v.chunks_exact_mut(0); -} - -#[test] -fn test_mut_rchunks() { - let mut v = [0, 1, 2, 3, 4, 5, 6]; - assert_eq!(v.rchunks_mut(3).len(), 3); - for (i, chunk) in v.rchunks_mut(3).enumerate() { - for x in chunk { - *x = i as u8; - } - } - let result = [2, 1, 1, 1, 0, 0, 0]; - assert_eq!(v, result); -} - -#[test] -fn test_mut_rchunks_rev() { - let mut v = [0, 1, 2, 3, 4, 5, 6]; - for (i, chunk) in v.rchunks_mut(3).rev().enumerate() { - for x in chunk { - *x = i as u8; - } - } - let result = [0, 1, 1, 1, 2, 2, 2]; - assert_eq!(v, result); -} - -#[test] -#[should_panic] -fn test_mut_rchunks_0() { - let mut v = [1, 2, 3, 4]; - let _it = v.rchunks_mut(0); -} - -#[test] -fn test_mut_rchunks_exact() { - let mut v = [0, 1, 2, 3, 4, 5, 6]; - assert_eq!(v.rchunks_exact_mut(3).len(), 2); - for (i, chunk) in v.rchunks_exact_mut(3).enumerate() { - for x in chunk { - *x = i as u8; - } - } - let result = [0, 1, 1, 1, 0, 0, 0]; - assert_eq!(v, result); -} - -#[test] -fn test_mut_rchunks_exact_rev() { - let mut v = [0, 1, 2, 3, 4, 5, 6]; - for (i, chunk) in v.rchunks_exact_mut(3).rev().enumerate() { - for x in chunk { - *x = i as u8; - } - } - let result = [0, 0, 0, 0, 1, 1, 1]; - assert_eq!(v, result); -} - -#[test] -#[should_panic] -fn test_mut_rchunks_exact_0() { - let mut v = [1, 2, 3, 4]; - let _it = v.rchunks_exact_mut(0); -} - -#[test] -fn test_mut_last() { - let mut x = [1, 2, 3, 4, 5]; - let h = x.last_mut(); - assert_eq!(*h.unwrap(), 5); - - let y: &mut [i32] = &mut []; - assert!(y.last_mut().is_none()); -} - -#[test] -fn test_to_vec() { - let xs: Box<_> = Box::new([1, 2, 3]); - let ys = xs.to_vec(); - assert_eq!(ys, [1, 2, 3]); -} - -#[test] -fn test_in_place_iterator_specialization() { - let src: Box<[usize]> = Box::new([1, 2, 3]); - let src_ptr = src.as_ptr(); - let sink: Box<_> = src.into_vec().into_iter().map(std::convert::identity).collect(); - let sink_ptr = sink.as_ptr(); - assert_eq!(src_ptr, sink_ptr); -} - -#[test] -fn test_box_slice_clone() { - let data = vec![vec![0, 1], vec![0], vec![1]]; - let data2 = data.clone().into_boxed_slice().clone().to_vec(); - - assert_eq!(data, data2); -} - -#[test] -#[allow(unused_must_use)] // here, we care about the side effects of `.clone()` -#[cfg_attr(target_os = "emscripten", ignore)] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_box_slice_clone_panics() { - use std::sync::atomic::{AtomicUsize, Ordering}; - use std::sync::Arc; - - struct Canary { - count: Arc, - panics: bool, - } - - impl Drop for Canary { - fn drop(&mut self) { - self.count.fetch_add(1, Ordering::SeqCst); - } - } - - impl Clone for Canary { - fn clone(&self) -> Self { - if self.panics { - panic!() - } - - Canary { count: self.count.clone(), panics: self.panics } - } - } - - let drop_count = Arc::new(AtomicUsize::new(0)); - let canary = Canary { count: drop_count.clone(), panics: false }; - let panic = Canary { count: drop_count.clone(), panics: true }; - - std::panic::catch_unwind(move || { - // When xs is dropped, +5. - let xs = - vec![canary.clone(), canary.clone(), canary.clone(), panic, canary].into_boxed_slice(); - - // When panic is cloned, +3. - xs.clone(); - }) - .unwrap_err(); - - // Total = 8 - assert_eq!(drop_count.load(Ordering::SeqCst), 8); -} - -#[test] -fn test_copy_from_slice() { - let src = [0, 1, 2, 3, 4, 5]; - let mut dst = [0; 6]; - dst.copy_from_slice(&src); - assert_eq!(src, dst) -} - -#[test] -#[should_panic(expected = "source slice length (4) does not match destination slice length (5)")] -fn test_copy_from_slice_dst_longer() { - let src = [0, 1, 2, 3]; - let mut dst = [0; 5]; - dst.copy_from_slice(&src); -} - -#[test] -#[should_panic(expected = "source slice length (4) does not match destination slice length (3)")] -fn test_copy_from_slice_dst_shorter() { - let src = [0, 1, 2, 3]; - let mut dst = [0; 3]; - dst.copy_from_slice(&src); -} - -#[test] -fn repeat_generic_slice() { - assert_eq!([1, 2].repeat(2), vec![1, 2, 1, 2]); - assert_eq!([1, 2, 3, 4].repeat(0), vec![]); - assert_eq!([1, 2, 3, 4].repeat(1), vec![1, 2, 3, 4]); - assert_eq!([1, 2, 3, 4].repeat(3), vec![1, 2, 3, 4, 1, 2, 3, 4, 1, 2, 3, 4]); -} - -#[test] -#[allow(unreachable_patterns)] -fn subslice_patterns() { - // This test comprehensively checks the passing static and dynamic semantics - // of subslice patterns `..`, `x @ ..`, `ref x @ ..`, and `ref mut @ ..` - // in slice patterns `[$($pat), $(,)?]` . - - #[derive(PartialEq, Debug, Clone)] - struct N(u8); - - macro_rules! n { - ($($e:expr),* $(,)?) => { - [$(N($e)),*] - } - } - - macro_rules! c { - ($inp:expr, $typ:ty, $out:expr $(,)?) => { - assert_eq!($out, identity::<$typ>($inp)) - }; - } - - macro_rules! m { - ($e:expr, $p:pat => $b:expr) => { - match $e { - $p => $b, - _ => panic!(), - } - }; - } - - // == Slices == - - // Matching slices using `ref` patterns: - let mut v = vec![N(0), N(1), N(2), N(3), N(4)]; - let mut vc = (0..=4).collect::>(); - - let [..] = v[..]; // Always matches. - m!(v[..], [N(0), ref sub @ .., N(4)] => c!(sub, &[N], n![1, 2, 3])); - m!(v[..], [N(0), ref sub @ ..] => c!(sub, &[N], n![1, 2, 3, 4])); - m!(v[..], [ref sub @ .., N(4)] => c!(sub, &[N], n![0, 1, 2, 3])); - m!(v[..], [ref sub @ .., _, _, _, _, _] => c!(sub, &[N], &n![] as &[N])); - m!(v[..], [_, _, _, _, _, ref sub @ ..] => c!(sub, &[N], &n![] as &[N])); - m!(vc[..], [x, .., y] => c!((x, y), (u8, u8), (0, 4))); - - // Matching slices using `ref mut` patterns: - let [..] = v[..]; // Always matches. - m!(v[..], [N(0), ref mut sub @ .., N(4)] => c!(sub, &mut [N], n![1, 2, 3])); - m!(v[..], [N(0), ref mut sub @ ..] => c!(sub, &mut [N], n![1, 2, 3, 4])); - m!(v[..], [ref mut sub @ .., N(4)] => c!(sub, &mut [N], n![0, 1, 2, 3])); - m!(v[..], [ref mut sub @ .., _, _, _, _, _] => c!(sub, &mut [N], &mut n![] as &mut [N])); - m!(v[..], [_, _, _, _, _, ref mut sub @ ..] => c!(sub, &mut [N], &mut n![] as &mut [N])); - m!(vc[..], [x, .., y] => c!((x, y), (u8, u8), (0, 4))); - - // Matching slices using default binding modes (&): - let [..] = &v[..]; // Always matches. - m!(&v[..], [N(0), sub @ .., N(4)] => c!(sub, &[N], n![1, 2, 3])); - m!(&v[..], [N(0), sub @ ..] => c!(sub, &[N], n![1, 2, 3, 4])); - m!(&v[..], [sub @ .., N(4)] => c!(sub, &[N], n![0, 1, 2, 3])); - m!(&v[..], [sub @ .., _, _, _, _, _] => c!(sub, &[N], &n![] as &[N])); - m!(&v[..], [_, _, _, _, _, sub @ ..] => c!(sub, &[N], &n![] as &[N])); - m!(&vc[..], [x, .., y] => c!((x, y), (&u8, &u8), (&0, &4))); - - // Matching slices using default binding modes (&mut): - let [..] = &mut v[..]; // Always matches. - m!(&mut v[..], [N(0), sub @ .., N(4)] => c!(sub, &mut [N], n![1, 2, 3])); - m!(&mut v[..], [N(0), sub @ ..] => c!(sub, &mut [N], n![1, 2, 3, 4])); - m!(&mut v[..], [sub @ .., N(4)] => c!(sub, &mut [N], n![0, 1, 2, 3])); - m!(&mut v[..], [sub @ .., _, _, _, _, _] => c!(sub, &mut [N], &mut n![] as &mut [N])); - m!(&mut v[..], [_, _, _, _, _, sub @ ..] => c!(sub, &mut [N], &mut n![] as &mut [N])); - m!(&mut vc[..], [x, .., y] => c!((x, y), (&mut u8, &mut u8), (&mut 0, &mut 4))); - - // == Arrays == - let mut v = n![0, 1, 2, 3, 4]; - let vc = [0, 1, 2, 3, 4]; - - // Matching arrays by value: - m!(v.clone(), [N(0), sub @ .., N(4)] => c!(sub, [N; 3], n![1, 2, 3])); - m!(v.clone(), [N(0), sub @ ..] => c!(sub, [N; 4], n![1, 2, 3, 4])); - m!(v.clone(), [sub @ .., N(4)] => c!(sub, [N; 4], n![0, 1, 2, 3])); - m!(v.clone(), [sub @ .., _, _, _, _, _] => c!(sub, [N; 0], n![] as [N; 0])); - m!(v.clone(), [_, _, _, _, _, sub @ ..] => c!(sub, [N; 0], n![] as [N; 0])); - m!(v.clone(), [x, .., y] => c!((x, y), (N, N), (N(0), N(4)))); - m!(v.clone(), [..] => ()); - - // Matching arrays by ref patterns: - m!(v, [N(0), ref sub @ .., N(4)] => c!(sub, &[N; 3], &n![1, 2, 3])); - m!(v, [N(0), ref sub @ ..] => c!(sub, &[N; 4], &n![1, 2, 3, 4])); - m!(v, [ref sub @ .., N(4)] => c!(sub, &[N; 4], &n![0, 1, 2, 3])); - m!(v, [ref sub @ .., _, _, _, _, _] => c!(sub, &[N; 0], &n![] as &[N; 0])); - m!(v, [_, _, _, _, _, ref sub @ ..] => c!(sub, &[N; 0], &n![] as &[N; 0])); - m!(vc, [x, .., y] => c!((x, y), (u8, u8), (0, 4))); - - // Matching arrays by ref mut patterns: - m!(v, [N(0), ref mut sub @ .., N(4)] => c!(sub, &mut [N; 3], &mut n![1, 2, 3])); - m!(v, [N(0), ref mut sub @ ..] => c!(sub, &mut [N; 4], &mut n![1, 2, 3, 4])); - m!(v, [ref mut sub @ .., N(4)] => c!(sub, &mut [N; 4], &mut n![0, 1, 2, 3])); - m!(v, [ref mut sub @ .., _, _, _, _, _] => c!(sub, &mut [N; 0], &mut n![] as &mut [N; 0])); - m!(v, [_, _, _, _, _, ref mut sub @ ..] => c!(sub, &mut [N; 0], &mut n![] as &mut [N; 0])); - - // Matching arrays by default binding modes (&): - m!(&v, [N(0), sub @ .., N(4)] => c!(sub, &[N; 3], &n![1, 2, 3])); - m!(&v, [N(0), sub @ ..] => c!(sub, &[N; 4], &n![1, 2, 3, 4])); - m!(&v, [sub @ .., N(4)] => c!(sub, &[N; 4], &n![0, 1, 2, 3])); - m!(&v, [sub @ .., _, _, _, _, _] => c!(sub, &[N; 0], &n![] as &[N; 0])); - m!(&v, [_, _, _, _, _, sub @ ..] => c!(sub, &[N; 0], &n![] as &[N; 0])); - m!(&v, [..] => ()); - m!(&v, [x, .., y] => c!((x, y), (&N, &N), (&N(0), &N(4)))); - - // Matching arrays by default binding modes (&mut): - m!(&mut v, [N(0), sub @ .., N(4)] => c!(sub, &mut [N; 3], &mut n![1, 2, 3])); - m!(&mut v, [N(0), sub @ ..] => c!(sub, &mut [N; 4], &mut n![1, 2, 3, 4])); - m!(&mut v, [sub @ .., N(4)] => c!(sub, &mut [N; 4], &mut n![0, 1, 2, 3])); - m!(&mut v, [sub @ .., _, _, _, _, _] => c!(sub, &mut [N; 0], &mut n![] as &[N; 0])); - m!(&mut v, [_, _, _, _, _, sub @ ..] => c!(sub, &mut [N; 0], &mut n![] as &[N; 0])); - m!(&mut v, [..] => ()); - m!(&mut v, [x, .., y] => c!((x, y), (&mut N, &mut N), (&mut N(0), &mut N(4)))); -} - -#[test] -fn test_chunk_by() { - let slice = &[1, 1, 1, 3, 3, 2, 2, 2, 1, 0]; - - let mut iter = slice.chunk_by(|a, b| a == b); - assert_eq!(iter.next(), Some(&[1, 1, 1][..])); - assert_eq!(iter.next(), Some(&[3, 3][..])); - assert_eq!(iter.next(), Some(&[2, 2, 2][..])); - assert_eq!(iter.next(), Some(&[1][..])); - assert_eq!(iter.next(), Some(&[0][..])); - assert_eq!(iter.next(), None); - - let mut iter = slice.chunk_by(|a, b| a == b); - assert_eq!(iter.next_back(), Some(&[0][..])); - assert_eq!(iter.next_back(), Some(&[1][..])); - assert_eq!(iter.next_back(), Some(&[2, 2, 2][..])); - assert_eq!(iter.next_back(), Some(&[3, 3][..])); - assert_eq!(iter.next_back(), Some(&[1, 1, 1][..])); - assert_eq!(iter.next_back(), None); - - let mut iter = slice.chunk_by(|a, b| a == b); - assert_eq!(iter.next(), Some(&[1, 1, 1][..])); - assert_eq!(iter.next_back(), Some(&[0][..])); - assert_eq!(iter.next(), Some(&[3, 3][..])); - assert_eq!(iter.next_back(), Some(&[1][..])); - assert_eq!(iter.next(), Some(&[2, 2, 2][..])); - assert_eq!(iter.next_back(), None); -} - -#[test] -fn test_chunk_by_mut() { - let slice = &mut [1, 1, 1, 3, 3, 2, 2, 2, 1, 0]; - - let mut iter = slice.chunk_by_mut(|a, b| a == b); - assert_eq!(iter.next(), Some(&mut [1, 1, 1][..])); - assert_eq!(iter.next(), Some(&mut [3, 3][..])); - assert_eq!(iter.next(), Some(&mut [2, 2, 2][..])); - assert_eq!(iter.next(), Some(&mut [1][..])); - assert_eq!(iter.next(), Some(&mut [0][..])); - assert_eq!(iter.next(), None); - - let mut iter = slice.chunk_by_mut(|a, b| a == b); - assert_eq!(iter.next_back(), Some(&mut [0][..])); - assert_eq!(iter.next_back(), Some(&mut [1][..])); - assert_eq!(iter.next_back(), Some(&mut [2, 2, 2][..])); - assert_eq!(iter.next_back(), Some(&mut [3, 3][..])); - assert_eq!(iter.next_back(), Some(&mut [1, 1, 1][..])); - assert_eq!(iter.next_back(), None); - - let mut iter = slice.chunk_by_mut(|a, b| a == b); - assert_eq!(iter.next(), Some(&mut [1, 1, 1][..])); - assert_eq!(iter.next_back(), Some(&mut [0][..])); - assert_eq!(iter.next(), Some(&mut [3, 3][..])); - assert_eq!(iter.next_back(), Some(&mut [1][..])); - assert_eq!(iter.next(), Some(&mut [2, 2, 2][..])); - assert_eq!(iter.next_back(), None); -} diff --git a/library/alloc/tests/str.rs b/library/alloc/tests/str.rs deleted file mode 100644 index 0078f5eaa3d2b..0000000000000 --- a/library/alloc/tests/str.rs +++ /dev/null @@ -1,2458 +0,0 @@ -#![allow(invalid_from_utf8)] - -use std::assert_matches::assert_matches; -use std::borrow::Cow; -use std::cmp::Ordering::{Equal, Greater, Less}; -use std::str::{from_utf8, from_utf8_unchecked}; - -#[test] -fn test_le() { - assert!("" <= ""); - assert!("" <= "foo"); - assert!("foo" <= "foo"); - assert_ne!("foo", "bar"); -} - -#[test] -fn test_find() { - assert_eq!("hello".find('l'), Some(2)); - assert_eq!("hello".find(|c: char| c == 'o'), Some(4)); - assert!("hello".find('x').is_none()); - assert!("hello".find(|c: char| c == 'x').is_none()); - assert_eq!("ประเทศไทย中华Việt Nam".find('华'), Some(30)); - assert_eq!("ประเทศไทย中华Việt Nam".find(|c: char| c == '华'), Some(30)); -} - -#[test] -fn test_rfind() { - assert_eq!("hello".rfind('l'), Some(3)); - assert_eq!("hello".rfind(|c: char| c == 'o'), Some(4)); - assert!("hello".rfind('x').is_none()); - assert!("hello".rfind(|c: char| c == 'x').is_none()); - assert_eq!("ประเทศไทย中华Việt Nam".rfind('华'), Some(30)); - assert_eq!("ประเทศไทย中华Việt Nam".rfind(|c: char| c == '华'), Some(30)); -} - -#[test] -fn test_collect() { - let empty = ""; - let s: String = empty.chars().collect(); - assert_eq!(empty, s); - let data = "ประเทศไทย中"; - let s: String = data.chars().collect(); - assert_eq!(data, s); -} - -#[test] -fn test_into_bytes() { - let data = String::from("asdf"); - let buf = data.into_bytes(); - assert_eq!(buf, b"asdf"); -} - -#[test] -fn test_find_str() { - // byte positions - assert_eq!("".find(""), Some(0)); - assert!("banana".find("apple pie").is_none()); - - let data = "abcabc"; - assert_eq!(data[0..6].find("ab"), Some(0)); - assert_eq!(data[2..6].find("ab"), Some(3 - 2)); - assert!(data[2..4].find("ab").is_none()); - - let string = "ประเทศไทย中华Việt Nam"; - let mut data = String::from(string); - data.push_str(string); - assert!(data.find("ไท华").is_none()); - assert_eq!(data[0..43].find(""), Some(0)); - assert_eq!(data[6..43].find(""), Some(6 - 6)); - - assert_eq!(data[0..43].find("ประ"), Some(0)); - assert_eq!(data[0..43].find("ทศไ"), Some(12)); - assert_eq!(data[0..43].find("ย中"), Some(24)); - assert_eq!(data[0..43].find("iệt"), Some(34)); - assert_eq!(data[0..43].find("Nam"), Some(40)); - - assert_eq!(data[43..86].find("ประ"), Some(43 - 43)); - assert_eq!(data[43..86].find("ทศไ"), Some(55 - 43)); - assert_eq!(data[43..86].find("ย中"), Some(67 - 43)); - assert_eq!(data[43..86].find("iệt"), Some(77 - 43)); - assert_eq!(data[43..86].find("Nam"), Some(83 - 43)); - - // find every substring -- assert that it finds it, or an earlier occurrence. - let string = "Việt Namacbaabcaabaaba"; - for (i, ci) in string.char_indices() { - let ip = i + ci.len_utf8(); - for j in string[ip..].char_indices().map(|(i, _)| i).chain(Some(string.len() - ip)) { - let pat = &string[i..ip + j]; - assert!(match string.find(pat) { - None => false, - Some(x) => x <= i, - }); - assert!(match string.rfind(pat) { - None => false, - Some(x) => x >= i, - }); - } - } -} - -fn s(x: &str) -> String { - x.to_string() -} - -macro_rules! test_concat { - ($expected: expr, $string: expr) => {{ - let s: String = $string.concat(); - assert_eq!($expected, s); - }}; -} - -#[test] -fn test_concat_for_different_types() { - test_concat!("ab", vec![s("a"), s("b")]); - test_concat!("ab", vec!["a", "b"]); -} - -#[test] -fn test_concat_for_different_lengths() { - let empty: &[&str] = &[]; - test_concat!("", empty); - test_concat!("a", ["a"]); - test_concat!("ab", ["a", "b"]); - test_concat!("abc", ["", "a", "bc"]); -} - -macro_rules! test_join { - ($expected: expr, $string: expr, $delim: expr) => {{ - let s = $string.join($delim); - assert_eq!($expected, s); - }}; -} - -#[test] -fn test_join_for_different_types() { - test_join!("a-b", ["a", "b"], "-"); - let hyphen = "-".to_string(); - test_join!("a-b", [s("a"), s("b")], &*hyphen); - test_join!("a-b", vec!["a", "b"], &*hyphen); - test_join!("a-b", &*vec!["a", "b"], "-"); - test_join!("a-b", vec![s("a"), s("b")], "-"); -} - -#[test] -fn test_join_for_different_lengths() { - let empty: &[&str] = &[]; - test_join!("", empty, "-"); - test_join!("a", ["a"], "-"); - test_join!("a-b", ["a", "b"], "-"); - test_join!("-a-bc", ["", "a", "bc"], "-"); -} - -// join has fast paths for small separators up to 4 bytes -// this tests the slow paths. -#[test] -fn test_join_for_different_lengths_with_long_separator() { - assert_eq!("~~~~~".len(), 15); - - let empty: &[&str] = &[]; - test_join!("", empty, "~~~~~"); - test_join!("a", ["a"], "~~~~~"); - test_join!("a~~~~~b", ["a", "b"], "~~~~~"); - test_join!("~~~~~a~~~~~bc", ["", "a", "bc"], "~~~~~"); -} - -#[test] -fn test_join_issue_80335() { - use core::{borrow::Borrow, cell::Cell}; - - struct WeirdBorrow { - state: Cell, - } - - impl Default for WeirdBorrow { - fn default() -> Self { - WeirdBorrow { state: Cell::new(false) } - } - } - - impl Borrow for WeirdBorrow { - fn borrow(&self) -> &str { - let state = self.state.get(); - if state { - "0" - } else { - self.state.set(true); - "123456" - } - } - } - - let arr: [WeirdBorrow; 3] = Default::default(); - test_join!("0-0-0", arr, "-"); -} - -#[test] -#[cfg_attr(miri, ignore)] // Miri is too slow -fn test_unsafe_slice() { - assert_eq!("ab", unsafe { "abc".get_unchecked(0..2) }); - assert_eq!("bc", unsafe { "abc".get_unchecked(1..3) }); - assert_eq!("", unsafe { "abc".get_unchecked(1..1) }); - fn a_million_letter_a() -> String { - let mut i = 0; - let mut rs = String::new(); - while i < 100000 { - rs.push_str("aaaaaaaaaa"); - i += 1; - } - rs - } - fn half_a_million_letter_a() -> String { - let mut i = 0; - let mut rs = String::new(); - while i < 100000 { - rs.push_str("aaaaa"); - i += 1; - } - rs - } - let letters = a_million_letter_a(); - assert_eq!(half_a_million_letter_a(), unsafe { letters.get_unchecked(0..500000) }); -} - -#[test] -fn test_starts_with() { - assert!("".starts_with("")); - assert!("abc".starts_with("")); - assert!("abc".starts_with("a")); - assert!(!"a".starts_with("abc")); - assert!(!"".starts_with("abc")); - assert!(!"ödd".starts_with("-")); - assert!("ödd".starts_with("öd")); -} - -#[test] -fn test_ends_with() { - assert!("".ends_with("")); - assert!("abc".ends_with("")); - assert!("abc".ends_with("c")); - assert!(!"a".ends_with("abc")); - assert!(!"".ends_with("abc")); - assert!(!"ddö".ends_with("-")); - assert!("ddö".ends_with("dö")); -} - -#[test] -fn test_is_empty() { - assert!("".is_empty()); - assert!(!"a".is_empty()); -} - -#[test] -fn test_replacen() { - assert_eq!("".replacen('a', "b", 5), ""); - assert_eq!("acaaa".replacen("a", "b", 3), "bcbba"); - assert_eq!("aaaa".replacen("a", "b", 0), "aaaa"); - - let test = "test"; - assert_eq!(" test test ".replacen(test, "toast", 3), " toast toast "); - assert_eq!(" test test ".replacen(test, "toast", 0), " test test "); - assert_eq!(" test test ".replacen(test, "", 5), " "); - - assert_eq!("qwer123zxc789".replacen(char::is_numeric, "", 3), "qwerzxc789"); -} - -#[test] -fn test_replace() { - let a = "a"; - assert_eq!("".replace(a, "b"), ""); - assert_eq!("a".replace(a, "b"), "b"); - assert_eq!("ab".replace(a, "b"), "bb"); - let test = "test"; - assert_eq!(" test test ".replace(test, "toast"), " toast toast "); - assert_eq!(" test test ".replace(test, ""), " "); -} - -#[test] -fn test_replace_2a() { - let data = "ประเทศไทย中华"; - let repl = "دولة الكويت"; - - let a = "ประเ"; - let a2 = "دولة الكويتทศไทย中华"; - assert_eq!(data.replace(a, repl), a2); -} - -#[test] -fn test_replace_2b() { - let data = "ประเทศไทย中华"; - let repl = "دولة الكويت"; - - let b = "ะเ"; - let b2 = "ปรدولة الكويتทศไทย中华"; - assert_eq!(data.replace(b, repl), b2); -} - -#[test] -fn test_replace_2c() { - let data = "ประเทศไทย中华"; - let repl = "دولة الكويت"; - - let c = "中华"; - let c2 = "ประเทศไทยدولة الكويت"; - assert_eq!(data.replace(c, repl), c2); -} - -#[test] -fn test_replace_2d() { - let data = "ประเทศไทย中华"; - let repl = "دولة الكويت"; - - let d = "ไท华"; - assert_eq!(data.replace(d, repl), data); -} - -#[test] -fn test_replace_pattern() { - let data = "abcdαβγδabcdαβγδ"; - assert_eq!(data.replace("dαβ", "😺😺😺"), "abc😺😺😺γδabc😺😺😺γδ"); - assert_eq!(data.replace('γ', "😺😺😺"), "abcdαβ😺😺😺δabcdαβ😺😺😺δ"); - assert_eq!(data.replace(&['a', 'γ'] as &[_], "😺😺😺"), "😺😺😺bcdαβ😺😺😺δ😺😺😺bcdαβ😺😺😺δ"); - assert_eq!(data.replace(|c| c == 'γ', "😺😺😺"), "abcdαβ😺😺😺δabcdαβ😺😺😺δ"); -} - -// The current implementation of SliceIndex fails to handle methods -// orthogonally from range types; therefore, it is worth testing -// all of the indexing operations on each input. -mod slice_index { - // Test a slicing operation **that should succeed,** - // testing it on all of the indexing methods. - // - // This is not suitable for testing failure on invalid inputs. - macro_rules! assert_range_eq { - ($s:expr, $range:expr, $expected:expr) => { - let mut s: String = $s.to_owned(); - let mut expected: String = $expected.to_owned(); - { - let s: &str = &s; - let expected: &str = &expected; - - assert_eq!(&s[$range], expected, "(in assertion for: index)"); - assert_eq!(s.get($range), Some(expected), "(in assertion for: get)"); - unsafe { - assert_eq!( - s.get_unchecked($range), - expected, - "(in assertion for: get_unchecked)", - ); - } - } - { - let s: &mut str = &mut s; - let expected: &mut str = &mut expected; - - assert_eq!(&mut s[$range], expected, "(in assertion for: index_mut)",); - assert_eq!( - s.get_mut($range), - Some(&mut expected[..]), - "(in assertion for: get_mut)", - ); - unsafe { - assert_eq!( - s.get_unchecked_mut($range), - expected, - "(in assertion for: get_unchecked_mut)", - ); - } - } - }; - } - - // Make sure the macro can actually detect bugs, - // because if it can't, then what are we even doing here? - // - // (Be aware this only demonstrates the ability to detect bugs - // in the FIRST method that panics, as the macro is not designed - // to be used in `should_panic`) - #[test] - #[should_panic(expected = "out of bounds")] - fn assert_range_eq_can_fail_by_panic() { - assert_range_eq!("abc", 0..5, "abc"); - } - - // (Be aware this only demonstrates the ability to detect bugs - // in the FIRST method it calls, as the macro is not designed - // to be used in `should_panic`) - #[test] - #[should_panic(expected = "==")] - fn assert_range_eq_can_fail_by_inequality() { - assert_range_eq!("abc", 0..2, "abc"); - } - - // Generates test cases for bad index operations. - // - // This generates `should_panic` test cases for Index/IndexMut - // and `None` test cases for get/get_mut. - macro_rules! panic_cases { - ($( - in mod $case_name:ident { - data: $data:expr; - - // optional: - // - // a similar input for which DATA[input] succeeds, and the corresponding - // output str. This helps validate "critical points" where an input range - // straddles the boundary between valid and invalid. - // (such as the input `len..len`, which is just barely valid) - $( - good: data[$good:expr] == $output:expr; - )* - - bad: data[$bad:expr]; - message: $expect_msg:expr; // must be a literal - } - )*) => {$( - mod $case_name { - #[test] - fn pass() { - let mut v: String = $data.into(); - - $( assert_range_eq!(v, $good, $output); )* - - { - let v: &str = &v; - assert_eq!(v.get($bad), None, "(in None assertion for get)"); - } - - { - let v: &mut str = &mut v; - assert_eq!(v.get_mut($bad), None, "(in None assertion for get_mut)"); - } - } - - #[test] - #[should_panic(expected = $expect_msg)] - fn index_fail() { - let v: String = $data.into(); - let v: &str = &v; - let _v = &v[$bad]; - } - - #[test] - #[should_panic(expected = $expect_msg)] - fn index_mut_fail() { - let mut v: String = $data.into(); - let v: &mut str = &mut v; - let _v = &mut v[$bad]; - } - } - )*}; - } - - #[test] - fn simple_ascii() { - assert_range_eq!("abc", .., "abc"); - - assert_range_eq!("abc", 0..2, "ab"); - assert_range_eq!("abc", 0..=1, "ab"); - assert_range_eq!("abc", ..2, "ab"); - assert_range_eq!("abc", ..=1, "ab"); - - assert_range_eq!("abc", 1..3, "bc"); - assert_range_eq!("abc", 1..=2, "bc"); - assert_range_eq!("abc", 1..1, ""); - assert_range_eq!("abc", 1..=0, ""); - } - - #[test] - fn simple_unicode() { - // 日本 - assert_range_eq!("\u{65e5}\u{672c}", .., "\u{65e5}\u{672c}"); - - assert_range_eq!("\u{65e5}\u{672c}", 0..3, "\u{65e5}"); - assert_range_eq!("\u{65e5}\u{672c}", 0..=2, "\u{65e5}"); - assert_range_eq!("\u{65e5}\u{672c}", ..3, "\u{65e5}"); - assert_range_eq!("\u{65e5}\u{672c}", ..=2, "\u{65e5}"); - - assert_range_eq!("\u{65e5}\u{672c}", 3..6, "\u{672c}"); - assert_range_eq!("\u{65e5}\u{672c}", 3..=5, "\u{672c}"); - assert_range_eq!("\u{65e5}\u{672c}", 3.., "\u{672c}"); - - let data = "ประเทศไทย中华"; - assert_range_eq!(data, 0..3, "ป"); - assert_range_eq!(data, 3..6, "ร"); - assert_range_eq!(data, 3..3, ""); - assert_range_eq!(data, 30..33, "华"); - - /*0: 中 - 3: 华 - 6: V - 7: i - 8: ệ - 11: t - 12: - 13: N - 14: a - 15: m */ - let ss = "中华Việt Nam"; - assert_range_eq!(ss, 3..6, "华"); - assert_range_eq!(ss, 6..16, "Việt Nam"); - assert_range_eq!(ss, 6..=15, "Việt Nam"); - assert_range_eq!(ss, 6.., "Việt Nam"); - - assert_range_eq!(ss, 0..3, "中"); - assert_range_eq!(ss, 3..7, "华V"); - assert_range_eq!(ss, 3..=6, "华V"); - assert_range_eq!(ss, 3..3, ""); - assert_range_eq!(ss, 3..=2, ""); - } - - #[test] - #[cfg_attr(target_os = "emscripten", ignore)] // hits an OOM - #[cfg_attr(miri, ignore)] // Miri is too slow - fn simple_big() { - fn a_million_letter_x() -> String { - let mut i = 0; - let mut rs = String::new(); - while i < 100000 { - rs.push_str("华华华华华华华华华华"); - i += 1; - } - rs - } - fn half_a_million_letter_x() -> String { - let mut i = 0; - let mut rs = String::new(); - while i < 100000 { - rs.push_str("华华华华华"); - i += 1; - } - rs - } - let letters = a_million_letter_x(); - assert_range_eq!(letters, 0..3 * 500000, half_a_million_letter_x()); - } - - #[test] - #[should_panic] - fn test_slice_fail() { - let _ = &"中华Việt Nam"[0..2]; - } - - panic_cases! { - in mod rangefrom_len { - data: "abcdef"; - good: data[6..] == ""; - bad: data[7..]; - message: "out of bounds"; - } - - in mod rangeto_len { - data: "abcdef"; - good: data[..6] == "abcdef"; - bad: data[..7]; - message: "out of bounds"; - } - - in mod rangetoinclusive_len { - data: "abcdef"; - good: data[..=5] == "abcdef"; - bad: data[..=6]; - message: "out of bounds"; - } - - in mod rangeinclusive_len { - data: "abcdef"; - good: data[0..=5] == "abcdef"; - bad: data[0..=6]; - message: "out of bounds"; - } - - in mod range_len_len { - data: "abcdef"; - good: data[6..6] == ""; - bad: data[7..7]; - message: "out of bounds"; - } - - in mod rangeinclusive_len_len { - data: "abcdef"; - good: data[6..=5] == ""; - bad: data[7..=6]; - message: "out of bounds"; - } - } - - panic_cases! { - in mod rangeinclusive_exhausted { - data: "abcdef"; - - good: data[0..=5] == "abcdef"; - good: data[{ - let mut iter = 0..=5; - iter.by_ref().count(); // exhaust it - iter - }] == ""; - - // 0..=6 is out of bounds before exhaustion, so it - // stands to reason that it still would be after. - bad: data[{ - let mut iter = 0..=6; - iter.by_ref().count(); // exhaust it - iter - }]; - message: "out of bounds"; - } - } - - panic_cases! { - in mod range_neg_width { - data: "abcdef"; - good: data[4..4] == ""; - bad: data[4..3]; - message: "begin <= end (4 <= 3)"; - } - - in mod rangeinclusive_neg_width { - data: "abcdef"; - good: data[4..=3] == ""; - bad: data[4..=2]; - message: "begin <= end (4 <= 3)"; - } - } - - mod overflow { - panic_cases! { - in mod rangeinclusive { - data: "hello"; - // note: using 0 specifically ensures that the result of overflowing is 0..0, - // so that `get` doesn't simply return None for the wrong reason. - bad: data[0..=usize::MAX]; - message: "maximum usize"; - } - - in mod rangetoinclusive { - data: "hello"; - bad: data[..=usize::MAX]; - message: "maximum usize"; - } - } - } - - mod boundary { - const DATA: &str = "abcαβγ"; - - const BAD_START: usize = 4; - const GOOD_START: usize = 3; - const BAD_END: usize = 6; - const GOOD_END: usize = 7; - const BAD_END_INCL: usize = BAD_END - 1; - const GOOD_END_INCL: usize = GOOD_END - 1; - - // it is especially important to test all of the different range types here - // because some of the logic may be duplicated as part of micro-optimizations - // to dodge unicode boundary checks on half-ranges. - panic_cases! { - in mod range_1 { - data: super::DATA; - bad: data[super::BAD_START..super::GOOD_END]; - message: - "byte index 4 is not a char boundary; it is inside 'α' (bytes 3..5) of"; - } - - in mod range_2 { - data: super::DATA; - bad: data[super::GOOD_START..super::BAD_END]; - message: - "byte index 6 is not a char boundary; it is inside 'β' (bytes 5..7) of"; - } - - in mod rangefrom { - data: super::DATA; - bad: data[super::BAD_START..]; - message: - "byte index 4 is not a char boundary; it is inside 'α' (bytes 3..5) of"; - } - - in mod rangeto { - data: super::DATA; - bad: data[..super::BAD_END]; - message: - "byte index 6 is not a char boundary; it is inside 'β' (bytes 5..7) of"; - } - - in mod rangeinclusive_1 { - data: super::DATA; - bad: data[super::BAD_START..=super::GOOD_END_INCL]; - message: - "byte index 4 is not a char boundary; it is inside 'α' (bytes 3..5) of"; - } - - in mod rangeinclusive_2 { - data: super::DATA; - bad: data[super::GOOD_START..=super::BAD_END_INCL]; - message: - "byte index 6 is not a char boundary; it is inside 'β' (bytes 5..7) of"; - } - - in mod rangetoinclusive { - data: super::DATA; - bad: data[..=super::BAD_END_INCL]; - message: - "byte index 6 is not a char boundary; it is inside 'β' (bytes 5..7) of"; - } - } - } - - const LOREM_PARAGRAPH: &str = "\ - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse quis lorem \ - sit amet dolor ultricies condimentum. Praesent iaculis purus elit, ac malesuada \ - quam malesuada in. Duis sed orci eros. Suspendisse sit amet magna mollis, mollis \ - nunc luctus, imperdiet mi. Integer fringilla non sem ut lacinia. Fusce varius \ - tortor a risus porttitor hendrerit. Morbi mauris dui, ultricies nec tempus vel, \ - gravida nec quam."; - - // check the panic includes the prefix of the sliced string - #[test] - #[should_panic(expected = "byte index 1024 is out of bounds of `Lorem ipsum dolor sit amet")] - fn test_slice_fail_truncated_1() { - let _ = &LOREM_PARAGRAPH[..1024]; - } - // check the truncation in the panic message - #[test] - #[should_panic(expected = "luctus, im`[...]")] - fn test_slice_fail_truncated_2() { - let _ = &LOREM_PARAGRAPH[..1024]; - } -} - -#[test] -fn test_str_slice_rangetoinclusive_ok() { - let s = "abcαβγ"; - assert_eq!(&s[..=2], "abc"); - assert_eq!(&s[..=4], "abcα"); -} - -#[test] -#[should_panic] -fn test_str_slice_rangetoinclusive_notok() { - let s = "abcαβγ"; - let _ = &s[..=3]; -} - -#[test] -fn test_str_slicemut_rangetoinclusive_ok() { - let mut s = "abcαβγ".to_owned(); - let s: &mut str = &mut s; - assert_eq!(&mut s[..=2], "abc"); - assert_eq!(&mut s[..=4], "abcα"); -} - -#[test] -#[should_panic] -fn test_str_slicemut_rangetoinclusive_notok() { - let mut s = "abcαβγ".to_owned(); - let s: &mut str = &mut s; - let _ = &mut s[..=3]; -} - -#[test] -fn test_is_char_boundary() { - let s = "ศไทย中华Việt Nam β-release 🐱123"; - assert!(s.is_char_boundary(0)); - assert!(s.is_char_boundary(s.len())); - assert!(!s.is_char_boundary(s.len() + 1)); - for (i, ch) in s.char_indices() { - // ensure character locations are boundaries and continuation bytes are not - assert!(s.is_char_boundary(i), "{} is a char boundary in {:?}", i, s); - for j in 1..ch.len_utf8() { - assert!( - !s.is_char_boundary(i + j), - "{} should not be a char boundary in {:?}", - i + j, - s - ); - } - } -} - -#[test] -fn test_trim_start_matches() { - let v: &[char] = &[]; - assert_eq!(" *** foo *** ".trim_start_matches(v), " *** foo *** "); - let chars: &[char] = &['*', ' ']; - assert_eq!(" *** foo *** ".trim_start_matches(chars), "foo *** "); - assert_eq!(" *** *** ".trim_start_matches(chars), ""); - assert_eq!("foo *** ".trim_start_matches(chars), "foo *** "); - - assert_eq!("11foo1bar11".trim_start_matches('1'), "foo1bar11"); - let chars: &[char] = &['1', '2']; - assert_eq!("12foo1bar12".trim_start_matches(chars), "foo1bar12"); - assert_eq!("123foo1bar123".trim_start_matches(|c: char| c.is_numeric()), "foo1bar123"); -} - -#[test] -fn test_trim_end_matches() { - let v: &[char] = &[]; - assert_eq!(" *** foo *** ".trim_end_matches(v), " *** foo *** "); - let chars: &[char] = &['*', ' ']; - assert_eq!(" *** foo *** ".trim_end_matches(chars), " *** foo"); - assert_eq!(" *** *** ".trim_end_matches(chars), ""); - assert_eq!(" *** foo".trim_end_matches(chars), " *** foo"); - - assert_eq!("11foo1bar11".trim_end_matches('1'), "11foo1bar"); - let chars: &[char] = &['1', '2']; - assert_eq!("12foo1bar12".trim_end_matches(chars), "12foo1bar"); - assert_eq!("123foo1bar123".trim_end_matches(|c: char| c.is_numeric()), "123foo1bar"); -} - -#[test] -fn test_trim_matches() { - let v: &[char] = &[]; - assert_eq!(" *** foo *** ".trim_matches(v), " *** foo *** "); - let chars: &[char] = &['*', ' ']; - assert_eq!(" *** foo *** ".trim_matches(chars), "foo"); - assert_eq!(" *** *** ".trim_matches(chars), ""); - assert_eq!("foo".trim_matches(chars), "foo"); - - assert_eq!("11foo1bar11".trim_matches('1'), "foo1bar"); - let chars: &[char] = &['1', '2']; - assert_eq!("12foo1bar12".trim_matches(chars), "foo1bar"); - assert_eq!("123foo1bar123".trim_matches(|c: char| c.is_numeric()), "foo1bar"); -} - -#[test] -fn test_trim_start() { - assert_eq!("".trim_start(), ""); - assert_eq!("a".trim_start(), "a"); - assert_eq!(" ".trim_start(), ""); - assert_eq!(" blah".trim_start(), "blah"); - assert_eq!(" \u{3000} wut".trim_start(), "wut"); - assert_eq!("hey ".trim_start(), "hey "); -} - -#[test] -fn test_trim_end() { - assert_eq!("".trim_end(), ""); - assert_eq!("a".trim_end(), "a"); - assert_eq!(" ".trim_end(), ""); - assert_eq!("blah ".trim_end(), "blah"); - assert_eq!("wut \u{3000} ".trim_end(), "wut"); - assert_eq!(" hey".trim_end(), " hey"); -} - -#[test] -fn test_trim() { - assert_eq!("".trim(), ""); - assert_eq!("a".trim(), "a"); - assert_eq!(" ".trim(), ""); - assert_eq!(" blah ".trim(), "blah"); - assert_eq!("\nwut \u{3000} ".trim(), "wut"); - assert_eq!(" hey dude ".trim(), "hey dude"); -} - -#[test] -fn test_is_whitespace() { - assert!("".chars().all(|c| c.is_whitespace())); - assert!(" ".chars().all(|c| c.is_whitespace())); - assert!("\u{2009}".chars().all(|c| c.is_whitespace())); // Thin space - assert!(" \n\t ".chars().all(|c| c.is_whitespace())); - assert!(!" _ ".chars().all(|c| c.is_whitespace())); -} - -#[test] -fn test_is_utf8() { - // deny overlong encodings - assert!(from_utf8(&[0xc0, 0x80]).is_err()); - assert!(from_utf8(&[0xc0, 0xae]).is_err()); - assert!(from_utf8(&[0xe0, 0x80, 0x80]).is_err()); - assert!(from_utf8(&[0xe0, 0x80, 0xaf]).is_err()); - assert!(from_utf8(&[0xe0, 0x81, 0x81]).is_err()); - assert!(from_utf8(&[0xf0, 0x82, 0x82, 0xac]).is_err()); - assert!(from_utf8(&[0xf4, 0x90, 0x80, 0x80]).is_err()); - - // deny surrogates - assert!(from_utf8(&[0xED, 0xA0, 0x80]).is_err()); - assert!(from_utf8(&[0xED, 0xBF, 0xBF]).is_err()); - - assert!(from_utf8(&[0xC2, 0x80]).is_ok()); - assert!(from_utf8(&[0xDF, 0xBF]).is_ok()); - assert!(from_utf8(&[0xE0, 0xA0, 0x80]).is_ok()); - assert!(from_utf8(&[0xED, 0x9F, 0xBF]).is_ok()); - assert!(from_utf8(&[0xEE, 0x80, 0x80]).is_ok()); - assert!(from_utf8(&[0xEF, 0xBF, 0xBF]).is_ok()); - assert!(from_utf8(&[0xF0, 0x90, 0x80, 0x80]).is_ok()); - assert!(from_utf8(&[0xF4, 0x8F, 0xBF, 0xBF]).is_ok()); -} - -#[test] -fn test_const_is_utf8() { - const _: () = { - // deny overlong encodings - assert!(from_utf8(&[0xc0, 0x80]).is_err()); - assert!(from_utf8(&[0xc0, 0xae]).is_err()); - assert!(from_utf8(&[0xe0, 0x80, 0x80]).is_err()); - assert!(from_utf8(&[0xe0, 0x80, 0xaf]).is_err()); - assert!(from_utf8(&[0xe0, 0x81, 0x81]).is_err()); - assert!(from_utf8(&[0xf0, 0x82, 0x82, 0xac]).is_err()); - assert!(from_utf8(&[0xf4, 0x90, 0x80, 0x80]).is_err()); - - // deny surrogates - assert!(from_utf8(&[0xED, 0xA0, 0x80]).is_err()); - assert!(from_utf8(&[0xED, 0xBF, 0xBF]).is_err()); - - assert!(from_utf8(&[0xC2, 0x80]).is_ok()); - assert!(from_utf8(&[0xDF, 0xBF]).is_ok()); - assert!(from_utf8(&[0xE0, 0xA0, 0x80]).is_ok()); - assert!(from_utf8(&[0xED, 0x9F, 0xBF]).is_ok()); - assert!(from_utf8(&[0xEE, 0x80, 0x80]).is_ok()); - assert!(from_utf8(&[0xEF, 0xBF, 0xBF]).is_ok()); - assert!(from_utf8(&[0xF0, 0x90, 0x80, 0x80]).is_ok()); - assert!(from_utf8(&[0xF4, 0x8F, 0xBF, 0xBF]).is_ok()); - }; -} - -#[test] -fn from_utf8_mostly_ascii() { - // deny invalid bytes embedded in long stretches of ascii - for i in 32..64 { - let mut data = [0; 128]; - data[i] = 0xC0; - assert!(from_utf8(&data).is_err()); - data[i] = 0xC2; - assert!(from_utf8(&data).is_err()); - } -} - -#[test] -fn const_from_utf8_mostly_ascii() { - const _: () = { - // deny invalid bytes embedded in long stretches of ascii - let mut i = 32; - while i < 64 { - let mut data = [0; 128]; - data[i] = 0xC0; - assert!(from_utf8(&data).is_err()); - data[i] = 0xC2; - assert!(from_utf8(&data).is_err()); - - i = i + 1; - } - }; -} - -#[test] -fn from_utf8_error() { - macro_rules! test { - ($input: expr, $expected_valid_up_to:pat, $expected_error_len:pat) => { - let error = from_utf8($input).unwrap_err(); - assert_matches!(error.valid_up_to(), $expected_valid_up_to); - assert_matches!(error.error_len(), $expected_error_len); - - const _: () = { - match from_utf8($input) { - Err(error) => { - let valid_up_to = error.valid_up_to(); - let error_len = error.error_len(); - - assert!(matches!(valid_up_to, $expected_valid_up_to)); - assert!(matches!(error_len, $expected_error_len)); - } - Ok(_) => unreachable!(), - } - }; - }; - } - test!(b"A\xC3\xA9 \xFF ", 4, Some(1)); - test!(b"A\xC3\xA9 \x80 ", 4, Some(1)); - test!(b"A\xC3\xA9 \xC1 ", 4, Some(1)); - test!(b"A\xC3\xA9 \xC1", 4, Some(1)); - test!(b"A\xC3\xA9 \xC2", 4, None); - test!(b"A\xC3\xA9 \xC2 ", 4, Some(1)); - test!(b"A\xC3\xA9 \xC2\xC0", 4, Some(1)); - test!(b"A\xC3\xA9 \xE0", 4, None); - test!(b"A\xC3\xA9 \xE0\x9F", 4, Some(1)); - test!(b"A\xC3\xA9 \xE0\xA0", 4, None); - test!(b"A\xC3\xA9 \xE0\xA0\xC0", 4, Some(2)); - test!(b"A\xC3\xA9 \xE0\xA0 ", 4, Some(2)); - test!(b"A\xC3\xA9 \xED\xA0\x80 ", 4, Some(1)); - test!(b"A\xC3\xA9 \xF1", 4, None); - test!(b"A\xC3\xA9 \xF1\x80", 4, None); - test!(b"A\xC3\xA9 \xF1\x80\x80", 4, None); - test!(b"A\xC3\xA9 \xF1 ", 4, Some(1)); - test!(b"A\xC3\xA9 \xF1\x80 ", 4, Some(2)); - test!(b"A\xC3\xA9 \xF1\x80\x80 ", 4, Some(3)); -} - -#[test] -fn test_as_bytes() { - // no null - let v = [ - 224, 184, 168, 224, 185, 132, 224, 184, 151, 224, 184, 162, 228, 184, 173, 229, 141, 142, - 86, 105, 225, 187, 135, 116, 32, 78, 97, 109, - ]; - let b: &[u8] = &[]; - assert_eq!("".as_bytes(), b); - assert_eq!("abc".as_bytes(), b"abc"); - assert_eq!("ศไทย中华Việt Nam".as_bytes(), v); -} - -#[test] -#[should_panic] -fn test_as_bytes_fail() { - // Don't double free. (I'm not sure if this exercises the - // original problem code path anymore.) - let s = String::from(""); - let _bytes = s.as_bytes(); - panic!(); -} - -#[test] -fn test_as_ptr() { - let buf = "hello".as_ptr(); - unsafe { - assert_eq!(*buf.add(0), b'h'); - assert_eq!(*buf.add(1), b'e'); - assert_eq!(*buf.add(2), b'l'); - assert_eq!(*buf.add(3), b'l'); - assert_eq!(*buf.add(4), b'o'); - } -} - -#[test] -fn vec_str_conversions() { - let s1: String = String::from("All mimsy were the borogoves"); - - let v: Vec = s1.as_bytes().to_vec(); - let s2: String = String::from(from_utf8(&v).unwrap()); - let mut i = 0; - let n1 = s1.len(); - let n2 = v.len(); - assert_eq!(n1, n2); - while i < n1 { - let a: u8 = s1.as_bytes()[i]; - let b: u8 = s2.as_bytes()[i]; - assert_eq!(a, b); - i += 1; - } -} - -#[test] -fn test_contains() { - assert!("abcde".contains("bcd")); - assert!("abcde".contains("abcd")); - assert!("abcde".contains("bcde")); - assert!("abcde".contains("")); - assert!("".contains("")); - assert!(!"abcde".contains("def")); - assert!(!"".contains("a")); - - let data = "ประเทศไทย中华Việt Nam"; - assert!(data.contains("ประเ")); - assert!(data.contains("ะเ")); - assert!(data.contains("中华")); - assert!(!data.contains("ไท华")); -} - -#[test] -fn test_contains_char() { - assert!("abc".contains('b')); - assert!("a".contains('a')); - assert!(!"abc".contains('d')); - assert!(!"".contains('a')); -} - -#[test] -fn test_split_at() { - let s = "ศไทย中华Việt Nam"; - for (index, _) in s.char_indices() { - let (a, b) = s.split_at(index); - assert_eq!(&s[..a.len()], a); - assert_eq!(&s[a.len()..], b); - } - let (a, b) = s.split_at(s.len()); - assert_eq!(a, s); - assert_eq!(b, ""); -} - -#[test] -fn test_split_at_mut() { - let mut s = "Hello World".to_string(); - { - let (a, b) = s.split_at_mut(5); - a.make_ascii_uppercase(); - b.make_ascii_lowercase(); - } - assert_eq!(s, "HELLO world"); -} - -#[test] -#[should_panic] -fn test_split_at_boundscheck() { - let s = "ศไทย中华Việt Nam"; - let _ = s.split_at(1); -} - -#[test] -fn test_escape_unicode() { - assert_eq!("abc".escape_unicode().to_string(), "\\u{61}\\u{62}\\u{63}"); - assert_eq!("a c".escape_unicode().to_string(), "\\u{61}\\u{20}\\u{63}"); - assert_eq!("\r\n\t".escape_unicode().to_string(), "\\u{d}\\u{a}\\u{9}"); - assert_eq!("'\"\\".escape_unicode().to_string(), "\\u{27}\\u{22}\\u{5c}"); - assert_eq!("\x00\x01\u{fe}\u{ff}".escape_unicode().to_string(), "\\u{0}\\u{1}\\u{fe}\\u{ff}"); - assert_eq!("\u{100}\u{ffff}".escape_unicode().to_string(), "\\u{100}\\u{ffff}"); - assert_eq!("\u{10000}\u{10ffff}".escape_unicode().to_string(), "\\u{10000}\\u{10ffff}"); - assert_eq!("ab\u{fb00}".escape_unicode().to_string(), "\\u{61}\\u{62}\\u{fb00}"); - assert_eq!("\u{1d4ea}\r".escape_unicode().to_string(), "\\u{1d4ea}\\u{d}"); -} - -#[test] -fn test_escape_debug() { - // Note that there are subtleties with the number of backslashes - // on the left- and right-hand sides. In particular, Unicode code points - // are usually escaped with two backslashes on the right-hand side, as - // they are escaped. However, when the character is unescaped (e.g., for - // printable characters), only a single backslash appears (as the character - // itself appears in the debug string). - assert_eq!("abc".escape_debug().to_string(), "abc"); - assert_eq!("a c".escape_debug().to_string(), "a c"); - assert_eq!("éèê".escape_debug().to_string(), "éèê"); - assert_eq!("\0\r\n\t".escape_debug().to_string(), "\\0\\r\\n\\t"); - assert_eq!("'\"\\".escape_debug().to_string(), "\\'\\\"\\\\"); - assert_eq!("\u{7f}\u{ff}".escape_debug().to_string(), "\\u{7f}\u{ff}"); - assert_eq!("\u{100}\u{ffff}".escape_debug().to_string(), "\u{100}\\u{ffff}"); - assert_eq!("\u{10000}\u{10ffff}".escape_debug().to_string(), "\u{10000}\\u{10ffff}"); - assert_eq!("ab\u{200b}".escape_debug().to_string(), "ab\\u{200b}"); - assert_eq!("\u{10d4ea}\r".escape_debug().to_string(), "\\u{10d4ea}\\r"); - assert_eq!( - "\u{301}a\u{301}bé\u{e000}".escape_debug().to_string(), - "\\u{301}a\u{301}bé\\u{e000}" - ); -} - -#[test] -fn test_escape_default() { - assert_eq!("abc".escape_default().to_string(), "abc"); - assert_eq!("a c".escape_default().to_string(), "a c"); - assert_eq!("éèê".escape_default().to_string(), "\\u{e9}\\u{e8}\\u{ea}"); - assert_eq!("\r\n\t".escape_default().to_string(), "\\r\\n\\t"); - assert_eq!("'\"\\".escape_default().to_string(), "\\'\\\"\\\\"); - assert_eq!("\u{7f}\u{ff}".escape_default().to_string(), "\\u{7f}\\u{ff}"); - assert_eq!("\u{100}\u{ffff}".escape_default().to_string(), "\\u{100}\\u{ffff}"); - assert_eq!("\u{10000}\u{10ffff}".escape_default().to_string(), "\\u{10000}\\u{10ffff}"); - assert_eq!("ab\u{200b}".escape_default().to_string(), "ab\\u{200b}"); - assert_eq!("\u{10d4ea}\r".escape_default().to_string(), "\\u{10d4ea}\\r"); -} - -#[test] -fn test_total_ord() { - assert_eq!("1234".cmp("123"), Greater); - assert_eq!("123".cmp("1234"), Less); - assert_eq!("1234".cmp("1234"), Equal); - assert_eq!("12345555".cmp("123456"), Less); - assert_eq!("22".cmp("1234"), Greater); -} - -#[test] -fn test_iterator() { - let s = "ศไทย中华Việt Nam"; - let v = ['ศ', 'ไ', 'ท', 'ย', '中', '华', 'V', 'i', 'ệ', 't', ' ', 'N', 'a', 'm']; - - let mut pos = 0; - let it = s.chars(); - - for c in it { - assert_eq!(c, v[pos]); - pos += 1; - } - assert_eq!(pos, v.len()); - assert_eq!(s.chars().count(), v.len()); -} - -#[test] -fn test_iterator_advance() { - let s = "「赤錆」と呼ばれる鉄錆は、水の存在下での鉄の自然酸化によって生じる、オキシ水酸化鉄(III) 等の(含水)酸化物粒子の疎な凝集膜であるとみなせる。"; - let chars: Vec = s.chars().collect(); - let mut it = s.chars(); - it.advance_by(1).unwrap(); - assert_eq!(it.next(), Some(chars[1])); - it.advance_by(33).unwrap(); - assert_eq!(it.next(), Some(chars[35])); -} - -#[test] -fn test_rev_iterator() { - let s = "ศไทย中华Việt Nam"; - let v = ['m', 'a', 'N', ' ', 't', 'ệ', 'i', 'V', '华', '中', 'ย', 'ท', 'ไ', 'ศ']; - - let mut pos = 0; - let it = s.chars().rev(); - - for c in it { - assert_eq!(c, v[pos]); - pos += 1; - } - assert_eq!(pos, v.len()); -} - -#[test] -fn test_to_lowercase_rev_iterator() { - let s = "AÖßÜ💩ΣΤΙΓΜΑΣDžfiİ"; - let v = ['\u{307}', 'i', 'fi', 'dž', 'σ', 'α', 'μ', 'γ', 'ι', 'τ', 'σ', '💩', 'ü', 'ß', 'ö', 'a']; - - let mut pos = 0; - let it = s.chars().flat_map(|c| c.to_lowercase()).rev(); - - for c in it { - assert_eq!(c, v[pos]); - pos += 1; - } - assert_eq!(pos, v.len()); -} - -#[test] -fn test_to_uppercase_rev_iterator() { - let s = "aößü💩στιγμαςDžfiᾀ"; - let v = - ['Ι', 'Ἀ', 'I', 'F', 'DŽ', 'Σ', 'Α', 'Μ', 'Γ', 'Ι', 'Τ', 'Σ', '💩', 'Ü', 'S', 'S', 'Ö', 'A']; - - let mut pos = 0; - let it = s.chars().flat_map(|c| c.to_uppercase()).rev(); - - for c in it { - assert_eq!(c, v[pos]); - pos += 1; - } - assert_eq!(pos, v.len()); -} - -#[test] -#[cfg_attr(miri, ignore)] // Miri is too slow -fn test_chars_decoding() { - let mut bytes = [0; 4]; - for c in (0..0x110000).filter_map(std::char::from_u32) { - let s = c.encode_utf8(&mut bytes); - if Some(c) != s.chars().next() { - panic!("character {:x}={} does not decode correctly", c as u32, c); - } - } -} - -#[test] -#[cfg_attr(miri, ignore)] // Miri is too slow -fn test_chars_rev_decoding() { - let mut bytes = [0; 4]; - for c in (0..0x110000).filter_map(std::char::from_u32) { - let s = c.encode_utf8(&mut bytes); - if Some(c) != s.chars().rev().next() { - panic!("character {:x}={} does not decode correctly", c as u32, c); - } - } -} - -#[test] -fn test_iterator_clone() { - let s = "ศไทย中华Việt Nam"; - let mut it = s.chars(); - it.next(); - assert!(it.clone().zip(it).all(|(x, y)| x == y)); -} - -#[test] -fn test_iterator_last() { - let s = "ศไทย中华Việt Nam"; - let mut it = s.chars(); - it.next(); - assert_eq!(it.last(), Some('m')); -} - -#[test] -fn test_chars_debug() { - let s = "ศไทย中华Việt Nam"; - let c = s.chars(); - assert_eq!( - format!("{c:?}"), - r#"Chars(['ศ', 'ไ', 'ท', 'ย', '中', '华', 'V', 'i', 'ệ', 't', ' ', 'N', 'a', 'm'])"# - ); -} - -#[test] -fn test_bytesator() { - let s = "ศไทย中华Việt Nam"; - let v = [ - 224, 184, 168, 224, 185, 132, 224, 184, 151, 224, 184, 162, 228, 184, 173, 229, 141, 142, - 86, 105, 225, 187, 135, 116, 32, 78, 97, 109, - ]; - let mut pos = 0; - - for b in s.bytes() { - assert_eq!(b, v[pos]); - pos += 1; - } -} - -#[test] -fn test_bytes_revator() { - let s = "ศไทย中华Việt Nam"; - let v = [ - 224, 184, 168, 224, 185, 132, 224, 184, 151, 224, 184, 162, 228, 184, 173, 229, 141, 142, - 86, 105, 225, 187, 135, 116, 32, 78, 97, 109, - ]; - let mut pos = v.len(); - - for b in s.bytes().rev() { - pos -= 1; - assert_eq!(b, v[pos]); - } -} - -#[test] -fn test_bytesator_nth() { - let s = "ศไทย中华Việt Nam"; - let v = [ - 224, 184, 168, 224, 185, 132, 224, 184, 151, 224, 184, 162, 228, 184, 173, 229, 141, 142, - 86, 105, 225, 187, 135, 116, 32, 78, 97, 109, - ]; - - let mut b = s.bytes(); - assert_eq!(b.nth(2).unwrap(), v[2]); - assert_eq!(b.nth(10).unwrap(), v[10]); - assert_eq!(b.nth(200), None); -} - -#[test] -fn test_bytesator_count() { - let s = "ศไทย中华Việt Nam"; - - let b = s.bytes(); - assert_eq!(b.count(), 28) -} - -#[test] -fn test_bytesator_last() { - let s = "ศไทย中华Việt Nam"; - - let b = s.bytes(); - assert_eq!(b.last().unwrap(), 109) -} - -#[test] -fn test_char_indicesator() { - let s = "ศไทย中华Việt Nam"; - let p = [0, 3, 6, 9, 12, 15, 18, 19, 20, 23, 24, 25, 26, 27]; - let v = ['ศ', 'ไ', 'ท', 'ย', '中', '华', 'V', 'i', 'ệ', 't', ' ', 'N', 'a', 'm']; - - let mut pos = 0; - let it = s.char_indices(); - - for c in it { - assert_eq!(c, (p[pos], v[pos])); - pos += 1; - } - assert_eq!(pos, v.len()); - assert_eq!(pos, p.len()); -} - -#[test] -fn test_char_indices_revator() { - let s = "ศไทย中华Việt Nam"; - let p = [27, 26, 25, 24, 23, 20, 19, 18, 15, 12, 9, 6, 3, 0]; - let v = ['m', 'a', 'N', ' ', 't', 'ệ', 'i', 'V', '华', '中', 'ย', 'ท', 'ไ', 'ศ']; - - let mut pos = 0; - let it = s.char_indices().rev(); - - for c in it { - assert_eq!(c, (p[pos], v[pos])); - pos += 1; - } - assert_eq!(pos, v.len()); - assert_eq!(pos, p.len()); -} - -#[test] -fn test_char_indices_last() { - let s = "ศไทย中华Việt Nam"; - let mut it = s.char_indices(); - it.next(); - assert_eq!(it.last(), Some((27, 'm'))); -} - -#[test] -fn test_splitn_char_iterator() { - let data = "\nMäry häd ä little lämb\nLittle lämb\n"; - - let split: Vec<&str> = data.splitn(4, ' ').collect(); - assert_eq!(split, ["\nMäry", "häd", "ä", "little lämb\nLittle lämb\n"]); - - let split: Vec<&str> = data.splitn(4, |c: char| c == ' ').collect(); - assert_eq!(split, ["\nMäry", "häd", "ä", "little lämb\nLittle lämb\n"]); - - // Unicode - let split: Vec<&str> = data.splitn(4, 'ä').collect(); - assert_eq!(split, ["\nM", "ry h", "d ", " little lämb\nLittle lämb\n"]); - - let split: Vec<&str> = data.splitn(4, |c: char| c == 'ä').collect(); - assert_eq!(split, ["\nM", "ry h", "d ", " little lämb\nLittle lämb\n"]); -} - -#[test] -fn test_split_char_iterator_no_trailing() { - let data = "\nMäry häd ä little lämb\nLittle lämb\n"; - - let split: Vec<&str> = data.split('\n').collect(); - assert_eq!(split, ["", "Märy häd ä little lämb", "Little lämb", ""]); - - let split: Vec<&str> = data.split_terminator('\n').collect(); - assert_eq!(split, ["", "Märy häd ä little lämb", "Little lämb"]); -} - -#[test] -fn test_split_char_iterator_inclusive() { - let data = "\nMäry häd ä little lämb\nLittle lämb\n"; - - let split: Vec<&str> = data.split_inclusive('\n').collect(); - assert_eq!(split, ["\n", "Märy häd ä little lämb\n", "Little lämb\n"]); - - let uppercase_separated = "SheePSharKTurtlECaT"; - let mut first_char = true; - let split: Vec<&str> = uppercase_separated - .split_inclusive(|c: char| { - let split = !first_char && c.is_uppercase(); - first_char = split; - split - }) - .collect(); - assert_eq!(split, ["SheeP", "SharK", "TurtlE", "CaT"]); -} - -#[test] -fn test_split_char_iterator_inclusive_rev() { - let data = "\nMäry häd ä little lämb\nLittle lämb\n"; - - let split: Vec<&str> = data.split_inclusive('\n').rev().collect(); - assert_eq!(split, ["Little lämb\n", "Märy häd ä little lämb\n", "\n"]); - - // Note that the predicate is stateful and thus dependent - // on the iteration order. - // (A different predicate is needed for reverse iterator vs normal iterator.) - // Not sure if anything can be done though. - let uppercase_separated = "SheePSharKTurtlECaT"; - let mut term_char = true; - let split: Vec<&str> = uppercase_separated - .split_inclusive(|c: char| { - let split = term_char && c.is_uppercase(); - term_char = c.is_uppercase(); - split - }) - .rev() - .collect(); - assert_eq!(split, ["CaT", "TurtlE", "SharK", "SheeP"]); -} - -#[test] -fn test_rsplit() { - let data = "\nMäry häd ä little lämb\nLittle lämb\n"; - - let split: Vec<&str> = data.rsplit(' ').collect(); - assert_eq!(split, ["lämb\n", "lämb\nLittle", "little", "ä", "häd", "\nMäry"]); - - let split: Vec<&str> = data.rsplit("lämb").collect(); - assert_eq!(split, ["\n", "\nLittle ", "\nMäry häd ä little "]); - - let split: Vec<&str> = data.rsplit(|c: char| c == 'ä').collect(); - assert_eq!(split, ["mb\n", "mb\nLittle l", " little l", "d ", "ry h", "\nM"]); -} - -#[test] -fn test_rsplitn() { - let data = "\nMäry häd ä little lämb\nLittle lämb\n"; - - let split: Vec<&str> = data.rsplitn(2, ' ').collect(); - assert_eq!(split, ["lämb\n", "\nMäry häd ä little lämb\nLittle"]); - - let split: Vec<&str> = data.rsplitn(2, "lämb").collect(); - assert_eq!(split, ["\n", "\nMäry häd ä little lämb\nLittle "]); - - let split: Vec<&str> = data.rsplitn(2, |c: char| c == 'ä').collect(); - assert_eq!(split, ["mb\n", "\nMäry häd ä little lämb\nLittle l"]); -} - -#[test] -fn test_split_once() { - assert_eq!("".split_once("->"), None); - assert_eq!("-".split_once("->"), None); - assert_eq!("->".split_once("->"), Some(("", ""))); - assert_eq!("a->".split_once("->"), Some(("a", ""))); - assert_eq!("->b".split_once("->"), Some(("", "b"))); - assert_eq!("a->b".split_once("->"), Some(("a", "b"))); - assert_eq!("a->b->c".split_once("->"), Some(("a", "b->c"))); - assert_eq!("---".split_once("--"), Some(("", "-"))); -} - -#[test] -fn test_rsplit_once() { - assert_eq!("".rsplit_once("->"), None); - assert_eq!("-".rsplit_once("->"), None); - assert_eq!("->".rsplit_once("->"), Some(("", ""))); - assert_eq!("a->".rsplit_once("->"), Some(("a", ""))); - assert_eq!("->b".rsplit_once("->"), Some(("", "b"))); - assert_eq!("a->b".rsplit_once("->"), Some(("a", "b"))); - assert_eq!("a->b->c".rsplit_once("->"), Some(("a->b", "c"))); - assert_eq!("---".rsplit_once("--"), Some(("-", ""))); -} - -#[test] -fn test_split_whitespace() { - let data = "\n \tMäry häd\tä little lämb\nLittle lämb\n"; - let words: Vec<&str> = data.split_whitespace().collect(); - assert_eq!(words, ["Märy", "häd", "ä", "little", "lämb", "Little", "lämb"]) -} - -#[test] -fn test_lines() { - fn t(data: &str, expected: &[&str]) { - let lines: Vec<&str> = data.lines().collect(); - assert_eq!(lines, expected); - } - t("", &[]); - t("\n", &[""]); - t("\n2nd", &["", "2nd"]); - t("\r\n", &[""]); - t("bare\r", &["bare\r"]); - t("bare\rcr", &["bare\rcr"]); - t("Text\n\r", &["Text", "\r"]); - t( - "\nMäry häd ä little lämb\n\r\nLittle lämb\n", - &["", "Märy häd ä little lämb", "", "Little lämb"], - ); - t( - "\r\nMäry häd ä little lämb\n\nLittle lämb", - &["", "Märy häd ä little lämb", "", "Little lämb"], - ); -} - -#[test] -fn test_splitator() { - fn t(s: &str, sep: &str, u: &[&str]) { - let v: Vec<&str> = s.split(sep).collect(); - assert_eq!(v, u); - } - t("--1233345--", "12345", &["--1233345--"]); - t("abc::hello::there", "::", &["abc", "hello", "there"]); - t("::hello::there", "::", &["", "hello", "there"]); - t("hello::there::", "::", &["hello", "there", ""]); - t("::hello::there::", "::", &["", "hello", "there", ""]); - t("ประเทศไทย中华Việt Nam", "中华", &["ประเทศไทย", "Việt Nam"]); - t("zzXXXzzYYYzz", "zz", &["", "XXX", "YYY", ""]); - t("zzXXXzYYYz", "XXX", &["zz", "zYYYz"]); - t(".XXX.YYY.", ".", &["", "XXX", "YYY", ""]); - t("", ".", &[""]); - t("zz", "zz", &["", ""]); - t("ok", "z", &["ok"]); - t("zzz", "zz", &["", "z"]); - t("zzzzz", "zz", &["", "", "z"]); -} - -#[test] -fn test_str_default() { - use std::default::Default; - - fn t>() { - let s: S = Default::default(); - assert_eq!(s.as_ref(), ""); - } - - t::<&str>(); - t::(); - t::<&mut str>(); -} - -#[test] -fn test_str_container() { - fn sum_len(v: &[&str]) -> usize { - v.iter().map(|x| x.len()).sum() - } - - let s = "01234"; - assert_eq!(5, sum_len(&["012", "", "34"])); - assert_eq!(5, sum_len(&["01", "2", "34", ""])); - assert_eq!(5, sum_len(&[s])); -} - -#[test] -fn test_str_from_utf8() { - let xs = b"hello"; - assert_eq!(from_utf8(xs), Ok("hello")); - - let xs = "ศไทย中华Việt Nam".as_bytes(); - assert_eq!(from_utf8(xs), Ok("ศไทย中华Việt Nam")); - - let xs = b"hello\xFF"; - assert!(from_utf8(xs).is_err()); -} - -#[test] -fn test_pattern_deref_forward() { - let data = "aabcdaa"; - assert!(data.contains("bcd")); - assert!(data.contains(&"bcd")); - assert!(data.contains(&"bcd".to_string())); -} - -#[test] -fn test_empty_match_indices() { - let data = "aä中!"; - let vec: Vec<_> = data.match_indices("").collect(); - assert_eq!(vec, [(0, ""), (1, ""), (3, ""), (6, ""), (7, "")]); -} - -#[test] -fn test_bool_from_str() { - assert_eq!("true".parse().ok(), Some(true)); - assert_eq!("false".parse().ok(), Some(false)); - assert_eq!("not even a boolean".parse::().ok(), None); -} - -fn check_contains_all_substrings(haystack: &str) { - let mut modified_needle = String::new(); - - for i in 0..haystack.len() { - // check different haystack lengths since we special-case short haystacks. - let haystack = &haystack[0..i]; - assert!(haystack.contains("")); - for j in 0..haystack.len() { - for k in j + 1..=haystack.len() { - let needle = &haystack[j..k]; - assert!(haystack.contains(needle)); - modified_needle.clear(); - modified_needle.push_str(needle); - modified_needle.replace_range(0..1, "\0"); - assert!(!haystack.contains(&modified_needle)); - - modified_needle.clear(); - modified_needle.push_str(needle); - modified_needle.replace_range(needle.len() - 1..needle.len(), "\0"); - assert!(!haystack.contains(&modified_needle)); - } - } - } -} - -#[test] -#[cfg_attr(miri, ignore)] // Miri is too slow -fn strslice_issue_16589() { - assert!("bananas".contains("nana")); - - // prior to the fix for #16589, x.contains("abcdabcd") returned false - // test all substrings for good measure - check_contains_all_substrings("012345678901234567890123456789bcdabcdabcd"); -} - -#[test] -fn strslice_issue_16878() { - assert!(!"1234567ah012345678901ah".contains("hah")); - assert!(!"00abc01234567890123456789abc".contains("bcabc")); -} - -#[test] -fn strslice_issue_104726() { - // Edge-case in the simd_contains impl. - // The first and last byte are the same so it backtracks by one byte - // which aligns with the end of the string. Previously incorrect offset calculations - // lead to out-of-bounds slicing. - #[rustfmt::skip] - let needle = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaba"; - let haystack = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaab"; - assert!(!haystack.contains(needle)); -} - -#[test] -#[cfg_attr(miri, ignore)] // Miri is too slow -fn test_strslice_contains() { - let x = "There are moments, Jeeves, when one asks oneself, 'Do trousers matter?'"; - check_contains_all_substrings(x); -} - -#[test] -fn test_rsplitn_char_iterator() { - let data = "\nMäry häd ä little lämb\nLittle lämb\n"; - - let mut split: Vec<&str> = data.rsplitn(4, ' ').collect(); - split.reverse(); - assert_eq!(split, ["\nMäry häd ä", "little", "lämb\nLittle", "lämb\n"]); - - let mut split: Vec<&str> = data.rsplitn(4, |c: char| c == ' ').collect(); - split.reverse(); - assert_eq!(split, ["\nMäry häd ä", "little", "lämb\nLittle", "lämb\n"]); - - // Unicode - let mut split: Vec<&str> = data.rsplitn(4, 'ä').collect(); - split.reverse(); - assert_eq!(split, ["\nMäry häd ", " little l", "mb\nLittle l", "mb\n"]); - - let mut split: Vec<&str> = data.rsplitn(4, |c: char| c == 'ä').collect(); - split.reverse(); - assert_eq!(split, ["\nMäry häd ", " little l", "mb\nLittle l", "mb\n"]); -} - -#[test] -fn test_split_char_iterator() { - let data = "\nMäry häd ä little lämb\nLittle lämb\n"; - - let split: Vec<&str> = data.split(' ').collect(); - assert_eq!(split, ["\nMäry", "häd", "ä", "little", "lämb\nLittle", "lämb\n"]); - - let mut rsplit: Vec<&str> = data.split(' ').rev().collect(); - rsplit.reverse(); - assert_eq!(rsplit, ["\nMäry", "häd", "ä", "little", "lämb\nLittle", "lämb\n"]); - - let split: Vec<&str> = data.split(|c: char| c == ' ').collect(); - assert_eq!(split, ["\nMäry", "häd", "ä", "little", "lämb\nLittle", "lämb\n"]); - - let mut rsplit: Vec<&str> = data.split(|c: char| c == ' ').rev().collect(); - rsplit.reverse(); - assert_eq!(rsplit, ["\nMäry", "häd", "ä", "little", "lämb\nLittle", "lämb\n"]); - - // Unicode - let split: Vec<&str> = data.split('ä').collect(); - assert_eq!(split, ["\nM", "ry h", "d ", " little l", "mb\nLittle l", "mb\n"]); - - let mut rsplit: Vec<&str> = data.split('ä').rev().collect(); - rsplit.reverse(); - assert_eq!(rsplit, ["\nM", "ry h", "d ", " little l", "mb\nLittle l", "mb\n"]); - - let split: Vec<&str> = data.split(|c: char| c == 'ä').collect(); - assert_eq!(split, ["\nM", "ry h", "d ", " little l", "mb\nLittle l", "mb\n"]); - - let mut rsplit: Vec<&str> = data.split(|c: char| c == 'ä').rev().collect(); - rsplit.reverse(); - assert_eq!(rsplit, ["\nM", "ry h", "d ", " little l", "mb\nLittle l", "mb\n"]); -} - -#[test] -fn test_rev_split_char_iterator_no_trailing() { - let data = "\nMäry häd ä little lämb\nLittle lämb\n"; - - let mut split: Vec<&str> = data.split('\n').rev().collect(); - split.reverse(); - assert_eq!(split, ["", "Märy häd ä little lämb", "Little lämb", ""]); - - let mut split: Vec<&str> = data.split_terminator('\n').rev().collect(); - split.reverse(); - assert_eq!(split, ["", "Märy häd ä little lämb", "Little lämb"]); -} - -#[test] -fn test_utf16_code_units() { - assert_eq!("é\u{1F4A9}".encode_utf16().collect::>(), [0xE9, 0xD83D, 0xDCA9]) -} - -#[test] -fn test_utf16_size_hint() { - assert_eq!("".encode_utf16().size_hint(), (0, Some(0))); - assert_eq!("123".encode_utf16().size_hint(), (1, Some(3))); - assert_eq!("1234".encode_utf16().size_hint(), (2, Some(4))); - assert_eq!("12345678".encode_utf16().size_hint(), (3, Some(8))); - - fn hint_vec(src: &str) -> Vec<(usize, Option)> { - let mut it = src.encode_utf16(); - let mut result = Vec::new(); - result.push(it.size_hint()); - while it.next().is_some() { - result.push(it.size_hint()) - } - result - } - - assert_eq!(hint_vec("12"), [(1, Some(2)), (1, Some(1)), (0, Some(0))]); - assert_eq!(hint_vec("\u{101234}"), [(2, Some(4)), (1, Some(1)), (0, Some(0))]); - assert_eq!(hint_vec("\u{101234}a"), [(2, Some(5)), (2, Some(2)), (1, Some(1)), (0, Some(0))]); -} - -#[test] -fn starts_with_in_unicode() { - assert!(!"├── Cargo.toml".starts_with("# ")); -} - -#[test] -fn starts_short_long() { - assert!(!"".starts_with("##")); - assert!(!"##".starts_with("####")); - assert!("####".starts_with("##")); - assert!(!"##ä".starts_with("####")); - assert!("####ä".starts_with("##")); - assert!(!"##".starts_with("####ä")); - assert!("##ä##".starts_with("##ä")); - - assert!("".starts_with("")); - assert!("ä".starts_with("")); - assert!("#ä".starts_with("")); - assert!("##ä".starts_with("")); - assert!("ä###".starts_with("")); - assert!("#ä##".starts_with("")); - assert!("##ä#".starts_with("")); -} - -#[test] -fn contains_weird_cases() { - assert!("* \t".contains(' ')); - assert!(!"* \t".contains('?')); - assert!(!"* \t".contains('\u{1F4A9}')); -} - -#[test] -fn trim_ws() { - assert_eq!(" \t a \t ".trim_start_matches(|c: char| c.is_whitespace()), "a \t "); - assert_eq!(" \t a \t ".trim_end_matches(|c: char| c.is_whitespace()), " \t a"); - assert_eq!(" \t a \t ".trim_start_matches(|c: char| c.is_whitespace()), "a \t "); - assert_eq!(" \t a \t ".trim_end_matches(|c: char| c.is_whitespace()), " \t a"); - assert_eq!(" \t a \t ".trim_matches(|c: char| c.is_whitespace()), "a"); - assert_eq!(" \t \t ".trim_start_matches(|c: char| c.is_whitespace()), ""); - assert_eq!(" \t \t ".trim_end_matches(|c: char| c.is_whitespace()), ""); - assert_eq!(" \t \t ".trim_start_matches(|c: char| c.is_whitespace()), ""); - assert_eq!(" \t \t ".trim_end_matches(|c: char| c.is_whitespace()), ""); - assert_eq!(" \t \t ".trim_matches(|c: char| c.is_whitespace()), ""); -} - -#[test] -fn to_lowercase() { - assert_eq!("".to_lowercase(), ""); - assert_eq!("AÉDžaé ".to_lowercase(), "aédžaé "); - - // https://github.com/rust-lang/rust/issues/26035 - assert_eq!("ΑΣ".to_lowercase(), "ας"); - assert_eq!("Α'Σ".to_lowercase(), "α'ς"); - assert_eq!("Α''Σ".to_lowercase(), "α''ς"); - - assert_eq!("ΑΣ Α".to_lowercase(), "ας α"); - assert_eq!("Α'Σ Α".to_lowercase(), "α'ς α"); - assert_eq!("Α''Σ Α".to_lowercase(), "α''ς α"); - - assert_eq!("ΑΣ' Α".to_lowercase(), "ας' α"); - assert_eq!("ΑΣ'' Α".to_lowercase(), "ας'' α"); - - assert_eq!("Α'Σ' Α".to_lowercase(), "α'ς' α"); - assert_eq!("Α''Σ'' Α".to_lowercase(), "α''ς'' α"); - - assert_eq!("Α Σ".to_lowercase(), "α σ"); - assert_eq!("Α 'Σ".to_lowercase(), "α 'σ"); - assert_eq!("Α ''Σ".to_lowercase(), "α ''σ"); - - assert_eq!("Σ".to_lowercase(), "σ"); - assert_eq!("'Σ".to_lowercase(), "'σ"); - assert_eq!("''Σ".to_lowercase(), "''σ"); - - assert_eq!("ΑΣΑ".to_lowercase(), "ασα"); - assert_eq!("ΑΣ'Α".to_lowercase(), "ασ'α"); - assert_eq!("ΑΣ''Α".to_lowercase(), "ασ''α"); - - // https://github.com/rust-lang/rust/issues/124714 - assert_eq!("abcdefghijklmnopΣ".to_lowercase(), "abcdefghijklmnopς"); - - // a really long string that has it's lowercase form - // even longer. this tests that implementations don't assume - // an incorrect upper bound on allocations - let upper = str::repeat("İ", 512); - let lower = str::repeat("i̇", 512); - assert_eq!(upper.to_lowercase(), lower); - - // a really long ascii-only string. - // This test that the ascii hot-path - // functions correctly - let upper = str::repeat("A", 511); - let lower = str::repeat("a", 511); - assert_eq!(upper.to_lowercase(), lower); -} - -#[test] -fn to_uppercase() { - assert_eq!("".to_uppercase(), ""); - assert_eq!("aéDžßfiᾀ".to_uppercase(), "AÉDŽSSFIἈΙ"); -} - -#[test] -fn test_into_string() { - // The only way to acquire a Box in the first place is through a String, so just - // test that we can round-trip between Box and String. - let string = String::from("Some text goes here"); - assert_eq!(string.clone().into_boxed_str().into_string(), string); -} - -#[test] -fn test_box_slice_clone() { - let data = String::from("hello HELLO hello HELLO yes YES 5 中ä华!!!"); - let data2 = data.clone().into_boxed_str().clone().into_string(); - - assert_eq!(data, data2); -} - -#[test] -fn test_cow_from() { - let borrowed = "borrowed"; - let owned = String::from("owned"); - match (Cow::from(owned.clone()), Cow::from(borrowed)) { - (Cow::Owned(o), Cow::Borrowed(b)) => assert!(o == owned && b == borrowed), - _ => panic!("invalid `Cow::from`"), - } -} - -#[test] -fn test_repeat() { - assert_eq!("".repeat(3), ""); - assert_eq!("abc".repeat(0), ""); - assert_eq!("α".repeat(3), "ααα"); -} - -mod pattern { - use std::str::pattern::SearchStep::{self, Done, Match, Reject}; - use std::str::pattern::{Pattern, ReverseSearcher, Searcher}; - - macro_rules! make_test { - ($name:ident, $p:expr, $h:expr, [$($e:expr,)*]) => { - #[allow(unused_imports)] - mod $name { - use std::str::pattern::SearchStep::{Match, Reject}; - use super::{cmp_search_to_vec}; - #[test] - fn fwd() { - cmp_search_to_vec(false, $p, $h, vec![$($e),*]); - } - #[test] - fn bwd() { - cmp_search_to_vec(true, $p, $h, vec![$($e),*]); - } - } - } - } - - fn cmp_search_to_vec<'a>( - rev: bool, - pat: impl Pattern<'a, Searcher: ReverseSearcher<'a>>, - haystack: &'a str, - right: Vec, - ) { - let mut searcher = pat.into_searcher(haystack); - let mut v = vec![]; - loop { - match if !rev { searcher.next() } else { searcher.next_back() } { - Match(a, b) => v.push(Match(a, b)), - Reject(a, b) => v.push(Reject(a, b)), - Done => break, - } - } - if rev { - v.reverse(); - } - - let mut first_index = 0; - let mut err = None; - - for (i, e) in right.iter().enumerate() { - match *e { - Match(a, b) | Reject(a, b) if a <= b && a == first_index => { - first_index = b; - } - _ => { - err = Some(i); - break; - } - } - } - - if let Some(err) = err { - panic!("Input skipped range at {err}"); - } - - if first_index != haystack.len() { - panic!("Did not cover whole input"); - } - - assert_eq!(v, right); - } - - make_test!( - str_searcher_ascii_haystack, - "bb", - "abbcbbd", - [Reject(0, 1), Match(1, 3), Reject(3, 4), Match(4, 6), Reject(6, 7),] - ); - make_test!( - str_searcher_ascii_haystack_seq, - "bb", - "abbcbbbbd", - [Reject(0, 1), Match(1, 3), Reject(3, 4), Match(4, 6), Match(6, 8), Reject(8, 9),] - ); - make_test!( - str_searcher_empty_needle_ascii_haystack, - "", - "abbcbbd", - [ - Match(0, 0), - Reject(0, 1), - Match(1, 1), - Reject(1, 2), - Match(2, 2), - Reject(2, 3), - Match(3, 3), - Reject(3, 4), - Match(4, 4), - Reject(4, 5), - Match(5, 5), - Reject(5, 6), - Match(6, 6), - Reject(6, 7), - Match(7, 7), - ] - ); - make_test!( - str_searcher_multibyte_haystack, - " ", - "├──", - [Reject(0, 3), Reject(3, 6), Reject(6, 9),] - ); - make_test!( - str_searcher_empty_needle_multibyte_haystack, - "", - "├──", - [ - Match(0, 0), - Reject(0, 3), - Match(3, 3), - Reject(3, 6), - Match(6, 6), - Reject(6, 9), - Match(9, 9), - ] - ); - make_test!(str_searcher_empty_needle_empty_haystack, "", "", [Match(0, 0),]); - make_test!(str_searcher_nonempty_needle_empty_haystack, "├", "", []); - make_test!( - char_searcher_ascii_haystack, - 'b', - "abbcbbd", - [ - Reject(0, 1), - Match(1, 2), - Match(2, 3), - Reject(3, 4), - Match(4, 5), - Match(5, 6), - Reject(6, 7), - ] - ); - make_test!( - char_searcher_multibyte_haystack, - ' ', - "├──", - [Reject(0, 3), Reject(3, 6), Reject(6, 9),] - ); - make_test!( - char_searcher_short_haystack, - '\u{1F4A9}', - "* \t", - [Reject(0, 1), Reject(1, 2), Reject(2, 3),] - ); - - // See #85462 - #[test] - fn str_searcher_empty_needle_after_done() { - // Empty needle and haystack - { - let mut searcher = "".into_searcher(""); - - assert_eq!(searcher.next(), SearchStep::Match(0, 0)); - assert_eq!(searcher.next(), SearchStep::Done); - assert_eq!(searcher.next(), SearchStep::Done); - assert_eq!(searcher.next(), SearchStep::Done); - - let mut searcher = "".into_searcher(""); - - assert_eq!(searcher.next_back(), SearchStep::Match(0, 0)); - assert_eq!(searcher.next_back(), SearchStep::Done); - assert_eq!(searcher.next_back(), SearchStep::Done); - assert_eq!(searcher.next_back(), SearchStep::Done); - } - // Empty needle and non-empty haystack - { - let mut searcher = "".into_searcher("a"); - - assert_eq!(searcher.next(), SearchStep::Match(0, 0)); - assert_eq!(searcher.next(), SearchStep::Reject(0, 1)); - assert_eq!(searcher.next(), SearchStep::Match(1, 1)); - assert_eq!(searcher.next(), SearchStep::Done); - assert_eq!(searcher.next(), SearchStep::Done); - assert_eq!(searcher.next(), SearchStep::Done); - - let mut searcher = "".into_searcher("a"); - - assert_eq!(searcher.next_back(), SearchStep::Match(1, 1)); - assert_eq!(searcher.next_back(), SearchStep::Reject(0, 1)); - assert_eq!(searcher.next_back(), SearchStep::Match(0, 0)); - assert_eq!(searcher.next_back(), SearchStep::Done); - assert_eq!(searcher.next_back(), SearchStep::Done); - assert_eq!(searcher.next_back(), SearchStep::Done); - } - } -} - -macro_rules! generate_iterator_test { - { - $name:ident { - $( - ($($arg:expr),*) -> [$($t:tt)*]; - )* - } - with $fwd:expr, $bwd:expr; - } => { - #[test] - fn $name() { - $( - { - let res = vec![$($t)*]; - - let fwd_vec: Vec<_> = ($fwd)($($arg),*).collect(); - assert_eq!(fwd_vec, res); - - let mut bwd_vec: Vec<_> = ($bwd)($($arg),*).collect(); - bwd_vec.reverse(); - assert_eq!(bwd_vec, res); - } - )* - } - }; - { - $name:ident { - $( - ($($arg:expr),*) -> [$($t:tt)*]; - )* - } - with $fwd:expr; - } => { - #[test] - fn $name() { - $( - { - let res = vec![$($t)*]; - - let fwd_vec: Vec<_> = ($fwd)($($arg),*).collect(); - assert_eq!(fwd_vec, res); - } - )* - } - } -} - -generate_iterator_test! { - double_ended_split { - ("foo.bar.baz", '.') -> ["foo", "bar", "baz"]; - ("foo::bar::baz", "::") -> ["foo", "bar", "baz"]; - } - with str::split, str::rsplit; -} - -generate_iterator_test! { - double_ended_split_terminator { - ("foo;bar;baz;", ';') -> ["foo", "bar", "baz"]; - } - with str::split_terminator, str::rsplit_terminator; -} - -generate_iterator_test! { - double_ended_matches { - ("a1b2c3", char::is_numeric) -> ["1", "2", "3"]; - } - with str::matches, str::rmatches; -} - -generate_iterator_test! { - double_ended_match_indices { - ("a1b2c3", char::is_numeric) -> [(1, "1"), (3, "2"), (5, "3")]; - } - with str::match_indices, str::rmatch_indices; -} - -generate_iterator_test! { - not_double_ended_splitn { - ("foo::bar::baz", 2, "::") -> ["foo", "bar::baz"]; - } - with str::splitn; -} - -generate_iterator_test! { - not_double_ended_rsplitn { - ("foo::bar::baz", 2, "::") -> ["baz", "foo::bar"]; - } - with str::rsplitn; -} - -#[test] -fn different_str_pattern_forwarding_lifetimes() { - use std::str::pattern::Pattern; - - fn foo<'a, P>(p: P) - where - for<'b> &'b P: Pattern<'a>, - { - for _ in 0..3 { - "asdf".find(&p); - } - } - - foo::<&str>("x"); -} - -#[test] -fn test_str_multiline() { - let a: String = "this \ -is a test" - .to_string(); - let b: String = "this \ - is \ - another \ - test" - .to_string(); - assert_eq!(a, "this is a test".to_string()); - assert_eq!(b, "this is another test".to_string()); -} - -#[test] -fn test_str_escapes() { - let x = "\\\\\ - "; - assert_eq!(x, r"\\"); // extraneous whitespace stripped -} - -#[test] -fn const_str_ptr() { - const A: [u8; 2] = ['h' as u8, 'i' as u8]; - const B: &'static [u8; 2] = &A; - const C: *const u8 = B as *const u8; - - // Miri does not deduplicate consts (https://github.com/rust-lang/miri/issues/131) - #[cfg(not(miri))] - { - let foo = &A as *const u8; - assert_eq!(foo, C); - } - - unsafe { - assert_eq!(from_utf8_unchecked(&A), "hi"); - assert_eq!(*C, A[0]); - assert_eq!(*(&B[0] as *const u8), A[0]); - } -} - -#[test] -fn utf8() { - let yen: char = '¥'; // 0xa5 - let c_cedilla: char = 'ç'; // 0xe7 - let thorn: char = 'þ'; // 0xfe - let y_diaeresis: char = 'ÿ'; // 0xff - let pi: char = 'Π'; // 0x3a0 - - assert_eq!(yen as isize, 0xa5); - assert_eq!(c_cedilla as isize, 0xe7); - assert_eq!(thorn as isize, 0xfe); - assert_eq!(y_diaeresis as isize, 0xff); - assert_eq!(pi as isize, 0x3a0); - - assert_eq!(pi as isize, '\u{3a0}' as isize); - assert_eq!('\x0a' as isize, '\n' as isize); - - let bhutan: String = "འབྲུག་ཡུལ།".to_string(); - let japan: String = "日本".to_string(); - let uzbekistan: String = "Ўзбекистон".to_string(); - let austria: String = "Österreich".to_string(); - - let bhutan_e: String = - "\u{f60}\u{f56}\u{fb2}\u{f74}\u{f42}\u{f0b}\u{f61}\u{f74}\u{f63}\u{f0d}".to_string(); - let japan_e: String = "\u{65e5}\u{672c}".to_string(); - let uzbekistan_e: String = - "\u{40e}\u{437}\u{431}\u{435}\u{43a}\u{438}\u{441}\u{442}\u{43e}\u{43d}".to_string(); - let austria_e: String = "\u{d6}sterreich".to_string(); - - let oo: char = 'Ö'; - assert_eq!(oo as isize, 0xd6); - - fn check_str_eq(a: String, b: String) { - let mut i: isize = 0; - for ab in a.bytes() { - println!("{i}"); - println!("{ab}"); - let bb: u8 = b.as_bytes()[i as usize]; - println!("{bb}"); - assert_eq!(ab, bb); - i += 1; - } - } - - check_str_eq(bhutan, bhutan_e); - check_str_eq(japan, japan_e); - check_str_eq(uzbekistan, uzbekistan_e); - check_str_eq(austria, austria_e); -} - -#[test] -fn utf8_chars() { - // Chars of 1, 2, 3, and 4 bytes - let chs: Vec = vec!['e', 'é', '€', '\u{10000}']; - let s: String = chs.iter().cloned().collect(); - let schs: Vec = s.chars().collect(); - - assert_eq!(s.len(), 10); - assert_eq!(s.chars().count(), 4); - assert_eq!(schs.len(), 4); - assert_eq!(schs.iter().cloned().collect::(), s); - - assert!((from_utf8(s.as_bytes()).is_ok())); - // invalid prefix - assert!((!from_utf8(&[0x80]).is_ok())); - // invalid 2 byte prefix - assert!((!from_utf8(&[0xc0]).is_ok())); - assert!((!from_utf8(&[0xc0, 0x10]).is_ok())); - // invalid 3 byte prefix - assert!((!from_utf8(&[0xe0]).is_ok())); - assert!((!from_utf8(&[0xe0, 0x10]).is_ok())); - assert!((!from_utf8(&[0xe0, 0xff, 0x10]).is_ok())); - // invalid 4 byte prefix - assert!((!from_utf8(&[0xf0]).is_ok())); - assert!((!from_utf8(&[0xf0, 0x10]).is_ok())); - assert!((!from_utf8(&[0xf0, 0xff, 0x10]).is_ok())); - assert!((!from_utf8(&[0xf0, 0xff, 0xff, 0x10]).is_ok())); -} - -#[test] -fn utf8_char_counts() { - let strs = [("e", 1), ("é", 1), ("€", 1), ("\u{10000}", 1), ("eé€\u{10000}", 4)]; - let spread = if cfg!(miri) { 4 } else { 8 }; - let mut reps = [8, 64, 256, 512] - .iter() - .copied() - .flat_map(|n| n - spread..=n + spread) - .collect::>(); - if cfg!(not(miri)) { - reps.extend([1024, 1 << 16].iter().copied().flat_map(|n| n - spread..=n + spread)); - } - let counts = if cfg!(miri) { 0..1 } else { 0..8 }; - let padding = counts.map(|len| " ".repeat(len)).collect::>(); - - for repeat in reps { - for (tmpl_str, tmpl_char_count) in strs { - for pad_start in &padding { - for pad_end in &padding { - // Create a string with padding... - let with_padding = - format!("{}{}{}", pad_start, tmpl_str.repeat(repeat), pad_end); - // ...and then skip past that padding. This should ensure - // that we test several different alignments for both head - // and tail. - let si = pad_start.len(); - let ei = with_padding.len() - pad_end.len(); - let target = &with_padding[si..ei]; - - assert!(!target.starts_with(" ") && !target.ends_with(" ")); - let expected_count = tmpl_char_count * repeat; - assert_eq!( - expected_count, - target.chars().count(), - "wrong count for `{:?}.repeat({})` (padding: `{:?}`)", - tmpl_str, - repeat, - (pad_start.len(), pad_end.len()), - ); - } - } - } - } -} - -#[test] -fn floor_char_boundary() { - fn check_many(s: &str, arg: impl IntoIterator, ret: usize) { - for idx in arg { - assert_eq!( - s.floor_char_boundary(idx), - ret, - "{:?}.floor_char_boundary({:?}) != {:?}", - s, - idx, - ret - ); - } - } - - // edge case - check_many("", [0, 1, isize::MAX as usize, usize::MAX], 0); - - // basic check - check_many("x", [0], 0); - check_many("x", [1, isize::MAX as usize, usize::MAX], 1); - - // 1-byte chars - check_many("jp", [0], 0); - check_many("jp", [1], 1); - check_many("jp", 2..4, 2); - - // 2-byte chars - check_many("ĵƥ", 0..2, 0); - check_many("ĵƥ", 2..4, 2); - check_many("ĵƥ", 4..6, 4); - - // 3-byte chars - check_many("日本", 0..3, 0); - check_many("日本", 3..6, 3); - check_many("日本", 6..8, 6); - - // 4-byte chars - check_many("🇯🇵", 0..4, 0); - check_many("🇯🇵", 4..8, 4); - check_many("🇯🇵", 8..10, 8); -} - -#[test] -fn ceil_char_boundary() { - fn check_many(s: &str, arg: impl IntoIterator, ret: usize) { - for idx in arg { - assert_eq!( - s.ceil_char_boundary(idx), - ret, - "{:?}.ceil_char_boundary({:?}) != {:?}", - s, - idx, - ret - ); - } - } - - // edge case - check_many("", [0], 0); - - // basic check - check_many("x", [0], 0); - check_many("x", [1], 1); - - // 1-byte chars - check_many("jp", [0], 0); - check_many("jp", [1], 1); - check_many("jp", [2], 2); - - // 2-byte chars - check_many("ĵƥ", 0..=0, 0); - check_many("ĵƥ", 1..=2, 2); - check_many("ĵƥ", 3..=4, 4); - - // 3-byte chars - check_many("日本", 0..=0, 0); - check_many("日本", 1..=3, 3); - check_many("日本", 4..=6, 6); - - // 4-byte chars - check_many("🇯🇵", 0..=0, 0); - check_many("🇯🇵", 1..=4, 4); - check_many("🇯🇵", 5..=8, 8); - - // above len - check_many("hello", 5..=10, 5); -} diff --git a/library/alloc/tests/string.rs b/library/alloc/tests/string.rs deleted file mode 100644 index e20ceae87b0d5..0000000000000 --- a/library/alloc/tests/string.rs +++ /dev/null @@ -1,882 +0,0 @@ -use std::assert_matches::assert_matches; -use std::borrow::Cow; -use std::cell::Cell; -use std::collections::TryReserveErrorKind::*; -use std::ops::Bound; -use std::ops::Bound::*; -use std::ops::RangeBounds; -use std::panic; -use std::str; - -pub trait IntoCow<'a, B: ?Sized> -where - B: ToOwned, -{ - fn into_cow(self) -> Cow<'a, B>; -} - -impl<'a> IntoCow<'a, str> for String { - fn into_cow(self) -> Cow<'a, str> { - Cow::Owned(self) - } -} - -impl<'a> IntoCow<'a, str> for &'a str { - fn into_cow(self) -> Cow<'a, str> { - Cow::Borrowed(self) - } -} - -#[test] -fn test_from_str() { - let owned: Option = "string".parse().ok(); - assert_eq!(owned.as_ref().map(|s| &**s), Some("string")); -} - -#[test] -fn test_from_cow_str() { - assert_eq!(String::from(Cow::Borrowed("string")), "string"); - assert_eq!(String::from(Cow::Owned(String::from("string"))), "string"); -} - -#[test] -fn test_unsized_to_string() { - let s: &str = "abc"; - let _: String = (*s).to_string(); -} - -#[test] -fn test_from_utf8() { - let xs = b"hello".to_vec(); - assert_eq!(String::from_utf8(xs).unwrap(), String::from("hello")); - - let xs = "ศไทย中华Việt Nam".as_bytes().to_vec(); - assert_eq!(String::from_utf8(xs).unwrap(), String::from("ศไทย中华Việt Nam")); - - let xs = b"hello\xFF".to_vec(); - let err = String::from_utf8(xs).unwrap_err(); - assert_eq!(err.as_bytes(), b"hello\xff"); - let err_clone = err.clone(); - assert_eq!(err, err_clone); - assert_eq!(err.into_bytes(), b"hello\xff".to_vec()); - assert_eq!(err_clone.utf8_error().valid_up_to(), 5); -} - -#[test] -fn test_from_utf8_lossy() { - let xs = b"hello"; - let ys: Cow<'_, str> = "hello".into_cow(); - assert_eq!(String::from_utf8_lossy(xs), ys); - - let xs = "ศไทย中华Việt Nam".as_bytes(); - let ys: Cow<'_, str> = "ศไทย中华Việt Nam".into_cow(); - assert_eq!(String::from_utf8_lossy(xs), ys); - - let xs = b"Hello\xC2 There\xFF Goodbye"; - assert_eq!( - String::from_utf8_lossy(xs), - String::from("Hello\u{FFFD} There\u{FFFD} Goodbye").into_cow() - ); - - let xs = b"Hello\xC0\x80 There\xE6\x83 Goodbye"; - assert_eq!( - String::from_utf8_lossy(xs), - String::from("Hello\u{FFFD}\u{FFFD} There\u{FFFD} Goodbye").into_cow() - ); - - let xs = b"\xF5foo\xF5\x80bar"; - assert_eq!( - String::from_utf8_lossy(xs), - String::from("\u{FFFD}foo\u{FFFD}\u{FFFD}bar").into_cow() - ); - - let xs = b"\xF1foo\xF1\x80bar\xF1\x80\x80baz"; - assert_eq!( - String::from_utf8_lossy(xs), - String::from("\u{FFFD}foo\u{FFFD}bar\u{FFFD}baz").into_cow() - ); - - let xs = b"\xF4foo\xF4\x80bar\xF4\xBFbaz"; - assert_eq!( - String::from_utf8_lossy(xs), - String::from("\u{FFFD}foo\u{FFFD}bar\u{FFFD}\u{FFFD}baz").into_cow() - ); - - let xs = b"\xF0\x80\x80\x80foo\xF0\x90\x80\x80bar"; - assert_eq!( - String::from_utf8_lossy(xs), - String::from("\u{FFFD}\u{FFFD}\u{FFFD}\u{FFFD}foo\u{10000}bar").into_cow() - ); - - // surrogates - let xs = b"\xED\xA0\x80foo\xED\xBF\xBFbar"; - assert_eq!( - String::from_utf8_lossy(xs), - String::from("\u{FFFD}\u{FFFD}\u{FFFD}foo\u{FFFD}\u{FFFD}\u{FFFD}bar").into_cow() - ); -} - -#[test] -fn test_from_utf16() { - let pairs = [ - ( - String::from("𐍅𐌿𐌻𐍆𐌹𐌻𐌰\n"), - vec![ - 0xd800, 0xdf45, 0xd800, 0xdf3f, 0xd800, 0xdf3b, 0xd800, 0xdf46, 0xd800, 0xdf39, - 0xd800, 0xdf3b, 0xd800, 0xdf30, 0x000a, - ], - ), - ( - String::from("𐐒𐑉𐐮𐑀𐐲𐑋 𐐏𐐲𐑍\n"), - vec![ - 0xd801, 0xdc12, 0xd801, 0xdc49, 0xd801, 0xdc2e, 0xd801, 0xdc40, 0xd801, 0xdc32, - 0xd801, 0xdc4b, 0x0020, 0xd801, 0xdc0f, 0xd801, 0xdc32, 0xd801, 0xdc4d, 0x000a, - ], - ), - ( - String::from("𐌀𐌖𐌋𐌄𐌑𐌉·𐌌𐌄𐌕𐌄𐌋𐌉𐌑\n"), - vec![ - 0xd800, 0xdf00, 0xd800, 0xdf16, 0xd800, 0xdf0b, 0xd800, 0xdf04, 0xd800, 0xdf11, - 0xd800, 0xdf09, 0x00b7, 0xd800, 0xdf0c, 0xd800, 0xdf04, 0xd800, 0xdf15, 0xd800, - 0xdf04, 0xd800, 0xdf0b, 0xd800, 0xdf09, 0xd800, 0xdf11, 0x000a, - ], - ), - ( - String::from("𐒋𐒘𐒈𐒑𐒛𐒒 𐒕𐒓 𐒈𐒚𐒍 𐒏𐒜𐒒𐒖𐒆 𐒕𐒆\n"), - vec![ - 0xd801, 0xdc8b, 0xd801, 0xdc98, 0xd801, 0xdc88, 0xd801, 0xdc91, 0xd801, 0xdc9b, - 0xd801, 0xdc92, 0x0020, 0xd801, 0xdc95, 0xd801, 0xdc93, 0x0020, 0xd801, 0xdc88, - 0xd801, 0xdc9a, 0xd801, 0xdc8d, 0x0020, 0xd801, 0xdc8f, 0xd801, 0xdc9c, 0xd801, - 0xdc92, 0xd801, 0xdc96, 0xd801, 0xdc86, 0x0020, 0xd801, 0xdc95, 0xd801, 0xdc86, - 0x000a, - ], - ), - // Issue #12318, even-numbered non-BMP planes - (String::from("\u{20000}"), vec![0xD840, 0xDC00]), - ]; - - for p in &pairs { - let (s, u) = (*p).clone(); - let s_as_utf16 = s.encode_utf16().collect::>(); - let u_as_string = String::from_utf16(&u).unwrap(); - - assert!(core::char::decode_utf16(u.iter().cloned()).all(|r| r.is_ok())); - assert_eq!(s_as_utf16, u); - - assert_eq!(u_as_string, s); - assert_eq!(String::from_utf16_lossy(&u), s); - - assert_eq!(String::from_utf16(&s_as_utf16).unwrap(), s); - assert_eq!(u_as_string.encode_utf16().collect::>(), u); - } -} - -#[test] -fn test_utf16_invalid() { - // completely positive cases tested above. - // lead + eof - assert!(String::from_utf16(&[0xD800]).is_err()); - // lead + lead - assert!(String::from_utf16(&[0xD800, 0xD800]).is_err()); - - // isolated trail - assert!(String::from_utf16(&[0x0061, 0xDC00]).is_err()); - - // general - assert!(String::from_utf16(&[0xD800, 0xd801, 0xdc8b, 0xD800]).is_err()); -} - -#[test] -fn test_from_utf16_lossy() { - // completely positive cases tested above. - // lead + eof - assert_eq!(String::from_utf16_lossy(&[0xD800]), String::from("\u{FFFD}")); - // lead + lead - assert_eq!(String::from_utf16_lossy(&[0xD800, 0xD800]), String::from("\u{FFFD}\u{FFFD}")); - - // isolated trail - assert_eq!(String::from_utf16_lossy(&[0x0061, 0xDC00]), String::from("a\u{FFFD}")); - - // general - assert_eq!( - String::from_utf16_lossy(&[0xD800, 0xd801, 0xdc8b, 0xD800]), - String::from("\u{FFFD}𐒋\u{FFFD}") - ); -} - -#[test] -fn test_push_bytes() { - let mut s = String::from("ABC"); - unsafe { - let mv = s.as_mut_vec(); - mv.extend_from_slice(&[b'D']); - } - assert_eq!(s, "ABCD"); -} - -#[test] -fn test_push_str() { - let mut s = String::new(); - s.push_str(""); - assert_eq!(&s[0..], ""); - s.push_str("abc"); - assert_eq!(&s[0..], "abc"); - s.push_str("ประเทศไทย中华Việt Nam"); - assert_eq!(&s[0..], "abcประเทศไทย中华Việt Nam"); -} - -#[test] -fn test_add_assign() { - let mut s = String::new(); - s += ""; - assert_eq!(s.as_str(), ""); - s += "abc"; - assert_eq!(s.as_str(), "abc"); - s += "ประเทศไทย中华Việt Nam"; - assert_eq!(s.as_str(), "abcประเทศไทย中华Việt Nam"); -} - -#[test] -fn test_push() { - let mut data = String::from("ประเทศไทย中"); - data.push('华'); - data.push('b'); // 1 byte - data.push('¢'); // 2 byte - data.push('€'); // 3 byte - data.push('𤭢'); // 4 byte - assert_eq!(data, "ประเทศไทย中华b¢€𤭢"); -} - -#[test] -fn test_pop() { - let mut data = String::from("ประเทศไทย中华b¢€𤭢"); - assert_eq!(data.pop().unwrap(), '𤭢'); // 4 bytes - assert_eq!(data.pop().unwrap(), '€'); // 3 bytes - assert_eq!(data.pop().unwrap(), '¢'); // 2 bytes - assert_eq!(data.pop().unwrap(), 'b'); // 1 bytes - assert_eq!(data.pop().unwrap(), '华'); - assert_eq!(data, "ประเทศไทย中"); -} - -#[test] -fn test_split_off_empty() { - let orig = "Hello, world!"; - let mut split = String::from(orig); - let empty: String = split.split_off(orig.len()); - assert!(empty.is_empty()); -} - -#[test] -#[should_panic] -fn test_split_off_past_end() { - let orig = "Hello, world!"; - let mut split = String::from(orig); - let _ = split.split_off(orig.len() + 1); -} - -#[test] -#[should_panic] -fn test_split_off_mid_char() { - let mut shan = String::from("山"); - let _broken_mountain = shan.split_off(1); -} - -#[test] -fn test_split_off_ascii() { - let mut ab = String::from("ABCD"); - let orig_capacity = ab.capacity(); - let cd = ab.split_off(2); - assert_eq!(ab, "AB"); - assert_eq!(cd, "CD"); - assert_eq!(ab.capacity(), orig_capacity); -} - -#[test] -fn test_split_off_unicode() { - let mut nihon = String::from("日本語"); - let orig_capacity = nihon.capacity(); - let go = nihon.split_off("日本".len()); - assert_eq!(nihon, "日本"); - assert_eq!(go, "語"); - assert_eq!(nihon.capacity(), orig_capacity); -} - -#[test] -fn test_str_truncate() { - let mut s = String::from("12345"); - s.truncate(5); - assert_eq!(s, "12345"); - s.truncate(3); - assert_eq!(s, "123"); - s.truncate(0); - assert_eq!(s, ""); - - let mut s = String::from("12345"); - let p = s.as_ptr(); - s.truncate(3); - s.push_str("6"); - let p_ = s.as_ptr(); - assert_eq!(p_, p); -} - -#[test] -fn test_str_truncate_invalid_len() { - let mut s = String::from("12345"); - s.truncate(6); - assert_eq!(s, "12345"); -} - -#[test] -#[should_panic] -fn test_str_truncate_split_codepoint() { - let mut s = String::from("\u{FC}"); // ü - s.truncate(1); -} - -#[test] -fn test_str_clear() { - let mut s = String::from("12345"); - s.clear(); - assert_eq!(s.len(), 0); - assert_eq!(s, ""); -} - -#[test] -fn test_str_add() { - let a = String::from("12345"); - let b = a + "2"; - let b = b + "2"; - assert_eq!(b.len(), 7); - assert_eq!(b, "1234522"); -} - -#[test] -fn remove() { - let mut s = "ศไทย中华Việt Nam; foobar".to_string(); - assert_eq!(s.remove(0), 'ศ'); - assert_eq!(s.len(), 33); - assert_eq!(s, "ไทย中华Việt Nam; foobar"); - assert_eq!(s.remove(17), 'ệ'); - assert_eq!(s, "ไทย中华Vit Nam; foobar"); -} - -#[test] -#[should_panic] -fn remove_bad() { - "ศ".to_string().remove(1); -} - -#[test] -fn test_remove_matches() { - // test_single_pattern_occurrence - let mut s = "abc".to_string(); - s.remove_matches('b'); - assert_eq!(s, "ac"); - // repeat_test_single_pattern_occurrence - s.remove_matches('b'); - assert_eq!(s, "ac"); - - // test_single_character_pattern - let mut s = "abcb".to_string(); - s.remove_matches('b'); - assert_eq!(s, "ac"); - - // test_pattern_with_special_characters - let mut s = "ศไทย中华Việt Nam; foobarศ".to_string(); - s.remove_matches('ศ'); - assert_eq!(s, "ไทย中华Việt Nam; foobar"); - - // test_pattern_empty_text_and_pattern - let mut s = "".to_string(); - s.remove_matches(""); - assert_eq!(s, ""); - - // test_pattern_empty_text - let mut s = "".to_string(); - s.remove_matches("something"); - assert_eq!(s, ""); - - // test_empty_pattern - let mut s = "Testing with empty pattern.".to_string(); - s.remove_matches(""); - assert_eq!(s, "Testing with empty pattern."); - - // test_multiple_consecutive_patterns_1 - let mut s = "aaaaa".to_string(); - s.remove_matches('a'); - assert_eq!(s, ""); - - // test_multiple_consecutive_patterns_2 - let mut s = "Hello **world****today!**".to_string(); - s.remove_matches("**"); - assert_eq!(s, "Hello worldtoday!"); - - // test_case_insensitive_pattern - let mut s = "CASE ** SeNsItIvE ** PaTtErN.".to_string(); - s.remove_matches("sEnSiTiVe"); - assert_eq!(s, "CASE ** SeNsItIvE ** PaTtErN."); - - // test_pattern_with_digits - let mut s = "123 ** 456 ** 789".to_string(); - s.remove_matches("**"); - assert_eq!(s, "123 456 789"); - - // test_pattern_occurs_after_empty_string - let mut s = "abc X defXghi".to_string(); - s.remove_matches("X"); - assert_eq!(s, "abc defghi"); - - // test_large_pattern - let mut s = "aaaXbbbXcccXdddXeee".to_string(); - s.remove_matches("X"); - assert_eq!(s, "aaabbbcccdddeee"); - - // test_pattern_at_multiple_positions - let mut s = "Pattern ** found ** multiple ** times ** in ** text.".to_string(); - s.remove_matches("**"); - assert_eq!(s, "Pattern found multiple times in text."); -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_retain() { - let mut s = String::from("α_β_γ"); - - s.retain(|_| true); - assert_eq!(s, "α_β_γ"); - - s.retain(|c| c != '_'); - assert_eq!(s, "αβγ"); - - s.retain(|c| c != 'β'); - assert_eq!(s, "αγ"); - - s.retain(|c| c == 'α'); - assert_eq!(s, "α"); - - s.retain(|_| false); - assert_eq!(s, ""); - - let mut s = String::from("0è0"); - let _ = panic::catch_unwind(panic::AssertUnwindSafe(|| { - let mut count = 0; - s.retain(|_| { - count += 1; - match count { - 1 => false, - 2 => true, - _ => panic!(), - } - }); - })); - assert!(std::str::from_utf8(s.as_bytes()).is_ok()); -} - -#[test] -fn insert() { - let mut s = "foobar".to_string(); - s.insert(0, 'ệ'); - assert_eq!(s, "ệfoobar"); - s.insert(6, 'ย'); - assert_eq!(s, "ệfooยbar"); -} - -#[test] -#[should_panic] -fn insert_bad1() { - "".to_string().insert(1, 't'); -} -#[test] -#[should_panic] -fn insert_bad2() { - "ệ".to_string().insert(1, 't'); -} - -#[test] -fn test_slicing() { - let s = "foobar".to_string(); - assert_eq!("foobar", &s[..]); - assert_eq!("foo", &s[..3]); - assert_eq!("bar", &s[3..]); - assert_eq!("oob", &s[1..4]); -} - -#[test] -fn test_simple_types() { - assert_eq!(1.to_string(), "1"); - assert_eq!((-1).to_string(), "-1"); - assert_eq!(200.to_string(), "200"); - assert_eq!(2.to_string(), "2"); - assert_eq!(true.to_string(), "true"); - assert_eq!(false.to_string(), "false"); - assert_eq!(("hi".to_string()).to_string(), "hi"); -} - -#[test] -fn test_vectors() { - let x: Vec = vec![]; - assert_eq!(format!("{x:?}"), "[]"); - assert_eq!(format!("{:?}", vec![1]), "[1]"); - assert_eq!(format!("{:?}", vec![1, 2, 3]), "[1, 2, 3]"); - assert!(format!("{:?}", vec![vec![], vec![1], vec![1, 1]]) == "[[], [1], [1, 1]]"); -} - -#[test] -fn test_from_iterator() { - let s = "ศไทย中华Việt Nam".to_string(); - let t = "ศไทย中华"; - let u = "Việt Nam"; - - let a: String = s.chars().collect(); - assert_eq!(s, a); - - let mut b = t.to_string(); - b.extend(u.chars()); - assert_eq!(s, b); - - let c: String = [t, u].into_iter().collect(); - assert_eq!(s, c); - - let mut d = t.to_string(); - d.extend(vec![u]); - assert_eq!(s, d); -} - -#[test] -fn test_drain() { - let mut s = String::from("αβγ"); - assert_eq!(s.drain(2..4).collect::(), "β"); - assert_eq!(s, "αγ"); - - let mut t = String::from("abcd"); - t.drain(..0); - assert_eq!(t, "abcd"); - t.drain(..1); - assert_eq!(t, "bcd"); - t.drain(3..); - assert_eq!(t, "bcd"); - t.drain(..); - assert_eq!(t, ""); -} - -#[test] -#[should_panic] -fn test_drain_start_overflow() { - let mut s = String::from("abc"); - s.drain((Excluded(usize::MAX), Included(0))); -} - -#[test] -#[should_panic] -fn test_drain_end_overflow() { - let mut s = String::from("abc"); - s.drain((Included(0), Included(usize::MAX))); -} - -#[test] -fn test_replace_range() { - let mut s = "Hello, world!".to_owned(); - s.replace_range(7..12, "世界"); - assert_eq!(s, "Hello, 世界!"); -} - -#[test] -#[should_panic] -fn test_replace_range_char_boundary() { - let mut s = "Hello, 世界!".to_owned(); - s.replace_range(..8, ""); -} - -#[test] -fn test_replace_range_inclusive_range() { - let mut v = String::from("12345"); - v.replace_range(2..=3, "789"); - assert_eq!(v, "127895"); - v.replace_range(1..=2, "A"); - assert_eq!(v, "1A895"); -} - -#[test] -#[should_panic] -fn test_replace_range_out_of_bounds() { - let mut s = String::from("12345"); - s.replace_range(5..6, "789"); -} - -#[test] -#[should_panic] -fn test_replace_range_inclusive_out_of_bounds() { - let mut s = String::from("12345"); - s.replace_range(5..=5, "789"); -} - -#[test] -#[should_panic] -fn test_replace_range_start_overflow() { - let mut s = String::from("123"); - s.replace_range((Excluded(usize::MAX), Included(0)), ""); -} - -#[test] -#[should_panic] -fn test_replace_range_end_overflow() { - let mut s = String::from("456"); - s.replace_range((Included(0), Included(usize::MAX)), ""); -} - -#[test] -fn test_replace_range_empty() { - let mut s = String::from("12345"); - s.replace_range(1..2, ""); - assert_eq!(s, "1345"); -} - -#[test] -fn test_replace_range_unbounded() { - let mut s = String::from("12345"); - s.replace_range(.., ""); - assert_eq!(s, ""); -} - -#[test] -fn test_replace_range_evil_start_bound() { - struct EvilRange(Cell); - - impl RangeBounds for EvilRange { - fn start_bound(&self) -> Bound<&usize> { - Bound::Included(if self.0.get() { - &1 - } else { - self.0.set(true); - &0 - }) - } - fn end_bound(&self) -> Bound<&usize> { - Bound::Unbounded - } - } - - let mut s = String::from("🦀"); - s.replace_range(EvilRange(Cell::new(false)), ""); - assert_eq!(Ok(""), str::from_utf8(s.as_bytes())); -} - -#[test] -fn test_replace_range_evil_end_bound() { - struct EvilRange(Cell); - - impl RangeBounds for EvilRange { - fn start_bound(&self) -> Bound<&usize> { - Bound::Included(&0) - } - fn end_bound(&self) -> Bound<&usize> { - Bound::Excluded(if self.0.get() { - &3 - } else { - self.0.set(true); - &4 - }) - } - } - - let mut s = String::from("🦀"); - s.replace_range(EvilRange(Cell::new(false)), ""); - assert_eq!(Ok(""), str::from_utf8(s.as_bytes())); -} - -#[test] -fn test_extend_ref() { - let mut a = "foo".to_string(); - a.extend(&['b', 'a', 'r']); - - assert_eq!(&a, "foobar"); -} - -#[test] -fn test_into_boxed_str() { - let xs = String::from("hello my name is bob"); - let ys = xs.into_boxed_str(); - assert_eq!(&*ys, "hello my name is bob"); -} - -#[test] -fn test_reserve_exact() { - // This is all the same as test_reserve - - let mut s = String::new(); - assert_eq!(s.capacity(), 0); - - s.reserve_exact(2); - assert!(s.capacity() >= 2); - - for _i in 0..16 { - s.push('0'); - } - - assert!(s.capacity() >= 16); - s.reserve_exact(16); - assert!(s.capacity() >= 32); - - s.push('0'); - - s.reserve_exact(16); - assert!(s.capacity() >= 33) -} - -#[test] -#[cfg_attr(miri, ignore)] // Miri does not support signalling OOM -#[cfg_attr(target_os = "android", ignore)] // Android used in CI has a broken dlmalloc -fn test_try_with_capacity() { - let string = String::try_with_capacity(1000).unwrap(); - assert_eq!(0, string.len()); - assert!(string.capacity() >= 1000 && string.capacity() <= isize::MAX as usize); - - assert!(String::try_with_capacity(usize::MAX).is_err()); -} - -#[test] -#[cfg_attr(miri, ignore)] // Miri does not support signalling OOM -#[cfg_attr(target_os = "android", ignore)] // Android used in CI has a broken dlmalloc -fn test_try_reserve() { - // These are the interesting cases: - // * exactly isize::MAX should never trigger a CapacityOverflow (can be OOM) - // * > isize::MAX should always fail - // * On 16/32-bit should CapacityOverflow - // * On 64-bit should OOM - // * overflow may trigger when adding `len` to `cap` (in number of elements) - // * overflow may trigger when multiplying `new_cap` by size_of:: (to get bytes) - - const MAX_CAP: usize = isize::MAX as usize; - const MAX_USIZE: usize = usize::MAX; - - { - // Note: basic stuff is checked by test_reserve - let mut empty_string: String = String::new(); - - // Check isize::MAX doesn't count as an overflow - if let Err(CapacityOverflow) = empty_string.try_reserve(MAX_CAP).map_err(|e| e.kind()) { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - // Play it again, frank! (just to be sure) - if let Err(CapacityOverflow) = empty_string.try_reserve(MAX_CAP).map_err(|e| e.kind()) { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - - // Check isize::MAX + 1 does count as overflow - assert_matches!( - empty_string.try_reserve(MAX_CAP + 1).map_err(|e| e.kind()), - Err(CapacityOverflow), - "isize::MAX + 1 should trigger an overflow!" - ); - - // Check usize::MAX does count as overflow - assert_matches!( - empty_string.try_reserve(MAX_USIZE).map_err(|e| e.kind()), - Err(CapacityOverflow), - "usize::MAX should trigger an overflow!" - ); - } - - { - // Same basic idea, but with non-zero len - let mut ten_bytes: String = String::from("0123456789"); - - if let Err(CapacityOverflow) = ten_bytes.try_reserve(MAX_CAP - 10).map_err(|e| e.kind()) { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - if let Err(CapacityOverflow) = ten_bytes.try_reserve(MAX_CAP - 10).map_err(|e| e.kind()) { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - - assert_matches!( - ten_bytes.try_reserve(MAX_CAP - 9).map_err(|e| e.kind()), - Err(CapacityOverflow), - "isize::MAX + 1 should trigger an overflow!" - ); - - // Should always overflow in the add-to-len - assert_matches!( - ten_bytes.try_reserve(MAX_USIZE).map_err(|e| e.kind()), - Err(CapacityOverflow), - "usize::MAX should trigger an overflow!" - ); - } -} - -#[test] -#[cfg_attr(miri, ignore)] // Miri does not support signalling OOM -#[cfg_attr(target_os = "android", ignore)] // Android used in CI has a broken dlmalloc -fn test_try_reserve_exact() { - // This is exactly the same as test_try_reserve with the method changed. - // See that test for comments. - - const MAX_CAP: usize = isize::MAX as usize; - const MAX_USIZE: usize = usize::MAX; - - { - let mut empty_string: String = String::new(); - - if let Err(CapacityOverflow) = empty_string.try_reserve_exact(MAX_CAP).map_err(|e| e.kind()) - { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - if let Err(CapacityOverflow) = empty_string.try_reserve_exact(MAX_CAP).map_err(|e| e.kind()) - { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - - assert_matches!( - empty_string.try_reserve_exact(MAX_CAP + 1).map_err(|e| e.kind()), - Err(CapacityOverflow), - "isize::MAX + 1 should trigger an overflow!" - ); - - assert_matches!( - empty_string.try_reserve_exact(MAX_USIZE).map_err(|e| e.kind()), - Err(CapacityOverflow), - "usize::MAX should trigger an overflow!" - ); - } - - { - let mut ten_bytes: String = String::from("0123456789"); - - if let Err(CapacityOverflow) = - ten_bytes.try_reserve_exact(MAX_CAP - 10).map_err(|e| e.kind()) - { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - if let Err(CapacityOverflow) = - ten_bytes.try_reserve_exact(MAX_CAP - 10).map_err(|e| e.kind()) - { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - - assert_matches!( - ten_bytes.try_reserve_exact(MAX_CAP - 9).map_err(|e| e.kind()), - Err(CapacityOverflow), - "isize::MAX + 1 should trigger an overflow!" - ); - - assert_matches!( - ten_bytes.try_reserve_exact(MAX_USIZE).map_err(|e| e.kind()), - Err(CapacityOverflow), - "usize::MAX should trigger an overflow!" - ); - } -} - -#[test] -fn test_from_char() { - assert_eq!(String::from('a'), 'a'.to_string()); - let s: String = 'x'.into(); - assert_eq!(s, 'x'.to_string()); -} - -#[test] -fn test_str_concat() { - let a: String = "hello".to_string(); - let b: String = "world".to_string(); - let s: String = format!("{a}{b}"); - assert_eq!(s.as_bytes()[9], 'd' as u8); -} diff --git a/library/alloc/tests/task.rs b/library/alloc/tests/task.rs deleted file mode 100644 index 034039a1eae9d..0000000000000 --- a/library/alloc/tests/task.rs +++ /dev/null @@ -1,36 +0,0 @@ -use alloc::rc::Rc; -use alloc::sync::Arc; -use alloc::task::{LocalWake, Wake}; -use core::task::{LocalWaker, Waker}; - -#[test] -#[cfg_attr(miri, should_panic)] // `will_wake` doesn't guarantee that this test will work, and indeed on Miri it fails -fn test_waker_will_wake_clone() { - struct NoopWaker; - - impl Wake for NoopWaker { - fn wake(self: Arc) {} - } - - let waker = Waker::from(Arc::new(NoopWaker)); - let clone = waker.clone(); - - assert!(waker.will_wake(&clone)); - assert!(clone.will_wake(&waker)); -} - -#[test] -#[cfg_attr(miri, should_panic)] // `will_wake` doesn't guarantee that this test will work, and indeed on Miri it fails -fn test_local_waker_will_wake_clone() { - struct NoopWaker; - - impl LocalWake for NoopWaker { - fn wake(self: Rc) {} - } - - let waker = LocalWaker::from(Rc::new(NoopWaker)); - let clone = waker.clone(); - - assert!(waker.will_wake(&clone)); - assert!(clone.will_wake(&waker)); -} diff --git a/library/alloc/tests/thin_box.rs b/library/alloc/tests/thin_box.rs deleted file mode 100644 index e008b0cc35718..0000000000000 --- a/library/alloc/tests/thin_box.rs +++ /dev/null @@ -1,262 +0,0 @@ -use core::fmt::Debug; -use core::mem::size_of; -use std::boxed::ThinBox; - -#[test] -fn want_niche_optimization() { - fn uses_niche() -> bool { - size_of::<*const ()>() == size_of::>>() - } - - trait Tr {} - assert!(uses_niche::()); - assert!(uses_niche::<[i32]>()); - assert!(uses_niche::()); -} - -#[test] -fn want_thin() { - fn is_thin() -> bool { - size_of::<*const ()>() == size_of::>() - } - - trait Tr {} - assert!(is_thin::()); - assert!(is_thin::<[i32]>()); - assert!(is_thin::()); -} - -#[allow(dead_code)] -fn assert_covariance() { - fn thin_box<'new>(b: ThinBox<[&'static str]>) -> ThinBox<[&'new str]> { - b - } -} - -#[track_caller] -fn verify_aligned(ptr: *const T) { - // Use `black_box` to attempt to obscure the fact that we're calling this - // function on pointers that come from box/references, which the compiler - // would otherwise realize is impossible (because it would mean we've - // already executed UB). - // - // That is, we'd *like* it to be possible for the asserts in this function - // to detect brokenness in the ThinBox impl. - // - // It would probably be better if we instead had these as debug_asserts - // inside `ThinBox`, prior to the point where we do the UB. Anyway, in - // practice these checks are mostly just smoke-detectors for an extremely - // broken `ThinBox` impl, since it's an extremely subtle piece of code. - let ptr = core::hint::black_box(ptr); - assert!( - ptr.is_aligned() && !ptr.is_null(), - "misaligned ThinBox data; valid pointers to `{ty}` should be aligned to {align}: {ptr:p}", - ty = core::any::type_name::(), - align = core::mem::align_of::(), - ); -} - -#[track_caller] -fn check_thin_sized(make: impl FnOnce() -> T) { - let value = make(); - let boxed = ThinBox::new(value.clone()); - let val = &*boxed; - verify_aligned(val as *const T); - assert_eq!(val, &value); -} - -#[track_caller] -fn check_thin_dyn(make: impl FnOnce() -> T) { - let value = make(); - let wanted_debug = format!("{value:?}"); - let boxed: ThinBox = ThinBox::new_unsize(value.clone()); - let val = &*boxed; - // wide reference -> wide pointer -> thin pointer - verify_aligned(val as *const dyn Debug as *const T); - let got_debug = format!("{val:?}"); - assert_eq!(wanted_debug, got_debug); -} - -macro_rules! define_test { - ( - @test_name: $testname:ident; - - $(#[$m:meta])* - struct $Type:ident($inner:ty); - - $($test_stmts:tt)* - ) => { - #[test] - fn $testname() { - use core::sync::atomic::{AtomicIsize, Ordering}; - // Define the type, and implement new/clone/drop in such a way that - // the number of live instances will be counted. - $(#[$m])* - #[derive(Debug, PartialEq)] - struct $Type { - _priv: $inner, - } - - impl Clone for $Type { - fn clone(&self) -> Self { - verify_aligned(self); - Self::new(self._priv.clone()) - } - } - - impl Drop for $Type { - fn drop(&mut self) { - verify_aligned(self); - Self::modify_live(-1); - } - } - - impl $Type { - fn new(i: $inner) -> Self { - Self::modify_live(1); - Self { _priv: i } - } - - fn modify_live(n: isize) -> isize { - static COUNTER: AtomicIsize = AtomicIsize::new(0); - COUNTER.fetch_add(n, Ordering::Relaxed) + n - } - - fn live_objects() -> isize { - Self::modify_live(0) - } - } - // Run the test statements - let _: () = { $($test_stmts)* }; - // Check that we didn't leak anything, or call drop too many times. - assert_eq!( - $Type::live_objects(), 0, - "Wrong number of drops of {}, `initializations - drops` should be 0.", - stringify!($Type), - ); - } - }; -} - -define_test! { - @test_name: align1zst; - struct Align1Zst(()); - - check_thin_sized(|| Align1Zst::new(())); - check_thin_dyn(|| Align1Zst::new(())); -} - -define_test! { - @test_name: align1small; - struct Align1Small(u8); - - check_thin_sized(|| Align1Small::new(50)); - check_thin_dyn(|| Align1Small::new(50)); -} - -define_test! { - @test_name: align1_size_not_pow2; - struct Align64NotPow2Size([u8; 79]); - - check_thin_sized(|| Align64NotPow2Size::new([100; 79])); - check_thin_dyn(|| Align64NotPow2Size::new([100; 79])); -} - -define_test! { - @test_name: align1big; - struct Align1Big([u8; 256]); - - check_thin_sized(|| Align1Big::new([5u8; 256])); - check_thin_dyn(|| Align1Big::new([5u8; 256])); -} - -// Note: `#[repr(align(2))]` is worth testing because -// - can have pointers which are misaligned, unlike align(1) -// - is still expected to have an alignment less than the alignment of a vtable. -define_test! { - @test_name: align2zst; - #[repr(align(2))] - struct Align2Zst(()); - - check_thin_sized(|| Align2Zst::new(())); - check_thin_dyn(|| Align2Zst::new(())); -} - -define_test! { - @test_name: align2small; - #[repr(align(2))] - struct Align2Small(u8); - - check_thin_sized(|| Align2Small::new(60)); - check_thin_dyn(|| Align2Small::new(60)); -} - -define_test! { - @test_name: align2full; - #[repr(align(2))] - struct Align2Full([u8; 2]); - check_thin_sized(|| Align2Full::new([3u8; 2])); - check_thin_dyn(|| Align2Full::new([3u8; 2])); -} - -define_test! { - @test_name: align2_size_not_pow2; - #[repr(align(2))] - struct Align2NotPower2Size([u8; 6]); - - check_thin_sized(|| Align2NotPower2Size::new([3; 6])); - check_thin_dyn(|| Align2NotPower2Size::new([3; 6])); -} - -define_test! { - @test_name: align2big; - #[repr(align(2))] - struct Align2Big([u8; 256]); - - check_thin_sized(|| Align2Big::new([5u8; 256])); - check_thin_dyn(|| Align2Big::new([5u8; 256])); -} - -define_test! { - @test_name: align64zst; - #[repr(align(64))] - struct Align64Zst(()); - - check_thin_sized(|| Align64Zst::new(())); - check_thin_dyn(|| Align64Zst::new(())); -} - -define_test! { - @test_name: align64small; - #[repr(align(64))] - struct Align64Small(u8); - - check_thin_sized(|| Align64Small::new(50)); - check_thin_dyn(|| Align64Small::new(50)); -} - -define_test! { - @test_name: align64med; - #[repr(align(64))] - struct Align64Med([u8; 64]); - check_thin_sized(|| Align64Med::new([10; 64])); - check_thin_dyn(|| Align64Med::new([10; 64])); -} - -define_test! { - @test_name: align64_size_not_pow2; - #[repr(align(64))] - struct Align64NotPow2Size([u8; 192]); - - check_thin_sized(|| Align64NotPow2Size::new([10; 192])); - check_thin_dyn(|| Align64NotPow2Size::new([10; 192])); -} - -define_test! { - @test_name: align64big; - #[repr(align(64))] - struct Align64Big([u8; 256]); - - check_thin_sized(|| Align64Big::new([10; 256])); - check_thin_dyn(|| Align64Big::new([10; 256])); -} diff --git a/library/alloc/tests/vec.rs b/library/alloc/tests/vec.rs deleted file mode 100644 index 71d79893e01d7..0000000000000 --- a/library/alloc/tests/vec.rs +++ /dev/null @@ -1,2716 +0,0 @@ -use core::alloc::{Allocator, Layout}; -use core::num::NonZero; -use core::ptr::NonNull; -use core::{assert_eq, assert_ne}; -use std::alloc::System; -use std::assert_matches::assert_matches; -use std::borrow::Cow; -use std::cell::Cell; -use std::collections::TryReserveErrorKind::*; -use std::fmt::Debug; -use std::hint; -use std::iter::InPlaceIterable; -use std::mem; -use std::mem::{size_of, swap}; -use std::ops::Bound::*; -use std::panic::{catch_unwind, AssertUnwindSafe}; -use std::rc::Rc; -use std::sync::atomic::{AtomicU32, Ordering}; -use std::vec::{Drain, IntoIter}; - -struct DropCounter<'a> { - count: &'a mut u32, -} - -impl Drop for DropCounter<'_> { - fn drop(&mut self) { - *self.count += 1; - } -} - -#[test] -fn test_small_vec_struct() { - assert_eq!(size_of::>(), size_of::() * 3); -} - -#[test] -fn test_double_drop() { - struct TwoVec { - x: Vec, - y: Vec, - } - - let (mut count_x, mut count_y) = (0, 0); - { - let mut tv = TwoVec { x: Vec::new(), y: Vec::new() }; - tv.x.push(DropCounter { count: &mut count_x }); - tv.y.push(DropCounter { count: &mut count_y }); - - // If Vec had a drop flag, here is where it would be zeroed. - // Instead, it should rely on its internal state to prevent - // doing anything significant when dropped multiple times. - drop(tv.x); - - // Here tv goes out of scope, tv.y should be dropped, but not tv.x. - } - - assert_eq!(count_x, 1); - assert_eq!(count_y, 1); -} - -#[test] -fn test_reserve() { - let mut v = Vec::new(); - assert_eq!(v.capacity(), 0); - - v.reserve(2); - assert!(v.capacity() >= 2); - - for i in 0..16 { - v.push(i); - } - - assert!(v.capacity() >= 16); - v.reserve(16); - assert!(v.capacity() >= 32); - - v.push(16); - - v.reserve(16); - assert!(v.capacity() >= 33) -} - -#[test] -fn test_zst_capacity() { - assert_eq!(Vec::<()>::new().capacity(), usize::MAX); -} - -#[test] -fn test_indexing() { - let v: Vec = vec![10, 20]; - assert_eq!(v[0], 10); - assert_eq!(v[1], 20); - let mut x: usize = 0; - assert_eq!(v[x], 10); - assert_eq!(v[x + 1], 20); - x = x + 1; - assert_eq!(v[x], 20); - assert_eq!(v[x - 1], 10); -} - -#[test] -fn test_debug_fmt() { - let vec1: Vec = vec![]; - assert_eq!("[]", format!("{:?}", vec1)); - - let vec2 = vec![0, 1]; - assert_eq!("[0, 1]", format!("{:?}", vec2)); - - let slice: &[isize] = &[4, 5]; - assert_eq!("[4, 5]", format!("{slice:?}")); -} - -#[test] -fn test_push() { - let mut v = vec![]; - v.push(1); - assert_eq!(v, [1]); - v.push(2); - assert_eq!(v, [1, 2]); - v.push(3); - assert_eq!(v, [1, 2, 3]); -} - -#[test] -fn test_extend() { - let mut v = Vec::new(); - let mut w = Vec::new(); - - v.extend(w.clone()); - assert_eq!(v, &[]); - - v.extend(0..3); - for i in 0..3 { - w.push(i) - } - - assert_eq!(v, w); - - v.extend(3..10); - for i in 3..10 { - w.push(i) - } - - assert_eq!(v, w); - - v.extend(w.clone()); // specializes to `append` - assert!(v.iter().eq(w.iter().chain(w.iter()))); - - // Zero sized types - #[derive(PartialEq, Debug)] - struct Foo; - - let mut a = Vec::new(); - let b = vec![Foo, Foo]; - - a.extend(b); - assert_eq!(a, &[Foo, Foo]); - - // Double drop - let mut count_x = 0; - { - let mut x = Vec::new(); - let y = vec![DropCounter { count: &mut count_x }]; - x.extend(y); - } - assert_eq!(count_x, 1); -} - -#[test] -fn test_extend_from_slice() { - let a: Vec = vec![1, 2, 3, 4, 5]; - let b: Vec = vec![6, 7, 8, 9, 0]; - - let mut v: Vec = a; - - v.extend_from_slice(&b); - - assert_eq!(v, [1, 2, 3, 4, 5, 6, 7, 8, 9, 0]); -} - -#[test] -fn test_extend_ref() { - let mut v = vec![1, 2]; - v.extend(&[3, 4, 5]); - - assert_eq!(v.len(), 5); - assert_eq!(v, [1, 2, 3, 4, 5]); - - let w = vec![6, 7]; - v.extend(&w); - - assert_eq!(v.len(), 7); - assert_eq!(v, [1, 2, 3, 4, 5, 6, 7]); -} - -#[test] -fn test_slice_from_ref() { - let values = vec![1, 2, 3, 4, 5]; - let slice = &values[1..3]; - - assert_eq!(slice, [2, 3]); -} - -#[test] -fn test_slice_from_mut() { - let mut values = vec![1, 2, 3, 4, 5]; - { - let slice = &mut values[2..]; - assert!(slice == [3, 4, 5]); - for p in slice { - *p += 2; - } - } - - assert!(values == [1, 2, 5, 6, 7]); -} - -#[test] -fn test_slice_to_mut() { - let mut values = vec![1, 2, 3, 4, 5]; - { - let slice = &mut values[..2]; - assert!(slice == [1, 2]); - for p in slice { - *p += 1; - } - } - - assert!(values == [2, 3, 3, 4, 5]); -} - -#[test] -fn test_split_at_mut() { - let mut values = vec![1, 2, 3, 4, 5]; - { - let (left, right) = values.split_at_mut(2); - { - let left: &[_] = left; - assert!(&left[..left.len()] == &[1, 2]); - } - for p in left { - *p += 1; - } - - { - let right: &[_] = right; - assert!(&right[..right.len()] == &[3, 4, 5]); - } - for p in right { - *p += 2; - } - } - - assert_eq!(values, [2, 3, 5, 6, 7]); -} - -#[test] -fn test_clone() { - let v: Vec = vec![]; - let w = vec![1, 2, 3]; - - assert_eq!(v, v.clone()); - - let z = w.clone(); - assert_eq!(w, z); - // they should be disjoint in memory. - assert!(w.as_ptr() != z.as_ptr()) -} - -#[test] -fn test_clone_from() { - let mut v = vec![]; - let three: Vec> = vec![Box::new(1), Box::new(2), Box::new(3)]; - let two: Vec> = vec![Box::new(4), Box::new(5)]; - // zero, long - v.clone_from(&three); - assert_eq!(v, three); - - // equal - v.clone_from(&three); - assert_eq!(v, three); - - // long, short - v.clone_from(&two); - assert_eq!(v, two); - - // short, long - v.clone_from(&three); - assert_eq!(v, three) -} - -#[test] -fn test_retain() { - let mut vec = vec![1, 2, 3, 4]; - vec.retain(|&x| x % 2 == 0); - assert_eq!(vec, [2, 4]); -} - -#[test] -fn test_retain_predicate_order() { - for to_keep in [true, false] { - let mut number_of_executions = 0; - let mut vec = vec![1, 2, 3, 4]; - let mut next_expected = 1; - vec.retain(|&x| { - assert_eq!(next_expected, x); - next_expected += 1; - number_of_executions += 1; - to_keep - }); - assert_eq!(number_of_executions, 4); - } -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_retain_pred_panic_with_hole() { - let v = (0..5).map(Rc::new).collect::>(); - catch_unwind(AssertUnwindSafe(|| { - let mut v = v.clone(); - v.retain(|r| match **r { - 0 => true, - 1 => false, - 2 => true, - _ => panic!(), - }); - })) - .unwrap_err(); - // Everything is dropped when predicate panicked. - assert!(v.iter().all(|r| Rc::strong_count(r) == 1)); -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_retain_pred_panic_no_hole() { - let v = (0..5).map(Rc::new).collect::>(); - catch_unwind(AssertUnwindSafe(|| { - let mut v = v.clone(); - v.retain(|r| match **r { - 0 | 1 | 2 => true, - _ => panic!(), - }); - })) - .unwrap_err(); - // Everything is dropped when predicate panicked. - assert!(v.iter().all(|r| Rc::strong_count(r) == 1)); -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_retain_drop_panic() { - struct Wrap(Rc); - - impl Drop for Wrap { - fn drop(&mut self) { - if *self.0 == 3 { - panic!(); - } - } - } - - let v = (0..5).map(|x| Rc::new(x)).collect::>(); - catch_unwind(AssertUnwindSafe(|| { - let mut v = v.iter().map(|r| Wrap(r.clone())).collect::>(); - v.retain(|w| match *w.0 { - 0 => true, - 1 => false, - 2 => true, - 3 => false, // Drop panic. - _ => true, - }); - })) - .unwrap_err(); - // Other elements are dropped when `drop` of one element panicked. - // The panicked wrapper also has its Rc dropped. - assert!(v.iter().all(|r| Rc::strong_count(r) == 1)); -} - -#[test] -fn test_retain_maybeuninits() { - // This test aimed to be run under miri. - use core::mem::MaybeUninit; - let mut vec: Vec<_> = [1i32, 2, 3, 4].map(|v| MaybeUninit::new(vec![v])).into(); - vec.retain(|x| { - // SAFETY: Retain must visit every element of Vec in original order and exactly once. - // Our values is initialized at creation of Vec. - let v = unsafe { x.assume_init_ref()[0] }; - if v & 1 == 0 { - return true; - } - // SAFETY: Value is initialized. - // Value wouldn't be dropped by `Vec::retain` - // because `MaybeUninit` doesn't drop content. - drop(unsafe { x.assume_init_read() }); - false - }); - let vec: Vec = vec - .into_iter() - .map(|x| unsafe { - // SAFETY: All values dropped in retain predicate must be removed by `Vec::retain`. - // Remaining values are initialized. - x.assume_init()[0] - }) - .collect(); - assert_eq!(vec, [2, 4]); -} - -#[test] -fn test_dedup() { - fn case(a: Vec, b: Vec) { - let mut v = a; - v.dedup(); - assert_eq!(v, b); - } - case(vec![], vec![]); - case(vec![1], vec![1]); - case(vec![1, 1], vec![1]); - case(vec![1, 2, 3], vec![1, 2, 3]); - case(vec![1, 1, 2, 3], vec![1, 2, 3]); - case(vec![1, 2, 2, 3], vec![1, 2, 3]); - case(vec![1, 2, 3, 3], vec![1, 2, 3]); - case(vec![1, 1, 2, 2, 2, 3, 3], vec![1, 2, 3]); -} - -#[test] -fn test_dedup_by_key() { - fn case(a: Vec, b: Vec) { - let mut v = a; - v.dedup_by_key(|i| *i / 10); - assert_eq!(v, b); - } - case(vec![], vec![]); - case(vec![10], vec![10]); - case(vec![10, 11], vec![10]); - case(vec![10, 20, 30], vec![10, 20, 30]); - case(vec![10, 11, 20, 30], vec![10, 20, 30]); - case(vec![10, 20, 21, 30], vec![10, 20, 30]); - case(vec![10, 20, 30, 31], vec![10, 20, 30]); - case(vec![10, 11, 20, 21, 22, 30, 31], vec![10, 20, 30]); -} - -#[test] -fn test_dedup_by() { - let mut vec = vec!["foo", "bar", "Bar", "baz", "bar"]; - vec.dedup_by(|a, b| a.eq_ignore_ascii_case(b)); - - assert_eq!(vec, ["foo", "bar", "baz", "bar"]); - - let mut vec = vec![("foo", 1), ("foo", 2), ("bar", 3), ("bar", 4), ("bar", 5)]; - vec.dedup_by(|a, b| { - a.0 == b.0 && { - b.1 += a.1; - true - } - }); - - assert_eq!(vec, [("foo", 3), ("bar", 12)]); -} - -#[test] -fn test_dedup_unique() { - let mut v0: Vec> = vec![Box::new(1), Box::new(1), Box::new(2), Box::new(3)]; - v0.dedup(); - let mut v1: Vec> = vec![Box::new(1), Box::new(2), Box::new(2), Box::new(3)]; - v1.dedup(); - let mut v2: Vec> = vec![Box::new(1), Box::new(2), Box::new(3), Box::new(3)]; - v2.dedup(); - // If the boxed pointers were leaked or otherwise misused, valgrind - // and/or rt should raise errors. -} - -#[test] -fn zero_sized_values() { - let mut v = Vec::new(); - assert_eq!(v.len(), 0); - v.push(()); - assert_eq!(v.len(), 1); - v.push(()); - assert_eq!(v.len(), 2); - assert_eq!(v.pop(), Some(())); - assert_eq!(v.pop(), Some(())); - assert_eq!(v.pop(), None); - - assert_eq!(v.iter().count(), 0); - v.push(()); - assert_eq!(v.iter().count(), 1); - v.push(()); - assert_eq!(v.iter().count(), 2); - - for &() in &v {} - - assert_eq!(v.iter_mut().count(), 2); - v.push(()); - assert_eq!(v.iter_mut().count(), 3); - v.push(()); - assert_eq!(v.iter_mut().count(), 4); - - for &mut () in &mut v {} - unsafe { - v.set_len(0); - } - assert_eq!(v.iter_mut().count(), 0); -} - -#[test] -fn test_partition() { - assert_eq!([].into_iter().partition(|x: &i32| *x < 3), (vec![], vec![])); - assert_eq!([1, 2, 3].into_iter().partition(|x| *x < 4), (vec![1, 2, 3], vec![])); - assert_eq!([1, 2, 3].into_iter().partition(|x| *x < 2), (vec![1], vec![2, 3])); - assert_eq!([1, 2, 3].into_iter().partition(|x| *x < 0), (vec![], vec![1, 2, 3])); -} - -#[test] -fn test_zip_unzip() { - let z1 = vec![(1, 4), (2, 5), (3, 6)]; - - let (left, right): (Vec<_>, Vec<_>) = z1.iter().cloned().unzip(); - - assert_eq!((1, 4), (left[0], right[0])); - assert_eq!((2, 5), (left[1], right[1])); - assert_eq!((3, 6), (left[2], right[2])); -} - -#[test] -fn test_cmp() { - let x: &[isize] = &[1, 2, 3, 4, 5]; - let cmp: &[isize] = &[1, 2, 3, 4, 5]; - assert_eq!(&x[..], cmp); - let cmp: &[isize] = &[3, 4, 5]; - assert_eq!(&x[2..], cmp); - let cmp: &[isize] = &[1, 2, 3]; - assert_eq!(&x[..3], cmp); - let cmp: &[isize] = &[2, 3, 4]; - assert_eq!(&x[1..4], cmp); - - let x: Vec = vec![1, 2, 3, 4, 5]; - let cmp: &[isize] = &[1, 2, 3, 4, 5]; - assert_eq!(&x[..], cmp); - let cmp: &[isize] = &[3, 4, 5]; - assert_eq!(&x[2..], cmp); - let cmp: &[isize] = &[1, 2, 3]; - assert_eq!(&x[..3], cmp); - let cmp: &[isize] = &[2, 3, 4]; - assert_eq!(&x[1..4], cmp); -} - -#[test] -fn test_vec_truncate_drop() { - static mut DROPS: u32 = 0; - struct Elem(#[allow(dead_code)] i32); - impl Drop for Elem { - fn drop(&mut self) { - unsafe { - DROPS += 1; - } - } - } - - let mut v = vec![Elem(1), Elem(2), Elem(3), Elem(4), Elem(5)]; - assert_eq!(unsafe { DROPS }, 0); - v.truncate(3); - assert_eq!(unsafe { DROPS }, 2); - v.truncate(0); - assert_eq!(unsafe { DROPS }, 5); -} - -#[test] -#[should_panic] -fn test_vec_truncate_fail() { - struct BadElem(i32); - impl Drop for BadElem { - fn drop(&mut self) { - let BadElem(ref mut x) = *self; - if *x == 0xbadbeef { - panic!("BadElem panic: 0xbadbeef") - } - } - } - - let mut v = vec![BadElem(1), BadElem(2), BadElem(0xbadbeef), BadElem(4)]; - v.truncate(0); -} - -#[test] -fn test_index() { - let vec = vec![1, 2, 3]; - assert!(vec[1] == 2); -} - -#[test] -#[should_panic] -fn test_index_out_of_bounds() { - let vec = vec![1, 2, 3]; - let _ = vec[3]; -} - -#[test] -#[should_panic] -fn test_slice_out_of_bounds_1() { - let x = vec![1, 2, 3, 4, 5]; - let _ = &x[!0..]; -} - -#[test] -#[should_panic] -fn test_slice_out_of_bounds_2() { - let x = vec![1, 2, 3, 4, 5]; - let _ = &x[..6]; -} - -#[test] -#[should_panic] -fn test_slice_out_of_bounds_3() { - let x = vec![1, 2, 3, 4, 5]; - let _ = &x[!0..4]; -} - -#[test] -#[should_panic] -fn test_slice_out_of_bounds_4() { - let x = vec![1, 2, 3, 4, 5]; - let _ = &x[1..6]; -} - -#[test] -#[should_panic] -fn test_slice_out_of_bounds_5() { - let x = vec![1, 2, 3, 4, 5]; - let _ = &x[3..2]; -} - -#[test] -#[should_panic] -fn test_swap_remove_empty() { - let mut vec = Vec::::new(); - vec.swap_remove(0); -} - -#[test] -fn test_move_items() { - let vec = vec![1, 2, 3]; - let mut vec2 = vec![]; - for i in vec { - vec2.push(i); - } - assert_eq!(vec2, [1, 2, 3]); -} - -#[test] -fn test_move_items_reverse() { - let vec = vec![1, 2, 3]; - let mut vec2 = vec![]; - for i in vec.into_iter().rev() { - vec2.push(i); - } - assert_eq!(vec2, [3, 2, 1]); -} - -#[test] -fn test_move_items_zero_sized() { - let vec = vec![(), (), ()]; - let mut vec2 = vec![]; - for i in vec { - vec2.push(i); - } - assert_eq!(vec2, [(), (), ()]); -} - -#[test] -fn test_drain_empty_vec() { - let mut vec: Vec = vec![]; - let mut vec2: Vec = vec![]; - for i in vec.drain(..) { - vec2.push(i); - } - assert!(vec.is_empty()); - assert!(vec2.is_empty()); -} - -#[test] -fn test_drain_items() { - let mut vec = vec![1, 2, 3]; - let mut vec2 = vec![]; - for i in vec.drain(..) { - vec2.push(i); - } - assert_eq!(vec, []); - assert_eq!(vec2, [1, 2, 3]); -} - -#[test] -fn test_drain_items_reverse() { - let mut vec = vec![1, 2, 3]; - let mut vec2 = vec![]; - for i in vec.drain(..).rev() { - vec2.push(i); - } - assert_eq!(vec, []); - assert_eq!(vec2, [3, 2, 1]); -} - -#[test] -fn test_drain_items_zero_sized() { - let mut vec = vec![(), (), ()]; - let mut vec2 = vec![]; - for i in vec.drain(..) { - vec2.push(i); - } - assert_eq!(vec, []); - assert_eq!(vec2, [(), (), ()]); -} - -#[test] -#[should_panic] -fn test_drain_out_of_bounds() { - let mut v = vec![1, 2, 3, 4, 5]; - v.drain(5..6); -} - -#[test] -fn test_drain_range() { - let mut v = vec![1, 2, 3, 4, 5]; - for _ in v.drain(4..) {} - assert_eq!(v, &[1, 2, 3, 4]); - - let mut v: Vec<_> = (1..6).map(|x| x.to_string()).collect(); - for _ in v.drain(1..4) {} - assert_eq!(v, &[1.to_string(), 5.to_string()]); - - let mut v: Vec<_> = (1..6).map(|x| x.to_string()).collect(); - for _ in v.drain(1..4).rev() {} - assert_eq!(v, &[1.to_string(), 5.to_string()]); - - let mut v: Vec<_> = vec![(); 5]; - for _ in v.drain(1..4).rev() {} - assert_eq!(v, &[(), ()]); -} - -#[test] -fn test_drain_inclusive_range() { - let mut v = vec!['a', 'b', 'c', 'd', 'e']; - for _ in v.drain(1..=3) {} - assert_eq!(v, &['a', 'e']); - - let mut v: Vec<_> = (0..=5).map(|x| x.to_string()).collect(); - for _ in v.drain(1..=5) {} - assert_eq!(v, &["0".to_string()]); - - let mut v: Vec = (0..=5).map(|x| x.to_string()).collect(); - for _ in v.drain(0..=5) {} - assert_eq!(v, Vec::::new()); - - let mut v: Vec<_> = (0..=5).map(|x| x.to_string()).collect(); - for _ in v.drain(0..=3) {} - assert_eq!(v, &["4".to_string(), "5".to_string()]); - - let mut v: Vec<_> = (0..=1).map(|x| x.to_string()).collect(); - for _ in v.drain(..=0) {} - assert_eq!(v, &["1".to_string()]); -} - -#[test] -fn test_drain_max_vec_size() { - let mut v = Vec::<()>::with_capacity(usize::MAX); - unsafe { - v.set_len(usize::MAX); - } - for _ in v.drain(usize::MAX - 1..) {} - assert_eq!(v.len(), usize::MAX - 1); - - let mut v = Vec::<()>::with_capacity(usize::MAX); - unsafe { - v.set_len(usize::MAX); - } - for _ in v.drain(usize::MAX - 1..=usize::MAX - 1) {} - assert_eq!(v.len(), usize::MAX - 1); -} - -#[test] -#[should_panic] -fn test_drain_index_overflow() { - let mut v = Vec::<()>::with_capacity(usize::MAX); - unsafe { - v.set_len(usize::MAX); - } - v.drain(0..=usize::MAX); -} - -#[test] -#[should_panic] -fn test_drain_inclusive_out_of_bounds() { - let mut v = vec![1, 2, 3, 4, 5]; - v.drain(5..=5); -} - -#[test] -#[should_panic] -fn test_drain_start_overflow() { - let mut v = vec![1, 2, 3]; - v.drain((Excluded(usize::MAX), Included(0))); -} - -#[test] -#[should_panic] -fn test_drain_end_overflow() { - let mut v = vec![1, 2, 3]; - v.drain((Included(0), Included(usize::MAX))); -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_drain_leak() { - static mut DROPS: i32 = 0; - - #[derive(Debug, PartialEq)] - struct D(u32, bool); - - impl Drop for D { - fn drop(&mut self) { - unsafe { - DROPS += 1; - } - - if self.1 { - panic!("panic in `drop`"); - } - } - } - - let mut v = vec![ - D(0, false), - D(1, false), - D(2, false), - D(3, false), - D(4, true), - D(5, false), - D(6, false), - ]; - - catch_unwind(AssertUnwindSafe(|| { - v.drain(2..=5); - })) - .ok(); - - assert_eq!(unsafe { DROPS }, 4); - assert_eq!(v, vec![D(0, false), D(1, false), D(6, false),]); -} - -#[test] -fn test_drain_keep_rest() { - let mut v = vec![0, 1, 2, 3, 4, 5, 6]; - let mut drain = v.drain(1..6); - assert_eq!(drain.next(), Some(1)); - assert_eq!(drain.next_back(), Some(5)); - assert_eq!(drain.next(), Some(2)); - - drain.keep_rest(); - assert_eq!(v, &[0, 3, 4, 6]); -} - -#[test] -fn test_drain_keep_rest_all() { - let mut v = vec![0, 1, 2, 3, 4, 5, 6]; - v.drain(1..6).keep_rest(); - assert_eq!(v, &[0, 1, 2, 3, 4, 5, 6]); -} - -#[test] -fn test_drain_keep_rest_none() { - let mut v = vec![0, 1, 2, 3, 4, 5, 6]; - let mut drain = v.drain(1..6); - - drain.by_ref().for_each(drop); - - drain.keep_rest(); - assert_eq!(v, &[0, 6]); -} - -#[test] -fn test_splice() { - let mut v = vec![1, 2, 3, 4, 5]; - let a = [10, 11, 12]; - v.splice(2..4, a); - assert_eq!(v, &[1, 2, 10, 11, 12, 5]); - v.splice(1..3, Some(20)); - assert_eq!(v, &[1, 20, 11, 12, 5]); -} - -#[test] -fn test_splice_inclusive_range() { - let mut v = vec![1, 2, 3, 4, 5]; - let a = [10, 11, 12]; - let t1: Vec<_> = v.splice(2..=3, a).collect(); - assert_eq!(v, &[1, 2, 10, 11, 12, 5]); - assert_eq!(t1, &[3, 4]); - let t2: Vec<_> = v.splice(1..=2, Some(20)).collect(); - assert_eq!(v, &[1, 20, 11, 12, 5]); - assert_eq!(t2, &[2, 10]); -} - -#[test] -#[should_panic] -fn test_splice_out_of_bounds() { - let mut v = vec![1, 2, 3, 4, 5]; - let a = [10, 11, 12]; - v.splice(5..6, a); -} - -#[test] -#[should_panic] -fn test_splice_inclusive_out_of_bounds() { - let mut v = vec![1, 2, 3, 4, 5]; - let a = [10, 11, 12]; - v.splice(5..=5, a); -} - -#[test] -fn test_splice_items_zero_sized() { - let mut vec = vec![(), (), ()]; - let vec2 = vec![]; - let t: Vec<_> = vec.splice(1..2, vec2.iter().cloned()).collect(); - assert_eq!(vec, &[(), ()]); - assert_eq!(t, &[()]); -} - -#[test] -fn test_splice_unbounded() { - let mut vec = vec![1, 2, 3, 4, 5]; - let t: Vec<_> = vec.splice(.., None).collect(); - assert_eq!(vec, &[]); - assert_eq!(t, &[1, 2, 3, 4, 5]); -} - -#[test] -fn test_splice_forget() { - let mut v = vec![1, 2, 3, 4, 5]; - let a = [10, 11, 12]; - std::mem::forget(v.splice(2..4, a)); - assert_eq!(v, &[1, 2]); -} - -#[test] -fn test_into_boxed_slice() { - let xs = vec![1, 2, 3]; - let ys = xs.into_boxed_slice(); - assert_eq!(&*ys, [1, 2, 3]); -} - -#[test] -fn test_append() { - let mut vec = vec![1, 2, 3]; - let mut vec2 = vec![4, 5, 6]; - vec.append(&mut vec2); - assert_eq!(vec, [1, 2, 3, 4, 5, 6]); - assert_eq!(vec2, []); -} - -#[test] -fn test_split_off() { - let mut vec = vec![1, 2, 3, 4, 5, 6]; - let orig_ptr = vec.as_ptr(); - let orig_capacity = vec.capacity(); - - let split_off = vec.split_off(4); - assert_eq!(vec, [1, 2, 3, 4]); - assert_eq!(split_off, [5, 6]); - assert_eq!(vec.capacity(), orig_capacity); - assert_eq!(vec.as_ptr(), orig_ptr); -} - -#[test] -fn test_split_off_take_all() { - // Allocate enough capacity that we can tell whether the split-off vector's - // capacity is based on its size, or (incorrectly) on the original capacity. - let mut vec = Vec::with_capacity(1000); - vec.extend([1, 2, 3, 4, 5, 6]); - let orig_ptr = vec.as_ptr(); - let orig_capacity = vec.capacity(); - - let split_off = vec.split_off(0); - assert_eq!(vec, []); - assert_eq!(split_off, [1, 2, 3, 4, 5, 6]); - assert_eq!(vec.capacity(), orig_capacity); - assert_eq!(vec.as_ptr(), orig_ptr); - - // The split-off vector should be newly-allocated, and should not have - // stolen the original vector's allocation. - assert!(split_off.capacity() < orig_capacity); - assert_ne!(split_off.as_ptr(), orig_ptr); -} - -#[test] -fn test_into_iter_as_slice() { - let vec = vec!['a', 'b', 'c']; - let mut into_iter = vec.into_iter(); - assert_eq!(into_iter.as_slice(), &['a', 'b', 'c']); - let _ = into_iter.next().unwrap(); - assert_eq!(into_iter.as_slice(), &['b', 'c']); - let _ = into_iter.next().unwrap(); - let _ = into_iter.next().unwrap(); - assert_eq!(into_iter.as_slice(), &[]); -} - -#[test] -fn test_into_iter_as_mut_slice() { - let vec = vec!['a', 'b', 'c']; - let mut into_iter = vec.into_iter(); - assert_eq!(into_iter.as_slice(), &['a', 'b', 'c']); - into_iter.as_mut_slice()[0] = 'x'; - into_iter.as_mut_slice()[1] = 'y'; - assert_eq!(into_iter.next().unwrap(), 'x'); - assert_eq!(into_iter.as_slice(), &['y', 'c']); -} - -#[test] -fn test_into_iter_debug() { - let vec = vec!['a', 'b', 'c']; - let into_iter = vec.into_iter(); - let debug = format!("{into_iter:?}"); - assert_eq!(debug, "IntoIter(['a', 'b', 'c'])"); -} - -#[test] -fn test_into_iter_count() { - assert_eq!([1, 2, 3].into_iter().count(), 3); -} - -#[test] -fn test_into_iter_next_chunk() { - let mut iter = b"lorem".to_vec().into_iter(); - - assert_eq!(iter.next_chunk().unwrap(), [b'l', b'o']); // N is inferred as 2 - assert_eq!(iter.next_chunk().unwrap(), [b'r', b'e', b'm']); // N is inferred as 3 - assert_eq!(iter.next_chunk::<4>().unwrap_err().as_slice(), &[]); // N is explicitly 4 -} - -#[test] -fn test_into_iter_clone() { - fn iter_equal>(it: I, slice: &[i32]) { - let v: Vec = it.collect(); - assert_eq!(&v[..], slice); - } - let mut it = [1, 2, 3].into_iter(); - iter_equal(it.clone(), &[1, 2, 3]); - assert_eq!(it.next(), Some(1)); - let mut it = it.rev(); - iter_equal(it.clone(), &[3, 2]); - assert_eq!(it.next(), Some(3)); - iter_equal(it.clone(), &[2]); - assert_eq!(it.next(), Some(2)); - iter_equal(it.clone(), &[]); - assert_eq!(it.next(), None); -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_into_iter_leak() { - static mut DROPS: i32 = 0; - - struct D(bool); - - impl Drop for D { - fn drop(&mut self) { - unsafe { - DROPS += 1; - } - - if self.0 { - panic!("panic in `drop`"); - } - } - } - - let v = vec![D(false), D(true), D(false)]; - - catch_unwind(move || drop(v.into_iter())).ok(); - - assert_eq!(unsafe { DROPS }, 3); -} - -#[test] -fn test_into_iter_advance_by() { - let mut i = vec![1, 2, 3, 4, 5].into_iter(); - assert_eq!(i.advance_by(0), Ok(())); - assert_eq!(i.advance_back_by(0), Ok(())); - assert_eq!(i.as_slice(), [1, 2, 3, 4, 5]); - - assert_eq!(i.advance_by(1), Ok(())); - assert_eq!(i.advance_back_by(1), Ok(())); - assert_eq!(i.as_slice(), [2, 3, 4]); - - assert_eq!(i.advance_back_by(usize::MAX), Err(NonZero::new(usize::MAX - 3).unwrap())); - - assert_eq!(i.advance_by(usize::MAX), Err(NonZero::new(usize::MAX).unwrap())); - - assert_eq!(i.advance_by(0), Ok(())); - assert_eq!(i.advance_back_by(0), Ok(())); - - assert_eq!(i.len(), 0); -} - -#[test] -fn test_into_iter_drop_allocator() { - struct ReferenceCountedAllocator<'a>(#[allow(dead_code)] DropCounter<'a>); - - unsafe impl Allocator for ReferenceCountedAllocator<'_> { - fn allocate(&self, layout: Layout) -> Result, core::alloc::AllocError> { - System.allocate(layout) - } - - unsafe fn deallocate(&self, ptr: NonNull, layout: Layout) { - // Safety: Invariants passed to caller. - unsafe { System.deallocate(ptr, layout) } - } - } - - let mut drop_count = 0; - - let allocator = ReferenceCountedAllocator(DropCounter { count: &mut drop_count }); - let _ = Vec::::new_in(allocator); - assert_eq!(drop_count, 1); - - let allocator = ReferenceCountedAllocator(DropCounter { count: &mut drop_count }); - let _ = Vec::::new_in(allocator).into_iter(); - assert_eq!(drop_count, 2); -} - -#[test] -fn test_into_iter_zst() { - #[derive(Debug, Clone)] - struct AlignedZstWithDrop([u64; 0]); - impl Drop for AlignedZstWithDrop { - fn drop(&mut self) { - let addr = self as *mut _ as usize; - assert!(hint::black_box(addr) % mem::align_of::() == 0); - } - } - - const C: AlignedZstWithDrop = AlignedZstWithDrop([0u64; 0]); - - for _ in vec![C].into_iter() {} - for _ in vec![C; 5].into_iter().rev() {} - - let mut it = vec![C, C].into_iter(); - assert_eq!(it.advance_by(1), Ok(())); - drop(it); - - let mut it = vec![C, C].into_iter(); - it.next_chunk::<1>().unwrap(); - drop(it); - - let mut it = vec![C, C].into_iter(); - it.next_chunk::<4>().unwrap_err(); - drop(it); -} - -#[test] -fn test_from_iter_specialization() { - let src: Vec = vec![0usize; 1]; - let srcptr = src.as_ptr(); - let sink = src.into_iter().collect::>(); - let sinkptr = sink.as_ptr(); - assert_eq!(srcptr, sinkptr); -} - -#[test] -fn test_from_iter_partially_drained_in_place_specialization() { - let src: Vec = vec![0usize; 10]; - let srcptr = src.as_ptr(); - let mut iter = src.into_iter(); - iter.next(); - iter.next(); - let sink = iter.collect::>(); - let sinkptr = sink.as_ptr(); - assert_eq!(srcptr, sinkptr); -} - -#[test] -fn test_from_iter_specialization_with_iterator_adapters() { - fn assert_in_place_trait(_: &T) {} - let owned: Vec = vec![0usize; 256]; - let refd: Vec<&usize> = owned.iter().collect(); - let src: Vec<&&usize> = refd.iter().collect(); - let srcptr = src.as_ptr(); - let iter = src - .into_iter() - .copied() - .cloned() - .enumerate() - .map(|i| i.0 + i.1) - .zip(std::iter::repeat(1usize)) - .map(|(a, b)| a + b) - .map_while(Option::Some) - .skip(1) - .map(|e| if e != usize::MAX { Ok(NonZero::new(e)) } else { Err(()) }); - assert_in_place_trait(&iter); - let sink = iter.collect::, _>>().unwrap(); - let sinkptr = sink.as_ptr(); - assert_eq!(srcptr as *const usize, sinkptr as *const usize); -} - -#[test] -fn test_in_place_specialization_step_up_down() { - fn assert_in_place_trait(_: &T) {} - let src = vec![[0u8; 4]; 256]; - let srcptr = src.as_ptr(); - let src_cap = src.capacity(); - let iter = src.into_iter().flatten(); - assert_in_place_trait(&iter); - let sink = iter.collect::>(); - let sinkptr = sink.as_ptr(); - assert_eq!(srcptr as *const u8, sinkptr); - assert_eq!(src_cap * 4, sink.capacity()); - - let iter = sink.into_iter().array_chunks::<4>(); - assert_in_place_trait(&iter); - let sink = iter.collect::>(); - let sinkptr = sink.as_ptr(); - assert_eq!(srcptr, sinkptr); - assert_eq!(src_cap, sink.capacity()); - - let mut src: Vec = Vec::with_capacity(17); - let src_bytes = src.capacity(); - src.resize(8, 0u8); - let sink: Vec<[u8; 4]> = src.into_iter().array_chunks::<4>().collect(); - let sink_bytes = sink.capacity() * 4; - assert_ne!(src_bytes, sink_bytes); - assert_eq!(sink.len(), 2); - - let mut src: Vec<[u8; 3]> = Vec::with_capacity(17); - src.resize(8, [0; 3]); - let iter = src.into_iter().map(|[a, b, _]| [a, b]); - assert_in_place_trait(&iter); - let sink: Vec<[u8; 2]> = iter.collect(); - assert_eq!(sink.len(), 8); - assert!(sink.capacity() <= 25); - - let src = vec![[0u8; 4]; 256]; - let srcptr = src.as_ptr(); - let iter = src.into_iter().flat_map(|a| a.into_iter().map(|b| b.wrapping_add(1))); - assert_in_place_trait(&iter); - let sink = iter.collect::>(); - assert_eq!(srcptr as *const u8, sink.as_ptr()); -} - -#[test] -fn test_from_iter_specialization_head_tail_drop() { - let drop_count: Vec<_> = (0..=2).map(|_| Rc::new(())).collect(); - let src: Vec<_> = drop_count.iter().cloned().collect(); - let srcptr = src.as_ptr(); - let iter = src.into_iter(); - let sink: Vec<_> = iter.skip(1).take(1).collect(); - let sinkptr = sink.as_ptr(); - assert_eq!(srcptr, sinkptr, "specialization was applied"); - assert_eq!(Rc::strong_count(&drop_count[0]), 1, "front was dropped"); - assert_eq!(Rc::strong_count(&drop_count[1]), 2, "one element was collected"); - assert_eq!(Rc::strong_count(&drop_count[2]), 1, "tail was dropped"); - assert_eq!(sink.len(), 1); -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_from_iter_specialization_panic_during_iteration_drops() { - let drop_count: Vec<_> = (0..=2).map(|_| Rc::new(())).collect(); - let src: Vec<_> = drop_count.iter().cloned().collect(); - let iter = src.into_iter(); - - let _ = std::panic::catch_unwind(AssertUnwindSafe(|| { - let _ = iter - .enumerate() - .filter_map(|(i, e)| { - if i == 1 { - std::panic!("aborting iteration"); - } - Some(e) - }) - .collect::>(); - })); - - assert!( - drop_count.iter().map(Rc::strong_count).all(|count| count == 1), - "all items were dropped once" - ); -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_from_iter_specialization_panic_during_drop_doesnt_leak() { - static mut DROP_COUNTER_OLD: [usize; 5] = [0; 5]; - static mut DROP_COUNTER_NEW: [usize; 2] = [0; 2]; - - #[derive(Debug)] - struct Old(usize); - - impl Drop for Old { - fn drop(&mut self) { - unsafe { - DROP_COUNTER_OLD[self.0] += 1; - } - - if self.0 == 3 { - panic!(); - } - - println!("Dropped Old: {}", self.0); - } - } - - #[derive(Debug)] - struct New(usize); - - impl Drop for New { - fn drop(&mut self) { - unsafe { - DROP_COUNTER_NEW[self.0] += 1; - } - - println!("Dropped New: {}", self.0); - } - } - - let _ = std::panic::catch_unwind(AssertUnwindSafe(|| { - let v = vec![Old(0), Old(1), Old(2), Old(3), Old(4)]; - let _ = v.into_iter().map(|x| New(x.0)).take(2).collect::>(); - })); - - assert_eq!(unsafe { DROP_COUNTER_OLD[0] }, 1); - assert_eq!(unsafe { DROP_COUNTER_OLD[1] }, 1); - assert_eq!(unsafe { DROP_COUNTER_OLD[2] }, 1); - assert_eq!(unsafe { DROP_COUNTER_OLD[3] }, 1); - assert_eq!(unsafe { DROP_COUNTER_OLD[4] }, 1); - - assert_eq!(unsafe { DROP_COUNTER_NEW[0] }, 1); - assert_eq!(unsafe { DROP_COUNTER_NEW[1] }, 1); -} - -// regression test for issue #85322. Peekable previously implemented InPlaceIterable, -// but due to an interaction with IntoIter's current Clone implementation it failed to uphold -// the contract. -#[test] -fn test_collect_after_iterator_clone() { - let v = vec![0; 5]; - let mut i = v.into_iter().map(|i| i + 1).peekable(); - i.peek(); - let v = i.clone().collect::>(); - assert_eq!(v, [1, 1, 1, 1, 1]); - assert!(v.len() <= v.capacity()); -} -#[test] -fn test_cow_from() { - let borrowed: &[_] = &["borrowed", "(slice)"]; - let owned = vec!["owned", "(vec)"]; - match (Cow::from(owned.clone()), Cow::from(borrowed)) { - (Cow::Owned(o), Cow::Borrowed(b)) => assert!(o == owned && b == borrowed), - _ => panic!("invalid `Cow::from`"), - } -} - -#[test] -fn test_from_cow() { - let borrowed: &[_] = &["borrowed", "(slice)"]; - let owned = vec!["owned", "(vec)"]; - assert_eq!(Vec::from(Cow::Borrowed(borrowed)), vec!["borrowed", "(slice)"]); - assert_eq!(Vec::from(Cow::Owned(owned)), vec!["owned", "(vec)"]); -} - -#[allow(dead_code)] -fn assert_covariance() { - fn drain<'new>(d: Drain<'static, &'static str>) -> Drain<'new, &'new str> { - d - } - fn into_iter<'new>(i: IntoIter<&'static str>) -> IntoIter<&'new str> { - i - } -} - -#[test] -fn from_into_inner() { - let vec = vec![1, 2, 3]; - let ptr = vec.as_ptr(); - let vec = vec.into_iter().collect::>(); - assert_eq!(vec, [1, 2, 3]); - assert_eq!(vec.as_ptr(), ptr); - - let ptr = &vec[1] as *const _; - let mut it = vec.into_iter(); - it.next().unwrap(); - let vec = it.collect::>(); - assert_eq!(vec, [2, 3]); - assert!(ptr != vec.as_ptr()); -} - -#[test] -fn overaligned_allocations() { - #[repr(align(256))] - struct Foo(usize); - let mut v = vec![Foo(273)]; - for i in 0..0x1000 { - v.reserve_exact(i); - assert!(v[0].0 == 273); - assert!(v.as_ptr() as usize & 0xff == 0); - v.shrink_to_fit(); - assert!(v[0].0 == 273); - assert!(v.as_ptr() as usize & 0xff == 0); - } -} - -#[test] -fn extract_if_empty() { - let mut vec: Vec = vec![]; - - { - let mut iter = vec.extract_if(|_| true); - assert_eq!(iter.size_hint(), (0, Some(0))); - assert_eq!(iter.next(), None); - assert_eq!(iter.size_hint(), (0, Some(0))); - assert_eq!(iter.next(), None); - assert_eq!(iter.size_hint(), (0, Some(0))); - } - assert_eq!(vec.len(), 0); - assert_eq!(vec, vec![]); -} - -#[test] -fn extract_if_zst() { - let mut vec = vec![(), (), (), (), ()]; - let initial_len = vec.len(); - let mut count = 0; - { - let mut iter = vec.extract_if(|_| true); - assert_eq!(iter.size_hint(), (0, Some(initial_len))); - while let Some(_) = iter.next() { - count += 1; - assert_eq!(iter.size_hint(), (0, Some(initial_len - count))); - } - assert_eq!(iter.size_hint(), (0, Some(0))); - assert_eq!(iter.next(), None); - assert_eq!(iter.size_hint(), (0, Some(0))); - } - - assert_eq!(count, initial_len); - assert_eq!(vec.len(), 0); - assert_eq!(vec, vec![]); -} - -#[test] -fn extract_if_false() { - let mut vec = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; - - let initial_len = vec.len(); - let mut count = 0; - { - let mut iter = vec.extract_if(|_| false); - assert_eq!(iter.size_hint(), (0, Some(initial_len))); - for _ in iter.by_ref() { - count += 1; - } - assert_eq!(iter.size_hint(), (0, Some(0))); - assert_eq!(iter.next(), None); - assert_eq!(iter.size_hint(), (0, Some(0))); - } - - assert_eq!(count, 0); - assert_eq!(vec.len(), initial_len); - assert_eq!(vec, vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10]); -} - -#[test] -fn extract_if_true() { - let mut vec = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; - - let initial_len = vec.len(); - let mut count = 0; - { - let mut iter = vec.extract_if(|_| true); - assert_eq!(iter.size_hint(), (0, Some(initial_len))); - while let Some(_) = iter.next() { - count += 1; - assert_eq!(iter.size_hint(), (0, Some(initial_len - count))); - } - assert_eq!(iter.size_hint(), (0, Some(0))); - assert_eq!(iter.next(), None); - assert_eq!(iter.size_hint(), (0, Some(0))); - } - - assert_eq!(count, initial_len); - assert_eq!(vec.len(), 0); - assert_eq!(vec, vec![]); -} - -#[test] -fn extract_if_complex() { - { - // [+xxx++++++xxxxx++++x+x++] - let mut vec = vec![ - 1, 2, 4, 6, 7, 9, 11, 13, 15, 17, 18, 20, 22, 24, 26, 27, 29, 31, 33, 34, 35, 36, 37, - 39, - ]; - - let removed = vec.extract_if(|x| *x % 2 == 0).collect::>(); - assert_eq!(removed.len(), 10); - assert_eq!(removed, vec![2, 4, 6, 18, 20, 22, 24, 26, 34, 36]); - - assert_eq!(vec.len(), 14); - assert_eq!(vec, vec![1, 7, 9, 11, 13, 15, 17, 27, 29, 31, 33, 35, 37, 39]); - } - - { - // [xxx++++++xxxxx++++x+x++] - let mut vec = vec![ - 2, 4, 6, 7, 9, 11, 13, 15, 17, 18, 20, 22, 24, 26, 27, 29, 31, 33, 34, 35, 36, 37, 39, - ]; - - let removed = vec.extract_if(|x| *x % 2 == 0).collect::>(); - assert_eq!(removed.len(), 10); - assert_eq!(removed, vec![2, 4, 6, 18, 20, 22, 24, 26, 34, 36]); - - assert_eq!(vec.len(), 13); - assert_eq!(vec, vec![7, 9, 11, 13, 15, 17, 27, 29, 31, 33, 35, 37, 39]); - } - - { - // [xxx++++++xxxxx++++x+x] - let mut vec = - vec![2, 4, 6, 7, 9, 11, 13, 15, 17, 18, 20, 22, 24, 26, 27, 29, 31, 33, 34, 35, 36]; - - let removed = vec.extract_if(|x| *x % 2 == 0).collect::>(); - assert_eq!(removed.len(), 10); - assert_eq!(removed, vec![2, 4, 6, 18, 20, 22, 24, 26, 34, 36]); - - assert_eq!(vec.len(), 11); - assert_eq!(vec, vec![7, 9, 11, 13, 15, 17, 27, 29, 31, 33, 35]); - } - - { - // [xxxxxxxxxx+++++++++++] - let mut vec = vec![2, 4, 6, 8, 10, 12, 14, 16, 18, 20, 1, 3, 5, 7, 9, 11, 13, 15, 17, 19]; - - let removed = vec.extract_if(|x| *x % 2 == 0).collect::>(); - assert_eq!(removed.len(), 10); - assert_eq!(removed, vec![2, 4, 6, 8, 10, 12, 14, 16, 18, 20]); - - assert_eq!(vec.len(), 10); - assert_eq!(vec, vec![1, 3, 5, 7, 9, 11, 13, 15, 17, 19]); - } - - { - // [+++++++++++xxxxxxxxxx] - let mut vec = vec![1, 3, 5, 7, 9, 11, 13, 15, 17, 19, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20]; - - let removed = vec.extract_if(|x| *x % 2 == 0).collect::>(); - assert_eq!(removed.len(), 10); - assert_eq!(removed, vec![2, 4, 6, 8, 10, 12, 14, 16, 18, 20]); - - assert_eq!(vec.len(), 10); - assert_eq!(vec, vec![1, 3, 5, 7, 9, 11, 13, 15, 17, 19]); - } -} - -// FIXME: re-enable emscripten once it can unwind again -#[test] -#[cfg(not(target_os = "emscripten"))] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn extract_if_consumed_panic() { - use std::rc::Rc; - use std::sync::Mutex; - - struct Check { - index: usize, - drop_counts: Rc>>, - } - - impl Drop for Check { - fn drop(&mut self) { - self.drop_counts.lock().unwrap()[self.index] += 1; - println!("drop: {}", self.index); - } - } - - let check_count = 10; - let drop_counts = Rc::new(Mutex::new(vec![0_usize; check_count])); - let mut data: Vec = (0..check_count) - .map(|index| Check { index, drop_counts: Rc::clone(&drop_counts) }) - .collect(); - - let _ = std::panic::catch_unwind(move || { - let filter = |c: &mut Check| { - if c.index == 2 { - panic!("panic at index: {}", c.index); - } - // Verify that if the filter could panic again on another element - // that it would not cause a double panic and all elements of the - // vec would still be dropped exactly once. - if c.index == 4 { - panic!("panic at index: {}", c.index); - } - c.index < 6 - }; - let drain = data.extract_if(filter); - - // NOTE: The ExtractIf is explicitly consumed - drain.for_each(drop); - }); - - let drop_counts = drop_counts.lock().unwrap(); - assert_eq!(check_count, drop_counts.len()); - - for (index, count) in drop_counts.iter().cloned().enumerate() { - assert_eq!(1, count, "unexpected drop count at index: {} (count: {})", index, count); - } -} - -// FIXME: Re-enable emscripten once it can catch panics -#[test] -#[cfg(not(target_os = "emscripten"))] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn extract_if_unconsumed_panic() { - use std::rc::Rc; - use std::sync::Mutex; - - struct Check { - index: usize, - drop_counts: Rc>>, - } - - impl Drop for Check { - fn drop(&mut self) { - self.drop_counts.lock().unwrap()[self.index] += 1; - println!("drop: {}", self.index); - } - } - - let check_count = 10; - let drop_counts = Rc::new(Mutex::new(vec![0_usize; check_count])); - let mut data: Vec = (0..check_count) - .map(|index| Check { index, drop_counts: Rc::clone(&drop_counts) }) - .collect(); - - let _ = std::panic::catch_unwind(move || { - let filter = |c: &mut Check| { - if c.index == 2 { - panic!("panic at index: {}", c.index); - } - // Verify that if the filter could panic again on another element - // that it would not cause a double panic and all elements of the - // vec would still be dropped exactly once. - if c.index == 4 { - panic!("panic at index: {}", c.index); - } - c.index < 6 - }; - let _drain = data.extract_if(filter); - - // NOTE: The ExtractIf is dropped without being consumed - }); - - let drop_counts = drop_counts.lock().unwrap(); - assert_eq!(check_count, drop_counts.len()); - - for (index, count) in drop_counts.iter().cloned().enumerate() { - assert_eq!(1, count, "unexpected drop count at index: {} (count: {})", index, count); - } -} - -#[test] -fn extract_if_unconsumed() { - let mut vec = vec![1, 2, 3, 4]; - let drain = vec.extract_if(|&mut x| x % 2 != 0); - drop(drain); - assert_eq!(vec, [1, 2, 3, 4]); -} - -#[test] -fn test_reserve_exact() { - // This is all the same as test_reserve - - let mut v = Vec::new(); - assert_eq!(v.capacity(), 0); - - v.reserve_exact(2); - assert!(v.capacity() >= 2); - - for i in 0..16 { - v.push(i); - } - - assert!(v.capacity() >= 16); - v.reserve_exact(16); - assert!(v.capacity() >= 32); - - v.push(16); - - v.reserve_exact(16); - assert!(v.capacity() >= 33) -} - -#[test] -#[cfg_attr(miri, ignore)] // Miri does not support signalling OOM -#[cfg_attr(target_os = "android", ignore)] // Android used in CI has a broken dlmalloc -fn test_try_with_capacity() { - let mut vec: Vec = Vec::try_with_capacity(5).unwrap(); - assert_eq!(0, vec.len()); - assert!(vec.capacity() >= 5 && vec.capacity() <= isize::MAX as usize / 4); - assert!(vec.spare_capacity_mut().len() >= 5); - - assert!(Vec::::try_with_capacity(isize::MAX as usize + 1).is_err()); -} - -#[test] -#[cfg_attr(miri, ignore)] // Miri does not support signalling OOM -#[cfg_attr(target_os = "android", ignore)] // Android used in CI has a broken dlmalloc -fn test_try_reserve() { - // These are the interesting cases: - // * exactly isize::MAX should never trigger a CapacityOverflow (can be OOM) - // * > isize::MAX should always fail - // * On 16/32-bit should CapacityOverflow - // * On 64-bit should OOM - // * overflow may trigger when adding `len` to `cap` (in number of elements) - // * overflow may trigger when multiplying `new_cap` by size_of:: (to get bytes) - - const MAX_CAP: usize = isize::MAX as usize; - const MAX_USIZE: usize = usize::MAX; - - { - // Note: basic stuff is checked by test_reserve - let mut empty_bytes: Vec = Vec::new(); - - // Check isize::MAX doesn't count as an overflow - if let Err(CapacityOverflow) = empty_bytes.try_reserve(MAX_CAP).map_err(|e| e.kind()) { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - // Play it again, frank! (just to be sure) - if let Err(CapacityOverflow) = empty_bytes.try_reserve(MAX_CAP).map_err(|e| e.kind()) { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - - // Check isize::MAX + 1 does count as overflow - assert_matches!( - empty_bytes.try_reserve(MAX_CAP + 1).map_err(|e| e.kind()), - Err(CapacityOverflow), - "isize::MAX + 1 should trigger an overflow!" - ); - - // Check usize::MAX does count as overflow - assert_matches!( - empty_bytes.try_reserve(MAX_USIZE).map_err(|e| e.kind()), - Err(CapacityOverflow), - "usize::MAX should trigger an overflow!" - ); - } - - { - // Same basic idea, but with non-zero len - let mut ten_bytes: Vec = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; - - if let Err(CapacityOverflow) = ten_bytes.try_reserve(MAX_CAP - 10).map_err(|e| e.kind()) { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - if let Err(CapacityOverflow) = ten_bytes.try_reserve(MAX_CAP - 10).map_err(|e| e.kind()) { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - - assert_matches!( - ten_bytes.try_reserve(MAX_CAP - 9).map_err(|e| e.kind()), - Err(CapacityOverflow), - "isize::MAX + 1 should trigger an overflow!" - ); - - // Should always overflow in the add-to-len - assert_matches!( - ten_bytes.try_reserve(MAX_USIZE).map_err(|e| e.kind()), - Err(CapacityOverflow), - "usize::MAX should trigger an overflow!" - ); - } - - { - // Same basic idea, but with interesting type size - let mut ten_u32s: Vec = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; - - if let Err(CapacityOverflow) = ten_u32s.try_reserve(MAX_CAP / 4 - 10).map_err(|e| e.kind()) - { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - if let Err(CapacityOverflow) = ten_u32s.try_reserve(MAX_CAP / 4 - 10).map_err(|e| e.kind()) - { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - - assert_matches!( - ten_u32s.try_reserve(MAX_CAP / 4 - 9).map_err(|e| e.kind()), - Err(CapacityOverflow), - "isize::MAX + 1 should trigger an overflow!" - ); - - // Should fail in the mul-by-size - assert_matches!( - ten_u32s.try_reserve(MAX_USIZE - 20).map_err(|e| e.kind()), - Err(CapacityOverflow), - "usize::MAX should trigger an overflow!" - ); - } -} - -#[test] -#[cfg_attr(miri, ignore)] // Miri does not support signalling OOM -#[cfg_attr(target_os = "android", ignore)] // Android used in CI has a broken dlmalloc -fn test_try_reserve_exact() { - // This is exactly the same as test_try_reserve with the method changed. - // See that test for comments. - - const MAX_CAP: usize = isize::MAX as usize; - const MAX_USIZE: usize = usize::MAX; - - { - let mut empty_bytes: Vec = Vec::new(); - - if let Err(CapacityOverflow) = empty_bytes.try_reserve_exact(MAX_CAP).map_err(|e| e.kind()) - { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - if let Err(CapacityOverflow) = empty_bytes.try_reserve_exact(MAX_CAP).map_err(|e| e.kind()) - { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - - assert_matches!( - empty_bytes.try_reserve_exact(MAX_CAP + 1).map_err(|e| e.kind()), - Err(CapacityOverflow), - "isize::MAX + 1 should trigger an overflow!" - ); - - assert_matches!( - empty_bytes.try_reserve_exact(MAX_USIZE).map_err(|e| e.kind()), - Err(CapacityOverflow), - "usize::MAX should trigger an overflow!" - ); - } - - { - let mut ten_bytes: Vec = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; - - if let Err(CapacityOverflow) = - ten_bytes.try_reserve_exact(MAX_CAP - 10).map_err(|e| e.kind()) - { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - if let Err(CapacityOverflow) = - ten_bytes.try_reserve_exact(MAX_CAP - 10).map_err(|e| e.kind()) - { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - - assert_matches!( - ten_bytes.try_reserve_exact(MAX_CAP - 9).map_err(|e| e.kind()), - Err(CapacityOverflow), - "isize::MAX + 1 should trigger an overflow!" - ); - - assert_matches!( - ten_bytes.try_reserve_exact(MAX_USIZE).map_err(|e| e.kind()), - Err(CapacityOverflow), - "usize::MAX should trigger an overflow!" - ); - } - - { - let mut ten_u32s: Vec = vec![1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; - - if let Err(CapacityOverflow) = - ten_u32s.try_reserve_exact(MAX_CAP / 4 - 10).map_err(|e| e.kind()) - { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - if let Err(CapacityOverflow) = - ten_u32s.try_reserve_exact(MAX_CAP / 4 - 10).map_err(|e| e.kind()) - { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - - assert_matches!( - ten_u32s.try_reserve_exact(MAX_CAP / 4 - 9).map_err(|e| e.kind()), - Err(CapacityOverflow), - "isize::MAX + 1 should trigger an overflow!" - ); - - assert_matches!( - ten_u32s.try_reserve_exact(MAX_USIZE - 20).map_err(|e| e.kind()), - Err(CapacityOverflow), - "usize::MAX should trigger an overflow!" - ); - } -} - -#[test] -fn test_stable_pointers() { - /// Pull an element from the iterator, then drop it. - /// Useful to cover both the `next` and `drop` paths of an iterator. - fn next_then_drop(mut i: I) { - i.next().unwrap(); - drop(i); - } - - // Test that, if we reserved enough space, adding and removing elements does not - // invalidate references into the vector (such as `v0`). This test also - // runs in Miri, which would detect such problems. - // Note that this test does *not* constitute a stable guarantee that all these functions do not - // reallocate! Only what is explicitly documented at - // is stably guaranteed. - let mut v = Vec::with_capacity(128); - v.push(13); - - // Laundering the lifetime -- we take care that `v` does not reallocate, so that's okay. - let v0 = &mut v[0]; - let v0 = unsafe { &mut *(v0 as *mut _) }; - // Now do a bunch of things and occasionally use `v0` again to assert it is still valid. - - // Pushing/inserting and popping/removing - v.push(1); - v.push(2); - v.insert(1, 1); - assert_eq!(*v0, 13); - v.remove(1); - v.pop().unwrap(); - assert_eq!(*v0, 13); - v.push(1); - v.swap_remove(1); - assert_eq!(v.len(), 2); - v.swap_remove(1); // swap_remove the last element - assert_eq!(*v0, 13); - - // Appending - v.append(&mut vec![27, 19]); - assert_eq!(*v0, 13); - - // Extending - v.extend_from_slice(&[1, 2]); - v.extend(&[1, 2]); // `slice::Iter` (with `T: Copy`) specialization - v.extend(vec![2, 3]); // `vec::IntoIter` specialization - v.extend(std::iter::once(3)); // `TrustedLen` specialization - v.extend(std::iter::empty::()); // `TrustedLen` specialization with empty iterator - v.extend(std::iter::once(3).filter(|_| true)); // base case - v.extend(std::iter::once(&3)); // `cloned` specialization - assert_eq!(*v0, 13); - - // Truncation - v.truncate(2); - assert_eq!(*v0, 13); - - // Resizing - v.resize_with(v.len() + 10, || 42); - assert_eq!(*v0, 13); - v.resize_with(2, || panic!()); - assert_eq!(*v0, 13); - - // No-op reservation - v.reserve(32); - v.reserve_exact(32); - assert_eq!(*v0, 13); - - // Partial draining - v.resize_with(10, || 42); - next_then_drop(v.drain(5..)); - assert_eq!(*v0, 13); - - // Splicing - v.resize_with(10, || 42); - next_then_drop(v.splice(5.., vec![1, 2, 3, 4, 5])); // empty tail after range - assert_eq!(*v0, 13); - next_then_drop(v.splice(5..8, vec![1])); // replacement is smaller than original range - assert_eq!(*v0, 13); - next_then_drop(v.splice(5..6, [1; 10].into_iter().filter(|_| true))); // lower bound not exact - assert_eq!(*v0, 13); - - // spare_capacity_mut - v.spare_capacity_mut(); - assert_eq!(*v0, 13); - - // Smoke test that would fire even outside Miri if an actual relocation happened. - // Also ensures the pointer is still writeable after all this. - *v0 -= 13; - assert_eq!(v[0], 0); -} - -// https://github.com/rust-lang/rust/pull/49496 introduced specialization based on: -// -// ``` -// unsafe impl IsZero for *mut T { -// fn is_zero(&self) -> bool { -// (*self).is_null() -// } -// } -// ``` -// -// … to call `RawVec::with_capacity_zeroed` for creating `Vec<*mut T>`, -// which is incorrect for fat pointers since `<*mut T>::is_null` only looks at the data component. -// That is, a fat pointer can be “null” without being made entirely of zero bits. -#[test] -fn vec_macro_repeating_null_raw_fat_pointer() { - let raw_dyn = &mut (|| ()) as &mut dyn Fn() as *mut dyn Fn(); - let vtable = dbg!(ptr_metadata(raw_dyn)); - let null_raw_dyn = ptr_from_raw_parts(std::ptr::null_mut(), vtable); - assert!(null_raw_dyn.is_null()); - - let vec = vec![null_raw_dyn; 1]; - dbg!(ptr_metadata(vec[0])); - assert!(std::ptr::eq(vec[0], null_raw_dyn)); - - // Polyfill for https://github.com/rust-lang/rfcs/pull/2580 - - fn ptr_metadata(ptr: *mut dyn Fn()) -> *mut () { - unsafe { std::mem::transmute::<*mut dyn Fn(), DynRepr>(ptr).vtable } - } - - fn ptr_from_raw_parts(data: *mut (), vtable: *mut ()) -> *mut dyn Fn() { - unsafe { std::mem::transmute::(DynRepr { data, vtable }) } - } - - #[repr(C)] - struct DynRepr { - data: *mut (), - vtable: *mut (), - } -} - -// This test will likely fail if you change the capacities used in -// `RawVec::grow_amortized`. -#[test] -fn test_push_growth_strategy() { - // If the element size is 1, we jump from 0 to 8, then double. - { - let mut v1: Vec = vec![]; - assert_eq!(v1.capacity(), 0); - - for _ in 0..8 { - v1.push(0); - assert_eq!(v1.capacity(), 8); - } - - for _ in 8..16 { - v1.push(0); - assert_eq!(v1.capacity(), 16); - } - - for _ in 16..32 { - v1.push(0); - assert_eq!(v1.capacity(), 32); - } - - for _ in 32..64 { - v1.push(0); - assert_eq!(v1.capacity(), 64); - } - } - - // If the element size is 2..=1024, we jump from 0 to 4, then double. - { - let mut v2: Vec = vec![]; - let mut v1024: Vec<[u8; 1024]> = vec![]; - assert_eq!(v2.capacity(), 0); - assert_eq!(v1024.capacity(), 0); - - for _ in 0..4 { - v2.push(0); - v1024.push([0; 1024]); - assert_eq!(v2.capacity(), 4); - assert_eq!(v1024.capacity(), 4); - } - - for _ in 4..8 { - v2.push(0); - v1024.push([0; 1024]); - assert_eq!(v2.capacity(), 8); - assert_eq!(v1024.capacity(), 8); - } - - for _ in 8..16 { - v2.push(0); - v1024.push([0; 1024]); - assert_eq!(v2.capacity(), 16); - assert_eq!(v1024.capacity(), 16); - } - - for _ in 16..32 { - v2.push(0); - v1024.push([0; 1024]); - assert_eq!(v2.capacity(), 32); - assert_eq!(v1024.capacity(), 32); - } - - for _ in 32..64 { - v2.push(0); - v1024.push([0; 1024]); - assert_eq!(v2.capacity(), 64); - assert_eq!(v1024.capacity(), 64); - } - } - - // If the element size is > 1024, we jump from 0 to 1, then double. - { - let mut v1025: Vec<[u8; 1025]> = vec![]; - assert_eq!(v1025.capacity(), 0); - - for _ in 0..1 { - v1025.push([0; 1025]); - assert_eq!(v1025.capacity(), 1); - } - - for _ in 1..2 { - v1025.push([0; 1025]); - assert_eq!(v1025.capacity(), 2); - } - - for _ in 2..4 { - v1025.push([0; 1025]); - assert_eq!(v1025.capacity(), 4); - } - - for _ in 4..8 { - v1025.push([0; 1025]); - assert_eq!(v1025.capacity(), 8); - } - - for _ in 8..16 { - v1025.push([0; 1025]); - assert_eq!(v1025.capacity(), 16); - } - - for _ in 16..32 { - v1025.push([0; 1025]); - assert_eq!(v1025.capacity(), 32); - } - - for _ in 32..64 { - v1025.push([0; 1025]); - assert_eq!(v1025.capacity(), 64); - } - } -} - -macro_rules! generate_assert_eq_vec_and_prim { - ($name:ident<$B:ident>($type:ty)) => { - fn $name + Debug, $B: Debug>(a: Vec, b: $type) { - assert!(a == b); - assert_eq!(a, b); - } - }; -} - -generate_assert_eq_vec_and_prim! { assert_eq_vec_and_slice (&[B]) } -generate_assert_eq_vec_and_prim! { assert_eq_vec_and_array_3([B; 3]) } - -#[test] -fn partialeq_vec_and_prim() { - assert_eq_vec_and_slice(vec![1, 2, 3], &[1, 2, 3]); - assert_eq_vec_and_array_3(vec![1, 2, 3], [1, 2, 3]); -} - -macro_rules! assert_partial_eq_valid { - ($a2:expr, $a3:expr; $b2:expr, $b3: expr) => { - assert!($a2 == $b2); - assert!($a2 != $b3); - assert!($a3 != $b2); - assert!($a3 == $b3); - assert_eq!($a2, $b2); - assert_ne!($a2, $b3); - assert_ne!($a3, $b2); - assert_eq!($a3, $b3); - }; -} - -#[test] -fn partialeq_vec_full() { - let vec2: Vec<_> = vec![1, 2]; - let vec3: Vec<_> = vec![1, 2, 3]; - let slice2: &[_] = &[1, 2]; - let slice3: &[_] = &[1, 2, 3]; - let slicemut2: &[_] = &mut [1, 2]; - let slicemut3: &[_] = &mut [1, 2, 3]; - let array2: [_; 2] = [1, 2]; - let array3: [_; 3] = [1, 2, 3]; - let arrayref2: &[_; 2] = &[1, 2]; - let arrayref3: &[_; 3] = &[1, 2, 3]; - - assert_partial_eq_valid!(vec2,vec3; vec2,vec3); - assert_partial_eq_valid!(vec2,vec3; slice2,slice3); - assert_partial_eq_valid!(vec2,vec3; slicemut2,slicemut3); - assert_partial_eq_valid!(slice2,slice3; vec2,vec3); - assert_partial_eq_valid!(slicemut2,slicemut3; vec2,vec3); - assert_partial_eq_valid!(vec2,vec3; array2,array3); - assert_partial_eq_valid!(vec2,vec3; arrayref2,arrayref3); - assert_partial_eq_valid!(vec2,vec3; arrayref2[..],arrayref3[..]); -} - -#[test] -fn test_vec_cycle() { - #[derive(Debug)] - struct C<'a> { - v: Vec>>>, - } - - impl<'a> C<'a> { - fn new() -> C<'a> { - C { v: Vec::new() } - } - } - - let mut c1 = C::new(); - let mut c2 = C::new(); - let mut c3 = C::new(); - - // Push - c1.v.push(Cell::new(None)); - c1.v.push(Cell::new(None)); - - c2.v.push(Cell::new(None)); - c2.v.push(Cell::new(None)); - - c3.v.push(Cell::new(None)); - c3.v.push(Cell::new(None)); - - // Set - c1.v[0].set(Some(&c2)); - c1.v[1].set(Some(&c3)); - - c2.v[0].set(Some(&c2)); - c2.v[1].set(Some(&c3)); - - c3.v[0].set(Some(&c1)); - c3.v[1].set(Some(&c2)); -} - -#[test] -fn test_vec_cycle_wrapped() { - struct Refs<'a> { - v: Vec>>>, - } - - struct C<'a> { - refs: Refs<'a>, - } - - impl<'a> Refs<'a> { - fn new() -> Refs<'a> { - Refs { v: Vec::new() } - } - } - - impl<'a> C<'a> { - fn new() -> C<'a> { - C { refs: Refs::new() } - } - } - - let mut c1 = C::new(); - let mut c2 = C::new(); - let mut c3 = C::new(); - - c1.refs.v.push(Cell::new(None)); - c1.refs.v.push(Cell::new(None)); - c2.refs.v.push(Cell::new(None)); - c2.refs.v.push(Cell::new(None)); - c3.refs.v.push(Cell::new(None)); - c3.refs.v.push(Cell::new(None)); - - c1.refs.v[0].set(Some(&c2)); - c1.refs.v[1].set(Some(&c3)); - c2.refs.v[0].set(Some(&c2)); - c2.refs.v[1].set(Some(&c3)); - c3.refs.v[0].set(Some(&c1)); - c3.refs.v[1].set(Some(&c2)); -} - -#[test] -fn test_zero_sized_capacity() { - for len in [0, 1, 2, 4, 8, 16, 32, 64, 128, 256] { - let v = Vec::<()>::with_capacity(len); - assert_eq!(v.len(), 0); - assert_eq!(v.capacity(), usize::MAX); - } -} - -#[test] -fn test_zero_sized_vec_push() { - const N: usize = 8; - - for len in 0..N { - let mut tester = Vec::with_capacity(len); - assert_eq!(tester.len(), 0); - assert!(tester.capacity() >= len); - for _ in 0..len { - tester.push(()); - } - assert_eq!(tester.len(), len); - assert_eq!(tester.iter().count(), len); - tester.clear(); - } -} - -#[test] -fn test_vec_macro_repeat() { - assert_eq!(vec![1; 3], vec![1, 1, 1]); - assert_eq!(vec![1; 2], vec![1, 1]); - assert_eq!(vec![1; 1], vec![1]); - assert_eq!(vec![1; 0], vec![]); - - // from_elem syntax (see RFC 832) - let el = Box::new(1); - let n = 3; - assert_eq!(vec![el; n], vec![Box::new(1), Box::new(1), Box::new(1)]); -} - -#[test] -fn test_vec_swap() { - let mut a: Vec = vec![0, 1, 2, 3, 4, 5, 6]; - a.swap(2, 4); - assert_eq!(a[2], 4); - assert_eq!(a[4], 2); - let mut n = 42; - swap(&mut n, &mut a[0]); - assert_eq!(a[0], 42); - assert_eq!(n, 0); -} - -#[test] -fn test_extend_from_within_spec() { - #[derive(Copy)] - struct CopyOnly; - - impl Clone for CopyOnly { - fn clone(&self) -> Self { - panic!("extend_from_within must use specialization on copy"); - } - } - - vec![CopyOnly, CopyOnly].extend_from_within(..); -} - -#[test] -fn test_extend_from_within_clone() { - let mut v = vec![String::from("sssss"), String::from("12334567890"), String::from("c")]; - v.extend_from_within(1..); - - assert_eq!(v, ["sssss", "12334567890", "c", "12334567890", "c"]); -} - -#[test] -fn test_extend_from_within_complete_rande() { - let mut v = vec![0, 1, 2, 3]; - v.extend_from_within(..); - - assert_eq!(v, [0, 1, 2, 3, 0, 1, 2, 3]); -} - -#[test] -fn test_extend_from_within_empty_rande() { - let mut v = vec![0, 1, 2, 3]; - v.extend_from_within(1..1); - - assert_eq!(v, [0, 1, 2, 3]); -} - -#[test] -#[should_panic] -fn test_extend_from_within_out_of_rande() { - let mut v = vec![0, 1]; - v.extend_from_within(..3); -} - -#[test] -fn test_extend_from_within_zst() { - let mut v = vec![(); 8]; - v.extend_from_within(3..7); - - assert_eq!(v, [(); 12]); -} - -#[test] -fn test_extend_from_within_empty_vec() { - let mut v = Vec::::new(); - v.extend_from_within(..); - - assert_eq!(v, []); -} - -#[test] -fn test_extend_from_within() { - let mut v = vec![String::from("a"), String::from("b"), String::from("c")]; - v.extend_from_within(1..=2); - v.extend_from_within(..=1); - - assert_eq!(v, ["a", "b", "c", "b", "c", "a", "b"]); -} - -#[test] -fn test_vec_dedup_by() { - let mut vec: Vec = vec![1, -1, 2, 3, 1, -5, 5, -2, 2]; - - vec.dedup_by(|a, b| a.abs() == b.abs()); - - assert_eq!(vec, [1, 2, 3, 1, -5, -2]); -} - -#[test] -fn test_vec_dedup_empty() { - let mut vec: Vec = Vec::new(); - - vec.dedup(); - - assert_eq!(vec, []); -} - -#[test] -fn test_vec_dedup_one() { - let mut vec = vec![12i32]; - - vec.dedup(); - - assert_eq!(vec, [12]); -} - -#[test] -fn test_vec_dedup_multiple_ident() { - let mut vec = vec![12, 12, 12, 12, 12, 11, 11, 11, 11, 11, 11]; - - vec.dedup(); - - assert_eq!(vec, [12, 11]); -} - -#[test] -fn test_vec_dedup_partialeq() { - #[derive(Debug)] - struct Foo(i32, #[allow(dead_code)] i32); - - impl PartialEq for Foo { - fn eq(&self, other: &Foo) -> bool { - self.0 == other.0 - } - } - - let mut vec = vec![Foo(0, 1), Foo(0, 5), Foo(1, 7), Foo(1, 9)]; - - vec.dedup(); - assert_eq!(vec, [Foo(0, 1), Foo(1, 7)]); -} - -#[test] -fn test_vec_dedup() { - let mut vec: Vec = Vec::with_capacity(8); - let mut template = vec.clone(); - - for x in 0u8..255u8 { - vec.clear(); - template.clear(); - - let iter = (0..8).map(move |bit| (x >> bit) & 1 == 1); - vec.extend(iter); - template.extend_from_slice(&vec); - - let (dedup, _) = template.partition_dedup(); - vec.dedup(); - - assert_eq!(vec, dedup); - } -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_vec_dedup_panicking() { - #[derive(Debug)] - struct Panic<'a> { - drop_counter: &'a Cell, - value: bool, - index: usize, - } - - impl<'a> PartialEq for Panic<'a> { - fn eq(&self, other: &Self) -> bool { - self.value == other.value - } - } - - impl<'a> Drop for Panic<'a> { - fn drop(&mut self) { - self.drop_counter.set(self.drop_counter.get() + 1); - if !std::thread::panicking() { - assert!(self.index != 4); - } - } - } - - let drop_counter = &Cell::new(0); - let expected = [ - Panic { drop_counter, value: false, index: 0 }, - Panic { drop_counter, value: false, index: 5 }, - Panic { drop_counter, value: true, index: 6 }, - Panic { drop_counter, value: true, index: 7 }, - ]; - let mut vec = vec![ - Panic { drop_counter, value: false, index: 0 }, - // these elements get deduplicated - Panic { drop_counter, value: false, index: 1 }, - Panic { drop_counter, value: false, index: 2 }, - Panic { drop_counter, value: false, index: 3 }, - Panic { drop_counter, value: false, index: 4 }, - // here it panics while dropping the item with index==4 - Panic { drop_counter, value: false, index: 5 }, - Panic { drop_counter, value: true, index: 6 }, - Panic { drop_counter, value: true, index: 7 }, - ]; - - let _ = catch_unwind(AssertUnwindSafe(|| vec.dedup())).unwrap_err(); - - assert_eq!(drop_counter.get(), 4); - - let ok = vec.iter().zip(expected.iter()).all(|(x, y)| x.index == y.index); - - if !ok { - panic!("expected: {expected:?}\ngot: {vec:?}\n"); - } -} - -// Regression test for issue #82533 -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_extend_from_within_panicking_clone() { - struct Panic<'dc> { - drop_count: &'dc AtomicU32, - aaaaa: bool, - } - - impl Clone for Panic<'_> { - fn clone(&self) -> Self { - if self.aaaaa { - panic!("panic! at the clone"); - } - - Self { ..*self } - } - } - - impl Drop for Panic<'_> { - fn drop(&mut self) { - self.drop_count.fetch_add(1, Ordering::SeqCst); - } - } - - let count = core::sync::atomic::AtomicU32::new(0); - let mut vec = vec![ - Panic { drop_count: &count, aaaaa: false }, - Panic { drop_count: &count, aaaaa: true }, - Panic { drop_count: &count, aaaaa: false }, - ]; - - // This should clone&append one Panic{..} at the end, and then panic while - // cloning second Panic{..}. This means that `Panic::drop` should be called - // 4 times (3 for items already in vector, 1 for just appended). - // - // Previously just appended item was leaked, making drop_count = 3, instead of 4. - std::panic::catch_unwind(move || vec.extend_from_within(..)).unwrap_err(); - - assert_eq!(count.load(Ordering::SeqCst), 4); -} - -#[test] -#[should_panic = "vec len overflow"] -fn test_into_flattened_size_overflow() { - let v = vec![[(); usize::MAX]; 2]; - let _ = v.into_flattened(); -} - -#[test] -fn test_box_zero_allocator() { - use core::{alloc::AllocError, cell::RefCell}; - use std::collections::HashSet; - - // Track ZST allocations and ensure that they all have a matching free. - struct ZstTracker { - state: RefCell<(HashSet, usize)>, - } - unsafe impl Allocator for ZstTracker { - fn allocate(&self, layout: Layout) -> Result, AllocError> { - let ptr = if layout.size() == 0 { - let mut state = self.state.borrow_mut(); - let addr = state.1; - assert!(state.0.insert(addr)); - state.1 += 1; - std::println!("allocating {addr}"); - std::ptr::without_provenance_mut(addr) - } else { - unsafe { std::alloc::alloc(layout) } - }; - Ok(NonNull::slice_from_raw_parts(NonNull::new(ptr).ok_or(AllocError)?, layout.size())) - } - - unsafe fn deallocate(&self, ptr: NonNull, layout: Layout) { - if layout.size() == 0 { - let addr = ptr.as_ptr() as usize; - let mut state = self.state.borrow_mut(); - std::println!("freeing {addr}"); - assert!(state.0.remove(&addr), "ZST free that wasn't allocated"); - } else { - unsafe { std::alloc::dealloc(ptr.as_ptr(), layout) } - } - } - } - - // Start the state at 100 to avoid returning null pointers. - let alloc = ZstTracker { state: RefCell::new((HashSet::new(), 100)) }; - - // Ensure that unsizing retains the same behavior. - { - let b1: Box<[u8; 0], &ZstTracker> = Box::new_in([], &alloc); - let b2: Box<[u8], &ZstTracker> = b1.clone(); - let _b3: Box<[u8], &ZstTracker> = b2.clone(); - } - - // Ensure that shrinking doesn't leak a ZST allocation. - { - let mut v1: Vec = Vec::with_capacity_in(100, &alloc); - v1.shrink_to_fit(); - } - - // Ensure that conversion to/from vec works. - { - let v1: Vec<(), &ZstTracker> = Vec::with_capacity_in(100, &alloc); - let _b1: Box<[()], &ZstTracker> = v1.into_boxed_slice(); - let b2: Box<[()], &ZstTracker> = Box::new_in([(), (), ()], &alloc); - let _v2: Vec<(), &ZstTracker> = b2.into(); - } - - // Ensure all ZSTs have been freed. - assert!(alloc.state.borrow().0.is_empty()); -} - -#[test] -fn test_vec_from_array_ref() { - assert_eq!(Vec::from(&[1, 2, 3]), vec![1, 2, 3]); -} - -#[test] -fn test_vec_from_array_mut_ref() { - assert_eq!(Vec::from(&mut [1, 2, 3]), vec![1, 2, 3]); -} - -#[test] -fn test_pop_if() { - let mut v = vec![1, 2, 3, 4]; - let pred = |x: &mut i32| *x % 2 == 0; - - assert_eq!(v.pop_if(pred), Some(4)); - assert_eq!(v, [1, 2, 3]); - - assert_eq!(v.pop_if(pred), None); - assert_eq!(v, [1, 2, 3]); -} - -#[test] -fn test_pop_if_empty() { - let mut v = Vec::::new(); - assert_eq!(v.pop_if(|_| true), None); - assert!(v.is_empty()); -} - -#[test] -fn test_pop_if_mutates() { - let mut v = vec![1]; - let pred = |x: &mut i32| { - *x += 1; - false - }; - assert_eq!(v.pop_if(pred), None); - assert_eq!(v, [2]); -} - -/// This assortment of tests, in combination with miri, verifies we handle UB on fishy arguments -/// in the stdlib. Draining and extending the allocation are fairly well-tested earlier, but -/// `vec.insert(usize::MAX, val)` once slipped by! -/// -/// All code that manipulates the collection types should be tested with "trivially wrong" args. -#[test] -fn max_dont_panic() { - let mut v = vec![0]; - let _ = v.get(usize::MAX); - v.shrink_to(usize::MAX); - v.truncate(usize::MAX); -} - -#[test] -#[should_panic] -fn max_insert() { - let mut v = vec![0]; - v.insert(usize::MAX, 1); -} - -#[test] -#[should_panic] -fn max_remove() { - let mut v = vec![0]; - v.remove(usize::MAX); -} - -#[test] -#[should_panic] -fn max_splice() { - let mut v = vec![0]; - v.splice(usize::MAX.., core::iter::once(1)); -} - -#[test] -#[should_panic] -fn max_swap_remove() { - let mut v = vec![0]; - v.swap_remove(usize::MAX); -} diff --git a/library/alloc/tests/vec_deque.rs b/library/alloc/tests/vec_deque.rs deleted file mode 100644 index cea5de4dd5984..0000000000000 --- a/library/alloc/tests/vec_deque.rs +++ /dev/null @@ -1,1825 +0,0 @@ -use core::num::NonZero; -use std::assert_matches::assert_matches; -use std::collections::TryReserveErrorKind::*; -use std::collections::{vec_deque::Drain, VecDeque}; -use std::fmt::Debug; -use std::ops::Bound::*; -use std::panic::{catch_unwind, AssertUnwindSafe}; - -use crate::hash; - -use Taggy::*; -use Taggypar::*; - -#[test] -fn test_simple() { - let mut d = VecDeque::new(); - assert_eq!(d.len(), 0); - d.push_front(17); - d.push_front(42); - d.push_back(137); - assert_eq!(d.len(), 3); - d.push_back(137); - assert_eq!(d.len(), 4); - assert_eq!(*d.front().unwrap(), 42); - assert_eq!(*d.back().unwrap(), 137); - let mut i = d.pop_front(); - assert_eq!(i, Some(42)); - i = d.pop_back(); - assert_eq!(i, Some(137)); - i = d.pop_back(); - assert_eq!(i, Some(137)); - i = d.pop_back(); - assert_eq!(i, Some(17)); - assert_eq!(d.len(), 0); - d.push_back(3); - assert_eq!(d.len(), 1); - d.push_front(2); - assert_eq!(d.len(), 2); - d.push_back(4); - assert_eq!(d.len(), 3); - d.push_front(1); - assert_eq!(d.len(), 4); - assert_eq!(d[0], 1); - assert_eq!(d[1], 2); - assert_eq!(d[2], 3); - assert_eq!(d[3], 4); -} - -fn test_parameterized(a: T, b: T, c: T, d: T) { - let mut deq = VecDeque::new(); - assert_eq!(deq.len(), 0); - deq.push_front(a.clone()); - deq.push_front(b.clone()); - deq.push_back(c.clone()); - assert_eq!(deq.len(), 3); - deq.push_back(d.clone()); - assert_eq!(deq.len(), 4); - assert_eq!((*deq.front().unwrap()).clone(), b.clone()); - assert_eq!((*deq.back().unwrap()).clone(), d.clone()); - assert_eq!(deq.pop_front().unwrap(), b.clone()); - assert_eq!(deq.pop_back().unwrap(), d.clone()); - assert_eq!(deq.pop_back().unwrap(), c.clone()); - assert_eq!(deq.pop_back().unwrap(), a.clone()); - assert_eq!(deq.len(), 0); - deq.push_back(c.clone()); - assert_eq!(deq.len(), 1); - deq.push_front(b.clone()); - assert_eq!(deq.len(), 2); - deq.push_back(d.clone()); - assert_eq!(deq.len(), 3); - deq.push_front(a.clone()); - assert_eq!(deq.len(), 4); - assert_eq!(deq[0].clone(), a.clone()); - assert_eq!(deq[1].clone(), b.clone()); - assert_eq!(deq[2].clone(), c.clone()); - assert_eq!(deq[3].clone(), d.clone()); -} - -#[test] -fn test_push_front_grow() { - let mut deq = VecDeque::new(); - for i in 0..66 { - deq.push_front(i); - } - assert_eq!(deq.len(), 66); - - for i in 0..66 { - assert_eq!(deq[i], 65 - i); - } - - let mut deq = VecDeque::new(); - for i in 0..66 { - deq.push_back(i); - } - - for i in 0..66 { - assert_eq!(deq[i], i); - } -} - -#[test] -fn test_index() { - let mut deq = VecDeque::new(); - for i in 1..4 { - deq.push_front(i); - } - assert_eq!(deq[1], 2); -} - -#[test] -#[should_panic] -fn test_index_out_of_bounds() { - let mut deq = VecDeque::new(); - for i in 1..4 { - deq.push_front(i); - } - deq[3]; -} - -#[test] -#[should_panic] -fn test_range_start_overflow() { - let deq = VecDeque::from(vec![1, 2, 3]); - deq.range((Included(0), Included(usize::MAX))); -} - -#[test] -#[should_panic] -fn test_range_end_overflow() { - let deq = VecDeque::from(vec![1, 2, 3]); - deq.range((Excluded(usize::MAX), Included(0))); -} - -#[derive(Clone, PartialEq, Debug)] -enum Taggy { - One(i32), - Two(i32, i32), - Three(i32, i32, i32), -} - -#[derive(Clone, PartialEq, Debug)] -enum Taggypar { - Onepar(T), - Twopar(T, T), - Threepar(T, T, T), -} - -#[derive(Clone, PartialEq, Debug)] -struct RecCy { - x: i32, - y: i32, - t: Taggy, -} - -#[test] -fn test_param_int() { - test_parameterized::(5, 72, 64, 175); -} - -#[test] -fn test_param_taggy() { - test_parameterized::(One(1), Two(1, 2), Three(1, 2, 3), Two(17, 42)); -} - -#[test] -fn test_param_taggypar() { - test_parameterized::>( - Onepar::(1), - Twopar::(1, 2), - Threepar::(1, 2, 3), - Twopar::(17, 42), - ); -} - -#[test] -fn test_param_reccy() { - let reccy1 = RecCy { x: 1, y: 2, t: One(1) }; - let reccy2 = RecCy { x: 345, y: 2, t: Two(1, 2) }; - let reccy3 = RecCy { x: 1, y: 777, t: Three(1, 2, 3) }; - let reccy4 = RecCy { x: 19, y: 252, t: Two(17, 42) }; - test_parameterized::(reccy1, reccy2, reccy3, reccy4); -} - -#[test] -fn test_with_capacity() { - let mut d = VecDeque::with_capacity(0); - d.push_back(1); - assert_eq!(d.len(), 1); - let mut d = VecDeque::with_capacity(50); - d.push_back(1); - assert_eq!(d.len(), 1); -} - -#[test] -fn test_with_capacity_non_power_two() { - let mut d3 = VecDeque::with_capacity(3); - d3.push_back(1); - - // X = None, | = lo - // [|1, X, X] - assert_eq!(d3.pop_front(), Some(1)); - // [X, |X, X] - assert_eq!(d3.front(), None); - - // [X, |3, X] - d3.push_back(3); - // [X, |3, 6] - d3.push_back(6); - // [X, X, |6] - assert_eq!(d3.pop_front(), Some(3)); - - // Pushing the lo past half way point to trigger - // the 'B' scenario for growth - // [9, X, |6] - d3.push_back(9); - // [9, 12, |6] - d3.push_back(12); - - d3.push_back(15); - // There used to be a bug here about how the - // VecDeque made growth assumptions about the - // underlying Vec which didn't hold and lead - // to corruption. - // (Vec grows to next power of two) - // good- [9, 12, 15, X, X, X, X, |6] - // bug- [15, 12, X, X, X, |6, X, X] - assert_eq!(d3.pop_front(), Some(6)); - - // Which leads us to the following state which - // would be a failure case. - // bug- [15, 12, X, X, X, X, |X, X] - assert_eq!(d3.front(), Some(&9)); -} - -#[test] -fn test_reserve_exact() { - let mut d = VecDeque::new(); - d.push_back(0); - d.reserve_exact(50); - assert!(d.capacity() >= 51); -} - -#[test] -fn test_reserve() { - let mut d = VecDeque::new(); - d.push_back(0); - d.reserve(50); - assert!(d.capacity() >= 51); -} - -#[test] -fn test_swap() { - let mut d: VecDeque<_> = (0..5).collect(); - d.pop_front(); - d.swap(0, 3); - assert_eq!(d.iter().cloned().collect::>(), [4, 2, 3, 1]); -} - -#[test] -fn test_iter() { - let mut d = VecDeque::new(); - assert_eq!(d.iter().next(), None); - assert_eq!(d.iter().size_hint(), (0, Some(0))); - - for i in 0..5 { - d.push_back(i); - } - { - let b: &[_] = &[&0, &1, &2, &3, &4]; - assert_eq!(d.iter().collect::>(), b); - } - - for i in 6..9 { - d.push_front(i); - } - { - let b: &[_] = &[&8, &7, &6, &0, &1, &2, &3, &4]; - assert_eq!(d.iter().collect::>(), b); - } - - let mut it = d.iter(); - let mut len = d.len(); - loop { - match it.next() { - None => break, - _ => { - len -= 1; - assert_eq!(it.size_hint(), (len, Some(len))) - } - } - } -} - -#[test] -fn test_rev_iter() { - let mut d = VecDeque::new(); - assert_eq!(d.iter().rev().next(), None); - - for i in 0..5 { - d.push_back(i); - } - { - let b: &[_] = &[&4, &3, &2, &1, &0]; - assert_eq!(d.iter().rev().collect::>(), b); - } - - for i in 6..9 { - d.push_front(i); - } - let b: &[_] = &[&4, &3, &2, &1, &0, &6, &7, &8]; - assert_eq!(d.iter().rev().collect::>(), b); -} - -#[test] -fn test_mut_rev_iter_wrap() { - let mut d = VecDeque::with_capacity(3); - assert!(d.iter_mut().rev().next().is_none()); - - d.push_back(1); - d.push_back(2); - d.push_back(3); - assert_eq!(d.pop_front(), Some(1)); - d.push_back(4); - - assert_eq!(d.iter_mut().rev().map(|x| *x).collect::>(), vec![4, 3, 2]); -} - -#[test] -fn test_mut_iter() { - let mut d = VecDeque::new(); - assert!(d.iter_mut().next().is_none()); - - for i in 0..3 { - d.push_front(i); - } - - for (i, elt) in d.iter_mut().enumerate() { - assert_eq!(*elt, 2 - i); - *elt = i; - } - - { - let mut it = d.iter_mut(); - assert_eq!(*it.next().unwrap(), 0); - assert_eq!(*it.next().unwrap(), 1); - assert_eq!(*it.next().unwrap(), 2); - assert!(it.next().is_none()); - } -} - -#[test] -fn test_mut_rev_iter() { - let mut d = VecDeque::new(); - assert!(d.iter_mut().rev().next().is_none()); - - for i in 0..3 { - d.push_front(i); - } - - for (i, elt) in d.iter_mut().rev().enumerate() { - assert_eq!(*elt, i); - *elt = i; - } - - { - let mut it = d.iter_mut().rev(); - assert_eq!(*it.next().unwrap(), 0); - assert_eq!(*it.next().unwrap(), 1); - assert_eq!(*it.next().unwrap(), 2); - assert!(it.next().is_none()); - } -} - -#[test] -fn test_into_iter() { - // Empty iter - { - let d: VecDeque = VecDeque::new(); - let mut iter = d.into_iter(); - - assert_eq!(iter.size_hint(), (0, Some(0))); - assert_eq!(iter.next(), None); - assert_eq!(iter.size_hint(), (0, Some(0))); - } - - // simple iter - { - let mut d = VecDeque::new(); - for i in 0..5 { - d.push_back(i); - } - - let b = vec![0, 1, 2, 3, 4]; - assert_eq!(d.into_iter().collect::>(), b); - } - - // wrapped iter - { - let mut d = VecDeque::new(); - for i in 0..5 { - d.push_back(i); - } - for i in 6..9 { - d.push_front(i); - } - - let b = vec![8, 7, 6, 0, 1, 2, 3, 4]; - assert_eq!(d.into_iter().collect::>(), b); - } - - // partially used - { - let mut d = VecDeque::new(); - for i in 0..5 { - d.push_back(i); - } - for i in 6..9 { - d.push_front(i); - } - - let mut it = d.into_iter(); - assert_eq!(it.size_hint(), (8, Some(8))); - assert_eq!(it.next(), Some(8)); - assert_eq!(it.size_hint(), (7, Some(7))); - assert_eq!(it.next_back(), Some(4)); - assert_eq!(it.size_hint(), (6, Some(6))); - assert_eq!(it.next(), Some(7)); - assert_eq!(it.size_hint(), (5, Some(5))); - } - - // advance_by - { - let mut d = VecDeque::new(); - for i in 0..=4 { - d.push_back(i); - } - for i in 6..=8 { - d.push_front(i); - } - - let mut it = d.into_iter(); - assert_eq!(it.advance_by(1), Ok(())); - assert_eq!(it.next(), Some(7)); - assert_eq!(it.advance_back_by(1), Ok(())); - assert_eq!(it.next_back(), Some(3)); - - let mut it = VecDeque::from(vec![1, 2, 3, 4, 5]).into_iter(); - assert_eq!(it.advance_by(10), Err(NonZero::new(5).unwrap())); - let mut it = VecDeque::from(vec![1, 2, 3, 4, 5]).into_iter(); - assert_eq!(it.advance_back_by(10), Err(NonZero::new(5).unwrap())); - } -} - -#[test] -fn test_drain() { - // Empty iter - { - let mut d: VecDeque = VecDeque::new(); - - { - let mut iter = d.drain(..); - - assert_eq!(iter.size_hint(), (0, Some(0))); - assert_eq!(iter.next(), None); - assert_eq!(iter.size_hint(), (0, Some(0))); - } - - assert!(d.is_empty()); - } - - // simple iter - { - let mut d = VecDeque::new(); - for i in 0..5 { - d.push_back(i); - } - - assert_eq!(d.drain(..).collect::>(), [0, 1, 2, 3, 4]); - assert!(d.is_empty()); - } - - // wrapped iter - { - let mut d = VecDeque::new(); - for i in 0..5 { - d.push_back(i); - } - for i in 6..9 { - d.push_front(i); - } - assert_eq!(d.drain(..).collect::>(), [8, 7, 6, 0, 1, 2, 3, 4]); - assert!(d.is_empty()); - } - - // partially used - { - let mut d: VecDeque<_> = VecDeque::new(); - for i in 0..5 { - d.push_back(i); - } - for i in 6..9 { - d.push_front(i); - } - - { - let mut it = d.drain(..); - assert_eq!(it.size_hint(), (8, Some(8))); - assert_eq!(it.next(), Some(8)); - assert_eq!(it.size_hint(), (7, Some(7))); - assert_eq!(it.next_back(), Some(4)); - assert_eq!(it.size_hint(), (6, Some(6))); - assert_eq!(it.next(), Some(7)); - assert_eq!(it.size_hint(), (5, Some(5))); - } - assert!(d.is_empty()); - } -} - -#[test] -fn test_from_iter() { - let v = vec![1, 2, 3, 4, 5, 6, 7]; - let deq: VecDeque<_> = v.iter().cloned().collect(); - let u: Vec<_> = deq.iter().cloned().collect(); - assert_eq!(u, v); - - let seq = (0..).step_by(2).take(256); - let deq: VecDeque<_> = seq.collect(); - for (i, &x) in deq.iter().enumerate() { - assert_eq!(2 * i, x); - } - assert_eq!(deq.len(), 256); -} - -#[test] -fn test_clone() { - let mut d = VecDeque::new(); - d.push_front(17); - d.push_front(42); - d.push_back(137); - d.push_back(137); - assert_eq!(d.len(), 4); - let mut e = d.clone(); - assert_eq!(e.len(), 4); - while !d.is_empty() { - assert_eq!(d.pop_back(), e.pop_back()); - } - assert_eq!(d.len(), 0); - assert_eq!(e.len(), 0); -} - -#[test] -fn test_eq() { - let mut d = VecDeque::new(); - assert!(d == VecDeque::with_capacity(0)); - d.push_front(137); - d.push_front(17); - d.push_front(42); - d.push_back(137); - let mut e = VecDeque::with_capacity(0); - e.push_back(42); - e.push_back(17); - e.push_back(137); - e.push_back(137); - assert!(&e == &d); - e.pop_back(); - e.push_back(0); - assert!(e != d); - e.clear(); - assert!(e == VecDeque::new()); -} - -#[test] -fn test_partial_eq_array() { - let d = VecDeque::::new(); - assert!(d == []); - - let mut d = VecDeque::new(); - d.push_front('a'); - assert!(d == ['a']); - - let mut d = VecDeque::new(); - d.push_back('a'); - assert!(d == ['a']); - - let mut d = VecDeque::new(); - d.push_back('a'); - d.push_back('b'); - assert!(d == ['a', 'b']); -} - -#[test] -fn test_hash() { - let mut x = VecDeque::new(); - let mut y = VecDeque::new(); - - x.push_back(1); - x.push_back(2); - x.push_back(3); - - y.push_back(0); - y.push_back(1); - y.pop_front(); - y.push_back(2); - y.push_back(3); - - assert!(hash(&x) == hash(&y)); -} - -#[test] -fn test_hash_after_rotation() { - // test that two deques hash equal even if elements are laid out differently - let len = 28; - let mut ring: VecDeque = (0..len as i32).collect(); - let orig = ring.clone(); - for _ in 0..ring.capacity() { - // shift values 1 step to the right by pop, sub one, push - ring.pop_front(); - for elt in &mut ring { - *elt -= 1; - } - ring.push_back(len - 1); - assert_eq!(hash(&orig), hash(&ring)); - assert_eq!(orig, ring); - assert_eq!(ring, orig); - } -} - -#[test] -fn test_eq_after_rotation() { - // test that two deques are equal even if elements are laid out differently - let len = 28; - let mut ring: VecDeque = (0..len as i32).collect(); - let mut shifted = ring.clone(); - for _ in 0..10 { - // shift values 1 step to the right by pop, sub one, push - ring.pop_front(); - for elt in &mut ring { - *elt -= 1; - } - ring.push_back(len - 1); - } - - // try every shift - for _ in 0..shifted.capacity() { - shifted.pop_front(); - for elt in &mut shifted { - *elt -= 1; - } - shifted.push_back(len - 1); - assert_eq!(shifted, ring); - assert_eq!(ring, shifted); - } -} - -#[test] -fn test_ord() { - let x = VecDeque::new(); - let mut y = VecDeque::new(); - y.push_back(1); - y.push_back(2); - y.push_back(3); - assert!(x < y); - assert!(y > x); - assert!(x <= x); - assert!(x >= x); -} - -#[test] -fn test_show() { - let ringbuf: VecDeque<_> = (0..10).collect(); - assert_eq!(format!("{ringbuf:?}"), "[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]"); - - let ringbuf: VecDeque<_> = vec!["just", "one", "test", "more"].iter().cloned().collect(); - assert_eq!(format!("{ringbuf:?}"), "[\"just\", \"one\", \"test\", \"more\"]"); -} - -#[test] -fn test_drop() { - static mut DROPS: i32 = 0; - struct Elem; - impl Drop for Elem { - fn drop(&mut self) { - unsafe { - DROPS += 1; - } - } - } - - let mut ring = VecDeque::new(); - ring.push_back(Elem); - ring.push_front(Elem); - ring.push_back(Elem); - ring.push_front(Elem); - drop(ring); - - assert_eq!(unsafe { DROPS }, 4); -} - -#[test] -fn test_drop_with_pop() { - static mut DROPS: i32 = 0; - struct Elem; - impl Drop for Elem { - fn drop(&mut self) { - unsafe { - DROPS += 1; - } - } - } - - let mut ring = VecDeque::new(); - ring.push_back(Elem); - ring.push_front(Elem); - ring.push_back(Elem); - ring.push_front(Elem); - - drop(ring.pop_back()); - drop(ring.pop_front()); - assert_eq!(unsafe { DROPS }, 2); - - drop(ring); - assert_eq!(unsafe { DROPS }, 4); -} - -#[test] -fn test_drop_clear() { - static mut DROPS: i32 = 0; - struct Elem; - impl Drop for Elem { - fn drop(&mut self) { - unsafe { - DROPS += 1; - } - } - } - - let mut ring = VecDeque::new(); - ring.push_back(Elem); - ring.push_front(Elem); - ring.push_back(Elem); - ring.push_front(Elem); - ring.clear(); - assert_eq!(unsafe { DROPS }, 4); - - drop(ring); - assert_eq!(unsafe { DROPS }, 4); -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_drop_panic() { - static mut DROPS: i32 = 0; - - struct D(bool); - - impl Drop for D { - fn drop(&mut self) { - unsafe { - DROPS += 1; - } - - if self.0 { - panic!("panic in `drop`"); - } - } - } - - let mut q = VecDeque::new(); - q.push_back(D(false)); - q.push_back(D(false)); - q.push_back(D(false)); - q.push_back(D(false)); - q.push_back(D(false)); - q.push_front(D(false)); - q.push_front(D(false)); - q.push_front(D(true)); - - catch_unwind(move || drop(q)).ok(); - - assert_eq!(unsafe { DROPS }, 8); -} - -#[test] -fn test_reserve_grow() { - // test growth path A - // [T o o H] -> [T o o H . . . . ] - let mut ring = VecDeque::with_capacity(4); - for i in 0..3 { - ring.push_back(i); - } - ring.reserve(7); - for i in 0..3 { - assert_eq!(ring.pop_front(), Some(i)); - } - - // test growth path B - // [H T o o] -> [. T o o H . . . ] - let mut ring = VecDeque::with_capacity(4); - for i in 0..1 { - ring.push_back(i); - assert_eq!(ring.pop_front(), Some(i)); - } - for i in 0..3 { - ring.push_back(i); - } - ring.reserve(7); - for i in 0..3 { - assert_eq!(ring.pop_front(), Some(i)); - } - - // test growth path C - // [o o H T] -> [o o H . . . . T ] - let mut ring = VecDeque::with_capacity(4); - for i in 0..3 { - ring.push_back(i); - assert_eq!(ring.pop_front(), Some(i)); - } - for i in 0..3 { - ring.push_back(i); - } - ring.reserve(7); - for i in 0..3 { - assert_eq!(ring.pop_front(), Some(i)); - } -} - -#[test] -fn test_get() { - let mut ring = VecDeque::new(); - ring.push_back(0); - assert_eq!(ring.get(0), Some(&0)); - assert_eq!(ring.get(1), None); - - ring.push_back(1); - assert_eq!(ring.get(0), Some(&0)); - assert_eq!(ring.get(1), Some(&1)); - assert_eq!(ring.get(2), None); - - ring.push_back(2); - assert_eq!(ring.get(0), Some(&0)); - assert_eq!(ring.get(1), Some(&1)); - assert_eq!(ring.get(2), Some(&2)); - assert_eq!(ring.get(3), None); - - assert_eq!(ring.pop_front(), Some(0)); - assert_eq!(ring.get(0), Some(&1)); - assert_eq!(ring.get(1), Some(&2)); - assert_eq!(ring.get(2), None); - - assert_eq!(ring.pop_front(), Some(1)); - assert_eq!(ring.get(0), Some(&2)); - assert_eq!(ring.get(1), None); - - assert_eq!(ring.pop_front(), Some(2)); - assert_eq!(ring.get(0), None); - assert_eq!(ring.get(1), None); -} - -#[test] -fn test_get_mut() { - let mut ring = VecDeque::new(); - for i in 0..3 { - ring.push_back(i); - } - - match ring.get_mut(1) { - Some(x) => *x = -1, - None => (), - }; - - assert_eq!(ring.get_mut(0), Some(&mut 0)); - assert_eq!(ring.get_mut(1), Some(&mut -1)); - assert_eq!(ring.get_mut(2), Some(&mut 2)); - assert_eq!(ring.get_mut(3), None); - - assert_eq!(ring.pop_front(), Some(0)); - assert_eq!(ring.get_mut(0), Some(&mut -1)); - assert_eq!(ring.get_mut(1), Some(&mut 2)); - assert_eq!(ring.get_mut(2), None); -} - -#[test] -fn test_front() { - let mut ring = VecDeque::new(); - ring.push_back(10); - ring.push_back(20); - assert_eq!(ring.front(), Some(&10)); - ring.pop_front(); - assert_eq!(ring.front(), Some(&20)); - ring.pop_front(); - assert_eq!(ring.front(), None); -} - -#[test] -fn test_as_slices() { - let mut ring: VecDeque = VecDeque::with_capacity(127); - let cap = ring.capacity() as i32; - let first = cap / 2; - let last = cap - first; - for i in 0..first { - ring.push_back(i); - - let (left, right) = ring.as_slices(); - let expected: Vec<_> = (0..=i).collect(); - assert_eq!(left, &expected[..]); - assert_eq!(right, []); - } - - for j in -last..0 { - ring.push_front(j); - let (left, right) = ring.as_slices(); - let expected_left: Vec<_> = (-last..=j).rev().collect(); - let expected_right: Vec<_> = (0..first).collect(); - assert_eq!(left, &expected_left[..]); - assert_eq!(right, &expected_right[..]); - } - - assert_eq!(ring.len() as i32, cap); - assert_eq!(ring.capacity() as i32, cap); -} - -#[test] -fn test_as_mut_slices() { - let mut ring: VecDeque = VecDeque::with_capacity(127); - let cap = ring.capacity() as i32; - let first = cap / 2; - let last = cap - first; - for i in 0..first { - ring.push_back(i); - - let (left, right) = ring.as_mut_slices(); - let expected: Vec<_> = (0..=i).collect(); - assert_eq!(left, &expected[..]); - assert_eq!(right, []); - } - - for j in -last..0 { - ring.push_front(j); - let (left, right) = ring.as_mut_slices(); - let expected_left: Vec<_> = (-last..=j).rev().collect(); - let expected_right: Vec<_> = (0..first).collect(); - assert_eq!(left, &expected_left[..]); - assert_eq!(right, &expected_right[..]); - } - - assert_eq!(ring.len() as i32, cap); - assert_eq!(ring.capacity() as i32, cap); -} - -#[test] -fn test_append() { - let mut a: VecDeque<_> = [1, 2, 3].into_iter().collect(); - let mut b: VecDeque<_> = [4, 5, 6].into_iter().collect(); - - // normal append - a.append(&mut b); - assert_eq!(a.iter().cloned().collect::>(), [1, 2, 3, 4, 5, 6]); - assert_eq!(b.iter().cloned().collect::>(), []); - - // append nothing to something - a.append(&mut b); - assert_eq!(a.iter().cloned().collect::>(), [1, 2, 3, 4, 5, 6]); - assert_eq!(b.iter().cloned().collect::>(), []); - - // append something to nothing - b.append(&mut a); - assert_eq!(b.iter().cloned().collect::>(), [1, 2, 3, 4, 5, 6]); - assert_eq!(a.iter().cloned().collect::>(), []); -} - -#[test] -fn test_append_permutations() { - fn construct_vec_deque( - push_back: usize, - pop_back: usize, - push_front: usize, - pop_front: usize, - ) -> VecDeque { - let mut out = VecDeque::new(); - for a in 0..push_back { - out.push_back(a); - } - for b in 0..push_front { - out.push_front(push_back + b); - } - for _ in 0..pop_back { - out.pop_back(); - } - for _ in 0..pop_front { - out.pop_front(); - } - out - } - - // Miri is too slow - let max = if cfg!(miri) { 3 } else { 5 }; - - // Many different permutations of both the `VecDeque` getting appended to - // and the one getting appended are generated to check `append`. - // This ensures all 6 code paths of `append` are tested. - for src_push_back in 0..max { - for src_push_front in 0..max { - // doesn't pop more values than are pushed - for src_pop_back in 0..(src_push_back + src_push_front) { - for src_pop_front in 0..(src_push_back + src_push_front - src_pop_back) { - let src = construct_vec_deque( - src_push_back, - src_pop_back, - src_push_front, - src_pop_front, - ); - - for dst_push_back in 0..max { - for dst_push_front in 0..max { - for dst_pop_back in 0..(dst_push_back + dst_push_front) { - for dst_pop_front in - 0..(dst_push_back + dst_push_front - dst_pop_back) - { - let mut dst = construct_vec_deque( - dst_push_back, - dst_pop_back, - dst_push_front, - dst_pop_front, - ); - let mut src = src.clone(); - - // Assert that appending `src` to `dst` gives the same order - // of values as iterating over both in sequence. - let correct = dst - .iter() - .chain(src.iter()) - .cloned() - .collect::>(); - dst.append(&mut src); - assert_eq!(dst, correct); - assert!(src.is_empty()); - } - } - } - } - } - } - } - } -} - -struct DropCounter<'a> { - count: &'a mut u32, -} - -impl Drop for DropCounter<'_> { - fn drop(&mut self) { - *self.count += 1; - } -} - -#[test] -fn test_append_double_drop() { - let (mut count_a, mut count_b) = (0, 0); - { - let mut a = VecDeque::new(); - let mut b = VecDeque::new(); - a.push_back(DropCounter { count: &mut count_a }); - b.push_back(DropCounter { count: &mut count_b }); - - a.append(&mut b); - } - assert_eq!(count_a, 1); - assert_eq!(count_b, 1); -} - -#[test] -#[should_panic] -fn test_append_zst_capacity_overflow() { - let mut v = Vec::with_capacity(usize::MAX); - // note: using resize instead of set_len here would - // be *extremely* slow in unoptimized builds. - // SAFETY: `v` has capacity `usize::MAX`, and no initialization - // is needed for empty tuples. - unsafe { v.set_len(usize::MAX) }; - let mut v = VecDeque::from(v); - let mut w = vec![()].into(); - v.append(&mut w); -} - -#[test] -fn test_retain() { - let mut buf = VecDeque::new(); - buf.extend(1..5); - buf.retain(|&x| x % 2 == 0); - let v: Vec<_> = buf.into_iter().collect(); - assert_eq!(&v[..], &[2, 4]); -} - -#[test] -fn test_extend_ref() { - let mut v = VecDeque::new(); - v.push_back(1); - v.extend(&[2, 3, 4]); - - assert_eq!(v.len(), 4); - assert_eq!(v[0], 1); - assert_eq!(v[1], 2); - assert_eq!(v[2], 3); - assert_eq!(v[3], 4); - - let mut w = VecDeque::new(); - w.push_back(5); - w.push_back(6); - v.extend(&w); - - assert_eq!(v.len(), 6); - assert_eq!(v[0], 1); - assert_eq!(v[1], 2); - assert_eq!(v[2], 3); - assert_eq!(v[3], 4); - assert_eq!(v[4], 5); - assert_eq!(v[5], 6); -} - -#[test] -fn test_contains() { - let mut v = VecDeque::new(); - v.extend(&[2, 3, 4]); - - assert!(v.contains(&3)); - assert!(!v.contains(&1)); - - v.clear(); - - assert!(!v.contains(&3)); -} - -#[allow(dead_code)] -fn assert_covariance() { - fn drain<'new>(d: Drain<'static, &'static str>) -> Drain<'new, &'new str> { - d - } -} - -#[test] -fn test_is_empty() { - let mut v = VecDeque::::new(); - assert!(v.is_empty()); - assert!(v.iter().is_empty()); - assert!(v.iter_mut().is_empty()); - v.extend(&[2, 3, 4]); - assert!(!v.is_empty()); - assert!(!v.iter().is_empty()); - assert!(!v.iter_mut().is_empty()); - while let Some(_) = v.pop_front() { - assert_eq!(v.is_empty(), v.len() == 0); - assert_eq!(v.iter().is_empty(), v.iter().len() == 0); - assert_eq!(v.iter_mut().is_empty(), v.iter_mut().len() == 0); - } - assert!(v.is_empty()); - assert!(v.iter().is_empty()); - assert!(v.iter_mut().is_empty()); - assert!(v.into_iter().is_empty()); -} - -#[test] -fn test_reserve_exact_2() { - // This is all the same as test_reserve - - let mut v = VecDeque::new(); - - v.reserve_exact(2); - assert!(v.capacity() >= 2); - - for i in 0..16 { - v.push_back(i); - } - - assert!(v.capacity() >= 16); - v.reserve_exact(16); - assert!(v.capacity() >= 32); - - v.push_back(16); - - v.reserve_exact(16); - assert!(v.capacity() >= 33) -} - -#[test] -#[cfg_attr(miri, ignore)] // Miri does not support signalling OOM -#[cfg_attr(target_os = "android", ignore)] // Android used in CI has a broken dlmalloc -fn test_try_with_capacity() { - let vec: VecDeque = VecDeque::try_with_capacity(5).unwrap(); - assert_eq!(0, vec.len()); - assert!(vec.capacity() >= 5 && vec.capacity() <= isize::MAX as usize / 4); - - assert!(VecDeque::::try_with_capacity(isize::MAX as usize + 1).is_err()); -} - -#[test] -#[cfg_attr(miri, ignore)] // Miri does not support signalling OOM -#[cfg_attr(target_os = "android", ignore)] // Android used in CI has a broken dlmalloc -fn test_try_reserve() { - // These are the interesting cases: - // * exactly isize::MAX should never trigger a CapacityOverflow (can be OOM) - // * > isize::MAX should always fail - // * On 16/32-bit should CapacityOverflow - // * On 64-bit should OOM - // * overflow may trigger when adding `len` to `cap` (in number of elements) - // * overflow may trigger when multiplying `new_cap` by size_of:: (to get bytes) - - const MAX_CAP: usize = isize::MAX as usize; - const MAX_USIZE: usize = usize::MAX; - - { - // Note: basic stuff is checked by test_reserve - let mut empty_bytes: VecDeque = VecDeque::new(); - - // Check isize::MAX doesn't count as an overflow - if let Err(CapacityOverflow) = empty_bytes.try_reserve(MAX_CAP).map_err(|e| e.kind()) { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - // Play it again, frank! (just to be sure) - if let Err(CapacityOverflow) = empty_bytes.try_reserve(MAX_CAP).map_err(|e| e.kind()) { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - - // Check isize::MAX + 1 does count as overflow - assert_matches!( - empty_bytes.try_reserve(MAX_CAP + 1).map_err(|e| e.kind()), - Err(CapacityOverflow), - "isize::MAX + 1 should trigger an overflow!" - ); - - // Check usize::MAX does count as overflow - assert_matches!( - empty_bytes.try_reserve(MAX_USIZE).map_err(|e| e.kind()), - Err(CapacityOverflow), - "usize::MAX should trigger an overflow!" - ); - } - - { - // Same basic idea, but with non-zero len - let mut ten_bytes: VecDeque = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10].into_iter().collect(); - - if let Err(CapacityOverflow) = ten_bytes.try_reserve(MAX_CAP - 10).map_err(|e| e.kind()) { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - if let Err(CapacityOverflow) = ten_bytes.try_reserve(MAX_CAP - 10).map_err(|e| e.kind()) { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - - assert_matches!( - ten_bytes.try_reserve(MAX_CAP - 9).map_err(|e| e.kind()), - Err(CapacityOverflow), - "isize::MAX + 1 should trigger an overflow!" - ); - - // Should always overflow in the add-to-len - assert_matches!( - ten_bytes.try_reserve(MAX_USIZE).map_err(|e| e.kind()), - Err(CapacityOverflow), - "usize::MAX should trigger an overflow!" - ); - } - - { - // Same basic idea, but with interesting type size - let mut ten_u32s: VecDeque = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10].into_iter().collect(); - - if let Err(CapacityOverflow) = ten_u32s.try_reserve(MAX_CAP / 4 - 10).map_err(|e| e.kind()) - { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - if let Err(CapacityOverflow) = ten_u32s.try_reserve(MAX_CAP / 4 - 10).map_err(|e| e.kind()) - { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - - assert_matches!( - ten_u32s.try_reserve(MAX_CAP / 4 - 9).map_err(|e| e.kind()), - Err(CapacityOverflow), - "isize::MAX + 1 should trigger an overflow!" - ); - - // Should fail in the mul-by-size - assert_matches!( - ten_u32s.try_reserve(MAX_USIZE - 20).map_err(|e| e.kind()), - Err(CapacityOverflow), - "usize::MAX should trigger an overflow!" - ); - } -} - -#[test] -#[cfg_attr(miri, ignore)] // Miri does not support signalling OOM -#[cfg_attr(target_os = "android", ignore)] // Android used in CI has a broken dlmalloc -fn test_try_reserve_exact() { - // This is exactly the same as test_try_reserve with the method changed. - // See that test for comments. - - const MAX_CAP: usize = isize::MAX as usize; - const MAX_USIZE: usize = usize::MAX; - - { - let mut empty_bytes: VecDeque = VecDeque::new(); - - if let Err(CapacityOverflow) = empty_bytes.try_reserve_exact(MAX_CAP).map_err(|e| e.kind()) - { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - if let Err(CapacityOverflow) = empty_bytes.try_reserve_exact(MAX_CAP).map_err(|e| e.kind()) - { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - - assert_matches!( - empty_bytes.try_reserve_exact(MAX_CAP + 1).map_err(|e| e.kind()), - Err(CapacityOverflow), - "isize::MAX + 1 should trigger an overflow!" - ); - - assert_matches!( - empty_bytes.try_reserve_exact(MAX_USIZE).map_err(|e| e.kind()), - Err(CapacityOverflow), - "usize::MAX should trigger an overflow!" - ); - } - - { - let mut ten_bytes: VecDeque = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10].into_iter().collect(); - - if let Err(CapacityOverflow) = - ten_bytes.try_reserve_exact(MAX_CAP - 10).map_err(|e| e.kind()) - { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - if let Err(CapacityOverflow) = - ten_bytes.try_reserve_exact(MAX_CAP - 10).map_err(|e| e.kind()) - { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - - assert_matches!( - ten_bytes.try_reserve_exact(MAX_CAP - 9).map_err(|e| e.kind()), - Err(CapacityOverflow), - "isize::MAX + 1 should trigger an overflow!" - ); - - assert_matches!( - ten_bytes.try_reserve_exact(MAX_USIZE).map_err(|e| e.kind()), - Err(CapacityOverflow), - "usize::MAX should trigger an overflow!" - ); - } - - { - let mut ten_u32s: VecDeque = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10].into_iter().collect(); - - if let Err(CapacityOverflow) = - ten_u32s.try_reserve_exact(MAX_CAP / 4 - 10).map_err(|e| e.kind()) - { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - if let Err(CapacityOverflow) = - ten_u32s.try_reserve_exact(MAX_CAP / 4 - 10).map_err(|e| e.kind()) - { - panic!("isize::MAX shouldn't trigger an overflow!"); - } - - assert_matches!( - ten_u32s.try_reserve_exact(MAX_CAP / 4 - 9).map_err(|e| e.kind()), - Err(CapacityOverflow), - "isize::MAX + 1 should trigger an overflow!" - ); - - assert_matches!( - ten_u32s.try_reserve_exact(MAX_USIZE - 20).map_err(|e| e.kind()), - Err(CapacityOverflow), - "usize::MAX should trigger an overflow!" - ); - } -} - -#[test] -fn test_rotate_nop() { - let mut v: VecDeque<_> = (0..10).collect(); - assert_unchanged(&v); - - v.rotate_left(0); - assert_unchanged(&v); - - v.rotate_left(10); - assert_unchanged(&v); - - v.rotate_right(0); - assert_unchanged(&v); - - v.rotate_right(10); - assert_unchanged(&v); - - v.rotate_left(3); - v.rotate_right(3); - assert_unchanged(&v); - - v.rotate_right(3); - v.rotate_left(3); - assert_unchanged(&v); - - v.rotate_left(6); - v.rotate_right(6); - assert_unchanged(&v); - - v.rotate_right(6); - v.rotate_left(6); - assert_unchanged(&v); - - v.rotate_left(3); - v.rotate_left(7); - assert_unchanged(&v); - - v.rotate_right(4); - v.rotate_right(6); - assert_unchanged(&v); - - v.rotate_left(1); - v.rotate_left(2); - v.rotate_left(3); - v.rotate_left(4); - assert_unchanged(&v); - - v.rotate_right(1); - v.rotate_right(2); - v.rotate_right(3); - v.rotate_right(4); - assert_unchanged(&v); - - fn assert_unchanged(v: &VecDeque) { - assert_eq!(v, &[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]); - } -} - -#[test] -fn test_rotate_left_parts() { - let mut v: VecDeque<_> = VecDeque::with_capacity(8); - v.extend(1..=7); - v.rotate_left(2); - assert_eq!(v.as_slices(), (&[3, 4, 5, 6, 7, 1][..], &[2][..])); - v.rotate_left(2); - assert_eq!(v.as_slices(), (&[5, 6, 7, 1][..], &[2, 3, 4][..])); - v.rotate_left(2); - assert_eq!(v.as_slices(), (&[7, 1][..], &[2, 3, 4, 5, 6][..])); - v.rotate_left(2); - assert_eq!(v.as_slices(), (&[2, 3, 4, 5, 6, 7, 1][..], &[][..])); - v.rotate_left(2); - assert_eq!(v.as_slices(), (&[4, 5, 6, 7, 1, 2][..], &[3][..])); - v.rotate_left(2); - assert_eq!(v.as_slices(), (&[6, 7, 1, 2][..], &[3, 4, 5][..])); - v.rotate_left(2); - assert_eq!(v.as_slices(), (&[1, 2][..], &[3, 4, 5, 6, 7][..])); -} - -#[test] -fn test_rotate_right_parts() { - let mut v: VecDeque<_> = VecDeque::with_capacity(8); - v.extend(1..=7); - v.rotate_right(2); - assert_eq!(v.as_slices(), (&[6, 7][..], &[1, 2, 3, 4, 5][..])); - v.rotate_right(2); - assert_eq!(v.as_slices(), (&[4, 5, 6, 7][..], &[1, 2, 3][..])); - v.rotate_right(2); - assert_eq!(v.as_slices(), (&[2, 3, 4, 5, 6, 7][..], &[1][..])); - v.rotate_right(2); - assert_eq!(v.as_slices(), (&[7, 1, 2, 3, 4, 5, 6][..], &[][..])); - v.rotate_right(2); - assert_eq!(v.as_slices(), (&[5, 6][..], &[7, 1, 2, 3, 4][..])); - v.rotate_right(2); - assert_eq!(v.as_slices(), (&[3, 4, 5, 6][..], &[7, 1, 2][..])); - v.rotate_right(2); - assert_eq!(v.as_slices(), (&[1, 2, 3, 4, 5, 6][..], &[7][..])); -} - -#[test] -fn test_rotate_left_random() { - let shifts = [ - 6, 1, 0, 11, 12, 1, 11, 7, 9, 3, 6, 1, 4, 0, 5, 1, 3, 1, 12, 8, 3, 1, 11, 11, 9, 4, 12, 3, - 12, 9, 11, 1, 7, 9, 7, 2, - ]; - let n = 12; - let mut v: VecDeque<_> = (0..n).collect(); - let mut total_shift = 0; - for shift in shifts.iter().cloned() { - v.rotate_left(shift); - total_shift += shift; - for i in 0..n { - assert_eq!(v[i], (i + total_shift) % n); - } - } -} - -#[test] -fn test_rotate_right_random() { - let shifts = [ - 6, 1, 0, 11, 12, 1, 11, 7, 9, 3, 6, 1, 4, 0, 5, 1, 3, 1, 12, 8, 3, 1, 11, 11, 9, 4, 12, 3, - 12, 9, 11, 1, 7, 9, 7, 2, - ]; - let n = 12; - let mut v: VecDeque<_> = (0..n).collect(); - let mut total_shift = 0; - for shift in shifts.iter().cloned() { - v.rotate_right(shift); - total_shift += shift; - for i in 0..n { - assert_eq!(v[(i + total_shift) % n], i); - } - } -} - -#[test] -fn test_try_fold_empty() { - assert_eq!(Some(0), VecDeque::::new().iter().try_fold(0, |_, _| None)); -} - -#[test] -fn test_try_fold_none() { - let v: VecDeque = (0..12).collect(); - assert_eq!(None, v.into_iter().try_fold(0, |a, b| if b < 11 { Some(a + b) } else { None })); -} - -#[test] -fn test_try_fold_ok() { - let v: VecDeque = (0..12).collect(); - assert_eq!(Ok::<_, ()>(66), v.into_iter().try_fold(0, |a, b| Ok(a + b))); -} - -#[test] -fn test_try_fold_unit() { - let v: VecDeque<()> = std::iter::repeat(()).take(42).collect(); - assert_eq!(Some(()), v.into_iter().try_fold((), |(), ()| Some(()))); -} - -#[test] -fn test_try_fold_unit_none() { - let v: std::collections::VecDeque<()> = [(); 10].iter().cloned().collect(); - let mut iter = v.into_iter(); - assert!(iter.try_fold((), |_, _| None).is_none()); - assert_eq!(iter.len(), 9); -} - -#[test] -fn test_try_fold_rotated() { - let mut v: VecDeque<_> = (0..12).collect(); - for n in 0..10 { - if n & 1 == 0 { - v.rotate_left(n); - } else { - v.rotate_right(n); - } - assert_eq!(Ok::<_, ()>(66), v.iter().try_fold(0, |a, b| Ok(a + b))); - } -} - -#[test] -fn test_try_fold_moves_iter() { - let v: VecDeque<_> = [10, 20, 30, 40, 100, 60, 70, 80, 90].iter().collect(); - let mut iter = v.into_iter(); - assert_eq!(iter.try_fold(0_i8, |acc, &x| acc.checked_add(x)), None); - assert_eq!(iter.next(), Some(&60)); -} - -#[test] -fn test_try_fold_exhaust_wrap() { - let mut v = VecDeque::with_capacity(7); - v.push_back(1); - v.push_back(1); - v.push_back(1); - v.pop_front(); - v.pop_front(); - let mut iter = v.iter(); - let _ = iter.try_fold(0, |_, _| Some(1)); - assert!(iter.is_empty()); -} - -#[test] -fn test_try_fold_wraparound() { - let mut v = VecDeque::with_capacity(8); - v.push_back(7); - v.push_back(8); - v.push_back(9); - v.push_front(2); - v.push_front(1); - let mut iter = v.iter(); - let _ = iter.find(|&&x| x == 2); - assert_eq!(Some(&7), iter.next()); -} - -#[test] -fn test_try_rfold_rotated() { - let mut v: VecDeque<_> = (0..12).collect(); - for n in 0..10 { - if n & 1 == 0 { - v.rotate_left(n); - } else { - v.rotate_right(n); - } - assert_eq!(Ok::<_, ()>(66), v.iter().try_rfold(0, |a, b| Ok(a + b))); - } -} - -#[test] -fn test_try_rfold_moves_iter() { - let v: VecDeque<_> = [10, 20, 30, 40, 100, 60, 70, 80, 90].iter().collect(); - let mut iter = v.into_iter(); - assert_eq!(iter.try_rfold(0_i8, |acc, &x| acc.checked_add(x)), None); - assert_eq!(iter.next_back(), Some(&70)); -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn truncate_leak() { - static mut DROPS: i32 = 0; - - struct D(bool); - - impl Drop for D { - fn drop(&mut self) { - unsafe { - DROPS += 1; - } - - if self.0 { - panic!("panic in `drop`"); - } - } - } - - let mut q = VecDeque::new(); - q.push_back(D(false)); - q.push_back(D(false)); - q.push_back(D(false)); - q.push_back(D(false)); - q.push_back(D(false)); - q.push_front(D(true)); - q.push_front(D(false)); - q.push_front(D(false)); - - catch_unwind(AssertUnwindSafe(|| q.truncate(1))).ok(); - - assert_eq!(unsafe { DROPS }, 7); -} - -#[test] -#[cfg_attr(not(panic = "unwind"), ignore = "test requires unwinding support")] -fn test_drain_leak() { - static mut DROPS: i32 = 0; - - #[derive(Debug, PartialEq)] - struct D(u32, bool); - - impl Drop for D { - fn drop(&mut self) { - unsafe { - DROPS += 1; - } - - if self.1 { - panic!("panic in `drop`"); - } - } - } - - let mut v = VecDeque::new(); - v.push_back(D(4, false)); - v.push_back(D(5, false)); - v.push_back(D(6, false)); - v.push_front(D(3, false)); - v.push_front(D(2, true)); - v.push_front(D(1, false)); - v.push_front(D(0, false)); - - catch_unwind(AssertUnwindSafe(|| { - v.drain(1..=4); - })) - .ok(); - - assert_eq!(unsafe { DROPS }, 4); - assert_eq!(v.len(), 3); - drop(v); - assert_eq!(unsafe { DROPS }, 7); -} - -#[test] -fn test_binary_search() { - // Contiguous (front only) search: - let deque: VecDeque<_> = vec![1, 2, 3, 5, 6].into(); - assert!(deque.as_slices().1.is_empty()); - assert_eq!(deque.binary_search(&3), Ok(2)); - assert_eq!(deque.binary_search(&4), Err(3)); - - // Split search (both front & back non-empty): - let mut deque: VecDeque<_> = vec![5, 6].into(); - deque.push_front(3); - deque.push_front(2); - deque.push_front(1); - deque.push_back(10); - assert!(!deque.as_slices().0.is_empty()); - assert!(!deque.as_slices().1.is_empty()); - assert_eq!(deque.binary_search(&0), Err(0)); - assert_eq!(deque.binary_search(&1), Ok(0)); - assert_eq!(deque.binary_search(&5), Ok(3)); - assert_eq!(deque.binary_search(&7), Err(5)); - assert_eq!(deque.binary_search(&20), Err(6)); -} - -#[test] -fn test_binary_search_by() { - let deque: VecDeque<_> = vec![(1,), (2,), (3,), (5,), (6,)].into(); - - assert_eq!(deque.binary_search_by(|&(v,)| v.cmp(&3)), Ok(2)); - assert_eq!(deque.binary_search_by(|&(v,)| v.cmp(&4)), Err(3)); -} - -#[test] -fn test_binary_search_by_key() { - let deque: VecDeque<_> = vec![(1,), (2,), (3,), (5,), (6,)].into(); - - assert_eq!(deque.binary_search_by_key(&3, |&(v,)| v), Ok(2)); - assert_eq!(deque.binary_search_by_key(&4, |&(v,)| v), Err(3)); -} - -#[test] -fn test_partition_point() { - // Contiguous (front only) search: - let deque: VecDeque<_> = vec![1, 2, 3, 5, 6].into(); - assert!(deque.as_slices().1.is_empty()); - assert_eq!(deque.partition_point(|&v| v <= 3), 3); - - // Split search (both front & back non-empty): - let mut deque: VecDeque<_> = vec![5, 6].into(); - deque.push_front(3); - deque.push_front(2); - deque.push_front(1); - deque.push_back(10); - assert!(!deque.as_slices().0.is_empty()); - assert!(!deque.as_slices().1.is_empty()); - assert_eq!(deque.partition_point(|&v| v <= 5), 4); -} - -#[test] -fn test_zero_sized_push() { - const N: usize = 8; - - // Zero sized type - struct Zst; - - // Test that for all possible sequences of push_front / push_back, - // we end up with a deque of the correct size - - for len in 0..N { - let mut tester = VecDeque::with_capacity(len); - assert_eq!(tester.len(), 0); - assert!(tester.capacity() >= len); - for case in 0..(1 << len) { - assert_eq!(tester.len(), 0); - for bit in 0..len { - if case & (1 << bit) != 0 { - tester.push_front(Zst); - } else { - tester.push_back(Zst); - } - } - assert_eq!(tester.len(), len); - assert_eq!(tester.iter().count(), len); - tester.clear(); - } - } -} - -#[test] -fn test_from_zero_sized_vec() { - let v = vec![(); 100]; - let queue = VecDeque::from(v); - assert_eq!(queue.len(), 100); -} - -#[test] -fn test_resize_keeps_reserved_space_from_item() { - let v = Vec::::with_capacity(1234); - let mut d = VecDeque::new(); - d.resize(1, v); - assert_eq!(d[0].capacity(), 1234); -} - -#[test] -fn test_collect_from_into_iter_keeps_allocation() { - let mut v = Vec::with_capacity(13); - v.extend(0..7); - check(v.as_ptr(), v.last().unwrap(), v.into_iter()); - - let mut v = VecDeque::with_capacity(13); - v.extend(0..7); - check(&v[0], &v[v.len() - 1], v.into_iter()); - - fn check(buf: *const i32, last: *const i32, mut it: impl Iterator) { - assert_eq!(it.next(), Some(0)); - assert_eq!(it.next(), Some(1)); - - let mut v: VecDeque = it.collect(); - assert_eq!(v.capacity(), 13); - assert_eq!(v.as_slices().0.as_ptr(), buf.wrapping_add(2)); - assert_eq!(&v[v.len() - 1] as *const _, last); - - assert_eq!(v.as_slices(), ([2, 3, 4, 5, 6].as_slice(), [].as_slice())); - v.push_front(7); - assert_eq!(v.as_slices(), ([7, 2, 3, 4, 5, 6].as_slice(), [].as_slice())); - v.push_front(8); - assert_eq!(v.as_slices(), ([8, 7, 2, 3, 4, 5, 6].as_slice(), [].as_slice())); - - // Now that we've adding thing in place of the two that we removed from - // the front of the iterator, we're back to matching the buffer pointer. - assert_eq!(v.as_slices().0.as_ptr(), buf); - assert_eq!(&v[v.len() - 1] as *const _, last); - - v.push_front(9); - assert_eq!(v.as_slices(), ([9].as_slice(), [8, 7, 2, 3, 4, 5, 6].as_slice())); - assert_eq!(v.capacity(), 13); - } -} diff --git a/library/backtrace b/library/backtrace deleted file mode 160000 index e15130618237e..0000000000000 --- a/library/backtrace +++ /dev/null @@ -1 +0,0 @@ -Subproject commit e15130618237eb3e2d4b622549f9647b4c1d9ca3 diff --git a/library/core/Cargo.toml b/library/core/Cargo.toml deleted file mode 100644 index e9fb39f19966c..0000000000000 --- a/library/core/Cargo.toml +++ /dev/null @@ -1,56 +0,0 @@ -[package] -name = "core" -version = "0.0.0" -license = "MIT OR Apache-2.0" -repository = "https://github.com/rust-lang/rust.git" -description = "The Rust Core Library" -autotests = false -autobenches = false -# If you update this, be sure to update it in a bunch of other places too! -# As of 2024, it was src/tools/opt-dist, the core-no-fp-fmt-parse test and -# the version of the prelude imported in core/lib.rs. -edition = "2021" - -[lib] -test = false -bench = false - -[[test]] -name = "coretests" -path = "tests/lib.rs" - -[[bench]] -name = "corebenches" -path = "benches/lib.rs" -test = true - -[dependencies] -safety = {path = "../contracts/safety" } - -[dev-dependencies] -rand = { version = "0.8.5", default-features = false } -rand_xorshift = { version = "0.3.0", default-features = false } - -[features] -# Make panics and failed asserts immediately abort without formatting any message -panic_immediate_abort = [] -# Choose algorithms that are optimized for binary size instead of runtime performance -optimize_for_size = [] -# Make `RefCell` store additional debugging information, which is printed out when -# a borrow error occurs -debug_refcell = [] - -[lints.rust.unexpected_cfgs] -level = "warn" -# x.py uses beta cargo, so `check-cfg` entries do not yet take effect -# for rust-lang/rust. But for users of `-Zbuild-std` it does. -# The unused warning is waiting for rust-lang/cargo#13925 to reach beta. -check-cfg = [ - 'cfg(bootstrap)', - 'cfg(no_fp_fmt_parse)', - 'cfg(stdarch_intel_sde)', - # core use #[path] imports to portable-simd `core_simd` crate - # and to stdarch `core_arch` crate which messes-up with Cargo list - # of declared features, we therefor expect any feature cfg - 'cfg(feature, values(any()))', -] diff --git a/library/core/benches/any.rs b/library/core/benches/any.rs deleted file mode 100644 index 53099b78266f8..0000000000000 --- a/library/core/benches/any.rs +++ /dev/null @@ -1,12 +0,0 @@ -use core::any::*; -use test::{black_box, Bencher}; - -#[bench] -fn bench_downcast_ref(b: &mut Bencher) { - b.iter(|| { - let mut x = 0; - let mut y = &mut x as &mut dyn Any; - black_box(&mut y); - black_box(y.downcast_ref::() == Some(&0)); - }); -} diff --git a/library/core/benches/array.rs b/library/core/benches/array.rs deleted file mode 100644 index d8cc44d05c4ba..0000000000000 --- a/library/core/benches/array.rs +++ /dev/null @@ -1,19 +0,0 @@ -use test::black_box; -use test::Bencher; - -macro_rules! map_array { - ($func_name:ident, $start_item: expr, $map_item: expr, $arr_size: expr) => { - #[bench] - fn $func_name(b: &mut Bencher) { - let arr = [$start_item; $arr_size]; - b.iter(|| black_box(arr).map(|_| black_box($map_item))); - } - }; -} - -map_array!(map_8byte_8byte_8, 0u64, 1u64, 80); -map_array!(map_8byte_8byte_64, 0u64, 1u64, 640); -map_array!(map_8byte_8byte_256, 0u64, 1u64, 2560); - -map_array!(map_8byte_256byte_256, 0u64, [0u64; 4], 2560); -map_array!(map_256byte_8byte_256, [0u64; 4], 0u64, 2560); diff --git a/library/core/benches/ascii.rs b/library/core/benches/ascii.rs deleted file mode 100644 index 71ec9fed2fe75..0000000000000 --- a/library/core/benches/ascii.rs +++ /dev/null @@ -1,381 +0,0 @@ -mod is_ascii; - -// Lower-case ASCII 'a' is the first byte that has its highest bit set -// after wrap-adding 0x1F: -// -// b'a' + 0x1F == 0x80 == 0b1000_0000 -// b'z' + 0x1F == 0x98 == 0b1001_1000 -// -// Lower-case ASCII 'z' is the last byte that has its highest bit unset -// after wrap-adding 0x05: -// -// b'a' + 0x05 == 0x66 == 0b0110_0110 -// b'z' + 0x05 == 0x7F == 0b0111_1111 -// -// … except for 0xFB to 0xFF, but those are in the range of bytes -// that have the highest bit unset again after adding 0x1F. -// -// So `(byte + 0x1f) & !(byte + 5)` has its highest bit set -// iff `byte` is a lower-case ASCII letter. -// -// Lower-case ASCII letters all have the 0x20 bit set. -// (Two positions right of 0x80, the highest bit.) -// Unsetting that bit produces the same letter, in upper-case. -// -// Therefore: -fn branchless_to_ascii_upper_case(byte: u8) -> u8 { - byte & !((byte.wrapping_add(0x1f) & !byte.wrapping_add(0x05) & 0x80) >> 2) -} - -macro_rules! benches { - ($( fn $name: ident($arg: ident: &mut [u8]) $body: block )+ @iter $( $is_: ident, )+) => { - benches! {@ - $( fn $name($arg: &mut [u8]) $body )+ - $( fn $is_(bytes: &mut [u8]) { bytes.iter().all(u8::$is_) } )+ - } - }; - - (@$( fn $name: ident($arg: ident: &mut [u8]) $body: block )+) => { - benches!(mod short SHORT $($name $arg $body)+); - benches!(mod medium MEDIUM $($name $arg $body)+); - benches!(mod long LONG $($name $arg $body)+); - }; - - (mod $mod_name: ident $input: ident $($name: ident $arg: ident $body: block)+) => { - mod $mod_name { - use super::*; - - $( - #[bench] - fn $name(bencher: &mut Bencher) { - bencher.bytes = $input.len() as u64; - bencher.iter(|| { - let mut vec = $input.as_bytes().to_vec(); - { - let $arg = &mut vec[..]; - black_box($body); - } - vec - }) - } - )+ - } - } -} - -use std::fmt::Write; -use test::black_box; -use test::Bencher; - -const ASCII_CASE_MASK: u8 = 0b0010_0000; - -benches! { - fn case00_alloc_only(_bytes: &mut [u8]) {} - - fn case01_black_box_read_each_byte(bytes: &mut [u8]) { - for byte in bytes { - black_box(*byte); - } - } - - fn case02_lookup_table(bytes: &mut [u8]) { - for byte in bytes { - *byte = ASCII_UPPERCASE_MAP[*byte as usize] - } - } - - fn case03_branch_and_subtract(bytes: &mut [u8]) { - for byte in bytes { - *byte = if b'a' <= *byte && *byte <= b'z' { - *byte - b'a' + b'A' - } else { - *byte - } - } - } - - fn case04_branch_and_mask(bytes: &mut [u8]) { - for byte in bytes { - *byte = if b'a' <= *byte && *byte <= b'z' { - *byte & !0x20 - } else { - *byte - } - } - } - - fn case05_branchless(bytes: &mut [u8]) { - for byte in bytes { - *byte = branchless_to_ascii_upper_case(*byte) - } - } - - fn case06_libcore(bytes: &mut [u8]) { - bytes.make_ascii_uppercase() - } - - fn case07_fake_simd_u32(bytes: &mut [u8]) { - // SAFETY: transmuting a sequence of `u8` to `u32` is always fine - let (before, aligned, after) = unsafe { - bytes.align_to_mut::() - }; - for byte in before { - *byte = branchless_to_ascii_upper_case(*byte) - } - for word in aligned { - // FIXME: this is incorrect for some byte values: - // addition within a byte can carry/overflow into the next byte. - // Test case: b"\xFFz " - *word &= !( - ( - word.wrapping_add(0x1f1f1f1f) & - !word.wrapping_add(0x05050505) & - 0x80808080 - ) >> 2 - ) - } - for byte in after { - *byte = branchless_to_ascii_upper_case(*byte) - } - } - - fn case08_fake_simd_u64(bytes: &mut [u8]) { - // SAFETY: transmuting a sequence of `u8` to `u64` is always fine - let (before, aligned, after) = unsafe { - bytes.align_to_mut::() - }; - for byte in before { - *byte = branchless_to_ascii_upper_case(*byte) - } - for word in aligned { - // FIXME: like above, this is incorrect for some byte values. - *word &= !( - ( - word.wrapping_add(0x1f1f1f1f_1f1f1f1f) & - !word.wrapping_add(0x05050505_05050505) & - 0x80808080_80808080 - ) >> 2 - ) - } - for byte in after { - *byte = branchless_to_ascii_upper_case(*byte) - } - } - - fn case09_mask_mult_bool_branchy_lookup_table(bytes: &mut [u8]) { - fn is_ascii_lowercase(b: u8) -> bool { - if b >= 0x80 { return false } - match ASCII_CHARACTER_CLASS[b as usize] { - L | Lx => true, - _ => false, - } - } - for byte in bytes { - *byte &= !(0x20 * (is_ascii_lowercase(*byte) as u8)) - } - } - - fn case10_mask_mult_bool_lookup_table(bytes: &mut [u8]) { - fn is_ascii_lowercase(b: u8) -> bool { - match ASCII_CHARACTER_CLASS[b as usize] { - L | Lx => true, - _ => false - } - } - for byte in bytes { - *byte &= !(0x20 * (is_ascii_lowercase(*byte) as u8)) - } - } - - fn case11_mask_mult_bool_match_range(bytes: &mut [u8]) { - fn is_ascii_lowercase(b: u8) -> bool { - match b { - b'a'..=b'z' => true, - _ => false - } - } - for byte in bytes { - *byte &= !(0x20 * (is_ascii_lowercase(*byte) as u8)) - } - } - - fn case12_mask_shifted_bool_match_range(bytes: &mut [u8]) { - fn is_ascii_lowercase(b: u8) -> bool { - match b { - b'a'..=b'z' => true, - _ => false - } - } - for byte in bytes { - *byte &= !((is_ascii_lowercase(*byte) as u8) * ASCII_CASE_MASK) - } - } - - fn case13_subtract_shifted_bool_match_range(bytes: &mut [u8]) { - fn is_ascii_lowercase(b: u8) -> bool { - match b { - b'a'..=b'z' => true, - _ => false - } - } - for byte in bytes { - *byte -= (is_ascii_lowercase(*byte) as u8) * ASCII_CASE_MASK - } - } - - fn case14_subtract_multiplied_bool_match_range(bytes: &mut [u8]) { - fn is_ascii_lowercase(b: u8) -> bool { - match b { - b'a'..=b'z' => true, - _ => false - } - } - for byte in bytes { - *byte -= (b'a' - b'A') * is_ascii_lowercase(*byte) as u8 - } - } - - @iter - - is_ascii, - is_ascii_alphabetic, - is_ascii_uppercase, - is_ascii_lowercase, - is_ascii_alphanumeric, - is_ascii_digit, - is_ascii_hexdigit, - is_ascii_punctuation, - is_ascii_graphic, - is_ascii_whitespace, - is_ascii_control, -} - -macro_rules! repeat { - ($s: expr) => { - concat!($s, $s, $s, $s, $s, $s, $s, $s, $s, $s) - }; -} - -const SHORT: &str = "Alice's"; -const MEDIUM: &str = "Alice's Adventures in Wonderland"; -const LONG: &str = repeat!( - r#" - La Guida di Bragia, a Ballad Opera for the Marionette Theatre (around 1850) - Alice's Adventures in Wonderland (1865) - Phantasmagoria and Other Poems (1869) - Through the Looking-Glass, and What Alice Found There - (includes "Jabberwocky" and "The Walrus and the Carpenter") (1871) - The Hunting of the Snark (1876) - Rhyme? And Reason? (1883) – shares some contents with the 1869 collection, - including the long poem "Phantasmagoria" - A Tangled Tale (1885) - Sylvie and Bruno (1889) - Sylvie and Bruno Concluded (1893) - Pillow Problems (1893) - What the Tortoise Said to Achilles (1895) - Three Sunsets and Other Poems (1898) - The Manlet (1903)[106] -"# -); - -#[rustfmt::skip] -const ASCII_UPPERCASE_MAP: [u8; 256] = [ - 0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, - 0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f, - 0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17, - 0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f, - b' ', b'!', b'"', b'#', b'$', b'%', b'&', b'\'', - b'(', b')', b'*', b'+', b',', b'-', b'.', b'/', - b'0', b'1', b'2', b'3', b'4', b'5', b'6', b'7', - b'8', b'9', b':', b';', b'<', b'=', b'>', b'?', - b'@', b'A', b'B', b'C', b'D', b'E', b'F', b'G', - b'H', b'I', b'J', b'K', b'L', b'M', b'N', b'O', - b'P', b'Q', b'R', b'S', b'T', b'U', b'V', b'W', - b'X', b'Y', b'Z', b'[', b'\\', b']', b'^', b'_', - b'`', - - b'A', b'B', b'C', b'D', b'E', b'F', b'G', - b'H', b'I', b'J', b'K', b'L', b'M', b'N', b'O', - b'P', b'Q', b'R', b'S', b'T', b'U', b'V', b'W', - b'X', b'Y', b'Z', - - b'{', b'|', b'}', b'~', 0x7f, - 0x80, 0x81, 0x82, 0x83, 0x84, 0x85, 0x86, 0x87, - 0x88, 0x89, 0x8a, 0x8b, 0x8c, 0x8d, 0x8e, 0x8f, - 0x90, 0x91, 0x92, 0x93, 0x94, 0x95, 0x96, 0x97, - 0x98, 0x99, 0x9a, 0x9b, 0x9c, 0x9d, 0x9e, 0x9f, - 0xa0, 0xa1, 0xa2, 0xa3, 0xa4, 0xa5, 0xa6, 0xa7, - 0xa8, 0xa9, 0xaa, 0xab, 0xac, 0xad, 0xae, 0xaf, - 0xb0, 0xb1, 0xb2, 0xb3, 0xb4, 0xb5, 0xb6, 0xb7, - 0xb8, 0xb9, 0xba, 0xbb, 0xbc, 0xbd, 0xbe, 0xbf, - 0xc0, 0xc1, 0xc2, 0xc3, 0xc4, 0xc5, 0xc6, 0xc7, - 0xc8, 0xc9, 0xca, 0xcb, 0xcc, 0xcd, 0xce, 0xcf, - 0xd0, 0xd1, 0xd2, 0xd3, 0xd4, 0xd5, 0xd6, 0xd7, - 0xd8, 0xd9, 0xda, 0xdb, 0xdc, 0xdd, 0xde, 0xdf, - 0xe0, 0xe1, 0xe2, 0xe3, 0xe4, 0xe5, 0xe6, 0xe7, - 0xe8, 0xe9, 0xea, 0xeb, 0xec, 0xed, 0xee, 0xef, - 0xf0, 0xf1, 0xf2, 0xf3, 0xf4, 0xf5, 0xf6, 0xf7, - 0xf8, 0xf9, 0xfa, 0xfb, 0xfc, 0xfd, 0xfe, 0xff, -]; - -enum AsciiCharacterClass { - C, // control - Cw, // control whitespace - W, // whitespace - D, // digit - L, // lowercase - Lx, // lowercase hex digit - U, // uppercase - Ux, // uppercase hex digit - P, // punctuation - N, // Non-ASCII -} -use self::AsciiCharacterClass::*; - -#[rustfmt::skip] -static ASCII_CHARACTER_CLASS: [AsciiCharacterClass; 256] = [ -// _0 _1 _2 _3 _4 _5 _6 _7 _8 _9 _a _b _c _d _e _f - C, C, C, C, C, C, C, C, C, Cw,Cw,C, Cw,Cw,C, C, // 0_ - C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, C, // 1_ - W, P, P, P, P, P, P, P, P, P, P, P, P, P, P, P, // 2_ - D, D, D, D, D, D, D, D, D, D, P, P, P, P, P, P, // 3_ - P, Ux,Ux,Ux,Ux,Ux,Ux,U, U, U, U, U, U, U, U, U, // 4_ - U, U, U, U, U, U, U, U, U, U, U, P, P, P, P, P, // 5_ - P, Lx,Lx,Lx,Lx,Lx,Lx,L, L, L, L, L, L, L, L, L, // 6_ - L, L, L, L, L, L, L, L, L, L, L, P, P, P, P, C, // 7_ - N, N, N, N, N, N, N, N, N, N, N, N, N, N, N, N, - N, N, N, N, N, N, N, N, N, N, N, N, N, N, N, N, - N, N, N, N, N, N, N, N, N, N, N, N, N, N, N, N, - N, N, N, N, N, N, N, N, N, N, N, N, N, N, N, N, - N, N, N, N, N, N, N, N, N, N, N, N, N, N, N, N, - N, N, N, N, N, N, N, N, N, N, N, N, N, N, N, N, - N, N, N, N, N, N, N, N, N, N, N, N, N, N, N, N, - N, N, N, N, N, N, N, N, N, N, N, N, N, N, N, N, -]; - -const ASCII_PATH: &[u8] = b"home/kyubey/rust/build/x86_64-unknown-linux-gnu/stage0/lib:/home/kyubey/workspace/rust/build/x86_64-unknown-linux-gnu/stage0-tools/release/deps"; -const RUST_INCANTATION: &[u8] = br#"AR_x86_64_unknown_linux_gnu="ar" CARGO_INCREMENTAL="0" CARGO_PROFILE_RELEASE_DEBUG="1" CARGO_PROFILE_RELEASE_DEBUG_ASSERTIONS="false" CARGO_PROFILE_RELEASE_OVERFLOW_CHECKS="false" CARGO_TARGET_DIR="/home/kyubey/workspace/rust/build/x86_64-unknown-linux-gnu/stage0-std" CC_x86_64_unknown_linux_gnu="cc" CFG_COMPILER_HOST_TRIPLE="x86_64-unknown-linux-gnu" CFG_RELEASE_CHANNEL="dev" CFLAGS_x86_64_unknown_linux_gnu="-ffunction-sections -fdata-sections -fPIC -m64" CXXFLAGS_x86_64_unknown_linux_gnu="-ffunction-sections -fdata-sections -fPIC -m64" CXX_x86_64_unknown_linux_gnu="c++" LD_LIBRARY_PATH="/home/kyubey/workspace/rust/build/x86_64-unknown-linux-gnu/stage0-sysroot/lib/rustlib/x86_64-unknown-linux-gnu/lib" LIBC_CHECK_CFG="1" RANLIB_x86_64_unknown_linux_gnu="ar s" REAL_LIBRARY_PATH_VAR="LD_LIBRARY_PATH" RUSTBUILD_NATIVE_DIR="/home/kyubey/workspace/rust/build/x86_64-unknown-linux-gnu/native" RUSTC="/home/kyubey/workspace/rust/build/bootstrap/debug/rustc" RUSTC_BOOTSTRAP="1" RUSTC_BREAK_ON_ICE="1" RUSTC_ERROR_METADATA_DST="/home/kyubey/workspace/rust/build/tmp/extended-error-metadata" RUSTC_FORCE_UNSTABLE="1" RUSTC_HOST_FUSE_LD_LLD="1" RUSTC_INSTALL_BINDIR="bin" RUSTC_LIBDIR="/home/kyubey/workspace/rust/build/x86_64-unknown-linux-gnu/stage0/lib" RUSTC_LINT_FLAGS="-Wrust_2018_idioms -Wunused_lifetimes -Wsemicolon_in_expressions_from_macros" RUSTC_REAL="/home/kyubey/workspace/rust/build/x86_64-unknown-linux-gnu/stage0/bin/rustc" RUSTC_SNAPSHOT="/home/kyubey/workspace/rust/build/x86_64-unknown-linux-gnu/stage0/bin/rustc" RUSTC_SNAPSHOT_LIBDIR="/home/kyubey/workspace/rust/build/x86_64-unknown-linux-gnu/stage0/lib" RUSTC_STAGE="0" RUSTC_SYSROOT="/home/kyubey/workspace/rust/build/x86_64-unknown-linux-gnu/stage0-sysroot" RUSTC_VERBOSE="0" RUSTDOC="/home/kyubey/workspace/rust/build/bootstrap/debug/rustdoc" RUSTDOCFLAGS="-C target-cpu=native --cfg=bootstrap -Csymbol-mangling-version=legacy -Zunstable-options -Zunstable-options --check-cfg=values(bootstrap) --check-cfg=values(stdarch_intel_sde) --check-cfg=values(no_fp_fmt_parse) --check-cfg=values(no_global_oom_handling) --check-cfg=values(no_rc) --check-cfg=values(no_sync) --check-cfg=values(freebsd12) --check-cfg=values(freebsd13) --check-cfg=values(backtrace_in_libstd) --check-cfg=values(target_env,\"libnx\") --check-cfg=values(target_arch,\"asmjs\",\"spirv\",\"nvptx\",\"xtensa\") -Clink-arg=-fuse-ld=lld -Clink-arg=-Wl,--threads=1 -Wrustdoc::invalid_codeblock_attributes --crate-version 1.72.0-dev -Zcrate-attr=doc(html_root_url=\"https://doc.rust-lang.org/nightly/\") -Zcrate-attr=warn(rust_2018_idioms)" RUSTDOC_FUSE_LD_LLD="1" RUSTDOC_LIBDIR="/home/kyubey/workspace/rust/build/x86_64-unknown-linux-gnu/stage0/lib" RUSTDOC_REAL="/path/to/nowhere/rustdoc/not/required" RUSTFLAGS="-C target-cpu=native --cfg=bootstrap -Csymbol-mangling-version=legacy -Zunstable-options -Zunstable-options --check-cfg=values(bootstrap) --check-cfg=values(stdarch_intel_sde) --check-cfg=values(no_fp_fmt_parse) --check-cfg=values(no_global_oom_handling) --check-cfg=values(no_rc) --check-cfg=values(no_sync) --check-cfg=values(freebsd12) --check-cfg=values(freebsd13) --check-cfg=values(backtrace_in_libstd) --check-cfg=values(target_env,\"libnx\") --check-cfg=values(target_arch,\"asmjs\",\"spirv\",\"nvptx\",\"xtensa\") -Zmacro-backtrace -Clink-args=-Wl,-z,origin -Clink-args=-Wl,-rpath,$ORIGIN/../lib -Clink-args=-fuse-ld=lld -Csplit-debuginfo=off -Cprefer-dynamic -Zinline-mir -Clto=off -Zcrate-attr=doc(html_root_url=\"https://doc.rust-lang.org/nightly/\")" RUST_COMPILER_RT_ROOT="/home/kyubey/workspace/rust/src/llvm-project/compiler-rt" RUST_TEST_THREADS="48" WINAPI_NO_BUNDLED_LIBRARIES="1" __CARGO_DEFAULT_LIB_METADATA="bootstrapstd" "/home/kyubey/workspace/rust/build/x86_64-unknown-linux-gnu/stage0/bin/cargo" "bench" "--target" "x86_64-unknown-linux-gnu" "-Zcheck-cfg=names,values,output" "-Zbinary-dep-depinfo" "-j" "48" "--features" " panic-unwind backtrace compiler-builtins-c" "--manifest-path" "/home/kyubey/workspace/rust/library/sysroot/Cargo.toml" "-p" "core" "--" "bench_ascii_escape_display" "--quiet" "-Z" "unstable-options" "--format" "json""#; - -#[bench] -fn bench_ascii_escape_display_no_escape(b: &mut Bencher) { - let mut writer = String::with_capacity(8 * 1024); - - b.iter(move || { - writer.clear(); - let iter = ASCII_PATH.escape_ascii(); - write!(writer, "{}", iter).unwrap(); - writer.len() - }) -} - -#[bench] -fn bench_ascii_escape_display_mixed(b: &mut Bencher) { - let mut writer = String::with_capacity(8 * 1024); - - b.iter(move || { - writer.clear(); - let iter = RUST_INCANTATION.escape_ascii(); - write!(writer, "{}", iter).unwrap(); - writer.len() - }) -} diff --git a/library/core/benches/ascii/is_ascii.rs b/library/core/benches/ascii/is_ascii.rs deleted file mode 100644 index a42a1dcfe3988..0000000000000 --- a/library/core/benches/ascii/is_ascii.rs +++ /dev/null @@ -1,82 +0,0 @@ -use super::{LONG, MEDIUM, SHORT}; -use test::black_box; -use test::Bencher; - -macro_rules! benches { - ($( fn $name: ident($arg: ident: &[u8]) $body: block )+) => { - benches!(mod short SHORT[..] $($name $arg $body)+); - benches!(mod medium MEDIUM[..] $($name $arg $body)+); - benches!(mod long LONG[..] $($name $arg $body)+); - // Ensure we benchmark cases where the functions are called with strings - // that are not perfectly aligned or have a length which is not a - // multiple of size_of::() (or both) - benches!(mod unaligned_head MEDIUM[1..] $($name $arg $body)+); - benches!(mod unaligned_tail MEDIUM[..(MEDIUM.len() - 1)] $($name $arg $body)+); - benches!(mod unaligned_both MEDIUM[1..(MEDIUM.len() - 1)] $($name $arg $body)+); - }; - - (mod $mod_name: ident $input: ident [$range: expr] $($name: ident $arg: ident $body: block)+) => { - mod $mod_name { - use super::*; - $( - #[bench] - fn $name(bencher: &mut Bencher) { - bencher.bytes = $input[$range].len() as u64; - let mut vec = $input.as_bytes().to_vec(); - bencher.iter(|| { - let $arg: &[u8] = &black_box(&mut vec)[$range]; - black_box($body) - }) - } - )+ - } - }; -} - -benches! { - fn case00_libcore(bytes: &[u8]) { - bytes.is_ascii() - } - - fn case01_iter_all(bytes: &[u8]) { - bytes.iter().all(|b| b.is_ascii()) - } - - fn case02_align_to(bytes: &[u8]) { - is_ascii_align_to(bytes) - } - - fn case03_align_to_unrolled(bytes: &[u8]) { - is_ascii_align_to_unrolled(bytes) - } -} - -// These are separate since it's easier to debug errors if they don't go through -// macro expansion first. -fn is_ascii_align_to(bytes: &[u8]) -> bool { - if bytes.len() < core::mem::size_of::() { - return bytes.iter().all(|b| b.is_ascii()); - } - // SAFETY: transmuting a sequence of `u8` to `usize` is always fine - let (head, body, tail) = unsafe { bytes.align_to::() }; - head.iter().all(|b| b.is_ascii()) - && body.iter().all(|w| !contains_nonascii(*w)) - && tail.iter().all(|b| b.is_ascii()) -} - -fn is_ascii_align_to_unrolled(bytes: &[u8]) -> bool { - if bytes.len() < core::mem::size_of::() { - return bytes.iter().all(|b| b.is_ascii()); - } - // SAFETY: transmuting a sequence of `u8` to `[usize; 2]` is always fine - let (head, body, tail) = unsafe { bytes.align_to::<[usize; 2]>() }; - head.iter().all(|b| b.is_ascii()) - && body.iter().all(|w| !contains_nonascii(w[0] | w[1])) - && tail.iter().all(|b| b.is_ascii()) -} - -#[inline] -fn contains_nonascii(v: usize) -> bool { - const NONASCII_MASK: usize = usize::from_ne_bytes([0x80; core::mem::size_of::()]); - (NONASCII_MASK & v) != 0 -} diff --git a/library/core/benches/char/methods.rs b/library/core/benches/char/methods.rs deleted file mode 100644 index 5d4df1ac8bd58..0000000000000 --- a/library/core/benches/char/methods.rs +++ /dev/null @@ -1,89 +0,0 @@ -use test::{black_box, Bencher}; - -const CHARS: [char; 9] = ['0', 'x', '2', '5', 'A', 'f', '7', '8', '9']; -const RADIX: [u32; 5] = [2, 8, 10, 16, 32]; - -#[bench] -fn bench_to_digit_radix_2(b: &mut Bencher) { - b.iter(|| CHARS.iter().cycle().take(10_000).map(|c| black_box(c).to_digit(2)).min()) -} - -#[bench] -fn bench_to_digit_radix_10(b: &mut Bencher) { - b.iter(|| CHARS.iter().cycle().take(10_000).map(|c| black_box(c).to_digit(10)).min()) -} - -#[bench] -fn bench_to_digit_radix_16(b: &mut Bencher) { - b.iter(|| CHARS.iter().cycle().take(10_000).map(|c| black_box(c).to_digit(16)).min()) -} - -#[bench] -fn bench_to_digit_radix_36(b: &mut Bencher) { - b.iter(|| CHARS.iter().cycle().take(10_000).map(|c| black_box(c).to_digit(36)).min()) -} - -#[bench] -fn bench_to_digit_radix_var(b: &mut Bencher) { - b.iter(|| { - CHARS - .iter() - .cycle() - .zip(RADIX.iter().cycle()) - .take(10_000) - .map(|(c, radix)| black_box(c).to_digit(*radix)) - .min() - }) -} - -#[bench] -fn bench_to_ascii_uppercase(b: &mut Bencher) { - b.iter(|| CHARS.iter().cycle().take(10_000).map(|c| black_box(c).to_ascii_uppercase()).min()) -} - -#[bench] -fn bench_to_ascii_lowercase(b: &mut Bencher) { - b.iter(|| CHARS.iter().cycle().take(10_000).map(|c| black_box(c).to_ascii_lowercase()).min()) -} - -#[bench] -fn bench_ascii_mix_to_uppercase(b: &mut Bencher) { - b.iter(|| { - (0..=255).cycle().take(10_000).map(|b| black_box(char::from(b)).to_uppercase()).count() - }) -} - -#[bench] -fn bench_ascii_mix_to_lowercase(b: &mut Bencher) { - b.iter(|| { - (0..=255).cycle().take(10_000).map(|b| black_box(char::from(b)).to_lowercase()).count() - }) -} - -#[bench] -fn bench_ascii_char_to_uppercase(b: &mut Bencher) { - b.iter(|| { - (0..=127).cycle().take(10_000).map(|b| black_box(char::from(b)).to_uppercase()).count() - }) -} - -#[bench] -fn bench_ascii_char_to_lowercase(b: &mut Bencher) { - b.iter(|| { - (0..=127).cycle().take(10_000).map(|b| black_box(char::from(b)).to_lowercase()).count() - }) -} - -#[bench] -fn bench_non_ascii_char_to_uppercase(b: &mut Bencher) { - b.iter(|| { - (128..=255).cycle().take(10_000).map(|b| black_box(char::from(b)).to_uppercase()).count() - }) -} - -#[bench] -fn bench_non_ascii_char_to_lowercase(b: &mut Bencher) { - b.iter(|| { - (128..=255).cycle().take(10_000).map(|b| black_box(char::from(b)).to_lowercase()).count() - }) -} diff --git a/library/core/benches/char/mod.rs b/library/core/benches/char/mod.rs deleted file mode 100644 index 9ca51a7684753..0000000000000 --- a/library/core/benches/char/mod.rs +++ /dev/null @@ -1 +0,0 @@ -mod methods; diff --git a/library/core/benches/fmt.rs b/library/core/benches/fmt.rs deleted file mode 100644 index d1cdb12e50f8c..0000000000000 --- a/library/core/benches/fmt.rs +++ /dev/null @@ -1,150 +0,0 @@ -use std::fmt::{self, Write as FmtWrite}; -use std::io::{self, Write as IoWrite}; -use test::{black_box, Bencher}; - -#[bench] -fn write_vec_value(bh: &mut Bencher) { - bh.iter(|| { - let mut mem = Vec::new(); - for _ in 0..1000 { - mem.write_all(black_box("abc").as_bytes()).unwrap(); - } - }); -} - -#[bench] -fn write_vec_ref(bh: &mut Bencher) { - bh.iter(|| { - let mut mem = Vec::new(); - let wr = &mut mem as &mut dyn io::Write; - for _ in 0..1000 { - wr.write_all(black_box("abc").as_bytes()).unwrap(); - } - }); -} - -#[bench] -fn write_vec_macro1(bh: &mut Bencher) { - bh.iter(|| { - let mut mem = Vec::new(); - let wr = &mut mem as &mut dyn io::Write; - for _ in 0..1000 { - write!(wr, "{}", black_box("abc")).unwrap(); - } - }); -} - -#[bench] -fn write_vec_macro2(bh: &mut Bencher) { - bh.iter(|| { - let mut mem = Vec::new(); - let wr = &mut mem as &mut dyn io::Write; - for _ in 0..1000 { - write!(wr, "{}", black_box("abc")).unwrap(); - } - }); -} - -#[bench] -fn write_vec_macro_debug(bh: &mut Bencher) { - bh.iter(|| { - let mut mem = Vec::new(); - let wr = &mut mem as &mut dyn io::Write; - for _ in 0..1000 { - write!(wr, "{:?}", black_box("☃")).unwrap(); - } - }); -} - -#[bench] -fn write_str_value(bh: &mut Bencher) { - bh.iter(|| { - let mut mem = String::new(); - for _ in 0..1000 { - mem.write_str(black_box("abc")).unwrap(); - } - }); -} - -#[bench] -fn write_str_ref(bh: &mut Bencher) { - bh.iter(|| { - let mut mem = String::new(); - let wr = &mut mem as &mut dyn fmt::Write; - for _ in 0..1000 { - wr.write_str(black_box("abc")).unwrap(); - } - }); -} - -#[bench] -fn write_str_macro1(bh: &mut Bencher) { - bh.iter(|| { - let mut mem = String::new(); - for _ in 0..1000 { - write!(mem, "{}", black_box("abc")).unwrap(); - } - }); -} - -#[bench] -fn write_str_macro2(bh: &mut Bencher) { - bh.iter(|| { - let mut mem = String::new(); - let wr = &mut mem as &mut dyn fmt::Write; - for _ in 0..1000 { - write!(wr, "{}", black_box("abc")).unwrap(); - } - }); -} - -#[bench] -fn write_str_macro_debug(bh: &mut Bencher) { - bh.iter(|| { - let mut mem = String::new(); - let wr = &mut mem as &mut dyn fmt::Write; - for _ in 0..1000 { - write!(wr, "{:?}", black_box("☃")).unwrap(); - } - }); -} - -#[bench] -fn write_str_macro_debug_ascii(bh: &mut Bencher) { - bh.iter(|| { - let mut mem = String::new(); - let wr = &mut mem as &mut dyn fmt::Write; - for _ in 0..1000 { - write!(wr, "{:?}", black_box("Hello, World!")).unwrap(); - } - }); -} - -#[bench] -fn write_u128_max(bh: &mut Bencher) { - bh.iter(|| { - test::black_box(format!("{}", u128::MAX)); - }); -} - -#[bench] -fn write_u128_min(bh: &mut Bencher) { - bh.iter(|| { - let s = format!("{}", 0u128); - test::black_box(s); - }); -} - -#[bench] -fn write_u64_max(bh: &mut Bencher) { - bh.iter(|| { - test::black_box(format!("{}", u64::MAX)); - }); -} - -#[bench] -fn write_u64_min(bh: &mut Bencher) { - bh.iter(|| { - test::black_box(format!("{}", 0u64)); - }); -} diff --git a/library/core/benches/hash/mod.rs b/library/core/benches/hash/mod.rs deleted file mode 100644 index 4f2e152b69526..0000000000000 --- a/library/core/benches/hash/mod.rs +++ /dev/null @@ -1 +0,0 @@ -mod sip; diff --git a/library/core/benches/hash/sip.rs b/library/core/benches/hash/sip.rs deleted file mode 100644 index 725c864dce9f1..0000000000000 --- a/library/core/benches/hash/sip.rs +++ /dev/null @@ -1,123 +0,0 @@ -#![allow(deprecated)] - -use core::hash::*; -use test::{black_box, Bencher}; - -fn hash_bytes(mut s: H, x: &[u8]) -> u64 { - Hasher::write(&mut s, x); - s.finish() -} - -fn hash_with(mut st: H, x: &T) -> u64 { - x.hash(&mut st); - st.finish() -} - -fn hash(x: &T) -> u64 { - hash_with(SipHasher::new(), x) -} - -#[bench] -fn bench_str_under_8_bytes(b: &mut Bencher) { - let s = "foo"; - b.iter(|| { - assert_eq!(hash(&s), 16262950014981195938); - }) -} - -#[bench] -fn bench_str_of_8_bytes(b: &mut Bencher) { - let s = "foobar78"; - b.iter(|| { - assert_eq!(hash(&s), 4898293253460910787); - }) -} - -#[bench] -fn bench_str_over_8_bytes(b: &mut Bencher) { - let s = "foobarbaz0"; - b.iter(|| { - assert_eq!(hash(&s), 10581415515220175264); - }) -} - -#[bench] -fn bench_long_str(b: &mut Bencher) { - let s = "Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor \ - incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud \ - exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute \ - irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla \ - pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui \ - officia deserunt mollit anim id est laborum."; - b.iter(|| { - assert_eq!(hash(&s), 17717065544121360093); - }) -} - -#[bench] -fn bench_u32(b: &mut Bencher) { - let u = 162629500u32; - let u = black_box(u); - b.iter(|| hash(&u)); - b.bytes = 8; -} - -#[bench] -fn bench_u32_keyed(b: &mut Bencher) { - let u = 162629500u32; - let u = black_box(u); - let k1 = black_box(0x1); - let k2 = black_box(0x2); - b.iter(|| hash_with(SipHasher::new_with_keys(k1, k2), &u)); - b.bytes = 8; -} - -#[bench] -fn bench_u64(b: &mut Bencher) { - let u = 16262950014981195938u64; - let u = black_box(u); - b.iter(|| hash(&u)); - b.bytes = 8; -} - -#[bench] -fn bench_bytes_4(b: &mut Bencher) { - let data = black_box([b' '; 4]); - b.iter(|| hash_bytes(SipHasher::default(), &data)); - b.bytes = 4; -} - -#[bench] -fn bench_bytes_7(b: &mut Bencher) { - let data = black_box([b' '; 7]); - b.iter(|| hash_bytes(SipHasher::default(), &data)); - b.bytes = 7; -} - -#[bench] -fn bench_bytes_8(b: &mut Bencher) { - let data = black_box([b' '; 8]); - b.iter(|| hash_bytes(SipHasher::default(), &data)); - b.bytes = 8; -} - -#[bench] -fn bench_bytes_a_16(b: &mut Bencher) { - let data = black_box([b' '; 16]); - b.iter(|| hash_bytes(SipHasher::default(), &data)); - b.bytes = 16; -} - -#[bench] -fn bench_bytes_b_32(b: &mut Bencher) { - let data = black_box([b' '; 32]); - b.iter(|| hash_bytes(SipHasher::default(), &data)); - b.bytes = 32; -} - -#[bench] -fn bench_bytes_c_128(b: &mut Bencher) { - let data = black_box([b' '; 128]); - b.iter(|| hash_bytes(SipHasher::default(), &data)); - b.bytes = 128; -} diff --git a/library/core/benches/iter.rs b/library/core/benches/iter.rs deleted file mode 100644 index c1cec5e6d3c8c..0000000000000 --- a/library/core/benches/iter.rs +++ /dev/null @@ -1,547 +0,0 @@ -use core::borrow::Borrow; -use core::iter::*; -use core::mem; -use core::num::Wrapping; -use core::ops::Range; -use test::{black_box, Bencher}; - -#[bench] -fn bench_rposition(b: &mut Bencher) { - let it: Vec = (0..300).collect(); - b.iter(|| { - it.iter().rposition(|&x| x <= 150); - }); -} - -#[bench] -fn bench_skip_while(b: &mut Bencher) { - b.iter(|| { - let it = 0..100; - let mut sum = 0; - it.skip_while(|&x| { - sum += x; - sum < 4000 - }) - .all(|_| true); - }); -} - -#[bench] -fn bench_multiple_take(b: &mut Bencher) { - let mut it = (0..42).cycle(); - b.iter(|| { - let n = it.next().unwrap(); - for _ in 0..n { - it.clone().take(it.next().unwrap()).all(|_| true); - } - }); -} - -fn scatter(x: i32) -> i32 { - (x * 31) % 127 -} - -#[bench] -fn bench_max_by_key(b: &mut Bencher) { - b.iter(|| { - let it = 0..100; - it.map(black_box).max_by_key(|&x| scatter(x)) - }) -} - -// https://www.reddit.com/r/rust/comments/31syce/using_iterators_to_find_the_index_of_the_min_or/ -#[bench] -fn bench_max_by_key2(b: &mut Bencher) { - fn max_index_iter(array: &[i32]) -> usize { - array.iter().enumerate().max_by_key(|&(_, item)| item).unwrap().0 - } - - let mut data = vec![0; 1638]; - data[514] = 9999; - - b.iter(|| max_index_iter(&data)); -} - -#[bench] -fn bench_max(b: &mut Bencher) { - b.iter(|| { - let it = 0..100; - it.map(black_box).map(scatter).max() - }) -} - -#[bench] -fn bench_range_step_by_sum_reducible(b: &mut Bencher) { - let r = 0u32..1024; - b.iter(|| { - let r = black_box(r.clone()).step_by(8); - - let mut sum: u32 = 0; - for i in r { - sum += i; - } - - sum - }) -} - -#[bench] -fn bench_range_step_by_loop_u32(b: &mut Bencher) { - let r = 0..(u16::MAX as u32); - b.iter(|| { - let r = black_box(r.clone()).step_by(64); - - let mut sum: u32 = 0; - for i in r { - let i = i ^ i.wrapping_sub(1); - sum = sum.wrapping_add(i); - } - - sum - }) -} - -#[bench] -fn bench_range_step_by_fold_usize(b: &mut Bencher) { - let r: Range = 0..(u16::MAX as usize); - b.iter(|| { - let r = black_box(r.clone()); - r.step_by(64) - .map(|x: usize| x ^ (x.wrapping_sub(1))) - .fold(0usize, |acc, i| acc.wrapping_add(i)) - }) -} - -#[bench] -fn bench_range_step_by_fold_u16(b: &mut Bencher) { - let r: Range = 0..u16::MAX; - b.iter(|| { - let r = black_box(r.clone()); - r.step_by(64).map(|x: u16| x ^ (x.wrapping_sub(1))).fold(0u16, |acc, i| acc.wrapping_add(i)) - }) -} - -pub fn copy_zip(xs: &[u8], ys: &mut [u8]) { - for (a, b) in ys.iter_mut().zip(xs) { - *a = *b; - } -} - -pub fn add_zip(xs: &[f32], ys: &mut [f32]) { - for (a, b) in ys.iter_mut().zip(xs) { - *a += *b; - } -} - -#[bench] -fn bench_zip_copy(b: &mut Bencher) { - let source = vec![0u8; 16 * 1024]; - let mut dst = black_box(vec![0u8; 16 * 1024]); - b.iter(|| copy_zip(&source, &mut dst)) -} - -#[bench] -fn bench_zip_add(b: &mut Bencher) { - let source = vec![1.; 16 * 1024]; - let mut dst = vec![0.; 16 * 1024]; - b.iter(|| add_zip(&source, &mut dst)); -} - -/// `Iterator::for_each` implemented as a plain loop. -fn for_each_loop(iter: I, mut f: F) -where - I: Iterator, - F: FnMut(I::Item), -{ - for item in iter { - f(item); - } -} - -/// `Iterator::for_each` implemented with `fold` for internal iteration. -/// (except when `by_ref()` effectively disables that optimization.) -fn for_each_fold(iter: I, mut f: F) -where - I: Iterator, - F: FnMut(I::Item), -{ - iter.fold((), move |(), item| f(item)); -} - -#[bench] -fn bench_for_each_chain_loop(b: &mut Bencher) { - b.iter(|| { - let mut acc = 0; - let iter = (0i64..1000000).chain(0..1000000).map(black_box); - for_each_loop(iter, |x| acc += x); - acc - }); -} - -#[bench] -fn bench_for_each_chain_fold(b: &mut Bencher) { - b.iter(|| { - let mut acc = 0; - let iter = (0i64..1000000).chain(0..1000000).map(black_box); - for_each_fold(iter, |x| acc += x); - acc - }); -} - -#[bench] -fn bench_for_each_chain_ref_fold(b: &mut Bencher) { - b.iter(|| { - let mut acc = 0; - let mut iter = (0i64..1000000).chain(0..1000000).map(black_box); - for_each_fold(iter.by_ref(), |x| acc += x); - acc - }); -} - -/// Helper to benchmark `sum` for iterators taken by value which -/// can optimize `fold`, and by reference which cannot. -macro_rules! bench_sums { - ($bench_sum:ident, $bench_ref_sum:ident, $iter:expr) => { - #[bench] - fn $bench_sum(b: &mut Bencher) { - b.iter(|| -> i64 { $iter.map(black_box).sum() }); - } - - #[bench] - fn $bench_ref_sum(b: &mut Bencher) { - b.iter(|| -> i64 { $iter.map(black_box).by_ref().sum() }); - } - }; -} - -bench_sums! { - bench_flat_map_sum, - bench_flat_map_ref_sum, - (0i64..1000).flat_map(|x| x..x+1000) -} - -bench_sums! { - bench_flat_map_chain_sum, - bench_flat_map_chain_ref_sum, - (0i64..1000000).flat_map(|x| once(x).chain(once(x))) -} - -bench_sums! { - bench_enumerate_sum, - bench_enumerate_ref_sum, - (0i64..1000000).enumerate().map(|(i, x)| x * i as i64) -} - -bench_sums! { - bench_enumerate_chain_sum, - bench_enumerate_chain_ref_sum, - (0i64..1000000).chain(0..1000000).enumerate().map(|(i, x)| x * i as i64) -} - -bench_sums! { - bench_filter_sum, - bench_filter_ref_sum, - (0i64..1000000).filter(|x| x % 3 == 0) -} - -bench_sums! { - bench_filter_chain_sum, - bench_filter_chain_ref_sum, - (0i64..1000000).chain(0..1000000).filter(|x| x % 3 == 0) -} - -bench_sums! { - bench_filter_map_sum, - bench_filter_map_ref_sum, - (0i64..1000000).filter_map(|x| x.checked_mul(x)) -} - -bench_sums! { - bench_filter_map_chain_sum, - bench_filter_map_chain_ref_sum, - (0i64..1000000).chain(0..1000000).filter_map(|x| x.checked_mul(x)) -} - -bench_sums! { - bench_fuse_sum, - bench_fuse_ref_sum, - (0i64..1000000).fuse() -} - -bench_sums! { - bench_fuse_chain_sum, - bench_fuse_chain_ref_sum, - (0i64..1000000).chain(0..1000000).fuse() -} - -bench_sums! { - bench_inspect_sum, - bench_inspect_ref_sum, - (0i64..1000000).inspect(|_| {}) -} - -bench_sums! { - bench_inspect_chain_sum, - bench_inspect_chain_ref_sum, - (0i64..1000000).chain(0..1000000).inspect(|_| {}) -} - -bench_sums! { - bench_peekable_sum, - bench_peekable_ref_sum, - (0i64..1000000).peekable() -} - -bench_sums! { - bench_peekable_chain_sum, - bench_peekable_chain_ref_sum, - (0i64..1000000).chain(0..1000000).peekable() -} - -bench_sums! { - bench_skip_sum, - bench_skip_ref_sum, - (0i64..1000000).skip(1000) -} - -bench_sums! { - bench_skip_chain_sum, - bench_skip_chain_ref_sum, - (0i64..1000000).chain(0..1000000).skip(1000) -} - -bench_sums! { - bench_skip_while_sum, - bench_skip_while_ref_sum, - (0i64..1000000).skip_while(|&x| x < 1000) -} - -bench_sums! { - bench_skip_while_chain_sum, - bench_skip_while_chain_ref_sum, - (0i64..1000000).chain(0..1000000).skip_while(|&x| x < 1000) -} - -bench_sums! { - bench_take_while_chain_sum, - bench_take_while_chain_ref_sum, - (0i64..1000000).chain(1000000..).take_while(|&x| x < 1111111) -} - -bench_sums! { - bench_cycle_take_sum, - bench_cycle_take_ref_sum, - (0..10000).cycle().take(1000000) -} - -bench_sums! { - bench_cycle_skip_take_sum, - bench_cycle_skip_take_ref_sum, - (0..100000).cycle().skip(1000000).take(1000000) -} - -bench_sums! { - bench_cycle_take_skip_sum, - bench_cycle_take_skip_ref_sum, - (0..100000).cycle().take(1000000).skip(100000) -} - -bench_sums! { - bench_skip_cycle_skip_zip_add_sum, - bench_skip_cycle_skip_zip_add_ref_sum, - (0..100000).skip(100).cycle().skip(100) - .zip((0..100000).cycle().skip(10)) - .map(|(a,b)| a+b) - .skip(100000) - .take(1000000) -} - -// Checks whether Skip> is as fast as Zip, Skip>, from -// https://users.rust-lang.org/t/performance-difference-between-iterator-zip-and-skip-order/15743 -#[bench] -fn bench_zip_then_skip(b: &mut Bencher) { - let v: Vec<_> = (0..100_000).collect(); - let t: Vec<_> = (0..100_000).collect(); - - b.iter(|| { - let s = v - .iter() - .zip(t.iter()) - .skip(10000) - .take_while(|t| *t.0 < 10100) - .map(|(a, b)| *a + *b) - .sum::(); - assert_eq!(s, 2009900); - }); -} -#[bench] -fn bench_skip_then_zip(b: &mut Bencher) { - let v: Vec<_> = (0..100_000).collect(); - let t: Vec<_> = (0..100_000).collect(); - - b.iter(|| { - let s = v - .iter() - .skip(10000) - .zip(t.iter().skip(10000)) - .take_while(|t| *t.0 < 10100) - .map(|(a, b)| *a + *b) - .sum::(); - assert_eq!(s, 2009900); - }); -} - -#[bench] -fn bench_skip_trusted_random_access(b: &mut Bencher) { - let v: Vec = black_box(vec![42; 10000]); - let mut sink = [0; 10000]; - - b.iter(|| { - for (val, idx) in v.iter().skip(8).zip(0..10000) { - sink[idx] += val; - } - sink - }); -} - -#[bench] -fn bench_filter_count(b: &mut Bencher) { - b.iter(|| (0i64..1000000).map(black_box).filter(|x| x % 3 == 0).count()) -} - -#[bench] -fn bench_filter_ref_count(b: &mut Bencher) { - b.iter(|| (0i64..1000000).map(black_box).by_ref().filter(|x| x % 3 == 0).count()) -} - -#[bench] -fn bench_filter_chain_count(b: &mut Bencher) { - b.iter(|| (0i64..1000000).chain(0..1000000).map(black_box).filter(|x| x % 3 == 0).count()) -} - -#[bench] -fn bench_filter_chain_ref_count(b: &mut Bencher) { - b.iter(|| { - (0i64..1000000).chain(0..1000000).map(black_box).by_ref().filter(|x| x % 3 == 0).count() - }) -} - -#[bench] -fn bench_partial_cmp(b: &mut Bencher) { - b.iter(|| (0..100000).map(black_box).partial_cmp((0..100000).map(black_box))) -} - -#[bench] -fn bench_chain_partial_cmp(b: &mut Bencher) { - b.iter(|| { - (0..50000).chain(50000..100000).map(black_box).partial_cmp((0..100000).map(black_box)) - }) -} - -#[bench] -fn bench_lt(b: &mut Bencher) { - b.iter(|| (0..100000).map(black_box).lt((0..100000).map(black_box))) -} - -#[bench] -fn bench_trusted_random_access_adapters(b: &mut Bencher) { - let vec1: Vec<_> = (0usize..100000).collect(); - let vec2 = black_box(vec1.clone()); - b.iter(|| { - let mut iter = vec1 - .iter() - .copied() - .enumerate() - .map(|(idx, e)| idx.wrapping_add(e)) - .zip(vec2.iter().copied()) - .map(|(a, b)| a.wrapping_add(b)) - .fuse(); - let mut acc: usize = 0; - let size = iter.size(); - for i in 0..size { - // SAFETY: TRA requirements are satisfied by 0..size iteration and then dropping the - // iterator. - acc = acc.wrapping_add(unsafe { iter.__iterator_get_unchecked(i) }); - } - acc - }) -} - -/// Exercises the iter::Copied specialization for slice::Iter -#[bench] -fn bench_next_chunk_copied(b: &mut Bencher) { - let v = vec![1u8; 1024]; - - b.iter(|| { - let mut iter = black_box(&v).iter().copied(); - let mut acc = Wrapping(0); - // This uses a while-let loop to side-step the TRA specialization in ArrayChunks - while let Ok(chunk) = iter.next_chunk::<{ mem::size_of::() }>() { - let d = u64::from_ne_bytes(chunk); - acc += Wrapping(d.rotate_left(7).wrapping_add(1)); - } - acc - }) -} - -/// Exercises the TrustedRandomAccess specialization in ArrayChunks -#[bench] -#[allow(noop_method_call)] -fn bench_next_chunk_trusted_random_access(b: &mut Bencher) { - let v = vec![1u8; 1024]; - - b.iter(|| { - black_box(&v) - .iter() - // this shows that we're not relying on the slice::Iter specialization in Copied - .map(|b| *b.borrow()) - .array_chunks::<{ mem::size_of::() }>() - .map(|ary| { - let d = u64::from_ne_bytes(ary); - Wrapping(d.rotate_left(7).wrapping_add(1)) - }) - .sum::>() - }) -} - -#[bench] -fn bench_next_chunk_filter_even(b: &mut Bencher) { - let a = (0..1024).next_chunk::<1024>().unwrap(); - - b.iter(|| black_box(&a).iter().filter(|&&i| i % 2 == 0).next_chunk::<32>()) -} - -#[bench] -fn bench_next_chunk_filter_predictably_true(b: &mut Bencher) { - let a = (0..1024).next_chunk::<1024>().unwrap(); - - b.iter(|| black_box(&a).iter().filter(|&&i| i < 100).next_chunk::<32>()) -} - -#[bench] -fn bench_next_chunk_filter_mostly_false(b: &mut Bencher) { - let a = (0..1024).next_chunk::<1024>().unwrap(); - - b.iter(|| black_box(&a).iter().filter(|&&i| i > 900).next_chunk::<32>()) -} - -#[bench] -fn bench_next_chunk_filter_map_even(b: &mut Bencher) { - let a = (0..1024).next_chunk::<1024>().unwrap(); - - b.iter(|| black_box(&a).iter().filter_map(|&i| (i % 2 == 0).then(|| i)).next_chunk::<32>()) -} - -#[bench] -fn bench_next_chunk_filter_map_predictably_true(b: &mut Bencher) { - let a = (0..1024).next_chunk::<1024>().unwrap(); - - b.iter(|| black_box(&a).iter().filter_map(|&i| (i < 100).then(|| i)).next_chunk::<32>()) -} - -#[bench] -fn bench_next_chunk_filter_map_mostly_false(b: &mut Bencher) { - let a = (0..1024).next_chunk::<1024>().unwrap(); - - b.iter(|| black_box(&a).iter().filter_map(|&i| (i > 900).then(|| i)).next_chunk::<32>()) -} diff --git a/library/core/benches/lib.rs b/library/core/benches/lib.rs deleted file mode 100644 index 32d15c386cb1b..0000000000000 --- a/library/core/benches/lib.rs +++ /dev/null @@ -1,35 +0,0 @@ -// wasm32 does not support benches (no time). -#![cfg(not(target_arch = "wasm32"))] -// Disabling in Miri as these would take too long. -#![cfg(not(miri))] -#![feature(flt2dec)] -#![feature(test)] -#![feature(trusted_random_access)] -#![feature(iter_array_chunks)] -#![feature(iter_next_chunk)] -#![feature(iter_advance_by)] - -extern crate test; - -mod any; -mod array; -mod ascii; -mod char; -mod fmt; -mod hash; -mod iter; -mod net; -mod num; -mod ops; -mod pattern; -mod slice; -mod str; -mod tuple; - -/// Returns a `rand::Rng` seeded with a consistent seed. -/// -/// This is done to avoid introducing nondeterminism in benchmark results. -fn bench_rng() -> rand_xorshift::XorShiftRng { - const SEED: [u8; 16] = [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15]; - rand::SeedableRng::from_seed(SEED) -} diff --git a/library/core/benches/net/addr_parser.rs b/library/core/benches/net/addr_parser.rs deleted file mode 100644 index b9406a9779dc6..0000000000000 --- a/library/core/benches/net/addr_parser.rs +++ /dev/null @@ -1,78 +0,0 @@ -use core::net::{IpAddr, Ipv4Addr, Ipv6Addr, SocketAddr, SocketAddrV4, SocketAddrV6}; -use core::str::FromStr; - -use test::{black_box, Bencher}; - -const IPV4_STR: &str = "192.168.0.1"; -const IPV4_STR_PORT: &str = "192.168.0.1:8080"; - -const IPV6_STR_FULL: &str = "2001:db8:0:0:0:0:c0a8:1"; -const IPV6_STR_COMPRESS: &str = "2001:db8::c0a8:1"; -const IPV6_STR_V4: &str = "2001:db8::192.168.0.1"; -const IPV6_STR_PORT: &str = "[2001:db8::c0a8:1]:8080"; -const IPV6_STR_PORT_SCOPE_ID: &str = "[2001:db8::c0a8:1%1337]:8080"; - -#[bench] -fn bench_parse_ipv4(b: &mut Bencher) { - b.iter(|| Ipv4Addr::from_str(black_box(IPV4_STR))); -} - -#[bench] -fn bench_parse_ipv6_full(b: &mut Bencher) { - b.iter(|| Ipv6Addr::from_str(black_box(IPV6_STR_FULL))); -} - -#[bench] -fn bench_parse_ipv6_compress(b: &mut Bencher) { - b.iter(|| Ipv6Addr::from_str(black_box(IPV6_STR_COMPRESS))); -} - -#[bench] -fn bench_parse_ipv6_v4(b: &mut Bencher) { - b.iter(|| Ipv6Addr::from_str(black_box(IPV6_STR_V4))); -} - -#[bench] -fn bench_parse_ipaddr_v4(b: &mut Bencher) { - b.iter(|| IpAddr::from_str(black_box(IPV4_STR))); -} - -#[bench] -fn bench_parse_ipaddr_v6_full(b: &mut Bencher) { - b.iter(|| IpAddr::from_str(black_box(IPV6_STR_FULL))); -} - -#[bench] -fn bench_parse_ipaddr_v6_compress(b: &mut Bencher) { - b.iter(|| IpAddr::from_str(black_box(IPV6_STR_COMPRESS))); -} - -#[bench] -fn bench_parse_ipaddr_v6_v4(b: &mut Bencher) { - b.iter(|| IpAddr::from_str(black_box(IPV6_STR_V4))); -} - -#[bench] -fn bench_parse_socket_v4(b: &mut Bencher) { - b.iter(|| SocketAddrV4::from_str(black_box(IPV4_STR_PORT))); -} - -#[bench] -fn bench_parse_socket_v6(b: &mut Bencher) { - b.iter(|| SocketAddrV6::from_str(black_box(IPV6_STR_PORT))); -} - -#[bench] -fn bench_parse_socket_v6_scope_id(b: &mut Bencher) { - b.iter(|| SocketAddrV6::from_str(black_box(IPV6_STR_PORT_SCOPE_ID))); -} - -#[bench] -fn bench_parse_socketaddr_v4(b: &mut Bencher) { - b.iter(|| SocketAddr::from_str(black_box(IPV4_STR_PORT))); -} - -#[bench] -fn bench_parse_socketaddr_v6(b: &mut Bencher) { - b.iter(|| SocketAddr::from_str(black_box(IPV6_STR_PORT))); -} diff --git a/library/core/benches/net/mod.rs b/library/core/benches/net/mod.rs deleted file mode 100644 index c29aed46ccdb8..0000000000000 --- a/library/core/benches/net/mod.rs +++ /dev/null @@ -1 +0,0 @@ -mod addr_parser; diff --git a/library/core/benches/num/dec2flt/mod.rs b/library/core/benches/num/dec2flt/mod.rs deleted file mode 100644 index fb4a786b27e3d..0000000000000 --- a/library/core/benches/num/dec2flt/mod.rs +++ /dev/null @@ -1,57 +0,0 @@ -use test::{black_box, Bencher}; - -#[bench] -fn bench_0(b: &mut Bencher) { - b.iter(|| black_box("0.0").parse::()); -} - -#[bench] -fn bench_42(b: &mut Bencher) { - b.iter(|| black_box("42").parse::()); -} - -#[bench] -fn bench_huge_int(b: &mut Bencher) { - // 2^128 - 1 - b.iter(|| black_box("170141183460469231731687303715884105727").parse::()); -} - -#[bench] -fn bench_short_decimal(b: &mut Bencher) { - b.iter(|| black_box("1234.5678").parse::()); -} - -#[bench] -fn bench_pi_long(b: &mut Bencher) { - b.iter(|| black_box("3.14159265358979323846264338327950288").parse::()); -} - -#[bench] -fn bench_pi_short(b: &mut Bencher) { - b.iter(|| black_box("3.141592653589793").parse::()) -} - -#[bench] -fn bench_1e150(b: &mut Bencher) { - b.iter(|| black_box("1e150").parse::()); -} - -#[bench] -fn bench_long_decimal_and_exp(b: &mut Bencher) { - b.iter(|| black_box("727501488517303786137132964064381141071e-123").parse::()); -} - -#[bench] -fn bench_min_subnormal(b: &mut Bencher) { - b.iter(|| black_box("5e-324").parse::()); -} - -#[bench] -fn bench_min_normal(b: &mut Bencher) { - b.iter(|| black_box("2.2250738585072014e-308").parse::()); -} - -#[bench] -fn bench_max(b: &mut Bencher) { - b.iter(|| black_box("1.7976931348623157e308").parse::()); -} diff --git a/library/core/benches/num/flt2dec/mod.rs b/library/core/benches/num/flt2dec/mod.rs deleted file mode 100644 index b1a9fc56bae54..0000000000000 --- a/library/core/benches/num/flt2dec/mod.rs +++ /dev/null @@ -1,36 +0,0 @@ -mod strategy { - mod dragon; - mod grisu; -} - -use core::num::flt2dec::MAX_SIG_DIGITS; -use core::num::flt2dec::{decode, DecodableFloat, Decoded, FullDecoded}; -use std::io::Write; -use test::{black_box, Bencher}; - -pub fn decode_finite(v: T) -> Decoded { - match decode(v).1 { - FullDecoded::Finite(decoded) => decoded, - full_decoded => panic!("expected finite, got {full_decoded:?} instead"), - } -} - -#[bench] -fn bench_small_shortest(b: &mut Bencher) { - let mut buf = Vec::with_capacity(20); - - b.iter(|| { - buf.clear(); - write!(black_box(&mut buf), "{}", black_box(3.1415926f64)).unwrap() - }); -} - -#[bench] -fn bench_big_shortest(b: &mut Bencher) { - let mut buf = Vec::with_capacity(300); - - b.iter(|| { - buf.clear(); - write!(black_box(&mut buf), "{}", black_box(f64::MAX)).unwrap() - }); -} diff --git a/library/core/benches/num/flt2dec/strategy/dragon.rs b/library/core/benches/num/flt2dec/strategy/dragon.rs deleted file mode 100644 index babedc6c0ec80..0000000000000 --- a/library/core/benches/num/flt2dec/strategy/dragon.rs +++ /dev/null @@ -1,75 +0,0 @@ -use super::super::*; -use core::num::flt2dec::strategy::dragon::*; -use std::mem::MaybeUninit; - -#[bench] -fn bench_small_shortest(b: &mut Bencher) { - let decoded = decode_finite(3.141592f64); - let mut buf = [MaybeUninit::new(0); MAX_SIG_DIGITS]; - b.iter(|| { - format_shortest(black_box(&decoded), &mut buf); - }); -} - -#[bench] -fn bench_big_shortest(b: &mut Bencher) { - let decoded = decode_finite(f64::MAX); - let mut buf = [MaybeUninit::new(0); MAX_SIG_DIGITS]; - b.iter(|| { - format_shortest(black_box(&decoded), &mut buf); - }); -} - -#[bench] -fn bench_small_exact_3(b: &mut Bencher) { - let decoded = decode_finite(3.141592f64); - let mut buf = [MaybeUninit::new(0); 3]; - b.iter(|| { - format_exact(black_box(&decoded), &mut buf, i16::MIN); - }); -} - -#[bench] -fn bench_big_exact_3(b: &mut Bencher) { - let decoded = decode_finite(f64::MAX); - let mut buf = [MaybeUninit::new(0); 3]; - b.iter(|| { - format_exact(black_box(&decoded), &mut buf, i16::MIN); - }); -} - -#[bench] -fn bench_small_exact_12(b: &mut Bencher) { - let decoded = decode_finite(3.141592f64); - let mut buf = [MaybeUninit::new(0); 12]; - b.iter(|| { - format_exact(black_box(&decoded), &mut buf, i16::MIN); - }); -} - -#[bench] -fn bench_big_exact_12(b: &mut Bencher) { - let decoded = decode_finite(f64::MAX); - let mut buf = [MaybeUninit::new(0); 12]; - b.iter(|| { - format_exact(black_box(&decoded), &mut buf, i16::MIN); - }); -} - -#[bench] -fn bench_small_exact_inf(b: &mut Bencher) { - let decoded = decode_finite(3.141592f64); - let mut buf = [MaybeUninit::new(0); 1024]; - b.iter(|| { - format_exact(black_box(&decoded), &mut buf, i16::MIN); - }); -} - -#[bench] -fn bench_big_exact_inf(b: &mut Bencher) { - let decoded = decode_finite(f64::MAX); - let mut buf = [MaybeUninit::new(0); 1024]; - b.iter(|| { - format_exact(black_box(&decoded), &mut buf, i16::MIN); - }); -} diff --git a/library/core/benches/num/flt2dec/strategy/grisu.rs b/library/core/benches/num/flt2dec/strategy/grisu.rs deleted file mode 100644 index b5bddb2c7c746..0000000000000 --- a/library/core/benches/num/flt2dec/strategy/grisu.rs +++ /dev/null @@ -1,109 +0,0 @@ -use super::super::*; -use core::num::flt2dec::strategy::grisu::*; -use std::mem::MaybeUninit; - -pub fn decode_finite(v: T) -> Decoded { - match decode(v).1 { - FullDecoded::Finite(decoded) => decoded, - full_decoded => panic!("expected finite, got {full_decoded:?} instead"), - } -} - -#[bench] -fn bench_small_shortest(b: &mut Bencher) { - let decoded = decode_finite(3.141592f64); - let mut buf = [MaybeUninit::new(0); MAX_SIG_DIGITS]; - b.iter(|| { - format_shortest(black_box(&decoded), &mut buf); - }); -} - -#[bench] -fn bench_big_shortest(b: &mut Bencher) { - let decoded = decode_finite(f64::MAX); - let mut buf = [MaybeUninit::new(0); MAX_SIG_DIGITS]; - b.iter(|| { - format_shortest(black_box(&decoded), &mut buf); - }); -} - -#[bench] -fn bench_small_exact_3(b: &mut Bencher) { - let decoded = decode_finite(3.141592f64); - let mut buf = [MaybeUninit::new(0); 3]; - b.iter(|| { - format_exact(black_box(&decoded), &mut buf, i16::MIN); - }); -} - -#[bench] -fn bench_big_exact_3(b: &mut Bencher) { - let decoded = decode_finite(f64::MAX); - let mut buf = [MaybeUninit::new(0); 3]; - b.iter(|| { - format_exact(black_box(&decoded), &mut buf, i16::MIN); - }); -} - -#[bench] -fn bench_small_exact_12(b: &mut Bencher) { - let decoded = decode_finite(3.141592f64); - let mut buf = [MaybeUninit::new(0); 12]; - b.iter(|| { - format_exact(black_box(&decoded), &mut buf, i16::MIN); - }); -} - -#[bench] -fn bench_big_exact_12(b: &mut Bencher) { - let decoded = decode_finite(f64::MAX); - let mut buf = [MaybeUninit::new(0); 12]; - b.iter(|| { - format_exact(black_box(&decoded), &mut buf, i16::MIN); - }); -} - -#[bench] -fn bench_small_exact_inf(b: &mut Bencher) { - let decoded = decode_finite(3.141592f64); - let mut buf = [MaybeUninit::new(0); 1024]; - b.iter(|| { - format_exact(black_box(&decoded), &mut buf, i16::MIN); - }); -} - -#[bench] -fn bench_big_exact_inf(b: &mut Bencher) { - let decoded = decode_finite(f64::MAX); - let mut buf = [MaybeUninit::new(0); 1024]; - b.iter(|| { - format_exact(black_box(&decoded), &mut buf, i16::MIN); - }); -} - -#[bench] -fn bench_one_exact_inf(b: &mut Bencher) { - let decoded = decode_finite(1.0); - let mut buf = [MaybeUninit::new(0); 1024]; - b.iter(|| { - format_exact(black_box(&decoded), &mut buf, i16::MIN); - }); -} - -#[bench] -fn bench_trailing_zero_exact_inf(b: &mut Bencher) { - let decoded = decode_finite(250.000000000000000000000000); - let mut buf = [MaybeUninit::new(0); 1024]; - b.iter(|| { - format_exact(black_box(&decoded), &mut buf, i16::MIN); - }); -} - -#[bench] -fn bench_halfway_point_exact_inf(b: &mut Bencher) { - let decoded = decode_finite(1.00000000000000011102230246251565404236316680908203125); - let mut buf = [MaybeUninit::new(0); 1024]; - b.iter(|| { - format_exact(black_box(&decoded), &mut buf, i16::MIN); - }); -} diff --git a/library/core/benches/num/int_log/mod.rs b/library/core/benches/num/int_log/mod.rs deleted file mode 100644 index 3807cd5d76cfc..0000000000000 --- a/library/core/benches/num/int_log/mod.rs +++ /dev/null @@ -1,125 +0,0 @@ -use rand::Rng; -use test::{black_box, Bencher}; - -macro_rules! int_log10_bench { - ($t:ty, $predictable:ident, $random:ident, $random_small:ident) => { - #[bench] - fn $predictable(bench: &mut Bencher) { - bench.iter(|| { - for n in 0..(<$t>::BITS / 8) { - for i in 1..=(100 as $t) { - let x = black_box(i << (n * 8)); - black_box(x.ilog10()); - } - } - }); - } - - #[bench] - fn $random(bench: &mut Bencher) { - let mut rng = crate::bench_rng(); - /* Exponentially distributed random numbers from the whole range of the type. */ - let numbers: Vec<$t> = (0..256) - .map(|_| { - let x = rng.gen::<$t>() >> rng.gen_range(0..<$t>::BITS); - if x != 0 { x } else { 1 } - }) - .collect(); - bench.iter(|| { - for x in &numbers { - black_box(black_box(x).ilog10()); - } - }); - } - - #[bench] - fn $random_small(bench: &mut Bencher) { - let mut rng = crate::bench_rng(); - /* Exponentially distributed random numbers from the range 0..256. */ - let numbers: Vec<$t> = (0..256) - .map(|_| { - let x = (rng.gen::() >> rng.gen_range(0..u8::BITS)) as $t; - if x != 0 { x } else { 1 } - }) - .collect(); - bench.iter(|| { - for x in &numbers { - black_box(black_box(x).ilog10()); - } - }); - } - }; -} - -int_log10_bench! {u8, u8_log10_predictable, u8_log10_random, u8_log10_random_small} -int_log10_bench! {u16, u16_log10_predictable, u16_log10_random, u16_log10_random_small} -int_log10_bench! {u32, u32_log10_predictable, u32_log10_random, u32_log10_random_small} -int_log10_bench! {u64, u64_log10_predictable, u64_log10_random, u64_log10_random_small} -int_log10_bench! {u128, u128_log10_predictable, u128_log10_random, u128_log10_random_small} - -macro_rules! int_log_bench { - ($t:ty, $random:ident, $random_small:ident, $geometric:ident) => { - #[bench] - fn $random(bench: &mut Bencher) { - let mut rng = crate::bench_rng(); - /* Exponentially distributed random numbers from the whole range of the type. */ - let numbers: Vec<$t> = (0..256) - .map(|_| { - let x = rng.gen::<$t>() >> rng.gen_range(0..<$t>::BITS); - if x >= 2 { x } else { 2 } - }) - .collect(); - bench.iter(|| { - for &b in &numbers { - for &x in &numbers { - black_box(black_box(x).ilog(b)); - } - } - }); - } - - #[bench] - fn $random_small(bench: &mut Bencher) { - let mut rng = crate::bench_rng(); - /* Exponentially distributed random numbers from the range 0..256. */ - let numbers: Vec<$t> = (0..256) - .map(|_| { - let x = (rng.gen::() >> rng.gen_range(0..u8::BITS)) as $t; - if x >= 2 { x } else { 2 } - }) - .collect(); - bench.iter(|| { - for &b in &numbers { - for &x in &numbers { - black_box(black_box(x).ilog(b)); - } - } - }); - } - - #[bench] - fn $geometric(bench: &mut Bencher) { - let bases: [$t; 16] = [2, 3, 4, 5, 7, 8, 9, 15, 16, 17, 31, 32, 33, 63, 64, 65]; - let base_and_numbers: Vec<($t, Vec<$t>)> = bases - .iter() - .map(|&b| { - let numbers = (0..=<$t>::MAX.ilog(b)).map(|exp| b.pow(exp)).collect(); - (b, numbers) - }) - .collect(); - bench.iter(|| { - for (b, numbers) in &base_and_numbers { - for &x in numbers { - black_box(black_box(x).ilog(black_box(*b))); - } - } - }); - } - }; -} - -int_log_bench! {u8, u8_log_random, u8_log_random_small, u8_log_geometric} -int_log_bench! {u16, u16_log_random, u16_log_random_small, u16_log_geometric} -int_log_bench! {u32, u32_log_random, u32_log_random_small, u32_log_geometric} -int_log_bench! {u64, u64_log_random, u64_log_random_small, u64_log_geometric} -int_log_bench! {u128, u128_log_random, u128_log_random_small, u128_log_geometric} diff --git a/library/core/benches/num/int_pow/mod.rs b/library/core/benches/num/int_pow/mod.rs deleted file mode 100644 index 063d722bdd1b5..0000000000000 --- a/library/core/benches/num/int_pow/mod.rs +++ /dev/null @@ -1,99 +0,0 @@ -use rand::Rng; -use test::{black_box, Bencher}; - -const ITERATIONS: usize = 128; // Uses an ITERATIONS * 20 Byte stack allocation -type IntType = i128; // Hardest native type to multiply -const EXPONENT_MAX: u32 = 31; -const MAX_BASE: IntType = 17; // +-17 ** 31 <= IntType::MAX - -macro_rules! pow_bench_template { - ($name:ident, $inner_macro:ident, $base_macro:ident) => { - #[bench] - fn $name(bench: &mut Bencher) { - // Frequent black_box calls can add latency and prevent optimizations, so for - // variable parameters we premake an array and pass the - // reference through black_box outside of the loop. - let mut rng = crate::bench_rng(); - let base_array: [IntType; ITERATIONS] = - core::array::from_fn(|_| rng.gen_range((-MAX_BASE..=MAX_BASE))); - let exp_array: [u32; ITERATIONS] = - core::array::from_fn(|_| rng.gen_range((0..=EXPONENT_MAX))); - - bench.iter(|| { - #[allow(unused, unused_mut)] - let mut base_iter = black_box(&base_array).into_iter(); - let mut exp_iter = black_box(&exp_array).into_iter(); - - (0..ITERATIONS).fold((0 as IntType, false), |acc, _| { - // Sometimes constants don't propogate all the way to the - // inside of the loop, so we call a custom expression every cycle - // rather than iter::repeat(CONST) - let base: IntType = $base_macro!(base_iter); - let exp: u32 = *exp_iter.next().unwrap(); - - let r: (IntType, bool) = $inner_macro!(base, exp); - (acc.0 ^ r.0, acc.1 ^ r.1) - }) - }); - } - }; -} - -// This may panic if it overflows. -macro_rules! inner_pow { - ($base:ident, $exp:ident) => { - ($base.pow($exp), false) - }; -} - -macro_rules! inner_wrapping { - ($base:ident, $exp:ident) => { - ($base.wrapping_pow($exp), false) - }; -} - -macro_rules! inner_overflowing { - ($base:ident, $exp:ident) => { - $base.overflowing_pow($exp) - }; -} - -// This will panic if it overflows. -macro_rules! inner_checked_unwrapped { - ($base:ident, $exp:ident) => { - ($base.checked_pow($exp).unwrap(), false) - }; -} - -macro_rules! inner_saturating { - ($base:ident, $exp:ident) => { - ($base.saturating_pow($exp), false) - }; -} - -macro_rules! make_const_base { - ($name:ident, $x:literal) => { - macro_rules! $name { - ($iter:ident) => { - $x - }; - } - }; -} - -make_const_base!(const_base_m7, -7); -make_const_base!(const_base_m8, -8); - -macro_rules! variable_base { - ($iter:ident) => { - *$iter.next().unwrap() - }; -} - -pow_bench_template!(pow_variable, inner_pow, variable_base); -pow_bench_template!(wrapping_pow_variable, inner_wrapping, variable_base); -pow_bench_template!(overflowing_pow_variable, inner_overflowing, variable_base); -pow_bench_template!(checked_pow_variable, inner_checked_unwrapped, variable_base); -pow_bench_template!(saturating_pow_variable, inner_saturating, variable_base); -pow_bench_template!(pow_m7, inner_pow, const_base_m7); -pow_bench_template!(pow_m8, inner_pow, const_base_m8); diff --git a/library/core/benches/num/mod.rs b/library/core/benches/num/mod.rs deleted file mode 100644 index 4922ee150d95f..0000000000000 --- a/library/core/benches/num/mod.rs +++ /dev/null @@ -1,109 +0,0 @@ -mod dec2flt; -mod flt2dec; -mod int_log; -mod int_pow; - -use std::str::FromStr; -use test::{black_box, Bencher}; - -const ASCII_NUMBERS: [&str; 19] = [ - "0", - "1", - "2", - "43", - "765", - "76567", - "987245987", - "-4aa32", - "1786235", - "8723095", - "f##5s", - "83638730", - "-2345", - "562aa43", - "-1", - "-0", - "abc", - "xyz", - "c0ffee", -]; - -macro_rules! from_str_bench { - ($mac:ident, $t:ty) => { - #[bench] - fn $mac(b: &mut Bencher) { - b.iter(|| { - ASCII_NUMBERS - .iter() - .cycle() - .take(5_000) - .filter_map(|s| <$t>::from_str(black_box(s)).ok()) - .max() - }) - } - }; -} - -macro_rules! from_str_radix_bench { - ($mac:ident, $t:ty, $radix:expr) => { - #[bench] - fn $mac(b: &mut Bencher) { - b.iter(|| { - ASCII_NUMBERS - .iter() - .cycle() - .take(5_000) - .filter_map(|s| <$t>::from_str_radix(black_box(s), $radix).ok()) - .max() - }) - } - }; -} - -from_str_bench!(bench_u8_from_str, u8); -from_str_radix_bench!(bench_u8_from_str_radix_2, u8, 2); -from_str_radix_bench!(bench_u8_from_str_radix_10, u8, 10); -from_str_radix_bench!(bench_u8_from_str_radix_16, u8, 16); -from_str_radix_bench!(bench_u8_from_str_radix_36, u8, 36); - -from_str_bench!(bench_u16_from_str, u16); -from_str_radix_bench!(bench_u16_from_str_radix_2, u16, 2); -from_str_radix_bench!(bench_u16_from_str_radix_10, u16, 10); -from_str_radix_bench!(bench_u16_from_str_radix_16, u16, 16); -from_str_radix_bench!(bench_u16_from_str_radix_36, u16, 36); - -from_str_bench!(bench_u32_from_str, u32); -from_str_radix_bench!(bench_u32_from_str_radix_2, u32, 2); -from_str_radix_bench!(bench_u32_from_str_radix_10, u32, 10); -from_str_radix_bench!(bench_u32_from_str_radix_16, u32, 16); -from_str_radix_bench!(bench_u32_from_str_radix_36, u32, 36); - -from_str_bench!(bench_u64_from_str, u64); -from_str_radix_bench!(bench_u64_from_str_radix_2, u64, 2); -from_str_radix_bench!(bench_u64_from_str_radix_10, u64, 10); -from_str_radix_bench!(bench_u64_from_str_radix_16, u64, 16); -from_str_radix_bench!(bench_u64_from_str_radix_36, u64, 36); - -from_str_bench!(bench_i8_from_str, i8); -from_str_radix_bench!(bench_i8_from_str_radix_2, i8, 2); -from_str_radix_bench!(bench_i8_from_str_radix_10, i8, 10); -from_str_radix_bench!(bench_i8_from_str_radix_16, i8, 16); -from_str_radix_bench!(bench_i8_from_str_radix_36, i8, 36); - -from_str_bench!(bench_i16_from_str, i16); -from_str_radix_bench!(bench_i16_from_str_radix_2, i16, 2); -from_str_radix_bench!(bench_i16_from_str_radix_10, i16, 10); -from_str_radix_bench!(bench_i16_from_str_radix_16, i16, 16); -from_str_radix_bench!(bench_i16_from_str_radix_36, i16, 36); - -from_str_bench!(bench_i32_from_str, i32); -from_str_radix_bench!(bench_i32_from_str_radix_2, i32, 2); -from_str_radix_bench!(bench_i32_from_str_radix_10, i32, 10); -from_str_radix_bench!(bench_i32_from_str_radix_16, i32, 16); -from_str_radix_bench!(bench_i32_from_str_radix_36, i32, 36); - -from_str_bench!(bench_i64_from_str, i64); -from_str_radix_bench!(bench_i64_from_str_radix_2, i64, 2); -from_str_radix_bench!(bench_i64_from_str_radix_10, i64, 10); -from_str_radix_bench!(bench_i64_from_str_radix_16, i64, 16); -from_str_radix_bench!(bench_i64_from_str_radix_36, i64, 36); diff --git a/library/core/benches/ops.rs b/library/core/benches/ops.rs deleted file mode 100644 index 0a2be8a28819f..0000000000000 --- a/library/core/benches/ops.rs +++ /dev/null @@ -1,19 +0,0 @@ -use core::ops::*; -use test::Bencher; - -// Overhead of dtors - -struct HasDtor { - _x: isize, -} - -impl Drop for HasDtor { - fn drop(&mut self) {} -} - -#[bench] -fn alloc_obj_with_dtor(b: &mut Bencher) { - b.iter(|| { - HasDtor { _x: 10 }; - }) -} diff --git a/library/core/benches/pattern.rs b/library/core/benches/pattern.rs deleted file mode 100644 index 480ac6f36d202..0000000000000 --- a/library/core/benches/pattern.rs +++ /dev/null @@ -1,42 +0,0 @@ -use test::black_box; -use test::Bencher; - -#[bench] -fn starts_with_char(b: &mut Bencher) { - let text = black_box("kdjsfhlakfhlsghlkvcnljknfqiunvcijqenwodind"); - b.iter(|| { - for _ in 0..1024 { - black_box(text.starts_with('k')); - } - }) -} - -#[bench] -fn starts_with_str(b: &mut Bencher) { - let text = black_box("kdjsfhlakfhlsghlkvcnljknfqiunvcijqenwodind"); - b.iter(|| { - for _ in 0..1024 { - black_box(text.starts_with("k")); - } - }) -} - -#[bench] -fn ends_with_char(b: &mut Bencher) { - let text = black_box("kdjsfhlakfhlsghlkvcnljknfqiunvcijqenwodind"); - b.iter(|| { - for _ in 0..1024 { - black_box(text.ends_with('k')); - } - }) -} - -#[bench] -fn ends_with_str(b: &mut Bencher) { - let text = black_box("kdjsfhlakfhlsghlkvcnljknfqiunvcijqenwodind"); - b.iter(|| { - for _ in 0..1024 { - black_box(text.ends_with("k")); - } - }) -} diff --git a/library/core/benches/slice.rs b/library/core/benches/slice.rs deleted file mode 100644 index 8f87a211449c0..0000000000000 --- a/library/core/benches/slice.rs +++ /dev/null @@ -1,173 +0,0 @@ -use core::ptr::NonNull; -use test::black_box; -use test::Bencher; - -enum Cache { - L1, - L2, - L3, -} - -impl Cache { - fn size(&self) -> usize { - match self { - Cache::L1 => 1000, // 8kb - Cache::L2 => 10_000, // 80kb - Cache::L3 => 1_000_000, // 8Mb - } - } -} - -fn binary_search(b: &mut Bencher, cache: Cache, mapper: F) -where - F: Fn(usize) -> usize, -{ - let size = cache.size(); - let v = (0..size).map(&mapper).collect::>(); - let mut r = 0usize; - b.iter(move || { - // LCG constants from https://en.wikipedia.org/wiki/Numerical_Recipes. - r = r.wrapping_mul(1664525).wrapping_add(1013904223); - // Lookup the whole range to get 50% hits and 50% misses. - let i = mapper(r % size); - black_box(v.binary_search(&i).is_ok()); - }); -} - -fn binary_search_worst_case(b: &mut Bencher, cache: Cache) { - let size = cache.size(); - - let mut v = vec![0; size]; - let i = 1; - v[size - 1] = i; - b.iter(move || { - black_box(v.binary_search(&i).is_ok()); - }); -} - -#[bench] -fn binary_search_l1(b: &mut Bencher) { - binary_search(b, Cache::L1, |i| i * 2); -} - -#[bench] -fn binary_search_l2(b: &mut Bencher) { - binary_search(b, Cache::L2, |i| i * 2); -} - -#[bench] -fn binary_search_l3(b: &mut Bencher) { - binary_search(b, Cache::L3, |i| i * 2); -} - -#[bench] -fn binary_search_l1_with_dups(b: &mut Bencher) { - binary_search(b, Cache::L1, |i| i / 16 * 16); -} - -#[bench] -fn binary_search_l2_with_dups(b: &mut Bencher) { - binary_search(b, Cache::L2, |i| i / 16 * 16); -} - -#[bench] -fn binary_search_l3_with_dups(b: &mut Bencher) { - binary_search(b, Cache::L3, |i| i / 16 * 16); -} - -#[bench] -fn binary_search_l1_worst_case(b: &mut Bencher) { - binary_search_worst_case(b, Cache::L1); -} - -#[bench] -fn binary_search_l2_worst_case(b: &mut Bencher) { - binary_search_worst_case(b, Cache::L2); -} - -#[bench] -fn binary_search_l3_worst_case(b: &mut Bencher) { - binary_search_worst_case(b, Cache::L3); -} - -#[derive(Clone)] -struct Rgb(#[allow(dead_code)] u8, #[allow(dead_code)] u8, #[allow(dead_code)] u8); - -impl Rgb { - fn gen(i: usize) -> Self { - Rgb(i as u8, (i as u8).wrapping_add(7), (i as u8).wrapping_add(42)) - } -} - -macro_rules! rotate { - ($fn:ident, $n:expr, $mapper:expr) => { - #[bench] - fn $fn(b: &mut Bencher) { - let mut x = (0usize..$n).map(&$mapper).collect::>(); - b.iter(|| { - for s in 0..x.len() { - x[..].rotate_right(s); - } - black_box(x[0].clone()) - }) - } - }; -} - -rotate!(rotate_u8, 32, |i| i as u8); -rotate!(rotate_rgb, 32, Rgb::gen); -rotate!(rotate_usize, 32, |i| i); -rotate!(rotate_16_usize_4, 16, |i| [i; 4]); -rotate!(rotate_16_usize_5, 16, |i| [i; 5]); -rotate!(rotate_64_usize_4, 64, |i| [i; 4]); -rotate!(rotate_64_usize_5, 64, |i| [i; 5]); - -macro_rules! swap_with_slice { - ($fn:ident, $n:expr, $mapper:expr) => { - #[bench] - fn $fn(b: &mut Bencher) { - let mut x = (0usize..$n).map(&$mapper).collect::>(); - let mut y = ($n..($n * 2)).map(&$mapper).collect::>(); - let mut skip = 0; - b.iter(|| { - for _ in 0..32 { - x[skip..].swap_with_slice(&mut y[..($n - skip)]); - skip = black_box(skip + 1) % 8; - } - black_box((x[$n / 3].clone(), y[$n * 2 / 3].clone())) - }) - } - }; -} - -swap_with_slice!(swap_with_slice_u8_30, 30, |i| i as u8); -swap_with_slice!(swap_with_slice_u8_3000, 3000, |i| i as u8); -swap_with_slice!(swap_with_slice_rgb_30, 30, Rgb::gen); -swap_with_slice!(swap_with_slice_rgb_3000, 3000, Rgb::gen); -swap_with_slice!(swap_with_slice_usize_30, 30, |i| i); -swap_with_slice!(swap_with_slice_usize_3000, 3000, |i| i); -swap_with_slice!(swap_with_slice_4x_usize_30, 30, |i| [i; 4]); -swap_with_slice!(swap_with_slice_4x_usize_3000, 3000, |i| [i; 4]); -swap_with_slice!(swap_with_slice_5x_usize_30, 30, |i| [i; 5]); -swap_with_slice!(swap_with_slice_5x_usize_3000, 3000, |i| [i; 5]); - -#[bench] -fn fill_byte_sized(b: &mut Bencher) { - #[derive(Copy, Clone)] - struct NewType(#[allow(dead_code)] u8); - - let mut ary = [NewType(0); 1024]; - - b.iter(|| { - let slice = &mut ary[..]; - black_box(slice.fill(black_box(NewType(42)))); - }); -} - -// Tests the ability of the compiler to recognize that only the last slice item is needed -// based on issue #106288 -#[bench] -fn fold_to_last(b: &mut Bencher) { - let slice: &[i32] = &[0; 1024]; - b.iter(|| black_box(slice).iter().fold(None, |_, r| Some(NonNull::from(r)))); -} diff --git a/library/core/benches/str.rs b/library/core/benches/str.rs deleted file mode 100644 index 0f14809444bc5..0000000000000 --- a/library/core/benches/str.rs +++ /dev/null @@ -1,12 +0,0 @@ -use std::str; -use test::{black_box, Bencher}; - -mod char_count; -mod corpora; -mod debug; -mod iter; - -#[bench] -fn str_validate_emoji(b: &mut Bencher) { - b.iter(|| str::from_utf8(black_box(corpora::emoji::LARGE.as_bytes()))); -} diff --git a/library/core/benches/str/char_count.rs b/library/core/benches/str/char_count.rs deleted file mode 100644 index 25d9b2e299223..0000000000000 --- a/library/core/benches/str/char_count.rs +++ /dev/null @@ -1,107 +0,0 @@ -use super::corpora::*; -use test::{black_box, Bencher}; - -macro_rules! define_benches { - ($( fn $name: ident($arg: ident: &str) $body: block )+) => { - define_benches!(mod en_tiny, en::TINY, $($name $arg $body)+); - define_benches!(mod en_small, en::SMALL, $($name $arg $body)+); - define_benches!(mod en_medium, en::MEDIUM, $($name $arg $body)+); - define_benches!(mod en_large, en::LARGE, $($name $arg $body)+); - define_benches!(mod en_huge, en::HUGE, $($name $arg $body)+); - - define_benches!(mod zh_tiny, zh::TINY, $($name $arg $body)+); - define_benches!(mod zh_small, zh::SMALL, $($name $arg $body)+); - define_benches!(mod zh_medium, zh::MEDIUM, $($name $arg $body)+); - define_benches!(mod zh_large, zh::LARGE, $($name $arg $body)+); - define_benches!(mod zh_huge, zh::HUGE, $($name $arg $body)+); - - define_benches!(mod ru_tiny, ru::TINY, $($name $arg $body)+); - define_benches!(mod ru_small, ru::SMALL, $($name $arg $body)+); - define_benches!(mod ru_medium, ru::MEDIUM, $($name $arg $body)+); - define_benches!(mod ru_large, ru::LARGE, $($name $arg $body)+); - define_benches!(mod ru_huge, ru::HUGE, $($name $arg $body)+); - - define_benches!(mod emoji_tiny, emoji::TINY, $($name $arg $body)+); - define_benches!(mod emoji_small, emoji::SMALL, $($name $arg $body)+); - define_benches!(mod emoji_medium, emoji::MEDIUM, $($name $arg $body)+); - define_benches!(mod emoji_large, emoji::LARGE, $($name $arg $body)+); - define_benches!(mod emoji_huge, emoji::HUGE, $($name $arg $body)+); - }; - (mod $mod_name: ident, $input: expr, $($name: ident $arg: ident $body: block)+) => { - mod $mod_name { - use super::*; - $( - #[bench] - fn $name(bencher: &mut Bencher) { - let input = $input; - bencher.bytes = input.len() as u64; - let mut input_s = input.to_string(); - bencher.iter(|| { - let $arg: &str = &black_box(&mut input_s); - black_box($body) - }) - } - )+ - } - }; -} - -define_benches! { - fn case00_libcore(s: &str) { - libcore(s) - } - - fn case01_filter_count_cont_bytes(s: &str) { - filter_count_cont_bytes(s) - } - - fn case02_iter_increment(s: &str) { - iterator_increment(s) - } - - fn case03_manual_char_len(s: &str) { - manual_char_len(s) - } -} - -fn libcore(s: &str) -> usize { - s.chars().count() -} - -#[inline] -fn utf8_is_cont_byte(byte: u8) -> bool { - (byte as i8) < -64 -} - -fn filter_count_cont_bytes(s: &str) -> usize { - s.as_bytes().iter().filter(|&&byte| !utf8_is_cont_byte(byte)).count() -} - -fn iterator_increment(s: &str) -> usize { - let mut c = 0; - for _ in s.chars() { - c += 1; - } - c -} - -fn manual_char_len(s: &str) -> usize { - let s = s.as_bytes(); - let mut c = 0; - let mut i = 0; - let l = s.len(); - while i < l { - let b = s[i]; - if b < 0x80 { - i += 1; - } else if b < 0xe0 { - i += 2; - } else if b < 0xf0 { - i += 3; - } else { - i += 4; - } - c += 1; - } - c -} diff --git a/library/core/benches/str/corpora.rs b/library/core/benches/str/corpora.rs deleted file mode 100644 index b4ac625061dfa..0000000000000 --- a/library/core/benches/str/corpora.rs +++ /dev/null @@ -1,88 +0,0 @@ -//! Exposes a number of modules with different kinds of strings. -//! -//! Each module contains `&str` constants named `TINY`, `SMALL`, `MEDIUM`, -//! `LARGE`, and `HUGE`. -//! -//! - The `TINY` string is generally around 8 bytes. -//! - The `SMALL` string is generally around 30-40 bytes. -//! - The `MEDIUM` string is generally around 600-700 bytes. -//! - The `LARGE` string is the `MEDIUM` string repeated 8x, and is around 5kb. -//! - The `HUGE` string is the `LARGE` string repeated 8x (or the `MEDIUM` -//! string repeated 64x), and is around 40kb. -//! -//! Except for `mod emoji` (which is just a bunch of emoji), the strings were -//! pulled from (localizations of) rust-lang.org. - -macro_rules! repeat8 { - ($s:expr) => { - concat!($s, $s, $s, $s, $s, $s, $s, $s) - }; -} - -macro_rules! define_consts { - ($s:literal) => { - pub const MEDIUM: &str = $s; - pub const LARGE: &str = repeat8!($s); - pub const HUGE: &str = repeat8!(repeat8!(repeat8!($s))); - }; -} - -pub mod en { - pub const TINY: &str = "Mary had"; - pub const SMALL: &str = "Mary had a little lamb, Little lamb"; - define_consts! { - "Rust is blazingly fast and memory-efficient: with no runtime or garbage - collector, it can power performance-critical services, run on embedded - devices, and easily integrate with other languages. Rust’s rich type system - and ownership model guarantee memory-safety and thread-safety — enabling you - to eliminate many classes of bugs at compile-time. Rust has great - documentation, a friendly compiler with useful error messages, and top-notch - tooling — an integrated package manager and build tool, smart multi-editor - support with auto-completion and type inspections, an auto-formatter, and - more." - } -} - -pub mod zh { - pub const TINY: &str = "速度惊"; - pub const SMALL: &str = "速度惊人且内存利用率极高"; - define_consts! { - "Rust 速度惊人且内存利用率极高。由于\ - 没有运行时和垃圾回收,它能够胜任对性能要\ - 求特别高的服务,可以在嵌入式设备上运行,\ - 还能轻松和其他语言集成。Rust 丰富的类型\ - 系统和所有权模型保证了内存安全和线程安全,\ - 让您在编译期就能够消除各种各样的错误。\ - Rust 拥有出色的文档、友好的编译器和清晰\ - 的错误提示信息, 还集成了一流的工具——\ - 包管理器和构建工具, 智能地自动补全和类\ - 型检验的多编辑器支持, 以及自动格式化代\ - 码等等。" - } -} - -pub mod ru { - pub const TINY: &str = "Сотни"; - pub const SMALL: &str = "Сотни компаний по"; - define_consts! { - "Сотни компаний по всему миру используют Rust в реальных\ - проектах для быстрых кросс-платформенных решений с\ - ограниченными ресурсами. Такие проекты, как Firefox,\ - Dropbox и Cloudflare, используют Rust. Rust отлично\ - подходит как для стартапов, так и для больших компаний,\ - как для встраиваемых устройств, так и для масштабируемых\ - web-сервисов. Мой самый большой комплимент Rust." - } -} - -pub mod emoji { - pub const TINY: &str = "😀😃"; - pub const SMALL: &str = "😀😃😄😁😆😅🤣😂🙂🙃😉😊😇🥰😍🤩😘"; - define_consts! { - "😀😃😄😁😆😅🤣😂🙂🙃😉😊😇🥰😍🤩😘😗☺😚😙🥲😋😛😜🤪😝🤑🤗🤭🤫🤔🤐🤨😐😑😶😶‍🌫️😏😒\ - 🙄😬😮‍💨🤥😌😔😪🤤😴😷🤒🤕🤢🤮🤧🥵🥶🥴😵😵‍💫🤯��🥳🥸😎🤓🧐😕😟🙁☹😮😯😲😳🥺😦😧😨\ - 😰😥😢😭😱😖😣😞😓😩😫🥱😤😡😠🤬😈👿💀☠💩🤡👹👺👻👽👾🤖😺😸😹😻😼😽🙀😿😾🙈🙉🙊\ - 💋💌💘💝💖💗💓��💕💟❣💔❤️‍🔥❤️‍🩹❤🧡💛💚💙💜🤎🖤🤍💯💢💥💫💦💨🕳💬👁️‍🗨️🗨🗯💭💤👋\ - 🤚🖐✋🖖👌🤌🤏✌" - } -} diff --git a/library/core/benches/str/debug.rs b/library/core/benches/str/debug.rs deleted file mode 100644 index cb91169eed8eb..0000000000000 --- a/library/core/benches/str/debug.rs +++ /dev/null @@ -1,79 +0,0 @@ -//! This primarily benchmarks `impl Debug for str`, -//! and it also explicitly tests that we minimizes calls to the underlying `Write`r. -//! While that is an implementation detail and there are no guarantees about it, -//! we should still try to minimize those calls over time rather than regress them. - -use std::fmt::{self, Write}; -use test::{black_box, Bencher}; - -#[derive(Default)] -struct CountingWriter { - buf: String, - write_calls: usize, -} - -impl Write for CountingWriter { - fn write_str(&mut self, s: &str) -> fmt::Result { - self.buf.push_str(s); - self.write_calls += 1; - Ok(()) - } -} - -fn assert_fmt(s: &str, expected: &str, expected_write_calls: usize) { - let mut w = CountingWriter::default(); - - write!(&mut w, "{s:?}").unwrap(); - assert_eq!(s.len(), 64); - assert_eq!(w.buf, expected); - assert_eq!(w.write_calls, expected_write_calls); -} - -#[bench] -fn ascii_only(b: &mut Bencher) { - let s = "just a bit of ascii text that has no escapes. 64 bytes exactly!!"; - assert_fmt(s, r#""just a bit of ascii text that has no escapes. 64 bytes exactly!!""#, 3); - b.iter(|| { - black_box(format!("{:?}", black_box(s))); - }); -} - -#[bench] -fn ascii_escapes(b: &mut Bencher) { - let s = "some\tmore\tascii\ttext\nthis time with some \"escapes\", also 64 byte"; - assert_fmt( - s, - r#""some\tmore\tascii\ttext\nthis time with some \"escapes\", also 64 byte""#, - 15, - ); - b.iter(|| { - black_box(format!("{:?}", black_box(s))); - }); -} - -#[bench] -fn some_unicode(b: &mut Bencher) { - let s = "egy kis szöveg néhány unicode betűvel. legyen ez is 64 byte."; - assert_fmt(s, r#""egy kis szöveg néhány unicode betűvel. legyen ez is 64 byte.""#, 3); - b.iter(|| { - black_box(format!("{:?}", black_box(s))); - }); -} - -#[bench] -fn mostly_unicode(b: &mut Bencher) { - let s = "предложение из кириллических букв."; - assert_fmt(s, r#""предложение из кириллических букв.""#, 3); - b.iter(|| { - black_box(format!("{:?}", black_box(s))); - }); -} - -#[bench] -fn mixed(b: &mut Bencher) { - let s = "\"❤️\"\n\"hűha ez betű\"\n\"кириллических букв\"."; - assert_fmt(s, r#""\"❤\u{fe0f}\"\n\"hűha ez betű\"\n\"кириллических букв\".""#, 21); - b.iter(|| { - black_box(format!("{:?}", black_box(s))); - }); -} diff --git a/library/core/benches/str/iter.rs b/library/core/benches/str/iter.rs deleted file mode 100644 index 58ae71fc10f12..0000000000000 --- a/library/core/benches/str/iter.rs +++ /dev/null @@ -1,17 +0,0 @@ -use super::corpora; -use test::{black_box, Bencher}; - -#[bench] -fn chars_advance_by_1000(b: &mut Bencher) { - b.iter(|| black_box(corpora::ru::LARGE).chars().advance_by(1000)); -} - -#[bench] -fn chars_advance_by_0010(b: &mut Bencher) { - b.iter(|| black_box(corpora::ru::LARGE).chars().advance_by(10)); -} - -#[bench] -fn chars_advance_by_0001(b: &mut Bencher) { - b.iter(|| black_box(corpora::ru::LARGE).chars().advance_by(1)); -} diff --git a/library/core/benches/tuple.rs b/library/core/benches/tuple.rs deleted file mode 100644 index d9ff9d0dd9378..0000000000000 --- a/library/core/benches/tuple.rs +++ /dev/null @@ -1,22 +0,0 @@ -use rand::prelude::*; -use test::{black_box, Bencher}; - -#[bench] -fn bench_tuple_comparison(b: &mut Bencher) { - let mut rng = black_box(super::bench_rng()); - - let data = black_box([ - ("core::iter::adapters::Chain", 123_usize), - ("core::iter::adapters::Clone", 456_usize), - ("core::iter::adapters::Copie", 789_usize), - ("core::iter::adapters::Cycle", 123_usize), - ("core::iter::adapters::Flatt", 456_usize), - ("core::iter::adapters::TakeN", 789_usize), - ]); - - b.iter(|| { - let x = data.choose(&mut rng).unwrap(); - let y = data.choose(&mut rng).unwrap(); - [x < y, x <= y, x > y, x >= y] - }); -} diff --git a/library/core/src/alloc/global.rs b/library/core/src/alloc/global.rs deleted file mode 100644 index 8df3ace54ffe1..0000000000000 --- a/library/core/src/alloc/global.rs +++ /dev/null @@ -1,276 +0,0 @@ -use crate::alloc::Layout; -use crate::cmp; -use crate::ptr; - -/// A memory allocator that can be registered as the standard library’s default -/// through the `#[global_allocator]` attribute. -/// -/// Some of the methods require that a memory block be *currently -/// allocated* via an allocator. This means that: -/// -/// * the starting address for that memory block was previously -/// returned by a previous call to an allocation method -/// such as `alloc`, and -/// -/// * the memory block has not been subsequently deallocated, where -/// blocks are deallocated either by being passed to a deallocation -/// method such as `dealloc` or by being -/// passed to a reallocation method that returns a non-null pointer. -/// -/// -/// # Example -/// -/// ``` -/// use std::alloc::{GlobalAlloc, Layout}; -/// use std::cell::UnsafeCell; -/// use std::ptr::null_mut; -/// use std::sync::atomic::{AtomicUsize, Ordering::Relaxed}; -/// -/// const ARENA_SIZE: usize = 128 * 1024; -/// const MAX_SUPPORTED_ALIGN: usize = 4096; -/// #[repr(C, align(4096))] // 4096 == MAX_SUPPORTED_ALIGN -/// struct SimpleAllocator { -/// arena: UnsafeCell<[u8; ARENA_SIZE]>, -/// remaining: AtomicUsize, // we allocate from the top, counting down -/// } -/// -/// #[global_allocator] -/// static ALLOCATOR: SimpleAllocator = SimpleAllocator { -/// arena: UnsafeCell::new([0x55; ARENA_SIZE]), -/// remaining: AtomicUsize::new(ARENA_SIZE), -/// }; -/// -/// unsafe impl Sync for SimpleAllocator {} -/// -/// unsafe impl GlobalAlloc for SimpleAllocator { -/// unsafe fn alloc(&self, layout: Layout) -> *mut u8 { -/// let size = layout.size(); -/// let align = layout.align(); -/// -/// // `Layout` contract forbids making a `Layout` with align=0, or align not power of 2. -/// // So we can safely use a mask to ensure alignment without worrying about UB. -/// let align_mask_to_round_down = !(align - 1); -/// -/// if align > MAX_SUPPORTED_ALIGN { -/// return null_mut(); -/// } -/// -/// let mut allocated = 0; -/// if self -/// .remaining -/// .fetch_update(Relaxed, Relaxed, |mut remaining| { -/// if size > remaining { -/// return None; -/// } -/// remaining -= size; -/// remaining &= align_mask_to_round_down; -/// allocated = remaining; -/// Some(remaining) -/// }) -/// .is_err() -/// { -/// return null_mut(); -/// }; -/// self.arena.get().cast::().add(allocated) -/// } -/// unsafe fn dealloc(&self, _ptr: *mut u8, _layout: Layout) {} -/// } -/// -/// fn main() { -/// let _s = format!("allocating a string!"); -/// let currently = ALLOCATOR.remaining.load(Relaxed); -/// println!("allocated so far: {}", ARENA_SIZE - currently); -/// } -/// ``` -/// -/// # Safety -/// -/// The `GlobalAlloc` trait is an `unsafe` trait for a number of reasons, and -/// implementors must ensure that they adhere to these contracts: -/// -/// * It's undefined behavior if global allocators unwind. This restriction may -/// be lifted in the future, but currently a panic from any of these -/// functions may lead to memory unsafety. -/// -/// * `Layout` queries and calculations in general must be correct. Callers of -/// this trait are allowed to rely on the contracts defined on each method, -/// and implementors must ensure such contracts remain true. -/// -/// * You must not rely on allocations actually happening, even if there are explicit -/// heap allocations in the source. The optimizer may detect unused allocations that it can either -/// eliminate entirely or move to the stack and thus never invoke the allocator. The -/// optimizer may further assume that allocation is infallible, so code that used to fail due -/// to allocator failures may now suddenly work because the optimizer worked around the -/// need for an allocation. More concretely, the following code example is unsound, irrespective -/// of whether your custom allocator allows counting how many allocations have happened. -/// -/// ```rust,ignore (unsound and has placeholders) -/// drop(Box::new(42)); -/// let number_of_heap_allocs = /* call private allocator API */; -/// unsafe { std::hint::assert_unchecked(number_of_heap_allocs > 0); } -/// ``` -/// -/// Note that the optimizations mentioned above are not the only -/// optimization that can be applied. You may generally not rely on heap allocations -/// happening if they can be removed without changing program behavior. -/// Whether allocations happen or not is not part of the program behavior, even if it -/// could be detected via an allocator that tracks allocations by printing or otherwise -/// having side effects. -#[stable(feature = "global_alloc", since = "1.28.0")] -pub unsafe trait GlobalAlloc { - /// Allocate memory as described by the given `layout`. - /// - /// Returns a pointer to newly-allocated memory, - /// or null to indicate allocation failure. - /// - /// # Safety - /// - /// This function is unsafe because undefined behavior can result - /// if the caller does not ensure that `layout` has non-zero size. - /// - /// (Extension subtraits might provide more specific bounds on - /// behavior, e.g., guarantee a sentinel address or a null pointer - /// in response to a zero-size allocation request.) - /// - /// The allocated block of memory may or may not be initialized. - /// - /// # Errors - /// - /// Returning a null pointer indicates that either memory is exhausted - /// or `layout` does not meet this allocator's size or alignment constraints. - /// - /// Implementations are encouraged to return null on memory - /// exhaustion rather than aborting, but this is not - /// a strict requirement. (Specifically: it is *legal* to - /// implement this trait atop an underlying native allocation - /// library that aborts on memory exhaustion.) - /// - /// Clients wishing to abort computation in response to an - /// allocation error are encouraged to call the [`handle_alloc_error`] function, - /// rather than directly invoking `panic!` or similar. - /// - /// [`handle_alloc_error`]: ../../alloc/alloc/fn.handle_alloc_error.html - #[stable(feature = "global_alloc", since = "1.28.0")] - unsafe fn alloc(&self, layout: Layout) -> *mut u8; - - /// Deallocate the block of memory at the given `ptr` pointer with the given `layout`. - /// - /// # Safety - /// - /// This function is unsafe because undefined behavior can result - /// if the caller does not ensure all of the following: - /// - /// * `ptr` must denote a block of memory currently allocated via - /// this allocator, - /// - /// * `layout` must be the same layout that was used - /// to allocate that block of memory. - #[stable(feature = "global_alloc", since = "1.28.0")] - unsafe fn dealloc(&self, ptr: *mut u8, layout: Layout); - - /// Behaves like `alloc`, but also ensures that the contents - /// are set to zero before being returned. - /// - /// # Safety - /// - /// This function is unsafe for the same reasons that `alloc` is. - /// However the allocated block of memory is guaranteed to be initialized. - /// - /// # Errors - /// - /// Returning a null pointer indicates that either memory is exhausted - /// or `layout` does not meet allocator's size or alignment constraints, - /// just as in `alloc`. - /// - /// Clients wishing to abort computation in response to an - /// allocation error are encouraged to call the [`handle_alloc_error`] function, - /// rather than directly invoking `panic!` or similar. - /// - /// [`handle_alloc_error`]: ../../alloc/alloc/fn.handle_alloc_error.html - #[stable(feature = "global_alloc", since = "1.28.0")] - unsafe fn alloc_zeroed(&self, layout: Layout) -> *mut u8 { - let size = layout.size(); - // SAFETY: the safety contract for `alloc` must be upheld by the caller. - let ptr = unsafe { self.alloc(layout) }; - if !ptr.is_null() { - // SAFETY: as allocation succeeded, the region from `ptr` - // of size `size` is guaranteed to be valid for writes. - unsafe { ptr::write_bytes(ptr, 0, size) }; - } - ptr - } - - /// Shrink or grow a block of memory to the given `new_size` in bytes. - /// The block is described by the given `ptr` pointer and `layout`. - /// - /// If this returns a non-null pointer, then ownership of the memory block - /// referenced by `ptr` has been transferred to this allocator. - /// Any access to the old `ptr` is Undefined Behavior, even if the - /// allocation remained in-place. The newly returned pointer is the only valid pointer - /// for accessing this memory now. - /// - /// The new memory block is allocated with `layout`, - /// but with the `size` updated to `new_size` in bytes. - /// This new layout must be used when deallocating the new memory block with `dealloc`. - /// The range `0..min(layout.size(), new_size)` of the new memory block is - /// guaranteed to have the same values as the original block. - /// - /// If this method returns null, then ownership of the memory - /// block has not been transferred to this allocator, and the - /// contents of the memory block are unaltered. - /// - /// # Safety - /// - /// This function is unsafe because undefined behavior can result - /// if the caller does not ensure all of the following: - /// - /// * `ptr` must be currently allocated via this allocator, - /// - /// * `layout` must be the same layout that was used - /// to allocate that block of memory, - /// - /// * `new_size` must be greater than zero. - /// - /// * `new_size`, when rounded up to the nearest multiple of `layout.align()`, - /// must not overflow isize (i.e., the rounded value must be less than or - /// equal to `isize::MAX`). - /// - /// (Extension subtraits might provide more specific bounds on - /// behavior, e.g., guarantee a sentinel address or a null pointer - /// in response to a zero-size allocation request.) - /// - /// # Errors - /// - /// Returns null if the new layout does not meet the size - /// and alignment constraints of the allocator, or if reallocation - /// otherwise fails. - /// - /// Implementations are encouraged to return null on memory - /// exhaustion rather than panicking or aborting, but this is not - /// a strict requirement. (Specifically: it is *legal* to - /// implement this trait atop an underlying native allocation - /// library that aborts on memory exhaustion.) - /// - /// Clients wishing to abort computation in response to a - /// reallocation error are encouraged to call the [`handle_alloc_error`] function, - /// rather than directly invoking `panic!` or similar. - /// - /// [`handle_alloc_error`]: ../../alloc/alloc/fn.handle_alloc_error.html - #[stable(feature = "global_alloc", since = "1.28.0")] - unsafe fn realloc(&self, ptr: *mut u8, layout: Layout, new_size: usize) -> *mut u8 { - // SAFETY: the caller must ensure that the `new_size` does not overflow. - // `layout.align()` comes from a `Layout` and is thus guaranteed to be valid. - let new_layout = unsafe { Layout::from_size_align_unchecked(new_size, layout.align()) }; - // SAFETY: the caller must ensure that `new_layout` is greater than zero. - let new_ptr = unsafe { self.alloc(new_layout) }; - if !new_ptr.is_null() { - // SAFETY: the previously allocated block cannot overlap the newly allocated block. - // The safety contract for `dealloc` must be upheld by the caller. - unsafe { - ptr::copy_nonoverlapping(ptr, new_ptr, cmp::min(layout.size(), new_size)); - self.dealloc(ptr, layout); - } - } - new_ptr - } -} diff --git a/library/core/src/alloc/layout.rs b/library/core/src/alloc/layout.rs deleted file mode 100644 index c63db5aa0aa2f..0000000000000 --- a/library/core/src/alloc/layout.rs +++ /dev/null @@ -1,517 +0,0 @@ -// Seemingly inconsequential code changes to this file can lead to measurable -// performance impact on compilation times, due at least in part to the fact -// that the layout code gets called from many instantiations of the various -// collections, resulting in having to optimize down excess IR multiple times. -// Your performance intuition is useless. Run perf. - -use safety::requires; -use crate::cmp; -use crate::error::Error; -use crate::fmt; -use crate::mem; -use crate::ptr::{Alignment, NonNull}; - -#[cfg(kani)] -use crate::kani; - -// While this function is used in one place and its implementation -// could be inlined, the previous attempts to do so made rustc -// slower: -// -// * https://github.com/rust-lang/rust/pull/72189 -// * https://github.com/rust-lang/rust/pull/79827 -const fn size_align() -> (usize, usize) { - (mem::size_of::(), mem::align_of::()) -} - -/// Layout of a block of memory. -/// -/// An instance of `Layout` describes a particular layout of memory. -/// You build a `Layout` up as an input to give to an allocator. -/// -/// All layouts have an associated size and a power-of-two alignment. The size, when rounded up to -/// the nearest multiple of `align`, does not overflow isize (i.e., the rounded value will always be -/// less than or equal to `isize::MAX`). -/// -/// (Note that layouts are *not* required to have non-zero size, -/// even though `GlobalAlloc` requires that all memory requests -/// be non-zero in size. A caller must either ensure that conditions -/// like this are met, use specific allocators with looser -/// requirements, or use the more lenient `Allocator` interface.) -#[stable(feature = "alloc_layout", since = "1.28.0")] -#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)] -#[lang = "alloc_layout"] -pub struct Layout { - // size of the requested block of memory, measured in bytes. - size: usize, - - // alignment of the requested block of memory, measured in bytes. - // we ensure that this is always a power-of-two, because API's - // like `posix_memalign` require it and it is a reasonable - // constraint to impose on Layout constructors. - // - // (However, we do not analogously require `align >= sizeof(void*)`, - // even though that is *also* a requirement of `posix_memalign`.) - align: Alignment, -} - -impl Layout { - /// Constructs a `Layout` from a given `size` and `align`, - /// or returns `LayoutError` if any of the following conditions - /// are not met: - /// - /// * `align` must not be zero, - /// - /// * `align` must be a power of two, - /// - /// * `size`, when rounded up to the nearest multiple of `align`, - /// must not overflow isize (i.e., the rounded value must be - /// less than or equal to `isize::MAX`). - #[stable(feature = "alloc_layout", since = "1.28.0")] - #[rustc_const_stable(feature = "const_alloc_layout_size_align", since = "1.50.0")] - #[inline] - #[rustc_allow_const_fn_unstable(ptr_alignment_type)] - pub const fn from_size_align(size: usize, align: usize) -> Result { - if !align.is_power_of_two() { - return Err(LayoutError); - } - - // SAFETY: just checked that align is a power of two. - Layout::from_size_alignment(size, unsafe { Alignment::new_unchecked(align) }) - } - - #[inline(always)] - const fn max_size_for_align(align: Alignment) -> usize { - // (power-of-two implies align != 0.) - - // Rounded up size is: - // size_rounded_up = (size + align - 1) & !(align - 1); - // - // We know from above that align != 0. If adding (align - 1) - // does not overflow, then rounding up will be fine. - // - // Conversely, &-masking with !(align - 1) will subtract off - // only low-order-bits. Thus if overflow occurs with the sum, - // the &-mask cannot subtract enough to undo that overflow. - // - // Above implies that checking for summation overflow is both - // necessary and sufficient. - isize::MAX as usize - (align.as_usize() - 1) - } - - /// Internal helper constructor to skip revalidating alignment validity. - #[inline] - const fn from_size_alignment(size: usize, align: Alignment) -> Result { - if size > Self::max_size_for_align(align) { - return Err(LayoutError); - } - - // SAFETY: Layout::size invariants checked above. - Ok(Layout { size, align }) - } - - /// Creates a layout, bypassing all checks. - /// - /// # Safety - /// - /// This function is unsafe as it does not verify the preconditions from - /// [`Layout::from_size_align`]. - #[stable(feature = "alloc_layout", since = "1.28.0")] - #[rustc_const_stable(feature = "const_alloc_layout_unchecked", since = "1.36.0")] - #[must_use] - #[inline] - #[rustc_allow_const_fn_unstable(ptr_alignment_type)] - #[requires(Layout::from_size_align(size, align).is_ok())] - pub const unsafe fn from_size_align_unchecked(size: usize, align: usize) -> Self { - // SAFETY: the caller is required to uphold the preconditions. - unsafe { Layout { size, align: Alignment::new_unchecked(align) } } - } - - /// The minimum size in bytes for a memory block of this layout. - #[stable(feature = "alloc_layout", since = "1.28.0")] - #[rustc_const_stable(feature = "const_alloc_layout_size_align", since = "1.50.0")] - #[must_use] - #[inline] - pub const fn size(&self) -> usize { - self.size - } - - /// The minimum byte alignment for a memory block of this layout. - /// - /// The returned alignment is guaranteed to be a power of two. - #[stable(feature = "alloc_layout", since = "1.28.0")] - #[rustc_const_stable(feature = "const_alloc_layout_size_align", since = "1.50.0")] - #[must_use = "this returns the minimum alignment, \ - without modifying the layout"] - #[inline] - #[rustc_allow_const_fn_unstable(ptr_alignment_type)] - pub const fn align(&self) -> usize { - self.align.as_usize() - } - - /// Constructs a `Layout` suitable for holding a value of type `T`. - #[stable(feature = "alloc_layout", since = "1.28.0")] - #[rustc_const_stable(feature = "alloc_layout_const_new", since = "1.42.0")] - #[must_use] - #[inline] - pub const fn new() -> Self { - let (size, align) = size_align::(); - // SAFETY: if the type is instantiated, rustc already ensures that its - // layout is valid. Use the unchecked constructor to avoid inserting a - // panicking codepath that needs to be optimized out. - unsafe { Layout::from_size_align_unchecked(size, align) } - } - - /// Produces layout describing a record that could be used to - /// allocate backing structure for `T` (which could be a trait - /// or other unsized type like a slice). - #[stable(feature = "alloc_layout", since = "1.28.0")] - #[rustc_const_unstable(feature = "const_alloc_layout", issue = "67521")] - #[must_use] - #[inline] - pub const fn for_value(t: &T) -> Self { - let (size, align) = (mem::size_of_val(t), mem::align_of_val(t)); - // SAFETY: see rationale in `new` for why this is using the unsafe variant - unsafe { Layout::from_size_align_unchecked(size, align) } - } - - /// Produces layout describing a record that could be used to - /// allocate backing structure for `T` (which could be a trait - /// or other unsized type like a slice). - /// - /// # Safety - /// - /// This function is only safe to call if the following conditions hold: - /// - /// - If `T` is `Sized`, this function is always safe to call. - /// - If the unsized tail of `T` is: - /// - a [slice], then the length of the slice tail must be an initialized - /// integer, and the size of the *entire value* - /// (dynamic tail length + statically sized prefix) must fit in `isize`. - /// - a [trait object], then the vtable part of the pointer must point - /// to a valid vtable for the type `T` acquired by an unsizing coercion, - /// and the size of the *entire value* - /// (dynamic tail length + statically sized prefix) must fit in `isize`. - /// - an (unstable) [extern type], then this function is always safe to - /// call, but may panic or otherwise return the wrong value, as the - /// extern type's layout is not known. This is the same behavior as - /// [`Layout::for_value`] on a reference to an extern type tail. - /// - otherwise, it is conservatively not allowed to call this function. - /// - /// [trait object]: ../../book/ch17-02-trait-objects.html - /// [extern type]: ../../unstable-book/language-features/extern-types.html - #[unstable(feature = "layout_for_ptr", issue = "69835")] - #[rustc_const_unstable(feature = "const_alloc_layout", issue = "67521")] - #[must_use] - pub const unsafe fn for_value_raw(t: *const T) -> Self { - // SAFETY: we pass along the prerequisites of these functions to the caller - let (size, align) = unsafe { (mem::size_of_val_raw(t), mem::align_of_val_raw(t)) }; - // SAFETY: see rationale in `new` for why this is using the unsafe variant - unsafe { Layout::from_size_align_unchecked(size, align) } - } - - /// Creates a `NonNull` that is dangling, but well-aligned for this Layout. - /// - /// Note that the pointer value may potentially represent a valid pointer, - /// which means this must not be used as a "not yet initialized" - /// sentinel value. Types that lazily allocate must track initialization by - /// some other means. - #[unstable(feature = "alloc_layout_extra", issue = "55724")] - #[rustc_const_unstable(feature = "alloc_layout_extra", issue = "55724")] - #[must_use] - #[inline] - pub const fn dangling(&self) -> NonNull { - // SAFETY: align is guaranteed to be non-zero - unsafe { NonNull::new_unchecked(crate::ptr::without_provenance_mut::(self.align())) } - } - - /// Creates a layout describing the record that can hold a value - /// of the same layout as `self`, but that also is aligned to - /// alignment `align` (measured in bytes). - /// - /// If `self` already meets the prescribed alignment, then returns - /// `self`. - /// - /// Note that this method does not add any padding to the overall - /// size, regardless of whether the returned layout has a different - /// alignment. In other words, if `K` has size 16, `K.align_to(32)` - /// will *still* have size 16. - /// - /// Returns an error if the combination of `self.size()` and the given - /// `align` violates the conditions listed in [`Layout::from_size_align`]. - #[stable(feature = "alloc_layout_manipulation", since = "1.44.0")] - #[inline] - pub fn align_to(&self, align: usize) -> Result { - Layout::from_size_align(self.size(), cmp::max(self.align(), align)) - } - - /// Returns the amount of padding we must insert after `self` - /// to ensure that the following address will satisfy `align` - /// (measured in bytes). - /// - /// e.g., if `self.size()` is 9, then `self.padding_needed_for(4)` - /// returns 3, because that is the minimum number of bytes of - /// padding required to get a 4-aligned address (assuming that the - /// corresponding memory block starts at a 4-aligned address). - /// - /// The return value of this function has no meaning if `align` is - /// not a power-of-two. - /// - /// Note that the utility of the returned value requires `align` - /// to be less than or equal to the alignment of the starting - /// address for the whole allocated block of memory. One way to - /// satisfy this constraint is to ensure `align <= self.align()`. - #[unstable(feature = "alloc_layout_extra", issue = "55724")] - #[rustc_const_unstable(feature = "const_alloc_layout", issue = "67521")] - #[must_use = "this returns the padding needed, \ - without modifying the `Layout`"] - #[inline] - pub const fn padding_needed_for(&self, align: usize) -> usize { - let len = self.size(); - - // Rounded up value is: - // len_rounded_up = (len + align - 1) & !(align - 1); - // and then we return the padding difference: `len_rounded_up - len`. - // - // We use modular arithmetic throughout: - // - // 1. align is guaranteed to be > 0, so align - 1 is always - // valid. - // - // 2. `len + align - 1` can overflow by at most `align - 1`, - // so the &-mask with `!(align - 1)` will ensure that in the - // case of overflow, `len_rounded_up` will itself be 0. - // Thus the returned padding, when added to `len`, yields 0, - // which trivially satisfies the alignment `align`. - // - // (Of course, attempts to allocate blocks of memory whose - // size and padding overflow in the above manner should cause - // the allocator to yield an error anyway.) - - let len_rounded_up = len.wrapping_add(align).wrapping_sub(1) & !align.wrapping_sub(1); - len_rounded_up.wrapping_sub(len) - } - - /// Creates a layout by rounding the size of this layout up to a multiple - /// of the layout's alignment. - /// - /// This is equivalent to adding the result of `padding_needed_for` - /// to the layout's current size. - #[stable(feature = "alloc_layout_manipulation", since = "1.44.0")] - #[rustc_const_unstable(feature = "const_alloc_layout", issue = "67521")] - #[must_use = "this returns a new `Layout`, \ - without modifying the original"] - #[inline] - pub const fn pad_to_align(&self) -> Layout { - let pad = self.padding_needed_for(self.align()); - // This cannot overflow. Quoting from the invariant of Layout: - // > `size`, when rounded up to the nearest multiple of `align`, - // > must not overflow isize (i.e., the rounded value must be - // > less than or equal to `isize::MAX`) - let new_size = self.size() + pad; - - // SAFETY: padded size is guaranteed to not exceed `isize::MAX`. - unsafe { Layout::from_size_align_unchecked(new_size, self.align()) } - } - - /// Creates a layout describing the record for `n` instances of - /// `self`, with a suitable amount of padding between each to - /// ensure that each instance is given its requested size and - /// alignment. On success, returns `(k, offs)` where `k` is the - /// layout of the array and `offs` is the distance between the start - /// of each element in the array. - /// - /// On arithmetic overflow, returns `LayoutError`. - #[unstable(feature = "alloc_layout_extra", issue = "55724")] - #[inline] - pub fn repeat(&self, n: usize) -> Result<(Self, usize), LayoutError> { - // This cannot overflow. Quoting from the invariant of Layout: - // > `size`, when rounded up to the nearest multiple of `align`, - // > must not overflow isize (i.e., the rounded value must be - // > less than or equal to `isize::MAX`) - let padded_size = self.size() + self.padding_needed_for(self.align()); - let alloc_size = padded_size.checked_mul(n).ok_or(LayoutError)?; - - // The safe constructor is called here to enforce the isize size limit. - let layout = Layout::from_size_alignment(alloc_size, self.align)?; - Ok((layout, padded_size)) - } - - /// Creates a layout describing the record for `self` followed by - /// `next`, including any necessary padding to ensure that `next` - /// will be properly aligned, but *no trailing padding*. - /// - /// In order to match C representation layout `repr(C)`, you should - /// call `pad_to_align` after extending the layout with all fields. - /// (There is no way to match the default Rust representation - /// layout `repr(Rust)`, as it is unspecified.) - /// - /// Note that the alignment of the resulting layout will be the maximum of - /// those of `self` and `next`, in order to ensure alignment of both parts. - /// - /// Returns `Ok((k, offset))`, where `k` is layout of the concatenated - /// record and `offset` is the relative location, in bytes, of the - /// start of the `next` embedded within the concatenated record - /// (assuming that the record itself starts at offset 0). - /// - /// On arithmetic overflow, returns `LayoutError`. - /// - /// # Examples - /// - /// To calculate the layout of a `#[repr(C)]` structure and the offsets of - /// the fields from its fields' layouts: - /// - /// ```rust - /// # use std::alloc::{Layout, LayoutError}; - /// pub fn repr_c(fields: &[Layout]) -> Result<(Layout, Vec), LayoutError> { - /// let mut offsets = Vec::new(); - /// let mut layout = Layout::from_size_align(0, 1)?; - /// for &field in fields { - /// let (new_layout, offset) = layout.extend(field)?; - /// layout = new_layout; - /// offsets.push(offset); - /// } - /// // Remember to finalize with `pad_to_align`! - /// Ok((layout.pad_to_align(), offsets)) - /// } - /// # // test that it works - /// # #[repr(C)] struct S { a: u64, b: u32, c: u16, d: u32 } - /// # let s = Layout::new::(); - /// # let u16 = Layout::new::(); - /// # let u32 = Layout::new::(); - /// # let u64 = Layout::new::(); - /// # assert_eq!(repr_c(&[u64, u32, u16, u32]), Ok((s, vec![0, 8, 12, 16]))); - /// ``` - #[stable(feature = "alloc_layout_manipulation", since = "1.44.0")] - #[inline] - pub fn extend(&self, next: Self) -> Result<(Self, usize), LayoutError> { - let new_align = cmp::max(self.align, next.align); - let pad = self.padding_needed_for(next.align()); - - let offset = self.size().checked_add(pad).ok_or(LayoutError)?; - let new_size = offset.checked_add(next.size()).ok_or(LayoutError)?; - - // The safe constructor is called here to enforce the isize size limit. - let layout = Layout::from_size_alignment(new_size, new_align)?; - Ok((layout, offset)) - } - - /// Creates a layout describing the record for `n` instances of - /// `self`, with no padding between each instance. - /// - /// Note that, unlike `repeat`, `repeat_packed` does not guarantee - /// that the repeated instances of `self` will be properly - /// aligned, even if a given instance of `self` is properly - /// aligned. In other words, if the layout returned by - /// `repeat_packed` is used to allocate an array, it is not - /// guaranteed that all elements in the array will be properly - /// aligned. - /// - /// On arithmetic overflow, returns `LayoutError`. - #[unstable(feature = "alloc_layout_extra", issue = "55724")] - #[inline] - pub fn repeat_packed(&self, n: usize) -> Result { - let size = self.size().checked_mul(n).ok_or(LayoutError)?; - // The safe constructor is called here to enforce the isize size limit. - Layout::from_size_alignment(size, self.align) - } - - /// Creates a layout describing the record for `self` followed by - /// `next` with no additional padding between the two. Since no - /// padding is inserted, the alignment of `next` is irrelevant, - /// and is not incorporated *at all* into the resulting layout. - /// - /// On arithmetic overflow, returns `LayoutError`. - #[unstable(feature = "alloc_layout_extra", issue = "55724")] - #[inline] - pub fn extend_packed(&self, next: Self) -> Result { - let new_size = self.size().checked_add(next.size()).ok_or(LayoutError)?; - // The safe constructor is called here to enforce the isize size limit. - Layout::from_size_alignment(new_size, self.align) - } - - /// Creates a layout describing the record for a `[T; n]`. - /// - /// On arithmetic overflow or when the total size would exceed - /// `isize::MAX`, returns `LayoutError`. - #[stable(feature = "alloc_layout_manipulation", since = "1.44.0")] - #[rustc_const_unstable(feature = "const_alloc_layout", issue = "67521")] - #[inline] - pub const fn array(n: usize) -> Result { - // Reduce the amount of code we need to monomorphize per `T`. - return inner(mem::size_of::(), Alignment::of::(), n); - - #[inline] - const fn inner( - element_size: usize, - align: Alignment, - n: usize, - ) -> Result { - // We need to check two things about the size: - // - That the total size won't overflow a `usize`, and - // - That the total size still fits in an `isize`. - // By using division we can check them both with a single threshold. - // That'd usually be a bad idea, but thankfully here the element size - // and alignment are constants, so the compiler will fold all of it. - if element_size != 0 && n > Layout::max_size_for_align(align) / element_size { - return Err(LayoutError); - } - - // SAFETY: We just checked that we won't overflow `usize` when we multiply. - // This is a useless hint inside this function, but after inlining this helps - // deduplicate checks for whether the overall capacity is zero (e.g., in RawVec's - // allocation path) before/after this multiplication. - let array_size = unsafe { element_size.unchecked_mul(n) }; - - // SAFETY: We just checked above that the `array_size` will not - // exceed `isize::MAX` even when rounded up to the alignment. - // And `Alignment` guarantees it's a power of two. - unsafe { Ok(Layout::from_size_align_unchecked(array_size, align.as_usize())) } - } - } -} - -#[stable(feature = "alloc_layout", since = "1.28.0")] -#[deprecated( - since = "1.52.0", - note = "Name does not follow std convention, use LayoutError", - suggestion = "LayoutError" -)] -pub type LayoutErr = LayoutError; - -/// The parameters given to `Layout::from_size_align` -/// or some other `Layout` constructor -/// do not satisfy its documented constraints. -#[stable(feature = "alloc_layout_error", since = "1.50.0")] -#[non_exhaustive] -#[derive(Clone, PartialEq, Eq, Debug)] -pub struct LayoutError; - -#[stable(feature = "alloc_layout", since = "1.28.0")] -impl Error for LayoutError {} - -// (we need this for downstream impl of trait Error) -#[stable(feature = "alloc_layout", since = "1.28.0")] -impl fmt::Display for LayoutError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str("invalid parameters to Layout::from_size_align") - } -} - -#[cfg(kani)] -#[unstable(feature="kani", issue="none")] -mod verify { - use super::*; - - #[kani::proof_for_contract(Layout::from_size_align_unchecked)] - pub fn check_from_size_align_unchecked() { - let s = kani::any::(); - let a = kani::any::(); - - unsafe { - let layout = Layout::from_size_align_unchecked(s, a); - assert_eq!(layout.size(), s); - assert_eq!(layout.align(), a); - } - } -} diff --git a/library/core/src/alloc/mod.rs b/library/core/src/alloc/mod.rs deleted file mode 100644 index 1c8e667654469..0000000000000 --- a/library/core/src/alloc/mod.rs +++ /dev/null @@ -1,427 +0,0 @@ -//! Memory allocation APIs - -#![stable(feature = "alloc_module", since = "1.28.0")] - -mod global; -mod layout; - -#[stable(feature = "global_alloc", since = "1.28.0")] -pub use self::global::GlobalAlloc; -#[stable(feature = "alloc_layout", since = "1.28.0")] -pub use self::layout::Layout; -#[stable(feature = "alloc_layout", since = "1.28.0")] -#[deprecated( - since = "1.52.0", - note = "Name does not follow std convention, use LayoutError", - suggestion = "LayoutError" -)] -#[allow(deprecated, deprecated_in_future)] -pub use self::layout::LayoutErr; - -#[stable(feature = "alloc_layout_error", since = "1.50.0")] -pub use self::layout::LayoutError; - -use crate::error::Error; -use crate::fmt; -use crate::ptr::{self, NonNull}; - -/// The `AllocError` error indicates an allocation failure -/// that may be due to resource exhaustion or to -/// something wrong when combining the given input arguments with this -/// allocator. -#[unstable(feature = "allocator_api", issue = "32838")] -#[derive(Copy, Clone, PartialEq, Eq, Debug)] -pub struct AllocError; - -#[unstable( - feature = "allocator_api", - reason = "the precise API and guarantees it provides may be tweaked.", - issue = "32838" -)] -impl Error for AllocError {} - -// (we need this for downstream impl of trait Error) -#[unstable(feature = "allocator_api", issue = "32838")] -impl fmt::Display for AllocError { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str("memory allocation failed") - } -} - -/// An implementation of `Allocator` can allocate, grow, shrink, and deallocate arbitrary blocks of -/// data described via [`Layout`][]. -/// -/// `Allocator` is designed to be implemented on ZSTs, references, or smart pointers because having -/// an allocator like `MyAlloc([u8; N])` cannot be moved, without updating the pointers to the -/// allocated memory. -/// -/// Unlike [`GlobalAlloc`][], zero-sized allocations are allowed in `Allocator`. If an underlying -/// allocator does not support this (like jemalloc) or return a null pointer (such as -/// `libc::malloc`), this must be caught by the implementation. -/// -/// ### Currently allocated memory -/// -/// Some of the methods require that a memory block be *currently allocated* via an allocator. This -/// means that: -/// -/// * the starting address for that memory block was previously returned by [`allocate`], [`grow`], or -/// [`shrink`], and -/// -/// * the memory block has not been subsequently deallocated, where blocks are either deallocated -/// directly by being passed to [`deallocate`] or were changed by being passed to [`grow`] or -/// [`shrink`] that returns `Ok`. If `grow` or `shrink` have returned `Err`, the passed pointer -/// remains valid. -/// -/// [`allocate`]: Allocator::allocate -/// [`grow`]: Allocator::grow -/// [`shrink`]: Allocator::shrink -/// [`deallocate`]: Allocator::deallocate -/// -/// ### Memory fitting -/// -/// Some of the methods require that a layout *fit* a memory block. What it means for a layout to -/// "fit" a memory block means (or equivalently, for a memory block to "fit" a layout) is that the -/// following conditions must hold: -/// -/// * The block must be allocated with the same alignment as [`layout.align()`], and -/// -/// * The provided [`layout.size()`] must fall in the range `min ..= max`, where: -/// - `min` is the size of the layout most recently used to allocate the block, and -/// - `max` is the latest actual size returned from [`allocate`], [`grow`], or [`shrink`]. -/// -/// [`layout.align()`]: Layout::align -/// [`layout.size()`]: Layout::size -/// -/// # Safety -/// -/// * Memory blocks returned from an allocator that are [*currently allocated*] must point to -/// valid memory and retain their validity while they are [*currently allocated*] and the shorter -/// of: -/// - the borrow-checker lifetime of the allocator type itself. -/// - as long as at least one of the instance and all of its clones has not been dropped. -/// -/// * copying, cloning, or moving the allocator must not invalidate memory blocks returned from this -/// allocator. A copied or cloned allocator must behave like the same allocator, and -/// -/// * any pointer to a memory block which is [*currently allocated*] may be passed to any other -/// method of the allocator. -/// -/// [*currently allocated*]: #currently-allocated-memory -#[unstable(feature = "allocator_api", issue = "32838")] -pub unsafe trait Allocator { - /// Attempts to allocate a block of memory. - /// - /// On success, returns a [`NonNull<[u8]>`][NonNull] meeting the size and alignment guarantees of `layout`. - /// - /// The returned block may have a larger size than specified by `layout.size()`, and may or may - /// not have its contents initialized. - /// - /// The returned block of memory remains valid as long as it is [*currently allocated*] and the shorter of: - /// - the borrow-checker lifetime of the allocator type itself. - /// - as long as at the allocator and all its clones has not been dropped. - /// - /// # Errors - /// - /// Returning `Err` indicates that either memory is exhausted or `layout` does not meet - /// allocator's size or alignment constraints. - /// - /// Implementations are encouraged to return `Err` on memory exhaustion rather than panicking or - /// aborting, but this is not a strict requirement. (Specifically: it is *legal* to implement - /// this trait atop an underlying native allocation library that aborts on memory exhaustion.) - /// - /// Clients wishing to abort computation in response to an allocation error are encouraged to - /// call the [`handle_alloc_error`] function, rather than directly invoking `panic!` or similar. - /// - /// [`handle_alloc_error`]: ../../alloc/alloc/fn.handle_alloc_error.html - fn allocate(&self, layout: Layout) -> Result, AllocError>; - - /// Behaves like `allocate`, but also ensures that the returned memory is zero-initialized. - /// - /// # Errors - /// - /// Returning `Err` indicates that either memory is exhausted or `layout` does not meet - /// allocator's size or alignment constraints. - /// - /// Implementations are encouraged to return `Err` on memory exhaustion rather than panicking or - /// aborting, but this is not a strict requirement. (Specifically: it is *legal* to implement - /// this trait atop an underlying native allocation library that aborts on memory exhaustion.) - /// - /// Clients wishing to abort computation in response to an allocation error are encouraged to - /// call the [`handle_alloc_error`] function, rather than directly invoking `panic!` or similar. - /// - /// [`handle_alloc_error`]: ../../alloc/alloc/fn.handle_alloc_error.html - fn allocate_zeroed(&self, layout: Layout) -> Result, AllocError> { - let ptr = self.allocate(layout)?; - // SAFETY: `alloc` returns a valid memory block - unsafe { ptr.as_non_null_ptr().as_ptr().write_bytes(0, ptr.len()) } - Ok(ptr) - } - - /// Deallocates the memory referenced by `ptr`. - /// - /// # Safety - /// - /// * `ptr` must denote a block of memory [*currently allocated*] via this allocator, and - /// * `layout` must [*fit*] that block of memory. - /// - /// [*currently allocated*]: #currently-allocated-memory - /// [*fit*]: #memory-fitting - unsafe fn deallocate(&self, ptr: NonNull, layout: Layout); - - /// Attempts to extend the memory block. - /// - /// Returns a new [`NonNull<[u8]>`][NonNull] containing a pointer and the actual size of the allocated - /// memory. The pointer is suitable for holding data described by `new_layout`. To accomplish - /// this, the allocator may extend the allocation referenced by `ptr` to fit the new layout. - /// - /// If this returns `Ok`, then ownership of the memory block referenced by `ptr` has been - /// transferred to this allocator. Any access to the old `ptr` is Undefined Behavior, even if the - /// allocation was grown in-place. The newly returned pointer is the only valid pointer - /// for accessing this memory now. - /// - /// If this method returns `Err`, then ownership of the memory block has not been transferred to - /// this allocator, and the contents of the memory block are unaltered. - /// - /// # Safety - /// - /// * `ptr` must denote a block of memory [*currently allocated*] via this allocator. - /// * `old_layout` must [*fit*] that block of memory (The `new_layout` argument need not fit it.). - /// * `new_layout.size()` must be greater than or equal to `old_layout.size()`. - /// - /// Note that `new_layout.align()` need not be the same as `old_layout.align()`. - /// - /// [*currently allocated*]: #currently-allocated-memory - /// [*fit*]: #memory-fitting - /// - /// # Errors - /// - /// Returns `Err` if the new layout does not meet the allocator's size and alignment - /// constraints of the allocator, or if growing otherwise fails. - /// - /// Implementations are encouraged to return `Err` on memory exhaustion rather than panicking or - /// aborting, but this is not a strict requirement. (Specifically: it is *legal* to implement - /// this trait atop an underlying native allocation library that aborts on memory exhaustion.) - /// - /// Clients wishing to abort computation in response to an allocation error are encouraged to - /// call the [`handle_alloc_error`] function, rather than directly invoking `panic!` or similar. - /// - /// [`handle_alloc_error`]: ../../alloc/alloc/fn.handle_alloc_error.html - unsafe fn grow( - &self, - ptr: NonNull, - old_layout: Layout, - new_layout: Layout, - ) -> Result, AllocError> { - debug_assert!( - new_layout.size() >= old_layout.size(), - "`new_layout.size()` must be greater than or equal to `old_layout.size()`" - ); - - let new_ptr = self.allocate(new_layout)?; - - // SAFETY: because `new_layout.size()` must be greater than or equal to - // `old_layout.size()`, both the old and new memory allocation are valid for reads and - // writes for `old_layout.size()` bytes. Also, because the old allocation wasn't yet - // deallocated, it cannot overlap `new_ptr`. Thus, the call to `copy_nonoverlapping` is - // safe. The safety contract for `dealloc` must be upheld by the caller. - unsafe { - ptr::copy_nonoverlapping(ptr.as_ptr(), new_ptr.as_mut_ptr(), old_layout.size()); - self.deallocate(ptr, old_layout); - } - - Ok(new_ptr) - } - - /// Behaves like `grow`, but also ensures that the new contents are set to zero before being - /// returned. - /// - /// The memory block will contain the following contents after a successful call to - /// `grow_zeroed`: - /// * Bytes `0..old_layout.size()` are preserved from the original allocation. - /// * Bytes `old_layout.size()..old_size` will either be preserved or zeroed, depending on - /// the allocator implementation. `old_size` refers to the size of the memory block prior - /// to the `grow_zeroed` call, which may be larger than the size that was originally - /// requested when it was allocated. - /// * Bytes `old_size..new_size` are zeroed. `new_size` refers to the size of the memory - /// block returned by the `grow_zeroed` call. - /// - /// # Safety - /// - /// * `ptr` must denote a block of memory [*currently allocated*] via this allocator. - /// * `old_layout` must [*fit*] that block of memory (The `new_layout` argument need not fit it.). - /// * `new_layout.size()` must be greater than or equal to `old_layout.size()`. - /// - /// Note that `new_layout.align()` need not be the same as `old_layout.align()`. - /// - /// [*currently allocated*]: #currently-allocated-memory - /// [*fit*]: #memory-fitting - /// - /// # Errors - /// - /// Returns `Err` if the new layout does not meet the allocator's size and alignment - /// constraints of the allocator, or if growing otherwise fails. - /// - /// Implementations are encouraged to return `Err` on memory exhaustion rather than panicking or - /// aborting, but this is not a strict requirement. (Specifically: it is *legal* to implement - /// this trait atop an underlying native allocation library that aborts on memory exhaustion.) - /// - /// Clients wishing to abort computation in response to an allocation error are encouraged to - /// call the [`handle_alloc_error`] function, rather than directly invoking `panic!` or similar. - /// - /// [`handle_alloc_error`]: ../../alloc/alloc/fn.handle_alloc_error.html - unsafe fn grow_zeroed( - &self, - ptr: NonNull, - old_layout: Layout, - new_layout: Layout, - ) -> Result, AllocError> { - debug_assert!( - new_layout.size() >= old_layout.size(), - "`new_layout.size()` must be greater than or equal to `old_layout.size()`" - ); - - let new_ptr = self.allocate_zeroed(new_layout)?; - - // SAFETY: because `new_layout.size()` must be greater than or equal to - // `old_layout.size()`, both the old and new memory allocation are valid for reads and - // writes for `old_layout.size()` bytes. Also, because the old allocation wasn't yet - // deallocated, it cannot overlap `new_ptr`. Thus, the call to `copy_nonoverlapping` is - // safe. The safety contract for `dealloc` must be upheld by the caller. - unsafe { - ptr::copy_nonoverlapping(ptr.as_ptr(), new_ptr.as_mut_ptr(), old_layout.size()); - self.deallocate(ptr, old_layout); - } - - Ok(new_ptr) - } - - /// Attempts to shrink the memory block. - /// - /// Returns a new [`NonNull<[u8]>`][NonNull] containing a pointer and the actual size of the allocated - /// memory. The pointer is suitable for holding data described by `new_layout`. To accomplish - /// this, the allocator may shrink the allocation referenced by `ptr` to fit the new layout. - /// - /// If this returns `Ok`, then ownership of the memory block referenced by `ptr` has been - /// transferred to this allocator. Any access to the old `ptr` is Undefined Behavior, even if the - /// allocation was shrunk in-place. The newly returned pointer is the only valid pointer - /// for accessing this memory now. - /// - /// If this method returns `Err`, then ownership of the memory block has not been transferred to - /// this allocator, and the contents of the memory block are unaltered. - /// - /// # Safety - /// - /// * `ptr` must denote a block of memory [*currently allocated*] via this allocator. - /// * `old_layout` must [*fit*] that block of memory (The `new_layout` argument need not fit it.). - /// * `new_layout.size()` must be smaller than or equal to `old_layout.size()`. - /// - /// Note that `new_layout.align()` need not be the same as `old_layout.align()`. - /// - /// [*currently allocated*]: #currently-allocated-memory - /// [*fit*]: #memory-fitting - /// - /// # Errors - /// - /// Returns `Err` if the new layout does not meet the allocator's size and alignment - /// constraints of the allocator, or if shrinking otherwise fails. - /// - /// Implementations are encouraged to return `Err` on memory exhaustion rather than panicking or - /// aborting, but this is not a strict requirement. (Specifically: it is *legal* to implement - /// this trait atop an underlying native allocation library that aborts on memory exhaustion.) - /// - /// Clients wishing to abort computation in response to an allocation error are encouraged to - /// call the [`handle_alloc_error`] function, rather than directly invoking `panic!` or similar. - /// - /// [`handle_alloc_error`]: ../../alloc/alloc/fn.handle_alloc_error.html - unsafe fn shrink( - &self, - ptr: NonNull, - old_layout: Layout, - new_layout: Layout, - ) -> Result, AllocError> { - debug_assert!( - new_layout.size() <= old_layout.size(), - "`new_layout.size()` must be smaller than or equal to `old_layout.size()`" - ); - - let new_ptr = self.allocate(new_layout)?; - - // SAFETY: because `new_layout.size()` must be lower than or equal to - // `old_layout.size()`, both the old and new memory allocation are valid for reads and - // writes for `new_layout.size()` bytes. Also, because the old allocation wasn't yet - // deallocated, it cannot overlap `new_ptr`. Thus, the call to `copy_nonoverlapping` is - // safe. The safety contract for `dealloc` must be upheld by the caller. - unsafe { - ptr::copy_nonoverlapping(ptr.as_ptr(), new_ptr.as_mut_ptr(), new_layout.size()); - self.deallocate(ptr, old_layout); - } - - Ok(new_ptr) - } - - /// Creates a "by reference" adapter for this instance of `Allocator`. - /// - /// The returned adapter also implements `Allocator` and will simply borrow this. - #[inline(always)] - fn by_ref(&self) -> &Self - where - Self: Sized, - { - self - } -} - -#[unstable(feature = "allocator_api", issue = "32838")] -unsafe impl Allocator for &A -where - A: Allocator + ?Sized, -{ - #[inline] - fn allocate(&self, layout: Layout) -> Result, AllocError> { - (**self).allocate(layout) - } - - #[inline] - fn allocate_zeroed(&self, layout: Layout) -> Result, AllocError> { - (**self).allocate_zeroed(layout) - } - - #[inline] - unsafe fn deallocate(&self, ptr: NonNull, layout: Layout) { - // SAFETY: the safety contract must be upheld by the caller - unsafe { (**self).deallocate(ptr, layout) } - } - - #[inline] - unsafe fn grow( - &self, - ptr: NonNull, - old_layout: Layout, - new_layout: Layout, - ) -> Result, AllocError> { - // SAFETY: the safety contract must be upheld by the caller - unsafe { (**self).grow(ptr, old_layout, new_layout) } - } - - #[inline] - unsafe fn grow_zeroed( - &self, - ptr: NonNull, - old_layout: Layout, - new_layout: Layout, - ) -> Result, AllocError> { - // SAFETY: the safety contract must be upheld by the caller - unsafe { (**self).grow_zeroed(ptr, old_layout, new_layout) } - } - - #[inline] - unsafe fn shrink( - &self, - ptr: NonNull, - old_layout: Layout, - new_layout: Layout, - ) -> Result, AllocError> { - // SAFETY: the safety contract must be upheld by the caller - unsafe { (**self).shrink(ptr, old_layout, new_layout) } - } -} diff --git a/library/core/src/any.rs b/library/core/src/any.rs deleted file mode 100644 index 37cb8e7d303af..0000000000000 --- a/library/core/src/any.rs +++ /dev/null @@ -1,741 +0,0 @@ -//! Utilities for dynamic typing or type reflection. -//! -//! # `Any` and `TypeId` -//! -//! `Any` itself can be used to get a `TypeId`, and has more features when used -//! as a trait object. As `&dyn Any` (a borrowed trait object), it has the `is` -//! and `downcast_ref` methods, to test if the contained value is of a given type, -//! and to get a reference to the inner value as a type. As `&mut dyn Any`, there -//! is also the `downcast_mut` method, for getting a mutable reference to the -//! inner value. `Box` adds the `downcast` method, which attempts to -//! convert to a `Box`. See the [`Box`] documentation for the full details. -//! -//! Note that `&dyn Any` is limited to testing whether a value is of a specified -//! concrete type, and cannot be used to test whether a type implements a trait. -//! -//! [`Box`]: ../../std/boxed/struct.Box.html -//! -//! # Smart pointers and `dyn Any` -//! -//! One piece of behavior to keep in mind when using `Any` as a trait object, -//! especially with types like `Box` or `Arc`, is that simply -//! calling `.type_id()` on the value will produce the `TypeId` of the -//! *container*, not the underlying trait object. This can be avoided by -//! converting the smart pointer into a `&dyn Any` instead, which will return -//! the object's `TypeId`. For example: -//! -//! ``` -//! use std::any::{Any, TypeId}; -//! -//! let boxed: Box = Box::new(3_i32); -//! -//! // You're more likely to want this: -//! let actual_id = (&*boxed).type_id(); -//! // ... than this: -//! let boxed_id = boxed.type_id(); -//! -//! assert_eq!(actual_id, TypeId::of::()); -//! assert_eq!(boxed_id, TypeId::of::>()); -//! ``` -//! -//! ## Examples -//! -//! Consider a situation where we want to log a value passed to a function. -//! We know the value we're working on implements `Debug`, but we don't know its -//! concrete type. We want to give special treatment to certain types: in this -//! case printing out the length of `String` values prior to their value. -//! We don't know the concrete type of our value at compile time, so we need to -//! use runtime reflection instead. -//! -//! ```rust -//! use std::fmt::Debug; -//! use std::any::Any; -//! -//! // Logger function for any type that implements `Debug`. -//! fn log(value: &T) { -//! let value_any = value as &dyn Any; -//! -//! // Try to convert our value to a `String`. If successful, we want to -//! // output the `String`'s length as well as its value. If not, it's a -//! // different type: just print it out unadorned. -//! match value_any.downcast_ref::() { -//! Some(as_string) => { -//! println!("String ({}): {}", as_string.len(), as_string); -//! } -//! None => { -//! println!("{value:?}"); -//! } -//! } -//! } -//! -//! // This function wants to log its parameter out prior to doing work with it. -//! fn do_work(value: &T) { -//! log(value); -//! // ...do some other work -//! } -//! -//! fn main() { -//! let my_string = "Hello World".to_string(); -//! do_work(&my_string); -//! -//! let my_i8: i8 = 100; -//! do_work(&my_i8); -//! } -//! ``` -//! - -#![stable(feature = "rust1", since = "1.0.0")] - -use crate::fmt; -use crate::hash; -use crate::intrinsics; - -/////////////////////////////////////////////////////////////////////////////// -// Any trait -/////////////////////////////////////////////////////////////////////////////// - -/// A trait to emulate dynamic typing. -/// -/// Most types implement `Any`. However, any type which contains a non-`'static` reference does not. -/// See the [module-level documentation][mod] for more details. -/// -/// [mod]: crate::any -// This trait is not unsafe, though we rely on the specifics of it's sole impl's -// `type_id` function in unsafe code (e.g., `downcast`). Normally, that would be -// a problem, but because the only impl of `Any` is a blanket implementation, no -// other code can implement `Any`. -// -// We could plausibly make this trait unsafe -- it would not cause breakage, -// since we control all the implementations -- but we choose not to as that's -// both not really necessary and may confuse users about the distinction of -// unsafe traits and unsafe methods (i.e., `type_id` would still be safe to call, -// but we would likely want to indicate as such in documentation). -#[stable(feature = "rust1", since = "1.0.0")] -#[cfg_attr(not(test), rustc_diagnostic_item = "Any")] -pub trait Any: 'static { - /// Gets the `TypeId` of `self`. - /// - /// If called on a `dyn Any` trait object - /// (or a trait object of a subtrait of `Any`), - /// this returns the `TypeId` of the underlying - /// concrete type, not that of `dyn Any` itself. - /// - /// # Examples - /// - /// ``` - /// use std::any::{Any, TypeId}; - /// - /// fn is_string(s: &dyn Any) -> bool { - /// TypeId::of::() == s.type_id() - /// } - /// - /// assert_eq!(is_string(&0), false); - /// assert_eq!(is_string(&"cookie monster".to_string()), true); - /// ``` - #[stable(feature = "get_type_id", since = "1.34.0")] - fn type_id(&self) -> TypeId; -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Any for T { - fn type_id(&self) -> TypeId { - TypeId::of::() - } -} - -/////////////////////////////////////////////////////////////////////////////// -// Extension methods for Any trait objects. -/////////////////////////////////////////////////////////////////////////////// - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for dyn Any { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Any").finish_non_exhaustive() - } -} - -// Ensure that the result of e.g., joining a thread can be printed and -// hence used with `unwrap`. May eventually no longer be needed if -// dispatch works with upcasting. -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for dyn Any + Send { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Any").finish_non_exhaustive() - } -} - -#[stable(feature = "any_send_sync_methods", since = "1.28.0")] -impl fmt::Debug for dyn Any + Send + Sync { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("Any").finish_non_exhaustive() - } -} - -impl dyn Any { - /// Returns `true` if the inner type is the same as `T`. - /// - /// # Examples - /// - /// ``` - /// use std::any::Any; - /// - /// fn is_string(s: &dyn Any) { - /// if s.is::() { - /// println!("It's a string!"); - /// } else { - /// println!("Not a string..."); - /// } - /// } - /// - /// is_string(&0); - /// is_string(&"cookie monster".to_string()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn is(&self) -> bool { - // Get `TypeId` of the type this function is instantiated with. - let t = TypeId::of::(); - - // Get `TypeId` of the type in the trait object (`self`). - let concrete = self.type_id(); - - // Compare both `TypeId`s on equality. - t == concrete - } - - /// Returns some reference to the inner value if it is of type `T`, or - /// `None` if it isn't. - /// - /// # Examples - /// - /// ``` - /// use std::any::Any; - /// - /// fn print_if_string(s: &dyn Any) { - /// if let Some(string) = s.downcast_ref::() { - /// println!("It's a string({}): '{}'", string.len(), string); - /// } else { - /// println!("Not a string..."); - /// } - /// } - /// - /// print_if_string(&0); - /// print_if_string(&"cookie monster".to_string()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn downcast_ref(&self) -> Option<&T> { - if self.is::() { - // SAFETY: just checked whether we are pointing to the correct type, and we can rely on - // that check for memory safety because we have implemented Any for all types; no other - // impls can exist as they would conflict with our impl. - unsafe { Some(self.downcast_ref_unchecked()) } - } else { - None - } - } - - /// Returns some mutable reference to the inner value if it is of type `T`, or - /// `None` if it isn't. - /// - /// # Examples - /// - /// ``` - /// use std::any::Any; - /// - /// fn modify_if_u32(s: &mut dyn Any) { - /// if let Some(num) = s.downcast_mut::() { - /// *num = 42; - /// } - /// } - /// - /// let mut x = 10u32; - /// let mut s = "starlord".to_string(); - /// - /// modify_if_u32(&mut x); - /// modify_if_u32(&mut s); - /// - /// assert_eq!(x, 42); - /// assert_eq!(&s, "starlord"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn downcast_mut(&mut self) -> Option<&mut T> { - if self.is::() { - // SAFETY: just checked whether we are pointing to the correct type, and we can rely on - // that check for memory safety because we have implemented Any for all types; no other - // impls can exist as they would conflict with our impl. - unsafe { Some(self.downcast_mut_unchecked()) } - } else { - None - } - } - - /// Returns a reference to the inner value as type `dyn T`. - /// - /// # Examples - /// - /// ``` - /// #![feature(downcast_unchecked)] - /// - /// use std::any::Any; - /// - /// let x: Box = Box::new(1_usize); - /// - /// unsafe { - /// assert_eq!(*x.downcast_ref_unchecked::(), 1); - /// } - /// ``` - /// - /// # Safety - /// - /// The contained value must be of type `T`. Calling this method - /// with the incorrect type is *undefined behavior*. - #[unstable(feature = "downcast_unchecked", issue = "90850")] - #[inline] - pub unsafe fn downcast_ref_unchecked(&self) -> &T { - debug_assert!(self.is::()); - // SAFETY: caller guarantees that T is the correct type - unsafe { &*(self as *const dyn Any as *const T) } - } - - /// Returns a mutable reference to the inner value as type `dyn T`. - /// - /// # Examples - /// - /// ``` - /// #![feature(downcast_unchecked)] - /// - /// use std::any::Any; - /// - /// let mut x: Box = Box::new(1_usize); - /// - /// unsafe { - /// *x.downcast_mut_unchecked::() += 1; - /// } - /// - /// assert_eq!(*x.downcast_ref::().unwrap(), 2); - /// ``` - /// - /// # Safety - /// - /// The contained value must be of type `T`. Calling this method - /// with the incorrect type is *undefined behavior*. - #[unstable(feature = "downcast_unchecked", issue = "90850")] - #[inline] - pub unsafe fn downcast_mut_unchecked(&mut self) -> &mut T { - debug_assert!(self.is::()); - // SAFETY: caller guarantees that T is the correct type - unsafe { &mut *(self as *mut dyn Any as *mut T) } - } -} - -impl dyn Any + Send { - /// Forwards to the method defined on the type `dyn Any`. - /// - /// # Examples - /// - /// ``` - /// use std::any::Any; - /// - /// fn is_string(s: &(dyn Any + Send)) { - /// if s.is::() { - /// println!("It's a string!"); - /// } else { - /// println!("Not a string..."); - /// } - /// } - /// - /// is_string(&0); - /// is_string(&"cookie monster".to_string()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn is(&self) -> bool { - ::is::(self) - } - - /// Forwards to the method defined on the type `dyn Any`. - /// - /// # Examples - /// - /// ``` - /// use std::any::Any; - /// - /// fn print_if_string(s: &(dyn Any + Send)) { - /// if let Some(string) = s.downcast_ref::() { - /// println!("It's a string({}): '{}'", string.len(), string); - /// } else { - /// println!("Not a string..."); - /// } - /// } - /// - /// print_if_string(&0); - /// print_if_string(&"cookie monster".to_string()); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn downcast_ref(&self) -> Option<&T> { - ::downcast_ref::(self) - } - - /// Forwards to the method defined on the type `dyn Any`. - /// - /// # Examples - /// - /// ``` - /// use std::any::Any; - /// - /// fn modify_if_u32(s: &mut (dyn Any + Send)) { - /// if let Some(num) = s.downcast_mut::() { - /// *num = 42; - /// } - /// } - /// - /// let mut x = 10u32; - /// let mut s = "starlord".to_string(); - /// - /// modify_if_u32(&mut x); - /// modify_if_u32(&mut s); - /// - /// assert_eq!(x, 42); - /// assert_eq!(&s, "starlord"); - /// ``` - #[stable(feature = "rust1", since = "1.0.0")] - #[inline] - pub fn downcast_mut(&mut self) -> Option<&mut T> { - ::downcast_mut::(self) - } - - /// Forwards to the method defined on the type `dyn Any`. - /// - /// # Examples - /// - /// ``` - /// #![feature(downcast_unchecked)] - /// - /// use std::any::Any; - /// - /// let x: Box = Box::new(1_usize); - /// - /// unsafe { - /// assert_eq!(*x.downcast_ref_unchecked::(), 1); - /// } - /// ``` - /// - /// # Safety - /// - /// Same as the method on the type `dyn Any`. - #[unstable(feature = "downcast_unchecked", issue = "90850")] - #[inline] - pub unsafe fn downcast_ref_unchecked(&self) -> &T { - // SAFETY: guaranteed by caller - unsafe { ::downcast_ref_unchecked::(self) } - } - - /// Forwards to the method defined on the type `dyn Any`. - /// - /// # Examples - /// - /// ``` - /// #![feature(downcast_unchecked)] - /// - /// use std::any::Any; - /// - /// let mut x: Box = Box::new(1_usize); - /// - /// unsafe { - /// *x.downcast_mut_unchecked::() += 1; - /// } - /// - /// assert_eq!(*x.downcast_ref::().unwrap(), 2); - /// ``` - /// - /// # Safety - /// - /// Same as the method on the type `dyn Any`. - #[unstable(feature = "downcast_unchecked", issue = "90850")] - #[inline] - pub unsafe fn downcast_mut_unchecked(&mut self) -> &mut T { - // SAFETY: guaranteed by caller - unsafe { ::downcast_mut_unchecked::(self) } - } -} - -impl dyn Any + Send + Sync { - /// Forwards to the method defined on the type `Any`. - /// - /// # Examples - /// - /// ``` - /// use std::any::Any; - /// - /// fn is_string(s: &(dyn Any + Send + Sync)) { - /// if s.is::() { - /// println!("It's a string!"); - /// } else { - /// println!("Not a string..."); - /// } - /// } - /// - /// is_string(&0); - /// is_string(&"cookie monster".to_string()); - /// ``` - #[stable(feature = "any_send_sync_methods", since = "1.28.0")] - #[inline] - pub fn is(&self) -> bool { - ::is::(self) - } - - /// Forwards to the method defined on the type `Any`. - /// - /// # Examples - /// - /// ``` - /// use std::any::Any; - /// - /// fn print_if_string(s: &(dyn Any + Send + Sync)) { - /// if let Some(string) = s.downcast_ref::() { - /// println!("It's a string({}): '{}'", string.len(), string); - /// } else { - /// println!("Not a string..."); - /// } - /// } - /// - /// print_if_string(&0); - /// print_if_string(&"cookie monster".to_string()); - /// ``` - #[stable(feature = "any_send_sync_methods", since = "1.28.0")] - #[inline] - pub fn downcast_ref(&self) -> Option<&T> { - ::downcast_ref::(self) - } - - /// Forwards to the method defined on the type `Any`. - /// - /// # Examples - /// - /// ``` - /// use std::any::Any; - /// - /// fn modify_if_u32(s: &mut (dyn Any + Send + Sync)) { - /// if let Some(num) = s.downcast_mut::() { - /// *num = 42; - /// } - /// } - /// - /// let mut x = 10u32; - /// let mut s = "starlord".to_string(); - /// - /// modify_if_u32(&mut x); - /// modify_if_u32(&mut s); - /// - /// assert_eq!(x, 42); - /// assert_eq!(&s, "starlord"); - /// ``` - #[stable(feature = "any_send_sync_methods", since = "1.28.0")] - #[inline] - pub fn downcast_mut(&mut self) -> Option<&mut T> { - ::downcast_mut::(self) - } - - /// Forwards to the method defined on the type `Any`. - /// - /// # Examples - /// - /// ``` - /// #![feature(downcast_unchecked)] - /// - /// use std::any::Any; - /// - /// let x: Box = Box::new(1_usize); - /// - /// unsafe { - /// assert_eq!(*x.downcast_ref_unchecked::(), 1); - /// } - /// ``` - #[unstable(feature = "downcast_unchecked", issue = "90850")] - #[inline] - pub unsafe fn downcast_ref_unchecked(&self) -> &T { - // SAFETY: guaranteed by caller - unsafe { ::downcast_ref_unchecked::(self) } - } - - /// Forwards to the method defined on the type `Any`. - /// - /// # Examples - /// - /// ``` - /// #![feature(downcast_unchecked)] - /// - /// use std::any::Any; - /// - /// let mut x: Box = Box::new(1_usize); - /// - /// unsafe { - /// *x.downcast_mut_unchecked::() += 1; - /// } - /// - /// assert_eq!(*x.downcast_ref::().unwrap(), 2); - /// ``` - #[unstable(feature = "downcast_unchecked", issue = "90850")] - #[inline] - pub unsafe fn downcast_mut_unchecked(&mut self) -> &mut T { - // SAFETY: guaranteed by caller - unsafe { ::downcast_mut_unchecked::(self) } - } -} - -/////////////////////////////////////////////////////////////////////////////// -// TypeID and its methods -/////////////////////////////////////////////////////////////////////////////// - -/// A `TypeId` represents a globally unique identifier for a type. -/// -/// Each `TypeId` is an opaque object which does not allow inspection of what's -/// inside but does allow basic operations such as cloning, comparison, -/// printing, and showing. -/// -/// A `TypeId` is currently only available for types which ascribe to `'static`, -/// but this limitation may be removed in the future. -/// -/// While `TypeId` implements `Hash`, `PartialOrd`, and `Ord`, it is worth -/// noting that the hashes and ordering will vary between Rust releases. Beware -/// of relying on them inside of your code! -#[derive(Clone, Copy, Debug, Eq, PartialOrd, Ord)] -#[stable(feature = "rust1", since = "1.0.0")] -pub struct TypeId { - // We avoid using `u128` because that imposes higher alignment requirements on many platforms. - // See issue #115620 for more information. - t: (u64, u64), -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq for TypeId { - #[inline] - fn eq(&self, other: &Self) -> bool { - self.t == other.t - } -} - -impl TypeId { - /// Returns the `TypeId` of the type this generic function has been - /// instantiated with. - /// - /// # Examples - /// - /// ``` - /// use std::any::{Any, TypeId}; - /// - /// fn is_string(_s: &T) -> bool { - /// TypeId::of::() == TypeId::of::() - /// } - /// - /// assert_eq!(is_string(&0), false); - /// assert_eq!(is_string(&"cookie monster".to_string()), true); - /// ``` - #[must_use] - #[stable(feature = "rust1", since = "1.0.0")] - #[rustc_const_unstable(feature = "const_type_id", issue = "77125")] - pub const fn of() -> TypeId { - let t: u128 = intrinsics::type_id::(); - - let t1 = (t >> 64) as u64; - let t2 = t as u64; - TypeId { t: (t1, t2) } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl hash::Hash for TypeId { - #[inline] - fn hash(&self, state: &mut H) { - // We only hash the lower 64 bits of our (128 bit) internal numeric ID, - // because: - // - The hashing algorithm which backs `TypeId` is expected to be - // unbiased and high quality, meaning further mixing would be somewhat - // redundant compared to choosing (the lower) 64 bits arbitrarily. - // - `Hasher::finish` returns a u64 anyway, so the extra entropy we'd - // get from hashing the full value would probably not be useful - // (especially given the previous point about the lower 64 bits being - // high quality on their own). - // - It is correct to do so -- only hashing a subset of `self` is still - // with an `Eq` implementation that considers the entire value, as - // ours does. - self.t.1.hash(state); - } -} - -/// Returns the name of a type as a string slice. -/// -/// # Note -/// -/// This is intended for diagnostic use. The exact contents and format of the -/// string returned are not specified, other than being a best-effort -/// description of the type. For example, amongst the strings -/// that `type_name::>()` might return are `"Option"` and -/// `"std::option::Option"`. -/// -/// The returned string must not be considered to be a unique identifier of a -/// type as multiple types may map to the same type name. Similarly, there is no -/// guarantee that all parts of a type will appear in the returned string: for -/// example, lifetime specifiers are currently not included. In addition, the -/// output may change between versions of the compiler. -/// -/// The current implementation uses the same infrastructure as compiler -/// diagnostics and debuginfo, but this is not guaranteed. -/// -/// # Examples -/// -/// ```rust -/// assert_eq!( -/// std::any::type_name::>(), -/// "core::option::Option", -/// ); -/// ``` -#[must_use] -#[stable(feature = "type_name", since = "1.38.0")] -#[rustc_const_unstable(feature = "const_type_name", issue = "63084")] -pub const fn type_name() -> &'static str { - intrinsics::type_name::() -} - -/// Returns the type name of the pointed-to value as a string slice. -/// -/// This is the same as `type_name::()`, but can be used where the type of a -/// variable is not easily available. -/// -/// # Note -/// -/// Like [`type_name`], this is intended for diagnostic use and the exact output is not -/// guaranteed. It provides a best-effort description, but the output may change between -/// versions of the compiler. -/// -/// In short: use this for debugging, avoid using the output to affect program behavior. More -/// information is available at [`type_name`]. -/// -/// Additionally, this function does not resolve trait objects. This means that -/// `type_name_of_val(&7u32 as &dyn Debug)` may return `"dyn Debug"`, but will not return `"u32"` -/// at this time. -/// -/// # Examples -/// -/// Prints the default integer and float types. -/// -/// ```rust -/// use std::any::type_name_of_val; -/// -/// let s = "foo"; -/// let x: i32 = 1; -/// let y: f32 = 1.0; -/// -/// assert!(type_name_of_val(&s).contains("str")); -/// assert!(type_name_of_val(&x).contains("i32")); -/// assert!(type_name_of_val(&y).contains("f32")); -/// ``` -#[must_use] -#[stable(feature = "type_name_of_val", since = "1.76.0")] -#[rustc_const_unstable(feature = "const_type_name", issue = "63084")] -pub const fn type_name_of_val(_val: &T) -> &'static str { - type_name::() -} diff --git a/library/core/src/arch.rs b/library/core/src/arch.rs deleted file mode 100644 index 31d6bc36fc8b9..0000000000000 --- a/library/core/src/arch.rs +++ /dev/null @@ -1,31 +0,0 @@ -#![doc = include_str!("../../stdarch/crates/core_arch/src/core_arch_docs.md")] - -#[allow(unused_imports)] -#[stable(feature = "simd_arch", since = "1.27.0")] -pub use crate::core_arch::arch::*; - -/// Inline assembly. -/// -/// Refer to [Rust By Example] for a usage guide and the [reference] for -/// detailed information about the syntax and available options. -/// -/// [Rust By Example]: https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html -/// [reference]: https://doc.rust-lang.org/nightly/reference/inline-assembly.html -#[stable(feature = "asm", since = "1.59.0")] -#[rustc_builtin_macro] -pub macro asm("assembly template", $(operands,)* $(options($(option),*))?) { - /* compiler built-in */ -} - -/// Module-level inline assembly. -/// -/// Refer to [Rust By Example] for a usage guide and the [reference] for -/// detailed information about the syntax and available options. -/// -/// [Rust By Example]: https://doc.rust-lang.org/nightly/rust-by-example/unsafe/asm.html -/// [reference]: https://doc.rust-lang.org/nightly/reference/inline-assembly.html -#[stable(feature = "global_asm", since = "1.59.0")] -#[rustc_builtin_macro] -pub macro global_asm("assembly template", $(operands,)* $(options($(option),*))?) { - /* compiler built-in */ -} diff --git a/library/core/src/array/ascii.rs b/library/core/src/array/ascii.rs deleted file mode 100644 index 3fea9a44049fb..0000000000000 --- a/library/core/src/array/ascii.rs +++ /dev/null @@ -1,47 +0,0 @@ -use crate::ascii; - -#[cfg(not(test))] -impl [u8; N] { - /// Converts this array of bytes into a array of ASCII characters, - /// or returns `None` if any of the characters is non-ASCII. - /// - /// # Examples - /// - /// ``` - /// #![feature(ascii_char)] - /// #![feature(const_option)] - /// - /// const HEX_DIGITS: [std::ascii::Char; 16] = - /// *b"0123456789abcdef".as_ascii().unwrap(); - /// - /// assert_eq!(HEX_DIGITS[1].as_str(), "1"); - /// assert_eq!(HEX_DIGITS[10].as_str(), "a"); - /// ``` - #[unstable(feature = "ascii_char", issue = "110998")] - #[must_use] - #[inline] - pub const fn as_ascii(&self) -> Option<&[ascii::Char; N]> { - if self.is_ascii() { - // SAFETY: Just checked that it's ASCII - Some(unsafe { self.as_ascii_unchecked() }) - } else { - None - } - } - - /// Converts this array of bytes into a array of ASCII characters, - /// without checking whether they're valid. - /// - /// # Safety - /// - /// Every byte in the array must be in `0..=127`, or else this is UB. - #[unstable(feature = "ascii_char", issue = "110998")] - #[must_use] - #[inline] - pub const unsafe fn as_ascii_unchecked(&self) -> &[ascii::Char; N] { - let byte_ptr: *const [u8; N] = self; - let ascii_ptr = byte_ptr as *const [ascii::Char; N]; - // SAFETY: The caller promised all the bytes are ASCII - unsafe { &*ascii_ptr } - } -} diff --git a/library/core/src/array/drain.rs b/library/core/src/array/drain.rs deleted file mode 100644 index 5fadf907b6219..0000000000000 --- a/library/core/src/array/drain.rs +++ /dev/null @@ -1,76 +0,0 @@ -use crate::iter::{TrustedLen, UncheckedIterator}; -use crate::mem::ManuallyDrop; -use crate::ptr::drop_in_place; -use crate::slice; - -/// A situationally-optimized version of `array.into_iter().for_each(func)`. -/// -/// [`crate::array::IntoIter`]s are great when you need an owned iterator, but -/// storing the entire array *inside* the iterator like that can sometimes -/// pessimize code. Notable, it can be more bytes than you really want to move -/// around, and because the array accesses index into it SRoA has a harder time -/// optimizing away the type than it does iterators that just hold a couple pointers. -/// -/// Thus this function exists, which gives a way to get *moved* access to the -/// elements of an array using a small iterator -- no bigger than a slice iterator. -/// -/// The function-taking-a-closure structure makes it safe, as it keeps callers -/// from looking at already-dropped elements. -pub(crate) fn drain_array_with( - array: [T; N], - func: impl for<'a> FnOnce(Drain<'a, T>) -> R, -) -> R { - let mut array = ManuallyDrop::new(array); - // SAFETY: Now that the local won't drop it, it's ok to construct the `Drain` which will. - let drain = Drain(array.iter_mut()); - func(drain) -} - -/// See [`drain_array_with`] -- this is `pub(crate)` only so it's allowed to be -/// mentioned in the signature of that method. (Otherwise it hits `E0446`.) -// INVARIANT: It's ok to drop the remainder of the inner iterator. -pub(crate) struct Drain<'a, T>(slice::IterMut<'a, T>); - -impl Drop for Drain<'_, T> { - fn drop(&mut self) { - // SAFETY: By the type invariant, we're allowed to drop all these. - unsafe { drop_in_place(self.0.as_mut_slice()) } - } -} - -impl Iterator for Drain<'_, T> { - type Item = T; - - #[inline] - fn next(&mut self) -> Option { - let p: *const T = self.0.next()?; - // SAFETY: The iterator was already advanced, so we won't drop this later. - Some(unsafe { p.read() }) - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let n = self.len(); - (n, Some(n)) - } -} - -impl ExactSizeIterator for Drain<'_, T> { - #[inline] - fn len(&self) -> usize { - self.0.len() - } -} - -// SAFETY: This is a 1:1 wrapper for a slice iterator, which is also `TrustedLen`. -unsafe impl TrustedLen for Drain<'_, T> {} - -impl UncheckedIterator for Drain<'_, T> { - unsafe fn next_unchecked(&mut self) -> T { - // SAFETY: `Drain` is 1:1 with the inner iterator, so if the caller promised - // that there's an element left, the inner iterator has one too. - let p: *const T = unsafe { self.0.next_unchecked() }; - // SAFETY: The iterator was already advanced, so we won't drop this later. - unsafe { p.read() } - } -} diff --git a/library/core/src/array/equality.rs b/library/core/src/array/equality.rs deleted file mode 100644 index bb668d2a67309..0000000000000 --- a/library/core/src/array/equality.rs +++ /dev/null @@ -1,155 +0,0 @@ -use crate::cmp::BytewiseEq; - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq<[U; N]> for [T; N] -where - T: PartialEq, -{ - #[inline] - fn eq(&self, other: &[U; N]) -> bool { - SpecArrayEq::spec_eq(self, other) - } - #[inline] - fn ne(&self, other: &[U; N]) -> bool { - SpecArrayEq::spec_ne(self, other) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq<[U]> for [T; N] -where - T: PartialEq, -{ - #[inline] - fn eq(&self, other: &[U]) -> bool { - let b: Result<&[U; N], _> = other.try_into(); - match b { - Ok(b) => *self == *b, - Err(_) => false, - } - } - #[inline] - fn ne(&self, other: &[U]) -> bool { - let b: Result<&[U; N], _> = other.try_into(); - match b { - Ok(b) => *self != *b, - Err(_) => true, - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq<[U; N]> for [T] -where - T: PartialEq, -{ - #[inline] - fn eq(&self, other: &[U; N]) -> bool { - let b: Result<&[T; N], _> = self.try_into(); - match b { - Ok(b) => *b == *other, - Err(_) => false, - } - } - #[inline] - fn ne(&self, other: &[U; N]) -> bool { - let b: Result<&[T; N], _> = self.try_into(); - match b { - Ok(b) => *b != *other, - Err(_) => true, - } - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq<&[U]> for [T; N] -where - T: PartialEq, -{ - #[inline] - fn eq(&self, other: &&[U]) -> bool { - *self == **other - } - #[inline] - fn ne(&self, other: &&[U]) -> bool { - *self != **other - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq<[U; N]> for &[T] -where - T: PartialEq, -{ - #[inline] - fn eq(&self, other: &[U; N]) -> bool { - **self == *other - } - #[inline] - fn ne(&self, other: &[U; N]) -> bool { - **self != *other - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq<&mut [U]> for [T; N] -where - T: PartialEq, -{ - #[inline] - fn eq(&self, other: &&mut [U]) -> bool { - *self == **other - } - #[inline] - fn ne(&self, other: &&mut [U]) -> bool { - *self != **other - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialEq<[U; N]> for &mut [T] -where - T: PartialEq, -{ - #[inline] - fn eq(&self, other: &[U; N]) -> bool { - **self == *other - } - #[inline] - fn ne(&self, other: &[U; N]) -> bool { - **self != *other - } -} - -// NOTE: some less important impls are omitted to reduce code bloat -// __impl_slice_eq2! { [A; $N], &'b [B; $N] } -// __impl_slice_eq2! { [A; $N], &'b mut [B; $N] } - -#[stable(feature = "rust1", since = "1.0.0")] -impl Eq for [T; N] {} - -trait SpecArrayEq: Sized { - fn spec_eq(a: &[Self; N], b: &[Other; N]) -> bool; - fn spec_ne(a: &[Self; N], b: &[Other; N]) -> bool; -} - -impl, Other, const N: usize> SpecArrayEq for T { - default fn spec_eq(a: &[Self; N], b: &[Other; N]) -> bool { - a[..] == b[..] - } - default fn spec_ne(a: &[Self; N], b: &[Other; N]) -> bool { - a[..] != b[..] - } -} - -impl, U, const N: usize> SpecArrayEq for T { - fn spec_eq(a: &[T; N], b: &[U; N]) -> bool { - // SAFETY: Arrays are compared element-wise, and don't add any padding - // between elements, so when the elements are `BytewiseEq`, we can - // compare the entire array at once. - unsafe { crate::intrinsics::raw_eq(a, crate::mem::transmute(b)) } - } - fn spec_ne(a: &[T; N], b: &[U; N]) -> bool { - !Self::spec_eq(a, b) - } -} diff --git a/library/core/src/array/iter.rs b/library/core/src/array/iter.rs deleted file mode 100644 index b314d0536a35a..0000000000000 --- a/library/core/src/array/iter.rs +++ /dev/null @@ -1,430 +0,0 @@ -//! Defines the `IntoIter` owned iterator for arrays. - -use crate::num::NonZero; -use crate::{ - fmt, - intrinsics::transmute_unchecked, - iter::{self, FusedIterator, TrustedLen, TrustedRandomAccessNoCoerce}, - mem::MaybeUninit, - ops::{IndexRange, Range}, - ptr, -}; - -/// A by-value [array] iterator. -#[stable(feature = "array_value_iter", since = "1.51.0")] -#[rustc_insignificant_dtor] -#[rustc_diagnostic_item = "ArrayIntoIter"] -pub struct IntoIter { - /// This is the array we are iterating over. - /// - /// Elements with index `i` where `alive.start <= i < alive.end` have not - /// been yielded yet and are valid array entries. Elements with indices `i - /// < alive.start` or `i >= alive.end` have been yielded already and must - /// not be accessed anymore! Those dead elements might even be in a - /// completely uninitialized state! - /// - /// So the invariants are: - /// - `data[alive]` is alive (i.e. contains valid elements) - /// - `data[..alive.start]` and `data[alive.end..]` are dead (i.e. the - /// elements were already read and must not be touched anymore!) - data: [MaybeUninit; N], - - /// The elements in `data` that have not been yielded yet. - /// - /// Invariants: - /// - `alive.end <= N` - /// - /// (And the `IndexRange` type requires `alive.start <= alive.end`.) - alive: IndexRange, -} - -// Note: the `#[rustc_skip_during_method_dispatch(array)]` on `trait IntoIterator` -// hides this implementation from explicit `.into_iter()` calls on editions < 2021, -// so those calls will still resolve to the slice implementation, by reference. -#[stable(feature = "array_into_iter_impl", since = "1.53.0")] -impl IntoIterator for [T; N] { - type Item = T; - type IntoIter = IntoIter; - - /// Creates a consuming iterator, that is, one that moves each value out of - /// the array (from start to end). The array cannot be used after calling - /// this unless `T` implements `Copy`, so the whole array is copied. - /// - /// Arrays have special behavior when calling `.into_iter()` prior to the - /// 2021 edition -- see the [array] Editions section for more information. - /// - /// [array]: prim@array - fn into_iter(self) -> Self::IntoIter { - // SAFETY: The transmute here is actually safe. The docs of `MaybeUninit` - // promise: - // - // > `MaybeUninit` is guaranteed to have the same size and alignment - // > as `T`. - // - // The docs even show a transmute from an array of `MaybeUninit` to - // an array of `T`. - // - // With that, this initialization satisfies the invariants. - // - // FIXME: If normal `transmute` ever gets smart enough to allow this - // directly, use it instead of `transmute_unchecked`. - let data: [MaybeUninit; N] = unsafe { transmute_unchecked(self) }; - IntoIter { data, alive: IndexRange::zero_to(N) } - } -} - -impl IntoIter { - /// Creates a new iterator over the given `array`. - #[stable(feature = "array_value_iter", since = "1.51.0")] - #[deprecated(since = "1.59.0", note = "use `IntoIterator::into_iter` instead")] - pub fn new(array: [T; N]) -> Self { - IntoIterator::into_iter(array) - } - - /// Creates an iterator over the elements in a partially-initialized buffer. - /// - /// If you have a fully-initialized array, then use [`IntoIterator`]. - /// But this is useful for returning partial results from unsafe code. - /// - /// # Safety - /// - /// - The `buffer[initialized]` elements must all be initialized. - /// - The range must be canonical, with `initialized.start <= initialized.end`. - /// - The range must be in-bounds for the buffer, with `initialized.end <= N`. - /// (Like how indexing `[0][100..100]` fails despite the range being empty.) - /// - /// It's sound to have more elements initialized than mentioned, though that - /// will most likely result in them being leaked. - /// - /// # Examples - /// - /// ``` - /// #![feature(array_into_iter_constructors)] - /// #![feature(maybe_uninit_uninit_array_transpose)] - /// #![feature(maybe_uninit_uninit_array)] - /// use std::array::IntoIter; - /// use std::mem::MaybeUninit; - /// - /// # // Hi! Thanks for reading the code. This is restricted to `Copy` because - /// # // otherwise it could leak. A fully-general version this would need a drop - /// # // guard to handle panics from the iterator, but this works for an example. - /// fn next_chunk( - /// it: &mut impl Iterator, - /// ) -> Result<[T; N], IntoIter> { - /// let mut buffer = MaybeUninit::uninit_array(); - /// let mut i = 0; - /// while i < N { - /// match it.next() { - /// Some(x) => { - /// buffer[i].write(x); - /// i += 1; - /// } - /// None => { - /// // SAFETY: We've initialized the first `i` items - /// unsafe { - /// return Err(IntoIter::new_unchecked(buffer, 0..i)); - /// } - /// } - /// } - /// } - /// - /// // SAFETY: We've initialized all N items - /// unsafe { Ok(buffer.transpose().assume_init()) } - /// } - /// - /// let r: [_; 4] = next_chunk(&mut (10..16)).unwrap(); - /// assert_eq!(r, [10, 11, 12, 13]); - /// let r: IntoIter<_, 40> = next_chunk(&mut (10..16)).unwrap_err(); - /// assert_eq!(r.collect::>(), vec![10, 11, 12, 13, 14, 15]); - /// ``` - #[unstable(feature = "array_into_iter_constructors", issue = "91583")] - #[rustc_const_unstable(feature = "const_array_into_iter_constructors", issue = "91583")] - pub const unsafe fn new_unchecked( - buffer: [MaybeUninit; N], - initialized: Range, - ) -> Self { - // SAFETY: one of our safety conditions is that the range is canonical. - let alive = unsafe { IndexRange::new_unchecked(initialized.start, initialized.end) }; - Self { data: buffer, alive } - } - - /// Creates an iterator over `T` which returns no elements. - /// - /// If you just need an empty iterator, then use - /// [`iter::empty()`](crate::iter::empty) instead. - /// And if you need an empty array, use `[]`. - /// - /// But this is useful when you need an `array::IntoIter` *specifically*. - /// - /// # Examples - /// - /// ``` - /// #![feature(array_into_iter_constructors)] - /// use std::array::IntoIter; - /// - /// let empty = IntoIter::::empty(); - /// assert_eq!(empty.len(), 0); - /// assert_eq!(empty.as_slice(), &[]); - /// - /// let empty = IntoIter::::empty(); - /// assert_eq!(empty.len(), 0); - /// ``` - /// - /// `[1, 2].into_iter()` and `[].into_iter()` have different types - /// ```should_fail,edition2021 - /// #![feature(array_into_iter_constructors)] - /// use std::array::IntoIter; - /// - /// pub fn get_bytes(b: bool) -> IntoIter { - /// if b { - /// [1, 2, 3, 4].into_iter() - /// } else { - /// [].into_iter() // error[E0308]: mismatched types - /// } - /// } - /// ``` - /// - /// But using this method you can get an empty iterator of appropriate size: - /// ```edition2021 - /// #![feature(array_into_iter_constructors)] - /// use std::array::IntoIter; - /// - /// pub fn get_bytes(b: bool) -> IntoIter { - /// if b { - /// [1, 2, 3, 4].into_iter() - /// } else { - /// IntoIter::empty() - /// } - /// } - /// - /// assert_eq!(get_bytes(true).collect::>(), vec![1, 2, 3, 4]); - /// assert_eq!(get_bytes(false).collect::>(), vec![]); - /// ``` - #[unstable(feature = "array_into_iter_constructors", issue = "91583")] - #[rustc_const_unstable(feature = "const_array_into_iter_constructors", issue = "91583")] - pub const fn empty() -> Self { - let buffer = MaybeUninit::uninit_array(); - let initialized = 0..0; - - // SAFETY: We're telling it that none of the elements are initialized, - // which is trivially true. And ∀N: usize, 0 <= N. - unsafe { Self::new_unchecked(buffer, initialized) } - } - - /// Returns an immutable slice of all elements that have not been yielded - /// yet. - #[stable(feature = "array_value_iter", since = "1.51.0")] - pub fn as_slice(&self) -> &[T] { - // SAFETY: We know that all elements within `alive` are properly initialized. - unsafe { - let slice = self.data.get_unchecked(self.alive.clone()); - MaybeUninit::slice_assume_init_ref(slice) - } - } - - /// Returns a mutable slice of all elements that have not been yielded yet. - #[stable(feature = "array_value_iter", since = "1.51.0")] - pub fn as_mut_slice(&mut self) -> &mut [T] { - // SAFETY: We know that all elements within `alive` are properly initialized. - unsafe { - let slice = self.data.get_unchecked_mut(self.alive.clone()); - MaybeUninit::slice_assume_init_mut(slice) - } - } -} - -#[stable(feature = "array_value_iter_impls", since = "1.40.0")] -impl Iterator for IntoIter { - type Item = T; - fn next(&mut self) -> Option { - // Get the next index from the front. - // - // Increasing `alive.start` by 1 maintains the invariant regarding - // `alive`. However, due to this change, for a short time, the alive - // zone is not `data[alive]` anymore, but `data[idx..alive.end]`. - self.alive.next().map(|idx| { - // Read the element from the array. - // SAFETY: `idx` is an index into the former "alive" region of the - // array. Reading this element means that `data[idx]` is regarded as - // dead now (i.e. do not touch). As `idx` was the start of the - // alive-zone, the alive zone is now `data[alive]` again, restoring - // all invariants. - unsafe { self.data.get_unchecked(idx).assume_init_read() } - }) - } - - fn size_hint(&self) -> (usize, Option) { - let len = self.len(); - (len, Some(len)) - } - - #[inline] - fn fold(mut self, init: Acc, mut fold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - let data = &mut self.data; - iter::ByRefSized(&mut self.alive).fold(init, |acc, idx| { - // SAFETY: idx is obtained by folding over the `alive` range, which implies the - // value is currently considered alive but as the range is being consumed each value - // we read here will only be read once and then considered dead. - fold(acc, unsafe { data.get_unchecked(idx).assume_init_read() }) - }) - } - - fn count(self) -> usize { - self.len() - } - - fn last(mut self) -> Option { - self.next_back() - } - - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - // This also moves the start, which marks them as conceptually "dropped", - // so if anything goes bad then our drop impl won't double-free them. - let range_to_drop = self.alive.take_prefix(n); - let remaining = n - range_to_drop.len(); - - // SAFETY: These elements are currently initialized, so it's fine to drop them. - unsafe { - let slice = self.data.get_unchecked_mut(range_to_drop); - ptr::drop_in_place(MaybeUninit::slice_assume_init_mut(slice)); - } - - NonZero::new(remaining).map_or(Ok(()), Err) - } - - #[inline] - unsafe fn __iterator_get_unchecked(&mut self, idx: usize) -> Self::Item { - // SAFETY: The caller must provide an idx that is in bound of the remainder. - unsafe { self.data.as_ptr().add(self.alive.start()).add(idx).cast::().read() } - } -} - -#[stable(feature = "array_value_iter_impls", since = "1.40.0")] -impl DoubleEndedIterator for IntoIter { - fn next_back(&mut self) -> Option { - // Get the next index from the back. - // - // Decreasing `alive.end` by 1 maintains the invariant regarding - // `alive`. However, due to this change, for a short time, the alive - // zone is not `data[alive]` anymore, but `data[alive.start..=idx]`. - self.alive.next_back().map(|idx| { - // Read the element from the array. - // SAFETY: `idx` is an index into the former "alive" region of the - // array. Reading this element means that `data[idx]` is regarded as - // dead now (i.e. do not touch). As `idx` was the end of the - // alive-zone, the alive zone is now `data[alive]` again, restoring - // all invariants. - unsafe { self.data.get_unchecked(idx).assume_init_read() } - }) - } - - #[inline] - fn rfold(mut self, init: Acc, mut rfold: Fold) -> Acc - where - Fold: FnMut(Acc, Self::Item) -> Acc, - { - let data = &mut self.data; - iter::ByRefSized(&mut self.alive).rfold(init, |acc, idx| { - // SAFETY: idx is obtained by folding over the `alive` range, which implies the - // value is currently considered alive but as the range is being consumed each value - // we read here will only be read once and then considered dead. - rfold(acc, unsafe { data.get_unchecked(idx).assume_init_read() }) - }) - } - - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - // This also moves the end, which marks them as conceptually "dropped", - // so if anything goes bad then our drop impl won't double-free them. - let range_to_drop = self.alive.take_suffix(n); - let remaining = n - range_to_drop.len(); - - // SAFETY: These elements are currently initialized, so it's fine to drop them. - unsafe { - let slice = self.data.get_unchecked_mut(range_to_drop); - ptr::drop_in_place(MaybeUninit::slice_assume_init_mut(slice)); - } - - NonZero::new(remaining).map_or(Ok(()), Err) - } -} - -#[stable(feature = "array_value_iter_impls", since = "1.40.0")] -impl Drop for IntoIter { - fn drop(&mut self) { - // SAFETY: This is safe: `as_mut_slice` returns exactly the sub-slice - // of elements that have not been moved out yet and that remain - // to be dropped. - unsafe { ptr::drop_in_place(self.as_mut_slice()) } - } -} - -#[stable(feature = "array_value_iter_impls", since = "1.40.0")] -impl ExactSizeIterator for IntoIter { - fn len(&self) -> usize { - self.alive.len() - } - fn is_empty(&self) -> bool { - self.alive.is_empty() - } -} - -#[stable(feature = "array_value_iter_impls", since = "1.40.0")] -impl FusedIterator for IntoIter {} - -// The iterator indeed reports the correct length. The number of "alive" -// elements (that will still be yielded) is the length of the range `alive`. -// This range is decremented in length in either `next` or `next_back`. It is -// always decremented by 1 in those methods, but only if `Some(_)` is returned. -#[stable(feature = "array_value_iter_impls", since = "1.40.0")] -unsafe impl TrustedLen for IntoIter {} - -#[doc(hidden)] -#[unstable(issue = "none", feature = "std_internals")] -#[rustc_unsafe_specialization_marker] -pub trait NonDrop {} - -// T: Copy as approximation for !Drop since get_unchecked does not advance self.alive -// and thus we can't implement drop-handling -#[unstable(issue = "none", feature = "std_internals")] -impl NonDrop for T {} - -#[doc(hidden)] -#[unstable(issue = "none", feature = "std_internals")] -unsafe impl TrustedRandomAccessNoCoerce for IntoIter -where - T: NonDrop, -{ - const MAY_HAVE_SIDE_EFFECT: bool = false; -} - -#[stable(feature = "array_value_iter_impls", since = "1.40.0")] -impl Clone for IntoIter { - fn clone(&self) -> Self { - // Note, we don't really need to match the exact same alive range, so - // we can just clone into offset 0 regardless of where `self` is. - let mut new = Self { data: MaybeUninit::uninit_array(), alive: IndexRange::zero_to(0) }; - - // Clone all alive elements. - for (src, dst) in iter::zip(self.as_slice(), &mut new.data) { - // Write a clone into the new array, then update its alive range. - // If cloning panics, we'll correctly drop the previous items. - dst.write(src.clone()); - // This addition cannot overflow as we're iterating a slice - new.alive = IndexRange::zero_to(new.alive.end() + 1); - } - - new - } -} - -#[stable(feature = "array_value_iter_impls", since = "1.40.0")] -impl fmt::Debug for IntoIter { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - // Only print the elements that were not yielded yet: we cannot - // access the yielded elements anymore. - f.debug_tuple("IntoIter").field(&self.as_slice()).finish() - } -} diff --git a/library/core/src/array/mod.rs b/library/core/src/array/mod.rs deleted file mode 100644 index 05874ab6c4cbb..0000000000000 --- a/library/core/src/array/mod.rs +++ /dev/null @@ -1,936 +0,0 @@ -//! Utilities for the array primitive type. -//! -//! *[See also the array primitive type](array).* - -#![stable(feature = "core_array", since = "1.36.0")] - -use crate::borrow::{Borrow, BorrowMut}; -use crate::cmp::Ordering; -use crate::convert::Infallible; -use crate::error::Error; -use crate::fmt; -use crate::hash::{self, Hash}; -use crate::iter::UncheckedIterator; -use crate::mem::{self, MaybeUninit}; -use crate::ops::{ - ChangeOutputType, ControlFlow, FromResidual, Index, IndexMut, NeverShortCircuit, Residual, Try, -}; -use crate::slice::{Iter, IterMut}; - -mod ascii; -mod drain; -mod equality; -mod iter; - -pub(crate) use drain::drain_array_with; - -#[stable(feature = "array_value_iter", since = "1.51.0")] -pub use iter::IntoIter; - -/// Creates an array of type [T; N], where each element `T` is the returned value from `cb` -/// using that element's index. -/// -/// # Arguments -/// -/// * `cb`: Callback where the passed argument is the current array index. -/// -/// # Example -/// -/// ```rust -/// // type inference is helping us here, the way `from_fn` knows how many -/// // elements to produce is the length of array down there: only arrays of -/// // equal lengths can be compared, so the const generic parameter `N` is -/// // inferred to be 5, thus creating array of 5 elements. -/// -/// let array = core::array::from_fn(|i| i); -/// // indexes are: 0 1 2 3 4 -/// assert_eq!(array, [0, 1, 2, 3, 4]); -/// -/// let array2: [usize; 8] = core::array::from_fn(|i| i * 2); -/// // indexes are: 0 1 2 3 4 5 6 7 -/// assert_eq!(array2, [0, 2, 4, 6, 8, 10, 12, 14]); -/// -/// let bool_arr = core::array::from_fn::<_, 5, _>(|i| i % 2 == 0); -/// // indexes are: 0 1 2 3 4 -/// assert_eq!(bool_arr, [true, false, true, false, true]); -/// ``` -#[inline] -#[stable(feature = "array_from_fn", since = "1.63.0")] -pub fn from_fn(cb: F) -> [T; N] -where - F: FnMut(usize) -> T, -{ - try_from_fn(NeverShortCircuit::wrap_mut_1(cb)).0 -} - -/// Creates an array `[T; N]` where each fallible array element `T` is returned by the `cb` call. -/// Unlike [`from_fn`], where the element creation can't fail, this version will return an error -/// if any element creation was unsuccessful. -/// -/// The return type of this function depends on the return type of the closure. -/// If you return `Result` from the closure, you'll get a `Result<[T; N], E>`. -/// If you return `Option` from the closure, you'll get an `Option<[T; N]>`. -/// -/// # Arguments -/// -/// * `cb`: Callback where the passed argument is the current array index. -/// -/// # Example -/// -/// ```rust -/// #![feature(array_try_from_fn)] -/// -/// let array: Result<[u8; 5], _> = std::array::try_from_fn(|i| i.try_into()); -/// assert_eq!(array, Ok([0, 1, 2, 3, 4])); -/// -/// let array: Result<[i8; 200], _> = std::array::try_from_fn(|i| i.try_into()); -/// assert!(array.is_err()); -/// -/// let array: Option<[_; 4]> = std::array::try_from_fn(|i| i.checked_add(100)); -/// assert_eq!(array, Some([100, 101, 102, 103])); -/// -/// let array: Option<[_; 4]> = std::array::try_from_fn(|i| i.checked_sub(100)); -/// assert_eq!(array, None); -/// ``` -#[inline] -#[unstable(feature = "array_try_from_fn", issue = "89379")] -pub fn try_from_fn(cb: F) -> ChangeOutputType -where - F: FnMut(usize) -> R, - R: Try, - R::Residual: Residual<[R::Output; N]>, -{ - let mut array = MaybeUninit::uninit_array::(); - match try_from_fn_erased(&mut array, cb) { - ControlFlow::Break(r) => FromResidual::from_residual(r), - ControlFlow::Continue(()) => { - // SAFETY: All elements of the array were populated. - try { unsafe { MaybeUninit::array_assume_init(array) } } - } - } -} - -/// Converts a reference to `T` into a reference to an array of length 1 (without copying). -#[stable(feature = "array_from_ref", since = "1.53.0")] -#[rustc_const_stable(feature = "const_array_from_ref_shared", since = "1.63.0")] -pub const fn from_ref(s: &T) -> &[T; 1] { - // SAFETY: Converting `&T` to `&[T; 1]` is sound. - unsafe { &*(s as *const T).cast::<[T; 1]>() } -} - -/// Converts a mutable reference to `T` into a mutable reference to an array of length 1 (without copying). -#[stable(feature = "array_from_ref", since = "1.53.0")] -#[rustc_const_unstable(feature = "const_array_from_ref", issue = "90206")] -pub const fn from_mut(s: &mut T) -> &mut [T; 1] { - // SAFETY: Converting `&mut T` to `&mut [T; 1]` is sound. - unsafe { &mut *(s as *mut T).cast::<[T; 1]>() } -} - -/// The error type returned when a conversion from a slice to an array fails. -#[stable(feature = "try_from", since = "1.34.0")] -#[derive(Debug, Copy, Clone)] -pub struct TryFromSliceError(()); - -#[stable(feature = "core_array", since = "1.36.0")] -impl fmt::Display for TryFromSliceError { - #[inline] - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - #[allow(deprecated)] - self.description().fmt(f) - } -} - -#[stable(feature = "try_from", since = "1.34.0")] -impl Error for TryFromSliceError { - #[allow(deprecated)] - fn description(&self) -> &str { - "could not convert slice to array" - } -} - -#[stable(feature = "try_from_slice_error", since = "1.36.0")] -impl From for TryFromSliceError { - fn from(x: Infallible) -> TryFromSliceError { - match x {} - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsRef<[T]> for [T; N] { - #[inline] - fn as_ref(&self) -> &[T] { - &self[..] - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl AsMut<[T]> for [T; N] { - #[inline] - fn as_mut(&mut self) -> &mut [T] { - &mut self[..] - } -} - -#[stable(feature = "array_borrow", since = "1.4.0")] -impl Borrow<[T]> for [T; N] { - fn borrow(&self) -> &[T] { - self - } -} - -#[stable(feature = "array_borrow", since = "1.4.0")] -impl BorrowMut<[T]> for [T; N] { - fn borrow_mut(&mut self) -> &mut [T] { - self - } -} - -/// Tries to create an array `[T; N]` by copying from a slice `&[T]`. Succeeds if -/// `slice.len() == N`. -/// -/// ``` -/// let bytes: [u8; 3] = [1, 0, 2]; -/// -/// let bytes_head: [u8; 2] = <[u8; 2]>::try_from(&bytes[0..2]).unwrap(); -/// assert_eq!(1, u16::from_le_bytes(bytes_head)); -/// -/// let bytes_tail: [u8; 2] = bytes[1..3].try_into().unwrap(); -/// assert_eq!(512, u16::from_le_bytes(bytes_tail)); -/// ``` -#[stable(feature = "try_from", since = "1.34.0")] -impl TryFrom<&[T]> for [T; N] -where - T: Copy, -{ - type Error = TryFromSliceError; - - #[inline] - fn try_from(slice: &[T]) -> Result<[T; N], TryFromSliceError> { - <&Self>::try_from(slice).copied() - } -} - -/// Tries to create an array `[T; N]` by copying from a mutable slice `&mut [T]`. -/// Succeeds if `slice.len() == N`. -/// -/// ``` -/// let mut bytes: [u8; 3] = [1, 0, 2]; -/// -/// let bytes_head: [u8; 2] = <[u8; 2]>::try_from(&mut bytes[0..2]).unwrap(); -/// assert_eq!(1, u16::from_le_bytes(bytes_head)); -/// -/// let bytes_tail: [u8; 2] = (&mut bytes[1..3]).try_into().unwrap(); -/// assert_eq!(512, u16::from_le_bytes(bytes_tail)); -/// ``` -#[stable(feature = "try_from_mut_slice_to_array", since = "1.59.0")] -impl TryFrom<&mut [T]> for [T; N] -where - T: Copy, -{ - type Error = TryFromSliceError; - - #[inline] - fn try_from(slice: &mut [T]) -> Result<[T; N], TryFromSliceError> { - ::try_from(&*slice) - } -} - -/// Tries to create an array ref `&[T; N]` from a slice ref `&[T]`. Succeeds if -/// `slice.len() == N`. -/// -/// ``` -/// let bytes: [u8; 3] = [1, 0, 2]; -/// -/// let bytes_head: &[u8; 2] = <&[u8; 2]>::try_from(&bytes[0..2]).unwrap(); -/// assert_eq!(1, u16::from_le_bytes(*bytes_head)); -/// -/// let bytes_tail: &[u8; 2] = bytes[1..3].try_into().unwrap(); -/// assert_eq!(512, u16::from_le_bytes(*bytes_tail)); -/// ``` -#[stable(feature = "try_from", since = "1.34.0")] -impl<'a, T, const N: usize> TryFrom<&'a [T]> for &'a [T; N] { - type Error = TryFromSliceError; - - #[inline] - fn try_from(slice: &'a [T]) -> Result<&'a [T; N], TryFromSliceError> { - if slice.len() == N { - let ptr = slice.as_ptr() as *const [T; N]; - // SAFETY: ok because we just checked that the length fits - unsafe { Ok(&*ptr) } - } else { - Err(TryFromSliceError(())) - } - } -} - -/// Tries to create a mutable array ref `&mut [T; N]` from a mutable slice ref -/// `&mut [T]`. Succeeds if `slice.len() == N`. -/// -/// ``` -/// let mut bytes: [u8; 3] = [1, 0, 2]; -/// -/// let bytes_head: &mut [u8; 2] = <&mut [u8; 2]>::try_from(&mut bytes[0..2]).unwrap(); -/// assert_eq!(1, u16::from_le_bytes(*bytes_head)); -/// -/// let bytes_tail: &mut [u8; 2] = (&mut bytes[1..3]).try_into().unwrap(); -/// assert_eq!(512, u16::from_le_bytes(*bytes_tail)); -/// ``` -#[stable(feature = "try_from", since = "1.34.0")] -impl<'a, T, const N: usize> TryFrom<&'a mut [T]> for &'a mut [T; N] { - type Error = TryFromSliceError; - - #[inline] - fn try_from(slice: &'a mut [T]) -> Result<&'a mut [T; N], TryFromSliceError> { - if slice.len() == N { - let ptr = slice.as_mut_ptr() as *mut [T; N]; - // SAFETY: ok because we just checked that the length fits - unsafe { Ok(&mut *ptr) } - } else { - Err(TryFromSliceError(())) - } - } -} - -/// The hash of an array is the same as that of the corresponding slice, -/// as required by the `Borrow` implementation. -/// -/// ``` -/// use std::hash::BuildHasher; -/// -/// let b = std::hash::RandomState::new(); -/// let a: [u8; 3] = [0xa8, 0x3c, 0x09]; -/// let s: &[u8] = &[0xa8, 0x3c, 0x09]; -/// assert_eq!(b.hash_one(a), b.hash_one(s)); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -impl Hash for [T; N] { - fn hash(&self, state: &mut H) { - Hash::hash(&self[..], state) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl fmt::Debug for [T; N] { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - fmt::Debug::fmt(&&self[..], f) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T, const N: usize> IntoIterator for &'a [T; N] { - type Item = &'a T; - type IntoIter = Iter<'a, T>; - - fn into_iter(self) -> Iter<'a, T> { - self.iter() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl<'a, T, const N: usize> IntoIterator for &'a mut [T; N] { - type Item = &'a mut T; - type IntoIter = IterMut<'a, T>; - - fn into_iter(self) -> IterMut<'a, T> { - self.iter_mut() - } -} - -#[stable(feature = "index_trait_on_arrays", since = "1.50.0")] -impl Index for [T; N] -where - [T]: Index, -{ - type Output = <[T] as Index>::Output; - - #[inline] - fn index(&self, index: I) -> &Self::Output { - Index::index(self as &[T], index) - } -} - -#[stable(feature = "index_trait_on_arrays", since = "1.50.0")] -impl IndexMut for [T; N] -where - [T]: IndexMut, -{ - #[inline] - fn index_mut(&mut self, index: I) -> &mut Self::Output { - IndexMut::index_mut(self as &mut [T], index) - } -} - -/// Implements comparison of arrays [lexicographically](Ord#lexicographical-comparison). -#[stable(feature = "rust1", since = "1.0.0")] -impl PartialOrd for [T; N] { - #[inline] - fn partial_cmp(&self, other: &[T; N]) -> Option { - PartialOrd::partial_cmp(&&self[..], &&other[..]) - } - #[inline] - fn lt(&self, other: &[T; N]) -> bool { - PartialOrd::lt(&&self[..], &&other[..]) - } - #[inline] - fn le(&self, other: &[T; N]) -> bool { - PartialOrd::le(&&self[..], &&other[..]) - } - #[inline] - fn ge(&self, other: &[T; N]) -> bool { - PartialOrd::ge(&&self[..], &&other[..]) - } - #[inline] - fn gt(&self, other: &[T; N]) -> bool { - PartialOrd::gt(&&self[..], &&other[..]) - } -} - -/// Implements comparison of arrays [lexicographically](Ord#lexicographical-comparison). -#[stable(feature = "rust1", since = "1.0.0")] -impl Ord for [T; N] { - #[inline] - fn cmp(&self, other: &[T; N]) -> Ordering { - Ord::cmp(&&self[..], &&other[..]) - } -} - -#[stable(feature = "copy_clone_array_lib", since = "1.58.0")] -impl Copy for [T; N] {} - -#[stable(feature = "copy_clone_array_lib", since = "1.58.0")] -impl Clone for [T; N] { - #[inline] - fn clone(&self) -> Self { - SpecArrayClone::clone(self) - } - - #[inline] - fn clone_from(&mut self, other: &Self) { - self.clone_from_slice(other); - } -} - -trait SpecArrayClone: Clone { - fn clone(array: &[Self; N]) -> [Self; N]; -} - -impl SpecArrayClone for T { - #[inline] - default fn clone(array: &[T; N]) -> [T; N] { - from_trusted_iterator(array.iter().cloned()) - } -} - -impl SpecArrayClone for T { - #[inline] - fn clone(array: &[T; N]) -> [T; N] { - *array - } -} - -// The Default impls cannot be done with const generics because `[T; 0]` doesn't -// require Default to be implemented, and having different impl blocks for -// different numbers isn't supported yet. - -macro_rules! array_impl_default { - {$n:expr, $t:ident $($ts:ident)*} => { - #[stable(since = "1.4.0", feature = "array_default")] - impl Default for [T; $n] where T: Default { - fn default() -> [T; $n] { - [$t::default(), $($ts::default()),*] - } - } - array_impl_default!{($n - 1), $($ts)*} - }; - {$n:expr,} => { - #[stable(since = "1.4.0", feature = "array_default")] - impl Default for [T; $n] { - fn default() -> [T; $n] { [] } - } - }; -} - -array_impl_default! {32, T T T T T T T T T T T T T T T T T T T T T T T T T T T T T T T T} - -impl [T; N] { - /// Returns an array of the same size as `self`, with function `f` applied to each element - /// in order. - /// - /// If you don't necessarily need a new fixed-size array, consider using - /// [`Iterator::map`] instead. - /// - /// - /// # Note on performance and stack usage - /// - /// Unfortunately, usages of this method are currently not always optimized - /// as well as they could be. This mainly concerns large arrays, as mapping - /// over small arrays seem to be optimized just fine. Also note that in - /// debug mode (i.e. without any optimizations), this method can use a lot - /// of stack space (a few times the size of the array or more). - /// - /// Therefore, in performance-critical code, try to avoid using this method - /// on large arrays or check the emitted code. Also try to avoid chained - /// maps (e.g. `arr.map(...).map(...)`). - /// - /// In many cases, you can instead use [`Iterator::map`] by calling `.iter()` - /// or `.into_iter()` on your array. `[T; N]::map` is only necessary if you - /// really need a new array of the same size as the result. Rust's lazy - /// iterators tend to get optimized very well. - /// - /// - /// # Examples - /// - /// ``` - /// let x = [1, 2, 3]; - /// let y = x.map(|v| v + 1); - /// assert_eq!(y, [2, 3, 4]); - /// - /// let x = [1, 2, 3]; - /// let mut temp = 0; - /// let y = x.map(|v| { temp += 1; v * temp }); - /// assert_eq!(y, [1, 4, 9]); - /// - /// let x = ["Ferris", "Bueller's", "Day", "Off"]; - /// let y = x.map(|v| v.len()); - /// assert_eq!(y, [6, 9, 3, 3]); - /// ``` - #[stable(feature = "array_map", since = "1.55.0")] - pub fn map(self, f: F) -> [U; N] - where - F: FnMut(T) -> U, - { - self.try_map(NeverShortCircuit::wrap_mut_1(f)).0 - } - - /// A fallible function `f` applied to each element on array `self` in order to - /// return an array the same size as `self` or the first error encountered. - /// - /// The return type of this function depends on the return type of the closure. - /// If you return `Result` from the closure, you'll get a `Result<[T; N], E>`. - /// If you return `Option` from the closure, you'll get an `Option<[T; N]>`. - /// - /// # Examples - /// - /// ``` - /// #![feature(array_try_map)] - /// - /// let a = ["1", "2", "3"]; - /// let b = a.try_map(|v| v.parse::()).unwrap().map(|v| v + 1); - /// assert_eq!(b, [2, 3, 4]); - /// - /// let a = ["1", "2a", "3"]; - /// let b = a.try_map(|v| v.parse::()); - /// assert!(b.is_err()); - /// - /// use std::num::NonZero; - /// - /// let z = [1, 2, 0, 3, 4]; - /// assert_eq!(z.try_map(NonZero::new), None); - /// - /// let a = [1, 2, 3]; - /// let b = a.try_map(NonZero::new); - /// let c = b.map(|x| x.map(NonZero::get)); - /// assert_eq!(c, Some(a)); - /// ``` - #[unstable(feature = "array_try_map", issue = "79711")] - pub fn try_map(self, f: F) -> ChangeOutputType - where - F: FnMut(T) -> R, - R: Try, - R::Residual: Residual<[R::Output; N]>, - { - drain_array_with(self, |iter| try_from_trusted_iterator(iter.map(f))) - } - - /// Returns a slice containing the entire array. Equivalent to `&s[..]`. - #[stable(feature = "array_as_slice", since = "1.57.0")] - #[rustc_const_stable(feature = "array_as_slice", since = "1.57.0")] - pub const fn as_slice(&self) -> &[T] { - self - } - - /// Returns a mutable slice containing the entire array. Equivalent to - /// `&mut s[..]`. - #[stable(feature = "array_as_slice", since = "1.57.0")] - pub fn as_mut_slice(&mut self) -> &mut [T] { - self - } - - /// Borrows each element and returns an array of references with the same - /// size as `self`. - /// - /// - /// # Example - /// - /// ``` - /// let floats = [3.1, 2.7, -1.0]; - /// let float_refs: [&f64; 3] = floats.each_ref(); - /// assert_eq!(float_refs, [&3.1, &2.7, &-1.0]); - /// ``` - /// - /// This method is particularly useful if combined with other methods, like - /// [`map`](#method.map). This way, you can avoid moving the original - /// array if its elements are not [`Copy`]. - /// - /// ``` - /// let strings = ["Ferris".to_string(), "♥".to_string(), "Rust".to_string()]; - /// let is_ascii = strings.each_ref().map(|s| s.is_ascii()); - /// assert_eq!(is_ascii, [true, false, true]); - /// - /// // We can still access the original array: it has not been moved. - /// assert_eq!(strings.len(), 3); - /// ``` - #[stable(feature = "array_methods", since = "1.77.0")] - pub fn each_ref(&self) -> [&T; N] { - from_trusted_iterator(self.iter()) - } - - /// Borrows each element mutably and returns an array of mutable references - /// with the same size as `self`. - /// - /// - /// # Example - /// - /// ``` - /// - /// let mut floats = [3.1, 2.7, -1.0]; - /// let float_refs: [&mut f64; 3] = floats.each_mut(); - /// *float_refs[0] = 0.0; - /// assert_eq!(float_refs, [&mut 0.0, &mut 2.7, &mut -1.0]); - /// assert_eq!(floats, [0.0, 2.7, -1.0]); - /// ``` - #[stable(feature = "array_methods", since = "1.77.0")] - pub fn each_mut(&mut self) -> [&mut T; N] { - from_trusted_iterator(self.iter_mut()) - } - - /// Divides one array reference into two at an index. - /// - /// The first will contain all indices from `[0, M)` (excluding - /// the index `M` itself) and the second will contain all - /// indices from `[M, N)` (excluding the index `N` itself). - /// - /// # Panics - /// - /// Panics if `M > N`. - /// - /// # Examples - /// - /// ``` - /// #![feature(split_array)] - /// - /// let v = [1, 2, 3, 4, 5, 6]; - /// - /// { - /// let (left, right) = v.split_array_ref::<0>(); - /// assert_eq!(left, &[]); - /// assert_eq!(right, &[1, 2, 3, 4, 5, 6]); - /// } - /// - /// { - /// let (left, right) = v.split_array_ref::<2>(); - /// assert_eq!(left, &[1, 2]); - /// assert_eq!(right, &[3, 4, 5, 6]); - /// } - /// - /// { - /// let (left, right) = v.split_array_ref::<6>(); - /// assert_eq!(left, &[1, 2, 3, 4, 5, 6]); - /// assert_eq!(right, &[]); - /// } - /// ``` - #[unstable( - feature = "split_array", - reason = "return type should have array as 2nd element", - issue = "90091" - )] - #[inline] - pub fn split_array_ref(&self) -> (&[T; M], &[T]) { - (&self[..]).split_first_chunk::().unwrap() - } - - /// Divides one mutable array reference into two at an index. - /// - /// The first will contain all indices from `[0, M)` (excluding - /// the index `M` itself) and the second will contain all - /// indices from `[M, N)` (excluding the index `N` itself). - /// - /// # Panics - /// - /// Panics if `M > N`. - /// - /// # Examples - /// - /// ``` - /// #![feature(split_array)] - /// - /// let mut v = [1, 0, 3, 0, 5, 6]; - /// let (left, right) = v.split_array_mut::<2>(); - /// assert_eq!(left, &mut [1, 0][..]); - /// assert_eq!(right, &mut [3, 0, 5, 6]); - /// left[1] = 2; - /// right[1] = 4; - /// assert_eq!(v, [1, 2, 3, 4, 5, 6]); - /// ``` - #[unstable( - feature = "split_array", - reason = "return type should have array as 2nd element", - issue = "90091" - )] - #[inline] - pub fn split_array_mut(&mut self) -> (&mut [T; M], &mut [T]) { - (&mut self[..]).split_first_chunk_mut::().unwrap() - } - - /// Divides one array reference into two at an index from the end. - /// - /// The first will contain all indices from `[0, N - M)` (excluding - /// the index `N - M` itself) and the second will contain all - /// indices from `[N - M, N)` (excluding the index `N` itself). - /// - /// # Panics - /// - /// Panics if `M > N`. - /// - /// # Examples - /// - /// ``` - /// #![feature(split_array)] - /// - /// let v = [1, 2, 3, 4, 5, 6]; - /// - /// { - /// let (left, right) = v.rsplit_array_ref::<0>(); - /// assert_eq!(left, &[1, 2, 3, 4, 5, 6]); - /// assert_eq!(right, &[]); - /// } - /// - /// { - /// let (left, right) = v.rsplit_array_ref::<2>(); - /// assert_eq!(left, &[1, 2, 3, 4]); - /// assert_eq!(right, &[5, 6]); - /// } - /// - /// { - /// let (left, right) = v.rsplit_array_ref::<6>(); - /// assert_eq!(left, &[]); - /// assert_eq!(right, &[1, 2, 3, 4, 5, 6]); - /// } - /// ``` - #[unstable( - feature = "split_array", - reason = "return type should have array as 2nd element", - issue = "90091" - )] - #[inline] - pub fn rsplit_array_ref(&self) -> (&[T], &[T; M]) { - (&self[..]).split_last_chunk::().unwrap() - } - - /// Divides one mutable array reference into two at an index from the end. - /// - /// The first will contain all indices from `[0, N - M)` (excluding - /// the index `N - M` itself) and the second will contain all - /// indices from `[N - M, N)` (excluding the index `N` itself). - /// - /// # Panics - /// - /// Panics if `M > N`. - /// - /// # Examples - /// - /// ``` - /// #![feature(split_array)] - /// - /// let mut v = [1, 0, 3, 0, 5, 6]; - /// let (left, right) = v.rsplit_array_mut::<4>(); - /// assert_eq!(left, &mut [1, 0]); - /// assert_eq!(right, &mut [3, 0, 5, 6][..]); - /// left[1] = 2; - /// right[1] = 4; - /// assert_eq!(v, [1, 2, 3, 4, 5, 6]); - /// ``` - #[unstable( - feature = "split_array", - reason = "return type should have array as 2nd element", - issue = "90091" - )] - #[inline] - pub fn rsplit_array_mut(&mut self) -> (&mut [T], &mut [T; M]) { - (&mut self[..]).split_last_chunk_mut::().unwrap() - } -} - -/// Populate an array from the first `N` elements of `iter` -/// -/// # Panics -/// -/// If the iterator doesn't actually have enough items. -/// -/// By depending on `TrustedLen`, however, we can do that check up-front (where -/// it easily optimizes away) so it doesn't impact the loop that fills the array. -#[inline] -fn from_trusted_iterator(iter: impl UncheckedIterator) -> [T; N] { - try_from_trusted_iterator(iter.map(NeverShortCircuit)).0 -} - -#[inline] -fn try_from_trusted_iterator( - iter: impl UncheckedIterator, -) -> ChangeOutputType -where - R: Try, - R::Residual: Residual<[T; N]>, -{ - assert!(iter.size_hint().0 >= N); - fn next(mut iter: impl UncheckedIterator) -> impl FnMut(usize) -> T { - move |_| { - // SAFETY: We know that `from_fn` will call this at most N times, - // and we checked to ensure that we have at least that many items. - unsafe { iter.next_unchecked() } - } - } - - try_from_fn(next(iter)) -} - -/// Version of [`try_from_fn`] using a passed-in slice in order to avoid -/// needing to monomorphize for every array length. -/// -/// This takes a generator rather than an iterator so that *at the type level* -/// it never needs to worry about running out of items. When combined with -/// an infallible `Try` type, that means the loop canonicalizes easily, allowing -/// it to optimize well. -/// -/// It would be *possible* to unify this and [`iter_next_chunk_erased`] into one -/// function that does the union of both things, but last time it was that way -/// it resulted in poor codegen from the "are there enough source items?" checks -/// not optimizing away. So if you give it a shot, make sure to watch what -/// happens in the codegen tests. -#[inline] -fn try_from_fn_erased( - buffer: &mut [MaybeUninit], - mut generator: impl FnMut(usize) -> R, -) -> ControlFlow -where - R: Try, -{ - let mut guard = Guard { array_mut: buffer, initialized: 0 }; - - while guard.initialized < guard.array_mut.len() { - let item = generator(guard.initialized).branch()?; - - // SAFETY: The loop condition ensures we have space to push the item - unsafe { guard.push_unchecked(item) }; - } - - mem::forget(guard); - ControlFlow::Continue(()) -} - -/// Panic guard for incremental initialization of arrays. -/// -/// Disarm the guard with `mem::forget` once the array has been initialized. -/// -/// # Safety -/// -/// All write accesses to this structure are unsafe and must maintain a correct -/// count of `initialized` elements. -/// -/// To minimize indirection fields are still pub but callers should at least use -/// `push_unchecked` to signal that something unsafe is going on. -struct Guard<'a, T> { - /// The array to be initialized. - pub array_mut: &'a mut [MaybeUninit], - /// The number of items that have been initialized so far. - pub initialized: usize, -} - -impl Guard<'_, T> { - /// Adds an item to the array and updates the initialized item counter. - /// - /// # Safety - /// - /// No more than N elements must be initialized. - #[inline] - pub unsafe fn push_unchecked(&mut self, item: T) { - // SAFETY: If `initialized` was correct before and the caller does not - // invoke this method more than N times then writes will be in-bounds - // and slots will not be initialized more than once. - unsafe { - self.array_mut.get_unchecked_mut(self.initialized).write(item); - self.initialized = self.initialized.unchecked_add(1); - } - } -} - -impl Drop for Guard<'_, T> { - fn drop(&mut self) { - debug_assert!(self.initialized <= self.array_mut.len()); - - // SAFETY: this slice will contain only initialized objects. - unsafe { - crate::ptr::drop_in_place(MaybeUninit::slice_assume_init_mut( - self.array_mut.get_unchecked_mut(..self.initialized), - )); - } - } -} - -/// Pulls `N` items from `iter` and returns them as an array. If the iterator -/// yields fewer than `N` items, `Err` is returned containing an iterator over -/// the already yielded items. -/// -/// Since the iterator is passed as a mutable reference and this function calls -/// `next` at most `N` times, the iterator can still be used afterwards to -/// retrieve the remaining items. -/// -/// If `iter.next()` panicks, all items already yielded by the iterator are -/// dropped. -/// -/// Used for [`Iterator::next_chunk`]. -#[inline] -pub(crate) fn iter_next_chunk( - iter: &mut impl Iterator, -) -> Result<[T; N], IntoIter> { - let mut array = MaybeUninit::uninit_array::(); - let r = iter_next_chunk_erased(&mut array, iter); - match r { - Ok(()) => { - // SAFETY: All elements of `array` were populated. - Ok(unsafe { MaybeUninit::array_assume_init(array) }) - } - Err(initialized) => { - // SAFETY: Only the first `initialized` elements were populated - Err(unsafe { IntoIter::new_unchecked(array, 0..initialized) }) - } - } -} - -/// Version of [`iter_next_chunk`] using a passed-in slice in order to avoid -/// needing to monomorphize for every array length. -/// -/// Unfortunately this loop has two exit conditions, the buffer filling up -/// or the iterator running out of items, making it tend to optimize poorly. -#[inline] -fn iter_next_chunk_erased( - buffer: &mut [MaybeUninit], - iter: &mut impl Iterator, -) -> Result<(), usize> { - let mut guard = Guard { array_mut: buffer, initialized: 0 }; - while guard.initialized < guard.array_mut.len() { - let Some(item) = iter.next() else { - // Unlike `try_from_fn_erased`, we want to keep the partial results, - // so we need to defuse the guard instead of using `?`. - let initialized = guard.initialized; - mem::forget(guard); - return Err(initialized); - }; - - // SAFETY: The loop condition ensures we have space to push the item - unsafe { guard.push_unchecked(item) }; - } - - mem::forget(guard); - Ok(()) -} diff --git a/library/core/src/ascii.rs b/library/core/src/ascii.rs deleted file mode 100644 index e9f4d0f93ed49..0000000000000 --- a/library/core/src/ascii.rs +++ /dev/null @@ -1,181 +0,0 @@ -//! Operations on ASCII strings and characters. -//! -//! Most string operations in Rust act on UTF-8 strings. However, at times it -//! makes more sense to only consider the ASCII character set for a specific -//! operation. -//! -//! The [`escape_default`] function provides an iterator over the bytes of an -//! escaped version of the character given. - -#![stable(feature = "core_ascii", since = "1.26.0")] - -use crate::escape; -use crate::fmt; -use crate::iter::FusedIterator; -use crate::num::NonZero; - -mod ascii_char; -#[unstable(feature = "ascii_char", issue = "110998")] -pub use ascii_char::AsciiChar as Char; - -/// An iterator over the escaped version of a byte. -/// -/// This `struct` is created by the [`escape_default`] function. See its -/// documentation for more. -#[must_use = "iterators are lazy and do nothing unless consumed"] -#[stable(feature = "rust1", since = "1.0.0")] -#[derive(Clone)] -pub struct EscapeDefault(escape::EscapeIterInner<4>); - -/// Returns an iterator that produces an escaped version of a `u8`. -/// -/// The default is chosen with a bias toward producing literals that are -/// legal in a variety of languages, including C++11 and similar C-family -/// languages. The exact rules are: -/// -/// * Tab is escaped as `\t`. -/// * Carriage return is escaped as `\r`. -/// * Line feed is escaped as `\n`. -/// * Single quote is escaped as `\'`. -/// * Double quote is escaped as `\"`. -/// * Backslash is escaped as `\\`. -/// * Any character in the 'printable ASCII' range `0x20` .. `0x7e` -/// inclusive is not escaped. -/// * Any other chars are given hex escapes of the form '\xNN'. -/// * Unicode escapes are never generated by this function. -/// -/// # Examples -/// -/// ``` -/// use std::ascii; -/// -/// let escaped = ascii::escape_default(b'0').next().unwrap(); -/// assert_eq!(b'0', escaped); -/// -/// let mut escaped = ascii::escape_default(b'\t'); -/// -/// assert_eq!(b'\\', escaped.next().unwrap()); -/// assert_eq!(b't', escaped.next().unwrap()); -/// -/// let mut escaped = ascii::escape_default(b'\r'); -/// -/// assert_eq!(b'\\', escaped.next().unwrap()); -/// assert_eq!(b'r', escaped.next().unwrap()); -/// -/// let mut escaped = ascii::escape_default(b'\n'); -/// -/// assert_eq!(b'\\', escaped.next().unwrap()); -/// assert_eq!(b'n', escaped.next().unwrap()); -/// -/// let mut escaped = ascii::escape_default(b'\''); -/// -/// assert_eq!(b'\\', escaped.next().unwrap()); -/// assert_eq!(b'\'', escaped.next().unwrap()); -/// -/// let mut escaped = ascii::escape_default(b'"'); -/// -/// assert_eq!(b'\\', escaped.next().unwrap()); -/// assert_eq!(b'"', escaped.next().unwrap()); -/// -/// let mut escaped = ascii::escape_default(b'\\'); -/// -/// assert_eq!(b'\\', escaped.next().unwrap()); -/// assert_eq!(b'\\', escaped.next().unwrap()); -/// -/// let mut escaped = ascii::escape_default(b'\x9d'); -/// -/// assert_eq!(b'\\', escaped.next().unwrap()); -/// assert_eq!(b'x', escaped.next().unwrap()); -/// assert_eq!(b'9', escaped.next().unwrap()); -/// assert_eq!(b'd', escaped.next().unwrap()); -/// ``` -#[stable(feature = "rust1", since = "1.0.0")] -pub fn escape_default(c: u8) -> EscapeDefault { - EscapeDefault::new(c) -} - -impl EscapeDefault { - #[inline] - pub(crate) const fn new(c: u8) -> Self { - Self(escape::EscapeIterInner::ascii(c)) - } - - #[inline] - pub(crate) fn empty() -> Self { - Self(escape::EscapeIterInner::empty()) - } - - #[inline] - pub(crate) fn as_str(&self) -> &str { - self.0.as_str() - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl Iterator for EscapeDefault { - type Item = u8; - - #[inline] - fn next(&mut self) -> Option { - self.0.next() - } - - #[inline] - fn size_hint(&self) -> (usize, Option) { - let n = self.0.len(); - (n, Some(n)) - } - - #[inline] - fn count(self) -> usize { - self.0.len() - } - - #[inline] - fn last(mut self) -> Option { - self.0.next_back() - } - - #[inline] - fn advance_by(&mut self, n: usize) -> Result<(), NonZero> { - self.0.advance_by(n) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl DoubleEndedIterator for EscapeDefault { - #[inline] - fn next_back(&mut self) -> Option { - self.0.next_back() - } - - #[inline] - fn advance_back_by(&mut self, n: usize) -> Result<(), NonZero> { - self.0.advance_back_by(n) - } -} - -#[stable(feature = "rust1", since = "1.0.0")] -impl ExactSizeIterator for EscapeDefault { - #[inline] - fn len(&self) -> usize { - self.0.len() - } -} - -#[stable(feature = "fused", since = "1.26.0")] -impl FusedIterator for EscapeDefault {} - -#[stable(feature = "ascii_escape_display", since = "1.39.0")] -impl fmt::Display for EscapeDefault { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.write_str(self.0.as_str()) - } -} - -#[stable(feature = "std_debug", since = "1.16.0")] -impl fmt::Debug for EscapeDefault { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - f.debug_struct("EscapeDefault").finish_non_exhaustive() - } -} diff --git a/library/core/src/ascii/ascii_char.rs b/library/core/src/ascii/ascii_char.rs deleted file mode 100644 index 34a05ac38884d..0000000000000 --- a/library/core/src/ascii/ascii_char.rs +++ /dev/null @@ -1,618 +0,0 @@ -//! This uses the name `AsciiChar`, even though it's not exposed that way right now, -//! because it avoids a whole bunch of "are you sure you didn't mean `char`?" -//! suggestions from rustc if you get anything slightly wrong in here, and overall -//! helps with clarity as we're also referring to `char` intentionally in here. - -use crate::fmt::{self, Write}; -use crate::mem::transmute; - -/// One of the 128 Unicode characters from U+0000 through U+007F, -/// often known as the [ASCII] subset. -/// -/// Officially, this is the first [block] in Unicode, _Basic Latin_. -/// For details, see the [*C0 Controls and Basic Latin*][chart] code chart. -/// -/// This block was based on older 7-bit character code standards such as -/// ANSI X3.4-1977, ISO 646-1973, and [NIST FIPS 1-2]. -/// -/// # When to use this -/// -/// The main advantage of this subset is that it's always valid UTF-8. As such, -/// the `&[ascii::Char]` -> `&str` conversion function (as well as other related -/// ones) are O(1): *no* runtime checks are needed. -/// -/// If you're consuming strings, you should usually handle Unicode and thus -/// accept `str`s, not limit yourself to `ascii::Char`s. -/// -/// However, certain formats are intentionally designed to produce ASCII-only -/// output in order to be 8-bit-clean. In those cases, it can be simpler and -/// faster to generate `ascii::Char`s instead of dealing with the variable width -/// properties of general UTF-8 encoded strings, while still allowing the result -/// to be used freely with other Rust things that deal in general `str`s. -/// -/// For example, a UUID library might offer a way to produce the string -/// representation of a UUID as an `[ascii::Char; 36]` to avoid memory -/// allocation yet still allow it to be used as UTF-8 via `as_str` without -/// paying for validation (or needing `unsafe` code) the way it would if it -/// were provided as a `[u8; 36]`. -/// -/// # Layout -/// -/// This type is guaranteed to have a size and alignment of 1 byte. -/// -/// # Names -/// -/// The variants on this type are [Unicode names][NamesList] of the characters -/// in upper camel case, with a few tweaks: -/// - For `` characters, the primary alias name is used. -/// - `LATIN` is dropped, as this block has no non-latin letters. -/// - `LETTER` is dropped, as `CAPITAL`/`SMALL` suffices in this block. -/// - `DIGIT`s use a single digit rather than writing out `ZERO`, `ONE`, etc. -/// -/// [ASCII]: https://www.unicode.org/glossary/index.html#ASCII -/// [block]: https://www.unicode.org/glossary/index.html#block -/// [chart]: https://www.unicode.org/charts/PDF/U0000.pdf -/// [NIST FIPS 1-2]: https://nvlpubs.nist.gov/nistpubs/Legacy/FIPS/fipspub1-2-1977.pdf -/// [NamesList]: https://www.unicode.org/Public/15.0.0/ucd/NamesList.txt -#[derive(Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash)] -#[unstable(feature = "ascii_char", issue = "110998")] -#[repr(u8)] -pub enum AsciiChar { - /// U+0000 (The default variant) - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Null = 0, - /// U+0001 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - StartOfHeading = 1, - /// U+0002 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - StartOfText = 2, - /// U+0003 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - EndOfText = 3, - /// U+0004 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - EndOfTransmission = 4, - /// U+0005 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Enquiry = 5, - /// U+0006 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Acknowledge = 6, - /// U+0007 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Bell = 7, - /// U+0008 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Backspace = 8, - /// U+0009 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CharacterTabulation = 9, - /// U+000A - #[unstable(feature = "ascii_char_variants", issue = "110998")] - LineFeed = 10, - /// U+000B - #[unstable(feature = "ascii_char_variants", issue = "110998")] - LineTabulation = 11, - /// U+000C - #[unstable(feature = "ascii_char_variants", issue = "110998")] - FormFeed = 12, - /// U+000D - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CarriageReturn = 13, - /// U+000E - #[unstable(feature = "ascii_char_variants", issue = "110998")] - ShiftOut = 14, - /// U+000F - #[unstable(feature = "ascii_char_variants", issue = "110998")] - ShiftIn = 15, - /// U+0010 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - DataLinkEscape = 16, - /// U+0011 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - DeviceControlOne = 17, - /// U+0012 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - DeviceControlTwo = 18, - /// U+0013 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - DeviceControlThree = 19, - /// U+0014 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - DeviceControlFour = 20, - /// U+0015 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - NegativeAcknowledge = 21, - /// U+0016 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SynchronousIdle = 22, - /// U+0017 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - EndOfTransmissionBlock = 23, - /// U+0018 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Cancel = 24, - /// U+0019 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - EndOfMedium = 25, - /// U+001A - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Substitute = 26, - /// U+001B - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Escape = 27, - /// U+001C - #[unstable(feature = "ascii_char_variants", issue = "110998")] - InformationSeparatorFour = 28, - /// U+001D - #[unstable(feature = "ascii_char_variants", issue = "110998")] - InformationSeparatorThree = 29, - /// U+001E - #[unstable(feature = "ascii_char_variants", issue = "110998")] - InformationSeparatorTwo = 30, - /// U+001F - #[unstable(feature = "ascii_char_variants", issue = "110998")] - InformationSeparatorOne = 31, - /// U+0020 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Space = 32, - /// U+0021 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - ExclamationMark = 33, - /// U+0022 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - QuotationMark = 34, - /// U+0023 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - NumberSign = 35, - /// U+0024 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - DollarSign = 36, - /// U+0025 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - PercentSign = 37, - /// U+0026 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Ampersand = 38, - /// U+0027 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Apostrophe = 39, - /// U+0028 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - LeftParenthesis = 40, - /// U+0029 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - RightParenthesis = 41, - /// U+002A - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Asterisk = 42, - /// U+002B - #[unstable(feature = "ascii_char_variants", issue = "110998")] - PlusSign = 43, - /// U+002C - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Comma = 44, - /// U+002D - #[unstable(feature = "ascii_char_variants", issue = "110998")] - HyphenMinus = 45, - /// U+002E - #[unstable(feature = "ascii_char_variants", issue = "110998")] - FullStop = 46, - /// U+002F - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Solidus = 47, - /// U+0030 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Digit0 = 48, - /// U+0031 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Digit1 = 49, - /// U+0032 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Digit2 = 50, - /// U+0033 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Digit3 = 51, - /// U+0034 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Digit4 = 52, - /// U+0035 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Digit5 = 53, - /// U+0036 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Digit6 = 54, - /// U+0037 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Digit7 = 55, - /// U+0038 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Digit8 = 56, - /// U+0039 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Digit9 = 57, - /// U+003A - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Colon = 58, - /// U+003B - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Semicolon = 59, - /// U+003C - #[unstable(feature = "ascii_char_variants", issue = "110998")] - LessThanSign = 60, - /// U+003D - #[unstable(feature = "ascii_char_variants", issue = "110998")] - EqualsSign = 61, - /// U+003E - #[unstable(feature = "ascii_char_variants", issue = "110998")] - GreaterThanSign = 62, - /// U+003F - #[unstable(feature = "ascii_char_variants", issue = "110998")] - QuestionMark = 63, - /// U+0040 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CommercialAt = 64, - /// U+0041 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalA = 65, - /// U+0042 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalB = 66, - /// U+0043 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalC = 67, - /// U+0044 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalD = 68, - /// U+0045 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalE = 69, - /// U+0046 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalF = 70, - /// U+0047 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalG = 71, - /// U+0048 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalH = 72, - /// U+0049 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalI = 73, - /// U+004A - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalJ = 74, - /// U+004B - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalK = 75, - /// U+004C - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalL = 76, - /// U+004D - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalM = 77, - /// U+004E - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalN = 78, - /// U+004F - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalO = 79, - /// U+0050 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalP = 80, - /// U+0051 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalQ = 81, - /// U+0052 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalR = 82, - /// U+0053 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalS = 83, - /// U+0054 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalT = 84, - /// U+0055 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalU = 85, - /// U+0056 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalV = 86, - /// U+0057 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalW = 87, - /// U+0058 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalX = 88, - /// U+0059 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalY = 89, - /// U+005A - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CapitalZ = 90, - /// U+005B - #[unstable(feature = "ascii_char_variants", issue = "110998")] - LeftSquareBracket = 91, - /// U+005C - #[unstable(feature = "ascii_char_variants", issue = "110998")] - ReverseSolidus = 92, - /// U+005D - #[unstable(feature = "ascii_char_variants", issue = "110998")] - RightSquareBracket = 93, - /// U+005E - #[unstable(feature = "ascii_char_variants", issue = "110998")] - CircumflexAccent = 94, - /// U+005F - #[unstable(feature = "ascii_char_variants", issue = "110998")] - LowLine = 95, - /// U+0060 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - GraveAccent = 96, - /// U+0061 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallA = 97, - /// U+0062 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallB = 98, - /// U+0063 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallC = 99, - /// U+0064 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallD = 100, - /// U+0065 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallE = 101, - /// U+0066 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallF = 102, - /// U+0067 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallG = 103, - /// U+0068 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallH = 104, - /// U+0069 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallI = 105, - /// U+006A - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallJ = 106, - /// U+006B - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallK = 107, - /// U+006C - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallL = 108, - /// U+006D - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallM = 109, - /// U+006E - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallN = 110, - /// U+006F - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallO = 111, - /// U+0070 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallP = 112, - /// U+0071 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallQ = 113, - /// U+0072 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallR = 114, - /// U+0073 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallS = 115, - /// U+0074 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallT = 116, - /// U+0075 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallU = 117, - /// U+0076 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallV = 118, - /// U+0077 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallW = 119, - /// U+0078 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallX = 120, - /// U+0079 - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallY = 121, - /// U+007A - #[unstable(feature = "ascii_char_variants", issue = "110998")] - SmallZ = 122, - /// U+007B - #[unstable(feature = "ascii_char_variants", issue = "110998")] - LeftCurlyBracket = 123, - /// U+007C - #[unstable(feature = "ascii_char_variants", issue = "110998")] - VerticalLine = 124, - /// U+007D - #[unstable(feature = "ascii_char_variants", issue = "110998")] - RightCurlyBracket = 125, - /// U+007E - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Tilde = 126, - /// U+007F - #[unstable(feature = "ascii_char_variants", issue = "110998")] - Delete = 127, -} - -impl AsciiChar { - /// Creates an ascii character from the byte `b`, - /// or returns `None` if it's too large. - #[unstable(feature = "ascii_char", issue = "110998")] - #[inline] - pub const fn from_u8(b: u8) -> Option { - if b <= 127 { - // SAFETY: Just checked that `b` is in-range - Some(unsafe { Self::from_u8_unchecked(b) }) - } else { - None - } - } - - /// Creates an ASCII character from the byte `b`, - /// without checking whether it's valid. - /// - /// # Safety - /// - /// `b` must be in `0..=127`, or else this is UB. - #[unstable(feature = "ascii_char", issue = "110998")] - #[inline] - pub const unsafe fn from_u8_unchecked(b: u8) -> Self { - // SAFETY: Our safety precondition is that `b` is in-range. - unsafe { transmute(b) } - } - - /// When passed the *number* `0`, `1`, …, `9`, returns the *character* - /// `'0'`, `'1'`, …, `'9'` respectively. - /// - /// If `d >= 10`, returns `None`. - #[unstable(feature = "ascii_char", issue = "110998")] - #[inline] - pub const fn digit(d: u8) -> Option { - if d < 10 { - // SAFETY: Just checked it's in-range. - Some(unsafe { Self::digit_unchecked(d) }) - } else { - None - } - } - - /// When passed the *number* `0`, `1`, …, `9`, returns the *character* - /// `'0'`, `'1'`, …, `'9'` respectively, without checking that it's in-range. - /// - /// # Safety - /// - /// This is immediate UB if called with `d > 64`. - /// - /// If `d >= 10` and `d <= 64`, this is allowed to return any value or panic. - /// Notably, it should not be expected to return hex digits, or any other - /// reasonable extension of the decimal digits. - /// - /// (This lose safety condition is intended to simplify soundness proofs - /// when writing code using this method, since the implementation doesn't - /// need something really specific, not to make those other arguments do - /// something useful. It might be tightened before stabilization.) - #[unstable(feature = "ascii_char", issue = "110998")] - #[inline] - pub const unsafe fn digit_unchecked(d: u8) -> Self { - debug_assert!(d < 10); - - // SAFETY: `'0'` through `'9'` are U+00030 through U+0039, - // so because `d` must be 64 or less the addition can return at most - // 112 (0x70), which doesn't overflow and is within the ASCII range. - unsafe { - let byte = b'0'.unchecked_add(d); - Self::from_u8_unchecked(byte) - } - } - - /// Gets this ASCII character as a byte. - #[unstable(feature = "ascii_char", issue = "110998")] - #[inline] - pub const fn to_u8(self) -> u8 { - self as u8 - } - - /// Gets this ASCII character as a `char` Unicode Scalar Value. - #[unstable(feature = "ascii_char", issue = "110998")] - #[inline] - pub const fn to_char(self) -> char { - self as u8 as char - } - - /// Views this ASCII character as a one-code-unit UTF-8 `str`. - #[unstable(feature = "ascii_char", issue = "110998")] - #[inline] - pub const fn as_str(&self) -> &str { - crate::slice::from_ref(self).as_str() - } -} - -macro_rules! into_int_impl { - ($($ty:ty)*) => { - $( - #[unstable(feature = "ascii_char", issue = "110998")] - impl From for $ty { - #[inline] - fn from(chr: AsciiChar) -> $ty { - chr as u8 as $ty - } - } - )* - } -} - -into_int_impl!(u8 u16 u32 u64 u128 char); - -impl [AsciiChar] { - /// Views this slice of ASCII characters as a UTF-8 `str`. - #[unstable(feature = "ascii_char", issue = "110998")] - #[inline] - pub const fn as_str(&self) -> &str { - let ascii_ptr: *const Self = self; - let str_ptr = ascii_ptr as *const str; - // SAFETY: Each ASCII codepoint in UTF-8 is encoded as one single-byte - // code unit having the same value as the ASCII byte. - unsafe { &*str_ptr } - } - - /// Views this slice of ASCII characters as a slice of `u8` bytes. - #[unstable(feature = "ascii_char", issue = "110998")] - #[inline] - pub const fn as_bytes(&self) -> &[u8] { - self.as_str().as_bytes() - } -} - -#[unstable(feature = "ascii_char", issue = "110998")] -impl fmt::Display for AsciiChar { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - ::fmt(self.as_str(), f) - } -} - -#[unstable(feature = "ascii_char", issue = "110998")] -impl fmt::Debug for AsciiChar { - fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { - #[inline] - fn backslash(a: AsciiChar) -> ([AsciiChar; 4], u8) { - ([AsciiChar::ReverseSolidus, a, AsciiChar::Null, AsciiChar::Null], 2) - } - - let (buf, len) = match self { - AsciiChar::Null => backslash(AsciiChar::Digit0), - AsciiChar::CharacterTabulation => backslash(AsciiChar::SmallT), - AsciiChar::CarriageReturn => backslash(AsciiChar::SmallR), - AsciiChar::LineFeed => backslash(AsciiChar::SmallN), - AsciiChar::ReverseSolidus => backslash(AsciiChar::ReverseSolidus), - AsciiChar::Apostrophe => backslash(AsciiChar::Apostrophe), - _ => { - let byte = self.to_u8(); - if !byte.is_ascii_control() { - ([*self, AsciiChar::Null, AsciiChar::Null, AsciiChar::Null], 1) - } else { - const HEX_DIGITS: [AsciiChar; 16] = *b"0123456789abcdef".as_ascii().unwrap(); - - let hi = HEX_DIGITS[usize::from(byte >> 4)]; - let lo = HEX_DIGITS[usize::from(byte & 0xf)]; - ([AsciiChar::ReverseSolidus, AsciiChar::SmallX, hi, lo], 4) - } - } - }; - - f.write_char('\'')?; - for byte in &buf[..len as usize] { - f.write_str(byte.as_str())?; - } - f.write_char('\'') - } -} diff --git a/library/core/src/asserting.rs b/library/core/src/asserting.rs deleted file mode 100644 index 212b637d34365..0000000000000 --- a/library/core/src/asserting.rs +++ /dev/null @@ -1,109 +0,0 @@ -// Contains the machinery necessary to print useful `assert!` messages. Not intended for public -// usage, not even nightly use-cases. -// -// Based on https://github.com/dtolnay/case-studies/tree/master/autoref-specialization. When -// 'specialization' is robust enough (5 years? 10 years? Never?), `Capture` can be specialized -// to [Printable]. - -#![allow(missing_debug_implementations)] -#![doc(hidden)] -#![unstable(feature = "generic_assert_internals", issue = "44838")] - -use crate::{ - fmt::{Debug, Formatter}, - marker::PhantomData, -}; - -// ***** TryCapture - Generic ***** - -/// Marker used by [Capture] -#[unstable(feature = "generic_assert_internals", issue = "44838")] -pub struct TryCaptureWithoutDebug; - -/// Catches an arbitrary `E` and modifies `to` accordingly -#[unstable(feature = "generic_assert_internals", issue = "44838")] -pub trait TryCaptureGeneric { - /// Similar to [TryCapturePrintable] but generic to any `E`. - fn try_capture(&self, to: &mut Capture); -} - -impl TryCaptureGeneric for &Wrapper<&E> { - #[inline] - fn try_capture(&self, _: &mut Capture) {} -} - -impl Debug for Capture { - fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), core::fmt::Error> { - f.write_str("N/A") - } -} - -// ***** TryCapture - Printable ***** - -/// Marker used by [Capture] -#[unstable(feature = "generic_assert_internals", issue = "44838")] -pub struct TryCaptureWithDebug; - -/// Catches an arbitrary `E: Printable` and modifies `to` accordingly -#[unstable(feature = "generic_assert_internals", issue = "44838")] -pub trait TryCapturePrintable { - /// Similar as [TryCaptureGeneric] but specialized to any `E: Printable`. - fn try_capture(&self, to: &mut Capture); -} - -impl TryCapturePrintable for Wrapper<&E> -where - E: Printable, -{ - #[inline] - fn try_capture(&self, to: &mut Capture) { - to.elem = Some(*self.0); - } -} - -impl Debug for Capture -where - E: Printable, -{ - fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), core::fmt::Error> { - match self.elem { - None => f.write_str("N/A"), - Some(ref value) => Debug::fmt(value, f), - } - } -} - -// ***** Others ***** - -/// All possible captured `assert!` elements -/// -/// # Types -/// -/// * `E`: **E**lement that is going to be displayed. -/// * `M`: **M**arker used to differentiate [Capture]s in regards to [Debug]. -#[unstable(feature = "generic_assert_internals", issue = "44838")] -pub struct Capture { - // If None, then `E` does not implements [Printable] or `E` wasn't evaluated (`assert!( ... )` - // short-circuited). - // - // If Some, then `E` implements [Printable] and was evaluated. - pub elem: Option, - phantom: PhantomData, -} - -impl Capture { - #[inline] - pub const fn new() -> Self { - Self { elem: None, phantom: PhantomData } - } -} - -/// Necessary for the implementations of `TryCapture*` -#[unstable(feature = "generic_assert_internals", issue = "44838")] -pub struct Wrapper(pub T); - -/// Tells which elements can be copied and displayed -#[unstable(feature = "generic_assert_internals", issue = "44838")] -pub trait Printable: Copy + Debug {} - -impl Printable for T where T: Copy + Debug {} diff --git a/library/core/src/async_iter/async_iter.rs b/library/core/src/async_iter/async_iter.rs deleted file mode 100644 index a0ffb6d47507b..0000000000000 --- a/library/core/src/async_iter/async_iter.rs +++ /dev/null @@ -1,163 +0,0 @@ -use crate::ops::DerefMut; -use crate::pin::Pin; -use crate::task::{Context, Poll}; - -/// A trait for dealing with asynchronous iterators. -/// -/// This is the main async iterator trait. For more about the concept of async iterators -/// generally, please see the [module-level documentation]. In particular, you -/// may want to know how to [implement `AsyncIterator`][impl]. -/// -/// [module-level documentation]: index.html -/// [impl]: index.html#implementing-async-iterator -#[unstable(feature = "async_iterator", issue = "79024")] -#[must_use = "async iterators do nothing unless polled"] -#[doc(alias = "Stream")] -#[lang = "async_iterator"] -pub trait AsyncIterator { - /// The type of items yielded by the async iterator. - type Item; - - /// Attempt to pull out the next value of this async iterator, registering the - /// current task for wakeup if the value is not yet available, and returning - /// `None` if the async iterator is exhausted. - /// - /// # Return value - /// - /// There are several possible return values, each indicating a distinct - /// async iterator state: - /// - /// - `Poll::Pending` means that this async iterator's next value is not ready - /// yet. Implementations will ensure that the current task will be notified - /// when the next value may be ready. - /// - /// - `Poll::Ready(Some(val))` means that the async iterator has successfully - /// produced a value, `val`, and may produce further values on subsequent - /// `poll_next` calls. - /// - /// - `Poll::Ready(None)` means that the async iterator has terminated, and - /// `poll_next` should not be invoked again. - /// - /// # Panics - /// - /// Once an async iterator has finished (returned `Ready(None)` from `poll_next`), calling its - /// `poll_next` method again may panic, block forever, or cause other kinds of - /// problems; the `AsyncIterator` trait places no requirements on the effects of - /// such a call. However, as the `poll_next` method is not marked `unsafe`, - /// Rust's usual rules apply: calls must never cause undefined behavior - /// (memory corruption, incorrect use of `unsafe` functions, or the like), - /// regardless of the async iterator's state. - #[lang = "async_iterator_poll_next"] - fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll>; - - /// Returns the bounds on the remaining length of the async iterator. - /// - /// Specifically, `size_hint()` returns a tuple where the first element - /// is the lower bound, and the second element is the upper bound. - /// - /// The second half of the tuple that is returned is an [Option]<[usize]>. - /// A [`None`] here means that either there is no known upper bound, or the - /// upper bound is larger than [`usize`]. - /// - /// # Implementation notes - /// - /// It is not enforced that an async iterator implementation yields the declared - /// number of elements. A buggy async iterator may yield less than the lower bound - /// or more than the upper bound of elements. - /// - /// `size_hint()` is primarily intended to be used for optimizations such as - /// reserving space for the elements of the async iterator, but must not be - /// trusted to e.g., omit bounds checks in unsafe code. An incorrect - /// implementation of `size_hint()` should not lead to memory safety - /// violations. - /// - /// That said, the implementation should provide a correct estimation, - /// because otherwise it would be a violation of the trait's protocol. - /// - /// The default implementation returns (0, [None]) which is correct for any - /// async iterator. - #[inline] - fn size_hint(&self) -> (usize, Option) { - (0, None) - } -} - -#[unstable(feature = "async_iterator", issue = "79024")] -impl AsyncIterator for &mut S { - type Item = S::Item; - - fn poll_next(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll> { - S::poll_next(Pin::new(&mut **self), cx) - } - - fn size_hint(&self) -> (usize, Option) { - (**self).size_hint() - } -} - -#[unstable(feature = "async_iterator", issue = "79024")] -impl